@svgrid/grid 1.0.2 → 1.1.1

package/src/features.ts

@@ -0,0 +1,128 @@
+// features handlers extracted from the controller. Imperative event handlers
+// reading/writing controller state via the `ctx` handle; the reactive core
+// ($state/$derived/$effect) stays in the controller.
+import {
+    applyExcelFilter,
+    normalizeForFilter,
+    createColumnVirtualizer,
+    createCoreRowModel,
+    createExpandedRowModel,
+    createFilteredRowModel,
+    createGroupedRowModel,
+    createSvelteVirtualizer,
+    createSortedRowModel,
+    createSvGrid,
+    getGridCellDomId,
+    sortFns,
+    tableFeatures,
+    rowSortingFeature,
+    columnFilteringFeature,
+    columnGroupingFeature,
+    type CellEditorOption,
+    type Column,
+    type ColumnDef,
+    type Row,
+    type RowData,
+    type TableFeatures,
+  } from "./index";
+import "./sv-grid-scrollbar";
+import {
+    computeColumnStat,
+    formatsNeedingStats,
+    type ColumnStat,
+  } from "./conditional-formatting";
+import SvGridDropdown from "./SvGridDropdown.svelte";
+import type {
+    Props,
+    SelectionRange,
+    CellEditState,
+    FilterOperator,
+    MenuPosition,
+  } from "./SvGrid.types";
+import {
+    rawToNumber,
+  } from "./SvGrid.helpers";
+import {
+    createScrollSync,
+  } from "./scroll-sync";
+import {
+    createKeyboard,
+  } from "./keyboard-handlers";
+import {
+    createSummaries,
+  } from "./summaries";
+import {
+    createMenus,
+  } from "./menus";
+import {
+    createCellRender,
+  } from "./cell-render";
+import {
+    createEditing,
+  } from "./editing";
+import {
+    createSelection,
+  } from "./selection";
+import {
+    createColumns,
+  } from "./columns";
+import {
+    createGridApi,
+  } from "./build-api";
+import {
+    createClipboard,
+  } from "./clipboard";
+import {
+    filterOperatorOptions,
+    fallbackOperatorOption,
+    TEXT_OPERATORS,
+    NUMBER_OPERATORS,
+    DATE_OPERATORS,
+    CHECKBOX_OPERATORS,
+    operatorOption,
+    operatorsForColumn,
+    defaultOperatorFor,
+    operatorLabelFor,
+  } from "./filter-operators";
+import {
+    type FacetBucket,
+    isBucketableColumn,
+    buildBuckets,
+    isInBucket,
+  } from "./facet-buckets";
+import {
+    getColumnBaseValue,
+    isGroupRow,
+    toolPanelHeaderLabel,
+    formatSummaryNumeric,
+    getColumnAlign,
+    getPinnedCellValue,
+    getColumnAccessorValue,
+    columnDefMatchesId,
+  } from "./cell-values";
+
+export function createFeatures<
+  TFeatures extends TableFeatures = TableFeatures,
+  TData extends RowData = RowData,
+>(ctx: any) {
+  // Merge the consumer's `features` set with whatever the boolean shortcuts
+  // imply. A shortcut set to `true` injects its feature; set to `false` it
+  // removes it (so `sortable={false}` wins even if `rowSortingFeature` was
+  // passed in `features`); left undefined it defers to `features`.
+  function resolveEffectiveFeatures(): TableFeatures {
+    const merged: Record<string, unknown> = { ...(ctx.props.features ?? {}) };
+    if (ctx.props.sortable === true) merged.rowSortingFeature = rowSortingFeature;
+    else if (ctx.props.sortable === false) delete merged.rowSortingFeature;
+    if (ctx.props.filterable === true)
+      merged.columnFilteringFeature = columnFilteringFeature;
+    else if (ctx.props.filterable === false) delete merged.columnFilteringFeature;
+    if (ctx.props.groupable === true)
+      merged.columnGroupingFeature = columnGroupingFeature;
+    else if (ctx.props.groupable === false) delete merged.columnGroupingFeature;
+    return tableFeatures(merged);
+  }
+
+  return {
+    resolveEffectiveFeatures,
+  };
+}

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 })
+  })
+})