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

package/docs/date-picker.examples.md

@@ -0,0 +1,1226 @@
+<!-- index: ./index.md -->
+# date-picker
+
+`data-ui="date-picker"` · Date field with a calendar popover.
+
+## Examples
+
+### Playground
+
+A field, a trigger and a calendar, driven by the controls below the canvas. Type into the field, or press the trigger and move through the calendar with the arrow keys: both write the same value.
+
+Excerpt — not a complete module
+
+```html
+<div slField>
+  <label slFieldLabel>Due date</label>
+  <div slDatePicker name="dueDate" (valueChange)="onValue($event)"></div>
+</div>
+```
+
+### Size
+
+The three steps of the control scale. The trigger follows the field: its box is the icon plus one step of space, inside the frame, as in every other control with an inner button.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDatePicker } from '@slotted/angular/date-picker';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { plainDate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-picker-sizes',
+  imports: [SlDatePicker, SlField, SlFieldLabel, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Shipped after</label>
+        <div slDatePicker size="sm" [defaultValue]="shippedAfter"></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Ship date</label>
+        <div slDatePicker size="md" [defaultValue]="shipDate"></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Move-in date</label>
+        <div slDatePicker size="lg" [defaultValue]="moveIn"></div>
+      </div>
+    </div>
+  `,
+})
+export class DatePickerSizes {
+  protected readonly shippedAfter = plainDate(2026, 9, 1);
+  protected readonly shipDate = plainDate(2026, 9, 30);
+  protected readonly moveIn = plainDate(2026, 11, 2);
+}
+```
+
+### Variant
+
+How much frame the field draws at rest. The trigger keeps its calendar icon in all three.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDatePicker } from '@slotted/angular/date-picker';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { plainDate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-picker-variants',
+  imports: [SlDatePicker, SlField, SlFieldLabel, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Invoice date</label>
+        <div slDatePicker variant="outline" [defaultValue]="invoiced"></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Posting date</label>
+        <div slDatePicker variant="subtle" [defaultValue]="invoiced"></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Value date</label>
+        <div slDatePicker variant="plain" [defaultValue]="valueDate"></div>
+      </div>
+    </div>
+  `,
+})
+export class DatePickerVariants {
+  protected readonly invoiced = plainDate(2026, 9, 30);
+  protected readonly valueDate = plainDate(2026, 10, 1);
+}
+```
+
+### Where the surface opens
+
+A preference: when the calendar does not fit on that side, it opens on the other, and data-placement on the positioner records the side it took.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDatePicker } from '@slotted/angular/date-picker';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { plainDate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-picker-placement',
+  imports: [SlDatePicker, SlField, SlFieldLabel, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Opens above, from the start edge</label>
+        <div slDatePicker placement="top-start" [defaultValue]="today"></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Opens below, from the end edge</label>
+        <div slDatePicker placement="bottom-end" [defaultValue]="today"></div>
+      </div>
+    </div>
+  `,
+})
+export class DatePickerPlacement {
+  protected readonly today = plainDate(2026, 9, 30);
+}
+```
+
+### Bounds
+
+min and max bound the field and the calendar together: the calendar disables the days outside them, and a typed date outside them marks the date picker invalid.
+
+Excerpt — not a complete module
+
+```html
+<div slDatePicker [min]="first" [max]="last"></div>
+```
+
+### Days that are refused
+
+One function reaches the field and the calendar. A refused date marks the date picker invalid when it is typed, and is disabled in the calendar.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDatePicker } from '@slotted/angular/date-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { dayOfWeek, plainDate, toISODate, type PlainDate } from '@slotted/core/date';
+
+/** Columbus Day, Veterans Day, Thanksgiving and Christmas Day, 2026. */
+const HOLIDAYS = new Set(['2026-10-12', '2026-11-11', '2026-11-26', '2026-12-25']);
+
+const isClosed = (date: PlainDate) =>
+  dayOfWeek(date) === 0 || dayOfWeek(date) === 6 || HOLIDAYS.has(toISODate(date));
+
+@Component({
+  selector: 'app-date-picker-unavailable',
+  imports: [SlDatePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Pickup date</label>
+      <div slDatePicker [defaultValue]="pickup" [isDateUnavailable]="isClosed"></div>
+      <span slFieldDescription>The Reno dock is closed on weekends and federal holidays.</span>
+    </div>
+  `,
+})
+export class DatePickerUnavailable {
+  protected readonly pickup = plainDate(2026, 10, 13);
+  protected readonly isClosed = isClosed;
+}
+```
+
+### Shortcuts and actions
+
+The two slots you fill: shortcuts beside the calendar and actions under it. The Date Picker ships no list of shortcuts, because the labels and dates belong to your product.
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import type { CalendarValue } from '@slotted/angular/calendar';
+import { SlDatePicker, SlDatePickerPresets } from '@slotted/angular/date-picker';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { addDays, isPlainDate, plainDate, type PlainDate } from '@slotted/core/date';
+
+const TODAY = plainDate(2026, 9, 30);
+
+const PRESETS = [
+  { label: 'Today', date: TODAY },
+  { label: 'Tomorrow', date: addDays(TODAY, 1) },
+  { label: 'Next Monday', date: plainDate(2026, 10, 5) },
+  { label: 'In 2 weeks', date: addDays(TODAY, 14) },
+];
+
+@Component({
+  selector: 'app-date-picker-presets',
+  imports: [SlButton, SlDatePicker, SlDatePickerPresets, SlField, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Dispatch date</label>
+      <div slDatePicker #picker="slDatePicker" [value]="date()" (valueChange)="set($event.value)">
+        <div slDatePickerPresets>
+          @for (preset of presets; track preset.label) {
+            <button
+              slButton
+              size="sm"
+              variant="ghost"
+              type="button"
+              (click)="date.set(preset.date); picker.closeSurface()"
+            >
+              {{ preset.label }}
+            </button>
+          }
+        </div>
+      </div>
+    </div>
+  `,
+})
+export class DatePickerPresets {
+  protected readonly presets = PRESETS;
+  protected readonly date = signal<PlainDate | null>(TODAY);
+
+  protected set(value: CalendarValue): void {
+    this.date.set(isPlainDate(value) ? value : null);
+  }
+}
+```
+
+### States
+
+Disabled and read-only both disable the trigger, so the calendar cannot open. Invalid draws the frame and the focus ring in the danger tone.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDatePicker } from '@slotted/angular/date-picker';
+import { SlField, SlFieldDescription, SlFieldError, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { plainDate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-picker-states',
+  imports: [SlDatePicker, SlField, SlFieldDescription, SlFieldError, SlFieldLabel, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      <div slField invalid required>
+        <label slFieldLabel>Delivery date</label>
+        <div slDatePicker [defaultValue]="delivery"></div>
+        <span slFieldError>The delivery date is before the order date, September 30, 2026.</span>
+      </div>
+      <div slField readOnly>
+        <label slFieldLabel>Order date</label>
+        <div slDatePicker [defaultValue]="ordered"></div>
+        <span slFieldDescription>Set when the order was placed.</span>
+      </div>
+      <div slField disabled>
+        <label slFieldLabel>Return by</label>
+        <div slDatePicker [defaultValue]="returnBy"></div>
+        <span slFieldDescription>Returns open once the order is delivered.</span>
+      </div>
+    </div>
+  `,
+})
+export class DatePickerStates {
+  protected readonly delivery = plainDate(2026, 9, 28);
+  protected readonly ordered = plainDate(2026, 9, 30);
+  protected readonly returnBy = plainDate(2026, 10, 30);
+}
+```
+
+### In a form
+
+name adds a hidden input that submits the date as an ISO 8601 string, so a plain form post sends 2026-09-09 whether the reader typed the date or chose it. formControlName binds it to a reactive form.
+
+Excerpt — not a complete module
+
+```html
+<form action="/bookings" method="post">
+  <div slDatePicker name="checkIn" required></div>
+  <button type="submit">Book</button>
+</form>
+```
+
+### On a narrow touch screen
+
+Under 480 pixels on a coarse pointer, the calendar opens as a sheet attached to the bottom of the viewport. The markup stays the same, and data-presentation on the positioner records which presentation is showing.
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import type { CalendarValue } from '@slotted/angular/calendar';
+import { SlDatePicker, SlDatePickerPresets } from '@slotted/angular/date-picker';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { addDays, isPlainDate, plainDate, type PlainDate } from '@slotted/core/date';
+
+const TODAY = plainDate(2026, 9, 30);
+
+@Component({
+  selector: 'app-date-picker-narrow',
+  imports: [SlButton, SlDatePicker, SlDatePickerPresets, SlField, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Proof of delivery date</label>
+      <div slDatePicker #picker="slDatePicker" [value]="date()" (valueChange)="set($event.value)">
+        <div slDatePickerPresets>
+          <button
+            slButton
+            size="sm"
+            variant="ghost"
+            type="button"
+            (click)="date.set(today); picker.closeSurface()"
+          >
+            Today
+          </button>
+          <button
+            slButton
+            size="sm"
+            variant="ghost"
+            type="button"
+            (click)="date.set(yesterday); picker.closeSurface()"
+          >
+            Yesterday
+          </button>
+        </div>
+      </div>
+    </div>
+  `,
+})
+export class DatePickerNarrow {
+  protected readonly today = TODAY;
+  protected readonly yesterday = addDays(TODAY, -1);
+  protected readonly date = signal<PlainDate | null>(null);
+
+  protected set(value: CalendarValue): void {
+    this.date.set(isPlainDate(value) ? value : null);
+  }
+}
+```
+
+### Composition and escape hatches
+
+provideDatePickerDefaults sets the time zone and the placement once, provideSlotted sets the language and the trigger’s names, exportAs returns focus(), openSurface() and closeSurface(), and cancel() refuses a value before it is applied.
+
+Excerpt — not a complete module
+
+```html
+<div slDatePicker #picker="slDatePicker" (valueChange)="$event.cancel()"></div>
+<button type="button" (click)="picker.openSurface()">Open calendar</button>
+```
+
+### The keyboard
+
+Alt+ArrowDown opens the calendar from the field and moves focus to the chosen day. Escape closes it and returns focus to the trigger; while the calendar shows months or years, Escape first returns to the day grid.
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { SlDatePicker } from '@slotted/angular/date-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { plainDate } from '@slotted/core/date';
+import type { ChangeRequest } from '@slotted/core/state';
+
+@Component({
+  selector: 'app-date-picker-keyboard',
+  imports: [SlDatePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Dispatch date</label>
+      <div
+        slDatePicker
+        [defaultValue]="dispatch"
+        [messages]="messages"
+        (openChange)="record($event)"
+      ></div>
+      <span slFieldDescription>{{ last() }}</span>
+    </div>
+  `,
+})
+export class DatePickerKeyboard {
+  protected readonly dispatch = plainDate(2026, 9, 30);
+  protected readonly messages = {
+    choose: 'Choose dispatch date',
+    change: 'Change dispatch date, {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 { SlDatePicker } from '@slotted/angular/date-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { plainDate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-picker-bounds',
+  imports: [SlDatePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Delivery window</label>
+      <div slDatePicker [defaultValue]="delivery" [max]="last" [min]="first"></div>
+      <span slFieldDescription>Carriers book October 2026 only.</span>
+    </div>
+  `,
+})
+export class DatePickerBounds {
+  protected readonly delivery = plainDate(2026, 10, 15);
+  protected readonly first = plainDate(2026, 10, 1);
+  protected readonly last = plainDate(2026, 10, 31);
+}
+```
+
+### clearable.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDatePicker } from '@slotted/angular/date-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { plainDate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-picker-clearable',
+  imports: [SlDatePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Hold shipment until</label>
+      <div slDatePicker clearable [defaultValue]="holdUntil"></div>
+      <span slFieldDescription>Clear the date to release the shipment.</span>
+    </div>
+  `,
+})
+export class DatePickerClearable {
+  protected readonly holdUntil = plainDate(2026, 10, 9);
+}
+```
+
+### controlled.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import type { CalendarValue } from '@slotted/angular/calendar';
+import { SlDatePicker } from '@slotted/angular/date-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlInline } from '@slotted/angular/inline';
+import { SlStack } from '@slotted/angular/stack';
+import {
+  addDays,
+  createDateFormat,
+  isPlainDate,
+  plainDate,
+  type PlainDate,
+} from '@slotted/core/date';
+
+const TODAY = plainDate(2026, 9, 30);
+const words = createDateFormat({ locale: 'en-US' });
+
+@Component({
+  selector: 'app-date-picker-controlled',
+  imports: [SlButton, SlDatePicker, SlField, SlFieldDescription, SlFieldLabel, SlInline, SlStack],
+  template: `
+    <div slStack [gap]="4">
+      <div slField>
+        <label slFieldLabel>Follow up with Harbor Freightways</label>
+        <div slDatePicker [value]="followUp()" (valueChange)="set($event.value)"></div>
+        <span slFieldDescription>{{ summary() }}</span>
+      </div>
+      <div slInline [gap]="2">
+        <button
+          slButton
+          size="sm"
+          tone="secondary"
+          variant="outline"
+          type="button"
+          (click)="inDays(7)"
+        >
+          In 1 week
+        </button>
+        <button
+          slButton
+          size="sm"
+          tone="secondary"
+          variant="outline"
+          type="button"
+          (click)="inDays(14)"
+        >
+          In 2 weeks
+        </button>
+        <button
+          slButton
+          size="sm"
+          tone="secondary"
+          variant="ghost"
+          type="button"
+          (click)="followUp.set(null)"
+        >
+          No follow-up
+        </button>
+      </div>
+    </div>
+  `,
+})
+export class DatePickerControlled {
+  protected readonly followUp = signal<PlainDate | null>(addDays(TODAY, 7));
+  protected readonly summary = computed(() => {
+    const date = this.followUp();
+    return date === null ? 'No follow-up scheduled.' : `Reminder on ${words.describe(date)}.`;
+  });
+
+  protected set(value: CalendarValue): void {
+    this.followUp.set(isPlainDate(value) ? value : null);
+  }
+
+  protected inDays(days: number): void {
+    this.followUp.set(addDays(TODAY, days));
+  }
+}
+```
+
+### default-view.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDatePicker } from '@slotted/angular/date-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { plainDate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-picker-default-view',
+  imports: [SlDatePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Date of incorporation</label>
+      <div slDatePicker defaultView="year" [max]="today"></div>
+      <span slFieldDescription>As printed on the certificate of incorporation.</span>
+    </div>
+  `,
+})
+export class DatePickerDefaultView {
+  protected readonly today = plainDate(2026, 9, 30);
+}
+```
+
+### defaults.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { provideDatePickerDefaults, SlDatePicker } from '@slotted/angular/date-picker';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { plainDate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-picker-defaults',
+  imports: [SlDatePicker, SlField, SlFieldLabel, SlStack],
+  providers: [
+    provideDatePickerDefaults({ size: 'sm', variant: 'subtle', placement: 'bottom-end' }),
+  ],
+  template: `
+    <div slStack [gap]="4">
+      <div slField>
+        <label slFieldLabel>Posted after</label>
+        <div slDatePicker [defaultValue]="postedAfter"></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Due before</label>
+        <div slDatePicker [defaultValue]="dueBefore"></div>
+      </div>
+    </div>
+  `,
+})
+export class DatePickerDefaults {
+  protected readonly postedAfter = plainDate(2026, 9, 1);
+  protected readonly dueBefore = plainDate(2026, 10, 31);
+}
+```
+
+### first-day.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDatePicker } from '@slotted/angular/date-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { plainDate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-picker-first-day',
+  imports: [SlDatePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Shift starts</label>
+      <div slDatePicker locale="en-US" [defaultValue]="shift" [firstDayOfWeek]="1"></div>
+      <span slFieldDescription>Rosters run Monday to Sunday.</span>
+    </div>
+  `,
+})
+export class DatePickerFirstDay {
+  protected readonly shift = plainDate(2026, 9, 30);
+}
+```
+
+### focus-and-open.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import { SlDatePicker } from '@slotted/angular/date-picker';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlInline } from '@slotted/angular/inline';
+import { SlStack } from '@slotted/angular/stack';
+import { plainDate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-picker-focus-and-open',
+  imports: [SlButton, SlDatePicker, SlField, SlFieldLabel, SlInline, SlStack],
+  template: `
+    <div slStack [gap]="4">
+      <div slField>
+        <label slFieldLabel>Contract renewal date</label>
+        <div slDatePicker #picker="slDatePicker" [defaultValue]="renewal"></div>
+      </div>
+      <div slInline [gap]="2">
+        <button
+          slButton
+          size="sm"
+          tone="secondary"
+          variant="outline"
+          type="button"
+          (click)="picker.focus()"
+        >
+          Edit date
+        </button>
+        <button
+          slButton
+          size="sm"
+          tone="secondary"
+          variant="outline"
+          type="button"
+          (click)="picker.openSurface()"
+        >
+          Open calendar
+        </button>
+      </div>
+    </div>
+  `,
+})
+export class DatePickerFocusAndOpen {
+  protected readonly renewal = plainDate(2027, 3, 31);
+}
+```
+
+### footer.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import { SlDatePicker, SlDatePickerFooter } from '@slotted/angular/date-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { plainDate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-picker-footer',
+  imports: [SlButton, SlDatePicker, SlDatePickerFooter, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Stock count date</label>
+      <div slDatePicker #picker="slDatePicker" closeOnSelect="never" [defaultValue]="count">
+        <div slDatePickerFooter>
+          <button slButton size="sm" type="button" (click)="picker.closeSurface()">Done</button>
+        </div>
+      </div>
+      <span slFieldDescription>The calendar stays open until you press Done.</span>
+    </div>
+  `,
+})
+export class DatePickerFooter {
+  protected readonly count = plainDate(2026, 10, 3);
+}
+```
+
+### 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 { SlDatePicker } from '@slotted/angular/date-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, toISODate, type PlainDate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-picker-form',
+  imports: [
+    ReactiveFormsModule,
+    SlButton,
+    SlDatePicker,
+    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>Delivery date</label>
+          <div
+            slDatePicker
+            name="deliveryDate"
+            formControlName="deliveryDate"
+            [min]="earliest"
+          ></div>
+          <span slFieldError live="polite" reserve>{{ error() }}</span>
+        </div>
+        <div slInline [gap]="3" align="center">
+          <button slButton type="submit">Book delivery</button>
+          <button slButton type="reset" tone="secondary" variant="outline">Reset</button>
+          @if (saved(); as message) {
+            <span slText size="sm" tone="muted">{{ message }}</span>
+          }
+        </div>
+      </div>
+    </form>
+  `,
+})
+export class DatePickerForm {
+  protected readonly earliest = plainDate(2026, 10, 1);
+  protected readonly form = new FormGroup({
+    deliveryDate: new FormControl<PlainDate | null>(null, Validators.required),
+  });
+  private readonly value = toSignal(this.form.controls.deliveryDate.valueChanges, {
+    initialValue: this.form.controls.deliveryDate.value,
+  });
+  private readonly submitted = signal(false);
+  protected readonly saved = signal<string | null>(null);
+  protected readonly error = computed(() => {
+    this.value();
+    const control = this.form.controls.deliveryDate;
+    if (control.hasError('slottedDateRange')) return 'Choose October 1, 2026 or later.';
+    if (this.submitted() && control.hasError('required')) return 'Choose a delivery date.';
+    return '';
+  });
+
+  protected submit(): void {
+    this.submitted.set(true);
+    const date = this.form.controls.deliveryDate.value;
+    this.saved.set(
+      this.form.valid && date !== null ? `Delivery booked for ${toISODate(date)}.` : null,
+    );
+  }
+
+  protected clear(): void {
+    this.submitted.set(false);
+    this.saved.set(null);
+  }
+}
+```
+
+### invoice-due.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import type { CalendarValue } from '@slotted/angular/calendar';
+import { SlDatePicker } from '@slotted/angular/date-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlSelect, SlSelectItem, type SelectSelection } from '@slotted/angular/select';
+import { SlStack } from '@slotted/angular/stack';
+import {
+  addDays,
+  createDateFormat,
+  isPlainDate,
+  plainDate,
+  type PlainDate,
+} from '@slotted/core/date';
+
+const TERMS = [
+  { value: 'receipt', label: 'Due on receipt', days: 0 },
+  { value: 'net-15', label: 'Net 15', days: 15 },
+  { value: 'net-30', label: 'Net 30', days: 30 },
+  { value: 'net-60', label: 'Net 60', days: 60 },
+];
+const words = createDateFormat({ locale: 'en-US' });
+
+@Component({
+  selector: 'app-date-picker-invoice-due',
+  imports: [
+    SlDatePicker,
+    SlField,
+    SlFieldDescription,
+    SlFieldLabel,
+    SlSelect,
+    SlSelectItem,
+    SlStack,
+  ],
+  template: `
+    <div slStack [gap]="5">
+      <div slField required>
+        <label slFieldLabel>Invoice date</label>
+        <div slDatePicker [value]="issued()" (valueChange)="setIssued($event.value)"></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Payment terms</label>
+        <sl-select [items]="terms" [(value)]="term">
+          @for (option of terms; track option.value) {
+            <sl-select-item [value]="option.value">{{ option.label }}</sl-select-item>
+          }
+        </sl-select>
+      </div>
+      <div slField readOnly>
+        <label slFieldLabel>Due date</label>
+        <div slDatePicker [value]="due()"></div>
+        <span slFieldDescription>{{ summary() }}</span>
+      </div>
+    </div>
+  `,
+})
+export class DatePickerInvoiceDue {
+  protected readonly terms = TERMS;
+  protected readonly issued = signal<PlainDate | null>(plainDate(2026, 9, 30));
+  protected readonly term = signal<SelectSelection>('net-30');
+  protected readonly due = computed(() => {
+    const issued = this.issued();
+    const days = TERMS.find((option) => option.value === this.term())?.days ?? 0;
+    return issued === null ? null : addDays(issued, days);
+  });
+  protected readonly summary = computed(() => {
+    const due = this.due();
+    return due === null ? 'Set the invoice date first.' : `Payment is due ${words.describe(due)}.`;
+  });
+
+  protected setIssued(value: CalendarValue): void {
+    this.issued.set(isPlainDate(value) ? value : null);
+  }
+}
+```
+
+### locale.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDatePicker } from '@slotted/angular/date-picker';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { plainDate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-picker-locale',
+  imports: [SlDatePicker, SlField, SlFieldLabel, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Ship date, United States (en-US)</label>
+        <div slDatePicker locale="en-US" [defaultValue]="shipDate"></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Ship date, United Kingdom (en-GB)</label>
+        <div slDatePicker locale="en-GB" [defaultValue]="shipDate"></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Ship date, Germany (de-DE)</label>
+        <div slDatePicker locale="de-DE" [defaultValue]="shipDate"></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Ship date, Japan (ja-JP)</label>
+        <div slDatePicker locale="ja-JP" [defaultValue]="shipDate"></div>
+      </div>
+    </div>
+  `,
+})
+export class DatePickerLocale {
+  protected readonly shipDate = plainDate(2026, 9, 30);
+}
+```
+
+### months.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDatePicker } from '@slotted/angular/date-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { plainDate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-picker-months',
+  imports: [SlDatePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Installation appointment</label>
+      <div slDatePicker [defaultValue]="appointment" [months]="2"></div>
+      <span slFieldDescription>Technicians book up to eight weeks ahead.</span>
+    </div>
+  `,
+})
+export class DatePickerMonths {
+  protected readonly appointment = plainDate(2026, 10, 20);
+}
+```
+
+### report-date.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import type { CalendarValue } from '@slotted/angular/calendar';
+import { SlDatePicker, SlDatePickerPresets } from '@slotted/angular/date-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { createDateFormat, isPlainDate, plainDate, type PlainDate } from '@slotted/core/date';
+
+const TODAY = plainDate(2026, 9, 30);
+const PRESETS = [
+  { label: 'Today', date: TODAY },
+  { label: 'End of last month', date: plainDate(2026, 8, 31) },
+  { label: 'End of last quarter', date: plainDate(2026, 6, 30) },
+  { label: 'End of fiscal 2025', date: plainDate(2025, 12, 31) },
+];
+const words = createDateFormat({ locale: 'en-US' });
+
+@Component({
+  selector: 'app-date-picker-report-date',
+  imports: [SlButton, SlDatePicker, SlDatePickerPresets, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Balance sheet as of</label>
+      <div
+        slDatePicker
+        #picker="slDatePicker"
+        [max]="today"
+        [value]="asOf()"
+        (valueChange)="set($event.value)"
+      >
+        <div slDatePickerPresets>
+          @for (preset of presets; track preset.label) {
+            <button
+              slButton
+              size="sm"
+              variant="ghost"
+              type="button"
+              (click)="asOf.set(preset.date); picker.closeSurface()"
+            >
+              {{ preset.label }}
+            </button>
+          }
+        </div>
+      </div>
+      <span slFieldDescription>{{ summary() }}</span>
+    </div>
+  `,
+})
+export class DatePickerReportDate {
+  protected readonly today = TODAY;
+  protected readonly presets = PRESETS;
+  protected readonly asOf = signal<PlainDate | null>(plainDate(2026, 8, 31));
+  protected readonly summary = computed(() => {
+    const asOf = this.asOf();
+    return asOf === null
+      ? 'Choose the closing date of the report.'
+      : `Balances close at the end of ${words.describe(asOf)}.`;
+  });
+
+  protected set(value: CalendarValue): void {
+    this.asOf.set(isPlainDate(value) ? value : null);
+  }
+}
+```
+
+### shipping-date.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import type { CalendarValue } from '@slotted/angular/calendar';
+import { SlDatePicker } from '@slotted/angular/date-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import {
+  addDays,
+  compareDate,
+  createDateFormat,
+  dayOfWeek,
+  isPlainDate,
+  plainDate,
+  toISODate,
+  type PlainDate,
+} from '@slotted/core/date';
+
+const ORDERED = plainDate(2026, 9, 30);
+const HOLIDAYS = new Set(['2026-10-12', '2026-11-11', '2026-11-26', '2026-12-25']);
+const words = createDateFormat({ locale: 'en-US' });
+
+const isBusinessDay = (date: PlainDate) =>
+  dayOfWeek(date) !== 0 && dayOfWeek(date) !== 6 && !HOLIDAYS.has(toISODate(date));
+
+const addBusinessDays = (from: PlainDate, count: number) => {
+  let date = from;
+  for (let added = 0; added < count;) {
+    date = addDays(date, 1);
+    if (isBusinessDay(date)) added += 1;
+  }
+  return date;
+};
+
+const businessDaysBetween = (from: PlainDate, to: PlainDate) => {
+  let count = 0;
+  for (let date = addDays(from, 1); compareDate(date, to) <= 0; date = addDays(date, 1)) {
+    if (isBusinessDay(date)) count += 1;
+  }
+  return count;
+};
+
+const EARLIEST = addBusinessDays(ORDERED, 2);
+const LATEST = addBusinessDays(ORDERED, 40);
+
+@Component({
+  selector: 'app-date-picker-shipping-date',
+  imports: [SlDatePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField required>
+      <label slFieldLabel>Ship date</label>
+      <div
+        slDatePicker
+        [isDateUnavailable]="isClosed"
+        [max]="latest"
+        [min]="earliest"
+        [value]="date()"
+        (valueChange)="set($event.value)"
+      ></div>
+      <span slFieldDescription>{{ summary() }}</span>
+    </div>
+  `,
+})
+export class DatePickerShippingDate {
+  protected readonly earliest = EARLIEST;
+  protected readonly latest = LATEST;
+  protected readonly isClosed = (day: PlainDate) => !isBusinessDay(day);
+  protected readonly date = signal<PlainDate | null>(EARLIEST);
+  protected readonly summary = computed(() => {
+    const date = this.date();
+    return date === null
+      ? 'Orders ship 2 to 40 business days after they are placed.'
+      : `Ships ${words.describe(date)}, ${businessDaysBetween(ORDERED, date)} business days after the order.`;
+  });
+
+  protected set(value: CalendarValue): void {
+    this.date.set(isPlainDate(value) ? value : null);
+  }
+}
+```
+
+### time-zones.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import type { CalendarValue } from '@slotted/angular/calendar';
+import { SlDatePicker } from '@slotted/angular/date-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { SlText } from '@slotted/angular/typography';
+import { isPlainDate, plainDate, toISODate, type PlainDate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-picker-time-zones',
+  imports: [SlDatePicker, SlField, SlFieldDescription, SlFieldLabel, SlStack, SlText],
+  template: `
+    <div slStack [gap]="4">
+      <div slField>
+        <label slFieldLabel>Settlement date, Auckland desk</label>
+        <div
+          slDatePicker
+          timeZone="Pacific/Auckland"
+          [value]="date()"
+          (valueChange)="set($event.value)"
+        ></div>
+        <span slFieldDescription>Today is marked by the date in Auckland.</span>
+      </div>
+      <span slText size="sm" tone="muted">{{ readout() }}</span>
+    </div>
+  `,
+})
+export class DatePickerTimeZones {
+  protected readonly date = signal<PlainDate | null>(plainDate(2026, 9, 30));
+  protected readonly readout = computed(() => {
+    const date = this.date();
+    return date === null
+      ? 'Value: null'
+      : `Value: ${JSON.stringify(date)}, sent as ${toISODate(date)}`;
+  });
+
+  protected set(value: CalendarValue): void {
+    this.date.set(isPlainDate(value) ? value : null);
+  }
+}
+```
+
+### typing.ts
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import type { CalendarValue } from '@slotted/angular/calendar';
+import { SlDatePicker } from '@slotted/angular/date-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { isPlainDate, plainDate, toISODate } from '@slotted/core/date';
+import type { ChangeRequest } from '@slotted/core/state';
+
+const REASONS: Record<string, string> = {
+  keyboard: 'from the keyboard',
+  pointer: 'pressed in the calendar',
+  clear: 'cleared',
+  blur: 'completed when the field lost focus',
+};
+
+@Component({
+  selector: 'app-date-picker-typing',
+  imports: [SlDatePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Goods received on</label>
+      <div slDatePicker [defaultValue]="received" (valueChange)="record($event)"></div>
+      <span slFieldDescription>{{ change() }}</span>
+    </div>
+  `,
+})
+export class DatePickerTyping {
+  protected readonly received = plainDate(2026, 9, 30);
+  protected readonly change = signal('No change yet.');
+
+  protected record(request: ChangeRequest<CalendarValue>): void {
+    const date = isPlainDate(request.value) ? toISODate(request.value) : 'empty';
+    this.change.set(`${date}, ${REASONS[request.reason] ?? request.reason}.`);
+  }
+}
+```
+
+### week-numbers.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import type { CalendarValue } from '@slotted/angular/calendar';
+import { SlDatePicker } from '@slotted/angular/date-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { isPlainDate, isoWeekNumber, plainDate, type PlainDate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-picker-week-numbers',
+  imports: [SlDatePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Production run</label>
+      <div
+        slDatePicker
+        weekNumbers
+        [firstDayOfWeek]="1"
+        [value]="date()"
+        (valueChange)="set($event.value)"
+      ></div>
+      <span slFieldDescription>{{ summary() }}</span>
+    </div>
+  `,
+})
+export class DatePickerWeekNumbers {
+  protected readonly date = signal<PlainDate | null>(plainDate(2026, 9, 30));
+
+  protected set(value: CalendarValue): void {
+    this.date.set(isPlainDate(value) ? value : null);
+  }
+
+  protected readonly summary = computed(() => {
+    const date = this.date();
+    return date === null ? 'No week planned.' : `Planned for week ${isoWeekNumber(date)}.`;
+  });
+}
+```