@motionscript/charts 0.0.0-stage → 0.1.0-alpha.10

package/dist/pie-chart/pie-ring.d.ts

@@ -0,0 +1,304 @@
+import { type FillResolved, type NodeOf, type Node2D, type Node2DProps, type Vector2 } from "@motionscript/sdk";
+import { type CenterConfig, type LabelConfig, type PieArc, type PieLabelMode, type PieLabelPlacement, type PieSlice, type RingConfig } from "./shared.js";
+export interface PieRingProps extends Node2DProps {
+    /** One entry per slice: its `category`, `value` and `fill`. */
+    slices: PieSlice[];
+    /** Ring geometry and paint — gap, hole, start angle, selection growth. */
+    ring: RingConfig;
+    /** How the labels are set, and the leader lines that point at them. */
+    label: LabelConfig;
+    /**
+     * How the hole's summary is set.
+     *
+     * Named `centerStyle` rather than `center` because every node already has a
+     * `center` — the anchor its position is measured from.
+     */
+    centerStyle: CenterConfig;
+    /** What the labels say, or `"none"` to drop them entirely. */
+    labelMode: PieLabelMode;
+    /** Where the labels sit: inside their wedge, outside on a leader, or nowhere. */
+    labelPlacement: PieLabelPlacement;
+    /**
+     * Sweep of the ring in `[0, 1]`: 0 draws nothing, 1 the full circle. The
+     * wedges grow around clockwise from the ring's `startAngle` as this rises.
+     */
+    growth: number;
+    /**
+     * Fade of the leader lines and labels in `[0, 1]`, held separate from
+     * {@link growth} so they arrive *after* the ring has swept in.
+     */
+    labelReveal: number;
+    /**
+     * How far each slice is currently pushed out of the ring, `0`–`1` per index.
+     * Owned by the chart, so the ring and the legend read one signal.
+     */
+    pops: number[];
+    /** Opacity everything *unselected* falls back to while any slice is selected. */
+    dimOpacity: number;
+    /**
+     * Text set in the middle of the ring's hole — the largest uninterrupted area
+     * the chart owns, and on a donut otherwise empty. A one-line summary there
+     * routinely does more work than the whole ring around it. Empty (the default)
+     * leaves the hole clear; ignored when there is no hole.
+     */
+    centerLabel: string;
+    /** Smaller second line under {@link centerLabel}. Empty (the default) drops it. */
+    centerCaption: string;
+    /**
+     * Fade of the hole's summary in `[0, 1]`. Its own signal, untouched by the
+     * ring's entrance — a hole label is usually a *conclusion*, so a scene that
+     * wants it to land on a later beat sets this to 0 and calls
+     * `PieChart.revealCenter` when it gets there.
+     */
+    centerReveal: number;
+}
+/** Where one slice's label sits and the polyline that points at it. */
+interface LabelPlacement {
+    /** Index of the slice. */
+    index: number;
+    /** Which side of the ring the label sits on: +1 right, −1 left. */
+    side: 1 | -1;
+    /** Leader polyline: wedge edge → elbow → label. */
+    leader: Vector2[];
+    /** Point the label's inner edge is pinned to. */
+    text: Vector2;
+}
+/** 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'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 declare class RingGeometry {
+    private readonly s;
+    private readonly box;
+    constructor(s: RingState, box: {
+        readonly width: number;
+        readonly height: number;
+    });
+    /** The drawn slices' angular spans, re-read every frame so a value tween re-cuts them. */
+    get arcs(): PieArc[];
+    /** Whether any slice is labelled on a leader — the only thing that costs a gutter. */
+    get hasLeaderLabels(): boolean;
+    /**
+     * 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.
+     */
+    insideRoom(arc: PieArc): number;
+    /** Widest line, in glyphs at the leading line's size, an inside label runs to. */
+    insideGlyphs(arc: PieArc): number;
+    /**
+     * 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.
+     */
+    get insideFont(): number;
+    /**
+     * 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.
+     */
+    get centerFont(): number;
+    /** Rim radius of a fully selected slice as a multiple of the ring's, clamped sane. */
+    get growFactor(): number;
+    /** How far past the ring's rim a fully selected slice reaches, in px. */
+    get maxPop(): number;
+    /** Height of one **leader** label block, in px — the unit those columns are spaced by. */
+    get labelRowHeight(): number;
+    /** Widest line, in glyphs, that a leader label for slice `index` can run to. */
+    captionGlyphs(index: number): number;
+    /**
+     * 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.
+     */
+    get labelGutters(): {
+        left: number;
+        right: number;
+    };
+    /**
+     * 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.
+     */
+    get centerX(): number;
+    /**
+     * 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).
+     */
+    get outerRadius(): number;
+    /** Radius of the hole in the middle: a fraction of the outer radius, or explicit px. */
+    get holeRadius(): number;
+    /** Radius of the circle every leader elbows on, clear of even a popped-out slice. */
+    get elbowRadius(): number;
+    /** How far slice `index` is currently pushed out, in `[0, 1]`. */
+    popOf(index: number): number;
+    /** Radius of slice `index`'s outer edge, its selection growth included. */
+    anchorRadius(index: number): number;
+    /**
+     * 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.
+     */
+    bandMidRadius(index: number): number;
+    /** The point slice `index`'s inside label is centred on. */
+    insideAnchor(index: number): Vector2;
+    /**
+     * 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.
+     */
+    get selectionStrength(): number;
+    /**
+     * 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.
+     */
+    sliceOpacity(index: number): number;
+    /** Slice `index`'s share of the ring as its label reads it, off the live values. */
+    percentText(index: number): string;
+    /**
+     * 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.
+     */
+    placements(): LabelPlacement[];
+    /** This frame's placement for slice `index`, or `undefined` if it isn't leadered. */
+    placementFor(index: number): LabelPlacement | undefined;
+}
+/** Each slice's fill, resolved. */
+export declare function ringFills(slices: readonly PieSlice[]): FillResolved[][];
+/**
+ * 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 declare const PieRing: import("@motionscript/sdk").Component<"pieRing", import("@motionscript/sdk").Merge<import("@motionscript/sdk").Box2DState, {
+    readonly slices: import("@motionscript/sdk").Type<PieSlice[], PieSlice[], false>;
+    readonly ring: import("@motionscript/sdk").Type<RingConfig, RingConfig, false>;
+    readonly label: import("@motionscript/sdk").Type<LabelConfig, LabelConfig, false>;
+    readonly centerStyle: import("@motionscript/sdk").Type<CenterConfig, CenterConfig, false>;
+    readonly labelMode: import("@motionscript/sdk").Type<PieLabelMode, PieLabelMode, false>;
+    readonly labelPlacement: import("@motionscript/sdk").Type<PieLabelPlacement, PieLabelPlacement, false>;
+    readonly growth: 1;
+    readonly labelReveal: 1;
+    readonly pops: import("@motionscript/sdk").Type<number[], number[], false>;
+    readonly dimOpacity: number;
+    readonly centerLabel: "";
+    readonly centerCaption: "";
+    readonly centerReveal: 1;
+}>, {
+    readonly sweep: unknown;
+    readonly revealLabels: unknown;
+    readonly revealCenter: unknown;
+}, null, Node2D<Node2DProps>, import("@motionscript/sdk").CallProps<import("@motionscript/sdk").Merge<import("@motionscript/sdk").Box2DState, {
+    readonly slices: import("@motionscript/sdk").Type<PieSlice[], PieSlice[], false>;
+    readonly ring: import("@motionscript/sdk").Type<RingConfig, RingConfig, false>;
+    readonly label: import("@motionscript/sdk").Type<LabelConfig, LabelConfig, false>;
+    readonly centerStyle: import("@motionscript/sdk").Type<CenterConfig, CenterConfig, false>;
+    readonly labelMode: import("@motionscript/sdk").Type<PieLabelMode, PieLabelMode, false>;
+    readonly labelPlacement: import("@motionscript/sdk").Type<PieLabelPlacement, PieLabelPlacement, false>;
+    readonly growth: 1;
+    readonly labelReveal: 1;
+    readonly pops: import("@motionscript/sdk").Type<number[], number[], false>;
+    readonly dimOpacity: number;
+    readonly centerLabel: "";
+    readonly centerCaption: "";
+    readonly centerReveal: 1;
+}>, null, import("@motionscript/sdk").BuiltNode<import("@motionscript/sdk").Merge<import("@motionscript/sdk").Box2DState, {
+    readonly slices: import("@motionscript/sdk").Type<PieSlice[], PieSlice[], false>;
+    readonly ring: import("@motionscript/sdk").Type<RingConfig, RingConfig, false>;
+    readonly label: import("@motionscript/sdk").Type<LabelConfig, LabelConfig, false>;
+    readonly centerStyle: import("@motionscript/sdk").Type<CenterConfig, CenterConfig, false>;
+    readonly labelMode: import("@motionscript/sdk").Type<PieLabelMode, PieLabelMode, false>;
+    readonly labelPlacement: import("@motionscript/sdk").Type<PieLabelPlacement, PieLabelPlacement, false>;
+    readonly growth: 1;
+    readonly labelReveal: 1;
+    readonly pops: import("@motionscript/sdk").Type<number[], number[], false>;
+    readonly dimOpacity: number;
+    readonly centerLabel: "";
+    readonly centerCaption: "";
+    readonly centerReveal: 1;
+}>, {
+    readonly sweep: unknown;
+    readonly revealLabels: unknown;
+    readonly revealCenter: unknown;
+}, Node2D<Node2DProps>>>>;
+export type PieRing = NodeOf<typeof PieRing>;
+export {};
+//# sourceMappingURL=pie-ring.d.ts.map

package/dist/pie-chart/pie-ring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pie-ring.d.ts","sourceRoot":"","sources":["../../src/pie-chart/pie-ring.ts"],"names":[],"mappings":"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"}