@flamingo-stack/openframe-frontend-core 0.0.213 → 0.0.214-snapshot.20260528192313

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

@@ -1,47 +1,51 @@
-<!-- source-hash: d5fd9c1811d9264819293e10d4e069fa -->
-A client-side React component that renders a responsive grid of feature cards with customizable styling, borders, and content layout.
+<!-- source-hash: 6c49039417df243ab2c6d3b41c998928 -->
+A client-side React component that renders a responsive grid of feature cards with configurable layouts, borders, backgrounds, icons, and status badges.
 
 ## Key Components
 
-### Types
-- **`FeatureCardItem`** - Interface defining individual card properties including icon, title, badge, content, and styling overrides
-- **`FeatureCardGridProps`** - Configuration interface for the grid layout, columns, spacing, and global styling options
+### Interfaces
+- **`FeatureCardItem`** — Defines individual card data: icon, title, badge, content, and per-card style overrides (`removeAllBorders`, `noBackground`, `customBackground`)
+- **`FeatureCardGridProps`** — Grid-level configuration: items array, column count, class overrides, border/background/gap controls
 
-### Components
-- **`FeatureCardGrid`** - Main component that renders a responsive grid of feature cards with intelligent border management and customizable layouts
+### Exports
+- **`FeatureCardGrid`** — Main component rendering a `Card` wrapper with a responsive CSS grid, dynamically computing row/column borders and applying per-item style overrides
 
 ## Usage Example
 
 ```typescript
-import { FeatureCardGrid } from './feature-card';
-import { SomeIcon } from './icons';
+import { FeatureCardGrid, FeatureCardItem } from './feature-card';
+import { ShieldIcon } from 'lucide-react';
 
-const features = [
+const items: FeatureCardItem[] = [
   {
-    icon: SomeIcon,
-    iconColor: '#0EA5E9',
-    title: 'Advanced Analytics',
-    badge: {
-      text: 'New',
-      variant: 'card' as const,
-      colorScheme: 'cyan' as const
-    },
-    content: <p>Real-time data insights and reporting</p>
+    icon: ShieldIcon,
+    iconColor: '#FFC008',
+    title: 'Automated Patching',
+    badge: { text: 'New', colorScheme: 'green' },
+    content: <p>Keep endpoints secure with zero-touch patch management.</p>,
   },
   {
-    title: 'Custom Integration',
-    content: <div>Flexible API connections</div>,
-    noBackground: true
-  }
+    title: 'AI Triage',
+    content: <p>Mingo AI resolves tickets before a technician is needed.</p>,
+    noBackground: true,
+  },
 ];
 
-<FeatureCardGrid 
-  items={features}
-  columns={2}
-  showBorders={true}
-  roundedCorners={true}
-  cardGap="gap-6"
-/>
+export default function Page() {
+  return (
+    <FeatureCardGrid
+      items={items}
+      columns={2}
+      cardGap="gap-6"
+      showBorders={true}
+      roundedCorners={true}
+    />
+  );
+}
 ```
 
-The component features intelligent responsive border handling, supports 2-3 column layouts, and provides extensive customization options for backgrounds, borders, and spacing. Each card can override global styles with item-specific properties like `noBackground` or `removeAllBorders`.
+## Notes
+
+- Border logic is **responsive-aware**: right borders are hidden on mobile (single column) and shown on desktop only where appropriate
+- When **all items** share `noBackground` or `removeAllBorders`, the outer `Card` container is also updated to match, avoiding visual inconsistencies
+- `content` accepts any `React.ReactNode`, making cards fully composable for marketing pages, feature showcases, or dashboard layouts

package/src/components/ui/.feature-list.md

