@casualoffice/sheets 0.18.0 → 0.20.0

package/src/charts/echarts-init.ts

@@ -0,0 +1,58 @@
+/**
+ * Copyright 2026 Casual Office
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { use } from 'echarts/core';
+import { CanvasRenderer } from 'echarts/renderers';
+import { BarChart, LineChart, PieChart, ScatterChart } from 'echarts/charts';
+import {
+  GridComponent,
+  LegendComponent,
+  TitleComponent,
+  TooltipComponent,
+  DatasetComponent,
+} from 'echarts/components';
+
+/**
+ * Tree-shaken ECharts wiring. We pay only for the chart types + canvas
+ * renderer we actually use. Pipeline Stage 4 already ships each lazy
+ * group as its own chunk; this module is the chart-group entry point —
+ * importing anything from `'echarts'` directly elsewhere would pull
+ * the full library back in and undo the bundle savings.
+ *
+ * P0 ships Bar (the demo type). P3 layers Line / Pie / Scatter /
+ * Area / Combo / Stacked variants on top — those use the same
+ * Chart/Component registrations registered here, so future types
+ * just import their chart constructor and add to `use([…])`.
+ */
+// `use` here is ECharts' renderer/component registry, not a React hook —
+// silence rules-of-hooks for the module-level call.
+// eslint-disable-next-line react-hooks/rules-of-hooks
+use([
+  CanvasRenderer,
+  BarChart,
+  LineChart,
+  PieChart,
+  ScatterChart,
+  GridComponent,
+  LegendComponent,
+  TitleComponent,
+  TooltipComponent,
+  DatasetComponent,
+]);
+
+export { init } from 'echarts/core';
+export type { EChartsType } from 'echarts/core';
+export type { EChartsOption } from 'echarts';

package/src/charts/hit-test.ts

@@ -0,0 +1,130 @@
+/**
+ * Copyright 2026 Casual Office
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Pixel ↔ cell conversion for chart drag / resize. The Univer facade
+ * doesn't ship a `pixelToCell` for our coordinate space, so we walk
+ * row heights / column widths via `getCellRect` until the cumulative
+ * extent contains the target coordinate.
+ *
+ * Inputs are in canvas-local PRE-scroll coordinates — the same frame
+ * `getCellRect` itself returns. Callers must add the viewport scroll
+ * before invoking these.
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Sheet = any;
+
+const MAX_SCAN = 2048;
+
+/** Find the row whose [top, bottom) range contains `y`. Clamped to MAX_SCAN. */
+export function rowAtY(sheet: Sheet, y: number, hintRow = 0): number {
+  if (y < 0) return 0;
+  // Walk forward from the hint. Charts only move a few cells per drag
+  // frame, so the hint puts us within a handful of iterations.
+  let r = Math.max(0, hintRow);
+  for (let i = 0; i < MAX_SCAN; i++) {
+    let rect: { top: number; bottom: number } | null = null;
+    try {
+      rect = sheet.getRange(r, 0).getCellRect();
+    } catch {
+      return Math.max(0, r - 1);
+    }
+    if (!rect) return Math.max(0, r - 1);
+    if (rect.top > y) {
+      // Overshot — walk back row by row.
+      while (r > 0) {
+        r--;
+        try {
+          const back = sheet.getRange(r, 0).getCellRect();
+          if (back && back.top <= y && back.bottom > y) return r;
+          if (back && back.top <= y) return r;
+        } catch {
+          return r;
+        }
+      }
+      return 0;
+    }
+    if (rect.bottom > y) return r;
+    r++;
+  }
+  return r;
+}
+
+/** Find the column whose [left, right) range contains `x`. Clamped to MAX_SCAN. */
+export function colAtX(sheet: Sheet, x: number, hintCol = 0): number {
+  if (x < 0) return 0;
+  let c = Math.max(0, hintCol);
+  for (let i = 0; i < MAX_SCAN; i++) {
+    let rect: { left: number; right: number } | null = null;
+    try {
+      rect = sheet.getRange(0, c).getCellRect();
+    } catch {
+      return Math.max(0, c - 1);
+    }
+    if (!rect) return Math.max(0, c - 1);
+    if (rect.left > x) {
+      while (c > 0) {
+        c--;
+        try {
+          const back = sheet.getRange(0, c).getCellRect();
+          if (back && back.left <= x && back.right > x) return c;
+          if (back && back.left <= x) return c;
+        } catch {
+          return c;
+        }
+      }
+      return 0;
+    }
+    if (rect.right > x) return c;
+    c++;
+  }
+  return c;
+}
+
+/**
+ * Convert a chart's screen-local pixel rect to cell-coordinate position.
+ * `screenRect` is the chart's host-local box (left/top/width/height).
+ * `host`-local pixels are translated to canvas-local pre-scroll coords
+ * using `canvasOffset` (canvas vs. host offset) and `scroll` (the
+ * worksheet's current scroll offset). We then snap the resulting
+ * top-left and bottom-right cells.
+ */
+export function rectToCellPos(
+  sheet: Sheet,
+  screenRect: { left: number; top: number; width: number; height: number },
+  canvasOffset: { x: number; y: number },
+  scroll: { x: number; y: number },
+  hint?: { startRow: number; startColumn: number; endRow: number; endColumn: number },
+): { startRow: number; endRow: number; startColumn: number; endColumn: number } | null {
+  const preLeft = screenRect.left - canvasOffset.x + scroll.x;
+  const preTop = screenRect.top - canvasOffset.y + scroll.y;
+  const preRight = preLeft + screenRect.width;
+  const preBottom = preTop + screenRect.height;
+
+  const startRow = rowAtY(sheet, preTop, hint?.startRow);
+  const startColumn = colAtX(sheet, preLeft, hint?.startColumn);
+  // For the bottom-right, snap to the cell BEFORE the bottom-right
+  // pixel (so the chart includes that cell, matching Excel's "anchor
+  // to bottom-right cell" semantics). Subtract 1 from preRight/Bottom
+  // to land in the inclusive last cell.
+  const endRow = Math.max(startRow, rowAtY(sheet, preBottom - 1, hint?.endRow ?? startRow));
+  const endColumn = Math.max(
+    startColumn,
+    colAtX(sheet, preRight - 1, hint?.endColumn ?? startColumn),
+  );
+  return { startRow, endRow, startColumn, endColumn };
+}

