@adia-ai/web-components 0.0.1

package/README.md

@@ -0,0 +1,195 @@
+# @adia-ai/web-components
+
+Vanilla web components + A2UI runtime for AdiaUI. **80 light-DOM custom
+elements**, a reactive core, a trait system, and a renderer that turns
+A2UI protocol messages into live DOM.
+
+> This package ships UI atoms only. The generation pipeline lives in
+> [`@adia-ai/gen-ui`](../gen-ui); the pattern corpus in
+> [`@adia-ai/gen-ui-training`](../gen-ui-training); the MCP server in
+> [`@adia-ai/gen-ui-mcp`](../gen-ui-mcp).
+
+## Quick start
+
+```html
+<link rel="stylesheet" href="node_modules/@adia-ai/web-components/index.css" />
+
+<script type="module">
+  import '@adia-ai/web-components';   // registers every *-n tag
+</script>
+
+<card-ui>
+  <header>
+    <span slot="icon"><avatar-ui icon="user"></avatar-ui></span>
+    <span slot="heading"><text-ui strong>Hello</text-ui></span>
+  </header>
+  <section>Composition works out of the box — no framework.</section>
+</card-ui>
+```
+
+The package `sideEffects` entry keeps the import above from being
+tree-shaken; importing `index.js` side-effect-registers every component.
+
+## Layout
+
+```
+web-components/
+├── core/           — Reactivity + base classes
+│   ├── signals.js       signal() / computed() / effect() / batch() / untracked()
+│   ├── template.js      tagged templates: html, css, repeat, stamp
+│   ├── element.js       AdiaElement — light-DOM reactive base
+│   ├── form.js          AdiaFormElement — form-associated + validation
+│   ├── provider.js      global provider registration + router-ui
+│   ├── anchor.js        popover + anchor-positioning
+│   ├── markdown.js      lightweight markdown renderer
+│   └── transport.js     SSE / streaming helpers for LLM adapters
+│
+├── components/     — 80 *-n custom elements
+│   └── <tag>/
+│       ├── <tag>.js       class definition (extends AdiaElement)
+│       ├── <tag>.css      @scope(tag-ui) two-block: tokens + styles
+│       ├── <tag>.yaml     authoring contract (props, slots, events, examples)
+│       └── <tag>.a2ui.json  generated — do NOT edit
+│
+├── patterns/       — Higher-level compositions (tag: `adia-*`)
+│   ├── app-shell, app-nav, section-nav   — admin layout scaffolding
+│   ├── adia-chat, adia-editor, gen-ui    — LLM + editor + gen-UI patterns
+│   └── index.js                          — registers all patterns
+│
+├── traits/         — 40 composable behaviors via defineTrait()
+│                     (pressable, focusTrap, confetti, resizable, …)
+│
+├── a2ui/           — A2UI runtime (renderer + wiring)
+│   ├── renderer.js         consumes A2UI JSON, stamps component trees
+│   ├── registry.js         component-name → class map (aliases included)
+│   ├── wiring-engine.js    binds controllers (toggle, form, data-stream)
+│   ├── wiring-registry.js  declarative event/data wiring catalog
+│   ├── surface.js          <canvas-ui> + <a2ui-root> hosts
+│   ├── stream.js           streamed-UI incremental hydration
+│   └── manifest-runtime.js surface manifest loader
+│
+├── styles/         — Global tokens and CSS layering
+│   ├── tokens.css              all --a-* design tokens
+│   ├── colors/                 primitives / semantics / scrims
+│   ├── typography.css, space.css, radius.css, shadow.css
+│   └── themes/*.css            8 themes (ocean, forest, sunset, …)
+│
+└── scripts/        — Build + dev utilities
+    └── build-components.mjs    YAML → .a2ui.json per-component
+```
+
+## Component contract
+
+Every component is a single-file class extending `AdiaElement` (or
+`AdiaFormElement` for form fields). All styling lives in a sibling `.css`
+file using **two-block `@scope`**:
+
+```css
+@scope (button-ui) {
+  :where(:scope) {
+    /* Tokens only — zero specificity, parent overrides win */
+    --button-bg:     var(--a-accent-bg);
+    --button-fg:     var(--a-accent-fg);
+    --button-radius: var(--a-radius);
+  }
+  :scope {
+    /* Styles — consume component tokens only, never global directly */
+    background: var(--button-bg);
+    color:      var(--button-fg);
+    border-radius: var(--button-radius);
+  }
+  :scope[variant="danger"] {
+    --button-bg: var(--a-danger-bg);   /* variants override tokens, not styles */
+  }
+}
+```
+
+Authoring rules (enforced by `coherence-audit`):
+
+1. **No raw colors** in component CSS — every color goes through a token.
+2. **Variants change tokens, modes change layout.** A selector that sets
+   `display`, `padding`, `flex`, `grid`, etc. is a *mode* and needs a
+   Sanctioned Mode Attributes entry in the contract doc.
+3. **Boolean props default to `false`.** If the expected default is "on",
+   flip the name (`closable` → `permanent`).
+4. **Event listeners in `connected()` have matching `removeEventListener`
+   in `disconnected()`.** Handlers are stable `#field` arrows, never
+   inline.
+5. **Light DOM only.** No `::part()`, `::slotted()`, shadow roots. Use
+   attribute selectors on children: `:scope > [slot="icon"]`.
+
+Full authoring contract: [`docs/specs/component-token-contract.md`](../../docs/specs/component-token-contract.md).
+The `adia-ui-author` skill encodes the 20 non-negotiable rules.
+
+## Card-n / drawer-ui composition parity
+
+Both accept bare `<header>` / `<section>` / `<footer>` tags OR explicit
+`[slot="header|body|footer"]`. Both activate a 3-column header grid when
+any direct `[slot="icon|heading|description|action"]` child is present
+(`:has(> …)` — direct-child only). Drawer supports multi-section bodies
+with sticky header/footer. See the drawer component page for worked
+examples.
+
+## A2UI runtime
+
+```javascript
+import { A2UIRenderer } from '@adia-ai/web-components/a2ui';
+
+const renderer = new A2UIRenderer({ target: document.getElementById('canvas') });
+renderer.apply({
+  type: 'updateComponents',
+  components: [
+    { id: 'root', component: 'Card', children: ['hdr', 'body'] },
+    { id: 'hdr',  component: 'Header', slots: { heading: 'Generated UI' } },
+    { id: 'body', component: 'Section', children: ['btn'] },
+    { id: 'btn',  component: 'Button', attrs: { variant: 'primary' }, content: 'Click' },
+  ],
+});
+```
+
+Accepts the four A2UI message kinds: `updateComponents`,
+`updateDataModel`, `wireComponents`, `createSurface`. The registry
+normalizes LLM-emitted aliases (e.g. `Carousel` → `swiper-ui`) so generated
+output is robust to name drift.
+
+## Build
+
+```bash
+npm run build:components    # regenerate all .a2ui.json from YAML
+```
+
+The build also writes `packages/gen-ui-training/catalog-a2ui_0_9.json` and
+`catalog-a2ui_0_9_rules.txt` — the flat-file catalog the MCP server and
+generation engine consume.
+
+## Themes, density, scale
+
+```html
+<div data-theme="ocean" density="compact" size="sm">
+  …all descendants re-theme / re-densify / re-scale automatically…
+</div>
+```
+
+- `[data-theme]` — 8 themes: `default`, `ocean`, `forest`, `sunset`,
+  `lavender`, `rose`, `slate`, `midnight`
+- `[density]` — `compact` (0.85×) · `spacious` (1.15×)
+- `[size]` — `sm`|`md`|`lg` shifts the entire typescale + component
+  dimensions
+- `[radius]` — `sharp` (0) · `rounded` (1) · `round` (2)
+
+Each is a CSS-variable override; no class toggles, no re-imports.
+
+## Dependency direction
+
+```
+gen-ui  ──reads──>  gen-ui-training  ←─reads──  web-components
+gen-ui-mcp  ──reads──>  gen-ui, gen-ui-training
+```
+
+Web-components never imports from gen-ui or gen-ui-mcp. The A2UI renderer
+consumes a protocol, not a generator — anything that emits valid A2UI
+messages drives it.
+
+## License
+
+MIT

