@casualoffice/sheets 0.9.0

package/src/xlsx/style-mapping.ts

@@ -0,0 +1,171 @@
+import type { IStyleData } from '@univerjs/core';
+import type * as ExcelJS from 'exceljs';
+
+/**
+ * Mappings between ExcelJS and Univer style models.
+ *
+ * Univer's `IStyleData` uses two-letter compact keys (bl, it, ff, fs, cl, bg,
+ * ht, vt, n, ul, bd) plus numeric enums for alignment. ExcelJS uses verbose
+ * keys (font.bold, alignment.horizontal, numFmt, etc.). Round-trip preserves
+ * the basics; advanced styling (gradients, patterns, complex borders) falls
+ * back to defaults.
+ */
+
+const ARGB_RX = /^#?([0-9A-Fa-f]{6,8})$/;
+
+function normalizeColor(argb: string | undefined): string | undefined {
+  if (!argb) return undefined;
+  const m = ARGB_RX.exec(argb);
+  if (!m) return undefined;
+  const hex = m[1];
+  // ExcelJS uses ARGB; drop alpha if present.
+  const rgb = hex.length === 8 ? hex.slice(2) : hex;
+  return `#${rgb.toLowerCase()}`;
+}
+
+// Accept Univer's Nullable<string> (string | null | void) by treating any
+// non-string input as undefined.
+function toARGB(rgb: unknown): string | undefined {
+  if (typeof rgb !== 'string' || !rgb) return undefined;
+  const m = ARGB_RX.exec(rgb);
+  if (!m) return undefined;
+  const hex = m[1];
+  const norm = hex.length === 8 ? hex : `FF${hex}`;
+  return norm.toUpperCase();
+}
+
+// Univer HorizontalAlign: 0 = default, 1 = LEFT, 2 = CENTER, 3 = RIGHT
+const H_ALIGN_FROM_EXCEL: Record<string, number> = {
+  left: 1,
+  center: 2,
+  right: 3,
+};
+const H_ALIGN_TO_EXCEL: Record<number, string> = {
+  1: 'left',
+  2: 'center',
+  3: 'right',
+};
+
+// Univer VerticalAlign: 0 = default, 1 = TOP, 2 = MIDDLE, 3 = BOTTOM
+const V_ALIGN_FROM_EXCEL: Record<string, number> = {
+  top: 1,
+  middle: 2,
+  bottom: 3,
+};
+const V_ALIGN_TO_EXCEL: Record<number, string> = {
+  1: 'top',
+  2: 'middle',
+  3: 'bottom',
+};
+
+export function excelStyleToUniver(cell: ExcelJS.Cell): IStyleData | undefined {
+  const s: IStyleData = {};
+
+  if (cell.font) {
+    if (cell.font.name) s.ff = cell.font.name;
+    if (cell.font.size) s.fs = cell.font.size;
+    if (cell.font.bold) s.bl = 1;
+    if (cell.font.italic) s.it = 1;
+    if (cell.font.underline) s.ul = { s: 1 };
+    const fc = normalizeColor((cell.font.color as { argb?: string } | undefined)?.argb);
+    if (fc) s.cl = { rgb: fc };
+  }
+
+  if (cell.fill && cell.fill.type === 'pattern' && cell.fill.pattern === 'solid') {
+    const bg = normalizeColor((cell.fill.fgColor as { argb?: string } | undefined)?.argb);
+    if (bg) s.bg = { rgb: bg };
+  }
+
+  if (cell.alignment) {
+    const ha = cell.alignment.horizontal;
+    if (ha && H_ALIGN_FROM_EXCEL[ha] !== undefined) s.ht = H_ALIGN_FROM_EXCEL[ha];
+    const va = cell.alignment.vertical;
+    if (va && V_ALIGN_FROM_EXCEL[va] !== undefined) s.vt = V_ALIGN_FROM_EXCEL[va];
+    if (cell.alignment.wrapText) s.tb = 3; // WrapStrategy.WRAP
+  }
+
+  if (cell.numFmt) s.n = { pattern: cell.numFmt };
+
+  // Borders — keep simple: any side present => thin border, color from spec.
+  if (cell.border) {
+    const bd: NonNullable<IStyleData['bd']> = {};
+    const sides: Array<['t' | 'b' | 'l' | 'r', 'top' | 'bottom' | 'left' | 'right']> = [
+      ['t', 'top'],
+      ['b', 'bottom'],
+      ['l', 'left'],
+      ['r', 'right'],
+    ];
+    for (const [k, key] of sides) {
+      const side = (cell.border as Record<string, unknown>)[key] as
+        | { style?: string; color?: { argb?: string } }
+        | undefined;
+      if (side?.style && side.style !== 'none') {
+        bd[k] = { s: 1, cl: { rgb: normalizeColor(side.color?.argb) ?? '#666666' } };
+      }
+    }
+    if (Object.keys(bd).length > 0) s.bd = bd;
+  }
+
+  return Object.keys(s).length > 0 ? s : undefined;
+}
+
+export function univerStyleToExcel(style: IStyleData): Partial<ExcelJS.Style> {
+  const out: Partial<ExcelJS.Style> = {};
+
+  const font: ExcelJS.Style['font'] = {};
+  if (style.ff) font.name = style.ff;
+  if (style.fs) font.size = style.fs;
+  if (style.bl === 1) font.bold = true;
+  if (style.it === 1) font.italic = true;
+  if (style.ul?.s === 1) font.underline = true;
+  if (style.cl && typeof style.cl === 'object' && 'rgb' in style.cl) {
+    const argb = toARGB(style.cl.rgb);
+    if (argb) font.color = { argb };
+  }
+  if (Object.keys(font).length > 0) out.font = font;
+
+  if (style.bg && typeof style.bg === 'object' && 'rgb' in style.bg) {
+    const argb = toARGB(style.bg.rgb);
+    if (argb) {
+      out.fill = {
+        type: 'pattern',
+        pattern: 'solid',
+        fgColor: { argb },
+      };
+    }
+  }
+
+  const alignment: ExcelJS.Style['alignment'] = {};
+  if (style.ht && H_ALIGN_TO_EXCEL[style.ht]) {
+    alignment.horizontal = H_ALIGN_TO_EXCEL[style.ht] as ExcelJS.Style['alignment']['horizontal'];
+  }
+  if (style.vt && V_ALIGN_TO_EXCEL[style.vt]) {
+    alignment.vertical = V_ALIGN_TO_EXCEL[style.vt] as ExcelJS.Style['alignment']['vertical'];
+  }
+  if (style.tb === 3) alignment.wrapText = true;
+  if (Object.keys(alignment).length > 0) out.alignment = alignment;
+
+  if (style.n?.pattern) out.numFmt = style.n.pattern;
+
+  if (style.bd) {
+    const border: ExcelJS.Style['border'] = {};
+    const sides: Array<['t' | 'b' | 'l' | 'r', 'top' | 'bottom' | 'left' | 'right']> = [
+      ['t', 'top'],
+      ['b', 'bottom'],
+      ['l', 'left'],
+      ['r', 'right'],
+    ];
+    for (const [k, key] of sides) {
+      const side = style.bd[k];
+      if (!side) continue;
+      const color = side.cl && 'rgb' in side.cl ? toARGB(side.cl.rgb) : undefined;
+      (border as Record<string, unknown>)[key] = {
+        style: 'thin',
+        ...(color ? { color: { argb: color } } : {}),
+      };
+    }
+    if (Object.keys(border).length > 0) out.border = border;
+  }
+
+  return out;
+}

