@svgrid/grid 1.0.2 → 1.1.0

package/src/filter-operators.test.ts

@@ -0,0 +1,174 @@
+import { describe, expect, it } from "vitest";
+import {
+  filterOperatorOptions,
+  fallbackOperatorOption,
+  TEXT_OPERATORS,
+  NUMBER_OPERATORS,
+  DATE_OPERATORS,
+  CHECKBOX_OPERATORS,
+  operatorOption,
+  operatorsForColumn,
+  defaultOperatorFor,
+  operatorLabelFor,
+} from "./filter-operators";
+import type { FilterOperator, FilterOption } from "./SvGrid.types";
+
+// `operatorsForColumn` / `defaultOperatorFor` / `operatorLabelFor` only ever
+// read `column?.columnDef.editorType`, so a minimal duck-typed stub is enough
+// to exercise every branch without standing up a real grid/column instance.
+function col(editorType?: string): any {
+  return editorType === undefined
+    ? { columnDef: {} }
+    : { columnDef: { editorType } };
+}
+
+describe("filter-operators: catalogue integrity", () => {
+  it("every option exposes value/label/iconName and a unique value", () => {
+    const values = filterOperatorOptions.map((o) => o.value);
+    expect(new Set(values).size).toBe(values.length);
+    for (const o of filterOperatorOptions) {
+      expect(typeof o.value).toBe("string");
+      expect(typeof o.label).toBe("string");
+      expect(o.iconName).toMatch(/^op-/);
+    }
+  });
+
+  it("fallback option is the 'contains' operator", () => {
+    expect(fallbackOperatorOption.value).toBe("contains");
+    expect(fallbackOperatorOption.label).toBe("Contains");
+  });
+
+  it("each type's operator list only references catalogued operators", () => {
+    const known = new Set(filterOperatorOptions.map((o) => o.value));
+    for (const list of [
+      TEXT_OPERATORS,
+      NUMBER_OPERATORS,
+      DATE_OPERATORS,
+      CHECKBOX_OPERATORS,
+    ]) {
+      for (const id of list) expect(known.has(id)).toBe(true);
+    }
+  });
+
+  it("the catalogue includes between / isBlank for numeric + date filtering", () => {
+    const values = filterOperatorOptions.map((o) => o.value);
+    expect(values).toContain("between");
+    expect(values).toContain("isBlank");
+  });
+});
+
+describe("operatorOption", () => {
+  it("returns the matching option for every catalogued operator", () => {
+    for (const o of filterOperatorOptions) {
+      expect(operatorOption(o.value)).toBe(o);
+    }
+  });
+
+  it("looks up a specific operator by value", () => {
+    expect(operatorOption("between")).toMatchObject({
+      value: "between",
+      label: "Between",
+    });
+    expect(operatorOption("greaterThan").label).toBe("Greater than");
+    expect(operatorOption("lessThan").label).toBe("Less than");
+    expect(operatorOption("startsWith").label).toBe("Starts with");
+  });
+
+  it("falls back to 'contains' for an unknown operator value", () => {
+    const result = operatorOption("nope" as FilterOperator);
+    expect(result).toBe(fallbackOperatorOption);
+    expect(result.value).toBe("contains");
+  });
+});
+
+describe("operatorsForColumn", () => {
+  const labels = (opts: FilterOption[]) => opts.map((o) => o.value);
+
+  it("number columns get equals/greaterThan/lessThan/between/isBlank", () => {
+    expect(labels(operatorsForColumn(col("number")))).toEqual(NUMBER_OPERATORS);
+  });
+
+  it("date columns get the date operator set", () => {
+    expect(labels(operatorsForColumn(col("date")))).toEqual(DATE_OPERATORS);
+  });
+
+  it("datetime columns share the date operator set", () => {
+    expect(labels(operatorsForColumn(col("datetime")))).toEqual(DATE_OPERATORS);
+  });
+
+  it("checkbox columns get only equals + isBlank", () => {
+    expect(labels(operatorsForColumn(col("checkbox")))).toEqual(
+      CHECKBOX_OPERATORS,
+    );
+  });
+
+  it("text columns get the text operator set", () => {
+    expect(labels(operatorsForColumn(col("text")))).toEqual(TEXT_OPERATORS);
+  });
+
+  it("an unknown editor type defaults to the text operator set", () => {
+    expect(labels(operatorsForColumn(col("currency")))).toEqual(TEXT_OPERATORS);
+  });
+
+  it("a column with no editorType defaults to text", () => {
+    expect(labels(operatorsForColumn(col()))).toEqual(TEXT_OPERATORS);
+  });
+
+  it("an undefined column defaults to the text operator set", () => {
+    expect(labels(operatorsForColumn(undefined))).toEqual(TEXT_OPERATORS);
+  });
+
+  it("returns full FilterOption objects (value+label+iconName), in order", () => {
+    const opts = operatorsForColumn(col("number"));
+    expect(opts[0]).toMatchObject({ value: "equals", iconName: "op-equals" });
+    for (const o of opts) {
+      expect(o).toHaveProperty("label");
+      expect(o).toHaveProperty("iconName");
+    }
+  });
+});
+
+describe("defaultOperatorFor", () => {
+  it("picks the first operator valid for the column type", () => {
+    expect(defaultOperatorFor(col("number"))).toBe("equals");
+    expect(defaultOperatorFor(col("date"))).toBe("equals");
+    expect(defaultOperatorFor(col("checkbox"))).toBe("equals");
+    expect(defaultOperatorFor(col("text"))).toBe("contains");
+  });
+
+  it("defaults to 'contains' for text / unknown / undefined columns", () => {
+    expect(defaultOperatorFor(col())).toBe("contains");
+    expect(defaultOperatorFor(undefined)).toBe("contains");
+    expect(defaultOperatorFor(col("mystery"))).toBe("contains");
+  });
+});
+
+describe("operatorLabelFor", () => {
+  const less = operatorOption("lessThan");
+  const greater = operatorOption("greaterThan");
+  const equals = operatorOption("equals");
+
+  it("renames lessThan/greaterThan to Before/After for date columns", () => {
+    expect(operatorLabelFor(less, col("date"))).toBe("Before");
+    expect(operatorLabelFor(greater, col("date"))).toBe("After");
+  });
+
+  it("applies the date relabelling for datetime columns too", () => {
+    expect(operatorLabelFor(less, col("datetime"))).toBe("Before");
+    expect(operatorLabelFor(greater, col("datetime"))).toBe("After");
+  });
+
+  it("leaves non-relabelled operators untouched on date columns", () => {
+    expect(operatorLabelFor(equals, col("date"))).toBe(equals.label);
+  });
+
+  it("keeps the catalogue label for non-date columns", () => {
+    expect(operatorLabelFor(less, col("number"))).toBe("Less than");
+    expect(operatorLabelFor(greater, col("number"))).toBe("Greater than");
+    expect(operatorLabelFor(less, col("text"))).toBe("Less than");
+  });
+
+  it("keeps the catalogue label when the column is undefined", () => {
+    expect(operatorLabelFor(greater, undefined)).toBe("Greater than");
+  });
+});

