@tremolo-ui/dom 0.4.0 → 0.6.0

package/dist/index.d.cts

@@ -1,17 +1,150 @@
+import { PianoLayout, ValueRange } from "@tremolo-ui/functions";
+//#region src/canvas/animation.d.ts
+/** What the canvas looked like when a frame was drawn. */
+interface AnimationFrame {
+  /** Width of the canvas in CSS pixels. */
+  width: number;
+  /** Height of the canvas in CSS pixels. */
+  height: number;
+  /** Frames drawn so far, starting at 0. */
+  count: number;
+  /** Milliseconds since the previous frame. */
+  deltaTime: number;
+  /** Milliseconds since the instance was created. */
+  elapsedTime: number;
+  /** Frames per second implied by `deltaTime`, or 0 when no time elapsed. */
+  fps: number;
+}
+type CanvasDrawFunction = (context: CanvasRenderingContext2D, frame: AnimationFrame) => void;
+type CanvasInitFunction = (context: CanvasRenderingContext2D, size: {
+  width: number;
+  height: number;
+}) => void;
+interface AnimationCanvasOptions {
+  /** Called for every frame. */
+  draw: CanvasDrawFunction;
+  /** Called once, after the first size is known and before the first frame. */
+  init?: CanvasInitFunction;
+  /**
+   * Keep drawing on every animation frame. When off, a frame is drawn only on
+   * a resize or an explicit {@link AnimationCanvasInstance.redraw}.
+   *
+   * @default true
+   */
+  animate?: boolean;
+  /**
+   * Size in CSS pixels. Ignored when `resizable` is on.
+   *
+   * @default { width: 100, height: 100 }
+   */
+  size?: {
+    width: number;
+    height: number;
+  };
+  /**
+   * Follow the size of the canvas's parent element instead of `size`.
+   *
+   * Fixed for the lifetime of the instance: it decides whether a
+   * `ResizeObserver` is attached.
+   *
+   * @default false
+   */
+  resizable?: boolean;
+  /**
+   * Carry the drawing across a resize, so that the canvas does not blank for a
+   * frame while the new size is drawn.
+   *
+   * @default true
+   */
+  reduceFlickering?: boolean;
+  /**
+   * Passed to `getContext('2d', …)`. Read once when the context is created, so
+   * it is fixed for the lifetime of the instance.
+   *
+   * @see https://developer.mozilla.org/docs/Web/API/HTMLCanvasElement/getContext#contextattributes
+   */
+  contextAttributes?: CanvasRenderingContext2DSettings;
+}
+interface AnimationCanvasInstance {
+  /**
+   * Replace the given options. Lets a wrapper feed a fresh `draw` in on every
+   * render without restarting the animation, so the frame count and the
+   * elapsed time keep running.
+   *
+   * `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.
+   */
+  update: (options: Partial<AnimationCanvasOptions>) => void;
+  /** Draw one frame now, whether or not `animate` is on. */
+  redraw: () => void;
+  destroy: () => void;
+}
+/**
+ * Drive a canvas from `requestAnimationFrame`, keeping its backing store in
+ * step with the device pixel ratio and, optionally, with the size of its
+ * parent.
+ *
+ * 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;
+//#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
+ */
+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;
+};
+declare function isDrawingState(value: unknown): value is DrawingState;
+//#endregion
 //#region src/midi/access.d.ts
 /** @private */
 declare const PERMISSION_DENIED = "PERMISSION_DENIED";
 /** @private */
 declare const NOT_SUPPORTED = "NOT_SUPPORTED";
 /** @private */
-type MIDIAccessError = typeof PERMISSION_DENIED | typeof NOT_SUPPORTED;
+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;
@@ -27,64 +160,239 @@ interface MIDIAccessInstance {
  */
 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.
+ */
+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.
+ */
+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;
 //#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;
-};
-type MIDIInputInstance = MIDIMessageInstance;
+//#region src/piano/index.d.ts
 /**
- * Handle note on/off and pitch bend events. To be used with {@link createMIDIAccess}.
- * Internally uses {@link createMIDIMessage}.
+ * What asked for a note to sound.
+ *
+ * A note stops only once everything that asked for it has let go, so two
+ * fingers on one key, or a key held by both the mouse and a MIDI keyboard,
+ * behave the way they look.
+ *
+ * Pointers use `pointer:<pointerId>`; everything else names its own source.
  */
