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

package/docs/datetime-picker.md

@@ -0,0 +1,150 @@
+<!-- index: ./index.md -->
+# datetime-picker
+
+`data-ui="datetime-picker"` · Date and time field with a picker popover.
+
+## Import
+
+```ts
+import { SlDateTimePicker, SlDateTimePickerOption, SlDateTimePickerPresets, SlDateTimePickerFooter } from '@slotted/angular/datetime-picker';
+```
+
+Selector: `[slDateTimePicker]` · exportAs: `slDateTimePicker`
+
+## Minimal example
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlDateTimePicker } from '@slotted/angular/datetime-picker';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { plainDate, plainDateTime, plainTime } from '@slotted/core/date';
+
+@Component({
+  selector: 'app-datetime-picker-basic',
+  imports: [SlDateTimePicker, SlField, SlFieldDescription, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Pickup date and time</label>
+      <div slDateTimePicker name="pickupAt" [referenceDateTime]="firstPickup"></div>
+      <span slFieldDescription>
+        Type the date and time, or choose them from the calendar and the list.
+      </span>
+    </div>
+  `,
+})
+export class DateTimePickerBasic {
+  protected readonly firstPickup = plainDateTime(plainDate(2026, 9, 30), plainTime(9, 0));
+}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the element the directive is on | yes |
+| `control` | div | yes |
+| `trigger` | button | yes |
+| `positioner` | div, after the control inside the root | no |
+| `content` | div with role="dialog" | no |
+| `head` | div | no |
+| `head-value` | span | no |
+| `now` | button | no |
+| `presets` | your own element, marked slDateTimePickerPresets | no |
+| `panels` | div | no |
+| `date-panel` | div | no |
+| `time-panel` | div | no |
+| `list` | div with role="listbox" | no |
+| `option` | div with role="option" | no |
+| `empty` | div | no |
+| `footer` | your own element, marked slDateTimePickerFooter | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `PlainDateTime \| null` | — | SlDateTimePicker | The value, when you control it. Update it from (valueChange). |
+| `defaultValue` | `PlainDateTime \| null` | — | SlDateTimePicker | The starting value when the Datetime Picker holds its own state. Read once, on init. |
+| `open` | `boolean` | — | SlDateTimePicker | Whether the panel is open, when you control it. Update it from (openChange). |
+| `defaultOpen` | `boolean` | false | SlDateTimePicker | Whether the panel starts open. A panel that starts open does not take focus. |
+| `highlighted` | `DateTimePickerHighlight` | — | SlDateTimePicker | Where the reader is in the panel, as { date, time }: the day the calendar has focused and the time the list has highlighted. Set it to control the highlight; update it from (highlightedChange). |
+| `defaultHighlighted` | `DateTimePickerHighlight` | — | SlDateTimePicker | Where the highlight starts. Unset, the panel opens on the day of the value, or of referenceDateTime, and on the time nearest to it. |
+| `min` | `PlainDateTime` | — | SlDateTimePicker | The earliest whole value. The calendar disables the days before its date, and on its date the list starts at its time. |
+| `max` | `PlainDateTime` | — | SlDateTimePicker | The latest whole value. The calendar disables the days after its date, and on its date the list stops at its time. |
+| `minTime` | `PlainTime` | — | SlDateTimePicker | The earliest time on every day inside the range. It applies together with min. |
+| `maxTime` | `PlainTime` | — | SlDateTimePicker | The latest time on every day inside the range. It applies together with max. |
+| `isDateUnavailable` | `(date: PlainDate) => boolean` | — | SlDateTimePicker | Returns true for a day the reader cannot choose. The calendar disables it, its list is empty, and a typed value on it marks the Datetime Picker invalid. |
+| `isTimeUnavailable` | `(time: PlainTime, date: PlainDate) => boolean` | — | SlDateTimePicker | Returns true for a time the reader cannot choose on a given day, so the rule can differ by day. A typed value it refuses marks the Datetime Picker invalid. |
+| `step` | `number` | 900 | SlDateTimePicker | Seconds between two times in the list, counted from the earliest time of the day, or from midnight. It applies to the list only; the field accepts any time. Ignored when options is set. |
+| `options` | `readonly PlainTime[]` | — | SlDateTimePicker | The times the list offers, in the order given, in place of step. Bounds and predicates still refuse times in it. |
+| `maxOptions` | `number` | 1440 | SlDateTimePicker | The most rows the list draws, a whole day at a one-minute step. Past it, the list is cut, carries data-truncated, and the panel’s accessible description says the remaining times are typed into the field. |
+| `unavailableOptions` | `'disable' \| 'hide'` | disable | SlDateTimePicker | What the list does with a refused time: shows it disabled, or leaves it out. |
+| `locale` | `string` | the provider’s locale, then en-US | SlDateTimePicker | A BCP 47 tag. It sets the segments, the clock, the calendar’s month and weekday names, the times in the list and the date and time in words. |
+| `timeZone` | `string` | the browser’s time zone | SlDateTimePicker | The IANA time zone that decides today in the calendar and what Now and the default referenceDateTime read from the clock. The value itself has no time zone. |
+| `hourCycle` | `12 \| 24` | the locale’s | SlDateTimePicker | A 12-hour clock with a day period, or a 24-hour clock, in the field and the list. |
+| `granularity` | `'hour' \| 'minute' \| 'second'` | minute | SlDateTimePicker | The smallest unit the field writes. |
+| `calendar` | `'gregory'` | gregory | SlDateTimePicker | The calendar system. gregory is the only value today. |
+| `firstDayOfWeek` | `number` | the locale’s | SlDateTimePicker | The first day of the calendar’s week, from 0 for Sunday to 6 for Saturday. |
+| `months` | `number` | 1 | SlDateTimePicker | How many months the calendar draws side by side. |
+| `weekNumbers` | `boolean` | false | SlDateTimePicker | Adds a column of ISO 8601 week numbers to the calendar. |
+| `referenceDateTime` | `PlainDateTime` | the current date and time | SlDateTimePicker | The date and time assumed where the reader has given none: the month the calendar opens on, the time the list opens on after a day is pressed on an empty value, and the point a relative expression and the arrow keys on an empty field count from. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | SlDateTimePicker | One step of the control scale for the field, the trigger and the rows of the list. Inside a field, an unset size follows the field. |
+| `variant` | `'outline' \| 'subtle' \| 'plain'` | outline | SlDateTimePicker | The frame of the field: a border, a fill, or none at rest. |
+| `placement` | `'bottom-start' \| 'bottom' \| 'bottom-end' \| 'top-start' \| 'top' \| 'top-end'` | bottom-start | SlDateTimePicker | Where the panel opens relative to the control. When it does not fit on that side, it opens on the other. |
+| `openTo` | `'date' \| 'time'` | date | SlDateTimePicker | The surface that takes focus when the trigger or openSurface() opens the panel. Both surfaces are drawn either way. |
+| `closeOnSelect` | `'auto' \| 'always' \| 'never'` | auto | SlDateTimePicker | When a press closes the panel: auto on the press that completes the value, always on every press that changes the value, never on none. |
+| `disabled` | `boolean` | the field’s | SlDateTimePicker | Disables the field and the trigger. Unset, it follows the form control, then the enclosing field. |
+| `readOnly` | `boolean` | the field’s | SlDateTimePicker | Keeps the value focusable and legible, and disables the trigger. Unset, it follows the enclosing field. |
+| `invalid` | `boolean` | the field’s | SlDateTimePicker | Marks the value invalid. A value outside the bounds or refused by a predicate is invalid whatever this says. |
+| `required` | `boolean` | the field’s | SlDateTimePicker | Sets aria-required on the field. Unset, it follows the enclosing field. Validators.required checks the value in a form. |
+| `clearable` | `boolean` | false | SlDateTimePicker | Adds a clear button to the field while it holds any part of a value. The button empties both halves. |
+| `relative` | `boolean` | true | SlDateTimePicker | Whether +, - and = on a segment open a relative expression in the field, such as +2h. |
+| `name` | `string` | — | SlDateTimePicker | Adds a hidden input with this name that submits the value as YYYY-MM-DDTHH:mm:ss. |
+| `messages` | `Partial<DatetimePickerMessages>` | — | SlDateTimePicker | Replaces the words of the language in force, key by key: the trigger’s name with no value (choose) and with one (change, with the value in its {date} slot), the Now button (now), the sentence for a day with no time (empty), and the panel’s description when the list is cut at maxOptions (truncated). |
+| `slDateTimePickerPresets` | `directive` | — | SlDateTimePickerPresets | Marks your own element as the shortcuts row in the head, beside Now. |
+| `slDateTimePickerFooter` | `directive` | — | SlDateTimePickerFooter | Marks your own element as the row of actions under both surfaces. |
+| `provideDateTimePickerDefaults` | `provider` | — | application | Sets timeZone, hourCycle, granularity, calendar, step, maxOptions, placement, openTo, closeOnSelect, unavailableOptions, size and variant once for every Datetime Picker under it. A value set on one Datetime Picker still wins. |
+| `slDateTimePickerOption` | `ng-template` | — | SlDateTimePickerOption | Draws the content of one row of the list. The context carries the time as $implicit, plus date, label, selected, current and unavailable. The row keeps its role, states and keyboard. |
+| `exportAs` | `slDateTimePicker` | — | SlDateTimePicker | Gives a template the instance: focus() moves focus to the first segment of the field, openSurface() opens the panel and moves focus into it, as the trigger does, and closeSurface() closes it. |
+| `ControlValueAccessor` | `interface` | — | SlDateTimePicker | formControlName, formControl and ngModel bind the value. As a validator it reports slottedDateTimeRange outside min and max, slottedDateTimeWindow outside minTime and maxTime, slottedDateTimeUnavailable for a refused date or time, and slottedDateTimeIncomplete while only one half is typed. Validators.required covers an empty value. |
+| `(keydown)` | `EventListener` | — | SlDateTimePicker | A listener on the host runs before the Datetime Picker handles keys on the control, the trigger and the list. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `valueChange` | `DateTimeFieldChangeRequest \| ChangeRequest<PlainDateTime \| null>` | Before the value changes. reason is keyboard for typing, select for a press in the calendar, the list or Now, clear for the clear button and blur for a value completed when the field loses focus. When the field moved the value, the request also carries segments and incomplete, the half still missing. A value that does not change emits nothing. |
+| `openChange` | `ChangeRequest<boolean>` | Before the panel opens or closes. reason is pointer for the trigger, keyboard for Alt+ArrowDown and ArrowDown on the trigger, programmatic for openSurface() and closeSurface(), escape and outsidePress for a dismissal, and select for the press that closed it. |
+| `highlightedChange` | `ChangeRequest<DateTimePickerHighlight>` | When the reader moves through either surface: the day the calendar has focused and the time the list has highlighted, as one value. Moving the highlight never changes the value. |
+
+## 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` |
+| `openTo` | `date`, `time` | `date` |
+| `closeOnSelect` | `auto`, `always`, `never` | `auto` |
+| `unavailableOptions` | `disable`, `hide` | `disable` |
+| `hourCycle` | `12`, `24` | — |
+| `granularity` | `hour`, `minute`, `second` | `minute` |
+| `calendar` | `gregory` | `gregory` |
+
+## Rules
+
+- The panel has role="dialog" and holds a role="grid" and a role="listbox", the arrangement the APG Date Picker Combobox example uses for its popup. The trigger has aria-haspopup="dialog" and aria-expanded, and aria-controls only while the panel exists. Both surfaces are in the DOM at every width.
+- The trigger’s accessible name carries the chosen date and time in words, such as “Change date and time, September 30, 2026 at 9:00 AM”. Focus returns to the trigger when the panel closes from a press or from Escape, so a screen reader announces the value there. The listbox has its own accessible name, the day its times belong to.
+- Opening the panel from the trigger or from openSurface() moves focus into the surface openTo names: the focused day in the calendar, or the chosen or nearest time in the list. Alt+ArrowDown opens the panel and leaves focus in the field. While the panel is open, Tab and Shift+Tab cycle through the head, the calendar, the list and the footer; each surface is one Tab stop.
+- Moving the highlight through the list never changes the value; Enter, Space or a press does. Changing the value on every highlight would send one change per time the reader passes.
+- Escape closes in steps: an open relative expression in the field closes first, then the calendar returns from the month or year grid to the day grid, and then the panel closes and focus returns 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.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-font-size-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-padding-inline-sm`, `--slotted-control-radius`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-datetime-picker-content-border-color`, `--slotted-datetime-picker-content-color`, `--slotted-datetime-picker-content-padding`, `--slotted-datetime-picker-content-radius`, `--slotted-datetime-picker-content-shadow`, `--slotted-datetime-picker-invalid-focus-ring-color`, `--slotted-datetime-picker-label-color`, `--slotted-datetime-picker-list-block-size`, `--slotted-datetime-picker-now-active-background`, `--slotted-datetime-picker-now-background`, `--slotted-datetime-picker-now-border-color`, `--slotted-datetime-picker-now-color`, `--slotted-datetime-picker-now-hover-background`, `--slotted-datetime-picker-now-hover-border-color`, `--slotted-datetime-picker-now-icon-color`, `--slotted-datetime-picker-option-current-background`, `--slotted-datetime-picker-option-hover-background`, `--slotted-datetime-picker-option-radius`, `--slotted-datetime-picker-option-selected-background`, `--slotted-datetime-picker-option-selected-color`, `--slotted-datetime-picker-option-selected-hover-background`, `--slotted-datetime-picker-radius`, `--slotted-datetime-picker-sheet-inline-size`, `--slotted-datetime-picker-surface`, `--slotted-datetime-picker-time-panel-inline-size`, `--slotted-datetime-picker-trigger-active-background`, `--slotted-datetime-picker-trigger-color`, `--slotted-datetime-picker-trigger-hover-background`, `--slotted-datetime-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-font-size-sm`, `--slotted-font-weight-medium`, `--slotted-radius-lg`, `--slotted-radius-sm`, `--slotted-shadow-md`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-6`, `--slotted-space-9`, `--slotted-surface-raised`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-solid-hover`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-z-index-popover`
+
+## Examples
+
+See [datetime-picker.examples.md](./datetime-picker.examples.md).

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

@@ -0,0 +1,225 @@
+<!-- index: ./index.md -->
+# datetime-range-picker
+
+`data-ui="datetime-range-picker"` · Start and end date-times with a picker.
+
+## Examples
+
+### One end at a time
+
+Already open: two tabs say the two ends, and the panel shows the one being chosen — the calendar with both dates drawn, and the list of that end running on its day. Press a day: the run restarts on it, and the end’s time is kept.
+
+Excerpt — not a complete module
+
+```html
+<div slDateTimeRangePicker defaultOpen locale="pt-BR" [defaultValue]="rental"></div>
+```
+
+### Focus follows the missing half
+
+Press a day: focus moves to the list, because the start has no time. Press a time: the tab moves to the return and focus goes back to the grid, because the return has no date. Press a day and then a time: the work is whole and the surface closes. The hint says each step.
+
+Excerpt — not a complete module
+
+```html
+<div slDateTimeRangePicker defaultOpen locale="pt-BR"></div>
+```
+
+### The duration, while the run is drawn
+
+Move along the grid: the band says the days and hours the rental would last for the day under you, with the time the end already holds. On the same day, every row of the end list says it too.
+
+Excerpt — not a complete module
+
+```html
+<div slDateTimeRangePicker locale="pt-BR" [defaultValue]="open"></div>
+```
+
+### Limits, explained
+
+A rental lasts an hour to thirty days. With a pickup chosen, the grid refuses the days past the thirtieth, the end list refuses the times inside the first hour, and the band says the rule. minLength and maxLength are seconds.
+
+Excerpt — not a complete module
+
+```html
+<div slDateTimeRangePicker [maxLength]="30 * 86400" [minLength]="3600"></div>
+```
+
+### Two bounds, and the day they meet on
+
+The agency opens from 08:00 to 18:00, and the fleet is booked from the 10th at 09:00. min and minTime both apply: on the 10th the lists start at 09:00, on every later day at 08:00 — the rule MUI declines.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slDateTimeRangePicker
+  [max]="seasonEnd"
+  [maxTime]="closing"
+  [min]="seasonStart"
+  [minTime]="opening"
+></div>
+```
+
+### Unavailable days and times
+
+The agency is closed on Sundays, and closes at noon on Saturdays. isDateUnavailable greys the Sundays; isTimeUnavailable empties the afternoon of a Saturday, on that day only. A rental cannot cross a Sunday while it is contiguous.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slDateTimeRangePicker
+  [isDateUnavailable]="isSunday"
+  [isTimeUnavailable]="isSaturdayAfternoon"
+></div>
+```
+
+### Months
+
+One month by default, because the list stands beside the grid and two months beside a list do not fit in 720 pixels. Ask for two: the list drops under the grid where the row is too narrow.
+
+Excerpt — not a complete module
+
+```html
+<div slDateTimeRangePicker [months]="2"></div>
+```
+
+### Now
+
+"Now" writes the current date and time into the current end, both halves, and the focus rule takes over. referenceDateTime fixes the clock for a story or a test.
+
+Excerpt — not a complete module
+
+```html
+<div slDateTimeRangePicker [messages]="{ now: 'Agora' }" [referenceDateTime]="clock"></div>
+```
+
+### Presets
+
+The rentals the agency offers by name. Each is a button with slDateTimeRangePickerPreset and its own range; pressing one writes the value and closes, and the one equal to the value is marked. The list is the product’s.
+
+Excerpt — not a complete module
+
+```html
+<div slDateTimeRangePicker>
+  <div slDateTimeRangePickerPresets>
+    <button [slDateTimeRangePickerPreset]="weekend">Fim de semana</button>
+    <button [slDateTimeRangePickerPreset]="week">Uma semana</button>
+  </div>
+</div>
+```
+
+### One end only
+
+A pickup and no return, written where the reader sees it. Open the surface: it opens on the return tab, the grid holds the start of an open run, and the list runs on the day the grid has focused until a return day is pressed.
+
+Excerpt — not a complete module
+
+```html
+<div slDateTimeRangePicker clearable [defaultValue]="open"></div>
+```
+
+### Size
+
+The three steps the frame takes. Type, height, gutter and the clear’s box follow the control scales, so a rental in a dense fleet table shrinks whole rather than in parts.
+
+Excerpt — not a complete module
+
+```html
+<div slDateTimeRangePicker size="sm"></div>
+<div slDateTimeRangePicker size="md"></div>
+<div slDateTimeRangePicker size="lg"></div>
+```
+
+### Variant
+
+How much frame the control shows at rest. plain is for a box that belongs to something else — a table cell — and draws its ring inward.
+
+Excerpt — not a complete module
+
+```html
+<div slDateTimeRangePicker variant="outline"></div>
+<div slDateTimeRangePicker variant="subtle"></div>
+<div slDateTimeRangePicker variant="plain"></div>
+```
+
+### States
+
+Read-only, disabled, invalid from the family and invalid from the consumer. A return before its pickup is invalid on the end field and on the frame, and nothing is swapped.
+
+Excerpt — not a complete module
+
+```html
+<div slDateTimeRangePicker readOnly [defaultValue]="rental"></div>
+<div slDateTimeRangePicker disabled [defaultValue]="rental"></div>
+<div slDateTimeRangePicker [defaultValue]="reversed"></div>
+<div slDateTimeRangePicker invalid [defaultValue]="rental"></div>
+```
+
+### Forms
+
+Two hidden inputs under startName and endName send YYYY-MM-DDTHH:mm:ss with a plain form post, whether the reader typed the values or pressed them.
+
+Excerpt — not a complete module
+
+```html
+<form [formGroup]="reservation" (ngSubmit)="reserve()">
+  <div
+    slDateTimeRangePicker
+    formControlName="rental"
+    startName="retirada"
+    endName="devolucao"
+  ></div>
+  <button type="submit">Reservar</button>
+</form>
+```
+
+### Narrow
+
+In a column narrower than the value the frame stays one line and the summary is cut with an ellipsis; the trigger’s name carries it whole. Open it: the list drops under the grid.
+
+Excerpt — not a complete module
+
+```html
+<div class="slotted-demo-measure">
+  <div slDateTimeRangePicker locale="pt-BR" [defaultValue]="rental"></div>
+</div>
+```
+
+### Composition
+
+provideDateTimeRangePickerDefaults sets the months, the step and how a duration is written once, provideSlotted the language and every word; the exported instance opens, closes and focuses; the slDateTimeRangePickerOption template replaces what a row draws; position — which tab — is the consumer’s to own.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slDateTimeRangePicker
+  #picker="slDateTimeRangePicker"
+  [position]="position"
+  (positionChange)="position = $event.value"
+>
+  <ng-template slDateTimeRangePickerOption let-label="label" let-duration="duration">
+    {{ label }} <small>{{ duration }}</small>
+  </ng-template>
+</div>
+<button type="button" (click)="picker.openSurface()">Abrir</button>
+```
+
+### Keyboard
+
+Enter opens onto the field of the current end; ArrowDown opens onto the grid, on its day. ArrowLeft and ArrowRight on a tab move to the other end. In the grid, the arrows move by day and the band says the duration; Enter writes a date and carries focus to the list. Escape walks the calendar down a view, then abandons the work.
+
+Excerpt — not a complete module
+
+```html
+<!-- Enter, Space         open onto the current end's field -->
+<!-- ArrowDown, Alt+Down  open onto the current end's day in the grid -->
+<!-- ArrowLeft, Right     on a tab: the other end, and its panel -->
+<!-- the grid's keys      calendar's, unchanged; the band says the duration -->
+<!-- Arrows, Page keys    move the list's highlight; Enter writes the time -->
+<!-- Escape               the calendar's view, then close and abandon -->
+<!-- Tab                  tabs, field, now, presets, grid, list, footer, done -->
+<div slDateTimeRangePicker></div>
+```