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

package/docs/tags-input.md

@@ -0,0 +1,361 @@
+<!-- index: ./index.md -->
+# tags-input
+
+`data-ui="tags-input"` · Text input that collects values as tags.
+
+## Import
+
+```ts
+import { SlTagsInput, provideTagsInputDefaults } from '@slotted/angular/tags-input';
+```
+
+Selector: `sl-tags-input` · exportAs: `slTagsInput`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<sl-tags-input
+  aria-label="To"
+  type="email"
+  placeholder="Add a recipient"
+  [defaultValue]="['ana.pereira@example.com']"
+/>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | sl-tags-input, the host element itself | yes |
+| `control` | div with role="grid" | yes |
+| `chips` | div with role="row" | yes |
+| `field` | span with role="gridcell" | yes |
+| `input` | input, with no role | yes |
+| `message` | span, visually hidden | no |
+| `counter` | span | no |
+| `clear` | button | no |
+| `hint` | span, visually hidden | yes |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `readonly string[]` | — | sl-tags-input | The values, in the order the reader gave them. A model, so [(value)] binds both ways. |
+| `defaultValue` | `readonly string[]` | — | sl-tags-input | The list an unbound control starts from, read once in ngOnInit. |
+| `inputValue` | `string` | — | sl-tags-input | The characters in the field. A model; it is emptied whenever a value is committed. |
+| `type` | `'text' \| 'email' \| 'url' \| 'tel' \| 'search'` | text | sl-tags-input | The input’s own type, and — with no validator — the grammar each value is judged against. |
+| `validateValue` | `(text: string) => boolean \| string` | — | sl-tags-input | Whether a text may be a value: true, false with the generic label, or a string saying why not. Absent, type, pattern, minLength and maxLength judge. Named validateValue because validate is the Validator’s own method. |
+| `invalidValues` | `'keep' \| 'refuse'` | keep | sl-tags-input | What becomes of a value that fails: a chip in the danger tone with its reason, or a report through valueRefuse. |
+| `normalize` | `(text: string) => string` | — | sl-tags-input | Runs before a value is judged. Trim by default. |
+| `split` | `(text: string) => readonly string[]` | — | sl-tags-input | How a paste is split. The default splits on the delimiters and on every line break. |
+| `formatLabel` | `(value: string) => string` | — | sl-tags-input | The chip’s text for a value. |
+| `lockedValues` | `readonly string[]` | — | sl-tags-input | The values the reader may not remove. |
+| `pattern` | `string` | — | sl-tags-input | The input’s own pattern, applied to each value. |
+| `minLength` | `number` | — | sl-tags-input | The input’s own minlength, applied to each value. |
+| `maxLength` | `number` | — | sl-tags-input | The input’s own maxlength, applied to each value. |
+| `list` | `string` | — | sl-tags-input | The id of a datalist, for the browser’s own completion. |
+| `placeholder` | `string` | — | sl-tags-input | The input’s placeholder. |
+| `name` | `string` | — | sl-tags-input | The name every hidden input carries, one per value. |
+| `form` | `string` | — | sl-tags-input | The form the hidden inputs belong to, when it is not an ancestor. |
+| `locale` | `string` | — | sl-tags-input | BCP 47, for the comparison the duplicate rule makes. The language in force when absent. |
+| `max` | `number \| null` | null | sl-tags-input | The most values the list may hold. |
+| `delimiters` | `readonly string[]` | , | sl-tags-input | The characters that commit the typed text and split a paste. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | sl-tags-input | The type step, and the frame’s height when empty. |
+| `variant` | `'outline' \| 'subtle' \| 'plain'` | outline | sl-tags-input | An edge, a ground, or neither. |
+| `overflow` | `'wrap' \| 'collapse'` | wrap | sl-tags-input | Whether the row wraps to three lines and scrolls, or stays one line and opens while focus is inside. |
+| `pendingOnBlur` | `'commit' \| 'keep' \| 'discard'` | commit | sl-tags-input | What leaving the control does with the text in the field. |
+| `editable` | `boolean` | false | sl-tags-input | Whether Enter or a double click on a chip opens it for editing. |
+| `reorderable` | `boolean` | false | sl-tags-input | Whether Alt with an arrow moves the focused chip. |
+| `allowDuplicates` | `boolean` | false | sl-tags-input | Whether the same value may stand twice. |
+| `addOnPaste` | `boolean` | true | sl-tags-input | Whether a paste with several values becomes several chips. |
+| `clearable` | `boolean` | true | sl-tags-input | Whether the clear button is drawn while the control holds something. |
+| `fullWidth` | `boolean` | true | sl-tags-input | Whether the frame fills its container. |
+| `disabled` | `boolean` | false | sl-tags-input | Unstated, the control asks the form and the field around it. |
+| `readOnly` | `boolean` | false | sl-tags-input | Whether the values may be read and copied but not changed. |
+| `required` | `boolean` | false | sl-tags-input | Whether an empty list is a validity error. |
+| `invalid` | `boolean` | false | sl-tags-input | Whether the control is drawn in error, in addition to any value that failed. |
+| `messages` | `Partial<TagsInputMessages>` | — | sl-tags-input | Words laid over the language in force, key by key: added, addedInvalid, clear, copied, count, countNamed, counter, duplicate, editHint, hint, invalid, remove, removed, reorder |
+| `provideTagsInputDefaults` | `(defaults: Partial<TagsInputDefaults>) => Provider` | — | application | Sets every axis once, at bootstrap or on a route; the words come from the language in force (provideSlotted). A binding on a control wins over it. |
+| `exportAs` | `slTagsInput` | — | sl-tags-input | The instance, for a template that needs focus(), clear(), setValue(), admit(), remove() or move(). |
+| `ControlValueAccessor` | `NG_VALUE_ACCESSOR` | — | sl-tags-input | formControl, formControlName and ngModel all move the whole list, and the form’s disabled state reaches the control. |
+| `Validator` | `NG_VALIDATORS` | — | sl-tags-input | required, tooMany, invalidValues — the values that failed, by name — and duplicate reach a Reactive Form without the consumer writing a validator. React answers with the platform’s setCustomValidity instead, and the asymmetry is recorded rather than levelled away. |
+| `slField` | `directive` | — | sl-tags-input | A control inside a field takes its id, its description, its error and its states from the field without being wrapped. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `valueChange` | `readonly string[]` | The list moved, as the two-way half of [(value)]. |
+| `valueChangeRequest` | `ChangeRequest<readonly string[]>` | The same move, with the reason on it: submit from typed text, a paste, a blur or an edit; remove from one value leaving; clear from all of them; keyboard from a reorder; programmatic from a method. |
+| `inputValueChange` | `string` | The text in the field moved, as the two-way half of [(inputValue)]. |
+| `inputValueChangeRequest` | `ChangeRequest<string>` | The same move, with the reason on it: keyboard, submit, clear, blur or programmatic. |
+| `valueRefuse` | `{ values: readonly string[]; cause: "duplicate" \| "limit" \| "invalid" }` | One or more values did not get in. It holds no state and cancels nothing. invalid arrives only under invalidValues="refuse". |
+| `valueCopy` | `{ values: readonly string[]; outcome: 'api' \| 'command' \| 'refused' }` | The reader copied a chip or the whole list with the keyboard, and the text either reached the clipboard or was refused. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `variant` | `outline`, `subtle`, `plain` | `outline` |
+| `overflow` | `wrap`, `collapse` | `wrap` |
+| `invalidValues` | `keep`, `refuse` | `keep` |
+| `pendingOnBlur` | `commit`, `keep`, `discard` | `commit` |
+| `editable` | `true`, `false` | `false` |
+| `reorderable` | `true`, `false` | `false` |
+| `allowDuplicates` | `true`, `false` | `false` |
+| `addOnPaste` | `true`, `false` | `true` |
+| `clearable` | `true`, `false` | `true` |
+| `fullWidth` | `true`, `false` | `true` |
+| `disabled` | `true`, `false` | `false` |
+| `readOnly` | `true`, `false` | `false` |
+| `required` | `true`, `false` | `false` |
+| `invalid` | `true`, `false` | `false` |
+
+## Rules
+
+- The control is a layout grid with one row: the chips are cells and the field is the last cell, so one Tab reaches the input and the arrows walk the row. The input carries no role, because it opens nothing.
+- Focus is set on a chip cell rather than on the remove button inside it, which is tabindex="-1"; Delete and Backspace do what the button does, and the row’s hint says so. Angular Material’s own chip grid resolves the grid pattern’s text-plus-widget cell the same way.
+- An invalid value is said three ways — the danger tone, the alert mark, and a description carrying the reason — because colour alone is not a message. The same reason is the input’s custom validity and the Validator’s invalidValues error, so a native form and a Reactive Form both refuse it.
+- Every change is announced once, politely: a value added with the count now held and its reason if it failed, a value removed with the count that is left, a move with its new position, a duplicate with the chip that holds it, and a copy with the count copied.
+- After a removal focus goes to the chip that took the removed one’s index, then the previous one, then the input — it is never lost to the document body.
+
+## 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-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-line-height-sm`, `--slotted-radius-none`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-surface-sunken`, `--slotted-tags-input-action-active-background`, `--slotted-tags-input-action-color`, `--slotted-tags-input-action-hover-background`, `--slotted-tags-input-action-size`, `--slotted-tags-input-autofill-background`, `--slotted-tags-input-background`, `--slotted-tags-input-border-color`, `--slotted-tags-input-color`, `--slotted-tags-input-counter-color`, `--slotted-tags-input-counter-complete-color`, `--slotted-tags-input-current-border-color`, `--slotted-tags-input-disabled-background`, `--slotted-tags-input-disabled-border-color`, `--slotted-tags-input-disabled-color`, `--slotted-tags-input-field-basis`, `--slotted-tags-input-field-min`, `--slotted-tags-input-hover-border-color`, `--slotted-tags-input-icon-size-min`, `--slotted-tags-input-invalid-border-color`, `--slotted-tags-input-invalid-edge-width`, `--slotted-tags-input-invalid-focus-ring-color`, `--slotted-tags-input-placeholder-color`, `--slotted-tags-input-plain-hover-background`, `--slotted-tags-input-radius`, `--slotted-tags-input-readonly-background`, `--slotted-tags-input-shadow`, `--slotted-tags-input-subtle-background`, `--slotted-tags-input-subtle-border-color`, `--slotted-tags-input-subtle-hover-background`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-border`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-secondary-subtle-active`, `--slotted-tone-secondary-subtle-hover`
+
+## Examples
+
+### The recipients of a message
+
+The value is a list of texts and the text is the label. formatLabel draws the chip from the address — a name where the value is an address — and the value a form receives stays the address.
+
+Excerpt — not a complete module
+
+```html
+<sl-tags-input aria-label="To" type="email" [(value)]="to" [formatLabel]="nameFor" />
+```
+
+### A value that fails is held, not dropped
+
+jhon.company stays where the reader can see it: the chip takes the danger tone and the alert mark, its reason is its description and its title, the frame is invalid, and a native submit is refused with the browser’s bubble on the control. Under invalidValues="refuse" the same value is reported instead.
+
+Excerpt — not a complete module
+
+```html
+<sl-tags-input aria-label="To" [validateValue]="hasAtSign" />
+
+<sl-tags-input
+  aria-label="SKUs"
+  invalidValues="refuse"
+  [validateValue]="isSku"
+  (valueRefuse)="report($event.cause, $event.values)"
+/>
+```
+
+### The browser validates, in the reader’s language
+
+With no validator given, type="email" and pattern judge each value the way the platform judges a single one, and the chip’s reason is the browser’s own validationMessage — already translated, and already the sentence the reader has seen on every other form.
+
+Excerpt — not a complete module
+
+```html
+<sl-tags-input aria-label="To" type="email" />
+
+<sl-tags-input aria-label="Order numbers" pattern="ORD-\d{6}" />
+```
+
+### A limit that is counted, and refused past it
+
+The counter is drawn only because max is set, takes the accent once the list is full, and the root carries data-complete. What arrives past the limit is reported with the values rather than dropped — a paste of six into a list of three says which three did not fit.
+
+Excerpt — not a complete module
+
+```html
+<sl-tags-input aria-label="Reviewers" [max]="3" (valueRefuse)="onRefuse($event)" />
+```
+
+### Duplicates
+
+The comparison is locale-sensitive, so typing the first address in capitals finds it already held; focus goes to that chip and its edge takes the accent for one long step, rather than nothing happening. allowDuplicates lets the same value stand twice.
+
+Excerpt — not a complete module
+
+```html
+<sl-tags-input aria-label="To" locale="pt-BR" />
+
+<sl-tags-input aria-label="Line items" allowDuplicates />
+```
+
+### Pasting many values at once
+
+A paste splits on the delimiters and on every line break — a column copied out of a spreadsheet arrives one value per line. split replaces the rule for a clipboard the family cannot guess, such as addresses with quoted names in them.
+
+Excerpt — not a complete module
+
+```html
+<sl-tags-input aria-label="Cc" type="email" [delimiters]="[',', ';']" />
+
+<sl-tags-input aria-label="To" type="email" [split]="addressesIn" />
+```
+
+### What leaving does with the pending text
+
+Three answers, one word each: commit turns the text into a value, keep leaves it in the box, discard empties it. A recipients field commits; a filter operand keeps; a chat box discards.
+
+Excerpt — not a complete module
+
+```html
+<sl-tags-input aria-label="To" pendingOnBlur="commit" />
+<sl-tags-input aria-label="Filter" pendingOnBlur="keep" />
+<sl-tags-input aria-label="Tags" pendingOnBlur="discard" />
+```
+
+### Editing a chip in place
+
+Enter on a chip — or a double click — turns its cell into a text field holding the value. Enter commits, Escape reverts, and the edit is judged like any other value: an edit into an address already held is refused and the chip that holds it takes focus.
+
+Excerpt — not a complete module
+
+```html
+<sl-tags-input aria-label="To" type="email" editable />
+```
+
+### Reorder, by keyboard first
+
+Alt with an arrow moves the focused chip one place along the row, following the writing direction; Alt+Home and Alt+End move it to either end. The request carries keyboard and nothing else, so a consumer persisting an order listens for exactly that.
+
+Excerpt — not a complete module
+
+```html
+<sl-tags-input
+  aria-label="Approvers, in order"
+  reorderable
+  (valueChangeRequest)="$event.reason === 'keyboard' && saveOrder($event.value)"
+/>
+```
+
+### A value the reader may not remove
+
+lockedValues keeps a mandatory recipient in the list: its chip carries data-disabled, draws no remove control, is skipped by Backspace and by the clear button, and is still reachable by arrow — because the reader still has to be able to read it.
+
+Excerpt — not a complete module
+
+```html
+<sl-tags-input
+  aria-label="Cc"
+  [defaultValue]="['support@example.com', 'ana.pereira@example.com']"
+  [lockedValues]="['support@example.com']"
+/>
+```
+
+### The list on the clipboard
+
+Ctrl+C on a chip copies its value; Ctrl+X copies it and removes it. Ctrl+C on the empty field copies the whole list, joined by the first delimiter and a space — the shape a paste into another instance of this family reads back.
+
+Excerpt — not a complete module
+
+```html
+<sl-tags-input aria-label="Cc" (valueCopy)="onCopy($event.values, $event.outcome)" />
+```
+
+### Overflow, and access to the whole list
+
+wrap grows the frame by whole rows to three and scrolls past them, and nothing leaves the DOM. collapse keeps one line and a +N at rest — for a filter bar or a table cell — and shows every chip while focus is inside the control, because there is no popup to hold them and no need for one.
+
+Excerpt — not a complete module
+
+```html
+<sl-tags-input aria-label="Cc" overflow="wrap" />
+<sl-tags-input aria-label="Cc" overflow="collapse" />
+```
+
+### Sizes
+
+The frame takes the control height of its step, so an empty control is exactly the height of a text field beside it; the chips keep the small step at every size, because a chip is a chip and not a control.
+
+Excerpt — not a complete module
+
+```html
+<sl-tags-input aria-label="To" size="sm" />
+<sl-tags-input aria-label="To" size="md" />
+<sl-tags-input aria-label="To" size="lg" />
+```
+
+### Variants
+
+outline for a form, subtle for a panel that already has a ground, and plain for a table cell — where an edge and a resting shadow would draw a cell that is not there.
+
+Excerpt — not a complete module
+
+```html
+<sl-tags-input aria-label="To" variant="outline" />
+<sl-tags-input aria-label="To" variant="subtle" />
+<sl-tags-input aria-label="To" variant="plain" />
+```
+
+### States
+
+disabled answers nothing and keeps its values legible; readOnly keeps the caret, the copy and the chips at full ink, and withholds every remove control; invalid retints the border and the focus ring together; required is the platform’s own, written on the input only while the list is empty.
+
+Excerpt — not a complete module
+
+```html
+<sl-tags-input aria-label="To" disabled />
+<sl-tags-input aria-label="To" readOnly />
+<sl-tags-input aria-label="To" invalid required />
+```
+
+### Content the family did not choose
+
+A sixty-character address truncates inside its chip and stays whole in the accessibility tree; the row wraps rather than pushing the frame wider; and under 120 pixels there is no chip at all and the counter answers instead.
+
+Excerpt — not a complete module
+
+```html
+<sl-tags-input
+  aria-label="To"
+  [defaultValue]="['quality-assurance-and-release-management@subsidiary.example.com']"
+/>
+```
+
+### The keyboard
+
+Tab reaches the field once. Backspace from an empty field moves to the last chip and removes nothing; a second press removes it. Delete takes the focused chip out, the arrows walk the row and mirror under rtl, Escape clears the text and never the list, and a printable character sends the reader back to the field.
+
+Excerpt — not a complete module
+
+```html
+<sl-tags-input aria-label="To" editable reorderable [defaultValue]="['ana.pereira@example.com']" />
+```
+
+### In a form
+
+One hidden input per value under the name to, a ControlValueAccessor, and a Validator beside it — so a Reactive Form sees required, tooMany and the values that failed by name, and a plain form is refused by the input’s own custom validity.
+
+Excerpt — not a complete module
+
+```html
+<div slField [invalid]="to.invalid">
+  <label slFieldLabel>To</label>
+  <sl-tags-input name="to" type="email" required [formControl]="to" />
+  <span slFieldError>Name at least one recipient</span>
+</div>
+```
+
+### Composition, and the defaults an application sets once
+
+An injection token carries the axes, provideSlotted the language, exportAs reaches the instance from the template, and list passes through to a datalist for the browser’s own completion.
+
+Excerpt — not a complete module
+
+```html
+<sl-tags-input #to="slTagsInput" aria-label="To" list="contacts" type="email" />
+<datalist id="contacts">
+  <option value="ana.pereira@example.com"></option>
+</datalist>
+
+<button type="button" (click)="to.setValue(team, 'programmatic')">Add the whole team</button>
+```