@flighthq/haptics 0.1.0

package/dist/haptics.d.ts

@@ -0,0 +1,15 @@
+import type { HapticImpactStyle, HapticNotificationType, HapticsBackend, HapticsCapabilities } from '@flighthq/types';
+export declare function cancelDeviceVibration(): boolean;
+export declare function createWebHapticsBackend(): HapticsBackend;
+export declare function getHapticsBackend(): HapticsBackend;
+export declare function getHapticsCapabilities(out: HapticsCapabilities): HapticsCapabilities;
+export declare function isHapticsSupported(): boolean;
+export declare function prepareHaptics(): void;
+export declare function setHapticsBackend(backend: HapticsBackend | null): void;
+export declare function triggerHapticImpact(style: HapticImpactStyle, intensity?: number): boolean;
+export declare function triggerHapticNotification(type: HapticNotificationType): boolean;
+export declare function triggerHapticSelection(): boolean;
+export declare function vibrateDevice(durationMs: number): boolean;
+export declare function vibrateDevicePattern(pattern: Readonly<number[]>): boolean;
+export declare function vibrateDeviceWaveform(timings: Readonly<number[]>, amplitudes: Readonly<number[]>, repeat?: number): boolean;
+//# sourceMappingURL=haptics.d.ts.map

package/dist/haptics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"haptics.d.ts","sourceRoot":"","sources":["../src/haptics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAGtH,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C;AAKD,wBAAgB,uBAAuB,IAAI,cAAc,CA8CxD;AAGD,wBAAgB,iBAAiB,IAAI,cAAc,CAGlD;AAGD,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,mBAAmB,GAAG,mBAAmB,CAEpF;AAGD,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAID,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAGD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,IAAI,CAEtE;AAID,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,iBAAiB,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAIzF;AAID,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAE/E;AAGD,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAGD,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEzD;AAID,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,OAAO,CAGzE;AAOD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,EAC3B,UAAU,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,EAC9B,MAAM,SAAK,GACV,OAAO,CAOT"}

package/dist/haptics.js

