@xsynaptic/sonic-ui 0.10.3 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @xsynaptic/sonic-ui
 
+## 0.12.0
+
+### Minor Changes
+
+- Wave controls: `requestPeaks` may return one promise or an iterable of them, each repainting once however often it is returned, and its `PeaksRequest` type is exported. A write to `pending` or `peaks` inside the call no longer asks again for the same window, and `pending` ignores an unchanged list. The waveform now asks when its window moves, its data is written or a promise settles, not on every repaint. `<sonic-wavestrip>` gains `clientXOf(value)`, the viewport x where a value sits.
+
+## 0.11.0
+
+### Minor Changes
+
+- - Breaking: lit colours take status names. `data-sonic-lit` values `alt`, `hot`, `clip` and `dim` are now `ok`, `warning`, `danger` and `idle`; `--sonic-lit-alt`, `--sonic-hot` and `--sonic-clip` are now `--sonic-lit-ok`, `--sonic-lit-warning` and `--sonic-lit-danger`. A meter's and a spectrum's hot and clip zones keep their names and draw in the warning and danger colours.
+  - Toggle: new `<sonic-toggle>`, a round cap sliding in a well, two or three positions or on/off, with lit, momentary and disabled positions and an optional LED or icon on the cap.
+  - Segmented control and switch: `data-sonic-disabled` on a position child disables that one position; arrows skip it, a press and the bat pass it by. A disabled switch position's label is drawn faint, which also dims the labels of a wholly disabled switch.
+  - Switch: a press on the rest label of a two-position switch holds its momentary position instead of latching it.
+  - Button and segmented control: a held Space shows the press in Firefox. `data-sonic-pressed` marks a part held by a key as well as by a pointer.
+  - Segmented control: on a skin whose ink is dark the chosen legend is drawn in the ink, so it reads on a light cap; the lit well still marks the choice.
+
+## 0.10.4
+
+### Patch Changes
+
+- - Value controls: `dragging`, `revealed` and `cancelling` read the states of the same names as properties, so script need not match `:state()`.
+  - Waveform: every promise `requestPeaks` returns repaints as it settles, not only the latest; connecting no longer throws where `document.fonts` is missing.
+  - Wave strip: `--sonic-wavestrip-groove-size`, a length, overrides `--sonic-wavestrip-groove-ratio` so the empty groove keeps its thickness on a `fill` strip.
+  - Waveform: `--sonic-waveform-label-font-size`, a length, overrides `--sonic-waveform-label-font-ratio`; `--sonic-waveform-label-line-height` sets the label's line height.
+  - Wave strip: the marker band holds one part per marker in the order `markers` reads back; the README now lists what the wave controls make public.
+
 ## 0.10.3
 
 ### Patch Changes

package/README.md

