@joknoll/svelte-attach-haptic 0.1.0

package/README.md

@@ -0,0 +1,129 @@
+# svelte-attach-haptic
+
+A Svelte attachment for adding haptic feedback to elements using the [Svelte 5 attachments API](https://svelte.dev/docs/svelte/attachments).
+
+Uses the Web Vibration API. Silently no-ops on unsupported platforms (desktop).
+
+## Installation
+
+```
+npm install @joknoll/svelte-attach-haptic
+```
+
+## Example
+
+```svelte
+<script lang="ts">
+  import { haptic, useHaptic } from "@joknoll/svelte-attach-haptic";
+
+  const tap = useHaptic("medium", ["pointerdown"]);
+</script>
+
+<!-- Default: medium intensity on click -->
+<button {@attach haptic()}>Default</button>
+
+<!-- Built-in presets -->
+<button {@attach haptic({ pattern: "success" })}>Success</button>
+<button {@attach haptic({ pattern: "error" })}>Error</button>
+
+<!-- Custom event trigger -->
+<button {@attach haptic({ pattern: "heavy", events: ["pointerdown"] })}>Heavy on pointerdown</button>
+
+<!-- Factory: create a reusable haptic with shared defaults -->
+<button {@attach tap()}>Factory default</button>
+<button {@attach tap({ pattern: "light" })}>Factory with override</button>
+```
+
+[Demo](https://joknoll.github.io/svelte-attach-haptic/) | [npm](https://www.npmjs.com/package/svelte-attach-haptic)
+
+## API
+
+### `haptic(options?)`
+
+Svelte attachment that triggers haptic feedback on an element.
+
+| Option      | Type                           | Default     | Description                          |
+| ----------- | ------------------------------ | ----------- | ------------------------------------ |
+| `pattern`   | `HapticInput`                  | `"medium"`  | Vibration pattern or preset name     |
+| `events`    | `[triggerEvent, cancelEvent?]` | `["click"]` | DOM events to trigger/cancel haptics |
+| `intensity` | `number`                       | `0.5`       | Global intensity override (0–1)      |
+
+### `useHaptic(pattern?, events?, intensity?)`
+
+Factory function that returns a reusable attachment with preset defaults. The returned function accepts optional overrides per element.
+
+```svelte
+<script lang="ts">
+  import { useHaptic } from "svelte-attach-haptic";
+  const tap = useHaptic("medium", ["pointerdown"]);
+</script>
+
+<button {@attach tap()}>Uses defaults</button>
+<button {@attach tap({ pattern: "light" })}>Override pattern</button>
+```
+
+### `Haptic` class
+
+For manual control outside of attachments:
+
+```ts
+import { Haptic } from "svelte-attach-haptic";
+
+const h = new Haptic("success");
+h.trigger();
+h.cancel();
+```
+
+### `isSupported`
+
+Boolean indicating whether the Web Vibration API is available.
+
+### Built-in presets
+
+| Preset        | Category     | Description                                              |
+| ------------- | ------------ | -------------------------------------------------------- |
+| `"light"`     | Impact       | Short, subtle tap (small toggle, minor interaction)      |
+| `"medium"`    | Impact       | Standard tap (button press, card snap-to-position)       |
+| `"heavy"`     | Impact       | Strong impact (major state change, force press)          |
+| `"soft"`      | Impact       | Soft impact (gentle interaction)                         |
+| `"rigid"`     | Impact       | Crisp impact (sharp, precise feedback)                   |
+| `"selection"` | Selection    | Selection feedback (picker scroll, slider detent)        |
+| `"success"`   | Notification | Success notification (form saved, payment confirmed)     |
+| `"warning"`   | Notification | Warning notification (destructive action, limit reached) |
+| `"error"`     | Notification | Error notification (validation failure, network error)   |
+| `"nudge"`     | Other        | Double bump (attention grab)                             |
+| `"buzz"`      | Other        | Long buzz                                                |
+
+### Custom patterns
+
+```ts
+// Single duration (ms)
+haptic({ pattern: 200 });
+
+// Array of durations (vibrate, pause, vibrate, ...)
+haptic({ pattern: [100, 50, 100] });
+
+// Vibration objects with per-step intensity
+haptic({
+  pattern: [
+    { duration: 50, intensity: 0.8 },
+    { delay: 100, duration: 30, intensity: 0.4 },
+  ],
+});
+```
+
+## Design Guidelines
+
+1. **Haptics supplement, never replace.** Always pair with visual feedback.
+2. **Match intensity to significance.** Light interactions → `"light"`/`"selection"`. Standard → `"medium"`/`"success"`. Major → `"heavy"`/`"error"`/`"warning"`.
+3. **Do not overuse.** Reserve for meaningful moments.
+4. **Synchronize perfectly.** Fire haptic at the exact instant the visual change occurs.
+5. **For async ops**, trigger when the result arrives:
+   ```ts
+   try {
+     await submit();
+     new Haptic("success").trigger();
+   } catch {
+     new Haptic("error").trigger();
+   }
+   ```

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+import { Attachment } from "svelte/attachments";
+
+//#region src/haptic.d.ts
+interface Vibration {
+  duration: number;
+  intensity?: number;
+  delay?: number;
+}
+type HapticPattern = number[] | Vibration[];
+type HapticInput = number | string | HapticPattern;
+type HapticEvents = [keyof HTMLElementEventMap, (keyof HTMLElementEventMap)?];
+interface HapticOptions {
+  pattern?: HapticInput;
+  events?: HapticEvents;
+  intensity?: number;
+}
+type HapticPresetName = "success" | "warning" | "error" | "light" | "medium" | "heavy" | "soft" | "rigid" | "selection" | "nudge" | "buzz";
+declare const defaultPatterns: Record<HapticPresetName, Vibration[]>;
+/** Whether the Web Vibration API is available in the current environment. */
+declare const isSupported: boolean;
+/**
+ * Resolve a haptic input into a flat vibrate pattern (number[]).
+ * Returns an empty array if the input is invalid or unknown.
+ */
+declare function createPattern(input?: HapticInput, intensity?: number): number[];
+/** Fire a pre-built vibrate pattern. No-op if the Vibration API is unavailable. */
+declare function triggerHaptic(pattern: number[]): void;
+/** Cancel any active vibration. No-op if the Vibration API is unavailable. */
+declare function cancelHaptic(): void;
+/** Convenience class for manual haptic control. */
+declare class Haptic {
+  static readonly isSupported: boolean;
+  private readonly pattern;
+  constructor(input?: HapticInput, intensity?: number);
+  trigger(): void;
+  cancel(): void;
+}
+/** Svelte attachment that triggers haptic feedback on DOM events. */
+declare function haptic(options?: HapticOptions): Attachment<HTMLElement>;
+/** Create a reusable haptic attachment factory with preset defaults. */
+declare function useHaptic(pattern?: HapticInput, events?: HapticEvents, intensity?: number): (overrides?: Partial<HapticOptions>) => Attachment<HTMLElement>;
+//#endregion
+export { Haptic, type HapticEvents, type HapticInput, type HapticOptions, type HapticPattern, type Vibration, cancelHaptic, createPattern, defaultPatterns, haptic, isSupported, triggerHaptic, useHaptic };

package/dist/index.js

@@ -0,0 +1 @@
+import{on as e}from"svelte/events";const t={success:[{duration:30,intensity:.5},{delay:60,duration:40,intensity:1}],warning:[{duration:40,intensity:.8},{delay:100,duration:40,intensity:.6}],error:[{duration:40,intensity:.9},{delay:40,duration:40,intensity:.9},{delay:40,duration:40,intensity:.9}],light:[{duration:15,intensity:.4}],medium:[{duration:25,intensity:.7}],heavy:[{duration:35,intensity:1}],soft:[{duration:40,intensity:.5}],rigid:[{duration:10,intensity:1}],selection:[{duration:8,intensity:.3}],nudge:[{duration:80,intensity:.8},{delay:80,duration:50,intensity:.3}],buzz:[{duration:1e3,intensity:1}]},n=1e3;function r(e){return Math.max(0,Math.min(1,e))}function i(e){if(typeof e==`number`)return[{duration:e}];if(typeof e==`string`){let n=t[e];return n?n.map(e=>({...e})):(console.warn(`[svelte-attach-haptic] Unknown preset: "${e}"`),null)}if(e.length===0)return[];if(typeof e[0]==`number`){let t=e,n=[];for(let e=0;e<t.length;e+=2){let r=e>0?t[e-1]:0;n.push({...r>0&&{delay:r},duration:t[e]})}return n}return e.map(e=>({...e}))}function a(e,t){if(t>=1)return[e];if(t<=0)return[];let n=Math.max(1,Math.round(20*t)),r=20-n,i=[],a=e;for(;a>=20;)i.push(n,r),a-=20;if(a>0){let e=Math.max(1,Math.round(a*t));i.push(e);let n=a-e;n>0&&i.push(n)}return i}function o(e,t){t<=0||(e.length>0&&e.length%2==0?e[e.length-1]+=t:(e.length===0&&e.push(0),e.push(t)))}function s(e,t){let n=[];for(let i of e){let e=r(i.intensity??t);o(n,i.delay??0);let s=a(i.duration,e);if(s.length===0){o(n,i.duration);continue}for(let e of s)n.push(e)}return n}const c=typeof navigator<`u`&&typeof navigator.vibrate==`function`;function l(e=`medium`,t=.5){let a=i(e);if(!a||a.length===0)return[];for(let e of a)e.duration>n&&(e.duration=n);return s(a,r(t))}function u(e){c&&e.length>0&&navigator.vibrate(e)}function d(){c&&navigator.vibrate(0)}var f=class{static isSupported=c;pattern;constructor(e=`medium`,t=.5){this.pattern=l(e,t)}trigger(){u(this.pattern)}cancel(){d()}};function p(t={}){return n=>{let{pattern:r=`medium`,events:i=[`click`],intensity:a=.5}=t,[o,s]=i,c=l(r,a),f=e(n,o,()=>u(c)),p=s?e(n,s,()=>d()):null;return()=>{f(),p?.()}}}function m(e,t,n){return r=>p({pattern:e,events:t,intensity:n,...r})}export{f as Haptic,d as cancelHaptic,l as createPattern,t as defaultPatterns,p as haptic,c as isSupported,u as triggerHaptic,m as useHaptic};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@joknoll/svelte-attach-haptic",
+  "version": "0.1.0",
+  "description": "A Svelte attachment for adding haptics to elements.",
+  "keywords": [
+    "attachment",
+    "haptics",
+    "svelte",
+    "svelte5"
+  ],
+  "homepage": "https://github.com/joknoll/svelte-attach/tree/main/packages/haptic#readme",
+  "bugs": {
+    "url": "https://github.com/joknoll/svelte-attach/issues"
+  },
+  "license": "MIT",
+  "author": "joknoll",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joknoll/svelte-attach.git",
+    "directory": "packages/haptic"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "@typescript/native-preview": "7.0.0-dev.20260509.2",
+    "bumpp": "^11.1.0",
+    "jsdom": "^28.1.0",
+    "svelte": "^5.55.0",
+    "typescript": "^6.0.3",
+    "vite-plus": "latest"
+  },
+  "peerDependencies": {
+    "svelte": ">=5.55.0"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check"
+  }
+}