@moldable-ai/ui 0.2.29 → 0.2.32

package/docs/macos-design-audit.md

@@ -0,0 +1,144 @@
+# macOS design audit for Moldable UI
+
+Status: active  
+Target: macOS desktop apps rendered in Moldable-owned Tauri windows  
+Scope: `@moldable-ai/ui`, app-owned titlebars, and the Moldable UI catalog
+
+This audit treats macOS AppKit and SwiftUI behavior as the semantic reference
+while allowing a React implementation. The goal is not to copy source pixels.
+The goal is to preserve macOS hierarchy, density, control roles, window
+behavior, input behavior, and accessibility expectations.
+
+## Reference baseline
+
+- Foundations: Typography — Ensuring legibility, Conveying hierarchy, Using
+  system fonts, Platform considerations/macOS
+- Foundations: Layout — Visual hierarchy, Adaptability, Platform
+  considerations/macOS
+- Foundations: Materials — Liquid Glass, Standard materials, Platform
+  considerations/macOS
+- Foundations: Color — Best practices, Inclusive color, System colors
+- Foundations: Dark Mode — Best practices, Platform considerations/macOS
+- Foundations: Accessibility — Vision, Mobility, Cognitive
+- Foundations: Icons — Best practices, Platform considerations/macOS
+- Foundations: Motion — Best practices, Providing feedback
+- Platforms: Designing for macOS — Best practices
+- Layout: Sidebars, Split views, Windows, Lists and tables
+- Menus: Toolbars — Titles, Navigation, Actions, Item groupings,
+  Platform considerations/macOS
+- Menus: Buttons — Style, Content, Role, Platform considerations/macOS
+- Controls: Toggles, Segmented controls, Text fields
+- Search: Search fields — Best practices, Platform considerations/iPadOS,
+  macOS
+
+## Severity-ranked findings
+
+### P0 — window and navigation semantics
+
+1. App-owned titlebars must preserve the native traffic-light exclusion area,
+   a draggable noninteractive region, double-click window behavior, and usable
+   interactive controls. `Toolbar`, the desktop host, and window metadata must
+   be tested together; CSS alone cannot guarantee this contract.
+2. Toolbar titles must identify the current view or document, not repeat the
+   application name. App identity belongs to the window and system surfaces.
+3. Back controls must call Moldable navigation and expose the same action to
+   keyboard and menu commands. A decorative chevron is not navigation.
+
+### P1 — hierarchy and control roles
+
+1. Use a sidebar or tab view for top-level destinations. A segmented control is
+   for a small set of closely related modes that affect one view, not primary
+   app navigation.
+2. Keep only frequent actions in a toolbar. Put infrequent actions in a More
+   menu and mirror every command in the macOS menu bar.
+3. Group only controls that are logically related. Standalone navigation
+   controls should usually be quiet; groups may own one shared capsule.
+4. Use the system appearance by default. An appearance selector is appropriate
+   in a component test harness, but not as persistent application chrome.
+5. Prefer compact macOS typography: 13 px body, 15–16 px titles, 18 px section
+   headings, and 24 px display headings. Avoid web-dashboard hero sizing in
+   ordinary desktop panes.
+6. Prefer flat content hierarchy, separators, and selection fills over nested
+   bordered cards and repeated shadows. Materials belong to navigation and
+   transient controls, not every content surface.
+7. Use switches for immediate, emphasized binary settings. Use checkboxes for
+   ordinary grouped preferences and radio buttons for mutually exclusive
+   choices.
+
+### P2 — desktop completeness
+
+1. Extend the existing resizable `SplitView` with a documented collapsible
+   recipe, restoration, and automatic narrow-window collapse.
+2. Add table column resizing, sorting, optional alternating row backgrounds,
+   keyboard range selection, and state restoration.
+3. Extend command metadata so toolbar items, menus, keyboard shortcuts,
+   accessibility labels, and disabled state can share one source of truth.
+4. Separate semantic action roles from visual button variants and cover
+   default, cancel, destructive, help, disclosure, toolbar, and icon-only
+   actions.
+5. Validate at increased contrast, reduced transparency, reduced motion,
+   keyboard-only input, 200% zoom, and light/dark appearances.
+
+## Current conformance
+
+The shared package already provides:
+
+- semantic light and dark colors instead of raw app-specific grays;
+- a system-font stack and compact macOS-oriented type tokens;
+- labeled icon buttons with visible keyboard focus;
+- reduced-motion and reduced-transparency fallbacks;
+- explicit status text in addition to color;
+- titlebar insets and window drag handlers for app-owned top toolbars;
+- compact, regular, and comfortable density tokens;
+- a distinct accent-colored `prominent` button role for the single key action
+  in a view, without changing the appearance of existing default buttons.
+
+The Moldable UI catalog now demonstrates:
+
+- top-level source-list navigation in the sidebar;
+- current-view toolbar titles;
+- quiet standalone toolbar navigation;
+- preview-only appearance and accessibility controls;
+- flatter stages, fewer shadows, and smaller radii;
+- package typography tokens instead of oversized page-specific values.
+
+## Component acceptance criteria
+
+### Toolbar
+
+- Uses the current view or document title.
+- Preserves native window-control clearance in app-owned windows.
+- Dragging works from every noninteractive toolbar region.
+- Interactive descendants never initiate a window drag.
+- Frequent actions are visible; rare actions are in More.
+- Related actions share a group; unrelated actions do not.
+- Commands have labels, tooltips when helpful, shortcuts, menu equivalents,
+  disabled states, and tests.
+
+### Sidebar and split view
+
+- Selection is persistent and visually unambiguous.
+- Search filters the sidebar content it sits above.
+- Sidebar width is resizable within reasonable minimum and maximum values.
+- The sidebar can collapse automatically in a narrow window and manually at
+  any size.
+- The divider remains subtle and the sidebar doesn’t compete with content.
+
+### Controls
+
+- Labels describe outcomes, not implementation.
+- The default action is visually prominent only when the context needs one.
+- Destructive actions are explicit and separated from routine actions.
+- Icons use familiar system metaphors and never carry meaning without an
+  accessible label.
+- Controls remain operable with keyboard, pointer, VoiceOver, increased
+  contrast, reduced transparency, and reduced motion.
+
+## Review policy
+
+Every new public visual primitive must include catalog stories for light and
+dark appearance, compact and regular density, wide and narrow viewport,
+rest/focus/disabled/invalid states where applicable, and accessible naming.
+Every window-chrome change must be verified in a real Moldable-owned macOS
+window because embedded browser rendering cannot validate traffic-light
+placement or native dragging.

