@utopia-studio-design/design-system-cli 0.4.0 → 0.5.0

package/data/docs/charts.md

@@ -0,0 +1,95 @@
+# Ceramic Charts
+
+Ceramic Charts separates the stable semantic and interaction contract from the
+low-level renderer. Import application chart contracts from:
+
+```tsx
+import {
+  ChartRoot,
+  type ChartDatum,
+  type ChartSeriesDefinition,
+} from '@utopia-studio-design/design-system/Charts'
+```
+
+`ChartRoot` ships with a tree-shakeable Recharts adapter. A product may supply a
+different `ChartRenderer` without replacing Ceramic's series identities, states,
+keyboard model, summary, legend, exact-value output, RTL behavior, or semantic
+tokens.
+
+## Data and series identity
+
+Every period and series needs a stable ID. Missing values use `null`; never
+convert missing data to zero.
+
+```tsx
+const series: ChartSeriesDefinition[] = [
+  { id: 'current', label: 'Current period', tone: 'primary' },
+  { id: 'previous', label: 'Previous period', tone: 'benchmark', pattern: 'dash' },
+]
+
+const data: ChartDatum[] = [
+  { id: 'jan', label: 'Jan', values: { current: 42, previous: 35 } },
+  { id: 'feb', label: 'Feb', values: { current: 46, previous: null } },
+]
+```
+
+## Required states
+
+Use the explicit `loading`, `empty`, `error`, `partial`, and `ready` states.
+Partial data keeps the available geometry visible, identifies unavailable values
+in the live explorer and table, and does not imply zero.
+
+## Keyboard and accessibility
+
+- Supply a concise `accessibleSummary`.
+- The plot is one focusable composite. Logical Left/Right arrows explore
+  adjacent periods; `Home` and `End` move to the range boundaries.
+- RTL reverses chronological rendering and logical inline movement.
+- `ChartTooltipPanel` announces the exact active values.
+- Use `showDataTable` or `ChartDataTable` for an exact-value and screen-reader
+  alternative.
+- Series use semantic tokens plus dash/dot patterns; never rely on color alone.
+- Reduced motion disables renderer animation and loading shimmer.
+
+## Chart families
+
+The default renderer supports `line`, `bar`, `area`, `stacked`, `scatter`, and
+`donut`. Products should choose the family from the analysis task rather than
+from visual preference.
+
+## Copyable blocks
+
+Install or inspect:
+
+- `analytics-chart-card`
+- `kpi-grid`
+- `comparison-chart-panel`
+- `chart-with-data-table`
+
+The blocks live in `blocks/analytics-dashboard` and are copied through the CLI
+so product teams can customize queries and structure without forking the core
+chart contract.
+
+## Runnable template
+
+`template-analytics-dashboard` exercises all families and states in light/dark,
+LTR/RTL, desktop, and 320px layouts.
+
+```bash
+npx utopia-ds template template-analytics-dashboard --copy ./analytics-dashboard
+```
+
+## Performance boundary
+
+- Renderer packages stay behind the `Charts` entry point.
+- The root package entry does not re-export Charts; import from
+  `@utopia-studio-design/design-system/Charts` so chart code remains isolated.
+- Contract CI caps the emitted Charts entry and its shared implementation chunk
+  at 30 KiB before gzip.
+- Release CI caps the runnable analytics chart asset at 475 KiB before gzip and
+  135 KiB after gzip.
+- Initial dashboard data should remain below 500 plotted points per visible
+  panel; aggregate or virtualize the tabular alternative above that threshold.
+- Keep interaction feedback under 100ms and avoid animating more than 12 visible
+  series.
+- The template is a QA fixture, not a product persistence or query layer.

package/data/docs/composition-registry.md

