semiotic 2.0.2 → 3.0.0-beta.1

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

@@ -0,0 +1,119 @@
+import * as React from "react";
+import type { OrdinalFrameProps } from "../../types/ordinalTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+/**
+ * StackedBarChart component props
+ */
+export interface StackedBarChartProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
+    /**
+     * Array of data points with category, subcategory, and value.
+     * @example
+     * ```ts
+     * [
+     *   {category: 'Q1', subcategory: 'Product A', value: 100},
+     *   {category: 'Q1', subcategory: 'Product B', value: 150},
+     *   {category: 'Q2', subcategory: 'Product A', value: 120}
+     * ]
+     * ```
+     */
+    data: TDatum[];
+    /**
+     * Field name or function to access category values
+     * @default "category"
+     */
+    categoryAccessor?: ChartAccessor<TDatum, string>;
+    /**
+     * Field name or function to access subcategory values (for stacking)
+     * @default "subcategory"
+     */
+    stackBy: ChartAccessor<TDatum, string>;
+    /**
+     * Field name or function to access numeric values
+     * @default "value"
+     */
+    valueAccessor?: ChartAccessor<TDatum, number>;
+    /**
+     * Chart orientation
+     * @default "vertical"
+     */
+    orientation?: "vertical" | "horizontal";
+    /**
+     * Label for the category axis
+     */
+    categoryLabel?: string;
+    /**
+     * Label for the value axis
+     */
+    valueLabel?: string;
+    /**
+     * Format function for value axis tick labels
+     */
+    valueFormat?: (d: number | string) => string;
+    /**
+     * Field name or function to determine bar color (typically stackBy)
+     * @default stackBy value
+     */
+    colorBy?: ChartAccessor<TDatum, string>;
+    /**
+     * Color scheme for categorical data or custom colors array
+     * @default "category10"
+     */
+    colorScheme?: string | string[];
+    /**
+     * Normalize to 100% (percentage stacked)
+     * @default false
+     */
+    normalize?: boolean;
+    /**
+     * Padding between bar groups (in pixels)
+     * @default 5
+     */
+    barPadding?: number;
+    /**
+     * Enable hover annotations
+     * @default true
+     */
+    enableHover?: boolean;
+    /**
+     * Show grid lines
+     * @default false
+     */
+    showGrid?: boolean;
+    /**
+     * Show legend for stack categories
+     * @default true
+     */
+    showLegend?: boolean;
+    /**
+     * Tooltip configuration
+     */
+    tooltip?: TooltipProp;
+    /**
+     * Additional OrdinalFrame props for advanced customization
+     * For full control, consider using OrdinalFrame directly
+     * @see https://semiotic.nteract.io/guides/ordinal-frame
+     */
+    frameProps?: Partial<Omit<OrdinalFrameProps, "data" | "size">>;
+}
+/**
+ * StackedBarChart - Visualize part-to-whole relationships with stacked bars.
+ *
+ * A simplified wrapper around OrdinalFrame for creating stacked bar charts.
+ *
+ * @example
+ * ```tsx
+ * <StackedBarChart
+ *   data={[
+ *     {category: 'Q1', product: 'A', value: 100},
+ *     {category: 'Q1', product: 'B', value: 150},
+ *     {category: 'Q2', product: 'A', value: 120},
+ *     {category: 'Q2', product: 'B', value: 180}
+ *   ]}
+ *   stackBy="product"
+ *   categoryLabel="Quarter"
+ *   valueLabel="Sales"
+ * />
+ * ```
+ */
+export declare function StackedBarChart<TDatum extends Record<string, any> = Record<string, any>>(props: StackedBarChartProps<TDatum>): React.JSX.Element;

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

