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

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

@@ -1,44 +1,45 @@
-<!-- source-hash: 2667346028d431e1bcbabbae2bbfb32b -->
-A flexible, accessible modal dialog component system built with React and Tailwind CSS. Provides keyboard navigation, backdrop click handling, and scroll blocking functionality.
+<!-- source-hash: bde5cd5df57a305212c78a5d9d2b8add -->
+A **deprecated** modal dialog component set providing accessible overlay UI primitives. All exports are superseded by `ModalV2` from `./modal-v2`.
+
+> ⚠️ **Deprecated** — Migrate to `ModalV2` and its sub-components from `./modal-v2`.
 
 ## Key Components
 
-- **`Modal`** - Main modal container with overlay, keyboard handling (Escape key), and scroll blocking
-- **`ModalContent`** - Wrapper for modal body content
-- **`ModalHeader`** - Styled header section with bottom border
-- **`ModalTitle`** - Semantic h2 title element for the modal
-- **`ModalFooter`** - Footer section with right-aligned button layout
+| Export | Description |
+|--------|-------------|
+| `Modal` | Root overlay container; handles `Escape` key, backdrop click, and scroll locking |
+| `ModalContent` | Scrollable body area (`overflow-y-auto`) |
+| `ModalHeader` | Top section with bottom border, fixed height |
+| `ModalTitle` | Styled `<h2>` heading within the header |
+| `ModalFooter` | Bottom action bar, right-aligned with gap |
+
+All components use `React.forwardRef` and accept an optional `className` for Tailwind overrides via `cn()`.
 
 ## Usage Example
 
 ```typescript
-import { Modal, ModalHeader, ModalTitle, ModalContent, ModalFooter } from './modal'
-import { useState } from 'react'
-
-function MyComponent() {
-  const [isOpen, setIsOpen] = useState(false)
+import { Modal, ModalContent, ModalHeader, ModalTitle, ModalFooter } from "./modal"
 
+function ExampleDialog({ open, onClose }: { open: boolean; onClose: () => void }) {
   return (
-    <>
-      <button onClick={() => setIsOpen(true)}>Open Modal</button>
-      
-      <Modal isOpen={isOpen} onClose={() => setIsOpen(false)}>
-        <ModalHeader>
-          <ModalTitle>Confirm Action</ModalTitle>
-        </ModalHeader>
-        
-        <ModalContent>
-          <p className="px-6 py-4">Are you sure you want to proceed?</p>
-        </ModalContent>
-        
-        <ModalFooter>
-          <button onClick={() => setIsOpen(false)}>Cancel</button>
-          <button onClick={() => setIsOpen(false)}>Confirm</button>
-        </ModalFooter>
-      </Modal>
-    </>
+    <Modal isOpen={open} onClose={onClose}>
+      <ModalHeader>
+        <ModalTitle>Confirm Action</ModalTitle>
+      </ModalHeader>
+      <ModalContent className="px-6 py-4">
+        <p>Are you sure you want to proceed?</p>
+      </ModalContent>
+      <ModalFooter>
+        <button onClick={onClose}>Cancel</button>
+        <button onClick={onClose}>Confirm</button>
+      </ModalFooter>
+    </Modal>
   )
 }
 ```
 
-The modal automatically handles accessibility attributes (`role="dialog"`, `aria-modal="true"`), prevents background scrolling when open, and closes on Escape key or backdrop click.
+## Behavior Notes
+
+- Backdrop click and `Escape` key both trigger `onClose`
+- `document.body` scroll is blocked (`overflow: hidden`) while modal is open and restored on close/unmount
+- Renders at `z-index: 1300` using a fixed full-screen overlay

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

@@ -1,47 +1,54 @@
-<!-- source-hash: 2dd78ebc3acbb9fedfdbd148ee5426c8 -->
-A reusable dropdown menu component that displays contextual actions behind an ellipsis (three dots) icon button. Built on top of Radix UI's DropdownMenu primitive with custom OpenFrame design system styling.
+<!-- source-hash: d1c57ae6ae958d461aaf3fb171dd1d00 -->
+A compact, reusable dropdown menu component triggered by an ellipsis icon button, built on Radix UI's `DropdownMenu`. Supports both link-based and click-based menu items with optional icons, danger states, and controlled open/close behavior.
 
 ## Key Components
 
