@ukiahinsure/a2ui-react-adapter 0.1.18 → 0.1.19

package/dist/index.d.ts

@@ -1,9 +1,23 @@
-import { A as A2UIClientAdapter, a as A2UISurfaceMetadata, b as A2UISessionController, c as A2UIRoomLike } from './session-BcHSjUlD.js';
-export { d as A2UIActionDeliveryStatus, e as A2UIActionResult, f as A2UIActionState, g as A2UICapabilityEnvelope, h as A2UIClientActionEnvelope, i as A2UIClientAdapterOptions, j as A2UIClientErrorEnvelope, k as A2UIClientErrorEvent, l as A2UIEditingSnapshot, m as A2UIFieldControl, n as A2UIFieldDescriptor, o as A2UIFieldInteractionField, p as A2UIFieldInteractionGroup, q as A2UIFieldValue, r as A2UIPendingAction, s as A2UIRendererActionEvent, t as A2UIServerEnvelope, u as A2UISessionControllerOptions, v as A2UISessionSnapshot, w as A2UISessionStatus, x as A2UIStreamParticipant, y as A2UISurfaceStructure, z as A2UITabDescriptor, B as A2UITrustedServerParticipant, C as A2UI_CAPABILITIES_TOPIC, D as A2UI_CLIENT_TOPIC, E as A2UI_PROTOCOL_VERSION, F as A2UI_SERVER_TOPIC, G as AckEnvelope, H as AckFieldError, I as AdapterSurface, J as CLIENT_ACTIONS, K as CLIENT_ERROR_CODES, L as ClientAction, M as ClientErrorCode, N as ENVELOPE_VERSION, O as MAX_ENVELOPE_BYTES, P as ParticipantRole, S as SectionNavigation, Q as SnapshotEnvelope, R as SurfaceUpdateEnvelope } from './session-BcHSjUlD.js';
+import { A as A2UIClientAdapter, a as A2UISurfaceMetadata, b as A2UISessionController, c as A2UIRoomLike } from './session-BnvcVx-k.js';
+export { d as A2UIActionDeliveryStatus, e as A2UIActionResult, f as A2UIActionState, g as A2UICapabilityEnvelope, h as A2UIClientActionEnvelope, i as A2UIClientAdapterOptions, j as A2UIClientErrorEnvelope, k as A2UIClientErrorEvent, l as A2UIEditingSnapshot, m as A2UIFieldControl, n as A2UIFieldDescriptor, o as A2UIFieldInteractionField, p as A2UIFieldInteractionGroup, q as A2UIFieldUpdateEvent, r as A2UIFieldValue, s as A2UIPendingAction, t as A2UIRendererActionEvent, u as A2UIServerEnvelope, v as A2UISessionControllerOptions, w as A2UISessionSnapshot, x as A2UISessionStatus, y as A2UIStreamParticipant, z as A2UISurfaceStructure, B as A2UITabDescriptor, C as A2UITrustedServerParticipant, D as A2UI_CAPABILITIES_TOPIC, E as A2UI_CLIENT_TOPIC, F as A2UI_PROTOCOL_VERSION, G as A2UI_SERVER_TOPIC, H as AckEnvelope, I as AckFieldError, J as AdapterSurface, K as CLIENT_ACTIONS, L as CLIENT_ERROR_CODES, M as ClientAction, N as ClientErrorCode, O as ENVELOPE_VERSION, P as MAX_ENVELOPE_BYTES, Q as ParticipantRole, S as SectionNavigation, R as SnapshotEnvelope, T as SurfaceUpdateEnvelope } from './session-BnvcVx-k.js';
 import { ReactNode } from 'react';
 
 /** Accessible host around the official A2UI v0.9.1 React surface. */
 
