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

package/src/components/tickets/hooks/.use-ticket-actions.md

@@ -1,39 +1,32 @@
-<!-- source-hash: 6164b984e1688be647fedf5037a794eb -->
-Brief description of the file's purpose: This hook encapsulates all ticket write operations (create, update, close, reopen, reply) for the Flamingo/OpenFrame tickets UI, routing them through a single `/api/chat/agent/ticket-action` endpoint with single-flight protection, per-row mutexes, a serialization queue, and mirror-sync retry logic.
+<!-- source-hash: 972f5fe6b007673ab1eb81a819bd300b -->
+Orchestrates all ticket write operations (create, update, close, reopen, reply) through a single POST endpoint, with optimistic UI updates, per-row mutex guards, a serialized mutation queue, and mirror-sync retry logic.
 
 ## Key Components
 
-### `useTicketActions(options: UseTicketActionsOptions): UseTicketActionsReturn`
-The primary exported hook. Accepts callback options from the parent and returns ticket action handlers plus loading state selectors.
-
-### `UseTicketActionsOptions`
-Configuration interface injected by the parent component:
-- `prependOptimistic` — adds an optimistic placeholder row to the QueryClient cache before the server roundtrip
-- `removeOptimistic` — removes the placeholder on mirror-sync failure or real ticket arrival
-- `removeTicketFromCache` — silent cache removal on `TICKET_NOT_FOUND`
-- `toast` — notification helper (injected for testability)
-- `onSupportSystemDown` — called on `412 HUBSPOT_DISCONNECTED`
-
-### `UseTicketActionsReturn`
-Returned handler surface:
-- `submitTicket(input)` — creates a new ticket with subject, content, and optional attachments
-- `sendMessage(ticket, text, attachments)` — sends a combined reply note
-- `closeTicket(ticket, resolution?)` — closes a ticket
-- `reopenTicket(ticket)` — reopens a closed ticket
-- `isSubmittingForm` — boolean loading state for form-level submission
-- `isRowBusy(localId)` — per-row busy predicate for UI disabling
-
-### `TicketRef`
-Decouples the local mirror UUID (`id`) from the HubSpot external id (`external_id`), both required for correct mutex and server routing.
+### Hook
+
+**`useTicketActions(options)`** — Returns all ticket mutation helpers and associated state selectors.
+
+### Interfaces
+
+| Interface | Purpose |
+|---|---|
+| `UseTicketActionsOptions` | Inbound callbacks: `prependOptimistic`, `removeOptimistic`, `removeTicketFromCache`, `toast`, `onSupportSystemDown` |
+| `UseTicketActionsReturn` | Outbound actions and state selectors |
+| `TicketRef` | Decouples the local mirror UUID (`id`) from the HubSpot external ID (`external_id`) |
+| `TicketActionResponse` | Flat wire shape from `/api/chat/agent/ticket-action` |
 
 ### Internal Mechanisms
-| Mechanism | Purpose |
+
+| Mechanism | Description |
 |---|---|
-| `formInFlightRef` + `isSubmittingForm` | Prevents duplicate form submits across async ticks |
-| `busyRowsRef` + `busyRows` | Per-row mutex preventing fan-out on the same ticket row |
-| `queueRef` / `enqueue` | Depth-1 serial queue preventing server rate-limit stampedes |
-| `watchMirrorSync` | 3s/6s/12s backoff refetch loop when `mirror_synced === false`; drops placeholder after 30s cap |
-| `watcherControllersRef` | `AbortController` map; aborted on unmount and on duplicate-submit replacement |
+| `formInFlightRef` + `isSubmittingForm` | Ref/state split prevents duplicate form submits in the same tick |
+| `busyRowsRef` + `busyRows` | Per-row `Set<string>` mutex; `isRowBusy(localId)` drives row-level UI disable |
+| `enqueue()` | Depth-1 promise queue serializes all mutations; prevents server rate-limit stampedes |
+| `watcherControllersRef` | Tracks `AbortController` per placeholder for mirror-sync backoff refetches; cleaned up on unmount |
+| `replyErrorByTicket` | Persisted `Map<externalId, error>` powers the inline reply-failure banner in `<TicketDetailDrawer>` |
+| `REPLY_BANNER_CODES` | Subset of `TicketActionErrorCode` values that surface in the inline banner vs. toast-only |
+| `MIRROR_SYNC_BACKOFF_MS` | `[3000, 6000, 12000]` ms retry schedule (~21s cumulative); drops placeholder after exhaustion |
 
 ## Usage Example
 
