@flamingo-stack/openframe-frontend-core 0.0.212 → 0.0.213-snapshot.20260528174436

package/src/components/ui/.status-badge.md

@@ -1,49 +1,37 @@
-<!-- source-hash: e7abb4f8009374dd2b76e644ab218efc -->
-A reusable React component for displaying status badges with various visual styles, color schemes, and layout variants for different UI contexts.
+<!-- source-hash: 03e68088323281da2f3ddac5a1dabf62 -->
+A client-side React component that renders styled status/label badges with configurable size variants and color schemes using `class-variance-authority`.
 
 ## Key Components
 
-- **StatusBadge** - Main component that renders status badges with customizable styling
-- **statusBadgeVariants** - Class variance authority (CVA) configuration defining visual variants
-- **StatusBadgeProps** - TypeScript interface extending HTML div attributes with component-specific props
-
-The component supports two main variants:
-- `card` - Larger badges (px-3 py-1.5, text-sm) for card displays
-- `button` - Compact badges (px-2 py-0.5, text-[10px]) with multi-line text support
-
-Color schemes include Flamingo brand colors (cyan, pink, yellow, green, purple), semantic states (success, error, warning), and border-only variants for task type indicators.
+- **`statusBadgeVariants`** — CVA variant config defining two axes:
+  - `variant`: `"card"` (default, larger) or `"button"` (compact, stamp-like)
+  - `colorScheme`: `cyan`, `pink`, `yellow`, `green`, `purple`, `success`, `error`, `warning`, `default`, `accentBorder`, `errorBorder`, `whiteBorder`
+- **`StatusBadge`** — Main exported `<span>`-based component
+- **`singleLine`** prop — Opt-out flag for the `button` variant's multi-word vertical stacking behavior
 
 ## Usage Example
 
 ```typescript
 import { StatusBadge } from './status-badge';
 
-function TaskCard() {
-  return (
-    <div className="flex gap-2">
-      {/* Card variant with brand color */}
-      <StatusBadge 
-        text="ACTIVE" 
-        variant="card" 
-        colorScheme="green" 
-      />
-      
-      {/* Button variant with multi-line text */}
-      <StatusBadge 
-        text="HIGH PRIORITY" 
-        variant="button" 
-        colorScheme="error" 
-      />
-      
-      {/* Border-only variant for task types */}
-      <StatusBadge 
-        text="API TASK" 
-        variant="card" 
-        colorScheme="accentBorder" 
-      />
-    </div>
-  );
-}
+// Default card badge
+<StatusBadge text="Active" colorScheme="success" />
+
+// Compact button badge with stacked multi-word text
+<StatusBadge text="TO DO" variant="button" colorScheme="warning" />
+
+// Compact button badge, single line (inline chat context)
+<StatusBadge text="IN PROGRESS" variant="button" colorScheme="cyan" singleLine />
+
+// Border-only accent badge (task type)
+<StatusBadge text="BUG" colorScheme="errorBorder" />
+
+// Custom class override
+<StatusBadge text="Custom" colorScheme="purple" className="rounded-full" />
 ```
 
-The component automatically handles text wrapping for button variants, splitting space-separated text into multiple lines for better readability in narrow spaces.
+## Notes
+
+- Renders as `<span>` (not `<div>`) to remain HTML-valid inside inline contexts such as `<p>`, `<a>`, or markdown-rendered content
+- `variant="button"` with multi-word text auto-stacks each word vertically (stamp effect); pass `singleLine` to disable
+- Extends `React.HTMLAttributes<HTMLSpanElement>`, so all standard span props (`id`, `onClick`, `aria-*`, etc.) are forwarded

package/src/components/ui/.switch.md

@@ -1,44 +1,31 @@
-<!-- source-hash: 400f72780c45e06d93dc69f92d9463ac -->
-A React switch/toggle component built on top of Radix UI primitives with support for both controlled and uncontrolled usage patterns. The component provides smooth animations and consistent styling with custom accent colors.
+<!-- source-hash: 9e0e6c7a40dc325660ad4e61baf2efdb -->
+A accessible toggle switch component built on Radix UI primitives, supporting both controlled and uncontrolled usage patterns with Flamingo ODS design tokens.
 
 ## Key Components
 
