Pointeract

https://github.com/hesprs/pointeract
Admin
Pointeract is a tiny, modular JavaScript/TypeScript library for handling user interactions with DOM...
Tokens:21,033
Snippets:179
Trust Score:6.9
License:Apache-2.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### pointeract.start()

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/basic/use-pointeract.md

Starts the Pointeract instance or specified modules.

```APIDOC
## [METHOD] pointeract.start()

### Description
Starts the Pointeract instance if no arguments are provided. If module constructors are provided, starts those modules. If the base class is already started, starting modules will resume them if they were stopped at module level.

### Method
start

### Endpoint
`pointeract.start(modules?)`

### Parameters
#### Parameters
- **modules** (Array<ModuleConstructor>) - Optional - An array of module constructors to start. If omitted, starts the base class.

### Request Example
```TypeScript
pointeract.start(); // starts the base class
pointeract.start([Drag]); // starts the Drag module
```

### Response
#### Success Response
- **void** - No return value.

#### Response Example
```TypeScript
pointeract.start();
```
```

--------------------------------

### Full Pointeract usage example

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/basic/use-pointeract.md

Complete usage example for the Pointeract library. It shows how to instantiate with options and plugins, subscribe to the 'drag' event, hot-update options, unsubscribe, pause/resume, disable only the PreventDefault plugin, and dispose the instance.

```TypeScript
import { Pointeract, Drag, PreventDefault, Events } from 'pointeract';

function hook(e: Events['drag']) {
    console.log(e);
};

const app = document.getElementById('app') as HTMLDivElement;
const options = {
    element: app,
    coordinateOutput: 'absolute',
}

// instantiate the class and subscribe
const pointeract = new Pointeract(options, [Drag, PreventDefault])
    .start()
    .on('drag', hook);

// Hot update options
options.coordinateOutput = 'relative';

// Unsubscribe
pointeract.off('drag', hook);

// Pause
pointeract.stop();
// Resume
pointeract.start();

// Disable PreventDefault only
pointeract.stop([PreventDefault]);

// Dispose
pointeract.dispose();
```

--------------------------------

### Install Pointeract with npm, pnpm, yarn, or bun

Source: https://github.com/hesprs/pointeract/blob/main/README.md

Install Pointeract using your preferred package manager. The commands are shown for npm, pnpm, yarn, and bun.

```sh
npm add pointeract
```

```sh
pnpm add pointeract
```

```sh
yarn add pointeract
```

```sh
bun add pointeract
```

--------------------------------

### Smooth Zooming with Lubricator

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/events/zoom.md

This example demonstrates how to enable smooth zooming by integrating the Lubricator module with the zoom event using the lubricatorZoomPreset.

```APIDOC
## Smooth Zooming with Lubricator

### Description
Pointeract supports smoothing zoom events using the Lubricator module. You can use the `lubricatorZoomPreset` or customize your own.

### Usage Example
```TypeScript
import { WheelPanZoom, Lubricator, Pointeract, lubricatorZoomPreset as zoom } from 'pointeract';

new Pointeract({
    element: app,
    lubricator: { zoom },
}, [WheelPanZoom, Lubricator])
```
```

--------------------------------

### Start and Stop Pointeract

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/basic/use-pointeract.md

Starts and stops the Pointeract instance. Pointeract does nothing after initialization until start() is called. stop() returns the instance and does not destroy it.

```TypeScript
pointeract.start();
```

```TypeScript
pointeract.stop();
```

--------------------------------

### Module Start/Stop Independence Example

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/basic/use-pointeract.md

Illustrates that module start/stop is independent of the base class. Stopping the base pauses all modules; starting it resumes only modules not explicitly stopped. A module stopped at module level must be explicitly reenabled.

```TypeScript
// we have modules PreventDefault and Drag
pointeract.stop(); // everything is paused
pointeract.stop([PreventDefault]); // no apparent change, but PreventDefault is disabled at module level
pointeract.start(); // only the base class and Drag are started
pointeract.start([PreventDefault]); // PreventDefault will not be restarted unless explicitly reenabled here
```

--------------------------------

### Instantiate Pointeract with Options and Modules

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/basic/use-pointeract.md

Shows the complete setup for creating a Pointeract instance: importing the class and modules, obtaining a DOM element, defining options, and constructing the instance. The modules argument is optional.

```TypeScript
import { Pointeract } from 'pointeract';
```

```TypeScript
import { Drag, PreventDefault } from 'pointeract';
```

```TypeScript
const app = document.getElementById('app') as HTMLDivElement;
```

```HTML
<div id="app"></div>
```

```TypeScript
const options = {
    element: app,
    coordinateOutput: 'absolute',
}
```

```TypeScript
const pointeract = new Pointeract(options, [Drag, PreventDefault]);
```

--------------------------------

### Initialize Pointeract with Drag module and log drag events

Source: https://github.com/hesprs/pointeract/blob/main/README.md

Create a Pointeract instance with the Drag module, start it, and listen for 'drag' events. The element is provided via the `element` option.

```TypeScript
import { Pointeract, Drag } from 'pointeract';

new Pointeract({ element: yourElement }, [Drag])
    .start()
    .on('drag', e => console.log(e));
```

--------------------------------

### Import and initialize MultitouchPanZoom

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/modules/multitouch-pan-zoom.md

