@adia-ai/web-components 0.4.6 → 0.4.8

package/components/drawer/drawer.js

@@ -1,296 +1,17 @@
 /**
- * <drawer-ui> — Slide-out panel anchored to a viewport edge.
+ * `<drawer-ui>` — auto-registers the tag on import.
  *
- * Uses native <dialog> for focus trapping, Escape key, and ::backdrop.
- * Content panel slides in/out with CSS transitions.
- * Exit animation plays before dialog.close() via [data-closing].
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Authoring — card-ui-style tags (recommended):
- *   <drawer-ui side="right" size="md">
- *     <header>Title block</header>
- *     <section>Body content</section>
- *     <footer>Action buttons</footer>
- *   </drawer-ui>
+ *   import { UIDrawer } from '@adia-ai/web-components/components/drawer/class';
  *
- * Authoring — explicit slots (also supported):
- *   <drawer-ui>
- *     <header slot="header">…</header>
- *     <section slot="body">…</section>
- *     <footer slot="footer">…</footer>
- *   </drawer-ui>
- *
- * Title-only (stamps an empty header with a close button):
- *   <drawer-ui text="Settings" side="right"></drawer-ui>
- *
- * API:
- *   drawer.show() · drawer.hide() · drawer.open = true|false
- *
- * Events:
- *   close — fired after the drawer finishes closing
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
-
-class UIDrawer extends UIElement {
-  #bound = false;
-  #closing = false;
-  #previousFocus = null;
-  #closeTimer = null;
-  #dialogRef = null;
-
-  static properties = {
-    text:      { type: String,  default: '', reflect: true },
-    side:      { type: String,  default: 'right', reflect: true },
-    size:      { type: String,  default: 'md', reflect: true },
-    permanent: { type: Boolean, default: false, reflect: true },
-    open:      { type: Boolean, default: false, reflect: true },
-  };
-
-  static parts = {
-    dialog: '<dialog slot="dialog"></dialog>',
-    panel:  '<div slot="panel"></div>',
-    header: '<header slot="header"></header>',
-    close:  '<button-ui slot="close" icon="x" variant="ghost" size="sm" aria-label="Close"></button-ui>',
-    body:   '<section slot="body"></section>',
-    footer: '<footer slot="footer"></footer>',
-  };
-
-  // No template — drawer composes from authored light-DOM children. An empty
-  // html`` result would trigger stamp() → replaceChildren(), wiping authored
-  // [slot=header|body|footer] before render() can migrate them into the panel.
-
-  constructor() {
-    super();
-    // Safari requires <dialog>.showModal() to be invoked synchronously inside
-    // the click handler. The reactive system schedules render() in a microtask
-    // after the property change, which Safari treats as outside the user-gesture
-    // window and silently no-ops the showModal. Wrap the auto-installed `open`
-    // setter so dialog state syncs in the same synchronous frame as the
-    // assignment. See docs/BROWSER-COMPAT.md §3a (Flavor C).
-    const desc = Object.getOwnPropertyDescriptor(this, 'open');
-    if (desc?.set) {
-      const origSet = desc.set;
-      Object.defineProperty(this, 'open', {
-        get: desc.get,
-        set: (v) => {
-          origSet.call(this, v);
-          this.#syncDialog();
-        },
-        configurable: true,
-      });
-    }
-  }
-
-  #onPress = (e) => {
-    if (e.target.closest('[slot="close"]')) this.open = false;
-  };
-
-  #onDialogCancel = (e) => {
-    e.preventDefault();
-    if (!this.permanent) this.open = false;
-  };
-
-  #onDialogClose = () => {
-    this.open = false;
-    this.#previousFocus?.focus();
-    this.#previousFocus = null;
-    this.dispatchEvent(new Event('close', { bubbles: true }));
-  };
-
-  #onDialogClick = (e) => {
-    if (e.target === this.#dialogRef && !this.permanent) this.open = false;
-  };
-
-  connected() {
-    this.addEventListener('press', this.#onPress);
-
-    // Bind dialog listeners as soon as the dialog part is available.
-    const dialog = this.ensure('dialog');
-    if (dialog && !this.#bound) {
-      this.#bound = true;
-      this.#dialogRef = dialog;
-      dialog.addEventListener('cancel', this.#onDialogCancel);
-      dialog.addEventListener('close', this.#onDialogClose);
-      dialog.addEventListener('click', this.#onDialogClick);
-    }
-  }
-
-  disconnected() {
-    this.removeEventListener('press', this.#onPress);
-    if (this.#dialogRef) {
-      this.#dialogRef.removeEventListener('cancel', this.#onDialogCancel);
-      this.#dialogRef.removeEventListener('close', this.#onDialogClose);
-      this.#dialogRef.removeEventListener('click', this.#onDialogClick);
-    }
-    if (this.#closeTimer != null) {
-      clearTimeout(this.#closeTimer);
-      this.#closeTimer = null;
-    }
-    this.#bound = false;
-    this.#dialogRef = null;
-  }
-
-  #getDuration() {
-    const raw = getComputedStyle(this).getPropertyValue('--drawer-duration').trim();
-    return parseFloat(raw) || 200;
-  }
-
-  /**
-   * Adopt a slotted part into the panel. Accepts either an explicit
-   * [slot="X"] element OR a bare tag matching the card-ui convention
-   * (<header> → header, <section> → body, <footer> → footer). The tag is only
-   * adopted when no slot attribute is set, so authors can still opt into
-   * explicit slotting. The slot attribute is normalized onto the adopted
-   * element so downstream CSS selectors (`[slot="header"]`) match in both
-   * cases.
-   */
-  #adoptSlot(slot, panel, mode = 'append') {
-    const fallbackTag = { header: 'header', body: 'section', footer: 'footer' }[slot];
-    const isMatch = (c) => c.getAttribute('slot') === slot
-      || (fallbackTag && !c.getAttribute('slot') && c.localName === fallbackTag);
-
-    const inDirect = [...this.children].find(isMatch);
-    const inPanel  = [...panel.children].find(c => c.getAttribute('slot') === slot);
-
-    if (inDirect && inPanel && inDirect !== inPanel) {
-      // User provided their own after we stamped a default — drop the stamp.
-      inPanel.remove();
-    }
-
-    const el = inDirect || inPanel || (() => {
-      const blueprint = this.constructor._pp?.[slot];
-      if (!blueprint) return null;
-      const clone = blueprint.cloneNode(true);
-      clone.setAttribute('data-stamped', '');
-      return clone;
-    })();
-    if (!el) return null;
-
-    if (el.getAttribute('slot') !== slot) el.setAttribute('slot', slot);
-
-    if (el.parentElement !== panel) {
-      if (mode === 'prepend') panel.prepend(el);
-      else panel.appendChild(el);
-    }
-    return el;
-  }
-
-  render() {
-    const dialog = this.ensure('dialog');
-
-    if (this.text) {
-      dialog.setAttribute('aria-label', this.text);
-      this.setAttribute('aria-label', this.text);
-    } else {
-      dialog.removeAttribute('aria-label');
-      this.removeAttribute('aria-label');
-    }
-
-    const panel = this.ensure('panel');
-    if (panel.parentElement !== dialog) dialog.appendChild(panel);
-
-    const header = this.#adoptSlot('header', panel, 'prepend');
-
-    // text="…" shorthand: stamp a [slot="heading"] into the header so the
-    // card-ui grid picks it up. Any author-supplied heading wins.
-    if (header) {
-      let stampedHeading = header.querySelector(':scope > [slot="heading"][data-stamped]');
-      const hasAuthorHeading = [...header.children].some(c =>
-        !c.hasAttribute('data-stamped') &&
-        (c.getAttribute('slot') === 'heading' || /^h[1-6]$/.test(c.localName))
-      );
-      if (this.text && !hasAuthorHeading) {
-        if (!stampedHeading) {
-          stampedHeading = document.createElement('span');
-          stampedHeading.setAttribute('slot', 'heading');
-          stampedHeading.setAttribute('data-stamped', '');
-          header.prepend(stampedHeading);
-        }
-        if (stampedHeading.textContent !== this.text) stampedHeading.textContent = this.text;
-      } else if (stampedHeading) {
-        stampedHeading.remove();
-      }
-    }
-
-    if (!this.permanent) {
-      const close = this.ensure('close');
-      if (header && close.parentElement !== header) header.appendChild(close);
-    } else {
-      this.drop('close');
-    }
-
-    // Body — multiple sections allowed (card-ui parity). Accepts either
-    // bare <section> tags or explicit [slot="body"]. If the author provides
-    // none, stamp an empty default so title-only drawers still lay out.
-    const authorSections = [...this.children].filter(c =>
-      c.getAttribute('slot') === 'body'
-      || (c.localName === 'section' && !c.getAttribute('slot'))
-    );
-    if (authorSections.length === 0) {
-      this.#adoptSlot('body', panel, 'append');
-    } else {
-      for (const s of authorSections) {
-        if (s.getAttribute('slot') !== 'body') s.setAttribute('slot', 'body');
-        if (s.parentElement !== panel) panel.appendChild(s);
-      }
-    }
-
-    // Footer is opt-in — only mounted if the author supplied one (either
-    // [slot="footer"] or a bare <footer> tag, card-ui style).
-    const userFooter = [...this.children].find(c =>
-      c.getAttribute('slot') === 'footer' || (!c.getAttribute('slot') && c.localName === 'footer')
-    );
-    if (userFooter) {
-      if (userFooter.getAttribute('slot') !== 'footer') userFooter.setAttribute('slot', 'footer');
-      if (userFooter.parentElement !== panel) panel.appendChild(userFooter);
-    }
-
-    // Sync open state — also syncs synchronously from the `open` setter
-    // (see constructor) so showModal() runs in the click handler's gesture
-    // frame on Safari.
-    this.#syncDialog();
-  }
-
-  #syncDialog() {
-    const dialog = this.#dialogRef;
-    if (!dialog) return;
-    if (this.open && !dialog.open) {
-      this.#closing = false;
-      this.#previousFocus = document.activeElement;
-      dialog.showModal();
-      // Synchronous reflow instead of rAF — Safari throttles
-      // requestAnimationFrame when a top-layer dialog is open, sometimes
-      // delaying [data-open] (and the slide-in transition) by tens of
-      // seconds. Forcing a reflow keeps the animation start in the same
-      // synchronous frame. See docs/BROWSER-COMPAT.md §3a (Flavor C).
-      void dialog.offsetHeight;
-      dialog.setAttribute('data-open', '');
-    } else if (!this.open && dialog.open && !this.#closing) {
-      this.#animateClose(dialog);
-    }
-  }
-
-  #animateClose(dialog) {
-    this.#closing = true;
-    // Set [data-closing] FIRST (carries the transition spec), force a
-    // reflow, THEN remove [data-open]. If both attribute changes batch
-    // into a single style update, Safari can skip the slide-out animation
-    // entirely.
-    dialog.setAttribute('data-closing', '');
-    void dialog.offsetHeight;
-    dialog.removeAttribute('data-open');
-
-    this.#closeTimer = setTimeout(() => {
-      this.#closeTimer = null;
-      this.#closing = false;
-      dialog.removeAttribute('data-closing');
-      if (dialog.open) dialog.close();
-    }, this.#getDuration());
-  }
+import { defineIfFree } from '../../core/register.js';
+import { UIDrawer } from './class.js';
 
