@casualoffice/sheets 0.18.0 → 0.20.0

package/src/chrome/TablesPanel.tsx

@@ -0,0 +1,283 @@
+/**
+ * Copyright 2026 Casual Office
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ */
+
+/**
+ * Tables side panel: lists the formatted tables on the active sheet with
+ * inline rename, theme swatches, and delete. Ported from the standalone app's
+ * TablesPanel — the app-only `useUI`/`useBusy` couplings are replaced by the
+ * panel host's `onClose`, and the Univer facade is reached through `api.univer`.
+ */
+import { useEffect, useMemo, useState, type CSSProperties } from 'react';
+
+import { ensurePluginByName } from '../univer';
+import type { PanelComponentProps } from './extensions';
+import { Icon } from './Icon';
+import { PanelHeader, PanelEmpty } from './panel-shell';
+
+// Univer's six built-in table themes, surfaced as swatches.
+const TABLE_THEMES = [
+  { id: 'table-default-0', label: 'Indigo', swatch: '#6280F9' },
+  { id: 'table-default-1', label: 'Teal', swatch: '#16BDCA' },
+  { id: 'table-default-2', label: 'Green', swatch: '#31C48D' },
+  { id: 'table-default-3', label: 'Purple', swatch: '#AC94FA' },
+  { id: 'table-default-4', label: 'Pink', swatch: '#F17EBB' },
+  { id: 'table-default-5', label: 'Red', swatch: '#F98080' },
+] as const;
+type TableThemeId = (typeof TABLE_THEMES)[number]['id'];
+
+interface TableRange {
+  startRow: number;
+  startColumn: number;
+  endRow: number;
+  endColumn: number;
+}
+interface RawTable {
+  id: string;
+  name: string;
+  subUnitId: string;
+  range: TableRange;
+}
+interface TableInfo extends RawTable {
+  styleId: string;
+}
+
+function colLetters(col: number): string {
+  let n = col + 1;
+  let out = '';
+  while (n > 0) {
+    const r = (n - 1) % 26;
+    out = String.fromCharCode(65 + r) + out;
+    n = Math.floor((n - 1) / 26);
+  }
+  return out;
+}
+function toA1(r: TableRange): string {
+  const start = `${colLetters(r.startColumn)}${r.startRow + 1}`;
+  const end = `${colLetters(r.endColumn)}${r.endRow + 1}`;
+  return start === end ? start : `${start}:${end}`;
+}
+
+const REFRESH_CMDS = new Set([
+  'sheet.command.add-table',
+  'sheet.command.delete-table',
+  'sheet.command.set-table-config',
+  'sheet.mutation.add-table',
+  'sheet.mutation.set-table-config',
+  'sheet.mutation.delete-table',
+  'sheet.operation.set-worksheet-activate',
+  'doc.command-replace-snapshot',
+]);
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+function readTables(univer: any, sheetId: string | null): TableInfo[] {
+  try {
+    const wb = univer.getActiveWorkbook?.();
+    if (!wb) return [];
+    const all: RawTable[] = wb.getTableList?.() ?? [];
+    return all
+      .filter((t) => (sheetId ? t.subUnitId === sheetId : true))
+      .map((t) => ({ ...t, styleId: 'table-default-0' }));
+  } catch {
+    // Table plugin still registering — the CommandExecuted subscription
+    // recomputes once it's ready.
+    return [];
+  }
+}
+
+const header: CSSProperties = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: 8,
+  padding: '10px 12px',
+  borderBottom: '1px solid var(--cs-chrome-border, #edeff3)',
+};
+
+export function TablesPanel({ api, onClose }: PanelComponentProps) {
+  const univer = (api as any).univer;
+  const [tables, setTables] = useState<TableInfo[]>([]);
+  const [renaming, setRenaming] = useState<{ id: string; draft: string } | null>(null);
+
+  useEffect(() => {
+    if (!univer) return;
+    let cancelled = false;
+    let disp: { dispose?: () => void } | undefined;
+    const compute = () => {
+      if (cancelled) return;
+      const sheetId = univer.getActiveWorkbook?.()?.getActiveSheet?.()?.getSheetId?.() ?? null;
+      setTables(readTables(univer, sheetId));
+    };
+    // The table plugin is lazy-loaded — `getTableList()` resolves SheetTableService
+    // and throws if the plugin isn't registered yet, so ensure it before reading.
+    void ensurePluginByName('table').then(() => {
+      if (cancelled) return;
+      compute();
+      disp = univer.addEvent(univer.Event.CommandExecuted, (e: { id?: string }) => {
+        if (e.id && REFRESH_CMDS.has(e.id)) compute();
+      });
+    });
+    return () => {
+      cancelled = true;
+      disp?.dispose?.();
+    };
+  }, [univer]);
+
+  const themesById = useMemo(() => {
+    const m = new Map<string, (typeof TABLE_THEMES)[number]>();
+    for (const t of TABLE_THEMES) m.set(t.id, t);
+    return m;
+  }, []);
+
+  const empty = tables.length === 0;
+
+  const onRenameCommit = async (id: string, currentName: string) => {
+    if (!renaming || renaming.id !== id) return;
+    const next = renaming.draft.trim();
+    setRenaming(null);
+    if (!next || next === currentName) return;
+    const sheet = univer.getActiveWorkbook?.()?.getActiveSheet?.();
+    if (!sheet) return;
+    await ensurePluginByName('table');
+    const ok = await Promise.resolve(sheet.setTableName?.(id, next));
+    if (ok === false) console.warn(`[tables] rename rejected: "${next}"`);
+  };
+
+  const onPickTheme = async (id: string, themeId: TableThemeId) => {
+    const wb = univer.getActiveWorkbook?.();
+    if (!wb) return;
+    await ensurePluginByName('table');
+    univer.executeCommand('sheet.command.set-table-config', {
+      unitId: wb.getId(),
+      tableId: id,
+      theme: themeId,
+    });
+  };
+
+  const onDelete = async (id: string) => {
+    const wb = univer.getActiveWorkbook?.();
+    if (!wb) return;
+    await ensurePluginByName('table');
+    wb.removeTable?.(id);
+  };
+
+  return (
+    <div
+      data-testid="cs-tables-panel"
+      style={{ height: '100%', display: 'flex', flexDirection: 'column' }}
+    >
+      <PanelHeader icon="table" title="Tables" count={tables.length} onClose={onClose} />
+
+      <div style={{ flex: 1, overflow: 'auto', padding: 12 }}>
+        {empty ? (
+          <PanelEmpty icon="table_rows" title="No tables on this sheet" testId="cs-tables-panel-empty">
+            Select your data, then use <strong>Insert → Table</strong> from the menu.
+          </PanelEmpty>
+        ) : (
+          <ul
+            style={{
+              listStyle: 'none',
+              margin: 0,
+              padding: 0,
+              display: 'flex',
+              flexDirection: 'column',
+              gap: 8,
+            }}
+          >
+            {tables.map((t) => {
+              const isRenaming = renaming?.id === t.id;
+              const theme = themesById.get(t.styleId);
+              return (
+                <li
+                  key={t.id}
+                  data-testid={`cs-tables-panel-row-${t.id}`}
+                  style={{
+                    border: '1px solid var(--cs-chrome-border, #edeff3)',
+                    borderRadius: 8,
+                    padding: 10,
+                    display: 'flex',
+                    flexDirection: 'column',
+                    gap: 6,
+                  }}
+                >
+                  <div style={{ display: 'flex', alignItems: 'center', gap: 6 }}>
+                    {isRenaming ? (
+                      <input
+                        autoFocus
+                        value={renaming.draft}
+                        onChange={(e) => setRenaming({ id: t.id, draft: e.target.value })}
+                        onBlur={() => onRenameCommit(t.id, t.name)}
+                        onKeyDown={(e) => {
+                          if (e.key === 'Enter') onRenameCommit(t.id, t.name);
+                          if (e.key === 'Escape') setRenaming(null);
+                        }}
+                        style={{ flex: 1, font: 'inherit', padding: '2px 4px' }}
+                      />
+                    ) : (
+                      <button
+                        type="button"
+                        onClick={() => setRenaming({ id: t.id, draft: t.name })}
+                        title="Click to rename"
+                        style={{
+                          flex: 1,
+                          textAlign: 'left',
+                          border: 'none',
+                          background: 'transparent',
+                          cursor: 'pointer',
+                          font: 'inherit',
+                          fontWeight: 600,
+                          color: 'inherit',
+                        }}
+                      >
+                        {t.name}
+                      </button>
+                    )}
+                    <span style={{ opacity: 0.6, fontSize: 12 }}>{toA1(t.range)}</span>
+                    <button
+                      type="button"
+                      aria-label={`Delete table ${t.name}`}
+                      title="Delete table"
+                      onClick={() => onDelete(t.id)}
+                      style={{
+                        border: 'none',
+                        background: 'transparent',
+                        cursor: 'pointer',
+                        color: 'inherit',
+                      }}
+                    >
+                      <Icon name="delete" size={16} />
+                    </button>
+                  </div>
+                  <div role="group" aria-label="Table theme" style={{ display: 'flex', gap: 4 }}>
+                    {TABLE_THEMES.map((opt) => (
+                      <button
+                        key={opt.id}
+                        type="button"
+                        title={opt.label}
+                        aria-label={opt.label}
+                        aria-pressed={theme?.id === opt.id}
+                        onClick={() => onPickTheme(t.id, opt.id)}
+                        style={{
+                          width: 18,
+                          height: 18,
+                          borderRadius: 4,
+                          cursor: 'pointer',
+                          background: opt.swatch,
+                          border:
+                            theme?.id === opt.id
+                              ? '2px solid var(--cs-chrome-active-fg, #0e7490)'
+                              : '1px solid rgba(0,0,0,0.15)',
+                        }}
+                      />
+                    ))}
+                  </div>
+                </li>
+              );
+            })}
+          </ul>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/chrome/Toolbar.tsx

@@ -371,7 +371,13 @@ const BAR_STYLE: CSSProperties = {
   background: 'var(--cs-chrome-bg, #eef1f5)',
   flex: '0 0 auto',
   userSelect: 'none',
-  flexWrap: 'wrap',
+  // Single row that scrolls horizontally when the controls don't fit — never
+  // wrap into a broken second row with orphaned icons (matches Google Sheets /
+  // the standalone app's overflow-scroll toolbar). Scrollbar hidden; the row
+  // stays one line and the groups keep their order.
+  flexWrap: 'nowrap',
+  overflowX: 'auto',
+  scrollbarWidth: 'none',
 };
 
 const BTN_STYLE: CSSProperties = {

package/src/chrome/panel-context.tsx

@@ -0,0 +1,55 @@
+/**
+ * Copyright 2026 Casual Office
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ */
+
+/**
+ * Panel store for the SDK chrome's side-panel rail (Tables/Charts/Comments/…).
+ *
+ * A single `openPanelId` is the whole state — that IS the mutex: opening one
+ * panel closes any other, exactly like the standalone app's PanelMutex, but
+ * without the app-only `ui-context`. The rail toggles panels through here and
+ * the panel host renders whichever id is open. Kept deliberately tiny so the
+ * chrome stays a thin shell around Univer.
+ */
+import { createContext, useContext, useMemo, useState, type ReactNode } from 'react';
+
+export interface PanelStore {
+  /** The id of the currently-open panel, or null when the rail is all-closed. */
+  openPanelId: string | null;
+  /** Open `id`, replacing whatever was open (mutex). */
+  open: (id: string) => void;
+  /** Close the open panel. */
+  close: () => void;
+  /** Toggle `id`: open it if closed, close it if it's the open one. */
+  toggle: (id: string) => void;
+}
+
+const PanelContext = createContext<PanelStore | null>(null);
+
+export function PanelProvider({ children }: { children: ReactNode }) {
+  const [openPanelId, setOpenPanelId] = useState<string | null>(null);
+  const store = useMemo<PanelStore>(
+    () => ({
+      openPanelId,
+      open: (id) => setOpenPanelId(id),
+      close: () => setOpenPanelId(null),
+      toggle: (id) => setOpenPanelId((cur) => (cur === id ? null : id)),
+    }),
+    [openPanelId],
+  );
+  return <PanelContext.Provider value={store}>{children}</PanelContext.Provider>;
+}
+
+/** Read the panel store. Returns a no-op store when used outside a provider. */
+export function usePanels(): PanelStore {
+  return (
+    useContext(PanelContext) ?? {
+      openPanelId: null,
+      open: () => {},
+      close: () => {},
+      toggle: () => {},
+    }
+  );
+}

package/src/chrome/panel-registry.ts

@@ -0,0 +1,48 @@
+/**
+ * Copyright 2026 Casual Office
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ */
+
+/**
+ * Built-in side panels the SDK chrome ships (mirrors `BUILT_IN_DIALOGS`). Each
+ * entry gets a rail button + a body rendered by the panel host. Hosts can add
+ * more via `extensions.panels` (see extensions.ts) — those are merged after
+ * these on the rail.
+ */
+import { lazy, type ComponentType } from 'react';
+
+import type { PanelComponentProps } from './extensions';
+import { TablesPanel } from './TablesPanel';
+import { PivotFieldsPanel } from './PivotFieldsPanel';
+import { CommentsPanel } from './CommentsPanel';
+import { HistoryPanel } from './HistoryPanel';
+// Charts panel pulls echarts — lazy so it (and echarts) only load when the
+// panel is first opened. PanelHost renders panels inside a Suspense boundary.
+const ChartsPanel = lazy(() =>
+  import('../charts/ChartsPanel').then((m) => ({ default: m.ChartsPanel })),
+);
+
+export interface BuiltInPanel {
+  /** Stable id (rail `data-testid` `cs-panel-rail-<id>`, mutex key). */
+  id: string;
+  /** Rail button tooltip / aria-label. */
+  label: string;
+  /** Material Symbols icon name for the rail button. */
+  icon: string;
+  /** The panel body; receives `{ api, onClose }`. */
+  component: ComponentType<PanelComponentProps>;
+}
+
+export const BUILT_IN_PANELS: BuiltInPanel[] = [
+  { id: 'tables', label: 'Tables', icon: 'table', component: TablesPanel },
+  {
+    id: 'pivot',
+    label: 'PivotTable Fields',
+    icon: 'pivot_table_chart',
+    component: PivotFieldsPanel,
+  },
+  { id: 'charts', label: 'Charts', icon: 'analytics', component: ChartsPanel },
+  { id: 'comments', label: 'Comments', icon: 'forum', component: CommentsPanel },
+  { id: 'history', label: 'History', icon: 'history', component: HistoryPanel },
+];

package/src/chrome/panel-shell.tsx

@@ -0,0 +1,151 @@
+/**
+ * Copyright 2026 Casual Office
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ */
+
+/**
+ * Shared chrome for the side panels — a consistent, polished header (icon +
+ * title + optional count/actions + hover-capable close) and small building
+ * blocks, so every panel (Tables / Charts / Pivot / Comments / History) looks
+ * the same. Styling maps to the design-system tokens the host loads
+ * (`--color-*`), falling back to the chrome vars, then a hardcoded default —
+ * so it looks right standalone and themed inside a host.
+ */
+import { useState, type CSSProperties, type ReactNode } from 'react';
+
+import { Icon } from './Icon';
+
+const MUTED = 'var(--color-text-secondary, var(--cs-chrome-muted, #605e5c))';
+const DIVIDER = 'var(--color-divider, var(--cs-chrome-border, #edeff3))';
+
+const headerStyle: CSSProperties = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: 10,
+  padding: '10px 14px',
+  flex: '0 0 auto',
+  background: 'var(--color-surface, var(--cs-chrome-input-bg, #ffffff))',
+  borderBottom: `1px solid ${DIVIDER}`,
+};
+
+const titleStyle: CSSProperties = {
+  fontWeight: 600,
+  fontSize: 14,
+  flex: 1,
+  minWidth: 0,
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+  whiteSpace: 'nowrap',
+};
+
+const countStyle: CSSProperties = {
+  fontSize: 11,
+  fontWeight: 600,
+  minWidth: 18,
+  height: 18,
+  padding: '0 5px',
+  display: 'inline-flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  borderRadius: 9,
+  background: 'var(--color-hover, rgba(15,23,42,0.06))',
+  color: MUTED,
+};
+
+/** A ghost icon button with a real hover state (inline styles can't do :hover). */
+export function IconButton({
+  name,
+  label,
+  onClick,
+  size = 18,
+}: {
+  name: string;
+  label: string;
+  onClick: () => void;
+  size?: number;
+}) {
+  const [hover, setHover] = useState(false);
+  return (
+    <button
+      type="button"
+      aria-label={label}
+      title={label}
+      onClick={onClick}
+      onMouseEnter={() => setHover(true)}
+      onMouseLeave={() => setHover(false)}
+      style={{
+        flex: '0 0 auto',
+        display: 'inline-flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        width: 26,
+        height: 26,
+        border: 'none',
+        borderRadius: 6,
+        cursor: 'pointer',
+        color: hover ? 'var(--color-text, var(--cs-chrome-fg, #201f1e))' : MUTED,
+        background: hover ? 'var(--color-hover, rgba(15,23,42,0.06))' : 'transparent',
+      }}
+    >
+      <Icon name={name} size={size} />
+    </button>
+  );
+}
+
+export function PanelHeader({
+  icon,
+  title,
+  count,
+  onClose,
+  actions,
+}: {
+  icon: string;
+  title: string;
+  count?: number;
+  onClose: () => void;
+  /** Optional trailing actions (e.g. an add button) shown before the close. */
+  actions?: ReactNode;
+}) {
+  return (
+    <header style={headerStyle}>
+      <Icon name={icon} size={18} style={{ color: MUTED, flex: '0 0 auto' }} />
+      <span style={titleStyle}>{title}</span>
+      {count != null && count > 0 && <span style={countStyle}>{count}</span>}
+      {actions}
+      <IconButton name="close" label={`Close ${title} panel`} onClick={onClose} />
+    </header>
+  );
+}
+
+/** Centered empty-state block for panels with no content yet. */
+export function PanelEmpty({
+  icon,
+  title,
+  children,
+  testId,
+}: {
+  icon: string;
+  title: string;
+  children?: ReactNode;
+  testId?: string;
+}) {
+  return (
+    <div
+      data-testid={testId}
+      style={{
+        textAlign: 'center',
+        padding: '32px 20px',
+        color: MUTED,
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        gap: 6,
+      }}
+    >
+      <Icon name={icon} size={40} style={{ opacity: 0.35 }} />
+      <div style={{ fontWeight: 600, fontSize: 14, color: 'var(--color-text, inherit)' }}>{title}</div>
+      {children && <div style={{ fontSize: 13, lineHeight: 1.5 }}>{children}</div>}
+    </div>
+  );
+}

package/src/pivots/apply.ts

@@ -0,0 +1,139 @@
+/**
+ * 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 { computePivot, type PivotGrid, type SourceMatrix } from './compute';
+import type { PivotModel } from './types';
+
+/**
+ * Read the source range, compute the pivot, then write the resulting
+ * cell grid into the target sheet starting at `model.target`. The
+ * write is one `setRangeValues` call so it lands as a single Univer
+ * mutation — collab and undo both treat it atomically.
+ *
+ * If `prevExtent` is supplied (refresh path), the previous output
+ * rectangle is cleared first so a shrunk pivot doesn't leave residual
+ * rows from the prior write. Insert paths pass null.
+ */
+export function applyPivot(
+  api: FUniver,
+  model: PivotModel,
+  prevExtent?: { rows: number; cols: number } | null,
+): { rows: number; cols: number } | null {
+  const wb = api.getActiveWorkbook();
+  if (!wb) return null;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const sheets = wb.getSheets() as any[];
+  const sourceWs = sheets.find((s) => s.getSheetId?.() === model.sourceSheetId);
+  const targetWs = sheets.find((s) => s.getSheetId?.() === model.targetSheetId);
+  if (!sourceWs || !targetWs) return null;
+
+  const matrix = readSourceMatrix(sourceWs, model.source);
+  if (matrix.records.length === 0) return null;
+
+  const { grid } = computePivot(matrix, model);
+  if (grid.length === 0) return null;
+
+  // Clear the previous extent first if we have one — keeps stale rows
+  // from leaking through when the new grid is smaller (e.g. a filter
+  // narrowed the row keys, or the source range shrank).
+  if (prevExtent && (prevExtent.rows > grid.length || prevExtent.cols > (grid[0]?.length ?? 0))) {
+    clearGridArea(targetWs, model.target, prevExtent);
+  }
+
+  writeGridToSheet(targetWs, model.target, grid);
+  return { rows: grid.length, cols: grid[0]?.length ?? 0 };
+}
+
+/**
+ * P1 — re-read source data and re-apply the pivot. Refreshing is what
+ * makes pivots track upstream edits; without it the output frozen at
+ * insert time goes stale. Returns the new extent (or null on failure).
+ */
+export function refreshPivot(
+  api: FUniver,
+  model: PivotModel,
+): { rows: number; cols: number } | null {
+  return applyPivot(api, model, model.lastOutputExtent ?? null);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function readSourceMatrix(ws: any, src: PivotModel['source']): SourceMatrix {
+  const headers: string[] = [];
+  for (let c = src.startColumn; c <= src.endColumn; c++) {
+    const v = ws.getRange(src.startRow, c).getValue();
+    headers.push(v == null ? '' : String(v));
+  }
+  const records: Array<Array<string | number | null>> = [];
+  for (let r = src.startRow + 1; r <= src.endRow; r++) {
+    const row: Array<string | number | null> = [];
+    let anyValue = false;
+    for (let c = src.startColumn; c <= src.endColumn; c++) {
+      const v = ws.getRange(r, c).getValue();
+      if (v == null || v === '') {
+        row.push(null);
+      } else if (typeof v === 'number' || typeof v === 'string') {
+        row.push(v);
+        anyValue = true;
+      } else if (typeof v === 'boolean') {
+        row.push(v ? 1 : 0);
+        anyValue = true;
+      } else {
+        row.push(String(v));
+        anyValue = true;
+      }
+    }
+    // Skip blank rows — Excel treats them as terminators, but a
+    // misclick that includes an extra blank row in the selection
+    // shouldn't introduce a phantom "(blank)" key. Drop them.
+    if (anyValue) records.push(row);
+  }
+  return { headers, records };
+}
+
+/** Blank an arbitrary rectangle on the sheet — used by refresh to
+ *  reset the previous output before writing the new grid. */
+function clearGridArea(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ws: any,
+  target: { row: number; column: number },
+  extent: { rows: number; cols: number },
+): void {
+  const blank: Array<Array<{ v: null }>> = [];
+  for (let r = 0; r < extent.rows; r += 1) {
+    const row: Array<{ v: null }> = [];
+    for (let c = 0; c < extent.cols; c += 1) {
+      row.push({ v: null });
+    }
+    blank.push(row);
+  }
+  const range = ws.getRange(target.row, target.column, extent.rows, extent.cols);
+  range.setValues(blank);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function writeGridToSheet(ws: any, target: { row: number; column: number }, grid: PivotGrid): void {
+  const rows = grid.length;
+  const cols = grid[0]?.length ?? 0;
+  if (rows === 0 || cols === 0) return;
+  // Build the IRange-shaped object setRangeValues expects: a 2D
+  // array of `{ v }` cell objects keyed by `[r-offset][c-offset]`.
+  const cellMatrix: Array<Array<{ v: string | number | null }>> = grid.map((rowVals) =>
+    rowVals.map((v) => ({ v })),
+  );
+  const range = ws.getRange(target.row, target.column, rows, cols);
+  range.setValues(cellMatrix);
+}