semiotic 3.5.2 → 3.5.4

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

@@ -1,11 +1,18 @@
 import type { Datum } from "../shared/datumTypes";
 import * as React from "react";
-import type { StreamXYFrameProps } from "../../stream/types";
+import type { StreamXYFrameProps, BandConfig } from "../../stream/types";
 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";
+export interface SemanticGradientStop {
+    /** Percent from baseline to line/top. 0 = baseline, 100 = line/top. */
+    at: number;
+    color: string;
+    /** Optional opacity applied to this stop. */
+    opacity?: number;
+}
 /**
  * AreaChart component props
  */
@@ -23,7 +30,7 @@ export interface AreaChartProps<TDatum extends Datum = Datum> extends BaseChartP
      * Field name or function to access x values
      * @default "x"
      */
-    xAccessor?: ChartAccessor<TDatum, number>;
+    xAccessor?: ChartAccessor<TDatum, number | Date | string>;
     /**
      * Field name or function to access y values
      * @default "y"
@@ -90,6 +97,14 @@ export interface AreaChartProps<TDatum extends Datum = Datum> extends BaseChartP
             color: string;
         }>;
     };
+    /**
+     * Semantic area gradient stops expressed in user-facing percentages:
+     * `at: 0` is the baseline and `at: 100` is the line/top of the area.
+     * This is converted to `gradientFill.colorStops`, whose raw offsets use
+     * the renderer coordinate convention (`0` = top, `1` = baseline).
+     * When set, this takes precedence over `gradientFill`.
+     */
+    semanticGradient?: SemanticGradientStop[];
     /**
      * Area opacity (flat fill, ignored when gradientFill is set)
      * @default 0.7
@@ -183,6 +198,16 @@ export interface AreaChartProps<TDatum extends Datum = Datum> extends BaseChartP
      * ```
      */
     anomaly?: AnomalyConfig;
+    /**
+     * Asymmetric min/max band(s) drawn under the area fill. Distinct from
+     * `y0Accessor` (which replaces the area's baseline) — `band` is a
+     * decorative envelope painted beneath the area, driven by independent
+     * `y0Accessor` / `y1Accessor` per band. Pass an array for fan charts.
+     *
+     * The hovered datum gets `band: { y0, y1 }` and `bands: [...]` for
+     * tooltip access. See the LineChart docs for full ergonomics.
+     */
+    band?: BandConfig<TDatum> | Array<BandConfig<TDatum>>;
     /**
      * 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

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

@@ -1,6 +1,6 @@
 import type { Datum } from "../shared/datumTypes";
 import * as React from "react";
-import type { StreamXYFrameProps } from "../../stream/types";
+import type { StreamXYFrameProps, BandConfig } from "../../stream/types";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
@@ -29,7 +29,7 @@ export interface LineChartProps<TDatum extends Datum = Datum> extends BaseChartP
      * Field name or function to access x values
      * @default "x"
      */
-    xAccessor?: ChartAccessor<TDatum, number>;
+    xAccessor?: ChartAccessor<TDatum, number | Date | string>;
     /**
      * Field name or function to access y values
      * @default "y"
@@ -181,6 +181,30 @@ export interface LineChartProps<TDatum extends Datum = Datum> extends BaseChartP
      * envelope around the extrapolated forecast region.
      */
     forecast?: ForecastConfig;
+    /**
+     * Asymmetric min/max band(s) drawn under the line. Differs from
+     * `forecast`/`anomaly` (computed envelopes around a series) by being
+     * pure data passthrough — provide `y0Accessor` / `y1Accessor` and the
+     * band is drawn between them at each x.
+     *
+     * Pass an array for percentile fans (e.g. p25/p75 on top of p10/p90).
+     * Each band participates in y-extent auto-derivation, so a tall band
+     * can never get clipped. The hovered datum is enriched with
+     * `band: { y0, y1 }` (first band) and `bands: [...]` (all bands) so
+     * tooltip functions can read the envelope without re-running the
+     * accessors.
+     *
+     * @example
+     * ```tsx
+     * <LineChart
+     *   data={[{ time, average, min, max }, ...]}
+     *   xAccessor="time"
+     *   yAccessor="average"
+     *   band={{ y0Accessor: "min", y1Accessor: "max" }}
+     * />
+     * ```
+     */
+    band?: BandConfig<TDatum> | Array<BandConfig<TDatum>>;
     /**
      * Fixed x domain `[min, max]`. Either bound may be `undefined` to leave
      * that side data-derived.

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

@@ -14,9 +14,13 @@ export interface ScatterplotProps<TDatum extends Datum = Datum> extends BaseChar
     /** Array of data points. Each point should have x and y properties. */
     data?: TDatum[];
     /** Field name or function to access x values @default "x" */
