@mydatavalue/polter 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,220 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React$1 from 'react';
+
+type ExecutionMode = 'guided' | 'instant';
+interface ExecutionTarget {
+    label: string;
+    element: HTMLElement | null;
+    /** Resolve element from AgentTarget registry by matching this param's value. */
+    fromParam?: string;
+    /** Resolve element from AgentTarget registry by matching a named target. */
+    fromTarget?: string;
+    /** Simulate typing the value of this param into the element. */
+    setParam?: string;
+    /** Set a value programmatically via onSetValue callback. */
+    setValue?: string;
+    onSetValue?: (value: unknown) => void;
+    /** Run a callback to prepare the DOM (e.g. scroll virtualized list) before resolving. */
+    prepareView?: (params: Record<string, unknown>) => void | Promise<void>;
+}
+interface AgentTargetEntry {
+    /** Action name — when omitted, the target is shared and matches any action. */
+    action?: string;
+    element: HTMLElement;
+    /** Parameter key — used with `value` for param-based resolution. */
+    param?: string;
+    /** Parameter value — matched against the agent's param value. */
+    value?: string;
+    /** Named target key — used for static lazy resolution via `fromTarget`. */
+    name?: string;
+}
+interface RegisteredAction {
+    name: string;
+    description: string;
+    parameters?: unknown;
+    onExecute?: (params: Record<string, unknown>) => void | Promise<void>;
+    disabled: boolean;
+    disabledReason?: string;
+    getExecutionTargets: () => ExecutionTarget[];
+}
+interface ToolSchema {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+interface ExecutionResult {
+    success: boolean;
+    actionName: string;
+    error?: string;
+}
+interface AvailableAction {
+    name: string;
+    description: string;
+    disabled: boolean;
+    disabledReason?: string;
+    hasParameters: boolean;
+}
+interface ExecutorConfig {
+    mode: ExecutionMode;
+    stepDelay: number;
+    overlayOpacity: number;
+    spotlightPadding: number;
+    tooltipEnabled: boolean;
+    cursorEnabled: boolean;
+    signal?: AbortSignal;
+    /** 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>;
+}
+interface AgentActionProviderProps {
+    mode?: ExecutionMode;
+    stepDelay?: number;
+    overlayOpacity?: number;
+    spotlightPadding?: number;
+    tooltipEnabled?: boolean;
+    cursorEnabled?: boolean;
+    children: React.ReactNode;
+    onExecutionStart?: (actionName: string) => void;
+    onExecutionComplete?: (result: ExecutionResult) => void;
+}
+interface AgentActionContextValue {
+    registerAction: (action: RegisteredAction) => void;
+    unregisterAction: (name: string) => void;
+    registerTarget: (id: string, entry: AgentTargetEntry) => void;
+    unregisterTarget: (id: string) => void;
+    execute: (actionName: string, params?: Record<string, unknown>) => Promise<ExecutionResult>;
+    availableActions: AvailableAction[];
+    schemas: ToolSchema[];
+    isExecuting: boolean;
+    mode: ExecutionMode;
+}
+
+declare function AgentActionProvider({ mode, stepDelay, overlayOpacity, spotlightPadding, tooltipEnabled, cursorEnabled, children, onExecutionStart, onExecutionComplete, }: AgentActionProviderProps): react_jsx_runtime.JSX.Element;
+
+interface AgentActionProps {
+    name: string;
+    description: string;
+    parameters?: unknown;
+    onExecute?: (params: Record<string, unknown>) => void | Promise<void>;
+    disabled?: boolean;
+    disabledReason?: string;
+    children?: React$1.ReactNode;
+}
+declare function AgentAction({ name, description, parameters, onExecute, disabled, disabledReason, children, }: AgentActionProps): react_jsx_runtime.JSX.Element | null;
+
+interface AgentStepProps {
+    label: string;
+    children?: React$1.ReactNode;
+    /** Resolve the target element from the AgentTarget registry by matching this param's value. */
+    fromParam?: string;
+    /** Resolve a named target from the AgentTarget registry (for static elements inside popovers/dropdowns). */
+    fromTarget?: string;
+    /** Simulate typing the value of this param into the element. */
+    setParam?: string;
+    /** Set a value programmatically via onSetValue callback. */
+    setValue?: string;
+    /** Callback for setValue — receives the param value and sets it on the component. */
+    onSetValue?: (value: unknown) => void;
+    /** Run a callback to prepare the DOM (e.g. scroll a virtualized list) before resolving the target. */
+    prepareView?: (params: Record<string, unknown>) => void | Promise<void>;
+}
+declare function AgentStep({ label, children, fromParam, fromTarget, setParam, setValue, onSetValue, prepareView, }: AgentStepProps): react_jsx_runtime.JSX.Element | null;
+
+interface AgentTargetProps {
+    /** The action name this target belongs to. Omit to make a shared target that any action can resolve. */
+    action?: string;
+    children: React$1.ReactNode;
+    /** The parameter key this target maps to (for fromParam resolution). */
+    param?: string;
+    /** The parameter value this target represents (for fromParam resolution). */
+    value?: string;
+    /** Named target key (for fromTarget resolution — static elements inside popovers/dropdowns). */
+    name?: string;
+}
+/**
+ * Register a DOM element as a selectable target for an agent action step.
+ *
+ * Use this to wrap lazily-rendered elements (dropdown options, search results, etc.)
+ * so that `AgentStep fromParam` or `AgentStep fromTarget` can find and interact
+ * with them after they mount.
+ *
+ * Works through React portals — context flows regardless of DOM position.
+ *
+ * @example
+ * ```tsx
+ * // Dynamic: match by param value (inside a dropdown's renderOption):
+ * <AgentTarget action="filter_by_tag" param="tag_name" value={option.label}>
+ *   <DropdownOption>{option.label}</DropdownOption>
+ * </AgentTarget>
+ *
+ * // Static: match by name (inside a popover that mounts lazily):
+ * <AgentTarget action="toggle_frozen_columns" name="freeze-btn">
+ *   <button>Freeze columns</button>
+ * </AgentTarget>
+ * ```
+ */
+declare function AgentTarget({ action, param, value, name, children }: AgentTargetProps): react_jsx_runtime.JSX.Element;
+
+interface AgentDevToolsProps {
+    /** Default open state. */
+    defaultOpen?: boolean;
+}
+declare function AgentDevTools({ defaultOpen }: AgentDevToolsProps): react_jsx_runtime.JSX.Element;
+
+interface StepConfig {
+    label: string;
+    fromParam?: string;
+    fromTarget?: string;
+    setParam?: string;
+    setValue?: string;
+    onSetValue?: (value: unknown) => void;
+    prepareView?: (params: Record<string, unknown>) => void | Promise<void>;
+}
+interface AgentActionConfig {
+    name: string;
+    description: string;
+    parameters?: unknown;
+    onExecute?: (params: Record<string, unknown>) => void | Promise<void>;
+    disabled?: boolean;
+    disabledReason?: string;
+    steps?: StepConfig[];
+}
+/**
+ * Hook-based action registration for actions that don't wrap a single element.
+ * Use this for per-row actions where AgentTargets are on scattered elements
+ * and the action resolves to them via fromParam/fromTarget.
+ *
+ * Accepts a single config or an array to batch-register multiple actions.
+ *
+ * For actions that wrap a visible element, prefer the <AgentAction> component.
+ */
+declare function useAgentAction(config: AgentActionConfig | AgentActionConfig[]): void;
+
+declare function useAgentActions(): AgentActionContextValue;
+
+/**
+ * Wraps an existing command handler with agent action routing.
+ *
+ * When a command arrives, if a matching `<AgentAction>` is mounted and enabled,
+ * it routes through `execute()` for visual guided execution. Otherwise it falls
+ * through to the original handler.
+ *
+ * Works with any command shape — you provide `getActionName` to extract the
+ * action name from your command object.
+ *
+ * @example
+ * ```tsx
+ * const handleCommand = useAgentCommandRouter(
+ *   existingHandler,
+ *   (cmd) => cmd.action,
+ * );
+ * ```
+ */
+declare function useAgentCommandRouter<T>(fallback: ((command: T) => void | Promise<void>) | null, getActionName: (command: T) => string): (command: T) => Promise<void>;
+
+type JsonSchema = Record<string, unknown>;
+declare function zodToJsonSchema(schema: unknown): JsonSchema;
+declare function generateToolSchemas(actions: RegisteredAction[]): ToolSchema[];
+
+export { AgentAction, type AgentActionContextValue, AgentActionProvider, type AgentActionProviderProps, AgentDevTools, AgentStep, AgentTarget, type AgentTargetEntry, type AvailableAction, type ExecutionMode, type ExecutionResult, type ExecutionTarget, type ExecutorConfig, type RegisteredAction, type ToolSchema, generateToolSchemas, useAgentAction, useAgentActions, useAgentCommandRouter, zodToJsonSchema };