@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482

package/src/components/ui/.cursor-pagination.md

@@ -1,52 +1,64 @@
-<!-- source-hash: 0e65f8e03b416890c9d63ba33ba86a8e -->
-Cursor-based pagination UI components for navigating relay-style paginated data using start/end cursors instead of page numbers.
+<!-- source-hash: 9a5725df328375e394d39d73c7bbb936 -->
+Cursor-based pagination UI components supporting forward/backward navigation with optional reset-to-first-page functionality.
 
 ## Key Components
 
 ### `CursorPagination`
-Full-featured pagination bar with optional info text, Previous/Next navigation, and a reset-to-first-page button. Supports both compact and standard layouts.
+
+Full-featured pagination bar with info text display and configurable navigation controls.
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `hasNextPage` | `boolean` | — | Whether a next page exists |
+| `hasPreviousPage` | `boolean` | — | Whether a previous page exists |
+| `isFirstPage` | `boolean` | `true` | Disables reset/previous when on first page |
+| `startCursor` | `string \| null` | — | Cursor passed to `onPrevious` |
+| `endCursor` | `string \| null` | — | Cursor passed to `onNext` |
+| `currentCount` | `number` | — | Items shown in the current page |
+| `totalCount` | `number \| null` | — | Total item count (optional) |
+| `itemName` | `string` | `'items'` | Label used in display text |
+| `loading` | `boolean` | `false` | Disables all buttons |
+| `onNext` | `(cursor: string) => void` | — | Called with `endCursor` |
+| `onPrevious` | `(cursor: string) => void` | — | Called with `startCursor` |
+| `onReset` | `() => void` | — | Replaces Previous button with a reset/home button |
+| `showInfo` | `boolean` | `true` | Toggles the item count display text |
+| `compact` | `boolean` | `false` | Reduces padding and hides button labels on mobile |
+| `resetButtonLabel` | `string` | `'First'` | Label for the reset button |
+| `resetButtonIcon` | `'home' \| 'rotate'` | `'home'` | Icon for the reset button |
 
 ### `CursorPaginationSimple`
-Minimal icon-only variant using transparent buttons — ideal for inline or space-constrained contexts like table toolbars.
-
-### `CursorPaginationProps`
-Full interface supporting:
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `hasNextPage` | `boolean` | Required. Enables/disables Next button |
-| `hasPreviousPage` | `boolean` | Enables/disables Previous button |
-| `isFirstPage` | `boolean` | Disables reset button when already on page 1 |
-| `startCursor` / `endCursor` | `string \| null` | Relay-style cursors passed back on navigation |
-| `totalCount` / `currentCount` | `number` | Drives the info display text |
-| `onNext` / `onPrevious` / `onReset` | `(cursor) => void` | Navigation callbacks |
-| `compact` | `boolean` | Reduces padding; hides button labels on mobile |
-| `resetButtonIcon` | `'home' \| 'rotate'` | Icon shown on the first-page reset button |
+
+Compact icon-only variant using transparent buttons — accepts a subset of `CursorPaginationProps`.
 
 ## Usage Example
 
 ```typescript
-import { CursorPagination, CursorPaginationSimple } from './cursor-pagination'
-
-// Full pagination bar
+// Full pagination bar with reset
 <CursorPagination
   hasNextPage={pageInfo.hasNextPage}
   hasPreviousPage={pageInfo.hasPreviousPage}
+  isFirstPage={currentPage === 0}
   startCursor={pageInfo.startCursor}
   endCursor={pageInfo.endCursor}
   currentCount={items.length}
-  totalCount={totalCount}
+  totalCount={500}
   itemName="tickets"
   onNext={(cursor) => fetchPage({ after: cursor })}
   onReset={() => fetchPage({})}
   compact
 />
 
-// Icon-only minimal variant
+// Icon-only simple variant
 <CursorPaginationSimple
   hasNextPage={pageInfo.hasNextPage}
-  onNext={() => fetchPage({ after: pageInfo.endCursor })}
-  onReset={() => fetchPage({})}
   isFirstPage={isFirstPage}
+  onNext={() => fetchPage({ after: pageInfo.endCursor })}
+  onReset={resetToFirstPage}
 />
-```
+```
+
+> **Navigation logic:** When `onReset` is provided, it replaces the Previous button with a Home/Reset button that is disabled on the first page. When only `onPrevious` is provided, a standard chevron-left Previous button is rendered instead.
+
+**Source:** [`cursor-pagination.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/cursor-pagination.tsx)

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

