import type { Page } from "playwright";

/**
 * A single step in a keyboard interaction sequence.
 *
 * - `focus`  — focuses a DOM element via CSS selector.
 * - `type`   — types text character by character with a humanlike delay.
 * - `press`  — sends a single named key (e.g. "ArrowDown", "Enter", "Escape", "Tab").
 * - `wait`   — pauses execution for the given number of milliseconds.
 */
export type KbStep =
  | { kind: "focus"; selector: string }
  | { kind: "type"; text: string; delayMs?: number }
  | { kind: "press"; key: string }
  | { kind: "wait"; ms: number };

/**
 * pw_keyboard_sequence — executes an ordered sequence of keyboard interactions on a Playwright Page.
 *
 * Use to script realistic input flows such as typing into an autocomplete field and then
 * navigating its dropdown with arrow keys before pressing Enter.
 */
export async function pw_keyboard_sequence(
  page: Page,
  sequence: KbStep[]
): Promise<void> {
  for (const step of sequence) {
    switch (step.kind) {
      case "focus":
        await page.locator(step.selector).first().focus();
        break;
      case "type":
        await page.keyboard.type(step.text, { delay: step.delayMs ?? 30 });
        break;
      case "press":
        await page.keyboard.press(step.key);
        break;
      case "wait":
        await page.waitForTimeout(step.ms);
        break;
      default: {
        // TypeScript exhaustiveness check — will also throw at runtime for JS callers.
        const _exhaustive: never = step;
        throw new Error(
          `pw_keyboard_sequence: unknown step kind "${(step as KbStep & { kind: string }).kind}"`
        );
      }
    }
  }
}