semiotic 3.5.0 → 3.5.2

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

@@ -0,0 +1,75 @@
+import type { ReactNode } from "react";
+import type { Datum } from "./datumTypes";
+import type { Accessor, ChartAccessor } from "./types";
+import type { SelectionHookResult } from "./selectionUtils";
+import type { HoverData } from "../../stream/types";
+export interface AreaSeriesSetupOptions<TDatum extends Datum = Datum> {
+    /** Sparse-filtered data array (the HOC's `safeData`). */
+    safeData: TDatum[];
+    /** Original `data` prop — used to short-circuit to push-mode flatten. */
+    data: TDatum[] | undefined;
+    /** Group accessor (`areaBy` on the HOC). When set, flat data is
+     *  grouped into one series per distinct value. */
+    areaBy?: ChartAccessor<TDatum, string>;
+    /** Field on grouped objects that contains the coordinate array.
+     *  Convention: `"coordinates"`. Pre-grouped input is detected by
+     *  presence of this field on the first row. */
+    lineDataAccessor: string;
+    /** Effective color accessor (already resolved by HOC: AreaChart =
+     *  `colorBy`; StackedAreaChart = `colorBy || areaBy`). */
+    colorBy?: Accessor<string> | ChartAccessor<TDatum, string>;
+    /** Resolved categorical color scale from `useChartSetup`. */
+    colorScale: ((v: string) => string) | undefined;
+    /** Top-level uniform `color` prop. */
+    color?: string;
+    /** Top-level primitive props — applied last so they win over
+     *  HOC base + (future) user style. */
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+    /** Selection hook output (`setup.effectiveSelectionHook`). */
+    effectiveSelectionHook: SelectionHookResult | null | undefined;
+    /** Resolved selection config (`setup.resolvedSelection`). */
+    resolvedSelection: import("./types").SelectionConfig | undefined;
+    /** Area fillOpacity. @default 0.7 */
+    areaOpacity: number;
+    /** Render line on top of fill. @default true */
+    showLine: boolean;
+    /** Line stroke width. @default 2 */
+    lineWidth: number;
+    /** Render points along the line. @default false */
+    showPoints: boolean;
+    /** Point radius when `showPoints`. @default 3 */
+    pointRadius: number;
+    xAccessor: ChartAccessor<TDatum, number>;
+    yAccessor: ChartAccessor<TDatum, number>;
+    xLabel?: string;
+    yLabel?: string;
+    /** Tooltip-side x formatter — same signature as `AxisConfig.xFormat`
+     *  so the HOC can forward the prop verbatim. ReactNode return is OK. */
+    xFormat?: (d: number | Date | string, index?: number, allTicks?: number[]) => string | ReactNode;
+    yFormat?: (d: number | Date | string) => string | ReactNode;
+    /** Field used to label the series row in the default tooltip.
+     *  Typically `areaBy ?? colorBy`. */
+    groupField?: Accessor<string> | ChartAccessor<TDatum, string>;
+}
+export interface AreaSeriesSetupResult<TDatum extends Datum = Datum> {
+    /** Flat data array ready for `<StreamXYFrame data={…} />`. Empty
+     *  when the HOC is in push mode (no `data` prop). */
+    flattenedData: TDatum[];
+    /** Selection-aware line/area style fn. */
+    lineStyle: (d: Datum) => Record<string, string | number>;
+    /** Selection-aware point style fn — `undefined` when `showPoints`
+     *  is false so the HOC can spread it conditionally. */
+    pointStyle: ((d: Datum) => Record<string, string | number>) | undefined;
+    /** Default tooltip content fn for the chart. */
+    defaultTooltipContent: (hover: HoverData) => ReactNode;
+}
+/**
+ * Build the area-series pieces for an area-shaped XY HOC.
+ * The HOC still owns chart-specific frame props (chartType,
+ * gradientFill, normalize, baseline, stackOrder) and all the
+ * passthrough wiring; this hook covers the part both shared
+ * verbatim before extraction.
+ */
+export declare function useAreaSeriesSetup<TDatum extends Datum = Datum>(options: AreaSeriesSetupOptions<TDatum>): AreaSeriesSetupResult<TDatum>;

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

