@bitforgehq/ui 0.3.0 → 0.3.2

package/ai/components/combobox.md

@@ -0,0 +1,411 @@
+# bf-combobox
+
+Text field that filters a list of options as you type and picks one
+
+`BfComboboxComponent` from `@bitforgehq/ui/overlay` · Forms · since 0.3.1
+
+## Example
+
+```ts
+import { Component, computed, signal } from '@angular/core';
+import { BfComboboxComponent, type BfComboboxOption } from '@bitforgehq/ui/overlay';
+
+/**
+ * The bf-combobox overview.
+ *
+ * Live demo of `bf-combobox`: assign a task to a person. Typing filters the people by name
+ * (ignoring case and accents, so "zoe" finds Zoë), the arrow keys move through the list and
+ * `Enter` or a click picks one; each option shows the person's email as a second line, and one
+ * person is away (disabled). The result line reports the assignee.
+ */
+@Component({
+  selector: 'app-example-combobox-overview',
+  imports: [BfComboboxComponent],
+  template: `
+    <div class="flex max-w-sm flex-col gap-3">
+      <bf-combobox
+        label="Assignee"
+        placeholder="Search people"
+        helpText="Type a name, then pick with Enter or a click."
+        [options]="people"
+        [(value)]="assignee"
+      />
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class ComboboxOverviewExampleComponent {
+  protected readonly people: readonly BfComboboxOption<number>[] = [
+    { value: 1, label: 'Ada Lovelace', description: 'ada@example.com' },
+    { value: 2, label: 'Grace Hopper', description: 'grace@example.com' },
+    { value: 3, label: 'Alan Turing', description: 'Away until Monday', disabled: true },
+    { value: 4, label: 'Katherine Johnson', description: 'katherine@example.com' },
+    { value: 5, label: 'Zoë Martin', description: 'zoe@example.com' },
+  ];
+  /** The person's id, `null` while nobody is assigned. */
+  readonly assignee = signal<number | null>(null);
+
+  readonly status = computed(() => {
+    const person = this.people.find((p) => p.value === this.assignee());
+    return person ? `Assigned to ${person.label}.` : 'Nobody assigned.';
+  });
+}
+```
+
+## Overview
+
+Text field with a filtered list of options to pick one value from (the ARIA combobox pattern).
+Typing filters the list by label, ignoring case and accents; the arrow keys move through it
+and `Enter` picks. Generic over the option value (a string by default); `null` means nothing is
+picked. For several values use `bf-multi-combobox`.
+
+A text field with a list of options that filters as you type, to pick one value from more choices
+than a dropdown can show comfortably: a person, a customer, a city. It follows the
+[ARIA 1.2 combobox](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) pattern with a list
+autocomplete: focus stays in the field while the arrow keys move through the options. It is a
+Signal Forms value control like `bf-select`, with the same label, help and error handling and the
+same field look, and generic over the option value.
+
+Import `BfComboboxComponent` and `BfComboboxOption` from `@bitforgehq/ui/overlay` (needs
+`@angular/cdk`): the list opens in the CDK overlay container, so it is never clipped by a scrolling
+parent and works inside a `BfDialogService` dialog.
+
+## When to use
+
+Use `bf-combobox` to pick one value from a list long enough to search, or whose options come from
+a server: an assignee, a customer, a time zone. Use [bf-select](https://bitforge-ui.web.app/components/select) instead for a
+short list the user can scan (it opens the platform's own picker on phones),
+[bf-radio-group](https://bitforge-ui.web.app/components/radio-group) for up to five or six options read side by side, and
+[bf-multi-combobox](https://bitforge-ui.web.app/components/multi-combobox) to pick several values as tags. Both work in both
+shells; in a Capacitor app set `provideBfDefaults({ fieldSize: 'lg' })` for 48 px fields.
+
+## Typing and picking
+
+Typing filters the options by label, ignoring case and accents (`zoe` finds "Zoë"), opens the list
+and makes the first match active. The arrow keys open the list and move through it (wrapping at
+the ends, skipping disabled options), `Home` and `End` jump to its ends, `Enter` or a click picks
+the active option: the value changes, `(changed)` emits it, the field shows its label and the list
+closes. `Escape` closes the list; a second `Escape` drops the typed text. `Tab` picks nothing.
+
+When the field loses focus, text that names an option exactly (ignoring case and accents) picks it,
+emptied text clears the value (`(changed)` emits `null`), and any other text reverts to the picked
+option's label, so the field never shows text that is not its value.
+
+Options take a `description` (a second, muted line, such as an email) and `disabled` (listed but
+not pickable). `value` is `null` while nothing is picked; for object values pass `compareWith`, as
+on `bf-select`.
+
+## Groups
+
+Give options a `group` to list them under that heading, in the order the groups first appear;
+options without a group come first. Filtering keeps the headings of the groups that still match.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { BfComboboxComponent, type BfComboboxOption } from '@bitforgehq/ui/overlay';
+
+/**
+ * Options under group headings.
+ *
+ * Each option's `group` lists it under that heading (a named `role="group"`), in the order the
+ * groups first appear; filtering keeps the headings of the groups that still have matches.
+ */
+@Component({
+  selector: 'app-example-combobox-groups',
+  imports: [BfComboboxComponent],
+  template: `
+    <bf-combobox
+      class="max-w-sm"
+      label="Time zone"
+      placeholder="Search cities"
+      [options]="zones"
+      [(value)]="zone"
+    />
+  `,
+})
+export class ComboboxGroupsExampleComponent {
+  protected readonly zones: readonly BfComboboxOption[] = [
+    { value: 'Europe/Zurich', label: 'Zürich', group: 'Europe' },
+    { value: 'Europe/Lisbon', label: 'Lisbon', group: 'Europe' },
+    { value: 'Europe/Helsinki', label: 'Helsinki', group: 'Europe' },
+    { value: 'America/New_York', label: 'New York', group: 'Americas' },
+    { value: 'America/Sao_Paulo', label: 'São Paulo', group: 'Americas' },
+    { value: 'Asia/Tokyo', label: 'Tokyo', group: 'Asia' },
+    { value: 'Asia/Singapore', label: 'Singapore', group: 'Asia' },
+  ];
+  readonly zone = signal<string | null>('Europe/Zurich');
+}
+```
+
+## Filtering and server search
+
+`filter` replaces the match function: `(option, query) => boolean`, called for a query that is not
+empty. For a server search, listen to `(queried)`, which emits the typed text on each change (`''`
+once the text is cleared), set `loading` while the request runs (the list shows a spinner row) and
+pass the results as `options` with `[filter]="null"`, so they are shown as the server sent them.
+Debounce or cancel requests in your search. The field keeps the label of the picked option when
+later results no longer hold it. With nothing to show, the list says "No results" (`emptyLabel`,
+else the `comboboxEmpty` label).
+
+The list is not virtualized: keep it to a few hundred options, and search on the server beyond that.
+
+```ts
+import { Component, DestroyRef, computed, inject, signal } from '@angular/core';
+import { BfComboboxComponent, type BfComboboxOption } from '@bitforgehq/ui/overlay';
+
+interface Customer {
+  id: string;
+  name: string;
+  city: string;
+}
+
+/** Stands in for the server's customer table. */
+const CUSTOMERS: readonly Customer[] = [
+  { id: 'c1', name: 'Acme Corporation', city: 'Basel' },
+  { id: 'c2', name: 'Globex', city: 'Bern' },
+  { id: 'c3', name: 'Initech', city: 'Geneva' },
+  { id: 'c4', name: 'Umbrella', city: 'Lausanne' },
+  { id: 'c5', name: 'Hooli', city: 'Zürich' },
+  { id: 'c6', name: 'Stark Industries', city: 'Lugano' },
+];
+
+/**
+ * Server search with a loading row.
+ *
+ * `(queried)` hands each typed text to a search (here a fake one that answers after 400 ms and
+ * matches the name or the city); `loading` shows a spinner row while it runs, and `[filter]="null"`
+ * shows the results as the server sent them, without filtering them again by label.
+ */
+@Component({
+  selector: 'app-example-combobox-server',
+  imports: [BfComboboxComponent],
+  template: `
+    <div class="flex max-w-sm flex-col gap-3">
+      <bf-combobox
+        label="Customer"
+        placeholder="Search by name or city"
+        [options]="options()"
+        [filter]="null"
+        [loading]="loading()"
+        [(value)]="customer"
+        (queried)="search($event)"
+      />
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </div>
+  `,
+})
+export class ComboboxServerExampleComponent {
+  private timer: ReturnType<typeof setTimeout> | undefined;
+  private readonly results = signal<readonly Customer[]>(CUSTOMERS);
+  readonly loading = signal(false);
+  readonly customer = signal<string | null>(null);
+
+  protected readonly options = computed<BfComboboxOption[]>(() =>
+    this.results().map((c) => ({ value: c.id, label: c.name, description: c.city })),
+  );
+  readonly status = computed(() => {
+    const picked = CUSTOMERS.find((c) => c.id === this.customer());
+    return picked ? `Customer: ${picked.name} (${picked.city}).` : 'No customer picked.';
+  });
+
+  constructor() {
+    inject(DestroyRef).onDestroy(() => clearTimeout(this.timer));
+  }
+
+  /** Starts a search for `query`, cancelling the one still running. */
+  search(query: string): void {
+    clearTimeout(this.timer);
+    this.loading.set(true);
+    this.timer = setTimeout(() => {
+      const q = query.trim().toLowerCase();
+      this.results.set(CUSTOMERS.filter((c) => `${c.name} ${c.city}`.toLowerCase().includes(q)));
+      this.loading.set(false);
+    }, 400);
+  }
+}
+```
+
+## With Signal Forms
+
+Bind a field with `[formField]`, modelled as `T | null` and starting at `null`; `required()` treats
+`null` as empty, and the error shows under the field once it is touched (or on submit), as on every
+library field. `readonly` shows the value but never opens the list.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { FormField, form, required, submit } from '@angular/forms/signals';
+import { BfButtonComponent } from '@bitforgehq/ui';
+import { BfComboboxComponent, type BfComboboxOption } from '@bitforgehq/ui/overlay';
+
+/**
+ * A required combobox in a Signal Forms form.
+ *
+ * `[formField]` binds the field (modelled as `T | null`, starting at `null`); `required()` treats
+ * `null` as empty, so submitting without a project shows the error under the field.
+ */
+@Component({
+  selector: 'app-example-combobox-forms',
+  imports: [BfButtonComponent, BfComboboxComponent, FormField],
+  template: `
+    <form class="flex max-w-sm flex-col items-start gap-3" (submit)="onSubmit($event)">
+      <bf-combobox
+        class="self-stretch"
+        label="Project"
+        placeholder="Search projects"
+        [options]="projects"
+        [formField]="task.project"
+      />
+      <bf-button type="submit">Create task</bf-button>
+      <p data-status aria-live="polite" class="text-caption text-text-muted">{{ status() }}</p>
+    </form>
+  `,
+})
+export class ComboboxFormsExampleComponent {
+  protected readonly projects: readonly BfComboboxOption[] = [
+    { value: 'atlas', label: 'Atlas relaunch' },
+    { value: 'borealis', label: 'Borealis' },
+    { value: 'cedar', label: 'Cedar migration' },
+  ];
+  private readonly model = signal<{ project: string | null }>({ project: null });
+  protected readonly task = form(this.model, (path) => {
+    required(path.project);
+  });
+  readonly status = signal('Pick a project, then create the task.');
+
+  async onSubmit(event: Event): Promise<void> {
+    event.preventDefault();
+    await submit(this.task, () => {
+      this.status.set(`Task created in ${this.model().project}.`);
+      return Promise.resolve(undefined);
+    });
+  }
+}
+```
+
+## Sizes and labels
+
+`size` follows the field steps (`sm` 32, `md` 40, `lg` 48 px; unset uses `provideBfDefaults()`'s
+`fieldSize`). Without a visible `label`, give it `ariaLabel` or `ariaLabelledby`, as on
+`bf-select`.
+
+## Desktop
+
+Built for a keyboard and a mouse: the field keeps focus while the arrow keys move through the list,
+and the pointer moving over an option makes it the active one. A click into the field opens the
+list; a click outside closes it. Options are 32, 36 or 44 px tall with the field's size. Under a
+coarse pointer every option row is at least 44 px tall; the field itself gets no touch extension,
+so touch apps use `fieldSize: 'lg'`.
+
+## Theming
+
+- Field: the `bf-input` / `bf-select` tokens: `border-strong` border (`danger-border` on error),
+  `primary` border and `ring` ring on focus, `surface-muted` while read-only or disabled, a
+  `text-subtle` chevron.
+- List: `bg-surface`, a 1 px `border-border`, `rounded-card`, `shadow-floating`; the active option
+  `surface-muted`, a selected option `primary-text` with a check mark, a disabled one
+  `text-disabled`, descriptions and group headings `text-muted`.
+- In forced colours the active option takes the system highlight.
+
+## Accessibility
+
+- The input is `role="combobox"` with `aria-autocomplete="list"`, `aria-expanded`, and while the
+  list shows options `aria-controls` (the listbox) and `aria-activedescendant` (the active option).
+  Focus never leaves the input.
+- The list is a `listbox` named like the field, its options `role="option"` with `aria-selected`
+  and `aria-disabled`; grouped options sit in a `role="group"` named by its heading.
+- The loading and "No results" rows are a `status` live region, so they are announced.
+- `bf-field` renders the `<label for>`, the help and the error text; `aria-describedby`,
+  `aria-invalid` and `aria-errormessage` follow the same rules as on `bf-select`.
+- `focus()` focuses the input; Signal Forms calls it from `focusBoundControl()`.
+
+### Keyboard
+
+| Key                                                  | Where     | Action                                                      |
+| ---------------------------------------------------- | --------- | ----------------------------------------------------------- |
+| <kbd>ArrowDown</kbd> / <kbd>ArrowUp</kbd>            | Field     | Opens the list on the picked (else first / last) option     |
+| <kbd>ArrowDown</kbd> / <kbd>ArrowUp</kbd>            | Open list | Next / previous enabled option, wrapping at the ends        |
+| <kbd>Home</kbd> / <kbd>End</kbd>                     | Open list | First / last enabled option                                 |
+| <kbd>Enter</kbd>                                     | Open list | Picks the active option and closes the list                 |
+| <kbd>Escape</kbd>                                    | Open list | Closes the list                                             |
+| <kbd>Escape</kbd>                                    | Field     | Drops the typed text and shows the picked option's label    |
+| <kbd>Tab</kbd>                                       | Field     | Moves on without picking; the list closes                   |
+| <kbd>A</kbd>–<kbd>Z</kbd>, <kbd>0</kbd>–<kbd>9</kbd> | Field     | Filters the list, opens it and makes the first match active |
+
+## Inputs
+
+| Name             | Type                                                        | Default         | Description                                                                                                                                                                |
+| ---------------- | ----------------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options`        | `readonly BfComboboxOption<T>[]`                            | required        | The options to choose from; with server search, the latest results (keep the picked one).                                                                                  |
+| `compareWith`    | `BfCompareWith<T>`                                          | `Object.is`     | Equality for matching `value` to an option (default `Object.is`); pass one for object values.                                                                              |
+| `filter`         | `BfComboboxFilter<T> \| null`                               | `labelContains` | Whether an option matches the typed text (default: its label contains it, ignoring case and accents); `null` shows `options` unfiltered, for results filtered by a server. |
+| `size`           | `BfSize \| undefined` (`'sm' \| 'md' \| 'lg' \| undefined`) | `undefined`     | Height step: sm 32, md 40, lg 48 px; unset follows `provideBfDefaults()` (`fieldSize`, `md` by default).                                                                   |
+| `label`          | `string`                                                    | `''`            | Visible label above the field.                                                                                                                                             |
+| `ariaLabel`      | `string`                                                    | `''`            | Accessible name when no visible label is rendered. Ignored when `label` is set.                                                                                            |
+| `ariaLabelledby` | `string`                                                    | `''`            | Id(s) of the element(s) that name the field when no visible label is rendered. Ignored when `label` is set.                                                                |
+| `placeholder`    | `string`                                                    | `''`            | Hint text shown in the empty field.                                                                                                                                        |
+| `helpText`       | `string`                                                    | `''`            | Helper text under the field.                                                                                                                                               |
+| `errorMessage`   | `string`                                                    | `''`            | Explicit error text; takes precedence over Signal Forms errors.                                                                                                            |
+| `emptyLabel`     | `string`                                                    | `''`            | Text of the list's row when no option matches; empty uses the `comboboxEmpty` label.                                                                                       |
+| `loading`        | `boolean`                                                   | `false`         | Shows a loading row in the list, while a server search for the typed text runs.                                                                                            |
+| `disabled`       | `boolean`                                                   | `false`         | Disables the field. Set by `[formField]`; do not bind it yourself.                                                                                                         |
+| `readonly`       | `boolean`                                                   | `false`         | Shows the value but blocks changes; the field stays focusable and the list never opens. Set by `[formField]`; do not bind it yourself.                                     |
+| `required`       | `boolean`                                                   | `false`         | Marks the field required. Set by `[formField]`; do not bind it yourself.                                                                                                   |
+| `invalid`        | `boolean`                                                   | `false`         | Field validity from Signal Forms. Set by `[formField]`; do not bind it yourself.                                                                                           |
+| `touched`        | `boolean`                                                   | `false`         | Whether the user has left the field. Set by `[formField]`; do not bind it yourself.                                                                                        |
+| `errors`         | `readonly ValidationError.WithOptionalFieldTree[]`          | `[]`            | Validation errors from Signal Forms. Set by `[formField]`; do not bind it yourself.                                                                                        |
+| `name`           | `string`                                                    | `''`            | Native name attribute of the text input. Set by `[formField]`; do not bind it yourself.                                                                                    |
+| `id`             | `string`                                                    | `generated`     | Input id; generated when not set.                                                                                                                                          |
+| `value`          | `T \| null`                                                 | `null`          | The picked option's value, `null` while nothing is picked; two-way bindable and bound by `[formField]`. Two-way: `[(value)]`.                                              |
+
+## Outputs
+
+| Name      | Payload      | Description                                                                                               |
+| --------- | ------------ | --------------------------------------------------------------------------------------------------------- |
+| `changed` | `T \| null`  | Emitted with the new value after the user picks an option, or `null` after clearing the text.             |
+| `queried` | `string`     | Emitted with the typed text each time the user changes it (`''` once it is cleared), for a server search. |
+| `focused` | `FocusEvent` | Emitted when the input gains focus.                                                                       |
+| `blurred` | `FocusEvent` | Emitted when the input loses focus.                                                                       |
+| `touch`   | `void`       | Emitted on blur so Signal Forms marks the field touched. Set by `[formField]`; do not bind it yourself.   |
+
+## Methods
+
+### `focus(options?: FocusOptions): void`
+
+Focuses the input; Signal Forms calls it from `focusBoundControl()`.
+
+| Parameter  | Type           | Description                                                           |
+| ---------- | -------------- | --------------------------------------------------------------------- |
+| `options?` | `FocusOptions` | Passed on to the native `focus()`, such as `{ preventScroll: true }`. |
+
+## Notes
+
+### Do
+
+- Give every option a short, distinct label; put details in `description`.
+- Keep the picked option in `options` when you replace them with server results.
+- Make the field required when it has no sensible empty state.
+
+### Don't
+
+- Don't use a combobox for a handful of options; use `bf-select` or `bf-radio-group`.
+- Don't load thousands of options into it; search on the server.
+- Don't use it for free text that may match no option; it reverts such text to the value.
+
+## Migration notes
+
+### 0.3.1
+
+New `bf-combobox` (`BfComboboxComponent<T>`) in `@bitforgehq/ui/overlay`: a text field with a
+list of options that filters as you type, to pick one value (the ARIA 1.2 combobox pattern with a
+list autocomplete). `[(value)]` is `T | null`; `options` are `BfComboboxOption<T>` (`value`,
+`label`, `description`, `disabled`, `group`); `compareWith`, `label`, `ariaLabel`,
+`ariaLabelledby`, `placeholder`, `helpText`, `errorMessage`, `size` (`fieldSize`) and the Signal
+Forms value contract like `bf-select`. Filters by label, ignoring case and accents; `filter`
+(`BfComboboxFilter<T>`) replaces the match, `null` turns local filtering off for server results,
+`(queried)` emits the typed text and `loading` shows a spinner row. Arrow keys open and move
+(wrapping), `Home`/`End`, `Enter` picks, `Escape` closes then drops the typed text, `Tab` picks
+nothing; leaving the field reverts unmatched text to the picked label (emptied text clears the
+value, `(changed)` emits `null`). Grouped options render in named `role="group"` sections. New
+label key `comboboxEmpty` ("No results", or `emptyLabel`) and a `BfComboboxHarness` in
+`@bitforgehq/ui/testing` (`open()`, `type(query)`, `getOptionLabels()`, `selectOption(label)`,
+`getValueText()`, `getChipLabels()`, `removeChip(label)`) for both comboboxes.