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

package/dist/components/types.d.ts

@@ -0,0 +1,451 @@
+import { default as React } from 'react';
+import { ContinuousParameter, BooleanParameter, DiscreteParameter, DiscreteOption, ScaleType, AudioParameter, MidiResolution, SizeType, InteractionMode, InteractionDirection } from '@cutoff/audio-ui-core';
+
+export type { SizeType, InteractionMode, InteractionDirection } from '@cutoff/audio-ui-core';
+/**
+ * Variant options for the Knob component
+ */
+export type KnobVariant = "abstract" | "simplest" | "plainCap" | "iconCap";
+/**
+ * Variant options for the Slider component
+ */
+export type SliderVariant = "abstract" | "trackless" | "trackfull" | "stripless";
+/**
+ * Cursor size options for the Slider component.
+ * Determines which component's width is used for the cursor.
+ * - "None": No cursor is rendered
+ * - "Strip": Width of the ValueStrip (if variant supports it)
+ * - "Track": Width of the LinearStrip (track)
+ * - "Tick": Width of the TickStrip (future use)
+ * - "Label": Entire width of the Slider, to the LabelStrip (future use)
+ */
+export type SliderCursorSize = "None" | "Strip" | "Track" | "Tick" | "Label";
+/**
+ * Mode for displaying value vs label.
+ * - "labelOnly": Always shows the label (default)
+ * - "valueOnly": Always shows the value
+ * - "interactive": Shows label normally, but temporarily swaps to value during interaction
+ */
+export type ValueLabelMode = "labelOnly" | "valueOnly" | "interactive";
+/**
+ * Standard event object emitted by all AudioUI controls.
+ * Provides the value in all three domain representations simultaneously.
+ */
+export type AudioControlEvent<T = number> = {
+    /** The real-world value (e.g. -6.0 dB, 440 Hz, true/false) */
+    value: T;
+    /** The normalized value (0.0 to 1.0) used for UI rendering and host automation */
+    normalizedValue: number;
+    /** The MIDI value (integer, e.g. 0-127 or 0-16383) used for hardware/protocol communication */
+    midiValue: number;
+    /** The parameter definition driving this value */
+    parameter?: any;
+};
+/**
+ * Props for interactive controls (drag, wheel, keyboard)
+ * Used by both continuous and enum controls.
+ *
+ * T is the real value type emitted by the control:
+ * - number for continuous controls (Knob, Slider)
+ * - boolean for boolean controls (not commonly using this type)
+ * - custom types for enum-like controls (e.g. CycleButton)
+ */
+export type InteractiveControlProps<T = number> = {
+    /**
+     * Handler for value changes.
+     * Receives a rich event object with real, normalized, and MIDI representations.
+     */
+    onChange?: (event: AudioControlEvent<T>) => void;
+    /**
+     * Interaction mode: drag, wheel, or both.
+     * @default "both"
+     */
+    interactionMode?: InteractionMode;
+    /**
+     * Sensitivity of the control.
+     * Represents the amount of normalized value change per pixel (drag) or unit (wheel).
+     * @default Component-specific
+     */
+    interactionSensitivity?: number;
+    /**
+     * Direction of the interaction.
+     * Overrides the default direction defined by the component's view.
+     */
+    interactionDirection?: InteractionDirection;
+};
+/**
+ * Adaptive sizing props for responsive components
+ */
+export type AdaptiveSizeProps = {
+    /**
+     * Adaptive sizing mode for the component.
+     * When true, the component stretches to fill its container and
+     * ignores the `size` prop for sizing constraints.
+     *
+     * When both `adaptiveSize` and `size` are provided, `adaptiveSize`
+     * takes precedence for sizing behavior.
+     *
+     * @default false
+     */
+    adaptiveSize?: boolean;
+    /** Size of the component
+     * @default 'normal'
+     */
+    size?: SizeType;
+};
+/**
+ * Layout props that control how AdaptiveBox behaves for a control.
+ */
+export type AdaptiveBoxProps = {
+    /**
+     * Layout mode for the control.
+     * - "scaleToFit": Preserve aspect ratio, letterbox within container.
+     * - "fill": Fill container, allowing horizontal stretching of the SVG.
+     *
+     * @default "scaleToFit"
+     */
+    displayMode?: "scaleToFit" | "fill";
+    /**
+     * Visibility of the label row.
+     * - "visible": Render the label and reserve space.
+     * - "hidden": Reserve space but visually hide the label.
+     * - "none": Do not reserve label space.
+     *
+     * @default "visible"
+     */
+    labelMode?: "none" | "hidden" | "visible";
+    /**
+     * Vertical position of the label relative to the control.
+     *
+     * @default "below"
+     */
+    labelPosition?: "above" | "below";
+    /**
+     * Horizontal alignment of the label text within its row.
+     *
+     * @default "center"
+     */
+    labelAlign?: "start" | "center" | "end";
+    /**
+     * How to handle label text overflow.
+     * - "ellipsis": Truncate with ellipsis when text is too long
+     * - "abbreviate": Abbreviate text to 3 characters max (e.g., "Volume" -> "Vol")
+     * - "auto": Automatically abbreviate when viewBoxWidth < viewBoxHeight, otherwise ellipsis
+     *
+     * @default "auto"
+     */
+    labelOverflow?: "ellipsis" | "abbreviate" | "auto";
+    /**
+     * Label height in the same units as SVG viewBox height.
+     * Overrides the default from the view component's static labelHeightUnits property.
+     */
+    labelHeightUnits?: number;
+};
+/**
+ * Logical size props for AdaptiveBox layout calculations.
+ * These correspond to the viewBox and labelHeightUnits properties
+ * from the ControlComponentView interface, but allow per-instance override.
+ */
+export type AdaptiveBoxLogicalSizeProps = {
+    /**
+     * ViewBox width in the same coordinate system as the content.
+     * Overrides the default from the view component's static viewBox.width property.
+     */
+    viewBoxWidthUnits?: number;
+    /**
+     * ViewBox height in the same coordinate system as the content.
+     * Overrides the default from the view component's static viewBox.height property.
+     */
+    viewBoxHeightUnits?: number;
+    /**
+     * Label height in the same units as SVG viewBox height.
+     * Overrides the default from the view component's static labelHeightUnits property.
+     */
+    labelHeightUnits?: number;
+};
+/**
+ * Metadata for a control component.
+ * Used for display in customization interfaces and documentation.
+ */
+export interface ControlComponentMetadata {
+    /** Display name/title for the component */
+    title: string;
+    /** Optional description of what the component does */
+    description?: string;
+}
+/**
+ * Props for themable components
+ */
+export type ThemableProps = {
+    /** Component primary color - any valid CSS color value
+     * @default "blue"
+     */
+    color?: string;
+    /** Roundness for component corners/caps
+     * Normalized value between 0.0 (square) and 1.0 (fully rounded)
+     * @default 0.3
+     */
+    roundness?: number;
+    /** Thickness for component strokes/widths
+     * Normalized value between 0.0 (smallest) and 1.0 (largest)
+     * @default 0.4
+     */
+    thickness?: number;
+};
+/**
+ * BaseProps for all components
+ */
+export type BaseProps = {
+    /** Additional CSS classes */
+    className?: string;
+    /** Additional inline styles */
+    style?: React.CSSProperties;
+    /** Click event handler */
+    onClick?: React.MouseEventHandler;
+    /** Mouse down event handler */
+    onMouseDown?: React.MouseEventHandler;
+    /** Mouse up event handler */
+    onMouseUp?: React.MouseEventHandler;
+    /** Mouse enter event handler */
+    onMouseEnter?: React.MouseEventHandler;
+    /** Mouse leave event handler */
+    onMouseLeave?: React.MouseEventHandler;
+};
+/**
+ * Props for continuous value controls (primitives like ContinuousControl).
+ *
+ * This type is size-agnostic: it does not include AdaptiveSizeProps.
+ * Built-in controls (Knob, Slider) combine this with AdaptiveSizeProps
+ * so only high-level components handle size and stretch.
+ *
+ * Supports two modes:
+ * 1. Parameter model mode: Provide `parameter` (ContinuousParameter) - all range/label info comes from the model
+ * 2. Ad-hoc mode: Provide `min`, `max`, `step`, `label` directly as props
+ *
+ * When `parameter` is provided, it takes precedence over ad-hoc props.
+ */
+export type ContinuousControlProps = BaseProps & InteractiveControlProps<number> & {
+    /** Current value of the control */
+    value: number;
+    /** Label displayed below the component */
+    label?: string;
+    /** Identifier for the parameter this control represents
+     * Used when creating ad-hoc parameters
+     */
+    paramId?: string;
+    /**
+     * Custom renderer for the value display
+     * If provided and returns a value, this function will be used to render the value instead of the default formatter
+     * @param value The current value
+     * @param parameterDef The full parameter definition (includes min, max, unit, scale, etc.)
+     * @returns A string representation of the value, or undefined to fall back to default formatter
+     */
+    valueFormatter?: (value: number, parameterDef: AudioParameter) => string | undefined;
+    /**
+     * Controls how the label and value are displayed.
+     * - "labelOnly": Always shows the label (default)
+     * - "valueOnly": Always shows the value
+     * - "interactive": Shows label normally, but temporarily swaps to value during interaction
+     * @default "labelOnly"
+     */
+    valueAsLabel?: ValueLabelMode;
+    /**
+     * Whether the component should operate in bipolar mode
+     * In bipolar mode, the component visualizes values relative to a center point
+     * rather than from minimum to maximum
+     * @default false
+     */
+    bipolar?: boolean;
+    /**
+     * Audio Parameter definition (Model)
+     * If provided, overrides min/max/step/label/bipolar from ad-hoc props
+     */
+    parameter?: ContinuousParameter;
+    /**
+     * Unit suffix for the value in ad-hoc mode (e.g. "dB", "Hz").
+     * Used only when the internal parameter model is created from the props.
+     * Ignored when a full `parameter` object is provided.
+     */
+    unit?: string;
+    /**
+     * Scale function or shortcut for the parameter in ad-hoc mode.
+     * Controls how the normalized 0..1 range maps to the real value domain.
+     * Common shortcuts are "linear", "log", and "exp".
+     * Ignored when a full `parameter` object is provided.
+     */
+    scale?: ScaleType;
+    /** Minimum value (ad-hoc mode, ignored if parameter provided) */
+    min?: number;
+    /** Maximum value (ad-hoc mode, ignored if parameter provided) */
+    max?: number;
+    /** Step size for value adjustments (ad-hoc mode, ignored if parameter provided)
+     * @default 1 (or calculated based on range)
+     */
+    step?: number;
+    /** MIDI resolution in bits (ad-hoc mode, ignored if parameter provided)
+     * @default 32
+     */
+    midiResolution?: MidiResolution;
+    /** Default value for the parameter (ad-hoc mode, ignored if parameter provided) */
+    defaultValue?: number;
+};
+/**
+ * Props for discrete value controls (primitives like DiscreteControl).
+ *
+ * This type is size-agnostic: it does not include AdaptiveSizeProps.
+ * Built-in controls (CycleButton) combine this with AdaptiveSizeProps
+ * so only high-level components handle size and stretch.
+ *
+ * **Important: Options vs Children**
+ *
+ * - **`options` prop**: Defines the parameter model (value, label, midiValue). Used for parameter structure.
+ * - **`children` (Option components)**: Provides visual content (ReactNodes) for rendering. Used for display.
+ *
+ * These serve different purposes and can be used together:
+ * - Use `options` when you have data-driven option definitions
+ * - Use `children` when you want to provide custom visual content (icons, styled text, etc.)
+ * - Use both: `options` for the model, `children` for visuals (matched by value)
+ *
+ * Supports four modes:
+ * 1. **Ad-Hoc Mode (Options prop)**: Model from `options` prop, visual from `children` (if provided) or default rendering
+ * 2. **Ad-Hoc Mode (Children only)**: Model inferred from OptionView children, visual from children
+ * 3. **Strict Mode (Parameter only)**: Model from `parameter` prop, visual via `renderOption` callback
+ * 4. **Hybrid Mode (Parameter + Children)**: Model from `parameter` prop, visual from children (matched by value)
+ *
+ * When `parameter` is provided, it takes precedence over ad-hoc props.
+ */
+export type DiscreteControlProps = BaseProps & {
+    /** Current value of the control (Controlled mode) */
+    value?: string | number;
+    /** Default value of the component (Uncontrolled mode) */
+    defaultValue?: string | number;
+    /** Handler for value changes */
+    onChange?: (event: AudioControlEvent<string | number>) => void;
+    /** Label displayed below the component */
+    label?: string;
+    /** Identifier for the parameter this control represents
+     * Used when creating ad-hoc parameters
+     */
+    paramId?: string;
+    /**
+     * Audio Parameter definition (Model)
+     * If provided, overrides label/options from ad-hoc props
+     */
+    parameter?: DiscreteParameter;
+    /** Option definitions for the parameter model (Ad-Hoc mode)
+     *
+     * **Parameter Model Only**: This prop defines the parameter structure (value, label, midiValue).
+     * It does NOT provide visual content - use `children` (OptionView components) for that.
+     *
+     * When both `options` and `children` are provided:
+     * - `options` defines the parameter model
+     * - `children` provide visual content (matched by value)
+     */
+    options?: DiscreteOption[];
+    /** Child elements (OptionView components) for visual content mapping (Hybrid/Ad-Hoc mode)
+     *
+     * **Visual Content Only**: Children provide ReactNodes for rendering (icons, text, custom components).
+     * They do NOT define the parameter model - use `options` prop or `parameter` prop for that.
+     *
+     * When both `options` and `children` are provided, children are matched to options by value
+     * to create the visual content map.
+     */
+    children?: React.ReactNode;
+    /** MIDI resolution in bits (ad-hoc mode, ignored if parameter provided)
+     * @default 7
+     */
+    midiResolution?: MidiResolution;
+    /** MIDI mapping strategy (ad-hoc mode, ignored if parameter provided)
+     * @default "spread"
+     */
+    midiMapping?: "spread" | "sequential" | "custom";
+};
+/**
+ * Props for boolean value controls (primitives).
+ *
+ * This type is size-agnostic: it does not include AdaptiveSizeProps.
+ * Built-in controls (Button) combine this with AdaptiveSizeProps
+ * so only high-level components handle size and stretch.
+ *
+ * Supports two modes:
+ * 1. Parameter model mode: Provide `parameter` (BooleanParameter) - all config comes from the model
+ * 2. Ad-hoc mode: Provide `label`, `latch` directly as props
+ *
+ * When `parameter` is provided, it takes precedence over ad-hoc props.
+ */
+export type BooleanControlProps = BaseProps & {
+    /** Current value (must be boolean) */
+    value: boolean;
+    /** Handler for value changes */
+    onChange?: (event: AudioControlEvent<boolean>) => void;
+    /** Label displayed below the component */
+    label?: string;
+    /** Identifier for the parameter this control represents
+     * Used when creating ad-hoc parameters
+     */
+    paramId?: string;
+    /**
+     * Audio Parameter definition (Model)
+     * If provided, overrides label/latch from ad-hoc props
+     */
+    parameter?: BooleanParameter;
+    /** Whether the button should latch (toggle between states) or momentary (only active while pressed)
+     * Ad-hoc mode only, ignored if parameter provided
+     * @default false
+     */
+    latch?: boolean;
+    /** MIDI resolution in bits (ad-hoc mode, ignored if parameter provided)
+     * @default 7
+     */
+    midiResolution?: MidiResolution;
+};
+/**
+ * Contract for a component acting as a visualization for a generic control.
+ * It defines the geometric requirements and interaction behavior.
+ */
+export interface ControlComponentView {
+    /** The viewBox dimensions required by this visualization */
+    viewBox: {
+        width: number;
+        height: number;
+    };
+    /**
+     * Label height in the same units as SVG viewBox height.
+     * Used by AdaptiveBox to calculate layout proportions.
+     */
+    labelHeightUnits?: number;
+    /**
+     * The preferred interaction configuration for this visualization.
+     * This tells the generic control how to interpret user input.
+     */
+    interaction: {
+        /** Supported interaction modes */
+        mode?: InteractionMode;
+        /**
+         * Direction of the interaction gesture.
+         * - vertical: Drag up/down changes value (Standard Faders/Knobs)
+         * - horizontal: Drag left/right changes value
+         * - circular: Drag in a circle around the center changes value (Rotary Knobs)
+         */
+        direction?: InteractionDirection;
+    };
+}
+/**
+ * The minimum props that ANY control view must accept.
+ */
+export interface ControlComponentViewProps {
+    /** The normalized value (0..1) to display */
+    normalizedValue: number;
+    /** Content to be rendered inside the control (e.g. label, icon) */
+    children?: React.ReactNode;
+    /** Optional class name passed from the parent */
+    className?: string;
+    /** Optional style passed from the parent */
+    style?: React.CSSProperties;
+}
+/**
+ * A Generic Component Type that enforces the contract + props.
+ * P = Additional custom props specific to the visualization (e.g. color, thickness).
+ */
+export type ControlComponent<P = Record<string, unknown>> = React.ComponentType<ControlComponentViewProps & P> & ControlComponentView & Partial<ControlComponentMetadata>;
+//# sourceMappingURL=types.d.ts.map