@@ -45,33 +38,53 @@ const {
   reopenTicket,
   isSubmittingForm,
   isRowBusy,
+  replyErrorFor,
+  clearReplyError,
 } = useTicketActions({
   prependOptimistic: (placeholder) => {
-    queryClient.setQueryData(['tickets'], (old: TicketData) => ({
-      ...old,
-      tickets: [placeholder, ...(old?.tickets ?? [])],
-    }))
-  },
-  removeOptimistic: (id) => {
-    queryClient.setQueryData(['tickets'], (old: TicketData) => ({
-      ...old,
-      tickets: old?.tickets.filter((t) => t.id !== id) ?? [],
+    queryClient.setQueryData(['tickets'], (prev: TicketData) => ({
+      ...prev,
+      tickets: [placeholder, ...prev.tickets],
     }))
   },
-  removeTicketFromCache: (ticketId) => { /* cache mutation */ },
+  removeOptimistic: (placeholderId) => { /* remove from cache */ },
+  removeTicketFromCache: (ticketId) => { /* evict row */ },
   toast,
   onSupportSystemDown: () => setSupportSystemDown(true),
 })
 
-// Create a ticket
+// Create a new ticket
 const ok = await submitTicket({
-  subject: 'VPN not connecting',
-  content: 'Unable to connect since this morning.',
+  subject: 'Outlook keeps crashing',
+  content: 'Happens on every launch since the last update.',
+  attachments: [],
 })
 
-// Close a ticket
+// Reply with text + attachments in one HubSpot Note
+await sendMessage(
+  { id: 'uuid-123', external_id: 'hs-456' },
+  'Reproduced — pushing a fix now.',
+  [attachment],
+)
+
+// Close with resolution note
 await closeTicket(
-  { id: ticket.id, external_id: ticket.external_id },
-  'Resolved by restarting the VPN client.'
+  { id: 'uuid-123', external_id: 'hs-456' },
+  'Resolved by rolling back the update.',
 )
-```
+
+// Disable a row while its action is in flight
+<button disabled={isRowBusy(ticket.id)}>Close</button>
+
+// Show inline reply error banner
+const replyError = replyErrorFor(ticket.external_id)
+{replyError && (
+  <ReplyErrorBanner error={replyError} onDismiss={() => clearReplyError(ticket.external_id)} />
+)}
+```
+
+## Notes
+
+- All mutations route through `executeTicketAction()`, which calls `embedAuthedFetch` with bearer/act-as headers — the same auth path as the chat agent.
+- `TicketRef.id` (UUID) and `TicketRef.external_id` (HubSpot numeric ID) must be kept distinct; swapping them causes either a React mutex miss or a HubSpot 404.
+- Source: [`use-ticket-actions.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-ticket-actions.ts)

package/src/components/tickets/hooks/.use-ticket-engagements.md

@@ -1,42 +1,42 @@
-<!-- source-hash: 14e8fee946105e4d0d83a53313cfd255 -->
-Fetches the conversation timeline (notes, messages, and attachments) for a single HubSpot ticket, powering the ticket drawer's timeline view. Intentionally separate from the ticket list hook since engagements require expensive multi-stage API calls and are only loaded on demand.
+<!-- source-hash: 0e3b0537d223c117b5e9ba85795c3235 -->
+Fetches and manages the conversation timeline (Note engagements and attachments) for a single ticket, powering the drawer's timeline view with optional live-polling support.
 
 ## Key Components
 
 ### Interfaces
 
-| Interface | Description |
-|---|---|
-| `TicketEngagementFile` | Attachment metadata: `id`, `name`, `url`, `mime`, `size` |
-| `TicketEngagement` | A single timeline entry with body, author info (`authorRole`, `authorName`, `authorEmail`, `authorAvatarUrl`), timestamp, and attachments |
-| `UseTicketEngagementsReturn` | Return shape: `engagements`, `isLoading`, `isFetching`, `error`, `refetch` |
+- **`TicketEngagementFile`** — Attachment metadata: `id`, `name`, `url`, `mime`, `size`
+- **`TicketEngagement`** — A single timeline entry with `body`, `authorRole` (`'customer' | 'support'`), resolved `authorName`/`authorEmail`/`authorAvatarUrl`, `createdAt`, and `attachments`
+- **`UseTicketEngagementsReturn`** — Hook return shape: `engagements`, `isLoading`, `isFetching`, `error`, `refetch`
 
 ### Hook
 
-**`useTicketEngagements(externalTicketId, enabled?)`** — Queries `/api/chat/agent/list-engagements` via `embedAuthedFetch`. Skips execution for anonymous users, missing ticket IDs, and optimistic `temp-*` placeholders. Caching is intentionally disabled (`staleTime: 0`, `gcTime: 0`) so every drawer-open reflects live HubSpot state.
+**`useTicketEngagements(externalTicketId, enabled?, refetchInterval?)`**
+
+- Skips fetching for optimistic (`temp-*`) ticket IDs and unauthenticated (`anon`) identities
+- Posts to `/api/chat/agent/list-engagements` via `embedAuthedFetch`
+- Disables all caching (`staleTime: 0`, `gcTime: 0`) to ensure HubSpot truth on every drawer open
+- Supports configurable live-polling via `refetchInterval`; polling automatically stops when the drawer unmounts
+- Fixes a skeleton double-flash by treating a fetchable ticket as "loading" from the very first render, even before `useChatIdentity` resolves
 
 ## Usage Example
 
 ```typescript
-const { engagements, isLoading, error, refetch } = useTicketEngagements(ticket.externalId)
-
-if (isLoading) return <Spinner />
-if (error) return <ErrorBanner message={error.message} />
-
-return (
-  <Timeline>
-    {engagements.map(e => (
-      <TimelineEntry
-        key={e.id}
-        body={e.body}
-        role={e.authorRole}   // 'customer' | 'support'
-        author={e.authorName}
-        avatarUrl={e.authorAvatarUrl}
-        attachments={e.attachments}
-      />
-    ))}
-  </Timeline>
+// Basic usage — fetch once when drawer opens
+const { engagements, isLoading, error } = useTicketEngagements(ticket.externalId)
+
+// Live-polling variant — refresh every 15 seconds while drawer is open
+const TICKET_LIVE_POLL_MS = 15_000
+
+const { engagements, isFetching, refetch } = useTicketEngagements(
+  ticket.externalId,
+  true,
+  TICKET_LIVE_POLL_MS,
 )
 ```
 
-> **Security note:** The server-side route enforces ticket ownership via `ticketBelongsToCustomer` before returning notes — customers cannot enumerate another customer's timeline by guessing ticket IDs.
+## Notes
+
+- Server enforces ticket ownership via `ticketBelongsToCustomer` before returning notes — customers cannot enumerate another customer's timeline by guessing ticket IDs
+- `authorName` for `support` engagements is resolved by matching the HubSpot owner email against the `profiles` table; returns `null` for non-Flamingo employees
+- For `customer` messages, `authorName`/`authorAvatarUrl` are `null` on the wire; the drawer reads live identity values for the current user's own messages

package/src/components/tickets/hooks/.use-tickets-list.md

@@ -1,36 +1,29 @@
-<!-- source-hash: 9effa67e5fd33a6782ade58cc9bf19ec -->
-Customer-scoped ticket list hook that wraps `POST /api/chat/agent/find-ticket`, supporting free-text search, status filtering, and server-side pagination with a single round-trip returning both rows and total count.
+<!-- source-hash: 6260376ea77bd4ce957bd2534ddcd997 -->
+Customer-scoped ticket list hook that wraps `POST /api/chat/agent/find-ticket`, returning paginated results with filtering support for search text and ticket status.
 
 ## Key Components
 
-### `useTicketsList(filters)`
-Main exported hook. Accepts a `UseTicketsListFilters` object and returns `UseTicketsListReturn`.
-
 ### `UseTicketsListFilters`
-| Field | Type | Description |
-|-------|------|-------------|
-| `customerEmail` | `string` | Resolved identity from parent — **must** be drilled in, not re-fetched |
-| `search` | `string?` | Free-text FTS query; empty = list all tickets |
-| `status` | `string?` | `'open'` \| `'closed'` \| `'all'` — empty/`'all'` skips filter |
-| `page` | `number?` | 1-based page number, defaults to `1` |
-| `pageSize` | `number?` | Items per page, server-capped at `100`, defaults to `20` |
+Input interface controlling the query:
+- `customerEmail` — required identity (drilled from parent to avoid race conditions with `useChatIdentity`)
+- `search` — free-text FTS filter; empty string returns all tickets
+- `status` — `'open'` | `'closed'` | `'all'` (empty/`'all'` omits the filter)
+- `page` / `pageSize` — 1-based pagination; server caps `pageSize` at 100
+- `refetchInterval` — optional polling interval (ms) for live status updates; paused on hidden tabs
 
 ### `UseTicketsListReturn`
-| Field | Type | Description |
-|-------|------|-------------|
-| `tickets` | `TicketData[]` | Current page of tickets |
-| `totalCount` | `number` | Total across all pages (drives pagination) |
-| `totalPages` | `number` | Pre-computed, clamped to ≥1 |
-| `page` / `pageSize` | `number` | Server-echoed values |
-| `isLoading` | `boolean` | `true` when no data exists for the current query slot |
-| `isFetching` | `boolean` | `true` during any background refetch |
-| `lastUpdatedAt` | `number \| null` | Wall-clock timestamp of last successful fetch |
+Output shape:
+- `tickets` — current page rows
+- `isLoading` — true when `data === undefined` or fetching with zero results (avoids TanStack v5 flag race conditions)
+- `totalCount` / `page` / `pageSize` / `totalPages` — server-echoed pagination metadata; `totalPages` is clamped to ≥ 1
+- `lastUpdatedAt` — wall-clock timestamp of last successful fetch
 
-## Cache Behavior
-
-- **Key:** `['tickets', 'self', identity, search, status, page, pageSize]` — each filter+page combo occupies its own slot
-- **Caching disabled** (`staleTime: 0`, `gcTime: 0`) — always fetches fresh data on mount, focus, and navigation
-- **Invalidation:** `useTicketActions` calls `queryClient.invalidateQueries({ queryKey: ['tickets'] })` after mutations, refreshing all slots
+### `useTicketsList(filters)`
+Core hook. Key behaviors:
+- Disabled when `customerEmail` is falsy (short-circuits the fetch)
+- Cache keyed by `['tickets', 'self', identity, search, status, page, pageSize]` — each filter/page combo gets its own slot
+- `staleTime: 0`, `gcTime: 0`, `refetchOnMount: 'always'` — deliberately no caching (live customer data)
+- Endpoint resolved from `useRequiredChatRuntime()` for reverse-proxy compatibility
 
 ## Usage Example
 
@@ -41,14 +34,15 @@ const {
   totalCount,
   totalPages,
   page,
-  pageSize,
+  refetch,
 } = useTicketsList({
   customerEmail: identity.user.email,
-  search: 'printer not working',
+  search: searchQuery,
   status: 'open',
-  page: 1,
+  page: currentPage,
   pageSize: 20,
+  refetchInterval: isDrawerOpen ? 10_000 : false,
 })
 ```
 
-> **Note:** Never call `useChatIdentity` inside this hook. Always drill `customerEmail` from the parent to avoid a null-identity race that causes an `EmptyState` flash before the first fetch fires.
+> Invalidate all ticket slots after mutations via `queryClient.invalidateQueries({ queryKey: ['tickets'] })`.

package/src/components/ui/.accordion.md

@@ -1,37 +1,39 @@
-<!-- source-hash: 81d02993dbe561b42733bf91b8d62a0e -->
-A React accordion component built on top of Radix UI primitives with custom styling and animations. This provides a fully accessible, keyboard-navigable accordion interface with smooth expand/collapse animations.
+<!-- source-hash: 22ee9a9634992447bd91b4c524998d3b -->
+Accessible accordion component built on Radix UI primitives, providing collapsible content sections with animated expand/collapse transitions and a rotating chevron indicator.
 
 ## Key Components
 
-- **`Accordion`** - Root container component (alias for `AccordionPrimitive.Root`)
-- **`AccordionItem`** - Individual accordion item wrapper with border styling
-- **`AccordionTrigger`** - Clickable header with chevron icon that rotates on expand
-- **`AccordionContent`** - Collapsible content area with custom accordion animations
+| Export | Description |
+|--------|-------------|
+| `Accordion` | Root container (re-export of `AccordionPrimitive.Root`); accepts `type="single"` or `type="multiple"` |
+| `AccordionItem` | Individual collapsible section with a bottom border |
+| `AccordionTrigger` | Clickable header with a `ChevronDown` icon that rotates 180° when open |
+| `AccordionContent` | Animated content panel using `animate-accordion-up/down` Tailwind keyframes |
 
 ## Usage Example
 
 ```typescript
-import { 
-  Accordion, 
-  AccordionItem, 
-  AccordionTrigger, 
-  AccordionContent 
-} from "./accordion"
-
-export function FAQSection() {
+import {
+  Accordion,
+  AccordionItem,
+  AccordionTrigger,
+  AccordionContent,
+} from "@/components/ui/accordion"
+
+export function FAQAccordion() {
   return (
-    <Accordion type="single" collapsible className="w-full">
+    <Accordion type="single" collapsible defaultValue="item-1">
       <AccordionItem value="item-1">
-        <AccordionTrigger>What is your return policy?</AccordionTrigger>
+        <AccordionTrigger>What is OpenFrame?</AccordionTrigger>
         <AccordionContent>
-          We offer a 30-day return policy for all items in original condition.
+          OpenFrame is a unified AI-driven platform for MSP operations.
         </AccordionContent>
       </AccordionItem>
-      
+
       <AccordionItem value="item-2">
-        <AccordionTrigger>How long does shipping take?</AccordionTrigger>
+        <AccordionTrigger>How does Mingo AI work?</AccordionTrigger>
         <AccordionContent>
-          Standard shipping takes 3-5 business days within the US.
+          Mingo AI automates IT support tasks for technicians.
         </AccordionContent>
       </AccordionItem>
     </Accordion>
@@ -39,4 +41,9 @@ export function FAQSection() {
 }
 ```
 
-The component includes built-in hover effects, smooth animations via CSS custom properties (`animate-accordion-up/down`), and automatic chevron rotation when items expand or collapse.
+## Notes
+
+- **`type="single"`** allows only one open item at a time; **`type="multiple"`** allows several.
+- Pass `collapsible` on a `single` accordion to allow closing the active item.
+- All components forward refs and accept standard Radix UI props alongside `className` for Tailwind customization.
+- Source: [`accordion.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/accordion.tsx)

package/src/components/ui/.actions-menu.md

@@ -1,31 +1,15 @@
-<!-- source-hash: 342a87b9f572574fd4c65a58c52361ef -->
-A flexible, accessible dropdown actions menu component built on Radix UI primitives, supporting grouped items, checkboxes, submenus, navigation links, and secondary icon actions.
+<!-- source-hash: d6f4857e4f0fccaffff7c8abd70a2f28 -->
+A flexible, grouped actions menu component supporting inline display and dropdown trigger modes, with items that can be plain actions, checkboxes, submenus, separators, or navigation links — each optionally enhanced with a secondary icon action.
 
 ## Key Components
 
-### Exported Components
-
-| Component | Description |
-|-----------|-------------|
-| `ActionsMenu` | Standalone menu panel (no trigger) — renders grouped items directly |
-| `ActionsMenuDropdown` | Full dropdown with a configurable trigger button and Radix-powered popover |
-
-### Internal Components
-
-| Component | Description |
-|-----------|-------------|
-| `MenuItem` | Renders a single item — handles `item`, `checkbox`, `submenu`, `separator`, and link variants |
-| `SecondaryAction` | 40px secondary icon button/link on the right side of a row, independently clickable |
-| `GroupSeparator` | Visual divider rendered between groups when `separator: true` |
-
-### Key Interfaces
-
-| Interface | Purpose |
-|-----------|---------|
-| `ActionsMenuItem` | Single menu item with optional `href`, `submenu`, `iconAction`, `checked` |
-| `ActionsMenuGroup` | Collection of items with optional separator |
-| `ActionsMenuProps` | Props for `ActionsMenu` — `groups`, `className`, `onItemClick` |
-| `ActionsMenuDropdownProps` | Extends `ActionsMenuProps` with trigger, alignment, and popover controls |
+| Export | Type | Description |
+|---|---|---|
+| `ActionsMenu` | Component | Standalone menu panel rendering grouped `ActionsMenuItem` rows |
+| `ActionsMenuDropdown` | Component | Wraps `ActionsMenu` in a Radix UI dropdown with a configurable trigger button |
+| `ActionsMenuItemIconAction` | Interface | Secondary icon button/link rendered on the right edge of a menu row |
+| `ActionsMenuItem` | Interface | Single menu row — supports `item`, `checkbox`, `submenu`, and `separator` types |
+| `ActionsMenuGroup` | Interface | Ordered collection of items with an optional visual separator |
 
 ## Usage Example
 
@@ -39,49 +23,47 @@ const groups = [
         id: "edit",
         label: "Edit",
         icon: <EditIcon />,
-        onClick: () => console.log("Edit clicked"),
+        onClick: () => console.log("edit"),
       },
-      {
-        id: "open",
-        label: "Open in new tab",
-        href: "/resource/123",
-        iconAction: {
-          icon: <ExternalLinkIcon />,
-          "aria-label": "Open in new tab",
-          href: "/resource/123",
-          openInNewTab: true,
-        },
-      },
-    ],
-    separator: true,
-  },
-  {
-    items: [
       {
         id: "notify",
         label: "Notifications",
-        type: "checkbox",
+        type: "checkbox" as const,
         checked: true,
         onClick: () => toggleNotifications(),
       },
-      { id: "sep", label: "", type: "separator" },
+    ],
+  },
+  {
+    separator: true,
+    items: [
       {
         id: "delete",
         label: "Delete",
-        disabled: true,
-        onClick: () => handleDelete(),
+        danger: true,
+        onClick: () => confirmDelete(),
       },
     ],
   },
 ];
 
-<ActionsMenuDropdown
-  groups={groups}
-  align="end"
-  side="bottom"
-  triggerAriaLabel="More actions"
-  onItemClick={(item) => console.log("Clicked:", item.id)}
-/>
+export function MyComponent() {
+  return (
+    <ActionsMenuDropdown
+      groups={groups}
+      align="end"
+      side="bottom"
+      triggerAriaLabel="Row actions"
+    />
+  );
+}
 ```
 
-> **Note:** The dropdown auto-closes after selecting a regular item but stays open for `checkbox` and `submenu` types, allowing toggling and nested navigation.
+## Notes
+
+- `closeOnSelect` defaults to closing the dropdown; set to `false` to keep it open (useful for multi-select scenarios).
+- `ActionsMenuDropdown` supports **controlled open state** via `open` + `onOpenChange`.
+- Items with `href` render as Next.js `<Link>` elements; `iconAction` renders an independent secondary `<Link>` or `<button>` on the row's right edge.
+- Submenus use Radix `DropdownMenuPrimitive.Sub` and support recursive `MenuItem` rendering.
+
+**Source:** [`actions-menu.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/actions-menu.tsx)

package/src/components/ui/.ai-generated-badge.md

@@ -0,0 +1,25 @@
+<!-- source-hash: 8efc6e7d680013ff739aca49651afb03 -->
+Renders a standardized "AI Generated" badge with a Sparkles icon, serving as the single source of truth for AI-generated content indicators across the application.
+
+## Key Components
+
+- **`AIGeneratedBadge`** — A functional component that wraps the `Badge` component with a fixed `secondary` variant, a `Sparkles` icon (12×12px), and the label "AI Generated". Accepts an optional `className` prop for additional styling.
+
+## Usage Example
+
+```typescript
+import { AIGeneratedBadge } from '@/components/ui/ai-generated-badge';
+
+// Basic usage
+<AIGeneratedBadge />
+
+// With custom positioning class
+<AIGeneratedBadge className="absolute top-2 right-2" />
+```
+
+## Notes
+
+- Replaces repeated inline `<Badge variant="secondary"><Sparkles/> AI Generated</Badge>` patterns previously copy-pasted across summary, video, and SEO editors.
+- The `className` prop is appended to the base flex layout classes, allowing layout overrides without losing default styling.
+
+**Source:** [`ai-generated-badge.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/ai-generated-badge.tsx)

package/src/components/ui/.alert-dialog.md

@@ -1,21 +1,21 @@
-<!-- source-hash: 6146e5c92352e7744ffcf239f861beb3 -->
-Accessible alert dialog component built on Radix UI's `AlertDialogPrimitive`, providing a modal confirmation pattern with animated overlay, centered content panel, and styled action/cancel buttons using Tailwind CSS.
+<!-- source-hash: 987a3c72b70286ca2d2102e429fad6b4 -->
+Accessible alert dialog component built on Radix UI primitives, providing a modal confirmation dialog with overlay, animations, and styled action/cancel buttons using the OpenFrame design system.
 
 ## Key Components
 
 | Export | Description |
-|--------|-------------|
-| `AlertDialog` | Root component (Radix `Root`) managing open/close state |
+|---|---|
+| `AlertDialog` | Root component wrapping Radix `AlertDialogPrimitive.Root` |
 | `AlertDialogTrigger` | Element that opens the dialog |
-| `AlertDialogPortal` | Renders dialog outside the DOM hierarchy |
-| `AlertDialogOverlay` | Fixed dark backdrop with fade animations |
-| `AlertDialogContent` | Centered modal panel with zoom/slide entrance animations |
+| `AlertDialogPortal` | Renders dialog outside the DOM tree |
+| `AlertDialogOverlay` | Fixed backdrop with fade animations |
+| `AlertDialogContent` | Centered modal panel with slide/zoom animations |
 | `AlertDialogHeader` | Layout wrapper for title and description |
-| `AlertDialogFooter` | Responsive action button row (stacked on mobile, inline on md+) |
-| `AlertDialogTitle` | Semibold heading (`text-lg font-semibold`) |
-| `AlertDialogDescription` | Muted body text (`text-sm text-muted-foreground`) |
-| `AlertDialogAction` | Confirm button styled with default `buttonVariants()` |
-| `AlertDialogCancel` | Dismiss button styled with `buttonVariants({ variant: "outline" })` |
+| `AlertDialogFooter` | Layout wrapper for action buttons (stacked on mobile, inline on desktop) |
+| `AlertDialogTitle` | Styled title using `text-h3` |
+| `AlertDialogDescription` | Muted subtitle using `text-h6` |
+| `AlertDialogAction` | Confirm button using default `buttonVariants()` |
+| `AlertDialogCancel` | Dismiss button using `outline` button variant |
 
 ## Usage Example
 
@@ -40,13 +40,13 @@ export function DeleteConfirmDialog() {
         <AlertDialogHeader>
           <AlertDialogTitle>Are you sure?</AlertDialogTitle>
           <AlertDialogDescription>
-            This will permanently remove the device from your fleet.
+            This action cannot be undone. The device will be permanently removed.
           </AlertDialogDescription>
         </AlertDialogHeader>
         <AlertDialogFooter>
           <AlertDialogCancel>Cancel</AlertDialogCancel>
-          <AlertDialogAction onClick={() => handleDelete()}>
-            Confirm
+          <AlertDialogAction onClick={handleDelete}>
+            Confirm Delete
           </AlertDialogAction>
         </AlertDialogFooter>
       </AlertDialogContent>
@@ -55,4 +55,9 @@ export function DeleteConfirmDialog() {
 }
 ```
 
-> **Accessibility:** Inherits full Radix UI ARIA semantics — focus is trapped within the dialog when open, and keyboard (`Escape`) dismissal is handled automatically.
+## Notes
+
+- Requires a client component context (`"use client"`)
+- Overlay uses `bg-ods-overlay` from the OpenFrame design token system
+- Animations use Tailwind `animate-in`/`animate-out` data-state classes
+- Source: [`alert-dialog.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/alert-dialog.tsx)