semiotic 3.1.2 → 3.2.1

package/dist/components/charts/ordinal/SwimlaneChart.d.ts

@@ -0,0 +1,65 @@
+import * as React from "react";
+import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
+import type { LegendInteractionMode } from "../shared/hooks";
+import type { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { RealtimeFrameHandle } from "../../realtime/types";
+export interface SwimlaneChartProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
+    /** Data array. Omit for push API mode. */
+    data?: TDatum[];
+    /** Accessor for lane categories (swim lanes). Default "category". */
+    categoryAccessor?: ChartAccessor<TDatum, string>;
+    /** Accessor for item subcategory (color grouping within lanes). Required. */
+    subcategoryAccessor: ChartAccessor<TDatum, string>;
+    /** Accessor for item size/duration. Default "value". */
+    valueAccessor?: ChartAccessor<TDatum, number>;
+    /** Orientation: "horizontal" renders lanes as rows (default), "vertical" as columns. */
+    orientation?: "vertical" | "horizontal";
+    /** Label for the category axis */
+    categoryLabel?: string;
+    /** Label for the value axis */
+    valueLabel?: string;
+    /** Format function for value axis ticks */
+    valueFormat?: (d: number | string) => string;
+    /** Color accessor — defaults to subcategoryAccessor */
+    colorBy?: ChartAccessor<TDatum, string>;
+    /** Color scheme for subcategories */
+    colorScheme?: string | string[];
+    /** Padding between lanes in pixels */
+    barPadding?: number;
+    /** Enable hover annotations */
+    enableHover?: boolean;
+    /** Show grid lines */
+    showGrid?: boolean;
+    /** Show category axis tick labels */
+    showCategoryTicks?: boolean;
+    /** Show legend */
+    showLegend?: boolean;
+    /** Legend interaction mode */
+    legendInteraction?: LegendInteractionMode;
+    /** Legend position */
+    legendPosition?: "right" | "left" | "top" | "bottom";
+    /** Tooltip configuration */
+    tooltip?: TooltipProp;
+    /** Annotation objects */
+    annotations?: Record<string, any>[];
+    /** Enable brush on the value axis */
+    brush?: boolean;
+    /** Callback when brush selection changes */
+    onBrush?: (extent: {
+        r: [number, number];
+    } | null) => void;
+    /** LinkedCharts brush integration */
+    linkedBrush?: string | {
+        name: string;
+        rField?: string;
+    };
+    /** Custom formatter for category tick labels */
+    categoryFormat?: CategoryFormatFn;
+    /** Pass-through props to StreamOrdinalFrame */
+    frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
+}
+export declare const SwimlaneChart: {
+    <TDatum extends Record<string, any> = Record<string, any>>(props: SwimlaneChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

package/dist/components/charts/ordinal/ViolinPlot.d.ts

@@ -1,7 +1,7 @@
 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 { LegendInteractionMode, LegendPosition } from "../shared/hooks";
+import type { BaseChartProps, ChartAccessor, CategoryFormatFn } 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 {
@@ -20,10 +20,25 @@ export interface ViolinPlotProps<TDatum extends Record<string, any> = Record<str
     categoryPadding?: number;
     enableHover?: boolean;
     showGrid?: boolean;
+    showCategoryTicks?: boolean;
     showLegend?: boolean;
+    legendInteraction?: LegendInteractionMode;
     legendPosition?: LegendPosition;
     tooltip?: TooltipProp;
     annotations?: Record<string, any>[];
+    /** Enable brush on the value axis */
+    brush?: boolean;
+    /** Callback when brush selection changes */
+    onBrush?: (extent: {
+        r: [number, number];
+    } | null) => void;
+    /** LinkedCharts brush integration */
+    linkedBrush?: string | {
+        name: string;
+        rField?: string;
+    };
+    /** Custom formatter for category tick labels */
+    categoryFormat?: CategoryFormatFn;
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 export declare const ViolinPlot: {

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

@@ -102,6 +102,26 @@ export interface RealtimeTemporalHistogramProps<TDatum extends Record<string, an
     loading?: boolean;
     /** Custom content to render when data is empty. Set to `false` to disable empty state. */
     emptyContent?: ReactNode | false;
+    /** Brush configuration. `true` defaults to `{ dimension: "x", snap: "bin" }`. */
+    brush?: boolean | "x" | {
+        dimension?: "x" | "y" | "xy";
+        snap?: "continuous" | "bin";
+        /** Actual bin boundary values for data-driven snapping (auto-populated from histogram bins when omitted) */
+        binBoundaries?: number[];
+        /** When true, snap during drag (not just on release). Default false. */
+        snapDuring?: boolean;
+    };
+    /** Callback when brush selection changes. Called with data-space extent, or null when cleared. */
+    onBrush?: (extent: {
+        x: [number, number];
+        y: [number, number];
+    } | null) => void;
+    /** Linked brush for cross-chart coordination via LinkedCharts */
+    linkedBrush?: string | {
+        name: string;
+        xField?: string;
+        yField?: string;
+    };
     /** Visual emphasis level for dashboard hierarchy. "primary" spans two columns in ChartGrid. */
     emphasis?: "primary" | "secondary";
     /** Show a legend */

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

@@ -0,0 +1,28 @@
+/**
+ * Coordinate resolution helpers for annotations.
+ *
+ * Resolves data coordinates to pixel positions, respecting anchor modes
+ * (fixed, latest, sticky), pointId matching, and bounds checking for
+ * streaming charts where data scrolls off-screen.
+ *
+ * Dependencies: types (AnnotationContext)
+ * 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;
+/**
+ * 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): {
+    x: number;
+    y: number;
+} | null;
+/**
+ * Returns true if a point annotation is within the visible chart area.
+ * Used to hide data-anchored annotations that have scrolled off-screen.
+ */
+export declare function isInBounds(px: number, py: number, context: AnnotationContext, margin?: number): boolean;

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

@@ -0,0 +1,15 @@
+/**
+ * Lightweight color manipulation helpers.
+ * Extracted from statisticalOverlays to avoid pulling the heavy module
+ * into the main barrel import graph.
+ */
+/**
+ * Darken a CSS hex color by a factor (0–1). factor=0.5 darkens by 50%.
+ * Returns the original string unchanged if it's not a valid hex color.
+ */
+export declare function darkenColor(hex: string, factor?: number): string;
+/**
+ * Lighten a CSS hex color by a factor (0–1). factor=0.5 lightens by 50%.
+ * Returns the original string unchanged if it's not a valid hex color.
+ */
+export declare function lightenColor(hex: string, factor?: number): string;

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

@@ -84,6 +84,33 @@ export declare function formatLargeNumber(value: number, decimals?: number): str
  * Used as the default axis tickFormat when no explicit format is provided.
  */
 export declare function smartTickFormat(value: any): string;
+type TimeGranularity = "seconds" | "minutes" | "hours" | "days" | "months" | "years";
+/**
+ * Creates a hierarchical time axis formatter.
+ *
+ * The first tick is fully qualified (e.g., "Mar 24, 2026 14:33:52").
+ * Subsequent ticks show only the significant unit change (e.g., ":53").
+ * When a time boundary is crossed (new minute, hour, day, etc.), the
+ * label re-qualifies up to that boundary (e.g., "14:34:00").
+ *
+ * Designed to be passed as `xFormat` on any Semiotic XY chart.
+ * Uses the extended `(value, index, allTicks)` signature.
+ *
+ * @param granularity - Optional explicit granularity. If omitted,
+ *   auto-detected from the tick spacing on first call.
+ *
+ * @example
+ * ```tsx
+ * import { adaptiveTimeTicks } from "semiotic"
+ *
+ * // Auto-detect granularity from the data
+ * <LineChart data={ts} xFormat={adaptiveTimeTicks()} />
+ *
+ * // Explicit granularity
+ * <LineChart data={ts} xFormat={adaptiveTimeTicks("minutes")} />
+ * ```
+ */
+export declare function adaptiveTimeTicks(granularity?: TimeGranularity): (value: any, index?: number, allTicks?: number[]) => string;
 /**
  * Truncates text to specified length with ellipsis
  *
@@ -92,3 +119,4 @@ export declare function smartTickFormat(value: any): string;
  * @returns Truncated text
  */
 export declare function truncateText(text: string, maxLength?: number): string;
+export {};

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

@@ -0,0 +1,35 @@
+/**
+ * Create a diagonal-line hatch CanvasPattern for use as a fill style.
+ *
+ * Returns a CanvasPattern that can be passed as `fill` in any pieceStyle,
+ * nodeStyle, or edgeStyle function. Works with all canvas-rendered charts.
+ *
+ * @example
+ * ```tsx
+ * const hatch = createHatchPattern({ background: "#4e79a7", stroke: "#fff" })
+ * <BarChart
+ *   pieceStyle={(d) => ({ fill: d.projected ? hatch : "#4e79a7" })}
+ * />
+ * ```
+ */
+export interface HatchPatternOptions {
+    /** Background color of the pattern tile */
+    background?: string;
+    /** Color of the diagonal lines */
+    stroke?: string;
+    /** Width of the diagonal lines in pixels @default 1.5 */
+    lineWidth?: number;
+    /** Spacing between lines in pixels @default 6 */
+    spacing?: number;
+    /** Angle of the lines in degrees (0 = horizontal, 45 = diagonal) @default 45 */
+    angle?: number;
+}
+/**
+ * Create a repeating diagonal-line hatch pattern for canvas fills.
+ *
+ * Must be called in a browser environment (needs canvas). Returns null
+ * in server/test environments where canvas is unavailable.
+ */
+export declare function createHatchPattern(options?: HatchPatternOptions, 
+/** Optional target canvas to create the pattern on (for correct DPR scaling) */
+targetCtx?: CanvasRenderingContext2D): CanvasPattern | null;

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

@@ -8,6 +8,17 @@ import type { TransitionConfig } from "../../stream/types";
  * Default fill color used when no colorBy is specified
  */
 export declare const DEFAULT_COLOR = "#007bff";
+/**
+ * Returns the theme's categorical palette, or undefined if no ThemeProvider or
+ * the palette is empty. Safe to call outside a ThemeProvider (returns undefined).
+ */
+export declare function useThemeCategorical(): string[] | undefined;
+/**
+ * Resolve the effective color for a data element when no colorBy is specified.
+ * Priority: color prop > theme categorical > colorScheme > DEFAULT_COLOR.
+ * When a palette is available, cycles through colors by category name.
+ */
+export declare function resolveDefaultFill(color: string | undefined, themeCategorical: string[] | undefined, colorScheme: string | string[] | undefined, category: string | undefined, categoryIndexMap: Map<string, number>): string;
 /**
  * Resolve an accessor (string key or function) into a function.
  * Used across chart components to normalize `valueAccessor`, `categoryAccessor`, etc.
@@ -15,7 +26,8 @@ export declare const DEFAULT_COLOR = "#007bff";
 export declare function resolveAccessor<T = any>(accessor: string | ((d: Record<string, any>, i?: number) => T)): (d: Record<string, any>) => T;
 /**
  * Hook to create a color scale from data and colorBy configuration.
- * Returns undefined when colorBy is absent or is a function accessor.
+ * 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;
 /**
@@ -31,7 +43,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, }: {
+export declare function useChartSelection({ selection, linkedHover, fallbackFields, unwrapData, onObservation, chartType, chartId, onClick, }: {
     selection?: SelectionConfig;
     linkedHover?: LinkedHoverProp;
     fallbackFields?: string[];
@@ -39,18 +51,32 @@ export declare function useChartSelection({ selection, linkedHover, fallbackFiel
     onObservation?: OnObservationCallback;
     chartType?: string;
     chartId?: string;
+    onClick?: (datum: any, event: {
+        x: number;
+        y: number;
+    }) => void;
 }): {
     activeSelectionHook: SelectionHookResult | null;
     customHoverBehavior: (d: Record<string, any> | null) => void;
     customClickBehavior: (d: Record<string, any> | null) => void;
+    /** Stable ID for this chart instance, used to suppress linked crosshair on source chart */
+    crosshairSourceId: string;
 };
+/**
+ * Compute crosshair props for StreamXYFrame from linkedHover config.
+ * Returns undefined when linkedHover is not in x-position mode.
+ */
+export declare function getCrosshairProps(linkedHover: unknown, crosshairSourceId: string): {
+    linkedCrosshairName: string;
+    linkedCrosshairSourceId: string;
+} | undefined;
 /**
  * Hook to create a legend and compute margins with legend-aware adjustment.
  * Consolidates the shouldShowLegend / createLegend / margin merge / right-margin
  * expansion pattern that every chart with color encoding repeats.
  */
 export type LegendPosition = "right" | "left" | "top" | "bottom";
-export declare function useChartLegendAndMargin({ data, colorBy, colorScale, showLegend, legendPosition, userMargin, defaults, }: {
+export declare function useChartLegendAndMargin({ data, colorBy, colorScale, showLegend, legendPosition, userMargin, defaults, categories, }: {
     data: Array<Record<string, any>>;
     colorBy: Accessor<string> | undefined;
     colorScale: ((v: string) => string) | undefined;
@@ -63,6 +89,7 @@ export declare function useChartLegendAndMargin({ data, colorBy, colorScale, sho
         left: number;
         right: number;
     };
+    categories?: string[];
 }): {
     legend: ReturnType<typeof createLegend> | undefined;
     margin: {
@@ -102,7 +129,13 @@ interface ChartModeInput {
     enableHover?: boolean;
     showLegend?: boolean;
     showLabels?: boolean;
+    showCategoryTicks?: boolean;
+    /** "vertical" | "horizontal" — used to shrink the category-axis margin when showCategoryTicks is false */
+    orientation?: string;
     title?: string;
+    description?: string;
+    summary?: string;
+    accessibleTable?: boolean;
     xLabel?: string;
     yLabel?: string;
     categoryLabel?: string;
@@ -119,6 +152,9 @@ interface ChartModeResult {
     showLegend: boolean | undefined;
     showLabels: boolean | undefined;
     title: string | undefined;
+    description: string | undefined;
+    summary: string | undefined;
+    accessibleTable: boolean | undefined;
     xLabel: string | undefined;
     yLabel: string | undefined;
     categoryLabel: string | undefined;

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

@@ -11,13 +11,14 @@ import type { LegendItem } from "../../types/legendTypes";
  * @param strokeWidth - Optional stroke width for legend items
  * @returns Legend configuration object for Semiotic frames
  */
-export declare function createLegend({ data, colorBy, colorScale, getColor, strokeColor, strokeWidth }: {
+export declare function createLegend({ data, colorBy, colorScale, getColor, strokeColor, strokeWidth, categories }: {
     data: Array<Record<string, any>>;
     colorBy: Accessor<string>;
     colorScale?: ((v: string) => string);
     getColor: (d: Record<string, any>, accessor: Accessor<string>, scale?: ((v: string) => string)) => string;
     strokeColor?: string;
     strokeWidth?: number;
+    categories?: string[];
 }): {
     legendGroups: {
         styleFn: (d: LegendItem) => Record<string, string | number>;

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

@@ -7,6 +7,8 @@
 export interface NormalizedLinkedHover {
     name: string;
     fields: string[];
+    mode?: "field" | "x-position";
+    xField?: string;
 }
 export interface NormalizedLinkedBrush {
     name: string;
@@ -22,7 +24,9 @@ export interface NormalizedLinkedBrush {
  */
 export declare function normalizeLinkedHover(prop: boolean | string | {
     name?: string;
-    fields: string[];
+    fields?: string[];
+    mode?: "field" | "x-position";
+    xField?: string;
 } | undefined, fallbackFields?: string[]): NormalizedLinkedHover | null;
 /**
  * Normalize the linkedBrush prop into a consistent config object.
@@ -44,8 +48,19 @@ export interface SelectionStyleConfig {
     unselectedStyle?: Record<string, any>;
     selectedStyle?: Record<string, any>;
 }
+/** 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.
+ */
+export declare function readSelectionOpacityFromCSS(container: Element | null): number;
 /**
  * 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)
  */
 export declare function wrapStyleWithSelection(baseStyleFn: (d: Record<string, any>) => Record<string, any>, selectionHook: SelectionHookResult | null, config?: SelectionStyleConfig): (d: Record<string, any>) => Record<string, any>;

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

@@ -56,20 +56,64 @@ export interface ForecastConfig {
     trainDasharray?: string;
     /** Dash pattern for forecast line segment. Default: "4,4" */
     forecastDasharray?: string;
-    /** Outlier dot color (pre-computed mode). Default: "#ef4444" */
-    anomalyColor?: string;
-    /** Outlier dot radius (pre-computed mode). Default: 6 */
-    anomalyRadius?: number;
+    /** Stroke opacity for the training line segment (0–1). Default: 1 */
+    trainOpacity?: number;
+    /** Stroke opacity for the forecast line segment (0–1). Default: 1 */
+    forecastOpacity?: number;
+    /**
+     * Training line stroke color.
+     * - `"darken"`: auto-darken the line's own color by 50% (hex colors only —
+     *   non-hex values like `rgb()` or CSS variables pass through unchanged).
+     * - Any CSS color string: use that color explicitly.
+     * - Omit to inherit the line's color unchanged.
+     */
+    trainStroke?: string;
+    /** Training line linecap (e.g. "round"). Default: inherits from base style */
+    trainLinecap?: string;
+    /**
+     * Render a solid underline beneath the dashed training line.
+     * - `true`: solid line in the base (or lightened) color beneath the dashed training line
+     * - `"lighten"`: solid line in a 40% lightened version of the line's color
+     * - Omit or `false`: no underline (default)
+     */
+    trainUnderline?: boolean | "lighten";
+    /**
+     * Outlier dot color.
+     * - `string`: fixed color (default: "#ef4444")
+     * - `(datum) => string`: per-datum color function
+     */
+    anomalyColor?: string | ((datum: Record<string, any>) => 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);
+    /**
+     * 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>);
+    /**
+     * Internal: field name used to group data into separate lines (e.g. "metricLabel").
+     * When set, boundary point duplication only bridges within the same group,
+     * preventing cross-metric stray lines. Set automatically by LineChart when
+     * both lineBy and forecast are active.
+     * @internal
+     */
+    _groupBy?: string;
     /** Label for the forecast/envelope region */
     label?: string;
 }
 /** Internal segment marker added to each datum */
 export declare const SEGMENT_FIELD: "__forecastSegment";
-export type SegmentType = "training" | "observed" | "forecast";
+export type SegmentType = "training" | "training-base" | "observed" | "forecast";
 export declare function buildAnomalyAnnotations(config: AnomalyConfig): Record<string, any>[];
 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 { 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>;

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

@@ -0,0 +1,11 @@
+import * as React from "react";
+/**
+ * Shared tooltip for distribution charts (BoxPlot, ViolinPlot, RidgelinePlot).
+ *
+ * Renders category name + summary statistics (n, min, Q1, median, Q3, max, mean).
+ * Falls back to category-only display when stats are unavailable.
+ */
+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;

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

@@ -21,7 +21,9 @@ export interface SelectionConfig {
  */
 export type LinkedHoverProp = boolean | string | {
     name?: string;
-    fields: string[];
+    fields?: string[];
+    mode?: "field" | "x-position";
+    xField?: string;
 };
 /**
  * Linked brush config
@@ -73,6 +75,23 @@ export interface BaseChartProps {
     loading?: boolean;
     /** Custom content to render when data is empty. Set to `false` to disable empty state. */
     emptyContent?: React.ReactNode | false;
+    /** Uniform fill color for all data marks. Overrides colorScheme and theme categorical.
+     * For per-category coloring, use `colorBy` + `colorScheme` instead. */
+    color?: string;
+    /** 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;
+    /** Accessible summary rendered as a screen-reader-only note.
+     * Use for trend descriptions or key takeaways that supplement the visual. */
+    summary?: string;
+    /** Enable accessible data table below the chart canvas. Default: true (via frame). */
+    accessibleTable?: boolean;
+    /** Callback when a data element is clicked. Receives the original datum and pixel coordinates.
+     * For lines, receives the line data; for bars, the bar datum; for pie slices, the slice datum. */
+    onClick?: (datum: any, event: {
+        x: number;
+        y: number;
+    }) => void;
     /** Visual emphasis level for dashboard hierarchy. "primary" spans two columns in ChartGrid. */
     emphasis?: "primary" | "secondary";
     /** Enable declarative bounded animation (enter/exit/update transitions).
@@ -91,10 +110,15 @@ export interface AxisConfig {
     /** Label for the y-axis */
     yLabel?: string;
     /** Format function for x-axis tick labels */
-    xFormat?: (d: any) => string;
+    xFormat?: (d: any, index?: number, allTicks?: number[]) => string;
     /** Format function for y-axis tick labels */
     yFormat?: (d: any) => string;
 }
+/**
+ * Category formatting for ordinal chart tick labels.
+ * Receives the category value and its index, returns a formatted string.
+ */
+export type CategoryFormatFn = (label: string, index?: number) => string;
 /**
  * Accessor type - can be a property name or a function
  * @deprecated Use DataAccessor from generalTypes for generic type safety

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

@@ -19,8 +19,8 @@ export interface ChartSetupInput {
     rawData: unknown[] | undefined;
     /** The color-by accessor (may be an "actual" colorBy derived from stackBy/groupBy/categoryAccessor) */
     colorBy: Accessor<string> | undefined;
-    /** Color scheme name or custom array */
-    colorScheme: string | string[];
+    /** Color scheme name or custom array — undefined lets useColorScale consult the theme */
+    colorScheme: string | string[] | undefined;
     /** Legend interaction mode */
     legendInteraction: LegendInteractionMode | undefined;
     /** Legend position override */
@@ -50,6 +50,11 @@ export interface ChartSetupInput {
         left: number;
         right: number;
     };
+    /** onClick callback */
+    onClick?: (datum: any, event: {
+        x: number;
+        y: number;
+    }) => void;
     /** Loading state */
     loading: boolean | undefined;
     /** Empty content override */
@@ -92,6 +97,11 @@ export interface ChartSetupResult {
     earlyReturn: ReactElement | null;
     /** Props to spread into the stream frame for legend behavior */
     legendBehaviorProps: Record<string, any>;
+    /** Crosshair props to spread into StreamXYFrame when linkedHover mode is "x-position" */
+    crosshairProps: {
+        linkedCrosshairName: string;
+        linkedCrosshairSourceId: string;
+    } | undefined;
 }
 /**
  * Hook that consolidates the shared boilerplate across all HOC charts:

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

@@ -0,0 +1,51 @@
+import type { RefObject, MutableRefObject } from "react";
+import type { StreamOrdinalFrameHandle } from "../../stream/ordinalTypes";
+export interface AggregatedRow {
+    __likertCategory: string;
+    /** Stacking key — may be sentinel value for neutral halves */
+    __likertLevel: string;
+    /** Human-readable level label — always the original level name (for legend/selection) */
+    __likertLevelLabel: string;
+    __likertCount: number;
+    __likertPct: number;
+    __likertLevelIndex: number;
+}
+/** Sentinel level names for the neutral split halves */
+export declare const NEUTRAL_NEG = "__likert_neutral_neg";
+export declare const NEUTRAL_POS = "__likert_neutral_pos";
+export declare function resolveAccessorFn<T>(accessor: string | ((d: any) => T) | undefined, fallback: string): (d: any) => T;
+/**
+ * Generate a diverging color scheme for N levels.
+ * Interpolates from red → gray → blue for odd, red → blue for even.
+ */
+export declare function defaultDivergingScheme(n: number): string[];
+export declare function aggregateData(data: any[], levels: string[], getCat: (d: any) => string, getScore: ((d: any) => number) | null, getLevel: ((d: any) => string) | null, getCount: ((d: any) => number) | null): AggregatedRow[];
+export declare function toDivergingValues(rows: AggregatedRow[], levels: string[]): AggregatedRow[];
+export declare function orderForDiverging(rows: AggregatedRow[], levels: string[]): AggregatedRow[];
+interface UseLikertAggregationConfig {
+    data: any[] | undefined;
+    levels: string[];
+    categoryAccessor?: string | ((d: any) => string);
+    valueAccessor?: string | ((d: any) => number);
+    levelAccessor?: string | ((d: any) => string);
+    countAccessor?: string | ((d: any) => number);
+    isDiverging: boolean;
+    frameRef: RefObject<StreamOrdinalFrameHandle | null>;
+}
+interface UseLikertAggregationResult {
+    /** Pre-processed data for static mode */
+    processedData: AggregatedRow[];
+    /** Re-aggregate all accumulated data (call from push handlers) */
+    reAggregate: (rawData: any[]) => void;
+    /** Ref holding accumulated raw data for push mode */
+    accumulatorRef: MutableRefObject<any[]>;
+}
+/**
+ * Encapsulates Likert-specific data aggregation:
+ * - Resolves accessor functions
+ * - Aggregates raw/pre-aggregated data to percentages
+ * - Applies diverging transforms (sign flip, neutral split, stacking order)
+ * - Provides re-aggregation callback for push API streaming
+ */
+export declare function useLikertAggregation({ data, levels, categoryAccessor, valueAccessor, levelAccessor, countAccessor, isDiverging, frameRef, }: UseLikertAggregationConfig): UseLikertAggregationResult;
+export {};

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

@@ -0,0 +1,28 @@
+import type { ChartAccessor } from "./types";
+export interface OrdinalBrushInput {
+    brushProp: boolean | undefined;
+    onBrushProp: ((extent: {
+        r: [number, number];
+    } | null) => void) | undefined;
+    linkedBrush: string | {
+        name: string;
+        rField?: string;
+    } | undefined;
+    valueAccessor: ChartAccessor<any, number>;
+}
+export interface OrdinalBrushResult {
+    hasBrush: boolean;
+    handleBrush: (extent: {
+        r: [number, number];
+    } | null) => void;
+    /** Spread into streamProps: `...brushStreamProps` */
+    brushStreamProps: {
+        brush: {
+            dimension: "r";
+        };
+        onBrush: (extent: {
+            r: [number, number];
+        } | null) => void;
+    } | Record<string, never>;
+}
+export declare function useOrdinalBrush({ brushProp, onBrushProp, linkedBrush, valueAccessor, }: OrdinalBrushInput): OrdinalBrushResult;