@cutoff/audio-ui-core 1.0.0-preview.20260123.1125

package/dist/styles/themes.css

@@ -0,0 +1,193 @@
+/*
+ * Copyright (c) 2026 Tylium.
+ * SPDX-License-Identifier: GPL-3.0-only OR LicenseRef-TELF-1.0
+ * See LICENSE.md for details.
+ */
+
+:root {
+    /* High-level theming parameters – Change this for global theme customization on default components */
+    --audioui-roundness-base: 0.3; /* Normalized 0.0-1.0 */
+    --audioui-primary-color: var(--audioui-adaptive-default-color);
+
+    /* Colors  */
+
+    --audioui-nearwhite: hsl(0, 0%, 96%);
+    --audioui-nearblack: hsl(0, 0%, 10%);
+
+    /* Named color themes */
+    --audioui-theme-blue: hsl(204, 88%, 52%);
+    --audioui-theme-orange: hsl(29, 100%, 48%);
+    --audioui-theme-pink: hsl(332, 92%, 52%);
+    --audioui-theme-green: hsl(160, 95%, 44%);
+    --audioui-theme-purple: hsl(252, 96%, 54%);
+    --audioui-theme-yellow: hsl(50, 100%, 50%);
+
+    /* Default theme — adaptive: dark ink on light, light ink on dark */
+    --audioui-theme-default: var(--audioui-nearblack); /* Light mode: near-black */
+    /* CSS variable for adaptive default - resolves correctly on both server and client */
+    --audioui-adaptive-default-color: var(--audioui-theme-default);
+    --audioui-adaptive-50: color-mix(in srgb, var(--audioui-adaptive-default-color) 50%, transparent);
+    --audioui-adaptive-20: color-mix(in srgb, var(--audioui-adaptive-default-color) 20%, transparent);
+    /* Adaptive luminosity variants - lighter for dark mode, darker for light mode */
+    --audioui-adaptive-light: color-mix(in srgb, var(--audioui-adaptive-default-color) 80%, white);
+    --audioui-adaptive-dark: color-mix(in srgb, var(--audioui-adaptive-default-color) 80%, black);
+
+    /* Color variants (computed via color-mix) */
+    --audioui-primary-50: color-mix(in srgb, var(--audioui-primary-color) 50%, transparent);
+    --audioui-primary-20: color-mix(in srgb, var(--audioui-primary-color) 20%, transparent);
+    /* Primary luminosity variants - lighter and darker versions */
+    --audioui-primary-light: color-mix(in srgb, var(--audioui-primary-color) 80%, white);
+    --audioui-primary-dark: color-mix(in srgb, var(--audioui-primary-color) 80%, black);
+
+    /* Text and typography */
+    --audioui-text-color: var(--audioui-nearblack);
+    --audioui-default-font-size: 14px;
+
+    /* Interactive highlight effect - users can customize or disable entirely */
+    /* Set to 'none' to disable, or any valid CSS filter value for custom effects */
+    --audioui-highlight-effect: brightness(1.15) contrast(1.05)
+        drop-shadow(
+            0 0 0.5em color-mix(in srgb, var(--audioui-primary-color, var(--audioui-text-color)) 35%, transparent)
+        );
+    --audioui-highlight-transition-duration: 50ms;
+
+    /* Cursor styles for interactive components - users can customize cursor types */
+    /* Variables are named after interaction functionality, not cursor type */
+    /* Default cursor values use SVG data URIs to ensure consistent behavior across browsers (fixing Safari regression with variable-based keyword cursors) */
+    --audioui-cursor-clickable: pointer; /* Clickable controls (Button, CycleButton, click-only controls) */
+    --audioui-cursor-bidirectional:
+        url("data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIHZpZXdCb3g9IjAgMCAzMiAzMiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBkPSJNMTYgN3YxOE03IDE2aDE4TTE2IDdsLTQgNE0xNiA3bDQgNE0xNiAyNWwtNC00TTE2IDI1bDQtNE03IDE2bDQtNE03IDE2bDQgNE0yNSAxNmwtNC00TTI1IDE2bC00IDQiIHN0cm9rZT0id2hpdGUiIHN0cm9rZS13aWR0aD0iNCIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIi8+PHBhdGggZD0iTTE2IDd2MThNNyAxNmgxOE0xNiA3bC00IDRNMTYgN2w0IDRNMTYgMjVsLTQtNE0xNiAyNWw0LTRNNyAxNmw0LTRNNyAxNmw0IDRNMjUgMTZsLTQtNE0yNSAxNmwtNCA0IiBzdHJva2U9ImJsYWNrIiBzdHJva2Utd2lkdGg9IjIiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgc3Ryb2tlLWxpbmVqb2luPSJyb3VuZCIvPjwvc3ZnPg==")
+            16 16,
+        move; /* Continuous controls with direction="both" */
+    --audioui-cursor-horizontal:
+        url("data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIHZpZXdCb3g9IjAgMCAzMiAzMiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBkPSJNNyAxNmgxOE03IDE2bDUtNU03IDE2bDUgNU0yNSAxNmwtNS01TTI1IDE2bC01IDUiIHN0cm9rZT0id2hpdGUiIHN0cm9rZS13aWR0aD0iNCIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIi8+PHBhdGggZD0iTTcgMTZoMThNNyAxNmw1LTVNNyAxNmw1IDVNMjUgMTZsLTUtNU0yNSAxNmwtNSA1IiBzdHJva2U9ImJsYWNrIiBzdHJva2Utd2lkdGg9IjIiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgc3Ryb2tlLWxpbmVqb2luPSJyb3VuZCIvPjwvc3ZnPg==")
+            16 16,
+        ew-resize; /* Horizontal drag (horizontal sliders, horizontal knobs) */
+    --audioui-cursor-vertical:
+        url("data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIHZpZXdCb3g9IjAgMCAzMiAzMiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48cGF0aCBkPSJNMTYgN3YxOE0xNiA3bC01IDVNMTYgN2w1IDVNMTYgMjVsLTUtNU0xNiAyNWw1LTUiIHN0cm9rZT0id2hpdGUiIHN0cm9rZS13aWR0aD0iNCIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIi8+PHBhdGggZD0iTTE2IDd2MThNMTYgN2wtNSA1TTE2IDdsNSA1TTE2IDI1bC01LTVNMTYgMjVsNS01IiBzdHJva2U9ImJsYWNrIiBzdHJva2Utd2lkdGg9IjIiIHN0cm9rZS1saW5lY2FwPSJyb3VuZCIgc3Ryb2tlLWxpbmVqb2luPSJyb3VuZCIvPjwvc3ZnPg==")
+            16 16,
+        ns-resize; /* Vertical drag (vertical sliders, wheel-only controls) */
+    --audioui-cursor-circular:
+        url("data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMzIiIGhlaWdodD0iMzIiIHZpZXdCb3g9IjAgMCAzMiAzMiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48Y2lyY2xlIGN4PSIxNiIgY3k9IjE2IiByPSIxMCIgc3Ryb2tlPSJ3aGl0ZSIgc3Ryb2tlLXdpZHRoPSI0Ii8+PGNpcmNsZSBjeD0iMTYiIGN5PSIxNiIgcj0iMTAiIHN0cm9rZT0iYmxhY2siIHN0cm9rZS13aWR0aD0iMiIvPjwvc3ZnPg==")
+            16 16,
+        move; /* Circular drag (knobs with direction="circular") */
+    --audioui-cursor-noneditable: default; /* Non-editable controls */
+    --audioui-cursor-disabled: not-allowed; /* Disabled controls */
+
+    /* Classic Piano Key Colors */
+    --audioui-keys-ivory: hsl(40, 20%, 95%); /* Warm off-white color for classic white keys */
+    --audioui-keys-ivory-stroke: hsl(40, 20%, 85%); /* Slightly darker for stroke contrast */
+    --audioui-keys-ebony: hsl(0, 0%, 15%); /* Deep black color for classic black keys */
+    --audioui-keys-ebony-stroke: hsl(0, 0%, 25%); /* Slightly lighter for stroke contrast */
+
+    /* Other component style customization */
+    --audioui-knob-cap-fill: #303030;
+    --audioui-button-stroke-width: 5px;
+
+    /* Slider component colors */
+    --audioui-slider-track-color: var(
+        --audioui-adaptive-20
+    ); /* Background track color (for all variants except abstract) */
+    --audioui-slider-strip-color: var(--audioui-primary-color); /* Foreground value strip color */
+    --audioui-slider-cursor-color: var(--audioui-primary-color); /* Cursor fill color */
+    --audioui-slider-cursor-border-color: var(
+        --audioui-primary-light
+    ); /* Cursor border color (luminosity variant for visibility) */
+    --audioui-slider-cursor-border-width: 5px; /* Cursor border width */
+
+    /* Component-specific roundness (calculated from base) */
+    --audioui-roundness-button: calc(var(--audioui-roundness-base) * 50px);
+    --audioui-roundness-knob: var(--audioui-roundness-base); /* Used as boolean in JS or linecap in CSS */
+    --audioui-roundness-slider: calc(var(--audioui-roundness-base) * 20px);
+    --audioui-roundness-keys: calc(var(--audioui-roundness-base) * 12px);
+
+    /* Derived Internal Variables - Not intended for direct customization */
+    /* These variables are automatically managed by the roundness attribute via theme setters and hooks */
+    --audioui-linecap-base: round; /* Inferred: 0.0 -> square, >0.0 -> round */
+    --audioui-linecap-knob: var(--audioui-linecap-base);
+    --audioui-linecap-slider: var(--audioui-linecap-base);
+    --audioui-linecap-button: var(--audioui-linecap-base);
+
+    /* Size System - Base Unit */
+    /* The atomic unit for consistent sizing across all components */
+    --audioui-unit: 48px;
+
+    /* Size Multipliers */
+    --audioui-size-mult-xsmall: 1;
+    --audioui-size-mult-small: 1.25;
+    --audioui-size-mult-normal: 1.5;
+    --audioui-size-mult-large: 2;
+    --audioui-size-mult-xlarge: 2.5;
+
+    /* Square Components (1x1): Button, Knob, CycleButton */
+    --audioui-size-square-xsmall: var(--audioui-unit);
+    --audioui-size-square-small: calc(var(--audioui-unit) * var(--audioui-size-mult-small));
+    --audioui-size-square-normal: calc(var(--audioui-unit) * var(--audioui-size-mult-normal));
+    --audioui-size-square-large: calc(var(--audioui-unit) * var(--audioui-size-mult-large));
+    --audioui-size-square-xlarge: calc(var(--audioui-unit) * var(--audioui-size-mult-xlarge));
+
+    /* Horizontal Slider (1x2): height = base, width = 2 * base (width > height) */
+    --audioui-size-hslider-height-xsmall: var(--audioui-unit);
+    --audioui-size-hslider-height-small: calc(var(--audioui-unit) * var(--audioui-size-mult-small));
+    --audioui-size-hslider-height-normal: calc(var(--audioui-unit) * var(--audioui-size-mult-normal));
+    --audioui-size-hslider-height-large: calc(var(--audioui-unit) * var(--audioui-size-mult-large));
+    --audioui-size-hslider-height-xlarge: calc(var(--audioui-unit) * var(--audioui-size-mult-xlarge));
+
+    --audioui-size-hslider-width-xsmall: calc(var(--audioui-size-hslider-height-xsmall) * 2);
+    --audioui-size-hslider-width-small: calc(var(--audioui-size-hslider-height-small) * 2);
+    --audioui-size-hslider-width-normal: calc(var(--audioui-size-hslider-height-normal) * 2);
+    --audioui-size-hslider-width-large: calc(var(--audioui-size-hslider-height-large) * 2);
+    --audioui-size-hslider-width-xlarge: calc(var(--audioui-size-hslider-height-xlarge) * 2);
+
+    /* Vertical Slider (2x1): width = base, height = 2 * base (height > width) */
+    --audioui-size-vslider-width-xsmall: var(--audioui-unit);
+    --audioui-size-vslider-width-small: calc(var(--audioui-unit) * var(--audioui-size-mult-small));
+    --audioui-size-vslider-width-normal: calc(var(--audioui-unit) * var(--audioui-size-mult-normal));
+    --audioui-size-vslider-width-large: calc(var(--audioui-unit) * var(--audioui-size-mult-large));
+    --audioui-size-vslider-width-xlarge: calc(var(--audioui-unit) * var(--audioui-size-mult-xlarge));
+
+    --audioui-size-vslider-height-xsmall: calc(var(--audioui-size-vslider-width-xsmall) * 2);
+    --audioui-size-vslider-height-small: calc(var(--audioui-size-vslider-width-small) * 2);
+    --audioui-size-vslider-height-normal: calc(var(--audioui-size-vslider-width-normal) * 2);
+    --audioui-size-vslider-height-large: calc(var(--audioui-size-vslider-width-large) * 2);
+    --audioui-size-vslider-height-xlarge: calc(var(--audioui-size-vslider-width-xlarge) * 2);
+
+    /* Keys (1x5): height = base, width = 5 * base (width > height) */
+    --audioui-size-keys-height-xsmall: var(--audioui-unit);
+    --audioui-size-keys-height-small: calc(var(--audioui-unit) * var(--audioui-size-mult-small));
+    --audioui-size-keys-height-normal: calc(var(--audioui-unit) * var(--audioui-size-mult-normal));
+    --audioui-size-keys-height-large: calc(var(--audioui-unit) * var(--audioui-size-mult-large));
+    --audioui-size-keys-height-xlarge: calc(var(--audioui-unit) * var(--audioui-size-mult-xlarge));
+
+    --audioui-size-keys-width-xsmall: calc(var(--audioui-size-keys-height-xsmall) * 5);
+    --audioui-size-keys-width-small: calc(var(--audioui-size-keys-height-small) * 5);
+    --audioui-size-keys-width-normal: calc(var(--audioui-size-keys-height-normal) * 5);
+    --audioui-size-keys-width-large: calc(var(--audioui-size-keys-height-large) * 5);
+    --audioui-size-keys-width-xlarge: calc(var(--audioui-size-keys-height-xlarge) * 5);
+}
+
+/* Dark mode overrides */
+.dark {
+    /* Default theme — near-white ink in dark mode */
+    --audioui-theme-default: var(--audioui-nearwhite);
+    /* Adaptive default updates automatically via CSS variable */
+    --audioui-adaptive-default-color: var(--audioui-theme-default);
+
+    /* Named color themes (can have dark mode variants if needed) */
+    --audioui-theme-blue: hsl(204, 88%, 53%);
+    --audioui-theme-orange: hsl(29, 100%, 50%);
+    --audioui-theme-pink: hsl(332, 95%, 54%);
+    --audioui-theme-green: hsl(160, 98%, 37%);
+    --audioui-theme-purple: hsl(252, 100%, 67%);
+    --audioui-theme-yellow: hsl(50, 100%, 50%);
+
+    /* Text color for dark mode */
+    --audioui-text-color: var(--audioui-nearwhite);
+
+    /* Other component style customization */
+    --audioui-knob-cap-fill: #4a4d50;
+
+    --audioui-slider-cursor-border-color: var(
+        --audioui-primary-dark
+    ); /* Cursor border color (luminosity variant for visibility) */
+}

