@motionscript/charts 0.1.0 → 0.1.1-alpha.0

package/dist/pie-chart/pie-ring.js

@@ -1,75 +1,47 @@
-import { Graphics2D, PathBuilder, Rect, Text, Types, component2d, fillOps, shadowOps, strokeOps, textOps, } from "@motionscript/sdk";
+import { Graphics2D, PathBuilder, Rect, Text, Types, clamp, component2d, fillOps, shadowOps, strokeOps, textOps, } from "@motionscript/sdk";
 import { asParts, fresh } from "../kit/entries.js";
 import { frameEase } from "../kit/motion.js";
 import { loadPaints } from "../kit/paints.js";
-import { clampUnit, formatPercent } from "../kit/shared.js";
-import { DEFAULT_PIE_CHART_THEME, pieArcs, relaxLabels, ringPoint, } from "./shared.js";
-/** Vertical breathing room between one label block and the next, in px. */
+import { formatPercent } from "../kit/shared.js";
+import { DEFAULT_PIE_CHART_THEME, pieArcs, relaxLabels, ringPoint, selectionFade, } from "./shared.js";
 const LABEL_GAP = 12;
-/** Breathing room past the outermost label, so it never touches the node's edge, in px. */
 const LABEL_PAD = 14;
-/** Rough width of one glyph as a fraction of the font size, for gutter sizing. */
+/** Rough glyph width as a fraction of the font size, for gutter sizing. */
 const GLYPH_RATIO = 0.62;
-/** Gap between a wedge's outer edge and where its leader lifts off, in px. */
 const LEADER_LIFTOFF = 6;
-/** How far past the ring's outer edge a leader runs before it elbows, in px. */
 const LEADER_LENGTH = 34;
-/** Horizontal run from the elbow to the label, in px. */
 const LABEL_STUB = 26;
-/** Gap between a leader's end and the label text it points at, in px. */
 const TEXT_INSET = 8;
-/**
- * Floor on the elbow's horizontal distance from the ring's axis, as a fraction
- * of the leader radius — so a label pushed clear above (or below) the ring still
- * elbows out sideways rather than running straight down the 12 o'clock line.
- */
+/** Floor on the elbow's distance from the ring's axis, as a fraction of the leader radius, so a label pushed above or below the ring still elbows out sideways. */
 const MIN_ELBOW = 0.18;
-/** Segments used to tessellate a full turn of arc; a wedge takes its share. */
 const ARC_STEPS = 240;
-/** Rounding applied to the leader's elbow, in px. */
 const ELBOW_RADIUS = 8;
-/** Side padding used when nothing is leadered out — no gutter to reserve. */
 const BARE_PAD = 2;
-/** An inside label's caption size, as a fraction of its leading line. */
 const INSIDE_CAPTION_RATIO = 0.44;
-/**
- * Where an inside label sits on a **solid pie** (no hole to split the band
- * with), as a fraction of the wedge's radius — far enough out that the label
- * clears the point every wedge converges on.
- */
+/** Where an inside label sits on a solid pie, as a fraction of the radius: far enough out to clear the point every wedge converges on. */
 const PIE_LABEL_RADIUS = 0.62;
-/** Fraction of the hole's diameter its summary is allowed to run to. */
 const CENTER_LABEL_FIT = 0.78;
-/** Fraction of the room inside a wedge that its label is allowed to run to. */
 const INSIDE_LABEL_FIT = 0.9;
-/** Below this, a wedge's bisector counts as axis-aligned and that term stops binding. */
+/** Below this a wedge's bisector counts as axis-aligned and that bound stops binding. */
 const AXIS_EPSILON = 1e-3;
-/** Fallback type size when a theme style leaves it unset or on autofit. */
+/** Type size when a theme style leaves it unset or on autofit. */
 const FALLBACK_SIZE = 26;
