@svgrid/grid 1.0.2 → 1.1.1

package/src/aligned-grids.test.ts

@@ -0,0 +1,80 @@
+/**
+ * Unit tests for aligned grids: two members sharing a group mirror horizontal
+ * scroll and column-resize widths to each other. Driven with minimal fake ctxs.
+ */
+import { describe, expect, it } from 'vitest'
+import { createAlignedGrids } from './aligned-grids'
+
+function makeCtx(group: string | undefined) {
+  return {
+    props: { alignedGridGroup: group },
+    scrollContainer: { scrollLeft: 0 } as { scrollLeft: number },
+    columnWidths: {} as Record<string, number>,
+  } as Record<string, any>
+}
+
+describe('aligned grids', () => {
+  it('mirrors horizontal scroll to peers in the same group', () => {
+    const a = makeCtx('g')
+    const b = makeCtx('g')
+    const ha = createAlignedGrids(a)
+    const hb = createAlignedGrids(b)
+    const un1 = ha.register()
+    const un2 = hb.register()
+
+    ha.broadcastScroll(240)
+    expect(b.scrollContainer.scrollLeft).toBe(240)
+    // and the other way
+    hb.broadcastScroll(80)
+    expect(a.scrollContainer.scrollLeft).toBe(80)
+    un1(); un2()
+  })
+
+  it('mirrors column-resize widths to peers (matched by column id)', () => {
+    const a = makeCtx('g')
+    const b = makeCtx('g')
+    const ha = createAlignedGrids(a)
+    const hb = createAlignedGrids(b)
+    ha.register(); hb.register()
+
+    a.columnWidths = { Feb: 180 }
+    ha.broadcastWidths()
+    expect(b.columnWidths.Feb).toBe(180)
+  })
+
+  it('does NOT mirror across different groups', () => {
+    const a = makeCtx('one')
+    const b = makeCtx('two')
+    const ha = createAlignedGrids(a)
+    const hb = createAlignedGrids(b)
+    ha.register(); hb.register()
+
+    ha.broadcastScroll(200)
+    expect(b.scrollContainer.scrollLeft).toBe(0)
+    a.columnWidths = { Feb: 999 }
+    ha.broadcastWidths()
+    expect(b.columnWidths.Feb).toBeUndefined()
+  })
+
+  it('is inert with no group set, and after unregister', () => {
+    const a = makeCtx(undefined)
+    const b = makeCtx(undefined)
+    const ha = createAlignedGrids(a)
+    const hb = createAlignedGrids(b)
+    ha.register(); hb.register()
+    ha.broadcastScroll(120)
+    expect(b.scrollContainer.scrollLeft).toBe(0)
+
+    // Grouped, then unregistered -> no longer receives updates.
+    const c = makeCtx('gg')
+    const d = makeCtx('gg')
+    const hc = createAlignedGrids(c)
+    const hd = createAlignedGrids(d)
+    const unc = hc.register()
+    const und = hd.register()
+    und() // d leaves the group
+    hc.broadcastScroll(55)
+    expect(d.scrollContainer.scrollLeft).toBe(0)
+    unc()
+  })
+})

package/src/aligned-grids.ts