package/dist/types.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Size options for control components
+ */
+export type SizeType = "xsmall" | "small" | "normal" | "large" | "xlarge";
+/**
+ * Interaction modes for controls
+ */
+export type InteractionMode = "drag" | "wheel" | "both";
+/**
+ * Interaction directions for controls
+ */
+export type InteractionDirection = "vertical" | "horizontal" | "circular" | "both";
+/**
+ * MIDI resolution in bits
+ * Supported values: 7, 8, 14, 16, 32, 64
+ */
+export type MidiResolution = 7 | 8 | 14 | 16 | 32 | 64;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE1E;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAExD;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,YAAY,GAAG,UAAU,GAAG,MAAM,CAAC;AAEnF;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC"}

package/dist/utils/colorUtils.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Detects if the current document is in dark mode.
+ *
+ * Checks both the document's class list (for `.dark` class) and the system preference
+ * via `prefers-color-scheme` media query. This ensures compatibility with frameworks
+ * like Tailwind CSS that use class-based dark mode.
+ *
+ * @returns true if dark mode is active, false otherwise
+ */
+export declare function isDarkMode(): boolean;
+/**
+ * Gets the adaptive default color (white in dark mode, black in light mode).
+ *
+ * Uses a CSS variable to ensure SSR and client render the same value, avoiding hydration mismatches.
+ * The actual color value is resolved by the browser based on the `.dark` class or system preference.
+ *
+ * @returns A CSS color value that adapts to the current color scheme
+ */
+export declare function getAdaptiveDefaultColor(): string;
+/**
+ * Generates a luminosity-based variant of a color.
+ *
+ * For named colors (blue, orange, pink, etc.), this function uses pre-computed HSL values
+ * for precise control. For other colors, it uses CSS `color-mix()` with black to darken.
+ *
+ * This is useful for creating visual hierarchies (e.g., primary50, primary20 variants)
+ * where you want progressively darker versions of a color.
+ *
+ * @param baseColor The base color (any valid CSS color value)
+ * @param luminosityPercentage The percentage of the original luminosity (0-100)
+ * @returns A CSS color value with adjusted luminosity
+ *
+ * @example
+ * ```ts
+ * generateLuminosityVariant("blue", 50); // 50% darker blue
+ * generateLuminosityVariant("#ff0000", 20); // Much darker red
+ * ```
+ */
+export declare function generateLuminosityVariant(baseColor: string, luminosityPercentage: number): string;
+/**
+ * Generates a transparency-based variant of a color.
+ *
+ * Uses CSS `color-mix()` to blend the color with transparent, creating a semi-transparent
+ * version. This is useful for hover states, disabled states, or layered visual effects.
+ *
+ * @param baseColor The base color (any valid CSS color value)
+ * @param opacityPercentage The opacity percentage (0-100, where 100 is fully opaque)
+ * @returns A CSS color value with adjusted opacity
+ *
+ * @example
+ * ```ts
+ * generateTransparencyVariant("blue", 50); // 50% transparent blue
+ * ```
+ */
+export declare function generateTransparencyVariant(baseColor: string, opacityPercentage: number): string;
+/**
+ * Generates a highlight color variant suitable for drop-shadow and glow effects.
+ *
+ * For HSL colors, this increases both saturation and lightness to create a brighter,
+ * more vibrant version. For other color formats, it blends with white.
+ *
+ * This is typically used for focus states, active states, or visual feedback effects.
+ *
+ * @param baseColor The base color (any valid CSS color value)
+ * @returns A CSS color value optimized for highlight effects
+ *
+ * @example
+ * ```ts
+ * generateHighlightColor("blue"); // Brighter, more saturated blue for highlights
+ * ```
+ */
+export declare function generateHighlightColor(baseColor: string): string;
+/**
+ * Generates a complete set of color variants for a component.
+ *
+ * This is the main utility for creating theme color palettes. It generates:
+ * - `primary`: The base color
+ * - `primary50`: A 50% variant (luminosity or transparency based on `variant` parameter)
+ * - `primary20`: A 20% variant (luminosity or transparency based on `variant` parameter)
+ * - `highlight`: A brighter variant optimized for focus/active states
+ *
+ * The `variant` parameter determines how `primary50` and `primary20` are calculated:
+ * - `"luminosity"`: Darker versions of the base color (good for backgrounds, tracks)
+ * - `"transparency"`: Semi-transparent versions (good for overlays, disabled states)
+ *
+ * @param baseColor The base color (any valid CSS color value)
+ * @param variant The variant type ('luminosity' or 'transparency')
+ * @returns An object with primary, primary50, primary20, and highlight color values
+ *
+ * @example
+ * ```ts
+ * const colors = generateColorVariants("blue", "luminosity");
+ * // { primary: "hsl(204, 88%, 53%)", primary50: "...", primary20: "...", highlight: "..." }
+ * ```
+ */
+export declare function generateColorVariants(baseColor: string, variant?: "luminosity" | "transparency"): {
+    primary: string;
+    primary50: string;
+    primary20: string;
+    highlight: string;
+};
+//# sourceMappingURL=colorUtils.d.ts.map