-- **Switch**: Main toggle component that extends Radix UI Switch with enhanced styling and state management
-- Supports both controlled (`checked` prop) and uncontrolled usage modes
-- Built-in state synchronization between internal and external state
-- Accessible focus management and keyboard navigation
+- **`Switch`** — A `forwardRef` wrapper around `@radix-ui/react-switch` that manages internal state while staying in sync with optional controlled props (`checked`, `onCheckedChange`).
 
 ## Usage Example
 
 ```typescript
-import { Switch } from "./switch"
-
-// Uncontrolled usage
-function BasicToggle() {
-  return <Switch />
-}
-
-// Controlled usage
-function ControlledToggle() {
-  const [enabled, setEnabled] = useState(false)
-  
-  return (
-    <Switch 
-      checked={enabled}
-      onCheckedChange={setEnabled}
-    />
-  )
-}
-
-// With custom styling
-function CustomSwitch() {
-  return (
-    <Switch 
-      className="scale-150" 
-      onCheckedChange={(checked) => console.log('Toggle:', checked)}
-    />
-  )
-}
+// Uncontrolled
+<Switch />
+
+// Controlled
+const [enabled, setEnabled] = React.useState(false);
+
+<Switch
+  checked={enabled}
+  onCheckedChange={(val) => setEnabled(val)}
+/>
+
+// Disabled state
+<Switch disabled checked={true} />
 ```
 
-The component automatically handles the visual transition between states, applying `bg-ods-accent` when checked and `bg-gray-600` when unchecked, with a smooth sliding thumb animation.
+## Key Behaviors
+
+- **Hybrid state management** — Maintains local `isChecked` state via `useState`, synced with the `checked` prop via `useEffect`, allowing both controlled and uncontrolled usage.
+- **Thumb animation** — The inner thumb translates `8px` on toggle using inline `transform` with a `duration-200` transition.
+- **ODS token styling** — Uses design tokens (`ods-accent`, `ods-text-secondary`, `ods-card`, `ods-bg-hover`, `ods-bg-active`, `ods-focus`) for consistent theming across states: default, hover, active, focus-visible, and disabled.
+- **Accessibility** — Inherits Radix UI's keyboard navigation, ARIA roles, and focus ring support out of the box.

package/src/components/ui/.tab-navigation.md

@@ -1,70 +1,73 @@
-<!-- source-hash: dca70073e5ccd0afa470136e81e1bd72 -->
-A flexible tab navigation component that supports both controlled state management and URL synchronization for maintaining tab state across page reloads and browser navigation.
+<!-- source-hash: 98a7f0660803887b4fe8c81807718051 -->
+Accessible, scrollable tab navigation component with optional URL synchronization and render prop support for content rendering.
 
 ## Key Components
 
-**Main Export:**
-- `TabNavigation` - The primary tab navigation component with URL sync capabilities
+### `TabNavigation`
+Main component that renders a horizontal tab bar with scroll overflow handling, fade gradients, and flexible state management modes.
 
-**Interfaces:**
-- `TabItem` - Defines tab structure with id, label, icon, optional component, and status indicator
-- `TabNavigationUrlSyncOptions` - Configuration options for URL parameter synchronization
+### Interfaces
 
-**Utility Functions:**
-- `getTabById()` - Retrieves a tab item by its ID
-- `getTabComponent()` - Extracts the React component from a tab item
+| Export | Description |
+|--------|-------------|
+| `TabItem` | Tab definition — `id`, `label`, `icon`, optional `component` and status `indicator` |
+| `TabNavigationUrlSyncOptions` | URL sync config — `paramName` (default: `'tab'`) and `replaceState` (default: `true`) |
+
+### Utility Functions
+
+| Function | Description |
+|----------|-------------|
+| `getTabById` | Finds a `TabItem` by `id` from a tabs array |
+| `getTabComponent` | Returns the `component` for a given tab id, or `null` |
 
 ## Usage Example
 
