@xsynaptic/sonic-ui 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # @xsynaptic/sonic-ui
 
-Native custom elements for audio interfaces: dials, sliders, keys, a segmented switch, a peak meter and a screen panel. Light DOM, drawn in CSS, skinned with `--sonic-*` custom properties. No framework, no runtime dependencies.
+Native custom elements for audio interfaces. Each control renders in the light DOM, drawn in CSS, skinned with `--sonic-*` custom properties. No framework, no runtime dependencies.
 
 Early and unstable: any 0.x release may break the API.
 
@@ -29,6 +29,13 @@ import '@xsynaptic/sonic-ui/define';
 
 The styles sit in `@layer sonic`, so list it after your resets. A skin (`slate`, `lime` or `ivory`) applies under `.sonic-skin-<name>` on any ancestor. The package root exports the classes without registering them, for your own tag names.
 
+## Usage
+
+- **Attributes and properties** reflect each other: `dial.max = 200` writes `max="200"`. `value` and the key's `pressed` are the live state and never write their attribute, as on native inputs.
+- **Events:** `change` when a control settles, and `input` while a dial or slider moves; both bubble.
+- **Formatting:** `formatValue` sets the text the readout and assistive technology read, and `parseValue` reads typed entry back. `formatPercent` and `parsePercent` from the package root show 0 to 1 as a percentage.
+- **Forms:** controls that hold a value submit under their `name`, reset, take a `<label>`, and follow a disabled `<fieldset>`, as native inputs do.
+
 ## Browsers
 
 Current Chrome and Edge, Safari 26 and Firefox 147.

package/dist/default/define/dial.js

@@ -0,0 +1,7 @@
+import { defineOnce } from "../elements/define-once.js";
+import { SonicDial } from "../elements/dial.js";
+
+//#region src/define/dial.ts
+defineOnce("sonic-dial", SonicDial);
+
+//#endregion

package/dist/default/define/key.js

@@ -0,0 +1,7 @@
+import { defineOnce } from "../elements/define-once.js";
+import { SonicKey } from "../elements/key.js";
+
+//#region src/define/key.ts
+defineOnce("sonic-key", SonicKey);
+
+//#endregion

package/dist/default/define/meter.js

@@ -0,0 +1,7 @@
+import { defineOnce } from "../elements/define-once.js";
+import { SonicMeter } from "../elements/meter.js";
+
+//#region src/define/meter.ts
+defineOnce("sonic-meter", SonicMeter);
+
+//#endregion

package/dist/default/define/number.js

@@ -0,0 +1,7 @@
+import { defineOnce } from "../elements/define-once.js";
+import { SonicNumber } from "../elements/number.js";
+
+//#region src/define/number.ts
+defineOnce("sonic-number", SonicNumber);
+
+//#endregion

package/dist/default/define/segmented.js

@@ -0,0 +1,7 @@
+import { defineOnce } from "../elements/define-once.js";
+import { SonicSegmented } from "../elements/segmented.js";
+
+//#region src/define/segmented.ts
+defineOnce("sonic-segmented", SonicSegmented);
+
+//#endregion

package/dist/default/define/slider.js

@@ -0,0 +1,7 @@
+import { defineOnce } from "../elements/define-once.js";
+import { SonicSlider } from "../elements/slider.js";
+
+//#region src/define/slider.ts
+defineOnce("sonic-slider", SonicSlider);
+
+//#endregion

package/dist/{define.js → default/define.js}

@@ -1,5 +1,6 @@
 import "./define/dial.js";
 import "./define/key.js";
 import "./define/meter.js";
+import "./define/number.js";
 import "./define/segmented.js";
 import "./define/slider.js";

package/dist/default/elements/define-once.js

@@ -0,0 +1,7 @@
+//#region src/elements/define-once.ts
+function defineOnce(tag, elementClass) {
+	if (!customElements.get(tag)) customElements.define(tag, elementClass);
+}
+
+//#endregion
+export { defineOnce };

package/dist/default/elements/dial.js

