@xsynaptic/sonic-ui 0.25.1 → 0.27.0

package/dist/default/elements/sonic-element.js

@@ -8,7 +8,6 @@ const namingAttributes = [
 	"aria-label",
 	"aria-labelledby"
 ];
-const canMatchStates = CSS.supports("selector(:state(a))");
 const canReferElements = "ariaLabelledByElements" in Element.prototype;
 function writeLabelledBy(target, labels) {
 	const current = target.ariaLabelledByElements;
@@ -26,7 +25,6 @@ var SonicElement = class SonicElement extends HTMLElement {
 	}
 	internals = "attachInternals" in HTMLElement.prototype ? this.attachInternals() : void 0;
 	#connection;
-	#customStates = canMatchStates ? this.internals?.states : void 0;
 	#states = /* @__PURE__ */ new Set();
 	static #labelId(label) {
 		if (label.id === "") {
@@ -50,6 +48,7 @@ var SonicElement = class SonicElement extends HTMLElement {
 			this.#connection = void 0;
 			throw error;
 		}
+		const { boxProbe: box, control, sheet } = this;
 	}
 	connectedMoveCallback() {}
 	disconnectedCallback() {
@@ -69,7 +68,6 @@ var SonicElement = class SonicElement extends HTMLElement {
 		}
 		if (!this.isDisabled() && !this.#focused()) target.focus(options);
 	}
-	checkStyles(control, sheet, box) {}
 	focusTarget() {}
 	forwardNaming(target, isNamed) {
 		const labels = isNamed ? this.namingLabels() : [];
@@ -89,7 +87,9 @@ var SonicElement = class SonicElement extends HTMLElement {
 	isDisabled() {
 		return this.disabled || this.matches(":disabled");
 	}
-	keepControl(control, signal) {
+	keepControl(signal) {
+		const control = this.control;
+		if (!control) return;
 		const keep = () => {
 			appendOnce(this, control);
 		};
@@ -118,14 +118,13 @@ var SonicElement = class SonicElement extends HTMLElement {
 		}
 		this.setAttribute(name, value === true ? "" : value.toString());
 	}
+	stateTarget() {
+		return this.control;
+	}
 	toggleState(state, isOn) {
-		if (isOn) {
-			this.#states.add(state);
-			this.#customStates?.add(state);
-			return;
-		}
-		this.#states.delete(state);
-		this.#customStates?.delete(state);
+		if (isOn) this.#states.add(state);
+		else this.#states.delete(state);
+		this.stateTarget()?.toggleAttribute(`data-sonic-${state}`, isOn);
 	}
 	upgradeProperties(...names) {
 		for (const name of names) {
@@ -138,8 +137,6 @@ var SonicElement = class SonicElement extends HTMLElement {
 	usesChild(_child) {
 		return false;
 	}
-	#checkBox(control, checked, box) {}
-	#checkHost(checked) {}
 	#focused() {
 		const root = this.getRootNode();
 		const active = root instanceof ShadowRoot ? root.activeElement : this.ownerDocument.activeElement;

package/dist/default/elements/spectrum.js

@@ -1,5 +1,5 @@
 import { requireChild, template } from "../lib/render.js";
-import { SonicDisplayElement } from "./display-element.js";
+import { SonicAnalyserElement } from "./analyser-element.js";
 import { columnEdges, columnLevels, gridColumns, gridRows, levelRows, loudestBin, zoneRows } from "../lib/spectrum-columns.js";
 import { areSettled, createLevels, receiveLevels, stepLevels } from "../lib/spectrum-levels.js";
 
@@ -71,9 +71,9 @@ function paintHolds(context, { look, rowOf }, { bars, holds }) {
 	context.fillStyle = look.colours.lit;
 	context.fill();
 }
-var SonicSpectrum = class extends SonicDisplayElement {
+var SonicSpectrum = class extends SonicAnalyserElement {
 	static observedAttributes = [
-		...SonicDisplayElement.observedAttributes,
+		...SonicAnalyserElement.observedAttributes,
 		"frequency-max",
 		"frequency-min",
 		"grid",

package/dist/default/elements/switch.js

@@ -20,20 +20,25 @@ const renderBare = template(`<button class="sonic-switch-position" role="switch"
 const pressCenterZone = .08;
 var SonicSwitch = class extends SonicPositionGroupElement {
 	bare = renderBare();
+	boxProbe = {
+		property: "padding-top",
+		selector: ".sonic-switch-label"
+	};
+	control = renderSwitch();
 	defaultOrientation = "vertical";
-	group = renderSwitch();
-	#bat = requireChild(this.group, ".sonic-switch-bat", HTMLSpanElement);
+	sheet = "switch.css";
+	#bat = requireChild(this.control, ".sonic-switch-bat", HTMLSpanElement);
 	#isClickSwallowed = false;
 	claimPress(index, event) {
 		if (this.#isOnBat(event)) return true;
 		const target = this.pressTarget(index);
 		if (this.isOptionDisabled(target) || !this.isMomentary(target)) return false;
-		capturePointer(this.group, event.pointerId);
+		capturePointer(this.control, event.pointerId);
 		this.hold(target, event.pointerId);
 		return true;
 	}
 	connect(signal) {
-		const group = this.group;
+		const group = this.control;
 		super.connect(signal);
 		this.bare.addEventListener("click", (event) => {
 			const isSwallowed = this.#isClickSwallowed && event instanceof PointerEvent && event.pointerType !== "";
@@ -70,7 +75,7 @@ var SonicSwitch = class extends SonicPositionGroupElement {
 			lift: (press, event) => {
 				this.#isClickSwallowed = true;
 				if (press.hasMoved || this.isDisabled()) return;
-				if (!isUnder(this.group, event.clientX, event.clientY)) return;
+				if (!isUnder(this.control, event.clientX, event.clientY)) return;
 				this.#pressBat(event);
 			},
 			move: (press, event) => {
@@ -101,7 +106,7 @@ var SonicSwitch = class extends SonicPositionGroupElement {
 	#renderThrow(index) {
 		const count = this.positions().length;
 		const at = index < 0 || count < 2 ? 0 : 2 * index / (count - 1) - 1;
-		this.group.style.setProperty("--_sonic-switch-at", String(at));
+		this.control.style.setProperty("--_sonic-switch-at", String(at));
 	}
 	#sideStep(from, event) {
 		const box = this.#bat.getBoundingClientRect();

package/dist/default/elements/toggle.js

@@ -22,12 +22,18 @@ const renderBare = template(`<button class="sonic-toggle-position" role="switch"
 const pressTolerance = 2;
 var SonicToggle = class extends SonicPositionGroupElement {
 	bare = renderBare();
+	boxProbe = {
+		property: "margin-top",
+		ratio: "--_sonic-toggle-gap-ratio",
+		selector: ".sonic-toggle-cap"
+	};
+	control = renderToggle();
 	defaultOrientation = "horizontal";
-	group = renderToggle();
-	#cap = requireChild(this.group, ".sonic-toggle-cap", HTMLSpanElement);
+	sheet = "toggle.css";
+	#cap = requireChild(this.control, ".sonic-toggle-cap", HTMLSpanElement);
 	#draggedTo;
 	#hasWarnedOfLegends = false;
-	#well = requireChild(this.group, ".sonic-toggle-well", HTMLSpanElement);
+	#well = requireChild(this.control, ".sonic-toggle-well", HTMLSpanElement);
 	claimPress() {
 		return true;
 	}
@@ -49,7 +55,7 @@ var SonicToggle = class extends SonicPositionGroupElement {
 	}
 	render() {
 		if (!this.isBound()) return;
-		this.group.style.setProperty("--_sonic-toggle-count", String(this.positions().length));
+		this.control.style.setProperty("--_sonic-toggle-count", String(this.positions().length));
 		this.#placeCap(this.#draggedTo ?? this.#restingAt());
 		super.render();
 		for (const [index, option] of this.options().entries()) option.style.setProperty("--_sonic-toggle-index", String(index));
@@ -58,11 +64,11 @@ var SonicToggle = class extends SonicPositionGroupElement {
 		return renderPosition();
 	}
 	#bindCap(signal) {
-		bindDrag(this.group, {
+		bindDrag(this.control, {
 			grab: (event) => this.#grab(event),
 			lift: (drag, event) => {
 				if (!drag.isPress || drag.isHolding || this.isDisabled()) return;
-				if (!isUnder(this.group, event.clientX, event.clientY)) return;
+				if (!isUnder(this.control, event.clientX, event.clientY)) return;
 				this.#press(drag.position);
 			},
 			move: (drag, event) => {
@@ -76,7 +82,7 @@ var SonicToggle = class extends SonicPositionGroupElement {
 				if (this.#slideTo(positionAt(drag.travel, pointer), event.pointerId)) drag.isPress = false;
 			},
 			release: (drag) => {
-				delete drag.marked.dataset.sonicPressed;
+				delete drag.marked.dataset.sonicActive;
 				this.#draggedTo = void 0;
 				this.toggleState("dragging", false);
 				this.render();
@@ -85,7 +91,7 @@ var SonicToggle = class extends SonicPositionGroupElement {
 	}
 	#checkLegends() {}
 	#fixedLegend() {
-		return [...this.children].find((child) => child !== this.group && !super.isMirrored(child));
+		return [...this.children].find((child) => child !== this.control && !super.isMirrored(child));
 	}
 	#grab(event) {
 		const position = this.pressedIndex(event.target);
@@ -94,7 +100,7 @@ var SonicToggle = class extends SonicPositionGroupElement {
 		const travel = this.#travel(event, isOnCap);
 		if (!travel || !isOnCap && this.isOptionDisabled(position)) return void 0;
 		const marked = this.options()[position] ?? this.bare;
-		marked.toggleAttribute("data-sonic-pressed", true);
+		marked.toggleAttribute("data-sonic-active", true);
 		return {
 			hasMoved: false,
 			isHolding: this.#holdFrom(position, event.pointerId),
@@ -113,7 +119,7 @@ var SonicToggle = class extends SonicPositionGroupElement {
 		return true;
 	}
 	#placeCap(at) {
-		this.group.style.setProperty("--_sonic-toggle-at", String(at));
+		this.control.style.setProperty("--_sonic-toggle-at", String(at));
 	}
 	#press(position) {
 		const target = this.pressTarget(position);

package/dist/default/elements/value-element.js

@@ -233,6 +233,7 @@ var SonicValueElement = class extends SonicFormElement {
 	#model = createValueModel(() => this.#spec());
 	#parseValue;
 	#readout;
+	#said;
 	attributeChangedCallback(name) {
 		if (name === "value" && this.#isHeld()) {
 			this.#writeHeld(this.numberAttribute("value", this.min));
@@ -250,7 +251,8 @@ var SonicValueElement = class extends SonicFormElement {
 	abandonHold() {
 		this.#gestures?.abandon();
 	}
-	bindGestures(control, signal, grab) {
+	bindGestures(signal, grab) {
+		const control = this.control;
 		const bubble = control.querySelector("[popover]");
 		if (bubble) this.#readout = {
 			anchor: control,
@@ -315,6 +317,9 @@ var SonicValueElement = class extends SonicFormElement {
 	controlRole() {
 		return "slider";
 	}
+	focusTarget() {
+		return this.control;
+	}
 	input(next) {
 		const previous = this.#model.value;
 		if (this.#model.input(next)) this.render();
@@ -373,8 +378,12 @@ var SonicValueElement = class extends SonicFormElement {
 	}
 	springTarget() {}
 	tapTarget() {}
-	travelPx(control, property) {
-		return Math.max(1, readPxProperty(getComputedStyle(control), property, fallbackTravelPx));
+	upwardAxis(travelProperty) {
+		const styles = getComputedStyle(this.control);
+		return {
+			position: (event) => -event.clientY,
+			travelPx: Math.max(1, readPxProperty(styles, travelProperty, fallbackTravelPx))
+		};
 	}
 	#entryText() {
 		const value = this.#model.value;
@@ -405,7 +414,7 @@ var SonicValueElement = class extends SonicFormElement {
 		writeAttribute(control, "aria-valuemax", String(high));
 		writeAttribute(control, "aria-valuenow", String(this.#spokenNow()));
 		if (orientation) writeAttribute(control, "aria-orientation", orientation);
-		writeAttribute(control, "aria-valuetext", this.spokenText(this.#spokenNow()));
+		writeAttribute(control, "aria-valuetext", this.#spokenValueText());
 		this.forwardNaming(control, true);
 		this.#renderDisabled(control);
 		this.renderReadout();
@@ -458,6 +467,19 @@ var SonicValueElement = class extends SonicFormElement {
 		const step = this.spokenStep;
 		return step !== void 0 && step > 0 ? trimFloat(Math.round(this.#model.value / step) * step) : this.#model.value;
 	}
+	#spokenValueText() {
+		const format = this.#formatSpokenValue ?? this.#formatValue ?? this.notation.speak;
+		const value = this.#spokenNow();
+		const said = this.#said;
+		if (said && said.format === format && said.value === value) return said.text;
+		const text = format?.(value);
+		this.#said = {
+			format,
+			text,
+			value
+		};
+		return text;
+	}
 	#textFor(value) {
 		return (this.#formatValue ?? this.notation.format)(value);
 	}

package/dist/default/elements/wave-element.js

@@ -1,5 +1,5 @@
 import { SonicValueElement } from "./value-element.js";
-import { bindSurface } from "../lib/canvas-surface.js";
+import { bindControlSurface } from "../lib/canvas-surface.js";
 import { formatClock, parseClock } from "../lib/clock.js";
 import { spokenDuration } from "../lib/spoken-duration.js";
 
@@ -32,6 +32,10 @@ var SonicWaveElement = class extends SonicValueElement {
 		this.renderMarkers();
 		this.render();
 	}
+	boxProbe = {
+		property: "margin-bottom",
+		selector: "[popover]"
+	};
 	notation = {
 		format: formatClock,
 		parse: parseClock,
@@ -65,15 +69,13 @@ var SonicWaveElement = class extends SonicValueElement {
 	}
 	connect(signal) {
 		const control = this.control;
-		this.keepControl(control, signal);
+		this.keepControl(signal);
 		this.renderEmpty();
-		this.#surface = bindSurface({
+		this.#surface = bindControlSurface({
 			canvas: this.canvas,
 			colours: this.colours,
-			fill: {
-				control,
-				sizeProperty: this.sizeProperty
-			},
+			control,
+			fill: this.fill,
 			lengths: this.lengths,
 			numbers: this.numbers,
 			paint: (context, frame) => {
@@ -82,10 +84,10 @@ var SonicWaveElement = class extends SonicValueElement {
 			resize: () => {
 				this.renderMarkers();
 			},
-			signal
+			signal,
+			sizeProperty: this.sizeProperty
 		});
 		this.render();
-		this.#surface.setFill(this.fill);
 	}
 	markerList() {
 		return this.#markers;

package/dist/default/elements/waveform.js

@@ -231,7 +231,7 @@ var SonicWaveform = class extends SonicWaveElement {
 			}
 		};
 		this.#zoomGesture = bindZoom(this.control, zoomTarget, signal);
-		this.bindGestures(this.control, signal, () => this.#grab());
+		this.bindGestures(signal, () => this.#grab());
 		bindZoomKeys(this.control, zoomTarget, signal);
 		if (!("fonts" in document)) return;
 		document.fonts.addEventListener("loadingdone", () => {
@@ -243,9 +243,6 @@ var SonicWaveform = class extends SonicWaveElement {
 		surface?.requestFrame();
 		if (surface?.isVisible === false || !this.#drawn) this.showCurrentMarker(this.#sourceSeconds());
 	}
-	focusTarget() {
-		return this.control;
-	}
 	isEmpty() {
 		return !this.#peaks || this.#peaks.samples.length === 0;
 	}

package/dist/default/elements/wavestrip.js

@@ -157,7 +157,7 @@ var SonicWavestrip = class extends SonicWaveElement {
 			},
 			valueAt: (event) => this.#markerStartAt(event, this.#axis()) ?? this.mapping().snap(this.valueFromPoint(event.clientX, event.clientY))
 		});
-		this.bindGestures(control, signal, (event) => this.#grab(event));
+		this.bindGestures(signal, (event) => this.#grab(event));
 	}
 	draw() {
 		const surface = this.surface();

package/dist/default/elements/xy.js

@@ -3,10 +3,7 @@ import { writeAttribute } from "../lib/write-attribute.js";
 import { SonicFormElement } from "./form-element.js";
 import { requireChild, template } from "../lib/render.js";
 import { Readout } from "./readout.js";
-import { ReadoutClaim } from "./readout-claim.js";
-import { createDoublePress } from "../lib/double-press.js";
 import { focusByPointer } from "../lib/focus-by-pointer.js";
-import { isMenuPress, isResetPress } from "../lib/modifier-press.js";
 import { resetKeys } from "../lib/value-mapping.js";
 import { createValueModel } from "../lib/value-model.js";
 import { pointerPosition } from "../lib/field.js";
@@ -203,26 +200,26 @@ var SonicXy = class extends SonicFormElement {
 	set yTaper(curve) {
 		this.reflect("y-taper", curve);
 	}
-	#claim = new ReadoutClaim(() => {
-		this.#renderReadout();
-	});
+	boxProbe = {
+		property: "margin-bottom",
+		selector: "[popover]"
+	};
+	control = renderXy();
+	sheet = "xy.css";
 	#currentAxis = "x";
-	#doublePress = createDoublePress();
-	#xy = renderXy();
-	#field = requireChild(this.#xy, ".sonic-xy-field", HTMLDivElement);
+	#field = requireChild(this.control, ".sonic-xy-field", HTMLDivElement);
 	#formatValue;
 	#gesture;
-	#isRevealed = false;
 	#models = {
 		x: createValueModel(() => this.#spec("x")),
 		y: createValueModel(() => this.#spec("y"))
 	};
 	#parts = {
-		x: requireChild(this.#xy, "[data-sonic-axis=\"x\"]", HTMLDivElement),
-		y: requireChild(this.#xy, "[data-sonic-axis=\"y\"]", HTMLDivElement)
+		x: requireChild(this.control, "[data-sonic-axis=\"x\"]", HTMLDivElement),
+		y: requireChild(this.control, "[data-sonic-axis=\"y\"]", HTMLDivElement)
 	};
-	#puck = requireChild(this.#xy, ".sonic-xy-puck", HTMLDivElement);
-	#readout = new Readout(requireChild(this.#xy, ".sonic-xy-readout", HTMLDivElement));
+	#puck = requireChild(this.control, ".sonic-xy-puck", HTMLDivElement);
+	#readout = new Readout(requireChild(this.control, ".sonic-xy-readout", HTMLDivElement));
 	attributeChangedCallback(name) {
 		if ((name === "x" || name === "y") && this.#gesture?.current()) return;
 		if (name === "disabled" && this.isDisabled()) this.#gesture?.end();
@@ -237,8 +234,8 @@ var SonicXy = class extends SonicFormElement {
 		this.#respec(...axes);
 	}
 	connect(signal) {
-		const xy = this.#xy;
-		this.keepControl(xy, signal);
+		const xy = this.control;
+		this.keepControl(signal);
 		this.render();
 		this.#bindPointer(xy, signal);
 		this.#bindKeys(xy, signal);
@@ -248,7 +245,7 @@ var SonicXy = class extends SonicFormElement {
 	}
 	render() {
 		if (!this.isBound()) return;
-		const { style } = this.#xy;
+		const { style } = this.control;
 		for (const axis of axes) {
 			const model = this.#models[axis];
 			const mapping = model.mapping();
@@ -275,49 +272,47 @@ var SonicXy = class extends SonicFormElement {
 			const move = keyMoves.get(event.key);
 			if (!move && !(resetKeys.has(event.key) && this.#hasDefault())) return;
 			event.preventDefault();
-			this.#claim.reveal("keys");
-			this.#renderReadout();
+			this.#gesture?.revealKeys();
 			if (move) this.#keyTo(...move);
 			else this.#reset();
 		}, { signal });
 		xy.addEventListener("focusout", (event) => {
 			if (event.relatedTarget instanceof Node && xy.contains(event.relatedTarget)) return;
-			if (this.#claim.conceal("keys")) this.#renderReadout();
+			this.#gesture?.concealKeys();
 		}, { signal });
 		signal.addEventListener("abort", () => {
-			if (this.#claim.conceal("keys")) this.#renderReadout();
+			this.#gesture?.concealKeys();
 		}, { once: true });
 	}
 	#bindPointer(xy, signal) {
 		xy.addEventListener("mousedown", (event) => {
 			event.preventDefault();
 		}, { signal });
-		xy.addEventListener("pointercancel", () => {
-			this.#doublePress.forget();
-		}, { signal });
 		this.#gesture = bindFieldGesture(xy, {
-			claim: this.#claim,
+			element: this,
 			grab: (event) => {
-				if (this.isDisabled() || isMenuPress(event)) return;
+				if (this.isDisabled()) return;
 				focusByPointer(this.focusTarget());
-				if (!isResetPress(event)) {
-					this.toggleState("dragging", true);
-					return this.#grab(event);
-				}
-				this.#reset();
+				this.toggleState("dragging", true);
+				return this.#grab(event);
 			},
 			input: (_hold, next) => {
-				if (!this.#input(next)) this.#renderReadout();
-			},
-			lift: (_hold, event) => {
-				if (!this.#doublePress.press(event) || this.doublePress !== "reset") return;
-				this.#reset();
+				this.#input(next);
 			},
 			release: (_hold, moved) => {
 				if (moved.length > 0) this.dispatchEvent(new Event("change", { bubbles: true }));
 			},
-			toggle: (isDragging) => {
-				this.toggleState("dragging", isDragging);
+			renderReadout: () => {
+				this.#renderReadout();
+			},
+			reset: () => {
+				if (this.isDisabled()) return;
+				focusByPointer(this.focusTarget());
+				this.#reset();
+			},
+			resetsOnDoublePress: () => this.doublePress === "reset",
+			toggle: (state, isOn) => {
+				this.toggleState(state, isOn);
 			}
 		}, signal);
 	}
@@ -408,16 +403,11 @@ var SonicXy = class extends SonicFormElement {
 		this.writeFormFields([["x", x], ["y", y]], `${String(x)},${String(y)}`);
 	}
 	#renderReadout() {
-		const { isRevealed } = this.#claim;
 		this.#readout.show({
 			anchor: this.#puck,
-			isOpen: isRevealed && this.readout,
+			isOpen: this.#gesture?.isRevealed() === true && this.readout,
 			text: this.#valueText("x")
 		});
-		if (isRevealed === this.#isRevealed) return;
-		this.#isRevealed = isRevealed;
-		this.toggleState("revealed", isRevealed);
-		this.dispatchEvent(new Event("sonic-reveal", { bubbles: true }));
 	}
 	#reset() {
 		this.#commit({

package/dist/default/lib/canvas-surface.js

@@ -10,6 +10,17 @@ function deviceBox(entry, css) {
 	if (!device || Math.abs(device.inlineSize - css.inlineSize * dpr) > 1) return void 0;
 	return Math.abs(device.blockSize - css.blockSize * dpr) > 1 ? void 0 : device;
 }
+function canTakeColour(context, colour) {
+	const kept = context.fillStyle;
+	const isKept = (sentinel) => {
+		context.fillStyle = sentinel;
+		context.fillStyle = colour;
+		return context.fillStyle === sentinel;
+	};
+	const isRefused = isKept("#000000") && isKept("#ffffff");
+	context.fillStyle = kept;
+	return !isRefused;
+}
 function readEach(properties, read) {
 	return Object.fromEntries(Object.entries(properties).flatMap(([name, property]) => property === void 0 ? [] : [[name, read(property)]]));
 }
@@ -181,7 +192,7 @@ var CanvasSurface = class {
 		const { canvas, colours, lengths = {}, numbers = {} } = this.#options;
 		const styles = getComputedStyle(canvas);
 		return {
-			colours: readEach(colours, (property) => styles.getPropertyValue(property).trim().replaceAll("currentcolor", () => styles.color)),
+			colours: readEach(colours, (property) => this.#resolve(styles.getPropertyValue(property).trim().replaceAll("currentcolor", () => styles.color))),
 			isReducedMotion: this.#reducedMotion.matches,
 			lengths: readEach(lengths, (property) => readPxProperty(styles, property, 0)),
 			numbers: readEach(numbers, (property) => readPxProperty(styles, property, 0))
@@ -209,6 +220,16 @@ var CanvasSurface = class {
 		if (previous.width === 0 || previous.height === 0) this.rebuild();
 		else this.invalidate();
 	}
+	#resolve(colour) {
+		const context = this.#context;
+		if (!context || canTakeColour(context, colour)) return colour;
+		const probe = document.createElement("span");
+		probe.style.color = colour;
+		this.#options.canvas.append(probe);
+		const resolved = getComputedStyle(probe).color;
+		probe.remove();
+		return resolved;
+	}
 	#schedule() {
 		if (this.#options.signal.aborted || this.#frame !== void 0 || !this.#isVisible) return;
 		this.#frame = requestAnimationFrame((frameMs) => {
@@ -233,6 +254,18 @@ var CanvasSurface = class {
 function bindSurface(options) {
 	return new CanvasSurface(options);
 }
+function bindControlSurface(options) {
+	const { control, fill, sizeProperty, ...surfaceOptions } = options;
+	const surface = bindSurface({
+		...surfaceOptions,
+		fill: {
+			control,
+			sizeProperty
+		}
+	});
+	surface.setFill(fill);
+	return surface;
+}
 
 //#endregion
-export { bindSurface };
+export { bindControlSurface, bindSurface };

package/dist/default/lib/key-press.js

@@ -3,7 +3,7 @@ function bindKeyPress(root, signal) {
 	let pressed;
 	const release = () => {
 		if (!pressed) return;
-		delete pressed.dataset.sonicPressed;
+		delete pressed.dataset.sonicActive;
 		pressed = void 0;
 	};
 	root.addEventListener("keydown", (event) => {
@@ -12,7 +12,7 @@ function bindKeyPress(root, signal) {
 		if (!(part instanceof HTMLButtonElement) || part.disabled) return;
 		release();
 		pressed = part;
-		part.dataset.sonicPressed = "";
+		part.dataset.sonicActive = "";
 	}, { signal });
 	root.addEventListener("keyup", (event) => {
 		if (event.key === " " || event.key === "Meta") release();

package/dist/default/lib/render.js

@@ -1,7 +1,7 @@
 //#region src/lib/render.ts
 function requireChild(root, selector, child) {
 	const found = root.querySelector(selector);
-	if (!(found instanceof child)) throw new Error(`A template is missing its ${selector}`);
+	if (!(found instanceof child)) throw new TypeError(`A template is missing its ${selector}`);
 	return found;
 }
 function template(html, root) {
@@ -9,7 +9,7 @@ function template(html, root) {
 	parsed.innerHTML = html;
 	return () => {
 		const clone = document.importNode(parsed.content, true).firstElementChild;
-		if (!(clone instanceof root)) throw new Error(`A template's root is not a ${root.name}`);
+		if (!(clone instanceof root)) throw new TypeError(`A template's root is not a ${root.name}`);
 		return clone;
 	};
 }

package/dist/dev/elements/{display-element.d.ts → analyser-element.d.ts}

@@ -1,8 +1,8 @@
 import { SonicElement } from "./sonic-element.js";
 import { Decibels } from "../lib/units.js";
 import { Surface, SurfaceFrame } from "../lib/canvas-surface.js";
-//#region src/elements/display-element.d.ts
-export declare abstract class SonicDisplayElement<Colour extends string, Numeric extends string = never> extends SonicElement {
+//#region src/elements/analyser-element.d.ts
+export declare abstract class SonicAnalyserElement<Colour extends string, Numeric extends string = never> extends SonicElement {
   #private;
   static readonly observedAttributes: string[];
   get analyser(): AnalyserNode | undefined;
@@ -31,4 +31,4 @@ export declare abstract class SonicDisplayElement<Colour extends string, Numeric
   protected surface(): Surface | undefined;
 }
 //#endregion
-//# sourceMappingURL=display-element.d.ts.map
+//# sourceMappingURL=analyser-element.d.ts.map