+**Controlled mode (no URL sync):**
+
 ```typescript
 import { TabNavigation, TabItem } from './tab-navigation'
 import { HomeIcon, SettingsIcon } from 'lucide-react'
 
 const tabs: TabItem[] = [
-  {
-    id: 'home',
-    label: 'Home',
-    icon: HomeIcon,
-    component: HomeComponent,
-    indicator: 'success'
-  },
-  {
-    id: 'settings',
-    label: 'Settings', 
-    icon: SettingsIcon,
-    component: SettingsComponent,
-    indicator: 'warning'
-  }
+  { id: 'home', label: 'Home', icon: HomeIcon },
+  { id: 'settings', label: 'Settings', icon: SettingsIcon, indicator: 'warning' },
 ]
 
-// URL sync mode (maintains state in URL)
-function MyApp() {
-  return (
-    <TabNavigation
-      tabs={tabs}
-      urlSync={{ paramName: 'view', replaceState: true }}
-      defaultTab="home"
-    >
-      {(activeTab) => {
-        const TabComponent = getTabComponent(tabs, activeTab)
-        return TabComponent ? <TabComponent /> : null
-      }}
-    </TabNavigation>
-  )
-}
-
-// Controlled mode
-function ControlledApp() {
-  const [activeTab, setActiveTab] = useState('home')
-  
-  return (
-    <TabNavigation
-      tabs={tabs}
-      activeTab={activeTab}
-      onTabChange={setActiveTab}
-    />
-  )
-}
+<TabNavigation
+  tabs={tabs}
+  activeTab={activeTab}
+  onTabChange={setActiveTab}
+>
+  {(tab) => <div>Content for: {tab}</div>}
+</TabNavigation>
+```
+
+**URL sync mode (persists active tab in query string):**
+
+```typescript
+<TabNavigation
+  tabs={tabs}
+  urlSync={{ paramName: 'section', replaceState: true }}
+  defaultTab="home"
+>
+  {(activeTab) => <ActiveTabContent tabId={activeTab} />}
+</TabNavigation>
+```
+
+**Forced scroll gradients with custom shadow color:**
+
+```typescript
+<TabNavigation
+  tabs={tabs}
+  showRightGradient
+  shadowClassName="from-black"
+  urlSync
+/>
 ```
 
-The component features gradient backgrounds, status indicators, horizontal scrolling for overflow, and smooth transitions between tab states.
+## Behavior Notes
+
+- Scroll overflow is detected via `ResizeObserver` and `scroll` events — fade gradients appear automatically on overflowing edges
+- The bottom border line fades to transparent on edges with active scroll shadows
+- URL sync mode reacts to browser back/forward navigation via `searchParams` changes
+- `indicator` dots render as color-coded badges (`error` → red, `warning` → accent yellow, `success` → green) over the tab icon

package/src/components/ui/.tab-selector.md

@@ -0,0 +1,40 @@
+<!-- source-hash: 0e28e1e106dbf76027ae86587226825d -->
+A accessible, styled tab selector component that renders a group of toggle buttons for switching between views or options, supporting icons, badges, disabled states, and two visual variants.
+
+## Key Components
+
+### Interfaces
+- **`TabSelectorItem`** — Defines individual tab configuration: `id`, optional `label`, `ariaLabel` (required for icon-only tabs), `icon`, `disabled`, and `badge`
+- **`TabSelectorProps`** — Component props including `value`, `onValueChange`, `items`, `variant`, `label`, `disabled`, and `className`
+
+### Component
+- **`TabSelector`** — Controlled tab button group that maps `items` to styled `<button>` elements, applying active/disabled/hover styles based on state and variant
+
+## Usage Example
+
+```typescript
+import { TabSelector } from './tab-selector'
+import { LayoutGrid, List } from 'lucide-react'
+
+const [view, setView] = React.useState('grid')
+
+<TabSelector
+  value={view}
+  onValueChange={setView}
+  label="View Mode"
+  variant="primary"
+  items={[
+    { id: 'grid', label: 'Grid', icon: <LayoutGrid /> },
+    { id: 'list', label: 'List', icon: <List /> },
+    { id: 'map',  label: 'Map',  disabled: true },
+  ]}
+/>
+```
+
+## Notes
+
+| Prop | Default | Description |
+|------|---------|-------------|
+| `variant` | `primary` | `primary` uses accent background; `secondary` uses surface grey |
+| `disabled` | `undefined` | Disables all tabs when set; overrides per-item `disabled` |
+| `ariaLabel` | — | Required on items where `label` is omitted (icon-only) |

package/src/components/ui/.tag-key-value-filter.md

