@acronis-platform/ui-react 3.0.0 → 4.0.0

package/dist/llms/app-shell-chat.md

@@ -0,0 +1,415 @@
+# AppShellChat
+
+> A 3-section, horizontally resizable application scaffold: a sidebar rail (SidebarPrimary, optionally SidebarSecondary) beside a Content page column and a Chat panel. Content and Chat resize against each other by dragging Chat's start border; the sidebars resize Content only (Chat keeps its explicit pixel width). Chat is resize-only: dragging down to its floor width shows an icon-only rail, and dragging up can take it to full width (Content shrinks to 0) since the resize ceiling is measured from the actual available row space. The Chat slot is optional, so the same scaffold also serves an ordinary two-column console screen.
+
+**Status:** ready · **Category:** layout · **Since:** v0.57.0
+
+## Import
+
+```tsx
+import { AppShellChat, AppShellChatSidebar, AppShellChatContent, AppShellChatContentHeader, AppShellChatContentBody, AppShellChatChat, AppShellChatChatHeader, AppShellChatChatBody, useAppShellChatInitialLayout } from '@acronis-platform/ui-react'
+```
+
+## Quick example
+
+```tsx
+// useAppShellChatInitialLayout() resolves ONCE at mount from the
+// viewport width — wire it into the sidebars' `defaultExpanded`,
+// since AppShellChatSidebar is a plain slot, not a fixed pairing
+// AppShellChat owns. Chat's own responsive width needs no wiring.
+const initialLayout = useAppShellChatInitialLayout();
+
+<AppShellChat>
+  <AppShellChatSidebar>
+    <SidebarPrimary defaultExpanded={initialLayout.primaryExpanded}>…</SidebarPrimary>
+    <SidebarSecondary defaultExpanded={initialLayout.secondaryExpanded}>…</SidebarSecondary>
+  </AppShellChatSidebar>
+  <AppShellChatContent>
+    <AppShellChatContentHeader>Page header</AppShellChatContentHeader>
+    <AppShellChatContentBody>{children}</AppShellChatContentBody>
+  </AppShellChatContent>
+  <AppShellChatChat>
+    <AppShellChatChatHeader label="Acronis AI" />
+    <AppShellChatChatBody>{chat}</AppShellChatChatBody>
+  </AppShellChatChat>
+</AppShellChat>
+```
+
+A 3-section, horizontally resizable application scaffold: a sidebar rail beside a
+Content page column and a Chat panel. Content and Chat resize against each other;
+Chat is resize-only — drag it down to an icon-only rail or up to full width. The
+Chat slot is optional, so the same scaffold also serves an ordinary two-column
+console screen.
+
+## When to Use
+
+- A product screen that pairs the main page content with a persistent,
+  resizable chat / assistant panel (e.g. "Acronis AI").
+- When the chat must be freely resizable — including down to an icon-only rail
+  or up to full width — without disturbing the navigation sidebars.
+
+## When NOT to Use
+
+- A transient chat overlay — use a Sheet or Popover.
+- Content that should resize proportionally in percentages — use **Resizable**
+  (this component deliberately uses fixed pixel sizing so sidebar changes never
+  resize the chat).
+
+## Parts
+
+| Part                        | Element   | Role                                                              |
+| --------------------------- | --------- | ----------------------------------------------------------------- |
+| `AppShellChat`              | `<div>`   | Root                                                              |
+| `AppShellChatSidebar`       | `<aside>` | Rail slot for SidebarPrimary (+ SidebarSecondary)                 |
+| `AppShellChatContent`       | `<div>`   | Page column (`flex-1`); can shrink to 0, never unmounts           |
+| `AppShellChatContentHeader` | `<div>`   | Page header row (bottom divider)                                  |
+| `AppShellChatContentBody`   | `<div>`   | Scrolling page body                                               |
+| `AppShellChatChat`          | `<aside>` | Resizable chat panel                                              |
+| `AppShellChatChatHeader`    | `<div>`   | Chat header (title + actions, or icon-only rail at the min width) |
+| `AppShellChatChatBody`      | `<div>`   | Scrolling chat body (hidden at the min width)                     |
+
+The resize edge is rendered automatically inside `AppShellChatChat` and is not a
+public part.
+
+## Quick Example
+
+### React
+
+```tsx
+import {
+  AppShellChat,
+  AppShellChatSidebar,
+  AppShellChatContent,
+  AppShellChatContentHeader,
+  AppShellChatContentBody,
+  AppShellChatChat,
+  AppShellChatChatHeader,
+  AppShellChatChatBody,
+  useAppShellChatInitialLayout,
+  SidebarPrimary,
+  SidebarSecondary,
+} from '@acronis-platform/ui-react';
+
+function Screen() {
+  // Resolves ONCE at mount from the viewport width — see "Responsive
+  // layout" below. AppShellChatSidebar is a plain slot (not a fixed
+  // SidebarPrimary+SidebarSecondary pairing it owns), so wiring the result
+  // into each sidebar's `defaultExpanded` is the consumer's job.
+  const initialLayout = useAppShellChatInitialLayout();
+
+  return (
+    <AppShellChat className="h-screen">
+      <AppShellChatSidebar>
+        <SidebarPrimary defaultExpanded={initialLayout.primaryExpanded}>
+          {/* … */}
+        </SidebarPrimary>
+        <SidebarSecondary defaultExpanded={initialLayout.secondaryExpanded}>
+          {/* … */}
+        </SidebarSecondary>
+      </AppShellChatSidebar>
+      <AppShellChatContent>
+        <AppShellChatContentHeader>Page header</AppShellChatContentHeader>
+        <AppShellChatContentBody>{/* page */}</AppShellChatContentBody>
+      </AppShellChatContent>
+      <AppShellChatChat>
+        <AppShellChatChatHeader label="Acronis AI" />
+        <AppShellChatChatBody>{/* chat */}</AppShellChatChatBody>
+      </AppShellChatChat>
+    </AppShellChat>
+  );
+}
+```
+
+## Sizing model
+
+Content is `flex-1 min-w-0`; Chat has an explicit pixel width (responsive by
+default, or an inline override once the user drags/keyboard-resizes it — see
+**Responsive layout** below). Because Chat never uses percentages and the
+sidebars sit outside any resizable group, expanding / collapsing / resizing a
+sidebar only reflows Content — Chat keeps its width. Chat's own resize range
+runs from a 48px floor (icon-only rail) up to the row's actual available
+width, so dragging it far enough shrinks Content to 0 and Chat alone fills
+the row — there is no separate full-width toggle.
+
+## Responsive layout
+
+Chat's width and the sidebars' initial expanded state both key off the same
+breakpoints (`src/lib/breakpoints.ts` — 1280px / 1680px), but with
+deliberately different lifetimes:
+
+- **Chat's width is LIVE** — plain responsive CSS, no wiring required. It
+  reflows on every browser resize (512px at 1680px+, 448px from
+  1280-1679px, the 48px icon-rail floor below 1280px) until the user drags
+  or keyboard-resizes it, at which point that explicit choice wins until
+  double-click/Home resets it.
+- **The sidebars' initial layout is frozen at mount** — resolved once from
+  `useAppShellChatInitialLayout()` (exported alongside `AppShellChat`) and
+  wired into `SidebarPrimary`/`SidebarSecondary`'s `defaultExpanded` prop
+  (see the Quick Example above). At 1680px+ both sidebars start expanded;
+  below that, `SidebarPrimary` starts collapsed while `SidebarSecondary`
+  stays expanded. A later viewport resize, or the user manually toggling a
+  sidebar, never re-derives this — sidebars own real collapse/expand
+  controls, so their state shouldn't fight a live viewport change the way
+  Chat's plain width safely can.
+
+See `behavior.md`'s **Responsive layout** section for the full Given/When/Then
+scenarios.
+
+## Spec Files
+
+| File               | Contents                                                          |
+| ------------------ | ----------------------------------------------------------------- |
+| `index.yaml`       | Identity, status, category, dependencies, Figma link              |
+| `anatomy.yaml`     | Root, parts, layout, states                                       |
+| `api.yaml`         | Framework-agnostic contract + framework adapters                  |
+| `tokens.yaml`      | Shared `--ui-*` token references (no component-specific tokens)   |
+| `behavior.md`      | Given/When/Then behavior scenarios                                |
+| `accessibility.md` | ARIA roles, keyboard map, screen-reader and contrast requirements |
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `width` | `number` | `undefined` | no | Controlled Chat width in px. When uncontrolled (the default), Chat's width is instead LIVE and breakpoint-responsive — 512px at 1680px+, 448px from 1280-1679px, 48px below that — reflowing on every browser resize until the user drags/keyboard-resizes it. Any explicit width (controlled, or a drag/keyboard override) is clamped during resize to [48, available] — the ceiling is the actual available row width (so Content can shrink to 0 and Chat can reach full width), not a fixed constant. |
+| `resizeAriaLabel` | `string` | `'Resize chat'` | no | Accessible label for the Chat resize edge (`role="separator"`). Consumers should localize this string for i18n. |
+| `resizeTooltip` | `ReactNode` | `(English tooltip: Resize/Reset)` | no | Tooltip content shown on the resize edge. Pass `null` to hide the tooltip entirely. Localize for i18n. |
+| `label` | `ReactNode` | `undefined` | no | Chat header title (or pass as children). Also serves as the icon-only rail's hover tooltip and (when a string) the Acronis mark's accessible name. |
+| `actions` | `ReactNode` | `undefined` | no | Trailing chat-header actions. Hidden while the chat is at its min width (icon-only rail). |
+
+## Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `width-change` | `number` | Fires when the Chat width changes via drag/keyboard. React: `onWidthChange` on AppShellChatChat. |
+
+## Content slots
+
+| Slot | Description |
+|------|-------------|
+| `default` | The composed scaffold. Author it from the parts: a sidebar rail slot, a Content column (header + body), and a Chat panel (header + body). The resize edge is rendered automatically inside the Chat panel. |
+
+## Behavior
+
+### Structure
+
+#### Renders three logical sections
+
+**Given** an AppShellChat wrapping a sidebar rail, a Content column, and a Chat panel
+**When** the component renders
+**Then** the sections lay out left→right as sidebar → Content → Chat
+**And** in `dir="rtl"` they mirror to right→left via CSS logical properties (no JS branch)
+**And** Content is `flex-1 min-w-0` while Chat has an explicit pixel width
+
+---
+
+### Sizing independence
+
+#### Sidebar interactions never resize Chat
+
+**Given** a Chat panel with a fixed/overridden width
+**When** either sidebar expands, collapses, or is resized
+**Then** only Content's width changes (it absorbs the delta)
+**And** Chat's width is unchanged
+
+> This falls out of the layout: Content is the only flex-growing item, and Chat's
+> width is an explicit pixel value (never a percentage), so the sidebars — flex
+> siblings outside any resizable group — cannot alter it.
+
+---
+
+### Content ↔ Chat resize
+
+#### Drag resizes Chat against Content, down to the min width
+
+**Given** a Chat panel
+**When** the user drags the resize edge on Chat's start border toward the row's end
+**Then** Chat's width tracks the pointer, down to a floor of 48px
+**And** Content reflows to fill the remaining width
+**And** the Content/Chat seam recolors on hover / drag / focus
+**And** there is no collapse threshold or toggle — the drag simply stops at the floor
+
+#### Drag resizes Chat up to full width
+
+**Given** a Chat panel and its sibling Content column
+**When** the user drags the resize edge toward the row's start
+**Then** Chat's width grows and Content shrinks, down to 0 width if dragged far enough
+**And** the resize ceiling is the row's actual available width at drag start (row
+width minus the sidebar rail), not a fixed constant — so Chat can reach full
+width whenever the row has the room (e.g. both sidebars collapsed), and is
+otherwise bounded by whatever space is actually free
+
+#### Double-click and keyboard
+
+**Given** the resize edge
+**When** the user double-clicks it
+**Then** the width resets to the current LIVE breakpoint-driven default
+(512px at 1680px+; see **Responsive layout** below) — NOT a fixed 512px
+regardless of viewport
+**And** ArrowLeft/ArrowRight resize by 16px (inverted in RTL), clamped to
+[48px, the same dynamically-measured ceiling used by drag]
+**And** Home resets the width the same way double-click does
+
+---
+
+### Icon-only rail at the min width
+
+#### Header and body adapt at 48px
+
+**Given** the Chat panel's width is at its 48px floor
+**When** it renders
+**Then** the panel has `data-state="collapsed"`
+**And** the header shows only the Acronis mark, sized to match the header's
+height at any other width; the full label appears on hover
+**And** the chat body is hidden (`hidden`)
+**And** any header `actions` are hidden
+
+**Given** the Chat panel's width is above the 48px floor
+**When** it renders
+**Then** the panel has `data-state="expanded"`
+**And** the header shows the title + any `actions`; the body is visible
+
+---
+
+### Responsive layout
+
+#### Chat's width is breakpoint-responsive, and stays LIVE until the user resizes it
+
+**Given** an uncontrolled Chat panel that the user has not yet dragged or
+keyboard-resized
+**When** the viewport width crosses 1280px or 1680px (the `xl`/`3xl` steps
+pinned in `src/styles/index.css` and mirrored in `src/lib/breakpoints.ts`)
+**Then** Chat's width reflows immediately, with no page reload or remount:
+48px (icon-only rail) below 1280px, 448px from 1280px up to 1680px, 512px at
+1680px and up
+**And** this reflow keeps happening on every subsequent browser resize —
+it is NOT a one-time initial measurement
+
+**Given** the user has dragged the resize handle, nudged it with the arrow
+keys, or the `width` prop is controlled
+**When** the viewport is resized afterward
+**Then** Chat's width no longer reflows — the explicit value (drag/keyboard
+override, or the controlled `width`) wins until double-click/Home resets it
+back to the live breakpoint-driven value
+
+> Unlike the sidebars below, Chat's responsive width needs no wiring from the
+> consumer — it's implemented as plain CSS (`w-12 xl:w-md 3xl:w-lg` on the
+> Chat panel), not a hook. There is no design token for these three widths
+> (a pure layout composition), so the pixel values live only as JS constants
+> in `app-shell-chat.tsx` mirroring the Tailwind classes.
+
+#### The sidebars' initial layout is breakpoint-derived, but frozen at mount
+
+**Given** a screen that renders `SidebarPrimary` (+ optionally
+`SidebarSecondary`) inside `AppShellChatSidebar`, wiring
+`useAppShellChatInitialLayout()`'s `primaryExpanded`/`secondaryExpanded`
+fields into each sidebar's `defaultExpanded` prop
+**When** the screen first mounts
+**Then** at 1680px and up, `SidebarPrimary` starts expanded and
+`SidebarSecondary` (if present) starts expanded
+**And** below 1680px, `SidebarPrimary` starts collapsed while
+`SidebarSecondary` (if present) still starts expanded
+
+**Given** a screen already mounted with that initial layout applied
+**When** the viewport is resized, or the user manually expands/collapses a
+sidebar
+**Then** the sidebars' state is NEVER re-derived from the viewport again —
+`useAppShellChatInitialLayout` reads `window.innerWidth` exactly once, at
+first render, because `defaultExpanded` is itself a one-shot value on the
+sidebar components (a later prop change is silently ignored); re-deriving it
+live would fight the user's own sidebar toggle on every resize
+
+> This is the opposite tradeoff from Chat's width, and deliberately so: Chat
+> is a pure visual size with no independent "user already chose something"
+> state to protect, so it can safely stay live forever. A sidebar's
+> expanded/collapsed state IS that kind of state (the user's own toggle), so
+> only the very first paint is allowed to be breakpoint-aware.
+
+---
+
+### Controlled / uncontrolled
+
+#### Width supports either mode
+
+**Given** `width` (controlled) or the uncontrolled, breakpoint-responsive
+default (see **Responsive layout** above)
+**When** the resize edge is dragged or operated via keyboard
+**Then** uncontrolled state updates internally, controlled state is owned by the consumer
+**And** `onWidthChange` always fires with the next value
+
+## Accessibility
+
+A layout scaffold. It contributes little ARIA of its own — the rich landmarks
+(`nav`) come from the SidebarPrimary / SidebarSecondary dropped into its rail
+slot. Its own interactive part is the Chat resize edge.
+
+## ARIA Roles and Attributes
+
+### Root (`div`)
+
+| Attribute   | Value            | Reason               |
+| ----------- | ---------------- | -------------------- |
+| `data-slot` | `app-shell-chat` | Styling / query hook |
+
+### Sidebar / Content / Chat regions
+
+`<aside>` for the sidebar rail and the Chat panel; `<div>` for the Content
+column. Consumers may add `aria-label` to the Chat `<aside>` to name the region.
+
+### Resize edge (`role="separator"`)
+
+| Attribute          | Value             | Reason                                    |
+| ------------------ | ----------------- | ----------------------------------------- |
+| `role`             | `separator`       | Exposes the draggable boundary            |
+| `aria-orientation` | `vertical`        | The boundary is vertical                  |
+| `aria-label`       | `resizeAriaLabel` | Names the control (default "Resize chat") |
+| `tabindex`         | `0`               | Keyboard-focusable for arrow-key resize   |
+
+### Chat header (at the min width)
+
+At the 48px floor, the header shows only the Acronis mark. The mark carries an
+accessible name (from the string `label`) and the full label is shown on hover
+via a tooltip; no visible text is rendered in the rail.
+
+---
+
+## Keyboard Navigation
+
+| Key               | Element     | Action                                 |
+| ----------------- | ----------- | -------------------------------------- |
+| Tab / Shift+Tab   | any         | Moves focus between interactive parts  |
+| ArrowLeft / Right | resize edge | Resizes Chat by 16px (inverted in RTL) |
+| Home              | resize edge | Resets Chat width to 512px             |
+
+Arrow-key directions are logical: growing Chat moves the boundary toward the
+row's start, so the grow key is ArrowLeft in LTR and ArrowRight in RTL. There is
+no Enter/Space action — the resize edge has no toggle, only resize.
+
+---
+
+## Focus
+
+The resize edge shows a focus ring using `--ui-focus-primary`, visible against
+the panel surface.
+
+---
+
+## Color and Contrast
+
+| Element                          | Minimum Ratio | Standard               |
+| -------------------------------- | ------------- | ---------------------- |
+| Chat header title vs surface     | 4.5:1         | WCAG 1.4.3 (AA)        |
+| Content/Chat seam (resize state) | 3:1           | WCAG 1.4.11 (non-text) |
+| Focus indicators                 | 3:1           | WCAG 1.4.11            |
+
+---
+
+## Testing Checklist
+
+- [ ] Content is always present and can shrink to 0 width; it is never unmounted
+- [ ] The resize edge is a `separator` with a name
+- [ ] Dragging or using arrows/Home on the resize edge resizes Chat between its
+      48px floor and the actual available row width (no fixed cap strands
+      Content with a bogus minimum)
+- [ ] Chat header at the 48px floor keeps an accessible name (icon) and hides
+      the body; both header states share the same height
+- [ ] Works in `dir="ltr"` and `dir="rtl"` (logical properties)