@adia-ai/web-components 0.0.2 → 0.0.3

package/a2ui/surface-manifest.js

@@ -1,294 +0,0 @@
-/**
- * Surface Manifest — Multi-surface relationship document (A008).
- *
- * Manages a graph of surfaces and their associations:
- *   routes-to, feeds, shares-context, depends-on, triggers, contains, slots-into
- *
- * The manifest is the design-time document that describes application topology.
- * The runtime reads it to set up navigation, pre-fetch data, and manage
- * cross-surface context.
- */
-
-/**
- * @typedef {object} SurfaceDescriptor
- * @property {string} name — Human-readable name
- * @property {string} [route] — URL pattern with :param placeholders
- * @property {boolean} [entryPoint] — Can user navigate here directly?
- * @property {string[]} [requiredParams] — Params needed to render
- * @property {Record<string, object>} [produces] — Data this surface outputs
- * @property {Record<string, { keys: string[] }>} [consumes] — Named contexts consumed
- * @property {string} [status] — generated | manual | template | placeholder
- * @property {string} [generatedBy] — Execution ID from gen-ui pipeline
- * @property {string[]} [tags] — Freeform tags
- */
-
-/**
- * @typedef {object} Association
- * @property {string} type — routes-to | feeds | shares-context | depends-on | triggers | contains | slots-into
- * @property {string} from — Source surface ID
- * @property {string} to — Target surface ID
- * @property {string} [trigger] — What activates this association
- * @property {Record<string, object>} [params] — Data passed from source to target
- * @property {object} [mapping] — Data flow mapping (for feeds)
- * @property {string} [context] — Shared context name (for shares-context)
- * @property {string} [condition] — Dependency condition (for depends-on)
- * @property {string} [fallback] — Fallback action (for depends-on)
- * @property {string} [effect] — Side effect (for triggers)
- * @property {string} [slot] — Composition slot (for contains/slots-into)
- * @property {number} [position] — Order within slot
- * @property {object} [meta] — Freeform metadata
- */
-
-export class SurfaceManifest {
-  #id;
-  #name;
-  #version;
-  /** @type {Map<string, SurfaceDescriptor>} */
-  #surfaces = new Map();
-  /** @type {Association[]} */
-  #associations = [];
-  /** @type {Map<string, object>} */
-  #sharedContexts = new Map();
-
-  /**
-   * @param {object} opts
-   * @param {string} opts.id — Manifest ID
-   * @param {string} opts.name — Human-readable name
-   * @param {string} [opts.version]
-   */
-  constructor({ id, name, version = '1.0.0' }) {
-    this.#id = id;
-    this.#name = name;
-    this.#version = version;
-  }
-
-  // ── Surface CRUD ──
-
-  /**
-   * Add or update a surface descriptor.
-   * @param {string} surfaceId
-   * @param {SurfaceDescriptor} descriptor
-   */
-  addSurface(surfaceId, descriptor) {
-    this.#surfaces.set(surfaceId, { ...descriptor });
-  }
-
-  /**
-   * Remove a surface and all its associations.
-   * @param {string} surfaceId
-   */
-  removeSurface(surfaceId) {
-    this.#surfaces.delete(surfaceId);
-    this.#associations = this.#associations.filter(
-      a => a.from !== surfaceId && a.to !== surfaceId
-    );
-  }
-
-  /**
-   * Get a surface descriptor.
-   * @param {string} surfaceId
-   * @returns {SurfaceDescriptor | null}
-   */
-  getSurface(surfaceId) {
-    return this.#surfaces.get(surfaceId) ?? null;
-  }
-
-  /** @returns {string[]} */
-  get surfaceIds() {
-    return [...this.#surfaces.keys()];
-  }
-
-  // ── Associations ──
-
-  /**
-   * Add an association between surfaces.
-   * @param {Association} association
-   */
-  addAssociation(association) {
-    // Validate surfaces exist
-    if (!this.#surfaces.has(association.from)) {
-      console.warn(`Manifest: surface "${association.from}" not found`);
-      return;
-    }
-    if (!this.#surfaces.has(association.to)) {
-      console.warn(`Manifest: surface "${association.to}" not found`);
-      return;
-    }
-
-    // Deduplicate: same type + from + to replaces existing
-    this.#associations = this.#associations.filter(
-      a => !(a.type === association.type && a.from === association.from && a.to === association.to)
-    );
-    this.#associations.push({ ...association });
-  }
-
-  /**
-   * Get associations for a surface (outgoing).
-   * @param {string} surfaceId
-   * @param {string} [type] — Filter by association type
-   * @returns {Association[]}
-   */
-  getAssociationsFrom(surfaceId, type) {
-    return this.#associations.filter(
-      a => a.from === surfaceId && (!type || a.type === type)
-    );
-  }
-
-  /**
-   * Get associations targeting a surface (incoming).
-   * @param {string} surfaceId
-   * @param {string} [type]
-   * @returns {Association[]}
-   */
-  getAssociationsTo(surfaceId, type) {
-    return this.#associations.filter(
-      a => a.to === surfaceId && (!type || a.type === type)
-    );
-  }
-
-  /**
-   * Get all surfaces sharing a context with the given surface.
-   * @param {string} surfaceId
-   * @returns {{ surfaceId: string, context: string }[]}
-   */
-  getSharedContextPeers(surfaceId) {
-    const peers = [];
-    for (const a of this.#associations) {
-      if (a.type !== 'shares-context') continue;
-      if (a.from === surfaceId) peers.push({ surfaceId: a.to, context: a.context });
-      if (a.to === surfaceId) peers.push({ surfaceId: a.from, context: a.context });
-    }
-    return peers;
-  }
-
-  // ── Shared Contexts ──
-
-  /**
-   * Define a shared context.
-   * @param {string} name
-   * @param {object} config — { shape, source, params }
-   */
-  defineSharedContext(name, config) {
-    this.#sharedContexts.set(name, { ...config });
-  }
-
-  /**
-   * Get a shared context definition.
-   * @param {string} name
-   * @returns {object | null}
-   */
-  getSharedContext(name) {
-    return this.#sharedContexts.get(name) ?? null;
-  }
-
-  // ── Validation ──
-
-  /**
-   * Validate the manifest for common issues.
-   * @returns {{ valid: boolean, issues: { severity: string, message: string }[] }}
-   */
-  validate() {
-    const issues = [];
-
-    // Check for orphan surfaces (no associations)
-    for (const id of this.#surfaces.keys()) {
-      const hasAssoc = this.#associations.some(a => a.from === id || a.to === id);
-      if (!hasAssoc && this.#surfaces.size > 1) {
-        issues.push({ severity: 'warning', message: `Surface "${id}" has no associations` });
-      }
-    }
-
-    // Check for missing entry points
-    const entryPoints = [...this.#surfaces.entries()].filter(([, d]) => d.entryPoint);
-    if (entryPoints.length === 0 && this.#surfaces.size > 0) {
-      issues.push({ severity: 'warning', message: 'No surface marked as entryPoint' });
-    }
-
-    // Check depends-on has fallback
-    for (const a of this.#associations) {
-      if (a.type === 'depends-on' && !a.fallback) {
-        issues.push({ severity: 'warning', message: `depends-on from "${a.from}" to "${a.to}" has no fallback` });
-      }
-    }
-
-    // Check shares-context references defined contexts
-    for (const a of this.#associations) {
-      if (a.type === 'shares-context' && a.context && !this.#sharedContexts.has(a.context)) {
-        issues.push({ severity: 'error', message: `Shared context "${a.context}" referenced but not defined` });
-      }
-    }
-
-    // Check feeds associations have trigger
-    for (const a of this.#associations) {
-      if (a.type === 'feeds' && !a.trigger) {
-        issues.push({ severity: 'warning', message: `feeds from "${a.from}" to "${a.to}" has no trigger` });
-      }
-    }
-
-    // Check routes-to targets have routes
-    for (const a of this.#associations) {
-      if (a.type === 'routes-to') {
-        const target = this.#surfaces.get(a.to);
-        if (target && !target.route) {
-          issues.push({ severity: 'error', message: `routes-to target "${a.to}" has no route defined` });
-        }
-      }
-    }
-
-    return {
-      valid: !issues.some(i => i.severity === 'error'),
-      issues,
-    };
-  }
-
-  // ── Serialization ──
-
-  /**
-   * Export as a JSON-serializable object.
-   * @returns {object}
-   */
-  toJSON() {
-    return {
-      $schema: 'https://a2ui.dev/schema/relationships/v1',
-      id: this.#id,
-      name: this.#name,
-      version: this.#version,
-      surfaces: Object.fromEntries(this.#surfaces),
-      associations: [...this.#associations],
-      sharedContexts: Object.fromEntries(this.#sharedContexts),
-    };
-  }
-
-  /**
-   * Import from a JSON object.
-   * @param {object} json
-   * @returns {SurfaceManifest}
-   */
-  static fromJSON(json) {
-    const manifest = new SurfaceManifest({
-      id: json.id,
-      name: json.name,
-      version: json.version,
-    });
-
-    if (json.surfaces) {
-      for (const [id, desc] of Object.entries(json.surfaces)) {
-        manifest.addSurface(id, desc);
-      }
-    }
-
-    if (json.sharedContexts) {
-      for (const [name, config] of Object.entries(json.sharedContexts)) {
-        manifest.defineSharedContext(name, config);
-      }
-    }
-
-    if (json.associations) {
-      for (const assoc of json.associations) {
-        manifest.addAssociation(assoc);
-      }
-    }
-
-    return manifest;
-  }
-}

package/a2ui/surface.js

@@ -1,222 +0,0 @@
-/**
- * Surface — A dock host where typed objects connect and disconnect cleanly.
- *
- * A Surface is the runtime representation of a rendered UI region.
- * It holds a data model, resolved params, and a registry of docked objects
- * (controllers, data sources, actions, providers, lifecycle hooks).
- *
- * Dockables attach via dock(surface) and clean up via undock().
- * The Surface doesn't know what dockables do internally — it just manages
- * their lifecycle and provides a shared context.
- */
-
-// ── Dock order (lowest docks first, undocks last) ──
-const DOCK_ORDER = { provider: 0, controller: 1, source: 2, action: 3, lifecycle: 4 };
-
-/**
- * @typedef {object} DockEntry
- * @property {import('./dockables/base.js').Dockable} dockable
- * @property {Function|null} cleanup — returned from dock()
- */
-
-export class Surface {
-  /** @type {string} */
-  surfaceId;
-
-  /** @type {Map<string, DockEntry>} keyed by dockable.id */
-  #docked = new Map();
-
-  /** @type {object} reactive-ish data model */
-  #model = {};
-
-  /** @type {object} resolved params (route, store, literal) */
-  #params = {};
-
-  /** @type {Map<string, Set<Function>>} model watchers keyed by path */
-  #watchers = new Map();
-
-  /** @type {HTMLElement} surface root element */
-  #rootElement;
-
-  /** @type {Map<string, HTMLElement>} componentId → DOM element */
-  #elements;
-
-  /**
-   * @param {string} surfaceId
-   * @param {HTMLElement} rootElement — the surface's root DOM node
-   * @param {Map<string, HTMLElement>} elements — componentId → element map
-   */
-  constructor(surfaceId, rootElement, elements) {
-    this.surfaceId = surfaceId;
-    this.#rootElement = rootElement;
-    this.#elements = elements;
-  }
-
-  // ── Context (passed to dockables) ─────────────────────────
-
-  /** @returns {SurfaceContext} */
-  get context() {
-    return {
-      surfaceId: this.surfaceId,
-      getElement: (id) => this.#elements.get(id) || null,
-      getRootElement: () => this.#rootElement,
-      getModel: (path) => path ? getPath(this.#model, path) : this.#model,
-      setModel: (path, value) => this.#setModel(path, value),
-      getDockable: (kind, id) => this.#getDockable(kind, id),
-      listDockables: (kind) => this.#listDockables(kind),
-      emit: (adiaEvent) => this.#emit(adiaEvent),
-      getParam: (key) => this.#params[key],
-      watchModel: (path, fn) => this.#watchModel(path, fn),
-    };
-  }
-
-  // ── Dock Protocol ─────────────────────────────────────────
-
-  /**
-   * Dock a new object. Calls dockable.dock(context).
-   * @param {import('./dockables/base.js').Dockable} dockable
-   */
-  dock(dockable) {
-    // If same id already docked, redock (hot-swap)
-    if (this.#docked.has(dockable.id)) {
-      this.undock(dockable.id);
-    }
-
-    const cleanup = dockable.dock(this.context);
-    this.#docked.set(dockable.id, {
-      dockable,
-      cleanup: typeof cleanup === 'function' ? cleanup : null,
-    });
-  }
-
-  /**
-   * Dock multiple objects in dependency order.
-   * @param {import('./dockables/base.js').Dockable[]} dockables
-   */
-  dockAll(dockables) {
-    const sorted = [...dockables].sort(
-      (a, b) => (DOCK_ORDER[a.kind] ?? 9) - (DOCK_ORDER[b.kind] ?? 9)
-    );
-    for (const d of sorted) this.dock(d);
-  }
-
-  /**
-   * Undock by id. Calls cleanup then dockable.undock().
-   * @param {string} id
-   */
-  undock(id) {
-    const entry = this.#docked.get(id);
-    if (!entry) return;
-    entry.cleanup?.();
-    entry.dockable.undock();
-    this.#docked.delete(id);
-  }
-
-  /**
-   * Undock everything in reverse dependency order.
-   */
-  undockAll() {
-    const entries = [...this.#docked.entries()].sort(
-      (a, b) => (DOCK_ORDER[b[1].dockable.kind] ?? 9) - (DOCK_ORDER[a[1].dockable.kind] ?? 9)
-    );
-    for (const [id] of entries) this.undock(id);
-  }
-
-  /**
-   * Undock specific ids.
-   * @param {string[]} ids
-   */
-  undockMany(ids) {
-    for (const id of ids) this.undock(id);
-  }
-
-  // ── Model ─────────────────────────────────────────────────
-
-  /** Set initial model state (before docking). */
-  setInitialModel(model) {
-    Object.assign(this.#model, model);
-  }
-
-  /** Set resolved params. */
-  setParams(params) {
-    Object.assign(this.#params, params);
-  }
-
-  /** Update element map (after re-render). */
-  updateElements(elements) {
-    this.#elements = elements;
-  }
-
-  // ── Private ───────────────────────────────────────────────
-
-  #setModel(path, value) {
-    setPath(this.#model, path, value);
-    // Notify watchers for this path and any parent paths
-    for (const [watchPath, fns] of this.#watchers) {
-      if (path === watchPath || path.startsWith(watchPath + '/')) {
-        for (const fn of fns) fn(getPath(this.#model, watchPath));
-      }
-    }
-  }
-
-  #watchModel(path, fn) {
-    if (!this.#watchers.has(path)) this.#watchers.set(path, new Set());
-    this.#watchers.get(path).add(fn);
-    return () => {
-      const set = this.#watchers.get(path);
-      set?.delete(fn);
-      if (set?.size === 0) this.#watchers.delete(path);
-    };
-  }
-
-  #getDockable(kind, id) {
-    const entry = this.#docked.get(id);
-    if (entry && entry.dockable.kind === kind) return entry.dockable;
-    return null;
-  }
-
-  #listDockables(kind) {
-    const result = [];
-    for (const { dockable } of this.#docked.values()) {
-      if (!kind || dockable.kind === kind) result.push(dockable);
-    }
-    return result;
-  }
-
-  #emit(adiaEvent) {
-    const target = adiaEvent.target
-      ? this.#elements.get(adiaEvent.target)
-      : this.#rootElement;
-    if (!target) return;
-
-    target.dispatchEvent(new CustomEvent(adiaEvent.event, {
-      bubbles: true,
-      detail: adiaEvent,
-    }));
-  }
-}
-
-// ── JSON Pointer helpers (simplified, "/" delimited) ────────
-
-function getPath(obj, path) {
-  if (!path || path === '/') return obj;
-  const keys = path.replace(/^\//, '').split('/');
-  let current = obj;
-  for (const key of keys) {
-    if (current == null) return undefined;
-    current = current[key];
-  }
-  return current;
-}
-
-function setPath(obj, path, value) {
-  if (!path || path === '/') return;
-  const keys = path.replace(/^\//, '').split('/');
-  let current = obj;
-  for (let i = 0; i < keys.length - 1; i++) {
-    const key = keys[i];
-    if (current[key] == null) current[key] = {};
-    current = current[key];
-  }
-  current[keys[keys.length - 1]] = value;
-}

package/a2ui/wire-factory.js

@@ -1,134 +0,0 @@
-/**
- * Wire Factory — Translates wireComponents messages into typed Dockable objects.
- *
- * This is the bridge between the LLM's declarative JSON and the runtime dock system.
- * Each section of the wireComponents message maps to a Dockable type:
- *
- *   data.sources      → DataSourceDock[]
- *   state.controllers → ControllerDock[]
- *   actions           → ActionDock[]
- *   provides          → ProviderDock
- *   lifecycle         → LifecycleDock
- *   state.model       → set directly on Surface
- */
-import { ControllerDock } from './dockables/controller.js';
-import { DataSourceDock } from './dockables/data-source.js';
-import { ActionDock } from './dockables/action.js';
-import { ProviderDock } from './dockables/provider.js';
-import { LifecycleDock } from './dockables/lifecycle.js';
-import { resolveController, resolveData, resolveHandler } from './wiring-registry.js';
-
-/**
- * Adapt a registry handler (old ctx shape) to the dock signature (config, surfaceCtx, domEvent).
- * The old handlers read from ctx.action.*, ctx.event, ctx.source, ctx.dataModel, ctx.updateModel, etc.
- * The new signature passes (config, surfaceCtx, domEventOrResult).
- */
-function adaptHandler(handlerFn) {
-  return async (config, surfaceCtx, domEventOrResult) => {
-    // Build a backward-compatible HandlerContext from the new args
-    const ctx = {
-      // Config props spread as "action" (old handlers read ctx.action.path, ctx.action.uri, etc.)
-      action: config,
-      // DOM event if present
-      event: domEventOrResult instanceof Event ? domEventOrResult : null,
-      source: domEventOrResult instanceof Event ? domEventOrResult.target : null,
-      // Model access
-      dataModel: surfaceCtx.getModel(),
-      updateModel: (path, value) => surfaceCtx.setModel(path, value),
-      // Controllers lookup
-      controllers: Object.fromEntries(
-        surfaceCtx.listDockables('controller').map(d => [d.id, d.controller])
-      ),
-      // Params
-      params: {},
-      // Data resolver
-      resolveData,
-    };
-    return handlerFn(ctx);
-  };
-}
-
-/**
- * Create a handler resolver function that looks up from the registry
- * and wraps with the adapter.
- * @returns {(name: string) => Function|null}
- */
-function createHandlerResolver() {
-  const cache = new Map();
-  return (name) => {
-    if (cache.has(name)) return cache.get(name);
-    const raw = resolveHandler(name);
-    if (!raw) return null;
-    const adapted = adaptHandler(raw);
-    cache.set(name, adapted);
-    return adapted;
-  };
-}
-
-/**
- * Create a controller class resolver (async, lazy-loaded).
- * @returns {(type: string) => Promise<Function|null>}
- */
-function createControllerResolver() {
-  return async (type) => resolveController(type);
-}
-
-/**
- * Create a data resolver that uses the wiring registry.
- * @returns {(uri: string, ctx: object) => Promise<*>}
- */
-function createDataResolver() {
-  return async (uri, ctx) => resolveData(uri, {});
-}
-
-/**
- * Translate a wireComponents message into an array of Dockable objects.
- *
- * @param {object} msg — wireComponents message
- * @returns {{ dockables: import('./dockables/base.js').Dockable[], initialModel: object|null }}
- */
-export function createDockables(msg) {
-  const dockables = [];
-  const handlerResolver = createHandlerResolver();
-  const controllerResolver = createControllerResolver();
-  const dataResolver = createDataResolver();
-
-  // Data sources
-  if (msg.data?.sources) {
-    for (const source of msg.data.sources) {
-      dockables.push(new DataSourceDock(source, dataResolver));
-    }
-  }
-
-  // Controllers
-  if (msg.state?.controllers) {
-    for (const ctrl of msg.state.controllers) {
-      dockables.push(new ControllerDock(ctrl, controllerResolver));
-    }
-  }
-
-  // Actions
-  if (msg.actions) {
-    for (const action of msg.actions) {
-      dockables.push(new ActionDock(action, handlerResolver));
-    }
-  }
-
-  // Provides
-  if (msg.provides) {
-    const provides = Array.isArray(msg.provides) ? msg.provides : [msg.provides];
-    for (const p of provides) {
-      dockables.push(new ProviderDock(p));
-    }
-  }
-
-  // Lifecycle
-  if (msg.lifecycle) {
-    dockables.push(new LifecycleDock(msg.lifecycle, handlerResolver));
-  }
-
-  // Initial model (not a dockable — set directly on Surface)
-  const initialModel = msg.state?.model || null;
-
-  return { dockables, initialModel };
-}