@@ -1,48 +1,67 @@
-<!-- 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.
+<!-- source-hash: 1dc21dcb29b7b10e34307413ef6f6f2f -->
+A React component that renders a compact metric/KPI card for dashboards, supporting values, percentage displays, circular progress rings, icons, tooltips, and optional navigation via Next.js Link.
 
 ## Key Components
 
-### `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
+### Exports
 
-### `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).
+- **`DashboardInfoCard`** — Main card component
+- **`DashboardInfoCardProps`** — Full prop interface
+- **`DashboardInfoCardPercentageDisplay`** — Union type controlling percentage render mode: `'auto'` | `'plain'` | `'tag'`
+- **`DashboardInfoCardProgressSize`** — Union type for responsive ring sizing: `number | { base, md?, lg? }`
+
+### Internal Helpers
+
+- **`renderPercentage()`** — Returns a `Tag` or plain text `<p>` based on `percentageDisplay` and `progressVariant`
+- **`renderProgress()`** — Generates responsive `CircularProgress` rings using Tailwind display utilities; stroke width scales proportionally with ring size
 
 ## Usage Example
 
 ```typescript
-// Static metric card
+import { DashboardInfoCard } from './dashboard-info-card'
+
+// Basic metric card
 <DashboardInfoCard
   title="Open Tickets"
   value={142}
-  percentage={72}
+  percentage={78}
   showProgress
   progressVariant="warning"
-  tooltip="Tickets currently unresolved"
+  percentageDisplay="auto"
 />
 
-// Navigable card with overflow progress
+// Navigable card with icon and tooltip
 <DashboardInfoCard
-  title="SLA Breaches"
-  value={18}
-  percentage={110}
-  showProgress
-  progressVariant="error"
-  progressOverflow="wrap"
+  title="SLA Compliance"
+  value="94%"
+  icon={<ShieldIcon />}
   href="/reports/sla"
+  tooltip="Percentage of tickets resolved within SLA"
+  progressVariant="success"
+  percentage={94}
+  showProgress
+  progressSize={{ base: 24, md: 56, lg: 72 }}
 />
 
-// Simple card, no progress
+// Plain percentage with custom value size
 <DashboardInfoCard
-  title="Devices Online"
-  value="1,024"
-  className="col-span-2"
+  title="Revenue"
+  value={24850}
+  subValue="this month"
+  percentage={12}
+  percentageDisplay="plain"
+  progressVariant="success"
+  showProgress
+  valueClassName="text-h2"
 />
-```
+```
+
+## Notes
+
+- When `href` is provided, the card renders as a Next.js `Link` with hover accent styles
+- Responsive ring sizing uses Tailwind `hidden`/`block` utilities; class names must be static strings for JIT scanning
+- Card height is fixed (`h-16` mobile / `h-[104px]` desktop) per Figma spec; `items-center` absorbs overflow from tall title tags
+
+---
+
+**Source:** [`dashboard-info-card.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/dashboard-info-card.tsx)

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

@@ -1,46 +1,62 @@
-<!-- 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.
+<!-- source-hash: fdd0e62dc792d4f4e438f4d6eb3c262f -->
+A polymorphic date picker component supporting both single-date and date-range selection modes, built on `react-day-picker` and `@radix-ui/react-popover` with custom Figma-aligned styling.
 
 ## Key Components
 
 | 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` |
+|---|---|---|
+| `DatePickerProps` | Type | Discriminated union of `SingleDatePickerProps` \| `RangeDatePickerProps` |
+| `DatePickerBaseProps` | Interface | Shared props: `placeholder`, `formatDate`, `disabled`, `fromDate`, `toDate`, `label`, `error`, `invalid`, `numberOfMonths` |
+| `SingleDatePickerProps` | Interface | `mode: "single"`, `value?: Date`, `onChange?: (date) => void` |
+| `RangeDatePickerProps` | Interface | `mode: "range"`, `value?: DateRange`, `onChange?: (range) => void` |
+| `DatePickerCalendar` | Component | Internal calendar renderer; supports `fluid` layout for filter menus |
+| `CalendarNavButton` | Component | Prev/next month navigation using `ChevronLeft`/`ChevronRight` icons |
+| `defaultFormatDate` | Function | Formats a `Date` as `MM/DD/YYYY` |
+| `formatDateRange` | Function | Formats a `DateRange` as `"from - to"` or just `"from"` if no end date |
+
+## Key Behaviors
+
+- **Range hover preview**: Highlights dates between the first selected date and the hovered date before the range is completed.
+- **Fluid mode**: When `fluid={true}`, day cells flex to fill container width (used by `DateFilterMenu`).
+- **Responsive months**: On screens smaller than `md`, always shows 1 month regardless of `numberOfMonths`.
+- **External sync**: `useEffect` keeps internal `draftRange` in sync when `selected` changes externally (e.g., on reset).
 
 ## Usage Example
 
 ```typescript