@@ -0,0 +1,56 @@
+<!-- source-hash: fecbf4975a9d0b0bedd4c57c8ae9a440 -->
+A two-level filter UI component that renders tag key/value selections as grouped checkbox lists, using a `"key:value"` string format to represent selected tags.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `TagKeyValueFilter` | Component | Main filter component rendering key checkboxes and dynamic value sections |
+| `TagKeyConfig` | Interface | Defines a tag key with its `key`, `label`, and available `values` |
+| `TagValueOption` | Interface | Defines a single selectable value with `id`, `label`, and optional `count` |
+| `TagKeyValueFilterProps` | Interface | Props for the main component |
+
+**Internal logic:**
+- `selectedMap` — parses `selectedTags` strings into `Map<key, Set<values>>` for O(1) lookups
+- `handleKeyToggle` — enables/disables an entire key group; uses an empty marker (`"key:"`) to keep value sections visible
+- `handleValueToggle` — toggles individual values; preserves the empty marker when the last value is unchecked
+
+## Usage Example
+
+```typescript
+import { TagKeyValueFilter } from "./tag-key-value-filter"
+
+const keys = [
+  {
+    key: "site",
+    label: "Site",
+    values: [
+      { id: "chicago", label: "Chicago", count: 12 },
+      { id: "dallas",  label: "Dallas",  count: 8  },
+    ],
+  },
+  {
+    key: "env",
+    label: "Environment",
+    values: [
+      { id: "production", label: "Production" },
+      { id: "staging",    label: "Staging"    },
+    ],
+  },
+]
+
+function MyFilters() {
+  const [selectedTags, setSelectedTags] = useState<string[]>([])
+
+  return (
+    <TagKeyValueFilter
+      keys={keys}
+      selectedTags={selectedTags}   // e.g. ["site:chicago", "env:production"]
+      onTagsChange={setSelectedTags}
+      keysTitle="Filter by Tag"
+    />
+  )
+}
+```
+
+> **Note:** Selected tags use the `"key:value"` format (e.g. `"site:chicago"`). An empty marker `"site:"` is used internally to keep a key's value section rendered even when no values are checked yet.

package/src/components/ui/.tag-search-input.md

@@ -0,0 +1,53 @@
+<!-- source-hash: 96e461088a5374855c0977550d1322c9 -->
+A controlled search input component that combines inline tag chips with a text input, supporting automatic or fixed tag overflow with a popup for hidden tags.
+
+## Key Components
+
+### `TagSearchOption<T>`
+Generic interface representing a selectable tag with a `label` string and typed `value`.
+
+### `TagSearchInputProps<T>`
+Full props interface for the component, including:
+- `tags` / `searchValue` — controlled state inputs
+- `onSearchChange` / `onTagRemove` / `onClearAll` — mutation callbacks
+- `limitTags` — `number | "auto"` (default `"auto"`) controls visible tag count
+- `renderTag` / `getLimitTagsText` — render customization slots
+- `onSubmit` / `onKeyDown` — keyboard event hooks
+
+### `TagSearchInput<T>`
+The main generic component. Renders a styled input container with:
+- **Visible tags** — rendered as `<Tag>` chips up to `visibleCount`
+- **Overflow badge** — a `+N` button that toggles a `HiddenTagsPopup`
+- **Text input** — flex-grows into remaining space
+- **Clear all button** — pinned right, appears when input or tags have values
+- **Off-screen measurement divs** — used by `useAutoLimitTags` to compute available width
+
+## Usage Example
+
+```typescript
+import { TagSearchInput, TagSearchOption } from "./tag-search-input"
+
+const options: TagSearchOption<number>[] = [
+  { label: "Windows", value: 1 },
+  { label: "macOS", value: 2 },
+  { label: "Linux", value: 3 },
+]
+
+function FilterBar() {
+  const [tags, setTags] = useState(options)
+  const [search, setSearch] = useState("")
+
+  return (
+    <TagSearchInput<number>
+      tags={tags}
+      searchValue={search}
+      onSearchChange={setSearch}
+      onTagRemove={(val) => setTags((prev) => prev.filter((t) => t.value !== val))}
+      onClearAll={() => { setTags([]); setSearch("") }}
+      onSubmit={(val) => console.log("submitted:", val)}
+      limitTags="auto"
+      placeholder="Filter devices..."
+    />
+  )
+}
+```

package/src/components/ui/.tag.md

@@ -1,40 +1,58 @@
-<!-- source-hash: 7de1b4de95dd4335aa90878cda53e860 -->
-A React component for displaying labeled tags with multiple visual variants and optional close functionality. The component uses class-variance-authority for consistent styling across different states and contexts.
+<!-- source-hash: af3df5d03b971509e29cd6ef6c4c1640 -->
+A client-side Tag component for displaying labeled badges with optional icons and dismissal functionality, built on `class-variance-authority` for variant-based styling.
 
 ## Key Components
 