-- **`MoreActionsMenu`** - Main component that renders the ellipsis trigger and dropdown menu
-- **`MoreActionsItem`** - Type definition for menu items with label, click handler, optional icon, disabled state, and danger styling
-- **`MoreActionsMenuProps`** - Interface defining positioning, styling, and accessibility options
+### `MoreActionsItem`
+Type definition for individual menu entries:
+- `label` — display text
+- `onClick` — optional click handler
+- `href` — renders item as a `<Link>` (anchor tag) instead of a button
+- `openInNewTab` — applies `target="_blank"` when using `href`
+- `icon` — optional React node rendered before the label
+- `disabled` — disables interaction and reduces opacity
+- `danger` — applies error color styling to the icon
+
+### `MoreActionsMenuProps`
+Configuration interface for the menu:
+- `items` — array of `MoreActionsItem`
+- `align`, `side`, `sideOffset` — Radix positioning controls
+- `trigger` — optional custom trigger element (replaces default ellipsis button)
+- `open` / `onOpenChange` — controlled open state support
+
+### `MoreActionsMenu`
+The exported component. Renders either a default ellipsis icon `Button` or a custom `trigger`, with a `DropdownMenuContent` list of items.
 
 ## Usage Example
 
 ```typescript
 import { MoreActionsMenu } from './more-actions-menu'
-import { EditIcon, DeleteIcon } from '../icons'
-
-const menuItems = [
-  {
-    label: 'Edit Item',
-    onClick: () => console.log('Edit clicked'),
-    icon: <EditIcon />
-  },
-  {
-    label: 'Delete Item',
-    onClick: () => console.log('Delete clicked'),
-    icon: <DeleteIcon />,
-    danger: true
-  },
-  {
-    label: 'Disabled Action',
-    onClick: () => {},
-    disabled: true
-  }
-]
-
-function MyComponent() {
-  return (
-    <MoreActionsMenu
-      items={menuItems}
-      align="end"
-      side="bottom"
-      ariaLabel="Item actions"
-    />
-  )
-}
-```
+import { EditIcon, TrashIcon } from '../icons'
 
-The component automatically handles click events, disabled states, danger styling (red text for destructive actions), and provides proper keyboard accessibility through ARIA labels.
+<MoreActionsMenu
+  items={[
+    {
+      label: 'Edit',
+      icon: <EditIcon />,
+      onClick: () => console.log('edit'),
+    },
+    {
+      label: 'View Details',
+      href: '/tickets/123',
+      openInNewTab: true,
+    },
+    {
+      label: 'Delete',
+      icon: <TrashIcon />,
+      danger: true,
+      onClick: () => console.log('delete'),
+    },
+  ]}
+  align="end"
+  side="bottom"
+/>
+```

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

@@ -1,51 +1,45 @@
-<!-- source-hash: c0f00fd9117e172d8b481dcf3049b999 -->
-A reusable card component for displaying organization information with OpenMSP VendorCard styling parity, featuring interactive hover effects, customizable footers, and action buttons.
+<!-- source-hash: a5842b7f26b01448b4819804ae2a446d -->
+Reusable card component for displaying organization/client summary information in a grid or list layout, supporting optional navigation, action buttons, device counts, and customizable footer stats.
 
 ## Key Components
 
-- **Organization interface**: Type definition for organization data including id, name, image, industry, stats, and custom metadata
-- **OrganizationCardProps interface**: Comprehensive props interface supporting custom styling, action buttons, footer stats, and navigation
-- **OrganizationCard component**: Main card component with VendorCard-style hover effects, 60px organization logo, fixed-height description, and flexible footer stats display
+### Interfaces
+- **`Organization`** — Data model for an organization entity (id, name, imageUrl, industry, tier, devices, MRR, etc.)
+- **`OrganizationCardProps`** — Full prop interface including optional `href`, `actionButton`, `footerStats`, `customFooter`, and `deviceCount`
 
-## Usage Example
-
-```typescript
-import { OrganizationCard } from './organization-card'
-import { Monitor, Trash2 } from 'lucide-react'
+### Component
+- **`OrganizationCard`** — Renders the card with three configurable zones:
+  - **Header** — `EntityImage` + name + subtitle (industry, tier, or website)
+  - **Body** — Optional 2-line clamped description
+  - **Footer** — `customFooter` node or auto-rendered `footerStats` array
+  - **Top-right overlay** — Either a device count badge (with `Monitor` icon) or an action button (ghost/primary variant)
 
