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

package/docs/time-range-picker.md

@@ -0,0 +1,152 @@
+<!-- index: ./index.md -->
+# time-range-picker
+
+`data-ui="time-range-picker"` · Start and end times with a picker.
+
+## Import
+
+```ts
+import { SlTimeRangePicker, SlTimeRangePickerPreset, SlTimeRangePickerPresets, SlTimeRangePickerFooter, SlTimeRangePickerOption } from '@slotted/angular/time-range-picker';
+```
+
+Selector: `[slTimeRangePicker]` · exportAs: `slTimeRangePicker`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div slField>
+  <label slFieldLabel>Reserva da sala</label>
+  <div
+    slTimeRangePicker
+    clearable
+    locale="pt-BR"
+    [messages]="{ start: 'Início', end: 'Fim' }"
+    [defaultValue]="booking"
+  ></div>
+</div>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the consumer’s own element | yes |
+| `control` | div | yes |
+| `trigger` | button | yes |
+| `summary` | span | yes |
+| `clear` | button | no |
+| `hidden-input` | input | yes |
+| `positioner` | div | no |
+| `content` | div | no |
+| `head` | div | no |
+| `tabs` | div | no |
+| `tab` | button | no |
+| `tab-label` | span | no |
+| `tab-value` | span | no |
+| `field` | div | no |
+| `now` | button | no |
+| `hint` | span | no |
+| `length` | span | no |
+| `limit` | span | no |
+| `presets` | div | no |
+| `preset` | button | no |
+| `panel` | div | no |
+| `list` | div | no |
+| `option` | div | no |
+| `option-duration` | span | no |
+| `empty` | div | no |
+| `footer` | div | no |
+| `done` | button | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `TimeRange \| null` | — | SlTimeRangePicker | { start, end }, each end nullable. Present means the consumer owns it. Both ends null is null. |
+| `defaultValue` | `TimeRange \| null` | — | SlTimeRangePicker | What it starts from when nobody else writes one. Read once. |
+| `open` | `boolean` | — | SlTimeRangePicker | Whether the surface is showing. Present means the consumer owns it. |
+| `defaultOpen` | `boolean` | false | SlTimeRangePicker | Whether it opens already showing. |
+| `position` | `'start' \| 'end'` | — | SlTimeRangePicker | The end being edited: the field and the panel carrying data-current, and where focus lands when the surface opens. Present means the consumer owns it. |
+| `defaultPosition` | `'start' \| 'end'` | start | SlTimeRangePicker | Where editing starts. |
+| `highlighted` | `{ start: PlainTime \| null; end: PlainTime \| null }` | — | SlTimeRangePicker | The highlighted option of each end’s list. Present means the consumer owns it. Moving it moves no value. |
+| `defaultHighlighted` | `{ start: PlainTime \| null; end: PlainTime \| null }` | — | SlTimeRangePicker | Where the highlights start; otherwise a list opens on its end, or on the nearest offered step. |
+| `min` | `PlainTime` | — | SlTimeRangePicker | The earliest time both fields and both lists accept. Crossed with the work: the start cannot step past the end, nor the end before the start. |
+| `max` | `PlainTime` | — | SlTimeRangePicker | The latest time any of the four accepts. |
+| `isTimeUnavailable` | `(time: PlainTime) => boolean` | — | SlTimeRangePicker | Refuses particular times. Typed at an end, it makes the control invalid; listed, the row cannot be pressed. |
+| `contiguous` | `boolean` | true | SlTimeRangePicker | Whether a run may cross an unavailable time. On, and with a start chosen, the options beyond the first unavailable one are refused in the end list; the search runs over the list, never over the seconds. |
+| `minLength` | `number` | — | SlTimeRangePicker | The shortest run allowed, in seconds. The lists refuse shorter ones and the band names the limit. |
+| `maxLength` | `number` | — | SlTimeRangePicker | The longest run allowed, in seconds. |
+| `lengthLabel` | `(seconds: number, locale?: string) => string` | durationLabel | SlTimeRangePicker | What the band and the rows say for a duration, in the product’s own words. The default writes "2 hr 30 min" in the family’s locale. |
+| `step` | `number` | 900 | SlTimeRangePicker | Seconds between two offered times, in both lists. Ignored when options states the list. The fields’ arrows move by one of their own unit regardless. |
+| `options` | `readonly PlainTime[]` | — | SlTimeRangePicker | The times to offer, stated rather than stepped; the same list for both ends. The bounds and the predicate still refuse. |
+| `maxOptions` | `number` | 1440 | SlTimeRangePicker | How many rows a list may reach before it is cut. Cut, the list carries data-truncated and the panel’s description says the rest is typed. |
+| `unavailableOptions` | `'disable' \| 'hide'` | disable | SlTimeRangePicker | What a refused time looks like in a list: drawn muted with aria-disabled, or left out. |
+| `locale` | `string` | provideSlotted | SlTimeRangePicker | BCP 47. Decides the field order, the digits, the day-period names and the duration’s units. Unset, the language in force decides. |
+| `timeZone` | `string` | — | SlTimeRangePicker | The zone "now" is read in. |
+| `hourCycle` | `12 \| 24` | — | SlTimeRangePicker | Twelve- or twenty-four-hour times. Unset, the locale decides. |
+| `granularity` | `'hour' \| 'minute' \| 'second'` | minute | SlTimeRangePicker | How much of a time the fields and the rows write. |
+| `referenceTime` | `PlainTime` | — | SlTimeRangePicker | What "now" is, for a story or a test; the clock otherwise. Anchors now and the relative expression. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | SlTimeRangePicker | The control scale of the frame. |
+| `variant` | `'outline' \| 'subtle' \| 'plain'` | outline | SlTimeRangePicker | How much frame the control shows at rest. |
+| `placement` | `'bottom-start' \| 'bottom' \| 'bottom-end' \| 'top-start' \| 'top' \| 'top-end'` | bottom-start | SlTimeRangePicker | Where the surface opens, before the positioner has read the room. |
+| `closeOnSelect` | `'auto' \| 'always' \| 'never'` | auto | SlTimeRangePicker | auto closes when a press completes the work; always closes on any press that changes the value; never closes on none. |
+| `disabled` | `boolean` | — | SlTimeRangePicker | Nothing answers; the value stays readable. |
+| `readOnly` | `boolean` | — | SlTimeRangePicker | Legible and copyable; the trigger and the clear are out of the tab sequence. |
+| `invalid` | `boolean` | — | SlTimeRangePicker | The consumer’s own word. Set, it wins; unset, the family’s own rules and the field around it decide. |
+| `required` | `boolean` | — | SlTimeRangePicker | Reaches both fields as aria-required. |
+| `clearable` | `boolean` | false | SlTimeRangePicker | Draws one clear on the frame, which empties both ends. |
+| `relative` | `boolean` | — | SlTimeRangePicker | Whether the field in the band takes the relative expression — +40, 1h30, = — the way a time-field does. |
+| `messages` | `Partial<TimeRangePickerMessages>` | — | SlTimeRangePicker | Words laid over the language in force, key by key: the two ends (start, end), the trigger’s names (choose; change with {start}, {end} and {length}; changeReversed), the hint (chooseTime with {end}; order, length, unavailable, bounds), the limit (limit.between, limit.atLeast, limit.atMost), now, done, clear, and a panel that is empty or cut short (empty, truncated). |
+| `startName` | `string` | — | SlTimeRangePicker | The name of the hidden input carrying the start. |
+| `endName` | `string` | — | SlTimeRangePicker | The name of the hidden input carrying the end. |
+| `slTimeRangePickerPresets` | `Directive` | — | SlTimeRangePicker | The consumer’s own shortcuts, as a directive on their own element holding slTimeRangePickerPreset buttons. |
+| `slTimeRangePickerFooter` | `Directive` | — | SlTimeRangePicker | The consumer’s own actions, before done in the footer, as a directive on their own element. |
+| `slTimeRangePickerOption` | `Directive on ng-template` | — | SlTimeRangePicker | What one row draws. The context carries the time as $implicit, plus position, label, duration, selected, current and unavailable. |
+| `slTimeRangePickerPreset` | `TimeRange \| (() => TimeRange)` | — | SlTimeRangePickerPreset | The range the press writes, or a function resolving it at the press. |
+| `provideTimeRangePickerDefaults` | `Provider` | — | application | Sets timeZone, hourCycle, granularity, step, maxOptions, unavailableOptions, closeOnSelect, placement, size, variant and lengthLabel once for everything under the injector. The locale and the words come from provideSlotted. |
+| `ControlValueAccessor and Validator` | `formControl, formControlName, ngModel` | — | SlTimeRangePicker | The whole { start, end } is the control’s value, and the family reports what no other validator can see: slottedTimeRangeOrder, slottedTimeRangeMin, slottedTimeRangeMax, slottedTimeRangeUnavailable and slottedTimeRangeLength. |
+| `exportAs` | `slTimeRangePicker` | — | SlTimeRangePicker | Hands a template the instance, so focus(), openSurface(), closeSurface() and choose(range) are reachable without a component of its own. |
+| `ng-content slots` | `slTimeRangePickerPresets, slTimeRangePickerFooter` | — | SlTimeRangePicker | The two places a consumer fills, as directives on their own elements, so a button, a list or a toolbar all keep their own semantics. |
+| `slTimeRangePickerOption` | `Directive on ng-template` | — | list | One row’s content, rendered once per option with the time, its label and its duration in the context; the row itself — role, states, keyboard, target size — stays the family’s. |
+| `slTimeRangePickerPreset` | `Directive on button` | — | presets | One shortcut on the consumer’s own button: it takes the range, writes data-part and type, and composes the click — a handler that calls preventDefault keeps the value where it was. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `valueChange` | `ChangeRequest<TimeRange \| null>` | Before the value moves, and cancellable. keyboard, blur or clear when an end was typed in the band, select when a press in the list, now, done or a preset completed the work or changed a whole one, clear for the clear button. A press that leaves the work with one end emits nothing. There is no two-way [(value)]: a form control carries it instead. |
+| `openChange` | `ChangeRequest<boolean>` | Before the surface opens or closes, and cancellable. pointer for the trigger and for done, keyboard for a key on the trigger, escape for the key, outsidePress for a press elsewhere, select for a press that completed the work. |
+| `positionChange` | `ChangeRequest<'start' \| 'end'>` | Before the current end moves. pointer for a press on a tab, keyboard for the arrows on one, select when a press in the list or a preset moved it, clear for the clear button, programmatic when the panel opened on the first missing end. |
+| `highlightedChange` | `ChangeRequest<{ start; end }>` | Before a highlight moves in either list. keyboard for the arrows and type-ahead, pointer for a press, programmatic when a list opened or changed under it. |
+
+## 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` |
+| `unavailableOptions` | `disable`, `hide` | `disable` |
+| `hourCycle` | `12`, `24` | — |
+| `granularity` | `hour`, `minute`, `second` | `minute` |
+| `position` | `start`, `end` | — |
+
+## Rules
+
+- The trigger’s accessible name carries both ends in words and the duration — "Change range, 14:00 – 16:30, 2 hr 30 min". Focus returns to it when the surface closes, so it is where a screen-reader user is told what happened; the summary’s ellipsis removes nothing they cannot hear.
+- The two ends are a tablist with automatic activation, and the panel is one end at a time: the list is a listbox named by the current tab, so "Start, 14:00" is heard before the first option. The hint is the list’s description, so what to choose next is read with it.
+- The duration is a polite live region: a sighted reader sees it beside every row, a screen-reader user hears it on every arrow.
+- Typing lives in the band: Enter on the trigger opens onto the first segment of the current end’s field, and the field keeps every key a time-field has, the relative expression included. On a coarse pointer the field is not drawn — a segment raises no keyboard — and Enter opens onto the list.
+- The rule datetime-picker wrote, once per end: a press that leaves the work with one end moves the tab to the other and carries focus to its list; the press that completes it closes the panel and returns focus to the trigger. A half-drawn run never reaches a form. Done is the way out when nothing closed it.
+- Escape is staged. dismissable-layer listens in the capture phase, so a field with an expression open takes the key first; then the surface closes and the work is abandoned.
+
+## 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-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-letter-spacing-wide`, `--slotted-line-height-sm`, `--slotted-radius-lg`, `--slotted-radius-none`, `--slotted-radius-pill`, `--slotted-radius-sm`, `--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-time-range-picker-action-active-background`, `--slotted-time-range-picker-action-color`, `--slotted-time-range-picker-action-hover-background`, `--slotted-time-range-picker-action-size`, `--slotted-time-range-picker-background`, `--slotted-time-range-picker-border-color`, `--slotted-time-range-picker-color`, `--slotted-time-range-picker-content-border-color`, `--slotted-time-range-picker-content-color`, `--slotted-time-range-picker-content-min-inline-size`, `--slotted-time-range-picker-content-padding`, `--slotted-time-range-picker-content-radius`, `--slotted-time-range-picker-content-shadow`, `--slotted-time-range-picker-current-color`, `--slotted-time-range-picker-current-size`, `--slotted-time-range-picker-disabled-background`, `--slotted-time-range-picker-disabled-border-color`, `--slotted-time-range-picker-disabled-color`, `--slotted-time-range-picker-done-active-background`, `--slotted-time-range-picker-done-background`, `--slotted-time-range-picker-done-color`, `--slotted-time-range-picker-done-hover-background`, `--slotted-time-range-picker-hint-color`, `--slotted-time-range-picker-hover-border-color`, `--slotted-time-range-picker-invalid-border-color`, `--slotted-time-range-picker-invalid-color`, `--slotted-time-range-picker-invalid-edge-width`, `--slotted-time-range-picker-invalid-focus-ring-color`, `--slotted-time-range-picker-label-color`, `--slotted-time-range-picker-length-color`, `--slotted-time-range-picker-limit-color`, `--slotted-time-range-picker-list-block-size`, `--slotted-time-range-picker-now-color`, `--slotted-time-range-picker-option-current-background`, `--slotted-time-range-picker-option-hover-background`, `--slotted-time-range-picker-option-radius`, `--slotted-time-range-picker-option-selected-background`, `--slotted-time-range-picker-option-selected-color`, `--slotted-time-range-picker-option-selected-hover-background`, `--slotted-time-range-picker-placeholder-color`, `--slotted-time-range-picker-plain-hover-background`, `--slotted-time-range-picker-preset-active-background`, `--slotted-time-range-picker-preset-background`, `--slotted-time-range-picker-preset-hover-background`, `--slotted-time-range-picker-preset-radius`, `--slotted-time-range-picker-preset-selected-background`, `--slotted-time-range-picker-preset-selected-color`, `--slotted-time-range-picker-radius`, `--slotted-time-range-picker-readonly-background`, `--slotted-time-range-picker-shadow`, `--slotted-time-range-picker-sheet-inline-size`, `--slotted-time-range-picker-subtle-background`, `--slotted-time-range-picker-subtle-border-color`, `--slotted-time-range-picker-subtle-hover-background`, `--slotted-time-range-picker-surface`, `--slotted-time-range-picker-tab-block-size`, `--slotted-tone-accent-border`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-solid-active`, `--slotted-tone-accent-solid-hover`, `--slotted-tone-accent-subtle-hover`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-danger-text`, `--slotted-tone-secondary-subtle`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-z-index-popover`
+
+## Examples
+
+See [time-range-picker.examples.md](./time-range-picker.examples.md).