@flamingo-stack/openframe-frontend-core 0.0.213 → 0.0.214

package/src/stories/.TabSelector.stories.md

@@ -0,0 +1,65 @@
+<!-- source-hash: eea14186773eb206e54d1ffb8e785935 -->
+Storybook stories for the `TabSelector` UI component, showcasing all supported variants, states, and composition patterns.
+
+## Key Components
+
+### Exported Stories
+
+| Story | Description |
+|-------|-------------|
+| `Primary` | Accent background on active tab (default variant) |
+| `Secondary` | Soft grey background on active tab |
+| `FiveTabs` | Full 5-tab layout matching Figma spec |
+| `WithIcons` | Tabs with Lucide icon prefixes |
+| `WithLabel` | Optional label rendered above the selector |
+| `WithDisabled` | Single tab disabled via `disabled` item property |
+| `Disabled` | Entire selector disabled via top-level `disabled` prop |
+| `TwoTabs` | Minimal two-tab configuration |
+| `PlatformExample` | Real-world OS platform picker with icons and label |
+| `VariantComparison` | Side-by-side `accent` vs `secondary` rendering |
+| `WithBadges` | Tabs with badge slots (e.g., "Soon" pill on Enterprise) |
+
+### `TabSelectorItem` Shape
+
+```typescript
+interface TabSelectorItem {
+  id: string;
+  label: string;
+  icon?: React.ReactNode;
+  disabled?: boolean;
+  badge?: React.ReactNode;
+}
+```
+
+## Usage Example
+
+```typescript
+import { TabSelector, type TabSelectorItem } from '../components/ui/tab-selector';
+import { useState } from 'react';
+
+const platforms: TabSelectorItem[] = [
+  { id: 'windows', label: 'Windows', icon: <Monitor className="w-5 h-5" /> },
+  { id: 'macos',   label: 'macOS',   icon: <Apple   className="w-5 h-5" /> },
+  { id: 'linux',   label: 'Linux',   icon: <Globe   className="w-5 h-5" />, disabled: true },
+];
+
+export function PlatformPicker() {
+  const [platform, setPlatform] = useState('macos');
+
+  return (
+    <TabSelector
+      label="Select Platform"
+      variant="primary"       // 'primary' | 'secondary'
+      value={platform}
+      onValueChange={setPlatform}
+      items={platforms}
+    />
+  );
+}
+```
+
+## Notes
+
+- All stories use a controlled `useState` render function to ensure interactive tab switching works correctly in Storybook.
+- The decorator wraps every story in a `600px` wide container to match typical usage contexts.
+- Badge content accepts any `React.ReactNode`, allowing custom pills, icons, or counters per tab.

package/src/stories/.Table.stories.md

@@ -1,56 +1,48 @@
-<!-- source-hash: 388b6c7933a0ee25057051f55e9ab1f1 -->
-A comprehensive Storybook configuration file that demonstrates various Table component use cases through interactive stories, including responsive column visibility, sorting, filtering, and different layout patterns optimized for different screen sizes.
+<!-- source-hash: b88a597eb0e06d6c5293430c95a28ff3 -->
+Storybook stories for the `Table` UI component, demonstrating all supported features including sorting, filtering, selection, responsive column visibility, loading/empty states, and row actions.
 
 ## Key Components
 