Imports the MultitouchPanZoom module and Pointeract, then creates a new Pointeract instance with the module attached to the app element. This is the required setup to enable multitouch pan and zoom events.

```TypeScript
import { MultitouchPanZoom, Pointeract } from 'pointeract';
const pointeract = new Pointeract({ element: app }, [MultitouchPanZoom]);
```

--------------------------------

### Custom Direction Maps

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/modules/swipe.md

Examples of custom direction maps for diagonal and eight-direction swipe detection.

```APIDOC
## Custom Direction Maps

### Description
Custom direction maps allow detection of diagonal or eight-direction swipes. The module traverses the map in anticlockwise order and finds the first entry whose boundary value is greater than the angle of the swipe. Angles are in radians from π to -π.

### Diagonal Direction Map
```TypeScript
const diagonalDirectionMap = {
	'down-left': -Math.PI / 2, // -90 degrees
	'down-right': 0,           // 0 degrees
	'up-right': Math.PI / 2,   // 90 degrees
	'up-left': Math.PI,        // 180 degrees
};
```

### Eight Direction Map
```TypeScript
const eightDirectionMap = {
	left: -(Math.PI / 8) * 7,        // -157.5 degrees
	'down-left': -(Math.PI / 8) * 5, // -112.5 degrees
	down: -(Math.PI / 8) * 3,        // -67.5 degrees
	'down-right': -Math.PI / 8,      // -25.5 degrees
	right: Math.PI / 8,              // 25.5 degrees
	'up-right': (Math.PI / 8) * 3,   // 67.5 degrees
	up: (Math.PI / 8) * 5,           // 112.5 degrees
	'up-left': (Math.PI / 8) * 7,    // 157.5 degrees
};
```

These maps are included in the package exports.
```

--------------------------------

### Diagonal and eight-direction maps

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/modules/swipe.md

Example maps for detecting diagonal or eight directions, both included in the package exports.

```TypeScript
const diagonalDirectionMap = {
	'down-left': -Math.PI / 2, // -90 degrees
	'down-right': 0,           // 0 degrees
	'up-right': Math.PI / 2,   // 90 degrees
	'up-left': Math.PI,        // 180 degrees
};

const eightDirectionMap = {
	left: -(Math.PI / 8) * 7,        // -157.5 degrees
	'down-left': -(Math.PI / 8) * 5, // -112.5 degrees
	down: -(Math.PI / 8) * 3,        // -67.5 degrees
	'down-right': -Math.PI / 8,      // -25.5 degrees
	right: Math.PI / 8,              // 25.5 degrees
	'up-right': (Math.PI / 8) * 3,   // 67.5 degrees
	up: (Math.PI / 8) * 5,           // 112.5 degrees
	'up-left': (Math.PI / 8) * 7,    // 157.5 degrees
};
```

--------------------------------

### Define options for Pointeract constructor

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/basic/use-pointeract.md

Options are defined as an object and passed as the first argument of a Pointeract constructor. The example defines options with element and coordinateOutput, and passes them along with modules [Drag, PreventDefault].

```TypeScript
const options = {
    element: app,
    coordinateOutput: 'absolute',
}
const pointeract = new Pointeract(options, [Drag, PreventDefault]);
```

--------------------------------

### Update options at runtime

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/basic/use-pointeract.md

Pointeract uses the same options reference passed in the constructor, allowing reactive updates at runtime. The example imports Pointeract, WheelPanZoom, and Options, defines options, creates an instance, and then changes coordinateOutput to 'relative', which instantly changes the output format.

```TypeScript
import { Pointeract, WheelPanZoom, Options } from 'pointeract';

const options: Options<WheelPanZoom> = {
    element: document.body
    coordinateOutput: 'absolute', // output absolute coordinates
}

const pointeract = new Pointeract(options, [WheelPanZoom]);

options.coordinateOutput = 'relative'; // output format instantly changes to relative
```

--------------------------------

### Resume Pointeract After Stopping

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/basic/use-pointeract.md

Shows how to pause and later resume Pointeract. stop() returns the instance and does not destroy it, so you can call start() again.

```TypeScript
pointeract.stop();
// ... some logic here
pointeract.start();
```

--------------------------------

### Subscribe to drag event with on()

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/basic/use-pointeract.md

Use on() to subscribe to events, similar to addEventListener(), but fully typed and returns the pointeract instance for chaining. The example subscribes to the 'drag' event and logs the event object.

```TypeScript
import type { StdEvents } from 'pointeract';

const hook = (e: StdEvents['drag']) => {
    console.log(e);
};
pointeract.on('drag', hook);
```

--------------------------------

### Events export with Click module

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/basic/types.md

Shows how to get the events type for a module using the Events export. For Click, the available events are pan, zoom, drag, and trueClick.

```TypeScript
import { Events, Click } from 'pointeract';

type AvailableEvents = Events<Click>;
// available events: pan, zoom, drag, trueClick
```

--------------------------------

### PointeractInterface for instance type

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/basic/types.md

Shows how to get the type of a Pointeract instance using the PointeractInterface exported class. InstanceType is exactly the type of the instance created with the same modules.

```TypeScript
import { PointeractInterface, Pointeract, Click } from 'pointeract';

const instance = new Pointeract({ element: document.body }, [Click]);
type InstanceType = PointeractInterface<[Click]>;
```

--------------------------------

### Unsubscribe from drag event with off()

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/basic/use-pointeract.md

