@cognior/iap-sdk 0.1.0

package/src/utils/selectors.ts

@@ -0,0 +1,107 @@
+// src/utils/selectors.ts
+/**
+ * DOM selector utilities.
+ * - Accepts either a CSS selector or an XPath string (your backend sometimes sends XPath).
+ * - We keep the original string; resolution (CSS first, then XPath) happens at render time.
+ */
+
+export function mapDomSelector(input: unknown): string {
+  if (typeof input !== "string") return "";
+  const sel = input.trim();
+  // We don't transform—just normalize whitespace so downstream can decide.
+  return sel;
+}
+
+/** Heuristic to detect if a string looks like XPath (vs CSS). */
+export function isLikelyXPath(sel: string): boolean {
+  const s = sel.trim();
+  if (!s) return false;
+  // Simple checks that cover your samples like "/html[1]/body[1]/..."
+  return (
+    s.startsWith("/") ||
+    s.startsWith(".//") ||
+    s.startsWith("//") ||
+    s.includes("/@") ||
+    /\[\d+\]/.test(s)
+  );
+}
+
+/**
+ * Optional convenience: resolve a selector against the DOM.
+ * Tries CSS first, then XPath. Safe to use anywhere.
+ */
+export function resolveSelector<T extends Element = Element>(
+  sel: string,
+  root: Document | Element = document
+): T | null {
+  if (!sel || typeof sel !== "string") return null;
+
+  // Try CSS
+  try {
+    const cssEl = (root as Document | Element).querySelector(sel) as T | null;
+    if (cssEl) return cssEl;
+  } catch {
+    // ignore invalid CSS: we'll try XPath next
+  }
+
+  // Try XPath
+  try {
+    const doc = root instanceof Document ? root : root.ownerDocument ?? document;
+    const result = doc.evaluate(
+      sel,
+      root as Node,
+      null,
+      XPathResult.FIRST_ORDERED_NODE_TYPE,
+      null
+    );
+    return (result.singleNodeValue as T) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Wait for an element to appear in the DOM with a timeout
+ */
+export function waitForElement<T extends Element = Element>(
+  selector: string,
+  options: { timeout?: number; root?: Document | Element } = {}
+): Promise<T> {
+  const { timeout = 5000, root = document } = options;
+  
+  return new Promise((resolve, reject) => {
+    // Check if element already exists
+    const existingElement = resolveSelector<T>(selector, root);
+    if (existingElement) {
+      resolve(existingElement);
+      return;
+    }
+    
+    let timeoutId: number;
+    let observer: MutationObserver;
+    
+    // Setup timeout
+    timeoutId = window.setTimeout(() => {
+      observer?.disconnect();
+      reject(new Error(`Element not found within timeout: ${selector}`));
+    }, timeout);
+    
+    // Setup mutation observer
+    observer = new MutationObserver(() => {
+      const element = resolveSelector<T>(selector, root);
+      if (element) {
+        clearTimeout(timeoutId);
+        observer.disconnect();
+        resolve(element);
+      }
+    });
+    
+    // Start observing
+    observer.observe(root as Node, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeOldValue: false
+    });
+  });
+}

package/src/utils/stepExecutor.ts

@@ -0,0 +1,345 @@
+// src/utils/stepExecutor.ts
+// Step execution engine for trigger-based flow execution
+
+import type { 
+  ModalSequenceStep, 
+  StepExecutionState, 
+  StepExecutionContext, 
+  FlowRunnerState 
+} from '../experiences/types';
+import { resolveSelector } from './selectors';
+import { normalizeTrigger } from './normalize';
+
+/**
+ * Manages step execution state and trigger handling
+ */
+export class StepExecutor {
+  private state: FlowRunnerState;
+  private steps: ModalSequenceStep[];
+  private flowId: string;
+  
+  constructor(steps: ModalSequenceStep[], flowId: string) {
+    this.steps = steps;
+    this.flowId = flowId;
+    this.state = {
+      currentStepIndex: -1,
+      stepContexts: new Map(),
+      isMultiStep: steps.length > 1,
+      pageLoadTriggersExecuted: new Set()
+    };
+  }
+
+  /**
+   * Initialize step contexts for all steps
+   */
+  public initializeSteps(): void {
+    console.debug(`[DAP] Initializing ${this.steps.length} steps for flow ${this.flowId}`);
+    
+    this.steps.forEach((step, index) => {
+      const stepId = step.stepId || `step-${index + 1}`;
+      const hasElementTrigger = !!(step.elementSelector && step.elementTrigger);
+      
+      const context: StepExecutionContext = {
+        stepIndex: index,
+        stepId: stepId,
+        state: "idle",
+        hasElementTrigger: hasElementTrigger,
+        triggerListeners: []
+      };
+      
+      this.state.stepContexts.set(index, context);
+      
+      console.debug(`[DAP] Step ${stepId} (${index}): hasElementTrigger=${hasElementTrigger}, trigger="${step.elementTrigger}"`);
+    });
+  }
+
+  /**
+   * Start execution from a specific step index
+   */
+  public async startFromStep(startIndex: number): Promise<void> {
+    const clampedIndex = Math.max(0, Math.min(startIndex, this.steps.length - 1));
+    console.debug(`[DAP] Starting flow execution from step ${clampedIndex}`);
+    
+    this.state.currentStepIndex = clampedIndex;
+    await this.executeStep(clampedIndex);
+  }
+
+  /**
+   * Execute a specific step based on its trigger configuration
+   */
+  private async executeStep(stepIndex: number): Promise<void> {
+    const step = this.steps[stepIndex];
+    const context = this.state.stepContexts.get(stepIndex);
+    
+    if (!step || !context) {
+      console.error(`[DAP] Invalid step or context for index ${stepIndex}`);
+      return;
+    }
+
+    console.debug(`[DAP] Executing step ${context.stepId} with state ${context.state}`);
+
+    // Check if step has trigger configuration
+    if (context.hasElementTrigger && step.elementSelector && step.elementTrigger) {
+      await this.executeTriggeredStep(stepIndex, step, context);
+    } else {
+      // No trigger - render immediately with navigation controls
+      await this.executeImmediateStep(stepIndex, step, context);
+    }
+  }
+
+  /**
+   * Execute a step that requires a trigger
+   */
+  private async executeTriggeredStep(
+    stepIndex: number, 
+    step: ModalSequenceStep, 
+    context: StepExecutionContext
+  ): Promise<void> {
+    
+    // Handle page load triggers specially
+    if (step.elementTrigger === "on page load") {
+      await this.handlePageLoadTrigger(stepIndex, step, context);
+      return;
+    }
+
+    // Find the target element
+    const targetElement = this.findTargetElement(step.elementSelector!);
+    if (!targetElement) {
+      console.warn(`[DAP] Element not found for selector "${step.elementSelector}", falling back to immediate execution`);
+      await this.executeImmediateStep(stepIndex, step, context);
+      return;
+    }
+
+    // Set up trigger listeners
+    context.targetElement = targetElement;
+    context.state = "waiting-for-trigger";
+    
+    this.setupTriggerListeners(stepIndex, step, context, targetElement);
+    
+    console.debug(`[DAP] Step ${context.stepId} is now waiting for trigger "${step.elementTrigger}" on element`, targetElement);
+  }
+
+  /**
+   * Execute a step immediately with navigation controls
+   */
+  private async executeImmediateStep(
+    stepIndex: number, 
+    step: ModalSequenceStep, 
+    context: StepExecutionContext
+  ): Promise<void> {
+    console.debug(`[DAP] Executing step ${context.stepId} immediately (no trigger)`);
+    
+    context.state = "rendered";
+    
+    // Render the step with navigation controls if multi-step
+    await this.renderStepWithNavigation(stepIndex, step, context);
+  }
+
+  /**
+   * Handle page load triggers with deduplication
+   */
+  private async handlePageLoadTrigger(
+    stepIndex: number, 
+    step: ModalSequenceStep, 
+    context: StepExecutionContext
+  ): Promise<void> {
+    const stepId = context.stepId;
+    
+    // Check if this page load trigger has already been executed
+    if (this.state.pageLoadTriggersExecuted.has(stepId)) {
+      console.debug(`[DAP] Page load trigger for step ${stepId} already executed, skipping`);
+      return;
+    }
+
+    console.debug(`[DAP] Executing page load trigger for step ${stepId}`);
+    
+    // Mark as executed for this page lifecycle
+    this.state.pageLoadTriggersExecuted.add(stepId);
+    context.state = "rendered";
+    context.lastTriggeredTime = Date.now();
+    
+    // Render without navigation controls (triggered steps don't get navigation)
+    await this.renderStepWithoutNavigation(stepIndex, step, context);
+  }
+
+  /**
+   * Set up event listeners for triggered steps
+   */
+  private setupTriggerListeners(
+    stepIndex: number,
+    step: ModalSequenceStep,
+    context: StepExecutionContext,
+    targetElement: HTMLElement
+  ): void {
+    const normalizedTrigger = normalizeTrigger(step.elementTrigger);
+    
+    const triggerHandler = (event: Event) => {
+      console.debug(`[DAP] Trigger "${normalizedTrigger}" fired for step ${context.stepId}`);
+      
+      // Update context
+      context.state = "rendered";
+      context.lastTriggeredTime = Date.now();
+      
+      // Clean up listeners before rendering
+      this.cleanupStepListeners(context);
+      
+      // Render the step without navigation
+      this.renderStepWithoutNavigation(stepIndex, step, context);
+    };
+
+    // Map trigger types to event types
+    const eventType = this.mapTriggerToEventType(normalizedTrigger);
+    if (!eventType) {
+      console.warn(`[DAP] Unknown trigger type "${step.elementTrigger}", falling back to click`);
+      targetElement.addEventListener('click', triggerHandler);
+      context.triggerListeners!.push(() => targetElement.removeEventListener('click', triggerHandler));
+    } else {
+      eventType.forEach(eventName => {
+        targetElement.addEventListener(eventName, triggerHandler);
+        context.triggerListeners!.push(() => targetElement.removeEventListener(eventName, triggerHandler));
+      });
+    }
+  }
+
+  /**
+   * Map trigger string to DOM event types
+   */
+  private mapTriggerToEventType(trigger: string): string[] | null {
+    switch (trigger.toLowerCase()) {
+      case 'click':
+      case 'on click':
+        return ['click'];
+      case 'hover':
+      case 'on hover':
+        return ['mouseenter'];
+      case 'focus':
+      case 'on focus':
+        return ['focus'];
+      case 'blur':
+      case 'on blur':
+        return ['blur'];
+      case 'change':
+      case 'on change':
+        return ['change'];
+      case 'input':
+      case 'on input':
+        return ['input'];
+      default:
+        return null;
+    }
+  }
+
+  /**
+   * Find target element using CSS selector or XPath
+   */
+  private findTargetElement(selector: string): HTMLElement | null {
+    try {
+      return resolveSelector(selector) as HTMLElement;
+    } catch (error) {
+      console.error(`[DAP] Error resolving selector "${selector}":`, error);
+      return null;
+    }
+  }
+
+  /**
+   * Navigate to the next step
+   */
+  public async goToNextStep(): Promise<void> {
+    if (this.state.currentStepIndex < this.steps.length - 1) {
+      const currentContext = this.state.stepContexts.get(this.state.currentStepIndex);
+      if (currentContext) {
+        currentContext.state = "completed";
+        this.cleanupStepListeners(currentContext);
+      }
+      
+      this.state.currentStepIndex++;
+      await this.executeStep(this.state.currentStepIndex);
+    }
+  }
+
+  /**
+   * Navigate to the previous step
+   */
+  public async goToPreviousStep(): Promise<void> {
+    if (this.state.currentStepIndex > 0) {
+      const currentContext = this.state.stepContexts.get(this.state.currentStepIndex);
+      if (currentContext) {
+        currentContext.state = "idle";
+        this.cleanupStepListeners(currentContext);
+      }
+      
+      this.state.currentStepIndex--;
+      await this.executeStep(this.state.currentStepIndex);
+    }
+  }
+
+  /**
+   * Clean up event listeners for a step
+   */
+  private cleanupStepListeners(context: StepExecutionContext): void {
+    if (context.triggerListeners) {
+      context.triggerListeners.forEach(cleanup => cleanup());
+      context.triggerListeners = [];
+    }
+  }
+
+  /**
+   * Clean up all resources
+   */
+  public cleanup(): void {
+    console.debug(`[DAP] Cleaning up step executor for flow ${this.flowId}`);
+    
+    this.state.stepContexts.forEach(context => {
+      this.cleanupStepListeners(context);
+    });
+    
+    this.state.stepContexts.clear();
+    this.state.pageLoadTriggersExecuted.clear();
+  }
+
+  /**
+   * Get current step context
+   */
+  public getCurrentStepContext(): StepExecutionContext | undefined {
+    return this.state.stepContexts.get(this.state.currentStepIndex);
+  }
+
+  /**
+   * Get step context by index
+   */
+  public getStepContext(index: number): StepExecutionContext | undefined {
+    return this.state.stepContexts.get(index);
+  }
+
+  /**
+   * Check if step has navigation controls (no trigger defined)
+   */
+  public stepHasNavigationControls(stepIndex: number): boolean {
+    const context = this.state.stepContexts.get(stepIndex);
+    return context ? !context.hasElementTrigger : true; // Default to true for safety
+  }
+
+  /**
+   * Placeholder for rendering step with navigation - to be implemented by modalSequence
+   */
+  private async renderStepWithNavigation(
+    stepIndex: number, 
+    step: ModalSequenceStep, 
+    context: StepExecutionContext
+  ): Promise<void> {
+    // This will be called by the modalSequence renderer
+    console.debug(`[DAP] Would render step ${context.stepId} with navigation controls`);
+  }
+
+  /**
+   * Placeholder for rendering step without navigation - to be implemented by modalSequence
+   */
+  private async renderStepWithoutNavigation(
+    stepIndex: number, 
+    step: ModalSequenceStep, 
+    context: StepExecutionContext
+  ): Promise<void> {
+    // This will be called by the modalSequence renderer
+    console.debug(`[DAP] Would render step ${context.stepId} without navigation controls`);
+  }
+}

package/src/utils/triggerNormalizer.ts

@@ -0,0 +1,149 @@
+// src/utils/triggerNormalizer.ts
+// Trigger normalization utilities for DAP SDK
+
+import { resolveSelector } from './selectors';
+
+/**
+ * Normalize backend trigger strings to DOM event types
+ */
+export function normalizeTrigger(trigger: string | undefined | null): {
+  eventType: string;
+  isSynthetic: boolean;
+} {
+  if (!trigger) {
+    console.warn('[DAP] No trigger specified, defaulting to click');
+    return { eventType: 'click', isSynthetic: false };
+  }
+
+  const normalizedTrigger = trigger.toLowerCase().trim();
+  
+  console.debug(`[DAP] Normalizing trigger: "${trigger}" → processing "${normalizedTrigger}"`);
+
+  // Handle synthetic triggers (SDK controlled)
+  if (normalizedTrigger === 'on page load' || normalizedTrigger === 'page load' || normalizedTrigger === 'pageload') {
+    console.debug(`[DAP] Trigger normalized: "${trigger}" → synthetic page load`);
+    return { eventType: 'pageload', isSynthetic: true };
+  }
+
+  // Handle hover triggers
+  if (normalizedTrigger === 'on hover' || normalizedTrigger === 'hover' || normalizedTrigger === 'mouseover') {
+    console.debug(`[DAP] Trigger normalized: "${trigger}" → "mouseenter"`);
+    return { eventType: 'mouseenter', isSynthetic: false };
+  }
+
+  // Handle click triggers  
+  if (normalizedTrigger === 'on click' || normalizedTrigger === 'click') {
+    console.debug(`[DAP] Trigger normalized: "${trigger}" → "click"`);
+    return { eventType: 'click', isSynthetic: false };
+  }
+
+  // Handle focus triggers
+  if (normalizedTrigger === 'on focus' || normalizedTrigger === 'focus') {
+    console.debug(`[DAP] Trigger normalized: "${trigger}" → "focus"`);
+    return { eventType: 'focus', isSynthetic: false };
+  }
+
+  // Handle blur triggers
+  if (normalizedTrigger === 'on blur' || normalizedTrigger === 'blur') {
+    console.debug(`[DAP] Trigger normalized: "${trigger}" → "blur"`);
+    return { eventType: 'blur', isSynthetic: false };
+  }
+
+  // Handle input/typing triggers
+  if (normalizedTrigger === 'on input' || normalizedTrigger === 'input' || normalizedTrigger === 'typing') {
+    console.debug(`[DAP] Trigger normalized: "${trigger}" → "input"`);
+    return { eventType: 'input', isSynthetic: false };
+  }
+
+  // Handle change triggers
+  if (normalizedTrigger === 'on change' || normalizedTrigger === 'change') {
+    console.debug(`[DAP] Trigger normalized: "${trigger}" → "change"`);
+    return { eventType: 'change', isSynthetic: false };
+  }
+
+  // Handle keydown triggers
+  if (normalizedTrigger === 'on keydown' || normalizedTrigger === 'keydown') {
+    console.debug(`[DAP] Trigger normalized: "${trigger}" → "keydown"`);
+    return { eventType: 'keydown', isSynthetic: false };
+  }
+
+  // Handle keyup triggers
+  if (normalizedTrigger === 'on keyup' || normalizedTrigger === 'keyup') {
+    console.debug(`[DAP] Trigger normalized: "${trigger}" → "keyup"`);
+    return { eventType: 'keyup', isSynthetic: false };
+  }
+
+  // Default fallback
+  console.warn(`[DAP] Unknown trigger type: "${trigger}", defaulting to click`);
+  return { eventType: 'click', isSynthetic: false };
+}
+
+/**
+ * Wait for an element to exist in the DOM with timeout and retry
+ */
+export function waitForElement(
+  selector: string, 
+  options: {
+    timeout?: number;
+    interval?: number;
+    maxRetries?: number;
+  } = {}
+): Promise<Element> {
+  const { 
+    timeout = 10000,  // 10 seconds default
+    interval = 100,   // Check every 100ms
+    maxRetries = timeout / interval
+  } = options;
+
+  return new Promise((resolve, reject) => {
+    let attempts = 0;
+
+    const checkElement = () => {
+      attempts++;
+      console.debug(`[DAP] Attempting to find element (${attempts}/${maxRetries}): ${selector}`);
+      
+      try {
+        // Use resolveSelector utility which handles both CSS and XPath
+        const element = resolveSelector(selector);
+        
+        if (element) {
+          console.debug(`[DAP] Element found after ${attempts} attempts: ${selector}`);
+          resolve(element);
+          return;
+        }
+      } catch (error) {
+        console.debug(`[DAP] Error finding element: ${error}`);
+      }
+
+      if (attempts >= maxRetries) {
+        console.warn(`[DAP] Element not found after ${attempts} attempts (${timeout}ms): ${selector}`);
+        reject(new Error(`Element not found: ${selector}`));
+        return;
+      }
+
+      setTimeout(checkElement, interval);
+    };
+
+    // Start checking immediately
+    checkElement();
+  });
+}
+
+/**
+ * Evaluate XPath expression
+ */
+function evaluateXPath(xpath: string): Element | null {
+  try {
+    const result = document.evaluate(
+      xpath,
+      document,
+      null,
+      XPathResult.FIRST_ORDERED_NODE_TYPE,
+      null
+    );
+    return result.singleNodeValue as Element | null;
+  } catch (error) {
+    console.debug(`[DAP] XPath evaluation failed: ${error}`);
+    return null;
+  }
+}