@slotted/angular 0.0.0-stage → 0.1.0-beta.0

package/docs/datetime-picker.examples.md

@@ -0,0 +1,1269 @@
+<!-- index: ./index.md -->
+# datetime-picker
+
+`data-ui="datetime-picker"` · Date and time field with a picker popover.
+
+## Examples
+
+### Playground
+
+One Datetime Picker driven by the controls below the canvas. Open it: the calendar and the list are both in the panel, the head shows the value so far, and the panel closes on the press that completes the value.
+
+Excerpt — not a complete module
+
+```html
+<div slField>
+  <label slFieldLabel>Pickup date and time</label>
+  <div slDateTimePicker name="pickupAt" [clearable]="true"></div>
+  <span slFieldDescription>The carrier collects at this date and time.</span>
+</div>
+```
+
+### Two surfaces in one dialog
+
+The panel holds a grid drawn by SlCalendar and a listbox drawn by the Datetime Picker. Both are in the DOM at every width; no tabs switch between them, so assistive technology reads the same structure on a wide and a narrow screen.
+
+Excerpt — not a complete module
+
+```html
+<div slDateTimePicker [defaultOpen]="true"></div>
+```
+
+### Which surface takes focus on open
+
+openTo decides where focus lands when the panel opens, not what the panel draws. Both surfaces are present either way, in the same order: the calendar, then the list.
+
+Excerpt — not a complete module
+
+```html
+<div slDateTimePicker openTo="time"></div>
+```
+
+### The value closes the panel, not a button
+
+With closeOnSelect="auto", the press that completes the value closes the panel. A press on a value that was already whole changes one half and leaves the panel open, so the reader can change the day and then the time. always closes on every press that changes the value; never closes on none.
+
+Excerpt — not a complete module
+
+```html
+<div slDateTimePicker closeOnSelect="auto"></div>
+<div slDateTimePicker closeOnSelect="always"></div>
+<div slDateTimePicker closeOnSelect="never"></div>
+```
+
+### Seconds
+
+granularity="second" writes seconds in the field, and a step of 30 offers a time every half minute. The list stops at maxOptions rows, so a step in seconds needs a window from minTime to maxTime to stay short.
+
+Excerpt — not a complete module
+
+```html
+<div slDateTimePicker granularity="second" [step]="30"></div>
+```
+
+### The step, and where it counts from
+
+The list counts from min’s time when min is set and from midnight when it is not, the rule input[type=time] uses. A step of 900 from 09:07 offers 09:07, 09:22 and 09:37; the field still accepts 09:15 by typing.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDateTimePicker } from '@slotted/angular/datetime-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { plainDate, plainDateTime, plainTime } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-datetime-picker-step',
+  imports: [SlDateTimePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Dock appointment</label>
+      <div
+        slDateTimePicker
+        [maxTime]="lastStart"
+        [minTime]="firstStart"
+        [referenceDateTime]="reference"
+        [step]="1800"
+      ></div>
+      <span slFieldDescription>Appointments start every 30 minutes from 7:15 AM.</span>
+    </div>
+  `,
+})
+export class DateTimePickerStep {
+  protected readonly firstStart = plainTime(7, 15);
+  protected readonly lastStart = plainTime(16, 45);
+  protected readonly reference = plainDateTime(plainDate(2026, 9, 30), plainTime(7, 15));
+}
+```
+
+### Two pairs of bounds together
+
+min and max bound the whole value; minTime and maxTime bound the times of every day inside the range. On the day of min the list starts at min’s time, on the day of max it stops at max’s time, and on every day between it runs from minTime to maxTime.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slDateTimePicker
+  [min]="bookingOpens"
+  [max]="bookingCloses"
+  [minTime]="nine"
+  [maxTime]="six"
+></div>
+```
+
+### The list follows the day the reader is on
+
+Before a day is chosen, the list answers the day the calendar has focused. Moving through the month recomputes it, so a Saturday that closes early shows its shorter list, or the empty state, while the reader is still deciding.
+
+Excerpt — not a complete module
+
+```html
+<div slDateTimePicker [isTimeUnavailable]="closesEarlyOnSaturday"></div>
+```
+
+### Refused times are disabled or hidden
+
+A refused time stays in the list, disabled, so the reader can still see the step. unavailableOptions="hide" removes refused times instead. A day that offers no time shows the empty message.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDateTimePicker } from '@slotted/angular/datetime-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import {
+  dayOfWeek,
+  plainDate,
+  plainDateTime,
+  plainTime,
+  type PlainDate,
+  type PlainTime,
+} from '@slotted/core/date';
+
+@Component({
+  selector: 'app-datetime-picker-unavailable',
+  imports: [SlDateTimePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Warehouse inspection</label>
+      <div
+        slDateTimePicker
+        [isDateUnavailable]="isWeekend"
+        [isTimeUnavailable]="isLunch"
+        [maxTime]="dayEnds"
+        [minTime]="dayStarts"
+        [referenceDateTime]="reference"
+        [step]="1800"
+      ></div>
+      <span slFieldDescription>Weekdays from 8:00 AM to 5:00 PM, closed for lunch at noon.</span>
+    </div>
+  `,
+})
+export class DateTimePickerUnavailable {
+  protected readonly dayStarts = plainTime(8, 0);
+  protected readonly dayEnds = plainTime(17, 0);
+  protected readonly reference = plainDateTime(plainDate(2026, 9, 30), plainTime(9, 0));
+  protected readonly isWeekend = (date: PlainDate) =>
+    dayOfWeek(date) === 0 || dayOfWeek(date) === 6;
+  protected readonly isLunch = (time: PlainTime) => time.hour === 12;
+}
+```
+
+### One press for the current date and time
+
+Now writes both halves from the clock in timeZone. It does the same as the relative expression 0 in the field, for a reader who does not know the expression. messages.now replaces its label.
+
+Excerpt — not a complete module
+
+```html
+<div slDateTimePicker [messages]="{ now: 'Right now' }"></div>
+```
+
+### Typing with the panel open
+
+Alt+ArrowDown opens the panel and leaves focus in the field, so every key the segments take still works, including +, - and = for a relative expression. Escape closes the expression first and leaves the panel open.
+
+Excerpt — not a complete module
+
+```html
+<div slDateTimePicker [defaultOpen]="true" [referenceDateTime]="reference"></div>
+```
+
+### Your own shortcuts
+
+An element with slDateTimePickerPresets adds a row in the head beside Now. The row wraps inside the panel’s width instead of widening it.
+
+Excerpt — not a complete module
+
+```html
+<div slDateTimePicker>
+  <div slDateTimePickerPresets>
+    <button slButton size="sm" variant="ghost" type="button" (click)="tomorrowAtNine()">
+      Tomorrow, 9:00 AM
+    </button>
+    <button slButton size="sm" variant="ghost" type="button" (click)="mondayAtTwo()">
+      Monday, 2:00 PM
+    </button>
+  </div>
+</div>
+```
+
+### Size
+
+The three steps of the control scale. Inside a field, an unset size follows the field. The rows of the list follow the same scale.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDateTimePicker } from '@slotted/angular/datetime-picker';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { plainDate, plainDateTime, plainTime } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-datetime-picker-sizes',
+  imports: [SlDateTimePicker, SlField, SlFieldLabel, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Created after</label>
+        <div slDateTimePicker size="sm" [defaultValue]="created"></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Pickup</label>
+        <div slDateTimePicker size="md" [defaultValue]="pickup"></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Store opening</label>
+        <div slDateTimePicker size="lg" [defaultValue]="opening"></div>
+      </div>
+    </div>
+  `,
+})
+export class DateTimePickerSizes {
+  protected readonly created = plainDateTime(plainDate(2026, 9, 1), plainTime(0, 0));
+  protected readonly pickup = plainDateTime(plainDate(2026, 9, 30), plainTime(9, 0));
+  protected readonly opening = plainDateTime(plainDate(2026, 11, 2), plainTime(10, 0));
+}
+```
+
+### Variant
+
+The frame is the datetime field’s, the same frame every field in a form draws. plain draws no frame at rest, for a table cell or a toolbar, and still shows hover and focus.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDateTimePicker } from '@slotted/angular/datetime-picker';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { plainDate, plainDateTime, plainTime } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-datetime-picker-variants',
+  imports: [SlDateTimePicker, SlField, SlFieldLabel, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Pickup</label>
+        <div slDateTimePicker variant="outline" [defaultValue]="pickup"></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Loading starts</label>
+        <div slDateTimePicker variant="subtle" [defaultValue]="pickup"></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Gate opens</label>
+        <div slDateTimePicker variant="plain" [defaultValue]="pickup"></div>
+      </div>
+    </div>
+  `,
+})
+export class DateTimePickerVariants {
+  protected readonly pickup = plainDateTime(plainDate(2026, 9, 30), plainTime(9, 0));
+}
+```
+
+### Placement
+
+Where the panel opens relative to the control. It is a preference: when the panel does not fit on that side, the positioner opens it on the other, and data-placement says which side it chose.
+
+Excerpt — not a complete module
+
+```html
+<div slDateTimePicker placement="top-start"></div>
+```
+
+### States
+
+Read-only stays focusable and legible. Disabled takes no key and no press, and its trigger is a disabled button. Invalid draws the frame and the focus ring in the danger tone. In the list, the chosen time outranks the highlighted time, which outranks hover.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDateTimePicker } from '@slotted/angular/datetime-picker';
+import { SlField, SlFieldDescription, SlFieldError, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { plainDate, plainDateTime, plainTime } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-datetime-picker-states',
+  imports: [SlDateTimePicker, SlField, SlFieldDescription, SlFieldError, SlFieldLabel, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      <div slField invalid required>
+        <label slFieldLabel>Pickup</label>
+        <div slDateTimePicker [defaultValue]="early"></div>
+        <span slFieldError
+          >The pickup is before the order was placed, September 30 at 9:00 AM.</span
+        >
+      </div>
+      <div slField readOnly>
+        <label slFieldLabel>Order placed</label>
+        <div slDateTimePicker [defaultValue]="placed"></div>
+        <span slFieldDescription>Set when the order was placed.</span>
+      </div>
+      <div slField disabled>
+        <label slFieldLabel>Delivered</label>
+        <div slDateTimePicker></div>
+        <span slFieldDescription>Filled in by the carrier on delivery.</span>
+      </div>
+    </div>
+  `,
+})
+export class DateTimePickerStates {
+  protected readonly early = plainDateTime(plainDate(2026, 9, 29), plainTime(16, 0));
+  protected readonly placed = plainDateTime(plainDate(2026, 9, 30), plainTime(9, 0));
+}
+```
+
+### In a form
+
+The Datetime Picker is a form control: formControlName, formControl and ngModel bind the value, and name adds a hidden input that submits it as YYYY-MM-DDTHH:mm:ss. The field around it supplies the label, the description and the error, and passes its size, disabled state and validity to the Datetime Picker unless it sets its own.
+
+Excerpt — not a complete module
+
+```html
+<form [formGroup]="form">
+  <div slField>
+    <label slFieldLabel>Pickup date and time</label>
+    <div slDateTimePicker formControlName="pickupAt"></div>
+    <span slFieldDescription>The dock is open from 9:00 AM to 6:00 PM.</span>
+  </div>
+</form>
+```
+
+### Narrow
+
+With too little room for both surfaces, the list wraps under the calendar, in the value’s own order. Nothing is hidden and no switch is drawn.
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import { SlDateTimePicker, SlDateTimePickerPresets } from '@slotted/angular/datetime-picker';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import {
+  addDays,
+  plainDate,
+  plainDateTime,
+  plainTime,
+  type PlainDateTime,
+} from '@slotted/core/date';
+
+const TODAY = plainDate(2026, 9, 30);
+
+@Component({
+  selector: 'app-datetime-picker-narrow',
+  imports: [SlButton, SlDateTimePicker, SlDateTimePickerPresets, SlField, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Delivery appointment</label>
+      <div
+        slDateTimePicker
+        #picker="slDateTimePicker"
+        [referenceDateTime]="reference"
+        [step]="1800"
+        [value]="delivery()"
+        (valueChange)="delivery.set($event.value)"
+      >
+        <div slDateTimePickerPresets>
+          <button
+            slButton
+            size="sm"
+            type="button"
+            variant="ghost"
+            (click)="delivery.set(todayAtFive); picker.closeSurface()"
+          >
+            Today, 5:00 PM
+          </button>
+          <button
+            slButton
+            size="sm"
+            type="button"
+            variant="ghost"
+            (click)="delivery.set(tomorrowAtNine); picker.closeSurface()"
+          >
+            Tomorrow, 9:00 AM
+          </button>
+        </div>
+      </div>
+    </div>
+  `,
+})
+export class DateTimePickerNarrow {
+  protected readonly reference = plainDateTime(TODAY, plainTime(9, 0));
+  protected readonly todayAtFive = plainDateTime(TODAY, plainTime(17, 0));
+  protected readonly tomorrowAtNine = plainDateTime(addDays(TODAY, 1), plainTime(9, 0));
+  protected readonly delivery = signal<PlainDateTime | null>(null);
+}
+```
+
+### Composition
+
+provideDateTimePickerDefaults sets the step and the clock once; provideSlotted sets the language and the words; an ng-template with slDateTimePickerOption draws the content of one row; slDateTimePickerFooter takes your actions; and exportAs reaches focus(), openSurface() and closeSurface(). A value set on one Datetime Picker still wins over the provider.
+
+Excerpt — not a complete module
+
+```html
+<div slDateTimePicker>
+  <ng-template slDateTimePickerOption let-time let-label="label">
+    <span>{{ label }}</span>
+    <span>{{ seatsLeft(time) }} seats left</span>
+  </ng-template>
+</div>
+```
+
+### Keyboard
+
+Alt+ArrowDown opens the panel from a segment and leaves focus in the field. ArrowDown on the trigger opens it and moves focus into the surface openTo names. In the list: the arrow keys, Home, End, type-ahead, and PageUp and PageDown to the previous or next hour. Tab stays inside the panel while it is open, and each surface is one Tab stop.
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { SlDateTimePicker } from '@slotted/angular/datetime-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { plainDate, plainDateTime, plainTime } from '@slotted/core/date';
+import type { ChangeRequest } from '@slotted/core/state';
+
+@Component({
+  selector: 'app-datetime-picker-keyboard',
+  imports: [SlDateTimePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Dispatch</label>
+      <div
+        slDateTimePicker
+        [defaultValue]="dispatch"
+        [messages]="messages"
+        (openChange)="record($event)"
+      ></div>
+      <span slFieldDescription>{{ last() }}</span>
+    </div>
+  `,
+})
+export class DateTimePickerKeyboard {
+  protected readonly dispatch = plainDateTime(plainDate(2026, 9, 30), plainTime(16, 30));
+  protected readonly messages = {
+    choose: 'Choose dispatch time',
+    change: 'Change dispatch time, {date}',
+  };
+  protected readonly last = signal('Focus the field and press Alt+ArrowDown.');
+
+  protected record(request: ChangeRequest<boolean>): void {
+    this.last.set(`${request.value ? 'Opened' : 'Closed'} by ${request.reason}.`);
+  }
+}
+```
+
+### bounds.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDateTimePicker } from '@slotted/angular/datetime-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { plainDate, plainDateTime, plainTime } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-datetime-picker-bounds',
+  imports: [SlDateTimePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Container collection</label>
+      <div
+        slDateTimePicker
+        [defaultValue]="opens"
+        [max]="closes"
+        [maxTime]="dayEnds"
+        [min]="opens"
+        [minTime]="dayStarts"
+        [step]="3600"
+      ></div>
+      <span slFieldDescription>
+        From October 1 at 1:00 PM to October 9 at 12:00 PM, between 8:00 AM and 5:00 PM.
+      </span>
+    </div>
+  `,
+})
+export class DateTimePickerBounds {
+  protected readonly opens = plainDateTime(plainDate(2026, 10, 1), plainTime(13, 0));
+  protected readonly closes = plainDateTime(plainDate(2026, 10, 9), plainTime(12, 0));
+  protected readonly dayStarts = plainTime(8, 0);
+  protected readonly dayEnds = plainTime(17, 0);
+}
+```
+
+### carrier-pickup.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import {
+  SlDateTimePicker,
+  SlDateTimePickerFooter,
+  SlDateTimePickerOption,
+} from '@slotted/angular/datetime-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlText } from '@slotted/angular/typography';
+import {
+  createDateTimeFormat,
+  dayOfWeek,
+  plainDate,
+  plainDateTime,
+  plainTime,
+  toISODate,
+  toISOTime,
+  type PlainDate,
+  type PlainDateTime,
+  type PlainTime,
+} from '@slotted/core/date';
+
+const TRUCKS_PER_WINDOW = 3;
+/** Pickups already booked, by date and window. */
+const BOOKED: Record<string, number> = {
+  '2026-10-01T08:00:00': 3,
+  '2026-10-01T10:30:00': 2,
+  '2026-10-02T13:00:00': 3,
+  '2026-10-02T15:30:00': 1,
+};
+const words = createDateTimeFormat({ locale: 'en-US' });
+
+const trucksLeft = (time: PlainTime, date: PlainDate) =>
+  TRUCKS_PER_WINDOW - (BOOKED[`${toISODate(date)}T${toISOTime(time)}`] ?? 0);
+
+@Component({
+  selector: 'app-datetime-picker-carrier-pickup',
+  imports: [
+    SlButton,
+    SlDateTimePicker,
+    SlDateTimePickerFooter,
+    SlDateTimePickerOption,
+    SlField,
+    SlFieldDescription,
+    SlFieldLabel,
+    SlText,
+  ],
+  template: `
+    <div slField required>
+      <label slFieldLabel>Carrier pickup slot</label>
+      <div
+        slDateTimePicker
+        #picker="slDateTimePicker"
+        closeOnSelect="never"
+        [isDateUnavailable]="isWeekend"
+        [isTimeUnavailable]="isFull"
+        [min]="earliest"
+        [options]="windows"
+        [referenceDateTime]="reference"
+        [value]="pickup()"
+        (valueChange)="pickup.set($event.value)"
+      >
+        <ng-template
+          slDateTimePickerOption
+          let-time
+          let-date="date"
+          let-label="label"
+          let-unavailable="unavailable"
+        >
+          <span>{{ label }}</span>
+          <span slText size="sm" tone="muted">{{ capacity(time, date, unavailable) }}</span>
+        </ng-template>
+        <div slDateTimePickerFooter>
+          <button slButton size="sm" type="button" (click)="picker.closeSurface()">Done</button>
+        </div>
+      </div>
+      <span slFieldDescription>{{ summary() }}</span>
+    </div>
+  `,
+})
+export class DateTimePickerCarrierPickup {
+  /** The windows Harbor Freightways collects in, every weekday. */
+  protected readonly windows = [
+    plainTime(8, 0),
+    plainTime(10, 30),
+    plainTime(13, 0),
+    plainTime(15, 30),
+  ];
+  protected readonly earliest = plainDateTime(plainDate(2026, 10, 1), plainTime(8, 0));
+  protected readonly reference = plainDateTime(plainDate(2026, 10, 1), plainTime(10, 30));
+  protected readonly pickup = signal<PlainDateTime | null>(null);
+  protected readonly summary = computed(() => {
+    const pickup = this.pickup();
+    return pickup === null
+      ? 'Harbor Freightways collects on weekdays, in four windows.'
+      : `Harbor Freightways collects on ${words.describe(pickup)}.`;
+  });
+
+  protected readonly isWeekend = (date: PlainDate) =>
+    dayOfWeek(date) === 0 || dayOfWeek(date) === 6;
+  protected readonly isFull = (time: PlainTime, date: PlainDate) => trucksLeft(time, date) === 0;
+
+  protected capacity(time: PlainTime, date: PlainDate, unavailable: boolean): string {
+    return unavailable ? 'Full' : `${trucksLeft(time, date)} of ${TRUCKS_PER_WINDOW} trucks left`;
+  }
+}
+```
+
+### clearable.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDateTimePicker } from '@slotted/angular/datetime-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { plainDate, plainDateTime, plainTime } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-datetime-picker-clearable',
+  imports: [SlDateTimePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Hold shipment until</label>
+      <div slDateTimePicker clearable [defaultValue]="holdUntil"></div>
+      <span slFieldDescription>Clear the date and time to release the shipment.</span>
+    </div>
+  `,
+})
+export class DateTimePickerClearable {
+  protected readonly holdUntil = plainDateTime(plainDate(2026, 10, 9), plainTime(17, 0));
+}
+```
+
+### controlled.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import { SlDateTimePicker } from '@slotted/angular/datetime-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlInline } from '@slotted/angular/inline';
+import { SlStack } from '@slotted/angular/stack';
+import {
+  addDays,
+  createDateTimeFormat,
+  plainDate,
+  plainDateTime,
+  plainTime,
+  type PlainDateTime,
+} from '@slotted/core/date';
+
+const TODAY = plainDate(2026, 9, 30);
+const words = createDateTimeFormat({ locale: 'en-US' });
+
+@Component({
+  selector: 'app-datetime-picker-controlled',
+  imports: [
+    SlButton,
+    SlDateTimePicker,
+    SlField,
+    SlFieldDescription,
+    SlFieldLabel,
+    SlInline,
+    SlStack,
+  ],
+  template: `
+    <div slStack [gap]="4">
+      <div slField>
+        <label slFieldLabel>Call Harbor Freightways</label>
+        <div slDateTimePicker [value]="call()" (valueChange)="call.set($event.value)"></div>
+        <span slFieldDescription>{{ summary() }}</span>
+      </div>
+      <div slInline [gap]="2">
+        <button
+          slButton
+          size="sm"
+          tone="secondary"
+          type="button"
+          variant="outline"
+          (click)="schedule(1, 9)"
+        >
+          Tomorrow, 9:00 AM
+        </button>
+        <button
+          slButton
+          size="sm"
+          tone="secondary"
+          type="button"
+          variant="outline"
+          (click)="schedule(2, 14)"
+        >
+          Friday, 2:00 PM
+        </button>
+        <button
+          slButton
+          size="sm"
+          tone="secondary"
+          type="button"
+          variant="ghost"
+          (click)="call.set(null)"
+        >
+          No call
+        </button>
+      </div>
+    </div>
+  `,
+})
+export class DateTimePickerControlled {
+  protected readonly call = signal<PlainDateTime | null>(
+    plainDateTime(addDays(TODAY, 1), plainTime(9, 0)),
+  );
+  protected readonly summary = computed(() => {
+    const call = this.call();
+    return call === null ? 'No call scheduled.' : `Call on ${words.describe(call)}.`;
+  });
+
+  protected schedule(days: number, hour: number): void {
+    this.call.set(plainDateTime(addDays(TODAY, days), plainTime(hour, 0)));
+  }
+}
+```
+
+### footer.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import { SlDateTimePicker, SlDateTimePickerFooter } from '@slotted/angular/datetime-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { plainDate, plainDateTime, plainTime } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-datetime-picker-footer',
+  imports: [
+    SlButton,
+    SlDateTimePicker,
+    SlDateTimePickerFooter,
+    SlField,
+    SlFieldDescription,
+    SlFieldLabel,
+  ],
+  template: `
+    <div slField>
+      <label slFieldLabel>Maintenance window starts</label>
+      <div
+        slDateTimePicker
+        #picker="slDateTimePicker"
+        closeOnSelect="never"
+        [defaultValue]="start"
+        [step]="3600"
+      >
+        <div slDateTimePickerFooter>
+          <button slButton size="sm" type="button" (click)="picker.closeSurface()">Done</button>
+        </div>
+      </div>
+      <span slFieldDescription>Conveyors stop for four hours from this time.</span>
+    </div>
+  `,
+})
+export class DateTimePickerFooter {
+  protected readonly start = plainDateTime(plainDate(2026, 10, 3), plainTime(22, 0));
+}
+```
+
+### form.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { toSignal } from '@angular/core/rxjs-interop';
+import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
+import { SlButton } from '@slotted/angular/button';
+import { SlDateTimePicker } from '@slotted/angular/datetime-picker';
+import { SlField, SlFieldError, SlFieldLabel } from '@slotted/angular/field';
+import { SlInline } from '@slotted/angular/inline';
+import { SlStack } from '@slotted/angular/stack';
+import { SlText } from '@slotted/angular/typography';
+import {
+  plainDate,
+  plainDateTime,
+  plainTime,
+  toISODateTime,
+  type PlainDateTime,
+} from '@slotted/core/date';
+
+@Component({
+  selector: 'app-datetime-picker-form',
+  imports: [
+    ReactiveFormsModule,
+    SlButton,
+    SlDateTimePicker,
+    SlField,
+    SlFieldError,
+    SlFieldLabel,
+    SlInline,
+    SlStack,
+    SlText,
+  ],
+  template: `
+    <form novalidate [formGroup]="form" (ngSubmit)="submit()" (reset)="clear()">
+      <div slStack [gap]="5">
+        <div slField required [invalid]="error() === '' ? undefined : true">
+          <label slFieldLabel>Pickup date and time</label>
+          <div
+            slDateTimePicker
+            formControlName="pickupAt"
+            name="pickupAt"
+            [min]="earliest"
+            [referenceDateTime]="earliest"
+          ></div>
+          <span slFieldError live="polite" reserve>{{ error() }}</span>
+        </div>
+        <div slInline align="center" [gap]="3">
+          <button slButton type="submit">Book pickup</button>
+          <button slButton tone="secondary" type="reset" variant="outline">Reset</button>
+          @if (saved(); as message) {
+            <span slText size="sm" tone="muted">{{ message }}</span>
+          }
+        </div>
+      </div>
+    </form>
+  `,
+})
+export class DateTimePickerForm {
+  protected readonly earliest = plainDateTime(plainDate(2026, 10, 1), plainTime(8, 0));
+  protected readonly form = new FormGroup({
+    pickupAt: new FormControl<PlainDateTime | null>(null, Validators.required),
+  });
+  private readonly value = toSignal(this.form.controls.pickupAt.valueChanges, {
+    initialValue: this.form.controls.pickupAt.value,
+  });
+  private readonly submitted = signal(false);
+  protected readonly saved = signal<string | null>(null);
+  protected readonly error = computed(() => {
+    this.value();
+    const control = this.form.controls.pickupAt;
+    if (control.hasError('slottedDateTimeRange')) {
+      return 'Choose October 1, 2026 at 8:00 AM or later.';
+    }
+    if (this.submitted() && control.hasError('required')) return 'Choose a pickup date and time.';
+    return '';
+  });
+
+  protected submit(): void {
+    this.submitted.set(true);
+    const pickup = this.form.controls.pickupAt.value;
+    this.saved.set(
+      this.form.valid && pickup !== null ? `Pickup booked for ${toISODateTime(pickup)}.` : null,
+    );
+  }
+
+  protected clear(): void {
+    this.submitted.set(false);
+    this.saved.set(null);
+  }
+}
+```
+
+### granularity.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDateTimePicker } from '@slotted/angular/datetime-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { plainDate, plainDateTime, plainTime } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-datetime-picker-granularity',
+  imports: [SlDateTimePicker, SlField, SlFieldDescription, SlFieldLabel, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Shift starts</label>
+        <div slDateTimePicker granularity="hour" [defaultValue]="shift" [step]="3600"></div>
+        <span slFieldDescription>Shifts start on the hour.</span>
+      </div>
+      <div slField>
+        <label slFieldLabel>Batch run starts</label>
+        <div
+          slDateTimePicker
+          granularity="second"
+          [defaultValue]="batch"
+          [maxTime]="windowEnd"
+          [minTime]="windowStart"
+          [step]="30"
+        ></div>
+        <span slFieldDescription>The nightly run starts between 2:00:00 and 2:05:00 AM.</span>
+      </div>
+    </div>
+  `,
+})
+export class DateTimePickerGranularity {
+  protected readonly shift = plainDateTime(plainDate(2026, 10, 1), plainTime(6, 0));
+  protected readonly batch = plainDateTime(plainDate(2026, 9, 30), plainTime(2, 0, 30));
+  protected readonly windowStart = plainTime(2, 0);
+  protected readonly windowEnd = plainTime(2, 5);
+}
+```
+
+### hour-cycle.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDateTimePicker } from '@slotted/angular/datetime-picker';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { plainDate, plainDateTime, plainTime } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-datetime-picker-hour-cycle',
+  imports: [SlDateTimePicker, SlField, SlFieldLabel, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Departure, 12-hour clock</label>
+        <div slDateTimePicker [defaultValue]="departure" [hourCycle]="12"></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Departure, 24-hour clock</label>
+        <div slDateTimePicker [defaultValue]="departure" [hourCycle]="24"></div>
+      </div>
+    </div>
+  `,
+})
+export class DateTimePickerHourCycle {
+  protected readonly departure = plainDateTime(plainDate(2026, 9, 30), plainTime(18, 45));
+}
+```
+
+### locale.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDateTimePicker } from '@slotted/angular/datetime-picker';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { plainDate, plainDateTime, plainTime } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-datetime-picker-locale',
+  imports: [SlDateTimePicker, SlField, SlFieldLabel, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Pickup, United States (en-US)</label>
+        <div slDateTimePicker locale="en-US" [defaultValue]="pickup"></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Pickup, United Kingdom (en-GB)</label>
+        <div slDateTimePicker locale="en-GB" [defaultValue]="pickup"></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Pickup, Germany (de-DE)</label>
+        <div slDateTimePicker locale="de-DE" [defaultValue]="pickup"></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Pickup, Japan (ja-JP)</label>
+        <div slDateTimePicker locale="ja-JP" [defaultValue]="pickup"></div>
+      </div>
+    </div>
+  `,
+})
+export class DateTimePickerLocale {
+  protected readonly pickup = plainDateTime(plainDate(2026, 9, 30), plainTime(14, 30));
+}
+```
+
+### options.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDateTimePicker } from '@slotted/angular/datetime-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { plainDate, plainDateTime, plainTime } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-datetime-picker-options',
+  imports: [SlDateTimePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Line-haul departure</label>
+      <div slDateTimePicker [options]="departures" [referenceDateTime]="reference"></div>
+      <span slFieldDescription>The Chicago to Memphis trailer leaves five times a day.</span>
+    </div>
+  `,
+})
+export class DateTimePickerOptions {
+  protected readonly departures = [
+    plainTime(5, 40),
+    plainTime(8, 15),
+    plainTime(11, 50),
+    plainTime(16, 5),
+    plainTime(21, 30),
+  ];
+  protected readonly reference = plainDateTime(plainDate(2026, 9, 30), plainTime(8, 15));
+}
+```
+
+### publish-at.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import { SlDateTimePicker, SlDateTimePickerPresets } from '@slotted/angular/datetime-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import {
+  addDays,
+  createDateTimeFormat,
+  dayOfWeek,
+  plainDate,
+  plainDateTime,
+  plainTime,
+  type PlainDateTime,
+} from '@slotted/core/date';
+
+const NOW = plainDateTime(plainDate(2026, 9, 30), plainTime(9, 0));
+const TOMORROW = plainDateTime(addDays(NOW.date, 1), plainTime(9, 0));
+const NEXT_MONDAY = plainDateTime(
+  addDays(NOW.date, (8 - dayOfWeek(NOW.date)) % 7 || 7),
+  plainTime(9, 0),
+);
+const words = createDateTimeFormat({ locale: 'en-US' });
+
+@Component({
+  selector: 'app-datetime-picker-publish-at',
+  imports: [
+    SlButton,
+    SlDateTimePicker,
+    SlDateTimePickerPresets,
+    SlField,
+    SlFieldDescription,
+    SlFieldLabel,
+  ],
+  template: `
+    <div slField required>
+      <label slFieldLabel>Publish the autumn price list at</label>
+      <div
+        slDateTimePicker
+        #picker="slDateTimePicker"
+        timeZone="America/New_York"
+        [min]="now"
+        [referenceDateTime]="now"
+        [value]="publishAt()"
+        (valueChange)="publishAt.set($event.value)"
+      >
+        <div slDateTimePickerPresets>
+          <button
+            slButton
+            size="sm"
+            type="button"
+            variant="ghost"
+            (click)="publishAt.set(tomorrow); picker.closeSurface()"
+          >
+            Tomorrow, 9:00 AM
+          </button>
+          <button
+            slButton
+            size="sm"
+            type="button"
+            variant="ghost"
+            (click)="publishAt.set(nextMonday); picker.closeSurface()"
+          >
+            Monday, 9:00 AM
+          </button>
+        </div>
+      </div>
+      <span slFieldDescription>{{ summary() }}</span>
+    </div>
+  `,
+})
+export class DateTimePickerPublishAt {
+  protected readonly now = NOW;
+  protected readonly tomorrow = TOMORROW;
+  protected readonly nextMonday = NEXT_MONDAY;
+  protected readonly publishAt = signal<PlainDateTime | null>(TOMORROW);
+  protected readonly summary = computed(() => {
+    const publishAt = this.publishAt();
+    return publishAt === null
+      ? 'Choose when the new prices go live, New York time.'
+      : `Prices go live on ${words.describe(publishAt)}, New York time.`;
+  });
+}
+```
+
+### reference.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { SlDateTimePicker } from '@slotted/angular/datetime-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import {
+  createDateTimeFormat,
+  plainDate,
+  plainDateTime,
+  plainTime,
+  type PlainDateTime,
+} from '@slotted/core/date';
+
+const words = createDateTimeFormat({ locale: 'en-US' });
+
+@Component({
+  selector: 'app-datetime-picker-reference',
+  imports: [SlDateTimePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Courier collection</label>
+      <div
+        slDateTimePicker
+        [referenceDateTime]="endOfShift"
+        [value]="collection()"
+        (valueChange)="collection.set($event.value)"
+      ></div>
+      <span slFieldDescription>{{ summary() }}</span>
+    </div>
+  `,
+})
+export class DateTimePickerReference {
+  protected readonly endOfShift = plainDateTime(plainDate(2026, 10, 1), plainTime(15, 0));
+  protected readonly collection = signal<PlainDateTime | null>(null);
+  protected readonly summary = computed(() => {
+    const collection = this.collection();
+    return collection === null
+      ? 'A day chosen in the calendar opens the time list on 3:00 PM.'
+      : `Collection on ${words.describe(collection)}.`;
+  });
+}
+```
+
+### time-zones.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { SlDateTimePicker } from '@slotted/angular/datetime-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { SlText } from '@slotted/angular/typography';
+import { toISODateTime, wallClockIn, type PlainDateTime } from '@slotted/core/date';
+
+/** The pickup as the server stores it: an instant, 7:00 PM UTC on September 30, 2026. */
+const STORED = Date.UTC(2026, 8, 30, 19, 0);
+
+@Component({
+  selector: 'app-datetime-picker-time-zones',
+  imports: [SlDateTimePicker, SlField, SlFieldDescription, SlFieldLabel, SlStack, SlText],
+  template: `
+    <div slStack [gap]="4">
+      <div slField>
+        <label slFieldLabel>Pickup, Chicago terminal</label>
+        <div
+          slDateTimePicker
+          timeZone="America/Chicago"
+          [value]="pickup()"
+          (valueChange)="pickup.set($event.value)"
+        ></div>
+        <span slFieldDescription>Today and Now follow the clock in Chicago.</span>
+      </div>
+      <span slText size="sm" tone="muted">{{ readout() }}</span>
+    </div>
+  `,
+})
+export class DateTimePickerTimeZones {
+  protected readonly pickup = signal<PlainDateTime | null>(wallClockIn(STORED, 'America/Chicago'));
+  protected readonly readout = computed(() => {
+    const pickup = this.pickup();
+    return pickup === null ? 'Value: null' : `Value: ${toISODateTime(pickup)}, with no offset`;
+  });
+}
+```
+
+### typing.ts
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { SlDateTimePicker } from '@slotted/angular/datetime-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import {
+  plainDate,
+  plainDateTime,
+  plainTime,
+  toISODateTime,
+  type PlainDateTime,
+} from '@slotted/core/date';
+import type { ChangeRequest } from '@slotted/core/state';
+
+const REASONS: Record<string, string> = {
+  keyboard: 'from the keyboard',
+  select: 'chosen in the panel',
+  clear: 'cleared',
+  blur: 'completed when the field lost focus',
+};
+
+@Component({
+  selector: 'app-datetime-picker-typing',
+  imports: [SlDateTimePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Goods received at</label>
+      <div
+        slDateTimePicker
+        [defaultValue]="received"
+        [referenceDateTime]="received"
+        (valueChange)="record($event)"
+      ></div>
+      <span slFieldDescription>{{ change() }}</span>
+    </div>
+  `,
+})
+export class DateTimePickerTyping {
+  protected readonly received = plainDateTime(plainDate(2026, 9, 30), plainTime(14, 30));
+  protected readonly change = signal('No change yet.');
+
+  protected record(request: ChangeRequest<PlainDateTime | null>): void {
+    const text = request.value === null ? 'empty' : toISODateTime(request.value);
+    this.change.set(`${text}, ${REASONS[request.reason] ?? request.reason}.`);
+  }
+}
+```