semiotic 2.0.3 → 3.0.0-beta.1

package/dist/charts/network/TreeDiagram.d.ts

@@ -0,0 +1,200 @@
+import * as React from "react";
+import type { NetworkFrameProps } from "../../types/networkTypes";
+import type { BaseChartProps, ChartAccessor, Accessor } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+/**
+ * TreeDiagram component props
+ */
+export interface TreeDiagramProps<TNode extends Record<string, any> = Record<string, any>, TEdge extends Record<string, any> = Record<string, any>> extends BaseChartProps {
+    /**
+     * Hierarchical data structure
+     * @example
+     * ```ts
+     * {
+     *   name: 'root',
+     *   children: [
+     *     {name: 'A', children: [{name: 'A1'}, {name: 'A2'}]},
+     *     {name: 'B'}
+     *   ]
+     * }
+     * ```
+     */
+    data: TNode;
+    /**
+     * Tree layout algorithm
+     * - "tree": standard tree layout
+     * - "cluster": cluster (dendrogram) layout
+     * - "partition": partition (icicle/sunburst) layout
+     * - "treemap": treemap layout (@deprecated — use the standalone {@link Treemap} component instead)
+     * - "circlepack": circle packing layout (@deprecated — use the standalone {@link CirclePack} component instead)
+     * @default "tree"
+     */
+    layout?: "tree" | "cluster" | "partition" | "treemap" | "circlepack";
+    /**
+     * Projection orientation
+     * - "vertical": top to bottom
+     * - "horizontal": left to right
+     * - "radial": radial layout (circular)
+     * @default "vertical"
+     */
+    orientation?: "vertical" | "horizontal" | "radial";
+    /**
+     * Field name or function to access children array
+     * @default "children"
+     */
+    childrenAccessor?: ChartAccessor<TNode, TNode[]>;
+    /**
+     * Field name or function to access node value for sizing
+     * Used by treemap and circlepack layouts
+     * @default "value"
+     */
+    valueAccessor?: Accessor<number>;
+    /**
+     * Field name or function to access node identifier
+     * @default "name"
+     */
+    nodeIdAccessor?: ChartAccessor<TNode, string>;
+    /**
+     * Field name or function to determine node color
+     * @example
+     * ```ts
+     * colorBy="category"
+     * colorBy={d => d.depth}
+     * ```
+     */
+    colorBy?: ChartAccessor<TNode, string | number>;
+    /**
+     * Color scheme for nodes or custom colors array
+     * @default "category10"
+     */
+    colorScheme?: string | string[];
+    /**
+     * Color nodes by depth level
+     * @default false
+     */
+    colorByDepth?: boolean;
+    /**
+     * Edge style
+     * - "line": straight lines
+     * - "curve": curved lines
+     * @default "curve"
+     */
+    edgeStyle?: "line" | "curve";
+    /**
+     * Label accessor for nodes
+     * @default Uses nodeIdAccessor
+     */
+    nodeLabel?: ChartAccessor<TNode, string>;
+    /**
+     * Show node labels
+     * @default true
+     */
+    showLabels?: boolean;
+    /**
+     * Node size for tree/cluster layouts
+     * @default 5
+     */
+    nodeSize?: number;
+    /**
+     * Enable hover annotations
+     * @default true
+     */
+    enableHover?: boolean;
+    /**
+     * Tooltip configuration
+     */
+    tooltip?: TooltipProp;
+    /**
+     * Additional NetworkFrame props for advanced customization
+     * For full control, consider using NetworkFrame directly
+     * @see https://semiotic.nteract.io/guides/network-frame
+     */
+    frameProps?: Partial<Omit<NetworkFrameProps, "edges" | "size">>;
+}
+/**
+ * TreeDiagram - Visualize hierarchical data structures
+ *
+ * A simplified wrapper around NetworkFrame for creating tree diagrams.
+ * Perfect for organizational charts, file systems, taxonomies, and
+ * any hierarchical data.
+ *
+ * @example
+ * ```tsx
+ * // Simple tree
+ * <TreeDiagram
+ *   data={{
+ *     name: 'Root',
+ *     children: [
+ *       {name: 'A', children: [{name: 'A1'}, {name: 'A2'}]},
+ *       {name: 'B'}
+ *     ]
+ *   }}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Horizontal cluster (dendrogram)
+ * <TreeDiagram
+ *   data={hierarchicalData}
+ *   layout="cluster"
+ *   orientation="horizontal"
+ *   colorByDepth={true}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Radial tree
+ * <TreeDiagram
+ *   data={hierarchicalData}
+ *   layout="tree"
+ *   orientation="radial"
+ *   colorBy="category"
+ *   nodeSize={8}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Treemap with sizing
+ * <TreeDiagram
+ *   data={hierarchicalData}
+ *   layout="treemap"
+ *   valueAccessor="size"
+ *   colorBy="type"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Circle pack
+ * <TreeDiagram
+ *   data={hierarchicalData}
+ *   layout="circlepack"
+ *   valueAccessor="value"
+ *   colorByDepth={true}
+ * />
+ * ```
+ *
+ * @remarks
+ * This component wraps {@link NetworkFrame} with sensible defaults for tree diagrams.
+ * Different layouts are suited for different use cases:
+ * - **tree/cluster**: Good for organizational structures, phylogenetic trees
+ * - **treemap**: Good for showing proportional sizes (disk usage, budget allocation)
+ * - **partition**: Good for hierarchical proportions (icicle or sunburst charts)
+ * - **circlepack**: Good for nested hierarchies with size encoding
+ *
+ * **Data Requirements:**
+ * - Data must be hierarchical JSON with a children property (or custom accessor)
+ * - For treemap/circlepack, nodes should have a value property for sizing
+ *
+ * **Breadcrumb to advanced usage:**
+ * - Use the `frameProps` prop to pass any NetworkFrame prop
+ * - See NetworkFrame documentation: https://semiotic.nteract.io/guides/network-frame
+ * - All NetworkFrame props are available via `frameProps`
+ *
+ * @param props - TreeDiagram configuration
+ * @returns Rendered tree diagram
+ */
+export declare function TreeDiagram<TNode extends Record<string, any> = Record<string, any>, TEdge extends Record<string, any> = Record<string, any>>(props: TreeDiagramProps<TNode, TEdge>): React.JSX.Element;

