@adia-ai/web-components 0.4.6 → 0.4.8

package/components/inspector/class.js

@@ -0,0 +1,142 @@
+/**
+ * Non-side-effect class export for `<inspector-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/inspector`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { UIElement } from '../../core/element.js';
+import { registry } from '@adia-ai/a2ui-runtime';
+import '../tabs/tabs.js';
+import '../tabs/tab.js';
+import '../code/code.js';
+
+/**
+ * <inspector-ui> — Developer tools pane for inspecting A2UI state.
+ *
+ * Composes <tabs-ui> with four panes:
+ *   Catalog  — A2UI registry type-to-tag mapping
+ *   Surface  — current surface schema (JSON)
+ *   Messages — message log
+ *   Code     — rendered HTML
+ *
+ * Usage (declarative — initial surface payload):
+ *   <inspector-ui>
+ *     { "hello": "world" }
+ *   </inspector-ui>
+ *
+ * Usage (imperative):
+ *   const inspector = document.querySelector('inspector-ui');
+ *   inspector.update(schema, messages);
+ *   inspector.setHTML(renderedHTML);
+ *
+ * Attributes:
+ *   value — active tab: 'catalog' | 'surface' | 'messages' | 'code'
+ *           (default: 'surface')
+ */
+export class UIInspector extends UIElement {
+  static properties = {
+    value: { type: String, default: 'surface', reflect: true },
+  };
+
+  static template = () => null;
+
+  #tabs = null;
+  #panes = {};
+
+  connected() {
+    const declarative = this.textContent?.trim() || '';
+    this.innerHTML = '';
+    this.#build(declarative);
+  }
+
+  disconnected() {
+    this.#tabs?.removeEventListener('change', this.#onChange);
+    this.#tabs = null;
+    this.#panes = {};
+  }
+
+  render() {
+    if (this.#tabs && this.#tabs.getAttribute('value') !== this.value) {
+      this.#tabs.setAttribute('value', this.value);
+    }
+  }
+
+  #onChange = (e) => {
+    if (e.detail?.value && e.detail.value !== this.value) {
+      this.value = e.detail.value;
+    }
+  };
+
+  #build(initialSurface) {
+    const catalogText = [...registry.entries()]
+      .map(([type, tag]) => `${type} → <${tag}>`)
+      .join('\n');
+
+    this.#tabs = document.createElement('tabs-ui');
+    this.#tabs.setAttribute('value', this.value || 'surface');
+    this.#tabs.addEventListener('change', this.#onChange);
+
+    this.#addPane('catalog', `Catalog (${registry.size})`, catalogText);
+    this.#addPane('surface', 'Surface', initialSurface || '{}', { language: 'json' });
+    this.#addPane('messages', 'Messages', '(no messages)');
+    this.#addPane('code', 'Code', '(empty)', { language: 'html', lineNumbers: true });
+
+    this.appendChild(this.#tabs);
+  }
+
+  #addPane(value, text, body, opts = {}) {
+    const tab = document.createElement('tab-ui');
+    tab.setAttribute('value', value);
+    tab.setAttribute('text', text);
+
+    const pane = document.createElement('code-ui');
+    if (opts.language) pane.setAttribute('language', opts.language);
+    if (opts.lineNumbers) pane.setAttribute('line-numbers', '');
+    pane.setAttribute('text', body);
+
+    tab.appendChild(pane);
+    this.#tabs.appendChild(tab);
+    this.#panes[value] = pane;
+  }
+
+  /**
+   * Refresh the surface state and message log.
+   * @param {object} schema — surface schema object (JSON-serializable)
+   * @param {object[]} messages — array of A2UI messages
+   */
+  update(schema, messages) {
+    if (this.#panes.surface) {
+      this.#panes.surface.setAttribute('text', JSON.stringify(schema, null, 2));
+    }
+    if (this.#panes.messages) {
+      const log = Array.isArray(messages) && messages.length
+        ? messages
+            .map((m, i) => `${i + 1}. ${m.type || m.messageType || 'unknown'}${m.surfaceId ? ` [${m.surfaceId}]` : ''}`)
+            .join('\n')
+        : '(no messages)';
+      this.#panes.messages.setAttribute('text', log);
+    }
+    const msgTab = this.#tabs?.querySelector('tab-ui[value="messages"]');
+    if (msgTab) {
+      const count = Array.isArray(messages) ? messages.length : 0;
+      msgTab.setAttribute('text', `Messages (${count})`);
+    }
+  }
+
+  /**
+   * Update the Code tab.
+   * @param {string} html — HTML string to display
+   */
+  setHTML(html) {
+    if (this.#panes.code) {
+      this.#panes.code.setAttribute('text', html || '(empty)');
+    }
+  }
+}

package/components/inspector/inspector.a2ui.json