@@ -0,0 +1,174 @@
+# Ceramic Composition Registry
+
+Ceramic's Composition Registry is the source of truth for modular dashboard
+layouts shared by agents, Studio runtime, and optional visual editors.
+
+Puck is not the registry. The Dashboard Composer includes it as an optional
+visual adapter that reads registered block definitions and writes versioned
+Ceramic Layout JSON. The same document can still be read and written by an
+agent without Puck.
+
+## Ownership
+
+```text
+Ceramic Components
+  -> Interaction Foundation
+  -> Dashboard Blocks
+  -> Composition Registry
+  -> Layout JSON
+  -> Agent / Studio runtime / optional Puck adapter
+```
+
+- Components own semantic UI and accessibility contracts.
+- Blocks own page-ready, product-relevant composition.
+- Themes own palette, typography, geometry, icon, and motion personality.
+- The registry owns allowed block types, props, states, spans, responsive
+  behavior, data requirements, locks, and agent permissions.
+- Layout JSON owns identity, ordering, placement, registered props, and locks.
+- Editors arrange registered blocks; they do not create Ceramic primitives or
+  styling contracts.
+
+## Public API
+
+```ts
+import {
+  ceramicCompositionRegistry,
+  getCeramicBlockDefinition,
+  listCeramicBlockDefinitions,
+  serializeCeramicLayout,
+  validateCeramicAgentMutation,
+  validateCeramicLayout,
+} from '@utopia-studio-design/design-system/Composition'
+```
+
+`listCeramicBlockDefinitions({ renderableOnly: true })` excludes roadmap
+definitions until a reviewed renderer is available. A planned definition stays
+discoverable to agents and editors but produces a `BLOCK_NOT_RENDERABLE`
+warning when present in a draft layout.
+
+The package also exposes the AI-readable sources used by the public API:
+
+```ts
+import blocks from '@utopia-studio-design/design-system/manifests/blocks.json'
+import registry from '@utopia-studio-design/design-system/manifests/composition-registry.json'
+import templates from '@utopia-studio-design/design-system/manifests/templates.json'
+```
+
+Use `Composition` for runtime validation. Use the JSON manifests for discovery,
+catalog generation, and build-time tooling; do not fork them into a second
+registry.
+
+## Design guardrails
+
+Layout documents may select semantic props such as `density`, `comparison`,
+`view`, and registered spans. They cannot contain arbitrary `style`, `sx`,
+`css`, `className`, raw colors, shadows, radii, spacing, or token overrides.
+
+Registry definitions must declare:
+
+- version and renderer availability;
+- props schema and supported spans;
+- semantic surfaces and responsive behavior;
+- loading, empty, error, and ready states;
+- data requirements;
+- RTL and reduced-motion readiness;
+- agent create, remove, move, and editable-prop permissions.
+
+## Layout validation
+
+The version 1 sample is
+[`examples/dashboard-layout.v1.json`](./examples/dashboard-layout.v1.json).
+
+```sh
+npx utopia-ds registry --list --json
+npx utopia-ds layout validate ./dashboard-layout.json --json
+npx utopia-ds layout serialize ./dashboard-layout.json
+```
+
+Validation is deterministic and does not silently coerce data. It rejects
+unsupported schema or block versions, duplicate IDs, unknown blocks, invalid
+props, arbitrary styling payloads, placements outside the grid, unsupported
+spans, broken region references, and unauthorized agent mutations.
+
+Canonical serialization sorts object keys while preserving array order so the
+same document can support storage, reviewable diffs, undo, and agent tool calls.
+
+## Runtime rendering
+
+The registry validates composition but does not import application blocks by
+path at runtime. A product supplies an explicit renderer map so code splitting,
+data adapters, permissions, and persistence remain owned by the application.
+
+The runnable
+[`Dashboard Composer`](../../templates/dashboard-composer/README.md) connects
+the current `todo-list`, `calendar-panel`, `issue-table`, `chart-panel`,
+`activity-feed`, `agent-status`, and `metric-grid`
+definitions to real Ceramic blocks:
+
+```tsx
+const renderers = {
+  'todo-list': TodoRenderer,
+  'calendar-panel': CalendarRenderer,
+  'issue-table': IssueTableRenderer,
+  'chart-panel': ChartPanelRenderer,
+  'activity-feed': ActivityRenderer,
+  'agent-status': AgentStatusRenderer,
+  'metric-grid': MetricsRenderer,
+}
+
+<CeramicDashboardRenderer
+  layout={layout}
+  renderers={renderers}
+  onLayoutChange={setLayout}
+/>
+```
+
+Layout JSON stores semantic configuration and placement. It does not store task
+records, calendar events, product authorization, adapter credentials, or
+arbitrary styles. Those values enter through the renderer map and application
+data layer.
+
+The `calendar-panel` definition exposes only reviewed scheduling configuration:
+`view`, `timeZone`, `locale`, `direction`, optional `weekStartsOn`,
+`secondaryCalendar`, `initialScrollHour`, and `showAgendaAlternative`.
+`direction: "inherit"` follows the dashboard, while `"auto"` derives direction
+from the block locale. Omitting `weekStartsOn` preserves locale-specific week
+conventions. The same pure resolver feeds the runtime and Puck previews so a
+registered field cannot be silently ignored by one consumer.
+
+The `activity-feed` definition follows the same boundary. Layout JSON may choose
+`density`, `groupBy`, `locale`, `direction`, `timeZone`, `showSources`, and
+`pageSize`; the product supplies localized activity records and retry/data
+adapters. `direction: "auto"` resolves from the locale, and timestamps are
+formatted in the registered IANA timezone. Runtime and Puck use the same
+`activity-feed-contract` resolver.
+
+The `agent-status` definition stores only reviewed display semantics. Execution
+records, sanitized summaries, progress, approval requests, and decision
+callbacks belong to the product data adapter. Runtime and Puck resolve filter,
+density, locale, direction, timezone, approval visibility, and item limits
+through the shared `agent-status-contract`. Raw prompts, stack traces,
+credentials, and command output do not belong in Layout JSON.
+
+The Dashboard Composer includes keyboard/touch move and remove controls,
+locked-region enforcement, agent mutation validation, a responsive Day
+transformation for the Calendar, RTL, dark mode, and live JSON evidence.
+
+## Agent and human control
+
+`locked: true` protects a block from agent removal, movement, or prop changes.
+A locked region protects every block ID it owns and its own membership. Locks
+are user/Studio-owned: an agent cannot add, remove, or toggle a block or region
+lock. An existing block ID also cannot be reassigned to another registered type
+or version to bypass create/remove permissions. Human products may add a
+reviewed unlock flow outside the agent mutation path, but an editor adapter must
+not bypass the validator.
+
+The included Puck integration is implemented as a thin adapter:
+
+1. Convert renderable Ceramic definitions into Puck component configuration.
+2. Render the same Ceramic block implementations used by Studio runtime.
+3. Translate editor changes into Ceramic Layout JSON.
+4. Validate before preview, persistence, or agent handoff.
+5. Preserve unknown future versions as explicit errors rather than dropping
+   fields.

