@tremolo-ui/dom 0.7.0 → 0.8.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ValueRange } from "@tremolo-ui/functions";
+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 {
@@ -143,6 +143,14 @@ interface AcceptCandidate {
  * there by the time the file is dropped, which is when the answer counts.
  */
 export declare function matchesAccept(candidate: AcceptCandidate, accept?: string): boolean;
+/**
+ * Split files into those that satisfy `accept` and those that do not, keeping
+ * their order. See {@link matchesAccept}.
+ */
+export declare function partitionByAccept(files: Iterable<File>, accept?: string): {
+  accepted: File[];
+  rejected: File[];
+};
 //#endregion
 //#region src/file/drop-zone.d.ts
 /** What is in the air over the element. */
@@ -184,7 +192,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. */
@@ -295,6 +304,194 @@ export declare function mapModifier<T extends ModifierSetting, U extends Modifie
  */
 export declare function applyDelta(value: number, direction: number, options: ModifierValue<InputEventOption>, { min, max, step, scale }: ValueRange, modifiers?: ModifierState): number;
 //#endregion
+//#region src/input/check-steps.d.ts
+interface CheckStepsOptions {
+  /** The component, for the message. */
+  component: string;
+  /** The axis, for a component that has more than one. */
+  axis?: string;
+  /**
+   * The range to probe, or `null` to check nothing. An unbounded input has no
+   * travel to sample, so `NumberInput` passes `null` when `min` and `max` are
+   * not both there.
+   */
+  range: ValueRange | null;
+  keyboard?: ModifierValue<InputEventOption> | null;
+  wheel?: ModifierValue<InputEventOption> | null;
+  /**
+   * How the value is displayed, where the component shows one. Called with
+   * probe values only.
+   */
+  format?: (value: number) => string;
+}
+/**
+ * The warnings to show when a key press or a wheel notch cannot produce a
+ * change the user can see. Empty when there is nothing to say.
+ *
+ * Two settings that are each fine on their own can cancel out, and nothing
+ * fails when they do — the control simply sits there:
+ *
+ * - **`step` coarser than the amount.** `keyboard={['raw', 0.1]}` with
+ *   `step={1}` rounds every press straight back to where it started
+ * - **the display coarser than the amount.** A `format` showing two decimals
+ *   of a kHz value cannot show a press worth 1 Hz
+ *
+ * The second is only reported when the press is invisible at *every* point
+ * along the travel. A display that rounds is a deliberate choice and is
+ * normally right — it is being too coarse everywhere that makes it a mistake.
+ *
+ * **Meant for development builds only.** It probes the whole travel, so call
+ * it behind an inline `process.env.NODE_ENV` check: the bundler then drops
+ * the call, and this function and its messages with it.
+ */
+export declare function checkSteps({ component, axis, range, keyboard, wheel, format }: CheckStepsOptions): string[];
+//#endregion
+//#region src/input/defaults.d.ts
+/**
+ * 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.
+ *
+ * A modifier entry is not snapped to `step`, which is what lets the finer
+ * amount move at all — see `applyDelta`.
+ */
+export declare const DEFAULT_KEYBOARD_OPTIONS: ModifierValue<InputEventOption>;
+/**
+ * The wheel amount used by Knob, NumberInput, Slider, and XYPad by default.
+ *
+ * Browsers turn shift+wheel into horizontal scrolling, which empties `deltaY`
+ * and fills `deltaX`, so no modifier is bound here.
+ */
+export declare const DEFAULT_WHEEL_OPTIONS: ModifierValue<InputEventOption>;
+/**
+ * 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 const DEFAULT_DRAG_SENSITIVITY: ModifierValue<number>;
+//#endregion
+//#region src/input/direction.d.ts
+/**
+ * Which way an input moves a value, before any amount is applied.
+ *
+ * `applyDelta` takes the direction as given, since which key or which sign of
+ * `deltaY` counts as "up" differs per control. The answers are collected here
+ * so that every wrapper gives the same one: a knob that turns the other way
+ * in one framework would be a bug nobody could see from the code.
+ *
+ * Two families, by what the control looks like:
+ *
+ * - **one value** (`Knob`, `Slider`, `NumberInput`): right and up raise it
+ * - **a position on screen** (`XYPad`, `PointsEditor`): in screen coordinates,
+ *   x growing rightwards and y growing downwards, plus which axis moves
+ *
+ * A control that runs the other way (`reverse`) flips the result itself.
+ */
+/** One of the four arrow keys, as `KeyboardEvent.key` names it. */
+type ArrowKey = 'ArrowRight' | 'ArrowLeft' | 'ArrowUp' | 'ArrowDown';
+/** Is `key` one of the four arrow keys? */
+export declare function isArrowKey(key: string): key is ArrowKey;
+/** A move along one of the two axes of a position on screen. */
+interface AxisMove {
+  /** 0 = x, 1 = y. */
+  axis: 0 | 1;
+  /** `1` towards the right or the bottom, `-1` towards the left or the top. */
+  direction: 1 | -1;
+}
+/**
+ * The direction an arrow key moves a single value: right and up raise it.
+ * `null` for any other key.
+ */
+export declare function arrowKeyDirection(key: string): 1 | -1 | null;
+/**
+ * The axis and direction an arrow key moves a position on screen. `null` for
+ * any other key.
+ *
+ * The key picks the axis, whichever element inside the control holds the
+ * focus: a two-dimensional control is one control to the person moving it.
+ */
+export declare function arrowKeyMove(key: string): AxisMove | null;
+interface WheelDirectionOptions {
+  /**
+   * Read horizontal scrolling as well, for a control laid out horizontally:
+   * scrolling right raises the value. Vertical scrolling still counts when
+   * there is no horizontal movement.
+   *
+   * @default false
+   */
+  horizontal?: boolean;
+}
+/**
+ * The direction one wheel event moves a single value: scrolling up raises it.
+ * `null` when the event carries no movement the control reads.
+ */
+export declare function wheelDirection(event: Pick<WheelEvent, 'deltaX' | 'deltaY'>, { horizontal }?: WheelDirectionOptions): 1 | -1 | null;
+/**
+ * The axis and direction one wheel event moves a position on screen. `null`
+ * when the event carries no movement.
+ *
+ * Scrolling moves y, and shift switches to x. Browsers turn shift+wheel into
+ * horizontal scrolling: `deltaY` comes out empty and `deltaX` carries the
+ * movement. Reading whichever axis moved keeps shift working as the x-axis
+ * modifier — and picks up a trackpad's own horizontal gesture, which never
+ * had a modifier.
+ */
+export declare function wheelMove(event: Pick<WheelEvent, 'deltaX' | 'deltaY' | 'shiftKey'>): AxisMove | null;
+//#endregion
+//#region src/knob/geometry.d.ts
+/**
+ * Width and height of the viewBox a knob is drawn in. The arcs and the thumb
+ * 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;
+}
+/**
+ * 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 point at `angle` on a circle of `radius` around the centre of the
+ * viewBox.
+ *
+ * The radius depends on the stroke of the line being drawn, which each arc
+ * has its own of, so the point is found per arc rather than once for the knob.
+ */
+export declare function knobArcPoint(angle: number, radius: number): {
+  x: number;
+  y: number;
+};
+/**
+ * The radius that keeps a stroke of `strokeWidth` inside the viewBox: half of
+ * the stroke falls outside the path it is drawn along.
+ */
+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/midi/access.d.ts
 /** @private */
 export declare const PERMISSION_DENIED = "PERMISSION_DENIED";
@@ -407,6 +604,185 @@ interface MIDIMessageInstance {
  */
 export declare function createMIDIMessage(midiAccess: MIDIAccess | null, onMIDIMessage: (event: MIDIMessageEvent) => void): MIDIMessageInstance;
 //#endregion
+//#region src/number-input/stepper-drag.d.ts
+interface StepperDragOptions {
+  /** The value now, read when the drag starts moving it. */
+  getValue: () => number;
+  /**
+   * The range the value moves across. Its `step` is what one step of the drag
+   * is worth; see `numberInputRanges` for the one a number input uses.
+   */
+  range: ValueRange;
+  /**
+   * How many pixels of vertical movement make one step.
+   *
+   * @default 1
+   */
+  pixels?: number;
+  /**
+   * How much a step is worth, per modifier key: `0.1` makes the same movement
+   * count a tenth as much. Pressing or releasing the key mid-drag does not
+   * move the value.
+   *
+   * @default { default: 1, shift: 0.1 }
+   */
+  sensitivity?: ModifierValue<number>;
+  /** Hide the pointer and keep it from hitting the edge of the screen. */
+  pointerLock?: boolean;
+  /** Called with the new value whenever the drag moves it. */
+  onChange: (value: number) => void;
+}
+interface StepperDragInstance {
+  /** Replace the given options. `pointerLock` reaches the next drag. */
+  update: (options: Partial<StepperDragOptions>) => void;
+  /**
+   * Whether the drag in progress has moved the value. A stepper button's
+   * press-and-hold repeat stands down once it has, so the value is not moved
+   * twice.
+   */
+  moved: () => boolean;
+  destroy: () => void;
+}
+/**
+ * Drag up and down on the steppers of a number input to move its value, one
+ * `step` every `pixels` — up raises it, as on a knob.
+ *
+ * Counted from where the drag started moving rather than added up per
+ * event, so rounding cannot accumulate. The start is taken on the first
+ * move, not on pointerdown: a stepper button acts on pointerdown, so by then
+ * the value may already have been nudged once, and the drag carries on from
+ * there.
+ */
+export declare function createStepperDrag(element: Element, options: StepperDragOptions): StepperDragInstance;
+//#endregion
+//#region src/number-input/value.d.ts
+/**
+ * The value a number input edits, and how far it may go.
+ *
+ * Unlike a slider, either end may be left open, and `clampValue: false` lets
+ * the value past the ends that are set.
+ */
+interface NumberInputValueOptions {
+  min?: number;
+  max?: number;
+  step?: number;
+  scale?: Scale;
+  /**
+   * Keep the value between `min` and `max`.
+   *
+   * @default true
+   */
+  clampValue?: boolean;
+}
+/** The ranges {@link nudgeNumberInput} moves a value across. */
+interface NumberInputRanges {
+  /** For a `normalized` amount, which needs a finite span to take a share of. */
+  normalized: ValueRange;
+  /** For a `raw` amount, which does not. */
+  raw: ValueRange;
+}
+/**
+ * The ranges a number input moves its value across, with the open ends
+ * filled in.
+ *
+ * A normalized amount needs a finite span even when an end is unbounded or
+ * clamping is off. Safe integers provide one without overflowing the span a
+ * scale calculates. A raw amount needs no span, so its open ends can cover
+ * every finite number instead of stopping at the safe-integer range.
+ */
+export declare function numberInputRanges({ min, max, step, scale, clampValue }: NumberInputValueOptions): NumberInputRanges;
+/**
+ * Move a number input's value by one press of a key, a wheel notch or a
+ * stepper, picking the range that suits the kind of amount. See `applyDelta`.
+ */
+export declare function nudgeNumberInput(value: number, direction: number, options: ModifierValue<InputEventOption>, ranges: NumberInputRanges, modifiers?: ModifierState): number;
+/**
+ * Where the value stands against the ends: whether it can go no further
+ * down or up, and whether it lies outside them — which only an unclamped
+ * input, or a value set from outside, can do.
+ */
+export declare function numberInputBounds(value: number, { min, max, clampValue }: NumberInputValueOptions): {
+  atMin: boolean;
+  atMax: boolean;
+  outOfRange: boolean;
+};
+/**
+ * The value typed text commits to, or `null` when there is no number in it.
+ *
+ * Text with no number is not a value: the input should go back to what it
+ * was showing rather than commit a zero the user never typed. What is read
+ * is clamped here and not while typing, since clamping as the user types
+ * would make "1500" impossible to enter into an input whose max is 100.
+ */
+export declare function commitNumberInputText(text: string, parse: (text: string) => number, { min, max, clampValue }: NumberInputValueOptions): number | null;
+//#endregion
+//#region src/number-input/text.d.ts
+/**
+ * Reading a number out of the text of a number input, and keeping the caret
+ * in place while the number under it changes.
+ *
+ * The text is whatever `format` made of the value — `"440 Hz"`, `"-6.0 dB"` —
+ * or a half-typed entry, so none of this assumes the text is a number alone.
+ */
+/** Where the number is in the text; the rest, on either side, is the unit. */
+interface NumberSpan {
+  start: number;
+  end: number;
+}
+/**
+ * Where the number is in the text: from its first digit to its last, with the
+ * sign and the decimal point in front of it. Whatever is left on either side
+ * is taken for the unit, so it does not matter whether a space separates them,
+ * or what the number looks like — `+6.0`, `1e+21`, `1,000` and `1:30` are each
+ * one number. `null` when the text has no digit at all.
+ */
+export declare function numberSpan(text: string): NumberSpan | null;
+/**
+ * The number in the text, with the unit after it ignored: the default `parse`
+ * of a number input.
+ *
+ * `NaN`, which leaves the value alone, whenever the number cannot be read
+ * safely, rather than a part of it: text with no number, a number that is not
+ * a plain one (`1,000` would otherwise read as 1, and `1:30` as 1), and text
+ * with something in front of the number, which can change what it means (the
+ * `L` of a pan reading `L 30`). A `format` that writes any of those needs its
+ * own `parse`.
+ */
+export declare function parseNumberText(text: string): number;
+/**
+ * Where the caret is, relative to the decimal point, so that it can be put
+ * back at the same digit once the value has changed. See
+ * {@link caretAtDecimalOffset}.
+ */
+export declare function caretDecimalOffset(text: string, caret: number): number;
+/**
+ * The caret position `offset` characters from the decimal point of the new
+ * text, kept within the number.
+ *
+ * @example
+ * // The caret sits in front of the point of "9.9" when ArrowUp turns it
+ * // into "10.0"
+ * const offset = caretDecimalOffset('9.9', 1) // 0
+ * caretAtDecimalOffset('10.0', offset) // 2: still in front of the point
+ */
+export declare function caretAtDecimalOffset(text: string, offset: number): number;
+//#endregion
+//#region src/options/replace.d.ts
+/**
+ * The `update()` argument that leaves an instance with exactly `next` as its
+ * options.
+ *
+ * `update()` merges into what the instance has, which suits a wrapper that
+ * pushes one setting at a time. A wrapper handed the whole new set instead —
+ * a Svelte action, a Vue composable — has to clear what the new set no longer
+ * carries, or a handler taken away, or an option left to its default, keeps
+ * working.
+ *
+ * @example
+ * instance.update(replaceOptions(previous, next))
+ */
+export declare function replaceOptions<T extends object>(previous: T | undefined, next: T | undefined): Partial<T>;
+//#endregion
 //#region src/piano/layout.d.ts
 type NoteRange = {
   first: number;
@@ -470,6 +846,48 @@ export declare function notePosition(note: number, layout: PianoLayout): number;
  * @param height height of the keyboard, in pixels
  */
 export declare function noteAt(x: number, y: number, height: number, layout: PianoLayout): number | null;
+/**
+ * The white key width that makes the keyboard exactly `width` wide, for a
+ * keyboard that follows the size of its container.
+ *
+ * Solved from {@link pianoWidth} rather than by dividing among the white
+ * keys, so that a range that starts or ends on a black key — which sticks out
+ * by a fraction of a white key — still fills the container. The width grows
+ * linearly with the white key width, so two samples pin it down.
+ */
+export declare function fitWhiteKeyWidth(width: number, layout: Omit<PianoLayout, 'whiteKeyWidth'>): number;
+//#endregion
+//#region src/piano/shortcuts.d.ts
+type KeyboardShortcuts = {
+  /**
+   * Keys laid out from `noteRange.first`, one entry per semitone.
+   *
+   * 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.
+   */
+  keys: string[];
+};
+/**
+ * Ready-made keyboard layouts. Both assume `noteRange.first` is a C.
+ */
+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[];
+  };
+};
+/**
+ * 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.
+ */
+type KeyboardShortcutsScope = 'root' | 'window';
 //#endregion
 //#region src/piano/index.d.ts
 /**
@@ -499,6 +917,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 +949,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;
@@ -540,6 +976,219 @@ interface PianoInputInstance {
  */
 export declare function createPianoInput(element: Element, options: PianoInputOptions): PianoInputInstance;
 //#endregion
+//#region src/xy.d.ts
+/**
+ * A pair of per-axis values. The tuple elements are labelled, so editors show
+ * `[x: number, y: number]` rather than a bare pair.
+ */
+type XY<T> = [x: T, y: T];
+/**
+ * A setting that may be given once for both axes, or per axis.
+ *
+ * A single value is told from a pair with `Array.isArray`, so the single form
+ * is only offered while `T` cannot itself be an array. Where it can, the pair
+ * is the only way to write it, since a lone array would be read as a pair.
+ */
+type XYInput<T> = [T] extends [readonly unknown[]] ? readonly [x: T, y: T] : T | readonly [x: T, y: T];
+/**
+ * Spread a setting that may have been given as a single value.
+ *
+ * The parameter is written out rather than taken as `XYInput<T>`: a
+ * conditional type cannot be narrowed, so the constraint stays where it is
+ * declared and this takes both forms.
+ *
+ * The pair is copied rather than passed along, so that the result is a tuple
+ * the caller owns even when a readonly one was given.
+ */
+export declare function toXY<T>(value: T | readonly [x: T, y: T]): XY<T>;
+//#endregion
+//#region src/selection/box.d.ts
+/**
+ * A rectangle in the 0..1 space of whatever the box is drawn over, with `y`
+ * growing downwards — the same space the items are given in.
+ */
+interface SelectionBoxRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+interface SelectionBoxOptions<Id> {
+  /**
+   * Everything the box can pick up, read on every move rather than taken as a
+   * snapshot: what is under the box changes while it is dragged, and an item
+   * may have moved since the last one.
+   */
+  items: () => Iterable<readonly [Id, XY<number>]>;
+  /** The box as it is dragged, and `null` once it is gone. */
+  onBoxChange?: (box: SelectionBoxRect | null) => void;
+  /** What the box covers, added to whatever it started from. */
+  onSelectionChange?: (ids: Id[]) => void;
+}
+interface SelectionBoxBeginOptions<Id> {
+  /**
+   * Add to `selection` rather than replacing it. Ctrl / meta rather than
+   * shift, for the controls where shift is the fine-adjustment key.
+   */
+  additive?: boolean;
+  /** What was selected before the box started. Only read when `additive`. */
+  selection?: readonly Id[];
+}
+interface SelectionBoxInstance<Id> {
+  /** Replace the given options, without interrupting a box in progress. */
+  update: (options: Partial<SelectionBoxOptions<Id>>) => void;
+  /** Start a box at `at`, which is one of its corners. */
+  begin: (at: XY<number>, options?: SelectionBoxBeginOptions<Id>) => void;
+  /** Drag the opposite corner to `to`. */
+  move: (to: XY<number>) => void;
+  /**
+   * Finish the box. The selection stays as it is.
+   *
+   * @returns whether a box was running, so that a caller can tell a drag from
+   *   a press that selected nothing.
+   */
+  end: () => boolean;
+  /** The box being dragged, or `null` when there is none. */
+  box: () => SelectionBoxRect | null;
+  destroy: () => void;
+}
+/** Whether the box covers the point, edges included. */
+export declare function selectionBoxCovers(box: SelectionBoxRect, [x, y]: XY<number>): boolean;
+/**
+ * Selecting by dragging a box over a set of items.
+ *
+ * The drag itself is not here: the caller owns the pointer, and reports where
+ * it went in the same 0..1 space the items are given in.
+ */
+export declare function createSelectionBox<Id>(options: SelectionBoxOptions<Id>): SelectionBoxInstance<Id>;
+//#endregion
+//#region src/points-editor/index.d.ts
+/** Where a point is: 0..1 on each axis, with y growing downwards. */
+interface PointPosition {
+  x: number;
+  y: number;
+}
+/**
+ * A point's value is its position in the editor, so its range is the editor:
+ * no scaling, and no rounding to a step.
+ */
+export declare const POINT_AXIS: {
+  min: number;
+  max: number;
+};
+/**
+ * How much one wheel notch moves a point by default: a hundredth of the
+ * editor, whatever its pixel size.
+ */
+export declare const POINTS_EDITOR_DEFAULT_WHEEL: ModifierValue<InputEventOption>;
+/**
+ * How much one arrow key press moves a point by default. Shift is the
+ * fine-adjustment key everywhere else, so it is bound here too — but only on
+ * the keyboard. On the wheel it already means the x axis, and browsers hand
+ * shift+wheel over as horizontal scrolling anyway.
+ */
+export declare const POINTS_EDITOR_DEFAULT_KEYBOARD: ModifierValue<InputEventOption>;
+/** Keep a point within its range. An axis left out runs from 0 to 1. */
+export declare function clampPoint(point: PointPosition, min?: Partial<PointPosition>, max?: Partial<PointPosition>): PointPosition;
+/**
+ * What a point tells the editor about itself, so that a selection can be
+ * moved without the editor knowing how the points are stored.
+ */
+interface PointsEditorPoint {
+  value: PointPosition;
+  min?: Partial<PointPosition>;
+  max?: Partial<PointPosition>;
+  /** A point that cannot move stays put while the rest of a selection moves. */
+  readonly?: boolean;
+  onChange?: (value: PointPosition) => void;
+  /** The point's own element, to match the focus and a press against. */
+  element?: Element | null;
+  /** The wheel option the point resolved, `null` for no wheel. */
+  wheel?: ModifierValue<InputEventOption> | null;
+}
+interface PointsEditorOptions {
+  /**
+   * Let points be selected, and a selection be moved as one. While it is off
+   * nothing is selected, and a drag moves only the point it started on.
+   *
+   * @default false
+   */
+  selectable?: boolean;
+  /**
+   * The ids of the selected points. Whoever holds the selection pushes it
+   * back with `update()` after {@link PointsEditorOptions.onSelectionChange}.
+   */
+  selection?: readonly string[];
+  /** Called whenever a press or a selection box changes the selection. */
+  onSelectionChange?: (selection: string[]) => void;
+  /** Called whenever the selection box changes, with `null` once it is gone. */
+  onSelectionBoxChange?: (rect: SelectionBoxRect | null) => void;
+}
+interface PointsEditorInstance {
+  /** Replace the given options. */
+  update: (options: Partial<PointsEditorOptions>) => void;
+  /**
+   * Register a point under `id`. `read` is called whenever the editor needs
+   * the point, so it can return what the point is now rather than what it
+   * was when it registered. Returns the function that unregisters it.
+   */
+  registerPoint: (id: string, read: () => PointsEditorPoint) => () => void;
+  /** Whether the element is a point, or inside one. */
+  isPointElement: (element: Element | null | undefined) => boolean;
+  /**
+   * A pointer went down on a point: work out the new selection and remember
+   * where everything the drag picked up started.
+   *
+   * Ctrl / meta add the point to the selection or take it out: shift is the
+   * fine-adjustment key on every control here, and it cannot be both. A
+   * press on a point already selected keeps the selection, so the group can
+   * be dragged.
+   */
+  beginPointDrag: (id: string, modifiers: ModifierState) => void;
+  /**
+   * Move everything the drag picked up by `delta` from where it started,
+   * stopping the whole group together at the edge.
+   */
+  movePointDrag: (delta: PointPosition) => void;
+  /**
+   * Move `id` — and the selection, when it is part of one — by `delta` from
+   * where the points are now: an input that is not a drag has no earlier
+   * position to measure against.
+   */
+  nudgeSelection: (id: string, delta: PointPosition) => void;
+  /**
+   * Move `id` by one press of `option` along one axis, taking the selection
+   * along as {@link PointsEditorInstance.nudgeSelection} does.
+   */
+  nudgePoint: (id: string, axis: 'x' | 'y', direction: number, option: ModifierValue<InputEventOption>, modifiers?: ModifierState) => void;
+  /**
+   * Move the point holding the focus by one wheel notch, with its own wheel
+   * option. The wheel is listened to once for the whole editor, since a wheel
+   * event only reaches what the cursor is over. Returns whether a point took
+   * it, so the caller knows whether to consume the event.
+   */
+  nudgeFocusedPoint: (axis: 'x' | 'y', direction: number, modifiers: ModifierState) => boolean;
+  /** A drag on empty space started at `at`: start a selection box there. */
+  beginSelectionBox: (at: PointPosition, modifiers: ModifierState) => void;
+  moveSelectionBox: (to: PointPosition) => void;
+  /**
+   * End the selection box. The press that started it left the focus on
+   * nothing, and the arrow keys and the wheel reach a point only through the
+   * focus, so it is handed to one of the points the box selected.
+   */
+  endSelectionBox: () => void;
+  destroy: () => void;
+}
+/**
+ * The selection and the moves of a points editor: which points a press or a
+ * box selects, and how a selection moves as one.
+ *
+ * The points stay with the wrapper, which registers each one; the editor only
+ * reads them when it needs to, so a point's value can change on every frame
+ * of a drag without anything being re-registered.
+ */
+export declare function createPointsEditor(options?: PointsEditorOptions): PointsEditorInstance;
+//#endregion
 //#region src/pointer/drag.d.ts
 type DragState = {
   /** Total movement from the drag start, in screen coordinates. */
@@ -656,32 +1305,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,6 +1444,50 @@ 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}. */
@@ -853,65 +1520,81 @@ interface WheelInstance {
  */
 export declare function createWheel(element: Element, onWheel: (event: WheelEvent) => void, options?: WheelOptions): WheelInstance;
 //#endregion
-//#region src/selection/box.d.ts
+//#region src/position.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.
+ * Where a value sits along a track, as a whole percentage from its start.
+ *
+ * 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.
  */
-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;
+export declare function valuePercent(value: number, { min, max, scale }: Pick<ValueRange, 'min' | 'max' | 'scale'>, reversed?: boolean): number;
+//#endregion
+//#region src/slider/marks.d.ts
+/**
+ * How `Slider.Marks` fills itself in when it is given no children: one option
+ * every `per`, or every `step` of the slider. The object form turns off the
+ * mark or the label for the whole set; a single option is customized by
+ * writing `Slider.MarksOption` out instead.
+ */
+type MarksOptions = 'step' | number | {
+  per: 'step' | number;
+  mark?: boolean;
+  label?: boolean;
+};
+/** One mark along a slider, as {@link sliderMarks} lays them out. */
+interface SliderMark {
+  value: number;
+  mark: boolean;
+  label: boolean;
 }
-/** 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 marks `options` asks for between `min` and `max`, in ascending order.
  *
- * 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.
+ * Each value is a whole multiple of the interval, rounded to the digits the
+ * interval has: stepping by 0.1 would otherwise put binary debris in the
+ * labels (`0.1 * 3` is `0.30000000000000004`).
  */
-export declare function createSelectionBox<Id>(options: SelectionBoxOptions<Id>): SelectionBoxInstance<Id>;
+export declare function sliderMarks(options: MarksOptions, min: number, max: number, step: number): SliderMark[];
+//#endregion
+//#region src/style.d.ts
+/**
+ * A number as a CSS length, for a custom property.
+ *
+ * A custom property takes whatever text it is given, so `--size: 50` comes out
+ * as the invalid `50` rather than `50px`. React appends `px` to a bare number
+ * only for the properties it knows take a length, and a custom property is
+ * never one of them; Vue and Svelte append nothing at all. Anything already a
+ * string is passed through, so `'3rem'` and `'100%'` still work.
+ */
+export declare function cssLength(value: number | string | undefined): string | undefined;
+/**
+ * Take an element out of sight while leaving it in the accessibility tree and
+ * in the tab order.
+ *
+ * `display: none` and `visibility: hidden` would remove it from both, and the
+ * native control underneath a headless component is what carries the ARIA and
+ * the keyboard behaviour. `pointer-events: none` is safe because nothing is
+ * ever clicked here directly: a `<label>` forwards its click, and a drag is
+ * handled by the part that is visible.
+ *
+ * Every value is a string with its unit, so the object can be handed to any
+ * framework's `style` binding as it is.
+ */
+export declare const visuallyHiddenStyle: {
+  readonly position: "absolute";
+  readonly width: "1px";
+  readonly height: "1px";
+  readonly padding: "0";
+  readonly margin: "-1px";
+  readonly overflow: "hidden";
+  readonly clip: "rect(0, 0, 0, 0)";
+  readonly clipPath: "inset(50%)";
+  readonly whiteSpace: "nowrap";
+  readonly border: "0";
+  readonly pointerEvents: "none";
+};
 //#endregion
-export type { AcceptCandidate, AnimationCanvasInstance, AnimationCanvasOptions, AnimationFrame, 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 { AcceptCandidate, AnimationCanvasInstance, AnimationCanvasOptions, AnimationFrame, ArrowKey, AxisMove, AxisOptions, CanvasDrawFunction, CanvasInitFunction, CheckStepsOptions, DragInstance, DragOptions, DragState, DragValueInstance, DragValueMapping, DragValueOptions, DrawingContext, DrawingState, DrawingStateValue, DropZoneInstance, DropZoneOptions, DropZoneState, InputEventOption, KeyboardShortcuts, KeyboardShortcutsScope, KnobAngleOptions, KnobAngles, LongPressInstance, LongPressOptions, MIDIAccessError, MIDIAccessInstance, MIDIAccessOptions, MIDIAccessState, MIDIInputHandlers, MIDIInputInstance, MIDIMessageInstance, MappingContext, MarksOptions, Modifier, ModifierMap, ModifierState, ModifierValue, NoteRange, NoteSource, NumberInputRanges, NumberInputValueOptions, NumberSpan, PianoInputInstance, PianoInputOptions, PianoLayout, PointPosition, PointsEditorInstance, PointsEditorOptions, PointsEditorPoint, SelectionBoxBeginOptions, SelectionBoxInstance, SelectionBoxOptions, SelectionBoxRect, SliderMark, StepperDragInstance, StepperDragOptions, WheelDirectionOptions, WheelInstance, WheelOptions, XY, XYInput };
 //# sourceMappingURL=index.d.ts.map