+/**
+ * The agent changed what the form shows: it filled or corrected field values
+ * (`field-value`), or moved the conversation to a new current field group
+ * (`current-group`). `element` is the rendered container for the first
+ * affected field (the whole choice group or date editor, not one option), so
+ * hosts can scroll to it for any control type.
+ */
+interface A2UIAgentUpdateEvent {
+    reason: "field-value" | "current-group";
+    surfaceId: string;
+    fields: readonly string[];
+    groupId?: string;
+    element?: HTMLElement;
+}
 interface A2UISurfaceHostProps {
     adapter: A2UIClientAdapter;
     /** Render a specific surface; defaults to the adapter's current surface. */
@@ -25,8 +39,10 @@ interface A2UISurfaceHostProps {
     noSurfaceFallback?: ReactNode;
     /** Shown when the surface fails to render. */
     errorFallback?: ReactNode;
+    /** Called after the DOM reflects an agent-driven field or group change. */
+    onAgentUpdate?: (event: A2UIAgentUpdateEvent) => void;
 }
-declare function A2UISurfaceHost({ adapter, surfaceId, surfaceMetadata, sessionController, hostId, ariaLabel, disabled, busy, invalidFields, validationSummaryId, noSurfaceFallback, errorFallback, }: A2UISurfaceHostProps): ReactNode;
+declare function A2UISurfaceHost({ adapter, surfaceId, surfaceMetadata, sessionController, hostId, ariaLabel, disabled, busy, invalidFields, validationSummaryId, noSurfaceFallback, errorFallback, onAgentUpdate, }: A2UISurfaceHostProps): ReactNode;
 
 /** Explicit room-ownership helper backed by backend-issued runtime material. */
 
@@ -48,4 +64,4 @@ interface A2UIJoinedRoom {
  */
 declare function joinA2UIRoom(tokenProvider: A2UITokenProvider): Promise<A2UIJoinedRoom>;
 
-export { A2UIClientAdapter, type A2UIJoinedRoom, A2UIRoomLike, type A2UIRuntimeMaterial, A2UISessionController, A2UISurfaceHost, type A2UISurfaceHostProps, A2UISurfaceMetadata, type A2UITokenProvider, joinA2UIRoom };
+export { type A2UIAgentUpdateEvent, A2UIClientAdapter, type A2UIJoinedRoom, A2UIRoomLike, type A2UIRuntimeMaterial, A2UISessionController, A2UISurfaceHost, type A2UISurfaceHostProps, A2UISurfaceMetadata, type A2UITokenProvider, joinA2UIRoom };

package/dist/index.js

@@ -220,6 +220,7 @@ var A2UIClientAdapter = class {
   #listeners = /* @__PURE__ */ new Set();
   #actionListeners = /* @__PURE__ */ new Set();
   #errorListeners = /* @__PURE__ */ new Set();
+  #fieldUpdateListeners = /* @__PURE__ */ new Set();
   #surfaceOrder = [];
   #structureBySurface = /* @__PURE__ */ new Map();
   #persistedListRowsByPath = /* @__PURE__ */ new Map();
@@ -420,6 +421,10 @@ var A2UIClientAdapter = class {
     this.#errorListeners.add(listener);
     return () => this.#errorListeners.delete(listener);
   };
+  subscribeFieldUpdates = (listener) => {
+    this.#fieldUpdateListeners.add(listener);
+    return () => this.#fieldUpdateListeners.delete(listener);
+  };
   /** Monotonic change counter for `useSyncExternalStore`. */
   getVersion = () => this.#version;
   dispose() {
@@ -436,6 +441,7 @@ var A2UIClientAdapter = class {
     this.#listeners.clear();
     this.#actionListeners.clear();
     this.#errorListeners.clear();
+    this.#fieldUpdateListeners.clear();
   }
   #applySurfaceEnvelope(envelope) {
     const validated = A2uiMessageListSchema.safeParse(envelope.messages);
@@ -502,6 +508,12 @@ var A2UIClientAdapter = class {
       );
       return false;
     }
+    const changedFields = envelope.kind === "snapshot" ? [] : changedFieldNames(
+      previous,
+      candidate,
+      envelope.surfaceId,
+      nextStructure.get(envelope.surfaceId)
+    );
     this.#processor = candidate;
     this.#surfaceOrder = [...candidate.model.surfacesMap.keys()];
     this.#structureBySurface = nextStructure;
@@ -518,8 +530,20 @@ var A2UIClientAdapter = class {
     );
     previous.model.dispose();
     this.#notify();
+    if (changedFields.length > 0) {
+      this.#emitFieldUpdate({
+        surfaceId: envelope.surfaceId,
+        fields: changedFields
+      });
+    }
     return true;
   }
