semiotic 3.0.1 → 3.1.0

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

@@ -0,0 +1,42 @@
+/**
+ * Shared transition utilities for PipelineStores.
+ *
+ * Extracts common easing logic and types used by PipelineStore,
+ * OrdinalPipelineStore, NetworkPipelineStore, and GeoPipelineStore.
+ */
+/** Active transition state tracked by each PipelineStore */
+export interface ActiveTransition {
+    startTime: number;
+    duration: number;
+}
+/** Easing mode — determines interpolation curve */
+export type EasingMode = "linear" | "ease-out-cubic";
+/**
+ * Compute the eased interpolation parameter from raw progress.
+ *
+ * @param rawT   - Raw linear progress in [0, 1]
+ * @param easing - Easing mode. "linear" returns rawT unchanged;
+ *                 "ease-out-cubic" (default) applies 1 - (1 - t)^3.
+ * @returns Eased progress in [0, 1]
+ */
+export declare function computeEasing(rawT: number, easing?: EasingMode): number;
+/**
+ * Compute the raw linear progress of a transition.
+ *
+ * @param now        - Current timestamp (e.g. performance.now())
+ * @param transition - The active transition state
+ * @returns Raw progress clamped to [0, 1]
+ */
+export declare function computeRawProgress(now: number, transition: ActiveTransition): number;
+/**
+ * Linearly interpolate between two values.
+ *
+ * @param from - Start value
+ * @param to   - End value
+ * @param t    - Eased progress in [0, 1]
+ */
+export declare function lerp(from: number, to: number, t: number): number;
+/**
+ * Get the current timestamp in a way that works both in browser and Node.
+ */
+export declare function now(): number;

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

@@ -0,0 +1,9 @@
+import type { GeoSceneNode } from "../geoTypes";
+/**
+ * Canvas renderer for GeoAreaSceneNode — projected geographic polygons.
+ * Uses Path2D for GPU-accelerated rendering of complex geo paths.
+ *
+ * Points and lines in a geo frame are rendered by the existing
+ * pointCanvasRenderer and lineCanvasRenderer respectively.
+ */
+export declare function geoCanvasRenderer(ctx: CanvasRenderingContext2D, nodes: GeoSceneNode[], _scales: any, _layout: any): void;

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

@@ -1,6 +1,7 @@
 import type { StreamRendererFn } from "./types";
 /**
  * Canvas heatmap renderer.
- * Renders HeatcellSceneNode as filled rectangles with color encoding.
+ * Renders HeatcellSceneNode as filled rectangles with color encoding,
+ * and optionally draws cell value text when showValues is enabled.
  */
 export declare const heatmapCanvasRenderer: StreamRendererFn;

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

@@ -4,5 +4,6 @@ import type { StreamRendererFn } from "./types";
  * Renders LineSceneNode paths using moveTo/lineTo.
  * Supports threshold-based segment coloring when colorThresholds + rawValues
  * are present on the node.
+ * Supports d3-shape curve interpolation when node.curve is set.
  */
 export declare const lineCanvasRenderer: StreamRendererFn;

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

@@ -0,0 +1,50 @@
+/**
+ * Shared pulse overlay rendering utilities.
+ *
+ * Pulse is a brief visual flash (glow/overlay) applied to scene nodes when
+ * their aggregated value changes. Each node carries `_pulseIntensity` (0–1),
+ * `_pulseColor`, and optionally `_pulseGlowRadius`.
+ *
+ * Three visual variants:
+ * - **Rect overlay**: semi-transparent fillRect on top of the bar/cell
+ * - **Circle glow ring**: expanding stroke ring around a point
+ * - **Path fill overlay**: re-traces an arbitrary path and fills with glow
+ */
+interface PulseFields {
+    _pulseIntensity?: number;
+    _pulseColor?: string;
+    _pulseGlowRadius?: number;
+}
+/**
+ * Returns true if the node has an active pulse effect.
+ */
+export declare function hasPulse(node: PulseFields): boolean;
+/**
+ * Render a rectangular pulse overlay (used by bar, heatmap, and network rect renderers).
+ * Call this after drawing the main fill/stroke for the rectangle.
+ */
+export declare function renderRectPulse(ctx: CanvasRenderingContext2D, node: PulseFields & {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}, alphaMultiplier?: number): void;
+/**
+ * Render a circular glow ring pulse (used by point and network circle renderers).
+ * Call this after drawing the main circle fill/stroke.
+ */
+export declare function renderCirclePulse(ctx: CanvasRenderingContext2D, node: PulseFields & {
+    x?: number;
+    y?: number;
+    cx?: number;
+    cy?: number;
+    r: number;
+}, alphaMultiplier?: number): void;
+/**
+ * Render a path-based fill pulse (used by area, wedge, and geo renderers).
+ * The caller must trace the path onto ctx BEFORE calling this function,
+ * or pass a Path2D object as the third argument (for geo renderers).
+ * This function sets alpha/fillStyle and calls ctx.fill().
+ */
+export declare function renderPathPulse(ctx: CanvasRenderingContext2D, node: PulseFields, path?: Path2D, alphaMultiplier?: number): void;
+export {};

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