-**Interface Definitions:**
-- `User` - Sample data structure representing user records
-- `sampleUsers` - Mock dataset with 5 user records for story examples
-
-**Story Exports:**
-- `Basic` - Standard table with essential columns
-- `ResponsiveColumns` - Progressive column disclosure based on screen size
-- `MultipleBreakpoints` - Complex breakpoint hiding with array-based configuration
-- `Loading` - Skeleton state with configurable row count
-- `Empty` - No data state with custom messaging
-- `Selectable` - Row selection functionality
-- `Sortable` - Column sorting capabilities
-- `Clickable` - Interactive row click handling
-- `MobileFirst` - Mobile-optimized progressive enhancement
-- `TabletOptimized` - Tablet-specific column visibility for interactive elements
+- **`Basic`** — Minimal table with static columns, no interactivity
+- **`ResponsiveColumns`** — Progressive column disclosure using `hideAt` breakpoints (`sm`, `md`, `lg`, `xl`)
+- **`MultipleBreakpoints`** — `hideAt` accepting an array of breakpoints for granular visibility control
+- **`Loading`** — Skeleton row state via `loading: true` and `skeletonRows`
+- **`Empty`** — Empty state with custom `emptyMessage`
+- **`Selectable`** — Row selection with `selectable` and `selectedRows` props
+- **`Sortable`** — Column sorting via `sortable`, `sortBy`, and `sortDirection` props
+- **`Clickable`** / **`ClickableWithActions`** — Row click handlers with optional inline `rowActions`
+- **`MobileFirst`** — Mobile-optimized layout with progressive column reveal
+- **`TabletOptimized`** — Tablet-focused layout showing only sortable/filterable columns at 768–1024px
+- **`WithFilters`** — Stateful story using `useState` to drive `filterable` columns with `filterOptions`
 
 ## Usage Example
 
 ```typescript
-// Basic responsive table story
-export const ResponsiveColumns: Story = {
-  args: {
-    data: sampleUsers,
-    columns: [
-      { key: 'name', label: 'Name' },
-      { key: 'email', label: 'Email' },
-      { key: 'role', label: 'Role', hideAt: 'sm' },
-      { key: 'status', label: 'Status', hideAt: 'md' }
-    ] as TableColumn<User>[],
-    rowKey: 'id'
-  }
-}
+import { Table, type TableColumn, type TableFilters } from '../components/ui/table'
 
-// Table with filtering and sorting
-export const TabletOptimized: Story = {
-  args: {
-    columns: [
-      { key: 'name', label: 'Name', sortable: true },
-      { 
-        key: 'status', 
-        label: 'Status', 
-        filterable: true,
-        filterOptions: [
-          { id: 'active', label: 'Active', value: 'active' }
-        ]
-      }
+const columns: TableColumn<User>[] = [
+  { key: 'name', label: 'Name', sortable: true },
+  { key: 'email', label: 'Email', hideAt: 'sm' },
+  {
+    key: 'status',
+    label: 'Status',
+    filterable: true,
+    filterOptions: [
+      { id: 'active', label: 'Active', value: 'active' },
+      { id: 'inactive', label: 'Inactive', value: 'inactive' },
     ],
-    onFilterChange: (filters) => console.log(filters)
-  }
-}
+  },
+]
+
+<Table
+  data={users}
+  columns={columns}
+  rowKey="id"
+  sortBy="name"
+  sortDirection="asc"
+  selectable
+  selectedRows={[]}
+  onFilterChange={(filters: TableFilters) => console.log(filters)}
+  rowActions={[{ label: 'Edit', variant: 'outline', onClick: (item) => console.log(item) }]}
+/>
 ```

package/src/stories/.TableColumnFilterDropdown.stories.md