+  #emitFieldUpdate(event) {
+    this.#options.onFieldUpdate?.(event);
+    for (const listener of this.#fieldUpdateListeners) {
+      listener(event);
+    }
+  }
   #createProcessor() {
     return new MessageProcessor(
       [editableDateCatalog],
@@ -1709,6 +1733,25 @@ function cloneJsonArray(value) {
 function isFieldValue(value) {
   return value === null || typeof value === "string" || typeof value === "boolean" || typeof value === "number" && Number.isFinite(value);
 }
+function changedFieldNames(previous, candidate, surfaceId, structure) {
+  const before = previous.model.getSurface(surfaceId);
+  const after = candidate.model.getSurface(surfaceId);
+  if (before === void 0 || after === void 0 || structure === void 0) {
+    return [];
+  }
+  const fields = /* @__PURE__ */ new Set();
+  for (const { field } of structure.fieldsByComponent.values()) {
+    const path = fieldPointer(field);
+    const next = after.dataModel.get(path);
+    if (hasFieldValue(next) && !fieldValueEquivalent(before.dataModel.get(path), next)) {
+      fields.add(field);
+    }
+  }
+  return [...fields];
+}
+function hasFieldValue(value) {
+  return Array.isArray(value) ? value.length > 0 : value !== void 0 && value !== null && value !== "";
+}
 function fieldValueEquivalent(left, right) {
   if (Array.isArray(left) && Array.isArray(right)) {
     return left.length === right.length && left.every((value, index) => Object.is(value, right[index]));
@@ -1747,6 +1790,7 @@ function classifyProcessingError(error) {
 // src/SurfaceHost.tsx
 import {
   Component,
+  useEffect,
   useId as useId3,
   useLayoutEffect as useLayoutEffect2,
   useRef as useRef2,
@@ -1766,7 +1810,8 @@ function A2UISurfaceHost({
   invalidFields = [],
   validationSummaryId,
   noSurfaceFallback,
-  errorFallback
+  errorFallback,
+  onAgentUpdate
 }) {
   const version = useSyncExternalStore(
     adapter.subscribe,
@@ -1785,12 +1830,26 @@ function A2UISurfaceHost({
   const lastFocusedState = useRef2(void 0);
   const lastViewedSection = useRef2(void 0);
   const lastValidationKey = useRef2("");
+  const pendingFieldUpdates = useRef2(/* @__PURE__ */ new Map());
+  const lastCurrentGroupId = useRef2(void 0);
+  const onAgentUpdateRef = useRef2(onAgentUpdate);
+  onAgentUpdateRef.current = onAgentUpdate;
   const resolvedSurfaceMetadata = surfaceMetadata ?? controllerSnapshot?.surface ?? null;
   const editing = controllerSnapshot?.editing ?? editingForSurface(resolvedSurfaceMetadata);
   const surface = surfaceId === void 0 ? adapter.currentSurface : adapter.getSurface(surfaceId);
   const structure = surface === void 0 ? EMPTY_STRUCTURE : adapter.getSurfaceStructure(surface.id);
   const focusKey = surface === void 0 ? void 0 : `${surface.id}:${resolvedSurfaceMetadata?.activeStateId ?? "surface"}`;
   const frameId = hostId ?? `a2ui-surface-${generatedId}`;
+  useEffect(
+    () => adapter.subscribeFieldUpdates((event) => {
+      const pending = pendingFieldUpdates.current.get(event.surfaceId) ?? /* @__PURE__ */ new Set();
+      for (const field of event.fields) {
+        pending.add(field);
+      }
+      pendingFieldUpdates.current.set(event.surfaceId, pending);
+    }),
+    [adapter]
+  );
   useLayoutEffect2(() => {
     const root = rootRef.current;
     if (root === null || surface === void 0) {
@@ -1833,6 +1892,42 @@ function A2UISurfaceHost({
         ),
         setInteractionDisabled(root, disabled || busy)
       ];
+      reportAgentUpdates();
+    };
+    const reportAgentUpdates = () => {
+      const changedFields = [
+        ...pendingFieldUpdates.current.get(surface.id) ?? []
+      ];
+      pendingFieldUpdates.current.clear();
+      const currentGroup = resolvedSurfaceMetadata?.fieldInteractions.find(
+        (group) => group.mode === "current"
+      );
+      const previousGroupId = lastCurrentGroupId.current;
+      if (currentGroup !== void 0) {
+        lastCurrentGroupId.current = currentGroup.groupId;
+      }
+      const report = onAgentUpdateRef.current;
+      if (report === void 0) {
+        return;
+      }
+      if (changedFields.length > 0) {
+        report({
+          reason: "field-value",
+          surfaceId: surface.id,
+          fields: changedFields,
+          element: agentUpdateElement(root, changedFields, structure.fields)
+        });
+      }
+      if (currentGroup !== void 0 && previousGroupId !== void 0 && currentGroup.groupId !== previousGroupId) {
+        const fields = currentGroup.fields.map((binding) => binding.field);
+        report({
+          reason: "current-group",
+          surfaceId: surface.id,
+          fields,
+          groupId: currentGroup.groupId,
+          element: agentUpdateElement(root, fields, structure.fields)
+        });
+      }
     };
     const scheduleControlRefresh = () => {
       queueMicrotask(refreshControls);
@@ -1957,6 +2052,33 @@ function focusProgressTarget(root, metadata, invalidFields) {
     });
   }
 }
+function agentUpdateElement(root, fields, descriptors) {
+  const controls = [
+    ...root.querySelectorAll("[data-a2ui-field]")
+  ];
+  for (const field of fields) {
+    const control = controls.find(
+      (candidate) => candidate.dataset.a2uiField === field
+    );
+    if (control !== void 0) {
+      return control.closest("[data-a2ui-date-editor]") ?? control.closest('[role="radiogroup"]') ?? control;
+    }
+    const descriptor = descriptors.find(
+      (candidate) => candidate.field === field
+    );
+    const labels = /* @__PURE__ */ new Set([displayFieldLabel(field)]);
+    if (descriptor !== void 0) {
+      labels.add(descriptor.label);
+    }
+    const label = [
+      ...root.querySelectorAll("label, strong, legend")
+    ].find((candidate) => labels.has(candidate.textContent?.trim() ?? ""));
+    if (label?.parentElement != null && root.contains(label.parentElement)) {
+      return label.parentElement;
+    }
+  }
+  return void 0;
+}
 function isControlDisabled(control) {
   return control.getAttribute("aria-disabled") === "true" || "disabled" in control && control.disabled === true;
 }