@@ -0,0 +1,48 @@
+<!-- source-hash: de46e328067be52e6b8316046dcf529b -->
+A client-side React component that renders a styled vertical list of feature items, each with an icon, title, and description.
+
+## Key Components
+
+### Interfaces
+- **`FeatureListItemData`** — Shape of each list item: `icon` (ReactNode), `title` (string), `description` (string)
+- **`FeatureListProps`** — Component props: `items` array, optional `className`, optional `iconBoxSize` (default: `72`)
+
+### Component
+- **`FeatureList`** — Renders a bordered card list where each row displays a square icon box alongside a title and description. Dividers are automatically added between items.
+
+## Usage Example
+
+```typescript
+import { FeatureList, FeatureListItemData } from './feature-list';
+import { ShieldIcon, ZapIcon, CloudIcon } from 'lucide-react';
+
+const features: FeatureListItemData[] = [
+  {
+    icon: <ShieldIcon size={32} />,
+    title: 'Secure by Default',
+    description: 'All connections are encrypted end-to-end.',
+  },
+  {
+    icon: <ZapIcon size={32} />,
+    title: 'Lightning Fast',
+    description: 'Sub-100ms response times across all regions.',
+  },
+  {
+    icon: <CloudIcon size={32} />,
+    title: 'Cloud Native',
+    description: 'Built for scalable, distributed infrastructure.',
+  },
+];
+
+export default function Page() {
+  return (
+    <FeatureList
+      items={features}
+      iconBoxSize={64}
+      className="max-w-xl"
+    />
+  );
+}
+```
+
+> **Note:** The `iconBoxSize` prop controls both width and height of the icon container in pixels. Icon content is not automatically sized — size your icon element to fit within the box.

package/src/components/ui/.field-wrapper.md

@@ -0,0 +1,47 @@
+<!-- source-hash: 0d873ee81fa30b5916e604a92d4925d2 -->
+A layout wrapper component that provides consistent label and error message chrome for form fields, with reserved space to prevent layout shifts.
+
+## Key Components
+
+### `FieldWrapper`
+A `forwardRef` component that wraps form field children with optional label and error/warning message display.
+
+### `FieldWrapperProps`
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | — | Label text rendered above the field |
+| `error` | `string` | — | Error message rendered below the field |
+| `errorVariant` | `"error" \| "warning"` | `"error"` | Controls error text color (red vs yellow) |
+| `className` | `string` | — | Additional classes for the outer wrapper |
+| `children` | `React.ReactNode` | — | The form field element(s) |
+
+### Behavior Notes
+- When neither `label` nor `error` is provided, the wrapper renders as `contents` (no extra DOM box).
+- The error message is absolutely positioned (`translate-y-full`) below the field, preventing layout shifts in the surrounding form.
+- Long error messages are `truncate`d with the full text accessible via the `title` attribute.
+
+## Usage Example
+
+```typescript
+import { FieldWrapper } from "./field-wrapper"
+import { TextInput } from "./text-input"
+
+// Standard field with label and error
+<FieldWrapper label="Email address" error="Invalid email format">
+  <TextInput type="email" value={email} onChange={handleChange} />
+</FieldWrapper>
+
+// Warning variant
+<FieldWrapper
+  label="Username"
+  error="Username is already taken"
+  errorVariant="warning"
+>
+  <TextInput value={username} onChange={handleChange} />
+</FieldWrapper>
+
+// No chrome — wrapper renders as contents
+<FieldWrapper>
+  <TextInput placeholder="Search..." />
+</FieldWrapper>
+```

package/src/components/ui/.file-upload.md

