semiotic 3.4.2 → 3.5.1

package/dist/components/charts/realtime/RealtimeHeatmap.d.ts

@@ -108,16 +108,34 @@ export interface RealtimeHeatmapProps<TDatum extends Datum = Datum> {
  *
  * @example
  * ```tsx
+ * // Count-aggregated heatmap — each push lands in a (time-bin × value-bin) cell
  * const ref = useRef<RealtimeFrameHandle>(null)
- * ref.current.push({ time: Date.now(), x: 42, y: 7 })
+ * useEffect(() => {
+ *   const id = setInterval(() => ref.current?.push({ time: Date.now(), y: Math.random() * 10 }), 50)
+ *   return () => clearInterval(id)
+ * }, [])
+ * return (
+ *   <RealtimeHeatmap
+ *     ref={ref}
+ *     timeAccessor="time"
+ *     valueAccessor="y"
+ *     heatmapXBins={30}
+ *     heatmapYBins={20}
+ *     aggregation="count"
+ *   />
+ * )
+ * ```
  *
+ * @example
+ * ```tsx
+ * // Mean aggregation with a sequential color scheme; useful for sensor density maps
  * <RealtimeHeatmap
  *   ref={ref}
  *   timeAccessor="time"
  *   valueAccessor="y"
- *   heatmapXBins={30}
- *   heatmapYBins={20}
- *   aggregation="count"
+ *   aggregation="mean"
+ *   colorScheme="viridis"
+ *   windowSize={500}
  * />
  * ```
  */

package/dist/components/charts/realtime/RealtimeHistogram.d.ts

@@ -148,15 +148,18 @@ export interface RealtimeTemporalHistogramProps<TDatum extends Datum = Datum> {
  *
  * @example
  * ```tsx
- * // Simple histogram
+ * // Simple temporal histogram — push each event, the chart bins by time
  * <RealtimeTemporalHistogram
  *   ref={ref}
  *   binSize={20}
  *   fill="#007bff"
  *   enableHover
  * />
+ * ```
  *
- * // Stacked by category
+ * @example
+ * ```tsx
+ * // Stacked by category — same push API, color by status field
  * <RealtimeTemporalHistogram
  *   ref={ref}
  *   binSize={25}

package/dist/components/charts/realtime/RealtimeLineChart.d.ts

@@ -110,14 +110,35 @@ export interface RealtimeLineChartProps<TDatum extends Datum = Datum> {
  *
  * @example
  * ```tsx
+ * // Single streaming series — push each datum, the chart slides
  * const ref = useRef<RealtimeFrameHandle>(null)
+ * useEffect(() => {
+ *   const id = setInterval(() => ref.current?.push({ time: Date.now(), value: Math.random() }), 100)
+ *   return () => clearInterval(id)
+ * }, [])
+ * return (
+ *   <RealtimeLineChart
+ *     ref={ref}
+ *     stroke="#007bff"
+ *     strokeWidth={2}
+ *     windowSize={200}
+ *     enableHover
+ *   />
+ * )
+ * ```
  *
+ * @example
+ * ```tsx
+ * // Decay + pulse — older points fade, newly-pushed points flash
  * <RealtimeLineChart
  *   ref={ref}
- *   stroke="#007bff"
+ *   timeAccessor="t"
+ *   valueAccessor="v"
+ *   stroke="#0b5fff"
  *   strokeWidth={2}
- *   windowSize={200}
- *   enableHover
+ *   decay={{ type: "linear" }}
+ *   pulse={{ type: "fade", durationMs: 400 }}
+ *   windowSize={500}
  * />
  * ```
  */

package/dist/components/charts/realtime/RealtimeSwarmChart.d.ts

@@ -112,6 +112,7 @@ export interface RealtimeSwarmChartProps<TDatum extends Datum = Datum> {
  *
  * @example
  * ```tsx
+ * // Per-sensor swarm — each push is a discrete dot, color by category
  * <RealtimeSwarmChart
  *   ref={ref}
  *   radius={4}
@@ -120,6 +121,17 @@ export interface RealtimeSwarmChartProps<TDatum extends Datum = Datum> {
  *   colors={{ sensor1: "#007bff", sensor2: "#28a745" }}
  * />
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Threshold-coloured outliers via a y-threshold annotation
+ * <RealtimeSwarmChart
+ *   ref={ref}
+ *   radius={3}
+ *   annotations={[{ type: "y-threshold", value: 0.9, color: "#dc3545", label: "alert" }]}
+ *   windowSize={300}
+ * />
+ * ```
  */
 export declare const RealtimeSwarmChart: {
     <TDatum extends Datum = Datum>(props: RealtimeSwarmChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;

package/dist/components/charts/realtime/RealtimeWaterfallChart.d.ts

@@ -111,6 +111,7 @@ export interface RealtimeWaterfallChartProps<TDatum extends Datum = Datum> {
  *
  * @example
  * ```tsx
+ * // Trade-flow waterfall — push each delta, the chart accumulates from baseline
  * <RealtimeWaterfallChart
  *   ref={ref}
  *   positiveColor="#28a745"
@@ -119,6 +120,19 @@ export interface RealtimeWaterfallChartProps<TDatum extends Datum = Datum> {
  *   windowSize={300}
  * />
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Themed via CSS variables — same chart, brand colors via the theme provider
+ * <ThemeProvider theme="bi-tool">
+ *   <RealtimeWaterfallChart
+ *     ref={ref}
+ *     positiveColor="var(--semiotic-success)"
+ *     negativeColor="var(--semiotic-danger)"
+ *     stroke="var(--semiotic-border)"
+ *   />
+ * </ThemeProvider>
+ * ```
  */
 export declare const RealtimeWaterfallChart: {
     <TDatum extends Datum = Datum>(props: RealtimeWaterfallChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;

package/dist/components/charts/realtime/defaultRealtimeTooltip.d.ts

@@ -0,0 +1,67 @@
+import type { ReactNode } from "react";
+import type { Datum } from "../shared/datumTypes";
+import type { HoverData } from "../../realtime/types";
+import type { ChartAccessor } from "../shared/types";
+interface DefaultRealtimeTooltipOptions<TDatum extends Datum = Datum> {
+    timeAccessor?: ChartAccessor<TDatum, number>;
+    valueAccessor?: ChartAccessor<TDatum, number>;
+    /**
+     * Field-name aliases shown in the tooltip ("x" / "y" by default).
+     * Some Realtime HOCs may want to show "time" / "value" or
+     * "category" / "count" — pass overrides here. The strings are
+     * cosmetic; data lookup still uses `timeAccessor`/`valueAccessor`.
+     */
+    xLabel?: string;
+    yLabel?: string;
+}
+/**
+ * Build a default tooltip renderer for a Realtime HOC. Returns a
+ * function compatible with `tooltipContent: (d: HoverData) => ReactNode`.
+ */
+export declare function buildDefaultRealtimeTooltip<TDatum extends Datum = Datum>(options?: DefaultRealtimeTooltipOptions<TDatum>): (d: HoverData) => ReactNode;
+/**
+ * Waterfall-specific default tooltip.
+ *
+ * The waterfall scene builder enriches each rect's datum with
+ * `baseline` (cumulative at the start of the bar), `cumEnd`
+ * (cumulative at the top of the bar), and `delta` (signed per-tick
+ * change). The default `x:`/`y:` shape is misleading for waterfall
+ * because the bar's vertical projection encodes the *cumulative*
+ * total — hovering a bar high on the chart and seeing the per-tick
+ * delta felt disconnected from what the bar visually showed.
+ *
+ * This tooltip surfaces all three relevant quantities:
+ *   x:  <time>        (the configured timeAccessor)
+ *   Δ:  +5.2 / -3.1   (the per-tick delta, sign-prefixed)
+ *   total: 87.4       (the cumulative running sum at the bar top)
+ *
+ * Falls back to the canonical x/y shape if the enriched fields are
+ * absent (e.g. a static-data render that bypassed the waterfall
+ * scene builder).
+ */
+export declare function buildWaterfallTooltip<TDatum extends Datum = Datum>(options?: DefaultRealtimeTooltipOptions<TDatum>): (d: HoverData) => ReactNode;
+/**
+ * Heatmap-specific default tooltip.
+ *
+ * The streaming heatmap aggregates raw points into 2D bins; each cell's
+ * datum is `{ xi, yi, value, count, sum, xCenter, yCenter, agg }`. The
+ * generic `x: <time>, y: <value>` shape is meaningless because the cell
+ * doesn't carry the user's original fields — it carries bin indices and
+ * aggregated counts.
+ *
+ * This tooltip surfaces the user-relevant info:
+ *   x:     <data-space x-center of the bin>
+ *   y:     <data-space y-center of the bin>
+ *   count: 12               (when datum.count is present — streaming path)
+ *   sum:   142              (when agg === "sum")
+ *   mean:  11.83            (when agg === "mean")
+ *
+ * For `agg === "sum"` we always surface the sum (it's the metric the
+ * heatmap is colored by, even when sum happens to equal count).
+ *
+ * Falls back to the canonical x/y shape if the enriched fields are
+ * absent (e.g. a non-streaming render path); the count/sum/mean rows
+ * only appear when the matching field is present on the datum.
+ */
+export declare function buildHeatmapTooltip<TDatum extends Datum = Datum>(options?: DefaultRealtimeTooltipOptions<TDatum>): (d: HoverData) => ReactNode;
+export {};

package/dist/components/charts/realtime/resolveWindowSize.d.ts

@@ -0,0 +1,26 @@
+import type { Datum } from "../shared/datumTypes";
+/**
+ * Auto-fit the realtime ring buffer to bounded data.
+ *
+ * Realtime HOCs accept both a static `data` array (bounded use) and
+ * ref-based `push()` (streaming use). The underlying ring buffer is
+ * sized by `windowSize`, which has historically defaulted to 200.
+ * That default is fine for streaming — the buffer scrolls — but
+ * silently truncates static `data` arrays larger than 200 points
+ * (the older entries fall off the back as new ones arrive during the
+ * single bulk ingest, which looks like a bug from the consumer's
+ * perspective).
+ *
+ * Resolution rule:
+ *   - **Explicit user `windowSize` always wins** — they may want a
+ *     specific cap regardless of the data size (e.g. preview the
+ *     last 50 of a 1000-point archive).
+ *   - **Otherwise** auto-fit to `max(data.length, 200)`. The 200
+ *     floor preserves the streaming-default ring size when `data`
+ *     is empty/undefined; data-size sets the floor when present so
+ *     bounded ingestion never drops points.
+ *
+ * Replaces the historical `windowSize={data.length}` workaround that
+ * appeared in our own theming docs and likely consumer code.
+ */
+export declare function resolveRealtimeWindowSize(windowSizeProp: number | undefined, data: Datum[] | undefined): number;

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

@@ -0,0 +1,91 @@
+/**
+ * Single source of truth for per-chart prop specifications.
+ *
+ * Three downstream consumers used to maintain their own per-chart entries:
+ *   - `ai/schema.json`                                    (LLM tool definitions)
+ *   - `src/components/charts/shared/validationMap.ts`     (runtime prop validation)
+ *   - `ai/componentMetadata.cjs`                          (category buckets)
+ *
+ * Today, `ai/schema.json` is generated from this registry — run
+ * `npm run docs:chart-specs:schema` to refresh it after editing a spec.
+ * `validationMap.ts` and `ai/componentMetadata.cjs` are still hand-edited
+ * but are gated for parity by the registry: `check:chart-specs` (run via
+ * `npm run check:chart-specs`) regenerates each chart's schema/
+ * validation/metadata entries with the pure functions in
+ * `scripts/lib/chart-specs-generators.mjs` and fails the build on any
+ * drift, including unexpected adds or removes that bypass the registry.
+ *
+ * Design notes:
+ *   - Shared prop bags (common, xyAxis, ordinalAxis) live in `PROP_BAGS` and
+ *     are referenced by name in each spec so common surface stays in one place.
+ *   - The runtime PropType set ("string" | "number" | "boolean" | "array" |
+ *     "object" | "function") is broader than JSON Schema's, but the schema
+ *     generator emits whatever types this registry declares — including
+ *     "function" inside type unions (canonical entries like
+ *     `RidgelinePlot.tooltip: ["function", "object"]` and
+ *     `SwimlaneChart.onBrush: "function"` already use this convention; LLMs
+ *     read the union and pick a non-function alternative when they can't
+ *     supply a function value). For props that are purely callbacks or
+ *     escape hatches an LLM cannot meaningfully populate, tag the spec
+ *     with `omitFromSchema: true` to keep it in validationMap but out of
+ *     schema.json. `description` and `default` annotations surface in
+ *     schema.json (and MCP responses) but are dropped from validationMap
+ *     (which only reads `type` and `enum`).
+ */
+export type PropType = "string" | "number" | "boolean" | "array" | "object" | "function";
+export type DataShape = "array" | "object" | "network" | "realtime" | "none";
+export type ChartCategory = "xy" | "ordinal" | "network" | "geo" | "realtime";
+export interface ChartPropSpec {
+    /** Allowed runtime types. May be a single value or a union. */
+    type: PropType | PropType[];
+    /** Allowed enum values for string-typed props. */
+    enum?: readonly string[];
+    /** Default value surfaced in schema.json (and shown in MCP getSchema). */
+    default?: unknown;
+    /** Schema-side description; surfaces in LLM tool definitions. */
+    description?: string;
+    /**
+     * When true, the prop is included in validationMap but omitted from
+     * schema.json. Use for handler/callback props (`onClick`, `tooltip`)
+     * and pass-through escape hatches (`frameProps`) that LLMs shouldn't
+     * be asked to populate.
+     */
+    omitFromSchema?: boolean;
+}
+export interface ChartSpec {
+    /** Component name, must match the React export. */
+    name: string;
+    category: ChartCategory;
+    /** Human-readable description for schema.tools[].function.description. */
+    description: string;
+    /** Statically-required props. Push-mode optionality lives in behaviorContracts. */
+    required: string[];
+    /** Drives validation dispatch (validateArrayData / validateNetworkData / …). */
+    dataShape: DataShape;
+    /** Accessor props validated against the data shape at runtime. */
+    dataAccessors: string[];
+    /**
+     * Shared prop bags this chart composes. Bag props are merged in left-to-right
+     * order; chart-specific `ownProps` win on key collision.
+     */
+    propBags: ReadonlyArray<keyof typeof PROP_BAGS>;
+    /** Chart-specific prop spec, overlaid on top of the composed bags. */
+    ownProps: Record<string, ChartPropSpec>;
+}
+export declare const PROP_BAGS: {
+    readonly common: Record<string, ChartPropSpec>;
+    readonly xyAxis: Record<string, ChartPropSpec>;
+    readonly ordinalAxis: Record<string, ChartPropSpec>;
+    readonly realtime: Record<string, ChartPropSpec>;
+};
+export declare const ORIENTATION_ENUM: readonly ["vertical", "horizontal"];
+export declare const HORIZONTAL_VERTICAL_ENUM: readonly ["horizontal", "vertical"];
+export declare const LEGEND_POSITION_ENUM: readonly ["right", "left", "top", "bottom"];
+export declare const CURVE_ENUM: readonly ["linear", "monotoneX", "monotoneY", "step", "stepAfter", "stepBefore", "basis", "cardinal", "catmullRom"];
+export declare const CHART_MODE_ENUM: readonly ["primary", "context", "sparkline"];
+export declare const CHART_SPECS: Record<string, ChartSpec>;
+/**
+ * Compose a chart's full prop set (bags + ownProps) in deterministic order.
+ * ownProps wins on key collision so a chart can override a shared default.
+ */
+export declare function composeProps(spec: ChartSpec): Record<string, ChartPropSpec>;

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

@@ -0,0 +1,62 @@
+/**
+ * Inlined replacement for the subset of `d3-scale-chromatic` that
+ * `semiotic` actually uses.
+ *
+ * Why this module exists: `d3-scale-chromatic` ships ~76KB of palette
+ * data and pulls in `d3-color` + `d3-interpolate` transitively. We
+ * use exactly 3 categorical schemes, 12 sequential single-/multi-hue
+ * interpolators, and 7 diverging interpolators. Inlining at the right
+ * granularity is much smaller than the dependency.
+ *
+ * Fidelity choices:
+ *   - **Categorical schemes** are byte-identical to d3 — they're just
+ *     hex-string arrays of the canonical Tableau / ColorBrewer / d3
+ *     palettes.
+ *   - **Sequential and diverging interpolators** sample the canonical
+ *     palette at coarser resolution than d3's ~256-stop precomputed
+ *     LUTs. d3 uses a Catmull-Rom basis spline through the same stops;
+ *     we use linear RGB interpolation. The visible difference at
+ *     typical N=5–9 binning or continuous heatmap rendering is
+ *     imperceptible (RGB-linear and basis-spline produce ΔE < 1 across
+ *     the gradient for these palettes — well under perceptual
+ *     threshold). Behavior is identical for the discrete-binning use
+ *     cases that dominate consumer code.
+ *
+ * Each interpolator has the same signature as d3's: `(t: number) =>
+ * string`, where `t ∈ [0, 1]` and the return is a `#rrggbb` CSS color
+ * string (matching d3-color's `Rgb#toString()` output for opaque
+ * colors, which is what flows into JSX `stroke=` / `fill=` attributes
+ * downstream). `t` outside [0, 1] is clamped, matching d3 behavior.
+ *
+ * Palette stops are taken from d3-scale-chromatic and ColorBrewer
+ * source: https://github.com/d3/d3-scale-chromatic
+ *
+ * Add to this module rather than re-introducing the dependency if a
+ * new scheme is needed — copy the relevant palette strings from the
+ * d3 source and add the export.
+ */
+/** D3's standard 10-color categorical palette (Vega Category10). */
+export declare const schemeCategory10: readonly string[];
+/** Tableau 10 default categorical palette. */
+export declare const schemeTableau10: readonly string[];
+/** ColorBrewer Set3 — 12 pastel categorical colors. */
+export declare const schemeSet3: readonly string[];
+export declare const interpolateBlues: (t: number) => string;
+export declare const interpolateReds: (t: number) => string;
+export declare const interpolateGreens: (t: number) => string;
+export declare const interpolateOranges: (t: number) => string;
+export declare const interpolatePurples: (t: number) => string;
+export declare const interpolateGreys: (t: number) => string;
+export declare const interpolateViridis: (t: number) => string;
+export declare const interpolatePlasma: (t: number) => string;
+export declare const interpolateInferno: (t: number) => string;
+export declare const interpolateMagma: (t: number) => string;
+export declare const interpolateCividis: (t: number) => string;
+export declare const interpolateTurbo: (t: number) => string;
+export declare const interpolateRdBu: (t: number) => string;
+export declare const interpolatePiYG: (t: number) => string;
+export declare const interpolatePRGn: (t: number) => string;
+export declare const interpolateBrBG: (t: number) => string;
+export declare const interpolateRdYlBu: (t: number) => string;
+export declare const interpolateRdYlGn: (t: number) => string;
+export declare const interpolateSpectral: (t: number) => string;

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

@@ -1,4 +1,3 @@
-import { interpolateBlues, interpolateReds, interpolateGreens, interpolateOranges, interpolatePurples, interpolateViridis, interpolatePlasma } from "d3-scale-chromatic";
 import type { Datum } from "./datumTypes";
 /**
  * Predefined color schemes
@@ -7,13 +6,13 @@ export declare const COLOR_SCHEMES: {
     category10: readonly string[];
     tableau10: readonly string[];
     set3: readonly string[];
-    blues: typeof interpolateBlues;
-    reds: typeof interpolateReds;
-    greens: typeof interpolateGreens;
-    oranges: typeof interpolateOranges;
-    purples: typeof interpolatePurples;
-    viridis: typeof interpolateViridis;
-    plasma: typeof interpolatePlasma;
+    blues: (t: number) => string;
+    reds: (t: number) => string;
+    greens: (t: number) => string;
+    oranges: (t: number) => string;
+    purples: (t: number) => string;
+    viridis: (t: number) => string;
+    plasma: (t: number) => string;
 };
 /**
  * Default colors for charts
@@ -46,7 +45,7 @@ export declare const DEPTH_PALETTE_COLORS: string[];
  * getColor({value: 10}, d => d.value > 5 ? 'red' : 'blue')
  * ```
  */
-export declare function getColor(dataPoint: any, colorBy: string | ((d: Datum) => string), colorScale?: (v: any) => string): string;
+export declare function getColor(dataPoint: Datum, colorBy: string | ((d: Datum) => string), colorScale?: (v: string) => string): string;
 /**
  * Creates a color scale function from data
  *
@@ -71,4 +70,4 @@ export declare function createColorScale(data: Array<Datum>, colorBy: string, sc
  * @param domain - Optional domain for scaling [minValue, maxValue]
  * @returns Size value
  */
-export declare function getSize(dataPoint: any, sizeBy: string | ((d: Datum) => number), sizeRange?: [number, number], domain?: [number, number]): number;
+export declare function getSize(dataPoint: Datum, sizeBy: string | ((d: Datum) => number), sizeRange?: [number, number], domain?: [number, number]): number;

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

@@ -0,0 +1,58 @@
+/**
+ * Inlined replacement for the subset of `d3-format` that semiotic and
+ * its consumers actually exercise.
+ *
+ * Why this module exists: `d3-format` ships ~42KB unpacked plus a
+ * full locale-data table we don't use. Internally semiotic only emits
+ * three format strings (`,.0f`, `,.${n}f`, `.${n}%`) but the public
+ * `xFormat` / `yFormat` / `valueFormat` props let consumers pass any
+ * d3-format spec, so the parser needs to cover the realistic chart
+ * subset, not just the strings semiotic emits itself.
+ *
+ * What's implemented (the chart-relevant subset):
+ *
+ *     [,][.precision][~][type]
+ *
+ *   - `,` — thousands grouping using a literal comma. Matches d3's
+ *     default-locale behavior (en-US); intentionally not locale-aware,
+ *     because chart axis labels need stable output across CI runners
+ *     and SSR snapshots — a runtime-locale separator would shift to
+ *     `1.234,56` under de-DE / fr-FR and break golden-file tests.
+ *   - `.N` — fractional precision (digits after the decimal for
+ *     `f`/`%`, significant digits for `s`/`r`/`g`/`e`)
+ *   - `~` — trim trailing zeros (matches d3's `~` modifier)
+ *   - type: `f` (fixed), `%` (percent ×100), `e` (exponential),
+ *     `d` (integer; precision ignored), `s` (SI prefix), `r` (rounded
+ *     to N significant digits), `g` (general — switches between fixed
+ *     and exponential), or omitted (treated as `g` with default
+ *     precision, matching d3).
+ *
+ * What's NOT implemented (rare in chart axis labels):
+ *
+ *   - `[fill][align]` (`0`, `<`, `>`, `^`, `=`) — padding/alignment
+ *   - `[sign]` (`+`, `-`, `(`, ` `) — sign behaviors
+ *   - `[symbol]` (`$`, `#`) — currency / radix prefix
+ *   - `[width]` — minimum field width
+ *   - `b`/`o`/`x`/`X`/`c`/`n`/`p` types — binary/octal/hex/code-point/
+ *     comma/percent-rounded
+ *
+ * If a consumer passes a spec with one of the un-implemented features
+ * the parser falls through to a best-effort `Intl.NumberFormat` call
+ * so we don't crash; if the input isn't even a recognized spec, the
+ * caller's existing `try/catch` falls back to `String(value)`.
+ */
+/**
+ * Build a number formatter from a d3-format-style spec string.
+ * Mirrors `d3.format(spec)`: returns `(value: number) => string`.
+ *
+ * **Throws on unparseable specs and unimplemented types.** This
+ * matches d3's contract — the existing `try/catch` in
+ * `formatUtils.formatNumber` (and any consumer code that wraps a
+ * `format(spec)` call) catches the throw and falls back to
+ * `String(value)`. Earlier shim revisions silently fell back to
+ * `Intl.NumberFormat`, which (a) suppressed bad-input errors that
+ * the outer fallback was designed to handle, and (b) reintroduced a
+ * runtime-locale dependency that would shift output across CI runners
+ * and SSR snapshot baselines.
+ */
+export declare function format(spec: string): (value: number) => string;

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

@@ -0,0 +1,27 @@
+/**
+ * Identity-preserving filter for sparse arrays of objects.
+ *
+ * Public chart props (`data`, `points`, `nodes`, `edges`, `flows`,
+ * `series`, `areas`) get fed to ingestion, color extraction, scene
+ * builders, and accessor lookups that read `d[field]` without
+ * null-checking individual entries. CSV-parsed and lookup-failed
+ * pipelines commonly emit `null` / `undefined` interlopers; without
+ * upfront filtering, the HOC crashes the moment a hook iterates the
+ * array.
+ *
+ * Returns the original array reference when nothing needs to be
+ * dropped. Consumers doing identity checks against the input prop —
+ * notably the cache keys inside `PipelineStore` and the `useMemo`
+ * deps inside `useChartSetup` / `useColorScale` — keep their fast
+ * paths in the common case where the input is already clean.
+ */
+/**
+ * Singleton empty array. Use as a stable default when a caller needs
+ * to satisfy a non-optional `T[]` parameter without allocating a fresh
+ * `[]` on every render — which would invalidate any downstream
+ * `useMemo` keyed on the array reference (e.g. `useChartSetup`'s
+ * sparse-array filter, color-scale memos). Frozen so accidental
+ * mutation throws in strict mode rather than corrupting later reads.
+ */
+export declare const EMPTY_ARRAY: readonly unknown[];
+export declare function filterSparseArray<T>(input: readonly T[] | undefined | null): T[];

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

@@ -0,0 +1,113 @@
+import type { ReactNode } from "react";
+import type { Datum } from "./datumTypes";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { HoverData } from "../../realtime/types";
+import type { LinkedHoverProp, SelectionConfig } from "./types";
+import type { OnObservationCallback } from "../../store/ObservationStore";
+import type { AnimateProp } from "../../stream/pipelineTransitionUtils";
+/**
+ * The frames accept `tooltipContent: (d: HoverData) => ReactNode`,
+ * which is a slightly wider parameter than the `TooltipContentFn`
+ * (`(d: Datum) => ReactNode`) the `Tooltip` module exports. The HOC
+ * default tooltip generated by `buildDefaultTooltip` matches the
+ * wider shape; user-provided tooltip functions (via `normalizeTooltip`)
+ * conform to the narrower `Datum` shape. At runtime both work because
+ * `HoverData` carries the original `Datum` plus interaction metadata,
+ * and the user's tooltip body reads only fields it knows about.
+ *
+ * Typing the helper's return at the wider `HoverData` shape lets either
+ * source flow through without a cast at the call site, matching the
+ * inline form HOCs used before this refactor.
+ */
+type FrameTooltipContent = (d: HoverData) => ReactNode;
+/**
+ * Returns the spreadable subset of base metadata props for the frame.
+ *
+ *   - Truthy gate for `title` / `description` / `summary` / `className`:
+ *     empty strings should NOT shadow the frame's own defaults.
+ *   - Defined gate for `accessibleTable`: an explicit `false` is a real
+ *     consumer choice (suppresses the sr-only data table) and must
+ *     reach the frame.
+ *   - Defined-and-non-null gate for `animate`: matches `props.animate
+ *     != null`. Lets `false` through (disables animation explicitly)
+ *     while filtering `undefined` so the frame's intro-on-default
+ *     stays in effect.
+ *
+ * The returned object is suitable for `...spread` into a frame-props
+ * object literal.
+ */
+export interface BaseMetadataProps {
+    title?: string | ReactNode;
+    description?: string;
+    summary?: string;
+    accessibleTable?: boolean;
+    className?: string;
+    animate?: AnimateProp;
+}
+export declare function buildBaseMetadataProps(input: BaseMetadataProps): BaseMetadataProps;
+/**
+ * Returns the spreadable hover/click behavior props for the frame.
+ *
+ * The predicates encode the same logic the HOCs already used inline:
+ *
+ *   - `customHoverBehavior` is forwarded only when at least one
+ *     consumer-side hover-driving prop is set (`linkedHover` for
+ *     cross-chart highlight, `onObservation` for AI observation
+ *     emission, `onClick` for click resolution that needs hover-driven
+ *     hit testing, `hoverHighlight` for the dim-non-hovered effect).
+ *   - `customClickBehavior` mirrors the click-driving subset
+ *     (`onObservation`, `onClick`, `linkedHover` for cross-chart
+ *     selection lock).
+ *
+ * Returning the props as a spreadable object means HOCs that don't
+ * need either get an empty merge that adds nothing.
+ */
+export declare function buildCustomBehaviorProps(input: {
+    linkedHover?: LinkedHoverProp;
+    onObservation?: OnObservationCallback;
+    onClick?: ((datum: Datum, position: {
+        x: number;
+        y: number;
+    }) => void) | undefined;
+    hoverHighlight?: boolean;
+    customHoverBehavior: (d: Datum | null) => void;
+    customClickBehavior: (d: Datum | null) => void;
+    /**
+     * Whether `linkedHover` participates in the click predicate. Most
+     * XY / ordinal HOCs say yes — `linkedHover` cross-chart selection
+     * fires on click-to-lock as well as hover. Geo HOCs and
+     * `CandlestickChart` say no — their click resolution only needs
+     * direct consumer-side handlers (`onObservation` / `onClick`).
+     * Default is `true` to match the more common case.
+     */
+    linkedHoverInClickPredicate?: boolean;
+}): {
+    customHoverBehavior?: (d: Datum | null) => void;
+    customClickBehavior?: (d: Datum | null) => void;
+};
+/**
+ * Resolve the `tooltipContent` prop for the frame.
+ *
+ *   - `tooltip === false` → noop function (suppresses the frame's
+ *     default tooltip rendering entirely).
+ *   - Otherwise → `normalizeTooltip(tooltip)` (a function, possibly
+ *     returned by `Tooltip({ ... })` / `MultiLineTooltip({ ... })`),
+ *     falling back to the chart's own `defaultTooltipContent` if
+ *     `tooltip` is undefined or an unrecognized form.
+ *
+ * Returning `tooltipContent` as an object means HOCs spread it like
+ * the other helpers and don't have to remember the noop-vs-default
+ * branch in line.
+ */
+export declare function buildTooltipProps(input: {
+    tooltip: TooltipProp | undefined;
+    defaultTooltipContent: FrameTooltipContent;
+}): {
+    tooltipContent: FrameTooltipContent;
+};
+/**
+ * Selection-config alias. Re-exported so HOCs that use these helpers
+ * don't need a parallel import path for the type that flows through
+ * `buildCustomBehaviorProps`.
+ */
+export type { SelectionConfig };