@viraui/react 2026.10.0 → 2026.11.0-next.0

package/dist/components/gauge/demos/timer.d.ts

@@ -0,0 +1,9 @@
+type TimerDemoProps = {
+    value?: number;
+    min?: number;
+    max?: number;
+    label?: string;
+};
+/** Upstream rings/timer — 60s ring, major/minor ticks, mono sec readout. */
+export declare function TimerDemo({ value, min, max, label }: TimerDemoProps): import('react').JSX.Element;
+export {};

package/dist/components/gauge/demos/volume.d.ts

@@ -0,0 +1,10 @@
+import * as React from 'react';
+type VolumeDemoProps = {
+    value?: number;
+    min?: number;
+    max?: number;
+    label?: string;
+};
+/** Upstream arcs/volume — knob face, thin outer scale, grip dot. */
+export declare function VolumeDemo({ value: valueProp, min, max, label }: VolumeDemoProps): React.JSX.Element;
+export {};

package/dist/components/gauge/demos/wind.d.ts

@@ -0,0 +1,9 @@
+type WindDemoProps = {
+    value?: number;
+    min?: number;
+    max?: number;
+    label?: string;
+};
+/** Upstream needles/wind — arrow vane, compass ticks; fixed speed in hub gap. */
+export declare function WindDemo({ value, min, max, label }: WindDemoProps): import('react').JSX.Element;
+export {};

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

@@ -0,0 +1,55 @@
+import { GaugeEnd } from './utils';
+import * as React from 'react';
+export type GaugeDotProps = {
+    /**
+     * Radius of the dot itself, in SVG units.
+     * @defaultValue 10
+     */
+    radius?: number;
+    /**
+     * Fill colour. Unset uses theme primary.
+     * @defaultValue `var(--global-primary)`
+     */
+    color?: string;
+    /**
+     * Fill opacity for the dot and optional halo.
+     * @defaultValue 1
+     */
+    opacity?: number;
+    /**
+     * Offset of the dot's centre from the scale's reference line.
+     * @defaultValue 0
+     */
+    offset?: number;
+    /**
+     * Sweeps of the scale the dot makes across the domain, as
+     * `GaugeNeedle.turns`: two sends it round twice while the value crosses
+     * the domain once.
+     * @defaultValue 1
+     */
+    turns?: number;
+    /**
+     * Width of a ring drawn behind the dot in `haloColor`, so it stands off
+     * whatever band it rides. 0 leaves the dot bare.
+     * @defaultValue 0
+     */
+    halo?: number;
+    /**
+     * Colour of the halo: the surface under the gauge, usually.
+     * @defaultValue `var(--global-background)`
+     */
+    haloColor?: string;
+    /**
+     * Which end of a range the dot rides. Two dots, one at each end, make
+     * the handles of a range.
+     * @defaultValue `'to'`
+     */
+    end?: GaugeEnd;
+};
+/**
+ * A disc riding the scale at the current value: the head of a progress ring,
+ * a body on its orbit, the handle on a dial or a slider. `GaugeMarks` stands at fixed values
+ * and points along the radius; this follows the value the way a needle does,
+ * and is round at any size a stroke cap could not reach.
+ */
+export declare const GaugeDot: React.FC<GaugeDotProps>;

package/dist/components/gauge/dot.js

