semiotic 3.8.5 → 3.8.7

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

@@ -1,4 +1,5 @@
 import type { Datum } from "./datumTypes";
+import type { AxisChromeInput } from "../../legendLayout";
 import { useChartLegendAndMargin, useLegendInteraction, DEFAULT_COLOR } from "./hooks";
 import type { LegendInteractionMode, LegendPosition } from "./hooks";
 import type { Accessor, SelectionConfig, LinkedHoverProp, HoverHighlightMode, MobileInteractionProp, ResolvedMobileInteractionConfig } from "./types";
@@ -8,6 +9,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 +48,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 +80,14 @@ export interface ChartSetupInput {
     width: number;
     /** Resolved height from useChartMode */
     height: number;
+    /** Whether the resolved chart mode includes a title. */
+    hasTitle?: boolean;
+    /**
+     * Bottom-axis chrome, so a bottom legend reserves space outside the tick
+     * labels rather than only being drawn past them. Omit for charts with no
+     * horizontal axis (pie/donut/radial) — the gutter resolves to 0.
+     */
+    axisChrome?: AxisChromeInput;
 }
 /**
  * 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

package/dist/components/data/portability/capabilityBinding.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Bind a library-neutral IDID capability descriptor to a Semiotic runtime
+ * capability. A portable `intentScores` field is authoritative when present;
+ * omission retains the host's ranking policy.
+ *
+ * The portable descriptor intentionally cannot contain executable `fits` or
+ * `buildProps` functions. Treating it as a complete runtime capability would
+ * therefore make every dataset appear to fit, which is precisely the kind of
+ * plausible-but-unsafe recommendation the portability layer refuses to make.
+ *
+ * This binder overlays the descriptor's portable policy (rubric, intent
+ * scores, variants, caveats, and mobile contract) onto a host-resolved
+ * capability while retaining the host's executable data-fit, prop-building,
+ * scale, quality, and numeric-contract logic.
+ */
+import type { ChartCapability } from "../../ai/chartCapabilityTypes";
+import { type PortableChartCapability } from "./spec";
+import type { PortabilityDiagnostic, PortabilityLoss, PortabilityProvenance, PortabilityStatus } from "./result";
+/** Runtime capability plus the exact portable descriptor that shaped it. */
+export interface BoundPortableChartCapability extends ChartCapability {
+    readonly portableDescriptor: PortableChartCapability;
+}
+/** Structured activation result; refused results never contain a capability. */
+export interface PortableCapabilityBindingResult {
+    status: PortabilityStatus;
+    capability?: BoundPortableChartCapability;
+    diagnostics: readonly PortabilityDiagnostic[];
+    lossReport: readonly PortabilityLoss[];
+    provenance: PortabilityProvenance;
+}
+/**
+ * Activate a portable descriptor against an explicitly resolved host
+ * capability.
+ *
+ * The component ids must match. The portable rubric/intent scores are
+ * authoritative for ranking; portable variants replace host variants when the
+ * field is present (an omitted variants field means no carried variants).
+ * Host `fits`, `buildProps`, numeric contracts, scale/quality gates, and
+ * dynamic caveats remain in force.
+ */
+export declare function bindPortableCapability(descriptor: unknown, host: ChartCapability | undefined): PortableCapabilityBindingResult;

package/dist/components/data/portability/index.d.ts

@@ -10,6 +10,8 @@
  */
 export { IDID_SPEC_VERSION, BUILTIN_INTENT_IDS, validatePortableCapability, validatePortableAudienceProfile, validatePortableAnnotation, } from "./spec";
 export type { BuiltInIntentId, PortableIntentId, PortableChartRubric, PortableChartVariant, PortableMobileInteractionCapability, PortableMobileLabelCapability, PortableMobileCustomCapability, PortableMobileCapability, PortableChartCapability, PortableReceptionModality, PortableAudienceTarget, PortableAudienceProfile, PortableAnnotationActorKind, PortableAnnotationSource, PortableAnnotationBasis, PortableAnnotationProvenance, PortableAnnotationFreshness, PortableAnnotationStatus, PortableAnnotationAnchor, PortableAnnotationLifecycle, PortableAnnotated, ValidationResult, } from "./spec";
+export { bindPortableCapability } from "./capabilityBinding";
+export type { BoundPortableChartCapability, PortableCapabilityBindingResult, } from "./capabilityBinding";
 export { toVegaLite, toVegaLiteResult, attachIDID, readIDID, attachIDIDAnnotations, readIDIDAnnotations, } from "./vegaLite";
 export type { IDIDVegaLiteMeta, ToVegaLiteOptions, VegaLiteExportResult, } from "./vegaLite";
 export { fromVegaLiteResult, unwrapIDIDEnrichedVegaLiteSpec, } from "../fromVegaLite";

package/dist/components/geometry/bumpRibbonGeometry.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Screen-space geometry for magnitude-encoded bump-chart ribbons.
+ *
+ * A conventional area chart offsets both boundaries vertically. That makes a
+ * band look artificially thin when its centerline moves sharply between
+ * ranks. This helper follows the idea behind d3.svg.ribbon instead: sample the
+ * centerline, calculate its local normal, then offset by the requested radius.
+ * The visible thickness therefore stays perpendicular to the trajectory.
+ */
+export interface BumpRibbonPoint {
+    x: number;
+    y: number;
+    /** Half of the desired visible ribbon thickness, in pixels. */
+    radius: number;
+}
+export interface BumpRibbonGeometry {
+    topPath: [number, number][];
+    bottomPath: [number, number][];
+    /** Index of the nearest input datum for every sampled path vertex. */
+    datumIndices: number[];
+}
+export interface BumpRibbonGeometryOptions {
+    /** Smooth horizontal-tangent Béziers or straight segments. */
+    curve?: "smooth" | "linear";
+    /** Samples emitted for each interval. Stable counts enable path animation. */
+    samplesPerSegment?: number;
+}
+/**
+ * Build paired boundary paths around a bump-chart centerline.
+ *
+ * The first sample of every interval after the first is omitted because it is
+ * identical to the previous interval's final sample. Every trajectory with
+ * the same number of ranking columns therefore emits the same number of
+ * vertices, which lets StreamXYFrame interpolate paths during data updates.
+ */
+export declare function buildBumpRibbonGeometry(points: BumpRibbonPoint[], options?: BumpRibbonGeometryOptions): BumpRibbonGeometry;

