@gridkitjs/react 0.6.0 → 0.8.0

package/dist/index.js

@@ -1,19 +1,24 @@
 // src/DataGrid/DataGrid.tsx
 import {
+  useEffect as useEffect2,
   useImperativeHandle,
-  useMemo as useMemo2,
+  useMemo as useMemo4,
   useRef as useRef4,
   useState as useState5
 } from "react";
 import {
   applyColumnOrder,
+  computeAggregates,
   defineColumnsFromRows,
   fitColumnsToWidth,
+  groupRows,
   moveColumnBefore,
+  paginateRows as paginateRows2,
   resolveColumnWidths,
   resolveRowId,
   resolveShownRows,
-  totalColumnWidth
+  totalColumnWidth,
+  withGroupAggregates
 } from "@gridkitjs/core";
 
 // src/DataGrid/components/GridHeader.tsx
@@ -33,6 +38,7 @@ function classNames(...values) {
 // src/DataGrid/useGridNavigation.ts
 import {
   useEffect,
+  useMemo,
   useRef,
   useState
 } from "react";
@@ -47,18 +53,26 @@ function tabIndexFor(columnIndex, focusedColumnIndex) {
 }
 function cellAt(table, focus) {
   const row = focus.rowIndex === HEADER_ROW ? table.tHead?.rows[0] ?? null : table.tBodies[0]?.rows[focus.rowIndex] ?? null;
-  return row?.cells[focus.columnIndex] ?? null;
+  if (row === null) {
+    return null;
+  }
+  const columnIndex = Math.min(focus.columnIndex, row.cells.length - 1);
+  return row.cells[columnIndex] ?? null;
 }
 function useGridNavigation({
   tableRef,
   rowCount,
-  columnCount
+  columnCount,
+  isSkippableRow
 }) {
   const [stored, setStored] = useState({
     rowIndex: HEADER_ROW,
     columnIndex: 0
   });
-  const focus = clampFocus(stored, rowCount, columnCount);
+  const focus = useMemo(
+    () => clampFocus(stored, rowCount, columnCount),
+    [stored, rowCount, columnCount]
+  );
   const pending = useRef(false);
   useEffect(() => {
     if (!pending.current) {
@@ -103,7 +117,8 @@ function useGridNavigation({
       focus,
       rowCount,
       columnCount,
-      pageSize()
+      pageSize(),
+      isSkippableRow
     );
     if (next === null) {
       return;
@@ -124,7 +139,7 @@ function useGridNavigation({
 
 // src/DataGrid/useGridSelection.ts
 import {
-  useMemo,
+  useMemo as useMemo2,
   useRef as useRef2
 } from "react";
 import {
@@ -164,16 +179,16 @@ function countMessage(count, noun) {
   return count === 1 ? `1 ${noun} selected` : `${String(count)} ${noun}s selected`;
 }
 function useAsSet(values) {
-  return useMemo(() => new Set(values), [values]);
+  return useMemo2(() => new Set(values), [values]);
 }
 function useIndexedBy(values, key) {
-  return useMemo(
+  return useMemo2(
     () => new Map(values.map((value) => [value[key], value])),
     [values, key]
   );
 }
 function useMappedArray(values, key) {
-  return useMemo(() => values.map((value) => value[key]), [values, key]);
+  return useMemo2(() => values.map((value) => value[key]), [values, key]);
 }
 function useGridSelection({
   rows,
@@ -366,16 +381,26 @@ function ChevronsUpDownIcon() {
 function ChevronUpIcon() {
   return /* @__PURE__ */ jsx(Icon, { children: /* @__PURE__ */ jsx("path", { d: "m18 15-6-6-6 6" }) });
 }
+function GroupIcon() {
+  return /* @__PURE__ */ jsxs(Icon, { children: [
+    /* @__PURE__ */ jsx("rect", { x: "3", y: "3", width: "7", height: "7", rx: "1" }),
+    /* @__PURE__ */ jsx("rect", { x: "14", y: "3", width: "7", height: "7", rx: "1" }),
+    /* @__PURE__ */ jsx("rect", { x: "8.5", y: "14", width: "7", height: "7", rx: "1" })
+  ] });
+}
 function GridHeader({
   columns,
   resize,
   drag,
   sort,
   sortableColumns,
+  grouping,
+  groupableColumns,
+  groupToggleIconColumns,
   nav,
   selection
 }) {
-  const { beforeId } = drag.dropTarget ?? {};
+  const beforeId = drag.dropTarget?.kind === "column-order" ? drag.dropTarget.beforeId : void 0;
   const draggedEntry = columns.find((entry) => entry.id === drag.draggedColumnId) ?? null;
   return /* @__PURE__ */ jsxs("thead", { children: [
     /* @__PURE__ */ jsx("tr", { className: "grid-header", role: "row", "aria-rowindex": 1, children: columns.map((entry, index) => {
@@ -388,10 +413,16 @@ function GridHeader({
       const sortable = column.sortable ?? sortableColumns;
       const sortDirection = sort.directionFor(entry.id);
       const sortPriority = sort.priorityFor(entry.id);
+      const groupable = column.groupable ?? groupableColumns;
+      const showGroupToggleIcon = column.groupToggleIcon ?? groupToggleIconColumns;
+      const isGrouped = grouping.groupBy.some(
+        (level) => level.columnId === entry.id
+      );
       const shortcuts = buildKeyShortcuts({
         reorderable: entry.reorderable,
         resizable: entry.resizable,
-        sortable
+        sortable,
+        groupable
       });
       return /* @__PURE__ */ jsxs(
         "th",
@@ -413,7 +444,7 @@ function GridHeader({
             if (drag.justDragged()) {
               return;
             }
-            if (event.target instanceof Element && (event.target.closest(".header-resize-handle") !== null || event.target.closest(".header-sort-toggle") !== null)) {
+            if (event.target instanceof Element && (event.target.closest(".header-resize-handle") !== null || event.target.closest(".header-sort-toggle") !== null || event.target.closest(".header-group-toggle") !== null)) {
               return;
             }
             selection.selectColumn(entry.id, intentOf(event));
@@ -441,6 +472,11 @@ function GridHeader({
               sort.toggle(entry, { shiftKey: event.shiftKey });
               return;
             }
+            if (event.key === "ArrowDown" && event.altKey && groupable) {
+              event.preventDefault();
+              grouping.toggleGroupBy(entry.id);
+              return;
+            }
             if (event.key === " " || event.key === "Enter") {
               event.preventDefault();
               selection.selectColumn(
@@ -453,7 +489,11 @@ function GridHeader({
           },
           className: classNames(
             "header-cell",
-            entry.reorderable ? "is-reorderable" : "",
+            // The grab affordance a header showing either drag
+            // destination shares — a column dragged only for grouping
+            // (`groupByDraggable` without `reorderable`) grabs the same
+            // way one dragged only for reordering does.
+            entry.reorderable || entry.groupByDraggable ? "is-reorderable" : "",
             selected ? "is-selected" : "",
             resizing ? "is-resizing" : "",
             dragging ? "is-dragging" : "",
@@ -468,12 +508,40 @@ function GridHeader({
             "aria-sort",
             sortDirection === "asc" ? "ascending" : "descending"
           ),
-          ...entry.reorderable && {
+          ...(entry.reorderable || entry.groupByDraggable) && {
             onPointerDown: (event) => {
               drag.startDrag(entry, event);
             }
           },
           children: [
+            groupable && showGroupToggleIcon && /*
+             * Inline, before the label, rather than absolutely
+             * positioned like the sort toggle and resize handle: those
+             * two already share the header's right edge, and a third
+             * overlay there would need its own carve-out. Sitting in
+             * normal flow costs nothing but a few pixels of label width.
+             * A pointer affordance only, same as the other two — the
+             * keyboard equivalent is Alt+ArrowDown on the header itself.
+             */
+            /* @__PURE__ */ jsx(
+              "span",
+              {
+                className: classNames(
+                  "header-group-toggle",
+                  isGrouped ? "is-grouped" : ""
+                ),
+                "aria-hidden": "true",
+                tabIndex: -1,
+                onPointerDown: (event) => {
+                  event.stopPropagation();
+                },
+                onClick: (event) => {
+                  event.stopPropagation();
+                  grouping.toggleGroupBy(entry.id);
+                },
+                children: /* @__PURE__ */ jsx(GroupIcon, {})
+              }
+            ),
             entry.label,
             sortable && /*
              * A pointer affordance only, and hidden from assistive
@@ -546,17 +614,224 @@ function GridHeader({
 }
 
 // src/DataGrid/components/GridBody.tsx
-import { intentOf as intentOf2 } from "@gridkitjs/core";
+import { useMemo as useMemo3 } from "react";
+import {
+  groupRowId,
+  intentOf as intentOf2
+} from "@gridkitjs/core";
+
+// src/DataGrid/components/GridGroupRow.tsx
+import { memo } from "react";
+
+// src/DataGrid/components/formatAggregateValue.ts
+function formatAggregateValue(value) {
+  if (value === null || value === void 0) {
+    return "\u2014";
+  }
+  if (value instanceof Date) {
+    return value.toLocaleString();
+  }
+  switch (typeof value) {
+    case "string":
+    case "boolean":
+    case "bigint":
+    case "symbol":
+      return String(value);
+    case "number":
+      return value.toLocaleString();
+    case "function":
+      return "(function)";
+    default:
+      return JSON.stringify(value);
+  }
+}
+
+// src/DataGrid/components/GridGroupRow.tsx
+import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
+function formatGroupValue(value) {
+  if (value === null || value === void 0) {
+    return "(blank)";
+  }
+  if (value instanceof Date) {
+    return value.toLocaleString();
+  }
+  switch (typeof value) {
+    case "string":
+    case "number":
+    case "boolean":
+    case "bigint":
+    case "symbol":
+      return String(value);
+    case "function":
+      return "(function)";
+    default:
+      return JSON.stringify(value);
+  }
+}
+function GridGroupRowComponent({
+  columnCount,
+  groupId,
+  level,
+  columnLabel,
+  value,
+  expanded,
+  count,
+  datasetIndex,
+  posinset,
+  setsize,
+  focused,
+  aggregates,
+  results,
+  columns
+}) {
+  const byId = new Map(columns.map((entry) => [entry.id, entry]));
+  return /* @__PURE__ */ jsx2(
+    "tr",
+    {
+      role: "row",
+      "aria-rowindex": datasetIndex + 2,
+      "aria-level": level + 1,
+      "aria-expanded": expanded,
+      "aria-setsize": setsize,
+      "aria-posinset": posinset,
+      "data-gridkit-group": groupId,
+      className: classNames(
+        "grid-group-row",
+        `is-group-level-${String(level)}`
+      ),
+      children: /* @__PURE__ */ jsx2(
+        "td",
+        {
+          role: "gridcell",
+          colSpan: columnCount,
+          tabIndex: focused ? 0 : -1,
+          "aria-keyshortcuts": "Space Enter",
+          className: "grid-group-cell",
+          children: /* @__PURE__ */ jsxs2(
+            "div",
+            {
+              className: "grid-group-cell-content",
+              style: { paddingInlineStart: `${String(level * 1.25 + 0.5)}rem` },
+              children: [
+                /* @__PURE__ */ jsx2(
+                  "span",
+                  {
+                    className: classNames(
+                      "group-toggle",
+                      expanded ? "is-expanded" : "is-collapsed"
+                    ),
+                    "aria-hidden": "true"
+                  }
+                ),
+                /* @__PURE__ */ jsxs2("span", { className: "group-label", children: [
+                  columnLabel,
+                  ": ",
+                  formatGroupValue(value)
+                ] }),
+                /* @__PURE__ */ jsxs2("span", { className: "group-count", children: [
+                  "(",
+                  count,
+                  ")"
+                ] }),
+                aggregates.length > 0 && /* @__PURE__ */ jsx2("span", { className: "group-aggregates", children: aggregates.map((spec) => {
+                  const key = spec.id ?? spec.columnId;
+                  const aggregateValue = results.get(key);
+                  const column = byId.get(spec.columnId);
+                  const rendered = column?.column.footerTemplate ? column.column.footerTemplate({
+                    value: aggregateValue,
+                    rows: []
+                  }) : formatAggregateValue(aggregateValue);
+                  const aggregateLabel = spec.id ?? column?.label ?? spec.columnId;
+                  return /* @__PURE__ */ jsxs2("span", { className: "group-aggregate", children: [
+                    aggregateLabel,
+                    ": ",
+                    rendered
+                  ] }, key);
+                }) })
+              ]
+            }
+          )
+        }
+      )
+    }
+  );
+}
+var GridGroupRow = memo(
+  GridGroupRowComponent
+);
+var GridGroupRow_default = GridGroupRow;
+
+// src/DataGrid/components/GridGroupSummaryRow.tsx
+import { memo as memo2 } from "react";
+import { jsx as jsx3, jsxs as jsxs3 } from "react/jsx-runtime";
+function GridGroupSummaryRowComponent({
+  groupId,
+  level,
+  datasetIndex,
+  results,
+  aggregates,
+  columns
+}) {
+  return /* @__PURE__ */ jsx3(
+    "tr",
+    {
+      role: "row",
+      "aria-rowindex": datasetIndex + 2,
+      "data-gridkit-group-summary": groupId,
+      className: classNames(
+        "grid-group-summary-row",
+        `is-group-level-${String(level)}`
+      ),
+      children: columns.map((entry) => {
+        const specs = aggregates.filter(
+          (candidate) => candidate.columnId === entry.id
+        );
+        const { column } = entry;
+        return /* @__PURE__ */ jsxs3(
+          "td",
+          {
+            role: "gridcell",
+            "data-gridkit-column": entry.id,
+            className: "grid-group-summary-cell",
+            style: { textAlign: specs[0]?.alignment ?? entry.alignment },
+            children: [
+              entry.id === columns[0]?.id && /* @__PURE__ */ jsx3(
+                "span",
+                {
+                  className: "grid-group-summary-indent",
+                  style: { width: `${String(level * 1.25 + 0.5)}rem` },
+                  "aria-hidden": "true"
+                }
+              ),
+              specs.map((spec) => {
+                const value = results.get(spec.id ?? spec.columnId);
+                return column.footerTemplate ? column.footerTemplate({ value, rows: [] }) : formatAggregateValue(value);
+              }).flatMap(
+                (rendered, index) => index === 0 ? [rendered] : [", ", rendered]
+              )
+            ]
+          },
+          entry.id
+        );
+      })
+    }
+  );
+}
+var GridGroupSummaryRow = memo2(
+  GridGroupSummaryRowComponent
+);
+var GridGroupSummaryRow_default = GridGroupSummaryRow;
 
 // src/DataGrid/components/GridRow.tsx
 import { accessDotted } from "@gridkitjs/core";
-import { memo } from "react";
-import { jsx as jsx2 } from "react/jsx-runtime";
+import { memo as memo3 } from "react";
+import { jsx as jsx4 } from "react/jsx-runtime";
 function GridRowComponent({
   columns,
   rowId,
   row,
   rowIndex,
+  datasetIndex,
   activeColumnId,
   selectedColumnIds,
   selected,
@@ -565,17 +840,17 @@ function GridRowComponent({
   rowsSelectable,
   cellsSelectable
 }) {
-  return /* @__PURE__ */ jsx2(
+  return /* @__PURE__ */ jsx4(
     "tr",
     {
       role: "row",
-      "aria-rowindex": rowIndex + 2,
+      "aria-rowindex": datasetIndex + 2,
       ...ariaAttr(rowsSelectable, "aria-selected", selected),
       className: classNames("grid-row", selected ? "is-selected" : ""),
       children: columns.map(({ id, column, alignment }, columnIndex) => {
         const value = accessDotted(row, column.field);
         const cellSelected = id === selectedColumnId;
-        return /* @__PURE__ */ jsx2(
+        return /* @__PURE__ */ jsx4(
           "td",
           {
             role: "gridcell",
@@ -592,7 +867,14 @@ function GridRowComponent({
               column.cellClassName ?? ""
             ),
             style: { textAlign: alignment },
-            children: column.cellTemplate ? column.cellTemplate({ value, row, rowIndex, rowId, selected }) : value
+            children: column.cellTemplate ? column.cellTemplate({
+              value,
+              row,
+              rowIndex,
+              datasetIndex,
+              rowId,
+              selected
+            }) : value
           },
           id
         );
@@ -600,11 +882,11 @@ function GridRowComponent({
     }
   );
 }
-var GridRow = memo(GridRowComponent);
+var GridRow = memo3(GridRowComponent);
 var GridRow_default = GridRow;
 
 // src/DataGrid/components/GridBody.tsx
-import { jsx as jsx3 } from "react/jsx-runtime";
+import { jsx as jsx5 } from "react/jsx-runtime";
 function cellFrom(target) {
   if (!(target instanceof Element)) {
     return null;
@@ -621,18 +903,57 @@ function cellFrom(target) {
     columnId
   };
 }
+function groupRowFrom(target) {
+  if (!(target instanceof Element)) {
+    return null;
+  }
+  const row = target.closest("tr[data-gridkit-group]");
+  const groupId = row?.getAttribute("data-gridkit-group");
+  if (!(row instanceof HTMLTableRowElement) || groupId === null || groupId === void 0) {
+    return null;
+  }
+  return { rowIndex: row.sectionRowIndex, groupId };
+}
+function groupAriaMeta(rows) {
+  const totals = /* @__PURE__ */ new Map();
+  for (const entry of rows) {
+    if (!("kind" in entry) || entry.kind !== "group") continue;
+    const parentKey = groupRowId(entry.path.slice(0, -1));
+    totals.set(parentKey, (totals.get(parentKey) ?? 0) + 1);
+  }
+  const seen = /* @__PURE__ */ new Map();
+  const meta = /* @__PURE__ */ new Map();
+  for (const entry of rows) {
+    if (!("kind" in entry) || entry.kind !== "group") continue;
+    const parentKey = groupRowId(entry.path.slice(0, -1));
+    const posinset = (seen.get(parentKey) ?? 0) + 1;
+    seen.set(parentKey, posinset);
+    meta.set(entry.groupId, {
+      posinset,
+      setsize: totals.get(parentKey) ?? posinset
+    });
+  }
+  return meta;
+}
 function GridBody({
   columns,
   rows,
   activeColumnId,
   nav,
-  selection
+  selection,
+  grouping,
+  aggregates,
+  groupAggregateDisplay
 }) {
   const { selectedCell, rowMode, cellMode } = selection;
+  const ariaMeta = useMemo3(() => groupAriaMeta(rows), [rows]);
   function targetOf(target) {
     const position = cellFrom(target);
     const entry = position === null ? void 0 : rows[position.rowIndex];
-    return position === null || entry === void 0 ? null : { position, rowId: entry.rowId };
+    if (position === null || entry === void 0 || "kind" in entry) {
+      return null;
+    }
+    return { position, rowId: entry.rowId };
   }
   function select(rowId, columnId, modifiers) {
     const intent = intentOf2(modifiers);
@@ -643,21 +964,45 @@ function GridBody({
       selection.selectCell({ rowId, columnId }, intent);
     }
   }
-  return /* @__PURE__ */ jsx3(
+  return /* @__PURE__ */ jsx5(
     "tbody",
     {
       className: "grid-body",
       onFocus: (event) => {
+        const group = groupRowFrom(event.target);
+        if (group !== null) {
+          nav.focusCell(group.rowIndex, 0);
+          return;
+        }
         const found = targetOf(event.target);
         if (found === null) return;
         nav.focusCell(found.position.rowIndex, found.position.columnIndex);
       },
       onClick: (event) => {
+        const group = groupRowFrom(event.target);
+        if (group !== null) {
+          grouping.toggleExpansion(group.groupId);
+          return;
+        }
         const found = targetOf(event.target);
         if (found === null) return;
         select(found.rowId, found.position.columnId, event);
       },
       onKeyDown: (event) => {
+        const group = groupRowFrom(event.target);
+        if (group !== null) {
+          if (event.key === "ArrowLeft" || event.key === "ArrowRight") {
+            event.preventDefault();
+            return;
+          }
+          if (event.key === " " || event.key === "Enter") {
+            event.preventDefault();
+            grouping.toggleExpansion(group.groupId);
+            return;
+          }
+          nav.onKeyDown(event);
+          return;
+        }
         if (event.key === " " || event.key === "Enter") {
           const found = targetOf(event.target);
           if (found === null) return;
@@ -671,37 +1016,193 @@ function GridBody({
         }
         nav.onKeyDown(event);
       },
-      children: rows.map(({ rowId, row, rowIndex }) => /* @__PURE__ */ jsx3(
-        GridRow_default,
-        {
-          columns,
-          rowId,
-          row,
-          rowIndex,
-          activeColumnId,
-          selectedColumnIds: selection.selectedColumnIds,
-          selected: selection.selectedRowIds.has(rowId),
-          selectedColumnId: selectedCell?.rowId === rowId ? selectedCell.columnId : null,
-          focusedColumnIndex: nav.focus.rowIndex === rowIndex ? nav.focus.columnIndex : null,
-          rowsSelectable: rowMode !== false,
-          cellsSelectable: cellMode !== false
-        },
-        rowId
-      ))
+      children: rows.map((entry) => {
+        if (!("kind" in entry)) {
+          return /* @__PURE__ */ jsx5(
+            GridRow_default,
+            {
+              columns,
+              rowId: entry.rowId,
+              row: entry.row,
+              rowIndex: entry.rowIndex,
+              datasetIndex: entry.datasetIndex,
+              activeColumnId,
+              selectedColumnIds: selection.selectedColumnIds,
+              selected: selection.selectedRowIds.has(entry.rowId),
+              selectedColumnId: selectedCell?.rowId === entry.rowId ? selectedCell.columnId : null,
+              focusedColumnIndex: nav.focus.rowIndex === entry.rowIndex ? nav.focus.columnIndex : null,
+              rowsSelectable: rowMode !== false,
+              cellsSelectable: cellMode !== false
+            },
+            entry.rowId
+          );
+        }
+        if (entry.kind === "group-summary") {
+          return /* @__PURE__ */ jsx5(
+            GridGroupSummaryRow_default,
+            {
+              groupId: entry.groupId,
+              level: entry.level,
+              datasetIndex: entry.datasetIndex,
+              results: entry.aggregates,
+              aggregates,
+              columns
+            },
+            `${entry.groupId}-summary`
+          );
+        }
+        return /* @__PURE__ */ jsx5(
+          GridGroupRow_default,
+          {
+            columnCount: columns.length,
+            groupId: entry.groupId,
+            level: entry.level,
+            columnLabel: columns.find((column) => column.id === entry.columnId)?.label ?? entry.columnId,
+            value: entry.value,
+            expanded: entry.expanded,
+            count: entry.count,
+            datasetIndex: entry.datasetIndex,
+            posinset: ariaMeta.get(entry.groupId)?.posinset ?? 1,
+            setsize: ariaMeta.get(entry.groupId)?.setsize ?? 1,
+            aggregates: groupAggregateDisplay === "inline" ? aggregates : [],
+            results: entry.aggregates,
+            columns,
+            focused: nav.focus.rowIndex === entry.rowIndex
+          },
+          entry.groupId
+        );
+      })
     }
   );
 }
 
-// src/DataGrid/useColumnDrag.ts
+// src/DataGrid/components/GridFooter.tsx
+import { jsx as jsx6 } from "react/jsx-runtime";
+function GridFooter({
+  columns,
+  aggregates,
+  results,
+  rows
+}) {
+  return /* @__PURE__ */ jsx6("tfoot", { children: /* @__PURE__ */ jsx6("tr", { className: "grid-footer", role: "row", children: columns.map((entry) => {
+    const specs = aggregates.filter(
+      (candidate) => candidate.columnId === entry.id
+    );
+    const { column } = entry;
+    return /* @__PURE__ */ jsx6(
+      "td",
+      {
+        role: "gridcell",
+        "data-gridkit-column": entry.id,
+        className: "grid-footer-cell",
+        style: { textAlign: specs[0]?.alignment ?? entry.alignment },
+        children: specs.map((spec) => {
+          const value = results.get(spec.id ?? spec.columnId);
+          return column.footerTemplate ? column.footerTemplate({ value, rows }) : formatAggregateValue(value);
+        }).flatMap(
+          (rendered, index) => index === 0 ? [rendered] : [", ", rendered]
+        )
+      },
+      entry.id
+    );
+  }) }) });
+}
+
+// src/DataGrid/components/GridPager.tsx
+import { paginationWindow } from "@gridkitjs/core";
+import { jsx as jsx7, jsxs as jsxs4 } from "react/jsx-runtime";
+function GridPager({ pager, config }) {
+  const { pagination, pageCount, currentPage } = pager;
+  const variant = config?.variant ?? "compact";
+  const sizeOptions = config?.sizeOptions;
+  return /* @__PURE__ */ jsxs4("div", { className: "gridkit-grid-pager", role: "group", "aria-label": "Pagination", children: [
+    /* @__PURE__ */ jsx7(
+      "button",
+      {
+        type: "button",
+        className: "grid-pager-button",
+        disabled: pagination.pageIndex <= 0,
+        onClick: () => {
+          pager.previousPage();
+        },
+        children: "Previous"
+      }
+    ),
+    variant === "numbered" ? paginationWindow(currentPage, pageCount, {
+      boundaryCount: config?.boundaryCount,
+      siblingCount: config?.siblingCount
+    }).map(
+      (entry, index) => entry === "ellipsis" ? /* @__PURE__ */ jsx7(
+        "span",
+        {
+          className: "grid-pager-ellipsis",
+          "aria-hidden": "true",
+          children: "\u2026"
+        },
+        `ellipsis-${String(index)}`
+      ) : /* @__PURE__ */ jsx7(
+        "button",
+        {
+          type: "button",
+          className: "grid-pager-button",
+          "aria-label": `Page ${String(entry)}`,
+          "aria-current": entry === currentPage ? "page" : void 0,
+          onClick: () => {
+            pager.goToPage(entry - 1);
+          },
+          children: entry
+        },
+        entry
+      )
+    ) : /* @__PURE__ */ jsxs4("span", { className: "grid-pager-status", children: [
+      "Page ",
+      pageCount === 0 ? 0 : currentPage,
+      " of ",
+      pageCount
+    ] }),
+    /* @__PURE__ */ jsx7(
+      "button",
+      {
+        type: "button",
+        className: "grid-pager-button",
+        disabled: pagination.pageIndex >= pageCount - 1,
+        onClick: () => {
+          pager.nextPage();
+        },
+        children: "Next"
+      }
+    ),
+    sizeOptions !== void 0 && sizeOptions.length > 0 && /* @__PURE__ */ jsxs4("label", { className: "grid-pager-page-size", children: [
+      "Rows per page",
+      /* @__PURE__ */ jsx7(
+        "select",
+        {
+          value: pagination.pageSize,
+          onChange: (event) => {
+            pager.setPageSize(Number(event.target.value));
+          },
+          children: sizeOptions.map((size) => /* @__PURE__ */ jsx7("option", { value: size, children: size }, size))
+        }
+      )
+    ] })
+  ] });
+}
+
+// src/DataGrid/components/GroupByBar.tsx
+import { createPortal as createPortal2 } from "react-dom";
+import { resolveKeyboardDropTarget } from "@gridkitjs/core";
+
+// src/DataGrid/groupByDropTarget.ts
+import {
+  movesGroupBy,
+  resolveDropBefore
+} from "@gridkitjs/core";
+
+// src/DataGrid/useDragReorder.ts
 import {
   useRef as useRef3,
   useState as useState2
 } from "react";
-import {
-  movesColumn,
-  resolveDropBefore,
-  resolveKeyboardDropTarget
-} from "@gridkitjs/core";
 
 // src/DataGrid/pointerGesture.ts
 function startPointerGesture(element, pointerId, handlers) {
@@ -737,21 +1238,20 @@ function startPointerGesture(element, pointerId, handlers) {
   window.addEventListener("keydown", onKeyDown);
 }
 
-// src/DataGrid/useColumnDrag.ts
+// src/DataGrid/useDragReorder.ts
 var DRAG_THRESHOLD = 4;
-function headerAt(x, y) {
-  const element = document.elementFromPoint(x, y);
-  return element?.closest("th[data-gridkit-column]") ?? null;
+function elementAt(x, y, selector) {
+  return document.elementFromPoint(x, y)?.closest(selector) ?? null;
 }
 function sideOf(element, x) {
   const rect = element.getBoundingClientRect();
   return x < rect.left + rect.width / 2 ? "before" : "after";
 }
-function useColumnDrag({
-  order,
+function useDragReorder({
+  resolveTarget,
   onDrop
 }) {
-  const [draggedColumnId, setDraggedColumnId] = useState2(null);
+  const [draggedId, setDraggedId] = useState2(null);
   const [dropTarget, setDropTarget] = useState2(null);
   const [ghostTransform, setGhostTransform] = useState2(null);
   const dragged = useRef3(false);
@@ -760,10 +1260,9 @@ function useColumnDrag({
     dragged.current = false;
     return answer;
   }
-  function startDrag(entry, event) {
-    const header = event.currentTarget;
+  function startDrag(id, grabElement, event) {
     const { pointerId, clientX: startX } = event;
-    const grabX = startX - header.getBoundingClientRect().left;
+    const grabX = startX - grabElement.getBoundingClientRect().left;
     let dragging = false;
     let target = null;
     function placeGhost(x, y) {
@@ -771,10 +1270,10 @@ function useColumnDrag({
     }
     function reset() {
       setGhostTransform(null);
-      setDraggedColumnId(null);
+      setDraggedId(null);
       setDropTarget(null);
     }
-    startPointerGesture(header, pointerId, {
+    startPointerGesture(grabElement, pointerId, {
       onMove(moveEvent) {
         const { clientX, clientY } = moveEvent;
         if (!dragging) {
@@ -783,20 +1282,17 @@ function useColumnDrag({
           }
           dragging = true;
           dragged.current = true;
-          setDraggedColumnId(entry.id);
+          setDraggedId(id);
         }
         placeGhost(clientX, clientY);
-        const over = headerAt(clientX, clientY);
-        const overId = over?.getAttribute("data-gridkit-column");
-        const beforeId = over && overId ? resolveDropBefore(order, overId, sideOf(over, clientX)) : void 0;
-        target = beforeId !== void 0 && movesColumn(order, entry.id, beforeId) ? { kind: "column-order", beforeId } : null;
+        target = resolveTarget(clientX, clientY, id);
         setDropTarget(target);
       },
       onEnd() {
         const dropped = target;
         reset();
         if (dragging && dropped !== null) {
-          onDrop(dropped, entry.id);
+          onDrop(dropped, id);
         }
       },
       // Escape and a cancelled pointer both leave the order as it was.
@@ -806,20 +1302,214 @@ function useColumnDrag({
       }
     });
   }
+  return {
+    draggedId,
+    dropTarget,
+    ghostTransform,
+    startDrag,
+    justDragged
+  };
+}
+
+// src/DataGrid/groupByDropTarget.ts
+function resolveGroupByDropTarget(clientX, clientY, movedId, groupBy) {
+  const overBar = elementAt(clientX, clientY, "[data-gridkit-group-by-bar]");
+  if (overBar === null) {
+    return null;
+  }
+  const overChip = elementAt(clientX, clientY, "[data-gridkit-group-chip]");
+  const chipId = overChip?.getAttribute("data-gridkit-group-chip");
+  const beforeColumnId = overChip && chipId ? resolveDropBefore(
+    groupBy.map((entry) => entry.columnId),
+    chipId,
+    sideOf(overChip, clientX)
+  ) : null;
+  return movesGroupBy(groupBy, movedId, beforeColumnId) ? { kind: "group-by", beforeColumnId } : null;
+}
+
+// src/DataGrid/useGroupByDrag.ts
+function useGroupByDrag({
+  groupBy,
+  onDrop
+}) {
+  const drag = useDragReorder({
+    resolveTarget: (clientX, clientY, movedId) => resolveGroupByDropTarget(clientX, clientY, movedId, groupBy),
+    onDrop: (target, movedId) => {
+      onDrop(movedId, target.beforeColumnId);
+    }
+  });
+  return {
+    draggedColumnId: drag.draggedId,
+    dropTarget: drag.dropTarget,
+    ghostTransform: drag.ghostTransform,
+    startDrag: (columnId, event) => {
+      drag.startDrag(columnId, event.currentTarget, event);
+    },
+    justDragged: drag.justDragged
+  };
+}
+
+// src/DataGrid/components/GroupByBar.tsx
+import { jsx as jsx8, jsxs as jsxs5 } from "react/jsx-runtime";
+function GroupByBar({
+  columns,
+  grouping,
+  columnName,
+  headerDragEligible,
+  headerDragBlocked,
+  headerDropTarget
+}) {
+  const { groupBy } = grouping;
+  const groupByIds = groupBy.map((entry) => entry.columnId);
+  const chipDrag = useGroupByDrag({
+    groupBy,
+    onDrop: (movedId, beforeColumnId) => {
+      grouping.moveGroupBy(movedId, beforeColumnId);
+    }
+  });
+  const activeDropTarget = chipDrag.dropTarget ?? headerDropTarget;
+  const isDragTarget = chipDrag.draggedColumnId !== null || headerDragEligible;
+  const showPlaceholder = groupBy.length === 0 && columns.some((entry) => entry.groupByDraggable);
+  function labelFor(columnId) {
+    return columns.find((entry) => entry.id === columnId)?.label ?? columnId;
+  }
+  function moveByKeyboard(columnId, direction) {
+    const beforeColumnId = resolveKeyboardDropTarget(
+      groupByIds,
+      columnId,
+      direction
+    );
+    if (beforeColumnId === void 0) {
+      return;
+    }
+    grouping.moveGroupBy(columnId, beforeColumnId);
+  }
+  return /* @__PURE__ */ jsxs5(
+    "div",
+    {
+      className: classNames(
+        "gridkit-group-by-bar",
+        isDragTarget ? "is-drag-target" : "",
+        headerDragBlocked ? "is-drag-blocked" : ""
+      ),
+      "data-gridkit-group-by-bar": "",
+      role: "group",
+      "aria-label": "Grouped by",
+      children: [
+        showPlaceholder && /* @__PURE__ */ jsx8("span", { className: "group-by-bar-placeholder", children: "Drag a column here to group by it" }),
+        groupBy.map((entry, index) => {
+          const dropBefore = activeDropTarget?.beforeColumnId === entry.columnId;
+          const dropAfter = activeDropTarget?.beforeColumnId === null && index === groupBy.length - 1;
+          const dragging = chipDrag.draggedColumnId === entry.columnId;
+          return /* @__PURE__ */ jsxs5(
+            "span",
+            {
+              className: classNames(
+                "group-by-chip",
+                dragging ? "is-dragging" : "",
+                dropBefore ? "is-drop-before" : "",
+                dropAfter ? "is-drop-after" : ""
+              ),
+              "data-gridkit-group-chip": entry.columnId,
+              tabIndex: 0,
+              "aria-label": groupBy.length > 1 ? `${columnName(entry.columnId)}, level ${String(index + 1)} of ${String(groupBy.length)}` : columnName(entry.columnId),
+              "aria-keyshortcuts": "Control+ArrowLeft Control+ArrowRight",
+              onPointerDown: (event) => {
+                chipDrag.startDrag(entry.columnId, event);
+              },
+              onKeyDown: (event) => {
+                const horizontal = event.key === "ArrowLeft" || event.key === "ArrowRight";
+                if (horizontal && event.ctrlKey) {
+                  event.preventDefault();
+                  moveByKeyboard(
+                    entry.columnId,
+                    event.key === "ArrowLeft" ? -1 : 1
+                  );
+                }
+              },
+              children: [
+                /* @__PURE__ */ jsx8("span", { className: "group-by-chip-label", children: labelFor(entry.columnId) }),
+                /* @__PURE__ */ jsx8(
+                  "button",
+                  {
+                    type: "button",
+                    className: "group-by-chip-remove",
+                    "aria-label": `Stop grouping by ${columnName(entry.columnId)}`,
+                    onPointerDown: (event) => {
+                      event.stopPropagation();
+                    },
+                    onClick: () => {
+                      grouping.toggleGroupBy(entry.columnId);
+                    },
+                    children: "\xD7"
+                  }
+                )
+              ]
+            },
+            entry.columnId
+          );
+        }),
+        chipDrag.draggedColumnId !== null && chipDrag.ghostTransform !== null && createPortal2(
+          /* @__PURE__ */ jsx8(
+            "span",
+            {
+              className: "group-by-chip drag-ghost",
+              style: { transform: chipDrag.ghostTransform },
+              "aria-hidden": "true",
+              children: labelFor(chipDrag.draggedColumnId)
+            }
+          ),
+          document.body
+        )
+      ]
+    }
+  );
+}
+
+// src/DataGrid/useColumnDrag.ts
+import {
+  movesColumn,
+  resolveDropBefore as resolveDropBefore2,
+  resolveKeyboardDropTarget as resolveKeyboardDropTarget2
+} from "@gridkitjs/core";
+function useColumnDrag({
+  order,
+  groupBy,
+  groupByDraggableIds,
+  onDrop
+}) {
+  const drag = useDragReorder({
+    resolveTarget(clientX, clientY, movedId) {
+      const over = elementAt(clientX, clientY, "th[data-gridkit-column]");
+      const overId = over?.getAttribute("data-gridkit-column");
+      const beforeId = over && overId ? resolveDropBefore2(order, overId, sideOf(over, clientX)) : void 0;
+      if (beforeId !== void 0) {
+        return movesColumn(order, movedId, beforeId) ? { kind: "column-order", beforeId } : null;
+      }
+      const alreadyGrouped = groupBy.some(
+        (entry) => entry.columnId === movedId
+      );
+      return groupByDraggableIds.has(movedId) && !alreadyGrouped ? resolveGroupByDropTarget(clientX, clientY, movedId, groupBy) : null;
+    },
+    onDrop
+  });
+  function startDrag(entry, event) {
+    drag.startDrag(entry.id, event.currentTarget, event);
+  }
   function moveByKeyboard(entry, direction) {
-    const beforeId = resolveKeyboardDropTarget(order, entry.id, direction);
+    const beforeId = resolveKeyboardDropTarget2(order, entry.id, direction);
     if (beforeId === void 0) {
       return;
     }
     onDrop({ kind: "column-order", beforeId }, entry.id);
   }
   return {
-    draggedColumnId,
-    dropTarget,
-    ghostTransform,
+    draggedColumnId: drag.draggedId,
+    dropTarget: drag.dropTarget,
+    ghostTransform: drag.ghostTransform,
     startDrag,
     moveByKeyboard,
-    justDragged
+    justDragged: drag.justDragged
   };
 }
 
@@ -994,8 +1684,110 @@ function useElementWidth(ref, enabled) {
   return width;
 }
 
+// src/DataGrid/usePagination.ts
+import {
+  paginateRows
+} from "@gridkitjs/core";
+function usePagination({
+  pagination,
+  setPagination,
+  rows,
+  onPaginationChange
+}) {
+  const { pageCount, pageIndex } = paginateRows(rows, pagination);
+  function commit(next) {
+    commitIfChanged(pagination, next, setPagination, (committed) => {
+      const { pageCount: committedPageCount } = paginateRows(rows, committed);
+      onPaginationChange?.({
+        pagination: committed,
+        pageCount: committedPageCount
+      });
+    });
+  }
+  function goToPage(nextPageIndex) {
+    const { pageIndex: clamped } = paginateRows(rows, {
+      ...pagination,
+      pageIndex: nextPageIndex
+    });
+    commit({ ...pagination, pageIndex: clamped });
+  }
+  return {
+    pagination,
+    pageCount,
+    currentPage: Math.min(pagination.pageIndex + 1, pageCount),
+    goToPage,
+    nextPage: () => {
+      goToPage(pageIndex + 1);
+    },
+    previousPage: () => {
+      goToPage(pageIndex - 1);
+    },
+    setPageSize: (pageSize) => {
+      const next = { pageIndex: 0, pageSize };
+      const { pageIndex: clamped } = paginateRows(rows, next);
+      commit({ ...next, pageIndex: clamped });
+    }
+  };
+}
+
+// src/DataGrid/useRowGrouping.ts
+import {
+  collapseAllGroups,
+  expandAllGroups,
+  moveGroupByBefore,
+  toggleGroupExpansion
+} from "@gridkitjs/core";
+function useRowGrouping({
+  groupBy,
+  setGroupBy,
+  expansion,
+  setExpansion,
+  onGroupByChange,
+  onGroupExpansionChange
+}) {
+  function commitExpansion(next, groupId) {
+    commitIfChanged(expansion, next, setExpansion, (committed) => {
+      onGroupExpansionChange?.({ groupId, expansion: committed });
+    });
+  }
+  function commitGroupBy(next, columnId) {
+    commitIfChanged(groupBy, next, setGroupBy, (committed) => {
+      onGroupByChange?.({ columnId, groupBy: committed });
+    });
+  }
+  function toggleGroupBy(columnId) {
+    const isGrouped = groupBy.some((entry) => entry.columnId === columnId);
+    const next = isGrouped ? groupBy.filter((entry) => entry.columnId !== columnId) : [...groupBy, { columnId }];
+    commitGroupBy(next, columnId);
+  }
+  function moveGroupBy(columnId, beforeColumnId) {
+    commitGroupBy(
+      moveGroupByBefore(groupBy, columnId, beforeColumnId),
+      columnId
+    );
+  }
+  return {
+    groupBy,
+    expansion,
+    isExpanded: (groupId) => !expansion.includes(groupId),
+    toggleExpansion: (groupId) => {
+      commitExpansion(toggleGroupExpansion(expansion, groupId), groupId);
+    },
+    expandAll: () => {
+      commitExpansion(expandAllGroups(expansion), null);
+    },
+    collapseAll: (rows) => {
+      commitExpansion(collapseAllGroups(rows), null);
+    },
+    toggleGroupBy,
+    moveGroupBy
+  };
+}
+
 // src/DataGrid/DataGrid.tsx
-import { jsx as jsx4, jsxs as jsxs2 } from "react/jsx-runtime";
+import { jsx as jsx9, jsxs as jsxs6 } from "react/jsx-runtime";
+var DEFAULT_PAGE_SIZE = 25;
+var NO_AGGREGATES = [];
 function DataGridComponent({
   dataSource,
   columns,
@@ -1017,7 +1809,21 @@ function DataGridComponent({
   sortableColumns = false,
   defaultColumnSort,
   onColumnSortChange,
+  groupableColumns = false,
+  groupToggleIconColumns = true,
+  groupByDraggableColumns = false,
+  groupByBarVisibility = "auto",
+  defaultGroupBy,
+  onGroupByChange,
+  defaultGroupExpansion,
+  onGroupExpansionChange,
   defaultFilter,
+  paginated = false,
+  defaultPagination,
+  pager,
+  onPaginationChange,
+  aggregates,
+  groupAggregateDisplay = "inline",
   label,
   labelledBy,
   ref,
@@ -1029,6 +1835,7 @@ function DataGridComponent({
   const viewportRef = useRef4(null);
   const tableRef = useRef4(null);
   const viewportWidth = useElementWidth(viewportRef, resizeMode === "fit");
+  const subscribersRef = useRef4(/* @__PURE__ */ new Set());
   const [sizing, setSizing] = useState5(
     defaultColumnSizing ?? {}
   );
@@ -1036,7 +1843,14 @@ function DataGridComponent({
     defaultColumnOrder ?? []
   );
   const [sort, setSort] = useState5(defaultColumnSort ?? []);
+  const [groupBy, setGroupBy] = useState5(defaultGroupBy ?? []);
+  const [expansion, setExpansion] = useState5(
+    defaultGroupExpansion ?? []
+  );
   const [filter] = useState5(defaultFilter ?? []);
+  const [pagination, setPagination] = useState5(
+    defaultPagination ?? { pageIndex: 0, pageSize: DEFAULT_PAGE_SIZE }
+  );
   const [announcement, setAnnouncement] = useState5("");
   const [rowSelection, setRowSelection] = useState5(
     defaultRowSelection ?? []
@@ -1047,29 +1861,31 @@ function DataGridComponent({
   const [cellSelection, setCellSelection] = useState5(
     defaultCellSelection ?? null
   );
-  const rows = useMemo2(
+  const rows = useMemo4(
     () => dataSource?.map((row, rowIndex) => ({
       rowId: resolveRowId(row, rowIndex, getRowId),
       row,
-      rowIndex
+      rowIndex,
+      datasetIndex: rowIndex
     })) ?? [],
     [dataSource, getRowId]
   );
-  const definedColumns = useMemo2(() => {
+  const definedColumns = useMemo4(() => {
     if (columns && columns.length !== 0) return columns;
     if (dataSource && dataSource.length > 0)
       return defineColumnsFromRows(dataSource);
     return [];
   }, [columns, dataSource]);
-  const orderedColumns = useMemo2(
+  const orderedColumns = useMemo4(
     () => applyColumnOrder(definedColumns, order),
     [definedColumns, order]
   );
-  const resolved = useMemo2(() => {
+  const resolved = useMemo4(() => {
     const widths = resolveColumnWidths(orderedColumns, sizing, {
       sizes: columnSizeDefaults,
       resizable: resizableColumns,
-      reorderable: reorderableColumns
+      reorderable: reorderableColumns,
+      groupByDraggable: groupByDraggableColumns
     });
     return resizeMode === "fit" && viewportWidth !== null ? fitColumnsToWidth(widths, viewportWidth, columnSizeDefaults) : widths;
   }, [
@@ -1079,12 +1895,61 @@ function DataGridComponent({
     viewportWidth,
     columnSizeDefaults,
     resizableColumns,
-    reorderableColumns
+    reorderableColumns,
+    groupByDraggableColumns
   ]);
-  const shownRows = useMemo2(
+  const shownRows = useMemo4(
     () => resolveShownRows(rows, filter, sort, resolved),
     [rows, filter, sort, resolved]
   );
+  const displayRows = useMemo4(
+    () => groupRows(shownRows, groupBy, expansion, resolved),
+    [shownRows, groupBy, expansion, resolved]
+  );
+  const activeAggregates = aggregates ?? NO_AGGREGATES;
+  const aggregatedRows = useMemo4(
+    () => withGroupAggregates(
+      displayRows,
+      shownRows,
+      groupBy,
+      activeAggregates,
+      resolved,
+      groupAggregateDisplay
+    ),
+    [
+      displayRows,
+      shownRows,
+      groupBy,
+      activeAggregates,
+      resolved,
+      groupAggregateDisplay
+    ]
+  );
+  const grandTotal = useMemo4(
+    () => computeAggregates(
+      shownRows.map((entry) => entry.row),
+      activeAggregates,
+      resolved
+    ),
+    [shownRows, activeAggregates, resolved]
+  );
+  const paginatedRows = useMemo4(
+    () => paginated ? paginateRows2(aggregatedRows, pagination) : { rows: aggregatedRows, pageCount: 1, pageIndex: 0 },
+    [paginated, aggregatedRows, pagination]
+  );
+  const paginationSnapshot = useMemo4(
+    () => ({
+      pageIndex: paginatedRows.pageIndex,
+      pageSize: pagination.pageSize
+    }),
+    [paginatedRows.pageIndex, pagination.pageSize]
+  );
+  const displayDataRows = useMemo4(
+    () => groupBy.length === 0 && !paginated ? shownRows : paginatedRows.rows.filter(
+      (entry) => !("kind" in entry)
+    ),
+    [paginatedRows, groupBy.length, paginated, shownRows]
+  );
   function columnName(columnId) {
     const entry = resolved.find((candidate) => candidate.id === columnId);
     if (entry === void 0) {
@@ -1110,16 +1975,73 @@ function DataGridComponent({
     columnSizeDefaults,
     onColumnResize: handleColumnResize
   });
+  function handleGroupByChange(event) {
+    onGroupByChange?.(event);
+    const entry = event.groupBy.find(
+      (candidate) => candidate.columnId === event.columnId
+    );
+    if (entry === void 0) {
+      announce(`${columnName(event.columnId)}, grouping removed`);
+      return;
+    }
+    announce(
+      event.groupBy.length > 1 ? `Grouped by ${columnName(event.columnId)}, level ${String(event.groupBy.indexOf(entry) + 1)} of ${String(event.groupBy.length)}` : `Grouped by ${columnName(event.columnId)}`
+    );
+  }
+  function handleGroupExpansionChange(event) {
+    onGroupExpansionChange?.(event);
+    if (event.groupId === null) {
+      announce(
+        event.expansion.length === 0 ? "All groups expanded" : "All groups collapsed"
+      );
+      return;
+    }
+    announce(
+      event.expansion.includes(event.groupId) ? "Group collapsed" : "Group expanded"
+    );
+  }
+  const grouping = useRowGrouping({
+    groupBy,
+    setGroupBy,
+    expansion,
+    setExpansion,
+    onGroupByChange: handleGroupByChange,
+    onGroupExpansionChange: handleGroupExpansionChange
+  });
   const nav = useGridNavigation({
     tableRef,
-    rowCount: shownRows.length,
-    columnCount: resolved.length
+    // Group headers are addressable rows too — the whole point of the flat
+    // `DisplayRow[]` shape is that they share one position space with data
+    // rows, so navigation counts them the same way. Page-relative
+    // (`paginatedRows`, not `displayRows`): arrow keys operate on what's
+    // actually in the DOM, which is the current page — a different "page"
+    // concept than `useGridNavigation`'s own Page Up/Down viewport scrolling.
+    rowCount: paginatedRows.rows.length,
+    columnCount: resolved.length,
+    // A group's own summary row (`groupAggregateDisplay: "row"`) occupies a
+    // real slot in `rowCount` above — its DOM position has to line up with
+    // everything else — but is presentational, never a tab stop: arrow-key
+    // vertical movement steps over it rather than landing there.
+    isSkippableRow: (rowIndex) => {
+      const entry = paginatedRows.rows[rowIndex];
+      return entry !== void 0 && "kind" in entry && entry.kind === "group-summary";
+    }
   });
-  const displayedIds = useMemo2(
+  const displayedIds = useMemo4(
     () => orderedColumns.map((column) => column.id ?? column.field),
     [orderedColumns]
   );
+  const groupByDraggableIds = useMemo4(
+    () => new Set(
+      resolved.filter((entry) => entry.groupByDraggable).map((entry) => entry.id)
+    ),
+    [resolved]
+  );
   function handleDrop(target, movedId) {
+    if (target.kind === "group-by") {
+      grouping.moveGroupBy(movedId, target.beforeColumnId);
+      return;
+    }
     const next = moveColumnBefore(displayedIds, movedId, target.beforeId);
     if (next === displayedIds) {
       return;
@@ -1132,7 +2054,16 @@ function DataGridComponent({
     );
     nav.focusCell(HEADER_ROW, position);
   }
-  const drag = useColumnDrag({ order: displayedIds, onDrop: handleDrop });
+  const drag = useColumnDrag({
+    order: displayedIds,
+    groupBy,
+    groupByDraggableIds,
+    onDrop: handleDrop
+  });
+  const draggedColumnAlreadyGrouped = drag.draggedColumnId !== null && groupBy.some((entry) => entry.columnId === drag.draggedColumnId);
+  const dragEligibleForGroupBy = drag.draggedColumnId !== null && groupByDraggableIds.has(drag.draggedColumnId) && !draggedColumnAlreadyGrouped;
+  const showGroupByBar = groupByBarVisibility === "always" || groupByBarVisibility === "auto" && (groupBy.length > 0 || dragEligibleForGroupBy);
+  const headerGroupByDropTarget = drag.dropTarget?.kind === "group-by" ? drag.dropTarget : null;
   function handleColumnSortChange(event) {
     onColumnSortChange?.(event);
     const entry = event.sort.find(
@@ -1152,8 +2083,27 @@ function DataGridComponent({
     setSort,
     onColumnSortChange: handleColumnSortChange
   });
+  function handlePaginationChange(event) {
+    onPaginationChange?.(event);
+    announce(
+      `Page ${String(event.pagination.pageIndex + 1)} of ${String(event.pageCount)}`
+    );
+  }
+  const paginationApi = usePagination({
+    pagination,
+    setPagination,
+    rows: displayRows,
+    onPaginationChange: handlePaginationChange
+  });
+  const [previous, setPrevious] = useState5({ filter, sort, groupBy });
+  if (previous.filter !== filter || previous.sort !== sort || previous.groupBy !== groupBy) {
+    setPrevious({ filter, sort, groupBy });
+    if (pagination.pageIndex !== 0) {
+      setPagination({ ...pagination, pageIndex: 0 });
+    }
+  }
   const selection = useGridSelection({
-    rows: shownRows,
+    rows: displayDataRows,
     columns: resolved,
     selectable,
     rowSelection,
@@ -1167,6 +2117,27 @@ function DataGridComponent({
     columnName
   });
   const multiselectable = selection.rowMode === "multiple" || selection.columnMode === "multiple";
+  useEffect2(() => {
+    for (const listener of subscribersRef.current) {
+      listener();
+    }
+  }, [
+    shownRows,
+    aggregatedRows,
+    resolved,
+    sizing,
+    order,
+    sort,
+    groupBy,
+    expansion,
+    paginationSnapshot,
+    paginatedRows.pageCount,
+    grandTotal,
+    rowSelection,
+    columnSelection,
+    cellSelection,
+    nav.focus
+  ]);
   useImperativeHandle(ref, () => ({
     get element() {
       return viewportRef.current;
@@ -1175,10 +2146,20 @@ function DataGridComponent({
       return tableRef.current;
     },
     getRows: () => shownRows,
+    // `aggregatedRows`, not the plain `displayRows` it's derived from: the
+    // same array shape and content, except every group header's own
+    // `aggregates` field is populated — the whole reason `getDisplayRows()`
+    // is where a consumer reads a specific group's computed results from.
+    getDisplayRows: () => aggregatedRows,
     getColumns: () => resolved,
     getColumnSizing: () => sizing,
     getColumnOrder: () => order,
     getColumnSort: () => sort,
+    getGroupBy: () => groupBy,
+    getGroupExpansion: () => expansion,
+    getPagination: () => paginationSnapshot,
+    getPageCount: () => paginatedRows.pageCount,
+    getAggregates: () => grandTotal,
     getRowSelection: () => rowSelection,
     getColumnSelection: () => columnSelection,
     getCellSelection: () => cellSelection,
@@ -1186,8 +2167,18 @@ function DataGridComponent({
     focusCell: nav.focusCell,
     clearSelection: selection.clear,
     selectAllRows: selection.selectAllRows,
+    expandAllGroups: grouping.expandAll,
+    collapseAllGroups: () => {
+      grouping.collapseAll(displayRows);
+    },
+    goToPage: paginationApi.goToPage,
+    nextPage: paginationApi.nextPage,
+    previousPage: paginationApi.previousPage,
+    setPageSize: paginationApi.setPageSize,
     scrollToRow: (rowId, options) => {
-      const index = shownRows.findIndex((entry) => entry.rowId === rowId);
+      const index = paginatedRows.rows.findIndex(
+        (entry) => !("kind" in entry) && entry.rowId === rowId
+      );
       if (index === -1) return;
       tableRef.current?.tBodies[0]?.rows[index]?.scrollIntoView(options);
     },
@@ -1197,15 +2188,32 @@ function DataGridComponent({
         (entry) => entry.getAttribute("data-gridkit-column") === columnId
       ) : void 0;
       cell?.scrollIntoView(options);
+    },
+    subscribe: (listener) => {
+      subscribersRef.current.add(listener);
+      return () => {
+        subscribersRef.current.delete(listener);
+      };
     }
   }));
-  return /* @__PURE__ */ jsxs2("div", { className: "gridkit-data-grid-viewport", ref: viewportRef, children: [
-    /* @__PURE__ */ jsxs2(
+  return /* @__PURE__ */ jsxs6("div", { className: "gridkit-data-grid-viewport", ref: viewportRef, children: [
+    showGroupByBar && /* @__PURE__ */ jsx9(
+      GroupByBar,
+      {
+        columns: resolved,
+        grouping,
+        columnName,
+        headerDragEligible: dragEligibleForGroupBy,
+        headerDragBlocked: draggedColumnAlreadyGrouped,
+        headerDropTarget: headerGroupByDropTarget
+      }
+    ),
+    /* @__PURE__ */ jsxs6(
       "table",
       {
         ref: tableRef,
-        role: "grid",
-        "aria-rowcount": shownRows.length + 1,
+        role: groupBy.length > 0 ? "treegrid" : "grid",
+        "aria-rowcount": aggregatedRows.length + 1,
         "aria-colcount": resolved.length,
         ...ariaAttr(multiselectable, "aria-multiselectable", true),
         ...ariaAttr(labelledBy !== void 0, "aria-labelledby", labelledBy),
@@ -1242,8 +2250,8 @@ function DataGridComponent({
           selection.cellMode === false ? "" : "selectable-cells"
         ),
         children: [
-          /* @__PURE__ */ jsx4("colgroup", { children: resolved.map((entry) => /* @__PURE__ */ jsx4("col", { style: { width: entry.width } }, entry.id)) }),
-          /* @__PURE__ */ jsx4(
+          /* @__PURE__ */ jsx9("colgroup", { children: resolved.map((entry) => /* @__PURE__ */ jsx9("col", { style: { width: entry.width } }, entry.id)) }),
+          /* @__PURE__ */ jsx9(
             GridHeader,
             {
               columns: resolved,
@@ -1251,27 +2259,217 @@ function DataGridComponent({
               drag,
               sort: columnSort,
               sortableColumns,
+              grouping,
+              groupableColumns,
+              groupToggleIconColumns,
               nav,
               selection
             }
           ),
-          /* @__PURE__ */ jsx4(
+          /* @__PURE__ */ jsx9(
             GridBody,
             {
               columns: resolved,
-              rows: shownRows,
+              rows: paginatedRows.rows,
               activeColumnId: resize.activeColumnId,
               nav,
-              selection
+              selection,
+              grouping,
+              aggregates: activeAggregates,
+              groupAggregateDisplay
+            }
+          ),
+          activeAggregates.length > 0 && /* @__PURE__ */ jsx9(
+            GridFooter,
+            {
+              columns: resolved,
+              aggregates: activeAggregates,
+              results: grandTotal,
+              rows: shownRows.map((entry) => entry.row)
             }
           )
         ]
       }
     ),
-    /* @__PURE__ */ jsx4("div", { className: "gridkit-sr-only", role: "status", "aria-live": "polite", children: announcement })
+    paginated && (pager?.template ? pager.template({
+      pagination: paginationApi.pagination,
+      currentPage: paginationApi.currentPage,
+      pageCount: paginationApi.pageCount,
+      pageSizeOptions: pager.sizeOptions,
+      goToPage: paginationApi.goToPage,
+      nextPage: paginationApi.nextPage,
+      previousPage: paginationApi.previousPage,
+      setPageSize: paginationApi.setPageSize
+    }) : /* @__PURE__ */ jsx9(GridPager, { pager: paginationApi, config: pager })),
+    /* @__PURE__ */ jsx9("div", { className: "gridkit-sr-only", role: "status", "aria-live": "polite", children: announcement })
   ] });
 }
+
+// src/DataGrid/hooks/usePaginationState.ts
+import { useCallback as useCallback2 } from "react";
+
+// src/DataGrid/hooks/useGridSnapshot.ts
+import { useCallback, useSyncExternalStore } from "react";
+function useGridSnapshot(gridRef, getSnapshot, fallback) {
+  const subscribe = useCallback(
+    (listener) => {
+      const api = gridRef.current;
+      if (api === null) {
+        return () => {
+        };
+      }
+      return api.subscribe(listener);
+    },
+    [gridRef]
+  );
+  return useSyncExternalStore(subscribe, () => {
+    const api = gridRef.current;
+    return api === null ? fallback : getSnapshot(api);
+  });
+}
+
+// src/DataGrid/hooks/usePaginationState.ts
+var FALLBACK_PAGINATION = { pageIndex: 0, pageSize: 0 };
+function usePaginationState(gridRef) {
+  const pagination = useGridSnapshot(
+    gridRef,
+    useCallback2((api) => api.getPagination(), []),
+    FALLBACK_PAGINATION
+  );
+  const pageCount = useGridSnapshot(
+    gridRef,
+    useCallback2((api) => api.getPageCount(), []),
+    0
+  );
+  return {
+    pagination,
+    pageCount,
+    goToPage: (pageIndex) => {
+      gridRef.current?.goToPage(pageIndex);
+    },
+    nextPage: () => {
+      gridRef.current?.nextPage();
+    },
+    previousPage: () => {
+      gridRef.current?.previousPage();
+    },
+    setPageSize: (pageSize) => {
+      gridRef.current?.setPageSize(pageSize);
+    }
+  };
+}
+
+// src/DataGrid/hooks/useGroupByState.ts
+import { useCallback as useCallback3 } from "react";
+var FALLBACK_GROUP_BY = [];
+var FALLBACK_EXPANSION = [];
+function useGroupByState(gridRef) {
+  const groupBy = useGridSnapshot(
+    gridRef,
+    useCallback3((api) => api.getGroupBy(), []),
+    FALLBACK_GROUP_BY
+  );
+  const groupExpansion = useGridSnapshot(
+    gridRef,
+    useCallback3((api) => api.getGroupExpansion(), []),
+    FALLBACK_EXPANSION
+  );
+  return {
+    groupBy,
+    groupExpansion,
+    expandAllGroups: () => {
+      gridRef.current?.expandAllGroups();
+    },
+    collapseAllGroups: () => {
+      gridRef.current?.collapseAllGroups();
+    }
+  };
+}
+
+// src/DataGrid/hooks/useColumnSortState.ts
+import { useCallback as useCallback4 } from "react";
+var FALLBACK_SORT = [];
+function useColumnSortState(gridRef) {
+  return useGridSnapshot(
+    gridRef,
+    useCallback4((api) => api.getColumnSort(), []),
+    FALLBACK_SORT
+  );
+}
+
+// src/DataGrid/hooks/useSelectionState.ts
+import { useCallback as useCallback5 } from "react";
+var FALLBACK_SELECTION = [];
+var FALLBACK_CELL_SELECTION = null;
+function useSelectionState(gridRef) {
+  const rowSelection = useGridSnapshot(
+    gridRef,
+    useCallback5((api) => api.getRowSelection(), []),
+    FALLBACK_SELECTION
+  );
+  const columnSelection = useGridSnapshot(
+    gridRef,
+    useCallback5((api) => api.getColumnSelection(), []),
+    FALLBACK_SELECTION
+  );
+  const cellSelection = useGridSnapshot(
+    gridRef,
+    useCallback5((api) => api.getCellSelection(), []),
+    FALLBACK_CELL_SELECTION
+  );
+  return {
+    rowSelection,
+    columnSelection,
+    cellSelection,
+    clearSelection: () => {
+      gridRef.current?.clearSelection();
+    },
+    selectAllRows: () => {
+      gridRef.current?.selectAllRows();
+    }
+  };
+}
+
+// src/DataGrid/hooks/useAggregateState.ts
+import { useCallback as useCallback6 } from "react";
+var FALLBACK_AGGREGATES = /* @__PURE__ */ new Map();
+function useAggregateState(gridRef) {
+  return useGridSnapshot(
+    gridRef,
+    useCallback6((api) => api.getAggregates(), []),
+    FALLBACK_AGGREGATES
+  );
+}
+
+// src/DataGrid/hooks/useColumnSizingState.ts
+import { useCallback as useCallback7 } from "react";
+var FALLBACK_SIZING = {};
+function useColumnSizingState(gridRef) {
+  return useGridSnapshot(
+    gridRef,
+    useCallback7((api) => api.getColumnSizing(), []),
+    FALLBACK_SIZING
+  );
+}
+
+// src/DataGrid/hooks/useColumnOrderState.ts
+import { useCallback as useCallback8 } from "react";
+var FALLBACK_ORDER = [];
+function useColumnOrderState(gridRef) {
+  return useGridSnapshot(
+    gridRef,
+    useCallback8((api) => api.getColumnOrder(), []),
+    FALLBACK_ORDER
+  );
+}
 export {
-  DataGridComponent
+  DataGridComponent,
+  useAggregateState,
+  useColumnOrderState,
+  useColumnSizingState,
+  useColumnSortState,
+  useGroupByState,
+  usePaginationState,
+  useSelectionState
 };
 //# sourceMappingURL=index.js.map