package/src/filter-operators.ts

@@ -0,0 +1,87 @@
+// Filter-operator catalogue + the pure helpers that pick which operators
+// apply to a column and how they're labelled. Fully static - no grid state -
+// so it lives outside the controller.
+import type { Column, RowData } from "./index";
+import type { FilterOperator, FilterOption } from "./SvGrid.types";
+
+export const filterOperatorOptions: Array<FilterOption> = [
+  { value: "contains", label: "Contains", iconName: "op-contains" },
+  { value: "equals", label: "Equals", iconName: "op-equals" },
+  { value: "startsWith", label: "Starts with", iconName: "op-startsWith" },
+  { value: "greaterThan", label: "Greater than", iconName: "op-greaterThan" },
+  { value: "lessThan", label: "Less than", iconName: "op-lessThan" },
+  { value: "between", label: "Between", iconName: "op-between" },
+  { value: "isBlank", label: "Is blank", iconName: "op-isBlank" },
+];
+/** Which operators make sense for each column editor type. */
+export const TEXT_OPERATORS: Array<FilterOperator> = [
+  "contains",
+  "equals",
+  "startsWith",
+  "isBlank",
+];
+export const NUMBER_OPERATORS: Array<FilterOperator> = [
+  "equals",
+  "greaterThan",
+  "lessThan",
+  "between",
+  "isBlank",
+];
+export const DATE_OPERATORS: Array<FilterOperator> = [
+  "equals",
+  "lessThan",
+  "greaterThan",
+  "between",
+  "isBlank",
+];
+export const CHECKBOX_OPERATORS: Array<FilterOperator> = ["equals", "isBlank"];
+export const fallbackOperatorOption: FilterOption = {
+  value: "contains",
+  label: "Contains",
+  iconName: "op-contains",
+};
+
+export function operatorOption(value: FilterOperator): FilterOption {
+  return (
+    filterOperatorOptions.find((option) => option.value === value) ??
+    fallbackOperatorOption
+  );
+}
+
+/** Returns the operators that make sense for the given column's data type. */
+export function operatorsForColumn<TData extends RowData>(
+  column: Column<TData> | undefined,
+): Array<FilterOption> {
+  const editorType = column?.columnDef.editorType ?? "text";
+  const ids =
+    editorType === "number"
+      ? NUMBER_OPERATORS
+      : editorType === "date" || editorType === "datetime"
+        ? DATE_OPERATORS
+        : editorType === "checkbox"
+          ? CHECKBOX_OPERATORS
+          : TEXT_OPERATORS;
+  return ids
+    .map((id) => filterOperatorOptions.find((option) => option.value === id))
+    .filter((option): option is FilterOption => Boolean(option));
+}
+
+/** Default operator for a column (first one valid for its type). */
+export function defaultOperatorFor<TData extends RowData>(
+  column: Column<TData> | undefined,
+): FilterOperator {
+  return operatorsForColumn(column)[0]?.value ?? "contains";
+}
+
+/** Date columns get friendlier labels for "less / greater than". */
+export function operatorLabelFor<TData extends RowData>(
+  option: FilterOption,
+  column: Column<TData> | undefined,
+): string {
+  const editorType = column?.columnDef.editorType;
+  if (editorType === "date" || editorType === "datetime") {
+    if (option.value === "lessThan") return "Before";
+    if (option.value === "greaterThan") return "After";
+  }
+  return option.label;
+}

