/**
 * ActionEngine Types
 *
 * Defines the types for the unified execution layer for interventions
 * (highlight, tooltip, badge, DOM modifications, navigation).
 */
import type { Placement } from '@floating-ui/dom';
/** Static surface slots with fixed positioning */
export type StaticSurfaceSlot = 'drawer_right' | 'drawer_left' | 'drawer_bottom' | 'overlay_center' | 'overlay_corner_br' | 'overlay_corner_bl' | 'toast_top' | 'toast_bottom';
/** Dynamic inline slot (rendered inside anchor) */
export type InlineSurfaceSlot = `inline:${string}`;
/** Dynamic adjacent slot (positioned near anchor) */
export type AdjacentSurfaceSlot = `adjacent:${string}`;
/** All surface slot types */
export type SurfaceSlot = StaticSurfaceSlot | InlineSurfaceSlot | AdjacentSurfaceSlot;
/** Highlight style configuration */
export interface HighlightStyle {
    /** Ring color (default: "#5b8cff") */
    color?: string;
    /** Backdrop scrim opacity 0-1 (default: 0.55, set to 0 to hide) */
    scrimOpacity?: number;
    /** Space between element and ring in pixels (default: 12) */
    paddingPx?: number;
    /** Ring corner radius in pixels (default: 12) */
    radiusPx?: number;
}
/** Badge position relative to anchor */
export type BadgePosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
/** CTA button configuration for tooltips/modals */
export interface CtaButton {
    label: string;
    actionId: string;
    primary?: boolean;
}
/** Modal content configuration */
export interface ModalContent {
    title?: string;
    body: string;
}
/** Tooltip content configuration */
export interface TooltipContent {
    title?: string;
    body: string;
    cta?: {
        label: string;
        action: ActionStep;
    };
    ctaButtons?: CtaButton[];
}
/** Tooltip trigger mode */
export type TooltipTrigger = 'immediate' | 'hover' | 'click';
/** Position where HTML/content should be inserted */
export type InsertPosition = 'before' | 'after' | 'prepend' | 'append' | 'replace';
/** Widget configuration for surface mounting */
export interface WidgetConfig {
    widgetId: string;
    props?: Record<string, unknown>;
    priority?: number;
}
/** Base action with common properties */
interface BaseAction {
    /** Optional label for debugging/telemetry */
    label?: string;
}
/** Highlight an anchor element with spotlight effect */
export interface HighlightAction extends BaseAction {
    kind: 'overlays:highlight';
    anchorId: string;
    style?: HighlightStyle;
    /** Duration in ms before auto-cleanup (for use in sequences) */
    duration?: number;
}
/** Pulse animation on an anchor element */
export interface PulseAction extends BaseAction {
    kind: 'overlays:pulse';
    anchorId: string;
    duration?: number;
}
/** Add a badge near an anchor element */
export interface BadgeAction extends BaseAction {
    kind: 'overlays:badge';
    anchorId: string;
    content: string;
    position?: BadgePosition;
}
/** Tooltip lifecycle - when the action completes (for sequences) */
export type TooltipWaitFor = 'dismissed' | 'cta-click' | `timeout:${number}`;
/** Show a tooltip near an anchor element */
export interface TooltipAction extends BaseAction {
    kind: 'overlays:tooltip';
    anchorId: string;
    content: TooltipContent;
    trigger?: TooltipTrigger;
    placement?: Placement;
    /** When the action completes (for use in sequences). Publishes event to EventBus. */
    waitFor?: TooltipWaitFor;
}
/** Modal lifecycle - when the action completes (for sequences) */
export type ModalWaitFor = 'dismissed' | 'cta-click' | `timeout:${number}`;
/** Show a centered modal dialog */
export interface ModalAction extends BaseAction {
    kind: 'overlays:modal';
    content: ModalContent;
    size?: 'sm' | 'md' | 'lg';
    blocking?: boolean;
    scrim?: {
        opacity?: number;
    };
    dismiss?: {
        onEsc?: boolean;
        closeButton?: boolean;
        timeoutMs?: number;
    };
    ctaButtons?: CtaButton[];
    /** When the action completes (for use in sequences). Publishes event to EventBus. */
    waitFor?: ModalWaitFor;
}
/** Insert HTML content relative to anchor */
export interface InsertHtmlAction extends BaseAction {
    kind: 'content:insertHtml';
    anchorId: string;
    html: string;
    position: InsertPosition;
}
/** Set text content of an anchor */
export interface SetTextAction extends BaseAction {
    kind: 'content:setText';
    anchorId: string;
    text: string;
}
/** Set an attribute on an anchor */
export interface SetAttrAction extends BaseAction {
    kind: 'content:setAttr';
    anchorId: string;
    attr: string;
    value: string;
}
/** Add a CSS class to an anchor */
export interface AddClassAction extends BaseAction {
    kind: 'content:addClass';
    anchorId: string;
    className: string;
}
/** Remove a CSS class from an anchor */
export interface RemoveClassAction extends BaseAction {
    kind: 'content:removeClass';
    anchorId: string;
    className: string;
}
/** Set inline styles on an anchor */
export interface SetStyleAction extends BaseAction {
    kind: 'content:setStyle';
    anchorId: string;
    styles: Record<string, string>;
}
/** Mount a widget to a surface slot */
export interface MountWidgetAction extends BaseAction {
    kind: 'core:mountWidget';
    slot: SurfaceSlot;
    widget: WidgetConfig;
}
/** Scroll to an anchor element */
export interface ScrollToAction extends BaseAction {
    kind: 'navigation:scrollTo';
    anchorId: string;
    behavior?: ScrollBehavior;
    block?: ScrollLogicalPosition;
    inline?: ScrollLogicalPosition;
}
/** Navigate to a URL */
export interface NavigateAction extends BaseAction {
    kind: 'navigation:navigate';
    url: string;
    target?: '_self' | '_blank';
}
/** Wait for a duration or an event on the EventBus */
export interface WaitAction extends BaseAction {
    kind: 'core:wait';
    /** Wait for a specific duration in milliseconds */
    durationMs?: number;
    /** Wait for an event on the EventBus */
    event?: string;
}
/** Execute actions in sequence, awaiting each one's completion */
export interface SequenceAction extends BaseAction {
    kind: 'core:sequence';
    actions: ActionStep[];
}
/** Execute actions in parallel */
export interface ParallelAction extends BaseAction {
    kind: 'core:parallel';
    actions: ActionStep[];
    /** How to determine completion: "all" waits for all, "any" completes when first finishes */
    waitFor?: 'all' | 'any';
}
/** Tour step with route + action mapping */
export interface TourStep {
    id: string;
    action: ActionStep;
    route?: string;
    onAction?: Record<string, string | 'end'>;
}
/** Orchestrate sequential steps with cross-page state */
export interface TourAction extends BaseAction {
    kind: 'core:tour';
    tourId: string;
    steps: TourStep[];
    startStep?: string;
    autoStart?: boolean;
}
/** Union of all action step types */
export type ActionStep = HighlightAction | PulseAction | BadgeAction | TooltipAction | ModalAction | InsertHtmlAction | SetTextAction | SetAttrAction | AddClassAction | RemoveClassAction | SetStyleAction | MountWidgetAction | ScrollToAction | NavigateAction | WaitAction | SequenceAction | ParallelAction | TourAction;
/** Extract action kind literal types */
export type ActionKind = ActionStep['kind'];
/** State of an action */
export type ActionState = 'pending' | 'applied' | 'reverted' | 'failed';
/** Handle returned when an action is applied */
export interface ActionHandle {
    /** Unique ID for this action instance */
    id: string;
    /** The action that was applied */
    action: ActionStep;
    /** Revert the action */
    revert: () => Promise<void>;
    /** Check if action is still applied */
    isApplied: () => boolean;
    /** Update action in place (if supported) */
    update: (changes: Partial<ActionStep>) => Promise<void>;
    /** Get current state */
    getState: () => ActionState;
}
/** Handle for batch action operations */
export interface BatchActionHandle {
    /** Unique ID for this batch */
    id: string;
    /** Individual action handles */
    handles: ActionHandle[];
    /** Revert all actions in the batch */
    revertAll: () => Promise<void>;
    /** Check if all actions are still applied */
    isApplied: () => boolean;
}
/** Tracked active action */
export interface ActiveAction {
    /** Action ID */
    id: string;
    /** The action definition */
    action: ActionStep;
    /** Adaptive that owns this action */
    adaptiveId?: string;
    /** When the action was applied */
    appliedTs: number;
    /** Current state */
    state: ActionState;
}
/** Validation error */
export interface ValidationError {
    code: string;
    message: string;
    field?: string;
}
/** Validation warning */
export interface ValidationWarning {
    code: string;
    message: string;
    suggestion?: string;
}
/** Result of validating an action */
export interface ValidationResult {
    valid: boolean;
    errors: ValidationError[];
    warnings: ValidationWarning[];
}
/** Cleanup function returned by executors */
export type ExecutorCleanup = () => void | Promise<void>;
/** Update function for actions that support in-place updates */
export type ExecutorUpdate = (changes: Partial<ActionStep>) => void | Promise<void>;
/** Result returned by action executors */
export interface ExecutorResult {
    /** Function to clean up/revert the action */
    cleanup: ExecutorCleanup;
    /** Optional function to update the action in place */
    updateFn?: ExecutorUpdate;
}
/** Executor function signature */
export type ActionExecutor<T extends ActionStep = ActionStep> = (action: T, context: ExecutorContext) => Promise<ExecutorResult>;
/** Context passed to executors */
export interface ExecutorContext {
    /** Overlay root element for rendering */
    overlayRoot: HTMLElement;
    /** Resolve an anchor ID to an element */
    resolveAnchor: (anchorId: string) => HTMLElement | null;
    /** Generate unique IDs */
    generateId: () => string;
    /** Publish events to EventBus */
    publishEvent: (name: string, props?: Record<string, unknown>) => void;
    /** Get the current adaptive ID (if any) */
    adaptiveId?: string;
    /**
     * Execute a nested action (for composite executors like tours).
     * Returns a handle that can be used to revert the action.
     */
    applyAction?: (action: ActionStep) => Promise<ActionHandle>;
    /**
     * Subscribe to events (for composite executors).
     * Returns an unsubscribe function.
     */
    subscribeEvent?: (name: string, callback: (props?: Record<string, unknown>) => void) => () => void;
    /**
     * Subscribe to navigation changes (pushState, replaceState, popstate).
     * Provided by NavigationMonitor. Returns an unsubscribe function.
     */
    subscribeNavigation?: (callback: (url: string, method: string) => void) => () => void;
}
/** Executor registry interface (subset needed by ActionEngine) */
export interface ActionEngineExecutorRegistry {
    get: (kind: string) => ActionExecutor<ActionStep> | undefined;
    has: (kind: string) => boolean;
}
/** Options for creating an ActionEngine */
export interface ActionEngineOptions {
    /** Overlay root element */
    overlayRoot: HTMLElement;
    /** Event bus for publishing and subscribing to action events */
    eventBus?: {
        publish: (name: string, props?: Record<string, unknown>) => void;
        subscribe: (filter: {
            names?: string[];
            patterns?: string[];
        }, callback: (event: {
            name: string;
            props?: Record<string, unknown>;
        }) => void) => () => void;
    };
    /** Surfaces provider for mountWidget actions */
    surfaces?: {
        mount: (slot: SurfaceSlot, content: RenderableContent, opts?: MountOptions) => MountHandle;
    };
    /** Function to resolve anchor IDs to elements */
    anchorResolver: (anchorId: string) => HTMLElement | null;
    /** Current adaptive ID for attribution */
    adaptiveId?: string;
    /** Optional executor registry (uses default singleton if not provided) */
    executorRegistry?: ActionEngineExecutorRegistry;
    /** Subscribe to navigation changes (from NavigationMonitor) */
    subscribeNavigation?: (callback: (url: string, method: string) => void) => () => void;
}
/** The ActionEngine interface */
export interface ActionEngine {
    /** Apply a single action */
    apply: (action: ActionStep) => Promise<ActionHandle>;
    /** Apply multiple actions atomically */
    applyBatch: (actions: ActionStep[]) => Promise<BatchActionHandle>;
    /** Validate an action before applying */
    validate: (action: ActionStep) => ValidationResult;
    /** Get all currently active actions */
    getActive: () => ActiveAction[];
    /** Clean up all active actions and resources */
    destroy: () => void;
}
/** Renderable content types for surfaces */
export type RenderableContent = {
    type: 'react';
    component: unknown;
    props?: Record<string, unknown>;
} | {
    type: 'html';
    content: string;
} | {
    type: 'widget';
    widgetId: string;
    config?: Record<string, unknown>;
} | {
    type: 'custom';
    mount: (container: HTMLElement) => () => void;
};
/** Mount options for surfaces */
export interface MountOptions {
    priority?: number;
    exclusive?: boolean;
    animation?: 'fade' | 'slide' | 'scale' | 'none';
    position?: {
        placement: Placement | 'auto';
        offset?: {
            x: number;
            y: number;
        };
        flip?: boolean;
        shift?: boolean;
    };
    constraints?: {
        maxWidth?: string;
        maxHeight?: string;
        minWidth?: string;
        minHeight?: string;
    };
}
/** Mount handle returned by Surfaces */
export interface MountHandle {
    update: (content: RenderableContent) => void;
    setOptions: (opts: Partial<MountOptions>) => void;
    unmount: () => void;
    isMounted: () => boolean;
    getContainer: () => HTMLElement | null;
}
export {};
