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

package/docs/time-field.md

@@ -0,0 +1,291 @@
+<!-- index: ./index.md -->
+# time-field
+
+`data-ui="time-field"` · Typed time input split into segments.
+
+## Import
+
+```ts
+import { SlTimeField, SlTimeFieldStart, SlTimeFieldEnd } from '@slotted/angular/time-field';
+```
+
+Selector: `[slTimeField]` · exportAs: `slTimeField`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div slField>
+  <label slFieldLabel>Hora de início</label>
+  <div slTimeField clearable locale="pt-BR" name="inicio"></div>
+  <span slFieldDescription>A reunião começa nesta hora.</span>
+</div>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div, or the element render returns | yes |
+| `segments` | div | yes |
+| `segment` | div | yes |
+| `literal` | span | yes |
+| `duration` | input | no |
+| `preview` | span | no |
+| `value-text` | span | yes |
+| `start` | span | no |
+| `end` | span | no |
+| `clear` | button | no |
+| `hidden-input` | input | yes |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `PlainTime \| null` | — | SlTimeField | Present means the consumer owns the value. The control asks and waits rather than moving it. |
+| `defaultValue` | `PlainTime \| null` | — | SlTimeField | The value the control starts from when nobody else writes one. Read once, in ngOnInit. |
+| `min` | `PlainTime` | — | SlTimeField | The earliest time the control accepts. Reported through aria-valuemin, and as slottedTimeRange to a reactive form. |
+| `max` | `PlainTime` | — | SlTimeField | The latest time the control accepts. Reported through aria-valuemax, and as slottedTimeRange to a reactive form. |
+| `isTimeUnavailable` | `(time: PlainTime) => boolean` | — | SlTimeField | Refuses particular times — a lunch break, a booked slot, a closed shop. Reported as slottedTimeUnavailable to a reactive form. |
+| `locale` | `string` | provideSlotted | SlTimeField | BCP 47. Decides the field order, the separators, the placeholder and whether a day period is drawn at all. Unset, the language in force decides. |
+| `timeZone` | `string` | runtime | SlTimeField | Which zone answers "what time is it now", and nothing else. The value itself is a wall-clock time and carries no zone. |
+| `hourCycle` | `12 \| 24` | locale | SlTimeField | The question a consumer asks about the clock. Which variant of each — h11 or h12, h23 or h24 — is the locale’s own. |
+| `granularity` | `'hour' \| 'minute' \| 'second'` | minute | SlTimeField | The smallest unit the field draws and takes. Seconds exist only when the value has them. |
+| `referenceTime` | `PlainTime` | now | SlTimeField | What an empty segment steps from and what a duration resolves against. Stating it is what makes a story and a spec deterministic. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | SlTimeField | The type step, matching the field around it. |
+| `variant` | `'outline' \| 'subtle' \| 'plain'` | outline | SlTimeField | How much frame the control shows at rest. |
+| `disabled` | `boolean` | — | SlTimeField | Unstated rather than false, so the control defers to the field — and to the form, which sets it through setDisabledState. |
+| `readOnly` | `boolean` | — | SlTimeField | Readable, copyable and focusable, and not changeable. Arrow keys still walk between fields; nothing steps. |
+| `invalid` | `boolean` | — | SlTimeField | Unstated rather than false. Retargets the focus ring. |
+| `required` | `boolean` | — | SlTimeField | Unstated rather than false. Reaches the group as aria-required; the form’s own Validators.required states the rule. |
+| `clearable` | `boolean` | false | SlTimeField | Draws a button that empties the value and returns focus to the first segment. |
+| `relative` | `boolean` | true | SlTimeField | Whether +, - and = open the duration expression. Set it false and the three keys do nothing. |
+| `messages` | `Partial<TimeFieldMessages>` | — | SlTimeField | Words laid over the language in force, key by key: the clear button’s name (clear), the expression region’s name (duration) and the preview of a time past midnight (nextDay, with a {time} slot). |
+| `name` | `string` | — | SlTimeField | The name the hidden input carries the HH:mm:ss string under, for a plain form post. |
+| `slTimeFieldStart` | `directive` | — | SlTimeFieldStart | An adornment before the time in the reading direction, on the consumer’s own element. |
+| `slTimeFieldEnd` | `directive` | — | SlTimeFieldEnd | An adornment after the time in the reading direction, on the consumer’s own element. |
+| `provideTimeFieldDefaults` | `provider` | — | application | Sets timeZone, hourCycle, granularity, relative, size and variant once for everything under it. A control that states any of them itself still wins. The locale and the words come from provideSlotted. |
+| `ControlValueAccessor` | `interface` | — | SlTimeField | The control belongs in a reactive form and in a template form. It is the integration point React has no equivalent of, and the asymmetry is recorded rather than levelled away. |
+| `Validator` | `interface` | — | SlTimeField | slottedTimeRange and slottedTimeUnavailable are validity this control owns and no other validator can see. required is left to Angular’s own, because a form already has a word for it. |
+| `exportAs` | `slTimeField` | — | SlTimeField | A template reaches the instance for focus(), focusEntry() and clear(), and reads the derived time() signal. |
+| `(keydown)` | `EventListener` | — | SlTimeField | The family handles the keys on the host, so a consumer’s own listener on the same element runs first — which is the composition React gets by calling the consumer’s handler before acting. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `valueChange` | `TimeFieldChangeRequest` | Before the value moves, and cancellable. The request carries the new value, the value it replaces, the segments, whether a duration crossed midnight, the reason and the originating event. It arrives when a run of typed digits ends — never on every keystroke inside one, because typing 23 into an hour passes through 2 on the way. There is no two-way [(value)]: one slot could carry none of that, and a form gets the same movement through ControlValueAccessor. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `variant` | `outline`, `subtle`, `plain` | `outline` |
+| `hourCycle` | `12`, `24` | — |
+| `granularity` | `hour`, `minute`, `second` | `minute` |
+
+## Rules
+
+- The fields are a role="group" whose accessible name is the whole time in words, which is what the APG’s spin-button example names as the thing that lets a screen-reader user perceive a time without visiting every button and remembering each.
+- Each field is a role="spinbutton" carrying aria-valuenow, aria-valuemin, aria-valuemax and aria-valuetext — and the day period is why aria-valuetext is not optional: aria-valuenow there is 0 or 1, which is not a name in any language.
+- Exactly one field is in the tab sequence at a time; the arrows walk between them and mirror in a right-to-left document, because the keys are physical and the order they walk is the writing order.
+- The expression region is a real input with its own accessible name, and its preview is a polite live region: a reader is being asked to accept a value they did not write, so the resolved time has to be perceivable before Enter — including to a reader who cannot see it.
+- A step wraps inside its own field and never carries: 23:59 stepping the minute up reaches 23:00 rather than midnight, which is the example’s stated rule and the difference between one arrow press changing one field and changing two.
+
+## Tokens
+
+`--slotted-border-subtle`, `--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-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-radius-none`, `--slotted-radius-xs`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-surface-sunken`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-time-field-action-active-background`, `--slotted-time-field-action-color`, `--slotted-time-field-action-hover-background`, `--slotted-time-field-action-size`, `--slotted-time-field-adornment-color`, `--slotted-time-field-background`, `--slotted-time-field-border-color`, `--slotted-time-field-color`, `--slotted-time-field-disabled-background`, `--slotted-time-field-disabled-border-color`, `--slotted-time-field-disabled-color`, `--slotted-time-field-hover-border-color`, `--slotted-time-field-icon-size-min`, `--slotted-time-field-invalid-border-color`, `--slotted-time-field-invalid-edge-width`, `--slotted-time-field-invalid-focus-ring-color`, `--slotted-time-field-literal-color`, `--slotted-time-field-period-min-inline-size`, `--slotted-time-field-placeholder-color`, `--slotted-time-field-plain-hover-background`, `--slotted-time-field-preview-color`, `--slotted-time-field-preview-next-color`, `--slotted-time-field-radius`, `--slotted-time-field-readonly-background`, `--slotted-time-field-relative-border-color`, `--slotted-time-field-segment-focus-background`, `--slotted-time-field-segment-focus-color`, `--slotted-time-field-segment-min-inline-size`, `--slotted-time-field-segment-padding-inline`, `--slotted-time-field-segment-radius`, `--slotted-time-field-shadow`, `--slotted-time-field-subtle-background`, `--slotted-time-field-subtle-border-color`, `--slotted-time-field-subtle-hover-background`, `--slotted-tone-accent-border`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-tone-warning-text`
+
+## Examples
+
+### The locale writes the time
+
+The same component in four locales. The field order, the separators, the placeholder and whether a day period exists all come from Intl — nobody writes a format string.
+
+Excerpt — not a complete module
+
+```html
+<div slTimeField locale="pt-BR"></div>
+<div slTimeField locale="en-US"></div>
+<div slTimeField locale="ja-JP"></div>
+<div slTimeField locale="ar-EG"></div>
+```
+
+### Four hour cycles, not a boolean
+
+Intl resolves h11, h12, h23 and h24, and a boolean can say two of them. Ask for 12 in ja-JP and the hour runs from zero beside 午前, because that is what the locale writes. The public axis stays 12 | 24.
+
+Excerpt — not a complete module
+
+```html
+<div slTimeField locale="en-US" [hourCycle]="12"></div>
+<div slTimeField locale="ja-JP" [hourCycle]="12"></div>
+<div slTimeField locale="en-US" [hourCycle]="24"></div>
+```
+
+### Granularity
+
+How much of the time is drawn, and how much of it is typed. Seconds exist only when the value has them; an hour-granularity field is one spin button and one value.
+
+Excerpt — not a complete module
+
+```html
+<div slTimeField granularity="hour" locale="pt-BR"></div>
+<div slTimeField granularity="minute" locale="pt-BR"></div>
+<div slTimeField granularity="second" locale="pt-BR"></div>
+```
+
+### A time written as a duration
+
+Press +, - or = on any segment and the field takes an expression instead: +40m, 1h30, -15, 0. What it resolves to is drawn beside it before Enter commits anything, and Escape puts the segments back untouched. No surveyed implementation offers it.
+
+Excerpt — not a complete module
+
+```html
+<div slTimeField locale="pt-BR" [referenceTime]="afternoon"></div>
+```
+
+### A duration that crosses midnight
+
++90m at 23:00 is 00:30 the next day, and this library holds no day beside a time. The preview changes tone, says so in words, and the request carries crossesMidnight — so a consumer holding a PlainDateTime knows to add one. Nothing else surveyed says anything at all.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slTimeField
+  locale="pt-BR"
+  [messages]="{ nextDay: '{time} no dia seguinte' }"
+  [referenceTime]="late"
+  (valueChange)="save($event.value, $event.crossesMidnight)"
+></div>
+```
+
+### Size
+
+The three steps a field can be. A control inside a field takes the field’s step, so a form cannot end up with a small field holding a medium control on one row.
+
+Excerpt — not a complete module
+
+```html
+<div slTimeField size="sm"></div>
+<div slTimeField size="md"></div>
+<div slTimeField size="lg"></div>
+```
+
+### Variant
+
+How much frame the control shows. outline takes the ground it is on, subtle sinks into the page, and plain shows nothing until it is used — which is what a dense table needs.
+
+Excerpt — not a complete module
+
+```html
+<div slTimeField variant="outline"></div>
+<div slTimeField variant="subtle"></div>
+<div slTimeField variant="plain"></div>
+```
+
+### Bounds
+
+min and max fence the value and reach the spin buttons as aria-valuemin and aria-valuemax. A time outside them is invalid whatever the field around it says, because the control is the only thing that knows.
+
+Excerpt — not a complete module
+
+```html
+<div slTimeField [min]="opens" [max]="closes"></div>
+```
+
+### Times the product refuses
+
+isTimeUnavailable answers a lunch break, a booked slot, a closed shop — anything a pair of bounds cannot say. A predicate reaches every time; three lists of numbers reach only the ones on a unit boundary.
+
+Excerpt — not a complete module
+
+```html
+<div slTimeField locale="pt-BR" [isTimeUnavailable]="isLunch"></div>
+```
+
+### States
+
+Read-only stays focusable and copyable and never looks disabled; disabled answers no key and no pointer; invalid keeps its focus ring and retargets its colour. Tab through the row to see each one answer.
+
+Excerpt — not a complete module
+
+```html
+<div slTimeField readOnly></div>
+<div slTimeField invalid></div>
+<div slTimeField disabled></div>
+<div slTimeField required></div>
+```
+
+### Clearing
+
+The button appears only once a segment holds something, and pressing it empties every field, emits the clear reason and puts focus back on the first segment rather than leaving it nowhere.
+
+Excerpt — not a complete module
+
+```html
+<div slTimeField clearable [messages]="{ clear: 'Limpar a hora' }"></div>
+```
+
+### Adornments
+
+The two slots take an icon, a mark or a word, and both are named for the reading direction rather than for a side, so the same markup reads correctly in a right-to-left document. A time zone label belongs here: the value itself is a wall-clock time and carries no zone.
+
+Excerpt — not a complete module
+
+```html
+<div slTimeField>
+  <span slTimeFieldStart><span slIcon></span></span>
+  <span slTimeFieldEnd>BRT</span>
+</div>
+```
+
+### In a form
+
+The value reaches a plain form post as an HH:mm:ss string through a hidden input, so a server reads it without any JavaScript touching the control. A half-typed time posts nothing at all, because it is not a time.
+
+Excerpt — not a complete module
+
+```html
+<form [formGroup]="form" (ngSubmit)="save()">
+  <div slField>
+    <label slFieldLabel>Hora de início</label>
+    <div slTimeField formControlName="inicio" required></div>
+  </div>
+</form>
+```
+
+### Content the family did not choose
+
+A day period written as a word rather than as two letters, a second granularity in a narrow column, and a right-to-left document — where the sequence still reads 14:30 rather than 30:14, because a clock time is a numeric run and bidi renders one left to right.
+
+Excerpt — not a complete module
+
+```html
+<div slTimeField granularity="second" locale="es-MX" [hourCycle]="12"></div>
+```
+
+### Composition and escape hatches
+
+The provider sets the clock once for everything under it, provideSlotted the language; render substitutes the frame’s element; and the ref carries focus(), clear() and which field holds focus.
+
+Excerpt — not a complete module
+
+```html
+<div slTimeField #hora="slTimeField" locale="pt-BR"></div>
+<button type="button" (click)="hora.focus()">Focar</button>
+<button type="button" (click)="hora.clear()">Limpar</button>
+```
+
+### The keyboard
+
+Every key the spin-button pattern lists, plus the two the pattern has no example for: the arrows across, which are logical rather than physical, and the three characters that open a duration. Put focus in the field and try them.
+
+Excerpt — not a complete module
+
+```html
+<div slTimeField (keydown)="onKeyDown($event)"></div>
+```