@flamingo-stack/openframe-frontend-core 0.0.212 → 0.0.213-snapshot.20260528174436

package/src/nats/shared-connection.ts

@@ -0,0 +1,285 @@
+import { createNatsClient, type NatsClient, type NatsStatus, type NatsStatusEvent } from './nats'
+
+export const NATS_DEFAULTS = {
+  SHARED_CLOSE_DELAY_MS: 3000,
+  CONNECT_TIMEOUT_MS: 10_000,
+  PING_INTERVAL_MS: 30_000,
+  MAX_PING_OUT: 3,
+  RETRY_INITIAL_DELAY_MS: 1000,
+  RETRY_MAX_DELAY_MS: 30_000,
+  RETRY_MULTIPLIER: 2,
+} as const
+
+export interface NatsReconnectionBackoff {
+  /** Number of fast retries before exponential phase kicks in. Default: 0. */
+  fastRetries?: number
+  /** Delay used during the fast-retry phase. Default: RETRY_INITIAL_DELAY_MS. */
+  fastRetryDelayMs?: number
+  /** Base delay for the exponential phase. Default: RETRY_INITIAL_DELAY_MS. */
+  initialDelayMs?: number
+  /** Upper cap on any single retry delay. Default: RETRY_MAX_DELAY_MS. */
+  maxDelayMs?: number
+  /** Per-attempt multiplier during exponential phase. Default: RETRY_MULTIPLIER. */
+  multiplier?: number
+}
+
+export interface SharedConnection {
+  wsUrl: string
+  client: NatsClient
+  connectPromise: Promise<void> | null
+  refCount: number
+  closeTimer: ReturnType<typeof setTimeout> | null
+  retryTimer: ReturnType<typeof setTimeout> | null
+  /**
+   * Identity of the consumer driving reconnect. When set, other consumers
+   * should observe status only and skip their own scheduleRetry — otherwise
+   * each disconnect triggers multiple concurrent connect() calls racing over
+   * connectPromise.
+   */
+  retryOwner: object | null
+}
+
+export interface AcquireClientOptions {
+  name?: string
+  user?: string
+  pass?: string
+  connectTimeoutMs?: number
+  pingIntervalMs?: number
+  maxPingOut?: number
+}
+
+export interface ReleaseClientOptions {
+  delayMs?: number
+}
+
+let shared: SharedConnection | null = null
+
+export function getSharedConnection(): SharedConnection | null {
+  return shared
+}
+
+export function acquireClient(url: string, opts?: AcquireClientOptions): SharedConnection {
+  if (shared?.wsUrl !== url) {
+    if (shared) {
+      if (shared.closeTimer) clearTimeout(shared.closeTimer)
+      const old = shared
+      shared = null
+      void old.client.close().catch(() => {})
+    }
+
+    const {
+      name = 'openframe-frontend',
+      user = 'machine',
+      pass = '',
+      connectTimeoutMs = NATS_DEFAULTS.CONNECT_TIMEOUT_MS,
+      pingIntervalMs = NATS_DEFAULTS.PING_INTERVAL_MS,
+      maxPingOut = NATS_DEFAULTS.MAX_PING_OUT,
+    } = opts ?? {}
+
+    const client = createNatsClient({
+      servers: url,
+      name,
+      user,
+      pass,
+      connectTimeoutMs,
+      reconnect: false,
+      pingIntervalMs,
+      maxPingOut,
+    })
+
+    shared = {
+      wsUrl: url,
+      client,
+      connectPromise: null,
+      refCount: 0,
+      closeTimer: null,
+      retryTimer: null,
+      retryOwner: null,
+    }
+  }
+
+  shared.refCount += 1
+  if (shared.closeTimer) {
+    clearTimeout(shared.closeTimer)
+    shared.closeTimer = null
+  }
+  return shared
+}
+
+export function releaseClient(url: string, opts?: ReleaseClientOptions): void {
+  if (!shared || shared.wsUrl !== url) return
+
+  shared.refCount = Math.max(0, shared.refCount - 1)
+  if (shared.refCount > 0) return
+
+  const delay = opts?.delayMs ?? NATS_DEFAULTS.SHARED_CLOSE_DELAY_MS
+  shared.closeTimer = setTimeout(() => {
+    const s = shared
+    shared = null
+    if (s) {
+      if (s.retryTimer) {
+        clearTimeout(s.retryTimer)
+        s.retryTimer = null
+      }
+      void s.client.close().catch(() => {})
+    }
+  }, delay)
+}
+
+export function getSharedConnectionFor(url: string | null | undefined): SharedConnection | null {
+  if (!url) return null
+  return shared && shared.wsUrl === url ? shared : null
+}
+
+// ---------------------------------------------------------------------------
+// Connection lifecycle: retry + status loop, shared by NatsProvider and the
+// chat hooks. Each consumer that wants to drive reconnect creates an
+// ownerToken and calls startConnectionLifecycle(). The first caller to claim
+// retryOwner runs the actual retry loop; subsequent claimants observe status
+// only. When the owner unmounts and releases retryOwner, the next status
+// event lets a surviving consumer pick up ownership opportunistically.
+// ---------------------------------------------------------------------------
+
+export interface ConnectionLifecycleOptions {
+  conn: SharedConnection
+  wsUrl: string
+  onBeforeReconnect?: () => Promise<void> | void
+  backoff?: NatsReconnectionBackoff
+  getFreshUrl: () => string | null
+  /** Called on every status change (after closed-guard). */
+  onStatusChange?: (status: NatsStatus, evt: NatsStatusEvent) => void
+  /**
+   * Decide which statuses should trigger a retry attempt. Defaults to closed +
+   * disconnected. Override to skip 'error' (JetStream protocol errors that
+   * don't close the WS) or include it.
+   */
+  shouldRetryOn?: (status: NatsStatus) => boolean
+}
+
+export interface ConnectionLifecycleHandle {
+  /** Stop observing status, clear any pending retry, release ownership if held. */
+  stop(): void
+}
+
+const defaultShouldRetryOn = (status: NatsStatus) => status === 'closed' || status === 'disconnected'
+
+export function startConnectionLifecycle(options: ConnectionLifecycleOptions): ConnectionLifecycleHandle {
+  const { conn, wsUrl } = options
+  // Each lifecycle gets its own identity for retry ownership. The first lifecycle to claim
+  // an unowned connection drives reconnect; later attachers observe status only until the
+  // owner releases (see opportunistic claim in scheduleRetry).
+  const ownerToken = {}
+  if (!conn.retryOwner) conn.retryOwner = ownerToken
+
+  let closed = false
+  let retryAttempt = 0
+
+  function emitSynthetic(status: NatsStatus) {
+    if (closed) return
+    options.onStatusChange?.(status, { status })
+    if (status === 'connected') {
+      retryAttempt = 0
+    }
+  }
+
+  function scheduleRetry() {
+    if (closed) return
+    if (getSharedConnectionFor(wsUrl) !== conn) return
+    if (!conn.retryOwner) conn.retryOwner = ownerToken
+    if (conn.retryOwner !== ownerToken) return
+
+    if (conn.retryTimer) {
+      clearTimeout(conn.retryTimer)
+      conn.retryTimer = null
+    }
+
+    const cfg = options.backoff ?? {}
+    const fastRetries = cfg.fastRetries ?? 0
+    const fastDelay = cfg.fastRetryDelayMs ?? NATS_DEFAULTS.RETRY_INITIAL_DELAY_MS
+    const baseDelay = cfg.initialDelayMs ?? NATS_DEFAULTS.RETRY_INITIAL_DELAY_MS
+    const maxDelay = cfg.maxDelayMs ?? NATS_DEFAULTS.RETRY_MAX_DELAY_MS
+    const multiplier = cfg.multiplier ?? NATS_DEFAULTS.RETRY_MULTIPLIER
+
+    const delay =
+      retryAttempt < fastRetries
+        ? fastDelay
+        : Math.min(baseDelay * multiplier ** (retryAttempt - fastRetries), maxDelay)
+    const jitteredDelay = delay * (0.5 + Math.random() * 0.5)
+    retryAttempt++
+
+    conn.retryTimer = setTimeout(async () => {
+      conn.retryTimer = null
+      if (closed) return
+      if (getSharedConnectionFor(wsUrl) !== conn) return
+
+      try {
+        await options.onBeforeReconnect?.()
+      } catch {
+        // continue regardless of token-refresh outcome
+      }
+      if (closed) return
+      if (getSharedConnectionFor(wsUrl) !== conn) return
+
+      const freshUrl = options.getFreshUrl()
+      if (freshUrl !== wsUrl) return
+
+      try {
+        conn.connectPromise = null
+        conn.connectPromise = conn.client.connect()
+        await conn.connectPromise
+        if (!closed && getSharedConnectionFor(wsUrl) === conn) {
+          retryAttempt = 0
+        }
+      } catch {
+        conn.connectPromise = null
+        if (!closed && getSharedConnectionFor(wsUrl) === conn) {
+          scheduleRetry()
+        }
+      }
+    }, jitteredDelay)
+  }
+
+  const shouldRetryOn = options.shouldRetryOn ?? defaultShouldRetryOn
+
+  const unsubStatus = conn.client.onStatus((evt) => {
+    if (closed) return
+    options.onStatusChange?.(evt.status, evt)
+    if (evt.status === 'connected') {
+      retryAttempt = 0
+    }
+    if (shouldRetryOn(evt.status)) {
+      scheduleRetry()
+    }
+  })
+
+  if (conn.client.isConnected()) {
+    emitSynthetic('connected')
+  }
+
+  void (async () => {
+    try {
+      conn.connectPromise ||= conn.client.connect()
+      await conn.connectPromise
+    } catch {
+      conn.connectPromise = null
+      if (closed) return
+
+      emitSynthetic('disconnected')
+      scheduleRetry()
+    }
+  })()
+
+  return {
+    stop() {
+      closed = true
+      unsubStatus()
+      if (conn.retryTimer) {
+        clearTimeout(conn.retryTimer)
+        conn.retryTimer = null
+      }
+      if (conn.retryOwner === ownerToken) {
+        conn.retryOwner = null
+      }
+    },
+  }
+}