package/data/docs/dashboard-composer.md

@@ -0,0 +1,94 @@
+# Dashboard Composer
+
+Dashboard Composer demonstrates the first usable runtime layer over Ceramic's
+Composition Registry. The same versioned Layout JSON is read by the runtime,
+edited through accessible human controls, and validated for agent mutations.
+
+## Included blocks
+
+- `todo-list`: completion, priority, due context, filtering, density, and
+  loading/empty/error/ready states.
+- `calendar-panel`: Month, Week, Day, and Agenda views with timezone-aware
+  events and a compact Day transformation.
+- `issue-table`: a governed active/backlog/blocked/completed workspace with
+  registered columns and density over product-owned issue records.
+- `chart-panel`: a lazy-loaded semantic chart with registered family,
+  comparison, and exact-value table controls.
+- `activity-feed`: localized chronological updates with day/source grouping,
+  timezone formatting, scoped automatic RTL, source visibility, and recoverable
+  pagination.
+- `agent-status`: localized execution progress, risk, approvals, blocked,
+  failed, and completed states with product-owned operational decisions.
+- `metric-grid`: locale-aware progress metrics in a locked owner region.
+
+## Data boundary
+
+Layout JSON owns:
+
+- registered block type and version;
+- semantic props;
+- column, span, compact span, and order;
+- block and region locks.
+
+The product owns:
+
+- task and event records;
+- agent execution records, sanitized summaries, and approval callbacks;
+- persistence and optimistic adapters;
+- authorization;
+- localized product copy;
+- data loading and error policy.
+
+## Agent mutation
+
+Call `validateCeramicAgentMutation(current, next)` before applying an agent
+proposal. A proposal cannot move, remove, or edit a locked block; change a
+locked region; create or toggle user/Studio locks; reassign an existing block
+ID to a different type or version; edit an unregistered prop; or introduce
+arbitrary styling.
+
+The runnable template is available at `/templates/dashboard-composer/` in the
+local documentation app and through the CLI template bundle.
+
+Open `/templates/dashboard-composer/agent-status-lab/` to inspect loading,
+empty, recoverable error, filtered-empty, and ready/approval states without
+changing production data. The lab uses the same block, locale resolver, and
+semantic styles as the Dashboard runtime.
+
+## Optional Puck editor
+
+Open `/templates/dashboard-composer/visual-editor/` to use the same registered
+blocks through Puck 0.22. The adapter:
+
+- exposes only definitions with an available product renderer;
+- generates fields from each definition's registered `propsSchema` and
+  `agentPermissions.editableProps`;
+- maps block and locked-region permissions to Puck insert, drag, edit,
+  duplicate, and delete permissions;
+- filters Puck's internal props before producing Layout JSON;
+- repacks reordered blocks into valid registered spans; and
+- calls `validateCeramicAgentMutation(current, next)` before accepting Publish.
+
+Puck Data is an editing format, not a second source of truth. Persist the
+validated Ceramic Layout JSON. Task records, calendar events, activity records
+and cursors, agent execution records and approval decisions, authorization, and
+server persistence remain product-owned.
+
+The visual-editor route first renders a 3 KB Ceramic boot shell, then
+lazy-loads registered block previews and editing controls, followed by the Puck
+surface and stylesheet. Both loading stages are announced to assistive
+technology, and recoverable error states preserve the validated layout if an
+optional chunk cannot load. Dashboard runtime and state-lab entry points do not
+include or preload the editor payload.
+
+The editor imports `@puckeditor/core/no-external.css` rather than Puck's
+standard stylesheet, which requests a hosted Inter font. Puck's public chrome
+variables are bridged to Ceramic semantic surface, text, interaction, focus,
+radius, typography, and motion tokens so light and dark modes stay inside the
+active design-system contract without raw color overrides.
+
+Dashboard Composer imports `KPIGrid` from the metric-only
+`AnalyticsMetricBlocks.tsx` entry. This preserves the existing KPI contract and
+the compatibility re-export from `AnalyticsDashboardBlocks.tsx`. Recharts and
+the chart explorer remain outside the initial Dashboard Composer HTML and load
+only when a registered Chart Panel renderer is present.

