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

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

@@ -0,0 +1,349 @@
+// Pretui — Odometer: a number whose changed digits roll into place.
+import Component from '@glimmer/component';
+import { htmlSafe } from '@ember/template';
+import { cssDeclaration } from '../pretui-css';
+import { modifier } from 'ember-modifier';
+import { defined, formatNumber, toNumber } from '../internal/reading-format';
+import type { FormatOptionBag } from '../internal/reading-format';
+
+// ── Odometer — the Law 5 canonical mechanism ─────────────────────────────
+// "Each digit a 1ch window over a stacked 0–9 column, translateY sprung;
+//  offset > 5 → offset -= 10 so every digit takes the shortest path around
+//  the ring (9→0 rolls forward one, not backward nine)."
+//
+// That arithmetic is `rollPath` below, verbatim. Two implementation notes,
+// both deliberate:
+//
+//  1. The rendered column is the SLICE of the 0–9 ring the digit must travel
+//     (at most six cells), not the whole ring. A ring-plus-winding-offset
+//     implementation drifts without bound — a counter that only ever ticks up
+//     drives its units digit to +1 every update forever, and re-basing that
+//     offset needs a second frame (rAF/timeout), which the realm forbids. The
+//     slice keeps every position bounded, and the visible travel is identical:
+//     8→3 rolls forward through 9-0-1-2, 7→3 rolls backward through 6-5-4.
+//  2. The motion is ONE CSS animation whose from-state is the custom property
+//     `--pretui-odo-start`; the resting transform (`--pretui-odo-rest`) is the
+//     base style, so `animation: none` under prefers-reduced-motion lands on
+//     the end state, never a frozen midpoint (Law 5). Replay on change comes
+//     from a keyed {{#each}} — the digit's key encodes from>to, so a changed
+//     digit is a new element and its animation starts fresh. No timers, no
+//     JS animation loop, no transitionend bookkeeping.
+//
+// A11y: the whole digit track is aria-hidden with an sr-only mirror of the
+// real value beside it. `@announce` defaults to 'off' — a value that rolls on
+// every tick would otherwise spam a screen reader with every intermediate
+// number; turn it on only where the value settles at human pace.
+export interface RollFrame {
+  /** the ring slice, top to bottom, as digit characters */
+  cells: string[];
+  /** index the window starts on (the old digit) */
+  start: number;
+  /** index the window rests on (the new digit) */
+  rest: number;
+}
+
+/**
+ * The Law 5 ring walk: shortest path from one digit to another.
+ * `(to - from + 10) % 10`, then `offset > 5 → offset -= 10`.
+ */
+export function rollPath(from: number, to: number): RollFrame {
+  let offset = (((to - from) % 10) + 10) % 10;
+  if (offset > 5) {
+    offset -= 10;
+  }
+  let steps = Math.abs(offset);
+  let cells: string[] = [];
+  if (offset >= 0) {
+    // forward: the ring slice ascends from the old digit; the window rides up
+    for (let i = 0; i <= steps; i++) {
+      cells.push(String((from + i) % 10));
+    }
+    return { cells, start: 0, rest: steps };
+  }
+  // backward: the same ascending slice, entered from its bottom; window rides down
+  for (let i = steps; i >= 0; i--) {
+    cells.push(String((((from - i) % 10) + 10) % 10));
+  }
+  return { cells, start: steps, rest: 0 };
+}
+
+interface OdoSlot {
+  key: string;
+  digit: boolean;
+  char: string;
+  cells: string[];
+  style: ReturnType<typeof htmlSafe>;
+}
+
+const DIGIT_RE = /[0-9]/;
+
+export interface OdometerSignature {
+  Args: {
+    /** the value to display. A number is formatted through Intl; a string is used verbatim, so a pre-formatted value ('$12,480') rolls too. */
+    value?: number | string;
+    /** 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;
+    /** 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 added per digit so the carry cascades (default 0.03; 0 rolls every digit together) */
+    stagger?: number;
+    /** which end the stagger counts from: 'right' (default — the units digit leads, like a carry) or 'left' */
+    staggerFrom?: 'right' | 'left';
+    /** height of one digit cell, any CSS length (default 1em) */
+    cellHeight?: string;
+    /** live-region politeness for the sr-only value. 'off' (default) because a value that rolls on every tick would spam a screen reader; use 'polite' only where the value settles at human pace. */
+    announce?: 'off' | 'polite' | 'assertive';
+    /** rendered when the value is missing or not a finite number (default '—') */
+    placeholder?: string;
+  };
+  Blocks: {
+    /** static content before the digits — read aloud before the value */
+    before: [];
+    /** static content after the digits — read aloud after the value */
+    after: [];
+  };
+  Element: HTMLSpanElement;
+}
+
+// Records what the odometer just rendered, AFTER the DOM has it, so the
+// next render can diff against it. This bookkeeping used to live inside the
+// slots getter; a getter that writes is a side effect (ember/no-side-effects
+// flags it) and it is genuinely post-render state, not derivation. Args are
+// positional: the text that was just rendered, and the sink that stores it.
+const recordRendered = modifier(
+  (_el: HTMLElement, [text, sink]: [string, (rendered: string) => void]) => {
+    sink(text);
+  },
+);
+
+export class Odometer extends Component<OdometerSignature> {
+  // Untracked on purpose: this is "what the DOM currently shows". It is read
+  // during render (by the slots getter) and written after render (by the
+  // recordRendered modifier). Tracking it would make that write a
+  // backtracking violation; leaving it untracked is correct, because a
+  // change to it must never by itself schedule a re-render.
+  private previous: string | undefined = undefined;
+
+  // Called by the modifier once the browser is showing `text`.
+  private remember = (rendered: string) => {
+    this.previous = rendered;
+  };
+
+  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,
+      defined({
+        ...(a.options ?? {}),
+        style: a.style,
+        currency: a.currency,
+        minimumFractionDigits: a.minimumFractionDigits,
+        maximumFractionDigits: a.maximumFractionDigits,
+        useGrouping: a.useGrouping,
+      }),
+    );
+  }
+
+  get rootStyle(): ReturnType<typeof htmlSafe> {
+    let a = this.args;
+    // Durations are numbers we formatted ourselves; `@cellHeight` and
+    // `@ease` are caller strings and clear the kit-wide allowlist first
+    // (pretui-css.gts) — a rejected one falls back to the stylesheet.
+    let bits = [
+      `--pretui-odo-duration: ${(a.duration ?? 0.5).toFixed(3)}s`,
+      `--pretui-odo-stagger: ${(a.stagger ?? 0.03).toFixed(3)}s`,
+      cssDeclaration('--pretui-odo-cell', a.cellHeight ?? '1em') ??
+        '--pretui-odo-cell: 1em',
+    ];
+    let ease = cssDeclaration('--pretui-odo-ease', a.ease);
+    if (ease) {
+      bits.push(ease);
+    }
+    return htmlSafe(bits.join('; '));
+  }
+
+  /**
+   * The rendered slots, right-anchored against what the DOM currently shows,
+   * so a value that grows a digit keeps its columns aligned. Characters that
+   * are digits on both sides roll; everything else (separators, currency
+   * marks, compact suffixes) is static — a documented edge, since a value
+   * crossing '999' → '1,000' re-shapes the string and those positions snap.
+   */
+  get slots(): OdoSlot[] {
+    let next = this.text;
+    // Pure read: `previous` is whatever the DOM is currently showing. The
+    // recordRendered modifier advances it after this render commits.
+    let prev = this.previous ?? next;
+    let shift = next.length - prev.length;
+    let digitIndex = 0;
+    let total = 0;
+    for (let ch of next) {
+      if (DIGIT_RE.test(ch)) {
+        total++;
+      }
+    }
+    let out: OdoSlot[] = [];
+    for (let i = 0; i < next.length; i++) {
+      let ch = next[i] as string;
+      let before = prev[i - shift];
+      let isDigit = DIGIT_RE.test(ch);
+      let frame: RollFrame = { cells: [ch], start: 0, rest: 0 };
+      if (isDigit && before !== undefined && DIGIT_RE.test(before) && before !== ch) {
+        frame = rollPath(Number(before), Number(ch));
+      }
+      let order =
+        this.args.staggerFrom === 'left' ? digitIndex : total - 1 - digitIndex;
+      out.push({
+        key: `${i}:${before ?? ''}>${ch}`,
+        digit: isDigit,
+        char: ch,
+        cells: frame.cells,
+        style: htmlSafe(
+          `--pretui-odo-start: ${frame.start}; --pretui-odo-rest: ${frame.rest}; --pretui-odo-i: ${Math.max(order, 0)}`,
+        ),
+      });
+      if (isDigit) {
+        digitIndex++;
+      }
+    }
+    return out;
+  }
+
+  get liveAttr(): string | undefined {
+    let mode = this.args.announce ?? 'off';
+    return mode === 'off' ? undefined : mode;
+  }
+  get isEmpty(): string | undefined {
+    return toNumber(this.args.value) === undefined &&
+      !(typeof this.args.value === 'string' && this.args.value !== '')
+      ? 'true'
+      : undefined;
+  }
+  <template>
+    <span
+      class='pretui-odometer'
+      style={{this.rootStyle}}
+      data-empty={{this.isEmpty}}
+      data-test-pretui-odometer
+      {{recordRendered this.text this.remember}}
+      ...attributes
+    >
+      {{yield to='before'}}
+      <span class='pretui-odo-track' aria-hidden='true'>
+        {{#each this.slots key='key' as |slot|}}
+          {{#if slot.digit}}
+            <span class='pretui-odo-digit'>
+              <span class='pretui-odo-strut'>{{slot.char}}</span>
+              <span class='pretui-odo-ring' style={{slot.style}}>
+                {{#each slot.cells as |cell|}}
+                  <span class='pretui-odo-cell'>{{cell}}</span>
+                {{/each}}
+              </span>
+            </span>
+          {{else}}
+            <span class='pretui-odo-char'>{{slot.char}}</span>
+          {{/if}}
+        {{/each}}
+      </span>
+      <span class='pretui-odo-sr' aria-live={{this.liveAttr}}>{{this.text}}</span>
+      {{yield to='after'}}
+    </span>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-odometer {
+          display: inline-flex;
+          align-items: baseline;
+          font-variant-numeric: tabular-nums;
+          line-height: var(--pretui-odo-cell, 1em);
+        }
+        .pretui-odometer[data-empty='true'] {
+          color: var(--muted-foreground);
+        }
+        .pretui-odo-track {
+          display: inline-flex;
+          align-items: baseline;
+        }
+        .pretui-odo-char {
+          white-space: pre;
+        }
+        .pretui-odo-digit {
+          position: relative;
+          display: inline-block;
+          /* clip-path, not overflow: hidden — an overflow-clipped inline-block
+             synthesises its baseline from the bottom margin edge, which drops
+             the digits below the surrounding text. Clipping keeps the strut's
+             real baseline. The small vertical bleed is intentional: display
+             fonts can paint cap/bowl antialiasing just outside their fractional
+             line box (Space Grotesk's 5 is the visible case). A zero inset
+             sheared that ink off at every Odometer size. Horizontal clipping
+             remains exact, so adjacent digit columns cannot overlap. */
+          clip-path: inset(-0.08em 0);
+        }
+        .pretui-odo-strut {
+          visibility: hidden;
+        }
+        .pretui-odo-ring {
+          position: absolute;
+          inset-inline: 0;
+          top: 0;
+          transform: translateY(
+            calc(var(--pretui-odo-rest, 0) * var(--pretui-odo-cell, 1em) * -1)
+          );
+          animation: pretui-odo-roll var(--pretui-odo-duration, 0.5s)
+            var(--pretui-odo-ease, cubic-bezier(0.16, 1, 0.3, 1)) backwards;
+          animation-delay: calc(
+            var(--pretui-odo-i, 0) * var(--pretui-odo-stagger, 0.03s)
+          );
+        }
+        @keyframes pretui-odo-roll {
+          from {
+            transform: translateY(
+              calc(var(--pretui-odo-start, 0) * var(--pretui-odo-cell, 1em) * -1)
+            );
+          }
+        }
+        .pretui-odo-cell {
+          display: block;
+          height: var(--pretui-odo-cell, 1em);
+          line-height: var(--pretui-odo-cell, 1em);
+          text-align: center;
+        }
+        .pretui-odo-sr {
+          position: absolute;
+          width: 1px;
+          height: 1px;
+          overflow: hidden;
+          clip: rect(0 0 0 0);
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-odo-ring {
+            animation: none;
+          }
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,55 @@
+## What it is
+
+A number that rolls to its new value, digit by digit, with the carry cascading from the units end.
+
+Use it where a value changes and the change is worth noticing — a live total, a counter settling. **Stat** composes it for the headline case.
+
+## The contract
+
+```
+@value?      — a number is formatted through Intl; a STRING is used verbatim,
+               so a pre-formatted value ('$12,480') rolls too
+@locale?, @style?, @currency?, @minimumFractionDigits?, @maximumFractionDigits?,
+@useGrouping?, @options?  — the Intl surface, ignored when @value is a string
+@duration?   — roll duration in seconds. Default 0.5
+@ease?       — CSS timing function. Default a sprung cubic-bezier
+@stagger?    — seconds of delay added per digit so the carry cascades. Default 0.03;
+               0 rolls every digit together
+@staggerFrom? — which end the stagger counts from: 'right' (default — the units
+               digit leads, like a carry) | 'left'
+@cellHeight? — height of one digit cell, any CSS length. Default 1em
+@announce?   — live-region politeness for the sr-only value. Default 'off'
+@placeholder? — when the value is missing or not finite. Default '—'
+
+<:before>, <:after> — static content read aloud before and after the value
+```
+
+**A string `@value` rolls verbatim.** That is what lets a caller who has already formatted a number — through **FormatNumber**, or from a server — get the roll without the component re-parsing and re-formatting it.
+
+**`@staggerFrom='right'` is the default because that is how a carry works.** The units digit moves first and the tens follow it, which is what makes the roll read as counting rather than as a row of independent wheels.
+
+**`@announce` defaults to `'off'`, and that is a deliberate accessibility decision**, not an oversight — see below.
+
+## Prior art
+
+The odometer/rolling-number component that appears in every dashboard kit.
+
+Where Pretui is better: the string passthrough, the carry direction as a knob, and the live region defaulting to silent.
+
+Where it is thinner: no per-digit colour or emphasis, no roll on mount (the first render is the resting value), and no count-up-from-zero mode.
+
+## Accessibility
+
+- **The rolling digits are `aria-hidden` and the value is mirrored in a live region.** Announcing a wheel of digits mid-roll would be meaningless.
+- **That region is `'off'` by default because a value that rolls on every tick would spam a screen reader.** Use `'polite'` only where the value settles at human pace — a total that updates when someone acts, not a metric streaming from a socket.
+- **`<:before>` and `<:after>` are read in order around the value**, so "$" and "per month" land in the right places in the announcement rather than being visual decoration.
+- **`@placeholder` announces as a dash**, so a missing value is perceivable.
+- **Reduced motion should land on the resting value**, which costs nothing — the digits' resting position is the value.
+
+## Theming
+
+`--pretui-odo-cell` (digit cell height, from `@cellHeight`), `--pretui-odo-duration` and `--pretui-odo-ease` (the roll), `--pretui-odo-stagger` and `--pretui-odo-i` (the cascade and each digit's index), `--pretui-odo-start` and `--pretui-odo-rest` (the roll's endpoints).
+
+Everything is derived from args rather than from tokens, because a roll's timing belongs to the moment rather than to the theme — and the digits inherit their face and color from context, so an odometer inside a **Stat** looks like that headline rather than like a widget.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,258 @@
+// Pretui — Odometer usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { FreestyleUsage } from './freestyle-usage';
+import { Odometer } from './odometer';
+import { LOCALES, NUMBER_STYLES } from '../demo-reading-format';
+
+// ── Odometer ─────────────────────────────────────────────────────────────
+const STAGGER_FROM = ['right', 'left'];
+// Locales chosen to break naive formatters: RTL digits, a comma decimal
+// separator, a lakh/crore grouping, and an East Asian compact scale.
+
+// Law 5 names this as one of Pretui's two canonical motion mechanisms, and
+// the law is specific: each digit is a 1ch window over a stacked 0–9
+// column, and `offset > 5 → offset -= 10` so every digit takes the
+// SHORTEST path around the ring — 9→0 rolls forward one, not backward
+// nine. That shortest-path rule is the whole difference between "the
+// number changed" and a slot machine. The example has to be interactive
+// because a still Odometer is just a number.
+class OdometerUsage extends Component {
+  staggerFromOptions = STAGGER_FROM;
+  styleOptions = NUMBER_STYLES;
+  localeOptions = LOCALES;
+
+  @tracked value = 128480;
+  @tracked duration: number | null = 0.5;
+  @tracked stagger: number | null = 0.03;
+  @tracked staggerFrom = 'right';
+  @tracked style = 'currency';
+  @tracked currency = 'USD';
+  @tracked cellHeight = '1em';
+
+  setDuration = (v: number | null) => (this.duration = v);
+  setStagger = (v: number | null) => (this.stagger = v);
+  setStaggerFrom = (v: string) => (this.staggerFrom = v);
+  setStyle = (v: string) => (this.style = v);
+  setCurrency = (v: string) => (this.currency = v);
+  setCellHeight = (v: string) => (this.cellHeight = v);
+  setValue = (v: number | null) => (this.value = v ?? 0);
+
+  // The carry cases that matter: +1 rolls one digit, +9 forces a cascade,
+  // and the 9→0 wrap is where the shortest-path rule proves itself.
+  bumpOne = (_e: Event) => (this.value = this.value + 1);
+  bumpNine = (_e: Event) => (this.value = this.value + 9);
+  bumpLot = (_e: Event) => (this.value = this.value + 4821);
+  dropLot = (_e: Event) => (this.value = Math.max(0, this.value - 3607));
+  wrap = (_e: Event) => (this.value = this.value + (9 - (this.value % 10)));
+
+  get styleVal() {
+    return this.style as 'decimal' | 'currency' | 'percent' | 'unit';
+  }
+  get staggerFromVal() {
+    return this.staggerFrom as 'right' | 'left';
+  }
+  get durationVal() {
+    return this.duration ?? undefined;
+  }
+  get staggerVal() {
+    return this.stagger ?? undefined;
+  }
+  get usage() {
+    let bits = [`@value={{${this.value}}}`];
+    if (this.style !== 'decimal') bits.push(`@style='${this.style}'`);
+    if (this.style === 'currency') bits.push(`@currency='${this.currency}'`);
+    if (this.duration !== 0.5) bits.push(`@duration={{${this.duration}}}`);
+    if (this.stagger !== 0.03) bits.push(`@stagger={{${this.stagger}}}`);
+    if (this.staggerFrom !== 'right')
+      bits.push(`@staggerFrom='${this.staggerFrom}'`);
+    if (this.cellHeight !== '1em')
+      bits.push(`@cellHeight='${this.cellHeight}'`);
+    return `<Odometer ${bits.join(' ')} />`;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='Odometer'
+      @description="A numeral that rolls when it changes — Law 5's canonical mechanism for motion that encodes a state transition rather than decorating one. Each digit is a window over a stacked 0–9 ring, and every digit takes the shortest path around it, so 9→0 rolls forward one step instead of spinning back nine. Motion is a CSS transition on a custom property (no timers, no animation engine); reduced motion snaps straight to the end state. The animated digits are aria-hidden with an sr-only real value beside them, and @announce defaults to off because a figure that moves on every tick would flood a screen reader. Stat composes this."
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='odo-stack'>
+          <div class='odo-hero'>
+            <Odometer
+              @value={{this.value}}
+              @style={{this.styleVal}}
+              @currency={{this.currency}}
+              @duration={{this.durationVal}}
+              @stagger={{this.staggerVal}}
+              @staggerFrom={{this.staggerFromVal}}
+              @cellHeight={{this.cellHeight}}
+            >
+              <:after><span class='odo-suffix'>settled</span></:after>
+            </Odometer>
+          </div>
+          <p class='odo-note'>Season total for
+            <em>Alishan Cloud Farms</em>. Move it and watch the carry.</p>
+          <div class='odo-controls'>
+            <button type='button' class='odo-btn' {{on 'click' this.bumpOne}}>
+              +1
+            </button>
+            <button type='button' class='odo-btn' {{on 'click' this.bumpNine}}>
+              +9
+            </button>
+            <button type='button' class='odo-btn' {{on 'click' this.wrap}}>
+              roll to 9
+            </button>
+            <button type='button' class='odo-btn' {{on 'click' this.bumpLot}}>
+              +4,821
+            </button>
+            <button type='button' class='odo-btn' {{on 'click' this.dropLot}}>
+              −3,607
+            </button>
+          </div>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.Number
+          @name='value'
+          @value={{this.value}}
+          @description='The value. A number is formatted through Intl; a string is used verbatim, so a pre-formatted value like $12,480 rolls too.'
+          @onInput={{this.setValue}}
+        />
+        <Args.Number
+          @name='duration'
+          @defaultValue={{0.5}}
+          @value={{this.duration}}
+          @min={{0}}
+          @max={{3}}
+          @step={{0.05}}
+          @description='Roll duration in seconds.'
+          @onInput={{this.setDuration}}
+        />
+        <Args.Number
+          @name='stagger'
+          @defaultValue={{0.03}}
+          @value={{this.stagger}}
+          @min={{0}}
+          @max={{0.3}}
+          @step={{0.01}}
+          @description='Seconds added per digit so the carry cascades. 0 rolls every digit together — which reads as a slot machine, not a carry.'
+          @onInput={{this.setStagger}}
+        />
+        <Args.String
+          @name='staggerFrom'
+          @defaultValue='right'
+          @value={{this.staggerFrom}}
+          @options={{this.staggerFromOptions}}
+          @description='Which end the stagger counts from. right means the units digit leads, which is the direction a real carry travels.'
+          @onInput={{this.setStaggerFrom}}
+        />
+        <Args.String
+          @name='cellHeight'
+          @defaultValue='1em'
+          @value={{this.cellHeight}}
+          @description='Height of one digit cell, any CSS length. Sets the window the ring rolls behind.'
+          @onInput={{this.setCellHeight}}
+        />
+        <Args.String
+          @name='style'
+          @defaultValue='decimal'
+          @value={{this.style}}
+          @options={{this.styleOptions}}
+          @description='Intl style for numeric values — decimal, currency, percent, or unit.'
+          @onInput={{this.setStyle}}
+        />
+        <Args.String
+          @name='currency'
+          @value={{this.currency}}
+          @description='ISO 4217 code for style=currency; without it the style degrades to decimal.'
+          @onInput={{this.setCurrency}}
+        />
+        <Args.String
+          @name='ease'
+          @description='CSS timing function for the roll. Defaults to a sprung cubic-bezier so the digit settles rather than stopping dead.'
+        />
+        <Args.String
+          @name='announce'
+          @defaultValue='off'
+          @description='Live-region politeness for the sr-only value. off by default — a value that rolls on every tick would spam a screen reader. Use polite only where it settles at human pace.'
+        />
+        <Args.String
+          @name='locale, minimum/maximumFractionDigits, useGrouping, options'
+          @description='The Intl surface, matching FormatNumber.'
+        />
+        <Args.Yield
+          @name='before / after'
+          @description='Static content on either side of the digits, read aloud in order — a currency word, a unit, a label.'
+        />
+        <Args.String
+          @name='placeholder'
+          @defaultValue='—'
+          @description='Rendered when the value is missing or non-finite.'
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .odo-stack {
+        display: flex;
+        flex-direction: column;
+        gap: var(--space-4, 14px);
+      }
+      .odo-hero {
+        font-size: 33px;
+        font-weight: 700;
+        letter-spacing: -0.02em;
+        color: var(--foreground);
+      }
+      .odo-suffix {
+        margin-left: var(--space-2, 6px);
+        font-size: var(--text-ui-md, 12.5px);
+        font-weight: 500;
+        color: var(--muted-foreground);
+      }
+      .odo-note {
+        margin: 0;
+        font-size: var(--text-ui-md, 12.5px);
+        color: var(--muted-foreground);
+      }
+      .odo-note em {
+        font-style: normal;
+        font-weight: 600;
+        color: var(--foreground);
+      }
+      .odo-controls {
+        display: flex;
+        flex-wrap: wrap;
+        gap: var(--space-2, 6px);
+      }
+      .odo-btn {
+        padding: 5px 10px;
+        border: 0;
+        border-radius: var(--radius-control, 7px);
+        background: var(--card);
+        box-shadow: var(
+          --pretui-shadow-control,
+          0 0 0 1px var(--border)
+        );
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        font-weight: 500;
+        color: var(--foreground);
+        cursor: pointer;
+      }
+      .odo-btn:hover {
+        background: var(--muted);
+      }
+      .odo-btn:focus-visible {
+        outline: 2px solid var(--ring);
+        outline-offset: 2px;
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_ODOMETER: Record<string, unknown> = {
+  Odometer: OdometerUsage,
+};