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

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

@@ -0,0 +1,66 @@
+// Pretui — DatePicker usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { DatePicker } from './date-picker';
+import { FreestyleUsage } from './freestyle-usage';
+import { Token } from './token';
+
+// ── DatePicker — built fresh (boxel-ui exports no single-date picker; only
+//    DateRangePicker) — no boxel usage page to port, so
+//    the knob set is native. Popover trigger + shared Pretui Calendar;
+//    arrow keys rove the day buttons. ──────────────────────────────────────
+class DatePickerUsage extends GlimmerComponent {
+  @tracked value = '2026-08-12';
+  @tracked disabled = false;
+  setValue = (v: string) => (this.value = v);
+  toggleDisabled = (v: boolean) => (this.disabled = v);
+  onChange = (iso: string) => (this.value = iso);
+  get usage() {
+    return `<DatePicker @value='${this.value}' @onValueChange={{this.onChange}} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='DatePicker'
+      @description='Single-date input: a readonly Pretui Input trigger opening the shared Pretui Calendar (single mode) in a Popover. Arrow keys move the focused day (roving tabindex), Enter selects, Escape or the backdrop closes. Dates travel as ISO yyyy-mm-dd strings.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <DatePicker
+          @value={{this.value}}
+          @disabled={{this.disabled}}
+          @onValueChange={{this.onChange}}
+        />
+        <Token @value={{this.value}} />
+        <DatePicker @defaultValue='2026-08-20' />
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='value'
+          @description='Selected date as ISO yyyy-mm-dd (controlled — wins over internal state).'
+          @value={{this.value}}
+          @onInput={{this.setValue}}
+        />
+        <Args.String
+          @name='defaultValue'
+          @description='Uncontrolled seed, ISO yyyy-mm-dd — the second specimen manages itself from this.'
+          @hideControls={{true}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @description='Disables the trigger input.'
+          @defaultValue={{false}}
+          @value={{this.disabled}}
+          @onInput={{this.toggleDisabled}}
+        />
+        <Args.Action
+          @name='onValueChange'
+          @description='Called with the ISO yyyy-mm-dd string when a day is picked.'
+        />
+      </:api>
+    </FreestyleUsage>
+  </template>
+}
+
+export const DEMOS_DATE_PICKER: Record<string, unknown> = {
+  DatePicker: DatePickerUsage,
+};

package/bundled-realms/pretui/components/date-range-picker.gts

@@ -0,0 +1,131 @@
+// Pretui — DateRangePicker: a trigger opening a range-mode Calendar.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { on } from '@ember/modifier';
+import { fn } from '@ember/helper';
+import { Input } from './input';
+import { Popover } from './popover';
+import { Calendar } from './calendar';
+import type { DateRangeValue } from './calendar';
+import { DISPLAY_FMT, fromIso } from '../internal/reading-extras';
+
+// ── DateRangePicker ──────────────────────────────────────────────────────
+// A readonly Pretui Input trigger + Popover
+// around a range-mode Calendar — the same month grid DatePicker uses. Two
+// months side by side by default; the calendar collapses to one month in a
+// narrow container. First click sets the start, second completes the range
+// (swapped when reversed) and closes the popover; hover paints the
+// prospective span. ISO yyyy-mm-dd strings both ways.
+export interface DateRangePickerSignature {
+  Args: {
+    value?: DateRangeValue; // controlled
+    defaultValue?: DateRangeValue; // uncontrolled seed
+    minDate?: string; // ISO yyyy-mm-dd
+    maxDate?: string; // ISO yyyy-mm-dd
+    months?: number; // side-by-side months (default 2)
+    disabled?: boolean;
+    onValueChange?: (range: { start: string | null; end: string | null }) => void;
+  };
+  Element: HTMLDivElement;
+}
+
+export class DateRangePicker extends Component<DateRangePickerSignature> {
+  @tracked internal: DateRangeValue | undefined = this.args.defaultValue;
+
+  get value(): DateRangeValue {
+    return this.args.value ?? this.internal ?? {};
+  }
+  get monthCount(): number {
+    return Math.max(1, Math.floor(this.args.months ?? 2));
+  }
+  get display(): string {
+    let start = fromIso(this.value.start ?? '');
+    let end = fromIso(this.value.end ?? '');
+    if (start && end) {
+      return `${DISPLAY_FMT.format(start)} – ${DISPLAY_FMT.format(end)}`;
+    }
+    if (start) {
+      return `${DISPLAY_FMT.format(start)} – …`;
+    }
+    return '';
+  }
+  onTriggerKey = (open: boolean, toggle: () => void, e: Event) => {
+    let key = (e as KeyboardEvent).key;
+    if (!open && (key === 'Enter' || key === ' ' || key === 'ArrowDown')) {
+      e.preventDefault();
+      toggle();
+    }
+  };
+  handleRange = (
+    close: () => void,
+    next: { start: string | null; end: string | null },
+  ) => {
+    this.internal = next;
+    this.args.onValueChange?.(next);
+    if (next.start && next.end) {
+      close();
+    }
+  };
+
+  <template>
+    <div
+      class='pretui-daterange'
+      data-months={{this.monthCount}}
+      data-test-pretui-date-range-picker
+      ...attributes
+    >
+      <Popover @placement='bottom-start' @label='Choose date range'>
+        <:trigger as |open toggle|>
+          <Input
+            @value={{this.display}}
+            @placeholder='Select date range'
+            @disabled={{@disabled}}
+            class='pretui-daterange-trigger'
+            readonly
+            aria-haspopup='dialog'
+            aria-expanded={{if open 'true' 'false'}}
+            {{on 'click' toggle}}
+            {{on 'keydown' (fn this.onTriggerKey open toggle)}}
+          />
+        </:trigger>
+        <:default as |close|>
+          <Calendar
+            @mode='range'
+            @range={{this.value}}
+            @months={{this.monthCount}}
+            @minDate={{@minDate}}
+            @maxDate={{@maxDate}}
+            @onRangeChange={{fn this.handleRange close}}
+          />
+        </:default>
+      </Popover>
+    </div>
+    <style scoped>
+      /* above Input's layer, so these win by layer order, not file order */
+      @layer PretComponent, PretComposite;
+      @layer PretComposite {
+        .pretui-daterange {
+          display: inline-block;
+        }
+        .pretui-daterange-trigger {
+          min-width: 230px;
+          cursor: pointer;
+        }
+        /* two one-month panels (222px each) + panel gap + popover padding;
+           viewport-capped so the calendar's container query can collapse it
+           to a single month on narrow screens. Sized through Popover's own
+           custom-property knobs (they inherit — no :deep()). */
+        .pretui-daterange {
+          --pretui-popover-width: calc(
+            444px + var(--space-5, 14px) + 2 * var(--space-4, 11px)
+          );
+          --pretui-popover-max-width: calc(100vw - 16px);
+          --pretui-popover-min-width: 0;
+        }
+        .pretui-daterange[data-months='1'] {
+          --pretui-popover-width: calc(222px + 2 * var(--space-4, 11px));
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/date-range-picker.md

@@ -0,0 +1,55 @@
+## What it is
+
+A start/end date field: a Pretui **Input** trigger, a **Popover**, and a **Calendar** in range mode showing two months by default. Use it for any span — a report period, a booking, a filter window. Do not compose two **DatePicker**s: a range needs the prospective-span preview and the swap-on-reverse-selection behaviour, and two independent fields give you neither plus a validation problem.
+
+## The contract
+
+```
+@value? { start, end } / @defaultValue? / @onValueChange?({ start, end })
+@minDate?, @maxDate?, @months? (default 2), @disabled?
+```
+
+ISO `yyyy-mm-dd` strings throughout, matching **Calendar** — which compare lexicographically, so the range math needs no `Date` objects and has none of the timezone bugs the category is known for.
+
+**`@onValueChange` fires on _both_ clicks**, with `end: null` after the first. That is the decision worth knowing: the caller sees the intermediate state, so it can disable a submit button or show "select an end date" while the range is half-built. A component that only reported completed ranges would hide that state.
+
+Picked in reverse, start and end swap. While the end is unset, the prospective span paints from the hovered day **or from the keyboard focus when arrowing** — so the preview is not pointer-only.
+
+`@months` defaults to 2, and a narrow container collapses to the first panel via an inline-size container query.
+
+## Prior art
+
+**DateRangePicker is built on Calendar rather than on boxel-ui's ember-power-calendar,** so both Pretui date controls share the same **Calendar**. That is the design decision to understand: two calendar implementations in one kit is a guaranteed inconsistency — different keyboard behaviour, different disabled-day rules, different visual language — and building on Calendar gives up a working third-party component for one that agrees with **DatePicker** in every detail.
+
+**React Spectrum `DateRangePicker`** is the field's reference: two segmented fields (each segment a `role="spinbutton"`), a range calendar, `minValue`/`maxValue`, `isDateUnavailable`, `allowsNonContiguousRanges`, and full internationalisation. **react-day-picker** with `mode="range"` is the ecosystem default. **Web Awesome** ships nothing.
+
+Where Pretui is better than the react-day-picker composition: it is one component with one keyboard model rather than a Popover plus a calendar library plus a trigger you wired yourself, and the trigger is a real **Input** so the value is visible and copyable.
+
+Where it is behind Spectrum, plainly: **no locale support** (formatters are hard-coded `en-US`), no segmented entry, no unavailable-dates predicate, no minimum or maximum span length, and no preset shortcuts ("Last 7 days", "This quarter") — which is the feature every analytics range picker has and the one users reach for first.
+
+## Accessibility
+
+Governing pattern: APG's **datepicker dialog**, plus the range-specific problem that there is no settled pattern for communicating a _span_ to a screen reader.
+
+What is right: `aria-haspopup="dialog"` and `aria-expanded` on the trigger — the correct wiring, and more than **Menu** or **Popover** do in this kit. Enter/Space/ArrowDown open the panel.
+
+Gaps, and the range-specific one is the interesting one:
+
+- **The span is visual only.** `data-in-range` days are dressed as part of the selection, but their `aria-pressed` is false — only the two endpoints report as pressed. A screen-reader user arrowing through a selected range hears "March 4, pressed", then eleven unpressed days, then "March 15, pressed". There is no announcement of "in selected range" and no live region reporting the span's length. Spectrum announces the range description on change; nothing here does.
+- **The half-built state is silent.** After the first click the component is waiting for an end date, and nothing announces that. This is exactly the state `@onRangeChange`'s `end: null` exists to let _you_ surface — do it, in a `role="status"` region.
+- **Both Popover gaps are inherited**: focus is not moved into the panel on open or restored on close, and **Escape only works once focus is inside the panel**, so a keyboard user who opens the picker cannot dismiss it without tabbing in first.
+- **All of Calendar's keyboard gaps apply** — Arrow keys only; no Home/End, no Page Up/Down for month, no Shift+Page for year — and they hurt more here, because selecting a range across two months means arrowing across a month boundary twice.
+- **The two month panels have no individual accessible names**, so a screen-reader user cannot tell which month they are in without reading a day's label.
+- **No accessible name of its own.** Use **Field**/**FormField**, or pass `aria-label`.
+- **No format hint for typed entry** (**WCAG 3.3.2**), and no parsing feedback.
+- Calendar's inline-size containment means the popover must be given an explicit width — at `@months={{2}}` that is roughly double, and a too-narrow panel silently collapses to one month.
+
+## Theming
+
+Trigger: **Input**'s tokens. Surface: **Popover**'s, including the `--pretui-popover-*` sizing knobs — which you **must** widen for two panels. Grid: **Calendar**'s `data-*` day states.
+
+The range-specific dressing is where a stylesheet earns its keep: `data-range-start`, `data-in-range` and `data-range-end` should read as one continuous band, which usually means asymmetric radii on the endpoints and a flat fill between them. Because those are `data-*` attributes rather than component args, a stylesheet can do that without touching the component.
+
+Check `data-in-range` against `--hover` per theme: the in-range fill and the pointer-hover fill often use the same token, and when they do, the user cannot tell the committed range from the one they are previewing.
+
+The styles sit in `@layer PretComposite`, above Input's `PretComponent` layer, so what this component sets on Input wins by layer order. A caller's unlayered CSS overrides both without a more specific selector.

package/bundled-realms/pretui/components/date-range-picker.usage.gts

@@ -0,0 +1,125 @@
+// Pretui — DateRangePicker usage page.
+import GlimmerComponent from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { DateRangePicker } from './date-range-picker';
+import { FreestyleUsage } from './freestyle-usage';
+import { Token } from './token';
+
+// ── DateRangePicker — the shared Pretui Calendar in range mode behind a
+//    popover trigger that matches DatePicker's. ──────────────────────────
+class DateRangePickerUsage extends GlimmerComponent {
+  @tracked start: string | null = '2026-08-03';
+  @tracked end: string | null = '2026-08-14';
+  @tracked minDate = '';
+  @tracked maxDate = '';
+  @tracked months = 2;
+  @tracked disabled = false;
+  setStart = (v: string) => (this.start = v || null);
+  setEnd = (v: string) => (this.end = v || null);
+  setMinDate = (v: string) => (this.minDate = v);
+  setMaxDate = (v: string) => (this.maxDate = v);
+  setMonths = (v: number) => (this.months = v);
+  toggleDisabled = (v: boolean) => (this.disabled = v);
+  onChange = (r: { start: string | null; end: string | null }) => {
+    this.start = r.start;
+    this.end = r.end;
+  };
+  get rangeObj() {
+    return { start: this.start, end: this.end };
+  }
+  get rangeString() {
+    return `${this.start ?? '—'} → ${this.end ?? '—'}`;
+  }
+  get startStr() {
+    return this.start ?? '';
+  }
+  get endStr() {
+    return this.end ?? '';
+  }
+  get minDateVal() {
+    return this.minDate || undefined;
+  }
+  get maxDateVal() {
+    return this.maxDate || undefined;
+  }
+  get usage() {
+    return `<DateRangePicker @value={{this.range}} @onValueChange={{this.onChange}} />`;
+  }
+  <template>
+    <FreestyleUsage
+      @name='DateRangePicker'
+      @description='Range input for filters, reports, booking flows, and any time-window: a readonly Pretui Input trigger opening the shared Pretui Calendar in range mode — two months side by side, collapsing to one in a narrow container. First click sets the start, second completes the range (swapped if reversed) and closes the popover; hover paints the prospective span. Speaks ISO yyyy-mm-dd strings both ways.'
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='range-col'>
+          <Token @value={{this.rangeString}} />
+          <DateRangePicker
+            @value={{this.rangeObj}}
+            @minDate={{this.minDateVal}}
+            @maxDate={{this.maxDateVal}}
+            @months={{this.months}}
+            @disabled={{this.disabled}}
+            @onValueChange={{this.onChange}}
+          />
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.String
+          @name='value.start'
+          @description='Start of the controlled range (ISO yyyy-mm-dd; empty = unset). Together with value.end this is the { start, end } @value object — seed @defaultValue instead for uncontrolled use.'
+          @value={{this.startStr}}
+          @onInput={{this.setStart}}
+        />
+        <Args.String
+          @name='value.end'
+          @description='End of the controlled range (ISO yyyy-mm-dd; empty = unset — the trigger shows "start – …" while selecting).'
+          @value={{this.endStr}}
+          @onInput={{this.setEnd}}
+        />
+        <Args.Action
+          @name='onValueChange'
+          @description='Called with { start, end } ISO yyyy-mm-dd strings on both clicks — end is null after the first click, set (and ordered) after the second, which also closes the popover.'
+          @required={{true}}
+        />
+        <Args.String
+          @name='minDate'
+          @description='Earliest selectable day (ISO yyyy-mm-dd); days before it render disabled. Set to today for an Airbnb-style no-past-dates calendar.'
+          @value={{this.minDate}}
+          @onInput={{this.setMinDate}}
+        />
+        <Args.String
+          @name='maxDate'
+          @description='Latest selectable day (ISO yyyy-mm-dd); days after it render disabled (e.g. a booking horizon).'
+          @value={{this.maxDate}}
+          @onInput={{this.setMaxDate}}
+        />
+        <Args.Number
+          @name='months'
+          @description='Side-by-side month panels in the popover calendar (default 2); narrow containers collapse to the first.'
+          @defaultValue={{2}}
+          @value={{this.months}}
+          @onInput={{this.setMonths}}
+        />
+        <Args.Bool
+          @name='disabled'
+          @description='Disables the trigger input (the popover cannot open).'
+          @defaultValue={{false}}
+          @value={{this.disabled}}
+          @onInput={{this.toggleDisabled}}
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .range-col {
+        display: grid;
+        gap: var(--space-3, 8px);
+        justify-items: start;
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_DATE_RANGE_PICKER: Record<string, unknown> = {
+  DateRangePicker: DateRangePickerUsage,
+};

package/bundled-realms/pretui/components/date-time-picker.gts

@@ -0,0 +1,227 @@
+// Pretui — DateTimePicker: a date and a time in one field, committed as one ISO datetime.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { fn } from '@ember/helper';
+import { on } from '@ember/modifier';
+import { Popover } from './popover';
+import { Calendar } from './calendar';
+import { TimeInput } from './time-input';
+import type { TimeInputHourCycle } from './time-input';
+import { Button } from './button';
+import { DISPLAY_FMT, fromIso } from '../internal/reading-extras';
+
+export interface DateTimePickerSignature {
+  Args: {
+    /** Controlled value: 'YYYY-MM-DDTHH:MM', or with ':SS' at second granularity. */
+    value?: string;
+    defaultValue?: string;
+    /** Fires with the committed datetime when Done is pressed. */
+    onChange?: (value: string) => void;
+    /** Alias of `@onChange` — the kit's control spelling. */
+    onValueChange?: (value: string) => void;
+    /** 'minute' (default) or 'second'. */
+    granularity?: 'minute' | 'second';
+    hourCycle?: TimeInputHourCycle;
+    /** The trigger's accessible name prefix (default 'Date and time'). */
+    label?: string;
+    placeholder?: string;
+    minDate?: string;
+    maxDate?: string;
+    disabled?: boolean;
+  };
+  Element: HTMLSpanElement;
+}
+
+const DATETIME = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2}(?::\d{2})?)$/;
+const MINUTE_TIME = /^\d{2}:\d{2}$/;
+const SECOND_TIME = /^\d{2}:\d{2}:\d{2}$/;
+
+function split(value: string | undefined): { date?: string; time?: string } {
+  let m = value ? DATETIME.exec(value) : null;
+  return m ? { date: m[1], time: m[2] } : {};
+}
+
+/**
+ * DatePicker and TimeInput composed into one field with one popover: the
+ * calendar and the time segments sit together, and Done commits a single
+ * string. The value always carries the `T` separator and no zone — a
+ * wall-clock datetime, the shape a DateTimeField stores. Done is disabled
+ * until both halves are complete, so a half-filled value never leaves the
+ * popover; closing without Done keeps the committed value.
+ */
+export class DateTimePicker extends Component<DateTimePickerSignature> {
+  @tracked private internal: string | undefined = this.args.defaultValue;
+  @tracked draftDate: string | undefined;
+  @tracked draftTime: string | undefined;
+
+  get value(): string | undefined {
+    return this.args.value ?? this.internal;
+  }
+  get withSeconds(): boolean {
+    return this.args.granularity === 'second';
+  }
+  get display(): string {
+    let { date, time } = split(this.value);
+    if (!date || !time) {
+      return '';
+    }
+    let d = fromIso(date);
+    return `${d ? DISPLAY_FMT.format(d) : date}, ${time}`;
+  }
+  get placeholder(): string {
+    return this.args.placeholder ?? 'Select date and time';
+  }
+  /** Names what the trigger shows, so a voice user can say it (WCAG 2.5.3). */
+  get triggerName(): string {
+    let label = this.args.label ?? 'Date and time';
+    return `${label}: ${this.display || this.placeholder}`;
+  }
+  /** The time in exactly the shape the granularity commits. */
+  get timeShape(): RegExp {
+    return this.withSeconds ? SECOND_TIME : MINUTE_TIME;
+  }
+  get draftComplete(): boolean {
+    return Boolean(this.draftDate && this.draftTime && this.timeShape.test(this.draftTime));
+  }
+  /** A seeded time trimmed or padded to the granularity. */
+  private fit(time: string | undefined): string | undefined {
+    if (!time) {
+      return undefined;
+    }
+    let hm = time.slice(0, 5);
+    return this.withSeconds ? (time.length >= 8 ? time.slice(0, 8) : `${hm}:00`) : hm;
+  }
+
+  /** Seed the drafts from the committed value each time the popover opens. */
+  begin = (toggle: () => void, open: boolean) => {
+    if (!open) {
+      let { date, time } = split(this.value);
+      this.draftDate = date;
+      this.draftTime = this.fit(time);
+    }
+    toggle();
+  };
+  onTriggerKey = (open: boolean, toggle: () => void, e: Event) => {
+    let key = (e as KeyboardEvent).key;
+    if (!open && key === 'ArrowDown') {
+      e.preventDefault();
+      this.begin(toggle, open);
+    }
+  };
+  setDate = (iso: string) => {
+    this.draftDate = iso;
+  };
+  setTime = (wire: string) => {
+    this.draftTime = wire || undefined;
+  };
+  done = (close: () => void) => {
+    if (!this.draftComplete) {
+      return;
+    }
+    let next = `${this.draftDate}T${this.draftTime}`;
+    if (this.args.value === undefined) {
+      this.internal = next;
+    }
+    this.args.onChange?.(next);
+    this.args.onValueChange?.(next);
+    close();
+  };
+
+  <template>
+    <span class='pretui-datetime' data-test-pretui-date-time-picker ...attributes>
+      <Popover @placement='bottom-start' @label='Choose date and time'>
+        <:trigger as |open toggle|>
+          <button
+            type='button'
+            class='pretui-datetime-trigger'
+            aria-haspopup='dialog'
+            aria-expanded={{if open 'true' 'false'}}
+            aria-label={{this.triggerName}}
+            disabled={{@disabled}}
+            data-test-pretui-date-time-trigger
+            {{on 'click' (fn this.begin toggle open)}}
+            {{on 'keydown' (fn this.onTriggerKey open toggle)}}
+          >
+            {{#if this.display}}
+              <span class='pretui-datetime-value' data-test-pretui-date-time-value>{{this.display}}</span>
+            {{else}}
+              <span class='pretui-datetime-placeholder'>{{this.placeholder}}</span>
+            {{/if}}
+          </button>
+        </:trigger>
+        <:default as |close|>
+          <div class='pretui-datetime-panel' data-test-pretui-date-time-panel>
+            <Calendar @value={{this.draftDate}} @minDate={{@minDate}} @maxDate={{@maxDate}} @onValueChange={{this.setDate}} />
+            <div class='pretui-datetime-foot'>
+              <TimeInput
+                @value={{this.draftTime}}
+                @withSeconds={{this.withSeconds}}
+                @hourCycle={{@hourCycle}}
+                @label='Time'
+                @onValueChange={{this.setTime}}
+              />
+              <Button
+                @appearance='accent'
+                @size='s'
+                aria-disabled={{unless this.draftComplete 'true'}}
+                data-test-pretui-date-time-done
+                {{on 'click' (fn this.done close)}}
+              >Done</Button>
+            </div>
+          </div>
+        </:default>
+      </Popover>
+    </span>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-datetime {
+          display: inline-block;
+          --pretui-popover-width: calc(222px + 2 * var(--space-4, 11px));
+          --pretui-popover-min-width: 0;
+        }
+        .pretui-datetime-trigger {
+          display: flex;
+          align-items: center;
+          min-inline-size: 13rem;
+          min-block-size: var(--pretui-control-h, 2.25rem);
+          padding-inline: var(--space-3, 0.5rem);
+          border: 0;
+          border-radius: var(--radius-control, 6px);
+          background: var(--input-background, var(--card));
+          box-shadow: 0 0 0 1px var(--input, var(--border));
+          color: var(--foreground);
+          font-family: var(--font-sans);
+          font-size: var(--text-ui-md, 0.78rem);
+          text-align: start;
+          cursor: pointer;
+        }
+        .pretui-datetime-trigger:focus-visible {
+          outline: 2px solid var(--ring);
+          outline-offset: 1px;
+        }
+        .pretui-datetime-trigger:disabled {
+          opacity: 0.6;
+          cursor: not-allowed;
+        }
+        .pretui-datetime-value {
+          font-variant-numeric: tabular-nums;
+        }
+        .pretui-datetime-placeholder {
+          color: var(--muted-foreground);
+        }
+        .pretui-datetime-panel {
+          display: grid;
+          gap: var(--space-3, 0.5rem);
+        }
+        .pretui-datetime-foot {
+          display: flex;
+          align-items: center;
+          justify-content: space-between;
+          gap: var(--space-2, 0.375rem);
+          padding-block-start: var(--space-3, 0.5rem);
+          border-block-start: 1px solid var(--border);
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/date-time-picker.md

@@ -0,0 +1,60 @@
+## What it is
+
+**A date and a time in one field**, committed as one wall-clock datetime such as `2026-10-02T07:30`. Use it for a meeting start, a roast slot, a delivery window, or any moment that needs both halves.
+
+Reach for a neighbour when only one half is needed:
+
+- **DatePicker** is a date alone.
+- **TimeInput** is a time alone.
+- **Calendar** is an inline month grid with no field.
+
+## The contract
+
+```
+@value?, @defaultValue?, @onChange? (alias @onValueChange)
+@granularity? ('minute' | 'second'; default 'minute'), @hourCycle?
+@label? (default 'Date and time'), @placeholder?
+@minDate?, @maxDate?, @disabled?
+Element: HTMLSpanElement
+```
+
+**One field, one popover.** The trigger opens a popover with a **Calendar** above a **TimeInput** and a Done button. Choosing a day and setting the time change a draft. Done commits the draft as one string and closes the popover.
+
+**The value always has the `T` and no zone.** It is `YYYY-MM-DDTHH:MM`, with `:SS` at second granularity, and a seeded value is fitted to the granularity (padded with `:00`, or trimmed): the wall-clock shape a DateTimeField stores. Time zones belong to the field, not the picker.
+
+**A half-filled value never leaves.** Done is `aria-disabled` until both a day and a time in exactly the granularity's shape are set, and pressing it early does nothing. Closing without Done keeps the committed value. Opening again seeds the draft from it, so changing only the day keeps the time.
+
+## Prior art
+
+**Mantine `DateTimePicker`** takes `value`, `onChange`, `withSeconds`, `valueFormat`, `minDate`, `maxDate` and `submitButtonProps`, and has the same one-popover-plus-submit shape. **Ant `DatePicker showTime`** adds a time column beside the calendar with an OK button. **MUI X `DateTimePicker`** is a stepped view with tabs.
+
+Where Pretui is better: **the committed value is one explicit string** with no `Date` object, zone or format to configure, and **Done refuses a half-filled value**. Mantine emits a `Date` in local time.
+
+Where it is thinner: **no typed input.** The field is a button, so you can't type "2026-10-02 07:30". There are **no presets** ("Now", "Tomorrow 9:00"), **no range mode**, and **no time-zone selection**.
+
+## Accessibility
+
+A disclosure trigger opening a dialog-like popover, composed from **Calendar** and **TimeInput**, each with its own pattern.
+
+- **The trigger** is a `<button>` with `aria-haspopup="dialog"` and `aria-expanded`. It is named "{label}: {date}, {time}", or "{label}: {placeholder}" while empty, so the name includes the visible text (WCAG 2.5.3) and the committed value is heard. The tests assert the name, including the committed time, and the expanded state.
+- **The calendar** is Calendar's grid of day buttons with its roving keyboard, and **the time** is TimeInput's labelled group of spinbuttons — or, on a touch screen, the native time input TimeInput swaps in for them.
+- **Done is `aria-disabled`, not `disabled`,** so it stays focusable and announced while it refuses. The tests assert that it refuses and then commits.
+- **ArrowDown on the trigger opens it**, as for DatePicker. Escape and an outside click close it through **Popover**.
+
+## Theming
+
+The trigger reads `--input-background`, `--input`, `--ring`, `--radius-control`, `--pretui-control-h`, `--foreground`, `--muted-foreground`, `--font-sans` and `--text-ui-md`. The panel reads **Popover**'s tokens (the width is set with `--pretui-popover-width`), **Calendar**'s and **TimeInput**'s own, `--border` for the rule above the time, and `--space-2` / `--space-3`.
+
+The panel's one-month width is fixed.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+
+## React ecosystem
+
+| Agent types                               | Give them                           |
+| ----------------------------------------- | ----------------------------------- |
+| Mantine `<DateTimePicker value onChange>` | `<DateTimePicker @value @onChange>` |
+| Mantine `withSeconds`                     | `@granularity='second'`             |
+| Ant `<DatePicker showTime>`               | `<DateTimePicker>`                  |
+| `Date` object values                      | an ISO wall-clock string with `T`   |
+| Ant `presets`                             | not supported                       |