package/docs/native-integration.md

@@ -16,10 +16,10 @@ Do not create UI-only no-op stubs for native menus, share sheets, or date
 pickers. First define ownership, cancellation, errors, replay/reconnect
 behavior, and platform fallbacks.
 
-`DateField` is the portable renderer baseline. A future system date picker,
-share sheet, or native menu must only be selected after the host advertises the
-service through a versioned context. Requests must remain bound to the
-originating app window and user activation.
+`DateField`, renderer menus, and browser file/share controls remain the
+portable baselines. The package currently exposes host-advertised date/time
+picker, share, native-menu, and file-dialog services with renderer fallbacks.
+Requests remain bound to the originating app window and user activation.
 
 Standalone windows should remain host-owned surfaces around an app frame. Do
 not load arbitrary app URLs directly into a privileged native webview merely to

package/docs/platform-architecture.md

@@ -0,0 +1,189 @@
+# Moldable UI platform architecture
+
+## Goal
+
+Moldable applications use one stable UI contract while platform packs provide
+versioned operating-system measurements and recipes.
+
+```text
+immutable platform pack
+  → Moldable semantic adapter
+    → stable Moldable component API
+      → optional Moldable brand overrides
+        → app composition
+```
+
+The current complete reference pack is `macos-27`. A partial `macos-26`
+source module supplies the floating-sidebar recipe. Future packs can include
+a newer macOS release, Windows, or a platform-neutral web fallback without
+requiring apps to import version-specific tokens.
+
+## Immutable platform packs
+
+A platform pack contains factual source data only:
+
+- semantic colors and appearance modes;
+- typography metrics;
+- control sizes, geometry, and state recipes;
+- window, toolbar, menu, sidebar, and overlay measurements;
+- material recipes and capability requirements;
+- accessibility and native-host adaptations.
+
+Published pack values never change in place. Corrections create a package
+patch with an audit note; a new operating-system release gets a new pack.
+Platform packs contain no artwork, images, icon paths, screenshots, fonts, or
+copied component implementations.
+
+Private source variables use a versioned namespace such as
+`--m27-source-*` or `--m26-source-*` and are scoped to the source version:
+
+```css
+[data-ui-platform='macos'][data-ui-platform-version='27']
+```
+
+This allows multiple packs to ship together without variable collisions.
+
+Partial source modules do not become complete platform packs until they cover
+the full stable contract. They can still contribute a deliberately versioned
+component recipe, such as the macOS 26 floating sidebar.
+
+## Stable Moldable contract
+
+Applications and universal components consume only `--m-ui-*` recipe tokens
+and stable React props. They never read versioned `--m*-source-*` variables
+directly.
+
+Examples:
+
+```css
+--m-ui-color-text-primary
+--m-ui-color-accent
+--m-ui-control-height
+--m-ui-button-radius
+--m-ui-toolbar-control-height
+--m-ui-menu-item-height
+```
+
+Each platform adapter maps its immutable source values to this contract. A
+Moldable theme may then deliberately override a documented subset of semantic
+roles, but cannot mutate the platform-pack source.
+
+## Runtime selection
+
+`ThemeProvider` resolves independent axes:
+
+```ts
+<ThemeProvider
+  platform="macos"
+  platformVersion="27"
+  uiTheme="moldable"
+  sidebarStyle="floating"
+  appearance="system"
+  controlSize="medium"
+/>
+```
+
+The resolved document attributes are:
+
+```html
+<html
+  data-ui-platform="macos"
+  data-ui-platform-version="27"
+  data-ui-platform-pack="macos-27"
+  data-ui-sidebar-style="floating"
+  data-ui-theme="moldable"
+  data-ui-appearance="dark"
+  data-control-size="medium"
+></html>
+```
+
+Unsupported platform/version requests resolve to the explicit web fallback
+pack rather than silently borrowing the latest macOS values.
+
+## Independently selectable component recipes
+
+An application can use one base platform pack while opting a component family
+into a different, compatible anatomy. Public API names describe the result,
+not the source OS version:
+
+| `sidebarStyle` | Anatomy                                              | Immutable source       |
+| -------------- | ---------------------------------------------------- | ---------------------- |
+| `platform`     | Follow the selected base platform                    | Selected platform pack |
+| `floating`     | Inset glass shell with independent radius and shadow | macOS 26               |
+| `edge-to-edge` | Sidebar joined to the window/content edge            | macOS 27               |
+
+The macOS 27 edge-to-edge anatomy does not draw a standalone divider or
+material background around the sidebar. The sidebar reveals the app/window
+canvas beneath it, so each app can choose a plain color, image, or other
+background for the whole composition. The hairline follows only the outer
+window perimeter.
+
+For an app-wide choice:
+
+```tsx
+<ThemeProvider platform="macos" platformVersion="27" sidebarStyle="floating" />
+```
+
+For a single sidebar:
+
+```tsx
+<Sidebar sidebarStyle="edge-to-edge">{/* … */}</Sidebar>
+```
+
+`SIDEBAR_STYLES` is the registry boundary that records the source platform and
+version for each semantic recipe. Components resolve stable
+`--m-ui-sidebar-*` tokens and never branch on version numbers.
+
+## Component strategy
+
+### Universal components
+
+Use one component when semantics and interaction behavior are shared:
+
+- button, checkbox, radio group, switch;
+- text, search, and number fields;
+- slider, segmented control, progress;
+- table, form, dialog, popover, tooltip;
+- toolbar composition and command models.
+
+Their DOM behavior remains accessible and platform-neutral. Platform recipes
+control geometry and presentation.
+
+### Platform adapters
+
+Use a thin adapter when native ownership or interaction differs:
+
+- native menu-bar integration;
+- window controls and draggable titlebar regions;
+- system file, color, date, sharing, and permission dialogs;
+- native materials and backdrop capabilities;
+- platform keyboard shortcuts and pointer conventions.
+
+The app imports the stable Moldable API. The provider/host selects the adapter.
+
+### Version-specific implementations
+
+Only create a version-specific component when CSS recipe changes cannot express
+the difference in semantics or anatomy. Keep the version branch at the
+registry boundary:
+
+```ts
+const windowChrome = platformRegistry.resolve({
+  platform: 'macos',
+  version: '27',
+  capability: 'windowChrome',
+})
+```
+
+Do not scatter checks such as `if (macOSVersion >= 27)` through components.
+
+## Catalog contract
+
+The core component catalog shows resolved stable components and their state,
+appearance, density, viewport, accessibility, and native-capability matrices.
+The Moldable UI showcase owns raw platform-pack reference pages and
+platform/version comparisons. Explicit Moldable overrides remain separately
+identifiable in both surfaces.
+
+Together these surfaces keep OS fidelity, Moldable design decisions, and
+compatibility behavior independently reviewable.

