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

package/src/stories/.Board.stories.md

@@ -1,35 +1,40 @@
-<!-- source-hash: eded9627e041539da9106ebd71cd1d56 -->
-Storybook stories for the `Board` component, demonstrating all major configuration variants including drag-and-drop, column types, pagination, loading states, and collapse behavior.
+<!-- source-hash: 8939b0ce480239cfb76e028389e4824d -->
+Storybook stories for the `Board` component, covering all major interaction states including drag-and-drop, column types, pagination, loading, and empty states.
 
 ## Key Components
 
-| Export | Description |
-|--------|-------------|
-| `Default` | Five canonical ticket-status columns with seeded tickets and full drag-and-drop wired up |
-| `SystemAndCustom` | Mixed system and custom columns mirroring the OpenFrame Tickets layout, with DnD restrictions |
-| `CustomColumns` | Fully custom columns proving column color is decoupled from `TicketStatus` |
-| `Collapsible` | Columns with collapse toggle persisted to `localStorage` via `collapseStorageKey` |
-| `Pagination` | Demonstrates `onLoadMore` with a 600ms simulated delay, appending 10 tickets per page from a pool of 50 |
-| `InitialLoading` | All columns start in `isLoading` skeleton state, resolving to seeded data after 1 second |
-| `Empty` | Empty columns to verify the drop placeholder render |
+### Seed Data Helpers
+- **`ASSIGNEES`** — Static array of mock users with `id`, `initials`, and `name`
+- **`baseTicket(i, status, overrides)`** — Factory function generating a `BoardTicket` from index, status string, and optional overrides
+- **`buildSeedColumns()`** — Builds five canonical status columns (`ACTIVE`, `TECH_REQUIRED`, `ON_HOLD`, `RESOLVED`, `ARCHIVED`) with seeded tickets
 
-**Helpers used internally:**
+### State Management Helper
+- **`applyChange(columns, change)`** — Immutably applies a `BoardChange` (drag-and-drop result) to column state, handling `afterTicketId` and `beforeTicketId` insertion points
 
-- `buildSeedColumns()` — generates five default status columns with varied ticket data
-- `applyChange()` — immutably applies a `BoardChange` (move/reorder) to the column state
+### Exported Stories
+
+| Story | Description |
+|---|---|
+| `Default` | Five canonical-status columns with full DnD wired up |
+| `SystemAndCustom` | Mixed system + custom columns; AI-Assistance refuses drops, Resolved tickets are pinned |
+| `CustomColumns` | Fully custom columns decoupled from `TicketStatus` (Backlog, In Review, Blocked, Done) |
+| `Collapsible` | Column collapse/expand with `localStorage` persistence via `collapseStorageKey` |
+| `Pagination` | One column loads 10 of 50 tickets; `onLoadMore` appends pages after a 600ms simulated delay |
+| `InitialLoading` | All columns start in `isLoading` skeleton state, resolving to seed data after 1 second |
+| `Empty` | All columns empty to verify the drop placeholder rendering |
 
 ## Usage Example
 
 ```typescript
-// Minimal interactive board with DnD and immutable state update
+// Minimal controlled Board with DnD
 const [columns, setColumns] = React.useState(buildSeedColumns())
 
 <Board
   columns={columns}
   onChange={change => setColumns(prev => applyChange(prev, change))}
-  onTicketClick={id => console.log('clicked', id)}
-  onAddTicket={colId => console.log('add to', colId)}
-  collapseStorageKey="my-board-collapse"
-  onLoadMore={columnId => fetchNextPage(columnId)}
+  getTicketHref={id => `/tickets/${id}`}
+  onAddTicket={columnId => console.log('add to', columnId)}
 />
-```
+```
+
+**Source:** [`Board.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/Board.stories.tsx)

package/src/stories/.Button.stories.md

