@tremolo-ui/react 0.8.0 → 0.9.0

package/dist/index.d.cts

@@ -1,14 +1,7 @@
-import React, { AriaAttributes, CSSProperties, ComponentPropsWithoutRef, DependencyList, ReactNode, Ref, RefObject, SVGProps } from "react";
-import { AnimationFrame, AxisOptions, DragState, DropZoneOptions, InputEventOption, KeyboardShortcuts, KeyboardShortcutsScope, KnobAngles, MIDIAccessOptions, MIDIInputHandlers, MarksOptions, ModifierState, ModifierValue, NoteRange, PointPosition, PointsEditorInstance, SelectionBoxRect, WheelOptions, XY, XYInput } from "@tremolo-ui/dom";
+import React, { AriaAttributes, CSSProperties, ComponentPropsWithoutRef, ReactNode, Ref, RefObject, SVGProps } from "react";
+import { AxisOptions, CanvasDrawFunction, CanvasInitFunction, ChangeSource, DragState, DropZoneOptions, InputEventOption, KeyboardShortcuts, KeyboardShortcutsScope, KnobAngles, MIDIAccessOptions, MIDIInputHandlers, MarksOptions, ModifierState, ModifierValue, NoteRange, PointPosition, PointsEditorInstance, SelectionBoxRect, WheelOptions, XY, XYInput } from "@tremolo-ui/dom";
 import { Scale, 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: AnimationFrame) => void;
 interface AnimationCanvasCommonProps {
   /**
    * Draw one frame. It is given the 2D context and the frame: the size in CSS
@@ -17,12 +10,12 @@ interface AnimationCanvasCommonProps {
    * A new function replaces the old one in place, so writing it inline does
    * not restart anything.
    */
-  draw: DrawFunction;
+  draw: CanvasDrawFunction;
   /**
    * Called once before the first frame, with the context and the size in CSS
    * pixels. Set up what every frame shares here.
    */
-  init?: InitFunction;
+  init?: CanvasInitFunction;
   /**
    * Redraw on every animation frame. Turn it off to draw only when there is a
    * reason to: when the canvas mounts, when it is resized, and when the
@@ -219,37 +212,37 @@ interface KnobThumbProps {
    * Fill colour of the circle.
    * @default 'currentColor'
    */
-  thumb?: string;
+  color?: string;
   /**
    * Colour of the line that points at the value.
    * @default 'currentColor'
    */
-  thumbLine?: string;
+  lineColor?: string;
   /**
    * Diameter of the circle, as a percentage of the knob.
    * @default 84
    */
-  thumbSize?: number;
+  size?: number;
   /**
    * Thickness of the line, as a percentage of the knob.
    * @default 6
    */
-  thumbLineWeight?: number;
+  lineWeight?: number;
   /**
    * How far down the line reaches, as a percentage of the knob from its top.
    * The line starts at the edge of the circle.
    * @default 35
    */
-  thumbLineLength?: number;
+  lineLength?: number;
   /**
-   * Classes for what the thumb draws inside itself: `thumbLine` is the line
-   * that points at the value.
+   * Classes for what the thumb draws inside itself: `line` is the line that
+   * points at the value.
    */
   classes?: {
-    thumbLine?: string;
+    line?: string;
   };
 }
-declare function Thumb({ className, thumb, thumbLine, thumbSize, thumbLineWeight, thumbLineLength, classes, ...props }: KnobThumbProps & Omit<SVGProps<SVGSVGElement>, 'd' | keyof KnobThumbProps>): import("react").JSX.Element;
+declare function Thumb({ className, color, lineColor, size, lineWeight, lineLength, classes, ...props }: KnobThumbProps & Omit<SVGProps<SVGSVGElement>, 'd' | keyof KnobThumbProps>): import("react").JSX.Element;
 //#endregion
 //#region src/css-variables.d.ts
 /**
@@ -317,10 +310,10 @@ interface KnobProps {
    */
   scale?: Scale;
   /**
-   * The value a double click restores, while `enableDoubleClickDefault` is on.
-   * @default min
+   * The value a double click restores. `null` turns the double click off.
+   * @default startValue
    */
-  defaultValue?: number;
+  resetValue?: number | null;
   /**
    * Where the active arc starts. Put it at the centre of a bipolar control,
    * such as a pan knob, so that the arc grows from there either way.
@@ -336,11 +329,9 @@ interface KnobProps {
    * The cursor to show while dragging. It is set on the dragged element, so it
    * stays while the pointer is outside the knob.
    *
-   * @default { cursor: 'grabbing' }
+   * @default 'grabbing'
    */