-// Basic usage with pre-fetched image
-const org = {
-  id: '123',
-  name: 'Acme Corp',
-  industry: 'Technology',
-  description: 'Leading software company...',
-  totalDevices: 150
-}
+When `href` is provided, the entire card is wrapped in a `Link` for navigation.
 
-// Simple card
-<OrganizationCard organization={org} />
+## Usage Example
 
-// With custom footer stats and action button
+```typescript
 <OrganizationCard
-  organization={org}
+  organization={{
+    id: "org_123",
+    name: "Acme Corp",
+    industry: "Manufacturing",
+    description: "A leading widget manufacturer.",
+    totalDevices: 42,
+  }}
+  href="/organizations/org_123"
+  deviceCount={42}
   footerStats={[
-    { icon: <Monitor className="w-4 h-4" />, value: 150, label: 'devices' },
-    { value: '$2,500', label: 'MRR' }
+    { icon: <DollarSign className="w-4 h-4" />, value: 1200, label: "MRR" },
   ]}
-  showActionButton
   actionButton={{
-    icon: <Trash2 className="h-4 w-4" />,
-    label: 'Remove',
-    onClick: (org) => handleRemove(org.id),
-    variant: 'ghost'
+    icon: <Trash2 className="w-4 h-4" />,
+    label: "Remove",
+    variant: "ghost",
+    onClick: (org, e) => handleRemove(org.id),
   }}
-  deviceCount={150}
+  showActionButton
 />
+```
 
-// With custom navigation
-<OrganizationCard
-  organization={org}
-  onClick={(org) => router.push(`/custom/${org.id}`)}
-  baseUrl="https://app.example.com"
-/>
-```
+> **Note:** `deviceCount` takes display priority over `showActionButton` — if both are provided, only the device badge renders in the top-right corner.

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

@@ -1,62 +1,52 @@
-<!-- source-hash: 4f2f7fa333798c2bab1dbe0d9f5200dc -->
-A responsive page actions component that provides flexible button layouts and mobile-optimized interfaces for page-level actions across OpenFrame.
+<!-- source-hash: 70d0d7bf97f25795ba22d26ce08d067f -->
+Responsive page-level action bar component that renders action buttons in three layout variants (`icon-buttons`, `primary-buttons`, `menu-primary`), automatically adapting between desktop and mobile layouts with overflow menus.
 
 ## Key Components
 
-- **`PageActions`** - Main component supporting three variants: `icon-buttons`, `primary-buttons`, and `menu-primary`
-- **`PageActionButton`** - Type definition for action buttons with label, onClick, icon, variant, and mobile visibility options
-- **`IconButtonsVariant`** - Desktop icon buttons that collapse to a single icon or menu on mobile
-- **`PrimaryButtonsVariant`** - Primary/outline buttons that become a fixed bottom bar on mobile
-- **`MenuPrimaryVariant`** - Combines dropdown menu with primary buttons, mobile-optimized bottom bar
-- **`usePageActionsBottomPadding`** - Hook returning CSS classes for bottom padding when fixed mobile bars are present
+### Types
+- **`PageActionButton`** — Action descriptor supporting labels, icons, links (`href`), submenus, split-button icon actions, and visibility/rendering flags like `showOnlyMobile` and `iconOnlyOnDesktop`
+- **`PageActionsProps`** — Props for the main `PageActions` component
+
+### Components
+- **`PageActions`** — Root component; dispatches to the correct variant
+- **`IconButtonsVariant`** — Desktop: icon buttons + optional overflow menu. Mobile: single icon or merged `...` dropdown
+- **`PrimaryButtonsVariant`** — Desktop: labeled buttons sorted by variant. Mobile: fixed bottom bar
+- **`MenuPrimaryVariant`** — Desktop: `...` menu + accent-styled primary buttons. Mobile: all actions in a single `...` dropdown
+
+### Utilities
+- **`renderActionButton`** — Renders a `Button`, `SplitButton`, or submenu `ActionsMenuDropdown` based on action config
+- **`actionToMenuItems`** — Converts a `PageActionButton` to `ActionsMenuItem[]` for mobile dropdown merging
+- **`usePageActionsBottomPadding`** — Hook returning a Tailwind padding class to prevent content from being obscured by the mobile bottom bar
 
 ## Usage Example
 
 ```typescript