@@ -0,0 +1,48 @@
+import type { Datum } from "./datumTypes";
+import type { Accessor } from "./types";
+export interface EncodingDomainOptions<TDatum extends Datum = Datum> {
+    /** Encoding accessor (string field name or function). */
+    accessor: Accessor<number> | undefined;
+    /** Bounded chart data. Ignored when `isPushMode` is true. */
+    data: TDatum[];
+    /** When true, the hook tracks pushed values via the returned
+     *  `trackPushed` helper instead of reading `data`. */
+    isPushMode: boolean;
+}
+export interface EncodingDomainResult<TDatum extends Datum = Datum> {
+    /** `[min, max]` tuple over seen values. Undefined when no data has
+     *  been seen yet (push mode initial state, or bounded mode with
+     *  empty data + no accessor). */
+    domain: [number, number] | undefined;
+    /** Walk `items` and update the running domain. Bumps the version
+     *  counter when any min/max actually moves. No-op in bounded mode
+     *  — the hook reads from `data` directly there. */
+    trackPushed: (items: TDatum[]) => void;
+    /** Reset the running domain to empty. Paired with the HOC's
+     *  `clear()` override. No-op in bounded mode. */
+    reset: () => void;
+}
+/**
+ * Track a numeric encoding's `[min, max]` domain across bounded and
+ * push data sources.
+ *
+ * @example
+ * ```tsx
+ * // BubbleChart-style usage:
+ * const { domain: sizeDomain, trackPushed, reset } = useEncodingDomain({
+ *   accessor: sizeBy,
+ *   data: safeData,
+ *   isPushMode: data === undefined,
+ * })
+ *
+ * useFrameImperativeHandle(ref, {
+ *   variant: "xy", frameRef,
+ *   overrides: {
+ *     push: (d) => { trackPushed([d]); frameRef.current?.push(d) },
+ *     pushMany: (ds) => { trackPushed(ds); frameRef.current?.pushMany(ds) },
+ *     clear: () => { reset(); frameRef.current?.clear() },
+ *   },
+ * })
+ * ```
+ */
+export declare function useEncodingDomain<TDatum extends Datum = Datum>(options: EncodingDomainOptions<TDatum>): EncodingDomainResult<TDatum>;

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

@@ -1,6 +1,6 @@
 import type { Ref, RefObject, DependencyList } from "react";
 import type { RealtimeFrameHandle } from "../../realtime/types";