@@ -0,0 +1,81 @@
+import { template } from "../lib/render.js";
+import { SonicRangeElement } from "./range-element.js";
+import { readPxProperty } from "../lib/read-px-property.js";
+
+//#region src/elements/dial.ts
+const renderDial = template(`
+		<div class="sonic-dial" role="slider" tabindex="0">
+			<div class="sonic-dial-notches"></div>
+			<div class="sonic-dial-ring"></div>
+			<div class="sonic-dial-modulation"></div>
+			<div class="sonic-dial-cap"></div>
+			<div class="sonic-dial-pointer"></div>
+			<div class="sonic-dial-readout" popover="manual">
+				<span></span>
+				<input
+					autocomplete="off"
+					class="sonic-dial-entry"
+					enterkeyhint="done"
+					hidden
+					spellcheck="false"
+					type="text"
+				/>
+			</div>
+		</div>
+	`, HTMLDivElement);
+const fallbackTravelPx = 160;
+var SonicDial = class extends SonicRangeElement {
+	static observedAttributes = [
+		...SonicRangeElement.observedAttributes,
+		"endless",
+		"modulation"
+	];
+	get endless() {
+		return this.hasAttribute("endless");
+	}
+	set endless(isEndless) {
+		this.reflect("endless", isEndless);
+	}
+	get modulation() {
+		return this.numberAttribute("modulation", 0);
+	}
+	set modulation(amount) {
+		this.reflect("modulation", amount);
+	}
+	#dial = renderDial();
+	connectedCallback() {
+		this.upgradeProperties("endless", "modulation");
+		super.connectedCallback();
+	}
+	connect(signal) {
+		const dial = this.#dial;
+		this.appendOnce(dial);
+		this.render();
+		this.checkStyles(dial, "dial.css");
+		this.bindGestures(dial, signal, () => ({
+			position: (event) => -event.clientY,
+			travelPx: readPxProperty(getComputedStyle(dial), "--_sonic-dial-travel", fallbackTravelPx)
+		}));
+	}
+	focusTarget() {
+		return this.#dial;
+	}
+	render() {
+		const dial = this.#dial;
+		const positions = this.positions();
+		const [modulationFrom, modulationTo] = this.modulationFractions(this.endless ? 0 : this.modulation);
+		dial.style.setProperty("--_sonic-dial-value", String(this.fraction(this.value)));
+		dial.style.setProperty("--_sonic-dial-origin", String(this.originFraction()));
+		dial.style.setProperty("--_sonic-dial-modulation-from", String(modulationFrom));
+		dial.style.setProperty("--_sonic-dial-modulation-to", String(modulationTo));
+		if (positions === void 0) dial.style.removeProperty("--_sonic-dial-positions");
+		else dial.style.setProperty("--_sonic-dial-positions", String(positions));
+		this.renderAria(dial);
+	}
+	wraps() {
+		return this.endless;
+	}
+};
+
+//#endregion
+export { SonicDial };

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

@@ -0,0 +1,56 @@
+import { SonicElement } from "./sonic-element.js";
+
+//#region src/elements/form-element.ts
+var SonicFormElement = class extends SonicElement {
+	static formAssociated = true;
+	get form() {
+		return this.internals?.form ?? null;
+	}
+	get labels() {
+		return this.internals?.labels ?? null;
+	}
+	get name() {
+		return this.getAttribute("name") ?? "";
+	}
+	set name(value) {
+		this.reflect("name", value);
+	}
+	constructor() {
+		super();
+		if (this.internals) this.internals.role = "none";
+		this.addEventListener("click", (event) => {
+			if (event.target === this) this.activate();
+		});
+		this.addEventListener("focusin", () => {
+			this.render();
+		});
+	}
+	connectedCallback() {
+		this.upgradeProperties("name");
+		super.connectedCallback();
+	}
+	formDisabledCallback() {
+		this.attributeChangedCallback("disabled");
+	}
+	formResetCallback() {
+		this.attributeChangedCallback("value");
+	}
+	formStateRestoreCallback(state) {
+		const prefix = `${this.localName}:`;
+		if (typeof state === "string" && state.startsWith(prefix)) this.restoreState(state.slice(prefix.length));
+	}
+	activate() {
+		this.focus();
+	}
+	namingLabels() {
+		const internals = this.internals;
+		if (!internals || this.hasAttribute("aria-label") || this.hasAttribute("aria-labelledby")) return [];
+		return [...internals.labels].filter((label) => label instanceof Element);
+	}
+	writeFormValue(value, state) {
+		this.internals?.setFormValue(value, `${this.localName}:${state}`);
+	}
+};
+
+//#endregion
+export { SonicFormElement };

package/dist/default/elements/key.js

