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

package/src/components/features/ai-enrich/.AIEnrichButton.md

@@ -1,45 +1,48 @@
-<!-- source-hash: 85d234020490e54e3251b26b200e61b1 -->
-A specialized button component that provides AI-powered content enrichment functionality with loading states, customizable variants, and a sparkles icon.
+<!-- source-hash: 553f8dbdfb9763d4ad797668077fd3a4 -->
+A reusable client-side button component that triggers AI enrichment actions, featuring a sparkles icon, loading state, and configurable size/variant options.
 
 ## Key Components
 
-- **`AIEnrichButton`** - Main React functional component that renders an AI enrichment button
-- **`AIEnrichButtonProps`** - TypeScript interface defining component props including onClick handler, loading states, and styling options
-- **`sizeMap`** - Maps component size props (`sm`, `md`, `lg`) to Button component sizes
-- **`variantMap`** - Maps component variants (`primary`, `secondary`, `outline`) to Button component variants
+### `AIEnrichButtonProps`
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `onClick` | `() => void` | — | Handler called on button click |
+| `disabled` | `boolean` | `false` | Disables the button |
+| `loading` | `boolean` | `false` | Shows loading state and swaps label |
+| `label` | `string` | `'AI Enrich'` | Default button text |
+| `loadingLabel` | `string` | `'Enriching...'` | Text shown during loading |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Button size |
+| `variant` | `'primary' \| 'secondary' \| 'outline'` | `'outline'` | Visual style |
+| `className` | `string` | — | Additional CSS classes |
+
+### `AIEnrichButton`
+The exported functional component. Internally maps the `size` and `variant` props to the underlying `Button` component's accepted values, and hides the `SparklesIcon` while loading.
 
 ## Usage Example
 
 ```typescript
 import { AIEnrichButton } from './components/AIEnrichButton'
 
-function ContentEditor() {
-  const [isEnriching, setIsEnriching] = useState(false)
+function TicketForm() {
+  const [enriching, setEnriching] = React.useState(false)
 
   const handleEnrich = async () => {
-    setIsEnriching(true)
-    try {
-      // Call AI enrichment API
-      await enrichContent()
-    } finally {
-      setIsEnriching(false)
-    }
+    setEnriching(true)
+    await enrichTicketWithAI()
+    setEnriching(false)
   }
 
   return (
-    <div>
-      <AIEnrichButton
-        onClick={handleEnrich}
-        loading={isEnriching}
-        label="Enhance with AI"
-        loadingLabel="Processing..."
-        variant="primary"
-        size="md"
-        className="my-4"
-      />
-    </div>
+    <AIEnrichButton
+      onClick={handleEnrich}
+      loading={enriching}
+      size="sm"
+      variant="primary"
+      label="Enrich Ticket"
+      loadingLabel="Analyzing..."
+    />
   )
 }
 ```
 
-The component automatically handles loading states, disables interaction during processing, and displays appropriate labels. The sparkles icon provides visual feedback for AI functionality and is hidden during loading.
+> The button automatically disables itself during loading (`disabled || loading`), preventing duplicate submissions while Mingo AI processes the enrichment request.

package/src/components/features/ai-enrich/.AIEnrichSection.md

@@ -1,51 +1,55 @@
-<!-- source-hash: 5552d95934cddb1d296daa3277e703de -->
-A React component that provides a comprehensive UI section for AI-powered data enrichment functionality. It handles the complete enrichment workflow including trigger button, status display, confidence metrics, warnings, and required field validation.
+<!-- source-hash: 3297a26442c5b70d119e373c4687b748 -->
+Reusable AI enrichment panel component that renders a full-featured UI section for triggering AI-powered data enrichment, displaying status feedback, confidence scores, warnings, and optional custom instructions.
 
 ## Key Components
 
