@motionscript/charts 0.1.0-alpha.0 → 0.1.0-alpha.10

package/src/pie-chart/pie-ring.ts

@@ -1,26 +1,26 @@
 import {
-  Rect,
-  command,
-  type AssetScope,
   Graphics2D,
-  Node2D,
   PathBuilder,
+  Rect,
   Text,
-  easeOut,
+  Types,
+  component2d,
   fillOps,
-  property,
+  shadowOps,
   strokeOps,
   textOps,
-  type Command,
-  type CommandArgs,
+  type Fill,
   type FillResolved,
-  type NodeConfig,
+  type NodeOf,
+  type Node2D,
   type Node2DProps,
-  type RenderContext2D,
   type TextStyle,
   type Vector2,
-} from "@motionscript/core"
+} from "@motionscript/sdk"
 
+import { asParts, fresh } from "../kit/entries"
+import { frameEase } from "../kit/motion"
+import { loadPaints } from "../kit/paints"
 import { clampUnit, formatPercent } from "../kit/shared"
 import {
   DEFAULT_PIE_CHART_THEME,
@@ -35,7 +35,6 @@ import {
   type PieSlice,
   type RingConfig,
 } from "./shared"
-import { declarePaints } from "@motionscript/core/component"
 
 export interface PieRingProps extends Node2DProps {
   /** One entry per slice: its `category`, `value` and `fill`. */
@@ -217,234 +216,40 @@ function wedgePath(
   return path
 }
 
+/** What the ring's geometry reads off its entries. */
+interface RingState {
+  readonly slices: PieSlice[]
+  readonly ring: RingConfig
+  readonly label: LabelConfig
+  readonly centerStyle: CenterConfig
+  readonly labelMode: PieLabelMode
+  readonly labelPlacement: PieLabelPlacement
+  readonly pops: readonly number[]
+  readonly dimOpacity: number
+  readonly centerLabel: string
+  readonly centerCaption: string
+}
+
 /**
- * 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 ({@link centerX}) — so a
- * ring whose slices all leader one way doesn't leave a bald patch on the other.
+ * 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.
  */
-export class PieRing extends Node2D<PieRingProps> {
-  @property({ default: () => [] as PieSlice[] }) declare slices: PieSlice[]
-  @property({ default: DEFAULT_PIE_CHART_THEME.ring }) declare ring: RingConfig
-  @property({ default: DEFAULT_PIE_CHART_THEME.label })
-  declare label: LabelConfig
-  @property({ default: DEFAULT_PIE_CHART_THEME.center })
-  declare centerStyle: CenterConfig
-  @property({ default: "percent" }) declare labelMode: PieLabelMode
-  @property({ default: "leader" }) declare labelPlacement: PieLabelPlacement
-  @property({ default: 1 }) declare growth: number
-  @property({ default: 1 }) declare labelReveal: number
-  @property({ default: () => [] as number[] }) declare pops: number[]
-  @property({ default: DEFAULT_PIE_CHART_THEME.spotlight.dimOpacity })
-  declare dimOpacity: number
-  @property({ default: "" }) declare centerLabel: string
-  @property({ default: "" }) declare centerCaption: string
-  @property({ default: 1 }) declare centerReveal: number
-
-  /** Each slice's fill, resolved once so `renderSelf` doesn't re-resolve every frame. */
-  private fills: FillResolved[][] = []
-
-  constructor(props?: NodeConfig<PieRing, PieRingProps>) {
-    super(props)
-
-    this.fills = this.slices.map((slice) => fillOps.resolve(slice.fill))
-
-    // One label per *drawn* slice (a zero-valued slice gets no wedge, so no
-    // label either), in whichever of the two forms the chart asked for. 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 label 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 props alone, is settled here.
-    if (this.labelPlacement !== "none" && this.labelMode !== "none") {
-      for (const arc of this.arcs) this.addLabel(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.
-    if (this.hasCenterLabel) this.addCenterLabel()
-  }
-
-  /** Build slice `arc`'s label, in whichever form the chart's placement asks for. */
-  private addLabel(arc: PieArc): void {
-    const slice = this.slices[arc.index]
-    // Fades in with the ring's labels, then dims along with its own slice
-    // whenever another slice takes the focus.
-    const opacity = () =>
-      clampUnit(this.labelReveal) * this.sliceOpacity(arc.index)
-    const wantsCategory =
-      this.labelMode === "both" || this.labelMode === "category"
-    const wantsPercent =
-      this.labelMode === "both" || this.labelMode === "percent"
-
-    if (this.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.
-      const inside: Node2D[] = []
-      if (wantsPercent) {
-        inside.push(
-          new Text({
-            ...textOps.styleProps(this.label.insideStyle),
-            text: formatPercent(arc.fraction),
-            fontSize: () => this.insideFont,
-          })
-        )
-      }
-      if (wantsCategory) {
-        inside.push(
-          new Text({
-            ...textOps.styleProps(this.label.insideStyle),
-            text: slice.category,
-            fontSize: () =>
-              this.labelMode === "category"
-                ? this.insideFont
-                : this.insideFont * INSIDE_CAPTION_RATIO,
-          })
-        )
-      }
-      this.add(
-        new Rect({ flow: "vertical",
-          width: "hug",
-          height: "hug",
-          gap: 0,
-          align: "center",
-          opacity,
-          center: () => this.insideAnchor(arc.index),
-          children: inside,
-        })
-      )
-      return
-    }
-
-    const side = this.sideOf(arc.mid)
-    const at = () => this.placementFor(arc.index)?.text ?? { x: 0, y: 0 }
-    const children: Node2D[] = []
-    if (wantsCategory) {
-      children.push(
-        new Text({
-          ...textOps.styleProps(this.label.textStyle),
-          text: slice.category,
-          textAlign: side > 0 ? "left" : "right",
-        })
-      )
-    }
-    if (wantsPercent) {
-      children.push(
-        new Text({
-          ...textOps.styleProps(this.label.percentStyle),
-          text: formatPercent(arc.fraction),
-          textAlign: side > 0 ? "left" : "right",
-        })
-      )
-    }
-    this.add(
-      new Rect({ flow: "vertical",
-        width: "hug",
-        height: "hug",
-        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,
-      })
-    )
-  }
-
-  /** Build the hole's summary block. */
-  private addCenterLabel(): void {
-    const children: Node2D[] = []
-    if (this.centerLabel !== "") {
-      children.push(
-        new Text({
-          ...textOps.styleProps(this.centerStyle.labelStyle),
-          text: this.centerLabel,
-          fontSize: () => this.centerFont,
-        })
-      )
-    }
-    if (this.centerCaption !== "") {
-      children.push(
-        new Text({
-          ...textOps.styleProps(this.centerStyle.captionStyle),
-          text: this.centerCaption,
-          fontSize: () =>
-            this.centerFont *
-            (sizeOf(this.centerStyle.captionStyle, 22) /
-              sizeOf(this.centerStyle.labelStyle, 46)),
-        })
-      )
-    }
-    this.add(
-      new Rect({ flow: "vertical",
-        width: "hug",
-        height: "hug",
-        gap: 2,
-        align: "center",
-        opacity: () => clampUnit(this.centerReveal),
-        center: () => ({ x: this.centerX, y: 0 }),
-        children,
-      })
-    )
-  }
-
-  // ---- Arcs --------------------------------------------------------------
+export class RingGeometry {
+  constructor(
+    private readonly s: RingState,
+    private readonly box: { readonly width: number; readonly height: number }
+  ) { }
 
   /** The drawn slices' angular spans, re-read every frame so a value tween re-cuts them. */
-  private get arcs(): PieArc[] {
-    return pieArcs(this.slices, this.ring.startAngle)
-  }
-
-  /** Which side a leader off bisector `mid` runs to: +1 right, −1 left. */
-  private sideOf(mid: number): 1 | -1 {
-    return Math.sin(mid) >= 0 ? 1 : -1
+  get arcs(): PieArc[] {
+    return pieArcs(this.s.slices, this.s.ring.startAngle)
   }
 
   /** Whether any slice is labelled on a leader — the only thing that costs a gutter. */
-  private get hasLeaderLabels(): boolean {
-    return (
-      this.labelPlacement === "leader" &&
-      this.labelMode !== "none" &&
-      this.arcs.length > 0
-    )
+  get hasLeaderLabels(): boolean {
+    return this.s.labelPlacement === "leader" && this.s.labelMode !== "none" && this.arcs.length > 0
   }
 
   // ---- Label sizing ------------------------------------------------------
@@ -465,7 +270,7 @@ export class PieRing extends Node2D<PieRingProps> {
    * Measured off the *unpopped* radius, so a slice growing out of the ring
    * doesn't resize its own text mid-animation.
    */
-  private insideRoom(arc: PieArc): number {
+  insideRoom(arc: PieArc): number {
     const outer = this.outerRadius
     const hole = this.holeRadius
     const band = hole > 0 ? outer - hole : outer * (1 - PIE_LABEL_RADIUS) * 2
@@ -478,20 +283,13 @@ export class PieRing extends Node2D<PieRingProps> {
   }
 
   /** Widest line, in glyphs at the leading line's size, an inside label runs to. */
-  private insideGlyphs(arc: PieArc): number {
-    const category = this.slices[arc.index]?.category.length ?? 0
-    const percent =
-      this.labelMode === "both" || this.labelMode === "percent"
-        ? formatPercent(arc.fraction).length
-        : 0
+  insideGlyphs(arc: PieArc): number {
+    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.
-    const caption =
-      this.labelMode === "category"
-        ? category
-        : this.labelMode === "both"
-          ? category * INSIDE_CAPTION_RATIO
-          : 0
+    const caption = mode === "category" ? category : mode === "both" ? category * INSIDE_CAPTION_RATIO : 0
     return Math.max(1, percent, caption)
   }
 
@@ -504,77 +302,63 @@ export class PieRing extends Node2D<PieRingProps> {
    * 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.
    */
-  private get insideFont(): number {
-    let size = sizeOf(this.label.insideStyle, FALLBACK_SIZE * 1.9)
+  get insideFont(): number {
+    let size = sizeOf(this.s.label.insideStyle, FALLBACK_SIZE * 1.9)
     for (const arc of this.arcs) {
-      const fits =
-        (this.insideRoom(arc) * INSIDE_LABEL_FIT) /
-        (this.insideGlyphs(arc) * GLYPH_RATIO)
+      const fits = (this.insideRoom(arc) * INSIDE_LABEL_FIT) / (this.insideGlyphs(arc) * GLYPH_RATIO)
       size = Math.min(size, fits)
     }
     return Math.max(1, size)
   }
 
-  /** Whether the hole carries a summary at all. */
-  private get hasCenterLabel(): boolean {
-    return this.centerLabel !== "" || this.centerCaption !== ""
-  }
-
   /**
    * 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.
    */
-  private get centerFont(): number {
-    const wanted = sizeOf(this.centerStyle.labelStyle, 46)
+  get centerFont(): number {
+    const { centerStyle, centerLabel, centerCaption } = this.s
+    const wanted = sizeOf(centerStyle.labelStyle, 46)
     const hole = this.holeRadius
     if (hole <= 0) return wanted
-    const captionRatio =
-      sizeOf(this.centerStyle.captionStyle, 22) / Math.max(1, 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.
-    const glyphs = Math.max(
-      1,
-      this.centerLabel.length,
-      this.centerCaption.length * captionRatio
-    )
+    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 layoutBounds ------------------------
+  // ---- Ring geometry, all derived from the box ---------------------------
 
   /** Rim radius of a fully selected slice as a multiple of the ring's, clamped sane. */
-  private get growFactor(): number {
-    return Math.max(1, Math.min(1.6, this.ring.selectedGrow))
+  get growFactor(): number {
+    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. */
-  private get maxPop(): number {
+  get maxPop(): number {
     return this.outerRadius * (this.growFactor - 1)
   }
 
   /** Height of one **leader** label block, in px — the unit those columns are spaced by. */
-  private get labelRowHeight(): number {
+  get labelRowHeight(): number {
     // 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.label.textStyle) * 1.25
-    const percent = sizeOf(this.label.percentStyle) * 1.25
-    if (this.labelMode === "both") return caption + percent + 2
-    return this.labelMode === "category" ? caption : percent
+    const caption = sizeOf(this.s.label.textStyle) * 1.25
+    const percent = sizeOf(this.s.label.percentStyle) * 1.25
+    if (this.s.labelMode === "both") 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. */
-  private captionGlyphs(index: number): number {
+  captionGlyphs(index: number): number {
+    const mode = this.s.labelMode
     // "100%" is the widest a percentage gets; captions are their own length.
-    const percent =
-      this.labelMode === "percent" || this.labelMode === "both" ? 4 : 0
-    const category =
-      this.labelMode === "category" || this.labelMode === "both"
-        ? (this.slices[index]?.category.length ?? 0)
-        : 0
+    const percent = mode === "percent" || mode === "both" ? 4 : 0
+    const category = mode === "category" || mode === "both" ? (this.s.slices[index]?.category.length ?? 0) : 0
     return Math.max(percent, category)
   }
 
@@ -586,18 +370,13 @@ export class PieRing extends Node2D<PieRingProps> {
    * Excludes the ring's own selection-growth allowance, which scales with the
    * radius and so is divided out in {@link outerRadius} instead.
    */
-  private get labelGutters(): { left: number; right: number } {
+  get labelGutters(): { left: number; right: number } {
     const gutters = { left: BARE_PAD, right: BARE_PAD }
     if (!this.hasLeaderLabels) return gutters
-    const glyph = sizeOf(this.label.textStyle) * GLYPH_RATIO
+    const glyph = sizeOf(this.s.label.textStyle) * GLYPH_RATIO
     for (const arc of this.arcs) {
-      const room =
-        LEADER_LENGTH +
-        LABEL_STUB +
-        TEXT_INSET +
-        this.captionGlyphs(arc.index) * glyph +
-        LABEL_PAD
-      const key = this.sideOf(arc.mid) > 0 ? "right" : "left"
+      const room = LEADER_LENGTH + LABEL_STUB + TEXT_INSET + this.captionGlyphs(arc.index) * glyph + LABEL_PAD
+      const key = sideOf(arc.mid) > 0 ? "right" : "left"
       gutters[key] = Math.max(gutters[key], room)
     }
     return gutters
@@ -609,7 +388,7 @@ export class PieRing extends Node2D<PieRingProps> {
    * 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.
    */
-  private get centerX(): number {
+  get centerX(): number {
     const { left, right } = this.labelGutters
     return (left - right) / 2
   }
@@ -620,35 +399,32 @@ export class PieRing extends Node2D<PieRingProps> {
    * 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).
    */
-  private get outerRadius(): number {
+  get outerRadius(): number {
     const { left, right } = this.labelGutters
-    const room = Math.min(
-      (this.layoutBounds.width - left - right) / 2,
-      this.layoutBounds.height / 2 - this.labelRowHeight - 4
-    )
+    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. */
-  private get holeRadius(): number {
-    const configured = this.ring.holeRadius
+  get holeRadius(): number {
+    const configured = this.s.ring.holeRadius
     if (configured <= 0) return 0
     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. */
-  private get elbowRadius(): number {
+  get elbowRadius(): number {
     return this.outerRadius + this.maxPop + LEADER_LENGTH
   }
 
   /** How far slice `index` is currently pushed out, in `[0, 1]`. */
-  private popOf(index: number): number {
-    return clampUnit(this.pops[index] ?? 0)
+  popOf(index: number): number {
+    return clampUnit(this.s.pops[index] ?? 0)
   }
 
   /** Radius of slice `index`'s outer edge, its selection growth included. */
-  private anchorRadius(index: number): number {
+  anchorRadius(index: number): number {
     return this.outerRadius + this.maxPop * this.popOf(index)
   }
 
@@ -658,14 +434,14 @@ export class PieRing extends Node2D<PieRingProps> {
    * 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.
    */
-  private bandMidRadius(index: number): number {
+  bandMidRadius(index: number): number {
     const rim = this.anchorRadius(index)
     const hole = this.holeRadius
     return hole > 0 ? (hole + rim) / 2 : rim * PIE_LABEL_RADIUS
   }
 
-  /** Node2D-space point slice `index`'s inside label is centred on. */
-  private insideAnchor(index: number): Vector2 {
+  /** The point slice `index`'s inside label is centred on. */
+  insideAnchor(index: number): Vector2 {
     const arc = this.arcs.find((a) => a.index === index)
     if (arc === undefined) return { x: this.centerX, y: 0 }
     const point = ringPoint(this.bandMidRadius(index), arc.mid)
@@ -677,24 +453,28 @@ export class PieRing extends Node2D<PieRingProps> {
    * the same tween the pops do, so the dim below arrives with the growth rather
    * than needing an animation of its own.
    */
-  private get selectionStrength(): number {
+  get selectionStrength(): number {
     let strongest = 0
-    for (let i = 0; i < this.slices.length; i++) {
-      strongest = Math.max(strongest, this.popOf(i))
-    }
+    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 {@link dimOpacity} in proportion to how
+   * 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.
    */
-  private sliceOpacity(index: number): number {
+  sliceOpacity(index: number): number {
     const focus = this.selectionStrength
     if (focus <= 0) return 1
-    return 1 - (1 - clampUnit(this.dimOpacity)) * focus * (1 - this.popOf(index))
+    return 1 - (1 - clampUnit(this.s.dimOpacity)) * focus * (1 - this.popOf(index))
+  }
+
+  /** Slice `index`'s share of the ring as its label reads it, off the live values. */
+  percentText(index: number): string {
+    const arc = this.arcs.find((a) => a.index === index)
+    return formatPercent(arc?.fraction ?? 0)
   }
 
   // ---- Label placement ---------------------------------------------------
@@ -707,14 +487,14 @@ export class PieRing extends Node2D<PieRingProps> {
    * the label's *settled* y, which keeps the final run horizontal and the whole
    * polyline outside the ring however far the label was nudged.
    */
-  private placements(): LabelPlacement[] {
+  placements(): LabelPlacement[] {
     if (!this.hasLeaderLabels) return []
     const arcs = this.arcs
     if (arcs.length === 0 || this.outerRadius <= 0) return []
 
     const radius = this.elbowRadius
     const rowHeight = this.labelRowHeight
-    const top = this.layoutBounds.height / 2 - rowHeight / 2
+    const top = this.box.height / 2 - rowHeight / 2
     const bottom = -top
     const cx = this.centerX
 
@@ -728,31 +508,20 @@ export class PieRing extends Node2D<PieRingProps> {
     const right: Slot[] = []
     const left: Slot[] = []
     for (const arc of arcs) {
-      const side = this.sideOf(arc.mid)
+      const side = sideOf(arc.mid)
       const ideal = ringPoint(radius, arc.mid).y
-      ;(side > 0 ? right : left).push({
-        index: arc.index,
-        side,
-        mid: arc.mid,
-        ideal,
-        y: ideal,
-      })
+      ;(side > 0 ? right : left).push({ index: arc.index, side, mid: arc.mid, ideal, y: ideal })
     }
     relaxLabels(right, rowHeight + LABEL_GAP, top, bottom)
     relaxLabels(left, rowHeight + LABEL_GAP, top, bottom)
 
     return [...right, ...left].map((slot) => {
-      const start = ringPoint(
-        this.anchorRadius(slot.index) + LEADER_LIFTOFF,
-        slot.mid
-      )
+      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
       // 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)
-      )
+      const onCircle = Math.sqrt(Math.max(0, radius * radius - slot.y * slot.y))
       const elbowX = cx + slot.side * Math.max(onCircle, radius * MIN_ELBOW)
       const endX = cx + slot.side * (radius + LABEL_STUB)
 
@@ -770,134 +539,310 @@ export class PieRing extends Node2D<PieRingProps> {
   }
 
   /** This frame's placement for slice `index`, or `undefined` if it isn't leadered. */
-  private placementFor(index: number): LabelPlacement | undefined {
+  placementFor(index: number): LabelPlacement | undefined {
     return this.placements().find((placement) => placement.index === index)
   }
+}
 
-  // ---- Draw --------------------------------------------------------------
+/** Which side a leader off bisector `mid` runs to: +1 right, −1 left. */
+function sideOf(mid: number): 1 | -1 {
+  return Math.sin(mid) >= 0 ? 1 : -1
+}
 
-  /**
-   * The ring's paints live nowhere `ShapeNode` would look: one fill per slice,
-   * resolved once into {@link fills}, plus the leader line's own stroke. Both are
-   * passed explicitly — see {@link declarePaints}.
-   */
-  override declareAssets(assets: AssetScope): void {
-    super.declareAssets(assets)
-    declarePaints(this, assets, {
-      fills: this.fills,
-      strokes: [strokeOps.resolve(this.label.leaderStroke)],
-    })
-  }
+const NO_BOX = { width: 0, height: 0 }
 
-  protected renderSelf(ctx: RenderContext2D): void {
-    const rOuter = this.outerRadius
-    if (rOuter <= 0) return
+/**
+ * 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.
+ */
+const resolvedFills = new WeakMap<object, FillResolved[]>()
 
-    const arcs = this.arcs
-    if (arcs.length === 0) return
+function resolvedFill(fill: Fill): FillResolved[] {
+  if (typeof fill !== "object" || fill === null) return fillOps.resolve(fill)
+  let resolved = resolvedFills.get(fill)
+  if (resolved === undefined) resolvedFills.set(fill, resolved = fillOps.resolve(fill))
+  return resolved
+}
 
-    const sweep = clampUnit(this.growth)
-    const revealEnd = this.ring.startAngle * (Math.PI / 180) + Math.PI * 2 * sweep
-    const hole = this.holeRadius
-    const halfGap = Math.max(0, this.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.
-    const cx = this.centerX
-    const half = rOuter + this.maxPop + 1 + Math.abs(cx)
-    const centerBounds: [number, number, number, number] = [
-      -half,
-      -half,
-      half,
-      half,
-    ]
-    // Explicit width/height alongside centerBounds: a wedge path's command list
-    // carries no implied extent, so a slice filled with an image or a video needs
-    // this to size its decode.
-    const span = half * 2
+/** Each slice's fill, resolved. */
+export function ringFills(slices: readonly PieSlice[]): FillResolved[][] {
+  return slices.map((slice) => resolvedFill(slice.fill))
+}
 
-    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.
-      const a1 = Math.min(arc.a1, revealEnd)
-      if (a1 <= arc.a0) continue
-
-      const path = wedgePath(
-        arc.a0,
-        a1,
-        hole,
-        this.anchorRadius(arc.index),
-        halfGap,
-        cx
-      )
-      const g = new Graphics2D().path(
-        path.toPathState({ centerBounds, width: span, height: span })
-      )
-      g.shadow(this.ring.shadow)
-      g.fill(this.fills[arc.index] ?? [])
-      g.stroke(this.ring.stroke)
-      ctx.draw(g.opacity(this.sliceOpacity(arc.index)))
-    }
+/**
+ * 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.
+ */
+function ringLabels(s: RingState & { readonly labelReveal: number; readonly centerReveal: number }) {
+  const blocks: Node2D[] = []
+  // A label block's parent is the ring: its box is what the ring was laid out at.
+  const geometry = () => new RingGeometry(s, (blocks[0]?.parent as Node2D | null | undefined)?.layoutBounds ?? NO_BOX)
 
-    // 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(this.labelReveal)
-    if (reveal <= 0.001) return
-    for (const placement of this.placements()) {
-      ctx.draw(
-        new Graphics2D()
-          .line({ points: placement.leader, radius: ELBOW_RADIUS })
-          .stroke(this.label.leaderStroke)
-          .opacity(reveal * this.sliceOpacity(placement.index))
-      )
-    }
-  }
+  const label = (arc: PieArc): Node2D => {
+    // 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 wantsCategory = s.labelMode === "both" || s.labelMode === "category"
+    const wantsPercent = s.labelMode === "both" || s.labelMode === "percent"
 
-  // ---- Entrance ----------------------------------------------------------
+    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.
+      const inside: Node2D[] = []
+      if (wantsPercent) {
+        inside.push(new Text({
+          ...textOps.styleProps(s.label.insideStyle),
+          text: () => geometry().percentText(arc.index),
+          fontSize: () => geometry().insideFont,
+        }))
+      }
+      if (wantsCategory) {
+        inside.push(new Text({
+          ...textOps.styleProps(s.label.insideStyle),
+          text: () => s.slices[arc.index]?.category ?? "",
+          fontSize: () => (s.labelMode === "category" ? geometry().insideFont : geometry().insideFont * INSIDE_CAPTION_RATIO),
+        }))
+      }
+      return new Rect({
+        flow: "vertical",
+        width: "hug",
+        height: "hug",
+        gap: 0,
+        align: "center",
+        opacity,
+        center: () => geometry().insideAnchor(arc.index),
+        children: inside,
+      })
+    }
 
-  /** Tween {@link growth} `0 → 1`, wiping the wedges in around the ring. */
-  @command()
-  sweep(
-    args: CommandArgs<Record<string, never>> & { duration: number }
-  ): Command<RingSweep> {
-    // 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.
-    return this.command<RingSweep>((t) => ({ growth: t }), args.duration, args.easing ?? easeOut())
+    const side = sideOf(arc.mid)
+    const at = () => geometry().placementFor(arc.index)?.text ?? { x: 0, y: 0 }
+    const children: Node2D[] = []
+    if (wantsCategory) {
+      children.push(new Text({
+        ...textOps.styleProps(s.label.textStyle),
+        text: () => s.slices[arc.index]?.category ?? "",
+        textAlign: side > 0 ? "left" : "right",
+      }))
+    }
+    if (wantsPercent) {
+      children.push(new Text({
+        ...textOps.styleProps(s.label.percentStyle),
+        text: () => geometry().percentText(arc.index),
+        textAlign: side > 0 ? "left" : "right",
+      }))
+    }
+    return new Rect({
+      flow: "vertical",
+      width: "hug",
+      height: "hug",
+      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,
+    })
   }
 
-  /** Tween {@link labelReveal} `0 → 1`, fading the leaders and captions up. */
-  @command()
-  revealLabels(
-    args: CommandArgs<Record<string, never>> & { duration: number }
-  ): Command<RingLabels> {
-    return this.command<RingLabels>((t) => ({ labelReveal: t }), args.duration, args.easing ?? easeOut())
+  if (s.labelPlacement !== "none" && s.labelMode !== "none") {
+    for (const arc of pieArcs(s.slices, s.ring.startAngle)) blocks.push(label(arc))
   }
 
-  /**
-   * 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.
-   */
-  @command()
-  revealCenter(
-    args: CommandArgs<Record<string, never>> & { duration?: number } = {}
-  ): Command<RingCenter> {
-    const from = clampUnit(this.centerReveal)
-    return this.command<RingCenter>(
-      (t) => ({ centerReveal: from + (1 - from) * t }),
-      args.duration ?? 0.6,
-      args.easing ?? easeOut()
-    )
-  }
+  // 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.
+  if (s.centerLabel !== "" || s.centerCaption !== "") {
+    const children: Node2D[] = []
+    if (s.centerLabel !== "") {
+      children.push(new Text({
+        ...textOps.styleProps(s.centerStyle.labelStyle),
+        text: s.centerLabel,
+        fontSize: () => geometry().centerFont,
+      }))
+    }
+    if (s.centerCaption !== "") {
+      children.push(new Text({
+        ...textOps.styleProps(s.centerStyle.captionStyle),
+        text: s.centerCaption,
+        fontSize: () =>
+          geometry().centerFont * (sizeOf(s.centerStyle.captionStyle, 22) / sizeOf(s.centerStyle.labelStyle, 46)),
+      }))
+    }
+    blocks.push(new Rect({
+      flow: "vertical",
+      width: "hug",
+      height: "hug",
+      gap: 2,
+      align: "center",
+      opacity: () => clampUnit(s.centerReveal),
+      center: () => ({ x: geometry().centerX, y: 0 }),
+      children,
+    }))
+  }
+  return asParts(blocks)
 }
 
-/** The signals the ring's own commands move, as props types. */
-type RingSweep = { growth: number }
-type RingLabels = { labelReveal: number }
-type RingCenter = { centerReveal: number }
+/**
+ * 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.
+ */
+export const PieRing = component2d({
+  key: "pieRing",
+  state: {
+    slices: fresh<PieSlice[]>(() => []),
+    ring: Types.custom<RingConfig>(DEFAULT_PIE_CHART_THEME.ring),
+    label: Types.custom<LabelConfig>(DEFAULT_PIE_CHART_THEME.label),
+    centerStyle: Types.custom<CenterConfig>(DEFAULT_PIE_CHART_THEME.center),
+    labelMode: Types.custom<PieLabelMode>("percent"),
+    labelPlacement: Types.custom<PieLabelPlacement>("leader"),
+    growth: 1,
+    labelReveal: 1,
+    pops: fresh<number[]>(() => []),
+    dimOpacity: DEFAULT_PIE_CHART_THEME.spotlight.dimOpacity,
+    centerLabel: "",
+    centerCaption: "",
+    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.
+  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.
+     */
+    sweep: (timeline) => {
+      const ease = frameEase(timeline)
+      return timeline.animate((t) => ({ growth: ease(t) }))
+    },
+    /** Tween `labelReveal` `0 → 1`, fading 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.
+     */
+    revealCenter: (timeline, state) => {
+      const ease = frameEase(timeline)
+      const from = clampUnit(state.centerReveal)
+      return timeline.animate((t) => ({ centerReveal: from + (1 - from) * ease(t) }))
+    },
+  },
+  render: (ctx, state) => {
+    const g = new RingGeometry(state, ctx.size)
+    const rOuter = g.outerRadius
+    const arcs = rOuter > 0 ? g.arcs : []
+    if (arcs.length > 0) {
+      const sweep = clampUnit(state.growth)
+      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.
+      const cx = g.centerX
+      const half = rOuter + g.maxPop + 1 + Math.abs(cx)
+      const centerBounds: [number, number, number, number] = [-half, -half, half, half]
+      // Explicit width/height alongside centerBounds: a wedge path's command list
+      // carries no implied extent, so a slice filled with an image or a video needs
+      // this to size its decode.
+      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.
+        const a1 = Math.min(arc.a1, revealEnd)
+        if (a1 <= arc.a0) continue
+
+        const path = wedgePath(arc.a0, a1, hole, g.anchorRadius(arc.index), halfGap, cx)
+        const wedge = new Graphics2D().path(path.toPathState({ centerBounds, width: span, height: span }))
+        wedge.shadow(state.ring.shadow)
+        wedge.fill(fills[arc.index] ?? [])
+        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)
+      if (reveal > 0.001) {
+        for (const placement of g.placements()) {
+          ctx.draw(
+            new Graphics2D()
+              .line({ points: placement.leader, radius: ELBOW_RADIUS })
+              .stroke(state.label.leaderStroke)
+              .opacity(reveal * g.sliceOpacity(placement.index))
+          )
+        }
+      }
+    }
+    ctx.children()
+  },
+})
+
+export type PieRing = NodeOf<typeof PieRing>