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

package/docs/date-range-picker.examples.md

@@ -0,0 +1,1300 @@
+<!-- index: ./index.md -->
+# date-range-picker
+
+`data-ui="date-range-picker"` · Start and end dates with a calendar popover.
+
+## Examples
+
+### Playground
+
+Check-in and check-out in one frame, driven by the controls below the canvas. Type into either field, or press the trigger and choose two days: while the range is drawn, the band above the calendar says how many nights it holds.
+
+Excerpt — not a complete module
+
+```html
+<div slField>
+  <label slFieldLabel>Stay</label>
+  <div
+    slDateRangePicker
+    count="nights"
+    startName="checkin"
+    endName="checkout"
+    [value]="value"
+    (valueChange)="value = $event.value"
+  ></div>
+</div>
+```
+
+### Size
+
+The three steps of the control scale. Both fields, the dash and the trigger follow the step together, so a range in a dense table shrinks as one control.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDateRangePicker } from '@slotted/angular/date-range-picker';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { plainDate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-range-picker-sizes',
+  imports: [SlDateRangePicker, SlField, SlFieldLabel, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Created between</label>
+        <div slDateRangePicker size="sm" [defaultValue]="created"></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Billing period</label>
+        <div slDateRangePicker size="md" [defaultValue]="billing"></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Lease term</label>
+        <div slDateRangePicker size="lg" [defaultValue]="lease"></div>
+      </div>
+    </div>
+  `,
+})
+export class DateRangePickerSizes {
+  protected readonly created = { start: plainDate(2026, 9, 1), end: plainDate(2026, 9, 30) };
+  protected readonly billing = { start: plainDate(2026, 10, 1), end: plainDate(2026, 10, 31) };
+  protected readonly lease = { start: plainDate(2026, 11, 1), end: plainDate(2027, 10, 31) };
+}
+```
+
+### Variant
+
+How much frame the control draws at rest. The two fields inside are plain, and the one frame answers hover, focus and invalid for both.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDateRangePicker } from '@slotted/angular/date-range-picker';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { plainDate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-range-picker-variants',
+  imports: [SlDateRangePicker, SlField, SlFieldLabel, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Outline</label>
+        <div slDateRangePicker variant="outline" [defaultValue]="quarter"></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Subtle</label>
+        <div slDateRangePicker variant="subtle" [defaultValue]="quarter"></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Plain</label>
+        <div slDateRangePicker variant="plain" [defaultValue]="quarter"></div>
+      </div>
+    </div>
+  `,
+})
+export class DateRangePickerVariants {
+  protected readonly quarter = { start: plainDate(2026, 7, 1), end: plainDate(2026, 9, 30) };
+}
+```
+
+### The length while the range is drawn
+
+Open the calendar and choose a start: the band follows the pointer and the focused day, and says the length of the range the next press would make. count decides the unit: a stay counts nights and a leave request counts days, so the same two dates give 4 nights or 5 days.
+
+Excerpt — not a complete module
+
+```html
+<div slDateRangePicker count="nights"></div>
+<div slDateRangePicker count="days"></div>
+```
+
+### Length limits
+
+A stay of two to seven nights. Once a check-in is chosen, the calendar disables the days that would break the rule and the band names it; a typed range outside it marks the frame invalid. minLength and maxLength count in the unit count names.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDateRangePicker } from '@slotted/angular/date-range-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+
+@Component({
+  selector: 'app-date-range-picker-limits',
+  imports: [SlDateRangePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Forklift rental</label>
+      <div slDateRangePicker [minLength]="2" [maxLength]="14"></div>
+      <span slFieldDescription>Rentals run from 2 to 14 days.</span>
+    </div>
+  `,
+})
+export class DateRangePickerLimits {}
+```
+
+### Unavailable days
+
+The room is taken from the 15th to the 18th. Choose a check-in before it: the calendar disables the nights past the first taken day, because a range runs without gaps. [contiguous]="false" lets a range run across an unavailable day and checks only its two ends.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDateRangePicker } from '@slotted/angular/date-range-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { compareDate, plainDate, type PlainDate } from '@slotted/core/date';
+
+const BOOKED_FROM = plainDate(2026, 10, 14);
+const BOOKED_TO = plainDate(2026, 10, 16);
+
+const isBooked = (date: PlainDate) =>
+  compareDate(date, BOOKED_FROM) >= 0 && compareDate(date, BOOKED_TO) <= 0;
+
+@Component({
+  selector: 'app-date-range-picker-unavailable',
+  imports: [SlDateRangePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Training room</label>
+      <div slDateRangePicker [isDateUnavailable]="isBooked"></div>
+      <span slFieldDescription>
+        Booked October 14 to 16. A booking cannot run across those days.
+      </span>
+    </div>
+  `,
+})
+export class DateRangePickerUnavailable {
+  protected readonly isBooked = isBooked;
+}
+```
+
+### Presets
+
+The stays a hotel offers by name. Each is a button with slDateRangePickerPreset and its own range; pressing one writes the value and closes the calendar, and the one equal to the value carries data-selected. The list belongs to the product.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import {
+  SlDateRangePicker,
+  SlDateRangePickerPreset,
+  SlDateRangePickerPresets,
+  type DateRange,
+} from '@slotted/angular/date-range-picker';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { addDays, plainDate } from '@slotted/core/date';
+
+const TODAY = plainDate(2026, 9, 30);
+
+const LAST_30_DAYS: DateRange = { start: addDays(TODAY, -29), end: TODAY };
+
+const PRESETS: { label: string; range: DateRange }[] = [
+  { label: 'Last 7 days', range: { start: addDays(TODAY, -6), end: TODAY } },
+  { label: 'Last 30 days', range: LAST_30_DAYS },
+  { label: 'This quarter', range: { start: plainDate(2026, 7, 1), end: TODAY } },
+  { label: 'Last quarter', range: { start: plainDate(2026, 4, 1), end: plainDate(2026, 6, 30) } },
+  { label: 'Year to date', range: { start: plainDate(2026, 1, 1), end: TODAY } },
+];
+
+@Component({
+  selector: 'app-date-range-picker-presets',
+  imports: [
+    SlDateRangePicker,
+    SlDateRangePickerPreset,
+    SlDateRangePickerPresets,
+    SlField,
+    SlFieldLabel,
+  ],
+  template: `
+    <div slField>
+      <label slFieldLabel>Report period</label>
+      <div slDateRangePicker [defaultValue]="last30Days" [max]="today">
+        <div slDateRangePickerPresets>
+          @for (preset of presets; track preset.label) {
+            <button [slDateRangePickerPreset]="preset.range">{{ preset.label }}</button>
+          }
+        </div>
+      </div>
+    </div>
+  `,
+})
+export class DateRangePickerPresets {
+  protected readonly today = TODAY;
+  protected readonly last30Days = LAST_30_DAYS;
+  protected readonly presets = PRESETS;
+}
+```
+
+### An open end
+
+A check-in without a check-out is a value, { start, end: null }, and the field shows it. Open the calendar over it and the first press writes the missing end. required asks for both ends.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDateRangePicker } from '@slotted/angular/date-range-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { plainDate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-range-picker-open-end',
+  imports: [SlDateRangePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Price valid</label>
+      <div slDateRangePicker clearable [defaultValue]="validity"></div>
+      <span slFieldDescription>Leave the end empty for a price with no end date.</span>
+    </div>
+  `,
+})
+export class DateRangePickerOpenEnd {
+  protected readonly validity = { start: plainDate(2026, 10, 1), end: null };
+}
+```
+
+### States
+
+Read-only keeps the dates legible and copyable and disables the buttons; disabled disables everything and keeps the dates readable; a check-out before its check-in is invalid on the end field and on the frame, and the ends are not swapped; required reaches both fields.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDateRangePicker } from '@slotted/angular/date-range-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-range-picker-states',
+  imports: [SlDateRangePicker, SlField, SlFieldDescription, SlFieldError, SlFieldLabel, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      <div slField invalid required>
+        <label slFieldLabel>Campaign dates</label>
+        <div slDateRangePicker [defaultValue]="campaign"></div>
+        <span slFieldError>The end date is before the start date.</span>
+      </div>
+      <div slField readOnly>
+        <label slFieldLabel>Fiscal quarter</label>
+        <div slDateRangePicker [defaultValue]="quarter"></div>
+        <span slFieldDescription>Set by finance when the quarter opens.</span>
+      </div>
+      <div slField disabled>
+        <label slFieldLabel>Price freeze</label>
+        <div slDateRangePicker [defaultValue]="freeze"></div>
+        <span slFieldDescription>Unlocks once the pricing review is approved.</span>
+      </div>
+    </div>
+  `,
+})
+export class DateRangePickerStates {
+  protected readonly campaign = { start: plainDate(2026, 10, 12), end: plainDate(2026, 10, 5) };
+  protected readonly quarter = { start: plainDate(2026, 7, 1), end: plainDate(2026, 9, 30) };
+  protected readonly freeze = { start: plainDate(2026, 11, 23), end: plainDate(2026, 12, 31) };
+}
+```
+
+### Forms
+
+The whole range is the form control’s value, and a plain form post also sends two ISO 8601 strings under startName and endName. Choose a stay and submit.
+
+Excerpt — not a complete module
+
+```html
+<form [formGroup]="reservation" (ngSubmit)="reserve()">
+  <div slDateRangePicker formControlName="stay" startName="checkin" endName="checkout"></div>
+  <button type="submit">Reserve</button>
+</form>
+```
+
+### Narrow
+
+In a column narrower than two dates, the frame stays on one line: each date clips at its own edge and scrolls back into view when focus enters it, and the trigger keeps its place. The surface is capped by the room available, and the second month wraps under the first. On a touch screen narrower than 480 pixels, the surface is a sheet.
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import {
+  SlDateRangePicker,
+  SlDateRangePickerPreset,
+  SlDateRangePickerPresets,
+} from '@slotted/angular/date-range-picker';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { addDays, plainDate } from '@slotted/core/date';
+
+const TODAY = plainDate(2026, 9, 30);
+
+@Component({
+  selector: 'app-date-range-picker-narrow',
+  imports: [
+    SlDateRangePicker,
+    SlDateRangePickerPreset,
+    SlDateRangePickerPresets,
+    SlField,
+    SlFieldLabel,
+  ],
+  template: `
+    <div slField>
+      <label slFieldLabel>Deliveries between</label>
+      <div slDateRangePicker [max]="today">
+        <div slDateRangePickerPresets>
+          <button [slDateRangePickerPreset]="todayOnly">Today</button>
+          <button [slDateRangePickerPreset]="lastWeek">Last 7 days</button>
+        </div>
+      </div>
+    </div>
+  `,
+})
+export class DateRangePickerNarrow {
+  protected readonly today = TODAY;
+  protected readonly todayOnly = { start: TODAY, end: TODAY };
+  protected readonly lastWeek = { start: addDays(TODAY, -6), end: TODAY };
+}
+```
+
+### Composition
+
+provideDateRangePickerDefaults sets the unit and the months for a section, and provideSlotted sets the language and every word. The instance opens, closes and focuses one end; [position] and (positionChange) control which end the next press writes.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slDateRangePicker
+  #picker="slDateRangePicker"
+  [position]="position"
+  (positionChange)="position = $event.value"
+></div>
+<button type="button" (click)="picker.openSurface()">Open</button>
+```
+
+### The keyboard
+
+Alt+ArrowDown opens the calendar from either field and leaves focus there. Enter on the trigger opens it on the day of the end being edited; each arrow moves the pending end and the band says the length; Enter twice writes the range. Escape returns to the day grid first, then closes and discards a range that has only its start.
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { SlDateRangePicker } from '@slotted/angular/date-range-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-range-picker-keyboard',
+  imports: [SlDateRangePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Shipping blackout</label>
+      <div
+        slDateRangePicker
+        [defaultValue]="blackout"
+        [messages]="messages"
+        (openChange)="record($event)"
+      ></div>
+      <span slFieldDescription>{{ last() }}</span>
+    </div>
+  `,
+})
+export class DateRangePickerKeyboard {
+  protected readonly blackout = { start: plainDate(2026, 11, 26), end: plainDate(2026, 11, 29) };
+  protected readonly messages = {
+    choose: 'Choose blackout dates',
+    change: 'Change blackout dates, {start} to {end}, {length}',
+  };
+  protected readonly last = signal('Focus either date and press Alt+ArrowDown.');
+
+  protected record(request: ChangeRequest<boolean>): void {
+    this.last.set(`${request.value ? 'Opened' : 'Closed'} by ${request.reason}.`);
+  }
+}
+```
+
+### across-unavailable.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDateRangePicker } from '@slotted/angular/date-range-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { dayOfWeek, toISODate, type PlainDate } from '@slotted/core/date';
+
+const HOLIDAYS = new Set(['2026-10-12', '2026-11-11', '2026-11-26', '2026-12-25']);
+
+const isNonWorkingDay = (date: PlainDate) =>
+  dayOfWeek(date) === 0 || dayOfWeek(date) === 6 || HOLIDAYS.has(toISODate(date));
+
+@Component({
+  selector: 'app-date-range-picker-across-unavailable',
+  imports: [SlDateRangePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Vacation</label>
+      <div slDateRangePicker [contiguous]="false" [isDateUnavailable]="isNonWorkingDay"></div>
+      <span slFieldDescription>
+        Start and end on a working day. Weekends and holidays inside the vacation are fine.
+      </span>
+    </div>
+  `,
+})
+export class DateRangePickerAcrossUnavailable {
+  protected readonly isNonWorkingDay = isNonWorkingDay;
+}
+```
+
+### bounds.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDateRangePicker } from '@slotted/angular/date-range-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { plainDate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-range-picker-bounds',
+  imports: [SlDateRangePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Shipment window</label>
+      <div slDateRangePicker [min]="earliest" [max]="latest"></div>
+      <span slFieldDescription>Carriers accept bookings from October 1 to December 31, 2026.</span>
+    </div>
+  `,
+})
+export class DateRangePickerBounds {
+  protected readonly earliest = plainDate(2026, 10, 1);
+  protected readonly latest = plainDate(2026, 12, 31);
+}
+```
+
+### clearable.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDateRangePicker } from '@slotted/angular/date-range-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { plainDate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-range-picker-clearable',
+  imports: [SlDateRangePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Order date</label>
+      <div slDateRangePicker clearable [defaultValue]="ordered"></div>
+      <span slFieldDescription>Clear the dates to list orders from any date.</span>
+    </div>
+  `,
+})
+export class DateRangePickerClearable {
+  protected readonly ordered = { start: plainDate(2026, 9, 14), end: plainDate(2026, 9, 27) };
+}
+```
+
+### compare-periods.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import {
+  SlDateRangePicker,
+  SlDateRangePickerPreset,
+  SlDateRangePickerPresets,
+  type DateRange,
+} from '@slotted/angular/date-range-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { addDays, daysBetween, plainDate, stepYear } from '@slotted/core/date';
+
+const SEPTEMBER: DateRange = { start: plainDate(2026, 9, 1), end: plainDate(2026, 9, 30) };
+
+/** The run of the same length that ends the day before the period starts. */
+const previousPeriod = (period: DateRange): DateRange | null => {
+  if (period.start === null || period.end === null) return null;
+  const days = daysBetween(period.start, period.end) + 1;
+  return { start: addDays(period.start, -days), end: addDays(period.start, -1) };
+};
+
+const lastYear = (period: DateRange): DateRange | null =>
+  period.start === null || period.end === null
+    ? null
+    : { start: stepYear(period.start, -1).date, end: stepYear(period.end, -1).date };
+
+@Component({
+  selector: 'app-date-range-picker-compare-periods',
+  imports: [
+    SlDateRangePicker,
+    SlDateRangePickerPreset,
+    SlDateRangePickerPresets,
+    SlField,
+    SlFieldDescription,
+    SlFieldLabel,
+    SlStack,
+  ],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Period</label>
+        <div slDateRangePicker [value]="period()" (valueChange)="period.set($event.value)"></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Compare to</label>
+        <div slDateRangePicker [value]="baseline()" (valueChange)="baseline.set($event.value)">
+          <div slDateRangePickerPresets>
+            @if (previous(); as range) {
+              <button [slDateRangePickerPreset]="range">Previous period</button>
+            }
+            @if (sameLastYear(); as range) {
+              <button [slDateRangePickerPreset]="range">Same period last year</button>
+            }
+          </div>
+        </div>
+        <span slFieldDescription>Shortcuts follow the period above.</span>
+      </div>
+    </div>
+  `,
+})
+export class DateRangePickerComparePeriods {
+  protected readonly period = signal<DateRange | null>(SEPTEMBER);
+  protected readonly baseline = signal<DateRange | null>(previousPeriod(SEPTEMBER));
+  protected readonly previous = computed(() => {
+    const period = this.period();
+    return period === null ? null : previousPeriod(period);
+  });
+  protected readonly sameLastYear = computed(() => {
+    const period = this.period();
+    return period === null ? null : lastYear(period);
+  });
+}
+```
+
+### controlled.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import { SlDateRangePicker, type DateRange } from '@slotted/angular/date-range-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlInline } from '@slotted/angular/inline';
+import { SlStack } from '@slotted/angular/stack';
+import { endOfMonth, plainDate, startOfMonth, stepMonth, toISODate } from '@slotted/core/date';
+
+const SEPTEMBER: DateRange = { start: plainDate(2026, 9, 1), end: plainDate(2026, 9, 30) };
+const FALLBACK = plainDate(2026, 9, 1);
+
+/** The calendar month before or after the one the range starts in. */
+const shift = (range: DateRange | null, months: number): DateRange => {
+  const first = startOfMonth(stepMonth(range?.start ?? FALLBACK, months).date);
+  return { start: first, end: endOfMonth(first) };
+};
+
+@Component({
+  selector: 'app-date-range-picker-controlled',
+  imports: [
+    SlButton,
+    SlDateRangePicker,
+    SlField,
+    SlFieldDescription,
+    SlFieldLabel,
+    SlInline,
+    SlStack,
+  ],
+  template: `
+    <div slStack [gap]="4">
+      <div slField>
+        <label slFieldLabel>Statement period</label>
+        <div slDateRangePicker [value]="period()" (valueChange)="period.set($event.value)"></div>
+        <span slFieldDescription>{{ summary() }}</span>
+      </div>
+      <div slInline [gap]="2">
+        <button
+          slButton
+          size="sm"
+          tone="secondary"
+          variant="outline"
+          type="button"
+          (click)="move(-1)"
+        >
+          Previous month
+        </button>
+        <button
+          slButton
+          size="sm"
+          tone="secondary"
+          variant="outline"
+          type="button"
+          (click)="move(1)"
+        >
+          Next month
+        </button>
+        <button
+          slButton
+          size="sm"
+          tone="secondary"
+          variant="ghost"
+          type="button"
+          (click)="period.set(null)"
+        >
+          Clear
+        </button>
+      </div>
+    </div>
+  `,
+})
+export class DateRangePickerControlled {
+  protected readonly period = signal<DateRange | null>(SEPTEMBER);
+  protected readonly summary = computed(() => {
+    const period = this.period();
+    return period?.start && period.end
+      ? `Statement from ${toISODate(period.start)} to ${toISODate(period.end)}.`
+      : 'Choose both dates to run the statement.';
+  });
+
+  protected move(months: number): void {
+    this.period.set(shift(this.period(), months));
+  }
+}
+```
+
+### count.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDateRangePicker } from '@slotted/angular/date-range-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { plainDate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-range-picker-count',
+  imports: [SlDateRangePicker, SlField, SlFieldDescription, SlFieldLabel, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Hotel stay</label>
+        <div slDateRangePicker count="nights" [defaultValue]="trip"></div>
+        <span slFieldDescription>Counted in nights: October 12 to 16 is 4 nights.</span>
+      </div>
+      <div slField>
+        <label slFieldLabel>Trade show leave</label>
+        <div slDateRangePicker count="days" [defaultValue]="trip"></div>
+        <span slFieldDescription>Counted in days: October 12 to 16 is 5 days.</span>
+      </div>
+    </div>
+  `,
+})
+export class DateRangePickerCount {
+  protected readonly trip = { start: plainDate(2026, 10, 12), end: plainDate(2026, 10, 16) };
+}
+```
+
+### defaults.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import {
+  provideDateRangePickerDefaults,
+  SlDateRangePicker,
+} from '@slotted/angular/date-range-picker';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { plainDate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-range-picker-defaults',
+  imports: [SlDateRangePicker, SlField, SlFieldLabel, SlStack],
+  providers: [provideDateRangePickerDefaults({ count: 'nights', months: 1, variant: 'subtle' })],
+  template: `
+    <div slStack [gap]="4">
+      <div slField>
+        <label slFieldLabel>Lisbon hotel</label>
+        <div slDateRangePicker [defaultValue]="lisbon"></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Porto hotel</label>
+        <div slDateRangePicker [defaultValue]="porto"></div>
+      </div>
+    </div>
+  `,
+})
+export class DateRangePickerDefaults {
+  protected readonly lisbon = { start: plainDate(2026, 11, 9), end: plainDate(2026, 11, 12) };
+  protected readonly porto = { start: plainDate(2026, 11, 12), end: plainDate(2026, 11, 14) };
+}
+```
+
+### dock-booking.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { SlDateRangePicker, type DateRange } from '@slotted/angular/date-range-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import {
+  createDateFormat,
+  dayOfWeek,
+  plainDate,
+  toISODate,
+  type PlainDate,
+} from '@slotted/core/date';
+
+const TODAY = plainDate(2026, 9, 30);
+/** Days another carrier already holds dock 4. */
+const HELD = new Set(['2026-10-07', '2026-10-08', '2026-10-21', '2026-10-22', '2026-10-23']);
+const words = createDateFormat({ locale: 'en-US' });
+
+const isClosed = (date: PlainDate) =>
+  dayOfWeek(date) === 0 || dayOfWeek(date) === 6 || HELD.has(toISODate(date));
+
+@Component({
+  selector: 'app-date-range-picker-dock-booking',
+  imports: [SlDateRangePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField required>
+      <label slFieldLabel>Dock 4 unloading window</label>
+      <div
+        slDateRangePicker
+        [isDateUnavailable]="isClosed"
+        [max]="latest"
+        [maxLength]="3"
+        [min]="earliest"
+        [value]="slot()"
+        (valueChange)="slot.set($event.value)"
+      ></div>
+      <span slFieldDescription>{{ summary() }}</span>
+    </div>
+  `,
+})
+export class DateRangePickerDockBooking {
+  protected readonly isClosed = isClosed;
+  protected readonly earliest = plainDate(2026, 10, 1);
+  protected readonly latest = plainDate(2026, 11, 30);
+  protected readonly slot = signal<DateRange | null>(null);
+  protected readonly summary = computed(() => {
+    const slot = this.slot();
+    return slot?.start && slot.end
+      ? `Dock 4 is yours from ${words.describe(slot.start)} to ${words.describe(slot.end)}.`
+      : `Book 1 to 3 weekdays from October 1. Booked as of ${words.describe(TODAY)}: Oct 7–8 and Oct 21–23.`;
+  });
+}
+```
+
+### first-day.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDateRangePicker } from '@slotted/angular/date-range-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { plainDate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-range-picker-first-day',
+  imports: [SlDateRangePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Sprint 42</label>
+      <div slDateRangePicker weekNumbers [defaultValue]="sprint" [firstDayOfWeek]="1"></div>
+      <span slFieldDescription>Sprints run two ISO weeks, Monday to Friday.</span>
+    </div>
+  `,
+})
+export class DateRangePickerFirstDay {
+  protected readonly sprint = { start: plainDate(2026, 10, 5), end: plainDate(2026, 10, 16) };
+}
+```
+
+### focus-and-open.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import { SlDateRangePicker } from '@slotted/angular/date-range-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-range-picker-focus-and-open',
+  imports: [SlButton, SlDateRangePicker, SlField, SlFieldLabel, SlInline, SlStack],
+  template: `
+    <div slStack [gap]="4">
+      <div slField>
+        <label slFieldLabel>Contract term</label>
+        <div slDateRangePicker #picker="slDateRangePicker" [defaultValue]="term"></div>
+      </div>
+      <div slInline [gap]="2">
+        <button
+          slButton
+          size="sm"
+          tone="secondary"
+          variant="outline"
+          type="button"
+          (click)="picker.focus('end')"
+        >
+          Edit end date
+        </button>
+        <button
+          slButton
+          size="sm"
+          tone="secondary"
+          variant="outline"
+          type="button"
+          (click)="picker.openSurface()"
+        >
+          Open calendar
+        </button>
+      </div>
+    </div>
+  `,
+})
+export class DateRangePickerFocusAndOpen {
+  protected readonly term = { start: plainDate(2026, 4, 1), end: plainDate(2027, 3, 31) };
+}
+```
+
+### footer.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlButton } from '@slotted/angular/button';
+import { SlDateRangePicker, SlDateRangePickerFooter } from '@slotted/angular/date-range-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { plainDate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-range-picker-footer',
+  imports: [
+    SlButton,
+    SlDateRangePicker,
+    SlDateRangePickerFooter,
+    SlField,
+    SlFieldDescription,
+    SlFieldLabel,
+  ],
+  template: `
+    <div slField>
+      <label slFieldLabel>Stock count freeze</label>
+      <div
+        slDateRangePicker
+        #picker="slDateRangePicker"
+        closeOnSelect="never"
+        [defaultValue]="freeze"
+      >
+        <div slDateRangePickerFooter>
+          <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 DateRangePickerFooter {
+  protected readonly freeze = { start: plainDate(2026, 10, 30), end: plainDate(2026, 11, 1) };
+}
+```
+
+### form.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { toSignal } from '@angular/core/rxjs-interop';
+import { FormControl, FormGroup, ReactiveFormsModule, type ValidatorFn } from '@angular/forms';
+import { SlButton } from '@slotted/angular/button';
+import { SlDateRangePicker, type DateRange } from '@slotted/angular/date-range-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 { toISODate } from '@slotted/core/date';
+
+/** Both ends present: Validators.required accepts a range with one end open. */
+const bothEnds: ValidatorFn = (control) => {
+  const range = control.value as DateRange | null;
+  return range?.start && range.end ? null : { bothEnds: true };
+};
+
+@Component({
+  selector: 'app-date-range-picker-form',
+  imports: [
+    ReactiveFormsModule,
+    SlButton,
+    SlDateRangePicker,
+    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>Code freeze</label>
+          <div
+            slDateRangePicker
+            startName="freezeStart"
+            endName="freezeEnd"
+            formControlName="freeze"
+          ></div>
+          <span slFieldError live="polite" reserve>{{ error() }}</span>
+        </div>
+        <div slInline [gap]="3" align="center">
+          <button slButton type="submit">Save freeze</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 DateRangePickerForm {
+  protected readonly form = new FormGroup({
+    freeze: new FormControl<DateRange | null>(null, bothEnds),
+  });
+  private readonly value = toSignal(this.form.controls.freeze.valueChanges, {
+    initialValue: this.form.controls.freeze.value,
+  });
+  private readonly submitted = signal(false);
+  protected readonly saved = signal<string | null>(null);
+  protected readonly error = computed(() => {
+    this.value();
+    const control = this.form.controls.freeze;
+    if (control.hasError('slottedDateRangeOrder')) {
+      return 'The end date must be on or after the start date.';
+    }
+    if (this.submitted() && control.hasError('bothEnds')) return 'Enter a start and an end date.';
+    return '';
+  });
+
+  protected submit(): void {
+    this.submitted.set(true);
+    const range = this.form.controls.freeze.value;
+    this.saved.set(
+      this.form.valid && range?.start && range.end
+        ? `Freeze saved from ${toISODate(range.start)} to ${toISODate(range.end)}.`
+        : null,
+    );
+  }
+
+  protected clear(): void {
+    this.submitted.set(false);
+    this.saved.set(null);
+  }
+}
+```
+
+### locale.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDateRangePicker } from '@slotted/angular/date-range-picker';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlStack } from '@slotted/angular/stack';
+import { plainDate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-range-picker-locale',
+  imports: [SlDateRangePicker, SlField, SlFieldLabel, SlStack],
+  template: `
+    <div slStack [gap]="5">
+      <div slField>
+        <label slFieldLabel>Peak season, United States (en-US)</label>
+        <div slDateRangePicker locale="en-US" [defaultValue]="season"></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Peak season, United Kingdom (en-GB)</label>
+        <div slDateRangePicker locale="en-GB" [defaultValue]="season"></div>
+      </div>
+      <div slField>
+        <label slFieldLabel>Peak season, Germany (de-DE)</label>
+        <div slDateRangePicker locale="de-DE" [defaultValue]="season"></div>
+      </div>
+    </div>
+  `,
+})
+export class DateRangePickerLocale {
+  protected readonly season = { start: plainDate(2026, 11, 2), end: plainDate(2026, 12, 23) };
+}
+```
+
+### months.ts
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDateRangePicker } from '@slotted/angular/date-range-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { plainDate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-range-picker-months',
+  imports: [SlDateRangePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Promotion window</label>
+      <div slDateRangePicker [defaultValue]="promotion" [months]="1"></div>
+      <span slFieldDescription>Promotions run inside one month.</span>
+    </div>
+  `,
+})
+export class DateRangePickerMonths {
+  protected readonly promotion = { start: plainDate(2026, 10, 5), end: plainDate(2026, 10, 18) };
+}
+```
+
+### position.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { SlDateRangePicker, type DateRange } from '@slotted/angular/date-range-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { plainDate, toISODate } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-date-range-picker-position',
+  imports: [SlDateRangePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Scissor lift rental</label>
+      <div
+        slDateRangePicker
+        defaultPosition="end"
+        [value]="rental()"
+        (valueChange)="rental.set($event.value)"
+      ></div>
+      <span slFieldDescription>{{ summary() }}</span>
+    </div>
+  `,
+})
+export class DateRangePickerPosition {
+  protected readonly rental = signal<DateRange | null>({
+    start: plainDate(2026, 10, 5),
+    end: plainDate(2026, 10, 9),
+  });
+  protected readonly summary = computed(() => {
+    const end = this.rental()?.end;
+    return end
+      ? `Returns ${toISODate(end)}. Open the calendar and press a day to move the return date.`
+      : 'Choose a return date.';
+  });
+}
+```
+
+### reporting-filter.ts
+
+Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import {
+  SlDateRangePicker,
+  SlDateRangePickerPreset,
+  SlDateRangePickerPresets,
+  type DateRange,
+} from '@slotted/angular/date-range-picker';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+import { SlGrid } from '@slotted/angular/grid';
+import { SlStack } from '@slotted/angular/stack';
+import {
+  SlStatCard,
+  SlStatCardComparison,
+  SlStatCardDelta,
+  SlStatCardFigure,
+  SlStatCardHeader,
+  SlStatCardLabel,
+  SlStatCardPeriod,
+  SlStatCardValue,
+} from '@slotted/angular/stat-card';
+import { addDays, daysBetween, plainDate, type PlainDate } from '@slotted/core/date';
+
+const TODAY = plainDate(2026, 9, 30);
+const LAST_7_DAYS: DateRange = { start: addDays(TODAY, -6), end: TODAY };
+const PRESETS: { label: string; range: DateRange }[] = [
+  { label: 'Last 7 days', range: LAST_7_DAYS },
+  { label: 'Last 30 days', range: { start: addDays(TODAY, -29), end: TODAY } },
+  { label: 'This quarter', range: { start: plainDate(2026, 7, 1), end: TODAY } },
+];
+
+/** Orders shipped on one day, from the Northwind warehouse feed. */
+const ordersOn = (date: PlainDate) => 150 + date.month * 6 + ((date.day * 37) % 50);
+
+const ordersBetween = (start: PlainDate, end: PlainDate) => {
+  let total = 0;
+  for (let date = start; daysBetween(date, end) >= 0; date = addDays(date, 1)) {
+    total += ordersOn(date);
+  }
+  return total;
+};
+
+@Component({
+  selector: 'app-date-range-picker-reporting-filter',
+  imports: [
+    SlDateRangePicker,
+    SlDateRangePickerPreset,
+    SlDateRangePickerPresets,
+    SlField,
+    SlFieldLabel,
+    SlGrid,
+    SlStack,
+    SlStatCard,
+    SlStatCardComparison,
+    SlStatCardDelta,
+    SlStatCardFigure,
+    SlStatCardHeader,
+    SlStatCardLabel,
+    SlStatCardPeriod,
+    SlStatCardValue,
+  ],
+  template: `
+    <div slStack [gap]="5">
+      <div slField size="sm">
+        <label slFieldLabel>Period</label>
+        <div
+          slDateRangePicker
+          [max]="today"
+          [value]="period()"
+          (valueChange)="period.set($event.value)"
+        >
+          <div slDateRangePickerPresets>
+            @for (preset of presets; track preset.label) {
+              <button [slDateRangePickerPreset]="preset.range">{{ preset.label }}</button>
+            }
+          </div>
+        </div>
+      </div>
+      <div slGrid [gap]="4" minItemWidth="sm">
+        <div slStatCard goodWhen="up" [delta]="figures().delta">
+          <div slStatCardHeader><span slStatCardLabel>Orders shipped</span></div>
+          <div slStatCardFigure>
+            <span slStatCardValue [value]="figures().orders"></span>
+            <span slStatCardDelta></span>
+            <p slStatCardComparison>
+              from {{ figures().previous.toLocaleString('en-US') }}
+              <span slStatCardPeriod>previous {{ figures().days }} days</span>
+            </p>
+          </div>
+        </div>
+        <div slStatCard>
+          <div slStatCardHeader><span slStatCardLabel>Orders per day</span></div>
+          <div slStatCardFigure>
+            <span slStatCardValue [value]="figures().perDay"></span>
+            <p slStatCardComparison>
+              over <span slStatCardPeriod>{{ figures().days }} days</span>
+            </p>
+          </div>
+        </div>
+      </div>
+    </div>
+  `,
+})
+export class DateRangePickerReportingFilter {
+  protected readonly today = TODAY;
+  protected readonly presets = PRESETS;
+  protected readonly period = signal<DateRange | null>(LAST_7_DAYS);
+  protected readonly figures = computed(() => {
+    const period = this.period();
+    if (!period?.start || !period.end)
+      return { days: 0, orders: 0, previous: 0, delta: 0, perDay: 0 };
+    const days = daysBetween(period.start, period.end) + 1;
+    const orders = ordersBetween(period.start, period.end);
+    const previous = ordersBetween(addDays(period.start, -days), addDays(period.start, -1));
+    return {
+      days,
+      orders,
+      previous,
+      delta: previous === 0 ? 0 : (orders - previous) / previous,
+      perDay: Math.round(orders / days),
+    };
+  });
+}
+```
+
+### typing.ts
+
+Example
+
+```ts
+import { Component, signal } from '@angular/core';
+import { SlDateRangePicker, type DateRange } from '@slotted/angular/date-range-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { toISODate, type PlainDate } from '@slotted/core/date';
+import type { ChangeRequest } from '@slotted/core/state';
+
+const HOW: Record<string, string> = {
+  blur: 'completed when the field lost focus',
+  clear: 'cleared',
+  keyboard: 'typed',
+  pointer: 'pressed',
+  programmatic: 'set from code',
+  select: 'chosen in the calendar',
+};
+const iso = (date: PlainDate | null) => (date === null ? 'open' : toISODate(date));
+
+@Component({
+  selector: 'app-date-range-picker-typing',
+  imports: [SlDateRangePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Audit window</label>
+      <div slDateRangePicker [value]="period()" (valueChange)="record($event)"></div>
+      <span slFieldDescription>{{ last() }}</span>
+    </div>
+  `,
+})
+export class DateRangePickerTyping {
+  protected readonly period = signal<DateRange | null>(null);
+  protected readonly last = signal('Type both dates, or choose two days in the calendar.');
+
+  protected record(request: ChangeRequest<DateRange | null>): void {
+    const value = request.value;
+    this.period.set(value);
+    this.last.set(
+      value === null
+        ? `No dates, ${HOW[request.reason]}.`
+        : `${iso(value.start)} to ${iso(value.end)}, ${HOW[request.reason]}.`,
+    );
+  }
+}
+```