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

package/docs/field.md

@@ -0,0 +1,127 @@
+<!-- index: ./index.md -->
+# field
+
+`data-ui="field"` · Label, control, help and error for one input.
+
+## Import
+
+```ts
+import {
+  provideFieldDefaults,
+  SlField,
+  SlFieldAction,
+  SlFieldControl,
+  SlFieldCounter,
+  SlFieldDescription,
+  SlFieldError,
+  SlFieldHeader,
+  SlFieldHelp,
+  SlFieldIndicator,
+  SlFieldLabel,
+} from '@slotted/angular/field';
+```
+
+Selector: `[slField]` · exportAs: `slField`
+
+## Minimal example
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlTextField, SlTextFieldInput } from '@slotted/angular/text-field';
+
+@Component({
+  selector: 'app-field-basic',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlTextField, SlTextFieldInput],
+  template: `
+    <div slField required>
+      <label slFieldLabel>Email</label>
+      <div slTextField>
+        <input slTextFieldInput type="email" autocomplete="email" />
+      </div>
+      <span slFieldDescription>Invoices are sent to this address.</span>
+    </div>
+  `,
+})
+export class FieldBasic {}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the element carrying slField, a div | yes |
+| `header` | the element carrying slFieldHeader, a div | no |
+| `label` | label[slFieldLabel] | no |
+| `mark` | span, drawn inside the label | no |
+| `help` | button[slFieldHelp] | no |
+| `indicator` | the element carrying slFieldIndicator, a span | no |
+| `action` | the a or button carrying slFieldAction | no |
+| `control` | the element carrying slFieldControl | no |
+| `counter` | the element carrying slFieldCounter | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | slField | The type step, matching the control the field wraps. The label, the messages and the counter read the control type scale, which the theme restates per density. |
+| `labelPlacement` | `'top' \| 'side'` | top | slField | Where the label sits. side reflows to top when the field’s own inline size is below 320 pixels; the query is a container query, not a viewport query. |
+| `necessity` | `'mark' \| 'optional' \| 'words' \| 'none'` | mark | slField | How necessity is written: an asterisk on a required field, (optional) on a field a reader may skip, both words, or nothing, for a form that says once that every field is required. |
+| `messages` | `Partial<FieldMessages>` | — | slField | Words that replace the active language’s, key by key: the necessity words (optional, required) and the help button’s name (help). |
+| `required` | `boolean` | — | slField | Unset rather than false. Reaches the control as aria-required, never as the native required, which would turn on browser constraint validation and change how the form submits. |
+| `invalid` | `boolean` | — | slField, slFieldCounter | On slField: unset rather than false; writes aria-invalid on the control and data-invalid on the field, and leaves the label’s colour unchanged. On slFieldCounter: the count has passed its limit, which can happen before validation runs, so it is the counter’s own state and defaults to false. |
+| `disabled` | `boolean` | from the group, then the token | slField, provideFieldDefaults | Unset rather than false, so a field follows the slFieldGroup around it. A stated value wins, and it reaches the control as the native attribute. |
+| `readOnly` | `boolean` | from the group, then the token | slField, provideFieldDefaults | Unset rather than false. Reaches the control as the native readonly, which keeps the value focusable and copyable. |
+| `id` | `string` | generated | slField | A static attribute, read with HostAttributeToken, that is the base of <id>-control, <id>-label, <id>-indicator, <id>-help, <id>-description, <id>-counter and <id>-error. When unset, an application-scoped factory generates it, so two applications in one server process do not collide. |
+| `slFieldHelp` | `string` | '' | button[slFieldHelp] | The help text, written once as the directive’s value. It reaches the tooltip and the hidden node that describes the button and the control. |
+| `open` | `boolean` | false | button[slFieldHelp] | Whether the hint is showing. It is the composed SlTooltip’s model, exposed on the button, so [(open)] binds it both ways. |
+| `side` | `'top' \| 'bottom' \| 'inline-start' \| 'inline-end' \| 'left' \| 'right'` | top | button[slFieldHelp] | Where the hint opens. It flips to the opposite side when there is no room. |
+| `aria-label` | `string` | messages.help | button[slFieldHelp] | The accessible name of the help button, read with HostAttributeToken. Unset, it is the field’s help message; written, it applies to this button alone. |
+| `type` | `'button' \| 'submit' \| 'reset'` | button on a button | [slFieldAction] | Written on a button that states no type, so the action never submits the form it sits in. A link gets none. |
+| `tone` | `'accent' \| 'secondary' \| 'success' \| 'warning' \| 'danger'` | secondary on slFieldDescription, danger on slFieldError | slFieldDescription, slFieldError | Both messages are inline-message roots and take its five tones, so a warning that does not block submission is slFieldError with tone="warning". |
+| `mark` | `'glyph' \| 'dot' \| 'none'` | none | slFieldDescription, slFieldError | The mark the message draws. A field’s messages draw none by default: an icon repeated under every control of a form reads as texture, and the ink and the sentence already state the tone. glyph draws the tone’s icon at the text size, and dot draws one neutral bullet. |
+| `live` | `'off' \| 'polite' \| 'assertive'` | off | slFieldDescription, slFieldError | Whether the message announces itself. off by default, because a message present when the page loads is not announced whatever role it carries. |
+| `reserve` | `boolean` | false | slFieldDescription, slFieldError | Keeps one line open whether or not there is a message, so a form that renders its error unconditionally does not move when the error appears. |
+| `exportAs="slFieldHelp"` | `SlFieldHelp` | — | button[slFieldHelp] | Hands the template the help button. Its state is the composed tooltip’s, bound through [(open)] and (openChangeRequest) rather than through a method. |
+| `exportAs="slField"` | `SlField` | — | slField | Hands the template the field instance, so a page can point its own element at ids().control, ids().description or ids().error without inventing an identifier, and read count() to draw a count of its own. |
+| `slFieldControl` | `directive` | — | any control element | Wires a control Slotted does not ship, on the consumer’s own element. Slotted’s own controls inject SlField themselves and need no directive, so their wiring cannot be written wrong. |
+| `provideFieldDefaults()` | `{ size, labelPlacement, necessity, disabled, readOnly }` | — | an application, a route or a component | The five decisions an application takes once for every field under the provider. slFieldGroup answers the same source for its own subtree, so a compact or disabled section is one attribute instead of one per field. |
+| `ng-content` | `projected content` | — | slField | The label or the header, the counter and the two message directives are selected by name; everything else, the control and anything beside it, is projected as written. slFieldHeader projects its content in the order the page wrote it. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `(openChange)` | `boolean` | On button[slFieldHelp], after the hint opened or closed. It is the output half of [(open)]. |
+| `(openChangeRequest)` | `ChangeRequest<boolean>` | On button[slFieldHelp], before the hint opens or closes, once per transition. reason is pointer for a hover or a press; keyboard for focus, Enter or Space; or escape, blur or programmatic. cancel() refuses the change. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `labelPlacement` | `top`, `side` | `top` |
+| `necessity` | `mark`, `optional`, `words`, `none` | `mark` |
+
+## Rules
+
+- No WAI-ARIA Authoring Practices pattern covers a field. Four sources cover it together: the Authoring Practices’ Providing Accessible Names and Descriptions practice (w3.org/WAI/ARIA/apg/practices/names-and-descriptions/) for the label and the description, the HTML specification for label[for] and fieldset[disabled], and WCAG 2.2 Understanding 3.3.1 Error Identification and 3.3.2 Labels or Instructions for the error and the help.
+- The label is associated explicitly. The naming practice records that some combinations of assistive technology and browser do not treat the implicit form, a label wrapping its control, as an accessible name, so the field derives an identifier and points for at it instead of nesting.
+- slField writes aria-required, never the native required. The native attribute turns on browser constraint validation and changes how the form submits, which describing a field must not do as a side effect. To get it, write required on the control: every written attribute is read with HostAttributeToken before the binding that would replace it. disabled and readonly are native, because taking a control out of the tab order and out of submission is what those attributes mean.
+- The accessible description is the indicator, the help, the description, the count and the error, in that order, whatever order the page writes them in. Each slot has one correct reading order, so the field states it instead of reading it from the DOM. The count is included so a counter is related to its control by identifier.
+- The help, the indicator and the action stand beside the label, never inside it. HTML forbids labelable content such as a button inside a label other than the control it labels, and a press on it would reach the label and move focus to the control instead of opening the hint.
+- The help is a toggletip. A tooltip alone opens on a touch screen only on a long press, because a tap triggers the element’s own action; the help button has no other action, so a press opens the hint and a second press closes it. The help text also sits in a hidden node inside the button, which describes the button and the control while the tooltip is closed, because a hidden element referenced directly still enters the description. The tooltip describes nothing, so the hint is never read twice.
+- A disabled field leaves its help and its action operable, because the help often explains why the field is disabled.
+- The necessity asterisk is hidden from assistive technology and the necessity words are not. A reader working through a form of twenty required fields does not need to hear “asterisk” twenty times, and aria-required already states the fact; (optional) is information no other attribute supplies.
+- The error is text in the page, as WCAG 2.2 SC 3.3.1 requires, never a tooltip. As an inline message it also carries the severity as visually hidden text, so a reader who cannot see the red ink hears “Error:” before the sentence.
+- live defaults to off, because a message present when the page finishes loading is not announced whatever role it carries. A form that shows the error after submit writes live="polite", and the reader hears it once.
+
+## Tokens
+
+`--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-inner-size-md`, `--slotted-control-inner-size-sm`, `--slotted-control-radius`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-foreground`, `--slotted-field-action-color`, `--slotted-field-action-color-active`, `--slotted-field-action-color-hover`, `--slotted-field-action-radius`, `--slotted-field-column-gap`, `--slotted-field-counter-color`, `--slotted-field-counter-invalid-color`, `--slotted-field-font-family`, `--slotted-field-header-gap`, `--slotted-field-help-color`, `--slotted-field-help-radius`, `--slotted-field-help-surface-active`, `--slotted-field-help-surface-hover`, `--slotted-field-icon-size-min`, `--slotted-field-label-color`, `--slotted-field-label-font-weight`, `--slotted-field-label-inline-size`, `--slotted-field-line-height`, `--slotted-field-mark-color`, `--slotted-field-mark-gap`, `--slotted-field-mark-text-color`, `--slotted-field-row-gap`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-font-weight-regular`, `--slotted-line-height-sm`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-5`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-text`, `--slotted-tone-danger-text`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`
+
+## Examples
+
+See [field.examples.md](./field.examples.md).