package/src/hyperformula-adapter.test.ts

@@ -0,0 +1,256 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+  createHyperFormulaSheet,
+  type HyperFormulaInstance,
+} from './hyperformula-adapter'
+
+/**
+ * A tiny in-memory fake that emulates just the slice of the HyperFormula
+ * API the adapter touches: setCellContents / getCellValue / destroy.
+ *
+ * It stores raw cell contents in a Map keyed by "sheet:row:col" and
+ * evaluates `=A1+B1` style formulas with a deliberately small expression
+ * engine so we can assert the adapter wires reads/writes correctly without
+ * needing the real ~1MB hyperformula package.
+ */
+function makeFakeEngine() {
+  const raw = new Map<string, unknown>()
+  const key = (s: number, r: number, c: number) => `${s}:${r}:${c}`
+
+  // Resolve an A1 reference (e.g. "A1", "B2") to a cell value.
+  const colLetterToIndex = (letters: string) => {
+    let n = 0
+    for (const ch of letters) n = n * 26 + (ch.charCodeAt(0) - 64)
+    return n - 1
+  }
+
+  function evalCell(sheet: number, row: number, col: number): unknown {
+    const stored = raw.get(key(sheet, row, col))
+    if (typeof stored !== 'string' || !stored.startsWith('=')) return stored
+    const expr = stored.slice(1)
+    // Replace A1-style refs with their numeric values.
+    const substituted = expr.replace(/([A-Z]+)(\d+)/g, (_m, letters, digits) => {
+      const refCol = colLetterToIndex(letters)
+      const refRow = Number(digits) - 1
+      const v = evalCell(sheet, refRow, refCol)
+      return String(typeof v === 'number' ? v : 0)
+    })
+    try {
+      // Only ever digits / operators after substitution: safe to eval here.
+      // eslint-disable-next-line no-new-func
+      return Function(`"use strict";return (${substituted})`)()
+    } catch {
+      return '#ERROR!'
+    }
+  }
+
+  const engine = {
+    setCellContents: vi.fn(
+      (cell: { sheet: number; row: number; col: number }, contents: unknown) => {
+        raw.set(key(cell.sheet, cell.row, cell.col), contents)
+        return [
+          {
+            address: { sheet: cell.sheet, row: cell.row, col: cell.col },
+            newValue: evalCell(cell.sheet, cell.row, cell.col),
+          },
+        ]
+      },
+    ),
+    getCellValue: vi.fn((cell: { sheet: number; row: number; col: number }) =>
+      evalCell(cell.sheet, cell.row, cell.col),
+    ),
+    destroy: vi.fn(() => {}),
+    rebuildAndRecalculate: vi.fn(() => {}),
+    // test-only introspection
+    _raw: raw,
+  }
+  return engine as HyperFormulaInstance & {
+    setCellContents: ReturnType<typeof vi.fn>
+    getCellValue: ReturnType<typeof vi.fn>
+    destroy: ReturnType<typeof vi.fn>
+    _raw: Map<string, unknown>
+  }
+}
+
+describe('createHyperFormulaSheet', () => {
+  let hf: ReturnType<typeof makeFakeEngine>
+
+  beforeEach(() => {
+    hf = makeFakeEngine()
+  })
+
+  it('seeds the engine with one setCellContents per cell in field order', () => {
+    const rows = [
+      { a: 1, b: 2 },
+      { a: 10, b: 20 },
+    ]
+    createHyperFormulaSheet({ hyperformula: hf, rows, fields: ['a', 'b'] })
+
+    // 2 rows x 2 fields = 4 seeded cells.
+    expect(hf.setCellContents).toHaveBeenCalledTimes(4)
+    // Field 'a' is column 0, field 'b' is column 1 (order = column index).
+    expect(hf.setCellContents).toHaveBeenCalledWith(
+      { sheet: 0, row: 0, col: 0 },
+      1,
+    )
+    expect(hf.setCellContents).toHaveBeenCalledWith(
+      { sheet: 0, row: 1, col: 1 },
+      20,
+    )
+  })
+
+  it('computed snapshot pulls evaluated values out of the engine', () => {
+    const rows = [{ a: 2, b: 3, total: '=A1+B1' }]
+    const sheet = createHyperFormulaSheet({
+      hyperformula: hf,
+      rows,
+      fields: ['a', 'b', 'total'],
+    })
+    expect(sheet.computed[0]).toEqual({ a: 2, b: 3, total: 5 })
+    // getCellValue called once per cell in the snapshot (3 fields).
+    expect(hf.getCellValue).toHaveBeenCalledTimes(3)
+  })
+
+  it('raw snapshot keeps the original formula strings untouched', () => {
+    const rows = [{ a: 2, b: 3, total: '=A1+B1' }]
+    const sheet = createHyperFormulaSheet({
+      hyperformula: hf,
+      rows,
+      fields: ['a', 'b', 'total'],
+    })
+    expect(sheet.raw[0]!.total).toBe('=A1+B1')
+    // raw is a copy, not the same object reference as the input row.
+    expect(sheet.raw[0]).not.toBe(rows[0])
+  })
+
+  it('preserves non-formula fields not listed in `fields`', () => {
+    const rows = [{ a: 1, b: 2, name: 'keep-me' }]
+    const sheet = createHyperFormulaSheet({
+      hyperformula: hf,
+      rows,
+      fields: ['a', 'b'],
+    })
+    // `name` was never registered as a column but survives in computed.
+    expect(sheet.computed[0]!.name).toBe('keep-me')
+    expect(sheet.raw[0]!.name).toBe('keep-me')
+  })
+
+  it('update() writes the edited cell back and re-evaluates dependents', () => {
+    const rows = [{ a: 2, b: 3, total: '=A1+B1' }]
+    const sheet = createHyperFormulaSheet({
+      hyperformula: hf,
+      rows,
+      fields: ['a', 'b', 'total'],
+    })
+    expect(sheet.computed[0]!.total).toBe(5)
+
+    hf.setCellContents.mockClear()
+    const next = sheet.update(0, 'a', 100)
+
+    // The edited cell was pushed into the engine at its column index (a => col 0).
+    expect(hf.setCellContents).toHaveBeenCalledWith(
+      { sheet: 0, row: 0, col: 0 },
+      100,
+    )
+    // Dependent formula recomputed from the engine.
+    expect(next.computed[0]).toEqual({ a: 100, b: 3, total: 103 })
+    // raw reflects the new edited literal but keeps the formula string.
+    expect(next.raw[0]).toEqual({ a: 100, b: 3, total: '=A1+B1' })
+  })
+
+  it('update() with an unregistered field skips the engine write but updates rows', () => {
+    const rows = [{ a: 1, b: 2, note: 'x' }]
+    const sheet = createHyperFormulaSheet({
+      hyperformula: hf,
+      rows,
+      fields: ['a', 'b'],
+    })
+    hf.setCellContents.mockClear()
+
+    const next = sheet.update(0, 'note' as 'a', 'edited')
+
+    // `note` is not a registered column => no setCellContents call.
+    expect(hf.setCellContents).not.toHaveBeenCalled()
+    // But the raw/computed row still carries the new value.
+    expect(next.raw[0]!.note).toBe('edited')
+    expect(next.computed[0]!.note).toBe('edited')
+  })
+
+  it('respects a custom sheetId for every read and write', () => {
+    const rows = [{ a: 1 }]
+    const sheet = createHyperFormulaSheet({
+      hyperformula: hf,
+      rows,
+      fields: ['a'],
+      sheetId: 7,
+    })
+    expect(hf.setCellContents).toHaveBeenCalledWith(
+      { sheet: 7, row: 0, col: 0 },
+      1,
+    )
+    expect(hf.getCellValue).toHaveBeenCalledWith({ sheet: 7, row: 0, col: 0 })
+
+    hf.setCellContents.mockClear()
+    sheet.update(0, 'a', 9)
+    expect(hf.setCellContents).toHaveBeenCalledWith(
+      { sheet: 7, row: 0, col: 0 },
+      9,
+    )
+  })
+
+  it('defaults sheetId to 0 when omitted', () => {
+    createHyperFormulaSheet({ hyperformula: hf, rows: [{ a: 1 }], fields: ['a'] })
+    expect(hf.setCellContents).toHaveBeenCalledWith(
+      { sheet: 0, row: 0, col: 0 },
+      1,
+    )
+  })
+
+  it('handles an empty rows array without touching the engine', () => {
+    const sheet = createHyperFormulaSheet({
+      hyperformula: hf,
+      rows: [],
+      fields: ['a', 'b'],
+    })
+    expect(hf.setCellContents).not.toHaveBeenCalled()
+    expect(sheet.computed).toEqual([])
+    expect(sheet.raw).toEqual([])
+  })
+
+  it('cross-row formula references resolve through the engine', () => {
+    const rows = [
+      { a: 5 },
+      { a: 7 },
+      { a: '=A1+A2' },
+    ]
+    const sheet = createHyperFormulaSheet({
+      hyperformula: hf,
+      rows,
+      fields: ['a'],
+    })
+    expect(sheet.computed[2]!.a).toBe(12)
+  })
+
+  it('destroy() tears down the underlying engine', () => {
+    const sheet = createHyperFormulaSheet({
+      hyperformula: hf,
+      rows: [{ a: 1 }],
+      fields: ['a'],
+    })
+    sheet.destroy()
+    expect(hf.destroy).toHaveBeenCalledTimes(1)
+  })
+
+  it('update() returns fresh array instances each call (no shared mutation)', () => {
+    const rows = [{ a: 1, b: 1 }]
+    const sheet = createHyperFormulaSheet({
+      hyperformula: hf,
+      rows,
+      fields: ['a', 'b'],
+    })
+    const first = sheet.update(0, 'a', 2)
+    const second = sheet.update(0, 'b', 3)
+    expect(first.computed).not.toBe(second.computed)
+    expect(second.computed[0]).toEqual({ a: 2, b: 3 })
+  })
+})