-    xAccessor?: ChartAccessor<TDatum, number>;
+    xAccessor?: ChartAccessor<TDatum, number | Date | string>;
     /** Field name or function to access y values @default "y" */
     yAccessor?: ChartAccessor<TDatum, number>;
+    /** X scale type @default "linear" */
+    xScaleType?: "linear" | "log" | "time";
+    /** Y scale type @default "linear" */
+    yScaleType?: "linear" | "log";
     /** Field name or function to determine point color */
     colorBy?: ChartAccessor<TDatum, string>;
     /** Color scheme for categorical data or custom colors array @default "category10" */

package/dist/components/semiotic-ai.d.ts

@@ -37,7 +37,7 @@ export { Treemap } from "./charts/network/Treemap";
 export { CirclePack } from "./charts/network/CirclePack";
 export { OrbitDiagram } from "./charts/network/OrbitDiagram";
 export { RealtimeLineChart } from "./charts/realtime/RealtimeLineChart";
-export { RealtimeHistogram } from "./charts/realtime/RealtimeHistogram";
+export { RealtimeHistogram, TemporalHistogram } from "./charts/realtime/RealtimeHistogram";
 export { RealtimeSwarmChart } from "./charts/realtime/RealtimeSwarmChart";
 export { RealtimeWaterfallChart } from "./charts/realtime/RealtimeWaterfallChart";
 export { RealtimeHeatmap } from "./charts/realtime/RealtimeHeatmap";

package/dist/components/semiotic-realtime.d.ts

@@ -7,13 +7,13 @@ import StreamNetworkFrame from "./stream/StreamNetworkFrame";
 import { RingBuffer } from "./realtime/RingBuffer";
 import { IncrementalExtent } from "./realtime/IncrementalExtent";
 import { RealtimeLineChart } from "./charts/realtime/RealtimeLineChart";
-import { RealtimeHistogram } from "./charts/realtime/RealtimeHistogram";
+import { RealtimeHistogram, TemporalHistogram } from "./charts/realtime/RealtimeHistogram";
 import { RealtimeSwarmChart } from "./charts/realtime/RealtimeSwarmChart";
 import { RealtimeWaterfallChart } from "./charts/realtime/RealtimeWaterfallChart";
 import { RealtimeHeatmap } from "./charts/realtime/RealtimeHeatmap";
-export { StreamXYFrame, StreamNetworkFrame, RingBuffer, IncrementalExtent, RealtimeLineChart, RealtimeHistogram, RealtimeSwarmChart, RealtimeWaterfallChart, RealtimeHeatmap };
+export { StreamXYFrame, StreamNetworkFrame, RingBuffer, IncrementalExtent, RealtimeLineChart, RealtimeHistogram, TemporalHistogram, RealtimeSwarmChart, RealtimeWaterfallChart, RealtimeHeatmap };
 export type { RealtimeLineChartProps } from "./charts/realtime/RealtimeLineChart";
-export type { RealtimeHistogramProps } from "./charts/realtime/RealtimeHistogram";
+export type { RealtimeHistogramProps, TemporalHistogramProps } from "./charts/realtime/RealtimeHistogram";
 export type { RealtimeSwarmChartProps } from "./charts/realtime/RealtimeSwarmChart";
 export type { RealtimeWaterfallChartProps } from "./charts/realtime/RealtimeWaterfallChart";
 export type { RealtimeHeatmapProps } from "./charts/realtime/RealtimeHeatmap";

package/dist/components/semiotic-server.d.ts

@@ -1,5 +1,6 @@
 export { renderToStaticSVG, renderXYToStaticSVG, renderOrdinalToStaticSVG, renderNetworkToStaticSVG, renderGeoToStaticSVG, renderChart, renderToImage, renderDashboard, } from "./server/renderToStaticSVG";
 export type { RenderToImageOptions, DashboardChart, DashboardLayout, RenderDashboardOptions, } from "./server/renderToStaticSVG";
+export type { LegendLayout } from "./types/legendTypes";
 export { renderToAnimatedGif, generateFrameSVGs, generateFrameSequence } from "./server/animatedGif";
 export type { AnimatedGifOptions } from "./server/animatedGif";
 export { resolveTheme, themeStyles } from "./server/themeResolver";

package/dist/components/semiotic-xy.d.ts

@@ -21,7 +21,7 @@ export { XYCustomChart } from "./charts/custom/XYCustomChart";
 export type { StreamXYFrameProps, StreamXYFrameHandle } from "./stream/types";
 export type { CustomLayout, LayoutContext, LayoutResult } from "./stream/customLayout";
 export type { LineChartProps } from "./charts/xy/LineChart";
-export type { AreaChartProps } from "./charts/xy/AreaChart";
+export type { AreaChartProps, SemanticGradientStop } from "./charts/xy/AreaChart";
 export type { DifferenceChartProps } from "./charts/xy/DifferenceChart";
 export type { StackedAreaChartProps } from "./charts/xy/StackedAreaChart";
 export type { ScatterplotProps } from "./charts/xy/Scatterplot";

