Input Simulation

/**
 * Keyboard input simulation interface
 */
interface Keyboard {
  /** Press key down (without releasing) */
  down(key: string, options?: KeyboardDownOptions): Promise<void>;
  /** Release key */
  up(key: string): Promise<void>;
  /** Press and release key */
  press(key: string, options?: KeyboardPressOptions): Promise<void>;
  /** Type text character by character */
  type(text: string, options?: KeyboardTypeOptions): Promise<void>;
  /** Insert text without simulating key events */
  insertText(text: string): Promise<void>;
}

// Access keyboard from page
const keyboard = page.keyboard;

// Basic key presses
await keyboard.press('Enter');
await keyboard.press('Tab');
await keyboard.press('Escape');

// Key combinations
await keyboard.down('Control');
await keyboard.press('a'); // Ctrl+A
await keyboard.up('Control');

// Modifier shortcuts
await keyboard.press('Control+c'); // Copy
await keyboard.press('Control+v'); // Paste
await keyboard.press('Control+Shift+Tab'); // Previous tab

// Type text with realistic delays
await keyboard.type('Hello World!', { delay: 100 });

// Insert text instantly
await keyboard.insertText('Bulk text insertion');

// Complex key sequences
await keyboard.down('Shift');
await keyboard.press('ArrowRight');
await keyboard.press('ArrowRight');
await keyboard.up('Shift'); // Select text
await keyboard.press('Delete');

/**
 * Mouse input simulation interface
 */
interface Mouse {
  /** Move mouse cursor to coordinates */
  move(x: number, y: number, options?: MouseMoveOptions): Promise<void>;
  /** Click at coordinates */
  click(x: number, y: number, options?: MouseClickOptions): Promise<void>;
  /** Double-click at coordinates */
  dblclick(x: number, y: number, options?: MouseDblclickOptions): Promise<void>;
  /** Press mouse button down */
  down(options?: MouseDownOptions): Promise<void>;
  /** Release mouse button */
  up(options?: MouseUpOptions): Promise<void>;
  /** Scroll mouse wheel */
  wheel(deltaX: number, deltaY: number): Promise<void>;
}

// Access mouse from page
const mouse = page.mouse;

// Basic mouse operations
await mouse.move(100, 200);
await mouse.click(100, 200);
await mouse.dblclick(100, 200);

// Drag and drop
await mouse.move(100, 100);
await mouse.down();
await mouse.move(200, 200);
await mouse.up();

// Right-click context menu
await mouse.click(150, 150, { button: 'right' });

// Mouse wheel scrolling
await mouse.wheel(0, -100); // Scroll up
await mouse.wheel(0, 100);  // Scroll down
await mouse.wheel(-50, 0);  // Scroll left
await mouse.wheel(50, 0);   // Scroll right

// Custom click options
await mouse.click(100, 100, {
  button: 'middle',
  clickCount: 2,
  delay: 100
});

// Hold mouse button
await mouse.down({ button: 'left' });
await page.waitForTimeout(1000);
await mouse.up({ button: 'left' });

/**
 * Touch input simulation interface
 */
interface Touchscreen {
  /** Perform single tap gesture */
  tap(x: number, y: number): Promise<void>;
}

// Access touchscreen from page
const touch = page.touchscreen;

// Basic tap gesture
await touch.tap(100, 200);

// Multi-touch simulation (using evaluate)
await page.evaluate(() => {
  // Simulate pinch gesture
  const element = document.elementFromPoint(200, 200);
  if (element) {
    const touchStart = new TouchEvent('touchstart', {
      touches: [
        new Touch({ identifier: 1, target: element, clientX: 100, clientY: 100 }),
        new Touch({ identifier: 2, target: element, clientX: 200, clientY: 100 })
      ]
    });
    element.dispatchEvent(touchStart);
  }
});

/**
 * Element-targeted input methods
 */
