semiotic 2.0.3 → 3.0.0-beta.2

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

@@ -0,0 +1,426 @@
+"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.ScatterplotMatrix = ScatterplotMatrix;
+const React = __importStar(require("react"));
+const react_1 = require("react");
+const StreamXYFrame_1 = __importDefault(require("../../stream/StreamXYFrame"));
+const d3_brush_1 = require("d3-brush");
+const d3_selection_1 = require("d3-selection");
+const colorUtils_1 = require("../shared/colorUtils");
+const hooks_1 = require("../shared/hooks");
+const LinkedCharts_1 = require("../../LinkedCharts");
+const useSelection_1 = require("../../store/useSelection");
+const SelectionStore_1 = require("../../store/SelectionStore");
+// Internal field used to identify datums across cells
+const SPLOM_IDX = "__splomIdx";
+// Shared clientId for all hover writers — ensures each new hover REPLACES
+// the previous one (same key in the clause Map) instead of accumulating.
+const HOVER_CLIENT_ID = "splom-hover-source";
+const CELL_MARGIN = { top: 4, bottom: 4, left: 4, right: 4 };
+function CellBrushOverlay({ frameRef, cellSize, xField, yField, onBrush }) {
+    const svgRef = (0, react_1.useRef)(null);
+    const chartW = cellSize - CELL_MARGIN.left - CELL_MARGIN.right;
+    const chartH = cellSize - CELL_MARGIN.top - CELL_MARGIN.bottom;
+    (0, react_1.useEffect)(() => {
+        if (!svgRef.current)
+            return;
+        const g = (0, d3_selection_1.select)(svgRef.current).select(".brush-g");
+        const brush = (0, d3_brush_1.brush)()
+            .extent([[0, 0], [chartW, chartH]])
+            .on("brush end", (event) => {
+            const scales = frameRef.current?.getScales();
+            if (!scales)
+                return;
+            if (!event.selection) {
+                onBrush(null);
+                return;
+            }
+            const [[px0, py0], [px1, py1]] = event.selection;
+            const dataExtent = [
+                [scales.x.invert(px0), scales.y.invert(py0)],
+                [scales.x.invert(px1), scales.y.invert(py1)]
+            ];
+            onBrush(dataExtent);
+        });
+        g.call(brush);
+        // Style the brush
+        g.select(".selection")
+            .attr("fill", "steelblue")
+            .attr("fill-opacity", 0.15)
+            .attr("stroke", "steelblue")
+            .attr("stroke-width", 1);
+        return () => {
+            brush.on("brush end", null);
+        };
+    }, [chartW, chartH, frameRef, onBrush]);
+    return (React.createElement("svg", { ref: svgRef, width: cellSize, height: cellSize, style: { position: "absolute", top: 0, left: 0 } },
+        React.createElement("g", { className: "brush-g", transform: `translate(${CELL_MARGIN.left},${CELL_MARGIN.top})` })));
+}
+function ScatterplotCell({ data, xField, yField, fieldLabels, cellSize, pointRadius, pointOpacity, colorBy, colorScale, brushSelectionName, hoverSelectionName, unselectedOpacity, showGrid, tooltip, mode, onPointHover }) {
+    const frameRef = (0, react_1.useRef)(null);
+    const clientId = `splom-${xField}-${yField}`;
+    // Brush selection (crossfilter) — only used in brush mode
+    const brushSelectionHook = (0, useSelection_1.useSelection)({
+        name: brushSelectionName,
+        clientId,
+        fields: [xField, yField]
+    });
+    const brushHook = (0, useSelection_1.useBrushSelection)({
+        name: brushSelectionName,
+        xField,
+        yField
+    });
+    // Hover selection — all cells share HOVER_CLIENT_ID so each new hover
+    // REPLACES the previous cell's clause instead of accumulating.
+    const hoverHook = (0, useSelection_1.useSelection)({
+        name: hoverSelectionName,
+        clientId: HOVER_CLIENT_ID,
+        fields: [SPLOM_IDX]
+    });
+    const hoverSelectPoints = hoverHook.selectPoints;
+    // Brush callback: convert d3-brush data-space extent to useBrushSelection format
+    const handleBrush = (0, react_1.useCallback)((extent) => {
+        if (!extent) {
+            brushHook.brushInteraction.end(null);
+            return;
+        }
+        brushHook.brushInteraction.during(extent);
+    }, [brushHook.brushInteraction]);
+    const customHoverBehavior = (0, react_1.useCallback)((hover) => {
+        if (!hover) {
+            onPointHover?.(null);
+            return;
+        }
+        const d = hover.data;
+        const idx = d?.[SPLOM_IDX];
+        if (idx !== undefined) {
+            hoverSelectPoints({ [SPLOM_IDX]: [idx] });
+            onPointHover?.(d, hover.x + CELL_MARGIN.left, hover.y + CELL_MARGIN.top);
+        }
+    }, [hoverSelectPoints, onPointHover]);
+    const pointStyle = (0, react_1.useCallback)((d) => {
+        const style = {
+            opacity: pointOpacity,
+            r: pointRadius
+        };
+        if (colorBy) {
+            style.fill = (0, colorUtils_1.getColor)(d, colorBy, colorScale);
+        }
+        else {
+            style.fill = hooks_1.DEFAULT_COLOR;
+        }
+        if (mode === "hover") {
+            const hoverHighlighted = hoverHook.isActive && hoverHook.predicate(d);
+            if (hoverHighlighted) {
+                style.opacity = 1;
+                style.r = pointRadius * 2.5;
+                style.stroke = "#333";
+                style.strokeWidth = 1.5;
+            }
+            else if (hoverHook.isActive) {
+                style.opacity = pointOpacity * 0.6;
+            }
+        }
+        else {
+            // brush mode
+            const brushDimmed = brushSelectionHook.isActive && !brushSelectionHook.predicate(d);
+            if (brushDimmed) {
+                style.opacity = unselectedOpacity;
+            }
+        }
+        return style;
+    }, [colorBy, colorScale, pointOpacity, pointRadius, mode, brushSelectionHook.isActive, brushSelectionHook.predicate, hoverHook.isActive, hoverHook.predicate, unselectedOpacity]);
+    return (React.createElement("div", { style: { position: "relative", width: cellSize, height: cellSize } },
+        React.createElement(StreamXYFrame_1.default, { ref: frameRef, chartType: "scatter", data: data, size: [cellSize, cellSize], xAccessor: xField, yAccessor: yField, pointStyle: pointStyle, margin: CELL_MARGIN, showAxes: false, enableHover: mode === "hover", customHoverBehavior: mode === "hover" ? customHoverBehavior : undefined, tooltipContent: mode === "hover" ? (() => null) : undefined }),
+        mode === "brush" && (React.createElement(CellBrushOverlay, { frameRef: frameRef, cellSize: cellSize, xField: xField, yField: yField, onBrush: handleBrush }))));
+}
+function DiagonalCell({ data, field, label, cellSize, bins, colorBy, colorScale, brushSelectionName, hoverSelectionName, unselectedOpacity, mode }) {
+    const brushHook = (0, useSelection_1.useSelection)({
+        name: brushSelectionName,
+        clientId: `splom-diag-${field}`,
+        fields: [field]
+    });
+    const hoverHook = (0, useSelection_1.useSelection)({
+        name: hoverSelectionName,
+        clientId: `splom-diag-${field}-hover`,
+        fields: [SPLOM_IDX]
+    });
+    // Use the active mode's predicate
+    const activeHook = mode === "hover" ? hoverHook : brushHook;
+    const isActive = activeHook.isActive;
+    const activePredicate = activeHook.predicate;
+    const histogram = (0, react_1.useMemo)(() => {
+        const values = data.map((d) => d[field]).filter((v) => v != null && !isNaN(v));
+        if (values.length === 0)
+            return { bars: [], selectedBars: [], max: 0 };
+        const min = Math.min(...values);
+        const max = Math.max(...values);
+        const binWidth = (max - min) / bins || 1;
+        const counts = new Array(bins).fill(0);
+        const selectedCounts = new Array(bins).fill(0);
+        for (const d of data) {
+            const v = d[field];
+            if (v == null || isNaN(v))
+                continue;
+            const idx = Math.min(Math.floor((v - min) / binWidth), bins - 1);
+            counts[idx]++;
+            if (!isActive || activePredicate(d)) {
+                selectedCounts[idx]++;
+            }
+        }
+        const maxCount = Math.max(...counts, 1);
+        return {
+            bars: counts.map((c, i) => ({
+                x: (i / bins) * cellSize,
+                w: (cellSize / bins) - 1,
+                h: (c / maxCount) * (cellSize - 24),
+                count: c
+            })),
+            selectedBars: selectedCounts.map((c, i) => ({
+                x: (i / bins) * cellSize,
+                w: (cellSize / bins) - 1,
+                h: (c / maxCount) * (cellSize - 24),
+                count: c
+            })),
+            max: maxCount
+        };
+    }, [data, field, bins, cellSize, isActive, activePredicate]);
+    return (React.createElement("svg", { width: cellSize, height: cellSize, style: { overflow: "hidden" } },
+        React.createElement("text", { x: cellSize / 2, y: 14, textAnchor: "middle", fontSize: 11, fontWeight: "bold", fill: "#333" }, label),
+        histogram.bars.map((bar, i) => (React.createElement("rect", { key: `bg-${i}`, x: bar.x, y: cellSize - bar.h, width: Math.max(bar.w, 1), height: bar.h, fill: "#ccc", opacity: isActive ? 0.3 : 0.6 }))),
+        isActive &&
+            histogram.selectedBars.map((bar, i) => (React.createElement("rect", { key: `sel-${i}`, x: bar.x, y: cellSize - bar.h, width: Math.max(bar.w, 1), height: bar.h, fill: hooks_1.DEFAULT_COLOR, opacity: 0.7 })))));
+}
+// ── Label Cell ─────────────────────────────────────────────────────────────
+function LabelCell({ label, cellSize }) {
+    return (React.createElement("svg", { width: cellSize, height: cellSize },
+        React.createElement("text", { x: cellSize / 2, y: cellSize / 2, textAnchor: "middle", dominantBaseline: "middle", fontSize: 12, fontWeight: "bold", fill: "#333" }, label)));
+}
+// ── ScatterplotMatrix ──────────────────────────────────────────────────────
+function ScatterplotMatrixInner(props) {
+    const { data, fields, fieldLabels = {}, colorBy, colorScheme = "category10", cellSize = 150, cellGap = 4, pointRadius = 2, pointOpacity = 0.5, diagonal = "histogram", histogramBins = 20, brushMode = "crossfilter", hoverMode = true, unselectedOpacity = 0.1, showGrid = false, tooltip, showLegend, idAccessor, width, height, className } = props;
+    const brushSelectionName = "splom";
+    const hoverSelectionName = "splom-hover";
+    // Brush and hover are mutually exclusive: hover wins when enabled
+    const cellMode = hoverMode ? "hover" : (brushMode ? "brush" : "hover");
+    // Grid-level hover state — single tooltip for the entire matrix
+    const clearSelection = (0, SelectionStore_1.useSelectionSelector)((s) => s.clearSelection);
+    const [hoveredInfo, setHoveredInfo] = (0, react_1.useState)(null);
+    // Clear all hover state when mouse leaves the grid
+    const handleGridMouseLeave = (0, react_1.useCallback)(() => {
+        clearSelection(hoverSelectionName);
+        setHoveredInfo(null);
+    }, [clearSelection, hoverSelectionName]);
+    // Stamp each datum with a stable index for cross-cell identity matching
+    const indexedData = (0, react_1.useMemo)(() => {
+        return (data || []).map((d, i) => {
+            if (d[SPLOM_IDX] !== undefined)
+                return d;
+            return { ...d, [SPLOM_IDX]: i };
+        });
+    }, [data]);
+    const colorScale = (0, hooks_1.useColorScale)(indexedData, colorBy, colorScheme);
+    const n = fields.length;
+    const labelWidth = 40;
+    // Legend
+    const shouldShowLegend = showLegend !== undefined ? showLegend : !!colorBy;
+    const legend = (0, react_1.useMemo)(() => {
+        if (!shouldShowLegend || !colorBy)
+            return null;
+        const colorField = typeof colorBy === "string" ? colorBy : null;
+        if (!colorField)
+            return null;
+        const categories = [...new Set(indexedData.map((d) => d[colorField]))];
+        return categories.map((cat) => ({
+            label: String(cat),
+            color: colorScale ? colorScale(String(cat)) : hooks_1.DEFAULT_COLOR
+        }));
+    }, [shouldShowLegend, colorBy, indexedData, colorScale]);
+    const gridStyle = (0, react_1.useMemo)(() => ({
+        display: "grid",
+        gridTemplateColumns: `${labelWidth}px ${fields.map(() => `${cellSize}px`).join(" ")}`,
+        gridTemplateRows: `${fields.map(() => `${cellSize}px`).join(" ")} ${labelWidth}px`,
+        gap: `${cellGap}px`,
+        width: "fit-content"
+    }), [fields, cellSize, cellGap, labelWidth]);
+    return (React.createElement("div", { className: className, style: { position: "relative" } },
+        legend && (React.createElement("div", { style: { display: "flex", gap: 12, marginBottom: 8, flexWrap: "wrap" } }, legend.map((item) => (React.createElement("div", { key: item.label, style: { display: "flex", alignItems: "center", gap: 4 } },
+            React.createElement("span", { style: {
+                    display: "inline-block",
+                    width: 10,
+                    height: 10,
+                    borderRadius: "50%",
+                    backgroundColor: item.color
+                } }),
+            React.createElement("span", { style: { fontSize: 11 } }, item.label)))))),
+        React.createElement("div", { style: gridStyle, onMouseLeave: cellMode === "hover" ? handleGridMouseLeave : undefined },
+            fields.map((rowField, row) => (React.createElement(React.Fragment, { key: `row-${rowField}` },
+                React.createElement("div", { style: {
+                        display: "flex",
+                        alignItems: "center",
+                        justifyContent: "center",
+                        writingMode: "vertical-rl",
+                        transform: "rotate(180deg)",
+                        fontSize: 11,
+                        fontWeight: "bold",
+                        color: "#333"
+                    } }, fieldLabels[rowField] || rowField),
+                fields.map((colField, col) => {
+                    if (row === col) {
+                        // Diagonal
+                        if (diagonal === "label") {
+                            return (React.createElement(LabelCell, { key: `diag-${rowField}`, label: fieldLabels[rowField] || rowField, cellSize: cellSize }));
+                        }
+                        return (React.createElement(DiagonalCell, { key: `diag-${rowField}`, data: indexedData, field: rowField, label: fieldLabels[rowField] || rowField, cellSize: cellSize, bins: histogramBins, colorBy: colorBy, colorScale: colorScale, brushSelectionName: brushSelectionName, hoverSelectionName: hoverSelectionName, unselectedOpacity: unselectedOpacity, mode: cellMode }));
+                    }
+                    return (React.createElement(ScatterplotCell, { key: `cell-${rowField}-${colField}`, data: indexedData, xField: colField, yField: rowField, fieldLabels: fieldLabels, cellSize: cellSize, pointRadius: pointRadius, pointOpacity: pointOpacity, colorBy: colorBy, colorScale: colorScale, brushSelectionName: brushSelectionName, hoverSelectionName: hoverSelectionName, unselectedOpacity: unselectedOpacity, showGrid: showGrid, tooltip: tooltip, mode: cellMode, onPointHover: cellMode === "hover" ? (datum, px, py) => {
+                            if (datum) {
+                                setHoveredInfo({
+                                    datum,
+                                    xField: colField,
+                                    yField: rowField,
+                                    colIndex: col,
+                                    rowIndex: row,
+                                    px: px ?? 0,
+                                    py: py ?? 0
+                                });
+                            }
+                            else {
+                                setHoveredInfo(null);
+                            }
+                        } : undefined }));
+                })))),
+            React.createElement("div", null),
+            " ",
+            fields.map((field) => (React.createElement("div", { key: `col-label-${field}`, style: {
+                    display: "flex",
+                    alignItems: "center",
+                    justifyContent: "center",
+                    fontSize: 11,
+                    fontWeight: "bold",
+                    color: "#333"
+                } }, fieldLabels[field] || field)))),
+        hoveredInfo && cellMode === "hover" && (() => {
+            const d = hoveredInfo.datum;
+            const xFieldLabel = fieldLabels[hoveredInfo.xField] || hoveredInfo.xField;
+            const yFieldLabel = fieldLabels[hoveredInfo.yField] || hoveredInfo.yField;
+            const colorLabel = colorBy
+                ? typeof colorBy === "function" ? colorBy(d) : d[colorBy]
+                : null;
+            // Resolve ID for header
+            const idLabel = idAccessor
+                ? (typeof idAccessor === "function" ? idAccessor(d) : d[idAccessor])
+                : `Row ${d[SPLOM_IDX]}`;
+            // Cell origin in grid coordinates
+            const cellLeft = labelWidth + hoveredInfo.colIndex * (cellSize + cellGap);
+            const cellTop = hoveredInfo.rowIndex * (cellSize + cellGap);
+            // Point position within the cell
+            const tooltipLeft = cellLeft + hoveredInfo.px;
+            const tooltipTop = cellTop + hoveredInfo.py - 8; // 8px above the point
+            return (React.createElement("div", { style: {
+                    position: "absolute",
+                    left: tooltipLeft,
+                    top: tooltipTop,
+                    transform: "translate(-50%, -100%)",
+                    color: "#333",
+                    background: "rgba(255,255,255,0.95)",
+                    border: "1px solid #ddd",
+                    borderRadius: 3,
+                    padding: "4px 8px",
+                    fontSize: 11,
+                    lineHeight: 1.4,
+                    whiteSpace: "nowrap",
+                    pointerEvents: "none",
+                    zIndex: 10
+                } },
+                React.createElement("div", { style: { fontWeight: "bold", marginBottom: 2 } }, String(idLabel)),
+                React.createElement("div", null,
+                    xFieldLabel,
+                    ": ",
+                    d[hoveredInfo.xField] != null ? Number(d[hoveredInfo.xField]).toFixed(1) : "–"),
+                React.createElement("div", null,
+                    yFieldLabel,
+                    ": ",
+                    d[hoveredInfo.yField] != null ? Number(d[hoveredInfo.yField]).toFixed(1) : "–"),
+                colorLabel != null && React.createElement("div", { style: { opacity: 0.8 } },
+                    typeof colorBy === "string" ? colorBy : "group",
+                    ": ",
+                    String(colorLabel))));
+        })()));
+}
+/**
+ * ScatterplotMatrix (SPLOM) — multi-dimensional scatter visualization
+ *
+ * Renders an N×N grid of scatterplots for all pairwise combinations of the
+ * specified fields. Diagonal cells show histograms. Supports two interaction
+ * modes:
+ *
+ * - **Hover** (default): hover a point to cross-highlight the same datum
+ *   in every cell. Set `hoverMode={true}` (the default).
+ * - **Brush**: drag to select a region in one cell; matching points are
+ *   highlighted across all cells (crossfilter: the brushed cell excludes
+ *   its own filter). Set `hoverMode={false}` to enable brush mode.
+ *
+ * The two modes are mutually exclusive — hover takes priority when enabled.
+ *
+ * @example
+ * ```tsx
+ * <ScatterplotMatrix
+ *   data={iris}
+ *   fields={["sepalLength", "sepalWidth", "petalLength", "petalWidth"]}
+ *   colorBy="species"
+ *   cellSize={160}
+ *   diagonal="histogram"
+ * />
+ * ```
+ */
+function ScatterplotMatrix(props) {
+    const { brushMode = "crossfilter", hoverMode = true } = props;
+    const selectionConfig = {};
+    if (!hoverMode && brushMode) {
+        selectionConfig.splom = { resolution: brushMode };
+    }
+    if (hoverMode) {
+        selectionConfig["splom-hover"] = { resolution: "union" };
+    }
+    return (React.createElement(LinkedCharts_1.LinkedCharts, { selections: selectionConfig },
+        React.createElement(ScatterplotMatrixInner, { ...props })));
+}
+ScatterplotMatrix.displayName = "ScatterplotMatrix";

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

