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

package/docs/text-field.md

@@ -0,0 +1,125 @@
+<!-- index: ./index.md -->
+# text-field
+
+`data-ui="text-field"` · Single-line text input.
+
+## Import
+
+```ts
+import {
+  provideTextFieldDefaults,
+  SlTextField,
+  SlTextFieldAction,
+  SlTextFieldEnd,
+  SlTextFieldInput,
+  SlTextFieldStart,
+} from '@slotted/angular/text-field';
+```
+
+Selector: `[slTextField]` · exportAs: `slTextField`
+
+## 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-text-field-basic',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlTextField, SlTextFieldInput],
+  template: `
+    <div slField required>
+      <label slFieldLabel>Company name</label>
+      <div slTextField clearable>
+        <input slTextFieldInput autocomplete="organization" defaultValue="Northwind Traders" />
+      </div>
+      <span slFieldDescription>Printed on every invoice and packing slip.</span>
+    </div>
+  `,
+})
+export class TextFieldBasic {}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the element carrying slTextField | yes |
+| `input` | input[slTextFieldInput] | yes |
+| `start` | any element carrying slTextFieldStart | no |
+| `end` | any element carrying slTextFieldEnd | no |
+| `action` | button[slTextFieldAction], inside slTextFieldStart or slTextFieldEnd | no |
+| `busy` | span[data-ui="spinner"], rendered by the frame | no |
+| `caps-lock` | span, rendered by the frame | no |
+| `clear` | button, rendered by the frame | no |
+| `copy` | button, rendered by the frame | no |
+| `reveal` | button, rendered by the frame | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `string` | — | slTextFieldInput | Makes the value controlled. It is written to the input the way a form control’s value is. Without it the input keeps its own value. |
+| `defaultValue` | `string` | — | slTextFieldInput | The value the input starts from when nothing else writes one. It is read once the inputs are bound. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | slTextField, provideTextFieldDefaults | The step of the control scale. Without it the text field takes the size of the field around it, then the one provideTextFieldDefaults sets. Height, padding, type and icon size come from the control scales, which the theme restates for each density. |
+| `variant` | `'outline' \| 'subtle' \| 'plain'` | outline | slTextField, provideTextFieldDefaults | How much frame the control draws. plain draws no border at rest and keeps the same box, for a dense table cell. |
+| `mono` | `boolean` | false | slTextField, provideTextFieldDefaults | Sets the value in the monospaced font with tabular figures, for identifiers, hashes and keys. |
+| `clearable` | `boolean` | false | slTextField | Draws a button that empties the value with reason "clear" and returns focus to the input. The button is withdrawn while the value is empty, disabled or read-only. |
+| `revealable` | `boolean` | false | slTextField | Draws a toggle that shows a password as characters. It appears only on type="password" and is withdrawn while the input is disabled. |
+| `revealed` | `boolean` | — | slTextFieldInput | Makes the password toggle controlled. defaultRevealed sets the uncontrolled starting state. |
+| `showCount` | `boolean` | false | slTextFieldInput | Publishes the length of the value to the field around it, which draws the count at the end of its label row. |
+| `countMax` | `number` | maxlength | slTextFieldInput | The limit the count is measured against. Without maxlength it is a soft limit: the value can pass it, and the count turns to the danger tone before validation runs. |
+| `start` | `slTextFieldStart` | — | any element | Content before the value in the reading direction, on your own element, which keeps its own semantics. |
+| `end` | `slTextFieldEnd` | — | any element | Content after the value in the reading direction. |
+| `disabled` | `boolean` | from the field, or false | slTextFieldInput | Unset by default, so the input takes the state of the field around it and of a disabled form control. When set, it wins, and it is the native attribute. |
+| `readOnly` | `boolean` | from the field, or false | slTextFieldInput | Unset by default, so the input takes the state of the field around it. It is the native readonly: the input stays focusable and selectable, and its value is submitted. A static readonly attribute you write is read before the binding computes. |
+| `invalid` | `boolean` | from the field, or false | slTextFieldInput | Unset by default, so the input takes the state of the field around it. It sets aria-invalid on the input and data-invalid on the frame. |
+| `required` | `boolean` | — | the input element | The input’s own attribute; slTextFieldInput never writes it. A field marks a required value with aria-required instead, because the native attribute turns on browser constraint validation. |
+| `type` | `'text' \| 'search' \| 'email' \| 'url' \| 'tel' \| 'password'` | text | the input element | The input’s own type, written as a static attribute. It is read before the host binding computes, so the reveal toggle can swap it and restore what you wrote. |
+| `copyable` | `boolean` | false | slTextField | Draws a button that writes the value to the clipboard, shows a check for two seconds and announces the outcome. It is hidden while the value is empty or the input is disabled. |
+| `loading` | `boolean` | false | slTextField | Draws the shared spinner before the buttons and sets aria-busy on the input; the value stays editable. Once loading is bound, false included, the spinner keeps its place so it can leave with a transition. |
+| `messages` | `Partial<TextFieldMessages>` | — | slTextField | Replaces words of the active language, key by key. clear, reveal and copy name the buttons; reveal does not change with the state, because aria-pressed carries it. copied and copyFailed announce the outcome of a copy. capsLock is announced once when Caps Lock turns on in a focused password field. |
+| `button[slTextFieldAction]` | `directive` | type="button" | inside slTextFieldStart or slTextFieldEnd | A button you place inside the frame. slMenuTriggerFor, slTooltipTrigger or a popover trigger can sit on the same element. The part attribute is written back after the first render, because slMenuTriggerFor binds data-part to null. Its exportAs is slTextFieldAction. |
+| `the directives themselves` | `slTextField, slTextFieldInput, slTextFieldStart, slTextFieldEnd` | — | your own elements | Every part except the buttons and marks the frame renders is a directive on an element you write, so each keeps its own semantics, attributes and listeners. |
+| `exportAs` | `'slTextField' / 'slTextFieldInput'` | — | a template | Reaches the instance from a template. inputElement on slTextFieldInput is the native input, with focus(), select() and setSelectionRange(). |
+| `provideTextFieldDefaults()` | `{ size, variant, mono }` | — | an injector | Sets size, variant and mono once for every text field in the injector. A field outranks it for size, so a text field inside a field takes the field’s size. |
+| `ControlValueAccessor` | `formControl, formControlName, ngModel` | — | slTextFieldInput | slTextFieldInput works with reactive and template-driven forms as it is. It provides no validator: the form owns validity. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `(valueChange)` | `ChangeRequest<string>` | Emitted by slTextFieldInput before the value changes. The request carries the new value, the value it replaces, the reason ("keyboard" for an edit in the input, "clear" for the clear button), the originating event, and cancel(), which refuses the change before it commits. |
+| `(revealedChange)` | `ChangeRequest<boolean>` | Emitted by slTextFieldInput before the password toggle changes, with reason "pointer" or "keyboard" read from the click. A form that hides the password again on blur binds [revealed] and listens here. |
+| `(valueCopy)` | `TextFieldCopyDetail — { copied, reason, source, value }` | Emitted by slTextField after the copy button has asked the clipboard. copied is false when the clipboard refused the value, and reason is "pointer" or "keyboard". |
+| `ControlValueAccessor` | `the form’s own value and touched state` | The form receives the value whenever it changes and the request was not cancelled, and the touched state on blur. There is no [(value)], because a two-way binding carries only the value, neither the reason nor cancel(). |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `variant` | `outline`, `subtle`, `plain` | `outline` |
+
+## Rules
+
+- There is no WAI-ARIA Authoring Practices pattern for a text field: the APG lists thirty patterns, and none of them is a single-line text input. The sources are the HTML specification for the input element, the APG practice Providing Accessible Names and Descriptions (w3.org/WAI/ARIA/apg/practices/names-and-descriptions/) for its name, and the ARIA textbox role for what may sit inside it.
+- The frame has no role. WAI-ARIA requires the children of a textbox to be non-interactive and presentational, so the clear and reveal buttons are siblings of the input inside a box that announces nothing.
+- The input takes its name from the field’s label, whose for attribute points at the identifier the field generates. The APG naming practice records that some combinations of browser and assistive technology compute no name from a label that wraps its control.
+- Inside a required field the input carries aria-required, never the native required. In Angular a host binding overrides a static attribute, so every attribute you write that slTextFieldInput also binds (id, aria-describedby, aria-invalid, aria-required, readonly and type) is read before the binding computes and is never overwritten.
+- The clear and reveal buttons are native buttons with names you translate once through messages. Each is at least 24 CSS pixels wide at every size and density, which meets WCAG 2.2 success criterion 2.5.8. The reveal button keeps one name and carries its state in aria-pressed, which is the APG rule for a toggle button.
+- The copy button announces its outcome through the shared live announcer, Copied or Copy failed, because the check that replaces the copy mark is only visible. The Caps Lock mark is hidden from assistive technology; its message is announced once when Caps Lock turns on while the password field has focus.
+- loading sets aria-busy on the input and leaves it enabled, so the keyboard stays on the input while an asynchronous check runs. The spinner is hidden from assistive technology.
+- A menu inside the frame follows the APG menu button pattern (w3.org/WAI/ARIA/apg/patterns/menu-button/). slMenuTriggerFor on the action supplies aria-haspopup, aria-expanded, and Enter, Space and ArrowDown to open.
+- No key is bound to Escape. Some browsers clear a search input on Escape, and a text field that consumed the key inside a dialog would leave a keyboard user unable to close the dialog. WCAG success criterion 2.1.4 addresses the defects that single-key shortcuts cause.
+
+## 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-inner-size-lg`, `--slotted-control-inner-size-md`, `--slotted-control-inner-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-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-family-mono`, `--slotted-font-weight-medium`, `--slotted-radius-none`, `--slotted-radius-xs`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-surface-sunken`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-field-action-active-background`, `--slotted-text-field-action-color`, `--slotted-text-field-action-hover-background`, `--slotted-text-field-action-label-color`, `--slotted-text-field-action-size`, `--slotted-text-field-adornment-color`, `--slotted-text-field-autofill-background`, `--slotted-text-field-background`, `--slotted-text-field-border-color`, `--slotted-text-field-caps-lock-color`, `--slotted-text-field-color`, `--slotted-text-field-copy-complete-color`, `--slotted-text-field-disabled-background`, `--slotted-text-field-disabled-border-color`, `--slotted-text-field-disabled-color`, `--slotted-text-field-hover-border-color`, `--slotted-text-field-icon-size-min`, `--slotted-text-field-invalid-border-color`, `--slotted-text-field-invalid-edge-width`, `--slotted-text-field-invalid-focus-ring-color`, `--slotted-text-field-placeholder-color`, `--slotted-text-field-plain-hover-background`, `--slotted-text-field-radius`, `--slotted-text-field-readonly-background`, `--slotted-text-field-shadow`, `--slotted-text-field-subtle-background`, `--slotted-text-field-subtle-border-color`, `--slotted-text-field-subtle-hover-background`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-surface`, `--slotted-tone-danger-border`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`, `--slotted-tone-success-text`, `--slotted-tone-warning-text`
+
+## Examples
+
+See [text-field.examples.md](./text-field.examples.md).