package/dist/components/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/components/types.ts"],"names":[],"mappings":"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"}

package/dist/hooks/useAdaptiveSize.d.ts

@@ -0,0 +1,32 @@
+import { SizeType } from '@cutoff/audio-ui-core';
+
+/**
+ * Hook that encapsulates adaptive sizing logic for components implementing AdaptiveSizeProps.
+ *
+ * Determines sizing behavior based on `adaptiveSize` and `size` props:
+ * - When `adaptiveSize` is true, the component stretches to fill its container (no size constraints)
+ * - When `adaptiveSize` is false, size classes and styles are applied based on the `size` prop
+ *
+ * @param adaptiveSize - Whether the component should stretch to fill its container
+ * @param size - The size value (ignored when adaptiveSize is true)
+ * @param componentType - The type of component ('knob', 'button', 'keys', or 'slider')
+ * @param orientation - Optional orientation for slider components ('vertical' or 'horizontal')
+ * @returns Object containing `sizeClassName` and `sizeStyle`
+ *
+ * @example
+ * ```tsx
+ * const { sizeClassName, sizeStyle } = useAdaptiveSize(
+ *   adaptiveSize,
+ *   size,
+ *   "knob"
+ * );
+ * ```
+ */
+export declare function useAdaptiveSize(adaptiveSize: boolean | undefined, size: SizeType | undefined, componentType: "knob" | "button" | "keys" | "slider", orientation?: "vertical" | "horizontal"): {
+    sizeClassName: string | undefined;
+    sizeStyle: {
+        width: string;
+        height: string;
+    } | undefined;
+};
+//# sourceMappingURL=useAdaptiveSize.d.ts.map

