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

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

@@ -0,0 +1,159 @@
+// Pretui — Button usage page. The freestyle contract for the catalog tile:
+// live example, knobs for every arg, and the API table the kit teaches from.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { BUTTON_SHAPES, Button } from './button';
+import type { ButtonShape } from './button';
+import {
+  PRETUI_APPEARANCES,
+  PRETUI_SIZES,
+  PRETUI_TONES,
+} from '../pretui-primitives';
+import type {
+  PretuiAppearance,
+  PretuiSize,
+  PretuiTone,
+} from '../pretui-primitives';
+
+// Spread the published vocabulary rather than restating it: Freestyle's
+// @options takes a mutable string[], and a hand-written copy silently omits
+// any axis value added later.
+const TONES = [...PRETUI_TONES];
+const APPEARANCES = [...PRETUI_APPEARANCES];
+const SIZES = [...PRETUI_SIZES];
+const SHAPES = [...BUTTON_SHAPES];
+
+export class ButtonUsage extends GlimmerComponent {
+  @tracked tone = 'primary';
+  @tracked appearance = 'accent';
+  @tracked size = 'm';
+  @tracked busy = false;
+  @tracked busyLabel = '';
+  @tracked disabled = false;
+  @tracked href = '';
+  @tracked shape = 'rounded';
+  setTone = (v: string) => (this.tone = v);
+  setAppearance = (v: string) => (this.appearance = v);
+  setSize = (v: string) => (this.size = v);
+  setBusy = (v: boolean) => (this.busy = v);
+  setBusyLabel = (v: string) => (this.busyLabel = v);
+  setDisabled = (v: boolean) => (this.disabled = v);
+  setHref = (v: string) => (this.href = v);
+  setShape = (v: string) => (this.shape = v);
+  get toneVal() {
+    return this.tone as PretuiTone;
+  }
+  get appearanceVal() {
+    return this.appearance as PretuiAppearance;
+  }
+  get hrefVal() {
+    return this.href || undefined;
+  }
+  get shapeVal() {
+    return this.shape as ButtonShape;
+  }
+  get sizeVal() {
+    return this.size as PretuiSize;
+  }
+  get usage() {
+    let bits = [`@tone='${this.tone}'`, `@appearance='${this.appearance}'`];
+    if (this.size !== 'm') bits.push(`@size='${this.size}'`);
+    if (this.busy) bits.push('@busy={{true}}');
+    if (this.busyLabel) bits.push(`@busyLabel='${this.busyLabel}'`);
+    if (this.disabled) bits.push('@disabled={{true}}');
+    if (this.href) bits.push(`@href='${this.href}'`);
+    if (this.shape !== 'rounded') bits.push(`@shape='${this.shape}'`);
+    return `<Button ${bits.join(' ')}>Keep selling</Button>`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='Button'
+      @description='Interactive button for actions and form submission. The boxel-ui @kind axis is re-cut as the two-axis treatment grid: @tone picks the hue, @appearance picks the recipe. Renders a native button, or a native link with @href; the boxel-ui LinkTo mode is host-router coupling and stays behind.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <Button
+          @tone={{this.toneVal}}
+          @appearance={{this.appearanceVal}}
+          @size={{this.sizeVal}}
+          @busy={{this.busy}}
+          @busyLabel={{this.busyLabel}}
+          @disabled={{this.disabled}}
+          @href={{this.hrefVal}}
+          @shape={{this.shapeVal}}
+        >Keep selling</Button>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='tone'
+          @value={{this.tone}}
+          @options={{TONES}}
+          @defaultValue='primary'
+          @description='Semantic color — WHY the element is colored. Sets --pretui-tone/--pretui-tone-on from theme tokens.'
+          @onInput={{this.setTone}}
+        />
+        <Args.String
+          @name='appearance'
+          @value={{this.appearance}}
+          @options={{APPEARANCES}}
+          @defaultValue='accent'
+          @description='Visual weight — HOW loud. One recipe per appearance, written once, reading the tone variables.'
+          @onInput={{this.setAppearance}}
+        />
+        <Args.String
+          @name='size'
+          @value={{this.size}}
+          @options={{SIZES}}
+          @defaultValue='m'
+          @description='Sets only the host font-size; every internal dimension rides the em (webawesome scaling). m is 28px-high.'
+          @onInput={{this.setSize}}
+        />
+        <Args.Bool
+          @name='busy'
+          @value={{this.busy}}
+          @defaultValue={{false}}
+          @description='Swaps the label for a spinner while an action runs, at the same width. Presses are ignored, but the button keeps focus (aria-disabled, not disabled).'
+          @onInput={{this.setBusy}}
+        />
+        <Args.String
+          @name='busyLabel'
+          @value={{this.busyLabel}}
+          @description='Shown next to the spinner while busy when it fits in the button, and always added to the accessible name. Set it when the visible label does not already say the button is busy.'
+          @onInput={{this.setBusyLabel}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @value={{this.disabled}}
+          @defaultValue={{false}}
+          @description='Disables the button.'
+          @onInput={{this.setDisabled}}
+        />
+        <Args.String
+          @name='href'
+          @value={{this.href}}
+          @description='Renders a real link (an <a>) with the same look. A disabled link drops its href; @busy does not apply.'
+          @onInput={{this.setHref}}
+        />
+        <Args.String
+          @name='shape'
+          @value={{this.shape}}
+          @options={{SHAPES}}
+          @defaultValue='rounded'
+          @description="Corner treatment. rounded is the theme's --radius less 2px; --pretui-button-radius overrides any shape per instance."
+          @onInput={{this.setShape}}
+        />
+        <Args.Base
+          @name='variant'
+          @typeLabel='String'
+          @description='Deprecated sugar over @tone + @appearance: primary→primary/accent, secondary→neutral/outlined, ghost→neutral/plain, destructive→danger/accent.'
+          @hideControls={{true}}
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_BUTTON: Record<string, unknown> = {
+  Button: ButtonUsage,
+};

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

@@ -0,0 +1,457 @@
+// Pretui — Calendar: the month grid every date control in the kit shares.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { fn } from '@ember/helper';
+import { focusWhen, rovingTabindex } from '../focus';
+import { LABEL_FMT, MONTH_FMT, fromIso, toIso } from '../internal/reading-extras';
+
+// ── Calendar ─────────────────────────────────────────────────────────────
+// THE Pretui date surface: one month-grid calendar shared by DatePicker and
+// DateRangePicker so the kit has exactly one calendar implementation.
+// Focus follows the arrow keys via a roving tabindex: the modifier focuses a
+// day button only when it just became the keyboard target (navigating flag —
+// never steals focus on plain renders).
+// (Both primitives live in focus.gts, the kit's single focus/keyboard
+// foundation.)
+
+interface DayCell {
+  iso: string;
+  day: number;
+  outside: boolean;
+  label: string;
+}
+
+interface CalendarPanel {
+  key: string;
+  label: string;
+  cells: DayCell[];
+}
+
+const WEEKDAYS = ['Su', 'Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa'];
+
+export interface DateRangeValue {
+  start?: string | null;
+  end?: string | null;
+}
+
+export interface CalendarSignature {
+  Args: {
+    mode?: 'single' | 'range'; // default 'single'
+    value?: string; // single: ISO yyyy-mm-dd (controlled)
+    defaultValue?: string; // single: uncontrolled seed
+    onValueChange?: (iso: string) => void; // single: day picked
+    range?: DateRangeValue; // range: controlled { start, end }
+    defaultRange?: DateRangeValue; // range: uncontrolled seed
+    onRangeChange?: (range: {
+      start: string | null;
+      end: string | null;
+    }) => void; // range: fires on both clicks (end null after the first)
+    months?: number; // panels side by side (default 1); narrow containers collapse to the first
+    minDate?: string; // ISO yyyy-mm-dd — earlier days disabled
+    maxDate?: string; // ISO yyyy-mm-dd — later days disabled
+    disabled?: boolean; // every day disabled
+  };
+  Element: HTMLDivElement;
+}
+
+// Range semantics: first click sets start (end null), second completes —
+// swapped when picked in reverse. While the end is unset the prospective
+// span paints from the hovered day (or the keyboard focus when arrowing).
+// Day state is reflected as data-* attributes: data-selected (single),
+// data-range-start / data-range-end / data-in-range (range), data-today,
+// data-outside. ISO yyyy-mm-dd strings at every boundary — they compare
+// lexicographically, so the range math needs no Date objects.
+export class Calendar extends Component<CalendarSignature> {
+  private initDate =
+    fromIso(
+      this.args.value ??
+        this.args.defaultValue ??
+        this.args.range?.start ??
+        this.args.defaultRange?.start ??
+        this.args.range?.end ??
+        this.args.defaultRange?.end ??
+        '',
+    ) ?? new Date();
+  private todayIso = toIso(new Date());
+  @tracked internalValue: string | undefined = this.args.defaultValue;
+  @tracked internalRange: DateRangeValue | undefined = this.args.defaultRange;
+  @tracked viewYear = this.initDate.getFullYear();
+  @tracked viewMonth = this.initDate.getMonth();
+  @tracked focusIso = toIso(this.initDate);
+  @tracked navigating = false;
+  @tracked hoverIso: string | undefined;
+
+  weekdays = WEEKDAYS;
+
+  get mode(): 'single' | 'range' {
+    return this.args.mode ?? 'single';
+  }
+  get monthCount(): number {
+    return Math.max(1, Math.floor(this.args.months ?? 1));
+  }
+  get isMulti(): boolean {
+    return this.monthCount > 1;
+  }
+  get selectedIso(): string | undefined {
+    return this.args.value ?? this.internalValue;
+  }
+  get rangeValue(): DateRangeValue {
+    return this.args.range ?? this.internalRange ?? {};
+  }
+  get firstIso(): string {
+    return toIso(new Date(this.viewYear, this.viewMonth, 1));
+  }
+  get lastIso(): string {
+    return toIso(new Date(this.viewYear, this.viewMonth + this.monthCount, 0));
+  }
+  get panels(): CalendarPanel[] {
+    let out: CalendarPanel[] = [];
+    for (let p = 0; p < this.monthCount; p++) {
+      let first = new Date(this.viewYear, this.viewMonth + p, 1);
+      let y = first.getFullYear();
+      let m = first.getMonth();
+      let startOffset = first.getDay();
+      let cells: DayCell[] = [];
+      for (let i = 0; i < 42; i++) {
+        let d = new Date(y, m, 1 - startOffset + i);
+        cells.push({
+          iso: toIso(d),
+          day: d.getDate(),
+          outside: d.getMonth() !== m,
+          label: LABEL_FMT.format(d),
+        });
+      }
+      out.push({ key: `${y}-${m}`, label: MONTH_FMT.format(first), cells });
+    }
+    return out;
+  }
+  get rovingIso(): string {
+    let f = this.focusIso;
+    return f >= this.firstIso && f <= this.lastIso ? f : this.firstIso;
+  }
+  // Committed range, or the prospective span while the end is unset — the
+  // probe is the hovered day, falling back to the keyboard focus target.
+  get paint(): { start?: string; end?: string } {
+    if (this.mode !== 'range') {
+      return {};
+    }
+    let { start, end } = this.rangeValue;
+    if (start && end) {
+      return { start, end };
+    }
+    if (start) {
+      let probe =
+        this.hoverIso ?? (this.navigating ? this.focusIso : undefined);
+      if (probe && probe !== start) {
+        return probe < start
+          ? { start: probe, end: start }
+          : { start, end: probe };
+      }
+      return { start, end: start };
+    }
+    return {};
+  }
+
+  isSelected = (cell: DayCell): boolean =>
+    this.mode === 'single' && cell.iso === this.selectedIso;
+  isRangeStart = (cell: DayCell): boolean => cell.iso === this.paint.start;
+  isRangeEnd = (cell: DayCell): boolean => cell.iso === this.paint.end;
+  isInRange = (cell: DayCell): boolean => {
+    let { start, end } = this.paint;
+    return !!start && !!end && cell.iso > start && cell.iso < end;
+  };
+  isToday = (cell: DayCell): boolean => cell.iso === this.todayIso;
+  isPressed = (cell: DayCell): boolean =>
+    this.isSelected(cell) || this.isRangeStart(cell) || this.isRangeEnd(cell);
+  isDisabled = (cell: DayCell): boolean =>
+    this.args.disabled === true ||
+    (this.args.minDate !== undefined && cell.iso < this.args.minDate) ||
+    (this.args.maxDate !== undefined && cell.iso > this.args.maxDate);
+  isRovingTarget = (cell: DayCell): boolean =>
+    this.navigating && !cell.outside && cell.iso === this.focusIso;
+  isRoving = (cell: DayCell): boolean =>
+    !cell.outside && cell.iso === this.rovingIso;
+
+  setView = (d: Date) => {
+    this.viewYear = d.getFullYear();
+    this.viewMonth = d.getMonth();
+  };
+  // Keep d visible: scroll the view back for earlier dates, forward (keeping
+  // d in the LAST panel) for later ones.
+  setViewToInclude = (d: Date) => {
+    let iso = toIso(d);
+    if (iso < this.firstIso) {
+      this.setView(d);
+    } else if (iso > this.lastIso) {
+      this.setView(
+        new Date(d.getFullYear(), d.getMonth() - (this.monthCount - 1), 1),
+      );
+    }
+  };
+  prevMonth = () => {
+    this.setView(new Date(this.viewYear, this.viewMonth - 1, 1));
+  };
+  nextMonth = () => {
+    this.setView(new Date(this.viewYear, this.viewMonth + 1, 1));
+  };
+  onDayKeydown = (e: Event) => {
+    let key = (e as KeyboardEvent).key;
+    let delta =
+      key === 'ArrowLeft'
+        ? -1
+        : key === 'ArrowRight'
+          ? 1
+          : key === 'ArrowUp'
+            ? -7
+            : key === 'ArrowDown'
+              ? 7
+              : 0;
+    if (!delta) {
+      return;
+    }
+    e.preventDefault();
+    let d = fromIso(this.focusIso);
+    if (!d) {
+      return;
+    }
+    d.setDate(d.getDate() + delta);
+    let iso = toIso(d);
+    if (this.args.minDate !== undefined && iso < this.args.minDate) {
+      return;
+    }
+    if (this.args.maxDate !== undefined && iso > this.args.maxDate) {
+      return;
+    }
+    this.navigating = true;
+    this.focusIso = iso;
+    this.setViewToInclude(d);
+  };
+  hoverDay = (cell: DayCell) => {
+    this.hoverIso = cell.iso;
+  };
+  clearHover = () => {
+    this.hoverIso = undefined;
+  };
+  pick = (cell: DayCell) => {
+    this.focusIso = cell.iso;
+    let d = fromIso(cell.iso);
+    if (d) {
+      this.setViewToInclude(d);
+    }
+    if (this.mode === 'range') {
+      let { start, end } = this.rangeValue;
+      let next: { start: string | null; end: string | null };
+      if (!start || end) {
+        next = { start: cell.iso, end: null };
+      } else if (cell.iso < start) {
+        next = { start: cell.iso, end: start };
+      } else {
+        next = { start, end: cell.iso };
+      }
+      this.internalRange = next;
+      this.args.onRangeChange?.(next);
+    } else {
+      this.internalValue = cell.iso;
+      this.args.onValueChange?.(cell.iso);
+    }
+  };
+
+  <template>
+    <div
+      class='pretui-calendar'
+      data-mode={{this.mode}}
+      data-multi={{if this.isMulti 'true'}}
+      data-test-pretui-calendar
+      ...attributes
+    >
+      <div class='pretui-cal-panels' {{on 'pointerleave' this.clearHover}}>
+        {{#each this.panels key='key' as |panel|}}
+          <div class='pretui-cal-panel'>
+            <div class='pretui-cal-head'>
+              <button
+                type='button'
+                class='pretui-cal-nav'
+                data-dir='prev'
+                aria-label='Previous month'
+                {{on 'click' this.prevMonth}}
+              >‹</button>
+              <span class='pretui-cal-month'>{{panel.label}}</span>
+              <button
+                type='button'
+                class='pretui-cal-nav'
+                data-dir='next'
+                aria-label='Next month'
+                {{on 'click' this.nextMonth}}
+              >›</button>
+            </div>
+            <div class='pretui-cal-weekdays'>
+              {{#each this.weekdays as |w|}}
+                <span class='pretui-cal-weekday'>{{w}}</span>
+              {{/each}}
+            </div>
+            <div class='pretui-cal-grid'>
+              {{#each panel.cells key='iso' as |cell|}}
+                <button
+                  type='button'
+                  class='pretui-cal-day'
+                  disabled={{if (this.isDisabled cell) true}}
+                  data-outside={{if cell.outside 'true'}}
+                  data-selected={{if (this.isSelected cell) 'true'}}
+                  data-range-start={{if (this.isRangeStart cell) 'true'}}
+                  data-range-end={{if (this.isRangeEnd cell) 'true'}}
+                  data-in-range={{if (this.isInRange cell) 'true'}}
+                  data-today={{if (this.isToday cell) 'true'}}
+                  aria-label={{cell.label}}
+                  aria-pressed={{if (this.isPressed cell) 'true' 'false'}}
+                  {{rovingTabindex (this.isRoving cell)}}
+                  {{focusWhen (this.isRovingTarget cell)}}
+                  {{on 'click' (fn this.pick cell)}}
+                  {{on 'pointerenter' (fn this.hoverDay cell)}}
+                  {{on 'keydown' this.onDayKeydown}}
+                >{{cell.day}}</button>
+              {{/each}}
+            </div>
+          </div>
+        {{/each}}
+      </div>
+    </div>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-calendar {
+          /* inline-size container so panels can collapse under narrow hosts;
+             containment means width comes from the parent, not the grid —
+             hosts (or popover panels) give the calendar an explicit width */
+          container-type: inline-size;
+          width: 100%;
+        }
+        .pretui-cal-panels {
+          display: flex;
+          flex-wrap: wrap;
+          align-items: flex-start;
+          gap: var(--space-5, 14px);
+        }
+        .pretui-cal-panel {
+          display: grid;
+          gap: var(--space-3, 8px);
+        }
+        .pretui-cal-head {
+          display: flex;
+          align-items: center;
+          justify-content: space-between;
+          gap: var(--space-3, 8px);
+        }
+        .pretui-cal-month {
+          font-family: var(--font-mono);
+          font-size: var(--text-ui-xs, 11px);
+          font-weight: 500;
+          letter-spacing: var(--track-eyebrow, 0.08em);
+          text-transform: uppercase;
+          color: var(--foreground);
+        }
+        .pretui-cal-nav {
+          width: 24px;
+          height: 24px;
+          border: 0;
+          padding: 0;
+          border-radius: 7px;
+          background: transparent;
+          color: var(--muted-foreground);
+          font-size: 14px;
+          line-height: 1;
+          display: inline-grid;
+          place-content: center;
+          cursor: pointer;
+        }
+        .pretui-cal-nav:hover {
+          background: var(--hover, var(--boxel-100));
+          color: var(--foreground);
+        }
+        /* multi-month: prev lives on the first panel, next on the last */
+        .pretui-cal-panel:not(:first-child) .pretui-cal-nav[data-dir='prev'],
+        .pretui-cal-panel:not(:last-child) .pretui-cal-nav[data-dir='next'] {
+          visibility: hidden;
+        }
+        .pretui-cal-weekdays,
+        .pretui-cal-grid {
+          display: grid;
+          grid-template-columns: repeat(7, 30px);
+          gap: 2px;
+        }
+        .pretui-cal-weekday {
+          display: inline-grid;
+          place-content: center;
+          height: 18px;
+          font-family: var(--font-mono);
+          font-size: 10px;
+          letter-spacing: var(--track-eyebrow, 0.08em);
+          text-transform: uppercase;
+          color: var(--muted-foreground);
+        }
+        .pretui-cal-day {
+          height: 28px;
+          border: 0;
+          padding: 0;
+          border-radius: 7px;
+          background: transparent;
+          font-size: var(--text-ui-md, 12.5px);
+          font-variant-numeric: tabular-nums;
+          color: var(--foreground);
+          cursor: pointer;
+        }
+        .pretui-cal-day:hover:not(:disabled) {
+          background: var(--hover, var(--boxel-100));
+        }
+        .pretui-cal-day:disabled {
+          color: var(--ink-3, var(--boxel-400));
+          opacity: 0.55;
+          cursor: default;
+        }
+        .pretui-cal-day[data-outside] {
+          color: var(--ink-3, var(--boxel-400));
+        }
+        /* side-by-side months: outside days would duplicate their neighbor's
+           in-month days, so they hide (still occupying their grid slot) */
+        .pretui-calendar[data-multi] .pretui-cal-day[data-outside] {
+          visibility: hidden;
+        }
+        .pretui-cal-day[data-today] {
+          box-shadow: inset 0 0 0 1px var(--line-strong, var(--boxel-400));
+        }
+        .pretui-cal-day[data-in-range] {
+          background: color-mix(in oklch, var(--primary) 14%, var(--card));
+          color: color-mix(in oklch, var(--foreground) 30%, var(--primary));
+          border-radius: 0;
+        }
+        .pretui-cal-day[data-selected],
+        .pretui-cal-day[data-range-start],
+        .pretui-cal-day[data-range-end] {
+          background: var(--primary);
+          color: var(--primary-foreground);
+          font-weight: 600;
+        }
+        .pretui-cal-day[data-range-start] {
+          border-radius: 7px 0 0 7px;
+        }
+        .pretui-cal-day[data-range-end] {
+          border-radius: 0 7px 7px 0;
+        }
+        .pretui-cal-day[data-range-start][data-range-end] {
+          border-radius: 7px;
+        }
+        .pretui-cal-day:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 1px;
+        }
+        @container (max-width: 455px) {
+          .pretui-cal-panel:not(:first-child) {
+            display: none;
+          }
+          .pretui-cal-panel:first-child .pretui-cal-nav[data-dir='next'] {
+            visibility: visible;
+          }
+        }
+      }
+    </style>
+  </template>
+}

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

@@ -0,0 +1,57 @@
+## What it is
+
+**THE Pretui date surface.** One month-grid implementation — pure date math, roving-tabindex arrow keys, single and range modes — shared by every date control in the kit. Use it inline when the calendar should always be visible (a booking view, a scheduling panel). If it should live behind a field, use **DatePicker** or **DateRangePicker**, both of which wrap this exact component. There is deliberately no second calendar anywhere in the kit.
+
+## The contract
+
+```
+@mode? 'single' | 'range'   (default 'single')
+single:  @value? / @defaultValue? / @onValueChange?(iso)
+range:   @range? / @defaultRange? / @onRangeChange?({ start, end })
+@months? (default 1), @minDate?, @maxDate?, @disabled?
+```
+
+**ISO `yyyy-mm-dd` strings at every boundary.** Not `Date` objects, not timestamps. The reason is that ISO date strings **compare lexicographically** — `'2026-03-04' < '2026-03-11'` is true — so the entire range and bounds math runs on string comparison with no `Date` construction, no timezone, and no off-by-one from a UTC/local mismatch. That is the single best decision in this component, and it is why a range calendar here has none of the DST bugs the category is famous for.
+
+**Range semantics:** first click sets `start` with `end: null`, second completes; picked in reverse they swap. While the end is unset, the prospective span paints from the hovered day — **or from the keyboard focus when arrowing**, so the preview works without a pointer.
+
+**Day state is reflected as `data-*`**: `data-selected`, `data-range-start`, `data-range-end`, `data-in-range`, `data-today`, `data-outside`. A stylesheet can dress every state without the component exposing a variant.
+
+`@months` puts panels side by side; **an inline-size container query collapses to the first panel** in a narrow host. Note the consequence the source flags: containment means width comes from the parent, so **a host or popover panel must give the calendar an explicit width**.
+
+## Prior art
+
+**React Aria's `useCalendar`/`useCalendarGrid`** is the most complete implementation in the field, and the comparison is instructive: it renders `role="application"` on the calendar (with the visible range folded into the accessible name), `role="grid"` on the table, `aria-hidden` column headers (day names are already in each cell's label), and announces month changes imperatively via `announce(visibleRangeDescription)` — but **only** when the change came from the Prev/Next buttons, not when it came from arrowing. **Web Awesome** has no calendar. **react-day-picker** is the ecosystem default and is `role="grid"` based.
+
+Where Pretui is better: **lexicographic ISO math** (above) — react-day-picker and Spectrum both carry substantial date-object machinery (Spectrum has an entire `@internationalized/date` package) to avoid the bugs that string comparison simply does not have. And **one calendar for the whole kit**: DateRangePicker is built on this grid rather than on boxel-ui's ember-power-calendar, so both date controls share it. Two calendars in one kit is a guaranteed inconsistency.
+
+Where it is behind, and it is a real distance: **no locale support.** Every formatter is hard-coded `'en-US'`, so weekday order, month names and day names are American English regardless of the user. For an internationalised product this is disqualifying, and it is the largest gap in the component.
+
+Also absent: year/month dropdown navigation, week numbers, multi-date (non-range) selection, and any notion of a disabled _set_ of dates beyond min/max.
+
+## Accessibility
+
+Governing pattern: APG's **datepicker dialog** grid — `role="grid"` on the table, roving `tabindex` on cells, `aria-selected` on the selected date, and a specific keyboard contract.
+
+The implementation takes a different, defensible route: **days are `<button aria-pressed>` in a plain container**, with a roving tabindex and `focusWhen` moving real focus. Toggle-button semantics rather than grid semantics. That is legitimate — each day announces as a pressed/unpressed button with a full `aria-label` (weekday, month, day, year via `LABEL_FMT`) — and it avoids the grid pattern's complexity. But it means the calendar is **not announced as a grid**, so a screen-reader user gets no row/column context and no "week of" orientation.
+
+Concrete gaps against the pattern:
+
+- **Only Arrow keys are implemented.** `ArrowLeft/Right` are ±1 day, `ArrowUp/Down` are ±7. **Home/End (first/last day of the current week), Page Up/Page Down (previous/next month), and Shift+Page Up/Page Down (previous/next year) are all missing.** That is more than half the pattern's key list, and it means keyboard users must arrow through 30 presses to change month. This is the highest-value fix on the component.
+- **Arrow keys hard-stop at `@minDate`/`@maxDate`** — the handler returns rather than clamping, so focus simply does not move and nothing says why.
+- **No live region on the month heading.** APG's pattern puts `aria-live="polite"` on the month/year heading so navigation announces; React Aria announces imperatively. Here, pressing "Next month" changes the visible grid silently. Arrow navigation across a month boundary does call `setViewToInclude`, so the view follows focus — good — but that change is also silent.
+- **Weekday headers are plain `<span>`s** with no association to the columns. Since each day's `aria-label` includes the weekday name, nothing is lost for screen-reader users, and the spans should arguably be `aria-hidden` (React Aria hides its column headers for exactly this reason).
+- **No accessible name on the calendar itself.** No `aria-label`, no `role`. Two calendars in a range picker are two unnamed groups.
+- **`aria-pressed` on the day buttons is not the range vocabulary.** In range mode, `data-in-range` days are visually part of the selection but their pressed state does not reflect that, so a screen-reader user hears only the two endpoints as pressed.
+- **`disabled` on out-of-range days** removes them from the tab order entirely, which is right for a roving-tabindex composite.
+- `data-today` styling exists; verify it is not colour-only.
+
+## Theming
+
+`--pretui-selected` / `--primary` (selected day), `--hover` (hover and in-range fill), `--foreground` / `--muted-foreground` (day ink, and the dimmed `data-outside` days), `--border`, `--card`, `--radius`, `--text-ui-md`, `--text-ui-sm`.
+
+Every day state is a `data-*` attribute, so a stylesheet can dress `today`, `in-range`, `range-start` and `range-end` independently — including giving the range endpoints asymmetric radii, which is what makes a range read as one continuous band.
+
+Two things to check per theme: `data-today` must be distinguishable from `data-selected` without relying on color alone, and `data-outside` (adjacent-month days) must be dim enough to recede but still clear **WCAG 1.4.3** — it is the most common contrast failure in any calendar.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.