@flamingo-stack/openframe-frontend-core 0.0.213 → 0.0.214-snapshot.20260528192313

package/src/stories/.PageContainer.stories.md

@@ -1,44 +1,50 @@
-<!-- source-hash: 20b9937080b2caa3584f87d4ae933cfe -->
-Storybook stories configuration for the PageContainer component, showcasing various layouts and usage patterns for different page types in the application.
+<!-- source-hash: f72131cedcde7906c303bc3ea8538959 -->
+Storybook stories for the `PageContainer` layout component, covering legacy and advanced usage variants including list, detail, form, and content page layouts.
 
 ## Key Components
 
-- **Meta Configuration** - Storybook metadata with interactive controls for variant, padding, background, and header visibility
-- **Story Variants** - Comprehensive examples including legacy, list, detail, form, and content page layouts
-- **PlaceholderContent** - Reusable component for demonstrating page content areas
-- **Interactive Controls** - Argtype definitions for testing different component configurations
+- **`Legacy`** — Basic container with full-width background and no structured header
+- **`LegacyCustomBackground`** / **`LegacyContentWidthBackground`** — Legacy mode with custom background and content-width options
+- **`ListPage`** / **`ListPageMultipleActions`** — List variant with title, subtitle, and action buttons
+- **`DetailPage`** / **`DetailPageWithActions`** — Detail variant with back button navigation and optional actions
+- **`FormPage`** — Form variant with cancel/save/publish actions
+- **`ContentPage`** — Generic content layout variant
+- **`CustomHeaderContent`** / **`WithHeaderActions`** / **`HiddenHeader`** — Header customization stories
+- **`WithPaddingAndBackground`** — Demonstrates `padding` and `background` prop combinations
+
+## Storybook Controls
+
+| Control | Options |
+|---------|---------|
+| `variant` | `list`, `detail`, `form`, `content` |
+| `padding` | `none`, `sm`, `md`, `lg` |
+| `background` | `default`, `card`, `transparent` |
+| `showHeader` | `boolean` |
 
 ## Usage Example
 
 ```typescript
-// Basic list page story
-export const ListPage: Story = {
-  args: {
-    variant: 'list',
-    title: 'Devices',
-    subtitle: '24 devices found',
-    actions: [
-      { 
-        label: 'Add Device', 
-        onClick: () => {}, 
-        icon: <Plus className="w-5 h-5" />, 
-        variant: 'primary' 
-      },
-    ],
-    children: <PlaceholderContent />,
-  },
-};
+// List page with actions
+<PageContainer
+  variant="list"
+  title="Devices"
+  subtitle="24 devices found"
+  actions={[
+    { label: 'Add Device', onClick: handleAdd, icon: <Plus />, variant: 'primary' }
+  ]}
+>
+  <DeviceTable />
+</PageContainer>
 
 // Detail page with back navigation
-export const DetailPage: Story = {
-  args: {
-    variant: 'detail',
-    title: 'Device Details',
-    subtitle: 'MacBook Pro — Online',
-    backButton: { label: 'Back to Devices', onClick: () => {} },
-    children: <PlaceholderContent />,
-  },
-};
-```
-
-The stories demonstrate legacy mode compatibility, advanced variants (list, detail, form, content), header customization options, and various padding/background combinations. Each story includes realistic props and content to showcase the PageContainer's flexibility across different application contexts.
+<PageContainer
+  variant="detail"
+  title="Device Details"
+  backButton={{ label: 'Back to Devices', onClick: handleBack }}
+  actions={[
+    { label: 'Delete', onClick: handleDelete, variant: 'outline' }
+  ]}
+>
+  <DeviceDetails />
+</PageContainer>
+```

package/src/stories/.PageLayout.stories.md

@@ -0,0 +1,60 @@
+<!-- source-hash: 3e5784b9b627d4143a0bac991ef6fb48 -->
+Storybook stories for the `PageLayout` component, covering all major layout variants including title-only, subtitle/image combinations, mobile responsive behavior, and action button configurations.
+
+## Key Components
+
+| Export | Description |
+|--------|-------------|
+| `TitleOnly` | Minimal header with title and content only |
+| `WithSubtitleAndImage` | Full organization detail header with back button, thumbnail, subtitle, and icon-button actions |
+| `MobileActionsMenu` | Same as `WithSubtitleAndImage` at mobile viewport — actions collapse to `…` dropdown |
+| `WithSubtitleOnly` | Title + one-line context note with primary-button actions |
+| `WithImageOnly` | Branded entity header without a subtitle line |
+| `WithSelector` | Desktop tab selector (table/grid toggle) rendered before action buttons |
+| `WithSelectorMobile` | `WithSelector` at mobile viewport — selector hidden, only `…` dropdown remains |
+| `LongTitleTruncates` | Verifies ellipsis truncation when title/subtitle overflow the header |
+
+## Usage Example
+
+```typescript
+// Minimal usage
+<PageLayout title="Devices">
+  <Table data={devices} columns={columns} rowKey="id" />
+</PageLayout>
+
+// Full organization detail page
+<PageLayout
+  title="TechFlow Solutions"
+  subtitle="techflow.com • Software Development"
+  image={{ src: logoSrc, alt: 'TechFlow logo' }}
+  backButton={{ label: 'Back to Organizations', onClick: handleBack }}
+  actionsVariant="icon-buttons"
+  actions={[
+    { label: 'Archive Organization', onClick: handleArchive, variant: 'outline', icon: <BoxArchiveIcon size={24} /> },
+    { label: 'Edit Organization',    onClick: handleEdit,    variant: 'outline', icon: <PenEditIcon size={24} />    },
+  ]}
+>
+  <Table data={devices} columns={columns} rowKey="id" />
+</PageLayout>
+
+// With desktop tab selector (hidden on mobile)
+<PageLayout
+  title="Devices"
+  actionsVariant="icon-buttons"
+  actions={[{ label: 'Add Device', onClick: fn(), variant: 'outline', icon: <PlusCircleIcon size={24} /> }]}
+  selector={
+    <TabSelector
+      value={view}
+      onValueChange={setView}
+      items={[
+        { id: 'table', label: '', icon: <TableCellIcon size={24} /> },
+        { id: 'grid',  label: '', icon: <GridLayoutIcon size={24} /> },
+      ]}
+    />
+  }
+>
+  <Table data={devices} columns={columns} rowKey="id" />
+</PageLayout>
+```
+
+**`actionsVariant` options:** `icon-buttons` (labeled outline buttons → `…` menu on mobile), `primary-buttons` (always visible primary buttons), `menu-primary` (menu trigger with primary style).

package/src/stories/.ParallaxImageShowcase.stories.md

@@ -0,0 +1,49 @@
+<!-- source-hash: bc3b7f6794a8e489c9fce54c9abbaeb4 -->
+Storybook stories for the `ParallaxImageShowcase` component, covering layout variants, parallax intensity levels, shadow options, and partial image configurations using inline SVG placeholder images.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `meta` | `Meta` | Storybook metadata — registers component under `Features/ParallaxImageShowcase` with controls for `layout`, `intensity`, and `shadow` |
+| `makePlaceholder` | Helper | Generates an SVG data URI mimicking a screenshot UI with sidebar, panels, and a centered label |
+| `images` | Fixture | Three placeholder images with `left`, `center`, and `right` position assignments |
+| `NonBoxed` | `Story` | Default overlapping layer layout |
+| `Boxed` | `Story` | Two-row layout with optional `logoElement` slot |
+| `Grid` | `Story` | Three-column grid layout |
+| `SubtleIntensity` / `HighIntensity` | `Story` | Parallax motion range demos (`0.3` → `5`) |
+| `GridWithShadow` / `GridHighIntensity` | `Story` | Grid layout with shadow and intensity combinations |
+| `TwoImages` / `SingleImage` | `Story` | Edge-case coverage for reduced image counts |
+
+## Usage Example
+
+```typescript
+import { ParallaxImageShowcase } from '../components/features/parallax-image-showcase'
+
+// Minimal usage with three positioned images
+<ParallaxImageShowcase
+  layout="non-boxed"
+  intensity={1.5}
+  shadow={false}
+  images={[
+    { src: '/screenshots/dashboard.png', alt: 'Dashboard', position: 'left' },
+    { src: '/screenshots/analytics.png', alt: 'Analytics', position: 'center' },
+    { src: '/screenshots/settings.png',  alt: 'Settings',  position: 'right' },
+  ]}
+/>
+
+// Boxed layout with a logo slot
+<ParallaxImageShowcase
+  layout="boxed"
+  images={images}
+  logoElement={<img src="/logo.svg" alt="Logo" />}
+/>
+```
+
+## Controls Reference
+
+| Prop | Control | Values |
+|------|---------|--------|
+| `layout` | select | `non-boxed` · `boxed` · `grid` |
+| `intensity` | number slider | `0` – `10`, step `0.1` |
+| `shadow` | boolean toggle | `true` / `false` |

package/src/stories/.PhoneInput.stories.md

@@ -0,0 +1,53 @@
+<!-- source-hash: 1e78827c6bdbb029fe4aeac35f0fdda1 -->
+Storybook stories for the `PhoneInput` UI component, demonstrating various states, country configurations, and layout scenarios.
+
+## Key Components
+
+### `PhoneInputControlled`
+Internal stateful wrapper that manages `phone`, `country`, and `isInvalid` state, wiring up all `PhoneInput` callbacks and rendering an inline validation warning when the number is invalid.
+
+### Exported Stories
+
+| Story | Description |
+|---|---|
+| `Default` | US country code, empty value |
+| `UnitedKingdom` | Pre-selected GB country code |
+| `WithValue` | Pre-filled US number `(555) 123-4567` |
+| `Disabled` | Disabled input with a pre-filled value |
+| `CustomPlaceholder` | Custom placeholder text `"Enter phone..."` |
+| `NarrowContainer` | 300px container to verify overflow handling |
+| `Germany` | Pre-selected DE country code |
+
+## Usage Example
+
+```typescript
+// Replicate the controlled pattern from stories in your own component
+import { PhoneInput } from '@/components/ui/phone-input';
+import { useState } from 'react';
+import type { CountryCode } from 'libphonenumber-js';
+
+function MyForm() {
+  const [phone, setPhone] = useState('');
+  const [country, setCountry] = useState<CountryCode>('US');
+  const [isInvalid, setIsInvalid] = useState(false);
+
+  return (
+    <>
+      <PhoneInput
+        value={phone}
+        countryCode={country}
+        onPhoneChange={setPhone}
+        onCountryChange={setCountry}
+        onValidationChange={setIsInvalid}
+      />
+      {isInvalid && <p>Invalid phone number</p>}
+    </>
+  );
+}
+```
+
+## Notes
+
+- Stories are scoped under the `UI/PhoneInput` Storybook path.
+- All stories use `PhoneInputControlled` via the `render` override rather than Storybook's default args rendering, ensuring live state management within the canvas.
+- Country codes follow the [`libphonenumber-js`](https://www.npmjs.com/package/libphonenumber-js) `CountryCode` type.

package/src/stories/.QueryReportTable.stories.md

@@ -0,0 +1,44 @@
+<!-- source-hash: 30d7c4e87b438b12b503725269f756f6 -->
+Storybook stories for the `QueryReportTable` component, covering all major display states, configuration options, and edge cases for visual testing and documentation.
+
+## Key Components
+
+- **`Default`** — Basic table with auto-derived columns from data keys
+- **`Loading`** — Skeleton placeholder state with configurable rows/columns
+- **`Empty`** — Empty state with a custom message
+- **`CustomColumnOrder`** — Explicit column ordering with remaining keys appended
+- **`WideColumns` / `NarrowColumns`** — Column width variants (`columnWidth` prop)
+- **`ManyColumns`** — Horizontal scroll with right-edge gradient fade using a 14-column dataset
+- **`NoExport`** — Hides the CSV export button (`showExport: false`)
+- **`CustomExport`** — Custom filename and `onExport` callback
+- **`WithHeaderActions`** — Renders additional controls (e.g. Refresh button) in the table header
+- **`WithNullValues`** — Displays `null` fields as dashes
+- **`SingleRow`** — Single-record result set
+
+## Usage Example
+
+```typescript
+import { QueryReportTable } from '../components/ui/query-report-table'
+
+<QueryReportTable
+  title="Server Health Report"
+  data={[
+    { hostname: 'prod-web-01', cpu_usage: 45, status: 'healthy' },
+  ]}
+  columnOrder={['status', 'hostname', 'cpu_usage']}
+  columnWidth={160}
+  exportFilename="server-health-2026-02"
+  onExport={() => console.log('Exported')}
+  headerActions={<Button variant="outline">Refresh</Button>}
+/>
+```
+
+## ArgTypes (Storybook Controls)
+
+| Prop | Control | Range |
+|---|---|---|
+| `columnWidth` | number | 80–400, step 10 |
+| `skeletonRows` | number | 1–20 |
+| `skeletonColumns` | number | 1–12 |
+| `showExport` | boolean | — |
+| `loading` | boolean | — |

package/src/stories/.RadioGroup.stories.md

@@ -0,0 +1,46 @@
+<!-- source-hash: 708dc6fe37c97945e4c968bc3a3e4867 -->
+Storybook stories for the `RadioGroup` UI component, demonstrating all supported variants, states, and theme configurations within the OpenFrame design system.
+
+## Key Components
+
+| Export | Description |
+|---|---|
+| `Default` | Basic radio group with three unselected options |
+| `WithDefaultValue` | Uncontrolled group with a pre-selected option via `defaultValue` |
+| `Disabled` | Entire group disabled with a pre-selected value |
+| `DisabledItem` | Group with a single item disabled while others remain interactive |
+| `Horizontal` | Horizontal layout using `orientation="horizontal"` with flex-row styling |
+| `Controlled` | Controlled component using `useState` with live selection display |
+| `FlamingoTheme` | Group wrapped in `data-app-type="flamingo"` decorator for Flamingo-branded styling |
+
+## Usage Example
+
+```typescript
+import { RadioGroup, RadioGroupItem } from '../components/ui/radio-group';
+import { useState } from 'react';
+
+// Uncontrolled with default selection
+<RadioGroup defaultValue="option-1">
+  <div className="flex items-center gap-3">
+    <RadioGroupItem value="option-1" id="opt-1" />
+    <label htmlFor="opt-1">Option 1</label>
+  </div>
+  <div className="flex items-center gap-3">
+    <RadioGroupItem value="option-2" id="opt-2" />
+    <label htmlFor="opt-2">Option 2</label>
+  </div>
+</RadioGroup>
+
+// Controlled
+const [value, setValue] = useState('option-1');
+<RadioGroup value={value} onValueChange={setValue}>
+  <RadioGroupItem value="option-1" id="opt-1" />
+  <RadioGroupItem value="option-2" id="opt-2" />
+</RadioGroup>
+```
+
+## Notes
+
+- Built on **Radix UI** primitives with OpenFrame design tokens (`ods-text-primary`, `ods-text-secondary`)
+- The `renderItem` helper ensures consistent label/input pairing across all stories
+- Use `data-app-type="flamingo"` on a parent wrapper to activate Flamingo-specific theme overrides

package/src/stories/.RadioGroupBlock.stories.md

@@ -0,0 +1,45 @@
+<!-- source-hash: af0e39e63f288e66b45ccc927c98cf2a -->
+Storybook stories for the `RadioGroupBlock` component, covering all visual states, variants, and interactive behaviors for the ODS design system's bordered radio group.
+
+## Key Components
+
+- **`Default`** — Basic radio group with no pre-selected value
+- **`WithDefaultValue`** — Pre-selected option via `defaultValue`
+- **`WithDescriptions`** — Options with descriptive sub-text (e.g., pricing tiers)
+- **`Disabled`** / **`DisabledItem`** — Whole group or individual option disabled
+- **`Error`** — Group with inline validation error message
+- **`Controlled`** — Controlled component with `useState` showing selected value
+- **`AllStates`** — Combined showcase of selected, disabled, error, and description states
+- **`DevicePricing`** / **`DevicePricingDisabled`** — `grouped` variant with trailing `Tag` discount badges, modeled after Figma device-pricing picker
+- **`Grouped`** — `grouped` variant with dividers, no trailing slot (billing period example)
+- **`FlamingoTheme`** — Same group rendered inside a `data-app-type="flamingo"` container for theme verification
+
+## Usage Example
+
+```typescript
+// Controlled usage with grouped variant and trailing slots
+import { RadioGroupBlock } from '../components/ui/radio-group';
+import { Tag } from '../components/ui/tag';
+
+<RadioGroupBlock
+  name="pricing"
+  variant="grouped"
+  defaultValue="300"
+  options={[
+    {
+      value: '100',
+      label: '100 devices',
+      description: '$5,400/year',
+      trailing: <Tag variant="success" label="-10%" />,
+    },
+    {
+      value: '300',
+      label: '300 devices',
+      description: '$14,400/year',
+      trailing: <Tag variant="success" label="-20%" />,
+    },
+  ]}
+/>
+```
+
+**Configurable `argTypes`:** `defaultValue`, `value`, `disabled`, `error`, `variant` (`separated` | `grouped`), `onValueChange`. All stories render at `400px` width via a shared decorator.

package/src/stories/.Select.stories.md

@@ -1,22 +1,26 @@
-<!-- source-hash: a57080f2d4d37dc92f1ae1d4fa84a3d1 -->
-Storybook stories file demonstrating the Select component and its various states and configurations for the OpenFrame UI library.
+<!-- source-hash: 57929b92378079c47ade3983e6429cff -->
+Storybook stories for the `Select` UI component, showcasing all variants and states including grouped items, validation, disabled states, and `FieldWrapper` integration.
 
 ## Key Components
 
-- **Meta Configuration** - Storybook metadata with title, component reference, layout parameters, and custom decorator
-- **Story Variants** - Seven different stories showcasing select functionality:
-  - `Default` - Basic select with placeholder
-  - `WithValue` - Pre-selected value example
-  - `Disabled` - Non-interactive disabled state
-  - `WithGroups` - Categorized options with labels and separators
-  - `WithDisabledItem` - Individual disabled items within options
-  - `ManyItems` - Scrollable list with timezone options
-  - `AllVariants` - Side-by-side comparison view
+| Story | Description |
+|---|---|
+| `Default` | Basic select with placeholder text |
+| `WithValue` | Select with a pre-selected default value |
+| `Disabled` | Non-interactive disabled state |
+| `WithGroups` | Grouped items with `SelectLabel` and `SelectSeparator` |
+| `WithDisabledItem` | Select with individual disabled option |
+| `ManyItems` | Scrollable list (25 UTC timezones) |
+| `Invalid` | Error/invalid visual state via `invalid` prop on `SelectTrigger` |
+| `WithLabel` | Wrapped in `FieldWrapper` with a label |
+| `WithLabelAndError` | `FieldWrapper` with label and error message |
+| `WithLabelAndValue` | `FieldWrapper` with a pre-selected value |
+| `AllVariants` | All states rendered together for comparison |
 
 ## Usage Example
 
 ```typescript