@@ -0,0 +1,46 @@
+<!-- source-hash: e750ae57313642f731dcbf7079870828 -->
+Storybook stories for the `TableColumnFilterDropdown` component, demonstrating a compact filter icon button used in table column headers with checkbox-based filtering options.
+
+## Key Components
+
+- **`Default`** — Base state with no active filters; icon renders subtly
+- **`WithActiveFilters`** — Pre-selected filters (`active`, `inactive`) causing the icon to highlight with accent color
+- **`InTableHeaderContext`** — Decorates the story inside a styled table header row for visual context
+- **`MultipleColumns`** — Side-by-side Status and Type filter dropdowns sharing a single `TableFilters` state via `useState`
+- **`Interactive`** — Fully stateful story showing real-time filter selection feedback
+
+## Usage Example
+
+```typescript
+import { TableColumnFilterDropdown } from '../components/ui/table/table-column-filter-dropdown'
+import type { FilterOption, TableFilters } from '../components/ui/table/types'
+
+const statusOptions: FilterOption[] = [
+  { id: 'active', label: 'Active', value: 'active' },
+  { id: 'inactive', label: 'Inactive', value: 'inactive' },
+]
+
+function TableHeader() {
+  const [filters, setFilters] = useState<TableFilters>({})
+
+  return (
+    <div className="flex items-center gap-2">
+      <span>Status</span>
+      <TableColumnFilterDropdown
+        columnKey="status"
+        columnLabel="Status"
+        filterOptions={statusOptions}
+        filters={filters}
+        onFilterChange={setFilters}
+        placement="bottom-start"
+      />
+    </div>
+  )
+}
+```
+
+## Notes
+
+- `placement` prop accepts `bottom-start`, `bottom-end`, or `bottom` (controllable via Storybook select)
+- The filter icon highlights automatically when `filters[columnKey]` contains active selections
+- `onFilterChange` receives the full updated `TableFilters` object, making it suitable for shared multi-column filter state

package/src/stories/.Tag.stories.md

@@ -1,41 +1,52 @@
-<!-- source-hash: 51def75df74b17c99fb886c2e1837a96 -->
-Storybook configuration file that defines interactive stories and documentation for the Tag UI component. This file showcases all available variants, states, and configurations of the Tag component with live examples and controls.
+<!-- source-hash: 6142d73d82bfcb3ba377d2f80cb29999 -->
+Storybook stories for the `Tag` UI component, covering all visual variants, icon/close button combinations, disabled states, and composite showcase renders.
 
 ## Key Components
 
-- **meta**: Storybook configuration object defining the component title, controls, and argument types
-- **Story variants**: Individual stories demonstrating each tag variant (primary, outline, success, warning, error, critical, grey)
-- **Feature stories**: Examples showcasing icons, close buttons, and combined functionality
-- **Collection stories**: Grouped displays showing all variants together for comparison
+| Export | Description |
+|--------|-------------|
+| `Primary` | Default primary variant |
+| `Outline` | Outline/bordered variant |
+| `Success` / `Warning` / `Error` / `Critical` / `Grey` | Semantic status variants |
+| `WithIcon` | Tag with a leading icon |
+| `WithCloseButton` | Tag with dismissible close handler |
+| `WithIconAndClose` | Tag combining icon and close button |
+| `Disabled` / `AllDisabled` | Disabled state across all variants |
+| `AllVariants` | Showcase of every variant side-by-side |
+| `AllWithIcons` | All variants with icons |
+| `AllWithClose` | All variants with close buttons |
+| `AllWithIconAndClose` | All variants with both icon and close |
+| `DisabledWithIconAndClose` | Disabled state with full feature set |
 
 ## Usage Example
 
 ```typescript
-// Individual variant story
-export const Primary: Story = {
-  args: { variant: 'primary', children: 'Tag' },
-};
-
-// Story with interactive features
-export const WithIconAndClose: Story = {
-  args: {
-    variant: 'success',
-    children: 'Tag',
-    icon: <Smile className="size-5" />,
-    onClose: () => alert('close'),
-  },
-};
-
-// Custom render function for grouped display
-export const AllVariants: Story = {
-  render: () => (
-    <div className="flex flex-wrap gap-3">
-      <Tag variant="primary">Primary</Tag>
-      <Tag variant="outline">Outline</Tag>
-      {/* ... other variants */}
-    </div>
-  ),
-};
+import { Tag } from '../components/ui/tag';
+import { Smile } from 'lucide-react';
+
+// Basic variant
+<Tag variant="success" label="Active" />
+
+// With icon
+<Tag variant="primary" label="Category" icon={<Smile className="size-5" />} />
+
+// Dismissible
+<Tag variant="warning" label="Pending" onClose={() => handleRemove()} />
+
+// Full featured
+<Tag
+  variant="error"
+  label="Failed"
+  icon={<Smile className="size-5" />}
+  onClose={() => handleRemove()}
+  disabled={false}
+/>
 ```
 
