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

package/docs/date-picker.md

@@ -0,0 +1,121 @@
+<!-- index: ./index.md -->
+# date-picker
+
+`data-ui="date-picker"` · Date field with a calendar popover.
+
+## Import
+
+```ts
+import { SlDatePicker, SlDatePickerPresets, SlDatePickerFooter } from '@slotted/angular/date-picker';
+```
+
+Selector: `[slDatePicker]` · exportAs: `slDatePicker`
+
+## Minimal example
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDatePicker } from '@slotted/angular/date-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+
+@Component({
+  selector: 'app-date-picker-basic',
+  imports: [SlDatePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Requested delivery date</label>
+      <div slDatePicker name="deliveryDate"></div>
+      <span slFieldDescription>Type the date or choose it from the calendar.</span>
+    </div>
+  `,
+})
+export class DatePickerBasic {}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | your own element carrying slDatePicker | yes |
+| `control` | div | yes |
+| `trigger` | button | yes |
+| `positioner` | div, after the control inside the root | yes |
+| `content` | div with role="dialog" | yes |
+| `presets` | your own element carrying slDatePickerPresets | no |
+| `footer` | your own element carrying slDatePickerFooter | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `PlainDate \| DateRange \| PlainDate[] \| null` | — | SlDatePicker | The selected value, whose shape follows selectionMode. Binding it makes the value controlled. |
+| `defaultValue` | `PlainDate \| DateRange \| PlainDate[] \| null` | — | SlDatePicker | The starting value of an uncontrolled date picker. Read once, when the date picker initializes. |
+| `open` | `boolean` | — | SlDatePicker | Whether the calendar is showing. Binding it makes the open state controlled. |
+| `defaultOpen` | `boolean` | false | SlDatePicker | Whether the calendar shows when the date picker initializes. Focus does not move into it. |
+| `min` | `PlainDate` | — | SlDatePicker | The earliest date the field and the calendar accept. Earlier days are disabled in the calendar, an earlier typed date marks the date picker invalid, and a form reports slottedDateRange. |
+| `max` | `PlainDate` | — | SlDatePicker | The latest date the field and the calendar accept. Later days are disabled in the calendar, a later typed date marks the date picker invalid, and a form reports slottedDateRange. |
+| `isDateUnavailable` | `(date: PlainDate) => boolean` | — | SlDatePicker | Returns true for a date the reader cannot choose. The calendar disables it, a typed unavailable date marks the date picker invalid, and a form reports slottedDateUnavailable. |
+| `selectionMode` | `'single' \| 'range' \| 'multiple'` | single | SlDatePicker | How many dates the calendar selects, and so the shape of the value. The field shows a single date only; for a start and an end, use slDateRangePicker. |
+| `months` | `number` | 1 | SlDatePicker | How many months the calendar draws side by side. |
+| `defaultView` | `'day' \| 'month' \| 'year'` | day | SlDatePicker | The grid the calendar opens on. |
+| `weekNumbers` | `boolean` | false | SlDatePicker | Adds a column of ISO 8601 week numbers to the calendar. |
+| `fixedWeeks` | `boolean` | true | SlDatePicker | 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 | SlDatePicker | Where the calendar opens relative to the field. When it does not fit on that side, it opens on the other. |
+| `closeOnSelect` | `'auto' \| 'always' \| 'never'` | auto | SlDatePicker | Whether choosing a day closes the calendar. auto closes it for a single date and keeps it open for a range or several dates, which need more than one press. |
+| `locale` | `string` | the provideSlotted locale, else en-US | SlDatePicker | A BCP 47 tag. Sets the order, separators and placeholders of the segments, the month and weekday names, the first day of the week and the date the trigger announces. |
+| `timeZone` | `string` | the browser’s time zone | SlDatePicker | The IANA time zone that decides which day is today. The value itself has no time zone. |
+| `firstDayOfWeek` | `number` | the locale’s | SlDatePicker | The day the calendar starts each week on, from 0 for Sunday to 6 for Saturday. |
+| `yearPivot` | `number` | 20 | SlDatePicker | How a two-digit typed year resolves: a year up to this many years ahead of today is read in this century, and a later one in the previous century. |
+| `calendar` | `'gregory'` | gregory | SlDatePicker | The calendar system. gregory is the only value today. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | SlDatePicker | One step of the control scale for the field and the trigger. Inside slField, an unset size follows the field. |
+| `variant` | `'outline' \| 'subtle' \| 'plain'` | outline | SlDatePicker | How much frame the field draws at rest: a border, a filled ground, or neither. |
+| `disabled` | `boolean` | — | SlDatePicker | Disables the segments and the trigger, and takes both out of the tab order. Read from the form control, then from the enclosing slField, when unset. |
+| `readOnly` | `boolean` | — | SlDatePicker | Keeps the date legible and focusable and disables the trigger, so the calendar cannot open. Read from the enclosing slField when unset. |
+| `invalid` | `boolean` | — | SlDatePicker | Draws the frame and the focus ring in the danger tone and sets aria-invalid. A date outside min and max, or refused by isDateUnavailable, sets it on its own. |
+| `required` | `boolean` | — | SlDatePicker | Sets aria-required on the field. Read from the enclosing slField when unset. In a form, add Validators.required. |
+| `clearable` | `boolean` | false | SlDatePicker | Adds a clear button to the field while it holds a date. It sets the value to null and returns focus to the field. |
+| `name` | `string` | — | SlDatePicker | Adds a hidden input with this name that submits the date as an ISO 8601 string, such as 2026-09-30. |
+| `messages` | `Partial<DatePickerMessages>` | — | SlDatePicker | Replaces the trigger’s accessible name, key by key: choose while no date is set, and change, with the date in its {date} slot, once one is. |
+| `slDatePickerPresets` | `Directive` | — | SlDatePicker | Marks your own element as the shortcuts column beside the calendar. |
+| `slDatePickerFooter` | `Directive` | — | SlDatePicker | Marks your own element as the actions row under the calendar. |
+| `provideDatePickerDefaults` | `Provider` | — | application | Sets timeZone, placement, closeOnSelect, calendar, size and variant for every slDatePicker under the injector. An input on one date picker wins. |
+| `ControlValueAccessor` | `NG_VALUE_ACCESSOR` | — | SlDatePicker | formControl, formControlName and ngModel bind the value, a form reset empties the field, and the form’s disabled state reaches the date picker. |
+| `Validator` | `NG_VALIDATORS` | — | SlDatePicker | Reports slottedDateRange, with min, max and the date, for a date outside the bounds, and slottedDateUnavailable for a date isDateUnavailable refuses. required is left to Validators.required. |
+| `exportAs` | `slDatePicker` | — | SlDatePicker | A template reference to the instance, with focus(), which focuses the first segment, and openSurface() and closeSurface(), which show and hide the calendar without a bound open input. openSurface() moves focus into the calendar. |
+| `ng-content slots` | `slDatePickerPresets, slDatePickerFooter` | — | SlDatePicker | The two places you fill, as directives on your own elements, so a button, a list or a toolbar keeps its own semantics. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `valueChange` | `ChangeRequest<CalendarValue>` | Before the value changes, from the field or the calendar. reason is keyboard for typing and for the calendar’s keys, pointer for a press on a day, clear for the clear button and blur for a date completed when the field loses focus. cancel() keeps the current value. There is no [(value)] two-way binding: bind [value] and update it from this output. |
+| `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 chosen day. cancel() keeps the current state. |
+
+## 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` |
+| `calendar` | `gregory` | `gregory` |
+
+## Rules
+
+- The trigger’s accessible name carries the chosen date in words, such as “Change date, Wednesday, September 30, 2026”. Focus returns to the trigger when the calendar closes from a chosen day or from Escape, so a screen reader announces the date there.
+- Opening the calendar from the trigger, from Alt+ArrowDown or from openSurface() moves focus to the chosen day, or to today when no date is set. While the calendar is open, Tab and Shift+Tab cycle through the shortcuts, the calendar and the footer.
+- 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 and returns focus to the trigger.
+- Alt+ArrowDown is a shortcut, never the only way in. ChromeOS turns it into PageDown before the browser receives it, so the trigger is always drawn.
+- 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.
+- The field and the calendar refuse the same dates, from the same min, max and isDateUnavailable, so a date the calendar disables marks the field invalid when it is typed.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-border-width`, `--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-radius`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-date-picker-content-border-color`, `--slotted-date-picker-content-color`, `--slotted-date-picker-content-padding`, `--slotted-date-picker-content-radius`, `--slotted-date-picker-content-shadow`, `--slotted-date-picker-invalid-focus-ring-color`, `--slotted-date-picker-radius`, `--slotted-date-picker-surface`, `--slotted-date-picker-trigger-active-background`, `--slotted-date-picker-trigger-color`, `--slotted-date-picker-trigger-hover-background`, `--slotted-date-picker-trigger-size`, `--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-radius-lg`, `--slotted-shadow-md`, `--slotted-space-2`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-9`, `--slotted-surface-raised`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-z-index-popover`
+
+## Examples
+
+See [date-picker.examples.md](./date-picker.examples.md).