@kidlib/web-audio 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Kristinn Roach Gunnarsson
+
+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,24 @@
+# @kidlib/web-audio
+
+High-level Web Audio primitives for creating musical instruments and tools.
+This package requires a browser with Web Audio and AudioWorklet support.
+
+## Install
+
+```sh
+pnpm add @kidlib/web-audio
+```
+
+## Usage
+
+```ts
+import { createSamplePlayer } from '@kidlib/web-audio';
+import { inputController } from '@kidlib/web-audio/io';
+import { registerKnobElement } from '@kidlib/web-audio/components';
+
+const player = await createSamplePlayer();
+player.play(60);
+```
+
+UI elements such as `KnobElement` are available only from the optional
+`@kidlib/web-audio/components` entry point.

package/dist/components.d.ts

@@ -0,0 +1,94 @@
+export declare type AudiolibElement = (typeof ELEMENTS)[keyof typeof ELEMENTS];
+
+export declare function defineElement(tagName: AudiolibElement, elementClass: CustomElementConstructor): void;
+
+declare const ELEMENTS: {
+    readonly KNOB: "knob-element";
+};
+
+export declare type KnobChangeEventDetail = {
+    value: number;
+    rotation: number;
+    percentage: number;
+    source: 'user' | 'programmatic';
+};
+
+export declare class KnobElement extends HTMLElement {
+    private pathElement;
+    private static stylesInjected;
+    private config;
+    private currentValue;
+    private currentRotation;
+    private rotationToValue;
+    private valueToRotation;
+    private applySnapping;
+    private static mapRange;
+    private static clamp;
+    static get observedAttributes(): string[];
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string, newValue: string): void;
+    private injectGlobalStyles;
+    private updateConfigFromAttributes;
+    private updateDimensions;
+    private updateColorFromAttribute;
+    private render;
+    private cleanup;
+    private createUtilityFunctions;
+    private dragHandlers?;
+    private lastClickTime;
+    private readonly DOUBLE_CLICK_THRESHOLD;
+    private createDraggable;
+    private updateBorder;
+    private dispatchChangeEvent;
+    setValue(value: number): void;
+    /**
+     * Sets the knob value using a normalized 0-1 input, automatically handling
+     * the knob's range and curve transformation.
+     * @param normalizedValue - Value between 0 and 1
+     */
+    setValueNormalized(normalizedValue: number): void;
+    /**
+     * Gets the current knob value as a normalized 0-1 value, accounting for
+     * the knob's range and curve. Inverse of setValueNormalized().
+     * @returns Normalized value between 0 and 1
+     */
+    getValueNormalized(): number;
+    resetToDefault(): void;
+    getValue(): number;
+    setCurve(curve: number): void;
+    getCurve(): number;
+    setDisabled(disabled: boolean): void;
+    isDisabled(): boolean;
+    getPercentage(): number;
+    get value(): number;
+    set value(val: number);
+    get disabled(): boolean;
+    set disabled(val: boolean);
+}
+
+export declare type KnobElementOptions = {
+    minValue: number;
+    maxValue: number;
+    defaultValue: number;
+    minRotation: number;
+    maxRotation: number;
+    snapIncrement: number;
+    allowedValues?: number[];
+    curve?: number;
+    snapThresholds?: Array<{
+        maxValue: number;
+        increment: number;
+    }>;
+    disabled?: boolean;
+    borderStyle?: 'currentState' | 'fullCircle';
+    width?: number;
+    height?: number;
+    color?: string;
+    value?: number;
+};
+
+export declare function registerKnobElement(): void;
+
+export { }

package/dist/components.js