-import { PageActions } from './page-actions'
-import { PlusIcon, EditIcon } from '../icons'
-
-// Icon buttons variant (collapses to menu on mobile)
-<PageActions
-  variant="icon-buttons"
-  actions={[
-    {
-      label: 'Create Item',
-      onClick: () => handleCreate(),
-      icon: <PlusIcon />,
-      variant: 'outline'
-    },
-    {
-      label: 'Edit',
-      onClick: () => handleEdit(),
-      icon: <EditIcon />,
-      disabled: !selectedItem
-    }
-  ]}
-  gap="md"
-/>
-
-// Primary buttons with fixed mobile bottom bar
-<PageActions
-  variant="primary-buttons"
-  actions={[
-    { label: 'Cancel', onClick: onCancel, variant: 'outline' },
-    { label: 'Save Changes', onClick: onSave, variant: 'primary', loading: isSaving }
-  ]}
-/>
-
-// Menu + primary variant for complex action sets
-<PageActions
-  variant="menu-primary"
-  actions={[
-    { label: 'Publish', onClick: onPublish, variant: 'primary' }
-  ]}
-  menuActions={[
-    { label: 'Duplicate', onClick: onDuplicate, icon: <CopyIcon /> },
-    { label: 'Delete', onClick: onDelete, icon: <TrashIcon />, danger: true }
-  ]}
-/>
-
-// Add bottom padding when using fixed mobile bars
-const paddingClass = usePageActionsBottomPadding('primary-buttons')
+import { PageActions, usePageActionsBottomPadding } from './page-actions'
+
+function MyPage() {
+  const bottomPad = usePageActionsBottomPadding('primary-buttons')
+
+  return (
+    <div className={bottomPad}>
+      <PageActions
+        variant="primary-buttons"
+        actions={[
+          {
+            label: 'Save',
+            variant: 'accent',
+            onClick: () => handleSave(),
+          },
+          {
+            label: 'More',
+            icon: <SettingsIcon />,
+            submenu: [
+              { id: 'export', label: 'Export', onClick: handleExport },
+              { id: 'delete', label: 'Delete', onClick: handleDelete },
+            ],
+          },
+        ]}
+      />
+    </div>
+  )
+}
 ```

package/src/components/ui/.phone-input.md

@@ -0,0 +1,54 @@
+<!-- source-hash: 8f44dd654f7205b5e41cde63c6ee32dd -->
+A composite phone number input component combining a country selector dropdown with a phone number text field, featuring debounced validation using `libphonenumber-js`.
+
+## Key Components
+
+### `PhoneInput` (main export)
+A controlled input component that renders a country code selector and phone number field side-by-side.
+
+**Props (`PhoneInputProps`):**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `value` | `string` | Current phone number value |
+| `countryCode` | `CountryCode` | Selected country (ISO code) |
+| `onPhoneChange` | `(phone: string) => void` | Called on phone input change |
+| `onCountryChange` | `(country: CountryCode) => void` | Called on country selection |
+| `onValidationChange` | `(isInvalid: boolean) => void` | Optional validation state callback |
+| `disabled` | `boolean` | Disables both inputs |
+| `placeholder` | `string` | Input placeholder text |
+| `onKeyDown` | `React.KeyboardEvent handler` | Key event passthrough |
+
+### `CountryOption` (internal)
+Renders a single country row inside the dropdown showing flag, dial code, and country name.
+
+### Validation Behavior
+- Input is restricted to digits, spaces, hyphens, and parentheses
+- Validation triggers via debounce (300ms) after 4+ digits are entered
+- Immediate validation fires on input blur
+- Empty input clears any invalid state without triggering validation
+
+## Usage Example
+
+```typescript
+import { PhoneInput } from './phone-input'
+import { useState } from 'react'
+import type { CountryCode } from 'libphonenumber-js'
+
+function ContactForm() {
+  const [phone, setPhone] = useState('')
+  const [country, setCountry] = useState<CountryCode>('US')
+  const [hasError, setHasError] = useState(false)
+
+  return (
+    <PhoneInput
+      value={phone}
+      countryCode={country}
+      onPhoneChange={setPhone}
+      onCountryChange={setCountry}
+      onValidationChange={setHasError}
+      placeholder="Phone Number (optional)"
+    />
+  )
+}
+```

package/src/components/ui/.progress-bar.md

@@ -1,42 +1,50 @@
-<!-- source-hash: 3772caa7006d2e37150d4cab56dc1904 -->
-A segmented progress bar component that dynamically calculates segments based on container width and provides configurable color thresholds for different data types.
+<!-- source-hash: e7dc6507dbb40dd8dffb5171634e1bd5 -->
+Segmented progress bar component that visualizes a numeric value (0–100) using dynamically calculated fill segments, with responsive sizing and threshold-based color coding.
 
 ## Key Components
 
-**ProgressBar** - Main React component that renders a horizontal segmented progress bar with:
-- Dynamic segment calculation using ResizeObserver
-- Configurable warning and critical thresholds
-- Inverted color logic for different data types (disk usage vs battery health)
-- ODS design token integration for consistent styling
+### `ProgressBarProps`
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `progress` | `number` | — | Value from 0–100 to display |
+| `warningThreshold` | `number` | `75` | Threshold for warning color |
+| `criticalThreshold` | `number` | `90` | Threshold for critical color |
+| `segmentWidth` | `number` | `3.43px` | Desktop segment width |
+| `mobileSegmentWidth` | `number` | `5px` | Mobile segment width |
+| `segmentGap` | `number` | `2px` | Gap between segments |
+| `height` | `number` | `24px` | Desktop bar height |
+| `mobileHeight` | `number` | `8px` | Mobile bar height |
+| `inverted` | `boolean` | `false` | Flips color logic (high = good) |
+
+### Color Logic
+- **Normal** (e.g., disk usage): green → warning → red as value increases
+- **Inverted** (e.g., battery health): red → warning → green as value increases
+- Uses ODS design tokens: `--ods-attention-green-success`, `--color-warning`, `--ods-attention-red-error`
+
+### Responsive Behavior
+Uses `useMdUp()` hook to switch between desktop and mobile segment dimensions. A `ResizeObserver` dynamically recalculates segment count based on container width, ensuring pixel-perfect fills on any layout.
 
 ## Usage Example
 
 ```typescript
