semiotic 3.8.4 → 3.8.6

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

@@ -0,0 +1,35 @@
+export interface GradientStop {
+    /** Position along the gradient, clamped to 0–1. */
+    offset: number;
+    /** Stop color. Omit to inherit the mark's resolved color. */
+    color?: string;
+    /** Stop opacity, clamped to 0–1. */
+    opacity?: number;
+}
+export interface GradientConfig {
+    stops: GradientStop[];
+}
+interface ColorStopsConfig {
+    colorStops: Array<{
+        offset: number;
+        color: string;
+    }>;
+}
+interface OpacityEndpointsConfig {
+    topOpacity?: number;
+    bottomOpacity?: number;
+}
+export interface SemanticGradientStopInput {
+    at: number;
+    color: string;
+    opacity?: number;
+}
+export type GradientInput = GradientConfig | boolean | ColorStopsConfig | OpacityEndpointsConfig;
+export type ColorGradientInput = GradientConfig | ColorStopsConfig;
+export type SemanticGradientInput = GradientConfig | SemanticGradientStopInput[];
+export declare const DEFAULT_GRADIENT: GradientConfig;
+export declare function normalizeGradient(input: GradientInput | null | undefined, defaultGradient?: GradientConfig): GradientConfig | undefined;
+export declare function normalizeColorGradient(input: ColorGradientInput | null | undefined): GradientConfig | undefined;
+export declare function normalizeSemanticGradient(input: SemanticGradientInput | null | undefined): GradientConfig | undefined;
+export declare function reverseGradient(gradient: GradientConfig): GradientConfig;
+export {};

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

