@viraui/react 2026.10.0 → 2026.11.0-next.0

package/dist/components/gauge/needle.js

@@ -0,0 +1,162 @@
+"use client";
+import { polar, valueToTurnedAngle } from "./math.js";
+import { useRoundGauge } from "./context.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
+//#region src/components/gauge/needle.tsx
+var PRIMARY = "var(--global-primary)";
+var FOREGROUND = "var(--global-foreground)";
+var pts = (points) => points.map((p) => `${p.x},${p.y}`).join(" ");
+var NeedleShape = ({ kind = "line", length = .85, width = 6, color = PRIMARY, tail = 30, tailColor = color, tailDot = 0, turns = 1, end = "to" }) => {
+	const gauge = useRoundGauge("GaugeNeedle");
+	const { radius, min, max, startAngle, endAngle } = gauge;
+	const value = end === "from" ? gauge.from : gauge.value;
+	const angle = valueToTurnedAngle(value, min, max, startAngle, endAngle, turns);
+	const tip = polar(radius * length, angle);
+	const back = polar(-tail, angle);
+	const endDot = tail > 0 && tailDot > 0 ? /* @__PURE__ */ jsx("circle", {
+		cx: back.x,
+		cy: back.y,
+		r: tailDot,
+		fill: tailColor
+	}) : null;
+	if (kind === "arrow") {
+		const reach = radius * length;
+		const headLength = Math.min(width * 4, reach);
+		const base = polar(reach - headLength, angle);
+		const shaftLeft = polar(width / 2, angle - 90);
+		const shaftRight = polar(width / 2, angle + 90);
+		const headLeft = polar(width * 2, angle - 90);
+		const headRight = polar(width * 2, angle + 90);
+		const offset = (p, d) => ({
+			x: p.x + d.x,
+			y: p.y + d.y
+		});
+		return /* @__PURE__ */ jsxs("g", { children: [
+			tail > 0 && /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("polygon", {
+				points: pts([
+					shaftLeft,
+					shaftRight,
+					offset(back, shaftRight),
+					offset(back, shaftLeft)
+				]),
+				fill: tailColor
+			}), /* @__PURE__ */ jsx("circle", {
+				cx: back.x,
+				cy: back.y,
+				r: width / 2,
+				fill: tailColor
+			})] }),
+			/* @__PURE__ */ jsx("polygon", {
+				points: pts([
+					shaftLeft,
+					offset(base, shaftLeft),
+					offset(base, headLeft),
+					tip,
+					offset(base, headRight),
+					offset(base, shaftRight),
+					shaftRight
+				]),
+				fill: color
+			}),
+			endDot
+		] });
+	}
+	if (kind === "line") return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("line", {
+		x1: back.x,
+		y1: back.y,
+		x2: tip.x,
+		y2: tip.y,
+		stroke: color,
+		strokeWidth: width,
+		strokeLinecap: "round"
+	}), endDot] });
+	const left = polar(width / 2, angle - 90);
+	const right = polar(width / 2, angle + 90);
+	const endRadius = width * .2;
+	const endLeft = polar(endRadius, angle - 90);
+	const endRight = polar(endRadius, angle + 90);
+	const blade = (endPoint) => pts([
+		{
+			x: endPoint.x + endLeft.x,
+			y: endPoint.y + endLeft.y
+		},
+		{
+			x: endPoint.x + endRight.x,
+			y: endPoint.y + endRight.y
+		},
+		right,
+		left
+	]);
+	const rear = kind === "compass" ? blade(back) : pts([
+		{
+			x: back.x + left.x * .6,
+			y: back.y + left.y * .6
+		},
+		{
+			x: back.x + right.x * .6,
+			y: back.y + right.y * .6
+		},
+		right,
+		left
+	]);
+	return /* @__PURE__ */ jsxs("g", { children: [
+		tail > 0 && /* @__PURE__ */ jsx("polygon", {
+			points: rear,
+			fill: tailColor
+		}),
+		tail > 0 && kind === "compass" && /* @__PURE__ */ jsx("circle", {
+			cx: back.x,
+			cy: back.y,
+			r: endRadius,
+			fill: tailColor
+		}),
+		/* @__PURE__ */ jsx("polygon", {
+			points: blade(tip),
+			fill: color
+		}),
+		/* @__PURE__ */ jsx("circle", {
+			cx: tip.x,
+			cy: tip.y,
+			r: endRadius,
+			fill: color
+		}),
+		endDot
+	] });
+};
+/**
+* A needle pointing at the current value. Add a `GaugeHub` for the pivot, or
+* a `gap` to clear the centre for a readout instead.
+*/
+var GaugeNeedle = ({ gap = 0, ...props }) => {
+	const maskId = `gauge-needle-gap${React.useId().replace(/\W/g, "")}`;
+	if (gap <= 0) return /* @__PURE__ */ jsx(NeedleShape, { ...props });
+	return /* @__PURE__ */ jsxs("g", { children: [/* @__PURE__ */ jsxs("mask", {
+		id: maskId,
+		maskUnits: "userSpaceOnUse",
+		x: -1e4,
+		y: -1e4,
+		width: 2e4,
+		height: 2e4,
+		children: [/* @__PURE__ */ jsx("rect", {
+			x: -1e4,
+			y: -1e4,
+			width: 2e4,
+			height: 2e4,
+			fill: "white"
+		}), /* @__PURE__ */ jsx("circle", {
+			r: gap,
+			fill: "black"
+		})]
+	}), /* @__PURE__ */ jsx("g", {
+		mask: `url(#${maskId})`,
+		children: /* @__PURE__ */ jsx(NeedleShape, { ...props })
+	})] });
+};
+/** The pivot disc at the centre, drawn once however many needles there are. */
+var GaugeHub = ({ radius = 12, color = FOREGROUND }) => radius > 0 ? /* @__PURE__ */ jsx("circle", {
+	r: radius,
+	fill: color
+}) : null;
+//#endregion
+export { GaugeHub, GaugeNeedle };

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

