@tremolo-ui/dom 0.5.0 → 0.7.0

package/dist/index.d.cts

@@ -1,5 +1,4 @@
-import { PianoLayout, ValueRange } from "@tremolo-ui/functions";
-
+import { ValueRange } from "@tremolo-ui/functions";
 //#region src/canvas/animation.d.ts
 /** What the canvas looked like when a frame was drawn. */
 interface AnimationFrame {
@@ -13,7 +12,7 @@ interface AnimationFrame {
   deltaTime: number;
   /** Milliseconds since the instance was created. */
   elapsedTime: number;
-  /** Frames per second implied by `deltaTime`. */
+  /** Frames per second implied by `deltaTime`, or 0 when no time elapsed. */
   fps: number;
 }
 type CanvasDrawFunction = (context: CanvasRenderingContext2D, frame: AnimationFrame) => void;
@@ -34,7 +33,7 @@ interface AnimationCanvasOptions {
    */
   animate?: boolean;
   /**
-   * Size in CSS pixels. Ignored when `relativeSize` is on.
+   * Size in CSS pixels. Ignored when `resizable` is on.
    *
    * @default { width: 100, height: 100 }
    */
@@ -50,7 +49,7 @@ interface AnimationCanvasOptions {
    *
    * @default false
    */
-  relativeSize?: boolean;
+  resizable?: boolean;
   /**
    * Carry the drawing across a resize, so that the canvas does not blank for a
    * frame while the new size is drawn.
@@ -72,7 +71,7 @@ interface AnimationCanvasInstance {
    * render without restarting the animation, so the frame count and the
    * elapsed time keep running.
    *
-   * `relativeSize` and `contextAttributes` are fixed for the lifetime of the
+   * `resizable` and `contextAttributes` are fixed for the lifetime of the
    * instance and are ignored here.
    *
    * While `animate` is off this also draws a frame, since nothing else would.
@@ -90,36 +89,246 @@ interface AnimationCanvasInstance {
  * Drawing code works in CSS pixels: the context is scaled by the device pixel
  * ratio, and `width` / `height` of each {@link AnimationFrame} are CSS pixels.
  */
-declare function createAnimationCanvas(canvas: HTMLCanvasElement, options: AnimationCanvasOptions): AnimationCanvasInstance;
+export declare function createAnimationCanvas(canvas: HTMLCanvasElement, options: AnimationCanvasOptions): AnimationCanvasInstance;
 //#endregion
 //#region src/canvas/context.d.ts
 /**
- * The properties of a 2D context that survive `save()` / `restore()`, and so
- * are what has to be carried across a resize by hand: setting `canvas.width`
- * resets the context to its defaults.
+ * 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
  */
-declare const drawingState: readonly ["strokeStyle", "fillStyle", "globalAlpha", "lineWidth", "lineCap", "lineJoin", "miterLimit", "lineDashOffset", "shadowOffsetX", "shadowOffsetY", "shadowBlur", "shadowColor", "globalCompositeOperation", "font", "textAlign", "textBaseline", "direction", "imageSmoothingEnabled"];
+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>;
-declare function isDrawingState(value: unknown): value is 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;
+//#endregion
+//#region src/file/drop-zone.d.ts
+/** What is in the air over the element. */
+interface DropZoneState {
+  /** Files are being dragged over the element. */
+  over: boolean;
+  /**
+   * None of what is being dragged matches `accept`, as far as can be told
+   * before the drop.
+   *
+   * The browser reports the type of what is being dragged but withholds the
+   * name, so a rule written as an extension cannot be decided yet and is not
+   * counted against the drag. It is decided on the drop, where the name is.
+   */
+  invalid: boolean;
+}
+interface DropZoneOptions {
+  /**
+   * Which files to take, written the way the `accept` attribute of a file
+   * input is: a comma separated list of extensions (`.wav`), MIME types
+   * (`audio/wav`) and type groups (`audio/*`).
+   */
+  accept?: string;
+  /**
+   * Take more than one file from a single drop. With it off, only the first
+   * accepted file is reported, as a file input without `multiple` does.
+   *
+   * @default false
+   */
+  multiple?: boolean;
+  /**
+   * Refuse the drop. The drag is still swallowed rather than let through: an
+   * unhandled drop makes the browser leave the page and open the file.
+   *
+   * @default false
+   */
+  disabled?: boolean;
+  /** Called with the dropped files that match `accept`. */
+  onDrop?: (files: File[], event: DragEvent) => void;
+  /**
+   * Called with the dropped files that do not match `accept`, so that the
+   * reason can be shown.
+   */
+  onReject?: (files: File[], event: DragEvent) => void;
+  /** Called whenever {@link DropZoneInstance.state} would change. */
+  onStateChange?: (state: DropZoneState) => void;
+}
+interface DropZoneInstance {
+  /** What is in the air over the element, right now. */
+  readonly state: DropZoneState;
+  /** Replace the given options, keeping the listeners in place. */
+  update: (options: DropZoneOptions) => void;
+  destroy: () => void;
+}
+/**
+ * Take files dropped onto an element.
+ *
+ * ```ts
+ * const zone = createDropZone(element, {
+ *   accept: 'audio/*',
+ *   onDrop: (files) => load(files[0]),
+ * })
+ * ```
+ *
+ * The element needs no attribute of its own: a drop target is made by
+ * cancelling `dragover`, which this does.
+ */
+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;
+}
+/** 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/midi/access.d.ts
 /** @private */
-declare const PERMISSION_DENIED = "PERMISSION_DENIED";
+export declare const PERMISSION_DENIED = "PERMISSION_DENIED";
 /** @private */
-declare const NOT_SUPPORTED = "NOT_SUPPORTED";
+export declare const NOT_SUPPORTED = "NOT_SUPPORTED";
 /** @private */
-type MIDIAccessError = typeof PERMISSION_DENIED | typeof NOT_SUPPORTED;
+export declare const UNAVAILABLE = "UNAVAILABLE";
+/** @private */
+type MIDIAccessError = typeof PERMISSION_DENIED | typeof NOT_SUPPORTED | typeof UNAVAILABLE;
+type MIDIAccessOptions = {
+  /**
+   * Ask for system exclusive messages as well.
+   *
+   * Browsers treat this as a separate, more sensitive permission, so leave it
+   * off unless the app actually reads or sends sysex.
+   *
+   * @default false
+   */
+  sysex?: boolean;
+};
 type MIDIAccessState = {
   readonly midiAccess: MIDIAccess | null;
   readonly error: MIDIAccessError | null;
+  /**
+   * The inputs currently connected, in the order MIDIAccess lists them.
+   *
+   * Kept up to date as devices are plugged in and unplugged, so a UI listing
+   * the devices does not have to watch `statechange` itself.
+   */
+  readonly inputs: readonly MIDIInput[];
 };
 interface MIDIAccessInstance {
   /** Request MIDI access. Safe to call more than once. */
-  request: () => void;
+  request: (options?: MIDIAccessOptions) => void;
   getState: () => MIDIAccessState;
   /** Snapshot for server side rendering. Always the initial state. */
   getServerState: () => MIDIAccessState;
@@ -133,37 +342,136 @@ interface MIDIAccessInstance {
  * The returned instance holds the state and notifies subscribers when it changes,
  * so it can be consumed from any framework.
  */
-declare function createMIDIAccess(): 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.
+ */
+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 two data bytes are little-endian — the first carries the low 7 bits —
+   * which is the other way round from every other message.
+   */
+  onPitchBendEvent?: (value: number, channel: number) => void;
+  /** `controller` is the CC number, `value` is 0-127. */
+  onControlChangeEvent?: (controller: number, value: number, channel: number) => void;
+  onProgramChangeEvent?: (program: number, channel: number) => void;
+  /** Pressure for one held note (polyphonic aftertouch). */
+  onAftertouchEvent?: (note: number, pressure: number, channel: number) => void;
+  /** Pressure for the whole channel, sent by keyboards with one sensor. */
+  onChannelPressureEvent?: (pressure: number, channel: number) => void;
+};
+interface MIDIInputInstance {
+  /** Replace the handlers, keeping the listeners in place. */
+  update: (handlers: MIDIInputHandlers) => void;
+  destroy: () => void;
+}
+/**
+ * Handle the channel voice messages of every connected input. To be used with
+ * {@link createMIDIAccess}. Internally uses {@link createMIDIMessage}, so
+ * devices plugged in later are picked up.
+ *
+ * System messages (clock, sysex, and the rest of `0xf0`-`0xff`) are not
+ * decoded here; reach for {@link createMIDIMessage} for those.
+ */
+export declare function createMIDIInput(midiAccess: MIDIAccess | null, handlers: MIDIInputHandlers): MIDIInputInstance;
 //#endregion
 //#region src/midi/message.d.ts
 interface MIDIMessageInstance {
+  /** Replace the handler, keeping the listeners in place. */
+  update: (onMIDIMessage: (event: MIDIMessageEvent) => void) => void;
   destroy: () => void;
 }
 /**
  * Listen to raw `midimessage` events on every input of a MIDIAccess.
  *
+ * The set of inputs is followed rather than sampled: MIDIAccess fires
+ * `statechange` when a device is plugged in or unplugged, and the listeners
+ * move with it. A keyboard connected after access was granted works without
+ * the caller having to rebuild anything.
+ *
  * Use this when you need more detail than {@link createMIDIInput} provides.
  */
-declare function createMIDIMessage(midiAccess: MIDIAccess | null, onMIDIMessage: (event: MIDIMessageEvent) => void): MIDIMessageInstance;
+export declare function createMIDIMessage(midiAccess: MIDIAccess | null, onMIDIMessage: (event: MIDIMessageEvent) => void): MIDIMessageInstance;
 //#endregion
-//#region src/midi/input.d.ts
-type MIDIInputHandlers = {
-  onNoteOnEvent?: (note: number, velocity: number) => void;
-  onNoteOffEvent?: (note: number) => void;
-  onPitchBendEvent?: (msb: number, lsb: number) => void;
+//#region src/piano/layout.d.ts
+type NoteRange = {
+  first: number;
+  last: number;
 };
-type MIDIInputInstance = MIDIMessageInstance;
 /**
- * Handle note on/off and pitch bend events. To be used with {@link createMIDIAccess}.
- * Internally uses {@link createMIDIMessage}.
+ * `[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.
  */
-declare function createMIDIInput(midiAccess: MIDIAccess | null, {
-  onNoteOnEvent,
-  onNoteOffEvent,
-  onPitchBendEvent
-}: MIDIInputHandlers): MIDIInputInstance;
+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;
 //#endregion
-//#region src/piano/input.d.ts
+//#region src/piano/index.d.ts
 /**
  * What asked for a note to sound.
  *
@@ -230,14 +538,17 @@ interface PianoInputInstance {
  *
  * Tracks every pointer at once, so a chord can be played with several fingers.
  */
-declare function createPianoInput(element: Element, options: PianoInputOptions): PianoInputInstance;
+export declare function createPianoInput(element: Element, options: PianoInputOptions): PianoInputInstance;
 //#endregion
 //#region src/pointer/drag.d.ts
 type DragState = {
-  /** Total movement from the drag start, in screen coordinates. */x: number;
-  y: number; /** Movement since the previous event, in screen coordinates. */
+  /** Total movement from the drag start, in screen coordinates. */
+  x: number;
+  y: number;
+  /** Movement since the previous event, in screen coordinates. */
   deltaX: number;
-  deltaY: number; /** Pointer position in viewport coordinates. */
+  deltaY: number;
+  /** Pointer position in viewport coordinates. */
   clientX: number;
   clientY: number;
   /**
@@ -267,6 +578,40 @@ type DragOptions = {
    * restored once the last one is up.
    */
   cursor?: string;
+  /**
+   * Decide whether a pointerdown starts a drag at all.
+   *
+   * Checked before anything else — **before the pointer is captured** — so
+   * declining here leaves the whole gesture to whatever else is listening.
+   * Deciding later would be too late: the capture has already been taken from
+   * the element that was going to handle it.
+   *
+   * The use for it is a drag on a container that also holds draggable things
+   * of its own, such as a rubber-band selection that must not begin on top of
+   * one of the objects it would select.
+   */
+  shouldStart?: (event: PointerEvent) => boolean;
+  /**
+   * Hide the pointer and read its movement directly, instead of following it
+   * around the screen.
+   *
+   * A relative drag — a knob, a stepper — does not care where the pointer is,
+   * only how far it moved, and letting it wander has two costs: the cursor
+   * ends up far from what it is holding, and **the drag stops at the edge of
+   * the screen**, where the operating system pins the pointer and the
+   * coordinates stop changing. A fine drag reaches that edge quickly.
+   *
+   * **Not for a drag whose value is the position pointed at** — anything on
+   * `elementMapping`. `clientX` / `clientY` freeze while the pointer is
+   * locked, so there is no position left to read.
+   *
+   * The request needs a user gesture, which a pointerdown is, but it can still
+   * be refused; the drag then carries on as an ordinary one. Read on
+   * pointerdown, so `update()` reaches the next drag rather than the current.
+   *
+   * @default false
+   */
+  pointerLock?: boolean;
   /**
    * Track every pointer that goes down on the element, rather than only the
    * first. Each one gets its own `onDragStart` / `onDrag` / `onDragEnd` and
@@ -280,6 +625,10 @@ type DragOptions = {
   multiPointer?: boolean;
   onDragStart?: (state: DragState) => void;
   onDrag?: (state: DragState) => void;
+  /**
+   * Called exactly once for every drag that starts, whether tracking ends by
+   * pointer release, cancellation, capture or lock loss, or destruction.
+   */
   onDragEnd?: (state: DragState) => void;
 };
 interface DragInstance {
@@ -291,6 +640,7 @@ interface DragInstance {
    * here.
    */
   update: (options: DragOptions) => void;
+  /** End any active drags before removing the instance. */
   destroy: () => void;
 }
 /**
@@ -304,7 +654,7 @@ interface DragInstance {
  *
  * One pointer at a time by default; see {@link DragOptions.multiPointer}.
  */
-declare function createDrag(element: Element, options?: DragOptions): DragInstance;
+export declare function createDrag(element: Element, options?: DragOptions): DragInstance;
 //#endregion
 //#region src/xy.d.ts
 /**
@@ -330,9 +680,9 @@ type XYInput<T> = [T] extends [readonly unknown[]] ? readonly [x: T, y: T] : T |
  * 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.
  */
-declare function toXY<T>(value: T | readonly [x: T, y: T]): XY<T>;
+export declare function toXY<T>(value: T | readonly [x: T, y: T]): XY<T>;
 //#endregion
-//#region src/pointer/dragValue.d.ts
+//#region src/pointer/drag-value.d.ts
 /**
  * How the 0-1 travel of one axis maps onto a value.
  *
@@ -377,20 +727,41 @@ interface DragValueMapping {
  * The element is read on every event, so it may be mounted after the drag is
  * set up and may change size while a drag is in progress.
  */
-declare function elementMapping(getElement: () => Element | null | undefined): DragValueMapping;
+export declare function elementMapping(getElement: () => Element | null | undefined, { sensitivity }?: {
+  /**
+   * How much the movement counts, read on every move. `1` is the pointer
+   * position itself; `0.1` makes the same movement cover a tenth of the
+   * travel, which is what a fine-adjustment modifier wants.
+   *
+   * Anything but `1` turns the mapping relative: the value stops being the
+   * position pointed at and starts being where it stood when the sensitivity
+   * changed, plus the movement since. **The pointer and the value stay apart
+   * for the rest of the drag** rather than snapping back together when the
+   * key is released, since snapping would move the value nobody asked to
+   * move.
+   */
+  sensitivity?: (state: DragState) => number;
+}): DragValueMapping;
 /**
  * Move the value away from where it stood when the drag started, by the
  * distance dragged. The pointer position itself carries no meaning, so the
  * value can be adjusted from anywhere on the screen.
  */
-declare function relativeMapping({
-  pixelRange
-}?: {
+export declare function relativeMapping({ pixelRange, sensitivity }?: {
   /**
    * Pixels of movement that span the whole range.
    * @default 100
    */
   pixelRange?: XYInput<number>;
+  /**
+   * How much the movement counts, read on every move. `1` is `pixelRange` as
+   * given; `0.1` makes the same movement cover a tenth of the range, which is
+   * what a fine-adjustment modifier wants.
+   *
+   * Changing it mid-drag does not disturb the value: the travel so far is
+   * folded into the origin and measuring starts again from there.
+   */
+  sensitivity?: (state: DragState) => number;
 }): DragValueMapping;
 interface DragValueOptions {
   /** Scaling of each axis; a single value applies to both. */
@@ -417,6 +788,16 @@ interface DragValueOptions {
   threshold?: number;
   /** @see DragOptions.cursor */
   cursor?: string;
+  /**
+   * @see DragOptions.pointerLock
+   *
+   * Only for a mapping that moves the value relative to where it stood, such
+   * as {@link relativeMapping}. {@link elementMapping} reads the pointer
+   * position, and there is none while it is locked.
+   */
+  pointerLock?: boolean;
+  /** @see DragOptions.shouldStart */
+  shouldStart?: (event: PointerEvent) => boolean;
   onChange?: (value: XY<number>, state: DragState) => void;
   onDragStart?: (value: XY<number>, state: DragState) => void;
   onDragEnd?: (value: XY<number>, state: DragState) => void;
@@ -438,10 +819,12 @@ interface DragValueInstance {
  * mapping decides where the pointer sits on the 0-1 travel of each axis, and
  * the axis options turn that into a value.
  */
-declare function createDragValue(element: Element, options: DragValueOptions): DragValueInstance;
+export declare function createDragValue(element: Element, options: DragValueOptions): DragValueInstance;
 //#endregion
 //#region src/pointer/wheel.d.ts
 interface WheelOptions {
+  /** Replace the callback through {@link WheelInstance.update}. */
+  onWheel?: (event: WheelEvent) => void;
   /**
    * Only report events while the focus is inside the element.
    *
@@ -468,7 +851,67 @@ interface WheelInstance {
  * The listener is registered with `passive: false` so that the handler can call
  * `preventDefault()` to stop the page from scrolling.
  */
-declare function createWheel(element: Element, onWheel: (event: WheelEvent) => void, options?: WheelOptions): WheelInstance;
+export declare function createWheel(element: Element, onWheel: (event: WheelEvent) => void, options?: WheelOptions): WheelInstance;
+//#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
-export { type AnimationCanvasInstance, type AnimationCanvasOptions, type AnimationFrame, type AxisOptions, type CanvasDrawFunction, type CanvasInitFunction, type DragInstance, type DragOptions, type DragState, type DragValueInstance, type DragValueMapping, type DragValueOptions, type DrawingContext, type DrawingState, type DrawingStateValue, type MIDIAccessError, type MIDIAccessInstance, type MIDIAccessState, type MIDIInputHandlers, type MIDIInputInstance, type MIDIMessageInstance, type MappingContext, NOT_SUPPORTED, type NoteSource, PERMISSION_DENIED, type PianoInputInstance, type PianoInputOptions, type WheelInstance, type WheelOptions, type XY, type XYInput, createAnimationCanvas, createDrag, createDragValue, createMIDIAccess, createMIDIInput, createMIDIMessage, createPianoInput, createWheel, drawingState, elementMapping, isDrawingState, relativeMapping, toXY };
+export type { AcceptCandidate, AnimationCanvasInstance, AnimationCanvasOptions, AnimationFrame, AxisOptions, CanvasDrawFunction, CanvasInitFunction, DragInstance, DragOptions, DragState, DragValueInstance, DragValueMapping, DragValueOptions, DrawingContext, DrawingState, DrawingStateValue, DropZoneInstance, DropZoneOptions, DropZoneState, InputEventOption, MIDIAccessError, MIDIAccessInstance, MIDIAccessOptions, MIDIAccessState, MIDIInputHandlers, MIDIInputInstance, MIDIMessageInstance, MappingContext, Modifier, ModifierMap, ModifierState, ModifierValue, NoteRange, NoteSource, PianoInputInstance, PianoInputOptions, PianoLayout, SelectionBoxBeginOptions, SelectionBoxInstance, SelectionBoxOptions, SelectionBoxRect, WheelInstance, WheelOptions, XY, XYInput };
 //# sourceMappingURL=index.d.cts.map