@adia-ai/web-components 0.8.37 → 0.8.38

package/components/drilldown/drilldown.class.js

@@ -0,0 +1,542 @@
+/**
+ * Non-side-effect class export for `<drilldown-ui>`.
+ *
+ * Importing this file gives you the class without auto-registering the tag.
+ * Useful for test isolation, subclassing with tag-name override, or selective
+ * composition.
+ *
+ * The auto-register path stays at `@adia-ai/web-components/components/drilldown`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { UIElement, untracked } from '../../core/element.js';
+
+/**
+ * <drilldown-ui> — Single-panel, multi-level drill-in menu.
+ *
+ * Data-driven, content-only primitive (gh#1285) — set `.items` to a tree of
+ * `{value, label, meta?, dot?, counts?, children?, leaf?}` nodes; `children`
+ * may be a sync array or a `(item) => array | Promise<array>` lazy loader.
+ *
+ * Events:
+ *   select   — leaf activation (or branch activation with [select-on-drill]).
+ *              detail: { path, item }
+ *   navigate — the shown level changed (drill / back / jump / `.path` set).
+ *              detail: { path }
+ */
+export class UIDrilldown extends UIElement {
+  static requiredIcons = ['caret-left', 'caret-right', 'magnifying-glass'];
+
+  static properties = {
+    rootLabel:    { type: String,  default: '',   reflect: true, attribute: 'root-label' },
+    filterable:   { type: Boolean, default: false, reflect: true },
+    placeholder:  { type: String,  default: 'Filter…', reflect: true },
+    selectOnDrill:{ type: Boolean, default: false, reflect: true, attribute: 'select-on-drill' },
+    static:       { type: Boolean, default: false, reflect: true },
+  };
+
+  // `path` is deliberately NOT in `static properties` (mirrors `items`,
+  // below — `dynamic: true` in the yaml, `audit-static-properties-vs-yaml`
+  // exempted): array values need real JSON encode/decode, which the
+  // generic reflect() helper can't do (it falls back to `String(v)` —
+  // a lossy comma-join — for anything that isn't Boolean). `path` still
+  // genuinely reflects to the `path` attribute — hand-rolled below via
+  // `static get observedAttributes()` + `attributeChangedCallback()` —
+  // it just doesn't route through the declarative property system.
+  static get observedAttributes() {
+    return [...super.observedAttributes, 'path'];
+  }
+
+  static template = () => null;
+
+  // ── Data ──
+  #items = [];
+  #childrenCache = new WeakMap();  // resolved-children-array, keyed by item object
+  #pendingLoads = new WeakMap();   // in-flight Promise, keyed by item object
+  #drillFrom = [];                 // per-depth: the value that was drilled FROM (for back-focus restore)
+  #filterQuery = '';
+
+  // ── DOM refs (stamped once) ──
+  #stamped = false;
+  #backBtn = null;
+  #backLabelEl = null;
+  #titleEl = null;
+  #countEl = null;
+  #filterRowEl = null;
+  #filterInputEl = null;
+  #panelEl = null;
+  #liveEl = null;
+  #breadcrumbEl = null;
+  #rowByEl = new WeakMap();
+  #activeValue = null;
+  #focusOnNextRender = null;       // 'first' | { restoreValue } | null
+  #path = [];                      // current drilled-in level (array of ancestor values)
+  #applyingPathAttr = false;       // re-entrancy guard: our own setAttribute('path', …) below
+
+  // ── Public data prop (mirrors command-ui's `.options` — JS-only, not
+  // reflected: object-array values don't round-trip through attributes) ──
+
+  get items() { return this.#items; }
+  set items(list) {
+    this.#items = Array.isArray(list) ? list : [];
+    this.#childrenCache = new WeakMap();
+    this.#pendingLoads = new WeakMap();
+    if (this.#stamped) this.#renderLevel(null);
+  }
+
+  // ── Public `path` accessor — hand-rolled JSON attribute reflection
+  // (see the `static get observedAttributes()` note above `static
+  // properties`). Setting `.path` is fully synchronous: it updates
+  // internal state, reflects the attribute, and re-renders the level
+  // in the SAME call — no dependency on the signals-effect scheduler,
+  // so `#focusOnNextRender` (set by `#drillInto()`/`back()` immediately
+  // before assigning `.path`) is always consumed by the render its own
+  // assignment triggers. ──
+
+  get path() { return [...this.#path]; }
+  set path(arr) {
+    this.#setPath(Array.isArray(arr) ? arr.map(String) : [], false);
+  }
+
+  #setPath(next, fromAttribute) {
+    const prev = this.#path;
+    const pathChanged = prev.length !== next.length || next.some((v, i) => v !== prev[i]);
+    let direction = null;
+    if (pathChanged) {
+      if (next.length > prev.length && prev.every((v, i) => v === next[i])) direction = 'forward';
+      else if (prev.length > next.length && next.every((v, i) => v === prev[i])) direction = 'backward';
+    }
+    this.#path = next;
+
+    if (!fromAttribute) {
+      this.#applyingPathAttr = true;
+      if (next.length) this.setAttribute('path', JSON.stringify(next));
+      else this.removeAttribute('path');
+      this.#applyingPathAttr = false;
+    }
+
+    if (this.#stamped) {
+      this.#renderLevel(direction);
+      if (pathChanged) {
+        this.dispatchEvent(new CustomEvent('navigate', { bubbles: true, detail: { path: [...next] } }));
+      }
+    }
+  }
+
+  attributeChangedCallback(name, oldVal, newVal) {
+    if (name === 'path') {
+      if (this.#applyingPathAttr) return;
+      let parsed = [];
+      try {
+        const p = JSON.parse(newVal ?? '[]');
+        if (Array.isArray(p)) parsed = p.map(String);
+      } catch { /* malformed — treat as empty path */ }
+      this.#setPath(parsed, true);
+      return;
+    }
+    super.attributeChangedCallback(name, oldVal, newVal);
+  }
+
+  connected() {
+    this.setAttribute('role', 'group');
+    this.addEventListener('keydown', this.#onKeydown);
+    // gh#284-style upgrade replay: a `path` attribute present BEFORE
+    // upgrade isn't guaranteed to have replayed attributeChangedCallback
+    // in every DOM shim (see element.js's own identical rationale for
+    // its declared-property pre-sync loop, which does not cover `path`
+    // since it isn't in `static properties`). Sync explicitly here.
+    if (this.hasAttribute('path')) {
+      let parsed = [];
+      try {
+        const p = JSON.parse(this.getAttribute('path') ?? '[]');
+        if (Array.isArray(p)) parsed = p.map(String);
+      } catch { /* malformed — treat as empty path */ }
+      this.#path = parsed;
+    }
+  }
+
+  render() {
+    if (!this.#stamped) this.#stamp();
+    this.#renderLevel(null);
+  }
+
+  disconnected() {
+    this.removeEventListener('keydown', this.#onKeydown);
+    this.#filterInputEl?.removeEventListener('input', this.#onFilterInput);
+    this.#backBtn?.removeEventListener('click', this.#onBackClick);
+    this.#panelEl?.removeEventListener('click', this.#onPanelClick);
+    this.#panelEl = null;
+    this.#filterInputEl = null;
+    this.#backBtn = null;
+    this.#backLabelEl = null;
+    this.#titleEl = null;
+    this.#countEl = null;
+    this.#filterRowEl = null;
+    this.#liveEl = null;
+    this.#breadcrumbEl = null;
+  }
+
+  // ── Structural stamp (once) ──
+
+  #stamp() {
+    this.innerHTML = `
+      <div slot="header">
+        <button-ui slot="back" icon="caret-left" variant="ghost" size="sm" hidden>
+          <span data-back-label></span>
+        </button-ui>
+        <div slot="breadcrumb"></div>
+        <div slot="title">
+          <span data-level-title></span>
+          <span data-level-count></span>
+        </div>
+      </div>
+      <div slot="filter" hidden>
+        <icon-ui name="magnifying-glass"></icon-ui>
+        <input type="text" />
+      </div>
+      <div slot="viewport">
+        <div slot="panel" role="listbox"></div>
+      </div>
+      <div slot="live" aria-live="polite" data-visually-hidden></div>
+    `;
+
+    this.#backBtn = this.querySelector('[slot="back"]');
+    this.#backLabelEl = this.querySelector('[data-back-label]');
+    this.#titleEl = this.querySelector('[data-level-title]');
+    this.#countEl = this.querySelector('[data-level-count]');
+    this.#filterRowEl = this.querySelector('[slot="filter"]');
+    this.#filterInputEl = this.querySelector('[slot="filter"] input');
+    this.#panelEl = this.querySelector('[slot="panel"]');
+    this.#liveEl = this.querySelector('[slot="live"]');
+    this.#breadcrumbEl = this.querySelector('[slot="breadcrumb"]');
+
+    // Adopt a consumer-supplied [slot="breadcrumb"] child (static markup —
+    // not an interpolated collection, so a direct querySelector is safe;
+    // mirrors the `wrapper-trap-ok` carve-out documented in tree.class.js).
+    const declaredBreadcrumb = [...this.children].find(
+      (el) => el.getAttribute('slot') === 'breadcrumb' && el.parentElement === this,
+    );
+    if (declaredBreadcrumb && declaredBreadcrumb !== this.#breadcrumbEl) {
+      this.#breadcrumbEl.replaceWith(declaredBreadcrumb);
+      this.#breadcrumbEl = declaredBreadcrumb;
+    }
+
+    this.#backBtn.addEventListener('click', this.#onBackClick);
+    this.#filterInputEl.addEventListener('input', this.#onFilterInput);
+    this.#panelEl.addEventListener('click', this.#onPanelClick);
+    this.#stamped = true;
+  }
+
+  // ── Prop-driven chrome sync (filterable / placeholder) — cheap, run every render() ──
+
+  #syncChrome() {
+    this.#filterRowEl.hidden = !this.filterable;
+    this.#filterInputEl.placeholder = this.placeholder;
+  }
+
+  // ── Tree walking ──
+
+  #findChild(list, value) {
+    return (list || []).find((it) => String(it.value) === String(value)) || null;
+  }
+
+  /** Resolve `item.children` to an array, or `'loading'`/`'pending'` sentinel. */
+  #resolveChildren(item) {
+    if (!item || item.leaf) return [];
+    const raw = item.children;
+    if (raw == null) return [];
+    if (Array.isArray(raw)) return raw;
+    if (typeof raw === 'function') {
+      if (this.#childrenCache.has(item)) return this.#childrenCache.get(item);
+      if (this.#pendingLoads.has(item)) return 'loading';
+      let result;
+      try {
+        result = raw(item);
+      } catch {
+        result = [];
+      }
+      if (result && typeof result.then === 'function') {
+        this.#pendingLoads.set(item, result);
+        result.then((resolved) => {
+          this.#pendingLoads.delete(item);
+          this.#childrenCache.set(item, Array.isArray(resolved) ? resolved : []);
+          this.#renderLevel(null);
+        }).catch(() => {
+          this.#pendingLoads.delete(item);
+          this.#childrenCache.set(item, []);
+          this.#renderLevel(null);
+        });
+        return 'loading';
+      }
+      const resolved = Array.isArray(result) ? result : [];
+      this.#childrenCache.set(item, resolved);
+      return resolved;
+    }
+    return [];
+  }
+
+  #hasChildren(item) {
+    if (!item || item.leaf) return false;
+    if (Array.isArray(item.children)) return item.children.length > 0;
+    return typeof item.children === 'function';
+  }
+
+  /** Walk `#items` through `path`, returning { item, list } for the current level. `item` is null at root. */
+  #resolveLevel(path) {
+    let list = this.#items;
+    let item = null;
+    for (const value of path) {
+      item = this.#findChild(list, value);
+      if (!item) return { item: null, list: [] };
+      const children = this.#resolveChildren(item);
+      list = children === 'loading' ? 'loading' : children;
+      if (list === 'loading') return { item, list: 'loading' };
+    }
+    return { item, list };
+  }
+
+  // ── Render current level ──
+
+  #renderLevel(direction) {
+    if (!this.#stamped) return;
+    // untracked: this rebuilds the row DOM from scratch on every call,
+    // creating fresh icon-ui/skeleton-ui/empty-state-ui children each
+    // time. render() (the caller) runs inside the base class's tracked
+    // effect WITHOUT an untracked() wrap (only connected() gets one) —
+    // a child's own reactive-property reads/writes during its
+    // synchronous connectedCallback would otherwise be attributed to
+    // THIS effect, and recreating that same child on every subsequent
+    // render re-triggers it, oscillating (the signals drain-loop guard
+    // traps exactly this shape — see element.js's own identical
+    // rationale for wrapping connected()).
+    untracked(() => this.#renderLevelImpl(direction));
+  }
+
+  #renderLevelImpl(direction) {
+    this.#syncChrome();
+
+    const path = this.path;
+    const { item: currentItem, list } = this.#resolveLevel(path);
+
+    // Header
+    const title = currentItem ? (currentItem.label ?? '') : (this.rootLabel || '');
+    this.#titleEl.textContent = title;
+    this.#backBtn.hidden = path.length === 0;
+    if (path.length > 0) {
+      const { item: parentItem } = this.#resolveLevel(path.slice(0, -1));
+      this.#backLabelEl.textContent = parentItem ? (parentItem.label ?? '') : (this.rootLabel || '');
+    }
+
+    const loading = list === 'loading';
+    const items = loading ? [] : list;
+    const q = this.#filterQuery.trim().toLowerCase();
+    const visible = q
+      ? items.filter((it) =>
+          (it.label || '').toLowerCase().includes(q) ||
+          (it.meta || '').toLowerCase().includes(q))
+      : items;
+
+    this.#countEl.textContent = loading ? '' : String(items.length);
+
+    // Body
+    this.#panelEl.setAttribute('aria-busy', String(loading));
+    this.#panelEl.setAttribute('aria-label', title || 'Items');
+    this.#panelEl.innerHTML = '';
+    this.#panelEl.removeAttribute('data-anim');
+
+    if (loading) {
+      for (let i = 0; i < 4; i++) {
+        const sk = document.createElement('skeleton-ui');
+        sk.setAttribute('height', '2.25rem');
+        sk.setAttribute('data-drilldown-skeleton', '');
+        this.#panelEl.appendChild(sk);
+      }
+    } else if (!visible.length) {
+      const empty = document.createElement('empty-state-ui');
+      empty.setAttribute('minimal', '');
+      empty.setAttribute('heading', q ? 'No matches' : 'No items');
+      this.#panelEl.appendChild(empty);
+    } else {
+      for (const it of visible) this.#panelEl.appendChild(this.#createRow(it));
+    }
+
+    if (!this.static) {
+      if (direction === 'forward') this.#panelEl.setAttribute('data-anim', 'forward');
+      else if (direction === 'backward') this.#panelEl.setAttribute('data-anim', 'backward');
+    }
+
+    // Focus handling — the row list is rebuilt from scratch above, so even
+    // an unchanged `#activeValue` needs its tabindex reasserted on the
+    // FRESH node (a persisted value match is not the same DOM element).
+    const rows = [...this.#panelEl.querySelectorAll('[role="option"]')];
+    if (this.#focusOnNextRender === 'first' && rows[0]) {
+      this.#activate(rows[0]);
+      rows[0].focus();
+    } else if (this.#focusOnNextRender && this.#focusOnNextRender.restoreValue != null) {
+      const target = rows.find((r) => r.dataset.value === String(this.#focusOnNextRender.restoreValue));
+      if (target) {
+        this.#activate(target);
+        target.focus();
+      } else if (rows[0]) {
+        this.#activate(rows[0]);
+      }
+    } else {
+      const keep = rows.find((r) => r.dataset.value === this.#activeValue);
+      if (keep) this.#activate(keep);
+      else if (rows[0]) this.#activate(rows[0]);
+    }
+    this.#focusOnNextRender = null;
+
+    // aria-live announcement
+    const count = loading ? '' : ` — ${items.length} item${items.length === 1 ? '' : 's'}`;
+    this.#liveEl.textContent = `${title || 'Root'}${count}`;
+  }
+
+  #escAttr(s) {
+    return String(s ?? '').replace(/"/g, '&quot;');
+  }
+  #escText(s) {
+    return String(s ?? '')
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;');
+  }
+
+  #createRow(item) {
+    const hasChildren = this.#hasChildren(item);
+    const row = document.createElement('div');
+    row.setAttribute('role', 'option');
+    row.setAttribute('tabindex', '-1');
+    row.setAttribute('aria-selected', 'false');
+    row.dataset.value = String(item.value);
+    if (!hasChildren) row.setAttribute('data-leaf', '');
+
+    let html = '';
+    if (item.dot) {
+      html += `<span slot="dot" data-tone="${this.#escAttr(item.dot)}"></span>`;
+    }
+    html += `<div slot="main"><span slot="label">${this.#escText(item.label)}</span>`;
+    if (item.meta) html += `<span slot="meta">${this.#escText(item.meta)}</span>`;
+    html += `</div>`;
+    const counts = Array.isArray(item.counts) ? item.counts : [];
+    if (counts.length) {
+      html += `<span slot="counts">${counts
+        .map((c) => `<span data-count-chip data-tone="${this.#escAttr(c.variant || 'neutral')}">${this.#escText(c.value)}</span>`)
+        .join('')}</span>`;
+    }
+    if (hasChildren) html += `<icon-ui name="caret-right" slot="chevron"></icon-ui>`;
+    row.innerHTML = html;
+
+    this.#rowByEl.set(row, item);
+    return row;
+  }
+
+  // ── Roving tabindex ──
+
+  #activate(row) {
+    const prev = this.#panelEl.querySelector('[role="option"][tabindex="0"]');
+    if (prev && prev !== row) prev.setAttribute('tabindex', '-1');
+    row.setAttribute('tabindex', '0');
+    this.#activeValue = row.dataset.value;
+  }
+
+  #moveActive(dir) {
+    const rows = [...this.#panelEl.querySelectorAll('[role="option"]')];
+    if (!rows.length) return;
+    const current = this.#panelEl.querySelector('[role="option"][tabindex="0"]');
+    let idx = current ? rows.indexOf(current) : -1;
+    idx = (idx + dir + rows.length) % rows.length;
+    this.#activate(rows[idx]);
+    rows[idx].focus();
+  }
+
+  // ── Navigation actions ──
+
+  #drillInto(item) {
+    const path = this.path;
+    this.#drillFrom[path.length] = item.value;
+    this.#focusOnNextRender = 'first';
+    this.path = [...path, item.value];
+  }
+
+  back() {
+    const path = this.path;
+    if (!path.length) return;
+    const restoreValue = this.#drillFrom[path.length - 1];
+    this.#focusOnNextRender = { restoreValue };
+    this.path = path.slice(0, -1);
+  }
+
+  #fireSelect(item) {
+    this.dispatchEvent(new CustomEvent('select', {
+      bubbles: true,
+      detail: { path: this.path, item },
+    }));
+  }
+
+  #activateItem(item) {
+    const hasChildren = this.#hasChildren(item);
+    if (!hasChildren) {
+      this.#fireSelect(item);
+      return;
+    }
+    if (this.selectOnDrill) this.#fireSelect(item);
+    this.#drillInto(item);
+  }
+
+  // ── Event handlers (stable bound arrows — symmetric add/remove) ──
+
+  #onBackClick = () => this.back();
+
+  #onFilterInput = () => {
+    this.#filterQuery = this.#filterInputEl.value;
+    this.#renderLevel(null);
+  };
+
+  #onPanelClick = (e) => {
+    const row = e.target instanceof Element ? e.target.closest('[role="option"]') : null;
+    if (!row) return;
+    const item = this.#rowByEl.get(row);
+    if (!item) return;
+    this.#activate(row);
+    this.#activateItem(item);
+  };
+
+  #onKeydown = (e) => {
+    const row = e.target instanceof Element ? e.target.closest('[role="option"]') : null;
+    switch (e.key) {
+      case 'ArrowDown':
+        e.preventDefault();
+        this.#moveActive(1);
+        break;
+      case 'ArrowUp':
+        e.preventDefault();
+        this.#moveActive(-1);
+        break;
+      case 'ArrowRight': {
+        if (!row) break;
+        e.preventDefault();
+        const item = this.#rowByEl.get(row);
+        if (item && this.#hasChildren(item)) this.#activateItem(item);
+        break;
+      }
+      case 'ArrowLeft':
+      case 'Backspace':
+        if (e.key === 'Backspace' && e.target === this.#filterInputEl) break;
+        e.preventDefault();
+        this.back();
+        break;
+      case 'Enter':
+      case ' ':
+        if (!row) break;
+        e.preventDefault();
+        {
+          const item = this.#rowByEl.get(row);
+          if (item) this.#activateItem(item);
+        }
+        break;
+    }
+  };
+}