semiotic 2.0.3 → 3.0.0-beta.1

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;

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

@@ -0,0 +1,193 @@
+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";
+/**
+ * LineChart component props
+ */
+export interface LineChartProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps, AxisConfig {
+    /**
+     * Array of data points or array of line objects with coordinates.
+     * @example
+     * ```ts
+     * // Simple format (single line)
+     * [{x: 1, y: 10}, {x: 2, y: 20}]
+     *
+     * // Multiple lines with grouping
+     * [{x: 1, y: 10, series: 'A'}, {x: 2, y: 20, series: 'A'}, {x: 1, y: 15, series: 'B'}]
+     *
+     * // Line objects format
+     * [{label: 'Series A', coordinates: [{x: 1, y: 10}, {x: 2, y: 20}]}]
+     * ```
+     */
+    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 lines
+     * @example
+     * ```ts
+     * lineBy="series"  // Group by series field
+     * lineBy={d => d.category}  // Use function
+     * ```
+     */
+    lineBy?: ChartAccessor<TDatum, string>;
+    /**
+     * Field name in line objects that contains coordinate arrays
+     * Used when data is in line objects format
+     * @default "coordinates"
+     */
+    lineDataAccessor?: string;
+    /**
+     * Field name or function to determine line color
+     * @example
+     * ```ts
+     * colorBy="series"
+     * 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 "linear"
+     */
+    curve?: "linear" | "monotoneX" | "monotoneY" | "step" | "stepAfter" | "stepBefore" | "basis" | "cardinal" | "catmullRom";
+    /**
+     * Show points on the line
+     * @default false
+     */
+    showPoints?: boolean;
+    /**
+     * Point radius when showPoints is true
+     * @default 3
+     */
+    pointRadius?: number;
+    /**
+     * Fill area under the line
+     * @default false
+     */
+    fillArea?: boolean;
+    /**
+     * Area opacity when fillArea is true
+     * @default 0.3
+     */
+    areaOpacity?: number;
+    /**
+     * Line stroke width
+     * @default 2
+     */
+    lineWidth?: number;
+    /**
+     * Enable hover annotations
+     * @default true
+     */
+    enableHover?: boolean;
+    /**
+     * Show grid lines
+     * @default false
+     */
+    showGrid?: boolean;
+    /**
+     * Show legend for multiple lines
+     * @default true (when multiple lines)
+     */
+    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">>;
+}
+/**
+ * LineChart - Visualize trends and time series data with lines
+ *
+ * A simplified wrapper around XYFrame for creating line charts. Perfect for
+ * showing trends, comparisons, and temporal patterns in your data.
+ *
+ * @example
+ * ```tsx
+ * // Simple line chart
+ * <LineChart
+ *   data={[
+ *     {x: 1, y: 10},
+ *     {x: 2, y: 20},
+ *     {x: 3, y: 15}
+ *   ]}
+ *   xLabel="Time"
+ *   yLabel="Value"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple lines with grouping
+ * <LineChart
+ *   data={[
+ *     {x: 1, y: 10, series: 'A'},
+ *     {x: 2, y: 20, series: 'A'},
+ *     {x: 1, y: 15, series: 'B'},
+ *     {x: 2, y: 25, series: 'B'}
+ *   ]}
+ *   lineBy="series"
+ *   colorBy="series"
+ *   xLabel="Time"
+ *   yLabel="Value"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Area chart with custom curve
+ * <LineChart
+ *   data={data}
+ *   curve="monotoneX"
+ *   fillArea={true}
+ *   areaOpacity={0.3}
+ *   showPoints={true}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Advanced: Override XYFrame props
+ * <LineChart
+ *   data={data}
+ *   frameProps={{
+ *     lineType: { type: "line", interpolator: d3.curveCardinal },
+ *     customLineMark: ({ d }) => <path stroke="red" />
+ *   }}
+ * />
+ * ```
+ *
+ * @remarks
+ * This component wraps {@link XYFrame} with sensible defaults for line 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 - LineChart configuration
+ * @returns Rendered line chart
+ */
+export declare function LineChart<TDatum extends Record<string, any> = Record<string, any>>(props: LineChartProps<TDatum>): React.JSX.Element;

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

@@ -0,0 +1,50 @@
+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";
+/**
+ * Scatterplot component props
+ */
+export interface ScatterplotProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps, AxisConfig {
+    /** Array of data points. Each point should have x and y properties. */
+    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 point color */
+    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 */
+    sizeBy?: ChartAccessor<TDatum, number>;
+    /** Min and max radius for points @default [3, 15] */
+    sizeRange?: [number, number];
+    /** Default point radius when sizeBy is not specified @default 5 */
+    pointRadius?: number;
+    /** Point opacity @default 0.8 */
+    pointOpacity?: 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 XYFrame props for advanced customization */
+    frameProps?: Partial<Omit<XYFrameProps, "points" | "size">>;
+}
+/**
+ * Scatterplot - Visualize relationships between two continuous variables
+ *
+ * @example
+ * ```tsx
+ * <Scatterplot
+ *   data={[{x: 1, y: 10}, {x: 2, y: 20}]}
+ *   xLabel="Time"
+ *   yLabel="Value"
+ * />
+ * ```
+ */
+export declare function Scatterplot<TDatum extends Record<string, any> = Record<string, any>>(props: ScatterplotProps<TDatum>): React.JSX.Element;