@adia-ai/a2ui-runtime 0.3.0

package/wiring-registry.js

@@ -0,0 +1,342 @@
+/**
+ * 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 };
+}