@xsynaptic/sonic-ui 0.1.0 → 0.2.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: dials, sliders, keys, a segmented switch, a peak meter and a screen panel. 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:** the dial, slider, key and switch 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/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/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/{elements → default/elements}/dial.js

@@ -26,7 +26,17 @@ const renderDial = template(`
 const fallbackTravelPx = 160;
 var SonicDial = class extends SonicRangeElement {
 	static observedAttributes = [...SonicRangeElement.observedAttributes, "modulation"];
+	get modulation() {
+		return this.numberAttribute("modulation", 0);
+	}
+	set modulation(amount) {
+		this.reflect("modulation", amount);
+	}
 	#dial = renderDial();
+	connectedCallback() {
+		this.upgradeProperties("modulation");
+		super.connectedCallback();
+	}
 	connect(signal) {
 		const dial = this.#dial;
 		this.appendOnce(dial);
@@ -37,10 +47,13 @@ var SonicDial = class extends SonicRangeElement {
 			travelPx: readPxProperty(getComputedStyle(dial), "--_sonic-dial-travel", fallbackTravelPx)
 		}));
 	}
+	focusTarget() {
+		return this.#dial;
+	}
 	render() {
 		const dial = this.#dial;
 		const positions = this.positions();
-		const modulated = this.fraction(this.value + this.numberAttribute("modulation", 0));
+		const modulated = this.fraction(this.value + this.modulation);
 		const value = this.fraction(this.value);
 		dial.style.setProperty("--_sonic-dial-value", String(value));
 		dial.style.setProperty("--_sonic-dial-origin", String(this.originFraction()));
@@ -53,5 +66,4 @@ var SonicDial = class extends SonicRangeElement {
 };
 
 //#endregion
-export { SonicDial };
-//# sourceMappingURL=dial.js.map
+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 };