@adia-ai/web-components 0.0.1 → 0.0.3

package/a2ui/wiring-engine.js

@@ -1,209 +0,0 @@
-/**
- * Wiring Engine — Processes wireComponents messages via the Surface dock system.
- *
- * This is the bridge between the renderer (which receives raw messages)
- * and the Surface (which manages dockable objects). It:
- *
- *   1. Creates/retrieves a Surface for the surfaceId
- *   2. Resolves params from the message
- *   3. Translates the message sections into typed Dockables via wire-factory
- *   4. Docks them in dependency order on the Surface
- *
- * The external API is unchanged: process(msg), teardown(surfaceId), teardownAll().
- */
-
-import { Surface } from './surface.js';
-import { createDockables } from './wire-factory.js';
-
-export class WiringEngine {
-  /** @type {Map<string, Surface>} */
-  #surfaces = new Map();
-
-  /** @type {(surfaceId: string, path: string, data: unknown) => void} */
-  #updateDataModel;
-
-  /** @type {(surfaceId: string, componentId: string) => HTMLElement | null} */
-  #getElement;
-
-  /**
-   * @param {object} opts
-   * @param {(surfaceId: string, path: string, data: unknown) => void} opts.updateDataModel
-   * @param {(surfaceId: string, componentId: string) => HTMLElement | null} opts.getElement
-   */
-  constructor({ updateDataModel, getElement }) {
-    this.#updateDataModel = updateDataModel;
-    this.#getElement = getElement;
-  }
-
-  /**
-   * Process a wireComponents message.
-   * Multiple calls for the same surfaceId are additive (new dockables added,
-   * same-id dockables hot-swapped).
-   *
-   * @param {object} message
-   */
-  async process(message) {
-    const { surfaceId } = message;
-    if (!surfaceId) return;
-
-    let surface = this.#surfaces.get(surfaceId);
-    if (!surface) {
-      surface = this.#createSurface(surfaceId);
-      this.#surfaces.set(surfaceId, surface);
-    }
-
-    try {
-      // Resolve params (before creating dockables, they may need params)
-      if (message.data?.params) {
-        surface.setParams(this.#resolveParams(message.data.params));
-      }
-
-      // Translate message → dockables
-      const { dockables, initialModel } = createDockables(message);
-
-      // Set initial model state before docking
-      if (initialModel) {
-        surface.setInitialModel(initialModel);
-      }
-
-      // Handle explicit undocking
-      if (message.undock) {
-        surface.undockMany(message.undock);
-      }
-
-      // Dock all in dependency order
-      // Some dockables have async dock() (controllers), so we dock sequentially
-      // by kind to maintain order guarantees
-      for (const dockable of dockables) {
-        await surface.dock(dockable);
-      }
-    } catch (err) {
-      console.warn(`Wiring: error processing wireComponents for "${surfaceId}":`, err.message);
-    }
-  }
-
-  /**
-   * Tear down all wiring for a surface.
-   * @param {string} surfaceId
-   */
-  teardown(surfaceId) {
-    const surface = this.#surfaces.get(surfaceId);
-    if (!surface) return;
-    surface.undockAll();
-    this.#surfaces.delete(surfaceId);
-  }
-
-  /**
-   * Tear down everything.
-   */
-  teardownAll() {
-    for (const surfaceId of this.#surfaces.keys()) this.teardown(surfaceId);
-  }
-
-  /**
-   * Get a surface for inspection/testing.
-   * @param {string} surfaceId
-   * @returns {Surface|null}
-   */
-  getSurface(surfaceId) {
-    return this.#surfaces.get(surfaceId) || null;
-  }
-
-  /**
-   * Get a wired surface's state (for debugging/inspection).
-   * @param {string} surfaceId
-   */
-  getSurfaceState(surfaceId) {
-    const surface = this.#surfaces.get(surfaceId);
-    if (!surface) return null;
-    const dockables = surface.context.listDockables();
-    return {
-      surfaceId,
-      controllerCount: dockables.filter(d => d.kind === 'controller').length,
-      sourceCount: dockables.filter(d => d.kind === 'source').length,
-      actionCount: dockables.filter(d => d.kind === 'action').length,
-      providerCount: dockables.filter(d => d.kind === 'provider').length,
-      hasLifecycle: dockables.some(d => d.kind === 'lifecycle'),
-      totalDocked: dockables.length,
-    };
-  }
-
-  // ── Private ────────────────────────────────────────────────
-
-  /**
-   * Create a Surface wired to the renderer's element map.
-   */
-  #createSurface(surfaceId) {
-    // Create an element proxy that delegates to the renderer's getElement
-    const elementsProxy = {
-      get: (componentId) => this.#getElement(surfaceId, componentId),
-      has: (componentId) => !!this.#getElement(surfaceId, componentId),
-    };
-
-    // The root element is the surface container in the renderer
-    const rootElement = this.#getElement(surfaceId, 'root') || document.createElement('div');
-
-    // Build a Map-like wrapper so Surface can use elements.get()
-    const elements = new Proxy(new Map(), {
-      get(target, prop) {
-        if (prop === 'get') return (id) => elementsProxy.get(id);
-        if (prop === 'has') return (id) => elementsProxy.has(id);
-        return target[prop];
-      },
-    });
-
-    // Wrap updateDataModel so dockables that call ctx.setModel
-    // also flow through to the renderer's data binding system
-    const surface = new Surface(surfaceId, rootElement, elements);
-
-    // Monkey-patch setModel on context to also notify the renderer
-    const originalContext = surface.context;
-    const origSetModel = originalContext.setModel;
-    const updateDataModel = this.#updateDataModel;
-    Object.defineProperty(surface, 'context', {
-      get() {
-        const ctx = originalContext;
-        return {
-          ...ctx,
-          setModel(path, value) {
-            origSetModel(path, value);
-            updateDataModel(surfaceId, path, value);
-          },
-        };
-      },
-    });
-
-    return surface;
-  }
-
-  /**
-   * Resolve parameter declarations to values.
-   * @param {Record<string, { from: string, key: string }>} params
-   * @returns {Record<string, string>}
-   */
-  #resolveParams(params) {
-    const resolved = {};
-    for (const [name, spec] of Object.entries(params)) {
-      switch (spec.from) {
-        case 'route': {
-          const hash = location.hash.slice(1);
-          const match = hash.match(new RegExp(`${spec.key}/([^/]+)`));
-          if (match) resolved[name] = match[1];
-          break;
-        }
-        case 'query': {
-          const url = new URL(location.href);
-          const val = url.searchParams.get(spec.key);
-          if (val) resolved[name] = val;
-          break;
-        }
-        case 'literal':
-          resolved[name] = spec.value;
-          break;
-        default:
-          if (typeof spec === 'string') resolved[name] = spec;
-      }
-    }
-    return resolved;
-  }
-}

