bzzz 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pavle Lucic
+
+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,30 @@
+# bzzz
+
+Haptic feedback for the web. Native vibration + audio fallback.
+
+[![npm](https://img.shields.io/npm/v/bzzz)](https://www.npmjs.com/package/bzzz)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/bzzz)](https://bundlephobia.com/package/bzzz)
+
+## Install
+
+```bash
+npm install bzzz
+```
+
+## Usage
+
+```typescript
+import { haptics } from "bzzz";
+
+button.addEventListener("click", () => {
+  haptics.success();
+});
+```
+
+## Documentation
+
+[pavlito.github.io/bzzz](https://pavlito.github.io/bzzz)
+
+## License
+
+MIT

package/dist/chunk-RLTRZ2WN.mjs

@@ -0,0 +1,398 @@
+// src/capabilities.ts
+function getAudioContextConstructor() {
+  const runtime = globalThis;
+  return runtime.AudioContext ?? runtime.webkitAudioContext;
+}
+function isIOS() {
+  if (typeof navigator === "undefined") return false;
+  const ua = navigator.userAgent;
+  if (/iPad|iPhone|iPod/.test(ua)) return true;
+  if (navigator.maxTouchPoints > 1) {
+    if (navigator.platform === "MacIntel") return true;
+    const uad = navigator.userAgentData;
+    if (uad?.platform === "macOS") return true;
+  }
+  return false;
+}
+function hasVibrationHardware() {
+  if (typeof navigator === "undefined") return false;
+  if (typeof navigator.vibrate !== "function") return false;
+  if (typeof matchMedia !== "undefined" && matchMedia("(pointer: coarse)").matches) {
+    return true;
+  }
+  return false;
+}
+function prefersReducedMotion() {
+  if (typeof matchMedia === "undefined") return false;
+  return matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+function getCapabilityState() {
+  return {
+    haptics: hasVibrationHardware(),
+    audio: Boolean(getAudioContextConstructor()),
+    ios: isIOS(),
+    reducedMotion: prefersReducedMotion()
+  };
+}
+
+// src/patterns.ts
+var defaultPatterns = {
+  selection: [
+    { type: "pulse", duration: 8, intensity: 0.4 },
+    { type: "gap", duration: 12 },
+    { type: "pulse", duration: 10, intensity: 0.6 }
+  ],
+  success: [
+    { type: "pulse", duration: 15, intensity: 0.4 },
+    { type: "gap", duration: 40 },
+    { type: "pulse", duration: 25, intensity: 0.7 },
+    { type: "gap", duration: 60 },
+    { type: "pulse", duration: 35, intensity: 1 }
+  ],
+  error: [
+    { type: "pulse", duration: 30, intensity: 0.7 },
+    { type: "gap", duration: 30 },
+    { type: "pulse", duration: 30, intensity: 0.7 },
+    { type: "gap", duration: 30 },
+    { type: "pulse", duration: 35, intensity: 0.9 },
+    { type: "gap", duration: 30 },
+    { type: "pulse", duration: 40, intensity: 1 }
+  ],
+  toggle: [
+    { type: "pulse", duration: 12, intensity: 0.5 },
+    { type: "gap", duration: 24 },
+    { type: "pulse", duration: 18, intensity: 0.8 },
+    { type: "gap", duration: 24 },
+    { type: "pulse", duration: 12, intensity: 0.5 }
+  ],
+  snap: [
+    { type: "pulse", duration: 8, intensity: 0.3 },
+    { type: "gap", duration: 8 },
+    { type: "pulse", duration: 10, intensity: 0.5 },
+    { type: "gap", duration: 8 },
+    { type: "pulse", duration: 12, intensity: 0.7 },
+    { type: "gap", duration: 8 },
+    { type: "pulse", duration: 14, intensity: 0.9 },
+    { type: "gap", duration: 8 },
+    { type: "pulse", duration: 16, intensity: 1 }
+  ]
+};
+for (const pattern of Object.values(defaultPatterns)) {
+  Object.freeze(pattern);
+  for (const block of pattern) {
+    Object.freeze(block);
+  }
+}
+Object.freeze(defaultPatterns);
+function clonePattern(pattern) {
+  return pattern.map((block) => ({ ...block }));
+}
+
+// src/audio.ts
+var CLICK_DURATION = 5e-3;
+var CLICK_GAIN = 0.3;
+var FILTER_FREQ = 2200;
+var FILTER_Q = 3;
+var engine = null;
+function getAudioEngine() {
+  if (engine) return engine;
+  try {
+    let createClickBuffer2 = function() {
+      const buffer = ctx.createBuffer(1, bufferLength, ctx.sampleRate);
+      const data = buffer.getChannelData(0);
+      for (let i = 0; i < data.length; i++) {
+        const t = i / data.length;
+        const envelope = (1 - t) * (1 - t);
+        data[i] = (Math.random() * 2 - 1) * envelope;
+      }
+      return buffer;
+    }, playTap2 = function(startTime, intensity = 1) {
+      if (ctx.state === "suspended") {
+        ctx.resume().catch(() => void 0);
+      }
+      const level = Math.max(0, Math.min(1, intensity));
+      if (level === 0) return;
+      const buffer = createClickBuffer2();
+      const source = ctx.createBufferSource();
+      source.buffer = buffer;
+      const filter = ctx.createBiquadFilter();
+      filter.type = "lowpass";
+      filter.frequency.setValueAtTime(
+        FILTER_FREQ + (Math.random() - 0.5) * 400,
+        startTime
+      );
+      filter.Q.setValueAtTime(FILTER_Q, startTime);
+      const gain = ctx.createGain();
+      gain.gain.setValueAtTime(CLICK_GAIN * level, startTime);
+      source.connect(filter);
+      filter.connect(gain);
+      gain.connect(ctx.destination);
+      source.start(startTime);
+      source.stop(startTime + CLICK_DURATION);
+    };
+    var createClickBuffer = createClickBuffer2, playTap = playTap2;
+    const AC = globalThis.AudioContext ?? globalThis.webkitAudioContext;
+    if (!AC) return null;
+    const ctx = new AC();
+    const bufferLength = Math.ceil(CLICK_DURATION * ctx.sampleRate);
+    engine = { playTap: playTap2, context: ctx };
+    return engine;
+  } catch {
+    return null;
+  }
+}
+function resetAudioEngine() {
+  if (engine) {
+    try {
+      engine.context.close().catch(() => {
+      });
+    } catch {
+    }
+  }
+  engine = null;
+}
+
+// src/safari-haptics.ts
+var TAP_INTERVAL = 26;
+var label = null;
+function ensureDOM() {
+  if (label) return;
+  if (typeof document === "undefined") return;
+  label = document.createElement("label");
+  label.ariaHidden = "true";
+  Object.assign(label.style, {
+    position: "fixed",
+    left: "-9999px",
+    top: "-9999px",
+    opacity: "0.01",
+    pointerEvents: "none"
+  });
+  const input = document.createElement("input");
+  input.type = "checkbox";
+  input.setAttribute("switch", "");
+  input.ariaHidden = "true";
+  input.tabIndex = -1;
+  label.appendChild(input);
+  document.body.appendChild(label);
+}
+function triggerSafariHaptic() {
+  if (typeof document === "undefined") return;
+  ensureDOM();
+  label?.click();
+}
+var pendingTimers = [];
+function playSafariPattern(pattern) {
+  for (const id of pendingTimers) clearTimeout(id);
+  pendingTimers = [];
+  let cursorMs = 0;
+  const pulseTimes = [];
+  for (const block of pattern) {
+    if (block.type === "pulse" && block.duration >= 5) {
+      pulseTimes.push(cursorMs);
+    }
+    cursorMs += block.duration;
+  }
+  if (pulseTimes.length === 0) return;
+  triggerSafariHaptic();
+  for (let i = 1; i < pulseTimes.length; i++) {
+    const delay = Math.max(pulseTimes[i] - pulseTimes[0], i * TAP_INTERVAL);
+    pendingTimers.push(setTimeout(() => triggerSafariHaptic(), delay));
+  }
+}
+function destroySafariHaptic() {
+  for (const id of pendingTimers) clearTimeout(id);
+  pendingTimers = [];
+  if (label?.parentNode) label.parentNode.removeChild(label);
+  label = null;
+}
+
+// src/playback.ts
+var PWM_CYCLE = 20;
+function modulateVibration(duration, intensity) {
+  if (intensity >= 1) return [duration];
+  if (intensity <= 0) return [];
+  if (duration <= PWM_CYCLE) return [duration];
+  const onTime = Math.max(1, Math.round(PWM_CYCLE * intensity));
+  const offTime = PWM_CYCLE - onTime;
+  const result = [];
+  let remaining = duration;
+  while (remaining >= PWM_CYCLE) {
+    result.push(onTime, offTime);
+    remaining -= PWM_CYCLE;
+  }
+  if (remaining > 0) {
+    const remainOn = Math.min(remaining, onTime);
+    result.push(remainOn);
+    const remainOff = remaining - remainOn;
+    if (remainOff > 0) {
+      result.push(remainOff);
+    }
+  }
+  return result;
+}
+function toVibrationPattern(pattern) {
+  const result = [];
+  for (const block of pattern) {
+    if (block.type === "pulse") {
+      const intensity = block.intensity ?? 1;
+      const modulated = modulateVibration(block.duration, intensity);
+      if (modulated.length > 0) {
+        if (result.length > 0 && result.length % 2 === 1) {
+          result.push(0, ...modulated);
+        } else {
+          result.push(...modulated);
+        }
+      }
+    } else if (block.type === "gap") {
+      if (result.length === 0) continue;
+      if (result.length % 2 === 0) {
+        result[result.length - 1] += block.duration;
+      } else {
+        result.push(block.duration);
+      }
+    }
+  }
+  return result;
+}
+function playAudioClicks(pattern) {
+  const engine2 = getAudioEngine();
+  if (!engine2) return false;
+  const startTime = engine2.context.currentTime + 0.01;
+  let cursorMs = 0;
+  let scheduled = false;
+  for (const block of pattern) {
+    if (block.type === "pulse" && block.duration >= 5) {
+      engine2.playTap(startTime + cursorMs / 1e3, block.intensity ?? 1);
+      scheduled = true;
+    }
+    cursorMs += block.duration;
+  }
+  return scheduled;
+}
+function validatePattern(pattern) {
+  return pattern.map((b) => {
+    const duration = Math.max(0, Number.isFinite(b.duration) ? b.duration : 0);
+    if (b.type === "pulse") {
+      return {
+        type: "pulse",
+        duration,
+        intensity: b.intensity != null ? Math.max(0, Math.min(1, b.intensity)) : void 0
+      };
+    }
+    return { type: "gap", duration };
+  });
+}
+function playPattern(pattern, options) {
+  const capabilities = getCapabilityState();
+  if (capabilities.reducedMotion || options?.enabled === false) return { mode: "none" };
+  const validated = validatePattern(pattern);
+  const vibrationPattern = toVibrationPattern(validated);
+  if (capabilities.ios && validated.some((b) => b.type === "pulse" && b.duration >= 5)) {
+    playSafariPattern(validated);
+    try {
+      playAudioClicks(validated);
+    } catch {
+    }
+    return { mode: "haptics" };
+  }
+  if (vibrationPattern.length > 0 && capabilities.haptics && navigator.vibrate(vibrationPattern)) {
+    try {
+      playAudioClicks(validated);
+    } catch {
+    }
+    return { mode: "haptics" };
+  }
+  if (capabilities.audio) {
+    try {
+      const played = playAudioClicks(validated);
+      return { mode: played ? "audio" : "none" };
+    } catch {
+      return { mode: "none" };
+    }
+  }
+  return { mode: "none" };
+}
+
+// src/runtime.ts
+function createRegistry(overrides) {
+  const registry = /* @__PURE__ */ new Map();
+  for (const [name, pattern] of Object.entries(defaultPatterns)) {
+    registry.set(name, clonePattern(pattern));
+  }
+  if (overrides) {
+    for (const [name, pattern] of Object.entries(overrides)) {
+      registry.set(name, clonePattern(pattern));
+    }
+  }
+  return registry;
+}
+function resolvePattern(registry, nameOrPattern) {
+  if (typeof nameOrPattern !== "string") {
+    return clonePattern(nameOrPattern);
+  }
+  const pattern = registry.get(nameOrPattern);
+  if (!pattern) {
+    throw new Error(`Unknown haptics pattern: ${nameOrPattern}`);
+  }
+  return clonePattern(pattern);
+}
+var singletonEnabled = true;
+function playNamedPattern(name) {
+  return playPattern(clonePattern(defaultPatterns[name]), { enabled: singletonEnabled });
+}
+var haptics = {
+  selection: () => playNamedPattern("selection"),
+  success: () => playNamedPattern("success"),
+  error: () => playNamedPattern("error"),
+  toggle: () => playNamedPattern("toggle"),
+  snap: () => playNamedPattern("snap"),
+  play: (pattern) => playPattern(clonePattern(pattern), { enabled: singletonEnabled }),
+  getCapabilities: () => getCapabilityState(),
+  setEnabled: (enabled) => {
+    singletonEnabled = enabled;
+  },
+  isEnabled: () => singletonEnabled,
+  dispose: () => {
+    resetAudioEngine();
+    destroySafariHaptic();
+  }
+};
+function createHaptics(options = {}) {
+  const registry = createRegistry(options.patterns);
+  let enabled = true;
+  return {
+    play: (nameOrPattern) => playPattern(resolvePattern(registry, nameOrPattern), { enabled }),
+    register: (name, pattern) => {
+      registry.set(name, clonePattern(pattern));
+    },
+    getCapabilities: () => getCapabilityState(),
+    setEnabled: (value) => {
+      enabled = value;
+    },
+    isEnabled: () => enabled,
+    dispose: () => {
+      resetAudioEngine();
+      destroySafariHaptic();
+    }
+  };
+}
+function dispose() {
+  resetAudioEngine();
+  destroySafariHaptic();
+}
+function setEnabled(enabled) {
+  haptics.setEnabled(enabled);
+}
+function isEnabled() {
+  return haptics.isEnabled();
+}
+
+export {
+  getCapabilityState,
+  defaultPatterns,
+  haptics,
+  createHaptics,
+  dispose,
+  setEnabled,
+  isEnabled
+};

package/dist/index.d.mts

@@ -0,0 +1,124 @@
+import { C as CapabilityState, a as CreateHapticsOptions, H as HapticsInstance, b as HapticsApi } from './types-BRn0rP4m.mjs';
+export { G as GapBlock, N as NamedPattern, P as PatternBlock, c as PatternRegistry, d as PlaybackMode, e as PlaybackResult, f as PulseBlock } from './types-BRn0rP4m.mjs';
+
+declare function getCapabilityState(): CapabilityState;
+
+declare const defaultPatterns: {
+    readonly selection: readonly [{
+        readonly type: "pulse";
+        readonly duration: 8;
+        readonly intensity: 0.4;
+    }, {
+        readonly type: "gap";
+        readonly duration: 12;
+    }, {
+        readonly type: "pulse";
+        readonly duration: 10;
+        readonly intensity: 0.6;
+    }];
+    readonly success: readonly [{
+        readonly type: "pulse";
+        readonly duration: 15;
+        readonly intensity: 0.4;
+    }, {
+        readonly type: "gap";
+        readonly duration: 40;
+    }, {
+        readonly type: "pulse";
+        readonly duration: 25;
+        readonly intensity: 0.7;
+    }, {
+        readonly type: "gap";
+        readonly duration: 60;
+    }, {
+        readonly type: "pulse";
+        readonly duration: 35;
+        readonly intensity: 1;
+    }];
+    readonly error: readonly [{
+        readonly type: "pulse";
+        readonly duration: 30;
+        readonly intensity: 0.7;
+    }, {
+        readonly type: "gap";
+        readonly duration: 30;
+    }, {
+        readonly type: "pulse";
+        readonly duration: 30;
+        readonly intensity: 0.7;
+    }, {
+        readonly type: "gap";
+        readonly duration: 30;
+    }, {
+        readonly type: "pulse";
+        readonly duration: 35;
+        readonly intensity: 0.9;
+    }, {
+        readonly type: "gap";
+        readonly duration: 30;
+    }, {
+        readonly type: "pulse";
+        readonly duration: 40;
+        readonly intensity: 1;
+    }];
+    readonly toggle: readonly [{
+        readonly type: "pulse";
+        readonly duration: 12;
+        readonly intensity: 0.5;
+    }, {
+        readonly type: "gap";
+        readonly duration: 24;
+    }, {
+        readonly type: "pulse";
+        readonly duration: 18;
+        readonly intensity: 0.8;
+    }, {
+        readonly type: "gap";
+        readonly duration: 24;
+    }, {
+        readonly type: "pulse";
+        readonly duration: 12;
+        readonly intensity: 0.5;
+    }];
+    readonly snap: readonly [{
+        readonly type: "pulse";
+        readonly duration: 8;
+        readonly intensity: 0.3;
+    }, {
+        readonly type: "gap";
+        readonly duration: 8;
+    }, {
+        readonly type: "pulse";
+        readonly duration: 10;
+        readonly intensity: 0.5;
+    }, {
+        readonly type: "gap";
+        readonly duration: 8;
+    }, {
+        readonly type: "pulse";
+        readonly duration: 12;
+        readonly intensity: 0.7;
+    }, {
+        readonly type: "gap";
+        readonly duration: 8;
+    }, {
+        readonly type: "pulse";
+        readonly duration: 14;
+        readonly intensity: 0.9;
+    }, {
+        readonly type: "gap";
+        readonly duration: 8;
+    }, {
+        readonly type: "pulse";
+        readonly duration: 16;
+        readonly intensity: 1;
+    }];
+};
+
+declare const haptics: HapticsApi;
+declare function createHaptics(options?: CreateHapticsOptions): HapticsInstance;
+declare function dispose(): void;
+declare function setEnabled(enabled: boolean): void;
+declare function isEnabled(): boolean;
+
+export { CapabilityState, CreateHapticsOptions, HapticsApi, HapticsInstance, createHaptics, defaultPatterns, dispose, getCapabilityState as getCapabilities, haptics, isEnabled, setEnabled };

package/dist/index.d.ts

@@ -0,0 +1,124 @@
+import { C as CapabilityState, a as CreateHapticsOptions, H as HapticsInstance, b as HapticsApi } from './types-BRn0rP4m.js';
+export { G as GapBlock, N as NamedPattern, P as PatternBlock, c as PatternRegistry, d as PlaybackMode, e as PlaybackResult, f as PulseBlock } from './types-BRn0rP4m.js';
+
+declare function getCapabilityState(): CapabilityState;
+
+declare const defaultPatterns: {
+    readonly selection: readonly [{
+        readonly type: "pulse";
+        readonly duration: 8;
+        readonly intensity: 0.4;
+    }, {
+        readonly type: "gap";
+        readonly duration: 12;
+    }, {
+        readonly type: "pulse";
+        readonly duration: 10;
+        readonly intensity: 0.6;
+    }];
+    readonly success: readonly [{
+        readonly type: "pulse";
+        readonly duration: 15;
+        readonly intensity: 0.4;
+    }, {
+        readonly type: "gap";
+        readonly duration: 40;
+    }, {
+        readonly type: "pulse";
+        readonly duration: 25;
+        readonly intensity: 0.7;
+    }, {
+        readonly type: "gap";
+        readonly duration: 60;
+    }, {
+        readonly type: "pulse";
+        readonly duration: 35;
+        readonly intensity: 1;
+    }];
+    readonly error: readonly [{
+        readonly type: "pulse";
+        readonly duration: 30;
+        readonly intensity: 0.7;
+    }, {
+        readonly type: "gap";
+        readonly duration: 30;
+    }, {
+        readonly type: "pulse";
+        readonly duration: 30;
+        readonly intensity: 0.7;
+    }, {
+        readonly type: "gap";
+        readonly duration: 30;
+    }, {
+        readonly type: "pulse";
+        readonly duration: 35;
+        readonly intensity: 0.9;
+    }, {
+        readonly type: "gap";
+        readonly duration: 30;
+    }, {
+        readonly type: "pulse";
+        readonly duration: 40;
+        readonly intensity: 1;
+    }];
+    readonly toggle: readonly [{
+        readonly type: "pulse";
+        readonly duration: 12;
+        readonly intensity: 0.5;
+    }, {
+        readonly type: "gap";
+        readonly duration: 24;
+    }, {
+        readonly type: "pulse";
+        readonly duration: 18;
+        readonly intensity: 0.8;
+    }, {
+        readonly type: "gap";
+        readonly duration: 24;
+    }, {
+        readonly type: "pulse";
+        readonly duration: 12;
+        readonly intensity: 0.5;
+    }];
+    readonly snap: readonly [{
+        readonly type: "pulse";
+        readonly duration: 8;
+        readonly intensity: 0.3;
+    }, {
+        readonly type: "gap";
+        readonly duration: 8;
+    }, {
+        readonly type: "pulse";
+        readonly duration: 10;
+        readonly intensity: 0.5;
+    }, {
+        readonly type: "gap";
+        readonly duration: 8;
+    }, {
+        readonly type: "pulse";
+        readonly duration: 12;
+        readonly intensity: 0.7;
+    }, {
+        readonly type: "gap";
+        readonly duration: 8;
+    }, {
+        readonly type: "pulse";
+        readonly duration: 14;
+        readonly intensity: 0.9;
+    }, {
+        readonly type: "gap";
+        readonly duration: 8;
+    }, {
+        readonly type: "pulse";
+        readonly duration: 16;
+        readonly intensity: 1;
+    }];
+};
+
+declare const haptics: HapticsApi;
+declare function createHaptics(options?: CreateHapticsOptions): HapticsInstance;
+declare function dispose(): void;
+declare function setEnabled(enabled: boolean): void;
+declare function isEnabled(): boolean;
+
+export { CapabilityState, CreateHapticsOptions, HapticsApi, HapticsInstance, createHaptics, defaultPatterns, dispose, getCapabilityState as getCapabilities, haptics, isEnabled, setEnabled };