semiotic 3.0.0 → 3.1.0

package/dist/{charts → components/charts}/ordinal/StackedBarChart.d.ts

@@ -1,9 +1,11 @@
 import * as React from "react";
 import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
+import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { RealtimeFrameHandle } from "../../realtime/types";
 export interface StackedBarChartProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
-    data: TDatum[];
+    data?: TDatum[];
     categoryAccessor?: ChartAccessor<TDatum, string>;
     stackBy: ChartAccessor<TDatum, string>;
     valueAccessor?: ChartAccessor<TDatum, number>;
@@ -18,11 +20,13 @@ export interface StackedBarChartProps<TDatum extends Record<string, any> = Recor
     enableHover?: boolean;
     showGrid?: boolean;
     showLegend?: boolean;
+    legendInteraction?: LegendInteractionMode;
+    legendPosition?: "right" | "left" | "top" | "bottom";
     tooltip?: TooltipProp;
     annotations?: Record<string, any>[];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
-export declare function StackedBarChart<TDatum extends Record<string, any> = Record<string, any>>(props: StackedBarChartProps<TDatum>): React.JSX.Element;
-export declare namespace StackedBarChart {
-    var displayName: string;
-}
+export declare const StackedBarChart: {
+    <TDatum extends Record<string, any> = Record<string, any>>(props: StackedBarChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

package/dist/{charts → components/charts}/ordinal/SwarmPlot.d.ts

@@ -1,9 +1,11 @@
 import * as React from "react";
 import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
+import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { RealtimeFrameHandle } from "../../realtime/types";
 export interface SwarmPlotProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
-    data: TDatum[];
+    data?: TDatum[];
     categoryAccessor?: ChartAccessor<TDatum, string>;
     valueAccessor?: ChartAccessor<TDatum, number>;
     orientation?: "vertical" | "horizontal";
@@ -20,11 +22,13 @@ export interface SwarmPlotProps<TDatum extends Record<string, any> = Record<stri
     enableHover?: boolean;
     showGrid?: boolean;
     showLegend?: boolean;
+    legendInteraction?: LegendInteractionMode;
+    legendPosition?: LegendPosition;
     tooltip?: TooltipProp;
     annotations?: Record<string, any>[];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
-export declare function SwarmPlot<TDatum extends Record<string, any> = Record<string, any>>(props: SwarmPlotProps<TDatum>): React.JSX.Element;
-export declare namespace SwarmPlot {
-    var displayName: string;
-}
+export declare const SwarmPlot: {
+    <TDatum extends Record<string, any> = Record<string, any>>(props: SwarmPlotProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

package/dist/{charts → components/charts}/ordinal/ViolinPlot.d.ts

@@ -1,9 +1,11 @@
 import * as React from "react";
 import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
+import type { LegendPosition } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { RealtimeFrameHandle } from "../../realtime/types";
 export interface ViolinPlotProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
-    data: TDatum[];
+    data?: TDatum[];
     categoryAccessor?: ChartAccessor<TDatum, string>;
     valueAccessor?: ChartAccessor<TDatum, number>;
     orientation?: "vertical" | "horizontal";
@@ -19,11 +21,12 @@ export interface ViolinPlotProps<TDatum extends Record<string, any> = Record<str
     enableHover?: boolean;
     showGrid?: boolean;
     showLegend?: boolean;
+    legendPosition?: LegendPosition;
     tooltip?: TooltipProp;
     annotations?: Record<string, any>[];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
-export declare function ViolinPlot<TDatum extends Record<string, any> = Record<string, any>>(props: ViolinPlotProps<TDatum>): React.JSX.Element;
-export declare namespace ViolinPlot {
-    var displayName: string;
-}
+export declare const ViolinPlot: {
+    <TDatum extends Record<string, any> = Record<string, any>>(props: ViolinPlotProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

package/dist/{charts → components/charts}/realtime/RealtimeHeatmap.d.ts

@@ -2,9 +2,10 @@ import * as React from "react";
 import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, AnnotationContext, DecayConfig, PulseConfig, StalenessConfig } from "../../stream/types";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { ReactNode } from "react";
-import type { ChartMode } from "../shared/types";
+import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
+import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
-export interface RealtimeHeatmapProps {
+export interface RealtimeHeatmapProps<TDatum extends Record<string, any> = Record<string, any>> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
     /** Chart dimensions as [width, height] */
@@ -33,11 +34,11 @@ export interface RealtimeHeatmapProps {
     /** Controlled data array */
     data?: Record<string, any>[];
     /** Time/x value accessor */
-    timeAccessor?: string | ((d: Record<string, any>) => number);
+    timeAccessor?: ChartAccessor<TDatum, number>;
     /** Value/y accessor */
-    valueAccessor?: string | ((d: Record<string, any>) => number);
+    valueAccessor?: ChartAccessor<TDatum, number>;
     /** Category accessor for colored cells */
-    categoryAccessor?: string | ((d: Record<string, any>) => string);
+    categoryAccessor?: ChartAccessor<TDatum, string>;
     /** Fixed time domain */
     timeExtent?: [number, number];
     /** Fixed value domain */
@@ -81,6 +82,20 @@ export interface RealtimeHeatmapProps {
         name?: string;
         fields: string[];
     };
+    /** Consume a named selection — dims unselected elements */
+    selection?: SelectionConfig;
+    /** Show a loading skeleton placeholder */
+    loading?: boolean;
+    /** Custom content to render when data is empty. Set to `false` to disable empty state. */
+    emptyContent?: ReactNode | false;
+    /** Visual emphasis level for dashboard hierarchy. "primary" spans two columns in ChartGrid. */
+    emphasis?: "primary" | "secondary";
+    /** Show a legend */
+    showLegend?: boolean;
+    /** Legend position */
+    legendPosition?: LegendPosition;
+    /** Legend interaction mode */
+    legendInteraction?: LegendInteractionMode;
 }
 /**
  * RealtimeHeatmap - Streaming heatmap with 2D grid binning.
@@ -103,4 +118,7 @@ export interface RealtimeHeatmapProps {
  * />
  * ```
  */
-export declare const RealtimeHeatmap: React.ForwardRefExoticComponent<RealtimeHeatmapProps & React.RefAttributes<RealtimeFrameHandle>>;
+export declare const RealtimeHeatmap: {
+    <TDatum extends Record<string, any> = Record<string, any>>(props: RealtimeHeatmapProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

package/dist/{charts → components/charts}/realtime/RealtimeHistogram.d.ts

@@ -2,9 +2,10 @@ import * as React from "react";
 import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, AnnotationContext, DecayConfig, PulseConfig, StalenessConfig, TransitionConfig } from "../../stream/types";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { ReactNode } from "react";
-import type { ChartMode } from "../shared/types";
+import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
+import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
-export interface RealtimeTemporalHistogramProps {
+export interface RealtimeTemporalHistogramProps<TDatum extends Record<string, any> = Record<string, any>> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
     /** Time interval for binning */
@@ -35,9 +36,9 @@ export interface RealtimeTemporalHistogramProps {
     /** Controlled data array */
     data?: Record<string, any>[];
     /** Time value accessor */
-    timeAccessor?: string | ((d: Record<string, any>) => number);
+    timeAccessor?: ChartAccessor<TDatum, number>;
     /** Value accessor */
-    valueAccessor?: string | ((d: Record<string, any>) => number);
+    valueAccessor?: ChartAccessor<TDatum, number>;
     /** Fixed time domain */
     timeExtent?: [number, number];
     /** Fixed value domain */
@@ -48,7 +49,7 @@ export interface RealtimeTemporalHistogramProps {
      * Category accessor for stacked bars.
      * When provided, bars are stacked by category within each bin.
      */
-    categoryAccessor?: string | ((d: Record<string, any>) => string);
+    categoryAccessor?: ChartAccessor<TDatum, string>;
     /**
      * Category-to-color map for stacked bars.
      * Keys also determine stack order (listed keys first, then alphabetical).
@@ -87,6 +88,8 @@ export interface RealtimeTemporalHistogramProps {
         name?: string;
         fields: string[];
     };
+    /** Consume a named selection — dims unselected elements */
+    selection?: SelectionConfig;
     /** Configurable opacity decay for older data */
     decay?: DecayConfig;
     /** Flash effect on newly inserted data */
@@ -95,6 +98,18 @@ export interface RealtimeTemporalHistogramProps {
     staleness?: StalenessConfig;
     /** Smooth position interpolation on data change */
     transition?: TransitionConfig;
+    /** Show a loading skeleton placeholder */
+    loading?: boolean;
+    /** Custom content to render when data is empty. Set to `false` to disable empty state. */
+    emptyContent?: ReactNode | false;
+    /** Visual emphasis level for dashboard hierarchy. "primary" spans two columns in ChartGrid. */
+    emphasis?: "primary" | "secondary";
+    /** Show a legend */
+    showLegend?: boolean;
+    /** Legend position */
+    legendPosition?: LegendPosition;
+    /** Legend interaction mode */
+    legendInteraction?: LegendInteractionMode;
 }
 /**
  * RealtimeTemporalHistogram - Streaming temporal histogram.
@@ -126,8 +141,14 @@ export interface RealtimeTemporalHistogramProps {
  * />
  * ```
  */
-export declare const RealtimeTemporalHistogram: React.ForwardRefExoticComponent<RealtimeTemporalHistogramProps & React.RefAttributes<RealtimeFrameHandle>>;
+export declare const RealtimeTemporalHistogram: {
+    <TDatum extends Record<string, any> = Record<string, any>>(props: RealtimeTemporalHistogramProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};
 /** @deprecated Use RealtimeTemporalHistogram instead */
-export declare const RealtimeHistogram: React.ForwardRefExoticComponent<RealtimeTemporalHistogramProps & React.RefAttributes<RealtimeFrameHandle>>;
+export declare const RealtimeHistogram: {
+    <TDatum extends Record<string, any> = Record<string, any>>(props: RealtimeTemporalHistogramProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};
 /** @deprecated Use RealtimeTemporalHistogramProps instead */
 export type RealtimeHistogramProps = RealtimeTemporalHistogramProps;

package/dist/{charts → components/charts}/realtime/RealtimeLineChart.d.ts

@@ -2,9 +2,10 @@ import * as React from "react";
 import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, AnnotationContext, DecayConfig, PulseConfig, StalenessConfig, TransitionConfig } from "../../stream/types";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { ReactNode } from "react";
-import type { ChartMode } from "../shared/types";
+import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
+import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
-export interface RealtimeLineChartProps {
+export interface RealtimeLineChartProps<TDatum extends Record<string, any> = Record<string, any>> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
     /** Chart dimensions as [width, height] */
@@ -33,9 +34,9 @@ export interface RealtimeLineChartProps {
     /** Controlled data array */
     data?: Record<string, any>[];
     /** Time value accessor */
-    timeAccessor?: string | ((d: Record<string, any>) => number);
+    timeAccessor?: ChartAccessor<TDatum, number>;
     /** Value accessor */
-    valueAccessor?: string | ((d: Record<string, any>) => number);
+    valueAccessor?: ChartAccessor<TDatum, number>;
     /** Fixed time domain */
     timeExtent?: [number, number];
     /** Fixed value domain */
@@ -81,6 +82,20 @@ export interface RealtimeLineChartProps {
         name?: string;
         fields: string[];
     };
+    /** Consume a named selection — dims unselected elements */
+    selection?: SelectionConfig;
+    /** Show a loading skeleton placeholder */
+    loading?: boolean;
+    /** Custom content to render when data is empty. Set to `false` to disable empty state. */
+    emptyContent?: ReactNode | false;
+    /** Visual emphasis level for dashboard hierarchy. "primary" spans two columns in ChartGrid. */
+    emphasis?: "primary" | "secondary";
+    /** Show a legend */
+    showLegend?: boolean;
+    /** Legend position */
+    legendPosition?: LegendPosition;
+    /** Legend interaction mode */
+    legendInteraction?: LegendInteractionMode;
 }
 /**
  * RealtimeLineChart - Simplified wrapper for streaming line charts.
@@ -101,4 +116,7 @@ export interface RealtimeLineChartProps {
  * />
  * ```
  */
-export declare const RealtimeLineChart: React.ForwardRefExoticComponent<RealtimeLineChartProps & React.RefAttributes<RealtimeFrameHandle>>;
+export declare const RealtimeLineChart: {
+    <TDatum extends Record<string, any> = Record<string, any>>(props: RealtimeLineChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

package/dist/{charts → components/charts}/realtime/RealtimeSwarmChart.d.ts

@@ -2,9 +2,10 @@ import * as React from "react";
 import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, AnnotationContext } from "../../stream/types";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { ReactNode } from "react";
-import type { ChartMode } from "../shared/types";
+import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
+import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
-export interface RealtimeSwarmChartProps {
+export interface RealtimeSwarmChartProps<TDatum extends Record<string, any> = Record<string, any>> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
     /** Chart dimensions as [width, height] */
@@ -33,9 +34,9 @@ export interface RealtimeSwarmChartProps {
     /** Controlled data array */
     data?: Record<string, any>[];
     /** Time value accessor */
-    timeAccessor?: string | ((d: Record<string, any>) => number);
+    timeAccessor?: ChartAccessor<TDatum, number>;
     /** Value accessor */
-    valueAccessor?: string | ((d: Record<string, any>) => number);
+    valueAccessor?: ChartAccessor<TDatum, number>;
     /** Fixed time domain */
     timeExtent?: [number, number];
     /** Fixed value domain */
@@ -43,7 +44,7 @@ export interface RealtimeSwarmChartProps {
     /** Extent padding factor */
     extentPadding?: number;
     /** Category accessor for color-coding dots */
-    categoryAccessor?: string | ((d: Record<string, any>) => string);
+    categoryAccessor?: ChartAccessor<TDatum, string>;
     /** Category-to-color map */
     colors?: Record<string, string>;
     /** Dot radius */
@@ -81,6 +82,20 @@ export interface RealtimeSwarmChartProps {
         name?: string;
         fields: string[];
     };
+    /** Consume a named selection — dims unselected elements */
+    selection?: SelectionConfig;
+    /** Show a loading skeleton placeholder */
+    loading?: boolean;
+    /** Custom content to render when data is empty. Set to `false` to disable empty state. */
+    emptyContent?: ReactNode | false;
+    /** Visual emphasis level for dashboard hierarchy. "primary" spans two columns in ChartGrid. */
+    emphasis?: "primary" | "secondary";
+    /** Show a legend */
+    showLegend?: boolean;
+    /** Legend position */
+    legendPosition?: LegendPosition;
+    /** Legend interaction mode */
+    legendInteraction?: LegendInteractionMode;
 }
 /**
  * RealtimeSwarmChart - Simplified wrapper for streaming dot/swarm charts.
@@ -103,4 +118,7 @@ export interface RealtimeSwarmChartProps {
  * />
  * ```
  */
-export declare const RealtimeSwarmChart: React.ForwardRefExoticComponent<RealtimeSwarmChartProps & React.RefAttributes<RealtimeFrameHandle>>;
+export declare const RealtimeSwarmChart: {
+    <TDatum extends Record<string, any> = Record<string, any>>(props: RealtimeSwarmChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

package/dist/{charts → components/charts}/realtime/RealtimeWaterfallChart.d.ts

@@ -2,9 +2,10 @@ import * as React from "react";
 import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, AnnotationContext } from "../../stream/types";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { ReactNode } from "react";
-import type { ChartMode } from "../shared/types";
+import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
+import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
-export interface RealtimeWaterfallChartProps {
+export interface RealtimeWaterfallChartProps<TDatum extends Record<string, any> = Record<string, any>> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
     /** Chart dimensions as [width, height] */
@@ -33,9 +34,9 @@ export interface RealtimeWaterfallChartProps {
     /** Controlled data array */
     data?: Record<string, any>[];
     /** Time value accessor */
-    timeAccessor?: string | ((d: Record<string, any>) => number);
+    timeAccessor?: ChartAccessor<TDatum, number>;
     /** Value accessor (positive = gain, negative = loss) */
-    valueAccessor?: string | ((d: Record<string, any>) => number);
+    valueAccessor?: ChartAccessor<TDatum, number>;
     /** Fixed time domain */
     timeExtent?: [number, number];
     /** Fixed value domain */
@@ -81,6 +82,20 @@ export interface RealtimeWaterfallChartProps {
         name?: string;
         fields: string[];
     };
+    /** Consume a named selection — dims unselected elements */
+    selection?: SelectionConfig;
+    /** Show a loading skeleton placeholder */
+    loading?: boolean;
+    /** Custom content to render when data is empty. Set to `false` to disable empty state. */
+    emptyContent?: ReactNode | false;
+    /** Visual emphasis level for dashboard hierarchy. "primary" spans two columns in ChartGrid. */
+    emphasis?: "primary" | "secondary";
+    /** Show a legend */
+    showLegend?: boolean;
+    /** Legend position */
+    legendPosition?: LegendPosition;
+    /** Legend interaction mode */
+    legendInteraction?: LegendInteractionMode;
 }
 /**
  * RealtimeWaterfallChart - Simplified wrapper for streaming waterfall charts.
@@ -100,4 +115,7 @@ export interface RealtimeWaterfallChartProps {
  * />
  * ```
  */
-export declare const RealtimeWaterfallChart: React.ForwardRefExoticComponent<RealtimeWaterfallChartProps & React.RefAttributes<RealtimeFrameHandle>>;
+export declare const RealtimeWaterfallChart: {
+    <TDatum extends Record<string, any> = Record<string, any>>(props: RealtimeWaterfallChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

package/dist/{charts → components/charts}/shared/colorUtils.d.ts

@@ -22,6 +22,11 @@ export declare const DEFAULT_COLORS: readonly string[];
  * Pastel palette for depth-based hierarchy coloring (Treemap, CirclePack, TreeDiagram).
  * Index corresponds to hierarchy depth, wraps via modulo.
  */
+/**
+ * Default streaming palette — used by PipelineStore, OrdinalPipelineStore,
+ * and useStreamingLegend for consistent colors when no colorScheme is specified.
+ */
+export declare const STREAMING_PALETTE: string[];
 export declare const DEPTH_PALETTE_COLORS: string[];
 /**
  * Gets a color for a data point based on the colorBy configuration

package/dist/components/charts/shared/diagnoseConfig.d.ts

@@ -0,0 +1,23 @@
+/**
+ * diagnoseConfig — anti-pattern detector for Semiotic chart configurations.
+ *
+ * Catches common failure modes that produce blank charts or runtime errors,
+ * returning actionable fix instructions for each issue found.
+ */
+export interface Diagnosis {
+    severity: "error" | "warning";
+    code: string;
+    message: string;
+    fix: string;
+}
+export interface DiagnosisResult {
+    ok: boolean;
+    diagnoses: Diagnosis[];
+}
+/**
+ * Run anti-pattern diagnostics on a Semiotic chart configuration.
+ *
+ * Returns actionable diagnoses with severity, code, message, and fix instruction.
+ * Runs validateProps internally — validation errors are included as diagnoses.
+ */
+export declare function diagnoseConfig(componentName: string, props: Record<string, any>): DiagnosisResult;

package/dist/{charts → components/charts}/shared/hooks.d.ts

@@ -3,6 +3,7 @@ import type { SelectionHookResult } from "./selectionUtils";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { Accessor, SelectionConfig, LinkedHoverProp, ChartMode } from "./types";
 import type { MarginType } from "../../types/generalTypes";
+import type { TransitionConfig } from "../../stream/types";
 /**
  * Default fill color used when no colorBy is specified
  */
@@ -16,7 +17,7 @@ export declare function resolveAccessor<T = any>(accessor: string | ((d: Record<
  * Hook to create a color scale from data and colorBy configuration.
  * Returns undefined when colorBy is absent or is a function accessor.
  */
-export declare function useColorScale(data: Array<Record<string, any>>, colorBy: Accessor<string> | undefined, colorScheme?: string | string[]): ((v: string) => string) | undefined;
+export declare function useColorScale(data: Array<Record<string, any>>, colorBy: string | ((d: any, i?: number) => any) | undefined, colorScheme?: string | string[]): ((v: string) => string) | undefined;
 /**
  * Hook to sort data by a value accessor.
  * Used by BarChart and DotPlot.
@@ -48,11 +49,13 @@ export declare function useChartSelection({ selection, linkedHover, fallbackFiel
  * Consolidates the shouldShowLegend / createLegend / margin merge / right-margin
  * expansion pattern that every chart with color encoding repeats.
  */
-export declare function useChartLegendAndMargin({ data, colorBy, colorScale, showLegend, userMargin, defaults, }: {
+export type LegendPosition = "right" | "left" | "top" | "bottom";
+export declare function useChartLegendAndMargin({ data, colorBy, colorScale, showLegend, legendPosition, userMargin, defaults, }: {
     data: Array<Record<string, any>>;
     colorBy: Accessor<string> | undefined;
     colorScale: ((v: string) => string) | undefined;
     showLegend: boolean | undefined;
+    legendPosition?: LegendPosition;
     userMargin: MarginType | undefined;
     defaults?: {
         top: number;
@@ -68,7 +71,30 @@ export declare function useChartLegendAndMargin({ data, colorBy, colorScale, sho
         left: number;
         right: number;
     };
+    legendPosition: LegendPosition;
 };
+export type LegendInteractionMode = "highlight" | "isolate" | "none";
+export interface LegendInteractionState {
+    highlightedCategory: string | null;
+    isolatedCategories: Set<string>;
+    onLegendHover: (item: {
+        label: string;
+    } | null) => void;
+    onLegendClick: (item: {
+        label: string;
+    }) => void;
+    /** Selection predicate that dims non-matching data — use with wrapStyleWithSelection */
+    legendSelectionHook: {
+        isActive: boolean;
+        predicate: (d: Record<string, any>) => boolean;
+    } | null;
+}
+/**
+ * Hook managing legend highlight/isolate interaction.
+ * - "highlight": hover over legend item dims everything else to 30% opacity
+ * - "isolate": click toggles category visibility; click all to reset
+ */
+export declare function useLegendInteraction(mode: LegendInteractionMode | undefined, colorBy: string | ((d: any) => string) | undefined, allCategories: string[]): LegendInteractionState;
 interface ChartModeInput {
     width?: number;
     height?: number;
@@ -112,4 +138,12 @@ export declare function useChartMode(mode: ChartMode | undefined, userProps: Cha
     width?: number;
     height?: number;
 }): ChartModeResult;
+/**
+ * Resolve the `animate` prop into a `TransitionConfig` for Stream Frames.
+ * Returns undefined when animate is falsy (no transition).
+ */
+export declare function resolveAnimateConfig(animate: boolean | {
+    duration?: number;
+    easing?: "linear" | "ease-out";
+} | undefined): TransitionConfig | undefined;
 export {};

package/dist/{charts → components/charts}/shared/legendUtils.d.ts

@@ -1,4 +1,5 @@
 import type { Accessor } from "./types";
+import type { LegendItem } from "../../types/legendTypes";
 /**
  * Create a legend configuration for HOC components
  *
@@ -19,9 +20,7 @@ export declare function createLegend({ data, colorBy, colorScale, getColor, stro
     strokeWidth?: number;
 }): {
     legendGroups: {
-        styleFn: (d: {
-            color: string;
-        }) => Record<string, string | number>;
+        styleFn: (d: LegendItem) => Record<string, string | number>;
         type: "fill";
         items: {
             label: string;

package/dist/{charts → components/charts}/shared/statisticalOverlays.d.ts

@@ -67,10 +67,9 @@ export interface ForecastConfig {
 export declare const SEGMENT_FIELD: "__forecastSegment";
 export type SegmentType = "training" | "observed" | "forecast";
 export declare function buildAnomalyAnnotations(config: AnomalyConfig): Record<string, any>[];
-interface ForecastResult {
+export interface ForecastResult {
     processedData: Record<string, any>[];
     annotations: Record<string, any>[];
 }
 export declare function buildForecast(data: Record<string, any>[], xAccessor: string, yAccessor: string, forecastConfig: ForecastConfig, anomalyConfig?: AnomalyConfig): ForecastResult;
 export declare function createSegmentLineStyle(baseStyle: (d: Record<string, any>) => Record<string, any>, forecastConfig: ForecastConfig): (d: Record<string, any>) => Record<string, any>;
-export {};

package/dist/components/charts/shared/statisticalOverlaysLazy.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Lazy-loaded wrapper for statistical overlays.
+ * Only loads the LOESS/forecast logic when forecast or anomaly props are actually used.
+ */
+export type { ForecastResult } from "./statisticalOverlays";
+/** Duplicated here to avoid pulling in the heavy statisticalOverlays module at import time */
+export declare const SEGMENT_FIELD: "__forecastSegment";
+export declare function buildForecastLazy(...args: Parameters<typeof import("./statisticalOverlays")["buildForecast"]>): Promise<import("./statisticalOverlays").ForecastResult>;
+export declare function buildAnomalyAnnotationsLazy(...args: Parameters<typeof import("./statisticalOverlays")["buildAnomalyAnnotations"]>): Promise<Record<string, any>[]>;
+export declare function createSegmentLineStyleLazy(...args: Parameters<typeof import("./statisticalOverlays")["createSegmentLineStyle"]>): Promise<(d: Record<string, any>) => Record<string, any>>;

package/dist/components/charts/shared/stringDistance.d.ts

@@ -0,0 +1,11 @@
+/**
+ * String distance utilities for typo detection and field suggestions.
+ * Shared by validateProps and validateChartData.
+ */
+/** Levenshtein edit distance between two strings. */
+export declare function levenshtein(a: string, b: string): number;
+/**
+ * Find the closest match from candidates by Levenshtein distance.
+ * Returns the match if distance <= maxDist, otherwise null/undefined.
+ */
+export declare function closestMatch(input: string, candidates: string[], maxDist?: number): string | undefined;

package/dist/{charts → components/charts}/shared/tooltipUtils.d.ts

@@ -2,8 +2,8 @@ import * as React from "react";
 import type { HoverData } from "../../realtime/types";
 export interface TooltipFieldConfig {
     label: string;
-    accessor: string | ((d: Record<string, any>) => any);
-    role?: "x" | "y" | "color" | "size" | "group" | "value";
+    accessor: string | ((d: any) => any);
+    role?: "title" | "x" | "y" | "color" | "size" | "group" | "value";
 }
 /**
  * Extract a display name from an accessor.

package/dist/{charts → components/charts}/shared/types.d.ts

@@ -69,6 +69,18 @@ export interface BaseChartProps {
     onObservation?: OnObservationCallback;
     /** Identifier for this chart instance, included in observation events */
     chartId?: string;
+    /** Show a loading skeleton placeholder */
+    loading?: boolean;
+    /** Custom content to render when data is empty. Set to `false` to disable empty state. */
+    emptyContent?: React.ReactNode | false;
+    /** Visual emphasis level for dashboard hierarchy. "primary" spans two columns in ChartGrid. */
+    emphasis?: "primary" | "secondary";
+    /** Enable declarative bounded animation (enter/exit/update transitions).
+     * `true` uses defaults (300ms ease-out). Object form allows customization. */
+    animate?: boolean | {
+        duration?: number;
+        easing?: "linear" | "ease-out";
+    };
 }
 /**
  * Axis configuration props
@@ -97,9 +109,9 @@ export type ChartAccessor<TDatum, T> = (keyof TDatum & string) | ((d: Record<str
 /**
  * Color configuration
  */
-export interface ColorConfig {
+export interface ColorConfig<TDatum = Record<string, any>> {
     /** Field name or function to determine color */
-    colorBy?: Accessor<string>;
+    colorBy?: ChartAccessor<TDatum, string>;
     /** Color scheme name (e.g., "blues", "category10") */
     colorScheme?: string;
     /** Custom color palette */
@@ -108,9 +120,9 @@ export interface ColorConfig {
 /**
  * Size configuration
  */
-export interface SizeConfig {
+export interface SizeConfig<TDatum = Record<string, any>> {
     /** Field name or function to determine size */
-    sizeBy?: Accessor<number>;
+    sizeBy?: ChartAccessor<TDatum, number>;
     /** Min and max size range */
     sizeRange?: [number, number];
 }