Use off() to unsubscribe from events, similar to removeEventListener(). The example unsubscribes the previously defined hook from the 'drag' event.

```TypeScript
pointeract.off('drag', hook);
```

--------------------------------

### Extract single event type with indexed access

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/basic/types.md

Shows how to extract the type of a single event from the Events type using indexed access. The example extracts the 'pan' event type and uses it in a callback.

```TypeScript
type PanEvents = Events<Click>['pan'];

const onPan = (e: PanEvent) => console.log(e);
```

--------------------------------

### Swipe Module Loading

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/modules/swipe.md

Shows how to import and initialize the Swipe module with Pointeract.

```APIDOC
## Swipe Module Loading

### Description
Import the Swipe module and pass it to the Pointeract constructor to enable swipe detection.

### Code Example
```TypeScript
import { Swipe, Pointeract } from 'pointeract';
const pointeract = new Pointeract({ element: app }, [Swipe]);
```
```

--------------------------------

### Click Module Usage

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/modules/click.md

Shows how to load and use the Click module with the Pointeract library, including the available options.

```APIDOC
## Click Module

### Description
The Click module checks whether the mouse/touch has actually moved during down and up, and dispatches a `trueClick` event when it has not moved.

### Event
- **trueClick** - Dispatched when a click is detected without significant pointer movement.

### Loading
```TypeScript
import { Click, Pointeract } from 'pointeract';
const pointeract = new Pointeract({ element: app }, [Click]);
```

### Options
```TypeScript
interface Options extends BaseOptions {
    clickStreakWindow?: number;
    clickMoveThreshold?: number;
}
```

- `clickStreakWindow` (number) - Optional - The interval in milliseconds between which two click events are considered in a streak. Defaults to **400**.
- `clickMoveThreshold` (number) - Optional - The upper limit in pixels for pointer movement to be considered a click. Defaults to **5**.
```

--------------------------------

### new Pointeract(options, modules?)

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/basic/use-pointeract.md

Creates a new Pointeract instance with the given options and optional modules.

```APIDOC
## [CONSTRUCTOR] new Pointeract(options, modules?)

### Description
Creates a new Pointeract instance. The modules parameter is optional and can be an array of module constructors.

### Method
Constructor

### Endpoint
`new Pointeract(options, modules?)`

### Parameters
#### Constructor Parameters
- **options** (object) - Required - Options for the Pointeract instance. See the Options section for details.
- **modules** (Array<ModuleConstructor>) - Optional - An array of module constructors to enable.

### Request Example
```TypeScript
const options = {
    element: app,
    coordinateOutput: 'absolute',
}
const pointeract = new Pointeract(options, [Drag, PreventDefault]);
```

### Response
#### Success Response
- **pointeract** (Pointeract) - The created Pointeract instance.

#### Response Example
```TypeScript
const pointeract = new Pointeract(options, [Drag, PreventDefault]);
```
```

--------------------------------

### Import and instantiate WheelPanZoom

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/modules/wheel-pan-zoom.md

Shows how to load the WheelPanZoom module and attach it to a Pointeract instance. The module is passed as an array element to the Pointeract constructor.

```TypeScript
import { WheelPanZoom, Pointeract } from 'pointeract';
const pointeract = new Pointeract({ element: app }, [WheelPanZoom]);
```

--------------------------------

### new Pointeract(options, modules)

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/basic/use-pointeract.md

Creates a new Pointeract instance with the given options and modules.

```APIDOC
## new Pointeract(options, modules)

### Description
Creates a new Pointeract instance with the given options and modules.

### Method
constructor

### Parameters
- **options** (object) - Required - The options object. Must include `element` and optionally `coordinateOutput`.
- **modules** (array) - Required - An array of modules to enable.

### Options
- **element** (HTMLElement) - Required - The element to monitor.
- **coordinateOutput** (string) - Optional - Defines the output coordinates format. Possible values: 'absolute', 'relative' (default), 'relativeFraction'.

### Example
```typescript
const options = {
    element: app,
    coordinateOutput: 'absolute',
}
const pointeract = new Pointeract(options, [Drag, PreventDefault]);
```
```

--------------------------------

### BaseModule Hooks and dispatch

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/development/custom-modules.md

Documentation for the BaseModule hooks and the dispatch method for custom modules in Pointeract.

```APIDOC
## BaseModule Hooks

### Description
Defines lifecycle and event hooks for custom modules in Pointeract. These hooks are called by Pointeract when corresponding pointer or lifecycle events occur.

### Method
Class definition

### Endpoint
BaseModule

### Parameters
#### Hooks
- **onPointerDown** (function) - Optional - Triggered when a pointer is pressed (same to `pointerdown` event but with extra context and avoids repeatedly adding listeners).
- **onPointerMove** (function) - Optional - Triggered when a pointer is moved (same to `pointermove` event).
- **onPointerUp** (function) - Optional - Triggered when a pointer is released (same to `pointerup` event).
- **onWheel** (function) - Optional - Triggered when a wheel event is triggered (same to `wheel` event).
- **onStart** (function) - Optional - Triggered when the module is started or after construction (`pointeract.start([MyModule])`).
- **onStop** (function) - Optional - Triggered when the module is stopped or before disposal (`pointeract.stop([MyModule])`).
- **dispose** (function) - Optional - Triggered when the module and the Pointeract instance is disposed (`pointeract.dispose()`).

### Request Example
```TypeScript
class MyModule extends BaseModule {
  onPointerDown = (event, pointer, pointers) => {
    // handle pointer down
  };
}
```

### Response
#### Success Response
No return value expected.

#### Response Example
No response body.

## dispatch(name, detail)

### Description
Dispatches a custom event from within a module. The first argument is the event name, the second is the event body, which can be undefined.

### Method
Method call

### Endpoint
this.dispatch(name, detail)

### Parameters
#### Arguments
- **name** (string) - Required - The event name.
- **detail** (any) - Optional - The event body, can be undefined.

### Request Example
```TypeScript
this.dispatch('my-event', { data: 'value' });
```

### Response
#### Success Response
No return value.

#### Response Example
No response body.
```

