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

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

@@ -0,0 +1,274 @@
+// Pretui — FormatBytes usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { FormatBytes } from './format-bytes';
+import { LOCALES, SPOKEN_MODES } from '../demo-reading-format';
+
+// ── FormatBytes ──────────────────────────────────────────────────────────
+const BYTE_BASES = ['binary', 'decimal'];
+
+const BYTE_UNITS = ['byte', 'bit'];
+
+const BYTE_DISPLAYS = ['short', 'narrow', 'long'];
+
+// The page leads with the binary/decimal split because conflating them is
+// the classic bytes bug — the same number renders two different ways and
+// both are correct, which is exactly why it is a knob and never an
+// assumption. The specimen ladder shows one value crossing every scale
+// step, which is where an off-by-one-power error would show itself.
+const BYTE_LADDER = [512, 8_192, 1_048_576, 734_003_200, 5_497_558_138_880];
+
+class FormatBytesUsage extends Component {
+  baseOptions = BYTE_BASES;
+  unitOptions = BYTE_UNITS;
+  displayOptions = BYTE_DISPLAYS;
+  spokenOptions = SPOKEN_MODES;
+  localeOptions = LOCALES;
+  ladder = BYTE_LADDER;
+
+  @tracked value = 734003200;
+  @tracked base = 'binary';
+  @tracked unit = 'byte';
+  @tracked display = 'short';
+  @tracked locale = 'en-US';
+  @tracked maximumFractionDigits: number | null = 1;
+  @tracked token = false;
+  @tracked spoken = 'auto';
+
+  setValue = (v: number | null) => (this.value = v ?? 0);
+  setBase = (v: string) => (this.base = v);
+  setUnit = (v: string) => (this.unit = v);
+  setDisplay = (v: string) => (this.display = v);
+  setLocale = (v: string) => (this.locale = v);
+  setMaxFraction = (v: number | null) => (this.maximumFractionDigits = v);
+  setToken = (v: boolean) => (this.token = v);
+  setSpoken = (v: string) => (this.spoken = v);
+
+  get baseVal() {
+    return this.base as 'binary' | 'decimal';
+  }
+  get unitVal() {
+    return this.unit as 'byte' | 'bit';
+  }
+  get displayVal() {
+    return this.display as 'short' | 'narrow' | 'long';
+  }
+  get spokenVal() {
+    return this.spoken as 'auto' | 'always' | 'off';
+  }
+  get maxFractionVal() {
+    return this.maximumFractionDigits ?? undefined;
+  }
+  get otherBase() {
+    return this.base === 'binary' ? 'decimal' : 'binary';
+  }
+  get otherBaseVal() {
+    return this.otherBase as 'binary' | 'decimal';
+  }
+  get usage() {
+    let bits = [`@value={{${this.value}}}`];
+    if (this.base !== 'binary') bits.push(`@base='${this.base}'`);
+    if (this.unit !== 'byte') bits.push(`@unit='${this.unit}'`);
+    if (this.display !== 'short') bits.push(`@display='${this.display}'`);
+    if (this.locale !== 'en-US') bits.push(`@locale='${this.locale}'`);
+    if (this.maximumFractionDigits !== 1)
+      bits.push(`@maximumFractionDigits={{${this.maximumFractionDigits}}}`);
+    if (this.token) bits.push('@token={{true}}');
+    if (this.spoken !== 'auto') bits.push(`@spoken='${this.spoken}'`);
+    return `<FormatBytes ${bits.join(' ')} />`;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='FormatBytes'
+      @description="Human-readable byte sizes. The binary/decimal split is the point: 734,003,200 bytes is either 700 MiB or 734 MB depending on which convention you mean, and both are right — so the base is a required decision rather than a silent default. Reach for it wherever a file, payload, or quota size appears in prose; wear @token in machine contexts like an artifact table. Sibling of RelativeTime and FormatNumber."
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='fmt-stack'>
+          <p class='fmt-line'>
+            The
+            <em>Da Hong Pao</em>
+            origin scan uploaded from Wuyishan is
+            <FormatBytes
+              @value={{this.value}}
+              @base={{this.baseVal}}
+              @unit={{this.unitVal}}
+              @display={{this.displayVal}}
+              @locale={{this.locale}}
+              @maximumFractionDigits={{this.maxFractionVal}}
+              @token={{this.token}}
+              @spoken={{this.spokenVal}}
+            />
+            in the manifest.
+          </p>
+
+          <div class='fmt-compare'>
+            <span class='fmt-cap'>{{this.base}}</span>
+            <FormatBytes
+              @value={{this.value}}
+              @base={{this.baseVal}}
+              @unit={{this.unitVal}}
+              @display={{this.displayVal}}
+              @locale={{this.locale}}
+              @maximumFractionDigits={{this.maxFractionVal}}
+            />
+            <span class='fmt-cap'>{{this.otherBase}}</span>
+            <FormatBytes
+              @value={{this.value}}
+              @base={{this.otherBaseVal}}
+              @unit={{this.unitVal}}
+              @display={{this.displayVal}}
+              @locale={{this.locale}}
+              @maximumFractionDigits={{this.maxFractionVal}}
+            />
+          </div>
+
+          <ul class='fmt-ladder'>
+            {{#each this.ladder as |step|}}
+              <li>
+                <FormatBytes
+                  @value={{step}}
+                  @base={{this.baseVal}}
+                  @unit={{this.unitVal}}
+                  @display={{this.displayVal}}
+                  @locale={{this.locale}}
+                  @maximumFractionDigits={{this.maxFractionVal}}
+                />
+              </li>
+            {{/each}}
+          </ul>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.Number
+          @name='value'
+          @value={{this.value}}
+          @min={{0}}
+          @max={{5497558138880}}
+          @description='The size, counted in bytes (or bits when @unit is bit). Strings are coerced; a non-finite value renders @placeholder instead of NaN.'
+          @onInput={{this.setValue}}
+        />
+        <Args.String
+          @name='base'
+          @defaultValue='binary'
+          @value={{this.base}}
+          @options={{this.baseOptions}}
+          @description="binary = IEC, divide by 1024, KiB/MiB labels. decimal = SI, divide by 1000, kB/MB labels. Never inferred — conflating the two is the classic bytes bug."
+          @onInput={{this.setBase}}
+        />
+        <Args.String
+          @name='unit'
+          @defaultValue='byte'
+          @value={{this.unit}}
+          @options={{this.unitOptions}}
+          @description='What the raw number counts. bit is for throughput figures, where a factor of eight is a real defect.'
+          @onInput={{this.setUnit}}
+        />
+        <Args.String
+          @name='display'
+          @defaultValue='short'
+          @value={{this.display}}
+          @options={{this.displayOptions}}
+          @description='Unit wording: short (2.4 MB), narrow (2.4MB), long (2.4 megabytes). Decimal base only — binary always uses the IEC symbol.'
+          @onInput={{this.setDisplay}}
+        />
+        <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.Number
+          @name='maximumFractionDigits'
+          @value={{this.maximumFractionDigits}}
+          @min={{0}}
+          @max={{4}}
+          @description='Ceiling on fraction digits. Defaults to 0 for raw bytes and 1 once the value has been scaled.'
+          @onInput={{this.setMaxFraction}}
+        />
+        <Args.Number
+          @name='minimumFractionDigits'
+          @defaultValue={{0}}
+          @description='Floor on fraction digits — pin it to keep a column of sizes from jittering in width.'
+        />
+        <Args.Bool
+          @name='token'
+          @defaultValue={{false}}
+          @value={{this.token}}
+          @description='Wear the Token dress (Law 3) — mono and accent-tinted, for machine contexts rather than prose.'
+          @onInput={{this.setToken}}
+        />
+        <Args.String
+          @name='spoken'
+          @defaultValue='auto'
+          @value={{this.spoken}}
+          @options={{this.spokenOptions}}
+          @description='sr-only mirror policy. auto mirrors only when the visible text reads badly aloud (IEC symbols, narrow units); always forces it; off suppresses it.'
+          @onInput={{this.setSpoken}}
+        />
+        <Args.String
+          @name='placeholder'
+          @defaultValue='—'
+          @description='Rendered when the value is missing or non-finite. The component never emits NaN.'
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      /* Every value rides a token with a LIGHT fallback; no dark branch
+         anywhere — the theme frame supplies the swap. */
+      .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-compare {
+        display: grid;
+        grid-template-columns: auto 1fr;
+        align-items: baseline;
+        gap: var(--space-2, 6px) var(--space-3, 10px);
+        padding: var(--space-3, 10px);
+        border-radius: var(--radius-surface, 10px);
+        box-shadow: var(
+          --pretui-shadow-hairline,
+          0 0 0 1px var(--border)
+        );
+      }
+      .fmt-ladder {
+        display: flex;
+        flex-wrap: wrap;
+        gap: var(--space-2, 6px) var(--space-4, 14px);
+        margin: 0;
+        padding: 0;
+        list-style: none;
+        font-variant-numeric: tabular-nums;
+        font-size: var(--text-ui-md, 12.5px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_FORMAT_BYTES: Record<string, unknown> = {
+  FormatBytes: FormatBytesUsage,
+};

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

@@ -0,0 +1,249 @@
+// Pretui — FormatDate: a date or time through Intl that never reads the clock.
+import Component from '@glimmer/component';
+import { toIso } from '../internal/reading-extras';
+import { FormattedValue } from './formatted-value';
+import { defined, formatDate, toDate } from '../internal/reading-format';
+import type { FormatOptionBag } from '../internal/reading-format';
+
+// ── FormatDate ← wa-format-date ──────────────────────────────────────────
+// Sibling of RelativeTime (reading-extras): RelativeTime says how long ago,
+// FormatDate says when. Same conventions — a <time> root with a machine
+// `datetime`, a `title` carrying the long form, no clock read, no auto-tick.
+// Better than the inspiration:
+//   - `datetime` is calendar-correct: date-only renderings emit `toIso(d)`
+//     (local calendar date) instead of an ISO instant, which for a Berlin
+//     morning would otherwise stamp the previous day.
+//   - Intl throws when `dateStyle`/`timeStyle` meet component options
+//     (`month`, `weekday`, …). Precedence is resolved BEFORE Intl sees it:
+//     any component option present drops the styles.
+//   - `@omitCurrentYear` with a caller-supplied `@now` renders this year's
+//     dates as 'Mar 14' and older ones as 'Mar 14, 2025'. It never reads the
+//     clock: without `@now` it is inert.
+const STYLE_TO_PARTS: Record<string, FormatOptionBag> = {
+  short: { month: 'numeric', day: 'numeric' },
+  medium: { month: 'short', day: 'numeric' },
+  long: { month: 'long', day: 'numeric' },
+  full: { weekday: 'long', month: 'long', day: 'numeric' },
+};
+
+const DATE_PART_KEYS = [
+  'weekday',
+  'era',
+  'year',
+  'month',
+  'day',
+  'hour',
+  'minute',
+  'second',
+  'dayPeriod',
+];
+
+export interface FormatDateSignature {
+  Args: {
+    /** the moment to render: a Date, an epoch number, or a string. A bare `YYYY-MM-DD` is read as a LOCAL calendar date, not UTC midnight. */
+    date?: string | number | Date;
+    /** BCP-47 locale tag; omit for the runtime default. An unknown tag falls back rather than throwing. */
+    locale?: string;
+    /** whole-date preset. Ignored the moment any component knob (@month, @weekday, …) is set — Intl refuses the combination, so precedence is resolved here. */
+    dateStyle?: 'full' | 'long' | 'medium' | 'short';
+    /** whole-time preset, same precedence rule as @dateStyle */
+    timeStyle?: 'full' | 'long' | 'medium' | 'short';
+    /** weekday component */
+    weekday?: 'long' | 'short' | 'narrow';
+    /** era component */
+    era?: 'long' | 'short' | 'narrow';
+    /** year component */
+    year?: 'numeric' | '2-digit';
+    /** month component */
+    month?: 'numeric' | '2-digit' | 'long' | 'short' | 'narrow';
+    /** day component */
+    day?: 'numeric' | '2-digit';
+    /** hour component */
+    hour?: 'numeric' | '2-digit';
+    /** minute component */
+    minute?: 'numeric' | '2-digit';
+    /** second component */
+    second?: 'numeric' | '2-digit';
+    /** timezone label component */
+    timeZoneName?: 'long' | 'short' | 'shortOffset' | 'longOffset';
+    /** force 12- or 24-hour clock; leave unset to follow the locale */
+    hour12?: boolean;
+    /** finer-grained clock control than @hour12 */
+    hourCycle?: 'h11' | 'h12' | 'h23' | 'h24';
+    /** IANA zone, e.g. 'Asia/Shanghai'. An unknown zone falls back to local rather than throwing. */
+    timeZone?: string;
+    /** non-Gregorian calendar, e.g. 'japanese' */
+    calendar?: string;
+    /** digit system, e.g. 'arab' */
+    numberingSystem?: string;
+    /** reference instant for @omitCurrentYear. Caller-supplied, exactly as RelativeTime takes @now — this component never reads the clock. */
+    now?: string | number | Date;
+    /** drop the year when the date falls in the same year as @now. Inert without @now. */
+    omitCurrentYear?: boolean;
+    /** any Intl.DateTimeFormat option not named above; named knobs win over it */
+    options?: FormatOptionBag;
+    /** title attribute carrying the long form (default true). A caller-supplied title in ...attributes wins. */
+    hint?: boolean;
+    /** wear the Token dress (Law 3) — for machine contexts like a log line */
+    token?: boolean;
+    /** sr-only mirror policy: 'auto' mirrors when the visible form is numeric-heavy ('3/14/26' reads badly aloud), 'always' forces it, 'off' suppresses it */
+    spoken?: 'auto' | 'always' | 'off';
+    /** rendered when the date is missing or unparseable (default '—') */
+    placeholder?: string;
+  };
+  Element: HTMLTimeElement;
+}
+
+export class FormatDate extends Component<FormatDateSignature> {
+  get dateObj(): Date | undefined {
+    return toDate(this.args.date);
+  }
+  get nowObj(): Date | undefined {
+    return toDate(this.args.now);
+  }
+  /** the caller's knobs merged over @options, undefined entries stripped */
+  get requested(): FormatOptionBag {
+    let a = this.args;
+    return defined({
+      ...(a.options ?? {}),
+      dateStyle: a.dateStyle,
+      timeStyle: a.timeStyle,
+      weekday: a.weekday,
+      era: a.era,
+      year: a.year,
+      month: a.month,
+      day: a.day,
+      hour: a.hour,
+      minute: a.minute,
+      second: a.second,
+      timeZoneName: a.timeZoneName,
+      hour12: a.hour12,
+      hourCycle: a.hourCycle,
+      timeZone: a.timeZone,
+      calendar: a.calendar,
+      numberingSystem: a.numberingSystem,
+    });
+  }
+  get options(): FormatOptionBag {
+    let bag: FormatOptionBag = { ...this.requested };
+    let hasParts = DATE_PART_KEYS.some((k) => bag[k] !== undefined);
+    if (hasParts) {
+      // Intl throws on dateStyle beside a component option — parts win.
+      delete bag['dateStyle'];
+      delete bag['timeStyle'];
+    }
+    let sameYear =
+      this.args.omitCurrentYear === true &&
+      this.dateObj !== undefined &&
+      this.nowObj !== undefined &&
+      this.dateObj.getFullYear() === this.nowObj.getFullYear();
+    if (sameYear) {
+      let style = bag['dateStyle'];
+      if (typeof style === 'string' && STYLE_TO_PARTS[style]) {
+        delete bag['dateStyle'];
+        bag = { ...STYLE_TO_PARTS[style], ...bag };
+      }
+      delete bag['year'];
+    }
+    if (Object.keys(bag).length === 0) {
+      return { dateStyle: 'medium' };
+    }
+    // A bag of only zone/system knobs still needs something to render.
+    let renders =
+      bag['dateStyle'] !== undefined ||
+      bag['timeStyle'] !== undefined ||
+      DATE_PART_KEYS.some((k) => bag[k] !== undefined);
+    return renders ? bag : { ...bag, dateStyle: 'medium' };
+  }
+  get hasTime(): boolean {
+    let bag = this.options;
+    return (
+      bag['timeStyle'] !== undefined ||
+      bag['hour'] !== undefined ||
+      bag['minute'] !== undefined ||
+      bag['second'] !== undefined
+    );
+  }
+  get text(): string {
+    let d = this.dateObj;
+    if (!d) {
+      return this.args.placeholder ?? '—';
+    }
+    return formatDate(d, this.args.locale, this.options);
+  }
+  get datetimeAttr(): string | undefined {
+    let d = this.dateObj;
+    if (!d) {
+      return undefined;
+    }
+    // A calendar date stays a calendar date; an instant stays an instant.
+    return this.hasTime ? d.toISOString() : toIso(d);
+  }
+  get longText(): string | undefined {
+    let d = this.dateObj;
+    if (!d) {
+      return undefined;
+    }
+    let bag: FormatOptionBag = { dateStyle: 'full' };
+    if (this.hasTime) {
+      bag['timeStyle'] = 'short';
+    }
+    let zone = this.options['timeZone'];
+    if (zone !== undefined) {
+      bag['timeZone'] = zone;
+    }
+    return formatDate(d, this.args.locale, bag);
+  }
+  get titleAttr(): string | undefined {
+    if (this.args.hint === false) {
+      return undefined;
+    }
+    let long = this.longText;
+    return long === this.text ? undefined : long;
+  }
+  get numericLooking(): boolean {
+    let bag = this.options;
+    let month = bag['month'];
+    return (
+      bag['dateStyle'] === 'short' || month === 'numeric' || month === '2-digit'
+    );
+  }
+  get spoken(): string | undefined {
+    let mode = this.args.spoken ?? 'auto';
+    if (mode === 'off' || !this.dateObj) {
+      return undefined;
+    }
+    if (mode === 'always' || this.numericLooking) {
+      let long = this.longText;
+      return long === this.text ? undefined : long;
+    }
+    return undefined;
+  }
+  get isEmpty(): boolean {
+    return this.dateObj === undefined;
+  }
+  <template>
+    <time
+      class='pretui-format-date'
+      datetime={{this.datetimeAttr}}
+      title={{this.titleAttr}}
+      data-test-pretui-format-date
+      ...attributes
+    >
+      <FormattedValue
+        @text={{this.text}}
+        @spoken={{this.spoken}}
+        @token={{@token}}
+        @empty={{this.isEmpty}}
+      />
+    </time>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-format-date {
+          white-space: nowrap;
+          font-variant-numeric: tabular-nums;
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,55 @@
+## What it is
+
+Locale-aware date and time rendering on a real `<time>` element, with a correct `datetime` attribute and a long-form title.
+
+**RelativeTime** is its sibling: this one says "14 March 2026", that one says "2 months ago".
+
+## The contract
+
+```
+@date?      — a Date, an epoch number, or a string. A bare YYYY-MM-DD is read as a
+              LOCAL calendar date, not UTC midnight
+@locale?    — BCP-47 tag; an unknown tag falls back rather than throwing
+@dateStyle?, @timeStyle? — whole-date and whole-time presets
+@weekday?, @era?, @year?, @month?, @day?, @hour?, @minute?, @second?
+@timeZone?, @calendar?, @numberingSystem?
+@now?       — reference instant for @omitCurrentYear. Caller-supplied
+@omitCurrentYear? — drop the year when the date is in the same year as @now
+@options?   — any Intl option not named above; named knobs win
+@hint?      — title attribute carrying the long form. Default true
+@token?     — wear the Token dress, for machine contexts like a log line
+@spoken?    — sr-only mirror: 'auto' (default) | 'always' | 'off'
+@placeholder? — when the date is missing or unparseable. Default '—'
+```
+
+**A bare `YYYY-MM-DD` is a local calendar date, not UTC midnight.** Reading it as an instant is how a date shifts by a day for half the world.
+
+**`datetime` is calendar-correct.** A date-only rendering emits a local calendar date rather than an ISO instant — which for a Berlin morning would otherwise stamp the previous day.
+
+**Precedence is resolved before Intl sees it.** `Intl` _throws_ when `dateStyle`/`timeStyle` meet component options like `@month` or `@weekday`; here any component option present simply drops the styles. Same policy as **FormatNumber**: a formatter must not take down a card over a combination of args.
+
+**`@omitCurrentYear` is inert without `@now`**, because deciding what "this year" means requires an instant and this component never reads the clock.
+
+## Prior art
+
+**`wa-format-date`.**
+
+Where Pretui is better: the calendar-correct `datetime`, the resolved precedence instead of a throw, and the clock-free `@omitCurrentYear`.
+
+Where it is thinner: no date ranges, no duration formatting, and no "smart" format that switches between absolute and relative — combining the two is the caller's call.
+
+## Accessibility
+
+- **It renders a real `<time>` with a machine-readable `datetime`**, so assistive technology and anything parsing the page get the unambiguous value.
+- **`@spoken='auto'` mirrors when the visible form is numeric-heavy.** "3/14/26" read aloud is three numbers; the mirror says the date.
+- **`@hint` puts the long form in a `title`**, which is a pointer affordance rather than an accessible one — a caller-supplied title in `...attributes` wins, so it can be overridden.
+- **`@placeholder` announces as a dash** rather than leaving an empty element.
+- **A date with no year is ambiguous out of context.** `@omitCurrentYear` is a density optimisation for a list where the year is obvious; in a single rendered date it removes information a reader may need.
+
+## Theming
+
+`@token` swaps to the kit's **Token** treatment; otherwise the element inherits everything from its context.
+
+A date in prose should be prose and a date in a log line should be mono, and those are the only two cases — which is why there is one flag rather than a token surface.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.