@joknoll/svelte-attach-sound 0.1.0

package/README.md

@@ -0,0 +1,32 @@
+# svelte-attach-sound
+
+A Svelte attachment for binding sound playback to DOM events using the [Svelte 5 attachments API](https://svelte.dev/docs/svelte/attachments).
+
+You can find CC-Zero licensed sounds at [freesound.org](https://freesound.org/)
+
+## Installation
+
+```
+npm install @joknoll/svelte-attach-sound
+```
+
+## Example
+
+```svelte
+<script lang="ts">
+  import { sound, useSound } from "@joknoll/svelte-attach-sound";
+  import click_mp3 from "$lib/assets/click.mp3";
+
+  const click = useSound(click_mp3, ["pointerdown"]);
+</script>
+
+<!-- Inline -->
+<button {@attach sound({ src: click_mp3, events: ["click"] })}>Click</button>
+<button {@attach sound({ src: click_mp3, events: ["mouseenter"] })}>Enter</button>
+
+<!-- Factory: reusable with shared defaults -->
+<button {@attach click()}>Click</button>
+<button {@attach click({ volume: 0.5 })}>Click (quieter)</button>
+```
+
+[Demo](https://joknoll.github.io/svelte-attach-sound/) | [npm](https://www.npmjs.com/package/svelte-attach-sound)

package/dist/index.d.ts

@@ -0,0 +1,54 @@
+import { Attachment } from "svelte/attachments";
+
+//#region src/index.d.ts
+type SoundSource = string;
+type SoundEvents = [keyof HTMLElementEventMap, (keyof HTMLElementEventMap)?];
+type SoundOptions = {
+  /** Playback volume, 0.0 to 1.0. Default: 1. */volume?: number; /** Whether the sound loops. Default: false. */
+  loop?: boolean; /** Playback rate multiplier. Default: 1. */
+  rate?: number;
+};
+type Options = {
+  src: SoundSource;
+  events: SoundEvents;
+} & SoundOptions;
+declare class Sound {
+  private buffer;
+  private source;
+  private token;
+  private options;
+  constructor(src: SoundSource, options?: SoundOptions);
+  private load;
+  play(): void;
+  stop(): void;
+}
+/**
+ * Creates a sound attachment that binds playback to DOM events on the element.
+ *
+ * @example
+ * ```svelte
+ * <button {@attach sound({ src: click_mp3, events: ["click"] })}>
+ *   Click me
+ * </button>
+ * ```
+ */
+declare function sound(options: Options): Attachment<HTMLElement>;
+/**
+ * Creates a pre-configured sound attachment factory reusable across elements.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useSound } from "svelte-attach-sound";
+ *   import click_mp3 from "./assets/click.mp3";
+ *
+ *   const click = useSound(click_mp3, ["click"]);
+ * </script>
+ *
+ * <button {@attach click()}>Click me</button>
+ * <button {@attach click({ volume: 0.5 })}>Quieter</button>
+ * ```
+ */
+declare function useSound(src: SoundSource, events: SoundEvents, options?: SoundOptions): (overrideOptions?: SoundOptions) => Attachment<HTMLElement>;
+//#endregion
+export { Sound, sound, useSound };

package/dist/index.js

@@ -0,0 +1 @@
+import{on as e}from"svelte/events";let t=null;function n(){return typeof AudioContext>`u`?null:t??=new AudioContext}var r=class{buffer;source=null;token=0;options;constructor(e,t={}){this.options=t,this.buffer=this.load(e)}async load(e){let t=n();if(!t)return null;try{let n=await(await fetch(e)).arrayBuffer();return await t.decodeAudioData(n)}catch(t){return console.warn(`[svelte-attach-sound] Failed to load sound:`,e,t),null}}play(){let e=this.token;this.buffer.then(t=>{if(!t||e!==this.token)return;let r=n();if(!r)return;r.resume();let i=r.createBufferSource();i.buffer=t,i.loop=this.options.loop??!1,i.playbackRate.value=this.options.rate??1;let a=r.createGain();a.gain.value=this.options.volume??1,i.connect(a).connect(r.destination),this.source=i,i.start()})}stop(){this.token+=1;try{this.source?.stop()}catch{}this.source=null}};function i(t){return n=>{let{src:i,events:a,...o}=t,[s,c]=a,l=new r(i,o),u=e(n,s,()=>l.play()),d=c?e(n,c,()=>l.stop()):null;return()=>{u(),d?.(),l.stop()}}}function a(e,t,n){return r=>i({src:e,events:t,...n,...r})}export{r as Sound,i as sound,a as useSound};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@joknoll/svelte-attach-sound",
+  "version": "0.1.0",
+  "description": "A Svelte attachment for binding sound playback to DOM events using the Web Audio API.",
+  "keywords": [
+    "attachment",
+    "sound",
+    "svelte",
+    "svelte5",
+    "web-audio"
+  ],
+  "homepage": "https://github.com/joknoll/svelte-attach/tree/main/packages/sound#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/sound"
+  },
+  "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": "^29.0.1",
+    "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"
+  }
+}