semiotic 3.2.0 → 3.2.2

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

@@ -0,0 +1,94 @@
+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";
+/**
+ * LikertChart — visualize Likert scale survey responses.
+ *
+ * Supports two data formats:
+ *
+ * **Raw responses** — each row is one respondent's answer:
+ * ```
+ * [{ question: "Q1", score: 4 }, { question: "Q1", score: 2 }, ...]
+ * ```
+ * Set `valueAccessor` to the integer score field. Scores are mapped to
+ * `levels` by index (score 1 → levels[0], score 2 → levels[1], …).
+ *
+ * **Pre-aggregated** — each row is a (question, level, count) triple:
+ * ```
+ * [{ question: "Q1", level: "Agree", count: 45 }, ...]
+ * ```
+ * Set `levelAccessor` and `countAccessor`.
+ *
+ * **Orientation:**
+ * - `"horizontal"` (default) — diverging bar chart centered at 0%.
+ *   Negative levels extend left, positive right. If `levels` has an odd
+ *   count, the center level is split 50/50 across the centerline and drawn
+ *   in a neutral color. Even counts split cleanly at the midpoint.
+ * - `"vertical"` — stacked 100% bar chart, levels stacked bottom-to-top.
+ *
+ * **Important:** The diverging layout assigns meaning by position in the
+ * `levels` array. The first half is treated as "negative", the second half
+ * as "positive", and (if odd) the middle entry as "neutral". If your data
+ * doesn't follow this low-to-high convention, the chart will misrepresent
+ * the polarity.
+ */
+export interface LikertChartProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
+    data?: TDatum[];
+    /** Question / item accessor — the ordinal axis. */
+    categoryAccessor?: ChartAccessor<TDatum, string>;
+    /**
+     * Integer score accessor (raw response mode).
+     * Scores are 1-based: score 1 maps to levels[0], score 2 to levels[1], etc.
+     * Mutually exclusive with levelAccessor/countAccessor.
+     */
+    valueAccessor?: ChartAccessor<TDatum, number>;
+    /**
+     * Level name accessor (pre-aggregated mode).
+     * Each value must match an entry in `levels`.
+     */
+    levelAccessor?: ChartAccessor<TDatum, string>;
+    /**
+     * Count/frequency accessor (pre-aggregated mode). Defaults to "count".
+     */
+    countAccessor?: ChartAccessor<TDatum, number>;
+    /**
+     * Ordered response labels from most negative to most positive.
+     * Example (5-point): ["Strongly Disagree", "Disagree", "Neutral", "Agree", "Strongly Agree"]
+     * Example (4-point): ["Strongly Disagree", "Disagree", "Agree", "Strongly Agree"]
+     *
+     * Odd count → center level is neutral. Even count → clean negative/positive split.
+     */
+    levels: string[];
+    /**
+     * "horizontal" (default): diverging bar chart centered at 0%.
+     * "vertical": stacked 100% bar chart.
+     */
+    orientation?: "horizontal" | "vertical";
+    /**
+     * One color per level. Should match the length of `levels`.
+     * For diverging orientation, use a diverging palette (red→neutral→blue).
+     */
+    colorScheme?: string[];
+    categoryLabel?: string;
+    valueLabel?: string;
+    valueFormat?: (d: number | string) => string;
+    barPadding?: number;
+    enableHover?: boolean;
+    showGrid?: boolean;
+    showCategoryTicks?: boolean;
+    showLegend?: boolean;
+    legendInteraction?: LegendInteractionMode;
+    legendPosition?: "right" | "left" | "top" | "bottom";
+    tooltip?: TooltipProp;
+    annotations?: Record<string, any>[];
+    /** Custom formatter for category tick labels */
+    categoryFormat?: CategoryFormatFn;
+    frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
+}
+export declare const LikertChart: {
+    <TDatum extends Record<string, any> = Record<string, any>>(props: LikertChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

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

@@ -11,7 +11,6 @@ export interface PieChartProps<TDatum extends Record<string, any> = Record<strin
     colorBy?: ChartAccessor<TDatum, string>;
     colorScheme?: string | string[];
     startAngle?: number;
-    slicePadding?: number;
     enableHover?: boolean;
     showCategoryTicks?: boolean;
     showLegend?: boolean;

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

@@ -1,10 +1,11 @@
 import * as React from "react";
 import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
-import type { LegendPosition } from "../shared/hooks";
-import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import type { 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 RidgelinePlotProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
-    data: TDatum[];
+    data?: TDatum[];
     categoryAccessor?: ChartAccessor<TDatum, string>;
     valueAccessor?: ChartAccessor<TDatum, number>;
     orientation?: "vertical" | "horizontal";
@@ -21,9 +22,12 @@ export interface RidgelinePlotProps<TDatum extends Record<string, any> = Record<
     showGrid?: boolean;
     showCategoryTicks?: boolean;
     showLegend?: boolean;
+    legendInteraction?: LegendInteractionMode;
     legendPosition?: LegendPosition;
     tooltip?: TooltipProp;
     annotations?: Record<string, any>[];
+    /** Custom formatter for category tick labels */
+    categoryFormat?: CategoryFormatFn;
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 /**
@@ -32,7 +36,7 @@ export interface RidgelinePlotProps<TDatum extends Record<string, any> = Record<
  * Each category shows its value distribution as a filled area extending from a
  * baseline. The amplitude prop controls overlap between rows.
  */
-export declare function RidgelinePlot<TDatum extends Record<string, any> = Record<string, any>>(props: RidgelinePlotProps<TDatum>): React.JSX.Element;
-export declare namespace RidgelinePlot {
-    var displayName: string;
-}
+export declare const RidgelinePlot: {
+    <TDatum extends Record<string, any> = Record<string, any>>(props: RidgelinePlotProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

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

@@ -1,7 +1,7 @@
 import * as React from "react";
 import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
 import type { LegendInteractionMode } from "../shared/hooks";
-import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import type { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 export interface StackedBarChartProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
@@ -25,6 +25,8 @@ export interface StackedBarChartProps<TDatum extends Record<string, any> = Recor
     legendPosition?: "right" | "left" | "top" | "bottom";
     tooltip?: TooltipProp;
     annotations?: Record<string, any>[];
+    /** Custom formatter for category tick labels */
+    categoryFormat?: CategoryFormatFn;
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 export declare const StackedBarChart: {

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

@@ -1,7 +1,7 @@
 import * as React from "react";
 import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
-import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import type { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 export interface SwarmPlotProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
@@ -27,6 +27,19 @@ export interface SwarmPlotProps<TDatum extends Record<string, any> = Record<stri
     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 SwarmPlot: {

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 {
@@ -22,9 +22,23 @@ export interface ViolinPlotProps<TDatum extends Record<string, any> = Record<str
     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/hooks.d.ts

@@ -26,7 +26,8 @@ export declare function resolveDefaultFill(color: string | undefined, themeCateg
 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;
 /**
@@ -42,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[];
@@ -50,11 +51,25 @@ 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
@@ -118,6 +133,9 @@ interface ChartModeInput {
     /** "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;
@@ -134,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/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.

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
@@ -76,6 +78,20 @@ 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;
+    /** 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).
@@ -98,6 +114,11 @@ export interface AxisConfig {
     /** 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;

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

@@ -0,0 +1,54 @@
+import type { Ref, RefObject } from "react";
+import type { StreamOrdinalFrameHandle } from "../../stream/ordinalTypes";
+import type { RealtimeFrameHandle } from "../../realtime/types";
+import type { Accessor } from "./types";
+import type { LegendPosition } from "./hooks";
+interface UseOrdinalStreamingConfig {
+    /** External ref for push API */
+    ref: Ref<RealtimeFrameHandle>;
+    /** Internal frame ref */
+    frameRef: RefObject<StreamOrdinalFrameHandle | null>;
+    /** True when data prop is undefined (push API mode) */
+    isPushMode: boolean;
+    /** Color-by accessor (may be derived from stackBy/groupBy/etc.) */
+    colorBy: Accessor<string> | undefined;
+    /** Color scheme name or array — undefined lets useColorScale consult the theme */
+    colorScheme: string | string[] | undefined;
+    /** Whether legend is requested */
+    showLegend: boolean | undefined;
+    /** Legend position */
+    legendPosition?: LegendPosition;
+    /** Results from useChartSetup — needed for legend/margin merge */
+    setup: {
+        legendBehaviorProps: Record<string, any>;
+        legendPosition: LegendPosition;
+        margin: {
+            top: number;
+            right: number;
+            bottom: number;
+            left: number;
+        };
+    };
+}
+interface UseOrdinalStreamingResult {
+    /** Legend props merged with streaming legend (spread into streamProps) */
+    effectiveLegendProps: Record<string, any>;
+    /** Margin merged with streaming legend margin adjustments */
+    effectiveMargin: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+}
+/**
+ * Shared hook for ordinal charts that support push API + streaming legend.
+ *
+ * Consolidates: useStreamingLegend, wrappedPush/pushMany,
+ * useImperativeHandle, effectiveLegendProps, effectiveMargin.
+ *
+ * Used by: StackedBarChart, GroupedBarChart, PieChart, DonutChart, SwimlaneChart.
+ * NOT used by LikertChart (custom accumulator + deterministic legend).
+ */
+export declare function useOrdinalStreaming({ ref, frameRef, isPushMode, colorBy, colorScheme, showLegend, legendPosition, setup, }: UseOrdinalStreamingConfig): UseOrdinalStreamingResult;
+export {};