@@ -1,53 +1,48 @@
-<!-- source-hash: da7a4cc8d96ad03653cebb8d1ec11d45 -->
-Storybook stories for the `Button` UI component, covering all variants, sizes, states, icon configurations, and link behaviors with interactive controls.
+<!-- source-hash: 9800f8a45e8e63abbb33c1772baecc99 -->
+Storybook stories for the `Button` component, covering all variants, sizes, states, icon configurations, and link behaviors used in the OpenFrame UI library.
 
 ## Key Components
 
-| Story | Description |
+| Export | Description |
 |---|---|
-| `Accent` / `Outline` / `Transparent` / `Destructive` | Surface variant stories |
-| `SizeDefault` / `SizeSmall` | Size variant stories |
-| `IconOnly` / `WithLeftIcon` / `WithRightIcon` / `WithBothIcons` | Icon placement stories |
-| `Disabled` / `Loading` / `FullWidth` | State stories |
-| `SplitIcon` / `SplitIconOutline` / `SplitIconSmall` / `SplitIconAsLink` | Split-icon button variations |
-| `AsLink` / `ExternalLink` | Button rendered as anchor tag |
-| `AllVariants` / `AllSizes` / `IconButtonGrid` / `WithIconsShowcase` / `StatesShowcase` / `NotificationCounters` | Showcase/grid stories |
-
-**Controls exposed via `argTypes`:** `variant`, `size`, `fullWidth`, `disabled`, `loading`
+| `Accent`, `Outline`, `Transparent`, `Destructive`, `Warning` | Individual variant stories |
+| `SizeDefault`, `SizeSmall`, `SizeCompact` | Size variant stories |
+| `IconOnly`, `WithLeftIcon`, `WithRightIcon`, `WithBothIcons` | Icon placement stories |
+| `Disabled`, `Loading`, `FullWidth` | State stories |
+| `SplitIcon`, `SplitIconOutline`, `SplitIconAsLink`, `SplitIconSmall` | Split icon button stories |
+| `AsLink`, `ExternalLink` | Anchor/navigation stories |
+| `AllVariants`, `AllSizes`, `IconButtonGrid`, `WithIconsShowcase`, `StatesShowcase`, `NotificationCounters` | Composite showcase stories |
 
 ## Usage Example
 
 ```typescript
-// Minimal interactive story with controls
-import { Button } from '../components/ui/button';
-
-export const MyStory: Story = {
-  args: {
-    children: 'Click me',
-    variant: 'accent',
-    size: 'default',
-    loading: false,
-    disabled: false,
-  },
+// Individual story — renders an accent button
+export const Accent: Story = {
+  args: { children: 'Button', variant: 'accent' },
 };
 
-// Split-icon button as a navigation link
-export const SplitNav: Story = {
-  args: {
-    children: 'Docs',
-    href: '/docs',
-    splitIcon: <ExternalLinkIcon />,
-    variant: 'outline',
+// Composite showcase — renders all variants in normal, disabled, and loading states
+export const AllVariants: Story = {
+  args: { children: 'Button' },
+  render: () => {
+    const variants = ['accent', 'outline', 'transparent', 'destructive', 'warning'] as const;
+    return (
+      <div style={{ display: 'grid', gridTemplateColumns: 'auto auto auto', gap: '1rem' }}>
+        {variants.map((variant) => (
+          <React.Fragment key={variant}>
+            <Button variant={variant}>{variant}</Button>
+            <Button variant={variant} disabled>{variant}</Button>
+            <Button variant={variant} loading>{variant}</Button>
+          </React.Fragment>
+        ))}
+      </div>
+    );
   },
 };
+```
 
-// Icon-only with accessible label
-export const IconAction: Story = {
-  args: {
-    size: 'icon',
-    variant: 'destructive',
-    leftIcon: <Trash2 />,
-    'aria-label': 'Delete item',
-  },
-};
-```
+## Controlled Args
+
+The Storybook `argTypes` panel exposes interactive controls for `variant` (`accent` | `outline` | `transparent` | `destructive` | `warning`), `size` (`default` | `small` | `compact` | `icon`), `fullWidth`, `disabled`, and `loading`.
+
+**Source:** [`Button.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/Button.stories.tsx)

package/src/stories/.CampaignCardAdmin.stories.md

