@hapticjs/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,384 @@
+export { accessibility, gaming, notifications, presets, system, ui } from './presets/index.js';
+
+/** A single step in a haptic sequence */
+interface HapticStep {
+    type: 'vibrate' | 'pause';
+    /** Duration in milliseconds */
+    duration: number;
+    /** Intensity from 0.0 to 1.0 (0 = off, 1 = max) */
+    intensity: number;
+    /** Optional easing for intensity ramps */
+    easing?: EasingFunction;
+}
+/** A complete haptic pattern — a named sequence of steps */
+interface HapticPattern {
+    name?: string;
+    steps: HapticStep[];
+    metadata?: Record<string, unknown>;
+}
+/** Easing function type for smooth transitions */
+type EasingFunction = 'linear' | 'ease-in' | 'ease-out' | 'ease-in-out';
+/** Semantic impact styles matching iOS UIImpactFeedbackGenerator */
+type ImpactStyle = 'light' | 'medium' | 'heavy' | 'rigid' | 'soft';
+/** Semantic notification types */
+type NotificationType = 'success' | 'warning' | 'error';
+/** All built-in semantic effect names */
+type SemanticEffect = 'tap' | 'doubleTap' | 'longPress' | 'success' | 'warning' | 'error' | 'selection' | 'toggle' | ImpactStyle;
+
+/** Capabilities a haptic adapter supports */
+interface AdapterCapabilities {
+    /** Number of discrete intensity levels (1 = on/off only, 100+ = fine-grained) */
+    maxIntensityLevels: number;
+    /** Minimum pulse duration in ms */
+    minDuration: number;
+    /** Maximum continuous duration in ms */
+    maxDuration: number;
+    /** Whether the adapter can play multi-step patterns natively */
+    supportsPattern: boolean;
+    /** Whether the adapter can vary intensity (not just on/off) */
+    supportsIntensity: boolean;
+    /** Whether the adapter has dual motors (gamepad-style) */
+    dualMotor: boolean;
+}
+/** Interface all haptic adapters must implement */
+interface HapticAdapter {
+    readonly name: string;
+    readonly supported: boolean;
+    /** Get the capabilities of this adapter */
+    capabilities(): AdapterCapabilities;
+    /** Fire a single haptic pulse */
+    pulse(intensity: number, duration: number): Promise<void>;
+    /** Play a sequence of haptic steps */
+    playSequence(steps: HapticStep[]): Promise<void>;
+    /** Cancel any ongoing haptic effect */
+    cancel(): void;
+    /** Clean up resources */
+    dispose(): void;
+}
+
+/** Visual fallback style when haptics are unavailable */
+type VisualFallbackStyle = 'flash' | 'shake' | 'pulse';
+/** Fallback configuration for non-haptic feedback */
+interface FallbackConfig {
+    type: 'none' | 'visual' | 'audio' | 'both';
+    visual?: {
+        /** Element to animate */
+        element?: HTMLElement;
+        /** CSS class to toggle */
+        className?: string;
+        /** Animation style */
+        style?: VisualFallbackStyle;
+    };
+    audio?: {
+        enabled: boolean;
+        /** Volume from 0 to 1 */
+        volume: number;
+    };
+}
+/** Main configuration for the haptic engine */
+interface HapticConfig {
+    /** Explicitly set an adapter (overrides auto-detection) */
+    adapter?: HapticAdapter;
+    /** Global intensity multiplier (0.0 to 1.0) */
+    intensity: number;
+    /** Whether haptics are enabled */
+    enabled: boolean;
+    /** Fallback when haptics are unavailable */
+    fallback: FallbackConfig;
+    /** Respect system haptic settings */
+    respectSystemSettings: boolean;
+}
+
+/** HPL Token types */
+type HPLTokenType = 'LIGHT' | 'MEDIUM' | 'HEAVY' | 'PAUSE' | 'TAP' | 'SUSTAIN' | 'GROUP_START' | 'GROUP_END' | 'REPEAT';
+/** A single HPL token */
+interface HPLToken {
+    type: HPLTokenType;
+    value: string;
+    /** For REPEAT tokens, the repeat count */
+    repeatCount?: number;
+}
+/** AST node types */
+type HPLNodeType = 'vibrate' | 'pause' | 'tap' | 'sustain' | 'group' | 'sequence';
+/** Base AST node */
+interface HPLBaseNode {
+    type: HPLNodeType;
+}
+/** Vibrate node — ~, #, or @ */
+interface HPLVibrateNode extends HPLBaseNode {
+    type: 'vibrate';
+    intensity: number;
+    duration: number;
+}
+/** Pause node — . */
+interface HPLPauseNode extends HPLBaseNode {
+    type: 'pause';
+    duration: number;
+}
+/** Tap node — | */
+interface HPLTapNode extends HPLBaseNode {
+    type: 'tap';
+    duration: number;
+    intensity: number;
+}
+/** Sustain node — - */
+interface HPLSustainNode extends HPLBaseNode {
+    type: 'sustain';
+    extension: number;
+}
+/** Group node — [...] with optional repeat */
+interface HPLGroupNode extends HPLBaseNode {
+    type: 'group';
+    children: HPLNode[];
+    repeat: number;
+}
+/** Sequence node — the root */
+interface HPLSequenceNode extends HPLBaseNode {
+    type: 'sequence';
+    children: HPLNode[];
+}
+/** Any HPL AST node */
+type HPLNode = HPLVibrateNode | HPLPauseNode | HPLTapNode | HPLSustainNode | HPLGroupNode | HPLSequenceNode;
+
+/**
+ * Fluent builder for composing haptic patterns programmatically.
+ *
+ * Usage:
+ *   const pattern = new PatternComposer()
+ *     .tap(0.5)
+ *     .pause(100)
+ *     .ramp(0.2, 1.0, 300)
+ *     .buzz(200)
+ *     .build();
+ */
+declare class PatternComposer {
+    private steps;
+    private _onPlay?;
+    /** Register a play callback (used by HapticEngine) */
+    onPlay(fn: (steps: HapticStep[]) => Promise<void>): this;
+    /** Add a short tap vibration */
+    tap(intensity?: number): this;
+    /** Add a vibration with specified duration and intensity */
+    vibrate(duration: number, intensity?: number): this;
+    /** Add a buzz (medium-length vibration) */
+    buzz(duration?: number, intensity?: number): this;
+    /** Add a pause */
+    pause(duration?: number): this;
+    /** Add an intensity ramp from start to end intensity over duration */
+    ramp(startIntensity: number, endIntensity: number, duration: number, easing?: EasingFunction): this;
+    /** Add a pulse pattern (on-off-on-off) */
+    pulse(count: number, onDuration?: number, offDuration?: number, intensity?: number): this;
+    /** Repeat the entire current sequence N times */
+    repeat(times: number): this;
+    /** Build and return the step array */
+    build(): HapticStep[];
+    /** Build and immediately play the pattern */
+    play(): Promise<void>;
+    /** Reset the composer */
+    clear(): this;
+    /** Get total duration in ms */
+    get duration(): number;
+}
+
+/**
+ * The main haptic engine — orchestrates adapters, patterns, and fallbacks.
+ *
+ * Usage:
+ *   const engine = HapticEngine.create();
+ *   engine.tap();
+ *   engine.success();
+ *   engine.play('~~..##..@@');
+ */
+declare class HapticEngine {
+    private adapter;
+    private config;
+    private adaptive;
+    private fallback;
+    constructor(config?: Partial<HapticConfig>);
+    /** Create a new engine with auto-detected adapter */
+    static create(config?: Partial<HapticConfig>): HapticEngine;
+    /** Light tap feedback */
+    tap(intensity?: number): Promise<void>;
+    /** Double tap */
+    doubleTap(intensity?: number): Promise<void>;
+    /** Long press feedback */
+    longPress(intensity?: number): Promise<void>;
+    /** Success notification */
+    success(): Promise<void>;
+    /** Warning notification */
+    warning(): Promise<void>;
+    /** Error notification */
+    error(): Promise<void>;
+    /** Selection change feedback */
+    selection(): Promise<void>;
+    /** Toggle feedback */
+    toggle(on: boolean): Promise<void>;
+    /** Impact with style (matches iOS UIImpactFeedbackGenerator) */
+    impact(style?: ImpactStyle): Promise<void>;
+    /** Vibrate for a specified duration */
+    vibrate(duration: number, intensity?: number): Promise<void>;
+    /**
+     * Play a haptic pattern.
+     * Accepts:
+     *   - HPL string: "~~..##..@@"
+     *   - HapticPattern object
+     *   - Raw HapticStep array
+     */
+    play(pattern: string | HapticPattern | HapticStep[]): Promise<void>;
+    /** Create a new pattern composer */
+    compose(): PatternComposer;
+    /** Update engine configuration */
+    configure(config: Partial<HapticConfig>): void;
+    /** Check if haptics are supported on this device */
+    get isSupported(): boolean;
+    /** Get the current adapter name */
+    get adapterName(): string;
+    /** Cancel any ongoing haptic effect */
+    cancel(): void;
+    /** Clean up resources */
+    dispose(): void;
+    private _playSteps;
+}
+
+/**
+ * Adapts ideal haptic patterns to what the device can actually produce.
+ * Handles intensity quantization, duration clamping, and step merging.
+ */
+declare class AdaptiveEngine {
+    adapt(steps: HapticStep[], capabilities: AdapterCapabilities): HapticStep[];
+    private _adaptStep;
+}
+
+/**
+ * Provides visual/audio fallback when haptic hardware is unavailable.
+ */
+declare class FallbackManager {
+    private config;
+    constructor(config: FallbackConfig);
+    updateConfig(config: FallbackConfig): void;
+    /** Execute fallback feedback for the given steps */
+    execute(steps: HapticStep[]): Promise<void>;
+    private _visualFallback;
+    private _audioFallback;
+}
+
+/**
+ * Auto-detect the best available haptic adapter for the current platform.
+ */
+declare function detectAdapter(): HapticAdapter;
+
+/**
+ * No-op adapter — used in SSR, Node, or when no haptic hardware is available.
+ * Silently accepts all calls without doing anything.
+ */
+declare class NoopAdapter implements HapticAdapter {
+    readonly name = "noop";
+    readonly supported = false;
+    capabilities(): AdapterCapabilities;
+    pulse(_intensity: number, _duration: number): Promise<void>;
+    playSequence(_steps: HapticStep[]): Promise<void>;
+    cancel(): void;
+    dispose(): void;
+}
+
+/**
+ * Web Vibration API adapter.
+ * Uses navigator.vibrate() — supported on Android browsers.
+ * Intensity is simulated via PWM (rapid on/off) since the API only supports on/off.
+ */
+declare class WebVibrationAdapter implements HapticAdapter {
+    readonly name = "web-vibration";
+    readonly supported: boolean;
+    private _cancelled;
+    constructor();
+    capabilities(): AdapterCapabilities;
+    pulse(_intensity: number, duration: number): Promise<void>;
+    playSequence(steps: HapticStep[]): Promise<void>;
+    cancel(): void;
+    dispose(): void;
+    /** Convert steps to Vibration API pattern array */
+    private _toVibrationPattern;
+    /** Check if all steps can be played with native pattern (no intensity variation) */
+    private _canUseNativePattern;
+    /** Simulate lower intensity via pulse-width modulation */
+    private _pwmVibrate;
+}
+
+declare class HPLParserError extends Error {
+    constructor(message: string);
+}
+/**
+ * Recursive descent parser for the Haptic Pattern Language (HPL).
+ *
+ * Grammar:
+ *   Pattern   := Segment+
+ *   Segment   := Group | Atom
+ *   Group     := '[' Segment+ ']' Repeat?
+ *   Atom      := '~' | '#' | '@' | '.' | '|' | '-'
+ *   Repeat    := 'x' Number
+ */
+declare class HPLParser {
+    private tokens;
+    private pos;
+    parse(input: string): HPLSequenceNode;
+    private _parseSegments;
+    private _parseSegment;
+    private _parseGroup;
+    private _parseAtom;
+    private _makeVibrate;
+    private _makePause;
+    private _makeTap;
+    private _makeSustain;
+}
+/** Convenience function to parse an HPL string */
+declare function parseHPL(input: string): HPLSequenceNode;
+
+/**
+ * Compiles an HPL AST into a flat array of HapticSteps.
+ * Handles group expansion, sustain merging, and repeat unrolling.
+ */
+declare function compile(ast: HPLSequenceNode): HapticStep[];
+/**
+ * Optimize a step sequence by merging adjacent same-type steps.
+ */
+declare function optimizeSteps(steps: HapticStep[]): HapticStep[];
+
+declare class HPLTokenizerError extends Error {
+    readonly position: number;
+    constructor(message: string, position: number);
+}
+/** Tokenize an HPL pattern string into tokens */
+declare function tokenize(input: string): HPLToken[];
+
+/** Validate an HPL pattern string and return human-readable errors */
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+declare function validateHPL(input: string): ValidationResult;
+
+/** Platform detection utilities */
+interface PlatformInfo {
+    isWeb: boolean;
+    isNode: boolean;
+    isReactNative: boolean;
+    hasVibrationAPI: boolean;
+    hasGamepadAPI: boolean;
+    isIOS: boolean;
+    isAndroid: boolean;
+    isMobile: boolean;
+}
+declare function detectPlatform(): PlatformInfo;
+
+/**
+ * Pre-configured haptic engine singleton.
+ * Import and use directly for quick haptic feedback:
+ *
+ *   import { haptic } from '@hapticjs/core';
+ *   haptic.tap();
+ *   haptic.success();
+ *   haptic.play('~~..##..@@');
+ */
+declare const haptic: HapticEngine;
+
+export { type AdapterCapabilities, AdaptiveEngine, type EasingFunction, type FallbackConfig, FallbackManager, type HPLNode, type HPLNodeType, HPLParser, HPLParserError, type HPLToken, type HPLTokenType, HPLTokenizerError, type HapticAdapter, type HapticConfig, HapticEngine, type HapticPattern, type HapticStep, type ImpactStyle, NoopAdapter, type NotificationType, PatternComposer, type PlatformInfo, type SemanticEffect, type ValidationResult, type VisualFallbackStyle, WebVibrationAdapter, compile, detectAdapter, detectPlatform, haptic, optimizeSteps, parseHPL, tokenize, validateHPL };