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

package/src/hooks/ui/.use-image-edge-color.md

@@ -0,0 +1,42 @@
+<!-- source-hash: 38dbaa1fd6bace90952c3ff98f54f23a -->
+A React hook that extracts the dominant edge color from an image URL for use as a background fill behind letterboxed (`object-contain`) images.
+
+## Key Components
+
+### `extractEdgeColor(img: HTMLImageElement): string`
+Internal utility that performs canvas-based pixel analysis:
+- Scales the image down to a 100×100 thumbnail for performance
+- Samples a 15% border band along all four edges
+- Quantizes RGB values into 32-step buckets to group similar colors
+- Returns the averaged RGB of the most common bucket as a CSS `rgb(...)` string
+
+### `useImageEdgeColor(imageUrl, fallback?): string`
+Exported React hook that wraps `extractEdgeColor` with async image loading:
+- Sets `crossOrigin="anonymous"` for canvas pixel access on CDN-hosted images
+- Cancels stale updates via cleanup flag on unmount or URL change
+- Falls back to the provided color (default `#000000`) on load error or missing URL
+
+## Usage Example
+
+```typescript
+import { useImageEdgeColor } from './use-image-edge-color';
+
+function ProductImage({ src }: { src: string }) {
+  const bgColor = useImageEdgeColor(src, '#1a1a1a');
+
+  return (
+    <div style={{ backgroundColor: bgColor, padding: '1rem' }}>
+      <img
+        src={src}
+        style={{ objectFit: 'contain', width: '100%', height: '300px' }}
+        alt="Product"
+      />
+    </div>
+  );
+}
+```
+
+## Notes
+
+- **CORS requirement:** The image server must return CORS headers. Supabase, Cloudflare Images, and the Flamingo image proxy all support this. If CORS fails, `onerror` fires and the fallback color is used.
+- **Why bucketing vs. averaging:** Simple pixel averaging produces muddy mid-tones when edges contain distinct color regions (e.g., blue sky above tan sand). Bucketing picks the *dominant* region instead.

package/src/hooks/ui/.use-media-query.md

@@ -1,40 +1,48 @@
-<!-- source-hash: ad8be7d69a54d22da2cee837d13753b7 -->
-A React hook for detecting CSS media query matches with SSR-safe hydration handling. Returns `undefined` during server-side rendering and initial client-side render to prevent hydration mismatches.
+<!-- source-hash: 658ce45ffa6bcde5f5bc895ea6b0b28a -->
+React hook for responsive design that detects whether a CSS media query matches the current viewport, returning `undefined` during SSR to avoid hydration mismatches.
 
 ## Key Components
 
-- **`useMediaQuery(query: string)`** - Core hook that accepts any CSS media query string and returns match status
-- **`breakpoints`** - Predefined Tailwind CSS-compatible breakpoint definitions (sm, md, lg, xl, 2xl)
-- **Convenience hooks** - `useSmUp()`, `useMdUp()`, `useLgUp()`, `useXlUp()`, `use2xlUp()` for common responsive breakpoints
+| Export | Type | Description |
+|--------|------|-------------|
+| `useMediaQuery` | Hook | Core hook accepting any CSS media query string |
+| `breakpoints` | Object | Predefined breakpoints: `md` (800px), `lg` (1280px) |
+| `useMdUp` | Hook | Returns `true` when viewport ≥ 800px |
+| `useLgUp` | Hook | Returns `true` when viewport ≥ 1280px |
+| `useSmUp` | Hook | ⚠️ Deprecated — alias for `useMdUp` |
 
 ## Usage Example
 
 ```typescript
-import { useMediaQuery, useMdUp, breakpoints } from './use-media-query'
-
-function ResponsiveComponent() {
-  // Custom media query
-  const isDarkMode = useMediaQuery('(prefers-color-scheme: dark)')
-  
-  // Predefined breakpoint
-  const isMdUp = useMdUp()
-  
-  // Custom breakpoint
-  const isWide = useMediaQuery('(min-width: 1400px)')
-
-  // Handle undefined state during SSR/hydration
-  if (isDarkMode === undefined || isMdUp === undefined) {
-    return <div>Loading...</div>
-  }
+import { useMediaQuery, useMdUp, useLgUp, breakpoints } from "./use-media-query"
+
+// Custom query
+function Component() {
+  const isPortrait = useMediaQuery("(orientation: portrait)")
+
+  // Returns undefined on first render (SSR-safe)
+  if (isPortrait === undefined) return <Skeleton />
+  return <div>{isPortrait ? "Portrait" : "Landscape"}</div>
+}
+
+// Predefined breakpoints
+function ResponsiveLayout() {
+  const isMd = useMdUp()  // >= 800px
+  const isLg = useLgUp()  // >= 1280px
 
   return (
     <div>
-      <p>Dark mode: {isDarkMode ? 'Yes' : 'No'}</p>
-      <p>Medium screen or larger: {isMdUp ? 'Yes' : 'No'}</p>
-      <p>Wide screen: {isWide ? 'Yes' : 'No'}</p>
+      {isLg ? <DesktopNav /> : isMd ? <TabletNav /> : <MobileNav />}
     </div>
   )
 }
+
+// Using breakpoints object directly
+const isDesktop = useMediaQuery(breakpoints.lg)
 ```
 