package/dist/components/semiotic.d.ts

@@ -19,13 +19,14 @@ import { Tooltip, MultiLineTooltip, normalizeTooltip } from "./Tooltip/Tooltip";
 import { RingBuffer } from "./realtime/RingBuffer";
 import { IncrementalExtent } from "./realtime/IncrementalExtent";
 import { RealtimeLineChart } from "./charts/realtime/RealtimeLineChart";
-import { RealtimeTemporalHistogram, RealtimeHistogram } from "./charts/realtime/RealtimeHistogram";
+import { RealtimeTemporalHistogram, RealtimeHistogram, TemporalHistogram } from "./charts/realtime/RealtimeHistogram";
 import { RealtimeSwarmChart } from "./charts/realtime/RealtimeSwarmChart";
 import { RealtimeWaterfallChart } from "./charts/realtime/RealtimeWaterfallChart";
 import { RealtimeHeatmap } from "./charts/realtime/RealtimeHeatmap";
-export { StreamXYFrame, StreamOrdinalFrame, StreamNetworkFrame, Scatterplot, ConnectedScatterplot, LineChart, AreaChart, DifferenceChart, StackedAreaChart, Heatmap, BubbleChart, BarChart, StackedBarChart, LikertChart, SwarmPlot, BoxPlot, Histogram, ViolinPlot, RidgelinePlot, DotPlot, ForceDirectedGraph, ChordDiagram, SankeyDiagram, ProcessSankey, TreeDiagram, PieChart, DonutChart, GaugeChart, FunnelChart, GroupedBarChart, SwimlaneChart, Treemap, CirclePack, OrbitDiagram, ScatterplotMatrix, MinimapChart, QuadrantChart, MultiAxisLineChart, CandlestickChart, XYCustomChart, NetworkCustomChart, OrdinalCustomChart, LinkedCharts, ThemeProvider, useTheme, exportChart, toConfig, fromConfig, toURL, fromURL, copyConfig, configToJSX, serializeSelections, deserializeSelections, fromVegaLite, ChartErrorBoundary, ChartContainer, ChartGrid, CategoryColorProvider, useCategoryColors, ContextLayout, DetailsPanel, Tooltip, MultiLineTooltip, normalizeTooltip, RingBuffer, IncrementalExtent, RealtimeLineChart, RealtimeTemporalHistogram, RealtimeHistogram, RealtimeSwarmChart, RealtimeWaterfallChart, RealtimeHeatmap, createHatchPattern };
-export { ScatterplotProps, ConnectedScatterplotProps, LineChartProps, AreaChartProps, DifferenceChartProps, StackedAreaChartProps, HeatmapProps, BubbleChartProps, BarChartProps, StackedBarChartProps, LikertChartProps, SwarmPlotProps, BoxPlotProps, HistogramProps, ViolinPlotProps, DotPlotProps, PieChartProps, DonutChartProps, GaugeChartProps, GaugeThreshold, FunnelChartProps, GroupedBarChartProps, SwimlaneChartProps, RidgelinePlotProps, OrbitDiagramProps, OrbitNode, ForceDirectedGraphProps, ChordDiagramProps, SankeyDiagramProps, ProcessSankeyProps, ProcessSankeyTick, TreeDiagramProps, TreemapProps, CirclePackProps, ScatterplotMatrixProps, MinimapChartProps, MinimapConfig, QuadrantChartProps, MultiAxisLineChartProps, MultiAxisSeriesConfig, CandlestickChartProps, QuadrantsConfig, QuadrantConfig, CenterlineStyle, BaseChartProps, AxisConfig, Accessor, ChartAccessor, ChartMode } from "./charts";
-export type { StreamXYFrameProps, StreamXYFrameHandle, StreamChartType, RuntimeMode, SceneNode, Changeset, StreamScales, StreamLayout, CurveType, CanvasRendererFn } from "./stream/types";
+export { StreamXYFrame, StreamOrdinalFrame, StreamNetworkFrame, Scatterplot, ConnectedScatterplot, LineChart, AreaChart, DifferenceChart, StackedAreaChart, Heatmap, BubbleChart, BarChart, StackedBarChart, LikertChart, SwarmPlot, BoxPlot, Histogram, ViolinPlot, RidgelinePlot, DotPlot, ForceDirectedGraph, ChordDiagram, SankeyDiagram, ProcessSankey, TreeDiagram, PieChart, DonutChart, GaugeChart, FunnelChart, GroupedBarChart, SwimlaneChart, Treemap, CirclePack, OrbitDiagram, ScatterplotMatrix, MinimapChart, QuadrantChart, MultiAxisLineChart, CandlestickChart, XYCustomChart, NetworkCustomChart, OrdinalCustomChart, LinkedCharts, ThemeProvider, useTheme, exportChart, toConfig, fromConfig, toURL, fromURL, copyConfig, configToJSX, serializeSelections, deserializeSelections, fromVegaLite, ChartErrorBoundary, ChartContainer, ChartGrid, CategoryColorProvider, useCategoryColors, ContextLayout, DetailsPanel, Tooltip, MultiLineTooltip, normalizeTooltip, RingBuffer, IncrementalExtent, RealtimeLineChart, RealtimeTemporalHistogram, RealtimeHistogram, TemporalHistogram, RealtimeSwarmChart, RealtimeWaterfallChart, RealtimeHeatmap, createHatchPattern };
+export type { LegendLayout } from "./types/legendTypes";
+export { ScatterplotProps, ConnectedScatterplotProps, LineChartProps, AreaChartProps, SemanticGradientStop, DifferenceChartProps, StackedAreaChartProps, HeatmapProps, BubbleChartProps, BarChartProps, StackedBarChartProps, LikertChartProps, SwarmPlotProps, BoxPlotProps, HistogramProps, ViolinPlotProps, DotPlotProps, PieChartProps, DonutChartProps, GaugeChartProps, GaugeThreshold, FunnelChartProps, GroupedBarChartProps, SwimlaneChartProps, RidgelinePlotProps, OrbitDiagramProps, OrbitNode, ForceDirectedGraphProps, ChordDiagramProps, SankeyDiagramProps, ProcessSankeyProps, ProcessSankeyTick, TreeDiagramProps, TreemapProps, CirclePackProps, ScatterplotMatrixProps, MinimapChartProps, MinimapConfig, QuadrantChartProps, MultiAxisLineChartProps, MultiAxisSeriesConfig, CandlestickChartProps, QuadrantsConfig, QuadrantConfig, CenterlineStyle, BaseChartProps, AxisConfig, Accessor, ChartAccessor, ChartMode } from "./charts";
+export type { StreamXYFrameProps, StreamXYFrameHandle, StreamChartType, RuntimeMode, SceneNode, Changeset, StreamScales, StreamLayout, CurveType, CanvasRendererFn, XYFrameAxisConfig, BandConfig } from "./stream/types";
 export type { StreamRendererFn } from "./stream/renderers/types";
 export type { StreamOrdinalFrameProps, StreamOrdinalFrameHandle, OrdinalChartType, OrdinalScales, OrdinalSceneNode } from "./stream/ordinalTypes";
 export type { StreamNetworkFrameProps, StreamNetworkFrameHandle, NetworkChartType, NetworkSceneNode, NetworkSceneEdge, NetworkLabel, ThresholdAlertConfig } from "./stream/networkTypes";
