@moldable-ai/ui 0.2.20 → 0.2.21

package/docs/adaptive-materials.md

@@ -0,0 +1,79 @@
+# Adaptive materials
+
+Moldable uses restrained translucent material to separate controls and
+navigation from the content they operate on. Material frames content; it does
+not replace content surfaces.
+
+## Roles
+
+Use `regular` material for normal toolbar and window chrome, grouped controls,
+menus, and temporary control overlays. It provides enough frosting for text
+and icons to remain stable as content moves behind it.
+
+Use `clear` material only for compact controls floating over photos, maps,
+video, or another richly colored canvas. Check the control against the
+lightest, darkest, and busiest content it can cover. If contrast is not stable,
+use `regular`.
+
+Documents, calendars, tables, forms, cards, sheets, inspectors, and primary
+working canvases remain opaque. Do not stack translucent content cards to
+create hierarchy.
+
+## Components
+
+`Material` applies one adaptive surface:
+
+```tsx
+<Material asChild variant="clear" shape="circle" interactive>
+  <IconButton label="Center map" variant="ghost">
+    <Locate />
+  </IconButton>
+</Material>
+```
+
+`MaterialGroup` applies one sampled layer to a related cluster:
+
+```tsx
+<MaterialGroup variant="regular" shape="capsule" spacing="compact">
+  <IconButton label="Previous" variant="ghost">
+    <ChevronLeft />
+  </IconButton>
+  <IconButton label="Next" variant="ghost">
+    <ChevronRight />
+  </IconButton>
+</MaterialGroup>
+```
+
+Children of a `MaterialGroup` should be ordinary transparent or ghost
+controls. Do not apply another `Material` to every child. A single grouped
+sampler produces clearer hierarchy and avoids accumulated blur.
+
+`Toolbar`, `AppFrameTitlebar`, and `AppFrameStatusbar` expose a `material`
+property. Their normal chrome uses `regular`; pass `material="none"` for an
+opaque or transparent composition that supplies its own surface.
+
+## Fallback behavior
+
+Every material starts from an opaque fallback. Translucent sampling is enabled
+only when the renderer supports backdrop filtering.
+
+- Reduced transparency uses opaque fills and removes blur and saturation.
+- Increased contrast makes fills more opaque and strengthens borders.
+- Forced colors use system surfaces and borders without blur or shadows.
+- Reduced motion removes material press transforms.
+
+The manual `data-transparency="reduced"`, `data-contrast="increased"`, and
+`data-motion="reduced"` attributes mirror system preferences for deterministic
+catalog and app testing.
+
+Do not animate blur, saturation, or backdrop filters. They are expensive,
+visually noisy, and difficult to make accessible. Limit the number of visible
+sampled layers and avoid nesting them.
+
+## Host boundary
+
+CSS material samples content inside the app renderer. It cannot sample the
+desktop behind a native window. Native behind-window material, window
+transparency, active-window appearance, and energy policy remain host-owned
+capabilities. Apps should use the same semantic variants regardless of which
+adapter renders them.

package/docs/app-anatomy.md

