@tremolo-ui/dom 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { ValueRange } from "@tremolo-ui/functions";
+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.js";
+import { Scale, ValueRange } from "@tremolo-ui/functions";
 //#region src/canvas/animation.d.ts
 /** What the canvas looked like when a frame was drawn. */
 interface AnimationFrame {
@@ -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,59 +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;
-//#endregion
 //#region src/file/drop-zone.d.ts
 /** What is in the air over the element. */
 interface DropZoneState {
@@ -184,7 +140,8 @@ interface DropZoneOptions {
   onDrop?: (files: File[], event: DragEvent) => void;
   /**
    * Called with the dropped files that do not match `accept`, so that the
-   * reason can be shown.
+   * reason can be shown. It comes after `onDrop` for the same drop, so a list
+   * of rejected files can be cleared in `onDrop` and filled here.
    */
   onReject?: (files: File[], event: DragEvent) => void;
   /** Called whenever {@link DropZoneInstance.state} would change. */
@@ -212,98 +169,134 @@ interface DropZoneInstance {
  */
 export declare function createDropZone(element: Element, options?: DropZoneOptions): DropZoneInstance;
 //#endregion
-//#region src/input/modifiers.d.ts
+//#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;
+}
+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;
+  /**
+   * 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.
+   */
+  pulse: (source: ChangeSource) => void;
+  /**
+   * A gesture that starts and ends around a single change, such as a reset:
+   * `change` runs between the two.
+   */
+  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;
+}
 /**
- * Options for setting the amount of keyboard and mouse wheel changes.
+ * 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.
  */
-type InputEventOption = readonly ['normalized' | 'raw', number];
+export declare function createChangeGesture(options?: ChangeGestureOptions): ChangeGestureInstance;
+//#endregion
+//#region src/input/defaults.d.ts
 /**
- * A modifier key that can carry an amount of its own.
+ * The keyboard amount used by Knob, NumberInput, Slider, and XYPad by default:
+ * 1 per press in the units of the value, and 0.1 with shift held. That is one
+ * `step` only while `step` is 1; a coarser `step` rounds 1 straight back, which
+ * `checkSteps` warns about.
  *
- * `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.
+ * A modifier entry is not snapped to `step`, which is what lets the finer
+ * amount move at all — see `applyDelta`.
  */
-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>>;
+export declare const DEFAULT_KEYBOARD_OPTIONS: ModifierValue<InputEventOption>;
 /**
- * A single setting, or one per modifier key.
+ * The wheel amount used by Knob, NumberInput, Slider, and XYPad by default.
  *
- * @example
- * ['raw', 1]
- * { default: ['raw', 1], shift: ['raw', 0.1] }
+ * Browsers turn shift+wheel into horizontal scrolling, which empties `deltaY`
+ * and fills `deltaX`, so no modifier is bound here.
  */
-type ModifierValue<T extends ModifierSetting> = T | ModifierMap<T>;
+export declare const DEFAULT_WHEEL_OPTIONS: ModifierValue<InputEventOption>;
 /**
- * Pick the setting that applies, given the modifier keys being held.
- *
- * @example
- * selectModifier({ default: 1, shift: 0.1 }, event)
+ * The drag sensitivity used by value controls by default. Shift makes the
+ * same movement cover a tenth of the range, matching the arrow keys.
  */
-export declare function selectModifier<T extends ModifierSetting>(options: ModifierValue<T>, modifiers?: ModifierState): {
-  value: T;
-  modifier: Modifier | null;
-};
+export declare const DEFAULT_DRAG_SENSITIVITY: ModifierValue<number>;
+//#endregion
+//#region src/knob/geometry.d.ts
+/**
+ * Width and height of the viewBox a knob is drawn in. The arcs and the thumb
+ * are laid out in these units, and the SVG scales them to the knob's size.
+ */
+export declare const KNOB_VIEWBOX_SIZE = 100;
+interface KnobAngleOptions {
+  value: number;
+  min: number;
+  max: number;
+  scale: Scale;
+  /** Where the active arc starts from, so that it can grow from the middle. */
+  startValue: number;
+  /** How far the knob turns from `min` to `max`, in degrees. */
+  angleRange: number;
+}
 /**
- * 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] }
+ * The angles a knob is drawn with, in degrees clockwise from the top.
+ *
+ * The travel is centred on the top, so `angleRange` of 270 runs from -135 to
+ * 135. Derived from the value alone, so a wrapper can call it while rendering.
+ */
+interface KnobAngles {
+  /** The value, normalized to 0..1 along the scale. */
+  p: number;
+  /** Where the travel starts. */
+  r1: number;
+  /** Where the active arc starts: the lower of the value and `startValue`. */
+  r2: number;
+  /** Where the active arc ends: the higher of the value and `startValue`. */
+  r3: number;
+  /** Where the travel ends. */
+  r4: number;
+}
+export declare function knobAngles({ value, min, max, scale, startValue, angleRange }: KnobAngleOptions): KnobAngles;
+/**
+ * The radius that keeps a stroke of `strokeWidth` inside the viewBox: half of
+ * the stroke falls outside the path it is drawn along.
  */
-export declare function mapModifier<T extends ModifierSetting, U extends ModifierSetting>(options: ModifierValue<T>, fn: (value: T) => U): ModifierValue<U>;
+export declare function knobArcRadius(strokeWidth: number | string | undefined): number;
+/** Build an SVG path for an arc, splitting full turns into drawable segments. */
+export declare function knobArcPath(startAngle: number, endAngle: number, radius: number): string;
 //#endregion
-//#region src/input/apply-delta.d.ts
+//#region src/midi/access.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 })
+ * Why MIDI access could not be had.
  *
- * @example
- * // Shift+ArrowDown, where `keyboard` is { default: …, shift: ['raw', 0.1] }
- * applyDelta(value, -1, keyboard, range, event)
+ * - `'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
  */
-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 */
-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;
+type MIDIAccessError = 'NOT_SUPPORTED' | 'PERMISSION_DENIED' | 'UNAVAILABLE';
 type MIDIAccessOptions = {
   /**
    * Ask for system exclusive messages as well.
@@ -345,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.
@@ -360,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.
@@ -407,69 +394,37 @@ interface MIDIMessageInstance {
  */
 export declare function createMIDIMessage(midiAccess: MIDIAccess | null, onMIDIMessage: (event: MIDIMessageEvent) => void): MIDIMessageInstance;
 //#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;
+//#region src/piano/shortcuts.d.ts
+type KeyboardShortcuts = {
   /**
-   * Width of a black key, as a fraction of {@link PianoLayout.whiteKeyWidth}.
+   * Keys laid out from `noteRange.first`, one entry per semitone.
    *
-   * @default 0.65
+   * An empty string leaves that note without a shortcut: `KeyboardEvent.key` is
+   * never empty, so the entry can never match. Use it to skip the black keys
+   * (see {@link SHORTCUTS.HOME_ROW_NATURAL}) and keep the remaining entries
+   * lined up with the notes.
    */
-  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;
+  keys: string[];
+};
 /**
- * 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`.
+ * Ready-made keyboard layouts. Both assume `noteRange.first` is a C.
  */
-export declare function notePosition(note: number, layout: PianoLayout): number;
+export declare const SHORTCUTS: {
+  /** Every semitone from C, over the two rows of a QWERTY keyboard. */
+  HOME_ROW: {
+    keys: string[];
+  };
+  /** The white keys only, on the home row. Black keys have no shortcut. */
+  HOME_ROW_NATURAL: {
+    keys: string[];
+  };
+};
 /**
- * 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
+ * Where keyboard shortcuts listen. `root` handles keys only while the piano
+ * or one of its descendants has focus; `window` handles them anywhere on the
+ * page except in editable elements.
  */
-export declare function noteAt(x: number, y: number, height: number, layout: PianoLayout): number | null;
+type KeyboardShortcutsScope = 'root' | 'window';
 //#endregion
 //#region src/piano/index.d.ts
 /**
@@ -499,6 +454,24 @@ interface PianoInputOptions {
    * @default 127
    */
   midiMax?: number;
+  /**
+   * Play notes from the computer keyboard: `keys[i]` plays
+   * `layout.noteRange.first + i`. `SHORTCUTS` has ready-made layouts.
+   *
+   * A held key keeps its note until it is released, the focus leaves (with
+   * `root`), or the window loses focus. Changing the keys, the scope or the
+   * note range releases every note a key is holding, since the key would
+   * mean something else on release.
+   */
+  keyboardShortcuts?: KeyboardShortcuts;
+  /**
+   * Where keyboard shortcuts listen: on the element (`root`), which has to
+   * be focusable, or anywhere on the page (`window`). Keys typed into an
+   * editable element are ignored either way.
+   *
+   * @default 'root'
+   */
+  keyboardShortcutsScope?: KeyboardShortcutsScope;
   /** 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. */
@@ -513,8 +486,8 @@ interface PianoInputInstance {
    */
   update: (options: Partial<PianoInputOptions>) => void;
   /**
-   * Start a note from something other than a pointer: a keyboard shortcut, a
-   * MIDI message, an imperative call.
+   * Start a note from something other than a pointer or a shortcut: a MIDI
+   * message, an imperative call.
    */
   noteOn: (note: number, options?: {
     source?: NoteSource;
@@ -656,32 +629,6 @@ interface DragInstance {
  */
 export 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.
- */
-export 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.
@@ -821,10 +768,58 @@ interface DragValueInstance {
  */
 export declare function createDragValue(element: Element, options: DragValueOptions): DragValueInstance;
 //#endregion
+//#region src/pointer/long-press.d.ts
+interface LongPressOptions {
+  /** Called once on the press, then again every `interval` after `delay`. */
+  onPress: () => void;
+  /**
+   * How long the press has to be held before it starts repeating, in
+   * milliseconds.
+   *
+   * @default 500
+   */
+  delay?: number;
+  /**
+   * How often it repeats once it has started, in milliseconds.
+   *
+   * @default 40
+   */
+  interval?: number;
+}
+interface LongPressInstance {
+  /**
+   * Start a press, from a `pointerdown` or with no event at all. Only the
+   * primary button starts one, and a press already in progress is left alone.
+   */
+  start: (event?: Pick<PointerEvent, 'button' | 'pointerId'>) => void;
+  /** End the press, as releasing the pointer would. */
+  stop: () => void;
+  /** Replace the given options. The press in progress picks them up. */
+  update: (options: Partial<LongPressOptions>) => void;
+  /** Whether a press is in progress. */
+  pressed: () => boolean;
+  destroy: () => void;
+}
+/**
+ * Repeat an action while a pointer is held down: once on the press, then
+ * again every `interval` after `delay` — the way a stepper button or a
+ * key held on a keyboard behaves.
+ *
+ * The release is listened for on the window, not on the element: the
+ * pointer may be let go anywhere. Only the pointer that started the press
+ * ends it, so a second finger lifting elsewhere does not. The window losing
+ * focus ends it too, since the release would never arrive.
+ */
+export declare function createLongPress(options: LongPressOptions): LongPressInstance;
+//#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.
    *
@@ -842,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;
 }
 /**
@@ -851,67 +846,18 @@ 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/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;
+//#region src/position.d.ts
 /**
- * Selecting by dragging a box over a set of items.
+ * Where a value sits along a track, as a whole percentage from its start.
  *
- * 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.
+ * Normalized along the scale, so a thumb, the fill behind it and the marks
+ * all sit on the curve the drag follows. `reversed` measures from the other
+ * end — for a track that grows upwards or leftwards on screen, since CSS
+ * places things from the top and the left.
  */
-export declare function createSelectionBox<Id>(options: SelectionBoxOptions<Id>): SelectionBoxInstance<Id>;
+export declare function valuePercent(value: number, { min, max, scale }: Pick<ValueRange, 'min' | 'max' | 'scale'>, reversed?: boolean): number;
 //#endregion
-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 };
+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.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/canvas/animation.ts","../src/canvas/context.ts","../src/file/accept.ts","../src/file/drop-zone.ts","../src/input/modifiers.ts","../src/input/apply-delta.ts","../src/midi/access.ts","../src/midi/input.ts","../src/midi/message.ts","../src/piano/layout.ts","../src/piano/index.ts","../src/pointer/drag.ts","../src/xy.ts","../src/pointer/drag-value.ts","../src/pointer/wheel.ts","../src/selection/box.ts"],"mappings":";;;UAQiB;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA;;EAEA;;KAGU,sBACV,SAAS,0BACT,OAAO;KAGG,sBACV,SAAS,0BACT;EAAQ;EAAe;;UAGR;;EAEf,MAAM;;EAGN,OAAO;;;;;;;EAQP;;;;;;EAOA;IAAS;IAAe;;;;;;;;;;EAUxB;;;;;;;EAQA;;;;;;;EAQA,oBAAoB;;UAGL;;;;;;;;;;;EAWf,SAAS,SAAS,QAAQ;;EAG1B;EAEA;;;;;;;;;;wBAWc,sBACd,QAAQ,mBACR,SAAS,yBACR;;;;;;;;;;;qBCxGU;KA6BD,uBAAuB;KACvB,oBAAoB,yBAAyB;KAC7C,iBAAiB,KAAK,0BAA0B;;EAE1D;;EAEA,WAAW;;wBAGG,eAAe,iBAAiB,SAAS;;;;;;;;;;UCvCxC;;EAEf;;EAEA;;;;;;;;;;;;;;;;;;;wBAoBc,cACd,WAAW,iBACX;;;;UC9Be;;EAEf;;;;;;;;;EASA;;UAGe;;;;;;EAMf;;;;;;;EAOA;;;;;;;EAOA;;EAGA,UAAU,OAAO,QAAQ,OAAO;;;;;EAKhC,YAAY,OAAO,QAAQ,OAAO;;EAElC,iBAAiB,OAAO;;UAGT;;WAEN,OAAO;;EAEhB,SAAS,SAAS;EAClB;;;;;;;;;;;;;;;wBAgBc,eACd,SAAS,SACT,UAAS,kBACR;;;;;;KCvES;;;;;;;;KASA;;UAGK;EACf;EACA;EACA;EACA;;;KAIG,2BAA2B;KAEpB,YAAY,UAAU;EAAqB,SAAS;IAAM,QACpE,OAAO,UAAU;;;;;;;;KAUP,cAAc,UAAU,mBAAmB,IAAI,YAAY;;;;;;;wBAqCvD,eAAe,UAAU,iBACvC,SAAS,cAAc,IACvB,YAAY;EACT,OAAO;EAAG,UAAU;;;;;;;;;;;;;;;;wBAiCT,YACd,UAAU,iBACV,UAAU,iBACV,SAAS,cAAc,IAAI,KAAK,OAAO,MAAM,IAAI,cAAc;;;;;;;;;;;;;;;;;;;;;;;;wBC5EjD,WACd,eACA,mBACA,SAAS,cAAc,qBACrB,KAAK,KAAK,MAAM,SAAuB,YACzC,YAAY;;;;qBCxCD;;qBAEA;;qBAEA;;KAGD,yBACD,2BACA,uBACA;KAEC;;;;;;;;;EASV;;KAGU;WACD,YAAY;WACZ,OAAO;;;;;;;WAOP,iBAAiB;;UASX;;EAEf,UAAU,UAAU;EACpB,gBAAgB;;EAEhB,sBAAsB;;EAEtB,YAAY;EACZ;;;;;;;;wBA+Bc,oBAAoB;;;;;;;;;qBC/DvB;;;;;KAMD;EACV,iBAAiB,cAAc,kBAAkB;EACjD,kBAAkB,cAAc;;;;;;;EAOhC,oBAAoB,eAAe;;EAEnC,wBACE,oBACA,eACA;EAEF,wBAAwB,iBAAiB;;EAEzC,qBAAqB,cAAc,kBAAkB;;EAErD,0BAA0B,kBAAkB;;UAG7B;;EAEf,SAAS,UAAU;EACnB;;;;;;;;;;wBAWc,gBACd,YAAY,mBACZ,UAAU,oBACT;;;UCjEc;;EAEf,SAAS,gBAAgB,OAAO;EAChC;;;;;;;;;;;;wBAac,kBACd,YAAY,mBACZ,gBAAgB,OAAO,4BACtB;;;KCXS;EACV;EACA;;;;;wBAMc,kBAAkB,WAAW;;;;;;;UAa5B;EACf,WAAW;;EAGX;;;;;;;EAQA;;;;;;EAOA;;;;;;EAOA;;;wBA8Bc,cAAc,QAAQ;;wBA0CtB,WAAW,QAAQ;;;;;;;;wBAYnB,aAAa,cAAc,QAAQ;;;;;;;;;;;;wBAenC,OACd,WACA,WACA,gBACA,QAAQ;;;;;;;;;;;;KCjJE;UAEK;;EAEf,QAAQ;;;;;;;EAQR;;;;;;;EAQA;;EAGA,cAAc,cAAc;;EAE5B,cAAc;;EAEd,uBAAuB;;UAGR;;;;;EAKf,SAAS,SAAS,QAAQ;;;;;EAM1B,SACE,cACA;IAAY,SAAS;IAAY;;;EAGnC,UAAU,cAAc;IAAY,SAAS;;;EAG7C;EAEA;;;;;;;;;;;;wBAec,iBACd,SAAS,SACT,SAAS,oBACR;;;KClFS;;EAEV;EACA;;EAEA;EACA;;EAEA;EACA;;;;;EAKA;EACA,OAAO;;KAGG;;;;;;;;;;EAUV;;;;;;;;;EAUA;;;;;;;;;;;;;EAcA,eAAe,OAAO;;;;;;;;;;;;;;;;;;;;;EAsBtB;;;;;;;;;;;EAYA;EAEA,eAAe,OAAO;EACtB,UAAU,OAAO;;;;;EAKjB,aAAa,OAAO;;UAGL;;;;;;;;EAQf,SAAS,SAAS;;EAElB;;;;;;;;;;;;;wBAmEc,WACd,SAAS,SACT,UAAS,cACR;;;;;;;KC7KS,GAAG,MAAM,GAAG,GAAG,GAAG;;;;;;;;KASlB,QAAQ,MAAM,4CACZ,GAAG,GAAG,GAAG,KACnB,cAAc,GAAG,GAAG,GAAG;;;;;;;;;;;wBAoBX,KAAK,GAAG,OAAO,cAAc,GAAG,GAAG,GAAG,KAAK,GAAG;;;;;;;;;UChB7C,oBAAoB;;;;;;;;;EASnC;;;UAIe;EACf,gBAAgB;;;;;;;;;;UAWD;;;;;EAKf,QAAQ,OAAO,WAAW,SAAS,mBAAmB;EACtD,OAAO,OAAO,WAAW,SAAS,mBAAmB;;;;;;;;;wBAUvC,eACd,kBAAkB,8BAEhB;;;;;;;;;;;;;EAcA,eAAe,OAAO;IAEvB;;;;;;wBAsEa,kBACd,YACA;;;;;EAMA,aAAa;;;;;;;;;EASb,eAAe,OAAO;IACf;UA8CQ;;EAEf,MAAM,QAAQ;;EAGd,SAAS;;;;;EAMT,iBAAiB;;;;;;;;;;;EAYjB;;EAGA;;EAEA;;;;;;;;EAQA;;EAEA,eAAe,OAAO;EAEtB,YAAY,OAAO,YAAY,OAAO;EACtC,eAAe,OAAO,YAAY,OAAO;EACzC,aAAa,OAAO,YAAY,OAAO;;UAGxB;;;;;;;EAOf,SAAS,SAAS,QAAQ;EAC1B;;;;;;;;;wBAUc,gBACd,SAAS,SACT,SAAS,mBACR;;;UCvRc;;EAEf,WAAW,OAAO;;;;;;;;;;;;;;EAclB;;UAGe;;EAEf,SAAS,SAAS;EAClB;;;;;;;;wBASc,YACd,SAAS,SACT,UAAU,OAAO,qBACjB,UAAS,eACR;;;;;;;UC7Bc;EACf;EACA;EACA;EACA;;UAGe,oBAAoB;;;;;;EAMnC,aAAa,mBAAmB,IAAI;;EAEpC,eAAe,KAAK;;EAEpB,qBAAqB,KAAK;;UAGX,yBAAyB;;;;;EAKxC;;EAEA,qBAAqB;;UAGN,qBAAqB;;EAEpC,SAAS,SAAS,QAAQ,oBAAoB;;EAG9C,QAAQ,IAAI,YAAY,UAAU,yBAAyB;;EAE3D,OAAO,IAAI;;;;;;;EAOX;;EAGA,WAAW;EAEX;;;wBAac,mBACd,KAAK,mBACJ,GAAG,IAAI;;;;;;;wBAgBM,mBAAmB,IACjC,SAAS,oBAAoB,MAC5B,qBAAqB"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/canvas/animation.ts","../src/file/drop-zone.ts","../src/input/change-gesture.ts","../src/input/defaults.ts","../src/knob/geometry.ts","../src/midi/access.ts","../src/midi/input.ts","../src/midi/message.ts","../src/piano/shortcuts.ts","../src/piano/index.ts","../src/pointer/drag.ts","../src/pointer/drag-value.ts","../src/pointer/long-press.ts","../src/pointer/wheel.ts","../src/position.ts"],"mappings":"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"}