@tremolo-ui/dom 0.7.0 → 0.9.0

package/dist/index.js

@@ -1,4 +1,5 @@
-import { clamp, isBlackKey, isWhiteKey, linearScale, normalizeValue, noteKey, noteKeys, stepValue, toPrecision } from "@tremolo-ui/functions";
+import { _ as DEFAULT_DRAG_SENSITIVITY, b as matchesAccept, h as notePosition, m as noteAt, o as createPointsEditor, t as toXY, u as createDrag, v as DEFAULT_KEYBOARD_OPTIONS, x as partitionByAccept, y as DEFAULT_WHEEL_OPTIONS } from "./xy-lNFl1CTO.js";
+import { clamp, linearScale, normalizeValue, radian, stepValue, toFixed, toPrecision } from "@tremolo-ui/functions";
 //#region src/canvas/context.ts
 /**
 * The assignable parts of a 2D context's drawing state. They have to be
@@ -36,9 +37,6 @@ const drawingState = [
 	"imageSmoothingEnabled",
 	"imageSmoothingQuality"
 ];
-function isDrawingState(value) {
-	return typeof value === "string" && drawingState.includes(value);
-}
 /** Copy the drawing state off a context, to put back after a resize. */
 function readDrawingState(context) {
 	const state = {};
@@ -235,39 +233,6 @@ function createAnimationCanvas(canvas, options) {
 	};
 }
 //#endregion
-//#region src/file/accept.ts
-/**
-* 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.
-*/
-function matchesAccept(candidate, accept) {
-	const rules = (accept ?? "").split(",").map((rule) => rule.trim().toLowerCase()).filter(Boolean);
-	if (rules.length === 0) return true;
-	const name = candidate.name?.toLowerCase();
-	const type = candidate.type.toLowerCase();
-	let undecided = false;
-	for (const rule of rules) if (rule.startsWith(".")) {
-		if (name === void 0) undecided = true;
-		else if (name.endsWith(rule)) return true;
-	} else if (rule.endsWith("/*")) {
-		if (type.startsWith(rule.slice(0, -1))) return true;
-	} else if (type === rule) return true;
-	return undecided;
-}
-//#endregion
 //#region src/file/drop-zone.ts
 /**
 * Take files dropped onto an element.
@@ -346,14 +311,10 @@ function createDropZone(element, options = {}) {
 			invalid: false
 		});
 		if (opts.disabled) return;
-		const dropped = Array.from(event.dataTransfer?.files ?? []);
-		const accepted = [];
-		const rejected = [];
-		for (const file of dropped) if (matchesAccept(file, opts.accept)) accepted.push(file);
-		else rejected.push(file);
-		if (rejected.length > 0) opts.onReject?.(rejected, event);
+		const { accepted, rejected } = partitionByAccept(event.dataTransfer?.files ?? [], opts.accept);
 		const taken = opts.multiple ? accepted : accepted.slice(0, 1);
 		if (taken.length > 0) opts.onDrop?.(taken, event);
+		if (rejected.length > 0) opts.onReject?.(rejected, event);
 	}
 	/**
 	* A drag that ends anywhere else — dropped on another element, cancelled
@@ -395,118 +356,122 @@ function createDropZone(element, options = {}) {
 	};
 }
 //#endregion
-//#region src/input/modifiers.ts
+//#region src/input/change-gesture.ts
 /**
-* Checked in this order, and the first one that is both held and configured
-* wins. Fixing an order is what keeps two modifiers held at once from
-* behaving differently between browsers.
+* 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.
 */
-const MODIFIER_ORDER = [
-	"meta",
-	"ctrl",
-	"alt",
-	"shift"
-];
-const MODIFIER_FLAG = {
-	meta: "metaKey",
-	ctrl: "ctrlKey",
-	alt: "altKey",
-	shift: "shiftKey"
-};
-/**
-* A map is the only form with a `default` key, which is what tells it apart
-* from a bare setting. Tuples are arrays, so they never match.
-*/
-function isModifierMap(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value) && "default" in value;
+function createChangeGesture(options = {}) {
+	let opts = options;
+	let current = null;
+	let timer = null;
+	function clearTimer() {
+		if (timer !== null) clearTimeout(timer);
+		timer = null;
+	}
+	function end() {
+		clearTimer();
+		if (!current) return;
+		const { source } = current;
+		current = null;
+		opts.onEnd?.(source);
+	}
+	function start(source, held) {
+		current = {
+			source,
+			held
+		};
+		opts.onStart?.(source);
+	}
+	return {
+		hold: (source) => {
+			if (current?.held && current.source === source) return;
+			end();
+			start(source, true);
+		},
+		pulse: (source) => {
+			if (current?.held) return;
+			if (!current || current.source !== source) {
+				end();
+				start(source, false);
+			}
+			clearTimer();
+			timer = setTimeout(end, opts.endDelay ?? 500);
+		},
+		instant: (source, change) => {
+			end();
+			start(source, false);
+			change();
+			end();
+		},
+		end,
+		active: () => current !== null,
+		update: (next) => {
+			opts = {
+				...opts,
+				...next
+			};
+		},
+		destroy: end
+	};
 }
