semiotic 3.4.2 → 3.5.1

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

@@ -0,0 +1,60 @@
+/**
+ * Inlined replacement for the subset of `d3-time-format` semiotic
+ * uses (the `timeFormat(spec)` factory).
+ *
+ * Why this module exists: `d3-time-format` (~86KB) plus its `d3-time`
+ * peer (~40KB) ship a complete strftime engine with locale-data
+ * bundles we don't use. semiotic only consumes the strftime token
+ * parser — locale formatting can defer to `Intl.DateTimeFormat`,
+ * which is built into every modern runtime.
+ *
+ * What's implemented (the chart-axis-relevant subset):
+ *
+ *   - `%Y` — 4-digit year
+ *   - `%y` — 2-digit year (zero-padded)
+ *   - `%m` — 2-digit month (01–12)
+ *   - `%d` — 2-digit day (01–31)
+ *   - `%e` — day of month, space-padded (matches d3)
+ *   - `%H` — 2-digit hour, 24-hr (00–23)
+ *   - `%I` — 2-digit hour, 12-hr (01–12)
+ *   - `%M` — 2-digit minute (00–59)
+ *   - `%S` — 2-digit second (00–59)
+ *   - `%L` — 3-digit millisecond (000–999)
+ *   - `%p` — AM/PM
+ *   - `%b` — short month name (Jan, Feb …)
+ *   - `%B` — long month name (January, February …)
+ *   - `%a` — short weekday name (Mon, Tue …)
+ *   - `%A` — long weekday name (Monday, Tuesday …)
+ *   - `%j` — day of year (001–366)
+ *   - `%%` — literal `%`
+ *
+ * What's NOT implemented (rare in chart axis labels):
+ *
+ *   - `%U` / `%W` — week of year (Sunday/Monday-based)
+ *   - `%Z` / `%z` — timezone name / offset
+ *   - `%c` / `%x` / `%X` — locale-default date/time/full forms
+ *   - `%f` — microseconds (always 0 in JS Date anyway)
+ *
+ * Localized name forms (`%b`/`%B`/`%a`/`%A`) defer to
+ * `Intl.DateTimeFormat` pinned to `en-US`. `d3-time-format` ships
+ * with an en-US default locale (`d3-time-format`'s
+ * `timeFormatDefaultLocale` swap is opt-in), so pinning matches its
+ * default behavior — and crucially, keeps tick labels stable across
+ * environments. Using the runtime's ambient locale would change axis
+ * text per CI runner / browser system locale, which surfaces as
+ * baseline drift in pixel / SSR snapshot tests.
+ *
+ * This shim uses the local timezone (matching `d3-time-format`'s
+ * `timeFormat`); for UTC equivalence we'd add a `utcFormat` factory
+ * that mirrors `getUTC*` accessors. Add it to this module rather than
+ * re-introducing the dependency if a UTC formatter becomes necessary.
+ */
+/**
+ * Build a date formatter from a strftime-style spec string.
+ * Mirrors `d3.timeFormat(spec)`: returns `(date: Date) => string`.
+ *
+ * Tokens are scanned left-to-right; literal text between tokens
+ * passes through unchanged. The returned function uses the local
+ * timezone (matching d3-time-format's `timeFormat`).
+ */
+export declare function timeFormat(spec: string): (date: Date) => string;

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