-type FrameVariant = "xy" | "network" | "geo-points";
+type FrameVariant = "xy" | "network" | "geo-points" | "geo-lines";
 interface Options {
     /**
      * Variant decides which default method bodies are emitted. The

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

@@ -0,0 +1,148 @@
+import type { ReactNode, ReactElement } from "react";
+import type { Datum } from "./datumTypes";
+import type { Accessor, ChartAccessor, SelectionConfig, LinkedHoverProp } from "./types";
+import type { OnObservationCallback } from "../../store/ObservationStore";
+import type { PartialMargin, MarginType } from "../../types/marginType";
+import { useChartSelection, useChartLegendAndMargin } from "./hooks";
+import type { LegendInteractionMode, LegendPosition, LegendInteractionState } from "./hooks";
+export interface NetworkChartSetupInput<TNode extends Datum = Datum, TEdge extends Datum = Datum> {
+    /** Raw `nodes` prop (may be undefined). */
+    nodes: TNode[] | undefined;
+    /** Raw `edges` prop (may be undefined). */
+    edges: TEdge[] | undefined;
+    /**
+     * When `true`, missing nodes are inferred from edge endpoints via
+     * `inferNodesFromEdges`. Sankey/Chord set this; ForceDirected leaves
+     * it `false` and treats both as required. Default: `true`.
+     */
+    inferNodes?: boolean;
+    /** Node id accessor for inference + tooltip identity. */
+    nodeIdAccessor?: ChartAccessor<TNode, string>;
+    /** Edge source accessor (used by `inferNodesFromEdges`). */
+    sourceAccessor?: ChartAccessor<TEdge, string>;
+    /** Edge target accessor (used by `inferNodesFromEdges`). */
+    targetAccessor?: ChartAccessor<TEdge, string>;
+    colorBy?: Accessor<string>;
+    colorScheme?: string | string[];
+    /** `undefined` defaults to "auto" (on when colorBy is set). */
+    showLegend?: boolean;
+    legendPosition?: LegendPosition;
+    legendInteraction?: LegendInteractionMode;
+    selection?: SelectionConfig;
+    linkedHover?: LinkedHoverProp;
+    onObservation?: OnObservationCallback;
+    onClick?: (datum: Datum, event: {
+        x: number;
+        y: number;
+    }) => void;
+    /** Used by useChartSelection for chart-type-stamped observation events. */
+    chartType: string;
+    chartId?: string;
+    /** Mode-resolved margin defaults from useChartMode. */
+    marginDefaults: MarginType;
+    /** User-provided margin override. */
+    userMargin?: PartialMargin;
+    width: number;
+    height: number;
+    loading?: boolean;
+    emptyContent?: ReactNode | false;
+    /**
+     * Which array drives the empty-state check. `"edges"` (default)
+     * fits Sankey/Chord/ProcessSankey where edges are the primary
+     * data shape and nodes are optional/inferred. `"nodes"` fits
+     * ForceDirectedGraph where both nodes and edges are required and
+     * empty-state should fire when the user supplied a sparse-only
+     * node list. The undefined-vs-empty distinction is preserved
+     * either way: undefined = push mode (don't show empty UI);
+     * present-but-empty = user supplied empty data (show empty UI).
+     */
+    emptyDataKey?: "edges" | "nodes";
+}
+export interface NetworkChartSetupResult {
+    /**
+     * Sparse-filtered nodes. When `inferNodes` was `true` and the
+     * caller didn't supply nodes, this is the inferred `[{id}]` array
+     * derived from edge endpoints. Otherwise it's just the input
+     * `nodes` with sparse holes removed.
+     */
+    safeNodes: Datum[];
+    /** Sparse-filtered edges. Identity-equal to input when nothing was dropped. */
+    safeEdges: Datum[];
+    /**
+     * Color scale built from `(safeNodes, colorBy, colorScheme)`.
+     * `undefined` when colorBy is unset.
+     */
+    colorScale: ((v: string) => string) | undefined;
+    /**
+     * Effective palette array. Resolved as:
+     * 1. `colorScheme` if it's an array.
+     * 2. ThemeProvider categorical if non-empty.
+     * 3. Named scheme lookup in `COLOR_SCHEMES`.
+     * 4. `DEFAULT_COLORS` fallback.
+     *
+     * Pass this to the frame's `colorScheme` prop so its internal
+     * `getNodeColor` (used for particles, hover, interactions) matches
+     * what the HOC's nodeStyle resolves.
+     */
+    effectivePalette: string[];
+    themeCategorical: string[] | undefined;
+    /** Distinct category values from `(safeNodes, colorBy)`, for legend interaction. */
+    allCategories: string[];
+    legendState: LegendInteractionState;
+    legend: ReturnType<typeof useChartLegendAndMargin>["legend"];
+    margin: MarginType;
+    legendPosition: LegendPosition;
+    customHoverBehavior: ReturnType<typeof useChartSelection>["customHoverBehavior"];
+    customClickBehavior: ReturnType<typeof useChartSelection>["customClickBehavior"];
+    /**
+     * The full selection-hook output. Most network HOCs only need the
+     * resolved hover/click behaviors above, but hierarchy charts
+     * (Treemap, CirclePack, TreeDiagram, OrbitDiagram) wrap node styles
+     * with selection state via `activeSelectionHook.isActive` /
+     * `.predicate`. Passed through verbatim so those charts don't need
+     * a parallel `useChartSelection` call.
+     */
+    activeSelectionHook: ReturnType<typeof useChartSelection>["activeSelectionHook"];
+    hoverSelectionHook: ReturnType<typeof useChartSelection>["hoverSelectionHook"];
+    crosshairSourceId: ReturnType<typeof useChartSelection>["crosshairSourceId"];
+    /** When non-null, render this element instead of the chart. */
+    loadingEl: ReactElement | null;
+    /** When non-null, render this element instead of the chart. */
+    emptyEl: ReactElement | null;
+}
+/**
+ * Run the consolidated network-HOC setup pipeline. Call this once
+ * after `useChartMode` and before any chart-specific logic. The
+ * returned `loadingEl`/`emptyEl` are early-exit slots — when either
+ * is non-null, return it before the frame.
+ *
+ * @example
+ * ```tsx
+ * const setup = useNetworkChartSetup({
+ *   nodes, edges,
+ *   inferNodes: true,
+ *   nodeIdAccessor, sourceAccessor, targetAccessor,
+ *   colorBy, colorScheme, showLegend, legendPosition, legendInteraction,
+ *   selection, linkedHover, onObservation, onClick,
+ *   chartType: "SankeyDiagram", chartId,
+ *   marginDefaults, userMargin, width, height,
+ *   loading, emptyContent,
+ * })
+ * if (setup.loadingEl) return setup.loadingEl
+ * if (setup.emptyEl) return setup.emptyEl
+ * return (
+ *   <StreamNetworkFrame
+ *     nodes={setup.safeNodes}
+ *     edges={setup.safeEdges}
+ *     colorScheme={setup.effectivePalette}
+ *     legend={setup.legend}
+ *     legendPosition={setup.legendPosition}
+ *     margin={setup.margin}
+ *     customHoverBehavior={setup.customHoverBehavior}
+ *     customClickBehavior={setup.customClickBehavior}
+ *     ...
+ *   />
+ * )
+ * ```
+ */
+export declare function useNetworkChartSetup<TNode extends Datum = Datum, TEdge extends Datum = Datum>(input: NetworkChartSetupInput<TNode, TEdge>): NetworkChartSetupResult;

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