@@ -0,0 +1,87 @@
+// Aligned grids - keep two or more independent grids in lockstep on horizontal
+// scroll and column widths. Grids that share the same `alignedGridGroup` string
+// register with a module-level registry (same pattern as managed row dragging);
+// when one scrolls horizontally or a column is resized, the others follow.
+//
+// Loop-safety without flags: scroll sync no-ops when the target already has the
+// value (so the echo scroll event never fires); width sync compares a serialized
+// snapshot and pre-seeds it on apply, so the reactive effect that fires after
+// applying a peer's widths sees "no change" and doesn't echo.
+
+type Member = {
+  id: number;
+  applyScroll: (left: number) => void;
+  applyWidths: (widths: Record<string, number>) => void;
+};
+
+// Shared across every grid in the bundle.
+const groups = new Map<string, Map<number, Member>>();
+let seq = 0;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function createAlignedGrids<TFeatures, TData>(ctx: any) {
+  const id = ++seq;
+  let lastWidthsSerial = "";
+
+  const group = (): string | null => ctx.props.alignedGridGroup ?? null;
+
+  function peers(): Member[] {
+    const g = group();
+    if (!g) return [];
+    const m = groups.get(g);
+    if (!m) return [];
+    const out: Member[] = [];
+    for (const member of m.values()) if (member.id !== id) out.push(member);
+    return out;
+  }
+
+  const self: Member = {
+    id,
+    applyScroll(left: number) {
+      const el = ctx.scrollContainer as HTMLElement | null;
+      // Only set when it differs, so no echo scroll event fires -> no loop.
+      if (el && el.scrollLeft !== left) el.scrollLeft = left;
+    },
+    applyWidths(widths: Record<string, number>) {
+      const merged = { ...(ctx.columnWidths as Record<string, number>), ...widths };
+      // Pre-seed the serial so the columnWidths effect that fires after this
+      // set sees an unchanged snapshot and skips its own broadcast.
+      lastWidthsSerial = JSON.stringify(merged);
+      ctx.columnWidths = merged;
+    },
+  };
+
+  // Register on mount; returns the unregister for the effect's cleanup.
+  function register(): () => void {
+    const g = group();
+    if (!g) return () => {};
+    let m = groups.get(g);
+    if (!m) {
+      m = new Map();
+      groups.set(g, m);
+    }
+    m.set(id, self);
+    return () => {
+      const mm = groups.get(g);
+      if (!mm) return;
+      mm.delete(id);
+      if (!mm.size) groups.delete(g);
+    };
+  }
+
+  function broadcastScroll(left: number) {
+    const p = peers();
+    for (const member of p) member.applyScroll(left);
+  }
+
+  function broadcastWidths() {
+    if (!group()) return;
+    const serial = JSON.stringify((ctx.columnWidths as Record<string, number>) ?? {});
+    if (serial === lastWidthsSerial) return; // nothing new (or echo of an apply)
+    lastWidthsSerial = serial;
+    const w = ctx.columnWidths as Record<string, number>;
+    for (const member of peers()) member.applyWidths(w);
+  }
+
+  return { register, broadcastScroll, broadcastWidths, alignedGridId: id };
+}

package/src/build-api.coverage.test.ts