-// Basic select implementation
+// Basic usage
 <Select>
   <SelectTrigger>
     <SelectValue placeholder="Select an option..." />
@@ -27,7 +31,7 @@ Storybook stories file demonstrating the Select component and its various states
   </SelectContent>
 </Select>
 
-// Grouped select with categories
+// With grouped items
 <Select>
   <SelectTrigger>
     <SelectValue placeholder="Select a fruit..." />
@@ -44,6 +48,16 @@ Storybook stories file demonstrating the Select component and its various states
     </SelectGroup>
   </SelectContent>
 </Select>
-```
 
-The stories use a custom decorator that provides consistent styling with padding, background color using CSS custom properties (`--ods-bg`), and a maximum width constraint for optimal visual presentation in Storybook.
+// With validation via FieldWrapper
+<FieldWrapper label="Role" error="Please select a role">
+  <Select>
+    <SelectTrigger invalid>
+      <SelectValue placeholder="Select a role..." />
+    </SelectTrigger>
+    <SelectContent>
+      <SelectItem value="viewer">Viewer</SelectItem>
+    </SelectContent>
+  </Select>
+</FieldWrapper>
+```

package/src/stories/.SlashCommandSuggestions.stories.md

@@ -0,0 +1,41 @@
+<!-- source-hash: 1c7447069bb7b63321514a5ef06052ac -->
+Storybook stories for the `SlashCommandSuggestions` chat autocomplete component, providing visual test cases for the `/`-triggered command dropdown used in the Flamingo/OpenFrame chat interface.
+
+## Key Components
+
+### Stories
+
+| Story | Description |
+|-------|-------------|
+| `Default` | Full command list with the first row statically highlighted |
+| `Interactive` | Live hover-driven highlight via `useState`, mimics keyboard navigation |
+| `FilteredSingle` | Single result row, simulates typing `/road` to filter |
+| `NoActions` | Hides action chips when `onAction` is `undefined`, row becomes click-only |
+
+### Sample Data (`SAMPLE_COMMANDS`)
+
+14 `SlashCommandSummary` entries covering all production `/api/docs/commands` sources: ClickUp (`roadmap`, `delivery`), GitHub (`commits`, `pull-requests`, `pr-reviews`), Slack (`slack`), and OpenFrame content types (`docs`, `blogs`, `releases`, `case-studies`, `getting-started`, `webinars`, `events`, `podcasts`). Each entry includes `iconName` keys wired to the `resolveOnboardingIcon` registry.
+
+## Usage Example
+
+```typescript
+// Render the interactive story manually outside Storybook
+import { SlashCommandSuggestions } from '../components/chat/slash-command-suggestions'
+import { useState } from 'react'
+
+export function Demo() {
+  const [idx, setIdx] = useState(0)
+
+  return (
+    <SlashCommandSuggestions
+      commands={SAMPLE_COMMANDS}
+      highlightedIdx={idx}
+      onHover={setIdx}
+      onSelect={(cmd) => console.log('selected:', cmd.id)}
+      onAction={(cmd, actionId) => console.log('action:', cmd.id, actionId)}
+    />
+  )
+}
+```
+
+The decorator wraps every story in a `640px` container with a mock chat input row below, replicating the `absolute bottom-full` anchor behavior of the real `ChatInput` component.