package/dist/utils/colorUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"colorUtils.d.ts","sourceRoot":"","sources":["../../src/utils/colorUtils.ts"],"names":[],"mappings":"AA+BA;;;;;;;;GAQG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAKpC;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,GAAG,MAAM,CAgBjG;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,2BAA2B,CAAC,SAAS,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,GAAG,MAAM,CAEhG;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAgBhE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CACjC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,YAAY,GAAG,cAA6B,GACtD;IACC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACrB,CAqBA"}

package/dist/utils/math.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Shared SVG helper utilities for audio-ui components
+ */
+/**
+ * Convert polar coordinates to Cartesian coordinates.
+ *
+ * This function is used extensively in circular controls (knobs, rotary switches) to position
+ * elements around a circle. The angle system follows SVG conventions where 0° is at 3 o'clock
+ * and angles increase clockwise.
+ *
+ * @param centerX - X coordinate of the center point
+ * @param centerY - Y coordinate of the center point
+ * @param radius - Radius from center
+ * @param angleInDegrees - Angle in degrees (0° = 3 o'clock, increasing clockwise)
+ * @returns Object with x and y Cartesian coordinates
+ *
+ * @example
+ * ```ts
+ * // Position at 12 o'clock (top center)
+ * const { x, y } = polarToCartesian(50, 50, 30, 360);
+ * // x ≈ 50, y ≈ 20
+ * ```
+ */
+export declare const polarToCartesian: (centerX: number, centerY: number, radius: number, angleInDegrees: number) => {
+    x: number;
+    y: number;
+};
+/**
+ * Result of arc angle calculations
+ */
+export interface ArcAngleResult {
+    /** Normalized value (0-1, clamped) */
+    normalizedValue: number;
+    /** Openness in degrees (0-360, clamped) */
+    openness: number;
+    /** Start angle of the arc range in degrees (offset by rotation) */
+    startAngle: number;
+    /** End angle of the arc range in degrees (offset by rotation) */
+    endAngle: number;
+    /** Current angle in degrees based on normalized value (offset by rotation) */
+    valueToAngle: number;
+    /** Start angle for the value arc (foreground). Handles bipolar logic (starts at center) vs unipolar (starts at range start). */
+    valueStartAngle: number;
+}
+/**
+ * Calculates arc angles for rotary controls (ValueRing, RotaryImage components, or any other circular control).
+ *
+ * Calculates the angular range based on openness and converts a normalized value (0-1)
+ * to an angle within that range.
+ *
+ * The angle system:
+ * - 0 degrees is at 3 o'clock, increasing clockwise
+ * - Standard knob (90° openness) goes from ~225° (7:30) to ~495° (4:30)
+ * - 360° corresponds to UP (12 o'clock)
+ *
+ * @param normalizedValue Normalized value between 0 and 1
+ * @param openness Openness of the arc in degrees (0-360, default 90)
+ * @param rotation Rotation angle offset in degrees (default 0)
+ * @param bipolar Whether to start the value arc from the center (12 o'clock) instead of the start angle (default false)
+ * @param positions Optional number of discrete positions. When defined, the value will snap to the nearest position. Defaults to undefined (continuous mode).
+ * @returns Calculated angles and normalized values
+ *
+ * @example
+ * ```ts
+ * // Standard knob at 50% value
+ * const result = calculateArcAngles(0.5, 90);
+ * // result.valueToAngle = 360 (12 o'clock)
+ * // result.startAngle = 225 (7:30)
+ * // result.endAngle = 495 (4:30)
+ *
+ * // Bipolar knob (pan control) at center
+ * const bipolar = calculateArcAngles(0.5, 90, 0, true);
+ * // bipolar.valueStartAngle = 360 (starts from center)
+ *
+ * // Discrete positions (5-way switch)
+ * const discrete = calculateArcAngles(0.37, 90, 0, false, 5);
+ * // discrete.normalizedValue = 0.25 (snapped to nearest position)
+ * ```
+ */
+export declare function calculateArcAngles(normalizedValue: number, openness?: number, rotation?: number, bipolar?: boolean, positions?: number): ArcAngleResult;
+/**
+ * Calculates the cursor Y position for linear controls (sliders, faders).
+ *
+ * The cursor represents the current value position along a linear strip.
+ * The strip extends along the Y-axis (in unrotated coordinate space) from
+ * (cy - length/2) to (cy + length/2).
+ *
+ * The cursor position is independent of bipolar mode - it always maps:
+ * - value 0 = bottom (cy + length/2)
+ * - value 1 = top (cy - length/2)
+ *
+ * Bipolar mode only affects how the rectangle is drawn (from center vs from bottom),
+ * not the cursor position itself.
+ *
+ * @param cy Y coordinate of the strip center point
+ * @param length Length of the strip
+ * @param normalizedValue Normalized value between 0 and 1
+ * @returns Y coordinate of the cursor center
+ *
+ * @example
+ * ```ts
+ * // Cursor moves from bottom to top based on value
+ * const cursorY = calculateLinearPosition(150, 260, 0.65);
+ * // cursorY = 31 (65% from bottom to top)
+ * ```
+ */
+export declare function calculateLinearPosition(cy: number, length: number, normalizedValue: number): number;
+//# sourceMappingURL=math.d.ts.map