@@ -0,0 +1,44 @@
+/**
+ * Arc scale for a round dial. Parts ask the scale where a domain position
+ * lands rather than doing polar math themselves.
+ *
+ * Positions are gauge degrees. An offset moves a point outward from the
+ * reference circle (away from centre).
+ */
+export type GaugePoint = {
+    x: number;
+    y: number;
+};
+export type GaugeBox = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type GaugeScale = {
+    /** Position of the start of the domain. */
+    start: number;
+    /** Position of the end of the domain. */
+    end: number;
+    /**
+     * The scale runs right round and meets itself, as a full ring does, so
+     * its two ends land on the same spot.
+     */
+    closed: boolean;
+    /** The point at a position, `offset` outward from the reference circle. */
+    point: (position: number, offset?: number) => GaugePoint;
+    /**
+     * SVG path along the scale between two positions, `offset` outward. Empty
+     * when `to` is not past `from`.
+     */
+    path: (from: number, to: number, offset?: number) => string;
+    /** The outward direction at a position, as a unit vector. */
+    normal: (position: number) => GaugePoint;
+    /**
+     * Box round the whole scale with its reference circle moved `offset`
+     * outward. Includes the centre, where a needle pivots.
+     */
+    box: (offset?: number) => GaugeBox;
+};
+/** A dial's scale: a circle of `radius` swept from one gauge angle to another. */
+export declare const arcScale: (radius: number, startAngle: number, endAngle: number) => GaugeScale;

package/dist/components/gauge/scale.js

@@ -0,0 +1,21 @@
+import { arcBox, arcPath, polar } from "./math.js";
+//#region src/components/gauge/scale.ts
+/**
+* Arc scale for a round dial. Parts ask the scale where a domain position
+* lands rather than doing polar math themselves.
+*
+* Positions are gauge degrees. An offset moves a point outward from the
+* reference circle (away from centre).
+*/
+/** A dial's scale: a circle of `radius` swept from one gauge angle to another. */
+var arcScale = (radius, startAngle, endAngle) => ({
+	start: startAngle,
+	end: endAngle,
+	closed: endAngle - startAngle >= 360,
+	point: (angle, offset = 0) => polar(radius + offset, angle),
+	path: (from, to, offset = 0) => arcPath(radius + offset, from, to),
+	normal: (angle) => polar(1, angle),
+	box: (offset = 0) => arcBox(radius + offset, startAngle, endAngle)
+});
+//#endregion
+export { arcScale };

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

