semiotic 2.0.2 → 3.0.0-beta.1

package/ai/dist/src/components/charts/network/SankeyDiagram.js

@@ -0,0 +1,305 @@
+"use client";
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SankeyDiagram = SankeyDiagram;
+const React = __importStar(require("react"));
+const react_1 = require("react");
+const NetworkFrame_1 = __importDefault(require("../../NetworkFrame"));
+const colorUtils_1 = require("../shared/colorUtils");
+const Tooltip_1 = require("../../Tooltip/Tooltip");
+const hooks_1 = require("../shared/hooks");
+const ChartError_1 = __importDefault(require("../shared/ChartError"));
+const validateChartData_1 = require("../shared/validateChartData");
+const sankeyLayout_1 = require("../../processing/layouts/sankeyLayout");
+/**
+ * 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
+ */
+function SankeyDiagram(props) {
+    const { nodes, edges, width = 800, height = 600, margin = { top: 50, bottom: 50, left: 50, right: 50 }, className, title, sourceAccessor = "source", targetAccessor = "target", valueAccessor = "value", nodeIdAccessor = "id", colorBy, colorScheme = "category10", edgeColorBy = "source", orientation = "horizontal", nodeAlign = "justify", nodePaddingRatio = 0.05, nodeWidth = 15, nodeLabel, showLabels = true, enableHover = true, edgeOpacity = 0.5, edgeSort, tooltip, frameProps = {} } = props;
+    // Safe data defaults (hooks must always run)
+    const safeEdges = edges || [];
+    // Infer nodes from edges if not provided
+    const inferredNodes = (0, react_1.useMemo)(() => {
+        if (nodes && nodes.length > 0)
+            return nodes;
+        const nodeSet = new Set();
+        safeEdges.forEach((edge) => {
+            const sourceId = typeof sourceAccessor === "function"
+                ? sourceAccessor(edge)
+                : edge[sourceAccessor];
+            const targetId = typeof targetAccessor === "function"
+                ? targetAccessor(edge)
+                : edge[targetAccessor];
+            nodeSet.add(sourceId);
+            nodeSet.add(targetId);
+        });
+        return Array.from(nodeSet).map((id) => ({ id }));
+    }, [nodes, safeEdges, sourceAccessor, targetAccessor]);
+    // Create color scale if colorBy is specified
+    const colorScale = (0, hooks_1.useColorScale)(inferredNodes, colorBy, colorScheme);
+    // Node style function
+    const nodeStyle = (0, react_1.useMemo)(() => {
+        return (d) => {
+            const baseStyle = {
+                stroke: "black",
+                strokeWidth: 1
+            };
+            // Apply color
+            if (colorBy) {
+                baseStyle.fill = (0, colorUtils_1.getColor)(d, colorBy, colorScale);
+            }
+            else {
+                // Default color
+                baseStyle.fill = "#4d430c";
+            }
+            return baseStyle;
+        };
+    }, [colorBy, colorScale]);
+    // Edge style function
+    const edgeStyle = (0, react_1.useMemo)(() => {
+        return (d) => {
+            const baseStyle = {
+                stroke: "black",
+                strokeWidth: 0.5,
+                fillOpacity: edgeOpacity,
+                strokeOpacity: 0.3
+            };
+            // Apply color based on edge coloring strategy
+            if (typeof edgeColorBy === "function") {
+                baseStyle.fill = edgeColorBy(d);
+            }
+            else if (edgeColorBy === "source") {
+                if (colorBy && d.source) {
+                    baseStyle.fill = (0, colorUtils_1.getColor)(d.source, colorBy, colorScale);
+                }
+                else if (d.source) {
+                    baseStyle.fill = nodeStyle(d.source).fill;
+                }
+            }
+            else if (edgeColorBy === "target") {
+                if (colorBy && d.target) {
+                    baseStyle.fill = (0, colorUtils_1.getColor)(d.target, colorBy, colorScale);
+                }
+                else if (d.target) {
+                    baseStyle.fill = nodeStyle(d.target).fill;
+                }
+            }
+            else if (edgeColorBy === "gradient") {
+                // For gradient, use a semi-transparent gray
+                // (actual gradients would require SVG gradient definitions)
+                baseStyle.fill = "#999";
+                baseStyle.fillOpacity = edgeOpacity * 0.7;
+            }
+            return baseStyle;
+        };
+    }, [edgeColorBy, colorBy, colorScale, nodeStyle, edgeOpacity]);
+    // Node label function
+    const nodeLabelFn = (0, react_1.useMemo)(() => {
+        if (!showLabels)
+            return undefined;
+        const accessor = nodeLabel || nodeIdAccessor;
+        return (d) => {
+            if (typeof accessor === "function")
+                return accessor(d);
+            return d[accessor];
+        };
+    }, [showLabels, nodeLabel, nodeIdAccessor]);
+    // Build network type configuration
+    const networkType = (0, react_1.useMemo)(() => {
+        const config = {
+            type: "sankey",
+            orient: nodeAlign,
+            direction: orientation === "horizontal" ? undefined : "down",
+            nodePaddingRatio,
+            nodeWidth
+        };
+        if (edgeSort) {
+            config.edgeSort = edgeSort;
+        }
+        return config;
+    }, [nodeAlign, orientation, nodePaddingRatio, nodeWidth, edgeSort]);
+    // Tooltip content renderer for Sankey nodes and edges
+    const renderTooltip = (0, react_1.useMemo)(() => {
+        return (d) => {
+            const isEdge = !!d.edge || (d.source && d.target && !d.degree && d.degree !== 0);
+            if (isEdge) {
+                const sourceId = d.source?.id ?? d.edge?.source?.id ?? "?";
+                const targetId = d.target?.id ?? d.edge?.target?.id ?? "?";
+                const val = d.value ?? d.weight;
+                return (React.createElement("div", { className: "semiotic-tooltip", style: Tooltip_1.defaultTooltipStyle },
+                    React.createElement("div", { style: { fontWeight: "bold" } },
+                        sourceId,
+                        " \u2192 ",
+                        targetId),
+                    val != null && (React.createElement("div", { style: { marginTop: 4 } },
+                        "Value: ",
+                        typeof val === "number" ? val.toLocaleString() : String(val)))));
+            }
+            // Node tooltip
+            const accessor = nodeIdAccessor;
+            const nodeId = typeof accessor === "function"
+                ? accessor(d)
+                : d[accessor] ?? d.id;
+            const val = d.value;
+            return (React.createElement("div", { className: "semiotic-tooltip", style: Tooltip_1.defaultTooltipStyle },
+                React.createElement("div", { style: { fontWeight: "bold" } }, String(nodeId)),
+                val != null && (React.createElement("div", { style: { marginTop: 4 } },
+                    "Total: ",
+                    typeof val === "number" ? val.toLocaleString() : String(val))),
+                d.degree != null && (React.createElement("div", { style: { marginTop: 2 } },
+                    "Degree: ",
+                    d.degree,
+                    d.inDegree != null ? ` (${d.inDegree} in, ${d.outDegree} out)` : ""))));
+        };
+    }, [nodeIdAccessor]);
+    // Use htmlAnnotationRules to handle frame-hover annotations directly.
+    // This is checked before tooltipContent in the annotation pipeline,
+    // ensuring the custom Sankey tooltip always renders.
+    const tooltipFn = typeof tooltip === "function" ? tooltip : renderTooltip;
+    const htmlAnnotationRules = (0, react_1.useMemo)(() => {
+        return ({ d, i, adjustedSize }) => {
+            if (d.type !== "frame-hover")
+                return null;
+            const flipped = adjustedSize && d.x > adjustedSize[0] / 2;
+            const tooltipStyle = {
+                position: "absolute",
+                top: `${d.y}px`
+            };
+            if (flipped) {
+                tooltipStyle.right = `${adjustedSize[0] - d.x}px`;
+            }
+            else {
+                tooltipStyle.left = `${d.x}px`;
+            }
+            return (React.createElement("div", { key: `network-annotation-label-${i}`, className: `annotation annotation-network-label ${d.className || ""}`, style: tooltipStyle }, tooltipFn(d)));
+        };
+    }, [tooltipFn]);
+    // Validate data (after all hooks)
+    const error = (0, validateChartData_1.validateNetworkData)({
+        componentName: "SankeyDiagram",
+        edges,
+        edgesRequired: true,
+    });
+    if (error)
+        return React.createElement(ChartError_1.default, { componentName: "SankeyDiagram", message: error, width: width, height: height });
+    // Build NetworkFrame props
+    const networkFrameProps = {
+        size: [width, height],
+        nodes: inferredNodes,
+        edges: safeEdges,
+        nodeStyle,
+        edgeStyle,
+        nodeIDAccessor: nodeIdAccessor,
+        sourceAccessor,
+        targetAccessor,
+        edgeWidthAccessor: valueAccessor,
+        networkType,
+        hoverAnnotation: enableHover,
+        margin,
+        nodeSizeAccessor: () => 5, // Small size for hover target
+        ...(nodeLabelFn && { nodeLabels: nodeLabelFn }),
+        ...(className && { className }),
+        ...(title && { title }),
+        // Use htmlAnnotationRules for direct tooltip rendering (checked before tooltipContent)
+        htmlAnnotationRules,
+        // Allow frameProps to override defaults
+        transition: true,
+        ...frameProps,
+        _layoutMap: { sankey: sankeyLayout_1.sankeyLayout, flowchart: sankeyLayout_1.sankeyLayout }
+    };
+    return React.createElement(NetworkFrame_1.default, { ...networkFrameProps });
+}

