@flamingo-stack/openframe-frontend-core 0.0.213 → 0.0.214

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

@@ -0,0 +1,54 @@
+<!-- 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.
+
+## 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` |
+
+### `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 |
+
+## 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
+
+## Usage Example
+
+```typescript
+const {
+  tickets,
+  isLoading,
+  totalCount,
+  totalPages,
+  page,
+  pageSize,
+} = useTicketsList({
+  customerEmail: identity.user.email,
+  search: 'printer not working',
+  status: 'open',
+  page: 1,
+  pageSize: 20,
+})
+```
+
+> **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.

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

@@ -1,62 +1,87 @@
-<!-- source-hash: 412b98113ff29f66e6b4391a1641cde6 -->
-A client-side React component that renders a customizable actions menu with support for nested submenus, checkboxes, separators, and external links.
+<!-- 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.
 
 ## Key Components
 
-- **`ActionsMenu`** - Main menu component that accepts grouped menu items
-- **`MenuItem`** - Individual menu item renderer with submenu support
-- **`ActionsMenuItem`** - Interface defining menu item properties (label, icon, type, callbacks)
-- **`ActionsMenuGroup`** - Interface for grouping menu items with optional separators
-- **Portal-based submenus** - Uses ReactDOM.createPortal for overflow-safe submenu positioning
+### 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 |
 
 ## Usage Example
 
 ```typescript
-import { ActionsMenu, ActionsMenuItem } from './actions-menu'
-import { Settings, Download, Share } from 'lucide-react'
+import { ActionsMenuDropdown } from "./actions-menu";
 
-const menuGroups = [
+const groups = [
   {
     items: [
       {
-        id: 'download',
-        label: 'Download',
-        icon: <Download className="w-4 h-4" />,
-        onClick: () => console.log('Download clicked')
+        id: "edit",
+        label: "Edit",
+        icon: <EditIcon />,
+        onClick: () => console.log("Edit clicked"),
       },
       {
-        id: 'share',
-        label: 'Share',
-        icon: <Share className="w-4 h-4" />,
-        type: 'submenu' as const,
-        submenu: [
-          {
-            id: 'copy-link',
-            label: 'Copy Link',
-            onClick: () => navigator.clipboard.writeText(window.location.href)
-          }
-        ]
-      }
+        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
+    separator: true,
   },
   {
     items: [
       {
-        id: 'settings',
-        label: 'Settings',
-        icon: <Settings className="w-4 h-4" />,
-        href: '/settings',
-        showExternalLinkOnHover: true
-      }
-    ]
-  }
-]
-
-<ActionsMenu 
-  groups={menuGroups}
-  onItemClick={(item) => console.log('Item clicked:', item)}
+        id: "notify",
+        label: "Notifications",
+        type: "checkbox",
+        checked: true,
+        onClick: () => toggleNotifications(),
+      },
+      { id: "sep", label: "", type: "separator" },
+      {
+        id: "delete",
+        label: "Delete",
+        disabled: true,
+        onClick: () => handleDelete(),
+      },
+    ],
+  },
+];
+
+<ActionsMenuDropdown
+  groups={groups}
+  align="end"
+  side="bottom"
+  triggerAriaLabel="More actions"
+  onItemClick={(item) => console.log("Clicked:", item.id)}
 />
 ```
 
-The component features intelligent submenu positioning, click-outside handling, keyboard navigation support, and follows a dark theme design system with customizable styling through Tailwind CSS classes.
+> **Note:** The dropdown auto-closes after selecting a regular item but stays open for `checkbox` and `submenu` types, allowing toggling and nested navigation.

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

@@ -1,50 +1,53 @@
-<!-- source-hash: 2fb4ad12bb79561506d1589576a1f441 -->
-A comprehensive Alert Dialog component built on top of Radix UI primitives, providing styled and accessible modal dialogs for confirmations, warnings, and important user interactions.
+<!-- 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.
 
 ## Key Components
 
