semiotic 2.0.2 → 3.0.0-beta.1

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;

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

@@ -0,0 +1,127 @@
+import * as React from "react";
+import type { XYFrameProps } from "../../types/xyTypes";
+import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+/**
+ * AreaChart component props
+ */
+export interface AreaChartProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps, AxisConfig {
+    /**
+     * Array of data points, grouped by category.
+     * @example
+     * ```ts
+     * // Multiple areas with grouping
+     * [{x: 1, y: 10, category: 'A'}, {x: 2, y: 20, category: 'A'}, {x: 1, y: 15, category: 'B'}]
+     * ```
+     */
+    data: TDatum[];
+    /**
+     * Field name or function to access x values
+     * @default "x"
+     */
+    xAccessor?: ChartAccessor<TDatum, number>;
+    /**
+     * Field name or function to access y values
+     * @default "y"
+     */
+    yAccessor?: ChartAccessor<TDatum, number>;
+    /**
+     * Field name or function to group data into multiple areas
+     * @example
+     * ```ts
+     * areaBy="category"  // Group by category field
+     * areaBy={d => d.group}  // Use function
+     * ```
+     */
+    areaBy?: ChartAccessor<TDatum, string>;
+    /**
+     * Field name in area objects that contains coordinate arrays
+     * Used when data is in area objects format
+     * @default "coordinates"
+     */
+    lineDataAccessor?: string;
+    /**
+     * Field name or function to determine area color
+     * @example
+     * ```ts
+     * colorBy="category"
+     * colorBy={d => d.label}
+     * ```
+     */
+    colorBy?: ChartAccessor<TDatum, string>;
+    /**
+     * Color scheme for categorical data or custom colors array
+     * @default "category10"
+     */
+    colorScheme?: string | string[];
+    /**
+     * Curve interpolation type
+     * @default "monotoneX"
+     */
+    curve?: "linear" | "monotoneX" | "monotoneY" | "step" | "stepAfter" | "stepBefore" | "basis" | "cardinal" | "catmullRom";
+    /**
+     * Area opacity
+     * @default 0.7
+     */
+    areaOpacity?: number;
+    /**
+     * Show line on top of area
+     * @default true
+     */
+    showLine?: boolean;
+    /**
+     * Line stroke width when showLine is true
+     * @default 2
+     */
+    lineWidth?: number;
+    /**
+     * Enable hover annotations
+     * @default true
+     */
+    enableHover?: boolean;
+    /**
+     * Show grid lines
+     * @default false
+     */
+    showGrid?: boolean;
+    /**
+     * Show legend for multiple areas
+     * @default true (when multiple areas)
+     */
+    showLegend?: boolean;
+    /**
+     * Tooltip configuration
+     */
+    tooltip?: TooltipProp;
+    /**
+     * Additional XYFrame props for advanced customization
+     * For full control, consider using XYFrame directly
+     * @see https://semiotic.nteract.io/guides/xy-frame
+     */
+    frameProps?: Partial<Omit<XYFrameProps, "lines" | "size">>;
+}
+/**
+ * AreaChart - Visualize quantities over continuous intervals with overlapping filled areas
+ *
+ * Each series fills from its line down to the baseline. Multiple series overlap
+ * with transparency so all shapes remain visible.
+ *
+ * For stacked areas use {@link StackedAreaChart}.
+ *
+ * @example
+ * ```tsx
+ * <AreaChart
+ *   data={[
+ *     {x: 1, y: 10, category: 'A'},
+ *     {x: 2, y: 20, category: 'A'},
+ *     {x: 1, y: 15, category: 'B'},
+ *     {x: 2, y: 25, category: 'B'}
+ *   ]}
+ *   areaBy="category"
+ *   colorBy="category"
+ *   xLabel="Time"
+ *   yLabel="Value"
+ * />
+ * ```
+ */
+export declare function AreaChart<TDatum extends Record<string, any> = Record<string, any>>(props: AreaChartProps<TDatum>): React.JSX.Element;

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

