semiotic 2.0.3 → 3.0.0-beta.1

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

@@ -0,0 +1,128 @@
+import * as React from "react";
+import type { OrdinalFrameProps } from "../../types/ordinalTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+/**
+ * DotPlot component props
+ */
+export interface DotPlotProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
+    /**
+     * Array of data points with category and value.
+     * @example
+     * ```ts
+     * [
+     *   {category: 'Item A', value: 25},
+     *   {category: 'Item B', value: 40},
+     *   {category: 'Item C', value: 15}
+     * ]
+     * ```
+     */
+    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 "horizontal"
+     */
+    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 dot color
+     * @example
+     * ```ts
+     * colorBy="type"
+     * colorBy={d => d.value > 20 ? 'high' : 'low'}
+     * ```
+     */
+    colorBy?: ChartAccessor<TDatum, string>;
+    /**
+     * Color scheme for categorical data or custom colors array
+     * @default "category10"
+     */
+    colorScheme?: string | string[];
+    /**
+     * Sort categories by value
+     * @default true
+     * @example
+     * ```ts
+     * sort="asc"  // Ascending
+     * sort="desc"  // Descending
+     * sort={true}  // Descending (default)
+     * sort={(a, b) => a.value - b.value}  // Custom function
+     * ```
+     */
+    sort?: boolean | "asc" | "desc" | ((a: Record<string, any>, b: Record<string, any>) => number);
+    /**
+     * Dot radius
+     * @default 5
+     */
+    dotRadius?: number;
+    /**
+     * Padding between categories (in pixels)
+     * @default 10
+     */
+    categoryPadding?: number;
+    /**
+     * Enable hover annotations
+     * @default true
+     */
+    enableHover?: boolean;
+    /**
+     * Show grid lines
+     * @default true
+     */
+    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">>;
+}
+/**
+ * DotPlot - Visualize categorical data with Cleveland dot plots.
+ *
+ * A simplified wrapper around OrdinalFrame for creating dot plots.
+ *
+ * @example
+ * ```tsx
+ * <DotPlot
+ *   data={[
+ *     {category: 'Item A', value: 25},
+ *     {category: 'Item B', value: 40},
+ *     {category: 'Item C', value: 15}
+ *   ]}
+ *   categoryLabel="Items"
+ *   valueLabel="Value"
+ * />
+ * ```
+ */
+export declare function DotPlot<TDatum extends Record<string, any> = Record<string, any>>(props: DotPlotProps<TDatum>): React.JSX.Element;

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

@@ -0,0 +1,113 @@
+import * as React from "react";
+import type { OrdinalFrameProps } from "../../types/ordinalTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+/**
+ * GroupedBarChart component props
+ */
+export interface GroupedBarChartProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
+    /**
+     * Array of data points with category, group, and value.
+     * @example
+     * ```ts
+     * [
+     *   {category: 'Q1', product: 'A', value: 100},
+     *   {category: 'Q1', product: 'B', value: 150},
+     *   {category: 'Q2', product: 'A', value: 120},
+     *   {category: 'Q2', product: 'B', value: 180}
+     * ]
+     * ```
+     */
+    data: TDatum[];
+    /**
+     * Field name or function to access category values
+     * @default "category"
+     */
+    categoryAccessor?: ChartAccessor<TDatum, string>;
+    /**
+     * Field name or function to access group values (for grouping bars side by side)
+     */
+    groupBy: 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
+     * @default groupBy value
+     */
+    colorBy?: ChartAccessor<TDatum, string>;
+    /**
+     * Color scheme for categorical data or custom colors array
+     * @default "category10"
+     */
+    colorScheme?: string | string[];
+    /**
+     * 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 groups
+     * @default true
+     */
+    showLegend?: boolean;
+    /**
+     * Tooltip configuration
+     */
+    tooltip?: TooltipProp;
+    /**
+     * Additional OrdinalFrame props for advanced customization
+     * For full control, consider using OrdinalFrame directly
+     */
+    frameProps?: Partial<Omit<OrdinalFrameProps, "data" | "size">>;
+}
+/**
+ * GroupedBarChart - Visualize comparisons across categories with side-by-side bars.
+ *
+ * A simplified wrapper around OrdinalFrame using clusterbar type.
+ *
+ * @example
+ * ```tsx
+ * <GroupedBarChart
+ *   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}
+ *   ]}
+ *   groupBy="product"
+ *   categoryLabel="Quarter"
+ *   valueLabel="Sales"
+ * />
+ * ```
+ */
+export declare function GroupedBarChart<TDatum extends Record<string, any> = Record<string, any>>(props: GroupedBarChartProps<TDatum>): React.JSX.Element;

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

@@ -0,0 +1,83 @@
+import * as React from "react";
+import type { OrdinalFrameProps } from "../../types/ordinalTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+/**
+ * PieChart component props
+ */
+export interface PieChartProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
+    /**
+     * Array of data points, one per slice.
+     * @example
+     * ```ts
+     * [{category: 'A', value: 30}, {category: 'B', value: 50}, {category: 'C', value: 20}]
+     * ```
+     */
+    data: TDatum[];
+    /**
+     * Field name or function to access slice labels
+     * @default "category"
+     */
+    categoryAccessor?: ChartAccessor<TDatum, string>;
+    /**
+     * Field name or function to access slice values
+     * @default "value"
+     */
+    valueAccessor?: ChartAccessor<TDatum, number>;
+    /**
+     * Field name or function to determine slice color
+     * @default categoryAccessor
+     */
+    colorBy?: ChartAccessor<TDatum, string>;
+    /**
+     * Color scheme for categorical data or custom colors array
+     * @default "category10"
+     */
+    colorScheme?: string | string[];
+    /**
+     * Starting angle offset in degrees
+     * @default 0
+     */
+    startAngle?: number;
+    /**
+     * Padding between slices (in pixels)
+     * @default 2
+     */
+    slicePadding?: number;
+    /**
+     * Enable hover annotations
+     * @default true
+     */
+    enableHover?: boolean;
+    /**
+     * Show legend
+     * @default true
+     */
+    showLegend?: boolean;
+    /**
+     * Tooltip configuration
+     */
+    tooltip?: TooltipProp;
+    /**
+     * Additional OrdinalFrame props for advanced customization
+     * For full control, consider using OrdinalFrame directly
+     */
+    frameProps?: Partial<Omit<OrdinalFrameProps, "data" | "size">>;
+}
+/**
+ * PieChart - Visualize proportions as slices of a circle.
+ *
+ * A simplified wrapper around OrdinalFrame with radial projection.
+ *
+ * @example
+ * ```tsx
+ * <PieChart
+ *   data={[
+ *     {category: 'A', value: 30},
+ *     {category: 'B', value: 50},
+ *     {category: 'C', value: 20}
+ *   ]}
+ * />
+ * ```
+ */
+export declare function PieChart<TDatum extends Record<string, any> = Record<string, any>>(props: PieChartProps<TDatum>): React.JSX.Element;

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>>;