westures-core 1.2.1 → 1.3.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## Unreleased
+
+## 1.3.1
+
+- Add 'contextmenu' to CANCEL_EVENTS
+- Changed docs deployment strategy
+
+## 1.3.0
+
+- Introduce "headless" mode, which allows westures to be run in a server environment.
+
+## 1.2.0
+
+- Switch to "parcel" from "parcel-bundler"
+- Add a list of the PHASES to constants.js
+- Provide Input.elapsedTime
+- Provide Point2D.anglesTo()
+
 ## 1.1.0
 
 - Switch to using pointer events by default, combined with setting touch-action:

package/CONTRIBUTING.md

@@ -0,0 +1,121 @@
+# Contributing to westures-core
+
+Thanks for contributing to westures-core. Contributions to the gesture engine,
+tests, documentation, and examples are welcome.
+
+## Development Setup
+
+This project uses npm and is [tested in CI](./.github/workflows/node.js.yml) across a matrix of recent Node versions.
+
+Install dependencies with:
+
+```sh
+npm clean-install --ignore-scripts
+```
+
+## Common commands
+
+Run the same checks used by CI before opening a pull request:
+
+```bash
+npm run build
+npm run lint
+npm test
+npm run test:coverage
+```
+
+Additional useful commands:
+
+```bash
+npm run build:debug
+npm run lint:fix
+```
+
+## Development Workflow
+
+- Keep changes focused and update tests when behavior changes.
+- Update `CHANGELOG.md` for notable user-facing, maintenance, or security changes.
+- Open a pull request using the repository's pull request template.
+
+The source is in `src/`, tests are in `test/`, and `index.js` is the package
+entry point. The `dist/` directory contains build output; regenerate it with
+`npm run build` rather than editing it directly.
+
+Follow the existing JavaScript style. ESLint enforces the project conventions,
+including two-space indentation, single quotes, semicolons, and trailing commas
+in multiline constructs.
+
+## Pull Requests
+
+Before opening a pull request, run the build, linter, and relevant tests. Give
+the pull request a clear description, explain any behavioral changes, and use
+the provided pull request template to identify its type. Keep unrelated
+formatting or refactoring changes out of the pull request.
+
+For bugs, include a regression test when practical. For user-facing API or
+behavior changes, update the README and JSDoc documentation as appropriate.
+
+## Publishing Documentation
+
+Published documentation is generated with `npm run docs` and deployed from the
+generated `docs/` directory by the
+[documentation deployment workflow](./.github/workflows/deploy-documentation.yaml).
+
+To publish the current `deploy-docs` branch, push your changes to that branch.
+For a one-off deployment from another branch, run the **Build and Deploy**
+workflow manually in GitHub Actions and select the branch to deploy. The
+workflow installs dependencies, regenerates the documentation, and publishes
+the resulting `docs/` directory, so do not commit generated documentation just
+to deploy it.
+
+## Reporting Issues
+
+When reporting a bug, include the Node.js version, browser and version when
+relevant, a minimal reproduction, expected behavior, and actual behavior.
+
+## License
+
+By contributing, you agree that your contributions are licensed under the
+[MIT License](LICENSE).
+
+## Release process
+
+For a package release, use the following workflow so you publish from the same
+source commit you tag (with build artifacts generated locally), while only
+pushing the tag after `npm publish` succeeds.
+
+1. Create a release preparation branch from `main`.
+2. Update `package.json`, `package-lock.json`, and `CHANGELOG.md` for the new version.
+3. Commit the release preparation changes and open a pull request.
+4. Merge the pull request into `main`.
+5. Check out the merged `main` commit locally.
+6. Verify the working tree is clean.
+7. Create the release tag locally for that commit, but do not push it yet.
+8. Check what will be published with `npm pack --dry-run`.
+9. Sanity-check the built bundle in `dist/index.js`.
+10. Publish the package to npm from the tagged commit.
+11. Push the tag.
+12. Create the GitHub release from the pushed tag.
+
+Example commands for `1.3.1`:
+
+```bash
+git switch --create release/1.3.1
+git add package.json package-lock.json CHANGELOG.md
+git commit --message "Prepare for 1.3.1 release"
+gh pr create
+# merge the PR, then sync your local main to the merged commit
+git switch main
+git pull --ff-only origin main
+git status --short  # must produce no output
+git tag --annotate v1.3.1 --message "Release 1.3.1"
+npm pack --dry-run  # also builds, via 'prepare' script
+ls -lh dist/index.js
+npm publish
+git push origin v1.3.1
+gh release create v1.3.1 --title "v1.3.1"
+```
+
+If you want GitHub release notes to match the changelog closely, paste the
+`1.3.1` section of `CHANGELOG.md` into the release notes when creating the
+release.