@@ -0,0 +1,34 @@
+"use client";
+import { valueToTurnedAngle } from "./math.js";
+import { useGauge } from "./context.js";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import "react";
+//#region src/components/gauge/dot.tsx
+var PRIMARY = "var(--global-primary)";
+var BACKGROUND = "var(--global-background)";
+/**
+* A disc riding the scale at the current value: the head of a progress ring,
+* a body on its orbit, the handle on a dial or a slider. `GaugeMarks` stands at fixed values
+* and points along the radius; this follows the value the way a needle does,
+* and is round at any size a stroke cap could not reach.
+*/
+var GaugeDot = ({ radius = 10, color = PRIMARY, opacity = 1, offset = 0, turns = 1, halo = 0, haloColor = BACKGROUND, end = "to" }) => {
+	const gauge = useGauge();
+	const position = valueToTurnedAngle(end === "from" ? gauge.from : gauge.value, gauge.min, gauge.max, gauge.scale.start, gauge.scale.end, turns);
+	const { x, y } = gauge.scale.point(position, offset);
+	return /* @__PURE__ */ jsxs(Fragment, { children: [halo > 0 && /* @__PURE__ */ jsx("circle", {
+		cx: x,
+		cy: y,
+		r: radius + halo,
+		fill: haloColor,
+		fillOpacity: opacity
+	}), /* @__PURE__ */ jsx("circle", {
+		cx: x,
+		cy: y,
+		r: radius,
+		fill: color,
+		fillOpacity: opacity
+	})] });
+};
+//#endregion
+export { GaugeDot };

package/dist/components/gauge/gauge.css

@@ -0,0 +1 @@
+@layer viraui.preflight, viraui.components, viraui.overrides;@layer viraui.components{@property --vui-gauge-aspect-ratio{syntax:"*";inherits:false;initial-value:1}.viraui__gauge-module__Gauge_XrCKK{overflow:visible;color:var(--global-foreground);&[data-fit=square]{inline-size:100%;block-size:100%}&[data-fit=content]{inline-size:100%;max-block-size:100%;aspect-ratio:var(--vui-gauge-aspect-ratio)}}.viraui__gauge-module__Control_33uqc{position:relative;touch-action:none;-webkit-user-select:none;user-select:none;outline:none;cursor:grab;aspect-ratio:1;border-radius:var(--radius-full);&[data-disabled=true]{cursor:default}&:not([data-disabled=true]):active{cursor:grabbing}&:focus-visible,&:has(:focus-visible:not([data-pointer])){outline:var(--outline);outline-offset:var(--outline-offset)}}.viraui__gauge-module__VisuallyHidden_LUbhj{position:absolute;inline-size:1px;block-size:1px;padding:0;margin:-1px;overflow:hidden;clip-path:inset(50%);white-space:nowrap;border:0;&:focus-visible{outline:none}}.viraui__gauge-module__TooltipPositioner_5wZsF{position:absolute;inset-block-start:0;inset-inline-start:0;z-index:50;pointer-events:none}.viraui__gauge-module__Tooltip_BRUR6{box-sizing:border-box;inline-size:max-content;max-inline-size:20rem;padding-block:var(--space-2xs);padding-inline:var(--space-s);border-radius:var(--radius-m);background:var(--global-foreground);color:var(--global-background);font-size:var(--font-scale-body-s);animation:viraui__gauge-module__gauge-tooltip-in_5JTLs var(--duration-fast) var(--easing-entrance);@media (prefers-reduced-motion:reduce){animation:none}}.viraui__gauge-module__TooltipBody_44-M9{display:flex;flex-direction:column;align-items:center;line-height:1.15}.viraui__gauge-module__TooltipLabel_T-Hp5{opacity:.7}.viraui__gauge-module__TooltipValue_gAqRL{font-size:var(--font-scale-body-m);font-weight:600;font-variation-settings:"wght" 600;font-variant-numeric:tabular-nums}.viraui__gauge-module__TooltipUnit_iIW0i{margin-inline-start:var(--space-2xs);font-size:var(--font-scale-body-s);font-weight:500;font-variation-settings:"wght" 500;opacity:.7}@keyframes viraui__gauge-module__gauge-tooltip-in_5JTLs{0%{opacity:0;transform:scale(.95)}to{opacity:1;transform:scale(1)}}}

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