package/data/docs/database.md

@@ -0,0 +1,68 @@
+# Ceramic Database
+
+Ceramic Database is a schema-driven, multi-view record system. It does not
+replace read-oriented `Table`, `DataTable`, or `DataTableShell`, and it never
+owns product persistence or authorization.
+
+```tsx
+import {
+  DatabaseRoot,
+  type DatabaseRecord,
+  type DatabaseSchema,
+} from '@utopia-studio-design/design-system/Database'
+```
+
+## Stable contracts
+
+- Schemas use stable property IDs and support text, number, select,
+  multi-select, date, person, checkbox, and URL values.
+- Records use stable IDs. Filters, sorts, grouping, property visibility, and
+  saved views are serializable semantic data.
+- `DatabaseMutationAdapter` commits controlled mutations. Ceramic may show an
+  optimistic value, saving state, rollback, error announcement, and Undo, but
+  the product remains the source of truth.
+- `DatabasePermissions` gates edit, resize, column reorder, row reorder, and
+  bulk actions. Do not infer authorization from hidden controls.
+- `density="compact" | "default" | "comfortable"` controls desktop grid row
+  height. It does not remove properties or change the mobile record-card
+  reading order.
+
+## Keyboard and accessibility
+
+- The desktop grid exposes row/column counts, names every cell, and keeps one
+  active cell in the tab order.
+- Logical Arrow keys move between cells; `Home` and `End` move to grid
+  boundaries. Inline arrows reverse under RTL.
+- Enter or double-click starts editing. Escape cancels; Enter or blur validates
+  and commits.
+- Copy and paste are explicit callbacks so apps can enforce security and
+  multi-cell boundaries before reading or writing clipboard data.
+- Selection uses named checkboxes and an announced bulk-action surface.
+
+## Responsive behavior
+
+At narrow widths, the dense grid becomes record cards. Opening a card presents
+the complete property set in `RecordDetailDrawer`; the page itself never gains
+horizontal overflow.
+
+## Copyable blocks and template
+
+- `database-toolbar`
+- `database-table-block`
+- `saved-views-bar`
+- `record-detail-drawer`
+- `bulk-action-bar`
+- `template-database-workspace`
+
+```bash
+npx utopia-ds template template-database-workspace --copy ./database-workspace
+```
+
+## Performance budgets
+
+- The `Database` package entry is capped at 45 KiB before gzip.
+- The runnable database workspace asset is capped at 90 KiB before gzip and
+  25 KiB after gzip.
+- The 1,000-record fixture must render fewer than 40 grid rows in the DOM,
+  complete initial usable render under 1,000ms, and keep keyboard edit feedback
+  under 200ms in Chromium CI.

