semiotic 3.5.1 → 3.5.2

package/ai/system-prompt.md

@@ -1,6 +1,9 @@
 # Semiotic — React Data Visualization
 
-Use sub-path imports: `semiotic/xy` (143KB gz), `semiotic/ordinal` (109KB), `semiotic/network` (98KB), `semiotic/geo` (93KB), `semiotic/realtime` (145KB). Or `semiotic/ai` for all 39 non-geo HOCs in one import (269KB).
+<!-- semiotic-bundle-sizes:start -->
+<!-- Auto-generated by scripts/sync-bundle-sizes.mjs — do not edit by hand. -->
+**Use sub-path imports** — `semiotic/xy` (83KB gz), `semiotic/ordinal` (67KB gz), `semiotic/network` (62KB gz), `semiotic/geo` (50KB gz), `semiotic/realtime` (88KB gz), `semiotic/server` (114KB gz), `semiotic/utils` (22KB gz), `semiotic/recipes` (5KB gz), `semiotic/themes` (4KB gz), `semiotic/data` (3KB gz), `semiotic/ai` (184KB gz). Full `semiotic` is 183KB gz.
+<!-- semiotic-bundle-sizes:end -->
 
 ## Flat Array Data (`data: object[]`)
 - **LineChart** — `xAccessor`, `yAccessor`, `lineBy` (multi-line), `curve`

package/dist/components/Tooltip/FlippingTooltip.d.ts

@@ -29,6 +29,21 @@ interface FlippingTooltipProps {
  * On first render, uses a heuristic (similar to the old 70%/30% thresholds).
  * After measuring the actual tooltip size via ref, repositions precisely to
  * prevent clipping against container edges.
+ *
+ * Two defensive behaviors:
+ *
+ *   - **Chrome guarantee.** If the rendered tooltip content lacks the
+ *     `semiotic-tooltip` className on its root, the wrapper applies
+ *     `defaultTooltipStyle` to itself so the tooltip always has a
+ *     visible background, padding, and shadow. Shared tooltip helpers
+ *     keep working unchanged (their `semiotic-tooltip` class causes the
+ *     wrapper to stay transparent).
+ *   - **Non-finite position guard.** Returns `null` when `x` or `y` is
+ *     `NaN` / `Infinity`. The frame's hover plumbing can occasionally
+ *     produce a non-finite hit-test result during a scale rebuild or
+ *     when a custom layout emits a degenerate vertex; without the
+ *     guard, React throws `'NaN' is an invalid value for the 'top' css
+ *     style property` and the entire frame stops rendering.
  */
-export declare function FlippingTooltip({ x, y, containerWidth, containerHeight, margin, children, className, zIndex }: FlippingTooltipProps): import("react/jsx-runtime").JSX.Element;
+export declare function FlippingTooltip({ x, y, containerWidth, containerHeight, margin, children, className, zIndex }: FlippingTooltipProps): import("react/jsx-runtime").JSX.Element | null;
 export {};

package/dist/components/charts/geo/FlowMap.d.ts

@@ -1,5 +1,7 @@
 import type { Datum } from "../shared/datumTypes";
+import * as React from "react";
 import type { StreamGeoFrameProps, ProjectionProp } from "../../stream/geoTypes";
+import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
@@ -79,6 +81,13 @@ export interface FlowMapProps<TDatum extends Datum = Datum> extends BaseChartPro
     tileCacheSize?: number;
     /** Annotations */
     annotations?: Datum[];
+    /**
+     * ID accessor on flow records — required for `ref.current.remove(id)`
+     * and `ref.current.update(id, …)`. The accessor reads the same field
+     * the user supplies on each flow; the field is preserved on the
+     * resolved line entry so the frame's `removeLine` can match by id.
+     */
+    lineIdAccessor?: string | ((d: Datum) => string);
     /** Passthrough */
     frameProps?: Partial<Omit<StreamGeoFrameProps, "projection">>;
 }
