@fses/workbench-app 0.2.0 → 0.2.2

package/node_modules/@fses/workbench-card/src/renderers/chart/echartsRuntimeInteractions.ts

@@ -0,0 +1,450 @@
+/**
+ * @fileoverview ECharts runtime interaction helpers - shared readability defaults for workbench charts and recommendation previews.
+ * @author seadon
+ * @created 2026-08-08
+ */
+import type { ECharts, EChartsOption } from 'echarts';
+import { withEchartsTooltipPortal } from './echartsTooltipPortal';
+
+const WORKBENCH_BAR_MIN_HEIGHT = 2;
+const WORKBENCH_DONUT_HOVER_LABEL_MAX_FONT_SIZE = 16;
+const WORKBENCH_DONUT_HOVER_GRAPHIC_ID = '__workbench_donut_hover_label__';
+const WORKBENCH_HALF_DONUT_PLACEHOLDER_NAME = '__workbench_half_donut_placeholder__';
+const WORKBENCH_HALF_DONUT_PLACEHOLDER_FLAG = '__workbenchHalfDonutPlaceholder';
+const donutHoverCenterBindings = new WeakMap<ECharts, { option: EChartsOption }>();
+
+/**
+ * Reads a property from a plain object-like option value.
+ * @param value - Candidate object value.
+ * @param key - Property key.
+ * @returns Property value when available.
+ */
+function objectValue(value: unknown, key: string): unknown {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)[key]
+    : undefined;
+}
+
+/**
+ * Checks whether a runtime value is a record.
+ * @param value - Candidate runtime value.
+ * @returns True when the value can be merged as an option record.
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+/**
+ * Reads all series records from an ECharts option.
+ * @param option - Candidate ECharts option.
+ * @returns Series option records.
+ */
+function optionSeriesItems(option: EChartsOption): Record<string, unknown>[] {
+  const series = objectValue(option, 'series');
+  const items = Array.isArray(series) ? series : [series];
+  return items.filter(isRecord);
+}
+
+/**
+ * Caps a numeric option while preserving missing values with a readable default.
+ * @param value - Candidate option value.
+ * @param fallback - Default value used when the option is missing.
+ * @param max - Maximum allowed number.
+ * @returns Capped numeric value or the original non-number value.
+ */
+function cappedRuntimeNumber(value: unknown, fallback: number, max: number): unknown {
+  if (typeof value === 'number' && Number.isFinite(value)) return Math.min(value, max);
+  return value === undefined ? fallback : value;
+}
+
+/**
+ * Checks whether a color is explicitly transparent.
+ * @param value - Candidate color option.
+ * @returns True when the color should not receive visible bar fallbacks.
+ */
+function isTransparentRuntimeColor(value: unknown): boolean {
+  if (typeof value !== 'string') return false;
+  const normalized = value.replace(/\s+/g, '').toLowerCase();
+  return normalized === 'transparent' || normalized === 'rgba(0,0,0,0)' || /rgba\([^,]+,[^,]+,[^,]+,0\)/.test(normalized);
+}
+
+/**
+ * Checks whether a bar series is only used as an invisible layout helper.
+ * @param series - ECharts series option.
+ * @returns True for transparent helper bars such as waterfall offsets.
+ */
+function isTransparentRuntimeBarSeries(series: Record<string, unknown>): boolean {
+  const itemStyle = objectValue(series, 'itemStyle');
+  return isTransparentRuntimeColor(objectValue(series, 'color'))
+    || isTransparentRuntimeColor(objectValue(itemStyle, 'color'));
+}
+
+/**
+ * Checks whether a pie radius value represents a visible inner hole.
+ * @param value - Inner radius option from ECharts pie series.
+ * @returns True when the inner radius is greater than zero.
+ */
+function hasRuntimeInnerRadius(value: unknown): boolean {
+  if (typeof value === 'number') return value > 0;
+  if (typeof value !== 'string') return false;
+  const normalized = value.trim();
+  if (!normalized || normalized === '0' || normalized === '0%') return false;
+  const numeric = Number.parseFloat(normalized);
+  return Number.isFinite(numeric) && numeric > 0;
+}
+
+/**
+ * Checks whether a pie series is rendered as a donut with a center area.
+ * @param series - ECharts series option.
+ * @returns True for donut/ring pie series.
+ */
+function isRuntimeDonutSeries(series: Record<string, unknown>): boolean {
+  if (series.type !== 'pie') return false;
+  const radius = series.radius;
+  return Array.isArray(radius) && hasRuntimeInnerRadius(radius[0]);
+}
+
+/**
+ * Checks whether a pie series declares a partial-ring geometry.
+ * @param series - ECharts pie series option.
+ * @returns True when the series should render as a semi-donut.
+ */
+function isRuntimeHalfDonutSeries(series: Record<string, unknown>): boolean {
+  if (!isRuntimeDonutSeries(series)) return false;
+  return typeof series.startAngle === 'number'
+    && typeof series.endAngle === 'number'
+    && Math.abs(series.endAngle - series.startAngle) > 0
+    && Math.abs(series.endAngle - series.startAngle) <= 180;
+}
+
+/**
+ * Checks whether a pie data item is the internal transparent half-donut filler.
+ * @param value - Candidate ECharts data item.
+ * @returns True for display-only half-donut placeholders.
+ */
+export function isWorkbenchHalfDonutPlaceholderData(value: unknown): boolean {
+  return isRecord(value)
+    && (
+      value[WORKBENCH_HALF_DONUT_PLACEHOLDER_FLAG] === true
+      || value.name === WORKBENCH_HALF_DONUT_PLACEHOLDER_NAME
+    );
+}
+
+/**
+ * Reads the numeric value of a pie data item.
+ * @param value - Candidate ECharts data item.
+ * @returns Finite positive item value, or 0.
+ */
+function pieDataItemValue(value: unknown): number {
+  const raw = isRecord(value) ? value.value : value;
+  const numeric = typeof raw === 'number' ? raw : typeof raw === 'string' ? Number(raw) : Number.NaN;
+  return Number.isFinite(numeric) && numeric > 0 ? numeric : 0;
+}
+
+/**
+ * Creates a transparent filler slice so ECharts 5.x can render half donuts without pie.endAngle support.
+ * @param total - Sum of real pie values.
+ * @returns Internal display-only pie slice.
+ */
+function halfDonutPlaceholderDataItem(total: number): Record<string, unknown> {
+  return {
+    name: WORKBENCH_HALF_DONUT_PLACEHOLDER_NAME,
+    value: total,
+    [WORKBENCH_HALF_DONUT_PLACEHOLDER_FLAG]: true,
+    itemStyle: { color: 'transparent', opacity: 0 },
+    label: { show: false },
+    labelLine: { show: false },
+    emphasis: {
+      disabled: true,
+      itemStyle: { color: 'transparent', opacity: 0 },
+      label: { show: false },
+    },
+    select: { disabled: true },
+    tooltip: { show: false },
+  };
+}
+
+/**
+ * Applies a legacy-safe half-donut structure while preserving real data items.
+ * @param series - ECharts pie series option.
+ * @returns Pie series that renders as a half donut in both ECharts 5.x and 6.x.
+ */
+function withLegacyHalfDonutPieGeometry(series: Record<string, unknown>): Record<string, unknown> {
+  if (!isRuntimeHalfDonutSeries(series) || !Array.isArray(series.data)) return series;
+  const realData = series.data.filter(item => !isWorkbenchHalfDonutPlaceholderData(item));
+  const total = realData.reduce((sum, item) => sum + pieDataItemValue(item), 0);
+  if (total <= 0) return series;
+  const { endAngle: _endAngle, ...portableSeries } = series;
+  return {
+    ...portableSeries,
+    data: [...realData, halfDonutPlaceholderDataItem(total)],
+  };
+}
+
+/**
+ * Keeps donut hover labels centered in the ring instead of floating around slices.
+ * @param series - ECharts series option.
+ * @returns Donut series with centered, bounded emphasis label typography.
+ */
+function withReadablePieHoverLabel(series: Record<string, unknown>): Record<string, unknown> {
+  if (!isRuntimeDonutSeries(series)) return series;
+  const seriesLabel = objectValue(series, 'label');
+  const seriesLabelLine = objectValue(series, 'labelLine');
+  const emphasis = objectValue(series, 'emphasis');
+  const emphasisRecord = isRecord(emphasis) ? emphasis : {};
+  const label = objectValue(emphasisRecord, 'label');
+  const labelRecord = isRecord(label) ? label : {};
+  const {
+    width: _seriesLabelWidth,
+    overflow: _seriesLabelOverflow,
+    ellipsis: _seriesLabelEllipsis,
+    distance: _seriesLabelDistance,
+    distanceToLabelLine: _seriesLabelDistanceToLabelLine,
+    alignTo: _seriesLabelAlignTo,
+    edgeDistance: _seriesLabelEdgeDistance,
+    bleedMargin: _seriesLabelBleedMargin,
+    ...centerSeriesLabel
+  } = isRecord(seriesLabel) ? seriesLabel : {};
+  const {
+    width: _labelWidth,
+    overflow: _labelOverflow,
+    ellipsis: _labelEllipsis,
+    distance: _labelDistance,
+    distanceToLabelLine: _labelDistanceToLabelLine,
+    alignTo: _labelAlignTo,
+    edgeDistance: _labelEdgeDistance,
+    bleedMargin: _labelBleedMargin,
+    ...centerLabel
+  } = labelRecord;
+  return {
+    ...series,
+    label: {
+      ...centerSeriesLabel,
+      show: false,
+      position: 'center',
+      align: 'center',
+      verticalAlign: 'middle',
+      distance: 0,
+      offset: [0, 0],
+      rotate: 0,
+    },
+    labelLine: {
+      ...(isRecord(seriesLabelLine) ? seriesLabelLine : {}),
+      show: false,
+    },
+    labelLayout: {
+      hideOverlap: false,
+    },
+    emphasis: {
+      ...emphasisRecord,
+      label: {
+        ...centerLabel,
+        show: false,
+        position: 'center',
+        align: 'center',
+        verticalAlign: 'middle',
+        distance: 0,
+        offset: [0, 0],
+        rotate: 0,
+        fontSize: cappedRuntimeNumber(centerLabel.fontSize, 14, WORKBENCH_DONUT_HOVER_LABEL_MAX_FONT_SIZE),
+        fontWeight: centerLabel.fontWeight ?? 600,
+        lineHeight: cappedRuntimeNumber(centerLabel.lineHeight, 20, 22),
+      },
+    },
+  };
+}
+
+/**
+ * Gives non-zero bar values a visible footprint in compressed comparison charts.
+ * @param series - ECharts series option.
+ * @returns Bar series with a minimum visible height when appropriate.
+ */
+function withVisibleBarMinimum(series: Record<string, unknown>): Record<string, unknown> {
+  const coordinateSystem = typeof series.coordinateSystem === 'string' ? series.coordinateSystem : '';
+  if (
+    series.type !== 'bar'
+    || (coordinateSystem && coordinateSystem !== 'cartesian2d')
+    || series.barMinHeight !== undefined
+    || isTransparentRuntimeBarSeries(series)
+  ) return series;
+  return {
+    ...series,
+    barMinHeight: WORKBENCH_BAR_MIN_HEIGHT,
+  };
+}
+
+/**
+ * Applies workbench display defaults to all ECharts options before rendering.
+ * @param option - ECharts option from generated, materialized, or script renderers.
+ * @returns Option with generic readability safeguards.
+ */
+export function normalizeWorkbenchChartDisplayDefaults(option: EChartsOption): EChartsOption {
+  const series = objectValue(option, 'series');
+  if (!Array.isArray(series) && !isRecord(series)) return option;
+  const normalizeSeries = (item: unknown) => (
+    isRecord(item) ? withLegacyHalfDonutPieGeometry(withReadablePieHoverLabel(withVisibleBarMinimum(item))) : item
+  );
+  return {
+    ...option,
+    series: Array.isArray(series) ? series.map(normalizeSeries) : normalizeSeries(series),
+  } as EChartsOption;
+}
+
+/**
+ * Reads one series option as a record by index.
+ * @param option - Runtime ECharts option.
+ * @param index - Series index from ECharts event params.
+ * @returns Series option when present.
+ */
+function runtimeSeriesAt(option: EChartsOption, index: number): Record<string, unknown> | null {
+  const series = objectValue(option, 'series');
+  const item = Array.isArray(series) ? series[index] : index === 0 ? series : undefined;
+  return isRecord(item) ? item : null;
+}
+
+/**
+ * Converts an ECharts center coordinate into pixels.
+ * @param value - Center coordinate, number or percentage string.
+ * @param size - Chart width or height.
+ * @returns Pixel coordinate.
+ */
+function chartCenterCoordinate(value: unknown, size: number): number {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string') {
+    const text = value.trim();
+    if (text.endsWith('%')) {
+      const percent = Number.parseFloat(text);
+      if (Number.isFinite(percent)) return size * percent / 100;
+    }
+    const numeric = Number.parseFloat(text);
+    if (Number.isFinite(numeric)) return numeric;
+  }
+  return size / 2;
+}
+
+/**
+ * Converts a pie radius value into pixels.
+ * @param value - Radius coordinate, number or percentage string.
+ * @param chart - Current ECharts instance.
+ * @returns Pixel radius.
+ */
+function chartRadiusCoordinate(value: unknown, chart: ECharts): number {
+  const base = Math.min(chart.getWidth(), chart.getHeight()) / 2;
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string') {
+    const text = value.trim();
+    if (text.endsWith('%')) {
+      const percent = Number.parseFloat(text);
+      if (Number.isFinite(percent)) return base * percent / 100;
+    }
+    const numeric = Number.parseFloat(text);
+    if (Number.isFinite(numeric)) return numeric;
+  }
+  return base * 0.42;
+}
+
+/**
+ * Resolves the center and text width available for a donut hover label.
+ * @param series - Donut series option.
+ * @param chart - Current ECharts instance.
+ * @returns Pixel center and safe text width.
+ */
+function donutHoverCenterGeometry(series: Record<string, unknown>, chart: ECharts): { x: number; y: number; width: number } {
+  const center = Array.isArray(series.center) ? series.center : ['50%', '50%'];
+  const radius = Array.isArray(series.radius) ? series.radius : [];
+  const innerRadius = chartRadiusCoordinate(radius[0], chart);
+  return {
+    x: chartCenterCoordinate(center[0], chart.getWidth()),
+    y: chartCenterCoordinate(center[1], chart.getHeight()),
+    width: Math.max(72, Math.floor(innerRadius * 2 - 12)),
+  };
+}
+
+/**
+ * Writes the centered donut hover label with ECharts graphic so old label layouts cannot pull it outside the ring.
+ * @param chart - Current ECharts instance.
+ * @param option - Runtime ECharts option used by the chart.
+ * @param seriesIndex - Hovered series index.
+ * @param label - Hover label text.
+ */
+function setDonutHoverCenterLabel(chart: ECharts, option: EChartsOption, seriesIndex: number, label: string): void {
+  const series = runtimeSeriesAt(option, seriesIndex);
+  if (!series || !isRuntimeDonutSeries(series) || !label.trim()) return;
+  const geometry = donutHoverCenterGeometry(series, chart);
+  chart.setOption({
+    graphic: [{
+      id: WORKBENCH_DONUT_HOVER_GRAPHIC_ID,
+      type: 'text',
+      x: geometry.x,
+      y: geometry.y,
+      z: 100,
+      silent: true,
+      style: {
+        text: label.trim(),
+        fill: '#1f2937',
+        fontSize: WORKBENCH_DONUT_HOVER_LABEL_MAX_FONT_SIZE,
+        fontWeight: 600,
+        lineHeight: 22,
+        width: geometry.width,
+        overflow: 'break',
+        align: 'center',
+        verticalAlign: 'middle',
+      },
+    }],
+  } as EChartsOption);
+}
+
+/**
+ * Clears the runtime graphic used for donut hover labels.
+ * @param chart - Current ECharts instance.
+ */
+function clearDonutHoverCenterLabel(chart: ECharts): void {
+  chart.setOption({
+    graphic: [{
+      id: WORKBENCH_DONUT_HOVER_GRAPHIC_ID,
+      $action: 'remove',
+    }],
+  } as EChartsOption);
+}
+
+/**
+ * Binds generic donut hover behavior after the final runtime option is set.
+ * @param chart - Current ECharts instance.
+ * @param option - Final runtime ECharts option.
+ */
+export function bindWorkbenchEChartsRuntimeInteractions(chart: ECharts, option: EChartsOption): void {
+  if (!optionSeriesItems(option).some(isRuntimeDonutSeries)) return;
+  const existing = donutHoverCenterBindings.get(chart);
+  if (existing) {
+    existing.option = option;
+    return;
+  }
+  const binding = { option };
+  donutHoverCenterBindings.set(chart, binding);
+  chart.on('mouseover', (params: unknown) => {
+    const eventParams = params as { seriesType?: string; seriesIndex?: number; name?: unknown; data?: unknown };
+    if (eventParams.seriesType !== 'pie' || typeof eventParams.seriesIndex !== 'number') return;
+    if (isWorkbenchHalfDonutPlaceholderData(eventParams.data)) return;
+    const dataName = objectValue(eventParams.data, 'name');
+    const label = typeof eventParams.name === 'string' && eventParams.name.trim()
+      ? eventParams.name
+      : typeof dataName === 'string'
+        ? dataName
+        : '';
+    setDonutHoverCenterLabel(chart, binding.option, eventParams.seriesIndex, label);
+  });
+  chart.on('mouseout', (params: unknown) => {
+    const eventParams = params as { seriesType?: string };
+    if (eventParams.seriesType === 'pie') clearDonutHoverCenterLabel(chart);
+  });
+  chart.on('globalout', () => clearDonutHoverCenterLabel(chart));
+}
+
+/**
+ * Applies the shared workbench ECharts runtime option pipeline.
+ * @param option - Renderable ECharts option.
+ * @returns Option with readability and tooltip interaction defaults.
+ */
+export function prepareWorkbenchEChartsRuntimeOption<T extends EChartsOption>(option: T): T {
+  return withEchartsTooltipPortal(normalizeWorkbenchChartDisplayDefaults(option)) as T;
+}

