semiotic 3.2.2 → 3.2.3

package/CLAUDE.md

@@ -13,7 +13,7 @@
 - Every HOC accepts `frameProps` to pass through. TypeScript `strict: true`.
 
 ## Common Props (all HOCs)
-`title`, `description` (overrides aria-label), `summary` (sr-only note), `width` (600), `height` (400), `responsiveWidth`, `responsiveHeight`, `margin`, `className`, `color` (uniform fill — overrides theme/colorScheme), `enableHover` (true), `tooltip` (boolean | `(datum) => ReactNode` | `{ fields?, title?, format?, style? }`), `showLegend`, `showGrid` (false), `frameProps`, `onObservation`, `onClick`, `chartId`, `loading` (false), `emptyContent`, `legendInteraction` ("none"|"highlight"|"isolate"), `legendPosition` ("right"|"left"|"top"|"bottom"), `emphasis` ("primary"|"secondary"), `annotations` (array), `accessibleTable` (true)
+`title`, `description` (overrides aria-label), `summary` (sr-only note), `width` (600), `height` (400), `responsiveWidth`, `responsiveHeight`, `margin`, `className`, `color` (uniform fill — overrides theme/colorScheme), `enableHover` (true), `tooltip` (boolean | "multi" | `(datum) => ReactNode` | `{ fields?, title?, format?, style? }`), `showLegend`, `showGrid` (false), `frameProps`, `onObservation`, `onClick`, `chartId`, `loading` (false), `emptyContent`, `legendInteraction` ("none"|"highlight"|"isolate"), `legendPosition` ("right"|"left"|"top"|"bottom"), `emphasis` ("primary"|"secondary"), `annotations` (array), `accessibleTable` (true), `hoverHighlight` (boolean|"series" — dims non-hovered series on data mark hover), `hoverRadius` (number, default 30 — max pixel distance for hover/click hit testing)
 
 `onClick` receives `(datum, { x, y })` — the original datum and pixel coordinates. Works on lines, bars, areas, pie slices, nodes, and geo features.
 
@@ -21,8 +21,8 @@
 
 ## XY Charts (`semiotic/xy`)
 
-**LineChart** — `data`, `xAccessor` ("x"), `yAccessor` ("y"), `lineBy`, `lineDataAccessor` ("coordinates"), `colorBy`, `colorScheme`, `curve`, `lineWidth` (2), `showPoints`, `pointRadius` (3), `fillArea`, `areaOpacity` (0.3), `anomaly`, `forecast`, `directLabel`, `gapStrategy` ("break"|"interpolate"|"zero"), `xScaleType`/`yScaleType` ("linear"|"log")
-**AreaChart** — LineChart props + `areaBy`, `y0Accessor` (band/ribbon), `gradientFill` (boolean|{topOpacity,bottomOpacity}), `areaOpacity` (0.7), `showLine` (true)
+**LineChart** — `data`, `xAccessor` ("x"), `yAccessor` ("y"), `lineBy`, `lineDataAccessor` ("coordinates"), `colorBy`, `colorScheme`, `curve`, `lineWidth` (2), `showPoints`, `pointRadius` (3), `fillArea` (boolean|string[] — `true` fills all, `string[]` lists series names for per-series area fill), `areaOpacity` (0.3), `lineGradient` ({colorStops:[{offset,color}]} — horizontal gradient for line stroke), `anomaly`, `forecast`, `directLabel`, `gapStrategy` ("break"|"interpolate"|"zero"), `xScaleType`/`yScaleType` ("linear"|"log")
+**AreaChart** — LineChart props + `areaBy`, `y0Accessor` (band/ribbon), `gradientFill` (boolean|{topOpacity,bottomOpacity}|{colorStops:[{offset,color}]}), `lineGradient` ({colorStops:[{offset,color}]}), `areaOpacity` (0.7), `showLine` (true)
 **StackedAreaChart** — flat array + `areaBy` (required), `colorBy`, `normalize`. Do NOT use `lineBy` or `lineDataAccessor`.
 **Scatterplot** — `data`, `xAccessor`, `yAccessor`, `colorBy`, `sizeBy`, `sizeRange`, `pointRadius` (5), `pointOpacity` (0.8), `marginalGraphics`
 **BubbleChart** — Scatterplot + `sizeBy` (required), `sizeRange` ([5,40]), `bubbleOpacity` (0.6)
@@ -49,7 +49,9 @@
 
 **LikertChart** — `data`, `categoryAccessor` ("question"), `valueAccessor` ("score", raw mode) or `levelAccessor`+`countAccessor` ("count", pre-aggregated mode), `levels` (required, ordered negative→positive), `orientation` ("horizontal"|"vertical"), `colorScheme`. Horizontal (default): diverging bar chart centered at 0% — negative levels extend left, positive right, neutral (odd count) split 50/50 across centerline. Vertical: stacked 100% bar chart. Supports any scale size (3-point to 7-point+). Raw mode aggregates integer scores automatically (1-based: score 1 → levels[0]). The `levels` array order defines polarity — first half negative, second half positive, center neutral if odd. Supports push API for streaming — accumulates raw data internally and re-aggregates percentages on each push.
 