@@ -1,15 +1,8 @@
 /**
- * Declarative hatch-fill descriptor — a single value that renders as a
- * diagonal-line pattern on BOTH rendering backends.
+ * Declarative hatch-fill descriptor that renders as a diagonal-line pattern
+ * on both rendering backends.
  *
- * The library historically had two disjoint hatch primitives: a canvas
- * `createHatchPattern` (→ `CanvasPattern`) and an SVG `<pattern>` builder
- * (`hatchFill` recipe / `createSVGHatchPattern`). A caller had to know
- * which medium they were painting into and hand-produce the right thing —
- * which is why a `CanvasPattern` returned from a `pieceStyle` silently
- * collapses to a solid color in SSR (`svgFill` drops non-string fills).
- *
- * `HatchFill` closes that gap: it is a plain, serializable descriptor that
+ * `HatchFill` is a plain, serializable descriptor that
  * can be set directly as `style.fill`. The canvas renderer resolves it to a
  * `CanvasPattern` (`resolveHatchCanvasPattern`); the SVG serializer resolves
  * it to a `<pattern>` def + `url(#id)` (`hatchPatternDef` / `hatchFillId`).

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

@@ -2,9 +2,7 @@ export { DEFAULT_COLOR } from "./colorUtils";
 import type { SelectionHookResult } from "./selectionUtils";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { Accessor, SelectionConfig, LinkedHoverProp, ChartMode, HoverHighlightMode, ResolvedMobileInteractionConfig } from "./types";
-import type { MarginType, PartialMargin } from "../../types/marginType";
 import type { TransitionConfig } from "../../stream/types";
-import type { LegendValue } from "../../types/legendTypes";
 import type { Datum } from "./datumTypes";
 import type { ChartModeInput, ChartModeResult } from "./chartMode";
 export { DISABLED_MOBILE_INTERACTION, MOBILE_INTERACTION_DEFAULTS, MOBILE_INTERACTION_MIN_HIT_RADIUS, MOBILE_INTERACTION_TARGET_SIZE, isChartMode, resolveChartMode, resolveMobileInteraction, } from "./chartMode";
@@ -96,54 +94,8 @@ export declare function getCrosshairProps(linkedHover: unknown, crosshairSourceI
     linkedCrosshairName: string;
     linkedCrosshairSourceId: string;
 } | undefined;
-/**
- * Hook to create a legend and compute margins with legend-aware adjustment.
- * Consolidates the shouldShowLegend / createLegend / margin merge / right-margin
- * expansion pattern that every chart with color encoding repeats.
- */
-export type LegendPosition = "right" | "left" | "top" | "bottom";
-export declare function useChartLegendAndMargin({ data, colorBy, colorScale, showLegend, legendPosition, userMargin, defaults, categories, additionalLegend, }: {
-    data: Array<Datum>;
-    colorBy: Accessor<string> | undefined;
-    colorScale: ((v: string) => string) | undefined;
-    showLegend: boolean | undefined;
-    legendPosition?: LegendPosition;
-    userMargin: PartialMargin | undefined;
-    defaults?: MarginType;
-    categories?: string[];
-    /** Caller legend composed after the chart's inferred categorical groups. */
-    additionalLegend?: LegendValue;
-}): {
-    legend: LegendValue | undefined;
-    margin: MarginType;
-    legendPosition: LegendPosition;
-};
-export type LegendInteractionMode = "highlight" | "isolate" | "none";
-export interface LegendInteractionState {
-    highlightedCategory: string | null;
-    isolatedCategories: Set<string>;
-    onLegendHover: (item: {
-        label: string;
-    } | null) => void;
-    onLegendClick: (item: {
-        label: string;
-    }) => void;
-    /** Selection predicate that dims non-matching data — use with wrapStyleWithSelection */
-    legendSelectionHook: {
-        isActive: boolean;
-        predicate: (d: Datum) => boolean;
-    } | null;
-}
-/**
- * Hook managing legend highlight/isolate interaction.
- * - "highlight": hover over a legend item produces a selection hook that
- *   `wrapStyleWithSelection` uses to dim non-matching data. The actual
- *   dim opacity resolves in this order: per-chart
- *   `selection.unselectedOpacity` → `theme.colors.selectionOpacity` →
- *   `DEFAULT_SELECTION_OPACITY` fallback.
- * - "isolate": click toggles category visibility; click all to reset
- */
-export declare function useLegendInteraction(mode: LegendInteractionMode | undefined, colorBy: string | ((d: Datum) => string) | undefined, allCategories: string[]): LegendInteractionState;
+export { useChartLegendAndMargin, useLegendInteraction, } from "./useChartLegend";
+export type { LegendPosition, LegendInteractionMode, LegendInteractionState, } from "./useChartLegend";
 /**
  * React-facing alias for {@link resolveChartMode}. Mode resolution is kept
  * pure so non-React renderers (notably semiotic/server) consume the exact same

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

@@ -5,5 +5,5 @@
  * This compact registry is intentionally separate from validation metadata:
  * config serialization only needs chart-name membership.
  */