@@ -0,0 +1,87 @@
+import type { Datum } from "./datumTypes";
+import type { Accessor, ChartAccessor } from "./types";
+import type { SelectionHookResult } from "./selectionUtils";
+export interface OrdinalPieceStyleOptions {
+    /** colorBy accessor — string field name or function */
+    colorBy?: Accessor<string> | ChartAccessor<Datum, string>;
+    /** Resolved categorical color scale (typically from useChartSetup). */
+    colorScale: ((v: string) => string) | undefined;
+    /** Top-level uniform `color` prop (BaseChartProps). Applied as a
+     *  default-fill primitive when `colorBy` is unset. */
+    color?: string;
+    /** Theme categorical palette (from useThemeCategorical). */
+    themeCategorical: string[] | undefined;
+    /** colorScheme prop — array or string scheme name. */
+    colorScheme?: string | string[];
+    /** Stable category-index map for default-fill cycling. */
+    categoryIndexMap: Map<string, number>;
+    /** User-supplied `frameProps.pieceStyle`. Accepts the looser
+     *  Frame-side `Style` type (typed fields like `fill: string`) or a
+     *  function returning the same shape; we don't pin a stricter
+     *  contract here because every ordinal HOC re-types pieceStyle
+     *  via its own props interface. */
+    userPieceStyle?: ((d: Datum, category?: string) => Record<string, unknown>) | Record<string, unknown> | unknown;
+    /** Top-level primitive props — applied last so they win over HOC base + user overlay. */
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+    /**
+     * Chart-shape defaults applied BEFORE the color resolution and
+     * user overlay. Use for properties that are intrinsic to the
+     * chart's mark shape (point radius `r`, fillOpacity for swarms /
+     * dots, etc.). User-supplied `frameProps.pieceStyle` and top-level
+     * primitive props can still override them.
+     *
+     * Static object form for shape-constant defaults
+     * (`{ r: dotRadius, fillOpacity: 0.8 }` — DotPlot). Function form
+     * for per-datum derivation (`(d) => ({ r: sizeBy ? getSize(d, ...) :
+     * pointRadius })` — SwarmPlot's size-encoded points). The function
+     * receives the same `(d, category)` args as user pieceStyle.
+     */
+    baseStyleExtras?: Record<string, string | number | undefined> | ((d: Datum, category?: string) => Record<string, string | number | undefined>);
+    /**
+     * After the base fill is resolved, also write it to `stroke`.
+     * Used by statistical-summary charts (BoxPlot / ViolinPlot /
+     * RidgelinePlot / Histogram) where the box outline should match
+     * the box fill rather than be a separate stroke. Top-level
+     * primitive `stroke` still wins via `mergeShapeStyle` if supplied.
+     */
+    linkStrokeToFill?: boolean;
+    /**
+     * When `colorBy` is unset, pass the per-piece `category` to
+     * `resolveDefaultFill` so each piece cycles through the
+     * colorScheme's palette (Pie / Donut / Funnel / radial charts —
+     * each slice/wedge wants its own color).
+     *
+     * When `false` (default), the category arg is omitted and
+     * `resolveDefaultFill` returns the first scheme color uniformly
+     * (BarChart / StackedBarChart / GroupedBarChart — bars without
+     * `colorBy` should be one color, since the user picked
+     * `categoryAccessor` but explicitly didn't ask for category-driven
+     * coloring). Locked by `bugRepros.test.tsx` BR-2.
+     */
+    cycleByCategory?: boolean;
+    /** Selection hook output (typically `setup.effectiveSelectionHook`). */
+    effectiveSelectionHook: SelectionHookResult | null | undefined;
+    /** Resolved selection config (typically `setup.resolvedSelection`). */
+    resolvedSelection: import("./types").SelectionConfig | undefined;
+}
+/**
+ * Build a memoized `pieceStyle` function that the chart can pass
+ * straight to `<StreamOrdinalFrame pieceStyle={…} />`. Composes the
+ * standard base-fill / user-overlay / primitive-prop / selection
+ * pipeline so each HOC doesn't re-derive it.
+ *
+ * @example
+ * ```tsx
+ * const pieceStyle = useOrdinalPieceStyle({
+ *   colorBy, colorScale: setup.colorScale,
+ *   color, themeCategorical, colorScheme, categoryIndexMap,
+ *   userPieceStyle: frameProps?.pieceStyle,
+ *   stroke, strokeWidth, opacity,
+ *   effectiveSelectionHook: setup.effectiveSelectionHook,
+ *   resolvedSelection: setup.resolvedSelection,
+ * })
+ * ```
+ */
+export declare function useOrdinalPieceStyle(options: OrdinalPieceStyleOptions): (d: Datum, category?: string) => Record<string, string | number | undefined>;

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

