@tremolo-ui/react 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -1,27 +1,23 @@
 import * as _$react from "react";
-import React$1, { CSSProperties, ComponentPropsWithoutRef, DependencyList, ReactElement, ReactNode, Ref, RefObject, SVGProps } from "react";
-import { InputEventOption } from "@tremolo-ui/functions";
+import React, { CSSProperties, ComponentPropsWithoutRef, DependencyList, ReactElement, ReactNode, Ref, RefObject, SVGProps } from "react";
 import * as _$_tremolo_ui_dom0 from "@tremolo-ui/dom";
-import { MIDIAccessError, NOT_SUPPORTED, PERMISSION_DENIED } from "@tremolo-ui/dom";
+import { AnimationFrame, AxisOptions, MIDIAccessError, NOT_SUPPORTED, PERMISSION_DENIED, WheelOptions, XY, XY as XY$1, XYInput, XYInput as XYInput$1 } from "@tremolo-ui/dom";
+import { InputEventOption, NoteRange, Scale, Units, ValueRange } from "@tremolo-ui/functions";
 
 //#region src/components/AnimationCanvas/index.d.ts
 type InitFunction = (context: CanvasRenderingContext2D, option: {
   /** current canvas width */width: number; /** current canvas height */
   height: number;
 }) => void;
-type DrawFunction = (context: CanvasRenderingContext2D, option: {
-  /** current canvas width */width: number; /** current canvas height */
-  height: number; /** frame count */
-  count: number; /** delta time (ms) */
-  deltaTime: number; /** elapsed time (ms) */
-  elapsedTime: number; /** frame per second */
-  fps: number;
-}) => void;
+type DrawFunction = (context: CanvasRenderingContext2D, option: AnimationFrame) => void;
 interface CommonProps {
   draw: DrawFunction;
   init?: InitFunction;
   animate?: boolean;
   /**
+   * Read once, when the 2D context is created, so changing it later has no
+   * effect. Passing a fresh object on every render is therefore harmless.
+   *
    * @see https://developer.mozilla.org/docs/Web/API/HTMLCanvasElement/getContext#contextattributes
    */
   options?: CanvasRenderingContext2DSettings;
@@ -67,22 +63,22 @@ declare function InactiveLine({
   ...props
 }: Omit<SVGProps<SVGPathElement>, 'd'>): _$react.JSX.Element;
 //#endregion
-//#region src/components/_util/type.d.ts
-type Override<T, U> = T & Omit<U, keyof T>;
-//#endregion
 //#region src/components/Knob/SVGRoot.d.ts
-interface SVGRoot {
-  block?: boolean;
-  overflowVisible?: boolean;
+interface SVGRootProps {
+  /**
+   * `<Knob.InactiveLine />`, `<Knob.ActiveLine />` and `<Knob.Thumb />` go
+   * here, in the order you want them painted.
+   */
+  children: ReactNode;
 }
 declare function SVGRoot({
   children,
   style,
   ...props
-}: Override<SVGRoot, SVGProps<SVGSVGElement>>): _$react.JSX.Element;
+}: SVGRootProps & Omit<SVGProps<SVGSVGElement>, keyof SVGRootProps>): _$react.JSX.Element;
 //#endregion
 //#region src/components/Knob/Thumb.d.ts