-// Single date picker
-<DatePicker
-  mode="single"
-  label="Start Date"
-  value={selectedDate}
-  onChange={(date) => setSelectedDate(date)}
-  fromDate={new Date()}
-/>
-
-// Date range picker (dual month)
-<DatePicker
-  mode="range"
-  label="Date Range"
-  numberOfMonths={2}
-  value={range}
-  onChange={(range) => setRange(range)}
-  error={formError}
-  invalid={!!formError}
-/>
-```
+import { DatePicker } from "@openframe-oss-lib/ui";
+import { useState } from "react";
+import type { DateRange } from "react-day-picker";
 
-## Key Behaviors
+// Single mode
+function SingleExample() {
+  const [date, setDate] = useState<Date | undefined>();
+  return (
+    <DatePicker
+      mode="single"
+      value={date}
+      onChange={setDate}
+      label="Select date"
+      placeholder="MM/DD/YYYY"
+      fromDate={new Date()}
+    />
+  );
+}
+
+// Range mode
+function RangeExample() {
+  const [range, setRange] = useState<DateRange | undefined>();
+  return (
+    <DatePicker
+      mode="range"
+      value={range}
+      onChange={setRange}
+      numberOfMonths={2}
+      label="Date range"
+      placeholder="Start – End"
+    />
+  );
+}
+```
 
-- **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
+**Source:** [`date-picker.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/date-picker.tsx)

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

@@ -1,45 +1,48 @@
-<!-- source-hash: e2dcd0d341956fecb4817f070e40d10a -->
-Compact React component for displaying device name and organization in a stacked layout, optimized for use within table cells.
+<!-- source-hash: d1b3b6dcee088ca646f9755a8d278b12 -->
+Compact device card component designed for use in table cells, displaying device name and organization in a stacked vertical layout with graceful empty-state handling.
 
 ## Key Components
 
+### `DeviceCardCompact`
+A lightweight React component that renders device identity information. Returns an empty fragment when both `deviceName` and `organization` are absent, null, `'-'`, or the string `'null'`.
+
 ### `DeviceCardCompactProps`
-Extends `React.HTMLAttributes<HTMLDivElement>` with two optional fields:
+Extends `React.HTMLAttributes<HTMLDivElement>` with:
 
 | 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.
+|---|---|---|
+| `deviceName` | `string \| null` | Primary label shown in `text-ods-text-primary` |
+| `organization` | `string \| null` | Secondary label shown in `text-ods-text-secondary` |
+| `className` | `string` | Merged via `cn()` for custom overrides |
 
 ## Usage Example
 
 ```typescript
-// Basic usage in a table cell
+import { DeviceCardCompact } from '@openframe/ui'
+
+// Renders both rows
 <DeviceCardCompact
   deviceName="DESKTOP-ABC123"
   organization="Acme Corp"
 />
 
-// Handles missing/invalid values gracefully - renders nothing
+// Renders only device name
 <DeviceCardCompact
-  deviceName={null}
+  deviceName="DESKTOP-ABC123"
   organization="-"
 />
 
-// With custom className
+// Returns empty fragment — safe for sparse table data
 <DeviceCardCompact
-  deviceName="SERVER-01"
+  deviceName={null}
   organization={null}
-  className="max-w-[200px]"
 />
 ```
 
-## Behavior Notes
+## Notes
+
+- **Empty-state guard:** Values of `null`, `undefined`, `'-'`, or `'null'` (string) are treated as absent.
+- **Truncation:** Both labels truncate with `truncate` and expose the full value via the `title` attribute on hover.
+- **Layout:** Uses a `flex-col` container with `min-h-[60px]` to maintain consistent row height in tables.
 
-- **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`)
+**Source:** [`flamingo-stack/openframe-oss-lib`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/device-card-compact.tsx)

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