package/src/hyperformula-adapter.ts

@@ -0,0 +1,124 @@
+/**
+ * HyperFormula adapter — Excel-class formula evaluation for SvGrid.
+ *
+ * `hyperformula` is an OPTIONAL peer dependency. Consumers who want
+ * full Excel-compatible formulas install it themselves:
+ *
+ * ```bash
+ *   pnpm add hyperformula
+ * ```
+ *
+ * The adapter wraps an HF instance around the grid's flat-row data:
+ *
+ *   - Treats each `data[]` row as a spreadsheet row
+ *   - Each registered field maps to a spreadsheet column
+ *   - Values that start with `=` are evaluated by HF
+ *   - The adapter returns the computed rows ready to render
+ *   - On edit, call `update(rowIdx, field, value)` and the adapter
+ *     re-evaluates only the cells HF tells it are dirty
+ *
+ * Why not bundle HF: it's ~1MB minified and 99% of grids never need it.
+ * Keeping it peer-optional means tiny default bundle + heavy-formula
+ * users get the ~400 functions (VLOOKUP, INDIRECT, IFS, XLOOKUP, full
+ * date/time/financial libraries) on demand.
+ */
+
+/** Minimal HF type surface this adapter uses. Mirrored here (rather
+ *  than importing) so consumers without `hyperformula` installed still
+ *  type-check. */
+export type HyperFormulaInstance = {
+  setCellContents(
+    cell: { sheet: number; row: number; col: number },
+    contents: unknown,
+  ): Array<{ address: { sheet: number; row: number; col: number }; newValue: unknown }>
+  getCellValue(cell: { sheet: number; row: number; col: number }): unknown
+  destroy(): void
+  rebuildAndRecalculate(): void
+}
+
+export type HyperFormulaSheetConfig<T extends Record<string, unknown>> = {
+  /** The HF instance the consumer constructed (so they pick the
+   *  license key + options). */
+  hyperformula: HyperFormulaInstance
+  /** Sheet index inside the HF instance. Default 0. */
+  sheetId?: number
+  /** Source rows. Cell values starting with `=` are evaluated. */
+  rows: T[]
+  /** Ordered list of fields to expose to the formula engine. The
+   *  order determines the HF column index, which is how A1-style
+   *  references resolve. */
+  fields: ReadonlyArray<keyof T & string>
+}
+
+export type HyperFormulaSheet<T extends Record<string, unknown>> = {
+  /** Rows with every `=...` formula replaced by its evaluated value.
+   *  Use this in a custom cell renderer to DISPLAY the result. */
+  computed: T[]
+  /** Rows with formulas kept as their raw `=SUM(...)` strings.
+   *  Pass this as `<SvGrid data={...}>` so the inline editor lets the
+   *  user edit the formula text itself, not the evaluated value. */
+  raw: T[]
+  /** Call when a cell edit lands. Returns the new computed + raw
+   *  snapshots so the consumer can reassign both. */
+  update(rowIndex: number, field: keyof T & string, value: unknown): {
+    computed: T[]
+    raw: T[]
+  }
+  /** Tear the adapter + the HF instance down (releases memory). */
+  destroy(): void
+}
+
+/** Build a live spreadsheet adapter around a HyperFormula instance.
+ *  Returns computed rows + an `update()` hook to push edits back into
+ *  the engine. */
+export function createHyperFormulaSheet<T extends Record<string, unknown>>(
+  config: HyperFormulaSheetConfig<T>,
+): HyperFormulaSheet<T> {
+  const { hyperformula: hf, rows, fields } = config
+  const sheetId = config.sheetId ?? 0
+  const colByField = new Map<string, number>()
+  fields.forEach((f, i) => colByField.set(f as string, i))
+
+  // 1. Seed HF with every cell. HF expects raw strings for formulas
+  //    (`'=A1+B1'`) and primitives for everything else.
+  for (let r = 0; r < rows.length; r += 1) {
+    const row = rows[r]!
+    for (let c = 0; c < fields.length; c += 1) {
+      const field = fields[c]! as string
+      hf.setCellContents({ sheet: sheetId, row: r, col: c }, row[field as keyof T])
+    }
+  }
+
+  /** Pull computed values out of HF into a fresh row array. Preserves
+   *  any non-formula fields (i.e. those not in `fields`) untouched. */
+  function snapshot(): T[] {
+    const out: T[] = new Array(rows.length)
+    for (let r = 0; r < rows.length; r += 1) {
+      const next: Record<string, unknown> = { ...rows[r]! }
+      for (let c = 0; c < fields.length; c += 1) {
+        const field = fields[c]! as string
+        const v = hf.getCellValue({ sheet: sheetId, row: r, col: c })
+        next[field] = v
+      }
+      out[r] = next as T
+    }
+    return out
+  }
+
+  function rawSnapshot(): T[] {
+    return rows.map((r) => ({ ...r }))
+  }
+  return {
+    computed: snapshot(),
+    raw: rawSnapshot(),
+    update(rowIndex, field, value) {
+      const col = colByField.get(field as string)
+      if (col !== undefined) {
+        hf.setCellContents({ sheet: sheetId, row: rowIndex, col }, value)
+      }
+      rows[rowIndex] = { ...rows[rowIndex]!, [field]: value } as T
+      return { computed: snapshot(), raw: rawSnapshot() }
+    },
+    destroy() { hf.destroy() },
+  }
+}