@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482

package/src/components/features/index.ts

@@ -65,7 +65,11 @@ export * from './video-ratio-tabs'
 export * from './video-bites-shared'
 export * from './video-bites-strip'
 export * from './video-bites-display'
+export * from './card-hit-layer'
+export * from './video-hover-preview'
 export * from './entity-video-section'
+export * from './floating-walkthrough-video'
+export * from './use-walkthrough-video'
 export * from './use-video-warmup'
 export * from './captions-url'
 export * from './video-source-selector'

package/src/components/features/notifications/.approval-request-notification-tile.md

@@ -0,0 +1,45 @@
+<!-- source-hash: df0c665817142753be2e5e9762b91c23 -->
+A React notification tile component for displaying and acting on approval requests, supporting optimistic UI updates, collapsible command previews, and auto-dismiss behavior.
+
+## Key Components
+
+### `ApprovalRequestNotificationTileProps`
+| Prop | Type | Description |
+|---|---|---|
+| `notification` | `Notification` | Source notification data |
+| `onApprove` | `(id: string) => void \| Promise<void>` | Callback fired on approval |
+| `onReject` | `(id: string) => void \| Promise<void>` | Callback fired on rejection |
+| `onComplete` | `(id: string) => void` | Called after successful resolution |
+| `onSettle` | `(id: string) => void` | Optional settle lifecycle hook |
+| `liveDurationMs` | `number` | Auto-dismiss duration for live tiles |
+| `defaultExpanded` | `boolean` | Whether the command section starts open |
+
+### Internal State
+- **`localStatus`** — Optimistic `ChatApprovalStatus` set immediately on click; rolls back on request failure; defers to resolved backend status once available.
+- **`pinned`** — Prevents auto-dismiss when the user expands the command section mid-read.
+- **`processing`** — Disables action buttons and pauses the tile timer during async resolution.
+
+### `resolve()`
+Internal async handler that applies optimistic status, calls the appropriate action callback, rolls back on error, and calls `onComplete` only after confirmed server-side success.
+
+## Usage Example
+
+```typescript
+import { ApprovalRequestNotificationTile } from './approval-request-notification-tile'
+
+<ApprovalRequestNotificationTile
+  notification={notification}
+  liveDurationMs={8000}
+  defaultExpanded={false}
+  onApprove={async (id) => {
+    await api.approvals.approve(id)
+  }}
+  onReject={async (id) => {
+    await api.approvals.reject(id)
+  }}
+  onComplete={(id) => dismissNotification(id)}
+  onSettle={(id) => markSeen(id)}
+/>
+```
+
+**Source:** [`approval-request-notification-tile.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/approval-request-notification-tile.tsx)

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

@@ -1,18 +1,28 @@
-<!-- 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.
+<!-- source-hash: ea69954a9208818f5e9fec008eb82366 -->
+Public API barrel file for the notifications module, re-exporting all components, hooks, utilities, and TypeScript types from their respective internal modules.
 
 ## 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` |
+**Context & Hooks**
+- `NotificationsProvider` — React context provider for managing notification state
+- `useNotifications` — Hook to access notifications context (throws if outside provider)
+- `useOptionalNotifications` — Hook to access notifications context (returns `null` if outside provider)
+
+**UI Components**
+- `NotificationDrawer` — Slide-out drawer listing all notifications
+- `NotificationTile` — Individual notification row/card component
+- `NotificationPopups` — Floating toast-style popup notifications
+- `ApprovalRequestNotificationTile` — Specialized tile for approval request notifications
+
+**Utilities**
+- `approvalMetaToBatchData` — Transforms approval metadata into batch-compatible format
+- `getApprovalMeta` — Extracts approval metadata from a notification
+- `isApprovalNotification` — Type guard for approval notifications
+- `resolutionToStatus` — Maps an approval resolution to a display status
+- `ADMIN_APPROVAL_REQUEST_CONTEXT_TYPE` — Constant identifying the approval request context type
+
+**Types**
+`Notification`, `NotificationVariant`, `NotificationSeverity`, `AddNotificationInput`, `ApprovalNotificationMeta`, `ApprovalToolCallMeta`, `RenderNotificationTile`, and associated `Props` types.
 
 ## Usage Example
 
@@ -21,37 +31,31 @@ import {
   NotificationsProvider,
   useNotifications,
   NotificationDrawer,
-  NotificationTile,
-} from '@/notifications'
+  NotificationPopups,
+  isApprovalNotification,
+} from '@openframe-oss-lib/notifications'
+import type { AddNotificationInput, NotificationSeverity } from '@openframe-oss-lib/notifications'
 