package/a2ui/dockables/action.js

@@ -0,0 +1,152 @@
+/**
+ * ActionDock — Binds a AdiaEvent on a component to a handler.
+ *
+ * The AdiaEvent is a typed object: { event, target?, debounce?, throttle?, condition? }
+ * When the DOM event fires, the handler runs with the surface context.
+ * onSuccess/onError chains run follow-up handlers based on the outcome.
+ */
+import { Dockable } from './base.js';
+
+/**
+ * AdiaEvent type → DOM event name.
+ * AdiaUI components emit semantic events; these map to the actual DOM event to listen on.
+ */
+const NANO_TO_DOM = {
+  press:    'click',
+  submit:   'submit',
+  input:    'input',
+  change:   'change',
+  select:   'select',
+  toggle:   'change',
+  dismiss:  'close',
+  navigate: 'click',
+  mount:    'connectedCallback',
+  unmount:  'disconnectedCallback',
+  focus:    'focusin',
+  blur:     'focusout',
+  drag:     'dragstart',
+  drop:     'drop',
+};
+
+export { NANO_TO_DOM };
+
+export class ActionDock extends Dockable {
+  kind = 'action';
+
+  /** @type {string} */
+  id;
+
+  /** @type {{ event: string, target?: string, debounce?: number, throttle?: number, condition?: object }} */
+  event;
+
+  /** @type {string} handler name */
+  handler;
+
+  /** @type {object} handler config */
+  config;
+
+  /** @type {Array|null} follow-up actions on success */
+  onSuccess;
+
+  /** @type {Array|null} follow-up actions on error */
+  onError;
+
+  /** @type {Function} (handlerName) => handlerFn */
+  #resolveHandler;
+
+  /**
+   * @param {object} decl — { event, handler, config?, onSuccess?, onError? }
+   * @param {Function} resolveHandler — (name) => async (config, ctx) => result
+   */
+  constructor(decl, resolveHandler) {
+    super();
+    this.event = decl.event;
+    this.handler = decl.handler;
+    this.config = decl.config || {};
+    this.onSuccess = decl.onSuccess || null;
+    this.onError = decl.onError || null;
+    this.#resolveHandler = resolveHandler;
+
+    // Auto-generate id from event + target
+    this.id = `action:${this.event.event}:${this.event.target || 'root'}:${this.handler}`;
+  }
+
+  dock(ctx) {
+    const target = this.event.target
+      ? ctx.getElement(this.event.target)
+      : ctx.getRootElement();
+
+    if (!target) {
+      console.warn(`ActionDock: target "${this.event.target}" not found`);
+      return;
+    }
+
+    const domEventName = NANO_TO_DOM[this.event.event] || this.event.event;
+    const handlerFn = this.#resolveHandler(this.handler);
+
+    if (!handlerFn) {
+      console.warn(`ActionDock: unknown handler "${this.handler}"`);
+      return;
+    }
+
+    let listener = async (domEvent) => {
+      // Condition guard
+      if (this.event.condition) {
+        const val = ctx.getModel(this.event.condition.path);
+        if ('equals' in this.event.condition && val !== this.event.condition.equals) return;
+        if ('notEquals' in this.event.condition && val === this.event.condition.notEquals) return;
+        if ('exists' in this.event.condition && this.event.condition.exists && val == null) return;
+      }
+
+      try {
+        const result = await handlerFn(this.config, ctx, domEvent);
+
+        // Run onSuccess chain
+        if (this.onSuccess) {
+          for (const follow of this.onSuccess) {
+            const followFn = this.#resolveHandler(follow.handler);
+            if (followFn) await followFn(follow.config || {}, ctx, result);
+          }
+        }
+      } catch (err) {
+        // Run onError chain
+        if (this.onError) {
+          for (const follow of this.onError) {
+            const followFn = this.#resolveHandler(follow.handler);
+            if (followFn) await followFn(follow.config || {}, ctx, err);
+          }
+        } else {
+          console.error(`ActionDock: handler "${this.handler}" failed`, err);
+        }
+      }
+    };
+
+    // Debounce
+    if (this.event.debounce > 0) {
+      const origListener = listener;
+      let timer;
+      listener = (...args) => {
+        clearTimeout(timer);
+        timer = setTimeout(() => origListener(...args), this.event.debounce);
+      };
+    }
+
+    // Throttle
+    if (this.event.throttle > 0) {
+      const origListener = listener;
+      let last = 0;
+      listener = (...args) => {
+        const now = Date.now();
+        if (now - last >= this.event.throttle) {
+          last = now;
+          origListener(...args);
+        }
+      };
+    }
+
+    target.addEventListener(domEventName, listener);
+    return () => target.removeEventListener(domEventName, listener);
+  }
+
+  undock() {}
+}