package/data/docs/examples/dashboard-layout.v1.json

@@ -0,0 +1,65 @@
+{
+  "schemaVersion": 1,
+  "id": "operations-dashboard",
+  "theme": "utopia-default",
+  "columns": 12,
+  "blocks": [
+    {
+      "id": "overview-metrics",
+      "type": "metric-grid",
+      "version": 1,
+      "placement": {
+        "column": 1,
+        "span": 4,
+        "order": 1,
+        "compactSpan": 12
+      },
+      "props": {
+        "metrics": ["open", "blocked", "resolved"],
+        "density": "compact",
+        "comparison": "previous-period"
+      },
+      "locked": false
+    },
+    {
+      "id": "active-issues",
+      "type": "issue-table",
+      "version": 1,
+      "placement": {
+        "column": 1,
+        "span": 12,
+        "order": 2,
+        "compactSpan": 12
+      },
+      "props": {
+        "view": "active",
+        "density": "compact",
+        "columns": ["title", "status", "priority", "assignee"]
+      },
+      "locked": false
+    },
+    {
+      "id": "automation-status",
+      "type": "agent-status",
+      "version": 1,
+      "placement": {
+        "column": 9,
+        "span": 4,
+        "order": 3,
+        "compactSpan": 12
+      },
+      "props": {
+        "showApprovals": true,
+        "density": "default"
+      },
+      "locked": true
+    }
+  ],
+  "regions": [
+    {
+      "id": "governance",
+      "locked": true,
+      "blockIds": ["automation-status"]
+    }
+  ]
+}

package/data/docs/foundations.md

@@ -74,10 +74,11 @@ Arabic display sizing should follow the Latin display scale at about 95%, rather
 - Runtime recipes use four engine-neutral intents: `feedback`, `page`, `surface`, and `layout`.
 - Components consume `--motion-duration-*` and `--motion-ease-*` roles rather than hardcoded milliseconds or easing curves.
 - `MotionProvider` sets the theme profile and runtime adapter for a subtree. Motion-aware components expose `motion?: boolean` for a local override.
+- `MotionProvider asChild` applies that policy to exactly one semantic subtree root without adding a wrapper. The consumer root must accept `className`, `style`, `data-*`, and its children.
 - `motion={false}` and `prefers-reduced-motion: reduce` disable decorative movement while preserving state changes and accessibility.
 - Directional motion follows logical inline start/end and mirrors in RTL when direction carries meaning.
 - Icon motion follows the action: a bell swings from its top, download moves downward, and copy snaps once. Do not apply a generic bounce.