package/docs/standalone-app-windows.md

@@ -50,6 +50,43 @@ leading window-control inset. A top `Toolbar` consumes those values, sends
 maximize as a cross-platform approximation of the macOS titlebar zoom action.
 Interactive descendants are automatically excluded from dragging.
 
+Native behind-window material is also app-scoped and default-off. The native
+host must know about background, titlebar, and sidebar requests before creating
+the window, so apps declare them in `moldable.json`:
+
+```json
+{
+  "window": {
+    "titlebar": "host",
+    "nativeMaterial": {
+      "background": true,
+      "titlebar": true,
+      "sidebar": true
+    }
+  }
+}
+```
+
+For renderer-owned background and sidebar material, the shared frame must opt
+in too:
+
+```tsx
+<AppFrame nativeMaterial={{ background: true, sidebar: true }}>
+  <SidebarProvider>
+    <Sidebar>{/* navigation */}</Sidebar>
+    <AppFrameContent>{/* primary canvas */}</AppFrameContent>
+  </SidebarProvider>
+</AppFrame>
+```
+
+The manifest allows the host to build the native window correctly. The
+`AppFrame` option yields the portable canvas fill to the host's frosted
+`UnderWindowBackground` material and allows the shared `Sidebar` to declare its
+measured region. These options are independent: apps may opt into any
+combination of background, titlebar, and sidebar. If either side of an opt-in is
+absent, or the platform or accessibility settings do not support sampling, the
+corresponding surface keeps its portable semantic fill.
+
 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/docs/visual-regression.md

