@viraui/react 2026.10.0 → 2026.11.0-next.0

package/dist/components/gauge/tooltip.d.ts

@@ -0,0 +1,117 @@
+import * as React from 'react';
+/**
+ * What the tooltip is pinned to. `pointer` follows the cursor round the
+ * gauge, `value` sits on the scale at the value, and the rest are fixed
+ * points of the gauge: its centre, or the middle of an edge or a corner of
+ * the box its scale fills.
+ */
+export type GaugeTooltipPosition = 'pointer' | 'value' | 'center' | 'top' | 'right' | 'bottom' | 'left' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+/**
+ * Which way the bubble stands off its point. `auto` picks for the position:
+ * outward from the scale at the value, so the bubble swings round a dial with it,
+ * above the pointer, centred on the centre, and away from the dial at an
+ * edge or corner.
+ */
+export type GaugeTooltipSide = 'auto' | 'center' | 'top' | 'right' | 'bottom' | 'left';
+export type GaugeTooltipProps = {
+    /**
+     * Anchor on the gauge the bubble pins to.
+     * @defaultValue 'value'
+     */
+    position?: GaugeTooltipPosition;
+    /**
+     * Side the bubble stands off its point.
+     * @defaultValue 'auto'
+     */
+    side?: GaugeTooltipSide;
+    /**
+     * Domain value a `value` tooltip points at and shows. Defaults to the
+     * current value, or for a range the middle of it, showing both ends; a
+     * fixed one marks a target or a cutoff.
+     * @defaultValue Current gauge value (or range middle)
+     */
+    at?: number;
+    /**
+     * How far out from the scale's reference line the point sits, in SVG
+     * units: the spot on the scale for `value`, and the box round the scale
+     * for the edges and corners.
+     * @defaultValue 24
+     */
+    offset?: number;
+    /**
+     * Room between the point and the bubble, in CSS pixels.
+     * @defaultValue 8
+     */
+    gap?: number;
+    /**
+     * Keep the bubble on screen: flip it to the far side of its point when
+     * that side has more room, then slide it sideways in from the left or
+     * right edge while it still overlaps its point. On by default.
+     * @defaultValue true
+     */
+    avoidCollisions?: boolean;
+    /**
+     * Room kept clear between the bubble and the viewport edge, in CSS pixels.
+     * @defaultValue 8
+     */
+    collisionPadding?: number;
+    /**
+     * Hold the tooltip open, or shut, instead of showing it on hover, while
+     * a press that started on the gauge is held, and on keyboard focus.
+     * @defaultValue undefined
+     */
+    open?: boolean;
+    /**
+     * Small line above the value. Leave out for the value on its own.
+     * @defaultValue undefined
+     */
+    label?: React.ReactNode;
+    /**
+     * Printed after the value, a size down.
+     * @defaultValue undefined
+     */
+    unit?: React.ReactNode;
+    /**
+     * Fraction digits when formatting with `toFixed`.
+     * @defaultValue 0
+     */
+    decimals?: number;
+    /**
+     * Formats each number shown; a range formats its two ends apart.
+     * @defaultValue undefined
+     */
+    format?: (value: number) => string;
+    /**
+     * Placed between the two ends of a range.
+     * @defaultValue '–'
+     */
+    separator?: string;
+    /**
+     * Classes for the bubble, merged over its defaults.
+     * @defaultValue undefined
+     */
+    className?: string;
+    /**
+     * Inline style for the bubble. Prefer `--*` custom properties.
+     * @defaultValue undefined
+     */
+    style?: React.CSSProperties;
+    /**
+     * Replaces the default label, value and unit with any HTML, or a function
+     * of the value being shown for content that has to follow it. On a range
+     * the function gets its start as well.
+     * @defaultValue Default label / value / unit
+     */
+    children?: React.ReactNode | ((value: number, from?: number) => React.ReactNode);
+};
+/**
+ * An HTML tooltip for the gauge, shown while the pointer is over it. It reads
+ * the value with an optional label and unit by default, or renders whatever
+ * its children are, and can be pinned to the value on the arc, follow the
+ * pointer, or hold a fixed spot on the dial.
+ *
+ * The bubble is portalled to the body and placed through the SVG's screen
+ * transform, so it is never clipped by the gauge and keeps its own CSS size
+ * however the gauge, or an inset it sits in, is scaled.
+ */
+export declare const GaugeTooltip: React.FC<GaugeTooltipProps>;

