semiotic 2.0.3 → 3.0.0-beta.1

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

@@ -0,0 +1,181 @@
+import * as React from "react";
+import type { NetworkFrameProps } from "../../types/networkTypes";
+import type { BaseChartProps, ChartAccessor } from "../shared/types";
+import { type TooltipProp } from "../../Tooltip/Tooltip";
+/**
+ * ChordDiagram component props
+ */
+export interface ChordDiagramProps<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: 'Group1'}, {id: 'B', category: 'Group2'}]
+     * ```
+     */
+    nodes?: TNode[];
+    /**
+     * Array of edges with source, target, and value
+     * @example
+     * ```ts
+     * [
+     *   {source: 'A', target: 'B', value: 100},
+     *   {source: 'B', target: 'A', value: 80},
+     *   {source: 'A', target: 'A', value: 50}
+     * ]
+     * ```
+     */
+    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 (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.group}
+     * ```
+     */
+    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
+     * - function: custom coloring function
+     * @default "source"
+     */
+    edgeColorBy?: "source" | "target" | ((d: any) => string);
+    /**
+     * Padding angle between adjacent groups (in radians)
+     * @default 0.01
+     */
+    padAngle?: number;
+    /**
+     * Width of the outer arc (node) in pixels
+     * @default 20
+     */
+    groupWidth?: number;
+    /**
+     * Sort function for groups (nodes) around the circle
+     * @example
+     * ```ts
+     * sortGroups={(a, b) => b.value - a.value}
+     * ```
+     */
+    sortGroups?: (a: any, b: any) => number;
+    /**
+     * Label accessor for nodes
+     * @default Uses nodeIdAccessor
+     */
+    nodeLabel?: ChartAccessor<TNode, string>;
+    /**
+     * Show labels around circumference
+     * @default true
+     */
+    showLabels?: boolean;
+    /**
+     * Enable hover annotations
+     * @default true
+     */
+    enableHover?: boolean;
+    /**
+     * Edge opacity
+     * @default 0.5
+     */
+    edgeOpacity?: 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">>;
+}
+/**
+ * ChordDiagram - Visualize directed relationships with circular chord layout
+ *
+ * A simplified wrapper around NetworkFrame for creating chord diagrams.
+ * Perfect for showing flow and relationships between entities, especially
+ * when there are reciprocal connections and self-loops.
+ *
+ * @example
+ * ```tsx
+ * // Simple chord diagram
+ * <ChordDiagram
+ *   edges={[
+ *     {source: 'A', target: 'B', value: 100},
+ *     {source: 'B', target: 'A', value: 80},
+ *     {source: 'A', target: 'A', value: 50}
+ *   ]}
+ *   colorBy={(d) => d.id}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom styling and padding
+ * <ChordDiagram
+ *   edges={edges}
+ *   nodes={nodes}
+ *   colorBy="category"
+ *   edgeColorBy="source"
+ *   padAngle={0.05}
+ *   groupWidth={30}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With sorting and labels
+ * <ChordDiagram
+ *   edges={edges}
+ *   sortGroups={(a, b) => b.value - a.value}
+ *   nodeLabel="name"
+ *   showLabels={true}
+ * />
+ * ```
+ *
+ * @remarks
+ * This component wraps {@link NetworkFrame} with sensible defaults for chord diagrams.
+ * Chord diagrams work best when there are asymmetric relationships and self-loops.
+ *
+ * **Data Requirements:**
+ * - Edges must have source, target, and value properties
+ * - Self-loops (source === target) are displayed as curved arcs
+ * - Reciprocal edges show the asymmetry in relationships
+ *
+ * **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 - ChordDiagram configuration
+ * @returns Rendered chord diagram
+ */
+export declare function ChordDiagram<TNode extends Record<string, any> = Record<string, any>, TEdge extends Record<string, any> = Record<string, any>>(props: ChordDiagramProps<TNode, TEdge>): React.JSX.Element;

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

@@ -0,0 +1,103 @@
+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";
+/**
+ * CirclePack component props
+ */
+export interface CirclePackProps<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 circles
+     * @default true
+     */
+    showLabels?: boolean;
+    /**
+     * Node label accessor
+     * @default Uses nodeIdAccessor
+     */
+    nodeLabel?: ChartAccessor<TNode, string>;
+    /**
+     * Circle fill opacity (helps see nesting)
+     * @default 0.7
+     */
+    circleOpacity?: 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
+     */
+    frameProps?: Partial<Omit<NetworkFrameProps, "edges" | "size">>;
+}
+/**
+ * CirclePack - Visualize hierarchical data as nested circles.
+ *
+ * A simplified wrapper around NetworkFrame with circlepack layout.
+ * Each circle's area is proportional to its value.
+ *
+ * @example
+ * ```tsx
+ * <CirclePack
+ *   data={{
+ *     name: 'root',
+ *     children: [
+ *       {name: 'A', value: 100},
+ *       {name: 'B', value: 200},
+ *       {name: 'C', value: 150}
+ *     ]
+ *   }}
+ *   colorByDepth
+ * />
+ * ```
+ */
+export declare function CirclePack<TNode extends Record<string, any> = Record<string, any>, TEdge extends Record<string, any> = Record<string, any>>(props: CirclePackProps<TNode, TEdge>): React.JSX.Element;

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;