package/dist/utils/math.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"math.d.ts","sourceRoot":"","sources":["../../src/utils/math.ts"],"names":[],"mappings":"AAMA;;GAEG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,gBAAgB,GACzB,SAAS,MAAM,EACf,SAAS,MAAM,EACf,QAAQ,MAAM,EACd,gBAAgB,MAAM,KACvB;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAMxB,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B,sCAAsC;IACtC,eAAe,EAAE,MAAM,CAAC;IACxB,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,YAAY,EAAE,MAAM,CAAC;IACrB,gIAAgI;IAChI,eAAe,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,kBAAkB,CAC9B,eAAe,EAAE,MAAM,EACvB,QAAQ,GAAE,MAAW,EACrB,QAAQ,GAAE,MAAU,EACpB,OAAO,GAAE,OAAe,EACxB,SAAS,CAAC,EAAE,MAAM,GACnB,cAAc,CA6ChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM,CAQnG"}

package/dist/utils/normalizedProps.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Utility functions for translating normalized (0.0-1.0) roundness and thickness values
+ * to component-specific legacy ranges.
+ *
+ * All components accept normalized values (0.0-1.0) and translate them internally
+ * to their legacy ranges for rendering.
+ */
+/**
+ * Clamp a value to the 0.0-1.0 range
+ */
+export declare function clampNormalized(value: number): number;
+/**
+ * Translate normalized roundness (0.0-1.0) to KnobView legacy value.
+ * 0.0 = square (legacy: 0), >0.0 = round (legacy: 1+)
+ */
+export declare function translateKnobRoundness(normalized: number): number;
+export declare function translateKnobThickness(normalized: number): number;
+export declare function translateSliderRoundness(normalized: number): number;
+export declare function translateSliderThickness(normalized: number): number;
+export declare function translateButtonRoundness(normalized: number): number;
+export declare function translateKeysRoundness(normalized: number): number;
+//# sourceMappingURL=normalizedProps.d.ts.map