-- **AlertDialog** - Root container component (Radix Root primitive)
-- **AlertDialogTrigger** - Button or element that opens the dialog
-- **AlertDialogContent** - Main dialog container with overlay and animations
-- **AlertDialogHeader/Footer** - Layout containers for dialog sections
-- **AlertDialogTitle** - Accessible dialog heading
-- **AlertDialogDescription** - Supporting text for the dialog
-- **AlertDialogAction** - Primary action button (styled with default button variant)
-- **AlertDialogCancel** - Cancel/dismiss button (styled with outline variant)
-- **AlertDialogOverlay** - Semi-transparent backdrop
-- **AlertDialogPortal** - Renders dialog outside normal DOM flow
+| Export | Description |
+|--------|-------------|
+| `AlertDialog` | Root component (Radix `Root`) managing open/close state |
+| `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 |
+| `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" })` |
 
 ## Usage Example
 
 ```typescript
 import {
   AlertDialog,
-  AlertDialogAction,
-  AlertDialogCancel,
+  AlertDialogTrigger,
   AlertDialogContent,
-  AlertDialogDescription,
-  AlertDialogFooter,
   AlertDialogHeader,
   AlertDialogTitle,
-  AlertDialogTrigger,
-} from "./alert-dialog"
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogAction,
+  AlertDialogCancel,
+} from "@/components/ui/alert-dialog"
 
-function DeleteConfirmation() {
+export function DeleteConfirmDialog() {
   return (
     <AlertDialog>
-      <AlertDialogTrigger asChild>
-        <button>Delete Account</button>
-      </AlertDialogTrigger>
+      <AlertDialogTrigger>Delete Device</AlertDialogTrigger>
       <AlertDialogContent>
         <AlertDialogHeader>
-          <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
+          <AlertDialogTitle>Are you sure?</AlertDialogTitle>
           <AlertDialogDescription>
-            This action cannot be undone. This will permanently delete your account.
+            This will permanently remove the device from your fleet.
           </AlertDialogDescription>
         </AlertDialogHeader>
         <AlertDialogFooter>
           <AlertDialogCancel>Cancel</AlertDialogCancel>
-          <AlertDialogAction>Delete Account</AlertDialogAction>
+          <AlertDialogAction onClick={() => handleDelete()}>
+            Confirm
+          </AlertDialogAction>
         </AlertDialogFooter>
       </AlertDialogContent>
     </AlertDialog>
@@ -52,4 +55,4 @@ function DeleteConfirmation() {
 }
 ```
 
-The component includes smooth animations, responsive design, and follows accessibility best practices through Radix UI's robust foundation.
+> **Accessibility:** Inherits full Radix UI ARIA semantics — focus is trapped within the dialog when open, and keyboard (`Escape`) dismissal is handled automatically.

package/src/components/ui/.allowed-domains-input.md

@@ -1,31 +1,40 @@
-<!-- source-hash: 935d1df99872aa31bc563c07919bee91 -->
-A React component that provides an interactive interface for managing a list of allowed domains with validation support, add/remove functionality, and error handling.
+<!-- source-hash: 4488babe1708a2df7fd49ce4d01e1ce8 -->
+A client-side React component for managing a list of allowed domains, supporting add/remove operations with optional validation, duplicate prevention, and error display.
 
 ## Key Components
 
