User Input & Actions

/**
 * Click mouse button at current location
 * @param button - Mouse button (0=left, 1=middle, 2=right)
 * @param cb - Callback receiving (err)
 */
click(button?: number, cb?: callback): void;

/**
 * Double-click at current mouse location
 * @param cb - Callback receiving (err)
 */
doubleclick(cb?: callback): void;

/**
 * Press mouse button down
 * @param button - Mouse button (0=left, 1=middle, 2=right)
 * @param cb - Callback receiving (err)
 */
buttonDown(button?: number, cb?: callback): void;

/**
 * Release mouse button
 * @param button - Mouse button (0=left, 1=middle, 2=right)
 * @param cb - Callback receiving (err)
 */
buttonUp(button?: number, cb?: callback): void;

/**
 * Move mouse to element or coordinates
 * @param element - Target element (optional)
 * @param xOffset - X offset from element center
 * @param yOffset - Y offset from element center
 * @param cb - Callback receiving (err)
 */
moveTo(element?: Element, xOffset?: number, yOffset?: number, cb?: callback): void;

// Basic mouse operations
browser.click(function(err) {
  if (err) throw err;
  console.log('Left click performed');
});

// Right-click context menu
browser.click(2, function(err) {
  console.log('Right-click performed');
});

// Move to element and click
browser.elementById('target-button', function(err, element) {
  browser.moveTo(element, function(err) {
    browser.click();
  });
});

// Promise chain style mouse operations
browser
  .elementByCss('.draggable')
  .moveTo()
  .buttonDown(0)        // Press left button
  .moveTo(null, 100, 50) // Move 100px right, 50px down
  .buttonUp(0);         // Release left button

/**
 * Send keys to currently focused element or browser
 * @param keys - String or array of keys to send
 * @param cb - Callback receiving (err)
 */
keys(keys: string | string[], cb?: callback): void;

/**
 * Type text into specific element
 * @param element - Target element
 * @param keys - Text or keys to type
 * @param cb - Callback receiving (err)
 */
type(element: Element, keys: string | string[], cb?: callback): void;

/**
 * Replace element text content
 * @param element - Target element
 * @param keys - New text content
 * @param cb - Callback receiving (err)
 */
replace(element: Element, keys: string | string[], cb?: callback): void;

/**
 * Clear element text content
 * @param element - Target element
 * @param cb - Callback receiving (err)
 */
clear(element: Element, cb?: callback): void;

const wd = require('wd');

// Type into form fields
browser.elementById('username', function(err, usernameField) {
  browser.type(usernameField, 'testuser@example.com');
});

browser.elementById('password', function(err, passwordField) {
  browser.type(passwordField, 'secretpassword');
});

// Send special keys
browser.keys([wd.SPECIAL_KEYS.Tab, wd.SPECIAL_KEYS.Enter]);

// Clear and replace text
browser.elementById('search-input', function(err, searchField) {
  browser.clear(searchField);
  browser.type(searchField, 'new search term');
});

// Promise chain keyboard input
browser
  .elementById('comment-box')
  .clear()
  .type('This is my comment')
  .keys([wd.SPECIAL_KEYS.Shift, wd.SPECIAL_KEYS.Tab]) // Shift+Tab
  .keys(wd.SPECIAL_KEYS.Enter);

/**
 * Click on specific element
 * @param element - Element to click
 * @param cb - Callback receiving (err)
 */
clickElement(element: Element, cb?: callback): void;

/**
 * Submit form containing the element
 * @param element - Form element or element within form
 * @param cb - Callback receiving (err)
 */
submit(element: Element, cb?: callback): void;

// Click specific elements
browser.elementById('login-button', function(err, button) {
  browser.clickElement(button);
});

// Submit forms
browser.elementById('login-form', function(err, form) {
  browser.submit(form);
});

// Or submit via any form element
browser.elementById('username', function(err, input) {
  browser.type(input, 'user@example.com');
  browser.submit(input); // Submits the containing form
});

/**
 * Tap element (mobile/touch)
 * @param element - Element to tap
 * @param cb - Callback receiving (err)
 */
tapElement(element: Element, cb?: callback): void;

/**
 * Flick gesture on element
 * @param element - Target element
 * @param xSpeed - Horizontal flick speed
 * @param ySpeed - Vertical flick speed
 * @param cb - Callback receiving (err)
 */
flick(element: Element, xSpeed: number, ySpeed: number, cb?: callback): void;

