@tremolo-ui/dom 0.6.0 → 0.7.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { clamp, linearScale, normalizeValue, noteAt, stepValue, toPrecision } from "@tremolo-ui/functions";
+import { clamp, isBlackKey, isWhiteKey, linearScale, normalizeValue, noteKey, noteKeys, stepValue, toPrecision } from "@tremolo-ui/functions";
 //#region src/canvas/context.ts
 /**
 * The assignable parts of a 2D context's drawing state. They have to be
@@ -235,6 +235,271 @@ 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.
+*
+* ```ts
+* const zone = createDropZone(element, {
+*   accept: 'audio/*',
+*   onDrop: (files) => load(files[0]),
+* })
+* ```
+*
+* The element needs no attribute of its own: a drop target is made by
+* cancelling `dragover`, which this does.
+*/
+function createDropZone(element, options = {}) {
+	let opts = options;
+	let state = {
+		over: false,
+		invalid: false
+	};
+	/**
+	* `dragenter` and `dragleave` fire for descendants too, so moving between
+	* two children of the zone leaves before it enters. Counting the pairs is
+	* what keeps the state from flickering off in the middle of the element.
+	*/
+	let depth = 0;
+	function setState(next) {
+		if (next.over === state.over && next.invalid === state.invalid) return;
+		state = next;
+		opts.onStateChange?.(state);
+	}
+	function carriesFiles(transfer) {
+		return !!transfer?.types.includes("Files");
+	}
+	/** Whether anything being dragged could still be accepted. */
+	function anyAcceptable(transfer) {
+		const items = Array.from(transfer?.items ?? []).filter((item) => item.kind === "file");
+		if (items.length === 0) return true;
+		return items.some((item) => matchesAccept({ type: item.type }, opts.accept));
+	}
+	function onDragEnter(event) {
+		if (!carriesFiles(event.dataTransfer)) return;
+		event.preventDefault();
+		depth += 1;
+		setState({
+			over: true,
+			invalid: !anyAcceptable(event.dataTransfer)
+		});
+	}
+	function onDragOver(event) {
+		if (!carriesFiles(event.dataTransfer)) return;
+		event.preventDefault();
+		if (event.dataTransfer) event.dataTransfer.dropEffect = opts.disabled || state.invalid ? "none" : "copy";
+		if (!state.over) {
+			depth = Math.max(depth, 1);
+			setState({
+				over: true,
+				invalid: !anyAcceptable(event.dataTransfer)
+			});
+		}
+	}
+	function onDragLeave(event) {
+		if (!carriesFiles(event.dataTransfer)) return;
+		depth = Math.max(0, depth - 1);
+		if (depth === 0) setState({
+			over: false,
+			invalid: false
+		});
+	}
+	function onDrop(event) {
+		if (!carriesFiles(event.dataTransfer)) return;
+		event.preventDefault();
+		depth = 0;
+		setState({
+			over: false,
+			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 taken = opts.multiple ? accepted : accepted.slice(0, 1);
+		if (taken.length > 0) opts.onDrop?.(taken, event);
+	}
+	/**
+	* A drag that ends anywhere else — dropped on another element, cancelled
+	* with Esc, taken out of the window — sends no `dragleave` here, and the
+	* element would stay marked as a drop target for good.
+	*/
+	function onDragEndAnywhere() {
+		depth = 0;
+		setState({
+			over: false,
+			invalid: false
+		});
+	}
+	const handlers = {
+		dragenter: onDragEnter,
+		dragover: onDragOver,
+		dragleave: onDragLeave,
+		drop: onDrop
+	};
+	for (const [type, handler] of Object.entries(handlers)) element.addEventListener(type, handler);
+	const doc = element.ownerDocument;
+	doc?.addEventListener("dragend", onDragEndAnywhere);
+	doc?.addEventListener("drop", onDragEndAnywhere);
+	return {
+		get state() {
+			return state;
+		},
+		update: (next) => {
+			opts = {
+				...opts,
+				...next
+			};
+		},
+		destroy: () => {
+			for (const [type, handler] of Object.entries(handlers)) element.removeEventListener(type, handler);
+			doc?.removeEventListener("dragend", onDragEndAnywhere);
+			doc?.removeEventListener("drop", onDragEndAnywhere);
+		}
+	};
+}
+//#endregion
+//#region src/input/modifiers.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.
+*/
+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;
+}
+/**
+* Pick the setting that applies, given the modifier keys being held.
+*
+* @example
+* selectModifier({ default: 1, shift: 0.1 }, event)
+*/
+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
+		};
+	}
+	return {
+		value: options.default,
+		modifier: null
+	};
+}
+/**
+* Turn every entry of a setting into another kind of setting, keeping which
+* modifier each belongs to.
+*
+* A drag sensitivity is a number and a keyboard amount is a tuple, but the two
+* describe the same thing from the caller's side. This carries one over to the
+* other so that a component can hand a sensitivity to {@link applyDelta}
+* without unpicking the modifier map itself — which matters, since naming a
+* modifier is also what takes `step` out of the pipeline.
+*
+* @example
+* mapModifier({ default: 1, shift: 0.1 }, (f) => ['raw', step * f])
+* // { default: ['raw', 1], shift: ['raw', 0.1] }
+*/
+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;
+}
+//#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)
+*/
+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);
+}
+//#endregion
 //#region src/midi/access.ts
 /** @private */
 const PERMISSION_DENIED = "PERMISSION_DENIED";
@@ -448,6 +713,113 @@ 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;
+/**
+* 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.
+*/
+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
+};
+/** 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.
@@ -1064,6 +1436,6 @@ function createSelectionBox(options) {
 	};
 }
 //#endregion
-export { NOT_SUPPORTED, PERMISSION_DENIED, PITCH_BEND_CENTER, UNAVAILABLE, createAnimationCanvas, createDrag, createDragValue, createMIDIAccess, createMIDIInput, createMIDIMessage, createPianoInput, createSelectionBox, createWheel, drawingState, elementMapping, isDrawingState, relativeMapping, selectionBoxCovers, toXY };
+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 };
 
 //# sourceMappingURL=index.js.map