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

package/src/components/.pagination.md

@@ -1,44 +1,47 @@
-<!-- source-hash: c4bd5081b24a42378ae712967abb83c2 -->
-Accessible pagination component with smart page number windowing, ellipsis truncation, and both a high-level `Pagination` component and low-level composable primitives.
+<!-- source-hash: ed302fbaa512fab595b516fa57c425ad -->
+Accessible, client-side pagination component that renders page navigation with smart ellipsis logic and a set of composable sub-components for building custom pagination UIs.
 
 ## Key Components
 
 | Export | Type | Description |
-|--------|------|-------------|
-| `Pagination` | Component | All-in-one pagination with built-in windowing logic |
-| `PaginationContent` | Primitive | `<ul>` wrapper for custom pagination layouts |
-| `PaginationItem` | Primitive | `<li>` wrapper for individual page entries |
-| `PaginationLink` | Primitive | Styled `<button>` for page number links |
-| `PaginationEllipsis` | Primitive | `MoreHorizontal` icon span for truncated ranges |
-| `PaginationPrevious` | Primitive | Previous page `<button>` with chevron icon |
-| `PaginationNext` | Primitive | Next page `<button>` with chevron icon |
-
-### `PaginationProps`
-
-| Prop | Type | Description |
-|------|------|-------------|
-| `currentPage` | `number` | Active page (1-based) |
-| `totalPages` | `number` | Total number of pages |
-| `onPageChange` | `(page: number) => void` | Callback fired on page selection |
-| `className` | `string?` | Optional extra classes on the `<nav>` |
-
-**Windowing logic:** shows up to 5 page buttons — always including first and last — with ellipsis (`-1`/`-2` sentinels) filling gaps in between.
+|---|---|---|
+| `Pagination` | Component | Full-featured pagination with built-in page number generation, ellipsis, and prev/next controls |
+| `PaginationContent` | `forwardRef` | Flex container (`<ul>`) for pagination items |
+| `PaginationItem` | `forwardRef` | Wrapper `<li>` for individual pagination elements |
+| `PaginationLink` | `forwardRef` | Styled `<button>` for individual page links |
+| `PaginationEllipsis` | `forwardRef` | `<span>` rendering a `MoreHorizontal` icon with screen-reader text |
+| `PaginationPrevious` | `forwardRef` | Previous-page `<button>` with `ChevronLeft` icon |
+| `PaginationNext` | `forwardRef` | Next-page `<button>` with `ChevronRight` icon |
+
+**Page number algorithm:** Shows up to 5 pages. For larger sets it always renders the first and last page, up to 3 middle pages around the current page, and inserts ellipsis (`-1`/`-2` sentinel values) where gaps exist.
 
 ## Usage Example
 
+**Simple controlled pagination:**
+
 ```typescript
-// High-level component
 import { Pagination } from "@/components/pagination"
 
-<Pagination
-  currentPage={3}
-  totalPages={20}
-  onPageChange={(page) => setCurrentPage(page)}
-/>
+export function MyList() {
+  const [page, setPage] = React.useState(1)
+
+  return (
+    <>
+      <ItemList page={page} />
+      <Pagination
+        currentPage={page}
+        totalPages={20}
+        onPageChange={setPage}
+        className="mt-4"
+      />
+    </>
+  )
+}
 ```
 
