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

package/docs/date-field.md

@@ -0,0 +1,235 @@
+<!-- index: ./index.md -->
+# date-field
+
+`data-ui="date-field"` · Typed date input split into segments.
+
+## Import
+
+```ts
+import { SlDateField, SlDateFieldStart, SlDateFieldEnd } from '@slotted/angular/date-field';
+```
+
+Selector: `[slDateField]` · exportAs: `slDateField`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div slField>
+  <label slFieldLabel>Vencimento</label>
+  <div slDateField clearable locale="pt-BR" name="vencimento"></div>
+  <span slFieldDescription>A fatura vence nesta data.</span>
+</div>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | div, the consumer’s own element | yes |
+| `segments` | div | yes |
+| `segment` | div | yes |
+| `literal` | span | yes |
+| `start` | span | no |
+| `end` | span | no |
+| `clear` | button | no |
+| `hidden-input` | input | yes |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `PlainDate \| null` | — | SlDateField | The date the control shows. Present means the consumer owns it: the control asks and waits rather than moving it. |
+| `defaultValue` | `PlainDate \| null` | — | SlDateField | The date the control starts from when nobody else writes one. Read once, in ngOnInit, because Angular binds inputs after it constructs a component. |
+| `min` | `PlainDate` | — | SlDateField | The earliest date the control accepts. Reported through each segment’s aria-valuemin, and as the slottedDateRange form error. |
+| `max` | `PlainDate` | — | SlDateField | The latest date the control accepts, on the same terms as min. |
+| `isDateUnavailable` | `(date: PlainDate) => boolean` | — | SlDateField | Refuses particular dates — a weekend, a holiday, a day already booked. Reported as the slottedDateUnavailable form error. |
+| `locale` | `string` | the language in force | SlDateField | BCP 47. Decides the field order, the separators, the placeholder and the language a month is announced in. |
+| `timeZone` | `string` | the runtime’s | SlDateField | Which zone answers "what is today", and nothing else. The value itself has no zone. |
+| `firstDayOfWeek` | `number` | the locale’s | SlDateField | 0 is Sunday. Unused by the field itself; it is here so one provider configures the field and the calendar beside it. |
+| `yearPivot` | `number` | 20 | SlDateField | How far ahead a two-digit year may land before it is read as last century. 0 sends every future year into the past, which is what a birth date wants. |
+| `calendar` | `'gregory'` | gregory | SlDateField | The calendar system the value is written in. One value today, and an axis rather than a silence so a second one is not a contract break. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | SlDateField | The type step, matching the field around it. |
+| `variant` | `'outline' \| 'subtle' \| 'plain'` | outline | SlDateField | How much frame the control shows at rest. |
+| `disabled` | `boolean` | — | SlDateField | Unstated rather than false, so the control defers to the field. A form that disables the control from its model reaches the same state. |
+| `readOnly` | `boolean` | — | SlDateField | Readable, copyable and focusable, and not changeable. Arrow keys still walk between fields; nothing steps. |
+| `invalid` | `boolean` | — | SlDateField | Unstated rather than false. Retargets the focus ring. |
+| `required` | `boolean` | — | SlDateField | Unstated rather than false. Reaches the group as aria-required. |
+| `clearable` | `boolean` | false | SlDateField | Draws a button that empties the value and returns focus to the first segment. |
+| `messages` | `Partial<DateFieldMessages>` | — | SlDateField | Words laid over the language in force, key by key: the clear button’s accessible name (clear). |
+| `name` | `string` | — | SlDateField | The name the hidden input carries the ISO string under, for a plain form post. |
+| `provideDateFieldDefaults` | `Provider` | — | application | Sets timeZone, firstDayOfWeek, yearPivot, calendar, size and variant once for everything under the injector. A control that states any of them itself still wins. |
+| `exportAs` | `slDateField` | — | SlDateField | Hands a template the instance, so focus(), clear() and the derived date() signal are reachable without a component of its own. |
+| `ControlValueAccessor` | `implemented` | — | SlDateField | formControl, formControlName and ngModel all drive the control, and a form that disables it from its model reaches setDisabledState. |
+| `Validator` | `implemented` | — | SlDateField | min, max and isDateUnavailable report as slottedDateRange and slottedDateUnavailable. required is left to Angular’s own validator, because a form already has a word for it and two would disagree. |
+| `slDateFieldStart / slDateFieldEnd` | `Directive` | — | consumer element | The two adornment slots, as directives on the consumer’s own element, so an icon, a kbd or a span all keep their own semantics. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `valueChange` | `DateFieldChangeRequest` | Before the value moves, and cancellable. The request carries the new value, the value it replaces, the segments, the reason and the originating event. It arrives when a run of typed digits ends — on the digit that fills a field, on the key that leaves it, or on blur — never on every keystroke inside one, because typing 2026 into a year passes through 2, 20 and 202 on the way. There is no two-way [(value)]: one slot could carry none of that. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `variant` | `outline`, `subtle`, `plain` | `outline` |
+| `calendar` | `gregory` | `gregory` |
+
+## Rules
+
+- The three fields are a role="group" whose accessible name is the whole date in words, which is what the APG’s spin-button example names as the thing that lets a screen-reader user perceive a date without visiting all three buttons and remembering each.
+- Each field is a role="spinbutton" carrying aria-valuenow, aria-valuemin, aria-valuemax and aria-valuetext — and the month’s valuetext is its name, because "nine" is not September in any language a reader is thinking in.
+- 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 APG’s own example is marked deprecated for its visible arrow buttons, which duplicate keys the reader already has. This family draws none, and takes the roles, the wrapping rules and the aria-valuetext guidance whole.
+- A step wraps inside its own field and never carries: December steps up to January without moving the year, 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-date-field-action-active-background`, `--slotted-date-field-action-color`, `--slotted-date-field-action-hover-background`, `--slotted-date-field-action-size`, `--slotted-date-field-adornment-color`, `--slotted-date-field-background`, `--slotted-date-field-border-color`, `--slotted-date-field-color`, `--slotted-date-field-disabled-background`, `--slotted-date-field-disabled-border-color`, `--slotted-date-field-disabled-color`, `--slotted-date-field-hover-border-color`, `--slotted-date-field-icon-size-min`, `--slotted-date-field-invalid-border-color`, `--slotted-date-field-invalid-edge-width`, `--slotted-date-field-invalid-focus-ring-color`, `--slotted-date-field-literal-color`, `--slotted-date-field-placeholder-color`, `--slotted-date-field-plain-hover-background`, `--slotted-date-field-radius`, `--slotted-date-field-readonly-background`, `--slotted-date-field-segment-focus-background`, `--slotted-date-field-segment-focus-color`, `--slotted-date-field-segment-min-inline-size`, `--slotted-date-field-segment-padding-inline`, `--slotted-date-field-segment-radius`, `--slotted-date-field-shadow`, `--slotted-date-field-subtle-background`, `--slotted-date-field-subtle-border-color`, `--slotted-date-field-subtle-hover-background`, `--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-tone-accent-border`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-danger-border`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`
+
+## Examples
+
+### The locale writes the date
+
+The same directive in four locales. The field order, the separators and the placeholder all come from Intl — nobody writes a format string, and a Japanese reader gets the year first.
+
+Excerpt — not a complete module
+
+```html
+<div slDateField locale="pt-BR"></div>
+<div slDateField locale="en-US"></div>
+<div slDateField locale="de-DE"></div>
+<div slDateField locale="ja-JP"></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 slDateField size="sm"></div>
+<div slDateField size="md"></div>
+<div slDateField 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 slDateField variant="outline"></div>
+<div slDateField variant="subtle"></div>
+<div slDateField variant="plain"></div>
+```
+
+### Bounds and unavailable dates
+
+min and max fence the value, and isDateUnavailable refuses particular days. Both are also form validity rules, so a reactive form reports them without a validator of its own.
+
+Excerpt — not a complete module
+
+```html
+<div
+  slDateField
+  [min]="{ year: 2026, month: 1, day: 1 }"
+  [max]="{ year: 2026, month: 12, day: 31 }"
+  [isDateUnavailable]="isHoliday"
+></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 slDateField readOnly></div>
+<div slDateField invalid></div>
+<div slDateField disabled></div>
+<div slDateField 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 slDateField clearable [messages]="{ clear: 'Limpar a data' }"></div>
+```
+
+### Adornments
+
+The two slots are directives on the consumer’s own element, so an icon, a kbd or a span all work and none of them loses its own semantics.
+
+Excerpt — not a complete module
+
+```html
+<div slDateField>
+  <sl-icon slDateFieldStart name="calendar" />
+  <span slDateFieldEnd>UTC-3</span>
+</div>
+```
+
+### In a form
+
+Reactive Forms drives it through ControlValueAccessor, and min, max and isDateUnavailable report as form errors through Validator — the two integration points React has no equivalent of.
+
+Excerpt — not a complete module
+
+```html
+<form [formGroup]="form">
+  <div slField>
+    <label slFieldLabel>Vencimento</label>
+    <div slDateField formControlName="vencimento" [min]="today"></div>
+    <span slFieldError>Escolha uma data futura.</span>
+  </div>
+</form>
+```
+
+### A date halfway through
+
+A day and a month with no year is not a date, so the value is null and the hidden input is empty — and that is not the same as an empty field. The request carries the segments, which is what a draft is saved from.
+
+Excerpt — not a complete module
+
+```html
+<div slDateField (valueChange)="onRequest($event)"></div>
+```
+
+### Composition and escape hatches
+
+provideDateFieldDefaults sets the zone and the pivot once, provideSlotted the language; exportAs hands a template the instance; and focus() and clear() are the two actions no input can express.
+
+Excerpt — not a complete module
+
+```html
+<div slDateField #data="slDateField" locale="pt-BR"></div>
+<button type="button" (click)="data.clear()">Limpar</button>
+```
+
+### The keyboard
+
+Every key the spin-button pattern lists, on the field that has focus. Note two behaviours nothing else here has: a step wraps inside its own field, and a day a short month could not hold comes back when a longer one can.
+
+Excerpt — not a complete module
+
+```html
+<!-- ArrowUp / ArrowDown  step one, wrapping inside the field -->
+<!-- PageUp / PageDown    five for a day or a month, ten for a year -->
+<!-- Home / End           the field's lowest and highest value -->
+<!-- ArrowLeft / Right    the previous and next field, in writing order -->
+<!-- 0-9                  fills the field and moves on when it is full -->
+<!-- Backspace / Delete   empties one field back to its placeholder -->
+<div slDateField></div>
+```