@@ -0,0 +1,137 @@
+import * as React from "react";
+import type { OrdinalFrameProps } from "../../types/ordinalTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+/**
+ * SwarmPlot component props
+ */
+export interface SwarmPlotProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
+    /**
+     * Array of data points with category and value.
+     * @example
+     * ```ts
+     * [
+     *   {category: 'Group A', value: 10, type: 'X'},
+     *   {category: 'Group A', value: 12, type: 'Y'},
+     *   {category: 'Group B', value: 15, type: 'X'}
+     * ]
+     * ```
+     */
+    data: TDatum[];
+    /**
+     * Field name or function to access category values
+     * @default "category"
+     */
+    categoryAccessor?: ChartAccessor<TDatum, string>;
+    /**
+     * Field name or function to access numeric values
+     * @default "value"
+     */
+    valueAccessor?: ChartAccessor<TDatum, number>;
+    /**
+     * Chart orientation
+     * @default "vertical"
+     */
+    orientation?: "vertical" | "horizontal";
+    /**
+     * Label for the category axis
+     */
+    categoryLabel?: string;
+    /**
+     * Label for the value axis
+     */
+    valueLabel?: string;
+    /**
+     * Format function for value axis tick labels
+     */
+    valueFormat?: (d: number | string) => string;
+    /**
+     * Field name or function to determine point color
+     * @example
+     * ```ts
+     * colorBy="type"
+     * colorBy={d => d.score > 10 ? 'red' : 'blue'}
+     * ```
+     */
+    colorBy?: ChartAccessor<TDatum, string>;
+    /**
+     * Color scheme for categorical data or custom colors array
+     * @default "category10"
+     */
+    colorScheme?: string | string[];
+    /**
+     * Field name or function to determine point size
+     * @example
+     * ```ts
+     * sizeBy="importance"
+     * sizeBy={d => Math.sqrt(d.value)}
+     * ```
+     */
+    sizeBy?: ChartAccessor<TDatum, number>;
+    /**
+     * Min and max radius for points when using dynamic sizing
+     * @default [3, 8]
+     */
+    sizeRange?: [number, number];
+    /**
+     * Default point radius when sizeBy is not specified
+     * @default 4
+     */
+    pointRadius?: number;
+    /**
+     * Point opacity
+     * @default 0.7
+     */
+    pointOpacity?: number;
+    /**
+     * Padding between categories (in pixels)
+     * @default 20
+     */
+    categoryPadding?: number;
+    /**
+     * Enable hover annotations
+     * @default true
+     */
+    enableHover?: boolean;
+    /**
+     * Show grid lines
+     * @default false
+     */
+    showGrid?: boolean;
+    /**
+     * Show legend
+     * @default true (when colorBy is specified)
+     */
+    showLegend?: boolean;
+    /**
+     * Tooltip configuration
+     */
+    tooltip?: TooltipProp;
+    /**
+     * Additional OrdinalFrame props for advanced customization
+     * For full control, consider using OrdinalFrame directly
+     * @see https://semiotic.nteract.io/guides/ordinal-frame
+     */
+    frameProps?: Partial<Omit<OrdinalFrameProps, "data" | "size">>;
+}
+/**
+ * SwarmPlot - Visualize distributions with non-overlapping points.
+ *
+ * A simplified wrapper around OrdinalFrame for creating swarm plots (beeswarm plots).
+ *
+ * @example
+ * ```tsx
+ * <SwarmPlot
+ *   data={[
+ *     {category: 'Group A', value: 10},
+ *     {category: 'Group A', value: 12},
+ *     {category: 'Group A', value: 11},
+ *     {category: 'Group B', value: 15},
+ *     {category: 'Group B', value: 14}
+ *   ]}
+ *   categoryLabel="Group"
+ *   valueLabel="Value"
+ * />
+ * ```
+ */
+export declare function SwarmPlot<TDatum extends Record<string, any> = Record<string, any>>(props: SwarmPlotProps<TDatum>): React.JSX.Element;

package/dist/charts/realtime/RealtimeBarChart.d.ts

