@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482

package/src/stories/.CheckboxBlock.stories.md

@@ -1,59 +1,58 @@
-<!-- source-hash: d29f5d2cc4bf17eb228a4dc4aebe30a3 -->
-Storybook stories for the `CheckboxBlock` UI component, covering all interactive states, variants, and theme configurations for visual testing and documentation.
+<!-- source-hash: 4b530add022047c28303f0a957f8927e -->
+Storybook stories for the `CheckboxBlock` UI component, covering all interactive states, variants, and theming options for visual testing and documentation.
 
 ## Key Components
 
-### Stories Exported
+### Stories
 
 | Story | Description |
 |---|---|
-| `Default` | Unchecked checkbox block baseline |
-| `Checked` / `Disabled` / `DisabledChecked` | State variants |
-| `Controlled` | Stateful example using `useState` with live feedback |
-| `WithDescription` | Taller `h-16` variant with secondary description text |
-| `Error` / `FlamingoError` | Red border validation failure state |
-| `FlamingoChecked` | Pink accent theme via `data-app-type="flamingo"` wrapper |
-| `AllVariants` | Side-by-side comparison of all variants |
+| `Default` | Unchecked checkbox block with basic label |
+| `RepeatScriptRun` | Matches the Figma design reference label |
+| `Checked` | Pre-checked via `defaultChecked` |
+| `Disabled` / `DisabledChecked` | Non-interactive disabled states |
+| `Controlled` | Fully controlled with `useState`, displays live checked value |
+| `LongLabel` | Demonstrates text wrapping behavior |
+| `WithDescription` | Two-line variant (`label` + `description`) |
+| `WithTrailingAction` | Appends a `Button` via the `trailing` prop; uses `e.preventDefault()` to prevent label toggle |
+| `Error` | Red border validation failure state |
+| `FlamingoError` / `FlamingoChecked` | Pink accent theme via `data-app-type="flamingo"` |
+| `AllVariants` | Side-by-side comparison of all states |
 
 ### Configured `argTypes`
 
-- `label` — checkbox label text
+- `label` — primary checkbox label text
 - `checked` / `defaultChecked` — controlled vs. uncontrolled state
-- `description` — optional secondary text below label
+- `description` — optional secondary text (renders taller `h-16` variant)
 - `disabled` — disables interaction
-- `onCheckedChange` — action callback on state change
+- `onCheckedChange` — change callback (Storybook action logged)
 
 ## Usage Example
 
 ```typescript
-import { CheckboxBlock } from '../components/ui/checkbox-block';
-
-// Uncontrolled
-<CheckboxBlock label="Repeat Script Run" defaultChecked />
-
-// With description
+// Controlled usage with trailing action
 <CheckboxBlock
-  label="Run as User"
-  description="Windows Only"
-  disabled
-/>
-
-// Controlled
-const [checked, setChecked] = useState(false);
-<CheckboxBlock
-  label="Controlled Checkbox"
+  label="Use the default guardrails settings"
+  description="This customer follows guardrails defaults."
   checked={checked}
   onCheckedChange={setChecked}
+  trailing={
+    <Button variant="outline" onClick={e => e.preventDefault()}>
+      Edit Default Guardrails
+    </Button>
+  }
 />
 
 // Error state
 <CheckboxBlock
-  label="Accept terms"
-  error="Please accept to continue."
+  label="Send me an SMS"
+  description="Msg & data rates may apply."
+  error="Please agree to SMS notifications to continue."
 />
+```
+
+> **Note:** When using a `trailing` interactive element, always call `e.preventDefault()` on its click handler to prevent the wrapping `<label>` from toggling the checkbox — as used in the OpenFrame customer guardrails tab.
+
+## Source
 
-// Flamingo theme
-<div data-app-type="flamingo">
-  <CheckboxBlock label="Accept terms" defaultChecked />
-</div>
-```
+[`CheckboxBlock.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/CheckboxBlock.stories.tsx)

package/src/stories/.ContextCompactionDisplay.stories.md

