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

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

@@ -0,0 +1,42 @@
+<!-- source-hash: 657720c9ff5bd09aed030579a70dc162 -->
+Renders an inline, collapsible approval section within a board ticket card, allowing users to approve or reject pending requests without navigating away from the board.
+
+## Key Components
+
+### `BoardTicketApproval`
+Main exported component that displays a collapsed-by-default approval panel. Renders two visual variants based on `approvalType`:
+- **`ADMIN`** — Yellow shield icon (`ShieldCheckIcon`), label "Technician approval required"
+- **`CLIENT`** (default) — Animated dots icon (`DotsLoaderIcon`), label "Pending client approval"
+
+When expanded, renders the shared `ApprovalBatchMessage` component to handle approve/reject interactions.
+
+### `BoardTicketApprovalProps`
+| Prop | Type | Description |
+|---|---|---|
+| `pendingApproval` | `BoardTicketPendingApproval` | Approval metadata (id, type, tool calls) |
+| `onApprove` | `(requestId?: string) => void \| Promise<void>` | Callback fired on approval |
+| `onReject` | `(requestId?: string) => void \| Promise<void>` | Callback fired on rejection |
+
+### Supporting hooks/utilities
+- **`useCollapsible`** — Manages animated expand/collapse height via `containerStyle` and `innerRef`
+- **`cn`** — Utility for conditional class merging
+
+## Usage Example
+
+```typescript
+import { BoardTicketApproval } from './board-ticket-approval'
+
+const pendingApproval = {
+  id: 'req_abc123',
+  approvalType: 'ADMIN',
+  toolCalls: [{ name: 'restart_service', args: { service: 'nginx' } }],
+}
+
+<BoardTicketApproval
+  pendingApproval={pendingApproval}
+  onApprove={(requestId) => console.log('Approved:', requestId)}
+  onReject={(requestId) => console.log('Rejected:', requestId)}
+/>
+```
+
+**Source:** [`board-ticket-approval.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/board-ticket-approval.tsx)

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

@@ -1,51 +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.
+<!-- source-hash: eec2d729297b9f5f1be4e627c13aa43f -->
+Kanban-style drag-and-drop board component built on `@dnd-kit/core`, managing multi-column ticket reordering with cross-column movement, collapse state, and a custom horizontal scrollbar.
 
 ## Key Components
 
-| Export / Symbol | Description |
+| Export | 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 |
+| `Board` | Main board component rendering columns with full DnD context |
+| `BoardProps` | Interface defining all board configuration and callback props |
+| `locate()` | Internal helper to find a ticket across all columns by ID |
+| `findIndexInColumn()` | Internal helper to find a ticket's index within a specific column |
+
+## Key Behaviors
+
+- **Collision detection** — Custom strategy combining `pointerWithin`, `rectIntersection`, and `closestCorners` to prioritize ticket-level hits over column-level hits
+- **Cross-column guards** — Respects `dropDisabled` and `allowedFromColumns` constraints; reverts state on invalid drops
+- **Optimistic UI** — `isDraggingRef` prevents external `columns` prop updates from overwriting in-flight drag state
+- **Collapse persistence** — Column collapsed state stored via `useBoardCollapse` (keyed by `collapseStorageKey`)
+- **Custom scrollbar** — Horizontal scrollbar rendered via `useHorizontalScrollbar` with pointer-drag thumb support
+- **`onChange` payload** — Emits `BoardChange` with `ticketId`, `fromColumnId`, `toColumnId`, `afterTicketId`, and `beforeTicketId` for precise ordering
 
 ## Usage Example
 
 ```typescript
+import { Board } from './board'
+import type { BoardColumnDef, BoardChange } from './types'
+
+const columns: BoardColumnDef[] = [
+  { id: 'todo', label: 'To Do', color: '#6366f1', tickets: [...] },
+  { id: 'in-progress', label: 'In Progress', color: '#f59e0b', tickets: [...] },
+  { id: 'done', label: 'Done', color: '#10b981', tickets: [...], dropDisabled: false },
+]
+
+function handleChange(change: BoardChange) {
+  console.log(`Moved ${change.ticketId} from ${change.fromColumnId} to ${change.toColumnId}`)
+  // Persist reorder to backend
+}
+
 <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} />}
+  columns={columns}
+  onChange={handleChange}
+  onLoadMore={(columnId) => fetchMoreTickets(columnId)}
+  onAddTicket={(columnId) => openCreateModal(columnId)}
+  getTicketHref={(id) => `/tickets/${id}`}
   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.
