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

package/bundled-realms/pretui/components/separator.md

@@ -0,0 +1,36 @@
+## What it is
+
+**Separator** is **Divider** under the name shadcn, Radix and React Aria use. The export is the same component. Import it when a port already says Separator; the **Divider** writeup carries the depth.
+
+## The contract
+
+```
+@orientation? ('horizontal' | 'vertical'; default 'horizontal')
+@label?          — a centred label, horizontal only
+Element: HTMLDivElement
+```
+
+Identical to Divider: a `role="separator"` with an explicit `aria-orientation`.
+
+## Prior art
+
+**Radix `Separator`** takes `orientation` and `decorative`. `decorative` drops the role so a purely visual rule is not announced. **shadcn** wraps Radix. **React Aria `Separator`** takes `orientation` and `elementType`.
+
+Divider adds a centred `@label` ("or") that Radix leaves to composition. It has no `decorative` arg: a rule used only for rhythm still reaches the accessibility tree. Pass `aria-hidden='true'` through attributes to take it out.
+
+## Accessibility
+
+Identical to Divider. It is `role="separator"` with `aria-orientation`. `@label` becomes the separator's `aria-label`. Every Separator is announced, including decorative ones, until the call site adds `aria-hidden='true'`. A vertical Separator with a `@label` keeps the name but hides the text, which is a call-site mistake.
+
+## Theming
+
+Identical to Divider: `--border` (the rule), `--muted-foreground` and `--text-ui-sm` / `--track-ui` (the label), and `--pretui-divider-spacing` (the margin around it, default `--space-4`).
+
+## React ecosystem
+
+| shadcn / Radix / React Aria | Pretui                                  |
+| --------------------------- | --------------------------------------- |
+| `<Separator />`             | `<Separator />`                         |
+| `orientation="vertical"`    | `@orientation='vertical'`               |
+| `decorative`                | `aria-hidden='true'` through attributes |
+| a label between two rules   | `@label='or'`                           |

package/bundled-realms/pretui/components/separator.usage.gts

@@ -0,0 +1,32 @@
+// Pretui — Separator usage page.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { FreestyleUsage } from './freestyle-usage';
+import { Separator } from './separator';
+
+const SeparatorUsage: TemplateOnlyComponent = <template>
+  <FreestyleUsage
+    @name='Separator'
+    @description='Divider under the shadcn / Radix name: a role=separator rule with an explicit orientation and an optional centred label. Import it when a port already says Separator; the component and its writeup are Divider.'
+    @source="<Separator @label='or' />"
+  >
+    <:example>
+      <p class='sep-demo-line'>Sign in with a passkey</p>
+      <Separator @label='or' />
+      <p class='sep-demo-line'>Use a one-time code</p>
+    </:example>
+    <:api as |Args|>
+      <Args.String @name='orientation' @defaultValue='horizontal' @description='horizontal or vertical.' />
+      <Args.String @name='label' @value='or' @description='A centred label, horizontal only.' />
+    </:api>
+  </FreestyleUsage>
+  <style scoped>
+    .sep-demo-line {
+      margin: 0;
+      font-size: var(--text-ui-md, 0.78rem);
+    }
+  </style>
+</template>;
+
+export const DEMOS_SEPARATOR: Record<string, unknown> = {
+  Separator: SeparatorUsage,
+};

package/bundled-realms/pretui/components/session-prep.gts