@@ -0,0 +1,84 @@
+import { GaugeDomainProps, GaugeRange } from './context';
+import { GaugeTransition } from './transition';
+import * as React from 'react';
+/** See `GaugeProps.fit`. */
+export type GaugeFit = 'square' | 'content';
+export type GaugeProps = Omit<React.ComponentPropsWithRef<'svg'>, 'viewBox'> & GaugeDomainProps & {
+    /**
+     * Extra room around the reference circle for thick strokes, ticks and labels.
+     * @defaultValue 48
+     */
+    padding?: number;
+    /**
+     * How the SVG box is sized. `square` boxes the whole circle, so a half gauge
+     * reserves the room a full one would. `content` fits the box to the arc's own
+     * sweep and sets a matching aspect-ratio via `--vui-gauge-aspect-ratio`, so the
+     * dial fills the width it is given. `padding` is still what makes room for ticks,
+     * labels and value text, since those are drawn by children the root cannot measure.
+     * @defaultValue 'square'
+     */
+    fit?: GaugeFit;
+    /**
+     * Accessible name for the meter reading. When omitted, pass `aria-label`
+     * (or another naming technique) on the host SVG.
+     * @defaultValue undefined — no `aria-label` from this prop
+     */
+    label?: string;
+    /**
+     * The reading, or a `[from, to]` range to fill between.
+     * @defaultValue Required — no default.
+     */
+    value: number | GaugeRange;
+    /**
+     * Lower bound of the domain.
+     * @defaultValue 0
+     */
+    min?: number;
+    /**
+     * Upper bound of the domain.
+     * @defaultValue 100
+     */
+    max?: number;
+    /**
+     * Animate towards new values. `true` uses a gentle spring; pass a
+     * `GaugeTransition` to tune it or switch to a timed tween.
+     * @defaultValue undefined — instant updates
+     */
+    transition?: GaugeTransition | boolean;
+    /**
+     * Where the value starts on mount when animating.
+     * @defaultValue undefined — starts at the target value
+     */
+    initialValue?: number | GaugeRange;
+    /**
+     * Treat the domain as circular (shortest-path animation across the seam).
+     * @defaultValue false
+     */
+    wrap?: boolean;
+    /**
+     * Gauge degrees, clockwise from six o'clock — sweep start.
+     * @defaultValue 40
+     */
+    startAngle?: number;
+    /**
+     * Gauge degrees, clockwise from six o'clock — sweep end.
+     * @defaultValue 320
+     */
+    endAngle?: number;
+    /**
+     * Reference radius in SVG units.
+     * @defaultValue 200
+     */
+    radius?: number;
+    /**
+     * Turn the whole scale this many degrees clockwise.
+     * @defaultValue 0
+     */
+    rotate?: number;
+};
+/**
+ * Root of a composable gauge. Renders an SVG centred on the origin and
+ * publishes the value, domain and geometry to any primitive rendered inside.
+ * Exposes APG meter semantics on the host; decorative children have no roles.
+ */
+export declare const Gauge: React.FC<GaugeProps>;

package/dist/components/gauge/gauge.js

@@ -0,0 +1,62 @@
+"use client";
+import './gauge.css';
+import { clsx } from "../../core/clsx.js";
+import { arcBox } from "./math.js";
+import { GaugeContext, useGaugeContextValue } from "./context.js";
+import gauge_module_default from "./gauge.module.js";
+import { jsx } from "react/jsx-runtime";
+import "react";
+//#region src/components/gauge/gauge.tsx
+/**
+* Root of a composable gauge. Renders an SVG centred on the origin and
+* publishes the value, domain and geometry to any primitive rendered inside.
+* Exposes APG meter semantics on the host; decorative children have no roles.
+*/
+var Gauge = ({ value, min, max, startAngle, endAngle, radius, transition, initialValue, wrap, rotate, padding = 48, fit = "square", label, className, style, children, ...otherProps }) => {
+	const gauge = useGaugeContextValue({
+		value,
+		min,
+		max,
+		startAngle,
+		endAngle,
+		radius,
+		transition,
+		initialValue,
+		wrap,
+		rotate
+	});
+	const half = gauge.radius + padding;
+	const box = fit === "content" ? arcBox(gauge.radius, gauge.startAngle, gauge.endAngle, padding) : {
+		x: -half,
+		y: -half,
+		width: 2 * half,
+		height: 2 * half
+	};
+	const dynamicStyle = {
+		...style,
+		...fit === "content" && { "--vui-gauge-aspect-ratio": `${box.width} / ${box.height}` }
+	};
+	const meterProps = otherProps["aria-hidden"] === true || otherProps["aria-hidden"] === "true" ? {} : {
+		role: "meter",
+		...label != null ? { "aria-label": label } : {},
+		"aria-valuemin": gauge.min,
+		"aria-valuemax": gauge.max,
+		"aria-valuenow": gauge.target,
+		...gauge.range ? { "aria-valuetext": `${gauge.targetFrom} to ${gauge.target}` } : {}
+	};
+	return /* @__PURE__ */ jsx(GaugeContext.Provider, {
+		value: gauge,
+		children: /* @__PURE__ */ jsx("svg", {
+			...otherProps,
+			viewBox: `${box.x} ${box.y} ${box.width} ${box.height}`,
+			preserveAspectRatio: "xMidYMid meet",
+			...meterProps,
+			className: clsx(gauge_module_default.Gauge, className),
+			"data-fit": fit,
+			style: dynamicStyle,
+			children
+		})
+	});
+};
+//#endregion
+export { Gauge };