package/src/xlsx/tables-resource.ts

@@ -0,0 +1,211 @@
+import type ExcelJS from 'exceljs';
+import type { IWorkbookData } from '@univerjs/core';
+
+/**
+ * Passthrough preservation for xlsx ListObjects (a.k.a. Excel Tables).
+ * Univer doesn't model tables as first-class objects — autofilters and
+ * structured-reference parsing aren't there yet — so without a
+ * passthrough, opening an xlsx that ships a defined table and saving
+ * it again would silently strip the table back to plain cells.
+ *
+ * Data lives in our own sidecar (`__casual_sheets_tables__`); on
+ * export we replay `ws.addTable(...)` so the saved file shows the
+ * table to any reader (real Excel, gsheets, LibreOffice).
+ *
+ * When/if Univer grows native table support, this resource is the
+ * place to switch from sidecar to plugin shape — readers of older
+ * files keep working because the sidecar is forward-compatible.
+ */
+
+export const TABLES_RESOURCE = '__casual_sheets_tables__';
+
+export type SynthTableColumn = {
+  name: string;
+  filterButton?: boolean;
+  totalsRowFunction?: string;
+  totalsRowLabel?: string;
+  totalsRowFormula?: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  style?: any;
+};
+
+export type SynthTableV1 = {
+  name: string;
+  ref: string; // 'A1' or 'A1:C4'
+  displayName?: string;
+  headerRow?: boolean;
+  totalsRow?: boolean;
+  style?: {
+    theme?: string;
+    name?: string;
+    showRowStripes?: boolean;
+    showColumnStripes?: boolean;
+    showFirstColumn?: boolean;
+    showLastColumn?: boolean;
+  };
+  columns: SynthTableColumn[];
+  rows: unknown[][];
+};
+
+type Payload = {
+  v: 1;
+  sheets: Record<string, SynthTableV1[]>;
+};
+
+/**
+ * Walk every worksheet and lift any defined tables into the sidecar
+ * payload. ExcelJS stores tables on `ws.tables` keyed by table name;
+ * each value is a Table *instance* whose actual fields hang off
+ * `t.model` (`node_modules/exceljs/lib/doc/table.js:275`). Two
+ * gotchas the parser must handle:
+ *
+ *   1. After `xlsx.load`, the model uses `tableRef` (full range) and
+ *      drops `ref` (the original top-left author hint). We coalesce
+ *      onto `ref` as a single canonical full-range string.
+ *   2. The loaded model never carries `rows` — table cell data is
+ *      already on the worksheet. We don't need rows to round-trip.
+ */
+export function readTablesFromXlsx(
+  wb: ExcelJS.Workbook,
+  sheetIdForExcel: (excelId: number) => string,
+): Record<string, SynthTableV1[]> {
+  const out: Record<string, SynthTableV1[]> = {};
+  for (const ws of wb.worksheets) {
+    const tableMap = (ws as unknown as { tables?: Record<string, unknown> | Map<string, unknown> })
+      .tables;
+    if (!tableMap) continue;
+    const entries: unknown[] = tableMap instanceof Map
+      ? Array.from(tableMap.values())
+      : Object.values(tableMap);
+    if (entries.length === 0) continue;
+
+    const tables: SynthTableV1[] = [];
+    for (const tUnknown of entries) {
+      const tInstance = tUnknown as { model?: unknown };
+      const modelUnknown = (tInstance && typeof tInstance === 'object' && 'model' in tInstance)
+        ? tInstance.model
+        : tUnknown;
+      const model = modelUnknown as Record<string, unknown>;
+      if (!model || typeof model !== 'object') continue;
+      const name = model.name;
+      // Prefer the post-load `tableRef` (full range, eg `'A1:B3'`).
+      // Fall back to `ref` for tables that were `addTable`d in-process
+      // and never made the round-trip through xform load.
+      const refStr = typeof model.tableRef === 'string'
+        ? model.tableRef
+        : typeof model.ref === 'string'
+          ? model.ref
+          : null;
+      if (typeof name !== 'string' || !refStr) continue;
+
+      const cols: SynthTableColumn[] = Array.isArray(model.columns)
+        ? (model.columns as unknown[]).map((cUnknown) => {
+            const c = cUnknown as Record<string, unknown>;
+            return {
+              name: typeof c?.name === 'string' ? c.name : '',
+              ...(typeof c?.filterButton === 'boolean' ? { filterButton: c.filterButton } : {}),
+              ...(typeof c?.totalsRowFunction === 'string'
+                ? { totalsRowFunction: c.totalsRowFunction }
+                : {}),
+              ...(typeof c?.totalsRowLabel === 'string'
+                ? { totalsRowLabel: c.totalsRowLabel }
+                : {}),
+              ...(typeof c?.totalsRowFormula === 'string'
+                ? { totalsRowFormula: c.totalsRowFormula }
+                : {}),
+            };
+          })
+        : [];
+
+      tables.push({
+        name,
+        ref: refStr,
+        ...(typeof model.displayName === 'string' ? { displayName: model.displayName } : {}),
+        ...(typeof model.headerRow === 'boolean' ? { headerRow: model.headerRow } : {}),
+        ...(typeof model.totalsRow === 'boolean' ? { totalsRow: model.totalsRow } : {}),
+        ...(model.style && typeof model.style === 'object'
+          ? { style: model.style as SynthTableV1['style'] }
+          : {}),
+        columns: cols,
+        rows: [],
+      });
+    }
+    if (tables.length > 0) out[sheetIdForExcel(ws.id)] = tables;
+  }
+  return out;
+}
+
+/** Merge a synthesised table map into the snapshot resources. */
+export function mergeTablesIntoResources(
+  resources: IWorkbookData['resources'],
+  payload: Record<string, SynthTableV1[]>,
+): IWorkbookData['resources'] {
+  if (Object.keys(payload).length === 0) return resources;
+  const existing = resources?.find((r) => r.name === TABLES_RESOURCE);
+  if (existing) return resources;
+  const body: Payload = { v: 1, sheets: payload };
+  const next = [...(resources ?? [])];
+  next.push({ name: TABLES_RESOURCE, data: JSON.stringify(body) });
+  return next;
+}
+
+/** Read the tables resource off a snapshot. */
+export function readTablesFromSnapshot(
+  data: IWorkbookData,
+): Record<string, SynthTableV1[]> {
+  const entry = data.resources?.find((r) => r.name === TABLES_RESOURCE);
+  if (!entry?.data) return {};
+  try {
+    const parsed = JSON.parse(entry.data) as Partial<Payload>;
+    if (parsed?.v !== 1 || !parsed.sheets) return {};
+    return parsed.sheets;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Apply a per-sheet table set onto an ExcelJS worksheet.
+ *
+ * Why this bypasses `ws.addTable(...)`:
+ *
+ *   `Table.validate()` (`node_modules/exceljs/lib/doc/table.js:129`)
+ *   throws when `table.rows` is missing — but our round-trip case
+ *   doesn't carry rows (cell data already lives in `cellData`). And
+ *   `Table.store()` would *re-write* every cell from the rows
+ *   array, clobbering whatever the user had set after the table was
+ *   created. So instead of going through `addTable`, we attach the
+ *   load-shape model directly the same way ExcelJS's worksheet xform
+ *   setter does on load (`node_modules/exceljs/lib/doc/worksheet.js:
+ *   917`). The serializer then walks `Object.values(ws.tables).map(t
+ *   => t.model)` (`worksheet.js:856`) and writes the table parts —
+ *   `target` + `id` are filled in by `xlsx.js:632` during prepare.
+ */
+export function applyTablesToXlsxWorksheet(
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ws: any,
+  tables: SynthTableV1[],
+): void {
+  if (!tables?.length) return;
+  ws.tables = ws.tables ?? {};
+  for (const t of tables) {
+    if (!t?.name || !t?.ref || !Array.isArray(t.columns) || t.columns.length === 0) continue;
+    const model: Record<string, unknown> = {
+      name: t.name,
+      displayName: t.displayName ?? t.name,
+      tableRef: t.ref,
+      autoFilterRef: t.ref,
+      headerRow: t.headerRow ?? true,
+      totalsRow: t.totalsRow ?? false,
+      columns: t.columns.map((c) => ({
+        name: c.name,
+        ...(c.filterButton !== undefined ? { filterButton: c.filterButton } : {}),
+        ...(c.totalsRowFunction ? { totalsRowFunction: c.totalsRowFunction } : {}),
+        ...(c.totalsRowLabel ? { totalsRowLabel: c.totalsRowLabel } : {}),
+        ...(c.totalsRowFormula ? { totalsRowFormula: c.totalsRowFormula } : {}),
+      })),
+      style: t.style ?? {},
+    };
+    ws.tables[t.name] = { model };
+  }
+}