@@ -0,0 +1,28 @@
+<!-- source-hash: a00c050a6f1eac8477435dd9a06e4ae0 -->
+Storybook stories for `ContextCompactionDisplay`, a chat UI component that renders inline status pills when conversation context is compacted — showing a dots loader for the `started` state and a green check for `completed`.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `Started` | `Story` | Displays the in-progress state with a dots loader (`status: "started"`) |
+| `Completed` | `Story` | Displays the finished state with a green check (`status: "completed"`) |
+| `meta` | `Meta` | Storybook metadata wiring `ContextCompactionDisplay` under `Chat/ContextCompactionDisplay` |
+
+## Usage Example
+
+```typescript
+import { ContextCompactionDisplay } from "../components/chat/context-compaction-display";
+
+// In-progress: shows "Context limit reached…" with a dots loader
+<ContextCompactionDisplay status="started" />
+
+// Finished: shows "Earlier context summarized." with a check
+<ContextCompactionDisplay status="completed" />
+```
+
+## Notes
+
+- Stories are tagged with `autodocs` for automatic Storybook documentation generation.
+- The `plainDecorator` wraps each story in a `max-width: 640px` container with the `--color-bg` CSS variable applied, matching the chat surface background.
+- The underlying component (`context-compaction-display`) lives at [`components/chat/context-compaction-display`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/components/chat/context-compaction-display.tsx).

package/src/stories/.CustomerInterviewCard.stories.md

@@ -0,0 +1,36 @@
+<!-- source-hash: fbb7728f24a18cda956623e4fa987806 -->
+Storybook story file for the `CustomerInterviewCard` component, providing visual test stories across two display sizes (`sm` and `default`).
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `meta` | `Meta` | Storybook metadata configuration for `Chat/EntityCards/CustomerInterviewCard` |
+| `ChatInlineSm` | `Story` | Small-size card variant, intended for inline chat usage |
+| `Default` | `Story` | Default-size card variant |
+
+## Usage Example
+
+```typescript
+// Render the Default story in isolation (e.g. in a test or preview)
+import { Default } from './CustomerInterviewCard.stories'
+
+// Story args passed to CustomerInterviewCard:
+// {
+//   interview: customerInterview,       // fixture data for the customer_interview doc type
+//   href: '/customer-interviews/slug',  // deep-link to the full interview page
+//   size: 'default',                    // 'sm' | 'default'
+//   target: '_blank',
+//   rel: 'noopener noreferrer',
+// }
+```
+
+## Notes
+
+- Both stories use shared fixture data from `./__fixtures__/chat-cards` (`customerInterview`).
+- The `ChatColumnDecorator` wraps each story to simulate the chat column layout context.
+- The component's `main_video_url` field controls whether a play-button overlay appears on the cover image.
+- A user + MSP badge overlay renders in both size variants.
+- Stories are registered under the `Chat/EntityCards/CustomerInterviewCard` Storybook path.
+
+**Source:** [`CustomerInterviewCard.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/CustomerInterviewCard.stories.tsx)

package/src/stories/.DashboardInfoCard.stories.md

@@ -1,41 +1,39 @@
-<!-- source-hash: 903a9f23525777b275b7f8c4003cd050 -->
-Storybook stories for the `DashboardInfoCard` UI component, covering all props and visual states used in dashboard layouts.
+<!-- source-hash: 93ee5247b34f46a210b1c67f6352a00a -->
+Storybook stories file for the `DashboardInfoCard` component, providing interactive examples and documentation for all supported prop combinations and visual variants.
 
 ## Key Components
 
+### Stories
+
 | Story | Description |
 |---|---|
 | `Default` | Basic card with title and numeric value |
-| `WithPercentage` | Card showing a percentage alongside the value |
-| `WithProgress` | Circular progress indicator with percentage |
-| `CustomProgressVariant` | Progress ring with `error`/`warning`/`success`/`info`/`accent` variants |
-| `WithTooltip` | Question-mark icon with tooltip text |
-| `WithHref` | Clickable card rendered as a Next.js `Link` |
-| `WarningWithTag` / `ErrorWithTag` | Overflow percentage displayed as a colored `Tag` component |
-| `OverflowWrap` / `OverflowComparison` | Demonstrates `progressOverflow="wrap"` vs `"clamp"` for values >100% |
-| `FullyLoaded` | All props enabled simultaneously |
-| `CardGrid` | Multi-card dashboard grid layout decorator |
+| `StringValue` | Card with a string value |
+| `WithPercentage` | Value with percentage display |
+| `WithProgress` | Circular progress indicator |
+| `CustomProgressVariant` | Progress ring color variants (`success`, `warning`, `error`, `info`, `accent`) |
+| `WithTooltip` | Question-mark icon tooltip |
+| `WithHref` | Clickable card via Next.js Link |
+| `WarningWithTag` / `ErrorWithTag` | Overflow percentage rendered as colored `Tag` |
+| `OverflowWrap` / `OverflowComparison` | `progressOverflow="wrap"` vs `"clamp"` behavior |
+| `PlainPercentageWithColoredRing` | Colored ring with neutral plain-text percentage |
+| `DeviceStatusesOverview` | Four-column Figma "Devices Overview" grid |
+| `ProgressSizeComparison` | 24px vs 56px responsive ring sizes |
+| `WithTitleTag` / `WithTitleAndTag` | Figma "status" variant with `Tag` in title row |
+| `WithIcon` / `WithImage` | Bordered icon/image slot (Figma "icon" variant) |
+| `KitchenSink` | All props combined |
 
 ## Usage Example
 
 ```typescript
-import { DashboardInfoCard } from '@/components/ui/dashboard-info-card'
+import { DashboardInfoCard } from '../components/ui/dashboard-info-card'
+import { Tag } from '../components/ui/tag'
+import { MonitorIcon } from '../components/icons-v2-generated/devices/monitor-icon'
 
-// Basic usage
+// Basic card
 <DashboardInfoCard title="Total Devices" value={1284} />
 
-// With progress ring and navigation
-<DashboardInfoCard
-  title="Compliance Score"
-  value={92}
-  percentage={92}
-  showProgress
-  progressVariant="success"
-  tooltip="Based on the latest audit results"
-  href="/compliance"
-/>
-
-// Overflow handling for values exceeding 100%
+// With circular progress and overflow wrapping
 <DashboardInfoCard
   title="Device Usage"
   value={520}
@@ -44,14 +42,23 @@ import { DashboardInfoCard } from '@/components/ui/dashboard-info-card'
   progressVariant="warning"
   progressOverflow="wrap"
 />
+
+// Figma "icon" variant with navigation
+<DashboardInfoCard
+  title="Endpoints"
+  value={4046}
+  icon={<MonitorIcon />}
+  href="/devices"
+/>
+
+// Figma "status" variant with title Tag
+<DashboardInfoCard
+  title="Tickets"
+  value={75}
+  titleTag={<Tag variant="outline" label="Resolved" />}
+/>
 ```
 
-### `progressVariant` options
+## Source
 
-| Value | Use Case |
-|---|---|
-| `success` | Healthy / on-target metrics |
-| `warning` | Approaching limits |
-| `error` | Critical / over-limit |
-| `info` | Neutral informational |
-| `accent` | Brand highlight |
+[`DashboardInfoCard.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/DashboardInfoCard.stories.tsx)