package/src/charts/insert-chart.ts

@@ -0,0 +1,106 @@
+/**
+ * Copyright 2026 Casual Office
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { FUniver } from '@univerjs/core/facade';
+import type { ChartType, ChartModel } from './types';
+import { newChartId } from './types';
+
+type Range = { startRow: number; endRow: number; startColumn: number; endColumn: number };
+
+/**
+ * Build a ChartModel for `source` on the active sheet. The chart anchors
+ * to a 10-row × 8-col block placed two rows below the source so it doesn't
+ * cover its own data. Mirrors Excel's Insert > Chart defaults — source =
+ * the dialog's selection, output = roughly the right size, dropped below.
+ *
+ * Returns null when there's no active workbook/sheet, or the range has
+ * fewer than 2 rows × 2 cols (no header + data row, or no label + value
+ * column).
+ */
+export function buildChartModelForRange(
+  api: FUniver,
+  source: Range,
+  type: ChartType,
+): ChartModel | null {
+  const wb = api.getActiveWorkbook();
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const ws = wb?.getActiveSheet() as any;
+  if (!wb || !ws) return null;
+
+  const rows = source.endRow - source.startRow + 1;
+  const cols = source.endColumn - source.startColumn + 1;
+  if (rows < 2 || cols < 2) return null;
+
+  const chartTop = source.endRow + 2;
+  const chartLeft = source.startColumn;
+  return {
+    id: newChartId(),
+    sheetId: ws.getSheetId(),
+    source,
+    pos: {
+      startRow: chartTop,
+      endRow: chartTop + 9,
+      startColumn: chartLeft,
+      endColumn: chartLeft + 7,
+    },
+    type,
+  };
+}
+
+/**
+ * Read the active selection on the active sheet. Returns null if no
+ * workbook / sheet / selection is available — the menu item is enabled
+ * unconditionally, so the caller still has to handle the empty case.
+ */
+export function getActiveSelectionRange(api: FUniver): Range | null {
+  const wb = api.getActiveWorkbook();
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const ws = wb?.getActiveSheet() as any;
+  const range = ws?.getActiveRange();
+  if (!wb || !ws || !range) return null;
+  const r = range.getRange();
+  return {
+    startRow: r.startRow,
+    endRow: r.endRow,
+    startColumn: r.startColumn,
+    endColumn: r.endColumn,
+  };
+}
+
+/**
+ * Format a cell range as an A1-style reference (e.g. `A1:C4`). Used by
+ * the insert dialog to pre-fill its source-range input from the current
+ * selection so the common case is two clicks.
+ */
+export function rangeToA1(range: Range): string {
+  const tl = `${colIndexToA1(range.startColumn)}${range.startRow + 1}`;
+  if (range.startRow === range.endRow && range.startColumn === range.endColumn) {
+    return tl;
+  }
+  const br = `${colIndexToA1(range.endColumn)}${range.endRow + 1}`;
+  return `${tl}:${br}`;
+}
+
+function colIndexToA1(c: number): string {
+  let n = c + 1;
+  let s = '';
+  while (n > 0) {
+    const rem = (n - 1) % 26;
+    s = String.fromCharCode(65 + rem) + s;
+    n = Math.floor((n - 1) / 26);
+  }
+  return s;
+}

