@hsu-react/ui 2.4.0 → 2.4.2

package/lib/components/Chart/Polar/index.js

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var echarts = _interopRequireWildcard(require("echarts"));
+var _useContainerReady = _interopRequireDefault(require("../_hooks/useContainerReady"));
 var _react = _interopRequireWildcard(require("react"));
 var _indexModule = _interopRequireDefault(require("../index.module.scss"));
 var _jsxRuntime = require("react/jsx-runtime");
@@ -30,6 +31,8 @@ const Polar = props => {
   } = props;
   const chartRef = (0, _react.useRef)(null);
   const chartInstanceRef = (0, _react.useRef)(null);
+  // Defers `echarts.init` until the container has a box — see the hook for why
+  const containerReady = (0, _useContainerReady.default)(chartRef);
   const resizeObserverRef = (0, _react.useRef)(null);
 
   // Cache the chart option with useMemo
@@ -144,12 +147,16 @@ const Polar = props => {
 
   // Callback handling chart resize
   const handleResize = (0, _react.useCallback)(() => {
+    // A keep-alive tab losing focus fires the observer with a 0×0 box; resizing to that throws
+    // the laid-out canvas away and it has to be rebuilt when the tab comes back
+    const el = chartRef.current;
+    if (!el || el.clientWidth === 0 || el.clientHeight === 0) return;
     chartInstanceRef.current?.resize();
   }, []);
 
   // Initialize the chart
   (0, _react.useEffect)(() => {
-    if (!chartRef.current) return;
+    if (!chartRef.current || !containerReady) return;
 
     // Initialize a new instance or reuse the existing one
     let chart = chartInstanceRef.current;
@@ -174,7 +181,7 @@ const Polar = props => {
     return () => {
       window.removeEventListener("resize", handleResize);
     };
-  }, [chartOption, handleResize]);
+  }, [chartOption, handleResize, containerReady]);
 
   // Clean up resources on unmount
   (0, _react.useEffect)(() => {

package/lib/components/Chart/Radar/index.js

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var echarts = _interopRequireWildcard(require("echarts"));
+var _useContainerReady = _interopRequireDefault(require("../_hooks/useContainerReady"));
 var _react = _interopRequireWildcard(require("react"));
 var _indexModule = _interopRequireDefault(require("../index.module.scss"));
 var _jsxRuntime = require("react/jsx-runtime");
@@ -33,6 +34,8 @@ const Radar = props => {
   } = props;
   const chartRef = (0, _react.useRef)(null);
   const chartInstanceRef = (0, _react.useRef)(null);
+  // Defers `echarts.init` until the container has a box — see the hook for why
+  const containerReady = (0, _useContainerReady.default)(chartRef);
   const resizeObserverRef = (0, _react.useRef)(null);
   const hoveredIndicatorRef = (0, _react.useRef)(-1);
   const singleIndicatorEnabled = Boolean(singleIndicatorTooltipProp) && singleIndicatorMode !== undefined;
@@ -144,10 +147,14 @@ const Radar = props => {
     return option;
   }, [indicators, data, color, name, radar, series, coreOption, singleIndicatorEnabled, singleIndicatorFormatter, singleIndicatorRegion]);
   const handleResize = (0, _react.useCallback)(() => {
+    // A keep-alive tab losing focus fires the observer with a 0×0 box; resizing to that throws
+    // the laid-out canvas away and it has to be rebuilt when the tab comes back
+    const el = chartRef.current;
+    if (!el || el.clientWidth === 0 || el.clientHeight === 0) return;
     chartInstanceRef.current?.resize();
   }, []);
   (0, _react.useEffect)(() => {
-    if (!chartRef.current) return;
+    if (!chartRef.current || !containerReady) return;
     let chart = chartInstanceRef.current;
     if (!chart) {
       chart = echarts.init(chartRef.current);
@@ -263,7 +270,7 @@ const Radar = props => {
         }
       }
     };
-  }, [chartOption, handleResize, singleIndicatorEnabled, singleIndicatorRegion, singleIndicatorHighlight, singleIndicatorHoverFill, color]);
+  }, [chartOption, handleResize, singleIndicatorEnabled, singleIndicatorRegion, singleIndicatorHighlight, singleIndicatorHoverFill, color, containerReady]);
   (0, _react.useEffect)(() => {
     return () => {
       if (resizeObserverRef.current) {

package/lib/components/Chart/Sankey/index.js

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var _react = _interopRequireWildcard(require("react"));
+var _useContainerReady = _interopRequireDefault(require("../_hooks/useContainerReady"));
 var _indexModule = _interopRequireDefault(require("../index.module.scss"));
 var echarts = _interopRequireWildcard(require("echarts"));
 var _jsxRuntime = require("react/jsx-runtime");
@@ -22,6 +23,8 @@ const Sankey = props => {
   } = props;
   const chartRef = (0, _react.useRef)(null);
   const chartInstanceRef = (0, _react.useRef)(null);
+  // Defers `echarts.init` until the container has a box — see the hook for why
+  const containerReady = (0, _useContainerReady.default)(chartRef);
   const resizeObserverRef = (0, _react.useRef)(null);
 
   // Cache the chart option with useMemo
@@ -103,12 +106,16 @@ const Sankey = props => {
 
   // Callback handling chart resize
   const handleResize = (0, _react.useCallback)(() => {
+    // A keep-alive tab losing focus fires the observer with a 0×0 box; resizing to that throws
+    // the laid-out canvas away and it has to be rebuilt when the tab comes back
+    const el = chartRef.current;
+    if (!el || el.clientWidth === 0 || el.clientHeight === 0) return;
     chartInstanceRef.current?.resize();
   }, []);
 
   // Initialize the chart
   (0, _react.useEffect)(() => {
-    if (!chartRef.current) return;
+    if (!chartRef.current || !containerReady) return;
 
     // Initialize a new instance or reuse the existing one
     let chart = chartInstanceRef.current;
@@ -142,7 +149,7 @@ const Sankey = props => {
     return () => {
       window.removeEventListener("resize", handleResize);
     };
-  }, [chartOption, handleResize, getImage]);
+  }, [chartOption, handleResize, getImage, containerReady]);
 
   // Clean up resources on unmount
   (0, _react.useEffect)(() => {

package/lib/components/Chart/Tree/index.js

@@ -5,6 +5,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var _react = _interopRequireWildcard(require("react"));
+var _useContainerReady = _interopRequireDefault(require("../_hooks/useContainerReady"));
 var _indexModule = _interopRequireDefault(require("../index.module.scss"));
 var echarts = _interopRequireWildcard(require("echarts"));
 var _hsuUtils = require("hsu-utils");
@@ -23,6 +24,8 @@ const Tree = props => {
   } = props;
   const chartRef = (0, _react.useRef)(null);
   const chartInstanceRef = (0, _react.useRef)(null);
+  // Defers `echarts.init` until the container has a box — see the hook for why
+  const containerReady = (0, _useContainerReady.default)(chartRef);
   const resizeObserverRef = (0, _react.useRef)(null);
 
   // Cache the chart option with useMemo
@@ -43,12 +46,16 @@ const Tree = props => {
 
   // Callback handling chart resize
   const handleResize = (0, _react.useCallback)(() => {
+    // A keep-alive tab losing focus fires the observer with a 0×0 box; resizing to that throws
+    // the laid-out canvas away and it has to be rebuilt when the tab comes back
+    const el = chartRef.current;
+    if (!el || el.clientWidth === 0 || el.clientHeight === 0) return;
     chartInstanceRef.current?.resize();
   }, []);
 
   // Initialize the chart
   (0, _react.useEffect)(() => {
-    if (!chartRef.current) return;
+    if (!chartRef.current || !containerReady) return;
 
     // Initialize a new instance or reuse the existing one
     let chart = chartInstanceRef.current;
@@ -82,7 +89,7 @@ const Tree = props => {
     return () => {
       window.removeEventListener("resize", handleResize);
     };
-  }, [chartOption, handleResize, getImage]);
+  }, [chartOption, handleResize, getImage, containerReady]);
 
   // Clean up resources on unmount
   (0, _react.useEffect)(() => {

package/lib/components/Chart/_hooks/useContainerReady.d.ts

@@ -0,0 +1,18 @@
+import { RefObject } from "react";
+/**
+ * Whether the referenced element has a non-zero box yet.
+ *
+ * `echarts.init` on a 0×0 element logs `Can't get DOM width or height` and builds a canvas with no
+ * size, recovering only on the next `resize()`. A chart hits that path whenever it mounts before
+ * layout has given it space — inside a keep-alive tab that is not the active one, a collapsed
+ * panel, a modal that has not opened yet — so consuming apps see the warning for charts that end
+ * up rendering perfectly well.
+ *
+ * Gating `init` on this flag defers it to the first frame the element actually occupies space.
+ *
+ * It **latches**: once measured, the element going back to 0×0 (a keep-alive tab losing focus)
+ * must not read as "not ready" again, or the init effect would tear the chart down and re-create
+ * it on every tab switch.
+ */
+declare const useContainerReady: (ref: RefObject<HTMLElement | null>) => boolean;
+export default useContainerReady;

package/lib/components/Chart/_hooks/useContainerReady.js

@@ -0,0 +1,51 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _react = require("react");
+/**
+ * Whether the referenced element has a non-zero box yet.
+ *
+ * `echarts.init` on a 0×0 element logs `Can't get DOM width or height` and builds a canvas with no
+ * size, recovering only on the next `resize()`. A chart hits that path whenever it mounts before
+ * layout has given it space — inside a keep-alive tab that is not the active one, a collapsed
+ * panel, a modal that has not opened yet — so consuming apps see the warning for charts that end
+ * up rendering perfectly well.
+ *
+ * Gating `init` on this flag defers it to the first frame the element actually occupies space.
+ *
+ * It **latches**: once measured, the element going back to 0×0 (a keep-alive tab losing focus)
+ * must not read as "not ready" again, or the init effect would tear the chart down and re-create
+ * it on every tab switch.
+ */
+const useContainerReady = ref => {
+  const [ready, setReady] = (0, _react.useState)(false);
+  (0, _react.useEffect)(() => {
+    if (ready) return;
+    const el = ref.current;
+    if (!el) return;
+    const measure = () => {
+      const {
+        width,
+        height
+      } = el.getBoundingClientRect();
+      if (width > 0 && height > 0) {
+        setReady(true);
+        return true;
+      }
+      return false;
+    };
+
+    // Already laid out on mount — the common case, and it must not cost an extra frame
+    if (measure()) return;
+    const observer = new ResizeObserver(() => {
+      if (measure()) observer.disconnect();
+    });
+    observer.observe(el);
+    return () => observer.disconnect();
+  }, [ready, ref]);
+  return ready;
+};
+var _default = exports.default = useContainerReady;

package/lib/components/Chart/_utils/cartesian.d.ts

@@ -1,5 +1,6 @@
 import * as echarts from "echarts";
 import { ChartOptionType, SeriesDataType } from "..";
+import { ChartChrome } from "./chartTheme";
 export interface ChartScrollConfig {
     enabled?: boolean;
     autoScroll?: boolean;
@@ -29,8 +30,8 @@ export interface DataZoomIndexWindow {
  * percentages produced by native echarts interactions are rounded outward, so each boundary may include at most one extra item, without affecting the axis magnitude.
  */
 export declare const percentWindowToIndexWindow: (startPercent: number, endPercent: number, total: number) => DataZoomIndexWindow;
-export declare const createDefaultCategoryXAxis: (xAxisData?: Array<string>) => ChartOptionType;
-export declare const createDefaultValueYAxis: (mode?: "bar" | "line") => ChartOptionType;
+export declare const createDefaultCategoryXAxis: (xAxisData: Array<string> | undefined, chrome: ChartChrome) => ChartOptionType;
+export declare const createDefaultValueYAxis: (mode: "bar" | "line" | undefined, chrome: ChartChrome) => ChartOptionType;
 export declare const buildCartesianSeriesOptions: (mode: "bar" | "line", seriesData?: SeriesDataType, series?: echarts.SeriesOption | echarts.SeriesOption[]) => echarts.SeriesOption[];
 export declare const getSliderShow: (zoom?: echarts.DataZoomComponentOption | Record<string, unknown>) => boolean | undefined;
 export declare const resolveScrollConfig: (scrollConfig?: ChartScrollConfig) => NormalizedScrollConfig;

package/lib/components/Chart/_utils/cartesian.js

@@ -24,34 +24,32 @@ const percentWindowToIndexWindow = (startPercent, endPercent, total) => {
   };
 };
 exports.percentWindowToIndexWindow = percentWindowToIndexWindow;
-const createDefaultCategoryXAxis = xAxisData => ({
+const createDefaultCategoryXAxis = (xAxisData, chrome) => ({
   type: "category",
   boundaryGap: true,
   data: xAxisData,
   axisLabel: {
     interval: 0,
     hideOverlap: true,
-    textStyle: {
-      fontSize: 14,
-      color: "#373D48"
-    }
+    // echarts removed the `textStyle` nesting under `axisLabel` in v4: keeping it means both
+    // properties are silently dropped *and* a deprecation warning is logged on every render.
+    fontSize: chrome.fontSize,
+    color: chrome.axis
   },
   axisTick: {
     show: false
   }
 });
 exports.createDefaultCategoryXAxis = createDefaultCategoryXAxis;
-const createDefaultValueYAxis = (mode = "bar") => ({
+const createDefaultValueYAxis = (mode = "bar", chrome) => ({
   type: "value",
   axisLabel: {
-    textStyle: {
-      fontSize: 14,
-      color: "#373D48"
-    }
+    fontSize: chrome.fontSize,
+    color: chrome.axis
   },
   splitLine: mode === "line" ? {
     lineStyle: {
-      color: "#C9CED6",
+      color: chrome.splitLine,
       type: "dashed"
     }
   } : {

package/lib/components/Chart/_utils/chartTheme.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Colours for the chart *chrome* — axis ticks, split lines, legend labels.
+ *
+ * echarts options are plain JS, so they cannot read the `--vita-*` CSS variables the rest of the
+ * library styles itself with; the literal values have to be resolved here instead. These used to
+ * be hard-coded to a light-mode slate (`#373D48` / `#C9CED6`), which left every axis and legend
+ * nearly invisible once the page switched to the dark palette.
+ *
+ * The plotted data is deliberately *not* covered here: series colours come from echarts' own
+ * palette or from whatever the caller passes as `color`, and both read fine on either background.
+ */
+export interface ChartChrome {
+    /** Legend labels — a real label, so it sits on the foreground ramp */
+    text: string;
+    /** Axis tick labels — secondary information, one step down */
+    axis: string;
+    /** Split lines behind the plot area */
+    splitLine: string;
+    /** Base font size, same scale the rest of the library uses */
+    fontSize: number;
+}
+export declare const resolveChartChrome: (dark: boolean) => ChartChrome;

package/lib/components/Chart/_utils/chartTheme.js

@@ -0,0 +1,29 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.resolveChartChrome = void 0;
+var _tokens = require("../../../styles/tokens");
+/**
+ * Colours for the chart *chrome* — axis ticks, split lines, legend labels.
+ *
+ * echarts options are plain JS, so they cannot read the `--vita-*` CSS variables the rest of the
+ * library styles itself with; the literal values have to be resolved here instead. These used to
+ * be hard-coded to a light-mode slate (`#373D48` / `#C9CED6`), which left every axis and legend
+ * nearly invisible once the page switched to the dark palette.
+ *
+ * The plotted data is deliberately *not* covered here: series colours come from echarts' own
+ * palette or from whatever the caller passes as `color`, and both read fine on either background.
+ */
+
+const resolveChartChrome = dark => {
+  const t = dark ? _tokens.darkTokens : _tokens.lightTokens;
+  return {
+    text: t.foreground,
+    axis: t.mutedForeground,
+    splitLine: t.border,
+    fontSize: _tokens.fontTokens.size
+  };
+};
+exports.resolveChartChrome = resolveChartChrome;

package/lib/components/Chart/_utils/heatmap.d.ts

@@ -1,3 +1,4 @@
 import { ChartOptionType } from "..";
-export declare const createDefaultHeatmapXAxis: (xAxisData?: string[]) => ChartOptionType;
-export declare const createDefaultHeatmapYAxis: (yAxisData?: string[]) => ChartOptionType;
+import { ChartChrome } from "./chartTheme";
+export declare const createDefaultHeatmapXAxis: (xAxisData: string[] | undefined, chrome: ChartChrome) => ChartOptionType;
+export declare const createDefaultHeatmapYAxis: (yAxisData: string[] | undefined, chrome: ChartChrome) => ChartOptionType;

package/lib/components/Chart/_utils/heatmap.js

@@ -4,7 +4,7 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.createDefaultHeatmapYAxis = exports.createDefaultHeatmapXAxis = void 0;
-const createDefaultHeatmapXAxis = xAxisData => ({
+const createDefaultHeatmapXAxis = (xAxisData, chrome) => ({
   type: "category",
   data: xAxisData,
   splitArea: {
@@ -13,27 +13,24 @@ const createDefaultHeatmapXAxis = xAxisData => ({
   axisLabel: {
     interval: 0,
     hideOverlap: true,
-    textStyle: {
-      fontSize: 14,
-      color: "#373D48"
-    }
+    // See the note in `cartesian.ts`: `axisLabel.textStyle` has been deprecated since echarts 4
+    fontSize: chrome.fontSize,
+    color: chrome.axis
   },
   axisTick: {
     show: false
   }
 });
 exports.createDefaultHeatmapXAxis = createDefaultHeatmapXAxis;
-const createDefaultHeatmapYAxis = yAxisData => ({
+const createDefaultHeatmapYAxis = (yAxisData, chrome) => ({
   type: "category",
   data: yAxisData,
   splitArea: {
     show: true
   },
   axisLabel: {
-    textStyle: {
-      fontSize: 14,
-      color: "#373D48"
-    }
+    fontSize: chrome.fontSize,
+    color: chrome.axis
   },
   axisTick: {
     show: false

package/lib/components/Panel/ListPanel/ListModalPanel/index.module.scss

@@ -21,8 +21,18 @@
 
   height: 100%;
 
+  // Inside a modal the Search must not keep its card chrome. On a page it is an outlined white
+  // card standing on the grey page background; in a modal the body is already `--vita-surface`,
+  // so the same treatment paints a white card on white and only the border survives — a stray
+  // outline around the search row. The padding was already being cleared here; the background and
+  // border are the other half of the same intent, and `.tableContainer` below is flush for
+  // exactly this reason.
   .search {
     padding: 0px;
+
+    background: transparent;
+
+    border: none;
   }
 
   .tableContainer {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hsu-react/ui",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "description": "一套基于 React + Ant Design 的中后台业务组件库",
   "license": "MIT",
   "type": "module",

package/src/components/Chart/Bar/index.tsx

@@ -1,4 +1,5 @@
 import * as echarts from "echarts";
+import useContainerReady from "../_hooks/useContainerReady";
 
 import {
   ChartCommonProps,
@@ -21,6 +22,8 @@ import {
   percentWindowToIndexWindow,
   resolveScrollConfig,
 } from "../_utils/cartesian";
+import { resolveChartChrome } from "../_utils/chartTheme";
+import useIsDark from "../../../hooks/useIsDark";
 
 export interface ChartBarProps extends ChartCommonProps {
   chartTitle?: string;
@@ -70,6 +73,8 @@ const ChartBar: React.FC<ChartBarProps> = (props) => {
   } = props;
   const chartRef = useRef<HTMLDivElement>(null);
   const chartInstanceRef = useRef<echarts.ECharts | null>(null);
+  // Defers `echarts.init` until the container has a box — see the hook for why
+  const containerReady = useContainerReady(chartRef);
   const resizeObserverRef = useRef<ResizeObserver | null>(null);
   const prevXAxisKeyRef = useRef<string | null>(null);
   const legendScrollRef = useRef<ReturnType<typeof autoScrollLegend> | null>(
@@ -79,11 +84,15 @@ const ChartBar: React.FC<ChartBarProps> = (props) => {
     () => resolveScrollConfig(scrollConfig),
     [scrollConfig],
   );
+  // echarts options are plain JS and cannot read the `--vita-*` variables, so the axis and
+  // legend colours have to be resolved against the active appearance here
+  const isDark = useIsDark();
+  const chrome = useMemo(() => resolveChartChrome(isDark), [isDark]);
 
   // Cache the chart option with useMemo
   const chartOption = useMemo(() => {
-    const def_xAxis = createDefaultCategoryXAxis(xAxisData);
-    const def_yAxis = createDefaultValueYAxis("bar");
+    const def_xAxis = createDefaultCategoryXAxis(xAxisData, chrome);
+    const def_yAxis = createDefaultValueYAxis("bar", chrome);
 
     // Process xAxis config
     const processedXAxis = Array.isArray(xAxis)
@@ -212,8 +221,7 @@ const ChartBar: React.FC<ChartBarProps> = (props) => {
           data: legendData,
           icon: "circle",
           textStyle: {
-            color: "#373D48",
-            fontSize: 16,
+            color: chrome.text,
           },
           itemWidth: 8,
           itemHeight: 8,
@@ -259,16 +267,22 @@ const ChartBar: React.FC<ChartBarProps> = (props) => {
     series,
     enableLegendAutoScroll,
     coreOption,
+    chrome,
   ]);
 
   // Callback for handling chart resize
   const handleResize = useCallback(() => {
+    // A keep-alive tab losing focus fires the observer with a 0×0 box; resizing to that throws
+    // the laid-out canvas away and it has to be rebuilt when the tab comes back
+    const el = chartRef.current;
+    if (!el || el.clientWidth === 0 || el.clientHeight === 0) return;
+
     chartInstanceRef.current?.resize();
   }, []);
 
   // Initialize the chart
   useEffect(() => {
-    if (!chartRef.current) return;
+    if (!chartRef.current || !containerReady) return;
 
     // Initialize or reuse the existing instance
     let chart = chartInstanceRef.current;
@@ -463,6 +477,7 @@ const ChartBar: React.FC<ChartBarProps> = (props) => {
     legendScrollInterval,
     // 图例是否接管滚轮由它推导，漏了会拿到过期的滚动配置
     normalizedScroll,
+    containerReady,
   ]);
 
   // Handle auto play

package/src/components/Chart/Common/index.tsx

@@ -1,4 +1,5 @@
 import React, { useCallback, useEffect, useMemo, useRef } from "react";
+import useContainerReady from "../_hooks/useContainerReady";
 import styles from "../index.module.scss";
 import { ChartCommonProps, ChartOptionType, ChartsOption } from "..";
 import * as echarts from "echarts";
@@ -7,6 +8,8 @@ const Common: React.FC<ChartCommonProps> = (props) => {
   const { className, style, onChart, ...coreOption } = props;
   const chartRef = useRef<HTMLDivElement>(null);
   const chartInstanceRef = useRef<echarts.ECharts | null>(null);
+  // Defers `echarts.init` until the container has a box — see the hook for why
+  const containerReady = useContainerReady(chartRef);
   const resizeObserverRef = useRef<ResizeObserver | null>(null);
 
   // Cache the chart configuration with useMemo
@@ -20,12 +23,17 @@ const Common: React.FC<ChartCommonProps> = (props) => {
 
   // Callback that handles chart resize
   const handleResize = useCallback(() => {
+    // A keep-alive tab losing focus fires the observer with a 0×0 box; resizing to that throws
+    // the laid-out canvas away and it has to be rebuilt when the tab comes back
+    const el = chartRef.current;
+    if (!el || el.clientWidth === 0 || el.clientHeight === 0) return;
+
     chartInstanceRef.current?.resize();
   }, []);
 
   // Initialize the chart
   useEffect(() => {
-    if (!chartRef.current) return;
+    if (!chartRef.current || !containerReady) return;
 
     // Initialize or reuse an existing instance
     let chart = chartInstanceRef.current;
@@ -53,7 +61,9 @@ const Common: React.FC<ChartCommonProps> = (props) => {
     return () => {
       window.removeEventListener("resize", handleResize);
     };
-  }, [chartOption, handleResize, onChart]);
+  }, [chartOption, handleResize, onChart,
+    containerReady,
+  ]);
 
   // Clean up resources on component unmount
   useEffect(() => {

package/src/components/Chart/Gauge/index.tsx

@@ -1,4 +1,5 @@
 import * as echarts from "echarts";
+import useContainerReady from "../_hooks/useContainerReady";
 
 import {
   ChartCommonProps,
@@ -31,6 +32,8 @@ const Gauge: React.FC<ChartGaugeProps> = (props) => {
   } = series as echarts.GaugeSeriesOption;
   const chartRef = useRef<HTMLDivElement>(null);
   const chartInstanceRef = useRef<echarts.ECharts | null>(null);
+  // Defers `echarts.init` until the container has a box — see the hook for why
+  const containerReady = useContainerReady(chartRef);
   const resizeObserverRef = useRef<ResizeObserver | null>(null);
 
   // Cache the chart option with useMemo
@@ -104,12 +107,17 @@ const Gauge: React.FC<ChartGaugeProps> = (props) => {
 
   // Callback for handling chart resize
   const handleResize = useCallback(() => {
+    // A keep-alive tab losing focus fires the observer with a 0×0 box; resizing to that throws
+    // the laid-out canvas away and it has to be rebuilt when the tab comes back
+    const el = chartRef.current;
+    if (!el || el.clientWidth === 0 || el.clientHeight === 0) return;
+
     chartInstanceRef.current?.resize();
   }, []);
 
   // Initialize the chart
   useEffect(() => {
-    if (!chartRef.current) return;
+    if (!chartRef.current || !containerReady) return;
 
     // Initialize or reuse the existing instance
     let chart = chartInstanceRef.current;
@@ -134,7 +142,9 @@ const Gauge: React.FC<ChartGaugeProps> = (props) => {
     return () => {
       window.removeEventListener("resize", handleResize);
     };
-  }, [chartOption, handleResize]);
+  }, [chartOption, handleResize,
+    containerReady,
+  ]);
 
   // Clean up resources when the component unmounts
   useEffect(() => {