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

package/src/components/ui/.dashboard-info-card.md

@@ -1,41 +1,48 @@
-<!-- source-hash: b79fb965ec043fff7ff7066e9d359aa6 -->
-A reusable dashboard metrics card component that displays key performance indicators with optional progress visualization and navigation capabilities.
+<!-- source-hash: ad7aa24ce00c67388baad4341f1e3d5b -->
+A dashboard metric card component that displays a title, value, optional percentage, circular progress indicator, and tooltip — supporting both static and navigable (linked) variants.
 
 ## Key Components
 
-- **DashboardInfoCard**: Main component that renders a card with title, value, optional percentage, and circular progress indicator
-- **Props Interface**: Comprehensive configuration including styling, navigation (`href`), click handlers, and progress display options
-- **Navigation Logic**: Supports both programmatic navigation via `href` prop and custom click handlers via `onClick`
-- **Value Formatting**: Automatically formats numeric values with locale-appropriate thousand separators
+### `DashboardInfoCard`
+Main export. Renders a styled card with:
+- **Title** — secondary text label
+- **Value** — formatted number (via `toLocaleString`) or string, with optional custom className
+- **Percentage** — displayed as a `Tag` (for `warning`/`error` variants) or plain secondary text
+- **Circular progress ring** — shown when `showProgress` and `percentage` are both provided
+- **Tooltip** — question-mark icon trigger via `FloatingTooltip`
+- **Link behavior** — when `href` is supplied, renders as a Next.js `Link` with hover accent styles
+
+### `DashboardInfoCardProps`
+Interface driving all card configuration, including `progressOverflow` which controls how the `CircularProgress` ring handles values exceeding 100 (`'clamp'` default or `'wrap'` for overflow/overage display).
 
 ## Usage Example
 
 ```typescript
-import { DashboardInfoCard } from './dashboard-info-card'
-
-// Basic usage with navigation
+// Static metric card
 <DashboardInfoCard
-  title="Total Users"
-  value={1250}
-  href="/dashboard/users"
+  title="Open Tickets"
+  value={142}
+  percentage={72}
+  showProgress
+  progressVariant="warning"
+  tooltip="Tickets currently unresolved"
 />
 
-// With progress indicator and custom styling
+// Navigable card with overflow progress
 <DashboardInfoCard
-  title="Server Uptime"
-  value="99.9"
-  percentage={99.9}
-  showProgress={true}
-  progressColor="#00ff88"
-  className="col-span-2"
+  title="SLA Breaches"
+  value={18}
+  percentage={110}
+  showProgress
+  progressVariant="error"
+  progressOverflow="wrap"
+  href="/reports/sla"
 />
 
-// With custom click handler
+// Simple card, no progress
 <DashboardInfoCard
-  title="Active Sessions"
-  value={847}
-  onClick={() => console.log('Sessions clicked')}
+  title="Devices Online"
+  value="1,024"
+  className="col-span-2"
 />
-```
-
-The component uses the `InteractiveCard` wrapper for consistent hover states and accessibility, with special styling for navigation-enabled cards that highlight on hover. Progress visualization is provided through the `CircularProgress` component when enabled.
+```

package/src/components/ui/.date-picker.md

@@ -1,44 +1,46 @@
-<!-- source-hash: d6fe11c9ed7217421566bb0d75070790 -->
-A date picker component built with Radix UI Popover and react-day-picker, supporting both single date and date range selection modes with customizable styling and locale support.
+<!-- source-hash: c8a503e7c476a61ed70475150ecd1672 -->
+A composable date picker component supporting both single-date and date-range selection modes, built on `react-day-picker` and `@radix-ui/react-popover` with Flamingo's design system tokens.
 
 ## Key Components
 
-### Types
-- **`DatePickerMode`** - Union type for picker modes: "single" | "range"
-- **`DatePickerBaseProps`** - Shared props interface with placeholder, formatting, and constraints
-- **`SingleDatePickerProps`** - Props for single date selection mode
-- **`RangeDatePickerProps`** - Props for date range selection mode
-- **`DatePickerProps`** - Union of single and range props
-
-### Components
-- **`CalendarNavButton`** - Navigation button for previous/next month controls
-- **`DatePickerCalendar`** - Core calendar component with month navigation and date selection
-- **Helper functions** - `defaultFormatDate` and `formatDateRange` for date formatting
+| Export | Type | Description |
+|--------|------|-------------|
+| `DatePickerProps` | Type | Union of `SingleDatePickerProps` \| `RangeDatePickerProps` |
+| `DatePickerMode` | Type | `"single"` \| `"range"` |
+| `DatePickerBaseProps` | Interface | Shared props: `placeholder`, `disabled`, `fromDate`, `toDate`, `label`, `error`, `invalid`, `locale` |
+| `SingleDatePickerProps` | Interface | Extends base; `value: Date`, `onChange: (date) => void` |
+| `RangeDatePickerProps` | Interface | Extends base; `value: DateRange`, `onChange: (range) => void` |
+| `DatePickerCalendar` | Component | Internal calendar renderer with custom nav and range styling |
+| `CalendarNavButton` | Component | Chevron nav button wrapping Flamingo `Button` |
 
 ## Usage Example
 
 ```typescript