package/dist/hooks/useAdaptiveSize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAdaptiveSize.d.ts","sourceRoot":"","sources":["../../src/hooks/useAdaptiveSize.ts"],"names":[],"mappings":"AAOA,OAAO,EAAsD,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAErG;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAC3B,YAAY,EAAE,OAAO,YAAQ,EAC7B,IAAI,EAAE,QAAQ,YAAW,EACzB,aAAa,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,EACpD,WAAW,CAAC,EAAE,UAAU,GAAG,YAAY;;;;;;EAsB1C"}

package/dist/hooks/useArcAngle.d.ts

@@ -0,0 +1,23 @@
+import { ArcAngleResult } from '@cutoff/audio-ui-core';
+
+export type UseArcAngleResult = ArcAngleResult;
+/**
+ * Hook to calculate 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
+ */
+export declare function useArcAngle(normalizedValue: number, openness?: number, rotation?: number, bipolar?: boolean, positions?: number): UseArcAngleResult;
+//# sourceMappingURL=useArcAngle.d.ts.map

package/dist/hooks/useArcAngle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useArcAngle.d.ts","sourceRoot":"","sources":["../../src/hooks/useArcAngle.ts"],"names":[],"mappings":"AAOA,OAAO,EAAsB,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE3E,MAAM,MAAM,iBAAiB,GAAG,cAAc,CAAC;AAE/C;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,WAAW,CACvB,eAAe,EAAE,MAAM,EACvB,QAAQ,GAAE,MAAW,EACrB,QAAQ,GAAE,MAAU,EACpB,OAAO,GAAE,OAAe,EACxB,SAAS,CAAC,EAAE,MAAM,GACnB,iBAAiB,CAInB"}

