semiotic 2.0.3 → 3.0.0-beta.2

package/ai/dist/src/components/charts/xy/Heatmap.js

@@ -0,0 +1,235 @@
+"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.Heatmap = Heatmap;
+const React = __importStar(require("react"));
+const react_1 = require("react");
+const d3_scale_1 = require("d3-scale");
+const d3_scale_chromatic_1 = require("d3-scale-chromatic");
+const StreamXYFrame_1 = __importDefault(require("../../stream/StreamXYFrame"));
+const hooks_1 = require("../shared/hooks");
+const Tooltip_1 = require("../../Tooltip/Tooltip");
+const tooltipUtils_1 = require("../shared/tooltipUtils");
+const ChartError_1 = __importDefault(require("../shared/ChartError"));
+const validateChartData_1 = require("../shared/validateChartData");
+const selectionUtils_1 = require("../shared/selectionUtils");
+const useSelection_1 = require("../../store/useSelection");
+const useSelection_2 = require("../../store/useSelection");
+/**
+ * Heatmap - Visualize matrix data with color-encoded cells
+ *
+ * A simplified wrapper around StreamXYFrame for creating heatmaps. Perfect for
+ * showing patterns, correlations, and distributions in 2D data.
+ *
+ * @example
+ * ```tsx
+ * // Simple heatmap
+ * <Heatmap
+ *   data={[
+ *     {x: 1, y: 1, value: 10},
+ *     {x: 1, y: 2, value: 20},
+ *     {x: 2, y: 1, value: 15},
+ *     {x: 2, y: 2, value: 25}
+ *   ]}
+ *   xLabel="Time"
+ *   yLabel="Category"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom color scheme and value labels
+ * <Heatmap
+ *   data={data}
+ *   colorScheme="viridis"
+ *   showValues={true}
+ *   valueFormat={d => d.toFixed(1)}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Advanced: Custom color scale
+ * <Heatmap
+ *   data={data}
+ *   colorScheme="custom"
+ *   customColorScale={
+ *     scaleSequential(interpolatePlasma).domain([0, 100])
+ *   }
+ * />
+ * ```
+ *
+ * @remarks
+ * This component wraps {@link StreamXYFrame} with sensible defaults for heatmaps.
+ * For more advanced features like hexbins, contours, or custom summaries,
+ * use StreamXYFrame directly.
+ *
+ * **Breadcrumb to advanced usage:**
+ * - Use the `frameProps` prop to pass any StreamXYFrame prop
+ * - See StreamXYFrame documentation: https://semiotic.nteract.io/guides/xy-frame
+ * - All StreamXYFrame props are available via `frameProps`
+ *
+ * @param props - Heatmap configuration
+ * @returns Rendered heatmap
+ */
+function Heatmap(props) {
+    const { data, width = 600, height = 400, margin = { top: 50, bottom: 60, left: 70, right: 80 }, className, title, xAccessor = "x", yAccessor = "y", valueAccessor = "value", xLabel, yLabel, xFormat, yFormat, colorScheme = "blues", customColorScale, showValues = false, valueFormat, cellBorderColor = "#fff", cellBorderWidth = 1, enableHover = true, tooltip, frameProps = {}, selection, linkedHover } = props;
+    const safeData = data || [];
+    // ── Selection hooks (always called, conditional logic inside) ──────────
+    const hoverConfig = (0, selectionUtils_1.normalizeLinkedHover)(linkedHover, []);
+    const selectionHook = (0, useSelection_1.useSelection)({
+        name: selection?.name || "__unused__",
+        fields: []
+    });
+    const linkedHoverHook = (0, useSelection_2.useLinkedHover)({
+        name: hoverConfig?.name || "hover",
+        fields: hoverConfig?.fields || []
+    });
+    // Only use the hooks when the corresponding props are provided
+    const activeSelectionHook = selection ? { isActive: selectionHook.isActive, predicate: selectionHook.predicate } : null;
+    // ── Core chart logic ───────────────────────────────────────────────────
+    // Get value accessor function
+    const getValueFn = (0, react_1.useMemo)(() => {
+        return typeof valueAccessor === "function"
+            ? (d) => valueAccessor(d)
+            : (d) => d[valueAccessor];
+    }, [valueAccessor]);
+    // Calculate value domain
+    const valueDomain = (0, react_1.useMemo)(() => {
+        const values = safeData.map(getValueFn);
+        return [Math.min(...values), Math.max(...values)];
+    }, [safeData, getValueFn]);
+    // Create color scale
+    const colorScale = (0, react_1.useMemo)(() => {
+        if (colorScheme === "custom" && customColorScale) {
+            return customColorScale;
+        }
+        const interpolators = {
+            blues: d3_scale_chromatic_1.interpolateBlues,
+            reds: d3_scale_chromatic_1.interpolateReds,
+            greens: d3_scale_chromatic_1.interpolateGreens,
+            viridis: d3_scale_chromatic_1.interpolateViridis
+        };
+        const interpolator = interpolators[colorScheme] || d3_scale_chromatic_1.interpolateBlues;
+        return (0, d3_scale_1.scaleSequential)(interpolator).domain(valueDomain);
+    }, [colorScheme, customColorScale, valueDomain]);
+    // Get unique x and y values for bin sizing
+    const { xBinCount, yBinCount } = (0, react_1.useMemo)(() => {
+        const getX = (0, hooks_1.resolveAccessor)(xAccessor);
+        const getY = (0, hooks_1.resolveAccessor)(yAccessor);
+        return {
+            xBinCount: new Set(safeData.map(getX)).size,
+            yBinCount: new Set(safeData.map(getY)).size
+        };
+    }, [safeData, xAccessor, yAccessor]);
+    // Transform data to summary format for StreamXYFrame
+    const summaryData = (0, react_1.useMemo)(() => {
+        return { coordinates: safeData };
+    }, [safeData]);
+    // Summary style function
+    const baseSummaryStyle = (0, react_1.useMemo)(() => {
+        return (d) => {
+            const value = getValueFn(d);
+            return {
+                fill: colorScale(value),
+                stroke: cellBorderColor,
+                strokeWidth: cellBorderWidth
+            };
+        };
+    }, [getValueFn, colorScale, cellBorderColor, cellBorderWidth]);
+    const summaryStyle = (0, react_1.useMemo)(() => (0, selectionUtils_1.wrapStyleWithSelection)(baseSummaryStyle, activeSelectionHook, selection), [baseSummaryStyle, activeSelectionHook, selection]);
+    // Summary render function (for value labels)
+    const summaryRenderMode = (0, react_1.useMemo)(() => {
+        if (!showValues)
+            return undefined;
+        const midpoint = (valueDomain[0] + valueDomain[1]) / 2;
+        return (d, i) => {
+            const value = getValueFn(d);
+            const displayValue = valueFormat ? valueFormat(value) : String(value);
+            return (React.createElement("text", { textAnchor: "middle", dominantBaseline: "middle", fill: getValueFn(d) > midpoint ? "#fff" : "#000", fontSize: "12px" }, displayValue));
+        };
+    }, [showValues, getValueFn, valueFormat, valueDomain]);
+    // ── Hover behavior ─────────────────────────────────────────────────────
+    const customHoverBehavior = (0, react_1.useCallback)((d) => {
+        if (linkedHover) {
+            linkedHoverHook.onHover(d);
+        }
+    }, [linkedHover, linkedHoverHook]);
+    // Default tooltip showing x, y, and value
+    const defaultTooltipContent = (0, react_1.useMemo)(() => (0, tooltipUtils_1.buildDefaultTooltip)([
+        { label: xLabel || (0, tooltipUtils_1.accessorName)(xAccessor), accessor: xAccessor, role: "x" },
+        { label: yLabel || (0, tooltipUtils_1.accessorName)(yAccessor), accessor: yAccessor, role: "y" },
+        { label: (0, tooltipUtils_1.accessorName)(valueAccessor), accessor: valueAccessor, role: "value" },
+    ]), [xAccessor, yAccessor, xLabel, yLabel, valueAccessor]);
+    // Validate data (after all hooks)
+    const error = (0, validateChartData_1.validateArrayData)({
+        componentName: "Heatmap",
+        data: safeData,
+        accessors: {
+            xAccessor,
+            yAccessor,
+            valueAccessor,
+        },
+    });
+    if (error)
+        return React.createElement(ChartError_1.default, { componentName: "Heatmap", message: error, width: width, height: height });
+    // Build StreamXYFrame props
+    const streamProps = {
+        chartType: "heatmap",
+        data: safeData,
+        xAccessor,
+        yAccessor,
+        valueAccessor,
+        size: [width, height],
+        margin,
+        showAxes: true,
+        xLabel,
+        yLabel,
+        xFormat,
+        yFormat,
+        enableHover,
+        ...(title && { title }),
+        ...(className && { className }),
+        tooltipContent: (tooltip ? (0, Tooltip_1.normalizeTooltip)(tooltip) : defaultTooltipContent),
+        ...(linkedHover && { customHoverBehavior }),
+        ...frameProps
+    };
+    return React.createElement(StreamXYFrame_1.default, { ...streamProps });
+}
+Heatmap.displayName = "Heatmap";