interface Page {
  /** Click element by selector */
  click(selector: string, options?: PageClickOptions): Promise<void>;
  /** Double-click element by selector */
  dblclick(selector: string, options?: PageDblclickOptions): Promise<void>;
  /** Fill input element with text */
  fill(selector: string, value: string, options?: PageFillOptions): Promise<void>;
  /** Type text into element */
  type(selector: string, text: string, options?: PageTypeOptions): Promise<void>;
  /** Press key on element */
  press(selector: string, key: string, options?: PagePressOptions): Promise<void>;
  /** Check checkbox or radio button */
  check(selector: string, options?: PageCheckOptions): Promise<void>;
  /** Uncheck checkbox */
  uncheck(selector: string, options?: PageUncheckOptions): Promise<void>;
  /** Select options from dropdown */
  selectOption(selector: string, values: string | string[] | SelectOption | SelectOption[], options?: PageSelectOptionOptions): Promise<string[]>;
  /** Hover over element */
  hover(selector: string, options?: PageHoverOptions): Promise<void>;
  /** Focus element */
  focus(selector: string, options?: PageFocusOptions): Promise<void>;
  /** Dispatch event on element */
  dispatchEvent(selector: string, type: string, eventInit?: any, options?: PageDispatchEventOptions): Promise<void>;
}

// Element-specific interactions
await page.click('button#submit');
await page.fill('input[name="email"]', 'user@example.com');
await page.type('textarea', 'Some long text...', { delay: 50 });
await page.press('input[name="search"]', 'Enter');

// Form interactions
await page.check('input[type="checkbox"]');
await page.selectOption('select[name="country"]', 'USA');

// Hover and focus
await page.hover('.dropdown-trigger');
await page.focus('input[name="username"]');

// Custom events
await page.dispatchEvent('button', 'click', { 
  bubbles: true, 
  cancelable: true 
});

// Advanced click with modifiers
await page.click('a.link', {
  modifiers: ['Control'], // Ctrl+Click to open in new tab
  button: 'middle'        // Middle click
});

// Drag and drop using mouse
const source = await page.locator('#source').boundingBox();
const target = await page.locator('#target').boundingBox();

if (source && target) {
  await page.mouse.move(source.x + source.width / 2, source.y + source.height / 2);
  await page.mouse.down();
  await page.mouse.move(target.x + target.width / 2, target.y + target.height / 2);
  await page.mouse.up();
}

// Using HTML5 drag and drop API
await page.dragAndDrop('#source', '#target');

// Upload single file
await page.setInputFiles('input[type="file"]', 'path/to/file.txt');

// Upload multiple files
await page.setInputFiles('input[type="file"]', [
  'path/to/file1.txt',
  'path/to/file2.txt'
]);

// Upload from buffer
await page.setInputFiles('input[type="file"]', {
  name: 'test.txt',
  mimeType: 'text/plain',
  buffer: Buffer.from('Hello World')
});

// Common shortcuts
await page.keyboard.press('Control+a'); // Select all
await page.keyboard.press('Control+c'); // Copy
await page.keyboard.press('Control+v'); // Paste
await page.keyboard.press('Control+z'); // Undo
await page.keyboard.press('Control+y'); // Redo

// Browser shortcuts
await page.keyboard.press('F5');           // Refresh
await page.keyboard.press('Control+F5');   // Hard refresh
await page.keyboard.press('Control+t');    // New tab
await page.keyboard.press('Control+w');    // Close tab

// Text editing shortcuts
await page.keyboard.press('Home');         // Start of line
await page.keyboard.press('End');          // End of line
await page.keyboard.press('Control+Home'); // Start of document
await page.keyboard.press('Control+End');  // End of document

// Selection shortcuts
await page.keyboard.press('Shift+ArrowRight'); // Select character
await page.keyboard.press('Control+Shift+ArrowRight'); // Select word
await page.keyboard.press('Shift+End'); // Select to end of line

