semiotic 3.5.1 → 3.5.3

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

@@ -0,0 +1,59 @@
+/**
+ * regressionUtils — sugar for the `trend` annotation.
+ *
+ * The `trend` annotation type (see annotationRules.tsx) already
+ * computes and renders linear / polynomial / LOESS regression lines
+ * for any chart that exposes x/y scales. This module wraps that into
+ * a chart-prop ergonomic — `regression={true}`, `regression="loess"`,
+ * or a full config object — so users don't have to author an
+ * annotation object by hand for the most common cases.
+ *
+ * Mirrors the shape of LineChart's `forecast` and `anomaly` props,
+ * which are likewise sugar over annotation-side work.
+ */
+import type { Datum } from "./datumTypes";
+/** Regression methods supported by the trend annotation. */
+export type RegressionMethod = "linear" | "polynomial" | "loess";
+/**
+ * Full regression configuration. All visual props mirror the
+ * underlying `trend` annotation; users dropping into the `annotations`
+ * array directly can pass the same shape.
+ */
+export interface RegressionConfig {
+    /** Regression method. @default "linear" */
+    method?: RegressionMethod;
+    /** LOESS bandwidth (0–1). Lower = more local detail. @default 0.3 */
+    bandwidth?: number;
+    /** Polynomial order (only for `method: "polynomial"`). @default 2 */
+    order?: number;
+    /** Stroke color for the regression line. @default "#6366f1" */
+    color?: string;
+    /** Stroke width. @default 2 */
+    strokeWidth?: number;
+    /** Dash pattern. @default "6,3" */
+    strokeDasharray?: string;
+    /** Optional label rendered at the line's right end. */
+    label?: string;
+}
+/**
+ * Prop shape on chart HOCs. The boolean form gives users a
+ * "just draw a regression line" toggle; the string form picks the
+ * method with default styling; the object form opens up the full
+ * configuration. Mirrors `forecast` / `anomaly` on LineChart.
+ */
+export type RegressionProp = boolean | RegressionMethod | RegressionConfig;
+/**
+ * Convert a `regression` prop value into the trend-annotation object
+ * to splice into the chart's annotations array. Returns `undefined`
+ * when the prop is falsy so callers can skip the spread.
+ *
+ * @example
+ * ```ts
+ * const trendAnn = buildRegressionAnnotation(regression)
+ * const annotations = [
+ *   ...(trendAnn ? [trendAnn] : []),
+ *   ...(userAnnotations || []),
+ * ]
+ * ```
+ */
+export declare function buildRegressionAnnotation(regression: RegressionProp | undefined): Datum | undefined;

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

@@ -65,5 +65,12 @@ export declare const DEFAULT_SELECTION_OPACITY = 0.5;
  * Dimming opacity is resolved in this order:
  * 1. `config.unselectedOpacity` (explicit, usually per-chart or theme-merged)
  * 2. `DEFAULT_SELECTION_OPACITY`