@@ -0,0 +1,42 @@
+<!-- source-hash: cf353b09cad830f836030fb8046e62bc -->
+A flexible React dropzone component supporting both simple file selection and async managed upload workflows, with drag-and-drop, validation, and file list rendering.
+
+## Key Components
+
+### Interfaces
+- **`ManagedFileEntry`** — Represents an async-uploaded file with `id`, `fileName`, `fileSize`, `status` (`uploading` | `uploaded` | `error`), and optional `error` message
+- **`FileUploadProps`** — Full prop interface supporting both simple (`value`/`onChange`) and managed (`managedFiles`/`onRemoveManagedFile`) modes
+
+### Helpers
+- **`formatFileSize(bytes)`** — Converts bytes to human-readable string (B, KB, MB, GB)
+- **`matchesAccept(file, accept)`** — Validates a file against an accept string (MIME types, extensions, wildcards)
+- **`dragHasFiles(e)`** — Detects if a native drag event carries file data
+
+### Component
+- **`FileUpload`** — Main export; renders a dropzone button (when empty) or file list (when files exist), with optional window-level drop capture via `acceptWindowDrops`
+
+## Usage Example
+
+```typescript
+// Simple single-file mode
+<FileUpload
+  value={file}
+  onChange={(f) => setFile(f as File)}
+  accept="image/*"
+  maxSize={5 * 1024 * 1024}
+  fieldLabel="Profile Photo"
+/>
+
+// Async managed upload mode
+<FileUpload
+  onChange={(files) => uploadToS3(files as File[])}
+  managedFiles={managedFiles}
+  onRemoveManagedFile={(id) => removeManagedFile(id)}
+  multiple
+  maxFiles={5}
+  acceptWindowDrops
+  label="Drop attachments here"
+/>
+```
+
+> **Tip:** Use `managedFiles` + `onRemoveManagedFile` for presigned URL or background upload flows where upload status (`uploading` | `uploaded` | `error`) needs to be reflected in the UI. Use plain `value`/`onChange` for synchronous or form-controlled scenarios.

package/src/components/ui/.filter-checkbox-item.md

@@ -0,0 +1,43 @@
+<!-- source-hash: 80c3e1ef5a8303ea358c8f94bbacb69d -->
+A client-side checkbox item component for filter lists, built on Radix UI's Checkbox primitive with optional count display and ODS design tokens.
+
+## Key Components
+
+### `FilterCheckboxItemProps`
+| Prop | Type | Description |
+|------|------|-------------|
+| `label` | `string` | Display text for the checkbox item |
+| `checked` | `boolean` | Controlled checked state |
+| `onChange` | `(checked: boolean) => void` | Callback fired on toggle |
+| `count` | `number` (optional) | Item count displayed on the right |
+| `className` | `string` (optional) | Additional CSS classes |
+
+### `FilterCheckboxItem`
+A styled, accessible checkbox row that supports full-row click toggling. When `count` is provided, padding adjusts and the count renders as secondary text on the trailing edge.
+
+## Usage Example
+
+```typescript
+import { FilterCheckboxItem } from "./filter-checkbox-item"
+import { useState } from "react"
+
+function FilterPanel() {
+  const [active, setActive] = useState(false)
+
+  return (
+    <FilterCheckboxItem
+      label="Active Tickets"
+      checked={active}
+      onChange={setActive}
+      count={42}
+    />
+  )
+}
+```
+
+## Notes
+
+- Clicking anywhere on the row toggles the checkbox; the Radix `Root` has `stopPropagation` to avoid double-firing.
+- The checkmark icon renders only when `checked` is `true` via Radix's `Indicator`.
+- Count values are formatted with `toLocaleString()` for locale-aware number display.
+- Styled with ODS design tokens (`ods-accent`, `ods-card`, `ods-border`, etc.) for consistency across the Flamingo UI.

package/src/components/ui/.filter-list.md

