@mydatavalue/polter 0.1.2 → 0.1.4

package/README.md

@@ -79,6 +79,28 @@ import { z } from 'zod';
 </AgentAction>
 ```
 
+**Modal interactions** — click a button to open a modal, type a value, then confirm:
+
+```tsx
+// Parent — 3-step flow: open → type → confirm
+<AgentAction name="apply_discount" parameters={z.object({ pct: z.number() })}
+  onExecute={async () => { /* await async work started by the confirm click */ }}>
+  <AgentStep label="Open settings">
+    <SettingsButton />
+  </AgentStep>
+  <AgentStep label="Set value" fromTarget="discount-input" setParam="pct" />
+  <AgentStep label="Confirm" fromTarget="confirm-btn" />
+</AgentAction>
+
+// Child (modal) — targets with prepareView to set up internal state
+<AgentTarget name="discount-input" prepareView={() => setMode("custom")}>
+  <Input value={value} onChange={...} />
+</AgentTarget>
+<AgentTarget name="confirm-btn">
+  <ConfirmButton />
+</AgentTarget>
+```
+
 ### 3. Connect to your agent
 
 ```tsx

package/dist/index.d.mts

@@ -73,6 +73,8 @@ interface AgentTargetEntry {
     value?: string;
     /** Named target key — used for static lazy resolution via `fromTarget`. */
     name?: string;
+    /** Run a callback to prepare component state before the agent interacts with this target. */
+    prepareView?: (params: Record<string, unknown>) => void | Promise<void>;
 }
 interface RegisteredAction {
     name: string;
@@ -119,7 +121,7 @@ interface ExecutorConfig {
     /** Resolve an element from the AgentTarget registry. Used by fromParam steps. */
     resolveTarget?: (actionName: string, param: string, value: string, signal?: AbortSignal) => Promise<HTMLElement | null>;
     /** Resolve a named target from the AgentTarget registry. Used by fromTarget steps. */
-    resolveNamedTarget?: (actionName: string, name: string, signal?: AbortSignal) => Promise<HTMLElement | null>;
+    resolveNamedTarget?: (actionName: string, name: string, signal?: AbortSignal, params?: Record<string, unknown>) => Promise<HTMLElement | null>;
 }
 interface AgentActionProviderProps {
     mode?: ExecutionMode;
@@ -196,6 +198,8 @@ interface AgentTargetProps {
     value?: string;
     /** Named target key (for fromTarget resolution — static elements inside popovers/dropdowns). */
     name?: string;
+    /** Run a callback to prepare component state before the agent interacts with this target. Runs in the child's scope so it can access internal state. */
+    prepareView?: (params: Record<string, unknown>) => void | Promise<void>;
 }
 /**
  * Register a DOM element as a selectable target for an agent action step.
@@ -219,7 +223,7 @@ interface AgentTargetProps {
  * </AgentTarget>
  * ```
  */
-declare function AgentTarget({ action, param, value, name, children }: AgentTargetProps): react_jsx_runtime.JSX.Element;
+declare function AgentTarget({ action, param, value, name, prepareView, children }: AgentTargetProps): react_jsx_runtime.JSX.Element;
 
 interface AgentDevToolsProps {
     /** Default open state. */

package/dist/index.d.ts

@@ -73,6 +73,8 @@ interface AgentTargetEntry {
     value?: string;
     /** Named target key — used for static lazy resolution via `fromTarget`. */
     name?: string;
+    /** Run a callback to prepare component state before the agent interacts with this target. */
+    prepareView?: (params: Record<string, unknown>) => void | Promise<void>;
 }
 interface RegisteredAction {
     name: string;
@@ -119,7 +121,7 @@ interface ExecutorConfig {
     /** Resolve an element from the AgentTarget registry. Used by fromParam steps. */
     resolveTarget?: (actionName: string, param: string, value: string, signal?: AbortSignal) => Promise<HTMLElement | null>;
     /** Resolve a named target from the AgentTarget registry. Used by fromTarget steps. */
-    resolveNamedTarget?: (actionName: string, name: string, signal?: AbortSignal) => Promise<HTMLElement | null>;
+    resolveNamedTarget?: (actionName: string, name: string, signal?: AbortSignal, params?: Record<string, unknown>) => Promise<HTMLElement | null>;
 }
 interface AgentActionProviderProps {
     mode?: ExecutionMode;
@@ -196,6 +198,8 @@ interface AgentTargetProps {
     value?: string;
     /** Named target key (for fromTarget resolution — static elements inside popovers/dropdowns). */
     name?: string;
+    /** Run a callback to prepare component state before the agent interacts with this target. Runs in the child's scope so it can access internal state. */
+    prepareView?: (params: Record<string, unknown>) => void | Promise<void>;
 }
 /**
  * Register a DOM element as a selectable target for an agent action step.
@@ -219,7 +223,7 @@ interface AgentTargetProps {
  * </AgentTarget>
  * ```
  */
-declare function AgentTarget({ action, param, value, name, children }: AgentTargetProps): react_jsx_runtime.JSX.Element;
+declare function AgentTarget({ action, param, value, name, prepareView, children }: AgentTargetProps): react_jsx_runtime.JSX.Element;
 
 interface AgentDevToolsProps {
     /** Default open state. */

package/dist/index.js

@@ -330,7 +330,7 @@ async function resolveStepElement(target, actionName, params, config) {
     return config.resolveTarget(actionName, target.fromParam, paramValue, config.signal);
   }
   if (target.fromTarget && config.resolveNamedTarget) {
-    return config.resolveNamedTarget(actionName, target.fromTarget, config.signal);
+    return config.resolveNamedTarget(actionName, target.fromTarget, config.signal, params);
   }
   return target.element;
 }
@@ -542,7 +542,7 @@ function AgentActionProvider({
     []
   );
   const resolveNamedTarget = react.useCallback(
-    async (actionName, name, signal) => {
+    async (actionName, name, signal, params) => {
       const maxWait = 3e3;
       const pollInterval = 50;
       const start = Date.now();
@@ -550,6 +550,9 @@ function AgentActionProvider({
         if (signal?.aborted) return null;
         for (const entry of targetsRef.current.values()) {
           if ((!entry.action || entry.action === actionName) && entry.name === name && entry.element.isConnected) {
+            if (entry.prepareView && params) {
+              await entry.prepareView(params);
+            }
             return entry.element;
           }
         }
@@ -848,10 +851,12 @@ function AgentStep({
   if (!children) return null;
   return /* @__PURE__ */ jsxRuntime.jsx("div", { ref: wrapperRef, style: { display: "contents" }, children });
 }
-function AgentTarget({ action, param, value, name, children }) {
+function AgentTarget({ action, param, value, name, prepareView, children }) {
   const id = react.useId();
   const wrapperRef = react.useRef(null);
   const context = react.useContext(AgentActionContext);
+  const prepareViewRef = react.useRef(prepareView);
+  prepareViewRef.current = prepareView;
   if (!context) {
     throw new Error("AgentTarget must be used within an AgentActionProvider");
   }
@@ -859,7 +864,7 @@ function AgentTarget({ action, param, value, name, children }) {
   react.useEffect(() => {
     const element = wrapperRef.current?.firstElementChild;
     if (element) {
-      registerTarget(id, { action, param, value, name, element });
+      registerTarget(id, { action, param, value, name, element, prepareView: prepareViewRef.current });
     }
     return () => unregisterTarget(id);
   }, [id, action, param, value, name, registerTarget, unregisterTarget]);