@@ -1,6 +1,6 @@
 import type { ReactNode } from "react";
 import type { ScaleLinear } from "d3-scale";
-import type { ArrowOfTime, WindowMode, LineStyle, BarStyle, WaterfallStyle, SwarmStyle, HoverAnnotationConfig, HoverData, AnnotationContext } from "../realtime/types";
+import type { ArrowOfTime, WindowMode, LineStyle, BarStyle, WaterfallStyle, SwarmStyle, HoverAnnotationConfig, HoverData, AnnotationContext, AnnotationAnchorMode } from "../realtime/types";
 export interface DecayConfig {
     type: "linear" | "exponential" | "step";
     /** Exponential: half-life in buffer positions (default: bufferSize/2) */
@@ -60,6 +60,7 @@ export interface Style {
     stroke?: string;
     strokeWidth?: number;
     strokeDasharray?: string;
+    strokeLinecap?: "butt" | "round" | "square";
     fill?: string;
     fillOpacity?: number;
     opacity?: number;
@@ -84,6 +85,18 @@ export interface LineSceneNode {
     style: Style;
     datum: any;
     group?: string;
+    /** Curve interpolation type (default: linear / straight segments) */
+    curve?: CurveType;
+    /** Per-vertex decay opacities (oldest→newest = minOpacity→1.0). Set by PipelineStore.applyDecay. */
+    _decayOpacities?: number[];
+    /** Animation target opacity (set during enter/exit transitions) */
+    _targetOpacity?: number;
+    /** Stable identity key for transition tracking */
+    _transitionKey?: string;
+    /** Previous path coordinates for interpolation during transitions */
+    _prevPath?: [number, number][];
+    /** Target path coordinates for interpolation during transitions */
+    _targetPath?: [number, number][];
 }
 export interface AreaSceneNode {
     type: "area";
@@ -103,6 +116,22 @@ export interface AreaSceneNode {
     _pulseIntensity?: number;
     /** Pulse color */
     _pulseColor?: string;
+    /** Curve interpolation type (default: linear / straight segments) */
+    curve?: CurveType;
+    /** Per-vertex decay opacities (oldest→newest = minOpacity→1.0). Set by PipelineStore.applyDecay. */
+    _decayOpacities?: number[];
+    /** Animation target opacity (set during enter/exit transitions) */
+    _targetOpacity?: number;
+    /** Stable identity key for transition tracking */
+    _transitionKey?: string;
+    /** Previous top path coordinates for interpolation during transitions */
+    _prevTopPath?: [number, number][];
+    /** Target top path coordinates for interpolation during transitions */
+    _targetTopPath?: [number, number][];
+    /** Previous bottom path coordinates for interpolation during transitions */
+    _prevBottomPath?: [number, number][];
+    /** Target bottom path coordinates for interpolation during transitions */
+    _targetBottomPath?: [number, number][];
 }
 export interface PointSceneNode {
     type: "point";
@@ -123,7 +152,10 @@ export interface PointSceneNode {
     _targetX?: number;
     _targetY?: number;
     _targetR?: number;
+    _targetOpacity?: number;
     _decayOpacity?: number;
+    /** Stable identity key for transition tracking */
+    _transitionKey?: string;
 }
 export interface RectSceneNode {
     type: "rect";
@@ -136,12 +168,16 @@ export interface RectSceneNode {
     group?: string;
     _pulseIntensity?: number;
     _pulseColor?: string;
+    _pulseGlowRadius?: number;
     /** Animation target fields (set during transitions) */
     _targetX?: number;
     _targetY?: number;
     _targetW?: number;
     _targetH?: number;
+    _targetOpacity?: number;
     _decayOpacity?: number;
+    /** Stable identity key for transition tracking */
+    _transitionKey?: string;
 }
 export interface HeatcellSceneNode {
     type: "heatcell";
@@ -151,14 +187,26 @@ export interface HeatcellSceneNode {
     h: number;
     fill: string;
     datum: any;
+    /** Optional style object (used for decay/transition opacity on heatmap cells) */
+    style?: Style;
+    /** Numeric cell value (for canvas text rendering when showValues is enabled) */
+    value?: number;
+    /** Whether to render the value as text inside the cell */
+    showValues?: boolean;
+    /** Format function for the displayed value */
+    valueFormat?: (v: number) => string;
     _pulseIntensity?: number;
     _pulseColor?: string;
+    _pulseGlowRadius?: number;
     /** Animation target fields (set during transitions) */
     _targetX?: number;
     _targetY?: number;
     _targetW?: number;
     _targetH?: number;
+    _targetOpacity?: number;
     _decayOpacity?: number;
+    /** Stable identity key for transition tracking */
+    _transitionKey?: string;
 }
 export interface CandlestickSceneNode {
     type: "candlestick";
@@ -174,8 +222,17 @@ export interface CandlestickSceneNode {
     wickWidth: number;
     isUp: boolean;
     datum: any;
+    /** Optional style object (used during transition opacity animations) */
+    style?: Style;
     _pulseIntensity?: number;
     _pulseColor?: string;
+    _pulseGlowRadius?: number;
+    /** Animation target opacity (set during enter/exit transitions) */
+    _targetOpacity?: number;
+    /** Decay opacity for candlestick nodes (no style object, stored separately) */
+    _decayOpacity?: number;
+    /** Stable identity key for transition tracking */
+    _transitionKey?: string;
 }
 export interface CandlestickStyle {
     upColor?: string;
@@ -198,11 +255,15 @@ export interface StreamLayout {
     width: number;
     height: number;
 }
-export type CurveType = "linear" | "monotoneX" | "monotoneY" | "step" | "stepAfter" | "stepBefore" | "basis" | "cardinal" | "catmullRom";
+export type CurveType = "linear" | "monotoneX" | "monotoneY" | "step" | "stepAfter" | "stepBefore" | "basis" | "cardinal" | "catmullRom" | "natural";
 export interface StreamXYFrameProps<T = Record<string, any>> {
     chartType: StreamChartType;
     runtimeMode?: RuntimeMode;
     data?: T[];
+    /** Datasets larger than this are chunked for progressive rendering (default 5000) */
+    chunkThreshold?: number;
+    /** Number of items per progressive chunk (default 5000) */
+    chunkSize?: number;
     xAccessor?: string | ((d: T) => number);
     yAccessor?: string | ((d: T) => number);
     colorAccessor?: string | ((d: T) => string);
@@ -247,6 +308,8 @@ export interface StreamXYFrameProps<T = Record<string, any>> {
     windowMode?: WindowMode;
     windowSize?: number;
     timeAccessor?: string | ((d: T) => number);
+    xScaleType?: "linear" | "log";
+    yScaleType?: "linear" | "log";
     xExtent?: [number | undefined, number | undefined] | [number];
     yExtent?: [number | undefined, number | undefined] | [number];
     extentPadding?: number;
@@ -310,6 +373,8 @@ export interface StreamXYFrameProps<T = Record<string, any>> {
     showGrid?: boolean;
     legend?: ReactNode | {
         legendGroups: any[];
+    } | {
+        gradient: import("../types/legendTypes").GradientLegendConfig;
     };
     legendHoverBehavior?: (item: {
         label: string;
@@ -319,10 +384,13 @@ export interface StreamXYFrameProps<T = Record<string, any>> {
     }) => void;
     legendHighlightedCategory?: string | null;
     legendIsolatedCategories?: Set<string>;
+    legendPosition?: "right" | "left" | "top" | "bottom";
     /** SVG elements rendered behind the canvas (in pixel space) */
     backgroundGraphics?: ReactNode;
     /** SVG elements rendered on top of everything (in SVG overlay) */
     foregroundGraphics?: ReactNode;
+    /** Canvas renderers executed before the chart-type renderers (e.g. connecting lines under points) */
+    canvasPreRenderers?: CanvasRendererFn[];
     title?: string | ReactNode;
     categoryAccessor?: string | ((d: T) => string);
     /** Configurable opacity decay for older data points */
@@ -341,6 +409,12 @@ export interface StreamXYFrameProps<T = Record<string, any>> {
     heatmapXBins?: number;
     /** Number of y-axis bins for streaming heatmap (default: 20) */
     heatmapYBins?: number;
+    /** Show numeric values inside heatmap cells (rendered natively on canvas) */
+    showValues?: boolean;
+    /** Format function for heatmap cell value labels */
+    heatmapValueFormat?: (v: number) => string;
+    /** Render a visually-hidden data table from the scene graph for screen readers (first 50 rows) */
+    accessibleTable?: boolean;
 }
 export interface StreamXYFrameHandle<T = Record<string, any>> {
     push(datum: T): void;
@@ -354,4 +428,4 @@ export interface StreamXYFrameHandle<T = Record<string, any>> {
     } | null;
 }
 export type CanvasRendererFn = (ctx: CanvasRenderingContext2D, nodes: SceneNode[], scales: StreamScales, layout: StreamLayout) => void;
-export type { ArrowOfTime, WindowMode, LineStyle, BarStyle, WaterfallStyle, SwarmStyle, HoverAnnotationConfig, HoverData, AnnotationContext };
+export type { ArrowOfTime, WindowMode, LineStyle, BarStyle, WaterfallStyle, SwarmStyle, HoverAnnotationConfig, HoverData, AnnotationContext, AnnotationAnchorMode };

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

@@ -1,22 +1,46 @@
+import type { CSSProperties, ReactElement } from "react";
 export type SupportedLegendGlyphs = "fill" | "line";
-export type ItemType = SupportedLegendGlyphs | Function;
+export type ItemType = SupportedLegendGlyphs | ((item: LegendItem) => ReactElement);
 export interface LegendItem {
     label: string;
+    color?: string;
+    [key: string]: unknown;
 }
 export interface LegendGroup {
     type?: ItemType;
-    styleFn: Function;
+    styleFn: (item: LegendItem, index: number) => CSSProperties;
     items: LegendItem[];
     label: string;
 }
+/** Configuration for a gradient (continuous) legend */
+export interface GradientLegendConfig {
+    /** Color function: receives a value in `domain` range and returns a color string */
+    colorFn: (value: number) => string;
+    /** Data domain [min, max] */
+    domain: [number, number];
+    /** Optional label for the gradient */
+    label?: string;
+    /** Optional format function for tick labels */
+    format?: (v: number) => string;
+}
+/** Type guard: categorical legend config */
+export declare function isLegendConfig(value: unknown): value is {
+    legendGroups: LegendGroup[];
+};
+/** Type guard: gradient legend config */
+export declare function isGradientLegendConfig(value: unknown): value is {
+    gradient: GradientLegendConfig;
+};
 export interface LegendProps {
     legendGroups?: LegendGroup[];
-    customClickBehavior?: Function;
+    customClickBehavior?: (item: LegendItem) => void;
     customHoverBehavior?: (item: LegendItem | null) => void;
     /** Set of currently isolated category labels (shown with checkmarks) */
     isolatedCategories?: Set<string>;
     /** Whether hover-highlighting is active (dims non-hovered items) */
     highlightedCategory?: string | null;
+    /** Legend interaction mode — used to set aria-multiselectable on the listbox */
+    legendInteraction?: string;
     title?: string;
     width?: number;
     height?: number;