package/dist/hooks/useAudioParameter.d.ts

@@ -0,0 +1,89 @@
+import { AudioParameter, AudioParameterConverter } from '@cutoff/audio-ui-core';
+import { AudioControlEvent } from '../components/types';
+
+export interface UseAudioParameterResult {
+    /** The normalized value (0..1) for UI rendering */
+    normalizedValue: number;
+    /** Formatted string representation of the current value */
+    formattedValue: string;
+    /** The effective label to display (computed from userLabel, valueAsLabel, or parameter name) */
+    effectiveLabel: string;
+    /** The full parameter model instance */
+    converter: AudioParameterConverter;
+    /**
+     * Set the value using a normalized (0..1) input.
+     * Automatically denormalizes and calls onChange.
+     */
+    setNormalizedValue: (normalized: number) => void;
+    /**
+     * Adjust the value relatively (e.g. from mouse wheel or drag).
+     * @param delta The amount to change (in normalized units, typically small like 0.01)
+     * @param sensitivity Optional multiplier (default 1.0)
+     */
+    adjustValue: (delta: number, sensitivity?: number) => void;
+    /**
+     * Get the default normalized value (0..1).
+     * Returns the normalized defaultValue from the parameter if defined,
+     * otherwise returns 0.0 for unipolar or 0.5 for bipolar parameters.
+     */
+    getDefaultNormalizedValue: () => number;
+    /**
+     * Reset the value to the default value.
+     * Uses the parameter's defaultValue if defined, otherwise uses 0.0 for unipolar or 0.5 for bipolar.
+     */
+    resetToDefault: () => void;
+}
+/**
+ * Hook to manage audio parameter logic, normalization, and formatting.
+ *
+ * This is the primary hook for connecting audio parameter models to React components.
+ * It handles all value conversions (real ↔ normalized ↔ MIDI) and provides formatted
+ * display values. The hook ensures that all conversions go through the MIDI pivot,
+ * maintaining consistency with hardware standards.
+ *
+ * The hook provides:
+ * - `normalizedValue`: 0..1 value for UI rendering
+ * - `formattedValue`: Formatted string for display
+ * - `converter`: The AudioParameterConverter instance for advanced operations
+ * - `setNormalizedValue`: Set value from normalized input (e.g., from UI slider)
+ * - `adjustValue`: Adjust value relatively (e.g., from mouse wheel or drag)
+ *
+ * @param value The current real-world value (Source of Truth)
+ * @param onChange Callback when value changes. Receives an AudioControlEvent with all value representations.
+ * @param parameterDef The parameter definition (AudioParameter)
+ * @param userValueFormatter Optional custom renderer for the value display. If provided and returns a value, it takes precedence over the default formatter.
+ * @param userLabel Optional custom label. If provided and valueAsLabel is false, takes precedence over parameter name.
+ * @param valueAsLabel When true, displays the formatted value as the label instead of the provided label or parameter name.
+ * @returns Object containing normalizedValue, formattedValue, effectiveLabel, converter, setNormalizedValue, and adjustValue
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * const { normalizedValue, formattedValue, adjustValue } = useAudioParameter(
+ *   volume,
+ *   (e) => setVolume(e.value),
+ *   volumeParam
+ * );
+ *
+ * // With custom label and value formatter
+ * const { normalizedValue, formattedValue, effectiveLabel, adjustValue } = useAudioParameter(
+ *   volume,
+ *   (e) => setVolume(e.value),
+ *   volumeParam,
+ *   (val) => `${val.toFixed(1)} dB`, // Custom formatter
+ *   "Master Volume", // Custom label
+ *   false // Don't use value as label
+ * );
+ *
+ * // Use normalizedValue for rendering
+ * <KnobView normalizedValue={normalizedValue} />
+ *
+ * // Use adjustValue for relative changes
+ * <div onWheel={(e) => adjustValue(e.deltaY, 0.001)} />
+ *
+ * // Use effectiveLabel for display
+ * <label>{effectiveLabel}</label>
+ * ```
+ */
+export declare function useAudioParameter<T extends number | boolean | string>(value: T, onChange: undefined | ((event: AudioControlEvent<T>) => void), parameterDef: AudioParameter, userValueFormatter?: (value: T, parameterDef: AudioParameter) => string | undefined, userLabel?: string, valueAsLabel?: boolean): UseAudioParameterResult;
+//# sourceMappingURL=useAudioParameter.d.ts.map

