semiotic 3.4.1 → 3.5.0

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

@@ -0,0 +1,84 @@
+import type { Ref, RefObject, ReactElement, ReactNode } from "react";
+import { useChartMode } from "./hooks";
+import { type ChartSetupResult } from "./useChartSetup";
+import type { ChartMode, SelectionConfig, LinkedHoverProp } from "./types";
+import type { OnObservationCallback } from "../../store/ObservationStore";
+import type { PartialMargin, MarginType } from "../../types/marginType";
+import type { Datum } from "./datumTypes";
+import type { RealtimeFrameHandle } from "../../realtime/types";
+/**
+ * Margin shorthand → sided form. The Stream*Frame margin props only
+ * accept the sided object form, so HOCs that expose the user-friendly
+ * number shorthand have to expand it themselves. Centralized here so
+ * every custom-layout HOC normalizes consistently.
+ */
+export declare function normalizeUserMargin(m: PartialMargin | undefined): Partial<MarginType> | undefined;
+interface ScaffoldOptions {
+    /** Ref forwarded by the HOC. The hook binds the imperative handle internally. */
+    imperativeRef: Ref<RealtimeFrameHandle> | undefined;
+    /** Which `useFrameImperativeHandle` variant to bind. XY/ordinal frames share "xy". */
+    imperativeVariant: "xy" | "network";
+    /** Margin shorthand or sided form from the HOC's `margin` prop. */
+    margin: PartialMargin | undefined;
+    width?: number;
+    height?: number;
+    showGrid?: boolean;
+    enableHover?: boolean;
+    showLegend?: boolean;
+    title?: string;
+    mode?: ChartMode;
+    xLabel?: string;
+    yLabel?: string;
+}
+interface ScaffoldResult<TFrameHandle> {
+    /** Ref to attach to the inner Stream*Frame component. */
+    frameRef: RefObject<TFrameHandle | null>;
+    /** Result of `useChartMode` — width/height/showGrid/etc. with mode defaults applied. */
+    resolved: ReturnType<typeof useChartMode>;
+    /** User margin normalized to the sided form, or undefined if not supplied. */
+    normalizedMargin: Partial<MarginType> | undefined;
+}
+/**
+ * Scaffold shared by all three custom-layout HOCs: imperative-handle
+ * binding, chart-mode resolution, margin normalization. Network HOCs
+ * stop here; data-shaped HOCs layer `useChartSetup` on top via
+ * `useCustomChartSetup`.
+ */
+export declare function useCustomChartScaffold<TFrameHandle>(options: ScaffoldOptions): ScaffoldResult<TFrameHandle>;
+interface DataSetupOptions extends ScaffoldOptions {
+    /** Raw `data` prop from the HOC (may be undefined in push mode). */
+    data: Datum[] | undefined;
+    /** Label used by useChartSetup for observation events ("XYCustomChart", "OrdinalCustomChart"). */
+    chartTypeLabel: string;
+    /** Whether the hover callback should unwrap the datum (ordinal/network = true, XY = false). */
+    unwrapData: boolean;
+    /** Color scheme threaded into useChartSetup's color resolution. */
+    colorScheme?: string | string[];
+    /** Pass-through chart-setup inputs. */
+    selection?: SelectionConfig;
+    linkedHover?: LinkedHoverProp;
+    onObservation?: OnObservationCallback;
+    onClick?: (datum: any, ev: {
+        x: number;
+        y: number;
+    }) => void;
+    chartId?: string;
+    loading?: boolean;
+    emptyContent?: ReactNode;
+}
+interface DataSetupResult<TFrameHandle> extends ScaffoldResult<TFrameHandle> {
+    /** Sparse-filtered copy of the input data array. */
+    safeData: Datum[];
+    /** Full `useChartSetup` result — selection/legend/behavior wiring for the streamProps. */
+    setup: ChartSetupResult;
+    /** If non-null, the HOC should render this immediately (loading skeleton or empty state). */
+    earlyReturn: ReactElement | null;
+}
+/**
+ * Scaffold + `useChartSetup` wiring for the data-shaped custom-layout
+ * HOCs (`XYCustomChart`, `OrdinalCustomChart`). Each HOC stays in charge
+ * of its own frame-specific streamProps; the hook only owns the
+ * orchestration that is genuinely identical.
+ */
+export declare function useCustomChartSetup<TFrameHandle>(options: DataSetupOptions): DataSetupResult<TFrameHandle>;
+export {};

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

