westures-core 1.0.0 → 1.2.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.1.0
+
+- Switch to using pointer events by default, combined with setting touch-action:
+  none on the gesture elements (not the region itself).
+- Provide options on the Region for choosing whether to prefer pointer events
+  over mouse/touch events (preferPointer) and what to set the touch-action
+  property to on gesture elements (touchAction).
+- Default to using the window as the region if no element provided.
+- Add mouseleave to the CANCEL_EVENTS
+
 ## 1.0.0
 
 - Official first release! This engine is no longer considered to be in beta.

package/README.md

@@ -10,14 +10,27 @@ https://coveralls.io/repos/github/mvanderkamp/westures-core/badge.svg?branch=mas
 https://api.codeclimate.com/v1/badges/a5f4a4745352d6e2520c/maintainability)
 ](https://codeclimate.com/github/mvanderkamp/westures-core/maintainability)
 
-This module contains the core functionality of the Westures JavaScript gesture
-library. It is intended for use as a lighter-weight module to use if you do not
-intend on using the base gestures included with the standard [westures](
+Westures is a robust n-pointer multitouch gesture detection library for
+JavaScript. This means that each gesture is be capable of working seamlessly as
+input points are added and removed, with no limit on the number of input points,
+and with each input point contributing to the gesture.  It is also capable of
+working across a wide range of devices.
+
+This module contains the core functionality of the Westures gesture library for
+JavaScript. It is intended for use as a lighter-weight module to use if you do
+not want to use the base gestures included with the standard [westures](
 https://mvanderkamp.github.io/westures/) module.
 
 Visit this page for an example of the system in action: [Westures Example](
-https://mvanderkamp.github.io/westures-example/). Note that this is best viewed
-on a touch device.
+https://mvanderkamp.github.io/westures-example/).
+
+Westures aims to achieve its goals without using any dependencies, yet maintain
+usability across the main modern browsers. Transpilation may be necessary for
+this last point to be achieved, as the library is written using many of the
+newer features of the JavaScript language. A transpiled bundle is provided, but
+the browser target list is arbitrary and likely includes some bloat. In most
+cases you will be better off performing bundling, transpilation, and
+minification yourself.
 
 Westures is a fork of [ZingTouch](https://github.com/zingchart/zingtouch).
 
@@ -25,22 +38,30 @@ Westures is a fork of [ZingTouch](https://github.com/zingchart/zingtouch).
 
 ```javascript
 // Import the module.
-const { Region } = require('westures-core');
+const wes = require('westures-core');
+
+// Declare a region. The default is the window object, but other elements like
+// the document body work too.
+const region = new wes.Region();
 
-// Declare a region. The document body is probably a good one to use.
-const region = new Region(document.body);
+// Define a Gesture subclass
+class Follow extends wes.Gesture {
+  move(state) {
+    return state.centroid; // Reports the {x, y} of the average input position
+  }
+}
+
+// Locate an element to attach the gesture to.
+const element = document.querySelector('#follow');
 
 // Instantiate a Gesture for an element within the region.
-// Assumes a Pan gesture is available, and that the element you want to pan has
-// been saved in the `element` variable.
-const pan = new Pan(element, (data) => {
-  // data.translation.x ...
-  // data.translation.y ...
-  // and so on, depending on the Gesture
+const follow = new Follow(element, (data) => {
+  // data.x ...
+  // data.y ...
 });
 
 // Add the gesture to the region.
-region.addGesture(pan);
+region.addGesture(follow);
 ```
 
 ## Table of Contents
@@ -49,6 +70,9 @@ region.addGesture(pan);
 - [Overview](#overview)
 - [Basic Usage](#basic-usage)
 - [Implementing Custom Gestures](#implementing-custom-gestures)
+- [Nomenclature and Origins](#nomenclature-and-origins)
+- [Changes](#changes)
+- [Issues](#issues)
 - [Links](#links)
 
 ## Features
@@ -68,34 +92,41 @@ region.addGesture(pan);
 
 ## Overview
 
-There are seven classes defined in this module:
+There are seven classes made available by this module:
 
-- _Gesture:_ Respond to input phase "hooks" to define a gesture.
-- _Input:_ Track a single pointer through its lifetime, and store the progress
-    of gestures associated with that input.
-- _Point2D:_ Store and act on a 2-dimensional point.
-- _PointerData:_ Record data pertaining to a single user input event for a
-    single pointer.
-- _Region:_ Listen for user input events and respond appropriately.
-- _Smoothable:_ Datatype which provides inertial smoothing capabilities.
-- _State:_ Track all active Inputs within a Region.
+Name        | Description
+----------- | -----------
+Gesture     | Base class for defining westures gestures
+Input       | Track a single pointer through its lifetime
+Point2D     | Store and act on a 2-dimensional point
+PointerData | Record data pertaining to a single user input event for a single pointer.
+Region      | Listen for user input events and respond appropriately
+Smoothable  | Datatype which provides inertial smoothing capabilities
+State       | Track inputs within a Region
 
 Additionally, two support files are defined:
 
-- _constants:_ Constant values used throughout the engine.
-- _utils:_ Helpful utility functions.
+Name      | Description
+--------- | -----------
+constants | Constant values used throughout the engine
+utils     | Helpful utility functions
 
-These classes are structured as follows:
+Here is a graph to help you understand the relationships between these classes:
 
 ![Graph of westures-core module](
 https://raw.githubusercontent.com/mvanderkamp/westures-core/master/arkit.svg?sanitize=true)
 
 ## Basic Usage
 
+- [Declaring a Region](#declaring-a-region)
+- [Defining a Gesture Subclass](#defining-a-gesture-subclass)
+- [Instantiating a Gesture](#instantiating-a-gesture)
+- [Adding a Gesture to a Region](#adding-a-gesture-to-a-region)
+
 ### Importing the module
 
 ```javascript
-const { Region } = require('westures-core');
+const wes = require('westures-core');
 ```
 
 ### Declaring a Region
@@ -111,9 +142,31 @@ If you have lots of interactable elements on your page, you may find it
 convenient to use smaller elements as regions. Test it out in any case, and see
 what works better for you.
 
+By default, the window object is used.
+
 ```javascript
-const region = new Region(document.body);
+const region = new wes.Region(document.body);
 ```
+
+### Defining a Gesture Subclass
+
+In order to use the engine, you'll need to define gestures. This is done by
+extending the Gesture class provided by this module, and overriding any or all
+of the four phase hooks ('start', 'move', 'end', and 'cancel') as is appropriate
+for your gesture.
+
+Defined here is a very simple gesture that simply reports the centroid of the
+input points. Note that the returned value must be an Object!
+
+```javascript
+// Define a Gesture subclass
+class Follow extends wes.Gesture {
+  move(state) {
+    return state.centroid;
+  }
+}
+```
+
 ### Instantiating a Gesture
 
 When you instantiate a gesture, you need to provide a handler as well as an
@@ -122,38 +175,48 @@ with the region was inside the given Element. Therefore unless you want to try
 something fancy the gesture element should probably be contained inside the
 region element. It could even be the region element.
 
-Now for an example. Suppose you have a div within which you want to detect a Pan
-gesture (assume that such a gesture is available). Your handler is called
-`handler`, and the div is saved in the `element` variable.
+Now for an example. Suppose you have a div within which you want to detect the
+Follow gesture we defined above. The div has id 'follow'. We need to find the
+element first.
 
 ```javascript
-const pan = new Pan(element, handler);
+const element = document.querySelector('#follow');
 ```
 
-The `handler` function will be called whenever a Pan hook returns non-null data.
-The data returned by the hook will be available inside `handler` as such:
+And we also need a handler. This function will be called whenever a gesture hook
+returns non-null data. For Follow, this is just the move phase, but the handler
+doesn't need to know that. The data returned by the hook will be available
+inside the handler.
 
 ```javascript
-function handler(data) {
-  // data.translation.x ...
-  // data.translation.y ...
-  // and so on, depending on the gesture
+function followLogger(data) {
+  console.log(
+    'The centroid of the points interacting with #follow is:',
+    'x:', data.x,
+    'y:', data.y,
+  )
 }
 ```
 
-That said, none of this will actually work until you add the gesture to the
-region.
+Now we're ready to combine the element and its handler into a gesture.
+
+```javascript
+const follow = new Follow(element, followLogger);
+```
+
+We're not quite done though, as none of this will actually work until you add
+the gesture to the region.
 
 ### Adding a Gesture to a Region
 
 Simple:
 
 ```javascript
-region.addGesture(pan);
+region.addGesture(follow);
 ```
 
-Now the `handler` function will be called whenever a `pan` gesture is detected
-on the `#pannable` element inside the region.
+Now the `followLogger` function will be called whenever a `follow` gesture is
+detected on the `#follow` element inside the region.
 
 ## Implementing Custom Gestures
 
@@ -201,8 +264,11 @@ forwarded to bound handlers when a non-null value is returned by a hook.
 Returned values should be packed inside an object. For example, instead of just
 `return 42;`, a custom hook should do `return { value: 42 };`
 
+If your Gesture subclass needs to track any kind of complex state, remember that
+it may be necessary to reset the state in the `cancel` phase.
+
 For information about what data is accessible via the State object, see the full
-documentation [here](https://mvanderkamp.github.io/westures-core/State.html).
+documentation [here](https://mvanderkamp.github.io/westures-core/westures-core.State.html).
 Note that his documentation was generated with `jsdoc`.
 
 ### Default Data Passed to Handlers
@@ -212,16 +278,31 @@ to handlers, and for the most part what that data will be. Note though that a
 few properties will get added to the outgoing data object before the handler is
 called. Those properties are:
 
-Name     | Type    | Value
----------|---------|-------
-centroid | Point2D | The centroid of the input points.
-event    | Event   | The input event which caused the gesture to be recognized
-phase    | String  | `'start'`, `'move'`, `'end'`, or `'cancel'`
-type     | String  | The name of the gesture as specified by its designer.
-target   | Element | The Element that is associated with the recognized gesture.
+Name     | Type     | Value
+-------- | -------- | -----
+centroid | Point2D  | The centroid of the input points.
+event    | Event    | The input event which caused the gesture to be recognized
+phase    | String   | `'start'`, `'move'`, `'end'`, or `'cancel'`
+type     | String   | The name of the gesture as specified by its designer.
+target   | Element  | The Element that is associated with the recognized gesture.
+
+If data properties returned by a hook have a name collision with one of these
+properties, the value from the hook gets precedent and the default is
+overwritten.
+
+## Nomenclature and Origins
+
+In my last year of univerisity, I was working on an API for building
+multi-device interfaces called "WAMS" (Workspaces Across Multiple Surfaces),
+which included the goal of supporting multi-device gestures.
+
+After an extensive search I found that none of the available multitouch
+libraries for JavaScript provided the fidelity I needed, and concluded that I
+would need to write my own, or at least fork an existing one. ZingTouch proved
+to the be the most approachable, so I decided it would make a good starting
+point.
 
-If data properties returned by a hook clashes with one of these properties, the
-value from the hook gets precedent and the default is overwritten.
+The name "westures" is a mash-up of "WAMS" and "gestures".
 
 ## Changes
 
@@ -231,7 +312,7 @@ most recent updates.
 
 ## Issues
 
-If you find any compatibility issues, please let me know!
+If you find any issues, please let me know!
 
 ## Links