@agentman/chat-widget/docs/input-bar-full-sheet.md

Agentman Chat Widget for easy integration with web applications

# Input Bar Full Sheet Design

## Purpose & Objectives
- Deliver a Daydream-style bottom sheet that keeps the composer always on-screen while exposing the full chat when needed.
- Maintain parity with the primary conversation renderer so cards, streaming responses, and attachments behave identically.
- Provide a high-visibility mobile-first entry point that feels native to modern AI search experiences.

## User Experience Summary
- **Collapsed default:** A 72px, edge-to-edge input bar anchored to the viewport bottom (68px on narrow screens). Headers, prompts, and branding remain hidden in this state.
- **Expand trigger:** Focusing the composer, selecting a prompt, or calling `emitToggleEvent` promotes the widget to a sheet (80vh desktop / 95vh mobile) and locks background scroll.
- **Welcome state:** If no conversation history exists, the sheet opens to the slim welcome hero and prompt chips rendered inside the sheet body.
- **Conversation state:** After the first message, the sheet body transitions to the standard conversation view (messages list, attachments, streaming, orchestrator interactions).
- **Collapse triggers:** The floating ✕ button, backdrop click/tap, ESC key, or programmatic blur return the widget to the 72px bar and release the body scroll lock.

## Key Design Principles
- **Single composer:** The InputComponent is reused across all states, eliminating perceived jumps between welcome and conversation views.
- **Shared renderer:** All message rendering flows through the existing ConversationView so there is zero divergence in payload support.
- **State symmetry:** The sheet simply wraps the canonical welcome/conversation states; no new persistence or orchestration pathways are introduced.
- **Safe area aware:** Collapsed and expanded layouts respect `env(safe-area-inset-bottom)` to avoid overlapping the iOS home indicator.

## Architecture Overview
1. **Mode detection:** `ChatWidget` sets `isInputBarFullMode` when `agentClosedView === 'input-bar-sheet'` and forces `state.isOpen = true`.
2. **Sheet scaffold:** `initializeInputBarFullModeUI()` injects the backdrop, collapse control, and focus listeners. Collapsed/expanded states are tracked via the root element classes `am-sheet-collapsed` and `am-sheet-expanded`.
3. **Expansion logic:** Focus on `.am-input-textarea` or `.am-chat-input-textarea` calls `expandInputBarFullSheet()`, which adds the expanded class, locks body scroll via `am-no-scroll`, and defers to ViewManager for input focus.
4. **Collapse logic:** Backdrop clicks, ESC key, or focus leaving the widget call `collapseInputBarFullSheet()`, clearing the expanded class and body scroll lock.
5. **Floating prompts bypass:** `showFloatingPrompts()` exits early in sheet mode, ensuring the collapsed experience is exclusively owned by the composer bar.
6. **Toggle behavior:** `emitToggleEvent()` toggles the sheet instead of opening/closing the widget container.

## Styling Strategy
- New rules in `input-bar-sheet-mode.ts` handle both collapsed and expanded states, providing glassmorphism, shadowing, and transitions without affecting other variants.
- Collapsed state hides `.am-welcome-*`, headers, messages, and branding, while the composer retains padding and animation.
- Expanded state re-enables the hidden elements and introduces a dimmed backdrop; the backdrop is fully disabled while collapsed.
- Dark-mode adjustments reuse the same color system as the base widget for consistency.

## Accessibility Notes
- Backdrop and sheet are mutually exclusive: the backdrop has `pointer-events: none` while collapsed, preventing accidental focus trapping.
- ESC support mirrors modal dialogs; focus is returned to the collapsed composer after closing.
- Screen readers see an always-available textbox with ARIA labels provided by the existing InputComponent. The welcome and conversation content remain accessible because DOM order is unchanged.

## Testing Approach
1. **Manual smoke:** Use `test-input-bar-sheet.html` to confirm collapsed and expanded visuals, scroll locking, prompt interactions, and ESC behavior across desktop and mobile viewports.
2. **Conversation parity:** Send streaming responses, markdown messages, and attachment uploads to ensure message rendering matches the standard widget.
3. **Focus flows:** Tab through the sheet to guarantee focus cycles header → messages → composer and back without escaping the overlay (except via intentional collapse).
4. **Persistence reload:** With persistence enabled, reload the page to verify the sheet opens directly into the conversation state when history exists.

## Future Enhancements
- Add Playwright coverage for expansion/collapse flows and scroll locking assertions to catch regressions automatically.
- Provide theming knobs dedicated to sheet mode (header background, backdrop opacity, collapsed bar elevation).
- Investigate lazy-mounting the conversation view to reduce initial payload when the sheet has never been expanded.
- Consider exposing APIs for developers to open/close the sheet programmatically without simulating focus events.

## Success Metrics
- **Adoption:** Percentage of customers selecting `input-bar-sheet` when releasing the mode.
- **Engagement:** Increase in first-message send rate compared to toggle-only deployments on mobile.
- **Latency perception:** Qualitative feedback on perceived responsiveness thanks to the always-visible composer.