semiotic 3.3.1 → 3.4.1

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,18 +35,27 @@ 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.
+ *
+ * `"auto"` and function comparators are pass-through here. The frame-
+ * level `resolveCategories` decides the visual category order:
+ *   • `"auto"` → insertion order when streaming, value-desc when static.
+ *   • function → runs as a category-key comparator on the axis list.
+ * The HOC's row-level `data` order only seeds insertion order via the
+ * store's category Set; rearranging rows with a category comparator
+ * 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" | ((a: Record<string, any>, b: Record<string, any>) => 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,
@@ -43,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[];
@@ -60,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;
 };
@@ -80,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";
@@ -116,15 +127,19 @@ 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;
 }
 /**
  * Hook managing legend highlight/isolate interaction.
- * - "highlight": hover over legend item dims everything else to 30% opacity
+ * - "highlight": hover over a legend item produces a selection hook that
+ *   `wrapStyleWithSelection` uses to dim non-matching data. The actual
+ *   dim opacity resolves in this order: per-chart
+ *   `selection.unselectedOpacity` → `theme.colors.selectionOpacity` →
+ *   `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;
@@ -169,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,26 +42,28 @@ 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;
 }
-/** Default opacity for unselected (dimmed) elements */
-export declare const DEFAULT_SELECTION_OPACITY = 0.2;
 /**
- * Read the --semiotic-selection-opacity CSS variable from a container element.
- * Returns the numeric value or the default if not set or not parseable.
+ * Library fallback opacity for unselected (dimmed) elements.
+ *
+ * This is the last-resort value when nothing else supplies one. Clients
+ * control the effective default declaratively through `ThemeProvider`'s
+ * `colors.selectionOpacity` (built-in presets set this). Per-chart
+ * `selection.unselectedOpacity` still overrides the theme value.
  */
-export declare function readSelectionOpacityFromCSS(container: Element | null): number;
+export declare const DEFAULT_SELECTION_OPACITY = 0.5;
 /**
  * Wrap a base style function with selection awareness.
  * When a selection is active, non-matching datums get dimmed.
  *
  * Dimming opacity is resolved in this order:
- * 1. `config.unselectedOpacity` (explicit prop)
- * 2. `DEFAULT_SELECTION_OPACITY` (0.2)
+ * 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;

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

@@ -6,5 +6,5 @@ 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>>;
+export declare function buildAnomalyAnnotationsLazy(...args: Parameters<typeof import("./statisticalOverlays")["buildAnomalyAnnotations"]>): Promise<import("./datumTypes").Datum[]>;
+export declare function createSegmentLineStyleLazy(...args: Parameters<typeof import("./statisticalOverlays")["createSegmentLineStyle"]>): Promise<(d: import("./datumTypes").Datum) => import("./datumTypes").Datum>;

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

@@ -1,3 +1,4 @@
+import type { Datum } from "./datumTypes";
 import * as React from "react";
 /**
  * Shared tooltip for distribution charts (BoxPlot, ViolinPlot, RidgelinePlot).
@@ -7,5 +8,5 @@ import * as React from "react";
  */
 export declare function buildStatsTooltip(options?: {
     /** If provided, computes fallback stats from raw data when d.stats is missing */
-    valueAccessor?: string | ((d: any) => number);
-}): (d: Record<string, any>) => React.ReactElement;
+    valueAccessor?: string | ((d: Datum) => number);
+}): (d: Datum) => React.ReactElement;

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

@@ -1,17 +1,26 @@
 import * as React from "react";
 import type { HoverData } from "../../realtime/types";
+import type { Datum } from "./datumTypes";
 export interface TooltipFieldConfig {
     label: string;
     accessor: string | ((d: any) => any);
     role?: "title" | "x" | "y" | "color" | "size" | "group" | "value";
+    /** Per-field formatter. HOCs pass `xFormat`/`yFormat`/`valueFormat` here so
+     *  the default tooltip renders values consistently with the axis. Typed
+     *  permissively (`any` → `ReactNode`) to match the mixed formatter
+     *  signatures across ordinal (`(d: string | number) => string`) and XY
+     *  (`(d, index?, allTicks?) => ReactNode`). A ReactNode return renders
+     *  as-is in the tooltip span. If the formatter throws, the tooltip
+     *  falls back to the built-in `formatVal`. */
+    format?: (v: any, ...rest: any[]) => React.ReactNode;
 }
 /**
  * Extract a display name from an accessor.
  * Strings return themselves; functions return "value".
  */
-export declare function accessorName(acc: string | Function): string;
+export declare function accessorName(acc: string | ((...args: any[]) => any)): string;
 export declare function formatVal(v: unknown): string;
-export declare function resolveValue(d: Record<string, any>, acc: string | ((d: Record<string, any>) => any)): unknown;
+export declare function resolveValue(d: Datum, acc: string | ((d: Datum) => any)): unknown;
 /**
  * Build a default tooltipContent function for StreamXYFrame HOCs.
  * Receives HoverData ({ data, time, value, x, y }) and renders
@@ -25,10 +34,14 @@ export declare function buildDefaultTooltip(fields: TooltipFieldConfig[]): (hove
  * @param pieData - If true, extracts datum via `d.data?.[0] || d.data || d`
  *   (PieChart/DonutChart wrap data in arrays). Default: `d.data || d`.
  */
