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

package/src/components/ui/.ticket-status-tag.md

@@ -1,49 +1,53 @@
-<!-- source-hash: 5f8fd0a180217b9085f7ea5f038d319a -->
-Renders a styled badge for ticket statuses, normalizing any known status string (backend, chat, dialog-layer) into a canonical `TicketStatus` value with the correct color variant and optional icon.
+<!-- source-hash: 4625c3e196ab2432605ea8116cf40c08 -->
+Renders a styled ticket status badge that maps any status string variant (backend enum, chat lowercase, dialog alias) to a canonical display with correct color, label, and icon.
 
 ## Key Components
 
 ### Types & Exports
-| Export | Description |
-|--------|-------------|
-| `TicketStatus` | Canonical union type: `'ACTIVE' \| 'TECH_REQUIRED' \| 'ON_HOLD' \| 'RESOLVED' \| 'ARCHIVED'` |
-| `TicketStatusTagProps` | Props interface for the main component |
+- **`TicketStatus`** — Union type of canonical status values: `ACTIVE | AI_ASSISTANCE | TECH_REQUIRED | ON_HOLD | RESOLVED | ARCHIVED`
+- **`TicketStatusKind`** — Backend kind enum including `CUSTOM`
+- **`TicketStatusInput`** — Shape for raw ticket status fields from the backend (status, statusKind, statusName, statusColor)
+- **`TicketStatusTagProps`** — Full props interface for the tag component
 
 ### Utility Functions
-| Function | Description |
-|----------|-------------|
-| `resolveTicketStatus(status)` | Maps any known alias to a canonical `TicketStatus`; returns `null` for unknowns |
-| `getTicketStatusConfig(status)` | Returns `{ label, variant, icon }` for a given status string |
-| `getTicketStatusTag(status)` | Drop-in utility returning label/variant/icon for use outside the component |
+- **`resolveTicketStatus(status)`** — Normalizes any alias (e.g. `ACTION_REQUIRED`, `open`, `active`) to a canonical `TicketStatus` or `null`
+- **`getTicketStatusConfig(status)`** — Returns label, variant, and optional icon for any status string
+- **`getTicketStatusTag(status)`** — Drop-in replacement for legacy `getTicketStatusTag` utility
+- **`kindToCanonicalStatus(kind)`** — Maps a backend kind to its canonical status
+- **`usesCanonicalStatusStyle(kind)`** — Returns `true` for kinds that use system styling over backend color
+- **`resolveStatusTagProps(input)`** — Resolves a `TicketStatusInput` into `TicketStatusTag` props
 
 ### Component
-- **`TicketStatusTag`** — Wraps the base `Tag` component with resolved status config. Supports label override, hex `color` override with automatic contrast text, `showIcon` toggle, and additional `className`.
+- **`TicketStatusTag`** — Renders a `Tag` with optional icon, custom hex color with derived hover/active states, and an optional inline dropdown (via `ActionsMenuDropdown`) for in-place status changes
 
 ## Usage Example
 
 ```typescript
-// Basic usage
-<TicketStatusTag status="ACTIVE" />
-
-// With alias from dialog layer
-<TicketStatusTag status="ACTION_REQUIRED" />
-
-// HubSpot pipeline stage — custom label, canonical color
-<TicketStatusTag status="OPEN" label="Waiting on Contact" />
-
-// Hex color override (e.g. from a custom pipeline stage)
-<TicketStatusTag status="ON_HOLD" color="#7C3AED" />
-
-// Utility usage outside JSX
-const { label, variant } = getTicketStatusTag('resolved')
-// → { label: 'Resolved', variant: 'outline', icon: <CheckCircleIcon /> }
+// Basic display
+<TicketStatusTag status="RESOLVED" />
+
+// With custom backend color and label override
+<TicketStatusTag
+  status="TECH_REQUIRED"
+  label="Waiting on Client"
+  color="#F59E0B"
+/>
+
+// Inline status changer with dropdown
+<TicketStatusTag
+  status={ticket.status}
+  options={statusOptions}
+  onSelect={(id) => updateStatus(ticket.id, id)}
+  isPending={isUpdating}
+/>
+
+// Resolve from raw backend fields
+const props = resolveStatusTagProps({
+  statusKind: 'CUSTOM',
+  statusName: 'Escalated',
+  statusColor: '#DC2626',
+})
+<TicketStatusTag {...props} />
 ```
 