--------------------------------

### Import and initialize Click module

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/modules/click.md

Loads the Click module by passing it to the Pointeract constructor along with the target element.

```TypeScript
import { Click, Pointeract } from 'pointeract';
const pointeract = new Pointeract({ element: app }, [Click]);
```

--------------------------------

### Smooth Dragging with Lubricator

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/events/drag.md

Shows how to configure Pointeract with the Lubricator module and the lubricatorDragPreset to smoothify drag events.

```APIDOC
## Smooth Dragging with Lubricator

### Description
Pointeract supports using the `Lubricator` module to smoothify `drag` events. For quick configuration, you can use the `lubricatorDragPreset`.

### Usage Example
```TypeScript
import { Drag, Lubricator, Pointeract, lubricatorDragPreset as drag } from 'pointeract';

new Pointeract({
    element: app,
    lubricator: { drag },
}, [Drag, Lubricator])
```
```

--------------------------------

### Options type parameters accept module constructors, instances, or nothing

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/basic/types.md

Shows the three accepted type parameter forms for Pointeract types: module constructor types, module instance types, or nothing. MyOptions1 and MyOptions2 are equivalent, MyOptions3 is the base options.

```TypeScript
import { Drag, PreventDefault, type Options } from "pointeract";

type MyOptions1 = Options<[Drag, PreventDefault]>;
type MyOptions2 = Options<[typeof Drag, typeof PreventDefault]>;
type MyOptions3 = Options;
```

--------------------------------

### Context7 query prompt for pointeract

Source: https://github.com/hesprs/pointeract/blob/main/README.md

Use this prompt with AI agents when using Context7, which has a high score of 94 for pointeract, to skip the longer prompt and directly query the library.

```markdown
Query `pointeract` on Context7.
```

--------------------------------

### Import and instantiate Swipe with Pointeract

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/modules/swipe.md

Loads the Swipe module and creates a Pointeract instance with it. The element is set to 'app'.

```TypeScript
import { Swipe, Pointeract } from 'pointeract';
const pointeract = new Pointeract({ element: app }, [Swipe]);
```

--------------------------------

### Smooth zooming with lubricatorZoomPreset

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/events/zoom.md

Configures Pointeract with the lubricatorZoomPreset to smoothify zoom events. Requires the Lubricator module and the WheelPanZoom plugin, and passes the preset as the zoom lubricator.

```TypeScript
import { WheelPanZoom, Lubricator, Pointeract, lubricatorZoomPreset as zoom } from 'pointeract';

new Pointeract({
    element: app,
    lubricator: { zoom },
}, [WheelPanZoom, Lubricator])
```

--------------------------------

### Load Pointeract from unpkg in HTML

Source: https://github.com/hesprs/pointeract/blob/main/README.md

Include Pointeract directly in an HTML file via a module script. This link ships the latest ESM version by default.

```html
<script type="module">
  import { Pointeract } from 'https://unpkg.com/pointeract';
</script>
```

--------------------------------

### Smooth dragging with Lubricator preset

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/events/drag.md

Configures Pointeract with the Drag and Lubricator modules, using the lubricatorDragPreset to smoothify drag events. Requires importing Drag, Lubricator, Pointeract, and the preset.

```TypeScript
import { Drag, Lubricator, Pointeract, lubricatorDragPreset as drag } from 'pointeract';

new Pointeract({
    element: app,
    lubricator: { drag },
}, [Drag, Lubricator])
```

--------------------------------

### Options export with Click module

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/basic/types.md

Shows how to access the options type elsewhere using the Options export, passing the same modules as in the constructor. The resulting type includes the base options plus those added by Click.

```TypeScript
import { Options, Click } from 'pointeract';

type AvailableOptions = Options<[Click]>;
// available options: coordinateOutput, element, clickPreserveTime, moveThreshold
```

--------------------------------

### AI agent prompt for pointeract

Source: https://github.com/hesprs/pointeract/blob/main/README.md

Use this prompt with AI coding agents like OpenCode, Claude Code, Cursor, or a chat bot to have them handle a task using pointeract. Replace the placeholder comment with your specific requirements.

```markdown
I'm using `pointeract`, a library to detect user gestures, which can be considered as a modern alternative to Hammer.js. Read the documentation and help me with my requirements.

**"Get Started" Page in Documentation Website**: https://pointeract.consensia.cc/get-started (fetch more internal links when needed)

**Requirements**:

<!-- your requirements here -->
```

--------------------------------

### Customize module constructor with BaseArgs

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/development/custom-modules.md

Customizes the construction process by accepting BaseArgs and spreading them into super(). Use this when you need to add custom initialization logic.

