@versini/ui-datagrid 3.1.2 → 4.0.0

package/README.md

@@ -5,7 +5,7 @@ A data grid component library for React built with div-based ARIA grid layout fo
 - **Accessible**: Uses ARIA grid roles for screen reader support
 - **Flexible Layout**: Div-based structure allows for complex styling
 - **CSS Grid Columns**: Define column widths with CSS Grid track sizes
-- **Infinite Scrolling**: Progressive loading with IntersectionObserver
+- **Row Virtualization**: Windowing for large datasets — only viewport rows stay in the DOM
 - **Animated Height**: Smooth height transitions when content changes
 - **Sorting**: Built-in sorting utilities and sortable column headers
 - **Sticky Header/Footer**: With optional blur effects
@@ -35,7 +35,7 @@ import { DataGridRow } from "@versini/ui-datagrid/row";
 import { DataGridCell } from "@versini/ui-datagrid/cell";
 import { DataGridCellSort } from "@versini/ui-datagrid/cell-sort";
 
-// Infinite scroll (progressive loading)
+// Virtualized body for large datasets
 import { DataGridInfiniteBody } from "@versini/ui-datagrid/infinite";
 
 // Animated height wrapper
@@ -135,7 +135,7 @@ Supported column values include:
 
 ## Infinite Scroll
 