package/ai/dist/src/components/charts/network/TreeDiagram.js

@@ -0,0 +1,268 @@
+"use client";
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TreeDiagram = TreeDiagram;
+const React = __importStar(require("react"));
+const react_1 = require("react");
+const NetworkFrame_1 = __importDefault(require("../../NetworkFrame"));
+const colorUtils_1 = require("../shared/colorUtils");
+const Tooltip_1 = require("../../Tooltip/Tooltip");
+const hooks_1 = require("../shared/hooks");
+const ChartError_1 = __importDefault(require("../shared/ChartError"));
+const validateChartData_1 = require("../shared/validateChartData");
+const hierarchyLayout_1 = require("../../processing/layouts/hierarchyLayout");
+/**
+ * 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
+ */
+function TreeDiagram(props) {
+    const { data, width = 600, height = 600, margin = { top: 50, bottom: 50, left: 50, right: 50 }, className, title, layout = "tree", orientation = "vertical", childrenAccessor = "children", valueAccessor = "value", nodeIdAccessor = "name", colorBy, colorScheme = "category10", colorByDepth = false, edgeStyle = "curve", nodeLabel, showLabels = true, nodeSize = 5, enableHover = true, tooltip, frameProps = {} } = props;
+    // Flatten hierarchy to get all nodes for color scale
+    const allNodes = (0, react_1.useMemo)(() => {
+        if (!data)
+            return [];
+        const nodes = [];
+        const traverse = (node) => {
+            nodes.push(node);
+            const children = typeof childrenAccessor === "function"
+                ? childrenAccessor(node)
+                : node[childrenAccessor];
+            if (children && Array.isArray(children)) {
+                children.forEach(traverse);
+            }
+        };
+        traverse(data);
+        return nodes;
+    }, [data, childrenAccessor]);
+    // Create color scale if colorBy is specified
+    const colorScale = (0, react_1.useMemo)(() => {
+        if (colorByDepth) {
+            // Color by depth level
+            return (0, colorUtils_1.createColorScale)(allNodes.map((_, idx) => ({ depth: idx % 5 })), "depth", colorScheme);
+        }
+        if (!colorBy || typeof colorBy === "function") {
+            return undefined;
+        }
+        const scheme = Array.isArray(colorScheme) ? colorScheme : colorScheme;
+        return (0, colorUtils_1.createColorScale)(allNodes, colorBy, scheme);
+    }, [allNodes, colorBy, colorByDepth, colorScheme]);
+    // Node style function
+    const nodeStyleFn = (0, react_1.useMemo)(() => {
+        return (d) => {
+            const baseStyle = {
+                stroke: "black",
+                strokeWidth: 1
+            };
+            // Apply color
+            if (colorByDepth) {
+                baseStyle.fill = (0, colorUtils_1.getColor)({ depth: d.depth || 0 }, "depth", colorScale);
+            }
+            else if (colorBy) {
+                baseStyle.fill = (0, colorUtils_1.getColor)(d, colorBy, colorScale);
+            }
+            else {
+                // Default color
+                baseStyle.fill = hooks_1.DEFAULT_COLOR;
+            }
+            return baseStyle;
+        };
+    }, [colorBy, colorByDepth, colorScale]);
+    // Edge style function
+    const edgeStyleFn = (0, react_1.useMemo)(() => {
+        return () => ({
+            stroke: "#999",
+            strokeWidth: 1,
+            fill: "none"
+        });
+    }, []);
+    // Build network type configuration
+    const networkType = (0, react_1.useMemo)(() => {
+        const config = {
+            type: layout
+        };
+        // Set projection for tree/cluster layouts
+        if (layout === "tree" || layout === "cluster") {
+            config.projection = orientation;
+        }
+        // For partition layout, radial creates sunburst
+        if (layout === "partition" && orientation === "radial") {
+            config.projection = "radial";
+        }
+        return config;
+    }, [layout, orientation]);
+    // Hierarchy configuration
+    const hierarchyChildren = (0, react_1.useMemo)(() => {
+        if (typeof childrenAccessor === "function") {
+            return childrenAccessor;
+        }
+        return (d) => d[childrenAccessor];
+    }, [childrenAccessor]);
+    const hierarchySum = (0, react_1.useMemo)(() => {
+        // For layouts that need sizing (treemap, circlepack, partition)
+        if (layout === "treemap" ||
+            layout === "circlepack" ||
+            layout === "partition") {
+            if (typeof valueAccessor === "function") {
+                return valueAccessor;
+            }
+            return (d) => d[valueAccessor] || 1;
+        }
+        return undefined;
+    }, [layout, valueAccessor]);
+    // Validate data (after all hooks)
+    const error = (0, validateChartData_1.validateObjectData)({
+        componentName: "TreeDiagram",
+        data,
+    });
+    if (error)
+        return React.createElement(ChartError_1.default, { componentName: "TreeDiagram", message: error, width: width, height: height });
+    if (layout === "treemap") {
+        console.info("TreeDiagram: Consider using the standalone <Treemap> component for treemap visualizations.");
+    }
+    else if (layout === "circlepack") {
+        console.info("TreeDiagram: Consider using the standalone <CirclePack> component for circle packing visualizations.");
+    }
+    // Build NetworkFrame props
+    const networkFrameProps = {
+        size: [width, height],
+        edges: data, // For hierarchical data, pass to edges
+        nodeStyle: nodeStyleFn,
+        edgeStyle: edgeStyleFn,
+        nodeIDAccessor: nodeIdAccessor,
+        networkType,
+        hoverAnnotation: enableHover,
+        margin,
+        nodeSizeAccessor: () => nodeSize,
+        ...(hierarchyChildren && {
+            hierarchyChildren: hierarchyChildren
+        }),
+        ...(hierarchySum && { hierarchySum: hierarchySum }),
+        ...(className && { className }),
+        ...(title && { title }),
+        // Add tooltip support
+        ...(tooltip && { tooltipContent: (0, Tooltip_1.normalizeTooltip)(tooltip) }),
+        // Allow frameProps to override defaults
+        transition: true,
+        ...frameProps,
+        _layoutMap: hierarchyLayout_1.hierarchyLayouts
+    };
+    return React.createElement(NetworkFrame_1.default, { ...networkFrameProps });
+}