-The stories provide a comprehensive testing and documentation environment for the Tag component, allowing developers to interact with different configurations and see visual examples of all available options.
+## Variants
+
+The `Tag` component supports 7 variants controlled via the Storybook `select` control:
+
+```text
+primary | outline | success | warning | error | critical | grey
+```

package/src/stories/.TagKeyValueFilter.stories.md

@@ -0,0 +1,44 @@
+<!-- source-hash: 2efd92dbc250ad80e5820ff475ea0636 -->
+Storybook stories for `TagKeyValueFilter` and related UI components, demonstrating tag-based filtering workflows across standalone, combined, and modal contexts.
+
+## Key Components
+
+| Export | Description |
+|---|---|
+| `Standalone` | Basic `TagKeyValueFilter` with live selection display |
+| `WithPreselected` | Filter initialized with pre-selected `key:value` tag strings |
+| `WithTagSearchInput` | Combined `TagSearchInput` + `TagKeyValueFilter` for a full search-and-filter workflow |
+| `InsideFilterModal` | `TagKeyValueFilter` embedded inside `FilterModal` alongside standard filter groups |
+| `FilterModalTagsOnly` | `FilterModal` with only tag filters and no regular filter groups |
+
+**Sample data shapes used across stories:**
+- `sampleKeys` — `TagKeyConfig[]` covering `site`, `env`, `os`, and `role` dimensions with associated value counts
+- `sampleFilterGroups` — `FilterGroup[]` for a standard `Status` filter group
+
+## Usage Example
+
+```typescript
+// Standalone controlled usage
+const [tags, setTags] = useState<string[]>([]);
+
+<TagKeyValueFilter
+  keys={sampleKeys}           // TagKeyConfig[] — key/value tree
+  selectedTags={tags}         // string[] in "key:value" format
+  onTagsChange={setTags}
+/>
+
+// Inside FilterModal with mixed filter groups
+<FilterModal
+  isOpen={isOpen}
+  onClose={() => setIsOpen(false)}
+  filterGroups={sampleFilterGroups}
+  currentFilters={filters}
+  onFilterChange={setFilters}
+  tagFilterKeys={sampleKeys}
+  selectedTags={tags}
+  onTagsChange={setTags}
+  tagFilterTitle="Device Tags"
+/>
+```
+
+> Tags follow the `"key:value"` string format (e.g., `"site:chicago"`, `"env:production"`). All stories use controlled state via React's `useState`.

package/src/stories/.TagSearchInput.stories.md

@@ -0,0 +1,61 @@
+<!-- source-hash: 39e74029d3a13eedba8671d2a0c9a8f5 -->
+Storybook stories for the `TagSearchInput` UI component, covering all interactive states and layout behaviors including overflow, tag limits, and disabled mode.
+
+## Key Components
+
+**Exported Stories**
+
+| Story | Description |
+|---|---|
+| `Empty` | No tags, bare search input |
+| `WithTags` | A few tags fitting on one line |
+| `OverflowWithBadge` | Many tags triggering the automatic `+N` overflow badge |
+| `Resizable` | Drag-to-resize container demonstrating dynamic `+N` badge recalculation |
+| `NarrowContainer` | Narrow container collapsing all tags into `+N` |
+| `Disabled` | Non-interactive disabled state |
+| `WithSubmit` | Press Enter to add typed values as tags |
+| `LimitTags` | Hard cap of 2 visible tags via `limitTags` prop |
+| `NoClearAll` | Hides the clear-all button via `showClearAll={false}` |
+| `AllVariants` | All states rendered together for visual comparison |
+
+**Sample Data**
+
+- `sampleTags` — 3 tags (`site`, `env` prefixes)
+- `manyTags` — 8 tags across multiple prefixes (`site`, `env`, `os`, `role`, `team`, `region`, `status`)
+
+## Usage Example
+
+```typescript
+import { TagSearchInput, TagSearchOption } from '../components/ui/tag-search-input';
+import { useState } from 'react';
+
+const tags: TagSearchOption[] = [
+  { label: 'site:chicago', value: 'site:chicago' },
+  { label: 'env:production', value: 'env:production' },
+];
+
+function Example() {
+  const [activeTags, setActiveTags] = useState(tags);
+  const [search, setSearch] = useState('');
+
+  return (
+    <TagSearchInput
+      tags={activeTags}
+      searchValue={search}
+      onSearchChange={setSearch}
+      onTagRemove={(val) =>
+        setActiveTags((t) => t.filter((x) => x.value !== val))
+      }
+      onClearAll={() => { setActiveTags([]); setSearch(''); }}
+      onSubmit={(val) => {
+        if (val.trim()) {
+          setActiveTags((t) => [...t, { label: val, value: val }]);
+          setSearch('');
+        }
+      }}
+      limitTags={3}
+      placeholder="Search devices..."
+    />
+  );
+}
+```