-interface Props {
+interface Props$1 {
   /** color */
   thumb?: string;
   /** color */
@@ -98,7 +94,7 @@ interface Props {
     thumbLine?: string;
   };
 }
-declare function Thumb({
+declare function Thumb$2({
   className,
   thumb,
   thumbLine,
@@ -107,7 +103,7 @@ declare function Thumb({
   thumbLineLength,
   classes,
   ...props
-}: Props & Omit<SVGProps<SVGSVGElement>, 'd' | keyof Props>): _$react.JSX.Element;
+}: Props$1 & Omit<SVGProps<SVGSVGElement>, 'd' | keyof Props$1>): _$react.JSX.Element;
 //#endregion
 //#region src/components/Knob/index.d.ts
 interface KnobProps {
@@ -115,7 +111,16 @@ interface KnobProps {
   min: number;
   max: number;
   step?: number;
-  skew?: number;
+  /**
+   * How the value is distributed across the travel.
+   *
+   * Pick one of the scales from `@tremolo-ui/functions`: `linearScale`,
+   * `exponentialScale`, `curveScale(n)`, `symmetricSkewScale(n)`, or
+   * `skewScale(n)` for a value that has to match a JUCE parameter.
+   *
+   * @default linearScale
+   */
+  scale?: Scale;
   /**
    * value set when double-clicking
    * restriction: enableDoubleClickDefault = true
@@ -129,6 +134,10 @@ interface KnobProps {
    */
   startValue?: number;
   /** width and height */
+  /**
+   * Width and height of the knob.
+   * Defaults to the `--knob-size` CSS variable (50px).
+   */
   size?: number | string;
   /**
    * Global style to apply when dragged
@@ -154,6 +163,20 @@ interface KnobProps {
   /** angle range [degree] */
   angleRange?: number;
   onChange?: (value: number) => void;
+  /**
+   * The knob renders exactly what you compose here; there is no default
+   * markup to fall back to.
+   *
+   * @example
+   * <Knob.Root value={value} min={0} max={100} onChange={setValue}>
+   *   <Knob.SVGRoot>
+   *     <Knob.InactiveLine />
+   *     <Knob.ActiveLine />
+   *     <Knob.Thumb />
+   *   </Knob.SVGRoot>
+   * </Knob.Root>
+   */
+  children: ReactNode;
 }
 interface KnobMethods {
   focus: () => void;
@@ -167,67 +190,148 @@ declare const Knob: {
   SVGRoot: typeof SVGRoot;
   InactiveLine: typeof InactiveLine;
   ActiveLine: typeof ActiveLine;
-  Thumb: typeof Thumb;
+  Thumb: typeof Thumb$2;
 };
 //#endregion
-//#region src/components/NumberInput/DecrementStepper.d.ts
-interface DecrementStepperProps {
-  size?: number;
+//#region src/components/NumberInput/stepperButton.d.ts
+interface StepperButtonProps {
+  className?: string;
+  style?: CSSProperties;
+  /** Replaces the default arrow. Size it with the `--stepper-icon-size` variable. */
   children?: ReactNode;
 }
-declare function DecrementStepper({
-  size,
-  children,
-  className,
-  ...props
-}: DecrementStepperProps & Omit<ComponentPropsWithoutRef<'div'>, keyof DecrementStepperProps>): _$react.JSX.Element;
+//#endregion
+//#region src/components/NumberInput/DecrementStepper.d.ts
+type DecrementStepperProps = StepperButtonProps;
+/** Lowers the value by one `step`, repeating while held. */
+declare function DecrementStepper(props: DecrementStepperProps & Omit<ComponentPropsWithoutRef<'div'>, keyof DecrementStepperProps>): _$react.JSX.Element;
 //#endregion
 //#region src/components/NumberInput/IncrementStepper.d.ts
-interface IncrementStepperProps {
-  size?: number;
-  children?: ReactNode;
+type IncrementStepperProps = StepperButtonProps;
+/** Raises the value by one `step`, repeating while held. */
+declare function IncrementStepper(props: IncrementStepperProps & Omit<ComponentPropsWithoutRef<'div'>, keyof IncrementStepperProps>): _$react.JSX.Element;
+//#endregion
+//#region src/components/NumberInput/InputField.d.ts
+interface NumberInputFieldProps {
+  /**
+   * Select the text when the input takes focus. `'number'` selects the leading
+   * number, leaving whatever the format appended to it.
+   * @default 'none'
+   */
+  selectOnFocus?: 'all' | 'number' | 'none';
+  /**
+   * Commit and leave the input when Enter is pressed. Enter commits either way.
+   * @default true
+   */
+  blurOnEnter?: boolean;
+  className?: string;
+  style?: CSSProperties;
+  ref?: Ref<HTMLInputElement>;
 }
-declare function IncrementStepper({
-  size,
-  children,
+/**
+ * The text field of a `NumberInput`, and the only place the value can be typed.
+ *
+ * While the user types, their own text stands rather than `format(value)`, so
+ * that a half-finished entry is not rewritten under the caret.
+ */
+declare function InputField({
+  selectOnFocus,
+  blurOnEnter,
   className,
+  style,
+  ref,
+  onFocus,
+  onBlur,
+  onKeyDown,
   ...props
-}: IncrementStepperProps & Omit<ComponentPropsWithoutRef<'div'>, keyof IncrementStepperProps>): _$react.JSX.Element;
+}: NumberInputFieldProps & Omit<ComponentPropsWithoutRef<'input'>, keyof NumberInputFieldProps | 'type' | 'value' | 'defaultValue'>): _$react.JSX.Element;
 //#endregion
 //#region src/components/NumberInput/Stepper.d.ts
 interface StepperProps {
-  /** Display only when hovering. */
-  dynamic?: boolean;
+  className?: string;
+  style?: CSSProperties;
+  /** `<NumberInput.IncrementStepper />` and `<NumberInput.DecrementStepper />` go here. */
   children?: ReactNode;
+  ref?: Ref<HTMLDivElement>;
 }
+/**
+ * The area the steppers sit in, and a drag handle in its own right: dragging it
+ * up and down moves the value one `step` every `drag` pixels.
+ *
+ * The drag lives here rather than on `InputField` because `createDrag` turns
+ * off text selection on whatever element it is attached to.
+ */
 declare function Stepper({
-  dynamic,
-  children,
   className,
+  style,
+  children,
+  ref,
   ...props
 }: StepperProps & Omit<ComponentPropsWithoutRef<'div'>, keyof StepperProps>): _$react.JSX.Element;
 //#endregion
-//#region src/components/NumberInput/type.d.ts
+//#region src/components/NumberInput/context.d.ts
+type NumberInputContextValue = {
+  value: number;
+  /**
+   * The range the caller asked for. Left undefined when unbounded, which is
+   * what `aria-valuemin` / `aria-valuemax` and the steppers need to tell apart
+   * from a range that happens to sit at the edge of the safe integers.
+   */
+  min?: number;
+  max?: number;
+  step: number; /** How the value is distributed across the travel. */
+  scale: Scale;
+  disabled: boolean;
+  readonly: boolean;
+  clampValue: boolean;
+  /**
+   * The effective scaling for `applyDelta` and for clamping on commit, with the
+   * unbounded ends filled in. Ignores `min` / `max` when `clampValue` is off.
+   */
+  range: ValueRange;
+  keyboard: InputEventOption | null; /** Pixels of vertical drag on `Stepper` that move the value by one `step`. */
+  drag: number | null; /** What the input shows: the draft while editing, the formatted value otherwise. */
+  text: string;
+  editing: boolean; /** Whether the value sits outside `min` / `max`. Not judged while editing. */
+  outOfRange: boolean; /** Whether a stepper would have no effect, for `aria-disabled`. */
+  atMin: boolean;
+  atMax: boolean;
+  format: (value: number) => string;
+  parse: (text: string) => number; /** Typing. Replaces the draft and reports the parsed value, unclamped. */
+  setDraft: (text: string) => void; /** Blur or Enter. Clamps the draft, reports it, and drops the draft. */
+  commitDraft: () => void; /** Drops the draft and replaces the value: steppers, wheel, keyboard, drag. */
+  changeValue: (next: number) => void; /** Moves the value by one `option` in `direction`, normally +1 or -1. */
+  nudge: (direction: number, option: InputEventOption) => void; /** `InputField` registers itself here; `Root` focuses it through its methods. */
+  inputRef: RefObject<HTMLInputElement | null>;
+};
 /**
- * [unit, scale][]
- * @example
- * [['Hz', 1], ['kHz', 1000]]
+ * The only state behind this is the editing draft; `value` comes from the props
+ * of `Root` and everything else is derived during render.
  */
-type Units = [string, number][];
+declare function useNumberInputContext(): NumberInputContextValue;
+declare function useNumberInputContext<T>(selector: (state: NumberInputContextValue) => T): T;
 //#endregion
 //#region src/components/NumberInput/index.d.ts
 interface NumberInputProps {
-  value: number | string;
   /**
-   * Number.MIN_SAFE_INTEGER
+   * The value. What the input shows is `format(value)`, except while the user
+   * is typing, when their own text stands until it is committed.
    */
+  value: number;
   min?: number;
-  /**
-   * Number.MAX_SAFE_INTEGER
-   */
   max?: number;
   step?: number;
   /**
+   * How the value is distributed across the travel of a drag or a
+   * `'normalized'` wheel / keyboard nudge.
+   *
+   * @default linearScale
+   */
+  scale?: Scale;
+  /**
+   * Unit to display the value in, or a list to pick from by magnitude.
+   * Builds the default `format` and `parse`.
+   *
    * @example
    * units='Hz'
    * units={[['Hz', 1], ['kHz', 1000]]}
@@ -235,23 +339,26 @@ interface NumberInputProps {
    */
   units?: string | Units;
   /**
-   * Digits for rounding numbers.
+   * Digits after the decimal point, for the default `format`.
+   *
    * @example
-   * with:
-   * units={[['Hz', 1], ['kHz', 1000]]}
-   * digit={3}
-   * results:
-   * value=100 -> 100Hz, value=1600 -> 1.60Hz
+   * // units={[['Hz', 1], ['kHz', 1000]]} digit={2}
+   * // 100 -> 100.00Hz, 1600 -> 1.60kHz
    */
   digit?: number;
-  readonly?: boolean;
-  variant?: 'outline' | 'filled' | 'flushed' | 'unstyled';
-  selectWithFocus?: 'all' | 'number' | 'none';
-  blurOnEnter?: boolean;
-  keepWithinRange?: boolean;
-  clampValueOnBlur?: boolean;
+  /** Render the value as text. Takes precedence over `units` / `digit`. */
+  format?: (value: number) => string;
+  /** Read a value back out of the text. Takes precedence over `units`. */
+  parse?: (text: string) => number;
   /**
-   * wheel control option
+   * Keep the value within `min` and `max` when it is committed or stepped.
+   * Typing is never clamped, so that a value can be entered digit by digit.
+   * @default true
+   */
+  clampValue?: boolean;
+  /**
+   * Wheel control option. Only applies while the focus is inside, so that
+   * scrolling past the input does not change it.
    * If null, no event will be triggered
    */
   wheel?: InputEventOption | null;
@@ -260,12 +367,40 @@ interface NumberInputProps {
    * If null, no event will be triggered
    */
   keyboard?: InputEventOption | null;
-  activeColor?: string;
-  wrapperClassName?: string;
-  onChange?: (value: number, text: string) => void;
-  onFocus?: (value: number, text: string, event: React.FocusEvent<HTMLInputElement, Element>) => void;
-  onBlur?: (value: number, text: string, event: React.FocusEvent<HTMLInputElement, Element>) => void;
-  children?: ReactNode;
+  /**
+   * Pixels of vertical drag on `Stepper` that move the value by one `step`.
+   * If null, no event will be triggered
+   * @default 1
+   */
+  drag?: number | null;
+  /**
+   * Only the appearance will change.
+   * Please consider using with readonly.
+   * aria-disabled property is also applied.
+   */
+  disabled?: boolean;
+  /**
+   * Make the value unchangeable.
+   * aria-readonly property is also applied.
+   */
+  readonly?: boolean;
+  className?: string;
+  style?: CSSProperties;
+  onChange?: (value: number) => void;
+  /**
+   * The input renders exactly what you compose here; there is no default
+   * markup to fall back to.
+   *
+   * @example
+   * <NumberInput.Root value={value} min={0} max={100} onChange={setValue}>
+   *   <NumberInput.InputField />
+   *   <NumberInput.Stepper>
+   *     <NumberInput.IncrementStepper />
+   *     <NumberInput.DecrementStepper />
+   *   </NumberInput.Stepper>
+   * </NumberInput.Root>
+   */
+  children: ReactNode;
 }
 interface NumberInputMethods {
   focus: () => void;
@@ -275,99 +410,127 @@ interface NumberInputMethods {
  * Input with some useful functions for entering numerical values.
  */
 declare const NumberInput: {
-  Root: _$react.ForwardRefExoticComponent<NumberInputProps & Omit<Omit<_$react.DetailedHTMLProps<_$react.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref">, "type" | keyof NumberInputProps> & _$react.RefAttributes<NumberInputMethods>>;
+  Root: _$react.ForwardRefExoticComponent<NumberInputProps & Omit<Omit<_$react.DetailedHTMLProps<_$react.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof NumberInputProps> & _$react.RefAttributes<NumberInputMethods>>;
+  InputField: typeof InputField;
   Stepper: typeof Stepper;
   IncrementStepper: typeof IncrementStepper;
   DecrementStepper: typeof DecrementStepper;
 };
 //#endregion
-//#region src/components/Piano/key.d.ts
-interface KeyProps {
-  noteNumber: number;
-  width?: number;
-  height?: number | `${number}%`;
-  bg?: string;
-  color?: string;
-  activeBg?: string;
-  activeColor?: string;
-  style?: CSSProperties;
-  /**
-   * \<KeyLabel />
-   */
-  children?: ReactElement;
-  /** @internal */
-  __width?: number;
-}
-interface KeyMethods {
-  play: (velocity?: number) => void;
-  stop: () => void;
-  played: () => boolean;
-}
-//#endregion
-//#region src/components/Piano/context.d.ts
-type NoteRange = {
-  first: number;
-  last: number;
-};
-//#endregion
 //#region src/components/Piano/keyboardShortcuts.d.ts
 type KeyboardShortcuts = {
+  /**
+   * Keys laid out from `noteRange.first`, one entry per semitone.
+   *
+   * An empty string leaves that note without a shortcut: `KeyboardEvent.key` is
+   * never empty, so the entry can never match. Use it to skip the black keys
+   * (see {@link SHORTCUTS.HOME_ROW_NATURAL}) and keep the remaining entries
+   * lined up with the notes.
+   */
   keys: string[];
-  flags?: {
-    naturalOnly?: boolean;
-  };
 };
+/**
+ * Ready-made keyboard layouts. Both assume `noteRange.first` is a C.
+ */
 declare const SHORTCUTS: {
-  HOME_ROW: {
+  /** Every semitone from C, over the two rows of a QWERTY keyboard. */HOME_ROW: {
+    keys: string[];
+  }; /** The white keys only, on the home row. Black keys have no shortcut. */
+  HOME_ROW_NATURAL: {
     keys: string[];
   };
 };
 //#endregion
-//#region src/components/Piano/KeyLabel.d.ts
-interface KeyLabelProps {
-  /**
-   * override Piano.label
-   */
-  label?: (note: number, index: number) => ReactNode;
-  wrapperClassName?: string;
-  wrapperStyle?: CSSProperties;
-  /** @internal */
-  __note?: number;
-  /** @internal */
-  __label?: (note: number, index: number) => ReactNode;
-}
-declare function KeyLabel({
-  label,
-  className,
-  wrapperClassName,
-  wrapperStyle,
-  __note,
-  __label,
-  ...props
-}: KeyLabelProps & Omit<ComponentPropsWithoutRef<'div'>, keyof KeyLabelProps>): false | _$react.JSX.Element;
-//#endregion
 //#region src/components/Piano/index.d.ts
 /**
- * [noteRange.first, noteRange.first + 1 ..., noteRange.last]
+ * `style` that also takes CSS custom properties, which is how a key's colours
+ * are set: see `index.css` for the ones each key type reads.
+ */
+type CSSVariables = Record<`--${string}`, string | number | undefined>;
+/**
+ * What {@link PianoProps.keyProps} may return for one key.
+ *
+ * `data-*` attributes are spelled out because TypeScript only allows them on
+ * JSX syntax, not on an object type, and selecting on one is the usual way to
+ * mark a key out.
  */
-declare function getNoteRangeArray(noteRange: NoteRange): number[];
+type KeyAttributes = Omit<ComponentPropsWithoutRef<'div'>, 'style'> & {
+  style?: CSSProperties & CSSVariables;
+} & Record<`data-${string}`, string | number | boolean | undefined>;
+/** What a key is, when {@link PianoProps.label} or `keyProps` is asked about it. */
+interface KeyState {
+  /** Position in the note range, counting from `noteRange.first`. */
+  index: number;
+  keyType: 'white' | 'black';
+  /** Whether the note is currently sounding. */
+  active: boolean;
+  /** Whether the note is above {@link PianoProps.midiMax} and cannot sound. */
+  disabled: boolean;
+}
 interface PianoProps {
   noteRange: NoteRange;
+  /**
+   * Let a pointer slide from one key to the next while it is down.
+   *
+   * @default true
+   */
   glissando?: boolean;
+  /**
+   * Highest note that can sound. Keys above it are drawn `aria-disabled`.
+   *
+   * @default 127
+   */
   midiMax?: number;
   keyboardShortcuts?: KeyboardShortcuts;
+  /**
+   * Fill the parent element, deriving the width of a white key from it.
+   * {@link PianoProps.whiteKeyWidth} is ignored.
+   *
+   * @default false
+   */
   fill?: boolean;
-  whiteNoteWidth?: number;
-  blackNoteWidth?: number;
+  /** @default 40 */
+  whiteKeyWidth?: number;
+  /**
+   * Space between two white keys.
+   * @default 1
+   */
+  keyGap?: number;
+  /**
+   * Width of a black key, as a fraction of {@link PianoProps.whiteKeyWidth}.
+   * @default 0.65
+   */
+  blackKeyWidthRatio?: number;
+  /**
+   * Height of a black key, as a fraction of the height of the keyboard.
+   * @default 0.6
+   */
+  blackKeyHeightRatio?: number;
+  /** @default `fill ? '100%' : 160` */
   height?: number | string;
-  style?: CSSProperties;
-  onPlayNote?: (note: number, velocity?: number) => void;
-  onStopNote?: (note: number) => void;
-  label?: (note: number, index: number) => ReactNode;
+  style?: CSSProperties & CSSVariables;
+  /**
+   * What to draw inside a key. `''`, `null` and `undefined` leave it bare, so
+   * a layout with gaps — {@link SHORTCUTS.HOME_ROW_NATURAL}, say — needs no
+   * special casing.
+   */
+  label?: (note: number, state: KeyState) => ReactNode;
   /**
-   * \<WhiteKey /> | \<BlackKey />
+   * Extra props for one key, by note: a class, a style, a `data-*` attribute
+   * to select on.
+   *
+   * The geometry of the key (`left`, `width`, `height`) is applied after the
+   * returned `style` and cannot be overridden, so a key cannot be drawn
+   * somewhere other than where it responds.
+   *
+   * @example highlight the notes of a scale
+   * ```tsx
+   * keyProps={(note) => ({ 'data-in-scale': inScale(note, root, 'major') })}
+   * ```
    */
-  children?: ReactElement | ReactElement[];
+  keyProps?: (note: number, state: KeyState) => KeyAttributes;
+  onPlayNote?: (note: number, velocity?: number) => void;
+  onStopNote?: (note: number) => void;
 }
 interface PianoMethods {
   playNote: (note: number, velocity?: number) => void;
@@ -377,25 +540,32 @@ interface PianoMethods {
  * Customizable piano component.
  */
 declare const Piano: {
-  Root: React$1.ForwardRefExoticComponent<PianoProps & Omit<Omit<React$1.DetailedHTMLProps<React$1.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof PianoProps> & React$1.RefAttributes<PianoMethods>>;
-  WhiteKey: React$1.ForwardRefExoticComponent<KeyProps & Omit<Omit<React$1.DetailedHTMLProps<React$1.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof KeyProps> & React$1.RefAttributes<KeyMethods>>;
-  BlackKey: React$1.ForwardRefExoticComponent<KeyProps & Omit<Omit<React$1.DetailedHTMLProps<React$1.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof KeyProps> & React$1.RefAttributes<KeyMethods>>;
-  KeyLabel: typeof KeyLabel;
+  Root: _$react.ForwardRefExoticComponent<PianoProps & Omit<Omit<_$react.DetailedHTMLProps<_$react.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof PianoProps> & _$react.RefAttributes<PianoMethods>>;
 };
 //#endregion
 //#region src/components/PointsEditor/Background.d.ts
+interface PointsEditorBackgroundProps {
+  /** Whatever the points are placed over: a graph, a canvas, an image. */
+  children?: ReactNode;
+}
 declare function Background({
   className,
   children,
   ...props
-}: ComponentPropsWithoutRef<'div'>): _$react.JSX.Element;
+}: PointsEditorBackgroundProps & Omit<ComponentPropsWithoutRef<'div'>, keyof PointsEditorBackgroundProps>): _$react.JSX.Element;
 //#endregion
 //#region src/components/PointsEditor/Container.d.ts
+interface PointsEditorContainerProps {
+  /** `<PointsEditor.Point />` goes here. */
+  children?: ReactNode;
+  ref?: Ref<HTMLDivElement>;
+}
 declare function Container({
-  className,
   children,
+  className,
+  ref,
   ...props
-}: ComponentPropsWithoutRef<'div'>): _$react.JSX.Element;
+}: PointsEditorContainerProps & Omit<ComponentPropsWithoutRef<'div'>, keyof PointsEditorContainerProps>): _$react.JSX.Element;
 //#endregion
 //#region src/components/PointsEditor/Point.d.ts
 type PointBaseType = {
@@ -414,8 +584,14 @@ interface PointProps<T extends PointBaseType> {
   width?: number | string;
   height?: number | string;
   color?: string;
+  /** Overrides the `disabled` of `PointsEditor.Root`. */
   disabled?: boolean;
+  /** Overrides the `readonly` of `PointsEditor.Root`. */
   readonly?: boolean;
+  /** Overrides the `wheel` of `PointsEditor.Root`. */
+  wheel?: InputEventOption | null;
+  /** Overrides the `keyboard` of `PointsEditor.Root`. */
+  keyboard?: InputEventOption | null;
   onChange?: (value: PointBaseType) => void;
   onDragStart?: (value: PointBaseType) => void;
   onDragEnd?: (value: PointBaseType) => void;
@@ -428,38 +604,93 @@ declare function Point<T extends PointBaseType>({
   width,
   height,
   color,
-  disabled,
-  readonly,
+  disabled: _disabled,
+  readonly: _readonly,
+  wheel: _wheel,
+  keyboard: _keyboard,
   onChange,
   onDragStart,
   onDragEnd,
   className,
   style,
   onPointerDown,
+  onKeyDown,
   ...props
 }: PointProps<T> & Omit<ComponentPropsWithoutRef<'div'>, keyof PointProps<T>>): _$react.JSX.Element;
 //#endregion
+//#region src/components/PointsEditor/context.d.ts
+type PointsEditorContextValue = {
+  disabled: boolean;
+  readonly: boolean; /** Inherited by every `Point`; `null` turns the wheel off. */
+  wheel: InputEventOption | null; /** Inherited by every `Point`; `null` turns the keyboard off. */
+  keyboard: InputEventOption | null;
+  externalStyles: {
+    userSelectNone?: boolean;
+    cursor?: Cursor;
+  };
+  /**
+   * `Container` registers its element here; `Point` normalizes the pointer
+   * against it, so a point is placed by its position within the container.
+   */
+  containerRef: RefObject<HTMLDivElement | null>;
+};
+/**
+ * The settings `Root` was given, for the subcomponents to read. There is no
+ * state to keep in sync: a point's value belongs to the `Point` that draws it.
+ */
+declare function usePointsEditorContext(): PointsEditorContextValue;
+declare function usePointsEditorContext<T>(selector: (state: PointsEditorContextValue) => T): T;
+//#endregion
 //#region src/components/PointsEditor/index.d.ts
 interface PointsEditorProps {
   width?: number | string;
   height?: number | string;
-  grid?: number | PointBaseType;
+  /**
+   * Only the appearance will change.
+   * Please consider using with readonly.
+   * aria-disabled property is also applied.
+   */
   disabled?: boolean;
+  /**
+   * Make the points unmovable.
+   * aria-readonly property is also applied.
+   */
   readonly?: boolean;
   externalStyles?: {
     userSelectNone?: boolean;
     cursor?: Cursor;
   };
   /**
-   * wheel control option
+   * wheel control option for every `Point`. Shift selects the x axis.
    * If null, no event will be triggered
+   *
+   * A `Point` can override it with a `wheel` of its own.
    */
   wheel?: InputEventOption | null;
   /**
-   * keyboard control option
+   * keyboard control option for every `Point`, on the arrow keys.
    * If null, no event will be triggered
+   *
+   * A `Point` can override it with a `keyboard` of its own.
    */
   keyboard?: InputEventOption | null;
+  /**
+   * The editor renders exactly what you compose here; there is no default
+   * markup to fall back to.
+   *
+   * @example
+   * <PointsEditor.Root>
+   *   <PointsEditor.Background>
+   *     <svg viewBox="0 0 200 100">...</svg>
+   *   </PointsEditor.Background>
+   *   <PointsEditor.Container>
+   *     {points.map((point, i) => (
+   *       <PointsEditor.Point key={i} value={point} onChange={...} />
+   *     ))}
+   *   </PointsEditor.Container>
+   * </PointsEditor.Root>
+   */
+  children: ReactNode;
 }
 /**
  * Multiple Point Controller
@@ -472,28 +703,28 @@ declare const PointsEditor: {
 };
 //#endregion
 //#region src/components/Slider/type.d.ts
-type ScaleType = 'mark' | 'mark-number' | 'number';
-type ScaleOptions = ['step', ScaleType] | [number, ScaleType];
+type MarksType = 'mark' | 'mark-number' | 'number';
+type MarksOptions = ['step', MarksType] | [number, MarksType];
 //#endregion
-//#region src/components/Slider/Scale.d.ts
-interface ScaleProps {
+//#region src/components/Slider/Marks.d.ts
+interface MarksProps {
   gap?: number | string;
-  options?: ScaleOptions;
+  options?: MarksOptions;
   children?: ReactNode;
 }
-declare function Scale({
+declare function Marks({
   gap,
   options,
   children,
   className,
   style,
   ...props
-}: ScaleProps & Omit<ComponentPropsWithoutRef<'div'>, keyof ScaleProps>): _$react.JSX.Element;
+}: MarksProps & Omit<ComponentPropsWithoutRef<'div'>, keyof MarksProps>): _$react.JSX.Element;
 //#endregion
-//#region src/components/Slider/ScaleOption.d.ts
-interface ScaleOptionProps {
+//#region src/components/Slider/MarksOption.d.ts
+interface MarksOptionProps {
   value: number;
-  type?: ScaleType;
+  type?: MarksType;
   /** Display text instead of value. */
   label?: string;
   /** mark thickness */
@@ -512,7 +743,7 @@ interface ScaleOptionProps {
     label?: CSSProperties;
   };
 }
-declare function ScaleOption({
+declare function MarksOption({
   value,
   type,
   label,
@@ -525,24 +756,31 @@ declare function ScaleOption({
   className,
   style,
   ...props
-}: ScaleOptionProps & Omit<ComponentPropsWithoutRef<'div'>, keyof ScaleOptionProps>): _$react.JSX.Element;
+}: MarksOptionProps & Omit<ComponentPropsWithoutRef<'div'>, keyof MarksOptionProps>): _$react.JSX.Element;
 //#endregion
 //#region src/components/Slider/Thumb.d.ts
 interface SliderThumbProps {
-  size?: number | string;
-  width?: number | string;
-  height?: number | string;
+  /**
+   * Size comes from the `--thumb-size` CSS variable on `Slider.Root`, so that
+   * the root can reserve the matching amount of space around the track.
+   */
   color?: string;
   className?: string;
   style?: CSSProperties;
   children?: ReactNode;
-  /** @internal */
-  __percent?: number;
+  ref?: Ref<SliderThumbMethods>;
 }
 interface SliderThumbMethods {
   focus: () => void;
   blur: () => void;
 }
+declare function Thumb$1({
+  color,
+  children,
+  className,
+  style,
+  ref
+}: SliderThumbProps): _$react.JSX.Element;
 //#endregion
 //#region src/components/Slider/Track.d.ts
 interface SliderTrackProps {
@@ -553,11 +791,9 @@ interface SliderTrackProps {
   defaultStyle?: boolean;
   className?: string;
   style?: CSSProperties;
-  children?: ReactElement;
-  /** @internal */
-  __thumb?: ReactElement;
-  /** @internal */
-  __percent?: number;
+  /** `<Slider.Thumb />` goes here. */
+  children?: ReactNode;
+  ref?: Ref<HTMLDivElement>;
 }
 declare function Track({
   length,
@@ -568,23 +804,35 @@ declare function Track({
   className,
   style,
   defaultStyle,
-  __thumb,
-  __percent,
+  ref,
   ...props
 }: SliderTrackProps & Omit<ComponentPropsWithoutRef<'div'>, keyof SliderTrackProps>): _$react.JSX.Element;
 //#endregion
 //#region src/components/Slider/context.d.ts
-type State = {
+type SliderContextValue = {
+  value: number;
   min: number;
   max: number;
-  step: number;
-  skew: number;
+  step: number; /** How the value is distributed across the travel. */
+  scale: Scale;
   vertical: boolean;
   reverse: boolean;
   disabled: boolean;
   readonly: boolean;
+  /**
+   * Position of the thumb, 0-100, already accounting for the display direction
+   * implied by `vertical` and `reverse`.
+   */
+  percent: number; /** `Track` registers its element here; `Root` normalizes the pointer against it. */
+  trackRef: RefObject<HTMLDivElement | null>; /** `Thumb` registers itself here; `Root` focuses it when a drag starts. */
+  thumbRef: RefObject<SliderThumbMethods | null>;
 };
-declare function useSliderContext<T>(selector: (state: State) => T): T;
+/**
+ * Everything here is derived during render, so there is no state to keep in
+ * sync: `value` comes from the props of `Root` and the rest follows from it.
+ */
+declare function useSliderContext(): SliderContextValue;
+declare function useSliderContext<T>(selector: (state: SliderContextValue) => T): T;
 //#endregion
 //#region src/components/Slider/index.d.ts
 interface SliderProps {
@@ -592,7 +840,16 @@ interface SliderProps {
   min: number;
   max: number;
   step?: number;
-  skew?: number;
+  /**
+   * How the value is distributed across the travel.
+   *
+   * Pick one of the scales from `@tremolo-ui/functions`: `linearScale`,
+   * `exponentialScale`, `curveScale(n)`, `symmetricSkewScale(n)`, or
+   * `skewScale(n)` for a value that has to match a JUCE parameter.
+   *
+   * @default linearScale
+   */
+  scale?: Scale;
   /**
    * slider orientation
    * aria-orientation property is also applied.
@@ -630,8 +887,18 @@ interface SliderProps {
   onChange?: (value: number) => void;
   onDragStart?: (value: number) => void;
   onDragEnd?: (value: number) => void;
-  /** \<SliderThumb /> | \<SliderTrack /> */
-  children?: ReactElement | ReactElement[];
+  /**
+   * The slider renders exactly what you compose here; there is no default
+   * markup to fall back to.
+   *
+   * @example
+   * <Slider.Root value={value} min={0} max={100} onChange={setValue}>
+   *   <Slider.Track>
+   *     <Slider.Thumb />
+   *   </Slider.Track>
+   * </Slider.Root>
+   */
+  children: ReactNode;
 }
 interface SliderMethods {
   focus: () => void;
@@ -641,11 +908,11 @@ interface SliderMethods {
  * Customizable slider
  */
 declare const Slider: {
-  Root: React$1.ForwardRefExoticComponent<SliderProps & Omit<Omit<React$1.DetailedHTMLProps<React$1.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof SliderProps> & React$1.RefAttributes<SliderMethods>>;
-  Thumb: React$1.ForwardRefExoticComponent<SliderThumbProps & React$1.RefAttributes<SliderThumbMethods>>;
+  Root: React.ForwardRefExoticComponent<SliderProps & Omit<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof SliderProps> & React.RefAttributes<SliderMethods>>;
+  Thumb: typeof Thumb$1;
   Track: typeof Track;
-  Scale: typeof Scale;
-  ScaleOption: typeof ScaleOption;
+  Marks: typeof Marks;
+  MarksOption: typeof MarksOption;
 };
 //#endregion
 //#region src/components/XYPad/Area.d.ts
@@ -655,9 +922,9 @@ interface XYPadAreaProps {
   color?: string;
   className?: string;
   style?: CSSProperties;
-  children?: ReactElement;
-  /** inherit */
-  __thumb?: ReactElement;
+  /** `<XYPad.Thumb />` goes here. */
+  children?: ReactNode;
+  ref?: Ref<HTMLDivElement>;
 }
 declare function Area({
   width,
@@ -666,65 +933,92 @@ declare function Area({
   children,
   className,
   style,
-  __thumb,
+  ref,
   ...props
 }: XYPadAreaProps & Omit<ComponentPropsWithoutRef<'div'>, keyof XYPadAreaProps>): _$react.JSX.Element;
 //#endregion
 //#region src/components/XYPad/Thumb.d.ts
 interface XYPadThumbProps {
-  size?: number | string;
-  width?: number | string;
-  height?: number | string;
+  /**
+   * Size comes from the `--thumb-size` CSS variable on `XYPad.Root`, so that
+   * the root can reserve the matching amount of space around the area.
+   */
   color?: string;
   wrapperClassName?: string;
   wrapperStyle?: CSSProperties;
   children?: ReactNode;
-  /** @internal */
-  __disabled?: boolean;
-  /** @internal */
-  __readonly?: boolean;
-  /** @internal */
-  __css?: CSSProperties;
+  ref?: Ref<XYPadThumbMethods>;
 }
 interface XYPadThumbMethods {
   focus: () => void;
   blur: () => void;
 }
+type Props = XYPadThumbProps & Omit<ComponentPropsWithoutRef<'div'>, keyof XYPadThumbProps>;
+declare function Thumb({
+  color,
+  children,
+  wrapperClassName,
+  wrapperStyle,
+  className,
+  style,
+  ref,
+  ...props
+}: Props): _$react.JSX.Element;
 //#endregion
 //#region src/components/XYPad/index.d.ts
 /**
  * Two-dimensional slider component.
+ *
+ * The per-axis settings mirror `Slider`, given as `[x, y]` tuples. A plain
+ * value applies to both axes.
  */
-interface ValueOptions {
-  value: number;
-  min: number;
-  max: number;
-  step?: number;
-  skew?: number;
-  reverse?: boolean;
+interface XYPadProps {
+  value: XY<number>;
+  min: XYInput<number>;
+  max: XYInput<number>;
+  step?: XYInput<number>;
   /**
-   * wheel control option
+   * How the value of each axis is distributed across the travel.
+   *
+   * Pick one of the scales from `@tremolo-ui/functions`: `linearScale`,
+   * `exponentialScale`, `curveScale(n)`, `symmetricSkewScale(n)`, or
+   * `skewScale(n)` for a value that has to match a JUCE parameter.
+   *
+   * @default linearScale
+   */
+  scale?: XYInput<Scale>;
+  reverse?: XYInput<boolean>;
+  /**
+   * wheel control option. Shift selects the x axis.
+   * If null, no event will be triggered
    */
   wheel?: InputEventOption | null;
   /**
    * keyboard control option
+   * If null, no event will be triggered
    */
   keyboard?: InputEventOption | null;
-}
-interface XYPadProps {
-  x: ValueOptions;
-  y: ValueOptions;
   externalStyles?: {
     userSelectNone?: boolean;
     cursor?: Cursor;
   };
   disabled?: boolean;
   readonly?: boolean;
-  onChange?: (valueX: number, valueY: number) => void;
-  onDragStart?: (valueX: number, valueY: number) => void;
-  onDragEnd?: (valueX: number, valueY: number) => void;
-  /** \<XYPadThumb /> | \<XYPadArea /> */
-  children?: ReactElement | ReactElement[];
+  onChange?: (value: XY<number>) => void;
+  onDragStart?: (value: XY<number>) => void;
+  onDragEnd?: (value: XY<number>) => void;
+  /**
+   * The pad renders exactly what you compose here; there is no default
+   * markup to fall back to.
+   *
+   * @example
+   * <XYPad.Root value={[x, y]} min={0} max={100} onChange={setValue}>
+   *   <XYPad.Area>
+   *     <XYPad.Thumb />
+   *   </XYPad.Area>
+   * </XYPad.Root>
+   */
+  children: ReactNode;
 }
 interface XYPadMethods {
   focus: () => void;
@@ -735,8 +1029,8 @@ interface XYPadMethods {
  * Simple XYPad
  */
 declare const XYPad: {
-  Root: React$1.ForwardRefExoticComponent<XYPadProps & Omit<Omit<React$1.DetailedHTMLProps<React$1.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof XYPadProps> & React$1.RefAttributes<XYPadMethods>>;
-  Thumb: React$1.ForwardRefExoticComponent<XYPadThumbProps & Omit<Omit<React$1.DetailedHTMLProps<React$1.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof XYPadThumbProps> & React$1.RefAttributes<XYPadThumbMethods>>;
+  Root: _$react.ForwardRefExoticComponent<XYPadProps & Omit<Omit<_$react.DetailedHTMLProps<_$react.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof XYPadProps> & _$react.RefAttributes<XYPadMethods>>;
+  Thumb: typeof Thumb;
   Area: typeof Area;
 };
 //#endregion
@@ -769,40 +1063,46 @@ declare function useDrag<T extends Element>({
   onDragEnd
 }: UseDragProps): (node: T | null) => void;
 //#endregion
-//#region src/hooks/useDragWithElement.d.ts
-interface UseDragWithElement<T extends Element> {
-  baseElementRef: RefObject<T | null>;
+//#region src/hooks/useDragValue.d.ts
+interface UseDragValueOptions {
+  /** Scaling of each axis; a single value applies to both. */
+  axis: XYInput$1<AxisOptions>;
   /**
-   * Report the position on pointer down, before any movement.
+   * Normalize the pointer against the bounding rect of this element, so that
+   * the value *is* the position pointed at.
    *
-   * Enable it where the pointer position *is* the value, so that a plain click
-   * jumps to it. Leave it off where the element being dragged is an object in
-   * its own right, so that grabbing its edge does not shift it under the cursor.
+   * Give either this or `getValue`.
+   */
+  baseElementRef?: RefObject<Element | null>;
+  /**
+   * Move the value away from where it stood when the drag started, by the
+   * distance dragged. The pointer position itself carries no meaning.
    *
-   * @default false
+   * Give either this or `baseElementRef`.
    */
+  getValue?: () => XY$1<number>;
+  /**
+   * Pixels of movement that span the whole range, with `getValue`.
+   * @default 100
+   */
+  pixelRange?: XYInput$1<number>;
+  /** @see DragValueOptions.updateOnPointerDown */
   updateOnPointerDown?: boolean;
+  /** @default 0 */
+  threshold?: number;
   /** CSS cursor to show while dragging. Applied to the element itself. */
   cursor?: string;
-  onDrag: (normalizedX: number, normalizedY: number) => void;
-  onDragStart?: (normalizedX: number, normalizedY: number) => void;
-  onDragEnd?: (normalizedX: number, normalizedY: number) => void;
+  onChange?: (value: XY$1<number>) => void;
+  onDragStart?: (value: XY$1<number>) => void;
+  onDragEnd?: (value: XY$1<number>) => void;
 }
 /**
- * Track a pointer drag, reporting the position normalized against
- * the bounding rect of `baseElementRef`.
+ * Drive a value with a pointer drag.
  *
  * @returns a ref callback for the element that starts the drag, and whether a drag is in progress
  */
-declare function useDragWithElement<T extends Element>({
-  baseElementRef,
-  updateOnPointerDown,
-  cursor,
-  onDrag,
-  onDragStart,
-  onDragEnd
-}: UseDragWithElement<T>): {
-  refCallback: _$react.Dispatch<_$react.SetStateAction<Element | null>>;
+declare function useDragValue<T extends Element>(options: UseDragValueOptions): {
+  refCallback: (node: T | null) => void;
   dragging: boolean;
 };
 //#endregion
@@ -842,14 +1142,32 @@ declare function useMIDIInput(midiAccess: MIDIAccess | null, onNoteOnEvent?: (no
 declare function useMIDIMessage(midiAccess: MIDIAccess | null, onMIDIMessage: (event: MIDIMessageEvent) => void): void;
 //#endregion
 //#region src/hooks/useWheel.d.ts
+interface UseWheelOptions extends WheelOptions {
+  /**
+   * Listen on this element rather than on the one the returned ref callback is
+   * attached to, and ignore that callback.
+   *
+   * For a control made of several movable parts: a wheel event only reaches
+   * what the cursor is over, so a listener per part responds only while the
+   * cursor is over that same part. Listening on the element they share lets
+   * every part see the event, and each one decide whether it is the one to act.
+   *
+   * The element is read when the listener is attached, so a ref filled in by a
+   * parent is fine as long as the parent is above in the tree.
+   */
+  target?: RefObject<Element | null>;
+}
 /**
  * Listen to wheel events on an element.
  *
  * The listener is not passive, so the handler may call `preventDefault()`.
  *
- * @returns a ref callback to attach to the element
+ * @returns a ref callback to attach to the element, unused when `target` is given
  */
-declare function useWheel<T extends Element>(onWheel: (event: WheelEvent) => void): (node: T | null) => void;
+declare function useWheel<T extends Element>(onWheel: (event: WheelEvent) => void, {
+  requireFocus,
+  target
+}?: UseWheelOptions): (node: T | null) => void;
 //#endregion
-export { type AbsoluteSizingProps, AnimationCanvas, type AnimationCanvasProps, type CommonProps, type DecrementStepperProps, type DrawFunction, type IncrementStepperProps, type InitFunction, type KeyLabelProps, type KeyMethods, type KeyProps, type KeyboardShortcuts, Knob, type KnobMethods, type KnobProps, type MIDIAccessError, NOT_SUPPORTED, NumberInput, type NumberInputMethods, type NumberInputProps, PERMISSION_DENIED, Piano, type PianoMethods, type PianoProps, type PointBaseType, type PointProps, PointsEditor, type PointsEditorProps, type RelativeSizingProps, SHORTCUTS, type ScaleOptionProps, type ScaleProps, Slider, type SliderMethods, type SliderProps, type SliderThumbMethods, type SliderThumbProps, type SliderTrackProps, type StepperProps, type ValueOptions, XYPad, type XYPadAreaProps, type XYPadMethods, type XYPadProps, type XYPadThumbMethods, type XYPadThumbProps, clampPoint, getNoteRangeArray, useAnimationFrame, useDrag, useDragWithElement, useEventListener, useInterval, useLongPress, useMIDIAccess, useMIDIInput, useMIDIMessage, useSliderContext, useWheel };
+export { type AbsoluteSizingProps, AnimationCanvas, type AnimationCanvasProps, type CSSVariables, type CommonProps, type DecrementStepperProps, type DrawFunction, type IncrementStepperProps, type InitFunction, type KeyAttributes, type KeyState, type KeyboardShortcuts, Knob, type KnobMethods, type KnobProps, type MIDIAccessError, type MarksOptionProps, type MarksProps, NOT_SUPPORTED, NumberInput, type NumberInputFieldProps, type NumberInputMethods, type NumberInputProps, PERMISSION_DENIED, Piano, type PianoMethods, type PianoProps, type PointBaseType, type PointProps, PointsEditor, type PointsEditorBackgroundProps, type PointsEditorContainerProps, type PointsEditorContextValue, type PointsEditorProps, type RelativeSizingProps, SHORTCUTS, Slider, type SliderMethods, type SliderProps, type SliderThumbMethods, type SliderThumbProps, type SliderTrackProps, type StepperProps, type UseDragValueOptions, type UseWheelOptions, type XY, type XYInput, XYPad, type XYPadAreaProps, type XYPadMethods, type XYPadProps, type XYPadThumbMethods, type XYPadThumbProps, clampPoint, useAnimationFrame, useDrag, useDragValue, useEventListener, useInterval, useLongPress, useMIDIAccess, useMIDIInput, useMIDIMessage, useNumberInputContext, usePointsEditorContext, useSliderContext, useWheel };
 //# sourceMappingURL=index.d.cts.map