package/src/stories/.SplitButton.stories.md

@@ -0,0 +1,62 @@
+<!-- source-hash: b262c529e121e8f3f9e9aa107480cd1a -->
+Storybook stories for the `SplitButton` component, showcasing all supported variants, sizes, states, and icon configurations for visual testing and documentation.
+
+## Key Components
+
+| Export | Description |
+|--------|-------------|
+| `Accent` | Default accent variant with external link icon action |
+| `Outline` | Outline variant with new-tab icon action |
+| `Transparent` | Transparent variant with new-tab icon action |
+| `Destructive` | Destructive variant with trash icon and overflow menu |
+| `SizeSmall` | Small size variant demonstration |
+| `AsLink` | Button rendered as an anchor (`href`) with icon action |
+| `WithLeftIcon` | Main button with a left-side icon and dropdown action |
+| `Disabled` | Fully disabled state for the entire component |
+| `IconActionDisabled` | Only the secondary icon action is disabled |
+| `AllVariants` | Grid showcasing all 4 variants × default/disabled × default/small sizes |
+| `TwoActions` | Composite example combining link navigation and dropdown actions |
+
+## Usage Example
+
+```typescript
+import { SplitButton } from '../components/ui/button'
+import { FloppyDiscIcon as Save, Chevron01DownIcon as ChevronDown } from '../components/icons-v2-generated'
+
+// Main action button with a secondary icon action
+<SplitButton
+  variant="accent"
+  leftIcon={<Save />}
+  onClick={() => handleSave()}
+  iconAction={{
+    icon: <ChevronDown />,
+    'aria-label': 'More save options',
+    onClick: () => openMenu(),
+  }}
+>
+  Save
+</SplitButton>
+
+// Rendered as a link with external open icon action
+<SplitButton
+  variant="outline"
+  href="/docs"
+  iconAction={{
+    icon: <ExternalLink />,
+    'aria-label': 'Open in new tab',
+    href: '/docs',
+    openInNewTab: true,
+  }}
+>
+  Documentation
+</SplitButton>
+```
+
+## Controls
+
+| Prop | Type | Options |
+|------|------|---------|
+| `variant` | select | `accent`, `outline`, `transparent`, `destructive` |
+| `size` | select | `default`, `small` |
+| `fullWidth` | boolean | — |
+| `disabled` | boolean | — |