@@ -0,0 +1,157 @@
+import * as React from "react";
+import type { XYFrameProps } from "../../types/xyTypes";
+import type { BaseChartProps, AxisConfig, ChartAccessor } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+/**
+ * BubbleChart component props
+ */
+export interface BubbleChartProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps, AxisConfig {
+    /**
+     * Array of data points. Each point should have x, y, and size properties.
+     * @example
+     * ```ts
+     * [{x: 1, y: 10, size: 50, category: 'A'}, {x: 2, y: 20, size: 30, category: 'B'}]
+     * ```
+     */
+    data: TDatum[];
+    /**
+     * Field name or function to access x values
+     * @default "x"
+     */
+    xAccessor?: ChartAccessor<TDatum, number>;
+    /**
+     * Field name or function to access y values
+     * @default "y"
+     */
+    yAccessor?: ChartAccessor<TDatum, number>;
+    /**
+     * Field name or function to determine bubble size (required)
+     * @example
+     * ```ts
+     * sizeBy="population"
+     * sizeBy={d => Math.sqrt(d.value)}
+     * ```
+     */
+    sizeBy: ChartAccessor<TDatum, number>;
+    /**
+     * Min and max radius for bubbles
+     * @default [5, 40]
+     */
+    sizeRange?: [number, number];
+    /**
+     * Field name or function to determine bubble color
+     * @example
+     * ```ts
+     * colorBy="category"
+     * colorBy={d => d.value > 10 ? 'red' : 'blue'}
+     * ```
+     */
+    colorBy?: ChartAccessor<TDatum, string>;
+    /**
+     * Color scheme for categorical data or custom colors array
+     * @default "category10"
+     */
+    colorScheme?: string | string[];
+    /**
+     * Bubble opacity
+     * @default 0.6
+     */
+    bubbleOpacity?: number;
+    /**
+     * Bubble stroke width
+     * @default 1
+     */
+    bubbleStrokeWidth?: number;
+    /**
+     * Bubble stroke color
+     * @default "white"
+     */
+    bubbleStrokeColor?: string;
+    /**
+     * 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 XYFrame props for advanced customization
+     * For full control, consider using XYFrame directly
+     * @see https://semiotic.nteract.io/guides/xy-frame
+     */
+    frameProps?: Partial<Omit<XYFrameProps, "points" | "size">>;
+}
+/**
+ * BubbleChart - Visualize three dimensions of data using x, y, and size
+ *
+ * A simplified wrapper around XYFrame for creating bubble charts. Perfect for
+ * showing relationships between three continuous variables or comparing
+ * magnitudes across categories.
+ *
+ * @example
+ * ```tsx
+ * // Simple bubble chart
+ * <BubbleChart
+ *   data={[
+ *     {x: 1, y: 10, size: 50, name: 'A'},
+ *     {x: 2, y: 20, size: 30, name: 'B'},
+ *     {x: 3, y: 15, size: 70, name: 'C'}
+ *   ]}
+ *   sizeBy="size"
+ *   xLabel="Time"
+ *   yLabel="Value"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With color encoding
+ * <BubbleChart
+ *   data={data}
+ *   sizeBy="population"
+ *   colorBy="continent"
+ *   sizeRange={[5, 50]}
+ *   bubbleOpacity={0.7}
+ *   xLabel="GDP per Capita"
+ *   yLabel="Life Expectancy"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Advanced: Override XYFrame props
+ * <BubbleChart
+ *   data={data}
+ *   sizeBy="value"
+ *   frameProps={{
+ *     customPointMark: ({ d }) => <circle r={d.r} fill="gold" />
+ *   }}
+ * />
+ * ```
+ *
+ * @remarks
+ * This component wraps {@link XYFrame} with sensible defaults for bubble charts.
+ * For more advanced features like custom marks, annotations, or complex interactions,
+ * use XYFrame directly.
+ *
+ * **Breadcrumb to advanced usage:**
+ * - Use the `frameProps` prop to pass any XYFrame prop
+ * - See XYFrame documentation: https://semiotic.nteract.io/guides/xy-frame
+ * - All XYFrame props are available via `frameProps`
+ *
+ * @param props - BubbleChart configuration
+ * @returns Rendered bubble chart
+ */
+export declare function BubbleChart<TDatum extends Record<string, any> = Record<string, any>>(props: BubbleChartProps<TDatum>): React.JSX.Element;

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