@@ -0,0 +1,57 @@
+<!-- source-hash: 266230e3eb0a6c70e91f5bde060a9529 -->
+A accessible, interactive filter list UI component built with Radix UI checkboxes, supporting both single and multi-select modes with keyboard navigation.
+
+## Key Components
+
+### `FilterListItem`
+A single selectable row with a title, optional metadata badges, and a Radix UI checkbox. Supports keyboard interaction (`Enter`/`Space`), disabled state, and selected highlighting using ODS design tokens.
+
+**Props (`FilterListItemProps`):**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `title` | `string` | Display label for the item |
+| `meta` | `Array<string \| number>` | Optional bullet-separated metadata |
+| `selected` | `boolean` | Whether the item is checked |
+| `onToggle` | `(selected: boolean) => void` | Callback on selection change |
+| `disabled` | `boolean` | Disables interaction |
+| `className` | `string` | Additional CSS classes |
+
+### `FilterList<T>`
+A container that manages a collection of `FilterListItem` entries with controlled selection state. Supports generic item `data` typing for strongly-typed payloads.
+
+**Props (`FilterListProps<T>`):**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `items` | `Array<{ id, title, meta?, disabled?, data? }>` | List of items to render |
+| `selectedIds` | `string[]` | Currently selected item IDs |
+| `onChange` | `(selectedIds: string[]) => void` | Fires when selection changes |
+| `multiple` | `boolean` | Enables multi-select (default: `true`) |
+
+## Usage Example
+
+```typescript
+import { FilterList } from "@/components/filter-list"
+
+const items = [
+  { id: "win", title: "Windows", meta: ["Workstation", 42] },
+  { id: "mac", title: "macOS", meta: ["Laptop", 18] },
+  { id: "linux", title: "Linux", meta: ["Server", 7], disabled: true },
+]
+
+function DeviceFilter() {
+  const [selected, setSelected] = React.useState<string[]>(["win"])
+
+  return (
+    <FilterList
+      items={items}
+      selectedIds={selected}
+      onChange={setSelected}
+      multiple={true}
+    />
+  )
+}
+```
+
+> For single-select mode (e.g. priority filters), set `multiple={false}` — selecting a new item automatically deselects the previous one.

package/src/components/ui/.filter-modal.md

@@ -0,0 +1,59 @@
+<!-- source-hash: 0a032d083c46e509f8e9dcfa0550baef -->
+A modal dialog component for sorting and filtering table data, combining checkbox filter groups, column sorting, and tag key-value filters into a unified UI with loading and empty states.
+
+## Key Components
+
+### `FilterModal`
+Main exported component that renders a `ModalV2`-based dialog with three content sections and footer action buttons.
+
+### Exported Types
+
+| Type | Description |
+|------|-------------|
+| `FilterModalOption` | Single filter option with `id`, `label`, and optional `count` |
+| `FilterGroup` | Named group of `FilterModalOption` items |
+| `FilterModalProps` | Full props interface for `FilterModal` |
+| `SortConfig`, `SortDirection`, `SortableColumn` | Re-exported from `sort-column-item` |
+| `TagKeyConfig`, `TagValueOption` | Re-exported from `tag-key-value-filter` |
+
+### Internal Behavior
+- **Local state** (`selectedFilters`, `pendingTags`) buffers user selections until **Apply** is clicked
+- **Reset** clears all filters and tags immediately via `onFilterChange({})` and `onTagsChange?.([])`
+- **Sync on open** — `useEffect` resets local state to `currentFilters`/`selectedTags` whenever the modal opens
+- **Empty state** renders when no sort columns, filter groups, or tag filters are present
+- **Loading state** renders skeleton placeholders when `isLoading` is `true`
+
+## Usage Example
+
+```typescript
+const [filters, setFilters] = useState<TableFilters>({})
+const [tags, setTags] = useState<string[]>([])
+
+<FilterModal
+  isOpen={isModalOpen}
+  onClose={() => setIsModalOpen(false)}
+  filterGroups={[
+    {
+      id: 'status',
+      title: 'Status',
+      options: [
+        { id: 'active', label: 'Active', count: 12 },
+        { id: 'inactive', label: 'Inactive', count: 4 },
+      ],
+    },
+  ]}
+  sortConfig={{
+    title: 'Sort By',
+    sortBy: 'name',
+    sortDirection: 'asc',
+    columns: [{ key: 'name', label: 'Name' }],
+  }}
+  onSort={(column, direction) => console.log(column, direction)}
+  onFilterChange={setFilters}
+  currentFilters={filters}
+  tagFilterKeys={[{ key: 'env', label: 'Environment', values: [] }]}
+  selectedTags={tags}
+  onTagsChange={setTags}
+  isLoading={false}
+/>
+```

package/src/components/ui/.floating-tooltip.md

