@moldable-ai/ui 0.2.19 → 0.2.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moldable-ai/ui",
-  "version": "0.2.19",
+  "version": "0.2.21",
   "description": "Shared UI components for Moldable applications",
   "author": "Desiderata LLC",
   "license": "SEE LICENSE IN LICENSE",
@@ -26,10 +26,17 @@
       "import": "./dist/index.js",
       "require": "./dist/index.js"
     },
+    "./catalog": {
+      "types": "./dist/catalog/index.d.ts",
+      "import": "./dist/catalog/index.js",
+      "require": "./dist/catalog/index.js"
+    },
     "./styles": "./src/styles/index.css"
   },
   "files": [
     "dist",
+    "docs",
+    "src/components/ui/*.md",
     "src/styles",
     "LICENSE"
   ],
@@ -82,7 +89,6 @@
     "framer-motion": "^12.15.0",
     "input-otp": "^1.4.2",
     "lucide-react": "^0.473.0",
-    "next-themes": "^0.4.6",
     "react-day-picker": "^9.13.0",
     "react-hook-form": "^7.71.1",
     "react-markdown": "^10.1.0",
@@ -96,7 +102,6 @@
     "tailwindcss": "^4.1.10",
     "tw-animate-css": "^1.3.4",
     "vaul": "^1.1.2",