package/dist/components/gauge/tooltip.js

@@ -0,0 +1,337 @@
+"use client";
+import { clsx } from "../../core/clsx.js";
+import { foldValue } from "./math.js";
+import { useGauge } from "./context.js";
+import gauge_module_default from "./gauge.module.js";
+import { require_react_dom } from "../../node_modules/.pnpm/react-dom@19.3.0_react@19.3.0/node_modules/react-dom/index.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
+//#region src/components/gauge/tooltip.tsx
+var import_react_dom = require_react_dom();
+var extent = {
+	x: "width",
+	y: "height"
+};
+/**
+* The bubble's top left corner for a direction off the point: centred on the
+* point, moved `gap` along the direction, then pushed half its own size the
+* same way, so a side tooltip touches the point with that edge.
+*/
+var corner = (p, d, size, gap) => {
+	const len = Math.hypot(d.x, d.y) || 1;
+	return {
+		x: p.x + d.x / len * gap + (d.x - 1) / 2 * size.width,
+		y: p.y + d.y / len * gap + (d.y - 1) / 2 * size.height
+	};
+};
+/** Directions in screen space, y down, scaled so the longer axis is 1. */
+var sides = {
+	center: {
+		x: 0,
+		y: 0
+	},
+	top: {
+		x: 0,
+		y: -1
+	},
+	right: {
+		x: 1,
+		y: 0
+	},
+	bottom: {
+		x: 0,
+		y: 1
+	},
+	left: {
+		x: -1,
+		y: 0
+	}
+};
+/** Where each fixed position sits in the sweep's box, 0 to 1 across. */
+var boxPoints = {
+	top: {
+		x: .5,
+		y: 0
+	},
+	right: {
+		x: 1,
+		y: .5
+	},
+	bottom: {
+		x: .5,
+		y: 1
+	},
+	left: {
+		x: 0,
+		y: .5
+	},
+	"top-left": {
+		x: 0,
+		y: 0
+	},
+	"top-right": {
+		x: 1,
+		y: 0
+	},
+	"bottom-left": {
+		x: 0,
+		y: 1
+	},
+	"bottom-right": {
+		x: 1,
+		y: 1
+	}
+};
+/** What can take keyboard focus, to find the element that owns the gauge's.
+A range control is not focusable itself but holds the thumbs that are. */
+var FOCUSABLE = "[tabindex]:not([tabindex=\"-1\"]), a[href], button, input, select, textarea, [data-slot=\"gauge-control\"]";
+var subscribe = () => () => void 0;
+var useIsClient = () => React.useSyncExternalStore(subscribe, () => true, () => false);
+/** The label over the value and its unit. */
+var DefaultContent = ({ text, label, unit }) => /* @__PURE__ */ jsxs("div", {
+	className: gauge_module_default.TooltipBody,
+	children: [label && /* @__PURE__ */ jsx("span", {
+		className: gauge_module_default.TooltipLabel,
+		children: label
+	}), /* @__PURE__ */ jsxs("span", {
+		className: gauge_module_default.TooltipValue,
+		children: [text, unit && /* @__PURE__ */ jsx("span", {
+			className: gauge_module_default.TooltipUnit,
+			children: unit
+		})]
+	})]
+});
+/**
+* An HTML tooltip for the gauge, shown while the pointer is over it. It reads
+* the value with an optional label and unit by default, or renders whatever
+* its children are, and can be pinned to the value on the arc, follow the
+* pointer, or hold a fixed spot on the dial.
+*
+* The bubble is portalled to the body and placed through the SVG's screen
+* transform, so it is never clipped by the gauge and keeps its own CSS size
+* however the gauge, or an inset it sits in, is scaled.
+*/
+var GaugeTooltip = ({ position = "value", side = "auto", at, offset = 24, gap = 8, avoidCollisions = true, collisionPadding = 8, open, label, unit, decimals = 0, format, separator = "–", className, style, children }) => {
+	const gauge = useGauge();
+	const isClient = useIsClient();
+	const anchor = React.useRef(null);
+	const box = React.useRef(null);
+	const pointer = React.useRef(null);
+	const [hovered, setHovered] = React.useState(false);
+	const [pressed, setPressed] = React.useState(false);
+	const [focused, setFocused] = React.useState(false);
+	const shown = open ?? (hovered || pressed || focused);
+	const value = at ?? gauge.value;
+	const spread = at === void 0 && gauge.range;
+	let middle = value;
+	if (spread) {
+		if (gauge.wrap) middle = foldValue(gauge.from + foldValue(gauge.value - gauge.from, 0, gauge.max - gauge.min) / 2, gauge.min, gauge.max);
+		else middle = (gauge.from + gauge.value) / 2;
+	}
+	const along = gauge.positionOf(middle);
+	/** The point the bubble is pinned to, in client pixels. */
+	const pinned = () => {
+		if (position === "pointer") return pointer.current;
+		const ctm = anchor.current?.getScreenCTM();
+		if (!ctm) return null;
+		let p = {
+			x: 0,
+			y: 0
+		};
+		if (position === "value") p = gauge.scale.point(along, offset);
+		else if (position !== "center") {
+			const b = gauge.scale.box(offset);
+			const spot = boxPoints[position] ?? {
+				x: .5,
+				y: .5
+			};
+			p = {
+				x: b.x + b.width * spot.x,
+				y: b.y + b.height * spot.y
+			};
+		}
+		return new DOMPoint(p.x, p.y).matrixTransform(ctm);
+	};
+	/** The way the bubble stands off its point. */
+	const direction = () => {
+		if (side !== "auto") return sides[side];
+		if (position === "pointer") return sides.top;
+		if (position === "center") return sides.center;
+		if (position !== "value") {
+			const spot = boxPoints[position] ?? {
+				x: .5,
+				y: .5
+			};
+			return {
+				x: spot.x * 2 - 1,
+				y: spot.y * 2 - 1
+			};
+		}
+		const r = gauge.scale.normal(along);
+		const m = Math.max(Math.abs(r.x), Math.abs(r.y)) || 1;
+		return {
+			x: r.x / m,
+			y: r.y / m
+		};
+	};
+	const place = React.useEffectEvent(() => {
+		const el = box.current;
+		if (!el) return;
+		const p = pinned();
+		if (!p) {
+			el.style.visibility = "hidden";
+			return;
+		}
+		const size = {
+			width: el.offsetWidth,
+			height: el.offsetHeight
+		};
+		let d = direction();
+		let atPoint = corner(p, d, size, gap);
+		if (avoidCollisions) {
+			const view = {
+				width: document.documentElement.clientWidth,
+				height: document.documentElement.clientHeight
+			};
+			const pad = collisionPadding;
+			const spill = (spot, axis) => {
+				const span = size[extent[axis]];
+				const room = view[extent[axis]] - pad;
+				const out = Math.max(0, pad - spot[axis]) + Math.max(0, spot[axis] + span - room);
+				return Math.min(span, out);
+			};
+			for (const axis of ["x", "y"]) {
+				const before = spill(atPoint, axis);
+				if (before !== 0 && d[axis] !== 0) {
+					const flipped = {
+						...d,
+						[axis]: -d[axis]
+					};
+					const there = corner(p, flipped, size, gap);
+					if (spill(there, axis) < before) {
+						d = flipped;
+						atPoint = there;
+					}
+				}
+			}
+			const { width } = size;
+			if (p.x >= atPoint.x && p.x <= atPoint.x + width) {
+				const inside = Math.max(pad, Math.min(atPoint.x, view.width - pad - width));
+				atPoint = {
+					...atPoint,
+					x: Math.max(p.x - width, Math.min(inside, p.x))
+				};
+			}
+		}
+		el.style.visibility = "";
+		el.style.left = `${atPoint.x + window.scrollX}px`;
+		el.style.top = `${atPoint.y + window.scrollY}px`;
+	});
+	React.useEffect(() => {
+		const svg = anchor.current?.ownerSVGElement;
+		if (!svg) return;
+		const track = (e) => {
+			pointer.current = {
+				x: e.clientX,
+				y: e.clientY
+			};
+		};
+		const enter = (e) => {
+			track(e);
+			setHovered(true);
+		};
+		const move = (e) => {
+			track(e);
+			place();
+		};
+		const leave = () => setHovered(false);
+		const down = (e) => {
+			track(e);
+			setPressed(true);
+		};
+		svg.addEventListener("pointerenter", enter);
+		svg.addEventListener("pointermove", move);
+		svg.addEventListener("pointerleave", leave);
+		svg.addEventListener("pointerdown", down);
+		return () => {
+			svg.removeEventListener("pointerenter", enter);
+			svg.removeEventListener("pointermove", move);
+			svg.removeEventListener("pointerleave", leave);
+			svg.removeEventListener("pointerdown", down);
+		};
+	}, []);
+	React.useEffect(() => {
+		const owner = anchor.current?.ownerSVGElement?.closest(FOCUSABLE);
+		if (!owner) return;
+		const within = () => owner.contains(document.activeElement);
+		const check = () => setFocused(within() && Boolean(document.activeElement?.matches(":focus-visible:not([data-pointer])")));
+		const key = () => setFocused(within());
+		const blur = (e) => {
+			const next = e.relatedTarget;
+			if (!owner.contains(next)) setFocused(false);
+		};
+		check();
+		owner.addEventListener("focusin", check);
+		owner.addEventListener("keydown", key);
+		owner.addEventListener("focusout", blur);
+		return () => {
+			owner.removeEventListener("focusin", check);
+			owner.removeEventListener("keydown", key);
+			owner.removeEventListener("focusout", blur);
+		};
+	}, []);
+	React.useEffect(() => {
+		if (!pressed) return;
+		const move = (e) => {
+			pointer.current = {
+				x: e.clientX,
+				y: e.clientY
+			};
+			place();
+		};
+		const release = () => setPressed(false);
+		window.addEventListener("pointermove", move);
+		window.addEventListener("pointerup", release);
+		window.addEventListener("pointercancel", release);
+		return () => {
+			window.removeEventListener("pointermove", move);
+			window.removeEventListener("pointerup", release);
+			window.removeEventListener("pointercancel", release);
+		};
+	}, [pressed]);
+	React.useEffect(() => {
+		if (!shown) return;
+		const update = () => place();
+		window.addEventListener("scroll", update, true);
+		window.addEventListener("resize", update);
+		return () => {
+			window.removeEventListener("scroll", update, true);
+			window.removeEventListener("resize", update);
+		};
+	}, [shown]);
+	React.useLayoutEffect(() => {
+		if (shown) place();
+	});
+	const text = (v) => format ? format(v) : v.toFixed(decimals);
+	let content;
+	if (typeof children === "function") content = spread ? children(value, gauge.from) : children(value);
+	else content = children ?? /* @__PURE__ */ jsx(DefaultContent, {
+		text: spread ? `${text(gauge.from)}${separator}${text(value)}` : text(value),
+		label,
+		unit
+	});
+	return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("g", { ref: anchor }), shown && isClient && (0, import_react_dom.createPortal)(/* @__PURE__ */ jsx("div", {
+		ref: box,
+		className: gauge_module_default.TooltipPositioner,
+		children: /* @__PURE__ */ jsx("div", {
+			role: "tooltip",
+			"data-slot": "gauge-tooltip",
+			"data-elevation": "1",
+			style,
+			className: clsx(gauge_module_default.Tooltip, className),
+			children: content
+		})
+	}), document.body)] });
+};
+//#endregion
+export { GaugeTooltip };

