@adia-ai/web-components 0.4.6 → 0.4.8

package/components/icon/class.js

@@ -0,0 +1,54 @@
+/**
+ * Non-side-effect class export for `<icon-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/icon`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { UIElement, signal, html } from '../../core/element.js';
+import { getIcon } from '../../core/icons.js';
+
+export class UIIcon extends UIElement {
+  static properties = {
+    name:   { type: String, default: '',        reflect: true },
+    size:   { type: String, default: '',        reflect: true },
+    label:  { type: String, default: '',        reflect: true },
+    /** regular | thin | light | bold | fill | duotone */
+    weight: { type: String, default: 'regular', reflect: true },
+  };
+
+  connected() {
+    this.setAttribute('role', this.label ? 'img' : 'presentation');
+    if (!this.label) this.setAttribute('aria-hidden', 'true');
+  }
+
+  render() {
+    if (this.label) this.setAttribute('aria-label', this.label);
+    const svg = getIcon(this.name, this.weight || 'regular');
+    if (svg && this.innerHTML !== svg) this.innerHTML = svg;
+
+    // Pixel / rem / em passthrough — `size="48"` → 48px,
+    // `size="3.5rem"` → 3.5rem. Named-scale values (xs/sm/md/lg/xl/
+    // 2xl/3xl/4xl/fill) are handled by `:scope[size="…"]` rules in
+    // icon.css; we only set --icon-size inline for free-form values.
+    if (this.size && this.#isFreeFormSize(this.size)) {
+      this.style.setProperty('--icon-size', this.#normalizeSize(this.size));
+    } else if (this.style.getPropertyValue('--icon-size')) {
+      this.style.removeProperty('--icon-size');
+    }
+  }
+
+  #isFreeFormSize(s) {
+    return /^\d+(\.\d+)?(px|rem|em)?$/.test(s);
+  }
+
+  #normalizeSize(s) {
+    return /^\d+(\.\d+)?$/.test(s) ? `${s}px` : s;
+  }
+}

package/components/icon/icon.a2ui.json

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

package/components/icon/icon.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `<icon-ui>` — SVG icon from the icon registry. Renders inline SVG from getIcon().
+ *
+ * @see https://ui-kit.exe.xyz/site/components/icon
+ *
+ * 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 UIIcon extends UIElement {
+  /** Accessible label. Sets role=img and aria-label. */
+  label: string;
+  /** Icon name from registry */
+  name: string;
+  /** Icon size. Accepts the named scale (`xs` 12px / `sm` 14px / `md` 16px / `lg` 20px / `xl` 32px / `2xl` 48px / `3xl` 64px / `4xl` 96px / `fill` 100% of parent) or a free-form pixel / rem / em value as a string ("48", "3rem", "1.25em"). Overrides the inherited `--a-icon-size` from the universal `[size]` system on ancestors. */
+  size: string;
+  /** Icon weight — selects the Phosphor weight variant (thin/light/regular/bold/fill/duotone). */
+  weight: 'thin' | 'light' | 'regular' | 'bold' | 'fill' | 'duotone';
+}

package/components/icon/icon.js

@@ -1,44 +1,17 @@
-import { UIElement, signal, html } from '../../core/element.js';
-import { getIcon } from '../../core/icons.js';
+/**
+ * `<icon-ui>` — auto-registers the tag on import.
+ *
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UIIcon } from '@adia-ai/web-components/components/icon/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
 
-class UIIcon extends UIElement {
-  static properties = {
-    name:   { type: String, default: '',        reflect: true },
-    size:   { type: String, default: '',        reflect: true },
-    label:  { type: String, default: '',        reflect: true },
-    /** regular | thin | light | bold | fill | duotone */
-    weight: { type: String, default: 'regular', reflect: true },
-  };
+import { defineIfFree } from '../../core/register.js';
+import { UIIcon } from './class.js';
 
-  connected() {
-    this.setAttribute('role', this.label ? 'img' : 'presentation');
-    if (!this.label) this.setAttribute('aria-hidden', 'true');
-  }
-
-  render() {
-    if (this.label) this.setAttribute('aria-label', this.label);
-    const svg = getIcon(this.name, this.weight || 'regular');
-    if (svg && this.innerHTML !== svg) this.innerHTML = svg;
-
-    // Pixel / rem / em passthrough — `size="48"` → 48px,
-    // `size="3.5rem"` → 3.5rem. Named-scale values (xs/sm/md/lg/xl/
-    // 2xl/3xl/4xl/fill) are handled by `:scope[size="…"]` rules in
-    // icon.css; we only set --icon-size inline for free-form values.
-    if (this.size && this.#isFreeFormSize(this.size)) {
-      this.style.setProperty('--icon-size', this.#normalizeSize(this.size));
-    } else if (this.style.getPropertyValue('--icon-size')) {
-      this.style.removeProperty('--icon-size');
-    }
-  }
-
-  #isFreeFormSize(s) {
-    return /^\d+(\.\d+)?(px|rem|em)?$/.test(s);
-  }
-
-  #normalizeSize(s) {
-    return /^\d+(\.\d+)?$/.test(s) ? `${s}px` : s;
-  }
-}
-customElements.define('icon-ui', UIIcon);
+defineIfFree('icon-ui', UIIcon);
 
 export { UIIcon };