-- **AllowedDomainsInput**: Main forwardRef component that manages domain list state
-- **AllowedDomainsInputProps**: TypeScript interface defining component props including validation callbacks
-- **addDomain()**: Function that validates and adds new domains to the list
-- **removeDomain()**: Function that removes domains by index
-- **handleKeyDown()**: Keyboard handler for Enter key submission
+### `AllowedDomainsInputProps`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `value` | `string[]` | Controlled list of current domains |
+| `onChange` | `(domains: string[]) => void` | Callback when domain list changes |
+| `onValidate` | `(domain: string) => { valid, error?, cleanedDomain? }` | Optional custom domain validator |
+| `label` | `string` | Field label (default: `"Allowed Domains"`) |
+| `placeholder` | `string` | Input placeholder (default: `"example.com"`) |
+| `disabled` | `boolean` | Disables all interactions |
+| `error` | `string \| null` | External error message |
+| `helperText` | `string` | Helper text shown when no error is present |
+
+### `AllowedDomainsInput`
+
+A `forwardRef` component that renders:
+- **Existing domain rows** — each as a disabled `Input` with an `X` remove button
+- **New domain input** — accepts `Enter` key or "Add Domain" button to submit
+- **Validation feedback** — displays external `error` or internal `localError`
 
 ## Usage Example
 
 ```typescript
-import { AllowedDomainsInput } from "./allowed-domains-input"
+import { AllowedDomainsInput } from "@/components/ui/allowed-domains-input"
+
+function SettingsForm() {
+  const [domains, setDomains] = React.useState<string[]>(["flamingo.run"])
 
-function DomainSettings() {
-  const [domains, setDomains] = useState<string[]>(["example.com"])
-  
   const validateDomain = (domain: string) => {
-    const domainRegex = /^[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]*\.([a-zA-Z]{2,})$/
     const cleaned = domain.toLowerCase().replace(/^https?:\/\//, "")
-    
-    if (!domainRegex.test(cleaned)) {
-      return { valid: false, error: "Invalid domain format" }
-    }
-    
-    return { valid: true, cleanedDomain: cleaned }
+    const valid = /^[a-z0-9.-]+\.[a-z]{2,}$/.test(cleaned)
+    return { valid, error: valid ? undefined : "Enter a valid domain", cleanedDomain: cleaned }
   }
 
   return (
@@ -33,11 +42,10 @@ function DomainSettings() {
       value={domains}
       onChange={setDomains}
       onValidate={validateDomain}
-      placeholder="yourdomain.com"
-      helperText="Enter domains without protocol (http/https)"
+      helperText="Only users from these domains can sign in."
     />
   )
 }
 ```
 
-The component features real-time validation, duplicate prevention, keyboard shortcuts, and integrates with form libraries through controlled component patterns.
+> **Note:** Duplicate domains are silently ignored. If `onValidate` returns a `cleanedDomain`, that normalized value is stored instead of the raw input.

package/src/components/ui/.assignee-dropdown.md

@@ -0,0 +1,45 @@
+<!-- source-hash: 174def33d719cb0d6dbefdba06240030 -->
+A dropdown component for assigning users to tickets, supporting two visual variants: a compact avatar-based popover and a default inline editable display.
+
+## Key Components
+
+### Interfaces
+- **`TicketAssigneeOption`** — Shape for assignee list items (`value`, `label`, `imageUrl?`)
+- **`AssigneeDropdownProps`** — Component props including `currentAssignee`, `options`, `onAssign` callback, and `variant`
+
+### Exports
+- **`AssigneeDropdown`** — Main entry component that delegates to `CompactAssigneeDropdown` or `DefaultAssigneeDropdown` based on the `variant` prop
+
+### Internal Components
+- **`CompactAssigneeDropdown`** — Renders a circular avatar button (or `UserPlusIcon` when unassigned) that opens a searchable Radix UI popover list; selecting the current assignee deselects them
+- **`DefaultAssigneeDropdown`** — Inline display showing the assignee's avatar and name with a pencil edit icon; clicking switches to an `Autocomplete` input for searching and reassigning
+
+## Usage Example
+
+```typescript
+import { AssigneeDropdown } from './assignee-dropdown'
+
+const users = [
+  { value: 'u1', label: 'Alice Johnson', imageUrl: '/avatars/alice.png' },
+  { value: 'u2', label: 'Bob Smith' },
+]
+
+// Default variant (inline editable)
+<AssigneeDropdown
+  currentAssignee={{ id: 'u1', name: 'Alice Johnson', avatarSrc: '/avatars/alice.png' }}
+  options={users}
+  onAssign={(userId) => console.log('Assigned to:', userId)}
+/>
+
+// Compact variant (avatar popover)
+<AssigneeDropdown
+  options={users}
+  onAssign={(userId) => console.log('Assigned to:', userId)}
+  variant="compact"
+/>
+```
+
+**Behavior notes:**
+- `onAssign` receives `null` when the current assignee is deselected (compact variant toggle)
+- Search resets automatically when the compact popover closes
+- The `isLoading` prop shows a loading state inside the options list

