@jcsoftdev/ui 0.1.1 → 0.1.3

package/dist/charts/gauge-chart/gauge-chart.js

@@ -1,6 +1,6 @@
 "use client";
 import { jsx, jsxs } from "react/jsx-runtime";
-import { memo, useCallback, useMemo, useRef } from "react";
+import { memo, useCallback, useId, useMemo, useRef } from "react";
 import { cn } from "../../utils/cn.js";
 import { DECORATIVE } from "../core/a11y.js";
 import { ChartFrame } from "../core/chart-frame.js";
@@ -12,6 +12,7 @@ import { arcLine, degToRad, polarPoint, radToDeg } from "../core/polar.js";
 import { ChartTooltip } from "../core/tooltip.js";
 import { resolveLabels } from "../core/types.js";
 import { useIndexNavigation } from "../core/use-index-navigation.js";
+import { layoutGauge, showEndLabels } from "./gauge-layout.js";
 const BASE_TONE = "accent";
 function rangeColor(range) {
   return range.color ?? TONE_COLORS[range.tone ?? BASE_TONE].ink;
@@ -140,18 +141,22 @@ function GaugePlot({
   const a1 = degToRad(half);
   const span = a1 - a0;
   const needle = mode === "needle";
-  const reserve = variant === "semi" ? needle ? 52 : 30 : needle ? 40 : 16;
-  const pad = 12;
-  const tail = variant === "semi" ? 0 : Math.sin(degToRad(45));
-  const radius = Math.max(
-    40,
-    Math.min(width / 2 - pad - (minMaxLabels ? 6 : 0), (height - pad - reserve) / (1 + tail))
-  );
-  const band = Math.min(thickness, radius * 0.4);
-  const extent = radius * (1 + tail) + reserve;
-  const cx = width / 2;
-  const cy = Math.max(pad + radius, (height - extent) / 2 + radius);
-  const mid = radius - band / 2;
+  const endLabels = showEndLabels(minMaxLabels, ticks);
+  const uid = useId();
+  const valueChars = Math.max(format(min).length, format(max).length, format(value).length);
+  const layout = layoutGauge({
+    width,
+    height,
+    variant,
+    mode,
+    thickness,
+    endLabels,
+    customCenter: Boolean(centerContent),
+    caption: Boolean(caption),
+    bandLabel: bands.length > 0,
+    valueChars
+  });
+  const { radius, band, cx, cy, mid, valueSize } = layout;
   const toFraction = (v) => Math.min(1, Math.max(0, (v - min) / (max - min)));
   const angleFor = useCallback(
     (v) => a0 + span * Math.min(1, Math.max(0, (v - min) / (max - min))),
@@ -159,7 +164,7 @@ function GaugePlot({
   );
   const capAngle = roundedCaps ? band / 2 / mid : 0;
   const fraction = toFraction(shown);
-  const active = bands.find((item) => shown >= item.from && shown <= item.to);
+  const active = bands.find((item) => value >= item.from && value <= item.to);
   const valueColor = active ? rangeColor(active) : "var(--accent-word)";
   const progressEnd = a0 + capAngle + (span - 2 * capAngle) * fraction;
   const bandPaths = useMemo(
@@ -210,10 +215,10 @@ function GaugePlot({
     },
     { disabled: !animate }
   );
-  const valueSize = Math.round(Math.min(40, Math.max(20, radius * 0.34)));
   const captionSize = 12;
-  const valueY = needle ? cy + 22 + valueSize * 0.8 : variant === "semi" ? cy - 6 : cy + valueSize * 0.3;
-  const captionY = needle ? valueY + 6 + captionSize : valueY + 8 + captionSize;
+  const valueY = cy + layout.valueDy;
+  const captionY = cy + layout.captionDy;
+  const labelY = cy + layout.labelDy;
   const focused = nav.active != null ? nav.active : null;
   const focusedBand = bands.length > 0 && focused != null ? bands[focused] : void 0;
   const rows = focusedBand ? [
@@ -250,6 +255,27 @@ function GaugePlot({
         height,
         className: "block overflow-visible",
         children: [
+          roundedCaps && bands.length > 0 ? /* @__PURE__ */ jsx("defs", { children: /* @__PURE__ */ jsx(
+            "mask",
+            {
+              id: `${uid}-track`,
+              maskUnits: "userSpaceOnUse",
+              x: 0,
+              y: 0,
+              width,
+              height,
+              children: /* @__PURE__ */ jsx(
+                "path",
+                {
+                  d: arcLine(cx, cy, mid, a0 + capAngle, a1 - capAngle),
+                  fill: "none",
+                  stroke: "white",
+                  strokeWidth: band,
+                  strokeLinecap: "round"
+                }
+              )
+            }
+          ) }) : null,
           bands.length === 0 ? /* @__PURE__ */ jsx(
             "path",
             {
@@ -259,7 +285,7 @@ function GaugePlot({
               strokeLinecap: roundedCaps ? "round" : "butt",
               style: { stroke: "var(--chart-grid)" }
             }
-          ) : bandPaths.map((path, index) => {
+          ) : /* @__PURE__ */ jsx("g", { mask: roundedCaps ? `url(#${uid}-track)` : void 0, children: bandPaths.map((path, index) => {
             const item = bands[index];
             if (!item || !path) return null;
             return /* @__PURE__ */ jsx(
@@ -275,7 +301,7 @@ function GaugePlot({
               },
               index
             );
-          }),
+          }) }),
           !needle && fraction > 0 ? /* @__PURE__ */ jsx(
             "path",
             {
@@ -325,7 +351,7 @@ function GaugePlot({
                 /* @__PURE__ */ jsx(
                   "path",
                   {
-                    d: `M${cx - 4} ${cy} L${cx} ${cy - (mid + band * 0.3)} L${cx + 4} ${cy} Z`,
+                    d: `M${cx - 4} ${cy} L${cx} ${cy - layout.needleLength} L${cx + 4} ${cy} Z`,
                     style: { fill: "var(--ink)" }
                   }
                 ),
@@ -334,7 +360,7 @@ function GaugePlot({
               ]
             }
           ) : null,
-          minMaxLabels ? /* @__PURE__ */ jsxs("g", { ...DECORATIVE, className: "pointer-events-none", children: [
+          endLabels ? /* @__PURE__ */ jsxs("g", { ...DECORATIVE, className: "pointer-events-none", children: [
             /* @__PURE__ */ jsx(
               "text",
               {
@@ -381,7 +407,7 @@ function GaugePlot({
               "text",
               {
                 x: cx,
-                y: caption ? captionY + 16 : captionY,
+                y: labelY,
                 className: "font-bold text-[11px]",
                 style: { fill: valueColor },
                 children: active.label
@@ -397,9 +423,9 @@ function GaugePlot({
         className: "pointer-events-none absolute flex flex-col items-center text-center",
         style: {
           left: cx,
-          top: needle ? cy + 22 : variant === "semi" ? cy - 6 : cy,
-          width: Math.max(40, radius * 1.5),
-          transform: needle ? "translate(-50%, 0)" : variant === "semi" ? "translate(-50%, -100%)" : "translate(-50%, -50%)"
+          top: cy + layout.customDy,
+          width: layout.customWidth,
+          transform: layout.customAnchor === "above" ? "translate(-50%, -100%)" : layout.customAnchor === "middle" ? "translate(-50%, -50%)" : "translate(-50%, 0)"
         },
         children: centerContent({
           value,

package/dist/charts/gauge-chart/gauge-layout.d.ts

@@ -0,0 +1,46 @@
+export type GaugeVariant = "semi" | "three-quarter";
+export type GaugeMode = "progress" | "needle";
+export interface GaugeLayoutInput {
+    width: number;
+    height: number;
+    variant: GaugeVariant;
+    mode: GaugeMode;
+    thickness: number;
+    /** Min and max printed under the arc ends. */
+    endLabels: boolean;
+    /** The value block is custom HTML of unknown size. */
+    customCenter: boolean;
+    caption: boolean;
+    bandLabel: boolean;
+    /** Longest formatted value, in characters; sizes the value block width. */
+    valueChars: number;
+}
+export interface GaugeLayout {
+    radius: number;
+    /** Stroke width of the track and value arc. */
+    band: number;
+    cx: number;
+    cy: number;
+    /** Radius of the arc centre line. */
+    mid: number;
+    valueSize: number;
+    /** Distance from the centre to the top of the value block. */
+    blockTop: number;
+    /** Baselines relative to the centre. */
+    valueDy: number;
+    captionDy: number;
+    labelDy: number;
+    /** Where the custom centre block is anchored, relative to the centre. */
+    customAnchor: "above" | "below" | "middle";
+    customDy: number;
+    customWidth: number;
+    /** Needle reach from the hub; stops at the arc. */
+    needleLength: number;
+}
+/** Min/max labels duplicate the tick labels at the arc ends, so ticks win. */
+export declare function showEndLabels(minMaxLabels: boolean, ticks: number): boolean;
+/**
+ * Largest arc that fits the box in both directions, with the value block
+ * placed where the needle and hub never reach it.
+ */
+export declare function layoutGauge(input: GaugeLayoutInput): GaugeLayout;

package/dist/charts/gauge-chart/gauge-layout.js

@@ -0,0 +1,110 @@
+const PAD = 12;
+const HUB_RADIUS = 8;
+const MIN_RADIUS = 40;
+const CAPTION_SIZE = 12;
+const CUSTOM_BLOCK_HEIGHT = 72;
+const SIN_45 = Math.sin(Math.PI / 4);
+function showEndLabels(minMaxLabels, ticks) {
+  return minMaxLabels && !(ticks >= 1);
+}
+function clamp(value, lo, hi) {
+  return Math.min(hi, Math.max(lo, value));
+}
+const GLYPH_WIDTH = 0.6;
+function valueSizeFor(input, radius, band) {
+  const bySize = clamp(radius * 0.34, 20, 52);
+  if (input.customCenter || input.valueChars <= 0) return Math.round(bySize);
+  const inner = input.mode === "needle" ? radius * 2 : (radius - band) * 2 - 16;
+  const byWidth = inner / (input.valueChars * GLYPH_WIDTH);
+  return Math.max(12, Math.min(Math.round(bySize), Math.floor(byWidth)));
+}
+function blockFor(input, radius, valueSize) {
+  const { variant, mode, customCenter } = input;
+  const halfWidth = customCenter ? radius * 0.35 : input.valueChars * GLYPH_WIDTH * valueSize / 2;
+  const needle = mode === "needle";
+  let top;
+  if (needle) {
+    top = variant === "semi" ? HUB_RADIUS + 14 : Math.max(HUB_RADIUS + 14, halfWidth + 12);
+  } else if (variant === "semi") {
+    top = customCenter ? -(CUSTOM_BLOCK_HEIGHT + 6) : -(valueSize * 0.9 + 6);
+  } else {
+    top = customCenter ? -CUSTOM_BLOCK_HEIGHT / 2 : -valueSize * 0.5;
+  }
+  const gap = needle ? 6 : 8;
+  const valueDy = top + valueSize * 0.85;
+  const captionDy = valueDy + gap + CAPTION_SIZE;
+  const withCaption = input.caption ? captionDy : valueDy;
+  const labelDy = withCaption + (input.caption || !needle ? 16 : 14);
+  const last = input.bandLabel ? labelDy : withCaption;
+  const bottom = customCenter ? top + CUSTOM_BLOCK_HEIGHT : last + 4;
+  return { top, valueDy, captionDy, labelDy, bottom };
+}
+function below(input, radius, band) {
+  const valueSize = valueSizeFor(input, radius, band);
+  const mid = radius - band / 2;
+  const arcBottom = input.variant === "semi" ? band / 2 : mid * SIN_45 + band / 2;
+  const withLabels = arcBottom + (input.endLabels ? 19 : 2);
+  const block = blockFor(input, radius, valueSize).bottom;
+  const needleHub = input.mode === "needle" ? HUB_RADIUS : 0;
+  return Math.max(withLabels, block, needleHub);
+}
+function layoutGauge(input) {
+  const { width, height, thickness } = input;
+  const maxByWidth = width / 2 - PAD - (input.endLabels ? 6 : 0);
+  const fits = (radius2) => {
+    const band2 = Math.min(thickness, radius2 * 0.4);
+    return radius2 + below(input, radius2, band2) + PAD * 2 <= height;
+  };
+  let radius = MIN_RADIUS;
+  if (maxByWidth > MIN_RADIUS) {
+    if (fits(maxByWidth)) {
+      radius = maxByWidth;
+    } else {
+      let lo = MIN_RADIUS;
+      let hi = maxByWidth;
+      for (let i = 0; i < 30; i++) {
+        const probe = (lo + hi) / 2;
+        if (fits(probe)) lo = probe;
+        else hi = probe;
+      }
+      radius = lo;
+    }
+  }
+  const band = Math.min(thickness, radius * 0.4);
+  const mid = radius - band / 2;
+  const valueSize = valueSizeFor(input, radius, band);
+  const block = blockFor(input, radius, valueSize);
+  const extent = radius + below(input, radius, band);
+  const cx = width / 2;
+  const cy = Math.max(PAD + radius, (height - extent) / 2 + radius);
+  const needle = input.mode === "needle";
+  const customAnchor = needle || input.variant === "three-quarter" ? "below" : "above";
+  const customWidth = Math.max(40, radius * 1.5);
+  let customDy = block.top;
+  let anchor = customAnchor;
+  if (!needle && input.variant === "semi") customDy = -6;
+  else if (!needle) {
+    anchor = "middle";
+    customDy = 0;
+  }
+  return {
+    radius,
+    band,
+    cx,
+    cy,
+    mid,
+    valueSize,
+    blockTop: block.top,
+    valueDy: block.valueDy,
+    captionDy: block.captionDy,
+    labelDy: block.labelDy,
+    customAnchor: anchor,
+    customDy,
+    customWidth,
+    needleLength: mid + band * 0.3
+  };
+}
+export {
+  layoutGauge,
+  showEndLabels
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jcsoftdev/ui",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Token-driven React component library: React 19, Radix, Tailwind v4.",
   "author": "jcsoftdev",
   "license": "MIT",

package/src/charts/gauge-chart/gauge-chart.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { memo, type ReactNode, useCallback, useMemo, useRef } from "react";
+import { memo, type ReactNode, useCallback, useId, useMemo, useRef } from "react";
 import { cn } from "../../utils/cn.js";
 import { DECORATIVE } from "../core/a11y.js";
 import { ChartFrame } from "../core/chart-frame.js";
@@ -12,6 +12,7 @@ import { arcLine, degToRad, polarPoint, radToDeg } from "../core/polar.js";
 import { ChartTooltip } from "../core/tooltip.js";
 import { type ChartLabels, resolveLabels } from "../core/types.js";
 import { useIndexNavigation } from "../core/use-index-navigation.js";
+import { layoutGauge, showEndLabels } from "./gauge-layout.js";
 
 export interface GaugeRange {
   from: number;
@@ -238,18 +239,22 @@ function GaugePlot({
   const a1 = degToRad(half);
   const span = a1 - a0;
   const needle = mode === "needle";
-  const reserve = variant === "semi" ? (needle ? 52 : 30) : needle ? 40 : 16;
-  const pad = 12;
-  const tail = variant === "semi" ? 0 : Math.sin(degToRad(45));
-  const radius = Math.max(
-    40,
-    Math.min(width / 2 - pad - (minMaxLabels ? 6 : 0), (height - pad - reserve) / (1 + tail)),
-  );
-  const band = Math.min(thickness, radius * 0.4);
-  const extent = radius * (1 + tail) + reserve;
-  const cx = width / 2;
-  const cy = Math.max(pad + radius, (height - extent) / 2 + radius);
-  const mid = radius - band / 2;
+  const endLabels = showEndLabels(minMaxLabels, ticks);
+  const uid = useId();
+  const valueChars = Math.max(format(min).length, format(max).length, format(value).length);
+  const layout = layoutGauge({
+    width,
+    height,
+    variant,
+    mode,
+    thickness,
+    endLabels,
+    customCenter: Boolean(centerContent),
+    caption: Boolean(caption),
+    bandLabel: bands.length > 0,
+    valueChars,
+  });
+  const { radius, band, cx, cy, mid, valueSize } = layout;
 
   const toFraction = (v: number) => Math.min(1, Math.max(0, (v - min) / (max - min)));
   const angleFor = useCallback(
@@ -259,7 +264,9 @@ function GaugePlot({
   const capAngle = roundedCaps ? band / 2 / mid : 0;
 
   const fraction = toFraction(shown);
-  const active = bands.find((item) => shown >= item.from && shown <= item.to);
+  // Colour and label follow the target value, so they do not flip band by band
+  // while the arc or needle sweeps towards it.
+  const active = bands.find((item) => value >= item.from && value <= item.to);
   const valueColor = active ? rangeColor(active) : "var(--accent-word)";
   const progressEnd = a0 + capAngle + (span - 2 * capAngle) * fraction;
 
@@ -317,14 +324,10 @@ function GaugePlot({
   );
 
   // Value text ---------------------------------------------------------------
-  const valueSize = Math.round(Math.min(40, Math.max(20, radius * 0.34)));
   const captionSize = 12;
-  const valueY = needle
-    ? cy + 22 + valueSize * 0.8
-    : variant === "semi"
-      ? cy - 6
-      : cy + valueSize * 0.3;
-  const captionY = needle ? valueY + 6 + captionSize : valueY + 8 + captionSize;
+  const valueY = cy + layout.valueDy;
+  const captionY = cy + layout.captionDy;
+  const labelY = cy + layout.labelDy;
 
   // Tooltip -----------------------------------------------------------------
   const focused = nav.active != null ? nav.active : null;
@@ -376,6 +379,27 @@ function GaugePlot({
         height={height}
         className="block overflow-visible"
       >
+        {roundedCaps && bands.length > 0 ? (
+          <defs>
+            <mask
+              id={`${uid}-track`}
+              maskUnits="userSpaceOnUse"
+              x={0}
+              y={0}
+              width={width}
+              height={height}
+            >
+              <path
+                d={arcLine(cx, cy, mid, a0 + capAngle, a1 - capAngle)}
+                fill="none"
+                stroke="white"
+                strokeWidth={band}
+                strokeLinecap="round"
+              />
+            </mask>
+          </defs>
+        ) : null}
+
         {bands.length === 0 ? (
           <path
             d={arcLine(cx, cy, mid, a0 + capAngle, a1 - capAngle)}
@@ -385,23 +409,25 @@ function GaugePlot({
             style={{ stroke: "var(--chart-grid)" }}
           />
         ) : (
-          bandPaths.map((path, index) => {
-            const item = bands[index];
-            if (!item || !path) return null;
-            return (
-              <BandMark
-                // biome-ignore lint/suspicious/noArrayIndexKey: bands are positional and static.
-                key={index}
-                d={path}
-                width={band}
-                color={rangeColor(item)}
-                opacity={needle ? 0.92 : 0.26}
-                dimmed={focused != null && focused !== index}
-                onEnter={(event) => nav.hover(index, event)}
-                onLeave={nav.leave}
-              />
-            );
-          })
+          <g mask={roundedCaps ? `url(#${uid}-track)` : undefined}>
+            {bandPaths.map((path, index) => {
+              const item = bands[index];
+              if (!item || !path) return null;
+              return (
+                <BandMark
+                  // biome-ignore lint/suspicious/noArrayIndexKey: bands are positional and static.
+                  key={index}
+                  d={path}
+                  width={band}
+                  color={rangeColor(item)}
+                  opacity={needle ? 0.92 : 0.26}
+                  dimmed={focused != null && focused !== index}
+                  onEnter={(event) => nav.hover(index, event)}
+                  onLeave={nav.leave}
+                />
+              );
+            })}
+          </g>
         )}
 
         {!needle && fraction > 0 ? (
@@ -451,7 +477,7 @@ function GaugePlot({
             }}
           >
             <path
-              d={`M${cx - 4} ${cy} L${cx} ${cy - (mid + band * 0.3)} L${cx + 4} ${cy} Z`}
+              d={`M${cx - 4} ${cy} L${cx} ${cy - layout.needleLength} L${cx + 4} ${cy} Z`}
               style={{ fill: "var(--ink)" }}
             />
             <circle cx={cx} cy={cy} r={8} style={{ fill: "var(--ink)" }} />
@@ -459,7 +485,7 @@ function GaugePlot({
           </g>
         ) : null}
 
-        {minMaxLabels ? (
+        {endLabels ? (
           <g {...DECORATIVE} className="pointer-events-none">
             <text
               x={minPoint.x}
@@ -503,7 +529,7 @@ function GaugePlot({
             {active?.label && bands.length > 0 ? (
               <text
                 x={cx}
-                y={caption ? captionY + 16 : captionY}
+                y={labelY}
                 className="font-bold text-[11px]"
                 style={{ fill: valueColor }}
               >
@@ -519,13 +545,14 @@ function GaugePlot({
           className="pointer-events-none absolute flex flex-col items-center text-center"
           style={{
             left: cx,
-            top: needle ? cy + 22 : variant === "semi" ? cy - 6 : cy,
-            width: Math.max(40, radius * 1.5),
-            transform: needle
-              ? "translate(-50%, 0)"
-              : variant === "semi"
+            top: cy + layout.customDy,
+            width: layout.customWidth,
+            transform:
+              layout.customAnchor === "above"
                 ? "translate(-50%, -100%)"
-                : "translate(-50%, -50%)",
+                : layout.customAnchor === "middle"
+                  ? "translate(-50%, -50%)"
+                  : "translate(-50%, 0)",
           }}
         >
           {centerContent({

package/src/charts/gauge-chart/gauge-layout.ts

@@ -0,0 +1,183 @@
+export type GaugeVariant = "semi" | "three-quarter";
+export type GaugeMode = "progress" | "needle";
+
+const PAD = 12;
+const HUB_RADIUS = 8;
+const MIN_RADIUS = 40;
+const CAPTION_SIZE = 12;
+/** Height of a custom centre block (`centerContent`), which cannot be measured here. */
+const CUSTOM_BLOCK_HEIGHT = 72;
+const SIN_45 = Math.sin(Math.PI / 4);
+
+export interface GaugeLayoutInput {
+  width: number;
+  height: number;
+  variant: GaugeVariant;
+  mode: GaugeMode;
+  thickness: number;
+  /** Min and max printed under the arc ends. */
+  endLabels: boolean;
+  /** The value block is custom HTML of unknown size. */
+  customCenter: boolean;
+  caption: boolean;
+  bandLabel: boolean;
+  /** Longest formatted value, in characters; sizes the value block width. */
+  valueChars: number;
+}
+
+export interface GaugeLayout {
+  radius: number;
+  /** Stroke width of the track and value arc. */
+  band: number;
+  cx: number;
+  cy: number;
+  /** Radius of the arc centre line. */
+  mid: number;
+  valueSize: number;
+  /** Distance from the centre to the top of the value block. */
+  blockTop: number;
+  /** Baselines relative to the centre. */
+  valueDy: number;
+  captionDy: number;
+  labelDy: number;
+  /** Where the custom centre block is anchored, relative to the centre. */
+  customAnchor: "above" | "below" | "middle";
+  customDy: number;
+  customWidth: number;
+  /** Needle reach from the hub; stops at the arc. */
+  needleLength: number;
+}
+
+/** Min/max labels duplicate the tick labels at the arc ends, so ticks win. */
+export function showEndLabels(minMaxLabels: boolean, ticks: number): boolean {
+  return minMaxLabels && !(ticks >= 1);
+}
+
+function clamp(value: number, lo: number, hi: number): number {
+  return Math.min(hi, Math.max(lo, value));
+}
+
+/** Width of one tabular glyph as a share of the font size. */
+const GLYPH_WIDTH = 0.6;
+
+/**
+ * Value font size: scales with the radius, but long values (currency) shrink
+ * so the text stays inside the inner edge of the arc.
+ */
+function valueSizeFor(input: GaugeLayoutInput, radius: number, band: number): number {
+  const bySize = clamp(radius * 0.34, 20, 52);
+  if (input.customCenter || input.valueChars <= 0) return Math.round(bySize);
+  const inner = input.mode === "needle" ? radius * 2 : (radius - band) * 2 - 16;
+  const byWidth = inner / (input.valueChars * GLYPH_WIDTH);
+  return Math.max(12, Math.min(Math.round(bySize), Math.floor(byWidth)));
+}
+
+interface Block {
+  /** Distance from the centre to the top of the block. */
+  top: number;
+  valueDy: number;
+  captionDy: number;
+  labelDy: number;
+  bottom: number;
+}
+
+function blockFor(input: GaugeLayoutInput, radius: number, valueSize: number): Block {
+  const { variant, mode, customCenter } = input;
+  const halfWidth = customCenter ? radius * 0.35 : (input.valueChars * GLYPH_WIDTH * valueSize) / 2;
+  const needle = mode === "needle";
+  let top: number;
+  if (needle) {
+    // Semicircle: the sweep is the upper half, anything under the hub is free.
+    // Three-quarter: the free area is the wedge under the hub, so the top
+    // corners of the block must sit below the 45 degree needle positions.
+    top = variant === "semi" ? HUB_RADIUS + 14 : Math.max(HUB_RADIUS + 14, halfWidth + 12);
+  } else if (variant === "semi") {
+    top = customCenter ? -(CUSTOM_BLOCK_HEIGHT + 6) : -(valueSize * 0.9 + 6);
+  } else {
+    top = customCenter ? -CUSTOM_BLOCK_HEIGHT / 2 : -valueSize * 0.5;
+  }
+  const gap = needle ? 6 : 8;
+  const valueDy = top + valueSize * 0.85;
+  const captionDy = valueDy + gap + CAPTION_SIZE;
+  const withCaption = input.caption ? captionDy : valueDy;
+  const labelDy = withCaption + (input.caption || !needle ? 16 : 14);
+  const last = input.bandLabel ? labelDy : withCaption;
+  const bottom = customCenter ? top + CUSTOM_BLOCK_HEIGHT : last + 4;
+  return { top, valueDy, captionDy, labelDy, bottom };
+}
+
+/** Distance from the centre to the lowest thing drawn. */
+function below(input: GaugeLayoutInput, radius: number, band: number): number {
+  const valueSize = valueSizeFor(input, radius, band);
+  const mid = radius - band / 2;
+  const arcBottom = input.variant === "semi" ? band / 2 : mid * SIN_45 + band / 2;
+  const withLabels = arcBottom + (input.endLabels ? 19 : 2);
+  const block = blockFor(input, radius, valueSize).bottom;
+  const needleHub = input.mode === "needle" ? HUB_RADIUS : 0;
+  return Math.max(withLabels, block, needleHub);
+}
+
+/**
+ * Largest arc that fits the box in both directions, with the value block
+ * placed where the needle and hub never reach it.
+ */
+export function layoutGauge(input: GaugeLayoutInput): GaugeLayout {
+  const { width, height, thickness } = input;
+  const maxByWidth = width / 2 - PAD - (input.endLabels ? 6 : 0);
+  const fits = (radius: number) => {
+    const band = Math.min(thickness, radius * 0.4);
+    return radius + below(input, radius, band) + PAD * 2 <= height;
+  };
+
+  let radius = MIN_RADIUS;
+  if (maxByWidth > MIN_RADIUS) {
+    if (fits(maxByWidth)) {
+      radius = maxByWidth;
+    } else {
+      let lo = MIN_RADIUS;
+      let hi = maxByWidth;
+      for (let i = 0; i < 30; i++) {
+        const probe = (lo + hi) / 2;
+        if (fits(probe)) lo = probe;
+        else hi = probe;
+      }
+      radius = lo;
+    }
+  }
+
+  const band = Math.min(thickness, radius * 0.4);
+  const mid = radius - band / 2;
+  const valueSize = valueSizeFor(input, radius, band);
+  const block = blockFor(input, radius, valueSize);
+  const extent = radius + below(input, radius, band);
+  const cx = width / 2;
+  const cy = Math.max(PAD + radius, (height - extent) / 2 + radius);
+
+  const needle = input.mode === "needle";
+  const customAnchor = needle || input.variant === "three-quarter" ? "below" : "above";
+  const customWidth = Math.max(40, radius * 1.5);
+  let customDy = block.top;
+  let anchor: GaugeLayout["customAnchor"] = customAnchor;
+  if (!needle && input.variant === "semi") customDy = -6;
+  else if (!needle) {
+    anchor = "middle";
+    customDy = 0;
+  }
+
+  return {
+    radius,
+    band,
+    cx,
+    cy,
+    mid,
+    valueSize,
+    blockTop: block.top,
+    valueDy: block.valueDy,
+    captionDy: block.captionDy,
+    labelDy: block.labelDy,
+    customAnchor: anchor,
+    customDy,
+    customWidth,
+    needleLength: mid + band * 0.3,
+  };
+}