-### Status → Variant Map
-| Status | Variant | Icon |
-|--------|---------|------|
-| `ACTIVE` | `success` | — |
-| `TECH_REQUIRED` | `warning` | — |
-| `ON_HOLD` | `error` | — |
-| `RESOLVED` | `outline` | ✅ CheckCircle |
-| `ARCHIVED` | `grey` | — |
+**Source:** [`ticket-status-tag.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/ticket-status-tag.tsx)

package/src/components/ui/.toaster.md

@@ -1,20 +1,22 @@
-<!-- source-hash: 1847d3dd263a7c340149cc9157774ef5 -->
+<!-- source-hash: 698030c9d57a6d286851413d58aa0855 -->
 A client-side toast notification system built on top of [Sonner](https://sonner.emilkowal.ski/), providing styled toast components with variant support, progress indicators, and a specialized command approval flow.
 
 ## Key Components
 
 | Export | Type | Description |
 |--------|------|-------------|
-| `Toaster` | Component | Root provider wrapping Sonner's `Toaster`; injects the `toast-progress` keyframe animation |
+| `Toaster` | Component | Root provider component; wraps `SonnerToaster` with unstyled defaults and injects the `toast-progress` keyframe animation |
 | `ToastCard` | Component | Standard toast card with title, description, colored dot indicator, dismiss button, and animated progress bar |
-| `CommandApprovalToast` | Component | Expandable toast with Approve/Reject actions for AI command authorization flows |
-| `showToast` | Function | Imperative helper to fire a `ToastCard` toast |
+| `CommandApprovalToast` | Component | Expandable toast for AI/tool command approvals with approve/reject actions and optional `ToolIcon` |
+| `showToast` | Function | Imperative helper to fire a `ToastCard`; accepts a plain string or `ShowToastOptions` |
 | `showCommandApprovalToast` | Function | Imperative helper to fire a `CommandApprovalToast` |
 | `ToastVariant` | Type | `'default' \| 'success' \| 'warning' \| 'error' \| 'info'` |
+| `dotColorByVariant` | Constant | Maps each variant to an ODS background color class for the status dot |
+| `progressColorByVariant` | Constant | Maps each variant to an ODS background color class for the progress bar |
 
 ## Usage Example
 
-**Mount the provider once (root layout):**
+**Mount the provider once at the app root:**
 
 ```typescript
 import { Toaster } from '@/components/toaster'
@@ -34,24 +36,28 @@ export default function RootLayout({ children }) {
 ```typescript
 import { showToast } from '@/components/toaster'
 
-showToast({ title: 'Saved', description: 'Changes saved successfully.', variant: 'success' })
+// Simple string shorthand
+showToast('Settings saved')
 
-// Shorthand
-showToast('Operation complete')
+// With variant and description
+showToast({
+  title: 'Connection failed',
+  description: 'Could not reach the server.',
+  variant: 'error',
+  duration: 6000,
+})
 ```
 
-**Request command approval (Mingo AI flow):**
+**Request command approval from the AI agent flow:**
 
 ```typescript
 import { showCommandApprovalToast } from '@/components/toaster'
 
 showCommandApprovalToast({
-  command: 'apt-get upgrade -y',
+  command: 'rm -rf /var/log/old-logs',
   toolType: 'terminal',
-  approvalDescription: 'This will upgrade all system packages.',
+  approvalDescription: 'This will permanently delete log files.',
   onApprove: () => executeCommand(),
-  onReject: () => cancelJob(),
+  onReject: () => console.log('Rejected'),
 })
-```
-
-> `CommandApprovalToast` defaults to `duration: Infinity` so it persists until the technician explicitly approves or rejects the action.
+```

package/src/components/ui/.toggle.md

@@ -1,46 +1,47 @@
-<!-- source-hash: 1c76fc16642481ec29f5f1f42b31eb23 -->
-A customizable toggle button component built on Radix UI primitives with variant-based styling and accessibility features.
+<!-- source-hash: 4d4ada9c1e880bd6f3eb0ca0077d3b94 -->
+A client-side toggle button component built on Radix UI's `TogglePrimitive`, styled with `class-variance-authority` and OpenFrame design system tokens.
 
 ## Key Components
 
-- **`Toggle`** - Main toggle component with forwarded refs and customizable variants
-- **`toggleVariants`** - CVA-based style variants for different visual states and sizes
-- **Variant Types:**
-  - `variant`: `"default"` | `"outline"` 
-  - `size`: `"default"` | `"sm"` | `"lg"`
+- **`toggleVariants`** — CVA variant config defining styles for `variant` (`default`, `outline`) and `size` (`default`, `sm`, `lg`) combinations, using ODS design tokens (`ods-accent`, `ods-border`, `ods-focus`, etc.)
+- **`Toggle`** — A forwarded-ref React component wrapping `TogglePrimitive.Root` with variant-aware class merging via `cn`
 
 ## Usage Example
 
 ```typescript
-import { Toggle } from "./toggle"
-
-function ToggleExample() {
-  const [pressed, setPressed] = React.useState(false)
-  
-  return (
-    <div className="flex gap-4">
-      {/* Basic toggle */}
-      <Toggle pressed={pressed} onPressedChange={setPressed}>
-        Toggle me
-      </Toggle>
-      
-      {/* Outline variant, small size */}
-      <Toggle variant="outline" size="sm">
-        Small outline
-      </Toggle>
-      
-      {/* Large toggle with custom styling */}
-      <Toggle 
-        size="lg" 
-        className="bg-blue-500 text-white"
-        pressed={pressed}
-        onPressedChange={setPressed}
-      >
-        Custom toggle
-      </Toggle>
-    </div>
-  )
-}
+import { Toggle } from "@/components/ui/toggle"
+import { Bold } from "lucide-react"
+
+// Default toggle
+<Toggle aria-label="Toggle bold">
+  <Bold className="h-4 w-4" />
+</Toggle>
+
+// Outline variant, small size
+<Toggle variant="outline" size="sm" aria-label="Toggle italic">
+  Italic
+</Toggle>
+
+// Controlled toggle with pressed state
+<Toggle
+  pressed={isActive}
+  onPressedChange={setIsActive}
+  variant="outline"
+>
+  Active
+</Toggle>
 ```
 
-The component uses ODS (Open Design System) color tokens for consistent theming and includes hover states, focus management, and proper ARIA attributes through Radix UI.
+## Variants
+
+| Prop | Options | Default |
+|---|---|---|
+| `variant` | `default`, `outline` | `default` |
+| `size` | `default`, `sm`, `lg` | `default` |
+
+## Notes
+
+- Marked `"use client"` — compatible with Next.js App Router
+- Inherits all Radix `TogglePrimitive.Root` props (including `pressed`, `onPressedChange`, `defaultPressed`)
+- Active state styling (`data-[state=on]`) uses `ods-accent` background automatically
+- Source: [`components/ui/toggle.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/components/ui/toggle.tsx)

package/src/components/ui/.tooltip.md

@@ -1,14 +1,14 @@
-<!-- source-hash: 7a9da2d80c73e939b410ce27e719aa66 -->
-Accessible tooltip component built on Radix UI primitives, providing animated, portal-rendered tooltips with consistent ODS (OpenFrame Design System) styling.
+<!-- source-hash: ad1dda63b330dd9dfa95d0d9610631e5 -->
+Accessible tooltip component built on Radix UI primitives, with portal-aware rendering that inherits the active stacking context (e.g. inside drawers) and falls back to `document.body`.
 
 ## Key Components
 
 | Export | Type | Description |
-|--------|------|-------------|
-| `TooltipProvider` | Component | Context provider required at the app/layout level to manage tooltip state |
-| `Tooltip` | Component | Root wrapper controlling open/close behavior |
-| `TooltipTrigger` | Component | Element that activates the tooltip on hover/focus |
-| `TooltipContent` | Component | Styled content panel rendered in a portal with enter/exit animations |
+|---|---|---|
+| `TooltipProvider` | Component | Radix `Provider` wrapper; manages tooltip open/close delays globally |
+| `Tooltip` | Component | Radix `Root`; controls open state for a single tooltip |
+| `TooltipTrigger` | Component | Radix `Trigger`; wraps the element that activates the tooltip |
+| `TooltipContent` | Component | Styled content panel; portals into the active container via `usePortalContainer` |
 
 ## Usage Example
 
@@ -20,15 +20,15 @@ import {
   TooltipTrigger,
 } from "@/components/ui/tooltip"
 
-export function ActionButton() {
+export function InfoButton() {
   return (
     <TooltipProvider>
       <Tooltip>
         <TooltipTrigger asChild>
-          <button>Hover me</button>
+          <button aria-label="More info">ℹ️</button>
         </TooltipTrigger>
         <TooltipContent side="top">
-          <p>Helpful context here</p>
+          This action cannot be undone.
         </TooltipContent>
       </Tooltip>
     </TooltipProvider>
@@ -38,6 +38,9 @@ export function ActionButton() {
 
 ## Notes
 
-- `TooltipContent` defaults to `sideOffset={4}` and supports all four sides (`top`, `bottom`, `left`, `right`) with direction-aware slide-in animations via Tailwind data attributes.
-- Content is injected via a **portal**, ensuring correct stacking context (`z-[1400]`) above modals and overlays.
-- `TooltipProvider` should be placed high in the component tree (e.g., root layout) to avoid nesting multiple providers unnecessarily.
+- **Portal targeting** — `usePortalContainer` pipes the tooltip into a drawer or sheet's DOM node when one is active, preventing z-index clipping. Falls back to `document.body` when no container context is provided.
+- **Height constraint** — `max-h` is bound to `--radix-popper-available-height`, so oversized content scrolls rather than overflows the viewport.
+- **Animations** — Entry/exit transitions are driven by Radix `data-state` and `data-side` attributes via Tailwind `animate-in`/`animate-out` utilities.
+- **`sideOffset`** — Defaults to `4px`; can be overridden per instance via props.
+
+**Source:** [`tooltip.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/tooltip.tsx)

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

@@ -1,13 +1,15 @@
-<!-- source-hash: de008cac6e8735331504b8c3add5fdc8 -->
-Shared Tailwind class constants for button surface colors, outline borders, and split-divider colors — consumed by both `Button` and `SplitButton` components as a single source of truth.
+<!-- source-hash: 93b65bad78f61892d6bffdfdb828ce09 -->
+Defines shared Tailwind CSS style atoms consumed by `Button` and `SplitButton` components, establishing a single source of truth for surface colors, border styles, and split-divider colors across all button variants.
 
 ## Key Components
 
-- **`buttonSurfaceClasses`** — Object map of Tailwind classes per visual variant (`accent`, `outline`, `transparent`, `destructive`, `warning`), covering base, hover, active, `disabled:`, and `aria-disabled:` states.
-- **`outlineBorderClasses`** — Shared border string applied to `outline` variant buttons across all states.
-- **`splitDividerColorClasses`** — Per-variant border color for the vertical seam dividing main and icon halves in split-button layouts.
+- **`buttonSurfaceClasses`** — Record mapping each variant (`accent`, `outline`, `transparent`, `destructive`, `warning`) to Tailwind utility strings covering background, text, hover, active, and both `disabled:` / `aria-disabled:` states.
+- **`outlineBorderClasses`** — Shared border string applied exclusively to the `outline` variant across all interactive states.
+- **`splitDividerColorClasses`** — Record mapping each variant to its border color for the vertical seam separating the main and icon halves in split-button layouts.
 - **`ButtonSurfaceVariant`** — Derived union type (`"accent" | "outline" | "transparent" | "destructive" | "warning"`) inferred from `buttonSurfaceClasses` keys.
 
+> **`disabled:` vs `aria-disabled:`** — Both states are always paired. `disabled:` targets native `<button disabled>` elements; `aria-disabled:` handles `<a aria-disabled="true">` anchors, which do not support the CSS `:disabled` pseudo-class.
+
 ## Usage Example
 
 ```typescript
@@ -18,18 +20,15 @@ import {
   type ButtonSurfaceVariant,
 } from "./button-styles"
 
-const variant: ButtonSurfaceVariant = "accent"
-
-// Apply surface classes to a button element
-const surfaceClass = buttonSurfaceClasses[variant]
-// → "bg-ods-accent text-ods-text-on-accent hover:bg-ods-accent-hover ..."
-
-// Combine with border classes for the outline variant
-const outlineButtonClass = `${buttonSurfaceClasses.outline} ${outlineBorderClasses}`
+function getButtonClasses(variant: ButtonSurfaceVariant): string {
+  const surface = buttonSurfaceClasses[variant]
+  const border = variant === "outline" ? ` ${outlineBorderClasses}` : ""
+  return `${surface}${border}`
+}
 
-// Resolve divider color for a SplitButton
-const dividerClass = splitDividerColorClasses[variant]
-// → "border-ods-accent-active"
-```
+// "accent" → bg-ods-accent text-ods-text-on-accent hover:bg-ods-accent-hover …
+getButtonClasses("accent")
 
-> **Note:** Both `disabled:` and `aria-disabled:` states are included in every variant because `<a>` elements don't support the native `:disabled` pseudo-class — use `aria-disabled` on anchor-based buttons.
+// Split-button divider color for "destructive"
+const divider = splitDividerColorClasses["destructive"] // "border-ods-error-active"
+```

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

@@ -1,53 +1,46 @@
-<!-- source-hash: e6cbc38937ee7e5569d78f2d7f50de6f -->
-A polymorphic, variant-aware button component built on `class-variance-authority` and Radix UI's `Slot`, supporting standard buttons, link navigation, split-icon layouts, and loading states.
+<!-- source-hash: d5a003b7cf74c407be223ae980cad122 -->
+Flexible, multi-variant button component supporting standard buttons, links, split-icon layouts, and loading states via a unified `Button` interface.
 
 ## Key Components
 
-- **`Button`** — Primary export; a `forwardRef` component that renders as `<button>`, `<Link>`, or a custom element (`asChild`).
-- **`buttonVariants`** — CVA config for the standard single-content layout; drives `variant`, `size`, `fullWidth`, and `noPaddingX` props.
-- **`splitShellVariants` / `splitSlotVariants`** — CVA configs for the split layout (triggered by `splitIcon`), where a vertical divider separates content from a trailing icon area.
-- **`Spinner`** — Internal animated SVG displayed during the `loading` state; absolutely positioned to avoid layout shift.
-- **`ButtonProps`** — Full interface including `href`, `linkProps`, `leftIcon`, `rightIcon`, `splitIcon`, `loading`, and deprecated `size="small-legacy"`.
+- **`buttonVariants`** — CVA variant map defining styles for `variant` (`accent`, `outline`, `transparent`, `destructive`, `warning`), `size` (`default`, `small`, `small-legacy`, `compact`, `icon`, `icon-sm`), `fullWidth`, and `noPaddingX`.
+- **`splitShellVariants` / `splitSlotVariants`** — CVA helpers for the split-icon layout, where a vertical divider separates main content from a trailing icon area within a single click target.
+- **`Spinner`** — Internal SVG spinner rendered absolutely during `loading` state, preserving button dimensions.
+- **`Button`** — Primary export. A `forwardRef` component that auto-selects rendering strategy: `<Slot>` (`asChild`), `<Link>` (`href` / `linkProps`), split layout (`splitIcon`), or a plain `<button>`.
 
-## Usage Example
+## Props
 
-```typescript
-// Standard accent button
-<Button variant="accent" size="default" onClick={handleClick}>
-  Save
-</Button>
+| Prop | Type | Notes |
+|---|---|---|
+| `variant` | `accent` \| `outline` \| `transparent` \| `destructive` \| `warning` | Defaults to `accent` |
+| `size` | `default` \| `small` \| `compact` \| `icon` \| `icon-sm` | `small-legacy` deprecated |
+| `href` / `linkProps` | `string` / object | Renders as `<Link>`; `linkProps` wins over `href` |
+| `splitIcon` | `ReactNode` | Triggers split layout (default/small sizes only) |
+| `loading` | `boolean` | Hides content, shows spinner; implies `disabled` |
+| `asChild` | `boolean` | Delegates rendering to child via Radix `Slot` |
 
-// Link button with new-tab navigation
-<Button href="https://flamingo.run" openInNewTab>
-  Learn More
-</Button>
+## Usage Example
 
-// Loading state (preserves button width)
-<Button loading disabled>
-  Submitting...
+```typescript
+// Standard accent button with loading state
+<Button variant="accent" loading={isSubmitting} onClick={handleSubmit}>
+  Save Changes
 </Button>
 
-// Split layout with trailing icon
-<Button splitIcon={<ChevronDownIcon />} variant="outline">
-  Actions
+// Link button with split icon
+<Button href="/dashboard" splitIcon={<ChevronDownIcon />} variant="outline">
+  Dashboard
 </Button>
 
-// Pre-resolved nav link (from useNavLink)
-<Button linkProps={{ href: "/dashboard", target: "_blank", rel: "noopener noreferrer" }}>
-  Dashboard
+// Icon-only ghost button
+<Button variant="transparent" size="icon-sm" aria-label="Share">
+  <ShareIcon />
 </Button>
 
-// Render as child (asChild pattern)
-<Button asChild variant="destructive">
-  <a href="/delete">Delete Account</a>
+// Render as child (asChild)
+<Button asChild variant="outline">
+  <a href="https://openframe.ai">Learn More</a>
 </Button>
 ```
 
-### Variants
-
-| Prop | Options |
-|---|---|
-| `variant` | `accent` · `outline` · `transparent` · `destructive` · `warning` |
-| `size` | `default` · `small` · `icon` · `small-legacy` *(deprecated)* |
-| `fullWidth` | `true` / `false` |
-| `noPaddingX` | `true` / `false` |
+**Source:** [`button.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/button.tsx)

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

@@ -1,48 +1,71 @@
-<!-- source-hash: ae09312a4100bb1a98fd84f799794547 -->
-A compound button component with two independently interactive halves — a main action area and a trailing icon action area — separated by a 1px variant-colored divider seam.
+<!-- source-hash: 35b1020cbe4e7f93380a44a0312c0736 -->
+A dual-interactive button component that renders two independent clickable halves — a main action half and an icon half — separated by a 1px variant-colored divider seam.
 
 ## Key Components
 
-- **`SplitButton`** — Primary exported component (`React.forwardRef<HTMLDivElement, SplitButtonProps>`). Renders a `role="group"` div containing two `Half` instances sharing the same variant and size.
-- **`Half`** — Internal helper that renders either a `<button>` or a Next.js `<Link>` depending on whether an `href` is provided, applying `splitHalfVariants` classes.
-- **`splitHalfVariants`** — `cva`-powered class builder with `variant` (`accent` | `outline` | `transparent` | `destructive` | `warning`), `size` (`default` | `small`), and `side` (`main` | `icon`) axes. Compound variants handle rounded corners, divider borders, and icon-half width overrides.
-- **`SplitButtonIconAction`** — Interface describing the icon half: requires `icon` and `aria-label`; optionally accepts `onClick`, `href`, `openInNewTab`, `prefetch`, and `disabled`.
-- **`SplitButtonProps`** — Full prop surface for `SplitButton`, including `fullWidth`, `mainDisabled` (disables only the main half), `groupAriaLabel`, and the required `iconAction`.
+### `SplitButton` (default export)
+
+A `React.forwardRef` component wrapping both halves in a `role="group"` div. Each half independently supports button or link (`<a>`) rendering.
+
+### `Half` (internal)
+
+Renders either a Next.js `<Link>` or a `<button>` depending on whether an `href` is provided. Applies `splitHalfVariants` CVA classes for consistent styling.
+
+### `splitHalfVariants`
+
+CVA configuration controlling appearance via:
+- **`variant`**: `accent` | `outline` | `transparent` | `destructive` | `warning`
+- **`size`**: `default` | `small`
+- **`side`**: `main` | `icon` (controls rounding and divider border)
+- **`soloOnMobile`**: hides the icon half on small screens when `iconAction.openInNewTab` is `true`
+
+## Key Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `iconAction` | `SplitButtonIconAction` | Required. Icon half config (icon, aria-label, href/onClick) |
+| `variant` | `SplitButtonVariant` | Visual style; defaults to `"accent"` |
+| `disabled` | `boolean` | Disables both halves |
+| `mainDisabled` | `boolean` | Disables only the main half |
+| `fullWidth` | `boolean` | Stretches the main half; icon half stays fixed-width |
+| `openInNewTab` | `boolean` | Opens main link in new tab; also triggers `soloOnMobile` |
 
 ## Usage Example
 
 ```typescript
 import { SplitButton } from "./split-button"
-import { ChevronDownIcon, PlusIcon } from "lucide-react"
+import { ChevronDownIcon, ExternalLinkIcon } from "lucide-react"
 
-// Accent split button: main action navigates, icon half opens a dropdown
+// Button + icon-action as two independent targets
 <SplitButton
   variant="accent"
   size="default"
-  href="/tickets/new"
-  leftIcon={<PlusIcon />}
-  groupAriaLabel="Create ticket actions"
+  onClick={() => handleSave()}
   iconAction={{
     icon: <ChevronDownIcon />,
-    "aria-label": "More create options",
-    onClick: () => setDropdownOpen(true),
+    "aria-label": "More save options",
+    onClick: () => openDropdown(),
   }}
 >
-  New Ticket
+  Save
 </SplitButton>
 
-// Destructive split with main disabled independently
+// Link main half + new-tab icon half (icon hides on mobile)
 <SplitButton
-  variant="destructive"
-  mainDisabled
+  variant="outline"
+  href="/dashboard"
   iconAction={{
-    icon: <ChevronDownIcon />,
-    "aria-label": "Delete options",
-    onClick: handleIconClick,
+    icon: <ExternalLinkIcon />,
+    "aria-label": "Open in new tab",
+    href: "/dashboard",
+    openInNewTab: true,
   }}
+  groupAriaLabel="Dashboard navigation"
 >
-  Delete
+  Dashboard
 </SplitButton>
 ```
 
-> **Accessibility note:** The icon half has no visible text, so `iconAction["aria-label"]` is required. Use `groupAriaLabel` to label the wrapping `role="group"` when both halves share a semantic context.
+> **Note:** For a single-target button with a decorative trailing icon, use `<Button splitIcon>` instead. `SplitButton` is specifically for two independently interactive halves.
+
+**Source:** [`split-button.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/split-button.tsx)

package/src/components/ui/button/button-styles.ts

@@ -14,6 +14,19 @@ export const buttonSurfaceClasses = {
     "bg-ods-error text-ods-text-on-accent hover:bg-ods-error-hover active:bg-ods-error-active disabled:bg-ods-disabled aria-disabled:bg-ods-disabled",
   warning:
     "bg-ods-warning text-ods-text-on-accent hover:bg-ods-warning-hover active:bg-ods-warning-active disabled:bg-ods-disabled aria-disabled:bg-ods-disabled",
+  // A self-contained glyph (play badge, unmute glyph) that already carries its
+  // own scrim: no button surface at all, in any state. Distinct from
+  // `transparent`, whose hover/active fills would paint a rectangle behind the
+  // glyph — which is why call sites were undoing them with
+  // `hover:bg-transparent active:bg-transparent`.
+  glyph:
+    "bg-transparent text-ods-text-primary hover:bg-transparent active:bg-transparent disabled:bg-transparent disabled:text-ods-text-disabled aria-disabled:bg-transparent aria-disabled:text-ods-text-disabled",
+  // Chrome that sits ON media (video cards, image lightboxes): a scrim disc so
+  // the glyph stays legible over an arbitrary frame. Promoted to a variant
+  // because the walkthrough card, its theater and the bite cards were each
+  // stacking the same classes at the call site.
+  overlay:
+    "rounded-full bg-ods-overlay text-ods-text-primary backdrop-blur-sm hover:text-ods-accent active:text-ods-accent-active disabled:text-ods-text-disabled aria-disabled:text-ods-text-disabled",
 } as const
 
 export const outlineBorderClasses =

package/src/components/ui/button/button.tsx

@@ -26,6 +26,8 @@ const buttonVariants = cva(
         transparent: buttonSurfaceClasses.transparent,
         destructive: buttonSurfaceClasses.destructive,
         warning: buttonSurfaceClasses.warning,
+        glyph: buttonSurfaceClasses.glyph,
+        overlay: buttonSurfaceClasses.overlay,
       },
       size: {
         default: "py-[var(--spacing-system-sf)] px-[var(--spacing-system-m)] text-h3 md:h-12 h-10",
@@ -48,6 +50,9 @@ const buttonVariants = cva(
         // metadata rather than CTAs — author-page social rows, share rows.
         // Pair with variant="transparent" for the ghost treatment.
         "icon-sm": "p-[var(--spacing-system-xxs)] h-8 w-8 [&_svg]:h-4 [&_svg]:w-4",
+        // Bare 56px media glyph (play / unmute over video). A size variant so
+        // hosts stop re-implementing a <button> to escape the 20px svg cap.
+        "icon-glyph": "p-0 h-14 w-14 [&_svg]:h-14 [&_svg]:w-14",
       },
       fullWidth: {
         true: "w-full",