@tremolo-ui/dom 0.4.0 → 0.5.0

package/dist/index.js

@@ -1,3 +1,219 @@
+import { clamp, linearScale, normalizeValue, noteAt, stepValue } from "@tremolo-ui/functions";
+//#region src/canvas/context.ts
+/**
+* The properties of a 2D context that survive `save()` / `restore()`, and so
+* are what has to be carried across a resize by hand: setting `canvas.width`
+* resets the context to its defaults.
+*
+* @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/save
+*/
+const drawingState = [
+	"strokeStyle",
+	"fillStyle",
+	"globalAlpha",
+	"lineWidth",
+	"lineCap",
+	"lineJoin",
+	"miterLimit",
+	"lineDashOffset",
+	"shadowOffsetX",
+	"shadowOffsetY",
+	"shadowBlur",
+	"shadowColor",
+	"globalCompositeOperation",
+	"font",
+	"textAlign",
+	"textBaseline",
+	"direction",
+	"imageSmoothingEnabled"
+];
+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 = {};
+	for (const property of drawingState) state[property] = context[property];
+	return state;
+}
+/** Put a state read by {@link readDrawingState} back onto a context. */
+function writeDrawingState(context, state) {
+	for (const property of drawingState) context[property] = state[property];
+}
+/**
+* Give the canvas a backing store of `width * dpr` by `height * dpr` device
+* pixels while keeping it `width` by `height` in CSS pixels, and scale the
+* context so that drawing code can work in CSS pixels throughout.
+*
+* Assigning to `canvas.width` clears the canvas and resets the context, so
+* this both resizes and re-establishes the transform.
+*/
+function applyDevicePixelRatio(canvas, context, width, height, dpr) {
+	canvas.width = width * dpr;
+	canvas.height = height * dpr;
+	context.setTransform(1, 0, 0, 1, 0, 0);
+	context.scale(dpr, dpr);
+	canvas.style.width = `${width}px`;
+	canvas.style.height = `${height}px`;
+}
+//#endregion
+//#region src/canvas/animation.ts
+/**
+* Drive a canvas from `requestAnimationFrame`, keeping its backing store in
+* step with the device pixel ratio and, optionally, with the size of its
+* parent.
+*
+* Drawing code works in CSS pixels: the context is scaled by the device pixel
+* ratio, and `width` / `height` of each {@link AnimationFrame} are CSS pixels.
+*/
+function createAnimationCanvas(canvas, options) {
+	let opts = options;
+	const context2d = canvas.getContext("2d", opts.contextAttributes);
+	if (!context2d) throw new Error("createAnimationCanvas: cannot get a 2d context");
+	const context = context2d;
+	const relativeSize = opts.relativeSize ?? false;
+	/** Off-document canvas holding the drawing while the real one is resized. */
+	let memo = null;
+	let memoContext = null;
+	let width = 0;
+	let height = 0;
+	/** Whether a size has been applied, so a frame can be drawn. */
+	let sized = false;
+	let initialized = false;
+	let frameId = null;
+	let count = -1;
+	const startTime = performance.now();
+	let previousTime = startTime;
+	function devicePixelRatio() {
+		return globalThis.devicePixelRatio || 1;
+	}
+	/**
+	* Copy the canvas onto the memo canvas at its full device resolution, 1:1.
+	*
+	* Assigning to `memo.width` resets the memo's transform to the identity, so
+	* the copy neither scales nor resamples.
+	*/
+	function takeSnapshot() {
+		if (!(opts.reduceFlickering ?? true)) return null;
+		if (!memo) {
+			memo = globalThis.document?.createElement("canvas") ?? null;
+			memoContext = memo?.getContext("2d", opts.contextAttributes) ?? null;
+		}
+		if (!memo || !memoContext) return null;
+		const state = readDrawingState(context);
+		memo.width = canvas.width;
+		memo.height = canvas.height;
+		if (canvas.width > 0 && canvas.height > 0) memoContext.drawImage(canvas, 0, 0);
+		return state;
+	}
+	/**
+	* Put the snapshot back, given the size in CSS pixels it was taken at.
+	*
+	* The context is scaled to CSS pixels, so drawing the snapshot at its old
+	* CSS size leaves it exactly where it was. While the device pixel ratio
+	* stays put that is a 1:1 copy of device pixels, and when it changes the
+	* snapshot is rescaled once, from its full resolution.
+	*/
+	function restoreSnapshot(state, previousWidth, previousHeight) {
+		if (!state || !memo || !memoContext) return;
+		if (memo.width <= 0 || memo.height <= 0) return;
+		writeDrawingState(context, state);
+		context.drawImage(memo, 0, 0, previousWidth, previousHeight);
+	}
+	function applySize(w, h) {
+		const dpr = devicePixelRatio();
+		const previousWidth = width;
+		const previousHeight = height;
+		const state = takeSnapshot();
+		applyDevicePixelRatio(canvas, context, w, h, dpr);
+		width = w;
+		height = h;
+		sized = true;
+		restoreSnapshot(state, previousWidth, previousHeight);
+	}
+	function drawFrame() {
+		if (!sized) return;
+		if (!initialized) {
+			initialized = true;
+			opts.init?.(context, {
+				width,
+				height
+			});
+		}
+		const now = performance.now();
+		const deltaTime = now - previousTime;
+		previousTime = now;
+		count += 1;
+		opts.draw(context, {
+			width,
+			height,
+			count,
+			deltaTime,
+			elapsedTime: now - startTime,
+			fps: 1e3 / deltaTime
+		});
+	}
+	function tick() {
+		frameId = requestAnimationFrame(tick);
+		drawFrame();
+	}
+	function startLoop() {
+		if (frameId != null) return;
+		previousTime = performance.now();
+		frameId = requestAnimationFrame(tick);
+	}
+	function stopLoop() {
+		if (frameId == null) return;
+		cancelAnimationFrame(frameId);
+		frameId = null;
+	}
+	let observer = null;
+	if (relativeSize) {
+		const parent = canvas.parentElement;
+		if (!parent) throw new Error("createAnimationCanvas: relativeSize needs the canvas to have a parent element");
+		observer = new ResizeObserver((entries) => {
+			for (const entry of entries) {
+				const { width: w, height: h } = entry.contentRect;
+				applySize(w, h);
+				if (!(opts.animate ?? true)) drawFrame();
+			}
+		});
+		observer.observe(parent);
+	} else {
+		const { width: w = 100, height: h = 100 } = opts.size ?? {};
+		applySize(w, h);
+	}
+	if (opts.animate ?? true) startLoop();
+	else if (sized) drawFrame();
+	return {
+		update: (next) => {
+			const wasAnimating = opts.animate ?? true;
+			opts = {
+				...opts,
+				...next,
+				relativeSize,
+				contextAttributes: opts.contextAttributes
+			};
+			if (!relativeSize) {
+				const { width: w = 100, height: h = 100 } = opts.size ?? {};
+				if (w != width || h != height) applySize(w, h);
+			}
+			const animating = opts.animate ?? true;
+			if (animating && !wasAnimating) startLoop();
+			if (!animating && wasAnimating) stopLoop();
+			if (!animating) drawFrame();
+		},
+		redraw: drawFrame,
+		destroy: () => {
+			stopLoop();
+			observer?.disconnect();
+			observer = null;
+			memo = null;
+			memoContext = null;
+		}
+	};
+}
+//#endregion
 //#region src/midi/access.ts
 /** @private */
 const PERMISSION_DENIED = "PERMISSION_DENIED";
