@adia-ai/web-components 0.6.34 → 0.6.36

package/components/select/{class.js → select.class.js}

@@ -25,7 +25,9 @@ export class UISelect extends UIFormElement {
   // consumer markup). Aggregated by installIconLoadersForRegistered()
   // across all defined elements. Audited by check-required-icons.mjs
   // (slot 11). Per FEEDBACK-06 §4 + FEEDBACK-07 §4.
-  static requiredIcons = ['caret-up-down'];
+  // SPEC-040: [multiple] mode stamps <tag-ui> chips (own `x`), checkbox
+  // indicator (`check`), and search-input prefix (`magnifying-glass`).
+  static requiredIcons = ['caret-up-down', 'check', 'x', 'magnifying-glass'];
 
   // §225 (v0.5.9, FEEDBACK-10 §3): once-per-element console.warn dedup when
   // consumer authors children that aren't native <option>/<optgroup>. The
@@ -49,6 +51,14 @@ export class UISelect extends UIFormElement {
     // §184 (v0.5.5, FEEDBACK-08 §7): optional caption beneath the
     // trigger, wired to aria-describedby on the host.
     hint:        { type: String,  default: '', reflect: true },
+    // SPEC-040 (multi-select): chip trigger + checkbox list extensions.
+    // These are no-ops without [multiple] but reflect so [maxChips]
+    // selectors etc. work in CSS even when authored declaratively.
+    maxChips:    { type: Number,  default: 0, reflect: true, attribute: 'max-chips' },
+    min:         { type: Number,  default: 0, reflect: true },
+    max:         { type: Number,  default: 0, reflect: true },
+    selectAll:   { type: Boolean, default: false, reflect: true, attribute: 'select-all' },
+    clearable:   { type: Boolean, default: false, reflect: true },
   };
 
   // §184: per-instance hint id counter for aria-describedby wiring.
@@ -77,6 +87,11 @@ export class UISelect extends UIFormElement {
       this.dispatchEvent(new CustomEvent('action', { bubbles: true, detail: { action: opt.action } }));
       return;
     }
+    // SPEC-040 — multi-select: toggle membership without closing popover.
+    if (this.multiple) {
+      this.toggle(opt.value);
+      return;
+    }
     this.value = opt.value;
     this.open = false;
     this.#query = '';
@@ -84,12 +99,237 @@ export class UISelect extends UIFormElement {
     this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
   };
 
+  // SPEC-040 — internal helpers for [multiple] mode.
+
+  /**
+   * Override syncValue to enforce min/max constraints in multi-select mode.
+   * When value.length < min, set form validity to invalid (tooShort).
+   * When value.length > max, set form validity to invalid (tooLong).
+   * Single-select path delegates straight to the base implementation.
+   */
+  syncValue(val) {
+    if (!this.multiple) return super.syncValue(val);
+    const v = val ?? this.value ?? '';
+    this.internals.setFormValue(v);
+    const arr = String(v).split(',').map((s) => s.trim()).filter(Boolean);
+    if (this.min > 0 && arr.length < this.min) {
+      this.internals.setValidity(
+        { tooShort: true },
+        this.getAttribute('data-msg-min') || `Please select at least ${this.min}.`,
+        this,
+      );
+      return;
+    }
+    if (this.max > 0 && arr.length > this.max) {
+      this.internals.setValidity(
+        { tooLong: true },
+        this.getAttribute('data-msg-max') || `Please select no more than ${this.max}.`,
+        this,
+      );
+      return;
+    }
+    if (this.required && arr.length === 0) {
+      this.internals.setValidity(
+        { valueMissing: true },
+        this.getAttribute('data-msg-required') || 'This field is required.',
+        this,
+      );
+      return;
+    }
+    this.internals.setValidity({});
+  }
+
+  /**
+   * Parse the current value as an array of selected ids (multi-select).
+   * Returns an empty array for empty / falsy values.
+   */
+  #values() {
+    if (!this.value) return [];
+    return String(this.value).split(',').map((s) => s.trim()).filter(Boolean);
+  }
+
+  /**
+   * Serialize an array of ids back to the canonical comma-separated form,
+   * de-duplicating in insertion order (Set semantics per SPEC-040 §3).
+   */
+  #serialize(arr) {
+    const seen = new Set();
+    const out = [];
+    for (const v of arr) {
+      if (v == null || v === '') continue;
+      const k = String(v);
+      if (seen.has(k)) continue;
+      seen.add(k);
+      out.push(k);
+    }
+    return out.join(',');
+  }
+
+  /**
+   * Public method (per SPEC-040 §4): toggle one option's selection in
+   * multi-select mode. Single-select callers should set `value` directly.
+   */
+  toggle(id) {
+    if (!this.multiple) {
+      this.value = id;
+      this.syncValue(id);
+      this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
+      return;
+    }
+    const cur = this.#values();
+    const idx = cur.indexOf(String(id));
+    const prev = cur.slice();
+    let added = [];
+    let removed = [];
+    if (idx >= 0) {
+      cur.splice(idx, 1);
+      removed = [String(id)];
+    } else {
+      // SPEC-040 §4 max: suppress toggling past the cap.
+      if (this.max > 0 && cur.length >= this.max) {
+        this.dispatchEvent(new CustomEvent('invalid', {
+          bubbles: true,
+          detail: { value: prev, reason: 'max' },
+        }));
+        return;
+      }
+      cur.push(String(id));
+      added = [String(id)];
+    }
+    const next = this.#serialize(cur);
+    this.value = next;
+    this.syncValue(next);
+    // Re-render listbox aria-selected + chips
+    this.render();
+    this.dispatchEvent(new CustomEvent('change', {
+      bubbles: true,
+      detail: { value: cur, added, removed },
+    }));
+  }
+
+  /**
+   * Public method (SPEC-040 §4): select every non-disabled option.
+   */
+  selectAllOptions() {
+    if (!this.multiple) return;
+    const flat = this.#options.flatMap((o) => o.options || [o]).filter((o) => !o.disabled && !o.separator && !o.header && o.value != null);
+    const next = this.#serialize(flat.map((o) => o.value));
+    if (next === this.value) return;
+    const prev = this.#values();
+    this.value = next;
+    this.syncValue(next);
+    this.render();
+    const nextArr = this.#values();
+    const added = nextArr.filter((v) => !prev.includes(v));
+    this.dispatchEvent(new CustomEvent('change', {
+      bubbles: true,
+      detail: { value: nextArr, added, removed: [] },
+    }));
+  }
+
+  /**
+   * Public method (SPEC-040 §4): clear all selections.
+   */
+  clear() {
+    if (!this.multiple) {
+      this.value = '';
+      this.syncValue('');
+      this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: '' } }));
+      return;
+    }
+    const prev = this.#values();
+    if (prev.length === 0) return;
+    this.value = '';
+    this.syncValue('');
+    this.render();
+    this.dispatchEvent(new CustomEvent('change', {
+      bubbles: true,
+      detail: { value: [], added: [], removed: prev },
+    }));
+  }
+
+  /**
+   * Internal: remove the last chip (Backspace handling).
+   */
+  #removeLastChip() {
+    const cur = this.#values();
+    if (cur.length === 0) return;
+    const removed = cur.pop();
+    const next = this.#serialize(cur);
+    this.value = next;
+    this.syncValue(next);
+    this.render();
+    this.dispatchEvent(new CustomEvent('change', {
+      bubbles: true,
+      detail: { value: cur, added: [], removed: [removed] },
+    }));
+  }
+
+  /**
+   * Internal: handler for tag-ui `remove` events bubbling out of chips.
+   */
+  #onChipRemove = (e) => {
+    if (!this.multiple) return;
+    const target = e.target;
+    if (!target || target.tagName !== 'TAG-UI') return;
+    const id = target.dataset.chipValue;
+    if (!id) return;
+    e.stopPropagation();
+    // `tag-ui` already removes itself from the DOM; rebuild value as a
+    // single source of truth and re-stamp.
+    const cur = this.#values().filter((v) => v !== id);
+    const next = this.#serialize(cur);
+    this.value = next;
+    this.syncValue(next);
+    this.render();
+    this.dispatchEvent(new CustomEvent('change', {
+      bubbles: true,
+      detail: { value: cur, added: [], removed: [id] },
+    }));
+  };
+
+  /**
+   * Internal: handler for the "+N more" pill click — opens the popover.
+   */
+  #onMoreClick = (e) => {
+    e.stopPropagation();
+    if (this.disabled) return;
+    this.open = true;
+  };
+
+  /**
+   * Internal: handler for the clear-all `x` on the trigger.
+   */
+  #onClearAllClick = (e) => {
+    e.stopPropagation();
+    if (this.disabled || this.readonly) return;
+    this.clear();
+  };
+
+  /**
+   * Internal: handler for the "Select all" / "Clear" header button.
+   */
+  #onSelectAllClick = (e) => {
+    e.stopPropagation();
+    if (this.disabled || this.readonly) return;
+    const flat = this.#options.flatMap((o) => o.options || [o]).filter((o) => !o.disabled && !o.separator && !o.header && o.value != null);
+    const allIds = flat.map((o) => String(o.value));
+    const cur = new Set(this.#values());
+    const everyone = allIds.length > 0 && allIds.every((id) => cur.has(id));
+    if (everyone) this.clear();
+    else this.selectAllOptions();
+  };
+
   connected() {
     super.connected();
     this.setAttribute('role', 'combobox');
     this.setAttribute('tabindex', '0');
     this.addEventListener('click', this.#onClick);
     this.addEventListener('keydown', this.#onKey);
+    // SPEC-040: trap `remove` events from chip tag-ui children so the host
+    // value array stays the single source of truth. Bubbles, so we
+    // capture them at the host level — no per-chip wiring needed.
+    this.addEventListener('remove', this.#onChipRemove);
     // Only parse declarative <option>/<optgroup> children if options
     // weren't already set programmatically (e.g. via .options = [...])
     if (this.#options.length === 0) {
@@ -98,6 +338,13 @@ export class UISelect extends UIFormElement {
   }
 
   render() {
+    // SPEC-040 — in multi-select mode the trigger needs to host chips +
+    // optional clear-x + optional "+N more" pill alongside the usual
+    // leading / display / caret. We toggle host attribute [data-multi-chips]
+    // so CSS can switch layout from single-line text to flex-wrap chip row.
+    if (this.multiple) this.setAttribute('data-multi-chips', '');
+    else this.removeAttribute('data-multi-chips');
+
     // Stamp default trigger if none provided
     if (!this.querySelector('[slot="trigger"]')) {
       // Detach listbox before innerHTML wipe so it isn't destroyed
@@ -118,16 +365,31 @@ export class UISelect extends UIFormElement {
       // but not the rendering until this arc).
       const hintId = this.hint ? `select-hint-${++UISelect.#hintSeq}` : '';
       const hintMarkup = this.hint ? `<span slot="hint" id="${hintId}">${escapeHTML(this.hint)}</span>` : '';
+      // SPEC-040 — trigger needs a [data-chips] slot we can stamp tag-ui
+      // into in multi-select mode. The chip row sits BEFORE [slot="display"]
+      // so the display (placeholder or search input) renders inline at the
+      // end of the chips, matching standard multi-select UX.
       this.innerHTML = `
         <span slot="trigger">
           ${leading}
+          <span data-chips></span>
           ${displayMarkup}
+          <button type="button" data-clear-all aria-label="Clear all" hidden>
+            <icon-ui name="x"></icon-ui>
+          </button>
           <icon-ui name="caret-up-down" slot="caret"></icon-ui>
         </span>
         ${hintMarkup}
       `;
       if (this.hint) this.setAttribute('aria-describedby', hintId);
 
+      // Wire clear-all click once per stamp.
+      const clearBtn = this.querySelector('[data-clear-all]');
+      if (clearBtn) {
+        clearBtn.removeEventListener('click', this.#onClearAllClick);
+        clearBtn.addEventListener('click', this.#onClearAllClick);
+      }
+
       if (this.searchable) {
         // Detach from previous search input if any
         if (this.#searchInput) {
@@ -147,16 +409,38 @@ export class UISelect extends UIFormElement {
       if (lb) this.appendChild(lb);
     } else {
       const display = this.querySelector('[slot="display"]');
-      if (display) {
+      if (display && !this.multiple) {
+        // Single-select: keep the canonical text-rendering path.
         if (display.tagName === 'INPUT') {
           // Only update value when not actively editing (no active query)
           if (!this.#query) display.value = this.#displayText() === this.placeholder ? '' : this.#displayText();
         } else {
           display.textContent = this.#displayText();
         }
+      } else if (display && this.multiple) {
+        // Multi-select: display element holds the placeholder ONLY when
+        // no chips are present (otherwise the chip row IS the display).
+        const hasChips = this.#values().length > 0;
+        if (display.tagName === 'INPUT') {
+          // search input — keep placeholder; never inject the value text.
+          display.placeholder = hasChips ? '' : (this.placeholder || '');
+          if (!this.#query) display.value = '';
+        } else {
+          display.textContent = hasChips ? '' : (this.placeholder || '');
+        }
       }
     }
 
+    // SPEC-040 — stamp / reconcile chips + "+N more" pill on every render.
+    if (this.multiple) this.#stampChips();
+    // Show clear-all only in multi-select mode when [clearable] + chips present.
+    const clearBtn = this.querySelector('[data-clear-all]');
+    if (clearBtn) {
+      const show = this.multiple && this.clearable && this.#values().length > 0 && !this.disabled && !this.readonly;
+      if (show) clearBtn.removeAttribute('hidden');
+      else clearBtn.setAttribute('hidden', '');
+    }
+
     // Ensure listbox exists (regardless of trigger source)
     if (!this.#listbox) {
       this.#listbox = this.querySelector('[slot="listbox"]');
@@ -295,6 +579,24 @@ export class UISelect extends UIFormElement {
     if (!this.#listbox) return;
     this.#listbox.innerHTML = '';
 
+    // SPEC-040 — multi-select listbox is aria-multiselectable; checkbox
+    // indicator on each option row marks selection visually.
+    if (this.multiple) this.#listbox.setAttribute('aria-multiselectable', 'true');
+    else this.#listbox.removeAttribute('aria-multiselectable');
+
+    // SPEC-040 — Select-all / Clear control row at the top of the list.
+    if (this.multiple && this.selectAll) {
+      const header = document.createElement('div');
+      header.setAttribute('data-select-all', '');
+      const btn = document.createElement('button');
+      btn.type = 'button';
+      btn.dataset.selectAllBtn = '';
+      btn.textContent = this.#allSelected() ? 'Clear' : 'Select all';
+      btn.addEventListener('click', this.#onSelectAllClick);
+      header.appendChild(btn);
+      this.#listbox.appendChild(header);
+    }
+
     const renderOpt = (opt) => {
       if (opt.separator) {
         const hr = document.createElement('hr');
@@ -304,13 +606,31 @@ export class UISelect extends UIFormElement {
       const el = document.createElement('div');
       el.setAttribute('role', 'option');
       el.setAttribute('data-value', opt.value || '');
-      if (opt.icon) el.innerHTML = `<icon-ui name="${escapeHTML(opt.icon)}"></icon-ui>${escapeHTML(opt.label)}`;
-      else el.textContent = opt.label;
       // §FB-46: [multiple] value is comma-separated — use Set membership.
       const selSet = this.multiple
         ? new Set(this.value.split(',').map((s) => s.trim()).filter(Boolean))
         : null;
-      if (selSet ? selSet.has(opt.value) : opt.value === this.value) el.setAttribute('aria-selected', 'true');
+      const isSelected = selSet ? selSet.has(opt.value) : opt.value === this.value;
+      // SPEC-040 — multi-select option rows render a leading checkbox
+      // indicator (CSS-driven via [data-multi-option]); the `check` icon
+      // shows when aria-selected="true".
+      if (this.multiple) {
+        el.setAttribute('data-multi-option', '');
+        const box = document.createElement('span');
+        box.setAttribute('data-checkbox', '');
+        box.innerHTML = '<icon-ui name="check" aria-hidden="true"></icon-ui>';
+        el.appendChild(box);
+        const label = document.createElement('span');
+        label.setAttribute('data-option-label', '');
+        if (opt.icon) label.innerHTML = `<icon-ui name="${escapeHTML(opt.icon)}"></icon-ui>${escapeHTML(opt.label)}`;
+        else label.textContent = opt.label;
+        el.appendChild(label);
+      } else if (opt.icon) {
+        el.innerHTML = `<icon-ui name="${escapeHTML(opt.icon)}"></icon-ui>${escapeHTML(opt.label)}`;
+      } else {
+        el.textContent = opt.label;
+      }
+      if (isSelected) el.setAttribute('aria-selected', 'true');
       if (opt.disabled) el.setAttribute('aria-disabled', 'true');
       if (opt.action) el.dataset.action = opt.action;
       el.__adiaOption = opt;
@@ -338,10 +658,78 @@ export class UISelect extends UIFormElement {
         this.#listbox.appendChild(renderOpt(item));
       }
     }
+
+    // SPEC-040 — empty-state stamp when there are no consumer options.
+    if (this.#options.length === 0) {
+      const empty = document.createElement('div');
+      empty.setAttribute('data-empty', '');
+      empty.textContent = 'No options';
+      this.#listbox.appendChild(empty);
+    }
+
     if (this.#query) this.#applyFilter();
   }
 
+  /**
+   * SPEC-040 — returns true when every non-disabled option is currently
+   * selected. Used by the Select-all header to flip its label to "Clear".
+   */
+  #allSelected() {
+    if (!this.multiple) return false;
+    const flat = this.#options.flatMap((o) => o.options || [o])
+      .filter((o) => !o.disabled && !o.separator && !o.header && o.value != null);
+    if (flat.length === 0) return false;
+    const cur = new Set(this.#values());
+    return flat.every((o) => cur.has(String(o.value)));
+  }
+
+  /**
+   * SPEC-040 — reconcile the trigger chip row against the current value.
+   * Tag-ui children carry [data-chip-value] so we can identify which chip
+   * fired a `remove` event without re-parsing labels.
+   */
+  #stampChips() {
+    const slot = this.querySelector('[slot="trigger"] [data-chips]');
+    if (!slot) return;
+    const values = this.#values();
+    const cap = Number(this.maxChips) || 0;
+    const cappedValues = cap > 0 && values.length > cap ? values.slice(0, cap) : values;
+    const overflow = cap > 0 && values.length > cap ? values.length - cap : 0;
+    // Label lookup from internal options model (handles grouped form too).
+    const flat = this.#options.flatMap((o) => o.options || [o])
+      .filter((o) => !o.separator && !o.header && o.value != null);
+    const labelOf = (v) => {
+      const found = flat.find((o) => String(o.value) === String(v));
+      return found ? found.label : String(v);
+    };
+    // Rebuild — chips are cheap and reconciliation gets us correct order
+    // + correct labels with no per-chip tracking state.
+    while (slot.firstChild) slot.removeChild(slot.firstChild);
+    for (const v of cappedValues) {
+      const tag = document.createElement('tag-ui');
+      tag.setAttribute('size', 'sm');
+      // Only show the dismiss `x` when interactive (matches [disabled]/[readonly] gating).
+      if (!this.disabled && !this.readonly) tag.setAttribute('removable', '');
+      tag.dataset.chipValue = String(v);
+      tag.setAttribute('text', labelOf(v));
+      slot.appendChild(tag);
+    }
+    if (overflow > 0) {
+      const more = document.createElement('button');
+      more.type = 'button';
+      more.dataset.more = '';
+      more.textContent = `+${overflow} more`;
+      more.addEventListener('click', this.#onMoreClick);
+      slot.appendChild(more);
+    }
+  }
+
   #displayText() {
+    if (this.multiple) {
+      // SPEC-040 — chips render the selection; display element holds the
+      // placeholder when empty and is otherwise empty (CSS sees [data-multi-chips]).
+      return this.value ? '' : this.placeholder;
+    }
     const flat = this.#options.flatMap(o => o.options || [o]);
     const selected = flat.find(o => o.value === this.value || (o.header && o.label === this.value));
     return selected?.label || this.value || this.placeholder;
@@ -362,6 +750,22 @@ export class UISelect extends UIFormElement {
   };
 
   #onKey = (e) => {
+    // SPEC-040 — Backspace from the trigger removes the last chip.
+    // Two paths: (1) trigger focused, no search input — straight Backspace.
+    // (2) search input focused with empty query — Backspace removes a chip
+    // before it would start removing query characters.
+    if (e.key === 'Backspace' && this.multiple && !this.disabled && !this.readonly) {
+      const target = e.target;
+      const fromInput = target && target.tagName === 'INPUT' && target.getAttribute('slot') === 'display';
+      const queryEmpty = !this.#query || this.#query.length === 0;
+      if (!fromInput || queryEmpty) {
+        if (this.#values().length > 0) {
+          e.preventDefault();
+          this.#removeLastChip();
+          return;
+        }
+      }
+    }
     if (e.key === 'Escape') {
       if (this.searchable && this.#query) {
         // First Escape: clear query
@@ -380,6 +784,10 @@ export class UISelect extends UIFormElement {
         const focused = this.#listbox?.querySelector('[role="option"][data-focused]:not([data-filtered-out])');
         if (focused) {
           focused.click();
+          // SPEC-040 — Enter in multi-select commits + closes (matches the
+          // WAI-APG commit pattern). #onOptionClick keeps the popover open
+          // on plain clicks; Enter is the explicit commit.
+          if (this.multiple) this.open = false;
         } else if (this.searchable && this.freeText && this.#query) {
           // Commit free-text
           const q = this.#query;
@@ -401,7 +809,7 @@ export class UISelect extends UIFormElement {
       if (this.open) {
         const focused = this.#listbox?.querySelector('[role="option"][data-focused]');
         if (focused) focused.click();
-        else this.open = false;
+        else if (!this.multiple) this.open = false;
       } else {
         this.open = true;
       }
@@ -470,6 +878,7 @@ export class UISelect extends UIFormElement {
     super.disconnected();
     this.removeEventListener('click', this.#onClick);
     this.removeEventListener('keydown', this.#onKey);
+    this.removeEventListener('remove', this.#onChipRemove);
     if (this.#rafId != null) {
       cancelAnimationFrame(this.#rafId);
       this.#rafId = null;