bzzz 0.1.0

package/dist/react.js

@@ -0,0 +1,447 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/react.ts
+var react_exports = {};
+__export(react_exports, {
+  useCreateHaptics: () => useCreateHaptics,
+  useHaptics: () => useHaptics
+});
+module.exports = __toCommonJS(react_exports);
+var import_react = require("react");
+
+// 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/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/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();
+    }
+  };
+}
+
+// src/react.ts
+var hapticsReturn = {
+  selection: haptics.selection,
+  success: haptics.success,
+  error: haptics.error,
+  toggle: haptics.toggle,
+  snap: haptics.snap,
+  play: haptics.play,
+  getCapabilities: haptics.getCapabilities,
+  isEnabled: haptics.isEnabled,
+  setEnabled: haptics.setEnabled
+};
+function useHaptics() {
+  return hapticsReturn;
+}
+function useCreateHaptics(options) {
+  const instanceRef = (0, import_react.useRef)(null);
+  if (!instanceRef.current) {
+    instanceRef.current = createHaptics(options);
+  }
+  (0, import_react.useEffect)(() => {
+    return () => {
+      instanceRef.current?.dispose();
+      instanceRef.current = null;
+    };
+  }, []);
+  const instance = instanceRef.current;
+  return (0, import_react.useMemo)(() => ({
+    play: instance.play,
+    register: instance.register,
+    getCapabilities: instance.getCapabilities,
+    isEnabled: instance.isEnabled,
+    setEnabled: instance.setEnabled
+  }), [instance]);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useCreateHaptics,
+  useHaptics
+});

package/dist/react.mjs

@@ -0,0 +1,45 @@
+import {
+  createHaptics,
+  haptics
+} from "./chunk-RLTRZ2WN.mjs";
+
+// src/react.ts
+import { useEffect, useMemo, useRef } from "react";
+var hapticsReturn = {
+  selection: haptics.selection,
+  success: haptics.success,
+  error: haptics.error,
+  toggle: haptics.toggle,
+  snap: haptics.snap,
+  play: haptics.play,
+  getCapabilities: haptics.getCapabilities,
+  isEnabled: haptics.isEnabled,
+  setEnabled: haptics.setEnabled
+};
+function useHaptics() {
+  return hapticsReturn;
+}
+function useCreateHaptics(options) {
+  const instanceRef = useRef(null);
+  if (!instanceRef.current) {
+    instanceRef.current = createHaptics(options);
+  }
+  useEffect(() => {
+    return () => {
+      instanceRef.current?.dispose();
+      instanceRef.current = null;
+    };
+  }, []);
+  const instance = instanceRef.current;
+  return useMemo(() => ({
+    play: instance.play,
+    register: instance.register,
+    getCapabilities: instance.getCapabilities,
+    isEnabled: instance.isEnabled,
+    setEnabled: instance.setEnabled
+  }), [instance]);
+}
+export {
+  useCreateHaptics,
+  useHaptics
+};

package/dist/types-BRn0rP4m.d.mts

@@ -0,0 +1,47 @@
+type PulseBlock = {
+    type: "pulse";
+    duration: number;
+    intensity?: number;
+};
+type GapBlock = {
+    type: "gap";
+    duration: number;
+};
+type PatternBlock = PulseBlock | GapBlock;
+type NamedPattern = "selection" | "success" | "error" | "toggle" | "snap";
+type PlaybackMode = "haptics" | "audio" | "none";
+type PlaybackResult = {
+    mode: PlaybackMode;
+};
+type CapabilityState = {
+    haptics: boolean;
+    audio: boolean;
+    ios: boolean;
+    reducedMotion: boolean;
+};
+type PatternRegistry = Record<string, PatternBlock[]>;
+type CreateHapticsOptions = {
+    patterns?: PatternRegistry;
+};
+type HapticsApi = {
+    selection: () => PlaybackResult;
+    success: () => PlaybackResult;
+    error: () => PlaybackResult;
+    toggle: () => PlaybackResult;
+    snap: () => PlaybackResult;
+    play: (pattern: readonly PatternBlock[]) => PlaybackResult;
+    getCapabilities: () => CapabilityState;
+    setEnabled: (enabled: boolean) => void;
+    isEnabled: () => boolean;
+    dispose: () => void;
+};
+type HapticsInstance = {
+    play: (nameOrPattern: string | readonly PatternBlock[]) => PlaybackResult;
+    register: (name: string, pattern: readonly PatternBlock[]) => void;
+    getCapabilities: () => CapabilityState;
+    setEnabled: (enabled: boolean) => void;
+    isEnabled: () => boolean;
+    dispose: () => void;
+};
+
+export type { CapabilityState as C, GapBlock as G, HapticsInstance as H, NamedPattern as N, PatternBlock as P, CreateHapticsOptions as a, HapticsApi as b, PatternRegistry as c, PlaybackMode as d, PlaybackResult as e, PulseBlock as f };