package/dist/utils/normalizedProps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizedProps.d.ts","sourceRoot":"","sources":["../../src/utils/normalizedProps.ts"],"names":[],"mappings":"AAMA;;;;;;GAMG;AAEH;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAErD;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAGjE;AAED,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAGjE;AAED,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAGnE;AAED,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAGnE;AAED,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAGnE;AAED,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAGjE"}

package/dist/utils/noteUtils.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Utility functions for working with musical notes and MIDI note numbers
+ *
+ * Terminology:
+ * - Note: A pitch with octave (e.g., "C4", "F#5")
+ * - NoteName: The actual note without octave (e.g., "C", "F#")
+ * - NoteNum: The MIDI note number (e.g., 60 for C4)
+ */
+/**
+ * Array of note names in chromatic order (C to B with sharps)
+ */
+export declare const CHROMATIC_NOTES: readonly ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"];
+/**
+ * Array of white key note names in order (C to B)
+ */
+export declare const WHITE_KEY_NAMES: readonly ["C", "D", "E", "F", "G", "A", "B"];
+/**
+ * Mapping from white key index to chromatic offset
+ * This represents the semitone positions of white keys in a standard piano layout
+ * C=0, D=2, E=4, F=5, G=7, A=9, B=11
+ */
+export declare const WHITE_KEY_TO_CHROMATIC: readonly [0, 2, 4, 5, 7, 9, 11];
+/**
+ * Mapping from diatonic note names to chromatic indices
+ */
+export declare const DIATONIC_TO_CHROMATIC: Record<string, number>;
+/**
+ * Set of chromatic positions that correspond to white keys (C, D, E, F, G, A, B)
+ * Used to determine if a note is a white key or black key
+ */
+export declare const WHITE_KEY_POSITIONS: Set<number>;
+/**
+ * Converts a MIDI note number to a note string using a pre-computed lookup table
+ * MIDI note 60 is middle C (C4)
+ *
+ * @param noteNum - The MIDI note number to convert
+ * @returns The corresponding note (e.g., "C4", "F#5")
+ */
+export declare const noteNumToNote: (noteNum: number) => string;
+/**
+ * Converts a note string to a MIDI note number using a pre-computed lookup table
+ *
+ * @param note - The note to convert (e.g., "C4", "F#5")
+ * @returns The corresponding MIDI note number, or -1 if the note is invalid
+ */
+export declare const noteToNoteNum: (note: string) => number;
+/**
+ * Creates a Set of MIDI note numbers from an array of notes (strings and/or numbers)
+ * This can be used for efficient note lookups, especially when memoized in components
+ *
+ * @param notesOn - Array of notes that are on (can contain string notes and/or MIDI note numbers)
+ * @returns A Set of MIDI note numbers
+ */
+export declare const createNoteNumSet: (notesOn: (string | number)[]) => Set<number>;
+/**
+ * Checks if a note is in the notesOn array, handling both string notes and MIDI note numbers
+ * Uses a Set for O(1) lookups instead of array includes
+ *
+ * @param noteInput - The note to check (either a string note like "C4" or a MIDI note number)
+ * @param notesOn - Array of notes that are on (can contain string notes and/or MIDI note numbers)
+ * @returns True if the note is in the notesOn array, false otherwise
+ */
+export declare const isNoteOn: (noteInput: string | number, notesOn: (string | number)[]) => boolean;
+/**
+ * Checks if a given MIDI note number corresponds to a black key
+ *
+ * @param noteNum - The MIDI note number
+ * @returns true if black key, false if white key
+ */
+export declare const isBlackKey: (noteNum: number) => boolean;
+//# sourceMappingURL=noteUtils.d.ts.map