@@ -0,0 +1,57 @@
+import type { Datum } from "./datumTypes";
+import type { Accessor } from "./types";
+import type { ForecastConfig, AnomalyConfig } from "./statisticalOverlays";
+export interface SeriesFeaturesOptions {
+    /** Sparse-filtered chart data (the HOC's `safeData`). */
+    data: Datum[];
+    /** x accessor — string or function. */
+    xAccessor: Accessor<number | Date | string>;
+    /** y accessor — string or function. */
+    yAccessor: Accessor<number>;
+    /** Optional forecast configuration. When set, the hook adds
+     *  segment-tagged future points to `effectiveData` and appends
+     *  envelope/forecast-line annotations. */
+    forecast?: ForecastConfig | undefined;
+    /** Optional anomaly configuration (band + dot overlay). */
+    anomaly?: AnomalyConfig | undefined;
+    /** When the consuming HOC supports grouped series (e.g. LineChart's
+     *  `lineBy`), pass the grouping field name so the overlay pipeline
+     *  can do group-aware boundary duplication. Required when the same
+     *  data array carries multiple metric series interleaved by x. */
+    groupBy?: Accessor<string> | undefined;
+}
+export interface SeriesFeaturesResult {
+    /** Data to forward to the frame. When forecast adds future points,
+     *  this is the augmented set; otherwise the original `data`. */
+    effectiveData: Datum[];
+    /** Annotations the chart should merge into its own annotations
+     *  array (envelope, anomaly band, anomaly dots). Empty when
+     *  forecast/anomaly are unset or still loading. */
+    statisticalAnnotations: Datum[];
+    /** True when forecast is active and processedData differs from
+     *  the input data. Useful for HOC-side branches (e.g. LineChart's
+     *  compound-group accessor). */
+    hasForecast: boolean;
+    /** Resolved string key for the x axis — either the user's string
+     *  accessor or a synthetic key written by the bake step. The
+     *  forecast/anomaly pipeline reads through this key. */
+    xAccessorKey: string;
+    /** Resolved string key for the y axis (mirror of xAccessorKey). */
+    yAccessorKey: string;
+}
+/**
+ * Build series feature overlays (forecast + anomaly) for a chart.
+ * Returns the effective data + annotations to merge into the
+ * chart's stream-frame props. Returns the input data unchanged when
+ * neither prop is set.
+ *
+ * @example
+ * ```tsx
+ * const { effectiveData, statisticalAnnotations } = useSeriesFeatures({
+ *   data: safeData, xAccessor, yAccessor, forecast, anomaly,
+ * })
+ * const mergedAnnotations = [...(annotations || []), ...statisticalAnnotations]
+ * // forward effectiveData + mergedAnnotations to the frame
+ * ```
+ */
+export declare function useSeriesFeatures(options: SeriesFeaturesOptions): SeriesFeaturesResult;

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

