cacheplane · blove · Aug 25, 2026 · Aug 20, 2026 · Aug 20, 2026 · Aug 20, 2026
@@ -6,7 +6,7 @@ nav: Headless engine
 
 A headless renderer starts with `createLocalRowModel`. Add `createGrid` only when your renderer needs UI state. The grid below is exactly that: 75 services rendered from a plain `<table>`, with `createLocalRowModel` driving sort and filter and `createGrid` driving row selection.
 
-`setQuery` — triggered here by typing into the filter — does not settle synchronously. The model rebuilds cooperatively, yielding between slices so a large query cannot block the frame, and publishes progress and failures through `status`. (Sorting a column is the exception: a sort-only change on ungrouped data re-orders rows the model has already indexed, so it settles synchronously.) Two things follow, and the example does both: **select** what you subscribe to, or you re-render on every slice, and **read `status`**, or a rebuild that fails leaves stale rows on screen with nothing to say so.
+`setQuery` does not settle synchronously in the general case — the model rebuilds cooperatively, yielding between slices so a large query cannot block the frame, and publishes progress and failures through `status`. Sort-only and filter-only changes on ungrouped data are the exception, including typing into the filter here: each re-orders or re-selects rows the model has already indexed, so it settles synchronously with no `rebuilding` phase. Grouped and mixed changes still rebuild cooperatively — see [Snapshot & subscribe](/docs/headless/state-model) for a demo. Two things are still worth doing, and the example does both: **select** what you subscribe to, so a cooperative rebuild elsewhere doesn't re-render you on every slice, and **read `status`**, so a failed rebuild doesn't leave stale rows on screen with nothing to say so.
 
 <Example id="headless-custom-renderer" />
 

@@ -6,7 +6,7 @@ nav: Headless engine
 
 The row model and UI grid are independent observable stores. Subscribe only to the state your renderer uses.
 
-A `setQuery` that changes the filter does not settle synchronously — the model rebuilds cooperatively, yielding between slices so a large query cannot block the frame. A sort-only change on ungrouped data is the one exception: it re-orders rows the model has already indexed, so it settles synchronously and never publishes a `rebuilding` phase — a plain sort needs no progress UI. On a small dataset even the cooperative rebuild is over before a human (or React) can see it happen, which is why the button below filters 150,000 rows instead of 75: watch `status` cycle through `rebuilding` with a live percentage, then settle back to `ready`.
+A `setQuery` that changes row grouping does not settle synchronously — the model rebuilds cooperatively, yielding between slices so a large query cannot block the frame. Sort-only and filter-only changes on ungrouped data are the exception: each re-orders or re-selects rows the model has already indexed, so it settles synchronously and never publishes a `rebuilding` phase — plain sorting and filtering need no progress UI. Grouped and mixed changes still rebuild cooperatively. On a small dataset even the cooperative rebuild is over before a human (or React) can see it happen, which is why the button below groups 150,000 rows instead of 75: watch `status` cycle through `rebuilding` with a live percentage, then settle back to `ready`.
 
 <Example id="headless-rebuild-progress" />
 
@@ -43,7 +43,7 @@ committed, and mutations keep committing into it meanwhile: `setRows`,
 `applyTransaction` and both expansion paths publish a new snapshot while a
 rebuild runs. A renderer that stops re-reading the snapshot during a rebuild
 drops those, which is exactly the streaming-plus-filter case. The table in the
-example above stays on the last committed filter result throughout, exactly
+example above stays on the last committed result throughout, exactly
 like this.
 
 `completedRows` and `totalRows` count the rebuild's **work units, not rows**.