-  show() { this.open = true; }
-  hide() { this.open = false; }
-}
-customElements.define('drawer-ui', UIDrawer);
+defineIfFree('drawer-ui', UIDrawer);
 
 export { UIDrawer };

package/components/embed/class.js

@@ -0,0 +1,73 @@
+/**
+ * Non-side-effect class export for `<embed-ui>`.
+ *
+ * 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/embed`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <embed-ui src="https://example.com" height="400" aspect="16/9"></embed-ui>
+ *
+ * Responsive sandboxed iframe wrapper.
+ *
+ * Properties:
+ *   src    — iframe URL
+ *   height — iframe height (default '400')
+ *   width  — iframe width (default '100%')
+ *   aspect — optional CSS aspect-ratio (e.g. '16/9')
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIEmbed extends UIElement {
+  static properties = {
+    src:    { type: String,  default: '', reflect: true },
+    height: { type: String,  default: '400', reflect: true },
+    width:  { type: String,  default: '100%', reflect: true },
+    aspect: { type: String,  default: '', reflect: true },
+  };
+
+  static template = () => null;
+
+  #iframe = null;
+
+  connected() {
+    if (!this.#iframe) {
+      this.#iframe = document.createElement('iframe');
+      this.#iframe.setAttribute('sandbox', 'allow-scripts allow-same-origin');
+      this.#iframe.setAttribute('loading', 'lazy');
+      this.#iframe.setAttribute('allowfullscreen', '');
+      this.appendChild(this.#iframe);
+    }
+  }
+
+  render() {
+    if (!this.#iframe) return;
+
+    if (this.src) this.#iframe.src = this.src;
+
+    if (this.aspect) {
+      this.style.aspectRatio = this.aspect;
+      this.#iframe.style.width = '100%';
+      this.#iframe.style.height = '100%';
+      this.style.width = this.width;
+      this.style.height = '';
+    } else {
+      this.style.aspectRatio = '';
+      this.#iframe.style.width = '100%';
+      this.#iframe.style.height = this.height.match(/^\d+$/) ? `${this.height}px` : this.height;
+      this.style.width = this.width;
+      this.style.height = '';
+    }
+  }
+
+  disconnected() {
+    this.#iframe = null;
+  }
+}

package/components/embed/embed.a2ui.json

@@ -44,6 +44,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "agent",
+    "composes": [],
     "events": {},
     "examples": [
       {

package/components/embed/embed.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `<embed-ui>` — Responsive sandboxed iframe wrapper.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/embed
+ *
+ * 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 class UIEmbed extends UIElement {
+  /** CSS aspect-ratio (e.g. 16/9) */
+  aspect: string;
+  /** Iframe height. Plain numbers treated as pixels. */
+  height: string;
+  /** URL to load in the iframe */
+  src: string;
+  /** Iframe width. Any CSS width value. */
+  width: string;
+}