-import { ProgressBar } from './progress-bar';
-
-// Disk usage (high = bad, red)
-<ProgressBar 
-  progress={85} 
-  warningThreshold={70} 
-  criticalThreshold={90}
-  height={20}
-/>
+// Normal mode — disk usage (high values = bad)
+<ProgressBar progress={85} warningThreshold={70} criticalThreshold={90} />
 
-// Battery health (high = good, green) 
-<ProgressBar 
-  progress={45}
+// Inverted mode — battery health (high values = good)
+<ProgressBar
+  progress={25}
+  warningThreshold={40}
+  criticalThreshold={80}
   inverted={true}
-  warningThreshold={30}
-  criticalThreshold={70}
 />
 
-// Custom styling
+// Custom sizing
 <ProgressBar
   progress={60}
-  segmentWidth={8}
+  segmentWidth={5}
+  mobileSegmentWidth={8}
+  height={32}
+  mobileHeight={12}
   segmentGap={3}
-  height={24}
 />
-```
-
-The component automatically adjusts segment count based on container width and applies appropriate colors using CSS custom properties. The `inverted` prop switches the color logic - useful for metrics where high values are positive (battery level) versus negative (disk usage).
+```

package/src/components/ui/.radio-group.md

@@ -1,36 +1,48 @@
-<!-- source-hash: 67512c48ad1cb3283a707c84ed5d2c77 -->
-A React radio group component built on Radix UI primitives with custom styling and accessibility features. This component provides a styled radio button interface for single-selection scenarios.
+<!-- source-hash: 519574bf2339595c3bc66b2894c29fca -->
+Accessible radio group components built on Radix UI primitives, providing three levels of abstraction: a base `RadioGroup`, a styled `RadioGroupItem`, and a higher-level `RadioGroupBlock` that renders labeled option cards from a data array.
 
 ## Key Components
 
