semiotic 3.4.0 → 3.4.2

package/dist/components/stream/pipelineTransitions.d.ts

@@ -12,6 +12,7 @@
  */
 import type { SceneNode, TransitionConfig } from "./types";
 import type { ActiveTransition } from "./pipelineTransitionUtils";
+import type { Datum } from "../charts/shared/datumTypes";
 export type PrevPosition = {
     x: number;
     y: number;
@@ -19,6 +20,10 @@ export type PrevPosition = {
     h?: number;
     r?: number;
     opacity?: number;
+    openY?: number;
+    closeY?: number;
+    highY?: number;
+    lowY?: number;
 };
 export type PrevPath = {
     topPath?: [number, number][];
@@ -29,12 +34,19 @@ export type PrevPath = {
 /** Context needed from PipelineStore for identity resolution */
 export interface TransitionContext {
     runtimeMode?: "streaming" | "bounded";
-    getX: (d: any) => number;
-    getY: (d: any) => number;
-    getCategory?: (d: any) => string;
+    getX: (d: Datum) => number;
+    getY: (d: Datum) => number;
+    getCategory?: (d: Datum) => string;
 }
 /**
  * Get a stable identity key for a scene node.
+ *
+ * Exit stubs (created during startTransition for scrolled-off nodes) have
+ * `datum: null` and carry their original identity on `_transitionKey`. If a
+ * new transition starts while exits are still in the scene, resolving their
+ * identity via the datum-less fallback (e.g. `c:${index}`) would reshuffle
+ * which exit matches which key on the next snapshot. Preferring the stored
+ * `_transitionKey` keeps exits stable across overlapping transitions.
  */
 export declare function getNodeIdentity(ctx: TransitionContext, node: SceneNode, index: number): string | null;
 /**
@@ -56,4 +68,4 @@ export declare function startTransition(ctx: TransitionContext, transition: Tran
  * Advance the transition animation. Returns true if still animating.
  * Mutates scene nodes in place.
  */
-export declare function advanceTransition(now: number, transition: TransitionConfig, state: TransitionState, prevPositionMap: Map<string, PrevPosition>, prevPathMap: Map<string, PrevPath>): boolean;
+export declare function advanceTransition(now: number, transition: TransitionConfig, state: TransitionState, prevPositionMap: Map<string, PrevPosition>, _prevPathMap: Map<string, PrevPath>): boolean;

package/dist/components/stream/renderers/colorUtils.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Color utilities shared across canvas renderers.
+ *
+ * Kept here (not in layouts/hierarchyUtils or a deeper shared module) so
+ * renderers don't reach into unrelated layers for primitive helpers.
+ */
+/**
+ * Resolve any valid CSS color string to an [r, g, b] tuple.
+ *
+ * Uses the canvas's own fillStyle round-trip to normalize first: assigning a
+ * CSS color to `ctx.fillStyle` and reading it back always yields `#rrggbb`
+ * or `rgba(r, g, b, a)`. That means named colors (`red`, `steelblue`), hsl(),
+ * and any other valid CSS form work the same as hex and rgb. Without the
+ * normalization pass a bare regex parser silently falls back on anything it
+ * doesn't match — gradients from named colors would render gray.
+ *
+ * The prior fillStyle is restored so this is callable from the middle of a
+ * draw without disturbing in-progress paint state.
+ */
+export declare function parseCanvasColor(ctx: CanvasRenderingContext2D, color: string): [number, number, number];

package/dist/components/stream/types.d.ts

@@ -1,7 +1,26 @@
 import type { ReactNode } from "react";
 import type { ScaleLinear } from "d3-scale";
 import type { AnimateProp } from "./pipelineTransitionUtils";
+import type { LegendGroup, GradientLegendConfig } from "../types/legendTypes";
 import type { ArrowOfTime, WindowMode, LineStyle, BarStyle, WaterfallStyle, SwarmStyle, HoverAnnotationConfig, HoverData, AnnotationContext, AnnotationAnchorMode } from "../realtime/types";
+import type { Datum } from "../charts/shared/datumTypes";
+export type SceneDatum = Datum | null;
+export type SeriesDatum = Datum[] | null;
+export type AxisTickFormat = ((d: number, index?: number, allTicks?: number[]) => string) | ((d: string, index?: number, allTicks?: number[]) => string) | ((d: Date, index?: number, allTicks?: number[]) => string);
+export interface ThemeSemanticColors {
+    primary?: string;
+    secondary?: string;
+    success?: string;
+    danger?: string;
+    warning?: string;
+    error?: string;
+    info?: string;
+    text?: string;
+    textSecondary?: string;
+    border?: string;
+    grid?: string;
+    surface?: string;
+}
 export interface DecayConfig {
     type: "linear" | "exponential" | "step";
     /** Exponential: half-life in buffer positions (default: bufferSize/2) */
@@ -85,7 +104,7 @@ export interface LineSceneNode {
     /** Threshold-based color segments */
     colorThresholds?: LineColorThreshold[];
     style: Style;
-    datum: any;
+    datum: SeriesDatum;
     group?: string;
     /** Horizontal gradient for the line stroke */
     strokeGradient?: {
@@ -116,7 +135,7 @@ export interface AreaSceneNode {
     topPath: [number, number][];
     bottomPath: [number, number][];
     style: Style;
-    datum: any;
+    datum: SeriesDatum;
     group?: string;
     /** Gradient fill: opacity-based (topOpacity/bottomOpacity) or multi-color (colorStops) */
     fillGradient?: {
@@ -168,7 +187,7 @@ export interface PointSceneNode {
     y: number;
     r: number;
     style: Style;
-    datum: any;
+    datum: SceneDatum;
     /** Optional unique identifier for point-anchored annotations */
     pointId?: string;
     /** Pulse glow intensity 0–1 (set by PipelineStore when pulse is active) */
@@ -194,10 +213,25 @@ export interface RectSceneNode {
     h: number;
     /** Rounded corner radius on the end away from the baseline */
     roundedTop?: number;
-    /** Which edge to round: "top"/"bottom" (vertical), "right"/"left" (horizontal) */
+    /** Which edge is the "tip" (opposite the baseline): "top"/"bottom" for
+     *  vertical orientation, "right"/"left" for horizontal. Used by the
+     *  renderer for rounded-corner placement AND gradient direction. Set by
+     *  bar scene builders unconditionally so gradients resolve without
+     *  requiring roundedTop. */
     roundedEdge?: "top" | "bottom" | "right" | "left";
+    /** Gradient fill — same shape as the area-scene version. Runs tip → base
+     *  along the bar axis (inferred from `roundedEdge`). */
+    fillGradient?: {
+        topOpacity: number;
+        bottomOpacity: number;
+    } | {
+        colorStops: Array<{
+            offset: number;
+            color: string;
+        }>;
+    };
     style: Style;
-    datum: any;
+    datum: SceneDatum;
     group?: string;
     _pulseIntensity?: number;
     _pulseColor?: string;
@@ -219,7 +253,7 @@ export interface HeatcellSceneNode {
     w: number;
     h: number;
     fill: string;
-    datum: any;
+    datum: SceneDatum;
     /** Optional style object (used for decay/transition opacity on heatmap cells) */
     style?: Style;
     /** Numeric cell value (for canvas text rendering when showValues is enabled) */
@@ -256,7 +290,7 @@ export interface CandlestickSceneNode {
     isUp: boolean;
     /** Range/dumbbell mode — no body, endpoint dots instead */
     isRange?: boolean;
-    datum: any;
+    datum: SceneDatum;
     /** Optional style object (used during transition opacity animations) */
     style?: Style;
     _pulseIntensity?: number;
@@ -268,6 +302,13 @@ export interface CandlestickSceneNode {
     _decayOpacity?: number;
     /** Stable identity key for transition tracking */
     _transitionKey?: string;
+    /** Geometry targets — set during a transition so advanceTransition can lerp
+     *  toward them from the snapshotted prev position. Cleared on completion. */
+    _targetX?: number;
+    _targetOpenY?: number;
+    _targetCloseY?: number;
+    _targetHighY?: number;
+    _targetLowY?: number;
 }
 export interface CandlestickStyle {
     upColor?: string;
@@ -278,7 +319,7 @@ export interface CandlestickStyle {
     /** Single color for range/dumbbell mode (replaces up/down when no open/close provided) */
     rangeColor?: string;
 }
-export interface Changeset<T = Record<string, any>> {
+export interface Changeset<T = Datum> {
     inserts: T[];
     bounded: boolean;
     /** Hint: total dataset size when progressively chunking bounded data */
@@ -307,7 +348,7 @@ export interface StreamLayout {
     height: number;
 }
 export type CurveType = "linear" | "monotoneX" | "monotoneY" | "step" | "stepAfter" | "stepBefore" | "basis" | "cardinal" | "catmullRom" | "natural";
-export interface StreamXYFrameProps<T = Record<string, any>> {
+export interface StreamXYFrameProps<T = Datum> {
     chartType: StreamChartType;
     runtimeMode?: RuntimeMode;
     data?: T[];
@@ -409,7 +450,7 @@ export interface StreamXYFrameProps<T = Record<string, any>> {
         orient: "left" | "right" | "top" | "bottom";
         label?: string;
         ticks?: number;
-        tickFormat?: (d: any, index?: number, allTicks?: number[]) => string;
+        tickFormat?: AxisTickFormat;
         baseline?: boolean | "under";
         jaggedBase?: boolean;
     }>;
@@ -417,8 +458,8 @@ export interface StreamXYFrameProps<T = Record<string, any>> {
     yLabel?: string;
     /** Label for the right Y axis (dual-axis charts) */
     yLabelRight?: string;
-    xFormat?: (d: any, index?: number, allTicks?: number[]) => string | ReactNode;
-    yFormat?: (d: any) => string | ReactNode;
+    xFormat?: (d: number | Date | string, index?: number, allTicks?: number[]) => string | ReactNode;
+    yFormat?: (d: number | Date | string) => string | ReactNode;
     tickFormatTime?: (value: number) => string;
     tickFormatValue?: (value: number) => string;
     hoverAnnotation?: boolean | HoverAnnotationConfig;
@@ -448,13 +489,13 @@ export interface StreamXYFrameProps<T = Record<string, any>> {
     } | null) => void;
     /** Accessor for unique point IDs used by point-anchored annotations */
     pointIdAccessor?: string | ((d: T) => string);
-    annotations?: Record<string, any>[];
-    svgAnnotationRules?: (annotation: Record<string, any>, index: number, context: AnnotationContext) => ReactNode;
+    annotations?: Datum[];
+    svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     showGrid?: boolean;
     legend?: ReactNode | {
-        legendGroups: any[];
+        legendGroups: LegendGroup[];
     } | {
-        gradient: import("../types/legendTypes").GradientLegendConfig;
+        gradient: GradientLegendConfig;
     };
     legendHoverBehavior?: (item: {
         label: string;
@@ -510,7 +551,7 @@ export interface StreamXYFrameProps<T = Record<string, any>> {
     /** Source chart ID — crosshair is suppressed on the source chart to avoid double rendering */
     linkedCrosshairSourceId?: string;
 }
-export interface StreamXYFrameHandle<T = Record<string, any>> {
+export interface StreamXYFrameHandle<T = Datum> {
     push(datum: T): void;
     pushMany(data: T[]): void;
     /** Remove data points by ID. Requires pointIdAccessor. */

package/dist/components/stream/xySceneBuilders/areaScene.d.ts

@@ -1,3 +1,4 @@
+import type { Datum } from "../../charts/shared/datumTypes";
 /**
  * Area and stacked area scene builders.
  *
@@ -9,5 +10,5 @@
  */
 import type { SceneNode } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildAreaScene(ctx: XYSceneContext, data: Record<string, any>[]): SceneNode[];
-export declare function buildStackedAreaScene(ctx: XYSceneContext, data: Record<string, any>[]): SceneNode[];
+export declare function buildAreaScene(ctx: XYSceneContext, data: Datum[]): SceneNode[];
+export declare function buildStackedAreaScene(ctx: XYSceneContext, data: Datum[]): SceneNode[];

package/dist/components/stream/xySceneBuilders/barScene.d.ts

@@ -1,3 +1,4 @@
+import type { Datum } from "../../charts/shared/datumTypes";
 /**
  * Realtime histogram bar scene builder.
  *
@@ -15,4 +16,4 @@ export interface BarSceneResult {
     /** Sorted bin boundary values (edges of all bins) for data-driven brush snapping */
     binBoundaries: number[];
 }
-export declare function buildBarScene(ctx: XYSceneContext, data: Record<string, any>[]): BarSceneResult;
+export declare function buildBarScene(ctx: XYSceneContext, data: Datum[]): BarSceneResult;

package/dist/components/stream/xySceneBuilders/boundsScene.d.ts

@@ -1,3 +1,4 @@
+import type { Datum } from "../../charts/shared/datumTypes";
 /**
  * Bounds scene builder — produces an AreaSceneNode for confidence bands/envelopes.
  *
@@ -5,4 +6,4 @@
  */
 import type { AreaSceneNode } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildBoundsForGroup(ctx: XYSceneContext, data: Record<string, any>[], group: string): AreaSceneNode | null;
+export declare function buildBoundsForGroup(ctx: XYSceneContext, data: Datum[], group: string): AreaSceneNode | null;

package/dist/components/stream/xySceneBuilders/candlestickScene.d.ts

@@ -1,3 +1,4 @@
+import type { Datum } from "../../charts/shared/datumTypes";
 /**
  * Candlestick (OHLC) scene builder.
  *
@@ -7,4 +8,4 @@
  */
 import type { SceneNode, StreamLayout } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildCandlestickScene(ctx: XYSceneContext, data: Record<string, any>[], layout: StreamLayout): SceneNode[];
+export declare function buildCandlestickScene(ctx: XYSceneContext, data: Datum[], _layout: StreamLayout): SceneNode[];

package/dist/components/stream/xySceneBuilders/emitPointNodes.d.ts

@@ -1,3 +1,4 @@
+import type { Datum } from "../../charts/shared/datumTypes";
 /**
  * Shared helper for emitting PointSceneNodes from grouped data.
  *
@@ -9,5 +10,5 @@ import type { SceneNode } from "../types";
 import type { XYSceneContext } from "./types";
 export declare function emitPointNodes(ctx: XYSceneContext, groups: {
     key: string;
-    data: Record<string, any>[];
-}[], nodes: SceneNode[], yGetOverride?: (d: Record<string, any>) => number): void;
+    data: Datum[];
+}[], nodes: SceneNode[], yGetOverride?: (d: Datum) => number): void;

package/dist/components/stream/xySceneBuilders/heatmapScene.d.ts

@@ -1,3 +1,4 @@
+import type { Datum } from "../../charts/shared/datumTypes";
 import type { SceneNode, StreamLayout } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildHeatmapScene(ctx: XYSceneContext, data: Record<string, any>[], layout: StreamLayout): SceneNode[];
+export declare function buildHeatmapScene(ctx: XYSceneContext, data: Datum[], layout: StreamLayout): SceneNode[];

package/dist/components/stream/xySceneBuilders/lineScene.d.ts

@@ -1,3 +1,4 @@
+import type { Datum } from "../../charts/shared/datumTypes";
 /**
  * Line scene builder — produces LineSceneNode[] from grouped data.
  *
@@ -9,4 +10,4 @@
  */
 import type { SceneNode } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildLineScene(ctx: XYSceneContext, data: Record<string, any>[]): SceneNode[];
+export declare function buildLineScene(ctx: XYSceneContext, data: Datum[]): SceneNode[];

package/dist/components/stream/xySceneBuilders/mixedScene.d.ts

@@ -1,3 +1,4 @@
+import type { Datum } from "../../charts/shared/datumTypes";
 /**
  * Mixed scene builder — renders some series as areas and others as lines.
  *
@@ -9,4 +10,4 @@
  */
 import type { SceneNode } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildMixedScene(ctx: XYSceneContext, data: Record<string, any>[]): SceneNode[];
+export declare function buildMixedScene(ctx: XYSceneContext, data: Datum[]): SceneNode[];

package/dist/components/stream/xySceneBuilders/pointScene.d.ts

@@ -1,3 +1,4 @@
+import type { Datum } from "../../charts/shared/datumTypes";
 /**
  * Point/scatter/bubble scene builder.
  *
@@ -9,4 +10,4 @@
  */
 import type { SceneNode } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildPointScene(ctx: XYSceneContext, data: Record<string, any>[]): SceneNode[];
+export declare function buildPointScene(ctx: XYSceneContext, data: Datum[]): SceneNode[];

package/dist/components/stream/xySceneBuilders/swarmScene.d.ts

@@ -1,3 +1,4 @@
+import type { Datum } from "../../charts/shared/datumTypes";
 /**
  * Realtime swarm chart scene builder.
  *
@@ -7,4 +8,4 @@
  */
 import type { SceneNode } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildSwarmScene(ctx: XYSceneContext, data: Record<string, any>[]): SceneNode[];
+export declare function buildSwarmScene(ctx: XYSceneContext, data: Datum[]): SceneNode[];

package/dist/components/stream/xySceneBuilders/types.d.ts

@@ -1,3 +1,4 @@
+import type { Datum } from "../../charts/shared/datumTypes";
 /**
  * XYSceneContext — shared context passed to all XY scene builder functions.
  *
@@ -5,33 +6,33 @@
  * Scene builders are pure functions that receive this context instead of
  * accessing PipelineStore instance fields directly.
  */
-import type { StreamScales, Style, CurveType } from "../types";
+import type { StreamScales, Style, CurveType, BarStyle, ThemeSemanticColors } from "../types";
 export interface XYSceneContext {
     scales: StreamScales;
     config: XYSceneConfig;
-    getX: (d: any) => number;
-    getY: (d: any) => number;
-    getY0?: (d: any) => number | null;
-    getSize?: (d: any) => number;
-    getColor?: (d: any) => string;
-    getGroup?: (d: any) => string;
-    getCategory?: (d: any) => string;
-    getPointId?: (d: any) => string;
-    getBounds?: (d: any) => number | null;
-    getOpen?: (d: any) => number;
-    getHigh?: (d: any) => number;
-    getLow?: (d: any) => number;
-    getClose?: (d: any) => number;
+    getX: (d: Datum) => number;
+    getY: (d: Datum) => number;
+    getY0?: (d: Datum) => number | null;
+    getSize?: (d: Datum) => number;
+    getColor?: (d: Datum) => string;
+    getGroup?: (d: Datum) => string;
+    getCategory?: (d: Datum) => string;
+    getPointId?: (d: Datum) => string;
+    getBounds?: (d: Datum) => number | null;
+    getOpen?: (d: Datum) => number;
+    getHigh?: (d: Datum) => number;
+    getLow?: (d: Datum) => number;
+    getClose?: (d: Datum) => number;
     /** Style resolvers — delegate to PipelineStore's cached color management */
-    resolveLineStyle: (group: string, sampleDatum?: Record<string, any>) => Style;
-    resolveAreaStyle: (group: string, sampleDatum?: Record<string, any>) => Style;
-    resolveBoundsStyle: (group: string, sampleDatum?: Record<string, any>) => Style;
-    resolveColorMap: (data: Record<string, any>[]) => Map<string, string>;
+    resolveLineStyle: (group: string, sampleDatum?: Datum) => Style;
+    resolveAreaStyle: (group: string, sampleDatum?: Datum) => Style;
+    resolveBoundsStyle: (group: string, sampleDatum?: Datum) => Style;
+    resolveColorMap: (data: Datum[]) => Map<string, string>;
     resolveGroupColor: (group: string) => string | null;
     /** Group data by lineBy/colorBy accessor */
-    groupData: (data: Record<string, any>[]) => {
+    groupData: (data: Datum[]) => {
         key: string;
-        data: Record<string, any>[];
+        data: Datum[];
     }[];
     /** Instance-scoped mutable cache for bar category ordering (prevents cross-instance leaks) */
     barCategoryCache?: {
@@ -61,14 +62,14 @@ export interface XYSceneConfig {
             color: string;
         }>;
     };
-    annotations?: Record<string, any>[];
-    pointStyle?: (d: any) => Style & {
+    annotations?: Datum[];
+    pointStyle?: (d: Datum) => Style & {
         r?: number;
     };
     sizeRange?: [number, number];
-    xAccessor?: string | ((d: any) => any);
-    yAccessor?: string | ((d: any) => any);
-    valueAccessor?: string | ((d: any) => any);
+    xAccessor?: string | ((d: Datum) => any);
+    yAccessor?: string | ((d: Datum) => any);
+    valueAccessor?: string | ((d: Datum) => any);
     heatmapAggregation?: "count" | "sum" | "mean";
     heatmapXBins?: number;
     heatmapYBins?: number;
@@ -76,6 +77,13 @@ export interface XYSceneConfig {
     heatmapValueFormat?: (v: number) => string;
     binSize?: number;
     barColors?: Record<string, string>;
+    /** Bar fill/stroke/strokeWidth/gap. Threaded through from RealtimeHistogram. */
+    barStyle?: BarStyle;
+    themeSemantic?: ThemeSemanticColors;
+    /** Theme sequential scheme name — fallback when colorScheme is not set (heatmap). */
+    themeSequential?: string;
+    /** Theme diverging scheme name — fallback when colorScheme is not set. */
+    themeDiverging?: string;
     swarmStyle?: {
         radius?: number;
         fill?: string;
@@ -89,6 +97,7 @@ export interface XYSceneConfig {
         gap?: number;
         stroke?: string;
         strokeWidth?: number;
+        opacity?: number;
         connectorStroke?: string;
         connectorWidth?: number;
     };
@@ -104,5 +113,5 @@ export interface XYSceneConfig {
     candlestickRangeMode?: boolean;
     boundsStyle?: Style | ((d: any, group: string) => Style);
     lineStyle?: Style | ((d: any, group: string) => Style);
-    areaStyle?: (d: any) => Style;
+    areaStyle?: (d: Datum) => Style;
 }

package/dist/components/stream/xySceneBuilders/waterfallScene.d.ts

@@ -7,6 +7,7 @@
  * Dependencies: SceneGraph (buildRectNode)
  * Consumed by: PipelineStore.buildSceneNodes (chartType "waterfall")
  */
+import type { Datum } from "../../charts/shared/datumTypes";
 import type { SceneNode, StreamLayout } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildWaterfallScene(ctx: XYSceneContext, data: Record<string, any>[], layout: StreamLayout): SceneNode[];
+export declare function buildWaterfallScene(ctx: XYSceneContext, data: Datum[], layout: StreamLayout): SceneNode[];

package/dist/components/types/marginType.d.ts

@@ -0,0 +1,15 @@
+/** Resolved chart margin in pixels — every side populated. This is the
+ *  internal shape after the frame merges the user-supplied margin with
+ *  chart-mode defaults, so downstream layout math can read all four fields
+ *  without null-checking. */
+export interface MarginType {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+}
+/** Public-API margin shape. Users can pass any subset of sides (`{ left: 120 }`
+ *  for wide y-axis labels is a common pattern) or a single number as shorthand
+ *  for "same on all sides". The frame fills missing sides from the chart-mode
+ *  defaults before handing a fully-resolved `MarginType` to the layout code. */
+export type PartialMargin = number | Partial<MarginType>;