-- **AIEnrichSection**: Main component that orchestrates the AI enrichment interface
-- **ConfidenceField**: Interface for displaying confidence scores of enriched fields
-- **AIRequiredField**: Interface for tracking required fields and their completion status
-- **AIEnrichSectionProps**: Comprehensive props interface supporting all enrichment states
+### Interfaces
+
+| Interface | Purpose |
+|-----------|---------|
+| `ConfidenceField` | Defines a field with an optional confidence score for display |
+| `AIRequiredField` | Describes a required form field, its fill state, and display label |
+| `AIEnrichSectionProps` | Full prop contract for the `AIEnrichSection` component |
+
+### Component: `AIEnrichSection`
+
+The main exported component. Renders a card-style panel with:
+
+- **Header** — Icon (defaults to `SparklesIcon`), title, and optional description
+- **Custom Instructions** (opt-in) — Controlled `<Textarea>` for user-provided AI focus hints, passed upstream to Claude via `buildEditorFocusBlock()`
+- **Action Buttons** — `AIEnrichButton` (primary) and optional cancel button during loading
+- **Disabled State** — Shows `disabledMessage` with badge-styled list of unfilled required fields
+- **Loading State** — Spinner with live `statusMessage`
+- **Results Section** — Success/error status indicator, confidence badge, `AIWarningsSection`, custom `children`, and a clear button
 
 ## Usage Example
 
 ```typescript
-import { AIEnrichSection } from './AIEnrichSection'
-
-function FormWithAIEnrichment() {
-  const [status, setStatus] = useState<'idle' | 'loading' | 'success' | 'error'>('idle')
-  const [warnings, setWarnings] = useState<string[]>([])
-  
-  const requiredFields = [
-    { key: 'email', label: 'Email', isFilled: !!formData.email },
-    { key: 'company', label: 'Company', isFilled: !!formData.company }
-  ]
-
-  const confidenceFields = [
-    { label: 'Industry', key: 'industry', confidence: 85 },
-    { label: 'Company Size', key: 'size', confidence: 92 }
-  ]
-
-  return (
-    <AIEnrichSection
-      onEnrich={handleAIEnrichment}
-      loading={status === 'loading'}
-      status={status}
-      statusMessage="Analyzing company data..."
-      overallConfidence={88}
-      warnings={warnings}
-      requiredFields={requiredFields}
-      confidenceFields={confidenceFields}
-      onClear={() => setStatus('idle')}
-      canEnrich={requiredFields.every(f => f.isFilled)}
-    >
-      <div className="text-sm">
-        Created 3 new tags based on industry analysis
-      </div>
-    </AIEnrichSection>
-  )
-}
+<AIEnrichSection
+  title="Enrich Asset"
+  description="Use AI to auto-fill missing asset details."
+  onEnrich={handleEnrich}
+  loading={isLoading}
+  canEnrich={hasRequiredFields}
+  status={enrichStatus}
+  statusMessage="Analyzing asset data..."
+  overallConfidence={87}
+  warnings={enrichWarnings}
+  requiredFields={[
+    { key: 'version', label: 'Version', isFilled: !!formValues.version },
+    { key: 'vendor', label: 'Vendor', isFilled: !!formValues.vendor },
+  ]}
+  showCustomInstructions
+  customInstructions={instructions}
+  onCustomInstructionsChange={setInstructions}
+  onClear={handleClear}
+  showCancel
+  onCancel={handleCancel}
+/>
 ```
 
-The component automatically handles disabled states when required fields are missing, displays confidence badges for enriched data, and provides a clean interface for managing the entire AI enrichment process.
+## Notes
+
+- Supports `'default'` and `'compact'` layout variants via the `variant` prop
+- `customInstructions` is fully controlled — the parent owns the string value
+- `requiredFields` drives both `canEnrich` gating and the unfilled-fields badge display

package/src/components/features/board/.board-column-header.md

