semiotic 2.0.2 → 3.0.0-beta.1

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

@@ -0,0 +1,192 @@
+import * as React from "react";
+import type { NetworkFrameProps } from "../../types/networkTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+/**
+ * ForceDirectedGraph component props
+ */
+export interface ForceDirectedGraphProps<TNode extends Record<string, any> = Record<string, any>, TEdge extends Record<string, any> = Record<string, any>> extends BaseChartProps {
+    /**
+     * Array of nodes. Each node should have an id property.
+     * @example
+     * ```ts
+     * [{id: 'A', label: 'Node A'}, {id: 'B', label: 'Node B'}]
+     * ```
+     */
+    nodes: TNode[];
+    /**
+     * Array of edges connecting nodes.
+     * @example
+     * ```ts
+     * [{source: 'A', target: 'B'}, {source: 'B', target: 'C'}]
+     * ```
+     */
+    edges: TEdge[];
+    /**
+     * Field name or function to access node IDs
+     * @default "id"
+     */
+    nodeIDAccessor?: ChartAccessor<TNode, string>;
+    /**
+     * Field name or function to access edge source IDs
+     * @default "source"
+     */
+    sourceAccessor?: ChartAccessor<TEdge, string>;
+    /**
+     * Field name or function to access edge target IDs
+     * @default "target"
+     */
+    targetAccessor?: ChartAccessor<TEdge, string>;
+    /**
+     * Field name or function to determine node labels
+     * @example
+     * ```ts
+     * nodeLabel="label"  // Use label field
+     * nodeLabel={d => d.name}  // Use function
+     * ```
+     */
+    nodeLabel?: ChartAccessor<TNode, string>;
+    /**
+     * Field name or function to determine node color
+     * @example
+     * ```ts
+     * colorBy="group"
+     * colorBy={d => d.value > 10 ? 'red' : 'blue'}
+     * ```
+     */
+    colorBy?: ChartAccessor<TNode, string>;
+    /**
+     * Color scheme for categorical data or custom colors array
+     * @default "category10"
+     */
+    colorScheme?: string | string[];
+    /**
+     * Field name, number, or function to determine node size
+     * @example
+     * ```ts
+     * nodeSize={5}  // Fixed size
+     * nodeSize="importance"  // Use field
+     * nodeSize={d => d.connections * 2}  // Use function
+     * ```
+     */
+    nodeSize?: number | ChartAccessor<TNode, number>;
+    /**
+     * Min and max radius for nodes when using dynamic sizing
+     * @default [5, 20]
+     */
+    nodeSizeRange?: [number, number];
+    /**
+     * Field name, number, or function to determine edge width
+     * @default 1
+     */
+    edgeWidth?: number | ChartAccessor<TEdge, number>;
+    /**
+     * Edge color
+     * @default "#999"
+     */
+    edgeColor?: string;
+    /**
+     * Edge opacity
+     * @default 0.6
+     */
+    edgeOpacity?: number;
+    /**
+     * Number of force simulation iterations
+     * @default 300
+     */
+    iterations?: number;
+    /**
+     * Strength of the force simulation
+     * Lower values create looser layouts
+     * @default 0.1
+     */
+    forceStrength?: number;
+    /**
+     * Enable node labels
+     * @default false
+     */
+    showLabels?: boolean;
+    /**
+     * Enable hover annotations
+     * @default true
+     */
+    enableHover?: boolean;
+    /**
+     * Show legend
+     * @default true (when colorBy is specified)
+     */
+    showLegend?: 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, "nodes" | "edges" | "size">>;
+}
+/**
+ * ForceDirectedGraph - Visualize network relationships with force-directed layout
+ *
+ * A simplified wrapper around NetworkFrame for creating force-directed graphs.
+ * Perfect for visualizing connections, communities, and network structures.
+ *
+ * @example
+ * ```tsx
+ * // Simple force-directed graph
+ * <ForceDirectedGraph
+ *   nodes={[
+ *     {id: 'A', label: 'Node A'},
+ *     {id: 'B', label: 'Node B'},
+ *     {id: 'C', label: 'Node C'}
+ *   ]}
+ *   edges={[
+ *     {source: 'A', target: 'B'},
+ *     {source: 'B', target: 'C'}
+ *   ]}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With color and size encoding
+ * <ForceDirectedGraph
+ *   nodes={nodes}
+ *   edges={edges}
+ *   colorBy="group"
+ *   nodeSize="connections"
+ *   nodeSizeRange={[5, 25]}
+ *   showLabels={true}
+ *   iterations={500}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Advanced: Override NetworkFrame props
+ * <ForceDirectedGraph
+ *   nodes={nodes}
+ *   edges={edges}
+ *   frameProps={{
+ *     networkType: { type: "force", iterations: 500, edgeStrength: 2 },
+ *     customNodeIcon: ({ d }) => <circle r={10} fill="gold" />
+ *   }}
+ * />
+ * ```
+ *
+ * @remarks
+ * This component wraps {@link NetworkFrame} with sensible defaults for force-directed graphs.
+ * For more advanced features like custom layouts, hierarchical networks, or complex interactions,
+ * use NetworkFrame directly.
+ *
+ * **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 - ForceDirectedGraph configuration
+ * @returns Rendered force-directed graph
+ */
+export declare function ForceDirectedGraph<TNode extends Record<string, any> = Record<string, any>, TEdge extends Record<string, any> = Record<string, any>>(props: ForceDirectedGraphProps<TNode, TEdge>): React.JSX.Element;

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