@@ -0,0 +1,28 @@
+import type { Ref, RefObject, DependencyList } from "react";
+import type { RealtimeFrameHandle } from "../../realtime/types";
+type FrameVariant = "xy" | "network" | "geo-points";
+interface Options {
+    /**
+     * Variant decides which default method bodies are emitted. The
+     * concrete `frameRef` shape must match the variant — the helper
+     * trusts the caller here rather than fighting TypeScript's
+     * discriminated-union narrowing across heterogeneous frame handle
+     * types (`StreamXYFrameHandle` vs `StreamNetworkFrameHandle` vs
+     * `StreamGeoFrameHandle`). A regression test in
+     * `useFrameImperativeHandle.test.ts` exercises each variant's
+     * defaults plus the `getScales` omission for network/geo.
+     */
+    variant: FrameVariant;
+    frameRef: RefObject<unknown>;
+    overrides?: Partial<RealtimeFrameHandle>;
+    deps?: DependencyList;
+}
+/**
+ * Wire up the HOC's exposed `ref` to the inner frame ref using the
+ * shape conventions for the chosen variant. Pass `overrides` to
+ * replace specific methods (e.g. a wrapped `push` or a custom `clear`
+ * that runs HOC-side cleanup before delegating to the frame); the
+ * variant's defaults fill in everything else.
+ */
+export declare function useFrameImperativeHandle(ref: Ref<RealtimeFrameHandle> | undefined, options: Options): void;
+export {};

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

@@ -2,27 +2,14 @@ import type { Datum } from "./datumTypes";
 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 */
