web-haptic-engine 1.0.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright © 2026 Sumit Sahoo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,328 @@
+<div align="center">
+
+  <h1>📳 Web Haptic Engine</h1>
+
+  <p>A cross-platform haptic feedback engine for the web.<br>
+  Supports Android vibration, iOS Taptic feedback, audio impulse synthesis, drag haptics, and 23 built-in presets.</p>
+
+  <p>
+    <a href="https://www.npmjs.com/package/web-haptic-engine"><img src="https://img.shields.io/npm/v/web-haptic-engine" alt="npm version" /></a>
+    <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="MIT License" /></a>
+    <img src="https://img.shields.io/badge/platform-web-blue" alt="Platform" />
+    <img src="https://img.shields.io/badge/typescript-strict-blue" alt="TypeScript" />
+  </p>
+
+</div>
+
+---
+
+## ✨ Features
+
+| Category                   | Details                                                                                                 |
+| -------------------------- | ------------------------------------------------------------------------------------------------------- |
+| 📱 **Android Vibration**   | Full `navigator.vibrate()` pattern support with intensity-scaled durations                              |
+| 🍎 **iOS Taptic**          | Exploits the `<input type="checkbox" switch>` toggle to trigger native Taptic Engine feedback           |
+| 🔊 **Audio Impulse Layer** | 8 synthesized AudioBuffer impulses (`tick`, `tap`, `thud`, `click`, `snap`, `buzz`, `confirm`, `harsh`) |
+| 👆 **Drag Haptics**        | Touchmove-driven haptic feedback with distance threshold — works reliably on iOS                        |
+| 🎛️ **23 Presets**          | Ready-to-use patterns: `success`, `warning`, `error`, `heartbeat`, `spring`, `buzz`, and more           |
+| 🔗 **Sequences**           | Chain presets with delays, repeats, and custom gaps                                                     |
+| 〰️ **Easing Functions**    | `linear`, `easeIn`, `easeOut`, `easeInOut`, `bounce`, `spring`                                          |
+| 📦 **Zero Dependencies**   | No external runtime dependencies — pure TypeScript                                                      |
+
+---
+
+## 📥 Installation
+
+```bash
+npm install web-haptic-engine
+```
+
+```bash
+pnpm add web-haptic-engine
+```
+
+```bash
+yarn add web-haptic-engine
+```
+
+---
+
+## 🚀 Quick Start
+
+### Basic Usage
+
+```ts
+import { haptic } from "web-haptic-engine";
+
+// Fire a preset
+await haptic("success");
+await haptic("heartbeat");
+await haptic("click");
+
+// Fire with custom intensity
+await haptic("heavy", { intensity: 0.8 });
+
+// Fire a raw duration (ms)
+await haptic(50);
+```
+
+### Using the Engine
+
+```ts
+import { HapticEngine } from "web-haptic-engine";
+
+const engine = new HapticEngine({
+  throttleMs: 25,
+  audioLayer: true,
+  audioGain: 0.6,
+});
+
+// Trigger presets
+await engine.trigger("confirm");
+await engine.trigger("buzz", { intensity: 1.0 });
+
+// Sequences
+await engine.sequence([{ preset: "rampUp" }, { preset: "confirm", delay: 200 }], {
+  repeat: 2,
+  repeatGap: 300,
+});
+
+// Custom presets
+engine.registerPreset("myPattern", {
+  pattern: [
+    { duration: 20, intensity: 0.6 },
+    { delay: 50, duration: 40, intensity: 1.0 },
+  ],
+  impulse: "tap",
+  iosTicks: 2,
+  iosTickGap: 60,
+});
+await engine.trigger("myPattern");
+
+// Cleanup
+engine.destroy();
+```
+
+### 👆 Drag Haptics
+
+```ts
+import { HapticEngine } from "web-haptic-engine";
+
+const engine = new HapticEngine();
+
+const drag = engine.drag({
+  fireDist: 18, // px between haptic fires
+  impulse: "tick", // audio impulse type
+  intensity: 0.6,
+  onTick: (velocity, ticks) => {
+    console.log(`Tick #${ticks} at ${velocity}px/s`);
+  },
+});
+
+// Bind to a DOM element
+const unbind = drag.bind(document.getElementById("drag-area")!);
+
+// Later: cleanup
+unbind();
+drag.destroyAll();
+engine.destroy();
+```
+
+---
+
+## 🎛️ Presets
+
+| Preset         | Description               | Impulse   |
+| -------------- | ------------------------- | --------- |
+| ✅ `success`   | Ascending double-tap      | `confirm` |
+| ⚠️ `warning`   | Two hesitant taps         | `harsh`   |
+| ❌ `error`     | Three rapid harsh taps    | `harsh`   |
+| 👍 `confirm`   | Strong double-tap confirm | `confirm` |
+| 👎 `reject`    | Harsh staccato triple     | `harsh`   |
+| 🪶 `light`     | Single light tap          | `tick`    |
+| ⚖️ `medium`    | Moderate tap              | `tap`     |
+| 🏋️ `heavy`     | Strong tap                | `thud`    |
+| 🧸 `soft`      | Cushioned tap             | `tap`     |
+| 🔩 `rigid`     | Hard crisp snap           | `snap`    |
+| 🔘 `selection` | Subtle tick               | `tick`    |
+| ⏱️ `tick`      | Crisp tick                | `click`   |
+| 🖱️ `click`     | Ultra-short click         | `click`   |
+| 🫰 `snap`      | Sharp snap                | `snap`    |
+| 👉 `nudge`     | Two quick taps            | `tap`     |
+| 🐝 `buzz`      | Sustained vibration       | `buzz`    |
+| 💓 `heartbeat` | Heartbeat rhythm          | `thud`    |
+| 🧲 `spring`    | Bouncy pulses             | `tap`     |
+| 📈 `rampUp`    | Escalating                | `tap`     |
+| 📉 `rampDown`  | Decreasing                | `tap`     |
+| 💥 `thud`      | Heavy impact              | `thud`    |
+| 🎵 `trill`     | Rapid flutter             | `click`   |
+| 💗 `pulse`     | Rhythmic pulse            | `tap`     |
+
+---
+
+## 📖 API Reference
+
+### `HapticEngine`
+
+```ts
+const engine = new HapticEngine(options?: HapticEngineOptions)
+```
+
+| Option       | Type      | Default | Description                 |
+| ------------ | --------- | ------- | --------------------------- |
+| `throttleMs` | `number`  | `25`    | Minimum ms between triggers |
+| `audioLayer` | `boolean` | `true`  | Enable audio impulse layer  |
+| `audioGain`  | `number`  | `0.6`   | Master audio gain (0–1)     |
+
+#### 🔧 Methods
+
+| Method                         | Description                     |
+| ------------------------------ | ------------------------------- |
+| `trigger(input?, options?)`    | Fire a haptic pattern           |
+| `sequence(steps, options?)`    | Play a sequence of presets      |
+| `drag(options?)`               | Create a `DragHaptics` instance |
+| `cancel()`                     | Cancel active haptic playback   |
+| `setEnabled(enabled)`          | Enable/disable the engine       |
+| `setAudioLayer(enabled)`       | Toggle audio layer              |
+| `setAudioGain(gain)`           | Set audio gain (0–1)            |
+| `setThrottle(ms)`              | Set throttle interval           |
+| `registerPreset(name, preset)` | Register a custom preset        |
+| `fireHapticTick(intensity)`    | Fire a single platform tick     |
+| `fireImpulse(type, intensity)` | Fire a single audio impulse     |
+| `destroy()`                    | Clean up all resources          |
+
+#### 📊 Static Properties
+
+| Property                          | Description                                |
+| --------------------------------- | ------------------------------------------ |
+| `HapticEngine.supportsVibration`  | `true` if `navigator.vibrate` is available |
+| `HapticEngine.supportsIOSHaptics` | `true` if iOS Taptic switch is supported   |
+| `HapticEngine.isSupported`        | `true` if any haptic method is available   |
+
+### `DragHaptics`
+
+```ts
+const drag = engine.drag(options?: DragHapticsOptions)
+```
+
+| Option      | Type          | Default  | Description                             |
+| ----------- | ------------- | -------- | --------------------------------------- |
+| `fireDist`  | `number`      | `18`     | Minimum px moved to trigger next haptic |
+| `impulse`   | `ImpulseType` | `'tick'` | Audio impulse type                      |
+| `intensity` | `number`      | `0.6`    | Haptic intensity                        |
+| `onTick`    | `function`    | —        | Callback `(velocity, ticks) => void`    |
+
+### `haptic()` (convenience)
+
+```ts
+import { haptic } from "web-haptic-engine";
+
+await haptic("success"); // preset name
+await haptic(50); // raw duration ms
+await haptic([20, 10, 30]); // pattern array
+await haptic("heavy", { intensity: 1 }); // with options
+```
+
+---
+
+## 🌍 Platform Support
+
+| Platform          | Haptic Method                  | Audio                            |
+| ----------------- | ------------------------------ | -------------------------------- |
+| 📱 **Android**    | `navigator.vibrate()`          | AudioContext impulses            |
+| 🍎 **iOS Safari** | `<input switch>` Taptic toggle | AudioContext impulses            |
+| 🖥️ **Desktop**    | —                              | AudioContext impulses (fallback) |
+
+---
+
+## 🛠️ Tech Stack
+
+| Tool                                          | Purpose               |
+| --------------------------------------------- | --------------------- |
+| [TypeScript](https://www.typescriptlang.org/) | Type-safe source code |
+| [tsdown](https://tsdown.dev/)                 | Library bundling      |
+| [Vitest](https://vitest.dev/)                 | Unit testing          |
+| [Vite+](https://vite.dev/)                    | Unified toolchain     |
+
+---
+
+## 🧑‍💻 Development
+
+```bash
+# Install dependencies
+vp install
+
+# Build the library
+vp pack
+
+# Run tests
+vp test
+
+# Watch mode (rebuild on changes)
+vp pack --watch
+```
+
+---
+
+## 🎮 Demo
+
+An interactive demo is included in the `demo/` directory. It showcases all 23 presets, drag haptics, impulse buffers, sequences, and real-time controls for intensity and audio gain.
+
+```bash
+# Install dependencies (if not already done)
+vp install
+
+# Start the demo dev server
+vp run demo
+```
+
+This launches a Vite dev server. Open the URL shown in the terminal (typically `http://localhost:5173`) in your browser. For the full haptic experience, open it on a mobile device — Android for vibration, iOS Safari for Taptic feedback. On desktop, audio impulses still play as a fallback.
+
+---
+
+## 📁 Project Structure
+
+```
+web-haptic-engine/
+├── src/
+│   ├── core/               # Types, constants, easings & presets
+│   ├── audio/              # Web Audio impulse synthesis & playback
+│   ├── platform/           # Platform detection & adapters (Android, iOS)
+│   ├── interactions/       # User interaction patterns (drag haptics)
+│   ├── haptic-engine.ts    # Main HapticEngine class & convenience helpers
+│   └── index.ts            # Public API exports
+├── demo/
+│   ├── index.html          # Demo page
+│   ├── main.ts             # Demo app (imports from library)
+│   └── vite.config.ts      # Vite config for demo dev server
+├── tests/
+│   └── index.test.ts       # Unit tests
+├── tsdown.config.ts        # Library build config
+├── vite.config.ts          # Vite+ unified config
+├── tsconfig.json           # TypeScript config
+└── package.json
+```
+
+---
+
+## 💡 Acknowledgements
+
+This project was initially inspired by [web-haptics](https://github.com/lochie/web-haptics) by [@lochie](https://github.com/lochie).
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) guide for details.
+
+---
+
+## 📄 License
+
+This project is licensed under the **MIT License** — feel free to use it for both personal and commercial purposes. See the [LICENSE](LICENSE) file for details.
+
+---
+
+<p align="center">
+  Built with ❤️ by <a href="https://github.com/sumitsahoo">Sumit Sahoo</a>
+</p>

