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

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

@@ -0,0 +1,56 @@
+## What it is
+
+A date the reader already knows — a birthday, an issue date, an expiry — typed into three boxes rather than browsed in a calendar.
+
+Nobody scrolls back forty years to find their own birthday. This is not a second date control: **DatePicker** and **Calendar** are for a date you are _choosing_; this is for one you are _recalling_.
+
+## The contract
+
+```
+@value?      — the INITIAL date, YYYY-MM-DD
+@onChange?   — fires on every keystroke with the ISO date, or undefined while the
+               three boxes do not yet describe a real date; the second argument
+               carries the reason
+@label?      — the fieldset's legend
+@hint?       — example copy under the boxes, associated with all three
+@reference?  — the instant relative phrasing and two-digit years are measured against
+@min?, @max? — earliest and latest accepted dates, YYYY-MM-DD
+@disabled?
+@locale?     — BCP-47 tag deciding field ORDER and month vocabulary
+@quiet?      — suppress the echoed confirmation line
+```
+
+**`@value` seeds and then stops mattering.** The component owns the three boxes after mount and reports through `@onChange`; re-key it to seed again. That is named in the contract rather than hidden, because a re-seeding control would have to write tracked state from a modifier during render — a backtracking re-render waiting to happen.
+
+**Nothing here reads the clock.** `@reference` is how relative phrasing and two-digit-year expansion get an "now" — omit it and no relative phrase is shown at all. Realm code may not read the clock, so the app passes its own.
+
+**Parsing is deliberately permissive.** `3`, `mar` or `March` all work in the month box; `90` works in the year box; a whole date pasted into any one of them is distributed across all three.
+
+**`@onChange` reports `undefined` with a reason while the boxes do not describe a real date**, so a form decides when to show the problem rather than the component deciding for it.
+
+**`@locale` moves the field order and the month vocabulary only.** The labels stay in the interface language.
+
+## Prior art
+
+**`wa-known-date`.**
+
+Where Pretui is better: the reason accompanying an incomplete value, so a form can distinguish "not finished" from "wrong"; the clock-free design, which is a realm requirement and also makes the component deterministic in a test; and locale affecting order without dragging the interface language with it.
+
+Where it is thinner: no calendar fallback for a reader who would rather browse, no era or non-Gregorian calendars, and no partial dates — a month and year without a day is a real thing to want for an expiry, and this cannot express it.
+
+## Accessibility
+
+- **The three boxes are a `fieldset` with a legend from `@label`**, so they are announced as one field with three parts rather than as three unrelated inputs.
+- **`@hint` is associated with all three boxes** through `aria-describedby`, not just the first.
+- **The verdict line is a polite `role='status'` live region.** It echoes what was understood — "3 March 1990" — which is the affordance that makes permissive parsing safe: the reader can see that `mar` and `90` became what they meant.
+- **`@quiet` suppresses that echo**, and should be used only when the surrounding form shows the same confirmation.
+- **Relative phrasing depends on `@reference`.** Without it there is no "34 years ago", which is a loss for comprehension but never a loss of the value itself.
+- **Errors are reported through `@onChange`'s reason rather than rendered**, so the form owns the message and its placement.
+
+## Theming
+
+`--pretui-knowndate-day-width`, `--pretui-knowndate-month-width` and `--pretui-knowndate-year-width` size the three boxes independently, and `--pretui-destructive-ink` carries the invalid state.
+
+Three separate width tokens rather than one is the point: a month box wide enough for "September" and a day box wide enough for "31" are very different, and a theme that sets them together produces either a cramped month or three boxes of wasted space.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

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

