@motionscript/charts 0.1.0-alpha.3 → 0.1.0-alpha.5

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

@@ -1,159 +1,159 @@
-import {
-  command,
-  Rect,
-  Text,
-  easeOut,
-  property,
-  textOps,
-  type CommandArgs,
-  type NodeConfig,
-  type RectProps,
-} from "@motionscript/sdk"
-
-import {
-  DEFAULT_LEGEND,
-  clampUnit,
-  type LegendConfig,
-} from "../kit/shared"
-import { at, compose, hold, type Seekable } from "@motionscript/sdk/component"
-import type { PieSlice } from "./shared"
-
-export interface PieLegendProps extends RectProps {
-  /** One entry per slice, in ring order. */
-  slices: PieSlice[]
-  /** Padding, caption style, gaps, and swatch geometry — see {@link LegendConfig}. */
-  legend: LegendConfig
-  /**
-   * Per-slice opacity multiplier, by index — the same signal that dims the ring,
-   * so an entry fades in step with the wedge it names. Missing entries read as 1.
-   */
-  dims: number[]
-}
-
-/** How far an entry starts to the right of its slot when it enters, in px. */
-const SLIDE = 16
-
-/**
- * The legend of a {@link PieChart}: a **vertical-flow column** of entries, one per
- * slice, each pairing the slice's caption with its colour swatch.
- *
- * A column rather than the cartesian charts' row, because it sits *beside* the
- * ring rather than beneath the plot — a pie is as tall as it is wide, so the
- * space it leaves over is a vertical strip. It is otherwise the same entry: the
- * swatch carries the colour, the caption reads in the legend's neutral ink, and
- * both take the shared {@link LegendConfig}.
- *
- * There is no show/hide here. A pie's marks are its *rows*, and a row that
- * shouldn't be in the chart shouldn't be in the table — removing one would
- * silently re-cut every other wedge's share, which is a different chart rather
- * than the same chart with something hidden. Selection is what a pie has
- * instead, and it arrives through {@link dims}.
- */
-export class PieLegend extends Rect {
-  @property({ default: () => [] as PieSlice[] }) declare slices: PieSlice[]
-  @property({ default: DEFAULT_LEGEND }) declare legend: LegendConfig
-  @property({ default: () => [] as number[] }) declare dims: number[]
-
-  /** One entry per slice, ordered top → bottom, for the staggered entrance. */
-  private items: Rect[] = []
-
-  constructor(props?: NodeConfig<PieLegend, PieLegendProps>) {
-    // `flow` with the rest of the fixed geometry, and for the reason
-    // {@link ChartLegend} spells out: a `Rect` given none lays its children out
-    // `freeform`, so an unstated column is every caption drawn on top of the
-    // last one.
-    super({
-      ...(props as RectProps),
-      flow: "vertical",
-      align: "centerLeft",
-      width: "hug",
-      height: "hug",
-    })
-
-    // Fixed column geometry last, so it wins over what super() applied.
-    this.set({ gap: this.legend.itemGap / 3, padding: this.legend.padding })
-
-    for (let i = 0; i < this.slices.length; i++) {
-      const item = this.buildItem(this.slices[i])
-      this.items.push(item)
-      // The selection dim rides a wrapper rather than the entry itself, so the
-      // entrance can animate the entry's own opacity without the two fighting
-      // over one value — opacity multiplies down the tree, which is exactly the
-      // composition wanted here.
-      this.add(
-        new Rect({
-          width: "hug",
-          height: "hug",
-          flow: "freeform",
-          opacity: () => clampUnit(this.dims[i] ?? 1),
-          children: [item],
-        })
-      )
-    }
-  }
-
-  /** One entry: the slice's colour swatch beside its caption. */
-  private buildItem(slice: PieSlice): Rect {
-    const marker = this.legend.markerStyle
-    return new Rect({ flow: "horizontal",
-      gap: 12,
-      align: "center",
-      width: "hug",
-      height: "hug",
-      children: [
-        new Rect({
-          width: marker.height,
-          height: marker.height,
-          cornerRadius: marker.borderRadius,
-          fill: slice.fill,
-          stroke: marker.stroke,
-          shadow: marker.shadow,
-        }),
-        new Text({
-          ...textOps.styleProps(this.legend.textStyle),
-          text: slice.category,
-        }),
-      ],
-    })
-  }
-
-  /**
-   * Prime every entry at its pre-entrance state: shifted right and transparent.
-   *
-   * Idempotent, and separate from {@link enter} so the chart can arm its whole
-   * composition before the first frame is drawn — the resting state is the
-   * finished legend, so there is nothing hidden to reveal unless a scene asks.
-   */
-  arm(slide = SLIDE): void {
-    for (const item of this.items) item.set({ opacity: 0, x: slide })
-  }
-
-  /**
-   * Slide + fade every entry in from the right, staggered top-to-bottom.
-   *
-   * `duration` is the **whole** entrance: the stagger is carved out of it rather
-   * than added on top, so the command takes exactly the time the timeline laid
-   * out for it.
-   */
-  @command()
-  enter(
-    args: CommandArgs<Record<string, never>> & { duration: number }
-  ): Seekable {
-    const duration = args.duration
-    const easing = args.easing ?? easeOut()
-    const items = this.items
-    if (items.length === 0) return hold(duration)
-    this.arm()
-
-    // Each gap is a fifth of an entry's own move, the rhythm the axes use;
-    // solved for from the budget rather than added to it. The offsets were
-    // always `i * step` — written as `wait` inside a generator they merely only
-    // existed while it ran.
-    const per = duration / (1 + Math.max(0, items.length - 1) / 5)
-    const step = per / 5
-
-    return compose(
-      items.map((item, i) => at(i * step, item.to({ data: { opacity: 1, x: 0 }, duration: per, easing })))
-    )
-  }
-}
+import {
+  command,
+  Rect,
+  Text,
+  easeOut,
+  property,
+  textOps,
+  type CommandArgs,
+  type NodeConfig,
+  type RectProps,
+} from "@motionscript/sdk"
+
+import {
+  DEFAULT_LEGEND,
+  clampUnit,
+  type LegendConfig,
+} from "../kit/shared"
+import { at, compose, hold, type Seekable } from "@motionscript/sdk/component"
+import type { PieSlice } from "./shared"
+
+export interface PieLegendProps extends RectProps {
+  /** One entry per slice, in ring order. */
+  slices: PieSlice[]
+  /** Padding, caption style, gaps, and swatch geometry — see {@link LegendConfig}. */
+  legend: LegendConfig
+  /**
+   * Per-slice opacity multiplier, by index — the same signal that dims the ring,
+   * so an entry fades in step with the wedge it names. Missing entries read as 1.
+   */
+  dims: number[]
+}
+
+/** How far an entry starts to the right of its slot when it enters, in px. */
+const SLIDE = 16
+
+/**
+ * The legend of a {@link PieChart}: a **vertical-flow column** of entries, one per
+ * slice, each pairing the slice's caption with its colour swatch.
+ *
+ * A column rather than the cartesian charts' row, because it sits *beside* the
+ * ring rather than beneath the plot — a pie is as tall as it is wide, so the
+ * space it leaves over is a vertical strip. It is otherwise the same entry: the
+ * swatch carries the colour, the caption reads in the legend's neutral ink, and
+ * both take the shared {@link LegendConfig}.
+ *
+ * There is no show/hide here. A pie's marks are its *rows*, and a row that
+ * shouldn't be in the chart shouldn't be in the table — removing one would
+ * silently re-cut every other wedge's share, which is a different chart rather
+ * than the same chart with something hidden. Selection is what a pie has
+ * instead, and it arrives through {@link dims}.
+ */
+export class PieLegend extends Rect {
+  @property({ default: () => [] as PieSlice[] }) declare slices: PieSlice[]
+  @property({ default: DEFAULT_LEGEND }) declare legend: LegendConfig
+  @property({ default: () => [] as number[] }) declare dims: number[]
+
+  /** One entry per slice, ordered top → bottom, for the staggered entrance. */
+  private items: Rect[] = []
+
+  constructor(props?: NodeConfig<PieLegend, PieLegendProps>) {
+    // `flow` with the rest of the fixed geometry, and for the reason
+    // {@link ChartLegend} spells out: a `Rect` given none lays its children out
+    // `freeform`, so an unstated column is every caption drawn on top of the
+    // last one.
+    super({
+      ...(props as RectProps),
+      flow: "vertical",
+      align: "centerLeft",
+      width: "hug",
+      height: "hug",
+    })
+
+    // Fixed column geometry last, so it wins over what super() applied.
+    this.set({ gap: this.legend.itemGap / 3, padding: this.legend.padding })
+
+    for (let i = 0; i < this.slices.length; i++) {
+      const item = this.buildItem(i)
+      this.items.push(item)
+      // The selection dim rides a wrapper rather than the entry itself, so the
+      // entrance can animate the entry's own opacity without the two fighting
+      // over one value — opacity multiplies down the tree, which is exactly the
+      // composition wanted here.
+      this.add(
+        new Rect({
+          width: "hug",
+          height: "hug",
+          flow: "freeform",
+          opacity: () => clampUnit(this.dims[i] ?? 1),
+          children: [item],
+        })
+      )
+    }
+  }
+
+  /** One entry: the slice's colour swatch beside its caption. */
+  private buildItem(index: number): Rect {
+    const marker = this.legend.markerStyle
+    return new Rect({ flow: "horizontal",
+      gap: 12,
+      align: "center",
+      width: "hug",
+      height: "hug",
+      children: [
+        new Rect({
+          width: marker.height,
+          height: marker.height,
+          cornerRadius: marker.borderRadius,
+          fill: () => this.slices[index]?.fill ?? "white",
+          stroke: marker.stroke,
+          shadow: marker.shadow,
+        }),
+        new Text({
+          ...textOps.styleProps(this.legend.textStyle),
+          text: () => this.slices[index]?.category ?? "",
+        }),
+      ],
+    })
+  }
+
+  /**
+   * Prime every entry at its pre-entrance state: shifted right and transparent.
+   *
+   * Idempotent, and separate from {@link enter} so the chart can arm its whole
+   * composition before the first frame is drawn — the resting state is the
+   * finished legend, so there is nothing hidden to reveal unless a scene asks.
+   */
+  arm(slide = SLIDE): void {
+    for (const item of this.items) item.set({ opacity: 0, x: slide })
+  }
+
+  /**
+   * Slide + fade every entry in from the right, staggered top-to-bottom.
+   *
+   * `duration` is the **whole** entrance: the stagger is carved out of it rather
+   * than added on top, so the command takes exactly the time the timeline laid
+   * out for it.
+   */
+  @command()
+  enter(
+    args: CommandArgs<Record<string, never>> & { duration: number }
+  ): Seekable {
+    const duration = args.duration
+    const easing = args.easing ?? easeOut()
+    const items = this.items
+    if (items.length === 0) return hold(duration)
+    this.arm()
+
+    // Each gap is a fifth of an entry's own move, the rhythm the axes use;
+    // solved for from the budget rather than added to it. The offsets were
+    // always `i * step` — written as `wait` inside a generator they merely only
+    // existed while it ran.
+    const per = duration / (1 + Math.max(0, items.length - 1) / 5)
+    const step = per / 5
+
+    return compose(
+      items.map((item, i) => at(i * step, item.to({ data: { opacity: 1, x: 0 }, duration: per, easing })))
+    )
+  }
+}