interface KeyboardDownOptions {
  /** Whether to generate a keydown event */
  keydown?: boolean;
}

interface KeyboardPressOptions {
  /** Time to wait between keydown and keyup */
  delay?: number;
}

interface KeyboardTypeOptions {
  /** Time to wait between key presses */
  delay?: number;
}

interface MouseMoveOptions {
  /** Number of intermediate mousemove events */
  steps?: number;
}

interface MouseClickOptions {
  /** Which button to click */
  button?: 'left' | 'right' | 'middle';
  /** Number of clicks */
  clickCount?: number;
  /** Time to wait between mousedown and mouseup */
  delay?: number;
}

interface MouseDblclickOptions {
  /** Which button to double-click */
  button?: 'left' | 'right' | 'middle';
  /** Time to wait between clicks */
  delay?: number;
}

interface MouseDownOptions {
  /** Which button to press */
  button?: 'left' | 'right' | 'middle';
  /** Number of clicks */
  clickCount?: number;
}

interface MouseUpOptions {
  /** Which button to release */
  button?: 'left' | 'right' | 'middle';
  /** Number of clicks */
  clickCount?: number;
}

interface PageClickOptions {
  /** Which button to click */
  button?: 'left' | 'right' | 'middle';
  /** Number of clicks */
  clickCount?: number;
  /** Delay between mousedown and mouseup */
  delay?: number;
  /** Position relative to element */
  position?: { x: number; y: number; };
  /** Modifier keys to hold */
  modifiers?: Array<'Alt' | 'Control' | 'Meta' | 'Shift'>;
  /** Bypass actionability checks */
  force?: boolean;
  /** No action, just perform checks */
  trial?: boolean;
  /** Wait timeout */
  timeout?: number;
}

interface PageFillOptions {
  /** Bypass actionability checks */
  force?: boolean;
  /** No action, just perform checks */
  trial?: boolean;
  /** Wait timeout */
  timeout?: number;
}

interface PageTypeOptions {
  /** Delay between key presses */
  delay?: number;
  /** Wait timeout */
  timeout?: number;
}

interface PageHoverOptions {
  /** Position relative to element */
  position?: { x: number; y: number; };
  /** Modifier keys to hold */
  modifiers?: Array<'Alt' | 'Control' | 'Meta' | 'Shift'>;
  /** Bypass actionability checks */
  force?: boolean;
  /** No action, just perform checks */
  trial?: boolean;
  /** Wait timeout */
  timeout?: number;
}

type SpecialKey = 
  | 'Backspace' | 'Tab' | 'Enter' | 'Shift' | 'Control' | 'Alt' | 'Pause'
  | 'CapsLock' | 'Escape' | 'Space' | 'PageUp' | 'PageDown' | 'End' | 'Home'
  | 'ArrowLeft' | 'ArrowUp' | 'ArrowRight' | 'ArrowDown' | 'Insert' | 'Delete'
  | 'F1' | 'F2' | 'F3' | 'F4' | 'F5' | 'F6' | 'F7' | 'F8' | 'F9' | 'F10' | 'F11' | 'F12'
  | 'NumLock' | 'ScrollLock' | 'Meta' | 'ContextMenu';

type ModifierKey = 'Alt' | 'Control' | 'Meta' | 'Shift';

// Platform-specific aliases
// On macOS: 'Meta' = Command key, 'Control' = Control key
// On Windows/Linux: 'Meta' = Windows key, 'Control' = Control key

// Function keys
await page.keyboard.press('F12'); // Open dev tools

// Navigation keys
await page.keyboard.press('Home');
await page.keyboard.press('End');
await page.keyboard.press('PageDown');

// Modifier combinations
await page.keyboard.press('Control+Shift+I'); // Open dev tools
await page.keyboard.press('Alt+Tab'); // Switch applications

// Text manipulation
await page.keyboard.press('Control+a'); // Select all
await page.keyboard.press('Delete'); // Delete selection