@@ -0,0 +1,38 @@
+<!-- source-hash: 62d0fd5af004b0935685d20d4d932ddc -->
+Storybook stories for the `CampaignCardAdmin` chat-inline entity card, covering default display and edge cases where optional fields (description, goals) are absent.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `Default` | `Story` | Full campaign card with name, start date, goal count, and description |
+| `NoDescription` | `Story` | Campaign card with `description` set to `null` |
+| `NoGoals` | `Story` | Campaign card with an empty `goals` array |
+
+## Usage Example
+
+```typescript
+import { CampaignCardAdmin } from '../components/chat/entity-cards'
+import { campaignItem } from './__fixtures__/chat-cards'
+import { makeAnchorProps } from './__fixtures__/chat-card-decorator'
+
+// Render the card in your chat UI
+<CampaignCardAdmin
+  campaign={campaignItem}
+  anchorProps={makeAnchorProps('/admin/campaigns/' + campaignItem.id)}
+/>
+
+// Handle missing optional fields gracefully
+<CampaignCardAdmin
+  campaign={{ ...campaignItem, description: null, goals: [] }}
+  anchorProps={makeAnchorProps('/admin/campaigns/' + campaignItem.id)}
+/>
+```
+
+## Notes
+
+- Wrapped in `ChatColumnDecorator` to simulate the constrained chat column layout.
+- This is the **chat-only projection** of the `marketing_campaign` doc type — delete/manage actions belong to the hub's full admin card.
+- Stories live under the `Chat/EntityCards/CampaignCardAdmin` Storybook path.
+
+**Source:** [`CampaignCardAdmin.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/CampaignCardAdmin.stories.tsx)

package/src/stories/.CardsStrip.stories.md

@@ -0,0 +1,39 @@
+<!-- source-hash: f14c97ac08b17c846941af692b1556a9 -->
+Storybook story file for the `CardsStrip` component, covering chevron navigation, mixed card types, marquee auto-scroll, overflow edge cases, and custom cell width variants using real entity card fixtures.
+
+## Key Components
+
+| Export | Description |
+|---|---|
+| `CaseStudiesChevrons` | Chevron-nav strip of 7 uniform case-study cards with `autoScroll={false}` (Figma 3905:77388) |
+| `MixedCardTypes` | Strip mixing `CaseStudyCard`, `BlogCard`, and `CustomerInterviewCard` to verify row alignment |
+| `MarqueeOptIn` | Default marquee mode; documents clone accessibility contract (aria-hidden, tabindex suppression, click passthrough) |
+| `TwoItemsNoOverflow` | Edge case — fewer items than viewport width, so no clones, chevrons, or marquee activate |
+| `CustomCellWidth` | Demonstrates `cardWidthDesktop`/`cardWidthMobile` overrides for compact layouts |
+
+All stories use **organic children mode** (plain JSX children, no strip-side registration). The render-prop mode is covered by `VideoBitesStrip.stories.tsx`.
+
+## Usage Example
+
+```typescript
+// Chevron strip — pass autoScroll={false} for entity strips
+<CardsStrip title="Case Studies" autoScroll={false}>
+  {caseStudies.map(study => (
+    <CaseStudyCard key={study.slug} study={study} href={`/case-studies/${study.slug}`} />
+  ))}
+</CardsStrip>
+
+// Marquee strip — omit autoScroll (engine default is true)
+<CardsStrip title="Case Studies">
+  {caseStudies.map(study => (
+    <CaseStudyCard key={study.slug} study={study} href={`/case-studies/${study.slug}`} />
+  ))}
+</CardsStrip>
+
+// Custom cell widths
+<CardsStrip title="Compact Row" autoScroll={false} cardWidthDesktop={320} cardWidthMobile={280}>
+  {/* cards */}
+</CardsStrip>
+```
+
+> **Guidance:** Always pass `autoScroll={false}` for chevron-style entity strips. The engine defaults to `autoScroll={true}` for the marquee/bites contract — omitting it in an entity strip will silently enable marquee behavior.

package/src/stories/.CaseStudyCard.stories.md

@@ -0,0 +1,41 @@
+<!-- source-hash: 75ac7c181bdd6e2ff693703757ed5c57 -->
+Storybook stories for `CaseStudyCard`, covering both the compact chat-inline (`sm`) and full catalog grid (`default`) size variants of the `case_study` entity card.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `meta` | `Meta<CaseStudyCard>` | Storybook metadata — registers the component under `Chat/EntityCards/CaseStudyCard` with fullscreen layout |
+| `ChatInlineSm` | `Story` | Renders the compact card variant used inline within chat messages |
+| `Default` | `Story` | Renders the full catalog grid card variant |
+
+## Usage Example
+
+```typescript
+import { CaseStudyCard } from '../components/chat/entity-cards'
+import { caseStudy } from './__fixtures__/chat-cards'
+
+// Compact chat-inline variant
+<CaseStudyCard
+  study={caseStudy}
+  href={`/case-studies/${caseStudy.slug}`}
+  size="sm"
+  target="_blank"
+  rel="noopener noreferrer"
+/>
+
+// Full catalog grid variant
+<CaseStudyCard
+  study={caseStudy}
+  href={`/case-studies/${caseStudy.slug}`}
+  size="default"
+  target="_blank"
+  rel="noopener noreferrer"
+/>
+```
+
+## Notes
+
+- Both stories are wrapped in `ChatColumnDecorator` to simulate the chat column layout context.
+- The `CaseStudyCard` supports two sizes: `"sm"` (chat-inline compact) and `"default"` (catalog grid). Both render a user + MSP badge overlay.
+- Fixture data is sourced from [`__fixtures__/chat-cards`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/stories/__fixtures__/chat-cards.ts).

package/src/stories/.ChatContainer.stories.md

@@ -0,0 +1,41 @@
+<!-- source-hash: 292551494d3d57529210cbc9d678d8e9 -->
+Storybook stories for the `ChatContainer` composite component, demonstrating the full Fae client-facing chat shell across layout and state variants.
+
+## Key Components
+
+- **`FaeChatShell`** — Internal interactive wrapper that composes `ChatContainer`, `ChatHeader`, `ChatContent`, `ChatFooter`, `ChatMessageList`, `ChatInput`, `QuickActionWall`, and `ModelDisplay` into a working chat UI. Manages local message state and simulates user message submission.
+- **`FAE_MESSAGES`** — Sample conversation seed data pre-populating the message list with a realistic Fae/user exchange.
+- **`SAMPLE_QUICK_ACTIONS`** — Three quick-action chips (`Computer slow`, `Check updates`, `Internet problems`) used in the `QuickActionWall`.
+
+### Exported Stories
+
+| Story | Description |
+|---|---|
+| `Fae` | Default Fae chat shell with no extras |
+| `FaeWithTicket` | Header shows active ticket info row |
+| `ClientChatWithMspOrganization` | MSP branding bar rendered in header |
+| `ClientChatMspOrganizationLoading` | MSP branding slot in skeleton/loading state |
+| `FaeFullWidth` | Drops centered column; fills full container width |
+| `FaeBareHeader` | Strips card chrome from header for embedded contexts |
+| `FaeModelLoading` | `ModelDisplaySkeleton` shown while model metadata resolves |
+
+## Usage Example
+
+```typescript
+// Render the default Fae story in isolation
+import { Fae } from './ChatContainer.stories'
+
+// In a test or custom harness:
+<Fae.render />
+
+// Or control FaeChatShell props directly:
+<FaeChatShell
+  withTicketInfo
+  fullWidth
+  modelLoading={false}
+/>
+```
+
+## Source
+
+[`ChatContainer.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/ChatContainer.stories.tsx)

