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

package/docs/multi-select.md

@@ -0,0 +1,213 @@
+<!-- index: ./index.md -->
+# multi-select
+
+`data-ui="multi-select"` · Picks several options shown as tags.
+
+## Import
+
+```ts
+import { SlMultiSelect, SlMultiSelectGroup, SlMultiSelectItem, SlMultiSelectSeparator } from '@slotted/angular/multi-select';
+```
+
+Selector: `sl-multi-select, sl-multi-select-group, sl-multi-select-item, sl-multi-select-separator` · exportAs: `slMultiSelect, slMultiSelectGroup, slMultiSelectItem, slMultiSelectSeparator`
+
+## Minimal example
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlMultiSelect, SlMultiSelectItem } from '@slotted/angular/multi-select';
+
+const WAREHOUSES = [
+  { value: 'RNO', label: 'Reno, NV' },
+  { value: 'CMH', label: 'Columbus, OH' },
+  { value: 'SAV', label: 'Savannah, GA' },
+  { value: 'DFW', label: 'Dallas, TX' },
+  { value: 'ONT', label: 'Ontario, CA' },
+  { value: 'ABE', label: 'Allentown, PA' },
+];
+
+@Component({
+  selector: 'app-multi-select-basic',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlMultiSelect, SlMultiSelectItem],
+  template: `
+    <div slField>
+      <label slFieldLabel>Stocking warehouses</label>
+      <sl-multi-select placeholder="Add a warehouse">
+        @for (warehouse of warehouses; track warehouse.value) {
+          <sl-multi-select-item [value]="warehouse.value" [label]="warehouse.label" />
+        }
+      </sl-multi-select>
+      <span slFieldDescription>Chai tea, 24 bags is reordered at each of these warehouses.</span>
+    </div>
+  `,
+})
+export class MultiSelectBasic {
+  protected readonly warehouses = WAREHOUSES;
+}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | sl-multi-select, 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 role="combobox" | yes |
+| `counter` | span | no |
+| `busy` | span | no |
+| `clear` | button | no |
+| `trigger` | button | yes |
+| `arrow` | span | yes |
+| `positioner` | div, rendered by the layer template | yes |
+| `content` | div with role="listbox" and aria-multiselectable | yes |
+| `chosen` | div | no |
+| `group` | div with role="group" | no |
+| `group-label` | div | no |
+| `item` | div with role="option" | yes |
+| `indicator` | span | yes |
+| `icon` | span | no |
+| `label` | span | yes |
+| `match` | mark, the match part of the highlight component, inside label | no |
+| `description` | span | no |
+| `separator` | div with role="separator" | no |
+| `empty` | div | no |
+| `status` | div with role="status" | yes |
+| `placeholder` | div holding skeleton rows | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `value` | `readonly string[]` | — | sl-multi-select | The chosen values, in the order the reader chose them. A model, so [(value)] binds both ways. |
+| `defaultValue` | `readonly string[]` | — | sl-multi-select | The values an unbound multi-select starts with, read once in ngOnInit. |
+| `inputValue` | `string` | — | sl-multi-select | The text in the input. It is emptied whenever a value is committed. A model. |
+| `open` | `boolean` | — | sl-multi-select | Whether the list is open. A model. |
+| `highlightedValue` | `string \| null` | — | sl-multi-select | The option the highlight is on, which is not a chosen option. A model. |
+| `aria-label` | `string` | — | sl-multi-select | Names the input and the list, for a multi-select outside a field. |
+| `placeholder` | `string` | — | sl-multi-select | The text the input shows while no value is chosen. |
+| `items` | `MultiSelectItems` | — | sl-multi-select | Values and labels declared up front, so a tag shows its label before the list has rendered its options. |
+| `filter` | `MultiSelectFilter` | — | sl-multi-select | Compares an option label with the query. When absent, the comparison is a locale-sensitive "contains" that ignores case and accents; null turns filtering off for options a server has already filtered. |
+| `locale` | `string` | — | sl-multi-select | The BCP 47 language of the filter and of the duplicate comparison. When absent, the language in force. |
+| `validateValue` | `(text, values) => boolean` | — | sl-multi-select | Whether typed text may become a value. Text it turns down is reported through (valueRefuse) with the cause invalid. |
+| `name` | `string` | — | sl-multi-select | The submission name. One hidden input per value carries it. |
+| `form` | `string` | — | sl-multi-select | The id of the form the hidden inputs belong to, for a multi-select rendered outside it. |
+| `total` | `number` | — | sl-multi-select | The number of options in the whole collection, for aria-setsize on a windowed list. |
+| `max` | `number \| null` | null | sl-multi-select | The most values the set may hold; null means no limit. At the limit, every option not yet chosen is announced as unavailable. Past it, the validator reports tooMany. |
+| `delimiters` | `readonly string[]` | , | sl-multi-select | The characters that commit the typed text and split a paste. One list serves both. |
+| `creatable` | `boolean` | false | sl-multi-select | Whether typed text may become a value. |
+| `editable` | `boolean` | false | sl-multi-select | Whether Enter on a focused tag turns it into a text field. |
+| `reorderable` | `boolean` | false | sl-multi-select | Whether Alt with ArrowLeft, ArrowRight, Home or End moves the focused tag along the row. |
+| `allowDuplicates` | `boolean` | false | sl-multi-select | Whether the same value may be held twice. |
+| `addOnPaste` | `boolean` | true | sl-multi-select | Whether a paste that contains delimiters becomes several values. |
+| `commitOnBlur` | `boolean` | true | sl-multi-select | Whether typed text is committed when focus leaves the control. |
+| `overflow` | `'wrap' \| 'collapse'` | wrap | sl-multi-select | What the control does with more tags than fit: wrap grows by rows up to three, then scrolls; collapse keeps one row and counts the rest in a +N tag. |
+| `chosenOptions` | `'show' \| 'hide'` | show | sl-multi-select | Whether a chosen option stays in the list with a check, or leaves it. |
+| `clearable` | `boolean` | true | sl-multi-select | Whether the clear button is drawn while the control holds a value or typed text. |
+| `closeOnSelect` | `boolean` | false | sl-multi-select | Whether choosing an option closes the list. Off by default, because a set is built with several choices. |
+| `closeOnEscape` | `boolean` | true | sl-multi-select | Whether Escape closes the list. |
+| `closeOnOutsidePress` | `boolean` | true | sl-multi-select | Whether a press outside the list closes it. |
+| `loop` | `boolean` | false | sl-multi-select | Whether the highlight wraps from the last option to the first, and back. |
+| `highlightMatch` | `boolean` | true | sl-multi-select | Whether the span the query matched is marked. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | sl-multi-select | The step of the control scale. Inside a field, an unset size follows the field. |
+| `variant` | `'outline' \| 'subtle' \| 'plain'` | outline | sl-multi-select | The frame: outline draws an edge, subtle a filled ground, plain neither until hover or focus. |
+| `side` | `'bottom' \| 'top' \| 'inline-start' \| 'inline-end' \| 'left' \| 'right'` | bottom | sl-multi-select | The side of the control the list opens on. |
+| `align` | `'start' \| 'center' \| 'end'` | start | sl-multi-select | How the list aligns along that side. |
+| `width` | `'anchor' \| 'content'` | content | sl-multi-select | content keeps the list at least as wide as the control and widens it to its longest option; anchor pins it to the width of the control. |
+| `mount` | `'active' \| 'lazy' \| 'eager'` | active | sl-multi-select | When the list exists in the DOM: only while open (active), from the first open on (lazy), or from the start (eager). |
+| `strategy` | `'absolute' \| 'fixed'` | absolute | sl-multi-select | The CSS position the list uses. |
+| `openOn` | `'input' \| 'focus' \| 'manual'` | input | sl-multi-select | Which gestures open the list besides the trigger and the arrow keys: typing or a press on the input (input), also any focus on the input (focus), or none, so typing filters without opening (manual). |
+| `sideOffset` | `number` | 4 | sl-multi-select | The distance in pixels between the control and the list. |
+| `alignOffset` | `number` | 0 | sl-multi-select | The shift in pixels along the aligned edge. |
+| `collisionPadding` | `number` | 8 | sl-multi-select | How close in pixels the list may come to the edge of the viewport before it moves. |
+| `flip` | `boolean` | true | sl-multi-select | Whether the list moves to the opposite side when it does not fit. |
+| `shift` | `boolean` | true | sl-multi-select | Whether the list slides along its side to stay in view. |
+| `hideWhenDetached` | `boolean` | true | sl-multi-select | Whether the list hides when the control scrolls out of its clipping container. |
+| `portal` | `boolean` | true | sl-multi-select | Whether the list is portalled to the end of the document. |
+| `fullWidth` | `boolean` | true | sl-multi-select | Whether the control fills the width of its container. |
+| `disabled` | `boolean` | false | sl-multi-select | Whether the control is disabled: it takes no input, draws no remove buttons and leaves the tab order. |
+| `readOnly` | `boolean` | false | sl-multi-select | Whether the values can be read and copied but not changed. The input stays focusable; the list, the remove buttons and the clear button are withheld. |
+| `required` | `boolean` | false | sl-multi-select | Whether an empty set is invalid. |
+| `invalid` | `boolean` | false | sl-multi-select | Whether the control is drawn in the error state, with aria-invalid on the input. |
+| `loading` | `boolean` | false | sl-multi-select | Whether options are on their way: the spinner replaces the chevron and the list shows placeholder rows. |
+| `messages` | `Partial<MultiSelectMessages>` | — | sl-multi-select | Replaces any of the phrases the multi-select writes: clear, trigger, chosen ({count}), count ({count}), counter ({count}, {max}), create ({query}), empty, loading, remove ({label}) and reorder ({label}, {position}, {count}). Phrases left out come from the language in force. |
+| `value` | `string` | — | sl-multi-select-item | The key of the option, which is what enters the set. |
+| `label` | `string` | — | sl-multi-select-item | What the reader sees, what the filter compares and what the mark splits. It is an input rather than projected content, because the filter needs the text before the option renders. |
+| `disabled` | `boolean` | false | sl-multi-select-item | Whether the option can be chosen. |
+| `description` | `string` | — | sl-multi-select-item | A second line under the label. |
+| `icon` | `GlyphName` | — | sl-multi-select-item | The name of the glyph drawn in the first column of the option, as a Glyph inside an Icon box. |
+| `position` | `number` | — | sl-multi-select-item | The place of the option in a windowed collection, for aria-posinset. |
+| `label` | `string` | — | sl-multi-select-group | The name of the group. |
+| `provideMultiSelectDefaults()` | `Provider` | — | Application | Sets any axis once for every multi-select below it, in a bootstrap, a route or a component. The words come from the language in force, set by provideSlotted. A binding written on one multi-select still wins. |
+| `exportAs` | `slMultiSelect` | — | sl-multi-select | The instance, for a template that calls focus(), setOpen(), admit(), remove(), move(), clear() or scrollToKey(). |
+| `ControlValueAccessor` | `NG_VALUE_ACCESSOR` | — | sl-multi-select | formControl, formControlName and ngModel bind the whole set, and the disabled state of the form reaches the control. |
+| `Validator` | `NG_VALIDATORS` | — | sl-multi-select | Reports required, tooMany and duplicate to a reactive form, with no validator to write. The React binding has no equivalent. |
+| `ng-content` | `projection` | — | sl-multi-select | Options, groups and separators are your content, so your own control flow decides what the list holds. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `valueChange` | `readonly string[]` | The set changed. It is the two-way half of [(value)]. |
+| `valueChangeRequest` | `ChangeRequest<readonly string[]>` | The same change, with its reason: select for an option, submit for typed text, remove for one value, clear for all of them, keyboard for a reorder, and programmatic for a method. |
+| `valueRefuse` | `{ values: readonly string[]; cause: "duplicate" \| "limit" \| "invalid" }` | Values were turned away, and cause says why. Nothing is held and nothing can be cancelled: the values never entered the set. |
+| `inputValueChange` | `string` | The typed text changed. It is the two-way half of [(inputValue)], and inputValueChangeRequest carries the reason. |
+| `openChange` | `boolean` | The list opened or closed. openChangeRequest carries the reason: pointer, keyboard, escape, outsidePress, select, dismiss, blur or programmatic. |
+| `highlightedValueChange` | `string \| null` | The highlight moved. Moving it chooses nothing, and highlightedValueChangeRequest carries the reason. |
+| `loadMore` | `void` | The last option scrolled into view, so the next page can be fetched. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `sm`, `md`, `lg` | `md` |
+| `variant` | `outline`, `subtle`, `plain` | `outline` |
+| `side` | `bottom`, `top`, `inline-start`, `inline-end`, `left`, `right` | `bottom` |
+| `align` | `start`, `center`, `end` | `start` |
+| `width` | `anchor`, `content` | `content` |
+| `mount` | `active`, `lazy`, `eager` | `active` |
+| `strategy` | `absolute`, `fixed` | `absolute` |
+| `openOn` | `input`, `focus`, `manual` | `input` |
+| `overflow` | `wrap`, `collapse` | `wrap` |
+| `chosenOptions` | `show`, `hide` | `show` |
+| `creatable` | `true`, `false` | `false` |
+| `editable` | `true`, `false` | `false` |
+| `reorderable` | `true`, `false` | `false` |
+| `allowDuplicates` | `true`, `false` | `false` |
+| `commitOnBlur` | `true`, `false` | `true` |
+| `addOnPaste` | `true`, `false` | `true` |
+| `clearable` | `true`, `false` | `true` |
+| `loop` | `true`, `false` | `false` |
+| `highlightMatch` | `true`, `false` | `true` |
+| `closeOnSelect` | `true`, `false` | `false` |
+| `closeOnEscape` | `true`, `false` | `true` |
+| `closeOnOutsidePress` | `true`, `false` | `true` |
+| `flip` | `true`, `false` | `true` |
+| `shift` | `true`, `false` | `true` |
+| `hideWhenDetached` | `true`, `false` | `true` |
+| `portal` | `true`, `false` | `true` |
+| `fullWidth` | `true`, `false` | `true` |
+| `disabled` | `true`, `false` | `false` |
+| `readOnly` | `true`, `false` | `false` |
+| `required` | `true`, `false` | `false` |
+| `invalid` | `true`, `false` | `false` |
+| `loading` | `true`, `false` | `false` |
+
+## Rules
+
+- The input is the tab stop of the control. The tags, their remove buttons and the trigger carry tabindex="-1", as the combobox and grid patterns ask; the clear button, while it is drawn, is in the tab order.
+- The tags are a layout grid with one row, which leaves ArrowDown and ArrowUp to the list. Focus lands on a tag rather than on its remove button, and Delete and Backspace do what the button does. The grid carries the number of chosen values as its name.
+- The list sets aria-multiselectable, and selection does not follow the highlight: moving through the options chooses nothing until Enter or a press. This departs from the note in the combobox pattern, as every implementation surveyed does.
+- Changes are announced as well as drawn: a value added with the count now held, a value removed with its label and the count left, a value moved with its new position, and the limit when it is reached. The status row announces how many options match the query.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--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-medium`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-color-invalid`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-sans`, `--slotted-font-size-xs`, `--slotted-font-weight-medium`, `--slotted-font-weight-semibold`, `--slotted-line-height-md`, `--slotted-line-height-sm`, `--slotted-multi-select-action-active-background`, `--slotted-multi-select-action-color`, `--slotted-multi-select-action-hover-background`, `--slotted-multi-select-action-size`, `--slotted-multi-select-arrow-color`, `--slotted-multi-select-autofill-background`, `--slotted-multi-select-background`, `--slotted-multi-select-border-color`, `--slotted-multi-select-color`, `--slotted-multi-select-content-border-color`, `--slotted-multi-select-content-padding-block`, `--slotted-multi-select-content-padding-inline`, `--slotted-multi-select-content-radius`, `--slotted-multi-select-content-shadow`, `--slotted-multi-select-content-text`, `--slotted-multi-select-content-text-muted`, `--slotted-multi-select-counter-color`, `--slotted-multi-select-counter-complete-color`, `--slotted-multi-select-disabled-background`, `--slotted-multi-select-disabled-border-color`, `--slotted-multi-select-disabled-color`, `--slotted-multi-select-field-basis`, `--slotted-multi-select-field-min`, `--slotted-multi-select-highlight`, `--slotted-multi-select-highlight-active`, `--slotted-multi-select-highlight-ring`, `--slotted-multi-select-hover-border-color`, `--slotted-multi-select-icon-size-min`, `--slotted-multi-select-invalid-border-color`, `--slotted-multi-select-invalid-edge-width`, `--slotted-multi-select-invalid-focus-ring-color`, `--slotted-multi-select-item-radius`, `--slotted-multi-select-measure`, `--slotted-multi-select-open-border-color`, `--slotted-multi-select-placeholder-color`, `--slotted-multi-select-plain-hover-background`, `--slotted-multi-select-radius`, `--slotted-multi-select-readonly-background`, `--slotted-multi-select-selected-color`, `--slotted-multi-select-separator-color`, `--slotted-multi-select-shadow`, `--slotted-multi-select-subtle-background`, `--slotted-multi-select-subtle-border-color`, `--slotted-multi-select-subtle-hover-background`, `--slotted-multi-select-surface`, `--slotted-radius-lg`, `--slotted-radius-none`, `--slotted-shadow-md`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-5`, `--slotted-surface-raised`, `--slotted-surface-sunken`, `--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`, `--slotted-z-index-popover`
+
+## Examples
+
+See [multi-select.examples.md](./multi-select.examples.md).