package/src/stories/.DataRoomDocCard.stories.md

@@ -0,0 +1,42 @@
+<!-- source-hash: f7d4866713e90d4e1df564c5e131e04d -->
+Storybook stories for `DataRoomDocCard`, demonstrating the inline chat card component used to render `data_room_doc` and `markdown` document types in the chat UI.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `meta` | `Meta<typeof DataRoomDocCard>` | Storybook metadata — mounts component inside `ChatColumnDecorator` with `fullscreen` layout |
+| `DataRoom` | `Story` | Card variant using a `data_room_doc` item with `"Data room"` badge |
+| `KnowledgeBaseMarkdown` | `Story` | Card variant using a `markdown` item with `"OpenFrame Docs"` badge |
+
+## Key Concepts
+
+- **Single component, multiple source types** — `DataRoomDocCard` renders both `data_room_doc` and `markdown` doc types; the `sourceRepo` field on the item drives the badge label.
+- **`badgeText` is required** — callers must resolve the label before rendering (e.g. via `SOURCE_LABELS_BY_TABLE`) and pass it explicitly as a prop.
+- **`anchorProps`** — generated via `makeAnchorProps(url)` from the shared fixture helper; wraps the card in a navigable link.
+
+## Usage Example
+
+```typescript
+import { DataRoomDocCard } from '@/components/chat/entity-cards'
+import { makeAnchorProps } from './__fixtures__/chat-card-decorator'
+import { dataRoomDocItem } from './__fixtures__/chat-cards'
+
+// Data room document
+<DataRoomDocCard
+  item={dataRoomDocItem}
+  badgeText="Data room"
+  anchorProps={makeAnchorProps(dataRoomDocItem.url ?? '#')}
+/>
+
+// Markdown / OpenFrame Docs document
+<DataRoomDocCard
+  item={openframeDocsMarkdownItem}
+  badgeText="OpenFrame Docs"
+  anchorProps={makeAnchorProps(openframeDocsMarkdownItem.url ?? '#')}
+/>
+```
+
+## Source
+
+[`DataRoomDocCard.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/DataRoomDocCard.stories.tsx)

package/src/stories/.DataTable.stories.md

@@ -1,41 +1,46 @@
-<!-- source-hash: 4b92799da5c1a1952b02f5fb9273c343 -->
-Storybook showcase for the `DataTable` component, demonstrating all interactive features (sorting, filtering, row selection, column visibility, pagination, and row actions) using a mock device dataset built on TanStack Table.
+<!-- source-hash: 1540bbe5e22e7deb55cf8375776c08db -->
+Storybook showcase file demonstrating all major features of the `DataTable` component, which is a headless wrapper over TanStack Table (`@tanstack/react-table`) with a card-row UI.
 
 ## Key Components
 
-- **`Basic`** — Minimal setup with data and columns; no extra state
-- **`WithSorting`** — Consumer-owned sort cycle with `DataTableSortState`, supporting server-side or in-memory sorting
-- **`useDataTable`** — Hook wrapping TanStack Table; accepts `data`, `columns`, and flags like `clientSideSorting` / `clientSideFiltering`
-- **`baseColumns()`** — Reusable `ColumnDef<Device>[]` factory shared across stories, with responsive `hideAt` breakpoints
-- **Cell renderers** — `StatusTag`, `OSBadge`, `OwnerCell`, `TagsCell`, `LoadCell`, `LastSeenCell` — composable display-only cells
-- **`multiSelectFilterFn`** — Column filter function for multi-value faceted filtering (OS, Status)
-- **`makeDevices(count, startId?)`** — Deterministic fake device data generator seeded by index
+- **`DataTable`** — Root compound component accepting a TanStack `table` instance
+- **`DataTable.Header`** — Renders column headers with optional sort indicators
+- **`DataTable.Body`** — Renders data rows with configurable empty state
+- **`useDataTable`** — Hook that creates and manages the TanStack table instance
+- **`multiSelectFilterFn`** — Filter function for multi-value column filters
+- **Story exports**: `Basic`, `WithSorting` (and implied additional stories for filtering, selection, column visibility, etc.)
 
 ## Usage Example
 
 ```typescript
-import { DataTable, useDataTable, type ColumnDef } from '@/components/ui/data-table'
-
-const columns: ColumnDef<Device>[] = [
-  { accessorKey: 'hostname', header: 'Hostname', meta: { width: 'w-[200px]' } },
-  { accessorKey: 'status',   header: 'Status',   cell: ({ row }) => <StatusTag status={row.original.status} /> },
-]
-
-export function DevicesTable({ data }: { data: Device[] }) {
-  const table = useDataTable<Device>({
-    data,
-    columns,
-    clientSideSorting: true,
-    clientSideFiltering: true,
-  })
-
-  return (
-    <DataTable table={table}>
-      <DataTable.Header />
-      <DataTable.Body emptyMessage="No devices found" />
-    </DataTable>
-  )
-}
+// Minimal setup (Basic story pattern)
+const columns = useMemo<ColumnDef<Device>[]>(() => [
+  { accessorKey: 'hostname', header: 'Hostname', meta: { width: 'w-[260px]' } },
+  {
+    accessorKey: 'status',
+    header: 'Status',
+    cell: ({ row }) => <StatusTag status={row.original.status} />,
+    meta: { width: 'w-[140px]' },
+  },
+], [])
+
+const table = useDataTable<Device>({ data, columns })
+
+return (
+  <DataTable table={table}>
+    <DataTable.Header />
+    <DataTable.Body emptyMessage="No devices" />
+  </DataTable>
+)
+
+// Client-side sorting (WithSorting story pattern)
+const table = useDataTable<Device>({
+  data: sortedData,
+  columns,
+  clientSideSorting: true,
+})
 ```
 
-> **Note:** Row actions, checkboxes, and chevron links are regular `ColumnDef` entries — not magic props. Use `data-no-row-click` on interactive cell wrappers to prevent click-event bubbling to `onRowClick`.
+> **Note:** `useDataTable` defaults to `manualSorting: true` / `manualFiltering: true` for server-side use. Pass `clientSideSorting: true` or `clientSideFiltering: true` for in-memory operations. Row actions, chevron links, and selection checkboxes are declared as regular `ColumnDef` entries — not special props. Interactive cells that should not bubble clicks to `onRowClick` must wrap their content in a `data-no-row-click` div.
+
+**Source:** [`DataTable.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/DataTable.stories.tsx)

