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

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

@@ -0,0 +1,69 @@
+## What it is
+
+A **persistent notification item**: a title, a message, a tone, one inline action and a dismiss button. It stays until someone dismisses it. Use it for the entries in a notification centre, an inbox panel or an activity feed, or for a banner-sized notice that must wait to be acknowledged.
+
+It wears the same face as a **Toaster** item: the tone stripe, the title and message, the inline action and the dismiss button. A toast that ages out and the notification it leaves behind therefore read as the same object. How it differs from its neighbours:
+
+- **Toaster** stacks transient items and dismisses them on a clock. Notification has no clock.
+- **Toast** is the slimmer card with no tone and no dismiss button.
+- **Alert** is an inline message about the content it sits next to, with no dismiss button.
+- **Snackbar** is the alias Material agents type for a toast.
+
+## The contract
+
+```
+@title, @message? (alias @description)
+@tone? ('neutral' | 'info' | 'success' | 'warning' | 'danger', plus the kit's tone spellings; default 'neutral')
+@busy?, @live?
+@actionLabel?, @onAction?
+@onDismiss?, @dismissLabel? (default 'Dismiss')
+<:icon>     — a leading icon, tinted with the tone
+<:default>  — the message, when it needs markup
+<:action>   — replaces the inline action
+Element: HTMLDivElement
+```
+
+**The tone paints one stripe.** As in Toaster, the 3px leading stripe is the only place a tone shows, plus the inline action's ink and the icon's tint. A neutral notification is genuinely neutral, and a list of them does not turn into a wall of colour. Unknown tones fall back to neutral.
+
+**Announcing is opt-in.** A notification in a list is content, not news, and a centre that announces every row it renders is unusable. `@live={{true}}` makes it a live region when it appears: `role="alert"` with `aria-live="assertive"` for warning and danger, and `role="status"` with `aria-live="polite"` otherwise. It uses the same politeness rule as Toaster, from the same function.
+
+**Dismiss exists when it can do something.** The dismiss button renders only when `@onDismiss` is passed. The caller owns the list, so the caller removes the item.
+
+`@busy` swaps the icon for a spinner while the reported work is still running, such as an upload or an export, and sets `aria-busy` on the item. `@actionLabel` with `@onAction` renders one text button. The `<:action>` block takes a link or several controls instead.
+
+## Prior art
+
+**Mantine Notification** is the visual model: `title`, `children`, `color`, `icon`, `loading`, `withCloseButton` and `onClose`. **Ant `notification.open`** is an imperative host with `message`, `description`, `btn`, `duration` and `placement`. **MUI SnackbarContent** is the body of a Snackbar: `message` and `action`. **Sonner** toasts in shadcn take `description`, `action` and `cancel`.
+
+Where Pretui is better: **it is not announced by default.** Mantine's Notification is `role="alert"` unconditionally, so a panel of ten renders ten alerts. **Politeness follows severity** when it is announced, which none of the above do for a standalone item. **One face for toast and notification** means the transient and persistent forms cannot drift apart. **The dismiss button is always named**, with `@dismissLabel` for a more specific name.
+
+Where it is thinner: **no imperative API.** There is no `notification.open()`. Render it yourself, or use **Toaster**'s `ToastStore` for the transient case. There is **no timestamp or avatar slot**; put them in `<:default>`. **No read / unread state**: a notification centre's unread styling is the caller's.
+
+## Accessibility
+
+No APG pattern. A notification is text, one or two buttons and an optional live region.
+
+- **It is not a live region by default.** The tests assert that a danger notification without `@live` carries no `role` and no `aria-live`.
+- **With `@live`, politeness follows the tone.** Success is `role="status"` with `aria-live="polite"`, and danger is `role="alert"` with `aria-live="assertive"`. `aria-atomic="true"` makes the whole item read as one message. The tests assert both pairs. A live region only announces changes after it is in the page, so mount the item into an existing container rather than expecting its first render to be heard everywhere. **Toaster** handles that for transient items.
+- **`@busy`** sets `aria-busy="true"`. The spinner is hidden and adds no second status, which the tests assert.
+- **The dismiss button is a real `<button>` with an accessible name**, "Dismiss" by default. The tests assert the name and that it exists only with `@onDismiss`. On a coarse pointer its hit area grows to 44px without growing the glyph.
+- **The inline action is a `type="button"`**, so a notification inside a form never submits it.
+- **Tone is not the message.** The stripe backs up the title. "Payment failed" must say so in words.
+
+## Theming
+
+`--pretui-notification-tone` (set from the tone: `--pretui-info`, `--success`, `--warning`, `--destructive` or `--muted-foreground`), `--pretui-notification-width` (the maximum width, default 26rem), `--popover`, `--popover-foreground`, `--muted-foreground`, `--foreground`, `--primary` (a neutral item's action), `--radius-surface`, `--radius-control`, `--pretui-shadow-raised`, `--ring`, `--hover`, `--font-sans`, `--text-ui-md`, `--text-ui-sm`, `--space-3` and `--space-4`.
+
+These are the tokens a **Toaster** item reads, so a theme that retunes toasts retunes notifications the same way. The 3px stripe and the 1.25rem dismiss button 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 `<Notification title color onClose>`      | `@title` + `@tone` + `@onDismiss`                        |
+| Mantine `loading`                                 | `@busy`                                                  |
+| Ant `notification.open({ message, description })` | render `@title` + `@message`, or **Toaster**             |
+| MUI `<SnackbarContent message action>`            | `@title` + `<:action>`                                   |
+| Sonner `toast('…', { description, action })`      | **Toaster**'s `ToastStore`; this for the persistent copy |

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

@@ -0,0 +1,125 @@
+// Pretui — Notification usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { FreestyleUsage } from './freestyle-usage';
+import { Notification } from './notification';
+import type { ToastTone } from './toaster';
+
+const TONE_OPTIONS = ['neutral', 'info', 'success', 'warning', 'danger'];
+
+export class NotificationUsage extends Component {
+  toneOptions = TONE_OPTIONS;
+  @tracked title = 'Lot 7 is ready to ship';
+  @tracked message = 'Roasted 12 kg on Tuesday. Labels are printed.';
+  @tracked tone = 'success';
+  @tracked busy = false;
+  @tracked live = false;
+  @tracked actionLabel = 'View lot';
+  @tracked dismissed = false;
+  @tracked actions = 0;
+  setTitle = (v: string) => (this.title = v);
+  setMessage = (v: string) => (this.message = v);
+  setTone = (v: string) => (this.tone = v);
+  setBusy = (v: boolean) => (this.busy = v);
+  setLive = (v: boolean) => (this.live = v);
+  setActionLabel = (v: string) => (this.actionLabel = v);
+  onAction = () => this.actions++;
+  onDismiss = () => (this.dismissed = true);
+  restore = () => (this.dismissed = false);
+  get toneArg() {
+    return this.tone as ToastTone;
+  }
+  get usage() {
+    let bits = [`@title='${this.title}'`];
+    if (this.message) bits.push(`@message='${this.message}'`);
+    if (this.tone !== 'neutral') bits.push(`@tone='${this.tone}'`);
+    if (this.busy) bits.push('@busy={{true}}');
+    if (this.live) bits.push('@live={{true}}');
+    if (this.actionLabel) bits.push(`@actionLabel='${this.actionLabel}' @onAction={{this.view}}`);
+    bits.push('@onDismiss={{this.dismiss}}');
+    return `<Notification\n  ${bits.join('\n  ')}\n/>`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Notification'
+      @description='A persistent notification item: title, message, tone stripe, one inline action and a dismiss button. It wears the Toaster face but has no clock, so it stays until dismissed. Toast is the slimmer transient card; Toaster stacks items and ages them out.'
+      @source={{this.usage}}
+    >
+      <:example>
+        {{#if this.dismissed}}
+          <button type='button' class='nt-demo-restore' {{on 'click' this.restore}}>Show it again</button>
+        {{else}}
+          <Notification
+            @title={{this.title}}
+            @message={{this.message}}
+            @tone={{this.toneArg}}
+            @busy={{this.busy}}
+            @live={{this.live}}
+            @actionLabel={{this.actionLabel}}
+            @onAction={{this.onAction}}
+            @onDismiss={{this.onDismiss}}
+          />
+        {{/if}}
+        {{#if this.actions}}<p class='nt-demo-count'>Action pressed {{this.actions}} times</p>{{/if}}
+      </:example>
+      <:api as |Args|>
+        <Args.String @name='title' @required={{true}} @value={{this.title}} @onInput={{this.setTitle}} />
+        <Args.String
+          @name='message'
+          @value={{this.message}}
+          @description='The second line. The default block takes markup instead; @description is an alias.'
+          @onInput={{this.setMessage}}
+        />
+        <Args.String
+          @name='tone'
+          @value={{this.tone}}
+          @options={{this.toneOptions}}
+          @defaultValue='neutral'
+          @description='Paints the stripe. Kit tone spellings resolve.'
+          @onInput={{this.setTone}}
+        />
+        <Args.Bool
+          @name='busy'
+          @defaultValue={{false}}
+          @value={{this.busy}}
+          @description='A spinner in place of the icon while the reported work is still running.'
+          @onInput={{this.setBusy}}
+        />
+        <Args.Bool
+          @name='live'
+          @defaultValue={{false}}
+          @value={{this.live}}
+          @description='Announce it on arrival: alert for warning and danger, status otherwise. Leave off inside a Toaster or a list that already announces.'
+          @onInput={{this.setLive}}
+        />
+        <Args.String
+          @name='actionLabel'
+          @value={{this.actionLabel}}
+          @description='A single inline action, fired through @onAction. The action block replaces it.'
+          @onInput={{this.setActionLabel}}
+        />
+        <Args.Action @name='onAction' @description='Fired by the inline action.' />
+        <Args.Action @name='onDismiss' @description='Shows the dismiss button and fires when it is pressed.' />
+        <Args.String @name='dismissLabel' @defaultValue='Dismiss' @description="The dismiss button's accessible name." />
+        <Args.Yield @name='icon' @description='A leading icon, tinted with the tone.' />
+        <Args.Yield @name='default' @description='The message, when it needs markup.' />
+        <Args.Yield @name='action' @description='Replaces the inline action.' />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .nt-demo-restore {
+        font: inherit;
+      }
+      .nt-demo-count {
+        margin: var(--space-2, 0.375rem) 0 0;
+        font-size: var(--text-ui-sm, 0.72rem);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_NOTIFICATION: Record<string, unknown> = {
+  Notification: NotificationUsage,
+};

package/bundled-realms/pretui/components/number-input.gts

@@ -0,0 +1,191 @@
+// Pretui — NumberInput: a number field that clamps and rounds on commit.
+import Component from '@glimmer/component';
+import { BoxelInput } from '@cardstack/boxel-ui/components';
+import { emit, firstDefined } from '../pretui-primitives';
+import type { ControlNotifyArgs } from '../pretui-primitives';
+import { TYPED_FONT } from '../internal/extras';
+
+// BoxelInput @type='number' with the numeric knobs surfaced: @min/@max/
+// @step ride the native control (spinners + keyboard), and values clamp to
+// the bounds and round to @precision decimals on commit (change event —
+// blur / Enter / spinners) so clamping never fights mid-keystroke.
+// @onInput speaks number | null (null = empty/unparsable), Stepper-style.
+
+export interface NumberInputSignature {
+  Args: ControlNotifyArgs<number | null> & {
+    value?: number | null;
+    placeholder?: string;
+    min?: number;
+    max?: number;
+    step?: number;
+    /** decimal places applied on commit (0 = integers) */
+    precision?: number;
+    disabled?: boolean;
+    required?: boolean;
+    controlId?: string;
+    onInput?: (value: number | null) => void;
+    /**
+     * Force the committed value back inside `@min`/`@max` (default true —
+     * the behaviour this component has always had). Set false to let an
+     * out-of-range value stand and be REPORTED instead: a silent clamp tells
+     * the reader nothing about why their number changed, which is the whole
+     * of the complaint against clamp-only number fields.
+     */
+    clamp?: boolean;
+    /** force the invalid dress regardless of range */
+    invalid?: boolean;
+    /** aliases — React Aria / Base UI boolean spellings */
+    isDisabled?: boolean;
+    isRequired?: boolean;
+    isInvalid?: boolean;
+    /** message under the control; wins over the derived range message */
+    errorMessage?: string;
+    /** wording for the derived out-of-range message — receives (min, max),
+     * either of which may be undefined */
+    rangeMessage?: (min?: number, max?: number) => string;
+  };
+  Element: HTMLDivElement;
+}
+
+const defaultRangeMessage = (min?: number, max?: number) => {
+  if (min !== undefined && max !== undefined) {
+    return `Enter a number between ${min} and ${max}.`;
+  }
+  if (min !== undefined) {
+    return `Enter ${min} or more.`;
+  }
+  if (max !== undefined) {
+    return `Enter ${max} or less.`;
+  }
+  return 'Out of range.';
+};
+
+export class NumberInput extends Component<NumberInputSignature> {
+  get boxelValue() {
+    return this.args.value ?? null;
+  }
+  get disabled() {
+    return firstDefined(this.args.disabled, this.args.isDisabled);
+  }
+  get required() {
+    return firstDefined(this.args.required, this.args.isRequired);
+  }
+  get invalid() {
+    return firstDefined(this.args.invalid, this.args.isInvalid) ?? false;
+  }
+  private notify(v: number | null) {
+    emit(
+      [this.args.onInput, this.args.onChange, this.args.onValueChange],
+      v,
+    );
+  }
+  get clamps() {
+    return this.args.clamp ?? true;
+  }
+  /** A named tri-state, not a boolean: 'none' (nothing to say) is different
+   * from 'valid' (checked and fine), and only 'invalid' dresses the field. */
+  get rangeState(): 'valid' | 'invalid' | 'none' {
+    let v = this.args.value;
+    if (v === null || v === undefined || Number.isNaN(v)) return 'none';
+    if (this.args.min === undefined && this.args.max === undefined) {
+      return 'none';
+    }
+    let low = this.args.min !== undefined && v < this.args.min;
+    let high = this.args.max !== undefined && v > this.args.max;
+    return low || high ? 'invalid' : 'valid';
+  }
+  get state() {
+    return this.invalid || this.rangeState === 'invalid' ? 'invalid' : 'none';
+  }
+  get errorMessage() {
+    if (this.args.errorMessage) return this.args.errorMessage;
+    if (this.rangeState !== 'invalid') return undefined;
+    let format = this.args.rangeMessage ?? defaultRangeMessage;
+    return format(this.args.min, this.args.max);
+  }
+  private roundOnly(v: number) {
+    if (this.args.precision === undefined) return v;
+    let m = Math.pow(10, this.args.precision);
+    return Math.round(v * m) / m;
+  }
+  private clampRound(v: number) {
+    if (this.args.min !== undefined) {
+      v = Math.max(this.args.min, v);
+    }
+    if (this.args.max !== undefined) {
+      v = Math.min(this.args.max, v);
+    }
+    if (this.args.precision !== undefined) {
+      let m = Math.pow(10, this.args.precision);
+      v = Math.round(v * m) / m;
+    }
+    return v;
+  }
+  handleInput = (val: string) => {
+    let v = val === '' ? NaN : Number(val);
+    this.notify(Number.isNaN(v) ? null : v);
+  };
+  handleChange = (ev: Event) => {
+    let input = ev.target as HTMLInputElement;
+    let v = input.value === '' ? NaN : Number(input.value);
+    if (Number.isNaN(v)) {
+      return; // empty stays empty; the browser blocks unparsable text
+    }
+    // Rounding still applies when clamping is off — precision is a display
+    // contract, the bounds are a validity one.
+    let next = this.clamps ? this.clampRound(v) : this.roundOnly(v);
+    let display =
+      this.args.precision !== undefined
+        ? next.toFixed(this.args.precision)
+        : String(next);
+    if (input.value !== display) {
+      input.value = display;
+    }
+    this.notify(next);
+  };
+  <template>
+    <div
+      class='pretui-boxelwrap'
+      data-range-state={{this.rangeState}}
+      data-test-pretui-number-input
+      ...attributes
+    >
+      <BoxelInput
+        @type='number'
+        @value={{this.boxelValue}}
+        @placeholder={{@placeholder}}
+        @min={{@min}}
+        @max={{@max}}
+        @step={{@step}}
+        @disabled={{this.disabled}}
+        @required={{this.required}}
+        @state={{this.state}}
+        @errorMessage={{this.errorMessage}}
+        @onInput={{this.handleInput}}
+        @onChange={{this.handleChange}}
+        id={{@controlId}}
+        style={{TYPED_FONT}}
+      />
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        /* Same re-skin channel as EmailInput — see that component's note. */
+        .pretui-boxelwrap {
+          width: 100%;
+          font-size: var(--text-ui-md, 12.5px);
+          letter-spacing: var(--track-ui, 0.01em);
+          font-variant-numeric: tabular-nums;
+          --background: var(--field, var(--boxel-light));
+          --border: var(--input);
+          --ring: var(--primary);
+          --muted-foreground: var(--ink-3, var(--boxel-400));
+          --boxel-form-control-height: var(--control-h, 28px);
+          --boxel-input-height: var(--control-h, 28px);
+          --boxel-form-control-border-radius: var(--radius);
+          --boxel-sp-xs: 5px;
+          --boxel-sp-sm: 9px;
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,54 @@
+## What it is
+
+A numeric text field with min/max clamping and decimal-precision rounding. Use it when the user types a number and the exact value matters — a price, a quantity, a threshold. If the value is nudged rather than typed, **Stepper** puts `−`/`+` buttons around it. If it is approximate within a bounded range, **Slider**. If you are displaying a number rather than collecting one, **Stat**, **Token** or **FormatNumber**.
+
+## The contract
+
+```
+@value?, @min?, @max?, @precision?, @placeholder?
+@disabled?, @required?, @controlId?
+@onInput?(value: number | null)
+```
+
+**`@onInput` yields `number | null`, not a string.** That is the one place this component's signature diverges from the rest of the typed-input family, and it is correct: a numeric field that hands you `'12'` forces every call site to parse, and a field that hands you `NaN` for an empty box forces every call site to guard. `null` is the honest representation of "no number here".
+
+**`clampRound` applies bounds first, then precision.** `Math.max(min, …)`, `Math.min(max, …)`, then round to `10^precision`. Order matters: rounding after clamping means a value at the boundary stays exactly at the boundary rather than being rounded past it.
+
+`@value` is passed through as `null` when undefined, matching the underlying control.
+
+## Prior art
+
+A **thin runtime wrap of boxel-ui's number input**, per the standing reuse directive — the parsing and commit machinery is boxel-ui's, and the wrapper re-dresses it through the semantic-token + `--boxel-*` channel with no CSS reaching boxel markup.
+
+**Web Awesome `wa-number-input`** is the fullest reference: `step` (`number | 'any'`), `without-steppers`, `inputMode` (`numeric | decimal`), localized `increment`/`decrement` `aria-label`s, steppers auto-disabled at bounds, and the decrement button rendered _before_ the input in the DOM. **React Spectrum `NumberField`** takes `formatOptions` (an `Intl.NumberFormat` bag), `minValue`/`maxValue`/`step`, and picks `inputMode` from the format options and locale.
+
+Where Pretui is thinner, and these are the honest gaps:
+
+- **No `Intl.NumberFormat`.** Spectrum's `formatOptions` is what lets a number field display `$1,284.00` while holding `1284`. This component has `@precision` and nothing else — no currency, no percent, no grouping, no locale. **FormatNumber** exists for display; there is no formatted _input_.
+- **No `@step`.** The native arrow-key stepping uses the browser's default of 1, so a price field steps by whole units. **Stepper** has `@step`; this does not.
+- **No `inputMode` control**, so the mobile keyboard is whatever `type="number"` gives you.
+
+## Accessibility
+
+Governing pattern: APG **Spinbutton** — `role="spinbutton"` with `aria-valuenow`/`valuemin`/`valuemax`/`valuetext`, Up/Down by step, Home/End to the bounds, Page Up/Page Down by a larger step, and `aria-invalid` when out of range.
+
+An `<input type="number">` supplies the role and the `aria-value*` properties implicitly, plus Up/Down stepping. What it does not supply, and what this component does not add:
+
+- **Home/End and Page Up/Page Down are missing.** Half the pattern's key list.
+- **No `aria-valuetext`**, so a value with units announces as a bare number.
+- **A significant platform caveat**: React Aria's `useNumberField` deliberately **strips** the spinbutton role (`role: null`, all four `aria-value*` nulled) because **VoiceOver cannot focus a spin button**, substituting `aria-roledescription` and wrapping the field in `role="group"`. If VoiceOver is a target, `input[type=number]` inherits that problem and this component does nothing about it.
+- **`type="number"` has known input problems** independent of ARIA: scroll-wheel changes the value when the field has focus, non-numeric keystrokes are silently swallowed in some browsers, and the value is empty-string rather than partial for intermediate states. Spectrum uses `type="text"` with `inputMode` for exactly these reasons.
+- **No accessible name of its own.** Outside **Field**/**FormField** and without an explicit `aria-label`, the field is unnamed.
+- **No `autocomplete`** arg — relevant for numeric personal data (postal codes, card numbers) under **WCAG 1.3.5**. Family-wide hole.
+- **Clamping is silent.** Typing 500 into a field with `@max={{100}}` commits 100 with no announcement and no explanation. **WCAG 3.3.1** wants the error identified in text and **3.3.3** wants a suggestion; silently altering the user's input satisfies neither, and is arguably worse than rejecting it. Surface the bounds via **FormField**'s `@description` at minimum.
+- **`@disabled` uses the native attribute**, removing the field from the tab order.
+
+## Theming
+
+Consumed: `--field`, `--input`, `--primary` (focus ring via `--ring`), `--ink-3` (placeholder), `--control-h`, `--radius`, `--text-ui-md`, `--text-ui-sm`, `--text-ui-xs`, `--track-ui`.
+
+Forwarded into boxel-ui through the `--boxel-*` channel, matching **Input**'s metrics so a numeric field and a text field align in the same form.
+
+Native spinner buttons are a UA-rendered control that CSS custom properties cannot reach — a theme cannot restyle them, and they will look like the browser's rather than like the kit's. **Stepper** exists partly for that reason. If a theme wants consistent numeric chrome, prefer Stepper. The invalid dress arrives from an enclosing **Field** through the token channel, as with the rest of the family.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,132 @@
+// Pretui — NumberInput usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { NumberInput } from './number-input';
+
+function isNullVal(v: number | null): boolean {
+  return v === null;
+}
+
+// ── NumberInput — typed-input split, fresh page ──────────────────────────
+// Type-specific knobs: min / max / step / precision. Values clamp + round
+// on commit (blur / Enter / spinners); the readout shows what @onInput
+// received (number | null).
+class NumberInputUsage extends Component {
+  @tracked emitted: number | null = null;
+  @tracked min = 0;
+  @tracked max = 100;
+  @tracked step = 1;
+  @tracked precision = 0;
+  @tracked placeholder = '0';
+  @tracked disabled = false;
+  @tracked required = false;
+  setEmitted = (v: number | null) => (this.emitted = v);
+  setMin = (v: number | null) => (this.min = v ?? 0);
+  setMax = (v: number | null) => (this.max = v ?? 100);
+  setStep = (v: number | null) => (this.step = v ?? 1);
+  setPrecision = (v: number | null) => (this.precision = v ?? 0);
+  setPlaceholder = (v: string) => (this.placeholder = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  setRequired = (v: boolean) => (this.required = v);
+  get usage() {
+    let bits = [
+      `@min={{${this.min}}}`,
+      `@max={{${this.max}}}`,
+      `@step={{${this.step}}}`,
+    ];
+    if (this.precision) bits.push(`@precision={{${this.precision}}}`);
+    bits.push('@onInput={{this.setValue}}');
+    return `<NumberInput ${bits.join(' ')} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='NumberInput'
+      @description='Numeric entry riding boxel-ui BoxelInput (@type=number): native spinners and keyboard steps via @min/@max/@step, plus clamp-and-round to @precision decimals on commit — clamping never fights mid-keystroke.'
+      @source={{this.usage}}
+    >
+      <:example>
+        {{! uncontrolled on purpose: feeding every parsed keystroke back
+            into a controlled number @value would fight partial entries
+            like '3.' — the readout below proves the @onInput loop instead }}
+        <NumberInput
+          @min={{this.min}}
+          @max={{this.max}}
+          @step={{this.step}}
+          @precision={{this.precision}}
+          @placeholder={{this.placeholder}}
+          @disabled={{this.disabled}}
+          @required={{this.required}}
+          @onInput={{this.setEmitted}}
+        />
+        <p class='pretui-demo-readout' data-test-number-readout>
+          onInput received:
+          {{if (isNullVal this.emitted) 'null' this.emitted}}
+        </p>
+      </:example>
+      <:api as |Args|>
+        <Args.Number
+          @name='min'
+          @value={{this.min}}
+          @description='Lower bound — commits clamp here; native spinners stop here.'
+          @onInput={{this.setMin}}
+        />
+        <Args.Number
+          @name='max'
+          @value={{this.max}}
+          @description='Upper bound.'
+          @onInput={{this.setMax}}
+        />
+        <Args.Number
+          @name='step'
+          @defaultValue={{1}}
+          @value={{this.step}}
+          @description='Spinner / arrow-key increment.'
+          @onInput={{this.setStep}}
+        />
+        <Args.Number
+          @name='precision'
+          @defaultValue={{0}}
+          @value={{this.precision}}
+          @description='Decimal places applied on commit (0 = integers). Try 2 and type 3.14159.'
+          @onInput={{this.setPrecision}}
+        />
+        <Args.String
+          @name='placeholder'
+          @value={{this.placeholder}}
+          @onInput={{this.setPlaceholder}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @value={{this.disabled}}
+          @onInput={{this.setDisabled}}
+        />
+        <Args.Bool
+          @name='required'
+          @value={{this.required}}
+          @onInput={{this.setRequired}}
+        />
+        <Args.String
+          @name='controlId'
+          @description="The input's id for label wiring — supplied by a wrapping Field's yielded controlId."
+        />
+        <Args.Action
+          @name='onInput'
+          @description='Receives number | null — null while the field is empty.'
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-demo-readout {
+        margin: 8px 0 0;
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_NUMBER_INPUT: Record<string, unknown> = {
+  NumberInput: NumberInputUsage,
+};