-declare function createMIDIInput(midiAccess: MIDIAccess | null, {
-  onNoteOnEvent,
-  onNoteOffEvent,
-  onPitchBendEvent
-}: MIDIInputHandlers): MIDIInputInstance;
+type NoteSource = string;
+interface PianoInputOptions {
+  /** Geometry of the drawn keyboard, used to find the note under a pointer. */
+  layout: PianoLayout;
+  /**
+   * Let a pointer slide from one key to the next while it is down. With it off,
+   * the key that was pressed keeps sounding until the pointer is released.
+   *
+   * @default true
+   */
+  glissando?: boolean;
+  /**
+   * Highest note that can sound. Above it a note is refused, whichever source
+   * asks for it.
+   *
+   * @default 127
+   */
+  midiMax?: number;
+  /** Called when a note starts sounding, not for each source that asks. */
+  onPlayNote?: (note: number, velocity?: number) => void;
+  /** Called once the last source holding a note has let go. */
+  onStopNote?: (note: number) => void;
+  /** Called whenever {@link PianoInputInstance.activeNotes} would change. */
+  onActiveNotesChange?: (notes: number[]) => void;
+}
+interface PianoInputInstance {
+  /**
+   * Replace the given options. Lets a wrapper feed a fresh layout in without
+   * tearing down the listeners, which would abort a drag in progress.
+   */
+  update: (options: Partial<PianoInputOptions>) => void;
+  /**
+   * Start a note from something other than a pointer: a keyboard shortcut, a
+   * MIDI message, an imperative call.
+   */
+  noteOn: (note: number, options?: {
+    source?: NoteSource;
+    velocity?: number;
+  }) => void;
+  /** Release a note held by `source`. */
+  noteOff: (note: number, options?: {
+    source?: NoteSource;
+  }) => void;
+  /** The notes currently sounding, ascending. */
+  activeNotes: () => number[];
+  destroy: () => void;
+}
+/**
+ * Drive a piano keyboard with pointers, and own what is sounding.
+ *
+ * Every way of playing a note goes through the one instance — pointers here,
+ * keyboard shortcuts and MIDI through {@link PianoInputInstance.noteOn} — so
+ * there is a single answer to what is currently held, and drawing the keys is
+ * left entirely to the wrapper.
+ *
+ * Tracks every pointer at once, so a chord can be played with several fingers.
+ */
+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;
+  /**
+   * Which pointer this is. Always the same value for one drag; with
+   * {@link DragOptions.multiPointer} it tells concurrent drags apart.
+   */
+  pointerId: number;
   event: PointerEvent;
 };
 type DragOptions = {
   /**
-   * Minimum movement in pixels before `onDrag` fires.
+   * Minimum movement in pixels before `onDrag` fires. Movement below it is
+   * carried over to the next event rather than discarded, so a slow drag still
+   * reports once it adds up.
+   *
    * Prevents `onDrag` from firing on, for example, a double click.
-   * Values below 1 are clamped to 1.
    *
-   * @default 1
+   * @default 0
    */
   threshold?: number;
   /**
    * CSS cursor to show while dragging. Applied to the element itself: pointer
    * capture keeps it in effect even once the pointer leaves the element, so
    * there is no need to touch the document.
+   *
+   * With {@link DragOptions.multiPointer} it is set for the first pointer and
+   * 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
+   * carries its own totals; {@link DragState.pointerId} says which is which.
+   *
+   * Fixed for the lifetime of the instance: switching part way through a drag
+   * has no meaning, so `update()` ignores it.
+   *
+   * @default false
+   */
+  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 {
+  /**
+   * Replace the given options. Lets a wrapper feed fresh handlers in without
+   * tearing down the listeners, which would abort a drag in progress.
+   *
+   * `multiPointer` is fixed for the lifetime of the instance and is ignored
+   * here.
+   */
+  update: (options: DragOptions) => void;
+  /** End any active drags before removing the instance. */
   destroy: () => void;
 }
 /**
@@ -95,17 +403,198 @@ interface DragInstance {
  * element gets `touch-action: none` so that touch dragging does not scroll the
  * page, plus `user-select: none` so that a long press does not start a text
  * selection instead.
+ *
+ * One pointer at a time by default; see {@link DragOptions.multiPointer}.
+ */
+declare function createDrag(element: Element, options?: DragOptions): DragInstance;
+//#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.
+ */
+declare function toXY<T>(value: T | readonly [x: T, y: T]): XY<T>;
+//#endregion
+//#region src/pointer/drag-value.d.ts
+/**
+ * How the 0-1 travel of one axis maps onto a value.
+ *
+ * Extends `ValueRange` so that a drag and an `applyDelta` nudge from a wheel
+ * or an arrow key share one description of the scaling.
+ */
+interface AxisOptions extends ValueRange {
+  /**
+   * Flip the axis so that its far end is `min`.
+   *
+   * Positions follow the screen: x grows to the right, y downwards. A vertical
+   * slider whose maximum is at the top therefore reverses its y axis.
+   *
+   * @default false
+   */
+  reverse?: boolean;
+}
+/** Where the value of each axis currently sits, as a position (see {@link DragValueMapping}). */
+interface MappingContext {
+  position: () => XY<number>;
+}
+/**
+ * Turns pointer movement into a position on each axis: 0 is the `min` end of
+ * the travel and 1 the `max` end, before `reverse` and the scaling of
+ * {@link AxisOptions} are applied.
+ *
+ * A mapping holds the state of the drag in progress, so an instance belongs to
+ * a single {@link createDragValue} instance.
+ */
+interface DragValueMapping {
+  /**
+   * @returns the position, or null when it cannot be determined and the event
+   * should be ignored.
+   */
+  start: (state: DragState, context: MappingContext) => XY<number> | null;
+  move: (state: DragState, context: MappingContext) => XY<number> | null;
+}
+/**
+ * Map the pointer onto the bounding rect of an element: the value *is* the
+ * position pointed at, so the middle of the element is 0.5.
+ *
+ * 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, { 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, 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. */
+  axis: XYInput<AxisOptions>;
+  /** How pointer movement becomes a position. */
+  mapping: DragValueMapping;
+  /**
+   * The current value of each axis. Read when a drag starts, by mappings that
+   * move the value relative to it, such as {@link relativeMapping}.
+   */
+  getValue?: () => XY<number>;
+  /**
+   * Report the value on pointer down, before any movement.
+   *
+   * Enable it where the pointer position *is* the value, so that a plain click
+   * jumps to it. Leave it off where the element being dragged is an object in
+   * its own right, so that grabbing its edge does not shift it under the
+   * pointer.
+   *
+   * @default false
+   */
+  updateOnPointerDown?: boolean;
+  /** @see DragOptions.threshold */
+  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;
+}
+interface DragValueInstance {
+  /**
+   * Replace the given options. Lets a wrapper feed fresh values in without
+   * tearing down the listeners, which would abort a drag in progress.
+   *
+   * `mapping` is fixed for the lifetime of the instance and is ignored here.
+   */
+  update: (options: Partial<DragValueOptions>) => void;
+  destroy: () => void;
+}
+/**
+ * Drive a value with a pointer drag.
+ *
+ * Combines {@link createDrag} with the scaling of `@tremolo-ui/functions`: the
+ * 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 createDrag(element: Element, {
-  threshold: _threshold,
-  cursor,
-  onDragStart,
-  onDrag,
-  onDragEnd
-}?: DragOptions): DragInstance;
+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.
+   *
+   * A control that reacts to the wheel on hover alone takes the scroll away
+   * from the page, so passing over one in a long form silently changes its
+   * value. Requiring focus makes that an explicit act.
+   *
+   * The check is `contains`, not an identity test: the element that actually
+   * takes focus is usually a descendant, such as a thumb or an `<input>`, and
+   * a caller may have replaced it with markup of their own.
+   *
+   * @default false
+   */
+  requireFocus?: boolean;
+}
 interface WheelInstance {
+  /** Replace the given options, keeping the listener in place. */
+  update: (options: WheelOptions) => void;
   destroy: () => void;
 }
 /**
@@ -114,7 +603,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): WheelInstance;
+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. */
+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.
+ */
+declare function createSelectionBox<Id>(options: SelectionBoxOptions<Id>): SelectionBoxInstance<Id>;
 //#endregion
-export { type DragInstance, type DragOptions, type DragState, type MIDIAccessError, type MIDIAccessInstance, type MIDIAccessState, type MIDIInputHandlers, type MIDIInputInstance, type MIDIMessageInstance, NOT_SUPPORTED, PERMISSION_DENIED, type WheelInstance, createDrag, createMIDIAccess, createMIDIInput, createMIDIMessage, createWheel };
+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 MIDIAccessOptions, type MIDIAccessState, type MIDIInputHandlers, type MIDIInputInstance, type MIDIMessageInstance, type MappingContext, NOT_SUPPORTED, type NoteSource, PERMISSION_DENIED, PITCH_BEND_CENTER, type PianoInputInstance, type PianoInputOptions, type SelectionBoxBeginOptions, type SelectionBoxInstance, type SelectionBoxOptions, type SelectionBoxRect, UNAVAILABLE, type WheelInstance, type WheelOptions, type XY, type XYInput, createAnimationCanvas, createDrag, createDragValue, createMIDIAccess, createMIDIInput, createMIDIMessage, createPianoInput, createSelectionBox, createWheel, drawingState, elementMapping, isDrawingState, relativeMapping, selectionBoxCovers, toXY };
 //# sourceMappingURL=index.d.cts.map