@@ -0,0 +1,38 @@
+<!-- source-hash: 1ad6ce49d76bfa9f7bbe6737c01b2305 -->
+Renders the header for a Kanban board column, supporting both expanded and collapsed states with ticket status display, count, and optional ticket creation.
+
+## Key Components
+
+### `BoardColumnHeaderProps`
+| Prop | Type | Description |
+|------|------|-------------|
+| `column` | `BoardColumnDef` | Column definition including id, label, color, and tickets |
+| `collapsed` | `boolean` | Controls collapsed/expanded display mode |
+| `onToggleCollapse` | `() => void` | Callback to toggle column collapse state |
+| `onAddTicket` | `() => void` (optional) | Callback to trigger ticket creation |
+
+### `BoardColumnHeader`
+Client component that renders two distinct layouts:
+- **Collapsed:** Vertical layout with expand icon, rotated status tag, and ticket count
+- **Expanded:** Horizontal layout with status tag, count, collapse button, and optional add-ticket button
+
+Uses `getTicketStatusConfig` to determine whether to use a built-in status color or a custom column color for the `TicketStatusTag`.
+
+## Usage Example
+
+```typescript
+import { BoardColumnHeader } from './board-column-header'
+
+<BoardColumnHeader
+  column={{
+    id: 'in-progress',
+    label: 'In Progress',
+    color: '#FFC008',
+    tickets: [...],
+    total: 12,
+  }}
+  collapsed={false}
+  onToggleCollapse={() => setCollapsed(prev => !prev)}
+  onAddTicket={() => openCreateTicketModal('in-progress')}
+/>
+```

package/src/components/features/board/.board-column.md

@@ -0,0 +1,43 @@
+<!-- source-hash: 1bf9b2d5d2d477b1115c900de71defaa -->
+Renders a single kanban board column with drag-and-drop support, collapsible layout, infinite scroll via IntersectionObserver, and ticket card rendering.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `BoardColumn` | Component | Main column shell handling collapsed/expanded state, border joining, and color tinting |
+| `BoardColumnProps` | Interface | Public API for the column component |
+| `ColumnBody` | Internal Component | Scrollable droppable zone with `SortableContext`, infinite scroll sentinel, and loading states |
+| `SkeletonStack` | Internal Component | Renders `n` skeleton placeholders during initial load |
+| `EmptyState` | Internal Component | Illustrated empty state shown when a column has no tickets |
+
+## Usage Example
+
+```typescript
+<BoardColumn
+  column={{
+    id: 'open',
+    label: 'Open',
+    color: '#3B82F6',
+    tickets: myTickets,
+    hasMore: true,
+    isLoading: false,
+    isLoadingMore: false,
+  }}
+  collapsed={false}
+  onToggleCollapse={() => setCollapsed(c => !c)}
+  onAddTicket={(columnId) => openNewTicketModal(columnId)}
+  getTicketHref={(ticketId) => `/tickets/${ticketId}`}
+  renderAssignSlot={(ticket) => <AssigneePicker ticket={ticket} />}
+  onLoadMore={(columnId) => fetchNextPage(columnId)}
+  joinLeft={false}
+  joinRight={true}
+/>
+```
+
+## Notes
+
+- **Drag-and-drop**: Uses `@dnd-kit/core` (`useDroppable`) and `@dnd-kit/sortable` (`SortableContext`) — drop target is disabled when `column.dropDisabled` is set.
+- **Infinite scroll**: An `IntersectionObserver` watches a 1px sentinel div at the bottom of the scroll container; `onLoadMore` fires when it enters the viewport. Scroll is paused while `isLoadingMore` is true.
+- **Collapsed state**: When `collapsed=true`, the column shrinks to `w-14` and hides the body; the header remains visible.
+- **Joined borders**: `joinLeft`/`joinRight` props remove border radii and borders on adjacent edges for seamless multi-column layouts.

package/src/components/features/board/.board.md