@@ -0,0 +1,144 @@
+import { requireChild, template } from "../lib/render.js";
+import { SonicFormElement } from "./form-element.js";
+import { copyNode } from "../lib/copy-node.js";
+
+//#region src/elements/key.ts
+const renderKey = template(`
+		<button class="sonic-key" type="button"><span class="sonic-key-cap"></span></button>
+	`, HTMLButtonElement);
+const holdKeys = /* @__PURE__ */ new Set([" ", "Enter"]);
+var SonicKey = class extends SonicFormElement {
+	static observedAttributes = [
+		...SonicFormElement.observedAttributes,
+		"momentary",
+		"pressed",
+		"toggle",
+		"value"
+	];
+	get defaultPressed() {
+		return this.hasAttribute("pressed");
+	}
+	set defaultPressed(isPressed) {
+		this.reflect("pressed", isPressed);
+	}
+	get momentary() {
+		return this.hasAttribute("momentary");
+	}
+	set momentary(isMomentary) {
+		this.reflect("momentary", isMomentary);
+	}
+	get pressed() {
+		return this.#isDirty ? this.#pressed : this.defaultPressed;
+	}
+	set pressed(isPressed) {
+		this.#isDirty = true;
+		this.#pressed = isPressed === true;
+		this.render();
+	}
+	get toggle() {
+		return this.hasAttribute("toggle");
+	}
+	set toggle(isToggle) {
+		this.reflect("toggle", isToggle);
+	}
+	get value() {
+		return this.getAttribute("value") ?? "on";
+	}
+	set value(value) {
+		this.reflect("value", value);
+	}
+	#holder;
+	#isDirty = false;
+	#key = renderKey();
+	#pressed = false;
+	attributeChangedCallback(name) {
+		if (name === "pressed") this.#isDirty = false;
+		if (name === "disabled" && this.isDisabled()) this.#release();
+		this.render();
+	}
+	formResetCallback() {
+		this.attributeChangedCallback("pressed");
+	}
+	activate() {
+		this.#key.click();
+	}
+	connect(signal) {
+		const key = this.#key;
+		const cap = requireChild(key, ".sonic-key-cap", HTMLSpanElement);
+		this.upgradeProperties("defaultPressed", "momentary", "toggle", "pressed", "value");
+		this.mirrorChildren({
+			control: key,
+			copy: (originals) => {
+				cap.replaceChildren(...originals.map((original) => copyNode(original)));
+			}
+		}, signal);
+		this.render();
+		this.checkStyles(key, "key.css");
+		signal.addEventListener("abort", () => {
+			this.#release();
+		}, { once: true });
+		key.addEventListener("click", () => {
+			if (!this.toggle) return;
+			this.pressed = !this.pressed;
+			this.dispatchEvent(new Event("change", { bubbles: true }));
+		}, { signal });
+		this.#bindMomentary(key, signal);
+	}
+	focusTarget() {
+		return this.#key;
+	}
+	render() {
+		const key = this.#key;
+		key.disabled = this.isDisabled();
+		key.removeAttribute("aria-pressed");
+		if (this.toggle) key.setAttribute("aria-pressed", String(this.pressed));
+		this.toggleState("pressed", this.pressed);
+		this.forwardNaming(key, true);
+		const submitted = this.toggle && this.pressed ? this.value : null;
+		this.writeFormValue(submitted, String(this.pressed));
+	}
+	restoreState(state) {
+		if (this.toggle) this.pressed = state === "true";
+	}
+	#bindMomentary(key, signal) {
+		const releasePointer = (event) => {
+			if (event.pointerId === this.#holder) this.#release();
+		};
+		key.addEventListener("pointerdown", (event) => {
+			if (event.button !== 0 || !this.#isMomentary()) return;
+			key.setPointerCapture(event.pointerId);
+			this.#hold(event.pointerId);
+		}, { signal });
+		key.addEventListener("lostpointercapture", releasePointer, { signal });
+		key.addEventListener("pointercancel", releasePointer, { signal });
+		key.addEventListener("pointerup", releasePointer, { signal });
+		key.addEventListener("keydown", (event) => {
+			if (event.repeat || !holdKeys.has(event.key) || !this.#isMomentary()) return;
+			this.#hold(event.key);
+		}, { signal });
+		key.addEventListener("keyup", (event) => {
+			if (event.key === this.#holder) this.#release();
+		}, { signal });
+		key.addEventListener("blur", () => {
+			if (typeof this.#holder === "string") this.#release();
+		}, { signal });
+	}
+	#hold(holder) {
+		if (this.isDisabled() || this.#holder !== void 0) return;
+		this.#holder = holder;
+		this.pressed = true;
+		this.dispatchEvent(new Event("change", { bubbles: true }));
+	}
+	#isMomentary() {
+		return this.momentary && !this.toggle;
+	}
+	#release() {
+		if (this.#holder === void 0) return;
+		this.#holder = void 0;
+		this.pressed = false;
+		this.dispatchEvent(new Event("change", { bubbles: true }));
+	}
+};
+
+//#endregion
+export { SonicKey };

package/dist/{elements → default/elements}/meter.js

@@ -1,5 +1,5 @@
-import { SonicElement } from "./sonic-element.js";
 import { template } from "../lib/render.js";
+import { SonicElement } from "./sonic-element.js";
 
 //#region src/elements/meter.ts
 const renderMeter = template(`
@@ -38,6 +38,24 @@ var SonicMeter = class extends SonicElement {
 		this.#render(now);
 		this.#schedule(now);
 	}
+	get max() {
+		return this.numberAttribute("max", 0);
+	}
+	set max(decibels) {
+		this.reflect("max", decibels);
+	}
+	get min() {
+		return this.numberAttribute("min", -60);
+	}
+	set min(decibels) {
+		this.reflect("min", decibels);
+	}
+	get orientation() {
+		return this.getAttribute("orientation") === "horizontal" ? "horizontal" : "vertical";
+	}
+	set orientation(direction) {
+		this.reflect("orientation", direction);
+	}
 	#bar = -Infinity;
 	#clipAt = -Infinity;
 	#frame;
@@ -54,7 +72,7 @@ var SonicMeter = class extends SonicElement {
 	}
 	connect(signal) {
 		const now = performance.now();
-		this.upgradeProperty("level");
+		this.upgradeProperties("max", "min", "orientation", "level");
 		this.appendOnce(this.#meter);
 		this.#render(now);
 		this.#schedule(now);
@@ -66,24 +84,18 @@ var SonicMeter = class extends SonicElement {
 		}, { once: true });
 	}
 	#fraction(decibels) {
-		const min = this.#min();
-		const range = this.#max() - min;
+		const min = this.min;
+		const range = this.max - min;
 		return range > 0 ? Math.min(1, Math.max(0, (decibels - min) / range)) : 0;
 	}
 	#isSettled(now) {
-		const floor = this.#min();
+		const floor = this.min;
 		return this.#bar <= Math.max(this.#target, floor) && this.#peak <= Math.max(this.#bar, floor) && now - this.#clipAt >= holdMs;
 	}
-	#max() {
-		return this.numberAttribute("max", 0);
-	}
-	#min() {
-		return this.numberAttribute("min", -60);
-	}
 	#render(now) {
 		const meter = this.#meter;
-		meter.style.setProperty("--_sonic-meter-min", String(this.#min()));
-		meter.style.setProperty("--_sonic-meter-max", String(this.#max()));
+		meter.style.setProperty("--_sonic-meter-min", String(this.min));
+		meter.style.setProperty("--_sonic-meter-max", String(this.max));
 		if (this.disabled) {
 			meter.style.setProperty("--_sonic-meter-level", "0");
 			meter.style.setProperty("--_sonic-meter-peak", "0");
@@ -103,7 +115,7 @@ var SonicMeter = class extends SonicElement {
 		const fall = releaseDecibelsPerSecond * Math.max(0, time - (this.#lastFrame ?? time)) / 1e3;
 		this.#frame = void 0;
 		this.#lastFrame = time;
-		this.#bar = Math.max(this.#target, this.#min(), this.#bar - fall);
+		this.#bar = Math.max(this.#target, this.min, this.#bar - fall);
 		if (time - this.#peakAt >= holdMs) this.#peak = Math.max(this.#bar, this.#peak - fall);
 		this.#render(time);
 		if (this.#isSettled(time)) {
@@ -115,5 +127,4 @@ var SonicMeter = class extends SonicElement {
 };
 
 //#endregion
-export { SonicMeter };
-//# sourceMappingURL=meter.js.map
+export { SonicMeter };

package/dist/default/elements/number.js

@@ -0,0 +1,46 @@
+import { requireChild, template } from "../lib/render.js";
+import { SonicRangeElement } from "./range-element.js";
+import { readPxProperty } from "../lib/read-px-property.js";
+
+//#region src/elements/number.ts
+const renderNumber = template(`
+		<div class="sonic-number" role="spinbutton" tabindex="0">
+			<span aria-hidden="true" class="sonic-number-value"></span>
+			<input
+				autocomplete="off"
+				class="sonic-number-entry"
+				enterkeyhint="done"
+				hidden
+				spellcheck="false"
+				type="text"
+			/>
+		</div>
+	`, HTMLDivElement);
+const fallbackTravelPx = 160;
+var SonicNumber = class extends SonicRangeElement {
+	#number = renderNumber();
+	#digits = requireChild(this.#number, ".sonic-number-value", HTMLSpanElement);
+	connect(signal) {
+		const number = this.#number;
+		this.appendOnce(number);
+		this.render();
+		this.checkStyles(number, "number.css");
+		this.bindGestures(number, signal, () => ({
+			position: (event) => -event.clientY,
+			travelPx: readPxProperty(getComputedStyle(number), "--_sonic-number-travel", fallbackTravelPx)
+		}));
+	}
+	controlRole() {
+		return "spinbutton";
+	}
+	focusTarget() {
+		return this.#number;
+	}
+	render() {
+		this.#digits.textContent = this.valueText();
+		this.renderAria(this.#number);
+	}
+};
+
+//#endregion
+export { SonicNumber };