-import type {
-  Notification,
-  NotificationVariant,
-  AddNotificationInput,
-} from '@/notifications'
-
-// Wrap your app with the provider
 function App() {
   return (
     <NotificationsProvider>
+      <NotificationPopups position="bottom-right" />
       <NotificationDrawer />
-      <MainContent />
+      <MyContent />
     </NotificationsProvider>
   )
 }
 
-// Consume notifications in a child component
-function MainContent() {
+function MyContent() {
   const { addNotification } = useNotifications()
 
-  const notify = () => {
-    const input: AddNotificationInput = {
-      variant: 'success' as NotificationVariant,
-      message: 'Operation completed successfully',
-    }
+  const notify = (message: string, severity: NotificationSeverity) => {
+    const input: AddNotificationInput = { message, severity }
     addNotification(input)
   }
 
-  return <button onClick={notify}>Notify</button>
+  return <button onClick={() => notify('Task complete', 'success')}>Notify</button>
 }
-```
+```
+
+**Source:** [`src/notifications/index.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/notifications/index.ts)

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

@@ -1,34 +1,47 @@
-<!-- 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`.
+<!-- source-hash: e58046aa012c4e92bb2fca43c4247d8a -->
+A slide-over drawer component that displays unread notifications with infinite scroll, toggle controls for popup/desktop notifications, and a history navigation button. It renders either within an `AppLayout` panel or falls back to a full viewport `Drawer` depending on the host context.
 
 ## 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 |
+- **`NotificationDrawer`** — Primary export. Reads state from `useOptionalNotifications()` context and renders within `AppLayoutDrawer` or fallback `Drawer` based on layout context detection.
+- **`DrawerScrollList`** — Scrollable notification list with `IntersectionObserver`-based infinite scroll; renders `NotificationTile` items or custom tiles via `renderTile`.
+- **`DrawerLoadingTiles`** — Animated skeleton placeholders shown during paginated load.
+- **`EmptyState`** — Displayed when there are no unread notifications.
+- **`ShowNotificationsToggleRow`** — Switch to toggle in-app popup notifications.
+- **`DesktopNotificationsToggleRow`** — Switch to enable browser push notifications; requests permission on enable, disables itself if permission is denied, and hides on unsupported platforms (SSR, iOS Safari).
+- **`NotificationsHistoryButton`** — `SplitButton` that navigates to notification history inline or opens it in a new tab.
 
 ## Usage Example
 
 ```typescript
+// Wrap your app with NotificationsProvider, then render the drawer:
 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 }) {
+function AppShell() {
   return (
-    <NotificationsProvider
-      notifications={notifications}
-      onHistoryClick={() => router.push('/notifications/history')}
-    >
-      {children}
-      <NotificationDrawer liveDurationMs={5000} />
+    <NotificationsProvider>
+      <AppLayout>
+        <MainContent />
+        <NotificationDrawer
+          liveDurationMs={5000}
+          loadMoreRootMargin="300px"
+          renderTile={(notification, handlers) => (
+            <CustomNotificationTile
+              key={notification.id}
+              notification={notification}
+              {...handlers}
+            />
+          )}
+        />
+      </AppLayout>
     </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.
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `liveDurationMs` | `number` | — | Auto-dismiss duration for live tiles |
+| `loadMoreRootMargin` | `string` | `"200px"` | IntersectionObserver root margin for pagination trigger |
+| `renderTile` | `RenderNotificationTile` | ctx default | Custom tile renderer; falls back to `NotificationTile` |
+| `className` | `string` | — | Additional classes on the drawer panel |

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

@@ -0,0 +1,51 @@
+<!-- source-hash: c70868cc8411a9927a06dea4d9d98ea5 -->
+Renders a fixed-position overlay of live notification popups, automatically filtering, limiting, and positioning toast-style alerts that have not yet been read or settled.
+
+## Key Components
+
+### Types & Interfaces
+
+- **`NotificationPopupsPosition`** — Union type for popup placement: `'top-right'`, `'top-left'`, `'bottom-right'`, `'bottom-left'`
+- **`NotificationPopupsProps`** — Component props interface
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `className` | `string` | — | Additional CSS classes |
+| `liveDurationMs` | `number` | `4000` | How long a notification stays "live" in ms |
+| `maxVisible` | `number` | `4` | Maximum simultaneous popups |
+| `position` | `NotificationPopupsPosition` | `'top-right'` | Screen corner placement |
+| `hideWhenDrawerOpen` | `boolean` | `true` | Hides popups when notification drawer is open |
+| `renderTile` | `RenderNotificationTile` | — | Custom tile renderer (overrides context renderer) |
+
+### `NotificationPopups` (main export)
+
+Consumes `useOptionalNotifications` context and renders filtered, time-bounded notifications as accessible popup tiles. Supports both custom (`renderTile`) and default (`NotificationTile`) rendering. Handles click and keyboard (`Enter`/`Space`) activation, delegating to `notification.onClick`, or opening the drawer and settling the notification.
+
+## Usage Example
+
+```typescript
+import { NotificationPopups } from './notification-popups'
+
+// Basic usage — top-right corner, 4s live window
+<NotificationPopups />
+
+// Custom position and duration
+<NotificationPopups
+  position="bottom-left"
+  liveDurationMs={6000}
+  maxVisible={3}
+  hideWhenDrawerOpen={false}
+/>
+
+// Custom tile renderer
+<NotificationPopups
+  position="top-right"
+  renderTile={(notification, { liveDurationMs }) => (
+    <MyCustomTile notification={notification} duration={liveDurationMs} />
+  )}
+/>
+```
+
+> **Note:** `NotificationPopups` returns `null` if rendered outside a `NotificationsProvider`, `showPopups` is false, or no unread/unsettled notifications exist within the live window.

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

@@ -1,39 +1,55 @@
-<!-- source-hash: bd12c42181c375131ca22d95cc9d9e24 -->
-A self-contained notification tile component that renders a single notification with live/settled state management, auto-dismiss timing, and a progress bar animation.
+<!-- source-hash: 1ba572f673818df9756a2a78c2e0d6ad -->
+A client-side React component that renders a single notification tile with live auto-dismiss countdown, severity-based styling, image fallback, and accessible dismiss/complete controls.
 
 ## Key Components
 
-- **`NotificationTileProps`** — Interface defining the tile's configuration:
-  - `notification` — The `Notification` object to display
-  - `liveDurationMs` — Auto-settle duration in ms (default: `4000`)
-  - `onComplete` — Callback fired when the user marks the notification as done
-  - `onSettle` — Callback fired when the notification auto-dismisses or is manually closed
+### `NotificationTileProps`
+| Prop | Type | Description |
+|------|------|-------------|
+| `notification` | `Notification` | Core notification data (id, title, description, severity, etc.) |
+| `liveDurationMs` | `number` | Auto-dismiss window in ms (default: `4000`) |
+| `onComplete` | `(id: string) => void` | Called when user marks notification complete |
+| `onSettle` | `(id: string) => void` | Called when countdown expires or user dismisses live tile |
+| `paused` | `boolean` | Freezes the countdown without settling the notification |
+| `actions` | `ReactNode` | Action row rendered inside the padded section (e.g. approval buttons) |
+| `children` | `ReactNode` | Extra content below the padded section; bring your own top divider |
 
-- **`NotificationTile`** — Main exported component that:
-  - Determines `isLive` state based on `read`, `settled`, and elapsed time since `createdAt`
-  - Uses a `useEffect` timer to auto-call `onSettle` after the remaining live duration
-  - Shows a dismiss (`XmarkIcon`) button while live, swapping to a complete (`CheckCircleIcon`) button once settled
-  - Renders a CSS progress bar (`toast-progress` animation) anchored to `liveDurationMs` with a negative `animationDelay` to account for already-elapsed time
+### Internal Logic
+- **`accentVariant`** — maps backend `NotificationSeverity` (`INFO`, `SUCCESS`, `WARNING`, `DANGER`) to a `NotificationVariant`; falls back to `notification.variant`.
+- **`isLive`** — `true` when the notification is unread, unsettled, and within the `liveDurationMs` window.
+- **`failedImageUrl`** — tracks broken image URLs so the component falls back to the `icon` slot or a severity-colored dot.
+- **Progress bar** — animates via a CSS `toast-progress` keyframe using `animationDelay` to account for elapsed time since creation.
+- **Dual button slot** — dismiss (`XmarkIcon`) and complete (`CheckCircleIcon`) share one 16 px slot; the inactive button is `aria-hidden`, `disabled`, and `tabIndex={-1}`.
 
 ## Usage Example
 
 ```typescript
 import { NotificationTile } from './notification-tile'
 
-const notification = {
-  id: 'notif-1',
-  variant: 'success',
-  title: 'Ticket resolved',
-  description: 'Ticket #4821 has been closed.',
-  createdAt: Date.now(),
-  read: false,
-  settled: false,
+function NotificationFeed() {
+  const notification = {
+    id: 'notif-1',
+    title: 'Ticket #4821 updated',
+    description: 'A technician has responded to your request.',
+    severity: 'INFO' as const,
+    variant: 'info' as const,
+    createdAt: Date.now() - 1000,
+    read: false,
+    settled: false,
+  }
+
+  return (
+    <NotificationTile
+      notification={notification}
+      liveDurationMs={5000}
+      onSettle={(id) => console.log('dismissed', id)}
+      onComplete={(id) => console.log('completed', id)}
+      actions={
+        <button type="button">Approve</button>
+      }
+    />
+  )
 }
+```
 
-<NotificationTile
-  notification={notification}
-  liveDurationMs={5000}
-  onComplete={(id) => markComplete(id)}
-  onSettle={(id) => settleNotification(id)}
-/>
-```
+**Source:** [`notification-tile.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/notification-tile.tsx)

package/src/components/features/notifications/.notifications-context.md

@@ -1,73 +1,70 @@
-<!-- source-hash: c21d20125d1c832d1265f5a500b7053e -->
-React context provider managing in-app notification state, including add, read, settle, remove, and panel open/close operations via a reducer pattern.
+<!-- source-hash: 87176a6bcad1178d52fbb050df93200a -->
+React context module that manages notification state for the OpenFrame notifications system, providing CRUD operations, read/settled tracking, drawer open/close control, and optional server-side persistence callbacks.
 
 ## Key Components
 
 ### `NotificationsProvider`
-Wraps your app (or a subtree) to supply notification state. Uses `useReducer` for immutable state transitions and `useCallback`/`useMemo` for stable references.
+Top-level provider that initializes state via `useReducer` and exposes all notification operations through context. Accepts pagination props (`hasMore`, `isLoadingMore`, `onLoadMore`), popup visibility controls, desktop OS notification opt-in, and a custom tile renderer override.
 
-**Props:**
+### `NotificationsActions`
+Optional server-side callback hooks — `onMarkRead`, `onMarkAllRead`, `onRemove`, `onMarkSettled` — fired after local state updates for persistence sync.
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `initialNotifications` | `Notification[]` | `[]` | Seed the store on mount |
-| `maxNotifications` | `number` | `50` | Hard cap; oldest entries are trimmed |
-| `defaultShowPopups` | `boolean` | `true` | Initial popup visibility |
-| `onShowPopupsChange` | `(v: boolean) => void` | — | Callback on popup toggle |
-| `onHistoryClick` | `() => void` | — | Callback for "view history" action |
+### Internal `reducer`
+Handles `add`, `upsert`, `set`, `markRead`, `markAllRead`, `markSettled`, `remove`, and `clear` actions. The `upsert` action preserves position on update; `add` prepends and promotes to top. Both respect `maxNotifications`.
 
 ### `useNotifications`
-Primary hook — throws if called outside the provider.
+Strict hook — throws if called outside `<NotificationsProvider>`.
 
 ### `useOptionalNotifications`
-Safe hook — returns `null` instead of throwing; useful for components that optionally participate in the notification system.
-
-### `reducer`
-Pure state reducer handling: `add`, `markRead`, `markAllRead`, `markSettled`, `remove`, `clear`.
+Soft hook — returns `null` when no provider is present, safe for optional integration.
 
 ## Usage Example
 
 ```typescript
-import { NotificationsProvider, useNotifications } from './notifications-context'
+import {
+  NotificationsProvider,
+  useNotifications,
+} from './notifications-context'
 
-// 1. Wrap your app
-export default function App() {
+// Wrap your app or feature subtree
+function App() {
   return (
-    <NotificationsProvider maxNotifications={100} defaultShowPopups={true}>
-      <Dashboard />
+    <NotificationsProvider
+      maxNotifications={100}
+      defaultShowPopups={true}
+      hasMore={true}
+      isLoadingMore={false}
+      onLoadMore={() => fetchMoreNotifications()}
+      actions={{
+        onMarkRead: async (id) => await api.markRead(id),
+        onRemove: async (id) => await api.deleteNotification(id),
+      }}
+    >
+      <NotificationsBell />
     </NotificationsProvider>
   )
 }
 
-// 2. Consume in any child component
-function Dashboard() {
-  const { addNotification, unreadCount, markAllRead, toggle } = useNotifications()
-
-  const notify = () =>
-    addNotification({
-      title: 'Ticket Updated',
-      description: 'Ticket #1042 was resolved by Mingo AI.',
-      color: 'success',
-    })
+// Consume in any child component
+function NotificationsBell() {
+  const { unreadCount, addNotification, markAllRead, toggle } = useNotifications()
 
   return (
-    <>
-      <button onClick={notify}>Trigger</button>
-      <button onClick={toggle}>Inbox ({unreadCount})</button>
+    <button onClick={toggle}>
+      Bell ({unreadCount})
+      <button onClick={() => addNotification({ title: 'New alert', body: 'Something happened' })}>
+        Add
+      </button>
       <button onClick={markAllRead}>Mark all read</button>
-    </>
+    </button>
   )
 }
 ```
 
-## Context Value Reference
+## Notes
+
+- `upsert` vs `add`: `add` promotes the item to the top of the list on collision; `upsert` updates in place.
+- `actionsRef` pattern prevents stale closures when persistence callbacks change between renders.
+- `desktopPopupsConfigured` is `true` only when `onShowDesktopPopupsChange` is provided, gating the OS-level toggle in the UI.
 
-| Method / Property | Description |
-|---|---|
-| `notifications` | Full ordered array, newest first |
-| `unreadCount` | Derived count of unread items |
-| `isOpen` | Panel open state |
-| `addNotification(input)` | Adds entry, returns generated `id` |
-| `markSettled(id)` | Marks a notification as acted upon (e.g. hides progress) |
-| `open / close / toggle` | Control panel visibility |
-| `setShowPopups(bool)` | Toggle toast popups globally |
+**Source:** [`notifications-context.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/notifications-context.tsx)

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

@@ -1,45 +1,65 @@
-<!-- source-hash: 30636d800aad270ef8c49d64c5fe172d -->
-Defines TypeScript types for the notification system, including variant styles, notification shape, and input for creating new notifications.
+<!-- source-hash: 606f3b966d2c642c11c978923ae677cd -->
+Core type definitions and utility functions for the notification system, including approval-request notifications used by the Mingo AI approval workflow.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `NotificationVariant` | `type` | Union type for notification styles: `default`, `success`, `warning`, `error`, `info` |
-| `Notification` | `interface` | Full notification object shape including metadata and state |
-| `AddNotificationInput` | `type` | Partial input type for creating notifications, omitting auto-generated fields |
+### Types & Interfaces
+
+| Name | Description |
+|---|---|
+| `Notification` | Core notification shape with display, metadata, and interaction fields |
+| `AddNotificationInput` | Omits auto-generated fields (`id`, `createdAt`) for consumer-facing `addNotification` calls |
+| `NotificationVariant` | Visual style: `default` · `success` · `warning` · `error` · `info` |
+| `NotificationSeverity` | Backend severity level: `INFO` · `SUCCESS` · `WARNING` · `DANGER` |
+| `RenderNotificationTile` | Override callback to replace the default tile renderer per notification |
+| `ApprovalNotificationMeta` | Approval payload stored in `notification.meta` for `ADMIN_APPROVAL_REQUEST` notifications |
+| `ApprovalToolCallMeta` | Single planned tool invocation awaiting admin approval |
+
+### Utility Functions
+
+| Name | Description |
+|---|---|
+| `isApprovalNotification` | Guards whether a notification carries an approval request via `meta.contextType` |
+| `getApprovalMeta` | Safely extracts and validates `ApprovalNotificationMeta` from a notification; returns `null` on mismatch |
+| `resolutionToStatus` | Maps backend `ApprovalResolution` strings (`PENDING`, `APPROVED`, `REJECTED`, `CANCELLED`) to `ChatApprovalStatus` |
+| `approvalMetaToBatchData` | Converts `ApprovalNotificationMeta` to an `ApprovalBatchData` payload for chat approval batches |
+
+### Constants
+
+- **`ADMIN_APPROVAL_REQUEST_CONTEXT_TYPE`** — discriminator string (`"ADMIN_APPROVAL_REQUEST"`) matched against `notification.meta.contextType`
 
 ## Usage Example
 
 ```typescript
-import type { Notification, AddNotificationInput, NotificationVariant } from './types'
+import {
+  isApprovalNotification,
+  getApprovalMeta,
+  resolutionToStatus,
+  approvalMetaToBatchData,
+} from './types'
 
-// Creating a new notification input
-const input: AddNotificationInput = {
-  variant: 'success',
-  title: 'Ticket Resolved',
-  description: 'Issue #1042 has been closed successfully.',
-  meta: { ticketId: '1042' }
-}
+// Check and extract approval metadata
+if (isApprovalNotification(notification)) {
+  const approval = getApprovalMeta(notification)
+
+  if (approval) {
+    // Map resolution to a UI status
+    const status = resolutionToStatus(approval.resolution)
 
-// Full notification object (after system assigns id, createdAt, etc.)
-const notification: Notification = {
-  id: 'notif-abc123',
-  variant: 'error',
-  title: 'Connection Failed',
-  description: 'Unable to reach the RMM agent.',
-  createdAt: Date.now(),
-  read: false,
-  settled: false,
-  meta: { agentId: 'agent-007' }
+    // Build the batch payload for the chat approval component
+    const batchData = approvalMetaToBatchData(approval)
+  }
 }
 
-// Using the variant type directly
-const variant: NotificationVariant = 'warning'
+// Add a basic notification (id and createdAt are optional)
+const input: AddNotificationInput = {
+  title: 'Ticket #1042 Updated',
+  variant: 'success',
+  severity: 'SUCCESS',
+  onClick: () => router.push('/tickets/1042'),
+}
 ```
 
-## Notes
+## Source
 
-- `title` and `description` accept `ReactNode`, allowing rich content (strings, JSX elements).
-- `AddNotificationInput` makes `id` and `createdAt` optional, allowing the system to auto-generate them.
-- `meta` is an open-ended `Record<string, unknown>` for attaching arbitrary contextual data.
+[`types.ts` on GitHub](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/types.ts)

package/src/components/features/ticket-status-config-list/.ticket-status-config-list.md

@@ -0,0 +1,51 @@
+<!-- source-hash: 554e4c4e5d119f255ff40e907298f913 -->
+A drag-and-drop sortable list component for configuring ticket status ordering, built on `@dnd-kit/core` and `@dnd-kit/sortable`.
+
+## Key Components
+
+- **`TicketStatusConfigList<T>`** — Generic sortable list container. Accepts any item type with an `id: string` field, manages DnD sensors (pointer with 4px activation threshold + keyboard), and delegates row rendering to a consumer-supplied `renderRow` prop.
+- **`SortableRow`** — Internal render-prop component that wraps each list item with `useSortable`, applies CSS transforms/transitions, and elevates `z-index` while dragging to prevent items from rendering beneath siblings.
+- **`SortableRowRenderArgs`** — Interface exposing `dragHandleProps`, `dragHandleAttributes`, and `isDragging` to the row renderer, allowing custom drag handle placement.
+- **`TicketStatusConfigListProps<T>`** — Props interface for the list component.
+
+## Usage Example
+
+```typescript
+import {
+  TicketStatusConfigList,
+  type SortableRowRenderArgs,
+} from './ticket-status-config-list'
+
+const statuses = [
+  { id: 'open',        label: 'Open' },
+  { id: 'in-progress', label: 'In Progress' },
+  { id: 'closed',      label: 'Closed' },
+]
+
+function StatusSettings() {
+  const [items, setItems] = React.useState(statuses)
+
+  const handleReorder = (oldIndex: number, newIndex: number) => {
+    setItems(prev => {
+      const next = [...prev]
+      next.splice(newIndex, 0, next.splice(oldIndex, 1)[0])
+      return next
+    })
+  }
+
+  return (
+    <TicketStatusConfigList
+      items={items}
+      onReorder={handleReorder}
+      renderRow={(item, { dragHandleProps, dragHandleAttributes, isDragging }: SortableRowRenderArgs) => (
+        <div style={{ opacity: isDragging ? 0.5 : 1 }}>
+          <span {...dragHandleProps} {...dragHandleAttributes}>⠿</span>
+          {item.label}
+        </div>
+      )}
+    />
+  )
+}
+```
+
+The `onReorder` callback receives raw `oldIndex`/`newIndex` values — the parent is responsible for applying the reorder to its own state.