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

package/bundled-realms/pretui/components/usage-css-variable.md

@@ -0,0 +1,48 @@
+## What it is
+
+The CSS-variable row of a **FreestyleUsage** page — `Css.Basic`, yielded by the `<:cssVars>` block. It documents a custom property the component reads, and in the property lens lets you change it live and watch the example re-dress. Use it for every token a component consumes. For component _arguments_, the `Args.*` family (**UsageString**, **UsageBool**, **UsageNumber**, **UsageArray**, **UsageObject**, **UsageArgument**).
+
+## The contract
+
+```
+@mode? 'doc' | 'prop'
+@name?, @description?, @defaultValue?
+@value?: string | null
+```
+
+**This is the only Usage component whose subject is not an argument**, and it has its own block (`<:cssVars>`) for that reason. A component's theming surface is a real part of its contract — arguably the part most likely to be undocumented — and giving it a first-class row means a usage page can state which tokens matter rather than leaving a reader to grep the stylesheet.
+
+**The name prints bare, with no sigil**, because a custom-property name already carries `--`. The sibling `Args.*` rows print `@name`, and yields print `{{name}}` — three visual forms so a reader can tell an argument from a block from a token at a glance, without the page author annotating anything.
+
+**`@value` is `string | null`** — a CSS value is text, and `null` means "not overridden", which is meaningfully different from an empty string.
+
+Note there is no required/optional pair here, unlike every other row in the family: a token is never required.
+
+## Prior art
+
+**ember-freestyle's `Freestyle::Usage::CssVariable`** is the upstream; the invocation surface is verbatim, including the `<:cssVars as |Css|>` block name.
+
+**Storybook has no equivalent.** Its controls are props; CSS custom properties are documented, if at all, in an MDX page a human wrote and nobody keeps current. **Web Awesome's** docs list CSS custom properties and CSS parts in a static table per component — good documentation, not live. **Radix** documents its `--radix-*` output properties in prose.
+
+So the live-token knob is genuinely uncommon, and it is the right shape for a design system: **the surface that documents a component also lets you re-theme it in place.** Combined with **ThemeFrame**, a reader can switch theme _and_ poke an individual token, which is a much faster way to understand a component's theming surface than reading a table.
+
+Where it is thin: the value is free text, so there is no colour picker for a colour token, no length control for a dimension, and no validation — typing `blue!` silently produces an invalid declaration that CSS drops. **ColorPicker** and **Slider** are both in the kit and neither is wired.
+
+## Accessibility
+
+No pattern of its own; it renders a text control plus a table row.
+
+Gaps:
+
+- **The control is free text with no format guidance.** A token expecting a colour, a length, a duration and a shadow all get the same bare **Input** with no hint — a **WCAG 3.3.2** gap, and one that bites here because CSS values are exactly the kind of syntax people get wrong.
+- **An invalid value fails silently.** CSS drops a bad declaration, so the example simply does not change and nothing says why — no `aria-invalid`, no message (**WCAG 3.3.1**). That is arguably the worst failure mode in the family: the knob appears to do nothing.
+- **The control's accessible name** depends on the property rail wiring a `<label for>`; **Input** generates none of its own.
+- **Changing a token re-dresses the example silently** — no live region.
+- **Token names are punctuation-heavy** (`--pretui-shadow-overlay`) and are announced character by character or as run-together words depending on the reader. Nothing can be done about that, but it argues for `@description` carrying a human phrase.
+- **Changing a colour token can change the example's contrast**, and there is no contrast readout — a reader exploring theme values gets no signal that a combination has become unreadable. A computed ratio would be the single most valuable addition to this component, and it is the same gap **ColorPicker** has.
+
+## Theming
+
+**Input**'s tokens for the control, **Table**'s for the doc row, and the property rail's label voice. The default-value cell should use **Token**'s mono treatment — a CSS value is a machine value, Law 3.
+
+Nothing of its own, which is fitting for the component whose subject _is_ theming. Note the recursion worth being aware of: this row can change a token that the row itself reads, so a reader overriding `--muted-foreground` re-dresses the property list they are typing into.

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