@@ -57,7 +58,7 @@ export { darkenColor, lightenColor } from "./charts/shared/colorManipulation";
 export type { TooltipProp, TooltipConfig, TooltipField, MultiLineTooltipConfig } from "./Tooltip/Tooltip";
 export type { ArrowOfTime, WindowMode, ThresholdType, LineStyle, BarStyle, WaterfallStyle, SwarmStyle, AnnotationContext, AnnotationAnchorMode, CrosshairStyle, HoverAnnotationConfig, HoverData } from "./realtime/types";
 export type { RealtimeLineChartProps } from "./charts/realtime/RealtimeLineChart";
-export type { RealtimeTemporalHistogramProps, RealtimeHistogramProps } from "./charts/realtime/RealtimeHistogram";
+export type { RealtimeTemporalHistogramProps, RealtimeHistogramProps, TemporalHistogramProps } from "./charts/realtime/RealtimeHistogram";
 export type { RealtimeSwarmChartProps } from "./charts/realtime/RealtimeSwarmChart";
 export type { RealtimeWaterfallChartProps } from "./charts/realtime/RealtimeWaterfallChart";
 export type { RealtimeHeatmapProps } from "./charts/realtime/RealtimeHeatmap";

package/dist/components/server/renderToStaticSVG.d.ts

@@ -1,4 +1,5 @@
 import type { Datum } from "../charts/shared/datumTypes";
+import type { LegendLayout } from "../types/legendTypes";
 /**
  * Server-side rendering of Semiotic charts to standalone SVG strings.
  *
@@ -22,6 +23,7 @@ import type { StreamGeoFrameProps } from "../stream/geoTypes";
 import { type ThemeInput } from "./themeResolver";
 import { CHART_CONFIGS } from "./serverChartConfigs";
 type FrameType = "xy" | "ordinal" | "network" | "geo";
+type StaticFrameProps = (StreamXYFrameProps | StreamNetworkFrameProps | StreamOrdinalFrameProps | StreamGeoFrameProps) & ThemeAwareProps;
 interface ThemeAwareProps {
     theme?: ThemeInput;
     showLegend?: boolean;
@@ -32,10 +34,11 @@ interface ThemeAwareProps {
     background?: string;
     className?: string;
     legendPosition?: "right" | "left" | "top" | "bottom";
+    legendLayout?: LegendLayout;
     /** Prefix for SVG element IDs — used by renderDashboard to avoid collisions */
     _idPrefix?: string;
 }