@@ -1,7 +1,7 @@
 # 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.
+The runner exercises every authored story in the core component catalog. It
+does not start the desktop shell or any Moldable-managed app.
 
 ## What runs
 
@@ -32,8 +32,7 @@ one element:
 ```
 
 Playwright performs real hover, focus, and held-pointer interactions on that
-element. Button, segmented control, and toggle stories are the phase 1
-exemplars.
+element for every story that declares those live states.
 
 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
@@ -67,10 +66,9 @@ 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.
+unseeded randomness. Add an unavoidable 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moldable-ai/ui",
-  "version": "0.2.29",
+  "version": "0.2.32",
   "description": "Shared UI components for Moldable applications",
   "author": "Desiderata LLC",
   "license": "SEE LICENSE IN LICENSE",
@@ -31,6 +31,17 @@
       "import": "./dist/catalog/index.js",
       "require": "./dist/catalog/index.js"
     },
+    "./tokens": {
+      "types": "./dist/tokens/index.d.ts",
+      "import": "./dist/tokens/index.js",
+      "require": "./dist/tokens/index.js"
+    },
+    "./tokens/macos-27": "./src/tokens/macos-27/index.css",
+    "./platforms/macos-27": "./src/tokens/macos-27/index.css",
+    "./platforms/macos-27/source": "./src/tokens/macos-27/source.css",
+    "./tokens/macos-26": "./src/tokens/macos-26/index.css",
+    "./platforms/macos-26": "./src/tokens/macos-26/index.css",
+    "./platforms/macos-26/source": "./src/tokens/macos-26/source.css",
     "./styles": "./src/styles/index.css"
   },
   "files": [
@@ -39,6 +50,7 @@
     "src/components/ui/*.md",
     "src/lib/*.md",
     "src/styles",
+    "src/tokens",
     "LICENSE"
   ],
   "scripts": {

package/src/components/ui/accordion.md

@@ -0,0 +1,46 @@
+# Accordion
+
+## Purpose
+
+`Accordion` organizes related sections into independently expandable items. Use
+it when several peer sections should share one disclosure pattern; use
+`Collapsible` for a single disclosed region.
+
+## Usage
+
+```tsx
+import {
+  Accordion,
+  AccordionContent,
+  AccordionItem,
+  AccordionTrigger,
+} from '@moldable-ai/ui'
+
+;<Accordion type="single" collapsible>
+  <AccordionItem value="storage">
+    <AccordionTrigger>Storage</AccordionTrigger>
+    <AccordionContent>
+      Files remain in the current Moldable workspace.
+    </AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+## API
+
+- `Accordion` exposes the Radix root props, including `type="single"` or
+  `type="multiple"`, controlled state, and orientation.
+- `AccordionItem` requires the Radix item `value` and adds a dividing border.
+- `AccordionTrigger` renders a full-width trigger with a state-aware chevron.
+- `AccordionContent` provides the open and close animation. Its `className`
+  styles the inner content wrapper; remaining props apply to the Radix content
+  element.
+- Radix manages trigger relationships, expanded state, and keyboard behavior.
+
+## Quality bar
+
+- Keep trigger labels short and make each section understandable when closed.
+- Choose single or multiple expansion based on the task, not visual density.
+- Do not put another interactive control inside a trigger.
+- Do not hide required validation errors or the only primary action in a closed
+  item.