-All ordinal HOCs support `colorBy` and `colorScheme`. `categoryFormat` (`(label: string, index?: number) => string`) customizes individual tick labels (truncation, formatting). `showCategoryTicks` (default true) hides per-tick labels when false — margins auto-adjust. For distribution charts with `colorBy`, set `showCategoryTicks={false}` since the legend identifies categories.
+**GaugeChart** — `value` (required), `min` (0), `max` (100), `thresholds` (array of `{ value, color, label? }` defining zones), `arcWidth` (0.3, fraction of radius), `sweep` (240°), `fillZones` (true — when false, all zones render at full color and only needle moves; used for election-needle style displays), `showNeedle` (true), `needleColor`, `centerContent` (ReactNode or `(value, min, max) => ReactNode`), `valueFormat`, `showScaleLabels` (true), `backgroundColor`. Built on top of `StreamOrdinalFrame` with `projection="radial"` and `sweepAngle` (limits pie arc to < 360°). Reuses pie/donut rendering pipeline. Zones are sorted by threshold `value` before rendering. Arc auto-sizes to fill available space with negative margins for partial sweeps.
+
+All ordinal HOCs support `colorBy` and `colorScheme`. `categoryFormat` (`(label: string, index?: number) => string | ReactNode`) customizes individual tick labels (truncation, formatting, or custom ReactNode rendering via `<foreignObject>`). `showCategoryTicks` (default true) hides per-tick labels when false — margins auto-adjust. For distribution charts with `colorBy`, set `showCategoryTicks={false}` since the legend identifies categories.
 
 ## Network Charts (`semiotic/network`)
 
@@ -137,7 +139,7 @@ Fallback chain: `pointColor` → element color → `--semiotic-primary` CSS var
 **CategoryColorProvider** — `colors` (map) or `categories` + `colorScheme`
 Chart props: `selection`, `linkedHover`, `linkedBrush`. Hooks: `useSelection`, `useLinkedHover`, `useBrushSelection`, `useFilteredData`
 
-**Linked crosshair** (coordinate-based hover sync): `linkedHover={{ name: "sync", mode: "x-position", xField: "time" }}` broadcasts the hovered X data value. Other charts with the same `linkedHover` name render a synced vertical crosshair at that X position. Each chart shows its own Y values independently. Use for dashboards with multiple time-series at different scales.
+**Linked crosshair** (coordinate-based hover sync): `linkedHover={{ name: "sync", mode: "x-position", xField: "time" }}` broadcasts the hovered X data value. Other charts with the same `linkedHover` name render a synced vertical crosshair at that X position. Each chart shows its own Y values independently. Use for dashboards with multiple time-series at different scales. **Click-to-lock**: click a chart to lock the crosshair at that X position; the locked line changes to a dashed white stroke. Click again or press Escape to unlock. Locking is automatic when `linkedHover` uses `x-position` mode.
 **ScatterplotMatrix** — `data`, `fields`, `colorBy`, `cellSize`, `hoverMode`, `brushMode`
 **ChartContainer** — `title`, `subtitle`, `height` (400), `width` ("100%"), `status`, `loading`, `error`, `errorBoundary`, `actions` ({ export, fullscreen, copyConfig, dataSummary }), `controls`
 **ChartGrid** — `columns` (number|"auto"), `minCellWidth` (300), `gap` (16). `emphasis="primary"` spans two columns.
@@ -290,6 +292,46 @@ Charts render with `role="group"` (outer interactive wrapper, keyboard/focus) an
 - **frameProps style functions**: Bypass HOC color resolution — use `colorBy` prop instead. Frame style functions receive `(datum, categoryName)`, not `(datum, index)`.
 - **v2 migration**: `htmlAnnotationRules` → `widget` annotations + `svgAnnotationRules`. v2 `summaryStyle` index-based coloring → v3 category-string-based.
 - **accessibleTable**: Direct prop on HOCs. Set `accessibleTable={false}` to disable the sr-only data summary.