+**Composable low-level API:**
+
 ```typescript
-// Composable primitives for custom layouts
 import {
   PaginationContent,
   PaginationItem,
@@ -48,14 +51,16 @@ import {
   PaginationEllipsis,
 } from "@/components/pagination"
 
-<nav>
-  <PaginationContent>
-    <PaginationItem><PaginationPrevious onClick={() => setPage(p => p - 1)} /></PaginationItem>
-    <PaginationItem><PaginationLink onClick={() => setPage(1)}>1</PaginationLink></PaginationItem>
-    <PaginationItem><PaginationEllipsis /></PaginationItem>
-    <PaginationItem><PaginationNext onClick={() => setPage(p => p + 1)} /></PaginationItem>
-  </PaginationContent>
-</nav>
-```
-
-> All interactive elements include `aria-label` and `aria-current="page"` attributes, and screen-reader-only text via `sr-only` spans for full accessibility compliance.
+export function CustomPagination() {
+  return (
+    <nav aria-label="pagination">
+      <PaginationContent>
+        <PaginationItem><PaginationPrevious onClick={() => {}} /></PaginationItem>
+        <PaginationItem><PaginationLink>1</PaginationLink></PaginationItem>
+        <PaginationItem><PaginationEllipsis /></PaginationItem>
+        <PaginationItem><PaginationNext onClick={() => {}} /></PaginationItem>
+      </PaginationContent>
+    </nav>
+  )
+}
+```

package/src/components/.persistent-filter-controls.md

@@ -1,41 +1,74 @@
-<!-- source-hash: cad1f4c0a58d88fec0b4fd7dcdd7628a -->
-A React component library that provides persistent, accessible filter controls with loading state management and visual feedback for improved user experience during data fetching.
+<!-- source-hash: cfbf70162648ccd3e632dabc1ca9e692 -->
+Wrapper components that keep filter controls visible but visually disabled during loading states, with smooth transitions and full accessibility support.
 
 ## Key Components
 
-- **`PersistentFilterControls`** - Main wrapper component that manages loading states with visual feedback
-- **`PersistentSearchContainer`** - Enhanced search wrapper that keeps search interactive during loading
-- **`PersistentSidebar`** - Desktop sidebar wrapper with sticky positioning
-- **`PersistentMobileDropdown`** - Mobile-specific dropdown wrapper with responsive visibility
+| Export | Description |
+|---|---|
+| `PersistentFilterControls` | Base wrapper; handles opacity, pointer-events, ARIA attributes, and a spinning loader indicator |
+| `PersistentSearchContainer` | Wraps search inputs; keeps interaction enabled (`preventInteraction=false`) during loading |
+| `PersistentSidebar` | Wraps desktop sidebar filters; sticky-positioned, `0.5` disabled opacity |
+| `PersistentMobileDropdown` | Wraps mobile dropdown filters; hidden on `lg+`, `0.7` disabled opacity |
+
+## Props — `PersistentFilterControls`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `isLoading` | `boolean` | — | Triggers the disabled visual state |
+| `children` | `ReactNode` | — | Filter control components to wrap |
+| `className` | `string` | — | Additional Tailwind/CSS classes |
+| `disabledOpacity` | `number` | `0.6` | Opacity when loading (0–1) |
+| `transitionDuration` | `number` | `300` | Transition duration in milliseconds |
+| `preventInteraction` | `boolean` | `true` | Applies `pointer-events-none` during loading |
 
 ## Usage Example
 
 ```typescript
-// Basic filter controls with loading state
-<PersistentFilterControls isLoading={isLoadingData}>
-  <SearchInput />
-  <CategoryFilters />
-  <SortControls />
-</PersistentFilterControls>
+import {
+  PersistentFilterControls,
+  PersistentSearchContainer,
+  PersistentSidebar,
+  PersistentMobileDropdown,
+} from "./persistent-filter-controls"
+
+// Granular per-control usage
+function FilterLayout({ isLoading }: { isLoading: boolean }) {
+  return (
+    <>
+      {/* Search stays interactive during loading */}
+      <PersistentSearchContainer isLoading={isLoading}>
+        <SearchInput />
+      </PersistentSearchContainer>
 
-// Search container that stays interactive during loading
-<PersistentSearchContainer isLoading={isLoading}>
-  <SearchInput placeholder="Search vendors..." />
-</PersistentSearchContainer>
+      {/* Sidebar fully disabled at 50% opacity */}
+      <PersistentSidebar isLoading={isLoading}>
+        <CategoryFilterSidebar />
+      </PersistentSidebar>
 
-// Responsive sidebar with custom styling
-<PersistentSidebar 
+      {/* Mobile dropdown, hidden on desktop */}
+      <PersistentMobileDropdown isLoading={isLoading}>
+        <MobileFilterDropdown />
+      </PersistentMobileDropdown>
+    </>
+  )
+}
+
+// Or use the base component with custom settings
+<PersistentFilterControls
   isLoading={isLoading}