+## Source
+
+[`board.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/board.tsx)

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

@@ -1,21 +1,21 @@
-<!-- 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.
+<!-- source-hash: e95223b7a715cb1d3476318691c740eb -->
+Public client-side barrel file for the board UI module, re-exporting all components, hooks, utilities, and TypeScript types related to a Kanban-style ticket board.
 
 ## 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 |
+| `Board` | Component | Root board container component |
+| `BoardColumn` | Component | Individual column within the board |
+| `BoardColumnHeader` | Component | Header section for a board column |
+| `TicketCard`, `TicketCardView`, `TicketCardBody` | Components | Ticket card and its sub-views |
+| `BoardTicketApproval` | Component | Approval state overlay/indicator for tickets |
+| `TicketCardSkeleton` | Component | Loading skeleton 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 |
+| `tintOnDark` | Utility | Color utility for dark-mode tinting |
+| `columnFromTicketStatus` | Utility | Maps a ticket status to its board column |
+| `groupTicketsByStatus` | Utility | Groups an array of tickets by status |
+| `BoardChange`, `BoardColumnDef`, `BoardPriority`, `BoardTicket`, `BoardTicketAssignee`, `BoardTicketPendingApproval` | Types | Core domain types for board data |
 
 ## Usage Example
 
@@ -27,30 +27,27 @@ import {
   TicketCard,
   useBoardCollapse,
   groupTicketsByStatus,
+  columnFromTicketStatus,
 } 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>
-  )
-}
-```
+
+const tickets: BoardTicket[] = fetchTickets()
+const grouped = groupTicketsByStatus(tickets)
+const { collapseMap, toggleCollapse } = useBoardCollapse()
+
+return (
+  <Board>
+    {columns.map((col) => (
+      <BoardColumn key={col.id} collapsed={collapseMap[col.id]}>
+        <BoardColumnHeader column={col} onToggle={() => toggleCollapse(col.id)} />
+        {grouped[col.status]?.map((ticket) => (
+          <TicketCard key={ticket.id} ticket={ticket} />
+        ))}
+      </BoardColumn>
+    ))}
+  </Board>
+)
+```
+
+## Source
+
+[`index.ts` on GitHub](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/index.ts)

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

@@ -1,47 +1,44 @@
-<!-- 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.
+<!-- source-hash: d7f6f1d9740bf2793ab1c8cb52ff7356 -->
+Draggable and static board ticket card components for a kanban-style board view, providing both a `dnd-kit`-powered sortable card and a standalone presentational variant.
 
 ## 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 |
+| Export | 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 |
+| `TicketCardBody` | Component | Pure presentational inner content — title, device/org row, priority flag, assignees, tags, timestamp, new message badge, and approval row |
+| `TicketCardView` | Component | Static, non-draggable card using the same shell and body as the board card; suitable for embeds, previews, and marketing |
+| `TicketCard` | Component | Full draggable board card powered by `useSortable` from `@dnd-kit/sortable`; supports overlay mode, optional `href` link, and drag-disabled state |
+| `TicketCardBodyProps` | Interface | Props for the shared body: `ticket`, `columnColor`, `renderAssignSlot`, `onApprove`, `onReject` |
+| `TicketCardProps` | Interface | Extends body props with `columnId`, `href`, `isOverlay`, `dragDisabled`, and board-aware approve/reject signatures |
+
+**Constants:** `MAX_VISIBLE_TAGS = 2`, `MAX_VISIBLE_ASSIGNEES = 3`, `PRIORITY_COLOR_CLASS` maps `low | medium | high | urgent` to ODS color tokens.
 
 ## Usage Example
 
 ```typescript
-import { TicketCard } from './ticket-card'
-
+// Draggable board card (inside a <Board> with dnd-kit context)
 <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',
-  }}
+  ticket={ticket}
   columnId="in-progress"
-  href="/tickets/TKT-001"
+  columnColor="#6366f1"
+  href={`/tickets/${ticket.id}`}
+  onApprove={(ticketId, requestId) => handleApprove(ticketId, requestId)}
+  onReject={(ticketId, requestId) => handleReject(ticketId, requestId)}
 />
