gbs-add-block 1.2.7 → 1.2.8

package/README.md

@@ -1,4 +1,4 @@
-# GBS Building Blocks 2.0 (v1.2.7)
+# GBS Building Blocks 2.0 (v1.2.8)
 
 Latest and upgraded version of GBS building blocks with headless UI and removed dependencies.
 
@@ -6,9 +6,9 @@ Latest and upgraded version of GBS building blocks with headless UI and removed
 
 For detailed documentation on usage and props, Please visit: [Building Block Documentation v2.0](https://gramprokit.vercel.app)
 
-## What's New 🎉 (Ver 1.2.7)
+## What's New 🎉 (Ver 1.2.8)
 
-- UI Update (Canditate update for next major change 2.0.0)
+- Canditate update for next major change 2.0.0
 
 ## Authors
 

package/index.cjs

@@ -82,7 +82,7 @@ const copyComponent = async (component, destPath) => {
         component === "Grid"
           ? "This Version of Grid will be deprecated soon. Please Install The New Data Grid Component"
           : ""
-      }`
+      }`,
     );
   } catch (error) {
     console.error(`Error installing component ${component}:`, error.message);
@@ -97,12 +97,12 @@ const installComponentWithDependencies = async (component, destPath) => {
 
   // Check which components need to be installed
   const pendingInstalls = Array.from(componentsToInstall).filter(
-    (comp) => !checkComponentExists(comp, destPath)
+    (comp) => !checkComponentExists(comp, destPath),
   );
 
   if (pendingInstalls.length === 0) {
     console.log(
-      `✓ ${component} and all its dependencies are already installed.`
+      `✓ ${component} and all its dependencies are already installed.`,
     );
     return;
   }
@@ -134,12 +134,12 @@ const installMultipleComponents = async (components, destPath) => {
 
   // Filter out already installed components
   const pendingInstalls = Array.from(allComponentsToInstall).filter(
-    (comp) => !checkComponentExists(comp, destPath)
+    (comp) => !checkComponentExists(comp, destPath),
   );
 
   if (pendingInstalls.length === 0) {
     console.log(
-      "✓ All selected components and their dependencies are already installed."
+      "✓ All selected components and their dependencies are already installed.",
     );
     return;
   }
@@ -182,7 +182,7 @@ const interactiveComponentSelector = async () => {
       console.clear();
       console.log("🚀 Component Installer - Interactive Mode");
       console.log(
-        "Use ↑/↓ arrow keys to navigate, SPACE to select/deselect, ENTER to install\n"
+        "Use ↑/↓ arrow keys to navigate, SPACE to select/deselect, ENTER to install\n",
       );
 
       CONFIG.components.forEach((component, index) => {
@@ -216,7 +216,7 @@ const interactiveComponentSelector = async () => {
         case "\u001b[B": // Down arrow
           currentIndex = Math.min(
             CONFIG.components.length - 1,
-            currentIndex + 1
+            currentIndex + 1,
           );
           renderMenu();
           break;
@@ -266,7 +266,7 @@ const parseMultipleComponents = (componentString) => {
 
 const validateComponents = (components) => {
   const invalidComponents = components.filter(
-    (comp) => !CONFIG.components.includes(comp)
+    (comp) => !CONFIG.components.includes(comp),
   );
   if (invalidComponents.length > 0) {
     console.error(`Invalid components: ${invalidComponents.join(", ")}`);
@@ -338,7 +338,7 @@ const main = async () => {
 
   if (!argv.add) {
     console.error(
-      "Please specify a component to install using -a/--add, use -i/--interactive for interactive mode, or -l/--list to see available components"
+      "Please specify a component to install using -a/--add, use -i/--interactive for interactive mode, or -l/--list to see available components",
     );
     process.exit(1);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gbs-add-block",
-  "version": "1.2.7",
+  "version": "1.2.8",
   "description": "React Component Library",
   "type": "module",
   "files": [

package/source/components/datagridbeta/README.md

@@ -0,0 +1,232 @@
+# DataGrid
+
+A virtualized data grid for React 19 with no runtime dependencies besides React.
+Works in Vite/SPA apps and in the Next.js App Router.
+
+- **Fast by design:** rows and columns are virtualized; state lives in an
+  external store with per-row subscriptions, so selecting a row or moving focus
+  re-renders only the rows involved; column resizing rewrites CSS variables
+  without rendering; filtering and sorting run at low priority via
+  `useDeferredValue`.
+- **Features:** typed columns, multi-column sort, typed column filters, global
+  search, pagination, row selection (single, multiple, shift-range), column
+  resize / reorder (drag or menu) / pin / hide, inline editing with validation and
+  async saves, CSV / Excel / PDF export, clipboard copy, density, i18n, RTL, dark
+  mode, WAI-ARIA grid keyboard navigation.
+- **Client or server mode:** let the grid sort/filter/paginate, or receive a
+  query and fetch pages yourself.
+
+## Setup
+
+Import the stylesheet once (e.g. in your root CSS or layout):
+
+```css
+@import "../component-lib/data-grid/styles.css";
+```
+
+or from JS: `import "component-lib/data-grid/styles.css";`
+
+## Basic usage
+
+```tsx
+import { createColumnHelper, DataGrid } from "component-lib/data-grid";
+
+interface Employee { id: number; name: string; salary: number; startDate: string; active: boolean }
+
+const col = createColumnHelper<Employee>();
+
+// Define columns outside the component (or memoize them).
+const columns = [
+  col.field("id", { header: "ID", type: "number", width: 80, pin: "left" }),
+  col.field("name", { width: 200 }),
+  col.field("salary", { type: "number", format: (v) => `$${v.toLocaleString()}` }),
+  col.field("startDate", { type: "date" }),
+  col.field("active", { type: "boolean" }),
+];
+
+export function Employees({ data }: { data: Employee[] }) {
+  return <DataGrid data={data} columns={columns} getRowId="id" enableRowSelection height={600} />;
+}
+```
+
+`createColumnHelper` infers the value type for `cell`, `format`, `validate` and
+`sortFn`. Plain `ColumnDef<T>[]` objects work too.
+
+### Stable inputs
+
+The grid memoizes on the identity of `data`, `columns` and `getRowId`. Keep
+them stable: define columns at module level or with `useMemo`, and pass
+`getRowId` as a property name (`getRowId="id"`). With React Compiler enabled,
+inline values are memoized for you.
+
+## Columns
+
+| Option | Purpose |
+| --- | --- |
+| `field` / `accessor` / `id` | Where the value comes from. Display-only columns need just `id` and `cell`. |
+| `header`, `width`, `minWidth`, `maxWidth`, `align` | Presentation. |
+| `type` | `string` (default), `number`, `date`, `boolean`. Drives filter operators, sorting, alignment, editors and Excel cell types. |
+| `options` | `{ label, value }[]` for enum columns: "is any of" filter, select editor, label display. |
+| `format(value, row)` | Display text. Also used by search, CSV, PDF and copy. |
+| `cell(ctx)` | Custom renderer. Clicks on buttons/inputs inside cells don't trigger `onRowClick`. |
+| `pin`, `hidden` | Initial pin side / visibility. |
+| `sortable`, `filterable`, `resizable`, `reorderable`, `pinnable`, `hideable`, `searchable` | Per-column feature switches (default `true`). |
+| `sortFn`, `filterFn` | Custom comparison / matching. |
+| `editable`, `editor`, `validate` | Inline editing (below). |
+| `exportable`, `exportValue(row)` | Export control. |
+| `headerClassName`, `cellClassName` | Styling hooks. |
+
+## Server mode
+
+```tsx
+const [query, setQuery] = useState<GridQuery>(initialQuery);
+const { data, isFetching } = useQuery({ queryKey: ["orders", query], queryFn: () => fetchOrders(query) });
+
+<DataGrid
+  mode="server"
+  data={data?.rows ?? []}
+  rowCount={data?.total ?? 0}
+  loading={isFetching}
+  columns={columns}
+  initialState={initialQuery}
+  onQueryChange={setQuery}
+/>
+```
+
+`onQueryChange` receives `{ sorting, filters, globalFilter, pagination }`
+whenever one of them changes. Changing filters, search or sorting resets to the
+first page. The previous rows stay visible while `loading`.
+
+The framework-free core (`component-lib/data-grid/core`) exports `filterRows`,
+`sortRows` and `paginate`, so a Node or Next.js route handler can apply exactly
+the same semantics on the server.
+
+## State
+
+All grid state can be controlled or left internal:
+
+```ts
+interface GridState {
+  sorting; filters; globalFilter; pagination; rowSelection;
+  columnOrder; columnVisibility; columnSizing; columnPinning; density;
+}
+```
+
+- `initialState` seeds internal state.
+- `state` controls any subset of keys; the grid then calls `onStateChange(next, prev)`
+  instead of updating those keys itself.
+- Example: persist column layout with
+  `onStateChange={(s) => save(pick(s, ["columnOrder", "columnSizing", "columnPinning", "columnVisibility"]))}`.
+
+## Editing
+
+```ts
+col.field("salary", {
+  type: "number",
+  editable: (row) => !row.locked,
+  validate: (v) => (v < 0 ? "Must be positive" : null),
+});
+
+<DataGrid onCellEdit={async ({ rowId, columnId, value }) => { await save(rowId, columnId, value); }} />
+```
+
+Start editing with double-click, Enter or F2. Enter commits and moves down,
+Tab commits and moves right, and Escape cancels. The grid never mutates `data`:
+update it in `onCellEdit`. If `onCellEdit` returns a promise, the cell shows the
+pending value until it settles, and a rejection marks the cell invalid.
+Custom editors: `editor: (props) => <MyInput value={props.value} onChange={props.onChange} onBlur={() => props.commit()} />`.
+
+## Imperative API
+
+```tsx
+const api = useRef<GridApi<Employee>>(null);
+<DataGrid ref={api} ... />
+
+api.current?.setFilter("status", { operator: "in", value: ["active"] });
+api.current?.exportExcel({ scope: "selected", fileName: "people" });
+api.current?.focusCell(0, "name");
+```
+
+Methods include `toggleSort`, `setSorting`, `setFilter`, `clearFilters`,
+`setGlobalFilter`, `setPageIndex`, `setPageSize`, `toggleRowSelected`,
+`toggleAllRowsSelected`, `getSelectedRows`, `setColumnVisibility`,
+`setColumnWidth`, `pinColumn`, `moveColumn`, `resetColumns`, `scrollToRow`,
+`focusCell`, `startEditing`, `getRows`, `exportCsv`, `exportExcel`, `exportPdf`
+and `copyToClipboard`.
+
+## Export
+
+Export code is split into chunks loaded on first use.
+
+| Format | Notes |
+| --- | --- |
+| CSV | UTF-8 with BOM (opens correctly in Excel). Cells starting with `= + - @` are prefixed with `'` to prevent formula injection. |
+| Excel | Real `.xlsx`: typed numbers, booleans and dates, bold frozen header, auto-filter, column widths. Written without a library. |
+| PDF | Opens the browser print dialog with a print-formatted table; users choose "Save as PDF". Best for up to a few thousand rows. |
+
+Scopes: `filtered` (default), `all`, `selected`, `page`, or pass `rows`, e.g. a
+full result set fetched from the server.
+
+## Keyboard
+
+| Keys | Action |
+| --- | --- |
+| Arrows, Home/End, Ctrl+Home/End, PageUp/PageDown | Move between cells (header row included). |
+| Enter (header) | Sort; Shift+Enter adds to the sort. |
+| Alt+↓ or the Menu key (header) | Open the column menu. |
+| Enter / F2 | Edit the cell, or focus the widget inside a custom cell. |
+| Space | Toggle row selection (Shift for a range). |
+| Ctrl/Cmd+A | Select all rows. |
+| Ctrl/Cmd+C | Copy selected rows (TSV) or the active cell. |
+| Escape | Cancel editing / leave a widget inside a cell. |
+
+## Theming
+
+Styles live in `@layer components`, so Tailwind utilities passed via
+`classNames` / `className` win. Override the `--dg-*` variables for a theme:
+
+```css
+.dg-root { --dg-accent: #7c3aed; --dg-radius: 12px; --dg-font-size: 14px; }
+```
+
+Colors follow the page's `color-scheme`. A `.dark` or `[data-theme="dark"]`
+ancestor forces a scheme. State is exposed as attributes for styling:
+`data-selected`, `data-active`, `data-editing`, `data-pinned`, `data-density`,
+and `aria-sort` on header cells.
+
+Slots for `classNames`: `root`, `toolbar`, `viewport`, `header`, `headerCell`,
+`row`, `cell`, `pagination`.
+
+## Next.js
+
+Components carry `"use client"`; import `DataGrid` from a Server Component and
+pass serializable props (`data`, `initialState`). Column definitions contain
+functions, so define them in a client module. For server mode, fetch in a
+Server Component or Route Handler using `core` functions, and sync the query to
+the URL (e.g. with `nuqs`) through `state` + `onQueryChange`.
+
+## Known limits
+
+- Rows have a fixed height (per density or `rowHeight`); variable-height rows are not supported.
+- Updates from the grid's store render synchronously; heavy client-side filtering is
+  deferred with `useDeferredValue`, but a single filter pass over very large data
+  (1M+ rows) still runs on the main thread. For that scale, use server mode or a worker.
+- Row grouping, tree data and pivoting are not implemented.
+
+## Migrating from `component-lib/datagrid`
+
+| Old prop | New |
+| --- | --- |
+| `dataSource` (array) | `data` |
+| `dataSource` (URL string) | Fetch in your app; pass `data` (the grid no longer fetches). |
+| `lazy` + `pageSettings.totalCount` | `mode="server"` + `rowCount` |
+| `pageSettings.pageNumber` / `pageSize` | `initialState={{ pagination: { pageIndex: 0, pageSize } }}` |
+| `enableSearch`, `enableExcelExport`, `enablePdfExport` | `toolbar={{ search, export }}` |
+| `selectAll`, `onSelectRow` | `enableRowSelection`, `onStateChange` / `api.getSelectedRows()` |
+| `rowChange` / `onRowClick` | `onRowClick` |
+| `pageStatus` / `onPageChange`, `onFilterChange`, `onSearchChange` | `onQueryChange` |
+| `initialFilters`, `initialSearchParam` | `initialState={{ filters, globalFilter }}` |
+| `isFetching` | `loading` |
+| `column.headerText`, `column.template` | `header`, `cell` |
+| `grid*Class` props | `classNames` slots |
+| `ref.goToPage(n)` etc. | `ref.setPageIndex(n)` and the API above |

package/source/components/datagridbeta/__tests__/core.test.ts

@@ -0,0 +1,341 @@
+import { describe, expect, it, vi } from "vitest";
+import { computeLayout, getLayoutVars, moveColumn, resolveColumns } from "../core/columns";
+import { filterRows } from "../core/filtering";
+import { createGridEngine, type GridModel } from "../core/grid";
+import { buildRows, createRowIdGetter, paginate } from "../core/rows";
+import { sortRows, toggleSorting } from "../core/sorting";
+import { createInitialState, mergeState } from "../core/state";
+import type { ColumnDef, ColumnFilter, GridOptions, GridRow, SortItem } from "../core/types";
+import { createFormatters } from "../core/values";
+import { getColumnRange, getRowRange } from "../core/virtual";
+
+interface Person {
+  id: number;
+  name: string;
+  age: number | null;
+  city: string | null;
+  joined: string;
+  active: boolean;
+  status: "new" | "active" | "gone";
+}
+
+const people: Person[] = [
+  { id: 1, name: "Alice", age: 34, city: "Paris", joined: "2024-01-15", active: true, status: "active" },
+  { id: 2, name: "bob", age: null, city: "Berlin", joined: "2023-06-01", active: false, status: "new" },
+  { id: 3, name: "Carol", age: 28, city: null, joined: "2024-01-16", active: true, status: "gone" },
+  { id: 4, name: "Dave", age: 41, city: "Paris", joined: "2022-11-30", active: false, status: "active" },
+  { id: 5, name: "Item10", age: 28, city: "Rome", joined: "2024-03-01", active: true, status: "new" },
+  { id: 6, name: "Item2", age: 50, city: "Berlin", joined: "2021-07-07", active: true, status: "active" },
+];
+
+const defs: ColumnDef<Person>[] = [
+  { field: "id", type: "number" },
+  { field: "name" },
+  { field: "age", type: "number" },
+  { field: "city" },
+  { field: "joined", type: "date" },
+  { field: "active", type: "boolean" },
+  {
+    field: "status",
+    options: [
+      { label: "New", value: "new" },
+      { label: "Active", value: "active" },
+      { label: "Gone", value: "gone" },
+    ],
+  },
+];
+
+const columns = resolveColumns(defs);
+const formatters = createFormatters("en-US");
+const rows = buildRows(people, createRowIdGetter<Person>("id"));
+const ids = (list: GridRow<Person>[]) => list.map((row) => row.original.id);
+
+describe("columns", () => {
+  it("derives ids and readable headers", () => {
+    expect(columns[0].id).toBe("id");
+    expect(columns[1].header).toBe("Name");
+    expect(resolveColumns<{ firstName: string }>([{ field: "firstName" }])[0].header).toBe("First Name");
+    expect(resolveColumns<{ start_date: string }>([{ field: "start_date" }])[0].header).toBe("Start date");
+  });
+
+  it("rejects duplicate ids", () => {
+    expect(() => resolveColumns<Person>([{ field: "name" }, { field: "name" }])).toThrow(/Duplicate/);
+  });
+
+  it("lays out pinned, ordered, sized and hidden columns", () => {
+    const layout = computeLayout(columns, {
+      columnOrder: ["city", "name"],
+      columnVisibility: { age: false },
+      columnSizing: { name: 200 },
+      columnPinning: { left: ["id"], right: ["status"] },
+    });
+    expect(layout.left.map((i) => i.column.id)).toEqual(["id"]);
+    expect(layout.center.map((i) => i.column.id)).toEqual(["city", "name", "joined", "active"]);
+    expect(layout.right.map((i) => i.column.id)).toEqual(["status"]);
+    expect(layout.center[1]).toMatchObject({ offset: 160, width: 200 });
+    expect(layout.left[0].pinEdge).toBe(true);
+    expect(layout.right[0].pinEdge).toBe(true);
+    expect(layout.totalWidth).toBe(160 * 5 + 200);
+  });
+
+  it("offsets right-pinned columns from the end, including resize previews", () => {
+    const layout = computeLayout(columns, {
+      columnOrder: [],
+      columnVisibility: {},
+      columnSizing: {},
+      columnPinning: { left: [], right: ["city", "status"] },
+    });
+    const [city, status] = layout.right;
+    expect(getLayoutVars(layout)[`--dg-c${status.visibleIndex}-o`]).toBe("0px");
+    expect(getLayoutVars(layout)[`--dg-c${city.visibleIndex}-o`]).toBe("160px");
+    expect(getLayoutVars(layout, { status: 300 })[`--dg-c${city.visibleIndex}-o`]).toBe("300px");
+  });
+
+  it("moves a column into the target's pin section and back", () => {
+    const pinned = moveColumn(columns, { columnOrder: [], columnPinning: { left: ["id"], right: [] } }, "city", "id", "after");
+    expect(pinned.columnPinning.left).toEqual(["id", "city"]);
+
+    const unpinned = moveColumn(columns, pinned, "city", "name", "before");
+    expect(unpinned.columnPinning.left).toEqual(["id"]);
+    expect(unpinned.columnOrder.indexOf("city")).toBe(unpinned.columnOrder.indexOf("name") - 1);
+  });
+});
+
+describe("filtering", () => {
+  const run = (filters: ColumnFilter[], search = "") =>
+    ids(filterRows(rows, columns, filters, search, formatters));
+
+  it("returns the input array when nothing filters", () => {
+    expect(filterRows(rows, columns, [], "  ", formatters)).toBe(rows);
+    expect(filterRows(rows, columns, [{ columnId: "name", operator: "contains", value: "" }], "", formatters)).toBe(rows);
+  });
+
+  it("matches text case-insensitively", () => {
+    expect(run([{ columnId: "name", operator: "contains", value: "B" }])).toEqual([2]);
+  });
+
+  it("applies every column filter together", () => {
+    expect(
+      run([
+        { columnId: "city", operator: "equals", value: "paris" },
+        { columnId: "active", operator: "equals", value: false },
+      ]),
+    ).toEqual([4]);
+  });
+
+  it("handles empty cell values", () => {
+    expect(run([{ columnId: "city", operator: "startsWith", value: "p" }])).toEqual([1, 4]);
+    expect(run([{ columnId: "age", operator: "isEmpty" }])).toEqual([2]);
+  });
+
+  it("filters numbers", () => {
+    expect(run([{ columnId: "age", operator: "between", value: 28, value2: 34 }])).toEqual([1, 3, 5]);
+    expect(run([{ columnId: "age", operator: "gt", value: 40 }])).toEqual([4, 6]);
+  });
+
+  it("filters dates by local calendar day", () => {
+    expect(run([{ columnId: "joined", operator: "equals", value: "2024-01-15" }])).toEqual([1]);
+    expect(run([{ columnId: "joined", operator: "before", value: "2023-01-01" }])).toEqual([4, 6]);
+    expect(run([{ columnId: "joined", operator: "after", value: "2024-01-15" }])).toEqual([3, 5]);
+    expect(run([{ columnId: "joined", operator: "between", value: "2024-01-15", value2: "2024-01-16" }])).toEqual([1, 3]);
+  });
+
+  it("filters option sets", () => {
+    expect(run([{ columnId: "status", operator: "in", value: ["new", "gone"] }])).toEqual([2, 3, 5]);
+  });
+
+  it("searches display values and requires every term", () => {
+    expect(run([], "paris active")).toEqual([1, 4]);
+    expect(run([], "Gone")).toEqual([3]);
+  });
+});
+
+describe("sorting", () => {
+  const sorted = (sorting: SortItem[]) => ids(sortRows(rows, columns, sorting));
+
+  it("sorts numbers with empty values last in both directions", () => {
+    expect(sorted([{ columnId: "age", desc: false }])).toEqual([3, 5, 1, 4, 6, 2]);
+    expect(sorted([{ columnId: "age", desc: true }])).toEqual([6, 4, 1, 3, 5, 2]);
+  });
+
+  it("uses natural, case-insensitive string order", () => {
+    expect(sorted([{ columnId: "name", desc: false }])).toEqual([1, 2, 3, 4, 6, 5]);
+  });
+
+  it("applies sorts in priority order", () => {
+    expect(
+      sorted([
+        { columnId: "city", desc: false },
+        { columnId: "age", desc: true },
+      ]),
+    ).toEqual([6, 2, 4, 1, 5, 3]);
+  });
+
+  it("sorts dates and option labels", () => {
+    expect(sorted([{ columnId: "joined", desc: false }])).toEqual([6, 4, 2, 1, 3, 5]);
+    expect(sorted([{ columnId: "status", desc: false }])).toEqual([1, 4, 6, 3, 2, 5]);
+  });
+
+  it("cycles ascending, descending, off", () => {
+    const asc = toggleSorting([], "a", false);
+    expect(asc).toEqual([{ columnId: "a", desc: false }]);
+    const desc = toggleSorting(asc, "a", false);
+    expect(desc).toEqual([{ columnId: "a", desc: true }]);
+    expect(toggleSorting(desc, "a", false)).toEqual([]);
+    expect(toggleSorting(desc, "b", true)).toEqual([
+      { columnId: "a", desc: true },
+      { columnId: "b", desc: false },
+    ]);
+    expect(toggleSorting(desc, "b", false)).toEqual([{ columnId: "b", desc: false }]);
+  });
+});
+
+describe("pagination and virtualization", () => {
+  it("clamps the page index", () => {
+    const page = paginate(rows, { pageIndex: 9, pageSize: 4 }, { enabled: true, server: false });
+    expect(page).toMatchObject({ pageIndex: 1, pageCount: 2, pageOffset: 4 });
+    expect(ids(page.rows)).toEqual([5, 6]);
+  });
+
+  it("uses the server row count", () => {
+    const page = paginate(rows.slice(0, 2), { pageIndex: 3, pageSize: 2 }, { enabled: true, server: true, rowCount: 101 });
+    expect(page).toMatchObject({ pageCount: 51, pageOffset: 6, rowCount: 101 });
+    expect(page.rows).toHaveLength(2);
+  });
+
+  it("computes the visible row window", () => {
+    const viewport = { scrollTop: 400, scrollLeft: 0, width: 800, height: 440 };
+    expect(getRowRange(viewport, 1000, 40, 40, 2)).toEqual({ start: 8, end: 22 });
+  });
+
+  it("computes the visible column window", () => {
+    const many = resolveColumns<Record<string, number>>(
+      Array.from({ length: 50 }, (_, i) => ({ id: `c${i}`, accessor: (row) => row[`c${i}`], width: 100 })),
+    );
+    const layout = computeLayout(many, {
+      columnOrder: [],
+      columnVisibility: {},
+      columnSizing: {},
+      columnPinning: { left: ["c0"], right: [] },
+    });
+    expect(getColumnRange(layout, { scrollTop: 0, scrollLeft: 1000, width: 500, height: 300 }, 0)).toEqual({ start: 10, end: 14 });
+    expect(getColumnRange(layout, { scrollTop: 0, scrollLeft: 0, width: 0, height: 0 })).toEqual({ start: 0, end: 49 });
+  });
+});
+
+describe("state", () => {
+  it("seeds pinning and visibility from column definitions", () => {
+    const state = createInitialState<Person>({
+      data: [],
+      columns: [{ field: "id", pin: "left" }, { field: "name", hidden: true }],
+    });
+    expect(state.columnPinning).toEqual({ left: ["id"], right: [] });
+    expect(state.columnVisibility).toEqual({ name: false });
+  });
+
+  it("prefers defined controlled values", () => {
+    const state = createInitialState<Person>({ data: [], columns: [] });
+    expect(mergeState(state, undefined)).toBe(state);
+    expect(mergeState(state, { globalFilter: undefined })).toBe(state);
+    expect(mergeState(state, { globalFilter: "x" }).globalFilter).toBe("x");
+  });
+});
+
+function setup(overrides: Partial<GridOptions<Person>> = {}) {
+  const options: GridOptions<Person> = {
+    data: people,
+    columns: defs,
+    getRowId: "id",
+    enableRowSelection: true,
+    ...overrides,
+  };
+  const engine = createGridEngine(options);
+  const resolved = resolveColumns(options.columns);
+  const state = engine.api.getState();
+  const filtered = filterRows(rows, resolved, state.filters, state.globalFilter, formatters);
+  const sortedRows = sortRows(filtered, resolved, state.sorting);
+  const model: GridModel<Person> = {
+    columns: resolved,
+    coreRows: rows,
+    sortedRows,
+    page: paginate(sortedRows, state.pagination, { enabled: true, server: false }),
+    layout: computeLayout(resolved, state),
+    rowHeight: 40,
+    headerHeight: 40,
+    formatters,
+  };
+  engine.sync(options, model);
+  return engine;
+}
+
+describe("engine", () => {
+  it("returns to the first page and reports the query when filters change", () => {
+    const onQueryChange = vi.fn();
+    const engine = setup({ onQueryChange, initialState: { pagination: { pageIndex: 2, pageSize: 2 } } });
+
+    engine.api.setFilter("city", { operator: "equals", value: "paris" });
+
+    expect(engine.api.getState().pagination.pageIndex).toBe(0);
+    expect(onQueryChange).toHaveBeenCalledWith(
+      expect.objectContaining({
+        filters: [{ columnId: "city", operator: "equals", value: "paris" }],
+        pagination: { pageIndex: 0, pageSize: 2 },
+      }),
+    );
+  });
+
+  it("leaves controlled state to the parent", () => {
+    const onStateChange = vi.fn();
+    const engine = setup({ state: { sorting: [] }, onStateChange });
+
+    engine.api.toggleSort("name");
+
+    expect(engine.api.getState().sorting).toEqual([]);
+    expect(onStateChange.mock.calls[0][0].sorting).toEqual([{ columnId: "name", desc: false }]);
+  });
+
+  it("selects ranges and skips rows that cannot be selected", () => {
+    const engine = setup({ enableRowSelection: (row) => row.id !== 3 });
+
+    engine.api.toggleRowSelected("1");
+    engine.api.toggleRowSelected("4", { range: true });
+    expect(engine.api.getSelectedRowIds()).toEqual(["1", "2", "4"]);
+
+    engine.api.toggleAllRowsSelected(true);
+    expect(engine.api.getSelectedRows().map((p) => p.id)).toEqual([1, 2, 4, 5, 6]);
+  });
+
+  it("keeps one row selected in single mode", () => {
+    const engine = setup({ selectionMode: "single" });
+    engine.api.toggleRowSelected("1");
+    engine.api.toggleRowSelected("2");
+    expect(engine.api.getSelectedRowIds()).toEqual(["2"]);
+  });
+
+  it("validates edits and tracks async saves", async () => {
+    let finishSave!: () => void;
+    const onCellEdit = vi.fn(() => new Promise<void>((resolve) => (finishSave = resolve)));
+    const engine = setup({
+      columns: [
+        { field: "id", type: "number" },
+        { field: "name", editable: true, validate: (value) => (String(value).trim() ? null : "Required") },
+      ],
+      onCellEdit,
+    });
+
+    engine.api.startEditing("1", "name");
+    expect(engine.store.getSnapshot().ui.editing).toEqual({ rowId: "1", columnId: "name" });
+
+    expect(engine.commitEdit("1", "name", "  ")).toBe("Required");
+    expect(engine.commitEdit("1", "name", "Alicia")).toBeNull();
+    expect(onCellEdit).toHaveBeenCalledWith(
+      expect.objectContaining({ rowId: "1", columnId: "name", value: "Alicia", previousValue: "Alice" }),
+    );
+    expect(engine.store.getSnapshot().ui).toMatchObject({ editing: null, pending: { "1": { name: "Alicia" } } });
+
+    finishSave();
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(engine.store.getSnapshot().ui.pending).toEqual({});
+  });
+});