-export declare function buildOrdinalTooltip({ categoryAccessor, valueAccessor, groupAccessor, groupLabel, pieData, }: {
-    categoryAccessor: string | ((d: any) => any);
-    valueAccessor: string | ((d: any) => any);
-    groupAccessor?: string | ((d: any) => any);
+export declare function buildOrdinalTooltip({ categoryAccessor, valueAccessor, groupAccessor, groupLabel, pieData, valueFormat, }: {
+    categoryAccessor: string | ((d: Datum) => any);
+    valueAccessor: string | ((d: Datum) => any);
+    groupAccessor?: string | ((d: Datum) => any);
     groupLabel?: string;
     pieData?: boolean;
-}): (d: Record<string, any>) => React.ReactNode;
+    /** Same formatter the HOC passes to the value axis. Threaded here so the
+     *  default tooltip shows values consistently with the axis ("$450k", not
+     *  "450000"). Override by passing a custom `tooltip` prop. */
+    valueFormat?: (v: any, ...rest: any[]) => React.ReactNode;
+}): (d: Datum) => React.ReactNode;

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

@@ -1,6 +1,8 @@
 import type React from "react";
-import type { MarginType } from "../../types/generalTypes";
+import type { PartialMargin } from "../../types/marginType";
 import type { OnObservationCallback } from "../../store/ObservationStore";
+import type { AnimateProp } from "../../stream/pipelineTransitionUtils";
+import type { Datum } from "./datumTypes";
 /**
  * Selection consumption config — makes this chart react to a named selection
  */
@@ -10,9 +12,9 @@ export interface SelectionConfig {
     /** Opacity for unselected elements (default 0.2) */
     unselectedOpacity?: number;
     /** Style overrides for unselected elements */
-    unselectedStyle?: Record<string, any>;
+    unselectedStyle?: Datum;
     /** Style overrides for selected elements */
-    selectedStyle?: Record<string, any>;
+    selectedStyle?: Datum;
 }
 /**
  * Linked hover config
@@ -51,8 +53,10 @@ export interface BaseChartProps {
     width?: number;
     /** Chart height in pixels. Default: 400 */
     height?: number;
-    /** Margin around the chart. Can be number (same on all sides) or object specifying each side */
-    margin?: MarginType;
+    /** Margin around the chart. Accepts a number (same on all sides) or an object
+     *  with any subset of `top`/`bottom`/`left`/`right`. Missing sides fall back
+     *  to the chart-mode defaults. */
+    margin?: PartialMargin;
     /** Auto-match width to parent container. Default: false */
     responsiveWidth?: boolean;
     /** Auto-match height to parent container (requires parent with explicit height). Default: false */
@@ -79,6 +83,12 @@ export interface BaseChartProps {
     /** Uniform fill color for all data marks. Overrides colorScheme and theme categorical.
      * For per-category coloring, use `colorBy` + `colorScheme` instead. */
     color?: string;
+    /** Uniform stroke color for all data marks. Accepts a CSS variable. */
+    stroke?: string;
+    /** Uniform stroke width in pixels. */
+    strokeWidth?: number;
+    /** Uniform opacity for all data marks (0–1). Distinct from `--semiotic-selection-opacity` which only dims non-selected marks. */
+    opacity?: number;
     /** Accessible description overriding the auto-generated aria-label on the chart container.
      * Should describe the chart's purpose or content for screen reader users. */
     description?: string;
@@ -98,17 +108,15 @@ export interface BaseChartProps {
     /** Max pixel distance for hover/click hit testing. Default 30. Increase for sparse charts, decrease for dense ones. */
     hoverRadius?: number;
     /** ID accessor for remove()/update() on XY charts. Extracts a unique identifier from each datum. */
-    pointIdAccessor?: string | ((d: any) => string);
+    pointIdAccessor?: string | ((d: Datum) => string);
     /** ID accessor for remove()/update() on ordinal charts. Extracts a unique identifier from each datum. */
-    dataIdAccessor?: string | ((d: any) => string);
+    dataIdAccessor?: string | ((d: Datum) => string);
     /** 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";
-    };
+    /** Enable declarative bounded animation (enter/exit/update transitions + intro).
+     * `true` uses defaults (300ms ease-out, intro enabled). Object form allows customization.
+     * Set `{ intro: false }` to disable the animated intro on first render. */
+    animate?: AnimateProp;
 }
 /**
  * Axis configuration props
@@ -119,9 +127,9 @@ export interface AxisConfig {
     /** Label for the y-axis */
     yLabel?: string;
     /** Format function for x-axis tick labels. Return string or ReactNode for custom rendering. */
-    xFormat?: (d: any, index?: number, allTicks?: number[]) => string | React.ReactNode;
+    xFormat?: (d: number | Date | string, index?: number, allTicks?: number[]) => string | React.ReactNode;
     /** Format function for y-axis tick labels. Return string or ReactNode for custom rendering. */
-    yFormat?: (d: any) => string | React.ReactNode;
+    yFormat?: (d: number | Date | string) => string | React.ReactNode;
 }
 /**
  * Category formatting for ordinal chart tick labels.
@@ -135,14 +143,14 @@ export type CategoryFormatFn = (label: string, index?: number) => string | React
 export type Accessor<T = any> = string | ((d: any, i?: number) => T);
 /**
  * Generic accessor type that provides autocomplete when TDatum is specified.
- * Uses Record<string, any> in the function param so HOC charts can pass
+ * Uses Datum in the function param so HOC charts can pass
  * accessors to Stream Frames without contravariance errors under strict mode.
  */
