svelte-attach-sound 0.1.1

package/README.md

@@ -0,0 +1,71 @@
+# 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).
+
+Uses [Howler.js](https://howlerjs.com/) as a peer dependency.
+
+Find CC-Zero licensed sounds at [freesound.org](https://freesound.org/)
+
+## Installation
+
+```
+npm install svelte-attach-sound howler
+```
+
+## Example
+
+```svelte
+<script lang="ts">
+  import { sound, useSound } from "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>
+
+<!-- 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)
+
+## API
+
+### `sound(options)`
+
+Svelte attachment that plays a sound on a DOM event.
+
+| Option    | Type                                                           | Required | Description                                        |
+| --------- | -------------------------------------------------------------- | -------- | -------------------------------------------------- |
+| `src`     | `string \| string[]`                                           | Yes      | Audio file URL(s), with fallbacks                  |
+| `events`  | `[playEvent, stopEvent?]`                                      | Yes      | DOM event to trigger play, and optionally stop     |
+| `...rest` | [`HowlOptions`](https://github.com/goldfire/howler.js#options) | No       | Any Howler option (`volume`, `loop`, `rate`, etc.) |
+
+### `useSound(src, events, options?)`
+
+Factory that returns a reusable attachment with preset defaults. The returned function accepts optional per-call overrides.
+
+```svelte
+<script lang="ts">
+  const click = useSound(click_mp3, ["pointerdown"], { volume: 0.8 });
+</script>
+
+<button {@attach click()}>Uses defaults</button>
+<button {@attach click({ volume: 0.3 })}>Override volume</button>
+```
+
+### `Sound` class
+
+For manual control outside of attachments:
+
+```ts
+import { Sound } from "svelte-attach-sound";
+
+const s = new Sound(click_mp3, { volume: 0.5 });
+s.play();
+s.stop();
+s.destroy(); // stops playback and frees resources
+```

package/dist/index.cjs

@@ -0,0 +1,105 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/index.ts
+/**
+* A class representing a synthetic sound.
+* Can be used standalone for programmatic playback without any DOM dependency.
+*/
+var Sound = class {
+	config;
+	howl;
+	ready;
+	constructor(src, options = {}) {
+		this.config = {
+			...options,
+			src
+		};
+		this.ready = this.create();
+	}
+	whenReady(fn) {
+		this.ready.then(fn).catch(() => {});
+	}
+	async create() {
+		const { Howl } = await import("howler/src/howler.core");
+		this.howl = new Howl(this.config);
+	}
+	play() {
+		this.whenReady(() => this.howl?.play());
+	}
+	stop() {
+		this.whenReady(() => this.howl?.stop());
+	}
+	destroy() {
+		this.whenReady(() => {
+			this.howl?.stop();
+			this.howl?.unload();
+		});
+	}
+};
+/**
+* Creates a sound attachment that binds playback to DOM events on the element.
+*
+* Runs inside a Svelte effect — if options contain reactive state, the attachment
+* will automatically tear down and recreate when that state changes.
+*
+* @param options Options including `src`, `events`, and any Howler options.
+* @returns A Svelte attachment.
+*
+* @example
+* ```svelte
+* <button {@attach sound({ src: click_mp3, events: ["click"] })}>
+*   Click me
+* </button>
+* ```
+*/
+function sound(options) {
+	return (element) => {
+		const { src, events, ...howlOptions } = options;
+		const [playEvent, stopEvent] = events;
+		const instance = new Sound(src, howlOptions);
+		const handlePlay = () => instance.play();
+		const handleStop = () => instance.stop();
+		element.addEventListener(playEvent, handlePlay);
+		if (stopEvent) element.addEventListener(stopEvent, handleStop);
+		return () => {
+			element.removeEventListener(playEvent, handlePlay);
+			if (stopEvent) element.removeEventListener(stopEvent, handleStop);
+			instance.destroy();
+		};
+	};
+}
+/**
+* Creates a pre-configured sound attachment factory that can be reused across
+* multiple elements with optional per-element overrides.
+*
+* @param src The source URL(s) of the sound.
+* @param events The `[playEvent, stopEvent?]` tuple.
+* @param options Optional base Howler options.
+* @returns A factory function that returns a Svelte attachment.
+*
+* @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>
+*
+* <!-- Override options per-element -->
+* <button {@attach click({ volume: 0.5 })}>Click me (quieter)</button>
+* ```
+*/
+function useSound(src, events, options) {
+	return (overrideOptions) => sound({
+		src,
+		events,
+		...options,
+		...overrideOptions
+	});
+}
+//#endregion
+exports.Sound = Sound;
+exports.sound = sound;
+exports.useSound = useSound;

package/dist/index.d.cts

@@ -0,0 +1,72 @@
+import { HowlOptions } from "howler";
+import { Attachment } from "svelte/attachments";
+
+//#region src/index.d.ts
+type SoundSource = HowlOptions["src"];
+type SoundEvents = [keyof HTMLElementEventMap, (keyof HTMLElementEventMap)?];
+type SoundOptions = Omit<HowlOptions, "src">;
+/**
+ * Options for the sound attachment factory.
+ */
+type Options = {
+  events: SoundEvents;
+} & HowlOptions;
+/**
+ * A class representing a synthetic sound.
+ * Can be used standalone for programmatic playback without any DOM dependency.
+ */
+declare class Sound {
+  private config;
+  private howl;
+  private ready;
+  constructor(src: SoundSource, options?: SoundOptions);
+  private whenReady;
+  private create;
+  play(): void;
+  stop(): void;
+  destroy(): void;
+}
+/**
+ * Creates a sound attachment that binds playback to DOM events on the element.
+ *
+ * Runs inside a Svelte effect — if options contain reactive state, the attachment
+ * will automatically tear down and recreate when that state changes.
+ *
+ * @param options Options including `src`, `events`, and any Howler options.
+ * @returns A Svelte attachment.
+ *
+ * @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 that can be reused across
+ * multiple elements with optional per-element overrides.
+ *
+ * @param src The source URL(s) of the sound.
+ * @param events The `[playEvent, stopEvent?]` tuple.
+ * @param options Optional base Howler options.
+ * @returns A factory function that returns a Svelte attachment.
+ *
+ * @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>
+ *
+ * <!-- Override options per-element -->
+ * <button {@attach click({ volume: 0.5 })}>Click me (quieter)</button>
+ * ```
+ */
+declare function useSound(src: SoundSource, events: SoundEvents, options?: SoundOptions): (overrideOptions?: Partial<Options>) => Attachment<HTMLElement>;
+//#endregion
+export { Sound, sound, useSound };

package/dist/index.d.mts

@@ -0,0 +1,72 @@
+import { HowlOptions } from "howler";
+import { Attachment } from "svelte/attachments";
+
+//#region src/index.d.ts
+type SoundSource = HowlOptions["src"];
+type SoundEvents = [keyof HTMLElementEventMap, (keyof HTMLElementEventMap)?];
+type SoundOptions = Omit<HowlOptions, "src">;
+/**
+ * Options for the sound attachment factory.
+ */
+type Options = {
+  events: SoundEvents;
+} & HowlOptions;
+/**
+ * A class representing a synthetic sound.
+ * Can be used standalone for programmatic playback without any DOM dependency.
+ */
+declare class Sound {
+  private config;
+  private howl;
+  private ready;
+  constructor(src: SoundSource, options?: SoundOptions);
+  private whenReady;
+  private create;
+  play(): void;
+  stop(): void;
+  destroy(): void;
+}
+/**
+ * Creates a sound attachment that binds playback to DOM events on the element.
+ *
+ * Runs inside a Svelte effect — if options contain reactive state, the attachment
+ * will automatically tear down and recreate when that state changes.
+ *
+ * @param options Options including `src`, `events`, and any Howler options.
+ * @returns A Svelte attachment.
+ *
+ * @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 that can be reused across
+ * multiple elements with optional per-element overrides.
+ *
+ * @param src The source URL(s) of the sound.
+ * @param events The `[playEvent, stopEvent?]` tuple.
+ * @param options Optional base Howler options.
+ * @returns A factory function that returns a Svelte attachment.
+ *
+ * @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>
+ *
+ * <!-- Override options per-element -->
+ * <button {@attach click({ volume: 0.5 })}>Click me (quieter)</button>
+ * ```
+ */
+declare function useSound(src: SoundSource, events: SoundEvents, options?: SoundOptions): (overrideOptions?: Partial<Options>) => Attachment<HTMLElement>;
+//#endregion
+export { Sound, sound, useSound };

package/dist/index.mjs

@@ -0,0 +1,102 @@
+//#region src/index.ts
+/**
+* A class representing a synthetic sound.
+* Can be used standalone for programmatic playback without any DOM dependency.
+*/
+var Sound = class {
+	config;
+	howl;
+	ready;
+	constructor(src, options = {}) {
+		this.config = {
+			...options,
+			src
+		};
+		this.ready = this.create();
+	}
+	whenReady(fn) {
+		this.ready.then(fn).catch(() => {});
+	}
+	async create() {
+		const { Howl } = await import("howler/src/howler.core");
+		this.howl = new Howl(this.config);
+	}
+	play() {
+		this.whenReady(() => this.howl?.play());
+	}
+	stop() {
+		this.whenReady(() => this.howl?.stop());
+	}
+	destroy() {
+		this.whenReady(() => {
+			this.howl?.stop();
+			this.howl?.unload();
+		});
+	}
+};
+/**
+* Creates a sound attachment that binds playback to DOM events on the element.
+*
+* Runs inside a Svelte effect — if options contain reactive state, the attachment
+* will automatically tear down and recreate when that state changes.
+*
+* @param options Options including `src`, `events`, and any Howler options.
+* @returns A Svelte attachment.
+*
+* @example
+* ```svelte
+* <button {@attach sound({ src: click_mp3, events: ["click"] })}>
+*   Click me
+* </button>
+* ```
+*/
+function sound(options) {
+	return (element) => {
+		const { src, events, ...howlOptions } = options;
+		const [playEvent, stopEvent] = events;
+		const instance = new Sound(src, howlOptions);
+		const handlePlay = () => instance.play();
+		const handleStop = () => instance.stop();
+		element.addEventListener(playEvent, handlePlay);
+		if (stopEvent) element.addEventListener(stopEvent, handleStop);
+		return () => {
+			element.removeEventListener(playEvent, handlePlay);
+			if (stopEvent) element.removeEventListener(stopEvent, handleStop);
+			instance.destroy();
+		};
+	};
+}
+/**
+* Creates a pre-configured sound attachment factory that can be reused across
+* multiple elements with optional per-element overrides.
+*
+* @param src The source URL(s) of the sound.
+* @param events The `[playEvent, stopEvent?]` tuple.
+* @param options Optional base Howler options.
+* @returns A factory function that returns a Svelte attachment.
+*
+* @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>
+*
+* <!-- Override options per-element -->
+* <button {@attach click({ volume: 0.5 })}>Click me (quieter)</button>
+* ```
+*/
+function useSound(src, events, options) {
+	return (overrideOptions) => sound({
+		src,
+		events,
+		...options,
+		...overrideOptions
+	});
+}
+//#endregion
+export { Sound, sound, useSound };

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "svelte-attach-sound",
+  "version": "0.1.1",
+  "description": "A Svelte attachment for binding sound playback to DOM events using Howler.js",
+  "keywords": [
+    "attachment",
+    "howler",
+    "sound",
+    "svelte",
+    "svelte5"
+  ],
+  "homepage": "https://github.com/joknoll/svelte-attach-sound#readme",
+  "bugs": {
+    "url": "https://github.com/joknoll/svelte-attach-sound/issues"
+  },
+  "license": "MIT",
+  "author": "joknoll",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joknoll/svelte-attach-sound.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "devDependencies": {
+    "@types/howler": "^2.2.12",
+    "@types/node": "^25.0.3",
+    "bumpp": "^10.3.2",
+    "howler": "^2.2.4",
+    "oxfmt": "^0.40.0",
+    "oxlint": "^1.50.0",
+    "svelte": "^5.53.11",
+    "tsdown": "^0.21.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.16"
+  },
+  "peerDependencies": {
+    "howler": ">=2.0.0",
+    "svelte": ">=5.53.11"
+  }
+}