@@ -0,0 +1,33 @@
+import type { RealtimeFrameHandle } from "../../realtime/types";
+/**
+ * Status enum exposed by the hook.
+ *
+ * - `"idle"` — no pushes have happened yet since mount.
+ * - `"active"` — at least one push has happened within the
+ *   threshold window.
+ * - `"stale"` — pushes have stopped or slowed; last push is older
+ *   than `staleThresholdMs`.
+ */
+export type StreamStatus = "idle" | "active" | "stale";
+export interface StreamStatusOptions {
+    /** Time in ms since the last push before status flips to `"stale"`.
+     *  @default 5000 */
+    staleThresholdMs?: number;
+    /** Polling interval for status transitions. Smaller = more
+     *  responsive but higher cost. @default 1000 */
+    pollIntervalMs?: number;
+}
+export interface StreamStatusResult<THandle extends RealtimeFrameHandle = RealtimeFrameHandle> {
+    /** Ref to pass to the chart's `ref` prop. The hook intercepts
+     *  push/pushMany calls on this ref so it can timestamp them. */
+    ref: React.MutableRefObject<THandle | null>;
+    /** Current status. Re-renders the consumer on transition. */
+    status: StreamStatus;
+    /** Timestamp (from `performance.now()`) of the most recent push,
+     *  or null when no push has happened yet. */
+    lastPushTime: number | null;
+}
+/**
+ * Track ingest activity on a push-API chart and expose status.
+ */
+export declare function useStreamStatus<THandle extends RealtimeFrameHandle = RealtimeFrameHandle>(options?: StreamStatusOptions): StreamStatusResult<THandle>;

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

