@gridkitjs/react 0.4.0 → 0.6.0

package/dist/index.js

@@ -1,5 +1,10 @@
 // src/DataGrid/DataGrid.tsx
-import { useMemo as useMemo2, useRef as useRef4, useState as useState5 } from "react";
+import {
+  useImperativeHandle,
+  useMemo as useMemo2,
+  useRef as useRef4,
+  useState as useState5
+} from "react";
 import {
   applyColumnOrder,
   defineColumnsFromRows,
@@ -7,12 +12,23 @@ import {
   moveColumnBefore,
   resolveColumnWidths,
   resolveRowId,
+  resolveShownRows,
   totalColumnWidth
 } from "@gridkitjs/core";
 
 // src/DataGrid/components/GridHeader.tsx
 import { createPortal } from "react-dom";
-import { KEYBOARD_STEP } from "@gridkitjs/core";
+import { buildKeyShortcuts, intentOf, KEYBOARD_STEP } from "@gridkitjs/core";
+
+// src/DataGrid/ariaAttr.ts
+function ariaAttr(condition, key, value) {
+  return condition ? { [key]: value } : {};
+}
+
+// src/DataGrid/classNames.ts
+function classNames(...values) {
+  return values.filter(Boolean).join(" ");
+}
 
 // src/DataGrid/useGridNavigation.ts
 import {
@@ -20,16 +36,14 @@ import {
   useRef,
   useState
 } from "react";
-var HEADER_ROW = -1;
+import {
+  clampFocus,
+  nextFocusForKey,
+  HEADER_ROW
+} from "@gridkitjs/core";
 var FALLBACK_PAGE = 10;
-function clampFocus(focus, rowCount, columnCount) {
-  return {
-    rowIndex: Math.min(Math.max(focus.rowIndex, HEADER_ROW), rowCount - 1),
-    columnIndex: Math.min(
-      Math.max(focus.columnIndex, 0),
-      Math.max(columnCount - 1, 0)
-    )
-  };
+function tabIndexFor(columnIndex, focusedColumnIndex) {
+  return columnIndex === focusedColumnIndex ? 0 : -1;
 }
 function cellAt(table, focus) {
   const row = focus.rowIndex === HEADER_ROW ? table.tHead?.rows[0] ?? null : table.tBodies[0]?.rows[focus.rowIndex] ?? null;
@@ -77,83 +91,71 @@ function useGridNavigation({
     pending.current = true;
     setStored(next);
   }
-  function tabIndexFor(rowIndex, columnIndex) {
-    return rowIndex === focus.rowIndex && columnIndex === focus.columnIndex ? 0 : -1;
-  }
   function onKeyDown(event) {
-    if (event.altKey) {
+    const next = nextFocusForKey(
+      event.key,
+      {
+        ctrlKey: event.ctrlKey,
+        metaKey: event.metaKey,
+        altKey: event.altKey,
+        shiftKey: event.shiftKey
+      },
+      focus,
+      rowCount,
+      columnCount,
+      pageSize()
+    );
+    if (next === null) {
       return;
     }
-    const { rowIndex, columnIndex } = focus;
-    let next;
-    switch (event.key) {
-      case "ArrowLeft":
-        if (event.ctrlKey) return;
-        next = { rowIndex, columnIndex: columnIndex - 1 };
-        break;
-      case "ArrowRight":
-        if (event.ctrlKey) return;
-        next = { rowIndex, columnIndex: columnIndex + 1 };
-        break;
-      case "ArrowUp":
-        next = { rowIndex: rowIndex - 1, columnIndex };
-        break;
-      case "ArrowDown":
-        next = { rowIndex: rowIndex + 1, columnIndex };
-        break;
-      // Ctrl takes Home and End to the grid's ends rather than the row's, which
-      // is the one place Ctrl is navigation rather than reorder.
-      case "Home":
-        next = event.ctrlKey ? { rowIndex: HEADER_ROW, columnIndex: 0 } : { rowIndex, columnIndex: 0 };
-        break;
-      case "End":
-        next = event.ctrlKey ? { rowIndex: rowCount - 1, columnIndex: columnCount - 1 } : { rowIndex, columnIndex: columnCount - 1 };
-        break;
-      case "PageUp":
-        next = { rowIndex: rowIndex - pageSize(), columnIndex };
-        break;
-      case "PageDown":
-        next = { rowIndex: rowIndex + pageSize(), columnIndex };
-        break;
-      default:
-        return;
-    }
     event.preventDefault();
     focusCell(next.rowIndex, next.columnIndex);
   }
-  return { focus, tabIndexFor, focusCell, onKeyDown };
+  return {
+    focus,
+    tabIndexFor: (rowIndex, columnIndex) => tabIndexFor(
+      columnIndex,
+      rowIndex === focus.rowIndex ? focus.columnIndex : null
+    ),
+    focusCell,
+    onKeyDown
+  };
 }
 
 // src/DataGrid/useGridSelection.ts
-import { useMemo, useRef as useRef2 } from "react";
 import {
-  accessDotted,
+  useMemo,
+  useRef as useRef2
+} from "react";
+import {
+  applySelectionIntent,
   clearSelection,
   diffSelection,
+  resolveCell,
+  resolveColumns,
+  resolveRows,
   selectAll,
   selectCell,
-  selectOnly,
-  selectRange,
-  toggleCellSelection,
-  toggleSelection
+  toggleCellSelection
 } from "@gridkitjs/core";
-function intentOf(event) {
-  if (event.shiftKey) {
-    return "range";
+
+// src/DataGrid/commitIfChanged.ts
+function commitIfChanged(current, next, setState, onCommit) {
+  if (next === current) {
+    return false;
   }
-  return event.ctrlKey || event.metaKey ? "toggle" : "replace";
+  setState(next);
+  onCommit?.(next);
+  return true;
 }
-function applyIntent(selection, orderedIds, anchorId, id, intent, mode) {
-  switch (intent) {
-    case "toggle":
-      return toggleSelection(selection, id, mode);
-    // A range with no anchor yet spans from the id to itself, which is the
-    // plain click a first Shift-click may as well be.
-    case "range":
-      return selectRange(selection, orderedIds, anchorId ?? id, id, mode);
-    default:
-      return selectOnly(selection, id, mode);
-  }
+
+// src/DataGrid/useGridSelection.ts
+function keyboardSelectIntent(event) {
+  return {
+    ctrlKey: event.key === " " || event.ctrlKey,
+    metaKey: event.metaKey,
+    shiftKey: event.shiftKey
+  };
 }
 function countMessage(count, noun) {
   if (count === 0) {
@@ -161,6 +163,18 @@ function countMessage(count, noun) {
   }
   return count === 1 ? `1 ${noun} selected` : `${String(count)} ${noun}s selected`;
 }
+function useAsSet(values) {
+  return useMemo(() => new Set(values), [values]);
+}
+function useIndexedBy(values, key) {
+  return useMemo(
+    () => new Map(values.map((value) => [value[key], value])),
+    [values, key]
+  );
+}
+function useMappedArray(values, key) {
+  return useMemo(() => values.map((value) => value[key]), [values, key]);
+}
 function useGridSelection({
   rows,
   columns,
@@ -172,141 +186,106 @@ function useGridSelection({
   cellSelection,
   setCellSelection,
   callbacks,
-  announce
+  announce,
+  columnName
 }) {
   const rowMode = selectable?.rows ?? false;
   const columnMode = selectable?.columns ?? false;
   const cellMode = selectable?.cells ?? false;
-  const rowsById = useMemo(
-    () => new Map(rows.map((entry) => [entry.rowId, entry])),
-    [rows]
-  );
-  const rowIds = useMemo(() => rows.map((entry) => entry.rowId), [rows]);
-  const columnIds = useMemo(() => columns.map((entry) => entry.id), [columns]);
-  const selectedRowIds = useMemo(() => new Set(rowSelection), [rowSelection]);
-  const selectedColumnIds = useMemo(
-    () => new Set(columnSelection),
-    [columnSelection]
-  );
+  const rowsById = useIndexedBy(rows, "rowId");
+  const rowIds = useMappedArray(rows, "rowId");
+  const columnIds = useMappedArray(columns, "id");
+  const selectedRowIds = useAsSet(rowSelection);
+  const selectedColumnIds = useAsSet(columnSelection);
   const rowAnchor = useRef2(null);
   const columnAnchor = useRef2(null);
-  function resolveRows(ids) {
-    return ids.map((id) => rowsById.get(id)).filter((row) => row !== void 0);
-  }
-  function resolveColumns(ids) {
-    return ids.map((id) => {
-      const columnIndex = columns.findIndex((entry) => entry.id === id);
-      const column = columns[columnIndex];
-      return column === void 0 ? void 0 : { columnId: id, column, columnIndex };
-    }).filter((column) => column !== void 0);
-  }
-  function resolveCell(ref) {
-    if (ref === null) {
-      return null;
-    }
-    const entry = rowsById.get(ref.rowId);
-    const columnIndex = columns.findIndex(
-      (candidate) => candidate.id === ref.columnId
-    );
-    const column = columns[columnIndex];
-    if (entry === void 0 || column === void 0) {
-      return null;
-    }
-    return {
-      rowId: ref.rowId,
-      columnId: ref.columnId,
-      row: entry.row,
-      column,
-      rowIndex: entry.rowIndex,
-      columnIndex,
-      value: accessDotted(entry.row, column.column.field)
-    };
-  }
   function announceCount(changed, total, noun) {
     if (changed > 1) {
       announce(countMessage(total, noun));
     }
   }
   function commitRows(next) {
-    if (next === rowSelection) {
-      return;
-    }
-    setRowSelection(next);
-    const { added, removed } = diffSelection(rowSelection, next);
-    const addedRows = resolveRows(added);
-    const removedRows = resolveRows(removed);
-    for (const row of addedRows) {
-      callbacks.onRowSelect?.({ row, selection: next });
-    }
-    if (addedRows.length > 0) {
-      callbacks.onRowsSelect?.({ rows: addedRows, selection: next });
-    }
-    for (const row of removedRows) {
-      callbacks.onRowDeselect?.({ row, selection: next });
-    }
-    if (removedRows.length > 0) {
-      callbacks.onRowsDeselect?.({ rows: removedRows, selection: next });
-    }
-    callbacks.onRowSelectionChange?.({
-      added: addedRows,
-      removed: removedRows,
-      selected: resolveRows(next),
-      selection: next
+    commitIfChanged(rowSelection, next, setRowSelection, (committed) => {
+      const { added, removed } = diffSelection(rowSelection, committed);
+      const addedRows = resolveRows(rowsById, added);
+      const removedRows = resolveRows(rowsById, removed);
+      for (const row of addedRows) {
+        callbacks.onRowSelect?.({ row, selection: committed });
+      }
+      if (addedRows.length > 0) {
+        callbacks.onRowsSelect?.({ rows: addedRows, selection: committed });
+      }
+      for (const row of removedRows) {
+        callbacks.onRowDeselect?.({ row, selection: committed });
+      }
+      if (removedRows.length > 0) {
+        callbacks.onRowsDeselect?.({ rows: removedRows, selection: committed });
+      }
+      callbacks.onRowSelectionChange?.({
+        added: addedRows,
+        removed: removedRows,
+        selected: resolveRows(rowsById, committed),
+        selection: committed
+      });
+      announceCount(added.length + removed.length, committed.length, "row");
     });
-    announceCount(added.length + removed.length, next.length, "row");
   }
   function commitColumns(next) {
-    if (next === columnSelection) {
-      return;
-    }
-    setColumnSelection(next);
-    const { added, removed } = diffSelection(columnSelection, next);
-    const addedColumns = resolveColumns(added);
-    const removedColumns = resolveColumns(removed);
-    for (const column of addedColumns) {
-      callbacks.onColumnSelect?.({ column, selection: next });
-    }
-    if (addedColumns.length > 0) {
-      callbacks.onColumnsSelect?.({ columns: addedColumns, selection: next });
-    }
-    for (const column of removedColumns) {
-      callbacks.onColumnDeselect?.({ column, selection: next });
-    }
-    if (removedColumns.length > 0) {
-      callbacks.onColumnsDeselect?.({
-        columns: removedColumns,
-        selection: next
+    commitIfChanged(columnSelection, next, setColumnSelection, (committed) => {
+      const { added, removed } = diffSelection(columnSelection, committed);
+      const addedColumns = resolveColumns(columns, added);
+      const removedColumns = resolveColumns(columns, removed);
+      for (const column of addedColumns) {
+        callbacks.onColumnSelect?.({ column, selection: committed });
+      }
+      if (addedColumns.length > 0) {
+        callbacks.onColumnsSelect?.({
+          columns: addedColumns,
+          selection: committed
+        });
+      }
+      for (const column of removedColumns) {
+        callbacks.onColumnDeselect?.({ column, selection: committed });
+      }
+      if (removedColumns.length > 0) {
+        callbacks.onColumnsDeselect?.({
+          columns: removedColumns,
+          selection: committed
+        });
+      }
+      callbacks.onColumnSelectionChange?.({
+        added: addedColumns,
+        removed: removedColumns,
+        selected: resolveColumns(columns, committed),
+        selection: committed
       });
-    }
-    callbacks.onColumnSelectionChange?.({
-      added: addedColumns,
-      removed: removedColumns,
-      selected: resolveColumns(next),
-      selection: next
+      announceCount(added.length + removed.length, committed.length, "column");
     });
-    announceCount(added.length + removed.length, next.length, "column");
   }
   function commitCell(next) {
-    if (next === cellSelection) {
-      return;
-    }
-    setCellSelection(next);
-    const selected = resolveCell(next);
-    const deselected = resolveCell(cellSelection);
-    if (deselected !== null) {
-      callbacks.onCellDeselect?.({ cell: deselected, selection: next });
-    }
-    if (selected !== null) {
-      callbacks.onCellSelect?.({ cell: selected, selection: next });
-    }
-    callbacks.onCellSelectionChange?.({
-      selected,
-      deselected,
-      selection: next
+    commitIfChanged(cellSelection, next, setCellSelection, (committed) => {
+      const selected = resolveCell(rowsById, columns, committed);
+      const deselected = resolveCell(rowsById, columns, cellSelection);
+      if (deselected !== null) {
+        callbacks.onCellDeselect?.({ cell: deselected, selection: committed });
+      }
+      if (selected !== null) {
+        callbacks.onCellSelect?.({ cell: selected, selection: committed });
+      }
+      callbacks.onCellSelectionChange?.({
+        selected,
+        deselected,
+        selection: committed
+      });
+      if (selected !== null) {
+        announce(
+          `${columnName(selected.columnId)}, row ${String(selected.rowIndex + 1)}, selected`
+        );
+      }
     });
   }
   function selectRow(rowId, intent) {
-    const next = applyIntent(
+    const next = applySelectionIntent(
       rowSelection,
       rowIds,
       rowAnchor.current,
@@ -320,7 +299,7 @@ function useGridSelection({
     commitRows(next);
   }
   function selectColumn(columnId, intent) {
-    const next = applyIntent(
+    const next = applySelectionIntent(
       columnSelection,
       columnIds,
       columnAnchor.current,
@@ -363,10 +342,36 @@ function useGridSelection({
 
 // src/DataGrid/components/GridHeader.tsx
 import { jsx, jsxs } from "react/jsx-runtime";
+function Icon({ children }) {
+  return /* @__PURE__ */ jsx(
+    "svg",
+    {
+      viewBox: "0 0 24 24",
+      fill: "none",
+      stroke: "currentColor",
+      strokeWidth: 2,
+      strokeLinecap: "round",
+      strokeLinejoin: "round",
+      "aria-hidden": "true",
+      children
+    }
+  );
+}
+function ChevronsUpDownIcon() {
+  return /* @__PURE__ */ jsxs(Icon, { children: [
+    /* @__PURE__ */ jsx("path", { d: "m7 15 5 5 5-5" }),
+    /* @__PURE__ */ jsx("path", { d: "m7 9 5-5 5 5" })
+  ] });
+}
+function ChevronUpIcon() {
+  return /* @__PURE__ */ jsx(Icon, { children: /* @__PURE__ */ jsx("path", { d: "m18 15-6-6-6 6" }) });
+}
 function GridHeader({
   columns,
   resize,
   drag,
+  sort,
+  sortableColumns,
   nav,
   selection
 }) {
@@ -380,20 +385,27 @@ function GridHeader({
       const dropBefore = beforeId !== void 0 && beforeId === entry.id;
       const dropAfter = beforeId === null && index === columns.length - 1;
       const selected = selection.selectedColumnIds.has(entry.id);
-      const shortcuts = [
-        entry.reorderable ? "Control+ArrowLeft Control+ArrowRight" : "",
-        entry.resizable ? "Alt+ArrowLeft Alt+ArrowRight" : ""
-      ].filter(Boolean).join(" ");
+      const sortable = column.sortable ?? sortableColumns;
+      const sortDirection = sort.directionFor(entry.id);
+      const sortPriority = sort.priorityFor(entry.id);
+      const shortcuts = buildKeyShortcuts({
+        reorderable: entry.reorderable,
+        resizable: entry.resizable,
+        sortable
+      });
       return /* @__PURE__ */ jsxs(
         "th",
         {
           scope: "col",
+          role: "columnheader",
           "data-gridkit-column": entry.id,
           "aria-colindex": index + 1,
           tabIndex: nav.tabIndexFor(HEADER_ROW, index),
-          ...selection.columnMode !== false && {
-            "aria-selected": selected
-          },
+          ...ariaAttr(
+            selection.columnMode !== false,
+            "aria-selected",
+            selected
+          ),
           onFocus: () => {
             nav.focusCell(HEADER_ROW, index);
           },
@@ -401,7 +413,7 @@ function GridHeader({
             if (drag.justDragged()) {
               return;
             }
-            if (event.target instanceof Element && event.target.closest(".header-resize-handle") !== null) {
+            if (event.target instanceof Element && (event.target.closest(".header-resize-handle") !== null || event.target.closest(".header-sort-toggle") !== null)) {
               return;
             }
             selection.selectColumn(entry.id, intentOf(event));
@@ -419,21 +431,27 @@ function GridHeader({
               resize.nudge(entry, direction * KEYBOARD_STEP);
               return;
             }
+            if (event.key === "Enter" && event.altKey && entry.resizable) {
+              event.preventDefault();
+              resize.sizeToContent(entry);
+              return;
+            }
+            if (event.key === "ArrowUp" && event.altKey && sortable) {
+              event.preventDefault();
+              sort.toggle(entry, { shiftKey: event.shiftKey });
+              return;
+            }
             if (event.key === " " || event.key === "Enter") {
               event.preventDefault();
               selection.selectColumn(
                 entry.id,
-                intentOf({
-                  ctrlKey: event.key === " " || event.ctrlKey,
-                  metaKey: event.metaKey,
-                  shiftKey: event.shiftKey
-                })
+                intentOf(keyboardSelectIntent(event))
               );
               return;
             }
             nav.onKeyDown(event);
           },
-          className: [
+          className: classNames(
             "header-cell",
             entry.reorderable ? "is-reorderable" : "",
             selected ? "is-selected" : "",
@@ -443,8 +461,13 @@ function GridHeader({
             dropAfter ? "is-drop-after" : "",
             column.wrap?.header ? "is-wrapped" : "",
             column.headerClassName ?? ""
-          ].filter(Boolean).join(" "),
-          ...shortcuts !== "" && { "aria-keyshortcuts": shortcuts },
+          ),
+          ...ariaAttr(shortcuts !== "", "aria-keyshortcuts", shortcuts),
+          ...ariaAttr(
+            sortable && sortDirection !== null,
+            "aria-sort",
+            sortDirection === "asc" ? "ascending" : "descending"
+          ),
           ...entry.reorderable && {
             onPointerDown: (event) => {
               drag.startDrag(entry, event);
@@ -452,6 +475,33 @@ function GridHeader({
           },
           children: [
             entry.label,
+            sortable && /*
+             * A pointer affordance only, and hidden from assistive
+             * technology like the resize handle: the keyboard equivalent
+             * lives on the header itself, under Alt+ArrowUp (plain) /
+             * Alt+Shift+ArrowUp (stacking).
+             */
+            /* @__PURE__ */ jsxs(
+              "span",
+              {
+                className: classNames(
+                  "header-sort-toggle",
+                  sortDirection !== null ? `is-sorted-${sortDirection}` : ""
+                ),
+                "aria-hidden": "true",
+                tabIndex: -1,
+                onPointerDown: (event) => {
+                  event.stopPropagation();
+                },
+                onClick: (event) => {
+                  sort.toggle(entry, { shiftKey: event.shiftKey });
+                },
+                children: [
+                  sortDirection === null ? /* @__PURE__ */ jsx(ChevronsUpDownIcon, {}) : /* @__PURE__ */ jsx(ChevronUpIcon, {}),
+                  sortPriority !== null && sortPriority > 1 && /* @__PURE__ */ jsx("span", { className: "header-sort-priority", children: sortPriority })
+                ]
+              }
+            ),
             entry.resizable && /*
              * A pointer affordance only, and hidden from assistive
              * technology accordingly: a focusable handle per column would
@@ -495,8 +545,11 @@ function GridHeader({
   ] });
 }
 
+// src/DataGrid/components/GridBody.tsx
+import { intentOf as intentOf2 } from "@gridkitjs/core";
+
 // src/DataGrid/components/GridRow.tsx
-import { accessDotted as accessDotted2 } from "@gridkitjs/core";
+import { accessDotted } from "@gridkitjs/core";
 import { memo } from "react";
 import { jsx as jsx2 } from "react/jsx-runtime";
 function GridRowComponent({
@@ -517,10 +570,10 @@ function GridRowComponent({
     {
       role: "row",
       "aria-rowindex": rowIndex + 2,
-      ...rowsSelectable && { "aria-selected": selected },
-      className: ["grid-row", selected ? "is-selected" : ""].filter(Boolean).join(" "),
+      ...ariaAttr(rowsSelectable, "aria-selected", selected),
+      className: classNames("grid-row", selected ? "is-selected" : ""),
       children: columns.map(({ id, column, alignment }, columnIndex) => {
-        const value = accessDotted2(row, column.field);
+        const value = accessDotted(row, column.field);
         const cellSelected = id === selectedColumnId;
         return /* @__PURE__ */ jsx2(
           "td",
@@ -528,15 +581,16 @@ function GridRowComponent({
             role: "gridcell",
             "data-gridkit-column": id,
             "aria-colindex": columnIndex + 1,
-            tabIndex: columnIndex === focusedColumnIndex ? 0 : -1,
-            ...cellsSelectable && { "aria-selected": cellSelected },
-            className: [
+            tabIndex: tabIndexFor(columnIndex, focusedColumnIndex),
+            ...ariaAttr(cellsSelectable, "aria-selected", cellSelected),
+            ...ariaAttr(cellsSelectable, "aria-keyshortcuts", "Space Enter"),
+            className: classNames(
               "grid-cell",
               id === activeColumnId ? "is-resizing" : "",
               cellSelected || selectedColumnIds.has(id) ? "is-selected" : "",
               column.wrap?.cells ? "is-wrapped" : "",
               column.cellClassName ?? ""
-            ].filter(Boolean).join(" "),
+            ),
             style: { textAlign: alignment },
             children: column.cellTemplate ? column.cellTemplate({ value, row, rowIndex, rowId, selected }) : value
           },
@@ -581,7 +635,7 @@ function GridBody({
     return position === null || entry === void 0 ? null : { position, rowId: entry.rowId };
   }
   function select(rowId, columnId, modifiers) {
-    const intent = intentOf(modifiers);
+    const intent = intentOf2(modifiers);
     if (rowMode !== false) {
       selection.selectRow(rowId, intent);
     }
@@ -608,11 +662,11 @@ function GridBody({
           const found = targetOf(event.target);
           if (found === null) return;
           event.preventDefault();
-          select(found.rowId, found.position.columnId, {
-            ctrlKey: event.key === " " || event.ctrlKey,
-            metaKey: event.metaKey,
-            shiftKey: event.shiftKey
-          });
+          select(
+            found.rowId,
+            found.position.columnId,
+            keyboardSelectIntent(event)
+          );
           return;
         }
         nav.onKeyDown(event);
@@ -645,8 +699,45 @@ import {
 } from "react";
 import {
   movesColumn,
-  resolveDropBefore
+  resolveDropBefore,
+  resolveKeyboardDropTarget
 } from "@gridkitjs/core";
+
+// src/DataGrid/pointerGesture.ts
+function startPointerGesture(element, pointerId, handlers) {
+  element.setPointerCapture(pointerId);
+  function stop() {
+    element.removeEventListener("pointermove", move);
+    element.removeEventListener("pointerup", end);
+    element.removeEventListener("pointercancel", cancel);
+    window.removeEventListener("keydown", onKeyDown);
+    if (element.hasPointerCapture(pointerId)) {
+      element.releasePointerCapture(pointerId);
+    }
+  }
+  function move(event) {
+    handlers.onMove(event);
+  }
+  function end() {
+    stop();
+    handlers.onEnd();
+  }
+  function cancel() {
+    stop();
+    handlers.onCancel();
+  }
+  function onKeyDown(event) {
+    if (event.key === "Escape") {
+      cancel();
+    }
+  }
+  element.addEventListener("pointermove", move);
+  element.addEventListener("pointerup", end);
+  element.addEventListener("pointercancel", cancel);
+  window.addEventListener("keydown", onKeyDown);
+}
+
+// src/DataGrid/useColumnDrag.ts
 var DRAG_THRESHOLD = 4;
 function headerAt(x, y) {
   const element = document.elementFromPoint(x, y);
@@ -678,70 +769,49 @@ function useColumnDrag({
     function placeGhost(x, y) {
       setGhostTransform(`translate(${String(x - grabX)}px, ${String(y)}px)`);
     }
-    header.setPointerCapture(pointerId);
-    function move(moveEvent) {
-      const { clientX, clientY } = moveEvent;
-      if (!dragging) {
-        if (Math.abs(clientX - startX) < DRAG_THRESHOLD) {
-          return;
-        }
-        dragging = true;
-        dragged.current = true;
-        setDraggedColumnId(entry.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;
-      setDropTarget(target);
-    }
-    function stop() {
-      header.removeEventListener("pointermove", move);
-      header.removeEventListener("pointerup", end);
-      header.removeEventListener("pointercancel", cancel);
-      window.removeEventListener("keydown", onKeyDown);
-      if (header.hasPointerCapture(pointerId)) {
-        header.releasePointerCapture(pointerId);
-      }
+    function reset() {
       setGhostTransform(null);
       setDraggedColumnId(null);
       setDropTarget(null);
     }
-    function end() {
-      const dropped = target;
-      stop();
-      if (dragging && dropped !== null) {
-        onDrop(dropped, entry.id);
-      }
-    }
-    function cancel() {
-      target = null;
-      stop();
-    }
-    function onKeyDown(keyEvent) {
-      if (keyEvent.key === "Escape") {
-        cancel();
+    startPointerGesture(header, pointerId, {
+      onMove(moveEvent) {
+        const { clientX, clientY } = moveEvent;
+        if (!dragging) {
+          if (Math.abs(clientX - startX) < DRAG_THRESHOLD) {
+            return;
+          }
+          dragging = true;
+          dragged.current = true;
+          setDraggedColumnId(entry.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;
+        setDropTarget(target);
+      },
+      onEnd() {
+        const dropped = target;
+        reset();
+        if (dragging && dropped !== null) {
+          onDrop(dropped, entry.id);
+        }
+      },
+      // Escape and a cancelled pointer both leave the order as it was.
+      onCancel() {
+        target = null;
+        reset();
       }
-    }
-    header.addEventListener("pointermove", move);
-    header.addEventListener("pointerup", end);
-    header.addEventListener("pointercancel", cancel);
-    window.addEventListener("keydown", onKeyDown);
+    });
   }
   function moveByKeyboard(entry, direction) {
-    const index = order.indexOf(entry.id);
-    if (index === -1) {
-      return;
-    }
-    const targetIndex = direction === -1 ? index - 1 : index + 2;
-    if (targetIndex < 0) {
+    const beforeId = resolveKeyboardDropTarget(order, entry.id, direction);
+    if (beforeId === void 0) {
       return;
     }
-    onDrop(
-      { kind: "column-order", beforeId: order[targetIndex] ?? null },
-      entry.id
-    );
+    onDrop({ kind: "column-order", beforeId }, entry.id);
   }
   return {
     draggedColumnId,
@@ -762,13 +832,14 @@ import {
   beginColumnResize,
   clampColumnWidth,
   resolveColumnConstraints,
+  revertColumnSize,
   sizeColumnToContent
 } from "@gridkitjs/core";
 
 // src/DataGrid/measureColumnContent.ts
 function measureColumnContent(table, columnId) {
   const cells = table.querySelectorAll(
-    `[data-gridkit-column="${CSS.escape(columnId)}"]`
+    `td[data-gridkit-column="${CSS.escape(columnId)}"]`
   );
   const range = document.createRange();
   let widest = null;
@@ -810,45 +881,39 @@ function useColumnResize({
     let width = session.startWidth;
     event.preventDefault();
     event.stopPropagation();
-    handle.setPointerCapture(pointerId);
     setActiveColumnId(session.columnId);
-    function move(moveEvent) {
-      width = applyColumnResize(session, moveEvent.clientX);
-      commit(base, session.columnId, width, "move");
-    }
-    function stop() {
-      handle.removeEventListener("pointermove", move);
-      handle.removeEventListener("pointerup", end);
-      handle.removeEventListener("pointercancel", cancel);
-      window.removeEventListener("keydown", onKeyDown);
-      if (handle.hasPointerCapture(pointerId)) {
-        handle.releasePointerCapture(pointerId);
-      }
-      setActiveColumnId(null);
-    }
-    function end() {
-      stop();
-      commit(base, session.columnId, width, "end");
-    }
-    function cancel() {
-      stop();
-      setSizing(base);
-      onColumnResize?.({
-        columnId: session.columnId,
-        width: session.startWidth,
-        sizing: base,
-        phase: "end"
-      });
-    }
-    function onKeyDown(keyEvent) {
-      if (keyEvent.key === "Escape") {
-        cancel();
+    startPointerGesture(handle, pointerId, {
+      onMove(moveEvent) {
+        width = applyColumnResize(session, moveEvent.clientX);
+        commit(base, session.columnId, width, "move");
+      },
+      onEnd() {
+        setActiveColumnId(null);
+        if (width !== session.startWidth) {
+          commit(base, session.columnId, width, "end");
+        }
+      },
+      /**
+       * Escape puts back only the dragged column's pre-drag width, merged
+       * into whatever the sizing state is *now* — not the `base` snapshot
+       * taken at drag-start — so a different column resized via keyboard
+       * while this drag was still open keeps its change instead of being
+       * clobbered by a stale restore.
+       */
+      onCancel() {
+        setActiveColumnId(null);
+        setSizing((current) => {
+          const next = revertColumnSize(current, base, session.columnId);
+          onColumnResize?.({
+            columnId: session.columnId,
+            width: session.startWidth,
+            sizing: next,
+            phase: "end"
+          });
+          return next;
+        });
       }
-    }
-    handle.addEventListener("pointermove", move);
-    handle.addEventListener("pointerup", end);
-    handle.addEventListener("pointercancel", cancel);
-    window.addEventListener("keydown", onKeyDown);
+    });
   }
   function sizeToContent(entry) {
     const table = tableRef.current;
@@ -883,6 +948,31 @@ function useColumnResize({
   return { activeColumnId, startResize, sizeToContent, nudge };
 }
 
+// src/DataGrid/useColumnSort.ts
+import {
+  sortDirectionFor,
+  sortPriorityFor,
+  toggleColumnSort
+} from "@gridkitjs/core";
+function useColumnSort({
+  sort,
+  setSort,
+  onColumnSortChange
+}) {
+  function toggle(entry, event) {
+    const next = toggleColumnSort(sort, entry.id, { stack: event.shiftKey });
+    commitIfChanged(sort, next, setSort, (committed) => {
+      onColumnSortChange?.({ columnId: entry.id, sort: committed });
+    });
+  }
+  return {
+    sort,
+    directionFor: (columnId) => sortDirectionFor(sort, columnId),
+    priorityFor: (columnId) => sortPriorityFor(sort, columnId),
+    toggle
+  };
+}
+
 // src/DataGrid/useElementWidth.ts
 import { useLayoutEffect, useState as useState4 } from "react";
 function useElementWidth(ref, enabled) {
@@ -924,8 +1014,13 @@ function DataGridComponent({
   columnSizeDefaults,
   onColumnResize,
   onColumnOrderChange,
+  sortableColumns = false,
+  defaultColumnSort,
+  onColumnSortChange,
+  defaultFilter,
   label,
   labelledBy,
+  ref,
   ...callbacks
 }) {
   const hoverRows = hoverable?.rows ?? true;
@@ -940,6 +1035,8 @@ function DataGridComponent({
   const [order, setOrder] = useState5(
     defaultColumnOrder ?? []
   );
+  const [sort, setSort] = useState5(defaultColumnSort ?? []);
+  const [filter] = useState5(defaultFilter ?? []);
   const [announcement, setAnnouncement] = useState5("");
   const [rowSelection, setRowSelection] = useState5(
     defaultRowSelection ?? []
@@ -984,6 +1081,10 @@ function DataGridComponent({
     resizableColumns,
     reorderableColumns
   ]);
+  const shownRows = useMemo2(
+    () => resolveShownRows(rows, filter, sort, resolved),
+    [rows, filter, sort, resolved]
+  );
   function columnName(columnId) {
     const entry = resolved.find((candidate) => candidate.id === columnId);
     if (entry === void 0) {
@@ -1011,7 +1112,7 @@ function DataGridComponent({
   });
   const nav = useGridNavigation({
     tableRef,
-    rowCount: rows.length,
+    rowCount: shownRows.length,
     columnCount: resolved.length
   });
   const displayedIds = useMemo2(
@@ -1032,8 +1133,27 @@ function DataGridComponent({
     nav.focusCell(HEADER_ROW, position);
   }
   const drag = useColumnDrag({ order: displayedIds, onDrop: handleDrop });
+  function handleColumnSortChange(event) {
+    onColumnSortChange?.(event);
+    const entry = event.sort.find(
+      (candidate) => candidate.columnId === event.columnId
+    );
+    if (entry === void 0) {
+      announce(`${columnName(event.columnId)}, sort cleared`);
+      return;
+    }
+    const direction = entry.direction === "asc" ? "ascending" : "descending";
+    announce(
+      event.sort.length > 1 ? `${columnName(event.columnId)} sorted ${direction}, key ${String(event.sort.indexOf(entry) + 1)} of ${String(event.sort.length)}` : `${columnName(event.columnId)} sorted ${direction}`
+    );
+  }
+  const columnSort = useColumnSort({
+    sort,
+    setSort,
+    onColumnSortChange: handleColumnSortChange
+  });
   const selection = useGridSelection({
-    rows,
+    rows: shownRows,
     columns: resolved,
     selectable,
     rowSelection,
@@ -1043,20 +1163,57 @@ function DataGridComponent({
     cellSelection,
     setCellSelection,
     callbacks,
-    announce
+    announce,
+    columnName
   });
   const multiselectable = selection.rowMode === "multiple" || selection.columnMode === "multiple";
+  useImperativeHandle(ref, () => ({
+    get element() {
+      return viewportRef.current;
+    },
+    get table() {
+      return tableRef.current;
+    },
+    getRows: () => shownRows,
+    getColumns: () => resolved,
+    getColumnSizing: () => sizing,
+    getColumnOrder: () => order,
+    getColumnSort: () => sort,
+    getRowSelection: () => rowSelection,
+    getColumnSelection: () => columnSelection,
+    getCellSelection: () => cellSelection,
+    getFocusedCell: () => nav.focus,
+    focusCell: nav.focusCell,
+    clearSelection: selection.clear,
+    selectAllRows: selection.selectAllRows,
+    scrollToRow: (rowId, options) => {
+      const index = shownRows.findIndex((entry) => entry.rowId === rowId);
+      if (index === -1) return;
+      tableRef.current?.tBodies[0]?.rows[index]?.scrollIntoView(options);
+    },
+    scrollToColumn: (columnId, options) => {
+      const cells = tableRef.current?.querySelectorAll("[data-gridkit-column]");
+      const cell = cells ? Array.from(cells).find(
+        (entry) => entry.getAttribute("data-gridkit-column") === columnId
+      ) : void 0;
+      cell?.scrollIntoView(options);
+    }
+  }));
   return /* @__PURE__ */ jsxs2("div", { className: "gridkit-data-grid-viewport", ref: viewportRef, children: [
     /* @__PURE__ */ jsxs2(
       "table",
       {
         ref: tableRef,
         role: "grid",
-        "aria-rowcount": rows.length + 1,
+        "aria-rowcount": shownRows.length + 1,
         "aria-colcount": resolved.length,
-        ...multiselectable && { "aria-multiselectable": true },
-        ...labelledBy !== void 0 && { "aria-labelledby": labelledBy },
-        ...labelledBy === void 0 && label !== void 0 && { "aria-label": label },
+        ...ariaAttr(multiselectable, "aria-multiselectable", true),
+        ...ariaAttr(labelledBy !== void 0, "aria-labelledby", labelledBy),
+        ...ariaAttr(
+          labelledBy === void 0 && label !== void 0,
+          "aria-label",
+          label
+        ),
         onKeyDown: (event) => {
           if (event.key === "Escape") {
             if (drag.draggedColumnId !== null || resize.activeColumnId !== null)
@@ -1071,7 +1228,7 @@ function DataGridComponent({
           }
         },
         style: { width: totalColumnWidth(resolved) },
-        className: [
+        className: classNames(
           "gridkit-data-grid",
           borders ? `borders-${borders}` : "",
           // Hover is on by default and selection off, so one set of classes
@@ -1083,7 +1240,7 @@ function DataGridComponent({
           selection.rowMode === false ? "" : "selectable-rows",
           selection.columnMode === false ? "" : "selectable-columns",
           selection.cellMode === false ? "" : "selectable-cells"
-        ].filter(Boolean).join(" "),
+        ),
         children: [
           /* @__PURE__ */ jsx4("colgroup", { children: resolved.map((entry) => /* @__PURE__ */ jsx4("col", { style: { width: entry.width } }, entry.id)) }),
           /* @__PURE__ */ jsx4(
@@ -1092,6 +1249,8 @@ function DataGridComponent({
               columns: resolved,
               resize,
               drag,
+              sort: columnSort,
+              sortableColumns,
               nav,
               selection
             }
@@ -1100,7 +1259,7 @@ function DataGridComponent({
             GridBody,
             {
               columns: resolved,
-              rows,
+              rows: shownRows,
               activeColumnId: resize.activeColumnId,
               nav,
               selection