package/dist/types-BRn0rP4m.d.ts

@@ -0,0 +1,47 @@
+type PulseBlock = {
+    type: "pulse";
+    duration: number;
+    intensity?: number;
+};
+type GapBlock = {
+    type: "gap";
+    duration: number;
+};
+type PatternBlock = PulseBlock | GapBlock;
+type NamedPattern = "selection" | "success" | "error" | "toggle" | "snap";
+type PlaybackMode = "haptics" | "audio" | "none";
+type PlaybackResult = {
+    mode: PlaybackMode;
+};
+type CapabilityState = {
+    haptics: boolean;
+    audio: boolean;
+    ios: boolean;
+    reducedMotion: boolean;
+};
+type PatternRegistry = Record<string, PatternBlock[]>;
+type CreateHapticsOptions = {
+    patterns?: PatternRegistry;
+};
+type HapticsApi = {
+    selection: () => PlaybackResult;
+    success: () => PlaybackResult;
+    error: () => PlaybackResult;
+    toggle: () => PlaybackResult;
+    snap: () => PlaybackResult;
+    play: (pattern: readonly PatternBlock[]) => PlaybackResult;
+    getCapabilities: () => CapabilityState;
+    setEnabled: (enabled: boolean) => void;
+    isEnabled: () => boolean;
+    dispose: () => void;
+};
+type HapticsInstance = {
+    play: (nameOrPattern: string | readonly PatternBlock[]) => PlaybackResult;
+    register: (name: string, pattern: readonly PatternBlock[]) => void;
+    getCapabilities: () => CapabilityState;
+    setEnabled: (enabled: boolean) => void;
+    isEnabled: () => boolean;
+    dispose: () => void;
+};
+
+export type { CapabilityState as C, GapBlock as G, HapticsInstance as H, NamedPattern as N, PatternBlock as P, CreateHapticsOptions as a, HapticsApi as b, PatternRegistry as c, PlaybackMode as d, PlaybackResult as e, PulseBlock as f };

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "bzzz",
+  "version": "0.1.0",
+  "description": "Haptic feedback for the web. Native vibration + audio fallback.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.mjs",
+      "require": "./dist/react.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/react.ts --format esm,cjs --dts --clean --external react",
+    "dev": "tsup src/index.ts src/react.ts --format esm,cjs --dts --watch --external react",
+    "dev:website": "npm --prefix website run dev",
+    "build:website": "npm --prefix website run build",
+    "dev:all": "concurrently \"npm run dev\" \"npm run dev:website\"",
+    "lint": "tsc --noEmit",
+    "test": "vitest run",
+    "pack:check": "npm pack --dry-run --cache /tmp/bzzz-npm-cache"
+  },
+  "keywords": [
+    "haptics",
+    "audio",
+    "feedback",
+    "interaction",
+    "web"
+  ],
+  "license": "MIT",
+  "author": "Pavle Lucic",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pavlito/bzzz"
+  },
+  "homepage": "https://pavlito.github.io/bzzz",
+  "bugs": {
+    "url": "https://github.com/pavlito/bzzz/issues"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "concurrently": "^9.2.0",
+    "jsdom": "^29.0.0",
+    "react": "^19.0.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}