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

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

@@ -0,0 +1,49 @@
+## What it is
+
+A persistent application menu bar — File, Edit, View — always visible, over the same command tree **Menu** and **CommandPalette** render.
+
+## The contract
+
+```
+@items (required) — exactly Menu's arg type: a SubmenuNode becomes a File/Edit/View
+             menu, a CommandNode becomes a bare command in the bar. Sections and
+             '---' carry no meaning at the top level and contribute no items
+@label?      — accessible name for the bar. Default 'Main menu'. A page with more
+             than one menubar needs these to differ
+@onSelect?   — fires after any item activates, alongside the node's own handler
+@hoverDelay? — ms of hover before a NESTED submenu opens. Default 110
+@safeDelay?  — ms the safe triangle keeps deferring a sibling's hover. Default 300
+@platform?   — force the shortcut platform
+```
+
+**One tree, three surfaces.** A command object written for **Menu** renders unchanged here and in **CommandPalette**. The taxonomy, row model, panel markup, stylesheet, shortcut faces, safe triangle, roving tabindex and type-ahead buffer are shared rather than rewritten.
+
+**Top-level switching is never delayed; nested submenus are.** Once a menu is open, moving along the bar opens the next immediately — that is the platform behaviour. A bar that opened on hover would fire every time the pointer crossed the top of a window; one that kept a dwell delay after opening would feel broken. Hence `@hoverDelay` applying only below the top level.
+
+**The safe triangle defers a sibling's hover** while the pointer is travelling diagonally toward an open submenu, which is what stops a menu closing under a moving pointer.
+
+**Sections and separators are no-ops at the top level**, so one tree can carry structure that only matters in the panel.
+
+## Prior art
+
+**accessible-menu 4.4.0** (ISC, Nick Milton) — ported, not vendored. Its `menubar.js` and `_baseMenu.js` are the specification this follows, specifically their keyup state machine and the edge cases inside it.
+
+Where Pretui is better: the shared tree across three surfaces, and the shortcut faces coming from **Kbd**, so accelerators are platform-correct without the command tree knowing where it is running.
+
+Where it is thinner: no checkable top-level items, no dynamic enable/disable contract beyond what the node carries, and no window-level integration — this is a bar in a page.
+
+## Accessibility
+
+- **It follows the APG menubar pattern**, with the roving tabindex, type-ahead and keyup state machine taken from a specification rather than improvised.
+- **`@label` must differ between bars.** The default is 'Main menu', and two of those on one page are indistinguishable in a rotor.
+- **Shortcuts render through Kbd**, which means each announces its platform-neutral spelling rather than a run of glyphs.
+- **The hover behaviour is pointer-only sugar.** Every path through the bar exists on the keyboard, and the delays affect neither.
+- **The safe triangle is an accessibility affordance for motor control** as much as a polish detail: a submenu that closes because the pointer strayed a few pixels is unusable with a tremor.
+
+## Theming
+
+The panel stylesheet, shortcut faces and row model are **Menu**'s; the bar adds only its own strip.
+
+Sharing the panel is the visible half of the shared-tree design — a command looks identical whether it was reached from the bar, a context menu or the palette.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,220 @@
+// Pretui — Menubar usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Menubar } from './menubar';
+import type { MenuEntry, ShortcutPlatform } from '../internal/menu';
+import { PLATFORM_OPTIONS } from '../demo-menu';
+
+// ── Menubar ──────────────────────────────────────────────────────────────
+class MenubarState extends GlimmerComponent {
+  @tracked platform: string = 'apple';
+  @tracked log = '—';
+  @tracked wrapLines = false;
+  @tracked zoom = 'fit';
+
+  setPlatform = (value: string) => (this.platform = value);
+  setZoom = (value: string) => {
+    this.zoom = value;
+    this.log = 'Zoom: ' + value;
+  };
+  setWrap = (next: boolean) => {
+    this.wrapLines = next;
+    this.log = next ? 'Wrap lines on' : 'Wrap lines off';
+  };
+
+  get platformValue() {
+    return this.platform as ShortcutPlatform;
+  }
+
+  private ran = (what: string) => () => (this.log = what);
+
+  get items(): MenuEntry[] {
+    return [
+      {
+        kind: 'submenu',
+        label: 'File',
+        items: [
+          { label: 'New lot', kbd: 'Mod+N', onSelect: this.ran('New lot') },
+          {
+            label: 'Open lot',
+            kbd: 'Mod+O',
+            needsInput: true,
+            onSelect: this.ran('Open lot…'),
+          },
+          '---',
+          {
+            kind: 'submenu',
+            label: 'Export as',
+            items: [
+              { label: 'CSV', onSelect: this.ran('Export CSV') },
+              { label: 'Contract PDF', onSelect: this.ran('Export PDF') },
+              { label: 'Cupping sheet', onSelect: this.ran('Export sheet') },
+            ],
+          },
+          {
+            label: 'Publish to catalog',
+            disabled: true,
+          },
+          '---',
+          {
+            label: 'Withdraw lot',
+            kbd: 'Mod+Backspace',
+            destructive: true,
+            needsInput: true,
+            onSelect: this.ran('Withdraw lot…'),
+          },
+        ],
+      },
+      {
+        kind: 'submenu',
+        label: 'Edit',
+        items: [
+          { label: 'Undo', kbd: 'Mod+Z', onSelect: this.ran('Undo') },
+          {
+            label: 'Redo',
+            kbd: 'Mod+Shift+Z',
+            disabled: true,
+            onSelect: this.ran('Redo'),
+          },
+          '---',
+          {
+            kind: 'toggle',
+            label: 'Wrap long notes',
+            checked: this.wrapLines,
+            onChange: this.setWrap,
+          },
+        ],
+      },
+      {
+        kind: 'submenu',
+        label: 'View',
+        items: [
+          {
+            kind: 'section',
+            label: 'Zoom',
+            items: [
+              {
+                kind: 'radio',
+                group: 'zoom',
+                label: 'Fit to pane',
+                checked: this.zoom === 'fit',
+                onSelect: () => this.setZoom('fit'),
+              },
+              {
+                kind: 'radio',
+                group: 'zoom',
+                label: 'Actual size',
+                checked: this.zoom === 'actual',
+                onSelect: () => this.setZoom('actual'),
+              },
+            ],
+          },
+        ],
+      },
+      {
+        kind: 'submenu',
+        label: 'Window',
+        disabled: true,
+        items: [{ label: 'Never reachable' }],
+      },
+      { label: 'Help', kbd: 'F1', onSelect: this.ran('Help') },
+    ];
+  }
+}
+
+class MenubarUsage extends MenubarState {
+  <template>
+    <FreestyleUsage
+      @name='Menubar'
+      @description='An application menu bar — the WAI-ARIA menubar pattern, which is a different pattern from the menu button Menu implements rather than a horizontal skin of it. The axis flips: ←/→ move between titles and wrap, ↓ opens onto the first item and ↑ opens onto the last, Home/End jump to the first and last title. With a menu already down, ←/→ close it, step to the adjacent title and open THAT one with focus back on the bar — the behaviour that makes a real menu bar feel like one. Esc closes the menu and returns focus to its title, staying in the bar; inside a nested submenu it closes one level. The whole bar is ONE tab stop, so Tab leaves it rather than walking the titles. Hover is deliberately asymmetric: an idle bar ignores it entirely, an active one switches instantly with no dwell delay. It takes the same MenuNode tree as Menu and CommandPalette, so a command is defined once with one shortcut and one enabled rule.'
+    >
+      <:example>
+        <div class='mb-stage'>
+          <Menubar
+            @items={{this.items}}
+            @platform={{this.platformValue}}
+            @label='Sourcing desk'
+          />
+          <span class='mb-log'>last action:
+            <strong>{{this.log}}</strong></span>
+        </div>
+        <p class='mb-hint'>Focus the bar with Tab, then try: →/← to walk the
+          titles, ↓ to pull one down, → from an item to jump straight to the
+          next menu, type
+          <em>“v”</em>
+          to reach View, → on
+          <em>Export as</em>
+          to descend and ← to come back one level. Open File with the mouse and
+          then sweep across the titles — once the bar is active, hover switches
+          immediately.
+          <em>Window</em>
+          is dimmed: still focusable and announced, never opens.</p>
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='items'
+          @description='The same MenuNode tree Menu takes. A submenu node becomes a File/Edit/View menu; a plain command node becomes a bare title that acts on click, like Help. Sections and separators carry no meaning at the top level of a bar and contribute no titles, so they are simply skipped there. Everything below the top level is an ordinary menu at arbitrary depth.'
+          @value={{this.items}}
+        />
+        <Args.String
+          @name='label'
+          @description='Accessible name for the bar itself, announced as the menubar. A page with more than one bar needs these to differ.'
+          @value='Sourcing desk'
+          @defaultValue='Main menu'
+          @hideControls={{true}}
+        />
+        <Args.String
+          @name='platform'
+          @description='Forces the shortcut spelling instead of detecting it, exactly as on Menu — one kbd token renders both faces.'
+          @value={{this.platform}}
+          @options={{PLATFORM_OPTIONS}}
+          @defaultValue='(detected)'
+          @onInput={{this.setPlatform}}
+        />
+        <Args.Base
+          @name='onSelect'
+          @description='Fires after any item activates, alongside the node own onSelect handler. A toggle flips and the bar closes, per HIG.'
+          @hideControls={{true}}
+        />
+        <Args.Base
+          @name='hoverDelay / safeDelay'
+          @description='Hover-intent for NESTED submenus (110ms) and how long the Amazon safe triangle defers a sibling row crossed on the diagonal (300ms). Switching between top-level titles is never delayed — once the bar is active the reader has already declared intent. Both timers are owned by an ember-modifier and cleared in its destructor, and neither re-arms.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .mb-stage {
+        display: flex;
+        align-items: center;
+        gap: var(--space-4, 11px);
+        flex-wrap: wrap;
+      }
+      .mb-log {
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+      .mb-log strong {
+        color: var(--foreground);
+        font-weight: 600;
+      }
+      .mb-hint {
+        margin: var(--space-4, 11px) 0 0;
+        max-width: 62ch;
+        font-size: var(--text-ui-sm, 11.5px);
+        line-height: 1.6;
+        color: var(--muted-foreground);
+      }
+      .mb-hint em {
+        font-style: normal;
+        font-weight: 600;
+        color: var(--foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_MENUBAR: Record<string, unknown> = {
+  Menubar: MenubarUsage,
+};

package/bundled-realms/pretui/components/meter.gts

@@ -0,0 +1,113 @@
+// Pretui — Meter: a discrete bar meter that always ships a label (Law 4).
+import Component from '@glimmer/component';
+import { htmlSafe } from '@ember/template';
+import { hueStyle } from '../internal/ink';
+
+export interface MeterSignature {
+  Args: {
+    level: number;
+    segments?: number;
+    label: string; // Law 4: segments always ship a text label
+    hue?: string;
+    /** bar heights in px, written as rem (÷ 16) so they follow the root font size */
+    heights?: number[];
+  };
+  Element: HTMLSpanElement;
+}
+
+export class Meter extends Component<MeterSignature> {
+  get bars(): { on: boolean; style: ReturnType<typeof htmlSafe> }[] {
+    let segments = this.segmentsCount;
+    let heights = this.args.heights ?? [6, 10, 14];
+    let out = [];
+    for (let i = 0; i < segments; i++) {
+      let h = heights[i] ?? heights[heights.length - 1];
+      out.push({ on: i < this.levelNow, style: htmlSafe(`height: ${h / 16}rem`) });
+    }
+    return out;
+  }
+  // `@segments` as a whole number of bars, 3 when omitted. A fraction rounds
+  // up, the way it draws (2.5 draws three bars), and a negative or non-finite
+  // count reads as no bars, so `aria-valuemax` is always the number of bars
+  // drawn and never drops below `aria-valuemin`.
+  get segmentsCount() {
+    let segments = this.args.segments ?? 3;
+    return Number.isFinite(segments) ? Math.max(0, Math.ceil(segments)) : 0;
+  }
+  // `@level` as a whole number of bars in [0, segments], so `aria-valuenow`
+  // always sits between `aria-valuemin` and `aria-valuemax`, and what is
+  // announced is the number of bars a sighted user sees lit. A fraction rounds
+  // up, the way a partly reached step lights in the stepped ProgressBar, so 1.5
+  // lights and announces 2. An unset or non-finite level reads as 0.
+  get levelNow() {
+    let level = Number.isFinite(this.args.level) ? Math.ceil(this.args.level) : 0;
+    return Math.max(0, Math.min(level, this.segmentsCount));
+  }
+  get style() {
+    return hueStyle('--pretui-meter-hue', this.args.hue);
+  }
+  /**
+   * A FALLBACK ROLE LIST, which `role` has always accepted: the first token
+   * the engine understands wins.
+   *
+   * Firefox does not implement `role='meter'` at all, so a bare `role='meter'`
+   * announces there as an unnamed group and the level is simply lost. React
+   * Aria ships exactly this pair for the same reason. Meter-aware engines
+   * still get `meter`; Firefox falls back to `progressbar`, which reads the
+   * same `aria-valuenow`/`valuemin`/`valuemax` already present.
+   *
+   * Held in a getter rather than written inline because ember-template-lint's
+   * `no-invalid-role` validates the whole attribute as a single role name and
+   * rejects the (valid) two-token form.
+   */
+  meterRole = 'meter progressbar';
+  <template>
+    <span
+      class='pretui-meter'
+      style={{this.style}}
+      role={{this.meterRole}}
+      aria-valuenow={{this.levelNow}}
+      aria-valuemin='0'
+      aria-valuemax={{this.segmentsCount}}
+      aria-label={{@label}}
+      data-test-pretui-meter
+      ...attributes
+    >
+      <span class='pretui-meter-bars'>
+        {{#each this.bars as |bar|}}
+          <span class='pretui-meter-bar' data-on={{if bar.on 'true'}} style={{bar.style}}></span>
+        {{/each}}
+      </span>
+      {{#if @label}}<span class='pretui-meter-label'>{{@label}}</span>{{/if}}
+    </span>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-meter {
+          display: inline-flex;
+          align-items: flex-end;
+          gap: var(--boxel-sp-xs);
+        }
+        .pretui-meter-bars {
+          display: inline-flex;
+          align-items: flex-end;
+          gap: var(--boxel-sp-6xs);
+          height: 0.875rem;
+        }
+        .pretui-meter-bar {
+          width: 0.25rem;
+          border-radius: var(--boxel-border-radius-2xs);
+          background-color: var(--border-strong);
+        }
+        .pretui-meter-bar[data-on] {
+          background-color: var(--pretui-meter-hue, var(--primary));
+        }
+        .pretui-meter-label {
+          font-size: var(--boxel-font-size-xs);
+          font-weight: 500;
+          color: var(--muted-foreground);
+          line-height: 1;
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,50 @@
+## What it is
+
+A discrete signal-strength meter: a small run of rising bars, some lit, with a mandatory text label beside them. Use it for a _qualitative level within a known range_ — signal, confidence, priority, capacity, a 1–5 score. It is deliberately **not** a progress indicator: if the value is completion toward a goal, use **ProgressBar** or **ProgressRadial**, which look different on purpose. For an exact number, **Stat** or **Token**.
+
+## The contract
+
+```
+@level: number   (required)
+@label: string   (required)
+@segments? (default 3), @hue?, @heights? (default [6, 10, 14])
+```
+
+**Law 4: discrete beats continuous, and segments always ship a text label.** Both halves are enforced by the type — `@label` is required, not optional. A row of three bars conveys "some" but not "two of three"; the label is what makes the value readable, and making it required means no call site can ship a bar cluster with no words. This is the kit's clearest example of an accessibility requirement expressed as an API constraint rather than as documentation.
+
+**Discrete, not continuous.** Three bars at 6/10/14px (written as rem, so they follow the root font size), `@level` of them lit. `@segments` and `@heights` let you make it five bars or flat ones, with `@heights` falling back to its last entry when it runs short, so `@segments={{5}}` with the default three heights gives 6, 10, 14, 14, 14 — probably not what you want. Pass matching arrays.
+
+## Prior art
+
+**No component kit ships this.** Radix, Web Awesome, shadcn and React Spectrum all have `progressbar` and Spectrum has a `Meter` (a bar with `variant` `informative | positive | critical | warning`) — but the _segmented signal-strength_ form is a platform convention (iOS/Android status bars, Wi-Fi indicators) rather than a design-system component.
+
+Where making it one pays off: **the label requirement**. Every ad-hoc signal-strength cluster in every product is three unlabelled divs, and it is the most reliably inaccessible micro-component in the field. Requiring the label at the type level fixes that category of bug by construction.
+
+Where it is thinner than Spectrum's `Meter`: no semantic variants (a meter at 1/5 does not turn red), no `valueLabel`/`formatOptions`, and no continuous mode.
+
+## Accessibility
+
+Governing pattern: APG **Meter** — `role="meter"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax` and, when the raw number is not human-friendly, `aria-valuetext`, plus a label. Correct for a **static measurement within a known range**; wrong for task progress (that is `progressbar`) and wrong for unbounded quantities.
+
+What is right: `aria-valuenow`, `aria-valuemin="0"`, `aria-valuemax` and `aria-label` are all present, and the visible label is required — so unlike most of this kit's small components, a Meter is never anonymous.
+
+- **`role="meter progressbar"`, a fallback role list.** `role="meter"` has uneven support: Firefox does not implement it at all, and a bare `meter` there announces as an unlabelled group, losing the level. The first role an engine understands wins, so meter-aware engines get `meter` and Firefox falls back to `progressbar`, which reads the same `aria-value*` attributes. React Aria's `useMeter` ships the same pair for the same reason.
+- **The level is a whole number of bars in `[0, @segments]`.** `@level={{9}} @segments={{3}}` announces 3 and lights three bars; a negative level announces 0 and lights none. A fractional level rounds up, the way a partly reached step lights in the stepped ProgressBar, so `@level={{1.5}}` announces 2 and lights two bars. An unset or non-finite level announces 0 and lights none. The announced value never leaves `aria-valuemin..aria-valuemax`, and it always matches the lit count.
+- **`@segments` is a whole number of bars too, 3 when omitted.** `aria-valuemax` is the number of bars drawn. A fractional count rounds up, the way it draws, so `@segments={{2.5}}` draws three bars and reports a max of 3. A negative or non-finite count draws no bars and reports a max of 0, so `aria-valuemax` never reads `NaN` or drops below `aria-valuemin`.
+
+Gaps:
+
+- **No `aria-valuetext`.** "2" is announced where "2 of 3 — Medium" is meant. `@label` already holds the qualitative half; combining them into `valuetext` would make the announcement complete.
+- **The visible label is inside the `role="meter"` element, and `aria-label` is set to the same string.** `meter` does not take its name from content, so the `aria-label` wins — but the label text is still a child of the element, and some readers will read it again after the name. Moving the visible label outside the meter element (and pointing `aria-labelledby` at it) would be cleaner than the current duplication.
+- **Lit versus unlit is conveyed by fill color alone** — `--border-strong` versus the hue, with identical geometry. That is a **WCAG 1.4.1** risk if the theme's hue and border color are close in luminance; the rising heights differentiate the _bars_, not their states. An unlit outline or a lower opacity would add a second channel.
+- **0.25rem-wide bars** are very fine; at high zoom or low vision the lit/unlit distinction may not resolve at all. The label carries the value, which is precisely why Law 4 requires it.
+
+## Theming
+
+`--pretui-meter-hue` (per instance, defaulting to `--primary`), `--border-strong` (unlit bars), `--muted-foreground` (label ink), `--boxel-font-size-xs`.
+
+The 0.25rem bar width, `--boxel-sp-6xs` gap, `--boxel-border-radius-2xs` radius, 0.875rem cluster height and `--boxel-sp-xs` label gap are fixed; bar heights come from `@heights`, an arg rather than a token. `@heights` takes px figures and writes them as rem (÷ 16), so the bars scale with the root font size.
+
+Four tokens, so theming is cheap. The one thing to check per theme is `--border-strong` against `--pretui-meter-hue`: they are the only distinction between lit and unlit, and a theme whose dark mode pushes `--border-strong` toward mid-gray while using a muted hue can make a 1-of-3 meter indistinguishable from a 3-of-3 one.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,50 @@
+// Pretui — Meter usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Meter } from './meter';
+
+class MeterUsage extends GlimmerComponent {
+  @tracked level = 3;
+  @tracked label = 'High confidence';
+  setLevel = (v: number | null) => (this.level = v ?? 0);
+  setLabel = (v: string) => (this.label = v);
+  <template>
+    <FreestyleUsage
+      @name='Meter'
+      @description='Discrete strength meter (role=meter). Discrete beats continuous: qualitative judgments get countable bars, not percentages — Progress is for quantities.'
+    >
+      <:example>
+        <Meter @level={{this.level}} @label={{this.label}} />
+        <Meter @level={{1}} @label='Weak' @hue='var(--warning)' />
+        <Meter @level={{0}} @label='No signal' />
+      </:example>
+      <:api as |Args|>
+        <Args.Number
+          @name='level'
+          @value={{this.level}}
+          @min={{0}}
+          @max={{3}}
+          @description='How many of the three bars are lit.'
+          @onInput={{this.setLevel}}
+        />
+        <Args.String
+          @name='label'
+          @value={{this.label}}
+          @description='The judgment the bars quantify; also the accessible name.'
+          @onInput={{this.setLabel}}
+        />
+        <Args.Base
+          @name='hue'
+          @typeLabel='String'
+          @description='Optional hue override; defaults to primary.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_METER: Record<string, unknown> = {
+  Meter: MeterUsage,
+};

package/bundled-realms/pretui/components/modal.gts

@@ -0,0 +1,2 @@
+// Pretui — Modal: The Ant / Mantine / MUI name for Dialog.
+export { Dialog as Modal } from './dialog';

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

@@ -0,0 +1,41 @@
+## What it is
+
+**Modal** is **Dialog** under the name Ant, Mantine, MUI and React Aria use. The export is the same component. Import it when a port already says Modal; the **Dialog** writeup carries the depth. A destructive confirmation should be **AlertDialog**, not a Modal with two buttons, and a small question next to its trigger is **Popconfirm**.
+
+## The contract
+
+```
+@open?, @onClose?, @onOpenChange?
+@label?          — the accessible name
+@size? ('s' | 'm' | 'l'; sm / md / lg accepted)
+@dismissible? (default true)
+<:title> <:default> <:footer>
+Element: HTMLDialogElement
+```
+
+Identical to Dialog: a native `<dialog>` opened with `showModal()`.
+
+## Prior art
+
+**Ant `Modal`** takes `open`, `title`, `onOk`, `onCancel`, `footer`, `width`, `maskClosable` and `keyboard`, and has an imperative `Modal.confirm()`. **Mantine `Modal`** takes `opened`, `onClose`, `title`, `size`, `centered` and `closeOnClickOutside`. **MUI `Modal`** is the unstyled layer under MUI `Dialog`. **React Aria `Modal`** is the overlay that wraps a `Dialog`.
+
+Dialog gets the focus trap, Escape, background inertness and top-layer stacking from the platform, where each of those kits reimplements them. It is thinner in one place: there is no `onOk` / `onCancel` footer. The footer is a block you fill with Buttons.
+
+## Accessibility
+
+Identical to Dialog: APG **Dialog (Modal)**. `showModal()` supplies the dialog role, modality, the focus trap, Escape and inert background. `@label` is the accessible name and the only labelling route. A heading in `<:title>` is not wired through `aria-labelledby`, so pass `@label` as well.
+
+## Theming
+
+Identical to Dialog: `--card`, `--foreground`, `--muted-foreground`, `--border`, `--radius-surface`, `--pretui-shadow-overlay`, `--pretui-overlay-scrim`, `--text-heading`, `--weight-heading`, `--track-heading`, `--text-body`, `--leading-body`, `--space-3`, `--space-4` and `--space-6`.
+
+## React ecosystem
+
+| Ant / Mantine / MUI                    | Pretui                        |
+| -------------------------------------- | ----------------------------- |
+| `open` / `opened`                      | `@open`                       |
+| `onCancel` / `onClose`                 | `@onClose` or `@onOpenChange` |
+| `title`                                | `<:title>` plus `@label`      |
+| `footer` / `onOk`                      | `<:footer>` with Buttons      |
+| `maskClosable` / `closeOnClickOutside` | `@dismissible`                |
+| `Modal.confirm({...})`                 | **AlertDialog**               |

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

@@ -0,0 +1,50 @@
+// Pretui — Modal usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { FreestyleUsage } from './freestyle-usage';
+import { Button } from './button';
+import { Modal } from './modal';
+
+const SOURCE = "<Modal @open={{this.open}} @label='Lot 7' @onClose={{this.close}}>…</Modal>";
+
+export class ModalUsage extends Component {
+  @tracked open = false;
+  show = () => (this.open = true);
+  close = () => (this.open = false);
+  <template>
+    <FreestyleUsage
+      @name='Modal'
+      @description='Dialog under the Ant / Mantine / MUI name: a native dialog opened with showModal(), with the focus trap, Escape and inert background from the platform. Import it when a port already says Modal; the component and its writeup are Dialog.'
+      @source={{SOURCE}}
+    >
+      <:example>
+        <Button {{on 'click' this.show}}>Open Modal</Button>
+        <Modal @open={{this.open}} @label='Lot 7' @onClose={{this.close}}>
+          <:title>Lot 7</:title>
+          <:default><p class='ov-demo-p'>Lot 7 ships Thursday with the spring labels.</p></:default>
+          <:footer><Button {{on 'click' this.close}}>Close</Button></:footer>
+        </Modal>
+      </:example>
+      <:api as |Args|>
+        <Args.Bool @name='open' @description='Controlled open state.' />
+        <Args.String @name='label' @value='Lot 7' @description='The accessible name.' />
+        <Args.String @name='size' @defaultValue='m' @description='s, m or l.' />
+        <Args.Bool @name='dismissible' @defaultValue={{true}} @description='Escape and an outside click close it.' />
+        <Args.Action @name='onClose' @description='Called when it asks to close.' />
+        <Args.Yield @name='title' />
+        <Args.Yield @name='default' />
+        <Args.Yield @name='footer' />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .ov-demo-p {
+        margin: 0;
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_MODAL: Record<string, unknown> = {
+  Modal: ModalUsage,
+};