semiotic 3.0.1 → 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/components/charts/xy/AreaChart.d.ts

@@ -1,6 +1,7 @@
 import * as React from "react";
 import type { StreamXYFrameProps } from "../../stream/types";
-import type { LegendInteractionMode } from "../shared/hooks";
+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";
 /**
@@ -15,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"
@@ -118,6 +119,10 @@ export interface AreaChartProps<TDatum extends Record<string, any> = Record<stri
      * - "none": static legend (default)
      */
     legendInteraction?: LegendInteractionMode;
+    /**
+     * Legend position
+     */
+    legendPosition?: LegendPosition;
     /**
      * Tooltip configuration
      */
@@ -157,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/components/charts/xy/BubbleChart.d.ts

@@ -1,6 +1,7 @@
 import * as React from "react";
 import type { StreamXYFrameProps, MarginalGraphicsConfig } from "../../stream/types";
-import type { LegendInteractionMode } from "../shared/hooks";
+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 +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"
@@ -100,6 +101,10 @@ export interface BubbleChartProps<TDatum extends Record<string, any> = Record<st
      * - "none": static legend (default)
      */
     legendInteraction?: LegendInteractionMode;
+    /**
+     * Legend position
+     */
+    legendPosition?: LegendPosition;
     /**
      * Annotation objects to render on the chart
      */
@@ -172,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/components/charts/xy/ConnectedScatterplot.d.ts

@@ -1,5 +1,6 @@
 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";
@@ -7,8 +8,8 @@ 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" */
@@ -57,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/components/charts/xy/Heatmap.d.ts

@@ -1,5 +1,6 @@
 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";
@@ -14,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"
@@ -87,6 +88,16 @@ 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
@@ -162,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/components/charts/xy/LineChart.d.ts

@@ -1,5 +1,6 @@
 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";
@@ -22,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"
@@ -33,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
@@ -114,6 +125,11 @@ export interface LineChartProps<TDatum extends Record<string, any> = Record<stri
      * - "none": static legend (default)
      */
     legendInteraction?: LegendInteractionMode;
+    /**
+     * Legend position relative to the chart area
+     * @default "right"
+     */
+    legendPosition?: "right" | "left" | "top" | "bottom";
     /**
      * Tooltip configuration
      */
@@ -234,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/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/components/charts/xy/Scatterplot.d.ts

@@ -1,14 +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 } from "../shared/hooks";
+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" */
@@ -39,6 +40,8 @@ export interface ScatterplotProps<TDatum extends Record<string, any> = Record<st
     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 */
@@ -56,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;
+};

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

@@ -1,6 +1,7 @@
 import * as React from "react";
 import type { StreamXYFrameProps } from "../../stream/types";
-import type { LegendInteractionMode } from "../shared/hooks";
+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 +15,7 @@ export interface StackedAreaChartProps<TDatum extends Record<string, any> = Reco
      * [{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"
@@ -101,6 +102,10 @@ export interface StackedAreaChartProps<TDatum extends Record<string, any> = Reco
      * - "none": static legend (default)
      */
     legendInteraction?: LegendInteractionMode;
+    /**
+     * Legend position
+     */
+    legendPosition?: LegendPosition;
     /**
      * Tooltip configuration
      */
@@ -140,7 +145,7 @@ export interface StackedAreaChartProps<TDatum extends Record<string, any> = Reco
  * />
  * ```
  */
-export declare function StackedAreaChart<TDatum extends Record<string, any> = Record<string, any>>(props: StackedAreaChartProps<TDatum>): React.JSX.Element;
-export declare namespace StackedAreaChart {
-    var displayName: string;
-}
+export declare const StackedAreaChart: {
+    <TDatum extends Record<string, any> = Record<string, any>>(props: StackedAreaChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

package/dist/components/geo/mergeData.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Merge external data into GeoJSON features by joining on a key field.
+ *
+ * @example
+ * ```ts
+ * const enriched = mergeData(worldCountries, myCSV, {
+ *   featureKey: "properties.iso_a3",
+ *   dataKey: "country_code"
+ * })
+ * ```
+ *
+ * Cross-pollination: This pattern (key-based data join) could be extracted
+ * to a shared utility for any data merge operation in Semiotic.
+ */
+export declare function mergeData<T extends Record<string, any>>(features: GeoJSON.Feature[], data: T[], options: {
+    featureKey: string;
+    dataKey: string;
+}): GeoJSON.Feature[];

package/dist/components/geo/referenceGeography.d.ts

@@ -0,0 +1,10 @@
+export type ReferenceGeography = "world-110m" | "world-50m" | "land-110m" | "land-50m";
+/**
+ * Resolve a string reference to GeoJSON features.
+ * Uses dynamic import so bundlers can tree-shake/code-split the data.
+ */
+export declare function resolveReferenceGeography(name: ReferenceGeography): Promise<GeoJSON.Feature[]>;
+/**
+ * Check whether a value is a known reference geography string.
+ */
+export declare function isReferenceGeography(value: unknown): value is ReferenceGeography;

package/dist/components/geo/useReferenceAreas.d.ts

@@ -0,0 +1,13 @@
+import { type ReferenceGeography } from "./referenceGeography";
+export type AreasProp = GeoJSON.Feature[] | ReferenceGeography;
+/**
+ * Hook that resolves an `areas` prop — either GeoJSON features passed directly,
+ * or a string reference ("world-110m", etc.) that triggers an async load.
+ *
+ * Returns `null` while loading, resolved features when ready.
+ *
+ * When `areas` is already an array, the value is returned synchronously via
+ * useMemo (no stale-frame lag between prop changes). The useState+useEffect
+ * path is only used for async reference string resolution.
+ */
+export declare function useReferenceAreas(areas: AreasProp | undefined): GeoJSON.Feature[] | null;

package/dist/components/realtime/RingBuffer.d.ts

@@ -10,6 +10,7 @@ export declare class RingBuffer<T> {
     peek(): T | undefined;
     peekOldest(): T | undefined;
     [Symbol.iterator](): Iterator<T>;
+    forEach(callback: (value: T, index: number) => void): void;
     toArray(): T[];
     resize(newCapacity: number): T[];
     clear(): void;