semiotic 3.4.0 → 3.4.1

package/dist/components/charts/realtime/RealtimeLineChart.d.ts

@@ -5,7 +5,8 @@ import type { ReactNode } from "react";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
-export interface RealtimeLineChartProps<TDatum extends Record<string, any> = Record<string, any>> {
+import type { Datum } from "../shared/datumTypes";
+export interface RealtimeLineChartProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
     /** Chart dimensions as [width, height] */
@@ -32,7 +33,7 @@ export interface RealtimeLineChartProps<TDatum extends Record<string, any> = Rec
     /** Ring buffer capacity */
     windowSize?: number;
     /** Controlled data array */
-    data?: Record<string, any>[];
+    data?: Datum[];
     /** Time value accessor */
     timeAccessor?: ChartAccessor<TDatum, number>;
     /** Value accessor */
@@ -49,6 +50,8 @@ export interface RealtimeLineChartProps<TDatum extends Record<string, any> = Rec
     strokeWidth?: number;
     /** Dash pattern (e.g. "4,2") */
     strokeDasharray?: string;
+    /** Uniform line opacity (0–1). Pairs with `stroke` / `strokeWidth` for the designer-facing primitive vocabulary. */
+    opacity?: number;
     /** Show canvas-drawn axes */
     showAxes?: boolean;
     /** Background fill color */
@@ -60,9 +63,9 @@ export interface RealtimeLineChartProps<TDatum extends Record<string, any> = Rec
     /** Callback on hover */
     onHover?: (d: HoverData | null) => void;
     /** Annotation objects */
-    annotations?: Record<string, any>[];
+    annotations?: Datum[];
     /** SVG annotation render function */
-    svgAnnotationRules?: (annotation: Record<string, any>, index: number, context: AnnotationContext) => ReactNode;
+    svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     /** Custom formatter for time axis ticks */
     tickFormatTime?: (value: number) => string;
     /** Custom formatter for value axis ticks */
@@ -97,7 +100,7 @@ export interface RealtimeLineChartProps<TDatum extends Record<string, any> = Rec
     /** Legend interaction mode */
     legendInteraction?: LegendInteractionMode;
     /** ID accessor for remove()/update() on the push API */
-    pointIdAccessor?: string | ((d: any) => string);
+    pointIdAccessor?: string | ((d: Datum) => string);
 }
 /**
  * RealtimeLineChart - Simplified wrapper for streaming line charts.
@@ -119,6 +122,6 @@ export interface RealtimeLineChartProps<TDatum extends Record<string, any> = Rec
  * ```
  */
 export declare const RealtimeLineChart: {
-    <TDatum extends Record<string, any> = Record<string, any>>(props: RealtimeLineChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    <TDatum extends Datum = Datum>(props: RealtimeLineChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
     displayName?: string;
 };

package/dist/components/charts/realtime/RealtimeSwarmChart.d.ts

@@ -5,7 +5,8 @@ import type { ReactNode } from "react";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
-export interface RealtimeSwarmChartProps<TDatum extends Record<string, any> = Record<string, any>> {
+import type { Datum } from "../shared/datumTypes";
+export interface RealtimeSwarmChartProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
     /** Chart dimensions as [width, height] */
@@ -32,7 +33,7 @@ export interface RealtimeSwarmChartProps<TDatum extends Record<string, any> = Re
     /** Ring buffer capacity */
     windowSize?: number;
     /** Controlled data array */
-    data?: Record<string, any>[];
+    data?: Datum[];
     /** Time value accessor */
     timeAccessor?: ChartAccessor<TDatum, number>;
     /** Value accessor */
@@ -68,9 +69,9 @@ export interface RealtimeSwarmChartProps<TDatum extends Record<string, any> = Re
     /** Callback on hover */
     onHover?: (d: HoverData | null) => void;
     /** Annotation objects (including threshold coloring) */
-    annotations?: Record<string, any>[];
+    annotations?: Datum[];
     /** SVG annotation render function */
-    svgAnnotationRules?: (annotation: Record<string, any>, index: number, context: AnnotationContext) => ReactNode;
+    svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     /** Custom formatter for time axis ticks */
     tickFormatTime?: (value: number) => string;
     /** Custom formatter for value axis ticks */
@@ -97,7 +98,7 @@ export interface RealtimeSwarmChartProps<TDatum extends Record<string, any> = Re
     /** Legend interaction mode */
     legendInteraction?: LegendInteractionMode;
     /** ID accessor for remove()/update() on the push API */
-    pointIdAccessor?: string | ((d: any) => string);
+    pointIdAccessor?: string | ((d: Datum) => string);
 }
 /**
  * RealtimeSwarmChart - Simplified wrapper for streaming dot/swarm charts.
@@ -121,6 +122,6 @@ export interface RealtimeSwarmChartProps<TDatum extends Record<string, any> = Re
  * ```
  */
 export declare const RealtimeSwarmChart: {
-    <TDatum extends Record<string, any> = Record<string, any>>(props: RealtimeSwarmChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    <TDatum extends Datum = Datum>(props: RealtimeSwarmChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
     displayName?: string;
 };

package/dist/components/charts/realtime/RealtimeWaterfallChart.d.ts

@@ -5,7 +5,8 @@ import type { ReactNode } from "react";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
-export interface RealtimeWaterfallChartProps<TDatum extends Record<string, any> = Record<string, any>> {
+import type { Datum } from "../shared/datumTypes";
+export interface RealtimeWaterfallChartProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
     /** Chart dimensions as [width, height] */
@@ -32,7 +33,7 @@ export interface RealtimeWaterfallChartProps<TDatum extends Record<string, any>
     /** Ring buffer capacity */
     windowSize?: number;
     /** Controlled data array */
-    data?: Record<string, any>[];
+    data?: Datum[];
     /** Time value accessor */
     timeAccessor?: ChartAccessor<TDatum, number>;
     /** Value accessor (positive = gain, negative = loss) */
@@ -57,6 +58,8 @@ export interface RealtimeWaterfallChartProps<TDatum extends Record<string, any>
     stroke?: string;
     /** Bar stroke width */
     strokeWidth?: number;
+    /** Uniform bar opacity (0–1). */
+    opacity?: number;
     /** Show canvas-drawn axes */
     showAxes?: boolean;
     /** Background fill color */
@@ -68,9 +71,9 @@ export interface RealtimeWaterfallChartProps<TDatum extends Record<string, any>
     /** Callback on hover */
     onHover?: (d: HoverData | null) => void;
     /** Annotation objects */
-    annotations?: Record<string, any>[];
+    annotations?: Datum[];
     /** SVG annotation render function */
-    svgAnnotationRules?: (annotation: Record<string, any>, index: number, context: AnnotationContext) => ReactNode;
+    svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;
     /** Custom formatter for time axis ticks */
     tickFormatTime?: (value: number) => string;
     /** Custom formatter for value axis ticks */
@@ -97,7 +100,7 @@ export interface RealtimeWaterfallChartProps<TDatum extends Record<string, any>
     /** Legend interaction mode */
     legendInteraction?: LegendInteractionMode;
     /** ID accessor for remove()/update() on the push API */
-    pointIdAccessor?: string | ((d: any) => string);
+    pointIdAccessor?: string | ((d: Datum) => string);
 }
 /**
  * RealtimeWaterfallChart - Simplified wrapper for streaming waterfall charts.
@@ -118,6 +121,6 @@ export interface RealtimeWaterfallChartProps<TDatum extends Record<string, any>
  * ```
  */
 export declare const RealtimeWaterfallChart: {
-    <TDatum extends Record<string, any> = Record<string, any>>(props: RealtimeWaterfallChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    <TDatum extends Datum = Datum>(props: RealtimeWaterfallChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
     displayName?: string;
 };

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

@@ -1,4 +1,3 @@
-import * as React from "react";
 export interface ChartErrorProps {
     /** Component name for the error message */
     componentName: string;
@@ -18,4 +17,4 @@ export interface ChartErrorProps {
  * Designed to be obvious in development but not alarming in production —
  * uses muted colors that adapt to light/dark backgrounds.
  */
-export default function ChartError({ componentName, message, diagnosticHint, width, height, }: ChartErrorProps): React.JSX.Element;
+export default function ChartError({ componentName, message, diagnosticHint, width, height, }: ChartErrorProps): import("react/jsx-runtime").JSX.Element;

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

@@ -1,3 +1,4 @@
+import type { Datum } from "./datumTypes";
 /**
  * Coordinate resolution helpers for annotations.
  *
@@ -9,15 +10,15 @@
  * Consumed by: annotationRules.tsx (all annotation type renderers)
  */
 import type { AnnotationContext } from "../../realtime/types";
-export declare function resolveX(ann: Record<string, any>, context: AnnotationContext): number | null;
-export declare function resolveY(ann: Record<string, any>, context: AnnotationContext): number | null;
+export declare function resolveX(ann: Datum, context: AnnotationContext): number | null;
+export declare function resolveY(ann: Datum, context: AnnotationContext): number | null;
 /**
  * Resolve annotation position respecting anchor mode.
  * - "fixed" (default): resolve from annotation's own fields
  * - "latest": resolve from the most recent datum in the buffer
  * - "sticky": resolve from annotation fields; if not found, use cached position
  */
-export declare function resolveAnchoredPosition(ann: Record<string, any>, index: number, context: AnnotationContext): {
+export declare function resolveAnchoredPosition(ann: Datum, index: number, context: AnnotationContext): {
     x: number;
     y: number;
 } | null;

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

@@ -1,3 +1,4 @@
 import * as React from "react";
 import type { AnnotationContext } from "../../realtime/types";
-export declare function createDefaultAnnotationRules(frameType: "xy" | "ordinal" | "network"): (annotation: Record<string, any>, index: number, context: AnnotationContext) => React.ReactNode | null;
+import type { Datum } from "./datumTypes";
+export declare function createDefaultAnnotationRules(_frameType: "xy" | "ordinal" | "network"): (annotation: Datum, index: number, context: AnnotationContext) => React.ReactNode | null;

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

@@ -1,4 +1,5 @@
 import { interpolateBlues, interpolateReds, interpolateGreens, interpolateOranges, interpolatePurples, interpolateViridis, interpolatePlasma } from "d3-scale-chromatic";
+import type { Datum } from "./datumTypes";
 /**
  * Predefined color schemes
  */
@@ -45,7 +46,7 @@ export declare const DEPTH_PALETTE_COLORS: string[];
  * getColor({value: 10}, d => d.value > 5 ? 'red' : 'blue')
  * ```
  */
-export declare function getColor(dataPoint: any, colorBy: string | ((d: any) => string), colorScale?: (v: any) => string): string;
+export declare function getColor(dataPoint: any, colorBy: string | ((d: Datum) => string), colorScale?: (v: any) => string): string;
 /**
  * Creates a color scale function from data
  *
@@ -60,7 +61,7 @@ export declare function getColor(dataPoint: any, colorBy: string | ((d: any) =>
  * const color = colorScale('A') // Returns color for category 'A'
  * ```
  */
-export declare function createColorScale(data: Array<Record<string, any>>, colorBy: string, scheme?: string | string[]): (v: string) => string;
+export declare function createColorScale(data: Array<Datum>, colorBy: string, scheme?: string | string[]): (v: string) => string;
 /**
  * Generates a size function based on sizeBy configuration
  *
@@ -70,4 +71,4 @@ export declare function createColorScale(data: Array<Record<string, any>>, color
  * @param domain - Optional domain for scaling [minValue, maxValue]
  * @returns Size value
  */
-export declare function getSize(dataPoint: any, sizeBy: string | ((d: any) => number), sizeRange?: [number, number], domain?: [number, number]): number;
+export declare function getSize(dataPoint: any, sizeBy: string | ((d: Datum) => number), sizeRange?: [number, number], domain?: [number, number]): number;

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

@@ -0,0 +1,20 @@
+/**
+ * `Datum` — the canonical "user-supplied chart data row" type.
+ *
+ * A charting library cannot know the shape of the user's data ahead of time.
+ * This alias names that intent: "an object whose field types we do not know
+ * until the user plugs in a concrete generic." Every HOC threads a
+ * `<TDatum extends Datum = Datum>` generic so accessors can autocomplete
+ * user field names when a concrete type is supplied, while still accepting
+ * arbitrary data otherwise.
+ *
+ * Why `any` (and not `unknown`) on the value side: the library and user code
+ * both do unguarded field access (`d.x`, `d[accessor]`, `...d` spreads). With
+ * `unknown`, each access would require a narrowing step that adds no runtime
+ * safety (the data is still dynamically shaped at runtime) but imposes
+ * ergonomic cost on every user accessor function and every internal pass
+ * that augments rows. The `any` in this specific alias is the single,
+ * documented, library-wide allowance; it's the "clear and established
+ * reason" referenced by the lint policy for `@typescript-eslint/no-explicit-any`.
+ */
+export type Datum = Record<string, any>;

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

@@ -1,9 +1,4 @@
-/**
- * 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.
- */
+import type { Datum } from "./datumTypes";
 export interface Diagnosis {
     severity: "error" | "warning";
     code: string;
@@ -20,4 +15,4 @@ export interface DiagnosisResult {
  * 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;
+export declare function diagnoseConfig(componentName: string, props: Datum): DiagnosisResult;

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

@@ -1,3 +1,5 @@
+import * as React from "react";
+import type { Datum } from "./datumTypes";
 /**
  * Format number with specified format string
  *
@@ -38,7 +40,7 @@ export declare function formatAxis(type?: "number" | "date" | "percent" | "curre
     decimals?: number;
     format?: string;
     currency?: string;
-}): (d: any) => string;
+}): (d: number | string | Date) => string;
 /**
  * Creates a tooltip content generator
  *
@@ -56,7 +58,7 @@ export declare function formatAxis(type?: "number" | "date" | "percent" | "curre
  * )
  * ```
  */
-export declare function createTooltip(fields: string[], formatters?: Record<string, (v: any) => string>, labels?: Record<string, string>): (d: any) => JSX.Element;
+export declare function createTooltip(fields: string[], formatters?: Record<string, (v: any) => string>, labels?: Record<string, string>): (d: Datum) => React.JSX.Element;
 /**
  * Formats large numbers with K/M/B suffixes
  *

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

@@ -2,8 +2,9 @@ import { createLegend } from "./legendUtils";
 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 { MarginType, PartialMargin } from "../../types/marginType";
 import type { TransitionConfig } from "../../stream/types";
+import type { Datum } from "./datumTypes";
 /**
  * Default fill color used when no colorBy is specified
  */
@@ -13,6 +14,17 @@ export declare const DEFAULT_COLOR = "#007bff";
  * the palette is empty. Safe to call outside a ThemeProvider (returns undefined).
  */
 export declare function useThemeCategorical(): string[] | undefined;
+/**
+ * Return the ambient theme's sequential scheme name (e.g. "blues", "viridis")
+ * for magnitude encodings. Safe to call outside a ThemeProvider (returns undefined).
+ */
+export declare function useThemeSequential(): string | undefined;
+/**
+ * Return the ambient theme's diverging scheme name (e.g. "RdBu", "PiYG")
+ * for midpoint encodings (likert, ±deviation). Safe to call outside a
+ * ThemeProvider (returns undefined).
+ */
+export declare function useThemeDiverging(): string | undefined;
 /**
  * Resolve the effective color for a data element when no colorBy is specified.
  * Priority: color prop > theme categorical > colorScheme > DEFAULT_COLOR.
@@ -23,13 +35,13 @@ export declare function resolveDefaultFill(color: string | undefined, themeCateg
  * Resolve an accessor (string key or function) into a function.
  * Used across chart components to normalize `valueAccessor`, `categoryAccessor`, etc.
  */
-export declare function resolveAccessor<T = any>(accessor: string | ((d: Record<string, any>, i?: number) => T)): (d: Record<string, any>) => T;
+export declare function resolveAccessor<T = any>(accessor: string | ((d: Datum, i?: number) => T)): (d: Datum) => T;
 /**
  * Hook to create a color scale from data and colorBy configuration.
  * Returns undefined when colorBy is absent or data is empty (push API mode).
  * Supports both string and function accessors for colorBy.
  */
-export declare function useColorScale(data: Array<Record<string, any>>, colorBy: string | ((d: any, i?: number) => any) | undefined, colorScheme?: string | string[]): ((v: string) => string) | undefined;
+export declare function useColorScale(data: Array<Datum>, 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.
@@ -43,7 +55,7 @@ export declare function useColorScale(data: Array<Record<string, any>>, colorBy:
  * makes no sense (it would call the comparator with row objects instead
  * of strings), so we decline to sort in both cases.
  */
-export declare function useSortedData(data: Array<Record<string, any>>, sort: boolean | "asc" | "desc" | "auto" | ((a: string, b: string) => number), valueAccessor: Accessor<number>): Array<Record<string, any>>;
+export declare function useSortedData(data: Array<Datum>, sort: boolean | "asc" | "desc" | "auto" | ((a: string, b: string) => number), valueAccessor: Accessor<number>): Array<Datum>;
 /**
  * Hook to set up selection and linked hover for a chart component.
  * Consolidates normalizeLinkedHover, useSelection, useLinkedHover,
@@ -52,7 +64,7 @@ export declare function useSortedData(data: Array<Record<string, any>>, sort: bo
  * @param unwrapData - Deprecated / no-op. Hover data is always unwrapped
  *   (stream frames wrap the raw datum in { data, time, value, x, y }).
  */
-export declare function useChartSelection({ selection, linkedHover, fallbackFields, unwrapData, onObservation, chartType, chartId, onClick, hoverHighlight, colorByField, }: {
+export declare function useChartSelection({ selection, linkedHover, fallbackFields, unwrapData: _unwrapData, onObservation, chartType, chartId, onClick, hoverHighlight, colorByField, }: {
     selection?: SelectionConfig;
     linkedHover?: LinkedHoverProp;
     fallbackFields?: string[];
@@ -69,8 +81,8 @@ export declare function useChartSelection({ selection, linkedHover, fallbackFiel
 }): {
     activeSelectionHook: SelectionHookResult | null;
     hoverSelectionHook: SelectionHookResult | null;
-    customHoverBehavior: (d: Record<string, any> | null) => void;
-    customClickBehavior: (d: Record<string, any> | null) => void;
+    customHoverBehavior: (d: Datum | null) => void;
+    customClickBehavior: (d: Datum | null) => void;
     /** Stable ID for this chart instance, used to suppress linked crosshair on source chart */
     crosshairSourceId: string;
 };
@@ -89,27 +101,17 @@ export declare function getCrosshairProps(linkedHover: unknown, crosshairSourceI
  */
 export type LegendPosition = "right" | "left" | "top" | "bottom";
 export declare function useChartLegendAndMargin({ data, colorBy, colorScale, showLegend, legendPosition, userMargin, defaults, categories, }: {
-    data: Array<Record<string, any>>;
+    data: Array<Datum>;
     colorBy: Accessor<string> | undefined;
     colorScale: ((v: string) => string) | undefined;
     showLegend: boolean | undefined;
     legendPosition?: LegendPosition;
-    userMargin: MarginType | undefined;
-    defaults?: {
-        top: number;
-        bottom: number;
-        left: number;
-        right: number;
-    };
+    userMargin: PartialMargin | undefined;
+    defaults?: MarginType;
     categories?: string[];
 }): {
     legend: ReturnType<typeof createLegend> | undefined;
-    margin: {
-        top: number;
-        bottom: number;
-        left: number;
-        right: number;
-    };
+    margin: MarginType;
     legendPosition: LegendPosition;
 };
 export type LegendInteractionMode = "highlight" | "isolate" | "none";
@@ -125,7 +127,7 @@ export interface LegendInteractionState {
     /** Selection predicate that dims non-matching data — use with wrapStyleWithSelection */
     legendSelectionHook: {
         isActive: boolean;
-        predicate: (d: Record<string, any>) => boolean;
+        predicate: (d: Datum) => boolean;
     } | null;
 }
 /**
@@ -137,7 +139,7 @@ export interface LegendInteractionState {
  *   `DEFAULT_SELECTION_OPACITY` fallback.
  * - "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;
+export declare function useLegendInteraction(mode: LegendInteractionMode | undefined, colorBy: string | ((d: Datum) => string) | undefined, allCategories: string[]): LegendInteractionState;
 interface ChartModeInput {
     width?: number;
     height?: number;
@@ -182,6 +184,8 @@ interface ChartModeResult {
         left: number;
         right: number;
     };
+    /** True when mode is context or sparkline — the "hide interactive chrome" union. */
+    compactMode: boolean;
 }
 /**
  * Resolve chart display mode into concrete prop defaults.

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

@@ -1,5 +1,6 @@
 import type { Accessor } from "./types";
 import type { LegendItem } from "../../types/legendTypes";
+import type { Datum } from "./datumTypes";
 /**
  * Create a legend configuration for HOC components
  *
@@ -12,10 +13,10 @@ import type { LegendItem } from "../../types/legendTypes";
  * @returns Legend configuration object for Semiotic frames
  */
 export declare function createLegend({ data, colorBy, colorScale, getColor, strokeColor, strokeWidth, categories }: {
-    data: Array<Record<string, any>>;
+    data: Array<Datum>;
     colorBy: Accessor<string>;
     colorScale?: ((v: string) => string);
-    getColor: (d: Record<string, any>, accessor: Accessor<string>, scale?: ((v: string) => string)) => string;
+    getColor: (d: Datum, accessor: Accessor<string>, scale?: ((v: string) => string)) => string;
     strokeColor?: string;
     strokeWidth?: number;
     categories?: string[];

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

@@ -0,0 +1,43 @@
+import type { Datum } from "./datumTypes";
+/**
+ * mergeShapeStyle — overlay top-level primitive styling props on a style function.
+ *
+ * Phase B of the primitive-theming plan introduces three first-class props
+ * on every shape-drawing chart: `stroke`, `strokeWidth`, `opacity` (joining
+ * `color`, which was already there). They're resolved at the HOC layer via
+ * this helper so the merge order — and precedence — lands in exactly one
+ * place for every chart type.
+ *
+ * Precedence (highest wins):
+ *   1. Top-level primitive prop (this helper's `overrides` parameter)
+ *   2. User-supplied `frameProps.*Style` return value
+ *   3. HOC base style (categorical color resolution, theme fallback, etc.)
+ *
+ * The "top-level wins over function return" rule is deliberate: explicit >
+ * generic. A user writing `<BarChart stroke="red" />` expects red strokes,
+ * even if they also pass `frameProps.pieceStyle = d => ({ stroke: "blue" })`
+ * for per-datum customization. The top-level prop is the broad stroke, the
+ * per-datum function handles the exceptions.
+ *
+ * When no overrides are set, returns the input function unchanged so
+ * `useMemo` chains upstream preserve referential equality.
+ */
+export interface PrimitiveStyleOverrides {
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+}
+type StyleFnArg = (...args: any[]) => Datum;
+/** Returns true when at least one override key has a non-undefined value. */
+export declare function hasPrimitiveOverrides(overrides: PrimitiveStyleOverrides): boolean;
+/**
+ * Overlay `overrides` on the output of `styleFn`. Returns a new style
+ * function that calls the underlying one (if present) and merges the
+ * override fields last, so top-level props win.
+ *
+ * When `overrides` has no fields set, returns `styleFn` unchanged — this
+ * keeps the memoization-stable identity path hot for the common case
+ * where a designer has set nothing.
+ */
+export declare function mergeShapeStyle<F extends StyleFnArg>(styleFn: F | undefined, overrides: PrimitiveStyleOverrides): F;
+export {};

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

@@ -1,31 +1,32 @@
+import type { Datum } from "./datumTypes";
 import type { Accessor } from "./types";
 /**
  * Flatten a hierarchical data structure into an array of all nodes
  * by recursively traversing children.
  */
-export declare function flattenHierarchy(data: Record<string, any> | null, childrenAccessor: string | ((d: any) => any[])): Array<Record<string, any>>;
+export declare function flattenHierarchy(data: Datum | null, childrenAccessor: string | ((d: Datum) => any[])): Array<Datum>;
 /**
  * Infer nodes from edges when a nodes array is not provided.
  * Extracts unique source/target IDs and returns `{ id }` objects.
  * Returns the provided nodes array if it's non-empty.
  */
-export declare function inferNodesFromEdges(nodes: any[] | undefined, edges: any[], sourceAccessor: string | ((d: any) => string), targetAccessor: string | ((d: any) => string)): Array<{
+export declare function inferNodesFromEdges(nodes: any[] | undefined, edges: any[], sourceAccessor: string | ((d: Datum) => string), targetAccessor: string | ((d: Datum) => string)): Array<{
     id: string;
 }>;
 /**
  * Convert a valueAccessor prop into a hierarchy sum function.
  * Used by TreeDiagram, Treemap, and CirclePack for d3-hierarchy's `.sum()`.
  */
-export declare function resolveHierarchySum(valueAccessor: string | ((d: any) => number)): (d: Record<string, any>) => number;
+export declare function resolveHierarchySum(valueAccessor: string | ((d: Datum) => number)): (d: Datum) => number;
 /**
  * Create an edge style function for Sankey/Chord edge coloring.
  * Handles edgeColorBy = "source" | "target" | "gradient" | function.
  */
 export declare function createEdgeStyleFn({ edgeColorBy, colorBy, colorScale, nodeStyleFn, edgeOpacity, baseStyle, }: {
-    edgeColorBy: "source" | "target" | "gradient" | ((d: any) => string);
+    edgeColorBy: "source" | "target" | "gradient" | ((d: Datum) => string);
     colorBy: Accessor<string> | undefined;
     colorScale: ((v: string) => string) | undefined;
-    nodeStyleFn: (d: any, index?: number) => Record<string, any>;
+    nodeStyleFn: (d: any, index?: number) => Datum;
     edgeOpacity: number;
     baseStyle?: Record<string, string | number>;
-}): (d: Record<string, any>) => Record<string, any>;
+}): (d: Datum) => Datum;

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

@@ -1,3 +1,4 @@
+import type { Datum } from "./datumTypes";
 /**
  * Selection integration utilities for HOC charts.
  *
@@ -41,12 +42,12 @@ export declare function normalizeLinkedBrush(prop: string | {
 } | undefined): NormalizedLinkedBrush | null;
 export interface SelectionHookResult {
     isActive: boolean;
-    predicate: (datum: Record<string, any>) => boolean;
+    predicate: (datum: Datum) => boolean;
 }
 export interface SelectionStyleConfig {
     unselectedOpacity?: number;
-    unselectedStyle?: Record<string, any>;
-    selectedStyle?: Record<string, any>;
+    unselectedStyle?: Datum;
+    selectedStyle?: Datum;
 }
 /**
  * Library fallback opacity for unselected (dimmed) elements.
@@ -65,4 +66,4 @@ export declare const DEFAULT_SELECTION_OPACITY = 0.5;
  * 1. `config.unselectedOpacity` (explicit, usually per-chart or theme-merged)
  * 2. `DEFAULT_SELECTION_OPACITY`
  */
-export declare function wrapStyleWithSelection(baseStyleFn: (d: Record<string, any>) => Record<string, any>, selectionHook: SelectionHookResult | null, config?: SelectionStyleConfig): (d: Record<string, any>) => Record<string, any>;
+export declare function wrapStyleWithSelection(baseStyleFn: (d: Datum) => Datum, selectionHook: SelectionHookResult | null, config?: SelectionStyleConfig): (d: Datum) => Datum;

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

@@ -1,16 +1,4 @@
-/**
- * Statistical overlay processing for LineChart.
- *
- * Two modes:
- *   **Auto mode** — provide `trainEnd` + optional `steps`/`confidence`.
- *     The module computes regression, generates forecast points, and builds
- *     annotations (envelope, anomaly band, boundary line).
- *
- *   **Pre-computed mode** — provide field accessors (`isTraining`, `isForecast`,
- *     `isAnomaly`, `upperBounds`, `lowerBounds`). The module reads segment/bounds
- *     from the data and generates annotations without any statistical computation.
- *     Use this when bounds come from an external ML model.
- */
+import type { Datum } from "./datumTypes";
 export interface AnomalyConfig {
     /** Standard deviation multiplier for anomaly bounds. Default: 2 */
     threshold?: number;
@@ -39,15 +27,15 @@ export interface ForecastConfig {
     /** Confidence level for prediction interval (0-1). Default: 0.95 */
     confidence?: number;
     /** Field or function marking training data points */
-    isTraining?: string | ((d: Record<string, any>) => boolean);
+    isTraining?: string | ((d: Datum) => boolean);
     /** Field or function marking forecast data points */
-    isForecast?: string | ((d: Record<string, any>) => boolean);
+    isForecast?: string | ((d: Datum) => boolean);
     /** Field or function marking anomalous data points */
-    isAnomaly?: string | ((d: Record<string, any>) => boolean);
+    isAnomaly?: string | ((d: Datum) => boolean);
     /** Field or function for upper envelope bound per data point */
-    upperBounds?: string | ((d: Record<string, any>) => number);
+    upperBounds?: string | ((d: Datum) => number);
     /** Field or function for lower envelope bound per data point */
-    lowerBounds?: string | ((d: Record<string, any>) => number);
+    lowerBounds?: string | ((d: Datum) => number);
     /** Color for forecast line and envelope. Default: "#6366f1" */
     color?: string;
     /** Envelope fill opacity. Default: 0.15 */
@@ -82,19 +70,19 @@ export interface ForecastConfig {
      * - `string`: fixed color (default: "#ef4444")
      * - `(datum) => string`: per-datum color function
      */
-    anomalyColor?: string | ((datum: Record<string, any>) => string);
+    anomalyColor?: string | ((datum: Datum) => string);
     /**
      * Outlier dot radius.
      * - `number`: fixed radius (default: 6)
      * - `(datum) => number`: per-datum radius function (e.g. for count-based sizing)
      */
-    anomalyRadius?: number | ((datum: Record<string, any>) => number);
+    anomalyRadius?: number | ((datum: Datum) => number);
     /**
      * Full style override for anomaly dots.
      * When provided as a function, receives the datum and should return a CSS style object.
      * Overrides `anomalyColor` when provided.
      */
-    anomalyStyle?: Record<string, any> | ((datum: Record<string, any>) => Record<string, any>);
+    anomalyStyle?: Datum | ((datum: Datum) => Datum);
     /**
      * Internal: field name used to group data into separate lines (e.g. "metricLabel").
      * When set, boundary point duplication only bridges within the same group,
@@ -109,11 +97,11 @@ export interface ForecastConfig {
 /** Internal segment marker added to each datum */
 export declare const SEGMENT_FIELD: "__forecastSegment";
 export type SegmentType = "training" | "training-base" | "observed" | "forecast";
-export declare function buildAnomalyAnnotations(config: AnomalyConfig): Record<string, any>[];
+export declare function buildAnomalyAnnotations(config: AnomalyConfig): Datum[];
 export interface ForecastResult {
-    processedData: Record<string, any>[];
-    annotations: Record<string, any>[];
+    processedData: Datum[];
+    annotations: Datum[];
 }
-export declare function buildForecast(data: Record<string, any>[], xAccessor: string, yAccessor: string, forecastConfig: ForecastConfig, anomalyConfig?: AnomalyConfig): ForecastResult;
+export declare function buildForecast(data: Datum[], xAccessor: string, yAccessor: string, forecastConfig: ForecastConfig, anomalyConfig?: AnomalyConfig): ForecastResult;
 export { darkenColor, lightenColor } from "./colorManipulation";
-export declare function createSegmentLineStyle(baseStyle: (d: Record<string, any>) => Record<string, any>, forecastConfig: ForecastConfig): (d: Record<string, any>) => Record<string, any>;
+export declare function createSegmentLineStyle(baseStyle: (d: Datum) => Datum, forecastConfig: ForecastConfig): (d: Datum) => Datum;