@@ -0,0 +1,102 @@
+import * as React from "react";
+import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, RealtimeFrameHandle, AnnotationContext } from "../../realtime/types";
+import type { ReactNode } from "react";
+export interface RealtimeBarChartProps {
+    /** Time interval for binning */
+    binSize: number;
+    /** Chart dimensions as [width, height] */
+    size?: [number, number];
+    /** Chart margins */
+    margin?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+    /** CSS class name */
+    className?: string;
+    /** Direction time flows */
+    arrowOfTime?: ArrowOfTime;
+    /** Data retention strategy */
+    windowMode?: WindowMode;
+    /** Ring buffer capacity */
+    windowSize?: number;
+    /** Controlled data array */
+    data?: Record<string, any>[];
+    /** Time value accessor */
+    timeAccessor?: string | ((d: Record<string, any>) => number);
+    /** Value accessor */
+    valueAccessor?: string | ((d: Record<string, any>) => number);
+    /** Fixed time domain */
+    timeExtent?: [number, number];
+    /** Fixed value domain */
+    valueExtent?: [number, number];
+    /** Extent padding factor */
+    extentPadding?: number;
+    /**
+     * Category accessor for stacked bars.
+     * When provided, bars are stacked by category within each bin.
+     */
+    categoryAccessor?: string | ((d: Record<string, any>) => string);
+    /**
+     * Category-to-color map for stacked bars.
+     * Keys also determine stack order (listed keys first, then alphabetical).
+     */
+    colors?: Record<string, string>;
+    /** Bar fill color (non-stacked mode) */
+    fill?: string;
+    /** Bar stroke color */
+    stroke?: string;
+    /** Bar stroke width */
+    strokeWidth?: number;
+    /** Gap between bars in pixels */
+    gap?: number;
+    /** Show canvas-drawn axes */
+    showAxes?: boolean;
+    /** Background fill color */
+    background?: string;
+    /** Enable hover interaction */
+    enableHover?: boolean | HoverAnnotationConfig;
+    /** Custom tooltip renderer */
+    tooltipContent?: (d: HoverData) => ReactNode;
+    /** Callback on hover */
+    onHover?: (d: HoverData | null) => void;
+    /** Annotation objects */
+    annotations?: Record<string, any>[];
+    /** SVG annotation render function */
+    svgAnnotationRules?: (annotation: Record<string, any>, index: number, context: AnnotationContext) => ReactNode;
+    /** Custom formatter for time axis ticks */
+    tickFormatTime?: (value: number) => string;
+    /** Custom formatter for value axis ticks */
+    tickFormatValue?: (value: number) => string;
+}
+/**
+ * RealtimeBarChart - Simplified wrapper for streaming temporal histograms.
+ *
+ * Wraps RealtimeFrame with `chartType="bar"` and exposes bar styling as
+ * top-level props. Supports both simple and stacked (categorical) modes.
+ *
+ * Edge bins that only partially fall within the visible time window are
+ * rendered at proportionally narrower widths (Datadog-style).
+ *
+ * @example
+ * ```tsx
+ * // Simple histogram
+ * <RealtimeBarChart
+ *   ref={ref}
+ *   binSize={20}
+ *   fill="#007bff"
+ *   enableHover
+ * />
+ *
+ * // Stacked by category
+ * <RealtimeBarChart
+ *   ref={ref}
+ *   binSize={25}
+ *   categoryAccessor="category"
+ *   colors={{ errors: "#dc3545", warnings: "#fd7e14", info: "#007bff" }}
+ *   enableHover
+ * />
+ * ```
+ */
+export declare const RealtimeBarChart: React.ForwardRefExoticComponent<RealtimeBarChartProps & React.RefAttributes<RealtimeFrameHandle>>;

package/dist/charts/realtime/RealtimeLineChart.d.ts