@@ -0,0 +1,79 @@
+import { FontFamily, FontWeight, GaugeEnd, TextAnchor } from './utils';
+import * as React from 'react';
+export type GaugeTextProps = {
+    /**
+     * Position relative to the gauge centre in SVG units. Positive y is down.
+     * @defaultValue 0
+     */
+    x?: number;
+    /**
+     * Position relative to the gauge centre in SVG units. Positive y is down.
+     * @defaultValue 0
+     */
+    y?: number;
+    /**
+     * Font size in SVG units.
+     * @defaultValue 24
+     */
+    fontSize?: number;
+    /**
+     * Fill colour. Unset uses theme foreground.
+     * @defaultValue `var(--global-foreground)`
+     */
+    color?: string;
+    /**
+     * Typeface map: sans/rounded → body; mono → mono token.
+     * @defaultValue `'sans'`
+     */
+    font?: FontFamily;
+    /**
+     * Font weight token.
+     * @defaultValue `'medium'`
+     */
+    weight?: FontWeight;
+    /**
+     * Which edge of the text sits at `(x, y)`.
+     * @defaultValue `'middle'`
+     */
+    anchor?: TextAnchor;
+    /**
+     * Extra class names on the SVG `text` node.
+     * @defaultValue undefined
+     */
+    className?: string;
+    /**
+     * Inline styles merged onto the SVG `text` node (e.g. tabular nums).
+     * @defaultValue undefined
+     */
+    style?: React.CSSProperties;
+    /**
+     * Label content.
+     */
+    children: React.ReactNode;
+};
+/** A free-standing label anywhere on the gauge. */
+export declare const GaugeText: React.FC<GaugeTextProps>;
+export type GaugeValueProps = Omit<GaugeTextProps, 'children'> & {
+    /**
+     * Fixed decimal places when `format` is omitted.
+     * @defaultValue 0
+     */
+    decimals?: number;
+    /**
+     * Formats each number shown; a range formats its two ends apart.
+     * @defaultValue `value.toFixed(decimals)`
+     */
+    format?: (value: number) => string;
+    /**
+     * Placed between the two ends of a range.
+     * @defaultValue `'–'`
+     */
+    separator?: string;
+    /**
+     * Show only one end of a range rather than both.
+     * @defaultValue both ends when `range`, else `value`
+     */
+    end?: GaugeEnd;
+};
+/** The current value as text, or a range as its two ends. */
+export declare const GaugeValue: React.FC<GaugeValueProps>;

package/dist/components/gauge/text.js

@@ -0,0 +1,42 @@
+"use client";
+import { useGauge } from "./context.js";
+import { fontFamily, fontWeight } from "./utils.js";
+import { jsx } from "react/jsx-runtime";
+import "react";
+//#region src/components/gauge/text.tsx
+var FOREGROUND = "var(--global-foreground)";
+/** A free-standing label anywhere on the gauge. */
+var GaugeText = ({ x = 0, y = 0, fontSize = 24, color = FOREGROUND, font = "sans", weight = "medium", anchor = "middle", className, style, children }) => /* @__PURE__ */ jsx("text", {
+	x,
+	y,
+	fill: color,
+	fontSize,
+	fontFamily: fontFamily(font),
+	fontWeight: fontWeight(weight),
+	textAnchor: anchor,
+	dominantBaseline: "central",
+	className,
+	style,
+	children
+});
+/** The current value as text, or a range as its two ends. */
+var GaugeValue = ({ decimals = 0, format, separator = "–", end, className, style, fontSize = 96, weight = "semibold", ...props }) => {
+	const { value, from, range } = useGauge();
+	const text = (v) => format ? format(v) : v.toFixed(decimals);
+	let valueText = text(value);
+	if (end === "from") valueText = text(from);
+	else if (range && !end) valueText = `${text(from)}${separator}${text(value)}`;
+	return /* @__PURE__ */ jsx(GaugeText, {
+		fontSize,
+		weight,
+		className,
+		style: {
+			fontVariantNumeric: "tabular-nums",
+			...style
+		},
+		...props,
+		children: valueText
+	});
+};
+//#endregion
+export { GaugeText, GaugeValue };

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