package/ai/dist/src/components/charts/xy/LineChart.js

@@ -0,0 +1,307 @@
+"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.LineChart = LineChart;
+const React = __importStar(require("react"));
+const react_1 = require("react");
+const StreamXYFrame_1 = __importDefault(require("../../stream/StreamXYFrame"));
+const colorUtils_1 = require("../shared/colorUtils");
+const hooks_1 = require("../shared/hooks");
+const legendUtils_1 = require("../shared/legendUtils");
+const Tooltip_1 = require("../../Tooltip/Tooltip");
+const tooltipUtils_1 = require("../shared/tooltipUtils");
+const ChartError_1 = __importDefault(require("../shared/ChartError"));
+const validateChartData_1 = require("../shared/validateChartData");
+const selectionUtils_1 = require("../shared/selectionUtils");
+const useSelection_1 = require("../../store/useSelection");
+const useSelection_2 = require("../../store/useSelection");
+/**
+ * LineChart - Visualize trends and time series data with lines
+ *
+ * A simplified wrapper around StreamXYFrame for creating line charts. Perfect for
+ * showing trends, comparisons, and temporal patterns in your data.
+ *
+ * @example
+ * ```tsx
+ * // Simple line chart
+ * <LineChart
+ *   data={[
+ *     {x: 1, y: 10},
+ *     {x: 2, y: 20},
+ *     {x: 3, y: 15}
+ *   ]}
+ *   xLabel="Time"
+ *   yLabel="Value"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Multiple lines with grouping
+ * <LineChart
+ *   data={[
+ *     {x: 1, y: 10, series: 'A'},
+ *     {x: 2, y: 20, series: 'A'},
+ *     {x: 1, y: 15, series: 'B'},
+ *     {x: 2, y: 25, series: 'B'}
+ *   ]}
+ *   lineBy="series"
+ *   colorBy="series"
+ *   xLabel="Time"
+ *   yLabel="Value"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Area chart with custom curve
+ * <LineChart
+ *   data={data}
+ *   curve="monotoneX"
+ *   fillArea={true}
+ *   areaOpacity={0.3}
+ *   showPoints={true}
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Advanced: Override StreamXYFrame props
+ * <LineChart
+ *   data={data}
+ *   frameProps={{
+ *     lineType: { type: "line", interpolator: d3.curveCardinal },
+ *     customLineMark: ({ d }) => <path stroke="red" />
+ *   }}
+ * />
+ * ```
+ *
+ * @remarks
+ * This component wraps {@link StreamXYFrame} with sensible defaults for line charts.
+ * For more advanced features like custom marks, annotations, or complex interactions,
+ * use StreamXYFrame directly.
+ *
+ * **Breadcrumb to advanced usage:**
+ * - Use the `frameProps` prop to pass any StreamXYFrame prop
+ * - See StreamXYFrame documentation: https://semiotic.nteract.io/guides/xy-frame
+ * - All StreamXYFrame props are available via `frameProps`
+ *
+ * @param props - LineChart configuration
+ * @returns Rendered line chart
+ */
+function LineChart(props) {
+    const { data, width = 600, height = 400, margin: userMargin, className, title, xLabel, yLabel, xFormat, yFormat, xAccessor = "x", yAccessor = "y", lineBy, lineDataAccessor = "coordinates", colorBy, colorScheme = "category10", curve = "linear", showPoints = false, pointRadius = 3, fillArea = false, areaOpacity = 0.3, lineWidth = 2, enableHover = true, showGrid = false, showLegend, tooltip, frameProps = {}, selection, linkedHover } = props;
+    const safeData = data || [];
+    // ── Selection hooks (always called, conditional logic inside) ──────────
+    const hoverConfig = (0, selectionUtils_1.normalizeLinkedHover)(linkedHover, colorBy ? [typeof colorBy === "string" ? colorBy : ""] : []);
+    const selectionHook = (0, useSelection_1.useSelection)({
+        name: selection?.name || "__unused__",
+        fields: []
+    });
+    const linkedHoverHook = (0, useSelection_2.useLinkedHover)({
+        name: hoverConfig?.name || "hover",
+        fields: hoverConfig?.fields || []
+    });
+    // Only use the hooks when the corresponding props are provided
+    const activeSelectionHook = selection ? { isActive: selectionHook.isActive, predicate: selectionHook.predicate } : null;
+    // ── Core chart logic ───────────────────────────────────────────────────
+    // Check if data is in line objects format (has lineDataAccessor field)
+    const isLineObjectFormat = safeData[0]?.[lineDataAccessor] !== undefined;
+    // Transform data to line format if needed
+    const lineData = (0, react_1.useMemo)(() => {
+        if (isLineObjectFormat) {
+            // Data is already in line objects format
+            return safeData;
+        }
+        if (lineBy) {
+            // Group data by lineBy field
+            const grouped = safeData.reduce((acc, d) => {
+                const key = typeof lineBy === "function" ? lineBy(d) : d[lineBy];
+                if (!acc[key]) {
+                    const lineObj = { [lineDataAccessor]: [] };
+                    // Add the grouping field
+                    if (typeof lineBy === "string") {
+                        lineObj[lineBy] = key;
+                    }
+                    acc[key] = lineObj;
+                }
+                acc[key][lineDataAccessor].push(d);
+                return acc;
+            }, {});
+            return Object.values(grouped);
+        }
+        // Single line - wrap in line object
+        return [{ [lineDataAccessor]: safeData }];
+    }, [safeData, lineBy, lineDataAccessor, isLineObjectFormat]);
+    // Create color scale if colorBy is specified
+    const colorScale = (0, hooks_1.useColorScale)(safeData, colorBy, colorScheme);
+    // Line style function
+    const baseLineStyle = (0, react_1.useMemo)(() => {
+        return (d) => {
+            const baseStyle = {
+                strokeWidth: lineWidth
+            };
+            // Apply color
+            if (colorBy) {
+                baseStyle.stroke = (0, colorUtils_1.getColor)(d, colorBy, colorScale);
+            }
+            else {
+                baseStyle.stroke = hooks_1.DEFAULT_COLOR;
+            }
+            // Apply fill for area chart
+            if (fillArea) {
+                baseStyle.fill = baseStyle.stroke;
+                baseStyle.fillOpacity = areaOpacity;
+            }
+            return baseStyle;
+        };
+    }, [colorBy, colorScale, lineWidth, fillArea, areaOpacity]);
+    const lineStyle = (0, react_1.useMemo)(() => (0, selectionUtils_1.wrapStyleWithSelection)(baseLineStyle, activeSelectionHook, selection), [baseLineStyle, activeSelectionHook, selection]);
+    // Point style function (if showPoints is true)
+    const pointStyle = (0, react_1.useMemo)(() => {
+        if (!showPoints)
+            return undefined;
+        return (d) => {
+            const baseStyle = {
+                r: pointRadius,
+                fillOpacity: 1
+            };
+            // Match line color
+            if (colorBy) {
+                baseStyle.fill = (0, colorUtils_1.getColor)(d.parentLine || d, colorBy, colorScale);
+            }
+            else {
+                baseStyle.fill = hooks_1.DEFAULT_COLOR;
+            }
+            return baseStyle;
+        };
+    }, [showPoints, pointRadius, colorBy, colorScale]);
+    // Determine chart type for StreamXYFrame
+    const chartType = fillArea ? "area" : "line";
+    // Determine if we should show legend
+    const shouldShowLegend = showLegend !== undefined ? showLegend : lineData.length > 1;
+    // Build legend if needed
+    const legend = (0, react_1.useMemo)(() => {
+        if (!shouldShowLegend || !colorBy)
+            return undefined;
+        return (0, legendUtils_1.createLegend)({
+            data: lineData,
+            colorBy,
+            colorScale,
+            getColor: colorUtils_1.getColor
+        });
+    }, [shouldShowLegend, colorBy, lineData, colorScale]);
+    // Adjust margin for legend if present
+    const margin = (0, react_1.useMemo)(() => {
+        const defaultMargin = { top: 50, bottom: 60, left: 70, right: 40 };
+        const finalMargin = { ...defaultMargin, ...userMargin };
+        // If legend is present and right margin is too small, increase it
+        if (legend && finalMargin.right < 120) {
+            finalMargin.right = 120;
+        }
+        return finalMargin;
+    }, [userMargin, legend]);
+    // ── Hover behavior ─────────────────────────────────────────────────────
+    const customHoverBehavior = (0, react_1.useCallback)((d) => {
+        if (linkedHover) {
+            linkedHoverHook.onHover(d);
+        }
+    }, [linkedHover, linkedHoverHook]);
+    // Default tooltip showing all configured fields
+    const groupField = lineBy || colorBy;
+    const defaultTooltipContent = (0, react_1.useMemo)(() => (0, tooltipUtils_1.buildDefaultTooltip)([
+        { label: xLabel || (0, tooltipUtils_1.accessorName)(xAccessor), accessor: xAccessor, role: "x" },
+        { label: yLabel || (0, tooltipUtils_1.accessorName)(yAccessor), accessor: yAccessor, role: "y" },
+        ...(groupField ? [{ label: (0, tooltipUtils_1.accessorName)(groupField), accessor: groupField, role: "group" }] : []),
+    ]), [xAccessor, yAccessor, xLabel, yLabel, groupField]);
+    // Validate data (after all hooks)
+    const error = (0, validateChartData_1.validateArrayData)({
+        componentName: "LineChart",
+        data: safeData,
+        accessors: {
+            xAccessor,
+            yAccessor,
+        },
+    });
+    if (error)
+        return React.createElement(ChartError_1.default, { componentName: "LineChart", message: error, width: width, height: height });
+    // Flatten line data into a single array for StreamXYFrame
+    const flattenedData = (0, react_1.useMemo)(() => {
+        if (isLineObjectFormat || lineBy) {
+            // Already grouped into line objects — flatten coordinates out
+            return lineData.flatMap((line) => {
+                const coords = line[lineDataAccessor] || [];
+                // Carry grouping field onto each datum
+                if (lineBy && typeof lineBy === "string") {
+                    return coords.map((c) => ({ ...c, [lineBy]: line[lineBy] }));
+                }
+                return coords;
+            });
+        }
+        return safeData;
+    }, [lineData, lineDataAccessor, isLineObjectFormat, lineBy, safeData]);
+    // Build StreamXYFrame props
+    const streamProps = {
+        chartType,
+        data: flattenedData,
+        xAccessor,
+        yAccessor,
+        groupAccessor: lineBy || undefined,
+        curve,
+        lineStyle,
+        ...(showPoints && { pointStyle }),
+        size: [width, height],
+        margin,
+        showAxes: true,
+        xLabel,
+        yLabel,
+        xFormat,
+        yFormat,
+        enableHover,
+        showGrid,
+        ...(legend && { legend }),
+        ...(title && { title }),
+        ...(className && { className }),
+        tooltipContent: (tooltip ? (0, Tooltip_1.normalizeTooltip)(tooltip) : defaultTooltipContent),
+        ...(linkedHover && { customHoverBehavior }),
+        ...frameProps
+    };
+    return React.createElement(StreamXYFrame_1.default, { ...streamProps });
+}
+LineChart.displayName = "LineChart";