-- `utopia-default` uses the `ceremonial` profile, `dextrum` uses `swift`, and `barrier-intelligence` uses `precise`.
+- `utopia-default` uses the `ceremonial` profile, `dextrum` uses `swift`, and both `barrier-intelligence` and `renacore` use `precise`.
 - WAAPI is built in. Motion for React, Anime.js, and GSAP are optional peer adapters, so unused engines do not need to ship with an application.
 
 ```tsx

package/data/docs/interaction-foundation.md

@@ -0,0 +1,109 @@
+# Interaction foundation
+
+Ceramic complex components share a headless interaction contract. Charts,
+database surfaces, and schedulers consume this layer; product-specific data and
+workflow rules stay in the product.
+
+## Public import
+
+```ts
+import {
+  createCeramicFormatters,
+  createCommandHistory,
+  findTypeaheadMatch,
+  getGridNavigationTarget,
+  getVirtualRange,
+  reorderItems,
+  runOptimisticMutation,
+  updateSelection,
+  useCommandHistory,
+  useControllableState,
+  useOptimisticMutation,
+} from '@utopia-studio-design/design-system/Interaction'
+```
+
+## State
+
+Controlled state uses `value` plus `onChange`. Uncontrolled state uses
+`defaultValue`; after initialization it is not re-read. Change callbacks fire
+after the next value is resolved and do not fire when `Object.is` reports no
+change.
+
+Selection uses stable application keys. `replace`, `toggle`, `range`, and `all`
+are explicit behaviors. Range selection follows `orderedKeys`; never infer
+visual order from DOM position when sorting or virtualization is active.
+
+## Keyboard and direction
+
+`getGridNavigationTarget` supports logical inline arrows, block arrows,
+Home/End, and PageUp/PageDown. Inline arrows reverse under `direction: 'rtl'`;
+ArrowUp and ArrowDown do not. Composite widgets keep one tab stop and move focus
+after state commits.
+
+Typeahead is locale-aware and wraps once from the current item.
+
+## Drag, resize, and alternatives
+
+Pointer drag is never the only path. Provide keyboard- and touch-operable Move
+earlier/Move later actions, announce the committed position, and restore focus
+to the moved item. Resize affordances expose a keyboard-operable value and
+minimum/maximum constraints.
+
+Use logical `inline` and `block` coordinates for collision and drop contracts.
+When reduced motion is active, commit the final order or size without animated
+displacement.
+
+## Virtualization and scrolling
+
+`getVirtualRange` calculates a fixed-size visible window with overscan. Keep
+stable item keys and persist a `ScrollAnchor` (`key` plus offset within the
+item), not a raw pixel offset, when sorting or inserting data.
+
+Virtualized collections must preserve accessible position and set size, must
+not make off-screen content the only way to discover an action, and must be
+tested with production-scale fixtures.
+
+## Undo and optimistic recovery
+
+Commands implement both `execute` and `undo`. Executing a new command clears
+the redo stack. `useCommandHistory` keeps the current context and availability
+of Undo/Redo in the React render contract. Optimistic commits rollback on
+rejection; `useOptimisticMutation` aborts an interrupted request and surfaces an
+application-owned accessible error message. Abort signals belong to the
+consumer's request lifecycle.
+
+## Locale, timezone, and DST
+
+`createCeramicFormatters` delegates number and date rendering to `Intl`.
+Consumers must pass an IANA timezone for schedule surfaces. Store instants and
+timezone identifiers separately; do not persist a formatted label or fixed UTC
+offset as the event model. Ambiguous and skipped local times remain
+product-policy decisions.
+
+## Semantic tokens
+
+- `--interaction-density-{compact,default,comfortable}`
+- `--interaction-focus`
+- `--interaction-selection-{surface,border}`
+- `--interaction-drag-{surface,border}`
+- `--interaction-drop-indicator`
+- `--visualization-series-{1,2}` and `--visualization-grid`
+- `--temporal-today-surface`, `--temporal-now-indicator`,
+  `--temporal-outside-foreground`
+
+Themes may remap these roles but components must not replace them with raw
+colors, shadows, or radii.
+
+## Runnable references
+
+Copy the focused block:
+
+```sh
+npx utopia-ds block interaction-workbench --copy ./src/interaction-workbench
+```
+
+Or generate the full lab:
+
+```sh
+npx utopia-ds template template-interaction-lab --copy ./interaction-lab
+```