@@ -0,0 +1,127 @@
+// Pretui — UsageNumber: a number argument with its knob.
+import Component from '@glimmer/component';
+import { guidFor } from '@ember/object/internals';
+import { Input } from './input';
+import { Slider } from './slider';
+import { UsageArgument } from './usage-argument';
+import { PropReadOnly, PropRow, isPresent, readOnlyText } from '../internal/freestyle';
+import type { ArgsMode } from '../internal/freestyle';
+
+// ── Freestyle::Usage::Number ─────────────────────────────────────────────
+export interface UsageNumberSignature {
+  Args: {
+    mode?: ArgsMode;
+    name?: string;
+    description?: string;
+    defaultValue?: unknown;
+    required?: boolean;
+    optional?: boolean;
+    hideControls?: boolean;
+    value?: number | null;
+    min?: number;
+    max?: number;
+    step?: number;
+    onInput?: (value: number | null) => void;
+  };
+  Element: HTMLElement;
+}
+
+export class UsageNumber extends Component<UsageNumberSignature> {
+  get isProp() {
+    return this.args.mode === 'prop';
+  }
+  get shouldRenderRangeInput() {
+    return isPresent(this.args.min) && isPresent(this.args.max);
+  }
+  get hasControl() {
+    return typeof this.args.onInput === 'function';
+  }
+  get readOnlyValue() {
+    return readOnlyText(this.args.value ?? this.args.defaultValue);
+  }
+  get numValue() {
+    return this.args.value ?? undefined;
+  }
+  get textValue() {
+    return this.args.value == null ? undefined : String(this.args.value);
+  }
+  controlId = `${guidFor(this)}-control`;
+  // the rail labels the text field; Slider names itself with @label
+  get labelFor() {
+    return this.hasControl && !this.shouldRenderRangeInput
+      ? this.controlId
+      : undefined;
+  }
+  onSlide = (v: number) => {
+    this.args.onInput?.(v);
+  };
+  onText = (v: string) => {
+    this.args.onInput?.(v ? parseFloat(v) : null);
+  };
+  <template>
+    {{#if this.isProp}}
+      {{#unless @hideControls}}
+        <PropRow
+          @label={{@name}}
+          @required={{@required}}
+          @controlId={{this.labelFor}}
+        >
+          {{#if this.hasControl}}
+            {{#if this.shouldRenderRangeInput}}
+              <div class='numrange'>
+                <Slider
+                  @value={{this.numValue}}
+                  @min={{@min}}
+                  @max={{@max}}
+                  @step={{@step}}
+                  @label={{@name}}
+                  @onValueChange={{this.onSlide}}
+                />
+                <span class='numrange-readout'>{{@value}}</span>
+              </div>
+            {{else}}
+              <Input
+                @type='number'
+                @value={{this.textValue}}
+                @onInput={{this.onText}}
+                @controlId={{this.controlId}}
+                min={{@min}}
+                max={{@max}}
+                step={{@step}}
+              />
+            {{/if}}
+          {{else}}
+            <PropReadOnly @value={{this.readOnlyValue}} />
+          {{/if}}
+        </PropRow>
+      {{/unless}}
+    {{else}}
+      <UsageArgument
+        @type='Number'
+        @name={{@name}}
+        @description={{@description}}
+        @required={{@required}}
+        @defaultValue={{@defaultValue}}
+      />
+    {{/if}}
+    <style scoped>
+      .numrange {
+        --numrange-readout-min-w: 1.875rem;
+
+        display: flex;
+        align-items: center;
+        gap: var(--boxel-sp-xs);
+      }
+      .numrange > :first-child {
+        flex: 1;
+      }
+      .numrange-readout {
+        font-family: var(--font-mono);
+        font-size: var(--boxel-font-size-xs);
+        min-width: var(--numrange-readout-min-w);
+        text-align: end;
+        font-variant-numeric: tabular-nums;
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/usage-number.md

@@ -0,0 +1,48 @@
+## What it is
+
+The numeric argument row of a **FreestyleUsage** page — `Args.Number`. Docs lens: a table row. Property lens: a live control bound to the example, with `@min`/`@max`/`@step` driving it. Use it for any number-valued argument. For a string, **UsageString**; a boolean, **UsageBool**; for something with no manipulable value, **UsageArgument**.
+
+## The contract
+
+```
+@mode? 'doc' | 'prop'
+@name?, @description?, @defaultValue?, @required?, @optional?, @hideControls?
+@value?: number | null
+@min?, @max?, @step?
+@onInput?(value: number | null)
+```
+
+**`@value` and `@onInput` are `number | null`, not `number`.** A knob must be able to express "not set" — an argument left off entirely — and `null` is the honest representation. `NaN` and the empty string are both worse: the first renders as visible garbage, the second forces every consumer to parse.
+
+**`@min`/`@max`/`@step` are what make the control usable.** With bounds, a numeric knob can be a **Slider** — drag it and watch the example respond, which is the single most useful interaction on a documentation page. Without them, it falls back to a typed field. So supplying bounds is not decoration; it changes the affordance.
+
+**`@mode` is the lens.** The `<:api>` block is authored once and rendered twice — property list (`prop`) and API table (`doc`).
+
+## Prior art
+
+**ember-freestyle's `Freestyle::Usage::Number`** is the upstream; the invocation surface is verbatim.
+
+**Storybook's `number` and `range` controls** are the analogue, and — as with **UsageString**'s options — Storybook makes them two separate declarations (`control: { type: 'range', min, max, step }`), where here supplying the bounds is what selects the presentation. Fewer ways for the control type and its bounds to disagree.
+
+The Pretui port's improvement, consistent across the family: **the control is the kit's own Slider or Input**, so the documentation surface dogfoods the components it documents.
+
+Where it is behind Storybook: no unit annotation (a number that means pixels, seconds or a ratio looks identical), and no `Intl` formatting — a numeric knob shows a bare number, which is the same gap **NumberInput** has in the controls territory.
+
+## Accessibility
+
+No pattern of its own; it renders a **Slider** or an **Input** plus a table row, and inherits their contracts.
+
+Gaps, and two are inherited and consequential in this context:
+
+- **The number field is labeled by the rail.** Without bounds the knob is an **Input**, and the property row's label is its `<label for>`, so clicking the name focuses the field; `@min`, `@max` and `@step` reach the field too.
+- **The slider names itself.** With both bounds it is a **Slider**, which takes no `@controlId`, so it is named by `@label` (the argument name) and the rail stays plain text.
+- **No unit is announced.** Slider supports `@formatValue` for `aria-valuetext`, but UsageNumber has no unit argument to pass, so a knob announces "8" where "8 pixels" is meant.
+- **Changing a knob re-renders the example silently** — no live region, no confirmation.
+- **`@required`** adds a visually hidden "(required)" beside the asterisk, in the property row and the doc row.
+- **`null` versus `0`** is not distinguishable in the control's announcement; an unset numeric argument and one explicitly set to zero read the same.
+
+## Theming
+
+**Slider**'s or **Input**'s tokens for the control, **Table**'s for the doc row, and the property rail's mono label in `--muted-foreground`. The readout beside a slider is mono at a fixed minimum width (`--numrange-readout-min-w`), so the slider doesn't shift as the value changes.
+
+A property list shows sliders at several positions at once, so a thumb that disappears at either end of the track makes the knob unreadable exactly where the bounds are being demonstrated; check the thumb against the track in both schemes.

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

@@ -0,0 +1,58 @@
+// Pretui — UsageObject: a read-only object argument.
+import Component from '@glimmer/component';
+import { JsonTree } from './json-tree';
+import { UsageArgument } from './usage-argument';
+import { PropRow } from '../internal/freestyle';
+import type { ArgsMode } from '../internal/freestyle';
+
+// ── Freestyle::Usage::Object (read-only) ─────────────────────────────────
+export interface UsageObjectSignature {
+  Args: {
+    mode?: ArgsMode;
+    name?: string;
+    description?: string;
+    defaultValue?: unknown;
+    required?: boolean;
+    optional?: boolean;
+    hideControls?: boolean;
+    value?: unknown;
+  };
+  Element: HTMLElement;
+}
+
+export class UsageObject extends Component<UsageObjectSignature> {
+  get isProp() {
+    return this.args.mode === 'prop';
+  }
+  <template>
+    {{#if this.isProp}}
+      {{#unless @hideControls}}
+        <PropRow @label={{@name}} @required={{@required}}>
+          <JsonTree
+            @value={{@value}}
+            @label={{@name}}
+            @hideToolbar={{true}}
+            @pageSize={{25}}
+            class='jsonviewer'
+          />
+        </PropRow>
+      {{/unless}}
+    {{else}}
+      <UsageArgument
+        @type='Object'
+        @name={{@name}}
+        @description={{@description}}
+        @required={{@required}}
+        @defaultValue={{@defaultValue}}
+      />
+    {{/if}}
+    <style scoped>
+      /* JsonTree brings its own surface; the knob channel is all that is
+         needed here. */
+      .jsonviewer {
+        --pretui-json-max-height: 7.5rem;
+        --pretui-json-indent: var(--boxel-sp-sm);
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/usage-object.md

@@ -0,0 +1,48 @@
+## What it is
+
+The object argument row of a **FreestyleUsage** page — `Args.Object`. Docs lens: a table row. Property lens: the value rendered as an inspectable JSON tree. Use it for any structured argument — an options array, a config bag, a record — that the simpler knobs cannot express. For a plain string, **UsageString**; a list of strings, **UsageArray**; a value with no manipulable form at all, **UsageArgument**.
+
+## The contract
+
+```
+@mode? 'doc' | 'prop'
+@name?, @description?, @defaultValue?, @required?, @optional?, @hideControls?
+@value?: unknown
+```
+
+**Note what is absent: there is no input callback.** Every other typed knob in the family round-trips a value; this one **displays** and does not edit. That is the honest boundary — a generic structured editor is a component in its own right, and inventing a half one inside a documentation row would produce a knob that can corrupt the example it is demonstrating.
+
+**`@value` is `unknown`**, the widest type in the family, and goes straight to `JsonTree`, which takes plain JSON-safe data. A circular structure is not handled.
+
+**`@mode` is the lens.** The `<:api>` block is authored once and rendered twice — property list (`prop`) and API table (`doc`).
+
+This is where **the kit's most common array argument lands**: an options list of `{ value, label }`, taken by **Select**, **MultiSelect**, **RadioGroup**, **SegmentedControl**, **FilterChips** and **SortDropdown**, is documented here rather than by **UsageArray**, which is `string[]` only.
+
+## Prior art
+
+**ember-freestyle's `Freestyle::Usage::Object`** is the upstream; the invocation surface is verbatim.
+
+**Storybook's `object` control** is the analogue and it _does_ edit — a JSON textarea that parses on change, plus a tree view. That is more capability and it is genuinely useful for exploring a data-driven component; it is also the control most likely to leave a story in a broken state after a typo, which is presumably why the port stopped short.
+
+Where the Pretui version is better: **a real tree view rather than a blob of JSON text.** `JsonTree` gives collapsible nodes, so a reader inspecting a fifty-row options array sees its shape rather than scrolling a wall. Storybook's editing textarea makes you read the raw serialization.
+
+Where it is behind: no editing (above). `JsonTree` rows do copy their path and value from the keyboard (Ctrl/Cmd+Shift+C and Ctrl/Cmd+C).
+
+## Accessibility
+
+No pattern of its own; it renders a JSON tree plus a table row.
+
+The tree is where the accessibility questions are, and they are worth checking rather than assuming, because JSON viewers are routinely built as nested `<div>`s with click handlers:
+
+- **A collapsible tree should be the APG Tree View pattern** — `role="tree"`, `role="treeitem"`, `aria-expanded` on branches (and **absent**, not `false`, on leaves), `aria-level`/`aria-posinset`/`aria-setsize`, a roving tabindex so the tree is one tab stop, and Right/Left/Up/Down/Home/End. `JsonTree` implements it: `role="tree"` and `treeitem`, `aria-level`/`aria-posinset`/`aria-setsize`, `aria-expanded` on branches and a roving tabindex.
+- **If it is not a tree, it is at minimum a set of disclosure buttons**, each needing `aria-expanded` and a name that says what expands.
+- **A large object is a lot of announced text.** Deep JSON read linearly is close to unusable; the collapsed-by-default state is the accessibility feature, and expanding should be the user's choice.
+- **Punctuation-heavy content** — braces, brackets, quotes, colons — is announced inconsistently and often verbosely. A tree with structural nesting instead of visible punctuation reads far better.
+- **`@required`** adds a visually hidden "(required)" beside the asterisk, in the property row and the doc row.
+- **Nothing is editable**, so there is no invalid state to announce — which is one genuine upside of the read-only decision.
+
+## Theming
+
+`JsonTree`'s tokens for the tree (mono voice, key and value inks, the disclosure affordance), **Table**'s for the doc row, and the property rail's mono label. The knob caps the tree at 7.5rem tall and sets its indent to `--boxel-sp-sm`; rows keep JsonTree's own height.
+
+The key/value ink distinction is the thing to check in each theme: a JSON tree is read by scanning for keys, and if `--foreground` and `--muted-foreground` converge, the structure flattens into an undifferentiated block of mono text.

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

@@ -0,0 +1,89 @@
+// Pretui — UsageString: a string argument with its knob.
+import Component from '@glimmer/component';
+import { guidFor } from '@ember/object/internals';
+import { Input } from './input';
+import { Select } from './select';
+import { UsageArgument } from './usage-argument';
+import { PropReadOnly, PropRow, readOnlyText } from '../internal/freestyle';
+import type { ArgsMode } from '../internal/freestyle';
+
+// ── Freestyle::Usage::String ─────────────────────────────────────────────
+export interface UsageStringSignature {
+  Args: {
+    mode?: ArgsMode;
+    name?: string;
+    description?: string;
+    defaultValue?: unknown;
+    required?: boolean;
+    optional?: boolean;
+    hideControls?: boolean;
+    value?: string | null;
+    options?: string[];
+    onInput?: (value: string) => void;
+  };
+  Element: HTMLElement;
+}
+
+export class UsageString extends Component<UsageStringSignature> {
+  get isProp() {
+    return this.args.mode === 'prop';
+  }
+  get selectOptions() {
+    return (this.args.options ?? []).map((v) => ({ value: v, label: v }));
+  }
+  get valueStr() {
+    return this.args.value ?? undefined;
+  }
+  get hasControl() {
+    return typeof this.args.onInput === 'function';
+  }
+  get readOnlyValue() {
+    return readOnlyText(this.args.value ?? this.args.defaultValue);
+  }
+  controlId = `${guidFor(this)}-control`;
+  // the rail labels the control when there is one
+  get labelFor() {
+    return this.hasControl ? this.controlId : undefined;
+  }
+  callOnInput = (v: string) => {
+    this.args.onInput?.(v);
+  };
+  <template>
+    {{#if this.isProp}}
+      {{#unless @hideControls}}
+        <PropRow
+          @label={{@name}}
+          @required={{@required}}
+          @controlId={{this.labelFor}}
+        >
+          {{#if this.hasControl}}
+            {{#if @options}}
+              <Select
+                @options={{this.selectOptions}}
+                @value={{this.valueStr}}
+                @onValueChange={{this.callOnInput}}
+                @controlId={{this.controlId}}
+              />
+            {{else}}
+              <Input
+                @value={{this.valueStr}}
+                @onInput={{this.callOnInput}}
+                @controlId={{this.controlId}}
+              />
+            {{/if}}
+          {{else}}
+            <PropReadOnly @value={{this.readOnlyValue}} />
+          {{/if}}
+        </PropRow>
+      {{/unless}}
+    {{else}}
+      <UsageArgument
+        @type='String'
+        @name={{@name}}
+        @description={{@description}}
+        @required={{@required}}
+        @defaultValue={{@defaultValue}}
+      />
+    {{/if}}
+  </template>
+}

package/bundled-realms/pretui/components/usage-string.md

@@ -0,0 +1,46 @@
+## What it is
+
+The string argument row of a **FreestyleUsage** page — `Args.String`. In the docs lens it is a table row; in the property lens it is a live control bound to the example. With `@options` it renders a **Select**; without, an **Input**. Use it for any string-valued argument. For a boolean, **UsageBool**; a number, **UsageNumber**; a list, **UsageArray**; anything structural, **UsageObject** or **UsageArgument**.
+
+## The contract
+
+```
+@mode? 'doc' | 'prop'
+@name?, @description?, @defaultValue?, @required?, @optional?, @hideControls?
+@value?: string | null
+@options?: string[]
+@onInput?(value: string)
+```
+
+**`@options` turning an Input into a Select is the whole design decision.** A string argument with a known set of values is an enum in everything but the type system, and giving it a free-text box invites typos that silently produce a broken example. `selectOptions` maps the plain string array into the `{ value, label }` shape **Select** wants, so a page author writes `@options={{array 'sm' 'md' 'lg'}}` and gets a proper picker.
+
+**`@mode` is the lens.** The `<:api>` block is authored once and rendered twice — as the right-hand property list (`prop`) and as the API table (`doc`) below. This component knows both.
+
+`@hideControls` suppresses the knob while keeping the documentation, for an argument that is documented but not safely manipulable live.
+
+## Prior art
+
+**ember-freestyle's `Freestyle::Usage::String`** is the upstream; the invocation surface is verbatim.
+
+**Storybook's `text` and `select` controls** are the analogue, and they are chosen separately in `argTypes` — you declare `control: { type: 'select' }` and supply `options`. Here supplying `options` _is_ the declaration, which is one fewer thing to get wrong and one fewer way for a control's type and its options to disagree.
+
+Where the Pretui port improves on the freestyle upstream: **the control is the kit's own Select or Input**, so the knob is the same component the page may be documenting. A usage page for **Select** drives itself with a Select — which is a genuine forcing function, since a broken control breaks its own documentation immediately and visibly.
+
+Where it is behind Storybook: no `radio`/`inline-radio` presentation for small option sets (**SegmentedControl** or **RadioGroup** would be the natural choices and neither is wired), no `null`-vs-empty-string distinction in the UI despite the type admitting both, and no validation.
+
+## Accessibility
+
+No pattern of its own; it renders one of two kit controls plus a table row.
+
+Gaps:
+
+- **The rail is the control's `<label for>`**, so the visible argument name is the control's accessible name, and clicking it focuses the Input. The Select's trigger takes the same label through `aria-labelledby`.
+- **`@required`** adds a visually hidden "(required)" beside the asterisk, so it is part of the label, the same fix **FormField** made.
+- **Changing a knob re-renders the example silently.** No live region announces the effect, so a screen-reader user changing `@size` from `md` to `lg` gets no confirmation that anything happened. This belongs to **FreestyleUsage** but is felt here.
+- **Free-text mode has no format guidance.** A string argument expecting a CSS length or an ISO date offers a bare Input with no hint (**WCAG 3.3.2**), and `@description` lives in the _other_ lens — so the docs table has the explanation and the knob does not.
+- **The two lenses are not linked.** A reader in the property list has no route to the row documenting the same argument.
+- **`@options` with many values** produces a Select that auto-enables search past seven — inherited, and good.
+
+## Theming
+
+**Select** and **Input** token sets for the control, **Table**'s for the doc row, and the property rail's label: mono at `--boxel-font-size-xs` in `--muted-foreground`, which measures 6.9:1 on `--card` in light and 5.6:1 in dark.

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

@@ -0,0 +1,16 @@
+// Pretui — UsageYield: a doc-only row for a yielded block.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { UsageArgument } from './usage-argument';
+import type { UsagePresetSignature } from '../internal/freestyle';
+
+export const UsageYield: TemplateOnlyComponent<UsagePresetSignature> =
+  <template>
+    <UsageArgument
+      @mode={{@mode}}
+      @type='Yield'
+      @name={{@name}}
+      @description={{@description}}
+      @required={{@required}}
+      @defaultValue={{@defaultValue}}
+    />
+  </template>;