-The hook uses `useLayoutEffect` to avoid visual flicker and properly cleans up event listeners to prevent memory leaks.
+## Notes
+
+- Returns `undefined` during SSR and initial render — always guard against this before conditionally rendering UI
+- Uses `useLayoutEffect` to synchronously read the media query state before paint, preventing layout flicker
+- Automatically cleans up the `change` event listener on unmount

package/src/hooks/ui/.use-search.md

@@ -0,0 +1,51 @@
+<!-- source-hash: 8ccc6891a2b3966ffa91a4330f0065e9 -->
+Generic React hook for managing debounced async search state, including loading, error handling, and result mapping.
+
+## Key Components
+
+### `UseSearchConfig<T>`
+Configuration interface for the hook:
+- `searchFn` — async function that receives the query string and returns raw results
+- `mapResult` — transforms each raw result into a `SearchResult`
+- `debounceMs` — debounce delay in milliseconds (default: `300`)
+- `minQueryLength` — minimum characters before triggering a search (default: `2`)
+
+### `UseSearchReturn`
+Return shape exposing:
+- `query` / `setQuery` — controlled input state
+- `results` — mapped `SearchResult[]`
+- `isLoading` — `true` while the async search is in flight
+- `error` — error message string or `null`
+- `clearResults` — resets results and error state
+
+### `useSearch<T>(config)`
+Core hook that orchestrates debouncing via `useDebounce`, fires `searchFn` when the debounced query meets `minQueryLength`, and cancels stale in-flight requests via a `cancelled` flag on cleanup.
+
+## Usage Example
+
+```typescript
+import { useSearch } from "@/hooks/use-search"
+import type { Device } from "@/types"
+
+const { query, setQuery, results, isLoading, error } = useSearch<Device>({
+  searchFn: async (q) => await api.devices.search(q),
+  mapResult: (device) => ({
+    id: device.id,
+    label: device.hostname,
+    description: device.ipAddress,
+  }),
+  debounceMs: 400,
+  minQueryLength: 3,
+})
+
+// Bind to an input
+<SearchInput
+  value={query}
+  onChange={setQuery}
+  results={results}
+  loading={isLoading}
+  error={error}
+/>
+```
+
+> Stale request cancellation is handled automatically — if the query changes before a previous search resolves, its result is silently discarded.

package/src/nats/.nats.md

@@ -1,51 +1,72 @@
-<!-- source-hash: c85909ba81ed8077d3a889ff6145d073 -->
-A WebSocket-based NATS client wrapper that provides type-safe publish, subscribe, and request-reply messaging patterns for browser and Tauri environments. Built on top of the `nats.ws` library with automatic codec handling for bytes, strings, and JSON payloads.
+<!-- source-hash: 418321f518535eef27f0004848e1e1b3 -->
+A browser/Tauri-only NATS client factory for WebSocket-based NATS connections (`nats.ws`), providing typed pub/sub, request/reply, JetStream ordered consumer subscriptions, and connection lifecycle management.
 
 ## Key Components
 