package/a2ui/dockables/base.js

@@ -0,0 +1,30 @@
+/**
+ * Dockable — Base class for objects that attach to a Surface.
+ *
+ * Every dockable has:
+ *   kind — which port type it uses (controller, source, action, provider, lifecycle)
+ *   id   — unique identity within the surface
+ *   dock(context)  — attach and return cleanup function
+ *   undock()       — teardown
+ */
+export class Dockable {
+  /** @type {'controller'|'source'|'action'|'provider'|'lifecycle'} */
+  get kind() { throw new Error('Dockable subclass must define kind'); }
+
+  /** @type {string} */
+  get id() { throw new Error('Dockable subclass must define id'); }
+
+  /**
+   * Attach to a surface. Receives the surface context.
+   * Return a cleanup function, or void.
+   * @param {import('../surface.js').SurfaceContext} ctx
+   * @returns {(() => void)|void}
+   */
+  dock(ctx) { throw new Error('Dockable subclass must implement dock()'); }
+
+  /**
+   * Detach from the surface. Cleanup fn from dock() is called
+   * automatically before this.
+   */
+  undock() {}
+}

package/a2ui/dockables/controller.js

@@ -0,0 +1,97 @@
+/**
+ * ControllerDock — Wraps a AdiaUI controller as a dockable.
+ *
+ * Instantiates the controller, connects it to its host element,
+ * and sets up two-way binding between controller state and model paths.
+ */
+import { Dockable } from './base.js';
+
+export class ControllerDock extends Dockable {
+  kind = 'controller';
+
+  /** @type {string} */
+  id;
+
+  /** @type {string} controller type name, e.g., 'FormController' */
+  type;
+
+  /** @type {string} component id to attach to */
+  hostId;
+
+  /** @type {object} controller config */
+  config;
+
+  /** @type {object|null} model path bindings { stateKey: '/model/path' } */
+  bind;
+
+  /** @type {import('../../controllers/base.js').BaseController|null} */
+  controller = null;
+
+  /** @type {Function|null} resolve controller class */
+  #resolveClass;
+
+  /**
+   * @param {object} decl — { id, type, host, config?, bind? }
+   * @param {Function} resolveClass — async (type) => ControllerClass
+   */
+  constructor(decl, resolveClass) {
+    super();
+    this.id = decl.id;
+    this.type = decl.type;
+    this.hostId = decl.host;
+    this.config = decl.config || {};
+    this.bind = decl.bind || null;
+    this.#resolveClass = resolveClass;
+  }
+
+  async dock(ctx) {
+    const host = ctx.getElement(this.hostId);
+    if (!host) {
+      console.warn(`ControllerDock: host element "${this.hostId}" not found`);
+      return;
+    }
+
+    const ControllerClass = await this.#resolveClass(this.type);
+    if (!ControllerClass) {
+      console.warn(`ControllerDock: unknown controller type "${this.type}"`);
+      return;
+    }
+
+    this.controller = new ControllerClass(this.config);
+    this.controller.connect(host);
+
+    // Two-way bind: controller state ↔ model paths
+    const unbinders = [];
+    if (this.bind) {
+      for (const [stateKey, modelPath] of Object.entries(this.bind)) {
+        // Controller → model
+        if (this.controller.subscribe) {
+          const unsub = this.controller.subscribe(stateKey, (value) => {
+            ctx.setModel(modelPath, value);
+          });
+          if (unsub) unbinders.push(unsub);
+        }
+
+        // Model → controller (initial sync)
+        const initial = ctx.getModel(modelPath);
+        if (initial !== undefined && this.controller.setState) {
+          this.controller.setState(stateKey, initial);
+        }
+      }
+    }
+
+    host.controller = this.controller;
+
+    return () => {
+      host.controller = null;
+      unbinders.forEach(u => u());
+    };
+  }
+
+  undock() {
+    if (this.controller) {
+      this.controller.disconnect?.();
+      this.controller = null;
+    }
+  }
+}

