semiotic 3.8.5 → 3.8.6

package/dist/components/ai/chartCapabilities.d.ts

@@ -1,6 +1,7 @@
 import type { ChartCapability } from "./chartCapabilityTypes";
 import { LineChartCapability } from "../charts/xy/LineChart.capability";
 import { AreaChartCapability } from "../charts/xy/AreaChart.capability";
+import { BumpChartCapability } from "../charts/xy/BumpChart.capability";
 import { StackedAreaChartCapability } from "../charts/xy/StackedAreaChart.capability";
 import { ScatterplotCapability } from "../charts/xy/Scatterplot.capability";
 import { ConnectedScatterplotCapability } from "../charts/xy/ConnectedScatterplot.capability";
@@ -60,4 +61,4 @@ export declare function unregisterChartCapability(component: string): void;
 export declare function getCapabilities(): ReadonlyArray<ChartCapability>;
 /** Look up a capability by component name. */
 export declare function getCapability(component: string): ChartCapability | undefined;
-export { LineChartCapability, AreaChartCapability, StackedAreaChartCapability, ScatterplotCapability, ConnectedScatterplotCapability, BubbleChartCapability, QuadrantChartCapability, MultiAxisLineChartCapability, MinimapChartCapability, DifferenceChartCapability, CandlestickChartCapability, HeatmapCapability, BarChartCapability, GroupedBarChartCapability, StackedBarChartCapability, DotPlotCapability, PieChartCapability, DonutChartCapability, FunnelChartCapability, GaugeChartCapability, LikertChartCapability, SwimlaneChartCapability, HistogramCapability, BoxPlotCapability, SwarmPlotCapability, ViolinPlotCapability, RidgelinePlotCapability, ForceDirectedGraphCapability, SankeyDiagramCapability, ChordDiagramCapability, ProcessSankeyCapability, TreeDiagramCapability, TreemapCapability, CirclePackCapability, OrbitDiagramCapability, ChoroplethMapCapability, ProportionalSymbolMapCapability, FlowMapCapability, DistanceCartogramCapability, GaltonBoardChartCapability, EventDropChartCapability, PhysicsPileChartCapability, CollisionSwarmChartCapability, PhysicalFlowChartCapability, ProcessFlowChartCapability, GauntletChartCapability, CrucibleChartCapability };
+export { LineChartCapability, AreaChartCapability, BumpChartCapability, StackedAreaChartCapability, ScatterplotCapability, ConnectedScatterplotCapability, BubbleChartCapability, QuadrantChartCapability, MultiAxisLineChartCapability, MinimapChartCapability, DifferenceChartCapability, CandlestickChartCapability, HeatmapCapability, BarChartCapability, GroupedBarChartCapability, StackedBarChartCapability, DotPlotCapability, PieChartCapability, DonutChartCapability, FunnelChartCapability, GaugeChartCapability, LikertChartCapability, SwimlaneChartCapability, HistogramCapability, BoxPlotCapability, SwarmPlotCapability, ViolinPlotCapability, RidgelinePlotCapability, ForceDirectedGraphCapability, SankeyDiagramCapability, ChordDiagramCapability, ProcessSankeyCapability, TreeDiagramCapability, TreemapCapability, CirclePackCapability, OrbitDiagramCapability, ChoroplethMapCapability, ProportionalSymbolMapCapability, FlowMapCapability, DistanceCartogramCapability, GaltonBoardChartCapability, EventDropChartCapability, PhysicsPileChartCapability, CollisionSwarmChartCapability, PhysicalFlowChartCapability, ProcessFlowChartCapability, GauntletChartCapability, CrucibleChartCapability };

package/dist/components/charts/custom/XYCustomChart.d.ts

@@ -7,6 +7,7 @@ import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types"
 import type { TooltipProp } from "../../Tooltip/Tooltip";
 import type { ChartRecipe } from "../../ai/chartRecipes";
 import type { LegendValue } from "../../types/legendTypes";