package/src/nats/use-nats-subscription.ts

@@ -0,0 +1,99 @@
+'use client'
+
+import * as React from 'react'
+import type { JsMsg, Msg, NatsSubscribeOptions } from './nats'
+import { useOptionalNats } from './nats-provider'
+
+export interface UseNatsSubscriptionOptions extends NatsSubscribeOptions {
+  enabled?: boolean
+}
+
+export interface UseNatsSubscriptionReturn {
+  isSubscribed: boolean
+  isReady: boolean
+}
+
+/**
+ * Subscribe to a NATS subject using the shared connection from <NatsProvider>.
+ * Automatically (re)subscribes when the connection becomes ready, when the
+ * subject changes, and after reconnections.
+ */
+export function useNatsSubscription(
+  subject: string | null,
+  onMessage: (msg: Msg) => void | Promise<void>,
+  options?: UseNatsSubscriptionOptions,
+): UseNatsSubscriptionReturn {
+  const nats = useOptionalNats()
+  const handlerRef = React.useRef(onMessage)
+  React.useEffect(() => {
+    handlerRef.current = onMessage
+  }, [onMessage])
+
+  const [isSubscribed, setIsSubscribed] = React.useState(false)
+
+  const enabled = options?.enabled !== false
+  const queue = options?.queue
+  const max = options?.max
+  const reconnectionCount = nats?.reconnectionCount ?? 0
+  const isReady = !!nats?.isReady
+  const client = nats?.client ?? null
+
+  React.useEffect(() => {
+    if (!client || !isReady || !subject || !enabled) {
+      setIsSubscribed(false)
+      return
+    }
+
+    const sub = client.subscribeBytes(
+      subject,
+      (msg) => handlerRef.current(msg),
+      { queue, max },
+    )
+    setIsSubscribed(true)
+
+    return () => {
+      setIsSubscribed(false)
+      try {
+        sub.unsubscribe()
+      } catch {
+        // ignore
+      }
+    }
+    // reconnectionCount intentionally in deps: re-subscribe after reconnect
+  }, [client, isReady, subject, enabled, queue, max, reconnectionCount])
+
+  return { isSubscribed, isReady }
+}
+
+export type UseNatsJsonSubscriptionOptions = UseNatsSubscriptionOptions
+
+export function useNatsJsonSubscription<T = unknown>(
+  subject: string | null,
+  onPayload: (payload: T, msg: Msg) => void | Promise<void>,
+  options?: UseNatsJsonSubscriptionOptions,
+): UseNatsSubscriptionReturn {
+  const handlerRef = React.useRef(onPayload)
+  React.useEffect(() => {
+    handlerRef.current = onPayload
+  }, [onPayload])
+
+  const decoderRef = React.useRef<TextDecoder | null>(null)
+  if (!decoderRef.current && typeof TextDecoder !== 'undefined') {
+    decoderRef.current = new TextDecoder()
+  }
+
+  const wrapped = React.useCallback(async (msg: Msg) => {
+    const decoder = decoderRef.current
+    if (!decoder) return
+    try {
+      const parsed = JSON.parse(decoder.decode(msg.data)) as T
+      await handlerRef.current(parsed, msg)
+    } catch {
+      // ignore malformed payloads
+    }
+  }, [])
+
+  return useNatsSubscription(subject, wrapped, options)
+}
+
+export type NatsJsMsg = JsMsg

