semiotic 3.1.1 → 3.2.0

package/ai/system-prompt.md

@@ -76,6 +76,33 @@ Callback receiving `ChartObservation`: `{ type: "hover"|"click"|"brush"|"selecti
 ### emphasis
 `emphasis="primary"` makes a chart span two columns inside a `ChartGrid`.
 
+## Annotations (XY charts)
+- `annotations={[{ type: "y-threshold", value: 200, label: "SLA limit", color: "#e45050" }]}` — horizontal reference line
+- `annotations={[{ type: "x-threshold", value: 50, label: "Cutoff" }]}` — vertical reference line
+- `annotations={[{ type: "widget", time: 42, latency: 850, dy: -10, content: <span>Alert</span> }]}` — place React element at data coordinates
+- `annotations={[{ type: "enclose", coordinates: [datum1, datum2], label: "Cluster" }]}` — circle enclosing data points
+
+## Theming & Brand Styling
+All charts respond to CSS custom properties on any ancestor:
+```css
+.my-theme {
+  --semiotic-bg: #1a1a2e;        /* chart background */
+  --semiotic-text: #ededed;       /* primary text */
+  --semiotic-text-secondary: #aaa; /* tick labels */
+  --semiotic-grid: #333;          /* grid lines */
+  --semiotic-border: #555;        /* axis lines */
+  --semiotic-font-family: Georgia, serif;
+  --semiotic-tooltip-bg: #1a1a2e;
+  --semiotic-tooltip-text: #ededed;
+  --semiotic-tooltip-radius: 8px;
+}
+```
+Or use ThemeProvider with 15 named presets: `<ThemeProvider theme="tufte">`, `"tufte-dark"`, `"pastels"`, `"bi-tool"`, `"italian"`, `"journalist"`, `"playful"` (each with `-dark` variant), `"dark"`, `"high-contrast"`.
+
+`semiotic/themes` entry point: `themeToCSS(theme, selector)` generates CSS string, `themeToTokens(theme)` generates DTCG design tokens, `resolveThemePreset("tufte")` returns theme object by name. Theme objects: `TUFTE_LIGHT`, `TUFTE_DARK`, `PASTELS_LIGHT`, `BI_TOOL_LIGHT`, `ITALIAN_LIGHT`, `JOURNALIST_LIGHT`, `PLAYFUL_LIGHT`, etc.
+
+`COLOR_BLIND_SAFE_CATEGORICAL` — 8-color accessible palette (Wong 2011). Import from `semiotic`.
+
 ## Key Patterns
 - **Percentile band + main line**: Layer `<AreaChart yAccessor="p95" y0Accessor="p5" showLine={false} />` + `<LineChart yAccessor="p50" />`. AreaChart's `showLine` only draws the top edge, NOT a separate main line.
 - **SSR**: `renderToStaticSVG("ordinal", props)` or `renderOrdinalToStaticSVG(props)` from `semiotic/server`. Frame type is `"xy"` | `"ordinal"` | `"network"` (NOT component name).

package/dist/components/ThemeProvider.d.ts

@@ -1,12 +1,14 @@
 import * as React from "react";
-import { LIGHT_THEME, DARK_THEME } from "./store/ThemeStore";
+import { LIGHT_THEME, DARK_THEME, HIGH_CONTRAST_THEME } from "./store/ThemeStore";
 import type { SemioticTheme } from "./store/ThemeStore";
+import type { ThemePresetName } from "./semiotic-themes";
 interface ThemeProviderProps {
-    theme?: "light" | "dark" | Partial<SemioticTheme>;
+    /** Theme preset name (e.g. "tufte", "pastels-dark", "bi-tool") or a partial SemioticTheme object. */
+    theme?: ThemePresetName | Partial<SemioticTheme>;
     children: React.ReactNode;
 }
 declare function ThemeProviderWrapper({ theme, children }: ThemeProviderProps): React.JSX.Element;
 declare function useTheme(): SemioticTheme;
 export { ThemeProviderWrapper as ThemeProvider, useTheme };
-export { LIGHT_THEME, DARK_THEME };
+export { LIGHT_THEME, DARK_THEME, HIGH_CONTRAST_THEME };
 export type { SemioticTheme };

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

@@ -47,7 +47,7 @@ export interface ChoroplethMapProps<TDatum extends Record<string, any> = Record<
     /** Passthrough to StreamGeoFrame */
     frameProps?: Partial<Omit<StreamGeoFrameProps, "areas" | "projection">>;
 }
-export declare function ChoroplethMap<TDatum extends Record<string, any> = Record<string, any>>(props: ChoroplethMapProps<TDatum>): React.JSX.Element | null;
+export declare function ChoroplethMap<TDatum extends Record<string, any> = Record<string, any>>(props: ChoroplethMapProps<TDatum>): React.JSX.Element;
 export declare namespace ChoroplethMap {
     var displayName: string;
 }

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

@@ -26,6 +26,8 @@ export { MinimapChart } from "./xy/MinimapChart";
 export type { MinimapChartProps, MinimapConfig } from "./xy/MinimapChart";
 export { QuadrantChart } from "./xy/QuadrantChart";
 export type { QuadrantChartProps, QuadrantsConfig, QuadrantConfig, CenterlineStyle } from "./xy/QuadrantChart";
+export { MultiAxisLineChart } from "./xy/MultiAxisLineChart";
+export type { MultiAxisLineChartProps, MultiAxisSeriesConfig } from "./xy/MultiAxisLineChart";
 export { BarChart } from "./ordinal/BarChart";
 export type { BarChartProps } from "./ordinal/BarChart";
 export { StackedBarChart } from "./ordinal/StackedBarChart";
@@ -40,6 +42,8 @@ export { ViolinPlot } from "./ordinal/ViolinPlot";
 export type { ViolinPlotProps } from "./ordinal/ViolinPlot";
 export { RidgelinePlot } from "./ordinal/RidgelinePlot";
 export type { RidgelinePlotProps } from "./ordinal/RidgelinePlot";
+export { FunnelChart } from "./ordinal/FunnelChart";
+export type { FunnelChartProps } from "./ordinal/FunnelChart";
 export { DotPlot } from "./ordinal/DotPlot";
 export type { DotPlotProps } from "./ordinal/DotPlot";
 export { PieChart } from "./ordinal/PieChart";
@@ -75,6 +79,9 @@ export type { RealtimeHeatmapProps } from "./realtime/RealtimeHeatmap";
 export type { BaseChartProps, AxisConfig, Accessor, ChartAccessor, ChartMode } from "./shared/types";
 export { useColorScale, useSortedData, DEFAULT_COLOR } from "./shared/hooks";
 export { COLOR_SCHEMES, DEFAULT_COLORS, getColor, createColorScale, getSize } from "./shared/colorUtils";
-export { formatNumber, formatDate, formatAxis, createTooltip, formatLargeNumber, truncateText } from "./shared/formatUtils";
+export { formatNumber, formatDate, formatAxis, createTooltip, formatLargeNumber, truncateText, adaptiveTimeTicks } from "./shared/formatUtils";
+export { darkenColor, lightenColor } from "./shared/colorManipulation";
 export { Tooltip, MultiLineTooltip, normalizeTooltip } from "../Tooltip/Tooltip";
 export type { TooltipProp, TooltipConfig, TooltipField, MultiLineTooltipConfig } from "../Tooltip/Tooltip";
+export { createHatchPattern } from "./shared/hatchPattern";
+export type { HatchPatternOptions } from "./shared/hatchPattern";

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

@@ -21,6 +21,7 @@ export interface BarChartProps<TDatum extends Record<string, any> = Record<strin
     barPadding?: number;
     enableHover?: boolean;
     showGrid?: boolean;
+    showCategoryTicks?: boolean;
     showLegend?: boolean;
     legendInteraction?: LegendInteractionMode;
     legendPosition?: "right" | "left" | "top" | "bottom";

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

@@ -19,6 +19,7 @@ export interface BoxPlotProps<TDatum extends Record<string, any> = Record<string
     categoryPadding?: number;
     enableHover?: boolean;
     showGrid?: boolean;
+    showCategoryTicks?: boolean;
     showLegend?: boolean;
     legendInteraction?: LegendInteractionMode;
     legendPosition?: LegendPosition;

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

@@ -15,6 +15,7 @@ export interface DonutChartProps<TDatum extends Record<string, any> = Record<str
     startAngle?: number;
     slicePadding?: number;
     enableHover?: boolean;
+    showCategoryTicks?: boolean;
     showLegend?: boolean;
     legendInteraction?: LegendInteractionMode;
     legendPosition?: LegendPosition;

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

@@ -19,6 +19,7 @@ export interface DotPlotProps<TDatum extends Record<string, any> = Record<string
     categoryPadding?: number;
     enableHover?: boolean;
     showGrid?: boolean;
+    showCategoryTicks?: boolean;
     showLegend?: boolean;
     legendInteraction?: LegendInteractionMode;
     legendPosition?: LegendPosition;

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

@@ -0,0 +1,55 @@
+import * as React from "react";
+import type { StreamOrdinalFrameProps } from "../../stream/ordinalTypes";
+import type { LegendInteractionMode } from "../shared/hooks";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { RealtimeFrameHandle } from "../../realtime/types";
+/**
+ * FunnelChart component props
+ */
+export interface FunnelChartProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
+    data?: TDatum[];
+    /** Accessor for funnel step names (e.g., "Awareness", "Interest", "Purchase") */
+    stepAccessor?: ChartAccessor<TDatum, string>;
+    /** Accessor for the numeric value at each step */
+    valueAccessor?: ChartAccessor<TDatum, number>;
+    /** Accessor for splitting into mirrored categories (e.g., "control" vs "treatment") */
+    categoryAccessor?: ChartAccessor<TDatum, string>;
+    colorBy?: ChartAccessor<TDatum, string>;
+    colorScheme?: string | string[];
+    /**
+     * Funnel orientation.
+     *
+     * - `"horizontal"` (default): steps run top-to-bottom with centered bars and
+     *   trapezoid connectors between steps.
+     * - `"vertical"`: steps on the x-axis as vertical bars. Each bar is stacked:
+     *   solid = retained value, hatched = dropoff from the previous step.
+     *   Multi-category data renders grouped bars within each step.
+     */
+    orientation?: "horizontal" | "vertical";
+    /** Opacity of the trapezoid connectors between steps (0–1, default 0.3). Horizontal only. */
+    connectorOpacity?: number;
+    /** Show step name + value labels on bars (default true) */
+    showLabels?: boolean;
+    enableHover?: boolean;
+    showLegend?: boolean;
+    legendInteraction?: LegendInteractionMode;
+    legendPosition?: "right" | "left" | "top" | "bottom";
+    tooltip?: TooltipProp;
+    annotations?: Record<string, any>[];
+    frameProps?: Partial<Omit<StreamOrdinalFrameProps, "data" | "size">>;
+}
+/**
+ * FunnelChart — Visualize sequential conversion steps.
+ *
+ * **Horizontal** (default): centered bars narrowing top-to-bottom with
+ * trapezoid connectors. Multi-category mirrors around center axis.
+ *
+ * **Vertical** (`orientation="vertical"`): vertical bars with hatched
+ * dropoff stacking. Each bar shows retained (solid) + dropoff from
+ * previous step (hatched). Multi-category renders grouped bars.
+ */
+export declare const FunnelChart: {
+    <TDatum extends Record<string, any> = Record<string, any>>(props: FunnelChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

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

@@ -18,6 +18,7 @@ export interface GroupedBarChartProps<TDatum extends Record<string, any> = Recor
     barPadding?: number;
     enableHover?: boolean;
     showGrid?: boolean;
+    showCategoryTicks?: boolean;
     showLegend?: boolean;
     legendInteraction?: LegendInteractionMode;
     legendPosition?: "right" | "left" | "top" | "bottom";

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

@@ -18,6 +18,7 @@ export interface HistogramProps<TDatum extends Record<string, any> = Record<stri
     categoryPadding?: number;
     enableHover?: boolean;
     showGrid?: boolean;
+    showCategoryTicks?: boolean;
     showLegend?: boolean;
     legendPosition?: LegendPosition;
     tooltip?: TooltipProp;

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

@@ -13,6 +13,7 @@ export interface PieChartProps<TDatum extends Record<string, any> = Record<strin
     startAngle?: number;
     slicePadding?: number;
     enableHover?: boolean;
+    showCategoryTicks?: boolean;
     showLegend?: boolean;
     legendInteraction?: LegendInteractionMode;
     legendPosition?: LegendPosition;

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

@@ -19,6 +19,7 @@ export interface RidgelinePlotProps<TDatum extends Record<string, any> = Record<
     categoryPadding?: number;
     enableHover?: boolean;
     showGrid?: boolean;
+    showCategoryTicks?: boolean;
     showLegend?: boolean;
     legendPosition?: LegendPosition;
     tooltip?: TooltipProp;

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

@@ -19,6 +19,7 @@ export interface StackedBarChartProps<TDatum extends Record<string, any> = Recor
     barPadding?: number;
     enableHover?: boolean;
     showGrid?: boolean;
+    showCategoryTicks?: boolean;
     showLegend?: boolean;
     legendInteraction?: LegendInteractionMode;
     legendPosition?: "right" | "left" | "top" | "bottom";

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

@@ -21,6 +21,7 @@ export interface SwarmPlotProps<TDatum extends Record<string, any> = Record<stri
     categoryPadding?: number;
     enableHover?: boolean;
     showGrid?: boolean;
+    showCategoryTicks?: boolean;
     showLegend?: boolean;
     legendInteraction?: LegendInteractionMode;
     legendPosition?: LegendPosition;

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

@@ -20,6 +20,7 @@ export interface ViolinPlotProps<TDatum extends Record<string, any> = Record<str
     categoryPadding?: number;
     enableHover?: boolean;
     showGrid?: boolean;
+    showCategoryTicks?: boolean;
     showLegend?: boolean;
     legendPosition?: LegendPosition;
     tooltip?: TooltipProp;

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

@@ -0,0 +1,15 @@
+/**
+ * Lightweight color manipulation helpers.
+ * Extracted from statisticalOverlays to avoid pulling the heavy module
+ * into the main barrel import graph.
+ */
+/**
+ * Darken a CSS hex color by a factor (0–1). factor=0.5 darkens by 50%.
+ * Returns the original string unchanged if it's not a valid hex color.
+ */
+export declare function darkenColor(hex: string, factor?: number): string;
+/**
+ * Lighten a CSS hex color by a factor (0–1). factor=0.5 lightens by 50%.
+ * Returns the original string unchanged if it's not a valid hex color.
+ */
+export declare function lightenColor(hex: string, factor?: number): string;

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

@@ -84,6 +84,33 @@ export declare function formatLargeNumber(value: number, decimals?: number): str
  * Used as the default axis tickFormat when no explicit format is provided.
  */
 export declare function smartTickFormat(value: any): string;
+type TimeGranularity = "seconds" | "minutes" | "hours" | "days" | "months" | "years";
+/**
+ * Creates a hierarchical time axis formatter.
+ *
+ * The first tick is fully qualified (e.g., "Mar 24, 2026 14:33:52").
+ * Subsequent ticks show only the significant unit change (e.g., ":53").
+ * When a time boundary is crossed (new minute, hour, day, etc.), the
+ * label re-qualifies up to that boundary (e.g., "14:34:00").
+ *
+ * Designed to be passed as `xFormat` on any Semiotic XY chart.
+ * Uses the extended `(value, index, allTicks)` signature.
+ *
+ * @param granularity - Optional explicit granularity. If omitted,
+ *   auto-detected from the tick spacing on first call.
+ *
+ * @example
+ * ```tsx
+ * import { adaptiveTimeTicks } from "semiotic"
+ *
+ * // Auto-detect granularity from the data
+ * <LineChart data={ts} xFormat={adaptiveTimeTicks()} />
+ *
+ * // Explicit granularity
+ * <LineChart data={ts} xFormat={adaptiveTimeTicks("minutes")} />
+ * ```
+ */
+export declare function adaptiveTimeTicks(granularity?: TimeGranularity): (value: any, index?: number, allTicks?: number[]) => string;
 /**
  * Truncates text to specified length with ellipsis
  *
@@ -92,3 +119,4 @@ export declare function smartTickFormat(value: any): string;
  * @returns Truncated text
  */
 export declare function truncateText(text: string, maxLength?: number): string;
+export {};

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

@@ -0,0 +1,35 @@
+/**
+ * Create a diagonal-line hatch CanvasPattern for use as a fill style.
+ *
+ * Returns a CanvasPattern that can be passed as `fill` in any pieceStyle,
+ * nodeStyle, or edgeStyle function. Works with all canvas-rendered charts.
+ *
+ * @example
+ * ```tsx
+ * const hatch = createHatchPattern({ background: "#4e79a7", stroke: "#fff" })
+ * <BarChart
+ *   pieceStyle={(d) => ({ fill: d.projected ? hatch : "#4e79a7" })}
+ * />
+ * ```
+ */
+export interface HatchPatternOptions {
+    /** Background color of the pattern tile */
+    background?: string;
+    /** Color of the diagonal lines */
+    stroke?: string;
+    /** Width of the diagonal lines in pixels @default 1.5 */
+    lineWidth?: number;
+    /** Spacing between lines in pixels @default 6 */
+    spacing?: number;
+    /** Angle of the lines in degrees (0 = horizontal, 45 = diagonal) @default 45 */
+    angle?: number;
+}
+/**
+ * Create a repeating diagonal-line hatch pattern for canvas fills.
+ *
+ * Must be called in a browser environment (needs canvas). Returns null
+ * in server/test environments where canvas is unavailable.
+ */
+export declare function createHatchPattern(options?: HatchPatternOptions, 
+/** Optional target canvas to create the pattern on (for correct DPR scaling) */
+targetCtx?: CanvasRenderingContext2D): CanvasPattern | null;

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

@@ -8,6 +8,17 @@ import type { TransitionConfig } from "../../stream/types";
  * Default fill color used when no colorBy is specified
  */
 export declare const DEFAULT_COLOR = "#007bff";
+/**
+ * Returns the theme's categorical palette, or undefined if no ThemeProvider or
+ * the palette is empty. Safe to call outside a ThemeProvider (returns undefined).
+ */
+export declare function useThemeCategorical(): string[] | undefined;
+/**
+ * Resolve the effective color for a data element when no colorBy is specified.
+ * Priority: color prop > theme categorical > colorScheme > DEFAULT_COLOR.
+ * When a palette is available, cycles through colors by category name.
+ */
+export declare function resolveDefaultFill(color: string | undefined, themeCategorical: string[] | undefined, colorScheme: string | string[] | undefined, category: string | undefined, categoryIndexMap: Map<string, number>): string;
 /**
  * Resolve an accessor (string key or function) into a function.
  * Used across chart components to normalize `valueAccessor`, `categoryAccessor`, etc.
@@ -50,7 +61,7 @@ export declare function useChartSelection({ selection, linkedHover, fallbackFiel
  * expansion pattern that every chart with color encoding repeats.
  */
 export type LegendPosition = "right" | "left" | "top" | "bottom";
-export declare function useChartLegendAndMargin({ data, colorBy, colorScale, showLegend, legendPosition, userMargin, defaults, }: {
+export declare function useChartLegendAndMargin({ data, colorBy, colorScale, showLegend, legendPosition, userMargin, defaults, categories, }: {
     data: Array<Record<string, any>>;
     colorBy: Accessor<string> | undefined;
     colorScale: ((v: string) => string) | undefined;
@@ -63,6 +74,7 @@ export declare function useChartLegendAndMargin({ data, colorBy, colorScale, sho
         left: number;
         right: number;
     };
+    categories?: string[];
 }): {
     legend: ReturnType<typeof createLegend> | undefined;
     margin: {
@@ -102,6 +114,9 @@ interface ChartModeInput {
     enableHover?: boolean;
     showLegend?: boolean;
     showLabels?: boolean;
+    showCategoryTicks?: boolean;
+    /** "vertical" | "horizontal" — used to shrink the category-axis margin when showCategoryTicks is false */
+    orientation?: string;
     title?: string;
     xLabel?: string;
     yLabel?: string;

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

@@ -11,13 +11,14 @@ import type { LegendItem } from "../../types/legendTypes";
  * @param strokeWidth - Optional stroke width for legend items
  * @returns Legend configuration object for Semiotic frames
  */
-export declare function createLegend({ data, colorBy, colorScale, getColor, strokeColor, strokeWidth }: {
+export declare function createLegend({ data, colorBy, colorScale, getColor, strokeColor, strokeWidth, categories }: {
     data: Array<Record<string, any>>;
     colorBy: Accessor<string>;
     colorScale?: ((v: string) => string);
     getColor: (d: Record<string, any>, accessor: Accessor<string>, scale?: ((v: string) => string)) => string;
     strokeColor?: string;
     strokeWidth?: number;
+    categories?: string[];
 }): {
     legendGroups: {
         styleFn: (d: LegendItem) => Record<string, string | number>;

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

@@ -44,8 +44,19 @@ export interface SelectionStyleConfig {
     unselectedStyle?: Record<string, any>;
     selectedStyle?: Record<string, any>;
 }
+/** Default opacity for unselected (dimmed) elements */
+export declare const DEFAULT_SELECTION_OPACITY = 0.2;
+/**
+ * Read the --semiotic-selection-opacity CSS variable from a container element.
+ * Returns the numeric value or the default if not set or not parseable.
+ */
+export declare function readSelectionOpacityFromCSS(container: Element | null): number;
 /**
  * Wrap a base style function with selection awareness.
  * When a selection is active, non-matching datums get dimmed.
+ *
+ * Dimming opacity is resolved in this order:
+ * 1. `config.unselectedOpacity` (explicit prop)
+ * 2. `DEFAULT_SELECTION_OPACITY` (0.2)
  */
 export declare function wrapStyleWithSelection(baseStyleFn: (d: Record<string, any>) => Record<string, any>, selectionHook: SelectionHookResult | null, config?: SelectionStyleConfig): (d: Record<string, any>) => Record<string, any>;

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

@@ -56,20 +56,64 @@ export interface ForecastConfig {
     trainDasharray?: string;
     /** Dash pattern for forecast line segment. Default: "4,4" */
     forecastDasharray?: string;
-    /** Outlier dot color (pre-computed mode). Default: "#ef4444" */
-    anomalyColor?: string;
-    /** Outlier dot radius (pre-computed mode). Default: 6 */
-    anomalyRadius?: number;
+    /** Stroke opacity for the training line segment (0–1). Default: 1 */
+    trainOpacity?: number;
+    /** Stroke opacity for the forecast line segment (0–1). Default: 1 */
+    forecastOpacity?: number;
+    /**
+     * Training line stroke color.
+     * - `"darken"`: auto-darken the line's own color by 50% (hex colors only —
+     *   non-hex values like `rgb()` or CSS variables pass through unchanged).
+     * - Any CSS color string: use that color explicitly.
+     * - Omit to inherit the line's color unchanged.
+     */
+    trainStroke?: string;
+    /** Training line linecap (e.g. "round"). Default: inherits from base style */
+    trainLinecap?: string;
+    /**
+     * Render a solid underline beneath the dashed training line.
+     * - `true`: solid line in the base (or lightened) color beneath the dashed training line
+     * - `"lighten"`: solid line in a 40% lightened version of the line's color
+     * - Omit or `false`: no underline (default)
+     */
+    trainUnderline?: boolean | "lighten";
+    /**
+     * Outlier dot color.
+     * - `string`: fixed color (default: "#ef4444")
+     * - `(datum) => string`: per-datum color function
+     */
+    anomalyColor?: string | ((datum: Record<string, any>) => string);
+    /**
+     * Outlier dot radius.
+     * - `number`: fixed radius (default: 6)
+     * - `(datum) => number`: per-datum radius function (e.g. for count-based sizing)
+     */
+    anomalyRadius?: number | ((datum: Record<string, any>) => number);
+    /**
+     * Full style override for anomaly dots.
+     * When provided as a function, receives the datum and should return a CSS style object.
+     * Overrides `anomalyColor` when provided.
+     */
+    anomalyStyle?: Record<string, any> | ((datum: Record<string, any>) => Record<string, any>);
+    /**
+     * Internal: field name used to group data into separate lines (e.g. "metricLabel").
+     * When set, boundary point duplication only bridges within the same group,
+     * preventing cross-metric stray lines. Set automatically by LineChart when
+     * both lineBy and forecast are active.
+     * @internal
+     */
+    _groupBy?: string;
     /** Label for the forecast/envelope region */
     label?: string;
 }
 /** Internal segment marker added to each datum */
 export declare const SEGMENT_FIELD: "__forecastSegment";
-export type SegmentType = "training" | "observed" | "forecast";
+export type SegmentType = "training" | "training-base" | "observed" | "forecast";
 export declare function buildAnomalyAnnotations(config: AnomalyConfig): Record<string, any>[];
 export interface ForecastResult {
     processedData: Record<string, any>[];
     annotations: Record<string, any>[];
 }
 export declare function buildForecast(data: Record<string, any>[], xAccessor: string, yAccessor: string, forecastConfig: ForecastConfig, anomalyConfig?: AnomalyConfig): ForecastResult;
+export { darkenColor, lightenColor } from "./colorManipulation";
 export declare function createSegmentLineStyle(baseStyle: (d: Record<string, any>) => Record<string, any>, forecastConfig: ForecastConfig): (d: Record<string, any>) => Record<string, any>;

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

@@ -73,6 +73,9 @@ export interface BaseChartProps {
     loading?: boolean;
     /** Custom content to render when data is empty. Set to `false` to disable empty state. */
     emptyContent?: React.ReactNode | false;
+    /** Uniform fill color for all data marks. Overrides colorScheme and theme categorical.
+     * For per-category coloring, use `colorBy` + `colorScheme` instead. */
+    color?: string;
     /** Visual emphasis level for dashboard hierarchy. "primary" spans two columns in ChartGrid. */
     emphasis?: "primary" | "secondary";
     /** Enable declarative bounded animation (enter/exit/update transitions).
@@ -91,7 +94,7 @@ export interface AxisConfig {
     /** Label for the y-axis */
     yLabel?: string;
     /** Format function for x-axis tick labels */
-    xFormat?: (d: any) => string;
+    xFormat?: (d: any, index?: number, allTicks?: number[]) => string;
     /** Format function for y-axis tick labels */
     yFormat?: (d: any) => string;
 }

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

@@ -42,7 +42,7 @@ export interface HeatmapProps<TDatum extends Record<string, any> = Record<string
     /**
      * Format function for x-axis tick labels
      */
-    xFormat?: (d: any) => string;
+    xFormat?: (d: any, index?: number, allTicks?: number[]) => string;
     /**
      * Format function for y-axis tick labels
      */

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

@@ -0,0 +1,71 @@
+import * as React from "react";
+import type { StreamXYFrameProps, CurveType } from "../../stream/types";
+import type { RealtimeFrameHandle } from "../../realtime/types";
+import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { LegendInteractionMode, LegendPosition } from "../shared/hooks";
+/**
+ * Configuration for a single series in a MultiAxisLineChart.
+ */
+export interface MultiAxisSeriesConfig<TDatum = Record<string, any>> {
+    /** Field name or function to access y values for this series */
+    yAccessor: ChartAccessor<TDatum, number>;
+    /** Axis label for this series */
+    label?: string;
+    /** Override color for this series (defaults to theme palette) */
+    color?: string;
+    /** Tick format function for this series' axis */
+    format?: (d: number) => string;
+    /** Fixed extent [min, max] for this series. Required for push API streaming.
+     *  If omitted, computed from data. */
+    extent?: [number, number];
+}
+/**
+ * MultiAxisLineChart component props
+ */
+export interface MultiAxisLineChartProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps, AxisConfig {
+    /** Array of data points shared by both series */
+    data?: TDatum[];
+    /** Field name or function to access x values @default "x" */
+    xAccessor?: ChartAccessor<TDatum, number>;
+    /** Series configuration — exactly 2 for dual-axis mode.
+     *  If not exactly 2, renders as a normal line chart with a console warning. */
+    series: MultiAxisSeriesConfig<TDatum>[];
+    /** Color scheme or custom colors array @default "category10" */
+    colorScheme?: string | string[];
+    /** Enable hover annotations @default true */
+    enableHover?: boolean;
+    /** Curve interpolation @default "monotoneX" */
+    curve?: CurveType;
+    /** Line width in pixels @default 2 */
+    lineWidth?: number;
+    /** Show legend @default true */
+    showLegend?: boolean;
+    /** Show grid lines @default false */
+    showGrid?: boolean;
+    /** Tooltip configuration */
+    tooltip?: TooltipProp;
+    /** Legend interaction mode */
+    legendInteraction?: LegendInteractionMode;
+    /** Legend position */
+    legendPosition?: LegendPosition;
+    /** Annotations */
+    annotations?: Record<string, any>[];
+    /** Additional StreamXYFrame props */
+    frameProps?: Partial<Omit<StreamXYFrameProps, "chartType" | "data" | "size">>;
+}
+/**
+ * MultiAxisLineChart — Dual Y-axis line chart for comparing two series
+ * with different scales on the same time/x axis.
+ *
+ * Data is unitized (normalized to [0,1]) internally so both series share
+ * a common visual scale. The left axis shows series[0] values and the
+ * right axis shows series[1] values in their original units.
+ *
+ * If `series` does not contain exactly 2 entries, renders as a standard
+ * multi-line chart with a dev-mode console warning.
+ */
+export declare const MultiAxisLineChart: {
+    <TDatum extends Record<string, any> = Record<string, any>>(props: MultiAxisLineChartProps<TDatum> & React.RefAttributes<RealtimeFrameHandle>): React.ReactElement | null;
+    displayName?: string;
+};

package/dist/components/realtime/types.d.ts

@@ -56,6 +56,8 @@ export interface CrosshairStyle {
 export interface HoverAnnotationConfig {
     crosshair?: boolean | CrosshairStyle;
     snapToPoint?: boolean;
+    /** Color of the hover indicator dot. Defaults to the hovered element's color (stroke for lines, fill for points). Set a CSS color string to override. */
+    pointColor?: string;
 }
 export interface HoverData {
     data: Record<string, any>;

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

@@ -6,6 +6,8 @@ export { ConnectedScatterplot } from "./charts/xy/ConnectedScatterplot";
 export { BubbleChart } from "./charts/xy/BubbleChart";
 export { Heatmap } from "./charts/xy/Heatmap";
 export { ScatterplotMatrix } from "./charts/xy/ScatterplotMatrix";
+export { QuadrantChart } from "./charts/xy/QuadrantChart";
+export { MultiAxisLineChart } from "./charts/xy/MultiAxisLineChart";
 export { LinkedCharts } from "./LinkedCharts";
 export { useSelection, useLinkedHover, useBrushSelection, useFilteredData } from "./LinkedCharts";
 export { BarChart } from "./charts/ordinal/BarChart";
@@ -19,6 +21,7 @@ export { DotPlot } from "./charts/ordinal/DotPlot";
 export { RidgelinePlot } from "./charts/ordinal/RidgelinePlot";
 export { PieChart } from "./charts/ordinal/PieChart";
 export { DonutChart } from "./charts/ordinal/DonutChart";
+export { FunnelChart } from "./charts/ordinal/FunnelChart";
 export { ForceDirectedGraph } from "./charts/network/ForceDirectedGraph";
 export { ChordDiagram } from "./charts/network/ChordDiagram";
 export { SankeyDiagram } from "./charts/network/SankeyDiagram";

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

@@ -15,4 +15,7 @@ export { DotPlot } from "./charts/ordinal/DotPlot";
 export { PieChart } from "./charts/ordinal/PieChart";
 export { DonutChart } from "./charts/ordinal/DonutChart";
 export { RidgelinePlot } from "./charts/ordinal/RidgelinePlot";
+export { FunnelChart } from "./charts/ordinal/FunnelChart";
+export { createHatchPattern } from "./charts/shared/hatchPattern";
+export type { HatchPatternOptions } from "./charts/shared/hatchPattern";
 export type { StreamOrdinalFrameProps, StreamOrdinalFrameHandle, OrdinalChartType, OrdinalScales, OrdinalSceneNode } from "./stream/ordinalTypes";