package/src/stories/.Textarea.stories.md

@@ -1,33 +1,56 @@
-<!-- source-hash: 74738542f0c031ba8ae22f9b94866314 -->
-Storybook configuration file that defines interactive documentation and testing scenarios for the Textarea UI component, including various states like disabled, invalid, and custom sizing options.
+<!-- source-hash: ab03748717bd50a809cf19a269adcb31 -->
+Storybook stories for the `Textarea` UI component, covering all interactive states, variants, and compositional patterns used across the Flamingo/OpenFrame platform.
 
 ## Key Components
 
-- **meta**: Main Storybook configuration object with component metadata, controls, and decorators
-- **Story variants**: Multiple story exports demonstrating different textarea states and configurations
-- **argTypes**: Control definitions for interactive property manipulation in Storybook UI
-- **decorators**: Custom wrapper providing consistent styling and layout for all stories
+| Export | Description |
+|--------|-------------|
+| `Default` | Basic textarea with placeholder text |
+| `WithValue` | Pre-filled textarea using `defaultValue` |
+| `Disabled` / `DisabledWithValue` | Read-only disabled states |
+| `CustomRows` | Textarea with a configurable `rows` count |
+| `NoResize` | Fixed-height textarea via `!resize-none` class |
+| `Invalid` | Error/invalid visual state |
+| `WithLabel` | Textarea paired with a label |
+| `WithLabelAndError` | Label + inline validation error message |
+| `WithErrorOnly` | Validation error without a label |
+| `AllVariants` | Side-by-side comparison of all variants |
+
+## Configurable ArgTypes
+
+| Arg | Type | Description |
+|-----|------|-------------|
+| `placeholder` | `text` | Hint text shown when empty |
+| `disabled` | `boolean` | Prevents user interaction |
+| `invalid` | `boolean` | Applies error styling |
+| `rows` | `number` | Visible row height |
 
 ## Usage Example
 
 ```typescript
-// Basic story definition
-export const Default: Story = {
-  args: {
-    placeholder: 'Enter description...',
-  },
-}
-
-// Complex story with custom render function
-export const AllVariants: Story = {
-  render: () => (
-    <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
-      <Textarea placeholder="Default textarea" />
-      <Textarea defaultValue="With pre-filled value" />
-      <Textarea placeholder="Disabled" disabled />
-    </div>
-  ),
-}
-```
-
-The file exports 8 different story variants including `Default`, `WithValue`, `Disabled`, `CustomRows`, `NoResize`, `Invalid`, and `AllVariants` for comprehensive component testing. Each story demonstrates specific textarea functionality like error states, disabled states, custom row counts, and resize behavior. The stories support interactive controls for `placeholder`, `disabled`, `invalid`, and `rows` properties through Storybook's args system.
+import { Textarea } from '@/components/ui/textarea'
+
+// Basic usage
+<Textarea placeholder="Enter description..." />
+
+// With label and validation error
+<Textarea
+  label="Description"
+  placeholder="Enter description..."
+  error="Description is required"
+  invalid
+/>
+
+// Disabled with pre-filled content
+<Textarea
+  defaultValue="This content is read-only."
+  disabled
+/>
+
+// Fixed height, no resize
+<Textarea
+  placeholder="Fixed height..."
+  rows={8}
+  className="!resize-none"
+/>
+```

package/src/stories/.Theme.stories.md

@@ -0,0 +1,41 @@
+<!-- source-hash: a1cf673720fb7e195d055604da5c8efd -->
+Storybook stories for the ODS (OpenFrame Design System) theme system, demonstrating light/dark theme switching, design token visualization, and component behavior across themes.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `Showcase` | Story | Full-page demo with theme toggle, color token grid, and all UI components |
+| `ToggleOnly` | Story | Minimal copy-paste reference showing `ThemeProvider` + `useThemeToggle()` integration |
+| `SideBySide` | Story | Forced side-by-side light/dark panels using `.theme-light`/`.theme-dark` class escapes |
+| `ThemeToggleButton` | Helper | Toggle button built on `useThemeToggle()` with Sun/Moon icons |
+| `ThemeStatusBar` | Helper | Status bar showing current theme with explicit `setTheme('light' | 'dark')` controls |
+| `TokenGrid` | Helper | Visual swatches for all `--ods-*` surface, text, accent, status, and border tokens |
+| `ComponentsShowcase` | Helper | Renders Buttons, Inputs, Badges, Cards, and Alerts against the active theme |
+| `Swatch` | Helper | Single color swatch rendering a Tailwind token class with its label |
+
+## Usage Example
+
+```typescript
+// Wrap once with ThemeProvider; consume useThemeToggle() anywhere inside
+import { ThemeProvider, useThemeToggle } from '../components/providers/theme-provider'
+
+function MyToggle() {
+  const { isDark, toggle, mounted } = useThemeToggle()
+  return (
+    <button onClick={toggle}>
+      {mounted ? (isDark ? 'Switch to light' : 'Switch to dark') : 'Toggle theme'}
+    </button>
+  )
+}
+
+export default function App() {
+  return (
+    <ThemeProvider>
+      <MyToggle />
+    </ThemeProvider>
+  )
+}
+```
+
+> **How it works:** `ThemeProvider` (wrapping `next-themes`) sets `data-theme="light|dark"` on `<html>`. The `src/styles/ods-colors.css` file swaps all `--ods-*` primitive values accordingly — components only read tokens and are theme-unaware.

package/src/stories/.TicketAttachmentsList.stories.md

@@ -0,0 +1,39 @@
+<!-- source-hash: ddd9ad67dd51d76015bd6c722cee21e2 -->
+Storybook stories for the `TicketAttachmentsList` component, covering view-only file attachment list rendering across multiple attachment states.
+
+## Key Components
+
+- **`Default`** — Three mixed-format attachments (PNG, SVG, MP4) with download handlers
+- **`SingleFile`** — Minimal single PDF attachment scenario
+- **`NoDownload`** — Read-only attachment without a download action callback
+- **`Empty`** — Zero-attachment edge case rendering
+
+## Usage Example
+
+```typescript
+import { TicketAttachmentsList } from '../components/ui/ticket-attachments-list';
+
+// Basic usage with download handlers
+<TicketAttachmentsList
+  attachments={[
+    { id: '1', fileName: 'report.pdf', fileSize: '2.3 MB', onDownload: () => handleDownload('1') },
+    { id: '2', fileName: 'screenshot.png', fileSize: '512 KB', onDownload: () => handleDownload('2') },
+  ]}
+/>
+
+// Read-only, no download action
+<TicketAttachmentsList
+  attachments={[
+    { id: '1', fileName: 'readonly-file.txt', fileSize: '128 KB' },
+  ]}
+/>
+```
+
+## Attachment Item Shape
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | `string` | ✅ | Unique attachment identifier |
+| `fileName` | `string` | ✅ | Displayed file name with extension |
+| `fileSize` | `string` | ✅ | Human-readable size label |
+| `onDownload` | `() => void` | ❌ | Download action; omit for read-only |

package/src/stories/.TicketDescriptionViewer.stories.md

@@ -0,0 +1,39 @@
+<!-- source-hash: 70e0ec1bd6faabbc539fcfb3af28cb70 -->
+Storybook stories for the `TicketDescriptionViewer` component, providing visual test cases for rendering ticket description content in various formats (plain text, HTML, code, and empty states).
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `meta` | `Meta` | Storybook metadata — mounts component at `Tickets/TicketDescriptionViewer` with a 600px wrapper |
+| `PlainText` | `Story` | Plain text with line breaks |
+| `HtmlContent` | `Story` | Rich HTML with headings, lists, blockquotes |
+| `WithCode` | `Story` | Inline and block `<code>` / `<pre>` elements |
+| `Empty` | `Story` | Empty string fallback rendering |
+
+## Usage Example
+
+```typescript
+import { TicketDescriptionViewer } from '../components/ui/ticket-description-viewer';
+
+// Plain text
+<TicketDescriptionViewer content="Reduce onboarding from 4 weeks to 10 days." />
+
+// HTML from RichTextEditor output
+<TicketDescriptionViewer content="<h2>Steps</h2><ul><li>Setup</li></ul>" />
+
+// Empty state
+<TicketDescriptionViewer content="" />
+```
+
+## Story Overview
+
+```mermaid
+graph TD
+    meta["TicketDescriptionViewer Stories"] --> PlainText["PlainText\n(line-break text)"]
+    meta --> HtmlContent["HtmlContent\n(headings, lists, blockquote)"]
+    meta --> WithCode["WithCode\n(pre + code blocks)"]
+    meta --> Empty["Empty\n(empty string)"]
+```
+
+> All stories render inside a 600px-wide decorator div to simulate a realistic ticket detail panel width, matching the expected `RichTextEditor` output environment.

package/src/stories/.TicketInfoSection.stories.md

@@ -0,0 +1,40 @@
+<!-- source-hash: 82f8ca355b8119e08afe608bf0b4cf05 -->
+Storybook stories for the `TicketInfoSection` component, covering collapsed, expanded, interactive, and minimal display states of the collapsible ticket info bar.
+
+## Key Components
+
+- **`Collapsed`** — Default header-only view showing organization, user, device, and status fields
+- **`Expanded`** — Fully populated view with description, attachments, tags, knowledge base articles, and notes
+- **`Interactive`** — Stateful story demonstrating expand/collapse toggle with `useState`, device click handler, and note CRUD callbacks
+- **`Minimal`** — Expanded state with all fields set to "Unassigned", useful for empty-state validation
+
+## Usage Example
+
+```typescript
+import { TicketInfoSection } from '../components/ui/ticket-info-section';
+
+// Basic collapsed header
+<TicketInfoSection
+  organization={{ name: 'Acme Corp' }}
+  user="John Doe"
+  device={{ name: 'WIN-SERVER-01', icon: <Monitor className="size-4" /> }}
+  status="TECH_REQUIRED"
+  expanded={false}
+/>
+
+// Expanded with notes and attachments
+<TicketInfoSection
+  organization={{ name: 'Acme Corp' }}
+  user="John Doe"
+  device={{ name: 'WIN-SERVER-01' }}
+  status="ACTIVE"
+  expanded={true}
+  notes={mockNotes}
+  attachments={mockAttachments}
+  knowledgeBaseArticles={mockArticles}
+  tags={['Client-onboarding']}
+  onAddNote={(text) => console.log('Add note:', text)}
+  onEditNote={(id) => console.log('Edit note:', id)}
+  onDeleteNote={(id) => console.log('Delete note:', id)}
+/>
+```