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

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

@@ -0,0 +1,90 @@
+## What it is
+
+A selectable, keyboard-navigable, load-aware row collection: `<ul>`/`<li>` semantics, one tab stop with arrows within, the same `DataSource` selection model **DataTable** uses, and the same loading, empty and error chrome. It is what a **DataTable** becomes when the pane is too narrow for columns — the same rows, one **Item** per `<li>`.
+
+The kit has other things that draw rows, and none of them is this. **Feed** is `role='feed'`: a stream of independently authored articles with PageUp/PageDown paging and no selection. **Grid** wraps boxel-ui's tile container, a layout with no keyboard model. **DataGrid** is a table. **Masonry** is a column-major wall. **Item** is the row atom this component puts inside each `<li>`; it also stands alone. When a row should open into detail, use List's `<:expanded>` rather than **Collapsible** or **Accordion**: their trigger is a `<button>`, so a rich row summary can't go inside it, and their regions stay mounted while closed.
+
+## The contract
+
+```
+@items? | @options? | @dataSource?     — the collection (any spelling); OR
+@load?, @loadKey?                       — an async loader, re-run when the key changes
+@key?                                   — (row, index) => RowKey
+@label?                                 — the list's accessible name (default 'List')
+@size?                                  — xs|s|m|l|xl; sm/md/lg accepted
+@selectionMode?                         — none|single|multi
+@selected?, @defaultSelected?, @onSelectionChange?
+@onActivate?                            — (row, index): Enter on the focused row
+@rowLabel?                              — (row, index) => the row's accessible name
+@expandedKeys?, @defaultExpandedKeys?, @onExpandedChange?
+@divided? (default true), @bordered?
+@busy? | @loading?                      — aria-busy without replacing the rows
+@itemNoun?, @emptyTitle?, @emptyMessage?, @loadingLabel?, @skeletonRows?
+<:item as |row index api|>              — api is { index, selected, active, toggle }
+<:expanded as |row index|>              — per-row detail; supplying it turns on the expander
+<:header> <:footer>                     — inside the frame
+<:empty> <:loading> <:error>            — replace DataShell's defaults
+```
+
+**Selection is controlled or uncontrolled by the same rule as DataTable:** pass `@selected` and the component stops keeping its own copy; leave it out and it keeps state and still calls `@onSelectionChange`. In `multi` mode the control is a checkbox; in `single` it is a radio, and every radio shares one `name` so the browser enforces the single choice.
+
+**Keys are handled only when the row itself has focus.** ArrowDown/ArrowUp move the cursor, Home/End jump to the ends, Space toggles selection, Enter calls `@onActivate`. A caret in a text field inside a row still gets Home/End and Space types a space, because the handler checks that the event target is the `<li>`.
+
+**`@onActivate` is not a link.** A row with one obvious destination should carry a real `<a>` inside `<:item>` (**Item** has an `href` arg for exactly this); the activate callback is for rows whose action is not navigation.
+
+**`@rowLabel` defaults to "Row N".** That is honest and poor. Pass it: it names the selection control, the expander and the detail region, and there is nothing else to name them.
+
+**Expansion is DataTable's, row for row.** Supplying `<:expanded>` adds an expander button to every row, after the selection control (the same column order as DataTable, so a pane that switches between the two keeps the chevron in place). `@expandedKeys` controls which rows are open and `@defaultExpandedKeys` seeds the uncontrolled case; `@onExpandedChange` reports every change either way. Both components share one `ExpansionState`, so the rule cannot drift. **A row's detail renders only while it is open**: fifty collapsed rows render fifty summaries and no bodies. The detail sits inside the row's `<li>`, below the summary, so the selected tint runs through it. Clicks inside the detail never activate the row, and expanding never changes selection. The detail takes `tabindex='-1'`, so a click on its text focuses the detail rather than the row, and the row's Enter and Space don't fire from there. If focus is inside a detail when its row collapses (by the expander, a controlled `@expandedKeys` change or a reload), focus moves to that row's expander rather than falling to `<body>`.
+
+## Prior art
+
+**Ant `List`** takes `dataSource`, `renderItem`, `loadMore`, `pagination`, `bordered`, `split` and `size`, and pairs with `List.Item` and `List.Item.Meta`. **MUI `List`** is `List` + `ListItem` + `ListItemButton` + `ListItemText`, with no data contract. **Mantine `List`** is typographic. **React Aria `GridList`** is the accessibility reference for a selectable list and takes on `role='grid'` with row-level focus. **shadcn** has no list; its `Item` is the row atom.
+
+Where this is better: **one tab stop and a roving cursor**, which none of Ant, MUI or Mantine provide — their lists are either static or a Tab per row. **Selection state lives on a real control with a real name**, not on the row's class. **Load, empty and error states are built in** through **DataShell**, with `@busy` keeping the rows in place rather than swapping them for a spinner. **The `<:item>` block yields a row API**, so a row can render its own selected or active treatment without re-deriving it.
+
+Where it is thinner: **no `role='grid'` and no arrow-key travel into a row's controls** — React Aria's `GridList` does both; here the row is the focus stop and its contents are reached by Tab. **No `loadMore` and no built-in paging** (Ant has both; the kit's answer is **InfiniteScroll**, a stub, or paging in the caller). **No drag-reorder** (**Reorder** is the kit's). **No `itemLayout='vertical'`**; the row's shape is **Item**'s.
+
+Ant's `List.Item.Meta` hard-codes an `<h4>` for every row title. The row here is **Item**, which emits a `<span>` and leaves headings to the caller.
+
+## Accessibility
+
+Governing pattern: a native list. `role='listbox'` is deliberately not claimed, and the test file asserts the `<ul>` carries no role: an option's children are presentational, so a row holding a link, a button or a named avatar would lose all of it, and the realm's `require-presentational-children` lint reports exactly that in the caller's file. A list of rich rows is a list.
+
+What the component does, from its rendered markup and its tests:
+
+- **The `<ul>` is named** from `@label`.
+- **Exactly one `<li>` is in the tab sequence** (`tabindex='0'`, the rest `-1`), and the stop roves with ArrowDown, ArrowUp, Home and End. Focus arriving by click or by Tab from outside is followed rather than stolen.
+- **Selection is a real `<input type='checkbox'>` or `<input type='radio'>`** with an `aria-label` from `@rowLabel`; radios share one `name`. Space on the focused row toggles it, and the row carries `data-selected` for CSS.
+- **Enter on the focused row calls `@onActivate`** and does not select.
+- **The expander is a native `<button type='button'>`** with `aria-expanded`, an `aria-label` built from `@rowLabel` ("Expand Gyokuro" / "Collapse Gyokuro"), and `aria-controls` naming the detail **only while it is open**, since a collapsed row's detail does not exist. Enter and Space come from the button; the row's own keys are unchanged, and there is no ArrowRight/ArrowLeft expansion, which belongs to a tree grid.
+- **The open detail is a `role='region'`** named "{row label} details".
+- **An empty collection renders the EmptyState**, not an empty `<ul>`.
+- **`@busy` sets `aria-busy`** on the root and dims it without unmounting the rows.
+
+The caller's failures to avoid: a row whose only action is a click handler on the `<li>` is not reachable as a link and does not announce as one — put an `<a>` in the row; a row with no `@rowLabel` has selection controls named "Row 1", "Row 2"; and selection is shown by a background tint plus a rule down the inline start, so a stylesheet that removes the rule leaves color as the only signal.
+
+## Theming
+
+Consumed directly: `--foreground`, `--muted-foreground`, `--card`, `--border`, `--primary`, `--primary-foreground`, `--ring`, `--radius-surface`, `--hover`, `--input`, `--field`, `--text-ui-md`, `--text-ui-sm`, `--track-ui`, `--space-3`, `--space-4`, `--pretui-shadow-hairline`, `--pretui-control-rest`, `--pretui-control-border`, `--pretui-edge-highlight`, `--pretui-selected`.
+
+The selection control is drawn by the same declarations **DataTable** uses (15px, 5px radius, `--primary` fill with a `--primary-foreground` check), so a theme that retunes `--pretui-control-rest` and `--pretui-control-border` retunes both listings' checkboxes together. Density is one axis through `@size` on the root `font-size`. Coarse pointers get a 44px row floor and 20px controls without changing the fine-pointer rhythm.
+
+The expander matches DataTable's: a 1.7em ghost button with a `›` chevron that turns 90° when open (no transition under `prefers-reduced-motion`), 2.4em on coarse pointers. The detail is padded like the row, with a `--border` hairline above it.
+
+Each row's summary line is `container-type: inline-size`, which is what lets an **Item** inside it wrap its trailing meta under the body at 22rem.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+| React                                         | Pretui                              |
+| --------------------------------------------- | ----------------------------------- |
+| `dataSource` / `items` / `options`            | `@items` (all three spellings land) |
+| `renderItem`                                  | `<:item as \|row index api\|>`      |
+| `loadMore`                                    | not built; see **InfiniteScroll**   |
+| `bordered` / `split`                          | `@bordered` / `@divided`            |
+| `size`                                        | `@size`                             |
+| `selectionMode` / `selectedKeys` (React Aria) | `@selectionMode` / `@selected`      |
+| `onAction` (React Aria)                       | `@onActivate`                       |
+| Ant `expandable` / an accordion per row       | `<:expanded>` + `@expandedKeys`     |
+| `isPending` (React Aria)                      | `@busy`                             |

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

