@moldable-ai/ui 0.2.22 → 0.2.24

package/dist/lib/theme.js

@@ -1,7 +1,7 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useCallback, useContext, useEffect, useState, } from 'react';
-import { TooltipProvider } from '../components/ui/tooltip';
+import { TooltipProvider } from '../components/ui/tooltip.js';
 const ThemeContext = createContext(null);
 const STORAGE_KEY = 'moldable-theme';
 function getSystemTheme() {

package/docs/design-tokens.md

@@ -28,6 +28,11 @@ The default UI font is the platform sans-serif stack. Monospaced text uses the
 platform monospace stack. Prefer `Text` for normal interface copy; the token
 utilities are useful for display-scale titles and highly composed canvases.
 
+The native UI scale is deliberately small: `--text-11` for captions and
+metadata, `--text-13` for body and control text, `--text-16` for emphasized
+titles, `--text-18` for secondary headings, and `--text-24` for primary
+headings. Long-form Markdown keeps its prose scale.
+
 | Role    | CSS token          | Tailwind utility  | Use                                |
 | ------- | ------------------ | ----------------- | ---------------------------------- |
 | Display | `--type-display-*` | `text-ui-display` | One dominant app or document title |
@@ -109,15 +114,32 @@ disabled, and invalid states. Disabled wins over pointer states. Focus remains
 visible when combined with selected or invalid. Selection is durable state;
 hover is not a substitute for it.
 
+Focus rings use the neutral translucent `--ring` token at one pixel. Never use
+plain `focus:` ring utilities or accent colors for keyboard focus.
+
 Do not use state-layer colors as arbitrary fills. Prefer the shared component
 when one exists.
 
 ## Shape and materials
 
-Use `rounded-control`, `rounded-container`, and `rounded-overlay` to keep
-related objects visually consistent. `rounded-window` is host-informed and
-normally only useful in previews; the native host owns the actual window
-shape.
+Use `rounded-control`, `rounded-checkbox`, `rounded-popover`, `rounded-card`,
+`rounded-group`, `rounded-panel`, `rounded-dialog`, and `rounded-pill` to keep
+geometry tied to its role. The 4px checkbox role keeps a 16px checkbox
+visually square while ordinary controls retain their softer 10px corners.
+`rounded-container` and `rounded-overlay` remain compatibility aliases for
+card and popover geometry. `rounded-window` is host-informed and normally only
+useful in previews; the native host owns the actual window shape. Increased
+contrast reduces authored radii and uses inset borders instead of drop
+shadows.
+
+## Data series
+
+Charts consume `--chart-1` through `--chart-5` (and the matching
+`chart-1`…`chart-5` Tailwind aliases). The defaults intentionally reuse the
+info, success, pending, neutral, and accent support families so data graphics
+stay theme-aware and do not inherit Moldable's legacy brand orange. Apps may
+override the complete series palette at a theme boundary, but chart
+components and stories should never embed raw series colors.
 
 Adaptive material has two semantic variants. Each includes fill, fallback,
 border, highlight, blur, and saturation tokens:
@@ -125,8 +147,8 @@ border, highlight, blur, and saturation tokens:
 - `--material-regular-*` supports normal toolbar and control chrome.
 - `--material-clear-*` supports compact controls over media or a richly
   colored canvas.
-- `shadow-panel`, `shadow-overlay`, and `shadow-window` provide elevation
-  independently from translucency.
+- `shadow-panel`, `shadow-overlay`, `shadow-dialog`, and `shadow-window`
+  provide elevation independently from translucency.
 
 Use `Material` and `MaterialGroup` instead of assembling those tokens in app
 markup. `MaterialGroup` owns one sampled layer for a related control cluster;

package/docs/foundations.md

@@ -54,5 +54,7 @@ springy, and do not animate layout merely to make a screen feel active.
 
 ## Focus
 
-Keyboard focus must remain visible against every surface. Do not remove a
-focus ring unless the replacement is at least as clear.
+Keyboard focus uses a thin, neutral system-chrome ring. Apply it only through
+`focus-visible`; pointer and programmatic focus must not paint a ring. Dialogs
+focus their content container on open so the first Tab reaches the first
+control with the keyboard indicator.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moldable-ai/ui",
-  "version": "0.2.22",
+  "version": "0.2.24",
   "description": "Shared UI components for Moldable applications",
   "author": "Desiderata LLC",
   "license": "SEE LICENSE IN LICENSE",
@@ -37,11 +37,12 @@
     "dist",
     "docs",
     "src/components/ui/*.md",
+    "src/lib/*.md",
     "src/styles",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && node ./scripts/rewrite-relative-imports.mjs",
     "build:visual-host": "vite build --config vite.visual.config.ts",
     "dev": "tsc --watch",
     "lint": "eslint . --ext .ts,.tsx --max-warnings 0",
@@ -50,6 +51,7 @@
     "test": "vitest run",
     "test:visual": "pnpm build:visual-host && playwright test --config playwright.visual.config.ts",
     "test:visual:update": "pnpm build:visual-host && playwright test --config playwright.visual.config.ts --update-snapshots",
+    "filmstrip:orb-spawn": "node scripts/render-orb-spawn-filmstrip.mjs",
     "visual:serve": "vite preview --config vite.visual.config.ts --host 127.0.0.1 --port 4179 --strictPort"
   },
   "dependencies": {

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

@@ -0,0 +1,97 @@
+# Confirm dialog
+
+## Purpose
+
+`ConfirmDialog` asks for explicit confirmation before a consequential action
+and owns the pending and error states of an asynchronous confirmation.
+
+Use it for destructive or difficult-to-reverse actions, security-sensitive
+changes, and operations with a meaningful external effect. Do not interrupt
+routine, reversible actions; use undo or inline feedback instead. Use the
+lower-level `AlertDialog` family when the body needs custom media or layout.
+
+## Usage patterns
+
+```tsx
+import { Button, ConfirmDialog } from '@moldable-ai/ui'
+
+function DeleteRecordingDialog() {
+  return (
+    <ConfirmDialog
+      title="Delete recording?"
+      description="The audio and transcript will be permanently removed."
+      trigger={<Button variant="destructive">Delete recording</Button>}
+      confirmLabel="Delete"
+      pendingLabel="Deleting…"
+      variant="destructive"
+      size="sm"
+      onConfirm={() => deleteRecording(recordingId)}
+      onConfirmError={reportDeleteError}
+      getErrorMessage={() => 'The recording could not be deleted.'}
+    />
+  )
+}
+```
+
+For a controlled dialog, pass `open` and `onOpenChange`. Omit `trigger` when
+another event owns opening.
+
+## Anatomy
+
+`ConfirmDialog` composes `AlertDialog` with a required title and description,
+a cancel action, and one primary confirm action. It shows a shared spinner and
+`pendingLabel` while `onConfirm` is unresolved, then closes only after success.
+Rejected confirmation remains open and renders an alert message.
+
+## API summary
+
+- `title`, `description`, and `onConfirm` are required.
+- `trigger` accepts one React element.
+- `confirmLabel`, `pendingLabel`, and `cancelLabel` accept React content and
+  default to “Confirm”, “Working…”, and “Cancel”.
+- `variant` is `"default" | "destructive"` and defaults to `"default"`.
+- `size` is `"sm" | "default" | "lg"` and defaults to `"default"`.
+- `open`, `defaultOpen`, and `onOpenChange` support controlled or uncontrolled
+  disclosure.
+- `onConfirmError` receives the rejected value. `getErrorMessage` maps it to
+  rendered React content.
+
+## States and interaction
+
+While `onConfirm` is pending, both actions are disabled, repeated confirmation
+is ignored, and close requests are blocked. Success closes the dialog and calls
+`onOpenChange(false)`. Failure clears pending state, keeps the dialog open,
+shows the mapped error or default message, and calls `onConfirmError`.
+
+The surface uses `bg-background`, `border-separator`, `rounded-dialog`, and
+`shadow-dialog`. Description copy uses `text-text-secondary`; failed and
+destructive states use the semantic destructive role. Do not add raw danger
+colors or custom dialog elevation.
+
+## Keyboard and accessibility
+
+The component inherits alert-dialog semantics and focus containment. The
+dialog content receives initial focus; Enter activates the marked primary
+action when appropriate, and pending state prevents dismissal. Write a
+specific title and describe the consequence, not merely “Are you sure?”.
+Error copy is announced with `role="alert"`.
+
+## Do
+
+- Name the action and the affected object in the title or description.
+- Use `variant="destructive"` only for destructive confirmation.
+- Return the action promise from `onConfirm`.
+- Map technical failures to concise, actionable copy with `getErrorMessage`.
+
+## Don't
+
+- Do not confirm harmless, reversible, or high-frequency actions.
+- Do not close optimistically before `onConfirm` succeeds.
+- Do not perform the action from both the trigger and `onConfirm`.
+- Do not expose raw exception text to users.
+
+## Testing
+
+Exercise controlled and uncontrolled opening, success, rejection, repeated
+activation while pending, attempted dismissal while pending, destructive
+styling, all three sizes, and keyboard confirmation.

package/src/components/ui/context-menu.md

@@ -0,0 +1,158 @@
+# Context menu
+
+## Purpose
+
+`ContextMenu` presents commands for the object or region under the pointer. Its
+declarative item API automatically adopts the host-native menu when available
+and renders the same commands portably everywhere else.
+
+Context menus are shortcuts, not the only route to essential actions. Use
+`DropdownMenu` when a visible button should advertise the command list.
+
+## Usage patterns
+
+Use `items` for standard command menus that should automatically adopt the
+native host menu:
+
+```tsx
+import { FolderOpen } from 'lucide-react'
+import {
+  ContextMenu,
+  ContextMenuTrigger,
+  type MenuItems,
+} from '@moldable-ai/ui'
+
+const items: MenuItems[] = [
+  {
+    id: 'open',
+    label: 'Open',
+    icon: FolderOpen,
+    sfSymbol: 'folder',
+    shortcut: { key: 'o', modifiers: ['cmd'] },
+  },
+  { id: 'divider', kind: 'separator' },
+  { id: 'trash', label: 'Move to trash', destructive: true },
+]
+
+function ProjectContextMenu() {
+  return (
+    <ContextMenu items={items} onSelectItem={runCommand}>
+      <ContextMenuTrigger asChild>
+        <article>{project.name}</article>
+      </ContextMenuTrigger>
+    </ContextMenu>
+  )
+}
+```
+
+Use children for custom portable-only content or per-row handlers:
+
+```tsx
+import {
+  ContextMenu,
+  ContextMenuContent,
+  ContextMenuItem,
+  ContextMenuSeparator,
+  ContextMenuShortcut,
+  ContextMenuTrigger,
+} from '@moldable-ai/ui'
+
+function ProjectContextMenu() {
+  return (
+    <ContextMenu onOpenChange={setMenuOpen}>
+      <ContextMenuTrigger asChild>
+        <article>{project.name}</article>
+      </ContextMenuTrigger>
+      <ContextMenuContent>
+        <ContextMenuItem onSelect={openProject}>
+          Open
+          <ContextMenuShortcut>⌘O</ContextMenuShortcut>
+        </ContextMenuItem>
+        <ContextMenuSeparator />
+        <ContextMenuItem variant="destructive" onSelect={moveToTrash}>
+          Move to trash
+        </ContextMenuItem>
+      </ContextMenuContent>
+    </ContextMenu>
+  )
+}
+```
+
+## Anatomy
+
+Use `ContextMenuTrigger` around the target and place commands in
+`ContextMenuContent`. Groups, labels, separators, checkbox items, radio groups,
+shortcuts, and submenus are available for structured command sets.
+
+## API summary
+
+- `ContextMenu` supports `items?: MenuItems[]`,
+  `onSelectItem?: (id: string) => void`, `onOpenChange`, `dir`, and `modal`.
+- A `MenuItems` value supports `id`, `kind`, `label`, portable `icon`, reserved
+  `sfSymbol`, `enabled`, `checked`, `shortcut`, `destructive`, and `submenu`.
+- Do not provide `ContextMenuContent` together with `items`. In development this
+  reports an error, and `items` wins.
+- `ContextMenuTrigger` supports `asChild` and `disabled`.
+- `ContextMenuItem` supports menu item props such as `onSelect` and `disabled`,
+  plus `inset` and `variant="default" | "destructive"`.
+- `ContextMenuCheckboxItem` supports `checked`; radio items belong inside
+  `ContextMenuRadioGroup`, whose `value` and `onValueChange` manage the group.
+- `ContextMenuSub` supports `open`, `defaultOpen`, and `onOpenChange`.
+- `ContextMenuLabel` and `ContextMenuSubTrigger` support `inset`.
+
+## States and interaction
+
+Keep command order and wording stable across openings. Disable temporarily
+unavailable commands, but omit commands the target can never support. Check and
+radio state represent durable settings; focus highlighting is transient.
+
+Menu surfaces use `bg-popover`, `text-popover-foreground`,
+`rounded-overlay`, and `shadow-overlay`. Focused rows use the accent roles;
+destructive rows use `text-destructive` and the destructive focus layer.
+
+## Keyboard and accessibility
+
+Radix supplies menu roles, roving focus, typeahead, Escape dismissal, and
+submenu keyboard behavior. Do not put arbitrary controls inside an item. Make
+every essential command available from a visible button, menu, toolbar, or
+command palette as well as the context menu.
+
+## Platform behavior
+
+With `items`, a user-initiated context-menu gesture automatically opens the
+host-native menu when `nativeMenu` is advertised. The pointer position is its
+anchor, `selectedId` is delivered to `onSelectItem`, and dismissal is a no-op.
+No portable menu is rendered while that native request is open.
+
+When the service is not advertised, including web and iOS, the same items
+automatically render through the existing Radix anatomy. If advertised
+availability becomes stale and the host returns fallback, the original gesture
+is replayed into that portable implementation. Icons and destructive styling
+are portable in v1; `sfSymbol` is reserved and is not posted to or rendered by
+the native service.
+
+Shortcuts are display metadata only. They do not register keyboard handlers;
+keep command execution keyed by `onSelectItem`. See
+[`host-native-menu.md`](../../lib/host-native-menu.md) for host limits and
+cancellation behavior.
+
+## Do
+
+- Name items with short, verb-led labels.
+- Put JSX shortcuts at the end with `ContextMenuShortcut`, or declare shortcut
+  display metadata in `items`.
+- Separate destructive commands from routine commands.
+- Keep submenu depth shallow.
+
+## Don't
+
+- Do not make a context menu the only way to complete a task.
+- Do not mix `items` with `ContextMenuContent` children.
+- Do not treat shortcut metadata as a registered keyboard command.
+- Do not use raw colors, shadows, or radii for menu states.
+
+## Testing
+
+Exercise secondary click, long press where supported, keyboard navigation,
+Escape, disabled items, checkbox/radio state, submenus, native selection and
+dismissal, service availability changes, and portable fallback.

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

@@ -0,0 +1,165 @@
+# Dropdown menu
+
+## Purpose
+
+`DropdownMenu` presents a compact list of commands from a visible trigger. Use
+it for overflow actions, view commands, and small command groups. Its
+declarative item API automatically adopts the host-native menu when available.
+
+Use `Select` for a form value, `Combobox` for searchable selection,
+`ContextMenu` for commands attached to the pointer target, and `Popover` when
+the surface needs arbitrary interactive content rather than menu items.
+
+## Usage patterns
+
+Use `items` for standard command menus:
+
+```tsx
+import { Copy } from 'lucide-react'
+import {
+  Button,
+  DropdownMenu,
+  DropdownMenuTrigger,
+  type MenuItems,
+} from '@moldable-ai/ui'
+
+const items: MenuItems[] = [
+  {
+    id: 'duplicate',
+    label: 'Duplicate',
+    icon: Copy,
+    shortcut: { key: 'd', modifiers: ['cmd'] },
+  },
+  { id: 'divider', kind: 'separator' },
+  { id: 'trash', label: 'Move to trash', destructive: true },
+]
+
+function ProjectActionsMenu() {
+  return (
+    <DropdownMenu items={items} onSelectItem={runCommand}>
+      <DropdownMenuTrigger asChild>
+        <Button type="button" variant="outline" size="sm">
+          Actions
+        </Button>
+      </DropdownMenuTrigger>
+    </DropdownMenu>
+  )
+}
+```
+
+Use children for custom portable-only content or per-row handlers:
+
+```tsx
+import {
+  Button,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuShortcut,
+  DropdownMenuTrigger,
+} from '@moldable-ai/ui'
+
+function ProjectActionsMenu() {
+  return (
+    <DropdownMenu open={open} onOpenChange={setOpen}>
+      <DropdownMenuTrigger asChild>
+        <Button type="button" variant="outline" size="sm">
+          Actions
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent sideOffset={4} align="end">
+        <DropdownMenuItem onSelect={duplicate}>
+          Duplicate
+          <DropdownMenuShortcut>⌘D</DropdownMenuShortcut>
+        </DropdownMenuItem>
+        <DropdownMenuSeparator />
+        <DropdownMenuItem variant="destructive" onSelect={moveToTrash}>
+          Move to trash
+        </DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+```
+
+## Anatomy
+
+`DropdownMenuTrigger` advertises the menu and `DropdownMenuContent` contains
+the commands. Groups, labels, separators, checkbox items, radio groups,
+shortcuts, and submenus are available when the command set needs structure.
+
+## API summary
+
+- `DropdownMenu` supports `items?: MenuItems[]`,
+  `onSelectItem?: (id: string) => void`, `open`, `defaultOpen`,
+  `onOpenChange`, `dir`, and `modal`.
+- A `MenuItems` value supports `id`, `kind`, `label`, portable `icon`, reserved
+  `sfSymbol`, `enabled`, `checked`, `shortcut`, `destructive`, and `submenu`.
+- Do not provide `DropdownMenuContent` together with `items`. In development
+  this reports an error, and `items` wins.
+- `DropdownMenuTrigger` accepts button props and `asChild`.
+- `DropdownMenuContent` accepts positioning props including `side`, `align`,
+  and `sideOffset`; this wrapper defaults `sideOffset` to `4`.
+- `DropdownMenuItem` supports menu item props such as `onSelect` and
+  `disabled`, plus `inset` and `variant="default" | "destructive"`.
+- `DropdownMenuCheckboxItem` supports `checked`; radio items belong inside
+  `DropdownMenuRadioGroup`, whose `value` and `onValueChange` manage the group.
+- `DropdownMenuSub` supports `open`, `defaultOpen`, and `onOpenChange`.
+- `DropdownMenuLabel` and `DropdownMenuSubTrigger` support `inset`.
+
+## States and interaction
+
+Use controlled `open` when another surface, including a native-menu fallback,
+must open the portable menu. Checkbox and radio items retain menu semantics and
+should represent durable state. Keep command order stable and place destructive
+commands last or in a separated group.
+
+Menu surfaces use `bg-popover`, `text-popover-foreground`,
+`rounded-overlay`, and `shadow-overlay`. Focused and open submenu rows use the
+accent roles; destructive rows use the semantic destructive roles.
+
+## Keyboard and accessibility
+
+Radix supplies menu roles, trigger semantics, roving focus, typeahead, Escape
+dismissal, and submenu navigation. Give icon-only triggers an accessible name
+and a tooltip. Do not place form fields or arbitrary focusable content inside a
+menu item; use `Popover` or `Dialog`.
+
+## Platform behavior
+
+With `items`, pointer and keyboard trigger activation automatically opens the
+host-native menu when `nativeMenu` is advertised. The trigger rectangle is its
+anchor, `selectedId` is delivered to `onSelectItem`, and dismissal is a no-op.
+No portable menu is rendered while that native request is open.
+
+Without the advertisement, including web and iOS, the same items automatically
+render through the existing Radix anatomy. A stale advertisement that returns
+fallback opens the portable menu as well. Icons and destructive styling are
+portable in v1; `sfSymbol` is reserved and is not posted to or rendered by the
+native service.
+
+Shortcuts are display metadata only. They do not register keyboard handlers;
+keep command execution keyed by `onSelectItem`. See
+[`host-native-menu.md`](../../lib/host-native-menu.md) for host limits and
+cancellation behavior.
+
+## Do
+
+- Use a visible trigger that communicates the menu's scope.
+- Keep labels concise and verb-led.
+- Use checkbox and radio items for menu-owned state.
+- Keep submenus shallow and provide shortcuts only for real commands.
+
+## Don't
+
+- Do not use a command menu as a form-value selector.
+- Do not hide a single primary action behind an overflow trigger.
+- Do not mix `items` with `DropdownMenuContent` children.
+- Do not treat shortcut metadata as a registered keyboard command.
+
+## Testing
+
+Exercise pointer and keyboard opening, focus movement, typeahead, Escape,
+disabled items, checkbox/radio state, submenus, native selection and dismissal,
+service availability changes, and portable fallback.

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

@@ -0,0 +1,90 @@
+# Hover card
+
+## Purpose
+
+`HoverCard` reveals a richer, non-essential preview for a referenced object,
+usually a link. It helps users decide whether to open a person, file, project,
+or other destination without leaving the current view.
+
+Use `Tooltip` for a terse, non-interactive clarification of an already named
+control. Use `HoverCard` for preview content with several lines or pieces of
+metadata. Use `Popover` when the surface contains actions, fields, settings, or
+other interactive content.
+
+## Usage patterns
+
+```tsx
+import { HoverCard, HoverCardContent, HoverCardTrigger } from '@moldable-ai/ui'
+
+function ProjectPreview() {
+  return (
+    <HoverCard openDelay={400} closeDelay={150}>
+      <HoverCardTrigger href="/projects/atlas">
+        Atlas migration
+      </HoverCardTrigger>
+      <HoverCardContent side="right" align="start">
+        <p className="text-ui-label font-medium">Atlas migration</p>
+        <p className="text-text-secondary text-ui-body">
+          Infrastructure move · updated 12 minutes ago
+        </p>
+      </HoverCardContent>
+    </HoverCard>
+  )
+}
+```
+
+The trigger is link-based by default and accepts anchor props. Keep the
+destination usable without opening the preview.
+
+## Anatomy
+
+`HoverCard` owns timing and open state. `HoverCardTrigger` references the
+previewed object. `HoverCardContent` is portalled and collision-aware; this
+wrapper defaults to `align="center"`, `sideOffset={4}`, and a `w-64` preview.
+
+## API summary
+
+- `HoverCard` supports `open`, `defaultOpen`, `onOpenChange`, `openDelay`, and
+  `closeDelay`.
+- `HoverCardTrigger` accepts anchor props, including `href`.
+- `HoverCardContent` accepts positioning props including `side`, `align`, and
+  `sideOffset`, plus `forceMount` and outside-interaction handlers.
+
+## States and interaction
+
+The preview must remain supplementary. Touch users and users who never hover
+must still be able to understand and activate the trigger. Keep delay changes
+local and deliberate so neighboring previews do not flicker while the pointer
+moves through a collection.
+
+Content uses `bg-popover`, `text-popover-foreground`, `rounded-overlay`, and
+`shadow-overlay`. Use `text-text-secondary` for supporting preview metadata;
+do not invent a preview-only palette or elevation.
+
+## Keyboard and accessibility
+
+The trigger must retain its own accessible name and destination. Do not put
+required instructions only in the card. If content must receive focus or
+contain controls, switch to `Popover`, whose explicit trigger and dismissal
+model fit interactive content.
+
+## Do
+
+- Preview the same object the trigger names.
+- Keep content concise enough to scan without scrolling.
+- Include metadata that helps a navigation decision.
+- Preserve a working link or other primary path on the trigger.
+
+## Don't
+
+- Do not repeat a one-line label that belongs in `Tooltip`.
+- Do not place buttons, links, form fields, or required actions in the card;
+  use `Popover`.
+- Do not make hover the only way to discover important information.
+- Do not use a hover card as a delayed dialog.
+
+## Moldable considerations
+
+Hover cards are portable webview overlays. Keep them within collision-aware
+viewport bounds and avoid previews that cover the fixed desktop chat or a
+primary action for prolonged periods.