@@ -1,43 +1,52 @@
-<!-- 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.
+<!-- source-hash: 5697c86a68ac84022a2c4a002cebbac9 -->
+A client-side React card component for displaying device information including OS type, status, last-seen timestamp, and configurable action buttons.
 
 ## Key Components
 
 ### 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)
+- **`Device`** — Shape of a device record, including optional `id`, `machineId`, `name`, `type`, `operatingSystem`, `organization`, `status`, `lastSeen`, `tags`, `ipAddress`, `macAddress`, `version`, and `location`.
+- **`ActionButton`** — Configuration for a custom action button: `label`, `onClick`, `variant`, and `visible` flag.
+- **`DeviceCardProps`** — Extends `React.HTMLAttributes<HTMLDivElement>` with `device`, `actions`, `statusTag`, and `onDeviceClick`.
+
+### Component
+
+- **`DeviceCard`** — Renders a bordered card with three rows:
+  1. Device type icon, OS icon, device name/organization, and optional action buttons (more, details, custom).
+  2. Status tag and UTC-formatted last-seen timestamp (hydration-safe via `getUTC*` methods).
+  3. Device tags rendered as outline `Tag` pills.
 
 ## Usage Example
 
 ```typescript
 import { DeviceCard } from './device-card'
 
-<DeviceCard
-  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") },
-    customActions: [
-      { label: "Remote", onClick: () => startRemoteSession(), visible: true }
-    ]
-  }}
-  statusTag={{ variant: "success", label: "Online" }}
-  onDeviceClick={(device) => router.push(`/devices/${device.id}`)}
-/>
+export function Example() {
+  return (
+    <DeviceCard
+      device={{
+        id: 'dev-001',
+        name: 'MacBook Pro',
+        operatingSystem: 'macos',
+        organization: 'Acme Corp',
+        status: 'active',
+        lastSeen: new Date(),
+        tags: ['managed', 'engineering'],
+      }}
+      statusTag={{ variant: 'success', label: 'Active' }}
+      actions={{
+        moreButton: {
+          visible: true,
+          onClick: () => console.log('More clicked'),
+        },
+        customActions: [
+          { label: 'Connect', onClick: () => console.log('Connect'), visible: true },
+        ],
+      }}
+      onDeviceClick={(device) => console.log('Selected:', device.id)}
+    />
+  )
+}
 ```
 
