@czi-sds/data-viz 0.4.2 → 0.6.0

package/dist/index.cjs.d.ts

@@ -1,7 +1,12 @@
 /// <reference types="react" />
-import { ECharts, ElementEvent, DatasetComponentOption, EChartsOption, ScatterSeriesOption } from "echarts";
 import { HTMLAttributes } from "react";
+import { DatasetComponentOption, ECharts, EChartsOption, ScatterSeriesOption } from "echarts";
 interface CreateChartOptionsProps {
+    /**
+     * Display reference line and axis value under mouse pointer
+     * https://echarts.apache.org/en/option.html#axisPointer
+     */
+    axisPointer?: EChartsOption["axisPointer"];
     /**
      * The data array to be visualized
      * The data point object shape can be whatever you like, but it must be consistent with the `encode` option
@@ -18,6 +23,44 @@ interface CreateChartOptionsProps {
      * }
      */
     data: DatasetComponentOption["source"];
+    /**
+     * The `dataZoom` prop is utilized for implementing zoom functionality within a
+     * specific area of the chart. This feature empowers users to inspect data in
+     * granular detail, obtain an overview of the entire dataset, or eliminate
+     * outlier points.
+     * By applying the `dataZoom` prop while locking the zoom level, the chart
+     * efficiently renders a confined portion of the heatmap. This selective
+     * rendering strategy becomes especially advantageous when dealing with
+     * extensive datasets. Instead of rendering the entire heatmap at once,
+     * the chart dynamically loads and renders specific segments as the user
+     * scrolls through the data. This approach optimizes performance and enables
+     * the creation of heatmaps with large amounts of data.
+     * https://echarts.apache.org/en/option.html#dataZoom
+     */
+    dataZoom?: EChartsOption["dataZoom"];
+    /**
+     * The `camera` prop is utilized for implementing camera view port functionality
+     * within a specific area of the chart. This feature empowers users to render
+     * a confined portion of the heatmap. This selective rendering strategy becomes
+     * especially advantageous when dealing with extensive datasets. Instead of
+     * rendering the entire heatmap at once, the chart dynamically loads and renders
+     * specific segments as the user scrolls through the data. This approach optimizes
+     * performance and enables the creation of heatmaps with large amounts of data.
+     *
+     * The `height` and `width` properties are used to specify the dimensions of the
+     * camera view port. The `active` property is used to enable or disable the camera
+     * view port functionality.
+     */
+    camera?: {
+        active: boolean;
+        height: number;
+        width: number;
+    };
+    /**
+     * Customize the style of each cell item when mouse hovers on it, such as color, border, opacity, etc.
+     * https://echarts.apache.org/en/option.html#series-scatter.emphasis
+     */
+    emphasis?: ScatterSeriesOption["emphasis"];
     /**
      * The data for the x axis
      * For example:
@@ -30,7 +73,13 @@ interface CreateChartOptionsProps {
      * [{ value: "cellType1", textStyle: { color: "red" } }, "cellType2", "cellType3"]
      */
     yAxisData: CategoryAxisData;
+    /**
+     * The width of the chart in pixels
+     */
     width: number;
+    /**
+     * The height of the chart in pixels
+     */
     height: number;
     /**
      * Provide a mapping of data key to x/y axis encoding
@@ -56,6 +105,10 @@ interface CreateChartOptionsProps {
      * https://echarts.apache.org/en/option.html#series-scatter.itemStyle
      */
     itemStyle?: ScatterSeriesOption["itemStyle"];
+    /**
+     * The shape of the symbol.
+     */
+    symbol?: "circle" | "rect" | "roundRect";
     /**
      * `symbolSize` can be set to single numbers like 10, or use an array to represent width and height. For example, [20, 10] means symbol width is 20, and height is 10.
      *
@@ -71,6 +124,16 @@ interface CreateChartOptionsProps {
      * https://echarts.apache.org/en/option.html#grid
      */
     grid?: EChartsOption["grid"] | ((defaultOption: EChartsOption["grid"]) => EChartsOption["grid"]);
+    /**
+     * The options object to be passed to echarts.setOption()
+     * https://echarts.apache.org/en/option.html
+     */
+    options?: EChartsOption;
+    /**
+     * Event listeners for the chart
+     * https://echarts.apache.org/en/api.html#events
+     */
+    onEvents?: Record<string, (event: unknown, chart: ECharts) => void>;
 }
 type OrdinalRawValue = string | number;
 /**
@@ -85,7 +148,6 @@ type CategoryAxisData = (OrdinalRawValue | {
 })[];
 interface HeatmapChartProps extends HTMLAttributes<HTMLDivElement>, CreateChartOptionsProps {
     echartsRendererMode?: "svg" | "canvas";
-    onChartMouseMove?: (event: ElementEvent, chart: ECharts) => void;
 }
 declare const _default: import("react").MemoExoticComponent<import("react").ForwardRefExoticComponent<HeatmapChartProps & import("react").RefAttributes<HTMLDivElement>>>;
 export { HeatmapChartProps, _default, _default as HeatmapChart };

package/dist/index.cjs.js

@@ -62,8 +62,70 @@ var DEFAULT_ITEM_STYLE = {
         return "rgb(0, 0, 0)";
     },
 };
-function createChartOptions(_a) {
-    var data = _a.data, xAxisData = _a.xAxisData, yAxisData = _a.yAxisData, width = _a.width, height = _a.height, encode = _a.encode, _b = _a.itemStyle, itemStyle = _b === void 0 ? DEFAULT_ITEM_STYLE : _b, symbolSize = _a.symbolSize, gridProp = _a.grid;
+function createChartOptions(props) {
+    var axisPointer = props.axisPointer, camera = props.camera, data = props.data, dataZoom = props.dataZoom, emphasis = props.emphasis, encode = props.encode, gridProp = props.grid, _a = props.itemStyle, itemStyle = _a === void 0 ? DEFAULT_ITEM_STYLE : _a, options = props.options, symbolSize = props.symbolSize, _b = props.symbol, symbol = _b === void 0 ? "rect" : _b;
+    var _c = generateDefaultValues(props), defaultAxisPointer = _c.defaultAxisPointer, defaultDataZoom = _c.defaultDataZoom, defaultEmphasis = _c.defaultEmphasis, defaultGrid = _c.defaultGrid, defaultXAxis = _c.defaultXAxis, defaultYAxis = _c.defaultYAxis;
+    var customGrid = typeof gridProp === "function" ? gridProp(defaultGrid) : gridProp;
+    var _d = options || {}, optionsAxisPointer = _d.axisPointer, optionsDataZoom = _d.dataZoom, optionsSeries = _d.series, optionsXAxis = _d.xAxis, optionsYAxis = _d.yAxis, optionsRest = __rest(_d, ["axisPointer", "dataZoom", "series", "xAxis", "yAxis"]);
+    return __assign({ animation: false, axisPointer: mergeAxisPointer(defaultAxisPointer, axisPointer, optionsAxisPointer), dataZoom: (camera === null || camera === void 0 ? void 0 : camera.active)
+            ? mergeDataZoom(defaultDataZoom, dataZoom, optionsDataZoom)
+            : [], dataset: {
+            source: data,
+        }, grid: customGrid || defaultGrid, series: [
+            Object.assign({
+                emphasis: Object.assign(defaultEmphasis, emphasis),
+                encode: encode,
+                itemStyle: itemStyle,
+                legendHoverLink: false,
+                symbol: symbol,
+                symbolSize: symbolSize,
+            }, optionsSeries
+                ? Array.isArray(optionsSeries)
+                    ? optionsSeries[0]
+                    : optionsSeries
+                : [], { symbol: symbol, type: "scatter" }),
+        ], xAxis: [
+            Object.assign(defaultXAxis, optionsXAxis
+                ? Array.isArray(optionsXAxis)
+                    ? optionsXAxis[0]
+                    : optionsXAxis
+                : {}),
+        ], yAxis: [
+            Object.assign(defaultYAxis, optionsYAxis
+                ? Array.isArray(optionsYAxis)
+                    ? optionsYAxis[0]
+                    : optionsYAxis
+                : {}),
+        ] }, optionsRest);
+}
+function mergeAxisPointer(defaultAxisPointer, axisPointer, optionsAxisPointer) {
+    var finalAxisPointer = Array.isArray(axisPointer)
+        ? axisPointer // if it's an array, assume that the user has [{...propsToChangeOnX}] OR [ , {...propsToChangeOnY}] OR [{...propsToChangeOnX}, {...propsToChangeOnY}]
+        : [axisPointer, axisPointer]; // else if the user only supplies one AxisPointer object, we assume they want the props to apply to both x and y axisPointer objects
+    var finalOptionsAxisPointer = Array.isArray(optionsAxisPointer)
+        ? optionsAxisPointer
+        : [optionsAxisPointer, optionsAxisPointer];
+    // merge x axisPointer options
+    var x = __assign(__assign(__assign({}, defaultAxisPointer), finalAxisPointer[0]), finalOptionsAxisPointer === null || finalOptionsAxisPointer === void 0 ? void 0 : finalOptionsAxisPointer[0]);
+    // merge y axisPointer options
+    var y = __assign(__assign(__assign({}, defaultAxisPointer), finalAxisPointer[1]), finalOptionsAxisPointer[1]);
+    return [x, y];
+}
+function mergeDataZoom(defaultDataZoom, dataZoom, optionsDataZoom) {
+    var finalDataZoom = Array.isArray(dataZoom)
+        ? dataZoom // if it's an array, assume that the user has [{...propsToChangeOnX}] OR [ , {...propsToChangeOnY}] OR [{...propsToChangeOnX}, {...propsToChangeOnY}]
+        : [dataZoom, dataZoom]; // else if the user only supplies one dataZoom object, we assume they want the props to apply to both x and y zoom objects
+    var finalOptionsDataZoom = Array.isArray(optionsDataZoom)
+        ? optionsDataZoom
+        : [optionsDataZoom, optionsDataZoom];
+    // merge x dataZoom options
+    var x = __assign(__assign(__assign({}, defaultDataZoom[0]), finalDataZoom[0]), finalOptionsDataZoom === null || finalOptionsDataZoom === void 0 ? void 0 : finalOptionsDataZoom[0]);
+    // merge y dataZoom options
+    var y = __assign(__assign(__assign({}, defaultDataZoom[1]), finalDataZoom[1]), finalOptionsDataZoom[1]);
+    return [x, y];
+}
+function generateDefaultValues(props) {
+    var camera = props.camera, height = props.height, symbol = props.symbol, width = props.width, xAxisData = props.xAxisData, yAxisData = props.yAxisData;
     var defaultGrid = {
         height: "".concat(height, "px"),
         left: 0,
@@ -72,76 +134,100 @@ function createChartOptions(_a) {
         // labels to fixed spacings
         width: "".concat(width, "px"),
     };
-    var customGrid = typeof gridProp === "function" ? gridProp(defaultGrid) : gridProp;
-    return {
-        animation: false,
-        /**
-         * Display reference line and axis value under mouse pointer
-         * https://echarts.apache.org/en/option.html#axisPointer
-         */
-        axisPointer: {
-            label: { show: false },
-            show: true,
-            triggerOn: "mousemove",
+    var defaultAxisPointer = {
+        label: { show: false },
+        show: false,
+        triggerOn: "mousemove",
+    };
+    var defaultXAxis = {
+        axisLabel: { fontSize: 0, rotate: 90 },
+        axisLine: {
+            show: false,
         },
-        dataset: {
-            source: data,
+        axisTick: {
+            show: false,
         },
-        grid: customGrid || defaultGrid,
-        series: [
-            {
-                emphasis: {
-                    itemStyle: {
-                        color: "inherit",
-                    },
-                    scale: false,
-                },
-                encode: encode,
-                itemStyle: itemStyle,
-                legendHoverLink: false,
-                symbolSize: symbolSize,
-                type: "scatter",
-            },
-        ],
-        xAxis: [
-            {
-                axisLabel: { fontSize: 0, rotate: 90 },
-                axisLine: {
-                    show: false,
-                },
-                axisTick: {
-                    show: false,
-                },
-                boundaryGap: true,
-                data: xAxisData,
-                splitLine: {
-                    show: false,
-                },
-                type: "category",
-            },
-        ],
-        yAxis: [
-            {
-                axisLabel: { fontSize: 0 },
-                axisLine: {
-                    show: false,
-                },
-                axisTick: {
-                    show: false,
-                },
-                boundaryGap: true,
-                data: yAxisData,
-                splitLine: {
-                    show: false,
-                },
-            },
-        ],
+        boundaryGap: true,
+        data: xAxisData,
+        splitLine: {
+            show: false,
+        },
+        type: "category",
+    };
+    var defaultYAxis = {
+        axisLabel: { fontSize: 0 },
+        axisLine: {
+            show: false,
+        },
+        axisTick: {
+            show: false,
+        },
+        boundaryGap: true,
+        data: yAxisData,
+        splitLine: {
+            show: false,
+        },
+    };
+    var defaultEmphasis = {
+        itemStyle: {
+            borderColor: symbol === "circle" ? "black" : "white",
+            borderType: "solid",
+            borderWidth: symbol === "circle" ? 2 : 4,
+            opacity: 1,
+        },
+        scale: false,
+    };
+    var defaultCamera = {
+        height: camera && camera.height ? camera.height : 20,
+        width: camera && camera.width ? camera.width : 40,
+    };
+    var defaultDataZoom = [
+        {
+            // end index of the x axis window
+            endValue: defaultCamera.width - 1,
+            filterMode: "filter",
+            moveOnMouseMove: true,
+            // There's a PR to allow touchpad panning
+            // https://github.com/apache/echarts/pull/19352
+            moveOnMouseWheel: false,
+            orient: "horizontal",
+            preventDefaultMouseMove: true,
+            // start index of the x axis window
+            startValue: 0,
+            throttle: 0,
+            type: "inside",
+            xAxisIndex: 0,
+            zoomOnMouseWheel: false,
+        },
+        {
+            // end index of the y axis window
+            endValue: defaultCamera.height - 1,
+            filterMode: "filter",
+            moveOnMouseMove: true,
+            moveOnMouseWheel: true,
+            orient: "vertical",
+            preventDefaultMouseMove: true,
+            // start index of the y axis window
+            startValue: 0,
+            throttle: 0,
+            type: "inside",
+            yAxisIndex: 0,
+            zoomOnMouseWheel: false,
+        },
+    ];
+    return {
+        defaultAxisPointer: defaultAxisPointer,
+        defaultDataZoom: defaultDataZoom,
+        defaultEmphasis: defaultEmphasis,
+        defaultGrid: defaultGrid,
+        defaultXAxis: defaultXAxis,
+        defaultYAxis: defaultYAxis,
     };
 }
 
 var UPDATE_THROTTLE_MS = 1 * 100;
 function useUpdateChart(_a) {
-    var chart = _a.chart, data = _a.data, xAxisData = _a.xAxisData, yAxisData = _a.yAxisData, width = _a.width, height = _a.height, encode = _a.encode, itemStyle = _a.itemStyle, symbolSize = _a.symbolSize, grid = _a.grid;
+    var axisPointer = _a.axisPointer, camera = _a.camera, chart = _a.chart, data = _a.data, emphasis = _a.emphasis, xAxisData = _a.xAxisData, yAxisData = _a.yAxisData, width = _a.width, height = _a.height, encode = _a.encode, itemStyle = _a.itemStyle, symbol = _a.symbol, symbolSize = _a.symbolSize, grid = _a.grid, options = _a.options, onEvents = _a.onEvents;
     var throttledUpdateChart = react.useMemo(function () {
         return lodash.throttle(function () {
             if (!chart || !data || !xAxisData || !yAxisData) {
@@ -150,32 +236,67 @@ function useUpdateChart(_a) {
             // (thuang): resize() needs to be called before setOption() to prevent
             // TypeError: Cannot read properties of undefined (reading 'shouldBePainted')
             chart.resize();
-            chart.setOption(createChartOptions({
+            var chartOptions = createChartOptions({
+                axisPointer: axisPointer,
+                camera: camera,
                 data: data,
+                emphasis: emphasis,
                 encode: encode,
                 grid: grid,
                 height: height,
                 itemStyle: itemStyle,
+                options: options,
+                symbol: symbol,
                 symbolSize: symbolSize,
                 width: width,
                 xAxisData: xAxisData,
                 yAxisData: yAxisData,
-            }));
+            });
+            chart.setOption(chartOptions, {
+                replaceMerge: ["dataZoom", "tooltip"],
+            });
+            /**
+             * We need to remove old event listeners and bind new ones to
+             * make sure that the event listeners are updated when the props change.
+             */
+            if (onEvents) {
+                var _loop_1 = function (eventName) {
+                    if (Object.prototype.hasOwnProperty.call(onEvents, eventName) &&
+                        typeof eventName === "string" &&
+                        typeof onEvents[eventName] === "function") {
+                        // Remove old event listener
+                        chart.off(eventName);
+                        // Add new event listener
+                        chart.on(eventName, function (event) {
+                            onEvents[eventName](event, chart);
+                        });
+                    }
+                };
+                for (var eventName in onEvents) {
+                    _loop_1(eventName);
+                }
+            }
         }, UPDATE_THROTTLE_MS, 
         // (thuang): Trailing guarantees that the last call to the function will
         // be executed
         { trailing: true });
     }, [
+        axisPointer,
+        camera,
         chart,
         data,
+        emphasis,
         xAxisData,
         yAxisData,
         width,
         height,
         encode,
         itemStyle,
+        symbol,
         symbolSize,
         grid,
+        options,
+        onEvents,
     ]);
     react.useEffect(function () {
         return function () { return throttledUpdateChart.cancel(); };
@@ -184,8 +305,11 @@ function useUpdateChart(_a) {
     react.useEffect(function () {
         throttledUpdateChart();
     }, [
+        axisPointer,
+        camera,
         chart,
         data,
+        emphasis,
         xAxisData,
         yAxisData,
         throttledUpdateChart,
@@ -193,8 +317,11 @@ function useUpdateChart(_a) {
         height,
         encode,
         itemStyle,
+        symbol,
         symbolSize,
         grid,
+        options,
+        onEvents,
     ]);
 }
 
@@ -205,49 +332,121 @@ function getWidthAndHeight(_a) {
 }
 var templateObject_1;
 
-function HeatmapChart(props, ref) {
-    var width = props.width, height = props.height, _a = props.echartsRendererMode, echartsRendererMode = _a === void 0 ? "canvas" : _a, onChartMouseMove = props.onChartMouseMove, xAxisData = props.xAxisData, yAxisData = props.yAxisData, data = props.data, encode = props.encode, itemStyle = props.itemStyle, _b = props.symbolSize, symbolSize = _b === void 0 ? 5 : _b, grid = props.grid, rest = __rest(props, ["width", "height", "echartsRendererMode", "onChartMouseMove", "xAxisData", "yAxisData", "data", "encode", "itemStyle", "symbolSize", "grid"]);
+var HeatmapChart = react.forwardRef(function (props, ref
+// eslint-disable-next-line sonarjs/cognitive-complexity
+) {
+    var axisPointer = props.axisPointer, width = props.width, height = props.height, _a = props.echartsRendererMode, echartsRendererMode = _a === void 0 ? "svg" : _a, camera = props.camera, onEvents = props.onEvents, xAxisData = props.xAxisData, yAxisData = props.yAxisData, data = props.data, encode = props.encode, emphasis = props.emphasis, itemStyle = props.itemStyle, symbol = props.symbol, _b = props.symbolSize, symbolSize = _b === void 0 ? 5 : _b, grid = props.grid, options = props.options, rest = __rest(props, ["axisPointer", "width", "height", "echartsRendererMode", "camera", "onEvents", "xAxisData", "yAxisData", "data", "encode", "emphasis", "itemStyle", "symbol", "symbolSize", "grid", "options"]);
+    // Validate width and height
     if (!width || !height) {
         throw Error("Chart must have width and height > 0");
     }
-    var _c = react.useState(false), isChartInitialized = _c[0], setIsChartInitialized = _c[1];
-    var _d = react.useState(null), chart = _d[0], setChart = _d[1];
+    // Ref for the chart container
     var innerRef = react.useRef(null);
-    // Initialize charts
-    react.useEffect(function () {
+    /**
+     * (thuang): We need both a state and a ref to store the chart instance, so
+     * some hooks can opt out of re-rendering when the chart instance changes.
+     */
+    var _c = react.useState(null), chart = _c[0], setChart = _c[1];
+    var chartRef = react.useRef(chart);
+    /**
+     * (thuang): Use this ref to store the onEvents prop to prevent
+     * unnecessary re-renders when the onEvents prop changes.
+     * NOTE: This implies that `onEvents` prop changes alone from the parent
+     * won't re-render the chart
+     */
+    var onEventsRef = react.useRef(onEvents);
+    /**
+     * (thuang): Use this function to dispose the chart instance for both
+     * the state and the ref. This is to prevent memory leaks.
+     */
+    var disposeChart = react.useCallback(function () {
+        var _a;
+        (_a = chartRef.current) === null || _a === void 0 ? void 0 : _a.dispose();
+        chartRef.current = null;
+        setChart(null);
+    }, []);
+    // Function to initialize the chart
+    var initChart = react.useCallback(function () {
+        var onEventsCurrent = onEventsRef.current;
         var current = innerRef.current;
         if (!current ||
-            isChartInitialized ||
+            chartRef.current ||
             // (thuang): echart's `init()` will throw error if the container has 0 width or height
             (current === null || current === void 0 ? void 0 : current.getAttribute("height")) === "0" ||
             (current === null || current === void 0 ? void 0 : current.getAttribute("width")) === "0") {
             return;
         }
-        setIsChartInitialized(true);
+        // Initialize ECharts instance
         var rawChart = echarts.init(current, EMPTY_OBJECT, {
             renderer: echartsRendererMode,
             useDirtyRect: true,
         });
-        if (onChartMouseMove) {
-            rawChart.getZr().on("mousemove", function (event) {
-                onChartMouseMove(event, rawChart);
-            });
+        // Bind events if provided
+        if (onEventsCurrent) {
+            bindEvents(rawChart, onEventsCurrent);
         }
         setChart(rawChart);
-    }, [innerRef, isChartInitialized, echartsRendererMode, onChartMouseMove]);
+        chartRef.current = rawChart;
+        // Cleanup function
+        return function () {
+            disposeChart();
+            // Unbind events if provided
+            if (onEventsCurrent) {
+                for (var eventName in onEventsCurrent) {
+                    if (Object.prototype.hasOwnProperty.call(onEventsCurrent, eventName) &&
+                        typeof eventName === "string" &&
+                        typeof onEventsCurrent[eventName] === "function") {
+                        rawChart.off(eventName, onEventsCurrent[eventName]);
+                    }
+                }
+            }
+        };
+    }, [echartsRendererMode, disposeChart]);
+    // Initialize charts on component mount
+    react.useEffect(function () {
+        disposeChart();
+        initChart();
+    }, [initChart, disposeChart]);
+    // Hook to update chart data and options
     useUpdateChart({
+        axisPointer: axisPointer,
+        camera: camera,
         chart: chart,
         data: data,
+        emphasis: emphasis,
         encode: encode,
         grid: grid,
         height: height,
         itemStyle: itemStyle,
+        onEvents: onEvents,
+        options: options,
+        symbol: symbol,
         symbolSize: symbolSize,
         width: width,
         xAxisData: xAxisData,
         yAxisData: yAxisData,
     });
+    // Render the chart container
     return (jsxRuntime.jsx(ChartContainer, __assign({ height: height, width: width, ref: handleRef }, rest)));
+    // Function to bind events to the ECharts instance
+    function bindEvents(instance, events) {
+        function innerBindEvent(eventName, func) {
+            // Ignore invalid event configurations
+            if (typeof eventName === "string" && typeof func === "function") {
+                // Bind event
+                instance.on(eventName, function (param) {
+                    func(param, instance);
+                });
+            }
+        }
+        // Loop through events and bind them
+        for (var eventName in events) {
+            if (Object.prototype.hasOwnProperty.call(events, eventName)) {
+                innerBindEvent(eventName, events[eventName]);
+            }
+        }
+    }
+    // Function to handle the ref of the chart container
     function handleRef(element) {
         innerRef.current = element;
         if (!ref)
@@ -260,7 +459,7 @@ function HeatmapChart(props, ref) {
             ref.current = element;
         }
     }
-}
-var index = react.memo(react.forwardRef(HeatmapChart));
+});
+var index = react.memo(HeatmapChart);
 
 exports.HeatmapChart = index;