@@ -0,0 +1,69 @@
+import type { Datum } from "./datumTypes";
+import type { Accessor, ChartAccessor } from "./types";
+import type { SelectionHookResult, SelectionStyleConfig } from "./selectionUtils";
+export interface XYLineStyleOptions {
+    /**
+     * Base stroke width. The top-level `strokeWidth` override below
+     * wins via `mergeShapeStyle` when both are supplied.
+     * @default 2
+     */
+    lineWidth?: number;
+    /** Color accessor (string field name or function). */
+    colorBy?: Accessor<string> | ChartAccessor<Datum, string>;
+    /** Resolved categorical color scale (typically from useChartSetup). */
+    colorScale?: ((v: string) => string);
+    /** Static color used as the fallback stroke when `colorBy` is unset. */
+    color?: string;
+    /** Custom stroke resolver. Wins over `colorBy`/`colorScale`/`color`.
+     *  Receives the datum and the optional `group` key the frame
+     *  passes through `resolveLineStyle`. */
+    resolveStroke?: (d: Datum, group?: string) => string;
+    /** When `true`, every line fills. When a `string[]`, only series
+     *  whose `group` key appears in the array fill. When omitted/false,
+     *  no fill is set on the style. */
+    fillArea?: boolean | string[];
+    /** Fill opacity used when `fillArea` triggers a fill. @default 0.3 */
+    areaOpacity?: number;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+    /** Selection hook result from `useChartSelection`/`useChartSetup`.
+     *  Pass `null`/`undefined` to skip dimming entirely (MinimapChart's
+     *  overview line and main line both skip selection wrapping). */
+    effectiveSelectionHook?: SelectionHookResult | null;
+    /** Resolved selection style config (matched/unmatched style overrides). */
+    resolvedSelection?: SelectionStyleConfig;
+}
+/**
+ * Returns a memoized `lineStyle` callback that the XY frame's
+ * `resolveLineStyle` invokes with `(datum, group?)`.
+ *
+ * @example
+ * ```tsx
+ * // LineChart's recipe collapses to a single hook call:
+ * const lineStyle = useXYLineStyle({
+ *   lineWidth, colorBy, colorScale, color, fillArea, areaOpacity,
+ *   stroke, strokeWidth, opacity,
+ *   effectiveSelectionHook, resolvedSelection,
+ * })
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // MultiAxisLineChart hands in a series-aware resolver:
+ * const lineStyle = useXYLineStyle({
+ *   lineWidth,
+ *   resolveStroke: (d) => seriesColorMap.get(d[SERIES_FIELD]) || seriesColors[0],
+ *   stroke, strokeWidth, opacity,
+ *   effectiveSelectionHook: setup.effectiveSelectionHook,
+ *   resolvedSelection: setup.resolvedSelection,
+ * })
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // MinimapChart's overview line: thin stroke, no selection, no primitives.
+ * const overviewLineStyle = useXYLineStyle({ lineWidth: 1, colorBy, colorScale })
+ * ```
+ */
+export declare function useXYLineStyle(options: XYLineStyleOptions): (d: Datum, group?: string) => Datum;

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