-  externalStyles?: {
-    cursor?: CSSProperties['cursor'];
-  };
+  dragCursor?: CSSProperties['cursor'];
   /**
    * How much one notch of the wheel moves the value. It only acts while the
    * focus is inside, so that scrolling the page past the knob leaves it alone.
@@ -401,11 +392,6 @@ interface KnobProps {
    * @default { default: ['raw', 1], shift: ['raw', 0.1] }
    */
   keyboard?: ModifierValue<InputEventOption> | null;
-  /**
-   * Restore `defaultValue` on a double click.
-   * @default true
-   */
-  enableDoubleClickDefault?: boolean;
   /**
    * Make the knob unchangeable and remove it from the tab order.
    * The parts carry `data-disabled` while it is set.
@@ -415,7 +401,7 @@ interface KnobProps {
    * Make the knob unchangeable while leaving it focusable.
    * The parts carry `data-readonly` while it is set.
    */
-  readonly?: boolean;
+  readOnly?: boolean;
   /**
    * How far the knob turns from `min` to `max`, in degrees, centred on the
    * top.
@@ -427,6 +413,25 @@ interface KnobProps {
    * click moves it.
    */
   onChange?: (value: number) => void;
+  /**
+   * Called when a change of the value starts — a drag, a double click, the first wheel notch
+   * or arrow key — with the value
+   * before it and what it is made with. A host recording automation can treat
+   * the control as touched from here until `onChangeEnd`.
+   */
+  onChangeStart?: (value: number, source: ChangeSource) => void;
+  /**
+   * Called when the change ends, with the value it ended on: on release, or
+   * `changeEndDelay` after the last wheel notch or arrow key.
+   */
+  onChangeEnd?: (value: number, source: ChangeSource) => void;
+  /**
+   * How long after the last wheel notch or arrow key the change counts as
+   * over, in milliseconds. Neither has an event that says it is done.
+   *
+   * @default 500
+   */
+  changeEndDelay?: number;
   /**
    * The knob renders exactly what you compose here; there is no default
    * markup to fall back to.
@@ -442,6 +447,12 @@ interface KnobProps {
    */
   children: ReactNode;
   style?: CSSProperties & CSSVariables<'knob-size'>;
