semiotic 3.0.0-beta.4 → 3.0.0-beta.5

package/CLAUDE.md

@@ -1,7 +1,7 @@
 # Semiotic — AI Assistant Guide
 
 ## Quick Start
-- Install: `npm install semiotic@3.0.0-beta.4`
+- Install: `npm install semiotic`
 - Import from `semiotic` or granular: `semiotic/xy`, `semiotic/ordinal`, `semiotic/network`, `semiotic/realtime`, `semiotic/ai`, `semiotic/data`
 - `semiotic/ai` exports HOC charts + TooltipProvider + MultiLineTooltip + ThemeProvider + exportChart + validateProps + useChartObserver + DetailsPanel + ChartContainer
 - `semiotic/data` exports: `bin`, `rollup`, `groupBy`, `pivot`
@@ -17,13 +17,13 @@
 ## Component Reference
 
 ### Common props (all HOCs unless noted)
-`title` (string), `width` (number, 600), `height` (number, 400), `margin` (object), `className` (string), `enableHover` (boolean, true), `tooltip` (fn), `showLegend` (boolean), `showGrid` (boolean, false), `frameProps` (object), `onObservation` (fn), `chartId` (string)
+`title` (string), `width` (number, 600), `height` (number, 400), `responsiveWidth` (boolean, false), `responsiveHeight` (boolean, false), `margin` (object), `className` (string), `enableHover` (boolean, true), `tooltip` (fn), `showLegend` (boolean), `showGrid` (boolean, false), `frameProps` (object), `onObservation` (fn), `chartId` (string)
 
 ### XY Charts (from "semiotic" or "semiotic/xy")
 
-**LineChart** — `data` (required), `xAccessor` ("x"), `yAccessor` ("y"), `lineBy`, `lineDataAccessor` ("coordinates"), `colorBy`, `colorScheme` ("category10"), `curve` ("linear"|"monotoneX"|"monotoneY"|"step"|"stepAfter"|"stepBefore"|"basis"|"cardinal"|"catmullRom"), `lineWidth` (2), `showPoints` (false), `pointRadius` (3), `fillArea` (false), `areaOpacity` (0.3), `xLabel`, `yLabel`, `xFormat`, `yFormat`
+**LineChart** — `data` (required), `xAccessor` ("x"), `yAccessor` ("y"), `lineBy`, `lineDataAccessor` ("coordinates"), `colorBy`, `colorScheme` ("category10"), `curve` ("linear"|"monotoneX"|"monotoneY"|"step"|"stepAfter"|"stepBefore"|"basis"|"cardinal"|"catmullRom"), `lineWidth` (2), `showPoints` (false), `pointRadius` (3), `fillArea` (false), `areaOpacity` (0.3), `xLabel`, `yLabel`, `xFormat`, `yFormat`, `anomaly` (AnomalyConfig), `forecast` (ForecastConfig)
 
-**AreaChart** — Same as LineChart plus: `areaBy`, `areaOpacity` (0.7), `showLine` (true), curve default "monotoneX"
+**AreaChart** — Same as LineChart plus: `areaBy`, `y0Accessor` (per-point lower bound for band/ribbon charts), `gradientFill` (boolean|{topOpacity,bottomOpacity} — fade fill from line to baseline), `areaOpacity` (0.7), `showLine` (true), curve default "monotoneX"
 
 **StackedAreaChart** — Same as AreaChart plus: `normalize` (false)
 
@@ -131,6 +131,12 @@ Hooks: `useSelection`, `useLinkedHover`, `useBrushSelection`, `useFilteredData`
 // Theming
 <ThemeProvider theme="dark"><LineChart ... /></ThemeProvider>
 
+// Shared category colors across charts
+<CategoryColorProvider colors={{ North: "#e41a1c", South: "#377eb8" }}>
+  <LineChart data={d1} colorBy="region" />
+  <BarChart data={d2} colorBy="region" />  {/* same colors */}
+</CategoryColorProvider>
+
 // Data transforms
 import { bin, rollup, groupBy, pivot } from "semiotic/data"
 
@@ -141,6 +147,21 @@ await exportChart(el, { format: "png", scale: 2 })
 const ref = useRef()
 ref.current.push({ time: Date.now(), value: 42 })
 <RealtimeLineChart ref={ref} timeAccessor="time" valueAccessor="value" />