-import { DatePicker } from "./date-picker";
-
 // Single date picker
 <DatePicker
   mode="single"
+  label="Start Date"
   value={selectedDate}
-  onChange={setSelectedDate}
-  placeholder="Select a date"
-  formatDate={(date) => date.toLocaleDateString()}
+  onChange={(date) => setSelectedDate(date)}
+  fromDate={new Date()}
 />
 
-// Date range picker
+// Date range picker (dual month)
 <DatePicker
   mode="range"
-  value={selectedRange}
-  onChange={setSelectedRange}
+  label="Date Range"
   numberOfMonths={2}
-  placeholder="Select date range"
-  fromDate={new Date()}
-  toDate={new Date(Date.now() + 365 * 24 * 60 * 60 * 1000)}
+  value={range}
+  onChange={(range) => setRange(range)}
+  error={formError}
+  invalid={!!formError}
 />
 ```
 
-The component features custom dark theme styling with Flamingo brand colors (#ffc008), responsive design, and accessibility support through ARIA labels and keyboard navigation.
+## Key Behaviors
+
+- **Single mode**: renders one `DayPicker` month with custom nav header
+- **Range mode**: supports 1 or 2 simultaneous months; range start/end use accent color (`--ods-accent`), range middle uses `--ods-open-yellow-light`
+- **Popover trigger**: displays a calendar icon with formatted date or placeholder text; applies red border when `invalid={true}`
+- **Month navigation**: controlled internally via `useState<Date>`, independent of `DayPicker`'s built-in nav (hidden via `hideNavigation`)
+- **Locale support**: passes `locale` prop directly to `DayPicker` for i18n formatting

package/src/components/ui/.device-card-compact.md

@@ -1,46 +1,45 @@
-<!-- source-hash: 208410c670289a616bb1324ae6148df2 -->
-A compact React component that renders device information (name and organization) in a space-efficient vertical layout, primarily designed for use in table cells or other constrained spaces.
+<!-- source-hash: e2dcd0d341956fecb4817f070e40d10a -->
+Compact React component for displaying device name and organization in a stacked layout, optimized for use within table cells.
 
 ## Key Components
 
-- **`DeviceCardCompactProps`** - Interface extending HTML div attributes with optional `deviceName` and `organization` props
-- **`DeviceCardCompact`** - React functional component that conditionally renders device details in a stacked layout
-- **Value validation** - Built-in filtering for null, undefined, '-', and string 'null' values
-- **Empty state handling** - Returns empty fragment when no valid data is present
+### `DeviceCardCompactProps`
+Extends `React.HTMLAttributes<HTMLDivElement>` with two optional fields:
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `deviceName` | `string \| null` | Primary label shown in larger text |
+| `organization` | `string \| null` | Secondary label shown in smaller muted text |
+
+### `DeviceCardCompact`
+A display-only component that renders device info in a vertical flex column. Performs null-safety checks against `null`, `undefined`, `'-'`, and the string `'null'`. Returns an empty fragment when both values are absent.
 
 ## Usage Example
 
 ```typescript