-export declare const KNOWN_CHART_COMPONENTS: readonly ["BarChart", "StackedBarChart", "GroupedBarChart", "SwarmPlot", "BoxPlot", "Histogram", "ViolinPlot", "RidgelinePlot", "DotPlot", "PieChart", "DonutChart", "GaugeChart", "FunnelChart", "SwimlaneChart", "LikertChart", "LineChart", "AreaChart", "DifferenceChart", "StackedAreaChart", "Scatterplot", "BubbleChart", "Heatmap", "QuadrantChart", "MultiAxisLineChart", "CandlestickChart", "ConnectedScatterplot", "ScatterplotMatrix", "MinimapChart", "ForceDirectedGraph", "SankeyDiagram", "ProcessSankey", "ChordDiagram", "TreeDiagram", "Treemap", "CirclePack", "OrbitDiagram", "ChoroplethMap", "ProportionalSymbolMap", "FlowMap", "DistanceCartogram", "RealtimeLineChart", "RealtimeHistogram", "TemporalHistogram", "RealtimeSwarmChart", "RealtimeWaterfallChart", "RealtimeHeatmap", "GaltonBoardChart", "EventDropChart", "PhysicsPileChart", "CollisionSwarmChart", "GauntletChart", "ProcessFlowChart", "PhysicalFlowChart", "BigNumber"];
+export declare const KNOWN_CHART_COMPONENTS: readonly ["BarChart", "StackedBarChart", "GroupedBarChart", "SwarmPlot", "BoxPlot", "Histogram", "ViolinPlot", "RidgelinePlot", "DotPlot", "PieChart", "DonutChart", "GaugeChart", "FunnelChart", "SwimlaneChart", "LikertChart", "LineChart", "BumpChart", "AreaChart", "DifferenceChart", "StackedAreaChart", "Scatterplot", "BubbleChart", "Heatmap", "QuadrantChart", "MultiAxisLineChart", "CandlestickChart", "ConnectedScatterplot", "ScatterplotMatrix", "MinimapChart", "ForceDirectedGraph", "SankeyDiagram", "ProcessSankey", "ChordDiagram", "TreeDiagram", "Treemap", "CirclePack", "OrbitDiagram", "ChoroplethMap", "ProportionalSymbolMap", "FlowMap", "DistanceCartogram", "RealtimeLineChart", "RealtimeHistogram", "TemporalHistogram", "RealtimeSwarmChart", "RealtimeWaterfallChart", "RealtimeHeatmap", "GaltonBoardChart", "EventDropChart", "PhysicsPileChart", "CollisionSwarmChart", "GauntletChart", "CrucibleChart", "ProcessFlowChart", "PhysicalFlowChart", "BigNumber"];
 export declare function isKnownChartComponent(componentName: string): boolean;

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

@@ -18,8 +18,7 @@ import type { AutoPlaceAnnotations } from "../../recipes/annotationLayout";
  * 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.
+ * source flow through without a cast at the call site.
  */
 type FrameTooltipContent = (d: HoverData) => ReactNode;
 /**

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

@@ -0,0 +1,58 @@
+import type { Accessor } from "./types";
+import type { MarginType, PartialMargin } from "../../types/marginType";
+import type { LegendLayout, LegendValue } from "../../types/legendTypes";
+import type { Datum } from "./datumTypes";
+/**
+ * Hook to create a legend and compute margins with legend-aware adjustment.
+ * Consolidates the shouldShowLegend / createLegend / margin merge / right-margin
+ * expansion pattern that every chart with color encoding repeats.
+ */
+export type LegendPosition = "right" | "left" | "top" | "bottom";
+export declare function useChartLegendAndMargin({ data, colorBy, colorScale, showLegend, legendPosition, userMargin, defaults, categories, additionalLegend, chartWidth, legendLayout, hasTitle, }: {
+    data: Array<Datum>;
+    colorBy: Accessor<string> | undefined;
+    colorScale: ((v: string) => string) | undefined;
+    showLegend: boolean | undefined;
+    legendPosition?: LegendPosition;
+    userMargin: PartialMargin | undefined;
+    defaults?: MarginType;
+    categories?: string[];
+    /** Caller legend composed after the chart's inferred categorical groups. */
+    additionalLegend?: LegendValue;
+    /** Total chart width, used to estimate wrapping for top/bottom legends. */
+    chartWidth?: number;
+    /** Legend metrics shared with the renderer. */
+    legendLayout?: LegendLayout;
+    /** Reserve the chart-title band above a top legend. */
+    hasTitle?: boolean;
+}): {
+    legend: LegendValue | undefined;
+    margin: MarginType;
+    legendPosition: LegendPosition;
+};
+export type LegendInteractionMode = "highlight" | "isolate" | "none";
+export interface LegendInteractionState {
+    highlightedCategory: string | null;
+    isolatedCategories: Set<string>;
+    onLegendHover: (item: {
+        label: string;
+    } | null) => void;
+    onLegendClick: (item: {
+        label: string;
+    }) => void;
+    /** Selection predicate that dims non-matching data — use with wrapStyleWithSelection */
+    legendSelectionHook: {
+        isActive: boolean;
+        predicate: (d: Datum) => boolean;
+    } | null;
+}
+/**
+ * Hook managing legend highlight/isolate interaction.
+ * - "highlight": hover over a legend item produces a selection hook that
+ *   `wrapStyleWithSelection` uses to dim non-matching data. The actual
+ *   dim opacity resolves in this order: per-chart
+ *   `selection.unselectedOpacity` → `theme.colors.selectionOpacity` →
+ *   `DEFAULT_SELECTION_OPACITY` fallback.
+ * - "isolate": click toggles category visibility; click all to reset
+ */
+export declare function useLegendInteraction(mode: LegendInteractionMode | undefined, colorBy: string | ((d: Datum) => string) | undefined, allCategories: string[]): LegendInteractionState;

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