+
+// Forecast + anomaly detection (LineChart only)
+// Auto mode: training=dashed, observed=solid, forecast=dotted with confidence envelope
+<LineChart data={timeSeries} xAccessor="time" yAccessor="value"
+  forecast={{ trainEnd: 60, steps: 15, confidence: 0.95 }}
+  anomaly={{ threshold: 2, anomalyColor: "#ef4444" }} />
+
+// Pre-computed mode: bring your own bounds from an ML model
+// Data: { time, value, isTraining?, isForecast?, isAnomaly?, upperBounds?, lowerBounds? }
+// Envelope follows per-point bounds (non-rectilinear)
+<LineChart data={mlOutput} xAccessor="time" yAccessor="value"
+  forecast={{
+    isTraining: "isTraining", isForecast: "isForecast",
+    isAnomaly: "isAnomaly", upperBounds: "upper", lowerBounds: "lower",
+  }} />
 ```
 
 ## AI Features
@@ -153,6 +174,10 @@ ref.current.push({ time: Date.now(), value: 42 })
 
 **DetailsPanel** — selection-driven detail panel. Props: `children` (render fn), `position` ("right"|"bottom"|"overlay"), `size` (300), `trigger` ("click"|"hover"), `chartId`, `dismissOnEmpty`, `showClose`. Use inside ChartContainer via `detailsPanel` prop.
 
+**ChartGrid** — responsive grid layout for multiple charts. Props: `columns` (number|"auto"), `minCellWidth` (300), `gap` (16). Works with LinkedCharts.
+
+**ContextLayout** — places a primary chart alongside context chart(s). Props: `context` (ReactNode), `position` ("right"|"left"|"top"|"bottom"), `contextSize` (250), `gap` (12). Context charts use `mode="context"` for compact rendering.
+
 **ChartErrorBoundary** — `fallback` (ReactNode), `onError` (fn)
 
 **validateProps(componentName, props)** — returns `{ valid, errors }`

package/dist/CategoryColors.d.ts

@@ -0,0 +1,48 @@
+import * as React from "react";
+/**
+ * Category→color mapping. Maps category values (like "North", "error", "active")
+ * to fixed color strings. Charts inside a CategoryColorProvider will use these
+ * colors consistently regardless of what subset of categories each chart displays.
+ */
+export type CategoryColorMap = Record<string, string>;
+export interface CategoryColorProviderProps {
+    /** Explicit category→color mapping */
+    colors?: CategoryColorMap;
+    /**
+     * Category values to auto-assign colors from a scheme.
+     * Use when you want consistent colors but don't need specific assignments.
+     */
+    categories?: string[];
+    /** Color scheme to use for auto-assignment. Default: "category10" */
+    colorScheme?: string | string[];
+    children: React.ReactNode;
+}
+/**
+ * CategoryColorProvider — assigns stable colors to category values
+ * shared across all Semiotic charts within its subtree.
+ *
+ * Two modes:
+ * - **Explicit**: pass a `colors` map of category→color
+ * - **Auto**: pass a `categories` array and optional `colorScheme`
+ *
+ * Charts with `colorBy` inside this provider will use the mapped colors
+ * instead of computing their own color scale per-chart.
+ *
+ * ```tsx
+ * <CategoryColorProvider colors={{ North: "#e41a1c", South: "#377eb8", East: "#4daf4a" }}>
+ *   <ChartGrid columns={2}>
+ *     <LineChart data={d1} colorBy="region" responsiveWidth />
+ *     <BarChart data={d2} colorBy="region" responsiveWidth />
+ *   </ChartGrid>
+ * </CategoryColorProvider>
+ * ```
+ */
+export declare function CategoryColorProvider({ colors, categories, colorScheme, children, }: CategoryColorProviderProps): React.JSX.Element;
+export declare namespace CategoryColorProvider {
+    var displayName: string;
+}
+/**
+ * Hook to access the category color map from the nearest provider.
+ * Returns null if no provider is present.
+ */
+export declare function useCategoryColors(): CategoryColorMap | null;

package/dist/ChartGrid.d.ts

@@ -0,0 +1,37 @@
+import * as React from "react";
+export interface ChartGridProps {
+    /** Chart components to arrange in the grid */
+    children: React.ReactNode;
+    /** Number of columns. Default: "auto" (auto-fill based on minCellWidth) */
+    columns?: number | "auto";
+    /** Minimum cell width for auto columns. Default: 300 */
+    minCellWidth?: number;
+    /** Gap between cells in pixels. Default: 16 */
+    gap?: number;
+    /** CSS class for the grid container */
+    className?: string;
+    /** Inline style overrides */
+    style?: React.CSSProperties;
+}
+/**
+ * ChartGrid — responsive grid layout for multiple Semiotic charts.
+ *
+ * Arranges child charts in a CSS Grid that reflows based on available space.
+ * Each cell automatically gets `responsiveWidth` behavior since the grid
+ * manages the cell dimensions.
+ *
+ * Works naturally with `LinkedCharts` for coordinated views:
+ *
+ * ```tsx
+ * <LinkedCharts>
+ *   <ChartGrid columns={2}>
+ *     <LineChart data={d} xAccessor="x" yAccessor="y" responsiveWidth />
+ *     <BarChart data={d} categoryAccessor="cat" valueAccessor="val" responsiveWidth />
+ *   </ChartGrid>
+ * </LinkedCharts>
+ * ```
+ */
+export declare function ChartGrid({ children, columns, minCellWidth, gap, className, style, }: ChartGridProps): React.JSX.Element;
+export declare namespace ChartGrid {
+    var displayName: string;
+}

package/dist/ContextLayout.d.ts

@@ -0,0 +1,38 @@
+import * as React from "react";
+export interface ContextLayoutProps {
+    /** The main chart (renders at full size in the primary slot) */
+    children: React.ReactNode;
+    /** Context chart(s) displayed alongside the primary chart */
+    context: React.ReactNode;
+    /** Position of the context panel. Default: "right" */
+    position?: "right" | "left" | "bottom" | "top";
+    /** Size of the context panel in pixels. Default: 250 */
+    contextSize?: number;
+    /** Gap between primary and context panels in pixels. Default: 12 */
+    gap?: number;
+    /** CSS class for the layout container */
+    className?: string;
+    /** Inline style overrides */
+    style?: React.CSSProperties;
+}
+/**
+ * ContextLayout — places a primary chart alongside one or more context charts.
+ *
+ * The primary chart fills available space while the context panel has a fixed
+ * width (or height for top/bottom). Context charts should use `mode="context"`
+ * for compact rendering without axes or labels.
+ *
+ * ```tsx
+ * <ContextLayout
+ *   context={<Treemap data={hierarchy} mode="context" responsiveWidth colorByDepth />}
+ *   position="right"
+ *   contextSize={250}
+ * >
+ *   <LineChart data={timeSeries} xAccessor="time" yAccessor="value" responsiveWidth />
+ * </ContextLayout>
+ * ```
+ */
+export declare function ContextLayout({ children, context, position, contextSize, gap, className, style, }: ContextLayoutProps): React.JSX.Element;
+export declare namespace ContextLayout {
+    var displayName: string;
+}

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

@@ -0,0 +1,76 @@
+/**
+ * Statistical overlay processing for LineChart.
+ *
+ * Two modes:
+ *   **Auto mode** — provide `trainEnd` + optional `steps`/`confidence`.
+ *     The module computes regression, generates forecast points, and builds
+ *     annotations (envelope, anomaly band, boundary line).
+ *
+ *   **Pre-computed mode** — provide field accessors (`isTraining`, `isForecast`,
+ *     `isAnomaly`, `upperBounds`, `lowerBounds`). The module reads segment/bounds
+ *     from the data and generates annotations without any statistical computation.
+ *     Use this when bounds come from an external ML model.
+ */
+export interface AnomalyConfig {
+    /** Standard deviation multiplier for anomaly bounds. Default: 2 */
+    threshold?: number;
+    /** Show shaded anomaly band. Default: true */
+    showBand?: boolean;
+    /** Band fill color. Default: "#6366f1" */
+    bandColor?: string;
+    /** Band fill opacity. Default: 0.1 */
+    bandOpacity?: number;
+    /** Outlier dot color. Default: "#ef4444" */
+    anomalyColor?: string;
+    /** Outlier dot radius. Default: 6 */
+    anomalyRadius?: number;
+    /** Label for the band */
+    label?: string;
+}
+export interface ForecastConfig {
+    /** X-value where training data ends. Required for auto mode. */
+    trainEnd?: number;
+    /** Number of forecast steps beyond last data point. Default: 10 */
+    steps?: number;
+    /** Regression method. Default: "linear" */
+    method?: "linear" | "loess";
+    /** LOESS bandwidth (only for method="loess"). Default: 0.3 */
+    bandwidth?: number;
+    /** Confidence level for prediction interval (0-1). Default: 0.95 */
+    confidence?: number;
+    /** Field or function marking training data points */
+    isTraining?: string | ((d: Record<string, any>) => boolean);
+    /** Field or function marking forecast data points */
+    isForecast?: string | ((d: Record<string, any>) => boolean);
+    /** Field or function marking anomalous data points */
+    isAnomaly?: string | ((d: Record<string, any>) => boolean);
+    /** Field or function for upper envelope bound per data point */
+    upperBounds?: string | ((d: Record<string, any>) => number);
+    /** Field or function for lower envelope bound per data point */
+    lowerBounds?: string | ((d: Record<string, any>) => number);
+    /** Color for forecast line and envelope. Default: "#6366f1" */
+    color?: string;
+    /** Envelope fill opacity. Default: 0.15 */
+    bandOpacity?: number;
+    /** Dash pattern for training line segment. Default: "8,4" */
+    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;
+    /** 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 declare function buildAnomalyAnnotations(config: AnomalyConfig): Record<string, any>[];
+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 declare function createSegmentLineStyle(baseStyle: (d: Record<string, any>) => Record<string, any>, forecastConfig: ForecastConfig): (d: Record<string, any>) => Record<string, any>;
+export {};

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

@@ -50,6 +50,10 @@ export interface BaseChartProps {
     height?: number;
     /** Margin around the chart. Can be number (same on all sides) or object specifying each side */
     margin?: MarginType;
+    /** Auto-match width to parent container. Default: false */
+    responsiveWidth?: boolean;
+    /** Auto-match height to parent container (requires parent with explicit height). Default: false */
+    responsiveHeight?: boolean;
     /** CSS class name for the chart container */
     className?: string;
     /** Chart title displayed at the top */

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

@@ -60,7 +60,28 @@ export interface AreaChartProps<TDatum extends Record<string, any> = Record<stri
      */
     curve?: "linear" | "monotoneX" | "monotoneY" | "step" | "stepAfter" | "stepBefore" | "basis" | "cardinal" | "catmullRom";
     /**
-     * Area opacity
+     * Per-point lower bound accessor for band/ribbon charts.
+     * When set, the area fills between yAccessor (top) and y0Accessor (bottom)
+     * instead of filling down to the axis. Use for percentile bands (p5–p95),
+     * confidence intervals, or any ribbon visualization.
+     * @example
+     * ```ts
+     * // Data: [{ x: 0, p95: 80, p5: 20 }, ...]
+     * <AreaChart data={d} xAccessor="x" yAccessor="p95" y0Accessor="p5" />
+     * ```
+     */
+    y0Accessor?: ChartAccessor<TDatum, number>;
+    /**
+     * Gradient fill from line to baseline. Set `true` for default (80% → 5%)
+     * or `{ topOpacity, bottomOpacity }` for custom values.
+     * @default false
+     */
+    gradientFill?: boolean | {
+        topOpacity: number;
+        bottomOpacity: number;
+    };
+    /**
+     * Area opacity (flat fill, ignored when gradientFill is set)
      * @default 0.7
      */
     areaOpacity?: number;

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

@@ -2,6 +2,7 @@ import * as React from "react";
 import type { StreamXYFrameProps } from "../../stream/types";
 import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
 import { type TooltipProp } from "../../Tooltip/Tooltip";
+import type { AnomalyConfig, ForecastConfig } from "../shared/statisticalOverlays";
 /**
  * LineChart component props
  */
@@ -115,6 +116,17 @@ export interface LineChartProps<TDatum extends Record<string, any> = Record<stri
      * Annotation objects to render on the chart
      */
     annotations?: Record<string, any>[];
+    /**
+     * Anomaly detection configuration. Highlights outlier points and shows
+     * a shaded band representing the expected range (mean +/- threshold * stddev).
+     */
+    anomaly?: AnomalyConfig;
+    /**
+     * Forecast configuration. Splits the line into training (dashed),
+     * observed (solid), and forecast (dotted) segments. Shows a confidence
+     * envelope around the extrapolated forecast region.
+     */
+    forecast?: ForecastConfig;
     /**
      * Additional StreamXYFrame props for advanced customization
      * For full control, consider using StreamXYFrame directly