@@ -27,4 +27,16 @@ A display takes its signal as data: `spectrum.analyser = node`, or `spectrum.pus
 
 Under a hydrating framework, register the definitions once hydration is done (in React, from an effect); a control owns one child of its host and uses only the children it documents.
 
+## Wave controls
+
+`<sonic-wavestrip>` is the overview of a track, scrubbed to seek; `<sonic-waveform>` is the close-up that scrolls under a fixed playhead. Both are value controls in seconds that take their data as properties (`peaks`, `markers`); the types list the rest.
+
+Their events bubble and carry no detail, so read the property when one fires: `revealed` on `sonic-reveal`, `currentMarker` on `sonic-marker`, and the strip's `hoverValue` on `sonic-hover`, which `clientXOf(value)` turns into a viewport x.
+
+The strip draws one part per marker inside `.sonic-wavestrip-markers`, in `start` order: a `.sonic-wavestrip-marker` dot, or a `.sonic-wavestrip-region` when the marker has an `end`. Marker labels are hidden from assistive technology; fold `currentMarker` into `formatSpokenValue` to have one spoken.
+
+The waveform calls `requestPeaks(fromSeconds, toSeconds)` as its window moves, often every frame, so return at once for a span already loaded or on its way. Return a promise, or several, and the waveform repaints as each settles; an `async` function is the wrong shape, since it hands back a new settled promise each call. `pending` is yours to keep: list the spans being fetched, and clear each as it lands.
+
+With `fill` a control takes its container's height and its ratios follow. `--sonic-wavestrip-marker-size`, `--sonic-wavestrip-groove-size` and `--sonic-waveform-label-font-size` hold an absolute length instead.
+
 Targets current Chrome and Edge, Safari 26 and Firefox 147. MIT licensed.

package/dist/default/define/toggle.js

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

package/dist/default/define.js

@@ -8,6 +8,7 @@ import "./define/slider.js";
 import "./define/spectrum.js";
 import "./define/split.js";
 import "./define/switch.js";
+import "./define/toggle.js";
 import "./define/waveform.js";
 import "./define/wavestrip.js";
 import "./define/xy.js";

package/dist/default/elements/button.js

@@ -2,6 +2,7 @@ import { writeAttribute } from "../lib/write-attribute.js";
 import { SonicFormElement } from "./form-element.js";
 import { copyNode } from "../lib/copy-node.js";
 import { bindHold } from "../lib/hold.js";
+import { bindKeyPress } from "../lib/key-press.js";
 import { placeChildren, requireChild, template } from "../lib/render.js";
 import { mirrorChildren } from "../lib/mirror-children.js";
 import { capturePointer } from "../lib/pointer-drag.js";
@@ -125,6 +126,7 @@ var SonicButton = class extends SonicFormElement {
 			this.dispatchEvent(new Event("change", { bubbles: true }));
 		}, { signal });
 		this.#bindMomentary(button, signal);
+		bindKeyPress(button, signal);
 	}
 	focusTarget() {
 		return this.#button;

package/dist/default/elements/position-group.js

@@ -0,0 +1,163 @@
+import { writeAttribute } from "../lib/write-attribute.js";
+import { bindHold } from "../lib/hold.js";
+import { SonicRadioGroupElement, optionValue } from "./radio-group.js";
+
+//#region src/elements/position-group.ts
+var SonicPositionGroupElement = class extends SonicRadioGroupElement {
+	static observedAttributes = [
+		...SonicRadioGroupElement.observedAttributes,
+		"checked",
+		"orientation"
+	];
+	get checked() {
+		return this.#isDirty ? this.#checked : this.defaultChecked;
+	}
+	set checked(isChecked) {
+		this.#isDirty = true;
+		this.#checked = isChecked === true;
+		this.render();
+	}
+	get defaultChecked() {
+		return this.hasAttribute("checked");
+	}
+	set defaultChecked(isChecked) {
+		this.reflect("checked", isChecked);
+	}
+	get orientation() {
+		const orientation = this.getAttribute("orientation");
+		return orientation === "horizontal" || orientation === "vertical" ? orientation : this.defaultOrientation;
+	}
+	set orientation(direction) {
+		this.reflect("orientation", direction);
+	}
+	get value() {
+		const value = super.value;
+		return value === "" && this.isBare() ? "on" : value;
+	}
+	set value(next) {
+		super.value = next;
+	}
+	#checked = false;
+	#holding;
+	#isDirty = false;
+	attributeChangedCallback(name) {
+		if (name === "checked") this.#isDirty = false;
+		if (this.isDisabled()) this.#holding?.release();
+		super.attributeChangedCallback(name);
+	}
+	formResetCallback() {
+		this.#isDirty = false;
+		super.formResetCallback();
+	}
+	activate() {
+		if (this.isBare()) this.bare.click();
+		else super.activate();
+	}
+	along(event) {
+		return this.orientation === "vertical" ? event.clientY : event.clientX;
+	}
+	checkedIndex(options) {
+		return options.findIndex((option) => optionValue(option) === this.value);
+	}
+	chooseByClick(option) {
+		super.chooseByClick(option);
+		if (this.isMomentary(option)) this.springBack();
+	}
+	chooseByKey(option, event) {
+		if (!this.isMomentary(option)) {
+			super.chooseByKey(option, event);
+			return;
+		}
+		if (event.repeat) return;
+		this.hold(option, event.key);
+		option.focus();
+	}
+	connect(signal) {
+		this.upgradeProperties("defaultChecked", "checked", "orientation");
+		super.connect(signal);
+		this.#holding = bindHold(this.group, {
+			canHold: () => !this.isDisabled(),
+			leave: "focusout",
+			onHold: () => {
+				this.toggleState("held", true);
+			},
+			onRelease: () => {
+				this.toggleState("held", false);
+				this.springBack();
+			}
+		}, signal);
+	}
+	focusTarget() {
+		return this.isBare() ? this.bare : super.focusTarget();
+	}
+	hold(option, by) {
+		if (this.#holding?.hold(by) === true) this.select(option);
+	}
+	isBare() {
+		return this.options().length === 0;
+	}
+	isMomentary(option) {
+		const options = this.options();
+		return (option === options[0] || option === options.at(-1)) && options.length > 1 && option.querySelector("[data-sonic-value]")?.hasAttribute("data-sonic-momentary") === true;
+	}
+	isWrapping() {
+		return false;
+	}
+	pressTarget(option) {
+		const options = this.options();
+		const index = this.checkedIndex(options);
+		return (options.length === 2 && index >= 0 ? options[1 - index] : void 0) ?? option;
+	}
+	releaseHold() {
+		this.#holding?.release();
+	}
+	render() {
+		if (!this.isBound()) return;
+		const group = this.group;
+		const count = this.options().length;
+		if (count === 0) {
+			this.#renderBare();
+			return;
+		}
+		this.bare.remove();
+		writeAttribute(group, "role", "radiogroup");
+		writeAttribute(group, "data-sonic-position-count", String(count));
+		super.render();
+	}
+	restoreState(state) {
+		if (this.isBare()) this.checked = state === "true";
+		else super.restoreState(state);
+	}
+	setChecked(isChecked) {
+		if (isChecked === this.checked) return;
+		this.checked = isChecked;
+		this.dispatchEvent(new Event("change", { bubbles: true }));
+	}
+	springBack() {
+		const options = this.options();
+		const index = this.checkedIndex(options);
+		const held = options[index];
+		if (!held || !this.isMomentary(held)) return;
+		const rest = options[index === 0 ? 1 : index - 1];
+		if (!rest) return;
+		const isFocused = this.group.contains(this.ownerDocument.activeElement);
+		this.select(rest);
+		if (isFocused) rest.focus();
+	}
+	#renderBare() {
+		const group = this.group;
+		const bare = this.bare;
+		const isChecked = this.checked;
+		writeAttribute(group, "role", void 0);
+		writeAttribute(group, "data-sonic-position-count", void 0);
+		if (bare.parentElement !== group) group.append(bare);
+		writeAttribute(bare, "disabled", this.isDisabled() ? "" : void 0);
+		writeAttribute(bare, "aria-checked", String(isChecked));
+		this.forwardNaming(group, false);
+		this.forwardNaming(bare, true);
+		this.writeFormValue(isChecked ? this.value : null, String(isChecked));
+	}
+};
+
+//#endregion
+export { SonicPositionGroupElement };

package/dist/default/elements/radio-group.js

@@ -1,6 +1,8 @@
+import { clamp } from "../lib/math.js";
 import { writeAttribute } from "../lib/write-attribute.js";
 import { SonicFormElement } from "./form-element.js";
 import { copyNode } from "../lib/copy-node.js";
+import { bindKeyPress } from "../lib/key-press.js";
 import { placeChildren } from "../lib/render.js";
 import { mirrorChildren } from "../lib/mirror-children.js";
 import { bindDrag } from "../lib/pointer-drag.js";
@@ -52,9 +54,9 @@ var SonicRadioGroupElement = class extends SonicFormElement {
 		mirrorChildren(this, {
 			control: group,
 			copy: copyNode,
-			isCopied: (child) => child instanceof Element && child.matches("[data-sonic-value]"),
+			isCopied: (child) => this.isMirrored(child),
 			place: (copies) => {
-				this.#copyOptions(copies);
+				this.placeCopies(copies);
 			}
 		}, signal);
 		group.addEventListener("click", (event) => {
@@ -63,6 +65,7 @@ var SonicRadioGroupElement = class extends SonicFormElement {
 			if (option) this.chooseByClick(option);
 		}, { signal });
 		this.#bindPress(group, signal);
+		bindKeyPress(group, signal);
 		group.addEventListener("keydown", (event) => {
 			if (event.defaultPrevented) return;
 			const option = this.optionOf(event.target);
@@ -75,6 +78,12 @@ var SonicRadioGroupElement = class extends SonicFormElement {
 	focusTarget() {
 		return this.options().find((option) => option.tabIndex === 0);
 	}
+	isMirrored(child) {
+		return child instanceof Element && child.matches("[data-sonic-value]");
+	}
+	isOptionDisabled(option) {
+		return option.querySelector("[data-sonic-value]")?.hasAttribute("data-sonic-disabled") === true;
+	}
 	isWrapping() {
 		return true;
 	}
@@ -86,6 +95,9 @@ var SonicRadioGroupElement = class extends SonicFormElement {
 	options() {
 		return [...this.group.children].filter((child) => child instanceof HTMLButtonElement && child.getAttribute("role") === "radio");
 	}
+	placeCopies(copies) {
+		this.#copyOptions(copies);
+	}
 	releaseTarget(option) {
 		return option;
 	}
@@ -93,10 +105,10 @@ var SonicRadioGroupElement = class extends SonicFormElement {
 		if (!this.isBound()) return;
 		const options = this.options();
 		const checked = options.find((option) => optionValue(option) === this.#value);
-		const focusable = checked ?? options[0];
-		const isDisabled = this.isDisabled();
+		const enabled = this.isDisabled() ? [] : options.filter((option) => !this.isOptionDisabled(option));
+		const focusable = enabled.find((option) => option === checked) ?? enabled[0];
 		for (const option of options) {
-			writeAttribute(option, "disabled", isDisabled ? "" : void 0);
+			writeAttribute(option, "disabled", enabled.includes(option) ? void 0 : "");
 			writeAttribute(option, "aria-checked", String(option === checked));
 			writeAttribute(option, "tabindex", option === focusable ? "0" : "-1");
 		}
@@ -112,11 +124,22 @@ var SonicRadioGroupElement = class extends SonicFormElement {
 		this.value = next;
 		this.dispatchEvent(new Event("change", { bubbles: true }));
 	}
+	stepFrom(from, step) {
+		const options = this.options();
+		let index = from;
+		for (const _ of options) {
+			const next = index + step;
+			index = this.isWrapping() ? (next + options.length) % options.length : clamp(next, 0, options.length - 1);
+			const option = options[index];
+			if (option && !this.isOptionDisabled(option)) return option;
+		}
+	}
 	#bindPress(group, signal) {
 		bindDrag(group, {
 			grab: (event) => {
 				const option = this.optionOf(event.target);
-				if (!option || this.isDisabled() || this.claimPress(option, event)) return;
+				if (!option || this.isDisabled() || this.isOptionDisabled(option)) return;
+				if (this.claimPress(option, event)) return;
 				const boxes = this.#optionBoxes();
 				this.#markPressed(option);
 				return {
@@ -159,19 +182,18 @@ var SonicRadioGroupElement = class extends SonicFormElement {
 	}
 	#keyTarget(option, key) {
 		const options = this.options();
-		if (key === "Home") return options[0];
-		if (key === "End") return options.at(-1);
+		const isEnabled = (other) => !this.isOptionDisabled(other);
+		if (key === "Home") return options.find((other) => isEnabled(other));
+		if (key === "End") return options.findLast((other) => isEnabled(other));
 		const step = keySteps.get(key);
 		if (step === void 0) return void 0;
-		const index = options.indexOf(option) + step;
-		if (this.isWrapping()) return options[(index + options.length) % options.length];
-		return options[Math.min(Math.max(index, 0), options.length - 1)];
+		return this.stepFrom(options.indexOf(option), step) ?? option;
 	}
 	#markPressed(pressed) {
 		for (const option of this.options()) option.toggleAttribute("data-sonic-pressed", option === pressed);
 	}
 	#optionBoxes() {
-		return this.options().map((option) => [option, option.getBoundingClientRect()]);
+		return this.options().filter((option) => !this.isOptionDisabled(option)).map((option) => [option, option.getBoundingClientRect()]);
 	}
 	#refocus(focused, value) {
 		const options = this.options();

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

@@ -23,6 +23,7 @@ var SonicElement = class extends HTMLElement {
 	}
 	internals = "attachInternals" in HTMLElement.prototype ? this.attachInternals() : void 0;
 	#connection;
+	#states = /* @__PURE__ */ new Set();
 	blur() {
 		this.#focused()?.blur();
 	}
@@ -68,6 +69,9 @@ var SonicElement = class extends HTMLElement {
 		}
 		if (labels.length > 0) writeLabelledBy(target, labels);
 	}
+	hasState(state) {
+		return this.#states.has(state);
+	}
 	isBound() {
 		return this.#connection !== void 0;
 	}
@@ -104,8 +108,13 @@ var SonicElement = class extends HTMLElement {
 		this.setAttribute(name, value === true ? "" : value.toString());
 	}
 	toggleState(state, isOn) {
-		if (isOn) this.internals?.states.add(state);
-		else this.internals?.states.delete(state);
+		if (isOn) {
+			this.#states.add(state);
+			this.internals?.states.add(state);
+			return;
+		}
+		this.#states.delete(state);
+		this.internals?.states.delete(state);
 	}
 	upgradeProperties(...names) {
 		for (const name of names) {