-    "virtua": "^0.48.5",
     "zod": "^4.3.5"
   },
   "devDependencies": {

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

@@ -0,0 +1,31 @@
+# Alert Dialog and Confirm Dialog
+
+Use `AlertDialog` when the user must acknowledge a consequential choice. Use the
+composed anatomy for custom content and `ConfirmDialog` for the common
+promise-aware confirmation path.
+
+```tsx
+<ConfirmDialog
+  trigger={<Button variant="destructive">Delete recording</Button>}
+  title="Delete recording?"
+  description="This removes the local audio and transcript."
+  confirmLabel="Delete"
+  pendingLabel="Deleting…"
+  variant="destructive"
+  onConfirm={() => deleteRecording()}
+/>
+```
+
+`ConfirmDialog` prevents duplicate submission, disables cancellation while the
+operation is pending, closes only after success, and keeps failures in the
+dialog. Pass `getErrorMessage` when a safe, actionable domain error can be
+shown. The default error deliberately avoids exposing internal details.
+
+`AlertDialogContent` supports `sm`, `default`, and `lg` and stays within the
+host safe area. Use `AlertDialogBody` when explanation or affected-item content
+can grow. Keep the consequence visible while the action is pending.
+
+Use concrete labels such as “Delete recording,” not “OK.” Put the safe,
+reversible action first in keyboard order and the confirming action last. Do
+not use an alert dialog for ordinary navigation, long forms, or success
+messages.

package/src/components/ui/alert.md

@@ -0,0 +1,77 @@
+# Alert
+
+## Purpose
+
+`Alert` presents a persistent inline callout that belongs to the current
+surface. Use it for recoverable errors, permission or connection problems, and
+information the user should notice before continuing.
+
+Use `AlertDialog` when the user must confirm an action. Use `Empty` for the normal absence of data. Use a toast for brief feedback that does not need to remain in the layout.
+
+## Usage patterns
+
+```tsx
+import { CircleAlert } from 'lucide-react'
+import { Alert, AlertDescription, AlertTitle } from '@moldable-ai/ui'
+
+;<Alert tone="danger">
+  <CircleAlert />
+  <AlertTitle>Could not save</AlertTitle>
+  <AlertDescription>
+    The file changed on disk. Reload it, then try again.
+  </AlertDescription>
+  <AlertActions>
+    <Button size="sm">Reload</Button>
+  </AlertActions>
+</Alert>
+```
+
+Dismissible informational callouts may use `AlertDismiss`. Dismissal state is
+owned by the caller:
+
+```tsx
+<Alert tone="info">
+  <InfoIcon />
+  <AlertTitle>Local-only data</AlertTitle>
+  <AlertDescription>This workspace has not been synced.</AlertDescription>
+  <AlertDismiss label="Dismiss local-only notice" onClick={dismiss} />
+</Alert>
+```
+
+## API summary
+
+- `tone`: `neutral`, `info`, `success`, `warning`, or `danger`.
+- `density`: `compact` or `default`.
+- Neutral through warning tones default to `role="status"`; danger defaults to
+  `role="alert"`. The native `role` prop can override that choice.
+- `variant="default"` and `variant="destructive"` remain compatibility aliases.
+- `AlertTitle`: the short, emphasized heading.
+- `AlertDescription`: muted supporting content; supports nested paragraphs and controls.
+- `AlertActions`: a compact action row.
+- `AlertDismiss`: an icon action with a required accessible `label`; the caller
+  owns dismissal.
+- All parts accept the native props for their rendered element and a `className`.
+- A direct icon child on `Alert` receives the component’s grid placement and sizing.
+
+## Do
+
+- State what failed or what is blocked in a short title.
+- Include the specific message and a retry action when recovery is possible.
+- Keep technical details available through logs or a disclosure, not in the primary message.
+- Use an icon only when it improves recognition.
+- Keep the alert close to the field, pane, or operation it describes.
+
+## Don't
+
+- Do not use an alert as decorative introductory copy.
+- Do not show stack traces, raw exceptions, or secret values.
+- Do not use `danger` for neutral notices.
+- Do not rely on the icon or color alone for meaning.
+- Do not use `Alert` as a confirmation surface.
+- Do not use an alert for brief success feedback that should be a toast.
+
+## Moldable considerations
+
+Alerts inside a scrollable pane must participate in that pane’s chat-safe bottom spacing. Long-lived errors should not be covered by a fixed dock or desktop chat overlay.
+
+Copy should be calm and literal: “Could not load messages” is better than “Something went wrong!”. For authentication and permission states, name the blocked capability and offer exactly one primary next action. If the alert includes buttons, follow the standard button accessibility and density rules.

package/src/components/ui/app-frame.md

@@ -0,0 +1,38 @@
+# App frame
+
+The top-level shell for an app that can run in its own window or inside a host
+surface.
+
+```tsx
+<AppFrame>
+  <AppFrameTitlebar>
+    <AppFrameToolbar>
+      <strong>Calendar</strong>
+      <div className="ml-auto">{/* compact actions */}</div>
+    </AppFrameToolbar>
+  </AppFrameTitlebar>
+  <AppFrameContent>{/* the app-owned canvas */}</AppFrameContent>
+  <AppFrameStatusbar>Saved locally</AppFrameStatusbar>
+</AppFrame>
+```
+
+## Rules
+
+- Let the host render real window controls. Never draw imitation traffic lights.
+- Make the app's primary canvas the visual focus; titlebars and status bars are
+  supporting structure.
+- Titlebars and status bars use `material="regular"` by default. Use
+  `material="clear"` only when compact chrome overlays a rich canvas, or
+  `material="none"` when the composition supplies an opaque surface.
+- The app frame does not make the outer window draggable. A decorated native
+  titlebar or host-owned drag region must provide that behavior.
+- The host owns the `--window-*` inset variables. The component only consumes
+  them.
+- `AppFrameContent` applies the shared chat-safe padding by default. The value is
+  zero in a standalone window and is updated by the embedded host lifecycle.
+- Use `mode="embedded"` or `mode="window"` only for deterministic previews and
+  tests. Runtime apps should normally use `mode="auto"`; a future host context
+  may set `data-moldable-display-mode` before render when a window still uses an
+  app iframe.
+- Material samples only renderer content. Native behind-window material remains
+  host-owned.

package/src/components/ui/badge.md

@@ -0,0 +1,57 @@
+# Badge
+
+## Purpose
+
+`Badge` is a compact, non-primary label for status, category, count, or metadata. It helps a user scan rows and objects without becoming another action surface.
+
+Use a button or toggle when the element changes state. Use plain muted text when the metadata does not need a bounded shape.
+
+## Usage patterns
+
+```tsx
+import { Badge } from '@moldable-ai/ui'
+
+<Badge variant="secondary">Draft</Badge>
+<Badge variant="outline">3 selected</Badge>
+<Badge variant="destructive">Failed</Badge>
+```
+
+Badges work best at the edge of list rows, in compact inspector metadata, or beside a title. Keep the content short enough to scan without wrapping.
+
+When a badge is interactive, give the child its correct semantics:
+
+```tsx
+<Badge asChild variant="outline">
+  <a href="/jobs/running">Running</a>
+</Badge>
+```
+
+## API summary
+
+- `variant`: `default`, `secondary`, `destructive`, `outline`, `ghost`, or `link`. Defaults to `default`.
+- `asChild`: renders a Radix `Slot` and applies badge styling to its child.
+- Accepts native `span` props.
+- `badgeVariants` is exported for composing the same variants elsewhere.
+- Icons placed directly inside are normalized to a compact size.
+
+## Do
+
+- Use one or two words, a short number, or a concise state.
+- Prefer `secondary` or `outline` for ordinary metadata.
+- Use `destructive` only for a failure, blocked state, or serious warning.
+- Pair a colored state with clear text or an icon so meaning is not color-only.
+- Use `tabular-nums` through `className` for counts that update in place.
+
+## Don't
+
+- Do not turn every property into a badge.
+- Do not use badges as a substitute for primary buttons, tabs, or filters.
+- Do not place long explanations or sentences inside.
+- Do not invent raw category colors; use semantic variants unless a small, meaningful object color is required.
+- Do not show “AI” as a decorative badge when no actionable distinction exists.
+
+## Moldable considerations
+
+Moldable surfaces are intentionally dense, so badges should preserve horizontal scan order. In rows, keep the badge `shrink-0` and make the main text column `min-w-0`. Prefer a small status marker plus text over multiple adjacent badges.
+
+For background activity, use a precise state such as “Syncing” or “Queued”; remove the badge when the state no longer helps. A badge is not a notification and should not replace a useful Today item, alert, or progress indicator.

package/src/components/ui/button.md

@@ -0,0 +1,76 @@
+# Button
+
+## Purpose
+
+`Button` starts an immediate action or, with `asChild`, gives button styling and behavior to another interactive element. Use it for commands such as save, run, refresh, connect, archive, and open.
+
+Use a link for navigation. Use `Toggle` when the control represents an on/off view state, and `ToggleGroup` when the user chooses among a small set of modes.
+
+## Usage patterns
+
+```tsx
+import { Button } from '@moldable-ai/ui'
+import { RefreshCw } from 'lucide-react'
+
+<Button type="button" size="sm" className="cursor-pointer">
+  Save changes
+</Button>
+
+<Button
+  type="button"
+  variant="ghost"
+  size="icon-sm"
+  className="cursor-pointer"
+  aria-label="Refresh results"
+>
+  <RefreshCw />
+</Button>
+```
+
+Keep toolbar actions compact (`xs`, `sm`, `icon-xs`, or `icon-sm`). Reserve `default` or `lg` for the primary action in a form, setup state, or focused control dock. While an async action is running, disable the button, preserve its width, and show a small spinner beside a short status label.
+
+For links that should look like buttons:
+
+```tsx
+<Button asChild variant="outline" size="sm">
+  <a href="/settings">Open settings</a>
+</Button>
+```
+
+## API summary
+
+- `variant`: `default`, `destructive`, `outline`, `secondary`, `ghost`, or `link`. Defaults to `default`.
+- `size`: `default`, `xs`, `sm`, `lg`, `icon`, `icon-xs`, `icon-sm`, or `icon-lg`. Defaults to `default`.
+- `asChild`: renders a Radix `Slot` so the child owns the element and semantics.
+- Accepts native button props, including `type`, `disabled`, `aria-*`, and event handlers.
+- `buttonVariants` is exported for cases that need the same visual treatment on another component.
+
+## Do
+
+- Set `type="button"` unless the control intentionally submits a form.
+- Add `cursor-pointer`; use the real `disabled` attribute for unavailable or busy actions.
+- Give icon-only buttons an `aria-label` and a tooltip.
+- Use a specific Lucide icon that names the action.
+- Put one visually primary action in a local action group.
+- Keep labels literal and verb-led: “Save query”, “Connect account”, “Move to trash”.
+
+## Don't
+
+- Do not use a button for ordinary navigation without link semantics.
+- Do not rely on color alone to explain a destructive or selected action.
+- Do not use raw color classes, decorative gradients, or oversized call-to-action styling.
+- Do not use `Sparkles` as a generic AI marker.
+- Do not leave a busy button clickable or allow repeated submission.
+- Do not hide essential actions behind hover-only icon buttons.
+
+## Moldable considerations
+
+Buttons in a fixed bottom dock must remain above the desktop chat:
+
+```tsx
+<div style={{ bottom: 'calc(var(--chat-safe-padding, 0px) + 1.5rem)' }}>
+  <Button className="cursor-pointer">Apply changes</Button>
+</div>
+```
+
+Keep fixed groups within `max-w-[calc(100vw-2rem)]`. Toolbar buttons should normally fit an `h-8` or `h-9` bar. Important actions should also be exposed through app commands when useful. Do not add an app-local prompt or chat button when the action belongs to Moldable’s desktop chat.

package/src/components/ui/collapsible.md

@@ -0,0 +1,52 @@
+# Collapsible
+
+`Collapsible` exposes the unstyled Radix disclosure primitive.
+`CollapsibleSection` adds a consistent section trigger, state-aware chevron,
+border, and content spacing.
+
+```tsx
+<CollapsibleSection defaultOpen>
+  <CollapsibleSectionTrigger>Advanced options</CollapsibleSectionTrigger>
+  <CollapsibleSectionContent>
+    Controls that are useful less often.
+  </CollapsibleSectionContent>
+</CollapsibleSection>
+```
+
+## When to use
+
+Use a collapsible section for one independently disclosed region. Use
+`Accordion` when several peer sections need coordinated one-at-a-time or
+multi-section behavior.
+
+## API
+
+The base `Collapsible`, `CollapsibleTrigger`, and `CollapsibleContent` expose
+the Radix props directly.
+
+The section helpers add:
+
+- `CollapsibleSection`: bordered section root.
+- `CollapsibleSectionTrigger`: full-width trigger with a chevron driven by the
+  root `data-state`.
+- `CollapsibleSectionContent`: standard inset content.
+- `motion`: `default` or `none`.
+- `contentClassName`: styles the inset inner content without changing the
+  animated viewport.
+
+## Keyboard and accessibility
+
+The trigger is a button with `aria-expanded` and `aria-controls` managed by
+Radix. Space and Enter toggle it. The chevron is decorative.
+
+## Motion
+
+Motion is brief and uses the shared reduced-motion behavior. Set
+`motion="none"` for content where movement would distract or when a parent owns
+the transition.
+
+## Don't
+
+- Do not put another interactive control inside the trigger.
+- Do not hide required validation errors or primary actions by default.
+- Do not use a disclosure solely to make a sparse layout look busier.

package/src/components/ui/color-well.md

@@ -0,0 +1,11 @@
+# ColorWell
+
+Compact color selection or read-only swatch.
+
+```tsx
+<ColorWell aria-label="Project color" value={color} onValueChange={setColor} />
+```
+
+Use the browser color input as the renderer fallback. `readOnly` presents the
+value without implying interactivity. Never make color the only representation
+of a status or category.

package/src/components/ui/combobox.md

@@ -0,0 +1,42 @@
+# Combobox
+
+Searchable single- or multi-value selection for longer option sets.
+
+## When to use
+
+Use `Combobox` when users need to filter options, create values, or manage
+multiple selections. Use `Select` for a short fixed list, `Command` for actions,
+and `Input` for unconstrained text.
+
+## Anatomy
+
+Compose the root with `ComboboxInput`, `ComboboxContent`, `ComboboxList`, and
+`ComboboxItem`. Optional parts include groups, labels, separators, an empty
+state, clear/trigger controls, and the chips family for multi-value input.
+
+```tsx
+<Combobox items={projects}>
+  <ComboboxInput placeholder="Choose a project" />
+  <ComboboxContent>
+    <ComboboxEmpty>No matching projects.</ComboboxEmpty>
+    <ComboboxList>
+      {(project) => (
+        <ComboboxItem key={project.id} value={project}>
+          {project.name}
+        </ComboboxItem>
+      )}
+    </ComboboxList>
+  </ComboboxContent>
+</Combobox>
+```
+
+## Design and behavior
+
+- Keep option labels concise and place distinguishing metadata after the name.
+- Show a real loading state for remote results; “no matches” is not a loading
+  state.
+- Preserve Base UI keyboard navigation, focus, active-descendant, and
+  selection behavior.
+- Label the input visibly or with an accessible name.
+- Do not deep-import the implementation; `Combobox` is exported from the
+  package root.

package/src/components/ui/command.md

@@ -0,0 +1,54 @@
+# Command
+
+`Command` renders searchable, keyboard-driven actions and local choices.
+
+## When to use
+
+Use `CommandDialog` for an app-local command palette or picker with enough
+options to benefit from search. Use the item anatomy helpers when a result has
+supporting text or metadata.
+
+```tsx
+<CommandItem value="Open project">
+  <CommandItemIcon>
+    <FolderIcon />
+  </CommandItemIcon>
+  <CommandItemContent>
+    <CommandItemTitle>Open project</CommandItemTitle>
+    <CommandItemDescription>Choose a local folder</CommandItemDescription>
+  </CommandItemContent>
+  <CommandShortcut>⌘O</CommandShortcut>
+</CommandItem>
+```
+
+## Anatomy
+
+- `Command`, `CommandInput`, and `CommandList` own filtering and navigation.
+- `CommandGroup`, `CommandEmpty`, and `CommandSeparator` organize results.
+- `CommandItem` is the interactive cmdk option.
+- `CommandItemIcon`, `CommandItemContent`, `CommandItemTitle`, and
+  `CommandItemDescription` provide consistent row alignment.
+- `CommandShortcut` displays a trailing shortcut hint; it does not install the
+  shortcut.
+
+Use `NotificationDot`, `Status`, or `Spinner` as a trailing child when a result
+needs an indicator. Keep those states semantic instead of adding decoration to
+the row anatomy.
+
+## Keyboard and accessibility
+
+cmdk owns arrow-key navigation, selection, and filtering. Give icon-only
+information an accessible text equivalent. `CommandItemIcon` is decorative by
+default because the adjacent title should name the command.
+
+## Platform behavior
+
+This is a portable renderer component. An app-local palette does not replace
+the host command surface. Register host-visible commands through the Moldable
+command API and use this component only for commands owned by the current app.
+
+## Don't
+
+- Do not create a second interactive row inside `CommandItem`.
+- Do not install keyboard shortcuts from `CommandShortcut`.
+- Do not use a command palette for a small fixed set that fits in a menu.

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

@@ -0,0 +1,32 @@
+# Date Field
+
+## Purpose
+
+`DateField` provides a styled native HTML date input. It keeps platform parsing, keyboard entry, validation, locale-aware presentation, and the browser’s native picker rather than implementing a look-alike calendar.
+
+## Usage
+
+```tsx
+import { DateField } from '@moldable-ai/ui'
+
+;<DateField
+  aria-label="Due date"
+  value={dueDate}
+  min="2026-01-01"
+  onValueChange={setDueDate}
+  clearable
+/>
+```
+
+Values use the native timezone-free `YYYY-MM-DD` form. Use `value`/`onValueChange` for a controlled field or `defaultValue` for an uncontrolled field. Native attributes such as `min`, `max`, `step`, `required`, `disabled`, and `aria-invalid` pass through. `variant` is `default` or `filled`; `density` is `compact`, `default`, or `comfortable`.
+
+## Quality bar
+
+- Associate the input with a visible label or an accessible `aria-label`.
+- Store the returned value as a calendar date; do not pass it through a UTC timestamp just to format it.
+- Use native constraints and show validation text close to the field.
+- Allow clearing only when an empty date is valid.
+- Use a calendar popover only for workflows that require richer range, availability, or event selection.
+- Do not replace the native picker to imitate a desktop control.
+
+A host may later provide a native date capability. Keep that behind an explicit cross-client contract and preserve this web implementation as the portable fallback.

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

@@ -0,0 +1,55 @@
+# DatePicker
+
+`DatePicker` is a portable, date-only calendar popover. Its value is an ISO
+calendar date (`YYYY-MM-DD`), so app storage does not introduce timezone
+conversion.
+
+```tsx
+<DatePicker
+  aria-label="Due date"
+  value={dueDate}
+  onValueChange={setDueDate}
+  min="2026-01-01"
+  clearable
+/>
+```
+
+## DatePicker or DateField
+
+- Use `DatePicker` when a predictable renderer-owned calendar is important.
+- Use `DateField` when compact keyboard entry and the browser's date control
+  are preferable.
+- Use the standalone `Calendar` for ranges, multiple dates, or an always
+  visible month.
+
+## API
+
+- `value`, `defaultValue`: ISO `YYYY-MM-DD` or an empty string.
+- `onValueChange`: receives the next ISO date or an empty string.
+- `min`, `max`: inclusive ISO date limits.
+- `placeholder`: trigger copy when empty.
+- `locale`: the `react-day-picker` locale used by the calendar and display.
+- `formatValue`: custom trigger rendering for the ISO value.
+- `clearable`, `clearLabel`: optional clear action inside the popover.
+- `density`: `compact`, `default`, or `comfortable`.
+- `open`, `defaultOpen`, `onOpenChange`: controlled or uncontrolled popover.
+- Remaining button props apply to the trigger.
+
+## Keyboard and accessibility
+
+Label the trigger through visible form text, `aria-labelledby`, or
+`aria-label`. The trigger opens with Enter or Space. The calendar owns arrow,
+Home, End, Page Up, and Page Down behavior. Selection closes the popover and
+focus returns to the trigger.
+
+## Platform behavior
+
+This component is portable and uses no host API. A future native date or time
+control must be introduced through a shared host capability with this
+renderer-owned control as its fallback.
+
+## Don't
+
+- Do not put timestamps or UTC instants in this date-only value.
+- Do not use this component for time, date-time, or date-range selection.
+- Do not manually convert the selected value through `Date.toISOString()`.

package/src/components/ui/dialog.md

@@ -0,0 +1,40 @@
+# Dialog
+
+Use `Dialog` for focused work that temporarily blocks the current surface. Use
+`AlertDialog` or `ConfirmDialog` for consequential confirmation, `Popover` for
+small anchored controls, and `Sheet` for a secondary region that should retain
+spatial context.
+
+## Anatomy
+
+```tsx
+<Dialog>
+  <DialogTrigger asChild>
+    <Button>Edit details</Button>
+  </DialogTrigger>
+  <DialogContent size="lg">
+    <DialogHeader>
+      <DialogTitle>Edit details</DialogTitle>
+      <DialogDescription>Update the selected record.</DialogDescription>
+    </DialogHeader>
+    <DialogBody>{/* the only scrolling region */}</DialogBody>
+    <DialogFooter>{/* actions remain reachable */}</DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+`DialogContent` supports `sm`, `default`, `lg`, and `full`. It limits itself to
+the host-provided window and chat-safe insets. `DialogBody` owns vertical
+scrolling; do not put overflow on both the content and body.
+
+Keep dialogs opaque and visually stable. Translucent material belongs on small
+temporary control overlays where seeing the underlying context is useful.
+
+For async actions, keep the dialog controlled, disable duplicate submission,
+preserve the action label width, show inline field errors, and close only after
+success. Use `ConfirmDialog` when that is the entire workflow.
+
+Every dialog needs a `DialogTitle`. Add `DialogDescription` when the outcome or
+scope is not obvious. Escape, outside dismissal, initial focus, and focus return
+come from the Radix primitive; do not replace them with manual document event
+handlers.

package/src/components/ui/edge-fade.md

@@ -0,0 +1,7 @@
+# EdgeFade
+
+A non-interactive gradient cue that content continues beneath an edge.
+
+Place it inside a relatively positioned scroll container and select the
+matching `edge`. It never replaces a visible scrollbar or keyboard scrolling.
+Keep the fade subtle and omit it when content boundaries are already obvious.