-import { DeviceCardCompact } from './device-card-compact'
-
 // Basic usage in a table cell
-<td>
-  <DeviceCardCompact 
-    deviceName="iPad Pro 12.9"
-    organization="Engineering Team"
-  />
-</td>
-
-// With custom styling
-<DeviceCardCompact 
-  deviceName="MacBook Air"
-  organization="Design Department"
-  className="border rounded p-2"
+<DeviceCardCompact
+  deviceName="DESKTOP-ABC123"
+  organization="Acme Corp"
 />
 
-// Handles missing/invalid data gracefully
-<DeviceCardCompact 
+// Handles missing/invalid values gracefully - renders nothing
+<DeviceCardCompact
   deviceName={null}
   organization="-"
-  // Returns empty fragment - nothing rendered
 />
 
-// Only organization available
-<DeviceCardCompact 
-  deviceName=""
-  organization="Marketing Team"
-  // Only shows organization
+// With custom className
+<DeviceCardCompact
+  deviceName="SERVER-01"
+  organization={null}
+  className="max-w-[200px]"
 />
 ```
 
-The component uses Tailwind CSS with custom font styling and automatically truncates long text to prevent layout overflow.
+## Behavior Notes
+
+- **Empty state**: Returns `<></>` when both props are falsy, `'-'`, or `'null'`
+- **Partial render**: Renders only the available field when one value is missing
+- **Overflow**: Both labels use `truncate` with a `title` attribute for full text on hover
+- **Typography**: Device name renders at `16px` (`ods-text-primary`); organization at `14px` (`ods-text-secondary`)

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

@@ -1,43 +1,43 @@
-<!-- source-hash: 20e16cdb03f6879f6848856b39fb1030 -->
-A React component that renders device information in a structured card layout with interactive actions and customizable visual elements.
+<!-- source-hash: c41a33e86906d6bdb122fe05e0b8b30c -->
+A React client component that renders a styled card UI for displaying device information, including OS type, organization, status, last seen timestamp, and tags.
 
 ## Key Components
 
-- **Device Interface**: Comprehensive device data model supporting various device types, OS platforms, and metadata
-- **ActionButton Interface**: Configuration for custom action buttons with labels and click handlers
-- **DeviceCardProps Interface**: Props interface extending HTML div attributes with device data and action configuration
-- **DeviceCard Component**: Main card component with four distinct content rows (header, OS/organization, actions, status/tags)
-- **formatLastSeen Function**: Internal utility for formatting date/time strings in YYYY/MM/DD, HH:MM format
+### Interfaces
+- **`Device`** — Core device data model with fields for `id`, `name`, `type`, `operatingSystem`, `organization`, `status`, `lastSeen`, `tags`, and network properties (`ipAddress`, `macAddress`, etc.)
+- **`ActionButton`** — Configuration for custom action buttons with `label`, `onClick`, `variant`, and `visible` controls
+- **`DeviceCardProps`** — Extends `HTMLAttributes<HTMLDivElement>` with `device`, `actions`, `statusTag`, and `onDeviceClick`
+
+### Main Export
+- **`DeviceCard`** — The primary card component rendering a two-row layout: device identity (icon, name, OS, org, action buttons) and metadata (status tag, last seen, tags)
 
 ## Usage Example
 
 ```typescript