+import type { LegendInteractionMode, LegendPosition } from "../shared/useChartLegend";
 export interface XYCustomChartProps<TDatum extends Datum = Datum, TConfig extends object = Record<string, unknown>> extends BaseChartProps, AxisConfig {
     /** Data passed through to LayoutContext.data. */
     data?: TDatum[];
@@ -34,6 +35,8 @@ export interface XYCustomChartProps<TDatum extends Datum = Datum, TConfig extend
     showLegend?: boolean;
     /** Additional legend content. Categorical groups follow the inferred colorBy legend. */
     legend?: LegendValue;
+    legendInteraction?: LegendInteractionMode;
+    legendPosition?: LegendPosition;
     annotations?: Datum[];
     /** Field or function that declares the semantic category used for custom-layout color. */
     colorBy?: ChartAccessor<TDatum, string>;

package/dist/components/charts/geo/DistanceCartogram.d.ts

@@ -25,7 +25,7 @@ export interface DistanceCartogramProps<TDatum extends Datum = Datum> extends Ba
     center: string;
     /** Cost/distance accessor — numeric field or function */
     costAccessor: string | ((d: Datum) => number);
-    /** Interpolation between geographic (0) and cartogram (1) @default 1 */
+    /** Interpolation between geographic (0) and cartogram (1), clamped to [0, 1]. @default 1 */
     strength?: number;
     /** Line rendering mode @default "straight" */
     lineMode?: "straight" | "fractional";

package/dist/components/charts/index.d.ts

@@ -12,8 +12,11 @@ export { ConnectedScatterplot } from "./xy/ConnectedScatterplot";
 export type { ConnectedScatterplotProps } from "./xy/ConnectedScatterplot";
 export { LineChart } from "./xy/LineChart";
 export type { LineChartProps } from "./xy/LineChart";
+export { BumpChart, rankBumpData } from "./xy/BumpChart";
+export type { BumpChartProps, RankedBumpData, RankedBumpDatum, RankBumpDataOptions, } from "./xy/BumpChart";
 export { AreaChart } from "./xy/AreaChart";
 export type { AreaChartProps, SemanticGradientStop } from "./xy/AreaChart";
+export type { GradientConfig, GradientStop, SemanticGradientInput, } from "./shared/gradient";
 export { DifferenceChart } from "./xy/DifferenceChart";
 export type { DifferenceChartProps } from "./xy/DifferenceChart";
 export { StackedAreaChart } from "./xy/StackedAreaChart";

package/dist/components/charts/ordinal/BarChart.d.ts

@@ -7,6 +7,7 @@ import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import { type StyleRule } from "../shared/styleRules";
 import { type RegressionProp } from "../shared/regressionUtils";
+import { type GradientInput } from "../shared/gradient";
 /**
  * BarChart component props
  */
@@ -64,24 +65,16 @@ export interface BarChartProps<TDatum extends Datum = Datum> extends BaseChartPr
     /** Rounded top corner radius in pixels. Only the end away from the baseline is rounded. */
     roundedTop?: number;
     /**
-     * Gradient fill from the bar's tip (opposite the baseline) toward its base.
-     * - `true` — default opacity fade (80% → 5% of the resolved fill color).
-     * - `{ topOpacity, bottomOpacity }` — explicit opacity stops on the resolved fill.
-     * - `{ colorStops: [{offset, color}, ...] }` — arbitrary multi-color gradient.
-     *
+     * Gradient fill from the bar's tip (offset 0) toward its base (offset 1).
+     * Stops can set `color`, `opacity`, or both. Omit a stop color to inherit
+     * the resolved bar color.
+     * @example
+     * `{ stops: [{ offset: 0, opacity: 0.8 }, { offset: 1, opacity: 0.05 }] }`
      * Direction follows the bar's orientation (vertical/horizontal) and sign
      * (positive/negative bars). Same API as `AreaChart.gradientFill`.
      * @default false
      */
-    gradientFill?: boolean | {
-        topOpacity: number;
-        bottomOpacity: number;
-    } | {
-        colorStops: Array<{
-            offset: number;
-            color: string;
-        }>;
-    };
+    gradientFill?: GradientInput;
     /**
      * Declarative, threshold-aware bar styling. An ordered list of
      * `{ when, style }` rules; every rule whose condition matches a bar

package/dist/components/charts/ordinal/GaugeChart.d.ts

@@ -25,6 +25,9 @@ export interface GaugeChartProps extends BaseChartProps {
     /**
      * Arc-length gradient for the gauge band.
      *
+     * Offset 0 is the sweep start and offset 1 is the sweep end. Stops can set
+     * `color`, `opacity`, or both.
+     *
      * The gradient is sampled along the visible filled arc from sweep start
      * toward the current value. If `fillZones` is false, the entire arc uses
      * the gradient. If `fillZones` is true, the unfilled remainder stays on

package/dist/components/charts/ordinal/GroupedBarChart.d.ts

@@ -6,6 +6,7 @@ import type { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import { type StyleRule } from "../shared/styleRules";
 import type { RealtimeFrameHandle } from "../../realtime/types";
+import { type GradientInput } from "../shared/gradient";
 export interface GroupedBarChartProps<TDatum extends Datum = Datum> extends BaseChartProps {
     data?: TDatum[];
     categoryAccessor?: ChartAccessor<TDatum, string>;
@@ -22,6 +23,8 @@ export interface GroupedBarChartProps<TDatum extends Datum = Datum> extends Base
     barPadding?: number;
     /** Rounded corner radius on bar ends (away from baseline). */
     roundedTop?: number;
+    /** Tip-to-base bar gradient using `{ stops: [{ offset, color?, opacity? }] }`. */
+    gradientFill?: GradientInput;
     /**
      * Declarative, threshold-aware bar styling. Ordered `{ when, style }`
      * rules; the last applicable rule wins per property. `when` accepts a

package/dist/components/charts/ordinal/StackedBarChart.d.ts

@@ -6,6 +6,7 @@ import type { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { RealtimeFrameHandle } from "../../realtime/types";
 import { type StyleRule } from "../shared/styleRules";
+import { type GradientInput } from "../shared/gradient";
 export interface StackedBarChartProps<TDatum extends Datum = Datum> extends BaseChartProps {
     data?: TDatum[];
     categoryAccessor?: ChartAccessor<TDatum, string>;
@@ -23,6 +24,8 @@ export interface StackedBarChartProps<TDatum extends Datum = Datum> extends Base
     barPadding?: number;
     /** Rounded top corner radius. Only the topmost stacked segment gets rounded. */
     roundedTop?: number;
+    /** Tip-to-base segment gradient using `{ stops: [{ offset, color?, opacity? }] }`. */
+    gradientFill?: GradientInput;
     /**
      * Declarative, threshold-aware segment styling. Ordered `{ when, style }`
      * rules; the last applicable rule wins per property. `when` accepts a

package/dist/components/charts/ordinal/SwimlaneChart.d.ts

@@ -5,6 +5,7 @@ import type { LegendInteractionMode } from "../shared/hooks";
 import type { BaseChartProps, ChartAccessor, CategoryFormatFn } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
 import type { RealtimeFrameHandle } from "../../realtime/types";
+import { type GradientInput } from "../shared/gradient";
 export interface SwimlaneChartProps<TDatum extends Datum = Datum> extends BaseChartProps {
     /** Data array. Omit for push API mode. */
     data?: TDatum[];
@@ -61,20 +62,9 @@ export interface SwimlaneChartProps<TDatum extends Datum = Datum> extends BaseCh
     rTickValues?: number[];
     /** Align first value tick label to start, last to end. Prevents clipping at chart edges. */
     tickLabelEdgeAlign?: boolean;
-    /** Gradient fill for swimlane segments. `true` uses tip→base opacity ramp;
-     *  pass `{ topOpacity, bottomOpacity }` for a uniform alpha gradient or
-     *  `{ colorStops }` for a multi-stop color ramp. Same shape as
-     *  BarChart.gradientFill / AreaChart.gradientFill. The gradient runs along
-     *  the lane's growth direction (left→right horizontal, bottom→top vertical). */
-    gradientFill?: boolean | {
-        topOpacity: number;
-        bottomOpacity: number;
-    } | {
-        colorStops: Array<{
-            offset: number;
-            color: string;
-        }>;
-    };
+    /** Gradient fill along the lane's growth direction. Offset 0 is the tip
+     *  and offset 1 is the base. Stops can set `color`, `opacity`, or both. */
+    gradientFill?: GradientInput;
     /** Lane "track" fill — a rect drawn behind each lane spanning the full
      *  value-axis range, sized to the lane's bandwidth. Lets budget/progress
      *  lanes read as filled vs. empty. Pass a color string (CSS vars

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

@@ -1,12 +1,10 @@
 /**
- * Single source of truth for per-chart prop specifications.
- *
- * Three downstream consumers used to maintain their own per-chart entries:
+ * Single source of truth for per-chart prop specifications consumed by:
  *   - `ai/schema.json`                                    (LLM tool definitions)
  *   - `src/components/charts/shared/validationMap.ts`     (runtime prop validation)
  *   - `ai/componentMetadata.cjs`                          (category buckets)
  *
- * Today, `validationMap.generated.ts` and `ai/schema.json` are generated from
+ * `validationMap.generated.ts` and `ai/schema.json` are generated from
  * this registry — run `npm run docs:chart-specs:schema` to refresh both after
  * editing a spec. `componentMetadata.cjs` is still
  * hand-edited but gated for parity by the registry: `check:chart-specs` (run

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

@@ -1,16 +1,12 @@
 import type { Datum } from "./datumTypes";
+import type { ColorGradientInput, GradientConfig, GradientStop } from "./gradient";
 export interface GaugeThresholdLike {
     value: number;
     color: string;
     label?: string;
 }
-export interface GaugeGradientStop {
-    offset: number;
-    color: string;
-}
-export interface GaugeGradientFill {
-    colorStops: GaugeGradientStop[];
-}
+export type GaugeGradientStop = GradientStop;
+export type GaugeGradientFill = ColorGradientInput;
 export interface GaugeArcDatum extends Datum {
     category: string;
     value: number;
@@ -48,7 +44,7 @@ interface BuildGaugeArcModelOptions {
     backgroundColor: string;
     fillZones: boolean;
     showScaleLabels: boolean;
-    gradientFill?: GaugeGradientFill;
+    gradientFill?: GradientConfig;
     gradientSteps?: number;
 }
 /**

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", "CrucibleChart", "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;