-- **`createNatsClient(options)`** - Factory function that creates a NATS client instance
-- **`NatsClient`** - Main interface providing connection management and messaging operations
-- **`NatsClientOptions`** - Configuration interface for server URLs, authentication, and connection behavior
-- **Message Publishing** - `publishBytes()`, `publishString()`, `publishJson()` methods for fire-and-forget messaging
-- **Request-Reply** - `requestBytes()`, `requestString()`, `requestJson()` methods for synchronous communication
-- **Subscriptions** - `subscribeBytes()`, `subscribeString()`, `subscribeJson()` methods with queue groups and auto-unsubscribe
-- **Status Monitoring** - `onStatus()` method for connection state changes and error handling
+### Interfaces & Types
+| Export | Description |
+|--------|-------------|
+| `NatsClient` | Core client interface with all pub/sub/request/JetStream methods |
+| `NatsClientOptions` | Connection config: servers, auth, reconnect, exponential backoff, ping |
+| `NatsSubscribeOptions` | Per-subscription options: queue group, max messages, abort signal |
+| `NatsPublishOptions` / `NatsRequestOptions` | Optional headers and timeout per operation |
+| `JetStreamOrderedSubscribeOptions` | JetStream ephemeral consumer config: stream, filter, deliver policy, start sequence |
+| `NatsStatus` / `NatsStatusEvent` | Connection state machine: `connecting`, `connected`, `disconnected`, `reconnecting`, `closed`, `error` |
+
+### Factory Function
+- **`createNatsClient(options)`** — Returns a `NatsClient` instance. Lazily imports `nats.ws` (browser-safe). All methods are lazy-connected and browser-only (throws if `window` is undefined).
+
+### Internal Helpers
+- **`createExponentialBackoffHandler`** — Configurable exponential backoff with optional crypto jitter for reconnect delays.
+- **`toNatsHeaders`** — Converts `Record<string, string>` or native `NatsHeaders` into a `nats.ws` headers object.
+- **`mapNatsTypeToStatus`** — Normalizes raw `nats.ws` status events to the typed `NatsStatus` union.
 
 ## Usage Example
 
 ```typescript
 import { createNatsClient } from './nats'
 
-// Create client with WebSocket connection
 const client = createNatsClient({
   servers: 'wss://nats.example.com:443',
-  name: 'my-app',
-  token: 'auth-token'
+  name: 'flamingo-ui',
+  token: 'my-token',
+  exponentialBackoff: {
+    initialDelayMs: 500,
+    maxDelayMs: 15_000,
+    multiplier: 2,
+    jitter: true,
+  },
+})
+
+// Listen for connection status changes
+const off = client.onStatus((event) => {
+  console.log('NATS status:', event.status)
 })
 
-// Connect and handle status
 await client.connect()
-client.onStatus(({ status }) => console.log('NATS status:', status))
 
-// Publish JSON message
-client.publishJson('user.created', { id: 123, name: 'Alice' })
+// Typed JSON publish
+client.publishJson('telemetry.events', { deviceId: 'abc', value: 42 })
 
-// Subscribe to messages with queue group
-const handle = client.subscribeJson<UserEvent>('user.*', 
-  (payload, msg) => {
-    console.log('Received:', payload, 'on subject:', msg.subject)
-  },
-  { queue: 'workers' }
+// Typed JSON request/reply
+const response = await client.requestJson<{ ok: boolean }>(
+  'devices.query',
+  { id: 'abc' },
+  { timeoutMs: 3000 },
 )
 
-// Request-reply pattern
-const response = await client.requestJson<UserResponse, UserRequest>(
-  'user.get', 
-  { userId: 123 },
-  { timeoutMs: 5000 }
+// JetStream ordered consumer (live-tail)
+const handle = await client.subscribeJetStreamOrdered(
+  (msg) => console.log('JetStream msg:', msg.seq),
+  {
+    streamName: 'EVENTS',
+    filterSubject: 'events.>',
+    deliverPolicy: 'new',
+  },
 )
 
-// Clean up
+// Cleanup
 handle.unsubscribe()
+off()
 await client.close()
 ```

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)}
+/>
+```