feat: element specific destination point (#157)

* feat: element specific destination point

* from top-left

* add box

* style: comment

Author: bvandercar-vt

README.md

@@ -126,7 +126,8 @@ Moves the mouse to the specified selector or element.
 
 - **selector:** CSS selector or ElementHandle to identify the target element.
 - **options (optional):** Additional options for moving. **Extends the `options` of the `scrollIntoView` function (below)**
-  - `paddingPercentage (number):` Percentage of padding to be added inside the element. Default is `0` (may move to anywhere within the element). `100` will always move to center of element.
+  - `paddingPercentage (number):` Percentage of padding to be added inside the element when determining the target point. Default is `0` (may move to anywhere within the element). `100` will always move to center of element.
+  - `destination (Vector):` Destination to move the cursor to, relative to the top-left corner of the element. If specified, `paddingPercentage` is not used. If not specified (default), destination is random point within the `paddingPercentage`.
   - `waitForSelector (number):` Time to wait for the selector to appear in milliseconds. Default is to not wait for selector.
   - `moveDelay (number):` Delay after moving the mouse in milliseconds. Default is `0`. If `randomizeMoveDelay=true`, delay is randomized from 0 to `moveDelay`.
   - `randomizeMoveDelay (boolean):` Randomize delay between actions from `0` to `moveDelay`. Default is `true`.

src/spoof.ts

@@ -9,6 +9,7 @@ import {
   magnitude,
   origin,
   overshoot,
+  add,
   clamp,
   scale
 } from './math'
@@ -25,6 +26,13 @@ export interface BoxOptions {
    * @default 0
    */
   readonly paddingPercentage?: number
+  /**
+   * Destination to move the cursor to, relative to the top-left corner of the element.
+   * If specified, `paddingPercentage` is not used.
+   * If not specified (default), destination is random point within the `paddingPercentage`.
+   * @default undefined (random point)
+   */
+  readonly destination?: Vector
 }
 
 export interface ScrollOptions {
@@ -159,7 +167,7 @@ const fitts = (distance: number, width: number): number => {
 /** Get a random point on a box */
 const getRandomBoxPoint = (
   { x, y, width, height }: BoundingBox,
-  options?: BoxOptions
+  options?: Pick<BoxOptions, 'paddingPercentage'>
 ): Vector => {
   let paddingWidth = 0
   let paddingHeight = 0
@@ -540,7 +548,9 @@ export const createCursor = (
 
         const box = await boundingBoxWithFallback(page, elem)
         const { height, width } = box
-        const destination = getRandomBoxPoint(box, optionsResolved)
+        const destination = (optionsResolved.destination !== undefined)
+          ? add(box, optionsResolved.destination)
+          : getRandomBoxPoint(box, optionsResolved)
         const dimensions = { height, width }
         const overshooting = shouldOvershoot(
           previous,