@@ -0,0 +1,169 @@
+import { FontFamily, FontWeight, StrokeCap, TextAnchor, ValueColor } from './utils';
+import * as React from 'react';
+type CrossLineProps = {
+    /**
+     * Length of each line across the scale: along the radius of a dial.
+     * @defaultValue 12
+     */
+    length?: number;
+    /**
+     * Stroke width of each tick line.
+     * @defaultValue 2
+     */
+    width?: number;
+    /**
+     * One colour, or a function of each line's value to colour some apart:
+     * the ticks inside a range, or each in the colour of its zone.
+     * @defaultValue `var(--global-foreground)`
+     */
+    color?: ValueColor;
+    /**
+     * Stroke opacity for the tick group.
+     * @defaultValue 1
+     */
+    opacity?: number;
+    /**
+     * Stroke line cap.
+     * @defaultValue `'round'`
+     */
+    cap?: StrokeCap;
+    /**
+     * Offset of the line's midpoint from the scale's reference line.
+     * @defaultValue 0
+     */
+    offset?: number;
+};
+export type GaugeTicksProps = CrossLineProps & {
+    /**
+     * Number of intervals across the domain; renders `count + 1` ticks.
+     * @defaultValue 10
+     */
+    count?: number;
+};
+/** Evenly spaced tick marks along the whole scale. */
+export declare const GaugeTicks: React.FC<GaugeTicksProps>;
+export type GaugeTickFillProps = Omit<CrossLineProps, 'color'> & {
+    /**
+     * Number of intervals across the domain; renders `count + 1` ticks.
+     * @defaultValue 40
+     */
+    count?: number;
+    /**
+     * Where the lit stretch starts. Defaults to the start of the gauge's
+     * range, or `min` on a single value.
+     * @defaultValue gauge `from`
+     */
+    from?: number;
+    /**
+     * Where it ends. Defaults to the current value, or a range's far end.
+     * @defaultValue current gauge `value`
+     */
+    to?: number;
+    /**
+     * `fill` lights every tick from `from` to `to`, as an arc would fill.
+     * `nearest` lights only the tick nearest each end: on a single value a
+     * pointer made of ticks, on a range one at either end.
+     * @defaultValue `'fill'`
+     */
+    mode?: 'fill' | 'nearest';
+    /**
+     * Colour of the lit ticks: one, or a function of each tick's value, so a
+     * fill can run through zones or a gradient.
+     * @defaultValue `var(--global-foreground)`
+     */
+    color?: ValueColor;
+    /**
+     * Colour of the ticks left unlit. Defaults to a faint theme foreground.
+     * @defaultValue `fadeColor('var(--global-foreground)', 15)`
+     */
+    dimColor?: ValueColor;
+    /**
+     * Length of a lit tick, for meters whose live segments stand out.
+     * Defaults to `length`.
+     * @defaultValue same as `length`
+     */
+    litLength?: number;
+};
+/**
+ * Ticks that are the fill: the whole sweep is ticked, and those between the
+ * ends of the value are lit while the rest stay dim. It follows the value
+ * frame by frame as `GaugeArc` does, fills a range between its ends, and on
+ * a wrapped gauge runs forward from the start across the seam. With
+ * `mode="nearest"` it lights a single tick at each end instead, for a
+ * pointer drawn in ticks. Lit and dim colours can each be a function of the
+ * tick's value, so one primitive covers segmented meters, LED rings, zoned
+ * dials and dot-matrix pointers.
+ */
+export declare const GaugeTickFill: React.FC<GaugeTickFillProps>;
+export type GaugeMarksProps = CrossLineProps & {
+    /**
+     * Domain values to mark, for example the cutoffs between zones.
+     * @defaultValue derived from `count`, or empty
+     */
+    values?: number[];
+    /**
+     * Cut the domain into this many equal segments instead: the marks fall
+     * between the segments, none at the two ends. On a closed ring the seam is
+     * cut too, since the last segment meets the first there. Drawn in the
+     * surface's colour over a band, they slice it the way a water ring is cut
+     * into glasses.
+     * @defaultValue omitted (use `values`)
+     */
+    count?: number;
+};
+/**
+ * Marks across the scale at arbitrary domain values, or at equal cuts of
+ * the domain.
+ */
+export declare const GaugeMarks: React.FC<GaugeMarksProps>;
+export type GaugeTickLabelsProps = {
+    /**
+     * Number of intervals across the domain; renders `count + 1` labels.
+     * @defaultValue 10
+     */
+    count?: number;
+    /**
+     * Offset of the label from the scale's reference line.
+     * @defaultValue -48
+     */
+    offset?: number;
+    /**
+     * Which edge of each label sits at its point: `end` lines labels up
+     * against the left of a vertical bar.
+     * @defaultValue `'middle'`
+     */
+    anchor?: TextAnchor;
+    /**
+     * Font size in SVG units.
+     * @defaultValue 16
+     */
+    fontSize?: number;
+    /**
+     * One colour, or a function of each label's value.
+     * @defaultValue `var(--global-foreground)`
+     */
+    color?: ValueColor;
+    /**
+     * Typeface map: sans/rounded → body; mono → mono token.
+     * @defaultValue `'sans'`
+     */
+    font?: FontFamily;
+    /**
+     * Font weight token.
+     * @defaultValue `'medium'`
+     */
+    weight?: FontWeight;
+    /**
+     * Fixed decimal places when `format` is omitted.
+     * @defaultValue 0
+     */
+    decimals?: number;
+    /**
+     * Custom label formatter. Overrides `decimals` when set.
+     * @defaultValue `value.toFixed(decimals)`
+     */
+    format?: (value: number) => string;
+};
+/** Numeric labels at evenly spaced values along the scale. */
+export declare const GaugeTickLabels: React.FC<GaugeTickLabelsProps>;
+export {};