/**
 * Scroll by offset
 * @param xOffset - Horizontal scroll offset
 * @param yOffset - Vertical scroll offset
 * @param cb - Callback receiving (err)
 */
scroll(xOffset: number, yOffset: number, cb?: callback): void;

// Mobile touch interactions
browser.elementByCss('.mobile-button', function(err, button) {
  browser.tapElement(button);
});

// Flick gestures for scrolling
browser.elementByCss('.scrollable-area', function(err, area) {
  browser.flick(area, 0, -100); // Flick up to scroll down
});

// Page scrolling
browser.scroll(0, 300); // Scroll down 300 pixels

// Special keys available in wd.SPECIAL_KEYS
const SPECIAL_KEYS: {
  NULL: string;
  Tab: string;
  Enter: string;
  Return: string;
  Shift: string;
  Control: string;
  Alt: string;
  Pause: string;
  Escape: string;
  Space: string;
  Pageup: string;
  Pagedown: string;
  End: string;
  Home: string;
  'Left arrow': string;
  'Up arrow': string;
  'Right arrow': string;
  'Down arrow': string;
  Insert: string;
  Delete: string;
  'Back space': string;
  Clear: string;
  Help: string;
  Cancel: string;
  // Function keys F1-F12
  F1: string;
  F2: string;
  // ... F3 through F12
  // Numpad keys
  'Numpad 0': string;
  'Numpad 1': string;
  // ... through Numpad 9
  Multiply: string;
  Add: string;
  Subtract: string;
  Decimal: string;
  Divide: string;
  Semicolon: string;
  Equals: string;
  Command: string;
  Meta: string;
};

const wd = require('wd');

// Use special keys for navigation
browser.keys([
  wd.SPECIAL_KEYS.Control,
  'a'  // Ctrl+A to select all
]);

browser.keys(wd.SPECIAL_KEYS.Delete); // Delete selected text

// Form navigation
browser.keys([
  wd.SPECIAL_KEYS.Tab,        // Move to next field
  wd.SPECIAL_KEYS.Tab,        // Move to next field
  wd.SPECIAL_KEYS.Shift,      // Hold Shift
  wd.SPECIAL_KEYS.Tab         // Shift+Tab to go back
]);

// Function keys
browser.keys(wd.SPECIAL_KEYS.F5); // Refresh page
browser.keys(wd.SPECIAL_KEYS.F12); // Developer tools

// Arrow key navigation
browser.keys([
  wd.SPECIAL_KEYS['Down arrow'],
  wd.SPECIAL_KEYS['Down arrow'],
  wd.SPECIAL_KEYS.Enter
]);

/**
 * Upload file to file input element
 * @param filepath - Local path to file
 * @param cb - Callback receiving (err, remoteFilePath)
 */
uploadFile(filepath: string, cb?: callback): string;

// Upload file through input element
browser.elementByCss('input[type="file"]', function(err, fileInput) {
  browser.uploadFile('/path/to/local/file.pdf', function(err, remotePath) {
    if (err) throw err;
    console.log('File uploaded to:', remotePath);
    
    // Set the file path to the input
    browser.type(fileInput, remotePath);
  });
});

// Promise chain file upload
browser
  .uploadFile('./test-files/document.pdf')
  .then(remotePath => {
    return browser.elementByCss('input[type="file"]');
  })
  .then(fileInput => {
    return browser.type(fileInput, remotePath);
  })
  .elementById('upload-button')
  .click();

// Complex form filling
browser
  .elementById('first-name')
  .clear()
  .type('John')
  .keys(wd.SPECIAL_KEYS.Tab)      // Move to next field
  .type('Doe')                     // Type into last name
  .keys(wd.SPECIAL_KEYS.Tab)      // Move to email field
  .type('john.doe@example.com')
  .elementById('country-select')   // Click dropdown
  .click()
  .keys(['U', 'n', 'i'])          // Type to filter options
  .keys(wd.SPECIAL_KEYS.Enter)    // Select option
  .elementById('submit-form')
  .click();

// Drag and drop simulation
browser
  .elementByCss('.draggable-item')
  .moveTo()
  .buttonDown(0)                   // Start drag
  .elementByCss('.drop-zone')
  .moveTo()
  .buttonUp(0);                    // End drag

// Multi-selection with Ctrl key
browser
  .elementByCss('.item-1')
  .click()
  .keys(wd.SPECIAL_KEYS.Control)   // Hold Ctrl
  .elementByCss('.item-3')
  .click()                         // Ctrl+click for multi-select
  .elementByCss('.item-5')
  .click();                        // Another Ctrl+click