@@ -19,8 +19,8 @@ export function RebuildProgressDemo() {
 
   // Selecting `snapshot` (not the whole state) means this component bails
   // out on identity between rebuild slices — it only renders once, when the
-  // filter actually lands. `RebuildProgress` above is the one re-rendering on
-  // every slice in the meantime.
+  // grouping change actually lands. `RebuildProgress` above is the one
+  // re-rendering on every slice in the meantime.
   const readSnapshot = useCallback(
     () => rowModel.getState().snapshot,
     [rowModel],
@@ -31,28 +31,29 @@ export function RebuildProgressDemo() {
     readSnapshot,
   );
 
-  const [filtered, setFiltered] = useState(false);
+  const [grouped, setGrouped] = useState(false);
 
-  // A FILTER change, not a sort: a sort-only change on ungrouped data
-  // settles synchronously and never publishes a `rebuilding` phase, so it
-  // could not demonstrate the progress readout at all.
-  const toggleFilter = () => {
-    const next = !filtered;
-    setFiltered(next);
+  // A GROUPING change, not a filter or a sort: both of those settle
+  // synchronously on ungrouped data (the sort fast path and the filter fast
+  // path each require `rowGroups.length === 0`), so neither could
+  // demonstrate the progress readout anymore. Grouping never takes a fast
+  // path — it always rebuilds cooperatively — which is exactly why it is the
+  // vehicle here.
+  const toggleGrouped = () => {
+    const next = !grouped;
+    setGrouped(next);
     rowModel.setQuery({
       ...snapshot.query,
-      filters: next
-        ? [{ columnId: "region", operator: "equals", value: "west" }]
-        : [],
+      rowGroups: next ? [{ columnId: "region" }] : [],
     });
   };
 
   return (
     <div>
-      <button type="button" onClick={toggleFilter}>
-        {filtered
-          ? `Show all ${ORDER_COUNT.toLocaleString()} orders again`
-          : `Filter ${ORDER_COUNT.toLocaleString()} orders to the west region`}
+      <button type="button" onClick={toggleGrouped}>
+        {grouped
+          ? "Ungroup"
+          : `Group ${ORDER_COUNT.toLocaleString()} orders by region`}
       </button>
       <RebuildProgress rowModel={rowModel} />
       <p style={{ fontSize: 13 }}>
@@ -72,14 +73,21 @@ export function RebuildProgressDemo() {
         <tbody>
           {snapshot
             .range(0, Math.min(PREVIEW_ROWS, snapshot.visibleRowCount))
-            .filter((entry) => entry.kind === "data")
-            .map(({ rowId, row }) => (
-              <tr key={rowId}>
-                {columns.map((c) => (
-                  <td key={c.id}>{String(c.accessor(row))}</td>
-                ))}
-              </tr>
-            ))}
+            .map((entry) =>
+              entry.kind === "data" ? (
+                <tr key={entry.rowId}>
+                  {columns.map((c) => (
+                    <td key={c.id}>{String(c.accessor(entry.row))}</td>
+                  ))}
+                </tr>
+              ) : (
+                <tr key={entry.groupId}>
+                  <td colSpan={columns.length}>
+                    {String(entry.value)} ({entry.childCount})
+                  </td>
+                </tr>
+              ),
+            )}
         </tbody>
       </table>
     </div>

@@ -43,15 +43,12 @@ describe("RebuildProgressDemo", () => {
       });
 
       fireEvent.click(
-        screen.getByRole("button", { name: /filter 150,000 orders/i }),
+        screen.getByRole("button", { name: /group 150,000 orders/i }),
       );
 
       await waitFor(
         () => {
           expect(status).toHaveTextContent("Ready.");
-          // The filter landed: only the 30,000 west-region orders survive,
-          // and every preview row is one of them.
-          expect(screen.getByText(/30,000 rows indexed/)).toBeInTheDocument();
         },
         { timeout: REBUILD_TIMEOUT },
       );
@@ -60,34 +57,52 @@ describe("RebuildProgressDemo", () => {
       // Proves the rebuild actually published at least one intermediate
       // `rebuilding` slice before landing on `ready` — the whole reason this
       // example exists. On the small 75-row custom-renderer example this
-      // would be a coin flip; at 150,000 rows it is not. A sort-only change
-      // could never pass this: on ungrouped data it settles synchronously
-      // with no `rebuilding` phase at all.
+      // would be a coin flip; at 150,000 rows it is not. A sort-only or
+      // filter-only change could never pass this: on ungrouped data both
+      // settle synchronously with no `rebuilding` phase at all. Grouping is
+      // the one change vehicle that is cooperative by design, not omission.
       expect(sawRebuilding).toBe(true);
 
+      // The grouping landed: every visible region group has surfaced as its
+      // own row (5 regions), distinct from the plain data rows.
       const previewRows = screen.getAllByRole("row").slice(1);
       expect(previewRows.length).toBeGreaterThan(0);
-      for (const row of previewRows) {
-        expect(row).toHaveTextContent("west");
-      }
+      const groupRows = previewRows.filter((row) =>
+        /\(\d+\)/.test(row.textContent ?? ""),
+      );
+      expect(groupRows.length).toBeGreaterThan(0);
+
+      // Group rows sit alongside the 150,000 data rows in the indexed
+      // count, so it goes up, not down, once grouping lands.
+      const rowsIndexedText = screen.getByText(/rows indexed/).textContent;
+      const indexedCount = Number(
+        rowsIndexedText
+          ?.match(/^([\d,]+) rows indexed/)?.[1]
+          ?.replace(/,/g, ""),
+      );
+      expect(indexedCount).toBeGreaterThan(150_000);
     },
     REBUILD_TIMEOUT + 5_000,
   );
 
   it(
-    "clears the filter cooperatively on the second click",
+    "ungroups cooperatively on the second click",
     async () => {
       render(<RebuildProgressDemo />);
       await waitFor(() => screen.getByText(/150,000 rows indexed/), {
         timeout: REBUILD_TIMEOUT,
       });
 
       fireEvent.click(
-        screen.getByRole("button", { name: /filter 150,000 orders/i }),
+        screen.getByRole("button", { name: /group 150,000 orders/i }),
+      );
+      await waitFor(
+        () => {
+          const status = screen.getByRole("status");
+          expect(status).toHaveTextContent("Ready.");
+        },
+        { timeout: REBUILD_TIMEOUT },
       );
-      await waitFor(() => screen.getByText(/30,000 rows indexed/), {
-        timeout: REBUILD_TIMEOUT,
-      });
 
       let sawRebuilding = false;
       const status = screen.getByRole("status");
@@ -102,9 +117,7 @@ describe("RebuildProgressDemo", () => {
         subtree: true,
       });
 
-      fireEvent.click(
-        screen.getByRole("button", { name: /show all 150,000 orders/i }),
-      );
+      fireEvent.click(screen.getByRole("button", { name: /ungroup/i }));
 
       await waitFor(
         () => {
@@ -115,10 +128,17 @@ describe("RebuildProgressDemo", () => {
       );
 
       observer.disconnect();
-      // Removing a filter re-runs the same cooperative path over all
+      // Removing the grouping re-runs the same cooperative path over all
       // 150,000 source rows, so the toggle demonstrates progress in both
       // directions.
       expect(sawRebuilding).toBe(true);
+
+      // Ungrouped: no group rows remain, only plain data rows.
+      const previewRows = screen.getAllByRole("row").slice(1);
+      const groupRows = previewRows.filter((row) =>
+        /\(\d+\)/.test(row.textContent ?? ""),
+      );
+      expect(groupRows.length).toBe(0);
     },
     REBUILD_TIMEOUT + 5_000,
   );

@@ -8,7 +8,7 @@ export interface Order {
 const REGIONS = ["north", "south", "east", "west", "central"];
 
 // Deliberately large and deterministic (no Math.random): big enough that a
-// filter change cannot settle inside one animation frame, so the rebuild
+// grouping change cannot settle inside one animation frame, so the rebuild
 // really does publish multiple `rebuilding` slices instead of jumping
 // straight to `ready` — see the note on the smaller custom-renderer example.
 export const ORDER_COUNT = 150_000;

@@ -3,7 +3,7 @@ import { defineExample } from "../../../lib/docs/examples/define";
 export default defineExample({
   title: "Watching a rebuild",
   description:
-    "Filtering 150,000 rows cannot settle inside one animation frame, so status.kind cycles through rebuilding with a live completedRows/totalRows progress readout before returning to ready.",
+    "Grouping 150,000 rows cannot settle inside one animation frame, so status.kind cycles through rebuilding with a live completedRows/totalRows progress readout before returning to ready.",
   files: [
     "RebuildProgressDemo.tsx",
     "RebuildProgress.tsx",