-  className="w-64 space-y-4"
+  disabledOpacity={0.4}
+  transitionDuration={200}
+  preventInteraction
 >
-  <CategoryFilter />
-  <PriceRangeFilter />
-</PersistentSidebar>
-
-// Mobile dropdown with automatic responsive hiding
-<PersistentMobileDropdown isLoading={isLoading}>
-  <FilterDropdown />
-</PersistentMobileDropdown>
+  <CustomFilterPanel />
+</PersistentFilterControls>
 ```
 
-The components provide accessibility features including ARIA attributes, screen reader announcements, and keyboard navigation preservation during loading states. They use customizable opacity transitions and pointer event management to create smooth user experiences.
+## Accessibility
+
+- `role="region"` with `aria-label="Filter controls"` and `aria-busy` on the outer wrapper
+- `role="status"` with `aria-live="polite"` on a visually hidden (`sr-only`) element announces loading to screen readers
+- A visible spinning indicator (`animate-spin`) is rendered at `top-2 right-2` during loading
+- Keyboard navigation and screen reader access are preserved even when `pointer-events-none` is applied
+
+**Source:** [`persistent-filter-controls.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/persistent-filter-controls.tsx)

package/src/components/.pricing-display.md

@@ -1,50 +1,51 @@
-<!-- source-hash: 00831f49d3f69f4283d8a0c7a7a3bfd4 -->
-A React component for displaying pricing information with flexible styling configurations and support for both structured and legacy string pricing formats.
+<!-- source-hash: e8ca3b7bdcdb12ce459c31a0b64a34bd -->
+Renders pricing data consistently across comparison tables, vendor cards, and dropdowns, supporting both structured `StructuredPricingItem` arrays and legacy string formats.
 
 ## Key Components
 
-### Main Exports
-- **`PricingDisplay`** - Main component for rendering pricing with configurable styles
-- **`PRICING_STYLES`** - Predefined style configurations (comparison, compact, card)
-- **`formatPricingForDisplay`** - Utility function for preprocessing pricing strings
+### Exports
 
-### Internal Functions
-- **`formatPriceValue`** - Formats price values with optional tilde prefix
-- **`LegacyPricingDisplay`** - Backward compatibility component for string inputs
-- **`parsePricing`** - String parser for extracting price and unit information
+- **`PricingDisplay`** — Primary component that renders pricing with configurable styling. Accepts structured pricing data (single item, array, or legacy string) and a `styleConfig`.
+- **`PRICING_STYLES`** — Predefined style config constants for three layout contexts:
+  - `comparison` — Default; no tilde prefix, primary text color
+  - `compact` — Vendor dropdowns; shows tilde prefix (`~$`), secondary text color
+  - `card` — Vendor cards; shows tilde prefix, mixed primary/secondary colors
+- **`formatPricingForDisplay`** — Pass-through utility for pre-processing pricing strings (currently identity function).
 