package/node_modules/@fses/workbench-card/src/renderers/chart/echartsTitle.ts

@@ -0,0 +1,94 @@
+/**
+ * @fileoverview ECharts title helpers - hides inner chart titles already represented by card chrome.
+ * @author seadon
+ * @created 2026-05-20
+ */
+import type { EChartsOption } from 'echarts';
+
+/**
+ * Checks whether a runtime value is a readable object record.
+ * @param value - Candidate value.
+ * @returns True when the value is a non-null object and not an array.
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+/**
+ * Reads title text entries that will be hidden by the outer card chrome.
+ * @param title - ECharts title option.
+ * @returns Hidden title text values.
+ */
+function hiddenTitleTexts(title: unknown): string[] {
+  const titles = Array.isArray(title) ? title : [title];
+  return titles
+    .flatMap((item) => {
+      if (!isRecord(item)) return [];
+      const text = typeof item.text === 'string' ? item.text.trim() : '';
+      return text ? [text] : [];
+    });
+}
+
+/**
+ * Replaces series names that still duplicate a hidden inner ECharts title.
+ * @param series - ECharts series option.
+ * @param titleTexts - Hidden inner title texts.
+ * @param cardTitle - Outer workbench card title.
+ * @returns Series option without hidden template title names.
+ */
+function seriesWithoutHiddenTitleName(
+  series: unknown,
+  titleTexts: string[],
+  cardTitle: string,
+): unknown {
+  if (titleTexts.length === 0 || !cardTitle.trim()) return series;
+  const hiddenNames = new Set(titleTexts.map(text => text.trim()).filter(Boolean));
+  const nextName = cardTitle.trim();
+  const sanitizeOne = (item: unknown) => {
+    if (!isRecord(item)) return item;
+    const name = typeof item.name === 'string' ? item.name.trim() : '';
+    if (!name || !hiddenNames.has(name) || name === nextName) return item;
+    return {
+      ...item,
+      name: nextName,
+    };
+  };
+  return Array.isArray(series) ? series.map(sanitizeOne) : sanitizeOne(series);
+}
+
+/**
+ * Hides ECharts title entries when the outer card title is already present.
+ * @param option - ECharts option.
+ * @param cardTitle - Outer card title.
+ * @returns ECharts option with duplicated inner title hidden.
+ */
+export function hideDuplicateEchartsTitle<T extends EChartsOption | null>(
+  option: T,
+  cardTitle: string | undefined,
+): T {
+  if (!option || !cardTitle) return option;
+
+  const title = (option as Record<string, unknown>).title;
+  const titleTexts = hiddenTitleTexts(title);
+  const series = (option as Record<string, unknown>).series;
+  const nextSeries = seriesWithoutHiddenTitleName(series, titleTexts, cardTitle);
+
+  if (Array.isArray(title)) {
+    const nextTitle = title.map((item) => (
+      item && typeof item === 'object'
+        ? { ...(item as Record<string, unknown>), show: false }
+        : item
+    ));
+    return { ...option, title: nextTitle, series: nextSeries } as T;
+  }
+
+  if (title && typeof title === 'object') {
+    return {
+      ...option,
+      title: { ...(title as Record<string, unknown>), show: false },
+      series: nextSeries,
+    } as T;
+  }
+
+  return option;
+}