package/components/image/class.js

@@ -0,0 +1,112 @@
+/**
+ * Non-side-effect class export for `<image-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/image`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <image-ui src="/photo.jpg" alt="Photo" width="300" height="200"></image-ui>
+ * <image-ui src="/avatar.jpg" fit="cover" radius="full"></image-ui>
+ * <image-ui src="/hero.jpg" size="full"></image-ui>
+ * <image-ui src="/pixel.png" raw></image-ui>
+ *
+ * Lazy-loading image with skeleton fallback.
+ * Shows skeleton-ui while loading, swaps to img on load.
+ * Falls back to fallback URL or keeps skeleton on error.
+ *
+ * Size:   full (fills container width and height)
+ * Radius: sm, md, lg, full
+ * Fit:    cover (default), contain, fill, none
+ * Raw:    strips chrome (no background, no radius) for edge-to-edge rendering
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIImage extends UIElement {
+  static properties = {
+    src:      { type: String,  default: '',      reflect: true },
+    alt:      { type: String,  default: '',      reflect: true },
+    width:    { type: String,  default: '',      reflect: true },
+    height:   { type: String,  default: '',      reflect: true },
+    size:     { type: String,  default: '',      reflect: true },
+    fit:      { type: String,  default: 'cover', reflect: true },
+    radius:   { type: String,  default: '',      reflect: true },
+    raw:      { type: Boolean, default: false,   reflect: true },
+    fallback: { type: String,  default: '',      reflect: true },
+  };
+
+  static template = () => null;
+
+  #img = null;
+  #skeleton = null;
+
+  connected() {
+    this.#skeleton = this.querySelector(':scope > [slot="skeleton"]');
+    if (!this.#skeleton) {
+      this.#skeleton = document.createElement('skeleton-ui');
+      this.#skeleton.setAttribute('slot', 'skeleton');
+      this.#skeleton.setAttribute('width', '100%');
+      this.#skeleton.setAttribute('height', '100%');
+      this.appendChild(this.#skeleton);
+    }
+
+    this.#img = this.querySelector(':scope > [slot="image"]');
+    if (!this.#img) {
+      this.#img = document.createElement('img');
+      this.#img.setAttribute('slot', 'image');
+      this.#img.loading = 'lazy';
+      this.appendChild(this.#img);
+    }
+    this.#img.addEventListener('load', this.#onLoad);
+    this.#img.addEventListener('error', this.#onError);
+
+    this.#applySize();
+  }
+
+  render() {
+    if (!this.#img) return;
+
+    if (this.#img.getAttribute('src') !== this.src) {
+      this.removeAttribute('data-loaded');
+      this.removeAttribute('data-error');
+      this.#img.src = this.src || '';
+    }
+
+    this.#img.alt = this.alt || '';
+    this.#applySize();
+  }
+
+  #applySize() {
+    if (this.width)  this.style.width  = this.width;
+    if (this.height) this.style.height = this.height;
+  }
+
+  #onLoad = () => {
+    this.setAttribute('data-loaded', '');
+    this.removeAttribute('data-error');
+  };
+
+  #onError = () => {
+    if (this.fallback && this.#img.src !== this.fallback) {
+      this.#img.src = this.fallback;
+    } else {
+      this.setAttribute('data-error', '');
+    }
+  };
+
+  disconnected() {
+    if (this.#img) {
+      this.#img.removeEventListener('load', this.#onLoad);
+      this.#img.removeEventListener('error', this.#onError);
+    }
+    this.#img = null;
+    this.#skeleton = null;
+  }
+}

package/components/image/image.a2ui.json

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

package/components/image/image.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `<image-ui>` — Lazy-loading image with skeleton fallback. Shows skeleton while loading, falls back on error.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/image
+ *
+ * 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 UIImage extends UIElement {
+  /** Alt text for the image. */
+  alt: string;
+  /** Fallback image URL on error */
+  fallback: string;
+  /** Object-fit mode */
+  fit: 'cover' | 'contain' | 'fill' | 'none';
+  /** CSS height */
+  height: string;
+  /** Border radius token */
+  radius: 'sm' | 'md' | 'lg' | 'full';
+  /** Strip chrome (no background, no radius) for edge-to-edge rendering. */
+  raw: boolean;
+  /** Size preset — e.g. 'full' fills the container width and height. */
+  size: string;
+  /** Image source URL. */
+  src: string;
+  /** CSS width */
+  width: string;
+}

package/components/image/image.js

@@ -1,102 +1,17 @@
 /**
- * <image-ui src="/photo.jpg" alt="Photo" width="300" height="200"></image-ui>
- * <image-ui src="/avatar.jpg" fit="cover" radius="full"></image-ui>
- * <image-ui src="/hero.jpg" size="full"></image-ui>
- * <image-ui src="/pixel.png" raw></image-ui>
+ * `<image-ui>` — auto-registers the tag on import.
  *
- * Lazy-loading image with skeleton fallback.
- * Shows skeleton-ui while loading, swaps to img on load.
- * Falls back to fallback URL or keeps skeleton on error.
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Size:   full (fills container width and height)
- * Radius: sm, md, lg, full
- * Fit:    cover (default), contain, fill, none
- * Raw:    strips chrome (no background, no radius) for edge-to-edge rendering
+ *   import { UIImage } from '@adia-ai/web-components/components/image/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
-
-class UIImage extends UIElement {
-  static properties = {
-    src:      { type: String,  default: '',      reflect: true },
-    alt:      { type: String,  default: '',      reflect: true },
-    width:    { type: String,  default: '',      reflect: true },
-    height:   { type: String,  default: '',      reflect: true },
-    size:     { type: String,  default: '',      reflect: true },
-    fit:      { type: String,  default: 'cover', reflect: true },
-    radius:   { type: String,  default: '',      reflect: true },
-    raw:      { type: Boolean, default: false,   reflect: true },
-    fallback: { type: String,  default: '',      reflect: true },
-  };
-
-  static template = () => null;
-
-  #img = null;
-  #skeleton = null;
-
-  connected() {
-    this.#skeleton = this.querySelector(':scope > [slot="skeleton"]');
-    if (!this.#skeleton) {
-      this.#skeleton = document.createElement('skeleton-ui');
-      this.#skeleton.setAttribute('slot', 'skeleton');
-      this.#skeleton.setAttribute('width', '100%');
-      this.#skeleton.setAttribute('height', '100%');
-      this.appendChild(this.#skeleton);
-    }
-
-    this.#img = this.querySelector(':scope > [slot="image"]');
-    if (!this.#img) {
-      this.#img = document.createElement('img');
-      this.#img.setAttribute('slot', 'image');
-      this.#img.loading = 'lazy';
-      this.appendChild(this.#img);
-    }
-    this.#img.addEventListener('load', this.#onLoad);
-    this.#img.addEventListener('error', this.#onError);
-
-    this.#applySize();
-  }
-
-  render() {
-    if (!this.#img) return;
-
-    if (this.#img.getAttribute('src') !== this.src) {
-      this.removeAttribute('data-loaded');
-      this.removeAttribute('data-error');
-      this.#img.src = this.src || '';
-    }
-
-    this.#img.alt = this.alt || '';
-    this.#applySize();
-  }
-
-  #applySize() {
-    if (this.width)  this.style.width  = this.width;
-    if (this.height) this.style.height = this.height;
-  }
-
-  #onLoad = () => {
-    this.setAttribute('data-loaded', '');
-    this.removeAttribute('data-error');
-  };
-
-  #onError = () => {
-    if (this.fallback && this.#img.src !== this.fallback) {
-      this.#img.src = this.fallback;
-    } else {
-      this.setAttribute('data-error', '');
-    }
-  };
+import { defineIfFree } from '../../core/register.js';
+import { UIImage } from './class.js';
 
-  disconnected() {
-    if (this.#img) {
-      this.#img.removeEventListener('load', this.#onLoad);
-      this.#img.removeEventListener('error', this.#onError);
-    }
-    this.#img = null;
-    this.#skeleton = null;
-  }
-}
-customElements.define('image-ui', UIImage);
+defineIfFree('image-ui', UIImage);
 
 export { UIImage };

package/components/image/image.yaml

@@ -7,6 +7,10 @@ component: Image
 category: display
 version: 1
 description: Lazy-loading image with skeleton fallback. Shows skeleton while loading, falls back on error.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - skeleton-ui
 props:
   alt:
     description: Alt text for the image.

package/components/index.js

@@ -9,6 +9,14 @@
    list-ui). See packages/web-components/core/data-stream.js. */
 import '../core/data-stream.js';
 
+/* Side-effect import — wires the full @phosphor-icons/core asset tree
+   into the icon registry (`core/icons.js`). Consumers who load the
+   components barrel are loading ~90 elements; pulling phosphor along is
+   the zero-config expectation. Apps with bundle-size SLOs should skip
+   this barrel, import primitives piecemeal, and call
+   `installIconLoaders()` with a scoped glob — see `core/icons.js` JSDoc. */
+import '../core/icons-phosphor.js';
+
 export { UIIcon } from './icon/icon.js';
 export { UIButton } from './button/button.js';
 export { UILink } from './link/link.js';