package/dist/index.d.mts

@@ -0,0 +1,151 @@
+//#region src/core/easings.d.ts
+declare const easings: {
+  readonly linear: (t: number) => number;
+  readonly easeIn: (t: number) => number;
+  readonly easeOut: (t: number) => number;
+  readonly easeInOut: (t: number) => number;
+  readonly bounce: (t: number) => number;
+  readonly spring: (t: number) => number;
+};
+//#endregion
+//#region src/core/types.d.ts
+interface Vibration {
+  duration: number;
+  intensity?: number;
+  delay?: number;
+}
+type HapticPattern = number[] | Vibration[];
+type EasingFn = (t: number) => number;
+type ImpulseType = "tick" | "tap" | "thud" | "click" | "snap" | "buzz" | "confirm" | "harsh";
+interface HapticPreset {
+  pattern: Vibration[];
+  description?: string;
+  /** Number of iOS switch-checkbox toggles to fire for this preset. */
+  iosTicks?: number;
+  /** Milliseconds between iOS ticks. Defaults to IOS_GAP (55 ms). */
+  iosTickGap?: number;
+  /** Audio impulse type to play alongside the haptic. */
+  impulse?: ImpulseType;
+  /** Easing curve applied to multi-step patterns. */
+  easing?: keyof typeof easings;
+}
+type HapticInput = number | string | HapticPattern | HapticPreset;
+interface TriggerOptions {
+  intensity?: number;
+  audio?: boolean;
+}
+interface HapticEngineOptions {
+  debug?: boolean;
+  /** Minimum ms between trigger() calls. Default 25. */
+  throttleMs?: number;
+  /** Enable audio impulse layer. Default true. */
+  audioLayer?: boolean;
+  /** Master gain for audio impulses (0-1). Default 0.6. */
+  audioGain?: number;
+}
+interface SequenceStep {
+  preset: string;
+  delay?: number;
+  intensity?: number;
+}
+interface SequenceOptions {
+  repeat?: number;
+  repeatGap?: number;
+}
+interface DragHapticsOptions {
+  /** Minimum px moved since last fire to trigger next haptic (default: 18). */
+  fireDist?: number;
+  /** Audio impulse type for drag ticks (default: 'tick'). */
+  impulse?: ImpulseType;
+  /** Haptic/audio intensity 0-1 (default: 0.6). */
+  intensity?: number;
+  /** Callback fired on each drag tick with current velocity and tick count. */
+  onTick?: (velocity: number, ticks: number) => void;
+}
+//#endregion
+//#region src/core/presets.d.ts
+declare const presets: Record<string, HapticPreset>;
+//#endregion
+//#region src/interactions/drag-haptics.d.ts
+declare class DragHaptics {
+  private engine;
+  private opts;
+  curX: number;
+  curY: number;
+  private lastFireX;
+  private lastFireY;
+  private lastFireT;
+  private active;
+  private tickCount;
+  private cleanup;
+  /** Set during a touch sequence to prevent mouse handlers from double-firing. */
+  private touchActive;
+  constructor(engine: HapticEngine, options?: DragHapticsOptions);
+  /** Attach drag-haptic listeners to an element. Returns an unbind function. */
+  bind(element: HTMLElement): () => void;
+  private distFromLastFire;
+  /** Unbind all elements and stop tracking. */
+  destroyAll(): void;
+}
+//#endregion
+//#region src/haptic-engine.d.ts
+declare class HapticEngine {
+  private platform;
+  private iosPool;
+  private audio;
+  private useAudio;
+  private throttleMs;
+  private enabled;
+  private lastTriggerTime;
+  private activeAbort;
+  /** True if the device supports Android-style navigator.vibrate(). */
+  static readonly supportsVibration: boolean;
+  /** True if the device supports iOS switch-checkbox haptics. */
+  static readonly supportsIOSHaptics: boolean;
+  /** True if any form of haptic feedback is available. */
+  static readonly isSupported: boolean;
+  constructor(options?: HapticEngineOptions);
+  /**
+   * Fire a haptic + audio pattern. Input can be a preset name, duration (ms),
+   * Vibration[], number[] (alternating on/off), or a HapticPreset object.
+   */
+  trigger(input?: HapticInput, options?: TriggerOptions): Promise<void>;
+  /** Play an audio impulse. Set force=true to bypass the audio-enabled toggle. */
+  fireImpulse(type: ImpulseType, intensity: number, force?: boolean): void;
+  /** Fire a single platform haptic tick (short vibrate or single iOS switch toggle). */
+  fireHapticTick(intensity: number): void;
+  /**
+   * Fire a drag-optimized haptic tick. Skips cancel()/vibrate(0) overhead.
+   * Android: velocity scales pulse duration (12-25ms) and count (1-3 taps).
+   * iOS: single switch toggle (requires user activation to produce Taptic).
+   */
+  fireDragTick(intensity: number, velocity: number): void;
+  /** Fire a drag tick only on Android (vibration platform). No-op on iOS. */
+  fireDragTickIfVibration(intensity: number, velocity: number): void;
+  /** Play a sequence of preset steps with optional delays and repeats. */
+  sequence(steps: SequenceStep[], options?: SequenceOptions): Promise<void>;
+  /** Create a DragHaptics instance bound to this engine. */
+  drag(options?: DragHapticsOptions): DragHaptics;
+  /** Cancel any in-progress pattern or vibration. */
+  cancel(): void;
+  setEnabled(e: boolean): void;
+  get isEnabled(): boolean;
+  setAudioLayer(e: boolean): void;
+  setAudioGain(g: number): void;
+  setThrottle(ms: number): void;
+  registerPreset(name: string, preset: HapticPreset): void;
+  /** Clean up all resources (audio context, iOS DOM elements). */
+  destroy(): void;
+  /** Resolve any HapticInput into a Vibration[] and optional preset metadata. */
+  private resolveInput;
+  private fireAndroid;
+  private fireIOS;
+  /** Cancellable setTimeout wrapped in a Promise. */
+  private sleep;
+}
+/** Get or create the shared default engine instance. */
+declare function getDefaultEngine(opts?: HapticEngineOptions): HapticEngine;
+/** Fire a one-shot haptic using the default engine. */
+declare function haptic(input?: HapticInput, options?: TriggerOptions): Promise<void>;
+//#endregion
+export { DragHaptics, type DragHapticsOptions, type EasingFn, HapticEngine, type HapticEngineOptions, type HapticInput, type HapticPattern, type HapticPreset, type ImpulseType, type SequenceOptions, type SequenceStep, type TriggerOptions, type Vibration, easings, getDefaultEngine, haptic, presets };