package/src/components/ui/.autocomplete.md

@@ -1,48 +1,54 @@
-<!-- source-hash: 1889fd24b7bf12d381a0902565b29f66 -->
-A multi-select autocomplete component with search, keyboard navigation, and customizable rendering built on Radix UI primitives.
+<!-- source-hash: c483f7e7ed16ddf489c0f0b85c84e31b -->
+A fully-featured autocomplete/combobox input component supporting both single and multi-select modes, with keyboard navigation, tag display, filtering, and creatable options.
 
 ## Key Components
 
-- **AutocompleteOption<T>**: Interface defining option structure with label and value
-- **AutocompleteProps<T>**: Comprehensive props interface supporting multi-select, custom rendering, validation states
-- **AutocompleteInner<T>**: Main component implementation with keyboard navigation and tag management
-- **containerStyles**: Shared styling constants matching the design system's Input component
-- **innerInputStyles**: Input field styling with consistent typography and theming
+### Types & Interfaces
+- **`AutocompleteOption<T>`** — Shape of each selectable option (`label` + `value`)
+- **`AutocompleteInputChangeReason`** — Union of `'input' | 'reset' | 'clear'`
+- **`AutocompleteSingleProps<T>`** — Props for single-select mode
+- **`AutocompleteMultipleProps<T>`** — Props for multi-select mode (adds `maxItems`, `renderTag`, `limitTags`, etc.)
+- **`AutocompleteProps<T>`** — Discriminated union of the two modes
+
+### Internal Logic
+- **`AutocompleteInner`** — Core render function wrapped with `forwardRef`, managing:
+  - Controlled/uncontrolled input value state
+  - Dropdown open/close via Radix `PopoverPrimitive`
+  - Option filtering (client-side or delegated via `disableClientFilter`)
+  - Keyboard navigation (`ArrowDown/Up`, `Enter`, `Escape`)
+  - Tag overflow via `useAutoLimitTags` hook
+  - `freeSolo` and `creatable` modes
 
 ## Usage Example
 
 ```typescript
-import { Autocomplete, AutocompleteOption } from './autocomplete'
-
-const userOptions: AutocompleteOption<number>[] = [
-  { label: 'John Doe', value: 1 },
-  { label: 'Jane Smith', value: 2 },
-  { label: 'Bob Johnson', value: 3 }
-]
-
-function UserSelector() {
-  const [selectedUsers, setSelectedUsers] = React.useState<number[]>([])
-
-  return (
-    <Autocomplete
-      options={userOptions}
-      value={selectedUsers}
-      onChange={setSelectedUsers}
-      placeholder="Select users..."
-      label="Team Members"
-      maxItems={3}
-      limitTags={2}
-      freeSolo={true}
-      showClearAll={true}
-      renderOption={(option, isSelected) => (
-        <div className="flex items-center justify-between">
-          <span>{option.label}</span>
-          {isSelected && <Check className="h-4 w-4" />}
-        </div>
-      )}
-    />
-  )
-}
-```
-
-The component features keyboard navigation (arrow keys, Enter, Escape, Backspace), tag overflow handling, custom filtering, and integrates with form validation states through the `invalid` prop.
+// Single select
+<Autocomplete
+  options={[{ label: "Option A", value: "a" }, { label: "Option B", value: "b" }]}
+  value={selected}
+  onChange={(val) => setSelected(val)}
+  label="Pick one"
+  placeholder="Search..."
+/>
+
+// Multi-select with tag limit and creatable
+<Autocomplete
+  multiple
+  options={options}
+  value={selectedValues}
+  onChange={(vals) => setSelectedValues(vals)}
+  limitTags={3}
+  creatable
+  onCreateOption={(input) => persistNewOption(input)}
+  label="Tags"
+/>
+
+// Server-side filtering
+<Autocomplete
+  options={serverOptions}
+  value={value}
+  onChange={setValue}
+  disableClientFilter
+  onInputChange={(query, reason) => fetchOptions(query)}
+/>
+```

package/src/components/ui/.benefit-card.md

@@ -1,44 +1,59 @@
-<!-- source-hash: 62daa81d47cf45a76b1ac5e35401b10f -->
-A flexible React component system for displaying feature benefits with optional icons, supporting multiple visual variants and responsive grid layouts.
+<!-- source-hash: b039cee3855a4c8e259a4c0cd027fea4 -->
+A client-side React component providing styled benefit/feature cards with multiple visual variants and a responsive grid layout container.
 
 ## Key Components
 
-- **`BenefitCard`** - Individual card component with icon, title, and description
-- **`BenefitCardGrid`** - Container component for organizing cards in responsive grids (2, 3, or 4 columns)
-- **`BenefitCardProps`** - Props interface supporting three variants: `default`, `dark`, and `auth-figma`
-- **`BenefitCardGridProps`** - Grid container props with customizable column counts
+### `BenefitCard`
+Renders a single benefit card with an optional icon, title, and description. Supports three visual variants:
+
+| Variant | Description |
+|---|---|
+| `default` | Light background with standard body typography |
+| `dark` | Transparent background with monospace heading and shadow |
+| `auth-figma` | Transparent with larger padding and heading-scale typography |
+
+**Props:**
+- `icon` — optional React node rendered before the text content
+- `title` — required card heading
+- `description` — required supporting text
+- `variant` — visual style (`'default'` | `'dark'` | `'auth-figma'`)
+- `className` — additional Tailwind classes
+
+### `BenefitCardGrid`
+A responsive grid container that wraps multiple `BenefitCard` instances and automatically applies divider borders between items.
+
+**Props:**
+- `children` — one or more `BenefitCard` nodes
+- `columns` — grid column count: `2` | `3` | `4` (default: `2`)
+- `className` — additional Tailwind classes
 
 ## Usage Example
 
 ```typescript
 import { BenefitCard, BenefitCardGrid } from './benefit-card'