package/dist/hooks/useAudioParameter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useAudioParameter.d.ts","sourceRoot":"","sources":["../../src/hooks/useAudioParameter.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,MAAM,WAAW,uBAAuB;IACpC,mDAAmD;IACnD,eAAe,EAAE,MAAM,CAAC;IACxB,2DAA2D;IAC3D,cAAc,EAAE,MAAM,CAAC;IACvB,gGAAgG;IAChG,cAAc,EAAE,MAAM,CAAC;IACvB,wCAAwC;IACxC,SAAS,EAAE,uBAAuB,CAAC;IACnC;;;OAGG;IACH,kBAAkB,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD;;;;OAIG;IACH,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3D;;;;OAIG;IACH,yBAAyB,EAAE,MAAM,MAAM,CAAC;IACxC;;;OAGG;IACH,cAAc,EAAE,MAAM,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,GAAG,OAAO,GAAG,MAAM,EACjE,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,SAAS,GAAG,CAAC,CAAC,KAAK,EAAE,iBAAiB,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,EAC7D,YAAY,EAAE,cAAc,EAC5B,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,YAAY,EAAE,cAAc,KAAK,MAAM,GAAG,SAAS,EACnF,SAAS,CAAC,EAAE,MAAM,EAClB,YAAY,CAAC,EAAE,OAAO,GACvB,uBAAuB,CA4GzB"}