-import { DeviceCard, Device } from './device-card'
-
-const device: Device = {
-  id: '123',
-  name: 'MacBook Pro',
-  type: 'laptop',
-  operatingSystem: 'darwin',
-  organization: 'Acme Corp',
-  status: 'active',
-  lastSeen: new Date(),
-  tags: ['development', 'remote']
-}
+import { DeviceCard } from './device-card'
 
 <DeviceCard
-  device={device}
+  device={{
+    name: "WORKSTATION-01",
+    operatingSystem: "windows",
+    organization: "Acme Corp",
+    status: "active",
+    lastSeen: new Date(),
+    tags: ["managed", "production"],
+  }}
   actions={{
-    moreButton: { visible: true, onClick: () => console.log('More clicked') },
-    detailsButton: { visible: true, component: <Button>Details</Button> },
+    moreButton: { visible: true, onClick: () => console.log("more clicked") },
     customActions: [
-      { label: 'Connect', onClick: () => connect(device.id) },
-      { label: 'Restart', onClick: () => restart(device.id) }
+      { label: "Remote", onClick: () => startRemoteSession(), visible: true }
     ]
   }}
-  statusBadgeComponent={<StatusBadge status={device.status} />}
-  onDeviceClick={(device) => navigate(`/devices/${device.id}`)}
+  statusTag={{ variant: "success", label: "Online" }}
+  onDeviceClick={(device) => router.push(`/devices/${device.id}`)}
 />
 ```
 
-The component uses OpenFrame's design system (ODS) classes and supports both legacy OS identifiers and the newer OSPlatformId system for cross-compatibility.
+## Notes
+
+- `operatingSystem` supports both `OSPlatformId` values and legacy strings (`macos`, `ios`, `android`); `macos` is internally mapped to `darwin` for icon resolution
+- Action buttons use `e.stopPropagation()` to prevent triggering `onDeviceClick` when interacting with controls
+- `lastSeen` accepts either a `string` or `Date` and formats to `YYYY/MM/DD, HH:MM`

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

@@ -1,30 +1,36 @@
-<!-- source-hash: 2adff8bf876dd4a242bbb418cc3662e5 -->
-A styled dialog component system built on top of Radix UI's Dialog primitive, providing a complete modal implementation with overlay, animations, and customizable styling.
+<!-- source-hash: 1007936b4fa31192c76c72547575559a -->
+Accessible modal dialog component built on Radix UI's `DialogPrimitive`, providing a fully composed set of dialog sub-components with enter/exit animations, backdrop blur overlay, and a built-in close button.
 
 ## Key Components
 
-- **Dialog** - Root dialog component (alias for DialogPrimitive.Root)
-- **DialogTrigger** - Button to open the dialog (alias for DialogPrimitive.Trigger)
-- **DialogContent** - Main dialog container with overlay, close button, and animations
-- **DialogOverlay** - Backdrop overlay with blur effect and fade animations
-- **DialogHeader/DialogFooter** - Layout containers for dialog sections
-- **DialogTitle/DialogDescription** - Semantic text components with proper styling
-- **DialogClose** - Close button component (alias for DialogPrimitive.Close)
+| Export | Description |
+|--------|-------------|
+| `Dialog` | Root component managing open/close state |
+| `DialogTrigger` | Element that opens the dialog on interaction |
+| `DialogContent` | Main modal container; renders via `DialogPortal` with overlay, animations, and a close (`X`) button |
+| `DialogOverlay` | Fixed full-screen backdrop with blur and fade animations |
+| `DialogHeader` | Layout wrapper for title/description area |
+| `DialogFooter` | Layout wrapper for action buttons (reverses column order on mobile) |
+| `DialogTitle` | Semibold heading with accessible binding |
+| `DialogDescription` | Muted secondary text beneath the title |
+| `DialogClose` | Primitive close button for custom trigger placement |
+| `DialogPortal` | Renders dialog outside the DOM tree via a portal |
 
 ## Usage Example
 
 ```typescript
 import {
   Dialog,
+  DialogTrigger,
   DialogContent,
-  DialogDescription,
-  DialogFooter,
   DialogHeader,
   DialogTitle,
-  DialogTrigger,
-} from "./dialog"
+  DialogDescription,
+  DialogFooter,
+  DialogClose,
+} from "@/components/ui/dialog"
 