package/dist/components/gauge/gauge.module.js

@@ -0,0 +1,24 @@
+//#region src/components/gauge/gauge.module.css
+var Gauge = "viraui__gauge-module__Gauge_XrCKK";
+var Control = "viraui__gauge-module__Control_33uqc";
+var VisuallyHidden = "viraui__gauge-module__VisuallyHidden_LUbhj";
+var TooltipPositioner = "viraui__gauge-module__TooltipPositioner_5wZsF";
+var Tooltip = "viraui__gauge-module__Tooltip_BRUR6";
+var TooltipBody = "viraui__gauge-module__TooltipBody_44-M9";
+var TooltipLabel = "viraui__gauge-module__TooltipLabel_T-Hp5";
+var TooltipValue = "viraui__gauge-module__TooltipValue_gAqRL";
+var TooltipUnit = "viraui__gauge-module__TooltipUnit_iIW0i";
+var gauge_module_default = {
+	Gauge,
+	Control,
+	VisuallyHidden,
+	TooltipPositioner,
+	Tooltip,
+	"gauge-tooltip-in": "viraui__gauge-module__gauge-tooltip-in_5JTLs",
+	TooltipBody,
+	TooltipLabel,
+	TooltipValue,
+	TooltipUnit
+};
+//#endregion
+export { Control, Gauge, Tooltip, TooltipBody, TooltipLabel, TooltipPositioner, TooltipUnit, TooltipValue, VisuallyHidden, gauge_module_default as default };

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

@@ -0,0 +1,15 @@
+export { Gauge, type GaugeFit, type GaugeProps } from './gauge';
+export { GaugeInset, type GaugeInsetProps } from './inset';
+export { useGauge, useRoundGauge, type GaugeContextValue, type GaugeDomainProps, type GaugeRange, type GaugeReading, type GaugeReadingProps, type GaugeRoundShape, } from './context';
+export { arcScale, type GaugeBox, type GaugePoint, type GaugeScale } from './scale';
+export { GaugeTrack, GaugeArc, GaugeStack, GaugeZones, type GaugeArcProps, type GaugeStackPart, type GaugeStackProps, type GaugeZonesProps, } from './arcs';
+export { GaugeControl, type GaugeControlProps } from './control';
+export { GaugeTicks, GaugeTickFill, GaugeMarks, GaugeTickLabels, type GaugeTicksProps, type GaugeTickFillProps, type GaugeMarksProps, type GaugeTickLabelsProps, } from './ticks';
+export { GaugeText, GaugeValue, type GaugeTextProps, type GaugeValueProps } from './text';
+export { GaugeDot, type GaugeDotProps } from './dot';
+export { GaugeTooltip, type GaugeTooltipPosition, type GaugeTooltipProps, type GaugeTooltipSide } from './tooltip';
+export { GaugeNeedle, GaugeHub, type GaugeNeedleProps, type GaugeHubProps } from './needle';
+export { angleToValue, arcBox, arcPath, clamp, cutValues, degreesToRadians, foldValue, polar, stepValues, valueToAngle, valueToTurnedAngle, } from './math';
+export { clockLabel, clockTime, compassLabel, durationLabel, fadeColor, fontFamily, fontWeight, zoneColor, zoneCutoffs, type FontFamily, type FontWeight, type GaugeEnd, type NeedleStyle, type StrokeCap, type TextAnchor, type ValueColor, type Zone, } from './utils';
+export { DEFAULT_TRANSITION, cubicBezier, easingFunction, resolveTransition, springPhysics, stepSpring, type GaugeEasing, type GaugeSpringTransition, type GaugeTransition, type GaugeTweenTransition, } from './transition';
+export { useAnimatedValue } from './use-animated-value';

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

