@signalflare-ai/ui 0.5.0 → 1.0.0

package/ai/component-registry.md

@@ -30,7 +30,7 @@ Container for a row of AI message action buttons.
 
 ### AiAgentCard
 
-`AiAgentCard` — compact card showing one agent's status in a commander dashboard.  Displays: agent icon, name, status indicator, current task, model, duration, and tool call count. Clickable for selection.
+`AiAgentCard` — compact card showing one agent's status in a commander dashboard. Displays: agent icon, name, status indicator, current task, model, duration, and tool call count. Clickable for selection.
 
 **Type:** component
 
@@ -79,7 +79,7 @@ Container for a row of AI message action buttons.
 
 ### AiApproval
 
-Approval card for tool calls and plan submissions.  Maps to harness events: `tool_approval_required`, `plan_approval_required`, `plan_approved`.
+Approval card for tool calls and plan submissions. Maps to harness events: `tool_approval_required`, `plan_approval_required`, `plan_approved`.
 
 **Type:** component
 
@@ -173,7 +173,7 @@ Outer scroll container for a conversation. Sticks to the bottom as new messages
 
 ### AiInfoBanner
 
-Inline conversation banner for system notices. Renders as a compact, horizontally centered divider-like notice rather than a chat bubble.  Maps to harness events: `error`, `info`, `mode_changed`, `model_changed`.
+Inline conversation banner for system notices. Renders as a compact, horizontally centered divider-like notice rather than a chat bubble. Maps to harness events: `error`, `info`, `mode_changed`, `model_changed`.
 
 **Type:** component
 
@@ -201,34 +201,6 @@ Inline conversation banner for system notices. Renders as a compact, horizontall
 
 ---
 
-### AiLoader
-
-Spinning radial loader for AI streaming states.
-
-**Type:** component
-
-**Import:** `import { AiLoader } from "@signalflare-ai/ui";`
-
-**Category:** Other
-
-**Props:**
-
-- `children`: ReactNode
-- `className`: string
-- `id`: string
-- `lang`: string
-- `title`: string
-- `size`: enum [default: base]
-  - `"sm"`: Small — 12px
-  - `"base"`: Default — 16px
-  - `"lg"`: Large — 20px
-
-**Colors (sf tokens used):**
-
-`text-sf-subtle`
-
----
-
 ### AiMessage
 
 Root message container. Sets layout, group class, and role context.
@@ -259,7 +231,7 @@ Root message container. Sets layout, group class, and role context.
 
 ### AiMissionHeader
 
-`AiMissionHeader` — top bar for the Commander dashboard.  Shows: mission title, progress bar (from task list), agent count, live elapsed time, token usage, and an abort button while running.
+`AiMissionHeader` — top bar for the Commander dashboard. Shows: mission title, progress bar (from task list), agent count, live elapsed time, token usage, and an abort button while running.
 
 **Type:** component
 
@@ -299,9 +271,38 @@ Root message container. Sets layout, group class, and role context.
 
 ---
 