package/src/stories/.ChatInlineVideoPill.stories.md

@@ -0,0 +1,36 @@
+<!-- source-hash: b79b2c8f9f7df800c6a753d097091a12 -->
+Storybook stories for `ChatInlineVideoPill`, an inline span component that renders a video reference pill inside chat assistant message paragraphs.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `ChatInlineVideoPill` | Local component | Inline `<span>` pill showing a play icon and truncated video title |
+| `Default` | `Story` | Standard pill with a short, readable title |
+| `LongTitleTruncates` | `Story` | Validates truncation at `max-w-[220px]` for long titles |
+
+## Usage Example
+
+```typescript
+// The component is defined inline in dispatch.tsx (~line 318-326)
+// and is reproduced here for isolated story rendering:
+function ChatInlineVideoPill({ title }: { title: string }) {
+  return (
+    <span className="inline-flex items-center gap-1 px-1.5 py-0.5 rounded text-xs align-middle bg-ods-card border border-ods-border text-ods-text-primary">
+      <span aria-hidden="true" className="text-ods-text-secondary">▶</span>
+      <span className="truncate max-w-[220px]">{title}</span>
+    </span>
+  )
+}
+```
+
+## Design Notes
+
+- **Inline-only** — unlike all other entity cards, this component has no card wrapper, Ask/Display affordance, or block-level container. It sits directly within `<p>` text flow.
+- **Video hoisting** — the actual video player is extracted from the paragraph by the chat pre-scan pipeline and rendered above the assistant turn. This pill acts as a inline sentinel/reference marker.
+- **Truncation** — titles are capped at `max-w-[220px]` to prevent line wrapping of surrounding paragraph text.
+- **Decorator** — stories wrap the pill in a realistic `<p>` context via `ChatColumnDecorator` to verify inline flow renders correctly alongside surrounding prose.
+
+## Source
+
+[`ChatInlineVideoPill.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/ChatInlineVideoPill.stories.tsx)

package/src/stories/.ChatMessageEnhanced.stories.md

@@ -0,0 +1,51 @@
+<!-- source-hash: 97c4cee0a62454c372bae94dd2deb03b -->
+Storybook story file for `ChatMessageEnhanced`, providing interactive visual documentation for the primary chat message renderer used across Mingo (admin) and Fae (client) chat interfaces.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `AssistantFae` | `Story` | Fae assistant message with pink mono name and timestamp |
+| `AssistantMingo` | `Story` | Mingo assistant message with cyan mono name |
+| `UserMessage` | `Story` | User-authored message with grey mono name |
+| `FaeConversationTyping` | `Story` | Multi-message Fae flow showing greeting → user request → typing indicator |
+| `FaeConversationApproved` | `Story` | Fae flow with a resolved `approval_request` segment (APPROVED pill) |
+| `PendingApprovalSegment` | `Story` | Client approval card with live Approve/Reject buttons |
+| `AllSegmentTypes` | `Story` | Single message rendering all segment types: `thinking`, `text`, `tool_execution`, `context_compaction`, `error` |
+
+## Usage Example
+
+```typescript
+// Render a Fae assistant message with an approval segment
+<ChatMessageEnhanced
+  role="assistant"
+  name="Fae"
+  approvalVariant="client"
+  timestamp={new Date()}
+  content={[
+    { type: "text", text: "Just need your quick approval here." },
+    {
+      type: "approval_request",
+      data: {
+        command: "brew install --cask slack",
+        requestId: "req-1",
+        approvalType: "CLIENT",
+        explanation: "Install Slack via Homebrew Cask on macOS",
+      },
+      status: "pending",
+      onApprove: () => {},
+      onReject: () => {},
+    },
+  ]}
+/>
+```
+
+## Notes
+
+- **`at247()`** — pins story timestamps to `2:47 PM` so snapshot tests are deterministic; today-dated messages render time-only via `formatMessageTimestamp`.
+- **`panelDecorator`** — wraps each story in a `640px` container with the system background token, matching the `ChatMessageList` host context.
+- **`FaeConversationTyping` / `FaeConversationApproved`** — composite render functions that reproduce the full Fae desktop-app flow matching the Figma `fae-approval-block` spec.
+
+## Source
+
+[`ChatMessageEnhanced.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/ChatMessageEnhanced.stories.tsx)