@@ -0,0 +1,30 @@
+import { GaugeDomainProps } from './context';
+import * as React from 'react';
+export type GaugeInsetProps = Omit<React.ComponentPropsWithRef<'g'>, 'transform'> & GaugeDomainProps & {
+    /**
+     * Centre of the inset in the host gauge's SVG units. Positive y is down.
+     * @defaultValue 0
+     */
+    x?: number;
+    /**
+     * Centre of the inset in the host gauge's SVG units. Positive y is down.
+     * @defaultValue 0
+     */
+    y?: number;
+    /**
+     * Size relative to the host gauge: 0.3 draws it at a third of the size.
+     * @defaultValue 1
+     */
+    scale?: number;
+};
+/**
+ * A whole gauge drawn inside another one: a fuel dial under a speedometer, a
+ * second ring inside the first. It takes its own value and domain and sets up
+ * the same context `Gauge` does, so every primitive works inside it unchanged.
+ *
+ * It draws in the host's coordinate system rather than its own viewport, so it
+ * needs no `padding` or `fit`; `x`, `y` and `scale` place it, and everything
+ * inside — strokes, ticks, text — shrinks with it. Its reference radius stays
+ * the host's by default, which makes `scale` the only size to reason about.
+ */
+export declare const GaugeInset: React.FC<GaugeInsetProps>;

package/dist/components/gauge/inset.js

@@ -0,0 +1,39 @@
+"use client";
+import { GaugeContext, useGaugeContextValue } from "./context.js";
+import { jsx } from "react/jsx-runtime";
+import "react";
+//#region src/components/gauge/inset.tsx
+/**
+* A whole gauge drawn inside another one: a fuel dial under a speedometer, a
+* second ring inside the first. It takes its own value and domain and sets up
+* the same context `Gauge` does, so every primitive works inside it unchanged.
+*
+* It draws in the host's coordinate system rather than its own viewport, so it
+* needs no `padding` or `fit`; `x`, `y` and `scale` place it, and everything
+* inside — strokes, ticks, text — shrinks with it. Its reference radius stays
+* the host's by default, which makes `scale` the only size to reason about.
+*/
+var GaugeInset = ({ value, min, max, startAngle, endAngle, radius, transition, initialValue, wrap, rotate, x = 0, y = 0, scale = 1, children, ...otherProps }) => {
+	const gauge = useGaugeContextValue({
+		value,
+		min,
+		max,
+		startAngle,
+		endAngle,
+		radius,
+		transition,
+		initialValue,
+		wrap,
+		rotate
+	});
+	return /* @__PURE__ */ jsx(GaugeContext.Provider, {
+		value: gauge,
+		children: /* @__PURE__ */ jsx("g", {
+			transform: `translate(${x} ${y}) scale(${scale})`,
+			...otherProps,
+			children
+		})
+	});
+};
+//#endregion
+export { GaugeInset };

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