@@ -0,0 +1,164 @@
+// Pretui — SessionPrep: the session lifecycle made visible before turn one.
+import Component from '@glimmer/component';
+import { on } from '@ember/modifier';
+import { Button } from './button';
+import { StepList } from './step-list';
+import type { StepItem, StepState } from './step-list';
+
+// ── SessionPrep ──────────────────────────────────────────────────────────
+// Everything an agent does before the first message — summarising the last
+// session, reading the file history, assembling context — happens whether or
+// not it is shown. The spec's law is that it must be shown, with a way out.
+//
+// The rail is `StepList` unmodified: it already owns the numbered markers,
+// the connector lines, the four-state palette, the per-step state text for
+// screen readers, and the derived "2 of 3 complete" summary wired with
+// `aria-describedby`. Re-implementing that here would have been a second,
+// worse copy — so SessionPrep is the frame, the note, and the escape hatch.
+//
+// Not built, and named rather than hidden (Law 7): per-step detail lines
+// ('41 messages scanned'). `StepItem` is `{label, state}` and widening it is
+// StepList's call, not this component's.
+
+export type SessionPrepState = 'pending' | 'running' | 'complete' | 'failed';
+
+export interface SessionPrepStep {
+  /** stable id — the {{#each}} key */
+  id: string;
+  /** what this preparation step does */
+  label: string;
+  /** where it is (default 'pending') */
+  state?: SessionPrepState;
+}
+
+const PREP_STATE: Record<SessionPrepState, StepState> = {
+  pending: 'upcoming',
+  running: 'current',
+  complete: 'complete',
+  failed: 'error',
+};
+
+export interface SessionPrepSignature {
+  Args: {
+    /** the preparation steps, in order */
+    steps: SessionPrepStep[];
+    /** heading (default 'Preparing your session') */
+    title?: string;
+    /** one line under the heading explaining why the wait exists */
+    note?: string;
+    /** fires when the reader skips the remaining preparation */
+    onSkip?: () => void;
+    /** skip-button wording (default 'Skip preparation') */
+    skipLabel?: string;
+    /** rail presentation, passed through to StepList (default 'steps') */
+    variant?: 'steps' | 'track';
+  };
+  Blocks: {
+    /** extra content below the rail — a model picker, a skill chooser */
+    default: [];
+  };
+  Element: HTMLElement;
+}
+
+export class SessionPrep extends Component<SessionPrepSignature> {
+  get steps(): SessionPrepStep[] {
+    return this.args.steps ?? [];
+  }
+  get railSteps(): StepItem[] {
+    return this.steps.map((step) => ({
+      label: step.label,
+      state: PREP_STATE[step.state ?? 'pending'],
+    }));
+  }
+  get current(): number {
+    let index = this.steps.findIndex((s) => s.state === 'running');
+    return index === -1 ? this.steps.length : index;
+  }
+  get title(): string {
+    return this.args.title ?? 'Preparing your session';
+  }
+  get skipLabel(): string {
+    return this.args.skipLabel ?? 'Skip preparation';
+  }
+  get done(): boolean {
+    return (
+      this.steps.length > 0 &&
+      this.steps.every((s) => s.state === 'complete' || s.state === 'failed')
+    );
+  }
+
+  skip = () => this.args.onSkip?.();
+
+  <template>
+    <section
+      class='pretui-prep'
+      data-done={{if this.done 'true'}}
+      aria-label={{this.title}}
+      data-test-pretui-session-prep
+      ...attributes
+    >
+      <header class='pretui-prep-head'>
+        <h3 class='pretui-prep-title'>{{this.title}}</h3>
+        {{#if @onSkip}}
+          <Button
+            @tone='neutral'
+            @appearance='plain'
+            @size='s'
+            data-test-pretui-session-prep-skip
+            {{on 'click' this.skip}}
+          >{{this.skipLabel}}</Button>
+        {{/if}}
+      </header>
+      {{#if @note}}
+        <p class='pretui-prep-note'>{{@note}}</p>
+      {{/if}}
+      <StepList
+        @steps={{this.railSteps}}
+        @current={{this.current}}
+        @variant={{@variant}}
+        @label='Session preparation'
+        @summary={{true}}
+      />
+      {{yield}}
+    </section>
+
+    <style scoped>
+      @layer PretComponent {
+        .pretui-prep {
+          display: flex;
+          flex-direction: column;
+          gap: var(--space-4, 11px);
+          padding: var(--space-4, 13px);
+          border-radius: var(--radius-surface, 14px);
+          background: var(--card);
+          box-shadow: var(
+            --pretui-shadow-card,
+            0 0 0 1px var(--border),
+            0 1px 2px rgb(0 0 0 / 0.08)
+          );
+        }
+        .pretui-prep-head {
+          display: flex;
+          align-items: center;
+          gap: 10px;
+          flex-wrap: wrap;
+        }
+        .pretui-prep-title {
+          margin: 0;
+          flex: 1;
+          min-width: 0;
+          font-size: 13px;
+          font-weight: 600;
+          letter-spacing: -0.01em;
+        }
+        .pretui-prep-note {
+          margin: 0;
+          max-width: 62ch;
+          font-size: var(--text-ui-sm, 11.5px);
+          line-height: 1.6;
+          color: var(--muted-foreground);
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/session-prep.md

@@ -0,0 +1,48 @@
+## What it is
+
+The waiting surface before a session is ready: a rail of preparation steps, a note explaining why the wait exists, and a way to skip it.
+
+## The contract
+
+```
+@steps (required) — the preparation steps, in order
+@title?     — heading. Default 'Preparing your session'
+@note?      — one line under the heading explaining WHY the wait exists
+@onSkip?    — fires when the reader skips the remaining preparation
+@skipLabel? — default 'Skip preparation'
+@variant?   — rail presentation, passed to StepList. Default 'steps'
+
+<:default> — extra content below the rail: a model picker, a skill chooser
+```
+
+**`@note` is where the wait is justified.** A progress rail with no explanation is a loading screen; one that says why it is doing what it is doing is an explanation. The arg exists to make that the expected shape rather than an afterthought.
+
+**Skip is offered, not assumed.** No `@onSkip`, no skip button — the same rule as every other conditional affordance in the kit.
+
+**The rail is a real StepList**, so step state derivation and its accessibility come along rather than being re-implemented.
+
+**`<:default>` is for choices made during the wait**, which is the design's one genuinely good idea: a wait is dead time, and filling it with the setup questions that would otherwise come next is better than a spinner.
+
+## Prior art
+
+The session-warmup screens in agent products.
+
+Where Pretui is better: the note and the yielded block. Most warmup screens are a spinner with a rotating message; making the explanation an argument and the wait usable turns it into a step rather than an obstacle.
+
+Where it is thinner: no time estimate, no per-step failure state — a step that fails is StepList's to express, and this block does not model recovery — and no resume after skip.
+
+## Accessibility
+
+- **The block is a named region** taking its name from `@title`.
+- **Step state comes from StepList**, which conveys complete, current and upcoming as text rather than by rail colour.
+- **The skip control is a real button**, so the wait is escapable by keyboard.
+- **`@note` is associated with the heading**, giving the reason a place that is announced rather than being loose text.
+- **Content in `<:default>` is reachable while the rail progresses**, which is the point — a wait that traps focus in a progress indicator wastes the reader's time twice.
+
+## Theming
+
+Everything comes from **StepList** and the kit's block tokens; the component adds no surface.
+
+That keeps a warmup screen looking like the application it is warming up rather than like a splash screen, which matters because it is the first thing anyone sees.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/session-prep.usage.gts

@@ -0,0 +1,122 @@
+// Pretui — SessionPrep usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { FreestyleUsage } from './freestyle-usage';
+import { Button } from './button';
+import { SessionPrep } from './session-prep';
+import type { SessionPrepStep } from './session-prep';
+
+// ── SessionPrep ──────────────────────────────────────────────────────────
+const PREP_VARIANTS = ['steps', 'track'];
+
+class SessionPrepUsage extends GlimmerComponent {
+  @tracked stage = 1;
+  @tracked variant = 'steps';
+  @tracked skipped = false;
+
+  setVariant = (variant: string) => (this.variant = variant);
+  advance = () => (this.stage = this.stage >= 3 ? 0 : this.stage + 1);
+  skip = () => (this.skipped = true);
+  reset = () => {
+    this.skipped = false;
+    this.stage = 1;
+  };
+
+  get variantValue(): 'steps' | 'track' {
+    return this.variant === 'track' ? 'track' : 'steps';
+  }
+  get steps(): SessionPrepStep[] {
+    let labels = [
+      'Summarise the previous session',
+      'Copy the file history',
+      'Prepare the session context',
+    ];
+    return labels.map((label, i) => ({
+      id: 's' + i,
+      label,
+      state:
+        i < this.stage ? 'complete' : i === this.stage ? 'running' : 'pending',
+    }));
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='SessionPrep'
+      @description='Everything an agent does before your first message — summarising the last session, reading the file history, assembling context — happens whether or not it is shown. The law the spec states is that it must be shown, with a way out. The rail is StepList, unmodified: it already owns the numbered markers, the connector lines, the four-state palette, the per-step state text for assistive tech, and the derived "2 of 3 complete" summary wired with aria-describedby. Re-implementing that here would have produced a second, worse copy — so SessionPrep is the frame, the note, and the escape hatch, and a walkthrough (Onboarding) and a preparation read as one system because they share a rail.'
+    >
+      <:example>
+        {{#if this.skipped}}
+          <p class='demo-log'>Preparation skipped — the session starts cold.</p>
+        {{else}}
+          <SessionPrep
+            @steps={{this.steps}}
+            @note='Nothing is sent to the model until this finishes. Skipping starts the session without the previous context.'
+            @variant={{this.variantValue}}
+            @onSkip={{this.skip}}
+          />
+        {{/if}}
+        <span class='demo-row'>
+          <Button
+            @tone='neutral'
+            @appearance='outlined'
+            @size='s'
+            {{on 'click' this.advance}}
+          >Advance a step</Button>
+          <Button
+            @tone='neutral'
+            @appearance='outlined'
+            @size='s'
+            {{on 'click' this.reset}}
+          >Reset</Button>
+        </span>
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='steps'
+          @description='{ id, label, state?: pending | running | complete | failed }. The states map onto StepList’s upcoming / current / complete / error, so the rail’s palette and its screen-reader state text come for free.'
+          @value={{this.steps}}
+        />
+        <Args.String
+          @name='variant'
+          @description='Rail presentation, passed straight to StepList. "steps" is the numbered rail; "track" is the segmented bar for a pipeline read at a glance.'
+          @value={{this.variant}}
+          @options={{PREP_VARIANTS}}
+          @onInput={{this.setVariant}}
+          @defaultValue='steps'
+        />
+        <Args.Base
+          @name='title / note / onSkip / skipLabel'
+          @description='The heading, the line explaining why the wait exists, and the escape hatch — omit @onSkip and no skip button renders, because an escape hatch that does nothing is worse than none.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @name='default'
+          @description='Extra content below the rail — a model picker, a skill chooser, the "1 Skill ▴" row from the session-chrome spec.'
+          @hideControls={{true}}
+        />
+        <Args.Base
+          @name='not built'
+          @description='Per-step detail lines ("41 messages scanned"). StepItem is { label, state } and widening it is StepList’s call, not this component’s — named here rather than hidden.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .demo-log {
+        margin: 0 0 var(--space-4, 11px);
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+      .demo-row {
+        display: inline-flex;
+        gap: 8px;
+        margin-top: var(--space-4, 11px);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_SESSION_PREP: Record<string, unknown> = {
+  SessionPrep: SessionPrepUsage,
+};

package/bundled-realms/pretui/components/sheet-toolbar.gts

@@ -0,0 +1,130 @@
+// Pretui — SheetToolbar: the toolbar that drives a Sheet through its yielded API.
+import Component from '@glimmer/component';
+import { on } from '@ember/modifier';
+import { Button } from './button';
+import { SearchInput } from './search-input';
+import { Token } from './token';
+import type { SheetApi } from './sheet';
+
+export interface SheetToolbarSignature {
+  Args: {
+    /** the SheetApi yielded by `<Sheet>`'s `<:toolbar>` block */
+    api: SheetApi;
+    /** name of the table, rendered as the strip's title */
+    title?: string;
+    /** hide the quick-filter field */
+    hideSearch?: boolean;
+    /** placeholder for the quick-filter field */
+    placeholder?: string;
+  };
+  Blocks: {
+    /** extra controls, right-aligned after the search field */
+    actions: [];
+  };
+  Element: HTMLDivElement;
+}
+
+/**
+ * `SheetToolbar` — the chrome strip for `<Sheet>`: title, live row count
+ * as a machine value (Law 3), quick filter, and a sort-reset that appears
+ * only when there is a sort to reset. Composed from Pretui's own
+ * SearchInput / Button / Token rather than boxel-grid's `<Toolbar>` suite,
+ * which is grid-scoped chrome with a colliding name.
+ */
+export class SheetToolbar extends Component<SheetToolbarSignature> {
+  get counts(): string {
+    let api = this.args.api;
+    if (!api) {
+      return '';
+    }
+    return api.visibleCount === api.totalCount
+      ? `${api.totalCount}`
+      : `${api.visibleCount}/${api.totalCount}`;
+  }
+  get sorted(): boolean {
+    return !!this.args.api?.sort;
+  }
+  get query(): string {
+    return this.args.api?.query ?? '';
+  }
+  get placeholder(): string {
+    return this.args.placeholder ?? 'Filter rows…';
+  }
+  setQuery = (next: string): void => {
+    this.args.api?.setQuery(next);
+  };
+  clearSort = (_event: Event): void => {
+    this.args.api?.clearSort();
+  };
+
+  <template>
+    <div class='pretui-sheet-toolbar' data-test-pretui-sheet-toolbar ...attributes>
+      <div class='pretui-sheet-toolbar-id'>
+        {{#if @title}}
+          <span class='pretui-sheet-toolbar-title'>{{@title}}</span>
+        {{/if}}
+        <Token @value={{this.counts}} />
+        <span class='pretui-sheet-toolbar-unit'>rows</span>
+      </div>
+      <div class='pretui-sheet-toolbar-tools'>
+        {{#if this.sorted}}
+          <Button
+            @tone='neutral'
+            @appearance='plain'
+            @size='xs'
+            {{on 'click' this.clearSort}}
+          >Clear sort</Button>
+        {{/if}}
+        {{#unless @hideSearch}}
+          <SearchInput
+            @value={{this.query}}
+            @placeholder={{this.placeholder}}
+            @onInput={{this.setQuery}}
+          />
+        {{/unless}}
+        {{yield to='actions'}}
+      </div>
+    </div>
+
+    <style scoped>
+      @layer PretComponent {
+        .pretui-sheet-toolbar {
+          display: flex;
+          flex-wrap: wrap;
+          align-items: center;
+          justify-content: space-between;
+          gap: var(--space-3, 8px);
+          min-width: 0;
+        }
+        .pretui-sheet-toolbar-id {
+          display: flex;
+          align-items: baseline;
+          gap: 4px;
+          min-width: 0;
+        }
+        .pretui-sheet-toolbar-title {
+          font-size: var(--text-ui-lg, 13.5px);
+          font-weight: 600;
+          letter-spacing: var(--track-heading, -0.01em);
+          margin-right: 3px;
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+        }
+        .pretui-sheet-toolbar-unit {
+          font-family: var(--font-mono);
+          font-size: var(--text-ui-xs, 11px);
+          letter-spacing: var(--track-eyebrow, 0.08em);
+          text-transform: uppercase;
+          color: var(--muted-foreground);
+        }
+        .pretui-sheet-toolbar-tools {
+          display: flex;
+          align-items: center;
+          gap: var(--space-2, 6px);
+          min-width: 0;
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/sheet-toolbar.md

@@ -0,0 +1,51 @@
+## What it is
+
+**Sheet**'s chrome strip: a title, a quick-filter field, and a slot for actions, driven by the `SheetApi` the grid yields. Use it inside `<Sheet>`'s `<:toolbar>` block. It is not a general-purpose toolbar — for a page header use **Toolbar**, and for a row of related actions use **ButtonGroup** or **ActionBar**.
+
+## The contract
+
+```
+@api: SheetApi   (required — the object yielded by <Sheet>'s <:toolbar> block)
+@title?, @hideSearch?, @placeholder?
+<:actions>
+```
+
+**`@api` is the whole coupling.** The toolbar does not own the filter query, the sort, or anything else; it reads and writes through the api object the grid hands it. That is why it is a separate component rather than args on `Sheet`: a caller who wants different chrome writes their own and drives the same api, and a caller who wants the default writes one line.
+
+**The arg is `@hideSearch`, not its inverse** — the quick filter is on by default, because a grid without one is unusable past about thirty rows and defaulting it off means every call site remembers.
+
+The search field is the kit's **SearchInput**, so it matches every other search in the product and inherits its clear affordance.
+
+## Prior art
+
+**boxel-grid ships its own `<Toolbar>`, and it is deliberately unused** — the source says so plainly, along with `<Spinner>`, `<Toast>` and `<GridOverlay>`: Pretui has its own and the names collide. That is the honest reason this component exists, and it is a reasonable one: a toolbar built from the kit's **SearchInput** and **Button** looks like the rest of the product, and the engine's does not.
+
+Against the field: **AG Grid** ships a substantial toolbar with column chooser, export, grouping and filter panels. **TanStack Table** ships no UI at all. **React Spectrum's `TableView`** has no toolbar; sorting and filtering are the caller's chrome.
+
+So this sits at the minimal end deliberately. What it is missing versus AG Grid, and what you will reach for first: **a column chooser** (there is no way to hide or reorder columns), **export**, and **a filter panel** (the quick filter is a single string across all columns — there are no per-column filters, because the engine builds the table with the core row model only and `Sheet` filters the array itself).
+
+Where it is better than rolling your own strip beside a grid: the api coupling means the filter's state and the grid's are the same state, and there is no chance of the toolbar showing a query the grid is not applying.
+
+## Accessibility
+
+No APG pattern applies, and — as with **Toolbar** — it is worth being explicit that **this is not an ARIA toolbar**. The APG **Toolbar** pattern means `role="toolbar"`, a single tab stop and arrow-key traversal; a strip with a title, one text field and two buttons should not have it, and does not.
+
+What matters here is its relationship to the grid, and that is where the notable behaviour lives:
+
+- **The strip sits outside the grid element**, so the engine's Tab binding, which listens on the grid root, never sees its keys: Tab moves through the filter and actions like any other content. Sheet's carve-out is for the sort buttons in the header row, which do sit inside the grid.
+- **The quick filter is a SearchInput**, and inherits its gaps: no Escape-to-clear, no `role="search"` landmark, and no accessible name unless one is passed.
+
+Gaps:
+
+- **Filter results are announced by Sheet's live status line, not by this component.** That is the right division — the count belongs to the grid — but it means a SheetToolbar used outside a Sheet announces nothing.
+- **`@title` is a plain span**, not a heading. The grid takes its name from Sheet's `@label`, not from this title, so give the two the same words.
+- **No search-results relationship.** The quick filter and the grid are connected only through the api; `aria-controls` from the input to the grid would state it.
+- Target sizes in a dense strip should be checked against WCAG **2.5.8**'s 24×24 minimum.
+
+## Theming
+
+`--inset` or `--card` for the strip, `--border` and `--line-strong` for its rule against the grid, `--foreground` and `--muted-foreground` for the title, plus **SearchInput**'s and **Button**'s full token sets.
+
+Because **Sheet** turns the engine's own chrome off (`@chrome='none'`) and paints the hairline and depth itself, this strip and the grid's header band must be themed together — they are two components forming one visual object, and a theme that gives them different surfaces will produce a visible seam exactly where the engine's un-themable shadow used to be.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.