@ctrl-ui/react 0.9.0 → 0.9.1

package/dist/knob-contracts/range-knobs.d.ts

@@ -1,4 +1,4 @@
 //#region src/knob-contracts/range-knobs.d.ts
-export declare const rangeKnobs: readonly ["--cui-range-indeterminate-size", "--cui-range-track-radius", "--cui-range-track-background", "--cui-range-indicator-radius", "--cui-range-indicator-background", "--cui-range-thumb-radius", "--cui-range-thumb-background", "--cui-range-thumb-border-color", "--cui-range-thumb-shadow"];
+export declare const rangeKnobs: readonly ["--cui-range-level-warning-background", "--cui-range-level-clip-background", "--cui-range-indeterminate-size", "--cui-range-track-radius", "--cui-range-track-background", "--cui-range-indicator-radius", "--cui-range-indicator-background", "--cui-range-thumb-radius", "--cui-range-thumb-background", "--cui-range-thumb-border-color", "--cui-range-thumb-shadow"];
 export type RangeKnobStyle = Partial<Record<(typeof rangeKnobs)[number], string>>;
 //#endregion

package/dist/knob-contracts/range-knobs.js

@@ -1,5 +1,7 @@
 //#region src/knob-contracts/range-knobs.ts
 const rangeKnobs = [
+	"--cui-range-level-warning-background",
+	"--cui-range-level-clip-background",
 	"--cui-range-indeterminate-size",
 	"--cui-range-track-radius",
 	"--cui-range-track-background",

package/dist/lib/level-meter-ballistics.d.ts

@@ -0,0 +1,17 @@
+//#region src/lib/level-meter-ballistics.d.ts
+export declare const LEVEL_METER_RELEASE_DB_PER_SECOND = 24;
+export declare const LEVEL_METER_PEAK_HOLD_MS = 1000;
+export type LevelMeterScale = {
+  minDb: number;
+  maxDb: number;
+};
+export type LevelMeterReading = {
+  levelDb: number;
+  peakDb: number;
+  peakHeldUntilMs: number;
+};
+export declare function clampLevelDb(levelDb: number, { minDb, maxDb }: LevelMeterScale): number;
+export declare function levelMeterFraction(levelDb: number, scale: LevelMeterScale): number;
+export declare function advanceLevelMeterReading(reading: LevelMeterReading, targetDb: number, elapsedMs: number, nowMs: number, scale: LevelMeterScale): LevelMeterReading;
+export declare function levelMeterReadingSettled(reading: LevelMeterReading, targetDb: number, scale: LevelMeterScale): boolean;
+//#endregion

package/dist/lib/level-meter-ballistics.js

@@ -0,0 +1,32 @@
+//#region src/lib/level-meter-ballistics.ts
+const LEVEL_METER_RELEASE_DB_PER_SECOND = 24;
+const LEVEL_METER_PEAK_HOLD_MS = 1e3;
+function clampLevelDb(levelDb, { minDb, maxDb }) {
+	if (Number.isNaN(levelDb)) return minDb;
+	return Math.min(maxDb, Math.max(minDb, levelDb));
+}
+function levelMeterFraction(levelDb, scale) {
+	const span = scale.maxDb - scale.minDb;
+	if (!(span > 0)) return 0;
+	return (clampLevelDb(levelDb, scale) - scale.minDb) / span;
+}
+function advanceLevelMeterReading(reading, targetDb, elapsedMs, nowMs, scale) {
+	const target = clampLevelDb(targetDb, scale);
+	const fallDb = 24 * Math.max(0, elapsedMs) / 1e3;
+	const levelDb = Math.max(target, reading.levelDb - fallDb);
+	if (levelDb >= reading.peakDb) return {
+		levelDb,
+		peakDb: levelDb,
+		peakHeldUntilMs: nowMs + LEVEL_METER_PEAK_HOLD_MS
+	};
+	return {
+		levelDb,
+		peakDb: nowMs < reading.peakHeldUntilMs ? reading.peakDb : Math.max(levelDb, reading.peakDb - fallDb),
+		peakHeldUntilMs: reading.peakHeldUntilMs
+	};
+}
+function levelMeterReadingSettled(reading, targetDb, scale) {
+	return reading.levelDb === clampLevelDb(targetDb, scale) && reading.peakDb === reading.levelDb;
+}
+//#endregion
+export { LEVEL_METER_PEAK_HOLD_MS, LEVEL_METER_RELEASE_DB_PER_SECOND, advanceLevelMeterReading, clampLevelDb, levelMeterFraction, levelMeterReadingSettled };

package/dist/styles/index.css

@@ -75,8 +75,9 @@
 @import "./recipes/inline-attachment.css";
 @import "./recipes/source-badge.css";
 @import "./recipes/inline-citation.css";
-@import "./recipes/markdown-block.css";
 @import "./recipes/range.css";
+@import "./recipes/range-level-meter.css";
+@import "./recipes/markdown-block.css";
 @import "./recipes/morphing-panel.css";
 @import "./recipes/pagination.css";
 @import "./recipes/phone-input.css";

package/dist/styles/recipes/range-level-meter.css

@@ -0,0 +1,87 @@
+@layer components {
+  :where([data-control-family="range"][data-range-kind="level-meter"][data-slot="root"]) {
+    --cui-range-level-warning-background: var(--warning);
+    --cui-range-level-clip-background: var(--destructive);
+    --_range-level-peak-size: 2px;
+    --_range-level-zone-angle: 90deg;
+  }
+
+  :where([data-control-family="range"][data-range-kind="level-meter"][data-slot="root"][data-orientation="horizontal"]) {
+    block-size: calc(var(--spacing) * 2);
+  }
+
+  :where([data-control-family="range"][data-range-kind="level-meter"][data-slot="root"][data-orientation="horizontal"]:dir(rtl)) {
+    --_range-level-zone-angle: 270deg;
+  }
+
+  :where([data-control-family="range"][data-range-kind="level-meter"][data-slot="root"][data-orientation="vertical"]) {
+    --_range-level-zone-angle: 0deg;
+    flex-direction: column;
+    inline-size: calc(var(--spacing) * 2);
+    min-block-size: calc(var(--spacing) * 16);
+  }
+
+  :where([data-control-family="range"][data-range-kind="level-meter"][data-slot="track"]) {
+    flex: 1;
+    border-radius: var(--cui-range-track-radius);
+    background: var(--cui-range-track-background);
+  }
+
+  :where([data-control-family="range"][data-range-kind="level-meter"][data-slot="bar"]),
+  :where([data-control-family="range"][data-range-kind="level-meter"][data-slot="peak"]) {
+    background-image: linear-gradient(
+      var(--_range-level-zone-angle),
+      var(--cui-range-indicator-background) calc(var(--_range-level-warning-start, 1) * 100%),
+      var(--cui-range-level-warning-background) 0 calc(var(--_range-level-clip-start, 1) * 100%),
+      var(--cui-range-level-clip-background) 0
+    );
+  }
+
+  :where([data-control-family="range"][data-range-kind="level-meter"][data-slot="bar"]) {
+    clip-path: inset(0 calc((1 - var(--_range-level, 0)) * 100%) 0 0 round var(--cui-range-indicator-radius));
+  }
+
+  :where([data-control-family="range"][data-range-kind="level-meter"][data-slot="peak"]) {
+    clip-path: inset(
+      0 calc((1 - var(--_range-level-peak, 0)) * 100%) 0 calc(var(--_range-level-peak, 0) * 100% - var(--_range-level-peak-size))
+    );
+  }
+
+  :where([data-control-family="range"][data-range-kind="level-meter"][data-slot="bar"]:dir(rtl)) {
+    clip-path: inset(0 0 0 calc((1 - var(--_range-level, 0)) * 100%) round var(--cui-range-indicator-radius));
+  }
+
+  :where([data-control-family="range"][data-range-kind="level-meter"][data-slot="peak"]:dir(rtl)) {
+    clip-path: inset(
+      0 calc(var(--_range-level-peak, 0) * 100% - var(--_range-level-peak-size)) 0 calc((1 - var(--_range-level-peak, 0)) * 100%)
+    );
+  }
+
+  :where(
+    [data-range-kind="level-meter"][data-slot="root"][data-orientation="vertical"]
+      [data-control-family="range"][data-range-kind="level-meter"][data-slot="bar"]
+  ) {
+    clip-path: inset(calc((1 - var(--_range-level, 0)) * 100%) 0 0 0 round var(--cui-range-indicator-radius));
+  }
+
+  :where(
+    [data-range-kind="level-meter"][data-slot="root"][data-orientation="vertical"]
+      [data-control-family="range"][data-range-kind="level-meter"][data-slot="peak"]
+  ) {
+    clip-path: inset(
+      calc((1 - var(--_range-level-peak, 0)) * 100%) 0 calc(var(--_range-level-peak, 0) * 100% - var(--_range-level-peak-size)) 0
+    );
+  }
+}
+
+@property --cui-range-level-warning-background {
+  syntax: "<color>";
+  inherits: true;
+  initial-value: transparent;
+}
+
+@property --cui-range-level-clip-background {
+  syntax: "<color>";
+  inherits: true;
+  initial-value: transparent;
+}

package/dist/ui/level-meter.d.ts

@@ -0,0 +1,31 @@
+import { RangeKnobStyle } from "../knob-contracts/range-knobs.js";
+import { CSSProperties, ComponentProps } from "react";
+//#region src/ui/level-meter.d.ts
+export type LevelMeterSource = {
+  subscribe: (listener: (levelDb: number) => void) => () => void;
+};
+export type LevelMeterOrientation = "horizontal" | "vertical";
+export type LevelMeterProps = Omit<ComponentProps<"div">, "style"> & {
+  value?: number;
+  source?: LevelMeterSource | null;
+  minDb?: number;
+  maxDb?: number;
+  warningDb?: number;
+  clipDb?: number;
+  orientation?: LevelMeterOrientation;
+  style?: CSSProperties & RangeKnobStyle;
+};
+export type LevelMeterTrackProps = Omit<ComponentProps<"div">, "style"> & {
+  style?: CSSProperties & RangeKnobStyle;
+};
+export type LevelMeterBarProps = Omit<ComponentProps<"div">, "style" | "children"> & {
+  style?: CSSProperties & RangeKnobStyle;
+};
+export type LevelMeterPeakProps = Omit<ComponentProps<"div">, "style" | "children"> & {
+  style?: CSSProperties & RangeKnobStyle;
+};
+export declare function LevelMeter({ value, source, minDb, maxDb, warningDb, clipDb, orientation, className, style, children, ref, ...props }: LevelMeterProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export declare function LevelMeterTrack({ className, ...props }: LevelMeterTrackProps): import("react").JSX.Element;
+export declare function LevelMeterBar({ className, ...props }: LevelMeterBarProps): import("react").JSX.Element;
+export declare function LevelMeterPeak({ className, ...props }: LevelMeterPeakProps): import("react").JSX.Element;
+//#endregion

package/dist/ui/level-meter.js

@@ -0,0 +1,152 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { advanceLevelMeterReading, levelMeterFraction, levelMeterReadingSettled } from "../lib/level-meter-ballistics.js";
+import { useEffect, useRef, useState } from "react";
+import { useRender } from "@base-ui/react/use-render";
+import { jsx } from "react/jsx-runtime";
+//#region src/ui/level-meter.tsx
+const ARIA_UPDATE_INTERVAL_MS = 250;
+function createLevelMeterPainter() {
+	let root = null;
+	let scale = {
+		minDb: -60,
+		maxDb: 0
+	};
+	let announcesValue = false;
+	let targetDb = Number.NEGATIVE_INFINITY;
+	let reading = {
+		levelDb: scale.minDb,
+		peakDb: scale.minDb,
+		peakHeldUntilMs: 0
+	};
+	let frame = 0;
+	let lastFrameMs = 0;
+	let lastAnnouncedMs = Number.NEGATIVE_INFINITY;
+	const paint = (element, nowMs, settled) => {
+		element.style.setProperty("--_range-level", `${levelMeterFraction(reading.levelDb, scale)}`);
+		element.style.setProperty("--_range-level-peak", `${levelMeterFraction(reading.peakDb, scale)}`);
+		if (!announcesValue || !settled && nowMs - lastAnnouncedMs < ARIA_UPDATE_INTERVAL_MS) return;
+		lastAnnouncedMs = nowMs;
+		const roundedDb = Math.round(reading.levelDb);
+		element.setAttribute("aria-valuenow", `${roundedDb}`);
+		element.setAttribute("aria-valuetext", `${roundedDb} dB`);
+	};
+	const step = (nowMs) => {
+		frame = 0;
+		if (!root) return;
+		reading = advanceLevelMeterReading(reading, targetDb, nowMs - lastFrameMs, nowMs, scale);
+		lastFrameMs = nowMs;
+		const settled = levelMeterReadingSettled(reading, targetDb, scale);
+		paint(root, nowMs, settled);
+		if (!settled) frame = requestAnimationFrame(step);
+	};
+	const wake = () => {
+		if (frame !== 0 || !root) return;
+		lastFrameMs = performance.now();
+		frame = requestAnimationFrame(step);
+	};
+	return {
+		attach(element, nextScale, nextAnnouncesValue) {
+			root = element;
+			scale = nextScale;
+			announcesValue = nextAnnouncesValue;
+			wake();
+			return () => {
+				cancelAnimationFrame(frame);
+				frame = 0;
+				root = null;
+			};
+		},
+		setTarget(levelDb) {
+			targetDb = levelDb;
+			wake();
+		}
+	};
+}
+function LevelMeter({ value, source, minDb = -60, maxDb = 0, warningDb = -18, clipDb = -6, orientation = "horizontal", className, style, children, ref, ...props }) {
+	const [painter] = useState(createLevelMeterPainter);
+	const rootRef = useRef(null);
+	const labelled = Boolean(props["aria-label"] || props["aria-labelledby"]);
+	const scale = {
+		minDb,
+		maxDb
+	};
+	const zoneStyle = {
+		"--_range-level-warning-start": `${levelMeterFraction(warningDb, scale)}`,
+		"--_range-level-clip-start": `${levelMeterFraction(clipDb, scale)}`,
+		...style
+	};
+	useEffect(() => {
+		const root = rootRef.current;
+		if (!root) return;
+		return painter.attach(root, {
+			minDb,
+			maxDb
+		}, labelled);
+	}, [
+		painter,
+		minDb,
+		maxDb,
+		labelled
+	]);
+	useEffect(() => {
+		if (source) return source.subscribe(painter.setTarget);
+		painter.setTarget(value ?? Number.NEGATIVE_INFINITY);
+	}, [
+		painter,
+		source,
+		value
+	]);
+	return useRender({
+		defaultTagName: "div",
+		ref: [ref ?? null, rootRef],
+		props: {
+			...props,
+			role: labelled ? "meter" : void 0,
+			"aria-hidden": labelled ? void 0 : true,
+			"aria-valuemin": labelled ? minDb : void 0,
+			"aria-valuemax": labelled ? maxDb : void 0,
+			"aria-valuenow": labelled ? minDb : void 0,
+			"data-control-ui": "level-meter",
+			"data-control-family": "range",
+			"data-range-kind": "level-meter",
+			"data-slot": "root",
+			"data-orientation": orientation,
+			className: cn("flex", className),
+			style: zoneStyle,
+			children: children ?? /* @__PURE__ */ jsx(LevelMeterTrack, { children: /* @__PURE__ */ jsx(LevelMeterBar, {}) })
+		}
+	});
+}
+function LevelMeterTrack({ className, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		"data-control-ui": "level-meter",
+		"data-control-family": "range",
+		"data-range-kind": "level-meter",
+		"data-slot": "track",
+		className: cn("relative overflow-hidden", className),
+		...props
+	});
+}
+function LevelMeterBar({ className, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		"data-control-ui": "level-meter",
+		"data-control-family": "range",
+		"data-range-kind": "level-meter",
+		"data-slot": "bar",
+		className: cn("absolute inset-0", className),
+		...props
+	});
+}
+function LevelMeterPeak({ className, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		"data-control-ui": "level-meter",
+		"data-control-family": "range",
+		"data-range-kind": "level-meter",
+		"data-slot": "peak",
+		className: cn("absolute inset-0", className),
+		...props
+	});
+}
+//#endregion
+export { LevelMeter, LevelMeterBar, LevelMeterPeak, LevelMeterTrack };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctrl-ui/react",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Control UI components, blocks, and primitives with neutral defaults and consumer-owned themes.",
   "license": "MIT",
   "repository": {