-- **`Tag`** - Main component that renders a styled tag with optional icon and close button
-- **`tagVariants`** - CVA configuration defining styling variants (primary, outline, good, warning, error, critical, grey)
-- **`TagProps`** - Interface extending HTML div attributes with variant props, icon, and close handler
+- **`Tag`** — Main component rendering a styled badge with support for icons, labels, and a close button
+- **`tagVariants`** — CVA variant config exported for external reuse; supports 7 visual styles
+- **`TagProps`** — Interface extending `HTMLAttributes<HTMLDivElement>` with tag-specific props
+
+### Variants
+
+| Variant | Use Case |
+|---------|----------|
+| `primary` | Default yellow highlight |
+| `outline` | Dark background with border |
+| `success` | Green success state |
+| `warning` | Yellow warning state |
+| `error` | Red soft error state |
+| `critical` | Solid red critical alert |
+| `grey` | Neutral/muted state |
+
+### Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `label` | `React.ReactNode` | Required tag text or content |
+| `variant` | `TagVariant` | Visual style (default: `primary`) |
+| `icon` | `React.ReactNode` | Optional leading icon |
+| `onClose` | `() => void` | Renders dismiss button when provided |
+| `disabled` | `boolean` | Applies disabled styling and prevents interaction |
+| `labelClassName` | `string` | Additional classes for the label span |
 
 ## Usage Example
 
 ```typescript
-import { Tag } from './tag'
-import { AlertCircle } from 'lucide-react'
-
 // Basic tag
-<Tag>Development</Tag>
-
-// Tag with variant
-<Tag variant="error">Critical Issue</Tag>
-
-// Tag with icon and close functionality
-<Tag 
-  variant="success"
-  icon={<AlertCircle />}
-  onClose={() => console.log('Tag removed')}
->
-  Success
-</Tag>
-
-// Custom styling
-<Tag 
+<Tag label="Active" variant="success" />
+
+// With icon and close button
+<Tag
+  label="Urgent"
+  variant="critical"
+  icon={<AlertIcon />}
+  onClose={() => removeTag("urgent")}
+/>
+
+// Disabled state
+<Tag
+  label="Unavailable"
   variant="outline"
-  className="custom-spacing"
->
-  Custom Tag
-</Tag>
-```
-
-The component supports seven visual variants with hover and active states, uses CSS custom properties for theming, and includes accessibility features like proper ARIA labels for the close button. The close button prevents event propagation to avoid triggering parent click handlers.
+  disabled
+/>
+
+// Using tagVariants externally
+<div className={cn(tagVariants({ variant: "warning" }), "custom-class")}>
+  Custom element
+</div>
+```

package/src/components/ui/.tags-manager.md

@@ -0,0 +1,60 @@
+<!-- source-hash: 4570f165151567924d10e97102adf2d3 -->
+A full-featured tag management component that provides a searchable, multi-select tag picker with inline create, edit, and delete capabilities via a popover dropdown.
+
+## Key Components
+
+### Interfaces
+- **`TagItem`** — Shape of a tag object: `{ id, name, color? }`
+- **`TagsManagerProps`** — Full prop contract for the component, including async CRUD callbacks and loading states
+
+### Component
+- **`TagsManager`** — The primary exported component; renders a label-anchored popover with a chip-style multi-select input and a scrollable tag list
+
+### Internal Behaviors
+- `toggleTag` — Adds or removes a tag ID from the selection
+- `handleCreate` — Calls `onCreateTag`, auto-selects the result, and clears search
+- `startEdit` / `confirmEdit` / `cancelEdit` — Inline row-level edit flow
+- `handleDelete` — Calls `onDeleteTag` and removes the ID from selection if present
+- `handleClearAll` — Resets all selected IDs and clears the search input
+
+## Usage Example
+
+```typescript
+import { TagsManager, TagItem } from "@/components/ui/tags-manager";
+
+const allTags: TagItem[] = [
+  { id: "1", name: "Bug" },
+  { id: "2", name: "Feature" },
+  { id: "3", name: "Urgent" },
+];
+
+function TicketForm() {
+  const [selectedIds, setSelectedIds] = React.useState<string[]>(["1"]);
+
+  return (
+    <TagsManager
+      tags={allTags}
+      selectedIds={selectedIds}
+      onChange={setSelectedIds}
+      onCreateTag={async (name) => {
+        const created = await api.tags.create({ name });
+        return created; // must return TagItem
+      }}
+      onUpdateTag={async (id, name) => {
+        await api.tags.update(id, { name });
+      }}
+      onDeleteTag={async (id) => {
+        await api.tags.delete(id);
+      }}
+      label="Ticket Tags"
+      searchPlaceholder="Search tags..."
+    />
+  );
+}
+```
+
+**Key behaviours to note:**
+- Pressing `Backspace` on an empty search removes the last selected tag
+- Pressing `Enter` while typing a new (non-existing) name triggers `onCreateTag`
+- Edit/delete action buttons appear on row hover and are hidden otherwise
+- The popover stays open while interacting inside the anchor container