@@ -0,0 +1,203 @@
+// Pretui — List usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Chip } from './chip';
+import { StatusChip } from './status-chip';
+import { Item } from './item';
+import { List } from './list';
+import type { ListingSizeArg } from '../internal/reading-listing';
+import type { RowKey, SelectionMode } from '../data-component';
+import { LOTS, MODES, SIZES, lotLabel } from '../examples-listing';
+import type { Lot } from '../examples-listing';
+
+class ListUsage extends Component {
+  modes = MODES;
+  sizes = SIZES;
+  lots = LOTS;
+
+  @tracked selectionMode: SelectionMode = 'multi';
+  @tracked size: ListingSizeArg = 'm';
+  @tracked divided = true;
+  @tracked bordered = true;
+  @tracked lastSelection = '—';
+  @tracked lastActivated = '—';
+  @tracked lastExpanded = 'none';
+
+  setSelectionMode = (v: string) => (this.selectionMode = v as SelectionMode);
+  setSize = (v: string) => (this.size = v as ListingSizeArg);
+  setDivided = (v: boolean) => (this.divided = v);
+  setBordered = (v: boolean) => (this.bordered = v);
+  onExpandedChange = (keys: RowKey[]) => {
+    this.lastExpanded = keys.length ? keys.join(', ') : 'none';
+  };
+
+  rowKey = (row: Lot): RowKey => row.id;
+  rowLabel = (row: Lot): string => lotLabel(row);
+  onSelectionChange = (keys: RowKey[]) => {
+    this.lastSelection = keys.length ? keys.join(', ') : 'none';
+  };
+  onActivate = (row: Lot) => {
+    this.lastActivated = row.id;
+  };
+  meta = (row: Lot): string => String(row.kg) + ' kg';
+
+  <template>
+    <FreestyleUsage
+      @name='List'
+      @slug='list'
+      @description='The row collection: ul/li semantics, one tab stop with arrows within, the same DataSource selection model DataTable uses, and the same loading / empty / error chrome. It is what a DataTable becomes when the pane is too narrow for columns.'
+    >
+      <:example>
+        <div class='ls-demo'>
+          <div class='ls-readout'>
+            <span>selected
+              <strong>{{this.lastSelection}}</strong></span>
+            <span>activated
+              <strong>{{this.lastActivated}}</strong></span>
+            <span>expanded
+              <strong>{{this.lastExpanded}}</strong></span>
+          </div>
+          <p class='ls-hint'>Tab to the list, then ↑/↓ to walk it, Home/End for
+            the ends, Space to select, Enter to open.</p>
+
+          <List
+            @items={{this.lots}}
+            @key={{this.rowKey}}
+            @rowLabel={{this.rowLabel}}
+            @label='Lots on the desk'
+            @size={{this.size}}
+            @selectionMode={{this.selectionMode}}
+            @divided={{this.divided}}
+            @bordered={{this.bordered}}
+            @itemNoun='lot'
+            @onSelectionChange={{this.onSelectionChange}}
+            @onActivate={{this.onActivate}}
+            @onExpandedChange={{this.onExpandedChange}}
+          >
+            <:header>Twelve lots, newest first</:header>
+            <:item as |row|>
+              <Item @title={{row.tea}} @description={{row.supplier}}>
+                <:leading>
+                  <Chip @label={{row.id}} />
+                </:leading>
+                <:trailing>
+                  {{this.meta row}}
+                </:trailing>
+                <:actions>
+                  <StatusChip @value={{row.grade}} />
+                </:actions>
+              </Item>
+            </:item>
+            <:expanded as |row|>
+              <p class='ls-detail'>{{row.note}}</p>
+              <p class='ls-detail-meta'>{{row.place}} · {{row.price}}</p>
+            </:expanded>
+          </List>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='items'
+          @value={{this.lots}}
+          @description='The collection. items is the flat-collection noun; options and dataSource are accepted aliases so a shadcn or Ant shaped call still lands. Supply EITHER items or load.'
+        />
+        <Args.Action
+          @name='rowLabel'
+          @description='(row, index) => string. The row’s accessible name, used on its selection control. It defaults to "Row N", which is honest but poor — pass this.'
+        />
+        <Args.String
+          @name='selectionMode'
+          @value={{this.selectionMode}}
+          @options={{this.modes}}
+          @defaultValue='none'
+          @description="'none', 'single' or 'multi'. Selection is a real checkbox or radio with its own name, never a listbox option: an option’s children are presentational, so a row holding a link, a button or a named avatar would lose all of it. A list of rich rows is a list."
+          @onInput={{this.setSelectionMode}}
+        />
+        <Args.String
+          @name='size'
+          @value={{this.size}}
+          @options={{this.sizes}}
+          @defaultValue='m'
+          @description='Density on the house scale. Coarse pointers get a 44px row floor regardless, without changing the fine-pointer rhythm.'
+          @onInput={{this.setSize}}
+        />
+        <Args.Bool
+          @name='divided'
+          @value={{this.divided}}
+          @defaultValue={{true}}
+          @description='Hairline between rows.'
+          @onInput={{this.setDivided}}
+        />
+        <Args.Bool
+          @name='bordered'
+          @value={{this.bordered}}
+          @defaultValue={{false}}
+          @description='Frame the whole list, header and footer included.'
+          @onInput={{this.setBordered}}
+        />
+        <Args.Action
+          @name='onExpandedChange'
+          @description='(keys) => void. Supplying an expanded block (row, index) adds an expander button to every row, after the selection control. A row’s detail renders only while it is open, so a long list of collapsed rows renders no bodies. expandedKeys controls which rows are open, defaultExpandedKeys seeds them, and onExpandedChange reports every change either way, by the same rule as DataTable.'
+        />
+        <Args.Action
+          @name='onActivate'
+          @description='(row, index) => void — Enter on the focused row. A row with one obvious destination should carry a real anchor inside the item block instead; a click handler on a row is not a link.'
+        />
+        <Args.Object
+          @name='selected'
+          @description='Controlled selection (array of row keys); defaultSelected seeds the uncontrolled case, onSelectionChange reports every change either way.'
+        />
+        <Args.Bool
+          @name='busy'
+          @value={{false}}
+          @defaultValue={{false}}
+          @description='A caller-driven pending state: aria-busy without replacing the rows, so focus and scroll position survive. loading is accepted as an alias. This is React Aria’s isPending semantics rather than a disabled swap.'
+          @hideControls={{true}}
+        />
+        <Args.Yield
+          @description='Named blocks: item (row, index, api) where api is { index, selected, active, toggle }; expanded (row, index) for the per-row detail; header and footer inside the frame; and loading / empty / error.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .ls-demo {
+        display: grid;
+        gap: var(--space-4, 11px);
+        min-width: 0;
+      }
+      .ls-readout {
+        display: flex;
+        flex-wrap: wrap;
+        gap: var(--space-4, 11px);
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+      .ls-readout strong {
+        color: var(--foreground);
+        font-weight: 500;
+      }
+      .ls-detail,
+      .ls-detail-meta {
+        margin: 0;
+        font-size: var(--text-ui-sm, 11.5px);
+        line-height: 1.5;
+      }
+      .ls-detail-meta {
+        color: var(--muted-foreground);
+        font-family: var(--font-mono);
+      }
+      .ls-hint {
+        margin: 0;
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_LIST: Record<string, unknown> = {
+  List: ListUsage,
+};

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

@@ -0,0 +1,2 @@
+// Pretui — Loader: The shadcn / Mantine name for Spinner.
+export { Spinner as Loader } from './spinner';

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

@@ -0,0 +1,33 @@
+## What it is
+
+**Loader** is **Spinner** under the name shadcn and Mantine use. The export is the same class. Import it when a port already says Loader; the **Spinner** writeup carries the depth. Ant's `Spin` wrapping its children is a different component — that is **LoadingOverlay** — and a labelled "Loading…" row is **LoadingState**.
+
+## The contract
+
+```
+@size?   — pixels, or any spelling of the xs · s · m · l · xl scale
+```
+
+Identical to Spinner. Colour is `currentColor`, so tint the wrapper, not the component.
+
+## Prior art
+
+**Mantine `Loader`** has a `type` enum (oval, bars, dots) and its own `color`; **shadcn `Spinner`** is a single SVG that takes a `className`; **Ant `Spin`** adds `spinning`, a `tip` and children to overlay. Spinner is one ring with one size arg. It inherits ink instead of taking a colour, which is what lets it sit inside any **Button** tone unchanged, and it has no wrapping mode.
+
+## Accessibility
+
+No APG pattern. Spinner renders `role="status"` with `aria-label="Loading"`; pass a more specific `aria-label` through `...attributes` so several spinners on one page do not all say the same thing. The region mounts with its name already in place, so the announcement is not guaranteed — write "Loaded 24 results" into a persistent live region when loading ends. Reduced motion slows the rotation to 2.8s rather than stopping it.
+
+## Theming
+
+`currentColor` for both the track (at 25% alpha) and the indicator; there are no spinner-specific tokens. The 1.5px stroke, 0.7s period and 13px default size are fixed. A theme only needs `--foreground`, `--muted-foreground` and each Button tone's on-color to read at 25% alpha.
+
+## React ecosystem
+
+| shadcn / Mantine / Ant         | Pretui                                      |
+| ------------------------------ | ------------------------------------------- |
+| `Loader` / `Spinner` `size`    | `@size`                                     |
+| Mantine `type`                 | one ring; no enum                           |
+| Mantine `color`                | wrapper `color`, inherited                  |
+| Ant `Spin spinning` + children | **LoadingOverlay**                          |
+| Ant `tip`                      | **LoadingState** / **LoadingOverlay** label |

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

@@ -0,0 +1,35 @@
+// Pretui — Loader usage page.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { FreestyleUsage } from './freestyle-usage';
+import { Loader } from './loader';
+
+const LoaderUsage: TemplateOnlyComponent = <template>
+  <FreestyleUsage
+    @name='Loader'
+    @description='Spinner under the shadcn and Mantine name: an indeterminate ring that takes its colour from the surrounding text. Import it when a port already says Loader; the component and its writeup are Spinner.'
+    @source='<Loader @size={{20}} />'
+  >
+    <:example>
+      <Loader @size={{20}} />
+      <span class='tint-primary'><Loader @size={{20}} /></span>
+      <span class='tint-danger'><Loader @size={{20}} /></span>
+    </:example>
+    <:api as |Args|>
+      <Args.Number @name='size' @defaultValue={{13}} @description='Pixels, or any spelling of the xs · s · m · l · xl scale.' />
+    </:api>
+  </FreestyleUsage>
+  <style scoped>
+    .tint-primary {
+      color: var(--pretui-primary-ink, var(--boxel-highlight-hover));
+      display: inline-flex;
+    }
+    .tint-danger {
+      color: var(--pretui-destructive-ink, var(--boxel-danger));
+      display: inline-flex;
+    }
+  </style>
+</template>;
+
+export const DEMOS_LOADER: Record<string, unknown> = {
+  Loader: LoaderUsage,
+};

package/bundled-realms/pretui/components/loading-overlay.gts

@@ -0,0 +1,120 @@
+// Pretui — LoadingOverlay: a scrim and spinner over a region whose content stays mounted.
+import Component from '@glimmer/component';
+import { Spinner } from './spinner';
+import type { PretuiSizeArg } from '../pretui-primitives';
+
+export interface LoadingOverlaySignature {
+  Args: {
+    /** Show the overlay. The content underneath renders either way. */
+    open?: boolean;
+    /** What is loading, announced and shown under the spinner (default 'Loading'). */
+    label?: string;
+    /** Paint the label under the spinner; it is announced either way. */
+    showLabel?: boolean;
+    /** Frost the content under the scrim instead of only tinting it. */
+    blur?: boolean;
+    /** Make the content inert while open, so a half-loaded form cannot be edited. */
+    lock?: boolean;
+    /** Spinner size on the kit scale, or pixels (default 'l'). */
+    size?: number | PretuiSizeArg;
+  };
+  Blocks: {
+    default: [];
+  };
+  Element: HTMLDivElement;
+}
+
+/**
+ * The region keeps its content: the overlay sits over it rather than
+ * replacing it, so nothing reflows when loading starts or stops (Law 8).
+ * Skeleton is for content that does not exist yet, Spinner is inline, and
+ * LoadingState is a whole scene.
+ *
+ * `aria-busy` goes on the region, so assistive technology holds off reading
+ * changes until it clears. The status is one live region that stays mounted,
+ * so the announcement is not lost to a mount in the same frame. `@lock` adds
+ * `inert` to the content, which removes it from the tab order and the
+ * accessibility tree until loading ends.
+ */
+export class LoadingOverlay extends Component<LoadingOverlaySignature> {
+  get open(): boolean {
+    return this.args.open ?? false;
+  }
+  get label(): string {
+    return this.args.label ?? 'Loading';
+  }
+  get locked(): boolean {
+    return this.open && (this.args.lock ?? false);
+  }
+
+  <template>
+    <div
+      class='pretui-loading-overlay'
+      aria-busy={{if this.open 'true' 'false'}}
+      data-open={{if this.open 'true' 'false'}}
+      data-test-pretui-loading-overlay
+      ...attributes
+    >
+      <div class='pretui-lo-content' inert={{this.locked}} data-test-pretui-loading-overlay-content>
+        {{yield}}
+      </div>
+      <div class='pretui-lo-status' role='status' data-test-pretui-loading-overlay-status>
+        {{#if this.open}}<span class='pretui-lo-sr'>{{this.label}}</span>{{/if}}
+      </div>
+      {{#if this.open}}
+        <div class='pretui-lo-scrim' data-blur={{if @blur 'true' 'false'}} aria-hidden='true' data-test-pretui-loading-overlay-scrim>
+          <Spinner @size={{if @size @size 'l'}} aria-hidden='true' role='presentation' />
+          {{#if @showLabel}}<span class='pretui-lo-label'>{{this.label}}</span>{{/if}}
+        </div>
+      {{/if}}
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-loading-overlay {
+          position: relative;
+          isolation: isolate;
+          min-inline-size: 0;
+        }
+        .pretui-lo-scrim {
+          position: absolute;
+          inset: 0;
+          z-index: 1;
+          display: flex;
+          flex-direction: column;
+          align-items: center;
+          justify-content: center;
+          gap: var(--space-2, 0.5rem);
+          border-radius: inherit;
+          color: var(--foreground);
+          background: color-mix(in oklch, var(--card) var(--pretui-loading-overlay-mix, 72%), transparent);
+          animation: pretui-lo-in var(--pretui-dur-snap, 160ms) var(--pretui-ease-snap, ease-out) both;
+        }
+        .pretui-lo-scrim[data-blur='true'] {
+          backdrop-filter: blur(var(--pretui-loading-overlay-blur, 3px));
+        }
+        .pretui-lo-label {
+          font-size: var(--text-ui-sm, 0.8125rem);
+          color: var(--muted-foreground);
+        }
+        .pretui-lo-sr {
+          position: absolute;
+          inline-size: 1px;
+          block-size: 1px;
+          overflow: hidden;
+          clip-path: inset(50%);
+          white-space: nowrap;
+        }
+        @keyframes pretui-lo-in {
+          from {
+            opacity: 0;
+          }
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-lo-scrim {
+            animation: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/loading-overlay.md

@@ -0,0 +1,68 @@
+## What it is
+
+A **scrim and spinner over a region whose content is still there**. The content does not unmount when loading starts, so nothing reflows when it stops (Law 8). Wrap the region, a form being saved or a table being refreshed, and bind `@open` to the pending state.
+
+Reach for a neighbour when the situation is different:
+
+- **Skeleton** when there is no content yet to cover.
+- **Spinner** for an inline busy mark beside a label or inside a button.
+- **LoadingState** when the whole scene is loading and there is nothing to keep.
+- **Backdrop** for the scrim behind a layered surface such as a dialog.
+
+LoadingOverlay covers one region in place.
+
+## The contract
+
+```
+@open? (default false)
+@label? (default 'Loading'), @showLabel?
+@blur?, @lock?
+@size? (the spinner, on the kit scale or in pixels; default 'l')
+<:default>   — the region; it stays mounted
+Element: HTMLDivElement
+```
+
+**The content is always rendered.** The overlay is a sibling layer over it, absolutely positioned inside the region, never a replacement for it. Toggling `@open` does not re-create the content, so focus, scroll position and half-typed input survive a save.
+
+**One announcement, always mounted.** The region carries a `role="status"` element for its whole life. Opening puts `@label` into it, so screen readers hear "Saving billing details" rather than missing a live region that was mounted in the same frame as its text. The spinner inside the scrim is hidden from assistive technology, so the label is announced once.
+
+**`@lock` is the guard against editing half-loaded fields.** While open, it sets `inert` on the content, which takes it out of the tab order and the accessibility tree. Without `@lock`, the scrim blocks the pointer but a keyboard user can still tab into the region. That is right for a background refresh and wrong for a submit.
+
+`@showLabel` paints the label under the spinner. `@blur` frosts the content under the scrim instead of only tinting it.
+
+## Prior art
+
+**Mantine LoadingOverlay** takes `visible`, `loaderProps`, `overlayProps` (blur, colour, opacity) and `zIndex`, and expects the caller to make the parent `position: relative`. **Ant Spin** wraps its children with `spinning` and a `tip`, and blurs the content. **Chakra** has no component; it is Overlay plus Spinner by composition.
+
+Where Pretui is better: **the region is part of the component**, so there is no "remember to make the parent relative". **`aria-busy` is set on the region**, which Mantine does not do and Ant only does on its spinner. **Locking is one switch**: neither Mantine nor Ant stops a keyboard user from tabbing into a covered form. **The announcement survives**, because the status element exists before the text arrives.
+
+Where it is thinner: **no delay.** Ant's `delay` holds the spinner back for fast operations to avoid a flash, and here that is the caller's job. There is **no custom loader slot**, because the spinner is the kit's Spinner. **No progress value**: use **ProgressBar** inside the region for determinate work.
+
+## Accessibility
+
+No APG pattern. What matters is the busy state and one clear announcement.
+
+- **`aria-busy`** is `"true"` on the region while open and `"false"` otherwise. The tests assert both.
+- **The status region** is `role="status"`, mounted for the component's whole life and empty while closed. It holds `@label` while open. The tests assert the text and that there is exactly one status element: the spinner's own role is replaced with `presentation` and hidden.
+- **`@lock`** sets `inert` on the content only while open, and clears it when loading ends. The tests assert all three states and that `inert` stays off without `@lock`.
+- **The scrim is `aria-hidden`**. It is decoration, and the status region carries the meaning.
+- **Say what is loading.** "Loading" is the fallback, but "Saving billing details" tells a screen reader user what they are waiting for. The label is the caller's to write.
+- **Focus is the caller's job.** If the element that had focus becomes inert under `@lock`, focus moves to the body. Return it when the work finishes if it matters.
+
+## Theming
+
+`--pretui-loading-overlay-mix` (how opaque the scrim is: `--card` mixed with transparent, default 72%), `--pretui-loading-overlay-blur` (the `@blur` radius, default 3px), `--card`, `--foreground` (spinner ink), `--muted-foreground` (the painted label), `--text-ui-sm`, `--space-2` (the gap between spinner and label), `--pretui-dur-snap` and `--pretui-ease-snap` (the fade-in).
+
+The scrim mixes against `--card`, so dark mode gets a dark scrim without asking. The fade-in is skipped under `prefers-reduced-motion`. Covering the region edge to edge and inheriting its corner radius are fixed.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+| Agent types                              | Give them                              |
+| ---------------------------------------- | -------------------------------------- |
+| Mantine `<LoadingOverlay visible>`       | `@open`                                |
+| Ant `<Spin spinning tip>` around content | `@open` + `@label` + `@showLabel`      |
+| `overlayProps={{ blur }}`                | `@blur`                                |
+| `loaderProps={{ size }}`                 | `@size`                                |
+| `zIndex`                                 | not needed: the overlay stacks locally |

package/bundled-realms/pretui/components/loading-overlay.usage.gts

@@ -0,0 +1,102 @@
+// Pretui — LoadingOverlay usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { LoadingOverlay } from './loading-overlay';
+import { Input } from './input';
+import { Button } from './button';
+
+export class LoadingOverlayUsage extends Component {
+  @tracked open = true;
+  @tracked label = 'Saving billing details';
+  @tracked showLabel = true;
+  @tracked blur = false;
+  @tracked lock = true;
+  @tracked accountName = 'Northwind Roasters';
+  setOpen = (v: boolean) => (this.open = v);
+  setLabel = (v: string) => (this.label = v);
+  setShowLabel = (v: boolean) => (this.showLabel = v);
+  setBlur = (v: boolean) => (this.blur = v);
+  setLock = (v: boolean) => (this.lock = v);
+  setAccountName = (v: string) => (this.accountName = v);
+  get usage() {
+    let bits = [`@open={{${this.open}}}`, `@label='${this.label}'`];
+    if (this.showLabel) bits.push('@showLabel={{true}}');
+    if (this.blur) bits.push('@blur={{true}}');
+    if (this.lock) bits.push('@lock={{true}}');
+    return `<LoadingOverlay ${bits.join(' ')}>\n  …the form…\n</LoadingOverlay>`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='LoadingOverlay'
+      @description='A scrim and spinner over a region whose content stays mounted, so nothing reflows when loading starts or stops. The region is aria-busy while open, and @lock makes the content inert so a half-saved form cannot be edited. Skeleton is for content that does not exist yet; Spinner is inline.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <LoadingOverlay
+          @open={{this.open}}
+          @label={{this.label}}
+          @showLabel={{this.showLabel}}
+          @blur={{this.blur}}
+          @lock={{this.lock}}
+        >
+          <div class='lo-demo-form'>
+            <Input @value={{this.accountName}} @onInput={{this.setAccountName}} aria-label='Account name' />
+            <Input @value='accounts@northwind.example' aria-label='Billing email' />
+            <Button @appearance='accent'>Save</Button>
+          </div>
+        </LoadingOverlay>
+      </:example>
+      <:api as |Args|>
+        <Args.Bool
+          @name='open'
+          @defaultValue={{false}}
+          @value={{this.open}}
+          @description='Show the overlay. The content underneath renders either way.'
+          @onInput={{this.setOpen}}
+        />
+        <Args.String
+          @name='label'
+          @defaultValue='Loading'
+          @value={{this.label}}
+          @description='What is loading. Announced through the status region whether or not it is painted.'
+          @onInput={{this.setLabel}}
+        />
+        <Args.Bool
+          @name='showLabel'
+          @defaultValue={{false}}
+          @value={{this.showLabel}}
+          @description='Paint the label under the spinner.'
+          @onInput={{this.setShowLabel}}
+        />
+        <Args.Bool
+          @name='blur'
+          @defaultValue={{false}}
+          @value={{this.blur}}
+          @description='Frost the content under the scrim instead of only tinting it.'
+          @onInput={{this.setBlur}}
+        />
+        <Args.Bool
+          @name='lock'
+          @defaultValue={{false}}
+          @value={{this.lock}}
+          @description='Make the content inert while open: out of the tab order and the accessibility tree.'
+          @onInput={{this.setLock}}
+        />
+        <Args.Yield @name='default' @description='The region being loaded. It stays mounted.' />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .lo-demo-form {
+        display: grid;
+        gap: var(--space-2, 0.5rem);
+        padding: var(--space-4, 1rem);
+        max-inline-size: 22rem;
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_LOADING_OVERLAY: Record<string, unknown> = {
+  LoadingOverlay: LoadingOverlayUsage,
+};