@@ -118,9 +334,12 @@ const MANAGED_STYLES = [
 * 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}.
 */
-function createDrag(element, { threshold: _threshold = 1, cursor, onDragStart, onDrag, onDragEnd } = {}) {
-	const threshold = Math.max(_threshold, 1);
+function createDrag(element, options = {}) {
+	let opts = options;
+	const multiPointer = options.multiPointer ?? false;
 	const capture = element;
 	const style = element.style;
 	const previousStyles = /* @__PURE__ */ new Map();
@@ -128,22 +347,23 @@ function createDrag(element, { threshold: _threshold = 1, cursor, onDragStart, o
 		previousStyles.set(property, style.getPropertyValue(property));
 		style.setProperty(property, value);
 	}
-	let pointerId = null;
-	/** Where the listeners for the current drag live. */
-	let moveTarget = null;
-	let startX = 0;
-	let startY = 0;
-	let lastX = 0;
-	let lastY = 0;
+	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;
-	function state(event, deltaX, deltaY) {
+	function state(event, pointer, deltaX, deltaY) {
 		return {
-			x: event.screenX - startX,
-			y: event.screenY - startY,
+			x: event.screenX - pointer.startX,
+			y: event.screenY - pointer.startY,
 			deltaX,
 			deltaY,
 			clientX: event.clientX,
 			clientY: event.clientY,
+			pointerId: event.pointerId,
 			event
 		};
 	}
@@ -155,65 +375,307 @@ function createDrag(element, { threshold: _threshold = 1, cursor, onDragStart, o
 	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);
+		}
+		targets.set(target, count + 1);
+	}
+	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);
+		targets.delete(target);
+	}
 	function handlePointerDown(event) {
 		const pointerEvent = event;
-		if (pointerId !== null) return;
-		pointerId = pointerEvent.pointerId;
-		startX = lastX = pointerEvent.screenX;
-		startY = lastY = pointerEvent.screenY;
-		if (cursor && style) {
+		const pointerId = pointerEvent.pointerId;
+		if (pointers.has(pointerId)) return;
+		if (!multiPointer && pointers.size > 0) return;
+		const isFirst = pointers.size === 0;
+		if (isFirst && opts.cursor && style) {
 			previousCursor = style.cursor;
-			style.cursor = cursor;
+			style.cursor = opts.cursor;
 		}
 		capture.setPointerCapture?.(pointerId);
-		moveTarget = capture.hasPointerCapture?.(pointerId) === true ? element : globalThis.window ?? element;
-		moveTarget.addEventListener("pointermove", handlePointerMove);
-		moveTarget.addEventListener("pointerup", handlePointerUp);
-		moveTarget.addEventListener("pointercancel", handlePointerUp);
-		globalThis.document?.addEventListener("selectstart", preventSelectStart);
-		onDragStart?.(state(pointerEvent, 0, 0));
+		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
+		};
+		pointers.set(pointerId, pointer);
+		retainTarget(moveTarget);
+		if (isFirst) globalThis.document?.addEventListener("selectstart", preventSelectStart);
+		opts.onDragStart?.(state(pointerEvent, pointer, 0, 0));
 	}
 	function handlePointerMove(event) {
 		const pointerEvent = event;
-		if (pointerEvent.pointerId !== pointerId) return;
-		const deltaX = pointerEvent.screenX - lastX;
-		const deltaY = pointerEvent.screenY - lastY;
-		lastX = pointerEvent.screenX;
-		lastY = pointerEvent.screenY;
+		const pointer = pointers.get(pointerEvent.pointerId);
+		if (!pointer) return;
+		const deltaX = pointerEvent.screenX - pointer.lastX;
+		const deltaY = pointerEvent.screenY - pointer.lastY;
+		const threshold = opts.threshold ?? 0;
 		if (Math.abs(deltaX) < threshold && Math.abs(deltaY) < threshold) return;
-		onDrag?.(state(pointerEvent, deltaX, deltaY));
+		pointer.lastX = pointerEvent.screenX;
+		pointer.lastY = pointerEvent.screenY;
+		opts.onDrag?.(state(pointerEvent, pointer, deltaX, deltaY));
 	}
 	function handlePointerUp(event) {
 		const pointerEvent = event;
-		if (pointerEvent.pointerId !== pointerId) return;
-		const finalState = state(pointerEvent, pointerEvent.screenX - lastX, pointerEvent.screenY - lastY);
-		stopTracking();
-		onDragEnd?.(finalState);
+		const pointer = pointers.get(pointerEvent.pointerId);
+		if (!pointer) return;
+		const finalState = state(pointerEvent, pointer, pointerEvent.screenX - pointer.lastX, pointerEvent.screenY - pointer.lastY);
+		stopTracking(pointerEvent.pointerId);
+		opts.onDragEnd?.(finalState);
 	}
-	function stopTracking() {
-		if (pointerId === null) return;
+	function stopTracking(pointerId) {
+		const pointer = pointers.get(pointerId);
+		if (!pointer) return;
 		capture.releasePointerCapture?.(pointerId);
-		moveTarget?.removeEventListener("pointermove", handlePointerMove);
-		moveTarget?.removeEventListener("pointerup", handlePointerUp);
-		moveTarget?.removeEventListener("pointercancel", handlePointerUp);
+		releaseTarget(pointer.moveTarget);
+		pointers.delete(pointerId);
+		if (pointers.size > 0) return;
 		globalThis.document?.removeEventListener("selectstart", preventSelectStart);
-		if (cursor && style) {
-			style.cursor = previousCursor ?? "";
+		if (previousCursor !== void 0 && style) {
+			style.cursor = previousCursor;
 			previousCursor = void 0;
 		}
-		moveTarget = null;
-		pointerId = null;
 	}
 	element.addEventListener("pointerdown", handlePointerDown);
-	return { destroy: () => {
-		stopTracking();
-		element.removeEventListener("pointerdown", handlePointerDown);
-		if (style) for (const [property] of MANAGED_STYLES) {
-			const previous = previousStyles.get(property);
-			if (previous) style.setProperty(property, previous);
-			else style.removeProperty(property);
+	return {
+		update: (next) => {
+			opts = {
+				...opts,
+				...next,
+				multiPointer
+			};
+		},
+		destroy: () => {
+			for (const pointerId of [...pointers.keys()]) stopTracking(pointerId);
+			element.removeEventListener("pointerdown", handlePointerDown);
+			if (style) for (const [property] of MANAGED_STYLES) {
+				const previous = previousStyles.get(property);
+				if (previous) style.setProperty(property, previous);
+				else style.removeProperty(property);
+			}
+		}
+	};
+}
+//#endregion
+//#region src/piano/input.ts
+const DEFAULT_SOURCE = "api";
+/**
+* Drive a piano keyboard with pointers, and own what is sounding.
+*
+* Every way of playing a note goes through the one instance — pointers here,
+* keyboard shortcuts and MIDI through {@link PianoInputInstance.noteOn} — so
+* there is a single answer to what is currently held, and drawing the keys is
+* left entirely to the wrapper.
+*
+* Tracks every pointer at once, so a chord can be played with several fingers.
+*/
+function createPianoInput(element, options) {
+	let opts = options;
+	/** Which sources are holding each sounding note. */
+	const held = /* @__PURE__ */ new Map();
+	/** The note each pointer is currently on. */
+	const pointerNotes = /* @__PURE__ */ new Map();
+	function activeNotes() {
+		return [...held.keys()].sort((a, b) => a - b);
+	}
+	function noteOn(note, { source = DEFAULT_SOURCE, velocity } = {}) {
+		if (note > (opts.midiMax ?? 127)) return;
+		const sources = held.get(note);
+		if (sources) {
+			sources.add(source);
+			return;
+		}
+		held.set(note, new Set([source]));
+		opts.onPlayNote?.(note, velocity);
+		opts.onActiveNotesChange?.(activeNotes());
+	}
+	function noteOff(note, { source = DEFAULT_SOURCE } = {}) {
+		const sources = held.get(note);
+		if (!sources) return;
+		sources.delete(source);
+		if (sources.size > 0) return;
+		held.delete(note);
+		opts.onStopNote?.(note);
+		opts.onActiveNotesChange?.(activeNotes());
+	}
+	/** The note under a pointer, or null where the pointer is off the keys. */
+	function noteUnder(clientX, clientY) {
+		const { left, top, height } = element.getBoundingClientRect();
+		return noteAt(clientX - left, clientY - top, height, opts.layout);
+	}
+	/** Move a pointer onto a note, releasing whatever it held before. */
+	function movePointer(pointerId, note) {
+		const source = `pointer:${pointerId}`;
+		const previous = pointerNotes.get(pointerId);
+		if (previous === note) return;
+		if (previous !== void 0) noteOff(previous, { source });
+		if (note === null) pointerNotes.delete(pointerId);
+		else {
+			pointerNotes.set(pointerId, note);
+			noteOn(note, { source });
+		}
+	}
+	const drag = createDrag(element, {
+		multiPointer: true,
+		onDragStart: (state) => movePointer(state.pointerId, noteUnder(state.clientX, state.clientY)),
+		onDrag: (state) => {
+			if (opts.glissando === false) return;
+			movePointer(state.pointerId, noteUnder(state.clientX, state.clientY));
+		},
+		onDragEnd: (state) => movePointer(state.pointerId, null)
+	});
+	return {
+		update: (next) => {
+			opts = {
+				...opts,
+				...next
+			};
+		},
+		noteOn,
+		noteOff,
+		activeNotes,
+		destroy: () => {
+			drag.destroy();
+			for (const note of activeNotes()) {
+				held.delete(note);
+				opts.onStopNote?.(note);
+			}
+			pointerNotes.clear();
+			opts.onActiveNotesChange?.([]);
 		}
+	};
+}
+//#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/dragValue.ts
+/**
+* Map the pointer onto the bounding rect of an element: the value *is* the
+* position pointed at, so the middle of the element is 0.5.
+*
+* The element is read on every event, so it may be mounted after the drag is
+* set up and may change size while a drag is in progress.
+*/
+function elementMapping(getElement) {
+	function positionIn(state) {
+		const element = getElement();
+		if (!element) return null;
+		const { left, top, right, bottom } = element.getBoundingClientRect();
+		return [right > left ? normalizeValue(state.clientX, left, right) : 0, bottom > top ? normalizeValue(state.clientY, top, bottom) : 0];
+	}
+	return {
+		start: positionIn,
+		move: positionIn
+	};
+}
+/**
+* Move the value away from where it stood when the drag started, by the
+* distance dragged. The pointer position itself carries no meaning, so the
+* value can be adjusted from anywhere on the screen.
+*/
+function relativeMapping({ pixelRange = 100 } = {}) {
+	const [rangeX, rangeY] = toXY(pixelRange);
+	let origin = [0, 0];
+	return {
+		start: (_state, context) => {
+			origin = context.position();
+			return origin;
+		},
+		move: (state) => [origin[0] + state.x / rangeX, origin[1] + state.y / rangeY]
+	};
+}
+/**
+* Drive a value with a pointer drag.
+*
+* Combines {@link createDrag} with the scaling of `@tremolo-ui/functions`: the
+* mapping decides where the pointer sits on the 0-1 travel of each axis, and
+* the axis options turn that into a value.
+*/
+function createDragValue(element, options) {
+	let opts = options;
+	let lastValue = [0, 0];
+	const axes = () => toXY(opts.axis);
+	function valueOf(position) {
+		return axes().map((axis, i) => {
+			const p = axis.reverse ? 1 - position[i] : position[i];
+			const value = (axis.scale ?? linearScale).denormalize(p, axis.min, axis.max);
+			return clamp(axis.step ? stepValue(value, axis.step) : value, axis.min, axis.max);
+		});
+	}
+	const context = { position: () => {
+		const getValue = opts.getValue;
+		if (!getValue) throw new Error("createDragValue: getValue is required by the given mapping");
+		const value = getValue();
+		return axes().map((axis, i) => {
+			const n = (axis.scale ?? linearScale).normalize(value[i], axis.min, axis.max);
+			return axis.reverse ? 1 - n : n;
+		});
 	} };
+	const drag = createDrag(element, {
+		threshold: opts.threshold,
+		cursor: opts.cursor,
+		onDragStart: (state) => {
+			const position = opts.mapping.start(state, context);
+			if (position) {
+				lastValue = valueOf(position);
+				if (opts.updateOnPointerDown) opts.onChange?.(lastValue, state);
+			}
+			opts.onDragStart?.(lastValue, state);
+		},
+		onDrag: (state) => {
+			const position = opts.mapping.move(state, context);
+			if (!position) return;
+			lastValue = valueOf(position);
+			opts.onChange?.(lastValue, state);
+		},
+		onDragEnd: (state) => opts.onDragEnd?.(lastValue, state)
+	});
+	return {
+		update: (next) => {
+			opts = {
+				...opts,
+				...next,
+				mapping: opts.mapping
+			};
+			drag.update({
+				threshold: opts.threshold,
+				cursor: opts.cursor
+			});
+		},
+		destroy: () => drag.destroy()
+	};
 }
 //#endregion
 //#region src/pointer/wheel.ts
@@ -223,14 +685,30 @@ function createDrag(element, { threshold: _threshold = 1, cursor, onDragStart, o
 * The listener is registered with `passive: false` so that the handler can call
 * `preventDefault()` to stop the page from scrolling.
 */
-function createWheel(element, onWheel) {
-	const handler = (event) => onWheel(event);
+function createWheel(element, onWheel, options = {}) {
+	let opts = options;
+	function hasFocus() {
+		const active = element.ownerDocument?.activeElement;
+		return !!active && element.contains(active);
+	}
+	const handler = (event) => {
+		if (opts.requireFocus && !hasFocus()) return;
+		onWheel(event);
+	};
 	element.addEventListener("wheel", handler, { passive: false });
-	return { destroy: () => {
-		element.removeEventListener("wheel", handler);
-	} };
+	return {
+		update: (next) => {
+			opts = {
+				...opts,
+				...next
+			};
+		},
+		destroy: () => {
+			element.removeEventListener("wheel", handler);
+		}
+	};
 }
 //#endregion
-export { NOT_SUPPORTED, PERMISSION_DENIED, createDrag, createMIDIAccess, createMIDIInput, createMIDIMessage, createWheel };
+export { NOT_SUPPORTED, PERMISSION_DENIED, createAnimationCanvas, createDrag, createDragValue, createMIDIAccess, createMIDIInput, createMIDIMessage, createPianoInput, createWheel, drawingState, elementMapping, isDrawingState, relativeMapping, toXY };
 
 //# sourceMappingURL=index.js.map