-### Types
-- **`PricingStyleConfig`** - Configuration interface for text sizes, colors, and display options
-- **`PricingDisplayProps`** - Component props supporting structured or string pricing data
+### Internal
+
+- **`LegacyPricingDisplay`** — Handles backward-compatible string input, parsing comma-separated, pipe-separated, multi-cycle (`/$`), and single-price formats.
+- **`formatPriceValue`** — Normalizes `number | 'Free' | 'Contact'` to a display string, optionally prefixed with `~`.
+
+### Interfaces
+
+| Interface | Purpose |
+|---|---|
+| `PricingStyleConfig` | Font size, color, tilde prefix, and font-family tokens |
+| `PricingDisplayProps` | Component props; `pricing` accepts array, single item, or string |
 
 ## Usage Example
 
 ```typescript
 import { PricingDisplay, PRICING_STYLES } from './pricing-display'
 
-// With structured pricing data
-const structuredPricing = [{
-  ranges: [{ min: 25, unit: 'user/month' }]
-}]
+// Structured pricing (preferred)
+<PricingDisplay
+  pricing={[{ ranges: [{ min: 29, unit: 'device/month' }] }]}
+  styleConfig={PRICING_STYLES.card}
+/>
 
-// Basic usage with default styling
-<PricingDisplay pricing={structuredPricing} />
+// Legacy string input (backward compatible)
+<PricingDisplay
+  pricing="$29/device/month, $299/device/year"
+  styleConfig={PRICING_STYLES.comparison}
+/>
 
-// With custom compact styling
-<PricingDisplay 
-  pricing={structuredPricing}
+// Compact dropdown style with tilde prefix → renders "~$29/device/month"
+<PricingDisplay
+  pricing={structuredItem}
   styleConfig={PRICING_STYLES.compact}
-  className="my-2"
 />
-
-// Legacy string support
-<PricingDisplay pricing="$25/user/month" />
-
-// Multiple pricing tiers
-<PricingDisplay pricing={[
-  { ranges: [{ min: 10, unit: 'device/month' }] },
-  { ranges: [{ min: 120, unit: 'device/year' }] }
-]} />
 ```
 
-The component automatically handles various pricing formats including free tiers, contact-based pricing, and multi-tier structures while maintaining consistent visual presentation across different UI contexts.
+**Source:** [`pricing-display.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/pricing-display.tsx)

package/src/components/.results-count.md

@@ -1,42 +1,55 @@
-<!-- source-hash: 4a24692b0150d343e629a74a58baaa40 -->
-A React component that displays pagination information showing the current range of results and total count for search/listing interfaces.
+<!-- source-hash: 6cbebdb8e5cb24d3a740b0dfd374352c -->
+A client-side React component that displays paginated result counts with optional sorting context for vendor or post listings.
 
 ## Key Components
 
-- **`ResultsCountProps`** - Interface defining component props including pagination state and result type
-- **`ResultsCount`** - Main component that renders the results count display with optional sorting message
+**`ResultsCountProps`** — Interface defining component inputs:
 
-### Props
+| Prop | Type | Description |
+|---|---|---|
+| `currentPage` | `number` | Active page number (1-based) |
+| `pageSize` | `number` | Number of results per page |
+| `totalResults` | `number` | Total count across all pages |
+| `resultType` | `'vendors' \| 'posts'` | Controls singular/plural label |
+| `sortingMessage` | `string` (optional) | Accent-colored sort context appended to count |
 
-- `currentPage`: Current page number (1-based)
-- `pageSize`: Number of items per page
-- `totalResults`: Total number of available results
-- `resultType`: Type of content being displayed ('vendors' or 'posts')
-- `sortingMessage`: Optional message about current sorting method
+**`ResultsCount`** — Functional component that computes the visible result range and renders a summary string. Returns `null` when `totalResults` is `0`.
 
 ## Usage Example
 
 ```typescript
-import { ResultsCount } from './results-count'
-
-// Basic usage for vendor listings
+// Basic pagination count
 <ResultsCount
   currentPage={2}
   pageSize={20}
-  totalResults={156}
+  totalResults={85}
   resultType="vendors"
 />
-// Output: "Showing 21-40 of 156 vendors"
+// → "Showing 21-40 of 85 vendors"
 
-// With sorting message
+// With sorting context
 <ResultsCount
   currentPage={1}
   pageSize={10}
-  totalResults={45}
+  totalResults={1}
   resultType="posts"
-  sortingMessage="sorted by date"
+  sortingMessage="sorted by relevance"
+/>
+// → "Showing 1-1 of 1 post • sorted by relevance"
+
+// Returns null — renders nothing
+<ResultsCount
+  currentPage={1}
+  pageSize={10}
+  totalResults={0}
+  resultType="vendors"
 />
-// Output: "Showing 1-10 of 45 posts • sorted by date"
 ```
 
-The component automatically handles singular/plural forms, calculates the correct result range for the current page, and returns `null` when there are no results to display.
+## Notes
+
+- Range is computed as `startIndex = (currentPage - 1) * pageSize + 1` and `endIndex = Math.min(currentPage * pageSize, totalResults)`, preventing out-of-bounds display on the last page.
+- Automatically handles singular/plural labeling (`vendor` vs `vendors`, `post` vs `posts`).
+- `sortingMessage` renders in accent color (`text-ods-accent`) prefixed with a bullet separator.
+
+**Source:** [`results-count.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/results-count.tsx)