-import { ShieldIcon, SparklesIcon } from 'lucide-react'
-
-// Single benefit card
-<BenefitCard
-  icon={<ShieldIcon className="w-6 h-6" />}
-  title="Enhanced Security"
-  description="Advanced protection with multi-layer authentication"
-  variant="dark"
-/>
-
-// Grid of benefit cards
-<BenefitCardGrid columns={3}>
-  <BenefitCard
-    icon={<SparklesIcon className="w-5 h-5" />}
-    title="AI-Powered Automation"
-    description="Intelligent automation reduces manual tasks by 80%"
-  />
-  <BenefitCard
-    title="24/7 Support"
-    description="Round-the-clock technical assistance"
-    variant="auth-figma"
-  />
-  <BenefitCard
-    title="Scalable Infrastructure"
-    description="Grows with your business needs"
-  />
-</BenefitCardGrid>
-```
-
-The component uses Tailwind CSS with OpenFrame Design System (ODS) tokens and automatically handles responsive layouts with appropriate borders between grid items.
+import { ShieldIcon } from 'lucide-react'
+
+export function Features() {
+  return (
+    <BenefitCardGrid columns={3}>
+      <BenefitCard
+        icon={<ShieldIcon />}
+        title="Secure by Default"
+        description="End-to-end encryption across all endpoints."
+        variant="default"
+      />
+      <BenefitCard
+        icon={<ShieldIcon />}
+        title="AI-Powered"
+        description="Mingo AI resolves tickets before they escalate."
+        variant="dark"
+      />
+      <BenefitCard
+        title="Open Source"
+        description="Built on trusted open-source foundations."
+        variant="auth-figma"
+      />
+    </BenefitCardGrid>
+  )
+}
+```