@@ -8,6 +8,7 @@ import type { PartialMargin } from "../../types/marginType";
 import type { SelectionHookResult } from "./selectionUtils";
 import type { ReactElement, ReactNode } from "react";
 import type { LegendValue } from "../../types/legendTypes";
+import type { LegendLayout } from "../../types/legendTypes";
 /**
  * Input parameters for useChartSetup.
  *
@@ -46,6 +47,8 @@ export interface ChartSetupInput {
     showLegend: boolean | undefined;
     /** Caller legend appended to inferred categorical legend groups. */
     legend?: LegendValue;
+    /** Shared legend metrics, including any side-axis gutter. */
+    legendLayout?: LegendLayout;
     /** User-provided margin */
     userMargin: PartialMargin | undefined;
     /** Mode-resolved margin defaults */
@@ -76,6 +79,8 @@ export interface ChartSetupInput {
     width: number;
     /** Resolved height from useChartMode */
     height: number;
+    /** Whether the resolved chart mode includes a title. */
+    hasTitle?: boolean;
 }
 /**
  * Output from useChartSetup.

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

@@ -1,7 +1,7 @@
 import type { Ref, RefObject, ReactElement, ReactNode } from "react";
 import { useChartMode } from "./hooks";
 import { type ChartSetupResult } from "./useChartSetup";
-import type { Accessor, ChartMode, SelectionConfig, LinkedHoverProp, MobileInteractionProp } from "./types";
+import type { Accessor, ChartMode, SelectionConfig, LinkedHoverProp, MobileInteractionProp, HoverHighlightMode } from "./types";
 import type { MobileVisualizationContract } from "./auditMobileVisualization";
 import type { ResponsiveRule } from "./responsiveRules";
 import type { OnObservationCallback } from "../../store/ObservationStore";
@@ -9,6 +9,7 @@ import { type PartialMargin, type MarginType } from "../../types/marginType";
 import type { Datum } from "./datumTypes";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { LegendValue } from "../../types/legendTypes";
+import type { LegendInteractionMode, LegendPosition } from "./useChartLegend";
 /**
  * Margin shorthand → sided form. The Stream*Frame margin props only
  * accept the sided object form, so HOCs that expose the user-friendly
@@ -67,9 +68,13 @@ interface DataSetupOptions extends ScaffoldOptions {
     colorBy?: Accessor<string>;
     /** Caller legend appended to the inferred colorBy legend. */
     legend?: LegendValue;
+    legendInteraction?: LegendInteractionMode;
+    legendPosition?: LegendPosition;
     /** Pass-through chart-setup inputs. */
     selection?: SelectionConfig;
     linkedHover?: LinkedHoverProp;