package/a2ui/wiring-registry.js

@@ -1,342 +0,0 @@
-/**
- * Wiring Registry — Runtime lookup for controllers, action handlers, and data resolvers.
- *
- * Parallel to standardRegistry (type → tag for components), the wiring registry
- * maps controller types → factories, handler names → functions, and URI schemes → resolvers.
- *
- * All entries are lazily loaded — controllers are async factory functions, only imported
- * when a surface actually declares them. A surface that only uses actions never loads
- * any controller module.
- *
- * Extensible: consumers register custom controllers, handlers, and resolvers at startup.
- * A healthcare app registers CheckinController; a CRM registers PipelineController.
- */
-
-// ═══════════════════════════════════════════════════════════════
-// REGISTRY
-// ═══════════════════════════════════════════════════════════════
-
-export const wiringRegistry = {
-  /** Controller type → async factory function */
-  controllers: new Map([
-    ['FormController',        async () => (await import('../controllers/form.js')).FormController],
-    ['DataStreamController',  async () => (await import('../controllers/data-stream.js')).DataStreamController],
-    ['SelectionController',   async () => (await import('../controllers/selection.js')).SelectionController],
-    ['ToggleController',      async () => (await import('../controllers/toggle.js')).ToggleController],
-    ['AccordionController',   async () => (await import('../controllers/accordion.js')).AccordionController],
-    ['StateMachineController', async () => (await import('../controllers/state-machine.js')).StateMachineController],
-  ]),
-
-  /** Action handler name → handler function */
-  handlers: new Map([
-    ['submit-resource',    handleSubmitResource],
-    ['update-model',       handleUpdateModel],
-    ['navigate',           handleNavigate],
-    ['navigate-back',      handleNavigateBack],
-    ['controller-command', handleControllerCommand],
-    ['emit-event',         handleEmitEvent],
-    ['refresh-source',     handleRefreshSource],
-    ['notify',             handleNotify],
-  ]),
-
-  /** URI scheme → resolver function */
-  resolvers: new Map([
-    ['resource', defaultResourceResolver],
-    ['api',      defaultApiResolver],
-    ['mock',     defaultMockResolver],
-  ]),
-};
-
-// ═══════════════════════════════════════════════════════════════
-// REGISTRATION API
-// ═══════════════════════════════════════════════════════════════
-
-/**
- * Register a custom controller type.
- * @param {string} name — Controller type name
- * @param {() => Promise<new (...args: any[]) => any>} factory — Async factory returning the constructor
- */
-export function registerController(name, factory) {
-  wiringRegistry.controllers.set(name, factory);
-}
-
-/**
- * Register a custom action handler.
- * @param {string} name — Handler name
- * @param {(context: HandlerContext) => Promise<unknown>} fn — Handler function
- */
-export function registerHandler(name, fn) {
-  wiringRegistry.handlers.set(name, fn);
-}
-
-/**
- * Register a custom URI resolver.
- * @param {string} scheme — URI scheme (e.g., 'resource', 'api', 'custom')
- * @param {(uri: string, params: Record<string, string>) => Promise<unknown>} fn — Resolver function
- */
-export function registerResolver(scheme, fn) {
-  wiringRegistry.resolvers.set(scheme, fn);
-}
-
-// ═══════════════════════════════════════════════════════════════
-// RESOLUTION API
-// ═══════════════════════════════════════════════════════════════
-
-/**
- * Resolve a controller type to its constructor.
- * @param {string} type — Controller type name
- * @returns {Promise<(new (...args: any[]) => any) | null>}
- */
-export async function resolveController(type) {
-  const factory = wiringRegistry.controllers.get(type);
-  if (!factory) return null;
-  return factory();
-}
-
-/**
- * Resolve a handler name to its function.
- * @param {string} name — Handler name
- * @returns {((context: HandlerContext) => Promise<unknown>) | null}
- */
-export function resolveHandler(name) {
-  return wiringRegistry.handlers.get(name) || null;
-}
-
-/**
- * Resolve a resource URI to data.
- * @param {string} uri — Resource URI (e.g., 'resource://patients/123')
- * @param {Record<string, string>} [params] — Resolved parameters
- * @returns {Promise<unknown>}
- */
-export async function resolveData(uri, params = {}) {
-  // Interpolate params into URI
-  let resolved = uri;
-  for (const [key, value] of Object.entries(params)) {
-    resolved = resolved.replace(`{${key}}`, encodeURIComponent(value));
-  }
-
-  // Extract scheme
-  const schemeEnd = resolved.indexOf('://');
-  if (schemeEnd === -1) throw new Error(`Invalid URI: ${uri}`);
-  const scheme = resolved.slice(0, schemeEnd);
-
-  const resolver = wiringRegistry.resolvers.get(scheme);
-  if (!resolver) throw new Error(`No resolver for scheme "${scheme}"`);
-
-  return resolver(resolved, params);
-}
-
-// ═══════════════════════════════════════════════════════════════
-// HANDLER CONTEXT (passed to every action handler)
-// ═══════════════════════════════════════════════════════════════
-
-/**
- * @typedef {object} HandlerContext
- * @property {Event} event — The DOM event that triggered the action
- * @property {HTMLElement} source — The source element
- * @property {object} action — The action declaration from wireComponents
- * @property {object} dataModel — The surface's data model
- * @property {(path: string, value: unknown) => void} updateModel — Update the data model
- * @property {Record<string, any>} controllers — Map of controllerId → instance
- * @property {Record<string, string>} params — Resolved parameters
- * @property {(uri: string, params?: object) => Promise<unknown>} resolveData — Data resolver
- */
-
-// ═══════════════════════════════════════════════════════════════
-// BUILT-IN HANDLERS
-// ═══════════════════════════════════════════════════════════════
-
-/**
- * Submit to a resource URI (POST/PUT/PATCH/DELETE).
- */
-async function handleSubmitResource(ctx) {
-  const { action, params } = ctx;
-  const body = extractValue(action.body, ctx);
-
-  let uri = action.uri;
-  for (const [key, value] of Object.entries(params)) {
-    uri = uri.replace(`{${key}}`, encodeURIComponent(value));
-  }
-
-  const schemeEnd = uri.indexOf('://');
-  const scheme = schemeEnd > -1 ? uri.slice(0, schemeEnd) : 'api';
-  const resolver = wiringRegistry.resolvers.get(scheme);
-
-  // For submit, we need a POST-capable resolver
-  // Default: convert resource:// to /api/ REST convention
-  const apiPath = uri.replace(/^\w+:\/\//, '/api/');
-  const response = await fetch(apiPath, {
-    method: action.method || 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify(body),
-  });
-
-  if (!response.ok) {
-    const error = await response.text().catch(() => 'Request failed');
-    throw new Error(error);
-  }
-
-  return response.json().catch(() => ({}));
-}
-
-/**
- * Update the surface data model at a path.
- */
-async function handleUpdateModel(ctx) {
-  const { action } = ctx;
-  const value = extractValue(action.value, ctx);
-  ctx.updateModel(action.path, value);
-}
-
-/**
- * Navigate to a route.
- */
-async function handleNavigate(ctx) {
-  const { action, params } = ctx;
-  let path = action.navigate || action.path || '';
-  for (const [key, value] of Object.entries(params)) {
-    path = path.replace(`{${key}}`, encodeURIComponent(value));
-  }
-  if (path === 'back') {
-    history.back();
-  } else if (path) {
-    location.hash = path;
-  }
-}
-
-/**
- * Navigate back in browser history.
- */
-async function handleNavigateBack() {
-  history.back();
-}
-
-/**
- * Invoke a controller command.
- */
-async function handleControllerCommand(ctx) {
-  const { action, controllers } = ctx;
-  const controller = controllers[action.controllerId];
-  if (!controller?.commands?.[action.command]) {
-    console.warn(`Wiring: controller "${action.controllerId}" or command "${action.command}" not found`);
-    return;
-  }
-  return controller.commands[action.command](action.args);
-}
-
-/**
- * Re-emit as a named custom event on the surface root.
- */
-async function handleEmitEvent(ctx) {
-  const { action, source } = ctx;
-  const detail = extractValue(action.detail, ctx);
-  source.dispatchEvent(new CustomEvent(action.eventName || action.event, {
-    bubbles: true,
-    detail,
-  }));
-}
-
-/**
- * Re-fetch a named data source.
- */
-async function handleRefreshSource(ctx) {
-  const sourceId = ctx.action.sourceId;
-  // In the dock system, the surface context has getDockable.
-  // From the handler context, we can access it through the adapted ctx.
-  // For now, dispatch a custom event that the DataSourceDock can listen for.
-  document.dispatchEvent(new CustomEvent('a2ui-refresh-source', {
-    detail: { sourceId },
-  }));
-  return { refreshSource: sourceId };
-}
-
-/**
- * Show a toast/alert notification.
- */
-async function handleNotify(ctx) {
-  const { action } = ctx;
-  const message = typeof action === 'string' ? action : action.message || action.notify;
-  // Dispatch a notification event that a toast-ui can listen for
-  document.dispatchEvent(new CustomEvent('a2ui-notify', {
-    bubbles: true,
-    detail: { message, variant: action.variant || 'info' },
-  }));
-}
-
-// ═══════════════════════════════════════════════════════════════
-// VALUE EXTRACTION
-// ═══════════════════════════════════════════════════════════════
-
-/**
- * Extract a value based on a value descriptor.
- * @param {object|undefined} descriptor — { from, key, path, value }
- * @param {HandlerContext} ctx
- * @returns {unknown}
- */
-function extractValue(descriptor, ctx) {
-  if (!descriptor) return undefined;
-  if (typeof descriptor !== 'object') return descriptor;
-
-  switch (descriptor.from) {
-    case 'event-detail':
-      return descriptor.key ? ctx.event?.detail?.[descriptor.key] : ctx.event?.detail;
-    case 'event-target':
-      return descriptor.key ? ctx.source?.[descriptor.key] : ctx.source?.value;
-    case 'model':
-      return getModelValue(ctx.dataModel, descriptor.path);
-    case 'literal':
-      return descriptor.value;
-    case 'param':
-      return ctx.params?.[descriptor.key];
-    default:
-      return descriptor;
-  }
-}
-
-/**
- * Get a value from a data model by JSON Pointer path.
- * @param {object} model
- * @param {string} path — JSON Pointer (e.g., "/patient/name")
- * @returns {unknown}
- */
-function getModelValue(model, path) {
-  if (!path || !model) return undefined;
-  const segments = path.split('/').filter(Boolean);
-  let current = model;
-  for (const seg of segments) {
-    if (current == null || typeof current !== 'object') return undefined;
-    current = current[seg];
-  }
-  return current;
-}
-
-// ═══════════════════════════════════════════════════════════════
-// DEFAULT RESOLVERS
-// ═══════════════════════════════════════════════════════════════
-
-/**
- * Default resource:// resolver — maps to REST convention: /api/{path}
- */
-async function defaultResourceResolver(uri, params) {
-  const path = uri.replace(/^resource:\/\//, '/api/');
-  const response = await fetch(path);
-  if (!response.ok) throw new Error(`Resource fetch failed: ${response.status}`);
-  return response.json();
-}
-
-/**
- * Default api:// resolver — direct URL passthrough.
- */
-async function defaultApiResolver(uri, params) {
-  const url = uri.replace(/^api:\/\//, 'https://');
-  const response = await fetch(url);
-  if (!response.ok) throw new Error(`API fetch failed: ${response.status}`);
-  return response.json();
-}
-
-/**
- * Default mock:// resolver — returns empty object with the URI as _source.
- */
-async function defaultMockResolver(uri, params) {
-  return { _source: uri, _mock: true };
-}