prosthetic-hand 1.4.0 → 2.0.0

package/README.md

@@ -1,48 +1,43 @@
 
-# 🖑 prosthetic-hand 🖑
+# 🖐️ prosthetic-hand 🖐️
 
-A javascript library to emulate mouse/touch/pointer events, designed to help
-unit-test touch gestures.
+A JavaScript library to emulate mouse/touch/pointer events, designed to help unit-test touch gestures.
 
+## Installation
 
-## Demos
+```bash
+npm install prosthetic-hand
+```
 
-http://leaflet.github.io/prosthetic-hand/demos/
+## Usage
 
-## API documentation
+```js
+import Hand from 'prosthetic-hand';
 
-http://leaflet.github.io/prosthetic-hand/api-docs.html
+const hand = new Hand();
+const finger = h.growFinger('pointer', { pointerType: 'touch', pressure: 0.9 });
 
+finger
+  .wait(500)
+  .moveTo(200, 250, 0)
+  .down()
+  .moveBy(100, 150, 2000)
+  .up();
+```
 
+For more information see the [API documentation](http://leaflet.github.io/prosthetic-hand/api-docs.html) and [demos](http://leaflet.github.io/prosthetic-hand/demos/).
 
-## Install
+## Testing
 
-Run `npm install prosthetic-hand`.
+Run `npm install` and `npm start`, then open the URL printed in the console in your preferred browser.
 
-Files will be in `node_modules/prosthetic-hand/dist/`
+## Building the documentation
 
-## Build & test
-
-Run `npm install`, then `npm start`, then point your favourite web browser at
-`http://localhost:4567/demos/`
-
-## Compatibility note
-
-Please note that in order to emulate `TouchEvent`s or `PointerEvent`s, your
-web browser must support (or polyfill) these events. Short version: use
-Chrome when running code that emulates `TouchEvents`, and IE11 or Edge when
-emulating `PointerEvent`s.
+Run `npm run build-docs` and open the `api-docs.html` file generated by it.
 
 ## Contributing code
 
-Read the Leaflet guidelines at https://github.com/Leaflet/Leaflet/blob/master/CONTRIBUTING.md
-
-Whenever making a bugfix or a new feature, notify [IvanSanchez](https://github.com/IvanSanchez) so that a new version can be published to NPM.
-
-## Similar projects
-
-* https://github.com/francejs/effroi (three years old)
-* The simulator from http://hammerjs.github.io/ (too basic)
+Read the [Leaflet guidelines](https://github.com/Leaflet/Leaflet/blob/main/CONTRIBUTING.md). Whenever making a bugfix or a new feature, notify [IvanSanchez](https://github.com/IvanSanchez) so that a new version can be published to NPM.
 
 ## Legalese
 

package/lib/Capabilities.js

@@ -0,0 +1,33 @@
+
+// Detects some browser capabilities. Only for internal use, not exposed to the
+// API user.
+
+// touchConstructor, for Touch
+export var touchConstructor = true;
+
+try {
+	var foo = new Touch({ identifier: 0, target: document });
+} catch(e) {
+	touchConstructor = false;
+}
+
+
+// touchEventConstructor, for TouchEvent
+// Weirdly, Safari on iOS has Touch constructor but no TouchEvent constructor.
+export var touchEventConstructor = true;
+
+try {
+	var foo = new TouchEvent('touchdown')
+} catch(e) {
+	touchEventConstructor = false;
+}
+
+// touch: `true` if the browser implements `TouchEvent`
+export var touch = !!('TouchEvent' in window);
+
+// Some bits borrowed from Leaflet's L.Browser
+const ua = navigator.userAgent.toLowerCase();
+const webkit        = ua.includes('webkit');
+const chrome =        ua.includes('chrome');
+export const gecko  = ua.includes('gecko') && !webkit;
+export const safari = !chrome && ua.includes('safari');

package/{src → lib}/Finger.js

@@ -8,12 +8,12 @@ import * as capabilities from './Capabilities.js';
 //   ID whenever they go down.
 var fingerIdSequence = 1;
 
-// 🖑class Finger
+// 🖐️class Finger
 // Represents a finger, capable of performing single touch/pointer/mouse synthetic
 // events.
 
 /*
-🖑example
+🖐️example
 
 ```js
 var h = new Hand();
@@ -26,7 +26,7 @@ fatFinger.wait(500).moveTo(200, 250, 0).down().moveBy(100, 150, 2000).up();
 */
 export default class Finger {
 
-	// 🖑factory Finger(eventMode: String, options?: Finger state): Finger
+	// 🖐️factory Finger(eventMode: String, options?: Finger state): Finger
 	// Instantiates a new `Finger`. `eventMode` must be `mouse`, `touch` or `pointer`
 	// for `MouseEvent`s, `TouchEvent`s or `PointerEvent`s, respectively.
 	constructor(eventMode, options) {
@@ -40,36 +40,36 @@ export default class Finger {
 		/// TODO: parkinsonFactor or shakesFactor or jitteryness or something
 
 
-		// 🖑section Finger state
+		// 🖐️section Finger state
 		// The internal state of a `Finger` has options which will be reflected as
 		// properties of the events fired afterwards. Some of these state options
 		// apply only to a specific event mode.
 		this._state = Object.assign({}, {
-			// 🖑option x: Number; The number of pixels from the left boundary the finger is at.
+			// 🖐️option x: Number; The number of pixels from the left boundary the finger is at.
 			x: 0,
 
-			// 🖑option y: Number; The number of pixels from the top boundary the finger is at.
+			// 🖐️option y: Number; The number of pixels from the top boundary the finger is at.
 			y: 0,
 
-			// 🖑option down: Boolean; Whether the finger is down (clicking/touching/pressing) or not. This is referred to as "active" in some of the events specifications.
+			// 🖐️option down: Boolean; Whether the finger is down (clicking/touching/pressing) or not. This is referred to as "active" in some of the events specifications.
 			down: false,
 
-			// 🖑option pressure: Number = 0.5; The value for [`Touch.force`](`https://developer.mozilla.org/docs/Web/API/Touch/force`) or [`PointerEvent.pressure`](https://developer.mozilla.org/docs/Web/API/PointerEvent/pressure), between `0.0` and `1.0`
+			// 🖐️option pressure: Number = 0.5; The value for [`Touch.force`](`https://developer.mozilla.org/docs/Web/API/Touch/force`) or [`PointerEvent.pressure`](https://developer.mozilla.org/docs/Web/API/PointerEvent/pressure), between `0.0` and `1.0`
 			pressure: 0.5,
 
-			// 🖑option tiltX: Number = 0; The value for [`PointerEvent.tiltX`](https://developer.mozilla.org/docs/Web/API/PointerEvent/tiltX)
+			// 🖐️option tiltX: Number = 0; The value for [`PointerEvent.tiltX`](https://developer.mozilla.org/docs/Web/API/PointerEvent/tiltX)
 			tiltX: 0,
 
-			// 🖑option tiltY: Number = 0; The value for [`PointerEvent.tiltX`](https://developer.mozilla.org/docs/Web/API/PointerEvent/tiltY)
+			// 🖐️option tiltY: Number = 0; The value for [`PointerEvent.tiltX`](https://developer.mozilla.org/docs/Web/API/PointerEvent/tiltY)
 			tiltY: 0,
 
-			// 🖑option width: Number = 25; The value for [`Touch.radiusX`](`https://developer.mozilla.org/docs/Web/API/Touch/radiusX`) or [`PointerEvent.width`](https://developer.mozilla.org/docs/Web/API/PointerEvent/width)
+			// 🖐️option width: Number = 25; The value for [`Touch.radiusX`](`https://developer.mozilla.org/docs/Web/API/Touch/radiusX`) or [`PointerEvent.width`](https://developer.mozilla.org/docs/Web/API/PointerEvent/width)
 			width: 25,
 
-			// 🖑option radiusY: Number = 25; The value for [`Touch.radiusY`](`https://developer.mozilla.org/docs/Web/API/Touch/radiusY`) or [`PointerEvent.height`](https://developer.mozilla.org/docs/Web/API/PointerEvent/height)
+			// 🖐️option radiusY: Number = 25; The value for [`Touch.radiusY`](`https://developer.mozilla.org/docs/Web/API/Touch/radiusY`) or [`PointerEvent.height`](https://developer.mozilla.org/docs/Web/API/PointerEvent/height)
 			height: 25,
 
-			// 🖑option pointerType: String = 'pen'; The value for [`PointerEvent.pointerType`](https://developer.mozilla.org/docs/Web/API/PointerEvent/pointerType)
+			// 🖐️option pointerType: String = 'pen'; The value for [`PointerEvent.pointerType`](https://developer.mozilla.org/docs/Web/API/PointerEvent/pointerType)
 			pointerType: 'pen'
 		}, options);
 
@@ -111,15 +111,9 @@ export default class Finger {
 			} else {
 				this._initGraphicCircle();
 			}
-			if (!capabilities.pointer) {
-				console.warn('This browser cannot emulate pointer events.');
-			}
 		} else {
 			this._mode = 'mouse';
 			this._initGraphicCircle();
-			if (!capabilities.mouse) {
-				console.warn('This browser cannot emulate mouse events.');
-			}
 		}
 
 
@@ -135,28 +129,28 @@ export default class Finger {
 	}
 
 
-	// 🖑method isIdle(): Boolean
+	// 🖐️method isIdle(): Boolean
 	// Returns true when the finger has no more pending movements/waits/wiggles/etc.
 	isIdle() {
 		return !(this._movements.length);
 	}
 
 
-	// 🖑method down(delay?: Number): this
+	// 🖐️method down(delay?: Number): this
 	// Puts the finger down, optionally after a delay.
 	down(delay) {
 		return this.update({ down: true, getState: this._falseFn, duration: delay || 0 });
 	}
 
 
-	// 🖑method up(options?: {}): this
+	// 🖐️method up(options?: {}): this
 	// Lifts the finger up, after an optional delay.
 	up(delay) {
 		return this.update({ down: false, getState: this._falseFn, duration: delay || 0 });
 	}
 
 
-	// 🖑method wait(delay): this
+	// 🖐️method wait(delay): this
 	// Don't move this finger for `delay` milliseconds.
 	wait(delay) {
 		this._queueMove({finalState: this._finalState, getState: this._falseFn, duration: delay});
@@ -164,7 +158,7 @@ export default class Finger {
 	}
 
 
-	// 🖑method waitUntil(timestamp): this
+	// 🖐️method waitUntil(timestamp): this
 	// Don't move this finger until the given timestamp is reached.
 	waitUntil(timestamp) {
 		if (this._movements.length) {
@@ -185,7 +179,7 @@ export default class Finger {
 	}
 
 
-	// 🖑method update(options?: {}): this
+	// 🖐️method update(options?: {}): this
 	// Updates some of the finger options, like pressure or touch angle,
 	// without disturbing its movement, after an optional delay.
 	update(options, delay) {
@@ -194,7 +188,7 @@ export default class Finger {
 	}
 
 
-	// 🖑method reset(options?: {}): this
+	// 🖐️method reset(options?: {}): this
 	// Clears all the queued movements for this finger and immediately lifts it up
 	reset(options) {
 		return this;
@@ -202,7 +196,7 @@ export default class Finger {
 
 
 
-	// 🖑method moveTo(x: Number, y: Number, delay: Number, options?: {}): this
+	// 🖐️method moveTo(x: Number, y: Number, delay: Number, options?: {}): this
 	// Queues moving this finger to an absolute position at `(x, y)`; the
 	// movement will last for `delay` milliseconds.
 	moveTo(x, y, delay) {
@@ -210,7 +204,7 @@ export default class Finger {
 	}
 
 
-	// 🖑method moveBy(x: Number, y: Number, delay: Number, options?: {}): this
+	// 🖐️method moveBy(x: Number, y: Number, delay: Number, options?: {}): this
 	// Queues a move of this finger to an position relative to its last position
 	// plus`(x, y)`; the movement will last for `delay` milliseconds.
 	moveBy(x, y, delay) {
@@ -270,7 +264,7 @@ export default class Finger {
 
 
 	// Returns the timestamp when the next movement will be finished
-	// 🖑method getNextMoveEndTime(): Number|undefined
+	// 🖐️method getNextMoveEndTime(): Number|undefined
 	getNextMoveEndTime() {
 		if (!this._movements.length) {
 			return undefined;
@@ -280,7 +274,7 @@ export default class Finger {
 
 
 	/*
-	 * 🖑method getEvents(timestamp?: Number, justOne: Boolean): []
+	 * 🖐️method getEvents(timestamp?: Number, justOne: Boolean): []
 	 * Updates the private properties of the finger (x, y, timestamp) by
 	 * running the next movement(s) as far as indicated by the timestamp (or
 	 * as fas as to `performance.now()`), then checks if the state has changed
@@ -403,7 +397,7 @@ export default class Finger {
 
 
 
-	// 🖑method private_asTouch(): Touch
+	// 🖐️method private_asTouch(): Touch
 	// Returns an instance of `Touch` representing the current state of the finger
 	// Note this is not an event - a `TouchEvent` must be created later, with several
 	// `Touch`es.
@@ -426,23 +420,7 @@ export default class Finger {
 			});
 		} else {
 
-			if (capabilities.chrome) {
-				touch = document.createTouch(
-					window,	// view
-					this._touchTargetWhenDowned,	// target
-					this._id,	// identifier
-					this._state.x,	// clientX
-					this._state.y,	// clientY
-					this._state.x,	// screenX
-					this._state.y,	// screenY
-
-					// Inconsistency: These break anything other than chrome:
-					25,	// radiusX
-					25,	// radiusY
-					0,	// rotationAngle
-					this._state.pressure	// force
-				);
-			} else if (capabilities.gecko) {
+			if (capabilities.gecko) {
 				touch = document.createTouch(
 					window,	// view
 					this._touchTargetWhenDowned,	// target
@@ -472,108 +450,48 @@ export default class Finger {
 		return touch;
 	}
 
-	// 🖑method private_asPointerEvent(): PointerEvent
+	// 🖐️method private_asPointerEvent(): PointerEvent
 	// Returns an instance of `PointerEvent` representing the current state of the finger
 	_asPointerEvent(evType) {
-		var ev;
-		if (capabilities.pointerEventConstructor) {
-			ev = new PointerEvent('pointer' + evType, {
-				bubbles: true,
-				button: 0,	// Moz doesn't use -1 when no buttons are pressed, WTF?
-// 				buttons: this._state.down ? 1 : 0,
-//	 			detail: (evType === 'down' || evType === 'up') ? 1 : 0,	// TODO: count consecutive clicks
-				clientX: this._state.x,
-				clientY: this._state.y,
-				screenX: this._state.x,	/// TODO: Handle page scrolling
-				screenY: this._state.y,
-				pageX: this._state.x,
-				pageY: this._state.y,
-				pointerType: 'pen',
-				pointerId: this._id,
-				isPrimary: this._id === 1,
-				width: this._state.width,
-				height: this._state.height,
-				tiltX: this._state.tiltX,
-				tiltY: this._state.tiltY,
-				pressure: this._state.pressure
-// 				target: document.elementFromPoint(this._state.x, this._state.y),	// works with viewport coords
-			});
-		} else {
-			ev = document.createEvent('MSPointerEvent');
-			// https://docs.microsoft.com/en-us/previous-versions/windows/internet-explorer/ie-developer/platform-apis/jj192039(v=vs.85)
-			ev.initPointerEvent(
-				'pointer' + evType,    // Type
-				true,                  // canBubble
-				true,                  // cancelable
-				window,                // view
-				0,                     // detail
-				this._state.x,         // screenX
-				this._state.y,         // screenY
-				this._state.x,         // clientX
-				this._state.y,         // clientY
-				false,                 // ctrlKey
-				false,                 // altKey
-				false,                 // shiftKey
-				false,                 // metaKey
-				0,                     // button
-				null,                  // relatedTarget,
-				0,                     // offsetX?
-				0,                     // offsetY?
-				this._state.width,     // width
-				this._state.height,    // height
-				this._state.pressure,  // pressure
-				0,                     // rotation?
-				this._state.tiltX,     // tiltX
-				this._state.tiltY,     // tiltY
-				this._id,              // pointerId
-				'pen',                 // pointerType
-				0,                     // hwTimestamp?
-				this._id === 1         // isPrimary
-			);
-		}
-		return ev;
+		return new PointerEvent('pointer' + evType, {
+			bubbles: true,
+			button: 0,	// Moz doesn't use -1 when no buttons are pressed, WTF?
+// 			buttons: this._state.down ? 1 : 0,
+//	 		detail: (evType === 'down' || evType === 'up') ? 1 : 0,	// TODO: count consecutive clicks
+			clientX: this._state.x,
+			clientY: this._state.y,
+			screenX: this._state.x,	/// TODO: Handle page scrolling
+			screenY: this._state.y,
+			pageX: this._state.x,
+			pageY: this._state.y,
+			pointerType: this._state.pointerType,
+			pointerId: this._id,
+			isPrimary: this._id === 1,
+			width: this._state.width,
+			height: this._state.height,
+			tiltX: this._state.tiltX,
+			tiltY: this._state.tiltY,
+			pressure: this._state.pressure
+// 			target: document.elementFromPoint(this._state.x, this._state.y),	// works with viewport coords
+		});
 	}
 
-	// 🖑method private_asMouseEvent(evType: String): PointerEvent
+	// 🖐️method private_asMouseEvent(evType: String): PointerEvent
 	// Returns an instance of `PointerEvent` representing the current state of the finger
 	_asMouseEvent(evType) {
-		var ev;
-		if (capabilities.mouseEventConstructor) {
-			ev = new MouseEvent('mouse' + evType, {
-				bubbles: true,
-				button:  0,	// Moz doesn't use -1 when no buttons are pressed, WTF?
-				buttons: this._state.down ? 1 : 0,
-				detail:  (evType === 'down' || evType === 'up') ? 1 : 0,	// TODO: count consecutive clicks
-				clientX: this._state.x,
-				clientY: this._state.y,
-				screenX: this._state.x,	/// TODO: Handle page scrolling
-				screenY: this._state.y,
-				pageX:   this._state.x,
-				pageY:   this._state.y,
-	// 			target: document.elementFromPoint(this._state.x, this._state.y),	// works with viewport coords
-			});
-		} else {
-			// For legacy browsers and PhantomJS
-			ev = document.createEvent('MouseEvent');
-			ev.initMouseEvent(
-				'mouse' + evType,	// Type
-				true,	// canBubble
-				true,	// cancellable
-				window,	// view
-				0,	// detail
-				this._state.x,	// screenX
-				this._state.y,	// screenY
-				this._state.x,	// clientX
-				this._state.y,	// clientY
-				false,	// ctrlKey
-				false,	// altKey
-				false,	// shiftKey
-				false,	// metaKey
-				0,	// button
-				null	// relatedTarget
-			);
-		}
-		return ev;
+		return new MouseEvent('mouse' + evType, {
+			bubbles: true,
+			button:  0,	// Moz doesn't use -1 when no buttons are pressed, WTF?
+			buttons: this._state.down ? 1 : 0,
+			detail:  (evType === 'down' || evType === 'up') ? 1 : 0,	// TODO: count consecutive clicks
+			clientX: this._state.x,
+			clientY: this._state.y,
+			screenX: this._state.x,	/// TODO: Handle page scrolling
+			screenY: this._state.y,
+			pageX:   this._state.x,
+			pageY:   this._state.y,
+// 			target: document.elementFromPoint(this._state.x, this._state.y),	// works with viewport coords
+		});
 	}