```TypeScript
import { BaseModule, type BaseArgs } from 'pointeract';

class MyModule extends BaseModule {
    constructor(...args: BaseArgs) {
        super(...args);
        // ... your logic
    }
}
```

--------------------------------

### Load Drag Module with Pointeract

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/modules/drag.md

Imports the Drag and Pointeract classes from 'pointeract', then creates a new Pointeract instance with the app element and the Drag module to enable drag interactions.

```TypeScript
import { Drag, Pointeract } from 'pointeract';
const pointeract = new Pointeract({ element: app }, [Drag]);
```

--------------------------------

### BaseModule properties and Pointer type

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/development/custom-modules.md

Shows the properties and helpers available on BaseModule, including options, element, window, pointers, getNthPointer, toTargetCoords, augment, and dispatch. Also defines the Pointer type with records, target, and indexable properties.

```TypeScript
class BaseModule {
    options: <orchestrated options>;
    element: HTMLElement;
    window: Window;
    pointers: Map<number, Pointer>;
    getNthPointer: (n: number) => Pointer;
    toTargetCoords: (raw: Coordinates) => Coordinates;
    augment: (<orchestrated augmentations>) => void;
    dispatch: (name: <orchestrated event names>, detail?: <corresponding detail>) => void;
}

type Pointer = {
    records: Array<{ x: number; y: number; timestamp: number }>; // pointer records, coordinates are absolute screen coords
    target: EventTarget | null;
    [key: Indexable]: any; // your can add your own properties into a pointer, the key can be a string, number or symbol
};
```

--------------------------------

### Pointeract constructor options type orchestration

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/basic/types.md

Demonstrates how Pointeract automatically orchestrates the options type when instantiating the class. Without modules, only element and coordinateOutput are available; with Click, clickPreserveTime and moveThreshold are added.

```TypeScript
import { Pointeract, Click } from 'pointeract';

const options = { element: document.body };

new Pointeract(options);
// available options: element, coordinateOutput

new Pointeract(options, [Click]);
// available options: element, coordinateOutput, clickPreserveTime, moveThreshold
```

--------------------------------

### WheelPanZoom options interface

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/modules/wheel-pan-zoom.md

Defines the options interface for WheelPanZoom. Includes proControlSchema, lockControlSchema, and zoomFactor with their defaults described in the surrounding text.

```TypeScript
interface Options extends BaseOptions {
    proControlSchema?: boolean;
    lockControlSchema?: boolean;
    zoomFactor?: number;
}
```

--------------------------------

### on(event, handler)

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/basic/use-pointeract.md

Subscribes to a Pointeract event. The usage is similar to addEventListener() but fully typed and returns the pointeract instance for chaining.

```APIDOC
## on(event, handler)

### Description
Subscribes to a Pointeract event. The usage is similar to addEventListener() but fully typed and returns the pointeract instance for chaining.

### Method
on

### Parameters
- **event** (string) - Required - The event name to subscribe to. Must be a valid event from StdEvents.
- **handler** (function) - Required - The callback function to be invoked when the event is triggered.

### Returns
- The Pointeract instance for chaining.

### Example
```typescript
import type { StdEvents } from 'pointeract';

const hook = (e: StdEvents['drag']) => {
    console.log(e);
};
pointeract.on('drag', hook);
```
```

--------------------------------

### Define custom options with BaseOptions

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/development/custom-modules.md

Shows how to define custom options for a Pointeract module by extending BaseOptions and using the generic type parameter on BaseModule. The options reference is shared across the base class and modules, so this enables type-safe access to custom options.

```TypeScript
import { BaseModule, BaseOptions } from 'pointeract';

interface Options extends BaseOptions {
    moduleEnabled?: boolean,
}

class YourModule extends BaseModule<Options> {
    onPointerMove = () => {
        if (!this.options.moduleEnabled) return; // no error
    }
}
```

--------------------------------

### Swipe Options Interface

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/modules/swipe.md

Defines the options interface for configuring swipe detection behavior.

```APIDOC
## Swipe Options Interface

### Description
Options for configuring swipe detection, including minimum distance, velocity, timing windows, and direction mapping.

### Interface Definition
```TypeScript
interface Options extends BaseOptions {
	swipeMinDistance?: number;
	swipeMinVelocity?: number;
	swipeVelocityWindow?: number;
	swipeStreakWindow?: number;
    swipeDirectionMap?: Record<string, number>;
}
```

### Options Details
- **swipeMinDistance** (number) - Optional - The minimum distance in pixels that the pointer must move to be considered a swipe. Defaults to **20**.
- **swipeMinVelocity** (number) - Optional - The minimum velocity in pixels per second that the pointer must move to be considered a swipe. Defaults to **0**.
- **swipeVelocityWindow** (number) - Optional - The time window in milliseconds used to calculate the final velocity of the swipe. Defaults to **200**.
- **swipeStreakWindow** (number) - Optional - The time window in milliseconds within which concurrent pointer swipes are grouped into a combined event. Defaults to **400**.
- **swipeDirectionMap** (Record<string, number>) - Optional - The map of direction names with their boundary values of the angles that split a circle. The keys are the values of `direction` field in the [swipe event](/events/swipe).
```

--------------------------------

### Use Lubricator presets for pan and zoom

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/modules/lubricator.md

Uses the `lubricatorPanPreset` and `lubricatorZoomPreset` presets to configure Lubricator for `pan` and `zoom` events. Presets are imported from `pointeract` and plugged into the `lubricator` option.