@@ -0,0 +1,87 @@
+import type { Datum } from "./datumTypes";
+import type { Accessor, ChartAccessor } from "./types";
+import type { SelectionHookResult } from "./selectionUtils";
+export interface XYPointStyleOptions {
+    /** colorBy accessor — string field name or function. */
+    colorBy?: Accessor<string> | ChartAccessor<Datum, string>;
+    /** Resolved categorical color scale (typically from useChartSetup). */
+    colorScale: ((v: string) => string) | undefined;
+    /** Top-level uniform `color` prop. Used as the fallback fill when
+     *  `colorBy` is unset. */
+    color?: string;
+    /**
+     * Fixed point radius. When `radiusFn` is supplied, that wins
+     * (per-datum sizing for BubbleChart / Scatterplot's `sizeBy`).
+     * @default 5
+     */
+    pointRadius?: number;
+    /** Per-datum radius resolver (e.g. wraps `getSize(d, sizeBy, …)`).
+     *  Ignored when undefined; HOCs with no `sizeBy` should pass it
+     *  unset and rely on `pointRadius`. */
+    radiusFn?: (d: Datum) => number;
+    /** Default fillOpacity. Charts override this through their own
+     *  prop name (`pointOpacity`, `bubbleOpacity`). @default 1 */
+    fillOpacity?: number;
+    /**
+     * Fallback fill resolver invoked when `colorBy` is unset. Used by
+     * QuadrantChart to pick a color from the quadrant the point lands
+     * in. When omitted, fallback is `color || DEFAULT_COLOR` (the
+     * standard Scatterplot/BubbleChart behavior).
+     */
+    fallbackFill?: (d: Datum) => string;
+    /**
+     * Static or per-datum extra style applied BEFORE color resolution
+     * and primitive overlay. Use for shape-constant defaults
+     * (BubbleChart's `{ stroke: bubbleStrokeColor, strokeWidth: 1 }`).
+     * If extras supply a `fill`, the standard color resolution is
+     * skipped — same bypass as `useOrdinalPieceStyle`. Lets
+     * ConnectedScatterplot drop in its viridis-by-order fill.
+     */
+    baseStyleExtras?: Record<string, string | number | undefined> | ((d: Datum) => Record<string, string | number | undefined>);
+    /** Top-level primitive props — applied last via `mergeShapeStyle`. */
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+    /** Selection hook output (typically `setup.effectiveSelectionHook`). */
+    effectiveSelectionHook: SelectionHookResult | null | undefined;
+    /** Resolved selection config (typically `setup.resolvedSelection`). */
+    resolvedSelection: import("./types").SelectionConfig | undefined;
+    /**
+     * For ConnectedScatterplot-style charts whose color depends on the
+     * point's position in an ordered sequence, the resolver may need
+     * the point's parent line. Defaults to identity (`d => d`).
+     * Same hook BarChart's `parentLine` cascade uses.
+     */
+    colorDatumAccessor?: (d: Datum) => Datum;
+}
+/**
+ * Build a memoized `pointStyle` function for an XY HOC.
+ *
+ * @example
+ * ```tsx
+ * // Scatterplot — sizeBy-driven radius, standard color fallback
+ * const pointStyle = useXYPointStyle({
+ *   colorBy, colorScale: setup.colorScale,
+ *   color, pointRadius, fillOpacity: pointOpacity,
+ *   radiusFn: sizeBy ? (d) => getSize(d, sizeBy, sizeRange, sizeDomain) : undefined,
+ *   stroke, strokeWidth, opacity,
+ *   effectiveSelectionHook: setup.effectiveSelectionHook,
+ *   resolvedSelection: setup.resolvedSelection,
+ * })
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // QuadrantChart — bespoke fallback fill from quadrant lookup
+ * const pointStyle = useXYPointStyle({
+ *   colorBy, colorScale: setup.colorScale, color,
+ *   pointRadius, fillOpacity: pointOpacity,
+ *   radiusFn: sizeBy ? (d) => getSize(d, sizeBy, sizeRange, sizeDomain) : undefined,
+ *   fallbackFill: (d) => quadrantColor(d, getXValue, getYValue, xCenter, yCenter, quadrants),
+ *   stroke, strokeWidth, opacity,
+ *   effectiveSelectionHook: setup.effectiveSelectionHook,
+ *   resolvedSelection: setup.resolvedSelection,
+ * })
+ * ```
+ */
+export declare function useXYPointStyle(options: XYPointStyleOptions): (d: Datum) => Record<string, string | number | undefined>;

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

@@ -5,6 +5,7 @@ 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";
+import type { ForecastConfig, AnomalyConfig } from "../shared/statisticalOverlays";
 /**
  * AreaChart component props
  */
@@ -159,6 +160,43 @@ export interface AreaChartProps<TDatum extends Datum = Datum> extends BaseChartP
      * Annotation objects to render on the chart
      */
     annotations?: Datum[];
+    /**
+     * Forecast overlay — extends the area with a tagged training /
+     * observed / forecast region and (optionally) a confidence
+     * envelope. Same shape as LineChart's `forecast` prop. Pair with
+     * `anomaly` for combined anomaly + forecast visualization.
+     *
+     * @example
+     * ```tsx
+     * <AreaChart data={obs} xAccessor="t" yAccessor="value"
+     *            forecast={{ trainEnd: 80, steps: 10, color: "#6366f1" }} />
+     * ```
+     */
+    forecast?: ForecastConfig;
+    /**
+     * Anomaly overlay — adds a ±σ band and per-point anomaly dots.
+     * Standalone (without forecast) gives raw anomaly detection.
+     *
+     * @example
+     * ```tsx
+     * <AreaChart data={obs} anomaly={{ threshold: 2 }} />
+     * ```
+     */
+    anomaly?: AnomalyConfig;
+    /**
+     * 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