@@ -0,0 +1,78 @@
+import * as React from "react";
+import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, RealtimeFrameHandle, AnnotationContext } from "../../realtime/types";
+import type { ReactNode } from "react";
+export interface RealtimeLineChartProps {
+    /** Chart dimensions as [width, height] */
+    size?: [number, number];
+    /** Chart margins */
+    margin?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+    /** CSS class name */
+    className?: string;
+    /** Direction time flows */
+    arrowOfTime?: ArrowOfTime;
+    /** Data retention strategy */
+    windowMode?: WindowMode;
+    /** Ring buffer capacity */
+    windowSize?: number;
+    /** Controlled data array */
+    data?: Record<string, any>[];
+    /** Time value accessor */
+    timeAccessor?: string | ((d: Record<string, any>) => number);
+    /** Value accessor */
+    valueAccessor?: string | ((d: Record<string, any>) => number);
+    /** Fixed time domain */
+    timeExtent?: [number, number];
+    /** Fixed value domain */
+    valueExtent?: [number, number];
+    /** Extent padding factor */
+    extentPadding?: number;
+    /** Line color */
+    stroke?: string;
+    /** Line width */
+    strokeWidth?: number;
+    /** Dash pattern (e.g. "4,2") */
+    strokeDasharray?: string;
+    /** Show canvas-drawn axes */
+    showAxes?: boolean;
+    /** Background fill color */
+    background?: string;
+    /** Enable hover interaction */
+    enableHover?: boolean | HoverAnnotationConfig;
+    /** Custom tooltip renderer */
+    tooltipContent?: (d: HoverData) => ReactNode;
+    /** Callback on hover */
+    onHover?: (d: HoverData | null) => void;
+    /** Annotation objects */
+    annotations?: Record<string, any>[];
+    /** SVG annotation render function */
+    svgAnnotationRules?: (annotation: Record<string, any>, index: number, context: AnnotationContext) => ReactNode;
+    /** Custom formatter for time axis ticks */
+    tickFormatTime?: (value: number) => string;
+    /** Custom formatter for value axis ticks */
+    tickFormatValue?: (value: number) => string;
+}
+/**
+ * RealtimeLineChart - Simplified wrapper for streaming line charts.
+ *
+ * Wraps RealtimeFrame with `chartType="line"` and exposes stroke/strokeWidth
+ * as top-level props instead of requiring a `lineStyle` object.
+ *
+ * @example
+ * ```tsx
+ * const ref = useRef<RealtimeFrameHandle>(null)
+ *
+ * <RealtimeLineChart
+ *   ref={ref}
+ *   stroke="#007bff"
+ *   strokeWidth={2}
+ *   windowSize={200}
+ *   enableHover
+ * />
+ * ```
+ */
+export declare const RealtimeLineChart: React.ForwardRefExoticComponent<RealtimeLineChartProps & React.RefAttributes<RealtimeFrameHandle>>;

package/dist/charts/realtime/RealtimeSwarmChart.d.ts