package/a2ui/dockables/data-source.js

@@ -0,0 +1,103 @@
+/**
+ * DataSourceDock — Fetches data and pushes it into the surface model.
+ *
+ * Supports refresh strategies: once, on-focus, interval:{ms}, stream.
+ * Re-fetch on demand via refetch() (used by refresh-source handler).
+ */
+import { Dockable } from './base.js';
+
+export class DataSourceDock extends Dockable {
+  kind = 'source';
+
+  /** @type {string} */
+  id;
+
+  /** @type {string} URI template, e.g., "resource://users/{userId}" */
+  uri;
+
+  /** @type {string} model path to write to */
+  path;
+
+  /** @type {string} refresh strategy */
+  refresh;
+
+  /** @type {Function} (uri, params) => data */
+  #resolveData;
+
+  /** @type {import('../surface.js').SurfaceContext|null} */
+  #ctx = null;
+
+  /**
+   * @param {object} decl — { id, uri, path, refresh? }
+   * @param {Function} resolveData — async (uri, params) => data
+   */
+  constructor(decl, resolveData) {
+    super();
+    this.id = decl.id;
+    this.uri = decl.uri;
+    this.path = decl.path;
+    this.refresh = decl.refresh || 'once';
+    this.#resolveData = resolveData;
+  }
+
+  dock(ctx) {
+    this.#ctx = ctx;
+
+    // Initial fetch
+    this.#fetch(ctx);
+
+    // Refresh strategy
+    if (this.refresh === 'on-focus') {
+      const handler = () => this.#fetch(ctx);
+      window.addEventListener('focus', handler);
+      return () => window.removeEventListener('focus', handler);
+    }
+
+    if (this.refresh.startsWith('interval:')) {
+      const ms = parseInt(this.refresh.split(':')[1], 10);
+      if (ms > 0) {
+        const id = setInterval(() => this.#fetch(ctx), ms);
+        return () => clearInterval(id);
+      }
+    }
+
+    if (this.refresh === 'stream') {
+      const resolvedUri = this.#resolveUri(ctx);
+      try {
+        const source = new EventSource(resolvedUri);
+        source.onmessage = (e) => {
+          try { ctx.setModel(this.path, JSON.parse(e.data)); }
+          catch { /* malformed data */ }
+        };
+        return () => source.close();
+      } catch {
+        console.warn(`DataSourceDock: stream failed for ${resolvedUri}`);
+      }
+    }
+  }
+
+  undock() {
+    this.#ctx = null;
+  }
+
+  /** Re-fetch on demand (called by refresh-source handler). */
+  refetch() {
+    if (this.#ctx) this.#fetch(this.#ctx);
+  }
+
+  async #fetch(ctx) {
+    const resolvedUri = this.#resolveUri(ctx);
+    try {
+      const data = await this.#resolveData(resolvedUri, ctx);
+      if (data !== undefined) ctx.setModel(this.path, data);
+    } catch (err) {
+      console.warn(`DataSourceDock: fetch failed for ${resolvedUri}`, err);
+    }
+  }
+
+  #resolveUri(ctx) {
+    return this.uri.replace(/\{(\w+)\}/g, (_, key) => {
+      return ctx.getParam(key) ?? ctx.getModel('/' + key) ?? '';
+    });
+  }
+}

