@adia-ai/web-components 0.6.33 → 0.6.35

package/components/combobox/combobox.css

@@ -0,0 +1,244 @@
+@scope (combobox-ui) {
+  :where(:scope) {
+    /* ── Layout ── */
+    --combobox-gap-default:                 var(--a-space-2);
+    --combobox-field-gap-default:           var(--a-space-1);
+    --combobox-height-default:              var(--a-size);
+    --combobox-px-default:                  var(--a-ui-px);
+    --combobox-radius-default:              var(--a-radius);
+
+    /* ── Typography ── */
+    --combobox-font-size-default:           var(--a-ui-size);
+    --combobox-label-size-default:          var(--a-label-size);
+
+    /* ── Colors — field ── */
+    --combobox-bg-default:                  var(--a-ui-bg);
+    --combobox-bg-hover-default:            var(--a-ui-bg-hover);
+    --combobox-border-default:              var(--a-ui-border);
+    --combobox-border-hover-default:        var(--a-ui-border-hover);
+    --combobox-focus-ring-default:          var(--a-focus-ring);
+    --combobox-focus-ring-invalid-default:  var(--a-focus-ring-invalid);
+    --combobox-fg-default:                  var(--a-ui-text);
+    --combobox-fg-muted-default:            var(--a-ui-text-muted);
+    --combobox-fg-subtle-default:           var(--a-ui-text-subtle);
+    --combobox-fg-disabled-default:         var(--a-ui-text-disabled);
+    --combobox-label-fg-default:            var(--a-ui-text-muted);
+    --combobox-placeholder-fg-default:      var(--a-ui-text-placeholder);
+    --combobox-caret-fg-default:            var(--a-ui-text-muted);
+
+    /* ── Transition ── */
+    --combobox-duration-default:            var(--a-duration-fast);
+    --combobox-easing-default:              var(--a-easing);
+
+    /* ── Popover ── */
+    --combobox-popover-bg-default:          var(--a-canvas-bright);
+    --combobox-popover-border-default:      var(--a-ui-border);
+    --combobox-popover-radius-default:      var(--a-radius);
+    --combobox-popover-shadow-default:      var(--a-shadow-lg);
+
+    /* ── Options ── */
+    --combobox-option-px-default:           var(--a-ui-px);
+    --combobox-option-py-default:           var(--a-space-1);
+    --combobox-option-bg-active-default:    var(--a-ui-bg-hover);
+    --combobox-option-fg-active-default:    var(--a-ui-text-hover);
+    --combobox-option-bg-selected-default:  var(--a-ui-bg-selected);
+    --combobox-option-fg-selected-default:  var(--a-ui-text-selected);
+
+    /* ── Match highlight ── */
+    --combobox-match-bg-default:            var(--a-accent-muted);
+    --combobox-match-fg-default:            var(--a-accent-strong);
+
+    text-align: start;  /* §text-align-reset — block ancestor centering */
+  }
+
+  :scope {
+    /* ── Base ── */
+    box-sizing: border-box;
+    display: flex;
+    flex-direction: column;
+    gap: var(--combobox-gap, var(--combobox-gap-default));
+    position: relative;
+    min-width: 0;
+    font-size: var(--combobox-font-size, var(--combobox-font-size-default));
+  }
+
+  :scope[disabled] {
+    pointer-events: none;
+    color: var(--combobox-fg-disabled, var(--combobox-fg-disabled-default));
+    opacity: 0.6;
+  }
+
+  /* ── Label ── */
+  [data-label] {
+    display: block;
+    font-size: var(--combobox-label-size, var(--combobox-label-size-default));
+    color: var(--combobox-label-fg, var(--combobox-label-fg-default));
+  }
+
+  /* ── Field ── */
+  [data-field] {
+    display: flex;
+    align-items: center;
+    gap: var(--combobox-field-gap, var(--combobox-field-gap-default));
+    min-height: var(--combobox-height, var(--combobox-height-default));
+    padding: 0 var(--combobox-px, var(--combobox-px-default));
+    border: 1px solid var(--combobox-border, var(--combobox-border-default));
+    border-radius: var(--combobox-radius, var(--combobox-radius-default));
+    background: var(--combobox-bg, var(--combobox-bg-default));
+    color: var(--combobox-fg, var(--combobox-fg-default));
+    transition:
+      background  var(--combobox-duration, var(--combobox-duration-default)) var(--combobox-easing, var(--combobox-easing-default)),
+      border-color var(--combobox-duration, var(--combobox-duration-default)) var(--combobox-easing, var(--combobox-easing-default)),
+      color       var(--combobox-duration, var(--combobox-duration-default)) var(--combobox-easing, var(--combobox-easing-default)),
+      box-shadow  var(--combobox-duration, var(--combobox-duration-default)) var(--combobox-easing, var(--combobox-easing-default));
+  }
+
+  :scope:not([disabled]) [data-field]:hover {
+    background: var(--combobox-bg-hover, var(--combobox-bg-hover-default));
+    border-color: var(--combobox-border-hover, var(--combobox-border-hover-default));
+  }
+
+  :scope:focus-within [data-field] {
+    box-shadow: var(--combobox-focus-ring, var(--combobox-focus-ring-default));
+  }
+  :scope[aria-invalid="true"]:focus-within [data-field],
+  :scope[error]:focus-within [data-field] {
+    box-shadow: var(--combobox-focus-ring-invalid, var(--combobox-focus-ring-invalid-default));
+  }
+
+  [data-prefix],
+  [data-suffix] {
+    display: inline-flex;
+    align-items: center;
+    flex-shrink: 0;
+    color: var(--combobox-caret-fg, var(--combobox-caret-fg-default));
+    --a-icon-size: var(--combobox-font-size, var(--combobox-font-size-default));
+  }
+  [data-prefix]:empty { display: none; }
+  [data-suffix] {
+    cursor: pointer;
+  }
+
+  [data-input] {
+    flex: 1;
+    min-width: 0;
+    outline: none;
+    background: transparent;
+    color: var(--combobox-fg, var(--combobox-fg-default));
+    font: inherit;
+    font-size: var(--combobox-font-size, var(--combobox-font-size-default));
+    line-height: 1.4;
+    white-space: nowrap;
+    overflow: hidden;
+  }
+  [data-input][data-empty]::before {
+    content: attr(data-placeholder);
+    color: var(--combobox-placeholder-fg, var(--combobox-placeholder-fg-default));
+    pointer-events: none;
+  }
+
+  [data-clear] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    padding: 0;
+    margin: 0;
+    border: 0;
+    background: transparent;
+    color: var(--combobox-fg-muted, var(--combobox-fg-muted-default));
+    cursor: pointer;
+    --a-icon-size: var(--combobox-font-size, var(--combobox-font-size-default));
+  }
+  [data-clear]:hover {
+    color: var(--combobox-fg, var(--combobox-fg-default));
+  }
+}
+
+/* ── Top-layer popover: cannot inherit @scope component tokens ── */
+
+combobox-ui [data-listbox] {
+  margin: 0;
+  padding: var(--a-space-1);
+  border: 1px solid var(--a-ui-border);
+  border-radius: var(--a-radius);
+  background: var(--a-canvas-bright);
+  box-shadow: var(--a-shadow-lg);
+  max-height: 18rem;
+  overflow-y: auto;
+  font-family: inherit;
+  font-size: var(--a-ui-size);
+  color: var(--a-ui-text);
+  width: max-content;
+
+  opacity: 1;
+  translate: 0 0;
+  transition: opacity var(--a-duration-fast) var(--a-easing-out),
+              translate var(--a-duration-fast) var(--a-easing-out);
+}
+
+combobox-ui [data-listbox]:popover-open {
+  @starting-style {
+    opacity: 0;
+    translate: 0 -4px;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  combobox-ui [data-listbox] { transition: none; }
+}
+
+combobox-ui [data-listbox] [role="option"] {
+  display: flex;
+  align-items: center;
+  padding: var(--a-space-1) var(--a-ui-px);
+  border-radius: var(--a-radius-sm);
+  white-space: nowrap;
+  color: var(--a-ui-text-subtle);
+  cursor: pointer;
+  transition:
+    background var(--a-duration-fast) var(--a-easing),
+    color      var(--a-duration-fast) var(--a-easing);
+}
+
+combobox-ui [data-listbox] [role="option"][data-active] {
+  background: var(--a-ui-bg-hover);
+  color: var(--a-ui-text-hover);
+}
+
+combobox-ui [data-listbox] [role="option"][aria-selected="true"] {
+  background: var(--a-ui-bg-selected);
+  color: var(--a-ui-text-selected);
+  font-weight: var(--a-ui-weight);
+}
+
+combobox-ui [data-listbox] [role="option"][aria-disabled="true"] {
+  color: var(--a-ui-text-disabled);
+  cursor: not-allowed;
+}
+
+combobox-ui [data-listbox] [role="option"] mark {
+  background: var(--a-accent-muted);
+  color: var(--a-accent-strong);
+  padding: 0 0.1em;
+  border-radius: var(--a-radius-sm);
+}
+
+combobox-ui [data-listbox] [role="group"] [data-group-label] {
+  padding: var(--a-space-1) var(--a-ui-px);
+  font-size: var(--a-ui-tiny);
+  font-weight: var(--a-ui-weight);
+  color: var(--a-ui-text-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  white-space: nowrap;
+}
+
+combobox-ui [data-empty],
+combobox-ui [data-loading],
+combobox-ui [data-footer] {
+  padding: var(--a-space-2) var(--a-ui-px);
+  color: var(--a-ui-text-muted);
+  font-size: var(--a-ui-size);
+}
+
+combobox-ui [data-footer]:empty { display: none; }

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 './combobox.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);
+  });
+});