@@ -9,7 +9,9 @@ canvas independent of the desktop shell.
 ```tsx
 <AppFrame>
   <AppFrameTitlebar>
-    <AppFrameToolbar>{/* title, view controls, primary actions */}</AppFrameToolbar>
+    <AppFrameToolbar>
+      {/* title, view controls, primary actions */}
+    </AppFrameToolbar>
   </AppFrameTitlebar>
   <AppFrameContent scrollable={false}>
     {/* app-owned canvas and panes */}

package/docs/component-catalog.md

@@ -20,6 +20,7 @@ const manifest = createCatalogManifest({
         {
           id: 'primary-action',
           title: 'Primary action',
+          components: ['button'],
           interactions: ['rest', 'focus-visible', 'disabled', 'loading'],
           render: ({ interaction }) => (
             <Button
@@ -45,6 +46,8 @@ Every public interactive component should cover:
 - light and dark themes;
 - regular and compact density;
 - wide and narrow viewports;
+- standard accessibility behavior plus reduced transparency, increased
+  contrast, and reduced motion where material or motion is part of the recipe;
 - rest, focus-visible, disabled, invalid, selected, loading, and empty states
   where those states apply;
 - keyboard behavior in unit tests.
@@ -54,6 +57,26 @@ lets a visual-regression runner capture one addressable case at a time. Keep
 catalog stories deterministic: fixed content, fixed dates, no network calls,
 and no animation unless motion itself is under review.
 
-The included `coreComponentCatalog` is a smoke foundation, not the complete
-acceptance bar. Add each new public component and its meaningful states as part
-of the same change that adds the component.
+Accessibility environments are opt-in per story through
+`accessibilityModes`. Standard cases preserve the existing case ID; a
+nonstandard mode is appended as the final segment. The catalog maps those
+modes to deterministic `data-transparency`, `data-contrast`, and `data-motion`
+attributes.
+
+## Public component accountability
+
+Every story declares the public visual component modules it exercises through
+`components`. The core catalog test reads the barrel exports from
+`components/ui/index.ts` and requires every module to be either:
+
+- named by at least one deterministic story; or
+- listed in `coreCatalogExclusions` with a concise reason.
+
+Exclusions are visible debt, not permanent exemptions. Remove an exclusion in
+the same change that adds representative stories. Unknown component ids, stale
+exclusions, duplicate exclusions, and empty reasons fail the catalog test.
+
+The core catalog covers window materials, semantic controls, collections,
+navigation, representative popover material, and feedback recipes. Complex
+portals and geometry-dependent components remain explicitly deferred until an
+isolated browser fixture can make their states deterministic.

package/docs/design-tokens.md

@@ -119,15 +119,28 @@ related objects visually consistent. `rounded-window` is host-informed and
 normally only useful in previews; the native host owns the actual window
 shape.
 
-Material tokens keep depth and translucency restrained:
+Adaptive material has two semantic variants. Each includes fill, fallback,
+border, highlight, blur, and saturation tokens:
 
-- `--material-blur-toolbar` and `--material-blur-overlay`
-- `--material-saturation`
-- `shadow-panel`, `shadow-overlay`, and `shadow-window`
+- `--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.
+
+Use `Material` and `MaterialGroup` instead of assembling those tokens in app
+markup. `MaterialGroup` owns one sampled layer for a related control cluster;
+its children must not add nested material.
 
 Translucency must have an opaque fallback. The token system removes blur and
 uses opaque toolbar and overlay surfaces when the operating system requests
 reduced transparency or an ancestor has `data-transparency="reduced"`.
+Unsupported renderers stay on the same opaque fallback. Increased contrast
+makes fills more opaque and strengthens their borders.
+
+Material is a control and navigation affordance. Primary canvases, documents,
+tables, calendars, forms, cards, sheets, and inspectors remain opaque. See
+[Adaptive materials](./adaptive-materials.md) for composition rules.
 
 ## Motion
 

package/docs/foundations.md

@@ -37,9 +37,11 @@ Status color communicates status only; it is not decoration.
 Use semantic tokens only. Do not introduce raw gray, zinc, white, or black
 classes in app UI.
 
-Use material tokens for translucency and elevation. Materials distinguish
-canvas, toolbar, sidebar, raised, recessed, and overlay roles; they are not
-decorative glass effects.
+Use adaptive material only for navigation and control layers. Regular material
+supports toolbars and grouped controls; clear material is reserved for compact
+controls over media. Content canvases and content-bearing surfaces stay
+opaque. Group related controls under one sampler and never nest material
+effects.
 
 ## Motion
 

package/docs/standalone-app-windows.md

@@ -41,6 +41,14 @@ the document root. Composite content insets then resolve automatically. The
 transport used to deliver those values belongs to the host integration layer,
 not individual apps.
 
+Dedicated windows use the host titlebar by default. An app with a unified
+toolbar can declare `{ "window": { "titlebar": "app" } }` in `moldable.json`.
+In that mode the host removes its strip and advertises the titlebar height and
+leading window-control inset. `AppFrameTitlebar` consumes those values, sends
+`startWindowDrag` on a non-interactive pointerdown, and sends
+`titlebarDoubleClick` on a non-interactive double-click. The latter toggles
+maximize as a cross-platform approximation of the macOS titlebar zoom action.
+
 Window appearance roles are `--window-chrome-background`,
 `--window-chrome-foreground`, `--window-chrome-muted-foreground`,
 `--window-border`, and `--material-shadow-window`. The host may update the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moldable-ai/ui",
-  "version": "0.2.20",
+  "version": "0.2.21",
   "description": "Shared UI components for Moldable applications",
   "author": "Desiderata LLC",
   "license": "SEE LICENSE IN LICENSE",
@@ -80,7 +80,6 @@
     "@radix-ui/react-toggle": "^1.1.10",
     "@radix-ui/react-toggle-group": "^1.1.11",
     "@radix-ui/react-tooltip": "^1.2.8",
-    "@shadcn/react": "^0.2.1",
     "@tailwindcss/typography": "^0.5.16",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

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

@@ -2,7 +2,9 @@
 
 ## Purpose
 
-`Alert` presents an important inline message that belongs to the current surface. Use it for recoverable errors, permission or connection problems, and information the user should notice before continuing.
+`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.
 
@@ -12,23 +14,42 @@ Use `AlertDialog` when the user must confirm an action. Use `Empty` for the norm
 import { CircleAlert } from 'lucide-react'
 import { Alert, AlertDescription, AlertTitle } from '@moldable-ai/ui'
 
-;<Alert variant="destructive">
+;<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>
 ```
 