package/src/schemas/.contact-schema.md

@@ -0,0 +1,45 @@
+<!-- source-hash: 571de537c275f3d8b2eefb0fa68e0454 -->
+Defines and exports Zod validation schemas, type-safe option constants, and API response types for all contact-style forms across the Flamingo platform.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `companySizeOptions` | `const` tuple | Allowed company size values for Select widgets |
+| `referralSourceOptions` | `const` tuple | Allowed referral source values for Select widgets |
+| `defaultHelpCategoryOptions` | `const` tuple | Fallback help category options when none are supplied by the embedder |
+| `LinkedInUrlSchema` | `z.ZodSchema` | Reusable LinkedIn URL validator with hostname-exact matching (prevents substring injection) |
+| `ContactBaseSchema` | `z.ZodObject` | Shared base schema for all contact-style forms (contact, TMCG join, data-room, etc.) |
+| `ContactSchema` | `z.ZodObject` | Extends `ContactBaseSchema` with dropdown-constrained `companySize` and `referralSource` fields |
+| `ContactFormData` | `type` | Inferred TypeScript type from `ContactSchema` |
+| `ContactApiResponse` | `interface` | Shape of the `POST /api/contact` JSON response |
+
+## Usage Example
+
+```typescript
+import {
+  ContactSchema,
+  ContactBaseSchema,
+  LinkedInUrlSchema,
+  type ContactFormData,
+  defaultHelpCategoryOptions,
+} from './contact-schema';
+
+// Validate a generic contact form submission
+const result = ContactSchema.safeParse(req.body);
+if (!result.success) {
+  return res.status(400).json({ error: result.error.flatten() });
+}
+const data: ContactFormData = result.data;
+
+// Extend the base schema for a custom form
+const JoinSchema = ContactBaseSchema.extend({
+  companyName: z.string().min(2),
+  linkedin_url: LinkedInUrlSchema,
+});
+
+// Use option constants in a Select component
+<Select options={defaultHelpCategoryOptions} name="helpCategory" />
+```
+
+> **Note:** Always reference `LinkedInUrlSchema` directly rather than duplicating LinkedIn URL validation logic. Hostname-exact matching (`host === 'linkedin.com'` or `host.endsWith('.linkedin.com')`) is intentional — substring checks would accept adversarial inputs like `https://evil.com/linkedin.com/path`.