package/a2ui/dockables/index.js

@@ -0,0 +1,6 @@
+export { Dockable } from './base.js';
+export { ControllerDock } from './controller.js';
+export { DataSourceDock } from './data-source.js';
+export { ActionDock, NANO_TO_DOM } from './action.js';
+export { ProviderDock } from './provider.js';
+export { LifecycleDock } from './lifecycle.js';

package/a2ui/dockables/lifecycle.js

@@ -0,0 +1,84 @@
+/**
+ * LifecycleDock — Runs actions on mount, unmount, and model changes.
+ *
+ * One per surface. Fires onMount actions immediately on dock,
+ * watches model paths for changes, and runs onUnmount on undock.
+ */
+import { Dockable } from './base.js';
+
+export class LifecycleDock extends Dockable {
+  kind = 'lifecycle';
+  id = 'lifecycle';
+
+  /** @type {Array} actions to run on mount */
+  onMount;
+
+  /** @type {Array} actions to run on unmount */
+  onUnmount;
+
+  /** @type {Array} model path watchers */
+  onModelChange;
+
+  /** @type {Function} (handlerName) => handlerFn */
+  #resolveHandler;
+
+  /** @type {import('../surface.js').SurfaceContext|null} */
+  #ctx = null;
+
+  /**
+   * @param {object} decl — { onMount?, onUnmount?, onModelChange? }
+   * @param {Function} resolveHandler — (name) => async (config, ctx) => result
+   */
+  constructor(decl, resolveHandler) {
+    super();
+    this.onMount = decl.onMount || [];
+    this.onUnmount = decl.onUnmount || [];
+    this.onModelChange = decl.onModelChange || [];
+    this.#resolveHandler = resolveHandler;
+  }
+
+  dock(ctx) {
+    this.#ctx = ctx;
+
+    // Run onMount actions
+    for (const action of this.onMount) {
+      this.#run(action, ctx);
+    }
+
+    // Set up model watchers
+    const unwatchers = this.onModelChange.map((watcher) => {
+      let handler = () => this.#run(watcher, ctx);
+
+      // Debounce if specified
+      if (watcher.debounce > 0) {
+        const origHandler = handler;
+        let timer;
+        handler = () => {
+          clearTimeout(timer);
+          timer = setTimeout(origHandler, watcher.debounce);
+        };
+      }
+
+      return ctx.watchModel(watcher.path, handler);
+    });
+
+    return () => unwatchers.forEach(u => u());
+  }
+
+  undock() {
+    if (this.#ctx) {
+      for (const action of this.onUnmount) {
+        this.#run(action, this.#ctx);
+      }
+      this.#ctx = null;
+    }
+  }
+
+  async #run(action, ctx) {
+    const fn = this.#resolveHandler(action.handler);
+    if (fn) {
+      try { await fn(action.config || {}, ctx); }
+      catch (err) { console.warn(`LifecycleDock: ${action.handler} failed`, err); }
+    }
+  }
+}