package/src/charts/naming.ts

@@ -0,0 +1,38 @@
+/**
+ * Copyright 2026 Casual Office
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { ChartModel } from './types';
+
+/**
+ * Excel auto-names charts as "Chart 1", "Chart 2", ..., picking the
+ * lowest unused suffix even if intermediate charts have been deleted
+ * (so deleting Chart 2 then inserting again gives you Chart 2, not
+ * Chart 4). Match that.
+ *
+ * Operates on `ChartModel.title` — see the Chart Selection Pane for
+ * inline rename.
+ */
+export function nextChartName(existing: ChartModel[]): string {
+  const used = new Set<number>();
+  for (const c of existing) {
+    if (!c.title) continue;
+    const m = /^Chart (\d+)$/.exec(c.title);
+    if (m) used.add(Number(m[1]));
+  }
+  let n = 1;
+  while (used.has(n)) n++;
+  return `Chart ${n}`;
+}

package/src/charts/render-to-png.ts

@@ -0,0 +1,117 @@
+/**
+ * Copyright 2026 Casual Office
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { FUniver } from '@univerjs/core/facade';
+import { init } from './echarts-init';
+import { buildEChartsOption } from './build-option';
+import type { ChartModel } from './types';
+
+/**
+ * Render a chart model to a PNG ArrayBuffer using a detached ECharts
+ * instance. Used by the xlsx exporter (Charts P5b) so the chart shows
+ * up as a real image when the file is opened in Excel — the live
+ * interactive ECharts canvas can't ship; an embedded image can.
+ *
+ * Constraints:
+ *   - Must run on the main thread (ECharts needs a DOM container).
+ *   - The container is created inside `document.body` with
+ *     `visibility: hidden` + `pointer-events: none` so it never
+ *     interferes with the actual UI even momentarily.
+ *   - We choose pixel dimensions based on the chart's cell-anchored
+ *     position so the embedded PNG roughly matches what the user
+ *     sees in the app.
+ *
+ * Returns null when there's no source data (empty range etc.) so the
+ * exporter can skip the chart cleanly rather than embed a 1×1 blank.
+ */
+export async function renderChartToPng(
+  api: FUniver,
+  model: ChartModel,
+  pxWidth: number,
+  pxHeight: number,
+): Promise<ArrayBuffer | null> {
+  const opt = buildEChartsOption(api, model);
+  if (!opt) return null;
+
+  const host = document.createElement('div');
+  host.style.position = 'absolute';
+  host.style.left = '-99999px';
+  host.style.top = '0';
+  host.style.width = `${pxWidth}px`;
+  host.style.height = `${pxHeight}px`;
+  host.style.visibility = 'hidden';
+  host.style.pointerEvents = 'none';
+  document.body.appendChild(host);
+
+  try {
+    const inst = init(host, undefined, { renderer: 'canvas' });
+    // Apply the same option ChartOverlay uses so the snapshot matches
+    // what the user sees in-app. notMerge: true to fully override any
+    // ECharts defaults left over from the previous setOption.
+    inst.setOption(opt, true);
+    // ECharts renders on the next animation frame; force a synchronous
+    // resize so the canvas is filled before we read it.
+    inst.resize();
+    const dataUrl = inst.getDataURL({
+      type: 'png',
+      pixelRatio: 2,
+      backgroundColor: '#ffffff',
+    });
+    inst.dispose();
+    return dataUrlToArrayBuffer(dataUrl);
+  } finally {
+    host.remove();
+  }
+}
+
+function dataUrlToArrayBuffer(dataUrl: string): ArrayBuffer {
+  const comma = dataUrl.indexOf(',');
+  if (comma < 0) return new ArrayBuffer(0);
+  const b64 = dataUrl.slice(comma + 1);
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes.buffer;
+}
+
+/**
+ * Resolve the chart's pixel size from its cell-anchored position by
+ * walking the sheet's column widths / row heights. Falls back to a
+ * sensible default (480×320) when the snapshot doesn't have width/height
+ * data for the spanned cells.
+ */
+export function pixelsForChart(api: FUniver, model: ChartModel): { width: number; height: number } {
+  const wb = api.getActiveWorkbook();
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const sheets = wb?.getSheets() as any[] | undefined;
+  const ws = sheets?.find((s) => s.getSheetId?.() === model.sheetId);
+  if (!ws) return { width: 480, height: 320 };
+
+  let width = 0;
+  for (let c = model.pos.startColumn; c <= model.pos.endColumn; c++) {
+    const w = Number(ws.getColumnWidth?.(c) ?? 0);
+    width += w > 0 ? w : 88;
+  }
+  let height = 0;
+  for (let r = model.pos.startRow; r <= model.pos.endRow; r++) {
+    const h = Number(ws.getRowHeight?.(r) ?? 0);
+    height += h > 0 ? h : 24;
+  }
+  return {
+    width: Math.max(120, Math.round(width)),
+    height: Math.max(80, Math.round(height)),
+  };
+}