@@ -0,0 +1,69 @@
+/**
+ * Pure geometry for the gauge primitives.
+ *
+ * Angles are "gauge degrees": 0 points straight down (six o'clock) and
+ * values increase clockwise, so a sweep from 40° to 320° leaves an opening
+ * at the bottom. Coordinates are SVG units centred on the gauge origin.
+ */
+export declare const clamp: (value: number, min: number, max: number) => number;
+/**
+ * Fraction digits needed to write `n` in decimal without scientific notation
+ * padding. Used to clean binary float noise after step maths without coarsening
+ * a finer `step` (or a fractional bound) than a fixed `toFixed(2)` would.
+ */
+export declare const fractionDigits: (n: number) => number;
+/**
+ * A value folded back inside [min, max) modulo the span, as on a closed ring:
+ * 370° on a compass reads as 10°, and 25 o'clock as 1.
+ */
+export declare const foldValue: (value: number, min: number, max: number) => number;
+export declare const degreesToRadians: (degrees: number) => number;
+/**
+ * Point on a circle of `radius` at a gauge angle. Coordinates are rounded so
+ * server and client render identical attributes and hydration stays clean.
+ */
+export declare const polar: (radius: number, angle: number) => {
+    x: number;
+    y: number;
+};
+/** Linear map of a value in [min, max] onto the arc [startAngle, endAngle]. */
+export declare const valueToAngle: (value: number, min: number, max: number, startAngle: number, endAngle: number) => number;
+/**
+ * Angle for a value that wraps the arc more than once. A single turn maps the
+ * domain onto the sweep exactly as `valueToAngle` does; past that each turn
+ * runs the sweep again from its start, which is how a clock's minute hand
+ * gets round twelve times while the hour hand goes round once.
+ */
+export declare const valueToTurnedAngle: (value: number, min: number, max: number, startAngle: number, endAngle: number, turns: number) => number;
+/**
+ * SVG path for an arc of `radius` from `from` to `to` gauge degrees. Sweeps
+ * over 180° are split so a single `A` command never has to disambiguate a
+ * large arc, which also makes a full 360° circle render correctly.
+ */
+export declare const arcPath: (radius: number, from: number, to: number) => string;
+/**
+ * Tight bounding box of an arc sweep, inflated by `padding`. Takes the two
+ * endpoints, every quarter turn the sweep crosses, and the origin, so a gauge
+ * that pivots a needle keeps its hub inside the box. A sweep that closes on
+ * itself crosses all four quarters and lands back on the full square.
+ */
+export declare const arcBox: (radius: number, from: number, to: number, padding?: number) => {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+/** Evenly spaced values across the domain, inclusive of both ends. */
+export declare const stepValues: (min: number, max: number, intervals: number) => number[];
+/**
+ * The cutoffs that split the domain into `segments` equal parts: the values
+ * between the segments, none at the two ends. Ten glasses of water make nine
+ * cuts.
+ */
+export declare const cutValues: (min: number, max: number, segments: number) => number[];
+/**
+ * Inverse of `valueToAngle`: the domain value under a gauge angle. An angle
+ * in the opening outside the sweep goes to whichever end is nearer, so a
+ * pointer dragged past an end holds there rather than jumping to the other.
+ */
+export declare const angleToValue: (angle: number, min: number, max: number, startAngle: number, endAngle: number) => number;

package/dist/components/gauge/math.js

@@ -0,0 +1,135 @@
+//#region src/components/gauge/math.ts
+/**
+* Pure geometry for the gauge primitives.
+*
+* Angles are "gauge degrees": 0 points straight down (six o'clock) and
+* values increase clockwise, so a sweep from 40° to 320° leaves an opening
+* at the bottom. Coordinates are SVG units centred on the gauge origin.
+*/
+var clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+/**
+* Fraction digits needed to write `n` in decimal without scientific notation
+* padding. Used to clean binary float noise after step maths without coarsening
+* a finer `step` (or a fractional bound) than a fixed `toFixed(2)` would.
+*/
+var fractionDigits = (n) => {
+	if (!Number.isFinite(n)) return 0;
+	const s = Math.abs(n).toString().toLowerCase();
+	if (s.includes("e")) {
+		const [coeff = "0", exp = "0"] = s.split("e");
+		return Math.max(0, (coeff.split(".")[1] ?? "").length - Number(exp));
+	}
+	const dot = s.indexOf(".");
+	return dot === -1 ? 0 : s.length - dot - 1;
+};
+/**
+* A value folded back inside [min, max) modulo the span, as on a closed ring:
+* 370° on a compass reads as 10°, and 25 o'clock as 1.
+*/
+var foldValue = (value, min, max) => {
+	const lo = Math.min(min, max);
+	const span = Math.abs(max - min);
+	return span === 0 ? lo : lo + ((value - lo) % span + span) % span;
+};
+var degreesToRadians = (degrees) => degrees * Math.PI / 180;
+var round = (n) => Math.round(n * 1e3) / 1e3;
+/**
+* Point on a circle of `radius` at a gauge angle. Coordinates are rounded so
+* server and client render identical attributes and hydration stays clean.
+*/
+var polar = (radius, angle) => {
+	const theta = degreesToRadians(angle + 90);
+	return {
+		x: round(radius * Math.cos(theta)),
+		y: round(radius * Math.sin(theta))
+	};
+};
+/** Linear map of a value in [min, max] onto the arc [startAngle, endAngle]. */
+var valueToAngle = (value, min, max, startAngle, endAngle) => {
+	const span = max - min;
+	return startAngle + (span === 0 ? 0 : (clamp(value, min, max) - min) / span) * (endAngle - startAngle);
+};
+/**
+* Angle for a value that wraps the arc more than once. A single turn maps the
+* domain onto the sweep exactly as `valueToAngle` does; past that each turn
+* runs the sweep again from its start, which is how a clock's minute hand
+* gets round twelve times while the hour hand goes round once.
+*/
+var valueToTurnedAngle = (value, min, max, startAngle, endAngle, turns) => {
+	if (turns === 1) return valueToAngle(value, min, max, startAngle, endAngle);
+	const span = max - min;
+	return startAngle + (span === 0 ? 0 : (value - min) / span) * turns % 1 * (endAngle - startAngle);
+};
+var fmt = (n) => Number(n.toFixed(3)).toString();
+/**
+* SVG path for an arc of `radius` from `from` to `to` gauge degrees. Sweeps
+* over 180° are split so a single `A` command never has to disambiguate a
+* large arc, which also makes a full 360° circle render correctly.
+*/
+var arcPath = (radius, from, to) => {
+	const sweep = Math.min(to - from, 360);
+	if (sweep <= 0 || radius <= 0) return "";
+	const pieces = Math.max(1, Math.ceil(sweep / 180));
+	const step = sweep / pieces;
+	const start = polar(radius, from);
+	const parts = [`M ${fmt(start.x)} ${fmt(start.y)}`];
+	for (let i = 1; i <= pieces; i += 1) {
+		const p = polar(radius, from + step * i);
+		parts.push(`A ${fmt(radius)} ${fmt(radius)} 0 0 1 ${fmt(p.x)} ${fmt(p.y)}`);
+	}
+	return parts.join(" ");
+};
+/**
+* Tight bounding box of an arc sweep, inflated by `padding`. Takes the two
+* endpoints, every quarter turn the sweep crosses, and the origin, so a gauge
+* that pivots a needle keeps its hub inside the box. A sweep that closes on
+* itself crosses all four quarters and lands back on the full square.
+*/
+var arcBox = (radius, from, to, padding = 0) => {
+	const end = from + clamp(to - from, 0, 360);
+	const points = [
+		{
+			x: 0,
+			y: 0
+		},
+		polar(radius, from),
+		polar(radius, end)
+	];
+	for (let a = Math.ceil(from / 90) * 90; a <= end; a += 90) points.push(polar(radius, a));
+	const xs = points.map((p) => p.x);
+	const ys = points.map((p) => p.y);
+	const x = round(Math.min(...xs) - padding);
+	const y = round(Math.min(...ys) - padding);
+	return {
+		x,
+		y,
+		width: round(Math.max(...xs) + padding - x),
+		height: round(Math.max(...ys) + padding - y)
+	};
+};
+/** Evenly spaced values across the domain, inclusive of both ends. */
+var stepValues = (min, max, intervals) => {
+	const n = Math.max(1, Math.round(intervals));
+	return Array.from({ length: n + 1 }, (_, i) => min + (max - min) * i / n);
+};
+/**
+* The cutoffs that split the domain into `segments` equal parts: the values
+* between the segments, none at the two ends. Ten glasses of water make nine
+* cuts.
+*/
+var cutValues = (min, max, segments) => stepValues(min, max, segments).slice(1, -1);
+/**
+* Inverse of `valueToAngle`: the domain value under a gauge angle. An angle
+* in the opening outside the sweep goes to whichever end is nearer, so a
+* pointer dragged past an end holds there rather than jumping to the other.
+*/
+var angleToValue = (angle, min, max, startAngle, endAngle) => {
+	let a = angle;
+	while (a < startAngle) a += 360;
+	while (a >= startAngle + 360) a -= 360;
+	if (a > endAngle) a = a - endAngle < startAngle + 360 - a ? endAngle : startAngle;
+	const sweep = endAngle - startAngle;
+	return min + (sweep === 0 ? 0 : (a - startAngle) / sweep) * (max - min);
+};
+//#endregion
+export { angleToValue, arcBox, arcPath, clamp, cutValues, degreesToRadians, foldValue, fractionDigits, polar, stepValues, valueToAngle, valueToTurnedAngle };

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

@@ -0,0 +1,81 @@
+import { GaugeEnd, NeedleStyle } from './utils';
+import * as React from 'react';
+export type GaugeNeedleProps = {
+    /**
+     * Needle shape. `line` is a stroke with round ends, `pointer` a tapered
+     * blade that is widest at the centre and ends in a rounded tip, and
+     * `compass` a lozenge whose two halves can take different colours. `arrow`
+     * is a shaft ending in a triangular arrowhead, sized from the width, for
+     * wind or flow direction. Named `kind` (not `style`) so React's CSS
+     * `style` prop stays available as an object.
+     * @defaultValue `'line'`
+     */
+    kind?: NeedleStyle;
+    /**
+     * Length as a fraction of the reference radius.
+     * @defaultValue 0.85
+     */
+    length?: number;
+    /**
+     * Stroke width for `line`; width at the centre for the filled styles.
+     * @defaultValue 6
+     */
+    width?: number;
+    /**
+     * Fill/stroke colour. Unset uses theme primary.
+     * @defaultValue `var(--global-primary)`
+     */
+    color?: string;
+    /**
+     * How far the needle extends behind the centre, in SVG units.
+     * @defaultValue 30
+     */
+    tail?: number;
+    /**
+     * Colour of the tail half of a `pointer`, `compass` or `arrow`. Defaults to `color`.
+     * @defaultValue same as `color`
+     */
+    tailColor?: string;
+    /**
+     * Radius of a disc drawn at the end of the tail in `tailColor`, like the
+     * counterweight on a wind vane. 0 leaves the tail plain.
+     * @defaultValue 0
+     */
+    tailDot?: number;
+    /**
+     * Sweeps of the arc the needle makes across the domain. A clock's minute
+     * hand turns 12 times while the hour hand turns once.
+     * @defaultValue 1
+     */
+    turns?: number;
+    /**
+     * Radius of a clear circle around the centre, in SVG units, that splits the
+     * needle in two so a readout can sit between the halves. 0 draws it whole.
+     * @defaultValue 0
+     */
+    gap?: number;
+    /**
+     * Which end of a range the needle points at.
+     * @defaultValue `'to'`
+     */
+    end?: GaugeEnd;
+};
+/**
+ * A needle pointing at the current value. Add a `GaugeHub` for the pivot, or
+ * a `gap` to clear the centre for a readout instead.
+ */
+export declare const GaugeNeedle: React.FC<GaugeNeedleProps>;
+export type GaugeHubProps = {
+    /**
+     * Hub disc radius in SVG units. `0` hides the hub.
+     * @defaultValue 12
+     */
+    radius?: number;
+    /**
+     * Fill colour. Unset uses theme foreground.
+     * @defaultValue `var(--global-foreground)`
+     */
+    color?: string;
+};
+/** The pivot disc at the centre, drawn once however many needles there are. */
+export declare const GaugeHub: React.FC<GaugeHubProps>;