+- **Format functions returning ReactNode**: `xFormat`, `yFormat`, and `categoryFormat` can return `string | ReactNode`. ReactNode labels render inside `<foreignObject>` (SVG interop). Useful for rotated, multi-line, or icon-decorated tick labels:
+  ```jsx
+  <BarChart categoryFormat={(label) => <span style={{ color: "red" }}>{label}</span>} />
+  ```
+- **Per-series fillArea**: `fillArea={["seriesA", "seriesB"]}` on LineChart fills only named series while others stay as lines. Series names must match `lineBy`/`colorBy` group keys. Uses a dedicated `"mixed"` chart type internally:
+  ```jsx
+  <LineChart data={data} lineBy="series" colorBy="series" fillArea={["Revenue", "Cost"]} />
+  ```
+- **Hover highlight**: `hoverHighlight="series"` dims non-hovered series on data mark hover (not just legend). Requires `colorBy` as a string field. Works on all XY and ordinal HOCs.
+- **Click-to-lock crosshair**: In `linkedHover` x-position mode, clicking locks the crosshair (dashed white line). Hover updates are ignored while locked. Click again or press Escape to unlock. Multi-chart safe — unmounting one chart doesn't unlock another's crosshair.
+- **Multi-color gradientFill**: `gradientFill={{ colorStops: [{offset, color}] }}` on AreaChart for semantic color bands. Supports `transparent`. Requires at least 2 stops. Offsets clamped to [0,1]:
+  ```jsx
+  <AreaChart gradientFill={{ colorStops: [{ offset: 0, color: "red" }, { offset: 0.5, color: "transparent" }] }} />
+  ```
+- **Line stroke gradient**: `lineGradient={{ colorStops: [{offset, color}] }}` on LineChart/AreaChart for horizontal gradient strokes. Gradient runs from first to last X point.
+- **Multi-point tooltip**: `tooltip="multi"` on LineChart shows all series values at hovered X with color swatches (legend-in-tooltip). Custom tooltip functions receive `datum.allSeries: Array<{group, value, color}>`:
+  ```jsx
+  <LineChart data={data} lineBy="series" colorBy="series" tooltip="multi" />
+  ```
+- **Axis config** (`frameProps.axes`): Per-axis options: `includeMax: true` forces domain-max tick. `autoRotate: true` rotates bottom-axis labels 45° when crowded. `gridStyle: "dashed" | "dotted" | string` sets strokeDasharray on grid lines (requires `showGrid`):
+  ```jsx
+  <LineChart showGrid frameProps={{ axes: [{ orient: "bottom", includeMax: true, autoRotate: true, gridStyle: "dashed" }] }} />
+  ```
+- **Bar baseline alignment**: Ordinal axis baseline aligns with `rScale(0)`, not chart edge. `baselinePadding={true}` restores the old padded look; default `false` is flush.
+- **hoverRadius**: Max pixel distance for hover/click hit testing (default 30px across all frames — XY, network, geo, ordinal). Available on all XY HOCs and `StreamXYFrameProps`:
+  ```jsx
+  <Scatterplot hoverRadius={60} tooltip />  {/* Larger hit area for sparse data */}
+  ```
+- **Landmark ticks**: `landmarkTicks: true` on bottom/left axis config bolds tick labels at month/year boundaries. Works with `xScaleType: "time"` for Date-aware ticks. Custom function: `landmarkTicks: (value, index) => boolean`.
+- **xScaleType: "time"**: Creates `scaleTime` for the X axis. Ticks land on real calendar boundaries (weeks, months) instead of round numbers. Required for landmark ticks with timestamp data.
+- **Tick deduplication**: Adjacent identical tick labels are automatically removed. Prevents duplicate labels when tick format has insufficient resolution (e.g. month-only format on weekly ticks).
+
+## Performance
+
+- **scalePadding**: Pixel inset on scale ranges to prevent glyph clipping at chart edges. Insets both X and Y ranges — edge data points map to N pixels from the chart boundary instead of 0px. Domain and tick values unchanged (rendered positions shift inward with the range). On `StreamXYFrame`, use `scalePadding` directly; on HOC charts, pass via `frameProps`:
+  ```jsx
+  <StreamXYFrame chartType="candlestick" scalePadding={12} ... />
+  <Scatterplot data={data} pointRadius={8} frameProps={{ scalePadding: 12 }} />
+  ```
+- **Range/dumbbell plot**: Use `chartType="candlestick"` on StreamXYFrame with only `highAccessor` + `lowAccessor` (omit `openAccessor`/`closeAccessor`). Auto-detects range mode: no body rect, endpoint dots, single `rangeColor` via `candlestickStyle={{ rangeColor: "#6366f1" }}`. When `bodyWidth === 0`, body rect is skipped entirely (no invisible DOM elements).
 
 ## Performance
 

package/ai/schema.json

@@ -2778,6 +2778,69 @@
         }
       }
     },