package/src/components/.smooth-accordion.md

@@ -1,14 +1,25 @@
-<!-- source-hash: 8e2d34f99735f6301a4abd6dd93c8c3e -->
-A custom accordion component built on Radix UI primitives that provides ultra-smooth open/close animations using dynamic height measurement via `ResizeObserver`, replacing CSS variable-based transitions with pixel-precise `max-height` animation.
+<!-- source-hash: 2029770a635d305e72ad9b7c24b00f02 -->
+A set of animated accordion components built on top of `@radix-ui/react-accordion`, providing smooth height and opacity transitions using `ResizeObserver` for dynamic content measurement.
 
 ## Key Components
 
 | Export | Type | Description |
-|--------|------|-------------|
-| `SmoothAccordion` | Component | Re-export of `AccordionPrimitive.Root` — the accordion container |
-| `SmoothAccordionItem` | `forwardRef` Component | Accordion item wrapper with border removed (`border-0`) |
-| `SmoothAccordionTrigger` | `forwardRef` Component | Clickable header with label text and an animated `ChevronButton` |
-| `SmoothAccordionContent` | `forwardRef` Component | Animated content panel using `ResizeObserver` for height tracking |
+|---|---|---|
+| `SmoothAccordion` | Component | Re-export of `AccordionPrimitive.Root` for convenience |
+| `SmoothAccordionItem` | `forwardRef` Component | Wrapper around `AccordionPrimitive.Item` with border reset |
+| `SmoothAccordionTrigger` | `forwardRef` Component | Trigger header with label text and animated `ChevronButton` |
+| `SmoothAccordionContent` | `forwardRef` Component | Content panel with `ResizeObserver`-driven smooth animation |
+
+### `SmoothAccordionTrigger` Props
+
+| Prop | Type | Description |
+|---|---|---|
+| `label` | `React.ReactNode` | Content rendered as the accordion header |
+| `className` | `string?` | Additional CSS classes |
+
+### `SmoothAccordionContent` Animation
+
+Uses `ResizeObserver` to measure `scrollHeight` dynamically, animating `max-height` and `opacity` over `0.35s`. Height resets to `0px` after the close transition ends to avoid residual spacing.
 
 ## Usage Example
 