package/README.md

@@ -1,20 +1,12 @@
 # westures-core
 
-[![Build Status](
-https://travis-ci.org/mvanderkamp/westures-core.svg?branch=master)
-](https://travis-ci.org/mvanderkamp/westures-core)
-[![Coverage Status](
-https://coveralls.io/repos/github/mvanderkamp/westures-core/badge.svg?branch=master)
-](https://coveralls.io/github/mvanderkamp/westures-core?branch=master)
-[![Maintainability](
-https://api.codeclimate.com/v1/badges/a5f4a4745352d6e2520c/maintainability)
-](https://codeclimate.com/github/mvanderkamp/westures-core/maintainability)
-
-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.
+[![Node.js CI](https://github.com/mvanderkamp/westures-core/actions/workflows/node.js.yml/badge.svg)](https://github.com/mvanderkamp/westures-core/actions/workflows/node.js.yml)
+[![Coverage Status](https://coveralls.io/repos/github/mvanderkamp/westures-core/badge.svg?branch=main)](https://coveralls.io/github/mvanderkamp/westures-core?branch=main)
+[![Maintainability](https://api.codeclimate.com/v1/badges/a5f4a4745352d6e2520c/maintainability)](https://codeclimate.com/github/mvanderkamp/westures-core/maintainability)
+
+Westures is an n-pointer gesture detection library for JavaScript. Gestures can
+continue as input points are added and removed, with each active input point
+available to the gesture.
 
 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
@@ -24,13 +16,10 @@ 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/).
 
-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 has no runtime dependencies. It uses Pointer Events when available and
+otherwise listens to mouse and touch events. The package's CommonJS entry point
+is a bundled build; applications that target older browsers may need to
+transpile it as part of their own build pipeline.
 
 Westures is a fork of [ZingTouch](https://github.com/zingchart/zingtouch).
 
@@ -46,6 +35,10 @@ const region = new wes.Region();
 
 // Define a Gesture subclass
 class Follow extends wes.Gesture {
+  constructor(element, handler, options) {
+    super('follow', element, handler, options);
+  }
+
   move(state) {
     return state.centroid; // Reports the {x, y} of the average input position
   }
@@ -68,11 +61,13 @@ region.addGesture(follow);
 
 - [Features](#features)
 - [Overview](#overview)
+- [Installation](#installation)
 - [Basic Usage](#basic-usage)
 - [Implementing Custom Gestures](#implementing-custom-gestures)
 - [Nomenclature and Origins](#nomenclature-and-origins)
 - [Changes](#changes)
 - [Issues](#issues)
+- [Contributing](#contributing)
 - [Links](#links)
 
 ## Features
@@ -104,17 +99,26 @@ 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:
+The package also exports its constants and utility functions, including
+`PHASES`, `STATE_KEYS`, `angularDifference`, and `setFilter`.
 
-Name      | Description
---------- | -----------
-constants | Constant values used throughout the engine
-utils     | Helpful utility functions
+## Installation
 
-Here is a graph to help you understand the relationships between these classes:
+```sh
+npm install westures-core
+```
 
-![Graph of westures-core module](
-https://raw.githubusercontent.com/mvanderkamp/westures-core/master/arkit.svg?sanitize=true)
+The package uses CommonJS:
+
+```javascript
+const wes = require('westures-core');
+```
+
+`Region` requires a browser environment by default. For server-side or test
+use, create it in headless mode and provide events directly to
+`arbitrate(event)`, `cancel(event)`, and `handleKeyboardEvent(event)`. Events
+passed to a headless region must include a `target` so the region can select
+the gesture to evaluate.
 
 ## Basic Usage
 
@@ -123,12 +127,6 @@ https://raw.githubusercontent.com/mvanderkamp/westures-core/master/arkit.svg?san
 - [Instantiating a Gesture](#instantiating-a-gesture)
 - [Adding a Gesture to a Region](#adding-a-gesture-to-a-region)
 
-### Importing the module
-
-```javascript
-const wes = require('westures-core');
-```
-
 ### Declaring a Region
 
 First, decide what region should listen for events. This could be the
@@ -161,6 +159,10 @@ input points. Note that the returned value must be an Object!
 ```javascript
 // Define a Gesture subclass
 class Follow extends wes.Gesture {
+  constructor(element, handler, options) {
+    super('follow', element, handler, options);
+  }
+
   move(state) {
     return state.centroid;
   }
@@ -184,7 +186,7 @@ const element = document.querySelector('#follow');
 ```
 
 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
+returns an object. 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.
 
@@ -238,18 +240,19 @@ const { Gesture } = require('westures-core');
 const TIMEOUT = 100;
 
 class Tap extends Gesture {
-  constructor() {
-    super('tap');
+  constructor(element, handler, options) {
+    super('tap', element, handler, options);
     this.startTime = null;
   }
 
-  start(state) {
+  start() {
     this.startTime = Date.now();
   }
 
   end(state) {
     if (Date.now() - this.startTime <= TIMEOUT) {
-        return state.getInputsInPhase('end')[0].current.point;
+      const point = state.getInputsInPhase('end')[0].current.point;
+      return { centroid: point, ...point };
     }
     return null;
   }
@@ -260,7 +263,7 @@ There are problems with this example, and it should probably not be used as an
 actual Tap gesture, it is merely to illustrate the basic idea.
 
 The default hooks for all Gestures simply return null. Data will only be
-forwarded to bound handlers when a non-null value is returned by a hook.
+forwarded to bound handlers when an object 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 };`
 
@@ -280,7 +283,7 @@ called. Those properties are:
 
 Name     | Type     | Value
 -------- | -------- | -----
-centroid | Point2D  | The centroid of the input points.
+centroid | Point2D \| null | The centroid of the active 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.
@@ -290,9 +293,21 @@ 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.
 
+### Ending Inputs
+
+`State.active`, `State.activePoints`, and the default `centroid` represent only
+active inputs. During an `end` hook, this means that inputs ending in the
+current event are excluded; when the final input ends, the default `centroid`
+is `null`.
+
+Gestures based on released inputs should read them with
+`state.getInputsInPhase('end')`, retain any data they need, and return their
+own result. A tap gesture, for example, can compute its own centroid from the
+ending inputs and return it as `centroid`, as in the example above.
+
 ## Nomenclature and Origins
 
-In my last year of univerisity, I was working on an API for building
+In my last year of university, 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.
 
@@ -307,13 +322,18 @@ The name "westures" is a mash-up of "WAMS" and "gestures".
 ## Changes
 
 See the [changelog](
-https://github.com/mvanderkamp/westures-core/blob/master/CHANGELOG.md) for the
+https://github.com/mvanderkamp/westures-core/blob/main/CHANGELOG.md) for the
 most recent updates.
 
 ## Issues
 
 If you find any issues, please let me know!
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow and pull
+request guidelines.
+
 ## Links
 
 ### westures
@@ -327,4 +347,3 @@ If you find any issues, please let me know!
 - [npm](https://www.npmjs.com/package/westures-core)
 - [github](https://github.com/mvanderkamp/westures-core)
 - [documentation](https://mvanderkamp.github.io/westures-core/)
-