package/dist/charts/network/Treemap.d.ts

@@ -0,0 +1,98 @@
+import * as React from "react";
+import type { NetworkFrameProps } from "../../types/networkTypes";
+import type { BaseChartProps, ChartAccessor, Accessor } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+/**
+ * Treemap component props
+ */
+export interface TreemapProps<TNode extends Record<string, any> = Record<string, any>, TEdge extends Record<string, any> = Record<string, any>> extends BaseChartProps {
+    /**
+     * Hierarchical data structure with children and values.
+     * @example
+     * ```ts
+     * {
+     *   name: 'root',
+     *   children: [
+     *     {name: 'A', value: 100},
+     *     {name: 'B', children: [{name: 'B1', value: 50}, {name: 'B2', value: 30}]}
+     *   ]
+     * }
+     * ```
+     */
+    data: TNode;
+    /**
+     * Field name or function to access children array
+     * @default "children"
+     */
+    childrenAccessor?: ChartAccessor<TNode, TNode[]>;
+    /**
+     * Field name or function to access node value for sizing
+     * @default "value"
+     */
+    valueAccessor?: Accessor<number>;
+    /**
+     * Field name or function to access node identifier
+     * @default "name"
+     */
+    nodeIdAccessor?: ChartAccessor<TNode, string>;
+    /**
+     * Field name or function to determine node color
+     */
+    colorBy?: ChartAccessor<TNode, string | number>;
+    /**
+     * Color scheme for nodes or custom colors array
+     * @default "category10"
+     */
+    colorScheme?: string | string[];
+    /**
+     * Color nodes by hierarchy depth level
+     * @default false
+     */
+    colorByDepth?: boolean;
+    /**
+     * Show labels on treemap cells
+     * @default true
+     */
+    showLabels?: boolean;
+    /**
+     * Node label accessor
+     * @default Uses nodeIdAccessor
+     */
+    nodeLabel?: ChartAccessor<TNode, string>;
+    /**
+     * Enable hover annotations
+     * @default true
+     */
+    enableHover?: boolean;
+    /**
+     * Tooltip configuration
+     */
+    tooltip?: TooltipProp;
+    /**
+     * Additional NetworkFrame props for advanced customization
+     * For full control, consider using NetworkFrame directly
+     */
+    frameProps?: Partial<Omit<NetworkFrameProps, "edges" | "size">>;
+}
+/**
+ * Treemap - Visualize hierarchical data as nested rectangles.
+ *
+ * A simplified wrapper around NetworkFrame with treemap layout.
+ * Each rectangle's area is proportional to its value.
+ *
+ * @example
+ * ```tsx
+ * <Treemap
+ *   data={{
+ *     name: 'root',
+ *     children: [
+ *       {name: 'A', value: 100},
+ *       {name: 'B', value: 200},
+ *       {name: 'C', value: 150}
+ *     ]
+ *   }}
+ *   colorBy="name"
+ * />
+ * ```
+ */
+export declare function Treemap<TNode extends Record<string, any> = Record<string, any>, TEdge extends Record<string, any> = Record<string, any>>(props: TreemapProps<TNode, TEdge>): React.JSX.Element;