@@ -1,41 +1,58 @@
-<!-- source-hash: 6febb7684f7f7010464b400f32e9e44b -->
-A floating tooltip component built with Floating UI that provides precise positioning, color markup support, and ODS design system styling.
+<!-- source-hash: c7355b336531eeee83c49994040e5cbf -->
+A floating tooltip component built with `@floating-ui/react` that supports smart positioning, directional arrows, and inline color markup parsing.
 
 ## Key Components
 
-- **FloatingTooltip**: Main component that renders a floating tooltip with customizable positioning and styling
-- **parseColoredText**: Utility function that converts color markup syntax `[COLOR]text[/COLOR]` into styled JSX elements
-- **FloatingTooltipProps**: TypeScript interface defining component props including content, positioning, and styling options
+### `FloatingTooltip`
+The main exported component. Renders a portal-based tooltip with:
+- **Auto-positioning** via `flip`, `shift`, and `offset` middleware — avoids viewport clipping
+- **Arrow indicator** that dynamically repositions based on the resolved placement
+- **Hover interaction** with configurable open delay and safe polygon close detection
+- **`disabled` prop** — suppresses tooltip without unmounting the trigger wrapper
+
+### `parseColoredText` (internal)
+Parses `[COLOR]text[/COLOR]` markup within string content and maps it to ODS CSS classes:
+
+| Tag | Tailwind Class |
+|-----|----------------|
+| `[YELLOW]` | `text-ods-accent` |
+| `[GREEN]` | `text-ods-success` |
+| `[RED]` | `text-ods-error` |
+| `[BLUE]` / `[CYAN]` | `text-ods-info` |
+| `[PINK]` | `text-ods-accent` |
+
+### `FloatingTooltipProps`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `content` | `React.ReactNode` | — | Tooltip body; strings support color markup |
+| `children` | `React.ReactNode` | — | Trigger element |
+| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"right"` | Preferred placement |
+| `delayDuration` | `number` | `0` | Open delay in ms |
+| `disabled` | `boolean` | `false` | Suppresses tooltip |
+| `className` | `string` | — | Extra classes on the tooltip panel |
 
 ## Usage Example
 
 ```typescript
-import { FloatingTooltip } from './components/ui/floating-tooltip'
+import { FloatingTooltip } from "./floating-tooltip"
 
-// Basic tooltip
-<FloatingTooltip content="This is a helpful tooltip" side="top">
-  <button>Hover me</button>
+// Basic usage
+<FloatingTooltip content="Save changes">
+  <button>Save</button>
 </FloatingTooltip>
 
-// Tooltip with colored text markup
-<FloatingTooltip 
-  content="Status: [GREEN]Active[/GREEN] | [YELLOW]Warning[/YELLOW]"
-  side="right"
+// With color markup and delay
+<FloatingTooltip
+  content="Status: [GREEN]Online[/GREEN] — [YELLOW]1 warning[/YELLOW]"
+  side="top"
   delayDuration={300}
 >
-  <div className="status-indicator">
-    Status Icon
-  </div>
+  <span>Hover me</span>
 </FloatingTooltip>
 
-// Custom styled tooltip
-<FloatingTooltip
-  content="Custom tooltip content"
-  className="bg-red-100 border-red-300"
-  side="bottom"
->
-  <span>Custom Element</span>
+// Disabled (wrapper renders, tooltip suppressed)
+<FloatingTooltip content="Hidden tip" disabled>
+  <button>No tooltip</button>
 </FloatingTooltip>
-```
-
-The component supports color markup (`[YELLOW]`, `[GREEN]`, `[RED]`, `[BLUE]`, `[PINK]`, `[CYAN]`) that maps to ODS design system color classes, includes an arrow pointer, and handles positioning automatically with collision detection and fallback positioning.
+```

package/src/components/ui/.hidden-tags-popup.md