-/** A style's numeric size, guarding the autofit and unset cases. */
 function sizeOf(style, fallback = FALLBACK_SIZE) {
     const size = style.fontSize;
     return typeof size === "number" ? size : fallback;
 }
 /**
- * A ring-band wedge over `a0`→`a1` (radians, clockwise from 12 o'clock) spanning
- * `rInner`→`rOuter`, centred on `cx`. Ring wedges trace the outer arc, step in,
- * and trace the inner arc back; full pie wedges (`rInner <= 0`) close through the
- * centre.
- *
- * `halfGap` is **half the gap to the neighbouring slice, in px**, shaved off both
- * ends of the wedge. It's converted to an angle *per radius* (`halfGap / r` — a
- * wider angle near the hole than out at the rim), which is what keeps the channel
- * between two slices the same width all the way across the band. A fixed angular
- * gap instead reads as a thin pizza slice: right at the rim, pinched shut at the
- * hole. The inset is capped at the wedge's own half-span so a sliver of a slice
- * narrows to nothing rather than turning inside out.
+ * A wedge over `a0`..`a1` (radians clockwise from 12 o'clock) from `rInner` to
+ * `rOuter`, centred on `cx`; with `rInner <= 0` it closes through the centre.
+ * `halfGap` is half the px gap to the neighbour, converted to an angle per
+ * radius (wider near the hole) so the channel keeps one width across the band.
+ * The inset is capped at the wedge's half-span so a sliver narrows to nothing
+ * rather than turning inside out.
  */
 function wedgePath(a0, a1, rInner, rOuter, halfGap, cx) {
     const path = new PathBuilder();
     const span = a1 - a0;
     const steps = Math.max(2, Math.ceil((Math.abs(span) / (Math.PI * 2)) * ARC_STEPS));
-    /** Angular inset at radius `r` that puts the wedge's edge `halfGap` px off the divide. */
     const insetAt = (r) => r <= 0 ? 0 : Math.min(halfGap / r, span / 2.2);
     const arcTo = (r, i) => {
         const inset = insetAt(r);
@@ -79,8 +51,7 @@ function wedgePath(a0, a1, rInner, rOuter, halfGap, cx) {
         return { x: point.x + cx, y: point.y };
     };
     if (rInner <= 0) {
-        // Solid pie wedge: the sides converge on the centre, so only the outer rim
-        // carries the gap.
+        // The sides converge on the centre, so only the rim carries the gap.
         path.moveTo(cx, 0);
         for (let i = 0; i <= steps; i++) {
             const p = arcTo(rOuter, i);
@@ -96,8 +67,7 @@ function wedgePath(a0, a1, rInner, rOuter, halfGap, cx) {
         else
             path.lineTo(p.x, p.y);
     }
-    // Back along the inner arc — its own (wider) inset makes each side edge a
-    // straight chord sitting `halfGap` px off the divide at both ends.
+    // The inner arc's own wider inset makes each side edge a chord `halfGap` px off the divide at both ends.
     for (let i = steps; i >= 0; i--) {
         const p = arcTo(rInner, i);
         path.lineTo(p.x, p.y);
@@ -105,12 +75,7 @@ function wedgePath(a0, a1, rInner, rOuter, halfGap, cx) {
     path.close();
     return path;
 }
-/**
- * The ring's geometry for one box: every radius, gutter and label position,
- * derived from the entries and the size the ring was laid out at, and asked
- * afresh wherever it is read — the drawing, and the labels' bound positions
- * and sizes alike, so the two cannot disagree.
- */
+/** Every radius, gutter and label position for one box, derived afresh wherever read so the drawing and the labels' bound positions cannot disagree. */
 export class RingGeometry {
     s;
     box;
@@ -118,30 +83,19 @@ export class RingGeometry {
         this.s = s;
         this.box = box;
     }
-    /** The drawn slices' angular spans, re-read every frame so a value tween re-cuts them. */
+    /** Re-read every frame so a value tween re-cuts them. */
     get arcs() {
         return pieArcs(this.s.slices, this.s.ring.startAngle);
     }
-    /** Whether any slice is labelled on a leader — the only thing that costs a gutter. */
+    /** Leader labels are the only thing that costs a gutter. */
     get hasLeaderLabels() {
         return this.s.labelPlacement === "leader" && this.s.labelMode !== "none" && this.arcs.length > 0;
     }
-    // ---- Label sizing ------------------------------------------------------
     /**
-     * How wide a horizontal label centred in slice `arc`'s band can run before it
-     * leaves the wedge, in px.
-     *
-     * Two things bound it, and which one binds depends entirely on where the wedge
-     * sits. Stepping sideways from the label's centre moves you *radially* by
-     * `dx·sin(mid)` and *tangentially* by `dx·cos(mid)`, so a wedge at 3 o'clock is
-     * limited by the band's thickness (its label runs straight across the band)
-     * while a wedge at 12 o'clock is limited by its own arc (its label runs along
-     * the band, which is much roomier). Taking the smaller of the two is what stops
-     * a label overflowing the ring on one chart and being pointlessly shrunk on the
-     * next.
-     *
-     * Measured off the *unpopped* radius, so a slice growing out of the ring
-     * doesn't resize its own text mid-animation.
+     * Px a horizontal label centred in `arc`'s band can run before leaving the
+     * wedge: bound by the band's thickness near 3 o'clock, by its arc near 12.
+     * Measured off the unpopped radius, so a slice growing out of the ring does not
+     * resize its own text mid-animation.
      */
     insideRoom(arc) {
         const outer = this.outerRadius;
@@ -159,20 +113,11 @@ export class RingGeometry {
         const mode = this.s.labelMode;
         const category = this.s.slices[arc.index]?.category.length ?? 0;
         const percent = mode === "both" || mode === "percent" ? formatPercent(arc.fraction).length : 0;
-        // The caption is set at a fraction of the leading line, except when it *is*
-        // the leading line.
+        // The caption is a fraction of the leading line, unless it is the leading line.
         const caption = mode === "category" ? category : mode === "both" ? category * INSIDE_CAPTION_RATIO : 0;
         return Math.max(1, percent, caption);
     }
-    /**
-     * Font size of an inside label's leading line: what the theme asked for,
-     * shrunk if that wouldn't fit inside its wedge. **One size across every inside
-     * label** — the smallest any of them needs — because labels at mismatched
-     * sizes read as a mistake rather than as emphasis.
-     *
-     * So the theme's `insideStyle.fontSize` is an upper bound, not a promise: ask
-     * for the size the chart wants and the ring keeps it legal.
-     */
+    /** The theme's `insideStyle.fontSize` shrunk to fit, an upper bound. One size across every inside label (the smallest any needs): mismatched sizes read as a mistake. */
     get insideFont() {
         let size = sizeOf(this.s.label.insideStyle, FALLBACK_SIZE * 1.9);
         for (const arc of this.arcs) {
@@ -181,12 +126,7 @@ export class RingGeometry {
         }
         return Math.max(1, size);
     }
-    /**
-     * Font size of the hole's summary: the configured size, capped so it still
-     * fits across the hole. The cap matters because the hole's radius derives from
-     * the box, so a chart that reflows smaller would otherwise push its summary out
-     * through the ring.
-     */
+    /** The configured size capped to fit across the hole, which derives from the box: a smaller reflow would otherwise push the summary through the ring. */
     get centerFont() {
         const { centerStyle, centerLabel, centerCaption } = this.s;
         const wanted = sizeOf(centerStyle.labelStyle, 46);
@@ -194,25 +134,19 @@ export class RingGeometry {
         if (hole <= 0)
             return wanted;
         const captionRatio = sizeOf(centerStyle.captionStyle, 22) / Math.max(1, wanted);
-        // Both lines have to clear the hole, and the caption is set at a fraction of
-        // this size — so what binds is whichever is wider once drawn, not whichever
-        // has more characters.
+        // Both lines must clear the hole; the caption is a fraction of this size, so the wider once drawn binds, not the longer.
         const glyphs = Math.max(1, centerLabel.length, centerCaption.length * captionRatio);
         return Math.min(wanted, (hole * 2 * CENTER_LABEL_FIT) / (glyphs * GLYPH_RATIO));
     }
-    // ---- Ring geometry, all derived from the box ---------------------------
-    /** Rim radius of a fully selected slice as a multiple of the ring's, clamped sane. */
+    /** Rim radius of a fully selected slice as a multiple of the ring's. */
     get growFactor() {
         return Math.max(1, Math.min(1.6, this.s.ring.selectedGrow));
     }
-    /** How far past the ring's rim a fully selected slice reaches, in px. */
     get maxPop() {
         return this.outerRadius * (this.growFactor - 1);
     }
-    /** Height of one **leader** label block, in px — the unit those columns are spaced by. */
+    /** Height of one leader label block, the unit the columns are spaced by. Inside labels cost no vertical reserve. */
     get labelRowHeight() {
-        // Inside labels are stacked in the band, not in a column beside the ring, so
-        // they cost no vertical reserve.
         if (!this.hasLeaderLabels)
             return 0;
         const caption = sizeOf(this.s.label.textStyle) * 1.25;
@@ -221,7 +155,7 @@ export class RingGeometry {
             return caption + percent + 2;
         return this.s.labelMode === "category" ? caption : percent;
     }
-    /** Widest line, in glyphs, that a leader label for slice `index` can run to. */
+    /** Widest line in glyphs a leader label for slice `index` runs to. */
     captionGlyphs(index) {
         const mode = this.s.labelMode;
         // "100%" is the widest a percentage gets; captions are their own length.
@@ -229,14 +163,7 @@ export class RingGeometry {
         const category = mode === "category" || mode === "both" ? (this.s.slices[index]?.category.length ?? 0) : 0;
         return Math.max(percent, category);
     }
-    /**
-     * Horizontal room reserved on each side for the leaders and their labels, in
-     * px — measured **per side**, from the slices that actually leader out that
-     * way. A ring whose labels are all inside reserves nothing and draws bigger.
-     *
-     * Excludes the ring's own selection-growth allowance, which scales with the
-     * radius and so is divided out in {@link outerRadius} instead.
-     */
+    /** Room reserved per side for leaders and labels, from the slices that leader out that way. Excludes selection growth, which scales with the radius and is divided out in {@link outerRadius}. */
     get labelGutters() {
         const gutters = { left: BARE_PAD, right: BARE_PAD };
         if (!this.hasLeaderLabels)
@@ -249,28 +176,17 @@ export class RingGeometry {
         }
         return gutters;
     }
-    /**
-     * How far the ring's centre sits from the node's, in px. Zero while the
-     * gutters match; when the labels all fall one way it slides the ring into the
-     * empty half so the ring-plus-labels group stays centred in the box instead of
-     * the ring sitting dead centre with a bald patch beside it.
-     */
+    /** Slides the ring into the empty half when labels all fall one way, keeping the ring-plus-labels group centred. */
     get centerX() {
         const { left, right } = this.labelGutters;
         return (left - right) / 2;
     }
-    /**
-     * Radius of the ring's outer edge, fitted to whatever the label gutters leave.
-     * A fully selected slice reaches `radius × growFactor`, so the room has to
-     * cover that — hence the divisor, which keeps even the grown slice inside the
-     * box (and holds the ring the same size whether or not anything is selected).
-     */
+    /** Fitted to what the gutters leave. The divisor keeps a fully selected slice (`radius * growFactor`) inside the box, and the ring one size whether or not anything is selected. */
     get outerRadius() {
         const { left, right } = this.labelGutters;
         const room = Math.min((this.box.width - left - right) / 2, this.box.height / 2 - this.labelRowHeight - 4);
         return Math.max(0, room / this.growFactor);
     }
-    /** Radius of the hole in the middle: a fraction of the outer radius, or explicit px. */
     get holeRadius() {
         const configured = this.s.ring.holeRadius;
         if (configured <= 0)
@@ -278,30 +194,22 @@ export class RingGeometry {
         const px = configured < 1 ? configured * this.outerRadius : configured;
         return Math.min(px, this.outerRadius * 0.95);
     }
-    /** Radius of the circle every leader elbows on, clear of even a popped-out slice. */
+    /** The circle every leader elbows on, clear of even a popped-out slice. */
     get elbowRadius() {
         return this.outerRadius + this.maxPop + LEADER_LENGTH;
     }
-    /** How far slice `index` is currently pushed out, in `[0, 1]`. */
     popOf(index) {
-        return clampUnit(this.s.pops[index] ?? 0);
+        return clamp(this.s.pops[index] ?? 0, 0, 1);
     }
-    /** Radius of slice `index`'s outer edge, its selection growth included. */
     anchorRadius(index) {
         return this.outerRadius + this.maxPop * this.popOf(index);
     }
-    /**
-     * Radius an inside label sits at on slice `index`: halfway across the band on a
-     * donut, and further out than halfway on a solid pie, where "halfway" would
-     * crowd the point every wedge converges on. Rides the slice's own pop, so an
-     * inside label travels out with the wedge it belongs to.
-     */
+    /** Halfway across the band on a donut, further out on a solid pie, where halfway would crowd the point the wedges converge on. Rides the slice's pop. */
     bandMidRadius(index) {
         const rim = this.anchorRadius(index);
         const hole = this.holeRadius;
         return hole > 0 ? (hole + rim) / 2 : rim * PIE_LABEL_RADIUS;
     }
-    /** The point slice `index`'s inside label is centred on. */
     insideAnchor(index) {
         const arc = this.arcs.find((a) => a.index === index);
         if (arc === undefined)
@@ -309,43 +217,22 @@ export class RingGeometry {
         const point = ringPoint(this.bandMidRadius(index), arc.mid);
         return { x: point.x + this.centerX, y: point.y };
     }
-    /**
-     * How selected the ring is overall, in `[0, 1]` — the most-grown slice. Rides
-     * the same tween the pops do, so the dim below arrives with the growth rather
-     * than needing an animation of its own.
-     */
+    /** The most-grown slice, so the dim in {@link sliceOpacity} rides the pops' tween. */
     get selectionStrength() {
         let strongest = 0;
         for (let i = 0; i < this.s.slices.length; i++)
             strongest = Math.max(strongest, this.popOf(i));
         return strongest;
     }
-    /**
-     * Opacity slice `index` (and its leader and label) is drawn at: full while
-     * nothing is selected, falling toward `dimOpacity` in proportion to how
-     * selected the *rest* of the ring is. A slice that's selected itself stays at
-     * full — the two factors cancel.
-     */
+    /** Opacity of slice `index` with its leader and label. */
     sliceOpacity(index) {
-        const focus = this.selectionStrength;
-        if (focus <= 0)
-            return 1;
-        return 1 - (1 - clampUnit(this.s.dimOpacity)) * focus * (1 - this.popOf(index));
+        return selectionFade(this.selectionStrength, this.s.dimOpacity, this.popOf(index));
     }
-    /** Slice `index`'s share of the ring as its label reads it, off the live values. */
     percentText(index) {
         const arc = this.arcs.find((a) => a.index === index);
         return formatPercent(arc?.fraction ?? 0);
     }
-    // ---- Label placement ---------------------------------------------------
-    /**
-     * Where every leader label sits and how its leader gets there. Labels are split
-     * into a right and a left column by their slice's bisector, each column is
-     * spread so nothing overlaps (and nothing leaves the box), and each leader is
-     * then built as wedge edge → elbow → label. The elbow rides the leader circle at
-     * the label's *settled* y, which keeps the final run horizontal and the whole
-     * polyline outside the ring however far the label was nudged.
-     */
+    /** Labels split into left and right columns by their slice's bisector, each spread so nothing overlaps or leaves the box, then a leader built to each. */
     placements() {
         if (!this.hasLeaderLabels)
             return [];
@@ -369,7 +256,7 @@ export class RingGeometry {
         return [...right, ...left].map((slot) => {
             const start = ringPoint(this.anchorRadius(slot.index) + LEADER_LIFTOFF, slot.mid);
             // The elbow sits where the label's y crosses the leader circle. Solving
-            // x² + y² = radius² for x keeps it *on* that circle (never inside the
+            // x^2 + y^2 = radius^2 for x keeps it on that circle (never inside the
             // ring); a label pushed past the circle's top or bottom falls back to the
             // sideways floor so its leader still reads as pointing outward.
             const onCircle = Math.sqrt(Math.max(0, radius * radius - slot.y * slot.y));
@@ -387,22 +274,15 @@ export class RingGeometry {
             };
         });
     }
-    /** This frame's placement for slice `index`, or `undefined` if it isn't leadered. */
     placementFor(index) {
         return this.placements().find((placement) => placement.index === index);
     }
 }
-/** Which side a leader off bisector `mid` runs to: +1 right, −1 left. */
 function sideOf(mid) {
     return Math.sin(mid) >= 0 ? 1 : -1;
 }
 const NO_BOX = { width: 0, height: 0 };
-/**
- * Each slice's fill, resolved once per paint rather than every frame: the slices
- * are bound to the chart's rows and palette, so a theme tween hands over new
- * paint and the drawing must see it, but a frame that moves nothing must not
- * re-resolve. Keyed by the paint itself, so it is shared and needs no node.
- */
+/** Fills resolved once per paint, not per frame: a theme tween hands over new paint, but a frame that moves nothing must not re-resolve. Keyed by the paint, so it needs no node. */
 const resolvedFills = new WeakMap();
 function resolvedFill(fill) {
     if (typeof fill !== "object" || fill === null)
@@ -412,35 +292,20 @@ function resolvedFill(fill) {
         resolvedFills.set(fill, resolved = fillOps.resolve(fill));
     return resolved;
 }
-/** Each slice's fill, resolved. */
 export function ringFills(slices) {
     return slices.map((slice) => resolvedFill(slice.fill));
 }
-/**
- * The labels a ring was built with: one per *drawn* slice (a zero-valued slice
- * gets no wedge, so no label either), in whichever of the two forms the chart
- * asked for, then the hole's summary. Both are real Text stacked in a hug
- * vertical flow — the difference is only what they are pinned to and which line
- * leads. The point each is pinned to stays reactive and follows the ring as the
- * box resizes or its slice pops out; only the choice of form, which depends on
- * entries alone, is settled here.
- */
+/** One label per drawn slice (a zero-valued slice has no wedge), then the hole's summary. Only the choice of form is settled here; the pinned points stay reactive. */
 function ringLabels(s) {
     const blocks = [];
-    // A label block's parent is the ring: its box is what the ring was laid out at.
+    // A label block's parent is the ring, whose box it was laid out at.
     const geometry = () => new RingGeometry(s, blocks[0]?.parent?.layoutBounds ?? NO_BOX);
     const label = (arc) => {
-        // Fades in with the ring's labels, then dims along with its own slice
-        // whenever another slice takes the focus.
-        const opacity = () => clampUnit(s.labelReveal) * geometry().sliceOpacity(arc.index);
+        const opacity = () => clamp(s.labelReveal, 0, 1) * geometry().sliceOpacity(arc.index);
         const wantsCategory = s.labelMode === "both" || s.labelMode === "category";
         const wantsPercent = s.labelMode === "both" || s.labelMode === "percent";
         if (s.labelPlacement === "inside") {
-            // The number leads and the caption sits under it: inside a wedge the
-            // reader already knows *which* wedge they are looking at, so the magnitude
-            // is what the label is for. Both sizes are bound rather than read once —
-            // the fitted size derives from the ring's radius, which isn't known until
-            // the node has been laid out.
+            // The number leads: inside a wedge the reader knows which slice it is. Sizes are bound because the fitted size derives from a radius unknown until layout.
             const inside = [];
             if (wantsPercent) {
                 inside.push(new Text({
@@ -491,7 +356,6 @@ function ringLabels(s) {
             gap: 2,
             align: side > 0 ? "centerLeft" : "centerRight",
             opacity,
-            // Exactly one of these is set; `undefined` anchors are ignored.
             centerLeft: side > 0 ? at : undefined,
             centerRight: side > 0 ? undefined : at,
             children,
@@ -501,8 +365,7 @@ function ringLabels(s) {
         for (const arc of pieArcs(s.slices, s.ring.startAngle))
             blocks.push(label(arc));
     }
-    // The hole's summary, pinned to the ring's centre so it tracks the sideways
-    // shift a one-sided label column puts on the ring.
+    // Pinned to the ring's centre, so it tracks the sideways shift a one-sided label column causes.
     if (s.centerLabel !== "" || s.centerCaption !== "") {
         const children = [];
         if (s.centerLabel !== "") {
@@ -525,7 +388,7 @@ function ringLabels(s) {
             height: "hug",
             gap: 2,
             align: "center",
-            opacity: () => clampUnit(s.centerReveal),
+            opacity: () => clamp(s.centerReveal, 0, 1),
             center: () => ({ x: geometry().centerX, y: 0 }),
             children,
         }));
@@ -533,43 +396,12 @@ function ringLabels(s) {
     return asParts(blocks);
 }
 /**
- * The ring itself: one wedge per {@link PieSlice}, sized by its share of the
- * total, swept clockwise from the theme's `startAngle` with a `gap` of clear
- * space between neighbours — a *constant-width* channel, the same at the hole as
- * at the rim (see {@link wedgePath}). A **selected** slice reaches further out
- * while its hole edge stays put — so it reads as that band swelling out of the
- * ring rather than breaking off it — and the rest of the ring dims behind it,
- * leaders and labels included.
- *
- * This is the only part of the chart family that draws a path: the wedges are
- * filled {@link PathBuilder} polygons approximating each arc, and the leaders are
- * stroked polylines — both in the node's centred, y-up space, so neither depends
- * on SVG arc-sweep conventions. The **labels are real {@link Text} nodes**
- * (stacked in a hug vertical flow and pinned by their inner edge), so no
- * glyph-width guesswork decides where a caption starts.
- *
- * ### Label placement
- * Each label sits either **inside** its wedge or **outside** on a leader.
- *
- * An inside label is centred on its slice's band and leads with the number, the
- * caption set small underneath — inside a wedge the reader already knows which
- * slice they're on, so the magnitude is the thing being read. It costs no gutter
- * and no eye round-trip, so a ring labelled that way draws considerably bigger in
- * the same box.
- *
- * A leader label sits outside on the end of a polyline that lifts off its wedge,
- * elbows, and runs horizontally into the text. Labels are split into a left and a
- * right column by which way their slice's bisector points, and each column is
- * de-conflicted independently (see {@link relaxLabels}): a label takes the spot
- * nearest its wedge that still clears its neighbour, and the column is squeezed
- * to fit the node's height rather than spilling out of it. The elbow then rides on
- * a circle just outside the ring **at the label's settled y**, so the run into the
- * text is always horizontal and a nudged label never drags its leader back across
- * the ring.
- *
- * Only the sides that actually carry a leader reserve a gutter, and the ring's
- * centre slides into whatever the other side left over — so a ring whose slices
- * all leader one way doesn't leave a bald patch on the other.
+ * The ring: one wedge per {@link PieSlice} swept clockwise from `startAngle`,
+ * with a constant-width `gap` (see {@link wedgePath}). A selected slice swells
+ * out while its hole edge stays put, and the rest dims, leaders and labels
+ * included. The only path-drawing part of the chart family; labels are real
+ * {@link Text} nodes, so no glyph-width guesswork places a caption. Only the
+ * sides that carry a leader reserve a gutter, and the ring slides into the rest.
  */
 export const PieRing = component2d({
     key: "pieRing",
@@ -577,50 +409,48 @@ export const PieRing = component2d({
         slices: fresh(() => []),
         ring: Types.custom(DEFAULT_PIE_CHART_THEME.ring),
         label: Types.custom(DEFAULT_PIE_CHART_THEME.label),
+        // Not `center`: every node already has one, the anchor its position is measured from.
         centerStyle: Types.custom(DEFAULT_PIE_CHART_THEME.center),
         labelMode: Types.custom("percent"),
         labelPlacement: Types.custom("leader"),
+        /** Sweep `[0, 1]`: the wedges grow clockwise from `startAngle` as it rises. */
         growth: 1,
+        /** Fade of leaders and labels, separate from `growth` so they arrive after the sweep. */
         labelReveal: 1,
+        /** Per-slice pop `[0, 1]`, owned by the chart so the ring and legend read one signal. */
         pops: fresh(() => []),
+        /** Opacity everything unselected falls back to while any slice is selected. */
         dimOpacity: DEFAULT_PIE_CHART_THEME.spotlight.dimOpacity,
+        /** Empty leaves the hole clear; ignored when there is no hole. */
         centerLabel: "",
         centerCaption: "",
+        /** The hole's summary fade, untouched by the entrance: a scene that wants the conclusion on a later beat sets 0 and calls `revealCenter`. */
         centerReveal: 1,
     },
     // A plain node filled its parent; one made of its labels would hug them.
     defaults: { width: "fill", height: "fill" },
     children: (state) => ringLabels(state),
-    // The ring's paints live nowhere a paint entry would look: one fill per slice,
-    // the wedge outline and drop shadow of `ring`, and the leader line's own stroke.
+    // The paints sit past the paint entries: a fill per slice, the wedge outline and shadow, and the leader stroke.
     load: (loader, state) => loadPaints(loader, {
         fills: ringFills(state.slices),
         shadows: [shadowOps.resolve(state.ring.shadow)],
         strokes: [strokeOps.resolve(state.ring.stroke), strokeOps.resolve(state.label.leaderStroke)],
     }),
     commands: {
-        /**
-         * Tween `growth` `0 → 1`, wiping the wedges in around the ring. No priming
-         * to 0 first — the value at `t` is a function of `t`, so a repeat call
-         * re-sweeps by definition rather than by having reset something.
-         */
+        /** Wipe the wedges in around the ring (`growth` 0 to 1). */
         sweep: (timeline) => {
             const ease = frameEase(timeline);
             return timeline.animate((t) => ({ growth: ease(t) }));
         },
-        /** Tween `labelReveal` `0 → 1`, fading the leaders and captions up. */
+        /** Fade the leaders and captions up. */
         revealLabels: (timeline) => {
             const ease = frameEase(timeline);
             return timeline.animate((t) => ({ labelReveal: ease(t) }));
         },
-        /**
-         * Fade the hole's summary up. Deliberately not part of the ring's entrance: a
-         * hole label is usually the chart's conclusion, so the scene decides when it
-         * lands.
-         */
+        /** Fade the hole's summary up; not part of the entrance, since it is usually the conclusion. */
         revealCenter: (timeline, state) => {
             const ease = frameEase(timeline);
-            const from = clampUnit(state.centerReveal);
+            const from = clamp(state.centerReveal, 0, 1);
             return timeline.animate((t) => ({ centerReveal: from + (1 - from) * ease(t) }));
         },
     },
@@ -629,16 +459,16 @@ export const PieRing = component2d({
         const rOuter = g.outerRadius;
         const arcs = rOuter > 0 ? g.arcs : [];
         if (arcs.length > 0) {
-            const sweep = clampUnit(state.growth);
+            const sweep = clamp(state.growth, 0, 1);
             const revealEnd = state.ring.startAngle * (Math.PI / 180) + Math.PI * 2 * sweep;
             const hole = g.holeRadius;
             const halfGap = Math.max(0, state.ring.gap) / 2;
             // One shared frame (the whole ring square, grown slices included) pinned onto
             // every wedge path, so `Graphics2D.path()` doesn't re-centre each wedge on its
             // own bbox and collapse them all onto the origin. It stays symmetric about the
-            // *node's* origin — so path coordinates land exactly in node space — and is
-            // grown by the ring's sideways offset rather than moved with it, which would
-            // undo the very shift it has to contain.
+            // node's origin, so path coordinates land exactly in node space, and is grown
+            // by the ring's sideways offset rather than moved with it, which would undo
+            // the very shift it has to contain.
             const cx = g.centerX;
             const half = rOuter + g.maxPop + 1 + Math.abs(cx);
             const centerBounds = [-half, -half, half, half];
@@ -648,8 +478,7 @@ export const PieRing = component2d({
             const span = half * 2;
             const fills = ringFills(state.slices);
             for (const arc of arcs) {
-                // Clip the wedge to the growth-revealed arc; skip it until the sweep
-                // reaches it, so the ring draws in as one clockwise wipe.
+                // Clipped to the revealed arc, so the ring draws in as one clockwise wipe.
                 const a1 = Math.min(arc.a1, revealEnd);
                 if (a1 <= arc.a0)
                     continue;
@@ -660,11 +489,10 @@ export const PieRing = component2d({
                 wedge.stroke(state.ring.stroke);
                 ctx.draw(wedge.opacity(g.sliceOpacity(arc.index)));
             }
-            // Leaders. Each polyline gets its own `Graphics2D`: several open polylines
-            // chained into one command list are combined into a single surface before the
-            // stroke, which closes each contour back on itself and paints the leaders as
-            // thin triangles.
-            const reveal = clampUnit(state.labelReveal);
+            // One `Graphics2D` per leader: open polylines chained into one command list
+            // are combined into a single surface before the stroke, which closes each
+            // contour and paints the leaders as thin triangles.
+            const reveal = clamp(state.labelReveal, 0, 1);
             if (reveal > 0.001) {
                 for (const placement of g.placements()) {
                     ctx.draw(new Graphics2D()