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

package/docs/combobox.md

@@ -0,0 +1,209 @@
+<!-- index: ./index.md -->
+# combobox
+
+`data-ui="combobox"` · Text input that filters a list of options.
+
+## Import
+
+```ts
+import {
+  SlCombobox,
+  SlComboboxGroup,
+  SlComboboxItem,
+  SlComboboxItemIcon,
+  SlComboboxSeparator,
+} from '@slotted/angular/combobox';
+```
+
+Selector: `sl-combobox, sl-combobox-group, sl-combobox-item, [slComboboxItemIcon], sl-combobox-separator` · exportAs: `slCombobox, slComboboxGroup, slComboboxItem, slComboboxSeparator`
+
+## Minimal example
+
+Example
+
+```ts
+import { Component } from '@angular/core';
+import { SlCombobox, SlComboboxItem } from '@slotted/angular/combobox';
+import { SlField, SlFieldLabel } from '@slotted/angular/field';
+
+const CUSTOMERS = [
+  { id: 'brightline', name: 'Brightline Studio' },
+  { id: 'harbor-pine', name: 'Harbor & Pine' },
+  { id: 'northgate', name: 'Northgate Labs' },
+  { id: 'quill', name: 'Quill & Co.' },
+  { id: 'solstice', name: 'Solstice Outdoor' },
+  { id: 'verde', name: 'Verde Kitchen' },
+  { id: 'atlas', name: 'Atlas Freight' },
+  { id: 'juniper', name: 'Juniper Health' },
+];
+
+@Component({
+  selector: 'app-combobox-basic',
+  imports: [SlCombobox, SlComboboxItem, SlField, SlFieldLabel],
+  template: `
+    <div slField>
+      <label slFieldLabel>Customer</label>
+      <sl-combobox placeholder="Search customers">
+        @for (customer of customers; track customer.id) {
+          <sl-combobox-item [value]="customer.id" [label]="customer.name" />
+        }
+      </sl-combobox>
+    </div>
+  `,
+})
+export class ComboboxBasic {
+  protected readonly customers = CUSTOMERS;
+}
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | sl-combobox, the host element | yes |
+| `input` | input with role="combobox" | yes |
+| `trigger` | button | yes |
+| `arrow` | span | yes |
+| `busy` | span | no |
+| `clear` | button | no |
+| `positioner` | div, built at the end of the document when the popup opens | yes |
+| `content` | div with role="listbox" | yes |
+| `group` | sl-combobox-group with role="group" | no |
+| `group-label` | div | no |
+| `item` | sl-combobox-item with role="option" | yes |
+| `indicator` | span | yes |
+| `icon` | span, or the element slComboboxItemIcon is on | no |
+| `label` | span | yes |
+| `match` | mark | no |
+| `description` | span | no |
+| `separator` | sl-combobox-separator with role="separator" | no |
+| `empty` | div | no |
+| `status` | div with role="status" and aria-live="polite" | yes |
+| `placeholder` | div | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `inputValue` | `model<string>` | '' | sl-combobox | The text in the input, separate from the chosen value. Two-way. |
+| `value` | `model<string \| null>` | null | sl-combobox | The key of the chosen option. Two-way, and the value a form control binds. |
+| `defaultValue` | `string \| null` | — | sl-combobox | The initial value when value is not bound, read once at init. It sets the key, not the text. |
+| `open` | `model<boolean>` | false | sl-combobox | Whether the popup is open. Two-way. |
+| `highlightedValue` | `model<string \| null>` | null | sl-combobox | The key of the highlighted option, which is separate from the chosen one. Two-way. |
+| `aria-label` | `string` | — | sl-combobox | Names the input and the listbox when no field label names them. The host element keeps no name. |
+| `placeholder` | `string` | '' | sl-combobox | The text the input shows while it is empty. |
+| `filter` | `((label, query) => boolean) \| null` | — | sl-combobox | The comparison between a label and the query. Unset uses a locale-sensitive contains; null turns filtering off for a list a server has already filtered. |
+| `locale` | `string` | — | sl-combobox | The BCP 47 language of the default filter. The active locale when unset. |
+| `items` | `ComboboxItems` | — | sl-combobox | Labels for values, so a closed combobox can show the label of an option it has not rendered. |
+| `name` | `string` | — | sl-combobox | The name the value is submitted under. Renders a hidden input that carries the chosen key. |
+| `form` | `string` | — | sl-combobox | The id of the form the value is submitted with, when it is not the enclosing one. |
+| `total` | `number` | — | sl-combobox | The size of the whole collection, written to aria-setsize on each option. |
+| `autocomplete` | `'none' \| 'list' \| 'both'` | list | sl-combobox | What typing does: none keeps every option, list filters the options, and both also completes the first match inline. Written to aria-autocomplete. |
+| `openOn` | `'input' \| 'focus' \| 'manual'` | input | sl-combobox | When the popup opens without the trigger: on typing or a press on the input (input), on every focus and press (focus), or only from the trigger and the arrow keys (manual). |
+| `allowsCustomValue` | `boolean` | false | sl-combobox | Whether text that matches no option becomes the value on Enter or blur. |
+| `creatable` | `boolean` | false | sl-combobox | Whether the popup offers to create what was typed when nothing matched. Taking the offer emits create. |
+| `autoHighlight` | `boolean` | false | sl-combobox | Whether the first match is highlighted when the popup opens and after each query typed, so Enter takes it. A chosen option that is showing takes precedence. |
+| `highlightMatch` | `boolean` | true | sl-combobox | Whether the part of each label the query matched is marked. |
+| `size` | `'sm' \| 'md' \| 'lg'` | md | sl-combobox | The control size. Unset follows the enclosing field. |
+| `variant` | `'outline' \| 'subtle' \| 'plain'` | outline | sl-combobox | How much frame the control draws. |
+| `side` | `'bottom' \| 'top' \| 'inline-start' \| 'inline-end' \| 'left' \| 'right'` | bottom | sl-combobox | The edge of the control the popup opens from. |
+| `align` | `'start' \| 'center' \| 'end'` | start | sl-combobox | The alignment of the popup along that edge. |
+| `width` | `'anchor' \| 'content'` | content | sl-combobox | The popup width: content keeps it 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-combobox | When the popup is built: only while open, from the first open, or from the start. |
+| `strategy` | `'absolute' \| 'fixed'` | absolute | sl-combobox | The CSS positioning the popup uses. |
+| `clearable` | `boolean` | true | sl-combobox | Whether a clear button appears once the input holds text. |
+| `loop` | `boolean` | false | sl-combobox | Whether ArrowDown and ArrowUp wrap at the ends of the list. |
+| `closeOnSelect` | `boolean` | true | sl-combobox | Whether choosing an option closes the popup. |
+| `closeOnEscape` | `boolean` | true | sl-combobox | Whether Escape closes the popup. |
+| `closeOnOutsidePress` | `boolean` | true | sl-combobox | Whether a press outside the combobox closes the popup. |
+| `flip` | `boolean` | true | sl-combobox | Whether the popup moves to the opposite side when it does not fit. |
+| `shift` | `boolean` | true | sl-combobox | Whether the popup slides along its side to stay in view. |
+| `hideWhenDetached` | `boolean` | true | sl-combobox | Whether the popup hides once the control scrolls out of view. |
+| `portal` | `boolean` | true | sl-combobox | Whether the popup is built at the end of the document instead of inside the combobox. |
+| `fullWidth` | `boolean` | true | sl-combobox | Whether the control fills its container or keeps its own width. |
+| `disabled` | `boolean` | false | sl-combobox | Turns off the input, the trigger and the popup. Unset follows the enclosing field and the disabled state of the form control. |
+| `readOnly` | `boolean` | false | sl-combobox | Keeps the text selectable and copyable and never opens the popup. Unset follows the enclosing field. |
+| `required` | `boolean` | false | sl-combobox | Sets the native required attribute on the input, and the validator reports an empty value. Unset follows the enclosing field. |
+| `invalid` | `boolean` | false | sl-combobox | Draws the border and the focus ring in the invalid tone and sets aria-invalid. Unset follows the enclosing field. |
+| `loading` | `boolean` | false | sl-combobox | Shows the spinner, the placeholder rows and the loading message, and sets aria-busy on the listbox. |
+| `sideOffset` | `number` | 4 | sl-combobox | The gap between the control and the popup, in pixels. |
+| `alignOffset` | `number` | 0 | sl-combobox | How far the popup shifts along its side, in pixels. |
+| `collisionPadding` | `number` | 8 | sl-combobox | The minimum distance between the popup and the edge of the viewport, in pixels. |
+| `messages` | `Partial<ComboboxMessages>` | — | sl-combobox | Phrases that replace the active locale’s, key by key: clear, trigger, create ({query}), empty, loading and count ({count}). |
+| `value` | `string` | — | sl-combobox-item | The option key: what the form submits and what valueChange emits. |
+| `label` | `string` | — | sl-combobox-item | The option text: what the reader sees, what the filter compares and what the mark splits. |
+| `disabled` | `boolean` | false | sl-combobox-item | Keeps the option in the list, announces it as unavailable, and skips it with every movement key. |
+| `description` | `string` | — | sl-combobox-item | The second line under the label. |
+| `icon` | `GlyphName` | — | sl-combobox-item | The glyph drawn in the first column, as a Glyph inside an Icon. An element of your own goes there through slComboboxItemIcon. |
+| `position` | `number` | — | sl-combobox-item | The position of the option in the whole collection, written to aria-posinset. |
+| `label` | `string` | — | sl-combobox-group | The name of the group, which the group references through aria-labelledby. |
+| `provideComboboxDefaults()` | `Provider` | — | Application | Sets any axis once, in a bootstrap, a route or the providers of a component. The phrases come from the active locale, set by provideSlotted. |
+| `slComboboxItemIcon` | `directive` | — | element inside sl-combobox-item | Places the element in the first column, for artwork a glyph cannot draw, such as an avatar. |
+| `exportAs` | `slCombobox` | — | sl-combobox | The component instance, for a template that calls focus(), setOpen() or scrollToKey(). |
+| `ControlValueAccessor` | `NG_VALUE_ACCESSOR` | — | sl-combobox | formControl, formControlName and ngModel bind the chosen value, and the disabled state of the form control reaches the combobox. |
+| `Validator` | `NG_VALIDATORS` | — | sl-combobox | Reports required, and text that matches no option while allowsCustomValue is off. A native input cannot report the second. |
+| `native attributes` | `placeholder, aria-label` | — | sl-combobox | The two attributes the host passes to the input. Other attributes stay on the host element, and every text-editing key keeps its browser behaviour. |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `inputValueChange` | `string` | After the text changes; the output half of [(inputValue)]. |
+| `valueChange` | `string \| null` | After the chosen value changes; the output half of [(value)]. |
+| `openChange` | `boolean` | After the popup opens or closes; the output half of [(open)]. |
+| `highlightedValueChange` | `string \| null` | After the highlight moves; the output half of [(highlightedValue)]. |
+| `inputValueChangeRequest` | `ChangeRequest<string>` | Before the text changes. The reason is keyboard while the reader types, select when an option is chosen, and clear, blur or programmatic otherwise. |
+| `valueChangeRequest` | `ChangeRequest<string \| null>` | Before the chosen value changes. Typing emits only the text request; choosing an option emits both, each with the reason select. |
+| `openChangeRequest` | `ChangeRequest<boolean>` | Before the popup opens or closes. The reason tells a selection from a dismissal: select, escape, outsidePress, dismiss, blur, pointer, keyboard or programmatic. |
+| `highlightedValueChangeRequest` | `ChangeRequest<string \| null>` | Before the highlight moves, by key or by pointer, and when the filter removes the highlighted option. |
+| `create` | `{ query: string; reason: ComboboxValueReason }` | When the reader takes the create option, which appears while creatable is set, the query is not empty and nothing matched. The popup closes and nothing is selected: add the option to your collection and select it. |
+| `inputReset` | `{ rejected: string; reason: 'blur' }` | When the input loses focus holding text that matches no option while allowsCustomValue is off. The text returns to the label of the chosen option, or empties, and the event carries the rejected text. |
+| `loadMore` | `void` | When the end of the rendered list scrolls into view. Fetch the next page; the combobox keeps no cursor of its own. |
+
+## 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` |
+| `autocomplete` | `none`, `list`, `both` | `list` |
+| `openOn` | `input`, `focus`, `manual` | `input` |
+| `allowsCustomValue` | `true`, `false` | `false` |
+| `autoHighlight` | `true`, `false` | `false` |
+| `highlightMatch` | `true`, `false` | `true` |
+| `clearable` | `true`, `false` | `true` |
+| `loop` | `true`, `false` | `false` |
+| `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 input has role="combobox" with aria-autocomplete, aria-expanded and aria-controls. The popup has role="listbox", and each row has role="option". The trigger button is out of the tab sequence, as the ARIA combobox pattern requires.
+- Focus stays on the input, so Home, End, ArrowLeft, ArrowRight, Backspace and Delete keep their text-editing behaviour. The highlight moves through aria-activedescendant, and the caret does not move with it.
+- Escape works in two steps, both named by the pattern. With the popup open, it closes the popup and keeps the text. With the popup closed, it restores the label of the chosen option, and a second press clears the selection.
+- The status row is a polite live region. It announces how many options matched, and "Loading…" while a request is in flight.
+- Tab commits nothing: an option the reader arrowed past is not a choice, which is where the combobox differs from the select. Tab does accept an inline completion that is still showing.
+
+## Tokens
+
+`--slotted-border-subtle`, `--slotted-border-width-thin`, `--slotted-combobox-action-active-background`, `--slotted-combobox-action-color`, `--slotted-combobox-action-hover-background`, `--slotted-combobox-action-size`, `--slotted-combobox-arrow-color`, `--slotted-combobox-autofill-background`, `--slotted-combobox-background`, `--slotted-combobox-border-color`, `--slotted-combobox-color`, `--slotted-combobox-completion-background`, `--slotted-combobox-completion-color`, `--slotted-combobox-content-border-color`, `--slotted-combobox-content-padding-block`, `--slotted-combobox-content-padding-inline`, `--slotted-combobox-content-radius`, `--slotted-combobox-content-shadow`, `--slotted-combobox-content-text`, `--slotted-combobox-content-text-muted`, `--slotted-combobox-disabled-background`, `--slotted-combobox-disabled-border-color`, `--slotted-combobox-disabled-color`, `--slotted-combobox-highlight`, `--slotted-combobox-highlight-active`, `--slotted-combobox-highlight-ring`, `--slotted-combobox-hover-border-color`, `--slotted-combobox-icon-size-min`, `--slotted-combobox-invalid-border-color`, `--slotted-combobox-invalid-edge-width`, `--slotted-combobox-invalid-focus-ring-color`, `--slotted-combobox-item-radius`, `--slotted-combobox-measure`, `--slotted-combobox-open-border-color`, `--slotted-combobox-placeholder-color`, `--slotted-combobox-plain-hover-background`, `--slotted-combobox-radius`, `--slotted-combobox-readonly-background`, `--slotted-combobox-selected-color`, `--slotted-combobox-separator-color`, `--slotted-combobox-shadow`, `--slotted-combobox-subtle-background`, `--slotted-combobox-subtle-border-color`, `--slotted-combobox-subtle-hover-background`, `--slotted-combobox-surface`, `--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-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 [combobox.examples.md](./combobox.examples.md).