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

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

@@ -0,0 +1,54 @@
+## What it is
+
+A named-period parser: type `Q3`, `Jan 2026`, `W12` or `Fall 2025` and get a typed, sortable range.
+
+It is the control for a field whose value is a *period* rather than a date — a reporting quarter, a fiscal year, a week number — where a calendar is the wrong shape entirely.
+
+## The contract
+
+```
+@value?, @defaultValue? — the period token ('2026-Q3') or any recognised text
+@reference?       — the instant a partial period like 'Q3' resolves against, YYYY-MM-DD
+@locale?          — BCP-47 tag for month names and the resolved range
+@fiscalYearStart? — the calendar month a fiscal year starts in, 1–12. Default 1
+@fiscalYearLabel? — whether a fiscal year is named for the year it starts or ends in
+@hemisphere?      — which hemisphere the season names describe
+@label?, @hint?, @controlId?
+@disabled?
+@noStep?          — hide the previous / next stepper
+@quiet?           — hide the accepted-forms line
+@onChange?        — fires with the resolved period, or undefined and the reason
+```
+
+**Without `@reference`, a partial period is refused with a message rather than resolved against the wall clock.** `Q3` alone is not a period — it is a quarter of some year — and guessing which year from the system clock produces a value that changes meaning on New Year's Day. Realm code may not read the clock, and this is the honest consequence.
+
+**Fiscal years are configurable in both directions.** `@fiscalYearStart` says which month begins the year; `@fiscalYearLabel` says whether FY2026 is the one that *starts* in 2026 or the one that *ends* there. Both conventions are in use and neither is a default anyone can assume.
+
+**`@hemisphere` decides what the season names mean.** "Fall 2025" is a different range in Sydney than in New York.
+
+**`@onChange` reports the reason when there is no period**, so a form decides when to show it.
+
+## Prior art
+
+The kit's own `fields-configuration` month, quarter, week and year specs — four separate field types this replaces with one.
+
+Where Pretui is better: one control instead of four, a real refusal rather than a clock-based guess, and fiscal and hemisphere conventions as configuration rather than as assumptions.
+
+Where it is thinner: no range of periods ("Q1–Q3"), no custom period definitions beyond the built-in vocabulary, and no calendar affordance for a reader who would rather pick than type.
+
+## Accessibility
+
+- **The accepted-forms line is the component's most important affordance.** A permissive parser with no visible vocabulary is a guessing game; the line says what it understands, and `@quiet` should only remove it when the form says the same thing elsewhere.
+- **The resolved range is announced through a polite `role='status'` region**, so a reader can confirm that `Q3` became the right three months.
+- **The box carries `aria-invalid` and an `aria-describedby`** pointing at the explanation, so a refusal is both announced and located.
+- **The stepper buttons are individually named** — previous and next period — and use `aria-disabled` so they stay announced at the bounds rather than disappearing.
+- **`@hint` is ghost text behind the box, not a `placeholder` attribute**, so the field keeps its accessible name once typing starts.
+- **A refused partial period explains why**, which is the difference between "that's not valid" and "say which year".
+
+## Theming
+
+`--pretui-destructive-ink` for the invalid state, over the kit's shared control tokens; the ghost text and the stepper take the standard muted and control treatments rather than component-specific values.
+
+The deliberate absence of a token surface here is the point: a period field should be indistinguishable from a text field on the same form until it is used, so nothing about it is separately themeable.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,299 @@
+// Pretui — PeriodInput usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { PERIOD_FORMS, PeriodInput, parsePeriod, periodRangeText } from './period-input';
+import type { Period, PeriodResult } from './period-input';
+
+const LOCALES = ['en-US', 'en-GB', 'de-DE', 'fr-FR', 'ja-JP'];
+const FISCAL_STARTS = ['1', '4', '7', '10'];
+const FISCAL_LABELS = ['start', 'end'];
+const HEMISPHERES = ['north', 'south'];
+
+interface SpecimenRow {
+  typed: string;
+  kind: string;
+  id: string;
+  range: string;
+  days: string;
+}
+
+class PeriodInputUsage extends Component {
+  @tracked reference = '2026-08-13';
+  @tracked locale = 'en-US';
+  @tracked fiscalYearStart = '1';
+  @tracked fiscalYearLabel: 'start' | 'end' = 'start';
+  @tracked hemisphere: 'north' | 'south' = 'north';
+  @tracked seed = 'Q3 2026';
+  @tracked hint = 'Q3 2026';
+  @tracked label = 'Reporting period';
+  @tracked noStep = false;
+  @tracked quiet = false;
+  @tracked emitted = 'Nothing emitted yet.';
+
+  localeOptions = LOCALES;
+  fiscalStartOptions = FISCAL_STARTS;
+  fiscalLabelOptions = FISCAL_LABELS;
+  hemisphereOptions = HEMISPHERES;
+
+  setReference = (v: string) => (this.reference = v);
+  setLocale = (v: string) => (this.locale = v);
+  setFiscalStart = (v: string) => (this.fiscalYearStart = v);
+  setFiscalLabel = (v: string) => (this.fiscalYearLabel = v as 'start' | 'end');
+  setHemisphere = (v: string) => (this.hemisphere = v as 'north' | 'south');
+  setSeed = (v: string) => (this.seed = v);
+  setHint = (v: string) => (this.hint = v);
+  setLabel = (v: string) => (this.label = v);
+  setNoStep = (v: boolean) => (this.noStep = v);
+  setQuiet = (v: boolean) => (this.quiet = v);
+
+  take = (period: Period | undefined, result: PeriodResult) => {
+    if (period) {
+      this.emitted =
+        'onChange with ' + period.id + ' — ' + period.start + ' to ' + period.end;
+    } else if (result.empty) {
+      this.emitted = 'onChange with undefined — the box is empty.';
+    } else {
+      this.emitted = 'onChange with undefined — ' + (result.issue ?? '');
+    }
+  };
+
+  get fiscalStartNumber(): number {
+    return Number(this.fiscalYearStart);
+  }
+
+  get options() {
+    return {
+      reference: this.reference,
+      locale: this.locale,
+      fiscalYearStart: this.fiscalStartNumber,
+      fiscalYearLabel: this.fiscalYearLabel,
+      hemisphere: this.hemisphere,
+    };
+  }
+
+  /** Every documented form, resolved under the current conventions. */
+  get specimens(): SpecimenRow[] {
+    let forms = PERIOD_FORMS.concat(['Q3', 'Winter 2026']);
+    return forms.map((typed) => {
+      let result = parsePeriod(typed, this.options);
+      let period = result.period;
+      return {
+        typed,
+        kind: period ? period.kind : '—',
+        id: period ? period.id : '—',
+        range: period
+          ? periodRangeText(period, this.locale)
+          : (result.issue ?? ''),
+        days: period ? String(period.days) : '',
+      };
+    });
+  }
+
+  get usage(): string {
+    return (
+      '<PeriodInput' +
+      " @reference='" +
+      this.reference +
+      "'" +
+      " @fiscalYearStart=" +
+      '{{' +
+      this.fiscalYearStart +
+      '}}' +
+      ' @onChange={{this.take}} />'
+    );
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='PeriodInput'
+      @description='Type Q3, Jan 2026, W12 or Summer 2025 and get a typed period back — a kind, a year, an inclusive date range and a key that sorts. Not a date picker and not a duration: a period is a NAME for a span of the calendar that a reader already knows. Every convention that has no universal answer is a knob, including the one that matters most: with no reference instant, a partial period is refused rather than resolved against the wall clock.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='pretui-perioddemo'>
+          <PeriodInput
+            @defaultValue={{this.seed}}
+            @reference={{this.reference}}
+            @locale={{this.locale}}
+            @fiscalYearStart={{this.fiscalStartNumber}}
+            @fiscalYearLabel={{this.fiscalYearLabel}}
+            @hemisphere={{this.hemisphere}}
+            @label={{this.label}}
+            @hint={{this.hint}}
+            @noStep={{this.noStep}}
+            @quiet={{this.quiet}}
+            @onChange={{this.take}}
+          />
+          <p class='pretui-perioddemo-note'>{{this.emitted}}</p>
+
+          <p class='pretui-perioddemo-cap'>Every form, under the current
+            conventions</p>
+          <ul class='pretui-perioddemo-table'>
+            {{#each this.specimens key='typed' as |row|}}
+              <li class='pretui-perioddemo-row'>
+                <span class='pretui-perioddemo-typed'>{{row.typed}}</span>
+                <span class='pretui-perioddemo-kind'>{{row.kind}}</span>
+                <span class='pretui-perioddemo-id'>{{row.id}}</span>
+                <span class='pretui-perioddemo-range'>{{row.range}}</span>
+                <span class='pretui-perioddemo-days'>{{row.days}}</span>
+              </li>
+            {{/each}}
+          </ul>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='reference'
+          @value={{this.reference}}
+          @description='The instant a partial period like Q3 resolves against. Clear it and every partial form in the table below turns into a request for a year — which is the honest behaviour, because nothing here reads the clock and a card that guessed would index differently every time.'
+          @onInput={{this.setReference}}
+        />
+        <Args.String
+          @name='fiscalYearStart'
+          @value={{this.fiscalYearStart}}
+          @options={{this.fiscalStartOptions}}
+          @defaultValue='1'
+          @description='The calendar month a fiscal year starts in. 1 is the calendar year. Move it to 7 and Q1 becomes July to September.'
+          @onInput={{this.setFiscalStart}}
+        />
+        <Args.String
+          @name='fiscalYearLabel'
+          @value={{this.fiscalYearLabel}}
+          @options={{this.fiscalLabelOptions}}
+          @defaultValue='start'
+          @description='Whether a fiscal year is named for the calendar year it starts in or the one it ends in. There is genuinely no universal answer, so it is a knob rather than an assumption. Irrelevant while fiscalYearStart is 1.'
+          @onInput={{this.setFiscalLabel}}
+        />
+        <Args.String
+          @name='hemisphere'
+          @value={{this.hemisphere}}
+          @options={{this.hemisphereOptions}}
+          @defaultValue='north'
+          @description='Which hemisphere the season names describe. These are the meteorological seasons — three whole months each, no gaps and no overlaps, which is what makes a season a period at all.'
+          @onInput={{this.setHemisphere}}
+        />
+        <Args.String
+          @name='locale'
+          @value={{this.locale}}
+          @options={{this.localeOptions}}
+          @defaultValue='en-US'
+          @description='Decides which month names are understood and how the resolved range is written. English month names are always accepted as well, so a reader typing Mar into a German form is never told off.'
+          @onInput={{this.setLocale}}
+        />
+        <Args.String
+          @name='defaultValue'
+          @value={{this.seed}}
+          @description='The initial text. A resolved period is normalised on commit, so q3 2026 becomes Q3 2026 and the reader can see it was understood.'
+          @onInput={{this.setSeed}}
+        />
+        <Args.String
+          @name='hint'
+          @value={{this.hint}}
+          @description='Ghost text behind an empty box. Not a placeholder attribute — a placeholder doubles as the accessible name and vanishes on the first keystroke.'
+          @onInput={{this.setHint}}
+        />
+        <Args.String
+          @name='label'
+          @value={{this.label}}
+          @defaultValue='Period'
+          @description='The accessible name, ignored when a Field wrapper supplied a controlId.'
+          @onInput={{this.setLabel}}
+        />
+        <Args.Bool
+          @name='noStep'
+          @value={{this.noStep}}
+          @defaultValue={{false}}
+          @description='Hide the previous / next stepper. It moves the period by one of its OWN kind, so the next quarter after Q4 is Q1 of the following year and the next week after week 53 depends on how many weeks the year has. Up and down arrows do the same from the keyboard.'
+          @onInput={{this.setNoStep}}
+        />
+        <Args.Bool
+          @name='quiet'
+          @value={{this.quiet}}
+          @defaultValue={{false}}
+          @description='Hide the accepted-forms line. The resolved-range row is reserved space either way.'
+          @onInput={{this.setQuiet}}
+        />
+        <Args.Base
+          @name='Period'
+          @typeLabel='Interface'
+          @description='kind, id, year, index, start, end, days, label, and sortKey. The id sorts within a kind; sortKey is the start date and sorts across kinds, which an id cannot.'
+          @hideControls={{true}}
+        />
+        <Args.Action
+          @name='onChange'
+          @description='Fires on every keystroke with the resolved period, or undefined and the reason there is not one. The reason is computed immediately and only SHOWN after a commit, because telling a reader that Ja is not a month while they are typing January is how a parsing input becomes unusable.'
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-perioddemo {
+        display: grid;
+        gap: var(--space-3, 8px);
+        max-width: 560px;
+      }
+      .pretui-perioddemo-note {
+        margin: 0;
+        min-height: 1.4em;
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+      .pretui-perioddemo-cap {
+        margin: var(--space-3, 8px) 0 0;
+        font-size: var(--text-ui-xs, 10.5px);
+        letter-spacing: 0.08em;
+        text-transform: uppercase;
+        color: var(--muted-foreground);
+      }
+      .pretui-perioddemo-table {
+        margin: 0;
+        padding: 0;
+        list-style: none;
+        display: grid;
+        gap: 1px;
+      }
+      .pretui-perioddemo-row {
+        display: grid;
+        grid-template-columns: 6.5rem 4rem 5.5rem 1fr 2.5rem;
+        align-items: baseline;
+        gap: var(--space-2, 6px);
+        padding: 3px 0;
+        font-size: var(--text-ui-sm, 11.5px);
+        font-variant-numeric: tabular-nums;
+      }
+      .pretui-perioddemo-typed {
+        font-family: var(--font-mono);
+        color: var(--foreground);
+      }
+      .pretui-perioddemo-kind,
+      .pretui-perioddemo-id {
+        color: var(--muted-foreground);
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+        min-width: 0;
+      }
+      .pretui-perioddemo-range {
+        min-width: 0;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+        color: var(--foreground);
+      }
+      .pretui-perioddemo-days {
+        text-align: end;
+        color: var(--muted-foreground);
+      }
+      @container (max-width: 420px) {
+        .pretui-perioddemo-row {
+          grid-template-columns: 1fr 1fr;
+        }
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_PERIOD_INPUT: Record<string, unknown> = {
+  PeriodInput: PeriodInputUsage,
+};

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

@@ -0,0 +1,80 @@
+// Pretui — PhoneInput: boxel-ui's formatted phone field in Pretui cloth.
+import Component from '@glimmer/component';
+import { PhoneInput as BoxelPhoneInput } from '@cardstack/boxel-ui/components';
+import type { NormalizePhoneFormatResult } from '@cardstack/boxel-ui/helpers';
+import { emit, firstDefined } from '../pretui-primitives';
+import type { ControlAliasArgs } from '../pretui-primitives';
+
+// Same wrap as EmailInput: boxel-ui's awesome-phonenumber machinery
+// (as-you-type formatting, E.164 normalization, region validation) intact,
+// Pretui cloth via the token channel. onChange's NormalizePhoneFormatResult
+// collapses to @onValidation(errorMessage | null); @onInput receives the
+// sanitized value boxel emits (E.164 when valid, trimmed digits otherwise).
+
+export interface PhoneInputSignature {
+  Args: ControlAliasArgs & {
+    value?: string;
+    placeholder?: string;
+    disabled?: boolean;
+    required?: boolean;
+    controlId?: string;
+    onInput?: (value: string) => void;
+    onValidation?: (error: string | null) => void;
+  };
+  Element: HTMLDivElement;
+}
+
+export class PhoneInput extends Component<PhoneInputSignature> {
+  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);
+  }
+  handleChange = (
+    value: string | null,
+    validation: NormalizePhoneFormatResult | null,
+    _ev: Event,
+  ) => {
+    emit(
+      [this.args.onInput, this.args.onChange, this.args.onValueChange],
+      value ?? '',
+    );
+    this.args.onValidation?.(
+      validation && !validation.ok ? validation.error.message : null,
+    );
+  };
+  <template>
+    <div class='pretui-boxelwrap' data-test-pretui-phone-input ...attributes>
+      <BoxelPhoneInput
+        @value={{this.boxelValue}}
+        @onChange={{this.handleChange}}
+        @placeholder={{@placeholder}}
+        @disabled={{this.disabled}}
+        @required={{this.required}}
+        id={{@controlId}}
+      />
+    </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);
+          --background: var(--field, var(--boxel-light));
+          --border: var(--input);
+          --ring: var(--primary);
+          --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/phone-input.md

@@ -0,0 +1,55 @@
+## What it is
+
+A phone-number field with as-you-type formatting, E.164 normalisation and region-aware validation. Use it whenever a phone number is collected — the formatting alone is worth it, because a number typed as a continuous digit string is much harder to check by eye than one grouped by the user's region. Do not reach for plain **Input** with `type='tel'`: that gives you a numeric keypad and nothing else.
+
+## The contract
+
+```
+@value?, @placeholder?, @disabled?, @required?, @controlId?
+@onInput?(value: string)
+@onValidation?(error: string | null)
+```
+
+Identical in shape to **EmailInput**, **UrlInput** and the rest of the typed-input family — which is the point. They are interchangeable at a call site, and learning one teaches the others.
+
+**The two-callback split** is the same adaptation: boxel-ui's underlying control returns a `NormalizePhoneFormatResult` from its `onChange`, carrying the formatted value, the normalised E.164 form and any validation state in one object. Pretui collapses that into `@onInput(value)` — the same signature as every other control in the kit — plus `@onValidation(error | null)`.
+
+Worth being precise about what `@onInput` receives, because it determines what you store: it is the field's value as the user sees it, not necessarily the E.164 normalisation. If you need the canonical form for storage or comparison, read it from the boxel-ui layer rather than assuming the displayed string is it.
+
+`@value` is passed through as `null` when undefined, matching the underlying control's expectation.
+
+## Prior art
+
+A **thin runtime wrap of boxel-ui's phone input**, whose machinery is `awesome-phonenumber` — a port of Google's libphonenumber. That is the value being reused: as-you-type formatting per region, E.164 normalisation, and validity checks that know a UK mobile from a UK landline. Reimplementing any of that is a multi-year mistake.
+
+Against the field: **Web Awesome**, **Radix**, **React Spectrum** and **shadcn** all ship nothing here. Phone input is universally left to `react-phone-number-input`, `intl-tel-input` or an in-house regex — and the regex version is always wrong. So the comparison is: a real libphonenumber-backed field, dressed to match the kit, versus rolling your own.
+
+Where Pretui adds over boxel-ui: the callback split, and API consistency with the family.
+
+What is **not** exposed, and is the honest gap: **no country selector, no `@region` arg, no `@format` choice.** Every mature phone input has a flag dropdown that sets the parsing region, and there is none here — the region is whatever the underlying control defaults to. For an international form that is a real limitation, and the workaround is composing **InputGroup** with a **Select** yourself.
+
+## Accessibility
+
+Native `<input type="tel">` underneath; no APG pattern.
+
+What is right: `type="tel"` gives mobile users the numeric keypad and gives assistive tech the field's purpose.
+
+Gaps, and the first two are specific to phone fields:
+
+- **As-you-type formatting rewrites the field while the user types**, which is exactly the interaction screen readers and voice-input users handle worst — characters are inserted that the user did not type, and the caret moves. Verify what your target readers announce during input; this is a known-hard interaction and boxel-ui owns the implementation, so Pretui can neither guarantee nor fix it. If it is a problem, formatting on blur rather than on input is the accessible fallback.
+- **No `autocomplete="tel"`**, and no arg for it. **WCAG 1.3.5 Identify Input Purpose** (AA) requires it for a field collecting the user's own phone number, and it must currently be passed through `...attributes`. Family-wide hole.
+- **The ARIA wiring is boxel-ui's** and this wrapper adds none — whether the validation error reaches `aria-describedby` depends on the boxel-ui version. Verify it. The ecosystem's settled choice is `aria-describedby` over `aria-errormessage`, which VoiceOver and NVDA still handle poorly.
+- **No accessible name of its own.** Outside **Field**/**FormField** and without an explicit `aria-label`, the field is unnamed.
+- **`@onValidation` is a callback, not rendered output** — no `@errorMessage`/`@helperText` args here, unlike **Input**. If you drop the error, the field can show an invalid dress with nothing announced. Route it into a **FormField**.
+- **No visible format hint.** A user who does not know whether to include a country code has no instruction, which is a **WCAG 3.3.2 Labels or Instructions** concern. Use **FormField**'s `@description`.
+- **`@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 — the same height, radius, type-size and spacing knobs **Input** sets, so a phone field and a text field in the same form are pixel-identical.
+
+An inline `style` carries font inheritance (the UA font on native controls is one of the two places the token channel cannot reach). The invalid dress arrives from an enclosing **Field** by repointing `--border` and `--background`, so it works here without this component knowing about it — and the same mechanism means a theme redefines "invalid" once for the whole 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/phone-input.usage.gts

@@ -0,0 +1,91 @@
+// Pretui — PhoneInput usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { PhoneInput } from './phone-input';
+
+// ── PhoneInput ← phone-input/usage.gts ───────────────────────────────────
+// Dropped knobs: none upstream — the full set carries over. Same surface
+// adaptation as EmailInput: @onChange(value, NormalizePhoneFormatResult,
+// ev) splits into @onInput(value) + @onValidation(errorMessage | null).
+// @onInput receives boxel's sanitized value: E.164 when valid, trimmed
+// digits otherwise.
+class PhoneInputUsage extends Component {
+  @tracked value = '';
+  @tracked lastError: string | null = null;
+  @tracked placeholder = '';
+  @tracked disabled = false;
+  @tracked required = false;
+  setValue = (v: string) => (this.value = v);
+  setError = (e: string | null) => (this.lastError = e);
+  setPlaceholder = (v: string) => (this.placeholder = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  setRequired = (v: boolean) => (this.required = v);
+  get usage() {
+    let bits = [`@value='${this.value}'`];
+    if (this.required) bits.push('@required={{true}}');
+    bits.push('@onInput={{this.setValue}}', '@onValidation={{this.setError}}');
+    return `<PhoneInput ${bits.join(' ')} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='PhoneInput'
+      @description="Wraps boxel-ui's PhoneInput — as-you-type formatting, E.164 normalization, and region validation via awesome-phonenumber — re-dressed through the Pretui token channel. Sanitized values arrive via @onInput; the current validation error message (or null) via @onValidation."
+      @source={{this.usage}}
+    >
+      <:example>
+        <PhoneInput
+          @value={{this.value}}
+          @placeholder={{this.placeholder}}
+          @disabled={{this.disabled}}
+          @required={{this.required}}
+          @onInput={{this.setValue}}
+          @onValidation={{this.setError}}
+        />
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='value'
+          @optional={{true}}
+          @value={{this.value}}
+          @description='The current value passed to the input'
+          @onInput={{this.setValue}}
+        />
+        <Args.String
+          @name='placeholder'
+          @defaultValue='Enter phone'
+          @value={{this.placeholder}}
+          @description='Empty input placeholder'
+          @onInput={{this.setPlaceholder}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @value={{this.disabled}}
+          @onInput={{this.setDisabled}}
+        />
+        <Args.Bool
+          @name='required'
+          @value={{this.required}}
+          @description='Empty input counts as invalid once 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 the sanitized value as a string: E.164 when valid, trimmed digits otherwise.'
+        />
+        <Args.Action
+          @name='onValidation'
+          @description="Receives the current validation error message, or null when valid/empty — boxel-ui's NormalizePhoneFormatResult, collapsed to its error message."
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_PHONE_INPUT: Record<string, unknown> = {
+  PhoneInput: PhoneInputUsage,
+};

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

@@ -0,0 +1,2 @@
+// Pretui — PinInput: The Mantine / Chakra name for OtpInput.
+export { OtpInput as PinInput } from './otp-input';

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

@@ -0,0 +1,45 @@
+## What it is
+
+**OtpInput** under the name Mantine and Chakra use. The export is the same class — `import { PinInput } from './pin-input';` resolves to OtpInput — so the tile exists for a port of a Mantine `PinInput` or an agent whose first guess is that word. The contract and the depth, including a known focus defect, are on **OtpInput**; this page maps the Mantine and shadcn names onto it. For a code with a resend or expiry affordance, the surrounding form owns those.
+
+## The contract
+
+```
+@length?         — segment count (default 6); Mantine length, shadcn maxLength
+@value?, @defaultValue?
+@type?           — allowed character class (default 'numeric'); Mantine type
+@masked?         — password dots; Mantine mask
+@disabled?
+@label?          — group label announced by assistive tech (default 'One-time code')
+@onValueChange?  — every edit, with the joined dense string
+```
+
+**There is no `onComplete`.** Mantine and Chakra fire a second callback when the last slot lands; here the caller compares the emitted string's length to `@length` inside `@onValueChange`.
+
+## Prior art
+
+**Mantine `PinInput`** has `length`, `type` (`'number' | 'alphanumeric'` or a RegExp), `mask`, `placeholder`, `oneTimeCode` (sets `autocomplete`), `onComplete`, `error`, `size` and `radius`. **Chakra `PinInput`** is the same shape with `otp`, `manageFocus` and `placeholder`. **shadcn `InputOTP`** wraps input-otp: one hidden input over rendered slots, `maxLength`, `pattern`, and groups with separators.
+
+Where this is better: the emitted value is always dense, so a caller never compacts a string with holes, and completion is announced through a status region rather than carried by colour alone.
+
+Where it is thinner: no `placeholder`, no separator groups, no `error` state, no size or radius knobs, and the defect the OtpInput writeup records — every keystroke recreates the slot inputs and drops focus to the document, which makes keyboard entry close to unusable until it is fixed.
+
+## Accessibility
+
+OtpInput's: the slots sit in a `role='group'` named by `@label`, each slot is named "Digit N of M", and completion is announced once, politely, through a visually hidden status region. The focus loss on every keystroke is an accessibility defect first, and it is the alias's too.
+
+## Theming
+
+OtpInput's: `--pretui-otp-size` and `--pretui-otp-gap` for slot dimensions and spacing, over the kit's `--pretui-shadow-control` and `--pretui-shadow-inset` for the slot surfaces. Nothing is themed under a PinInput name.
+
+## React ecosystem
+
+| Mantine / Chakra / shadcn                      | Pretui                                       |
+| ---------------------------------------------- | -------------------------------------------- |
+| `length` / `maxLength`                         | `@length`                                    |
+| `value` / `onChange`                           | `@value` / `@onValueChange`                  |
+| `onComplete`                                   | compare the emitted length to `@length`      |
+| `type` / `pattern`                             | `@type` (`numeric`, `alpha`, `alphanumeric`) |
+| `mask`                                         | `@masked`                                    |
+| `oneTimeCode` / `otp`                          | not offered                                  |
+| `placeholder`, `error`, groups with separators | not offered                                  |