package/src/stories/.AnnouncementBar.stories.md

@@ -0,0 +1,45 @@
+<!-- source-hash: cf04b71bf17cf6b35fdcdc036bdc8b09 -->
+Storybook stories for the `AnnouncementBar` component, providing isolated visual variants with mocked API responses and localStorage state to simulate the full announcement lifecycle without a real backend.
+
+## Key Components
+
+| Export | Description |
+|--------|-------------|
+| `mockAnnouncement()` | Helper that intercepts `window.fetch` to return mock announcement data and clears dismiss flags from `localStorage` |
+| `Default` | Basic announcement with icon and description using the Flamingo yellow (`#FFD951`) background |
+| `WithCTA` | Announcement with a fully configured call-to-action button opening in a new tab |
+| `WithCTASameTab` | CTA variant targeting `_self` for same-tab navigation |
+| `BlueBackground` / `GreenBackground` | Color theme variants |
+| `WithOpenFrameLogo` | Uses the `openframe-logo` SVG icon with a branded CTA |
+| `WithPNGIcon` | Tests PNG icon rendering via `icon_png_url` |
+| `LongContent` | Stress-tests truncation behavior on long titles and descriptions |
+| `NoAnnouncement` | Renders with `null` announcement to verify the bar hides itself |
+
+## Usage Example
+
+```typescript
+// How the fetch mock works in each story decorator
+const cleanup = mockAnnouncement({
+  id: 'story-1',
+  title: 'New Feature Released',
+  description: 'Check out our latest updates.',
+  background_color: '#FFD951',
+  icon_type: 'svg',
+  icon_svg_name: 'rocket',
+  platform_id: 'openframe',
+  is_active: true,
+  created_at: new Date().toISOString(),
+  updated_at: new Date().toISOString(),
+})
+
+// The mock intercepts /api/announcements/active
+// and returns the provided announcement object.
+// Pass null to simulate no active announcement.
+mockAnnouncement(null)
+```
+
+## Notes
+
+- All stories use the `fullscreen` layout to replicate the top-of-page bar context
+- The `mockAnnouncement` helper automatically restores `window.fetch` and removes `localStorage` dismiss keys to prevent state leaking between story renders
+- `autodocs` is enabled, generating a component API table from the `Announcement` type

