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

package/bundled-realms/pretui/components/record-face.gts

@@ -0,0 +1,153 @@
+// Pretui — RecordFace: a record shown as avatar, title and meta.
+import Component from '@glimmer/component';
+import { Avatar } from './avatar';
+import { iconFor } from '../icon-registry';
+import type { PickerRecord } from '../internal/forms-picker';
+
+// ── RecordFace ───────────────────────────────────────────────────────────
+// The shared presentational row behind every record surface in this file
+// (listbox option, selection pill, dueling-list option). Exported as its own
+// primitive so sibling forms components render records identically.
+//
+// This is SLDS's `slds-listbox__option_entity` media object — figure, primary
+// text, meta text — with the term highlight computed rather than authored.
+// EntityDisplay (reading-extras) is the natural composition and was the first
+// choice, but its `@title` is a string with no title block, so the matched
+// term could not carry a <mark>. Gap noted for that component's owner.
+export interface RecordFaceSignature {
+  Args: {
+    /** The record to render. */
+    record: PickerRecord;
+    /** Search term to highlight inside `label` (case-insensitive, first hit). */
+    term?: string;
+    /** 'sm' shrinks the visual and drops the meta line (pill dress). */
+    size?: 'sm' | 'md';
+    /** Force the meta line off even at 'md'. */
+    hideMeta?: boolean;
+  };
+  Element: HTMLSpanElement;
+}
+
+export class RecordFace extends Component<RecordFaceSignature> {
+  get size() {
+    return this.args.size ?? 'md';
+  }
+  get icon() {
+    return iconFor(this.args.record?.icon);
+  }
+  get avatarSize() {
+    return this.size === 'sm' ? 15 : 21;
+  }
+  get showMeta() {
+    return (
+      this.size === 'md' && !this.args.hideMeta && Boolean(this.args.record?.meta)
+    );
+  }
+  get parts() {
+    let label = this.args.record?.label ?? '';
+    let term = (this.args.term ?? '').trim();
+    if (!term) {
+      return { before: label, match: '', after: '' };
+    }
+    let at = label.toLowerCase().indexOf(term.toLowerCase());
+    if (at < 0) {
+      return { before: label, match: '', after: '' };
+    }
+    return {
+      before: label.slice(0, at),
+      match: label.slice(at, at + term.length),
+      after: label.slice(at + term.length),
+    };
+  }
+  <template>
+    <span
+      class='pretui-rface'
+      data-size={{this.size}}
+      data-test-pretui-record-face
+      ...attributes
+    >
+      <span class='pretui-rface-visual' aria-hidden='true'>
+        {{#if this.icon}}
+          {{#let this.icon as |RecordIcon|}}<RecordIcon />{{/let}}
+        {{else}}
+          <Avatar @name={{@record.label}} @size={{this.avatarSize}} />
+        {{/if}}
+      </span>
+      <span class='pretui-rface-text'>
+        <span class='pretui-rface-label'>{{#if this.parts.match}}{{this.parts.before}}<mark
+              class='pretui-rface-mark'
+            >{{this.parts.match}}</mark>{{this.parts.after}}{{else}}{{@record.label}}{{/if}}</span>
+        {{#if this.showMeta}}
+          <span class='pretui-rface-meta'>{{@record.meta}}</span>
+        {{/if}}
+      </span>
+    </span>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-rface {
+          display: flex;
+          align-items: center;
+          gap: var(--space-3, 8px);
+          min-width: 0;
+          text-align: left;
+        }
+        .pretui-rface[data-size='sm'] {
+          gap: 5px;
+        }
+        .pretui-rface-visual {
+          display: inline-flex;
+          align-items: center;
+          justify-content: center;
+          flex: none;
+          width: var(--pretui-rface-visual-size, 21px);
+          height: var(--pretui-rface-visual-size, 21px);
+          color: var(--muted-foreground);
+        }
+        .pretui-rface[data-size='sm'] .pretui-rface-visual {
+          width: var(--pretui-rface-visual-size, 15px);
+          height: var(--pretui-rface-visual-size, 15px);
+        }
+        .pretui-rface-visual svg {
+          width: 100%;
+          height: 100%;
+        }
+        .pretui-rface-text {
+          display: flex;
+          flex-direction: column;
+          min-width: 0;
+          line-height: 1.25;
+        }
+        .pretui-rface-label {
+          font-size: var(--text-ui-md, 12.5px);
+          letter-spacing: var(--track-ui, 0.01em);
+          color: var(--foreground);
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+        }
+        .pretui-rface[data-size='sm'] .pretui-rface-label {
+          font-size: var(--text-ui-sm, 11.5px);
+          font-weight: 500;
+        }
+        /* the matched run — a tint of the accent, never a contrast flip */
+        .pretui-rface-mark {
+          background: color-mix(
+            in oklch,
+            var(--primary) 22%,
+            transparent
+          );
+          color: inherit;
+          border-radius: 3px;
+          padding: 0 1px;
+        }
+        .pretui-rface-meta {
+          font-size: var(--text-ui-xs, 11px);
+          color: var(--muted-foreground);
+          overflow: hidden;
+          text-overflow: ellipsis;
+          white-space: nowrap;
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/record-pill.gts

@@ -0,0 +1,116 @@
+// Pretui — RecordPill: a removable chip for a picked record.
+import Component from '@glimmer/component';
+import { on } from '@ember/modifier';
+import { RecordFace } from './record-face';
+import type { PickerRecord } from '../internal/forms-picker';
+
+// ── RecordPill ───────────────────────────────────────────────────────────
+// A selected record as a removable capsule. Built as its own primitive (not
+// buried in Lookup) because every record-valued form control needs it.
+//
+// Chip is the kit's capsule, but it is an 18px status marker with
+// no room for a 16px hit target; MultiSelect already set the precedent of a
+// purpose-built chip for removable selections. This one carries the FilterChips
+// capsule dress at 24px with a real, individually-named remove button.
+export interface RecordPillSignature {
+  Args: {
+    /** The record shown in the pill. */
+    record: PickerRecord;
+    /** Render the remove button — true by default. */
+    removable?: boolean;
+    /** Suppresses the remove button and dims the capsule. */
+    disabled?: boolean;
+    /** Called with the record when the remove button is pressed. */
+    onRemove?: (record: PickerRecord) => void;
+  };
+  Element: HTMLSpanElement;
+}
+
+export class RecordPill extends Component<RecordPillSignature> {
+  get removable() {
+    return (this.args.removable ?? true) && !this.args.disabled;
+  }
+  get removeLabel() {
+    return `Remove ${this.args.record?.label ?? 'item'}`;
+  }
+  handleRemove = () => {
+    if (this.args.record) {
+      this.args.onRemove?.(this.args.record);
+    }
+  };
+  <template>
+    <span
+      class='pretui-rpill'
+      data-disabled={{if @disabled 'true'}}
+      data-test-pretui-record-pill={{@record.id}}
+      ...attributes
+    >
+      <RecordFace @record={{@record}} @size='sm' />
+      {{#if this.removable}}
+        <button
+          type='button'
+          class='pretui-rpill-x'
+          aria-label={{this.removeLabel}}
+          title={{this.removeLabel}}
+          {{on 'click' this.handleRemove}}
+        >
+          <svg
+            width='8'
+            height='8'
+            viewBox='0 0 8 8'
+            aria-hidden='true'
+          ><path
+              d='M1.5 1.5 6.5 6.5 M6.5 1.5 1.5 6.5'
+              fill='none'
+              stroke='currentColor'
+              stroke-width='1.4'
+              stroke-linecap='round'
+            /></svg>
+        </button>
+      {{/if}}
+    </span>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-rpill {
+          display: inline-flex;
+          align-items: center;
+          gap: 4px;
+          min-height: 24px;
+          max-width: 100%;
+          border-radius: 12px;
+          padding: 2px 3px 2px 4px;
+          background: var(--card);
+          box-shadow: var(
+            --pretui-shadow-control,
+            0 0 0 1px var(--border)
+          );
+          color: var(--foreground);
+        }
+        .pretui-rpill[data-disabled] {
+          opacity: 0.55;
+        }
+        .pretui-rpill-x {
+          border: 0;
+          background: none;
+          padding: 0;
+          width: 16px;
+          height: 16px;
+          border-radius: 50%;
+          display: inline-grid;
+          place-content: center;
+          color: var(--ink-3, var(--boxel-400));
+          cursor: pointer;
+          flex: none;
+        }
+        .pretui-rpill-x:hover {
+          background: var(--hover, var(--boxel-100));
+          color: var(--foreground);
+        }
+        .pretui-rpill-x:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 1px;
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/record-pill.md

@@ -0,0 +1,55 @@
+## What it is
+
+A selected record as a removable capsule: icon or initials **Avatar**, label, and an individually-named remove button. Use it wherever a record-valued field shows its current value — inside **Lookup**, in a filter bar, beside a form field, in a **RecordDetail** row. If the value is a category rather than a record, **Chip**. If you need the full identity row with a subtitle, **EntityDisplay**. If the reference is gone, **BrokenLink**.
+
+## The contract
+
+```
+@record: PickerRecord   (required)
+@removable? (default true), @disabled?
+@onRemove?(record: PickerRecord)
+Element: HTMLSpanElement
+```
+
+`@disabled` suppresses the remove button _and_ dims the capsule — one arg, both consequences, so a disabled pill cannot be half-interactive.
+
+**It is built as its own primitive rather than buried inside Lookup**, and the reason is stated in the source: every record-valued form control needs it. **MultiSelect** already set the precedent of a purpose-built removable chip.
+
+**Why it is not `Chip`**, which is the kit's capsule: Chip is an 18px status marker with no room for a 16px hit target. A remove button inside an 18px pill is below any usable target size. So RecordPill carries the **FilterChips** capsule dress at **24px** with a real remove button. That is a considered fork rather than duplication, and it is the right call — the alternative was a Chip with a variant that changes its height and adds a button, which is two components wearing one name.
+
+## Prior art
+
+**SLDS's `pill`** is the direct ancestor — icon, label, remove — and is the component this whole record family descends from. **React Spectrum's `TagGroup`/`Tag`** is the modern equivalent, with `onRemove`, keyboard removal via the Delete key, and roving tabindex across the group. **Web Awesome `wa-tag`** has `with-remove`. **Radix** has none.
+
+Where Pretui matches the field: an individually-named remove button, which is the one thing that makes a row of pills usable — "Remove Acme Corp", not eight buttons all called "Remove".
+
+Where it is behind React Spectrum, and it is the notable gap: **there is no group.** Spectrum's `TagGroup` gives a set of pills a roving tabindex (one tab stop for the whole group), arrow navigation between them, and **Delete/Backspace to remove the focused pill** — the keyboard affordance people actually use. Pretui has the pill and not the group, so eight selected records are eight pills plus eight remove buttons, all in the tab sequence, with no keyboard shortcut for removal. Whatever contains the pills (**Lookup**, **MultiSelect**) owns that problem and neither solves it.
+
+Also absent: no size axis, no click-to-open (a pill representing a record you cannot navigate to is a dead end), and no overflow/"+3 more" behaviour.
+
+## Accessibility
+
+No APG pattern for a pill; the applicable model for a _set_ of them is Spectrum's grid-based `TagGroup`.
+
+What is right:
+
+- **The remove button is individually named** with the record's label, so a screen-reader user knows what they are removing.
+- **`@disabled` removes the button rather than disabling it**, so there is no unreachable dead control in the tab order.
+- **The avatar or icon is `aria-hidden`** (RecordFace wraps it), so Avatar's initials never announce as loose letters; the pill's text is its name.
+
+Gaps:
+
+- **No group semantics** (above). This is the substantive one: a row of pills is a set, and nothing says so — no count, no `role="list"`, no roving focus, no Delete-key removal.
+- **The pill itself is not focusable**, only its remove button. So keyboard users tab _past_ the label to reach the remove control, and there is no way to focus a pill to inspect or open it.
+- **Removal is not announced.** The pill disappears and nothing says "Acme Corp removed" — except inside **Lookup**, which has its own live region doing exactly that. A bare RecordPill outside Lookup announces nothing, which is worth knowing before using it in a filter bar.
+- **Focus after removal is unmanaged.** Removing the last pill in a row leaves focus on a detached node; focus should move to the next pill or to the field. This is the classic removable-tag bug and every implementation has to solve it explicitly.
+- **The label may truncate** with no full-text fallback, though the accessible name carries the full string.
+- Target size: the remove button is a 16px hit target inside a 24px capsule — below WCAG **2.5.8**'s 24×24 minimum, and the reason the pill was sized up from Chip's 18px in the first place. Worth noting the constraint was acknowledged and only partly resolved.
+
+## Theming
+
+The **FilterChips** capsule dress at 24px: the per-record hue derivation (`--pretui-chip-mix`, `--pretui-ink-mix` mixed against `--card`, hairline against `--border`), `--foreground`, `--muted-foreground`, `--hover` for the remove button, and **Avatar**'s hash palette for the initials fallback.
+
+Because the dress is shared with FilterChips, a theme retuning chip tints moves record pills too — intended, and worth knowing if you were tuning filter chips and forgot they also appear inside every Lookup. The 24px height is fixed; a theme cannot make pills denser without breaking the remove button's already-marginal target size.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/record-pill.usage.gts

@@ -0,0 +1,108 @@
+// Pretui — RecordPill usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { FreestyleUsage } from './freestyle-usage';
+import { Button } from './button';
+import { RecordPill } from './record-pill';
+import type { PickerRecord } from '../internal/forms-picker';
+import { ACCOUNTS } from '../internal/forms-picker-fixtures';
+
+// ── RecordPill ───────────────────────────────────────────────────────────
+// The removable capsule Lookup renders for each selection, exported on its
+// own so every record-valued form control shows a selection identically.
+// Where SLDS puts each pill in a role='option' with a remove <button> inside
+// (option has children presentational — the button is never exposed), this is
+// a plain span with a real, individually named button.
+class RecordPillUsage extends Component {
+  records = ACCOUNTS.slice(0, 3);
+  @tracked removed: string[] = [];
+  @tracked removable = true;
+  @tracked disabled = false;
+
+  get shown(): PickerRecord[] {
+    return this.records.filter((r) => !this.removed.includes(r.id));
+  }
+  remove = (record: PickerRecord) => {
+    this.removed = [...this.removed, record.id];
+  };
+  restore = () => (this.removed = []);
+  setRemovable = (v: boolean) => (this.removable = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+
+  get usage() {
+    let bits = ['@record={{record}}'];
+    if (!this.removable) {
+      bits.push('@removable={{false}}');
+    }
+    if (this.disabled) {
+      bits.push('@disabled={{true}}');
+    }
+    bits.push('@onRemove={{this.remove}}');
+    return `{{#each this.records as |record|}}\n  <RecordPill ${bits.join(' ')} />\n{{/each}}`;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='RecordPill'
+      @description='A selected record as a removable capsule — the selection surface shared by Lookup and any sibling form control that holds record references. Composes RecordFace at sm size (icon or initials Avatar, then the label) and adds one real, individually named remove button, so a screen reader hears “Remove Wuyi Origins, button” rather than nothing at all. Use it wherever a chosen record has to be visible and revocable outside a dropdown.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='pillrow'>
+          {{#each this.shown key='id' as |record|}}
+            <RecordPill
+              @record={{record}}
+              @removable={{this.removable}}
+              @disabled={{this.disabled}}
+              @onRemove={{this.remove}}
+            />
+          {{/each}}
+          {{#unless this.shown.length}}
+            <Button @variant='secondary' {{on 'click' this.restore}}>
+              Restore records
+            </Button>
+          {{/unless}}
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.Object
+          @name='record'
+          @required={{true}}
+          @description='The record shown in the pill: {id, label, meta?, icon?}. Only the label and icon render at pill size.'
+          @value={{this.records}}
+        />
+        <Args.Bool
+          @name='removable'
+          @defaultValue={{true}}
+          @description='Render the remove button.'
+          @value={{this.removable}}
+          @onInput={{this.setRemovable}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @defaultValue={{false}}
+          @description='Dims the capsule and suppresses the remove button.'
+          @value={{this.disabled}}
+          @onInput={{this.setDisabled}}
+        />
+        <Args.Action
+          @name='onRemove'
+          @description='Fires with the record when the remove button is pressed.'
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .pillrow {
+        display: flex;
+        flex-wrap: wrap;
+        align-items: center;
+        gap: var(--space-2, 5px);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_RECORD_PILL: Record<string, unknown> = {
+  RecordPill: RecordPillUsage,
+};

package/bundled-realms/pretui/components/relative-time.gts

@@ -0,0 +1,88 @@
+// Pretui — RelativeTime: a date as a phrase relative to a caller-supplied now.
+import Component from '@glimmer/component';
+import { ABS_FMT } from '../internal/reading-extras';
+
+// ── RelativeTime ─────────────────────────────────────────────────────────
+// webawesome relative-time semantics, realm-adapted: the phrase is computed
+// ONCE from @date vs @now (Intl.RelativeTimeFormat) and re-derives only when
+// the args change. @now is caller-supplied per the LoadingState precedent;
+// when omitted it captures the construction instant. It does NOT auto-tick —
+// the realm forbids timers, so "2 minutes ago" stays put until the caller
+// refreshes @now.
+export interface RelativeTimeSignature {
+  Args: {
+    date: string | Date;
+    now?: string | Date;
+    format?: 'long' | 'short' | 'narrow';
+    numeric?: 'always' | 'auto';
+  };
+  Element: HTMLTimeElement;
+}
+
+const RELATIVE_UNITS: { unit: Intl.RelativeTimeFormatUnit; ms: number }[] = [
+  { unit: 'year', ms: 365.25 * 24 * 3600e3 },
+  { unit: 'month', ms: 30.44 * 24 * 3600e3 },
+  { unit: 'week', ms: 7 * 24 * 3600e3 },
+  { unit: 'day', ms: 24 * 3600e3 },
+  { unit: 'hour', ms: 3600e3 },
+  { unit: 'minute', ms: 60e3 },
+];
+
+function asDate(value: string | Date | undefined): Date | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  let d = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(d.getTime()) ? undefined : d;
+}
+
+export class RelativeTime extends Component<RelativeTimeSignature> {
+  // Captured once — the no-timer stand-in for "now" when @now is omitted.
+  private constructedAt = new Date();
+
+  get dateObj(): Date | undefined {
+    return asDate(this.args.date);
+  }
+  get nowObj(): Date {
+    return asDate(this.args.now) ?? this.constructedAt;
+  }
+  get phrase(): string {
+    let date = this.dateObj;
+    if (!date) {
+      return '';
+    }
+    let diff = date.getTime() - this.nowObj.getTime();
+    let match = RELATIVE_UNITS.find((u) => Math.abs(diff) >= u.ms);
+    let unit: Intl.RelativeTimeFormatUnit = match?.unit ?? 'second';
+    let ms = match?.ms ?? 1e3;
+    let fmt = new Intl.RelativeTimeFormat('en-US', {
+      style: this.args.format ?? 'long',
+      numeric: this.args.numeric ?? 'auto',
+    });
+    return fmt.format(Math.round(diff / ms), unit);
+  }
+  get datetimeAttr(): string | undefined {
+    return this.dateObj?.toISOString();
+  }
+  get titleAttr(): string | undefined {
+    let d = this.dateObj;
+    return d ? ABS_FMT.format(d) : undefined;
+  }
+  <template>
+    <time
+      class='pretui-relative-time'
+      datetime={{this.datetimeAttr}}
+      title={{this.titleAttr}}
+      data-test-pretui-relative-time
+      ...attributes
+    >{{this.phrase}}</time>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-relative-time {
+          white-space: nowrap;
+          font-variant-numeric: tabular-nums;
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/relative-time.md

@@ -0,0 +1,58 @@
+## What it is
+
+"3 days ago", "in 2 hours" — a timestamp rendered as a phrase relative to a reference instant. Use it in **Timeline**, **Feed**, comment lists, activity rows: anywhere the _recency_ matters more than the exact instant. If the exact instant matters — an audit record, a scheduled time, a legal timestamp — render the absolute date instead, or render both. For a formatted absolute date, **FormatDate**; for a fixed known date, **KnownDate**.
+
+## The contract
+
+```
+@date: string | Date   (required)
+@now?: string | Date
+@format? 'long' | 'short' | 'narrow'   (default 'long')
+@numeric? 'always' | 'auto'            (default 'auto')
+Element: HTMLTimeElement
+```
+
+**It does not tick.** The realm forbids timers, so the phrase is computed once from `@date` versus `@now` and recomputes only when the args change. `@now` is caller-supplied — the same precedent as **LoadingState**'s elapsed arg — and when omitted it captures the _construction_ instant. So "2 minutes ago" stays "2 minutes ago" until the caller refreshes `@now`. On a long-lived page that is a correctness issue you must handle, not a limitation you can ignore.
+
+**`@numeric='auto'` is the right default** and is what turns "1 day ago" into "yesterday" and "0 days ago" into "today". `'always'` keeps the numbers, which is what you want in a dense table where every row should read the same shape.
+
+The unit is chosen by walking a descending table (year, month, week, day, hour, minute) and taking the first whose magnitude the difference exceeds, falling back to seconds. Note **`week` is in the table**, so a 10-day-old item reads "last week" rather than "10 days ago" — worth knowing, because several implementations skip weeks.
+
+## Prior art
+
+**Web Awesome `wa-relative-time`** is the direct semantic source: `date`, `format`, `numeric`, `sync` and a locale, wrapping `Intl.RelativeTimeFormat` over a `<time>` element. **React Spectrum** has no relative-time component. **`<relative-time>`** (GitHub's element) is the widely-deployed reference and it _does_ tick.
+
+The differences, stated honestly:
+
+- **Web Awesome has `sync`, which auto-updates the phrase.** Pretui cannot — no timers — so `@now` is the caller's job. That is a real capability gap, imposed by the platform rather than chosen, and it is why the arg exists at all.
+- **Pretui has no locale arg.** `Intl.RelativeTimeFormat` is constructed with a hard-coded `'en-US'`. Web Awesome takes the element's `lang`. For an internationalised product this is disqualifying, and it is the same gap **Calendar** has.
+- **Pretui recomputes the formatter on every access.** `new Intl.RelativeTimeFormat(...)` inside the `phrase` getter means a table of 200 timestamps constructs 200 formatters per render. `Intl` constructors are not cheap; hoisting them into module-level constants (as this same file already does for `DISPLAY_FMT`, `LABEL_FMT`, `MONTH_FMT` and `ABS_FMT`) is a one-line fix and an inconsistency with the file's own practice.
+
+Where it is better than the naive version everyone writes: it uses `Intl.RelativeTimeFormat` rather than a hand-written pluralisation ladder, so "1 minute ago" versus "2 minutes ago" is the platform's problem, and it renders a real `<time>` element.
+
+## Accessibility
+
+No pattern governs it. The relevant criteria are WCAG **1.3.1** and, for the ticking question, **4.1.3**.
+
+What is right, and it is the important part:
+
+- **It renders `<time datetime="…">` with a full ISO 8601 timestamp.** So the machine-readable instant is always present even though the visible text is a phrase — which is exactly what `<time>` is for, and what a `<span>` version loses. Assistive tech, browsers and scrapers all get the real value.
+- **`title` carries the absolute formatted date** (`ABS_FMT`, medium date plus short time), so a pointer user can hover for the exact instant.
+- **Nothing ticks, so nothing announces repeatedly.** A live-updating relative time inside a live region is a notorious screen-reader nuisance; the no-timer constraint accidentally produces the polite behaviour.
+
+Gaps:
+
+- **`title` is the only route to the absolute time for most users.** It is not shown on touch, not reachable by keyboard, and announced inconsistently by screen readers. So for a keyboard or touch user, "3 days ago" is _all_ the information available. Where the exact instant matters, render it visibly rather than relying on `title`.
+- **Screen readers do not announce `datetime`.** The `<time>` element's machine value is not spoken; a screen-reader user hears the phrase, same as everyone else. The `datetime` attribute is for machines, not for assistive tech — a common misconception worth stating.
+- **A stale `@now` produces silently wrong output.** "2 minutes ago" on a page open for an hour is a factual error with no visual indication. This is the component's most consequential failure mode and it is the caller's to prevent.
+- **An invalid `@date` renders an empty string** — `phrase` returns `''` and `datetime` is `undefined`, so the element is empty. Nothing is announced, and nothing distinguishes it from a missing value.
+- **No locale support** (above) means non-English users see English phrases regardless of their settings.
+- `white-space: nowrap` prevents a phrase wrapping mid-way, which is right.
+
+## Theming
+
+Effectively none: `white-space: nowrap` and `font-variant-numeric: tabular-nums`. Ink, size and family are inherited from context — which is correct for something that appears inside **Timeline** rows, **Feed** articles and table cells, and should look like the text around it in each.
+
+The tabular figures are the one deliberate typographic choice: in a column of timestamps, "11 days ago" and "3 days ago" align on the same grid rather than jittering. A theme needs a font whose tabular figures actually differ from its proportional ones for that to have any effect.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

package/bundled-realms/pretui/components/relative-time.usage.gts

@@ -0,0 +1,89 @@
+// Pretui — RelativeTime usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { RelativeTime } from './relative-time';
+
+// ── RelativeTime — from webawesome's relative-time semantics ──────────────
+const RT_FORMAT_OPTIONS = ['long', 'short', 'narrow'];
+
+const RT_NUMERIC_OPTIONS = ['auto', 'always'];
+
+// Dropped knobs: sync (webawesome's auto-tick timer — the realm forbids
+// timers, so the phrase computes once from @date vs @now and @now is
+// caller-supplied per the LoadingState precedent), display (no absolute-date
+// fallback mode), lang (locale fixed to en-US like the rest of the kit).
+class RelativeTimeUsage extends GlimmerComponent {
+  @tracked date = '2026-08-11T09:30:00';
+  @tracked now = '2026-08-12T12:00:00';
+  @tracked format = 'long';
+  @tracked numeric = 'auto';
+  setDate = (v: string) => (this.date = v);
+  setNow = (v: string) => (this.now = v);
+  setFormat = (v: string) => (this.format = v);
+  setNumeric = (v: string) => (this.numeric = v);
+  get formatVal() {
+    return this.format as 'long' | 'short' | 'narrow';
+  }
+  get numericVal() {
+    return this.numeric as 'always' | 'auto';
+  }
+  get nowVal() {
+    return this.now || undefined;
+  }
+  get usage() {
+    return `<RelativeTime @date='${this.date}' @now='${this.now}' />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='RelativeTime'
+      @description='Displays a date as a human phrase relative to @now ("yesterday", "in 3 days") via Intl.RelativeTimeFormat, inside a <time> element carrying the ISO datetime and an absolute-date title. Computes once — it does not auto-tick in the realm (no timers); pass a fresh @now to update.'
+      @source={{this.usage}}
+      @viewportMode='inline'
+    >
+      <:example>
+        <RelativeTime
+          @date={{this.date}}
+          @now={{this.nowVal}}
+          @format={{this.formatVal}}
+          @numeric={{this.numericVal}}
+        />
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='date'
+          @required={{true}}
+          @description='The instant to describe — ISO datetime string (or a Date when invoked from code).'
+          @value={{this.date}}
+          @onInput={{this.setDate}}
+        />
+        <Args.String
+          @name='now'
+          @description='The reference instant — caller-supplied (LoadingState precedent). Omitted, it captures the construction instant and never ticks.'
+          @value={{this.now}}
+          @onInput={{this.setNow}}
+        />
+        <Args.String
+          @name='format'
+          @description="Intl.RelativeTimeFormat style: 'long' (3 days ago), 'short' (3 days ago, abbreviated units), or 'narrow' (3d ago)."
+          @options={{RT_FORMAT_OPTIONS}}
+          @defaultValue='long'
+          @value={{this.format}}
+          @onInput={{this.setFormat}}
+        />
+        <Args.String
+          @name='numeric'
+          @description="'auto' allows phrases like 'yesterday'; 'always' forces '1 day ago'."
+          @options={{RT_NUMERIC_OPTIONS}}
+          @defaultValue='auto'
+          @value={{this.numeric}}
+          @onInput={{this.setNumeric}}
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_RELATIVE_TIME: Record<string, unknown> = {
+  RelativeTime: RelativeTimeUsage,
+};