package/node_modules/@fses/workbench-card/src/renderers/chart/echartsTooltipPortal.ts

@@ -0,0 +1,140 @@
+/**
+ * @fileoverview ECharts tooltip bounds helpers - keeps chart tooltips readable without expanding page width.
+ * @author seadon
+ * @created 2026-06-23
+ */
+import type { EChartsOption } from 'echarts';
+
+const TOOLTIP_EXTRA_CSS = [
+  'box-sizing: border-box',
+  'max-width: min(420px, calc(100vw - 24px), 100%)',
+  'white-space: normal',
+  'overflow-wrap: anywhere',
+  'word-break: break-word',
+  'line-height: 1.45',
+  'font-size: 12px',
+  'padding: 8px 10px',
+  'border-radius: 4px',
+  'z-index: 10000',
+].join('; ');
+
+/**
+ * Checks whether a runtime value is a plain record.
+ * @param value - Unknown runtime value.
+ * @returns True when the value can be read as an object map.
+ */
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+/**
+ * Keeps tooltip text readable while preserving custom text colors and weights.
+ * @param textStyle - Existing ECharts tooltip text style.
+ * @returns Tooltip text style with compact card-friendly sizing.
+ */
+function withReadableTooltipTextStyle(textStyle: unknown): Record<string, unknown> {
+  const existing = isPlainRecord(textStyle) ? textStyle : {};
+  const fontSize = typeof existing.fontSize === 'number' ? Math.min(existing.fontSize, 12) : 12;
+  const lineHeight = typeof existing.lineHeight === 'number' ? Math.min(existing.lineHeight, 18) : 18;
+  return {
+    ...existing,
+    fontSize,
+    lineHeight,
+  };
+}
+
+/**
+ * Merges ECharts tooltip CSS text without dropping renderer-provided styles.
+ * @param extraCssText - Existing tooltip CSS text.
+ * @returns CSS text with readable wrapping constraints appended.
+ */
+function mergeTooltipExtraCssText(extraCssText: unknown): string {
+  const existing = typeof extraCssText === 'string' ? extraCssText.trim().replace(/;$/, '') : '';
+  return existing ? `${existing}; ${TOOLTIP_EXTRA_CSS};` : `${TOOLTIP_EXTRA_CSS};`;
+}
+
+/**
+ * Positions the tooltip around the cursor without letting it overflow the chart viewport.
+ * @param point - Cursor point supplied by ECharts.
+ * @param _params - ECharts tooltip params.
+ * @param dom - Tooltip DOM element.
+ * @param _rect - Trigger rect supplied by ECharts.
+ * @param size - ECharts tooltip size metadata.
+ * @returns Tooltip coordinates within the current chart viewport.
+ */
+function readableTooltipPosition(
+  point: unknown,
+  _params: unknown,
+  dom: unknown,
+  _rect: unknown,
+  size: unknown,
+): [number, number] {
+  const cursor = Array.isArray(point) ? point : [0, 0];
+  const sizeRecord = isPlainRecord(size) ? size : {};
+  const viewSize = Array.isArray(sizeRecord.viewSize) ? sizeRecord.viewSize : [];
+  const contentSize = Array.isArray(sizeRecord.contentSize) ? sizeRecord.contentSize : [];
+  const domElement = typeof HTMLElement !== 'undefined' && dom instanceof HTMLElement ? dom : null;
+  const width = Math.ceil(domElement?.offsetWidth || Number(contentSize[0]) || 0);
+  const height = Math.ceil(domElement?.offsetHeight || Number(contentSize[1]) || 0);
+  const viewWidth = Number(viewSize[0]) || (typeof window === 'undefined' ? 0 : window.innerWidth);
+  const viewHeight = Number(viewSize[1]) || (typeof window === 'undefined' ? 0 : window.innerHeight);
+  const padding = 8;
+  const gap = 12;
+  const cursorX = Number(cursor[0]) || 0;
+  const cursorY = Number(cursor[1]) || 0;
+  let x = cursorX + gap;
+  let y = cursorY + gap;
+  if (viewWidth > 0 && x + width + padding > viewWidth) x = cursorX - width - gap;
+  if (viewHeight > 0 && y + height + padding > viewHeight) y = cursorY - height - gap;
+  return [
+    Math.max(padding, x),
+    Math.max(padding, y),
+  ];
+}
+
+/**
+ * Adds bounded tooltip defaults while preserving existing tooltip settings.
+ * @param tooltip - Existing ECharts tooltip option.
+ * @returns Tooltip option that stays within the chart viewport.
+ */
+function withTooltipPortal(tooltip: unknown): Record<string, unknown> {
+  const tooltipRecord = tooltip as Record<string, unknown>;
+  const {
+    appendToBody: _appendToBody,
+    appendTo: _appendTo,
+    ...safeTooltip
+  } = tooltipRecord;
+  return {
+    ...safeTooltip,
+    appendToBody: false,
+    confine: true,
+    textStyle: withReadableTooltipTextStyle(tooltipRecord.textStyle),
+    extraCssText: mergeTooltipExtraCssText(tooltipRecord.extraCssText),
+    position: tooltipRecord.position ?? readableTooltipPosition,
+  };
+}
+
+/**
+ * Ensures chart HTML tooltips are appended to body instead of the chart container.
+ * @param option - ECharts option generated from a card renderer.
+ * @returns Option with tooltip portal defaults applied.
+ */
+export function withEchartsTooltipPortal<T extends EChartsOption>(option: T): T {
+  const optionRecord = option as Record<string, unknown>;
+  if (!Object.prototype.hasOwnProperty.call(optionRecord, 'tooltip')) return option;
+  const tooltip = optionRecord.tooltip;
+
+  if (Array.isArray(tooltip)) {
+    return {
+      ...option,
+      tooltip: tooltip.map((item) => (isPlainRecord(item) ? withTooltipPortal(item) : item)),
+    } as T;
+  }
+
+  if (!isPlainRecord(tooltip)) return option;
+
+  return {
+    ...option,
+    tooltip: withTooltipPortal(tooltip),
+  } as T;
+}