package/src/components/ui/alert.md

@@ -11,8 +11,15 @@ Use `AlertDialog` when the user must confirm an action. Use `Empty` for the norm
 ## Usage patterns
 
 ```tsx
-import { CircleAlert } from 'lucide-react'
-import { Alert, AlertDescription, AlertTitle } from '@moldable-ai/ui'
+import { CircleAlert, InfoIcon } from 'lucide-react'
+import {
+  Alert,
+  AlertActions,
+  AlertDescription,
+  AlertDismiss,
+  AlertTitle,
+  Button,
+} from '@moldable-ai/ui'
 
 ;<Alert tone="danger">
   <CircleAlert />
@@ -40,8 +47,9 @@ owned by the caller:
 
 ## API summary
 
-- `tone`: `neutral`, `info`, `success`, `warning`, or `danger`.
-- `density`: `compact` or `default`.
+- `tone`: `neutral`, `info`, `success`, `warning`, or `danger`; defaults to
+  `neutral`.
+- `density`: `compact` or `default`; defaults to `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.

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

@@ -4,7 +4,7 @@ The top-level shell for an app that can run in its own window or inside a host
 surface.
 
 ```tsx
-<AppFrame>
+<AppFrame nativeMaterial={{ background: true, sidebar: true }}>
   <Toolbar position="top">
     <ToolbarTitle>Today</ToolbarTitle>
     <ToolbarActions>{/* compact actions */}</ToolbarActions>
@@ -29,8 +29,11 @@ surface.
 - `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.