package/dist/components/legendLayout.d.ts

@@ -1,8 +1,82 @@
-import type { LegendLayout } from "./types/legendTypes";
+import type { LegendLayout, LegendValue } from "./types/legendTypes";
 export declare const DEFAULT_LEGEND_SWATCH_SIZE = 16;
 export declare const DEFAULT_LEGEND_LABEL_GAP = 6;
 export declare const DEFAULT_LEGEND_ITEM_GAP = 10;
 export declare const DEFAULT_LEGEND_ROW_HEIGHT = 22;
+export declare const DEFAULT_SIDE_LEGEND_WIDTH = 100;
+export declare const DEFAULT_LEGEND_DISTANCE = 10;
+/**
+ * SVG text has no useful intrinsic width until after it is mounted. Keep the
+ * estimate shared by margin calculation and rendering so side legends never
+ * reserve one width and draw into another.
+ */
+export declare function estimateLegendTextWidth(label: string): number;
+/** Resolve the layout box needed by a left/right legend. */
+export declare function resolveSideLegendWidth(legend: LegendValue | null | undefined, layout?: LegendLayout): number;
+/** Resolve the requested gap between the legend edge and plot edge. */
+export declare function resolveLegendDistance(legend: LegendValue | null | undefined): number;
+/** Resolve plot-adjacent chrome reserved before a left/right legend. */
+export declare function resolveLegendSideGutter(layout?: LegendLayout): number;
+/**
+ * Height of the chrome a horizontal axis draws *outside* the plot rect, which
+ * a top/bottom legend has to clear.
+ *
+ * The axis renderers place tick labels on a baseline 18px past the axis line
+ * and an axis title at 40px (58px when ticks are rotated); each needs a few
+ * more pixels for descenders. A bottom legend anchored at `plotBottom +
+ * legendDistance` lands in exactly that band, so without this reservation the
+ * legend and the tick labels draw at the same y.
+ */
+export declare const AXIS_TICK_CHROME = 22;
+export declare const AXIS_TITLE_CHROME = 46;
+export declare const ROTATED_AXIS_TITLE_CHROME = 64;
+export interface AxisChromeInput {
+    /** A horizontal axis renders on this side of the plot. */
+    hasAxis?: boolean;
+    /** An axis title (`xLabel` / `valueLabel` / `categoryLabel`) is present. */
+    hasAxisLabel?: boolean;
+    /** Tick labels are rotated, which pushes the axis title further out. */
+    rotatedTicks?: boolean;
+}
+/**
+ * Space to reserve between the plot edge and a top/bottom legend.
+ *
+ * `legendLayout.axisGutter` is the explicit override (including `0` to opt out
+ * and restore pre-3.8.7 placement); otherwise the band is derived from the
+ * axis chrome actually being drawn, and is 0 when there is no axis on that
+ * side — so pie/donut and axes-off charts are unaffected.
+ */
+export declare function resolveAxisChromeGutter(input?: AxisChromeInput, layout?: LegendLayout): number;
+/**
+ * Resolve `axisChrome` for an XY chart HOC's `useChartLegendAndMargin` call.
+ * Mirrors `server/staticXY.tsx`'s `renderStreamXYFrame` (`hasAxis:
+ * showAxes !== false`, `hasAxisLabel: !!xLabel`) so a bottom-legend chart
+ * reserves the same margin on the client as `renderChart` does on the
+ * server — leaving either side to guess (the pre-3.8.8 default) makes the
+ * client over- or under-reserve relative to the SSR output whenever a
+ * wrapped legend pushes the reservation past the 80px floor.
+ */
+export declare function resolveXYAxisChrome(input: {
+    showAxes?: boolean;
+    xLabel?: unknown;
+}): AxisChromeInput;
+/**
+ * Resolve `axisChrome` for an ordinal chart HOC's `useChartLegendAndMargin`
+ * call. Mirrors `server/staticOrdinal.tsx`'s `renderOrdinalFrame`: the
+ * bottom axis is the value axis for `"horizontal"` projection, the category
+ * axis otherwise, and radial projections draw no axis at all. See
+ * `resolveXYAxisChrome` for why this must track the server computation.
+ */
+export declare function resolveOrdinalAxisChrome(input: {
+    showAxes?: boolean;
+    projection?: "horizontal" | "vertical" | "radial";
+    hasCategoryLabel: boolean;
+    hasValueLabel: boolean;
+}): AxisChromeInput;
+/** Estimate the layout-box height used to place a top/bottom legend. */
+export declare function resolveHorizontalLegendHeight(legend: LegendValue | null | undefined, availableWidth: number, layout?: LegendLayout): number;
+/** Margin required to fit a side legend and its plot-edge gap. */
+export declare function resolveSideLegendMargin(legend: LegendValue | null | undefined, layout?: LegendLayout): number;
 export interface LegendMetrics {
     swatchSize: number;
     labelGap: number;