@tremolo-ui/dom 0.8.0 → 0.9.0

package/dist/index.d.cts

@@ -1,3 +1,4 @@
+import { D as ModifierState, E as ModifierMap, O as ModifierValue, S as notePosition, T as Modifier, _ as NoteRange, c as PointsEditorInstance, f as createPointsEditor, h as XYInput, l as PointsEditorOptions, m as XY, p as SelectionBoxRect, s as PointPosition, t as MarksOptions, u as PointsEditorPoint, v as PianoLayout, w as InputEventOption } from "./marks-DK7xJmGM.cjs";
 import { Scale, ValueRange } from "@tremolo-ui/functions";
 //#region src/canvas/animation.d.ts
 /** What the canvas looked like when a frame was drawn. */
@@ -15,7 +16,15 @@ interface AnimationFrame {
   /** Frames per second implied by `deltaTime`, or 0 when no time elapsed. */
   fps: number;
 }
+/**
+ * Draws one frame, given the 2D context and the frame: the size in CSS pixels,
+ * `count`, `deltaTime`, `elapsedTime` and `fps`.
+ */
 type CanvasDrawFunction = (context: CanvasRenderingContext2D, frame: AnimationFrame) => void;
+/**
+ * Sets up what every frame shares. Called once, with the context and the size
+ * in CSS pixels, before the first frame; not again on a resize.
+ */
 type CanvasInitFunction = (context: CanvasRenderingContext2D, size: {
   width: number;
   height: number;
@@ -91,67 +100,6 @@ interface AnimationCanvasInstance {
  */
 export declare function createAnimationCanvas(canvas: HTMLCanvasElement, options: AnimationCanvasOptions): AnimationCanvasInstance;
 //#endregion
-//#region src/canvas/context.d.ts
-/**
- * The assignable parts of a 2D context's drawing state. They have to be
- * carried across a resize by hand because setting `canvas.width` resets the
- * context to its defaults. The transform and line dash are handled separately
- * by {@link DrawingContext} because they are exposed through methods.
- *
- * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/save
- */
-export declare const drawingState: readonly ["strokeStyle", "fillStyle", "globalAlpha", "lineWidth", "lineCap", "lineJoin", "miterLimit", "lineDashOffset", "shadowOffsetX", "shadowOffsetY", "shadowBlur", "shadowColor", "globalCompositeOperation", "filter", "font", "fontKerning", "fontStretch", "fontVariantCaps", "textAlign", "textBaseline", "direction", "letterSpacing", "textRendering", "wordSpacing", "imageSmoothingEnabled", "imageSmoothingQuality"];
-type DrawingState = (typeof drawingState)[number];
-type DrawingStateValue = CanvasRenderingContext2D[DrawingState];
-type DrawingContext = Pick<CanvasRenderingContext2D, DrawingState> & {
-  /** The current line dash sequence. */
-  lineDash: number[];
-  /** The current transformation matrix. */
-  transform: DOMMatrix;
-};
-export declare function isDrawingState(value: unknown): value is DrawingState;
-//#endregion
-//#region src/file/accept.d.ts
-/**
- * What an `accept` rule is matched against.
- *
- * `File` satisfies it, and so does `DataTransferItem` — which matters while a
- * drag is still in the air, since the browser reports the type of what is
- * being dragged but withholds the name.
- */
-interface AcceptCandidate {
-  /** The file name, when it is known. */
-  name?: string;
-  /** The MIME type, or `''` when the browser has no type for it. */
-  type: string;
-}
-/**
- * Does a file satisfy an `accept` attribute?
- *
- * `accept` is written the way the HTML attribute is: a comma separated list of
- * extensions (`.wav`), MIME types (`audio/wav`) and type groups (`audio/*`).
- * Anything that matches one entry is accepted, and an empty or missing
- * `accept` takes everything.
- *
- * **The browser's own `accept` is only a hint to the file picker.** A person
- * can switch it to "All Files", drag a file in, or pick one the picker was
- * never asked about, so what arrives still has to be checked.
- *
- * A rule that cannot be decided is not treated as a rejection: with no `name`,
- * an extension rule says nothing either way, and `accept=".wav"` reports a
- * match rather than refusing a file it has not seen the name of. The name is
- * there by the time the file is dropped, which is when the answer counts.
- */
-export declare function matchesAccept(candidate: AcceptCandidate, accept?: string): boolean;
-/**
- * Split files into those that satisfy `accept` and those that do not, keeping
- * their order. See {@link matchesAccept}.
- */
-export declare function partitionByAccept(files: Iterable<File>, accept?: string): {
-  accepted: File[];
-  rejected: File[];
-};
-//#endregion
 //#region src/file/drop-zone.d.ts
 /** What is in the air over the element. */
 interface DropZoneState {
@@ -221,130 +169,55 @@ interface DropZoneInstance {
  */
 export declare function createDropZone(element: Element, options?: DropZoneOptions): DropZoneInstance;
 //#endregion
-//#region src/input/modifiers.d.ts
-/**
- * Options for setting the amount of keyboard and mouse wheel changes.
- */
-type InputEventOption = readonly ['normalized' | 'raw', number];
-/**
- * A modifier key that can carry an amount of its own.
- *
- * `ctrl` and `meta` are kept apart rather than folded into one "command" key:
- * a plugin UI that mirrors a desktop host usually wants the same physical key
- * on every platform, not the platform's own convention.
- */
-type Modifier = 'shift' | 'alt' | 'ctrl' | 'meta';
-/** The modifier flags of a `WheelEvent` or a `KeyboardEvent`. */
-interface ModifierState {
-  shiftKey: boolean;
-  altKey: boolean;
-  ctrlKey: boolean;
-  metaKey: boolean;
+//#region src/input/change-gesture.d.ts
+/** What a change of value was made with. */
+type ChangeSource = 'pointer' | 'wheel' | 'keyboard' | 'doubleClick';
+interface ChangeGestureOptions {
+  /** Called before the first change of a gesture. */
+  onStart?: (source: ChangeSource) => void;
+  /** Called after the last change of a gesture. */
+  onEnd?: (source: ChangeSource) => void;
+  /**
+   * How long after the last wheel notch or key press a gesture counts as
+   * over, in milliseconds. Neither has an event that says it is done, so the
+   * gesture ends when nothing more arrives for this long.
+   *
+   * @default 500
+   */
+  endDelay?: number;
 }
-/** One setting per modifier key, with `default` for none of them. */
-type ModifierSetting = number | InputEventOption;
-type ModifierMap<T extends ModifierSetting> = {
-  default: T;
-} & Partial<Record<Modifier, T>>;
-/**
- * A single setting, or one per modifier key.
- *
- * @example
- * ['raw', 1]
- * { default: ['raw', 1], shift: ['raw', 0.1] }
- */
-type ModifierValue<T extends ModifierSetting> = T | ModifierMap<T>;
-/**
- * Pick the setting that applies, given the modifier keys being held.
- *
- * @example
- * selectModifier({ default: 1, shift: 0.1 }, event)
- */
-export declare function selectModifier<T extends ModifierSetting>(options: ModifierValue<T>, modifiers?: ModifierState): {
-  value: T;
-  modifier: Modifier | null;
-};
-/**
- * Turn every entry of a setting into another kind of setting, keeping which
- * modifier each belongs to.
- *
- * A drag sensitivity is a number and a keyboard amount is a tuple, but the two
- * describe the same thing from the caller's side. This carries one over to the
- * other so that a component can hand a sensitivity to {@link applyDelta}
- * without unpicking the modifier map itself — which matters, since naming a
- * modifier is also what takes `step` out of the pipeline.
- *
- * @example
- * mapModifier({ default: 1, shift: 0.1 }, (f) => ['raw', step * f])
- * // { default: ['raw', 1], shift: ['raw', 0.1] }
- */
-export declare function mapModifier<T extends ModifierSetting, U extends ModifierSetting>(options: ModifierValue<T>, fn: (value: T) => U): ModifierValue<U>;
-//#endregion
-//#region src/input/apply-delta.d.ts
-/**
- * Move a value by an amount of input, as reported by a wheel or an arrow key.
- *
- * The pipeline matches {@link createDragValue}: scale, then step, then clamp.
- * Which key or which sign of `deltaY` counts as which direction is left to the
- * caller, since it differs per component.
- *
- * @param direction which way, and how many times, to apply the option. The
- * size of one step is `option[1]`, so this is normally `1` or `-1`.
- *
- * @param modifiers the event, for `options` that name a modifier key. See
- * {@link selectModifier}.
- *
- * @example
- * // ArrowDown on a slider whose keyboard option is ['raw', 1]
- * applyDelta(value, -1, keyboard, { min, max, step, scale })
- *
- * @example
- * // Shift+ArrowDown, where `keyboard` is { default: …, shift: ['raw', 0.1] }
- * applyDelta(value, -1, keyboard, range, event)
- */
-export declare function applyDelta(value: number, direction: number, options: ModifierValue<InputEventOption>, { min, max, step, scale }: ValueRange, modifiers?: ModifierState): number;
-//#endregion
-//#region src/input/check-steps.d.ts
-interface CheckStepsOptions {
-  /** The component, for the message. */
-  component: string;
-  /** The axis, for a component that has more than one. */
-  axis?: string;
+interface ChangeGestureInstance {
+  /**
+   * Start a gesture that lasts until {@link end}, such as a drag. A gesture of
+   * another kind in progress ends first.
+   */
+  hold: (source: ChangeSource) => void;
   /**
-   * The range to probe, or `null` to check nothing. An unbounded input has no
-   * travel to sample, so `NumberInput` passes `null` when `min` and `max` are
-   * not both there.
+   * One step of a gesture with no end of its own, such as a wheel notch:
+   * starts one if none is in progress, and ends it `endDelay` after the last
+   * step. While a held gesture is in progress the step belongs to it.
    */
-  range: ValueRange | null;
-  keyboard?: ModifierValue<InputEventOption> | null;
-  wheel?: ModifierValue<InputEventOption> | null;
+  pulse: (source: ChangeSource) => void;
   /**
-   * How the value is displayed, where the component shows one. Called with
-   * probe values only.
+   * A gesture that starts and ends around a single change, such as a reset:
+   * `change` runs between the two.
    */
-  format?: (value: number) => string;
+  instant: (source: ChangeSource, change: () => void) => void;
+  /** End the gesture in progress, if any. */
+  end: () => void;
+  /** Whether a gesture is in progress. */
+  active: () => boolean;
+  /** Replace the given options. A gesture in progress picks them up. */
+  update: (options: Partial<ChangeGestureOptions>) => void;
+  /** End a gesture in progress, so that nothing is left touched. */
+  destroy: () => void;
 }
 /**
- * The warnings to show when a key press or a wheel notch cannot produce a
- * change the user can see. Empty when there is nothing to say.
- *
- * Two settings that are each fine on their own can cancel out, and nothing
- * fails when they do — the control simply sits there:
- *
- * - **`step` coarser than the amount.** `keyboard={['raw', 0.1]}` with
- *   `step={1}` rounds every press straight back to where it started
- * - **the display coarser than the amount.** A `format` showing two decimals
- *   of a kHz value cannot show a press worth 1 Hz
- *
- * The second is only reported when the press is invisible at *every* point
- * along the travel. A display that rounds is a deliberate choice and is
- * normally right — it is being too coarse everywhere that makes it a mistake.
- *
- * **Meant for development builds only.** It probes the whole travel, so call
- * it behind an inline `process.env.NODE_ENV` check: the bundler then drops
- * the call, and this function and its messages with it.
+ * Track when a change of value starts and ends, whatever made it: a drag, the
+ * wheel, the keys or a reset. A host that records automation needs both ends
+ * to know when the control is touched.
  */
-export declare function checkSteps({ component, axis, range, keyboard, wheel, format }: CheckStepsOptions): string[];
+export declare function createChangeGesture(options?: ChangeGestureOptions): ChangeGestureInstance;
 //#endregion
 //#region src/input/defaults.d.ts
 /**
@@ -370,74 +243,6 @@ export declare const DEFAULT_WHEEL_OPTIONS: ModifierValue<InputEventOption>;
  */
 export declare const DEFAULT_DRAG_SENSITIVITY: ModifierValue<number>;
 //#endregion
-//#region src/input/direction.d.ts
-/**
- * Which way an input moves a value, before any amount is applied.
- *
- * `applyDelta` takes the direction as given, since which key or which sign of
- * `deltaY` counts as "up" differs per control. The answers are collected here
- * so that every wrapper gives the same one: a knob that turns the other way
- * in one framework would be a bug nobody could see from the code.
- *
- * Two families, by what the control looks like:
- *
- * - **one value** (`Knob`, `Slider`, `NumberInput`): right and up raise it
- * - **a position on screen** (`XYPad`, `PointsEditor`): in screen coordinates,
- *   x growing rightwards and y growing downwards, plus which axis moves
- *
- * A control that runs the other way (`reverse`) flips the result itself.
- */
-/** One of the four arrow keys, as `KeyboardEvent.key` names it. */
-type ArrowKey = 'ArrowRight' | 'ArrowLeft' | 'ArrowUp' | 'ArrowDown';
-/** Is `key` one of the four arrow keys? */
-export declare function isArrowKey(key: string): key is ArrowKey;
-/** A move along one of the two axes of a position on screen. */
-interface AxisMove {
-  /** 0 = x, 1 = y. */
-  axis: 0 | 1;
-  /** `1` towards the right or the bottom, `-1` towards the left or the top. */
-  direction: 1 | -1;
-}
-/**
- * The direction an arrow key moves a single value: right and up raise it.
- * `null` for any other key.
- */
-export declare function arrowKeyDirection(key: string): 1 | -1 | null;
-/**
- * The axis and direction an arrow key moves a position on screen. `null` for
- * any other key.
- *
- * The key picks the axis, whichever element inside the control holds the
- * focus: a two-dimensional control is one control to the person moving it.
- */
-export declare function arrowKeyMove(key: string): AxisMove | null;
-interface WheelDirectionOptions {
-  /**
-   * Read horizontal scrolling as well, for a control laid out horizontally:
-   * scrolling right raises the value. Vertical scrolling still counts when
-   * there is no horizontal movement.
-   *
-   * @default false
-   */
-  horizontal?: boolean;
-}
-/**
- * The direction one wheel event moves a single value: scrolling up raises it.
- * `null` when the event carries no movement the control reads.
- */
-export declare function wheelDirection(event: Pick<WheelEvent, 'deltaX' | 'deltaY'>, { horizontal }?: WheelDirectionOptions): 1 | -1 | null;
-/**
- * The axis and direction one wheel event moves a position on screen. `null`
- * when the event carries no movement.
- *
- * Scrolling moves y, and shift switches to x. Browsers turn shift+wheel into
- * horizontal scrolling: `deltaY` comes out empty and `deltaX` carries the
- * movement. Reading whichever axis moved keeps shift working as the x-axis
- * modifier — and picks up a trackpad's own horizontal gesture, which never
- * had a modifier.
- */
-export declare function wheelMove(event: Pick<WheelEvent, 'deltaX' | 'deltaY' | 'shiftKey'>): AxisMove | null;
-//#endregion
 //#region src/knob/geometry.d.ts
 /**
  * Width and height of the viewBox a knob is drawn in. The arcs and the thumb
@@ -473,17 +278,6 @@ interface KnobAngles {
   r4: number;
 }
 export declare function knobAngles({ value, min, max, scale, startValue, angleRange }: KnobAngleOptions): KnobAngles;
-/**
- * The point at `angle` on a circle of `radius` around the centre of the
- * viewBox.
- *
- * The radius depends on the stroke of the line being drawn, which each arc
- * has its own of, so the point is found per arc rather than once for the knob.
- */
-export declare function knobArcPoint(angle: number, radius: number): {
-  x: number;
-  y: number;
-};
 /**
  * The radius that keeps a stroke of `strokeWidth` inside the viewBox: half of
  * the stroke falls outside the path it is drawn along.
@@ -493,14 +287,16 @@ export declare function knobArcRadius(strokeWidth: number | string | undefined):
 export declare function knobArcPath(startAngle: number, endAngle: number, radius: number): string;
 //#endregion
 //#region src/midi/access.d.ts
-/** @private */
-export declare const PERMISSION_DENIED = "PERMISSION_DENIED";
-/** @private */
-export declare const NOT_SUPPORTED = "NOT_SUPPORTED";
-/** @private */
-export declare const UNAVAILABLE = "UNAVAILABLE";
-/** @private */
-type MIDIAccessError = typeof PERMISSION_DENIED | typeof NOT_SUPPORTED | typeof UNAVAILABLE;
+/**
+ * Why MIDI access could not be had.
+ *
+ * - `'NOT_SUPPORTED'`: the browser has no Web MIDI API, and asking again will
+ *   not change that
+ * - `'PERMISSION_DENIED'`: the user or the browser said no. Asking again is
+ *   worthwhile
+ * - `'UNAVAILABLE'`: anything else
+ */
+type MIDIAccessError = 'NOT_SUPPORTED' | 'PERMISSION_DENIED' | 'UNAVAILABLE';
 type MIDIAccessOptions = {
   /**
    * Ask for system exclusive messages as well.
@@ -542,13 +338,6 @@ interface MIDIAccessInstance {
 export declare function createMIDIAccess(): MIDIAccessInstance;
 //#endregion
 //#region src/midi/input.d.ts
-/**
- * Centre of the 14-bit pitch bend range: no bend.
- *
- * The range is not symmetric — 0 is 8192 below centre and 16383 is 8191 above
- * — so a wheel at rest reports exactly this rather than half of the maximum.
- */
-export declare const PITCH_BEND_CENTER = 8192;
 /**
  * Every handler is given the channel last, as 0-15. MIDI channels are written
  * 1-16 on hardware, so add one before showing it to anyone.
@@ -557,7 +346,8 @@ type MIDIInputHandlers = {
   onNoteOnEvent?: (note: number, velocity: number, channel: number) => void;
   onNoteOffEvent?: (note: number, channel: number) => void;
   /**
-   * The 14-bit bend, 0-16383, centred at {@link PITCH_BEND_CENTER}.
+   * The 14-bit bend, 0-16383, centred at 8192. `normalizePitchBend` in
+   * `@tremolo-ui/functions` turns it into -1 to 1.
    *
    * The two data bytes are little-endian — the first carries the low 7 bits —
    * which is the other way round from every other message.
@@ -604,259 +394,6 @@ interface MIDIMessageInstance {
  */
 export declare function createMIDIMessage(midiAccess: MIDIAccess | null, onMIDIMessage: (event: MIDIMessageEvent) => void): MIDIMessageInstance;
 //#endregion
-//#region src/number-input/stepper-drag.d.ts
-interface StepperDragOptions {
-  /** The value now, read when the drag starts moving it. */
-  getValue: () => number;
-  /**
-   * The range the value moves across. Its `step` is what one step of the drag
-   * is worth; see `numberInputRanges` for the one a number input uses.
-   */
-  range: ValueRange;
-  /**
-   * How many pixels of vertical movement make one step.
-   *
-   * @default 1
-   */
-  pixels?: number;
-  /**
-   * How much a step is worth, per modifier key: `0.1` makes the same movement
-   * count a tenth as much. Pressing or releasing the key mid-drag does not
-   * move the value.
-   *
-   * @default { default: 1, shift: 0.1 }
-   */
-  sensitivity?: ModifierValue<number>;
-  /** Hide the pointer and keep it from hitting the edge of the screen. */
-  pointerLock?: boolean;
-  /** Called with the new value whenever the drag moves it. */
-  onChange: (value: number) => void;
-}
-interface StepperDragInstance {
-  /** Replace the given options. `pointerLock` reaches the next drag. */
-  update: (options: Partial<StepperDragOptions>) => void;
-  /**
-   * Whether the drag in progress has moved the value. A stepper button's
-   * press-and-hold repeat stands down once it has, so the value is not moved
-   * twice.
-   */
-  moved: () => boolean;
-  destroy: () => void;
-}
-/**
- * Drag up and down on the steppers of a number input to move its value, one
- * `step` every `pixels` — up raises it, as on a knob.
- *
- * Counted from where the drag started moving rather than added up per
- * event, so rounding cannot accumulate. The start is taken on the first
- * move, not on pointerdown: a stepper button acts on pointerdown, so by then
- * the value may already have been nudged once, and the drag carries on from
- * there.
- */
-export declare function createStepperDrag(element: Element, options: StepperDragOptions): StepperDragInstance;
-//#endregion
-//#region src/number-input/value.d.ts
-/**
- * The value a number input edits, and how far it may go.
- *
- * Unlike a slider, either end may be left open, and `clampValue: false` lets
- * the value past the ends that are set.
- */
-interface NumberInputValueOptions {
-  min?: number;
-  max?: number;
-  step?: number;
-  scale?: Scale;
-  /**
-   * Keep the value between `min` and `max`.
-   *
-   * @default true
-   */
-  clampValue?: boolean;
-}
-/** The ranges {@link nudgeNumberInput} moves a value across. */
-interface NumberInputRanges {
-  /** For a `normalized` amount, which needs a finite span to take a share of. */
-  normalized: ValueRange;
-  /** For a `raw` amount, which does not. */
-  raw: ValueRange;
-}
-/**
- * The ranges a number input moves its value across, with the open ends
- * filled in.
- *
- * A normalized amount needs a finite span even when an end is unbounded or
- * clamping is off. Safe integers provide one without overflowing the span a
- * scale calculates. A raw amount needs no span, so its open ends can cover
- * every finite number instead of stopping at the safe-integer range.
- */
-export declare function numberInputRanges({ min, max, step, scale, clampValue }: NumberInputValueOptions): NumberInputRanges;
-/**
- * Move a number input's value by one press of a key, a wheel notch or a
- * stepper, picking the range that suits the kind of amount. See `applyDelta`.
- */
-export declare function nudgeNumberInput(value: number, direction: number, options: ModifierValue<InputEventOption>, ranges: NumberInputRanges, modifiers?: ModifierState): number;
-/**
- * Where the value stands against the ends: whether it can go no further
- * down or up, and whether it lies outside them — which only an unclamped
- * input, or a value set from outside, can do.
- */
-export declare function numberInputBounds(value: number, { min, max, clampValue }: NumberInputValueOptions): {
-  atMin: boolean;
-  atMax: boolean;
-  outOfRange: boolean;
-};
-/**
- * The value typed text commits to, or `null` when there is no number in it.
- *
- * Text with no number is not a value: the input should go back to what it
- * was showing rather than commit a zero the user never typed. What is read
- * is clamped here and not while typing, since clamping as the user types
- * would make "1500" impossible to enter into an input whose max is 100.
- */
-export declare function commitNumberInputText(text: string, parse: (text: string) => number, { min, max, clampValue }: NumberInputValueOptions): number | null;
-//#endregion
-//#region src/number-input/text.d.ts
-/**
- * Reading a number out of the text of a number input, and keeping the caret
- * in place while the number under it changes.
- *
- * The text is whatever `format` made of the value — `"440 Hz"`, `"-6.0 dB"` —
- * or a half-typed entry, so none of this assumes the text is a number alone.
- */
-/** Where the number is in the text; the rest, on either side, is the unit. */
-interface NumberSpan {
-  start: number;
-  end: number;
-}
-/**
- * Where the number is in the text: from its first digit to its last, with the
- * sign and the decimal point in front of it. Whatever is left on either side
- * is taken for the unit, so it does not matter whether a space separates them,
- * or what the number looks like — `+6.0`, `1e+21`, `1,000` and `1:30` are each
- * one number. `null` when the text has no digit at all.
- */
-export declare function numberSpan(text: string): NumberSpan | null;
-/**
- * The number in the text, with the unit after it ignored: the default `parse`
- * of a number input.
- *
- * `NaN`, which leaves the value alone, whenever the number cannot be read
- * safely, rather than a part of it: text with no number, a number that is not
- * a plain one (`1,000` would otherwise read as 1, and `1:30` as 1), and text
- * with something in front of the number, which can change what it means (the
- * `L` of a pan reading `L 30`). A `format` that writes any of those needs its
- * own `parse`.
- */
-export declare function parseNumberText(text: string): number;
-/**
- * Where the caret is, relative to the decimal point, so that it can be put
- * back at the same digit once the value has changed. See
- * {@link caretAtDecimalOffset}.
- */
-export declare function caretDecimalOffset(text: string, caret: number): number;
-/**
- * The caret position `offset` characters from the decimal point of the new
- * text, kept within the number.
- *
- * @example
- * // The caret sits in front of the point of "9.9" when ArrowUp turns it
- * // into "10.0"
- * const offset = caretDecimalOffset('9.9', 1) // 0
- * caretAtDecimalOffset('10.0', offset) // 2: still in front of the point
- */
-export declare function caretAtDecimalOffset(text: string, offset: number): number;
-//#endregion
-//#region src/options/replace.d.ts
-/**
- * The `update()` argument that leaves an instance with exactly `next` as its
- * options.
- *
- * `update()` merges into what the instance has, which suits a wrapper that
- * pushes one setting at a time. A wrapper handed the whole new set instead —
- * a Svelte action, a Vue composable — has to clear what the new set no longer
- * carries, or a handler taken away, or an option left to its default, keeps
- * working.
- *
- * @example
- * instance.update(replaceOptions(previous, next))
- */
-export declare function replaceOptions<T extends object>(previous: T | undefined, next: T | undefined): Partial<T>;
-//#endregion
-//#region src/piano/layout.d.ts
-type NoteRange = {
-  first: number;
-  last: number;
-};
-/**
- * `[noteRange.first, noteRange.first + 1, ..., noteRange.last]`
- */
-export declare function getNoteRangeArray(noteRange: NoteRange): number[];
-/**
- * The geometry of a drawn keyboard.
- *
- * One description is shared by the drawing and the hit testing, so a key cannot
- * be drawn somewhere other than where it responds.
- */
-interface PianoLayout {
-  noteRange: NoteRange;
-  /** Width of a white key, excluding {@link PianoLayout.keyGap}. */
-  whiteKeyWidth: number;
-  /**
-   * Space between two white keys. Part of the slot a white key occupies, so it
-   * still belongs to one of the keys for the purpose of hit testing.
-   *
-   * @default 1
-   */
-  keyGap?: number;
-  /**
-   * Width of a black key, as a fraction of {@link PianoLayout.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;
-}
-/** Width of a black key in pixels. */
-export declare function blackKeyWidth(layout: PianoLayout): number;
-/** Width of the whole keyboard in pixels. */
-export declare function pianoWidth(layout: PianoLayout): number;
-/**
- * Offset of the left edge of a key from the left edge of the keyboard, in
- * pixels.
- *
- * Notes outside `noteRange` are placed too, so the value is negative below
- * `noteRange.first`.
- */
-export declare function notePosition(note: number, layout: PianoLayout): number;
-/**
- * The note drawn at a point, or null where there is none.
- *
- * Black keys are tested first, so they win where they overlap a white one. A
- * white key covers its gap as well as its width, so the whole width of the
- * keyboard belongs to some key and a click cannot fall between two.
- *
- * @param x offset from the left edge of the keyboard, in pixels
- * @param y offset from its top edge, in pixels
- * @param height height of the keyboard, in pixels
- */
-export declare function noteAt(x: number, y: number, height: number, layout: PianoLayout): number | null;
-/**
- * The white key width that makes the keyboard exactly `width` wide, for a
- * keyboard that follows the size of its container.
- *
- * Solved from {@link pianoWidth} rather than by dividing among the white
- * keys, so that a range that starts or ends on a black key — which sticks out
- * by a fraction of a white key — still fills the container. The width grows
- * linearly with the white key width, so two samples pin it down.
- */
-export declare function fitWhiteKeyWidth(width: number, layout: Omit<PianoLayout, 'whiteKeyWidth'>): number;
-//#endregion
 //#region src/piano/shortcuts.d.ts
 type KeyboardShortcuts = {
   /**
@@ -976,219 +513,6 @@ interface PianoInputInstance {
  */
 export declare function createPianoInput(element: Element, options: PianoInputOptions): PianoInputInstance;
 //#endregion
-//#region src/xy.d.ts
-/**
- * A pair of per-axis values. The tuple elements are labelled, so editors show
- * `[x: number, y: number]` rather than a bare pair.
- */
-type XY<T> = [x: T, y: T];
-/**
- * A setting that may be given once for both axes, or per axis.
- *
- * A single value is told from a pair with `Array.isArray`, so the single form
- * is only offered while `T` cannot itself be an array. Where it can, the pair
- * is the only way to write it, since a lone array would be read as a pair.
- */
-type XYInput<T> = [T] extends [readonly unknown[]] ? readonly [x: T, y: T] : T | readonly [x: T, y: T];
-/**
- * Spread a setting that may have been given as a single value.
- *
- * The parameter is written out rather than taken as `XYInput<T>`: a
- * conditional type cannot be narrowed, so the constraint stays where it is
- * declared and this takes both forms.
- *
- * The pair is copied rather than passed along, so that the result is a tuple
- * the caller owns even when a readonly one was given.
- */
-export declare function toXY<T>(value: T | readonly [x: T, y: T]): XY<T>;
-//#endregion
-//#region src/selection/box.d.ts
-/**
- * A rectangle in the 0..1 space of whatever the box is drawn over, with `y`
- * growing downwards — the same space the items are given in.
- */
-interface SelectionBoxRect {
-  x: number;
-  y: number;
-  width: number;
-  height: number;
-}
-interface SelectionBoxOptions<Id> {
-  /**
-   * Everything the box can pick up, read on every move rather than taken as a
-   * snapshot: what is under the box changes while it is dragged, and an item
-   * may have moved since the last one.
-   */
-  items: () => Iterable<readonly [Id, XY<number>]>;
-  /** The box as it is dragged, and `null` once it is gone. */
-  onBoxChange?: (box: SelectionBoxRect | null) => void;
-  /** What the box covers, added to whatever it started from. */
-  onSelectionChange?: (ids: Id[]) => void;
-}
-interface SelectionBoxBeginOptions<Id> {
-  /**
-   * Add to `selection` rather than replacing it. Ctrl / meta rather than
-   * shift, for the controls where shift is the fine-adjustment key.
-   */
-  additive?: boolean;
-  /** What was selected before the box started. Only read when `additive`. */
-  selection?: readonly Id[];
-}
-interface SelectionBoxInstance<Id> {
-  /** Replace the given options, without interrupting a box in progress. */
-  update: (options: Partial<SelectionBoxOptions<Id>>) => void;
-  /** Start a box at `at`, which is one of its corners. */
-  begin: (at: XY<number>, options?: SelectionBoxBeginOptions<Id>) => void;
-  /** Drag the opposite corner to `to`. */
-  move: (to: XY<number>) => void;
-  /**
-   * Finish the box. The selection stays as it is.
-   *
-   * @returns whether a box was running, so that a caller can tell a drag from
-   *   a press that selected nothing.
-   */
-  end: () => boolean;
-  /** The box being dragged, or `null` when there is none. */
-  box: () => SelectionBoxRect | null;
-  destroy: () => void;
-}
-/** Whether the box covers the point, edges included. */
-export declare function selectionBoxCovers(box: SelectionBoxRect, [x, y]: XY<number>): boolean;
-/**
- * Selecting by dragging a box over a set of items.
- *
- * The drag itself is not here: the caller owns the pointer, and reports where
- * it went in the same 0..1 space the items are given in.
- */
-export declare function createSelectionBox<Id>(options: SelectionBoxOptions<Id>): SelectionBoxInstance<Id>;
-//#endregion
-//#region src/points-editor/index.d.ts
-/** Where a point is: 0..1 on each axis, with y growing downwards. */
-interface PointPosition {
-  x: number;
-  y: number;
-}
-/**
- * A point's value is its position in the editor, so its range is the editor:
- * no scaling, and no rounding to a step.
- */
-export declare const POINT_AXIS: {
-  min: number;
-  max: number;
-};
-/**
- * How much one wheel notch moves a point by default: a hundredth of the
- * editor, whatever its pixel size.
- */
-export declare const POINTS_EDITOR_DEFAULT_WHEEL: ModifierValue<InputEventOption>;
-/**
- * How much one arrow key press moves a point by default. Shift is the
- * fine-adjustment key everywhere else, so it is bound here too — but only on
- * the keyboard. On the wheel it already means the x axis, and browsers hand
- * shift+wheel over as horizontal scrolling anyway.
- */
-export declare const POINTS_EDITOR_DEFAULT_KEYBOARD: ModifierValue<InputEventOption>;
-/** Keep a point within its range. An axis left out runs from 0 to 1. */
-export declare function clampPoint(point: PointPosition, min?: Partial<PointPosition>, max?: Partial<PointPosition>): PointPosition;
-/**
- * What a point tells the editor about itself, so that a selection can be
- * moved without the editor knowing how the points are stored.
- */
-interface PointsEditorPoint {
-  value: PointPosition;
-  min?: Partial<PointPosition>;
-  max?: Partial<PointPosition>;
-  /** A point that cannot move stays put while the rest of a selection moves. */
-  readonly?: boolean;
-  onChange?: (value: PointPosition) => void;
-  /** The point's own element, to match the focus and a press against. */
-  element?: Element | null;
-  /** The wheel option the point resolved, `null` for no wheel. */
-  wheel?: ModifierValue<InputEventOption> | null;
-}
-interface PointsEditorOptions {
-  /**
-   * Let points be selected, and a selection be moved as one. While it is off
-   * nothing is selected, and a drag moves only the point it started on.
-   *
-   * @default false
-   */
-  selectable?: boolean;
-  /**
-   * The ids of the selected points. Whoever holds the selection pushes it
-   * back with `update()` after {@link PointsEditorOptions.onSelectionChange}.
-   */
-  selection?: readonly string[];
-  /** Called whenever a press or a selection box changes the selection. */
-  onSelectionChange?: (selection: string[]) => void;
-  /** Called whenever the selection box changes, with `null` once it is gone. */
-  onSelectionBoxChange?: (rect: SelectionBoxRect | null) => void;
-}
-interface PointsEditorInstance {
-  /** Replace the given options. */
-  update: (options: Partial<PointsEditorOptions>) => void;
-  /**
-   * Register a point under `id`. `read` is called whenever the editor needs
-   * the point, so it can return what the point is now rather than what it
-   * was when it registered. Returns the function that unregisters it.
-   */
-  registerPoint: (id: string, read: () => PointsEditorPoint) => () => void;
-  /** Whether the element is a point, or inside one. */
-  isPointElement: (element: Element | null | undefined) => boolean;
-  /**
-   * A pointer went down on a point: work out the new selection and remember
-   * where everything the drag picked up started.
-   *
-   * Ctrl / meta add the point to the selection or take it out: shift is the
-   * fine-adjustment key on every control here, and it cannot be both. A
-   * press on a point already selected keeps the selection, so the group can
-   * be dragged.
-   */
-  beginPointDrag: (id: string, modifiers: ModifierState) => void;
-  /**
-   * Move everything the drag picked up by `delta` from where it started,
-   * stopping the whole group together at the edge.
-   */
-  movePointDrag: (delta: PointPosition) => void;
-  /**
-   * Move `id` — and the selection, when it is part of one — by `delta` from
-   * where the points are now: an input that is not a drag has no earlier
-   * position to measure against.
-   */
-  nudgeSelection: (id: string, delta: PointPosition) => void;
-  /**
-   * Move `id` by one press of `option` along one axis, taking the selection
-   * along as {@link PointsEditorInstance.nudgeSelection} does.
-   */
-  nudgePoint: (id: string, axis: 'x' | 'y', direction: number, option: ModifierValue<InputEventOption>, modifiers?: ModifierState) => void;
-  /**
-   * Move the point holding the focus by one wheel notch, with its own wheel
-   * option. The wheel is listened to once for the whole editor, since a wheel
-   * event only reaches what the cursor is over. Returns whether a point took
-   * it, so the caller knows whether to consume the event.
-   */
-  nudgeFocusedPoint: (axis: 'x' | 'y', direction: number, modifiers: ModifierState) => boolean;
-  /** A drag on empty space started at `at`: start a selection box there. */
-  beginSelectionBox: (at: PointPosition, modifiers: ModifierState) => void;
-  moveSelectionBox: (to: PointPosition) => void;
-  /**
-   * End the selection box. The press that started it left the focus on
-   * nothing, and the arrow keys and the wheel reach a point only through the
-   * focus, so it is handed to one of the points the box selected.
-   */
-  endSelectionBox: () => void;
-  destroy: () => void;
-}
-/**
- * The selection and the moves of a points editor: which points a press or a
- * box selects, and how a selection moves as one.
- *
- * The points stay with the wrapper, which registers each one; the editor only
- * reads them when it needs to, so a point's value can change on every frame
- * of a drag without anything being re-registered.
- */
-export declare function createPointsEditor(options?: PointsEditorOptions): PointsEditorInstance;
-//#endregion
 //#region src/pointer/drag.d.ts
 type DragState = {
   /** Total movement from the drag start, in screen coordinates. */
@@ -1490,8 +814,12 @@ export declare function createLongPress(options: LongPressOptions): LongPressIns
 //#endregion
 //#region src/pointer/wheel.d.ts
 interface WheelOptions {
-  /** Replace the callback through {@link WheelInstance.update}. */
-  onWheel?: (event: WheelEvent) => void;
+  /**
+   * Called for every wheel event that `requireFocus` lets through. The
+   * listener is not passive, so this may call `preventDefault()` to keep the
+   * page from scrolling.
+   */
+  onWheel: (event: WheelEvent) => void;
   /**
    * Only report events while the focus is inside the element.
    *
@@ -1509,7 +837,7 @@ interface WheelOptions {
 }
 interface WheelInstance {
   /** Replace the given options, keeping the listener in place. */
-  update: (options: WheelOptions) => void;
+  update: (options: Partial<WheelOptions>) => void;
   destroy: () => void;
 }
 /**
@@ -1518,7 +846,7 @@ interface WheelInstance {
  * The listener is registered with `passive: false` so that the handler can call
  * `preventDefault()` to stop the page from scrolling.
  */
-export declare function createWheel(element: Element, onWheel: (event: WheelEvent) => void, options?: WheelOptions): WheelInstance;
+export declare function createWheel(element: Element, options: WheelOptions): WheelInstance;
 //#endregion
 //#region src/position.d.ts
 /**
@@ -1531,70 +859,5 @@ export declare function createWheel(element: Element, onWheel: (event: WheelEven
  */
 export declare function valuePercent(value: number, { min, max, scale }: Pick<ValueRange, 'min' | 'max' | 'scale'>, reversed?: boolean): number;
 //#endregion
-//#region src/slider/marks.d.ts
-/**
- * How `Slider.Marks` fills itself in when it is given no children: one option
- * every `per`, or every `step` of the slider. The object form turns off the
- * mark or the label for the whole set; a single option is customized by
- * writing `Slider.MarksOption` out instead.
- */
-type MarksOptions = 'step' | number | {
-  per: 'step' | number;
-  mark?: boolean;
-  label?: boolean;
-};
-/** One mark along a slider, as {@link sliderMarks} lays them out. */
-interface SliderMark {
-  value: number;
-  mark: boolean;
-  label: boolean;
-}
-/**
- * The marks `options` asks for between `min` and `max`, in ascending order.
- *
- * Each value is a whole multiple of the interval, rounded to the digits the
- * interval has: stepping by 0.1 would otherwise put binary debris in the
- * labels (`0.1 * 3` is `0.30000000000000004`).
- */
-export declare function sliderMarks(options: MarksOptions, min: number, max: number, step: number): SliderMark[];
-//#endregion
-//#region src/style.d.ts
-/**
- * A number as a CSS length, for a custom property.
- *
- * A custom property takes whatever text it is given, so `--size: 50` comes out
- * as the invalid `50` rather than `50px`. React appends `px` to a bare number
- * only for the properties it knows take a length, and a custom property is
- * never one of them; Vue and Svelte append nothing at all. Anything already a
- * string is passed through, so `'3rem'` and `'100%'` still work.
- */
-export declare function cssLength(value: number | string | undefined): string | undefined;
-/**
- * Take an element out of sight while leaving it in the accessibility tree and
- * in the tab order.
- *
- * `display: none` and `visibility: hidden` would remove it from both, and the
- * native control underneath a headless component is what carries the ARIA and
- * the keyboard behaviour. `pointer-events: none` is safe because nothing is
- * ever clicked here directly: a `<label>` forwards its click, and a drag is
- * handled by the part that is visible.
- *
- * Every value is a string with its unit, so the object can be handed to any
- * framework's `style` binding as it is.
- */
-export declare const visuallyHiddenStyle: {
-  readonly position: "absolute";
-  readonly width: "1px";
-  readonly height: "1px";
-  readonly padding: "0";
-  readonly margin: "-1px";
-  readonly overflow: "hidden";
-  readonly clip: "rect(0, 0, 0, 0)";
-  readonly clipPath: "inset(50%)";
-  readonly whiteSpace: "nowrap";
-  readonly border: "0";
-  readonly pointerEvents: "none";
-};
-//#endregion
-export type { AcceptCandidate, AnimationCanvasInstance, AnimationCanvasOptions, AnimationFrame, ArrowKey, AxisMove, AxisOptions, CanvasDrawFunction, CanvasInitFunction, CheckStepsOptions, DragInstance, DragOptions, DragState, DragValueInstance, DragValueMapping, DragValueOptions, DrawingContext, DrawingState, DrawingStateValue, DropZoneInstance, DropZoneOptions, DropZoneState, InputEventOption, KeyboardShortcuts, KeyboardShortcutsScope, KnobAngleOptions, KnobAngles, LongPressInstance, LongPressOptions, MIDIAccessError, MIDIAccessInstance, MIDIAccessOptions, MIDIAccessState, MIDIInputHandlers, MIDIInputInstance, MIDIMessageInstance, MappingContext, MarksOptions, Modifier, ModifierMap, ModifierState, ModifierValue, NoteRange, NoteSource, NumberInputRanges, NumberInputValueOptions, NumberSpan, PianoInputInstance, PianoInputOptions, PianoLayout, PointPosition, PointsEditorInstance, PointsEditorOptions, PointsEditorPoint, SelectionBoxBeginOptions, SelectionBoxInstance, SelectionBoxOptions, SelectionBoxRect, SliderMark, StepperDragInstance, StepperDragOptions, WheelDirectionOptions, WheelInstance, WheelOptions, XY, XYInput };
+export { type AnimationCanvasInstance, type AnimationCanvasOptions, type AnimationFrame, type AxisOptions, type CanvasDrawFunction, type CanvasInitFunction, type ChangeGestureInstance, type ChangeGestureOptions, type ChangeSource, type DragInstance, type DragOptions, type DragState, type DragValueInstance, type DragValueMapping, type DragValueOptions, type DropZoneInstance, type DropZoneOptions, type DropZoneState, type InputEventOption, type KeyboardShortcuts, type KeyboardShortcutsScope, type KnobAngleOptions, type KnobAngles, type LongPressInstance, type LongPressOptions, type MIDIAccessError, type MIDIAccessInstance, type MIDIAccessOptions, type MIDIAccessState, type MIDIInputHandlers, type MIDIInputInstance, type MIDIMessageInstance, type MappingContext, type MarksOptions, type Modifier, type ModifierMap, type ModifierState, type ModifierValue, type NoteRange, type NoteSource, type PianoInputInstance, type PianoInputOptions, type PianoLayout, type PointPosition, type PointsEditorInstance, type PointsEditorOptions, type PointsEditorPoint, type SelectionBoxRect, type WheelInstance, type WheelOptions, type XY, type XYInput, createPointsEditor, notePosition };
 //# sourceMappingURL=index.d.cts.map