@adia-ai/a2ui-runtime 0.3.0

package/controllers/data-stream.js

@@ -0,0 +1,281 @@
+import { BaseController } from './base.js';
+
+/**
+ * DataStreamController — pushes live data to chart components.
+ *
+ * Accepts: SSE URL, WebSocket URL, async iterable, polling function, or manual push.
+ * Accumulates data points in a buffer with configurable max size.
+ * Each new point triggers notify() → chart re-renders.
+ *
+ * Usage:
+ *   const ctrl = new DataStreamController({ max: 20 });
+ *   chart.controller = ctrl;
+ *
+ *   // Manual push
+ *   ctrl.commands.push({ month: 'Jan', revenue: 4200 });
+ *
+ *   // SSE
+ *   ctrl.commands.connect('sse', '/api/metrics');
+ *
+ *   // WebSocket
+ *   ctrl.commands.connect('ws', 'wss://api.example.com/stream');
+ *
+ *   // Polling
+ *   ctrl.commands.poll('/api/latest', 2000);
+ *
+ *   // Async iterable
+ *   ctrl.commands.consume(asyncIterable);
+ *
+ *   // Stop
+ *   ctrl.commands.stop();
+ */
+export class DataStreamController extends BaseController {
+  static schema = Object.freeze({
+    name: 'data-stream',
+    state: { data: 'array', status: 'string', error: 'string' },
+    commands: ['push', 'pushMany', 'connect', 'poll', 'consume', 'stop', 'clear'],
+    attributes: ['data-stream-status'],
+  });
+
+  #data = [];
+  #max;
+  #status = 'idle';  // idle | connecting | streaming | error | stopped
+  #error = null;
+  #abort = null;
+  #throttle = 0;      // ms — min interval between notify() calls. 0 = every push.
+  #sample = 1;        // keep every Nth point. 1 = keep all.
+  #pendingNotify = null;
+  #pushCount = 0;     // total pushes since connect (for sampling)
+
+  /**
+   * @param {Object} opts
+   * @param {number} [opts.max=100]      — Maximum data points to retain (FIFO)
+   * @param {number} [opts.throttle=0]   — Min ms between render notifications. 0 = every push.
+   * @param {number} [opts.sample=1]     — Keep every Nth point. 1 = keep all.
+   * @param {Array}  [opts.initial]      — Initial data
+   */
+  constructor({ max = 100, throttle = 0, sample = 1, initial = [] } = {}) {
+    super();
+    this.#max = max;
+    this.#throttle = throttle;
+    this.#sample = Math.max(1, Math.round(sample));
+    this.#data = initial.slice(-max);
+  }
+
+  getState() {
+    return {
+      data: this.#data,
+      status: this.#status,
+      error: this.#error,
+    };
+  }
+
+  reflect() {
+    if (!this.host) return;
+    this.host.setAttribute('data-stream-status', this.#status);
+  }
+
+  onDisconnect() {
+    this.commands.stop();
+  }
+
+  #append(point) {
+    // Sampling: skip points when sample > 1
+    this.#pushCount++;
+    if (this.#sample > 1 && this.#pushCount % this.#sample !== 0) return;
+
+    this.#data.push(point);
+    if (this.#data.length > this.#max) {
+      this.#data = this.#data.slice(-this.#max);
+    }
+    this.#scheduleNotify();
+  }
+
+  #appendMany(points) {
+    // Sampling: filter points when sample > 1
+    if (this.#sample > 1) {
+      const sampled = [];
+      for (const p of points) {
+        this.#pushCount++;
+        if (this.#pushCount % this.#sample === 0) sampled.push(p);
+      }
+      this.#data.push(...sampled);
+    } else {
+      this.#data.push(...points);
+    }
+    if (this.#data.length > this.#max) {
+      this.#data = this.#data.slice(-this.#max);
+    }
+    this.#scheduleNotify();
+  }
+
+  #scheduleNotify() {
+    // No throttle: immediate
+    if (this.#throttle <= 0) {
+      this.notify();
+      return;
+    }
+    // Throttled: batch into one notify per interval
+    if (this.#pendingNotify !== null) return;
+    this.#pendingNotify = setTimeout(() => {
+      this.#pendingNotify = null;
+      this.notify();
+    }, this.#throttle);
+  }
+
+  #setStatus(status, error = null) {
+    this.#status = status;
+    this.#error = error;
+    this.notify();
+  }
+
+  commands = {
+    /** Push a single data point */
+    push: (point) => {
+      this.#append(point);
+    },
+
+    /** Push multiple data points at once */
+    pushMany: (points) => {
+      this.#appendMany(points);
+    },
+
+    /** Connect to SSE or WebSocket stream */
+    connect: (type, url) => {
+      this.commands.stop();
+      this.#abort = new AbortController();
+
+      if (type === 'sse') {
+        this.#connectSSE(url);
+      } else if (type === 'ws') {
+        this.#connectWS(url);
+      } else {
+        this.#setStatus('error', `Unknown stream type: ${type}`);
+      }
+    },
+
+    /** Poll a URL at an interval (ms) */
+    poll: (url, interval = 2000) => {
+      this.commands.stop();
+      this.#abort = new AbortController();
+      this.#startPolling(url, interval);
+    },
+
+    /** Consume an async iterable */
+    consume: (iterable) => {
+      this.commands.stop();
+      this.#abort = new AbortController();
+      this.#consumeIterable(iterable);
+    },
+
+    /** Stop all active streams */
+    stop: () => {
+      if (this.#abort) {
+        this.#abort.abort();
+        this.#abort = null;
+      }
+      if (this.#pendingNotify !== null) {
+        clearTimeout(this.#pendingNotify);
+        this.#pendingNotify = null;
+      }
+      if (this.#status === 'streaming' || this.#status === 'connecting') {
+        this.#setStatus('stopped');
+      }
+    },
+
+    /** Clear all data */
+    clear: () => {
+      this.#data = [];
+      this.notify();
+    },
+  };
+
+  #connectSSE(url) {
+    this.#setStatus('connecting');
+    const es = new EventSource(url);
+    const signal = this.#abort.signal;
+
+    signal.addEventListener('abort', () => es.close());
+
+    es.onopen = () => this.#setStatus('streaming');
+
+    es.onmessage = (e) => {
+      try {
+        const point = JSON.parse(e.data);
+        this.#append(point);
+      } catch { /* skip malformed */ }
+    };
+
+    es.onerror = () => {
+      if (!signal.aborted) {
+        this.#setStatus('error', 'SSE connection lost');
+        es.close();
+      }
+    };
+  }
+
+  #connectWS(url) {
+    this.#setStatus('connecting');
+    const ws = new WebSocket(url);
+    const signal = this.#abort.signal;
+
+    signal.addEventListener('abort', () => ws.close());
+
+    ws.onopen = () => this.#setStatus('streaming');
+
+    ws.onmessage = (e) => {
+      try {
+        const msg = JSON.parse(e.data);
+        if (Array.isArray(msg)) this.#appendMany(msg);
+        else this.#append(msg);
+      } catch { /* skip malformed */ }
+    };
+
+    ws.onerror = () => {
+      if (!signal.aborted) {
+        this.#setStatus('error', 'WebSocket error');
+      }
+    };
+
+    ws.onclose = () => {
+      if (!signal.aborted) {
+        this.#setStatus('stopped');
+      }
+    };
+  }
+
+  async #startPolling(url, interval) {
+    this.#setStatus('streaming');
+    const signal = this.#abort.signal;
+
+    while (!signal.aborted) {
+      try {
+        const res = await fetch(url, { signal });
+        const json = await res.json();
+        if (Array.isArray(json)) this.#appendMany(json);
+        else this.#append(json);
+      } catch (e) {
+        if (signal.aborted) break;
+        this.#setStatus('error', e.message);
+        break;
+      }
+      await new Promise(r => setTimeout(r, interval));
+    }
+  }
+
+  async #consumeIterable(iterable) {
+    this.#setStatus('streaming');
+    const signal = this.#abort.signal;
+
+    try {
+      for await (const point of iterable) {
+        if (signal.aborted) break;
+        if (Array.isArray(point)) this.#appendMany(point);
+        else this.#append(point);
+      }
+      if (!signal.aborted) this.#setStatus('idle');
+    } catch (e) {
+      if (!signal.aborted) this.#setStatus('error', e.message);
+    }
+  }
+}

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(); },
+  };
+}