package/dist/components/gauge/transition.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Dependency-free value animation for the gauge: a damped spring and a
+ * cubic-bezier tween, both stepped per frame. Pure functions only; the hook
+ * that drives them lives in `use-animated-value.ts`.
+ */
+/** A named curve, CSS-style cubic-bezier control points, or your own function. */
+export type GaugeEasing = 'linear' | 'easeIn' | 'easeOut' | 'easeInOut' | [number, number, number, number] | ((t: number) => number);
+export type GaugeSpringTransition = {
+    type: 'spring';
+    /**
+     * Physics parameters. When any is given they take precedence over the
+     * perceptual `visualDuration` and `bounce` pair.
+     */
+    stiffness?: number;
+    damping?: number;
+    mass?: number;
+    /** Seconds the spring visibly takes to reach the target. Default 0.5. */
+    visualDuration?: number;
+    /** 0 settles without overshoot, 1 rings freely. Default 0.1. */
+    bounce?: number;
+};
+export type GaugeTweenTransition = {
+    type: 'tween';
+    /** Seconds. Default 0.5. */
+    duration?: number;
+    /** Default "easeInOut". */
+    ease?: GaugeEasing;
+};
+export type GaugeTransition = GaugeSpringTransition | GaugeTweenTransition;
+export declare const DEFAULT_TRANSITION: GaugeSpringTransition;
+/** Turns the `transition` prop into a concrete config, or null when off. */
+export declare const resolveTransition: (transition: GaugeTransition | boolean | undefined) => GaugeTransition | null;
+export type SpringPhysics = {
+    stiffness: number;
+    damping: number;
+    mass: number;
+};
+/**
+ * Physics for a spring config. The perceptual pair maps onto stiffness and
+ * damping the same way the motion library does, so a spring tuned against
+ * that library feels the same here.
+ */
+export declare const springPhysics: (t: GaugeSpringTransition) => SpringPhysics;
+export type SpringState = {
+    value: number;
+    velocity: number;
+};
+/**
+ * Advances a spring by `dt` seconds towards `target` with semi-implicit
+ * Euler in small substeps, which stays stable for stiff springs. Returns the
+ * new state and whether it has come to rest within `precision`.
+ */
+export declare const stepSpring: (state: SpringState, target: number, physics: SpringPhysics, dt: number, precision: number) => {
+    state: SpringState;
+    done: boolean;
+};
+/** A CSS-compatible cubic-bezier easing function. */
+export declare const cubicBezier: (x1: number, y1: number, x2: number, y2: number) => (x: number) => number;
+/** Resolves any `GaugeEasing` into a function of progress. */
+export declare const easingFunction: (ease?: GaugeEasing) => (t: number) => number;