-## 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`
+> **Note:** Last-seen dates are formatted using UTC getters (`getUTCFullYear`, etc.) to prevent React hydration mismatch [#418](https://github.com/flamingo-stack/openframe-oss-lib/issues) between server and client rendering environments.

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

@@ -1,20 +1,20 @@
-<!-- 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.
+<!-- source-hash: bb1d5a46d107bc7118d58cf030a3c64d -->
+Accessible modal dialog component built on Radix UI primitives, providing a composable set of parts for building dialogs with built-in animations, overlay, and keyboard/focus management.
 
 ## Key Components
 
 | 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 |
+| `DialogContent` | Centered modal panel with fade/zoom animations and an auto-rendered close button |
+| `DialogOverlay` | Blurred backdrop rendered behind the content |
 | `DialogPortal` | Renders dialog outside the DOM tree via a portal |
+| `DialogClose` | Button that closes the dialog |
+| `DialogHeader` | Layout wrapper for title/description at the top |
+| `DialogFooter` | Layout wrapper for action buttons at the bottom |
+| `DialogTitle` | Accessible title using `text-h3` styling |
+| `DialogDescription` | Accessible description using muted `text-h6` styling |
 
 ## Usage Example
 
@@ -40,14 +40,14 @@ export function ConfirmDialog() {
         <DialogHeader>
           <DialogTitle>Confirm Action</DialogTitle>
           <DialogDescription>
-            This action cannot be undone. Are you sure?
+            Are you sure you want to proceed? This cannot be undone.
           </DialogDescription>
         </DialogHeader>
         <DialogFooter>
           <DialogClose asChild>
-            <button>Cancel</button>
+            <button variant="outline">Cancel</button>
           </DialogClose>
-          <button onClick={() => console.log("confirmed")}>Confirm</button>
+          <button onClick={handleConfirm}>Confirm</button>
         </DialogFooter>
       </DialogContent>
     </Dialog>
@@ -55,4 +55,4 @@ export function ConfirmDialog() {
 }
 ```
 
-> `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.
+> `DialogContent` automatically renders `DialogOverlay` and a close (`X`) button — no need to add them manually. All components accept a `className` prop for Tailwind customization.

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

@@ -1,35 +1,32 @@
-<!-- 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.
+<!-- source-hash: a18a712084fb48e0dc7a1b864781f7b0 -->
+A full-featured drawer component built on Radix UI's Dialog primitive, providing animated slide-in panels from any viewport edge with support for drag-to-resize, size persistence, flush/floating layout modes, and a unified overlay backdrop.
 
 ## 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 |
+|---|---|---|
+| `Drawer` | Component | Root dialog container (re-export of `DialogPrimitive.Root`) |
+| `DrawerTrigger` | Component | Button/element that opens the drawer |
+| `DrawerClose` | Component | Button/element that closes 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 |
+| `DrawerOverlay` | Component | Dimmed full-screen backdrop (`bg-ods-overlay`) |
+| `DrawerContent` | Component | Main panel with side, flush, and resize props |
+| `DrawerResizeHandle` | Component (internal) | Drag handle with pointer capture and keyboard support |
+| `useResizableSize` | Hook (internal) | Manages clamped size state with `localStorage` persistence |
+| `drawerVariants` | CVA variants | Wrapper positioning by `side` and `flush` |
+| `drawerPanelVariants` | CVA variants | Panel chrome (rounded, border, padding) by `side` and `flush` |
 
-**`DrawerContent` Props:**
+### `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 |
+|---|---|---|---|
+| `side` | `"right" \| "left" \| "top" \| "bottom"` | `"right"` | Slide direction |
+| `flush` | `boolean` | `false` | Full-bleed on mobile; floating card on desktop |
+| `resizable` | `boolean` | `false` | Enables drag-to-resize handle |
+| `minSize` | `number` | — | Minimum panel size in px |
+| `maxSize` | `number` | — | Maximum panel size in px (clamped to viewport) |
+| `defaultSize` | `number` | — | Initial size when no stored value exists |
+| `storageKey` | `string` | — | `localStorage` key for size persistence |
 
 ## Usage Example
 
@@ -37,29 +34,28 @@ A client-side drawer component built on Radix UI's Dialog primitive, providing a
 import {
   Drawer,
   DrawerTrigger,
-  DrawerClose,
   DrawerContent,
-} from "@/components/ui/drawer"
+  DrawerClose,
+} from "@openframe/ui/components/drawer"
 
 // Basic drawer from the right
-function BasicDrawer() {
+export function SettingsDrawer() {
   return (
     <Drawer>
       <DrawerTrigger asChild>
-        <button>Open Panel</button>
+        <button>Open Settings</button>
       </DrawerTrigger>
       <DrawerContent side="right">
-        <p>Drawer content here</p>
-        <DrawerClose asChild>
-          <button>Close</button>
-        </DrawerClose>
+        <DrawerClose />
+        <h2>Settings</h2>
+        <p>Panel content here.</p>
       </DrawerContent>
     </Drawer>
   )
 }
 
-// Resizable flush chat panel persisted across sessions
-function ChatDrawer() {
+// Resizable flush drawer with persisted width
+export function ChatDrawer() {
   return (
     <Drawer>
       <DrawerTrigger asChild>
@@ -72,15 +68,25 @@ function ChatDrawer() {
         minSize={280}
         maxSize={800}
         defaultSize={400}
-        storageKey="chat-panel-width"
-        mobileBreakpoint={768}
-        resizeAriaLabel="Resize chat panel"
+        storageKey="chat-drawer-width"
       >
-        <p>Chat content</p>
+        {/* Consumer owns full internal layout */}
       </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`.
+## Resize Handle Keyboard Shortcuts
+
+| Key | Action |
+|---|---|
+| `ArrowLeft` / `ArrowRight` | Resize by 16px (horizontal panels) |
+| `ArrowUp` / `ArrowDown` | Resize by 16px (vertical panels) |
+| `Shift` + Arrow | Resize by 40px |
+| `Home` | Snap to `minSize` |
+| `End` | Snap to `maxSize` |
+
+## Source
+
+[`drawer.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/drawer.tsx)