@@ -0,0 +1,51 @@
+<!-- source-hash: 266e1c3c423b749f9d7def8ff717188e -->
+A drag-and-drop Kanban board component that manages ticket movement across columns using `@dnd-kit/core`, with support for column collapsing, horizontal scrolling, and constrained drop rules.
+
+## Key Components
+
+| Export / Symbol | Description |
+|---|---|
+| `Board` | Main board component rendering all columns with full DnD orchestration |
+| `BoardProps` | Props interface defining columns, event handlers, and customization options |
+| `collisionDetection` | Custom collision strategy: prefers ticket hits, falls back to column, then closest corners |
+| `handleDragStart` | Records drag origin (ticket + source column) and sets overlay state |
+| `handleDragOver` | Optimistically moves tickets across columns respecting `dropDisabled` and `allowedFromColumns` |
+| `handleDragEnd` | Commits the move by calling `onChange` with positional context (`afterTicketId`, `beforeTicketId`), or rolls back |
+| `handleDragCancel` | Reverts local state to the last server-provided `columns` prop |
+| `locate` | Helper to find a ticket's column, index, and reference by ID |
+| `findIndexInColumn` | Helper returning a ticket's index within a specific column |
+
+## Usage Example
+
+```typescript
+<Board
+  columns={[
+    {
+      id: 'open',
+      label: 'Open',
+      tickets: [{ id: 'T-1', title: 'Fix login bug' }],
+    },
+    {
+      id: 'in-progress',
+      label: 'In Progress',
+      tickets: [],
+      allowedFromColumns: ['open'],
+    },
+    {
+      id: 'done',
+      label: 'Done',
+      tickets: [],
+      dropDisabled: true,
+    },
+  ]}
+  onChange={({ ticketId, fromColumnId, toColumnId, afterTicketId }) => {
+    api.moveTicket({ ticketId, toColumnId, afterTicketId })
+  }}
+  onLoadMore={(columnId) => fetchMore(columnId)}
+  getTicketHref={(ticketId) => `/tickets/${ticketId}`}
+  renderAssignSlot={(ticket) => <AssigneeAvatar ticket={ticket} />}
+  collapseStorageKey="board-collapse-state"
+/>
+```
+
+> **Drop rules:** Set `dropDisabled: true` on a column to block all inbound drops. Use `allowedFromColumns: ['open']` to restrict which source columns can feed into a target — dragging back to the origin column is always permitted regardless of these rules.

package/src/components/features/board/.color-utils.md

@@ -0,0 +1,26 @@
+<!-- source-hash: 908a5d80c6498d71475f70d268086189 -->
+Computes a pre-blended background tint by mixing a given hex color at 10% opacity over a fixed dark background (`#161616`), returning the resulting opaque hex color.
+
+## Key Components
+
+- **`tintOnDark(hex: string): string`** — Takes a hex color string (e.g. `#FFC008`), blends it at 10% over `#161616`, and returns the resulting opaque hex color.
+
+## Usage Example
+
+```typescript
+import { tintOnDark } from './color-utils'
+
+const tinted = tintOnDark('#FFC008')
+// Returns the pre-blended hex, e.g. "#211e13"
+// Useful for subtle colored backgrounds on dark UIs
+
+const redTint = tintOnDark('#FF0000')
+// Blends red at 10% over #161616 → "#281616"
+```
+
+## Notes
+
+- The background is hardcoded to `#161616` (decimal `22`), matching Flamingo's dark theme base.
+- Blend formula per channel: `round(0.1 * foreground + 0.9 * 22)`
+- Input hex may include or omit the leading `#`.
+- Returns a fully opaque hex string — no alpha channel — making it safe for any CSS `background-color` context.

package/src/components/features/board/.index.md