package/src/stories/.ChatMingoInfoCards.stories.md

@@ -0,0 +1,30 @@
+<!-- source-hash: 72bc4b44eb59f863ebc8b29a59c67d77 -->
+Storybook stories file that documents and visually demonstrates `MingoInfoCard` variants for in-chat entity cards, mirroring the field mapping (icon, status pill, description, overflow menu) from the `CHAT_CARD_REGISTRY` dispatch for each integrated source type.
+
+## Key Components
+
+- **`meta`** — Storybook `Meta` config registering stories under `Chat/ChatMingoInfoCards`, with `fullscreen` layout and a `ChatColumnDecorator` wrapper that reproduces the in-chat column context.
+- **`openMenu`** — Shared factory that builds the standardized "⋯" overflow menu with `Ask Mingo` (Mingo logo) and `Open Details` (eye icon + ↗ new-tab side button) actions.
+- **`HubspotTicket`** — Story covering `hubspot_ticket` registry types; demonstrates status pill variants (`warning` → Open, `success` → Closed, `grey` → other) and missing-description/status edge cases.
+- **`GithubActivity`** — Story covering `github_commit`, `github_pull_request`, and `github_pr_review` types; shows per-kind icon switching and review-state pills (`success` → Approved, `error` → Changes, `grey` → Comment/neutral).
+- **`SlackMessage`** — Story covering `slack_message`; demonstrates the no-pill pattern with author + channel in the title and message preview as description.
+
+## Usage Example
+
+```typescript
+// Reproduce the HubSpot ticket card outside Storybook
+import { MingoInfoCard } from '../components/chat/mingo-info-card'
+import { TagIcon } from '../components/icons-v2-generated/shopping/tag-icon'
+
+<MingoInfoCard
+  title="Login page returns 500 after SSO redirect"
+  description="Customer cannot sign in via Google SSO since this morning…"
+  icon={<TagIcon size={24} />}
+  status={{ label: 'Open', variant: 'warning' }}
+  anchorProps={{ href: 'https://app.hubspot.com/contacts/0/ticket/123' }}
+  menuGroups={openMenu('https://app.hubspot.com/contacts/0/ticket/123')}
+  menuAriaLabel="Ticket actions"
+/>
+```
+
+**Source:** [`ChatMingoInfoCards.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/ChatMingoInfoCards.stories.tsx)

package/src/stories/.ChatTicketList.stories.md

@@ -1,33 +1,49 @@
-<!-- source-hash: 995995dfe9715311703dcbbfc0fbba0b -->
-Storybook stories for the `ChatTicketList` component, providing visual test cases across different ticket counts, statuses, and scroll/fade behaviors.
+<!-- source-hash: abdfb61054ac90989111840ada6a1cca -->
+Storybook stories for the `ChatTicketList` component, providing interactive visual test cases covering ticket states, scroll fading behavior, and loading skeletons.
 
 ## Key Components
 
-- **`meta`** — Storybook metadata registering the component under `Chat/ChatTicketList` with autodocs and a `ticketClicked` action handler
-- **`mockTickets`** — 5-item fixture dataset covering all ticket statuses: `ACTIVE`, `ON_HOLD`, `TECH_REQUIRED`, and `RESOLVED`
-- **`manyTickets`** — 15-item extended dataset (includes `mockTickets`) for testing scroll and fade overflow scenarios
-- **`constrainedDecorator`** — Factory returning a story decorator that wraps the component in a max-width 600px container with an optional fixed height, used to simulate real layout constraints
+| Export | Description |
+|---|---|
+| `Default` | Five mock tickets spanning all common statuses |
+| `SingleTicket` | Minimal single-ticket render |
+| `AllStatuses` | Four tickets demonstrating `ACTIVE`, `ON_HOLD`, `TECH_REQUIRED`, and `RESOLVED` states |
+| `ScrollFading` | 15 tickets in a 400px container to showcase scroll-edge fade effect |
+| `ScrollFadingCompact` | Same dataset in a tighter 280px container for more pronounced fading |
+| `Loading` | Empty tickets array with `isLoading: true` to render skeleton placeholder rows |
 
-## Exported Stories
+**Helpers**
 
-| Story | Description |
-|---|---|
-| `Default` | 5 tickets, unconstrained height |
-| `SingleTicket` | Only the first ticket rendered |
-| `AllStatuses` | First 4 tickets showing each distinct status |
-| `ScrollFading` | 15 tickets in a 400px container to demonstrate scroll fade |
-| `ScrollFadingCompact` | 15 tickets in a 280px container for more pronounced fade |
+- `mockTickets` — five representative `ChatTicketItemData` fixtures covering the four ticket statuses
+- `manyTickets` — extends `mockTickets` to 15 entries across diverse categories (Email, Security, Onboarding, Infrastructure, etc.)
+- `constrainedDecorator(height?)` — wraps each story in a max-width 600px flex container; accepts an optional fixed height to trigger scrollable overflow
 
 ## Usage Example
 
 ```typescript
-// Replicate the ScrollFading story manually
+// Render the scroll-fading story locally in Storybook
+import { ScrollFading } from "./ChatTicketList.stories";
+
+// Or compose the component directly with the same fixture data
 import { ChatTicketList } from "../components/chat/chat-ticket-list";
+import type { ChatTicketItemData } from "../components/chat/entity-cards/chat-ticket-item";
+
+const tickets: ChatTicketItemData[] = [
+  {
+    id: "1",
+    title: "Printer not working",
+    ticketNumber: "1002",
+    status: "ACTIVE",
+    category: "Hardware Issue",
+    timeAgo: "2 hours",
+  },
+];
+
+<ChatTicketList
+  tickets={tickets}
+  isLoading={false}
+  onTicketClick={(id) => console.log("clicked", id)}
+/>;
+```
 
-<div style={{ maxWidth: 600, height: 400 }}>
-  <ChatTicketList
-    tickets={manyTickets}
-    onTicketClick={(ticket) => console.log(ticket)}
-  />
-</div>
-```
+**Source:** [`ChatTicketList.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/ChatTicketList.stories.tsx)

package/src/stories/.ChatTypingIndicator.stories.md

@@ -0,0 +1,47 @@
+<!-- source-hash: 794302ba2da5741b5cee3d5040b87f88 -->
+Storybook stories for `ChatTypingIndicator`, documenting the animated three-dot typing indicator component across its size variants and configuration options.
+
+## Key Components
+
+| Export | Type | Description |
+|---|---|---|
+| `Default` | `Story` | Medium-size dots, no label (baseline render) |
+| `Small` | `Story` | `size="sm"` — matches `ChatInput` in-flight state |
+| `Large` | `Story` | `size="lg"` large dot variant |
+| `WithText` | `Story` | Includes "Assistant is typing" label via `showText: true` |
+| `MutedDots` | `Story` | Overrides dot color using `dotClassName` |
+
+## Usage Example
+
+```typescript
+import { ChatTypingIndicator } from "../components/chat/chat-typing-indicator";
+
+// Default medium dots
+<ChatTypingIndicator />
+
+// Small — used inside ChatInput while send is in flight
+<ChatTypingIndicator size="sm" />
+
+// With label and custom dot color
+<ChatTypingIndicator
+  size="lg"
+  showText={true}
+  dotClassName="bg-ods-text-secondary"
+/>
+```
+
+## Props Reference
+
+| Prop | Values | Description |
+|---|---|---|
+| `size` | `"sm"` \| `"md"` \| `"lg"` | Controls dot size; defaults to `"md"` |
+| `showText` | `boolean` | Renders "Assistant is typing" label alongside dots |
+| `dotClassName` | `string` | Tailwind class override for dot color (e.g., `bg-ods-text-secondary`) |
+
+## Notes
+
+- Component is rendered under the message header as the Fae assistant streams a reply
+- The `sm` size variant is also embedded within `<ChatInput>` during pending send state
+- Stories are wrapped in a `400px` max-width container with `var(--color-bg)` background to simulate real chat UI context
+
+**Source:** [`ChatTypingIndicator.stories.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/ChatTypingIndicator.stories.tsx)