```TypeScript
import {
    WheelPanZoom,
    Lubricator,
    Pointeract,
    lubricatorPanPreset as pan,
    lubricatorZoomPreset as zoom,
} from 'pointeract';

new Pointeract({
    element: app,
    lubricator: { pan, zoom },
}, [WheelPanZoom, Lubricator])
```

--------------------------------

### Import and instantiate Pointeract with PreventDefault

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/modules/prevent-default.md

Loads the PreventDefault module by importing it and passing it as a plugin to the Pointeract constructor. The module disables default browser behaviors for touch, mouse, and wheel events on the specified element.

```TypeScript
import { PreventDefault, Pointeract } from 'pointeract';
const pointeract = new Pointeract({ element: app }, [PreventDefault]);
```

--------------------------------

### Use augmented method on Pointeract instance

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/development/custom-modules.md

Demonstrates using the augmented method on a Pointeract instance. After loading the module, instance.log() is available with no type error and logs 'log injected!' to the console.

```TypeScript
import { Pointeract } from 'pointeract';
import YourModule from './your-module';

const instance = new Pointeract({ element: app }, [YourModule]);
instance.log();

// Result:
// no type error
// 'log injected!' appears in the console
```

--------------------------------

### Smooth panning with lubricatorPanPreset

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/events/pan.md

Configures Pointeract with a lubricator for smooth pan events, using the lubricatorPanPreset as the pan option.

```TypeScript
import { WheelPanZoom, Lubricator, Pointeract, lubricatorPanPreset as pan } from 'pointeract';

new Pointeract({
    element: app,
    lubricator: { pan },
}, [WheelPanZoom, Lubricator])
```

--------------------------------

### pointeract.on(eventName, callback)

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/basic/use-pointeract.md

Subscribes to an event emitted by Pointeract.

```APIDOC
## [METHOD] pointeract.on(eventName, callback)

### Description
Subscribes a callback to a Pointeract event. The event name and callback signature depend on the events emitted by Pointeract and its modules.

### Method
on

### Endpoint
`pointeract.on(eventName, callback)`

### Parameters
#### Parameters
- **eventName** (string) - Required - The name of the event to subscribe to.
- **callback** (Function) - Required - The callback function to invoke when the event is emitted.

### Request Example
```TypeScript
pointeract.on('drag', (event) => {
    console.log(event);
});
```

### Response
#### Success Response
- **void** - No return value.

#### Response Example
```TypeScript
pointeract.on('drag', (event) => {
    console.log(event);
});
```
```

--------------------------------

### Click module options interface

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/modules/click.md

Defines the options interface for the Click module, with optional clickStreakWindow and clickMoveThreshold properties.

```TypeScript
interface Options extends BaseOptions {
    clickStreakWindow?: number;
    clickMoveThreshold?: number;
}
```

--------------------------------

### Swipe options interface

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/modules/swipe.md

Defines the options interface for the Swipe module, extending BaseOptions with swipe-specific settings.

```TypeScript
interface Options extends BaseOptions {
	swipeMinDistance?: number;
	swipeMinVelocity?: number;
	swipeVelocityWindow?: number;
	swipeStreakWindow?: number;
    swipeDirectionMap?: Record<string, number>;
}
```

--------------------------------

### Extend BaseModule to create a custom module

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/development/custom-modules.md

Defines a custom module by extending BaseModule. The class can contain custom logic but must be instantiated by Pointeract.

```TypeScript
import { BaseModule } from 'pointeract';

class MyModule extends BaseModule {
    // ... your logic
}
```

--------------------------------

### BaseOptions interface

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/basic/use-pointeract.md

The BaseOptions interface defines the two base options: element (required) and coordinateOutput (optional). coordinateOutput can be 'absolute', 'relative' (default), or 'relativeFraction'.

```TypeScript
interface BaseOptions {
    element: HTMLElement;
    coordinateOutput?: 'absolute' | 'relative' | 'relativeFraction';
}
```

--------------------------------

### BaseModule class

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/development/custom-modules.md

The BaseModule class is the base class for all Pointeract modules. It provides properties and methods for accessing options, the element, window, pointers, and dispatching events.

```APIDOC
## BaseModule

### Description
The `BaseModule` class is the base class for all Pointeract modules. It provides properties and methods for accessing options, the element, window, pointers, and dispatching events.

### Properties
- `options` (orchestrated options) - The full options that the user passes in.
- `element` (HTMLElement) - The element to be monitored, same as the `event` field in `BaseOptions`.
- `window` (Window) - The window context of the monitoring element.
- `pointers` (Map<number, Pointer>) - A hot-updated map of pointers, keyed by pointer ID.
- `getNthPointer` (function) - Get the nth pointer value in the pointers map.
- `toTargetCoords` (function) - Convert screen coordinates to target coordinates configured by `coordinateOutput`.
- `augment` (function) - Inject properties into the parent `Pointeract` instance.
- `dispatch` (function) - Dispatch an event with a given name and detail.

### Type Parameters
- `Options` - Defaults to `BaseOptions`.
- `Events` - Defaults to `StdEvents`.
- `Augmentation` - Defaults to `{}`.

### Example
```TypeScript
import { BaseModule } from 'pointeract';

class MyModule extends BaseModule {
    // ... your logic
}
```
```

