@moldable-ai/ui 0.2.21 → 0.2.22

package/docs/visual-regression.md

@@ -0,0 +1,78 @@
+# Visual and accessibility regression
+
+The phase 1 runner exercises every authored story in the core component
+catalog. It does not start the desktop shell or any Moldable-managed app.
+
+## What runs
+
+`visual-host/` is a small Vite entry that renders one story at a time:
+
+```text
+?story=controls/button&theme=dark&width=360
+```
+
+Unique bare story ids are also accepted. Optional
+`transparency=reduced` and `contrast=increased` parameters set the same
+manual accessibility attributes used by the catalog. The host bundles Inter
+and Roboto Mono, waits for `document.fonts.ready`, and disables animations,
+transitions, scrolling, and the caret under `data-motion="reduced"`.
+
+The Playwright runner builds and serves that static host, blocks non-host
+network requests, freezes time and randomness, and tests Chromium at:
+
+- light and dark themes;
+- 360 × 720 and 960 × 720 viewports;
+- rest plus the browser-driven states declared by an exemplar story.
+
+A story opts into browser-driven states with `liveStates` and marks exactly
+one element:
+
+```tsx
+<Button data-state-target="hover focus pressed">Continue</Button>
+```
+
+Playwright performs real hover, focus, and held-pointer interactions on that
+element. Button, segmented control, and toggle stories are the phase 1
+exemplars.
+
+Every captured case also receives an axe WCAG 2 A/AA and WCAG 2.1 A/AA scan.
+Serious and critical violations fail. Per-story suppressions belong in
+`visual-tests/visual-matrix.ts` and must include a reason. Global
+suppressions are intentionally unsupported.
+
+## Local commands
+
+Install the pinned Chromium build once:
+
+```bash
+pnpm -C packages/ui exec playwright install chromium
+```
+
+Run against committed baselines:
+
+```bash
+pnpm -C packages/ui test:visual
+```
+
+Create or intentionally update baselines after reviewing the UI change:
+
+```bash
+pnpm -C packages/ui test:visual:update
+```
+
+Baseline PNGs live in `visual-tests/baselines/`. Failures emit actual,
+expected, diff, and trace artifacts in the gitignored `.visual-results/`
+directory.
+
+## Determinism and skips
+
+Stories must use fixed inputs and no live data, network, wall-clock timers, or
+unseeded randomness. Add an unavoidable phase 1 skip to
+`deterministicStorySkips` in `visual-tests/visual-matrix.ts` with a specific
+reason. Skips are reported in the runner summary; silent conditional skips
+are not allowed.
+
+## CI
+
+The `ui-regression` CI job installs Chromium and its Linux dependencies,
+builds only `@moldable-ai/ui`, then runs the combined visual and axe suite.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moldable-ai/ui",
-  "version": "0.2.21",
+  "version": "0.2.22",
   "description": "Shared UI components for Moldable applications",
   "author": "Desiderata LLC",
   "license": "SEE LICENSE IN LICENSE",
