lfocomp 0.1.0

package/types/lfo.d.ts

@@ -0,0 +1,350 @@
+/**
+ * Canvas-based LFO panel with waveform display, shape selector, parameter
+ * sliders, and a drag handle for wiring to any modulation target.
+ */
+export class LFOWidget {
+    /**
+     * @param {HTMLElement} container  Where the widget is appended.
+     * @param {string}      lfoId     Engine LFO id.
+     * @param {object}      [opts]
+     * @param {string}      [opts.color]    Accent color hex.
+     * @param {string}      [opts.label]    Display label.
+     * @param {function}    [opts.onConnect]    (lfoId, element, routeId) => void
+     * @param {function}    [opts.onDisconnect] (routeId) => void
+     */
+    constructor(container: HTMLElement, lfoId: string, opts?: {
+        color?: string;
+        label?: string;
+        onConnect?: Function;
+        onDisconnect?: Function;
+    });
+    _lfoId: string;
+    _color: string;
+    _label: string;
+    _onConnect: Function;
+    _onDisconnect: Function;
+    /** @type {Map<string, ModIndicator>} routeId → indicator */
+    _indicators: Map<string, ModIndicator>;
+    _latestValue: number;
+    _unsub: Function;
+    _rafHandle: number;
+    _destroyed: boolean;
+    _build(container: any): void;
+    _root: HTMLDivElement;
+    _led: HTMLDivElement;
+    _canvas: HTMLCanvasElement;
+    _ctx: CanvasRenderingContext2D;
+    _shapesEl: HTMLDivElement;
+    _bipolarBtn: HTMLButtonElement;
+    _rateInput: HTMLInputElement;
+    _depthInput: HTMLInputElement;
+    _phaseInput: HTMLInputElement;
+    _offsetInput: HTMLInputElement;
+    _jitterInput: HTMLInputElement;
+    _skewInput: HTMLInputElement;
+    _handle: HTMLDivElement;
+    _addParam(container: any, labelText: any, min: any, max: any, defaultVal: any, step: any, param: any, fmt: any, scale?: string): HTMLInputElement;
+    _refreshShapeButtons(): void;
+    _refreshBipolarBtn(): void;
+    /**
+     * Reflect effective (post-chain-modulation) rate and depth onto the param
+     * sliders so they visually track the modulated position.  Only touches the
+     * DOM when the effective value actually differs from the displayed value to
+     * avoid unnecessary repaints.
+     */
+    _syncChainedSliders(): void;
+    /**
+     * Remove any indicators whose routes have been deleted externally — e.g. when
+     * the target LFO is destroyed and engine.destroyLFO cleans up incoming routes.
+     * Called each tick so stale badges are cleared within one frame.
+     */
+    _pruneDeadRoutes(): void;
+    _recordSample(currentValue: any): void;
+    _wfBuf: HTMLCanvasElement;
+    _wfBufCtx: CanvasRenderingContext2D;
+    _wfHistory: Float32Array<ArrayBuffer>;
+    _wfSubpx: any;
+    _wfLastTime: number;
+    _wfPrevValue: any;
+    _wfNeedsFullRedraw: boolean;
+    /** Composite _wfBuf → visible canvas + cursor dot. Called from RAF. */
+    _rafDraw(): void;
+    /** Full repaint of _wfBuf from _wfHistory. */
+    _wfPaintFull(bCtx: any, W: any, H: any): void;
+    /**
+     * Scroll _wfBuf left by intShift, fill background+grid in new strip, then
+     * draw only the new right-edge stroke from _wfHistory.
+     */
+    _wfPaintIncremental(bCtx: any, W: any, H: any, intShift: any): void;
+    _wfDrawGrid(bCtx: any, W: any, H: any, x0: any, x1: any): void;
+    /** Stroke _wfHistory[xFrom..xTo] onto bCtx. */
+    _wfDrawHistoryStroke(bCtx: any, W: any, H: any, xFrom: any, xTo: any): void;
+    _updateLed(value: any): void;
+    _attachDragHandlers(handle: any): void;
+    _connectTo(element: any): void;
+    /**
+     * Programmatically connect this LFO to an element.
+     * @param {HTMLElement} element
+     * @param {object}      [opts]
+     * @param {number}      [opts.depth=0.5]
+     * @returns {string|null} routeId, or null if rejected (duplicate, self-mod).
+     */
+    connect(element: HTMLElement, opts?: {
+        depth?: number;
+    }): string | null;
+    /**
+     * Remove a specific modulation route.
+     * @param {string} routeId
+     */
+    disconnectRoute(routeId: string): void;
+    /** Disconnect all routes from this widget. */
+    disconnectAll(): void;
+    /** Tear down the widget and all its connections. */
+    destroy(): void;
+    get element(): HTMLDivElement;
+    get lfoId(): string;
+    get color(): string;
+    get label(): string;
+}
+/**
+ * lfo-ui.js — LFO widget, modulation indicators, and drag-to-assign wiring.
+ *
+ * Provides:
+ *   LFOWidget    — Canvas-based LFO panel with controls and a drag handle.
+ *   ModIndicator — Floating badge anchored to a connected element showing
+ *                  depth and a remove button. Also draws a range arc on range inputs.
+ *
+ * No external dependencies. Requires lfo-engine.js.
+ */
+export const LFO_COLORS: string[];
+/**
+ * Floating badge anchored to a connected input element.
+ * Shows depth, allows drag-to-adjust, and a remove button.
+ */
+export class ModIndicator {
+    /**
+     * @param {HTMLElement} element   Connected input.
+     * @param {string}      routeId
+     * @param {string}      lfoId
+     * @param {string}      color
+     * @param {string}      lfoLabel
+     * @param {function}    onRemove  Called when the user removes this connection.
+     */
+    constructor(element: HTMLElement, routeId: string, lfoId: string, color: string, lfoLabel: string, onRemove: Function);
+    _element: HTMLElement;
+    _routeId: string;
+    _lfoId: string;
+    _color: string;
+    _onRemove: Function;
+    _badge: HTMLDivElement;
+    _arcCanvas: HTMLCanvasElement;
+    _rafId: number;
+    _buildBadge(label: any): void;
+    _depthLabel: HTMLSpanElement;
+    _buildArcCanvas(): void;
+    _arcCtx: CanvasRenderingContext2D;
+    _updateDepthLabel(): void;
+    _startPositioning(): void;
+    _reposition(): void;
+    _badgeSize: {
+        bw: number;
+        bh: number;
+    };
+    _updateArc(): void;
+    destroy(): void;
+    get routeId(): string;
+}
+/**
+ * lfo-engine.js — Core LFO math engine, no DOM dependencies.
+ *
+ * Manages LFO instances, a global RAF tick loop, and a modulation routing
+ * graph. Routes can target HTML elements (range/number inputs) or other
+ * LFO parameters (for chaining).
+ *
+ * Usage:
+ *   import { engine, SHAPES } from './lfo-engine.js';
+ *   const id = engine.createLFO({ shape: 'sine', rate: 2 });
+ *   const routeId = engine.addRoute(id, 'element', sliderEl, null, { depth: 0.5 });
+ */
+export const SHAPES: string[];
+/**
+ * Programmatically connect an LFO to an HTML element.
+ * Equivalent to calling widget.connect(element, opts).
+ *
+ * @param {LFOWidget}   widget
+ * @param {HTMLElement} element
+ * @param {object}      [opts]
+ * @param {number}      [opts.depth=0.5]
+ * @returns {string|null} routeId, or null if connection was rejected.
+ */
+export function connect(widget: LFOWidget, element: HTMLElement, opts?: {
+    depth?: number;
+}): string | null;
+/**
+ * Create a fully wired LFO widget.
+ *
+ * @param {HTMLElement|object} containerOrOpts
+ *   If an HTMLElement, the widget is appended to it and opts is the second arg.
+ *   If an object, treated as opts — caller is responsible for appending widget.element.
+ * @param {object} [opts]
+ * @param {string}   [opts.shape='sine']   Initial waveform shape.
+ * @param {number}   [opts.rate=1]         Initial rate in Hz.
+ * @param {number}   [opts.depth=1]        Initial depth 0–1.
+ * @param {number}   [opts.phase=0]        Initial phase offset 0–1.
+ * @param {number}   [opts.offset=0]       DC offset -1–1.
+ * @param {string}   [opts.color]          Accent color. Auto-assigned if omitted.
+ * @param {string}   [opts.label]          Widget label. Auto-assigned if omitted.
+ * @param {function} [opts.onConnect]      Called when a connection is made.
+ * @param {function} [opts.onDisconnect]   Called when a connection is removed.
+ *
+ * @returns {{ lfoId: string, widget: LFOWidget }}
+ */
+export function createLFO(containerOrOpts?: HTMLElement | object, opts?: {
+    shape?: string;
+    rate?: number;
+    depth?: number;
+    phase?: number;
+    offset?: number;
+    color?: string;
+    label?: string;
+    onConnect?: Function;
+    onDisconnect?: Function;
+}): {
+    lfoId: string;
+    widget: LFOWidget;
+};
+/**
+ * Remove a modulation route and its UI indicator.
+ * Prefer calling widget.disconnectRoute(routeId) directly when you have the widget.
+ * This function handles programmatic routes created via connect() or drag-to-assign.
+ *
+ * @param {string} routeId
+ */
+export function disconnect(routeId: string): void;
+/** Global engine singleton — import and use directly. */
+export const engine: LFOEngine;
+/**
+ * Get all currently active modulation routes.
+ * @returns {object[]}
+ */
+export function getRoutes(): object[];
+export function injectStyles(): void;
+/** Deterministic pseudo-random in [-1, 1] for a given integer seed. */
+export function seededRand(seed: any): number;
+/** Smoothly interpolated random (cubic Hermite) for non-integer phase. */
+export function smoothRand(seed: any, phase: any): number;
+declare class LFOEngine {
+    /** @type {Map<string, LFOState>} */
+    _lfos: Map<string, LFOState>;
+    /** @type {Map<string, RouteState>} */
+    _routes: Map<string, RouteState>;
+    /** @type {Map<HTMLElement, ElementState>} */
+    _elementStates: Map<HTMLElement, ElementState>;
+    /** @type {Set<function>} */
+    _subscribers: Set<Function>;
+    _lastTs: any;
+    _rafId: number;
+    _running: boolean;
+    _tick(ts: any): void;
+    start(): void;
+    stop(): void;
+    /**
+     * Create a new LFO instance.
+     * @param {object} opts
+     * @param {string}  [opts.shape='sine']     Waveform shape. One of SHAPES.
+     * @param {number}  [opts.rate=1]           Frequency in Hz.
+     * @param {number}  [opts.depth=1]          Modulation depth multiplier 0–1.
+     * @param {number}  [opts.phase=0]          Initial phase offset 0–1.
+     * @param {number}  [opts.offset=0]         DC offset added to output, -1–1.
+     * @param {boolean} [opts.bipolar=true]     If false, output is remapped 0–1.
+     * @returns {string} LFO id.
+     */
+    createLFO(opts?: {
+        shape?: string;
+        rate?: number;
+        depth?: number;
+        phase?: number;
+        offset?: number;
+        bipolar?: boolean;
+    }): string;
+    /**
+     * Remove an LFO and all its routes.
+     * @param {string} id
+     */
+    destroyLFO(id: string): void;
+    /**
+     * Add a modulation route.
+     *
+     * For element routes: LFO modulates an HTML input element.
+     *   engine.addRoute(lfoId, 'element', inputEl, null, { depth: 0.5 });
+     *
+     * For LFO-chain routes: LFO modulates another LFO's rate or depth.
+     *   engine.addRoute(lfoId, 'lfo', targetLfoId, 'rate', { depth: 0.3 });
+     *
+     * @param {string}                sourceId
+     * @param {'element'|'lfo'}       targetType
+     * @param {HTMLElement|string}    target      Element or target LFO id.
+     * @param {string|null}           targetParam 'rate'|'depth' for lfo, null for element.
+     * @param {object}                opts
+     * @param {number}  [opts.depth=0.5]  Modulation depth 0–1.
+     * @param {number}  [opts.min]        Override element min.
+     * @param {number}  [opts.max]        Override element max.
+     * @param {number}  [opts.step]       Override element step.
+     * @returns {string|null} Route id, or null if the route was rejected (e.g. self-modulation).
+     */
+    addRoute(sourceId: string, targetType: "element" | "lfo", target: HTMLElement | string, targetParam: string | null, opts?: {
+        depth?: number;
+        min?: number;
+        max?: number;
+        step?: number;
+    }): string | null;
+    /**
+     * Remove a modulation route.
+     * @param {string} routeId
+     */
+    removeRoute(routeId: string): void;
+    /**
+     * Set the depth of an existing route.
+     * @param {string} routeId
+     * @param {number} depth  0–1
+     */
+    setRouteDepth(routeId: string, depth: number): void;
+    /**
+     * Enable or disable a route without removing it.
+     * @param {string}  routeId
+     * @param {boolean} enabled
+     */
+    setRouteEnabled(routeId: string, enabled: boolean): void;
+    /**
+     * Set a parameter on an LFO.
+     * @param {string} lfoId
+     * @param {string} param   'shape'|'rate'|'depth'|'phase'|'offset'|'bipolar'|'baseRate'|'baseDepth'|'jitter'|'skew'
+     * @param {*}      value
+     */
+    setParam(lfoId: string, param: string, value: any): void;
+    /**
+     * Get a parameter from an LFO.
+     * @param {string} lfoId
+     * @param {string} param
+     * @returns {*}
+     */
+    getParam(lfoId: string, param: string): any;
+    /** Get the current output value of an LFO. @param {string} lfoId @returns {number} */
+    getValue(lfoId: string): number;
+    /**
+     * Subscribe to tick notifications. Called each frame for every LFO.
+     * @param {function(lfoId: string, value: number): void} fn
+     * @returns {function} Unsubscribe callback.
+     */
+    subscribe(fn: any): Function;
+    getLFOs(): LFOState[];
+    getLFO(id: any): LFOState;
+    getAllRoutes(): RouteState[];
+    getRoute(id: any): RouteState;
+    getRoutesByElement(element: any): RouteState[];
+    getElementMeta(element: any): ElementState;
+    _initElementState(element: any, opts: any): void;
+    _cleanupElementState(element: any): void;
+    _computeValue(lfo: any, dt: any): any;
+}
+export {};