@@ -0,0 +1,88 @@
+import * as React from "react";
+import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, RealtimeFrameHandle, AnnotationContext } from "../../realtime/types";
+import type { ReactNode } from "react";
+export interface RealtimeSwarmChartProps {
+    /** Chart dimensions as [width, height] */
+    size?: [number, number];
+    /** Chart margins */
+    margin?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+    /** CSS class name */
+    className?: string;
+    /** Direction time flows */
+    arrowOfTime?: ArrowOfTime;
+    /** Data retention strategy */
+    windowMode?: WindowMode;
+    /** Ring buffer capacity */
+    windowSize?: number;
+    /** Controlled data array */
+    data?: Record<string, any>[];
+    /** Time value accessor */
+    timeAccessor?: string | ((d: Record<string, any>) => number);
+    /** Value accessor */
+    valueAccessor?: string | ((d: Record<string, any>) => number);
+    /** Fixed time domain */
+    timeExtent?: [number, number];
+    /** Fixed value domain */
+    valueExtent?: [number, number];
+    /** Extent padding factor */
+    extentPadding?: number;
+    /** Category accessor for color-coding dots */
+    categoryAccessor?: string | ((d: Record<string, any>) => string);
+    /** Category-to-color map */
+    colors?: Record<string, string>;
+    /** Dot radius */
+    radius?: number;
+    /** Dot fill color (when no categoryAccessor) */
+    fill?: string;
+    /** Dot opacity */
+    opacity?: number;
+    /** Dot stroke color */
+    stroke?: string;
+    /** Dot stroke width */
+    strokeWidth?: number;
+    /** Show canvas-drawn axes */
+    showAxes?: boolean;
+    /** Background fill color */
+    background?: string;
+    /** Enable hover interaction */
+    enableHover?: boolean | HoverAnnotationConfig;
+    /** Custom tooltip renderer */
+    tooltipContent?: (d: HoverData) => ReactNode;
+    /** Callback on hover */
+    onHover?: (d: HoverData | null) => void;
+    /** Annotation objects (including threshold coloring) */
+    annotations?: Record<string, any>[];
+    /** SVG annotation render function */
+    svgAnnotationRules?: (annotation: Record<string, any>, index: number, context: AnnotationContext) => ReactNode;
+    /** Custom formatter for time axis ticks */
+    tickFormatTime?: (value: number) => string;
+    /** Custom formatter for value axis ticks */
+    tickFormatValue?: (value: number) => string;
+}
+/**
+ * RealtimeSwarmChart - Simplified wrapper for streaming dot/swarm charts.
+ *
+ * Wraps RealtimeFrame with `chartType="swarm"` and exposes dot styling as
+ * top-level props. Each data point renders as an individual dot at its
+ * (time, value) coordinates.
+ *
+ * Supports threshold coloring via annotations to recolor dots that cross
+ * value boundaries.
+ *
+ * @example
+ * ```tsx
+ * <RealtimeSwarmChart
+ *   ref={ref}
+ *   radius={4}
+ *   opacity={0.8}
+ *   categoryAccessor="sensor"
+ *   colors={{ sensor1: "#007bff", sensor2: "#28a745" }}
+ * />
+ * ```
+ */
+export declare const RealtimeSwarmChart: React.ForwardRefExoticComponent<RealtimeSwarmChartProps & React.RefAttributes<RealtimeFrameHandle>>;

package/dist/charts/realtime/RealtimeWaterfallChart.d.ts

@@ -0,0 +1,85 @@
+import * as React from "react";
+import type { ArrowOfTime, WindowMode, HoverAnnotationConfig, HoverData, RealtimeFrameHandle, AnnotationContext } from "../../realtime/types";
+import type { ReactNode } from "react";
+export interface RealtimeWaterfallChartProps {
+    /** Chart dimensions as [width, height] */
+    size?: [number, number];
+    /** Chart margins */
+    margin?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+    /** CSS class name */
+    className?: string;
+    /** Direction time flows */
+    arrowOfTime?: ArrowOfTime;
+    /** Data retention strategy */
+    windowMode?: WindowMode;
+    /** Ring buffer capacity */
+    windowSize?: number;
+    /** Controlled data array */
+    data?: Record<string, any>[];
+    /** Time value accessor */
+    timeAccessor?: string | ((d: Record<string, any>) => number);
+    /** Value accessor (positive = gain, negative = loss) */
+    valueAccessor?: string | ((d: Record<string, any>) => number);
+    /** Fixed time domain */
+    timeExtent?: [number, number];
+    /** Fixed value domain */
+    valueExtent?: [number, number];
+    /** Extent padding factor */
+    extentPadding?: number;
+    /** Color for positive (gain) bars */
+    positiveColor?: string;
+    /** Color for negative (loss) bars */
+    negativeColor?: string;
+    /** Connector line stroke color (omit to hide connectors) */
+    connectorStroke?: string;
+    /** Connector line width */
+    connectorWidth?: number;
+    /** Gap between bars in pixels */
+    gap?: number;
+    /** Bar stroke color */
+    stroke?: string;
+    /** Bar stroke width */
+    strokeWidth?: number;
+    /** Show canvas-drawn axes */
+    showAxes?: boolean;
+    /** Background fill color */
+    background?: string;
+    /** Enable hover interaction */
+    enableHover?: boolean | HoverAnnotationConfig;
+    /** Custom tooltip renderer */
+    tooltipContent?: (d: HoverData) => ReactNode;
+    /** Callback on hover */
+    onHover?: (d: HoverData | null) => void;
+    /** Annotation objects */
+    annotations?: Record<string, any>[];
+    /** SVG annotation render function */
+    svgAnnotationRules?: (annotation: Record<string, any>, index: number, context: AnnotationContext) => ReactNode;
+    /** Custom formatter for time axis ticks */
+    tickFormatTime?: (value: number) => string;
+    /** Custom formatter for value axis ticks */
+    tickFormatValue?: (value: number) => string;
+}
+/**
+ * RealtimeWaterfallChart - Simplified wrapper for streaming waterfall charts.
+ *
+ * Wraps RealtimeFrame with `chartType="waterfall"` and exposes waterfall styling
+ * as top-level props. Visualizes cumulative deltas as connected bars rising and
+ * falling from a running baseline.
+ *
+ * @example
+ * ```tsx
+ * <RealtimeWaterfallChart
+ *   ref={ref}
+ *   positiveColor="#28a745"
+ *   negativeColor="#dc3545"
+ *   connectorStroke="#999"
+ *   windowSize={300}
+ * />
+ * ```
+ */
+export declare const RealtimeWaterfallChart: React.ForwardRefExoticComponent<RealtimeWaterfallChartProps & React.RefAttributes<RealtimeFrameHandle>>;

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