@@ -29,6 +29,11 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "agent",
+    "composes": [
+      "tabs-ui",
+      "tab-ui",
+      "code-ui"
+    ],
     "events": {},
     "examples": [
       {
@@ -53,7 +58,14 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "tags": [
+        "object-inspector",
+        "property-grid",
+        "record-detail",
+        "devtools-pane"
+      ]
+    },
     "tag": "inspector-ui",
     "tokens": {},
     "traits": [],

package/components/inspector/inspector.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `<inspector-ui>` — Developer tools pane for inspecting A2UI state.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/inspector
+ *
+ * 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 UIInspector extends UIElement {
+  /** Active tab. One of 'catalog', 'surface', 'messages', 'code'. */
+  value: string;
+}

package/components/inspector/inspector.js

@@ -1,133 +1,17 @@
-import { UIElement } from '../../core/element.js';
-import { registry } from '@adia-ai/a2ui-runtime';
-import '../tabs/tabs.js';
-import '../tabs/tab.js';
-import '../code/code.js';
-
 /**
- * <inspector-ui> — Developer tools pane for inspecting A2UI state.
- *
- * Composes <tabs-ui> with four panes:
- *   Catalog  — A2UI registry type-to-tag mapping
- *   Surface  — current surface schema (JSON)
- *   Messages — message log
- *   Code     — rendered HTML
+ * `<inspector-ui>` — auto-registers the tag on import.
  *
- * Usage (declarative — initial surface payload):
- *   <inspector-ui>
- *     { "hello": "world" }
- *   </inspector-ui>
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Usage (imperative):
- *   const inspector = document.querySelector('inspector-ui');
- *   inspector.update(schema, messages);
- *   inspector.setHTML(renderedHTML);
+ *   import { UIInspector } from '@adia-ai/web-components/components/inspector/class';
  *
- * Attributes:
- *   value — active tab: 'catalog' | 'surface' | 'messages' | 'code'
- *           (default: 'surface')
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
-class UIInspector extends UIElement {
-  static properties = {
-    value: { type: String, default: 'surface', reflect: true },
-  };
-
-  static template = () => null;
-
-  #tabs = null;
-  #panes = {};
-
-  connected() {
-    const declarative = this.textContent?.trim() || '';
-    this.innerHTML = '';
-    this.#build(declarative);
-  }
-
-  disconnected() {
-    this.#tabs?.removeEventListener('change', this.#onChange);
-    this.#tabs = null;
-    this.#panes = {};
-  }
-
-  render() {
-    if (this.#tabs && this.#tabs.getAttribute('value') !== this.value) {
-      this.#tabs.setAttribute('value', this.value);
-    }
-  }
-
-  #onChange = (e) => {
-    if (e.detail?.value && e.detail.value !== this.value) {
-      this.value = e.detail.value;
-    }
-  };
-
-  #build(initialSurface) {
-    const catalogText = [...registry.entries()]
-      .map(([type, tag]) => `${type} → <${tag}>`)
-      .join('\n');
-
-    this.#tabs = document.createElement('tabs-ui');
-    this.#tabs.setAttribute('value', this.value || 'surface');
-    this.#tabs.addEventListener('change', this.#onChange);
-
-    this.#addPane('catalog', `Catalog (${registry.size})`, catalogText);
-    this.#addPane('surface', 'Surface', initialSurface || '{}', { language: 'json' });
-    this.#addPane('messages', 'Messages', '(no messages)');
-    this.#addPane('code', 'Code', '(empty)', { language: 'html', lineNumbers: true });
-
-    this.appendChild(this.#tabs);
-  }
-
-  #addPane(value, text, body, opts = {}) {
-    const tab = document.createElement('tab-ui');
-    tab.setAttribute('value', value);
-    tab.setAttribute('text', text);
-
-    const pane = document.createElement('code-ui');
-    if (opts.language) pane.setAttribute('language', opts.language);
-    if (opts.lineNumbers) pane.setAttribute('line-numbers', '');
-    pane.setAttribute('text', body);
-
-    tab.appendChild(pane);
-    this.#tabs.appendChild(tab);
-    this.#panes[value] = pane;
-  }
-
-  /**
-   * Refresh the surface state and message log.
-   * @param {object} schema — surface schema object (JSON-serializable)
-   * @param {object[]} messages — array of A2UI messages
-   */
-  update(schema, messages) {
-    if (this.#panes.surface) {
-      this.#panes.surface.setAttribute('text', JSON.stringify(schema, null, 2));
-    }
-    if (this.#panes.messages) {
-      const log = Array.isArray(messages) && messages.length
-        ? messages
-            .map((m, i) => `${i + 1}. ${m.type || m.messageType || 'unknown'}${m.surfaceId ? ` [${m.surfaceId}]` : ''}`)
-            .join('\n')
-        : '(no messages)';
-      this.#panes.messages.setAttribute('text', log);
-    }
-    const msgTab = this.#tabs?.querySelector('tab-ui[value="messages"]');
-    if (msgTab) {
-      const count = Array.isArray(messages) ? messages.length : 0;
-      msgTab.setAttribute('text', `Messages (${count})`);
-    }
-  }
 
-  /**
-   * Update the Code tab.
-   * @param {string} html — HTML string to display
-   */
-  setHTML(html) {
-    if (this.#panes.code) {
-      this.#panes.code.setAttribute('text', html || '(empty)');
-    }
-  }
-}
+import { defineIfFree } from '../../core/register.js';
+import { UIInspector } from './class.js';
 
