@adia-ai/a2ui-retrieval 0.0.1

package/wiring-catalog.js

@@ -0,0 +1,195 @@
+/**
+ * Wiring Catalog — Knowledge base for the gen-ui pipeline.
+ *
+ * Indexes available wiring capabilities so the generator can emit valid
+ * wireComponents declarations alongside component trees.
+ *
+ * The schema has 5 docking points:
+ *   DATA     — sources, params (how the surface gets its data)
+ *   STATE    — controllers, model (how components manage behavior)
+ *   ACTIONS  — AdiaEvent → handler chains (what happens on events)
+ *   PROVIDES — context injection into subtrees
+ *   LIFECYCLE — onMount, onUnmount, onModelChange hooks
+ *
+ * Each point is optional. A static display surface needs none.
+ * A form needs STATE (FormController) + ACTIONS (submit).
+ * A dashboard needs DATA (sources) + STATE (DataStreamController).
+ * A full app needs all five.
+ */
+
+// ── AdiaEvent ──────────────────────────────────────────────────
+// A typed event object that the wiring system understands natively.
+// Maps 1:1 to DOM events but with AdiaUI semantics and payload contracts.
+//
+//   { "event": "press",  "target": "save-btn" }
+//   { "event": "input",  "target": "search",  "debounce": 300 }
+//   { "event": "submit", "target": "form-col" }
+//   { "event": "mount" }
+//
+// "event"    — AdiaEvent type name (see adiaEvents below)
+// "target"   — component id that emits. Omit for surface-level events.
+// "debounce" — ms, coalesce rapid-fire (input, resize)
+// "throttle" — ms, limit frequency (scroll, drag)
+// "condition" — guard: { path, equals|notEquals|exists }
+
+const adiaEvents = [
+  { event: 'press',    payload: null,           description: 'Button or interactive element activated.' },
+  { event: 'submit',   payload: 'form-values',  description: 'Form submission with validated field values.' },
+  { event: 'input',    payload: 'target-value',  description: 'Value changed (fires on every keystroke).' },
+  { event: 'change',   payload: 'event-detail',  description: 'Value committed (fires on blur or selection).' },
+  { event: 'select',   payload: 'event-detail',  description: 'Item selected from list, table, or menu.' },
+  { event: 'toggle',   payload: 'boolean',       description: 'Boolean state flipped (switch, checkbox).' },
+  { event: 'dismiss',  payload: null,            description: 'Close/dismiss (dialog, toast, popover).' },
+  { event: 'navigate', payload: 'route',         description: 'Internal navigation request.' },
+  { event: 'mount',    payload: null,            description: 'Surface or component entered the DOM.' },
+  { event: 'unmount',  payload: null,            description: 'Surface or component left the DOM.' },
+  { event: 'focus',    payload: null,            description: 'Element received focus.' },
+  { event: 'blur',     payload: null,            description: 'Element lost focus.' },
+  { event: 'drag',     payload: 'event-detail',  description: 'Drag operation on a sortable/draggable.' },
+  { event: 'drop',     payload: 'event-detail',  description: 'Drop completed on a sortable/draggable.' },
+];
+
+/**
+ * Get the full wiring catalog.
+ * @returns {object}
+ */
+export function getWiringCatalog() {
+  return {
+    // ── ADIA EVENTS ──
+    adiaEvents,
+
+    // ── DATA: how the surface gets its data ──
+    data: {
+      description: 'Fetch external data into the surface model. Sources are URI-based with refresh strategies.',
+      paramSources: ['route', 'store', 'literal', 'query', 'parent'],
+      uriSchemes: ['resource://', 'api://', 'mock://', 'ws://', 'sse://'],
+      refreshStrategies: ['once', 'on-focus', 'interval:{ms}', 'stream'],
+      example: {
+        params: { userId: { from: 'route', key: 'id' } },
+        sources: [
+          { id: 'user', uri: 'resource://users/{userId}', path: '/user', refresh: 'once' },
+          { id: 'activity', uri: 'resource://users/{userId}/activity', path: '/activity', refresh: 'on-focus' },
+        ],
+      },
+    },
+
+    // ── STATE: controllers that manage component behavior ──
+    controllers: [
+      {
+        type: 'FormController',
+        description: 'Manages field values, validation, dirty/pristine tracking. Attach to a Column/Section containing form fields.',
+        config: {
+          validateOn: { type: 'string', enum: ['blur', 'change', 'submit'], default: 'blur' },
+        },
+        commands: ['validate', 'reset', 'setFieldError'],
+        bind: { values: '/form/values', valid: '/form/valid', dirty: '/form/dirty' },
+      },
+      {
+        type: 'DataStreamController',
+        description: 'Live data buffer for charts, tables, feeds. Supports push, SSE, WebSocket, polling.',
+        config: {
+          max: { type: 'number', default: 100, description: 'FIFO buffer size' },
+          throttle: { type: 'number', default: 0, description: 'Min ms between renders' },
+        },
+        commands: ['push', 'pushMany', 'connect', 'poll', 'consume', 'stop', 'clear'],
+        bind: { data: '/stream/data', status: '/stream/status' },
+      },
+      {
+        type: 'SelectionController',
+        description: 'Single or multi-select state for lists, tables, grids.',
+        config: { mode: { type: 'string', enum: ['single', 'multi'], default: 'single' } },
+        commands: ['select', 'deselect', 'toggle', 'selectAll', 'clear'],
+        bind: { selected: '/selection/items', count: '/selection/count' },
+      },
+      {
+        type: 'ToggleController',
+        description: 'Boolean on/off state with attribute reflection.',
+        config: {},
+        commands: ['toggle', 'set'],
+        bind: { value: '/toggle/on' },
+      },
+      {
+        type: 'AccordionController',
+        description: 'Panel expand/collapse with mutual exclusion.',
+        config: { multiple: { type: 'boolean', default: false } },
+        commands: ['open', 'close', 'toggle'],
+        bind: { openPanels: '/accordion/open' },
+      },
+    ],
+
+    // ── ACTIONS: event → handler chains ──
+    handlers: [
+      { name: 'submit-resource', description: 'POST/PUT/PATCH/DELETE to a resource URI.', config: ['uri', 'method', 'body'] },
+      { name: 'update-model', description: 'Update the surface data model at a path.', config: ['path', 'value'] },
+      { name: 'navigate', description: 'Route to a path (supports {param} templates).', config: ['navigate'] },
+      { name: 'navigate-back', description: 'Go back in browser history.', config: [] },
+      { name: 'controller-command', description: 'Invoke a command on a controller.', config: ['controllerId', 'command', 'args'] },
+      { name: 'emit-event', description: 'Dispatch a named CustomEvent on the surface.', config: ['eventName', 'detail'] },
+      { name: 'refresh-source', description: 'Re-fetch a named data source.', config: ['sourceId'] },
+      { name: 'notify', description: 'Show a toast/alert notification.', config: ['message', 'variant'] },
+    ],
+
+    // ── ACTION SHAPE (AdiaEvent → handler) ──
+    actionShape: {
+      event: 'AdiaEvent object: { event, target?, debounce?, throttle?, condition? }',
+      handler: 'Handler name from the handlers list.',
+      config: 'Handler-specific configuration object.',
+      onSuccess: 'Follow-up actions array (each is { handler, config }).',
+      onError: 'Follow-up actions array on failure.',
+    },
+
+    // ── PROVIDES: context injection ──
+    provides: {
+      description: 'Inject shared state into a component subtree via a2ui-provider. Children consume via context name.',
+      example: { name: 'auth', host: 'root', value: { user: null, token: null } },
+    },
+
+    // ── LIFECYCLE hooks ──
+    lifecycle: {
+      onMount: 'Actions to run when the surface first renders (fetch initial data, start streams).',
+      onUnmount: 'Cleanup actions when the surface is destroyed (close WebSocket, stop polling).',
+      onModelChange: 'Watch a model path and fire actions when it changes (debounce supported).',
+    },
+
+    // ── VALUE EXTRACTION (how actions read data) ──
+    valueSources: [
+      { from: 'event-detail', description: 'Read from event.detail (key = property)' },
+      { from: 'event-target', description: 'Read from event.target (key = property, e.g., value)' },
+      { from: 'model', description: 'Read from data model (path = JSON Pointer)' },
+      { from: 'literal', description: 'Static value (value = the value)' },
+      { from: 'param', description: 'Read from resolved parameters (key = param name)' },
+      { from: 'controller', description: 'Read from a controller state (controllerId + key)' },
+    ],
+
+    // ── MULTI-SURFACE ASSOCIATIONS ──
+    associations: [
+      { name: 'routes-to', description: 'Navigation — source links to target.' },
+      { name: 'feeds', description: 'Data flow — source output → target input.' },
+      { name: 'shares-context', description: 'Shared state — both read/write same context.' },
+      { name: 'depends-on', description: 'Lifecycle — source waits for target.' },
+      { name: 'triggers', description: 'Side effect — source event → target update.' },
+      { name: 'contains', description: 'Composition — target renders inside source.' },
+    ],
+  };
+}
+
+/**
+ * Get AdiaEvent type info.
+ */
+export function getAdiaEvent(type) {
+  return adiaEvents.find(e => e.event === type) || null;
+}
+
+/**
+ * Get controller catalog entry by type name.
+ */
+export function getControllerInfo(type) {
+  return getWiringCatalog().controllers.find(c => c.type === type) || null;
+}
+
+/**
+ * Get handler catalog entry by name.
+ */
+export function getHandlerInfo(name) {
+  return getWiringCatalog().handlers.find(h => h.name === name) || null;
+}