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

package/bundled-realms/pretui/components/url-input.md

@@ -0,0 +1,58 @@
+## What it is
+
+A URL field with format validation that surfaces after the user has touched it. Use it for a link a user supplies — a repo, a homepage, a webhook target. If the value is an internal card reference, that is **Lookup** or **RecordPill**, not a URL. If you are showing a URL rather than collecting one, **Token** with a **CopyButton** reads better.
+
+## The contract
+
+```
+@value?, @placeholder?, @disabled?, @required?, @controlId?
+@onInput?(value: string)
+@onValidation?(error: string | null)
+```
+
+Same shape as **EmailInput** and **PhoneInput** — the typed-input family is deliberately interchangeable.
+
+**The `touched` gate is the interesting bit here**, and unlike its siblings it is implemented in the Pretui layer rather than delegated. The component tracks `touched` and derives a three-state `state`: `'initial'` until the user has interacted at all, then `'invalid'` if there is an error, then `'valid'` if there is a value, else `'initial'` again. So a pristine empty field is neutral, a field the user typed a good URL into gets a positive state, and only a touched field with a bad value goes red.
+
+That three-state model is worth noting because it is richer than the rest of the family: **EmailInput** and **PhoneInput** hand you an error and let the underlying engine decide when to show it; **UrlInput** owns the display gate itself. The practical difference is that a valid URL here gets affirmative feedback, which the others do not give.
+
+`@onValidation(error | null)` is the same split-out channel as the rest of the family, so a call site that ignores validation is written like a plain **Input**.
+
+## Prior art
+
+**Web Awesome** has no URL input — `wa-input type="url"` with native constraint validation. **React Spectrum** likewise: `TextField type="url"` plus a `validate` function. **shadcn** none. So, as with the rest of the family, the comparison is against native `type="url"` and the browser's own bubble.
+
+Two ways Pretui is better than the native baseline:
+
+- **The error is styled, positioned and yours.** Native constraint validation fires on submit and pops a UA bubble that cannot be styled, cannot be positioned, and is announced inconsistently. Here the error is a value you route wherever it belongs — usually a **FormField**.
+- **The touched gate** (above). Native validity is available from the first keystroke, so a naive implementation turns the field red while the user is typing "htt". Gating on touch is the behaviour every serious form implements by hand.
+
+Where it is behind: **no normalisation.** A user typing `example.com` gets a validation error rather than `https://example.com`; a user pasting a URL with tracking parameters gets it stored verbatim. Every mature URL field prepends a scheme when one is missing, and this does not. That is the clearest addition.
+
+Also missing versus a richer field: no scheme restriction (you cannot require `https`), no link-preview affordance, and no "open in new tab" companion.
+
+## Accessibility
+
+Native `<input type="url">`; no APG pattern.
+
+What is right: `type="url"` gives mobile keyboards the `/` and `.com` keys and gives assistive tech the field's purpose. The touched gate means a screen-reader user is not told the field is invalid before they have entered anything.
+
+Gaps:
+
+- **The valid state is visual only.** `state='valid'` produces a positive dress and announces nothing — there is no `aria-describedby` text saying the URL is well-formed. That is a smaller loss than a silent _error_ would be, but it means sighted and non-sighted users are getting different information.
+- **The ARIA wiring for the error is boxel-ui's**, and this wrapper adds none — verify against your boxel-ui version whether `@errorMessage` reaches `aria-describedby`. The ecosystem's settled choice is `aria-describedby` over `aria-errormessage`, which VoiceOver and NVDA still handle poorly.
+- **No accessible name of its own.** Outside **Field**/**FormField** and without an explicit `aria-label`, the field is unnamed.
+- **No `autocomplete="url"`**, and no arg for it. **WCAG 1.3.5 Identify Input Purpose** (AA) applies when the field collects the user's own URL. Family-wide hole, passed through `...attributes` for now.
+- **No format instruction.** "Enter a URL" without saying whether a scheme is required is a **WCAG 3.3.2** gap — and it bites harder here than elsewhere because the answer is "yes, and we will not add it for you". Use **FormField**'s `@description`.
+- **WCAG 3.3.3 Error Suggestion** asks for a correction where one is possible, and prepending a missing scheme is exactly such a correction. Not doing the normalisation is therefore an accessibility gap as well as a usability one.
+- **`@disabled` uses the native attribute**, removing the field from the tab order.
+
+## Theming
+
+Consumed: `--field`, `--input`, `--primary` (focus ring via `--ring`), `--ink-3` (placeholder), `--control-h`, `--radius`, `--text-ui-md`, `--text-ui-sm`, `--text-ui-xs`, `--track-ui`. The valid state additionally reads `--success` through the boxel-ui validation channel.
+
+Forwarded into boxel-ui through the `--boxel-*` channel, matching **Input**'s metrics exactly so the family aligns in a shared form.
+
+`--success` is the token to check per theme here: unlike the rest of the family, this component has an affirmative state, and a theme that tunes `--success` for a **Delta**'s 11.5px mono ink may find it too light as a field hairline. The invalid dress still arrives from an enclosing **Field** by repointing `--border`/`--background`, so error styling is a theme concern defined once.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/url-input.usage.gts

@@ -0,0 +1,97 @@
+// Pretui — UrlInput usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { UrlInput } from './url-input';
+
+// ── UrlInput — typed-input split, fresh page ─────────────────────────────
+// Type-specific behavior: EmailInput-shaped validation (boxel-ui has no
+// URL engine, so the checks are Pretui's own — URL parse + http/https
+// protocol, blur-gated, live revalidation once touched).
+class UrlInputUsage extends Component {
+  @tracked value = '';
+  @tracked lastError: string | null = null;
+  @tracked placeholder = 'https://example.com';
+  @tracked disabled = false;
+  @tracked required = false;
+  setValue = (v: string) => (this.value = v);
+  setError = (e: string | null) => (this.lastError = e);
+  setPlaceholder = (v: string) => (this.placeholder = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  setRequired = (v: boolean) => (this.required = v);
+  get usage() {
+    let bits = [`@value='${this.value}'`];
+    if (this.required) bits.push('@required={{true}}');
+    bits.push('@onInput={{this.setValue}}', '@onValidation={{this.setError}}');
+    return `<UrlInput ${bits.join(' ')} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='UrlInput'
+      @description='URL entry riding boxel-ui BoxelInput (@type=url) with an EmailInput-shaped validation surface: blur-gated first error, live revalidation once touched, valid checkmark on a good committed value. Requires an http:// or https:// URL.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <UrlInput
+          @value={{this.value}}
+          @placeholder={{this.placeholder}}
+          @disabled={{this.disabled}}
+          @required={{this.required}}
+          @onInput={{this.setValue}}
+          @onValidation={{this.setError}}
+        />
+        <p class='pretui-demo-readout' data-test-url-readout>
+          value = “{{this.value}}” · error =
+          {{if this.lastError this.lastError 'null'}}
+        </p>
+      </:example>
+      <:api as |Args|>
+        <Args.Bool
+          @name='required'
+          @value={{this.required}}
+          @description='An empty field counts as invalid on blur once required.'
+          @onInput={{this.setRequired}}
+        />
+        <Args.String
+          @name='value'
+          @value={{this.value}}
+          @onInput={{this.setValue}}
+        />
+        <Args.String
+          @name='placeholder'
+          @value={{this.placeholder}}
+          @onInput={{this.setPlaceholder}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @value={{this.disabled}}
+          @onInput={{this.setDisabled}}
+        />
+        <Args.String
+          @name='controlId'
+          @description="The input's id for label wiring — supplied by a wrapping Field's yielded controlId."
+        />
+        <Args.Action
+          @name='onInput'
+          @description='Receives the changed value as a string.'
+        />
+        <Args.Action
+          @name='onValidation'
+          @description='Receives the current validation error message, or null when valid/empty — the EmailInput split.'
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-demo-readout {
+        margin: 8px 0 0;
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_URL_INPUT: Record<string, unknown> = {
+  UrlInput: UrlInputUsage,
+};

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

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

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

@@ -0,0 +1,109 @@
+// Pretui — UsageArgument: one documented argument row (doc lens: table row; prop lens: nothing).
+import Component from '@glimmer/component';
+import { VisuallyHidden } from './visually-hidden';
+import { isPresent, readOnlyText } from '../internal/freestyle';
+import type { ArgsMode } from '../internal/freestyle';
+
+// ── Freestyle::Usage::Argument (doc lens: table row; prop lens: nothing) ──
+export interface UsageArgumentSignature {
+  Args: {
+    mode?: ArgsMode;
+    name?: string;
+    type?: string;
+    typeLabel?: string;
+    description?: string;
+    defaultValue?: unknown;
+    required?: boolean;
+    optional?: boolean;
+    hideControls?: boolean;
+  };
+  Blocks: { default: [] };
+  Element: HTMLElement;
+}
+
+export class UsageArgument extends Component<UsageArgumentSignature> {
+  get isDoc() {
+    return (this.args.mode ?? 'doc') === 'doc';
+  }
+  get typeLabel() {
+    return this.args.typeLabel || this.args.type;
+  }
+  get shouldRenderDefaultValue() {
+    return isPresent(this.args.defaultValue);
+  }
+  get defaultText() {
+    return readOnlyText(this.args.defaultValue);
+  }
+  // yields print as {{name}}, css vars bare (names carry --), args as @name
+  get sigilPre() {
+    if (this.args.type === 'Yield') return '{{';
+    if (this.args.type === 'CSS' || this.args.typeLabel === 'CSS') return '';
+    return '@';
+  }
+  get sigilPost() {
+    return this.args.type === 'Yield' ? '}}' : '';
+  }
+  <template>
+    {{#if this.isDoc}}
+      <tr class='pretui-usage-arg' data-test-pretui-usage-arg>
+        {{! the name heads the row, so each cell is announced with it }}
+        <th scope='row' class='pretui-usage-arg-name'>
+          <span class='u-sig'>{{this.sigilPre}}</span>{{#if
+            @name
+          }}{{@name}}{{/if}}<span class='u-sig'>{{this.sigilPost}}</span>
+          {{#if @required}}<span
+              class='u-req'
+              aria-hidden='true'
+              data-test-pretui-usage-arg-required
+            >*</span><VisuallyHidden> (required)</VisuallyHidden>{{/if}}
+        </th>
+        <td class='pretui-usage-arg-type'>{{this.typeLabel}}</td>
+        <td><span
+            class='pretui-usage-arg-description-text'
+          >{{@description}}</span></td>
+        <td class='pretui-usage-arg-default'>
+          {{#if this.shouldRenderDefaultValue}}
+            {{this.defaultText}}
+          {{else}}
+            —
+          {{/if}}
+        </td>
+      </tr>
+    {{/if}}
+    <style scoped>
+      .pretui-usage-arg {
+        --pretui-usage-arg-description-max-w: 32.5rem;
+      }
+      .pretui-usage-arg-name {
+        font-family: var(--font-mono);
+        font-weight: inherit;
+        white-space: nowrap;
+        width: 1%;
+      }
+      .u-sig {
+        color: var(--muted-foreground);
+      }
+      .u-req {
+        color: var(--destructive-ink);
+      }
+      .pretui-usage-arg-type {
+        font-family: var(--font-mono);
+        color: var(--muted-foreground);
+        white-space: nowrap;
+        width: 1%;
+      }
+      /* on a span: table layout ignores max-width on a cell */
+      .pretui-usage-arg-description-text {
+        display: block;
+        max-width: var(--pretui-usage-arg-description-max-w);
+      }
+      .pretui-usage-arg-default {
+        font-family: var(--font-mono);
+        color: var(--muted-foreground);
+        text-align: end;
+        white-space: nowrap;
+        width: 1%;
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,44 @@
+## What it is
+
+The base argument row of a **FreestyleUsage** page — `Args.Base` in the yielded hash. It documents an argument that has **no interactive control**: a component reference, an action, a yielded block, or any type a knob cannot represent. Reach for the typed siblings (**UsageString**, **UsageBool**, **UsageNumber**, **UsageArray**, **UsageObject**, **UsageCssVariable**) when the value _can_ be manipulated; reach for this when it cannot, or when you only want documentation.
+
+## The contract
+
+```
+@mode? 'doc' | 'prop'   (default 'doc')
+@name?, @type?, @typeLabel?, @description?, @defaultValue?
+@required?, @hideControls?
+@optional?   — accepted for ember-freestyle parity; it renders nothing
+```
+
+**`@mode` is the lens, and it is the architecture of the whole family.** A usage page authors its `<:api>` block **once**; `FreestyleUsage` renders it twice — as a right-hand **property list** (`prop`) and as an **API table** (`doc`) below. Every Usage component therefore knows both presentations. **`UsageArgument` renders a table row in `doc` and nothing at all in `prop`**, because there is no control to show. That asymmetry is what makes the dual-lens trick work: components with knobs appear in both, components without appear only in the docs.
+
+**The sigil is derived from `@type`.** Yields print as `{{name}}`, CSS variables print bare (their names already carry `--`), and ordinary args print as `@name`. So a reader can tell an argument from a block from a token at a glance, without the page author annotating it.
+
+`@typeLabel` overrides the displayed type when the real type is unreadable — a long union, a generic.
+
+## Prior art
+
+**ember-freestyle's `Freestyle::Usage::Base`** is the upstream, and the invocation surface here is verbatim: same block, same arg names, so a usage page written for ember-freestyle works unchanged.
+
+**Storybook's `argTypes`** is the closest analogue in the wider ecosystem, and it works the other way round: Storybook _derives_ the docs table from TypeScript types and lets you override, so the table is generated and the controls are inferred. That is less authoring, and it produces the well-known Storybook failure mode of a controls panel full of arguments nobody meant to expose, typed as `object` because the inference gave up.
+
+**The Pretui/freestyle bet is that documentation is authored, not derived** — and the dual-lens rendering is what makes that affordable. You write one row and get both the knob and the doc, so the cost of authoring is roughly the cost of the docs alone.
+
+Where it is behind Storybook: no type inference, no linking to the component's source, and no validation that the documented args match the real signature — a renamed arg leaves a stale row and nothing notices.
+
+## Accessibility
+
+No pattern governs it; it is a table row in one lens and nothing in the other.
+
+Gaps, and most belong to the page rather than the row:
+
+- **The name heads its row** (`<th scope="row">`), so each Type, Description and Default cell is announced with the argument it describes. The table itself is named by its section heading in **FreestyleUsage**.
+- **The required marker** is a visual asterisk hidden from assistive tech, with a visually hidden "(required)" beside it, the same fix **FormField** made.
+- **The sigil is decorative typography carrying meaning.** `{{name}}` versus `@name` versus a bare token name is a real distinction, conveyed by punctuation that screen readers announce inconsistently (or spell out). The type is in the Type column, which mitigates it.
+- **`@description` is prose in a table cell**, so it is announced only when the reader traverses to that cell — which is correct for a table and means the description is not part of the argument's name.
+- **The `prop` lens renders nothing**, so an argument documented with `Base` is invisible in the property list. That is intended; it does mean a reader working from the knobs alone will not know the argument exists.
+
+## Theming
+
+**Table**'s tokens for the row (`--card` with `--card-foreground`, `--border`, `--stripe`, `--hover`, the label role in the header). The name, type and default cells are set in `--font-mono`, with the type, default and sigils in `--muted-foreground`, so a reader can tell `'md'` the default from _md_ the prose; the asterisk is `--destructive-ink`. The description takes the row's ink and stops at `--pretui-usage-arg-description-max-w` (32.5rem), a local measure.

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

@@ -0,0 +1,80 @@
+// Pretui — UsageArray: an array argument with its knob.
+import Component from '@glimmer/component';
+import { guidFor } from '@ember/object/internals';
+import { Input } from './input';
+import { UsageArgument } from './usage-argument';
+import { PropReadOnly, PropRow, readOnlyText } from '../internal/freestyle';
+import type { ArgsMode } from '../internal/freestyle';
+
+// ── Freestyle::Usage::Array ──────────────────────────────────────────────
+export interface UsageArraySignature {
+  Args: {
+    mode?: ArgsMode;
+    name?: string;
+    description?: string;
+    defaultValue?: unknown;
+    required?: boolean;
+    optional?: boolean;
+    hideControls?: boolean;
+    value?: string[];
+    onInput?: (value: string[]) => void;
+  };
+  Element: HTMLElement;
+}
+
+export class UsageArray extends Component<UsageArraySignature> {
+  get isProp() {
+    return this.args.mode === 'prop';
+  }
+  get text() {
+    return (this.args.value ?? []).join(', ');
+  }
+  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 = (raw: string) => {
+    this.args.onInput?.(
+      raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean),
+    );
+  };
+  <template>
+    {{#if this.isProp}}
+      {{#unless @hideControls}}
+        <PropRow
+          @label={{@name}}
+          @required={{@required}}
+          @controlId={{this.labelFor}}
+        >
+          {{#if this.hasControl}}
+            <Input
+              @value={{this.text}}
+              @onInput={{this.callOnInput}}
+              @controlId={{this.controlId}}
+            />
+          {{else}}
+            <PropReadOnly @value={{this.readOnlyValue}} />
+          {{/if}}
+        </PropRow>
+      {{/unless}}
+    {{else}}
+      <UsageArgument
+        @type='Array'
+        @name={{@name}}
+        @description={{@description}}
+        @required={{@required}}
+        @defaultValue={{@defaultValue}}
+      />
+    {{/if}}
+  </template>
+}

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

@@ -0,0 +1,47 @@
+## What it is
+
+The array argument row of a **FreestyleUsage** page — `Args.Array`. Docs lens: a table row. Property lens: a control for editing a list of strings bound to the example. Use it for `string[]` arguments — a set of options, a list of tick labels, a column list. For structured data (an array of objects), **UsageObject**; for a single string, **UsageString**.
+
+## The contract
+
+```
+@mode? 'doc' | 'prop'
+@name?, @description?, @defaultValue?, @required?, @optional?, @hideControls?
+@value?: string[]
+@onInput?(value: string[])
+```
+
+**It is `string[]` only.** Not `unknown[]`, not generic. That is the honest boundary: a text-based knob can round-trip a list of strings and cannot round-trip a list of objects without inventing a serialisation. Arrays of anything else go to **UsageObject**, which shows them as JSON.
+
+**`@mode` is the lens.** The `<:api>` block is authored once and rendered twice — property list (`prop`) and API table (`doc`).
+
+The practical consequence of the string-only decision: the most common array argument in this kit is an options list of `{ value, label }` — **Select**, **MultiSelect**, **RadioGroup**, **SegmentedControl**, **FilterChips** and **SortDropdown** all take one — and **none of them can use this component's knob.** They document their options with **UsageObject** or **UsageArgument** instead. Worth knowing before reaching for `Args.Array`: it fits fewer of this kit's arguments than its name suggests.
+
+## Prior art
+
+**ember-freestyle's `Freestyle::Usage::Array`** is the upstream; the invocation surface is verbatim.
+
+**Storybook's `array` control** is the analogue and takes the same shape — a comma-or-newline-separated text field producing a string array — with the same limitation and the same escape (`object` for anything richer).
+
+So neither system solves the structured-array case with a knob, and both are honest about it. The Pretui port's contribution is the same as the rest of the family: **the control is the kit's own**, so the documentation surface dogfoods what it documents.
+
+Where both are behind what would actually help: no per-item add/remove/reorder. A list knob that lets you drag a fourth item into an options array would make **Select**'s and **Tabs**' usage pages genuinely explorable, and **DuelingPicklist** is right there in the kit as a model.
+
+## Accessibility
+
+No pattern of its own; it renders a text-based control plus a table row.
+
+Gaps:
+
+- **The separator convention is invisible.** A text field holding a list needs to say how items are separated — comma, newline, semicolon — and there is no visible instruction and no `aria-describedby`. That is a **WCAG 3.3.2 Labels or Instructions** gap, and it is worse here than in a normal form because the reader is learning the component, not filling in a known field.
+- **A malformed entry produces a silently wrong array.** Typing `a, b,` yields three items with an empty third, and nothing flags it — no `aria-invalid`, no message (**WCAG 3.3.1**).
+- **The control's accessible name** depends on the property rail actually wiring a `<label for>`; verify, since the underlying **Input** generates no name of its own.
+- **The current item count is not announced.** After editing, a screen-reader user has the raw text and no confirmation of how many items the component parsed — which is exactly the ambiguity the separator convention creates.
+- **Changing the knob re-renders the example silently** — no live region.
+- **`@required` must reach the accessible name** in the docs lens rather than only rendering an asterisk.
+
+## Theming
+
+**Input**'s tokens for the control, **Table**'s for the doc row, plus the property rail's label voice and **Token**'s treatment for the default value in the docs table.
+
+Nothing of its own. The docs table's default-value cell is where an array default (`['sm', 'md', 'lg']`) is rendered, and it should be in the mono voice — Law 3, machine values as jewelry — so a reader can distinguish the literal from prose describing it.

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

@@ -0,0 +1,62 @@
+// Pretui — UsageBool: a boolean argument with its knob.
+import Component from '@glimmer/component';
+import { Switch } from './switch';
+import { UsageArgument } from './usage-argument';
+import { PropReadOnly, PropRow, readOnlyText } from '../internal/freestyle';
+import type { ArgsMode } from '../internal/freestyle';
+
+// ── Freestyle::Usage::Bool ───────────────────────────────────────────────
+export interface UsageBoolSignature {
+  Args: {
+    mode?: ArgsMode;
+    name?: string;
+    description?: string;
+    defaultValue?: unknown;
+    required?: boolean;
+    optional?: boolean;
+    hideControls?: boolean;
+    value?: boolean;
+    onInput?: (value: boolean) => void;
+  };
+  Element: HTMLElement;
+}
+
+export class UsageBool extends Component<UsageBoolSignature> {
+  get isProp() {
+    return this.args.mode === 'prop';
+  }
+  get hasControl() {
+    return typeof this.args.onInput === 'function';
+  }
+  get readOnlyValue() {
+    return readOnlyText(this.args.value ?? this.args.defaultValue);
+  }
+  callOnInput = (v: boolean) => {
+    this.args.onInput?.(v);
+  };
+  <template>
+    {{#if this.isProp}}
+      {{#unless @hideControls}}
+        <PropRow @label={{@name}} @required={{@required}}>
+          {{#if this.hasControl}}
+            <Switch
+              @checked={{@value}}
+              @onCheckedChange={{this.callOnInput}}
+              aria-label={{@name}}
+            />
+          {{else}}
+            <PropReadOnly @value={{this.readOnlyValue}} />
+          {{/if}}
+        </PropRow>
+      {{/unless}}
+    {{else}}
+      <UsageArgument
+        @type='Bool'
+        @name={{@name}}
+        @description={{@description}}
+        @required={{@required}}
+        @defaultValue={{@defaultValue}}
+      />
+    {{/if}}
+  </template>
+}

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

@@ -0,0 +1,47 @@
+## What it is
+
+The boolean argument row of a **FreestyleUsage** page — `Args.Bool`. Docs lens: a table row. Property lens: a **Switch** bound to the example. Use it for any boolean argument. For a string, **UsageString**; a number, **UsageNumber**; anything without a manipulable value, **UsageArgument**.
+
+## The contract
+
+```
+@mode? 'doc' | 'prop'
+@name?, @description?, @defaultValue?, @required?, @optional?, @hideControls?
+@value?: boolean
+@onInput?(value: boolean)
+```
+
+**The control is a Switch, not a Checkbox**, and that is the correct choice for this context: a knob takes effect immediately with no save step, which is exactly the distinction between the two components in this kit. A Checkbox here would imply a form.
+
+**`@mode` is the lens.** The `<:api>` block is authored once and rendered twice — property list (`prop`) and API table (`doc`).
+
+Note the signature: `@value?: boolean` with no `null`, unlike **UsageString** (`string | null`) and **UsageNumber** (`number | null`). A boolean argument is on or off; an unset boolean is `false` from the component's point of view, which is honest for Glimmer args where an omitted boolean is falsy.
+
+## Prior art
+
+**ember-freestyle's `Freestyle::Usage::Bool`** is the upstream; the invocation surface is verbatim.
+
+**Storybook's `boolean` control** is the analogue and renders a toggle. Same shape, same idea.
+
+The Pretui port's improvement is the same one that runs through this family: **the control is the kit's own Switch**, so the documentation surface dogfoods the components it documents. A regression in Switch is visible on every usage page in the catalogue before it is visible in a test.
+
+Where it is behind Storybook: no tri-state for arguments that are meaningfully "unset" versus "false" — which matters more than it sounds, because a Glimmer component that distinguishes `@foo={{false}}` from an omitted `@foo` cannot be demonstrated here.
+
+## Accessibility
+
+No pattern of its own; it renders a **Switch** plus a table row, and inherits Switch's contract — `role="switch"`, `aria-checked` `'true'`/`'false'` (never `'mixed'`, which the Switch pattern forbids), Space and Enter both activating.
+
+Gaps, and the first is inherited and significant in this context:
+
+- **Switch has no accessible name of its own.** It takes `@controlId` so a wrapper can supply a `<label for>`, and the property rail's label must actually do that. If it does not, a property list of eight boolean knobs announces as eight switches called nothing. **This is the most likely real failure on a usage page** and it is worth checking directly — Switch is visually self-evident and the omission is easy to miss.
+- **Switch defines no focus-visible ring** (see its own note), so keyboard users tabbing the property list may not see where they are.
+- **Switch's 30×18 track is below WCAG 2.5.8's 24×24 minimum** on the short axis; in a dense property list there is no larger label row to compensate the way there is in a form.
+- **Toggling re-renders the example silently** — no live region, no confirmation.
+- **`@required` must reach the accessible name** in the docs lens, not only render an asterisk.
+- **The label must not change with state** (an APG Switch requirement): the rail should read `@disabled`, not "Disabled: on".
+
+## Theming
+
+**Switch**'s tokens for the control (`--pretui-control-border` / `--line-strong` for the off track, `--primary` for on, `--card` for the thumb, `--shadow-ink-mid`, and the snap duration/easing), **Table**'s for the doc row, plus the property rail's label voice.
+
+Nothing of its own. The one thing to check per theme is Switch's on/off distinction at this size: a property list shows many switches at once, most of them off, and if `--primary` and `--line-strong` are close in luminance the on ones do not stand out — which is exactly the reading task this surface exists for.

package/bundled-realms/pretui/components/usage-component-arg.gts

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

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

@@ -0,0 +1,56 @@
+// Pretui — UsageCssVariable: a documented CSS custom property.
+import Component from '@glimmer/component';
+import { guidFor } from '@ember/object/internals';
+import { Input } from './input';
+import { UsageArgument } from './usage-argument';
+import { PropRow } from '../internal/freestyle';
+import type { ArgsMode } from '../internal/freestyle';
+
+// ── Freestyle::Usage::BasicCssVariable ───────────────────────────────────
+export interface UsageCssVariableSignature {
+  Args: {
+    mode?: ArgsMode;
+    name?: string;
+    description?: string;
+    defaultValue?: unknown;
+    value?: string | null;
+    onInput?: (value: string) => void;
+  };
+  Element: HTMLElement;
+}
+
+export class UsageCssVariable extends Component<UsageCssVariableSignature> {
+  get isProp() {
+    return this.args.mode === 'prop';
+  }
+  get valueStr() {
+    return this.args.value ?? undefined;
+  }
+  get hasControl() {
+    return this.args.onInput !== undefined;
+  }
+  controlId = `${guidFor(this)}-control`;
+  callOnInput = (v: string) => {
+    this.args.onInput?.(v);
+  };
+  <template>
+    {{#if this.isProp}}
+      {{#if this.hasControl}}
+        <PropRow @label={{@name}} @controlId={{this.controlId}}>
+          <Input
+            @value={{this.valueStr}}
+            @onInput={{this.callOnInput}}
+            @controlId={{this.controlId}}
+          />
+        </PropRow>
+      {{/if}}
+    {{else}}
+      <UsageArgument
+        @typeLabel='CSS'
+        @name={{@name}}
+        @description={{@description}}
+        @defaultValue={{@defaultValue}}
+      />
+    {{/if}}
+  </template>
+}