package/dist/components/gauge/ticks.js

@@ -0,0 +1,124 @@
+"use client";
+import { cutValues, foldValue, stepValues } from "./math.js";
+import { useGauge } from "./context.js";
+import { fadeColor, fontFamily, fontWeight } from "./utils.js";
+import { jsx } from "react/jsx-runtime";
+import "react";
+//#region src/components/gauge/ticks.tsx
+var FOREGROUND = "var(--global-foreground)";
+/**
+* Evenly spaced domain values for ticks. On a closed ring the last step lands
+* on the first, so it is dropped rather than drawn twice.
+*/
+var tickValues = ({ min, max, scale }, count) => {
+	const values = stepValues(min, max, count);
+	if (scale.closed) values.pop();
+	return values;
+};
+/** Lines standing across the scale at domain values, as ticks do. */
+var CrossLines = ({ values, length = 12, lengthOf, width = 2, color = FOREGROUND, opacity = 1, cap = "round", offset = 0 }) => {
+	const { scale, positionOf } = useGauge();
+	const each = typeof color === "function" ? color : void 0;
+	return /* @__PURE__ */ jsx("g", {
+		stroke: typeof color === "string" ? color : void 0,
+		strokeOpacity: opacity,
+		strokeWidth: width,
+		strokeLinecap: cap,
+		children: values.map((value) => {
+			const half = (lengthOf?.(value) ?? length) / 2;
+			const a = scale.point(positionOf(value), offset - half);
+			const b = scale.point(positionOf(value), offset + half);
+			return /* @__PURE__ */ jsx("line", {
+				x1: a.x,
+				y1: a.y,
+				x2: b.x,
+				y2: b.y,
+				stroke: each?.(value)
+			}, value);
+		})
+	});
+};
+/** Evenly spaced tick marks along the whole scale. */
+var GaugeTicks = ({ count = 10, ...props }) => {
+	const gauge = useGauge();
+	return /* @__PURE__ */ jsx(CrossLines, {
+		values: tickValues(gauge, count),
+		...props
+	});
+};
+/**
+* Ticks that are the fill: the whole sweep is ticked, and those between the
+* ends of the value are lit while the rest stay dim. It follows the value
+* frame by frame as `GaugeArc` does, fills a range between its ends, and on
+* a wrapped gauge runs forward from the start across the seam. With
+* `mode="nearest"` it lights a single tick at each end instead, for a
+* pointer drawn in ticks. Lit and dim colours can each be a function of the
+* tick's value, so one primitive covers segmented meters, LED rings, zoned
+* dials and dot-matrix pointers.
+*/
+var GaugeTickFill = ({ count = 40, from, to, mode = "fill", color = FOREGROUND, dimColor = fadeColor(FOREGROUND, 15), length = 12, litLength = length, ...props }) => {
+	const gauge = useGauge();
+	const values = tickValues(gauge, count);
+	const tail = from ?? gauge.from;
+	const head = to ?? gauge.value;
+	const span = Math.abs(gauge.max - gauge.min);
+	const eps = span * 1e-6;
+	const ahead = (v) => foldValue(v - tail + eps, 0, span);
+	const between = (v) => gauge.wrap ? ahead(v) <= ahead(head) + eps : v >= Math.min(tail, head) - eps && v <= Math.max(tail, head) + eps;
+	const nearestTo = (target) => {
+		const gap = (v) => {
+			const d = Math.abs(v - target);
+			return gauge.wrap ? Math.min(d, span - d) : d;
+		};
+		return values.reduce((best, v) => gap(v) < gap(best) ? v : best);
+	};
+	const ends = mode === "nearest" ? new Set(gauge.range || from !== void 0 ? [nearestTo(tail), nearestTo(head)] : [nearestTo(head)]) : null;
+	const lit = new Map(values.map((v) => [v, ends ? ends.has(v) : between(v)]));
+	const paint = (c, v) => typeof c === "function" ? c(v) : c;
+	return /* @__PURE__ */ jsx(CrossLines, {
+		values,
+		length,
+		lengthOf: (v) => lit.get(v) ? litLength : length,
+		color: (v) => paint(lit.get(v) ? color : dimColor, v),
+		...props
+	});
+};
+/**
+* Marks across the scale at arbitrary domain values, or at equal cuts of
+* the domain.
+*/
+var GaugeMarks = ({ values, count, ...props }) => {
+	const { min, max, scale } = useGauge();
+	const marks = values ?? (count && count > 1 ? [...scale.closed ? [min] : [], ...cutValues(min, max, count)] : []);
+	return /* @__PURE__ */ jsx(CrossLines, {
+		values: marks,
+		...props
+	});
+};
+/** Numeric labels at evenly spaced values along the scale. */
+var GaugeTickLabels = ({ count = 10, offset = -48, anchor = "middle", fontSize = 16, color = FOREGROUND, font = "sans", weight = "medium", decimals = 0, format }) => {
+	const gauge = useGauge();
+	const { scale, positionOf } = gauge;
+	const values = tickValues(gauge, count);
+	const each = typeof color === "function" ? color : void 0;
+	return /* @__PURE__ */ jsx("g", {
+		fill: typeof color === "string" ? color : void 0,
+		fontSize,
+		fontFamily: fontFamily(font),
+		fontWeight: fontWeight(weight),
+		textAnchor: anchor,
+		dominantBaseline: "central",
+		style: { fontVariantNumeric: "tabular-nums" },
+		children: values.map((value) => {
+			const p = scale.point(positionOf(value), offset);
+			return /* @__PURE__ */ jsx("text", {
+				x: p.x,
+				y: p.y,
+				fill: each?.(value),
+				children: format ? format(value) : value.toFixed(decimals)
+			}, value);
+		})
+	});
+};
+//#endregion
+export { GaugeMarks, GaugeTickFill, GaugeTickLabels, GaugeTicks };