package/dist/components/gauge/transition.js

@@ -0,0 +1,129 @@
+//#region src/components/gauge/transition.ts
+var DEFAULT_TRANSITION = {
+	type: "spring",
+	visualDuration: .5,
+	bounce: .1
+};
+/** Turns the `transition` prop into a concrete config, or null when off. */
+var resolveTransition = (transition) => {
+	if (!transition) return null;
+	return transition === true ? DEFAULT_TRANSITION : transition;
+};
+/**
+* Physics for a spring config. The perceptual pair maps onto stiffness and
+* damping the same way the motion library does, so a spring tuned against
+* that library feels the same here.
+*/
+var springPhysics = (t) => {
+	if (t.stiffness !== void 0 || t.damping !== void 0 || t.mass !== void 0) return {
+		stiffness: t.stiffness ?? 100,
+		damping: t.damping ?? 10,
+		mass: t.mass ?? 1
+	};
+	const visualDuration = t.visualDuration ?? .5;
+	const bounce = t.bounce ?? .1;
+	const root = 2 * Math.PI / (visualDuration * 1.2);
+	const stiffness = root * root;
+	return {
+		stiffness,
+		damping: 2 * Math.min(1, Math.max(.05, 1 - bounce)) * Math.sqrt(stiffness),
+		mass: 1
+	};
+};
+var SUBSTEP = 1 / 240;
+/**
+* Advances a spring by `dt` seconds towards `target` with semi-implicit
+* Euler in small substeps, which stays stable for stiff springs. Returns the
+* new state and whether it has come to rest within `precision`.
+*/
+var stepSpring = (state, target, physics, dt, precision) => {
+	let { value, velocity } = state;
+	let remaining = Math.min(dt, .064);
+	while (remaining > 0) {
+		const h = Math.min(SUBSTEP, remaining);
+		const force = -physics.stiffness * (value - target) - physics.damping * velocity;
+		velocity += force / physics.mass * h;
+		value += velocity * h;
+		remaining -= h;
+	}
+	const done = Math.abs(value - target) < precision && Math.abs(velocity) < precision * 10;
+	return done ? {
+		state: {
+			value: target,
+			velocity: 0
+		},
+		done
+	} : {
+		state: {
+			value,
+			velocity
+		},
+		done
+	};
+};
+var namedCurves = {
+	linear: [
+		0,
+		0,
+		1,
+		1
+	],
+	easeIn: [
+		.42,
+		0,
+		1,
+		1
+	],
+	easeOut: [
+		0,
+		0,
+		.58,
+		1
+	],
+	easeInOut: [
+		.42,
+		0,
+		.58,
+		1
+	]
+};
+/** A CSS-compatible cubic-bezier easing function. */
+var cubicBezier = (x1, y1, x2, y2) => {
+	const bezier = (t, p1, p2) => {
+		const u = 1 - t;
+		return 3 * u * u * t * p1 + 3 * u * t * t * p2 + t * t * t;
+	};
+	const slope = (t, p1, p2) => {
+		const u = 1 - t;
+		return 3 * u * u * p1 + 6 * u * t * (p2 - p1) + 3 * t * t * (1 - p2);
+	};
+	return (x) => {
+		if (x <= 0) return 0;
+		if (x >= 1) return 1;
+		let t = x;
+		for (let i = 0; i < 8; i += 1) {
+			const dx = bezier(t, x1, x2) - x;
+			const d = slope(t, x1, x2);
+			if (Math.abs(dx) < 1e-6) return bezier(t, y1, y2);
+			if (Math.abs(d) < 1e-6) break;
+			t -= dx / d;
+		}
+		let lo = 0;
+		let hi = 1;
+		t = x;
+		while (hi - lo > 1e-6) {
+			if (bezier(t, x1, x2) < x) lo = t;
+			else hi = t;
+			t = (lo + hi) / 2;
+		}
+		return bezier(t, y1, y2);
+	};
+};
+/** Resolves any `GaugeEasing` into a function of progress. */
+var easingFunction = (ease = "easeInOut") => {
+	if (typeof ease === "function") return ease;
+	const [x1, y1, x2, y2] = Array.isArray(ease) ? ease : namedCurves[ease];
+	return cubicBezier(x1, y1, x2, y2);
+};
+//#endregion
+export { DEFAULT_TRANSITION, cubicBezier, easingFunction, resolveTransition, springPhysics, stepSpring };

package/dist/components/gauge/use-animated-value.d.ts

@@ -0,0 +1,14 @@
+import { GaugeTransition } from './transition';
+/**
+ * Follows `target` with the given transition and returns the value to draw
+ * this frame. With no transition it returns `target` as is and renders
+ * nothing extra. Honours `prefers-reduced-motion` by snapping.
+ *
+ * `span` is the size of the domain and sets the rest threshold. `initial` is
+ * where the value starts on mount, for a sweep-in from the minimum. `wrap`
+ * treats the domain as circular: every change is followed the shortest way
+ * round, so a heading crossing north never swings the long way back. The
+ * returned value may then sit outside the domain mid-flight; map it back
+ * with a modulo.
+ */
+export declare const useAnimatedValue: (target: number, transition: GaugeTransition | boolean | undefined, span: number, initial?: number, wrap?: boolean) => number;