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

package/docs/date-range-picker.md

@@ -0,0 +1,142 @@
+<!-- index: ./index.md -->
+# date-range-picker
+
+`data-ui="date-range-picker"` · Start and end dates with a calendar popover.
+
+## Import
+
+```ts
+import { SlDateRangePicker, SlDateRangePickerPreset, SlDateRangePickerPresets, SlDateRangePickerFooter, provideDateRangePickerDefaults } from '@slotted/angular/date-range-picker';
+```
+
+Selector: `[slDateRangePicker]` · exportAs: `slDateRangePicker`
+
+## Minimal example
+
+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-basic',
+  imports: [SlDateRangePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Reporting period</label>
+      <div slDateRangePicker startName="periodStart" endName="periodEnd"></div>
+      <span slFieldDescription>Type both dates or choose them from the calendar.</span>
+    </div>
+  `,
+})
+export class DateRangePickerBasic {}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | your own element | yes |
+| `control` | div | yes |
+| `start` | div | yes |
+| `separator` | span | yes |
+| `end` | div | yes |
+| `clear` | button | no |
+| `trigger` | button | yes |
+| `positioner` | div | no |
+| `content` | div with role="dialog" | no |
+| `head` | div | no |
+| `head-start` | span | no |
+| `head-end` | span | no |
+| `length` | span | no |
+| `limit` | span | no |
+| `panels` | div | no |
+| `presets` | your own element with slDateRangePickerPresets | no |
+| `preset` | your own button with slDateRangePickerPreset | no |
+| `footer` | your own element with slDateRangePickerFooter | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `DateRange \| null` | — | SlDateRangePicker | The range, { start, end }, where each end is a PlainDate or null. A range with both ends null is null. Binding it makes the value controlled. |
+| `defaultValue` | `DateRange \| null` | — | SlDateRangePicker | The starting value of an uncontrolled date range picker. Read once, on init. |
+| `open` | `boolean` | — | SlDateRangePicker | Whether the calendar is showing. Binding it makes the open state controlled. |
+| `defaultOpen` | `boolean` | false | SlDateRangePicker | Whether the calendar shows on the first render. Focus does not move into it. |
+| `position` | `'start' \| 'end'` | — | SlDateRangePicker | The end being edited: the field that carries data-current, the day the calendar opens on, and the end the next press in the calendar writes. Binding it makes the position controlled. |
+| `defaultPosition` | `'start' \| 'end'` | start | SlDateRangePicker | The end being edited on the first render. |
+| `min` | `PlainDate` | — | SlDateRangePicker | The earliest date both fields and the calendar accept. Earlier days are disabled in the calendar, and an earlier typed date marks the date range picker invalid. Once both ends are set, the start field also stops at the end and the end field at the start. |
+| `max` | `PlainDate` | — | SlDateRangePicker | The latest date both fields and the calendar accept. Later days are disabled in the calendar, and a later typed date marks the date range picker invalid. |
+| `isDateUnavailable` | `(date: PlainDate) => boolean` | — | SlDateRangePicker | Returns true for a date the reader cannot choose. The calendar disables it, and a typed range that contains it marks the date range picker invalid. |
+| `contiguous` | `boolean` | true | SlDateRangePicker | Whether a range must run without unavailable days. On, once a start is chosen the calendar also disables every day beyond the first unavailable one, searching up to maxLength days, or 366, on each side. Off, only the two ends are checked. |
+| `minLength` | `number` | — | SlDateRangePicker | The shortest range allowed, in the unit count names. Once a start is chosen, the calendar disables the days that would make a shorter range, and the band names the limit. |
+| `maxLength` | `number` | — | SlDateRangePicker | The longest range allowed, in the unit count names. A typed range outside either limit marks the date range picker invalid. |
+| `count` | `'days' \| 'nights'` | days | SlDateRangePicker | What the length counts. days counts both ends; nights counts the nights between them. The same day at both ends is 1 day or 0 nights. |
+| `months` | `number` | 2 | SlDateRangePicker | How many months the calendar draws side by side. When they do not fit, they wrap. |
+| `weekNumbers` | `boolean` | false | SlDateRangePicker | Adds a column of ISO 8601 week numbers to the calendar. |
+| `fixedWeeks` | `boolean` | true | SlDateRangePicker | Draws six rows for every month, so the surface keeps its height as the reader pages between months. |
+| `placement` | `'bottom-start' \| 'bottom' \| 'bottom-end' \| 'top-start' \| 'top' \| 'top-end'` | bottom-start | SlDateRangePicker | Where the calendar opens relative to the frame. When it does not fit on that side, it opens on the other. |
+| `closeOnSelect` | `'auto' \| 'always' \| 'never'` | auto | SlDateRangePicker | When choosing closes the calendar. auto closes it when the range is complete, by a second press or a shortcut, and keeps it open after the first press; always closes it on every press that changes the value; never keeps it open. |
+| `locale` | `string` | the provideSlotted locale, else en-US | SlDateRangePicker | A BCP 47 tag. Sets the order, separators and placeholders of both fields, the month and weekday names, the short dates in the band and the dates the trigger announces. |
+| `timeZone` | `string` | the browser’s time zone | SlDateRangePicker | The IANA time zone that decides which day is today. The value itself has no time zone. |
+| `firstDayOfWeek` | `number` | the locale’s | SlDateRangePicker | The day the calendar starts each week on, from 0 for Sunday to 6 for Saturday. |
+| `yearPivot` | `number` | 20 | SlDateRangePicker | How a two-digit year typed into either field resolves: with 20, 30 reads as 2030 and 80 as 1980. |
+| `calendar` | `'gregory'` | gregory | SlDateRangePicker | The calendar system. Gregorian is the only one today. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | SlDateRangePicker | One step of the control scale, for the frame, both fields and the trigger. Inside a field, an unset size follows the field. |
+| `variant` | `'outline' \| 'subtle' \| 'plain'` | outline | SlDateRangePicker | How much frame the control draws at rest. |
+| `disabled` | `boolean` | the field’s | SlDateRangePicker | Disables both fields, the clear button and the trigger, and takes them out of the tab order. A form control’s disabled state sets it too. |
+| `readOnly` | `boolean` | the field’s | SlDateRangePicker | Keeps both dates legible and focusable, and disables the clear button and the trigger. |
+| `invalid` | `boolean` | the field’s | SlDateRangePicker | Marks the date range picker invalid. An end before its start, a date outside min and max, an unavailable date in the range or a length outside the limits marks it invalid whatever this says. |
+| `required` | `boolean` | the field’s | SlDateRangePicker | Sets aria-required on both fields. |
+| `clearable` | `boolean` | false | SlDateRangePicker | Adds one clear button to the frame, which empties both ends. |
+| `messages` | `Partial<DateRangePickerMessages>` | — | SlDateRangePicker | Replaces words of the active language, key by key: choose and change for the trigger’s name before and after a range is set (change takes {start}, {end} and {length}), clear, start and end for the two fields’ names and the band’s placeholders, and the counting phrases days.length and nights.length with between, atLeast and atMost for the limits. |
+| `startName` | `string` | — | SlDateRangePicker | Adds a hidden input with this name that submits the start as an ISO 8601 string, such as 2026-09-30. |
+| `endName` | `string` | — | SlDateRangePicker | Adds a hidden input with this name that submits the end as an ISO 8601 string. |
+| `slDateRangePickerPresets` | `Directive` | — | SlDateRangePicker | Marks your own element as the column of shortcuts beside the calendar. It holds buttons with slDateRangePickerPreset. |
+| `slDateRangePickerFooter` | `Directive` | — | SlDateRangePicker | Marks your own element as the row of actions under the calendar. |
+| `slDateRangePickerPreset` | `DateRange \| (() => DateRange)` | — | SlDateRangePickerPreset | The range the shortcut writes, or a function that returns it when the shortcut is pressed, so a relative range such as "next weekend" is computed at the press. |
+| `provideDateRangePickerDefaults` | `Provider` | — | application | Sets timeZone, calendar, months, count, closeOnSelect, placement, size and variant for every date range picker under the injector. An input on one date range picker wins, and inside a field the field’s size wins. |
+| `ControlValueAccessor and Validator` | `formControl, formControlName, ngModel` | — | SlDateRangePicker | The whole { start, end } is the control’s value. The date range picker reports slottedDateRangeOrder, slottedDateRangeMin, slottedDateRangeMax, slottedDateRangeUnavailable and slottedDateRangeLength, and leaves required to Validators.required, which accepts a range with one open end. |
+| `exportAs` | `slDateRangePicker` | — | SlDateRangePicker | Gives a template the instance, with focus(position?), which focuses the first segment of one end (the current one by default), openSurface() and closeSurface(), which show and hide the calendar without a bound open, and choose(range), which writes a range as a shortcut does. openSurface() moves focus into the calendar. |
+| `Content slots` | `slDateRangePickerPresets, slDateRangePickerFooter` | — | SlDateRangePicker | The two places you fill, as directives on your own elements, so a button, a list or a toolbar keeps its own semantics. |
+| `slDateRangePickerPreset` | `Directive on button` | — | presets | One shortcut on your own button. It takes the range and sets data-part and type. A click handler that calls preventDefault() keeps the current value. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `valueChange` | `ChangeRequest<DateRange \| null>` | Before the value changes. reason is keyboard or blur for a typed end, select for a range completed in the calendar or written by a shortcut, and clear for the clear button. The first press in the calendar does not emit: the range is not complete yet. cancel() keeps the current value. There is no two-way [(value)] binding, because the request carries the reason; bind a form control for two-way binding. |
+| `openChange` | `ChangeRequest<boolean>` | Before the calendar opens or closes. reason is pointer for the trigger, keyboard for Alt+ArrowDown, programmatic for openSurface() and closeSurface(), escape for the Escape key, outsidePress for a press outside the surface and select for a completed range. cancel() keeps the current state. |
+| `positionChange` | `ChangeRequest<'start' \| 'end'>` | Before the end being edited changes. reason is pointer or keyboard when focus enters a field, select after a press in the calendar or a shortcut, and clear for the clear button. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `variant` | `outline`, `subtle`, `plain` | `outline` |
+| `placement` | `bottom-start`, `bottom`, `bottom-end`, `top-start`, `top`, `top-end` | `bottom-start` |
+| `closeOnSelect` | `auto`, `always`, `never` | `auto` |
+| `count` | `days`, `nights` | `days` |
+| `position` | `start`, `end` | — |
+| `calendar` | `gregory` | `gregory` |
+
+## Rules
+
+- The trigger’s accessible name carries both dates in words and the length, such as “Change range, Saturday, September 12, 2026 – Wednesday, September 16, 2026, 4 nights”. Focus returns to the trigger when the calendar closes, so a screen reader announces the range there.
+- Opening the calendar from the trigger or from openSurface() moves focus to the day of the end being edited, or to today when that end is empty. Alt+ArrowDown opens it and leaves focus in the field. While the calendar is open, Tab and Shift+Tab cycle through the shortcuts, the calendar and the footer.
+- The length is a polite live region. A sighted reader sees it follow the pointer; a screen-reader user hears it follow each arrow key.
+- Each field has its own name, from the start and end messages, and the dash between them is aria-hidden. Each field keeps its own spin buttons and its own keys. Inside a field, the frame is a group named by the field’s label, so a screen reader announces “Reporting period” and then “Start” on the way into the first date.
+- Escape closes in steps: while the calendar shows the month or year grid, Escape returns to the day grid; on the day grid, it closes the calendar, discards a range that has only its start, and returns focus to the trigger.
+- A range that has only its start in the calendar never reaches the value or a form: the first press is shown in the band, and the second press writes the range. A typed open end is a value, because the reader sees it in the field.
+- The surface has role="dialog" and the same accessible name as the trigger. The trigger sets aria-expanded, and sets aria-controls only while the surface exists. One day of the calendar is in the tab order, as the grid pattern requires.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-gap-lg`, `--slotted-control-gap-md`, `--slotted-control-gap-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-invalid-edge-width`, `--slotted-control-padding-inline-lg`, `--slotted-control-padding-inline-md`, `--slotted-control-padding-inline-sm`, `--slotted-control-radius`, `--slotted-control-shadow`, `--slotted-control-shadow-focus-geometry`, `--slotted-control-surface`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-date-range-picker-action-active-background`, `--slotted-date-range-picker-action-color`, `--slotted-date-range-picker-action-hover-background`, `--slotted-date-range-picker-action-size`, `--slotted-date-range-picker-background`, `--slotted-date-range-picker-border-color`, `--slotted-date-range-picker-color`, `--slotted-date-range-picker-content-border-color`, `--slotted-date-range-picker-content-color`, `--slotted-date-range-picker-content-padding`, `--slotted-date-range-picker-content-radius`, `--slotted-date-range-picker-content-shadow`, `--slotted-date-range-picker-current-color`, `--slotted-date-range-picker-current-size`, `--slotted-date-range-picker-disabled-background`, `--slotted-date-range-picker-disabled-border-color`, `--slotted-date-range-picker-disabled-color`, `--slotted-date-range-picker-hover-border-color`, `--slotted-date-range-picker-invalid-border-color`, `--slotted-date-range-picker-invalid-edge-width`, `--slotted-date-range-picker-invalid-focus-ring-color`, `--slotted-date-range-picker-length-color`, `--slotted-date-range-picker-limit-color`, `--slotted-date-range-picker-pending-color`, `--slotted-date-range-picker-placeholder-color`, `--slotted-date-range-picker-plain-hover-background`, `--slotted-date-range-picker-preset-active-background`, `--slotted-date-range-picker-preset-hover-background`, `--slotted-date-range-picker-preset-selected-background`, `--slotted-date-range-picker-preset-selected-color`, `--slotted-date-range-picker-radius`, `--slotted-date-range-picker-readonly-background`, `--slotted-date-range-picker-separator-color`, `--slotted-date-range-picker-shadow`, `--slotted-date-range-picker-sheet-inline-size`, `--slotted-date-range-picker-subtle-background`, `--slotted-date-range-picker-subtle-border-color`, `--slotted-date-range-picker-subtle-hover-background`, `--slotted-date-range-picker-surface`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-size-sm`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-font-weight-regular`, `--slotted-font-weight-semibold`, `--slotted-line-height-sm`, `--slotted-radius-lg`, `--slotted-radius-none`, `--slotted-radius-xs`, `--slotted-shadow-md`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-9`, `--slotted-surface-raised`, `--slotted-surface-sunken`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-subtle-hover`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-z-index-popover`
+
+## Examples
+
+See [date-range-picker.examples.md](./date-range-picker.examples.md).