@@ -0,0 +1,49 @@
+<!-- source-hash: cc1ede727d1bab8a8e8ff3b969595614 -->
+A floating popup component that displays a list of hidden tag items with optional remove functionality, typically used in multi-select inputs when tags overflow the visible area.
+
+## Key Components
+
+### Interfaces
+
+| Interface | Description |
+|-----------|-------------|
+| `HiddenTagItem` | Defines a tag item with a `label` (ReactNode) and `value` (unknown) |
+| `HiddenTagsPopupProps` | Props for the popup including `items`, `onRemove`, `disabled`, `className`, and `style` |
+
+### Exports
+
+- **`HiddenTagsPopup`** — A `forwardRef` component rendering an absolutely-positioned dropdown card listing overflow tags. Each item shows a truncated uppercase label and an optional remove button (`XmarkCircleIcon`) when `onRemove` is provided and `disabled` is false.
+
+## Usage Example
+
+```typescript
+import { HiddenTagsPopup, HiddenTagItem } from "./hidden-tags-popup"
+
+const overflowTags: HiddenTagItem[] = [
+  { label: "Engineering", value: "engineering" },
+  { label: "Design", value: "design" },
+]
+
+function TagSelector() {
+  const handleRemove = (value: unknown) => {
+    console.log("Remove tag:", value)
+  }
+
+  return (
+    <div style={{ position: "relative" }}>
+      <HiddenTagsPopup
+        items={overflowTags}
+        onRemove={handleRemove}
+        disabled={false}
+      />
+    </div>
+  )
+}
+```
+
+## Notes
+
+- Renders with `z-50` and `top-full` positioning — expects a relatively-positioned parent container.
+- Includes entrance animation via `animate-in fade-in-0 zoom-in-95`.
+- Remove button uses `e.stopPropagation()` to prevent unintended parent click events.
+- Accessible via `aria-label` on each remove button.

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

@@ -0,0 +1,54 @@
+<!-- source-hash: eee1f55a6c5cf2349c0897b18c2dfcf1 -->
+A reusable hover-triggered dropdown component that displays a list of clickable items. Uses fixed positioning via `getBoundingClientRect` to render correctly inside overflow-hidden containers like modals and sheets.
+
+## Key Components
+
+### Interfaces
+
+| Export | Description |
+|--------|-------------|
+| `HoverDropdownItem` | Defines each row: `label`, optional `icon`, `href`, `onClick`, `targetPlatform`, `path`, and an independent `secondaryAction` button |
+| `HoverDropdownRenderAnchorArgs` | Arguments passed to the `renderAnchor` slot for custom link routing |
+| `HoverDropdownProps` | Component props: `items`, `side`, `hideDelay`, `className`, `renderAnchor` |
+
+### Component
+
+**`HoverDropdown`** — Main export. Wraps any trigger element and shows a positioned dropdown on hover (or tap). Each row supports three render modes:
+- **Link row** — rendered via `renderAnchor` (defaults to plain `<a>`)
+- **Button row** — rendered as `<button>` when `onClick` is provided
+- **Non-interactive row** — rendered as `<span>` when neither `href` nor `onClick` is present (useful when only a `secondaryAction` applies)
+
+The dropdown auto-positions right → left → above/below based on available viewport space.
+
+## Usage Example
+
+```typescript
+// Basic usage
+<HoverDropdown items={[{ label: 'Blog Post', href: '/blog/1' }]}>
+  <span>Blog Posts (3)</span>
+</HoverDropdown>
+
+// With custom anchor renderer (e.g., chat runtime routing)
+<HoverDropdown
+  items={[
+    {
+      label: 'Design Doc',
+      href: '/docs/design',
+      path: 'docs/design',
+      targetPlatform: 'markdown',
+      secondaryAction: {
+        icon: <AskIcon />,
+        label: 'Ask about this',
+        onClick: () => handleAsk('design'),
+      },
+    },
+  ]}
+  renderAnchor={({ href, className, children }) => (
+    <NavLinkAnchorViaRuntime href={href} className={className}>
+      {children}
+    </NavLinkAnchorViaRuntime>
+  )}
+>
+  <Chip>Documents</Chip>
+</HoverDropdown>
+```