-customElements.define('inspector-ui', UIInspector);
+defineIfFree('inspector-ui', UIInspector);
 
 export { UIInspector };

package/components/inspector/inspector.yaml

@@ -1,5 +1,3 @@
-# Generated by scripts/migrate-yamls-to-v1.mjs — migrated to v1 contract.
-# Edit this file; run `npm run build:components` to regenerate a2ui.json.
 $schema: ../../../../scripts/schemas/component.yaml.schema.json
 name: UIInspector
 tag: inspector-ui
@@ -7,6 +5,12 @@ component: Inspector
 category: agent
 version: 1
 description: Developer tools pane for inspecting A2UI state.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - tabs-ui
+  - tab-ui
+  - code-ui
 props:
   value:
     description: Active tab. One of 'catalog', 'surface', 'messages', 'code'.
@@ -15,40 +19,27 @@ props:
 events: {}
 slots:
   default:
-    description: "Default slot — primary child content."
+    description: Default slot — primary child content.
 states:
-  - name: idle
-    description: Default, ready for interaction.
+- name: idle
+  description: Default, ready for interaction.
 traits: []
 tokens: {}
 a2ui:
   rules: []
 anti_patterns: []
 examples:
-  - name: basic-inspector
-    description: Basic Inspector usage
-    a2ui: >-
-      [
-        {
-          "id": "root",
-          "component": "Card",
-          "children": [
-            "sec"
-          ]
-        },
-        {
-          "id": "sec",
-          "component": "Section",
-          "children": [
-            "comp"
-          ]
-        },
-        {
-          "id": "comp",
-          "component": "Inspector"
-        }
-      ]
+- name: basic-inspector
+  description: Basic Inspector usage
+  a2ui: "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"sec\"\n    ]\n  },\n  {\n\
+    \    \"id\": \"sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"comp\"\n    ]\n  },\n  {\n    \"\
+    id\": \"comp\",\n    \"component\": \"Inspector\"\n  }\n]"
 keywords:
-  - inspector
-synonyms: {}
+- inspector
+synonyms:
+  tags:
+  - object-inspector
+  - property-grid
+  - record-detail
+  - devtools-pane
 related: []

package/components/kbd/class.js

@@ -0,0 +1,34 @@
+/**
+ * Non-side-effect class export for `<kbd-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/kbd`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <kbd-ui>⌘</kbd-ui><kbd-ui>K</kbd-ui>
+ * <kbd-ui>Ctrl+C</kbd-ui>
+ *
+ * Keyboard key cap. Purely decorative — content comes from innerHTML.
+ * Em-relative sizing so it scales with surrounding text.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIKbd extends UIElement {
+  static properties = {
+    size: { type: String, default: '', reflect: true },
+  };
+
+  static template = () => null;
+
+  connected() {
+    this.setAttribute('role', 'presentation');
+  }
+}

package/components/kbd/kbd.a2ui.json

@@ -33,6 +33,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "display",
+    "composes": [],
     "events": {},
     "examples": [
       {
@@ -90,6 +91,9 @@
         "kbd",
         "shortcut",
         "command"
+      ],
+      "tags": [
+        "Keyboard"
       ]
     },
     "tag": "kbd-ui",

package/components/kbd/kbd.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `<kbd-ui>` — Keyboard key cap. Purely decorative, content from innerHTML.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/kbd
+ *
+ * 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 UIKbd extends UIElement {
+  /** Sizing scale (compact tier — sm / md only). */
+  size: 'sm' | 'md';
+}

package/components/kbd/kbd.js

@@ -1,24 +1,17 @@
 /**
- * <kbd-ui>⌘</kbd-ui><kbd-ui>K</kbd-ui>
- * <kbd-ui>Ctrl+C</kbd-ui>
+ * `<kbd-ui>` — auto-registers the tag on import.
  *
- * Keyboard key cap. Purely decorative — content comes from innerHTML.
- * Em-relative sizing so it scales with surrounding text.
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UIKbd } from '@adia-ai/web-components/components/kbd/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
-
-class UIKbd extends UIElement {
-  static properties = {
-    size: { type: String, default: '', reflect: true },
-  };
-
-  static template = () => null;
+import { defineIfFree } from '../../core/register.js';
+import { UIKbd } from './class.js';
 
-  connected() {
-    this.setAttribute('role', 'presentation');
-  }
-}
-customElements.define('kbd-ui', UIKbd);
+defineIfFree('kbd-ui', UIKbd);
 
 export { UIKbd };