@@ -0,0 +1,192 @@
+// Pretui — KnownDate usage page.
+//
+// The reference instant is a KNOB, not the clock, which is the point of the
+// page as much as of the component: move it and the relative phrase moves
+// with it, deterministically, on every render and in every index pass. A
+// component that read Date.now() could not have this page at all.
+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 { KnownDate } from './known-date';
+import type { KnownDateResult } from './known-date';
+
+export class KnownDateUsage extends Component {
+  @tracked label = 'When was the lot harvested?';
+  @tracked hint = 'For example, 27 3 2007 — or paste 2007-03-27 into any box';
+  @tracked locale = 'en-GB';
+  @tracked reference = '2026-08-13';
+  @tracked min = '1900-01-01';
+  @tracked max = '2099-12-31';
+  @tracked seed = '1990-04-15';
+  @tracked quiet = false;
+  @tracked emitted = 'Nothing emitted yet.';
+  @tracked run = 0;
+
+  setLabel = (v: string) => (this.label = v);
+  setHint = (v: string) => (this.hint = v);
+  setLocale = (v: string) => (this.locale = v);
+  setReference = (v: string) => (this.reference = v);
+  setMin = (v: string) => (this.min = v);
+  setMax = (v: string) => (this.max = v);
+  setSeed = (v: string) => (this.seed = v);
+  setQuiet = (v: boolean) => (this.quiet = v);
+
+  onChange = (iso: string | undefined, result: KnownDateResult) => {
+    if (iso) {
+      this.emitted = 'onChange with ' + iso;
+    } else if (result.empty) {
+      this.emitted = 'onChange with undefined — the boxes are empty.';
+    } else {
+      this.emitted = 'onChange with undefined — ' + (result.issue ?? '');
+    }
+  };
+
+  /** KnownDate owns its three boxes after mount (see its signature note), so
+   * re-seeding is a re-mount — an identity-keyed single-item list, which is
+   * the timer-free replay pattern the motion demos established. */
+  reseed = () => (this.run = this.run + 1);
+  get runKey(): number[] {
+    return [this.run];
+  }
+  get localeOptions(): string[] {
+    return ['en-GB', 'en-US', 'ja-JP', 'de-DE', 'sv-SE'];
+  }
+
+  get usage(): string {
+    return (
+      '<KnownDate @label=' + "'" + this.label + "'" +
+      " @locale='" + this.locale + "'" +
+      " @reference='" + this.reference + "'" +
+      ' @onChange={{this.take}} />'
+    );
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='KnownDate'
+      @description='A date the reader already knows — a birthday, an issue date, an expiry — typed into three boxes rather than browsed in a calendar. Nobody scrolls back forty years to find their own birthday. This is not a second date control: DatePicker and Calendar are for a date you are CHOOSING. Try 3 or mar or March in the month box, 90 in the year box, or paste a whole date into any one of them.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='pretui-kd-demo'>
+          {{#each this.runKey key='@identity' as |run|}}
+            <KnownDate
+              @label={{this.label}}
+              @hint={{this.hint}}
+              @locale={{this.locale}}
+              @reference={{this.reference}}
+              @value={{this.seed}}
+              @min={{this.min}}
+              @max={{this.max}}
+              @quiet={{this.quiet}}
+              @onChange={{this.onChange}}
+              data-run={{run}}
+            />
+          {{/each}}
+          <p class='pretui-kd-demo-note'>{{this.emitted}}</p>
+          <Button
+            @size='xs'
+            @appearance='outlined'
+            data-test-pretui-known-date-reseed
+            {{on 'click' this.reseed}}
+          >Re-seed from value</Button>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='value'
+          @value={{this.seed}}
+          @description='The INITIAL date, YYYY-MM-DD. The component owns the three boxes after mount and reports through onChange; re-key it to seed it again.'
+          @onInput={{this.setSeed}}
+        />
+        <Args.String
+          @name='reference'
+          @value={{this.reference}}
+          @description='The instant the relative phrase and two-digit years are measured against. Omit it and no relative phrase is shown — nothing here ever reads the clock, because Date.now would make the card index differently every time.'
+          @onInput={{this.setReference}}
+        />
+        <Args.String
+          @name='label'
+          @value={{this.label}}
+          @defaultValue='Date'
+          @description='The fieldset legend.'
+          @onInput={{this.setLabel}}
+        />
+        <Args.String
+          @name='hint'
+          @value={{this.hint}}
+          @description='Example copy under the boxes, associated with all three.'
+          @onInput={{this.setHint}}
+        />
+        <Args.String
+          @name='locale'
+          @value={{this.locale}}
+          @defaultValue='en-US'
+          @options={{this.localeOptions}}
+          @description='Decides the field ORDER and the month vocabulary, asked of Intl rather than kept as a table. Labels stay in the interface language; only the order moves.'
+          @onInput={{this.setLocale}}
+        />
+        <Args.String
+          @name='min'
+          @value={{this.min}}
+          @description='Earliest accepted date, YYYY-MM-DD. Compared as a string, so no time zone can knock the check off by a day.'
+          @onInput={{this.setMin}}
+        />
+        <Args.String
+          @name='max'
+          @value={{this.max}}
+          @description='Latest accepted date, YYYY-MM-DD.'
+          @onInput={{this.setMax}}
+        />
+        <Args.Bool
+          @name='quiet'
+          @value={{this.quiet}}
+          @defaultValue={{false}}
+          @description='Suppress the echoed confirmation line. Leave it on: the echo is how a transcription error gets caught before the form is submitted.'
+          @onInput={{this.setQuiet}}
+        />
+        <Args.Action
+          @name='onChange'
+          @description='Fires on every keystroke with the ISO date, or undefined while the boxes do not yet describe a real date. The second argument carries the reason.'
+        />
+      </:api>
+      <:cssVars as |Css|>
+        <Css.Basic
+          @name='pretui-knowndate-day-width'
+          @type='dimension'
+          @description='Width of the day box.'
+        />
+        <Css.Basic
+          @name='pretui-knowndate-month-width'
+          @type='dimension'
+          @description='Width of the month box — wider than the others because it takes names as well as numbers.'
+        />
+        <Css.Basic
+          @name='pretui-knowndate-year-width'
+          @type='dimension'
+          @description='Width of the year box.'
+        />
+      </:cssVars>
+    </FreestyleUsage>
+    <style scoped>
+      .pretui-kd-demo {
+        display: grid;
+        gap: var(--space-3, 8px);
+        justify-items: start;
+        max-width: 460px;
+      }
+      .pretui-kd-demo-note {
+        margin: 0;
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-sm, 11.5px);
+        color: var(--muted-foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_KNOWN_DATE: Record<string, unknown> = {
+  KnownDate: KnownDateUsage,
+};

package/bundled-realms/pretui/components/label.gts

@@ -0,0 +1,60 @@
+// Pretui — Label: the field eyebrow, as label, span or legend.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+
+// Fresh, tiny. Ported semantics from boxel-ui label/index.gts (tag
+// polymorphism + default block), re-voiced as the Pretui field eyebrow:
+// small-caps mono, the same voice as PropRow labels and table headers.
+// boxel-ui's `(element @tag)` helper becomes simple if branches over the
+// three tags a form label actually takes.
+
+export type PretuiLabelTag = 'label' | 'span' | 'legend';
+
+function isTag(tag: string | undefined, t: string): boolean {
+  return tag === t;
+}
+
+export interface LabelSignature {
+  Args: {
+    tag?: PretuiLabelTag;
+    /** id of the control this label points at (label tag only) */
+    for?: string;
+  };
+  Blocks: { default: [] };
+  Element: HTMLElement;
+}
+
+export const Label: TemplateOnlyComponent<LabelSignature> = <template>
+  {{#if (isTag @tag 'legend')}}
+    <legend class='pretui-label' data-test-pretui-label ...attributes>
+      {{yield}}
+    </legend>
+  {{else if (isTag @tag 'span')}}
+    <span class='pretui-label' data-test-pretui-label ...attributes>
+      {{yield}}
+    </span>
+  {{else}}
+    <label
+      class='pretui-label'
+      for={{@for}}
+      data-test-pretui-label
+      ...attributes
+    >
+      {{yield}}
+    </label>
+  {{/if}}
+  <style scoped>
+    @layer PretComponent {
+      .pretui-label {
+        display: inline-block;
+        padding: 0;
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        font-weight: 500;
+        line-height: 16px;
+        letter-spacing: var(--track-eyebrow, 0.08em);
+        text-transform: uppercase;
+        color: var(--muted-foreground);
+      }
+    }
+  </style>
+</template>;

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

@@ -0,0 +1,56 @@
+## What it is
+
+The kit's field-label voice, as a component: small-caps mono in `--muted-foreground`, the same treatment as **Panel**'s eyebrow, **DataGrid**'s column headers and **FormField**'s labels. Use it when you need that voice with the _right element_ — a `<label>` bound to a control, a `<legend>` for a fieldset, or a `<span>` for a caption with nothing to point at. If you are labelling a control inside a form, you almost certainly want **FormField**, which uses this internally and also owns the id wiring; reach for `Label` directly only when composing something the form territory does not cover.
+
+## The contract
+
+```
+@tag? 'label' | 'span' | 'legend'   (default 'label')
+@for?   — id of the control (label tag only)
+<:default>
+Element: HTMLElement
+```
+
+**Tag polymorphism is the whole component.** The three tags are the three a form label actually takes: `<label for>` for a real control, `<legend>` for a fieldset's group name, and `<span>` for a static display where there is nothing to bind to — which is exactly the `@static` case in **FormField**. Choosing the element rather than always emitting a `<label>` matters: a `<label>` with no `for` and no wrapped control is a lie that passes review, and a group name inside a `<div>` is not announced when you enter the group.
+
+The implementation is deliberately three `if` branches rather than a dynamic-element helper. boxel-ui uses `(element @tag)`; Pretui enumerates, because there are exactly three valid tags and a closed set catches a typo at the type level rather than emitting `<lable>`.
+
+## Prior art
+
+**Radix `Label`** wraps `@radix-ui/react-label` and does one thing beyond a native label: it **prevents text selection on double-click**, since double-clicking a label to select its text is almost never what a user wanted next to a checkbox. **Web Awesome** has no label component at all — every control owns a `label` prop _and_ a `label` slot, with a `with-label` boolean for SSR slot detection. **React Aria `useField`** returns `labelProps` rather than a component, leaving the element to you. **shadcn** wraps Radix.
+
+Pretui's tag polymorphism is the differentiator, and it comes from a real need: **FormField** renders the same visual label as a `<label for>` when editable and a `<span>` when static, and without a tag arg that would be two copies of the styling.
+
+Where Pretui is behind Radix: **no double-click selection guard.** That is a genuinely good detail and it is one line.
+
+Where it is behind Web Awesome's approach: nothing structural — Web Awesome's per-control labels are a different architecture (each control owns its label) with its own costs, and Pretui's separation of label from control is the more composable choice. But note the consequence: **a Label does not know whether its target exists.** `@for` pointing at a nonexistent id is silently broken, which is exactly the hole **Field** has with `RadioGroup` and `Slider`.
+
+## Accessibility
+
+No APG pattern; this is the wiring layer, governed by WCAG **1.3.1**, **3.3.2 Labels or Instructions** and **4.1.2**.
+
+What is right: the three tags are the three correct elements, and `<legend>` in particular is available — most kits force you to reconstruct a group name with `aria-label`, which is less reliably announced than a real legend.
+
+Gaps:
+
+- **`@for` is not validated and not required.** A `<label>` with no `for` and no wrapped control has no association at all, and nothing warns. This is the most common way labels silently fail, and the component makes it easy — `@tag` defaults to `'label'`, so the _default_ usage is the one that needs `@for`.
+- **`text-transform: uppercase` is a styling transform, not a content change**, so screen readers announce the underlying text — "Approver email", not "A P P R O V E R". That is correct. But note some readers spell out short all-caps _source_ strings, so keep the authored text in normal case and let CSS do the uppercasing, which this component's styling assumes.
+- **11px at `--muted-foreground` with 0.08em tracking** is the kit's quietest label voice. Uppercase text at that size is measurably slower to read and harder for users with low vision — the tracking mitigates it, and it is a deliberate typographic choice, but it is at the edge of **WCAG 1.4.3** for `--muted-foreground` on `--card` and should be checked per theme.
+- **No required-indicator support.** **FormField** adds a visually-hidden "(required)" inside the label; a bare `Label` has no equivalent, so composing your own required field means reimplementing that.
+- **No `aria-hidden` or decorative mode**, so a Label used purely as a visual caption still announces.
+- Nothing is focusable; clicking a correctly-wired `<label>` focuses its control, which is the platform's behaviour and is preserved.
+
+## Theming
+
+`--font-mono`, `--text-ui-xs` (11px), `--track-eyebrow` (0.08em), `--muted-foreground`. Weight 500 and `line-height: 16px` are fixed.
+
+Four tokens, and they are the same four that define the eyebrow voice in **Panel**, **Toolbar**, **DataGrid** and **FormField** — so a theme retuning `--track-eyebrow` or `--text-ui-xs` moves all of them together, which is the intent. That coupling is the reason this exists as a component rather than as a utility class: there is one definition of what a label sounds like.
+
+The `line-height: 16px` is a fixed pixel value rather than a ratio, so a theme that scales `--text-ui-xs` up will get labels that clip or crowd. Worth changing to a unitless ratio.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+shadcn/Radix/Aria `Label`. Keep the small-caps Pretui voice. Must
+point at a control (`for` / `aria-labelledby`) — never a lone `<div>`.

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

@@ -0,0 +1,63 @@
+// Pretui — Label usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { Label } from './label';
+
+const LABEL_TAGS = ['label', 'span', 'legend'];
+
+// ── Label ← label/index.gts (no upstream usage page) ─────────────────────
+// Dropped knobs: @size ('small' | 'default' — the Pretui Label is a
+// single-size mono eyebrow; sizing rides the token sheet), @ellipsize (no
+// truncation variant in wave-0), free @tag (keyof HTMLElementTagNameMap —
+// narrowed to the three tags a field label actually takes).
+class LabelUsage extends Component {
+  tagOptions = LABEL_TAGS;
+  @tracked tag = 'label';
+  @tracked text = 'Card number';
+  setTag = (v: string) => (this.tag = v);
+  setText = (v: string) => (this.text = v);
+  get tagVal() {
+    return this.tag as 'label' | 'span' | 'legend';
+  }
+  get usage() {
+    let tagBit = this.tag === 'label' ? '' : ` @tag='${this.tag}'`;
+    return `<Label${tagBit}>${this.text}</Label>`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Label'
+      @description='Small-caps mono field label — the eyebrow voice shared by property rows and table headers. Renders as label, span, or legend.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <Label @tag={{this.tagVal}}>{{this.text}}</Label>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='tag'
+          @defaultValue='label'
+          @value={{this.tag}}
+          @options={{this.tagOptions}}
+          @description="Element to render — boxel-ui's free keyof HTMLElementTagNameMap, narrowed to label / span / legend."
+          @onInput={{this.setTag}}
+        />
+        <Args.String
+          @name='for'
+          @description='id of the control this label points at (label tag only).'
+        />
+        <Args.String
+          @name='text'
+          @value={{this.text}}
+          @description='Demo knob for the default block content.'
+          @onInput={{this.setText}}
+        />
+        <Args.Yield @description='Label content as the default block.' />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_LABEL: Record<string, unknown> = {
+  Label: LabelUsage,
+};