react-knob-headless/dist/index.d.ts

Unstyled & accessible knob primitive for React

import * as react from 'react';

type NativeDivProps = React.ComponentProps<'div'>;
type NativeDivPropsToExtend = Omit<NativeDivProps, 'role' | 'aria-valuemin' | 'aria-valuemax' | 'aria-valuenow' | 'aria-valuetext' | 'aria-orientation' | 'aria-label' | 'aria-labelledby' | 'tabIndex'>;
declare const KnobHeadless: react.ForwardRefExoticComponent<(Omit<NativeDivPropsToExtend & {
    readonly 'aria-label': string;
} & {
    /**
     * Current raw value.
     * Make sure it's not rounded.
     */
    readonly valueRaw: number;
    /**
     * Minimum value.
     */
    readonly valueMin: number;
    /**
     * Maximum value.
     */
    readonly valueMax: number;
    /**
     * The sensitivity of the drag gesture. Must be a positive float value.
     * Play with this value in different browsers to find the best one for your use case.
     * Recommended value: 0.006 (quite optimal for most scenarios, so far).
     */
    readonly dragSensitivity: number;
    /**
     * The rounding function for the raw value.
     */
    readonly valueRawRoundFn: (valueRaw: number) => number;
    /**
     * The function for mapping raw value to the human-readable text.
     */
    readonly valueRawDisplayFn: (valueRaw: number) => string;
    /**
     * Callback for when the raw value changes.
     * Note, that you shouldn't round the value here, instead, you have to do it inside "valueRawRoundFn".
     */
    readonly onValueRawChange: (newValueRaw: number) => void;
    /**
     * @DEPRECATED Use "axis" instead.
     *
     * Orientation of the knob and its gesture.
     */
    readonly orientation?: "horizontal" | "vertical" | undefined;
    /**
     * Gesture axis of the knob.
     * Default: "y".
     */
    readonly axis?: "y" | "x" | "xy" | undefined;
    /**
     * Whether to include the element into the sequential tab order.
     * If true, the element will be focusable via the keyboard by tabbing.
     * In most audio applications, the knob is usually controlled by the mouse / touch, so it's not needed.
     */
    readonly includeIntoTabOrder?: boolean | undefined;
    /**
     * Used for mapping the value to the normalized knob position (number from 0 to 1).
     * This is the place for making the interpolation, if non-linear one is required.
     * Example: logarithmic scale of frequency input, when knob center position 0.5 corresponds to ~ 1 kHz (instead of 10.1 kHz which is the "linear" center of frequency range).
     */
    readonly mapTo01?: ((x: number, min: number, max: number) => number) | undefined;
    /**
     * Opposite of `mapTo01`.
     */
    readonly mapFrom01?: ((x: number, min: number, max: number) => number) | undefined;
}, "ref"> | Omit<NativeDivPropsToExtend & {
    readonly 'aria-labelledby': string;
} & {
    /**
     * Current raw value.
     * Make sure it's not rounded.
     */
    readonly valueRaw: number;
    /**
     * Minimum value.
     */
    readonly valueMin: number;
    /**
     * Maximum value.
     */
    readonly valueMax: number;
    /**
     * The sensitivity of the drag gesture. Must be a positive float value.
     * Play with this value in different browsers to find the best one for your use case.
     * Recommended value: 0.006 (quite optimal for most scenarios, so far).
     */
    readonly dragSensitivity: number;
    /**
     * The rounding function for the raw value.
     */
    readonly valueRawRoundFn: (valueRaw: number) => number;
    /**
     * The function for mapping raw value to the human-readable text.
     */
    readonly valueRawDisplayFn: (valueRaw: number) => string;
    /**
     * Callback for when the raw value changes.
     * Note, that you shouldn't round the value here, instead, you have to do it inside "valueRawRoundFn".
     */
    readonly onValueRawChange: (newValueRaw: number) => void;
    /**
     * @DEPRECATED Use "axis" instead.
     *
     * Orientation of the knob and its gesture.
     */
    readonly orientation?: "horizontal" | "vertical" | undefined;
    /**
     * Gesture axis of the knob.
     * Default: "y".
     */
    readonly axis?: "y" | "x" | "xy" | undefined;
    /**
     * Whether to include the element into the sequential tab order.
     * If true, the element will be focusable via the keyboard by tabbing.
     * In most audio applications, the knob is usually controlled by the mouse / touch, so it's not needed.
     */
    readonly includeIntoTabOrder?: boolean | undefined;
    /**
     * Used for mapping the value to the normalized knob position (number from 0 to 1).
     * This is the place for making the interpolation, if non-linear one is required.
     * Example: logarithmic scale of frequency input, when knob center position 0.5 corresponds to ~ 1 kHz (instead of 10.1 kHz which is the "linear" center of frequency range).
     */
    readonly mapTo01?: ((x: number, min: number, max: number) => number) | undefined;
    /**
     * Opposite of `mapTo01`.
     */
    readonly mapFrom01?: ((x: number, min: number, max: number) => number) | undefined;
}, "ref">) & react.RefAttributes<HTMLDivElement>>;

type NativeLabelProps = React.ComponentProps<'label'>;
type NativeLabelPropsToExtend = Omit<NativeLabelProps, 'id'>;
type KnobHeadlessLabelProps = NativeLabelPropsToExtend & {
    readonly id: string;
};
declare const KnobHeadlessLabel: react.ForwardRefExoticComponent<Omit<KnobHeadlessLabelProps, "ref"> & react.RefAttributes<HTMLLabelElement>>;

type NativeOutputProps = React.ComponentProps<'output'>;
type NativeOutputPropsToExtend = Omit<NativeOutputProps, 'htmlFor'>;
type KnobHeadlessOutputProps = NativeOutputPropsToExtend & {
    readonly htmlFor: string;
};
declare const KnobHeadlessOutput: react.ForwardRefExoticComponent<Omit<KnobHeadlessOutputProps, "ref"> & react.RefAttributes<HTMLOutputElement>>;

type UseKnobKeyboardControlsProps = {
    /**
     * Same as `valueRaw` prop of `KnobHeadless`.
     */
    readonly valueRaw: number;
    /**
     * Same as `valueMin` prop of `KnobHeadless`.
     */
    readonly valueMin: number;
    /**
     * Same as `valueMax` prop of `KnobHeadless`.
     */
    readonly valueMax: number;
    /**
     * Step value. Typically it's 1% of the range.
     */
    readonly step: number;
    /**
     * Larger step value. Typically it's 10% of the range.
     */
    readonly stepLarger: number;
    /**
     * Same callback as `KnobHeadless` has, with "event" in 2nd argument.
     */
    readonly onValueRawChange: (newValueRaw: number, event: React.KeyboardEvent) => void;
    /**
     * To prevent scrolling, "event.preventDefault()" is called when the value changes,
     * but for most cases you don't need to change this behaviour.
     * However, if your application needs some more customized one, you can set this prop to true and handle scroll prevention on your own.
     */
    readonly noDefaultPrevention?: boolean;
};
declare const useKnobKeyboardControls: ({ valueRaw, valueMin, valueMax, step, stepLarger, onValueRawChange, noDefaultPrevention, }: UseKnobKeyboardControlsProps) => {
    onKeyDown: React.KeyboardEventHandler;
};

export { KnobHeadless, KnobHeadlessLabel, KnobHeadlessOutput, useKnobKeyboardControls };