@@ -0,0 +1,56 @@
+<!-- source-hash: 173932afe7ff44448182cb23b63b5547 -->
+Client-side barrel export file for the Board UI component library, exposing all public components, hooks, utilities, and TypeScript types for the Kanban-style ticket board feature.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `Board` / `BoardProps` | Component | Root board container |
+| `BoardColumn` / `BoardColumnProps` | Component | Individual board column |
+| `BoardColumnHeader` / `BoardColumnHeaderProps` | Component | Column header with title/actions |
+| `TicketCard` / `TicketCardProps` | Component | Draggable ticket card |
+| `TicketCardSkeleton` / `TicketCardSkeletonProps` | Component | Loading placeholder for ticket cards |
+| `useBoardCollapse` | Hook | Manages column collapse/expand state |
+| `BoardCollapseMap` / `UseBoardCollapseReturn` | Types | Collapse hook type contracts |
+| `tintOnDark` | Utility | Color tinting helper for dark backgrounds |
+| `columnFromTicketStatus` | Utility | Maps ticket status to board column |
+| `groupTicketsByStatus` | Utility | Groups ticket arrays by their status |
+| `BoardChange`, `BoardColumnDef`, `BoardPriority`, `BoardTicket`, `BoardTicketAssignee` | Types | Core board domain types |
+
+## Usage Example
+
+```typescript
+import {
+  Board,
+  BoardColumn,
+  BoardColumnHeader,
+  TicketCard,
+  useBoardCollapse,
+  groupTicketsByStatus,
+} from '@/components/board'
+import type { BoardTicket, BoardColumnDef } from '@/components/board'
+
+const columns: BoardColumnDef[] = [
+  { id: 'open', label: 'Open' },
+  { id: 'in_progress', label: 'In Progress' },
+  { id: 'closed', label: 'Closed' },
+]
+
+export function TicketBoard({ tickets }: { tickets: BoardTicket[] }) {
+  const { collapseMap, toggle } = useBoardCollapse()
+  const grouped = groupTicketsByStatus(tickets)
+
+  return (
+    <Board>
+      {columns.map((col) => (
+        <BoardColumn key={col.id} collapsed={collapseMap[col.id]}>
+          <BoardColumnHeader column={col} onToggle={() => toggle(col.id)} />
+          {grouped[col.id]?.map((ticket) => (
+            <TicketCard key={ticket.id} ticket={ticket} />
+          ))}
+        </BoardColumn>
+      ))}
+    </Board>
+  )
+}
+```

package/src/components/features/board/.ticket-card-skeleton.md

@@ -0,0 +1,38 @@
+<!-- source-hash: 1103dbd0890929bf5922563df098f12b -->
+Loading state placeholder component that renders an animated skeleton UI mimicking the structure of a ticket card while content is being fetched.
+
+## Key Components
+
+- **`TicketCardSkeleton`** — A `forwardRef` component that renders a structured skeleton layout matching the ticket card's visual hierarchy:
+  - Title placeholder (3/4 width bar)
+  - Subtitle row with icon and text placeholders
+  - Action area with icon and avatar placeholders
+  - Badge/tag row at the bottom
+
+- **`TicketCardSkeletonProps`** — Extends `React.HTMLAttributes<HTMLDivElement>`, accepting all standard div props plus an optional `className` for style overrides.
+
+## Usage Example
+
+```typescript
+import { TicketCardSkeleton } from '@/components/tickets/ticket-card-skeleton'
+
+// Basic loading state
+function TicketList({ isLoading, tickets }) {
+  if (isLoading) {
+    return (
+      <div className="flex flex-col gap-2">
+        {Array.from({ length: 5 }).map((_, i) => (
+          <TicketCardSkeleton key={i} />
+        ))}
+      </div>
+    )
+  }
+
+  return tickets.map(ticket => <TicketCard key={ticket.id} {...ticket} />)
+}
+
+// With custom className
+<TicketCardSkeleton className="opacity-50" />
+```
+
+> **Note:** This component uses ODS design tokens (`--spacing-system-*`, `ods-border`, `ods-bg`) and the shared `Skeleton` primitive for consistent pulse animation across the Flamingo UI. Pair it directly with `TicketCard` to ensure visual dimensions match during loading transitions.

package/src/components/features/board/.ticket-card.md