@@ -0,0 +1,195 @@
+import * as React from "react";
+import type { NetworkFrameProps } from "../../types/networkTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+/**
+ * SankeyDiagram component props
+ */
+export interface SankeyDiagramProps<TNode extends Record<string, any> = Record<string, any>, TEdge extends Record<string, any> = Record<string, any>> extends BaseChartProps {
+    /**
+     * Array of nodes (optional - will be inferred from edges if not provided)
+     * @example
+     * ```ts
+     * [{id: 'A', category: 'Source'}, {id: 'B', category: 'Target'}]
+     * ```
+     */
+    nodes?: TNode[];
+    /**
+     * Array of edges (links) with source, target, and value
+     * @example
+     * ```ts
+     * [
+     *   {source: 'A', target: 'B', value: 100},
+     *   {source: 'B', target: 'C', value: 80}
+     * ]
+     * ```
+     */
+    edges: TEdge[];
+    /**
+     * Field name or function to access source node identifier
+     * @default "source"
+     */
+    sourceAccessor?: ChartAccessor<TEdge, string>;
+    /**
+     * Field name or function to access target node identifier
+     * @default "target"
+     */
+    targetAccessor?: ChartAccessor<TEdge, string>;
+    /**
+     * Field name or function to access edge value (flow width)
+     * @default "value"
+     */
+    valueAccessor?: ChartAccessor<TEdge, number>;
+    /**
+     * Field name or function to access node identifier
+     * @default "id"
+     */
+    nodeIdAccessor?: ChartAccessor<TNode, string>;
+    /**
+     * Field name or function to determine node color
+     * @example
+     * ```ts
+     * colorBy="category"
+     * colorBy={d => d.type}
+     * ```
+     */
+    colorBy?: ChartAccessor<TNode, string>;
+    /**
+     * Color scheme for nodes or custom colors array
+     * @default "category10"
+     */
+    colorScheme?: string | string[];
+    /**
+     * Edge color strategy
+     * - "source": color edges by source node
+     * - "target": color edges by target node
+     * - "gradient": gradient from source to target
+     * - function: custom coloring function
+     * @default "source"
+     */
+    edgeColorBy?: "source" | "target" | "gradient" | ((d: any) => string);
+    /**
+     * Layout orientation
+     * @default "horizontal"
+     */
+    orientation?: "horizontal" | "vertical";
+    /**
+     * Node alignment strategy
+     * - "justify": spread nodes evenly
+     * - "left": align nodes to the left
+     * - "right": align nodes to the right
+     * - "center": center nodes
+     * @default "justify"
+     */
+    nodeAlign?: "justify" | "left" | "right" | "center";
+    /**
+     * Padding between nodes (ratio of node height)
+     * @default 0.05
+     */
+    nodePaddingRatio?: number;
+    /**
+     * Fixed width of nodes in pixels
+     * @default 15
+     */
+    nodeWidth?: number;
+    /**
+     * Label accessor for nodes
+     * @default Uses nodeIdAccessor
+     */
+    nodeLabel?: ChartAccessor<TNode, string>;
+    /**
+     * Show node labels
+     * @default true
+     */
+    showLabels?: boolean;
+    /**
+     * Enable hover annotations
+     * @default true
+     */
+    enableHover?: boolean;
+    /**
+     * Edge opacity
+     * @default 0.5
+     */
+    edgeOpacity?: number;
+    /**
+     * Sort function for edges
+     * @example
+     * ```ts
+     * edgeSort={(a, b) => b.value - a.value}
+     * ```
+     */
+    edgeSort?: (a: any, b: any) => number;
+    /**
+     * 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">>;
+}
+/**
+ * SankeyDiagram - Visualize flow and magnitude of movement between nodes
+ *
+ * A simplified wrapper around NetworkFrame for creating Sankey diagrams.
+ * Perfect for showing material, energy, cost, or any other quantity
+ * flowing through a system.
+ *
+ * @example
+ * ```tsx
+ * // Simple Sankey diagram
+ * <SankeyDiagram
+ *   edges={[
+ *     {source: 'A', target: 'B', value: 100},
+ *     {source: 'A', target: 'C', value: 50},
+ *     {source: 'B', target: 'D', value: 80}
+ *   ]}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom styling and orientation
+ * <SankeyDiagram
+ *   edges={edges}
+ *   nodes={nodes}
+ *   colorBy="category"
+ *   edgeColorBy="gradient"
+ *   orientation="vertical"
+ *   nodeAlign="center"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With sorting and padding
+ * <SankeyDiagram
+ *   edges={edges}
+ *   nodeWidth={20}
+ *   nodePaddingRatio={0.1}
+ *   edgeSort={(a, b) => b.value - a.value}
+ * />
+ * ```
+ *
+ * @remarks
+ * This component wraps {@link NetworkFrame} with sensible defaults for Sankey diagrams.
+ * Sankey diagrams are used for directed acyclic graphs (DAGs).
+ *
+ * **Data Requirements:**
+ * - Edges must have source, target, and value properties
+ * - Graph should be acyclic (no cycles)
+ * - If cycles are detected, consider using a force-directed layout instead
+ *
+ * **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`
+ * - For circular Sankey diagrams, use the `customSankey` prop via frameProps
+ *
+ * @param props - SankeyDiagram configuration
+ * @returns Rendered Sankey diagram
+ */
+export declare function SankeyDiagram<TNode extends Record<string, any> = Record<string, any>, TEdge extends Record<string, any> = Record<string, any>>(props: SankeyDiagramProps<TNode, TEdge>): React.JSX.Element;

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;