-export type ChartAccessor<TDatum, T> = (keyof TDatum & string) | ((d: Record<string, any>, i?: number) => T);
+export type ChartAccessor<TDatum, T> = (keyof TDatum & string) | ((d: Datum, i?: number) => T);
 /**
  * Color configuration
  */
-export interface ColorConfig<TDatum = Record<string, any>> {
+export interface ColorConfig<TDatum = Datum> {
     /** Field name or function to determine color */
     colorBy?: ChartAccessor<TDatum, string>;
     /** Color scheme name (e.g., "blues", "category10") */
@@ -153,7 +161,7 @@ export interface ColorConfig<TDatum = Record<string, any>> {
 /**
  * Size configuration
  */
-export interface SizeConfig<TDatum = Record<string, any>> {
+export interface SizeConfig<TDatum = Datum> {
     /** Field name or function to determine size */
     sizeBy?: ChartAccessor<TDatum, number>;
     /** Min and max size range */

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

@@ -1,8 +1,9 @@
+import type { Datum } from "./datumTypes";
 import { useChartLegendAndMargin, useLegendInteraction, DEFAULT_COLOR } from "./hooks";
 import type { LegendInteractionMode, LegendPosition } from "./hooks";
 import type { Accessor, SelectionConfig, LinkedHoverProp } from "./types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
-import type { MarginType } from "../../types/generalTypes";
+import type { PartialMargin } from "../../types/marginType";
 import type { SelectionHookResult } from "./selectionUtils";
 import type { ReactElement, ReactNode } from "react";
 /**
@@ -14,7 +15,7 @@ import type { ReactElement, ReactNode } from "react";
  */
 export interface ChartSetupInput {
     /** The data array used for color scale and category extraction */
-    data: Array<Record<string, any>>;
+    data: Array<Datum>;
     /** The original data prop (may be undefined) — used for empty-state check */
     rawData: unknown[] | undefined;
     /** The color-by accessor (may be an "actual" colorBy derived from stackBy/groupBy/categoryAccessor) */
@@ -42,7 +43,7 @@ export interface ChartSetupInput {
     /** Show legend override */
     showLegend: boolean | undefined;
     /** User-provided margin */
-    userMargin: MarginType | undefined;
+    userMargin: PartialMargin | undefined;
     /** Mode-resolved margin defaults */
     marginDefaults: {
         top: number;
@@ -81,9 +82,9 @@ export interface ChartSetupResult {
     /** The active cross-chart selection hook (before legend merge) */
     activeSelectionHook: SelectionHookResult | null;
     /** Custom hover behavior callback for the frame */
-    customHoverBehavior: (d: Record<string, any> | null) => void;
+    customHoverBehavior: (d: Datum | null) => void;
     /** Custom click behavior callback for the frame */
-    customClickBehavior: (d: Record<string, any> | null) => void;
+    customClickBehavior: (d: Datum | null) => void;
     /** Legend config (or undefined if no legend) */
     legend: ReturnType<typeof useChartLegendAndMargin>["legend"];
     /** Computed margin with legend-aware adjustments */
@@ -98,12 +99,20 @@ export interface ChartSetupResult {
     /** If non-null, the HOC should return this element (loading or empty state) */
     earlyReturn: ReactElement | null;
     /** Props to spread into the stream frame for legend behavior */
-    legendBehaviorProps: Record<string, any>;
+    legendBehaviorProps: Datum;
     /** Crosshair props to spread into StreamXYFrame when linkedHover mode is "x-position" */
     crosshairProps: {
         linkedCrosshairName: string;
         linkedCrosshairSourceId: string;
     } | undefined;
+    /**
+     * Selection config merged with theme-level defaults. HOCs should pass this
+     * to `wrapStyleWithSelection` instead of the raw `selection` prop so that
+     * the current theme's `colors.selectionOpacity` becomes the effective
+     * unselected-opacity fallback. Per-chart `selection.unselectedOpacity`
+     * still takes priority over the theme value.
+     */
+    resolvedSelection: SelectionConfig | undefined;
 }
 /**
  * Hook that consolidates the shared boilerplate across all HOC charts: