@adia-ai/web-components 0.4.6 → 0.4.8

package/components/block/class.js

@@ -0,0 +1,33 @@
+/**
+ * Non-side-effect class export for `<block-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/block`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <block-ui padding="md" margin="lg">Content here</block-ui>
+ *
+ * Generic padded/margined content wrapper. Pure CSS component.
+ *
+ * Properties:
+ *   padding — none | xs | sm | md | lg | xl (default 'md')
+ *   margin  — none | xs | sm | md | lg | xl (default 'none')
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIBlock extends UIElement {
+  static properties = {
+    padding: { type: String, default: 'md',   reflect: true },
+    margin:  { type: String, default: 'none', reflect: true },
+  };
+
+  static template = () => null;
+}

package/components/breadcrumb/breadcrumb.a2ui.json

@@ -44,6 +44,11 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "navigation",
+    "composes": [
+      "menu-ui",
+      "button-ui",
+      "menu-item-ui"
+    ],
     "events": {},
     "examples": [
       {

package/components/breadcrumb/breadcrumb.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `<breadcrumb-ui>` — Breadcrumb trail with auto-inserted separators. Supports a leading icon (first child) and an overflow popover that collapses middle crumbs into a `…` menu.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/breadcrumb
+ *
+ * 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 UIBreadcrumb extends UIElement {
+  /** Collapse middle crumbs into a `…` overflow popover when there are 4+ items. */
+  collapse: boolean;
+  /** Number of leading items to keep visible when [collapse] is active. The first item (often a home/icon link) sits before the overflow popover. */
+  collapseKeepLeading: number;
+  /** Number of trailing items to keep visible when [collapse] is active. The last item is always the current page. */
+  collapseKeepTrailing: number;
+  /** Character or string rendered between breadcrumb items via CSS ::before. */
+  separator: string;
+}

package/components/breadcrumb/breadcrumb.js

@@ -1,122 +1,17 @@
 /**
- * <breadcrumb-ui separator="/">
- *   <a href="/"><icon-ui name="house"></icon-ui></a>
- *   <a href="#">Workspace</a>
- *   <span>Current page</span>
- * </breadcrumb-ui>
+ * `<breadcrumb-ui>` — auto-registers the tag on import.
  *
- * Trail with auto-inserted separators. Items can be plain elements or
- * `<a href>` links; the last item is marked `aria-current="page"`.
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Variants:
- *   • Default — text-only crumbs
- *   • Icon-leading — first child is `<icon-ui>` (or a link wrapping one)
- *   • Collapsed — `[collapse]` hides middle crumbs into a `…` overflow
- *     popover; keeps `[collapse-keep-leading]` (default 1) and
- *     `[collapse-keep-trailing]` (default 2) visible at the edges.
+ *   import { UIBreadcrumb } from '@adia-ai/web-components/components/breadcrumb/class';
  *
- * The overflow uses `<popover-ui>` so it rides the top-layer (no
- * z-index battles inside scrolling containers).
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
+import { defineIfFree } from '../../core/register.js';
+import { UIBreadcrumb } from './class.js';
 
-class UIBreadcrumb extends UIElement {
-  static properties = {
-    separator:            { type: String,  default: '/', reflect: true },
-    collapse:             { type: Boolean, default: false, reflect: true },
-    collapseKeepLeading:  { type: Number,  default: 1, attribute: 'collapse-keep-leading', reflect: true },
-    collapseKeepTrailing: { type: Number,  default: 2, attribute: 'collapse-keep-trailing', reflect: true },
-  };
+defineIfFree('breadcrumb-ui', UIBreadcrumb);
 
-  static template = () => null;
-
-  connected() {
-    this.setAttribute('role', 'navigation');
-    this.setAttribute('aria-label', 'Breadcrumb');
-  }
-
-  render() {
-    // Strip prior chrome so render is idempotent across attribute changes.
-    this.querySelectorAll('[data-sep], [data-overflow]').forEach(el => el.remove());
-
-    const items = Array.from(this.children).filter(c =>
-      !c.hasAttribute('data-sep') && !c.hasAttribute('data-overflow')
-    );
-    const last = items.length - 1;
-
-    // Reset per-item chrome
-    items.forEach((child, i) => {
-      child.setAttribute('data-item', '');
-      child.removeAttribute('data-collapsed');
-      if (i === last) child.setAttribute('aria-current', 'page');
-      else child.removeAttribute('aria-current');
-    });
-
-    const keepLeading  = Math.max(0, this.collapseKeepLeading | 0);
-    const keepTrailing = Math.max(0, this.collapseKeepTrailing | 0);
-    const minLen = keepLeading + keepTrailing + 1;
-    const shouldCollapse = this.collapse && items.length >= Math.max(minLen, 4);
-
-    if (shouldCollapse) {
-      const collapsed = items.slice(keepLeading, items.length - keepTrailing);
-      collapsed.forEach(el => el.setAttribute('data-collapsed', ''));
-
-      const overflow = this.#buildOverflow(collapsed);
-      if (keepLeading > 0) items[keepLeading - 1].after(overflow);
-      else this.prepend(overflow);
-    }
-
-    // Stamp separators between every consecutive visible sibling.
-    const visible = Array.from(this.children).filter(c =>
-      !c.hasAttribute('data-sep') && !c.hasAttribute('data-collapsed')
-    );
-    for (let i = 0; i < visible.length - 1; i++) {
-      const sep = document.createElement('span');
-      sep.setAttribute('data-sep', '');
-      sep.setAttribute('aria-hidden', 'true');
-      sep.textContent = this.separator;
-      visible[i].after(sep);
-    }
-  }
-
-  #buildOverflow(collapsedItems) {
-    // Use <menu-ui> as the canonical popover-list primitive — same surface
-    // tokens as select-ui's listbox + menu-ui's action menu, with keyboard
-    // nav, top-layer rendering, and anchor positioning for free.
-    const menu = document.createElement('menu-ui');
-    menu.setAttribute('data-overflow', '');
-    menu.setAttribute('data-item', '');
-    menu.setAttribute('placement', 'bottom-start');
-
-    const trigger = document.createElement('button-ui');
-    trigger.setAttribute('slot', 'trigger');
-    trigger.setAttribute('text', '…');
-    trigger.setAttribute('variant', 'ghost');
-    trigger.setAttribute('size', 'sm');
-    trigger.setAttribute('aria-label', 'Show collapsed crumbs');
-    menu.appendChild(trigger);
-
-    for (const item of collapsedItems) {
-      const mi = document.createElement('menu-item-ui');
-      mi.setAttribute('text', item.textContent.trim());
-      // Encode the link target as the menu-item value; navigated on action.
-      if (item.tagName === 'A' && item.hasAttribute('href')) {
-        mi.setAttribute('value', item.getAttribute('href'));
-      }
-      menu.appendChild(mi);
-    }
-
-    // menu-ui dispatches `action` with `detail: { value, text }` on item
-    // activation. Navigate to the encoded href; ignore placeholder `#`.
-    menu.addEventListener('action', (e) => {
-      const href = e.detail?.value;
-      if (href && href !== '#') window.location.href = href;
-    });
-
-    return menu;
-  }
-}
-
-customElements.define('breadcrumb-ui', UIBreadcrumb);
 export { UIBreadcrumb };

package/components/breadcrumb/breadcrumb.yaml

@@ -7,6 +7,12 @@ component: Breadcrumb
 category: navigation
 version: 1
 description: Breadcrumb trail with auto-inserted separators. Supports a leading icon (first child) and an overflow popover that collapses middle crumbs into a `…` menu.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - menu-ui
+  - button-ui
+  - menu-item-ui
 props:
   separator:
     description: Character or string rendered between breadcrumb items via CSS ::before.

package/components/breadcrumb/class.js

@@ -0,0 +1,132 @@
+/**
+ * Non-side-effect class export for `<breadcrumb-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/breadcrumb`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <breadcrumb-ui separator="/">
+ *   <a href="/"><icon-ui name="house"></icon-ui></a>
+ *   <a href="#">Workspace</a>
+ *   <span>Current page</span>
+ * </breadcrumb-ui>
+ *
+ * Trail with auto-inserted separators. Items can be plain elements or
+ * `<a href>` links; the last item is marked `aria-current="page"`.
+ *
+ * Variants:
+ *   • Default — text-only crumbs
+ *   • Icon-leading — first child is `<icon-ui>` (or a link wrapping one)
+ *   • Collapsed — `[collapse]` hides middle crumbs into a `…` overflow
+ *     popover; keeps `[collapse-keep-leading]` (default 1) and
+ *     `[collapse-keep-trailing]` (default 2) visible at the edges.
+ *
+ * The overflow uses `<popover-ui>` so it rides the top-layer (no
+ * z-index battles inside scrolling containers).
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIBreadcrumb extends UIElement {
+  static properties = {
+    separator:            { type: String,  default: '/', reflect: true },
+    collapse:             { type: Boolean, default: false, reflect: true },
+    collapseKeepLeading:  { type: Number,  default: 1, attribute: 'collapse-keep-leading', reflect: true },
+    collapseKeepTrailing: { type: Number,  default: 2, attribute: 'collapse-keep-trailing', reflect: true },
+  };
+
+  static template = () => null;
+
+  connected() {
+    this.setAttribute('role', 'navigation');
+    this.setAttribute('aria-label', 'Breadcrumb');
+  }
+
+  render() {
+    // Strip prior chrome so render is idempotent across attribute changes.
+    this.querySelectorAll('[data-sep], [data-overflow]').forEach(el => el.remove());
+
+    const items = Array.from(this.children).filter(c =>
+      !c.hasAttribute('data-sep') && !c.hasAttribute('data-overflow')
+    );
+    const last = items.length - 1;
+
+    // Reset per-item chrome
+    items.forEach((child, i) => {
+      child.setAttribute('data-item', '');
+      child.removeAttribute('data-collapsed');
+      if (i === last) child.setAttribute('aria-current', 'page');
+      else child.removeAttribute('aria-current');
+    });
+
+    const keepLeading  = Math.max(0, this.collapseKeepLeading | 0);
+    const keepTrailing = Math.max(0, this.collapseKeepTrailing | 0);
+    const minLen = keepLeading + keepTrailing + 1;
+    const shouldCollapse = this.collapse && items.length >= Math.max(minLen, 4);
+
+    if (shouldCollapse) {
+      const collapsed = items.slice(keepLeading, items.length - keepTrailing);
+      collapsed.forEach(el => el.setAttribute('data-collapsed', ''));
+
+      const overflow = this.#buildOverflow(collapsed);
+      if (keepLeading > 0) items[keepLeading - 1].after(overflow);
+      else this.prepend(overflow);
+    }
+
+    // Stamp separators between every consecutive visible sibling.
+    const visible = Array.from(this.children).filter(c =>
+      !c.hasAttribute('data-sep') && !c.hasAttribute('data-collapsed')
+    );
+    for (let i = 0; i < visible.length - 1; i++) {
+      const sep = document.createElement('span');
+      sep.setAttribute('data-sep', '');
+      sep.setAttribute('aria-hidden', 'true');
+      sep.textContent = this.separator;
+      visible[i].after(sep);
+    }
+  }
+
+  #buildOverflow(collapsedItems) {
+    // Use <menu-ui> as the canonical popover-list primitive — same surface
+    // tokens as select-ui's listbox + menu-ui's action menu, with keyboard
+    // nav, top-layer rendering, and anchor positioning for free.
+    const menu = document.createElement('menu-ui');
+    menu.setAttribute('data-overflow', '');
+    menu.setAttribute('data-item', '');
+    menu.setAttribute('placement', 'bottom-start');
+
+    const trigger = document.createElement('button-ui');
+    trigger.setAttribute('slot', 'trigger');
+    trigger.setAttribute('text', '…');
+    trigger.setAttribute('variant', 'ghost');
+    trigger.setAttribute('size', 'sm');
+    trigger.setAttribute('aria-label', 'Show collapsed crumbs');
+    menu.appendChild(trigger);
+
+    for (const item of collapsedItems) {
+      const mi = document.createElement('menu-item-ui');
+      mi.setAttribute('text', item.textContent.trim());
+      // Encode the link target as the menu-item value; navigated on action.
+      if (item.tagName === 'A' && item.hasAttribute('href')) {
+        mi.setAttribute('value', item.getAttribute('href'));
+      }
+      menu.appendChild(mi);
+    }
+
+    // menu-ui dispatches `action` with `detail: { value, text }` on item
+    // activation. Navigate to the encoded href; ignore placeholder `#`.
+    menu.addEventListener('action', (e) => {
+      const href = e.detail?.value;
+      if (href && href !== '#') window.location.href = href;
+    });
+
+    return menu;
+  }
+}

package/components/button/button.a2ui.json

@@ -98,6 +98,9 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "action",
+    "composes": [
+      "icon-ui"
+    ],
     "events": {
       "press": {
         "description": "Fired on complete press (pointer up or Enter/Space)"

package/components/button/button.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `<button-ui>` — Clickable button with text, icon, and variant support. Supports submit type for forms.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/button
+ *
+ * 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 ButtonPressEvent = CustomEvent<unknown>;
+
+export class UIButton extends UIElement {
+  /** HTML button type (button, submit, reset) */
+  type: string;
+  /** Semantic intent — composes with [variant]. `<button-ui variant="solid" color="danger">` = filled destructive action; `<button-ui variant="outline" color="success">` = outlined success affordance. */
+  color: 'default' | 'accent' | 'info' | 'success' | 'warning' | 'danger';
+  /** Disables interaction and prevents click/press events */
+  disabled: boolean;
+  /** Leading Phosphor icon name (rendered before text). */
+  icon: string;
+  /** Sizing scale (xs/sm/md/lg/xl). */
+  size: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  /** Makes the button stretch to fill the parent's width */
+  stretch: boolean;
+  /** Button text, rendered via CSS attr(text) on ::after */
+  text: string;
+  /** Button label. Renderer routes this to the `text` attribute, which is rendered via CSS attr(text) on ::after and mirrored to aria-label. */
+  textContent: string;
+  /** Visual style — `solid` (default fill), `outline`, `ghost`. `default` / `primary` are aliases of `solid`. Style is independent of semantic intent — to express destructive / success / info / warning intent, set [color="…"] alongside.
+For **inline navigation** (Terms of Service, Privacy Policy, footer links, "Sign in" / "Sign up" cross-page affordances) use `<link-ui>` instead — it carries proper `<a href>` semantics, keyboard handling (Enter only, no Space), middle-click open-new-tab, and screen-reader announces "link" instead of "button". Mixing navigation and action affordances under the same primitive is a category error fixed at this junction. */
+  variant: 'default' | 'solid' | 'outline' | 'ghost' | 'primary' | 'secondary' | 'soft' | 'current';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIButton, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'press', listener: (ev: ButtonPressEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/components/button/button.js

@@ -1,68 +1,17 @@
-import { UIElement, signal, html } from '../../core/element.js';
-import { getIcon } from '../../core/icons.js';
-
-class UIButton extends UIElement {
-  static properties = {
-    text:     { type: String,  default: '', reflect: true },
-    textContent: { type: String, default: '' },
-    variant:  { type: String,  default: 'solid', reflect: true },
-    color:    { type: String,  default: '', reflect: true },
-    size:     { type: String,  default: 'md', reflect: true },
-    disabled: { type: Boolean, default: false, reflect: true },
-    stretch:  { type: Boolean, default: false, reflect: true },
-    icon:     { type: String,  default: '', reflect: true },
-    type:     { type: String,  default: 'button', reflect: true },
-  };
-
-  static template = () => null;
-
-  connected() {
-    this.setAttribute('role', 'button');
-    this.setAttribute('tabindex', '0');
-    this.addEventListener('click', this.#onClick);
-    this.addEventListener('keydown', this.#onKey);
-  }
-
-  render() {
-    // Don't clobber a user-provided aria-label with an empty string when
-    // text is unset (e.g. icon-only button with author-set aria-label).
-    // Only auto-set when we have meaningful text to put there.
-    if (this.text) this.setAttribute('aria-label', this.text);
-    if (this.icon) {
-      const existing = this.querySelector('icon-ui');
-      if (!existing || existing.name !== this.icon) {
-        if (existing) existing.remove();
-        const iconEl = document.createElement('icon-ui');
-        iconEl.setAttribute('name', this.icon);
-        this.prepend(iconEl);
-      }
-    }
-  }
-
-  #onClick = (e) => {
-    if (this.disabled) { e.stopPropagation(); return; }
-    if (this.type === 'submit') {
-      const form = this.closest('form');
-      if (form?.requestSubmit) form.requestSubmit();
-    } else if (this.type === 'reset') {
-      const form = this.closest('form');
-      if (form?.reset) form.reset();
-    }
-    this.dispatchEvent(new Event('press', { bubbles: true }));
-  };
-
-  #onKey = (e) => {
-    if (e.key === 'Enter' || e.key === ' ') {
-      e.preventDefault();
-      this.click();
-    }
-  };
-
-  disconnected() {
-    this.removeEventListener('click', this.#onClick);
-    this.removeEventListener('keydown', this.#onKey);
-  }
-}
-customElements.define('button-ui', UIButton);
+/**
+ * `<button-ui>` — auto-registers the tag on import.
+ *
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UIButton } from '@adia-ai/web-components/components/button/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { defineIfFree } from '../../core/register.js';
+import { UIButton } from './class.js';
+
+defineIfFree('button-ui', UIButton);
 
 export { UIButton };

package/components/button/button.yaml

@@ -7,6 +7,11 @@ component: Button
 category: action
 version: 1
 description: Clickable button with text, icon, and variant support. Supports submit type for forms.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# in their render() do NOT auto-import them. Consumer (or demo shell) must
+# explicitly import each composed primitive.
+composes:
+  - icon-ui  # created via document.createElement('icon-ui') when [icon] is set
 props:
   aria-label:
     description: Accessible label for screen readers. Auto-set from `text` when text is non-empty; meaningful override for icon-only buttons.

package/components/button/class.js

@@ -0,0 +1,80 @@
+/**
+ * `UIButton` class — non-side-effect export.
+ *
+ * Importing this file gives you the class without auto-registering the
+ * tag. Useful for:
+ *   - Test isolation (register under a different tag in a test)
+ *   - Subclassing with tag-name override
+ *   - Tree-shaking-conscious bundles that compose primitives selectively
+ *
+ * The auto-register path stays at `@adia-ai/web-components/components/button`
+ * (which imports this file + calls `customElements.define`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { UIElement, signal, html } from '../../core/element.js';
+import { getIcon } from '../../core/icons.js';
+
+export class UIButton extends UIElement {
+  static properties = {
+    text:     { type: String,  default: '', reflect: true },
+    textContent: { type: String, default: '' },
+    variant:  { type: String,  default: 'solid', reflect: true },
+    color:    { type: String,  default: '', reflect: true },
+    size:     { type: String,  default: 'md', reflect: true },
+    disabled: { type: Boolean, default: false, reflect: true },
+    stretch:  { type: Boolean, default: false, reflect: true },
+    icon:     { type: String,  default: '', reflect: true },
+    type:     { type: String,  default: 'button', reflect: true },
+  };
+
+  static template = () => null;
+
+  connected() {
+    this.setAttribute('role', 'button');
+    this.setAttribute('tabindex', '0');
+    this.addEventListener('click', this.#onClick);
+    this.addEventListener('keydown', this.#onKey);
+  }
+
+  render() {
+    // Don't clobber a user-provided aria-label with an empty string when
+    // text is unset (e.g. icon-only button with author-set aria-label).
+    // Only auto-set when we have meaningful text to put there.
+    if (this.text) this.setAttribute('aria-label', this.text);
+    if (this.icon) {
+      const existing = this.querySelector('icon-ui');
+      if (!existing || existing.name !== this.icon) {
+        if (existing) existing.remove();
+        const iconEl = document.createElement('icon-ui');
+        iconEl.setAttribute('name', this.icon);
+        this.prepend(iconEl);
+      }
+    }
+  }
+
+  #onClick = (e) => {
+    if (this.disabled) { e.stopPropagation(); return; }
+    if (this.type === 'submit') {
+      const form = this.closest('form');
+      if (form?.requestSubmit) form.requestSubmit();
+    } else if (this.type === 'reset') {
+      const form = this.closest('form');
+      if (form?.reset) form.reset();
+    }
+    this.dispatchEvent(new Event('press', { bubbles: true }));
+  };
+
+  #onKey = (e) => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      this.click();
+    }
+  };
+
+  disconnected() {
+    this.removeEventListener('click', this.#onClick);
+    this.removeEventListener('keydown', this.#onKey);
+  }
+}

package/components/calendar-picker/calendar-picker.a2ui.json

@@ -79,6 +79,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "input",
+    "composes": [],
     "events": {
       "change": {
         "description": "Fired when a date is selected"
@@ -130,7 +131,12 @@
         "name": "disabled"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "tags": [
+        "DateTimeInput",
+        "DatePicker"
+      ]
+    },
     "tag": "calendar-picker-ui",
     "tokens": {},
     "traits": [],