@@ -0,0 +1,133 @@
+// Cancels any in-progress device vibration. Returns false when haptics are unavailable.
+export function cancelDeviceVibration() {
+    return getHapticsBackend().cancel();
+}
+// Builds the default web backend over navigator.vibrate. Every method returns false when the Vibration
+// API is absent (jsdom, desktop browsers) or the call fails, rather than throwing. Web vibration is a
+// coarse approximation of native haptics: it can only buzz the motor for a duration/pattern.
+export function createWebHapticsBackend() {
+    return {
+        cancel() {
+            return webVibrate(0);
+        },
+        capabilities(out) {
+            const supported = typeof navigator !== 'undefined' && typeof navigator.vibrate === 'function';
+            out.amplitudeControl = false;
+            out.customEvents = false;
+            out.intensity = false;
+            out.patterns = supported;
+            out.supported = supported;
+            return out;
+        },
+        impact(style, intensity) {
+            const base = style === 'heavy' || style === 'rigid' ? 30 : style === 'medium' ? 20 : style === 'soft' ? 25 : 10;
+            const ms = intensity !== undefined ? Math.round(base * Math.max(0, Math.min(1, intensity))) : base;
+            return webVibrate(ms);
+        },
+        isSupported() {
+            return typeof navigator !== 'undefined' && typeof navigator.vibrate === 'function';
+        },
+        notification(type) {
+            const pattern = type === 'error' ? [20, 60, 20] : type === 'warning' ? [20, 60, 20, 60] : [15, 50, 15];
+            return webVibrate(pattern);
+        },
+        prepare() {
+            // No-op on web; native backends may pre-allocate feedback generators to reduce latency.
+        },
+        selection() {
+            return webVibrate(5);
+        },
+        vibrate(durationMs) {
+            return webVibrate(durationMs);
+        },
+        vibratePattern(pattern) {
+            if (pattern.length === 0)
+                return false;
+            return webVibrate(pattern);
+        },
+        vibrateWaveform(timings, _amplitudes, repeat) {
+            // Web backend ignores amplitudes; falls back to vibratePattern. repeat is unsupported on web.
+            if (timings.length === 0)
+                return false;
+            void repeat;
+            return webVibrate(timings);
+        },
+    };
+}
+// The active haptics backend, or a lazily-created web default. There is always a backend.
+export function getHapticsBackend() {
+    if (_backend === null)
+        _backend = createWebHapticsBackend();
+    return _backend;
+}
+// Fills out with the capabilities of the active HapticsBackend. Returns the same out object.
+export function getHapticsCapabilities(out) {
+    return getHapticsBackend().capabilities(out);
+}
+// Returns true if the active backend reports that haptics are available on the current device.
+export function isHapticsSupported() {
+    return getHapticsBackend().isSupported();
+}
+// Warm-up hint to reduce first-trigger latency (mirrors UIFeedbackGenerator.prepare). No-op on
+// backends that do not support pre-allocation. Always safe to call.
+export function prepareHaptics() {
+    getHapticsBackend().prepare?.();
+}
+// Installs a native host haptics backend; pass null to fall back to the web default.
+export function setHapticsBackend(backend) {
+    _backend = backend;
+}
+// Triggers a physical impact at the given style, with optional continuous intensity (0..1).
+// Intensity defaults to 1 when omitted. Returns false when haptics are unavailable.
+export function triggerHapticImpact(style, intensity) {
+    // Resolve the documented default here so every backend receives a concrete intensity; a native
+    // backend must not have to reinterpret `undefined` as full strength on its own.
+    return getHapticsBackend().impact(style, intensity ?? 1);
+}
+// Triggers a semantic notification cue ('success' | 'warning' | 'error').
+// Returns false when haptics are unavailable.
+export function triggerHapticNotification(type) {
+    return getHapticsBackend().notification(type);
+}
+// Triggers a light selection tick. Returns false when haptics are unavailable.
+export function triggerHapticSelection() {
+    return getHapticsBackend().selection();
+}
+// Vibrates the device for the given duration in milliseconds. Returns false when unavailable or denied.
+export function vibrateDevice(durationMs) {
+    return getHapticsBackend().vibrate(durationMs);
+}
+// Vibrates the device using a pattern array [onMs, offMs, onMs, ...] matching the Web Vibration API.
+// Returns false on empty pattern or when haptics are unavailable.
+export function vibrateDevicePattern(pattern) {
+    if (pattern.length === 0)
+        return false;
+    return getHapticsBackend().vibratePattern(pattern);
+}
+// Vibrates using an amplitude-aware waveform (maps to Android VibrationEffect.createWaveform).
+// timings and amplitudes must have equal length; amplitudes are 0..255 (per Android convention).
+// repeat is the index into timings at which to loop, or -1 (default) for no repeat.
+// Backends that lack native waveform support fall back to vibratePattern(timings).
+// Returns false on empty timings or when haptics are unavailable.
+export function vibrateDeviceWaveform(timings, amplitudes, repeat = -1) {
+    const backend = getHapticsBackend();
+    if (timings.length === 0)
+        return false;
+    if (backend.vibrateWaveform !== undefined) {
+        return backend.vibrateWaveform(timings, amplitudes, repeat);
+    }
+    return backend.vibratePattern(timings);
+}
+let _backend = null;
+function webVibrate(pattern) {
+    if (typeof navigator === 'undefined' || !('vibrate' in navigator) || typeof navigator.vibrate !== 'function') {
+        return false;
+    }
+    try {
+        return navigator.vibrate(pattern);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=haptics.js.map

package/dist/haptics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"haptics.js","sourceRoot":"","sources":["../src/haptics.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './haptics';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './haptics';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@flighthq/haptics",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/types": "0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Haptic feedback (vibrate, impact, notification, selection) over a swappable web/native backend",
+  "sideEffects": false
+}

package/src/haptics.test.ts

@@ -0,0 +1,340 @@
+import type { HapticImpactStyle, HapticNotificationType, HapticsBackend, HapticsCapabilities } from '@flighthq/types';
+
+import {
+  cancelDeviceVibration,
+  createWebHapticsBackend,
+  getHapticsBackend,
+  getHapticsCapabilities,
+  isHapticsSupported,
+  prepareHaptics,
+  setHapticsBackend,
+  triggerHapticImpact,
+  triggerHapticNotification,
+  triggerHapticSelection,
+  vibrateDevice,
+  vibrateDevicePattern,
+  vibrateDeviceWaveform,
+} from './haptics';
+
+function makeCapabilities(overrides: Partial<HapticsCapabilities> = {}): HapticsCapabilities {
+  return {
+    amplitudeControl: false,
+    customEvents: false,
+    intensity: false,
+    patterns: false,
+    supported: false,
+    ...overrides,
+  };
+}
+
+function fakeBackend(): HapticsBackend & {
+  cancelCount: number;
+  duration: number;
+  lastPattern: Readonly<number[]> | null;
+  lastWaveform: { amplitudes: Readonly<number[]>; repeat: number | undefined; timings: Readonly<number[]> } | null;
+  prepared: number;
+  style: HapticImpactStyle | null;
+  styleIntensity: number | undefined;
+  type: HapticNotificationType | null;
+  selections: number;
+} {
+  return {
+    cancelCount: 0,
+    duration: -1,
+    lastPattern: null,
+    lastWaveform: null,
+    prepared: 0,
+    style: null,
+    styleIntensity: undefined,
+    type: null,
+    selections: 0,
+    cancel() {
+      this.cancelCount += 1;
+      return true;
+    },
+    capabilities(out: HapticsCapabilities): HapticsCapabilities {
+      out.amplitudeControl = true;
+      out.customEvents = false;
+      out.intensity = true;
+      out.patterns = true;
+      out.supported = true;
+      return out;
+    },
+    impact(style: HapticImpactStyle, intensity?: number) {
+      this.style = style;
+      this.styleIntensity = intensity;
+      return true;
+    },
+    isSupported() {
+      return true;
+    },
+    notification(type: HapticNotificationType) {
+      this.type = type;
+      return true;
+    },
+    prepare() {
+      this.prepared += 1;
+    },
+    selection() {
+      this.selections += 1;
+      return true;
+    },
+    vibrate(durationMs: number) {
+      this.duration = durationMs;
+      return true;
+    },
+    vibratePattern(pattern: Readonly<number[]>) {
+      this.lastPattern = pattern;
+      return true;
+    },
+    vibrateWaveform(timings: Readonly<number[]>, amplitudes: Readonly<number[]>, repeat?: number) {
+      this.lastWaveform = { amplitudes, repeat, timings };
+      return true;
+    },
+  };
+}
+
+afterEach(() => setHapticsBackend(null));
+
+describe('cancelDeviceVibration', () => {
+  it('forwards to backend cancel', () => {
+    const backend = fakeBackend();
+    setHapticsBackend(backend);
+    expect(cancelDeviceVibration()).toBe(true);
+    expect(backend.cancelCount).toBe(1);
+  });
+
+  it('returns false when haptics unavailable (jsdom)', () => {
+    expect(cancelDeviceVibration()).toBe(false);
+  });
+});
+
+describe('createWebHapticsBackend', () => {
+  it('returns false for every method without throwing when vibrate is unavailable (jsdom)', () => {
+    const backend = createWebHapticsBackend();
+    expect(backend.vibrate(10)).toBe(false);
+    expect(backend.impact('heavy')).toBe(false);
+    expect(backend.impact('rigid')).toBe(false);
+    expect(backend.impact('soft')).toBe(false);
+    expect(backend.notification('error')).toBe(false);
+    expect(backend.selection()).toBe(false);
+    expect(backend.vibratePattern([100, 50, 100])).toBe(false);
+    expect(backend.cancel()).toBe(false);
+    expect(backend.isSupported()).toBe(false);
+  });
+
+  it('returns false for empty pattern without throwing', () => {
+    const backend = createWebHapticsBackend();
+    expect(backend.vibratePattern([])).toBe(false);
+  });
+
+  it('returns false for waveform with empty timings', () => {
+    const backend = createWebHapticsBackend();
+    expect(backend.vibrateWaveform!([], [], undefined)).toBe(false);
+  });
+
+  it('fills capabilities for web (no vibrate)', () => {
+    const backend = createWebHapticsBackend();
+    const out = makeCapabilities();
+    backend.capabilities(out);
+    expect(out.supported).toBe(false);
+    expect(out.patterns).toBe(false);
+    expect(out.intensity).toBe(false);
+    expect(out.amplitudeControl).toBe(false);
+    expect(out.customEvents).toBe(false);
+  });
+
+  it('prepare is a no-op and does not throw', () => {
+    const backend = createWebHapticsBackend();
+    expect(() => backend.prepare!()).not.toThrow();
+  });
+});
+
+describe('getHapticsBackend', () => {
+  it('falls back to a web backend', () => {
+    expect(getHapticsBackend()).not.toBeNull();
+  });
+
+  it('returns the registered backend', () => {
+    const backend = fakeBackend();
+    setHapticsBackend(backend);
+    expect(getHapticsBackend()).toBe(backend);
+  });
+});
+
+describe('getHapticsCapabilities', () => {
+  it('fills out via the fake backend', () => {
+    const backend = fakeBackend();
+    setHapticsBackend(backend);
+    const out = makeCapabilities();
+    const result = getHapticsCapabilities(out);
+    expect(result).toBe(out);
+    expect(out.supported).toBe(true);
+    expect(out.intensity).toBe(true);
+    expect(out.patterns).toBe(true);
+    expect(out.amplitudeControl).toBe(true);
+    expect(out.customEvents).toBe(false);
+  });
+
+  it('fills out from web backend when no backend is set', () => {
+    const out = makeCapabilities();
+    getHapticsCapabilities(out);
+    expect(out.supported).toBe(false);
+  });
+});
+
+describe('isHapticsSupported', () => {
+  it('returns true from fake backend', () => {
+    setHapticsBackend(fakeBackend());
+    expect(isHapticsSupported()).toBe(true);
+  });
+
+  it('returns false when vibrate is unavailable (jsdom)', () => {
+    expect(isHapticsSupported()).toBe(false);
+  });
+});
+
+describe('prepareHaptics', () => {
+  it('calls prepare on backends that provide it', () => {
+    const backend = fakeBackend();
+    setHapticsBackend(backend);
+    prepareHaptics();
+    expect(backend.prepared).toBe(1);
+  });
+
+  it('does not throw when backend has no prepare method', () => {
+    const backend = fakeBackend();
+    // Simulate a backend with no optional prepare
+    (backend as HapticsBackend & { prepare?: () => void }).prepare = undefined;
+    setHapticsBackend(backend);
+    expect(() => prepareHaptics()).not.toThrow();
+  });
+});
+
+describe('setHapticsBackend', () => {
+  it('clears back to the web fallback when passed null', () => {
+    setHapticsBackend(fakeBackend());
+    setHapticsBackend(null);
+    expect(getHapticsBackend()).not.toBeNull();
+  });
+});
+
+describe('triggerHapticImpact', () => {
+  it('forwards style to the active backend and defaults intensity to 1', () => {
+    const backend = fakeBackend();
+    setHapticsBackend(backend);
+    expect(triggerHapticImpact('medium')).toBe(true);
+    expect(backend.style).toBe('medium');
+    expect(backend.styleIntensity).toBe(1);
+  });
+
+  it('forwards intensity to the backend', () => {
+    const backend = fakeBackend();
+    setHapticsBackend(backend);
+    triggerHapticImpact('heavy', 0.5);
+    expect(backend.style).toBe('heavy');
+    expect(backend.styleIntensity).toBe(0.5);
+  });
+
+  it('supports rigid and soft styles', () => {
+    const backend = fakeBackend();
+    setHapticsBackend(backend);
+    triggerHapticImpact('rigid');
+    expect(backend.style).toBe('rigid');
+    triggerHapticImpact('soft');
+    expect(backend.style).toBe('soft');
+  });
+
+  it('web backend clamps intensity to 0..1', () => {
+    const webBackend = createWebHapticsBackend();
+    // Should not throw on out-of-range intensity even if vibrate returns false
+    expect(() => webBackend.impact('heavy', 2)).not.toThrow();
+    expect(() => webBackend.impact('heavy', -0.5)).not.toThrow();
+  });
+});
+
+describe('triggerHapticNotification', () => {
+  it('forwards type to the active backend', () => {
+    const backend = fakeBackend();
+    setHapticsBackend(backend);
+    expect(triggerHapticNotification('success')).toBe(true);
+    expect(backend.type).toBe('success');
+  });
+});
+
+describe('triggerHapticSelection', () => {
+  it('triggers a selection on the active backend', () => {
+    const backend = fakeBackend();
+    setHapticsBackend(backend);
+    expect(triggerHapticSelection()).toBe(true);
+    expect(backend.selections).toBe(1);
+  });
+});
+
+describe('vibrateDevice', () => {
+  it('forwards duration to the active backend', () => {
+    const backend = fakeBackend();
+    setHapticsBackend(backend);
+    expect(vibrateDevice(42)).toBe(true);
+    expect(backend.duration).toBe(42);
+  });
+});
+
+describe('vibrateDevicePattern', () => {
+  it('forwards pattern to the active backend', () => {
+    const backend = fakeBackend();
+    setHapticsBackend(backend);
+    const pattern = [100, 50, 100] as const;
+    expect(vibrateDevicePattern(pattern)).toBe(true);
+    expect(backend.lastPattern).toEqual(pattern);
+  });
+
+  it('returns false for empty pattern', () => {
+    const backend = fakeBackend();
+    setHapticsBackend(backend);
+    expect(vibrateDevicePattern([])).toBe(false);
+  });
+
+  it('returns false when haptics unavailable (jsdom)', () => {
+    expect(vibrateDevicePattern([100, 50, 100])).toBe(false);
+  });
+});
+
+describe('vibrateDeviceWaveform', () => {
+  it('calls vibrateWaveform on backends that support it', () => {
+    const backend = fakeBackend();
+    setHapticsBackend(backend);
+    const timings = [100, 50, 100] as const;
+    const amplitudes = [255, 0, 128] as const;
+    expect(vibrateDeviceWaveform(timings, amplitudes, 0)).toBe(true);
+    expect(backend.lastWaveform).toEqual({ timings, amplitudes, repeat: 0 });
+  });
+
+  it('defaults repeat to -1', () => {
+    const backend = fakeBackend();
+    setHapticsBackend(backend);
+    vibrateDeviceWaveform([100], [255]);
+    expect(backend.lastWaveform?.repeat).toBe(-1);
+  });
+
+  it('falls back to vibratePattern when backend lacks vibrateWaveform', () => {
+    const backend = fakeBackend();
+    (backend as HapticsBackend).vibrateWaveform = undefined;
+    setHapticsBackend(backend);
+    const timings = [100, 50] as const;
+    const amplitudes = [255, 0] as const;
+    expect(vibrateDeviceWaveform(timings, amplitudes)).toBe(true);
+    expect(backend.lastPattern).toEqual(timings);
+    expect(backend.lastWaveform).toBeNull();
+  });
+
+  it('returns false for empty timings', () => {
+    const backend = fakeBackend();
+    setHapticsBackend(backend);
+    expect(vibrateDeviceWaveform([], [], undefined)).toBe(false);
+  });
+
+  it('returns false when haptics unavailable (jsdom)', () => {
+    expect(vibrateDeviceWaveform([100], [255])).toBe(false);
+  });
+});