semiotic 2.0.3 → 3.0.0-beta.1

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;

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

@@ -0,0 +1,82 @@
+/**
+ * Format number with specified format string
+ *
+ * @param value - Number to format
+ * @param formatString - D3 format string (e.g., ".2f", ",.0f", ".1%")
+ * @returns Formatted string
+ *
+ * @see https://github.com/d3/d3-format#format for format string options
+ */
+export declare function formatNumber(value: number, formatString?: string): string;
+/**
+ * Format date with specified format string
+ *
+ * @param value - Date to format
+ * @param formatString - D3 time format string (e.g., "%Y-%m-%d", "%b %d")
+ * @returns Formatted string
+ *
+ * @see https://github.com/d3/d3-time-format#timeFormat for format string options
+ */
+export declare function formatDate(value: Date | number | string, formatString?: string): string;
+/**
+ * Creates a formatting function based on the type
+ *
+ * @param type - Type of formatting: 'number', 'date', 'percent', or 'currency'
+ * @param options - Optional configuration for the formatter
+ * @returns Formatting function
+ *
+ * @example
+ * ```ts
+ * const fmt = formatAxis('number', { decimals: 2 })
+ * fmt(1234.567) // "1,234.57"
+ *
+ * const dateFmt = formatAxis('date', { format: '%b %Y' })
+ * dateFmt(new Date()) // "Jan 2024"
+ * ```
+ */
+export declare function formatAxis(type?: "number" | "date" | "percent" | "currency", options?: {
+    decimals?: number;
+    format?: string;
+    currency?: string;
+}): (d: any) => string;
+/**
+ * Creates a tooltip content generator
+ *
+ * @param fields - Array of field names to display
+ * @param formatters - Optional map of field names to formatting functions
+ * @param labels - Optional map of field names to display labels
+ * @returns React element generator function
+ *
+ * @example
+ * ```ts
+ * const tooltip = createTooltip(
+ *   ['category', 'value'],
+ *   { value: d => formatNumber(d, ',.2f') },
+ *   { category: 'Category', value: 'Value' }
+ * )
+ * ```
+ */
+export declare function createTooltip(fields: string[], formatters?: Record<string, (v: any) => string>, labels?: Record<string, string>): (d: any) => JSX.Element;
+/**
+ * Formats large numbers with K/M/B suffixes
+ *
+ * @param value - Number to format
+ * @param decimals - Number of decimal places
+ * @returns Formatted string with suffix
+ *
+ * @example
+ * ```ts
+ * formatLargeNumber(1234) // "1.2K"
+ * formatLargeNumber(1234567) // "1.2M"
+ * formatLargeNumber(1234567890) // "1.2B"
+ * ```
+ */
+export declare function formatLargeNumber(value: number, decimals?: number): string;
+/**
+ * Truncates text to specified length with ellipsis
+ *
+ * @param text - Text to truncate
+ * @param maxLength - Maximum length before truncation
+ * @returns Truncated text
+ */
+export declare function truncateText(text: string, maxLength?: number): string;

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

@@ -0,0 +1,20 @@
+import type { Accessor } from "./types";
+/**
+ * Default fill color used when no colorBy is specified
+ */
+export declare const DEFAULT_COLOR = "#007bff";
+/**
+ * Resolve an accessor (string key or function) into a function.
+ * Used across chart components to normalize `valueAccessor`, `categoryAccessor`, etc.
+ */
+export declare function resolveAccessor<T = any>(accessor: string | ((d: Record<string, any>, i?: number) => T)): (d: Record<string, any>) => T;
+/**
+ * Hook to create a color scale from data and colorBy configuration.
+ * Returns undefined when colorBy is absent or is a function accessor.
+ */
+export declare function useColorScale(data: Array<Record<string, any>>, colorBy: Accessor<string> | undefined, colorScheme?: string | string[]): ((v: string) => string) | undefined;
+/**
+ * Hook to sort data by a value accessor.
+ * Used by BarChart and DotPlot.
+ */
+export declare function useSortedData(data: Array<Record<string, any>>, sort: boolean | "asc" | "desc" | ((a: Record<string, any>, b: Record<string, any>) => number), valueAccessor: Accessor<number>): Array<Record<string, any>>;

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

