Hermes

A utility library for scroll, wheel, keyboard, and touch event normalization.

Installation

npm install @adoratorio/hermes

Usage

This package is ESM-only. Import it as a module:

import Hermes from '@adoratorio/hermes';

const hermes = new Hermes({
  mode: Hermes.MODE.VIRTUAL,
  events: [Hermes.EVENTS.WHEEL, Hermes.EVENTS.TOUCH]
});

hermes.on((event) => {
  console.log(event.type, event.delta);
});

Configuration

| Parameter | Type | Default | Description | | :-------- | :--: | :-----: | :---------- | | mode | string | Hermes.MODE.VIRTUAL | VIRTUAL uses wheel/touch/key events; NATIVE listens to native scroll. | | events | Array<string> | [WHEEL, TOUCH, KEYS] | The events to listen to. | | root | HTMLElement \| Window| fallback | The DOM element used as the event listener root. | | passive | boolean | true | Use passive event listeners (improves perf, but prevents preventDefault()). | | emitGlobal | boolean | false | Emit global custom events on the window. | | touchMultiplier | number | 2 | Multiplier for touch values. | | keyMultiplier | number \| KeyMultipliers | 1 | Multiplier applied to keyboard-scroll deltas, globally or per key (keyed by Hermes.KEY). | | debug | boolean | false | Enable namespaced console.warn diagnostics for recoverable issues (contract violations always throw). |

Events option

• Hermes.EVENTS.WHEEL - wheel events, normalized across deltaModes.
• Hermes.EVENTS.TOUCH - touch moves; the release emits one more touch event whose delta is the gesture momentum.
• Hermes.EVENTS.KEYS - every scroll key: arrows, space (shift+space scrolls up), page up/down, home/end.
• Hermes.EVENTS.SPACEBAR / Hermes.EVENTS.ARROWS - narrower key groups, used only when KEYS is not enabled.

Keys are matched on KeyboardEvent.key; the values are exposed as Hermes.KEY (ArrowUp, PageDown, Home, ...). Keys pressed inside inputs, textareas, selects and contenteditable elements are ignored.

Methods

// Sets (or replaces) the handler and binds the listeners on the first call
hermes.on(handler: HermesHandler);

// Clears the handler and unbinds listeners
hermes.off();

// Alias for off()
hermes.destroy();

// Getter/Setter that gates emission on/off without unbinding
hermes.listen = false;

// Whether the listeners are currently bound
hermes.bound;

// Multipliers can be changed at runtime
hermes.touchMultiplier = 1.5;
hermes.keyMultiplier = { [Hermes.KEY.SPACE]: 0.5 };

Events

The handler receives a HermesEvent object:

interface HermesEvent {
  type: string;          // e.g., 'wheel', 'touch', 'keys'
  delta: Vec2;           // Normalized delta
  originalEvent: Event;  // The underlying DOM event
}

TypeScript Support

Hermes is entirely written in TypeScript and exports specific types like HermesEvent, HermesOptions, KeyMultipliers, and the MODE, EVENTS, KEY and DELTA_MODE constants.

Maintenance and compatibility

See MAINTAINERS.md, CONTRIBUTING.md and CHANGELOG.md. Historical contributor credits are retained. The CI runtime is Node 24; DOM instances are client-only. Imports are SSR-safe. The runtime expects native ES2023 support; TypeScript does not provide browser polyfills. DOM functionality uses requestAnimationFrame, Pointer/Touch Events and observers where applicable. Test the target browser matrix before release.

pageSize: 'root' opts in to root viewport dimensions for page-mode wheel input, space and PageUp/PageDown. The default pageSize: 'legacy' preserves existing wheel scaling and keyboard sensitivity.