package/src/stories/.AppLayout.stories.md

@@ -1,46 +1,45 @@
-<!-- source-hash: 7583eb7cd6a5e96c338c7af84ae7732b -->
-Storybook configuration file that defines stories for the AppLayout component, showcasing various layout configurations with sidebar navigation, header options, and main content areas.
+<!-- source-hash: 6e460b9179ea9cfc7a0f83bf49f746bd -->
+Storybook stories for the `AppLayout` component, showcasing layout configurations including sidebar states, header options, navigation interactions, and disabled states.
 
 ## Key Components
 
-- **Meta Configuration**: Storybook metadata with fullscreen layout and component documentation
-- **Navigation Items**: Pre-configured sidebar navigation with primary and secondary sections
-- **Story Variants**: Multiple story examples demonstrating different AppLayout configurations
-- **Interactive Examples**: Stories with stateful navigation and user interaction handling
+- **`Default`** — Standard layout with sidebar, header, and active navigation tracking via `useState`
+- **`WithHeaderUserOnly`** — Layout using only `headerProps` for user identity
+- **`WithSearchAndOrganizations`** — Header with search bar and org selector enabled
+- **`WithLoadingFallback`** — Custom Suspense fallback spinner injected via `loadingFallback` prop
+- **`WithCustomMainClassName`** — Overrides main content area background styling
+- **`MinimizedSidebar`** — Starts with sidebar collapsed to icon-only mode
+- **`Interactive`** — Fully interactive story with live navigation state and current route display
+- **`Disabled`** — All controls dimmed/inert except the mobile burger menu and sidebar collapse toggle
 
 ## Usage Example
 
 ```typescript
 import { AppLayout } from '../components/navigation/app-layout'
 
-// Basic layout with sidebar and header
+// Basic usage with sidebar and header
 <AppLayout
   sidebarConfig={{
     items: navigationItems,
-    onNavigate: handleNavigate,
-    onToggleMinimized: toggleSidebar,
+    onNavigate: (path) => router.push(path),
+    onToggleMinimized: () => setMinimized(prev => !prev),
   }}
   headerProps={{
     showNotifications: true,
     showUser: true,
-    userName: 'John Doe',
-    userEmail: 'john@example.com',
-    onProfile: handleProfile,
+    userName: 'Jane Smith',
+    userEmail: 'jane@example.com',
+    onProfile: () => router.push('/profile'),
     onLogout: handleLogout,
   }}
   mobileBurgerMenuProps={{
     user: {
-      userName: 'Alex Developer',
-      userEmail: 'alex@openframe.dev',
-      userAvatarUrl: 'https://github.com/shadcn.png',
+      userName: 'Jane Smith',
+      userEmail: 'jane@example.com',
       userRole: 'Admin',
     },
   }}
 >
-  <div className="p-4">
-    <h1>Main Content</h1>
-  </div>
+  <div className="p-4">Page content here</div>
 </AppLayout>
-```
-
-The stories demonstrate features like responsive sidebar behavior, search functionality, organization selection, custom loading states, and interactive navigation with proper state management.
+```

package/src/stories/.Autocomplete.stories.md

@@ -1,42 +1,56 @@
-<!-- source-hash: 6597ac1ad9801aac3429308510f4f32b -->
-Storybook stories configuration for the Autocomplete component demonstrating all possible states and configurations including selection limits, validation states, and custom rendering options.
+<!-- source-hash: aaa3356b95c56eaf4a969ac37cfe3145 -->
+Storybook stories for the `Autocomplete` UI component, covering all major interaction modes including single/multiple select, creatable options, server-side filtering, and various configuration props.
 
 ## Key Components
 
-- **Meta Configuration**: Storybook metadata for the Autocomplete component under 'UI/Autocomplete' category
-- **Sample Options**: Predefined list of industry options for consistent testing across all stories
-- **Story Variants**: 13 different story configurations covering all component states:
-  - `Default` - Basic autocomplete with no selection
-  - `WithLabel` - Includes form label
-  - `WithSelectedValues` - Pre-selected options demonstration
-  - `WithoutSearchIcon` - Hides the search icon
-  - `WithMaxItems` - Enforces selection limits
-  - `MaxItemsReached` - Shows behavior at capacity
-  - `Disabled` - Non-interactive state
-  - `Invalid` - Error/validation state
-  - `FreeSolo` - Allows custom option creation
-  - `CustomOptionRender` - Custom option display with colored indicators
-  - `LimitTags` - Truncates display with "+X more" indicator
-  - `Loading` - Shows loading state with custom text
-  - `AllVariants` - Comparison view of multiple configurations
+- **`Single`** — Basic single-select with no initial value
+- **`SingleWithValue`** — Single-select with a pre-selected option
+- **`SingleDisabled`** / **`MultipleDisabled`** — Disabled states
+- **`SingleWithError`** / **`MultipleWithError`** — Validation error display
+- **`Multiple`** — Multi-select with tag chips
+- **`MultipleWithValues`** — Multi-select with pre-selected values
+- **`MultipleWithMaxItems`** — Enforces a selection ceiling via `maxItems`
+- **`MultipleFreeSolo`** — Allows arbitrary text input without matching options
+- **`MultipleLimitTags`** — Collapses overflow tags via `limitTags`
+- **`MultipleCustomOptionRender`** — Custom `renderOption` with status indicator dots
+- **`Loading`** — Loading skeleton state with custom `loadingText`
+- **`SingleCreatable`** / **`MultipleCreatable`** — Create new options on the fly via `onCreateOption`
+- **`ServerSideFilter`** / **`ServerSideFilterCreatable`** — Disables client-side filtering; delegates to `onInputChange` with simulated async delay
+- **`SingleNoChevron`** / **`MultipleNoChevron`** — Hides the dropdown chevron icon via `showChevron={false}`
+- **`SingleKeepValueOnOpen`** — Preserves selected label text on focus via `clearOnOpen={false}`
 
 ## Usage Example
 
 ```typescript