@@ -0,0 +1,47 @@
+<!-- source-hash: 5c7fae07590f9209605f37d7b88636f3 -->
+Draggable kanban ticket card component for board views, supporting drag-and-drop via `@dnd-kit/sortable`, priority indicators, assignee avatars, device info, and tag display.
+
+## Key Components
+
+### `TicketCard`
+Main card component with three render modes:
+- **Overlay** – rendered during active drag (slight rotation, shadow)
+- **Link** – wraps content in a Next.js `<Link>` when `href` is provided
+- **Button** – falls back to a `<button>` for click-only interaction
+
+### `TicketTagRow` *(internal)*
+Renders up to `MAX_VISIBLE_TAGS` (2) tags with an overflow count badge (e.g. `+3`).
+
+### `PRIORITY_COLOR_CLASS`
+Maps `BoardPriority` values (`low`, `medium`, `high`, `urgent`) to ODS color tokens for the priority flag icon.
+
+## Props
+
+| Prop | Type | Description |
+|---|---|---|
+| `ticket` | `BoardTicket` | Ticket data to display |
+| `columnId` | `string` | Parent column ID, passed to sortable context |
+| `href` | `string?` | If set, card navigates on click |
+| `isOverlay` | `boolean` | Drag overlay mode (disables sortable refs) |
+| `dragDisabled` | `boolean?` | Disables dnd-kit drag handling |
+| `renderAssignSlot` | `(ticket) => ReactNode` | Custom assignee slot renderer |
+
+## Usage Example
+
+```typescript
+import { TicketCard } from './ticket-card'
+
+<TicketCard
+  ticket={{
+    id: 'TKT-001',
+    title: 'VPN not connecting',
+    priority: 'high',
+    tags: ['network', 'vpn'],
+    assignees: [{ id: 'u1', name: 'Alice', initials: 'AL' }],
+    deviceHostnames: ['workstation-42'],
+    organizationName: 'Acme Corp',
+  }}
+  columnId="in-progress"
+  href="/tickets/TKT-001"
+/>
+```

package/src/components/features/board/.types.md

@@ -0,0 +1,45 @@
+<!-- source-hash: 17f22ebd29735a4ef28b5782559c367e -->
+Defines the core data types and utility functions for the Kanban-style ticket board, including column definitions, ticket shapes, and helpers for mapping ticket statuses to board columns.
+
+## Key Components
+
+### Types
+
+| Type | Description |
+|------|-------------|
+| `BoardPriority` | Union type for ticket priority levels: `low`, `medium`, `high`, `urgent` |
+| `BoardTicketAssignee` | Assignee shape with optional avatar, initials, and name |
+| `BoardTicket` | Core ticket shape with status, priority, assignees, tags, and device info |
+| `BoardColumnDef` | Column definition including tickets, loading states, and drag/drop controls |
+| `BoardChange` | Represents a ticket move event between columns with ordering context |
+
+### Functions
+
+| Function | Description |
+|----------|-------------|
+| `columnFromTicketStatus` | Creates a `BoardColumnDef` from a `TicketStatus` with optional overrides |
+| `groupTicketsByStatus` | Buckets a flat ticket array into ordered columns by status |
+| `canonicalize` (internal) | Normalizes raw status strings to `TicketStatus`, including legacy `ACTION_REQUIRED → TECH_REQUIRED` mapping |
+
+## Usage Example
+
+```typescript
+import { groupTicketsByStatus, columnFromTicketStatus } from './types'
+
+// Group tickets into columns for the board
+const columns = groupTicketsByStatus(tickets, [
+  'ACTIVE',
+  'TECH_REQUIRED',
+  'ON_HOLD',
+  'RESOLVED',
+])
+
+// Build a single column with custom label and loading state
+const activeColumn = columnFromTicketStatus('ACTIVE', activeTickets, {
+  label: 'In Progress',
+  isLoadingMore: true,
+  total: 42,
+})
+```
+
+> `canonicalize` handles legacy status values automatically — `ACTION_REQUIRED` from older API responses is silently mapped to `TECH_REQUIRED` before bucketing.

package/src/components/features/board/.use-board-collapse.md

@@ -0,0 +1,34 @@
+<!-- source-hash: a1e52401ac78c99d8f31dd0b7b35996a -->
+Manages board column collapse state, supporting both persistent (localStorage) and in-memory storage modes depending on whether a `storageKey` is provided.
+
+## Key Components
+
+- **`BoardCollapseMap`** — Type alias for `Record<string, boolean>` mapping column IDs to their collapsed state
+- **`UseBoardCollapseReturn`** — Interface defining the hook's return shape
+- **`useBoardCollapse(storageKey?)`** — Main hook that initializes collapse state either in localStorage (when `storageKey` is given) or in component memory
+
+## Usage Example
+
+```typescript
+// Persistent collapse state (survives page refresh)
+const { collapsed, toggle, setCollapsed } = useBoardCollapse('my-board-key')
+
+// In-memory only (resets on unmount)
+const { collapsed, toggle, setCollapsed } = useBoardCollapse()
+
+// Toggle a column's collapsed state
+toggle('column-id-123')
+
+// Explicitly set a column's collapsed state
+setCollapsed('column-id-123', true)
+
+// Read current state
+const isCollapsed = collapsed['column-id-123'] // boolean | undefined
+```
+
+## Behavior Notes
+
+- When `storageKey` is provided, state is persisted via `useLocalStorage` and survives page reloads
+- When omitted, state lives in React `useState` and is scoped to the component's lifecycle
+- Both `toggle` and `setCollapsed` are memoized with `useCallback` to prevent unnecessary re-renders
+- Uses a fallback key `__board_collapse_unused__` internally to satisfy the `useLocalStorage` hook's required argument when no `storageKey` is given