-An alert can include a compact retry or setup action in its description, but the message should still stand on its own. Place the action close to the cause rather than at the top of the whole app.
+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
 
-- `Alert`: a `div` with `role="alert"`.
-- `variant`: `default` or `destructive`; defaults to `default`.
+- `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.
 
@@ -44,9 +65,10 @@ An alert can include a compact retry or setup action in its description, but the
 
 - Do not use an alert as decorative introductory copy.
 - Do not show stack traces, raw exceptions, or secret values.
-- Do not use `destructive` for neutral notices.
+- 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
 

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

@@ -21,6 +21,9 @@ surface.
 - 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
@@ -31,3 +34,5 @@ surface.
   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/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/combobox.md

@@ -40,4 +40,3 @@ state, clear/trigger controls, and the chips family for multi-value input.
 - 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

@@ -9,7 +9,7 @@
 ```tsx
 import { DateField } from '@moldable-ai/ui'
 
-<DateField
+;<DateField
   aria-label="Due date"
   value={dueDate}
   min="2026-01-01"

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/empty.md

@@ -20,7 +20,7 @@ import {
   EmptyTitle,
 } from '@moldable-ai/ui'
 
-;<Empty className="pb-[calc(var(--chat-safe-padding,0px)+2rem)]">
+;<Empty variant="pane" safeBottom>
   <EmptyHeader>
     <EmptyMedia variant="icon">
       <Database />
@@ -52,6 +52,9 @@ For a successful zero state, omit the action when there is nothing useful to do:
 ## API summary
 
 - `Empty`: centered flex container for the complete state.
+- `Empty variant`: `compact`, `pane`, or `full`; defaults to `pane`.
+- `Empty safeBottom`: adds host-provided chat clearance. Do not enable it when
+  an owning `AppFrameContent` or parent scroll region already applies clearance.
 - `EmptyHeader`: groups media, title, and description.
 - `EmptyMedia`: `variant="default"` or `variant="icon"`.
 - `EmptyTitle`: primary label.
@@ -65,7 +68,7 @@ For a successful zero state, omit the action when there is nothing useful to do:
 - Show one primary setup action when the state is blocked.
 - Distinguish first-run, filtered-zero, permission, and successful-zero states.
 - Keep the app’s normal shell or pane structure visible.
-- Add chat-safe padding when the empty state occupies a pane that reaches the bottom.
+- Use `safeBottom` when the empty state itself owns a pane that reaches the bottom.
 
 ## Don't
 
@@ -79,4 +82,6 @@ For a successful zero state, omit the action when there is nothing useful to do:
 
 An empty state should feel like part of a local instrument, not a landing page. Keep it visually small even when centered. If the desktop chat can resolve the state, provide specific app context or an explicit “Ask Moldable about this” affordance that prefills desktop chat; do not add another chat box.
 
-For scrollable panes, use enough bottom padding to remain visible above chat, commonly `pb-[calc(var(--chat-safe-padding,0px)+1rem)]` or more when a fixed dock is present.
+For scrollable panes, prefer `safeBottom` on the owning `ScrollArea`. Apply it
+to `Empty` only when the empty state is the owner, so nested states do not add
+the same safe area twice.

package/src/components/ui/grid.md

@@ -18,7 +18,7 @@ import {
   GridItemTitle,
 } from '@moldable-ai/ui'
 
-<Grid
+;<Grid
   aria-label="Artifacts"
   columns={3}
   selectionMode="single"
@@ -56,14 +56,18 @@ Prefer changing this value at deliberate window breakpoints. A smaller window sh
 
 ## Interaction contract
 
-- Arrow Left/Right moves one tile.
-- Arrow Up/Down moves by `columns`.
-- Home and End move to the first and last available tile.
+- Arrow Left/Right moves within the current row and stops at its edge.
+- Arrow Up/Down moves within the current column and stops at its edge.
+- Home and End move to the first and last available tile in the current row.
+- Control/Command + Home and End move to the first and last available tile in
+  the entire grid.
 - Space changes selection.
 - Enter changes selection and invokes `onAction`.
 - A single pointer click changes selection. A double click invokes `onAction`.
 - Disabled tiles are skipped.
 - Buttons and links inside a tile preserve their own pointer behavior.
+- When the grid first mounts, the first selected, enabled tile receives the
+  roving tab stop. If nothing is selected, the first enabled tile receives it.
 
 ## API summary
 

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

@@ -7,10 +7,10 @@
 ## Usage
 
 ```tsx
-import { IconButton } from '@moldable-ai/ui'
 import { RefreshCw } from 'lucide-react'
+import { IconButton } from '@moldable-ai/ui'
 
-<IconButton
+;<IconButton
   label="Refresh events"
   tooltip
   size="sm"