--------------------------------

### Load Lubricator with drag preset

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/modules/lubricator.md

Loads the Lubricator module with the drag preset. The module is a functional module that intercepts configured events and emits smoothified events. It requires the Drag module to be included in the modules array.

```TypeScript
import { Lubricator, Pointeract, Drag, lubricatorDragPreset as drag } from 'pointeract';
const pointeract = new Pointeract({
    element: app,
    lubricator: { drag },
}, [Lubricator, Drag]);
```

--------------------------------

### Augment Pointeract instance with custom method

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/development/custom-modules.md

Shows how to augment the Pointeract instance with custom methods. You must define an Augmentation interface and call this.augment() in the constructor. The default augmentation is empty, so no extension is needed.

```TypeScript
import { BaseModule, BaseOptions, StdEvents, BaseArgs } from 'pointeract';

interface Augmentation {
    log: YourModule['log'];
}

export default class YourModule extends BaseModule<Options, StdEvents, Augmentation> {
    private log = () => console.log('log injected!');

    constructor(...args: BaseArgs) {
        super(...args);
        this.augment({ log: this.log });
    }
}
```

--------------------------------

### pointeract.dispose()

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/basic/use-pointeract.md

Completely disposes the Pointeract instance and all its modules.

```APIDOC
## [METHOD] pointeract.dispose()

### Description
Disposes the Pointeract instance, cleaning up all resources, event listeners, and modules. After disposal, the instance cannot be reused.

### Method
dispose

### Endpoint
`pointeract.dispose()`

### Parameters
#### Parameters
None.

### Request Example
```TypeScript
pointeract.dispose();
```

### Response
#### Success Response
- **void** - No return value.

#### Response Example
```TypeScript
pointeract.dispose();
```
```

--------------------------------

### Stop Multiple Modules with Constructors

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/basic/use-pointeract.md

Stops specific modules at runtime by passing their constructors. Modules are enabled by default at construction. You cannot load a module not passed into the constructor.

```TypeScript
pointeract.stop([PreventDefault, Drag]); // multiple modules
```

--------------------------------

### Default Direction Map

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/modules/swipe.md

Shows the default direction map used when no custom map is provided.

```APIDOC
## Default Direction Map

### Description
The default direction map recognizes the four cardinal directions: left, down, right, and up.

### Code Example
```TypeScript
const defaultDirectionMap = {
	left: -(Math.PI / 4) * 3, // -135 degrees
	down: -Math.PI / 4,       // -45 degrees
	right: Math.PI / 4,       // 45 degrees
	up: (Math.PI / 4) * 3,    // 135 degrees
};
```
```

--------------------------------

### Smoothify zoom event with Lubricator

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/modules/lubricator.md

Configures Lubricator to intercept the `zoom` event, interpolate the `factor` field with a product goal, and stop when the leftover zoom factor is less than 0.01. The `decayFactor` of 0.25 controls the interpolation speed.

```TypeScript
import { WheelPanZoom, Lubricator, Pointeract } from 'pointeract';

new Pointeract({
    element: app,
    lubricator: {
        zoom: {
            decayFactor: 0.25,
            fields: {
                factor: {
                    countType: 'product',
                    diminishBoundary: 0.01,
                },
            },
        },
    },
}, [WheelPanZoom, Lubricator])
```

--------------------------------

### Pass custom events to `BaseModule` and dispatch them

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/development/custom-modules.md

Passes the custom events type parameter to `BaseModule` and dispatches the custom events. The `dispatch` calls are type-checked, providing full type safety for you and your module users.

```TypeScript
class YourModule extends BaseModule<BaseOptions, CustomEvents> {
    onPointerMove = () => {
        this.dispatch('moveMove'); // no error
        this.dispatch('moveDetail', { x: 0, y: 0 }); // no error
    };
}
```

--------------------------------

### Zoom Event

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/events/zoom.md

The zoom event provides the coordinates of the zoom origin and the zoom factor. It is accessible via Events['zoom'] and can be smoothed using the Lubricator module.

```APIDOC
## Zoom Event

### Description
This event is triggered when a zoom gesture occurs, providing the zoom origin coordinates and the zoom factor.

### Event Name
`zoom`

### Access Type
`Events['zoom']`

### Event Data
- **x** (number) - The x-coordinate of the zoom origin.
- **y** (number) - The y-coordinate of the zoom origin.
- **factor** (number) - The zoom factor; smaller than 1 zooms out, larger than 1 zooms in.

### Type Definition
```TypeScript
type ZoomEvent = {
    x: number;
    y: number;
    factor: number;
}
```
```

--------------------------------

### Drag Event Type

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/events/drag.md

The drag event provides the current pointer position and the delta movement since the last dispatch.

```APIDOC
## Drag Event

### Description
The `drag` event is triggered when the pointer moves while dragging. It provides the current position and the delta movement since the last dispatch.

### Event Name
`drag`

### Access Type
`Events['drag']`

### Details
```TypeScript
type DragEvent = {
    x: number;
    y: number;
    deltaX: number;
    deltaY: number;
}
```

### Properties
- **x** (number) - The x-coordinate of the pointer when the drag event is triggered.
- **y** (number) - The y-coordinate of the pointer when the drag event is triggered.
- **deltaX** (number) - The amount of drag in the x direction - the difference between the current position and the position of the last dispatch.
- **deltaY** (number) - The amount of drag in the y direction - the difference between the current position and the position of the last dispatch.
```