@@ -0,0 +1,231 @@
+"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.StackedAreaChart = StackedAreaChart;
+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");
+/**
+ * StackedAreaChart - Visualize quantities stacked on top of each other over continuous intervals
+ *
+ * Each series is stacked so that the total height represents the sum of all series.
+ * Use `normalize` for 100% stacked (proportional) areas.
+ *
+ * For overlapping (non-stacked) areas use {@link AreaChart}.
+ *
+ * @example
+ * ```tsx
+ * <StackedAreaChart
+ *   data={[
+ *     {x: 1, y: 10, category: 'A'},
+ *     {x: 2, y: 20, category: 'A'},
+ *     {x: 1, y: 15, category: 'B'},
+ *     {x: 2, y: 25, category: 'B'}
+ *   ]}
+ *   areaBy="category"
+ *   colorBy="category"
+ *   xLabel="Time"
+ *   yLabel="Value"
+ * />
+ * ```
+ */
+function StackedAreaChart(props) {
+    const { data, width = 600, height = 400, margin: userMargin, className, title, xLabel, yLabel, xFormat, yFormat, xAccessor = "x", yAccessor = "y", areaBy, lineDataAccessor = "coordinates", colorBy, colorScheme = "category10", curve = "monotoneX", areaOpacity = 0.7, showLine = true, lineWidth = 2, normalize = false, 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 area objects format (has lineDataAccessor field)
+    const isAreaObjectFormat = safeData[0]?.[lineDataAccessor] !== undefined;
+    // Transform data to line/area format if needed
+    const areaData = (0, react_1.useMemo)(() => {
+        if (isAreaObjectFormat) {
+            // Data is already in area objects format
+            return safeData;
+        }
+        if (areaBy) {
+            // Group data by areaBy field
+            const grouped = safeData.reduce((acc, d) => {
+                const key = typeof areaBy === "function" ? areaBy(d) : d[areaBy];
+                if (!acc[key]) {
+                    const areaObj = { [lineDataAccessor]: [] };
+                    // Add the grouping field
+                    if (typeof areaBy === "string") {
+                        areaObj[areaBy] = key;
+                    }
+                    acc[key] = areaObj;
+                }
+                acc[key][lineDataAccessor].push(d);
+                return acc;
+            }, {});
+            return Object.values(grouped);
+        }
+        // Single area - wrap in area object
+        return [{ [lineDataAccessor]: safeData }];
+    }, [safeData, areaBy, lineDataAccessor, isAreaObjectFormat]);
+    // Create color scale if colorBy is specified
+    const colorScale = (0, hooks_1.useColorScale)(safeData, colorBy, colorScheme);
+    // Area/line style function
+    const baseLineStyle = (0, react_1.useMemo)(() => {
+        return (d) => {
+            const baseStyle = {};
+            // Apply color
+            const color = colorBy ? (0, colorUtils_1.getColor)(d, colorBy, colorScale) : hooks_1.DEFAULT_COLOR;
+            baseStyle.fill = color;
+            baseStyle.fillOpacity = areaOpacity;
+            if (showLine) {
+                baseStyle.stroke = color;
+                baseStyle.strokeWidth = lineWidth;
+            }
+            else {
+                baseStyle.stroke = "none";
+            }
+            return baseStyle;
+        };
+    }, [colorBy, colorScale, areaOpacity, showLine, lineWidth]);
+    const lineStyle = (0, react_1.useMemo)(() => (0, selectionUtils_1.wrapStyleWithSelection)(baseLineStyle, activeSelectionHook, selection), [baseLineStyle, activeSelectionHook, selection]);
+    // Determine if we should show legend
+    const shouldShowLegend = showLegend !== undefined ? showLegend : areaData.length > 1;
+    // Build legend if needed
+    const legend = (0, react_1.useMemo)(() => {
+        if (!shouldShowLegend || !colorBy)
+            return undefined;
+        return (0, legendUtils_1.createLegend)({
+            data: areaData,
+            colorBy,
+            colorScale,
+            getColor: colorUtils_1.getColor
+        });
+    }, [shouldShowLegend, colorBy, areaData, 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 = areaBy || 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: "StackedAreaChart",
+        data: safeData,
+        accessors: {
+            xAccessor,
+            yAccessor,
+        },
+    });
+    if (error)
+        return React.createElement(ChartError_1.default, { componentName: "StackedAreaChart", message: error, width: width, height: height });
+    // Flatten area data into a single array for StreamXYFrame
+    const flattenedData = (0, react_1.useMemo)(() => {
+        if (isAreaObjectFormat || areaBy) {
+            return areaData.flatMap((area) => {
+                const coords = area[lineDataAccessor] || [];
+                if (areaBy && typeof areaBy === "string") {
+                    return coords.map((c) => ({ ...c, [areaBy]: area[areaBy] }));
+                }
+                return coords;
+            });
+        }
+        return safeData;
+    }, [areaData, lineDataAccessor, isAreaObjectFormat, areaBy, safeData]);
+    // Build StreamXYFrame props
+    const streamProps = {
+        chartType: "stackedarea",
+        data: flattenedData,
+        xAccessor,
+        yAccessor,
+        groupAccessor: areaBy || undefined,
+        curve,
+        normalize,
+        lineStyle,
+        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 });
+}
+StackedAreaChart.displayName = "StackedAreaChart";

package/ai/dist/src/components/constants/coordinateNames.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectedXBottom = exports.projectedXTop = exports.projectedXMiddle = exports.projectedYBottom = exports.projectedYTop = exports.projectedYMiddle = exports.projectedY = exports.projectedX = void 0;
+exports.projectedX = "x";
+exports.projectedY = "y";
+exports.projectedYMiddle = "yMiddle";
+exports.projectedYTop = "yTop";
+exports.projectedYBottom = "yBottom";
+exports.projectedXMiddle = "xMiddle";
+exports.projectedXTop = "xTop";
+exports.projectedXBottom = "xBottom";