package/dist/utils/noteUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"noteUtils.d.ts","sourceRoot":"","sources":["../../src/utils/noteUtils.ts"],"names":[],"mappings":"AAMA;;;;;;;GAOG;AAEH;;GAEG;AACH,eAAO,MAAM,eAAe,4EAA6E,CAAC;AAE1G;;GAEG;AACH,eAAO,MAAM,eAAe,8CAA+C,CAAC;AAE5E;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,iCAAkC,CAAC;AAEtE;;GAEG;AACH,eAAO,MAAM,qBAAqB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAQxD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,mBAAmB,aAAkC,CAAC;AAsBnE;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GAAI,SAAS,MAAM,KAAG,MAW/C,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,MAAM,KAAG,MAoB5C,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,KAAG,GAAG,CAAC,MAAM,CAiBzE,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,GAAI,WAAW,MAAM,GAAG,MAAM,EAAE,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,KAAG,OAcnF,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,UAAU,GAAI,SAAS,MAAM,KAAG,OAM5C,CAAC"}

package/dist/utils/propCompare.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Creates a comparison function for memoization to prevent unnecessary re-renders.
+ *
+ * This utility creates a function that performs shallow comparison of primitive props
+ * and uses fast-deep-equal for deep comparison of objects like style.
+ *
+ * @param options - Configuration options for the comparison
+ * @param options.deepCompareProps - Array of prop names that should be deeply compared
+ * @param options.alwaysCompareProps - Array of prop names that should always be directly compared (===)
+ * @returns A comparison function
+ *
+ * @example
+ * // Basic usage with style deep comparison
+ * const comparator = createPropComparator({
+ *   deepCompareProps: ['style']
+ * });
+ */
+export declare function createPropComparator<T extends Record<string, unknown>>({ deepCompareProps, alwaysCompareProps, }?: {
+    deepCompareProps?: Array<keyof T>;
+    alwaysCompareProps?: Array<keyof T>;
+}): (prevProps: T, nextProps: T) => boolean;
+//# sourceMappingURL=propCompare.d.ts.map