@@ -0,0 +1,19 @@
+import * as React from "react";
+export interface ChartErrorProps {
+    /** Component name for the error message */
+    componentName: string;
+    /** The error message to display */
+    message: string;
+    /** Chart width */
+    width: number;
+    /** Chart height */
+    height: number;
+}
+/**
+ * Renders a visible, styled error state inside the chart's dimensions.
+ * Shows the component name, error message, and a hint for developers.
+ *
+ * Designed to be obvious in development but not alarming in production —
+ * uses muted colors that adapt to light/dark backgrounds.
+ */
+export default function ChartError({ componentName, message, width, height, }: ChartErrorProps): React.JSX.Element;

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

@@ -0,0 +1,62 @@
+/**
+ * Predefined color schemes
+ */
+export declare const COLOR_SCHEMES: {
+    category10: any;
+    tableau10: any;
+    set3: any;
+    blues: any;
+    reds: any;
+    greens: any;
+    oranges: any;
+    purples: any;
+    viridis: any;
+    plasma: any;
+};
+/**
+ * Default colors for charts
+ */
+export declare const DEFAULT_COLORS: any;
+/**
+ * Gets a color for a data point based on the colorBy configuration
+ *
+ * @param dataPoint - The data point
+ * @param colorBy - Field name or function to determine color
+ * @param colorScale - Optional custom color scale
+ * @returns Color string
+ *
+ * @example
+ * ```ts
+ * // Using a field name
+ * getColor({category: 'A', value: 10}, 'category', colorScale)
+ *
+ * // Using a function
+ * getColor({value: 10}, d => d.value > 5 ? 'red' : 'blue')
+ * ```
+ */
+export declare function getColor(dataPoint: any, colorBy: string | ((d: any) => string), colorScale?: (v: any) => string): string;
+/**
+ * Creates a color scale function from data
+ *
+ * @param data - Array of data points
+ * @param colorBy - Field name to use for coloring
+ * @param scheme - Color scheme name or custom palette
+ * @returns Color scale function
+ *
+ * @example
+ * ```ts
+ * const colorScale = createColorScale(data, 'category')
+ * const color = colorScale('A') // Returns color for category 'A'
+ * ```
+ */
+export declare function createColorScale(data: Array<Record<string, any>>, colorBy: string, scheme?: string | string[]): (v: string) => string;
+/**
+ * Generates a size function based on sizeBy configuration
+ *
+ * @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
+ */
+export declare function getSize(dataPoint: any, sizeBy: string | ((d: any) => number), sizeRange?: [number, number], domain?: [number, number]): number;