-```
+
+// Static preview card (no dnd-kit context required)
+<TicketCardView
+  ticket={ticket}
+  columnColor="#6366f1"
+  className="max-w-sm"
+/>
+
+// Body only, composed into a custom shell
+<TicketCardBody
+  ticket={ticket}
+  columnColor="#6366f1"
+  renderAssignSlot={(t) => <AssignButton ticketId={t.id} />}
+/>
+```
+
+**Source:** [`ticket-card.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/ticket-card.tsx)

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

@@ -1,45 +1,52 @@
-<!-- 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.
+<!-- source-hash: 4467ba51b026b94129d271b01950c09d -->
+Defines the core types, interfaces, and utility functions for the Kanban-style ticket board, including column definitions, ticket shapes, and helpers for mapping tickets to board columns.
 
 ## Key Components
 
-### Types
+### Types & Interfaces
 
-| 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 |
+| Export | Description |
+|---|---|
+| `BoardPriority` | Union type: `'low' \| 'medium' \| 'high' \| 'urgent'` |
+| `BoardTicket` | Core ticket shape with status, priority, assignees, tags, and pending approval |
+| `BoardTicketAssignee` | Assignee identity with optional avatar and initials |
+| `BoardTicketPendingApproval` | Latest pending tool-call approval attached to a ticket |
+| `BoardColumnDef` | Board column config including tickets, color, drag/drop rules, and pagination state |
+| `BoardChange` | Describes a ticket move: source/target column and surrounding ticket IDs |
 
 ### 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 |
+| Export | Description |
+|---|---|
+| `columnFromTicketStatus` | Builds a `BoardColumnDef` from a canonical `TicketStatus`, applying default label/color with optional overrides |
+| `groupTicketsByStatus` | Buckets a flat list of `BoardTicket[]` into ordered `BoardColumnDef[]` for a given set of statuses |
+
+### Internal
+
+- `STATUS_DEFAULTS` — default label and hex color for each of the six canonical statuses (`ACTIVE`, `AI_ASSISTANCE`, `TECH_REQUIRED`, `ON_HOLD`, `RESOLVED`, `ARCHIVED`)
+- `canonicalize()` — normalizes raw status strings to `TicketStatus`, including the legacy alias `ACTION_REQUIRED → TECH_REQUIRED`
 
 ## 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, {
+import {
+  columnFromTicketStatus,
+  groupTicketsByStatus,
+  type BoardTicket,
+} from './types'
+
+const tickets: BoardTicket[] = [
+  { id: '1', title: 'Printer offline', ticketNumber: 'T-001', status: 'ACTIVE' },
+  { id: '2', title: 'VPN issue', ticketNumber: 'T-002', status: 'on hold' },
+]
+
+// Group flat tickets into board columns
+const columns = groupTicketsByStatus(tickets, ['ACTIVE', 'ON_HOLD', 'RESOLVED'])
+
+// Build a single column with overrides
+const activeColumn = columnFromTicketStatus('ACTIVE', tickets, {
   label: 'In Progress',
-  isLoadingMore: true,
   total: 42,
+  hasMore: true,
 })
-```
-
-> `canonicalize` handles legacy status values automatically — `ACTION_REQUIRED` from older API responses is silently mapped to `TECH_REQUIRED` before bucketing.
+```

package/src/components/features/card-hit-layer.tsx

@@ -0,0 +1,84 @@
+"use client";
+
+/**
+ * <CardHitLayer> — THE full-bleed click target for media cards.
+ *
+ * A CONTENTLESS `<a>`/`<button>` stretched over its positioned parent. Cards
+ * that show a video with overlaid chrome (walkthrough mini player, video-bite
+ * cards) all need the same thing: the whole card is one click target, while the
+ * visible label/controls sit above it as their own positioned elements.
+ *
+ * Why contentless: putting the label INSIDE the interactive element makes the
+ * element content-sized, so it collapses around the label instead of covering
+ * the card — that produced both a mis-placed title and a mostly-unclickable
+ * card in the walkthrough widget. Separating "what you click" from "what you
+ * see" makes both deterministic.
+ *
+ * Why a component and not a copied className: the two consumers drifted (only
+ * one had `cursor-pointer`, only one covered the full card), which is exactly
+ * the class of inconsistency this exists to prevent.
+ *
+ * The host owns stacking + hover gating via `className` (e.g. `z-20`, or the
+ * bite strip's touch gating, `isTouch && !isActive`).
+ */
+
+import React from 'react';
+import { cn } from '../../utils/cn';
+
+export interface CardHitLayerProps {
+  /** Accessible name. The layer has no content, so this IS its label. */
+  label: string;
+  /** Renders an anchor when set, otherwise a button. */
+  href?: string | null;
+  onClick?: (e: React.MouseEvent) => void;
+  /** Runs before click — used to stop media synchronously (audio-blip guard). */
+  onPointerDown?: (e: React.PointerEvent) => void;
+  /** Stacking + pointer-event gating supplied by the host. */
+  className?: string;
+  /** Marquee loop-clone: keep the pointer affordance and the click, but stay
+   *  out of the a11y tree and the tab order so the duplicate copy does not
+   *  double every link. Without this, clones rendered NO hit layer at all —
+   *  so the visible half of a marquee had no pointer cursor and no click. */
+  decorative?: boolean;
+}
+
+/** Reset every UA affordance so the layer is invisible but clickable. The
+ *  pointer cursor comes from the ODS base rule (ods-interaction-states.css),
+ *  not from here — one definition for every control in the system. */
+const HIT_LAYER_BASE =
+  'absolute inset-0 block h-full w-full appearance-none border-0 bg-transparent p-0 ' +
+  // A transparent full-card button is otherwise invisible to keyboard users.
+  'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ods-focus';
+
+export function CardHitLayer({
+  label,
+  href,
+  onClick,
+  onPointerDown,
+  className,
+  decorative = false,
+}: CardHitLayerProps): React.ReactElement {
+  const a11y = decorative
+    ? { 'aria-hidden': true as const, tabIndex: -1 }
+    : { 'aria-label': label };
+  if (href) {
+    return (
+      <a
+        href={href}
+        {...a11y}
+        onClick={onClick}
+        onPointerDown={onPointerDown}
+        className={cn(HIT_LAYER_BASE, className)}
+      />
+    );
+  }
+  return (
+    <button
+      type="button"
+      {...a11y}
+      onClick={onClick}
+      onPointerDown={onPointerDown}
+      className={cn(HIT_LAYER_BASE, className)}
+    />
+  );
+}