@adia-ai/web-components 0.4.6 → 0.4.8

package/components/link/link.js

@@ -1,177 +1,17 @@
 /**
- * <link-ui> — Inline navigation primitive.
+ * `<link-ui>` — auto-registers the tag on import.
  *
- *   <link-ui text="Terms of Service" href="/terms"></link-ui>
- *   <link-ui href="https://example.com" target="_blank">Read more</link-ui>
- *   <link-ui text="Sign in" variant="quiet" href="/signin"></link-ui>
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Semantic <a href> wrapper for cross-page navigation. Sibling of
- * <button-ui> — the two are NOT interchangeable:
- *   - <button-ui>: triggers an action (submit, open modal, copy, run handler)
- *   - <link-ui>:   navigates to a URL (real <a href> under the hood)
+ *   import { UILink } from '@adia-ai/web-components/components/link/class';
  *
- * The previous design conflated these via `<button-ui variant="link">`,
- * which produced a button DOM with link-look styling — accessibility
- * trees announced "button" for things screen-reader users expected to
- * be links, middle-click did nothing instead of opening new tabs,
- * search engines didn't see the link targets.
- *
- * Implementation: stamps an internal <a> element on connected() unless
- * a child <a> is already present (slot-passthrough mode for advanced
- * authoring). Renders the `text` prop into a <span> inside the <a>.
- * For target="_blank", auto-adds rel="noopener noreferrer" unless an
- * explicit rel is set.
- *
- * Properties:
- *   text     — visible label
- *   href     — destination URL (required for native nav semantics)
- *   target   — _self | _blank | _parent | _top
- *   rel      — explicit rel (defaults to noopener noreferrer for _blank)
- *   variant  — default | subtle | quiet
- *   block    — full-width row
- *   disabled — suppress activation
- *   icon     — optional leading Phosphor icon
- *
- * Events:
- *   press — bubbles on click/Enter with detail { href, target }. Fires
- *           BEFORE native navigation. preventDefault() the underlying
- *           click event to suppress native nav and route through the
- *           A2UI action-handler system.
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
-
-class UILink extends UIElement {
-  static properties = {
-    text:     { type: String,  default: '', reflect: true },
-    href:     { type: String,  default: '', reflect: true },
-    target:   { type: String,  default: '', reflect: true },
-    rel:      { type: String,  default: '', reflect: true },
-    variant:  { type: String,  default: 'default', reflect: true },
-    block:    { type: Boolean, default: false, reflect: true },
-    disabled: { type: Boolean, default: false, reflect: true },
-    icon:     { type: String,  default: '', reflect: true },
-  };
-
-  static template = () => null;
-
-  #onClick = (e) => {
-    if (this.disabled) {
-      e.preventDefault();
-      return;
-    }
-    // Dispatch press BEFORE native navigation so handlers can intercept.
-    const detail = { href: this.href, target: this.target };
-    const press = new CustomEvent('press', {
-      bubbles: true,
-      cancelable: true,
-      detail,
-    });
-    const allowed = this.dispatchEvent(press);
-    // If a handler called preventDefault on the press event, suppress
-    // the underlying anchor's native navigation too.
-    if (!allowed) e.preventDefault();
-  };
-
-  #onKey = (e) => {
-    // Links are activated by Enter only (NOT Space — that's button
-    // semantics). The native <a> handles this already, but we wire it
-    // explicitly for the disabled-suppression case.
-    if (this.disabled && e.key === 'Enter') {
-      e.preventDefault();
-    }
-  };
-
-  #ensureAnchor() {
-    // If author provided their own <a> child, leave it alone. Otherwise
-    // stamp one with the configured href/target/rel and mark it as
-    // autostamped so render() knows it owns the anchor's attrs +
-    // content. Slot-passthrough mode (author <a> child) preserves all
-    // author-set attrs across re-renders.
-    let a = this.querySelector(':scope > a');
-    if (!a) {
-      a = document.createElement('a');
-      a.dataset.autostamped = 'true';
-      this.appendChild(a);
-    }
-    // Move any direct text/icon children into the anchor so they inherit
-    // its semantics. Skip nodes already inside the anchor.
-    const toMove = [];
-    for (const node of this.childNodes) {
-      if (node === a) continue;
-      if (node.parentNode === this) toMove.push(node);
-    }
-    for (const node of toMove) a.appendChild(node);
-    return a;
-  }
-
-  connected() {
-    const a = this.#ensureAnchor();
-    this.addEventListener('click', this.#onClick);
-    this.addEventListener('keydown', this.#onKey);
-    // Disabled handling — aria-disabled rather than removing href, so
-    // the disabled state is announced to screen readers.
-    if (this.disabled) this.setAttribute('aria-disabled', 'true');
-  }
-
-  render() {
-    const a = this.querySelector(':scope > a');
-    if (!a) return;
-
-    // Slot-passthrough detection: if the author provided their own <a>
-    // child, leave its href/target/rel alone — they intentionally
-    // configured the anchor directly. We only manage anchors we
-    // auto-stamped (marked via data-autostamped).
-    const isAutostamped = a.dataset.autostamped === 'true';
-
-    if (isAutostamped) {
-      // href: empty string = no native nav, but element is still
-      // activatable via press event (handler-driven navigation).
-      if (this.href) a.setAttribute('href', this.href);
-      else a.removeAttribute('href');
-
-      // target: passed through verbatim.
-      if (this.target) a.setAttribute('target', this.target);
-      else a.removeAttribute('target');
-
-      // rel: explicit rel wins; otherwise auto-add noopener noreferrer
-      // for _blank to prevent tab-napping / referrer leakage.
-      if (this.rel) {
-        a.setAttribute('rel', this.rel);
-      } else if (this.target === '_blank') {
-        a.setAttribute('rel', 'noopener noreferrer');
-      } else {
-        a.removeAttribute('rel');
-      }
-    }
-
-    // Disabled — keep the anchor in the tree (so SR announcement works)
-    // but communicate state via aria-disabled. Click handler short-
-    // circuits when disabled is set. This applies to both autostamped
-    // and slot-passthrough modes.
-    if (this.disabled) {
-      this.setAttribute('aria-disabled', 'true');
-      a.setAttribute('tabindex', '-1');
-    } else {
-      this.removeAttribute('aria-disabled');
-      a.removeAttribute('tabindex');
-    }
-
-    // text + icon — stamp into the anchor when the props are set and
-    // this is an autostamped anchor. Don't touch author-provided
-    // anchors' content.
-    if (isAutostamped) {
-      const iconHTML = this.icon ? `<icon-ui name="${this.icon}"></icon-ui>` : '';
-      const textHTML = this.text ? `<span>${this.text}</span>` : '';
-      a.innerHTML = `${iconHTML}${textHTML}`;
-    }
-  }
+import { defineIfFree } from '../../core/register.js';
+import { UILink } from './class.js';
 
-  disconnected() {
-    this.removeEventListener('click', this.#onClick);
-    this.removeEventListener('keydown', this.#onKey);
-  }
-}
+defineIfFree('link-ui', UILink);
 
-customElements.define('link-ui', UILink);
 export { UILink };

package/components/list/class.js

@@ -0,0 +1,249 @@
+/**
+ * Non-side-effect class export for `<list-ui>` (+ co-located primitives).
+ *
+ * Importing this file gives you the class(es) 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/list`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <list-ui divider>
+ *   <list-item-ui icon="check" text="Item one"></list-item-ui>
+ *   <list-item-ui icon="check" text="Item two"></list-item-ui>
+ * </list-ui>
+ *
+ * Styled list with optional icons and dividers.
+ *
+ * Selection (mirrors table-ui):
+ *   <list-ui selectable selected-key="row-2">
+ *     <list-item-ui id="row-1" text="One"></list-item-ui>
+ *     <list-item-ui id="row-2" text="Two"></list-item-ui>
+ *   </list-ui>
+ *
+ * When `selectable`:
+ *   - Children (role="listitem") become keyboard-focusable via roving tabindex.
+ *   - Click selects the child; key is its id or data-key.
+ *   - aria-selected is set on all children.
+ *   - Fires `selection-change` with { key, previousKey }.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIList extends UIElement {
+  static properties = {
+    divider:     { type: Boolean, default: false, reflect: true },
+    spacing:     { type: String,  default: 'md',  reflect: true },
+    selectable:  { type: Boolean, default: false, reflect: true },
+    selectedKey: { type: String,  default: '',    reflect: true, attribute: 'selected-key' },
+  };
+
+  static template = () => null;
+
+  #bound = false;
+
+  connected() {
+    this.setAttribute('role', 'list');
+    if (!this.#bound) {
+      this.#bound = true;
+      this.addEventListener('click', this.#onClick);
+      this.addEventListener('keydown', this.#onKeydown);
+    }
+  }
+
+  disconnected() {
+    this.removeEventListener('click', this.#onClick);
+    this.removeEventListener('keydown', this.#onKeydown);
+    this.#bound = false;
+  }
+
+  render() {
+    if (!this.selectable) {
+      // Clear selection chrome from children
+      for (const ch of this.#items()) {
+        ch.removeAttribute('aria-selected');
+        ch.removeAttribute('tabindex');
+      }
+      return;
+    }
+    const key = this.selectedKey || '';
+    const items = this.#items();
+    let focusTarget = null;
+    for (const ch of items) {
+      const k = this.#keyOf(ch);
+      const selected = k && k === key;
+      ch.setAttribute('aria-selected', selected ? 'true' : 'false');
+      ch.setAttribute('tabindex', selected ? '0' : '-1');
+      if (selected) focusTarget = ch;
+    }
+    // Ensure at least one item is focusable (first) when nothing selected.
+    if (!focusTarget && items.length) {
+      items[0].setAttribute('tabindex', '0');
+    }
+  }
+
+  #items() {
+    return [...this.children].filter(
+      (el) => el.getAttribute && el.getAttribute('role') === 'listitem',
+    );
+  }
+
+  #keyOf(el) {
+    return el.id || el.getAttribute('data-key') || '';
+  }
+
+  #selectKey(newKey, { focus = false } = {}) {
+    if (!this.selectable) return;
+    if (!newKey) return;
+    const previousKey = this.selectedKey || '';
+    if (newKey === previousKey) return;
+    this.selectedKey = newKey;
+    this.dispatchEvent(new CustomEvent('selection-change', {
+      detail: { key: newKey, previousKey },
+      bubbles: true,
+    }));
+    if (focus) {
+      const el = [...this.#items()].find((i) => this.#keyOf(i) === newKey);
+      el?.focus?.();
+    }
+  }
+
+  #onClick = (e) => {
+    if (!this.selectable) return;
+    const item = e.target.closest?.('[role="listitem"]');
+    if (!item || item.parentElement !== this) return;
+    const key = this.#keyOf(item);
+    if (key) this.#selectKey(key);
+  };
+
+  #onKeydown = (e) => {
+    if (!this.selectable) return;
+    const items = this.#items();
+    if (!items.length) return;
+    const current = document.activeElement;
+    const idx = items.indexOf(current);
+    if (idx < 0) return;
+    let next = idx;
+    switch (e.key) {
+      case 'ArrowDown': next = Math.min(items.length - 1, idx + 1); break;
+      case 'ArrowUp':   next = Math.max(0, idx - 1); break;
+      case 'Home':      next = 0; break;
+      case 'End':       next = items.length - 1; break;
+      case 'Enter':
+      case ' ': {
+        e.preventDefault();
+        const key = this.#keyOf(items[idx]);
+        if (key) this.#selectKey(key);
+        return;
+      }
+      default: return;
+    }
+    if (next !== idx) {
+      e.preventDefault();
+      items[next]?.focus?.();
+    }
+  };
+}
+
+export class UIListItem extends UIElement {
+  static properties = {
+    icon:        { type: String, default: '', reflect: true },
+    text:        { type: String, default: '', reflect: true },
+    description: { type: String, default: '', reflect: true },
+  };
+
+  static template = () => null;
+
+  connected() {
+    this.setAttribute('role', 'listitem');
+    this.#stamp();
+  }
+
+  // Scoped to direct children — never reach into nested custom elements,
+  // otherwise we'd accidentally remove e.g. a <span slot="icon"> inside a
+  // child <card-ui> when list-item-ui has no `icon` prop.
+  #ownChild(selector) {
+    for (const ch of this.children) {
+      if (ch.matches(selector)) return ch;
+    }
+    return null;
+  }
+
+  // Mark slot elements we create so render() never deletes consumer-provided ones.
+  #stampMark(el) { el.dataset.listStamped = '1'; return el; }
+  #wasStamped(el) { return el?.dataset?.listStamped === '1'; }
+
+  #stamp() {
+    if (this.#ownChild('[slot="content"]')) return;
+
+    if (this.icon) {
+      let iconEl = this.#ownChild('[slot="icon"]') || this.#ownChild('icon-ui');
+      if (!iconEl) {
+        iconEl = this.#stampMark(document.createElement('icon-ui'));
+        iconEl.setAttribute('slot', 'icon');
+        this.prepend(iconEl);
+      }
+      iconEl.setAttribute('name', this.icon);
+    }
+
+    if (this.text) {
+      let span = this.#ownChild('[slot="text"]');
+      if (!span) {
+        span = this.#stampMark(document.createElement('span'));
+        span.setAttribute('slot', 'text');
+        this.appendChild(span);
+      }
+      if (this.#wasStamped(span)) span.textContent = this.text;
+    }
+
+    if (this.description) {
+      let desc = this.#ownChild('[slot="description"]');
+      if (!desc) {
+        desc = this.#stampMark(document.createElement('span'));
+        desc.setAttribute('slot', 'description');
+        this.appendChild(desc);
+      }
+      if (this.#wasStamped(desc)) desc.textContent = this.description;
+    }
+  }
+
+  render() {
+    // Sync icon — only touch elements we stamped.
+    const iconEl = this.#ownChild('[slot="icon"]');
+    if (this.icon) {
+      if (iconEl) {
+        if (this.#wasStamped(iconEl)) iconEl.setAttribute('name', this.icon);
+      } else {
+        const el = this.#stampMark(document.createElement('icon-ui'));
+        el.setAttribute('slot', 'icon');
+        el.setAttribute('name', this.icon);
+        this.prepend(el);
+      }
+    } else if (this.#wasStamped(iconEl)) {
+      iconEl.remove();
+    }
+
+    // Sync text — only touch elements we stamped.
+    const textEl = this.#ownChild('[slot="text"]');
+    if (this.#wasStamped(textEl)) textEl.textContent = this.text;
+
+    // Sync description — only touch elements we stamped.
+    const descEl = this.#ownChild('[slot="description"]');
+    if (this.description) {
+      if (descEl) {
+        if (this.#wasStamped(descEl)) descEl.textContent = this.description;
+      } else {
+        const el = this.#stampMark(document.createElement('span'));
+        el.setAttribute('slot', 'description');
+        el.textContent = this.description;
+        this.appendChild(el);
+      }
+    } else if (this.#wasStamped(descEl)) {
+      descEl.remove();
+    }
+  }
+}

package/components/list/list.a2ui.json

@@ -44,6 +44,9 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [
+      "icon-ui"
+    ],
     "events": {
       "selection-change": {
         "description": "Fired on selection-change."

package/components/list/list.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `<list-ui>` — Styled list with optional icons and dividers.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/list
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. 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 type ListSelectionChangeEvent = CustomEvent<unknown>;
+
+export class UIList extends UIElement {
+  /** Show dividers between items */
+  divider: boolean;
+  /** Enable selection on child listitems (roving tabindex + aria-selected). */
+  selectable: boolean;
+  /** ID (or data-key) of the currently-selected child listitem. */
+  selectedKey: string;
+  /** Item spacing */
+  spacing: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIList, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'selection-change', listener: (ev: ListSelectionChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}