+    /** Results from useChartSetup that should be forwarded to the stream frame */
     setup: {
         legendBehaviorProps: Datum;
-        legendPosition: LegendPosition;
         margin: {
             top: number;
             right: number;
@@ -32,9 +19,9 @@ interface UseOrdinalStreamingConfig {
     };
 }
 interface UseOrdinalStreamingResult {
-    /** Legend props merged with streaming legend (spread into streamProps) */
+    /** Legend/category-domain props from useChartSetup (spread into streamProps) */
     effectiveLegendProps: Datum;
-    /** Margin merged with streaming legend margin adjustments */
+    /** Margin from useChartSetup, including frame-domain legend expansion */
     effectiveMargin: {
         top: number;
         right: number;
@@ -45,11 +32,11 @@ interface UseOrdinalStreamingResult {
 /**
  * Shared hook for ordinal charts that support push API + streaming legend.
  *
- * Consolidates: useStreamingLegend, wrappedPush/pushMany,
- * useImperativeHandle, effectiveLegendProps, effectiveMargin.
+ * Consolidates imperative handle forwarding and returns the legend/margin
+ * props that useChartSetup derives from static data or frame-reported domains.
  *
  * 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 declare function useOrdinalStreaming({ ref, frameRef, setup, }: UseOrdinalStreamingConfig): UseOrdinalStreamingResult;
 export {};

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

@@ -1,20 +1,28 @@
 import type { Datum } from "./datumTypes";
 import type { Accessor } from "./types";
-import type { LegendPosition } from "./hooks";
+import { type LegendPosition } from "./hooks";
 /**
- * Hook that discovers categories from streamed (pushed) data and builds
- * a legend dynamically.
+ * Low-level push-API category-discovery wrapper.
  *
- * When the `data` prop is provided (bounded mode), this hook is inert —
- * the legend is built by `useChartSetup` from the full dataset.
+ * Most HOCs do NOT need this hook anymore. `useChartSetup` already
+ * synthesizes a push-mode legend from categories the StreamFrame emits
+ * via `onCategoriesChange`, applies the same provider/scheme/theme/
+ * STREAMING_PALETTE precedence the marks resolve through, and registers
+ * those categories with the parent `LinkedCharts` via
+ * `useChartLegendAndMargin` → `useLinkedChartCategories`. For HOCs that
+ * just want a working push-mode legend, that is enough.
  *
- * 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
+ * This hook is kept as the escape hatch for HOCs that must intercept
+ * the push call BEFORE the frame ingests it — typically aggregator HOCs
+ * like `LikertChart` that re-aggregate streamed rows into a different
+ * shape (level × count) before the frame sees them. `wrapPush` /
+ * `wrapPushMany` give those charts a place to run their accumulator
+ * code; the wrapped function then forwards to the original push.
  *
- * Returns `wrapPush` / `wrapPushMany` callbacks to wrap the imperative handle,
- * plus a `streamingLegend` that should override the (empty) legend from useChartSetup.
+ * Returned `streamingLegend` and `streamingMarginAdjust` are vestigial
+ * for these consumers — they're produced for backward compatibility,
+ * but new code should rely on `setup.legend` / `setup.margin` from
+ * `useChartSetup` instead.
  */
 export declare function useStreamingLegend({ isPushMode, colorBy, colorScheme, showLegend, legendPosition, }: {
     /** True when data prop is undefined (push API mode) */
@@ -31,6 +39,14 @@ export declare function useStreamingLegend({ isPushMode, colorBy, colorScheme, s
     wrapPush: (originalPush: (d: Datum) => void) => (datum: Datum) => void;
     wrapPushMany: (originalPushMany: (d: any[]) => void) => (data: any[]) => void;
     resetCategories: () => void;
+    categories: string[];
+    categoryDomainProps: {
+        legendCategoryAccessor: Accessor<string>;
+        onCategoriesChange: (categories: string[]) => void;
+    } | {
+        legendCategoryAccessor?: undefined;
+        onCategoriesChange?: undefined;
+    };
     streamingLegend: {
         legendGroups: {
             styleFn: (d: import("../../types/legendTypes").LegendItem) => Record<string, string | number>;

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

@@ -10,11 +10,11 @@ export interface PropDef {
     type: PropType | PropType[];
     enum?: readonly string[];
 }
-type DataShape = "array" | "object" | "network" | "realtime";
+type DataShape = "array" | "object" | "network" | "realtime" | "none";
 export interface ComponentSpec {
     /** Props that must be present */
     required: string[];
-    /** Data shape — drives which validateChartData helper to call */
+    /** Data shape — drives which validateChartData helper to call; "none" means no data prop is expected */
     dataShape: DataShape;
     /** Accessor props to validate against data (key = prop name) */
     dataAccessors: string[];

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

@@ -6,7 +6,8 @@
  * via spread to keep individual entries concise.
  *
  * Consumed by: validateProps.ts (validation engine), diagnoseConfig.ts,
- *              chartConfig.ts, check-schema-freshness.js
+ *              chartConfig.ts. Schema/validation parity is locked by the
+ *              Chart Spec Registry (`check:chart-specs`).
  */
 import type { ComponentSpec } from "./validateProps";
 export declare const VALIDATION_MAP: Record<string, ComponentSpec>;

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

@@ -3,15 +3,24 @@ interface SafeRenderProps {
     componentName: string;
     width: number;
     height: number;
+    /** @deprecated Retained for back-compat; no longer threaded into the
+     *  error boundary. Use `npx semiotic-ai --doctor` or import
+     *  `diagnoseConfig` from `semiotic/utils` for validation diagnostics. */
     chartProps?: Record<string, unknown>;
     children: React.ReactNode;
 }
 /**
- * Wraps a chart's rendered output with an error boundary.
- * If the chart throws during render, runs diagnoseConfig to produce
- * actionable fix suggestions alongside the error message.
+ * Wraps a chart's rendered output with an error boundary. If the chart
+ * throws during render, displays the error message with the component
+ * name.
+ *
+ * For richer prop diagnostics ("missing accessor", "wrong data shape",
+ * etc.), use `npx semiotic-ai --doctor` (CLI) or import `diagnoseConfig`
+ * from `semiotic/utils`. We intentionally don't bundle the validation
+ * map into every subpath import — it would add ~7KB gz to xy/ordinal/
+ * network just to power a fallback that only fires when render throws.
  */
-export declare function SafeRender({ componentName, width, height, chartProps, children }: SafeRenderProps): import("react/jsx-runtime").JSX.Element;
+export declare function SafeRender({ componentName, width, height, children }: SafeRenderProps): import("react/jsx-runtime").JSX.Element;
 /**
  * Renders a "No data available" placeholder when data is empty.
  * Returns null when data is present or emptyContent is `false`.

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

@@ -151,7 +151,8 @@ export interface AreaChartProps<TDatum extends Datum = Datum> extends BaseChartP
      */
     legendPosition?: LegendPosition;
     /**
-     * Tooltip configuration
+     * Tooltip configuration. Pass "multi" to show every area value at the
+     * hovered x position.
      */
     tooltip?: TooltipProp;
     /**
@@ -175,6 +176,7 @@ export interface AreaChartProps<TDatum extends Datum = Datum> extends BaseChartP
  *
  * @example
  * ```tsx
+ * // Multi-series areas with overlap transparency
  * <AreaChart
  *   data={[
  *     {x: 1, y: 10, category: 'A'},
@@ -188,6 +190,33 @@ export interface AreaChartProps<TDatum extends Datum = Datum> extends BaseChartP
  *   yLabel="Value"
  * />
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Single series with a vertical opacity gradient (tip → baseline fade)
+ * <AreaChart
+ *   data={data}
+ *   xAccessor="t"
+ *   yAccessor="value"
+ *   color="steelblue"
+ *   gradientFill={{ topOpacity: 0.8, bottomOpacity: 0.05 }}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Push mode — omit `data`, drive the chart through a ref. Use a
+ * // stable string id so `remove(id)` / `update(id, ...)` work later.
+ * const ref = useRef<RealtimeFrameHandle>(null)
+ * useEffect(() => {
+ *   const id = setInterval(() => {
+ *     const t = Date.now()
+ *     ref.current?.push({ id: String(t), x: t, y: Math.random() })
+ *   }, 200)
+ *   return () => clearInterval(id)
+ * }, [])
+ * return <AreaChart ref={ref} xAccessor="x" yAccessor="y" pointIdAccessor="id" />
+ * ```
  */
 export declare const AreaChart: {
     <TDatum extends Datum = Datum>(props: AreaChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;

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

@@ -32,13 +32,40 @@ export interface CandlestickChartProps<TDatum extends Datum = Datum> extends Bas
  *
  * @example
  * ```tsx
- * // Full OHLC
- * <CandlestickChart data={data} xAccessor="date"
- *   openAccessor="o" highAccessor="h" lowAccessor="l" closeAccessor="c" />
+ * // Full OHLC candlesticks
+ * <CandlestickChart
+ *   data={prices}
+ *   xAccessor="date"
+ *   openAccessor="o"
+ *   highAccessor="h"
+ *   lowAccessor="l"
+ *   closeAccessor="c"
+ * />
+ * ```
  *
- * // Range-only (e.g. min/max over a window)
- * <CandlestickChart data={data} xAccessor="date"
- *   highAccessor="max" lowAccessor="min" />
+ * @example
+ * ```tsx
+ * // Range-only (e.g. min/max bands per period)
+ * <CandlestickChart
+ *   data={data}
+ *   xAccessor="date"
+ *   highAccessor="max"
+ *   lowAccessor="min"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom up/down colors and bar width
+ * <CandlestickChart
+ *   data={prices}
+ *   xAccessor="date"
+ *   openAccessor="o"
+ *   highAccessor="h"
+ *   lowAccessor="l"
+ *   closeAccessor="c"
+ *   candlestickStyle={{ upColor: "#22c55e", downColor: "#ef4444", bodyWidth: 8 }}
+ * />
  * ```
  */
 export declare const CandlestickChart: {

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

@@ -51,6 +51,7 @@ export interface ConnectedScatterplotProps<TDatum extends Datum = Datum> extends
  *
  * @example
  * ```tsx
+ * // Country trajectory over time
  * <ConnectedScatterplot
  *   data={trajectory}
  *   xAccessor="gdp"
@@ -58,6 +59,29 @@ export interface ConnectedScatterplotProps<TDatum extends Datum = Datum> extends
  *   pointRadius={4}
  * />
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Explicit ordering field — sorts before connecting
+ * <ConnectedScatterplot
+ *   data={observations}
+ *   xAccessor="x"
+ *   yAccessor="y"
+ *   orderAccessor="timestamp"
+ *   orderLabel="Time"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Date-based ordering (Date or numeric values both work)
+ * <ConnectedScatterplot
+ *   data={dataByDate}
+ *   xAccessor="metric"
+ *   yAccessor="cost"
+ *   orderAccessor={(d) => new Date(d.month)}
+ * />
+ * ```
  */
 export declare const ConnectedScatterplot: {
     <TDatum extends Datum = Datum>(props: ConnectedScatterplotProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;

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

@@ -70,6 +70,57 @@ export interface MinimapChartProps<TDatum extends Datum = Datum> extends Omit<Ba
     /** Additional StreamXYFrame props */
     frameProps?: Partial<Omit<StreamXYFrameProps, "chartType" | "data" | "size">>;
 }
+/**
+ * MinimapChart - Line chart paired with a brushable overview minimap.
+ *
+ * Renders the same line data twice: a compressed overview (the minimap)
+ * and a zoomed detail view of the brushed range. Drag in the minimap to
+ * update the detail's domain. The minimap configuration (height, axes,
+ * brush direction) is nested under the `minimap` prop; brush state is
+ * exposed via `onBrush` (callback) and `brushExtent` (controlled value).
+ *
+ * Useful for long time series where the user needs both context and
+ * detail without losing their place in the full range.
+ *
+ * @example
+ * ```tsx
+ * // Time series with default minimap below the detail view
+ * <MinimapChart
+ *   data={timeSeries}
+ *   xAccessor="date"
+ *   yAccessor="value"
+ *   xScaleType="time"
+ *   minimap={{ height: 80, brushDirection: "x" }}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multi-series with a starting brush selection and an onBrush callback
+ * <MinimapChart
+ *   data={timeSeries}
+ *   xAccessor="t"
+ *   yAccessor="v"
+ *   lineBy="series"
+ *   colorBy="series"
+ *   minimap={{ height: 60, showAxes: true }}
+ *   brushExtent={[100, 500]}
+ *   onBrush={(extent) => console.log("brushed:", extent)}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Render the minimap above the detail rather than below
+ * <MinimapChart
+ *   data={timeSeries}
+ *   xAccessor="date"
+ *   yAccessor="value"
+ *   renderBefore
+ *   minimap={{ height: 50, background: "#f8fafc" }}
+ * />
+ * ```
+ */
 export declare function MinimapChart<TDatum extends Datum = Datum>(props: MinimapChartProps<TDatum>): import("react/jsx-runtime").JSX.Element;
 export declare namespace MinimapChart {
     var displayName: string;

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

@@ -65,6 +65,33 @@ export interface MultiAxisLineChartProps<TDatum extends Datum = Datum> extends B
  *
  * If `series` does not contain exactly 2 entries, renders as a standard
  * multi-line chart with a dev-mode console warning.
+ *
+ * @example
+ * ```tsx
+ * // Revenue (left axis, $) vs. signups (right axis, count)
+ * <MultiAxisLineChart
+ *   data={metrics}
+ *   xAccessor="month"
+ *   series={[
+ *     { yAccessor: "revenue", label: "Revenue", color: "#3b82f6", format: (v) => `$${v}` },
+ *     { yAccessor: "signups", label: "Signups", color: "#22c55e" },
+ *   ]}
+ *   legendPosition="bottom"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Pinning each axis extent independently
+ * <MultiAxisLineChart
+ *   data={metrics}
+ *   xAccessor="t"
+ *   series={[
+ *     { yAccessor: "tempC",   label: "°C", color: "#ef4444", extent: [-10, 40] },
+ *     { yAccessor: "humidity", label: "%", color: "#06b6d4", extent: [0, 100] },
+ *   ]}
+ * />
+ * ```
  */
 export declare const MultiAxisLineChart: {
     <TDatum extends Datum = Datum>(props: MultiAxisLineChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;

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

@@ -114,6 +114,27 @@ export interface QuadrantChartProps<TDatum extends Datum = Datum> extends BaseCh
  *   }}
  * />
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Effort vs. impact prioritization with a fixed 5×5 split.
+ * // Omit `xCenter`/`yCenter` to let the chart center on the domain midpoint.
+ * <QuadrantChart
+ *   data={features}
+ *   xAccessor="impact"
+ *   yAccessor="effort"
+ *   xCenter={5}
+ *   yCenter={5}
+ *   quadrants={{
+ *     topRight:    { label: "Quick wins",  color: "#22c55e" },
+ *     topLeft:     { label: "Maybe later", color: "#94a3b8" },
+ *     bottomRight: { label: "Big bets",    color: "#3b82f6" },
+ *     bottomLeft:  { label: "Skip",        color: "#ef4444" },
+ *   }}
+ *   colorBy="team"
+ *   sizeBy="estimate"
+ * />
+ * ```
  */
 export declare const QuadrantChart: {
     <TDatum extends Datum = Datum>(props: QuadrantChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;

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

@@ -49,16 +49,48 @@ export interface ScatterplotProps<TDatum extends Datum = Datum> extends BaseChar
     frameProps?: Partial<Omit<StreamXYFrameProps, "chartType" | "data" | "size">>;
 }
 /**
- * Scatterplot - Visualize relationships between two continuous variables
+ * Scatterplot - Visualize relationships between two continuous variables.
+ *
+ * Each row becomes a circle at `(xAccessor, yAccessor)`. Add a third
+ * dimension via {@link BubbleChart} (size encoding) or
+ * {@link ConnectedScatterplot} (point ordering). For matrix views of every
+ * pairwise combination, use {@link ScatterplotMatrix}.
  *
  * @example
  * ```tsx
+ * // Simple scatter
  * <Scatterplot
- *   data={[{x: 1, y: 10}, {x: 2, y: 20}]}
+ *   data={[{ x: 1, y: 10 }, { x: 2, y: 20 }]}
  *   xLabel="Time"
  *   yLabel="Value"
  * />
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Color by category, marginal histograms in axis margins
+ * <Scatterplot
+ *   data={observations}
+ *   xAccessor="age"
+ *   yAccessor="income"
+ *   colorBy="region"
+ *   showLegend
+ *   marginalGraphics={{ x: "histogram", y: "histogram" }}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Hover-highlight non-hovered series + click handler
+ * <Scatterplot
+ *   data={observations}
+ *   xAccessor="x"
+ *   yAccessor="y"
+ *   colorBy="cluster"
+ *   hoverHighlight
+ *   onClick={(d) => console.log(d)}
+ * />
+ * ```
  */
 export declare const Scatterplot: {
     <TDatum extends Datum = Datum>(props: ScatterplotProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;

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

@@ -56,6 +56,7 @@ export interface ScatterplotMatrixProps<TDatum extends Datum = Datum> extends Ba
  *
  * @example
  * ```tsx
+ * // Iris dataset — every pairwise field combination
  * <ScatterplotMatrix
  *   data={iris}
  *   fields={["sepalLength", "sepalWidth", "petalLength", "petalWidth"]}
@@ -64,6 +65,21 @@ export interface ScatterplotMatrixProps<TDatum extends Datum = Datum> extends Ba
  *   diagonal="histogram"
  * />
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Brush mode: drag in any cell to highlight matching points across the
+ * // matrix. The `crossfilter` mode excludes the brushed cell from its own
+ * // filter so it stays fully visible while the others dim non-matches.
+ * // Brush selections live in the matrix's internal selection store and do
+ * // not propagate to charts rendered outside the component.
+ * <ScatterplotMatrix
+ *   data={observations}
+ *   fields={["x", "y", "z"]}
+ *   hoverMode={false}
+ *   brushMode="crossfilter"
+ * />
+ * ```
  */
 export declare function ScatterplotMatrix<TDatum extends Datum = Datum>(props: ScatterplotMatrixProps<TDatum>): import("react/jsx-runtime").JSX.Element;
 export declare namespace ScatterplotMatrix {