semiotic 3.5.1 → 3.5.3

package/dist/components/stream/types.d.ts

@@ -4,6 +4,7 @@ import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { LegendGroup, GradientLegendConfig } from "../types/legendTypes";
 import type { ArrowOfTime, WindowMode, LineStyle, BarStyle, WaterfallStyle, SwarmStyle, HoverAnnotationConfig, HoverData, AnnotationContext, AnnotationAnchorMode } from "../realtime/types";
 import type { Datum } from "../charts/shared/datumTypes";
+import type { CoercibleNumber } from "./accessorUtils";
 export type SceneDatum = Datum | null;
 export type SeriesDatum = Datum[] | null;
 export type AxisTickFormat = ((d: number, index?: number, allTicks?: number[]) => string) | ((d: string, index?: number, allTicks?: number[]) => string) | ((d: Date, index?: number, allTicks?: number[]) => string);
@@ -89,6 +90,10 @@ export interface Style {
     icon?: HTMLImageElement | HTMLCanvasElement;
     /** Padding between stamped icons */
     iconPadding?: number;
+    /** Optional radius when style callbacks drive point size directly. */
+    r?: number;
+    /** Internal geo line flag: fade line ends at projection clipping edges. */
+    _edgeFade?: boolean;
 }
 export type SceneNode = LineSceneNode | AreaSceneNode | PointSceneNode | RectSceneNode | HeatcellSceneNode | CandlestickSceneNode;
 export interface LineColorThreshold {
@@ -227,6 +232,19 @@ export interface RectSceneNode {
      *  bar scene builders unconditionally so gradients resolve without
      *  requiring roundedTop. */
     roundedEdge?: "top" | "bottom" | "right" | "left";
+    /** Explicit per-corner radii. Overrides the `roundedTop` + `roundedEdge`
+     *  shortcut when present. Used by swimlanes (and any future chart that
+     *  needs to round arbitrary subsets of a rect's four corners) — the
+     *  outermost pieces of a lane round their leading/trailing corners and
+     *  middle pieces stay square. Keys map to physical corners: `tl`
+     *  top-left, `tr` top-right, `br` bottom-right, `bl` bottom-left.
+     *  Missing keys are treated as 0 (square). */
+    cornerRadii?: {
+        tl?: number;
+        tr?: number;
+        br?: number;
+        bl?: number;
+    };
     /** Gradient fill — same shape as the area-scene version. Runs tip → base
      *  along the bar axis (inferred from `roundedEdge`). */
     fillGradient?: {
@@ -356,6 +374,86 @@ export interface StreamLayout {
     height: number;
 }
 export type CurveType = "linear" | "monotoneX" | "monotoneY" | "step" | "stepAfter" | "stepBefore" | "basis" | "cardinal" | "catmullRom" | "natural";
+/**
+ * Asymmetric min/max envelope drawn under lines/areas. Data-driven cousin
+ * of `boundsAccessor` (which takes a single symmetric ±offset). Use for
+ * throughput min/max ribbons, percentile bands (p5–p95), SLO ranges, and
+ * fan charts (pass an array of bands).
+ *
+ * Painted with the parent series color at 0.2 fillOpacity by default.
+ * Override with `style`. Non-interactive by default; participates in
+ * y-extent auto-derivation so it can't clip.
+ */
+export interface BandConfig<T = Datum> {
+    /** Bottom of the band — field name or accessor function. */
+    y0Accessor: string | ((d: T) => number);
+    /** Top of the band — field name or accessor function. */
+    y1Accessor: string | ((d: T) => number);
+    /**
+     * Style override. Defaults to the parent line/area color at 0.2
+     * fillOpacity, matching the `boundsStyle` cascade.
+     */
+    style?: Style | ((d: T, group?: string) => Style);
+    /**
+     * When the parent chart groups by `lineBy` / `colorBy`:
+     * - `true` (default): one band per group, colored to match the line
+     * - `false`: a single band drawn across the whole dataset (e.g. an
+     *   aggregate min/max across all series)
+     */
+    perSeries?: boolean;
+    /**
+     * Whether the band area participates in hit testing. Defaults to
+     * `false` — the band is decorative; hover/click pass through to the
+     * line on top. Independent of the `datum.band` enrichment, which
+     * happens whenever a band is configured.
+     */
+    interactive?: boolean;
+}
+/**
+ * Per-axis configuration object for an XY frame's `axes: []` array.
+ * Distinct from `AxisConfig` exported from the HOC layer (which is the
+ * chart-level `xLabel` / `yLabel` / `xFormat` / `yFormat` bundle) —
+ * this type describes one axis at a time and is what
+ * `frameProps.axes[i]` consumes.
+ *
+ * Re-exported under the legacy name `AxisConfig` from `SVGOverlay.tsx`
+ * for backwards-compatibility with internal callers; new code should
+ * import this name directly.
+ */
+export interface XYFrameAxisConfig {
+    orient: "left" | "right" | "top" | "bottom";
+    label?: string;
+    ticks?: number;
+    /** Per-axis tick label formatter. ReactNode return is supported and
+     *  renders inside a `<foreignObject>`. */
+    tickFormat?: (d: any, index?: number, allTicks?: number[]) => string | ReactNode;
+    baseline?: boolean | "under";
+    jaggedBase?: boolean;
+    /** Explicit tick values. When provided, bypasses both d3's "nice"
+     *  generator and `axisExtent: "exact"` — the caller has hand-picked
+     *  the positions. Pixel-distance filtering downstream still drops
+     *  overlapping labels. Mirrors the ordinal frame's `rTickValues`. */
+    tickValues?: Array<number | Date>;
+    /** Grid line stroke style: `"dashed"` (6,4), `"dotted"` (2,4), or a
+     *  custom strokeDasharray string. Applied to grid lines extending
+     *  from ticks across the chart area. */
+    gridStyle?: "dashed" | "dotted" | string;
+    /** Always include the domain max as a tick, even if d3 omits it. */
+    includeMax?: boolean;
+    /** Auto-rotate labels 45° when horizontal spacing is too tight. */
+    autoRotate?: boolean;
+    /** Highlight ticks at time boundaries (new month, year, etc.) with
+     *  semibold text. `true` auto-detects Date boundaries. A function
+     *  receives (value, index) and returns true for landmark ticks. */
+    landmarkTicks?: boolean | ((value: any, index: number) => boolean);
+    /** Tick label anchoring strategy:
+     *  - `"middle"` (default): all tick labels centered on the tick mark
+     *  - `"edges"`: first tick label anchors to start, last to end,
+     *    middles stay centered. Pairs naturally with `axisExtent: "exact"`
+     *    — pins the domain to the data min/max AND keeps the extreme
+     *    labels from overflowing the plot. */
+    tickAnchor?: "middle" | "edges";
+}
 export interface StreamXYFrameProps<T = Datum> {
     chartType: StreamChartType;
     runtimeMode?: RuntimeMode;
@@ -364,10 +462,10 @@ export interface StreamXYFrameProps<T = Datum> {
     chunkThreshold?: number;
     /** Number of items per progressive chunk (default 5000) */
     chunkSize?: number;
-    xAccessor?: string | ((d: T) => number);
-    yAccessor?: string | ((d: T) => number);
+    xAccessor?: string | ((d: T) => CoercibleNumber);
+    yAccessor?: string | ((d: T) => CoercibleNumber);
     colorAccessor?: string | ((d: T) => string);
-    sizeAccessor?: string | ((d: T) => number);
+    sizeAccessor?: string | ((d: T) => CoercibleNumber);
     groupAccessor?: string | ((d: T) => string);
     lineDataAccessor?: string;
     curve?: CurveType;
@@ -432,6 +530,19 @@ export interface StreamXYFrameProps<T = Datum> {
      * If omitted, defaults to the line color at 0.2 opacity.
      */
     boundsStyle?: Style | ((d: T, group?: string) => Style);
+    /**
+     * Asymmetric min/max band(s) drawn under the line/area. Differs from
+     * `boundsAccessor` (which is a symmetric ±offset) and from `y0Accessor`
+     * (which replaces the area baseline). A band is a decorative envelope
+     * — painted under the lines, above the grid, non-interactive by default
+     * — driven by per-point `y0`/`y1` accessors.
+     *
+     * Pass an array for multi-band fan charts (e.g. p25/p75 inside p10/p90).
+     * Outer bands first; inner bands stack on top.
+     *
+     * Participates in y-extent auto-derivation when `yExtent` is not pinned.
+     */
+    band?: BandConfig<T> | Array<BandConfig<T>>;
     openAccessor?: string | ((d: T) => number);
     highAccessor?: string | ((d: T) => number);
     lowAccessor?: string | ((d: T) => number);
@@ -475,20 +586,25 @@ export interface StreamXYFrameProps<T = Datum> {
     barColors?: Record<string, string>;
     colorScheme?: string | string[];
     showAxes?: boolean;
-    axes?: Array<{
-        orient: "left" | "right" | "top" | "bottom";
-        label?: string;
-        ticks?: number;
-        tickFormat?: AxisTickFormat;
-        baseline?: boolean | "under";
-        jaggedBase?: boolean;
-    }>;
+    /**
+     * Per-axis config array. See `XYFrameAxisConfig` for the full set of
+     * fields — covers `tickValues`, `tickFormat`, `tickAnchor`,
+     * `landmarkTicks`, `autoRotate`, `gridStyle`, `includeMax`,
+     * `baseline`, `jaggedBase`, `label`, and `ticks`.
+     */
+    axes?: XYFrameAxisConfig[];
     xLabel?: string;
     yLabel?: string;
     /** Label for the right Y axis (dual-axis charts) */
     yLabelRight?: string;
     xFormat?: (d: number | Date | string, index?: number, allTicks?: number[]) => string | ReactNode;
     yFormat?: (d: number | Date | string) => string | ReactNode;
+    /** Axis extent mode. `"nice"` (default) uses d3-scale's rounded
+     *  tick generator — round tick labels at the cost of ticks not
+     *  reaching the exact data min/max. `"exact"` pins the first
+     *  and last tick to the data domain and spaces intermediate
+     *  ticks equidistantly. Applies to both x and y axes. */
+    axisExtent?: import("../charts/shared/axisExtent").AxisExtentMode;
     tickFormatTime?: (value: number) => string;
     tickFormatValue?: (value: number) => string;
     hoverAnnotation?: boolean | HoverAnnotationConfig;

package/dist/components/stream/xySceneBuilders/areaGradient.d.ts

@@ -0,0 +1,20 @@
+import type { AreaSceneNode } from "../types";
+type ResolvedAreaGradient = NonNullable<AreaSceneNode["fillGradient"]>;
+type OpacityGradient = {
+    topOpacity: number;
+    bottomOpacity: number;
+};
+type ColorStopGradient = {
+    colorStops: Array<{
+        offset: number;
+        color: string;
+    }>;
+};
+type OpacityGradientConfig = {
+    topOpacity?: number;
+    bottomOpacity?: number;
+};
+export type AreaGradientConfig = boolean | OpacityGradientConfig | ColorStopGradient;
+export declare const DEFAULT_AREA_GRADIENT: OpacityGradient;
+export declare function resolveAreaGradient(gradient: AreaGradientConfig | undefined): ResolvedAreaGradient | undefined;
+export {};

package/dist/components/stream/xySceneBuilders/barScene.d.ts

@@ -9,10 +9,10 @@ import type { Datum } from "../../charts/shared/datumTypes";
  * Dependencies: BinAccumulator (computeBins), SceneGraph (buildRectNode)
  * Consumed by: PipelineStore.buildSceneNodes (chartType "bar")
  */
-import type { SceneNode } from "../types";
+import type { RectSceneNode } from "../types";
 import type { XYSceneContext } from "./types";
 export interface BarSceneResult {
-    nodes: SceneNode[];
+    nodes: RectSceneNode[];
     /** Sorted bin boundary values (edges of all bins) for data-driven brush snapping */
     binBoundaries: number[];
 }

package/dist/components/stream/xySceneBuilders/candlestickScene.d.ts

@@ -6,6 +6,6 @@ import type { Datum } from "../../charts/shared/datumTypes";
  *
  * Consumed by: PipelineStore.buildSceneNodes (chartType "candlestick")
  */
-import type { SceneNode, StreamLayout } from "../types";
+import type { CandlestickSceneNode, StreamLayout } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildCandlestickScene(ctx: XYSceneContext, data: Datum[], _layout: StreamLayout): SceneNode[];
+export declare function buildCandlestickScene(ctx: XYSceneContext, data: Datum[], _layout: StreamLayout): CandlestickSceneNode[];

package/dist/components/stream/xySceneBuilders/heatmapScene.d.ts

@@ -1,4 +1,4 @@
 import type { Datum } from "../../charts/shared/datumTypes";
-import type { SceneNode, StreamLayout } from "../types";
+import type { HeatcellSceneNode, StreamLayout } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildHeatmapScene(ctx: XYSceneContext, data: Datum[], layout: StreamLayout): SceneNode[];
+export declare function buildHeatmapScene(ctx: XYSceneContext, data: Datum[], layout: StreamLayout): HeatcellSceneNode[];

package/dist/components/stream/xySceneBuilders/lineScene.d.ts

@@ -2,10 +2,11 @@ import type { Datum } from "../../charts/shared/datumTypes";
 /**
  * Line scene builder — produces LineSceneNode[] from grouped data.
  *
- * Handles: color thresholds from annotations, bounds/envelope areas,
- * and curve type attachment for canvas interpolation.
+ * Handles: color thresholds from annotations, ribbon envelopes
+ * (boundsAccessor + band), and curve type attachment for canvas
+ * interpolation.
  *
- * Dependencies: SceneGraph (buildLineNode), boundsScene (buildBoundsForGroup)
+ * Dependencies: SceneGraph (buildLineNode), ribbonScene (buildRibbon*)
  * Consumed by: PipelineStore.buildSceneNodes (chartType "line")
  */
 import type { SceneNode } from "../types";

package/dist/components/stream/xySceneBuilders/pointScene.d.ts

@@ -8,6 +8,6 @@ import type { Datum } from "../../charts/shared/datumTypes";
  * Dependencies: SceneGraph (buildPointNode)
  * Consumed by: PipelineStore.buildSceneNodes (chartTypes "scatter", "bubble")
  */
-import type { SceneNode } from "../types";
+import type { PointSceneNode } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildPointScene(ctx: XYSceneContext, data: Datum[]): SceneNode[];
+export declare function buildPointScene(ctx: XYSceneContext, data: Datum[]): PointSceneNode[];

package/dist/components/stream/xySceneBuilders/ribbonScene.d.ts

@@ -0,0 +1,107 @@
+import type { Datum } from "../../charts/shared/datumTypes";
+/**
+ * Ribbon scene builder — the unified primitive for painting a closed
+ * top/bottom envelope underneath a line/area, used by:
+ *
+ * - `boundsAccessor` (symmetric ±offset around `yAccessor`)
+ * - `band` (asymmetric `y0Accessor` / `y1Accessor` per BandConfig, with
+ *   multi-band fan support)
+ *
+ * Both public APIs normalize to `ResolvedRibbon[]` at the PipelineStore
+ * layer; the scene builders, y-extent expansion, and tooltip enrichment
+ * all read that single array.
+ *
+ * Consumed by: lineScene, areaScene, mixedScene (each renders ribbons
+ * before lines/areas so they sit underneath in z-order).
+ */
+import type { AreaSceneNode, Style } from "../types";
+import type { XYSceneContext } from "./types";
+/**
+ * One ribbon worth of geometry + style. The PipelineStore owns the
+ * normalization from `boundsAccessor` and `band` public props into this
+ * single internal shape.
+ */
+export interface ResolvedRibbon {
+    /**
+     * Origin of this ribbon:
+     * - `"bounds"`: produced by `boundsAccessor` (decorative-only)
+     * - `"band"`: produced by `band` (eligible for `datum.band` tooltip
+     *   enrichment in the hover handler)
+     */
+    kind: "bounds" | "band";
+    /**
+     * Top y-value for each datum. Return `NaN` to skip a datum entirely
+     * (gap behavior). Bounds resolves this from `y + offset` (collapsing
+     * to `y` when offset is non-finite, matching legacy behavior); band
+     * resolves it from `y1Accessor`.
+     */
+    getTop: (d: Datum) => number;
+    /**
+     * Bottom y-value for each datum. Same gap semantics as `getTop`.
+     */
+    getBottom: (d: Datum) => number;
+    /**
+     * Style override. When omitted, the scene builder falls back to
+     * `ctx.resolveBoundsStyle(group, sampleDatum)` — line color at 0.2
+     * fillOpacity. Functions get the first datum and group key.
+     */
+    style?: Style | ((d: Datum, group?: string) => Style);
+    /**
+     * `true` → one ribbon per group, colored to match each line.
+     * `false` → a single aggregate ribbon across the whole dataset.
+     * Bounds is always `true`. Band defaults to `true`; the public
+     * `BandConfig.perSeries: false` opt-out flips this.
+     */
+    perSeries: boolean;
+    /**
+     * Whether the ribbon area participates in hit testing. Bounds is
+     * always `false`. Band defaults to `false` but supports `interactive: true`.
+     */
+    interactive: boolean;
+}
+/**
+ * Build a single ribbon scene node for one slice of data.
+ *
+ * Iterates the data once, evaluates `getTop`/`getBottom` per datum, and
+ * collects coordinate pairs. Any datum with non-finite x, top, or bottom
+ * is skipped (gap semantics — equivalent to `gapStrategy: "break"`).
+ * Returns `null` when fewer than two valid points remain (a single
+ * point can't form a visible ribbon).
+ */
+export declare function buildRibbonForGroup(ctx: XYSceneContext, data: Datum[], group: string, ribbon: ResolvedRibbon): AreaSceneNode | null;
+/**
+ * Split ribbons by `perSeries` so the caller can dispatch correctly:
+ * per-series ribbons render once per group; aggregate ribbons render
+ * once across the full dataset.
+ */
+export declare function partitionRibbons(ribbons: ResolvedRibbon[] | undefined): {
+    perSeries: ResolvedRibbon[];
+    aggregate: ResolvedRibbon[];
+};
+/**
+ * Build all aggregate ribbons (perSeries=false) for the whole dataset.
+ * Each ribbon emits at most one AreaSceneNode under the synthetic
+ * group key `__ribbon_aggregate`.
+ */
+export declare function buildAggregateRibbons(ctx: XYSceneContext, data: Datum[], ribbons: ResolvedRibbon[]): AreaSceneNode[];
+/**
+ * Build all per-series ribbons for one grouped data slice. Each ribbon
+ * in the list emits at most one AreaSceneNode for the given group.
+ */
+export declare function buildPerSeriesRibbons(ctx: XYSceneContext, data: Datum[], group: string, ribbons: ResolvedRibbon[]): AreaSceneNode[];
+/**
+ * Enrich a hovered datum with band values so user tooltips can read
+ * `datum.band = { y0, y1 }` (first band) and `datum.bands = [...]`
+ * (all bands). Returns a shallow copy so the original data row is
+ * never mutated.
+ *
+ * Bounds-sourced ribbons (`kind: "bounds"`) are intentionally excluded
+ * — they're decorative, and the tooltip enrichment contract is
+ * band-only. Returns the input datum unchanged when no band-kind
+ * ribbons are configured or none produce finite values at this datum.
+ *
+ * Consumed by every code path that produces a `HoverData` in
+ * StreamXYFrame: pointer hover, multi-mode per-series datum, and
+ * keyboard navigation.
+ */
+export declare function enrichDatumWithBand(datum: Datum | null | undefined, ribbons: ResolvedRibbon[] | undefined): Datum;

package/dist/components/stream/xySceneBuilders/swarmScene.d.ts

@@ -6,6 +6,6 @@ import type { Datum } from "../../charts/shared/datumTypes";
  *
  * Consumed by: PipelineStore.buildSceneNodes (chartType "swarm")
  */
-import type { SceneNode } from "../types";
+import type { PointSceneNode } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildSwarmScene(ctx: XYSceneContext, data: Datum[]): SceneNode[];
+export declare function buildSwarmScene(ctx: XYSceneContext, data: Datum[]): PointSceneNode[];

package/dist/components/stream/xySceneBuilders/types.d.ts

@@ -1,4 +1,5 @@
 import type { Datum } from "../../charts/shared/datumTypes";
+import type { AreaGradientConfig } from "./areaGradient";
 /**
  * XYSceneContext — shared context passed to all XY scene builder functions.
  *
@@ -7,6 +8,7 @@ import type { Datum } from "../../charts/shared/datumTypes";
  * accessing PipelineStore instance fields directly.
  */
 import type { StreamScales, Style, CurveType, BarStyle, ThemeSemanticColors } from "../types";
+import type { ResolvedRibbon } from "./ribbonScene";
 export interface XYSceneContext {
     scales: StreamScales;
     config: XYSceneConfig;
@@ -18,7 +20,10 @@ export interface XYSceneContext {
     getGroup?: (d: Datum) => string;
     getCategory?: (d: Datum) => string;
     getPointId?: (d: Datum) => string;
-    getBounds?: (d: Datum) => number | null;
+    /** Resolved ribbons — unified list from `boundsAccessor` + `band`. The
+     *  scene builders iterate this once instead of carrying two parallel
+     *  code paths. Empty when neither prop is set. */
+    ribbons?: ResolvedRibbon[];
     getOpen?: (d: Datum) => number;
     getHigh?: (d: Datum) => number;
     getLow?: (d: Datum) => number;
@@ -42,7 +47,7 @@ export interface XYSceneContext {
 }
 /** Subset of PipelineConfig fields that scene builders need */
 export interface XYSceneConfig {
-    chartType: string;
+    chartType?: string;
     curve?: CurveType;
     colorScheme?: string | string[];
     normalize?: boolean;
@@ -50,15 +55,7 @@ export interface XYSceneConfig {
     baseline?: "zero" | "wiggle" | "silhouette";
     /** Stack order — see PipelineConfig.stackOrder. */
     stackOrder?: "key" | "insideOut" | "asc" | "desc";
-    gradientFill?: boolean | {
-        topOpacity?: number;
-        bottomOpacity?: number;
-    } | {
-        colorStops: Array<{
-            offset: number;
-            color: string;
-        }>;
-    };
+    gradientFill?: AreaGradientConfig;
     areaGroups?: Set<string>;
     lineGradient?: {
         colorStops: Array<{
@@ -83,7 +80,7 @@ export interface XYSceneConfig {
     barColors?: Record<string, string>;
     /** Bar fill/stroke/strokeWidth/gap. Threaded through from RealtimeHistogram. */
     barStyle?: BarStyle;
-    themeSemantic?: ThemeSemanticColors;
+    themeSemantic?: Partial<ThemeSemanticColors>;
     /** Theme sequential scheme name — fallback when colorScheme is not set (heatmap). */
     themeSequential?: string;
     /** Theme diverging scheme name — fallback when colorScheme is not set. */

package/dist/components/stream/xySceneBuilders/waterfallScene.d.ts

@@ -8,6 +8,6 @@
  * Consumed by: PipelineStore.buildSceneNodes (chartType "waterfall")
  */
 import type { Datum } from "../../charts/shared/datumTypes";
-import type { SceneNode, StreamLayout } from "../types";
+import type { RectSceneNode, StreamLayout } from "../types";
 import type { XYSceneContext } from "./types";
-export declare function buildWaterfallScene(ctx: XYSceneContext, data: Datum[], layout: StreamLayout): SceneNode[];
+export declare function buildWaterfallScene(ctx: XYSceneContext, data: Datum[], layout: StreamLayout): RectSceneNode[];

package/dist/components/types/legendTypes.d.ts

@@ -41,7 +41,7 @@ export interface LegendProps {
     highlightedCategory?: string | null;
     /** Legend interaction mode — used to set aria-multiselectable on the listbox */
     legendInteraction?: string;
-    title?: string;
+    title?: string | boolean;
     width?: number;
     height?: number;
     orientation?: string;