@adia-ai/a2ui 0.8.37

package/controllers/form.js

@@ -0,0 +1,81 @@
+import { BaseController } from './base.js';
+
+/**
+ * Form controller — tracks field values, validation, and dirty state.
+ * Sets [data-form-valid], [data-form-invalid], [data-form-dirty] on host.
+ */
+export class FormController extends BaseController {
+  static schema = Object.freeze({
+    name: 'form',
+    state: { values: 'object', errors: 'object', dirty: 'boolean', valid: 'boolean' },
+    commands: ['set', 'validate', 'reset', 'setInitial'],
+    attributes: ['data-form-valid', 'data-form-invalid', 'data-form-dirty'],
+  });
+
+  #initial = {};
+  #values = {};
+  #errors = {};
+  #validators = {};
+
+  constructor(initial = {}) {
+    super();
+    this.#initial = { ...initial };
+    this.#values = { ...initial };
+  }
+
+  onDisconnect(host) {
+    host.removeAttribute('data-form-valid');
+    host.removeAttribute('data-form-invalid');
+    host.removeAttribute('data-form-dirty');
+  }
+
+  getState() {
+    const dirty = Object.keys(this.#values).some(k => this.#values[k] !== this.#initial[k]);
+    const valid = Object.keys(this.#errors).length === 0;
+    return { values: { ...this.#values }, errors: { ...this.#errors }, dirty, valid };
+  }
+
+  reflect() {
+    if (!this.host) return;
+    const { dirty, valid } = this.getState();
+    if (valid) {
+      this.host.setAttribute('data-form-valid', '');
+      this.host.removeAttribute('data-form-invalid');
+    } else {
+      this.host.setAttribute('data-form-invalid', '');
+      this.host.removeAttribute('data-form-valid');
+    }
+    if (dirty) this.host.setAttribute('data-form-dirty', '');
+    else this.host.removeAttribute('data-form-dirty');
+  }
+
+  #runValidation(field) {
+    const fn = this.#validators[field];
+    if (!fn) { delete this.#errors[field]; return; }
+    const result = fn(this.#values[field]);
+    if (result === true || result == null) delete this.#errors[field];
+    else this.#errors[field] = typeof result === 'string' ? result : 'Invalid';
+  }
+
+  commands = {
+    set: (field, value) => {
+      this.#values[field] = value;
+      this.#runValidation(field);
+      this.notify();
+    },
+    validate: (field, fn) => {
+      this.#validators[field] = fn;
+      this.#runValidation(field);
+      this.notify();
+    },
+    reset: () => {
+      this.#values = { ...this.#initial };
+      this.#errors = {};
+      for (const field of Object.keys(this.#validators)) this.#runValidation(field);
+      this.notify();
+    },
+    setInitial: (values) => {
+      this.#initial = { ...values };
+    },
+  };
+}

package/controllers/index.js

@@ -0,0 +1,6 @@
+export { BaseController } from './base.js';
+export { ToggleController } from './toggle.js';
+export { SelectionController } from './selection.js';
+export { FormController } from './form.js';
+export { AccordionController } from './accordion.js';
+export { DataStreamController } from './data-stream.js';

package/controllers/selection.js

@@ -0,0 +1,82 @@
+import { BaseController } from './base.js';
+
+/**
+ * Selection controller — manages single or multi-select state.
+ * Sets [data-selection-active] on host, [data-selection-selected] on items.
+ */
+export class SelectionController extends BaseController {
+  static schema = Object.freeze({
+    name: 'selection',
+    state: { selected: 'Set', multiple: 'boolean' },
+    commands: ['select', 'deselect', 'toggle', 'clear', 'selectAll'],
+    attributes: ['data-selection-active', 'data-selection-selected'],
+  });
+
+  #selected = new Set();
+  #multiple = false;
+
+  constructor({ multiple = false, initial = [] } = {}) {
+    super();
+    this.#multiple = multiple;
+    for (const key of initial) this.#selected.add(String(key));
+  }
+
+  onConnect(host) {
+    host.setAttribute('data-selection-active', '');
+  }
+
+  onDisconnect(host) {
+    this.#clearReflection(host);
+    host.removeAttribute('data-selection-active');
+  }
+
+  getState() {
+    return { selected: new Set(this.#selected), multiple: this.#multiple };
+  }
+
+  reflect() {
+    if (!this.host) return;
+    const items = this.host.querySelectorAll('[data-selection-key]');
+    for (const item of items) {
+      const key = item.getAttribute('data-selection-key');
+      if (this.#selected.has(key)) item.setAttribute('data-selection-selected', '');
+      else item.removeAttribute('data-selection-selected');
+    }
+  }
+
+  #clearReflection(host) {
+    const items = host.querySelectorAll('[data-selection-selected]');
+    for (const item of items) item.removeAttribute('data-selection-selected');
+  }
+
+  commands = {
+    select: (key) => {
+      key = String(key);
+      if (!this.#multiple) this.#selected.clear();
+      this.#selected.add(key);
+      this.notify();
+    },
+    deselect: (key) => {
+      this.#selected.delete(String(key));
+      this.notify();
+    },
+    toggle: (key) => {
+      key = String(key);
+      if (this.#selected.has(key)) this.#selected.delete(key);
+      else {
+        if (!this.#multiple) this.#selected.clear();
+        this.#selected.add(key);
+      }
+      this.notify();
+    },
+    clear: () => {
+      this.#selected.clear();
+      this.notify();
+    },
+    selectAll: (keys) => {
+      if (!this.#multiple) return;
+      for (const k of keys) this.#selected.add(String(k));
+      this.notify();
+    },
+  };
+}

package/controllers/state-machine.js

@@ -0,0 +1,135 @@
+/**
+ * StateMachineController — a minimal XState-lite state chart for A2UI wiring.
+ *
+ * The LLM declares states + transitions in wireComponents. The runtime
+ * tracks current state, exposes it to CSS via `[data-state="…"]` on the
+ * host, and fires `stateEntered` / `stateExited` events. Transitions are
+ * triggered via commands (`send` named events or `transition` to a state).
+ *
+ * Goals (vs. the rest of the wiring system):
+ * - Expands the LLM's output surface beyond pure structure: it can emit a
+ *   multi-step wizard, a validation flow, a loading/ready/error trio, etc.,
+ *   without writing behavior code.
+ * - Declarative only — the catalog schema bounds what a state machine can
+ *   express. No arbitrary JS. Side effects are wiring actions (like every
+ *   other AdiaUI interactive surface).
+ *
+ * What's supported in this first pass (subset of statechart semantics):
+ *   - Finite states with named transitions (`on: { NEXT: "review" }`)
+ *   - Initial state (`initial: "welcome"`)
+ *   - `send(event)` to fire a transition
+ *   - `transition(state)` to jump to a state unconditionally
+ *   - CSS reflection via `data-state` on the host
+ *   - Entry/exit custom events
+ *
+ * Not yet (deliberately): guards, actions on transitions, hierarchical
+ * states, parallel states, history. Add when real exemplars demand them.
+ */
+
+import { BaseController } from './base.js';
+
+export class StateMachineController extends BaseController {
+  static schema = {
+    name: 'state-machine',
+    state: {
+      current: 'string',
+      history: 'string[]',
+    },
+    commands: ['send', 'transition', 'reset'],
+    attributes: ['data-state'],
+    config: {
+      initial: 'string',
+      states:  'object',  // { [name]: { on: { [event]: targetState } } }
+    },
+  };
+
+  #current = '';
+  #initial = '';
+  #states  = {};
+  #history = [];
+
+  onConnect(host) {
+    // Config read from the controller declaration. Falls back to any
+    // data-initial/data-states on the host for hand-authored surfaces.
+    const config = this.config || {};
+    this.#initial = config.initial
+      || host.dataset?.initial
+      || Object.keys(config.states || {})[0]
+      || '';
+    this.#states  = this._validateStates(config.states || {});
+    this.#current = this.#initial;
+    this.#history = this.#current ? [this.#current] : [];
+    if (this.#current) this._emit('stateEntered', { state: this.#current, initial: true });
+  }
+
+  /** Public state. */
+  getState() {
+    return { current: this.#current, history: [...this.#history] };
+  }
+
+  reflect() {
+    if (!this.host) return;
+    if (this.#current) this.host.setAttribute('data-state', this.#current);
+    else this.host.removeAttribute('data-state');
+  }
+
+  commands = {
+    /** Fire a named event; if current state defines a transition for it, move. */
+    send: (eventName) => {
+      if (!eventName || !this.#current) return;
+      const transitions = this.#states[this.#current]?.on || {};
+      const target = transitions[eventName];
+      if (!target) return; // unknown event in this state — silent no-op
+      this._moveTo(target, { event: eventName });
+    },
+
+    /** Unconditional jump to a declared state. */
+    transition: (target) => {
+      if (!target || !(target in this.#states)) return;
+      this._moveTo(target, { forced: true });
+    },
+
+    /** Return to initial state. Fires exit + enter events. */
+    reset: () => {
+      if (!this.#initial) return;
+      this._moveTo(this.#initial, { reset: true });
+    },
+  };
+
+  // ── internals ──
+
+  _moveTo(target, detail) {
+    if (target === this.#current) return;
+    const prev = this.#current;
+    if (prev) this._emit('stateExited', { state: prev, target, ...detail });
+    this.#current = target;
+    this.#history.push(target);
+    this.notify(); // triggers reflect() + subscribers
+    this._emit('stateEntered', { state: target, from: prev, ...detail });
+  }
+
+  _emit(name, detail) {
+    if (!this.host) return;
+    this.host.dispatchEvent(new CustomEvent(name, { bubbles: true, detail }));
+  }
+
+  _validateStates(states) {
+    // Shallow schema check: each state entry is an object; `on` is an object
+    // mapping event names → target state strings that exist in the map.
+    const out = {};
+    const names = Object.keys(states);
+    for (const name of names) {
+      const def = states[name] || {};
+      const on = {};
+      for (const [ev, target] of Object.entries(def.on || {})) {
+        if (typeof target !== 'string' || !(target in states)) {
+          console.warn(`[state-machine] state "${name}" transition "${ev}" → "${target}" — target not declared`);
+          continue;
+        }
+        on[ev] = target;
+      }
+      out[name] = { on };
+    }
+    return out;
+  }
+}

package/controllers/toggle.js

@@ -0,0 +1,40 @@
+import { BaseController } from './base.js';
+
+/**
+ * Toggle controller — manages on/off state.
+ * Sets [data-toggle-on] on host when active.
+ */
+export class ToggleController extends BaseController {
+  static schema = Object.freeze({
+    name: 'toggle',
+    state: { on: 'boolean' },
+    commands: ['toggle', 'set'],
+    attributes: ['data-toggle-on'],
+  });
+
+  #on = false;
+
+  constructor(initial = false) {
+    super();
+    this.#on = initial;
+  }
+
+  getState() {
+    return { on: this.#on };
+  }
+
+  onDisconnect(host) {
+    host.removeAttribute('data-toggle-on');
+  }
+
+  reflect() {
+    if (!this.host) return;
+    if (this.#on) this.host.setAttribute('data-toggle-on', '');
+    else this.host.removeAttribute('data-toggle-on');
+  }
+
+  commands = {
+    toggle: () => { this.#on = !this.#on; this.notify(); },
+    set: (v) => { this.#on = !!v; this.notify(); },
+  };
+}

package/dockables/action.d.ts

@@ -0,0 +1,55 @@
+/**
+ * ActionDock — Binds a UIEvent on a component to a handler function.
+ */
+
+import type { Dockable } from './base.js';
+import type { SurfaceContext } from '../surface.js';
+
+/** Mapping of A2UI semantic event names to DOM event names. */
+export declare const A2UI_EVENT_TO_DOM: Record<string, string>;
+
+export interface UIEventDecl {
+  /** A2UI semantic event name (press, submit, input, change, …). */
+  event: string;
+  /** Component ID to listen on. Defaults to the surface root. */
+  target?: string;
+  /** Debounce delay in ms. */
+  debounce?: number;
+  /** Throttle interval in ms. */
+  throttle?: number;
+  /** Optional condition guard. */
+  condition?: {
+    path: string;
+    equals?: unknown;
+    notEquals?: unknown;
+    exists?: boolean;
+  };
+}
+
+export interface ActionDecl {
+  /** DOM event descriptor. */
+  event: UIEventDecl;
+  /** Handler name from the wiring registry. */
+  handler: string;
+  config?: Record<string, unknown>;
+  onSuccess?: Array<{ handler: string; config?: Record<string, unknown> }> | null;
+  onError?: Array<{ handler: string; config?: Record<string, unknown> }> | null;
+}
+
+export declare class ActionDock extends Dockable {
+  readonly kind: 'action';
+  readonly id: string;
+  readonly event: UIEventDecl;
+  readonly handler: string;
+  readonly config: Record<string, unknown>;
+  readonly onSuccess: Array<{ handler: string; config?: Record<string, unknown> }> | null;
+  readonly onError: Array<{ handler: string; config?: Record<string, unknown> }> | null;
+
+  constructor(
+    decl: ActionDecl,
+    resolveHandler: (name: string) => ((config: unknown, ctx: SurfaceContext, event: unknown) => Promise<unknown>) | null,
+  );
+
+  dock(ctx: SurfaceContext): (() => void) | void;
+  undock(): void;
+}

package/dockables/action.js

@@ -0,0 +1,152 @@
+/**
+ * ActionDock — Binds a UIEvent on a component to a handler.
+ *
+ * The UIEvent 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';
+
+/**
+ * UIEvent type → DOM event name.
+ * AdiaUI components emit semantic events; these map to the actual DOM event to listen on.
+ */
+const A2UI_EVENT_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 { A2UI_EVENT_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 = A2UI_EVENT_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/dockables/base.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Dockable — Base class for objects that attach to a Surface.
+ */
+
+import type { SurfaceContext } from '../surface.js';
+
+/** The kinds of dockable objects. */
+export type DockableKind = 'controller' | 'source' | 'action' | 'provider' | 'lifecycle';
+
+export declare abstract class Dockable {
+  /** Port type — determines dock ordering. */
+  abstract readonly kind: DockableKind;
+
+  /** Unique identifier within the surface. */
+  abstract readonly id: string;
+
+  /**
+   * Attach to a surface. Return a cleanup function, or void.
+   */
+  dock(ctx: SurfaceContext): (() => void) | void;
+
+  /**
+   * Detach from the surface. The cleanup fn from dock() is called first.
+   */
+  undock(): void;
+}

package/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/dockables/controller.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ControllerDock — Wraps an AdiaUI controller as a dockable.
+ */
+
+import type { Dockable } from './base.js';
+import type { SurfaceContext } from '../surface.js';
+
+export interface ControllerDecl {
+  id: string;
+  /** Controller type name, e.g. 'FormController'. */
+  type: string;
+  /** Component ID of the host element to attach to. */
+  host: string;
+  config?: Record<string, unknown>;
+  /** Model path bindings: { stateKey: '/model/path' } */
+  bind?: Record<string, string> | null;
+}
+
+export declare class ControllerDock extends Dockable {
+  readonly kind: 'controller';
+  readonly id: string;
+  readonly type: string;
+  readonly hostId: string;
+  readonly config: Record<string, unknown>;
+  readonly bind: Record<string, string> | null;
+  controller: unknown | null;
+
+  constructor(
+    decl: ControllerDecl,
+    resolveClass: (type: string) => Promise<(new (...args: unknown[]) => unknown) | null>,
+  );
+
+  dock(ctx: SurfaceContext): Promise<(() => void) | void>;
+  undock(): void;
+}