+//#endregion
+//#region src/knob/geometry.ts
 /**
-* Pick the setting that applies, given the modifier keys being held.
-*
-* @example
-* selectModifier({ default: 1, shift: 0.1 }, event)
+* 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.
 */
-function selectModifier(options, modifiers) {
-	if (!isModifierMap(options)) return {
-		value: options,
-		modifier: null
-	};
-	if (modifiers) for (const modifier of MODIFIER_ORDER) {
-		const value = options[modifier];
-		if (value !== void 0 && modifiers[MODIFIER_FLAG[modifier]]) return {
-			value,
-			modifier
-		};
-	}
+const KNOB_VIEWBOX_SIZE = 100;
+const center = 50;
+function knobAngles({ value, min, max, scale, startValue, angleRange }) {
+	const p = scale.normalize(value, min, max);
+	const s = scale.normalize(startValue, min, max);
+	const r1 = -angleRange / 2;
 	return {
-		value: options.default,
-		modifier: null
+		p,
+		r1,
+		r2: r1 + Math.min(p, s) * angleRange,
+		r3: r1 + Math.max(p, s) * angleRange,
+		r4: angleRange / 2
 	};
 }
 /**
-* 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.
+* The point at `angle` on a circle of `radius` around the centre of the
+* viewBox.
 *
-* @example
-* mapModifier({ default: 1, shift: 0.1 }, (f) => ['raw', step * f])
-* // { default: ['raw', 1], shift: ['raw', 0.1] }
+* 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.
 */
-function mapModifier(options, fn) {
-	if (!isModifierMap(options)) return fn(options);
-	const mapped = { default: fn(options.default) };
-	for (const modifier of MODIFIER_ORDER) {
-		const value = options[modifier];
-		if (value !== void 0) mapped[modifier] = fn(value);
-	}
-	return mapped;
+function knobArcPoint(angle, radius) {
+	return {
+		x: center + radius * Math.cos(radian(angle - 90)),
+		y: center + radius * Math.sin(radian(angle - 90))
+	};
 }
-//#endregion
-//#region src/input/apply-delta.ts
 /**
-* Move a value by an amount of input, as reported by a wheel or an arrow key.
-*
-* The pipeline matches {@link createDragValue}: scale, then step, then clamp.
-* Which key or which sign of `deltaY` counts as which direction is left to the
-* caller, since it differs per component.
-*
-* @param direction which way, and how many times, to apply the option. The
-* size of one step is `option[1]`, so this is normally `1` or `-1`.
-*
-* @param modifiers the event, for `options` that name a modifier key. See
-* {@link selectModifier}.
-*
-* @example
-* // ArrowDown on a slider whose keyboard option is ['raw', 1]
-* applyDelta(value, -1, keyboard, { min, max, step, scale })
-*
-* @example
-* // Shift+ArrowDown, where `keyboard` is { default: …, shift: ['raw', 0.1] }
-* applyDelta(value, -1, keyboard, range, event)
+* The radius that keeps a stroke of `strokeWidth` inside the viewBox: half of
+* the stroke falls outside the path it is drawn along.
 */
-function applyDelta(value, direction, options, { min, max, step, scale = linearScale }, modifiers) {
-	if (min >= max) throw new RangeError("requirements: min < max");
-	if (step !== void 0 && (!Number.isFinite(step) || step <= 0)) throw new RangeError("applyDelta step: requirements: finite and greater than 0");
-	const { value: [mode, amount], modifier } = selectModifier(options, modifiers);
-	const x = direction * amount;
-	const next = mode === "normalized" ? scale.denormalize(scale.normalize(value, min, max) + x, min, max) : value + x;
-	const quantum = modifier === null ? step : void 0;
-	const stepped = quantum !== void 0 ? stepValue(next, quantum) : next;
-	return clamp(toPrecision(stepped), min, max);
+function knobArcRadius(strokeWidth) {
+	const width = typeof strokeWidth === "number" ? strokeWidth : Number.parseFloat(String(strokeWidth));
+	return Number.isFinite(width) ? center - width / 2 : center;
+}
+/** Build an SVG path for an arc, splitting full turns into drawable segments. */
+function knobArcPath(startAngle, endAngle, radius) {
+	const start = knobArcPoint(startAngle, radius);
+	const sweep = endAngle - startAngle;
+	const segmentCount = Math.max(1, Math.ceil(Math.abs(sweep) / 180));
+	const segmentSweep = sweep / segmentCount;
+	let path = `M ${start.x} ${start.y}`;
+	for (let i = 1; i <= segmentCount; i += 1) {
+		const end = knobArcPoint(startAngle + segmentSweep * i, radius);
+		path += ` A ${radius} ${radius} 0 0 ${segmentSweep >= 0 ? 1 : 0} ${end.x} ${end.y}`;
+	}
+	return path;
 }
 //#endregion
 //#region src/midi/access.ts
-/** @private */
-const PERMISSION_DENIED = "PERMISSION_DENIED";
-/** @private */
-const NOT_SUPPORTED = "NOT_SUPPORTED";
-/** @private */
-const UNAVAILABLE = "UNAVAILABLE";
 const INITIAL_STATE = {
 	midiAccess: null,
 	error: null,
@@ -520,9 +485,9 @@ const INITIAL_STATE = {
 */
 function toError(reason) {
 	const name = typeof reason === "object" && reason !== null && "name" in reason ? String(reason.name) : "";
-	if (name === "SecurityError" || name === "NotAllowedError") return PERMISSION_DENIED;
-	if (name === "NotSupportedError" || name === "TypeError") return NOT_SUPPORTED;
-	return UNAVAILABLE;
+	if (name === "SecurityError" || name === "NotAllowedError") return "PERMISSION_DENIED";
+	if (name === "NotSupportedError" || name === "TypeError") return "NOT_SUPPORTED";
+	return "UNAVAILABLE";
 }
 /**
 * Request MIDI access in the browser.
@@ -561,7 +526,7 @@ function createMIDIAccess() {
 		if (typeof navigator === "undefined" || !navigator.requestMIDIAccess) {
 			setState({
 				...state,
-				error: NOT_SUPPORTED
+				error: "NOT_SUPPORTED"
 			});
 			return;
 		}
@@ -659,13 +624,6 @@ const STATUS = {
 	PITCH_BEND: 224
 };
 /**
-* 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.
-*/
-const PITCH_BEND_CENTER = 8192;
-/**
 * 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.
@@ -713,347 +671,65 @@ function createMIDIInput(midiAccess, handlers) {
 	};
 }
 //#endregion
-//#region src/piano/layout.ts
-/**
-* `[noteRange.first, noteRange.first + 1, ..., noteRange.last]`
-*/
-function getNoteRangeArray(noteRange) {
-	return Array.from({ length: noteRange.last - noteRange.first + 1 }, (_, i) => i + noteRange.first);
-}
-const DEFAULT_KEY_GAP = 1;
-const DEFAULT_BLACK_KEY_WIDTH_RATIO = .65;
-const DEFAULT_BLACK_KEY_HEIGHT_RATIO = .6;
+//#region src/piano/shortcuts.ts
 /**
-* How many white keys sit at or before each pitch class, counting from C.
-*
-* A black key shares the number of the white key to its left plus one, which
-* puts it on the boundary between the two; {@link notePosition} then shifts it
-* back by half its width to centre it there.
+* Ready-made keyboard layouts. Both assume `noteRange.first` is a C.
 */
-const whiteKeysBefore = {
-	C: 0,
-	"C#": 1,
-	D: 1,
-	"D#": 2,
-	E: 2,
-	F: 3,
-	"F#": 4,
-	G: 4,
-	"G#": 5,
-	A: 5,
-	"A#": 6,
-	B: 6
+const SHORTCUTS = {
+	/** Every semitone from C, over the two rows of a QWERTY keyboard. */
+	HOME_ROW: { keys: [
+		"a",
+		"w",
+		"s",
+		"e",
+		"d",
+		"f",
+		"t",
+		"g",
+		"y",
+		"h",
+		"u",
+		"j",
+		"k",
+		"o",
+		"l",
+		"p",
+		";"
+	] },
+	/** The white keys only, on the home row. Black keys have no shortcut. */
+	HOME_ROW_NATURAL: { keys: [
+		"a",
+		"",
+		"s",
+		"",
+		"d",
+		"f",
+		"",
+		"g",
+		"",
+		"h",
+		"",
+		"j",
+		"k",
+		"",
+		"l",
+		"",
+		";"
+	] }
 };
-/** Width of a black key in pixels. */
-function blackKeyWidth(layout) {
-	return layout.whiteKeyWidth * (layout.blackKeyWidthRatio ?? DEFAULT_BLACK_KEY_WIDTH_RATIO);
-}
-function rawNotePosition(note, layout) {
-	const slot = layout.whiteKeyWidth + (layout.keyGap ?? DEFAULT_KEY_GAP);
-	const target = noteKey(note);
-	const first = noteKey(layout.noteRange.first);
-	const octave = Math.floor((note - layout.noteRange.first) / 12);
-	const octaveOffset = noteKeys.indexOf(first) > noteKeys.indexOf(target) ? 1 : 0;
-	const whiteKeysIn = whiteKeysBefore[target] - whiteKeysBefore[first] + (octave + octaveOffset) * 7;
-	return isBlackKey(note) ? whiteKeysIn * slot - blackKeyWidth(layout) / 2 : whiteKeysIn * slot;
-}
-function pianoBounds(layout) {
-	const notes = getNoteRangeArray(layout.noteRange);
-	if (notes.length === 0) return {
-		left: 0,
-		right: 0
-	};
-	let left = Infinity;
-	let right = -Infinity;
-	const whiteWidth = layout.whiteKeyWidth + (layout.keyGap ?? DEFAULT_KEY_GAP);
-	for (const note of notes) {
-		const noteLeft = rawNotePosition(note, layout);
-		const width = isBlackKey(note) ? blackKeyWidth(layout) : whiteWidth;
-		left = Math.min(left, noteLeft);
-		right = Math.max(right, noteLeft + width);
-	}
-	return {
-		left,
-		right
-	};
-}
-/** Width of the whole keyboard in pixels. */
-function pianoWidth(layout) {
-	const { left, right } = pianoBounds(layout);
-	return right - left;
-}
-/**
-* 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`.
-*/
-function notePosition(note, layout) {
-	return rawNotePosition(note, layout) - pianoBounds(layout).left;
-}
-/**
-* 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
-*/
-function noteAt(x, y, height, layout) {
-	if (x < 0 || x >= pianoWidth(layout) || y < 0 || y >= height) return null;
-	const notes = getNoteRangeArray(layout.noteRange);
-	if (y < height * (layout.blackKeyHeightRatio ?? DEFAULT_BLACK_KEY_HEIGHT_RATIO)) for (const note of notes) {
-		if (isWhiteKey(note)) continue;
-		const left = notePosition(note, layout);
-		if (left <= x && x < left + blackKeyWidth(layout)) return note;
-	}
-	const slot = layout.whiteKeyWidth + (layout.keyGap ?? DEFAULT_KEY_GAP);
-	for (const note of notes) {
-		if (isBlackKey(note)) continue;
-		const left = notePosition(note, layout);
-		if (left <= x && x < left + slot) return note;
-	}
-	return null;
-}
-//#endregion
-//#region src/pointer/drag.ts
-/**
-* Applied to the element for the lifetime of the instance.
-*
-* `touch-action` stops touch dragging from scrolling the page. That alone makes
-* the browser treat a long press as the start of a text selection, so selection
-* and the iOS callout are suppressed here too.
-*/
-const MANAGED_STYLES = [
-	["touch-action", "none"],
-	["user-select", "none"],
-	["-webkit-user-select", "none"],
-	["-webkit-touch-callout", "none"]
-];
-const managedStyleStates = /* @__PURE__ */ new WeakMap();
 /**
-* Track a pointer drag on an element.
-*
-* Uses Pointer Events only, and pointer capture so that the drag keeps working
-* once the pointer leaves the element. For the lifetime of the instance the
-* 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}.
+* Whether a key press was typed into something: shortcuts must not play a
+* note for a letter that is going into a text field.
 */
-function createDrag(element, options = {}) {
-	let opts = options;
-	const multiPointer = options.multiPointer ?? false;
-	const capture = element;
-	const style = element.style;
-	let managedStyles = managedStyleStates.get(element);
-	if (style) {
-		if (managedStyles) managedStyles.count += 1;
-		else {
-			const previous = /* @__PURE__ */ new Map();
-			for (const [property, value] of MANAGED_STYLES) {
-				previous.set(property, {
-					value: style.getPropertyValue(property),
-					priority: style.getPropertyPriority(property)
-				});
-				style.setProperty(property, value);
-			}
-			managedStyles = {
-				count: 1,
-				previous
-			};
-			managedStyleStates.set(element, managedStyles);
-		}
-	}
-	const pointers = /* @__PURE__ */ new Map();
-	/**
-	* How many pointers each target carries. Adding the same listener twice is a
-	* no-op and removing it once removes it for good, so a target is subscribed
-	* to while at least one pointer is on it and no longer.
-	*/
-	const targets = /* @__PURE__ */ new Map();
-	let previousCursor;
-	/** The pointer that asked for the lock, while it is still down. */
-	let lockedPointerId = null;
-	let lockRequest = 0;
-	let destroyed = false;
-	function state(event, pointer, deltaX, deltaY) {
-		return {
-			x: pointer.lockBaseX !== void 0 ? pointer.lockBaseX + pointer.lockMoveX : event.screenX - pointer.startX,
-			y: pointer.lockBaseY !== void 0 ? pointer.lockBaseY + pointer.lockMoveY : event.screenY - pointer.startY,
-			deltaX,
-			deltaY,
-			clientX: event.clientX,
-			clientY: event.clientY,
-			pointerId: event.pointerId,
-			event
-		};
-	}
-	/**
-	* `user-select: none` only makes the element's own text unselectable; the
-	* browser still starts a selection on long press and grabs whatever text it
-	* finds nearby. Cancelling the selection outright is what actually stops it.
-	*/
-	function preventSelectStart(event) {
-		event.preventDefault();
-	}
-	function retainTarget(target) {
-		const count = targets.get(target) ?? 0;
-		if (count === 0) {
-			target.addEventListener("pointermove", handlePointerMove);
-			target.addEventListener("pointerup", handlePointerUp);
-			target.addEventListener("pointercancel", handlePointerUp);
-			if (target === element) target.addEventListener("lostpointercapture", handleLostPointerCapture);
-		}
-		targets.set(target, count + 1);
+function isEditableTarget(target) {
+	if (!(target instanceof HTMLElement)) return false;
+	if (target.matches("input, textarea, select")) return true;
+	for (let element = target; element;) {
+		const contentEditable = element.getAttribute("contenteditable");
+		if (contentEditable !== null) return contentEditable.toLowerCase() !== "false";
+		element = element.parentElement;
 	}
-	function releaseTarget(target) {
-		const count = targets.get(target) ?? 0;
-		if (count > 1) {
-			targets.set(target, count - 1);
-			return;
-		}
-		target.removeEventListener("pointermove", handlePointerMove);
-		target.removeEventListener("pointerup", handlePointerUp);
-		target.removeEventListener("pointercancel", handlePointerUp);
-		if (target === element) target.removeEventListener("lostpointercapture", handleLostPointerCapture);
-		targets.delete(target);
-	}
-	function handlePointerDown(event) {
-		const pointerEvent = event;
-		if (pointerEvent.button !== 0) return;
-		const pointerId = pointerEvent.pointerId;
-		if (pointers.has(pointerId)) return;
-		if (!multiPointer && pointers.size > 0) return;
-		if (opts.shouldStart && !opts.shouldStart(pointerEvent)) return;
-		const isFirst = pointers.size === 0;
-		if (isFirst && opts.cursor && style) {
-			previousCursor = style.cursor;
-			style.cursor = opts.cursor;
-		}
-		capture.setPointerCapture?.(pointerId);
-		const moveTarget = capture.hasPointerCapture?.(pointerId) === true ? element : globalThis.window ?? element;
-		const pointer = {
-			moveTarget,
-			startX: pointerEvent.screenX,
-			startY: pointerEvent.screenY,
-			lastX: pointerEvent.screenX,
-			lastY: pointerEvent.screenY,
-			lockMoveX: 0,
-			lockMoveY: 0,
-			lastEvent: pointerEvent
-		};
-		pointers.set(pointerId, pointer);
-		retainTarget(moveTarget);
-		if (isFirst) globalThis.document?.addEventListener("selectstart", preventSelectStart);
-		if (isFirst && opts.pointerLock) {
-			const requestId = ++lockRequest;
-			lockedPointerId = pointerId;
-			globalThis.document?.addEventListener("pointerlockchange", handleLockChange);
-			try {
-				(capture.requestPointerLock?.())?.then?.(() => {
-					if (requestId === lockRequest && (!pointers.has(pointerId) || destroyed) && globalThis.document?.pointerLockElement === element) globalThis.document.exitPointerLock?.();
-				}, () => {});
-			} catch {}
-		}
-		opts.onDragStart?.(state(pointerEvent, pointer, 0, 0));
-	}
-	function handlePointerMove(event) {
-		const pointerEvent = event;
-		const pointer = pointers.get(pointerEvent.pointerId);
-		if (!pointer) return;
-		const locked = pointer.lockBaseX !== void 0;
-		const deltaX = locked ? pointerEvent.movementX ?? 0 : pointerEvent.screenX - pointer.lastX;
-		const deltaY = locked ? pointerEvent.movementY ?? 0 : pointerEvent.screenY - pointer.lastY;
-		const threshold = opts.threshold ?? 0;
-		if (Math.abs(deltaX) < threshold && Math.abs(deltaY) < threshold) return;
-		pointer.lastX = pointerEvent.screenX;
-		pointer.lastY = pointerEvent.screenY;
-		pointer.lastEvent = pointerEvent;
-		if (locked) {
-			pointer.lockMoveX += deltaX;
-			pointer.lockMoveY += deltaY;
-		}
-		opts.onDrag?.(state(pointerEvent, pointer, deltaX, deltaY));
-	}
-	function handleLockChange() {
-		if (lockedPointerId === null) return;
-		const pointer = pointers.get(lockedPointerId);
-		if (!pointer) return;
-		if (globalThis.document?.pointerLockElement === element) {
-			pointer.lockBaseX = pointer.lastX - pointer.startX;
-			pointer.lockBaseY = pointer.lastY - pointer.startY;
-			pointer.lockMoveX = 0;
-			pointer.lockMoveY = 0;
-			return;
-		}
-		if (pointer.lockBaseX === void 0) return;
-		finishDrag(lockedPointerId);
-	}
-	function handlePointerUp(event) {
-		const pointerEvent = event;
-		finishDrag(pointerEvent.pointerId, pointerEvent);
-	}
-	function handleLostPointerCapture(event) {
-		finishDrag(event.pointerId);
-	}
-	function finishDrag(pointerId, event) {
-		const pointer = pointers.get(pointerId);
-		if (!pointer) return;
-		const finalState = event ? state(event, pointer, event.screenX - pointer.lastX, event.screenY - pointer.lastY) : state(pointer.lastEvent, pointer, 0, 0);
-		stopTracking(pointerId);
-		opts.onDragEnd?.(finalState);
-	}
-	function stopTracking(pointerId) {
-		const pointer = pointers.get(pointerId);
-		if (!pointer) return;
-		pointers.delete(pointerId);
-		releaseTarget(pointer.moveTarget);
-		try {
-			if (capture.hasPointerCapture?.(pointerId) === true) capture.releasePointerCapture?.(pointerId);
-		} catch {}
-		if (lockedPointerId === pointerId) {
-			lockedPointerId = null;
-			const document = globalThis.document;
-			document?.removeEventListener("pointerlockchange", handleLockChange);
-			if (document?.pointerLockElement === element) document.exitPointerLock?.();
-		}
-		if (pointers.size > 0) return;
-		globalThis.document?.removeEventListener("selectstart", preventSelectStart);
-		if (previousCursor !== void 0 && style) {
-			style.cursor = previousCursor;
-			previousCursor = void 0;
-		}
-	}
-	element.addEventListener("pointerdown", handlePointerDown);
-	return {
-		update: (next) => {
-			opts = {
-				...opts,
-				...next,
-				multiPointer
-			};
-		},
-		destroy: () => {
-			if (destroyed) return;
-			destroyed = true;
-			element.removeEventListener("pointerdown", handlePointerDown);
-			for (const pointerId of [...pointers.keys()]) finishDrag(pointerId);
-			if (style && managedStyles && --managedStyles.count === 0) {
-				for (const [property] of MANAGED_STYLES) {
-					const previous = managedStyles.previous.get(property);
-					if (previous?.value) style.setProperty(property, previous.value, previous.priority);
-					else style.removeProperty(property);
-				}
-				managedStyleStates.delete(element);
-			}
-		}
-	};
+	return false;
 }
 //#endregion
 //#region src/piano/index.ts
@@ -1074,6 +750,11 @@ function createPianoInput(element, options) {
 	const held = /* @__PURE__ */ new Map();
 	/** The note each pointer is currently on. */
 	const pointerNotes = /* @__PURE__ */ new Map();
+	/**
+	* The note each held shortcut key is playing, by `code` — the physical key,
+	* so that releasing it with a different modifier or layout still matches.
+	*/
+	const shortcutNotes = /* @__PURE__ */ new Map();
 	function activeNotes() {
 		return [...held.keys()].sort((a, b) => a - b);
 	}
@@ -1116,6 +797,80 @@ function createPianoInput(element, options) {
 			noteOn(note, { source });
 		}
 	}
+	/** The note a shortcut key plays, or null when it has none. */
+	function shortcutNote(key) {
+		const keys = opts.keyboardShortcuts?.keys;
+		if (!keys || key === "") return null;
+		const { first, last } = opts.layout.noteRange;
+		const index = keys.indexOf(key);
+		const note = first + index;
+		return index === -1 || note > last ? null : note;
+	}
+	function onKeyDown(event) {
+		const id = event.code || event.key;
+		if (event.repeat || shortcutNotes.has(id)) return;
+		if (isEditableTarget(event.target)) return;
+		const note = shortcutNote(event.key);
+		if (note === null) return;
+		shortcutNotes.set(id, note);
+		noteOn(note, { source: `keyboard:${id}` });
+	}
+	function onKeyUp(event) {
+		const id = event.code || event.key;
+		const note = shortcutNotes.get(id);
+		if (note === void 0) return;
+		shortcutNotes.delete(id);
+		noteOff(note, { source: `keyboard:${id}` });
+	}
+	function releaseShortcuts() {
+		for (const [id, note] of shortcutNotes) noteOff(note, { source: `keyboard:${id}` });
+		shortcutNotes.clear();
+	}
+	function onFocusOut(event) {
+		const next = event.relatedTarget;
+		if (next instanceof Node && element.contains(next)) return;
+		releaseShortcuts();
+	}
+	/** The scope the listeners are bound for, or null when none are. */
+	let boundScope = null;
+	function bindShortcuts() {
+		const scope = opts.keyboardShortcuts ? opts.keyboardShortcutsScope ?? "root" : null;
+		if (scope === boundScope) return;
+		unbindShortcuts();
+		const win = globalThis.window;
+		if (!scope || !win) return;
+		const target = scope === "window" ? win : element;
+		target.addEventListener("keydown", onKeyDown);
+		target.addEventListener("keyup", onKeyUp);
+		if (scope === "root") element.addEventListener("focusout", onFocusOut);
+		win.addEventListener("blur", releaseShortcuts);
+		boundScope = scope;
+	}
+	function unbindShortcuts() {
+		const win = globalThis.window;
+		if (!boundScope || !win) return;
+		const target = boundScope === "window" ? win : element;
+		target.removeEventListener("keydown", onKeyDown);
+		target.removeEventListener("keyup", onKeyUp);
+		element.removeEventListener("focusout", onFocusOut);
+		win.removeEventListener("blur", releaseShortcuts);
+		boundScope = null;
+	}
+	/**
+	* What the held keys were started against. Compared by value: a caller
+	* who writes the keys inline hands over a new array on every update, and
+	* releasing on that would stop a note as soon as anything re-renders.
+	*/
+	function shortcutMapping() {
+		const { first, last } = opts.layout.noteRange;
+		return [
+			opts.keyboardShortcuts?.keys.join("\0") ?? "",
+			opts.keyboardShortcutsScope ?? "root",
+			first,
+			last
+		].join("
");
+	}
+	bindShortcuts();
 	const drag = createDrag(element, {
 		multiPointer: true,
 		onDragStart: (state) => movePointer(state.pointerId, noteUnder(state.clientX, state.clientY)),
@@ -1127,10 +882,13 @@ function createPianoInput(element, options) {
 	});
 	return {
 		update: (next) => {
+			const mapping = shortcutMapping();
 			opts = {
 				...opts,
 				...next
 			};
+			if (shortcutMapping() !== mapping) releaseShortcuts();
+			bindShortcuts();
 			const midiMax = opts.midiMax ?? 127;
 			const stoppedNotes = activeNotes().filter((note) => note > midiMax);
 			if (stoppedNotes.length === 0) return;
@@ -1146,6 +904,8 @@ function createPianoInput(element, options) {
 		activeNotes,
 		destroy: () => {
 			drag.destroy();
+			unbindShortcuts();
+			shortcutNotes.clear();
 			const notes = activeNotes();
 			for (const note of notes) {
 				held.delete(note);
@@ -1157,24 +917,6 @@ function createPianoInput(element, options) {
 	};
 }
 //#endregion
-//#region src/xy.ts
-function isPair(value) {
-	return Array.isArray(value);
-}
-/**
-* 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.
-*/
-function toXY(value) {
-	return isPair(value) ? [value[0], value[1]] : [value, value];
-}
-//#endregion
 //#region src/pointer/drag-value.ts
 /**
 * Map the pointer onto the bounding rect of an element: the value *is* the
@@ -1295,8 +1037,8 @@ function createDragValue(element, options) {
 			if (!position) return;
 			active = true;
 			lastValue = valueOf(position);
-			if (opts.updateOnPointerDown) opts.onChange?.(lastValue, state);
 			opts.onDragStart?.(lastValue, state);
+			if (opts.updateOnPointerDown) opts.onChange?.(lastValue, state);
 		},
 		onDrag: (state) => {
 			if (!active) return;
@@ -1335,6 +1077,73 @@ function createDragValue(element, options) {
 	};
 }
 //#endregion
+//#region src/pointer/long-press.ts
+/**
+* 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.
+*/
+function createLongPress(options) {
+	let opts = options;
+	let pointerId = null;
+	let active = false;
+	let timer = null;
+	function clearTimer() {
+		if (timer !== null) clearTimeout(timer);
+		timer = null;
+	}
+	/** Wait `wait`, fire, and keep going at `interval` from then on. */
+	function schedule(wait) {
+		timer = setTimeout(() => {
+			opts.onPress();
+			if (active) schedule(opts.interval ?? 40);
+		}, wait);
+	}
+	function onPointerEnd(event) {
+		if (pointerId !== null && event.pointerId !== pointerId) return;
+		stop();
+	}
+	function listen(add) {
+		const target = globalThis.window;
+		if (!target) return;
+		const method = add ? "addEventListener" : "removeEventListener";
+		target[method]("pointerup", onPointerEnd);
+		target[method]("pointercancel", onPointerEnd);
+		target[method]("blur", stop);
+	}
+	function stop() {
+		if (!active) return;
+		active = false;
+		pointerId = null;
+		clearTimer();
+		listen(false);
+	}
+	return {
+		start: (event) => {
+			if (active || event && event.button !== 0) return;
+			active = true;
+			pointerId = event?.pointerId ?? null;
+			listen(true);
+			opts.onPress();
+			if (active) schedule(opts.delay ?? 500);
+		},
+		stop,
+		update: (next) => {
+			opts = {
+				...opts,
+				...next
+			};
+		},
+		pressed: () => active,
+		destroy: stop
+	};
+}
+//#endregion
 //#region src/pointer/wheel.ts
 /**
 * Listen to wheel events on an element.
@@ -1342,18 +1151,15 @@ function createDragValue(element, options) {
 * The listener is registered with `passive: false` so that the handler can call
 * `preventDefault()` to stop the page from scrolling.
 */
-function createWheel(element, onWheel, options = {}) {
-	let opts = {
-		...options,
-		onWheel
-	};
+function createWheel(element, options) {
+	let opts = options;
 	function hasFocus() {
 		const active = element.ownerDocument?.activeElement;
 		return !!active && element.contains(active);
 	}
 	const handler = (event) => {
 		if (opts.requireFocus && !hasFocus()) return;
-		opts.onWheel?.(event);
+		opts.onWheel(event);
 	};
 	element.addEventListener("wheel", handler, { passive: false });
 	return {
@@ -1369,73 +1175,20 @@ function createWheel(element, onWheel, options = {}) {
 	};
 }
 //#endregion
-//#region src/selection/box.ts
-function rectOf(from, to) {
-	return {
-		x: Math.min(from[0], to[0]),
-		y: Math.min(from[1], to[1]),
-		width: Math.abs(to[0] - from[0]),
-		height: Math.abs(to[1] - from[1])
-	};
-}
-/** Whether the box covers the point, edges included. */
-function selectionBoxCovers(box, [x, y]) {
-	return x >= box.x && x <= box.x + box.width && y >= box.y && y <= box.y + box.height;
-}
+//#region src/position.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.
 */
-function createSelectionBox(options) {
-	let opts = options;
-	let drag = null;
-	let box = null;
-	function setBox(next) {
-		box = next;
-		opts.onBoxChange?.(next);
-	}
-	function apply(rect, base) {
-		const inside = [];
-		for (const [id, at] of opts.items()) if (selectionBoxCovers(rect, at) && !base.includes(id)) inside.push(id);
-		opts.onSelectionChange?.([...base, ...inside]);
-	}
-	return {
-		update: (next) => {
-			opts = {
-				...opts,
-				...next
-			};
-		},
-		begin: (at, { additive = false, selection = [] } = {}) => {
-			drag = {
-				from: at,
-				base: additive ? [...selection] : []
-			};
-			setBox(rectOf(at, at));
-			if (!additive) opts.onSelectionChange?.([]);
-		},
-		move: (to) => {
-			if (!drag) return;
-			const rect = rectOf(drag.from, to);
-			setBox(rect);
-			apply(rect, drag.base);
-		},
-		end: () => {
-			const running = drag !== null;
-			drag = null;
-			if (box !== null) setBox(null);
-			return running;
-		},
-		box: () => box,
-		destroy: () => {
-			drag = null;
-			box = null;
-		}
-	};
+function valuePercent(value, { min, max, scale = linearScale }, reversed = false) {
+	const normalized = scale.normalize(value, min, max);
+	return toFixed((reversed ? 1 - normalized : normalized) * 100);
 }
 //#endregion
-export { NOT_SUPPORTED, PERMISSION_DENIED, PITCH_BEND_CENTER, UNAVAILABLE, applyDelta, blackKeyWidth, createAnimationCanvas, createDrag, createDragValue, createDropZone, createMIDIAccess, createMIDIInput, createMIDIMessage, createPianoInput, createSelectionBox, createWheel, drawingState, elementMapping, getNoteRangeArray, isDrawingState, mapModifier, matchesAccept, noteAt, notePosition, pianoWidth, relativeMapping, selectModifier, selectionBoxCovers, toXY };
+export { DEFAULT_DRAG_SENSITIVITY, DEFAULT_KEYBOARD_OPTIONS, DEFAULT_WHEEL_OPTIONS, KNOB_VIEWBOX_SIZE, SHORTCUTS, createAnimationCanvas, createChangeGesture, createDrag, createDragValue, createDropZone, createLongPress, createMIDIAccess, createMIDIInput, createMIDIMessage, createPianoInput, createPointsEditor, createWheel, elementMapping, knobAngles, knobArcPath, knobArcRadius, notePosition, relativeMapping, valuePercent };
 
 //# sourceMappingURL=index.js.map