--------------------------------

### trueClick Event

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/events/true-click.md

The trueClick event fires when the pointer is released and the movement is below a threshold. It provides the pointer coordinates, target element, and a streak count for detecting multi-clicks.

```APIDOC
## trueClick Event

### Description
The `trueClick` event is dispatched when the pointer is released and the pointer movement is below a threshold, providing a more accurate click detection than the built-in `click` event.

### Event Name
`trueClick`

### Access Type
`Events['trueClick']`

### Details

```TypeScript
type TrueClickEvent = {
    x: number;
    y: number;
    target: EventTarget | null;
    streak: number;
}
```

- `x`, `y`: The coordinates of the pointer when the click event is triggered.
- `target`: The target element of the click event.
- `streak`: The number of clicks in a streak, you can use this to detect double/triple/quadruple/any click or tap.
```

--------------------------------

### Default direction map

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/modules/swipe.md

The default direction map for cardinal directions, with boundary angles in radians.

```TypeScript
const defaultDirectionMap = {
	left: -(Math.PI / 4) * 3, // -135 degrees
	down: -Math.PI / 4,       // -45 degrees
	right: Math.PI / 4,       // 45 degrees
	up: (Math.PI / 4) * 3,    // 135 degrees
};
```

--------------------------------

### Dispose Pointeract

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/basic/use-pointeract.md

Completely disposes the Pointeract instance. You do not need to call stop() or unsubscribe event listeners first; dispose() handles everything.

```TypeScript
pointeract.dispose();
```

--------------------------------

### pointeract.stop()

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/basic/use-pointeract.md

Stops the Pointeract instance or specified modules.

```APIDOC
## [METHOD] pointeract.stop()

### Description
Stops the Pointeract instance if no arguments are provided. If module constructors are provided, stops those modules. Stopping the base class pauses all modules, but modules can be individually stopped at module level.

### Method
stop

### Endpoint
`pointeract.stop(modules?)`

### Parameters
#### Parameters
- **modules** (Array<ModuleConstructor>) - Optional - An array of module constructors to stop. If omitted, stops the base class.

### Request Example
```TypeScript
pointeract.stop(); // stops the base class
pointeract.stop([PreventDefault]); // stops the PreventDefault module
```

### Response
#### Success Response
- **void** - No return value.

#### Response Example
```TypeScript
pointeract.stop();
```
```

--------------------------------

### off(event, handler)

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/basic/use-pointeract.md

Unsubscribes from a Pointeract event. The usage is similar to removeEventListener().

```APIDOC
## off(event, handler)

### Description
Unsubscribes from a Pointeract event. The usage is similar to removeEventListener().

### Method
off

### Parameters
- **event** (string) - Required - The event name to unsubscribe from.
- **handler** (function) - Required - The callback function that was used when subscribing.

### Returns
- The Pointeract instance for chaining.

### Example
```typescript
pointeract.off('drag', hook);
```
```

--------------------------------

### Extend `StdEvents` to declare custom events

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/development/custom-modules.md

Declares custom events by extending `StdEvents`. Add an event with no detail (`moveMove`) and an event with a detail object (`moveDetail`). This is required before using custom events in a module.

```TypeScript
import { BaseModule, StdEvents, BaseOptions } from 'pointeract';

interface CustomEvents extends StdEvents {
    moveMove: undefined; // add an event with no detail
    moveDetail: { x: number; y: number }; // add an event with detail of coordinates
}
```

--------------------------------

### pointeract.off(eventName, callback)

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/basic/use-pointeract.md

Unsubscribes a callback from a Pointeract event.

```APIDOC
## [METHOD] pointeract.off(eventName, callback)

### Description
Removes a previously subscribed callback from a Pointeract event.

### Method
off

### Endpoint
`pointeract.off(eventName, callback)`

### Parameters
#### Parameters
- **eventName** (string) - Required - The name of the event to unsubscribe from.
- **callback** (Function) - Required - The callback function to remove.

### Request Example
```TypeScript
const callback = (event) => {
    console.log(event);
};
pointeract.on('drag', callback);
pointeract.off('drag', callback);
```

### Response
#### Success Response
- **void** - No return value.

#### Response Example
```TypeScript
pointeract.off('drag', callback);
```
```

--------------------------------

### ZoomEvent type definition

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/events/zoom.md

Defines the structure of the zoom event, including the origin coordinates (x, y) and the zoom factor. The factor is smaller than 1 for zooming out and larger than 1 for zooming in.

```TypeScript
type ZoomEvent = {
    x: number;
    y: number;
    factor: number;
}
```

--------------------------------

### Lubricator Options interface

Source: https://github.com/hesprs/pointeract/blob/main/docs/src/pages/en/modules/lubricator.md

Defines the Options interface for the Lubricator module. The `lubricator` property contains per-event configurations, each with `decayFactor` and `fields`. Per-field configurations include `countType` ('sum' or 'product') and `diminishBoundary`.

```TypeScript
interface Options extends BaseOptions {
    lubricator?: {
        // this is the configuration for each event
        [Key: string]?: {
            decayFactor: number;
	        fields: {
                // this is the configuration for each field in the emitted event
                [Key: string]?: {
                    countType: 'sum' | 'product';
                    diminishBoundary: number;
                };
            };
        };
    };
}
```
Tokens:
Raw