package/src/components/features/notifications/.index.md

@@ -0,0 +1,57 @@
+<!-- source-hash: ec818e1d65048d1eb76277abcc10c0b6 -->
+Public API barrel file for the notifications module, re-exporting all components, hooks, context providers, and TypeScript types from their respective source files.
+
+## Key Components
+
+| Export | Type | Source |
+|--------|------|--------|
+| `NotificationsProvider` | Component | `notifications-context` |
+| `useNotifications` | Hook | `notifications-context` |
+| `useOptionalNotifications` | Hook | `notifications-context` |
+| `NotificationDrawer` | Component | `notification-drawer` |
+| `NotificationTile` | Component | `notification-tile` |
+| `Notification` | Type | `types` |
+| `NotificationVariant` | Type | `types` |
+| `AddNotificationInput` | Type | `types` |
+
+## Usage Example
+
+```typescript
+import {
+  NotificationsProvider,
+  useNotifications,
+  NotificationDrawer,
+  NotificationTile,
+} from '@/notifications'
+
+import type {
+  Notification,
+  NotificationVariant,
+  AddNotificationInput,
+} from '@/notifications'
+
+// Wrap your app with the provider
+function App() {
+  return (
+    <NotificationsProvider>
+      <NotificationDrawer />
+      <MainContent />
+    </NotificationsProvider>
+  )
+}
+
+// Consume notifications in a child component
+function MainContent() {
+  const { addNotification } = useNotifications()
+
+  const notify = () => {
+    const input: AddNotificationInput = {
+      variant: 'success' as NotificationVariant,
+      message: 'Operation completed successfully',
+    }
+    addNotification(input)
+  }
+
+  return <button onClick={notify}>Notify</button>
+}
+```

package/src/components/features/notifications/.notification-drawer.md

@@ -0,0 +1,34 @@
+<!-- source-hash: b78c3c40a3c3824dbca516563b5aef06 -->
+A right-side drawer component that displays unread notifications, a "Complete All" action, a pop-up toggle, and a history navigation button — consuming context from `useOptionalNotifications`.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `NotificationDrawer` | Component | Main drawer shell; renders only when notifications context is available |
+| `EmptyState` | Internal Component | Shown when there are no unread notifications |
+| `ShowNotificationsToggleRow` | Internal Component | Switch to enable/disable pop-up notification banners |
+| `NotificationsHistoryButton` | Internal Component | Outline button that navigates to notification history and closes the drawer |
+| `NotificationDrawerProps` | Interface | `className` and optional `liveDurationMs` for tile animations |
+
+## Usage Example
+
+```typescript
+import { NotificationDrawer } from './notification-drawer'
+import { NotificationsProvider } from './notifications-context'
+
+// Wrap your app (or layout) with the provider, then drop the drawer anywhere:
+export function AppLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <NotificationsProvider
+      notifications={notifications}
+      onHistoryClick={() => router.push('/notifications/history')}
+    >
+      {children}
+      <NotificationDrawer liveDurationMs={5000} />
+    </NotificationsProvider>
+  )
+}
+```
+
+> **Note:** `NotificationDrawer` returns `null` when rendered outside a `NotificationsProvider`. Open/close state is fully managed through the context — use the `open`/`close` methods exposed by `useOptionalNotifications` to control visibility from elsewhere in the UI.