@@ -0,0 +1,398 @@
+var k = Object.defineProperty;
+var y = (m, d, t) => d in m ? k(m, d, { enumerable: !0, configurable: !0, writable: !0, value: t }) : m[d] = t;
+var h = (m, d, t) => y(m, typeof d != "symbol" ? d + "" : d, t);
+const u = class u extends HTMLElement {
+  constructor() {
+    super();
+    h(this, "pathElement");
+    h(this, "config", {
+      minValue: 0,
+      maxValue: 100,
+      defaultValue: 0,
+      minRotation: -170,
+      maxRotation: 170,
+      snapIncrement: 1,
+      curve: 1,
+      disabled: !1,
+      borderStyle: "currentState"
+    });
+    h(this, "currentValue", 0);
+    h(this, "currentRotation", 0);
+    h(this, "rotationToValue");
+    h(this, "valueToRotation");
+    h(this, "applySnapping");
+    h(this, "dragHandlers");
+    h(this, "lastClickTime", 0);
+    h(this, "DOUBLE_CLICK_THRESHOLD", 300);
+  }
+  static mapRange(t, e, n, i, s) {
+    return e === t ? n : (s - t) * (i - n) / (e - t) + n;
+  }
+  static clamp(t, e, n) {
+    return Math.min(Math.max(t, e), n);
+  }
+  // Observed attributes
+  static get observedAttributes() {
+    return [
+      "min-value",
+      "max-value",
+      "default-value",
+      "min-rotation",
+      "max-rotation",
+      "snap-increment",
+      "allowed-values",
+      "value",
+      "disabled",
+      "width",
+      "height",
+      "border-style",
+      "curve",
+      "color"
+    ];
+  }
+  connectedCallback() {
+    this.injectGlobalStyles(), this.createUtilityFunctions(), this.render(), this.updateColorFromAttribute(), this.setValue(this.config.defaultValue ?? this.config.minValue), this.createDraggable();
+  }
+  disconnectedCallback() {
+    this.cleanup();
+  }
+  attributeChangedCallback(t, e, n) {
+    if (e !== n) {
+      if (t === "max-value" || t === "min-value") {
+        const i = this.config.minValue, s = this.config.maxValue;
+        this.updateConfigFromAttributes(), this.updateBorder();
+        let o;
+        t === "max-value" ? o = u.mapRange(
+          i,
+          // old min
+          parseFloat(e),
+          // old max
+          this.config.minValue,
+          // new min
+          this.config.maxValue,
+          // new max
+          this.currentValue
+        ) : o = u.mapRange(
+          parseFloat(e),
+          // old min
+          s,
+          // old max
+          this.config.minValue,
+          // new min
+          this.config.maxValue,
+          // new max
+          this.currentValue
+        ), this.createUtilityFunctions(), this.setValue(o);
+        return;
+      }
+      if (this.updateConfigFromAttributes(), this.updateBorder(), t === "width" || t === "height" || t === "border-style") return;
+      if (t === "color") {
+        this.updateColorFromAttribute();
+        return;
+      }
+      if (t === "curve") {
+        this.createUtilityFunctions(), this.setValue(this.currentValue);
+        return;
+      }
+    }
+  }
+  injectGlobalStyles() {
+    if (u.stylesInjected) return;
+    const t = document.createElement("style");
+    t.id = "knob-element-styles", t.textContent = `
+      knob-element {
+        display: block;
+        box-sizing: border-box;
+        --knob-size: 120px;
+        --knob-stroke: rgb(234, 234, 234);
+
+        width: var(--knob-size, 120px); 
+        height: var(--knob-size, 120px);
+
+        touch-action: none; /* Prevents browser touch gestures */
+        user-select: none; /* Prevents text selection during drag */
+        border-radius: 50%;
+        cursor: grab;
+      }
+      
+      knob-element[disabled] {
+        opacity: 0.5;
+        pointer-events: none; 
+      }
+    
+      knob-element:active {
+        cursor: grabbing;
+      }
+    `, document.head.appendChild(t), u.stylesInjected = !0;
+  }
+  updateConfigFromAttributes() {
+    const t = (r, a) => {
+      const c = this.getAttribute(r);
+      return c !== null ? parseFloat(c) : a;
+    }, e = (r, a) => this.getAttribute(r) || a, n = (r) => {
+      const a = this.getAttribute(r);
+      if (a)
+        try {
+          return JSON.parse(a);
+        } catch {
+          console.warn(`KnobElement: Invalid ${r} JSON:`, a);
+          return;
+        }
+    }, i = n("allowed-values");
+    let s = t("min-value", 0), o = t("max-value", 100);
+    if (i && i.length > 0) {
+      const r = [...i].sort((f, l) => f - l), a = r[0], c = r[r.length - 1];
+      this.hasAttribute("min-value") && s !== a && console.debug(
+        `KnobElement: min-value (${s}) doesn't match first allowedValue (${a}). Using ${a}.`
+      ), this.hasAttribute("max-value") && o !== c && console.debug(
+        `KnobElement: max-value (${o}) doesn't match last allowedValue (${c}). Using ${c}.`
+      ), this.hasAttribute("snap-thresholds") && console.debug(
+        "KnobElement: allowedValues overrides snap-increment and snap-thresholds."
+      ), s = a, o = c;
+    }
+    this.config = {
+      minValue: s,
+      maxValue: o,
+      defaultValue: t("default-value", 0),
+      minRotation: t("min-rotation", -150),
+      maxRotation: t("max-rotation", 150),
+      snapIncrement: t("snap-increment", 1),
+      curve: t("curve", 1),
+      borderStyle: e(
+        "border-style",
+        "currentState"
+      ),
+      allowedValues: i ? [...i].sort((r, a) => r - a) : void 0,
+      snapThresholds: n(
+        "snap-thresholds"
+      ),
+      disabled: this.hasAttribute("disabled")
+    }, this.updateDimensions();
+  }
+  updateDimensions() {
+    const t = this.getAttribute("width"), e = this.getAttribute("height");
+    if (t || e) {
+      const n = t || e || "120";
+      this.style.setProperty("--knob-size", `${n}px`);
+    }
+  }
+  updateColorFromAttribute() {
+    const t = this.getAttribute("color");
+    t && this.style.setProperty("--knob-stroke", t);
+  }
+  render() {
+    this.innerHTML = `
+      <svg class="ac-knob" width="100%" height="100%" viewBox="0 0 100 100">
+          <path class="knob-path" 
+                fill="none" 
+                stroke="var(--knob-stroke)" 
+                stroke-width="5" 
+                stroke-linecap="round"
+                stroke-linejoin="round"
+                d="M50,50 L50,2"
+                />
+      </svg>
+  `, this.pathElement = this.querySelector(".knob-path");
+  }
+  cleanup() {
+    this.dragHandlers && (this.removeEventListener("mousedown", this.dragHandlers.start), this.removeEventListener("touchstart", this.dragHandlers.start), document.removeEventListener("mousemove", this.dragHandlers.move), document.removeEventListener("mouseup", this.dragHandlers.end), document.removeEventListener("touchmove", this.dragHandlers.move), document.removeEventListener("touchend", this.dragHandlers.end));
+  }
+  createUtilityFunctions() {
+    const t = this.config.curve || 1;
+    this.rotationToValue = (e) => {
+      const n = u.mapRange(
+        this.config.minRotation,
+        this.config.maxRotation,
+        0,
+        1,
+        e
+      ), i = Math.pow(n, t);
+      return u.mapRange(
+        0,
+        1,
+        this.config.minValue,
+        this.config.maxValue,
+        i
+      );
+    }, this.valueToRotation = (e) => {
+      const n = u.mapRange(
+        this.config.minValue,
+        this.config.maxValue,
+        0,
+        1,
+        e
+      ), i = Math.pow(n, 1 / t);
+      return u.mapRange(
+        0,
+        1,
+        this.config.minRotation,
+        this.config.maxRotation,
+        i
+      );
+    }, this.applySnapping = (e) => {
+      if (this.config.allowedValues && this.config.allowedValues.length > 0)
+        return this.config.allowedValues.reduce((i, s) => Math.abs(s - e) < Math.abs(i - e) ? s : i);
+      if (this.config.snapIncrement <= 0) return e;
+      let n = this.config.snapIncrement;
+      if (this.config.snapThresholds) {
+        for (const { maxValue: i, increment: s } of this.config.snapThresholds)
+          if (e < i) {
+            n = s;
+            break;
+          }
+      }
+      return Math.round(e / n) * n;
+    };
+  }
+  // TODO(audiolib): Add keyboard controls and slider ARIA semantics in the planned accessibility pass.
+  createDraggable() {
+    const t = "pointerLockElement" in document && "requestPointerLock" in HTMLElement.prototype;
+    let e = !1, n = 0, i = 0, s = 0, o = !1;
+    const r = (l) => {
+      n = l.clientY, o = document.pointerLockElement === this, !(!t || document.pointerLockElement) && this.requestPointerLock().then(
+        () => {
+          o = document.pointerLockElement === this;
+        },
+        () => {
+          o = !1;
+        }
+      );
+    }, a = (l) => {
+      if (this.config.disabled) return;
+      const g = Date.now(), p = g - this.lastClickTime;
+      if (p < this.DOUBLE_CLICK_THRESHOLD && p > 0) {
+        this.resetToDefault();
+        return;
+      }
+      this.lastClickTime = g, e = !0, i = this.currentRotation, s = 0, "touches" in l ? (n = l.touches[0].clientY, o = !1) : r(l);
+    }, c = (l) => {
+      if (!e) return;
+      let g;
+      const p = 2;
+      if (o && document.pointerLockElement)
+        s += l.movementY, g = -s * p;
+      else {
+        const x = "touches" in l ? l.touches[0].clientY : l.clientY;
+        g = (n - x) * p;
+      }
+      const V = i + g, E = u.clamp(
+        V,
+        this.config.minRotation,
+        this.config.maxRotation
+      ), R = this.rotationToValue(E), b = this.applySnapping(R);
+      this.currentValue = b, b !== R ? this.currentRotation = this.valueToRotation(b) : this.currentRotation = E, this.updateBorder(), this.dispatchChangeEvent("user"), l.preventDefault();
+    }, f = () => {
+      e = !1, o && document.pointerLockElement && document.exitPointerLock(), o = !1;
+    };
+    this.dragHandlers = {
+      start: a,
+      move: c,
+      end: f
+    }, this.addEventListener("mousedown", a), this.addEventListener("touchstart", a, { passive: !1 }), document.addEventListener("mousemove", c), document.addEventListener("mouseup", f), document.addEventListener("touchmove", c, { passive: !1 }), document.addEventListener("touchend", f);
+  }
+  updateBorder() {
+    if (!this.pathElement) return;
+    if ((this.getAttribute("border-style") || "currentState") === "currentState") {
+      const s = (this.config.minRotation - 90) * Math.PI / 180, o = (this.currentRotation - 90) * Math.PI / 180, r = 48 * Math.cos(s) + 50, a = 48 * Math.sin(s) + 50, c = 48 * Math.cos(o) + 50, f = 48 * Math.sin(o) + 50, l = this.currentRotation - this.config.minRotation, g = Math.abs(l) > 180 ? 1 : 0, p = `M50,50 L${r},${a} A48,48,0,${g},1,${c},${f} Z`;
+      this.pathElement.setAttribute("d", p);
+    } else
+      this.pathElement.setAttribute("d", "M50,2 A48,48,0,1,1,49.9,2 Z");
+  }
+  dispatchChangeEvent(t = "programmatic") {
+    const e = u.mapRange(
+      this.config.minValue,
+      this.config.maxValue,
+      0,
+      100,
+      this.currentValue
+    ), n = new CustomEvent("knob-change", {
+      detail: {
+        value: this.currentValue,
+        rotation: this.currentRotation,
+        percentage: e,
+        source: t
+      },
+      bubbles: !0
+    });
+    this.dispatchEvent(n);
+  }
+  // Public API
+  setValue(t) {
+    !this.valueToRotation || !this.pathElement || (this.currentValue = u.clamp(
+      t,
+      this.config.minValue,
+      this.config.maxValue
+    ), this.currentRotation = this.valueToRotation(this.currentValue), this.updateBorder(), this.dispatchChangeEvent());
+  }
+  /**
+   * Sets the knob value using a normalized 0-1 input, automatically handling
+   * the knob's range and curve transformation.
+   * @param normalizedValue - Value between 0 and 1
+   */
+  setValueNormalized(t) {
+    const { minRotation: e, maxRotation: n } = this.config, i = Math.max(0, Math.min(1, t)), s = e + i * (n - e), o = this.rotationToValue(s);
+    this.setValue(o);
+  }
+  /**
+   * Gets the current knob value as a normalized 0-1 value, accounting for
+   * the knob's range and curve. Inverse of setValueNormalized().
+   * @returns Normalized value between 0 and 1
+   */
+  getValueNormalized() {
+    return (this.currentRotation - this.config.minRotation) / (this.config.maxRotation - this.config.minRotation);
+  }
+  resetToDefault() {
+    this.setValue(this.config.defaultValue);
+  }
+  getValue() {
+    return this.currentValue;
+  }
+  setCurve(t) {
+    this.config.curve = t, this.createUtilityFunctions(), this.setValue(this.currentValue);
+  }
+  getCurve() {
+    return this.config.curve || 1;
+  }
+  setDisabled(t) {
+    t ? this.setAttribute("disabled", "") : this.removeAttribute("disabled");
+  }
+  isDisabled() {
+    return this.hasAttribute("disabled");
+  }
+  getPercentage() {
+    return u.mapRange(
+      this.config.minValue,
+      this.config.maxValue,
+      0,
+      100,
+      this.currentValue
+    );
+  }
+  // Property getters/setters for easier JS usage
+  get value() {
+    return this.getValue();
+  }
+  set value(t) {
+    this.setValue(t);
+  }
+  get disabled() {
+    return this.isDisabled();
+  }
+  set disabled(t) {
+    this.setDisabled(t);
+  }
+};
+h(u, "stylesInjected", !1);
+let v = u;
+const L = { KNOB: "knob-element" };
+function w(m, d) {
+  typeof customElements > "u" || customElements.get(m) || customElements.define(m, d);
+}
+function C() {
+  w(L.KNOB, v);
+}
+export {
+  v as KnobElement,
+  w as defineElement,
+  C as registerKnobElement
+};