package/src/stories/.DatePicker.stories.md

@@ -1,38 +1,31 @@
-<!-- source-hash: 62c605b851ea957354fc89970178b5ca -->
-Storybook stories for the `DatePicker` UI component, covering single date, date range, input variants, time selection, constraints, and all-variants showcase.
+<!-- source-hash: db07b4e2e8a6c654b5b46e0057a004cc -->
+Storybook stories file for the `DatePicker` component, showcasing all variants, modes, and sub-components with interactive state management.
 
 ## Key Components
 
-| Export | Description |
-|--------|-------------|
-| `Single` | Basic single-date picker, uncontrolled initial state |
-| `SingleWithValue` | Single picker pre-seeded with today's date |
-| `Range` | Date range picker (from/to selection) |
-| `RangeWithValue` | Range picker pre-filled with today + 7 days |
-| `RangeTwoMonths` | Range picker showing two calendar months simultaneously |
+| Story | Description |
+|---|---|
+| `Single` | Basic single-date picker, empty initial state |
+| `SingleWithValue` | Single-date picker pre-seeded with today's date |
+| `Range` | Date range picker with `from`/`to` selection |
+| `RangeWithValue` | Range picker pre-seeded with a 7-day window |
+| `RangeTwoMonths` | Range picker rendering two calendar months |
 | `Disabled` | Non-interactive picker in disabled state |