package/src/charts/resources.ts

@@ -0,0 +1,108 @@
+/**
+ * Copyright 2026 Casual Office
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { IWorkbookData } from '@univerjs/core';
+import {
+  CHARTS_RESOURCE_NAME,
+  type ChartModel,
+  type ChartsResourceV1,
+  type ChartType,
+} from './types';
+
+/**
+ * Round-trip helpers for the charts plugin resource. The resource lives on
+ * `IWorkbookData.resources` and is carried through xlsx via the hidden
+ * `__casual_sheets_resources__` sheet we already use for outline groups,
+ * and through collab via Univer's snapshot-load path.
+ */
+
+const VALID_TYPES: ChartType[] = [
+  'column',
+  'column-stacked',
+  'column-stacked-100',
+  'bar',
+  'bar-stacked',
+  'bar-stacked-100',
+  'line',
+  'line-stacked',
+  'area',
+  'area-stacked',
+  'pie',
+  'doughnut',
+  'scatter',
+];
+
+/**
+ * The pre-P3 store used `'bar'` for what we now (correctly) call
+ * `'column'` — vertical bars. Migrate on read so existing workbooks
+ * keep rendering after the rename.
+ */
+function migrateType(raw: unknown): ChartType | null {
+  if (typeof raw !== 'string') return null;
+  // Existing 'bar' string is ambiguous between old "vertical column"
+  // and new "horizontal bar". P0/P1/P2 saved 'bar' meaning column;
+  // we have no horizontal-bar charts in the wild yet, so 'bar' from
+  // before P3 means column.
+  if (raw === 'bar') return 'column';
+  return VALID_TYPES.includes(raw as ChartType) ? (raw as ChartType) : null;
+}
+
+function isValidChart(c: unknown): c is ChartModel {
+  if (!c || typeof c !== 'object') return false;
+  const r = c as Record<string, unknown>;
+  if (typeof r.id !== 'string' || typeof r.sheetId !== 'string') return false;
+  const migrated = migrateType(r.type);
+  if (!migrated) return false;
+  r.type = migrated; // mutate so the rest of the app sees the new value
+  const src = r.source as Record<string, unknown> | undefined;
+  const pos = r.pos as Record<string, unknown> | undefined;
+  if (!src || !pos) return false;
+  for (const k of ['startRow', 'endRow', 'startColumn', 'endColumn'] as const) {
+    if (typeof src[k] !== 'number' || typeof pos[k] !== 'number') return false;
+  }
+  // `format` is optional and freely shaped — defer validation to
+  // `mergeFormat`, which fills missing fields with defaults. Anything
+  // we don't recognise is ignored at render time.
+  if (r.format != null && typeof r.format !== 'object') return false;
+  return true;
+}
+
+/** Read chart models out of a snapshot. Tolerant of older / missing payloads. */
+export function readChartsFromSnapshot(data: IWorkbookData | undefined): ChartModel[] {
+  if (!data?.resources?.length) return [];
+  const entry = data.resources.find((r) => r.name === CHARTS_RESOURCE_NAME);
+  if (!entry?.data) return [];
+  try {
+    const parsed = JSON.parse(entry.data) as Partial<ChartsResourceV1>;
+    if (parsed?.v !== 1 || !Array.isArray(parsed.charts)) return [];
+    return parsed.charts.filter(isValidChart);
+  } catch {
+    /* corrupt payload — drop silently, the workbook still opens fine */
+    return [];
+  }
+}
+
+/** Merge chart models INTO `data.resources` for export. Mutates in place. */
+export function writeChartsIntoSnapshot(data: IWorkbookData, charts: ChartModel[]): void {
+  const existing = data.resources ?? [];
+  const filtered = existing.filter((r) => r.name !== CHARTS_RESOURCE_NAME);
+  if (charts.length === 0) {
+    data.resources = filtered;
+    return;
+  }
+  const payload: ChartsResourceV1 = { v: 1, charts };
+  data.resources = [...filtered, { name: CHARTS_RESOURCE_NAME, data: JSON.stringify(payload) }];
+}