@@ -0,0 +1,153 @@
+import * as React from "react";
+import type { XYFrameProps } from "../../types/xyTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+/**
+ * Heatmap component props
+ */
+export interface HeatmapProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
+    /**
+     * Array of data points with x, y, and value properties.
+     * @example
+     * ```ts
+     * [{x: 1, y: 1, value: 10}, {x: 1, y: 2, value: 20}, {x: 2, y: 1, value: 15}]
+     * ```
+     */
+    data: TDatum[];
+    /**
+     * Field name or function to access x values
+     * @default "x"
+     */
+    xAccessor?: ChartAccessor<TDatum, number>;
+    /**
+     * Field name or function to access y values
+     * @default "y"
+     */
+    yAccessor?: ChartAccessor<TDatum, number>;
+    /**
+     * Field name or function to access cell values
+     * @default "value"
+     */
+    valueAccessor?: ChartAccessor<TDatum, number>;
+    /**
+     * 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;
+    /**
+     * Color scheme for the heatmap
+     * @default "blues"
+     */
+    colorScheme?: "blues" | "reds" | "greens" | "viridis" | "custom";
+    /**
+     * Custom color scale (used when colorScheme is "custom")
+     * @example
+     * ```ts
+     * customColorScale={scaleSequential(interpolatePlasma).domain([0, 100])}
+     * ```
+     */
+    customColorScale?: any;
+    /**
+     * Show values in cells
+     * @default false
+     */
+    showValues?: boolean;
+    /**
+     * Format function for cell value labels
+     */
+    valueFormat?: (d: number) => string;
+    /**
+     * Cell border color
+     * @default "#fff"
+     */
+    cellBorderColor?: string;
+    /**
+     * Cell border width
+     * @default 1
+     */
+    cellBorderWidth?: number;
+    /**
+     * Enable hover annotations
+     * @default true
+     */
+    enableHover?: boolean;
+    /**
+     * Tooltip configuration
+     */
+    tooltip?: TooltipProp;
+    /**
+     * Additional XYFrame props for advanced customization
+     * For full control, consider using XYFrame directly
+     * @see https://semiotic.nteract.io/guides/xy-frame
+     */
+    frameProps?: Partial<Omit<XYFrameProps, "summaries" | "size">>;
+}
+/**
+ * Heatmap - Visualize matrix data with color-encoded cells
+ *
+ * A simplified wrapper around XYFrame for creating heatmaps. Perfect for
+ * showing patterns, correlations, and distributions in 2D data.
+ *
+ * @example
+ * ```tsx
+ * // Simple heatmap
+ * <Heatmap
+ *   data={[
+ *     {x: 1, y: 1, value: 10},
+ *     {x: 1, y: 2, value: 20},
+ *     {x: 2, y: 1, value: 15},
+ *     {x: 2, y: 2, value: 25}
+ *   ]}
+ *   xLabel="Time"
+ *   yLabel="Category"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom color scheme and value labels
+ * <Heatmap
+ *   data={data}
+ *   colorScheme="viridis"
+ *   showValues={true}
+ *   valueFormat={d => d.toFixed(1)}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Advanced: Custom color scale
+ * <Heatmap
+ *   data={data}
+ *   colorScheme="custom"
+ *   customColorScale={
+ *     scaleSequential(interpolatePlasma).domain([0, 100])
+ *   }
+ * />
+ * ```
+ *
+ * @remarks
+ * This component wraps {@link XYFrame} with sensible defaults for heatmaps.
+ * For more advanced features like hexbins, contours, or custom summaries,
+ * use XYFrame directly.
+ *
+ * **Breadcrumb to advanced usage:**
+ * - Use the `frameProps` prop to pass any XYFrame prop
+ * - See XYFrame documentation: https://semiotic.nteract.io/guides/xy-frame
+ * - All XYFrame props are available via `frameProps`
+ *
+ * @param props - Heatmap configuration
+ * @returns Rendered heatmap
+ */
+export declare function Heatmap<TDatum extends Record<string, any> = Record<string, any>>(props: HeatmapProps<TDatum>): React.JSX.Element;