-// Basic story setup pattern used throughout
-export const ExampleStory: Story = {
-  args: {
-    options: sampleOptions,
-    value: ['enterprise', 'startup'],
-    onChange: () => {},
-    label: 'Industry Selection',
-    placeholder: 'Select industries...',
-  },
-  render: function Render(args) {
-    const [value, setValue] = useState<string[]>(args.value);
-    return <Autocomplete {...args} value={value} onChange={setValue} />;
-  },
-};
-```
+import { Autocomplete, AutocompleteOption } from '../components/ui/autocomplete';
 
-Each story uses the render function pattern to provide interactive state management, making the Storybook controls fully functional for testing component behavior.
+const options: AutocompleteOption<string>[] = [
+  { label: 'Enterprise', value: 'enterprise' },
+  { label: 'Startup', value: 'startup' },
+];
+
+// Single select
+<Autocomplete
+  options={options}
+  value={value}
+  onChange={setValue}
+  label="Industry"
+  placeholder="Select..."
+/>
+
+// Multi-select with creation + server-side filter
+<Autocomplete
+  multiple
+  creatable
+  disableClientFilter
+  options={filteredOptions}
+  value={selected}
+  onChange={setSelected}
+  onInputChange={handleSearch}
+  onCreateOption={(input) => addOption(input)}
+  loading={isLoading}
+  loadingText="Searching..."
+  maxItems={5}
+  limitTags={2}
+/>
+```

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

@@ -0,0 +1,35 @@
+<!-- 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.
+
+## 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 |
+
+**Helpers used internally:**
+
+- `buildSeedColumns()` — generates five default status columns with varied ticket data
+- `applyChange()` — immutably applies a `BoardChange` (move/reorder) to the column state
+
+## Usage Example
+
+```typescript
+// Minimal interactive board with DnD and immutable state update
+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)}
+/>
+```