+  tests. Runtime apps should normally use `mode="auto"`; the host may set
+  `data-moldable-display-mode` when a window still uses an app iframe.
 - Material samples only renderer content. Native behind-window material remains
-  host-owned.
+  host-owned. `nativeMaterial={{ background: true }}` reveals the host's
+  frosted full-window material, while `nativeMaterial={{ sidebar: true }}`
+  allows a compatible sidebar to declare its region. Declare each matching
+  `window.nativeMaterial` option in `moldable.json`. Every option defaults off,
+  and portable semantic fills remain in unsupported environments.

package/src/components/ui/aspect-ratio.md

@@ -0,0 +1,37 @@
+# AspectRatio
+
+## Purpose
+
+`AspectRatio` reserves a stable rectangular area for media whose width and
+height should scale together. Use it for previews, thumbnails, video, and other
+content where layout shift would be distracting.
+
+## Usage
+
+```tsx
+import { AspectRatio } from '@moldable-ai/ui'
+
+;<AspectRatio ratio={16 / 9} className="rounded-control overflow-hidden">
+  <img
+    src={previewUrl}
+    alt="Workspace preview"
+    className="size-full object-cover"
+  />
+</AspectRatio>
+```
+
+## API
+
+- Accepts the Radix aspect-ratio root props.
+- `ratio` is the desired width divided by height, such as `16 / 9` or `1`.
+- The component adds `data-slot="aspect-ratio"` and otherwise leaves content
+  rendering to the caller.
+
+## Quality bar
+
+- Set an explicit ratio that matches the expected media.
+- Give images useful alternative text, or an empty `alt` when decorative.
+- Choose `object-cover` or `object-contain` deliberately; the component does
+  not crop or fit its child.
+- Do not use an aspect ratio wrapper when the content must determine its own
+  height.

package/src/components/ui/avatar.md

@@ -0,0 +1,48 @@
+# Avatar
+
+## Purpose
+
+`Avatar` presents a person, account, or other recognizable identity in a
+compact circular frame. It includes image, fallback, badge, and overlapping
+group primitives.
+
+## Usage
+
+```tsx
+import {
+  Avatar,
+  AvatarFallback,
+  AvatarGroup,
+  AvatarGroupCount,
+  AvatarImage,
+} from '@moldable-ai/ui'
+
+;<AvatarGroup>
+  <Avatar size="sm">
+    <AvatarImage src={owner.photoUrl} alt={owner.name} />
+    <AvatarFallback>RM</AvatarFallback>
+  </Avatar>
+  <AvatarGroupCount>+3</AvatarGroupCount>
+</AvatarGroup>
+```
+
+## API
+
+- `Avatar`: Radix root props plus `size="sm"`, `"default"`, or `"lg"`;
+  defaults to `default`.
+- `AvatarImage`: Radix image props.
+- `AvatarFallback`: Radix fallback props, including delayed fallback behavior.
+- `AvatarBadge`: native `span` props for a compact corner marker.
+- `AvatarGroup` and `AvatarGroupCount`: native `div` props for an overlapping
+  group and its remaining count.
+
+## Quality bar
+
+- Provide a stable fallback, usually initials or a short recognizable mark.
+- Use meaningful image `alt` text, or empty `alt` when adjacent text already
+  names the same identity.
+- Keep one size across an avatar group.
+- Give a badge additional accessible context when its color or icon conveys
+  status.
+- Do not use an avatar as an unlabeled action; wrap it in the appropriate
+  button or link when interactive.