# 01 - Chat Bubble & Panel UI Architecture

This document explains the UI layout and state management for the floating Chat Bubble and Chat Panel UI shell built in **Milestone 1.5**.

---

## 1. UI Components Overview

The widget consists of two primary UI elements rendered inside the Shadow DOM:

1. **Floating Chat Bubble Button (`.chat-bubble-btn`):**
   - Fixed position at bottom-right (`bottom: 20px; right: 20px; z-index: 999999;`).
   - Circular button containing an SVG chat icon.
   - Accessible via keyboard and `aria-label="Open Chat Window"`.

2. **Chat Panel UI Shell (`.chat-panel`):**
   - Fixed position above the bubble (`bottom: 90px; right: 20px; width: 360px; height: 500px;`).
   - Contains:
     - **Header:** Title ("Support Chat"), Subtitle, and Close button (`×`).
     - **Body:** Message container displaying initial welcome message.
     - **Footer:** Visual input area and send button.

---

## 2. Open / Close State Interaction Logic

State is managed via a simple boolean flag `isOpen` inside `src/widget.js`:

```javascript
let isOpen = false;

function toggleChat() {
  isOpen = !isOpen;
  if (isOpen) {
    panel.classList.remove("hidden");
    bubbleBtn.setAttribute("aria-label", "Close Chat Window");
    closeBtn.focus();
  } else {
    panel.classList.add("hidden");
    bubbleBtn.setAttribute("aria-label", "Open Chat Window");
    bubbleBtn.focus();
  }
}
```

### Event Flow:
- Page loads $\rightarrow$ `panel` has class `.hidden` (`display: none`), `bubbleBtn` is visible.
- User clicks `bubbleBtn` $\rightarrow$ `toggleChat()` runs, removes `.hidden` class, panel opens, close button receives focus.
- User clicks `closeBtn` or `bubbleBtn` again $\rightarrow$ `toggleChat()` runs, adds `.hidden` class, panel closes, bubble button receives focus.

---

## 3. Why the UI Lives Exclusively Inside Shadow DOM

All HTML markup and CSS rules are attached to `shadow` root (`host.attachShadow({ mode: "open" })`).

- Host page CSS rules (like global `div` or `button` styles) cannot leak in to distort the bubble button or chat panel.
- Widget styles (like `.chat-panel` or `.chat-bubble-btn`) cannot leak out to corrupt host page layouts.

---

## 4. What is Intentionally Deferred (Not Implemented Yet)

- Reading `data-site-id` from script tag (Milestone 1.6).
- Initializing session via `/session/init` API (Milestone 1.7).
- Storing `sessionId` in `localStorage` (Milestone 1.8).
- Enabling chat input / sending messages to `/message` (Milestone 1.9).