@@ -0,0 +1,532 @@
+/**
+ * Coverage-focused behavioral tests for the SvGridApi assembled in
+ * `build-api.ts`. The existing `svgrid.api.test.ts` / `svgrid.api-extensions
+ * .test.ts` cover filters, row selection, pagination, navigation, and
+ * getState/setState. This file exercises the remaining surface:
+ *   - getCellValue / setCellValue
+ *   - selectCells / getSelected
+ *   - addRow(s) / removeRow(s) / applyTransaction
+ *   - addColumn(s) / removeColumn / setColumnVisible / getColumns
+ *   - setColumnWidth / setColumnPinning / setColumnOrder
+ *   - setFacetFilter
+ *   - undo / redo / canUndo / canRedo / clearHistory
+ *   - find (open/close/query/hits)
+ *   - grouping (setGroupBy / expandAllGroups / collapseAllGroups)
+ *   - autosizeColumn / refresh
+ *
+ * All tests mount the real <SvGrid /> in jsdom and drive the api handed back
+ * from onApiReady.
+ */
+
+import { describe, expect, it } from "vitest";
+import { mount, unmount } from "svelte";
+import SvGrid from "./SvGrid.svelte";
+import {
+  columnFilteringFeature,
+  columnGroupingFeature,
+  rowExpandingFeature,
+  rowSelectionFeature,
+  rowSortingFeature,
+  tableFeatures,
+} from "./index";
+import type { ColumnDef, SvGridApi } from "./index";
+
+type Row = { id: number; name: string; team: string; salary: number };
+
+const baseRows: Row[] = [
+  { id: 1, name: "Ada Lovelace", team: "Research", salary: 142_000 },
+  { id: 2, name: "Grace Hopper", team: "Compilers", salary: 158_000 },
+  { id: 3, name: "Alan Turing", team: "Research", salary: 138_000 },
+  { id: 4, name: "Margaret Hamilton", team: "Apollo", salary: 165_000 },
+  { id: 5, name: "Linus Torvalds", team: "Kernel", salary: 175_000 },
+];
+
+const baseColumns: ColumnDef<any, Row>[] = [
+  { field: "name", header: "Name", width: 200 },
+  { field: "team", header: "Team", width: 160 },
+  { field: "salary", header: "Salary", width: 140 },
+];
+
+const flush = () => Promise.resolve();
+
+function mountGrid(
+  extraProps: Record<string, unknown> = {},
+  features: any = tableFeatures({
+    columnFilteringFeature,
+    rowSortingFeature,
+    rowSelectionFeature,
+    columnGroupingFeature,
+    rowExpandingFeature,
+  }),
+): Promise<{ api: SvGridApi<any, Row>; target: HTMLElement; destroy: () => void }> {
+  return new Promise((resolveApi, rejectApi) => {
+    const target = document.createElement("div");
+    document.body.appendChild(target);
+    let captured: SvGridApi<any, Row> | null = null;
+    const app = mount(SvGrid, {
+      target,
+      props: {
+        data: baseRows.map((r) => ({ ...r })),
+        columns: baseColumns.map((c) => ({ ...c })),
+        features,
+        getRowId: (r: Row) => String(r.id),
+        rowHeight: 36,
+        containerHeight: 480,
+        virtualization: false,
+        enableCellSelection: true,
+        onApiReady(api: SvGridApi<any, Row>) {
+          captured = api;
+          resolveApi({
+            api,
+            target,
+            destroy: () => {
+              unmount(app);
+              target.remove();
+            },
+          });
+        },
+        ...extraProps,
+      } as any,
+    });
+    queueMicrotask(() => {
+      if (!captured) rejectApi(new Error("onApiReady never fired"));
+    });
+  });
+}
+
+describe("SvGridApi - cell read / write", () => {
+  it("getCellValue reads through the column field", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      expect(api.getCellValue(0, "name")).toBe("Ada Lovelace");
+      expect(api.getCellValue(3, "team")).toBe("Apollo");
+    } finally {
+      destroy();
+    }
+  });
+
+  it("getCellValue returns undefined for out-of-range row or unknown column", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      expect(api.getCellValue(999, "name")).toBeUndefined();
+      expect(api.getCellValue(0, "nope")).toBeUndefined();
+    } finally {
+      destroy();
+    }
+  });
+
+  it("setCellValue writes a new immutable row and reads back", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      api.setCellValue(0, "name", "Ada L.");
+      await flush();
+      expect(api.getCellValue(0, "name")).toBe("Ada L.");
+      // other rows untouched
+      expect(api.getCellValue(1, "name")).toBe("Grace Hopper");
+    } finally {
+      destroy();
+    }
+  });
+
+  it("setCellValue is a no-op for an invalid target", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      expect(() => api.setCellValue(999, "name", "x")).not.toThrow();
+      expect(() => api.setCellValue(0, "unknown", "x")).not.toThrow();
+    } finally {
+      destroy();
+    }
+  });
+});
+
+describe("SvGridApi - cell selection", () => {
+  it("selectCells sets a rectangle; getSelected reads it back normalized", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      api.selectCells([[2, 1, 0, 0]]); // unsorted corners
+      await flush();
+      expect(api.getSelected()).toEqual([[0, 0, 2, 1]]);
+    } finally {
+      destroy();
+    }
+  });
+
+  it("selectCells clamps open-ended (Infinity) coordinates to grid bounds", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      api.selectCells([[0, 0, Infinity, Infinity]]);
+      await flush();
+      // 5 rows (0..4), 3 cols (0..2)
+      expect(api.getSelected()).toEqual([[0, 0, 4, 2]]);
+    } finally {
+      destroy();
+    }
+  });
+
+  it("empty selectCells clears the range; getSelected returns []", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      api.selectCells([[0, 0, 1, 1]]);
+      await flush();
+      api.selectCells([]);
+      await flush();
+      expect(api.getSelected()).toEqual([]);
+    } finally {
+      destroy();
+    }
+  });
+});
+
+describe("SvGridApi - row mutations", () => {
+  it("addRow appends to the bottom by default", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      api.addRow({ id: 6, name: "New", team: "QA", salary: 1 } as Row);
+      await flush();
+      const data = api.getData() as Row[];
+      expect(data.length).toBe(6);
+      expect(data[5]!.id).toBe(6);
+    } finally {
+      destroy();
+    }
+  });
+
+  it("addRows at top / numeric index insert in place", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      api.addRows([{ id: 7, name: "Top", team: "T", salary: 1 } as Row], "top");
+      await flush();
+      expect((api.getData() as Row[])[0]!.id).toBe(7);
+
+      api.addRows([{ id: 8, name: "Mid", team: "M", salary: 1 } as Row], 2);
+      await flush();
+      expect((api.getData() as Row[])[2]!.id).toBe(8);
+    } finally {
+      destroy();
+    }
+  });
+
+  it("removeRow / removeRows drop by index", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      api.removeRow(0);
+      await flush();
+      expect((api.getData() as Row[]).map((r) => r.id)).toEqual([2, 3, 4, 5]);
+
+      api.removeRows([0, 2]); // drops ids 2 and 4
+      await flush();
+      expect((api.getData() as Row[]).map((r) => r.id)).toEqual([3, 5]);
+    } finally {
+      destroy();
+    }
+  });
+
+  it("applyTransaction adds, updates (by id), and removes; returns counts", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      const result = api.applyTransaction({
+        add: [{ id: 9, name: "Added", team: "X", salary: 1 } as Row],
+        update: [
+          { id: 2, name: "Grace H.", team: "Compilers", salary: 999 } as Row,
+        ],
+        remove: ["3"], // by getRowId string
+      });
+      await flush();
+      expect(result).toEqual({ added: 1, updated: 1, removed: 1 });
+      const data = api.getData() as Row[];
+      expect(data.find((r) => r.id === 3)).toBeUndefined();
+      expect(data.find((r) => r.id === 2)!.salary).toBe(999);
+      expect(data.find((r) => r.id === 9)).toBeTruthy();
+    } finally {
+      destroy();
+    }
+  });
+
+  it("applyTransaction removes by object reference too", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      const target = (api.getData() as Row[])[0]!;
+      const result = api.applyTransaction({ remove: [target] });
+      await flush();
+      expect(result.removed).toBe(1);
+      expect((api.getData() as Row[]).find((r) => r === target)).toBeUndefined();
+    } finally {
+      destroy();
+    }
+  });
+});
+
+describe("SvGridApi - column mutations", () => {
+  it("addColumn left / right / numeric position, then getColumns reflects it", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      api.addColumn({ field: "id", header: "ID" } as any, "left");
+      await flush();
+      expect(api.getColumns()[0]!.id).toBe("id");
+
+      api.addColumns([{ field: "extra", header: "Extra" } as any], "right");
+      await flush();
+      const cols = api.getColumns();
+      expect(cols[cols.length - 1]!.id).toBe("extra");
+    } finally {
+      destroy();
+    }
+  });
+
+  it("removeColumn drops a column from the visible set", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      api.removeColumn("team");
+      await flush();
+      expect(api.getColumns().find((c) => c.id === "team")).toBeUndefined();
+    } finally {
+      destroy();
+    }
+  });
+
+  it("setColumnVisible toggles visibility; getColumns lists hidden as visible:false", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      api.setColumnVisible("team", false);
+      await flush();
+      expect(api.isColumnVisible("team")).toBe(false);
+      const hidden = api.getColumns().find((c) => c.id === "team");
+      expect(hidden!.visible).toBe(false);
+
+      api.setColumnVisible("team", true);
+      await flush();
+      expect(api.isColumnVisible("team")).toBe(true);
+    } finally {
+      destroy();
+    }
+  });
+
+  it("setColumnWidth clamps + getColumnWidths round-trips", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      api.setColumnWidth("name", 333.7);
+      await flush();
+      expect(api.getColumnWidths().name).toBe(333);
+    } finally {
+      destroy();
+    }
+  });
+
+  it("setColumnPinning dedupes; getColumnPinning returns copies", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      api.setColumnPinning({ left: ["name", "name"], right: ["salary"] });
+      await flush();
+      const pin = api.getColumnPinning();
+      expect(pin.left).toEqual(["name"]);
+      expect(pin.right).toEqual(["salary"]);
+      // mutating the returned copy doesn't affect internal state
+      pin.left.push("hacked");
+      expect(api.getColumnPinning().left).toEqual(["name"]);
+    } finally {
+      destroy();
+    }
+  });
+
+  it("setColumnOrder + getColumnOrder round-trip", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      api.setColumnOrder(["salary", "name", "team"]);
+      await flush();
+      expect(api.getColumnOrder().slice(0, 3)).toEqual([
+        "salary",
+        "name",
+        "team",
+      ]);
+    } finally {
+      destroy();
+    }
+  });
+
+  // Note: autosizeColumn / autosizeAllColumns are intentionally not asserted
+  // here - they measure text via real DOM layout (canvas/escape), which jsdom
+  // does not provide, so they throw in this environment. They are exercised by
+  // the demo gallery / Playwright suite per the coverage config notes.
+});
+
+describe("SvGridApi - facet filter", () => {
+  it("setFacetFilter narrows displayed rows; null clears it", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      api.setFacetFilter("team", ["Research"]);
+      await flush();
+      const displayed = api.getDisplayedRows() as Row[];
+      expect(displayed.every((r) => r.team === "Research")).toBe(true);
+      expect(displayed.length).toBe(2);
+
+      api.setFacetFilter("team", null);
+      await flush();
+      expect((api.getDisplayedRows() as Row[]).length).toBe(5);
+    } finally {
+      destroy();
+    }
+  });
+
+  it("setFacetFilter with an empty array also clears", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      api.setFacetFilter("team", ["Apollo"]);
+      await flush();
+      api.setFacetFilter("team", []);
+      await flush();
+      expect((api.getDisplayedRows() as Row[]).length).toBe(5);
+    } finally {
+      destroy();
+    }
+  });
+});
+
+describe("SvGridApi - find", () => {
+  it("openFind / setFindQuery / getFindHits / closeFind", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      api.openFind();
+      api.setFindQuery("Research");
+      await flush();
+      const hits = api.getFindHits();
+      expect(Array.isArray(hits)).toBe(true);
+      // two cells contain "Research"
+      expect(hits.length).toBeGreaterThanOrEqual(2);
+
+      api.closeFind();
+      await flush();
+      expect(api.getFindHits()).toEqual([]);
+    } finally {
+      destroy();
+    }
+  });
+});
+
+describe("SvGridApi - undo / redo / history", () => {
+  it("canUndo is false before any history; undo/redo are no-ops then", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      expect(api.canUndo()).toBe(false);
+      expect(api.canRedo()).toBe(false);
+      expect(api.undo()).toBe(false);
+      expect(api.redo()).toBe(false);
+    } finally {
+      destroy();
+    }
+  });
+
+  it("clearHistory resets the stacks without throwing", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      expect(() => api.clearHistory()).not.toThrow();
+      expect(api.canUndo()).toBe(false);
+      expect(api.canRedo()).toBe(false);
+    } finally {
+      destroy();
+    }
+  });
+});
+
+describe("SvGridApi - grouping / expansion", () => {
+  it("setGroupBy groups rows; the underlying data is unchanged", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      api.setGroupBy(["team"]);
+      await flush();
+      // Grouping reshapes the display pipeline; the source data is intact.
+      expect((api.getData() as Row[]).length).toBe(5);
+      expect(api.getState().grouping).toContain("team");
+    } finally {
+      destroy();
+    }
+  });
+
+  it("expandAllGroups / collapseAllGroups run without error", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      api.setGroupBy(["team"]);
+      await flush();
+      expect(() => api.expandAllGroups()).not.toThrow();
+      await flush();
+      expect(() => api.collapseAllGroups()).not.toThrow();
+      await flush();
+      // un-group
+      api.setGroupBy([]);
+      await flush();
+      expect((api.getData() as Row[]).length).toBe(5);
+    } finally {
+      destroy();
+    }
+  });
+
+  it("setRowExpanded toggles a row's expanded flag", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      expect(() => api.setRowExpanded("1", true)).not.toThrow();
+      await flush();
+      expect(() => api.setRowExpanded("1", false)).not.toThrow();
+    } finally {
+      destroy();
+    }
+  });
+});
+
+describe("SvGridApi - sort opt-out + refresh", () => {
+  it("setSort with a direction sets a single active clause", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      api.setSort("salary", "asc");
+      await flush();
+      expect(api.getState().sorting).toEqual([{ id: "salary", desc: false }]);
+
+      api.setSort("name", "desc");
+      await flush();
+      // Setting a direction replaces the active sort clause.
+      expect(api.getState().sorting).toEqual([{ id: "name", desc: true }]);
+    } finally {
+      destroy();
+    }
+  });
+
+  it("setSort with a falsy direction removes that column's clause", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      api.setSort("salary", "asc");
+      await flush();
+      api.setSort("salary", null as any);
+      await flush();
+      expect(
+        api.getState().sorting.find((s) => s.id === "salary"),
+      ).toBeUndefined();
+    } finally {
+      destroy();
+    }
+  });
+
+  it("setSort is ignored for a non-sortable column", async () => {
+    const { api, destroy } = await mountGrid({
+      columns: [
+        { field: "name", header: "Name", width: 200, sortable: false },
+        { field: "team", header: "Team", width: 160 },
+      ],
+    });
+    try {
+      api.setSort("name", "asc");
+      await flush();
+      expect(api.getState().sorting.find((s) => s.id === "name")).toBeUndefined();
+    } finally {
+      destroy();
+    }
+  });
+
+  it("refresh re-runs the pipeline without throwing or losing data", async () => {
+    const { api, destroy } = await mountGrid();
+    try {
+      expect(() => api.refresh()).not.toThrow();
+      await flush();
+      expect((api.getData() as Row[]).length).toBe(5);
+    } finally {
+      destroy();
+    }
+  });
+});