+    /** Dim sibling categories while hovering a custom-layout mark. */
+    hoverHighlight?: HoverHighlightMode;
     onObservation?: OnObservationCallback;
     onClick?: (datum: Datum, ev: {
         x: number;

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

@@ -47,6 +47,7 @@ export interface NetworkChartSetupInput<TNode extends Datum = Datum, TEdge exten
     userMargin?: PartialMargin;
     width: number;
     height: number;
+    hasTitle?: boolean;
     loading?: boolean;
     /** Custom content rendered in place of the default skeleton while `loading` is true. */
     loadingContent?: ReactNode | false;

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

@@ -49,7 +49,7 @@ export declare function useStreamingLegend({ isPushMode, colorBy, colorScheme, s
     };
     streamingLegend: {
         legendGroups: {
-            styleFn: (d: import("../../types/legendTypes").LegendItem) => Record<string, string | number>;
+            styleFn: (d: import("../../semiotic-geo").LegendItem) => Record<string, string | number>;
             type: "fill";
             items: {
                 label: string;

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

@@ -7,23 +7,8 @@ import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types"
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import { type StyleRule } from "../shared/styleRules";
 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;
-}
-/**
- * Convert value-anchored `semanticGradient` stops (`{ at, color }` on the value
- * scale, 0–100) into the frame's `gradientFill.colorStops` (offset 0 = top).
- * Exported so the server (`renderChart`) config resolves it identically to this
- * HOC — otherwise SSR silently drops `semanticGradient` and paints a flat area.
- */
-export declare function semanticGradientToColorStops(stops: SemanticGradientStop[]): Array<{
-    offset: number;
-    color: string;
-}>;
+import { type ColorGradientInput, type GradientInput, type SemanticGradientInput, type SemanticGradientStopInput } from "../shared/gradient";
+export type SemanticGradientStop = SemanticGradientStopInput;
 /**
  * AreaChart component props
  */
@@ -101,28 +86,28 @@ export interface AreaChartProps<TDatum extends Datum = Datum> extends BaseChartP
      */
     y0Accessor?: ChartAccessor<TDatum, number>;
     /**
-     * Gradient fill from line to baseline. Set `true` for default opacity (80% → 5%),
-     * `{ topOpacity, bottomOpacity }` for custom opacity, or
-     * `{ colorStops: [{offset, color}] }` for multi-color gradients.
+     * Gradient fill from the line to the baseline. Offset 0 is the line/top and
+     * offset 1 is the baseline. Omit a stop color to inherit the area color.
+     * @example
+     * `{ stops: [{ offset: 0, opacity: 0.8 }, { offset: 1, opacity: 0.05 }] }`
      * @default false
      */
-    gradientFill?: boolean | {
-        topOpacity: number;
-        bottomOpacity: number;
-    } | {
-        colorStops: Array<{
-            offset: number;
-            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).
+    gradientFill?: GradientInput;
+    /**
+     * Value-anchored area gradient. Offset 0 is the resolved y-domain minimum
+     * and offset 1 is the resolved y-domain maximum.
      * When set, this takes precedence over `gradientFill`.
+     * @example
+     * `{ stops: [{ offset: 0, color: "#4e79a7" }, { offset: 1, color: "#d62728" }] }`
+     */
+    semanticGradient?: SemanticGradientInput;
+    /**
+     * Color the area's top-edge line with hard value bands derived from
+     * `semanticGradient`. Stop opacity is intentionally ignored for the line.
+     * Set to `false` to retain the normal solid stroke (or `lineGradient`).
+     * @default true when semanticGradient is set
      */
-    semanticGradient?: SemanticGradientStop[];
+    semanticLine?: boolean;
     /**
      * Area opacity (flat fill, ignored when gradientFill is set)
      * @default 0.7
@@ -131,12 +116,7 @@ export interface AreaChartProps<TDatum extends Datum = Datum> extends BaseChartP
     /**
      * Horizontal gradient for the line stroke. Color stops define a left-to-right gradient.
      */
-    lineGradient?: {
-        colorStops: Array<{
-            offset: number;
-            color: string;
-        }>;
-    };
+    lineGradient?: ColorGradientInput;
     /**
      * Show line on top of area
      * @default true
@@ -280,7 +260,10 @@ export interface AreaChartProps<TDatum extends Datum = Datum> extends BaseChartP
  *   xAccessor="t"
  *   yAccessor="value"
  *   color="steelblue"
- *   gradientFill={{ topOpacity: 0.8, bottomOpacity: 0.05 }}
+ *   gradientFill={{ stops: [
+ *     { offset: 0, opacity: 0.8 },
+ *     { offset: 1, opacity: 0.05 },
+ *   ] }}
  * />
  * ```
  *

package/dist/components/charts/xy/BumpChart.capability.d.ts

@@ -0,0 +1,11 @@
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+/**
+ * BumpChart capability — the ranking-over-x chart. Its canonical job is the
+ * `rank` intent: several series ranked against each other at each x-column,
+ * with rank as vertical position and the crossings telling the "who overtook
+ * whom" story. The `ribbon` variant additionally encodes magnitude.
+ *
+ * Read alongside `BumpChart.tsx`; this is what makes the chart discoverable
+ * through `suggestCharts` and self-describing through `describeChart` (L4).
+ */
+export declare const BumpChartCapability: ChartCapability;

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

@@ -0,0 +1,161 @@
+import * as React from "react";
+import type { RealtimeFrameHandle } from "../../realtime/types";
+import type { StreamXYFrameProps, Style } from "../../stream/types";
+import type { LayoutContext, LayoutResult } from "../../stream/customLayout";
+import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
+import type { Datum } from "../shared/datumTypes";
+import type { TooltipProp } from "../../Tooltip/Tooltip";
+import { type StyleRule } from "../shared/styleRules";
+import type { LegendValue } from "../../types/legendTypes";
+import type { LegendInteractionMode, LegendPosition } from "../shared/useChartLegend";
+export interface RankedBumpDatum<TDatum extends Datum = Datum> extends Datum {
+    x: number;
+    y: number;
+    __bumpRaw: TDatum;
+    __bumpSeries: string;
+    __bumpColorGroup: string;
+    __bumpValue: number;
+    __bumpRank: number;
+    __bumpXValue: unknown;
+    __bumpHighlighted: boolean;
+}
+export interface RankedBumpData<TDatum extends Datum = Datum> {
+    data: RankedBumpDatum<TDatum>[];
+    xValues: unknown[];
+    seriesOrder: string[];
+    overallOrder: string[];
+    valueExtent: [number, number];
+}
+export interface RankBumpDataOptions<TDatum extends Datum = Datum> {
+    xAccessor?: ChartAccessor<TDatum, number | Date | string>;
+    yAccessor?: ChartAccessor<TDatum, number>;
+    lineBy?: ChartAccessor<TDatum, string>;
+    rankDirection?: "descending" | "ascending";
+    highlightTop?: number;
+}
+export declare function mapBumpAnnotations(annotations: Datum[] | undefined, xValues: unknown[]): Datum[] | undefined;
+export declare function resolveBumpColorScheme(options: {
+    seriesOrder: string[];
+    overallOrder: string[];
+    highlightTop?: number;
+    color?: string;
+    colorScheme?: string | string[] | Record<string, string>;
+    neutralColor?: string;
+    themeCategorical?: string[];
+    themeNeutral?: string;
+}): string | string[] | Record<string, string> | undefined;
+/**
+ * Rank every x-column and return the flattened, frame-ready rows used by
+ * BumpChart. Ranking is ordinal and deterministic: equal values retain series
+ * first-appearance order.
+ */
+export declare function rankBumpData<TDatum extends Datum = Datum>(input: TDatum[], options?: RankBumpDataOptions<TDatum>): RankedBumpData<TDatum>;
+export interface BumpLayoutConfig {
+    ribbon: boolean;
+    curve: "smooth" | "linear";
+    samplesPerSegment: number;
+    ribbonSizeRange: [number, number];
+    valueExtent: [number, number];
+    seriesOrder: string[];
+    lineWidth: number;
+    ribbonOpacity: number;
+    lineOpacity: number;
+    neutralColor?: string;
+    color?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+    styleRules?: ReadonlyArray<StyleRule>;
+    areaStyle?: (datum: Datum) => Style;
+    pointStyle?: (datum: Datum) => Style & {
+        r?: number;
+    };
+    labelStyle?: React.CSSProperties | ((datum: Datum) => React.CSSProperties);
+    showPoints: boolean;
+    pointRadius: number;
+    showLabels: boolean | "start" | "end" | "both";
+}
+export declare function bumpLayout(ctx: LayoutContext<BumpLayoutConfig>): LayoutResult;
+export interface BumpChartProps<TDatum extends Datum = Datum> extends BaseChartProps, AxisConfig {
+    /** Flat observations. Each x-column is ranked from `yAccessor`. */
+    data: TDatum[];
+    /** Ranking column accessor. First-seen order determines the x-axis order. Default `"x"`. */
+    xAccessor?: ChartAccessor<TDatum, number | Date | string>;
+    /** Numeric magnitude to rank and, in ribbon mode, encode as width. Default `"y"`. */
+    yAccessor?: ChartAccessor<TDatum, number>;
+    /** Series identity accessor. Default `"series"`. */
+    lineBy?: ChartAccessor<TDatum, string>;
+    /** Highest values rank first by default; use `"ascending"` for metrics where lower is better. */
+    rankDirection?: "descending" | "ascending";
+    /** Draw magnitude-encoded, perpendicular-offset areas instead of fixed-width lines. */
+    ribbon?: boolean;
+    /** Centerline shape. Smooth uses horizontal-tangent cubic segments. Default `"smooth"`. */
+    curve?: "smooth" | "linear";
+    /** Full ribbon width range in pixels. Default `[4, 28]`. */
+    ribbonSizeRange?: [number, number];
+    /** Number of centerline samples per ranking interval. Default `12`. */
+    samplesPerSegment?: number;
+    /** Fixed line width when `ribbon` is false. Default `3`. */
+    lineWidth?: number;
+    /** Highlight only the N best series by mean rank; all others share `neutralColor`. */
+    highlightTop?: number;
+    /** Shared color for trajectories outside `highlightTop`. */
+    neutralColor?: string;
+    /** Ordered per-datum style rules. Trajectory rules resolve against each series' first observation. */
+    styleRules?: StyleRule[];
+    /** Style endpoint labels globally or per original datum. */
+    labelStyle?: React.CSSProperties | ((datum: TDatum) => React.CSSProperties);
+    colorScheme?: string | string[] | Record<string, string>;
+    ribbonOpacity?: number;
+    lineOpacity?: number;
+    showPoints?: boolean;
+    pointRadius?: number;
+    /** Endpoint labels. `true` is equivalent to `"end"`. Default `true`. */
+    showLabels?: boolean | "start" | "end" | "both";
+    showAxes?: boolean;
+    showGrid?: boolean;
+    showLegend?: boolean;
+    /** Additional legend content. */
+    legend?: LegendValue;
+    legendInteraction?: LegendInteractionMode;
+    legendPosition?: LegendPosition;
+    enableHover?: boolean;
+    /** Dim every trajectory except the hovered series. Default `true`. */
+    hoverHighlight?: boolean | "series";
+    tooltip?: TooltipProp;
+    /** Annotation objects. X coordinates may use the original x values. */
+    annotations?: Datum[];
+    /** Additional frame props, with BumpChart geometry remaining controlled. */
+    frameProps?: Partial<Omit<StreamXYFrameProps, "chartType" | "data" | "size" | "customLayout" | "layoutConfig">>;
+}
+/**
+ * Ranking-based bump chart. Each x-column ranks its series by `yAccessor`, and
+ * rank becomes vertical position. With `ribbon`, magnitude is encoded by true
+ * screen-space ribbon thickness instead of a vertically interpolated area.
+ *
+ * @example
+ * // Fixed-width ranking lines, coloring only the top 3 series by mean rank.
+ * <BumpChart
+ *   data={data}
+ *   xAccessor="quarter"
+ *   yAccessor="sales"
+ *   lineBy="team"
+ *   highlightTop={3}
+ * />
+ *
+ * @example
+ * // Magnitude-encoded ribbons (width ∝ value) with ascending rank for a
+ * // "lower is better" metric.
+ * <BumpChart
+ *   data={data}
+ *   xAccessor="week"
+ *   yAccessor="latencyMs"
+ *   lineBy="service"
+ *   rankDirection="ascending"
+ *   ribbon
+ * />
+ */
+export declare const BumpChart: {
+    <TDatum extends Datum = Datum>(props: BumpChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

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

@@ -5,6 +5,7 @@ import type { RealtimeFrameHandle } from "../../realtime/types";
 import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
+import { type GradientInput } from "../shared/gradient";
 export { computeDifferenceSegments } from "./differenceSegments";
 /**
  * DifferenceChart props
@@ -38,16 +39,8 @@ export interface DifferenceChartProps<TDatum extends Datum = Datum> extends Base
     curve?: "linear" | "monotoneX" | "monotoneY" | "step" | "stepAfter" | "stepBefore" | "basis" | "cardinal" | "catmullRom";
     /** Fill opacity for the difference region. Default `0.6`. */
     areaOpacity?: number;
-    /** Gradient fill across each segment, same shape as AreaChart.gradientFill. */
-    gradientFill?: boolean | {
-        topOpacity: number;
-        bottomOpacity: number;
-    } | {
-        colorStops: Array<{
-            offset: number;
-            color: string;
-        }>;
-    };
+    /** Gradient fill from each segment's tip (offset 0) to its base (offset 1). */
+    gradientFill?: GradientInput;
     /** Enable hover annotations. */
     enableHover?: boolean;
     /** Show grid lines. Default `false`. */

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

@@ -2,6 +2,7 @@ import type { Datum } from "../shared/datumTypes";
 import * as React from "react";
 import type { StreamXYFrameProps } from "../../stream/types";
 import type { RealtimeFrameHandle } from "../../realtime/types";
+import type { GradientLegendValue } from "../../types/legendTypes";
 import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
@@ -103,6 +104,8 @@ export interface HeatmapProps<TDatum extends Datum = Datum> extends BaseChartPro
      * @default "right"
      */
     legendPosition?: "right" | "left" | "top" | "bottom";
+    /** Gradient legend layout overrides. */
+    legend?: Pick<GradientLegendValue, "legendDistance">;
     /**
      * Legend interaction mode.
      * - "highlight": hover dims non-hovered categories to 30% opacity

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

@@ -7,6 +7,7 @@ import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types"
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import { type StyleRule } from "../shared/styleRules";
 import type { AnomalyConfig, ForecastConfig } from "../shared/statisticalOverlays";
+import { type ColorGradientInput } from "../shared/gradient";
 import type { LegendValue } from "../../types/legendTypes";
 /**
  * LineChart component props
@@ -113,15 +114,12 @@ export interface LineChartProps<TDatum extends Datum = Datum> extends BaseChartP
      */
     areaOpacity?: number;
     /**
-     * Horizontal gradient for the line stroke. Color stops define a left-to-right gradient.
-     * `{ colorStops: [{ offset: 0, color: "blue" }, { offset: 1, color: "red" }] }`
+     * Horizontal line-stroke gradient. Offset 0 is the left edge and offset 1
+     * is the right edge.
+     * @example
+     * `{ stops: [{ offset: 0, color: "blue" }, { offset: 1, color: "red" }] }`
      */
-    lineGradient?: {
-        colorStops: Array<{
-            offset: number;
-            color: string;
-        }>;
-    };
+    lineGradient?: ColorGradientInput;
     /**
      * Line stroke width
      * @default 2