-| `WithLabel` / `WithLabelAndError` | Picker with ODS label and optional error message |
-| `RangeWithLabel` | Range picker with label |
-| `CustomFormat` | Single picker with custom `formatDate` callback (en-GB locale) |
-| `WithConstraints` | Single picker limited to the next 30 days via `fromDate`/`toDate` |
-| `InputStyle` | `DatePickerInput` — calendar-icon-styled input variant |
-| `InputWithLabel` / `InputWithLabelAndError` | Input variant with label/error |
-| `InputWithTimeEmpty` | `DatePickerInput` with `showTime`, no initial value |
-| `InputWithTime` | `DatePickerInput` with `showTime`, pre-seeded with today |
-| `InputWithTime24Hour` | `DatePickerInput` with `use24HourFormat` flag |
-| `AllVariants` | Side-by-side showcase of all major variants |
+| `WithLabel` / `WithLabelAndError` | Picker with a field label and optional error message |
+| `CustomFormat` | Single picker using a custom `formatDate` callback |
+| `WithConstraints` | Single picker locked to the next 30 days via `fromDate`/`toDate` |
+| `InputStyle` | `DatePickerInput` — calendar-icon input field variant |
+| `InputWithTime` / `InputWithTimeEmpty` | `DatePickerInput` with 12-hour time selector |
+| `InputWithTime24Hour` | `DatePickerInput` with 24-hour time selector |
+| `AllVariants` | Side-by-side showcase of every picker variant |
 
 ## Usage Example
 
 ```typescript
+import { DatePicker, DatePickerInput, type DateRange } from "../components/ui/date-picker";
 import { useState } from "react";
-import {
-  DatePicker,
-  DatePickerInput,
-  type DateRange,
-} from "../components/ui/date-picker";
 
-// Single date picker
+// Single date
 function SingleExample() {
   const [date, setDate] = useState<Date | undefined>();
   return (
@@ -46,22 +39,28 @@ function SingleExample() {
   );
 }
 
-// Range picker with two months
+// Date range with constraints
 function RangeExample() {
   const [range, setRange] = useState<DateRange | undefined>();
+  const today = new Date();
+  const maxDate = new Date();
+  maxDate.setDate(today.getDate() + 30);
+
   return (
     <DatePicker
       mode="range"
-      placeholder="Select date range"
+      placeholder="Select range"
       value={range}
       onChange={setRange}
+      fromDate={today}
+      toDate={maxDate}
       numberOfMonths={2}
     />
   );
 }
 
-// Input variant with time (12h)
-function InputTimeExample() {
+// Input style with time selector
+function InputWithTimeExample() {
   const [date, setDate] = useState<Date | undefined>(new Date());
   return (
     <DatePickerInput
@@ -69,8 +68,13 @@ function InputTimeExample() {
       value={date}
       onChange={setDate}
       showTime
+      use24HourFormat
       label="Event Date"
     />
   );
 }
-```
+```
+
+## Source
+
+[`DatePicker.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/DatePicker.stories.tsx)

