@adia-ai/web-components 0.4.6 → 0.4.8

package/components/empty-state/empty-state.js

@@ -1,98 +1,17 @@
 /**
- * <empty-state-ui icon="magnifying-glass" heading="No results" description="Try adjusting your search.">
- *   <button-ui slot="action" text="Clear filters" variant="outline"></button-ui>
- * </empty-state-ui>
+ * `<empty-state-ui>` — auto-registers the tag on import.
  *
- * Placeholder for empty views — icon, heading, description, and action slot.
- * The action slot is user-provided (not stamped by the component).
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Note: Uses 'heading' attribute instead of 'title' to avoid native tooltip.
+ *   import { UIEmptyState } from '@adia-ai/web-components/components/empty-state/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
-
-class UIEmptyState extends UIElement {
-  static properties = {
-    icon:        { type: String, default: '', reflect: true },
-    heading:     { type: String, default: '', reflect: true },
-    description: { type: String, default: '', reflect: true },
-  };
-
-  static template = () => null;
-
-  #iconEl = null;
-  #headingEl = null;
-  #descEl = null;
-
-  // Mark slot elements we create so render() never overrides consumer-provided ones.
-  // See ADR-0010 (slot content is source of truth).
-  #stampMark(el) { el.dataset.emptyStateStamped = '1'; return el; }
-  #wasStamped(el) { return el?.dataset?.emptyStateStamped === '1'; }
-
-  connected() {
-    this.#iconEl = this.querySelector(':scope > [slot="icon"]');
-    if (!this.#iconEl) {
-      this.#iconEl = this.#stampMark(document.createElement('icon-ui'));
-      this.#iconEl.setAttribute('slot', 'icon');
-      this.#iconEl.setAttribute('size', 'lg');
-      this.insertBefore(this.#iconEl, this.firstChild);
-    }
-
-    this.#headingEl = this.querySelector(':scope > [slot="heading"]');
-    if (!this.#headingEl) {
-      this.#headingEl = this.#stampMark(document.createElement('span'));
-      this.#headingEl.setAttribute('slot', 'heading');
-      this.insertBefore(this.#headingEl, this.querySelector('[slot="action"]'));
-    }
-
-    this.#descEl = this.querySelector(':scope > [slot="description"]');
-    if (!this.#descEl) {
-      this.#descEl = this.#stampMark(document.createElement('span'));
-      this.#descEl.setAttribute('slot', 'description');
-      this.insertBefore(this.#descEl, this.querySelector('[slot="action"]'));
-    }
-  }
-
-  render() {
-    if (!this.#iconEl) return;
-
-    // Icon — only mutate stamped elements; visibility follows the source of truth.
-    if (this.#wasStamped(this.#iconEl)) {
-      if (this.icon) {
-        this.#iconEl.setAttribute('name', this.icon);
-        this.#iconEl.hidden = false;
-      } else {
-        this.#iconEl.hidden = true;
-      }
-    }
-
-    // Heading — same policy.
-    if (this.#wasStamped(this.#headingEl)) {
-      if (this.heading) {
-        this.#headingEl.textContent = this.heading;
-        this.#headingEl.hidden = false;
-      } else {
-        this.#headingEl.hidden = true;
-      }
-    }
-
-    // Description — same policy.
-    if (this.#wasStamped(this.#descEl)) {
-      if (this.description) {
-        this.#descEl.textContent = this.description;
-        this.#descEl.hidden = false;
-      } else {
-        this.#descEl.hidden = true;
-      }
-    }
-  }
+import { defineIfFree } from '../../core/register.js';
+import { UIEmptyState } from './class.js';
 
-  disconnected() {
-    this.#iconEl = null;
-    this.#headingEl = null;
-    this.#descEl = null;
-  }
-}
-customElements.define('empty-state-ui', UIEmptyState);
+defineIfFree('empty-state-ui', UIEmptyState);
 
 export { UIEmptyState };

package/components/empty-state/empty-state.yaml

@@ -7,6 +7,10 @@ component: EmptyState
 category: display
 version: 1
 description: Placeholder for empty views with icon, heading, description, and action slot.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - icon-ui
 props:
   description:
     description: Secondary descriptive text below the heading

package/components/feed/class.js

@@ -0,0 +1,381 @@
+/**
+ * Non-side-effect class export for `<feed-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/feed`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <feed-ui> + <feed-item-ui> — Shared top-layer feed channel.
+ *
+ * Per docs/specs/feed-channel.md (SPEC-FEED-CHANNEL-001).
+ *
+ * Phase 1 (skeleton) ships here:
+ *   - Per-position singletons (`<feed-ui position="bottom-right">`)
+ *     resolving OD-FEED-1; mounted lazily into document.body via
+ *     Popover API for top-layer placement.
+ *   - Auto-fade `<feed-item-ui>` policy. Sticky-dismissible and
+ *     action-required policies are stubs that respect the contract
+ *     (no auto-dismiss when `duration` is null/0; close button
+ *     surfaces when `dismissible` is set) but the action-required
+ *     focus-trap is deferred.
+ *   - Static API:  UIFeed.post() / .get() / .clear() / .purge()
+ *     — `purge()` directly addresses the audit's L-B4 container-leak
+ *     finding by giving consumers a tear-down hook.
+ *   - Global event channel:  window.dispatchEvent(new CustomEvent(
+ *       'feed', { detail: { text, position, ... } })) — same shape as
+ *     UIFeed.post() so any code can post without importing the
+ *     module directly. Idempotent listener install (HMR-safe).
+ *
+ * Toast migration (spec § 2.5) is deferred — toast-ui keeps its own
+ * container + API for now; the migration happens once the feed-ui
+ * surface has soaked.
+ */
+
+import { UIElement, html } from '../../core/element.js';
+
+/* ── Container — one per position, mounted into document.body ── */
+
+export class UIFeedContainer extends UIElement {
+  static properties = {
+    position: { type: String, default: 'bottom-right', reflect: true },
+    max:      { type: Number, default: 5,              reflect: true },
+  };
+  static template = () => html``;
+
+  connected() {
+    if (!this.hasAttribute('role')) this.setAttribute('role', 'region');
+    if (!this.hasAttribute('aria-label')) this.setAttribute('aria-label', 'Feed');
+  }
+}
+
+export class UIFeedItem extends UIElement {
+  #timer = null;
+  #removing = false;
+  #closeTimer = null;
+  #openRaf = null;
+
+  static properties = {
+    text:        { type: String,  default: '',           reflect: true },
+    heading:     { type: String,  default: '',           reflect: true },
+    icon:        { type: String,  default: '',           reflect: true },
+    variant:     { type: String,  default: 'default',    reflect: true },
+    duration:    { type: Number,  default: 4000,         reflect: true },
+    dismissible: { type: Boolean, default: false,        reflect: true },
+    // Phase 2: action-required policy. When set, the item carries an
+    // action button that the user MUST click (or dismiss) before the
+    // item goes away. Spec §2.3 — action-required role=alertdialog,
+    // focus is trapped until choice is made.
+    action:      { type: String,  default: '',           reflect: true },
+  };
+
+  static parts = {
+    body: '<div slot="body"></div>',
+  };
+  static template = () => html``;
+
+  #onPress = (e) => {
+    if (e.target.closest('[data-feed-close]')) { this.dismiss(); return; }
+    // Phase 2: action button — fires the action callback (if registered
+    // via FeedHandle.update with onAction) then dismisses. The handle's
+    // .update({onAction: fn}) populates this.#onAction below.
+    if (e.target.closest('[data-feed-action]')) {
+      try { this.#onAction?.(); } catch (err) { console.warn('[feed-item] action handler threw:', err); }
+      this.dismiss();
+    }
+  };
+
+  // Phase 2 focus-trap state — only used when the policy is action-required.
+  #onAction = null;
+  #focusTrapPrev = null;
+  #onTrapKeydown = null;
+
+  connected() {
+    this.addEventListener('press', this.#onPress);
+  }
+
+  #getDuration() {
+    const raw = getComputedStyle(this).getPropertyValue('--feed-item-duration').trim();
+    return parseFloat(raw) || 200;
+  }
+
+  render() {
+    const body = this.ensure('body');
+    body.textContent = '';
+    if (this.heading) {
+      const h = document.createElement('strong');
+      h.textContent = this.heading;
+      h.style.display = 'block';
+      body.appendChild(h);
+    }
+    if (this.text) {
+      const t = document.createElement('span');
+      t.textContent = this.text;
+      body.appendChild(t);
+    }
+
+    /* Inferred policy roles per spec §2.4. Auto-fade gets `status`;
+       sticky danger/warning gets `alert`; action-required (sticky +
+       has [action]) gets `alertdialog` and a focus trap. */
+    const isSticky = !this.duration || this.duration <= 0;
+    const isLoud   = this.variant === 'danger' || this.variant === 'warning';
+    const isActionRequired = isSticky && !!this.action;
+    let role = 'status';
+    if (isActionRequired) role = 'alertdialog';
+    else if (isSticky && isLoud) role = 'alert';
+    this.setAttribute('role', role);
+    this.setAttribute('aria-live', role === 'alert' || role === 'alertdialog' ? 'assertive' : 'polite');
+    if (isActionRequired) this.setAttribute('aria-modal', 'false'); // not page-blocking; focus-trap only
+
+    /* Render dismiss button for sticky items (spec §2.2 — default true
+       for sticky, false for auto-fade). Action-required items still
+       allow Escape to dismiss for safety; the action button is not the
+       only escape. */
+    const wantsClose = this.dismissible || isSticky;
+    let close = this.querySelector(':scope > [data-feed-close]');
+    if (wantsClose && !close) {
+      close = document.createElement('button-ui');
+      close.setAttribute('data-feed-close', '');
+      close.setAttribute('icon', 'x');
+      close.setAttribute('variant', 'ghost');
+      close.setAttribute('size', 'sm');
+      close.setAttribute('aria-label', 'Dismiss');
+      this.appendChild(close);
+    } else if (!wantsClose && close) {
+      close.remove();
+    }
+
+    /* Phase 2 — render the action button when [action] is set. Sits
+       between the body and the close button. */
+    let actionBtn = this.querySelector(':scope > [data-feed-action]');
+    if (this.action) {
+      if (!actionBtn) {
+        actionBtn = document.createElement('button-ui');
+        actionBtn.setAttribute('data-feed-action', '');
+        actionBtn.setAttribute('variant', 'ghost');
+        actionBtn.setAttribute('size', 'sm');
+        if (close && close.parentElement === this) this.insertBefore(actionBtn, close);
+        else                                       this.appendChild(actionBtn);
+      }
+      actionBtn.setAttribute('text', this.action);
+    } else if (actionBtn) {
+      actionBtn.remove();
+    }
+
+    /* Focus-trap activation for action-required. */
+    if (isActionRequired) this.#installFocusTrap();
+    else                  this.#uninstallFocusTrap();
+
+    if (!this.hasAttribute('data-open') && !this.#removing) {
+      this.#openRaf = requestAnimationFrame(() => {
+        this.#openRaf = null;
+        this.setAttribute('data-open', '');
+      });
+    }
+    this.#scheduleAutoDismiss();
+  }
+
+  #scheduleAutoDismiss() {
+    if (this.#timer) clearTimeout(this.#timer);
+    if (this.duration && this.duration > 0) {
+      this.#timer = setTimeout(() => this.dismiss(), this.duration);
+    }
+  }
+
+  dismiss() {
+    if (this.#removing) return;
+    this.#removing = true;
+    if (this.#timer) { clearTimeout(this.#timer); this.#timer = null; }
+    this.removeAttribute('data-open');
+    this.setAttribute('data-closing', '');
+    this.#closeTimer = setTimeout(() => {
+      this.#closeTimer = null;
+      const container = this.parentElement;
+      this.dispatchEvent(new Event('close', { bubbles: true }));
+      this.remove();
+      if (container?.matches?.('feed-ui')) UIFeed.releaseContainerIfEmpty(container);
+    }, this.#getDuration());
+  }
+
+  update(patch) {
+    if (!patch || typeof patch !== 'object') return;
+    for (const k of Object.keys(patch)) {
+      if (k in UIFeedItem.properties) this[k] = patch[k];
+    }
+    // Phase 2: handle is set via the FeedHandle's update(); not a
+    // reflected attribute, so it lives outside the property loop.
+    if (typeof patch.onAction === 'function') this.#onAction = patch.onAction;
+    this.#scheduleAutoDismiss();
+  }
+
+  // Phase 2 focus-trap. Installs on action-required items; saves the
+  // previously-focused element so we can return focus on dismiss; cycles
+  // Tab/Shift-Tab between focusable descendants; Escape dismisses.
+  #installFocusTrap() {
+    if (this.#onTrapKeydown) return; // already installed
+    this.#focusTrapPrev = document.activeElement;
+    const focusables = () => [...this.querySelectorAll('button, button-ui, [tabindex]:not([tabindex="-1"]), input, [data-feed-action], [data-feed-close]')]
+      .filter((el) => !el.hasAttribute('disabled') && el.offsetParent !== null);
+    this.#onTrapKeydown = (e) => {
+      if (e.key === 'Escape') { e.stopPropagation(); this.dismiss(); return; }
+      if (e.key !== 'Tab') return;
+      const els = focusables();
+      if (!els.length) return;
+      const first = els[0];
+      const last  = els[els.length - 1];
+      const active = document.activeElement;
+      if (e.shiftKey && active === first) { e.preventDefault(); last.focus(); }
+      else if (!e.shiftKey && active === last) { e.preventDefault(); first.focus(); }
+    };
+    this.addEventListener('keydown', this.#onTrapKeydown, true);
+    // Move focus into the item — prefer the action button.
+    queueMicrotask(() => {
+      const els = focusables();
+      const action = this.querySelector('[data-feed-action]');
+      (action || els[0])?.focus?.();
+    });
+  }
+
+  #uninstallFocusTrap() {
+    if (!this.#onTrapKeydown) return;
+    this.removeEventListener('keydown', this.#onTrapKeydown, true);
+    this.#onTrapKeydown = null;
+    // Restore focus to whatever had it before the trap engaged.
+    try { this.#focusTrapPrev?.focus?.(); } catch { /* element may have been removed */ }
+    this.#focusTrapPrev = null;
+  }
+
+  disconnected() {
+    this.removeEventListener('press', this.#onPress);
+    if (this.#timer) { clearTimeout(this.#timer); this.#timer = null; }
+    if (this.#closeTimer) { clearTimeout(this.#closeTimer); this.#closeTimer = null; }
+    if (this.#openRaf != null) { cancelAnimationFrame(this.#openRaf); this.#openRaf = null; }
+    this.#uninstallFocusTrap();
+  }
+}
+
+/* ── Static API — UIFeed ── */
+
+export class UIFeed {
+  static #containers = new Map();
+
+  /**
+   * Get (or lazily create) the per-position lane. Each lane is a
+   * manual Popover-API container — `[popover="manual"]` puts it in
+   * the browser's top-layer with no z-index wars and the native
+   * popover stack lets multiple lanes coexist (e.g. one feed in
+   * top-right + another in bottom-center) without collision.
+   */
+  static get(position = 'bottom-right') {
+    let el = UIFeed.#containers.get(position);
+    if (el && el.isConnected) return el;
+    el = document.createElement('feed-ui');
+    el.setAttribute('position', position);
+    if ('popover' in HTMLElement.prototype) el.setAttribute('popover', 'manual');
+    document.body.appendChild(el);
+    try { el.showPopover?.(); } catch { /* graceful fallback */ }
+    UIFeed.#containers.set(position, el);
+    return el;
+  }
+
+  /**
+   * Post a feed item. Returns a `FeedHandle` (`{id, dismiss, update}`).
+   *
+   * @param {Object} opts
+   * @param {string} [opts.text]
+   * @param {string} [opts.heading]
+   * @param {string} [opts.icon]
+   * @param {string} [opts.variant='default']  default | info | success | warning | danger
+   * @param {number|null} [opts.duration=4000]  ms; null/0 = sticky (requires close click)
+   * @param {string} [opts.position='bottom-right']
+   * @param {boolean} [opts.dismissible]  override default (true for sticky, false for auto)
+   * @param {string} [opts.id]
+   * @param {string} [opts.action]  Phase 2 — action button label. When set,
+   *                                duration is forced to null (sticky); the
+   *                                item gets role=alertdialog + focus trap.
+   * @param {function} [opts.onAction]  Phase 2 — callback invoked when the
+   *                                action button is pressed. Item dismisses
+   *                                after the callback returns.
+   */
+  static post(opts = {}) {
+    const {
+      text = '',
+      heading = '',
+      icon = '',
+      variant = 'default',
+      duration = 4000,
+      position = 'bottom-right',
+      dismissible,
+      id,
+      action = '',
+      onAction,
+    } = opts;
+    const v = variant === 'error' ? 'danger' : variant;  // documented alias
+    const container = UIFeed.get(position);
+    // Phase 2 max-queue: items above [max] queue with [data-queued] and
+    // become visible as visible items dismiss.
+    const max = parseInt(container.getAttribute('max') || '5', 10);
+    const visibleCount = [...container.children].filter((c) =>
+      c.tagName === 'FEED-ITEM-UI' && !c.hasAttribute('data-queued')
+    ).length;
+    const item = document.createElement('feed-item-ui');
+    if (id) item.setAttribute('data-id', id);
+    item.text = text;
+    item.heading = heading;
+    item.icon = icon;
+    item.variant = v;
+    // Action-required forces sticky.
+    item.duration = action ? 0 : duration;
+    if (dismissible != null) item.dismissible = !!dismissible;
+    if (action) item.action = action;
+    if (visibleCount >= max) item.setAttribute('data-queued', '');
+    container.appendChild(item);
+    if (typeof onAction === 'function') item.update({ onAction });
+    return {
+      id: id ?? null,
+      dismiss: () => item.dismiss(),
+      update:  (patch) => item.update(patch),
+    };
+  }
+
+  /** Clear all items in a single lane. */
+  static clear(position = 'bottom-right') {
+    const el = UIFeed.#containers.get(position);
+    if (!el) return;
+    for (const item of [...el.children]) {
+      if (item.tagName === 'FEED-ITEM-UI') item.dismiss?.();
+    }
+  }
+
+  /** Tear down ALL containers. Test cleanup; addresses audit L-B4. */
+  static purge() {
+    for (const el of UIFeed.#containers.values()) {
+      try { el.hidePopover?.(); } catch { /* noop */ }
+      el.remove();
+    }
+    UIFeed.#containers.clear();
+  }
+
+  /** Internal: drop a lane when its last item exits. Also rotates the
+   *  Phase 2 max-queue: when a visible item leaves, promote the oldest
+   *  queued sibling so the visible-count returns to [max]. */
+  static releaseContainerIfEmpty(container) {
+    if (!container) return;
+    // Promote the oldest queued sibling (if any) before deciding whether
+    // to release. The queue is FIFO; queued items live at the tail.
+    const queued = container.querySelector('feed-item-ui[data-queued]');
+    if (queued) queued.removeAttribute('data-queued');
+    if (container.children.length > 0) return;
+    try { container.hidePopover?.(); } catch { /* noop */ }
+    container.remove();
+    for (const [pos, el] of UIFeed.#containers) {
+      if (el === container) UIFeed.#containers.delete(pos);
+    }
+  }
+}

package/components/feed/feed.a2ui.json

@@ -43,7 +43,15 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
-    "events": {},
+    "composes": [
+      "button-ui",
+      "feed-item-ui"
+    ],
+    "events": {
+      "close": {
+        "description": "Fired on per-item dismissal (manual close, swipe, or auto-timeout). Bubbles."
+      }
+    },
     "examples": [],
     "keywords": [],
     "name": "UIFeedContainer",

package/components/feed/feed.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `<feed-ui>` — Shared top-layer feed channel. Per docs/specs/feed-channel.md (SPEC-FEED-CHANNEL-001). Per-position singletons mounted lazily into document.body via Popover API; consumers post via the static API (`UIFeed.post()`) or the global 'feed' CustomEvent.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/feed
+ *
+ * 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 FeedCloseEvent = CustomEvent<unknown>;
+
+export class UIFeed extends UIElement {
+  /** Cap on simultaneously visible items per lane */
+  max: number;
+  /** Lane the feed renders into */
+  position: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right' | 'inline';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIFeed, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'close', listener: (ev: FeedCloseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}