package/dist/utils/propCompare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"propCompare.d.ts","sourceRoot":"","sources":["../../src/utils/propCompare.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EACpE,gBAA4B,EAC5B,kBAAiC,GACpC,GAAE;IACC,gBAAgB,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;IAClC,kBAAkB,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;CAClC,IAK4B,WAAW,CAAC,EAAE,WAAW,CAAC,KAAG,OAAO,CA4BrE"}

package/dist/utils/sizing.d.ts

@@ -0,0 +1,39 @@
+import { SizeType } from '../types';
+
+/**
+ * Maps size values to CSS class names for square components (Button, Knob, CycleButton)
+ */
+export declare const squareSizeClassMap: Record<SizeType, string>;
+/**
+ * Maps size values to CSS class names for horizontal slider
+ */
+export declare const horizontalSliderSizeClassMap: Record<SizeType, string>;
+/**
+ * Maps size values to CSS class names for vertical slider
+ */
+export declare const verticalSliderSizeClassMap: Record<SizeType, string>;
+/**
+ * Maps size values to CSS class names for keys
+ */
+export declare const keysSizeClassMap: Record<SizeType, string>;
+/**
+ * Gets the appropriate size class name for a component
+ * @param componentType The type of component ('knob', 'button', 'keys', or 'slider')
+ * @param size The size value
+ * @param orientation The orientation for slider components ('vertical' or 'horizontal')
+ * @returns The CSS class name for the component size
+ */
+export declare function getSizeClassForComponent(componentType: "knob" | "button" | "keys" | "slider", size?: SizeType, orientation?: "vertical" | "horizontal"): string;
+/**
+ * Gets the CSS variable references for a component's size dimensions.
+ * Used to apply size as inline styles (which override AdaptiveBox's default 100%).
+ * @param componentType The type of component ('knob', 'button', 'keys', or 'slider')
+ * @param size The size value
+ * @param orientation The orientation for slider components ('vertical' or 'horizontal')
+ * @returns An object with width and height CSS variable references
+ */
+export declare function getSizeStyleForComponent(componentType: "knob" | "button" | "keys" | "slider", size?: SizeType, orientation?: "vertical" | "horizontal"): {
+    width: string;
+    height: string;
+};
+//# sourceMappingURL=sizing.d.ts.map