package/dist/charts/ordinal/BarChart.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";
+/**
+ * BarChart component props
+ */
+export interface BarChartProps<TDatum extends Record<string, any> = Record<string, any>> extends BaseChartProps {
+    /**
+     * Array of data points. Each point should have a category and value.
+     * @example
+     * ```ts
+     * [{category: 'A', value: 10}, {category: 'B', value: 20}]
+     * ```
+     */
+    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 bar color
+     * @example
+     * ```ts
+     * colorBy="category"  // Use category field
+     * colorBy={d => d.value > 10 ? 'green' : 'red'}  // Use function
+     * ```
+     */
+    colorBy?: ChartAccessor<TDatum, string>;
+    /**
+     * Color scheme for categorical data or custom colors array
+     * @default "category10"
+     */
+    colorScheme?: string | string[];
+    /**
+     * Sort bars by value
+     * @default false
+     * @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);
+    /**
+     * Padding between bars (in pixels)
+     * @default 5
+     */
+    barPadding?: 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">>;
+}
+/**
+ * BarChart - Visualize categorical data with bars.
+ *
+ * A simplified wrapper around OrdinalFrame for creating bar charts.
+ *
+ * @example
+ * ```tsx
+ * <BarChart
+ *   data={[
+ *     {category: 'A', value: 10},
+ *     {category: 'B', value: 20},
+ *     {category: 'C', value: 15}
+ *   ]}
+ *   categoryLabel="Category"
+ *   valueLabel="Value"
+ * />
+ * ```
+ */
+export declare function BarChart<TDatum extends Record<string, any> = Record<string, any>>(props: BarChartProps<TDatum>): React.JSX.Element;

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

@@ -0,0 +1,125 @@
+import * as React from "react";
+import type { OrdinalFrameProps } from "../../types/ordinalTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+/**
+ * BoxPlot component props
+ */
+export interface BoxPlotProps<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},
+     *   {category: 'Group A', value: 12},
+     *   {category: 'Group A', value: 15},
+     *   {category: 'Group B', value: 20}
+     * ]
+     * ```
+     */
+    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 box color
+     * @example
+     * ```ts
+     * colorBy="category"
+     * colorBy={d => d.group}
+     * ```
+     */
+    colorBy?: ChartAccessor<TDatum, string>;
+    /**
+     * Color scheme for categorical data or custom colors array
+     * @default "category10"
+     */
+    colorScheme?: string | string[];
+    /**
+     * Show outlier points
+     * @default true
+     */
+    showOutliers?: boolean;
+    /**
+     * Outlier point radius
+     * @default 3
+     */
+    outlierRadius?: 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">>;
+}
+/**
+ * BoxPlot - Visualize statistical distributions with box-and-whisker plots.
+ *
+ * A simplified wrapper around OrdinalFrame for creating box plots.
+ *
+ * @example
+ * ```tsx
+ * <BoxPlot
+ *   data={[
+ *     {category: 'Group A', value: 10},
+ *     {category: 'Group A', value: 12},
+ *     {category: 'Group A', value: 15},
+ *     {category: 'Group A', value: 18},
+ *     {category: 'Group B', value: 20},
+ *     {category: 'Group B', value: 22}
+ *   ]}
+ *   categoryLabel="Group"
+ *   valueLabel="Value"
+ * />
+ * ```
+ */
+export declare function BoxPlot<TDatum extends Record<string, any> = Record<string, any>>(props: BoxPlotProps<TDatum>): React.JSX.Element;

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

@@ -0,0 +1,95 @@
+import * as React from "react";
+import type { OrdinalFrameProps } from "../../types/ordinalTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+/**
+ * DonutChart component props
+ */
+export interface DonutChartProps<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>;
+    /**
+     * Inner radius in pixels. Controls the donut hole size.
+     * @default 60
+     */
+    innerRadius?: number;
+    /**
+     * Content to render in the center of the donut (e.g. a total label)
+     */
+    centerContent?: React.ReactNode;
+    /**
+     * 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">>;
+}
+/**
+ * DonutChart - Visualize proportions as slices of a ring.
+ *
+ * A simplified wrapper around OrdinalFrame with radial projection and
+ * an inner radius to create a donut shape.
+ *
+ * @example
+ * ```tsx
+ * <DonutChart
+ *   data={[
+ *     {category: 'A', value: 30},
+ *     {category: 'B', value: 50},
+ *     {category: 'C', value: 20}
+ *   ]}
+ *   innerRadius={80}
+ *   centerContent={<span>Total: 100</span>}
+ * />
+ * ```
+ */
+export declare function DonutChart<TDatum extends Record<string, any> = Record<string, any>>(props: DonutChartProps<TDatum>): React.JSX.Element;