semiotic 3.5.0 → 3.5.2

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

@@ -27,6 +27,11 @@ export interface GaugeChartProps extends BaseChartProps {
     backgroundColor?: string;
     /** Arc thickness as fraction of radius (0–1, default 0.3) */
     arcWidth?: number;
+    /** Pixel radius for the rounded ends of each arc segment, same prop
+     *  semantics as `DonutChart.cornerRadius`. Default `undefined`
+     *  (sharp corners). Useful for the "pill" aesthetic where each
+     *  threshold zone reads as a discrete capsule. */
+    cornerRadius?: number;
     /** Show needle indicator (default true) */
     showNeedle?: boolean;
     /** Needle color (default: var(--semiotic-text, #333)) */
@@ -94,6 +99,21 @@ export interface GaugeChartProps extends BaseChartProps {
  *   fillZones
  * />
  * ```
+ *
+ * @example
+ * ```tsx
+ * // Rounded segment ends — same `cornerRadius` semantics as DonutChart.
+ * // Each threshold zone reads as a capsule with the others.
+ * <GaugeChart
+ *   value={65}
+ *   thresholds={[
+ *     { value: 60, color: "#22c55e" },
+ *     { value: 80, color: "#f59e0b" },
+ *     { value: 100, color: "#ef4444" },
+ *   ]}
+ *   cornerRadius={6}
+ * />
+ * ```
  */
 export declare const GaugeChart: {
     (props: GaugeChartProps & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;

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

@@ -32,6 +32,8 @@ export interface GroupedBarChartProps<TDatum extends Datum = Datum> extends Base
     annotations?: Datum[];
     /** Custom formatter for category tick labels */
     categoryFormat?: CategoryFormatFn;
+    /** Fixed value-axis domain `[min, max]`. Either bound may be `undefined` to leave that side data-derived. */
+    valueExtent?: [number | undefined, number | undefined] | [number];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 /**

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

@@ -72,6 +72,8 @@ export interface HistogramProps<TDatum extends Datum = Datum> extends BaseChartP
     };
     /** Custom formatter for category tick labels */
     categoryFormat?: CategoryFormatFn;
+    /** Fixed value-axis domain `[min, max]`. Either bound may be `undefined` to leave that side data-derived. Wins over Histogram's auto-computed shared bin extent — useful for pinning the axis to a known range so streamed updates don't shift the bins as min/max drift. */
+    valueExtent?: [number | undefined, number | undefined] | [number];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 /**

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

@@ -87,6 +87,8 @@ export interface LikertChartProps<TDatum extends Datum = Datum> extends BaseChar
     annotations?: Datum[];
     /** Custom formatter for category tick labels */
     categoryFormat?: CategoryFormatFn;
+    /** Fixed value-axis domain `[min, max]`. Either bound may be `undefined` to leave that side data-derived. Likert is normally pinned to symmetric proportions; pass `valueExtent` to override. */
+    valueExtent?: [number | undefined, number | undefined] | [number];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 export interface LikertChartHandle extends RealtimeFrameHandle {

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

@@ -29,6 +29,8 @@ export interface RidgelinePlotProps<TDatum extends Datum = Datum> extends BaseCh
     annotations?: Datum[];
     /** Custom formatter for category tick labels */
     categoryFormat?: CategoryFormatFn;
+    /** Fixed value-axis domain `[min, max]`. Either bound may be `undefined` to leave that side data-derived. */
+    valueExtent?: [number | undefined, number | undefined] | [number];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 /**

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

@@ -33,6 +33,8 @@ export interface StackedBarChartProps<TDatum extends Datum = Datum> extends Base
     annotations?: Datum[];
     /** Custom formatter for category tick labels */
     categoryFormat?: CategoryFormatFn;
+    /** Fixed value-axis domain `[min, max]`. Either bound may be `undefined` to leave that side data-derived. Stacked bars auto-extend the value domain to cover the cumulative stack unless `valueExtent` is fully specified. */
+    valueExtent?: [number | undefined, number | undefined] | [number];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 /**

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

@@ -41,6 +41,8 @@ export interface SwarmPlotProps<TDatum extends Datum = Datum> extends BaseChartP
     };
     /** Custom formatter for category tick labels */
     categoryFormat?: CategoryFormatFn;
+    /** Fixed value-axis domain `[min, max]`. Either bound may be `undefined` to leave that side data-derived. */
+    valueExtent?: [number | undefined, number | undefined] | [number];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 /**

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

@@ -83,6 +83,13 @@ export interface SwimlaneChartProps<TDatum extends Datum = Datum> extends BaseCh
         color: string;
         opacity?: number;
     };
+    /** Rounded corner radius (in pixels) for the outermost ends of each
+     *  lane. Both ends round: left+right in horizontal orientation, top+bottom
+     *  in vertical. Middle segments of multi-segment lanes stay square so
+     *  pieces visually butt against each other. */
+    roundedTop?: number;
+    /** Fixed value-axis domain `[min, max]`. Either bound may be `undefined` to leave that side data-derived. */
+    valueExtent?: [number | undefined, number | undefined] | [number];
     /** Pass-through props to StreamOrdinalFrame */
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }

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

@@ -40,6 +40,8 @@ export interface ViolinPlotProps<TDatum extends Datum = Datum> extends BaseChart
     };
     /** Custom formatter for category tick labels */
     categoryFormat?: CategoryFormatFn;
+    /** Fixed value-axis domain `[min, max]`. Either bound may be `undefined` to leave that side data-derived. */
+    valueExtent?: [number | undefined, number | undefined] | [number];
     frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
 }
 /**

package/dist/components/charts/realtime/RealtimeHistogram.d.ts

@@ -6,7 +6,7 @@ import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
 import type { ChartMode, ChartAccessor, SelectionConfig } from "../shared/types";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 import type { Datum } from "../shared/datumTypes";
-export interface RealtimeTemporalHistogramProps<TDatum extends Datum = Datum> {
+export interface RealtimeHistogramProps<TDatum extends Datum = Datum> {
     /** Display mode: "primary" (full chrome), "context" (compact), "sparkline" (inline) */
     mode?: ChartMode;
     /** Time interval for binning */
@@ -137,7 +137,7 @@ export interface RealtimeTemporalHistogramProps<TDatum extends Datum = Datum> {
     pointIdAccessor?: string | ((d: Datum) => string);
 }
 /**
- * RealtimeTemporalHistogram - Streaming temporal histogram.
+ * RealtimeHistogram - Streaming temporal histogram.
  *
  * Wraps StreamXYFrame with `chartType="bar"` and `runtimeMode="streaming"`,
  * binning pushed data points into time-windowed bars. Supports both simple
@@ -149,7 +149,7 @@ export interface RealtimeTemporalHistogramProps<TDatum extends Datum = Datum> {
  * @example
  * ```tsx
  * // Simple temporal histogram — push each event, the chart bins by time
- * <RealtimeTemporalHistogram
+ * <RealtimeHistogram
  *   ref={ref}
  *   binSize={20}
  *   fill="#007bff"
@@ -160,7 +160,7 @@ export interface RealtimeTemporalHistogramProps<TDatum extends Datum = Datum> {
  * @example
  * ```tsx
  * // Stacked by category — same push API, color by status field
- * <RealtimeTemporalHistogram
+ * <RealtimeHistogram
  *   ref={ref}
  *   binSize={25}
  *   categoryAccessor="category"
@@ -169,14 +169,17 @@ export interface RealtimeTemporalHistogramProps<TDatum extends Datum = Datum> {
  * />
  * ```
  */
-export declare const RealtimeTemporalHistogram: {
-    <TDatum extends Datum = Datum>(props: RealtimeTemporalHistogramProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+export declare const RealtimeHistogram: {
+    <TDatum extends Datum = Datum>(props: RealtimeHistogramProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
     displayName?: string;
 };
-/** @deprecated Use RealtimeTemporalHistogram instead */
-export declare const RealtimeHistogram: {
-    <TDatum extends Datum = Datum>(props: RealtimeTemporalHistogramProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+/** @deprecated Use `RealtimeHistogram` (the canonical public name) instead. The
+ *  `RealtimeTemporalHistogram` alias is preserved for back-compat with code
+ *  written before the rename and will be removed in a future major version. */
+export declare const RealtimeTemporalHistogram: {
+    <TDatum extends Datum = Datum>(props: RealtimeHistogramProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
     displayName?: string;
 };
-/** @deprecated Use RealtimeTemporalHistogramProps instead */
-export type RealtimeHistogramProps = RealtimeTemporalHistogramProps;
+/** @deprecated Use `RealtimeHistogramProps` instead. Same component, just the
+ *  pre-rename type alias. */
+export type RealtimeTemporalHistogramProps<TDatum extends Datum = Datum> = RealtimeHistogramProps<TDatum>;

package/dist/components/charts/realtime/defaultRealtimeTooltip.d.ts

@@ -40,4 +40,47 @@ export declare function buildDefaultRealtimeTooltip<TDatum extends Datum = Datum
  * scene builder).
  */
 export declare function buildWaterfallTooltip<TDatum extends Datum = Datum>(options?: DefaultRealtimeTooltipOptions<TDatum>): (d: HoverData) => ReactNode;
+/**
+ * Histogram-specific default tooltip.
+ *
+ * The barScene's histogram path enriches each rect's datum with
+ * `{ binStart, binEnd, total, category?, categoryValue? }`. The generic
+ * `x: <time>, y: <value>` shape produces empty strings on those bins
+ * because neither `time` nor `value` exists on the aggregated payload.
+ * This builder surfaces the fields that actually carry meaning for a
+ * histogram bin:
+ *
+ *   range:    <binStart>–<binEnd>
+ *   count:    <total>
+ *   category: <category>        (only when categoryAccessor is set)
+ *
+ * Falls back to the canonical x/y shape if a bin's enriched fields are
+ * absent — guards against a non-streaming render path or a static frame
+ * that bypasses the bin scene.
+ */
+export declare function buildHistogramTooltip<TDatum extends Datum = Datum>(options?: DefaultRealtimeTooltipOptions<TDatum>): (d: HoverData) => ReactNode;
+/**
+ * Heatmap-specific default tooltip.
+ *
+ * The streaming heatmap aggregates raw points into 2D bins; each cell's
+ * datum is `{ xi, yi, value, count, sum, xCenter, yCenter, agg }`. The
+ * generic `x: <time>, y: <value>` shape is meaningless because the cell
+ * doesn't carry the user's original fields — it carries bin indices and
+ * aggregated counts.
+ *
+ * This tooltip surfaces the user-relevant info:
+ *   x:     <data-space x-center of the bin>
+ *   y:     <data-space y-center of the bin>
+ *   count: 12               (when datum.count is present — streaming path)
+ *   sum:   142              (when agg === "sum")
+ *   mean:  11.83            (when agg === "mean")
+ *
+ * For `agg === "sum"` we always surface the sum (it's the metric the
+ * heatmap is colored by, even when sum happens to equal count).
+ *
+ * Falls back to the canonical x/y shape if the enriched fields are
+ * absent (e.g. a non-streaming render path); the count/sum/mean rows
+ * only appear when the matching field is present on the datum.
+ */
+export declare function buildHeatmapTooltip<TDatum extends Datum = Datum>(options?: DefaultRealtimeTooltipOptions<TDatum>): (d: HoverData) => ReactNode;
 export {};

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

@@ -0,0 +1,59 @@
+/**
+ * Equidistant tick generation for the `axisExtent="exact"` axis mode.
+ *
+ * The default "nice" mode (d3 scale's `.ticks(count)` algorithm)
+ * returns aesthetically-rounded tick values WITHIN the data domain —
+ * the first tick may sit above the data min and the last tick may
+ * sit below the data max. That's the standard reading: round labels
+ * win, exact data bounds lose.
+ *
+ * "exact" mode reverses that tradeoff. The first tick sits exactly at
+ * `dataMin`, the last tick sits exactly at `dataMax`, and the
+ * intermediate ticks are equidistant within the domain. Labels are
+ * whatever the value formatter produces — often not round.
+ *
+ * Works on `scaleLinear` and `scaleTime` (operates on millisecond
+ * timestamps, returns Date objects so downstream formatters receive
+ * the same shape they get from `scale.ticks()`).
+ *
+ * `scaleLog` is supported but the ticks come out evenly spaced in
+ * VALUE space, not pixel space — `[1, 250.75, 500.5, 750.25, 1000]`
+ * instead of `[1, 10, 100, 1000]`. That's intentional for the
+ * "endpoints must read as the actual data bounds" use case the
+ * feature was added for, but it's not "equidistant on the rendered
+ * axis". Users that want log-space-equidistant ticks should pass
+ * explicit `tickValues` (e.g. `[1, 10, 100, 1000]`) — those bypass
+ * `axisExtent` entirely.
+ */
+export type AxisExtentMode = "nice" | "exact";
+/** A d3-style continuous scale (linear, time, log) — the bit we use.
+ *  The `domain()` return type stays as `number[]` / `Date[]` rather
+ *  than a strict 2-tuple because that's what d3-scale's own types
+ *  declare (the runtime contract is "first and last elements are the
+ *  bounds" — d3 never returns a single-element domain in practice). */
+type TickableScale<T = number | Date> = {
+    domain(): T[];
+    ticks(count?: number): T[];
+};
+/**
+ * Generate `count` ticks evenly spaced across the scale's domain,
+ * inclusive of both endpoints. For a domain of `[lo, hi]` and a
+ * count of `n`, returns `[lo, lo + step, ..., hi]` where
+ * `step = (hi - lo) / (n - 1)`.
+ *
+ * Edge cases:
+ * - `count < 2` returns just the two endpoints.
+ * - Empty/zero-width domain returns the endpoints unchanged.
+ * - Date-valued domain returns Date objects (preserving the shape
+ *   d3-scale-time's `.ticks()` returns).
+ */
+export declare function equidistantTicks<T extends number | Date>(scale: TickableScale<T>, count: number): T[];
+/**
+ * Return either equidistant ticks (when `mode === "exact"`) or the
+ * scale's own d3-generated ticks (default "nice" behavior).
+ *
+ * Centralized so XY and ordinal overlay code paths can both call
+ * one function instead of branching at every `.ticks()` site.
+ */
+export declare function ticksForMode<T extends number | Date>(scale: TickableScale<T>, count: number, mode: AxisExtentMode | undefined): T[];
+export {};

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

@@ -35,6 +35,73 @@
 export type PropType = "string" | "number" | "boolean" | "array" | "object" | "function";
 export type DataShape = "array" | "object" | "network" | "realtime" | "none";
 export type ChartCategory = "xy" | "ordinal" | "network" | "geo" | "realtime";
+/**
+ * Capability tags for runtime behavior. Driven by the
+ * `hoc-frame-architecture-audit` Phase 1: each chart declares which
+ * features it actually supports so docs, AI/MCP tools, and CI gates
+ * can read structured truth instead of inferring it from the source.
+ *
+ * All fields are required so a new chart entry can't omit them
+ * silently — the audit's anti-goal "Do not make registry metadata
+ * aspirational. It should describe real runtime behavior and be
+ * checked." applies here.
+ */
+export interface ChartCapabilities {
+    /**
+     * Render pipeline. `canvas` for Stream-Frame-driven charts that
+     * paint to canvas with SVG overlays for chrome (the common case).
+     * `svg` for charts that are pure SVG (none today, but reserved).
+     * `hybrid` for charts that use both — currently every Stream-Frame
+     * HOC qualifies as hybrid; reserve `canvas` for any future
+     * canvas-only fallback.
+     */
+    renderModes: Array<"canvas" | "svg" | "hybrid">;
+    /** Renders a legend swatch column when `colorBy` (or equivalent)
+     *  resolves to non-empty categories. */
+    supportsLegend: boolean;
+    /** Reads from a `selection` prop and dims/highlights matching
+     *  marks via `wrapStyleWithSelection` or equivalent. */
+    supportsSelection: boolean;
+    /** Produces a hover-driven selection (used by linked crosshair /
+     *  cross-filter patterns) via `linkedHover`. */
+    supportsLinkedHover: boolean;
+    /** Exposes a ref handle (`push`, `pushMany`, etc.) so consumers
+     *  can mutate the data list without re-rendering. Hierarchy
+     *  charts (Treemap/CirclePack/TreeDiagram/OrbitDiagram) and
+     *  pure-synthetic charts (GaugeChart) declare false. */
+    supportsPush: boolean;
+    /** Renders to a static SVG via `renderChart()` from `semiotic/server`
+     *  through a registered entry in `serverChartConfigs.ts`. SSR-only
+     *  charts (none yet) and HOC-SSR exclusions also declare false. */
+    supportsSSR: boolean;
+    /**
+     * How color is consumed by the chart's data marks.
+     * - `categorical`: discrete buckets, paired with a `colorBy` accessor.
+     * - `sequential`: continuous scale (heatmap intensity, choropleth value).
+     * - `threshold`: stepped scale with explicit breakpoints (gauge zones).
+     * - `continuous`: smooth interpolation along a 1-D path (gradient fill).
+     * - `none`: chart doesn't use color encoding (sparkline, pure layout).
+     */
+    colorModel: "categorical" | "sequential" | "threshold" | "continuous" | "none";
+    /**
+     * Where the geometry comes from.
+     * - `plugin`: a built-in plugin in the frame (sankey/force/chord/tree
+     *   for network; bar/pie/swarm/etc. for ordinal; line/area/etc. for XY).
+     * - `custom`: emitted via the frame's customLayout escape hatch
+     *   (ProcessSankey via `customNetworkLayout`, NetworkCustomChart,
+     *   XYCustomChart, OrdinalCustomChart).
+     * - `synthetic`: no layout — the chart constructs its scene from
+     *   the input value(s) directly (GaugeChart computes arc geometry).
+     */
+    layoutMode: "plugin" | "custom" | "synthetic";
+    /**
+     * Free-form tag list for opt-in features that don't fit the
+     * boolean shape — e.g. "particles", "forecast", "anomaly", "brush",
+     * "streamgraph", "minimap". Used by docs feature tables and
+     * potential capability-driven AI suggestions.
+     */
+    specialFeatures: string[];
+}
 export interface ChartPropSpec {
     /** Allowed runtime types. May be a single value or a union. */
     type: PropType | PropType[];
@@ -71,6 +138,14 @@ export interface ChartSpec {
     propBags: ReadonlyArray<keyof typeof PROP_BAGS>;
     /** Chart-specific prop spec, overlaid on top of the composed bags. */
     ownProps: Record<string, ChartPropSpec>;
+    /**
+     * Capability matrix — declarative facts about runtime behavior.
+     * Drives docs feature tables, capability-aware AI/MCP tools, and
+     * the `check:capabilities` drift gate (which verifies, e.g., that
+     * a chart claiming `supportsSSR: true` has a matching entry in
+     * `serverChartConfigs.ts`).
+     */
+    capabilities: ChartCapabilities;
 }
 export declare const PROP_BAGS: {
     readonly common: Record<string, ChartPropSpec>;

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

@@ -62,12 +62,18 @@ export declare function getColor(dataPoint: Datum, colorBy: string | ((d: Datum)
  */
 export declare function createColorScale(data: Array<Datum>, colorBy: string, scheme?: string | string[]): (v: string) => string;
 /**
- * Generates a size function based on sizeBy configuration
+ * Generates a size function based on sizeBy configuration.
+ *
+ * Output is clamped to `sizeRange`. A pushed point whose `sizeBy`
+ * value falls outside the currently-known domain (which can happen
+ * in push mode before the running min/max catches up) renders at
+ * the boundary radius rather than producing an arbitrarily large
+ * (or negative) pixel value.
  *
  * @param dataPoint - The data point
  * @param sizeBy - Field name or function to determine size
  * @param sizeRange - Min and max size range [min, max]
  * @param domain - Optional domain for scaling [minValue, maxValue]
- * @returns Size value
+ * @returns Size value, clamped to `sizeRange` when a domain is given
  */
 export declare function getSize(dataPoint: Datum, sizeBy: string | ((d: Datum) => number), sizeRange?: [number, number], domain?: [number, number]): number;

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

@@ -4,15 +4,13 @@ import type { Accessor } from "./types";
  * Flatten a hierarchical data structure into an array of all nodes
  * by recursively traversing children.
  */
-export declare function flattenHierarchy(data: Datum | null, childrenAccessor: string | ((d: Datum) => any[])): Array<Datum>;
+export declare function flattenHierarchy(data: Datum | null, childrenAccessor: string | ((d: Datum) => Datum[])): Array<Datum>;
 /**
  * Infer nodes from edges when a nodes array is not provided.
  * Extracts unique source/target IDs and returns `{ id }` objects.
  * Returns the provided nodes array if it's non-empty.
  */
-export declare function inferNodesFromEdges(nodes: any[] | undefined, edges: any[], sourceAccessor: string | ((d: Datum) => string), targetAccessor: string | ((d: Datum) => string)): Array<{
-    id: string;
-}>;
+export declare function inferNodesFromEdges(nodes: Datum[] | undefined, edges: Datum[], sourceAccessor: string | ((d: Datum) => string), targetAccessor: string | ((d: Datum) => string)): Datum[];
 /**
  * Convert a valueAccessor prop into a hierarchy sum function.
  * Used by TreeDiagram, Treemap, and CirclePack for d3-hierarchy's `.sum()`.
@@ -26,7 +24,7 @@ export declare function createEdgeStyleFn({ edgeColorBy, colorBy, colorScale, no
     edgeColorBy: "source" | "target" | "gradient" | ((d: Datum) => string);
     colorBy: Accessor<string> | undefined;
     colorScale: ((v: string) => string) | undefined;
-    nodeStyleFn: (d: any, index?: number) => Datum;
+    nodeStyleFn: (d: Datum, index?: number) => Datum;
     edgeOpacity: number;
     baseStyle?: Record<string, string | number>;
 }): (d: Datum) => Datum;

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

@@ -0,0 +1,99 @@
+/**
+ * radialGeometry — pure math helpers for radial chart authoring.
+ *
+ * The original consumer is `GaugeChart`, which needs to:
+ *   - Convert a sweep angle (degrees) into start-angle + radian
+ *     forms that align with the convention pieScene.ts uses
+ *     (0° = 12 o'clock, positive = clockwise, gap centered at the
+ *     6 o'clock position).
+ *   - Map a value in `[min, max]` to its angle along the arc.
+ *   - Compute the arc's visible bounding box in unit-circle coords
+ *     so a container can fit the arc and pick a maximum radius.
+ *
+ * Custom radial chart authors using `XYCustomChart` or building a
+ * bespoke radial layout can reach for the same primitives without
+ * reimplementing the trigonometry. Surface intentionally tight —
+ * each function is a few lines of math with a documented input
+ * convention.
+ */
+/** Result of `sweepToAngles`. All angles are in the
+ *  12-o'clock-zero, clockwise-positive convention used by pieScene
+ *  and the underlying gauge implementation. */
+export interface SweepAngles {
+    /** Full sweep angle in radians. */
+    sweepRad: number;
+    /** Gap angle (the unfilled portion) in degrees. */
+    gapDeg: number;
+    /** Starting angle of the arc, measured in degrees clockwise from
+     *  12 o'clock. The gap is centered at 6 o'clock (180°), so the
+     *  arc starts at `180° + gapDeg / 2`. */
+    startAngleDeg: number;
+    /** Same as `startAngleDeg`, in radians (12 o'clock = 0). */
+    startAngleRad: number;
+    /** Offset angle in radians measured from +X (3 o'clock, the
+     *  trigonometric convention). Useful for direct `Math.cos` /
+     *  `Math.sin` calls when projecting points onto the arc. */
+    offsetRad: number;
+}
+/**
+ * Convert a sweep angle (degrees) into the four angle forms a
+ * radial chart layout typically needs. Defaults to a 240° sweep
+ * (gauge-style: gap of 120° centered at the bottom).
+ *
+ * @example
+ * ```ts
+ * const { sweepRad, startAngleRad } = sweepToAngles(180) // half-circle
+ * ```
+ */
+export declare function sweepToAngles(sweepDegrees?: number): SweepAngles;
+/**
+ * Map a numeric value in `[min, max]` to its angle along the arc.
+ * Returned angles are in trig-convention radians (suitable for
+ * `Math.cos` / `Math.sin` to project to unit-circle x/y).
+ *
+ * Values outside `[min, max]` are clamped.
+ *
+ * @example
+ * ```ts
+ * const { offsetRad, sweepRad } = sweepToAngles(240)
+ * const θ = valueToAngle(75, 0, 100, sweepRad, offsetRad)
+ * // x = Math.cos(θ), y = Math.sin(θ)
+ * ```
+ */
+export declare function valueToAngle(value: number, min: number, max: number, sweepRad: number, offsetRad: number): number;
+/** Bounding box of the visible arc in unit-circle coordinates
+ *  (radius = 1 around the origin). Multiply by the chosen radius
+ *  to get pixel-space extents. */
+export interface ArcBoundingBox {
+    minX: number;
+    maxX: number;
+    minY: number;
+    maxY: number;
+    /** `maxX - minX`. Multiply by radius for pixel width. */
+    width: number;
+    /** `maxY - minY`. Multiply by radius for pixel height. */
+    height: number;
+    /** Center of the bbox in unit-circle coords. */
+    cx: number;
+    cy: number;
+}
+/**
+ * Compute the bounding box of an arc with the given sweep, in
+ * unit-circle coordinates. Useful for centering the arc within a
+ * container and picking a maximum radius that keeps the arc inside
+ * the available width/height.
+ *
+ * The bbox includes:
+ *   - The two arc endpoints.
+ *   - The arc's center point `(0, 0)`.
+ *   - Any of the cardinal points `(±1, 0)`, `(0, ±1)` that fall
+ *     within the swept range.
+ *
+ * @example
+ * ```ts
+ * const bbox = computeArcBoundingBox(240)
+ * // Maximize radius so the arc fits in a (W × H) container:
+ * const radius = Math.min((W - 2 * pad) / bbox.width, (H - 2 * pad) / bbox.height)
+ * ```
+ */
+export declare function computeArcBoundingBox(sweepDegrees?: number): ArcBoundingBox;

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

@@ -0,0 +1,59 @@
+/**
+ * regressionUtils — sugar for the `trend` annotation.
+ *
+ * The `trend` annotation type (see annotationRules.tsx) already
+ * computes and renders linear / polynomial / LOESS regression lines
+ * for any chart that exposes x/y scales. This module wraps that into
+ * a chart-prop ergonomic — `regression={true}`, `regression="loess"`,
+ * or a full config object — so users don't have to author an
+ * annotation object by hand for the most common cases.
+ *
+ * Mirrors the shape of LineChart's `forecast` and `anomaly` props,
+ * which are likewise sugar over annotation-side work.
+ */
+import type { Datum } from "./datumTypes";
+/** Regression methods supported by the trend annotation. */
+export type RegressionMethod = "linear" | "polynomial" | "loess";
+/**
+ * Full regression configuration. All visual props mirror the
+ * underlying `trend` annotation; users dropping into the `annotations`
+ * array directly can pass the same shape.
+ */
+export interface RegressionConfig {
+    /** Regression method. @default "linear" */
+    method?: RegressionMethod;
+    /** LOESS bandwidth (0–1). Lower = more local detail. @default 0.3 */
+    bandwidth?: number;
+    /** Polynomial order (only for `method: "polynomial"`). @default 2 */
+    order?: number;
+    /** Stroke color for the regression line. @default "#6366f1" */
+    color?: string;
+    /** Stroke width. @default 2 */
+    strokeWidth?: number;
+    /** Dash pattern. @default "6,3" */
+    strokeDasharray?: string;
+    /** Optional label rendered at the line's right end. */
+    label?: string;
+}
+/**
+ * Prop shape on chart HOCs. The boolean form gives users a
+ * "just draw a regression line" toggle; the string form picks the
+ * method with default styling; the object form opens up the full
+ * configuration. Mirrors `forecast` / `anomaly` on LineChart.
+ */
+export type RegressionProp = boolean | RegressionMethod | RegressionConfig;
+/**
+ * Convert a `regression` prop value into the trend-annotation object
+ * to splice into the chart's annotations array. Returns `undefined`
+ * when the prop is falsy so callers can skip the spread.
+ *
+ * @example
+ * ```ts
+ * const trendAnn = buildRegressionAnnotation(regression)
+ * const annotations = [
+ *   ...(trendAnn ? [trendAnn] : []),
+ *   ...(userAnnotations || []),
+ * ]
+ * ```
+ */
+export declare function buildRegressionAnnotation(regression: RegressionProp | undefined): Datum | undefined;

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

@@ -65,5 +65,12 @@ export declare const DEFAULT_SELECTION_OPACITY = 0.5;
  * Dimming opacity is resolved in this order:
  * 1. `config.unselectedOpacity` (explicit, usually per-chart or theme-merged)
  * 2. `DEFAULT_SELECTION_OPACITY`
+ *
+ * Variadic in the trailing args so callers can pass `(datum, group)` —
+ * the `group` argument that `PipelineStore.resolveLineStyle` threads
+ * through for line/area styles must reach the wrapped base function,
+ * or group-dependent styling (`fillArea: string[]`, `resolveStroke(d,
+ * group)` in `useXYLineStyle`'s MultiAxisLineChart path) silently
+ * drops to its no-group branch whenever a selection is active.
  */
-export declare function wrapStyleWithSelection(baseStyleFn: (d: Datum) => Datum, selectionHook: SelectionHookResult | null, config?: SelectionStyleConfig): (d: Datum) => Datum;
+export declare function wrapStyleWithSelection<TArgs extends unknown[]>(baseStyleFn: (d: Datum, ...args: TArgs) => Datum, selectionHook: SelectionHookResult | null, config?: SelectionStyleConfig): (d: Datum, ...args: TArgs) => Datum;

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

@@ -43,6 +43,11 @@ export interface BaseMetadataProps {
     accessibleTable?: boolean;
     className?: string;
     animate?: AnimateProp;
+    /** Strictly speaking not "metadata" — but the spread-when-defined
+     *  pattern is identical, and every XY/ordinal HOC needs to forward
+     *  this to the frame. Bundling it here avoids a parallel helper
+     *  + 22 separate adoption edits. */
+    axisExtent?: import("./axisExtent").AxisExtentMode;
 }
 export declare function buildBaseMetadataProps(input: BaseMetadataProps): BaseMetadataProps;
 /**

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

@@ -117,6 +117,19 @@ export interface BaseChartProps {
      * `true` uses defaults (300ms ease-out, intro enabled). Object form allows customization.
      * Set `{ intro: false }` to disable the animated intro on first render. */
     animate?: AnimateProp;
+    /** Axis extent mode. `"nice"` (default) uses d3-scale's rounded
+     *  tick generator — labels stay round but ticks may sit inside the
+     *  data domain. `"exact"` pins the first and last tick to the
+     *  actual data min and max with equidistant intermediate ticks.
+     *  Useful when a fixed scale (gauge, score band, KPI dial) needs
+     *  endpoints to read as the actual boundaries.
+     *
+     *  Applies to:
+     *  - XY charts: both x and y axes (linear, time, log).
+     *  - Ordinal charts: the value (r) axis only — the categorical
+     *    axis is a band scale and doesn't have a numeric tick set.
+     *  - Network / geo / hierarchy charts: no-op (no continuous axis). */
+    axisExtent?: import("./axisExtent").AxisExtentMode;
 }
 /**
  * Axis configuration props