+### AiPartGroup
+
+Groups streaming ephemeral activity (tool calls + reasoning) into a single rolling window during streaming, then collapses to a frozen summary line once the parent message completes. Behavior: - **Streaming:** shows the most recent `max` (default 3) ephemeral children. Pinned rows (errors / user-expanded) sit above the live window. - **Completed:** writes a snapshot keyed by `groupKey`, unmounts ephemeral children entirely, and renders a static `▸ {title} · N steps` line. - **Re-mount after completion:** always renders the cached snapshot — no animations, no `useEffect` re-runs, no tool re-execution risk.
+
+**Type:** component
+
+**Import:** `import { AiPartGroup } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `groupKey`: string (required)
+  Stable identifier — usually the parent message id. Required so the group can persist its frozen snapshot across re-mounts (scroll-back into a virtualized list re-renders without restarting animations).
+- `complete`: boolean
+  Set to `true` once the parent stream has finished. Triggers the group to snapshot its current children and from then on render only the static collapsed summary — ephemeral children never re-mount.
+- `title`: string
+  Title shown in the collapsed summary line. Falls back to the first reasoning text snippet, then to a step count.
+- `children`: ReactNode
+- `className`: string
+- `id`: string
+- `lang`: string
+
+**Colors (sf tokens used):**
+
+`bg-sf-tint`, `border-sf-line`, `text-sf-danger`, `text-sf-default`, `text-sf-subtle`, `text-sf-success`
+
+---
+
 ### AiQuestion
 
-Agent question card. Renders when the agent uses the `ask_user` built-in tool and needs a response before continuing.  Maps to harness event: `ask_question`.
+Agent question card. Renders when the agent uses the `ask_user` built-in tool and needs a response before continuing. Maps to harness event: `ask_question`.
 
 **Type:** component
 
@@ -355,6 +356,7 @@ Collapsible reasoning block. Supports three display variants: - `"default"` —
   - `"default"`: Expandable card with collapsible reasoning text and duration
   - `"inline"`: Compact single-line display with left accent border
   - `"minimal"`: Pill-shaped status badge
+  - `"ephemeral"`: Single-status row that auto-dismisses after streaming ends. Persists when the user expands it.
 - `isStreaming`: boolean
   Whether reasoning is currently streaming.
 - `duration`: number
@@ -371,6 +373,10 @@ Collapsible reasoning block. Supports three display variants: - `"default"` —
   Custom label override. Defaults to `"Thinking..."` (streaming) or `"Reasoning"` (done). Use to label observational memory blocks: `"Observing..."`, `"Reflecting..."`, etc.
 - `streamingLabel`: string
   Custom streaming label. When provided, used instead of `label` while `isStreaming` is true. Falls back to `label`, then to the default `"Thinking..."`.
+- `dismissDelay`: number
+  For `variant="ephemeral"`: ms to keep the completed row visible before fading out. Set to `0` to disable auto-dismiss.
+- `persist`: boolean
+  For `variant="ephemeral"`: when `true`, the row never auto-dismisses. User-expanded rows are pinned automatically.
 - `className`: string
 - `id`: string
 - `lang`: string
@@ -379,13 +385,13 @@ Collapsible reasoning block. Supports three display variants: - `"default"` —
 
 **Colors (sf tokens used):**
 
-`bg-sf-tint`, `border-sf-line`, `text-sf-subtle`
+`bg-sf-tint`, `border-sf-line`, `text-sf-subtle`, `text-sf-success`
 
 ---
 
 ### AiResponse
 
-Renders AI-generated markdown using Streamdown. Supports streaming animation, syntax-highlighted code, tables, and more.  Pass `isAnimating={true}` while streaming and `false` once complete to get character-by-character reveal animation.
+Renders AI-generated markdown using Streamdown. Supports streaming animation, syntax-highlighted code, tables, and more. Pass `isAnimating={true}` while streaming and `false` once complete to get character-by-character reveal animation.
 
 **Type:** component
 
@@ -487,7 +493,7 @@ AiStreamingText component
 
 ### AiSubagent
 
-Collapsible wrapper for nested subagent activity. Shows the subagent name, status, model, and duration in a header, with all subagent output (text, tool calls, etc.) in a collapsible body.  Maps to harness events: `subagent_start`, `subagent_text_delta`, `subagent_tool_start`, `subagent_tool_end`, `subagent_end`, `subagent_model_changed`.
+Collapsible wrapper for nested subagent activity. Shows the subagent name, status, model, and duration in a header, with all subagent output (text, tool calls, etc.) in a collapsible body. Maps to harness events: `subagent_start`, `subagent_text_delta`, `subagent_tool_start`, `subagent_tool_end`, `subagent_end`, `subagent_model_changed`.
 
 **Type:** component
 
@@ -549,7 +555,7 @@ Horizontally scrollable container for suggestion pills. Position it relative to
 
 ### AiTaskList
 
-Task progress list. Renders structured tasks from the harness `task_write` tool. Typically rendered inside the `PromptInputBackLayer` or inline in conversation.  Maps to harness event: `task_updated`.
+Task progress list. Renders structured tasks from the harness `task_write` tool. Typically rendered inside the `PromptInputBackLayer` or inline in conversation. Maps to harness event: `task_updated`.
 
 **Type:** component
 
@@ -574,13 +580,13 @@ Task progress list. Renders structured tasks from the harness `task_write` tool.
 
 **Colors (sf tokens used):**
 
-`bg-sf-brand`, `bg-sf-danger`, `bg-sf-subtle`, `bg-sf-tint`, `bg-sf-warning`, `text-sf-brand`, `text-sf-default`, `text-sf-subtle`, `text-sf-success`
+`bg-sf-brand`, `bg-sf-danger`, `bg-sf-subtle`, `bg-sf-success`, `bg-sf-tint`, `bg-sf-warning`, `text-sf-default`, `text-sf-subtle`
 
 ---
 
 ### AiTimeline
 
-`AiTimeline` — horizontal swim-lane timeline for commander-level orchestration.  Displays multiple `AiTimelineLane` children on a shared time axis. Supports live updating (a "now" marker follows the live edge), panning, and zoom via `pixelsPerSecond`.
+`AiTimeline` — horizontal swim-lane timeline for commander-level orchestration. Displays multiple `AiTimelineLane` children on a shared time axis. Supports live updating (a "now" marker follows the live edge), panning, and zoom via `pixelsPerSecond`.
 
 **Type:** component
 
@@ -630,6 +636,7 @@ Renders a single tool call. Supports three display variants: - `"default"` — e
   - `"default"`: Expandable card with collapsible input/output sections
   - `"inline"`: Compact single-line display with left accent border
   - `"minimal"`: Pill-shaped status badge
+  - `"ephemeral"`: Single-status row that auto-dismisses after the call completes. Persists on error or when the user expands it.
 - `duration`: number
   Duration in milliseconds.
 - `summary`: string
@@ -640,6 +647,10 @@ Renders a single tool call. Supports three display variants: - `"default"` — e
   Approval state for tools requiring confirmation.
 - `defaultExpanded`: boolean
   Default expanded state for the collapsible.
+- `dismissDelay`: number
+  For `variant="ephemeral"`: ms to keep the completed row visible before fading out. Set to `0` to disable auto-dismiss.
+- `persist`: boolean
+  For `variant="ephemeral"`: when `true`, the row never auto-dismisses. Errors and user-expanded rows are pinned automatically.
 - `className`: string
 - `id`: string
 - `lang`: string
@@ -648,13 +659,13 @@ Renders a single tool call. Supports three display variants: - `"default"` — e
 
 **Colors (sf tokens used):**
 
-`bg-sf-brand`, `bg-sf-danger`, `bg-sf-line`, `bg-sf-recessed`, `bg-sf-success`, `bg-sf-tint`, `bg-sf-warning`, `border-sf-elevated`, `border-sf-line`, `text-sf-brand`, `text-sf-danger`, `text-sf-subtle`, `text-sf-success`, `text-sf-warning`
+`bg-sf-brand`, `bg-sf-danger`, `bg-sf-line`, `bg-sf-recessed`, `bg-sf-subtle`, `bg-sf-success`, `bg-sf-tint`, `bg-sf-warning`, `border-sf-elevated`, `border-sf-line`, `text-sf-brand`, `text-sf-danger`, `text-sf-subtle`, `text-sf-success`, `text-sf-warning`
 
 ---
 
 ### AiUsageBar
 
-Compact token usage display bar. Shows input/output token counts, total, optional cost, and model identifier.  Maps to harness event: `usage_update`.
+Compact token usage display bar. Shows input/output token counts, total, optional cost, and model identifier. Maps to harness event: `usage_update`.
 
 **Type:** component
 
@@ -794,6 +805,7 @@ This is a compound component. Use these sub-components:
 Link sub-component
 
 Props:
+
 - `href`: string (required)
 - `icon`: React.ReactNode
 
@@ -802,6 +814,7 @@ Props:
 Current sub-component
 
 Props:
+
 - `loading`: boolean
 - `icon`: React.ReactNode
 
@@ -814,8 +827,8 @@ Separator sub-component
 Clipboard sub-component
 
 Props:
-- `text`: string (required)
 
+- `text`: string (required)
 
 ---
 
@@ -865,6 +878,7 @@ Primary action trigger. Supports multiple variants, sizes, shapes, icons, and lo
     - `not-disabled`: `not-disabled:hover:border-secondary! not-disabled:hover:bg-sf-control`
     - `disabled`: `disabled:bg-sf-control/50 disabled:!text-sf-danger/70`
     - `data-state`: `data-[state=open]:bg-sf-control`
+
 - `children`: ReactNode
 - `className`: string
 - `icon`: ReactNode
@@ -905,6 +919,7 @@ Checkbox component
   - `"default"`:
     - `focus`: `[&:focus-within>span]:ring-sf-ring`
     - `hover`: `[&:hover>span]:ring-sf-ring`
+
 - `label`: ReactNode
   Label content for the checkbox (enables built-in Field wrapper) - can be a string or any React node
 - `labelTooltip`: ReactNode
@@ -928,7 +943,7 @@ Checkbox component
 
 **Colors (sf tokens used):**
 
-`bg-sf-base`, `bg-sf-contrast`, `border-sf-line`, `ring-sf-contrast`, `ring-sf-danger`, `ring-sf-line`, `ring-sf-ring`, `text-sf-danger`, `text-sf-default`, `text-sf-inverse`, `text-sf-subtle`
+`bg-sf-base`, `bg-sf-contrast`, `border-sf-line`, `ring-sf-contrast`, `ring-sf-danger`, `ring-sf-interact`, `ring-sf-ring`, `text-sf-danger`, `text-sf-default`, `text-sf-inverse`, `text-sf-subtle`
 
 **Styling:**
 
@@ -959,6 +974,7 @@ Item sub-component
 Group sub-component
 
 Props:
+
 - `legend`: string (required)
 - `children`: ReactNode (required)
 - `error`: string
@@ -969,7 +985,6 @@ Props:
 - `controlFirst`: boolean
 - `className`: string
 
-
 ---
 
 ### ClipboardText
@@ -1080,9 +1095,6 @@ Code component
 
 **Styling:**
 
-- **Dimensions:** `[object Object]`
-- **Base Tokens:** `text-sf-default`
-
 **Sub-Components:**
 
 This is a compound component. Use these sub-components:
@@ -1092,15 +1104,15 @@ This is a compound component. Use these sub-components:
 Block sub-component
 
 Props:
+
 - `code`: string (required)
 - `lang`: CodeLang
 
-
 ---
 
 ### Collapsible
 
-Collapsible component for showing/hiding content.  Features: - Animated chevron indicator (rotates 180° when open) - Accessible with aria-expanded and aria-controls - Content panel with left border accent
+Collapsible component for showing/hiding content. Features: - Animated chevron indicator (rotates 180° when open) - Accessible with aria-expanded and aria-controls - Content panel with left border accent
 
 **Type:** component
 
@@ -1128,7 +1140,7 @@ Collapsible component for showing/hiding content.  Features: - Animated chevron
 
 ### Combobox
 
-Combobox — autocomplete input with filterable dropdown list.  Compound component: `Combobox` (Root), `.TriggerInput`, `.TriggerValue`, `.TriggerMultipleWithInput`, `.Content`, `.Item`, `.Chip`, `.Input`, `.Empty`, `.GroupLabel`, `.Group`, `.List`, `.Collection`.
+Combobox — autocomplete input with filterable dropdown list. Compound component: `Combobox` (Root), `.TriggerInput`, `.TriggerValue`, `.TriggerMultipleWithInput`, `.Content`, `.Item`, `.Chip`, `.Input`, `.Empty`, `.GroupLabel`, `.Group`, `.List`, `.Collection`.
 
 **Type:** component
 
@@ -1179,6 +1191,7 @@ This is a compound component. Use these sub-components:
 Content sub-component
 
 Props:
+
 - `className`: string
 - `align`: ComboboxBase.Positioner.Props["align"]
 - `alignOffset`: ComboboxBase.Positioner.Props["alignOffset"]
@@ -1230,9 +1243,11 @@ List sub-component
 Renders filtered list items. Use when you need more control over item rendering.
 
 Props:
+
 - `children`: (item: T, index: number) => ReactNode (required) - Function that receives each filtered item and returns a node
 
 Usage:
+
 ```tsx
 <Combobox.Collection>
   {(item, index) => (
@@ -1243,12 +1258,11 @@ Usage:
 </Combobox.Collection>
 ```
 
-
 ---
 
 ### CommandPalette
 
-CommandPalette — accessible command palette / spotlight search overlay.  Compound component: `CommandPalette.Root` (or `.Dialog` + `.Panel`), `.Input`, `.List`, `.Results`, `.Items`, `.Group`, `.GroupLabel`, `.Item`, `.ResultItem`, `.HighlightedText`, `.Empty`, `.Loading`, `.Footer`.  Built on `@base-ui/react/autocomplete` + `@base-ui/react/dialog`.
+CommandPalette — accessible command palette / spotlight search overlay. Compound component: `CommandPalette.Root` (or `.Dialog` + `.Panel`), `.Input`, `.List`, `.Results`, `.Items`, `.Group`, `.GroupLabel`, `.Item`, `.ResultItem`, `.HighlightedText`, `.Empty`, `.Loading`, `.Footer`. Built on `@base-ui/react/autocomplete` + `@base-ui/react/dialog`.
 
 **Type:** component
 
@@ -1317,12 +1331,11 @@ ColumnToggle sub-component
 
 Empty sub-component
 
-
 ---
 
 ### DatePicker
 
-DatePicker — a date selection calendar.  Built on [react-day-picker](https://daypicker.dev) with SF styling. Supports three selection modes: single, multiple, and range.
+DatePicker — a date selection calendar. Built on [react-day-picker](https://daypicker.dev) with SignalFlare styling. Supports three selection modes: single, multiple, and range.
 
 **Type:** component
 
@@ -1345,7 +1358,7 @@ DatePicker — a date selection calendar.  Built on [react-day-picker](https://d
 
 ### DateRangePicker
 
-DateRangePicker — dual-calendar date range selector.  Renders two side-by-side month calendars with click-to-select start/end dates, hover preview of the range, a timezone footer, and a reset button.
+DateRangePicker — dual-calendar date range selector. Renders two side-by-side month calendars with click-to-select start/end dates, hover preview of the range, a timezone footer, and a reset button.
 
 **Type:** component
 
@@ -1465,12 +1478,11 @@ Description sub-component
 
 Close sub-component
 
-
 ---
 
 ### DropdownMenu
 
-DropdownMenu — accessible dropdown menu anchored to a trigger.  Compound component: `DropdownMenu` (Root), `.Trigger`, `.Content`, `.Item`, `.CheckboxItem`, `.RadioGroup`, `.RadioItem`, `.RadioItemIndicator`, `.Sub`, `.SubTrigger`, `.SubContent`, `.Label`, `.Separator`, `.Shortcut`, `.Group`.  Built on `@base-ui/react/menu`.
+DropdownMenu — accessible dropdown menu anchored to a trigger. Compound component: `DropdownMenu` (Root), `.Trigger`, `.Content`, `.Item`, `.CheckboxItem`, `.RadioGroup`, `.RadioItem`, `.RadioItemIndicator`, `.Sub`, `.SubTrigger`, `.SubContent`, `.Label`, `.Separator`, `.Shortcut`, `.Group`. Built on `@base-ui/react/menu`.
 
 **Type:** component
 
@@ -1552,7 +1564,6 @@ Shortcut sub-component
 
 Group sub-component (wraps DropdownMenuPrimitive)
 
-
 ---
 
 ### Empty
@@ -1625,7 +1636,7 @@ Form field wrapper that provides a label, optional description, and error displa
 
 ### Filters
 
-Filters component for building and managing active filter conditions.  Supports multiple filter types (text, select, multiselect, custom), operators, and an "Add Filter" popover interface. Designed to work standalone or with DataGrid for advanced data filtering.
+Filters component for building and managing active filter conditions. Supports multiple filter types (text, select, multiselect, custom), operators, and an "Add Filter" popover interface. Designed to work standalone or with DataGrid for advanced data filtering.
 
 **Type:** component
 
@@ -1758,7 +1769,7 @@ Input component
 
 ### Label
 
-Label component for form fields.  Provides a standardized way to display labels with optional indicators: - Optional indicator: gray "(optional)" text when `showOptional={true}` - Tooltip: info icon with hover tooltip for additional context
+Label component for form fields. Provides a standardized way to display labels with optional indicators: - Optional indicator: gray "(optional)" text when `showOptional={true}` - Tooltip: info icon with hover tooltip for additional context
 
 **Type:** component
 
@@ -1809,7 +1820,6 @@ LayerCard component
 
 **Styling:**
 
-
 **Sub-Components:**
 
 This is a compound component. Use these sub-components:
@@ -1822,7 +1832,6 @@ Primary sub-component
 
 Secondary sub-component
 
-
 ---
 
 ### Link
@@ -1845,6 +1854,7 @@ Link component
   **State Classes:**
   - `"plain"`:
     - `hover`: `hover:text-primary/70`
+
 - `to`: string
 - `children`: ReactNode
 - `className`: string
@@ -1860,7 +1870,7 @@ Link component
 - `type`: string
 - `referrerPolicy`: enum
 - `render`: ReactNode
-  Allows you to replace the component’s HTML element with a different tag, or compose it with another component.
+  Allows you to replace the component's HTML element with a different tag, or compose it with another component.
 
 Accepts a `ReactElement` or a function that returns the element to render.
 
@@ -1872,7 +1882,6 @@ This is a compound component. Use these sub-components:
 
 ExternalIcon sub-component
 
-
 ---
 
 ### Loader
@@ -1898,7 +1907,7 @@ Animated circular spinner for indicating loading states. Uses CSS keyframe anima
 
 ### MenuBar
 
-MenuBar — horizontal icon-button toolbar with keyboard arrow-key navigation.  Each option renders as a `<button>` with a Tooltip. The active option is visually highlighted with an elevated background.
+MenuBar — horizontal icon-button toolbar with keyboard arrow-key navigation. Each option renders as a `<button>` with a Tooltip. The active option is visually highlighted with an elevated background.
 
 **Type:** component
 
@@ -1923,7 +1932,6 @@ MenuBar — horizontal icon-button toolbar with keyboard arrow-key navigation.
 
 **Styling:**
 
-
 ---
 
 ### Meter
@@ -1993,7 +2001,6 @@ Page navigation controls with page count display.
 
 **Styling:**
 
-
 ---
 
 ### Popover
@@ -2042,7 +2049,6 @@ Description sub-component
 
 Close sub-component
 
-
 ---
 
 ### PromptInput
@@ -2079,13 +2085,13 @@ Prompt input form. Can be self-managed or controlled via `PromptInputProvider`.
 
 **Colors (sf tokens used):**
 
-`bg-sf-base`, `bg-sf-elevated`, `bg-sf-overlay`, `bg-sf-tint`, `ring-sf-line`, `ring-sf-ring`, `text-sf-brand`, `text-sf-default`, `text-sf-inactive`, `text-sf-subtle`
+`bg-sf-base`, `bg-sf-control`, `bg-sf-elevated`, `bg-sf-overlay`, `bg-sf-tint`, `ring-sf-line`, `ring-sf-ring`, `text-sf-brand`, `text-sf-default`, `text-sf-inactive`, `text-sf-subtle`
 
 ---
 
 ### Radio
 
-Radio — radio button group for single-select choices.  Compound component: `Radio.Group` (with built-in Fieldset) and `Radio.Item`. Built on `@base-ui/react/radio-group` + `@base-ui/react/radio`.
+Radio — radio button group for single-select choices. Compound component: `Radio.Group` (with built-in Fieldset) and `Radio.Item`. Built on `@base-ui/react/radio-group` + `@base-ui/react/radio`.
 
 **Type:** component
 
@@ -2118,7 +2124,7 @@ Radio — radio button group for single-select choices.  Compound component: `Ra
 
 **Colors (sf tokens used):**
 
-`bg-sf-base`, `bg-sf-contrast`, `border-sf-line`, `ring-sf-danger`, `ring-sf-line`, `ring-sf-ring`, `text-sf-danger`, `text-sf-default`, `text-sf-subtle`
+`bg-sf-base`, `bg-sf-contrast`, `border-sf-line`, `ring-sf-danger`, `ring-sf-interact`, `ring-sf-ring`, `text-sf-danger`, `text-sf-default`, `text-sf-subtle`
 
 ---
 
@@ -2169,7 +2175,6 @@ Select component
 
 **Styling:**
 
-
 **Sub-Components:**
 
 This is a compound component. Use these sub-components:
@@ -2178,7 +2183,6 @@ This is a compound component. Use these sub-components:
 
 Option sub-component
 
-
 ---
 
 ### SensitiveInput
@@ -2238,7 +2242,7 @@ Password/secret input that masks its value by default and reveals on click. Incl
 
 ### Sidebar
 
-Sidebar — responsive navigation panel with expand/collapse support.  Compound component: `Sidebar` (root `<aside>`), `.Provider`, `.Header`, `.Content`, `.Footer`, `.Group`, `.GroupLabel`, `.GroupContent`, `.Menu`, `.MenuItem`, `.MenuButton`, `.MenuAction`, `.MenuBadge`, `.MenuSub`, `.MenuSubItem`, `.MenuSubButton`, `.Separator`, `.Input`, `.Trigger`, `.Rail`, `.MenuChevron`, `.Collapsible`, `.CollapsibleTrigger`, `.CollapsibleContent`.  Built on `@base-ui/react/collapsible` + `@base-ui/react/dialog`.
+Sidebar — responsive navigation panel with expand/collapse support. Compound component: `Sidebar` (root `<aside>`), `.Provider`, `.Header`, `.Content`, `.Footer`, `.Group`, `.GroupLabel`, `.GroupContent`, `.Menu`, `.MenuItem`, `.MenuButton`, `.MenuAction`, `.MenuBadge`, `.MenuSub`, `.MenuSubItem`, `.MenuSubButton`, `.Separator`, `.Input`, `.Trigger`, `.Rail`, `.MenuChevron`, `.Collapsible`, `.CollapsibleTrigger`, `.CollapsibleContent`. Built on `@base-ui/react/collapsible` + `@base-ui/react/dialog`.
 
 **Type:** component
 
@@ -2282,7 +2286,6 @@ Sidebar — responsive navigation panel with expand/collapse support.  Compound
 
 **Styling:**
 
-
 **Sub-Components:**
 
 This is a compound component. Use these sub-components:
@@ -2292,6 +2295,7 @@ This is a compound component. Use these sub-components:
 Provider sub-component
 
 Props:
+
 - `defaultOpen`: boolean
 - `open`: boolean
 - `variant`: SidebarVariant
@@ -2396,7 +2400,6 @@ CollapsibleTrigger sub-component
 
 CollapsibleContent sub-component
 
-
 ---
 
 ### SignalFlareAILogo
@@ -2674,6 +2677,60 @@ SignalFlare AI logo component.
 
 ---
 
+### Sparkline
+
+Sparkline — a tiny inline chart intended for embedding in cards, tables, or row-level cells. Renders without axes, grid, or legend by default.
+
+**Type:** component
+
+**Import:** `import { Sparkline } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `className`: string
+  Additional CSS classes
+- `children`: ReactNode
+  Child elements
+
+---
+
+### StatCard
+
+StatCard — compact KPI tile displaying a label, a primary value, and an optional delta + trend sparkline.
+
+**Type:** component
+
+**Import:** `import { StatCard } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `size`: enum [default: base]
+  Size of the card. Defaults to `"base"`.
+- `label`: ReactNode
+  Short descriptive label (e.g. `"Active users"`).
+- `value`: ReactNode
+  Primary value to emphasise (pre-formatted).
+- `hint`: ReactNode
+  Optional secondary text displayed under the value.
+- `delta`: StatCardDelta
+  Optional change indicator (arrow + number + label).
+- `trend`: ReactNode
+  Optional content slot rendered on the right-hand side — typically a `Sparkline` showing the metric's trend.
+- `loading`: boolean
+  When `true`, renders a skeleton placeholder in place of value + delta.
+- `className`: string
+  Additional CSS classes merged via `cn()`.
+
+**Colors (sf tokens used):**
+
+`bg-sf-elevated`, `bg-sf-fill`, `text-sf-danger`, `text-sf-default`, `text-sf-strong`, `text-sf-subtle`, `text-sf-success`
+
+---
+
 ### Surface
 
 Surface component
@@ -2756,6 +2813,7 @@ Item sub-component
 Group sub-component
 
 Props:
+
 - `legend`: string (required)
 - `children`: ReactNode (required)
 - `error`: string
@@ -2764,12 +2822,11 @@ Props:
 - `controlFirst`: boolean
 - `className`: string
 
-
 ---
 
 ### Table
 
-Table — semantic HTML table with styled rows, cells, and selection support.  Compound component: `Table` (Root), `.Header`, `.Head`, `.Body`, `.Row`, `.Cell`, `.Footer`, `.CheckCell`, `.CheckHead`, `.ResizeHandle`.
+Table — semantic HTML table with styled rows, cells, and selection support. Compound component: `Table` (Root), `.Header`, `.Head`, `.Body`, `.Row`, `.Cell`, `.Footer`, `.CheckCell`, `.CheckHead`, `.ResizeHandle`.
 
 **Type:** component
 
@@ -2834,7 +2891,6 @@ Footer sub-component
 
 ResizeHandle sub-component
 
-
 ---
 
 ### Tabs
@@ -2877,7 +2933,6 @@ Tab navigation component with segmented, underline, or pill style. Built on Base
 
 **Styling:**
 
-
 ---
 
 ### Text
@@ -2920,12 +2975,40 @@ Text component
 
 **Styling:**
 
+---
+
+### TextRoll
+
+Letter-by-letter roll animation. Each character flips on the X axis: the current letter rolls up and out, the new letter rolls in from below. Good for title changes (e.g. a streaming activity group swapping its current-step label) where the text content is short and the change should register visually. Wraps the string in an `aria-hidden` visual stack with a screen-reader-only copy of the full text so a11y tools always read the real content.
+
+**Type:** component
+
+**Import:** `import { TextRoll } from "@signalflare-ai/ui";`
+
+**Category:** Other
+
+**Props:**
+
+- `children`: string (required)
+  Text to animate. Each character rolls in / out independently.
+- `duration`: number
+  Duration (seconds) of each letter's enter and exit tween.
+- `getEnterDelay`: object
+  Per-letter delay for the enter animation.
+- `getExitDelay`: object
+  Per-letter delay for the exit animation.
+- `className`: string
+  Additional CSS classes merged via `cn()`. Use sf semantic tokens only.
+- `transition`: Transition
+  Shared transition for both enter and exit tweens.
+- `variants`: TextRollVariants
+  Override the default rotate-X roll with custom enter/exit variants.
 
 ---
 
 ### ThemeToggle
 
-Theme toggle button. Cycles through light → dark → system (follows OS) modes.  Reads from and writes to `localStorage` under the key `"theme"`. When set to `"system"` the key is removed so the OS preference takes over automatically. Applies the resolved mode to `document.documentElement.dataset.mode`.
+Theme toggle button. Cycles through light → dark → system (follows OS) modes. Reads from and writes to `localStorage` under the key `"theme"`. When set to `"system"` the key is removed so the OS preference takes over automatically. Applies the resolved mode to `document.documentElement.dataset.mode`.
 
 **Type:** component
 
@@ -2954,7 +3037,7 @@ Theme toggle button. Cycles through light → dark → system (follows OS) modes
 
 ### Toasty
 
-Toasty — toast notification provider and viewport.  Renders a `Toast.Provider` with a fixed-position viewport in the bottom-right corner. Toasts stack with smooth enter/exit animations, swipe-to-dismiss, and expand-on-hover.  Built on `@base-ui/react/toast`.
+Toasty — toast notification provider and viewport. Renders a `Toast.Provider` with a fixed-position viewport in the bottom-right corner. Toasts stack with smooth enter/exit animations, swipe-to-dismiss, and expand-on-hover. Built on `@base-ui/react/toast`.
 
 **Type:** component
 
@@ -2979,7 +3062,6 @@ Toasty — toast notification provider and viewport.  Renders a `Toast.Provider`
 
 **Styling:**
 
-
 ---
 
 ### Tooltip
@@ -3024,7 +3106,6 @@ Multi-line textarea input with Input variants and InputArea-specific dimensions
 
 **Props:**
 
-
 **Styling:**
 
 - **Size Variants:**
@@ -3036,7 +3117,8 @@ Multi-line textarea input with Input variants and InputArea-specific dimensions
 ## Quick Reference
 
 **Components by Category:**
-- **Other:** AiActions, AiAgentCard, AiApproval, AiCodeBlock, AiConversation, AiInfoBanner, AiLoader, AiMessage, AiMissionHeader, AiQuestion, AiReasoning, AiResponse, AiShimmer, AiStatusBadge, AiStreamingText, AiSubagent, AiSuggestions, AiTaskList, AiTimeline, AiToolCall, AiUsageBar, DataGrid, DatePicker, Filters, Label, Link, PromptInput, SensitiveInput, Sidebar, SignalFlareAILogo, Table, ThemeToggle, AgentHarness, Commander, DeleteResource, Map
+
+- **Other:** AiActions, AiAgentCard, AiApproval, AiCodeBlock, AiConversation, AiInfoBanner, AiMessage, AiMissionHeader, AiPartGroup, AiQuestion, AiReasoning, AiResponse, AiShimmer, AiStatusBadge, AiStreamingText, AiSubagent, AiSuggestions, AiTaskList, AiTimeline, AiToolCall, AiUsageBar, DataGrid, DatePicker, Filters, Label, Link, PromptInput, SensitiveInput, Sidebar, SignalFlareAILogo, Sparkline, StatCard, Table, TextRoll, ThemeToggle, AgentHarness, Commander, DashboardGrid, DeleteResource, Map, MetricsOverview
 - **Display:** Badge, Breadcrumbs, Code, Collapsible, Empty, LayerCard, Meter, Text
 - **Feedback:** Banner, Loader, Toasty
 - **Action:** Button, ClipboardText