@@ -0,0 +1,32 @@
+import type { Accessor } from "./types";
+/**
+ * Create a legend configuration for HOC components
+ *
+ * @param data - Array of data points
+ * @param colorBy - Field or function to determine color categories
+ * @param colorScale - Optional d3 color scale function
+ * @param getColor - Function to get color for a data point
+ * @param strokeColor - Optional stroke color for legend items
+ * @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 }: {
+    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;
+}): {
+    legendGroups: {
+        styleFn: (d: {
+            color: string;
+        }) => Record<string, string | number>;
+        type: "fill";
+        items: {
+            label: string;
+            color: string;
+        }[];
+        label: string;
+    }[];
+};

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

@@ -0,0 +1,58 @@
+import type { MarginType } from "../../types/generalTypes";
+/**
+ * Base props shared across all chart components
+ */
+export interface BaseChartProps {
+    /** Chart width in pixels. Default: 600 */
+    width?: number;
+    /** Chart height in pixels. Default: 400 */
+    height?: number;
+    /** Margin around the chart. Can be number (same on all sides) or object specifying each side */
+    margin?: MarginType;
+    /** CSS class name for the chart container */
+    className?: string;
+    /** Chart title displayed at the top */
+    title?: string;
+}
+/**
+ * Axis configuration props
+ */
+export interface AxisConfig {
+    /** Label for the x-axis */
+    xLabel?: string;
+    /** Label for the y-axis */
+    yLabel?: string;
+    /** Format function for x-axis tick labels */
+    xFormat?: (d: any) => string;
+    /** Format function for y-axis tick labels */
+    yFormat?: (d: any) => string;
+}
+/**
+ * Accessor type - can be a property name or a function
+ * @deprecated Use DataAccessor from generalTypes for generic type safety
+ */
+export type Accessor<T = any> = string | ((d: any, i?: number) => T);
+/**
+ * Generic accessor type that provides autocomplete when TDatum is specified
+ */
+export type ChartAccessor<TDatum, T> = (keyof TDatum & string) | ((d: TDatum, i?: number) => T);
+/**
+ * Color configuration
+ */
+export interface ColorConfig {
+    /** Field name or function to determine color */
+    colorBy?: Accessor<string>;
+    /** Color scheme name (e.g., "blues", "category10") */
+    colorScheme?: string;
+    /** Custom color palette */
+    colors?: string[];
+}
+/**
+ * Size configuration
+ */
+export interface SizeConfig {
+    /** Field name or function to determine size */
+    sizeBy?: Accessor<number>;
+    /** Min and max size range */
+    sizeRange?: [number, number];
+}

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

@@ -0,0 +1,41 @@
+/**
+ * Validates chart data and accessors at render time.
+ * Returns null if data is valid, or an error message string if not.
+ *
+ * Validation is intentionally lightweight — it checks the first data point
+ * to catch common mistakes (wrong field names, missing data) without
+ * iterating the entire dataset.
+ */
+type AccessorLike = string | ((...args: any[]) => any);
+interface ArrayDataValidation {
+    componentName: string;
+    data: any[] | undefined | null;
+    accessors?: Record<string, AccessorLike | undefined>;
+    requiredProps?: Record<string, any>;
+}
+interface ObjectDataValidation {
+    componentName: string;
+    data: any | undefined | null;
+    dataLabel?: string;
+}
+interface NetworkDataValidation {
+    componentName: string;
+    nodes?: any[] | undefined | null;
+    edges?: any[] | undefined | null;
+    nodesRequired?: boolean;
+    edgesRequired?: boolean;
+    accessors?: Record<string, AccessorLike | undefined>;
+}
+/**
+ * Validate array-based chart data (LineChart, BarChart, Scatterplot, etc.)
+ */
+export declare function validateArrayData({ componentName, data, accessors, requiredProps, }: ArrayDataValidation): string | null;
+/**
+ * Validate object/hierarchical data (TreeDiagram, Treemap, CirclePack)
+ */
+export declare function validateObjectData({ componentName, data, dataLabel, }: ObjectDataValidation): string | null;
+/**
+ * Validate network data (ForceDirectedGraph, ChordDiagram, SankeyDiagram)
+ */
+export declare function validateNetworkData({ componentName, nodes, edges, nodesRequired, edgesRequired, accessors, }: NetworkDataValidation): string | null;
+export {};

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

@@ -0,0 +1,18 @@
+/**
+ * Static props validation for AI code-generation pipelines.
+ *
+ * Validates component name, required props, prop types, enum values,
+ * unknown props (typo detection), and data shape via the existing
+ * validateArrayData / validateObjectData / validateNetworkData helpers.
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Validate props for a Semiotic HOC chart component.
+ *
+ * Checks: component name, required props, prop types, enum values,
+ * unknown prop names (typo detection), and data shape + accessor validity.
+ */
+export declare function validateProps(componentName: string, props: Record<string, any>): ValidationResult;