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

package/bundled-realms/pretui/components/stacking-cards.gts

@@ -0,0 +1,137 @@
+// Pretui — StackingCards: cards that stack as the page scrolls.
+import Component from '@glimmer/component';
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { hash } from '@ember/helper';
+import { cssNumber } from '../pretui-css';
+import { styleVar } from '../internal/structure-scenes';
+
+// ── StackingCards — TRANSCRIBED from fancy StackingCards ─────────────────
+// Cards pin and stack while the surrounding context scrolls. The original
+// couples useScroll progress to per-card scale transforms (scaleMultiplier
+// × totalCards bookkeeping through React context). This transcription is
+// pure CSS: every card is position: sticky with an nth-child-stepped top
+// (base --pretui-stack-top + index × @offset, indices capped at 8 steps —
+// deeper stacks share the 8th ledge), so each card pins slightly below
+// the previous one and the next card scrolls up over it. The subtle
+// depth cue is a STATIC nth-last-child scale (buried cards 0.97–0.99,
+// top card 1.0) — what the JS original adds that we skip is the
+// scroll-progress-LINKED version of that scale (cards shrinking live as
+// they are buried) plus arbitrary scroll-container options. No timers,
+// no animation — sticky positioning is scroll-coupled layout, so there
+// is no motion for prefers-reduced-motion to remove. Cards must be
+// direct children of the group (nth-child math); scroll travel between
+// pins comes from --pretui-stack-gap (default 24px) plus card height.
+
+export interface StackingCardsSignature {
+  Args: {
+    /** px each card's pin ledge sits below the previous card's — default 12 */
+    offset?: number;
+  };
+  Blocks: {
+    /** yields { Card } — render each stacked card as a direct child */
+    default: [{ Card: typeof StackingCard }];
+  };
+  Element: HTMLDivElement;
+}
+
+interface StackingCardSignature {
+  Blocks: {
+    default: [];
+  };
+  Element: HTMLElement;
+}
+
+const StackingCard: TemplateOnlyComponent<StackingCardSignature> = <template>
+  <article class='pretui-stacking-card' data-test-pretui-stacking-card ...attributes>
+    {{yield}}
+  </article>
+  <style scoped>
+    @layer PretComponent {
+      .pretui-stacking-card {
+        position: sticky;
+        top: calc(
+          var(--pretui-stack-top, 12px) +
+            var(--pretui-stack-index, 0) * var(--pretui-stack-offset, 12px)
+        );
+        transform-origin: top center;
+        border-radius: var(--radius-surface, 10px);
+        background: var(--card);
+        color: var(--card-foreground);
+        box-shadow:
+          0 0 0 1px var(--border),
+          var(--pretui-shadow-card, 0 8px 24px rgba(20, 18, 26, 0.08));
+      }
+      .pretui-stacking-card + .pretui-stacking-card {
+        margin-top: var(--pretui-stack-gap, 24px);
+      }
+      /* nth-child-stepped pin ledges — capped at 8 steps. */
+      .pretui-stacking-card:nth-child(1) {
+        --pretui-stack-index: 0;
+      }
+      .pretui-stacking-card:nth-child(2) {
+        --pretui-stack-index: 1;
+      }
+      .pretui-stacking-card:nth-child(3) {
+        --pretui-stack-index: 2;
+      }
+      .pretui-stacking-card:nth-child(4) {
+        --pretui-stack-index: 3;
+      }
+      .pretui-stacking-card:nth-child(5) {
+        --pretui-stack-index: 4;
+      }
+      .pretui-stacking-card:nth-child(6) {
+        --pretui-stack-index: 5;
+      }
+      .pretui-stacking-card:nth-child(7) {
+        --pretui-stack-index: 6;
+      }
+      .pretui-stacking-card:nth-child(8) {
+        --pretui-stack-index: 7;
+      }
+      .pretui-stacking-card:nth-child(n + 9) {
+        --pretui-stack-index: 8;
+      }
+      /* Static depth cue — the JS original animates this with scroll
+         progress; here buried cards simply sit at a smaller resting scale. */
+      .pretui-stacking-card:nth-last-child(2) {
+        transform: scale(0.99);
+      }
+      .pretui-stacking-card:nth-last-child(3) {
+        transform: scale(0.98);
+      }
+      .pretui-stacking-card:nth-last-child(n + 4) {
+        transform: scale(0.97);
+      }
+    }
+  </style>
+</template>;
+
+export class StackingCards extends Component<StackingCardsSignature> {
+  get offsetStyle(): string {
+    return styleVar(
+      '--pretui-stack-offset',
+      `${cssNumber(this.args.offset, 0, 512) ?? 12}px`,
+    );
+  }
+  <template>
+    <div
+      class='pretui-stacking-cards'
+      style={{this.offsetStyle}}
+      data-test-pretui-stacking-cards
+      ...attributes
+    >
+      {{yield (hash Card=StackingCard)}}
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-stacking-cards {
+          display: block;
+          font-size: var(--text-ui-md, 12.5px);
+          letter-spacing: var(--track-ui, 0.01em);
+          color: var(--foreground);
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/stacking-cards.md

@@ -0,0 +1,40 @@
+## What it is
+
+Cards that stack as you scroll: each one pins at a ledge below the previous, so the set builds into a deck rather than scrolling away.
+
+## The contract
+
+```
+@offset? — px each card's pin ledge sits below the previous card's. Default 12
+
+<:default> — yields { Card }; render each stacked card as a direct child
+```
+
+One arg, and a yielded component. The card is yielded rather than being a separate import so a caller cannot use it outside a stack, where the pinning would have nothing to pin against.
+
+**`@offset` is the ledge depth**, and it accumulates: the fifth card in a stack sits four offsets below the first. That is what makes the deck legible as a count.
+
+**The pinning is CSS sticky**, not a scroll listener — there is no measurement and no frame loop.
+
+## Prior art
+
+The stacking-cards scroll effect in marketing sites.
+
+Where Pretui is better: it is `position: sticky` and an offset rather than a scroll-driven transform, which means it costs nothing, cannot desync, and works with the browser's own scrolling rather than against it.
+
+Where it is thinner: no horizontal stacking, no scale or rotation as cards recede, and no control over which card is "active" — the browser decides, by scroll position.
+
+## Accessibility
+
+- **The cards are in source order and stay there.** Stacking is a visual arrangement produced by sticky positioning; nothing is reordered, hidden or removed, so a screen reader encounters the full set in sequence regardless of scroll position.
+- **That is the property that makes this effect safe**, and it is worth stating because most scroll-driven card effects achieve the look by transforming or removing elements.
+- **Reduced motion does not need a special case**, because there is no animation — the cards move with the scroll, not on a timeline.
+- **A deep stack accumulates offset**, so with a large `@offset` and many cards the last card's usable height shrinks. That is a layout consequence, and it hits anyone using a small viewport or large text hardest.
+
+## Theming
+
+`--pretui-stack-offset` (from `@offset`), `--pretui-stack-gap`, `--pretui-stack-index` and `--pretui-stack-top` — the per-card index and its computed pin position.
+
+The cards themselves take whatever surface the caller gives them; the component supplies position and nothing else, which is what lets a stack be built from any card in the kit.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/stacking-cards.usage.gts

@@ -0,0 +1,124 @@
+// Pretui — StackingCards usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { StackingCards } from './stacking-cards';
+
+// ── StackingCards ← fancy StackingCards ──────────────────────────────────
+// Live knob: offset (per-card pin ledge — replaces the original's
+// topPosition strings). Dropped surface: scaleMultiplier + totalCards
+// (the scroll-progress scale engine is not transcribed — the CSS version
+// uses a static nth-last-child resting scale), scrollOptions, and
+// per-item index wiring (nth-child does the counting). Scroll the host
+// to watch cards pin and stack.
+const STACK_CARDS = [
+  {
+    eyebrow: 'scene 01',
+    title: 'Pin the header',
+    copy: 'The first card reaches --pretui-stack-top and holds while the page keeps moving.',
+  },
+  {
+    eyebrow: 'scene 02',
+    title: 'Stack the second',
+    copy: 'Each successive card pins one @offset ledge lower, covering the one before.',
+  },
+  {
+    eyebrow: 'scene 03',
+    title: 'Bury the early ones',
+    copy: 'Buried cards rest at a slightly smaller scale — the static cut of the depth cue.',
+  },
+  {
+    eyebrow: 'scene 04',
+    title: 'Land the last',
+    copy: 'The final card rides at full scale; the stack releases when the group scrolls past.',
+  },
+];
+
+class StackingCardsUsage extends Component {
+  cards = STACK_CARDS;
+  @tracked offset = 12;
+  setOffset = (v: number | null) => (this.offset = v ?? 12);
+  get usage() {
+    return `<StackingCards @offset={{${this.offset}}} as |s|>\n  <s.Card>…</s.Card>\n  <s.Card>…</s.Card>\n</StackingCards>`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='StackingCards'
+      @description='Cards pin and stack while scrolling — each card is position: sticky with an nth-child-stepped top, so it holds its ledge while the next card scrolls up over it. Pure CSS: no scroll listeners, no timers, and nothing animates on a clock (sticky is scroll-coupled layout, so reduced-motion needs nothing removed). Transcribed from fancy StackingCards; the JS original additionally shrinks buried cards live with scroll progress — here that depth cue is a static resting scale.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='stack-scroller'>
+          <StackingCards @offset={{this.offset}} as |s|>
+            {{#each this.cards as |card|}}
+              <s.Card>
+                <div class='stack-card-body'>
+                  <span class='stack-eyebrow'>{{card.eyebrow}}</span>
+                  <h4 class='stack-title'>{{card.title}}</h4>
+                  <p class='stack-copy'>{{card.copy}}</p>
+                </div>
+              </s.Card>
+            {{/each}}
+          </StackingCards>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.Number
+          @name='offset'
+          @defaultValue={{12}}
+          @value={{this.offset}}
+          @min={{0}}
+          @max={{48}}
+          @step={{4}}
+          @description="px each card's pin ledge sits below the previous card's — 0 stacks them flush; larger values fan the pinned edges out."
+          @onInput={{this.setOffset}}
+        />
+        <Args.Yield
+          @description='Yields { Card } — render each card as a DIRECT child of the group (the nth-child ledge math depends on it; ledges cap at 8 steps). Scroll travel between pins comes from --pretui-stack-gap (24px) plus card height.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .stack-scroller {
+        height: 340px;
+        overflow-y: auto;
+        padding: var(--space-4, 11px);
+        border-radius: var(--radius-surface, 10px);
+        box-shadow: inset 0 0 0 1px var(--border);
+        background: var(--inset, var(--boxel-100));
+      }
+      .stack-card-body {
+        min-height: 170px;
+        display: grid;
+        align-content: start;
+        gap: 4px;
+        padding: var(--space-5, 16px);
+      }
+      .stack-eyebrow {
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        font-weight: 500;
+        letter-spacing: var(--track-eyebrow, 0.08em);
+        text-transform: uppercase;
+        color: var(--muted-foreground);
+      }
+      .stack-title {
+        margin: 0;
+        font-size: var(--text-ui-lg, 14px);
+        font-weight: 600;
+        color: var(--card-foreground);
+      }
+      .stack-copy {
+        margin: 0;
+        font-size: var(--text-ui-md, 12.5px);
+        color: var(--muted-foreground);
+        max-width: 46ch;
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_STACKING_CARDS: Record<string, unknown> = {
+  StackingCards: StackingCardsUsage,
+};

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

@@ -0,0 +1,216 @@
+// Pretui — Stat: the KPI headline: a rolling number, a delta and a comparison hint.
+import Component from '@glimmer/component';
+import { htmlSafe } from '@ember/template';
+import { Delta } from './delta';
+import { Odometer } from './odometer';
+import { formatNumber, toNumber } from '../internal/reading-format';
+import type { FormatOptionBag } from '../internal/reading-format';
+
+export interface StatSignature {
+  Args: {
+    /** the eyebrow above the number — a short noun phrase, set mono and uppercase */
+    label: string;
+    /**
+     * The headline value. A number is formatted through Intl using the format
+     * knobs below; a string is used verbatim, so a pre-formatted value
+     * ('61%', '9 d', '$12,480') renders exactly as written and still rolls.
+     */
+    value: number | string;
+    /** signed change since the comparison period, rendered as a `Delta` */
+    delta?: number;
+    /** custom text for the delta — passed straight to `Delta`'s own `@format` */
+    deltaFormat?: (n: number) => string;
+    /** small print beside the delta naming the comparison window ('vs spring') */
+    hint?: string;
+    /**
+     * Roll the headline digits when the value changes (default true). Set
+     * false for a value that is really a word, or for a headline that must
+     * wrap — the digit track is an inline-flex row and does not break lines.
+     */
+    roll?: boolean;
+    /** BCP-47 locale tag for number formatting; ignored when `@value` is a string */
+    locale?: string;
+    /** 'decimal' (default), 'currency', 'percent' or 'unit' */
+    style?: 'decimal' | 'currency' | 'percent' | 'unit';
+    /** ISO 4217 code for style='currency'; without it the style degrades to decimal */
+    currency?: string;
+    /** floor on fraction digits */
+    minimumFractionDigits?: number;
+    /** ceiling on fraction digits */
+    maximumFractionDigits?: number;
+    /** grouping separators (default: the locale's own choice) */
+    useGrouping?: boolean | 'always' | 'auto' | 'min2';
+    /** any Intl.NumberFormat option not named above; named knobs win over it */
+    options?: FormatOptionBag;
+    /** rendered when the value is missing or not a finite number (default '—') */
+    placeholder?: string;
+    /**
+     * Live-region politeness for the value a screen reader actually reads.
+     * 'off' (default) because a KPI that rolls on every tick would otherwise
+     * spam; 'polite' only where the value settles at human pace.
+     */
+    announce?: 'off' | 'polite' | 'assertive';
+    /** roll duration in seconds (default 0.5) */
+    duration?: number;
+    /** CSS timing function for the roll (default a sprung cubic-bezier) */
+    ease?: string;
+    /** seconds of delay per digit so the carry cascades (default 0.03; 0 rolls together) */
+    stagger?: number;
+    /** which end the stagger counts from: 'right' (default, like a carry) or 'left' */
+    staggerFrom?: 'right' | 'left';
+    /**
+     * Reserve this many digit columns of width up front. Nothing inside the
+     * block moves when a value grows a column, but the block itself widens —
+     * which shifts the next KPI in a row. Set it to the widest value the
+     * metric can reach ('999' → '1,000' wants 5) and the row stops reflowing.
+     * Unset (default) the box is content-sized.
+     */
+    minDigits?: number;
+  };
+  Element: HTMLDivElement;
+}
+
+// ── Stat — the KPI headline ──────────────────────────────────────────────
+// Ported from the Tremor KPI card (big number, delta chip, comparison hint).
+// Composes two kit primitives rather than re-cutting either: `Delta` (ink)
+// for the signed change, and `Odometer` (reading-format) for the headline
+// number — Law 5's canonical numeric mechanism, where each digit is a window
+// over a 0–9 ring and takes the shortest path around it.
+//
+// Better than the inspiration:
+//   - Tremor's KPI number is a static string; a metric that ticks swaps in
+//     place and the reader has to diff two frames from memory. Here the
+//     digits ROLL, which is exactly the state transition Law 5 says motion is
+//     for. It costs nothing at rest: the first paint is identical to plain
+//     text (Odometer has no previous value to travel from), and a value that
+//     never changes never animates.
+//   - The upstream takes a pre-formatted string only, so every caller writes
+//     its own `Intl` call. `@value` here also accepts a raw number and the
+//     format knobs ride through to Odometer, so the formatting lives in ONE
+//     place for the whole kit. A string is still used verbatim, so '61%' and
+//     '9 d' read exactly as written — and still roll, since Odometer rolls
+//     the digit positions of any string.
+//   - The label sits at the inline start of its own grid row, so a value that
+//     grows a column ('999' → '1,000') extends to the inline END and nothing
+//     inside the block shifts. What CAN shift is the block's own width, and
+//     with it a sibling KPI in a row — `@minDigits` reserves the columns up
+//     front so the row never reflows.
+//
+// Dropped from the Odometer surface deliberately: `@cellHeight`. Stat derives
+// it from its own headline line-height (`--pretui-stat-line`) so the digit
+// cells and the text line box are the same height; letting a caller set them
+// apart is the one knob that CAN move the label.
+export class Stat extends Component<StatSignature> {
+  get hasDelta() {
+    return this.args.delta !== undefined;
+  }
+  get deltaValue() {
+    return this.args.delta ?? 0;
+  }
+  /** rolling is the default; @roll={{false}} falls back to plain text */
+  get rolling() {
+    return this.args.roll ?? true;
+  }
+  // One digit cell === one headline line box. Expressed against the same
+  // custom property the CSS line-height reads, so a consumer that restyles
+  // `--pretui-stat-line` moves both together and the baseline stays put.
+  cellHeight = 'calc(var(--pretui-stat-line, 1.2) * 1em)';
+
+  get valueStyle(): ReturnType<typeof htmlSafe> | undefined {
+    let digits = this.args.minDigits;
+    return digits && digits > 0
+      ? htmlSafe(`--pretui-stat-min-digits: ${Math.trunc(digits)}`)
+      : undefined;
+  }
+
+  // The non-rolling branch. Same `formatNumber` the Odometer path runs
+  // through — the formatting is reused, not re-implemented, so the two
+  // branches cannot print a value differently.
+  get text(): string {
+    let raw = this.args.value;
+    if (typeof raw === 'string' && raw !== '') {
+      return raw;
+    }
+    let n = toNumber(raw);
+    if (n === undefined) {
+      return this.args.placeholder ?? '—';
+    }
+    let a = this.args;
+    return formatNumber(n, a.locale, {
+      ...(a.options ?? {}),
+      style: a.style,
+      currency: a.currency,
+      minimumFractionDigits: a.minimumFractionDigits,
+      maximumFractionDigits: a.maximumFractionDigits,
+      useGrouping: a.useGrouping,
+    });
+  }
+  <template>
+    <div class='pretui-stat' data-test-pretui-stat ...attributes>
+      <span class='pretui-stat-label'>{{@label}}</span>
+      <span
+        class='pretui-stat-value'
+        style={{this.valueStyle}}
+      >{{#if this.rolling}}<Odometer
+            @value={{@value}}
+            @locale={{@locale}}
+            @style={{@style}}
+            @currency={{@currency}}
+            @minimumFractionDigits={{@minimumFractionDigits}}
+            @maximumFractionDigits={{@maximumFractionDigits}}
+            @useGrouping={{@useGrouping}}
+            @options={{@options}}
+            @placeholder={{@placeholder}}
+            @announce={{@announce}}
+            @duration={{@duration}}
+            @ease={{@ease}}
+            @stagger={{@stagger}}
+            @staggerFrom={{@staggerFrom}}
+            @cellHeight={{this.cellHeight}}
+          />{{else}}{{this.text}}{{/if}}</span>
+      <span class='pretui-stat-foot'>
+        {{#if this.hasDelta}}<Delta @value={{this.deltaValue}} @format={{@deltaFormat}} />{{/if}}
+        {{#if @hint}}<span class='pretui-stat-hint'>{{@hint}}</span>{{/if}}
+      </span>
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-stat {
+          display: grid;
+          gap: 3px;
+          align-content: start;
+        }
+        .pretui-stat-label {
+          font-family: var(--font-mono);
+          font-size: 10.5px;
+          letter-spacing: var(--track-eyebrow, 0.08em);
+          text-transform: uppercase;
+          color: var(--muted-foreground);
+        }
+        .pretui-stat-value {
+          font-size: var(--text-stat, 25px);
+          font-weight: 600;
+          letter-spacing: var(--track-heading, -0.02em);
+          font-variant-numeric: tabular-nums;
+          line-height: var(--pretui-stat-line, 1.2);
+          /* Column reservation (@minDigits): one tabular digit advance is 1ch
+             plus the tracking that follows it. Unset it resolves to 0 and the
+             box is content-sized exactly as before. */
+          min-width: calc(
+            var(--pretui-stat-min-digits, 0) *
+              (1ch + var(--track-heading, -0.02em))
+          );
+        }
+        .pretui-stat-foot {
+          display: flex;
+          align-items: baseline;
+          gap: 6px;
+        }
+        .pretui-stat-hint {
+          font-size: var(--text-ui-xs, 11px);
+          color: var(--ink-3, var(--boxel-400));
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,57 @@
+## What it is
+
+A headline number with a label and an optional signed change: the KPI tile. Use it at the top of a dashboard or panel where one figure is the point. If you need several, put several in a row — there is no group component, deliberately. If the number is a proportion, **ProgressBar** or **Meter** carries more meaning. If it is a category, **Chip**. If you want the rolling digits without the label/delta framing, use **Odometer** directly.
+
+## The contract
+
+```
+@label, @value
+@delta?, @roll? (default true), @minDigits?, @placeholder? ('—')
+@locale?, @style?, @currency?, @minimumFractionDigits?, @maximumFractionDigits?, @useGrouping?, @options?
+@announce?, @duration?, @ease?, @stagger?
+```
+
+The `Intl.NumberFormat` surface is passed through wholesale, so currency, percent and grouping are the platform's, not a bespoke formatter.
+
+Three decisions worth understanding.
+
+**The headline rolls by default, and the roll is timer-free.** `@roll` delegates to **Odometer**, whose digit animation is one CSS animation keyed off each digit's from→to pair. Realm components own no timers — the prerenderer blocks them — so the alternative would have been no animation at all. `@roll={{false}}` falls back to plain text.
+
+**Both branches format through the same `formatNumber`.** The rolling path and the static path cannot print a value differently, because the formatting is reused rather than reimplemented. That sounds obvious and is the thing that goes wrong in every dashboard with two render paths.
+
+**Odometer's cell-height arg is deliberately not re-exposed here.** Stat derives it as `calc(var(--pretui-stat-line) * 1em)` from its own headline line-height, so a digit cell and the text line box are exactly the same height. Letting a caller set them apart is the one knob that can shift the label's baseline, so it is not exposed. `@minDigits` reserves width up front (via `--pretui-stat-min-digits`) so the row never reflows as digits are added.
+
+## Prior art
+
+**Nobody ships a Stat component.** Radix, Web Awesome, shadcn and React Spectrum all leave it to composition; shadcn's dashboard blocks assemble one from `Card` + `CardHeader` + text. The recognisable references are product patterns — Stripe Dashboard, Linear's insights, Vercel Analytics — plus **motion-primitives' `AnimatedNumber`** and **cult-ui's `animated-number`** for the rolling digits specifically.
+
+Where Pretui's version earns its place:
+
+- **The rolling digits are CSS, not a JS tween.** Every animated-number implementation in the reference set drives a `requestAnimationFrame` loop or a spring; this one is an animation keyed off the digit pair, which means it works under prerender, cannot leak, and costs nothing when off-screen.
+- **The layout cannot jump.** `@minDigits` plus the derived cell height means a value going from 999 to 1,000 does not shift the label or the delta. Hand-rolled KPI tiles reflow constantly.
+- **`Intl` passthrough rather than a bespoke format API.** Spectrum does this too; most dashboard components invent `prefix`/`suffix`/`decimals` props that cannot express a locale.
+
+Where it is thin: no sparkline slot, no icon, no comparison-period label ("vs. last month" is on you), no size axis, and no grouping component. Composing `Delta` is built in; composing anything else is not.
+
+## Accessibility
+
+No APG pattern; this is text, governed by WCAG **1.3.1**, **4.1.3** and **2.3.3**.
+
+What is right: `@announce` is passed through to Odometer, so the rolling value can be announced deliberately rather than by accident — and it is opt-in, which is correct, because a live-updating number in a live region narrates endlessly.
+
+Gaps:
+
+- **The label and value have no programmatic association.** They are two sibling `<span>`s. A screen-reader user hears "Revenue" then "1,284,000" then possibly "+12%" as three unrelated fragments. Wrapping in a `<dl>`/`<dt>`/`<dd>` — the markup **KeyValue** already uses — or pointing `aria-labelledby` from the value at the label would fix it, and this is the clearest change to make.
+- **The label is a `<span>`, not a heading**, so a dashboard of stats has no structure to navigate by.
+- **The rolling digits are a per-digit DOM structure.** Unless Odometer supplies a flat text mirror, a screen reader may encounter the digit cells individually — "one, comma, two, eight, four". Verify what `@roll={{true}}` announces before shipping it in a dashboard; `@roll={{false}}` is the safe path and produces identical text.
+- **The `@delta`'s direction is colour plus a `+`/`-` character at 11.5px** — see **Delta**'s own note. In a Stat this matters more, because the delta is often the actionable part of the tile and it is the smallest, lowest-contrast element in it.
+- **Continuously updating numbers and WCAG 2.2.2.** A Stat wired to live data animates on every change; there is no pause control and no `prefers-reduced-motion` branch documented at this level (Odometer owns that — check it).
+- **`@placeholder` defaults to `'—'`**, which several screen readers announce as "em dash" or skip entirely. A visually-hidden "no data" would be kinder.
+
+## Theming
+
+`--pretui-stat-line` (the headline line-height ratio, and the thing the digit cell height is derived from — the one token that moves both together), `--pretui-stat-min-digits` (set from `@minDigits`), plus the kit's type scale for the headline and `--muted-foreground` for the label. The delta's colours are **Delta**'s (`--success`, `--destructive`, `--muted-foreground`), and the rolling digits' motion tokens are **Odometer**'s (`@duration`, `@ease`, `@stagger` are args, not tokens).
+
+`--pretui-stat-line` is the important one: a theme that restyles the headline's line-height through it gets the digit cells moving in lockstep and the baseline staying put. An override that instead sets `line-height` directly on `.pretui-stat-value` will desynchronize the two and the label will shift when the value rolls.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,16 @@
+// Pretui — Stat usage page.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { FreestyleUsage } from './freestyle-usage';
+import { Stat } from './stat';
+
+const StatUsage: TemplateOnlyComponent = <template>
+    <FreestyleUsage @name='Stat' @description='A KPI headline that composes locale-aware rolling digits with a signed textual delta and comparison window.' @source='<Stat @label="Approved lots" @value={{1482}} @delta={{12}} … />'>
+      <:example><div class='stat-grid'><Stat @label='Approved lots' @value={{1482}} @delta={{12}} @hint='vs spring' @minDigits={{5}} /><Stat @label='Reserve value' @value={{286400}} @style='currency' @currency='USD' @delta={{-3}} @hint='vs estimate' /></div></:example>
+      <:api as |Args|><Args.String @name='label' @value='Approved lots' /><Args.Number @name='value' @value={{1482}} /><Args.Number @name='delta' @value={{12}} /><Args.String @name='hint' @value='vs spring' /><Args.Bool @name='roll' @defaultValue={{true}} /></:api>
+    </FreestyleUsage>
+    <style scoped>.stat-grid { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: var(--space-8, 34px); }</style>
+  </template>;
+
+export const DEMOS_STAT: Record<string, unknown> = {
+  Stat: StatUsage,
+};