package/dist/utils/sizing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sizing.d.ts","sourceRoot":"","sources":["../../src/utils/sizing.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEpC;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAMvD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,4BAA4B,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAMjE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,0BAA0B,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAM/D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAMrD,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACpC,aAAa,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,EACpD,IAAI,GAAE,QAAmB,EACzB,WAAW,GAAE,UAAU,GAAG,YAAyB,GACpD,MAAM,CAYR;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACpC,aAAa,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,EACpD,IAAI,GAAE,QAAmB,EACzB,WAAW,GAAE,UAAU,GAAG,YAAyB,GACpD;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CA4BnC"}

package/dist/utils/svg.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Calculate SVG arc path for circular controls (like knobs).
+ *
+ * This function generates the SVG path data for drawing arcs, which is essential for rendering
+ * circular controls. The path is rounded to avoid hydration mismatches between server and client.
+ *
+ * The angle system follows SVG conventions:
+ * - 0° is at 3 o'clock (right)
+ * - Angles increase clockwise
+ * - 360° is at 12 o'clock (top)
+ *
+ * @param cx - X coordinate of the center point
+ * @param cy - Y coordinate of the center point
+ * @param startAngle - Starting angle in degrees
+ * @param endAngle - Ending angle in degrees
+ * @param radius - Radius of the arc
+ * @param direction - Direction to draw the arc. "counter-clockwise" (default) draws from End to Start (standard for static shapes). "clockwise" draws from Start to End (useful for path animations).
+ * @returns SVG path string for the arc (e.g., "M 10 20 A 30 30 0 0 1 40 50")
+ *
+ * @example
+ * ```ts
+ * // Draw a 90-degree arc from 7:30 to 4:30 (standard knob range)
+ * const path = calculateArcPath(50, 50, 225, 495, 30);
+ * ```
+ */
+export declare const calculateArcPath: (cx: number, cy: number, startAngle: number, endAngle: number, radius: number, direction?: "clockwise" | "counter-clockwise") => string;
+//# sourceMappingURL=svg.d.ts.map

package/dist/utils/svg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"svg.d.ts","sourceRoot":"","sources":["../../src/utils/svg.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,gBAAgB,GACzB,IAAI,MAAM,EACV,IAAI,MAAM,EACV,YAAY,MAAM,EAClB,UAAU,MAAM,EAChB,QAAQ,MAAM,EACd,YAAW,WAAW,GAAG,mBAAyC,KACnE,MAgBF,CAAC"}