@@ -24,18 +35,16 @@ export function FAQ() {
   return (
     <SmoothAccordion type="single" collapsible>
       <SmoothAccordionItem value="item-1">
-        <SmoothAccordionTrigger label="What is Flamingo?" />
+        <SmoothAccordionTrigger label="What is OpenFrame?" />
         <SmoothAccordionContent>
-          Flamingo is an AI-powered MSP platform that replaces expensive
-          proprietary software with open-source alternatives.
+          OpenFrame is a unified AI-driven MSP platform.
         </SmoothAccordionContent>
       </SmoothAccordionItem>
 
       <SmoothAccordionItem value="item-2">
-        <SmoothAccordionTrigger label="What is OpenFrame?" />
+        <SmoothAccordionTrigger label="How does Mingo AI work?" />
         <SmoothAccordionContent>
-          OpenFrame is the unified platform integrating multiple MSP tools
-          into a single AI-driven interface.
+          Mingo AI automates IT support operations across the stack.
         </SmoothAccordionContent>
       </SmoothAccordionItem>
     </SmoothAccordion>
@@ -43,11 +52,6 @@ export function FAQ() {
 }
 ```
 
-## Animation Details
-
-`SmoothAccordionContent` avoids Radix's default CSS variable approach by:
+> **Note:** The `data-state` prop injected by Radix UI controls open/closed animation state. No additional state management is required by the consumer.
 
-1. **Measuring** actual content height via `scrollHeight` on mount and child changes
-2. **Observing** dynamic content resize with a `ResizeObserver`
-3. **Animating** `max-height` and `opacity` over `0.35s ease-in-out`
-4. **Resetting** `maxHeight` to `0` after the close transition ends to prevent residual spacing
+**Source:** [`smooth-accordion.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/smooth-accordion.tsx)

package/src/components/.social-icon-row.md

@@ -1,43 +1,55 @@
-<!-- source-hash: 5ee2a1885dc45a65b8396aea3f9f9f10 -->
-A client-side React component that renders a horizontal row of social media icon buttons with configurable links and styling variants.
+<!-- source-hash: 61507385ae20de6e7a2be68effe9807c -->
+A client-side React component that renders a horizontal row of social media icon buttons, supporting both link-based navigation and action callbacks with optional compact and grouped layouts.
 
 ## Key Components
 
-### Interfaces
-- **`SocialLink`** — Defines a social link entry with `platform` (string key), `href` (URL), and optional `label` (for accessibility)
-- **`SocialIconRowProps`** — Component props accepting `className`, `links` array, and a `variant` for button styling
+### Types
+
+- **`SocialLink`** — Discriminated union type ensuring each entry has either an `href` (anchor) or `onClick` (action callback), never both or neither. Supports `visibility` (`"external"` | `"internal"`) for grouping.
+- **`SocialIconRowProps`** — Component props including `links`, `variant`, `compact`, and `groupByVisibility`.
 
 ### Functions
-- **`renderSocialIcon(platform)`** — Maps a platform string to its corresponding icon component. Supports: `github`, `twitter`/`x`, `reddit`, `linkedin`, `luma`, `whatsapp`, `website`/`web`/`url`, `slack`, `discord`, `telegram`, `youtube`/`yt`, `instagram`/`ig`, `facebook`/`fb`. Falls back to `GlobeIcon` for unknown platforms.
-- **`SocialIconRow`** — Main exported component rendering a flex row of icon buttons, each wrapped in an accessible anchor tag.
 
-### Defaults
-- `defaultLinks` — Pre-configured links for GitHub, LinkedIn, and Facebook (Flamingo's primary social channels)
-- `variant` defaults to `'outline'`
+- **`renderSocialIcon(platform)`** — Maps a platform string (case-insensitive) to the corresponding icon component. Falls back to `GlobeIcon` for unknown platforms. Supported platforms: `github`, `twitter`/`x`, `reddit`, `linkedin`, `luma`, `whatsapp`, `email`/`mail`, `website`/`web`/`url`, `slack`, `discord`, `telegram`, `youtube`/`yt`, `instagram`/`ig`, `facebook`/`fb`, `copy`.
+- **`SocialIconRow`** — Main exported component.
+
+### Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `links` | `SocialLink[]` | GitHub, LinkedIn, Facebook | Array of social link definitions |
+| `variant` | `"accent"` \| `"outline"` \| `"transparent"` \| `"destructive"` | `"outline"` / `"transparent"` | Button variant; defaults to `"transparent"` in compact mode |
+| `compact` | `boolean` | `false` | 32px ghost icon buttons with tight `gap-2` for metadata/identity rows |
+| `groupByVisibility` | `boolean` | `false` | Splits external and internal links with a divider when both groups are present |
 
 ## Usage Example
 
 ```typescript
-// Default Flamingo social links
+import { SocialIconRow } from './social-icon-row';
+
+// Default full-width card row
 <SocialIconRow />
 
-// Custom links with accent variant
+// Compact author header row with custom links
 <SocialIconRow
-  variant="accent"
+  compact
   links={[
-    { platform: 'github', href: 'https://github.com/your-org', label: 'GitHub' },
-    { platform: 'slack', href: 'https://join.slack.com/...', label: 'Slack' },
-    { platform: 'youtube', href: 'https://youtube.com/@flamingo', label: 'YouTube' },
+    { platform: 'github', href: 'https://github.com/flamingo-stack/openframe-oss-lib', label: 'GitHub' },
+    { platform: 'twitter', href: 'https://x.com/flamingo_run', label: 'X' },
+    {
+      platform: 'copy',
+      label: 'Copy link',
+      onClick: () => navigator.clipboard.writeText(window.location.href),
+    },
   ]}
-  className="mt-4"
 />
 
-// Transparent variant for dark backgrounds
+// Grouped: external links / divider / internal-only links
 <SocialIconRow
-  variant="transparent"
+  groupByVisibility
   links={[
-    { platform: 'linkedin', href: 'https://linkedin.com/company/flamingo.run' },
-    { platform: 'twitter', href: 'https://x.com/flamingo' },
+    { platform: 'linkedin', href: 'https://linkedin.com/company/flamingo.run', visibility: 'external' },
+    { platform: 'slack', href: 'https://join.slack.com/...', visibility: 'internal' },
   ]}
 />
 ```

package/src/components/.sonner.md

@@ -1,41 +1,56 @@
-<!-- source-hash: 29dab1e4f92b76196533161ae17454c9 -->
-A React component that wraps the Sonner toast notification library with custom styling and dark theme configuration for consistent toast messages across the application.
+<!-- source-hash: ffdc48f7d697e19cf2af3c404ef4db8b -->
+A pre-configured wrapper around the [Sonner](https://sonner.emilkowal.ski/) toast library, styled with OpenFrame Design System (`ods-*`) tokens and fixed to dark theme, bottom-right position.
 
 ## Key Components
 
-- **`Toaster`** - Main toast notification component with pre-configured styling and positioning
-- **`ToasterProps`** - Type definition extending Sonner's component props for type safety
+- **`Toaster`** — Drop-in toast container component. Accepts all native `Sonner` props via spread, with ODS-themed defaults pre-applied.
+
+## ODS Token Mapping
+
+| Toast Part | Tokens Applied |
+|---|---|
+| Base toast | `ods-card`, `ods-text-primary`, `ods-border` |
+| Description | `ods-text-secondary` |
+| Action button | `ods-accent`, `ods-text-on-accent` |
+| Cancel button | `ods-bg-surface`, `ods-text-secondary` |
+| Error variant | `ods-error-secondary`, `ods-error` border |
+| Success variant | `ods-success-secondary`, `ods-success` border |
 
 ## Usage Example
 
+Mount once at the app root (e.g. layout), then trigger toasts anywhere:
+
 ```typescript
-import { Toaster } from './sonner'
-import { toast } from 'sonner'
+// app/layout.tsx
+import { Toaster } from "@/components/ui/sonner"
 
-// Add the Toaster component to your app root
-function App() {
+export default function RootLayout({ children }) {
   return (
-    <div>
-      {/* Your app content */}
-      <Toaster />
-    </div>
+    <html>
+      <body>
+        {children}
+        <Toaster />
+      </body>
+    </html>
   )
 }
+```
 
-// Trigger toast notifications anywhere in your app
-function handleSuccess() {
-  toast.success("Operation completed successfully!")
-}
+```typescript
+// anywhere in the app
+import { toast } from "sonner"
 
-function handleError() {
-  toast.error("Something went wrong!")
-}
+toast.success("Device synced successfully.")
+toast.error("Failed to connect to endpoint.")
+toast("Ticket #1042 updated.", { description: "Priority changed to High." })
+```
 
-function handleInfo() {
-  toast("Info message", {
-    description: "Additional details here"
-  })
-}
+Override defaults by passing props directly to `<Toaster>`:
+
+```typescript
+<Toaster position="top-center" duration={3000} />
 ```
 
-The component is pre-styled with ODS (design system) color tokens and positioned at the bottom-right of the screen. It includes custom styling for different toast types (success, error, info) and interactive elements like action and cancel buttons. The dark theme and custom CSS classes ensure consistent appearance with the application's design system.
+## Source
+
+[`sonner.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/sonner.tsx)