-- **`RadioGroup`** - The root container component that wraps radio items in a grid layout
-- **`RadioGroupItem`** - Individual radio button with custom styling, focus states, and a filled circle indicator when selected
+| Export | Type | Description |
+|--------|------|-------------|
+| `RadioGroup` | Component | Thin wrapper around Radix `RadioGroup.Root` with `grid gap-2` layout |
+| `RadioGroupItem` | Component | Styled circular radio input with focus ring, disabled, hover, and checked states |
+| `RadioGroupBlock` | Component | Data-driven option list with label, description, trailing slot, error state, and two layout variants |
+| `RadioGroupBlockOption` | Interface | Option shape: `value`, `label`, `description?`, `disabled?`, `trailing?` |
+| `RadioGroupBlockProps` | Interface | Props for `RadioGroupBlock` including `options`, `variant`, `error`, `itemClassName` |
 
 ## Usage Example
 
 ```typescript
-import { RadioGroup, RadioGroupItem } from "./radio-group"
-
-function SettingsForm() {
-  const [theme, setTheme] = React.useState("light")
-
-  return (
-    <RadioGroup value={theme} onValueChange={setTheme}>
-      <div className="flex items-center space-x-2">
-        <RadioGroupItem value="light" id="light" />
-        <label htmlFor="light">Light theme</label>
-      </div>
-      <div className="flex items-center space-x-2">
-        <RadioGroupItem value="dark" id="dark" />
-        <label htmlFor="dark">Dark theme</label>
-      </div>
-      <div className="flex items-center space-x-2">
-        <RadioGroupItem value="system" id="system" />
-        <label htmlFor="system">System theme</label>
-      </div>
-    </RadioGroup>
-  )
-}
+import { RadioGroup, RadioGroupItem, RadioGroupBlock } from "@/components/ui/radio-group"
+
+// Primitive usage
+<RadioGroup defaultValue="a">
+  <RadioGroupItem value="a" id="a" />
+  <RadioGroupItem value="b" id="b" />
+</RadioGroup>
+
+// Block usage — separated variant (default)
+<RadioGroupBlock
+  name="plan"
+  defaultValue="pro"
+  options={[
+    { value: "free", label: "Free", description: "Up to 3 users" },
+    { value: "pro",  label: "Pro",  description: "$49/mo", trailing: <Badge>Popular</Badge> },
+    { value: "ent",  label: "Enterprise", disabled: true },
+  ]}
+  error="Please select a plan"
+/>
+
+// Block usage — grouped variant (single bordered card)
+<RadioGroupBlock
+  name="region"
+  variant="grouped"
+  options={[
+    { value: "us", label: "United States" },
+    { value: "eu", label: "Europe" },
+  ]}
+/>
 ```
 
-The component uses OpenFrame Design System (ODS) color tokens and includes proper focus management, disabled states, and keyboard navigation support through Radix UI's accessibility features.
+> The `grouped` variant wraps all options in a single rounded border with dividers between rows, while `separated` (default) renders each option as its own card. Both variants propagate `error` as a red border and an absolute helper text rendered below the group.