@@ -71,6 +71,14 @@ export interface ChartSetupInput {
  * Output from useChartSetup.
  */
 export interface ChartSetupResult {
+    /**
+     * The input `data` array with `null`/non-object entries removed. Use
+     * this in place of the raw `data` prop when forwarding to the frame
+     * or doing any per-row iteration in the HOC body — it is identity-
+     * equal to the original prop when nothing was dropped, so consumer
+     * memo cache hits are preserved in the common case.
+     */
+    data: Array<Datum>;
     /** Color scale function, or undefined if no colorBy */
     colorScale: ((v: string) => string) | undefined;
     /** All unique category values from colorBy */

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,13 +151,28 @@ 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;
     /**
      * Annotation objects to render on the chart
      */
     annotations?: Datum[];
+    /**
+     * Fixed x domain `[min, max]`. Either bound may be `undefined` to leave
+     * that side data-derived. Useful for pinning a time axis to a known
+     * window (e.g. last 24 hours) so streamed updates don't shift the
+     * left/right edges as data flows in.
+     */
+    xExtent?: [number | undefined, number | undefined] | [number];
+    /**
+     * Fixed y domain `[min, max]`. Either bound may be `undefined` to leave
+     * that side data-derived. The fill baseline is the y-domain minimum, so
+     * setting `yExtent={[0, 100]}` anchors both the axis AND the area's
+     * baseline at 0 — the typical "percentage / counter" shape.
+     */
+    yExtent?: [number | undefined, number | undefined] | [number];
     /**
      * Additional StreamXYFrame props for advanced customization
      * For full control, consider using StreamXYFrame directly
@@ -175,6 +190,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 +204,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/BubbleChart.d.ts

@@ -110,6 +110,10 @@ export interface BubbleChartProps<TDatum extends Datum = Datum> extends BaseChar
      * Annotation objects to render on the chart
      */
     annotations?: Datum[];
+    /** Fixed x domain `[min, max]` (either bound may be undefined to leave that side data-derived). */
+    xExtent?: [number | undefined, number | undefined] | [number];
+    /** Fixed y domain `[min, max]` (either bound may be undefined to leave that side data-derived). */
+    yExtent?: [number | undefined, number | undefined] | [number];
     /**
      * Additional StreamXYFrame props for advanced customization
      * For full control, consider using StreamXYFrame directly

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

@@ -19,6 +19,10 @@ export interface CandlestickChartProps<TDatum extends Datum = Datum> extends Bas
     candlestickStyle?: CandlestickStyle;
     tooltip?: TooltipProp;
     annotations?: Datum[];
+    /** Fixed x domain `[min, max]` (either bound may be undefined to leave that side data-derived). */
+    xExtent?: [number | undefined, number | undefined] | [number];
+    /** Fixed y domain `[min, max]` (either bound may be undefined to leave that side data-derived). */
+    yExtent?: [number | undefined, number | undefined] | [number];
     enableHover?: boolean;
     showGrid?: boolean;
     frameProps?: Partial<Omit<StreamXYFrameProps, "chartType" | "data" | "size">>;
@@ -32,13 +36,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

@@ -37,6 +37,10 @@ export interface ConnectedScatterplotProps<TDatum extends Datum = Datum> extends
     legendInteraction?: LegendInteractionMode;
     /** Annotation objects to render on the chart */
     annotations?: Datum[];
+    /** Fixed x domain `[min, max]` (either bound may be undefined to leave that side data-derived). */
+    xExtent?: [number | undefined, number | undefined] | [number];
+    /** Fixed y domain `[min, max]` (either bound may be undefined to leave that side data-derived). */
+    yExtent?: [number | undefined, number | undefined] | [number];
     /** Additional StreamXYFrame props for advanced customization */
     frameProps?: Partial<Omit<StreamXYFrameProps, "chartType" | "data" | "size">>;
 }
@@ -51,6 +55,7 @@ export interface ConnectedScatterplotProps<TDatum extends Datum = Datum> extends
  *
  * @example
  * ```tsx
+ * // Country trajectory over time
  * <ConnectedScatterplot
  *   data={trajectory}
  *   xAccessor="gdp"
@@ -58,6 +63,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/Heatmap.d.ts

@@ -114,6 +114,10 @@ export interface HeatmapProps<TDatum extends Datum = Datum> extends BaseChartPro
      * Annotation objects to render on the chart
      */
     annotations?: Datum[];
+    /** Fixed x domain `[min, max]` (either bound may be undefined to leave that side data-derived). */
+    xExtent?: [number | undefined, number | undefined] | [number];
+    /** Fixed y domain `[min, max]` (either bound may be undefined to leave that side data-derived). */
+    yExtent?: [number | undefined, number | undefined] | [number];
     /**
      * Additional StreamXYFrame props for advanced customization
      * For full control, consider using StreamXYFrame directly

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

@@ -181,6 +181,18 @@ export interface LineChartProps<TDatum extends Datum = Datum> extends BaseChartP
      * envelope around the extrapolated forecast region.
      */
     forecast?: ForecastConfig;
+    /**
+     * Fixed x domain `[min, max]`. Either bound may be `undefined` to leave
+     * that side data-derived.
+     */
+    xExtent?: [number | undefined, number | undefined] | [number];
+    /**
+     * Fixed y domain `[min, max]`. Either bound may be `undefined` to leave
+     * that side data-derived. Wins over the auto-computed envelope extent
+     * when forecast bounds are present, so explicit user intent stays
+     * authoritative.
+     */
+    yExtent?: [number | undefined, number | undefined] | [number];
     /**
      * Additional StreamXYFrame props for advanced customization
      * For full control, consider using StreamXYFrame directly

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

@@ -67,9 +67,67 @@ export interface MinimapChartProps<TDatum extends Datum = Datum> extends Omit<Ba
     onBrush?: (extent: [number, number] | null) => void;
     /** Controlled brush extent */
     brushExtent?: [number, number];
+    /**
+     * Fixed y domain `[min, max]` (either bound may be undefined to leave
+     * that side data-derived). xExtent is reserved for brush selection on
+     * MinimapChart — pass `frameProps.xExtent` if you need to override the
+     * brushed x range from advanced consumers.
+     */
+    yExtent?: [number | undefined, number | undefined] | [number];
     /** 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;