@@ -42,11 +42,15 @@
   ],
   "scripts": {
     "build": "tsc",
+    "build:visual-host": "vite build --config vite.visual.config.ts",
     "dev": "tsc --watch",
     "lint": "eslint . --ext .ts,.tsx --max-warnings 0",
     "format": "prettier --write . --ignore-path ../../.prettierignore",
-    "check-types": "tsc --noEmit",
-    "test": "vitest run"
+    "check-types": "tsc --noEmit && tsc --noEmit -p tsconfig.visual.json",
+    "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",
+    "visual:serve": "vite preview --config vite.visual.config.ts --host 127.0.0.1 --port 4179 --strictPort"
   },
   "dependencies": {
     "@base-ui/react": "^1.1.0",
@@ -105,14 +109,19 @@
     "zod": "^4.3.5"
   },
   "devDependencies": {
+    "@axe-core/playwright": "^4.12.1",
+    "@fontsource/inter": "^5.3.0",
+    "@fontsource/roboto-mono": "^5.3.0",
     "@moldable-ai/eslint-config": "workspace:*",
     "@moldable-ai/prettier-config": "workspace:*",
     "@moldable-ai/typescript-config": "workspace:*",
+    "@playwright/test": "^1.62.0",
     "@types/node": "^24.0.3",
     "@types/react": "^19.1.6",
     "@types/react-dom": "^19.1.6",
     "jsdom": "^26.1.0",
     "typescript": "^5.8.3",
+    "vite": "^6.4.3",
     "vitest": "^4.1.8"
   },
   "peerDependencies": {

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

@@ -25,6 +25,33 @@ shown. The default error deliberately avoids exposing internal details.
 host safe area. Use `AlertDialogBody` when explanation or affected-item content
 can grow. Keep the consequence visible while the action is pending.
 
+For composed alert dialogs, put `loading` on `AlertDialogAction` while its
+request is in flight. This forwards the standard `Button` busy state, blocks
+duplicate activation, and preserves the action label width and accessible name.
+Use `pending` with `pendingLabel` when maintaining the confirmation-specific
+status-label pattern; `ConfirmDialog` manages that state automatically. Disable
+the surrounding form only when its other controls must not change during the
+request.
+
+Mark one confirming action with `primary` to enable Command+Enter on macOS or
+Control+Enter on other platforms. The shortcut does not run without a marked
+action, while that action is loading or disabled, during key composition or
+repeat, or when a focused control consumes the event with `preventDefault()`.
+Plain Enter remains native and Escape remains the Radix cancel behavior.
+
+```tsx
+<AlertDialogFooter>
+  <span className="text-muted-foreground mr-auto inline-flex items-center gap-1 text-xs">
+    Confirm <Kbd>⌘</Kbd>
+    <Kbd>Enter</Kbd>
+  </span>
+  <AlertDialogCancel>Cancel</AlertDialogCancel>
+  <AlertDialogAction primary loading={isDeleting}>
+    Delete recording
+  </AlertDialogAction>
+</AlertDialogFooter>
+```
+
 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

package/src/components/ui/button.md

@@ -25,9 +25,15 @@ import { RefreshCw } from 'lucide-react'
 >
   <RefreshCw />
 </Button>
+
+<Button type="submit" loading={isSaving}>
+  Save changes
+</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.
+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. Set `loading` while that button's async action is in flight. The button blocks pointer and keyboard activation, exposes `aria-busy`, keeps its accessible label mounted, and centers a width-stable spinner.
+
+Use `loading` for the action that started the request. Disable the whole form only when editing during the request would be unsafe or would invalidate the submitted payload; do not disable unrelated controls merely to communicate progress.
 
 For links that should look like buttons:
 
@@ -42,13 +48,14 @@ For links that should look like buttons:
 - `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.
+- `loading`: blocks activation, applies disabled behavior and `aria-busy`, and overlays the shared `Spinner` without unmounting or resizing the label. Defaults to `false`.
 - 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.
+- Add `cursor-pointer`; use the real `disabled` attribute for unavailable actions and `loading` for an in-flight action.
 - 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.
@@ -60,7 +67,7 @@ For links that should look like buttons:
 - 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 use `disabled` alone as the progress signal; use `loading` so progress is announced and the label width stays stable.
 - Do not hide essential actions behind hover-only icon buttons.
 
 ## Moldable considerations

package/src/components/ui/dialog.md

@@ -18,7 +18,15 @@ spatial context.
       <DialogDescription>Update the selected record.</DialogDescription>
     </DialogHeader>
     <DialogBody>{/* the only scrolling region */}</DialogBody>
-    <DialogFooter>{/* actions remain reachable */}</DialogFooter>
+    <DialogFooter>
+      <span className="text-muted-foreground mr-auto inline-flex items-center gap-1 text-xs">
+        Save <Kbd>⌘</Kbd>
+        <Kbd>Enter</Kbd>
+      </span>
+      <DialogAction primary loading={isSaving} onClick={saveChanges}>
+        Save changes
+      </DialogAction>
+    </DialogFooter>
   </DialogContent>
 </Dialog>
 ```
@@ -30,9 +38,20 @@ 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.
+Use `DialogAction` for footer commands that need the standard async and keyboard
+contracts. Its `loading` prop forwards to `Button`, preventing duplicate
+activation while retaining the label width and accessible name. Keep the dialog
+controlled, show inline field errors, and close only after success. Disable the
+whole form only when edits during submission would be unsafe. Use
+`ConfirmDialog` when confirmation is the entire workflow.
+
+Set `primary` on at most one `DialogAction` to opt into the default-action
+shortcut. Command+Enter activates it on macOS; Control+Enter does so on other
+platforms. The shortcut works from anywhere in the dialog unless a focused
+control consumes the key event with `preventDefault()`, or the primary action is
+loading or disabled. Plain Enter keeps the focused control's native behavior.
+Use `Kbd` to show the shortcut when it improves discovery; render the
+platform-appropriate modifier in app code.
 
 Every dialog needs a `DialogTitle`. Add `DialogDescription` when the outcome or
 scope is not obvious. Escape, outside dismissal, initial focus, and focus return

package/src/components/ui/error-boundary-view.md

@@ -0,0 +1,98 @@
+# ErrorBoundaryView
+
+`ErrorBoundaryView` presents a compact recovery state without owning error
+catching, reporting, or host policy.
+
+## When to use
+
+Use it as the renderer for a React error boundary, route-level failure, or
+host-provided pane error. Supply `actions` when the host owns reporting,
+navigation, or chat recovery.
+
+## When not to use
+
+Do not use it for inline field validation, routine empty states, or transient
+request failures that can stay beside the initiating control. It does not catch
+errors itself; use `AppErrorBoundary` when the package should own catching and
+Moldable reporting.
+
+## Anatomy
+
+The view contains one compact surface with a title, optional message, optional
+error-details disclosure, and one action row. It does not add illustrations or
+nested cards.
+
+## Usage
+
+```tsx
+import { ErrorBoundaryView } from '@moldable-ai/ui'
+
+function PaneError() {
+  return (
+    <ErrorBoundaryView
+      title="Could not load this pane"
+      message="Retry the request or report the captured error."
+      details={error.stack}
+      onRetry={retry}
+      actions={
+        <Button type="button" variant="secondary" onClick={reportError}>
+          Report error
+        </Button>
+      }
+    />
+  )
+}
+```
+
+## Variants and sizes
+
+The renderer has one responsive layout. It uses the available height in a pane
+and can fill a window when its parent gives it full height. The content remains
+bounded to a readable width.
+
+## API
+
+- `title`: heading content. Defaults to `"Something went wrong"`.
+- `message`: optional supporting copy.
+- `details`: optional string shown in a collapsed disclosure with a bounded,
+  scrollable monospace region.
+- `onRetry`: when supplied, renders a `Retry` button and calls the handler once
+  per activation.
+- `actions`: optional host-provided action content rendered after Retry.
+- `className`: optional classes merged onto the outer renderer.
+
+## States and interaction
+
+Omit `details` when there is no safe diagnostic text to show. Omit both
+`onRetry` and `actions` for a read-only failure. Keep retry state in the caller
+and pass `loading` to a custom action when retrying is asynchronous.
+
+## Keyboard and accessibility
+
+The details use native `details` and `summary` semantics. The title is the
+surface heading, the Retry control keeps native button behavior, and diagnostic
+text remains selectable.
+
+## Platform behavior
+
+The component has no host calls or platform branches. `AppErrorBoundary`
+supplies Moldable-specific reload and chat-prefill actions.
+
+## Do
+
+- Keep the title calm and literal.
+- Give the message a concrete recovery path.
+- Redact secrets before passing diagnostic details.
+- Use semantic theme tokens in custom actions.
+
+## Don't
+
+- Do not add decorative error art or nested cards.
+- Do not put binary data or unbounded logs in `details`.
+- Do not make this presentational component report or reload implicitly.
+
+## Testing
+
+Contract tests should verify copy, disclosure behavior, Retry activation, and
+host action rendering. Error-catching and reporting tests belong to the owning
+boundary.