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

package/bundled-realms/pretui/components/format-date.usage.gts

@@ -0,0 +1,245 @@
+// Pretui — FormatDate usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { FormatDate } from './format-date';
+import { LOCALES, SPOKEN_MODES } from '../demo-reading-format';
+
+// ── FormatDate ───────────────────────────────────────────────────────────
+const DATE_STYLES = ['', 'full', 'long', 'medium', 'short'];
+
+const ZONES = ['UTC', 'Asia/Shanghai', 'Europe/Lisbon', 'America/Sao_Paulo'];
+
+// The clock is NOT read here. @now is caller-supplied exactly as
+// RelativeTime takes it (realm law: no Date.now() in realm code), which is
+// also why @omitCurrentYear is inert until @now is passed — the component
+// has no other way to know what "this year" means.
+class FormatDateUsage extends Component {
+  styleOptions = DATE_STYLES;
+  localeOptions = LOCALES;
+  zoneOptions = ZONES;
+  spokenOptions = SPOKEN_MODES;
+
+  @tracked date = '2026-05-23T09:41:00Z';
+  @tracked locale = 'en-US';
+  @tracked dateStyle = 'medium';
+  @tracked timeStyle = '';
+  @tracked timeZone = 'UTC';
+  @tracked token = false;
+  @tracked hint = true;
+  @tracked spoken = 'auto';
+
+  setDate = (v: string) => (this.date = v);
+  setLocale = (v: string) => (this.locale = v);
+  setDateStyle = (v: string) => (this.dateStyle = v);
+  setTimeStyle = (v: string) => (this.timeStyle = v);
+  setTimeZone = (v: string) => (this.timeZone = v);
+  setToken = (v: boolean) => (this.token = v);
+  setHint = (v: boolean) => (this.hint = v);
+  setSpoken = (v: string) => (this.spoken = v);
+
+  get dateStyleVal() {
+    return (this.dateStyle || undefined) as
+      | 'full'
+      | 'long'
+      | 'medium'
+      | 'short'
+      | undefined;
+  }
+  get timeStyleVal() {
+    return (this.timeStyle || undefined) as
+      | 'full'
+      | 'long'
+      | 'medium'
+      | 'short'
+      | undefined;
+  }
+  get spokenVal() {
+    return this.spoken as 'auto' | 'always' | 'off';
+  }
+  get usage() {
+    let bits = [`@date='${this.date}'`];
+    if (this.dateStyle) bits.push(`@dateStyle='${this.dateStyle}'`);
+    if (this.timeStyle) bits.push(`@timeStyle='${this.timeStyle}'`);
+    if (this.locale !== 'en-US') bits.push(`@locale='${this.locale}'`);
+    if (this.timeZone !== 'UTC') bits.push(`@timeZone='${this.timeZone}'`);
+    if (this.token) bits.push('@token={{true}}');
+    if (!this.hint) bits.push('@hint={{false}}');
+    if (this.spoken !== 'auto') bits.push(`@spoken='${this.spoken}'`);
+    return `<FormatDate ${bits.join(' ')} />`;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='FormatDate'
+      @description="Locale-aware dates and times over Intl.DateTimeFormat, rendered inside a real <time datetime> element so the machine-readable instant survives alongside the human one. Presets (@dateStyle/@timeStyle) and component knobs (@year, @month, @weekday…) are mutually exclusive in Intl, so precedence is resolved here instead of throwing. Takes @now as an argument and never reads the clock. Sibling of RelativeTime, which measures distance rather than stating a moment."
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='fmt-stack'>
+          <p class='fmt-line'>
+            The
+            <em>Silver Needle</em>
+            lot from Fuding cleared inspection on
+            <FormatDate
+              @date={{this.date}}
+              @locale={{this.locale}}
+              @dateStyle={{this.dateStyleVal}}
+              @timeStyle={{this.timeStyleVal}}
+              @timeZone={{this.timeZone}}
+              @token={{this.token}}
+              @hint={{this.hint}}
+              @spoken={{this.spokenVal}}
+            />.
+          </p>
+
+          <div class='fmt-grid'>
+            {{#each this.localeOptions as |loc|}}
+              <div class='fmt-cell'>
+                <span class='fmt-cap'>{{loc}}</span>
+                <FormatDate
+                  @date={{this.date}}
+                  @locale={{loc}}
+                  @dateStyle={{this.dateStyleVal}}
+                  @timeStyle={{this.timeStyleVal}}
+                  @timeZone={{this.timeZone}}
+                />
+              </div>
+            {{/each}}
+          </div>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='date'
+          @value={{this.date}}
+          @description='A Date, an epoch number, or a string. A bare YYYY-MM-DD is read as a LOCAL calendar date, not UTC midnight — the off-by-one-day trap.'
+          @onInput={{this.setDate}}
+        />
+        <Args.String
+          @name='dateStyle'
+          @value={{this.dateStyle}}
+          @options={{this.styleOptions}}
+          @description='Whole-date preset. Ignored the moment any component knob is set, because Intl refuses the combination.'
+          @onInput={{this.setDateStyle}}
+        />
+        <Args.String
+          @name='timeStyle'
+          @value={{this.timeStyle}}
+          @options={{this.styleOptions}}
+          @description='Whole-time preset, same precedence rule as @dateStyle. Empty renders a date with no time.'
+          @onInput={{this.setTimeStyle}}
+        />
+        <Args.String
+          @name='locale'
+          @value={{this.locale}}
+          @options={{this.localeOptions}}
+          @description='BCP-47 tag; omit for the runtime default. An unknown tag falls back rather than throwing.'
+          @onInput={{this.setLocale}}
+        />
+        <Args.String
+          @name='timeZone'
+          @value={{this.timeZone}}
+          @options={{this.zoneOptions}}
+          @description='IANA zone. An unknown zone falls back to local rather than throwing.'
+          @onInput={{this.setTimeZone}}
+        />
+        <Args.Bool
+          @name='hint'
+          @defaultValue={{true}}
+          @value={{this.hint}}
+          @description='Carry the long form in a title attribute. A caller-supplied title in ...attributes wins.'
+          @onInput={{this.setHint}}
+        />
+        <Args.Bool
+          @name='token'
+          @defaultValue={{false}}
+          @value={{this.token}}
+          @description='Wear the Token dress (Law 3) — for log lines and machine contexts.'
+          @onInput={{this.setToken}}
+        />
+        <Args.String
+          @name='spoken'
+          @defaultValue='auto'
+          @value={{this.spoken}}
+          @options={{this.spokenOptions}}
+          @description="sr-only mirror policy. auto mirrors when the visible form is numeric-heavy — '3/14/26' reads badly aloud."
+          @onInput={{this.setSpoken}}
+        />
+        <Args.String
+          @name='now'
+          @description='Reference instant for @omitCurrentYear, caller-supplied exactly as RelativeTime takes it. This component never reads the clock (realm law: no Date.now()).'
+        />
+        <Args.Bool
+          @name='omitCurrentYear'
+          @defaultValue={{false}}
+          @description='Drop the year when the date falls in the same year as @now. Inert without @now — there is no other way to know what this year is.'
+        />
+        <Args.String
+          @name='weekday, era, year, month, day, hour, minute, second, timeZoneName'
+          @description='Individual Intl components. Setting any one of them overrides @dateStyle/@timeStyle entirely.'
+        />
+        <Args.String
+          @name='hour12, hourCycle, calendar, numberingSystem'
+          @description='Clock, calendar system (e.g. japanese), and digit system (e.g. arab).'
+        />
+        <Args.Object
+          @name='options'
+          @description='Escape hatch for any Intl.DateTimeFormat option not named above. Named knobs win over it.'
+        />
+        <Args.String
+          @name='placeholder'
+          @defaultValue='—'
+          @description='Rendered when the date is missing or unparseable. Never emits Invalid Date.'
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .fmt-stack {
+        display: flex;
+        flex-direction: column;
+        gap: var(--space-4, 14px);
+      }
+      .fmt-line {
+        margin: 0;
+        font-size: var(--text-ui-md, 12.5px);
+        line-height: 1.6;
+        color: var(--foreground);
+      }
+      .fmt-line em {
+        font-style: normal;
+        font-weight: 600;
+      }
+      .fmt-cap {
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        font-weight: 600;
+        letter-spacing: var(--track-eyebrow, 0.06em);
+        text-transform: uppercase;
+        color: var(--muted-foreground);
+      }
+      .fmt-grid {
+        display: grid;
+        grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
+        gap: var(--space-3, 10px);
+      }
+      .fmt-cell {
+        display: flex;
+        flex-direction: column;
+        gap: var(--space-1, 4px);
+        padding: var(--space-3, 10px);
+        border-radius: var(--radius-surface, 10px);
+        box-shadow: var(
+          --pretui-shadow-hairline,
+          0 0 0 1px var(--border)
+        );
+        font-size: var(--text-ui-md, 12.5px);
+        color: var(--foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_FORMAT_DATE: Record<string, unknown> = {
+  FormatDate: FormatDateUsage,
+};

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

@@ -0,0 +1,138 @@
+// Pretui — FormatNumber: a number, percent, currency or unit through Intl.
+import Component from '@glimmer/component';
+import { FormattedValue } from './formatted-value';
+import { defined, formatNumber, toNumber } from '../internal/reading-format';
+import type { FormatOptionBag } from '../internal/reading-format';
+
+// ── FormatNumber ← wa-format-number ──────────────────────────────────────
+// Better than the inspiration: the whole Intl.NumberFormat surface is named
+// and separately settable (Law 7) with `@options` as the escape hatch for
+// anything not named; `style: 'currency'` with no currency (and `'unit'` with
+// no unit) degrades to a decimal instead of throwing; and compact/scientific
+// notation keeps its full-precision value for a screen reader — '1.2M' is
+// visible, '1,234,567' is spoken.
+export interface FormatNumberSignature {
+  Args: {
+    /** the number to render (strings are coerced; anything non-finite renders @placeholder) */
+    value?: number | string;
+    /** BCP-47 locale tag; omit for the runtime default. An unknown tag falls back rather than throwing. */
+    locale?: string;
+    /** 'decimal' (default), 'currency', 'percent' (value 0.42 → 42%), or 'unit' */
+    style?: 'decimal' | 'currency' | 'percent' | 'unit';
+    /** ISO 4217 code, required by style='currency'; without it the style degrades to decimal instead of throwing */
+    currency?: string;
+    /** how the currency is written */
+    currencyDisplay?: 'symbol' | 'narrowSymbol' | 'code' | 'name';
+    /** how negative currency amounts are marked */
+    currencySign?: 'standard' | 'accounting';
+    /** CLDR unit identifier for style='unit', e.g. 'kilogram' or 'kilogram-per-hour' */
+    unit?: string;
+    /** unit wording for style='unit' */
+    unitDisplay?: 'short' | 'narrow' | 'long';
+    /** 'standard' (default), 'compact' (1.2M), 'scientific', 'engineering' */
+    notation?: 'standard' | 'compact' | 'scientific' | 'engineering';
+    /** compact wording: 'short' (1.2M) or 'long' (1.2 million) */
+    compactDisplay?: 'short' | 'long';
+    /** when the sign is shown */
+    signDisplay?: 'auto' | 'never' | 'always' | 'exceptZero' | 'negative';
+    /** grouping separators: true/false, or 'always' | 'auto' | 'min2' */
+    useGrouping?: boolean | 'always' | 'auto' | 'min2';
+    /** pad the integer part to at least this many digits */
+    minimumIntegerDigits?: number;
+    /** floor on fraction digits */
+    minimumFractionDigits?: number;
+    /** ceiling on fraction digits */
+    maximumFractionDigits?: number;
+    /** floor on significant digits (wins over fraction digits) */
+    minimumSignificantDigits?: number;
+    /** ceiling on significant digits (wins over fraction digits) */
+    maximumSignificantDigits?: number;
+    /** digit system, e.g. 'deva' */
+    numberingSystem?: string;
+    /** any Intl.NumberFormat option not named above; named knobs win over it */
+    options?: FormatOptionBag;
+    /** wear the Token dress (Law 3) — for machine contexts like a parameter row */
+    token?: boolean;
+    /** sr-only mirror policy: 'auto' mirrors whenever the visible text is abbreviated (compact/scientific/engineering notation), 'always' forces it, 'off' suppresses it */
+    spoken?: 'auto' | 'always' | 'off';
+    /** rendered when the value is missing or not a finite number (default '—') */
+    placeholder?: string;
+  };
+  Element: HTMLSpanElement;
+}
+
+export class FormatNumber extends Component<FormatNumberSignature> {
+  get num(): number | undefined {
+    return toNumber(this.args.value);
+  }
+  get options(): FormatOptionBag {
+    let a = this.args;
+    return defined({
+      ...(a.options ?? {}),
+      style: a.style,
+      currency: a.currency,
+      currencyDisplay: a.currencyDisplay,
+      currencySign: a.currencySign,
+      unit: a.unit,
+      unitDisplay: a.unitDisplay,
+      notation: a.notation,
+      compactDisplay: a.compactDisplay,
+      signDisplay: a.signDisplay,
+      useGrouping: a.useGrouping,
+      minimumIntegerDigits: a.minimumIntegerDigits,
+      minimumFractionDigits: a.minimumFractionDigits,
+      maximumFractionDigits: a.maximumFractionDigits,
+      minimumSignificantDigits: a.minimumSignificantDigits,
+      maximumSignificantDigits: a.maximumSignificantDigits,
+      numberingSystem: a.numberingSystem,
+    });
+  }
+  get text(): string {
+    let n = this.num;
+    if (n === undefined) {
+      return this.args.placeholder ?? '—';
+    }
+    return formatNumber(n, this.args.locale, this.options);
+  }
+  get abbreviated(): boolean {
+    let notation = this.options['notation'];
+    return (
+      notation === 'compact' ||
+      notation === 'scientific' ||
+      notation === 'engineering'
+    );
+  }
+  get spoken(): string | undefined {
+    let mode = this.args.spoken ?? 'auto';
+    let n = this.num;
+    if (mode === 'off' || n === undefined) {
+      return undefined;
+    }
+    if (mode !== 'always' && !this.abbreviated) {
+      return undefined;
+    }
+    // Full precision: same currency/unit dress, standard notation, grouped.
+    let bag: FormatOptionBag = { ...this.options };
+    delete bag['notation'];
+    delete bag['compactDisplay'];
+    delete bag['maximumFractionDigits'];
+    delete bag['minimumFractionDigits'];
+    delete bag['maximumSignificantDigits'];
+    delete bag['minimumSignificantDigits'];
+    let full = formatNumber(n, this.args.locale, bag);
+    return full === this.text ? undefined : full;
+  }
+  get isEmpty(): boolean {
+    return this.num === undefined;
+  }
+  <template>
+    <FormattedValue
+      @text={{this.text}}
+      @spoken={{this.spoken}}
+      @token={{@token}}
+      @empty={{this.isEmpty}}
+      data-test-pretui-format-number
+      ...attributes
+    />
+  </template>
+}

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

@@ -0,0 +1,51 @@
+## What it is
+
+Locale-aware number rendering: decimals, currency, percentages, units, compact notation — the whole of `Intl.NumberFormat` exposed as args, with a screen-reader mirror where the visible text is abbreviated.
+
+## The contract
+
+```
+@value?       — the number; strings are coerced, anything non-finite renders @placeholder
+@locale?      — BCP-47 tag; an unknown tag falls back rather than throwing
+@style?       — 'decimal' (default) | 'currency' | 'percent' | 'unit'
+@currency?    — ISO 4217, required by style='currency'
+@currencyDisplay?, @currencySign?
+@unit?, @unitDisplay?   — CLDR unit identifier and wording
+@notation?    — 'standard' (default) | 'compact' | 'scientific' | 'engineering'
+@compactDisplay?, @signDisplay?, @useGrouping?
+@minimumIntegerDigits?, @minimumFractionDigits?, @maximumFractionDigits?
+@minimumSignificantDigits?, @maximumSignificantDigits?
+@numberingSystem?
+@options?     — any Intl option not named above; named knobs win over it
+@token?       — wear the Token dress, for machine contexts like a parameter row
+@spoken?      — sr-only mirror: 'auto' (default) | 'always' | 'off'
+@placeholder? — when the value is missing or not finite. Default '—'
+```
+
+**Nothing throws.** An unknown locale falls back; `style='currency'` without a `@currency` degrades to decimal. A formatter that throws takes a whole card's render down over a data problem, which is never the right trade in a realm.
+
+**Named knobs win over `@options`.** The bag is an escape hatch for options this contract does not name, not a second way to set the ones it does.
+
+**`@spoken='auto'` mirrors whenever the visible text is abbreviated** — compact, scientific or engineering notation. "1.2M" read aloud is not a number; the mirror says the whole one.
+
+## Prior art
+
+**`wa-format-number`.**
+
+Where Pretui is better: the spoken mirror, and the refusal to throw. The upstream passes options straight to Intl, so a bad locale or a currency style with no code is a runtime exception in the middle of a page.
+
+Where it is thinner: no range formatting (`formatRange`), no per-part styling — you cannot make the currency symbol smaller than the digits — and no plural-aware wording beyond what `@unitDisplay` gives.
+
+## Accessibility
+
+- **The mirror is the point.** Abbreviated numbers read badly aloud, and `'auto'` decides that for you rather than leaving every call site to think about it.
+- **`@spoken='always'` is worth it in a dense table** where the visible form is terse for space reasons rather than notation reasons.
+- **`@spoken='off'` is for when the number is already announced elsewhere** — inside a label that repeats it, say.
+- **`@placeholder` defaults to an em dash**, which is announced as a dash rather than as silence, so a missing value is perceivable as missing.
+- **Grouping separators differ by locale**, which is why `@locale` matters to comprehension and not only to appearance.
+
+## Theming
+
+`@token` swaps the component into the kit's **Token** treatment — mono face, tabular figures — rather than defining a surface of its own.
+
+That is the whole theming story on purpose: a formatted number should look like the text around it unless it is a machine value, and the Token dress is the kit's one answer for machine values.