package/src/stories/.EmbeddableChat.stories.md

@@ -1,41 +1,58 @@
-<!-- source-hash: 928a4aa8278d9b5dca88c4e94782c25c -->
-Storybook stories for the `EmbeddableChat` component, covering three chat surface configurations: Guide-only, Mingo-only, and dual-mode (both transports enabled with a toggle).
+<!-- source-hash: 9e8b462d0e5c8f06f95dbf57d2bb9d98 -->
+Storybook visual stories for the `EmbeddableChat` component, covering new-user, returning-user, loading, error, and agent-mode states using mocked runtimes and NATS chat adapters.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `GuideOnly` | `Story` | Legacy single-mode Guide consumer matching `multi-platform-hub` mount pattern |
-| `MingoOnly` | `Story` | NATS agent transport surface with no mode toggle |
-| `BothModes` | `Story` | Dual-mode consumer with segmented Guide/Mingo header toggle |
-| `StoryShell` | Decorator | Wraps stories with `QueryClientProvider` + `ChatRuntimeContext` + canvas background |
-| `createMockRuntime()` | Helper | Returns a `ChatRuntime` with stub endpoints (all `/__story__/*`) |
-| `createMockMingoConfig()` | Helper | Returns a `UseNatsChatAdapterConfig` with `getNatsWsUrl: () => null` (no WS handshake) |
-| `SAMPLE_SLASH_COMMANDS` | Constant | 13 mock slash commands used to populate the empty-state chip grid |
+| Export / Identifier | Purpose |
+|---|---|
+| `createMockRuntime()` | Builds a minimal `ChatRuntime` with stub endpoints (no real server calls) |
+| `createMockMingoConfig()` | Base NATS adapter config; `getNatsWsUrl` returns `null` to keep WS idle |
+| `createMockMingoConfigWithDialogs()` | Extends base config with a paginated dialog history, rename/archive callbacks, and archived dialog support |
+| `createMockMingoConfigChatsLoading()` | Pins `isDialogsLoading: true` via a never-settling `fetchDialogs` promise |
+| `createMockMingoConfigChatLoading()` | Resolves the dialog list but pins message loading via a never-settling `fetchDialogMessages` |
+| `createMockMingoConfigChatsError()` | Rejects `fetchDialogs` to exercise the load-error + retry UI path |
+| `createMockMingoConfigArchiveEmpty()` | Resolves an empty archived dialogs page to render the archive empty state |
+| `SAMPLE_DIALOGS` | Eight canned `DialogItem` entries representing a returning user's chat history |
+| `SAMPLE_QUICK_ACTIONS` | Five `MingoQuickAction` chips passed to `EmbeddableChat` for the welcome view |
+| `FAE_AGENT_CONFIG` | Mocked `/api/ai-agents/fae` response for agent-mode quick-action chip rendering |
+| `COMMANDS_URL` / `COMMANDS_PREFIX` | Constants shared between the runtime mock and the `fetch` shim for slash-command stubs |
 
 ## Usage Example
 
 ```typescript
-// Minimal dual-mode story using the same pattern as BothModes
-export const MyStory: Story = {
-  render: (args) => (
-    <EmbeddableChat
-      {...args}
-      modes={{
-        guide: {},
-        mingo: createMockMingoConfig(),
-      }}
-      defaultActiveMode="mingo"
-      defaultOpen
-      showInternalTrigger={false}
-    />
+// Wrap EmbeddableChat in the required providers for a story
+function MemoizedRuntime({ children }: { children: React.ReactNode }) {
+  const runtime = useMemo(() => createMockRuntime(), [])
+  const queryClient = useMemo(() => new QueryClient(), [])
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <ChatRuntimeContext.Provider value={runtime}>
+        {children}
+      </ChatRuntimeContext.Provider>
+    </QueryClientProvider>
+  )
+}
+
+// Returning-user story with dialog history
+export const ReturningUser: StoryObj<typeof EmbeddableChat> = {
+  render: () => (
+    <MemoizedRuntime>
+      <EmbeddableChat
+        mingoConfig={createMockMingoConfigWithDialogs()}
+        quickActions={SAMPLE_QUICK_ACTIONS}
+      />
+    </MemoizedRuntime>
   ),
-  args: {},
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+    await userEvent.click(canvas.getByRole('button', { name: /history/i }))
+  },
 }
 ```
 
 ## Notes
 