+  /**
+   * Receives `focus` and `blur`. They do nothing while the knob is disabled,
+   * where the element's own `focus()` would still focus it. `ref` reaches the
+   * root element itself.
+   */
+  actionsRef?: Ref<KnobMethods>;
 }
 interface KnobMethods {
   focus: () => void;
@@ -451,7 +462,7 @@ interface KnobMethods {
  * Interactive rotary knob component implemented in SVG.
  */
 export declare const Knob: {
-  Root: import("react").ForwardRefExoticComponent<KnobProps & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof KnobProps> & import("react").RefAttributes<KnobMethods>>;
+  Root: import("react").ForwardRefExoticComponent<KnobProps & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof KnobProps> & import("react").RefAttributes<HTMLDivElement>>;
   SVGRoot: typeof SVGRoot;
   InactiveLine: typeof InactiveLine;
   ActiveLine: typeof ActiveLine;
@@ -489,7 +500,7 @@ type NumberInputContextValue = {
   /** How the value is distributed across the travel. */
   scale: Scale;
   disabled: boolean;
-  readonly: boolean;
+  readOnly: boolean;
   clampValue: boolean;
   /**
    * The effective scaling for `applyDelta`, with unbounded ends filled in.
@@ -505,6 +516,8 @@ type NumberInputContextValue = {
   dragSensitivity: ModifierValue<number>;
   /** Whether a `Stepper` drag hides the pointer and reads its movement. */
   pointerLock: boolean;
+  /** The cursor shown while a `Stepper` is dragged. */
+  dragCursor: CSSProperties['cursor'];
   /** What `InputField` selects when it takes focus. */
   selectOnFocus: 'all' | 'number' | 'none';
   /** Whether `InputField` shows the plain value while it has focus. */
@@ -664,6 +677,13 @@ interface NumberInputProps {
    * @default false
    */
   pointerLock?: boolean;
+  /**
+   * The cursor to show while dragging a `Stepper`. It is set on the stepper
+   * being dragged, so it stays while the pointer is outside it.
+   *
+   * @default 'ns-resize'
+   */
+  dragCursor?: CSSProperties['cursor'];
   /**
    * Select the text when `InputField` takes focus: `'all'` selects all of it,
    * `'number'` only the number, leaving the unit the format put around it,
@@ -719,13 +739,34 @@ interface NumberInputProps {
    * Make the value unchangeable.
    * The parts carry `data-readonly` while it is set.
    */
-  readonly?: boolean;
+  readOnly?: boolean;
   /**
    * Called with the new value. While the user types, it is called for every
    * entry that reads as a number, unclamped; committing the entry calls it
    * again if clamping changes the value.
    */
   onChange?: (value: number) => void;
+  /**
+   * Called when a change of the value starts — a press on a stepper, the
+   * first wheel notch, arrow key or typed character — with the value before
+   * it and what it is made with. A host recording automation can treat the
+   * input as touched from here until `onChangeEnd`.
+   */
+  onChangeStart?: (value: number, source: ChangeSource) => void;
+  /**
+   * Called when the change ends, with the value it ended on: when the stepper
+   * is released, when typed text is committed, or `changeEndDelay` after the
+   * last wheel notch or arrow key.
+   */
+  onChangeEnd?: (value: number, source: ChangeSource) => void;
+  /**
+   * How long after the last wheel notch, arrow key or typed character the
+   * change counts as over, in milliseconds. None of them has an event that
+   * says it is done.
+   *
+   * @default 500
+   */
+  changeEndDelay?: number;
   /**
    * The input renders exactly what you compose here; there is no default
    * markup to fall back to.
@@ -740,6 +781,12 @@ interface NumberInputProps {
    * </NumberInput.Root>
    */
   children: ReactNode;
+  /**
+   * Receives `focus` and `blur`, which act on the input of `InputField` — the
+   * element that takes the focus — and do nothing while
+   * the input is disabled. `ref` reaches the root element itself.
+   */
+  actionsRef?: Ref<NumberInputMethods>;
 }
 interface NumberInputMethods {
   focus: () => void;
@@ -749,11 +796,11 @@ interface NumberInputMethods {
  * Input with some useful functions for entering numerical values.
  */
 export declare const NumberInput: {
-  Root: import("react").ForwardRefExoticComponent<NumberInputProps & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof NumberInputProps> & import("react").RefAttributes<NumberInputMethods>>;
+  Root: import("react").ForwardRefExoticComponent<NumberInputProps & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof NumberInputProps> & import("react").RefAttributes<HTMLDivElement>>;
   InputField: import("react").ForwardRefExoticComponent<{
     form?: string | undefined | undefined;
     slot?: string | undefined | undefined;
-    style?: import("react").CSSProperties | undefined;
+    style?: CSSProperties | undefined;
     title?: string | undefined | undefined;
     pattern?: string | undefined | undefined;
     key?: import("react").Key | null | undefined;
@@ -764,7 +811,7 @@ export declare const NumberInput: {
     autoCapitalize?: "off" | "none" | "on" | "sentences" | "words" | "characters" | undefined | (string & {}) | undefined;
     autoFocus?: boolean | undefined | undefined;
     className?: string | undefined | undefined;
-    contentEditable?: (boolean | "true" | "false") | "inherit" | "plaintext-only" | undefined;
+    contentEditable?: "inherit" | (boolean | "true" | "false") | "plaintext-only" | undefined;
     contextMenu?: string | undefined | undefined;
     dir?: string | undefined | undefined;
     draggable?: (boolean | "true" | "false") | undefined;
@@ -1033,15 +1080,17 @@ export declare const NumberInput: {
     onTransitionRunCapture?: import("react").TransitionEventHandler<HTMLInputElement> | undefined;
     onTransitionStart?: import("react").TransitionEventHandler<HTMLInputElement> | undefined;
     onTransitionStartCapture?: import("react").TransitionEventHandler<HTMLInputElement> | undefined;
-    accept?: string | undefined | undefined;
-    multiple?: boolean | undefined | undefined;
-    disabled?: boolean | undefined | undefined;
-    height?: number | string | undefined | undefined;
-    width?: number | string | undefined | undefined;
     min?: number | string | undefined | undefined;
     max?: number | string | undefined | undefined;
     step?: number | string | undefined | undefined;
+    disabled?: boolean | undefined | undefined;
+    readOnly?: boolean | undefined | undefined;
     alt?: string | undefined | undefined;
+    height?: number | string | undefined | undefined;
+    width?: number | string | undefined | undefined;
+    accept?: string | undefined | undefined;
+    multiple?: boolean | undefined | undefined;
+    size?: number | undefined | undefined;
     autoComplete?: import("react").HTMLInputAutoCompleteAttribute | undefined;
     capture?: boolean | "user" | "environment" | undefined | undefined;
     checked?: boolean | undefined | undefined;
@@ -1055,9 +1104,7 @@ export declare const NumberInput: {
     minLength?: number | undefined | undefined;
     name?: string | undefined | undefined;
     placeholder?: string | undefined | undefined;
-    readOnly?: boolean | undefined | undefined;
     required?: boolean | undefined | undefined;
-    size?: number | undefined | undefined;
     src?: string | undefined | undefined;
   } & import("react").RefAttributes<HTMLInputElement>>;
   Stepper: import("react").ForwardRefExoticComponent<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
@@ -1183,6 +1230,11 @@ interface PianoProps {
   onPlayNote?: (note: number, velocity?: number) => void;
   /** Called once everything holding a note has let go of it. */
   onStopNote?: (note: number) => void;
+  /**
+   * Receives `playNote` and `stopNote`, which press and release a key as the
+   * pointer or the keyboard would. `ref` reaches the root element itself.
+   */
+  actionsRef?: Ref<PianoMethods>;
 }
 interface PianoMethods {
   playNote: (note: number, velocity?: number) => void;
@@ -1192,7 +1244,7 @@ interface PianoMethods {
  * Customizable piano component.
  */
 export declare const Piano: {
-  Root: import("react").ForwardRefExoticComponent<PianoProps & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof PianoProps> & import("react").RefAttributes<PianoMethods>>;
+  Root: import("react").ForwardRefExoticComponent<PianoProps & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof PianoProps> & import("react").RefAttributes<HTMLDivElement>>;
 };
 //#endregion
 //#region src/components/PointsEditor/Background.d.ts
@@ -1219,8 +1271,8 @@ interface PointsEditorPointProps<T extends PointPosition> {
   color?: string;
   /** Overrides the `disabled` of `PointsEditor.Root`. */
   disabled?: boolean;
-  /** Overrides the `readonly` of `PointsEditor.Root`. */
-  readonly?: boolean;
+  /** Overrides the `readOnly` of `PointsEditor.Root`. */
+  readOnly?: boolean;
   /** Overrides the `wheel` of `PointsEditor.Root`. */
   wheel?: ModifierValue<InputEventOption> | null;
   /** Overrides the `keyboard` of `PointsEditor.Root`. */
@@ -1237,13 +1289,28 @@ interface PointsEditorPointProps<T extends PointPosition> {
    * arrow keys or the wheel, including when it moves along with a selection.
    */
   onChange?: (value: PointPosition) => void;
-  /** Called when a drag on this point starts, with where the point is. */
-  onDragStart?: (value: PointPosition) => void;
-  /** Called when that drag ends, with where the point is. */
-  onDragEnd?: (value: PointPosition) => void;
+  /**
+   * Called when a change of this point starts — a drag on it, the first wheel
+   * notch or arrow key while it has the focus — with where it is and what the
+   * change is made with. The points that move along with a selection report
+   * through `onChange` only: the change belongs to the point being operated.
+   */
+  onChangeStart?: (value: PointPosition, source: ChangeSource) => void;
+  /**
+   * Called when that change ends, with where the point is: on release, or
+   * `changeEndDelay` after the last wheel notch or arrow key.
+   */
+  onChangeEnd?: (value: PointPosition, source: ChangeSource) => void;
+  /**
+   * How long after the last wheel notch or arrow key the change counts as
+   * over, in milliseconds. Neither has an event that says it is done.
+   *
+   * @default 500
+   */
+  changeEndDelay?: number;
   style?: CSSProperties & CSSVariables<'color' | 'translate'>;
 }
-declare function Point<T extends PointPosition>({ value, children, id: idProp, min, max, color, disabled: _disabled, readonly: _readonly, wheel: _wheel, keyboard: _keyboard, 'aria-label': ariaLabel, 'aria-valuetext': ariaValuetext, onChange, onDragStart, onDragEnd, className, style, onPointerDown, onKeyDown, onFocus, ...props }: PointsEditorPointProps<T> & Omit<ComponentPropsWithoutRef<'div'>, keyof PointsEditorPointProps<T>>): import("react").JSX.Element;
+declare function Point<T extends PointPosition>({ value, children, id: idProp, min, max, color, disabled: _disabled, readOnly: _readOnly, wheel: _wheel, keyboard: _keyboard, 'aria-label': ariaLabel, 'aria-valuetext': ariaValuetext, onChange, onChangeStart, onChangeEnd, changeEndDelay, className, style, onPointerDown, onKeyDown, onFocus, ...props }: PointsEditorPointProps<T> & Omit<ComponentPropsWithoutRef<'div'>, keyof PointsEditorPointProps<T>>): import("react").JSX.Element;
 //#endregion
 //#region src/components/PointsEditor/SelectionBox.d.ts
 /**
@@ -1257,16 +1324,15 @@ declare function SelectionBox({ children, className, style, ...props }: Componen
 //#region src/components/PointsEditor/context.d.ts
 type PointsEditorContextValue = {
   disabled: boolean;
-  readonly: boolean;
+  readOnly: boolean;
   /** Inherited by every `Point`; `null` turns the wheel off. */
   wheel: ModifierValue<InputEventOption> | null;
   /** Inherited by every `Point`; `null` turns the keyboard off. */
   keyboard: ModifierValue<InputEventOption> | null;
   /** Inherited by every `Point`. See `PointsEditorProps.dragSensitivity`. */
   dragSensitivity: ModifierValue<number>;
-  externalStyles: {
-    cursor?: CSSProperties['cursor'];
-  };
+  /** Inherited by every `Point`. See `PointsEditorProps.dragCursor`. */
+  dragCursor: CSSProperties['cursor'];
   /**
    * `Container` registers its element here; `Point` normalizes the pointer
    * against it, so a point is placed by its position within the container.
@@ -1304,16 +1370,14 @@ interface PointsEditorProps {
    * Make the points unmovable.
    * The parts carry `data-readonly` while it is set.
    */
-  readonly?: boolean;
+  readOnly?: boolean;
   /**
    * The cursor to show while dragging a point. It is set on the dragged
    * point, so it stays while the pointer is outside it.
    *
-   * @default { cursor: 'grabbing' }
+   * @default 'grabbing'
    */
-  externalStyles?: {
-    cursor?: CSSProperties['cursor'];
-  };
+  dragCursor?: CSSProperties['cursor'];
   /**
    * How much one notch of the wheel moves the focused `Point`. Scrolling
    * sideways, or with shift held, moves x; otherwise it moves y.
@@ -1427,6 +1491,11 @@ interface SliderThumbProps {
    */
   color?: string;
   style?: CSSProperties & CSSVariables<'color' | 'translate'>;
+  /**
+   * Receives `focus` and `blur` for the range input inside, which do nothing
+   * while the slider is disabled. `ref` reaches the thumb element itself.
+   */
+  actionsRef?: Ref<SliderThumbMethods>;
 }
 interface SliderThumbMethods {
   focus: () => void;
@@ -1442,11 +1511,11 @@ interface SliderTrackProps {
   length?: number | string;
   /** How thick the track is across that axis. Sets `--thickness`. */
   thickness?: number | string;
-  /** Colour of the part from `min` to the value. Sets `--active`. */
-  active?: string;
-  /** Colour of the rest of the track. Sets `--inactive`. */
-  inactive?: string;
-  style?: CSSProperties & CSSVariables<'length' | 'thickness' | 'active' | 'inactive' | 'percent'>;
+  /** Colour of the part from `min` to the value. Sets `--active-color`. */
+  activeColor?: string;
+  /** Colour of the rest of the track. Sets `--inactive-color`. */
+  inactiveColor?: string;
+  style?: CSSProperties & CSSVariables<'length' | 'thickness' | 'active-color' | 'inactive-color' | 'percent'>;
 }
 //#endregion
 //#region src/components/Slider/Marks.d.ts
@@ -1511,14 +1580,14 @@ type SliderContextValue = {
   step: number;
   /** How the value is distributed across the travel. */
   scale: Scale;
-  vertical: boolean;
+  orientation: 'horizontal' | 'vertical';
   reverse: boolean;
   disabled: boolean;
-  readonly: boolean;
+  readOnly: boolean;
   onChange?: (value: number) => void;
   /**
    * Position of the thumb, 0-100, already accounting for the display direction
-   * implied by `vertical` and `reverse`.
+   * implied by `orientation` and `reverse`.
    */
   percent: number;
   /** `Track` registers its element here; `Root` normalizes the pointer against it. */
@@ -1559,14 +1628,15 @@ interface SliderProps {
    */
   scale?: Scale;
   /**
-   * Run the slider vertically, with the value growing upwards. The range input
-   * inside the thumb takes its `aria-orientation` from this.
+   * Which way the slider runs. A vertical slider grows upwards. Every part
+   * carries the same value as `data-orientation`, and the range input inside
+   * the thumb takes its `aria-orientation` from it.
    *
-   * @default false
+   * @default 'horizontal'
    */
-  vertical?: boolean;
+  orientation?: 'horizontal' | 'vertical';
   /**
-   * Grow the value the other way: leftwards, or downwards when `vertical`.
+   * Grow the value the other way: leftwards, or downwards when vertical.
    * The arrow keys follow the direction on screen.
    *
    * @default false
@@ -1576,11 +1646,9 @@ interface SliderProps {
    * The cursor to show while dragging. It is set on the dragged element, so it
    * stays while the pointer is outside the slider.
    *
-   * @default { cursor: 'pointer' }
+   * @default 'pointer'
    */
-  externalStyles?: {
-    cursor?: CSSProperties['cursor'];
-  };
+  dragCursor?: CSSProperties['cursor'];
   /**
    * How much one notch of the wheel moves the value. It only acts while the
    * focus is inside, so that scrolling the page past the slider leaves it
@@ -1635,13 +1703,28 @@ interface SliderProps {
    * Make the value unchangeable.
    * The parts carry `data-readonly` while it is set.
    */
-  readonly?: boolean;
+  readOnly?: boolean;
   /** Called with the new value when a drag, the wheel or an arrow key moves it. */
   onChange?: (value: number) => void;
-  /** Called when a drag starts, with the value where the track was pressed. */
-  onDragStart?: (value: number) => void;
-  /** Called when the drag ends, with the value it ended on. */
-  onDragEnd?: (value: number) => void;
+  /**
+   * Called when a change of the value starts — a press on the track, the first wheel notch
+   * or arrow key — with the value
+   * before it and what it is made with. A host recording automation can treat
+   * the control as touched from here until `onChangeEnd`.
+   */
+  onChangeStart?: (value: number, source: ChangeSource) => void;
+  /**
+   * Called when the change ends, with the value it ended on: on release, or
+   * `changeEndDelay` after the last wheel notch or arrow key.
+   */
+  onChangeEnd?: (value: number, source: ChangeSource) => void;
+  /**
+   * How long after the last wheel notch or arrow key the change counts as
+   * over, in milliseconds. Neither has an event that says it is done.
+   *
+   * @default 500
+   */
+  changeEndDelay?: number;
   /**
    * The slider renders exactly what you compose here; there is no default
    * markup to fall back to.
@@ -1654,6 +1737,12 @@ interface SliderProps {
    * </Slider.Root>
    */
   children: ReactNode;
+  /**
+   * Receives `focus` and `blur`, which act on the range input inside the thumb —
+   * the element that takes the focus — and do nothing while the slider is
+   * disabled. `ref` reaches the root element itself.
+   */
+  actionsRef?: Ref<SliderMethods>;
 }
 interface SliderMethods {
   focus: () => void;
@@ -1663,8 +1752,8 @@ interface SliderMethods {
  * Customizable slider
  */
 export declare const Slider: {
-  Root: React.ForwardRefExoticComponent<SliderProps & Omit<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof SliderProps> & React.RefAttributes<SliderMethods>>;
-  Thumb: React.ForwardRefExoticComponent<SliderThumbProps & Omit<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof SliderThumbProps> & React.RefAttributes<SliderThumbMethods>>;
+  Root: React.ForwardRefExoticComponent<SliderProps & Omit<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof SliderProps> & React.RefAttributes<HTMLDivElement>>;
+  Thumb: React.ForwardRefExoticComponent<SliderThumbProps & Omit<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof SliderThumbProps> & React.RefAttributes<HTMLDivElement>>;
   Track: React.ForwardRefExoticComponent<SliderTrackProps & Omit<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof SliderTrackProps> & React.RefAttributes<HTMLDivElement>>;
   Marks: typeof Marks;
   MarksOption: typeof MarksOption;
@@ -1694,6 +1783,11 @@ interface XYPadThumbProps {
    */
   'aria-valuetext'?: XYInput<AriaAttributes['aria-valuetext']>;
   style?: CSSProperties & CSSVariables<'color' | 'translate'>;
+  /**
+   * Receives `focus` and `blur` for the range inputs inside, which do nothing
+   * while the pad is disabled. `ref` reaches the thumb element itself.
+   */
+  actionsRef?: Ref<XYPadThumbMethods>;
 }
 interface XYPadThumbMethods {
   focus: () => void;
@@ -1710,7 +1804,7 @@ type XYPadContextValue = {
   scale: XY<Scale>;
   reverse: XY<boolean>;
   disabled: boolean;
-  readonly: boolean;
+  readOnly: boolean;
   onChange?: (value: XY<number>) => void;
   /**
    * Position of the thumb, 0-100 per axis, already accounting for `reverse`.
@@ -1817,11 +1911,9 @@ interface XYPadProps {
    * The cursor to show while dragging. It is set on the dragged element, so it
    * stays while the pointer is outside the pad.
    *
-   * @default { cursor: 'pointer' }
+   * @default 'pointer'
    */
-  externalStyles?: {
-    cursor?: CSSProperties['cursor'];
-  };
+  dragCursor?: CSSProperties['cursor'];
   /**
    * Make the pad unchangeable and remove its thumb from the tab order.
    * The parts carry `data-disabled` while it is set.
@@ -1831,13 +1923,28 @@ interface XYPadProps {
    * Make the pad unchangeable while leaving its thumb focusable.
    * The parts carry `data-readonly` while it is set.
    */
-  readonly?: boolean;
+  readOnly?: boolean;
   /** Called with the new value when a drag, the wheel or an arrow key moves it. */
   onChange?: (value: XY<number>) => void;
-  /** Called when a drag starts, with the value where the area was pressed. */
-  onDragStart?: (value: XY<number>) => void;
-  /** Called when the drag ends, with the value it ended on. */
-  onDragEnd?: (value: XY<number>) => void;
+  /**
+   * Called when a change of the value starts — a press on the area, the first wheel notch
+   * or arrow key — with the value
+   * before it and what it is made with. A host recording automation can treat
+   * the control as touched from here until `onChangeEnd`.
+   */
+  onChangeStart?: (value: XY<number>, source: ChangeSource) => void;
+  /**
+   * Called when the change ends, with the value it ended on: on release, or
+   * `changeEndDelay` after the last wheel notch or arrow key.
+   */
+  onChangeEnd?: (value: XY<number>, source: ChangeSource) => void;
+  /**
+   * How long after the last wheel notch or arrow key the change counts as
+   * over, in milliseconds. Neither has an event that says it is done.
+   *
+   * @default 500
+   */
+  changeEndDelay?: number;
   /**
    * The pad renders exactly what you compose here; there is no default
    * markup to fall back to.
@@ -1850,23 +1957,46 @@ interface XYPadProps {
    * </XYPad.Root>
    */
   children: ReactNode;
+  /**
+   * Receives `focus` and `blur`, which act on the range inputs inside the thumb —
+   * the elements that take the focus — and do nothing while
+   * the pad is disabled. `ref` reaches the root element itself.
+   */
+  actionsRef?: Ref<XYPadMethods>;
 }
 interface XYPadMethods {
   focus: () => void;
   blur: () => void;
-  original: Ref<HTMLDivElement>;
 }
 /**
  * Simple XYPad
  */
 export declare const XYPad: {
-  Root: import("react").ForwardRefExoticComponent<XYPadProps & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof XYPadProps> & import("react").RefAttributes<XYPadMethods>>;
-  Thumb: import("react").ForwardRefExoticComponent<XYPadThumbProps & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof XYPadThumbProps> & import("react").RefAttributes<XYPadThumbMethods>>;
+  Root: import("react").ForwardRefExoticComponent<XYPadProps & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof XYPadProps> & import("react").RefAttributes<HTMLDivElement>>;
+  Thumb: import("react").ForwardRefExoticComponent<XYPadThumbProps & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, keyof XYPadThumbProps> & import("react").RefAttributes<HTMLDivElement>>;
   Area: import("react").ForwardRefExoticComponent<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
 };
 //#endregion
 //#region src/hooks/useAnimationFrame.d.ts
-export declare function useAnimationFrame(callback?: () => void, deps?: DependencyList): void;
+interface UseAnimationFrameOptions {
+  /**
+   * Stop the loop. Turning it back on starts a new one, whose first frame has
+   * a `deltaTime` of `0`.
+   * @default false
+   */
+  disabled?: boolean;
+}
+/**
+ * Call `callback` on every animation frame for as long as the component is
+ * mounted.
+ *
+ * The callback is read on every frame, so it can be written inline and see
+ * the latest render without restarting the loop.
+ *
+ * @param callback receives the frame's timestamp and the milliseconds since
+ * the previous frame, which is `0` on the first one
+ */
+export declare function useAnimationFrame(callback: (timestamp: DOMHighResTimeStamp, deltaTime: number) => void, { disabled }?: UseAnimationFrameOptions): void;
 //#endregion
 //#region src/hooks/useDrag.d.ts
 interface UseDragOptions {
@@ -2017,14 +2147,30 @@ export declare function useDropZone<T extends Element>({ accept, multiple, disab
 };
 //#endregion
 //#region src/hooks/useEventListener.d.ts
-type Target = EventTarget | null | (() => EventTarget | null);
-type Options = boolean | AddEventListenerOptions;
-export declare function useEventListener<K extends keyof DocumentEventMap>(target: Target, event: K, handler: (event: DocumentEventMap[K]) => void, options?: Options): VoidFunction;
-export declare function useEventListener<K extends keyof WindowEventMap>(target: Target, event: K, handler: (event: WindowEventMap[K]) => void, options?: Options): VoidFunction;
-export declare function useEventListener<K extends keyof GlobalEventHandlersEventMap>(target: Target, event: K, handler: (event: GlobalEventHandlersEventMap[K]) => void, options?: Options): VoidFunction;
-//#endregion
-//#region src/hooks/useInterval.d.ts
-export declare function useInterval(callback: () => void, delay: number | null): void;
+/**
+ * What {@link useEventListener} listens on. A function is called after every
+ * render, so it can return an element out of a ref; `null` listens on nothing.
+ */
+type UseEventListenerTarget = EventTarget | null | (() => EventTarget | null);
+/**
+ * The options of `addEventListener`, as a boolean for `capture` or as an
+ * object. `signal` is left out: the hook already owns when the listener goes.
+ */
+type UseEventListenerOptions = boolean | Pick<AddEventListenerOptions, 'capture' | 'once' | 'passive'>;
+/**
+ * Listen to an event on a target for as long as the component is mounted.
+ *
+ * The handler is read on every event, and the target and the options are
+ * compared by what they resolve to, so all three can be written inline. The
+ * listener is re-attached only when the element, the event or one of the
+ * options actually changes.
+ *
+ * @returns a function that removes the listener. It stays removed until the
+ * target, the event or the options change.
+ */
+export declare function useEventListener<K extends keyof DocumentEventMap>(target: UseEventListenerTarget, event: K, handler: (event: DocumentEventMap[K]) => void, options?: UseEventListenerOptions): VoidFunction;
+export declare function useEventListener<K extends keyof WindowEventMap>(target: UseEventListenerTarget, event: K, handler: (event: WindowEventMap[K]) => void, options?: UseEventListenerOptions): VoidFunction;
+export declare function useEventListener<K extends keyof GlobalEventHandlersEventMap>(target: UseEventListenerTarget, event: K, handler: (event: GlobalEventHandlersEventMap[K]) => void, options?: UseEventListenerOptions): VoidFunction;
 //#endregion
 //#region src/hooks/useLongPress.d.ts
 /**
@@ -2109,5 +2255,5 @@ interface UseWheelOptions extends Omit<WheelOptions, 'onWheel'> {
  */
 export declare function useWheel<T extends Element>(onWheel: (event: WheelEvent) => void, { requireFocus, target }?: UseWheelOptions): (node: T | null) => void;
 //#endregion
-export type { AnimationCanvasCommonProps, AnimationCanvasFixedProps, AnimationCanvasProps, AnimationCanvasResizableProps, CSSVariables, DrawFunction, DropZoneProps, FileInputContextValue, FileInputProps, FileInputTriggerProps, InitFunction, KeyAttributes, KeyState, KnobContextValue, KnobMethods, KnobProps, KnobSVGRootProps, KnobThumbProps, NumberInputContextValue, NumberInputMethods, NumberInputProps, PianoMethods, PianoProps, PointsEditorContextValue, PointsEditorPointProps, PointsEditorProps, SliderContextValue, SliderMarksOptionProps, SliderMarksProps, SliderMethods, SliderProps, SliderThumbMethods, SliderThumbProps, SliderTrackProps, UseDragOptions, UseDragValueOptions, UseDropZoneOptions, UseWheelOptions, XYPadContextValue, XYPadMethods, XYPadProps, XYPadThumbMethods, XYPadThumbProps };
+export type { AnimationCanvasCommonProps, AnimationCanvasFixedProps, AnimationCanvasProps, AnimationCanvasResizableProps, CSSVariables, DropZoneProps, FileInputContextValue, FileInputProps, FileInputTriggerProps, KeyAttributes, KeyState, KnobContextValue, KnobMethods, KnobProps, KnobSVGRootProps, KnobThumbProps, NumberInputContextValue, NumberInputMethods, NumberInputProps, PianoMethods, PianoProps, PointsEditorContextValue, PointsEditorPointProps, PointsEditorProps, SliderContextValue, SliderMarksOptionProps, SliderMarksProps, SliderMethods, SliderProps, SliderThumbMethods, SliderThumbProps, SliderTrackProps, UseAnimationFrameOptions, UseDragOptions, UseDragValueOptions, UseDropZoneOptions, UseEventListenerOptions, UseEventListenerTarget, UseWheelOptions, XYPadContextValue, XYPadMethods, XYPadProps, XYPadThumbMethods, XYPadThumbProps };
 //# sourceMappingURL=index.d.cts.map