@cardstack/boxel-cli 0.10.0 → 0.10.1-unstable.0

package/bundled-realms/pretui/demo-structure-dashboard.gts

@@ -0,0 +1,212 @@
+// Pretui — demo-structure-dashboard: freestyle usage pages for the
+// user-customizable dashboard (`DashboardGrid` + `DashboardItem`).
+//
+// Three pages, because the component has three stories to tell:
+//   1. DashboardGrid — the live surface, with the serialized layout shown
+//      beside it so the "layout is data" claim is visible, not asserted.
+//   2. DashboardGrid · read-only — the SAME layout with `@editable={{false}}`,
+//      rendered by CSS grid with no engine at all.
+//   3. DashboardItem — the cell on its own, outside a grid, which is exactly
+//      how it degrades when no host is supplied.
+//
+// Fixture data is deterministic: fixed arrays and `seedFrom`/`pick`, never
+// `Math.random()` or `Date.now()` (realm law — they break index determinism).
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './components/freestyle-usage';
+import { Token } from './components/token';
+import { DashboardGrid } from './components/dashboard-grid';
+import { resolveLayout } from './internal/structure-dashboard';
+import type { DashboardPlacement } from './internal/structure-dashboard';
+
+// ── fixture ──────────────────────────────────────────────────────────────
+
+export interface Tile {
+  id: string;
+  title: string;
+  kind: string;
+  metric: string;
+  delta: number;
+  level: number;
+}
+
+export const TILES: Tile[] = [
+  {
+    id: 'revenue',
+    title: 'Revenue',
+    kind: 'series/revenue@2',
+    metric: '£184,220',
+    delta: 12.4,
+    level: 3,
+  },
+  {
+    id: 'pipeline',
+    title: 'Pipeline',
+    kind: 'series/pipeline@2',
+    metric: '41 deals',
+    delta: -3.1,
+    level: 1,
+  },
+  {
+    id: 'churn',
+    title: 'Churn',
+    kind: 'series/churn@1',
+    metric: '1.9%',
+    delta: -0.4,
+    level: 1,
+  },
+  {
+    id: 'nps',
+    title: 'NPS',
+    kind: 'survey/nps@4',
+    metric: '+54',
+    delta: 6,
+    level: 2,
+  },
+  {
+    id: 'uptime',
+    title: 'Uptime',
+    kind: 'ops/uptime@1',
+    metric: '99.98%',
+    delta: 0.02,
+    level: 3,
+  },
+];
+
+export const START_LAYOUT: DashboardPlacement[] = [
+  { id: 'revenue', x: 0, y: 0, w: 6, h: 3 },
+  { id: 'pipeline', x: 6, y: 0, w: 6, h: 3 },
+  { id: 'churn', x: 0, y: 3, w: 4, h: 2 },
+  { id: 'nps', x: 4, y: 3, w: 4, h: 2 },
+  { id: 'uptime', x: 8, y: 3, w: 4, h: 2 },
+];
+
+/** Deterministic sparkline path — seeded, never random. */
+
+export function serializeLayout(layout: readonly DashboardPlacement[]): string {
+  return layout
+    .map((p) => `{ id: '${p.id}', x: ${p.x}, y: ${p.y}, w: ${p.w}, h: ${p.h} }`)
+    .join('\n');
+}
+
+// ── 2. read-only ─────────────────────────────────────────────────────────
+
+const READONLY_SOURCE = `<DashboardGrid
+  @items={{this.tiles}}
+  @layout={{this.layout}}
+  @editable={{false}}
+  @label='Quarterly board'
+>
+  <:title as |tile|>{{tile.title}}</:title>
+  <:item as |tile|>…</:item>
+</DashboardGrid>`;
+
+class DashboardReadOnlyDemo extends Component {
+  tiles = TILES;
+  @tracked messy = false;
+  setMessy = (v: boolean) => (this.messy = v);
+
+  /** A deliberately broken layout: every tile stacked on 0,0. */
+  get layout(): DashboardPlacement[] {
+    if (!this.messy) {
+      return START_LAYOUT;
+    }
+    return TILES.map((tile) => ({ id: tile.id, x: 0, y: 0, w: 4, h: 2 }));
+  }
+
+  get resolvedLabel(): string {
+    return serializeLayout(resolveLayout(this.layout, 12, false));
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='DashboardGrid · read-only'
+      @description="A dashboard is edited rarely and read constantly, so @editable={{false}} never constructs an engine at all: no GridStack instance, no listeners, no ResizeObserver, no injected stylesheet, no drag affordances — one CSS grid, positioned from the same coordinates. The two modes cannot drift because both resolve through resolveLayout(), which runs gridstack's own DOM-free GridStackEngine. Turn on 'overlapping layout' to watch a broken stored layout (every tile at 0,0) get untangled by exactly the collision resolution the live grid uses."
+      @source={{READONLY_SOURCE}}
+      @viewportMode='fill'
+    >
+      <:example>
+        <div class='ro-demo'>
+          <DashboardGrid
+            @items={{this.tiles}}
+            @layout={{this.layout}}
+            @editable={{false}}
+            @columns={{12}}
+            @cellHeight={{72}}
+            @label='Quarterly board, read only'
+          >
+            <:title as |tile|>{{tile.title}}</:title>
+            <:actions as |tile|>
+              <Token @value={{tile.kind}} />
+            </:actions>
+            <:item as |tile placement|>
+              <div class='ro-tile'>
+                <span class='ro-value'>{{tile.metric}}</span>
+                <span class='ro-span'>{{placement.w}}×{{placement.h}}</span>
+              </div>
+            </:item>
+          </DashboardGrid>
+          <pre class='ro-code'>{{this.resolvedLabel}}</pre>
+        </div>
+      </:example>
+
+      <:api as |Args|>
+        <Args.Bool
+          @name='overlapping layout'
+          @defaultValue={{false}}
+          @value={{this.messy}}
+          @description='Feed the grid a layout where every tile claims 0,0. The engine resolves it — this is a demo control, not a component argument.'
+          @onInput={{this.setMessy}}
+        />
+        <Args.Bool
+          @name='editable'
+          @defaultValue={{true}}
+          @description='Pinned false on this page.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @description='resolveLayout(layout, columns, float) is exported alongside the component: pure, DOM-free, and the same function this mode uses — call it wherever you need coordinates without a grid.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+
+    <style scoped>
+      .ro-demo {
+        display: grid;
+        gap: var(--space-4, 11px);
+      }
+      .ro-tile {
+        display: flex;
+        align-items: baseline;
+        justify-content: space-between;
+        gap: var(--space-2, 5px);
+      }
+      .ro-value {
+        font-size: 19px;
+        font-weight: 600;
+        letter-spacing: -0.02em;
+        font-variant-numeric: tabular-nums;
+        color: var(--card-foreground);
+      }
+      .ro-span {
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--muted-foreground);
+      }
+      .ro-code {
+        margin: 0;
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-sm, 11.5px);
+        line-height: 1.6;
+        color: var(--muted-foreground);
+        white-space: pre;
+        overflow-x: auto;
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_STRUCTURE_DASHBOARD: Record<string, unknown> = {
+  'DashboardGrid · read-only': DashboardReadOnlyDemo,
+};

package/bundled-realms/pretui/demo-structure-data.gts

@@ -0,0 +1,4 @@
+// Pretui — demo-structure-data: the fixed clock and fixtures the Feed and Timeline usage pages share.
+
+export const NOW = '2026-08-12T10:00:00Z';
+

package/bundled-realms/pretui/demo-structure-scroll.gts

@@ -0,0 +1,19 @@
+// Pretui — demo-structure-scroll: the lot fixtures the Carousel and Scroller usage pages share.
+import { PLACES, TEAS, seedFrom, take } from './examples';
+
+const SCROLL_SEED = seedFrom('pretui-scroll-demo');
+
+interface Lot {
+  id: string;
+  tea: string;
+  place: string;
+  chests: number;
+}
+
+export const LOTS: Lot[] = take(SCROLL_SEED, 0, 9, TEAS).map((tea, i) => ({
+  id: 'B-' + (101 + i),
+  tea,
+  place: PLACES[(seedFrom(tea) + i) % PLACES.length] as string,
+  chests: 20 + (seedFrom('lot#' + tea) % 180),
+}));
+

package/bundled-realms/pretui/demo-structure.gts

@@ -0,0 +1,21 @@
+// Pretui — demo-structure: the placement options the Tooltip, Popover and Drawer usage pages share.
+
+export const SIDE_OPTIONS = ['top', 'bottom', 'left', 'right'];
+
+export const PLACEMENT_OPTIONS = [
+  'top',
+  'top-start',
+  'top-end',
+  'bottom',
+  'bottom-start',
+  'bottom-end',
+  'left',
+  'left-start',
+  'left-end',
+  'right',
+  'right-start',
+  'right-end',
+];
+
+export const DRAWER_PLACEMENT_OPTIONS = ['end', 'start', 'bottom'];
+

package/bundled-realms/pretui/demo-surfaces-grid.gts

@@ -0,0 +1,104 @@
+// Pretui — demo-surfaces-grid: the ledger fixture the Sheet and SheetToolbar usage pages share.
+import { DATES, PLACES, SUPPLIERS, TEAS, pick, seedFrom } from './examples';
+import type { SheetColumn } from './components/sheet';
+
+// ── The fiction: a tea importer's arrivals ledger ────────────────────────
+// Deterministic (seedFrom/pick — Realm law: no Math.random, no Date.now),
+// and every row carries an `id`, because getSheet keys rows by `row.id`
+// and falls back to the ordinal when it is missing — which makes the
+// selected cell jump the moment a sort reorders the rows.
+//
+// A type ALIAS, not an interface: an interface has no implicit index
+// signature, so `Lot[]` would not be assignable to `SheetDatum[]`.
+export type Lot = {
+  id: string;
+  lot: string;
+  tea: string;
+  origin: string;
+  supplier: string;
+  kilos: number;
+  price: number;
+  arrives: string;
+  cleared: boolean;
+};
+
+const LEDGER_SEED = seedFrom('pretui-arrivals-ledger');
+
+function lotCode(origin: string, arrives: string, index: number): string {
+  let place = origin.replace(/[^A-Za-z]/g, '').slice(0, 2).toUpperCase();
+  let stamp = `${arrives.slice(2, 4)}${arrives.slice(5, 7)}`;
+  return `${place}-${stamp}-${String.fromCharCode(65 + (index % 26))}`;
+}
+
+export function buildLedger(count: number): Lot[] {
+  let out: Lot[] = [];
+  for (let i = 0; i < count; i++) {
+    let tea = pick(LEDGER_SEED, i, TEAS);
+    let origin = pick(LEDGER_SEED, i + 31, PLACES);
+    let supplier = pick(LEDGER_SEED, i + 67, SUPPLIERS);
+    let arrives = pick(LEDGER_SEED, i + 101, DATES);
+    let n = seedFrom(`${tea}/${origin}/${i}`);
+    out.push({
+      id: `lot-${i}`,
+      lot: lotCode(origin, arrives, i),
+      tea,
+      origin,
+      supplier,
+      kilos: 18 + (n % 240),
+      price: Number((36 + ((n >>> 9) % 310) + ((n >>> 5) % 100) / 100).toFixed(2)),
+      arrives,
+      cleared: (n >>> 3) % 3 !== 0,
+    });
+  }
+  return out;
+}
+
+export const LEDGER_COLUMNS: SheetColumn[] = [
+  {
+    key: 'lot',
+    label: 'Lot',
+    type: 'text',
+    width: 'minmax(8.5rem, 0.8fr)',
+    // A reference the warehouse assigned — a machine value (Law 3), and
+    // not ours to retype. Per-column gate, independent of @editable.
+    mono: true,
+    editable: false,
+    hint: 'ref',
+  },
+  { key: 'tea', label: 'Tea', type: 'text', width: 'minmax(10rem, 1.4fr)' },
+  { key: 'origin', label: 'Origin', type: 'text', width: 'minmax(8rem, 1fr)' },
+  {
+    key: 'supplier',
+    label: 'Supplier',
+    type: 'text',
+    width: 'minmax(12rem, 1.6fr)',
+  },
+  {
+    key: 'kilos',
+    label: 'Weight',
+    type: 'number',
+    width: 'minmax(6rem, 0.6fr)',
+    hint: 'kg',
+  },
+  {
+    key: 'price',
+    label: 'Price',
+    type: 'number',
+    width: 'minmax(7rem, 0.7fr)',
+    hint: 'USD/kg',
+  },
+  {
+    key: 'arrives',
+    label: 'Arrives',
+    type: 'date',
+    width: 'minmax(8.5rem, 0.8fr)',
+  },
+  {
+    key: 'cleared',
+    label: 'Cleared',
+    type: 'boolean',
+    width: 'minmax(6rem, 0.5fr)',
+    sortable: false,
+  },
+];
+

package/bundled-realms/pretui/demo-texture.gts

@@ -0,0 +1,21 @@
+// Pretui — demo-texture: the hue rail the BackgroundField, Backdrop and PulsingBorder usage pages share.
+
+// A curated hue rail. Every entry but the first is a THEME TOKEN, because the
+// point being demonstrated is that a field re-tints with the theme and with
+// light/dark on its own — the one literal at the end is there to prove the
+// arg also takes a plain CSS color when a caller really wants one.
+export const HUE_OPTIONS = [
+  'default',
+  'var(--chart-1)',
+  'var(--chart-2)',
+  'var(--chart-3)',
+  'var(--chart-4)',
+  'var(--chart-5)',
+  'var(--primary)',
+  'var(--foreground)',
+  '#c2410c',
+];
+
+export function hueArg(value: string): string | undefined {
+  return value === 'default' ? undefined : value;
+}

package/bundled-realms/pretui/docs/catalog-taxonomy.md

@@ -0,0 +1,200 @@
+# Pretui Catalog Taxonomy
+
+This document defines how components are classified and described in the
+Pretui catalog. It is the public reference for catalog authors, reviewers, and
+tools that generate or filter component metadata.
+
+## Principle
+
+A component's **category** and **composition tier** answer different
+questions and must not be collapsed into one hierarchy.
+
+- **Category** answers: _What kind of component is this, and where would a
+  product author look for it?_
+- **Tier** answers: _How compositionally complex is it?_
+- **Tags** describe cross-cutting capabilities that do not determine the
+  component's primary home.
+
+The catalog assigns one primary category and one tier to every component.
+A component may have any number of tags.
+
+## Categories
+
+The primary category vocabulary is:
+
+| Category         | Scope                                                                                                                   |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| Foundations      | Visual and semantic primitives: typography, labels, tokens, badges, accessibility utilities, and decorative treatments. |
+| Actions          | Buttons and explicit action affordances.                                                                                |
+| Inputs           | Controls that collect or select one value.                                                                              |
+| Forms            | Field composition, validation presentation, record editing, and multi-field workflows.                                  |
+| Layout           | Components whose primary job is arranging, sizing, scrolling, or fitting other content.                                 |
+| Navigation       | Components that move a user between locations, views, pages, or hierarchy levels.                                       |
+| Containers       | Surfaces that enclose, disclose, or group content without determining the larger page layout.                           |
+| Data Display     | Tables, lists, charts, trees, timelines, values, formatters, and collection views.                                      |
+| Feedback         | Status, progress, loading, empty, result, alert, and notification states.                                               |
+| Overlays         | Content rendered above or outside the normal document flow.                                                             |
+| Media            | Image, audio, video, model, asset, and time-based media interfaces.                                                     |
+| Agentic          | Conversation, reasoning, approval, work, recommendation, and result surfaces for agents.                                |
+| Motion & Effects | Reusable transition, presence, pointer, text-motion, and visual-effect behaviors.                                       |
+| Authoring Tools  | Inspector, layer, design-value, and component-documentation machinery.                                                  |
+
+Category names are user-facing and should use familiar product-language terms.
+Implementation packages, source libraries, rendering formats, and ownership
+boundaries are metadata, not categories.
+
+## Layout is a first-class category
+
+`Layout` is a primary category, not a synonym for every surface and not a
+composition tier. A component belongs in Layout when its main contract
+controls the placement, dimensions, overflow, responsiveness, or fitting of
+its children.
+
+The initial Layout set is:
+
+- Affix
+- AppShell
+- AspectRatio
+- Carousel
+- CopyFit
+- DashboardGrid
+- DashboardItem
+- GraphLayout
+- Grid
+- HeroSplit
+- InfiniteScroll
+- Masonry
+- PageScaffold
+- Resizable
+- ScrollArea
+- Scroller
+- SplitPanes
+- Stack
+- StackingCards
+- ZoomableFrame
+
+Important boundaries:
+
+- Card, Panel, and PanelSection are **Containers**.
+- Sidebar, BottomNav, Dock, Breadcrumb, Pagination, NavigationMenu, SkipLink,
+  and TableOfContents are **Navigation**.
+- Board, NodeCanvas, Tree, Timeline, Chart, BarList, and Sparkline are
+  **Data Display**.
+- Empty, EmptyState, and Skeleton are **Feedback**.
+- MorphingDialog, MorphingPopover, and Tooltip are **Overlays**.
+- FormLayout remains **Forms** and carries the `layout` tag because its
+  primary purpose is form composition.
+- StepsWithMedia remains a composed block and carries both `layout` and
+  `media` tags.
+
+### CopyFit naming
+
+`fitted` is a Boxel rendering format. CopyFit is the layout mechanism used to
+make copy and optional media adapt across the fitted format's available
+quantums. Naming the component after the mechanism keeps the format and the
+component distinct.
+
+CopyFit metadata:
+
+- Category: `Layout`
+- Suggested tier: `Compound`
+- Tags: `fitted`, `responsive`, `container-query`, `copy-fitting`
+
+Pret UI has no `FittedCard` alias; examples and documentation use `CopyFit`.
+`FittedCard` elsewhere refers to the boxel-ui component of that name.
+
+## Composition tiers
+
+The tier vocabulary contains only compositional levels:
+
+| Tier      | Meaning                                                                                 |
+| --------- | --------------------------------------------------------------------------------------- |
+| Primitive | A visual, semantic, or behavioral atom that is not normally a complete product control. |
+| Element   | A complete component with one focused job.                                              |
+| Compound  | A component assembled from multiple elements or primitives.                             |
+| Surface   | A bounded region that hosts or organizes product content.                               |
+| Block     | A reusable product-level composition or scene.                                          |
+| Runtime   | Authoring, catalog, or execution machinery rather than ordinary product UI.             |
+
+Forms, Media, Motion, Layout, and Agentic are categories, not tiers. Host
+ownership is also separate from tier.
+
+## Tags
+
+Tags capture meaningful overlap without forcing a component into several
+primary categories. Prefer a small controlled vocabulary. Useful tags include:
+
+- `accessible-utility`
+- `async`
+- `collection`
+- `container-query`
+- `copy-fitting`
+- `drag-drop`
+- `fitted`
+- `form-associated`
+- `keyboard-navigation`
+- `layout`
+- `media`
+- `responsive`
+- `selection`
+- `time-based`
+- `virtualized`
+
+Tags describe capabilities, not implementation trivia. Package names and
+source libraries belong in provenance metadata.
+
+## Metadata model
+
+Every catalog component should expose these concepts:
+
+| Field                  | Purpose                                                           |
+| ---------------------- | ----------------------------------------------------------------- |
+| `category`             | One primary user-facing category.                                 |
+| `tier`                 | One explicit composition tier. Never infer it from category.      |
+| `tags`                 | Controlled cross-cutting capability terms.                        |
+| `ownership`            | `pretui`, `boxel-ui`, or `host`.                                  |
+| `implementationStatus` | `planned`, `designed`, or `implemented`.                          |
+| `adoptionStatus`       | `experimental`, `demo-ready`, `in-use`, or `deprecated`.          |
+| `introducedVersion`    | The release in which the component entered the catalog.           |
+| `version`              | The component's current contract version.                         |
+| `brief`                | A concise statement of purpose and differentiation.               |
+| `dependencies`         | Structured component dependencies rather than a delimited string. |
+| `provenance`           | Structured sources, prior art, and implementation lineage.        |
+| `demandEvidence`       | The systems or research sources supporting demand.                |
+
+`PretUISpec` does not have the last three yet. Today dependencies are the
+`buildsOn` string, provenance is `source`, `lineage` and `refs`, and demand is
+a 1–5 `demand` score without its evidence. Host chrome is `ownership: host`,
+not a category.
+
+### Lifecycle fields
+
+`host` is ownership, not an implementation status. Likewise, `live` is too
+ambiguous to describe both implementation and adoption. A component can be
+implemented without having examples, or demo-ready without being used in a
+product. Those states must remain independently queryable.
+
+The “new” badge is computed: a component is new when its `introducedVersion`
+is the current kit release (`CURRENT_RELEASE` in `pretui-component.gts`), so
+the badge clears itself when that release is bumped.
+
+### Relationships and provenance
+
+Component dependencies should identify individual catalog components. External
+references should retain the source system, referenced component, and URL when
+available. Avoid packing several references into a display string; structured
+metadata supports filtering, validation, and future relationship views.
+
+## Catalog presentation
+
+The catalog should expose the two primary axes independently:
+
+1. Filter by **Category** in the navigation rail.
+2. Optionally group results by **Tier**.
+
+Search should include category, tier, tags, brief, dependencies, and
+provenance. Adoption filters remain independent of taxonomy.
+
+This preserves the periodic-table presentation while making discovery follow
+product intent: an author can ask for “layout,” then see which results are
+elements, compounds, surfaces, or blocks.

package/bundled-realms/pretui/docs/composites.md

@@ -0,0 +1,13 @@
+# The composites group
+
+Design notes shared by **OtpInput**, **TimeInput**, **StepList**, **ButtonGroup**, **Divider**.
+
+Form composites: segmented entry
+(OtpInput, TimeInput), progress structure (StepList), and grouping
+chrome (ButtonGroup, Divider). Semantics transcribed — not copied — from
+Web Awesome's wa-otp-input / wa-time-input / wa-button-group / wa-divider
+(MIT, (c) Fonticons) and React Spectrum's StepList (Apache-2.0, (c)
+Adobe), re-cut on the kit's own bones: Pretui tokens + light fallbacks,
+the value?/defaultValue?/onValueChange? contract, data-test-pretui-_ +
+data-_ state reflection, and no document-level listeners anywhere.
+Wave-0 adaptations are documented per component.

package/bundled-realms/pretui/docs/reading.md

@@ -0,0 +1,12 @@
+# The reading group
+
+Design notes shared by **DataGrid**, **KeyValue**, **Stat**, **Prose**, **StreamingText**, **Table**.
+
+Data display.
+Translated from pretui-design-system (components/reading + css/structure.css).
+Realm adaptation: StreamingText is timer-free — words reveal via CSS
+animation-delay stagger (the prerenderer blocks timers; reduced-motion
+snaps to the end state). The sr-only mirror carries the full text. Stat's
+headline number is likewise timer-free: it delegates to Odometer
+(reading-format), whose roll is one CSS animation keyed off the digit's
+from>to pair.

package/bundled-realms/pretui/docs/structure.md

@@ -0,0 +1,8 @@
+# The structure group
+
+Design notes shared by **Panel**, **Toolbar**, **Tooltip**, **Skeleton**, **Pagination**, **Breadcrumb**.
+
+Surfaces, the panel signature, navigation.
+Translated from pretui-design-system (components/structure + css/structure.css).
+Realm adaptations: Tooltip is CSS-only (hover/focus-within — prerender-safe);
+Menu closes via backdrop, not a document listener.