+    {
+      "type": "function",
+      "function": {
+        "name": "GaugeChart",
+        "description": "Single-value gauge with threshold zones, needle indicator, and configurable sweep angle. Built on StreamOrdinalFrame radial projection.",
+        "parameters": {
+          "type": "object",
+          "properties": {
+            "value": {
+              "type": "number",
+              "description": "Current gauge value"
+            },
+            "min": {
+              "type": "number",
+              "default": 0
+            },
+            "max": {
+              "type": "number",
+              "default": 100
+            },
+            "thresholds": {
+              "type": "array",
+              "description": "Array of { value, color, label? } defining threshold zones. Last value should equal max.",
+              "items": { "type": "object" }
+            },
+            "arcWidth": {
+              "type": "number",
+              "description": "Arc thickness as fraction of radius (0-1)",
+              "default": 0.3
+            },
+            "sweep": {
+              "type": "number",
+              "description": "Arc sweep angle in degrees (gap centered at bottom)",
+              "default": 240
+            },
+            "showNeedle": {
+              "type": "boolean",
+              "default": true
+            },
+            "needleColor": {
+              "type": "string"
+            },
+            "valueFormat": {
+              "type": "string",
+              "description": "Format function for center value label"
+            },
+            "showScaleLabels": {
+              "type": "boolean",
+              "default": true
+            },
+            "width": {
+              "type": "number",
+              "default": 300
+            },
+            "height": {
+              "type": "number",
+              "default": 250
+            }
+          },
+          "required": ["value"]
+        }
+      }
+    },
     {
       "type": "function",
       "function": {

package/dist/components/Tooltip/Tooltip.d.ts

@@ -134,12 +134,17 @@ export declare function MultiLineTooltip(config?: MultiLineTooltipConfig): (data
 /**
  * Type for tooltip prop that chart components accept
  */
-export type TooltipProp = boolean | ((data: Record<string, unknown>) => React.ReactNode) | ReturnType<typeof Tooltip> | ReturnType<typeof MultiLineTooltip> | TooltipConfig;
+export type TooltipProp = boolean | "multi" | ((data: Record<string, unknown>) => React.ReactNode) | ReturnType<typeof Tooltip> | ReturnType<typeof MultiLineTooltip> | TooltipConfig;
 /**
  * The function signature that Stream Frames expect for tooltipContent.
  * Compatible with HoverData and any Record-based hover object.
  */
 export type TooltipContentFn = (d: Record<string, any>) => React.ReactNode;
+/**
+ * Multi-point tooltip: shows all series values at the hovered X position
+ * with color swatches (legend-style). Used when tooltipMode="multi".
+ */
+export declare function MultiPointTooltip(): TooltipContentFn;
 /**
  * Convert a tooltip prop to the format Semiotic expects.
  * Returns `false` to disable, or a `TooltipContentFn` compatible with

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

@@ -52,6 +52,8 @@ export { PieChart } from "./ordinal/PieChart";
 export type { PieChartProps } from "./ordinal/PieChart";
 export { DonutChart } from "./ordinal/DonutChart";
 export type { DonutChartProps } from "./ordinal/DonutChart";
+export { GaugeChart } from "./ordinal/GaugeChart";
+export type { GaugeChartProps, GaugeThreshold } from "./ordinal/GaugeChart";
 export { GroupedBarChart } from "./ordinal/GroupedBarChart";
 export type { GroupedBarChartProps } from "./ordinal/GroupedBarChart";
 export { SwimlaneChart } from "./ordinal/SwimlaneChart";

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

@@ -19,6 +19,8 @@ export interface BarChartProps<TDatum extends Record<string, any> = Record<strin
     colorScheme?: string | string[];
     sort?: boolean | "asc" | "desc" | ((a: Record<string, any>, b: Record<string, any>) => number);
     barPadding?: number;
+    /** When true, adds padding below the 0 baseline. Default false (bars flush with axis). */
+    baselinePadding?: boolean;
     enableHover?: boolean;
     showGrid?: boolean;
     showCategoryTicks?: boolean;

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

@@ -0,0 +1,55 @@
+import * as React from "react";
+import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
+import type { BaseChartProps } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { RealtimeFrameHandle } from "../../realtime/types";
+export interface GaugeThreshold {
+    /** Upper bound of this zone (value, not percentage) */
+    value: number;
+    /** Color for this threshold zone */
+    color: string;
+    /** Optional label for the zone */
+    label?: string;
+}
+export interface GaugeChartProps extends BaseChartProps {
+    /** Current gauge value */
+    value: number;
+    /** Minimum scale value (default 0) */
+    min?: number;
+    /** Maximum scale value (default 100) */
+    max?: number;
+    /** Threshold zones — ordered list of { value, color, label? }. Last threshold's value should equal max. */
+    thresholds?: GaugeThreshold[];
+    /** Color of the value arc when no thresholds defined (default: theme primary) */
+    color?: string;
+    /** Background arc color (default: var(--semiotic-grid, #e0e0e0)) */
+    backgroundColor?: string;
+    /** Arc thickness as fraction of radius (0–1, default 0.3) */
+    arcWidth?: number;
+    /** Show needle indicator (default true) */
+    showNeedle?: boolean;
+    /** Needle color (default: var(--semiotic-text, #333)) */
+    needleColor?: string;
+    /** Center content — ReactNode rendered at the gauge center. If not provided, shows the value. */
+    centerContent?: React.ReactNode | ((value: number, min: number, max: number) => React.ReactNode);
+    /** Format function for the default center value label */
+    valueFormat?: (value: number) => string;
+    /** Show scale tick labels at min, max, and threshold boundaries (default true) */
+    showScaleLabels?: boolean;
+    /** Arc sweep angle in degrees (default 240 — leaves a 120° gap at the bottom) */
+    sweep?: number;
+    /** When false, all threshold zones render at full color and only the needle indicates value. Default true (zones fill up to value). */
+    fillZones?: boolean;
+    /** Enable tooltip on arc segments */
+    tooltip?: TooltipProp;
+    /** Annotations — supports threshold markers via standard annotation system */
+    annotations?: Record<string, any>[];
+    /** Enable hover interaction (default true) */
+    enableHover?: boolean;
+    /** frameProps escape hatch */
+    frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
+}
+export declare const GaugeChart: {
+    (props: GaugeChartProps & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

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

@@ -16,6 +16,7 @@ export interface GroupedBarChartProps<TDatum extends Record<string, any> = Recor
     colorBy?: ChartAccessor<TDatum, string>;
     colorScheme?: string | string[];
     barPadding?: number;
+    baselinePadding?: boolean;
     enableHover?: boolean;
     showGrid?: boolean;
     showCategoryTicks?: boolean;

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

@@ -17,6 +17,7 @@ export interface StackedBarChartProps<TDatum extends Record<string, any> = Recor
     colorScheme?: string | string[];
     normalize?: boolean;
     barPadding?: number;
+    baselinePadding?: boolean;
     enableHover?: boolean;
     showGrid?: boolean;
     showCategoryTicks?: boolean;

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

@@ -43,7 +43,7 @@ export declare function useSortedData(data: Array<Record<string, any>>, sort: bo
  * @param unwrapData - Deprecated / no-op. Hover data is always unwrapped
  *   (stream frames wrap the raw datum in { data, time, value, x, y }).
  */
-export declare function useChartSelection({ selection, linkedHover, fallbackFields, unwrapData, onObservation, chartType, chartId, onClick, }: {
+export declare function useChartSelection({ selection, linkedHover, fallbackFields, unwrapData, onObservation, chartType, chartId, onClick, hoverHighlight, colorByField, }: {
     selection?: SelectionConfig;
     linkedHover?: LinkedHoverProp;
     fallbackFields?: string[];
@@ -55,8 +55,11 @@ export declare function useChartSelection({ selection, linkedHover, fallbackFiel
         x: number;
         y: number;
     }) => void;
+    hoverHighlight?: boolean | "series";
+    colorByField?: string;
 }): {
     activeSelectionHook: SelectionHookResult | null;
+    hoverSelectionHook: SelectionHookResult | null;
     customHoverBehavior: (d: Record<string, any> | null) => void;
     customClickBehavior: (d: Record<string, any> | null) => void;
     /** Stable ID for this chart instance, used to suppress linked crosshair on source chart */

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

@@ -1,3 +1,4 @@
+import type React from "react";
 import type { MarginType } from "../../types/generalTypes";
 import type { OnObservationCallback } from "../../store/ObservationStore";
 /**
@@ -92,6 +93,10 @@ export interface BaseChartProps {
         x: number;
         y: number;
     }) => void;
+    /** Dim non-hovered series when hovering a data mark. "series" dims by the colorBy group key. */
+    hoverHighlight?: boolean | "series";
+    /** Max pixel distance for hover/click hit testing. Default 30. Increase for sparse charts, decrease for dense ones. */
+    hoverRadius?: number;
     /** Visual emphasis level for dashboard hierarchy. "primary" spans two columns in ChartGrid. */
     emphasis?: "primary" | "secondary";
     /** Enable declarative bounded animation (enter/exit/update transitions).
@@ -109,16 +114,16 @@ export interface AxisConfig {
     xLabel?: string;
     /** Label for the y-axis */
     yLabel?: string;
-    /** Format function for x-axis tick labels */
-    xFormat?: (d: any, index?: number, allTicks?: number[]) => string;
-    /** Format function for y-axis tick labels */
-    yFormat?: (d: any) => string;
+    /** Format function for x-axis tick labels. Return string or ReactNode for custom rendering. */
+    xFormat?: (d: any, index?: number, allTicks?: number[]) => string | React.ReactNode;
+    /** Format function for y-axis tick labels. Return string or ReactNode for custom rendering. */
+    yFormat?: (d: any) => string | React.ReactNode;
 }
 /**
  * Category formatting for ordinal chart tick labels.
  * Receives the category value and its index, returns a formatted string.
  */
-export type CategoryFormatFn = (label: string, index?: number) => string;
+export type CategoryFormatFn = (label: string, index?: number) => string | React.ReactNode;
 /**
  * Accessor type - can be a property name or a function
  * @deprecated Use DataAccessor from generalTypes for generic type safety

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

@@ -55,6 +55,8 @@ export interface ChartSetupInput {
         x: number;
         y: number;
     }) => void;
+    /** Dim non-hovered series on data mark hover */
+    hoverHighlight?: boolean | "series";
     /** Loading state */
     loading: boolean | undefined;
     /** Empty content override */

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

@@ -74,19 +74,34 @@ export interface AreaChartProps<TDatum extends Record<string, any> = Record<stri
      */
     y0Accessor?: ChartAccessor<TDatum, number>;
     /**
-     * Gradient fill from line to baseline. Set `true` for default (80% → 5%)
-     * or `{ topOpacity, bottomOpacity }` for custom values.
+     * 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.
      * @default false
      */
     gradientFill?: boolean | {
         topOpacity: number;
         bottomOpacity: number;
+    } | {
+        colorStops: Array<{
+            offset: number;
+            color: string;
+        }>;
     };
     /**
      * Area opacity (flat fill, ignored when gradientFill is set)
      * @default 0.7
      */
     areaOpacity?: number;
+    /**
+     * Horizontal gradient for the line stroke. Color stops define a left-to-right gradient.
+     */
+    lineGradient?: {
+        colorStops: Array<{
+            offset: number;
+            color: string;
+        }>;
+    };
     /**
      * Show line on top of area
      * @default true

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

@@ -38,7 +38,7 @@ export interface LineChartProps<TDatum extends Record<string, any> = Record<stri
      * Scale type for the x-axis
      * @default "linear"
      */
-    xScaleType?: "linear" | "log";
+    xScaleType?: "linear" | "log" | "time";
     /**
      * Scale type for the y-axis
      * @default "linear"
@@ -89,15 +89,26 @@ export interface LineChartProps<TDatum extends Record<string, any> = Record<stri
      */
     pointRadius?: number;
     /**
-     * Fill area under the line
+     * Fill area under the line. `true` fills all series, `string[]` lists series
+     * names (matching lineBy/colorBy group key) that get area fill while others stay as lines.
      * @default false
      */
-    fillArea?: boolean;
+    fillArea?: boolean | string[];
     /**
      * Area opacity when fillArea is true
      * @default 0.3
      */
     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" }] }`
+     */
+    lineGradient?: {
+        colorStops: Array<{
+            offset: number;
+            color: string;
+        }>;
+    };
     /**
      * Line stroke width
      * @default 2

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

@@ -15,6 +15,8 @@ export { ViolinPlot } from "./charts/ordinal/ViolinPlot";
 export { DotPlot } from "./charts/ordinal/DotPlot";
 export { PieChart } from "./charts/ordinal/PieChart";
 export { DonutChart } from "./charts/ordinal/DonutChart";
+export { GaugeChart } from "./charts/ordinal/GaugeChart";
+export type { GaugeChartProps, GaugeThreshold } from "./charts/ordinal/GaugeChart";
 export { RidgelinePlot } from "./charts/ordinal/RidgelinePlot";
 export { FunnelChart } from "./charts/ordinal/FunnelChart";
 export { LikertChart } from "./charts/ordinal/LikertChart";

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

@@ -17,6 +17,7 @@ export { createHatchPattern } from "./charts/shared/hatchPattern";
 export type { HatchPatternOptions } from "./charts/shared/hatchPattern";
 export { validateProps } from "./charts/shared/validateProps";
 export { diagnoseConfig } from "./charts/shared/diagnoseConfig";
+export { getHitRadius } from "./stream/hitTestUtils";
 export { toConfig, fromConfig, toURL, fromURL, copyConfig, configToJSX } from "./export/chartConfig";
 export type { ChartConfig, ToConfigOptions, CopyFormat } from "./export/chartConfig";
 export { serializeSelections, deserializeSelections } from "./export/selectionSerializer";
@@ -26,5 +27,5 @@ export { fromVegaLite } from "./data/fromVegaLite";
 export type { VegaLiteSpec, VegaLiteEncoding } from "./data/fromVegaLite";
 export { RingBuffer } from "./realtime/RingBuffer";
 export { IncrementalExtent } from "./realtime/IncrementalExtent";
-export { normalizeTooltip } from "./Tooltip/Tooltip";
+export { normalizeTooltip, MultiPointTooltip } from "./Tooltip/Tooltip";
 export { useReducedMotion, useHighContrast } from "./stream/useMediaPreferences";

package/dist/components/semiotic.d.ts

@@ -1,7 +1,7 @@
 import StreamXYFrame from "./stream/StreamXYFrame";
 import StreamOrdinalFrame from "./stream/StreamOrdinalFrame";
 import StreamNetworkFrame from "./stream/StreamNetworkFrame";
-import { Scatterplot, ConnectedScatterplot, LineChart, AreaChart, StackedAreaChart, Heatmap, BubbleChart, BarChart, StackedBarChart, LikertChart, SwarmPlot, BoxPlot, Histogram, ViolinPlot, RidgelinePlot, DotPlot, PieChart, DonutChart, GroupedBarChart, FunnelChart, SwimlaneChart, ForceDirectedGraph, ChordDiagram, SankeyDiagram, TreeDiagram, Treemap, CirclePack, OrbitDiagram, ScatterplotMatrix, MinimapChart, QuadrantChart, MultiAxisLineChart } from "./charts";
+import { Scatterplot, ConnectedScatterplot, LineChart, AreaChart, StackedAreaChart, Heatmap, BubbleChart, BarChart, StackedBarChart, LikertChart, SwarmPlot, BoxPlot, Histogram, ViolinPlot, RidgelinePlot, DotPlot, PieChart, DonutChart, GaugeChart, GroupedBarChart, FunnelChart, SwimlaneChart, ForceDirectedGraph, ChordDiagram, SankeyDiagram, TreeDiagram, Treemap, CirclePack, OrbitDiagram, ScatterplotMatrix, MinimapChart, QuadrantChart, MultiAxisLineChart } from "./charts";
 import { LinkedCharts } from "./LinkedCharts";
 import { ThemeProvider, useTheme } from "./ThemeProvider";
 import { exportChart } from "./export/exportChart";
@@ -23,8 +23,8 @@ import { RealtimeTemporalHistogram, RealtimeHistogram } from "./charts/realtime/
 import { RealtimeSwarmChart } from "./charts/realtime/RealtimeSwarmChart";
 import { RealtimeWaterfallChart } from "./charts/realtime/RealtimeWaterfallChart";
 import { RealtimeHeatmap } from "./charts/realtime/RealtimeHeatmap";
-export { StreamXYFrame, StreamOrdinalFrame, StreamNetworkFrame, Scatterplot, ConnectedScatterplot, LineChart, AreaChart, StackedAreaChart, Heatmap, BubbleChart, BarChart, StackedBarChart, LikertChart, SwarmPlot, BoxPlot, Histogram, ViolinPlot, RidgelinePlot, DotPlot, ForceDirectedGraph, ChordDiagram, SankeyDiagram, TreeDiagram, PieChart, DonutChart, FunnelChart, GroupedBarChart, SwimlaneChart, Treemap, CirclePack, OrbitDiagram, ScatterplotMatrix, MinimapChart, QuadrantChart, MultiAxisLineChart, LinkedCharts, ThemeProvider, useTheme, exportChart, toConfig, fromConfig, toURL, fromURL, copyConfig, configToJSX, serializeSelections, deserializeSelections, fromVegaLite, ChartErrorBoundary, ChartContainer, ChartGrid, CategoryColorProvider, useCategoryColors, ContextLayout, DetailsPanel, Tooltip, MultiLineTooltip, normalizeTooltip, RingBuffer, IncrementalExtent, RealtimeLineChart, RealtimeTemporalHistogram, RealtimeHistogram, RealtimeSwarmChart, RealtimeWaterfallChart, RealtimeHeatmap, createHatchPattern };
-export { ScatterplotProps, ConnectedScatterplotProps, LineChartProps, AreaChartProps, StackedAreaChartProps, HeatmapProps, BubbleChartProps, BarChartProps, StackedBarChartProps, LikertChartProps, SwarmPlotProps, BoxPlotProps, HistogramProps, ViolinPlotProps, DotPlotProps, PieChartProps, DonutChartProps, FunnelChartProps, GroupedBarChartProps, SwimlaneChartProps, RidgelinePlotProps, OrbitDiagramProps, OrbitNode, ForceDirectedGraphProps, ChordDiagramProps, SankeyDiagramProps, TreeDiagramProps, TreemapProps, CirclePackProps, ScatterplotMatrixProps, MinimapChartProps, MinimapConfig, QuadrantChartProps, MultiAxisLineChartProps, MultiAxisSeriesConfig, QuadrantsConfig, QuadrantConfig, CenterlineStyle, BaseChartProps, AxisConfig, Accessor, ChartAccessor, ChartMode } from "./charts";
+export { StreamXYFrame, StreamOrdinalFrame, StreamNetworkFrame, Scatterplot, ConnectedScatterplot, LineChart, AreaChart, StackedAreaChart, Heatmap, BubbleChart, BarChart, StackedBarChart, LikertChart, SwarmPlot, BoxPlot, Histogram, ViolinPlot, RidgelinePlot, DotPlot, ForceDirectedGraph, ChordDiagram, SankeyDiagram, TreeDiagram, PieChart, DonutChart, GaugeChart, FunnelChart, GroupedBarChart, SwimlaneChart, Treemap, CirclePack, OrbitDiagram, ScatterplotMatrix, MinimapChart, QuadrantChart, MultiAxisLineChart, LinkedCharts, ThemeProvider, useTheme, exportChart, toConfig, fromConfig, toURL, fromURL, copyConfig, configToJSX, serializeSelections, deserializeSelections, fromVegaLite, ChartErrorBoundary, ChartContainer, ChartGrid, CategoryColorProvider, useCategoryColors, ContextLayout, DetailsPanel, Tooltip, MultiLineTooltip, normalizeTooltip, RingBuffer, IncrementalExtent, RealtimeLineChart, RealtimeTemporalHistogram, RealtimeHistogram, RealtimeSwarmChart, RealtimeWaterfallChart, RealtimeHeatmap, createHatchPattern };
+export { ScatterplotProps, ConnectedScatterplotProps, LineChartProps, AreaChartProps, StackedAreaChartProps, HeatmapProps, BubbleChartProps, BarChartProps, StackedBarChartProps, LikertChartProps, SwarmPlotProps, BoxPlotProps, HistogramProps, ViolinPlotProps, DotPlotProps, PieChartProps, DonutChartProps, GaugeChartProps, GaugeThreshold, FunnelChartProps, GroupedBarChartProps, SwimlaneChartProps, RidgelinePlotProps, OrbitDiagramProps, OrbitNode, ForceDirectedGraphProps, ChordDiagramProps, SankeyDiagramProps, TreeDiagramProps, TreemapProps, CirclePackProps, ScatterplotMatrixProps, MinimapChartProps, MinimapConfig, QuadrantChartProps, MultiAxisLineChartProps, MultiAxisSeriesConfig, QuadrantsConfig, QuadrantConfig, CenterlineStyle, BaseChartProps, AxisConfig, Accessor, ChartAccessor, ChartMode } from "./charts";
 export type { StreamXYFrameProps, StreamXYFrameHandle, StreamChartType, RuntimeMode, SceneNode, Changeset, StreamScales, StreamLayout, CurveType, CanvasRendererFn } from "./stream/types";
 export type { StreamRendererFn } from "./stream/renderers/types";
 export type { StreamOrdinalFrameProps, StreamOrdinalFrameHandle, OrdinalChartType, OrdinalScales, OrdinalSceneNode } from "./stream/ordinalTypes";

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

@@ -1,11 +1,15 @@
 export declare function setCrosshairPosition(name: string, xValue: number, sourceId: string): void;
 export declare function clearCrosshairPosition(name: string, sourceId: string): void;
+/** Toggle lock: if unlocked, lock at xValue; if locked, unlock and clear. Returns new locked state. */
+export declare function toggleCrosshairLock(name: string, xValue: number, sourceId: string): boolean;
+/** Force-unlock a crosshair by name. When sourceId is provided, only unlocks if it matches (safe for multi-chart unmount). */
+export declare function unlockCrosshair(name: string, sourceId?: string): void;
 /**
  * Hook to read a specific crosshair position by name.
- * Returns the X value and sourceId, or null if no crosshair is active.
- * When name is undefined, uses a no-op subscription to avoid unnecessary re-renders.
+ * Returns the X value, sourceId, and locked state, or null if no crosshair is active.
  */
 export declare function useCrosshairPosition(name: string | undefined): {
     xValue: number;
     sourceId: string;
+    locked?: boolean;
 } | null;

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

@@ -18,6 +18,19 @@ export interface HitResult {
  * use the linear scan.
  */
 export declare function findNearestNode(scene: SceneNode[], px: number, py: number, maxDistance?: number, pointQuadtree?: Quadtree<PointSceneNode> | null): HitResult | null;
+/**
+ * Find all line/area nodes at a given X pixel coordinate.
+ * For each node, interpolates the Y value at px using the path data.
+ * Used for multi-point tooltip (show all series values at the hovered X).
+ */
+export declare function findAllNodesAtX(scene: SceneNode[], px: number, maxXDistance?: number): Array<{
+    node: SceneNode;
+    datum: any;
+    x: number;
+    y: number;
+    group?: string;
+    color?: string;
+}>;
 /**
  * Binary search for nearest point by time value in a RingBuffer.
  */

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

@@ -19,7 +19,7 @@ interface OrdinalSVGOverlayProps {
     showCategoryTicks?: boolean;
     oLabel?: string;
     rLabel?: string;
-    oFormat?: (d: string, index?: number) => string;
+    oFormat?: (d: string, index?: number) => string | React.ReactNode;
     rFormat?: (d: number) => string;
     showGrid?: boolean;
     title?: string | ReactNode;

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

@@ -9,6 +9,8 @@ export interface PipelineConfig {
     windowMode: WindowMode;
     arrowOfTime: ArrowOfTime;
     extentPadding: number;
+    /** Pixel inset on scale ranges to prevent glyph clipping at chart edges. Default 0. */
+    scalePadding?: number;
     maxCapacity?: number;
     xAccessor?: string | ((d: any) => number);
     yAccessor?: string | ((d: any) => number);
@@ -19,7 +21,7 @@ export interface PipelineConfig {
     groupAccessor?: string | ((d: any) => string);
     categoryAccessor?: string | ((d: any) => string);
     lineDataAccessor?: string;
-    xScaleType?: "linear" | "log";
+    xScaleType?: "linear" | "log" | "time";
     yScaleType?: "linear" | "log";
     xExtent?: [number | undefined, number | undefined] | [number];
     yExtent?: [number | undefined, number | undefined] | [number];
@@ -31,12 +33,26 @@ export interface PipelineConfig {
     lowAccessor?: string | ((d: any) => number);
     closeAccessor?: string | ((d: any) => number);
     candlestickStyle?: CandlestickStyle;
+    /** Internal: set by PipelineStore when open/close accessors are both missing */
+    candlestickRangeMode?: boolean;
     boundsAccessor?: string | ((d: any) => number);
     boundsStyle?: any;
     y0Accessor?: string | ((d: any) => number);
     gradientFill?: {
         topOpacity: number;
         bottomOpacity: number;
+    } | {
+        colorStops: Array<{
+            offset: number;
+            color: string;
+        }>;
+    };
+    areaGroups?: Set<string>;
+    lineGradient?: {
+        colorStops: Array<{
+            offset: number;
+            color: string;
+        }>;
     };
     lineStyle?: any;
     pointStyle?: (d: any) => Style & {

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

@@ -7,9 +7,15 @@ export interface AxisConfig {
     orient: "left" | "right" | "top" | "bottom";
     label?: string;
     ticks?: number;
-    tickFormat?: (d: any, index?: number, allTicks?: number[]) => string;
+    tickFormat?: (d: any, index?: number, allTicks?: number[]) => string | ReactNode;
     baseline?: boolean | "under";
     jaggedBase?: boolean;
+    /** Grid line stroke style: "dashed" (6,4), "dotted" (2,4), or a custom strokeDasharray string. Applied to grid lines extending from ticks across the chart area. */
+    gridStyle?: "dashed" | "dotted" | string;
+    /** Always include the domain max as a tick, even if d3 omits it. */
+    includeMax?: boolean;
+    /** Auto-rotate labels 45° when horizontal spacing is too tight. */
+    autoRotate?: boolean;
     /** Highlight ticks at time boundaries (new month, year, etc.) with semibold text.
      * `true` auto-detects Date boundaries. A function receives (value, index) and returns true for landmark ticks. */
     landmarkTicks?: boolean | ((value: any, index: number) => boolean);
@@ -32,8 +38,8 @@ interface SVGOverlayProps {
     yLabel?: string;
     /** Label for the right Y axis (dual-axis charts) */
     yLabelRight?: string;
-    xFormat?: (d: any, index?: number, allTicks?: number[]) => string;
-    yFormat?: (d: any) => string;
+    xFormat?: (d: any, index?: number, allTicks?: number[]) => string | ReactNode;
+    yFormat?: (d: any) => string | ReactNode;
     showGrid?: boolean;
     title?: string | ReactNode;
     legend?: ReactNode | {
@@ -96,8 +102,8 @@ interface SVGUnderlayProps {
     showAxes?: boolean;
     axes?: AxisConfig[];
     showGrid?: boolean;
-    xFormat?: (d: any, index?: number, allTicks?: number[]) => string;
-    yFormat?: (d: any) => string;
+    xFormat?: (d: any, index?: number, allTicks?: number[]) => string | ReactNode;
+    yFormat?: (d: any) => string | ReactNode;
 }
 export declare function SVGUnderlay(props: SVGUnderlayProps): React.JSX.Element | null;
 export declare function SVGOverlay(props: SVGOverlayProps): React.JSX.Element | null;