-function MyDialog() {
+export function ConfirmDialog() {
   return (
     <Dialog>
       <DialogTrigger asChild>
@@ -38,7 +44,10 @@ function MyDialog() {
           </DialogDescription>
         </DialogHeader>
         <DialogFooter>
-          <button type="submit">Confirm</button>
+          <DialogClose asChild>
+            <button>Cancel</button>
+          </DialogClose>
+          <button onClick={() => console.log("confirmed")}>Confirm</button>
         </DialogFooter>
       </DialogContent>
     </Dialog>
@@ -46,4 +55,4 @@ function MyDialog() {
 }
 ```
 
-The dialog features automatic backdrop blur, smooth zoom/slide animations, responsive design, and accessibility features including focus management and keyboard navigation.
+> `DialogContent` automatically injects `DialogOverlay` and the close (`X`) button — no need to add them manually. Use `DialogClose` only for custom close triggers within the footer or body.

package/src/components/ui/.drawer.md

@@ -0,0 +1,86 @@
+<!-- source-hash: 2221d7f0d18b72b3da12ead1872e85f9 -->
+A client-side drawer component built on Radix UI's Dialog primitive, providing animated slide-in panels from any viewport edge with optional drag-to-resize and localStorage persistence.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `Drawer` | Component | Root dialog primitive (alias for `DialogPrimitive.Root`) |
+| `DrawerTrigger` | Component | Trigger element to open the drawer |
+| `DrawerClose` | Component | Button/element to close the drawer |
+| `DrawerPortal` | Component | Renders drawer outside the DOM tree |
+| `DrawerOverlay` | Component | Semi-transparent backdrop with fade animations |
+| `DrawerContent` | Component | Main panel with slide animations, resize handle, and variant support |
+| `drawerVariants` | CVA | Wrapper positioning variants (`side`, `flush`) |
+| `drawerPanelVariants` | CVA | Panel chrome variants (rounded corners, border, padding) |
+| `DrawerResizeHandle` | Internal | Drag/keyboard-accessible resize handle rendered as panel sibling |
+| `useResizableSize` | Hook | Manages clamped panel size with viewport awareness and localStorage |
+
+**`DrawerContent` Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `side` | `"right" \| "left" \| "top" \| "bottom"` | `"right"` | Slide-in direction |
+| `flush` | `boolean` | `false` | Full-bleed mode (removes padding/border/rounded on mobile) |
+| `resizable` | `boolean` | — | Enables drag-to-resize handle |
+| `minSize` | `number` | — | Minimum resize size in px |
+| `maxSize` | `number` | — | Maximum resize size in px (also clamped by viewport) |
+| `defaultSize` | `number` | — | Initial size in px when no localStorage entry exists |
+| `storageKey` | `string` | — | localStorage key for persisting size across sessions |
+| `mobileBreakpoint` | `number` | — | Px breakpoint below which resizing is disabled |
+| `overlayClassName` | `string` | — | Additional classes for the overlay |
+| `resizeAriaLabel` | `string` | — | Accessible label for the resize handle |
+
+## Usage Example
+
+```typescript
+import {
+  Drawer,
+  DrawerTrigger,
+  DrawerClose,
+  DrawerContent,
+} from "@/components/ui/drawer"
+
+// Basic drawer from the right
+function BasicDrawer() {
+  return (
+    <Drawer>
+      <DrawerTrigger asChild>
+        <button>Open Panel</button>
+      </DrawerTrigger>
+      <DrawerContent side="right">
+        <p>Drawer content here</p>
+        <DrawerClose asChild>
+          <button>Close</button>
+        </DrawerClose>
+      </DrawerContent>
+    </Drawer>
+  )
+}
+
+// Resizable flush chat panel persisted across sessions
+function ChatDrawer() {
+  return (
+    <Drawer>
+      <DrawerTrigger asChild>
+        <button>Open Chat</button>
+      </DrawerTrigger>
+      <DrawerContent
+        side="right"
+        flush
+        resizable
+        minSize={280}
+        maxSize={800}
+        defaultSize={400}
+        storageKey="chat-panel-width"
+        mobileBreakpoint={768}
+        resizeAriaLabel="Resize chat panel"
+      >
+        <p>Chat content</p>
+      </DrawerContent>
+    </Drawer>
+  )
+}
+```
+
+> **Resize handle accessibility:** The handle supports keyboard navigation — `ArrowLeft`/`ArrowRight` (or `ArrowUp`/`ArrowDown`) resize in 16px steps; hold `Shift` for 40px steps. `Home`/`End` jump to `minSize`/`maxSize`.

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

@@ -0,0 +1,45 @@
+<!-- source-hash: 755936e5a23162889a0f4b377887a066 -->
+A styled dropdown trigger button that combines a labeled action area with a rotating chevron indicator, opening a `MoreActionsMenu` on click.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `DropdownButton` | Component | Main trigger button that wraps `MoreActionsMenu` |
+| `DropdownButtonProps` | Interface | Props definition for the component |
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | — | Button label text |
+| `icon` | `ReactNode` | — | Optional leading icon |
+| `items` | `MoreActionsItem[]` | — | Dropdown menu items |
+| `align` | `'start' \| 'center' \| 'end'` | `'end'` | Menu alignment |
+| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` | Menu opening side |
+| `disabled` | `boolean` | — | Disables interaction |
+
+## Key Behaviors
+
+- **Single click target** — label and chevron areas are visually separated by a border seam but share one `<button>` element
+- **Open state styles** — background lightens (`ods-bg-hover`) when the menu is open or hovered
+- **Chevron rotation** — animates 180° when the dropdown is open
+- **Disabled guard** — blocks `onOpenChange` and prevents pointer events when `disabled` is set
+
+## Usage Example
+
+```typescript
+import { DropdownButton } from './dropdown-button'
+import { SettingsIcon } from '../icons-v2-generated'
+
+<DropdownButton
+  label="Actions"
+  icon={<SettingsIcon />}
+  align="end"
+  side="bottom"
+  items={[
+    { label: 'Edit', onClick: () => console.log('edit') },
+    { label: 'Delete', onClick: () => console.log('delete'), destructive: true },
+  ]}
+/>
+```

package/src/components/ui/.entity-image.md

@@ -0,0 +1,46 @@
+<!-- source-hash: 3405ab77a3bbd5f68b76564b38e7a642 -->
+A client-side React component that renders an entity's avatar image with an automatic initials-based fallback when the image source is unavailable or fails to load.
+
+## Key Components
+
+### `EntityImageProps`
+| Prop | Type | Description |
+|------|------|-------------|
+| `src` | `string \| null` | Image URL to display |
+| `alt` | `string` | Alt text for the image and fallback aria-label |
+| `fallbackText` | `string` | Overrides `alt` as the initials source |
+| `className` | `string` | Additional CSS classes |
+
+### `EntityImage`
+Main export. Renders an `<img>` tag when a valid `src` is provided and loads successfully. Falls back to a styled `<div>` showing two-letter initials (via `getFirstLastInitials`) or `?` when no initials can be derived.
+
+**Fallback triggers:**
+- `src` is `null` or `undefined`
+- Image fires an `onError` event (broken URL, network failure, etc.)
+- Image error state resets automatically when `src` changes
+
+## Usage Example
+
+```typescript
+import { EntityImage } from './entity-image'
+
+// Renders the avatar image
+<EntityImage
+  src="https://cdn.example.com/avatars/acme.png"
+  alt="Acme Corp"
+/>
+
+// Renders initials fallback "AC" if image fails
+<EntityImage
+  src={null}
+  alt="Acme Corp"
+  className="my-custom-class"
+/>
+
+// Override initials source independently from alt text
+<EntityImage
+  src="https://cdn.example.com/avatars/john.png"
+  alt="User avatar"
+  fallbackText="John Doe"
+/>
+```

package/src/components/ui/.error-state.md

@@ -1,44 +1,57 @@
-<!-- source-hash: 8d026771a83a6389470261977d32ec19 -->
-A React component for displaying error states with customizable variants, icons, and action buttons for consistent error handling across the application.
+<!-- source-hash: 147d509f918f296b0265bcdeb8f2a9c1 -->
+Flexible error state display component for rendering contextual error, warning, and info messages with optional retry and navigation actions.
 
 ## Key Components
 
-- **ErrorState** - Main component with configurable title, message, variant (error/warning/info), and optional retry/home actions
-- **PageError** - Convenience component for general page errors with retry and home navigation options
-- **LoadError** - Specialized component for loading failures with retry functionality
-- **NotFoundError** - Component for 404-style errors with home navigation option
+### `ErrorState`
+The core component accepting the following props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `title` | `string` | `'Error'` | Heading text displayed above the message |
+| `message` | `string` | — | *(required)* Body text describing the error |
+| `variant` | `'error' \| 'warning' \| 'info'` | `'error'` | Controls color scheme and styling |
+| `showIcon` | `boolean` | `true` | Toggles the `AlertTriangle` icon |
+| `showRetry` | `boolean` | `false` | Shows "Try Again" button when `onRetry` is also provided |
+| `showHome` | `boolean` | `false` | Shows "Go Home" button when `onHome` is also provided |
+| `onRetry` | `() => void` | — | Callback fired on retry button click |
+| `onHome` | `() => void` | — | Callback fired on home button click |
+| `className` | `string` | — | Applied to the inner bordered card |
+| `containerClassName` | `string` | — | Applied to the outer wrapper `div` |
+
+### Convenience Components
+
+| Component | Variant | Buttons |
+|-----------|---------|---------|
+| `PageError` | `error` | Retry + Home |
+| `LoadError` | `error` | Retry |
+| `NotFoundError` | `warning` | Home |
 
 ## Usage Example
 
 ```typescript
 import { ErrorState, PageError, LoadError, NotFoundError } from './error-state'
 
-// Basic error with custom message
-<ErrorState 
-  message="Something went wrong while processing your request" 
-  variant="error"
-  showRetry 
-  onRetry={() => window.location.reload()}
-/>
-
-// Page error with navigation options
-<PageError 
-  message="Failed to load the dashboard"
+// Full control via ErrorState
+<ErrorState
+  title="Connection Failed"
+  message="Unable to reach the server."
+  variant="warning"
+  showRetry
   onRetry={() => refetch()}
-  onHome={() => router.push('/')}
 />
 
-// Loading error with retry
-<LoadError 
-  message="Unable to fetch user data"
-  onRetry={() => retry()}
+// Convenience wrappers
+<PageError
+  message="Something went wrong loading this page."
+  onRetry={() => router.refresh()}
+  onHome={() => router.push('/')}
 />
 
-// Not found error
-<NotFoundError 
-  message="The requested project was not found"
-  onHome={() => navigate('/projects')}
+<LoadError
+  message="Failed to load device list."
+  onRetry={() => refetch()}
 />
-```
 
-The component uses the OpenFrame Design System (ODS) color tokens and provides consistent styling across error, warning, and info variants with proper accessibility through semantic colors and icons.
+<NotFoundError onHome={() => router.push('/')} />
+```