-export declare function renderToStaticSVG(frameType: FrameType, props: (StreamXYFrameProps | StreamNetworkFrameProps | StreamOrdinalFrameProps | StreamGeoFrameProps) & ThemeAwareProps): string;
+export declare function renderToStaticSVG(frameType: FrameType, props: StaticFrameProps): string;
 export declare function renderXYToStaticSVG(props: StreamXYFrameProps & ThemeAwareProps): string;
 export declare function renderOrdinalToStaticSVG(props: StreamOrdinalFrameProps & ThemeAwareProps): string;
 export declare function renderNetworkToStaticSVG(props: StreamNetworkFrameProps & ThemeAwareProps): string;

package/dist/components/server/serverChartConfigs.d.ts

@@ -27,6 +27,7 @@ export declare const CHART_CONFIGS: {
         };
     };
     ConnectedScatterplot: ChartConfig;
+    QuadrantChart: ChartConfig;
     Heatmap: ChartConfig;
     BarChart: ChartConfig;
     StackedBarChart: ChartConfig;

package/dist/components/server/staticAnnotations.d.ts

@@ -29,7 +29,7 @@ interface AnnotationLayout {
     height: number;
 }
 export interface StaticAnnotationConfig {
-    annotations: Datum[];
+    annotations?: Datum[];
     scales: AnnotationScales;
     layout: AnnotationLayout;
     theme: SemioticTheme;

package/dist/components/server/staticLegend.d.ts

@@ -7,6 +7,21 @@
 import * as React from "react";
 import type { SemioticTheme } from "../store/ThemeStore";
 import type { Datum } from "../charts/shared/datumTypes";
+import type { GradientLegendConfig, LegendGroup, LegendLayout } from "../types/legendTypes";
+interface LegendItemLayout {
+    category: string;
+    width: number;
+    x: number;
+    y: number;
+}
+interface StaticLegendMetrics {
+    items: LegendItemLayout[];
+    width: number;
+    height: number;
+    swatchSize: number;
+    labelOffset: number;
+    swatchRadius: number;
+}
 export interface StaticLegendConfig {
     /** Category labels to show in legend */
     categories: string[];
@@ -28,13 +43,33 @@ export interface StaticLegendConfig {
     };
     /** Title presence (affects top-position offset) */
     hasTitle?: boolean;
+    /** SSR legend layout controls */
+    legendLayout?: LegendLayout;
+    /** Optional id namespace used for generated SVG ids */
+    idPrefix?: string;
+}
+export interface StaticLegendGroupsConfig extends Omit<StaticLegendConfig, "categories" | "colorScheme"> {
+    legendGroups: LegendGroup[];
+}
+export interface StaticGradientLegendConfig extends Omit<StaticLegendConfig, "categories" | "colorScheme"> {
+    gradient: GradientLegendConfig;
 }
+export declare function measureStaticLegend(config: StaticLegendConfig): Omit<StaticLegendMetrics, "items" | "labelOffset" | "swatchRadius">;
+export declare function measureStaticLegendGroups(config: StaticLegendGroupsConfig): Omit<StaticLegendMetrics, "items" | "labelOffset" | "swatchRadius">;
+export declare function measureStaticGradientLegend(config: StaticGradientLegendConfig): {
+    width: number;
+    height: number;
+    swatchSize: number;
+};
 /**
  * Render a static legend as SVG elements.
  * Returns null if no categories to show.
  */
 export declare function renderStaticLegend(config: StaticLegendConfig): React.ReactNode;
+export declare function renderStaticLegendGroups(config: StaticLegendGroupsConfig): React.ReactNode;
+export declare function renderStaticGradientLegend(config: StaticGradientLegendConfig): React.ReactNode;
 /**
  * Extract unique categories from data using an accessor.
  */
 export declare function extractCategories(data: any[], accessor: string | ((d: Datum) => string) | undefined): string[];
+export {};

package/dist/components/server/themeResolver.d.ts

@@ -6,7 +6,12 @@
  * No CSS custom properties — everything is concrete for inline SVG.
  */
 import type { SemioticTheme } from "../store/ThemeStore";
-export type ThemeInput = string | Partial<SemioticTheme> | undefined;
+type PartialThemeObject = Omit<Partial<SemioticTheme>, "colors" | "typography" | "tooltip"> & {
+    colors?: Partial<SemioticTheme["colors"]>;
+    typography?: Partial<SemioticTheme["typography"]>;
+    tooltip?: Partial<NonNullable<SemioticTheme["tooltip"]>>;
+};
+export type ThemeInput = string | PartialThemeObject | undefined;
 /**
  * Resolve a theme input to a full SemioticTheme object.
  *
@@ -37,3 +42,4 @@ export declare function themeStyles(theme: SemioticTheme): {
     titleFontSize: number;
     tickFontFamily: string;
 };
+export {};

package/dist/components/store/ThemeStore.d.ts

@@ -34,6 +34,8 @@ export interface SemioticTheme {
         textSecondary: string;
         grid: string;
         border: string;
+        /** Separator/border color for cell-like marks such as treemap tiles and heatmap cells. Falls back to `border`. */
+        cellBorder?: string;
         focus?: string;
         /** Linked hover/selection highlight color */
         selection?: string;
@@ -90,6 +92,12 @@ export interface ThemeStoreState {
     theme: SemioticTheme;
     setTheme: (theme: ThemeStoreUpdate) => void;
 }
-export type ThemeStoreUpdate = Partial<SemioticTheme> | "light" | "dark" | "high-contrast";
+export type SemioticThemeUpdate = Omit<Partial<SemioticTheme>, "colors" | "typography" | "tooltip" | "accessibility"> & {
+    colors?: Partial<SemioticTheme["colors"]>;
+    typography?: Partial<SemioticTheme["typography"]>;
+    tooltip?: Partial<NonNullable<SemioticTheme["tooltip"]>>;
+    accessibility?: Partial<NonNullable<SemioticTheme["accessibility"]>>;
+};
+export type ThemeStoreUpdate = SemioticThemeUpdate | "light" | "dark" | "high-contrast";
 export declare function resolveThemeUpdate(current: SemioticTheme, theme: ThemeStoreUpdate): SemioticTheme;
 export declare const ThemeProvider: import("react").FC<import("./createStore").StoreProviderProps<ThemeStoreState>>, useThemeSelector: <R>(selector: (state: ThemeStoreState) => R) => R;

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

@@ -1,14 +1,14 @@
 import * as React from "react";
 /** Scene node type used by the accessible data table — accepts any frame's scene nodes */
 type AnySceneNode = {
-    type: string;
+    type?: string;
     [key: string]: any;
 };
 declare const SR_ONLY_STYLE: React.CSSProperties;
 /**
  * Compute an aria-label describing the chart type and data shape from the scene graph.
  */
-export declare function computeCanvasAriaLabel(scene: AnySceneNode[], chartType: string): string;
+export declare function computeCanvasAriaLabel(scene: AnySceneNode[] | null | undefined, chartType: string): string;
 /**
  * Compute an aria-label for network charts from scene nodes and edges.
  */

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

@@ -1,7 +1,7 @@
 import type { Datum } from "../charts/shared/datumTypes";
 import type { ReactNode } from "react";
 import type { NetworkLabel } from "./networkTypes";
-import type { LegendGroup, GradientLegendConfig } from "../types/legendTypes";
+import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../types/legendTypes";
 type AnnotationAnchorNode = {
     type: string;
     datum: Datum | null;
@@ -43,6 +43,7 @@ export interface NetworkSVGOverlayProps {
     legendHighlightedCategory?: string | null;
     legendIsolatedCategories?: Set<string>;
     legendPosition?: "right" | "left" | "top" | "bottom";
+    legendLayout?: LegendLayout;
     /** User-provided SVG elements on top */
     foregroundGraphics?: ReactNode;
     /** Scene nodes for annotation positioning */

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

@@ -3,7 +3,7 @@ import * as React from "react";
 import type { OrdinalScales } from "./ordinalTypes";
 import type { AnnotationContext } from "../realtime/types";
 import type { ReactNode } from "react";
-import type { LegendGroup, GradientLegendConfig } from "../types/legendTypes";
+import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../types/legendTypes";
 import { type AxisExtentMode } from "../charts/shared/axisExtent";
 interface OrdinalSVGOverlayProps {
     width: number;
@@ -49,6 +49,7 @@ interface OrdinalSVGOverlayProps {
     legendHighlightedCategory?: string | null;
     legendIsolatedCategories?: Set<string>;
     legendPosition?: "right" | "left" | "top" | "bottom";
+    legendLayout?: LegendLayout;
     foregroundGraphics?: ReactNode;
     annotations?: Datum[];
     svgAnnotationRules?: (annotation: Datum, index: number, context: AnnotationContext) => ReactNode;

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

@@ -1,8 +1,10 @@
 import type { Datum } from "../charts/shared/datumTypes";
 import { type Quadtree } from "d3-quadtree";
 import { RingBuffer } from "../realtime/RingBuffer";
-import type { Changeset, StreamChartType, StreamScales, StreamLayout, SceneNode, PointSceneNode, CandlestickStyle, Style, ArrowOfTime, WindowMode, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, CurveType, BarStyle, ThemeSemanticColors } from "./types";
+import type { Changeset, StreamChartType, StreamScales, StreamLayout, SceneNode, PointSceneNode, CandlestickStyle, Style, ArrowOfTime, WindowMode, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, CurveType, BarStyle, ThemeSemanticColors, BandConfig } from "./types";
+import { type CoercibleNumber } from "./accessorUtils";
 import type { ActiveTransition } from "./pipelineTransitionUtils";
+import type { ResolvedRibbon } from "./xySceneBuilders/ribbonScene";
 import type { CustomLayout } from "./customLayout";
 import type { MarginType } from "../types/marginType";
 export interface PipelineConfig {
@@ -20,12 +22,12 @@ export interface PipelineConfig {
      *  padded domain so glyphs at the extremes don't clip the plot edge. */
     axisExtent?: import("../charts/shared/axisExtent").AxisExtentMode;
     maxCapacity?: number;
-    xAccessor?: string | ((d: Datum) => number);
-    yAccessor?: string | ((d: Datum) => number);
-    timeAccessor?: string | ((d: Datum) => number);
-    valueAccessor?: string | ((d: Datum) => number);
+    xAccessor?: string | ((d: Datum) => CoercibleNumber);
+    yAccessor?: string | ((d: Datum) => CoercibleNumber);
+    timeAccessor?: string | ((d: Datum) => CoercibleNumber);
+    valueAccessor?: string | ((d: Datum) => CoercibleNumber);
     colorAccessor?: string | ((d: Datum) => string);
-    sizeAccessor?: string | ((d: Datum) => number);
+    sizeAccessor?: string | ((d: Datum) => CoercibleNumber);
     groupAccessor?: string | ((d: Datum) => string);
     categoryAccessor?: string | ((d: Datum) => string);
     lineDataAccessor?: string;
@@ -40,16 +42,17 @@ export interface PipelineConfig {
     baseline?: "zero" | "wiggle" | "silhouette";
     /** Stack order — see StreamXYFrameProps.stackOrder. */
     stackOrder?: "key" | "insideOut" | "asc" | "desc";
-    openAccessor?: string | ((d: Datum) => number);
-    highAccessor?: string | ((d: Datum) => number);
-    lowAccessor?: string | ((d: Datum) => number);
-    closeAccessor?: string | ((d: Datum) => number);
+    openAccessor?: string | ((d: Datum) => CoercibleNumber);
+    highAccessor?: string | ((d: Datum) => CoercibleNumber);
+    lowAccessor?: string | ((d: Datum) => CoercibleNumber);
+    closeAccessor?: string | ((d: Datum) => CoercibleNumber);
     candlestickStyle?: CandlestickStyle;
     /** Internal: set by PipelineStore when open/close accessors are both missing */
     candlestickRangeMode?: boolean;
-    boundsAccessor?: string | ((d: Datum) => number);
+    boundsAccessor?: string | ((d: Datum) => CoercibleNumber);
     boundsStyle?: any;
-    y0Accessor?: string | ((d: Datum) => number);
+    y0Accessor?: string | ((d: Datum) => CoercibleNumber);
+    band?: BandConfig | BandConfig[];
     gradientFill?: {
         topOpacity: number;
         bottomOpacity: number;
@@ -149,8 +152,12 @@ export declare class PipelineStore {
     private getCategory;
     private getSize;
     private getColor;
-    private getBounds;
     private getY0;
+    /** Unified ribbon list — `boundsAccessor` + `band` both compose into
+     *  this single array (see `resolveRibbons`). Read by the scene
+     *  builders, y-extent expansion, and tooltip enrichment (which
+     *  filters on `kind === "band"`). Empty when neither prop is set. */
+    resolvedRibbons: ResolvedRibbon[];
     private getOpen;
     private getHigh;
     private getLow;

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

@@ -1,36 +1,9 @@
 import type { Datum } from "../charts/shared/datumTypes";
-import type { StreamScales, MarginalGraphicsConfig } from "./types";
+import type { StreamScales, MarginalGraphicsConfig, XYFrameAxisConfig } from "./types";
 import type { AnnotationContext } from "../realtime/types";
 import type { ReactNode } from "react";
-import type { LegendGroup, GradientLegendConfig } from "../types/legendTypes";
-export interface AxisConfig {
-    orient: "left" | "right" | "top" | "bottom";
-    label?: string;
-    ticks?: number;
-    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. Accepts `number | Date`: values pass through
-     *  to the scale (d3-scale's `scaleTime` reads Dates natively;
-     *  `scaleLinear` accepts numbers — feeding a Date into a linear
-     *  scale via `valueOf()` works at runtime but `tickFormat` receives
-     *  the Date as-is, so user formatters should match the axis's
-     *  underlying scale type). Mirrors the ordinal frame's
-     *  `rTickValues` contract. */
-    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);
-}
+import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../types/legendTypes";
+export type AxisConfig = XYFrameAxisConfig;
 interface SVGOverlayProps {
     width: number;
     height: number;
@@ -78,6 +51,7 @@ interface SVGOverlayProps {
     legendIsolatedCategories?: Set<string>;
     /** Legend position relative to chart area */
     legendPosition?: "right" | "left" | "top" | "bottom";
+    legendLayout?: LegendLayout;
     foregroundGraphics?: ReactNode;
     marginalGraphics?: MarginalGraphicsConfig;
     xValues?: number[];

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

@@ -13,7 +13,7 @@ export declare function xySceneNodeToSVG(node: SceneNode, i: number, idPrefix?:
 export declare function networkSceneNodeToSVG(node: NetworkSceneNode, i: number): React.ReactNode;
 export declare function networkSceneEdgeToSVG(edge: NetworkSceneEdge, i: number): React.ReactNode;
 export declare function networkLabelToSVG(label: NetworkLabel, i: number): React.ReactNode;
-export declare function ordinalSceneNodeToSVG(node: OrdinalSceneNode, i: number): React.ReactNode;
+export declare function ordinalSceneNodeToSVG(node: OrdinalSceneNode, i: number, idPrefix?: string): React.ReactNode;
 export declare function geoSceneNodeToSVG(node: GeoSceneNode, i: number): React.ReactNode;
 /**
  * Returns true when running in a true server/Node.js context where

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

@@ -12,6 +12,7 @@
  * the variable in the dependency array so the reference changes when behavior changes.
  */
 export declare function accessorsEquivalent(a: string | ((...args: any[]) => any) | undefined, b: string | ((...args: any[]) => any) | undefined): boolean;
-export declare function resolveAccessor<T extends Record<string, unknown>>(accessor: string | ((d: T) => number) | undefined, fallback: string): (d: T) => number;
+export type CoercibleNumber = number | Date | string;
+export declare function resolveAccessor<T extends Record<string, unknown>>(accessor: string | ((d: T) => CoercibleNumber) | undefined, fallback: string): (d: T) => number;
 export declare function resolveRawAccessor<T extends Record<string, unknown>>(accessor: string | ((d: T) => unknown) | undefined, fallback: string): (d: T) => unknown;
 export declare function resolveStringAccessor<T extends Record<string, unknown>>(accessor: string | ((d: T) => string) | undefined, fallback?: string): ((d: T) => string) | undefined;

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

@@ -1,6 +1,6 @@
 import type { ReactNode } from "react";
 import type { GeoProjection, GeoPath, GeoPermissibleObjects } from "d3-geo";
-import type { GradientLegendConfig, LegendGroup } from "../types/legendTypes";
+import type { GradientLegendConfig, LegendGroup, LegendLayout } from "../types/legendTypes";
 import type { Style, DecayConfig, PulseConfig, TransitionConfig, StalenessConfig, SceneDatum, PointSceneNode, ThemeSemanticColors } from "./types";
 import type { AnimateProp } from "./pipelineTransitionUtils";
 import type { HoverAnnotationConfig, HoverData } from "../realtime/types";
@@ -191,6 +191,7 @@ export interface StreamGeoFrameProps<T = Datum> {
         gradient: GradientLegendConfig;
     };
     legendPosition?: "right" | "left" | "top" | "bottom";
+    legendLayout?: LegendLayout;
     legendHoverBehavior?: (item: {
         label: string;
     } | null) => void;

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

@@ -19,6 +19,7 @@ export interface HoverPointerCoords {
     clientX: number;
     clientY: number;
 }
+export declare function normalizeHoverDatum(rawDatum: any): any;
 /**
  * Build a HoverData object from a raw datum and pixel coordinates.
  * The raw datum is preserved as `hover.data` for tooltip / callback

package/dist/components/stream/layouts/hierarchyLayoutPlugin.d.ts

@@ -5,7 +5,7 @@ import type { NetworkLayoutPlugin } from "../networkTypes";
  * Uses d3-hierarchy for all layout computations. This plugin is `hierarchical: true`,
  * meaning the input data is a single root node object rather than flat nodes+edges arrays.
  *
- * The hierarchy root is passed via `(config as any).__hierarchyRoot`, set by the store
+ * The hierarchy root is passed via `config.__hierarchyRoot`, set by the store
  * before calling computeLayout. The plugin builds the d3 hierarchy internally, runs the
  * appropriate layout algorithm, and populates the nodes/edges arrays.
  *

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

@@ -1,5 +1,5 @@
 import type { ReactNode } from "react";
-import type { LegendGroup, GradientLegendConfig } from "../types/legendTypes";
+import type { LegendGroup, GradientLegendConfig, LegendLayout } from "../types/legendTypes";
 export interface LegendRenderConfig {
     legend: ReactNode | {
         legendGroups: LegendGroup[];
@@ -15,6 +15,7 @@ export interface LegendRenderConfig {
         left: number;
     };
     legendPosition?: "right" | "left" | "top" | "bottom";
+    legendLayout?: LegendLayout;
     title?: string | ReactNode;
     legendHoverBehavior?: (item: {
         label: string;