package/src/stories/.TabNavigation.stories.md

@@ -1,45 +1,54 @@
-<!-- source-hash: 8a90b2a3ce7aa3caab122dc39d6ddec4 -->
-Storybook stories for the TabNavigation component demonstrating various usage patterns including controlled state management, URL synchronization, and visual indicators.
+<!-- source-hash: 03e4c838723c464e0642fcd3805a327d -->
+Storybook stories for the `TabNavigation` component, covering controlled state, URL synchronization, status indicators, overflow scroll shadows, and custom styling variants.
 
 ## Key Components
 
-- **defaultTabs**: Basic tab configuration with Home, Users, Settings, and Notifications
-- **tabsWithIndicators**: Extended tab set including status indicators (success, warning, error)
-- **Controlled**: Standard controlled component story with local state management
-- **WithContent**: Demonstrates children render prop pattern for tab content
-- **WithIndicators**: Shows tabs with visual status indicators
-- **UrlSync**: URL parameter synchronization using default "tab" param
-- **UrlSyncCustomParam**: Custom URL parameter name and replace state behavior
+**Exported Stories**
+
+| Story | Description |
+|---|---|
+| `Controlled` | Basic controlled mode with `activeTab` + `onTabChange` |
+| `WithContent` | Children render prop displaying active tab content |
+| `WithIndicators` | Tabs with `success`, `warning`, and `error` indicator badges |
+| `UrlSync` | Active tab driven by a `?tab=` URL search parameter |
+| `UrlSyncCustomParam` | URL sync with a custom param name (`section`) and `replaceState` |
+| `TwoTabs` | Minimal two-tab layout |
+| `DefaultTabOverride` | Pre-selects a non-first tab on mount |
+| `CustomClassName` | Custom Tailwind class on the tab container |
+| `ScrollShadows` | 15 tabs in a constrained width to trigger fade scroll shadows |
+| `CustomShadowColor` | Overrides scroll shadow gradient via `shadowClassName` |
+| `ShadowOnCustomBackground` | Shadow color matched to a custom card background |
+| `NoShadows` | Two tabs that fit without overflow — shadows never appear |
+
+**Fixture Data**
+- `defaultTabs` — 4 tabs (Overview, Users, Settings, Notifications)
+- `tabsWithIndicators` — 5 tabs with mixed `success`/`warning`/`error` indicators
+- `manyTabs` — 15 tabs used for overflow/scroll stories
 
 ## Usage Example
 
 ```typescript
-// Basic controlled tab navigation
-const [activeTab, setActiveTab] = useState('overview');
-
-<TabNavigation
-  tabs={defaultTabs}
-  activeTab={activeTab}
-  onTabChange={setActiveTab}
-/>
-
-// With status indicators and content
-<TabNavigation
-  tabs={tabsWithIndicators}
-  activeTab={activeTab}
-  onTabChange={setActiveTab}
->
-  {(activeTab) => (
-    <div>Content for {activeTab}</div>
-  )}
-</TabNavigation>
-
-// URL synchronized tabs
-<TabNavigation
-  tabs={defaultTabs}
-  urlSync={{ paramName: 'section', replaceState: true }}
-  defaultTab="overview"
-/>
-```
-
-The stories cover all major interaction patterns including two-tab layouts, default tab overrides, and custom styling through className props.
+// Controlled tab navigation with status indicators
+import { TabNavigation, TabItem } from '../components/ui/tab-navigation';
+import { useState } from 'react';
+import { Home, Settings } from 'lucide-react';
+
+const tabs: TabItem[] = [
+  { id: 'home', label: 'Home', icon: Home, indicator: 'success' },
+  { id: 'settings', label: 'Settings', icon: Settings, indicator: 'warning' },
+];
+
+export function MyPage() {
+  const [active, setActive] = useState('home');
+  return (
+    <TabNavigation
+      tabs={tabs}
+      activeTab={active}
+      onTabChange={setActive}
+      shadowClassName="from-ods-card"
+    >
+      {(activeTab) => <div>Viewing: {activeTab}</div>}
+    </TabNavigation>
+  );
+}
+```