@adia-ai/web-components 0.6.33 → 0.6.34

package/components/combobox/combobox.d.ts

@@ -0,0 +1,113 @@
+/**
+ * `<combobox-ui>` — Typeahead-filterable single-select primitive — the constrained-choice
+combobox per WAI-APG "Combobox With List Autocomplete (manual
+selection)". The committed value MUST come from the options list
+unless `[free-text]` is set. Distinct from `<select-ui searchable>`
+(button-first dropdown) and `<autocomplete-input-ui>` (free-form).
+Form-bearing via UIFormElement: `[name]`, `[value]`, `[required]`,
+`[disabled]`, fires `change`. Options via native `<option>` /
+`<optgroup>` children OR programmatic `.options` array.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/combobox
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export interface ComboboxChangeEventDetail {
+  /** Resolved option object or null when free-text / cleared. */
+  option: Record<string, unknown>;
+  /** One of `click` / `keyboard` / `programmatic`. */
+  source: string;
+  /** Committed value. */
+  value: string;
+}
+
+export type ComboboxChangeEvent = CustomEvent<ComboboxChangeEventDetail>;
+export interface ComboboxCloseEventDetail {
+  /** One of `escape` / `outside` / `select` / `blur`. */
+  reason: string;
+}
+
+export type ComboboxCloseEvent = CustomEvent<ComboboxCloseEventDetail>;
+export interface ComboboxCreateEventDetail {
+  /** The typed text the user is trying to create. */
+  value: string;
+}
+
+export type ComboboxCreateEvent = CustomEvent<ComboboxCreateEventDetail>;
+export interface ComboboxInputEventDetail {
+  /** Lowercased filter query. */
+  query: string;
+  /** Current input text (the user's typed query). */
+  value: string;
+}
+
+export type ComboboxInputEvent = CustomEvent<ComboboxInputEventDetail>;
+export interface ComboboxInvalidEventDetail {
+  /** The unmatched typed text. */
+  query: string;
+}
+
+export type ComboboxInvalidEvent = CustomEvent<ComboboxInvalidEventDetail>;
+export interface ComboboxOpenEventDetail {
+  /** One of `click` / `keyboard` / `typing`. */
+  trigger: string;
+}
+
+export type ComboboxOpenEvent = CustomEvent<ComboboxOpenEventDetail>;
+
+export class UICombobox extends UIElement {
+  /** Marks the field as required for form validation */
+  required: boolean;
+  /** Renders an `x` clear button when value is set */
+  clearable: boolean;
+  /** Implies `[free-text]`; on Enter with unmatched typed text fires a
+`create` event with detail.value so the consumer can run a
+backend create-then-refresh-options flow. */
+  creatable: boolean;
+  /** Disables interaction and dims the control */
+  disabled: boolean;
+  /** Validation error message */
+  error: string;
+  /** Caption text below the field; wires `aria-describedby` on the host
+so screen readers announce it as a description. */
+  hint: string;
+  /** Inline label rendered above the field. Wrap with <field-ui> for
+proper `<label for>` association in form-row compositions. */
+  label: string;
+  /** Shows a loading spinner inside the popover; consumer drives async fetch */
+  loading: boolean;
+  /** Form control name for form data submission */
+  name: string;
+  /** Reflects popover open / closed state */
+  open: boolean;
+  /** Programmatic option list. Array of {value, label, disabled?, group?} or grouped {label, options:[…]}. Alternative to declarative <option> / <optgroup> children. */
+  options: unknown[];
+  /** Placeholder text in the input when value is empty */
+  placeholder: string;
+  /** Prevents selection changes while keeping the field focusable + popover-open allowed */
+  readonly: boolean;
+  /** Sizing scale via universal `[size]` attribute system. Matches Input + Select sizing tokens so a Combobox rendered alongside either feels coherent in a form row. */
+  size: 'sm' | 'md' | 'lg';
+  /** Currently selected option value. Must be a member of `options[].value` unless `[free-text]` is set. With declarative <option> children, a child carrying the native `selected` attribute sets the initial value when this attribute is absent. */
+  value: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UICombobox, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'change', listener: (ev: ComboboxChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'close', listener: (ev: ComboboxCloseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'create', listener: (ev: ComboboxCreateEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'input', listener: (ev: ComboboxInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'invalid', listener: (ev: ComboboxInvalidEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'open', listener: (ev: ComboboxOpenEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/components/combobox/combobox.examples.md

@@ -0,0 +1,59 @@
+# combobox — Examples
+
+## basic
+
+```html
+<field-ui label="Country">
+  <combobox-ui name="country" placeholder="Select country…">
+    <option value="us">United States</option>
+    <option value="gb">United Kingdom</option>
+    <option value="de">Germany</option>
+    <option value="fr">France</option>
+    <option value="es">Spain</option>
+    <option value="it">Italy</option>
+  </combobox-ui>
+</field-ui>
+```
+
+## grouped options
+
+```html
+<field-ui label="Location">
+  <combobox-ui placeholder="Choose a city">
+    <optgroup label="Americas">
+      <option value="nyc">New York</option>
+      <option value="sf">San Francisco</option>
+    </optgroup>
+    <optgroup label="Europe">
+      <option value="london">London</option>
+      <option value="paris">Paris</option>
+    </optgroup>
+  </combobox-ui>
+</field-ui>
+```
+
+## creatable tag picker
+
+```html
+<field-ui label="Tag">
+  <combobox-ui name="tag" creatable placeholder="Pick or create a tag…">
+    <option value="bug">bug</option>
+    <option value="feature">feature</option>
+    <option value="chore">chore</option>
+  </combobox-ui>
+</field-ui>
+```
+
+Typing "regression" + Enter fires the `create` event with `detail.value === "regression"`.
+
+## clearable
+
+```html
+<field-ui label="Role">
+  <combobox-ui clearable value="user" placeholder="Pick a role…">
+    <option value="user">User</option>
+    <option value="admin">Admin</option>
+    <option value="guest">Guest</option>
+  </combobox-ui>
+</field-ui>
+```

package/components/combobox/combobox.js

@@ -0,0 +1,17 @@
+/**
+ * `<combobox-ui>` — auto-registers the tag on import.
+ *
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UICombobox } from '@adia-ai/web-components/components/combobox/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { defineIfFree } from '../../core/register.js';
+import { UICombobox } from './class.js';
+
+defineIfFree('combobox-ui', UICombobox);
+
+export { UICombobox };

package/components/combobox/combobox.test.js

@@ -0,0 +1,181 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import '../../core/element.js';
+import './combobox.js';
+
+const tick = () => new Promise((r) => queueMicrotask(r));
+
+function mount(html) {
+  const wrap = document.createElement('div');
+  wrap.innerHTML = html;
+  document.body.appendChild(wrap);
+  return wrap.firstElementChild;
+}
+
+describe('combobox-ui', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('parses declarative <option> children into the options model', async () => {
+    const el = mount(`
+      <combobox-ui>
+        <option value="a">Alpha</option>
+        <option value="b">Beta</option>
+        <option value="c">Gamma</option>
+      </combobox-ui>
+    `);
+    await tick();
+    expect(el.options.length).toBe(3);
+    expect(el.options[0].value).toBe('a');
+    expect(el.options[0].label).toBe('Alpha');
+  });
+
+  it('honours <option selected> as initial value', async () => {
+    const el = mount(`
+      <combobox-ui>
+        <option value="a">Alpha</option>
+        <option value="b" selected>Beta</option>
+        <option value="c">Gamma</option>
+      </combobox-ui>
+    `);
+    await tick();
+    expect(el.value).toBe('b');
+  });
+
+  it('renders ARIA combobox + listbox wiring per WAI-APG', async () => {
+    const el = mount(`
+      <combobox-ui>
+        <option value="a">Alpha</option>
+      </combobox-ui>
+    `);
+    await tick();
+    // Per spec §5: role + aria-expanded live on the editable surface.
+    const input = el.querySelector('[data-input]');
+    expect(input).toBeTruthy();
+    expect(input.getAttribute('role')).toBe('combobox');
+    expect(input.getAttribute('aria-autocomplete')).toBe('list');
+    expect(input.getAttribute('aria-expanded')).toBe('false');
+    expect(input.hasAttribute('aria-controls')).toBe(true);
+    const listbox = el.querySelector('[data-listbox]');
+    expect(listbox).toBeTruthy();
+    expect(listbox.getAttribute('role')).toBe('listbox');
+  });
+
+  it('programmatic .options = [...] re-renders the listbox', async () => {
+    const el = mount(`<combobox-ui></combobox-ui>`);
+    await tick();
+    el.options = [
+      { value: 'a', label: 'Alpha' },
+      { value: 'b', label: 'Beta' },
+    ];
+    await tick();
+    const opts = el.querySelectorAll('[role="option"]');
+    expect(opts.length).toBe(2);
+    expect(opts[0].dataset.value).toBe('a');
+  });
+
+  it('reflects [open] + aria-expanded on the input when opening', async () => {
+    const el = mount(`
+      <combobox-ui>
+        <option value="a">Alpha</option>
+        <option value="b">Beta</option>
+      </combobox-ui>
+    `);
+    await tick();
+    el.open = true;
+    await tick();
+    expect(el.hasAttribute('open')).toBe(true);
+    const input = el.querySelector('[data-input]');
+    expect(input.getAttribute('aria-expanded')).toBe('true');
+  });
+
+  it('selectOption() commits + fires change with the option object', async () => {
+    const el = mount(`
+      <combobox-ui>
+        <option value="a">Alpha</option>
+        <option value="b">Beta</option>
+      </combobox-ui>
+    `);
+    await tick();
+    let changeDetail = null;
+    el.addEventListener('change', (e) => { changeDetail = e.detail; });
+    const hit = el.selectOption('b');
+    expect(hit).toBe(true);
+    await tick();
+    expect(el.value).toBe('b');
+    expect(changeDetail).not.toBeNull();
+    expect(changeDetail.value).toBe('b');
+    expect(changeDetail.option?.value).toBe('b');
+    expect(changeDetail.source).toBe('programmatic');
+  });
+
+  it('selectOption() returns false for an unknown value (no commit)', async () => {
+    const el = mount(`
+      <combobox-ui>
+        <option value="a">Alpha</option>
+      </combobox-ui>
+    `);
+    await tick();
+    let changeCount = 0;
+    el.addEventListener('change', () => { changeCount += 1; });
+    const hit = el.selectOption('zzz');
+    expect(hit).toBe(false);
+    expect(el.value).toBe('');
+    expect(changeCount).toBe(0);
+  });
+
+  it('clear() resets value + fires change with null option', async () => {
+    const el = mount(`
+      <combobox-ui value="a">
+        <option value="a">Alpha</option>
+        <option value="b">Beta</option>
+      </combobox-ui>
+    `);
+    await tick();
+    let changeDetail = null;
+    el.addEventListener('change', (e) => { changeDetail = e.detail; });
+    el.clear();
+    await tick();
+    expect(el.value).toBe('');
+    expect(changeDetail.option).toBeNull();
+  });
+
+  it('renders aria-selected on the currently committed option', async () => {
+    const el = mount(`
+      <combobox-ui value="b">
+        <option value="a">Alpha</option>
+        <option value="b">Beta</option>
+      </combobox-ui>
+    `);
+    await tick();
+    const opts = el.querySelectorAll('[role="option"]');
+    const selected = Array.from(opts).filter((o) => o.getAttribute('aria-selected') === 'true');
+    expect(selected.length).toBe(1);
+    expect(selected[0].dataset.value).toBe('b');
+  });
+
+  it('exposes UICombobox extending UIFormElement (form participation)', async () => {
+    const el = mount(`
+      <combobox-ui name="x">
+        <option value="a">Alpha</option>
+      </combobox-ui>
+    `);
+    await tick();
+    expect(typeof el.checkValidity).toBe('function');
+    expect(typeof el.syncValue).toBe('function');
+  });
+
+  it('disabled options carry aria-disabled and are skipped by [role="option"][not aria-disabled]', async () => {
+    const el = mount(`
+      <combobox-ui>
+        <option value="a">Alpha</option>
+        <option value="b" disabled>Beta</option>
+        <option value="c">Gamma</option>
+      </combobox-ui>
+    `);
+    await tick();
+    const opts = el.querySelectorAll('[role="option"]');
+    expect(opts.length).toBe(3);
+    expect(opts[1].getAttribute('aria-disabled')).toBe('true');
+    const navigable = el.querySelectorAll('[role="option"]:not([aria-disabled="true"])');
+    expect(navigable.length).toBe(2);
+  });
+});