package/components/embed/embed.js

@@ -1,63 +1,17 @@
 /**
- * <embed-ui src="https://example.com" height="400" aspect="16/9"></embed-ui>
+ * `<embed-ui>` — auto-registers the tag on import.
  *
- * Responsive sandboxed iframe wrapper.
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Properties:
- *   src    — iframe URL
- *   height — iframe height (default '400')
- *   width  — iframe width (default '100%')
- *   aspect — optional CSS aspect-ratio (e.g. '16/9')
+ *   import { UIEmbed } from '@adia-ai/web-components/components/embed/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
-
-class UIEmbed extends UIElement {
-  static properties = {
-    src:    { type: String,  default: '', reflect: true },
-    height: { type: String,  default: '400', reflect: true },
-    width:  { type: String,  default: '100%', reflect: true },
-    aspect: { type: String,  default: '', reflect: true },
-  };
-
-  static template = () => null;
-
-  #iframe = null;
-
-  connected() {
-    if (!this.#iframe) {
-      this.#iframe = document.createElement('iframe');
-      this.#iframe.setAttribute('sandbox', 'allow-scripts allow-same-origin');
-      this.#iframe.setAttribute('loading', 'lazy');
-      this.#iframe.setAttribute('allowfullscreen', '');
-      this.appendChild(this.#iframe);
-    }
-  }
-
-  render() {
-    if (!this.#iframe) return;
-
-    if (this.src) this.#iframe.src = this.src;
-
-    if (this.aspect) {
-      this.style.aspectRatio = this.aspect;
-      this.#iframe.style.width = '100%';
-      this.#iframe.style.height = '100%';
-      this.style.width = this.width;
-      this.style.height = '';
-    } else {
-      this.style.aspectRatio = '';
-      this.#iframe.style.width = '100%';
-      this.#iframe.style.height = this.height.match(/^\d+$/) ? `${this.height}px` : this.height;
-      this.style.width = this.width;
-      this.style.height = '';
-    }
-  }
+import { defineIfFree } from '../../core/register.js';
+import { UIEmbed } from './class.js';
 
-  disconnected() {
-    this.#iframe = null;
-  }
-}
-customElements.define('embed-ui', UIEmbed);
+defineIfFree('embed-ui', UIEmbed);
 
 export { UIEmbed };

package/components/empty-state/class.js

@@ -0,0 +1,108 @@
+/**
+ * Non-side-effect class export for `<empty-state-ui>`.
+ *
+ * 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/empty-state`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <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>
+ *
+ * Placeholder for empty views — icon, heading, description, and action slot.
+ * The action slot is user-provided (not stamped by the component).
+ *
+ * Note: Uses 'heading' attribute instead of 'title' to avoid native tooltip.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export 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;
+      }
+    }
+  }
+
+  disconnected() {
+    this.#iconEl = null;
+    this.#headingEl = null;
+    this.#descEl = null;
+  }
+}

package/components/empty-state/empty-state.a2ui.json

@@ -39,6 +39,9 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "display",
+    "composes": [
+      "icon-ui"
+    ],
     "events": {},
     "examples": [
       {

package/components/empty-state/empty-state.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `<empty-state-ui>` — Placeholder for empty views with icon, heading, description, and action slot.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/empty-state
+ *
+ * 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 class UIEmptyState extends UIElement {
+  /** Secondary descriptive text below the heading */
+  description: string;
+  /** Primary heading text. Uses 'heading' instead of 'title' to avoid native tooltip. */
+  heading: string;
+  /** Icon name displayed above the heading */
+  icon: string;
+}