@casualoffice/sheets 0.17.0 → 0.19.0

package/src/charts/types.ts

@@ -0,0 +1,239 @@
+/**
+ * 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.
+ */
+
+/**
+ * Chart model the in-memory store (`charts-context`) carries per
+ * inserted chart. P0 is minimal — just enough to render a column
+ * chart bound to a cell range. P1 adds the resource persistence
+ * round-trip; P2 wires Univer's drawing model for move/resize; P3
+ * expands `type` into the catalog of supported chart types.
+ *
+ * Position lives in cell coordinates rather than pixels — that's
+ * how Excel anchors charts (top-left anchored to cell A, bottom-
+ * right to cell B). We can compute pixels on the fly via
+ * `range.getCellRect()` so the chart moves with the rows/columns
+ * when they shift.
+ */
+/**
+ * Chart subtypes, grouped by family. Matches the most-used subset of
+ * Excel's "Insert Chart" catalog:
+ *
+ *   - Column (vertical bars): clustered / stacked / 100 %-stacked.
+ *   - Bar (horizontal bars): clustered / stacked / 100 %-stacked.
+ *   - Line: line / stacked line.
+ *   - Area: area / stacked area.
+ *   - Pie: pie / doughnut.
+ *   - Scatter.
+ *
+ * The legacy `'bar'` literal that P0/P1 used for "vertical column
+ * chart" is migrated to `'column'` on read (see `resources.ts`).
+ */
+export type ChartType =
+  | 'column'
+  | 'column-stacked'
+  | 'column-stacked-100'
+  | 'bar'
+  | 'bar-stacked'
+  | 'bar-stacked-100'
+  | 'line'
+  | 'line-stacked'
+  | 'area'
+  | 'area-stacked'
+  | 'pie'
+  | 'doughnut'
+  | 'scatter';
+
+/** Top-level family — what shows in the left column of the Insert dialog. */
+export type ChartFamily = 'column' | 'bar' | 'line' | 'area' | 'pie' | 'scatter';
+
+export const CHART_FAMILY_OF: Record<ChartType, ChartFamily> = {
+  column: 'column',
+  'column-stacked': 'column',
+  'column-stacked-100': 'column',
+  bar: 'bar',
+  'bar-stacked': 'bar',
+  'bar-stacked-100': 'bar',
+  line: 'line',
+  'line-stacked': 'line',
+  area: 'area',
+  'area-stacked': 'area',
+  pie: 'pie',
+  doughnut: 'pie',
+  scatter: 'scatter',
+};
+
+/** Human-readable label shown in the panel + dialog. */
+export const CHART_TYPE_LABEL: Record<ChartType, string> = {
+  column: 'Clustered Column',
+  'column-stacked': 'Stacked Column',
+  'column-stacked-100': '100% Stacked Column',
+  bar: 'Clustered Bar',
+  'bar-stacked': 'Stacked Bar',
+  'bar-stacked-100': '100% Stacked Bar',
+  line: 'Line',
+  'line-stacked': 'Stacked Line',
+  area: 'Area',
+  'area-stacked': 'Stacked Area',
+  pie: 'Pie',
+  doughnut: 'Doughnut',
+  scatter: 'Scatter',
+};
+
+export type ChartModel = {
+  id: string;
+  /** Sheet the chart lives on. Matches `FWorksheet.getSheetId()`. */
+  sheetId: string;
+  /** Source data range — first row treated as header (column names),
+   *  first column as category axis labels. */
+  source: { startRow: number; endRow: number; startColumn: number; endColumn: number };
+  /** Chart position, in 0-indexed cell coordinates. */
+  pos: { startRow: number; endRow: number; startColumn: number; endColumn: number };
+  type: ChartType;
+  /** Auto-generated "Chart N" name; the user can rename via the panel
+   *  or the right-click menu. Doubles as the chart title shown above
+   *  the plot when `format.showTitle` is true. */
+  title?: string;
+  /** Excel's "Format Chart Area" options — none required; absent
+   *  values fall back to the defaults documented in `defaultFormat`. */
+  format?: ChartFormat;
+};
+
+/** Equivalent of Excel's "Format Chart Area" pane in scope. */
+export type ChartFormat = {
+  /** Render the chart title above the plot. Defaults to `true` when
+   *  the chart has a `title`, `false` otherwise. */
+  showTitle?: boolean;
+  /** Legend placement. `'none'` hides the legend entirely. */
+  legend?: 'top' | 'right' | 'bottom' | 'left' | 'none';
+  /** Optional axis titles. Ignored for pie / doughnut. */
+  xAxisTitle?: string;
+  yAxisTitle?: string;
+  /** Show major gridlines on the value axis. */
+  gridlines?: boolean;
+  /** Show numeric labels on bars / lines / slices. */
+  dataLabels?: boolean;
+  /** Color palette applied to the series. Mirrors Excel's "Change
+   *  Colors" picker — pick the first N from the chosen palette. */
+  palette?: ChartPalette;
+  /** Overlay a linear-regression trendline on every numeric series.
+   *  Only meaningful for line / scatter / area / bar / column charts;
+   *  ignored for pie. ECharts renders this via `markLine` from the
+   *  computed regression endpoints. */
+  trendline?: boolean;
+  /** Per-series colour overrides, keyed by series name (the header
+   *  row in the source range). Missing entries fall back to the
+   *  active `palette`. Stored on the resource so the override
+   *  survives reload + xlsx round-trip via the chart's `format`
+   *  payload. */
+  seriesColors?: Record<string, string>;
+  /** Combo charts: per-series render-kind override, keyed by series
+   *  name. Lets a column/bar/line/area chart mix bar + line series
+   *  (Excel's "Combo" chart type). Missing entries fall back to the
+   *  chart's base `type`. Only `'bar'` and `'line'` are offered; pie /
+   *  doughnut / scatter / 100%-stacked ignore this. */
+  seriesTypes?: Record<string, 'bar' | 'line'>;
+  /** Dual axis: when a series name maps to `true`, that series is
+   *  plotted against a secondary value axis (Excel's "Secondary Axis"
+   *  checkbox in the Format Data Series pane). The chart then renders
+   *  with two value axes — primary on the left, secondary on the
+   *  right. Only meaningful for the bar / column / line / area
+   *  families; ignored by pie / doughnut / scatter / 100%-stacked
+   *  (a shared 0–100% scale defeats the purpose). */
+  secondaryAxis?: Record<string, boolean>;
+};
+
+export type ChartPalette = 'office' | 'mono' | 'vivid' | 'pastel';
+
+/** Resolved (filled-in) format used by build-option. Apply over the
+ *  user's partial via `mergeFormat`. */
+export type ResolvedChartFormat = Required<Omit<ChartFormat, 'xAxisTitle' | 'yAxisTitle'>> & {
+  xAxisTitle?: string;
+  yAxisTitle?: string;
+};
+
+export function defaultFormat(model: Pick<ChartModel, 'title'>): ResolvedChartFormat {
+  return {
+    showTitle: Boolean(model.title),
+    legend: 'bottom',
+    gridlines: true,
+    dataLabels: false,
+    palette: 'office',
+    trendline: false,
+    seriesColors: {},
+    seriesTypes: {},
+    secondaryAxis: {},
+  };
+}
+
+export function mergeFormat(model: Pick<ChartModel, 'title' | 'format'>): ResolvedChartFormat {
+  const base = defaultFormat(model);
+  const f = model.format ?? {};
+  return {
+    showTitle: f.showTitle ?? base.showTitle,
+    legend: f.legend ?? base.legend,
+    gridlines: f.gridlines ?? base.gridlines,
+    dataLabels: f.dataLabels ?? base.dataLabels,
+    palette: f.palette ?? base.palette,
+    trendline: f.trendline ?? base.trendline,
+    seriesColors: f.seriesColors ?? base.seriesColors,
+    seriesTypes: f.seriesTypes ?? base.seriesTypes,
+    secondaryAxis: f.secondaryAxis ?? base.secondaryAxis,
+    xAxisTitle: f.xAxisTitle,
+    yAxisTitle: f.yAxisTitle,
+  };
+}
+
+/** Palette colours, applied in order to the series. Picked to match
+ *  Excel's default colour sets so the look stays familiar. */
+export const PALETTES: Record<ChartPalette, string[]> = {
+  office: ['#5B9BD5', '#ED7D31', '#A5A5A5', '#FFC000', '#4472C4', '#70AD47', '#264478', '#9E480E'],
+  mono: ['#1F77B4', '#3F8FBC', '#5FA7C5', '#7FBFCD', '#9FD7D6', '#BFEFDE', '#5A8DAA', '#3D6E89'],
+  vivid: ['#E63946', '#F1A208', '#06A77D', '#005F73', '#9B5DE5', '#F15BB5', '#00BBF9', '#00F5D4'],
+  pastel: ['#A3CEF1', '#FFD6A5', '#CAFFBF', '#FFADAD', '#BDB2FF', '#FDFFB6', '#FFC6FF', '#9BF6FF'],
+};
+
+export const PALETTE_LABELS: Record<ChartPalette, string> = {
+  office: 'Office',
+  mono: 'Monochromatic',
+  vivid: 'Vivid',
+  pastel: 'Pastel',
+};
+
+export const LEGEND_POSITIONS: { id: NonNullable<ChartFormat['legend']>; label: string }[] = [
+  { id: 'bottom', label: 'Bottom' },
+  { id: 'top', label: 'Top' },
+  { id: 'right', label: 'Right' },
+  { id: 'left', label: 'Left' },
+  { id: 'none', label: 'None' },
+];
+
+export function newChartId(): string {
+  return `ch-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+}
+
+/**
+ * Plugin-resource name we use when stashing chart models in
+ * `IWorkbookData.resources`. Mirrors `OUTLINE_RESOURCE_NAME` — survives
+ * xlsx via the hidden `__casual_sheets_resources__` sheet and survives
+ * collab via Univer's snapshot-load path.
+ */
+export const CHARTS_RESOURCE_NAME = '__casual_sheets_charts__';
+
+/** Versioned envelope so a future schema change can be detected. */
+export type ChartsResourceV1 = {
+  v: 1;
+  charts: ChartModel[];
+};

package/src/charts/univer-dom.ts

@@ -0,0 +1,102 @@
+/**
+ * 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.
+ */
+
+/**
+ * Helpers for reaching into Univer's mounted DOM. Internal Univer DOM
+ * identifiers are not part of the public API and have shifted between
+ * minor versions — centralise the selectors here so a Univer upgrade
+ * needs one fix instead of touching every overlay that anchors to the
+ * canvas (PresenceLayer, ChartLayer, future drawing/comment overlays).
+ *
+ * Every helper falls back to a structural query and warns once if it
+ * had to use the fallback, so a silent overlay-disappears regression
+ * surfaces in the console instead of looking like a sync bug.
+ */
+
+import type { FUniver } from '@univerjs/core/facade';
+
+const PRIMARY_CANVAS_SELECTOR = 'canvas[id^="univer-sheet-main-canvas_"]';
+/** Univer mounts a hidden formula-editor canvas BEFORE the main grid
+ *  canvas. That one has no id, sits with width/height = 0, and is
+ *  useless to anchor overlays to. The fallback path must explicitly
+ *  skip it — picking it caused PresenceLayer / ChartLayer to render
+ *  cursors at the wrong position whenever the primary selector raced
+ *  the main-canvas mount. */
+let fallbackWarned = false;
+
+export function getUniverHost(): HTMLElement | null {
+  return document.querySelector('[data-testid="univer-host"]') as HTMLElement | null;
+}
+
+export function getUniverMainCanvas(host: HTMLElement): HTMLCanvasElement | null {
+  const primary = host.querySelector(PRIMARY_CANVAS_SELECTOR) as HTMLCanvasElement | null;
+  if (primary) return primary;
+  // Walk all canvases and pick the first one that LOOKS like the main
+  // grid: has a non-empty id AND a non-zero rendered size. Editor
+  // canvases have empty ids and 0x0 boxes until focused. We refuse to
+  // return any of those — better to render no overlay than to anchor
+  // it to a hidden offscreen canvas.
+  const all = Array.from(host.querySelectorAll('canvas')) as HTMLCanvasElement[];
+  for (const c of all) {
+    if (!c.id) continue;
+    const r = c.getBoundingClientRect();
+    if (r.width < 50 || r.height < 50) continue;
+    if (!fallbackWarned) {
+      fallbackWarned = true;
+      console.warn(
+        '[univer-dom] primary canvas selector "%s" matched nothing — using fallback id "%s". Update PRIMARY_CANVAS_SELECTOR after a Univer upgrade.',
+        PRIMARY_CANVAS_SELECTOR,
+        c.id,
+      );
+    }
+    return c;
+  }
+  return null;
+}
+
+/**
+ * Pixel offset between the canvas top-left and the cell-content area's
+ * top-left — i.e. the row-header gutter width and the column-header
+ * gutter height. Every overlay that anchors to `getCellRect()`
+ * coordinates must add these to land on the actual cells instead of
+ * ~40 px up-and-left of them.
+ *
+ * We use Univer 0.22.x's documented defaults (row header = 46 px,
+ * column header = 20 px) rather than reaching into the render
+ * skeleton at runtime — the dynamic lookup via
+ * `RenderUnit.with(SheetSkeletonManagerService)` instantiates the
+ * service through redi, which transitively requires
+ * `SheetScrollManagerService` that may not yet be registered on the
+ * unit's injector when our rAF tick fires (race with Univer's
+ * render-unit init). The crash surfaces as
+ * "QuantityCheckError: Expect 1 dependency item(s) for id
+ * 'SheetScrollManagerService' but get 0".
+ *
+ * Hardcoding the defaults trades ~40 px accuracy for any user who
+ * customises header sizes (rare, undocumented in our app) for
+ * zero-risk init. If you change Univer's default theme, update
+ * these constants and the cursor/chart layers stay aligned.
+ */
+export type HeaderGutter = { rowHeaderWidth: number; columnHeaderHeight: number };
+
+const DEFAULT_HEADER_GUTTER: HeaderGutter = {
+  rowHeaderWidth: 46,
+  columnHeaderHeight: 20,
+};
+
+export function getHeaderGutter(_api: FUniver | null): HeaderGutter {
+  return DEFAULT_HEADER_GUTTER;
+}