-For datasets with hundreds to thousands of rows, use `DataGridInfiniteBody` for progressive loading:
+For large datasets, use `DataGridInfiniteBody`. It virtualizes the rows (windowing via [`@tanstack/react-virtual`](https://tanstack.com/virtual/latest)): only the rows near the viewport stay mounted, so the DOM stays small and scrolling stays smooth no matter how many rows there are.
 
 ```tsx
 import { useState } from "react";
@@ -161,8 +161,7 @@ function MyInfiniteTable({ data }) {
 
         <DataGridInfiniteBody
           data={data}
-          batchSize={25}
-          threshold={5}
+          estimatedRowHeight={48}
           onVisibleCountChange={(count) => setVisibleCount(count)}
         >
           {(item) => (
@@ -178,11 +177,13 @@ function MyInfiniteTable({ data }) {
 }
 ```
 
-The `DataGridInfiniteBody` component handles all the complexity internally:
+`DataGridInfiniteBody` keeps `columns` (including intrinsic `auto` tracks) working because it renders rows in normal grid flow between two full-span spacer elements (not absolutely positioned). It windows against the DataGrid's own scroll container — created when you set `maxHeight` or a sticky header/footer — and otherwise against the page (window scroll). To scroll inside your own bounded container, set `maxHeight` on the `DataGrid` rather than relying on an outer wrapper.
 
-- Progressive loading with IntersectionObserver
-- Correct marker placement for seamless scrolling (marker is placed `threshold` items before the end)
-- Automatic data slicing and memoization
+Notes:
+
+- **Set `estimatedRowHeight` close to your average row height.** It seeds the scrollbar before rows are measured; a good estimate minimizes scrollbar drift and makes `scrollToIndex` to far rows land accurately. Real heights are always measured from the DOM, so variable / wrapping rows work. It defaults to the grid's density (44, or 29 when the `DataGrid` is `compact`), so you usually only need to set it for unusually tall rows.
+- The grid exposes `aria-rowcount` and `aria-rowindex`, and keeps keyboard focus on the grid if a focused row recycles out.
+- **Known limitation:** because off-screen rows are removed from the DOM, browser find-in-page (Ctrl+F) and uncontrolled per-row state (e.g. an open menu, an uncommitted input) don't persist when a row recycles. Lift such state to controlled props. This is inherent to DOM virtualization.
 
 ### Jump to Row
 
@@ -226,7 +227,7 @@ function MyInfiniteTableWithJump({ data }) {
           </DataGridRow>
         </DataGridHeader>
 
-        <DataGridInfiniteBody ref={infiniteBodyRef} data={data} batchSize={25}>
+        <DataGridInfiniteBody ref={infiniteBodyRef} data={data}>
           {(item) => (
             <DataGridRow
               key={item.id}
@@ -246,8 +247,8 @@ function MyInfiniteTableWithJump({ data }) {
 
 The `scrollToIndex` method:
 
-- If the row is already visible → smooth scrolls to it immediately
-- If the row is not yet loaded → expands visible count first, then scrolls after render
+- Centers the target row in the scroll viewport, mounting it first if it's off-screen
+- Scrolls smoothly, unless the user prefers reduced motion (then it jumps instantly)
 
 ## Sorting
 
@@ -404,12 +405,11 @@ function MySortableTable({ data }) {
 
 | Prop                   | Type                                            | Default      | Description                                     |
 | ---------------------- | ----------------------------------------------- | ------------ | ----------------------------------------------- |
-| `data`                 | `T[]`                                           | **required** | The full dataset to render progressively        |
+| `data`                 | `T[]`                                           | **required** | The full dataset to virtualize                  |
 | `children`             | `(item: T, index: number) => ReactNode`         | **required** | Render function for each row                    |
-| `batchSize`            | `number`                                        | `20`         | Items to show initially and add per scroll      |
-| `threshold`            | `number`                                        | `5`          | Items before marker to allow seamless scrolling |
-| `rootMargin`           | `string`                                        | `'20px'`     | IntersectionObserver margin                     |
-| `onVisibleCountChange` | `(visibleCount: number, total: number) => void` | -            | Callback when visible count changes             |
+| `overscan`             | `number`                                        | `8`          | Rows rendered beyond the viewport on each side  |
+| `estimatedRowHeight`   | `number`                                        | `44` / `29`  | Initial row-height estimate (29 when `compact`) before measurement |
+| `onVisibleCountChange` | `(visibleCount: number, total: number) => void` | -            | Monotonic high-water mark — furthest row reached, plus one |
 | `noData`               | `boolean`                                       | `false`      | Display empty state instead of infinite scroll  |
 | `noDataText`           | `string`                                        | `'No Data'`  | Custom text for the empty state                 |
 | `className`            | `string`                                        | -            | CSS class for the body element                  |
@@ -419,7 +419,7 @@ function MySortableTable({ data }) {
 
 | Method          | Signature                 | Description                                                                     |
 | --------------- | ------------------------- | ------------------------------------------------------------------------------- |
-| `scrollToIndex` | `(index: number) => void` | Scroll to a row by index. Expands visible count if needed, then smooth scrolls. |
+| `scrollToIndex` | `(index: number) => void` | Center a row by index, mounting it if off-screen. Smooth unless reduced motion is preferred. |
 
 ## License
 

package/dist/197.js

@@ -1,10 +1,10 @@
 /*!
-  @versini/ui-datagrid v3.1.2
+  @versini/ui-datagrid v4.0.0
   © 2026 gizmette.com
 */
 
 import clsx from "clsx";
-import { useContext, useLayoutEffect, useRef } from "react";
+import { useContext, useEffect, useLayoutEffect, useRef } from "react";
 import { DataGridContext } from "./430.js";
 
 
@@ -60,54 +60,76 @@ import { DataGridContext } from "./430.js";
  */ function useColumnMeasurement(bodyRef, contentDependency, noData = false) {
     const ctx = useContext(DataGridContext);
     const prevWidthsRef = useRef([]);
-    // biome-ignore lint/correctness/useExhaustiveDependencies: contentDependency triggers remeasurement when rows change
-    useLayoutEffect(()=>{
+    const observerRef = useRef(null);
+    const needsMeasurement = Boolean(ctx.columns && (ctx.stickyHeader || ctx.stickyFooter));
+    /**
+	 * Re-query the current first row's cells, report any changed widths, and
+	 * return the cells. Held in a ref so the persistent ResizeObserver always runs
+	 * the latest logic without being recreated as the window slides.
+	 */ const measureRef = useRef(()=>[]);
+    measureRef.current = ()=>{
         const element = bodyRef.current;
-        const needsMeasurement = ctx.columns && (ctx.stickyHeader || ctx.stickyFooter);
         if (noData || !element || !needsMeasurement || !ctx.setMeasuredColumnWidths) {
-            return;
+            return [];
         }
         const firstRow = element.querySelector('[role="row"]');
-        if (!firstRow) {
-            return;
-        }
-        const cells = firstRow.querySelectorAll('[role="cell"], [role="columnheader"], [role="gridcell"]');
+        const cells = firstRow ? Array.from(firstRow.querySelectorAll('[role="cell"], [role="columnheader"], [role="gridcell"]')) : [];
         if (cells.length === 0) {
+            return [];
+        }
+        const dpr = typeof window !== "undefined" ? window.devicePixelRatio ?? 1 : 1;
+        const widths = cells.map((cell)=>quantizeWidthToDevicePixels(cell.getBoundingClientRect().width, dpr));
+        /**
+		 * Only update state if widths have actually changed to prevent infinite
+		 * loops.
+		 */ const prevWidths = prevWidthsRef.current;
+        const hasChanged = widths.length !== prevWidths.length || widths.some((w, i)=>w !== prevWidths[i]);
+        if (hasChanged) {
+            prevWidthsRef.current = widths;
+            ctx.setMeasuredColumnWidths(widths);
+        }
+        return cells;
+    };
+    /**
+	 * Keep a single ResizeObserver for the hook's lifetime and re-point it at the
+	 * current first row's cells whenever the rendered content changes (e.g. a
+	 * virtualized window sliding). The cells are the observed targets because the
+	 * body is `display: contents` (it has no box of its own); re-pointing the same
+	 * observer avoids tearing one down and allocating a new one on every scroll
+	 * shift.
+	 */ // biome-ignore lint/correctness/useExhaustiveDependencies: measureRef is stable; contentDependency re-points the observer when the rendered rows change
+    useLayoutEffect(()=>{
+        if (!needsMeasurement) {
+            observerRef.current?.disconnect();
             return;
         }
-        const measureColumns = ()=>{
-            const dpr = typeof window !== "undefined" ? window.devicePixelRatio ?? 1 : 1;
-            const widths = Array.from(cells).map((cell)=>quantizeWidthToDevicePixels(cell.getBoundingClientRect().width, dpr));
-            /**
-			 * Only update state if widths have actually changed to prevent infinite
-			 * loops.
-			 */ const prevWidths = prevWidthsRef.current;
-            const hasChanged = widths.length !== prevWidths.length || widths.some((w, i)=>w !== prevWidths[i]);
-            if (hasChanged) {
-                prevWidthsRef.current = widths;
-                ctx.setMeasuredColumnWidths?.(widths);
-            }
-        };
-        // Initial measurement.
-        measureColumns();
-        // Set up ResizeObserver to re-measure when cells resize.
-        const observer = new ResizeObserver(()=>{
-            measureColumns();
-        });
-        // Observe the body element for any size changes.
-        observer.observe(element);
-        // Also observe the first row's cells directly for more accurate updates.
+        if (!observerRef.current) {
+            observerRef.current = new ResizeObserver(()=>{
+                measureRef.current();
+            });
+        }
+        const observer = observerRef.current;
+        observer.disconnect();
+        const cells = measureRef.current();
         for (const cell of cells){
             observer.observe(cell);
         }
-        return ()=>observer.disconnect();
     }, [
         ctx.columns,
         ctx.stickyHeader,
         ctx.stickyFooter,
         ctx.setMeasuredColumnWidths,
-        contentDependency
+        contentDependency,
+        needsMeasurement,
+        noData
     ]);
+    // Disconnect on unmount.
+    useEffect(()=>{
+        return ()=>{
+            observerRef.current?.disconnect();
+            observerRef.current = null;
+        };
+    }, []);
 }
 
 export { getBodyClass, useColumnMeasurement };

package/dist/430.js

@@ -1,5 +1,5 @@
 /*!
-  @versini/ui-datagrid v3.1.2
+  @versini/ui-datagrid v4.0.0
   © 2026 gizmette.com
 */
 

package/dist/799.js

@@ -1,5 +1,5 @@
 /*!
-  @versini/ui-datagrid v3.1.2
+  @versini/ui-datagrid v4.0.0
   © 2026 gizmette.com
 */
 

package/dist/91.js

@@ -1,5 +1,5 @@
 /*!
-  @versini/ui-datagrid v3.1.2
+  @versini/ui-datagrid v4.0.0
   © 2026 gizmette.com
 */
 

package/dist/DataGrid/DataGridTypes.d.ts

@@ -290,5 +290,57 @@ export type DataGridContextValue = {
      * DataGridInfiniteBody where CSS :last-child doesn't work.
      */
     isLastRow?: boolean;
+    /**
+     * Total row count (header + body + footer) for `aria-rowcount` on the grid.
+     * Set only when a body virtualizes its rows; `undefined` otherwise, so
+     * non-virtualized grids render no `aria-rowcount`.
+     */
+    rowCount?: number;
+    /**
+     * Callback for a virtualizing body to report the total row count to the grid.
+     */
+    setRowCount?: (count: number | undefined) => void;
+    /**
+     * Number of header rows currently registered (0 or 1). Used to offset
+     * `aria-rowindex` so body rows are numbered after the header.
+     */
+    headerRows?: number;
+    /**
+     * Number of footer rows currently registered (0 or 1).
+     */
+    footerRows?: number;
+    /**
+     * 1-based ARIA row index for this row (header/body/footer), set per-row by
+     * the provider. Applied to the `role="row"` element when present.
+     */
+    ariaRowIndex?: number;
+    /**
+     * 0-based data index for a virtualized body row. Applied as `data-index` on
+     * the `role="row"` element so the virtualizer maps measurements to the row.
+     */
+    dataIndex?: number;
+    /**
+     * Virtualizer measure callback. Attached as a ref to the `role="row"` element
+     * so the virtualizer measures the real row box (the wrapper is
+     * `display:contents` and has no box).
+     */
+    measureRowElement?: (el: HTMLElement | null) => void;
+    /**
+     * Focus the grid element (a `tabIndex={-1}` sentinel). Used by a virtualizing
+     * body to keep focus off `document.body` when a focused row recycles out.
+     */
+    focusGrid?: () => void;
+    /**
+     * The internal bounded scroll container (sticky scrollable area, or the
+     * maxHeight wrapper) a virtualized body should window against. `null` until
+     * mounted, or when DataGrid owns no internal scroller (see `pageScroll`).
+     */
+    scrollContainer?: HTMLElement | null;
+    /**
+     * True when DataGrid has no internal bounded scroller (no sticky, no
+     * maxHeight), so a virtualized body should window against the page (window
+     * scroll) instead of `scrollContainer`.
+     */
+    pageScroll?: boolean;
 };
 export {};

package/dist/DataGrid/index.js

@@ -1,10 +1,10 @@
 /*!
-  @versini/ui-datagrid v3.1.2
+  @versini/ui-datagrid v4.0.0
   © 2026 gizmette.com
 */
 
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { useCallback, useMemo, useState } from "react";
+import { useCallback, useMemo, useRef, useState } from "react";
 import { BlurEffects } from "../799.js";
 import { getDataGridClasses } from "../91.js";
 import { DataGridContext } from "../430.js";
@@ -47,12 +47,21 @@ import { DataGridContext } from "../430.js";
     const unregisterFooter = useCallback(()=>setFooterCount((c)=>c - 1), []);
     const hasRegisteredHeader = headerCount > 0;
     const hasRegisteredFooter = footerCount > 0;
+    const headerRows = hasRegisteredHeader ? 1 : 0;
+    const footerRows = hasRegisteredFooter ? 1 : 0;
     /**
 	 * Only apply sticky behavior if both the prop is true AND the corresponding
 	 * component exists. This prevents adding padding/styles for non-existent
 	 * headers/footers.
 	 */ const effectiveStickyHeader = stickyHeader && hasRegisteredHeader;
     const effectiveStickyFooter = stickyFooter && hasRegisteredFooter;
+    const hasSticky = effectiveStickyHeader || effectiveStickyFooter;
+    /**
+	 * Whether DataGrid owns a bounded internal scroll container (sticky → the
+	 * scrollableContent area; maxHeight → the wrapper). When it doesn't, a
+	 * virtualized body windows against the page instead (pageScroll).
+	 */ const hasInternalScroller = hasSticky || Boolean(maxHeight);
+    const pageScroll = !hasInternalScroller;
     /**
 	 * State to hold the caption ID registered by DataGridHeader. Used for
 	 * aria-labelledby on the grid element for accessibility.
@@ -60,6 +69,28 @@ import { DataGridContext } from "../430.js";
     const handleSetCaptionId = useCallback((id)=>{
         setCaptionId(id);
     }, []);
+    /**
+	 * Total row count reported by DataGridInfiniteBody. Drives `aria-rowcount` on
+	 * the grid. Seeded `undefined` so non-infinite grids render no `aria-rowcount`
+	 * (markup stays unchanged).
+	 */ const [rowCount, setRowCount] = useState(undefined);
+    /**
+	 * Focus sentinel: a virtualizing body moves focus here (the grid element,
+	 * made focusable via tabIndex={-1}) when a focused row recycles out of the
+	 * DOM, so focus never drops to document.body.
+	 */ const gridRef = useRef(null);
+    const focusGrid = useCallback(()=>{
+        gridRef.current?.focus();
+    }, []);
+    /**
+	 * The internal scroll container a virtualized body should window against,
+	 * exposed via context. DataGrid owns a bounded scroller only when sticky
+	 * header/footer or maxHeight is set; otherwise the body windows against the
+	 * page (pageScroll).
+	 */ const [scrollContainer, setScrollContainer] = useState(null);
+    const scrollContainerRef = useCallback((el)=>{
+        setScrollContainer(el);
+    }, []);
     const classes = useMemo(()=>getDataGridClasses({
             mode,
             className,
@@ -90,7 +121,14 @@ import { DataGridContext } from "../430.js";
             unregisterFooter,
             setHeaderHeight,
             setFooterHeight,
-            setMeasuredColumnWidths
+            setMeasuredColumnWidths,
+            rowCount,
+            setRowCount,
+            headerRows,
+            footerRows,
+            focusGrid,
+            scrollContainer,
+            pageScroll
         }), [
         mode,
         compact,
@@ -103,7 +141,13 @@ import { DataGridContext } from "../430.js";
         registerHeader,
         unregisterHeader,
         registerFooter,
-        unregisterFooter
+        unregisterFooter,
+        rowCount,
+        headerRows,
+        footerRows,
+        focusGrid,
+        scrollContainer,
+        pageScroll
     ]);
     const wrapperStyle = maxHeight ? {
         maxHeight: typeof maxHeight === "number" ? `${maxHeight}px` : maxHeight
@@ -116,11 +160,6 @@ import { DataGridContext } from "../430.js";
         paddingTop: effectiveStickyHeader ? headerHeight : undefined,
         paddingBottom: effectiveStickyFooter ? footerHeight : undefined
     };
-    /**
-	 * When sticky header/footer is enabled, use Panel-like structure: - Outer
-	 * wrapper has overflow-hidden - Scrollable content area in the middle with
-	 * padding - Header/footer are absolutely positioned.
-	 */ const hasSticky = effectiveStickyHeader || effectiveStickyFooter;
     /**
 	 * When columns are provided, apply grid-template-columns at the grid level so
 	 * all rows can use subgrid to inherit the same column sizing.
@@ -128,8 +167,11 @@ import { DataGridContext } from "../430.js";
         gridTemplateColumns: columns.join(" ")
     } : undefined;
     const gridContent = /*#__PURE__*/ jsx("div", {
+        ref: gridRef,
         role: "grid",
         "aria-labelledby": captionId,
+        "aria-rowcount": rowCount,
+        tabIndex: rowCount != null ? -1 : undefined,
         className: classes.grid,
         style: gridStyle,
         ...rest,
@@ -158,9 +200,11 @@ import { DataGridContext } from "../430.js";
                     ]
                 }),
                 /*#__PURE__*/ jsx("div", {
+                    ref: hasInternalScroller && !hasSticky ? scrollContainerRef : undefined,
                     className: classes.wrapper,
                     style: wrapperStyle,
                     children: hasSticky ? /*#__PURE__*/ jsx("div", {
+                        ref: scrollContainerRef,
                         className: classes.scrollableContent,
                         style: scrollableContentStyle,
                         children: gridContent

package/dist/DataGridAnimated/AnimatedWrapper.d.ts

@@ -35,7 +35,6 @@ export type AnimatedWrapperProps = {
  *     <DataGrid maxHeight="400px" stickyHeader>
  *       <DataGridInfiniteBody
  *         data={largeData}
- *         batchSize={25}
  *         onVisibleCountChange={(count) => setVisibleCount(count)}
  *       >
  *         {(row) => (

package/dist/DataGridAnimated/index.js

@@ -1,5 +1,5 @@
 /*!
-  @versini/ui-datagrid v3.1.2
+  @versini/ui-datagrid v4.0.0
   © 2026 gizmette.com
 */
 
@@ -54,6 +54,12 @@ const DEFAULT_ANIMATION_DURATION = 300;
 		 */ if (lastHeightRef.current === 0) {
             lastHeightRef.current = ref.current.offsetHeight;
             prevDependencyRef.current = dependency;
+            // If a prior animation was canceled and the content collapsed to 0,
+            // clear any locked height so the wrapper can't stay frozen.
+            setAnimationState((state)=>state.isAnimating ? {
+                    height: "auto",
+                    isAnimating: false
+                } : state);
             return;
         }
         /**
@@ -68,8 +74,16 @@ const DEFAULT_ANIMATION_DURATION = 300;
 		 * Update the stored height for next time.
 		 */ lastHeightRef.current = newHeight;
         /**
-		 * If heights are the same or previous was 0, no animation needed.
+		 * If heights are the same or previous was 0, no animation needed. Reset any
+		 * height left locked by a just-canceled animation, so the wrapper can't get
+		 * stuck collapsed with `overflow: hidden` when the dependency keeps changing
+		 * without a height change — e.g. a virtualized body reporting a scroll-driven
+		 * count while its panel stays a fixed `maxHeight`.
 		 */ if (previousHeight === newHeight || previousHeight === 0) {
+            setAnimationState((state)=>state.isAnimating ? {
+                    height: "auto",
+                    isAnimating: false
+                } : state);
             return;
         }
         /**
@@ -142,7 +156,6 @@ const DEFAULT_ANIMATION_DURATION = 300;
  *     <DataGrid maxHeight="400px" stickyHeader>
  *       <DataGridInfiniteBody
  *         data={largeData}
- *         batchSize={25}
  *         onVisibleCountChange={(count) => setVisibleCount(count)}
  *       >
  *         {(row) => (

package/dist/DataGridBody/index.js

@@ -1,5 +1,5 @@
 /*!
-  @versini/ui-datagrid v3.1.2
+  @versini/ui-datagrid v4.0.0
   © 2026 gizmette.com
 */
 

package/dist/DataGridCell/index.js

@@ -1,5 +1,5 @@
 /*!
-  @versini/ui-datagrid v3.1.2
+  @versini/ui-datagrid v4.0.0
   © 2026 gizmette.com
 */
 

package/dist/DataGridCellSort/index.js

@@ -1,5 +1,5 @@
 /*!
-  @versini/ui-datagrid v3.1.2
+  @versini/ui-datagrid v4.0.0
   © 2026 gizmette.com
 */
 

package/dist/DataGridConstants/index.js

@@ -1,5 +1,5 @@
 /*!
-  @versini/ui-datagrid v3.1.2
+  @versini/ui-datagrid v4.0.0
   © 2026 gizmette.com
 */
 

package/dist/DataGridFooter/index.js

@@ -1,5 +1,5 @@
 /*!
-  @versini/ui-datagrid v3.1.2
+  @versini/ui-datagrid v4.0.0
   © 2026 gizmette.com
 */
 
@@ -89,7 +89,9 @@ DataGridFooter.displayName = "DataGridFooter";
     return /*#__PURE__*/ jsx(DataGridContext.Provider, {
         value: {
             ...ctx,
-            cellWrapper: CellWrapper.FOOTER
+            cellWrapper: CellWrapper.FOOTER,
+            // Footer is the last row (= total rowCount) when virtualized.
+            ariaRowIndex: ctx.rowCount != null ? ctx.rowCount : undefined
         },
         children: /*#__PURE__*/ jsx("div", {
             ref: footerRef,

package/dist/DataGridHeader/index.js

@@ -1,5 +1,5 @@
 /*!
-  @versini/ui-datagrid v3.1.2
+  @versini/ui-datagrid v4.0.0
   © 2026 gizmette.com
 */
 
@@ -110,7 +110,9 @@ DataGridHeader.displayName = "DataGridHeader";
     return /*#__PURE__*/ jsx(DataGridContext.Provider, {
         value: {
             ...ctx,
-            cellWrapper: CellWrapper.HEADER
+            cellWrapper: CellWrapper.HEADER,
+            // Header is row 1 when the grid is virtualized (rowCount set).
+            ariaRowIndex: ctx.rowCount != null ? 1 : undefined
         },
         children: /*#__PURE__*/ jsxs("div", {
             ref: headerRef,