semiotic 3.0.0 → 3.1.0

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

@@ -0,0 +1,112 @@
+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 { SelectionHookResult } from "./selectionUtils";
+import type { ReactElement, ReactNode } from "react";
+/**
+ * Input parameters for useChartSetup.
+ *
+ * This hook consolidates the color scale, category extraction, legend interaction,
+ * effective selection merge, legend + margin computation, loading/empty guards,
+ * and legend behavior props that every HOC chart repeats.
+ */
+export interface ChartSetupInput {
+    /** The data array used for color scale and category extraction */
+    data: Array<Record<string, any>>;
+    /** 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) */
+    colorBy: Accessor<string> | undefined;
+    /** Color scheme name or custom array */
+    colorScheme: string | string[];
+    /** Legend interaction mode */
+    legendInteraction: LegendInteractionMode | undefined;
+    /** Legend position override */
+    legendPosition?: LegendPosition;
+    /** Selection config from the HOC */
+    selection: SelectionConfig | undefined;
+    /** Linked hover config from the HOC */
+    linkedHover: LinkedHoverProp | undefined;
+    /** Fallback fields for selection/hover — typically derived from colorBy or categoryAccessor */
+    fallbackFields: string[];
+    /** Whether to unwrap data in hover callback (ordinal/network = true, XY = false) */
+    unwrapData?: boolean;
+    /** onObservation callback */
+    onObservation: OnObservationCallback | undefined;
+    /** Chart type name (e.g. "BarChart") */
+    chartType: string;
+    /** Chart ID for observation events */
+    chartId: string | undefined;
+    /** Show legend override */
+    showLegend: boolean | undefined;
+    /** User-provided margin */
+    userMargin: MarginType | undefined;
+    /** Mode-resolved margin defaults */
+    marginDefaults: {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+    };
+    /** Loading state */
+    loading: boolean | undefined;
+    /** Empty content override */
+    emptyContent?: ReactNode;
+    /** Resolved width from useChartMode */
+    width: number;
+    /** Resolved height from useChartMode */
+    height: number;
+}
+/**
+ * Output from useChartSetup.
+ */
+export interface ChartSetupResult {
+    /** Color scale function, or undefined if no colorBy */
+    colorScale: ((v: string) => string) | undefined;
+    /** All unique category values from colorBy */
+    allCategories: string[];
+    /** Legend interaction state (onLegendHover, onLegendClick, highlighted, isolated) */
+    legendState: ReturnType<typeof useLegendInteraction>;
+    /** The effective selection hook — legend selection takes priority over cross-chart selection */
+    effectiveSelectionHook: SelectionHookResult | null;
+    /** 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;
+    /** Custom click behavior callback for the frame */
+    customClickBehavior: (d: Record<string, any> | null) => void;
+    /** Legend config (or undefined if no legend) */
+    legend: ReturnType<typeof useChartLegendAndMargin>["legend"];
+    /** Computed margin with legend-aware adjustments */
+    margin: {
+        top: number;
+        bottom: number;
+        left: number;
+        right: number;
+    };
+    /** Resolved legend position */
+    legendPosition: LegendPosition;
+    /** 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>;
+}
+/**
+ * Hook that consolidates the shared boilerplate across all HOC charts:
+ *
+ * 1. Loading / empty state guards
+ * 2. useChartSelection (selection + linked hover)
+ * 3. useColorScale
+ * 4. allCategories extraction via useMemo
+ * 5. useLegendInteraction
+ * 6. effectiveSelectionHook merge (legend selection > cross-chart selection)
+ * 7. useChartLegendAndMargin
+ * 8. legendBehaviorProps for the stream frame
+ *
+ * Hooks are always called (no conditional returns before hooks) to satisfy React's
+ * rules of hooks. The `earlyReturn` field signals that the HOC should return early.
+ */
+export declare function useChartSetup(input: ChartSetupInput): ChartSetupResult;
+export { DEFAULT_COLOR };

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

@@ -0,0 +1,65 @@
+import type { Accessor } from "./types";
+import type { LegendPosition } from "./hooks";
+/**
+ * Hook that discovers categories from streamed (pushed) data and builds
+ * a legend dynamically.
+ *
+ * When the `data` prop is provided (bounded mode), this hook is inert —
+ * the legend is built by `useChartSetup` from the full dataset.
+ *
+ * When `data` is undefined (push API mode), this hook:
+ * 1. Wraps push/pushMany to intercept incoming data
+ * 2. Extracts category values via `colorBy`
+ * 3. Builds a legend config when new categories are discovered
+ *
+ * Returns `wrapPush` / `wrapPushMany` callbacks to wrap the imperative handle,
+ * plus a `streamingLegend` that should override the (empty) legend from useChartSetup.
+ */
+export declare function useStreamingLegend({ isPushMode, colorBy, colorScheme, showLegend, legendPosition, }: {
+    /** True when data prop is undefined (push API mode) */
+    isPushMode: boolean;
+    /** The color-by accessor (may be derived from stackBy/groupBy/categoryAccessor) */
+    colorBy: Accessor<string> | undefined;
+    /** Color scheme name or custom array */
+    colorScheme: string | string[];
+    /** Whether legend is requested */
+    showLegend: boolean | undefined;
+    /** Legend position */
+    legendPosition?: LegendPosition;
+}): {
+    wrapPush: (originalPush: (d: any) => void) => (datum: any) => void;
+    wrapPushMany: (originalPushMany: (d: any[]) => void) => (data: any[]) => void;
+    resetCategories: () => void;
+    streamingLegend: {
+        legendGroups: {
+            styleFn: (d: import("../../types/legendTypes").LegendItem) => Record<string, string | number>;
+            type: "fill";
+            items: {
+                label: string;
+                color: string;
+            }[];
+            label: string;
+        }[];
+    } | undefined;
+    streamingMarginAdjust: {
+        right: number;
+        left?: undefined;
+        top?: undefined;
+        bottom?: undefined;
+    } | {
+        left: number;
+        right?: undefined;
+        top?: undefined;
+        bottom?: undefined;
+    } | {
+        top: number;
+        right?: undefined;
+        left?: undefined;
+        bottom?: undefined;
+    } | {
+        bottom: number;
+        right?: undefined;
+        left?: undefined;
+        top?: undefined;
+    } | undefined;
+};

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

@@ -11,6 +11,16 @@ interface SafeRenderProps {
  * with the component name and error message instead of crashing the page.
  */
 export declare function SafeRender({ componentName, width, height, children }: SafeRenderProps): React.JSX.Element;
+/**
+ * Renders a "No data available" placeholder when data is empty.
+ * Returns null when data is present or emptyContent is `false`.
+ */
+export declare function renderEmptyState(data: any[] | undefined | null, width: number, height: number, emptyContent?: React.ReactNode | false): React.ReactElement | null;
+/**
+ * Renders a shimmer/skeleton loading placeholder.
+ * Returns null when loading is false.
+ */
+export declare function renderLoadingState(loading: boolean | undefined, width: number, height: number): React.ReactElement | null;
 /** Warn if a string accessor isn't found in the first data element */
 export declare function warnMissingField(componentName: string, data: any[] | undefined, accessorName: string, accessorValue: any): void;
 /** Warn if data looks like the wrong shape for this chart type */

package/dist/{charts → components/charts}/xy/AreaChart.d.ts

@@ -1,5 +1,7 @@
 import * as React from "react";
 import type { StreamXYFrameProps } from "../../stream/types";
+import type { RealtimeFrameHandle } from "../../realtime/types";
+import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 /**
@@ -14,7 +16,7 @@ export interface AreaChartProps<TDatum extends Record<string, any> = Record<stri
      * [{x: 1, y: 10, category: 'A'}, {x: 2, y: 20, category: 'A'}, {x: 1, y: 15, category: 'B'}]
      * ```
      */
-    data: TDatum[];
+    data?: TDatum[];
     /**
      * Field name or function to access x values
      * @default "x"
@@ -110,6 +112,17 @@ export interface AreaChartProps<TDatum extends Record<string, any> = Record<stri
      * @default true (when multiple areas)
      */
     showLegend?: boolean;
+    /**
+     * Legend interaction mode.
+     * - "highlight": hover dims non-hovered categories to 30% opacity
+     * - "isolate": click toggles category visibility with checkmark indicators
+     * - "none": static legend (default)
+     */
+    legendInteraction?: LegendInteractionMode;
+    /**
+     * Legend position
+     */
+    legendPosition?: LegendPosition;
     /**
      * Tooltip configuration
      */
@@ -149,7 +162,7 @@ export interface AreaChartProps<TDatum extends Record<string, any> = Record<stri
  * />
  * ```
  */
-export declare function AreaChart<TDatum extends Record<string, any> = Record<string, any>>(props: AreaChartProps<TDatum>): React.JSX.Element;
-export declare namespace AreaChart {
-    var displayName: string;
-}
+export declare const AreaChart: {
+    <TDatum extends Record<string, any> = Record<string, any>>(props: AreaChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

package/dist/{charts → components/charts}/xy/BubbleChart.d.ts

@@ -1,5 +1,7 @@
 import * as React from "react";
 import type { StreamXYFrameProps, MarginalGraphicsConfig } from "../../stream/types";
+import type { RealtimeFrameHandle } from "../../realtime/types";
+import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 /**
@@ -13,7 +15,7 @@ export interface BubbleChartProps<TDatum extends Record<string, any> = Record<st
      * [{x: 1, y: 10, size: 50, category: 'A'}, {x: 2, y: 20, size: 30, category: 'B'}]
      * ```
      */
-    data: TDatum[];
+    data?: TDatum[];
     /**
      * Field name or function to access x values
      * @default "x"
@@ -92,6 +94,17 @@ export interface BubbleChartProps<TDatum extends Record<string, any> = Record<st
     marginalGraphics?: MarginalGraphicsConfig;
     /** Accessor for unique point IDs, used by point-anchored annotations */
     pointIdAccessor?: ChartAccessor<TDatum, string>;
+    /**
+     * Legend interaction mode.
+     * - "highlight": hover dims non-hovered categories to 30% opacity
+     * - "isolate": click toggles category visibility with checkmark indicators
+     * - "none": static legend (default)
+     */
+    legendInteraction?: LegendInteractionMode;
+    /**
+     * Legend position
+     */
+    legendPosition?: LegendPosition;
     /**
      * Annotation objects to render on the chart
      */
@@ -164,7 +177,7 @@ export interface BubbleChartProps<TDatum extends Record<string, any> = Record<st
  * @param props - BubbleChart configuration
  * @returns Rendered bubble chart
  */
-export declare function BubbleChart<TDatum extends Record<string, any> = Record<string, any>>(props: BubbleChartProps<TDatum>): React.JSX.Element;
-export declare namespace BubbleChart {
-    var displayName: string;
-}
+export declare const BubbleChart: {
+    <TDatum extends Record<string, any> = Record<string, any>>(props: BubbleChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

package/dist/{charts → components/charts}/xy/ConnectedScatterplot.d.ts

@@ -1,13 +1,15 @@
 import * as React from "react";
 import type { StreamXYFrameProps } from "../../stream/types";
+import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { LegendInteractionMode } from "../shared/hooks";
 /**
  * ConnectedScatterplot component props
  */
 export interface ConnectedScatterplotProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps, AxisConfig {
-    /** Array of data points. Each point needs x and y properties. */
-    data: TDatum[];
+    /** Array of data points. Each point needs x and y properties. Omit when using push API. */
+    data?: TDatum[];
     /** Field name or function to access x values @default "x" */
     xAccessor?: ChartAccessor<TDatum, number>;
     /** Field name or function to access y values @default "y" */
@@ -30,6 +32,8 @@ export interface ConnectedScatterplotProps<TDatum extends Record<string, any> =
     tooltip?: TooltipProp;
     /** Accessor for unique point IDs, used by point-anchored annotations */
     pointIdAccessor?: ChartAccessor<TDatum, string>;
+    /** Legend interaction mode */
+    legendInteraction?: LegendInteractionMode;
     /** Annotation objects to render on the chart */
     annotations?: Record<string, any>[];
     /** Additional StreamXYFrame props for advanced customization */
@@ -54,7 +58,7 @@ export interface ConnectedScatterplotProps<TDatum extends Record<string, any> =
  * />
  * ```
  */
-export declare function ConnectedScatterplot<TDatum extends Record<string, any> = Record<string, any>>(props: ConnectedScatterplotProps<TDatum>): React.JSX.Element;
-export declare namespace ConnectedScatterplot {
-    var displayName: string;
-}
+export declare const ConnectedScatterplot: {
+    <TDatum extends Record<string, any> = Record<string, any>>(props: ConnectedScatterplotProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

package/dist/{charts → components/charts}/xy/Heatmap.d.ts

@@ -1,5 +1,7 @@
 import * as React from "react";
 import type { StreamXYFrameProps } from "../../stream/types";
+import type { RealtimeFrameHandle } from "../../realtime/types";
+import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 /**
@@ -13,7 +15,7 @@ export interface HeatmapProps<TDatum extends Record<string, any> = Record<string
      * [{x: 1, y: 1, value: 10}, {x: 1, y: 2, value: 20}, {x: 2, y: 1, value: 15}]
      * ```
      */
-    data: TDatum[];
+    data?: TDatum[];
     /**
      * Field name or function to access x values
      * @default "x"
@@ -86,6 +88,23 @@ export interface HeatmapProps<TDatum extends Record<string, any> = Record<string
      * Tooltip configuration
      */
     tooltip?: TooltipProp;
+    /**
+     * Show a gradient legend for the color scale.
+     * @default false
+     */
+    showLegend?: boolean;
+    /**
+     * Position of the gradient legend.
+     * @default "right"
+     */
+    legendPosition?: "right" | "left" | "top" | "bottom";
+    /**
+     * Legend interaction mode.
+     * - "highlight": hover dims non-hovered categories to 30% opacity
+     * - "isolate": click toggles category visibility with checkmark indicators
+     * - "none": static legend (default)
+     */
+    legendInteraction?: LegendInteractionMode;
     /**
      * Annotation objects to render on the chart
      */
@@ -154,7 +173,7 @@ export interface HeatmapProps<TDatum extends Record<string, any> = Record<string
  * @param props - Heatmap configuration
  * @returns Rendered heatmap
  */
-export declare function Heatmap<TDatum extends Record<string, any> = Record<string, any>>(props: HeatmapProps<TDatum>): React.JSX.Element;
-export declare namespace Heatmap {
-    var displayName: string;
-}
+export declare const Heatmap: {
+    <TDatum extends Record<string, any> = Record<string, any>>(props: HeatmapProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

package/dist/{charts → components/charts}/xy/LineChart.d.ts

@@ -1,5 +1,7 @@
 import * as React from "react";
 import type { StreamXYFrameProps } from "../../stream/types";
+import type { RealtimeFrameHandle } from "../../realtime/types";
+import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { AnomalyConfig, ForecastConfig } from "../shared/statisticalOverlays";
@@ -21,7 +23,7 @@ export interface LineChartProps<TDatum extends Record<string, any> = Record<stri
      * [{label: 'Series A', coordinates: [{x: 1, y: 10}, {x: 2, y: 20}]}]
      * ```
      */
-    data: TDatum[];
+    data?: TDatum[];
     /**
      * Field name or function to access x values
      * @default "x"
@@ -32,6 +34,16 @@ export interface LineChartProps<TDatum extends Record<string, any> = Record<stri
      * @default "y"
      */
     yAccessor?: ChartAccessor<TDatum, number>;
+    /**
+     * Scale type for the x-axis
+     * @default "linear"
+     */
+    xScaleType?: "linear" | "log";
+    /**
+     * Scale type for the y-axis
+     * @default "linear"
+     */
+    yScaleType?: "linear" | "log";
     /**
      * Field name or function to group data into multiple lines
      * @example
@@ -106,6 +118,18 @@ export interface LineChartProps<TDatum extends Record<string, any> = Record<stri
      * @default true (when multiple lines)
      */
     showLegend?: boolean;
+    /**
+     * Legend interaction mode.
+     * - "highlight": hover dims non-hovered categories to 30% opacity
+     * - "isolate": click toggles category visibility with checkmark indicators
+     * - "none": static legend (default)
+     */
+    legendInteraction?: LegendInteractionMode;
+    /**
+     * Legend position relative to the chart area
+     * @default "right"
+     */
+    legendPosition?: "right" | "left" | "top" | "bottom";
     /**
      * Tooltip configuration
      */
@@ -116,6 +140,24 @@ export interface LineChartProps<TDatum extends Record<string, any> = Record<stri
      * Annotation objects to render on the chart
      */
     annotations?: Record<string, any>[];
+    /**
+     * Place category labels directly at line endpoints instead of using a separate legend.
+     * When true, auto-hides the legend (override with `showLegend: true`).
+     * Pass an object for fine-grained control.
+     */
+    directLabel?: boolean | {
+        /** Where to place labels relative to the line. @default "end" */
+        position?: "end" | "start";
+        /** Font size for labels. @default 11 */
+        fontSize?: number;
+    };
+    /**
+     * How to handle null/undefined/NaN values in the data.
+     * - "break": break the line at gaps (default)
+     * - "interpolate": connect across gaps (skip missing points)
+     * - "zero": drop to zero at gap boundaries
+     */
+    gapStrategy?: "break" | "interpolate" | "zero";
     /**
      * Anomaly detection configuration. Highlights outlier points and shows
      * a shaded band representing the expected range (mean +/- threshold * stddev).
@@ -208,7 +250,7 @@ export interface LineChartProps<TDatum extends Record<string, any> = Record<stri
  * @param props - LineChart configuration
  * @returns Rendered line chart
  */
-export declare function LineChart<TDatum extends Record<string, any> = Record<string, any>>(props: LineChartProps<TDatum>): React.JSX.Element;
-export declare namespace LineChart {
-    var displayName: string;
-}
+export declare const LineChart: {
+    <TDatum extends Record<string, any> = Record<string, any>>(props: LineChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

package/dist/{charts → components/charts}/xy/MinimapChart.d.ts

@@ -1,5 +1,6 @@
 import * as React from "react";
 import type { StreamXYFrameProps } from "../../stream/types";
+import type { LegendPosition } from "../shared/hooks";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 export interface MinimapConfig {
@@ -54,6 +55,8 @@ export interface MinimapChartProps<TDatum extends Record<string, any> = Record<s
     showGrid?: boolean;
     /** Show legend */
     showLegend?: boolean;
+    /** Legend position */
+    legendPosition?: LegendPosition;
     /** Tooltip config */
     tooltip?: TooltipProp;
     /** Minimap configuration */

package/dist/components/charts/xy/QuadrantChart.d.ts

@@ -0,0 +1,120 @@
+import * as React from "react";
+import type { StreamXYFrameProps } from "../../stream/types";
+import type { RealtimeFrameHandle } from "../../realtime/types";
+import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
+/**
+ * Quadrant label and color configuration
+ */
+export interface QuadrantConfig {
+    /** Label text for the quadrant */
+    label: string;
+    /** Background fill color for the quadrant */
+    color: string;
+    /** Fill opacity (default: 0.08) */
+    opacity?: number;
+}
+/**
+ * Configuration for the four quadrants.
+ * Quadrants are defined relative to the center lines:
+ * - topRight: high X, high Y
+ * - topLeft: low X, high Y
+ * - bottomRight: high X, low Y
+ * - bottomLeft: low X, low Y
+ */
+export interface QuadrantsConfig {
+    topRight: QuadrantConfig;
+    topLeft: QuadrantConfig;
+    bottomRight: QuadrantConfig;
+    bottomLeft: QuadrantConfig;
+}
+/**
+ * Centerline style configuration
+ */
+export interface CenterlineStyle {
+    /** Line color @default "#999" */
+    stroke?: string;
+    /** Line width @default 1 */
+    strokeWidth?: number;
+    /** Dash pattern (e.g. [4, 3]) @default [] (solid) */
+    strokeDasharray?: number[];
+}
+/**
+ * QuadrantChart component props
+ */
+export interface QuadrantChartProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps, AxisConfig {
+    /** Array of data points */
+    data?: TDatum[];
+    /** Field name or function to access x values @default "x" */
+    xAccessor?: ChartAccessor<TDatum, number>;
+    /** Field name or function to access y values @default "y" */
+    yAccessor?: ChartAccessor<TDatum, number>;
+    /** X-coordinate of the vertical center line. Defaults to midpoint of x domain. */
+    xCenter?: number;
+    /** Y-coordinate of the horizontal center line. Defaults to midpoint of y domain. */
+    yCenter?: number;
+    /** Quadrant configuration: labels and colors for each of the four quadrants */
+    quadrants: QuadrantsConfig;
+    /** Style for the center lines */
+    centerlineStyle?: CenterlineStyle;
+    /** Show quadrant labels @default true */
+    showQuadrantLabels?: boolean;
+    /** Font size for quadrant labels @default 12 */
+    quadrantLabelSize?: number;
+    /** Field name or function to determine point color */
+    colorBy?: ChartAccessor<TDatum, string>;
+    /** Color scheme for categorical data @default "category10" */
+    colorScheme?: string | string[];
+    /** Field name or function to determine point size */
+    sizeBy?: ChartAccessor<TDatum, number>;
+    /** Min and max radius for points @default [3, 15] */
+    sizeRange?: [number, number];
+    /** Default point radius @default 5 */
+    pointRadius?: number;
+    /** Point opacity @default 0.8 */
+    pointOpacity?: number;
+    /** Enable hover annotations @default true */
+    enableHover?: boolean;
+    /** Show grid lines @default false */
+    showGrid?: boolean;
+    /** Show legend @default true (when colorBy is specified) */
+    showLegend?: boolean;
+    /** Tooltip configuration */
+    tooltip?: TooltipProp;
+    /** Accessor for unique point IDs */
+    pointIdAccessor?: ChartAccessor<TDatum, string>;
+    /** Legend interaction mode */
+    legendInteraction?: LegendInteractionMode;
+    /** Legend position */
+    legendPosition?: LegendPosition;
+    /** Annotation objects */
+    annotations?: Record<string, any>[];
+    /** Additional StreamXYFrame props */
+    frameProps?: Partial<Omit<StreamXYFrameProps, "chartType" | "data" | "size">>;
+}
+/**
+ * QuadrantChart — A scatterplot divided into four labeled, colored quadrants
+ * by center lines at user-specified x/y positions.
+ *
+ * Each quadrant gets a background color and label. Points are rendered as a
+ * standard scatter plot on top. Supports push API for streaming data.
+ *
+ * @example
+ * ```tsx
+ * <QuadrantChart
+ *   data={[{x: 1, y: 10}, {x: 5, y: 3}]}
+ *   xCenter={3} yCenter={5}
+ *   quadrants={{
+ *     topRight: { label: "Stars", color: "#4CAF50" },
+ *     topLeft: { label: "Question Marks", color: "#FF9800" },
+ *     bottomRight: { label: "Cash Cows", color: "#2196F3" },
+ *     bottomLeft: { label: "Dogs", color: "#F44336" },
+ *   }}
+ * />
+ * ```
+ */
+export declare const QuadrantChart: {
+    <TDatum extends Record<string, any> = Record<string, any>>(props: QuadrantChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

package/dist/{charts → components/charts}/xy/Scatterplot.d.ts

@@ -1,13 +1,15 @@
 import * as React from "react";
 import type { StreamXYFrameProps, MarginalGraphicsConfig } from "../../stream/types";
+import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 /**
  * Scatterplot component props
  */
 export interface ScatterplotProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps, AxisConfig {
     /** Array of data points. Each point should have x and y properties. */
-    data: TDatum[];
+    data?: TDatum[];
     /** Field name or function to access x values @default "x" */
     xAccessor?: ChartAccessor<TDatum, number>;
     /** Field name or function to access y values @default "y" */
@@ -36,6 +38,10 @@ export interface ScatterplotProps<TDatum extends Record<string, any> = Record<st
     marginalGraphics?: MarginalGraphicsConfig;
     /** Accessor for unique point IDs, used by point-anchored annotations */
     pointIdAccessor?: ChartAccessor<TDatum, string>;
+    /** Legend interaction mode */
+    legendInteraction?: LegendInteractionMode;
+    /** Legend position */
+    legendPosition?: LegendPosition;
     /** Annotation objects to render on the chart */
     annotations?: Record<string, any>[];
     /** Additional StreamXYFrame props for advanced customization */
@@ -53,7 +59,7 @@ export interface ScatterplotProps<TDatum extends Record<string, any> = Record<st
  * />
  * ```
  */
-export declare function Scatterplot<TDatum extends Record<string, any> = Record<string, any>>(props: ScatterplotProps<TDatum>): React.JSX.Element;
-export declare namespace Scatterplot {
-    var displayName: string;
-}
+export declare const Scatterplot: {
+    <TDatum extends Record<string, any> = Record<string, any>>(props: ScatterplotProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};