@@ -132,7 +141,7 @@ export interface FlowMapProps<TDatum extends Datum = Datum> extends BaseChartPro
  * />
  * ```
  */
-export declare function FlowMap<TDatum extends Datum = Datum>(props: FlowMapProps<TDatum>): import("react/jsx-runtime").JSX.Element;
-export declare namespace FlowMap {
-    var displayName: string;
-}
+export declare const FlowMap: {
+    <TDatum extends Datum = Datum>(props: FlowMapProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

package/dist/components/charts/index.d.ts

@@ -14,6 +14,8 @@ export { LineChart } from "./xy/LineChart";
 export type { LineChartProps } from "./xy/LineChart";
 export { AreaChart } from "./xy/AreaChart";
 export type { AreaChartProps } from "./xy/AreaChart";
+export { DifferenceChart } from "./xy/DifferenceChart";
+export type { DifferenceChartProps } from "./xy/DifferenceChart";
 export { StackedAreaChart } from "./xy/StackedAreaChart";
 export type { StackedAreaChartProps } from "./xy/StackedAreaChart";
 export { Heatmap } from "./xy/Heatmap";
@@ -72,6 +74,10 @@ export { ChordDiagram } from "./network/ChordDiagram";
 export type { ChordDiagramProps } from "./network/ChordDiagram";
 export { SankeyDiagram } from "./network/SankeyDiagram";
 export type { SankeyDiagramProps } from "./network/SankeyDiagram";
+export { ProcessSankey } from "./network/ProcessSankey";
+export type { ProcessSankeyProps, ProcessSankeyTick } from "./network/ProcessSankey";
+export { validateProcessSankey, formatProcessSankeyIssue, } from "./network/processSankey/algorithm";
+export type { ProcessSankeyNode as ProcessSankeyValidatorNode, ProcessSankeyEdge as ProcessSankeyValidatorEdge, ProcessSankeyIssue, } from "./network/processSankey/algorithm";
 export { TreeDiagram } from "./network/TreeDiagram";
 export type { TreeDiagramProps } from "./network/TreeDiagram";
 export { Treemap } from "./network/Treemap";

package/dist/components/charts/network/OrbitDiagram.d.ts

@@ -4,7 +4,7 @@ import type { StreamNetworkFrameProps } from "../../stream/networkTypes";
 import type { BaseChartProps } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 export interface OrbitNode {
-    datum: any;
+    datum: Datum;
     x: number;
     y: number;
     ring: number;
@@ -38,11 +38,11 @@ export interface OrbitDiagramProps<TDatum extends Datum = Datum> extends BaseCha
      */
     orbitMode?: OrbitMode;
     /** Ring size divisor per depth. Larger = tighter orbits. @default 2.95 */
-    orbitSize?: number | ((node: any) => number);
+    orbitSize?: number | ((node: Datum) => number);
     /** Orbit speed in degrees per frame @default 0.25 */
     speed?: number;
     /** Per-node speed modifier @default (node) => 1 / (node.depth + 1) */
-    revolution?: (node: any) => number;
+    revolution?: (node: Datum) => number;
     /**
      * Built-in revolution style presets:
      * - "locked": children rotate with parent at decreasing speed (default)
@@ -53,11 +53,11 @@ export interface OrbitDiagramProps<TDatum extends Datum = Datum> extends BaseCha
      */
     revolutionStyle?: "locked" | "decay" | "alternate";
     /** Vertical squash for elliptical orbits. 1 = circle, 0.5 = ellipse @default 1 */
-    eccentricity?: number | ((node: any) => number);
+    eccentricity?: number | ((node: Datum) => number);
     /** Show orbital ring paths @default true */
     showRings?: boolean;
     /** Node radius. Number or function of node. @default 6 */
-    nodeRadius?: number | ((node: any) => number);
+    nodeRadius?: number | ((node: Datum) => number);
     /** Show node labels @default false */
     showLabels?: boolean;
     /** Enable animation @default true */

package/dist/components/charts/network/ProcessSankey.d.ts

@@ -0,0 +1,141 @@
+import * as React from "react";
+import type { Datum } from "../shared/datumTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import type { RealtimeFrameHandle } from "../../realtime/types";
+import type { StreamNetworkFrameProps, ParticleStyle } from "../../stream/networkTypes";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+type TimeLike = number | Date | string;
+export interface ProcessSankeyTick {
+    date: TimeLike;
+    label: string;
+}
+export interface ProcessSankeyProps<TNode extends Datum = Datum, TEdge extends Datum = Datum> extends BaseChartProps {
+    nodes?: TNode[];
+    edges?: TEdge[];
+    /** [tStart, tEnd] of the chart's x-axis. Required. */
+    domain: [TimeLike, TimeLike];
+    /** Optional axis ticks. Each tick: { date, label }. */
+    axisTicks?: ProcessSankeyTick[];
+    nodeIdAccessor?: ChartAccessor<TNode, string>;
+    sourceAccessor?: ChartAccessor<TEdge, string>;
+    targetAccessor?: ChartAccessor<TEdge, string>;
+    valueAccessor?: ChartAccessor<TEdge, number>;
+    startTimeAccessor?: ChartAccessor<TEdge, TimeLike>;
+    endTimeAccessor?: ChartAccessor<TEdge, TimeLike>;
+    /**
+     * Accessor for a node's explicit lifetime extent — a `[start, end]`
+     * tuple of time-likes. Lane spans
+     * `min(xExtent[0], earliestEdge)` to `max(xExtent[1], latestEdge)`.
+     */
+    xExtentAccessor?: ChartAccessor<TNode, [TimeLike, TimeLike]>;
+    edgeIdAccessor?: ChartAccessor<TEdge, string>;
+    colorBy?: ChartAccessor<TNode, string>;
+    colorScheme?: string | string[];
+    /** Show a swatch + label legend. Defaults to `true` when `colorBy` is set. */
+    showLegend?: boolean;
+    /** Legend position. Default `"right"`. */
+    legendPosition?: "right" | "left" | "top" | "bottom";
+    /**
+     * Format function for time values — applied to axis tick labels and
+     * to time fields in the default tooltip. Same convention as
+     * `xFormat` on XY charts.
+     */
+    timeFormat?: (d: number | Date) => string | React.ReactNode;
+    /** Format function for the `value` field. Mirrors `yFormat` on XY charts. */
+    valueFormat?: (d: number) => string | React.ReactNode;
+    pairing?: "value" | "temporal";
+    packing?: "off" | "reuse";
+    laneOrder?: "insertion" | "crossing-min" | "inside-out" | "crossing-min+inside-out";
+    ribbonLane?: "source" | "target" | "both";
+    lifetimeMode?: "full" | "half";
+    showLaneRails?: boolean;
+    showQualityReadout?: boolean;
+    edgeOpacity?: number;
+    /** Tooltip content. `false` disables, `true` uses the default,
+     *  or pass a `Tooltip(...)` / custom function for full control. */
+    tooltip?: TooltipProp;
+    enableHover?: boolean;
+    onClick?: (datum: Datum, position?: {
+        x: number;
+        y: number;
+    }) => void;
+    showParticles?: boolean;
+    /** Style config for the particle overlay — same shape
+     *  StreamNetworkFrame consumes from SankeyDiagram. Defaults
+     *  (radius 3, opacity 0.7, spawnRate 0.1, maxPerEdge 50) live in
+     *  `DEFAULT_PARTICLE_STYLE`. */
+    particleStyle?: ParticleStyle;
+    /** Pass-through to the underlying StreamNetworkFrame. */
+    frameProps?: Partial<Omit<StreamNetworkFrameProps, "nodes" | "edges" | "chartType" | "size" | "customNetworkLayout" | "layoutConfig">>;
+}
+/**
+ * ProcessSankey — temporal flow between nodes with an actual time x-axis.
+ *
+ * Built on top of `StreamNetworkFrame` via the `customNetworkLayout`
+ * escape hatch. Bands and ribbons emit as `bezier` scene-edges; the
+ * Frame handles canvas painting, hit testing, accessibility, theme
+ * cascade, and the push API.
+ *
+ * **Differs from SankeyDiagram in three ways:**
+ *
+ * 1. **Edges carry time.** Each edge has `startTime` / `endTime`.
+ * 2. **Nodes have lifetimes, not ranks.** A node's vertical lane spans
+ *    `min(xExtent[0], earliestEdge)` to `max(xExtent[1], latestEdge)`.
+ * 3. **Static-graph cycles are valid** as long as edges move forward in time.
+ *
+ * @example
+ * ```tsx
+ * // Static fixture: pre-built nodes + timed edges, categorical colors.
+ * <ProcessSankey
+ *   nodes={[
+ *     { id: "Alice", category: "Person", xExtent: ["2026-01-06", "2026-01-06"] },
+ *     { id: "Bob",   category: "Person", xExtent: ["2026-02-01", "2026-02-01"] },
+ *     { id: "Eng",     category: "Team" },
+ *     { id: "Release", category: "Milestone", xExtent: ["2026-04-15", "2026-05-30"] },
+ *   ]}
+ *   edges={[
+ *     { id: "alice-eng", source: "Alice", target: "Eng",     value: 8,
+ *       startTime: "2026-01-20", endTime: "2026-02-10" },
+ *     { id: "bob-eng",   source: "Bob",   target: "Eng",     value: 5,
+ *       startTime: "2026-02-15", endTime: "2026-03-15" },
+ *     { id: "eng-rel",   source: "Eng",   target: "Release", value: 13,
+ *       startTime: "2026-04-15", endTime: "2026-05-15" },
+ *   ]}
+ *   domain={["2026-01-01", "2026-05-31"]}
+ *   colorBy="category"
+ *   showLegend
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Push mode: omit `edges`, mutate via the ref. Same chart shape, but
+ * // edges arrive over time. Particles depict throughput.
+ * const ref = useRef<RealtimeFrameHandle>(null)
+ *
+ * useEffect(() => {
+ *   const id = setInterval(() => {
+ *     ref.current?.push({
+ *       source: "API", target: "DB", value: Math.random() * 10,
+ *       startTime: Date.now(), endTime: Date.now() + 1500,
+ *     })
+ *   }, 800)
+ *   return () => clearInterval(id)
+ * }, [])
+ *
+ * return (
+ *   <ProcessSankey
+ *     ref={ref}
+ *     domain={[t0, t0 + 60_000]}
+ *     showParticles
+ *     colorBy="category"
+ *     showLegend
+ *   />
+ * )
+ * ```
+ */
+export declare const ProcessSankey: {
+    <TNode extends Datum = Datum, TEdge extends Datum = Datum>(props: ProcessSankeyProps<TNode, TEdge> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};
+export default ProcessSankey;

package/dist/components/charts/network/processSankey/algorithm.d.ts

@@ -0,0 +1,136 @@
+export interface ProcessSankeyNode {
+    id: string;
+    /** Optional explicit lifetime bound [start, end]. Lifetime is
+     *  `min(xExtent[0], earliestEdge)` to `max(xExtent[1], latestEdge)`. */
+    xExtent?: [number, number];
+}
+export interface ProcessSankeyEdge {
+    id: string;
+    source: string;
+    target: string;
+    value: number;
+    startTime: number;
+    endTime: number;
+}
+export interface ProcessSankeyIssue {
+    kind: string;
+    id?: string;
+    source?: string;
+    target?: string;
+    endpoint?: string;
+    nodeId?: string;
+}
+export interface ProcessSankeySample {
+    t: number;
+    topMass: number;
+    botMass: number;
+}
+export type AttachmentSide = "top" | "bot";
+export type AttachmentKind = "in" | "out";
+export interface ProcessSankeyAttachment {
+    side: AttachmentSide;
+    time: number;
+    sideMassBefore: number;
+    sideMassAfter: number;
+    kind: AttachmentKind;
+    value: number;
+}
+export interface ProcessSankeyNodeData {
+    samples: ProcessSankeySample[];
+    peak: number;
+    topPeak: number;
+    botPeak: number;
+    localAttachments: Map<string, ProcessSankeyAttachment>;
+}
+export interface ProcessSankeySlotPeak {
+    topPeak: number;
+    botPeak: number;
+}
+export interface ProcessSankeySlotOccupant {
+    id: string;
+    end: number;
+}
+export interface ProcessSankeySlot {
+    peak: ProcessSankeySlotPeak;
+    occupants: ProcessSankeySlotOccupant[];
+}
+export interface ProcessSankeyLaneLifetime {
+    start: number | null;
+    end: number | null;
+}
+export interface ProcessSankeySideRecord {
+    sourceSide?: AttachmentSide;
+    targetSide?: AttachmentSide;
+}
+export interface ProcessSankeyLayout {
+    nodeData: Record<string, ProcessSankeyNodeData>;
+    sides: Map<string, ProcessSankeySideRecord>;
+    valueScale: number;
+    padding: number;
+    compressedPadding: boolean;
+    centerlines: Record<string, number>;
+    laneLifetime: Record<string, ProcessSankeyLaneLifetime>;
+    slots: ProcessSankeySlot[];
+    slotByNode: Record<string, number>;
+    crossingsBefore: number | null;
+    crossingsAfter: number | null;
+    lengthBefore: number | null;
+    lengthAfter: number | null;
+}
+export interface ProcessSankeyOptions {
+    plotH: number;
+    pairing?: "value" | "temporal";
+    packing?: "off" | "reuse";
+    laneOrder?: "insertion" | "crossing-min" | "inside-out" | "crossing-min+inside-out";
+    lifetimeMode?: "full" | "half";
+}
+export interface ProcessSankeyEdgeIndex {
+    incoming: Record<string, ProcessSankeyEdge[]>;
+    outgoing: Record<string, ProcessSankeyEdge[]>;
+}
+type Domain = [number, number] | null | undefined;
+export declare function validateProcessSankey(nodes: ProcessSankeyNode[], edges: ProcessSankeyEdge[], domain: [number, number]): ProcessSankeyIssue[];
+export declare function formatProcessSankeyIssue(issue: ProcessSankeyIssue): string;
+export declare function buildEdgeIndex(nodes: ProcessSankeyNode[], edges: ProcessSankeyEdge[]): ProcessSankeyEdgeIndex;
+export declare function assignSides(nodes: ProcessSankeyNode[], edges: ProcessSankeyEdge[], edgeIndex: ProcessSankeyEdgeIndex, pairing?: "value" | "temporal"): Map<string, ProcessSankeySideRecord>;
+export declare function computeNode(node: ProcessSankeyNode, edgeIndex: ProcessSankeyEdgeIndex, sides: Map<string, ProcessSankeySideRecord>): ProcessSankeyNodeData;
+export declare function clampTime(t: number, domain: Domain): number;
+export declare function clampSamples(samples: ProcessSankeySample[], domain: Domain): ProcessSankeySample[];
+export declare function attachmentYRange(att: ProcessSankeyAttachment, cl: number, S: number): [number, number];
+export declare function buildBandPath(samples: ProcessSankeySample[], cl: number, S: number, xScale: (t: number) => number, domain: Domain): string | null;
+type SlotByNode = Record<string, number>;
+export declare function countCrossings(slotByNode: SlotByNode, edges: ProcessSankeyEdge[]): number;
+export declare function totalEdgeLength(slotByNode: SlotByNode, edges: ProcessSankeyEdge[]): number;
+interface LaneLayoutOptions {
+    plotH: number;
+    padding: number;
+    valueScale: number;
+    packing?: "off" | "reuse";
+    laneOrder?: "insertion" | "crossing-min" | "inside-out" | "crossing-min+inside-out";
+    lifetimeMode?: "full" | "half";
+}
+interface LaneLayoutResult {
+    effectiveSlotsHeight: number;
+    centerlines: Record<string, number>;
+    laneLifetime: Record<string, ProcessSankeyLaneLifetime>;
+    slots: ProcessSankeySlot[];
+    slotByNode: SlotByNode;
+    slotCenter: number[];
+    crossingsBefore: number | null;
+    crossingsAfter: number | null;
+    lengthBefore: number | null;
+    lengthAfter: number | null;
+}
+export declare function computeLaneLayout(nodes: ProcessSankeyNode[], edges: ProcessSankeyEdge[], nodeData: Record<string, ProcessSankeyNodeData>, edgeIndex: ProcessSankeyEdgeIndex, opts: LaneLayoutOptions): LaneLayoutResult;
+/**
+ * Compute the full Process Sankey layout for a given dataset and
+ * configuration. Pure function, no side effects.
+ *
+ * The chart's time domain isn't a layout opt — domain handling lives
+ * in the geometry helpers (`buildBandPath`, `buildRibbonGeometry`,
+ * `clampSamples`) which receive an `xScale` and a domain pair from
+ * the caller. The layout itself is timeless apart from the per-node
+ * sample/event timestamps.
+ */
+export declare function computeProcessSankeyLayout(nodes: ProcessSankeyNode[], edges: ProcessSankeyEdge[], opts: ProcessSankeyOptions): ProcessSankeyLayout;
+export {};

package/dist/components/charts/network/processSankey/buildScenes.d.ts

@@ -0,0 +1,45 @@
+import { scaleTime } from "d3-scale";
+import { type ProcessSankeyOptions, type ProcessSankeyLayout, type ProcessSankeyIssue } from "./algorithm";
+import type { ProcessSankeyLayoutConfig } from "./streamingLayout";
+import type { Datum } from "../../shared/datumTypes";
+export interface ProcessSankeyNormalizedNode {
+    id: string;
+    xExtent?: [number, number];
+    __raw?: Datum;
+}
+export interface ProcessSankeyNormalizedEdge {
+    id: string;
+    source: string;
+    target: string;
+    value: number;
+    startTime: number;
+    endTime: number;
+    __raw?: Datum;
+}
+export interface BuildScenesInput {
+    nodes: ProcessSankeyNormalizedNode[];
+    edges: ProcessSankeyNormalizedEdge[];
+    domain: [number, number];
+    plotW: number;
+    plotH: number;
+    ribbonLane: "source" | "target" | "both";
+    edgeOpacity: number;
+    /** Resolves a node's color by id+index (lets the caller plug in
+     *  the same theme/colorScheme/colorBy resolution the HOC uses). */
+    colorOf: (id: string, idx: number) => string;
+    layoutOpts: Pick<ProcessSankeyOptions, "pairing" | "packing" | "laneOrder" | "lifetimeMode">;
+}
+export interface BuildScenesResult {
+    layout: ProcessSankeyLayout | null;
+    layoutConfig: ProcessSankeyLayoutConfig;
+    issues: ProcessSankeyIssue[];
+    /** Used downstream for tooltips (mass-history) and overlays. */
+    xScale: ReturnType<typeof scaleTime>;
+}
+/**
+ * Run the full ProcessSankey layout pipeline. Returns the algorithm
+ * output, the bands/ribbons specs ready for `customNetworkLayout`, and
+ * the validation issues (caller decides whether to render an error
+ * gate or fall through). Pure: no DOM, no React, no rAF.
+ */
+export declare function buildProcessSankeyScenes(input: BuildScenesInput): BuildScenesResult;

package/dist/components/charts/network/processSankey/ribbonInputs.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Compute the `RibbonGeometryInput` shape for a ProcessSankey ribbon
+ * from its source/target attachment data. Both the HOC (CSR) and the
+ * pure scene builder (SSR) call this so the coords feeding into the
+ * shared `buildRibbonGeometry` helper match between the two paths.
+ *
+ * Replaces `algorithm.js`'s `buildRibbonPath` — the path-D formula
+ * itself moved into `buildRibbonGeometry` so SankeyDiagram and
+ * ProcessSankey emit identical M-C-L-C-Z shapes.
+ */
+import type { RibbonGeometryInput } from "../../../geometry/ribbonGeometry";
+type Side = "top" | "bot";
+type Kind = "in" | "out";
+interface AttachmentLike {
+    side: Side;
+    time: number;
+    sideMassBefore: number;
+    sideMassAfter: number;
+    kind: Kind;
+    value: number;
+}
+type RibbonLane = "source" | "target" | "both";
+type XScale = (t: number) => number;
+/**
+ * Build the geometry inputs for a single ProcessSankey ribbon. The
+ * source attachment is assumed to be `kind: "out"` (the value leaves
+ * the source on its outgoing side); the target attachment is
+ * `kind: "in"`. attachmentYRange's formula is inlined here to keep
+ * this module pure TS (the `algorithm.js` version is JS-only).
+ */
+export declare function computeProcessSankeyRibbonInputs(srcAtt: AttachmentLike, srcCenterline: number, tgtAtt: AttachmentLike, tgtCenterline: number, valueScale: number, xScale: XScale, lane: RibbonLane, domain: [number, number] | null): RibbonGeometryInput;
+export {};

package/dist/components/charts/network/processSankey/streamingLayout.d.ts

@@ -0,0 +1,58 @@
+import type { NetworkCustomLayout } from "../../../stream/networkCustomLayout";
+import type { BezierCache } from "../../../stream/networkTypes";
+import type { Datum } from "../../shared/datumTypes";
+export interface ProcessSankeyBandSpec {
+    id: string;
+    pathD: string;
+    fill: string;
+    stroke?: string;
+    strokeWidth?: number;
+    /** The user's raw node datum, surfaced as `data` in HoverData. */
+    rawDatum: Datum;
+    /** Pre-computed label x/y for the node band. */
+    labelX: number;
+    labelY: number;
+    labelText: string;
+}
+export interface ProcessSankeyRibbonSpec {
+    id: string;
+    pathD: string;
+    fill: string;
+    opacity: number;
+    /** The user's raw edge datum, surfaced as `data` in HoverData. */
+    rawDatum: Datum;
+    /**
+     * Pre-computed cubic bezier control points + halfWidth for the
+     * shared particle pipeline. ProcessSankey writes these alongside
+     * the ribbon's path-D string so the frame's particle pool can
+     * spawn / step / render against them without re-deriving the
+     * ribbon geometry. Optional — when omitted the ribbon paints
+     * normally but no particles flow along it.
+     */
+    bezier?: BezierCache;
+}
+export interface ProcessSankeyLayoutConfig {
+    bands: ProcessSankeyBandSpec[];
+    ribbons: ProcessSankeyRibbonSpec[];
+    /** Optional dim opacity for unselected bands/ribbons (linkedHover). */
+    showLabels?: boolean;
+}
+/**
+ * Marker attached to scene-edge datums so the HOC's `tooltipContent`
+ * can route node bands vs. flow ribbons through different default
+ * bodies. `data` still carries the user's original node/edge datum.
+ */
+export interface SceneDatumPayload {
+    __kind: "band" | "ribbon";
+    /** Original node/edge record, as the user pushed it. */
+    data: Datum;
+    /** Stable id for hit-deduplication and ref operations. */
+    id: string;
+}
+export declare const emitProcessSankeyScenes: NetworkCustomLayout<ProcessSankeyLayoutConfig>;
+/**
+ * Test whether an arbitrary HoverData/datum-shaped value carries the
+ * ProcessSankey scene marker. Lets the HOC's tooltipContent narrow to
+ * the band/ribbon variants without leaking the marker key everywhere.
+ */
+export declare function isProcessSankeyScenePayload(d: unknown): d is SceneDatumPayload;

package/dist/components/charts/network/processSankey/tooltipUtils.d.ts

@@ -0,0 +1,41 @@
+import type { ProcessSankeyNodeData } from "./algorithm";
+export interface MassHistoryRow {
+    t: number;
+    total: number;
+}
+export interface MassHistoryRowMarked extends MassHistoryRow {
+    /** "min" | "q25" | "median" | "q75" | "max" — present only when the
+     *  full series was condensed via `pickMassQuantiles`. */
+    mark?: string;
+}
+/**
+ * Distinct (time, total-mass) tuples drawn from a node's sample series.
+ * The same `(t, total)` pair never appears twice — the layout's
+ * same-time pre/post sample collapse is preserved here. Returns an
+ * empty array when `data` has no samples (or is undefined).
+ */
+export declare function massHistoryRows(data: ProcessSankeyNodeData | undefined): MassHistoryRow[];
+/** Number of quantile picks emitted on truncation. Fixed at five —
+ *  `min`, `q25`, `median`, `q75`, `max` — because the picks are
+ *  semantic (named labels), not cap-driven. The `truncateAt` parameter
+ *  on `pickMassQuantiles` controls *when* to truncate, not how many to
+ *  return. */
+export declare const QUANTILE_PICK_COUNT = 5;
+/**
+ * Condense a row series down to the five mass-quantile picks —
+ * `min`, `q25`, `median`, `q75`, `max` — re-sorted by time so the
+ * tooltip table reads chronologically. Returns the input unchanged
+ * when its length is at or below `truncateAt` (default 5).
+ *
+ * Same-time collisions are deduplicated, so very small or very flat
+ * series may yield fewer than five output rows even when truncation
+ * fires; the marks attached are the first ones encountered for each
+ * surviving timestamp, which keeps `min` and `max` stable when ties
+ * are present.
+ *
+ * Note: `truncateAt` is the *trigger threshold*, not the output cap —
+ * once truncation fires, the output always emits the five quantile
+ * picks. To raise/lower the threshold without changing the picks,
+ * pass a different `truncateAt`; to vary the picks, fork this util.
+ */
+export declare function pickMassQuantiles(rows: MassHistoryRow[], truncateAt?: number): MassHistoryRowMarked[];

package/dist/components/charts/ordinal/BarChart.d.ts

@@ -5,6 +5,7 @@ import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { RealtimeFrameHandle } from "../../realtime/types";
+import { type RegressionProp } from "../shared/regressionUtils";
 /**
  * BarChart component props
  */
@@ -90,6 +91,17 @@ export interface BarChartProps<TDatum extends Datum = Datum> extends BaseChartPr
     legendPosition?: "right" | "left" | "top" | "bottom";
     tooltip?: TooltipProp;
     annotations?: Datum[];
+    /**
+     * Overlay a regression line through the bar tops. Accepts `true`
+     * (linear), a method name (`"linear"` | `"polynomial"` | `"loess"`),
+     * or a full `RegressionConfig`. The regression treats categories
+     * as a numeric category-index for fit input; pixel positions are
+     * resolved through the band scale, so the line passes through bar
+     * centers. Best for ordered categories (months, quarters, score
+     * buckets) where a slope reads as a meaningful trend. Sugar over
+     * the `trend` annotation.
+     */
+    regression?: RegressionProp;
     /** Custom formatter for category tick labels */
     categoryFormat?: CategoryFormatFn;
     /** Fixed value-axis domain `[min, max]`. Either bound may be `undefined` to leave that side data-derived. */

package/dist/components/charts/ordinal/DotPlot.d.ts

@@ -5,6 +5,7 @@ import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { RealtimeFrameHandle } from "../../realtime/types";
+import { type RegressionProp } from "../shared/regressionUtils";
 export interface DotPlotProps<TDatum extends Datum = Datum> extends BaseChartProps {
     data?: TDatum[];
     categoryAccessor?: ChartAccessor<TDatum, string>;
@@ -34,6 +35,14 @@ export interface DotPlotProps<TDatum extends Datum = Datum> extends BaseChartPro
     legendPosition?: LegendPosition;
     tooltip?: TooltipProp;
     annotations?: Datum[];
+    /**
+     * Overlay a regression line through the dots. Same shape as
+     * Scatterplot's regression prop — accepts boolean, method-string,
+     * or full `RegressionConfig`. Pixel positions resolve through the
+     * band scale, so the line passes through dot centers. Sugar over
+     * the `trend` annotation.
+     */
+    regression?: RegressionProp;
     /** Custom formatter for category tick labels */
     categoryFormat?: CategoryFormatFn;
     /** Fixed value-axis domain `[min, max]`. Either bound may be `undefined` to leave that side data-derived. */