+ *
+ * Variadic in the trailing args so callers can pass `(datum, group)` —
+ * the `group` argument that `PipelineStore.resolveLineStyle` threads
+ * through for line/area styles must reach the wrapped base function,
+ * or group-dependent styling (`fillArea: string[]`, `resolveStroke(d,
+ * group)` in `useXYLineStyle`'s MultiAxisLineChart path) silently
+ * drops to its no-group branch whenever a selection is active.
  */
-export declare function wrapStyleWithSelection(baseStyleFn: (d: Datum) => Datum, selectionHook: SelectionHookResult | null, config?: SelectionStyleConfig): (d: Datum) => Datum;
+export declare function wrapStyleWithSelection<TArgs extends unknown[]>(baseStyleFn: (d: Datum, ...args: TArgs) => Datum, selectionHook: SelectionHookResult | null, config?: SelectionStyleConfig): (d: Datum, ...args: TArgs) => Datum;

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

@@ -43,6 +43,11 @@ export interface BaseMetadataProps {
     accessibleTable?: boolean;
     className?: string;
     animate?: AnimateProp;
+    /** Strictly speaking not "metadata" — but the spread-when-defined
+     *  pattern is identical, and every XY/ordinal HOC needs to forward
+     *  this to the frame. Bundling it here avoids a parallel helper
+     *  + 22 separate adoption edits. */
+    axisExtent?: import("./axisExtent").AxisExtentMode;
 }
 export declare function buildBaseMetadataProps(input: BaseMetadataProps): BaseMetadataProps;
 /**

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

@@ -21,6 +21,17 @@ export interface TooltipFieldConfig {
 export declare function accessorName(acc: string | ((...args: any[]) => any)): string;
 export declare function formatVal(v: unknown): string;
 export declare function resolveValue(d: Datum, acc: string | ((d: Datum) => any)): unknown;
+/**
+ * Build TooltipFieldConfig rows for a `band` prop config so the default
+ * tooltip surfaces envelope values automatically. Reads from the
+ * `bands` array the hover handler synthesizes onto the datum — one
+ * row pair per configured band (low + high). String accessors are
+ * used verbatim as labels; function accessors fall back to "low"/"high".
+ *
+ * Returns an empty array when band is not configured, so the spread at
+ * the call site is a no-op for the common case.
+ */
+export declare function bandTooltipFields(band: unknown, valueFormat?: (v: any, ...rest: any[]) => React.ReactNode): TooltipFieldConfig[];
 /**
  * Build a default tooltipContent function for StreamXYFrame HOCs.
  * Receives HoverData ({ data, time, value, x, y }) and renders

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

@@ -78,6 +78,12 @@ export interface BaseChartProps {
     chartId?: string;
     /** Show a loading skeleton placeholder */
     loading?: boolean;
+    /** Custom content to render in place of the default skeleton when `loading` is `true`.
+     *  Sibling to `emptyContent` — use for branded loading states or progress UI.
+     *  When omitted, the built-in shimmer-bar skeleton renders.
+     *  Pass `false` to suppress the loading UI entirely (an outer wrapper's
+     *  loading state takes over). */
+    loadingContent?: React.ReactNode | false;
     /** Custom content to render when data is empty. Set to `false` to disable empty state. */
     emptyContent?: React.ReactNode | false;
     /** Uniform fill color for all data marks. Overrides colorScheme and theme categorical.
@@ -117,6 +123,19 @@ export interface BaseChartProps {
      * `true` uses defaults (300ms ease-out, intro enabled). Object form allows customization.
      * Set `{ intro: false }` to disable the animated intro on first render. */
     animate?: AnimateProp;
+    /** Axis extent mode. `"nice"` (default) uses d3-scale's rounded
+     *  tick generator — labels stay round but ticks may sit inside the
+     *  data domain. `"exact"` pins the first and last tick to the
+     *  actual data min and max with equidistant intermediate ticks.
+     *  Useful when a fixed scale (gauge, score band, KPI dial) needs
+     *  endpoints to read as the actual boundaries.
+     *
+     *  Applies to:
+     *  - XY charts: both x and y axes (linear, time, log).
+     *  - Ordinal charts: the value (r) axis only — the categorical
+     *    axis is a band scale and doesn't have a numeric tick set.
+     *  - Network / geo / hierarchy charts: no-op (no continuous axis). */
+    axisExtent?: import("./axisExtent").AxisExtentMode;
 }
 /**
  * Axis configuration props

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

@@ -0,0 +1,78 @@
+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 | Date | string>;
+    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>;
+    /** Optional band prop — when set, the default tooltip surfaces a
+     *  pair of rows per band (low + high). Threaded through verbatim. */
+    band?: unknown;
+}
+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/useChartSetup.d.ts

@@ -60,6 +60,8 @@ export interface ChartSetupInput {
     hoverHighlight?: boolean;
     /** Loading state */
     loading: boolean | undefined;
+    /** Custom content rendered in place of the default skeleton while `loading` is true. */
+    loadingContent?: ReactNode | false;
     /** Empty content override */
     emptyContent?: ReactNode;
     /** Resolved width from useChartMode */

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

@@ -64,6 +64,7 @@ interface DataSetupOptions extends ScaffoldOptions {
     }) => void;
     chartId?: string;
     loading?: boolean;
+    loadingContent?: ReactNode | false;
     emptyContent?: ReactNode;
 }
 interface DataSetupResult<TFrameHandle> extends ScaffoldResult<TFrameHandle> {

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,150 @@
+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;
+    /** Custom content rendered in place of the default skeleton while `loading` is true. */
+    loadingContent?: ReactNode | false;
+    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>;