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

package/docs/select.md

@@ -0,0 +1,199 @@
+<!-- index: ./index.md -->
+# select
+
+`data-ui="select"` · Picks one option from a popup list.
+
+## Import
+
+```ts
+import { SlSelect, SlSelectGroup, SlSelectItem, SlSelectSeparator, SlSelectValue } from '@slotted/angular/select';
+```
+
+Selector: `sl-select, sl-select-group, sl-select-item, sl-select-separator, [slSelectValue]` · exportAs: `slSelect, slSelectGroup, slSelectItem, slSelectSeparator`
+
+## Minimal example
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlField, SlFieldDescription, SlFieldLabel } from '@slotted/angular/field';
+import { SlSelect, SlSelectItem } from '@slotted/angular/select';
+
+const WAREHOUSES = [
+  { value: 'RNO', label: 'Reno, NV' },
+  { value: 'CMH', label: 'Columbus, OH' },
+  { value: 'SAV', label: 'Savannah, GA' },
+];
+
+@Component({
+  selector: 'app-select-basic',
+  imports: [SlField, SlFieldDescription, SlFieldLabel, SlSelect, SlSelectItem],
+  template: `
+    <div slField>
+      <label slFieldLabel>Fulfilment warehouse</label>
+      <sl-select placeholder="Choose a warehouse">
+        @for (warehouse of warehouses; track warehouse.value) {
+          <sl-select-item [value]="warehouse.value">{{ warehouse.label }}</sl-select-item>
+        }
+      </sl-select>
+      <span slFieldDescription>New orders ship from this warehouse.</span>
+    </div>
+  `,
+})
+export class SelectBasic {
+  protected readonly warehouses = WAREHOUSES;
+}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | sl-select, the host element itself | yes |
+| `trigger` | button with role="combobox" | yes |
+| `value` | span | yes |
+| `arrow` | span | yes |
+| `busy` | span | no |
+| `tags` | span | no |
+| `summary` | span | no |
+| `clear` | button | no |
+| `positioner` | div, built into the portal when the popup opens | yes |
+| `content` | div with role="listbox", or role="dialog" under search | yes |
+| `search` | div, drawn only under search | no |
+| `search-icon` | span, aria-hidden | no |
+| `search-input` | input with role="combobox" | no |
+| `list` | div with role="listbox", drawn only under search | no |
+| `chosen` | div, aria-hidden, drawn while several values are chosen | no |
+| `match` | mark, the match part of the highlight family, whose root sits inside label | no |
+| `group` | sl-select-group with role="group" | no |
+| `group-label` | div | no |
+| `item` | sl-select-item with role="option" | yes |
+| `indicator` | span | yes |
+| `icon` | span | no |
+| `label` | span | yes |
+| `description` | span | no |
+| `separator` | sl-select-separator with role="separator" | no |
+| `empty` | div | no |
+| `status` | div with role="status" | no |
+| `placeholder` | div | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `search` | `boolean` | false | sl-select | Puts a search field at the top of the list. The list becomes a dialog, DOM focus moves into the search field, and typeahead turns off. |
+| `searchValue` | `model<string>` | '' | sl-select | The search query. Two-way bindable. It is never the selection. |
+| `filter` | `((label: string, query: string) => boolean) \| null` | createFilter | sl-select | Decides whether an option matches the query. Unset uses a locale-sensitive contains that ignores case and accents. null turns filtering off, for a list a server has already filtered. A function replaces the comparison. |
+| `highlightMatch` | `boolean` | true | sl-select | Whether the span of a label that matched the query is marked. |
+| `locale` | `string` | — | sl-select | The BCP 47 language the default filter compares in. Defaults to the language in force. |
+| `label` | `string` | — | sl-select-item | The label as text instead of projected content. The filter compares it and the match mark splits it. An option that projects its label is filtered on textValue or on its rendered text and is not marked, because Angular cannot read projected content before it is created. |
+| `value` | `model<string \| string[] \| null>` | null | sl-select | The chosen value, or values when multiple is set. Two-way bindable; formControl, formControlName and ngModel bind it too. |
+| `open` | `model<boolean>` | false | sl-select | Whether the list is open. Two-way bindable. |
+| `highlightedValue` | `model<string \| null>` | null | sl-select | The highlighted option. Two-way bindable. The highlight is where the keyboard is, not what is chosen. |
+| `placeholder` | `string` | — | sl-select | What the control shows while nothing is chosen. |
+| `items` | `SelectItems` | — | sl-select | Values with their labels, so the closed control can show the label of a value whose option has not been rendered. Options are rendered only while the list is open. |
+| `name` | `string` | — | sl-select | The name the value is submitted under. It renders a hidden native select that a plain form submits. |
+| `form` | `string` | — | sl-select | The id of the form the control belongs to, when it is not the enclosing form. |
+| `total` | `number` | — | sl-select | The size of the whole collection when only part of it is rendered. Options with position then carry aria-setsize and aria-posinset. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | sl-select | The step of the control scale. When unset, the select takes the size of its field. |
+| `variant` | `'outline' \| 'subtle' \| 'plain'` | outline | sl-select | How much frame the control draws: an outline, a filled subtle frame, or plain, with no frame at rest. |
+| `side` | `'bottom' \| 'top' \| 'inline-start' \| 'inline-end' \| 'left' \| 'right'` | bottom | sl-select | The edge of the control the list opens from. |
+| `align` | `'start' \| 'center' \| 'end'` | start | sl-select | Where the list aligns along that edge. |
+| `width` | `'anchor' \| 'content'` | content | sl-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-select | When the list exists in the DOM: active while it is open, lazy from the first open on, eager from the start. |
+| `strategy` | `'absolute' \| 'fixed'` | absolute | sl-select | The CSS position the positioner gives the list. |
+| `multiple` | `boolean` | false | sl-select | Allows several values. The value becomes an array, and the list stays open as options are chosen. |
+| `clearable` | `boolean` | false | sl-select | Draws a clear button once something is chosen. |
+| `loop` | `boolean` | false | sl-select | Whether the arrow keys wrap from the last option to the first. |
+| `typeahead` | `boolean` | true | sl-select | Whether typing the first letters of a label highlights the matching option. Off while search is set. |
+| `typeaheadTimeout` | `number` | 500 | sl-select | How long typed letters keep building one search, in milliseconds. |
+| `closeOnSelect` | `boolean` | true | sl-select | Whether choosing an option closes the list. A multiple select stays open regardless. |
+| `closeOnEscape` | `boolean` | true | sl-select | Whether Escape closes the list. |
+| `closeOnOutsidePress` | `boolean` | true | sl-select | Whether a press outside the list closes it. |
+| `flip` | `boolean` | true | sl-select | Whether the list may open on the opposite side when it does not fit. |
+| `shift` | `boolean` | true | sl-select | Whether the list may slide along its edge to stay in view. |
+| `hideWhenDetached` | `boolean` | true | sl-select | Whether the list hides while its control is scrolled out of view. |
+| `portal` | `boolean` | true | sl-select | Whether the list renders at the end of the document instead of inside the control. |
+| `fullWidth` | `boolean` | true | sl-select | Whether the control fills its container. false sizes it to its widest value. |
+| `disabled` | `boolean` | false | sl-select | Disables the control and takes it out of the tab order. When unset, the select takes the state of its field or of its form control. |
+| `readOnly` | `boolean` | false | sl-select | Keeps the value visible and focusable and never opens the list. When unset, the select takes the state of its field. |
+| `required` | `boolean` | false | sl-select | Sets aria-required, and makes the select’s validator report a required error while nothing is chosen. |
+| `invalid` | `boolean` | false | sl-select | Sets aria-invalid and draws the border and the focus ring in the danger tone. When unset, the select takes the state of its field. |
+| `loading` | `boolean` | false | sl-select | Shows the spinner, three placeholder rows and the loading message, and sets aria-busy on the listbox. |
+| `sideOffset` | `number` | 4 | sl-select | The gap between the control and the list, in pixels. |
+| `alignOffset` | `number` | 0 | sl-select | How far the list shifts along its edge, in pixels. |
+| `collisionPadding` | `number` | 8 | sl-select | The distance the list keeps from the edges of the viewport, in pixels. |
+| `messages` | `Partial<SelectMessages>` | — | sl-select | Replaces any of the phrases the select writes: clear, remove ({label}), summary ({count}), search, searchPlaceholder, count ({count}), empty and loading. Phrases left out come from the language in force. |
+| `value` | `string` | — | sl-select-item | The option’s value: what is submitted and what a change request carries. |
+| `disabled` | `boolean` | false | sl-select-item | Announces the option as unavailable, keeps it in the list, and skips it with every movement key. |
+| `description` | `string` | — | sl-select-item | A second line under the label. |
+| `icon` | `GlyphName` | — | sl-select-item | The glyph drawn in the first column, inside an Icon box. |
+| `textValue` | `string` | — | sl-select-item | The text typeahead and the filter match on, when the label is not plain text. |
+| `position` | `number` | — | sl-select-item | The option’s one-based place in the whole collection, written as aria-posinset. |
+| `label` | `string` | — | sl-select-group | The group’s heading, which names the group through aria-labelledby. |
+| `provideSelectDefaults()` | `Provider` | — | Application | Sets any axis once, in a bootstrap, a route or a component’s providers. The words come from the language in force, set by provideSlotted. An input set on one select still wins. |
+| `slSelectValue` | `ng-template` | — | sl-select | Replaces the built-in summary. The template context holds the values as $implicit and their labels as labels. |
+| `exportAs` | `slSelect` | — | sl-select | The SlSelect instance, for a template that calls focus(), focusSearch(), setOpen() or scrollToKey(). |
+| `ControlValueAccessor` | `NG_VALUE_ACCESSOR` | — | sl-select | formControl, formControlName and ngModel bind the value, and the form’s disabled state reaches the control. |
+| `Validator` | `NG_VALIDATORS` | — | sl-select | The select reports required itself: the hidden native select always holds an option, so the browser cannot. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `valueChange` | `string \| string[] \| null` | After the selection changes. It is the output half of [(value)]. |
+| `valueChangeRequest` | `ChangeRequest<string \| string[] \| null>` | Before the selection changes. reason is pointer, keyboard, clear, select or programmatic, and cancel() refuses the change. |
+| `openChange` | `boolean` | After the list opens or closes. It is the output half of [(open)]. |
+| `openChangeRequest` | `ChangeRequest<boolean>` | Before the list opens or closes. reason tells a choice from a dismissal: select, escape, outsidePress, pointer, keyboard, dismiss, blur or programmatic. |
+| `searchValueChange` | `string` | After the query changes. It is the output half of [(searchValue)]. |
+| `searchValueChangeRequest` | `ChangeRequest<string>` | Before the query changes. reason is keyboard for typing, select when an option is chosen while the list stays open, and clear when Escape empties the field or the list empties it as it opens and closes. |
+| `highlightedValueChangeRequest` | `ChangeRequest<string \| null>` | Before the highlight moves. reason is pointer, keyboard or programmatic. |
+
+## 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` |
+| `multiple` | `true`, `false` | `false` |
+| `clearable` | `true`, `false` | `false` |
+| `loop` | `true`, `false` | `false` |
+| `search` | `true`, `false` | `false` |
+| `highlightMatch` | `true`, `false` | `true` |
+| `typeahead` | `true`, `false` | `true` |
+| `closeOnSelect` | `true`, `false` | `true` |
+| `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 trigger is a button with role="combobox", aria-haspopup="listbox" and aria-expanded. The list is a listbox with an option for each row.
+- DOM focus stays on the trigger. aria-activedescendant names the highlighted option, which also carries data-current; chosen options carry aria-selected and data-selected. The highlight is where the keyboard is; the selection is what was chosen.
+- A disabled option carries aria-disabled, keeps its place in the list, and is skipped by every movement key, typeahead included.
+- Inside a field, the trigger carries the field’s control id, so a press on the label focuses it without opening the list. The trigger also takes the label through aria-labelledby, because the name a label gives a button does not reliably reach a button with role="combobox". Outside a field, give sl-select an aria-label, which it forwards to the trigger.
+- With search, the list is a dialog that holds a search field and a listbox, the trigger sets aria-haspopup="dialog", and focus moves into the search field while the list is open.
+- Tab chooses the highlighted option and moves focus on, as the APG select-only example specifies; a native select only closes. Escape closes without choosing.
+
+## 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-radius-lg`, `--slotted-radius-none`, `--slotted-select-action-active-background`, `--slotted-select-action-color`, `--slotted-select-action-hover-background`, `--slotted-select-action-size`, `--slotted-select-arrow-color`, `--slotted-select-background`, `--slotted-select-border-color`, `--slotted-select-color`, `--slotted-select-content-border-color`, `--slotted-select-content-padding-block`, `--slotted-select-content-padding-inline`, `--slotted-select-content-radius`, `--slotted-select-content-shadow`, `--slotted-select-content-text`, `--slotted-select-content-text-muted`, `--slotted-select-disabled-background`, `--slotted-select-disabled-border-color`, `--slotted-select-disabled-color`, `--slotted-select-highlight`, `--slotted-select-highlight-active`, `--slotted-select-highlight-ring`, `--slotted-select-hover-border-color`, `--slotted-select-icon-size-min`, `--slotted-select-invalid-border-color`, `--slotted-select-invalid-edge-width`, `--slotted-select-invalid-focus-ring-color`, `--slotted-select-item-radius`, `--slotted-select-measure`, `--slotted-select-open-border-color`, `--slotted-select-placeholder-color`, `--slotted-select-plain-hover-background`, `--slotted-select-radius`, `--slotted-select-readonly-background`, `--slotted-select-search-icon-color`, `--slotted-select-selected-color`, `--slotted-select-separator-color`, `--slotted-select-shadow`, `--slotted-select-subtle-background`, `--slotted-select-subtle-border-color`, `--slotted-select-subtle-hover-background`, `--slotted-select-surface`, `--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 [select.examples.md](./select.examples.md).