-- The `window.fetch` shim is installed **at module level** (not inside an effect) so the mock is in place before `EmbeddableChat`'s `useEffect` fires. A `__embeddableChatStoriesMockInstalled__` flag prevents double-patching across hot reloads.
-- All story endpoints resolve to `/__story__/*` — accidental real fetches return 404, not real server data.
-- `getNatsWsUrl: () => null` keeps the NATS dialog subscription idle in all stories.
+- The `pending<T>()` helper (`new Promise<T>(() => {})`) is the idiomatic way to freeze a loading state in Storybook without fake timers.
+- The `fetch` shim intercepts `COMMANDS_URL` and `AI_AGENT_CONFIG_PREFIX` requests so agent-mode and slash-command UI renders without a live backend.
+- Source: [`EmbeddableChat.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/EmbeddableChat.stories.tsx)

package/src/stories/.EmptyState.stories.md

@@ -0,0 +1,55 @@
+<!-- source-hash: b386b620f40c6970f6aa58f7c44bc3eb -->
+Storybook stories for the `NoData` empty-state component, covering the full range of compositional variants from a complete layout to individual sub-components.
+
+## Key Components
+
+| Export | Description |
+|---|---|
+| `Default` | Full composition with icon, title, description, feature actions, and Mingo CTA button |
+| `MessageTitleOnly` | Minimal state showing only an icon and title |
+| `WithoutActions` | Layout without the feature actions block |
+| `WithoutButton` | Layout without the footer CTA button |
+| `TwoActions` / `FourActions` | Dynamic action block with 2 or 4 items |
+| `ButtonAsLink` | CTA button rendered as an anchor (`href`) instead of a click handler |
+| `CustomButton` | Escape-hatch story passing arbitrary JSX via the `button` prop |
+| `StandaloneActions` | Renders `NoDataActions` + `NoDataAction` sub-components in isolation |
+| `StandaloneMessage` | Renders the `NoDataMessage` sub-component in isolation |
+| `Showcase` | Side-by-side gallery of the three most common configurations |
+
+## Usage Example
+
+```typescript
+// Full composition (mirrors the Default story)
+<NoData
+  icon={<Inbox />}
+  title="No data available"
+  description="Start by adding an item"
+  actions={[
+    { icon: <Zap />,      label: 'Real-time sync' },
+    { icon: <Sparkles />, label: 'Smart suggestions' },
+    { icon: <Database />, label: 'Unlimited storage' },
+  ]}
+  buttonLabel="Ask Mingo about Item"
+  buttonIcon={<MingoIcon className="size-5" />}
+  onButtonClick={() => openMingoPanel()}
+/>
+
+// Custom footer via escape hatch
+<NoData
+  icon={<Settings />}
+  title="No sources configured"
+  description="Connect a source to get started"
+  button={
+    <div className="flex gap-2">
+      <Button variant="outline" leftIcon={<Plus />}>Connect source</Button>
+      <Button variant="transparent" leftIcon={<FileText />}>View docs</Button>
+    </div>
+  }
+/>
+```
+
+## Notes
+
+- Stories are registered under **UI/EmptyState** in the Storybook sidebar.
+- `icon`, `actions`, `button`, `buttonIcon`, `onButtonClick`, and `buttonProps` controls are disabled in the Storybook controls panel; `title`, `description`, and `buttonLabel` accept free-text input.
+- The `MingoIcon` CTA uses design-token CSS variables (`--ods-flamingo-cyan-base`) for brand-consistent colouring.