@versini/ui-datagrid 0.3.8 → 0.4.1

package/README.md

@@ -36,10 +36,7 @@ import { DataGridCell } from "@versini/ui-datagrid/cell";
 import { DataGridCellSort } from "@versini/ui-datagrid/cell-sort";
 
 // Infinite scroll (progressive loading)
-import {
-  useInfiniteScroll,
-  InfiniteScrollMarker
-} from "@versini/ui-datagrid/infinite";
+import { DataGridInfiniteBody } from "@versini/ui-datagrid/infinite";
 
 // Animated height wrapper
 import {
@@ -138,52 +135,122 @@ Supported column values include:
 
 ## Infinite Scroll
 
-For datasets with hundreds to thousands of rows, use progressive loading:
+For datasets with hundreds to thousands of rows, use `DataGridInfiniteBody` for progressive loading:
 
 ```tsx
+import { useState } from "react";
 import { DataGrid } from "@versini/ui-datagrid/datagrid";
 import { DataGridHeader } from "@versini/ui-datagrid/header";
-import { DataGridBody } from "@versini/ui-datagrid/body";
 import { DataGridRow } from "@versini/ui-datagrid/row";
 import { DataGridCell } from "@versini/ui-datagrid/cell";
-import {
-  useInfiniteScroll,
-  InfiniteScrollMarker
-} from "@versini/ui-datagrid/infinite";
+import { DataGridInfiniteBody } from "@versini/ui-datagrid/infinite";
 import { AnimatedWrapper } from "@versini/ui-datagrid/animated";
 
 function MyInfiniteTable({ data }) {
-  const { visibleCount, hasMore, markerRef } = useInfiniteScroll({
-    totalItems: data.length,
-    batchSize: 25
-  });
-
-  const visibleData = data.slice(0, visibleCount);
+  const [visibleCount, setVisibleCount] = useState(0);
 
   return (
     <AnimatedWrapper dependency={visibleCount}>
       <DataGrid maxHeight="500px" stickyHeader>
-        <DataGridHeader>
+        <DataGridHeader caption={`Showing ${visibleCount} of ${data.length}`}>
           <DataGridRow>
             <DataGridCell>Name</DataGridCell>
             <DataGridCell>Date</DataGridCell>
           </DataGridRow>
         </DataGridHeader>
-        <DataGridBody>
-          {visibleData.map((item) => (
+
+        <DataGridInfiniteBody
+          data={data}
+          batchSize={25}
+          threshold={5}
+          onVisibleCountChange={(count) => setVisibleCount(count)}
+        >
+          {(item) => (
             <DataGridRow key={item.id}>
               <DataGridCell>{item.name}</DataGridCell>
               <DataGridCell>{item.date}</DataGridCell>
             </DataGridRow>
-          ))}
-          {hasMore && <InfiniteScrollMarker ref={markerRef} colSpan={2} />}
-        </DataGridBody>
+          )}
+        </DataGridInfiniteBody>
       </DataGrid>
     </AnimatedWrapper>
   );
 }
 ```
 
+The `DataGridInfiniteBody` component handles all the complexity internally:
+- Progressive loading with IntersectionObserver
+- Correct marker placement for seamless scrolling (marker is placed `threshold` items before the end)
+- Automatic data slicing and memoization
+
+### Jump to Row
+
+Use the `scrollToIndex` imperative method to programmatically scroll to any row, even if it's not yet loaded:
+
+```tsx
+import { useRef, useState } from "react";
+import { DataGrid } from "@versini/ui-datagrid/datagrid";
+import { DataGridHeader } from "@versini/ui-datagrid/header";
+import { DataGridRow } from "@versini/ui-datagrid/row";
+import { DataGridCell } from "@versini/ui-datagrid/cell";
+import {
+  DataGridInfiniteBody,
+  type DataGridInfiniteBodyRef
+} from "@versini/ui-datagrid/infinite";
+
+function MyInfiniteTableWithJump({ data }) {
+  const [activeRowId, setActiveRowId] = useState(null);
+  const infiniteBodyRef = useRef<DataGridInfiniteBodyRef>(null);
+
+  const handleJumpToRow = (targetId) => {
+    // Find the index of the row with the target id
+    const targetIndex = data.findIndex((row) => row.id === targetId);
+    if (targetIndex !== -1) {
+      setActiveRowId(targetId);
+      infiniteBodyRef.current?.scrollToIndex(targetIndex);
+    }
+  };
+
+  return (
+    <div>
+      <button onClick={() => handleJumpToRow(1341)}>
+        Jump to row with id=1341
+      </button>
+
+      <DataGrid maxHeight="400px" stickyHeader>
+        <DataGridHeader>
+          <DataGridRow>
+            <DataGridCell>ID</DataGridCell>
+            <DataGridCell>Name</DataGridCell>
+          </DataGridRow>
+        </DataGridHeader>
+
+        <DataGridInfiniteBody
+          ref={infiniteBodyRef}
+          data={data}
+          batchSize={25}
+        >
+          {(item) => (
+            <DataGridRow
+              key={item.id}
+              active={activeRowId === item.id}
+              onClick={() => setActiveRowId(item.id)}
+            >
+              <DataGridCell>{item.id}</DataGridCell>
+              <DataGridCell>{item.name}</DataGridCell>
+            </DataGridRow>
+          )}
+        </DataGridInfiniteBody>
+      </DataGrid>
+    </div>
+  );
+}
+```
+
+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
+
 ## Sorting
 
 ```tsx
@@ -328,14 +395,24 @@ function MySortableTable({ data }) {
 | `className`       | `string`                                        | -              | CSS class for the cell              |
 | `buttonClassName` | `string`                                        | -              | CSS class for the sort button       |
 
-### useInfiniteScroll
+### DataGridInfiniteBody
+
+| Prop                   | Type                                        | Default | Description                                       |
+| ---------------------- | ------------------------------------------- | ------- | ------------------------------------------------- |
+| `data`                 | `T[]`                                       | **required** | The full dataset to render progressively     |
+| `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               |
+| `className`            | `string`                                    | -       | CSS class for the body element                    |
+| `ref`                  | `React.Ref<DataGridInfiniteBodyRef>`        | -       | Ref to access imperative methods                  |
+
+### DataGridInfiniteBodyRef (Imperative Handle)
 
-| Option       | Type     | Default      | Description                      |
-| ------------ | -------- | ------------ | -------------------------------- |
-| `totalItems` | `number` | **required** | Total number of items            |
-| `batchSize`  | `number` | `20`         | Items to load per batch          |
-| `threshold`  | `number` | `5`          | Items before end to trigger load |
-| `rootMargin` | `string` | `'20px'`     | IntersectionObserver margin      |
+| Method          | Signature                    | Description                                              |
+| --------------- | ---------------------------- | -------------------------------------------------------- |
+| `scrollToIndex` | `(index: number) => void`    | Scroll to a row by index. Expands visible count if needed, then smooth scrolls. |
 
 ## License
 

package/dist/DataGrid/DataGrid.js

@@ -1,5 +1,5 @@
 /*!
-  @versini/ui-datagrid v0.3.8
+  @versini/ui-datagrid v0.4.1
   © 2026 gizmette.com
 */
 

package/dist/DataGrid/DataGridContext.js

@@ -1,5 +1,5 @@
 /*!
-  @versini/ui-datagrid v0.3.8
+  @versini/ui-datagrid v0.4.1
   © 2026 gizmette.com
 */
 

package/dist/DataGrid/DataGridTypes.d.ts

@@ -0,0 +1,280 @@
+import type React from "react";
+type CSSLength = `${number}px` | `${number}rem` | `${number}em` | `${number}ch` | `${number}vw` | `${number}vh` | `${number}cm` | `${number}mm` | `${number}in` | `${number}pt` | `${number}pc`;
+type CSSPercentage = `${number}%`;
+type CSSFraction = `${number}fr`;
+type CSSVar = `var(${string})`;
+type CSSCalc = `calc(${string})`;
+type CSSClamp = `clamp(${string})`;
+type CSSFitContent = `fit-content(${CSSLength | CSSPercentage})`;
+type GridTrackPrimitive = CSSLength | CSSPercentage | CSSFraction | "auto" | "min-content" | "max-content" | "subgrid" | CSSFitContent | CSSVar | CSSCalc | CSSClamp;
+type CSSMinMax = `minmax(${GridTrackPrimitive}, ${GridTrackPrimitive})`;
+type CSSRepeat = `repeat(${number | "auto-fill" | "auto-fit"}, ${GridTrackPrimitive})`;
+export type DataGridColumnSize = GridTrackPrimitive | CSSMinMax | CSSRepeat;
+import type { BlurEffect, CellWrapperType, SortDirection, ThemeMode } from "../DataGridConstants/DataGridConstants";
+export type DataGridProps = {
+    /**
+     * The content of the DataGrid (DataGridHeader, DataGridBody, DataGridFooter).
+     */
+    children: React.ReactNode;
+    /**
+     * CSS class to apply to the data grid.
+     */
+    className?: string;
+    /**
+     * If true, the data grid will have reduced padding.
+     */
+    compact?: boolean;
+    /**
+     * If true, a frosty overlay will be placed above the data grid, blocking all
+     * interactions (sorting, scrolling, etc.). The content remains visible but
+     * slightly blurred with a spinner.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * The max height of the data grid. Required for sticky header/footer to work.
+     * Accepts any valid CSS max-height value.
+     */
+    maxHeight?: string;
+    /**
+     * The theme mode of the data grid. Controls colors and styling.
+     * @default "system"
+     */
+    mode?: ThemeMode;
+    /**
+     * If true, the data grid header will be sticky (stays visible when scrolling).
+     * Requires maxHeight to be set or wrapperClassName to be set with a
+     * max-height.
+     */
+    stickyHeader?: boolean;
+    /**
+     * If true, the data grid footer will be sticky (stays visible when scrolling).
+     * Requires maxHeight to be set or wrapperClassName to be set with a
+     * max-height.
+     */
+    stickyFooter?: boolean;
+    /**
+     * The blur effect intensity for sticky header/footer backgrounds.
+     * @default "none"
+     */
+    blurEffect?: BlurEffect;
+    /**
+     * This attribute defines an alternative text that summarizes the content of
+     * the data grid. Not visible but read by screen readers.
+     */
+    summary?: string;
+    /**
+     * CSS class to apply to the data grid wrapper container.
+     */
+    wrapperClassName?: string;
+    /**
+     * An array of CSS Grid track sizes that define the width of each column.
+     * Template-literal union covers common grid values (fr, %, px/em/rem/etc.,
+     * minmax(), fit-content(), repeat(auto-fill/fit, ...), var(), calc()) so
+     * obviously invalid strings are caught at compile time.
+     * @example ["1fr", "1fr", "auto"] - Two equal columns and one auto-sized column
+     * @example ["200px", "1fr", "min-content"] - Fixed, flexible, and content-sized columns
+     */
+    columns?: ReadonlyArray<DataGridColumnSize>;
+};
+export type DataGridHeaderProps = {
+    /**
+     * The content of the header (DataGridRow elements).
+     */
+    children: React.ReactNode;
+    /**
+     * This attribute defines the caption (or title) of the data grid. When
+     * provided, it will be rendered above the header row as part of the same
+     * block, so they stay together whether sticky or not.
+     */
+    caption?: React.ReactNode;
+    /**
+     * CSS class to apply to the caption element.
+     */
+    captionClassName?: string;
+    /**
+     * CSS class to apply to the header.
+     */
+    className?: string;
+} & React.HTMLAttributes<HTMLDivElement>;
+export type DataGridBodyProps = {
+    /**
+     * The content of the body (DataGridRow elements).
+     */
+    children: React.ReactNode;
+    /**
+     * CSS class to apply to the body.
+     */
+    className?: string;
+} & React.HTMLAttributes<HTMLDivElement>;
+export type DataGridFooterProps = {
+    /**
+     * The content of the footer (DataGridRow elements).
+     */
+    children: React.ReactNode;
+    /**
+     * CSS class to apply to the footer.
+     */
+    className?: string;
+} & React.HTMLAttributes<HTMLDivElement>;
+export type DataGridRowProps = {
+    /**
+     * The content of the row (DataGridCell elements).
+     */
+    children: React.ReactNode;
+    /**
+     * CSS class to apply to the row.
+     */
+    className?: string;
+    /**
+     * If true, the row will display a left border indicator to show it's active.
+     * @default false
+     */
+    active?: boolean;
+} & React.HTMLAttributes<HTMLDivElement>;
+export type DataGridCellProps = {
+    /**
+     * The content of the cell.
+     */
+    children?: React.ReactNode;
+    /**
+     * CSS class to apply to the cell.
+     */
+    className?: string;
+    /**
+     * Horizontal alignment of the cell content.
+     */
+    align?: "left" | "center" | "right";
+    /**
+     * If true, adds a vertical border on the left side of the cell.
+     */
+    borderLeft?: boolean;
+    /**
+     * If true, adds a vertical border on the right side of the cell.
+     */
+    borderRight?: boolean;
+    /**
+     * Number of columns the cell should span. Defaults to 1.
+     */
+    colSpan?: number;
+} & React.HTMLAttributes<HTMLDivElement>;
+export type DataGridCellSortProps = {
+    /**
+     * Unique identifier for the cell. Used to determine which column is sorted.
+     */
+    cellId: string;
+    /**
+     * The label text for the sortable column header.
+     */
+    children: string;
+    /**
+     * Handler called when the sort button is clicked. Receives the cellId and
+     * current direction (if sorted).
+     */
+    onSort?: (cellId: string, currentDirection?: SortDirection) => void;
+    /**
+     * The current sort direction.
+     */
+    sortDirection: SortDirection | false;
+    /**
+     * The cellId of the currently sorted column.
+     */
+    sortedCell: string;
+    /**
+     * Horizontal alignment of the cell content.
+     */
+    align?: "left" | "center" | "right";
+    /**
+     * CSS class to apply to the sort button.
+     */
+    buttonClassName?: string;
+    /**
+     * CSS class to apply to the cell.
+     */
+    className?: string;
+    /**
+     * The focus mode for the sort button.
+     * @default "alt-system"
+     */
+    focusMode?: ThemeMode;
+    /**
+     * The theme mode for the sort button.
+     * @default "alt-system"
+     */
+    mode?: ThemeMode;
+    /**
+     * Content to display on the left side of the label.
+     */
+    slotLeft?: React.ReactNode;
+    /**
+     * Content to display on the right side of the label.
+     */
+    slotRight?: React.ReactNode;
+} & React.HTMLAttributes<HTMLDivElement>;
+export type DataGridContextValue = {
+    mode: ThemeMode;
+    stickyHeader?: boolean;
+    stickyFooter?: boolean;
+    compact?: boolean;
+    blurEffect?: BlurEffect;
+    cellWrapper?: CellWrapperType;
+    /**
+     * CSS grid column sizes passed from DataGrid to rows.
+     */
+    columns?: ReadonlyArray<DataGridColumnSize>;
+    /**
+     * Measured column widths in pixels, reported by DataGridBody. Used by sticky
+     * header/footer to sync column widths since they can't use subgrid (being
+     * absolutely positioned).
+     */
+    measuredColumnWidths?: number[];
+    /**
+     * Callback for DataGridHeader to register its caption ID for accessibility.
+     * DataGrid uses this to set aria-labelledby on the grid element.
+     */
+    setCaptionId?: (id: string | undefined) => void;
+    /**
+     * Callback for DataGridHeader to register itself with the parent DataGrid.
+     * Used to enable sticky header behavior regardless of nesting depth.
+     */
+    registerHeader?: () => void;
+    /**
+     * Callback for DataGridHeader to unregister itself when unmounting.
+     */
+    unregisterHeader?: () => void;
+    /**
+     * Callback for DataGridFooter to register itself with the parent DataGrid.
+     * Used to enable sticky footer behavior regardless of nesting depth.
+     */
+    registerFooter?: () => void;
+    /**
+     * Callback for DataGridFooter to unregister itself when unmounting.
+     */
+    unregisterFooter?: () => void;
+    /**
+     * Callback for DataGridHeader to report its measured height. Used for dynamic
+     * padding calculation instead of hard-coded values.
+     */
+    setHeaderHeight?: (height: number) => void;
+    /**
+     * Callback for DataGridFooter to report its measured height. Used for dynamic
+     * padding calculation instead of hard-coded values.
+     */
+    setFooterHeight?: (height: number) => void;
+    /**
+     * Callback for DataGridBody to report measured column widths. Used to sync
+     * sticky header/footer columns with body columns.
+     */
+    setMeasuredColumnWidths?: (widths: number[]) => void;
+    /**
+     * Row index for explicit odd/even styling. Used by DataGridInfiniteBody where
+     * CSS :nth-child selectors don't work due to wrapper elements.
+     */
+    rowIndex?: number;
+    /**
+     * Whether this is the last row (for explicit border removal). Used by
+     * DataGridInfiniteBody where CSS :last-child doesn't work.
+     */
+    isLastRow?: boolean;
+};
+export {};

package/dist/DataGrid/DataGridTypes.js

@@ -0,0 +1,9 @@
+/*!
+  @versini/ui-datagrid v0.4.1
+  © 2026 gizmette.com
+*/
+
+
+;// CONCATENATED MODULE: ./src/DataGrid/DataGridTypes.ts
+
+

package/dist/DataGrid/index.js

@@ -1,5 +1,5 @@
 /*!
-  @versini/ui-datagrid v0.3.8
+  @versini/ui-datagrid v0.4.1
   © 2026 gizmette.com
 */
 

package/dist/DataGridAnimated/AnimatedWrapper.d.ts

@@ -28,16 +28,20 @@ export type AnimatedWrapperProps = {
  *
  * @example
  * ```tsx
- * const { visibleCount } = useInfiniteScroll({ totalItems: data.length });
+ * const [visibleCount, setVisibleCount] = useState(0);
  *
  * return (
  *   <AnimatedWrapper dependency={visibleCount}>
- *     <DataGrid>
- *       <DataGridBody>
- *         {data.slice(0, visibleCount).map((item) => (
- *           <DataGridRow key={item.id}>...</DataGridRow>
- *         ))}
- *       </DataGridBody>
+ *     <DataGrid maxHeight="400px" stickyHeader>
+ *       <DataGridInfiniteBody
+ *         data={largeData}
+ *         batchSize={25}
+ *         onVisibleCountChange={(count) => setVisibleCount(count)}
+ *       >
+ *         {(row) => (
+ *           <DataGridRow key={row.id}>...</DataGridRow>
+ *         )}
+ *       </DataGridInfiniteBody>
  *     </DataGrid>
  *   </AnimatedWrapper>
  * );

package/dist/DataGridAnimated/AnimatedWrapper.js

@@ -1,5 +1,5 @@
 /*!
-  @versini/ui-datagrid v0.3.8
+  @versini/ui-datagrid v0.4.1
   © 2026 gizmette.com
 */
 
@@ -18,16 +18,20 @@ import { useAnimatedHeight } from "./useAnimatedHeight.js";
  *
  * @example
  * ```tsx
- * const { visibleCount } = useInfiniteScroll({ totalItems: data.length });
+ * const [visibleCount, setVisibleCount] = useState(0);
  *
  * return (
  *   <AnimatedWrapper dependency={visibleCount}>
- *     <DataGrid>
- *       <DataGridBody>
- *         {data.slice(0, visibleCount).map((item) => (
- *           <DataGridRow key={item.id}>...</DataGridRow>
- *         ))}
- *       </DataGridBody>
+ *     <DataGrid maxHeight="400px" stickyHeader>
+ *       <DataGridInfiniteBody
+ *         data={largeData}
+ *         batchSize={25}
+ *         onVisibleCountChange={(count) => setVisibleCount(count)}
+ *       >
+ *         {(row) => (
+ *           <DataGridRow key={row.id}>...</DataGridRow>
+ *         )}
+ *       </DataGridInfiniteBody>
  *     </DataGrid>
  *   </AnimatedWrapper>
  * );

package/dist/DataGridAnimated/index.js

@@ -1,5 +1,5 @@
 /*!
-  @versini/ui-datagrid v0.3.8
+  @versini/ui-datagrid v0.4.1
   © 2026 gizmette.com
 */
 

package/dist/DataGridAnimated/useAnimatedHeight.js

@@ -1,5 +1,5 @@
 /*!
-  @versini/ui-datagrid v0.3.8
+  @versini/ui-datagrid v0.4.1
   © 2026 gizmette.com
 */
 

package/dist/DataGridBody/DataGridBody.js

@@ -1,86 +1,42 @@
 /*!
-  @versini/ui-datagrid v0.3.8
+  @versini/ui-datagrid v0.4.1
   © 2026 gizmette.com
 */
 
 import { jsx } from "react/jsx-runtime";
-import clsx from "clsx";
-import { useContext, useLayoutEffect, useRef } from "react";
+import { useContext, useRef } from "react";
 import { DataGridContext } from "../DataGrid/DataGridContext.js";
 import { CellWrapper } from "../DataGridConstants/index.js";
+import { getBodyClass } from "./getBodyClass.js";
+import { useColumnMeasurement } from "./useColumnMeasurement.js";
 
 ;// CONCATENATED MODULE: external "react/jsx-runtime"
 
-;// CONCATENATED MODULE: external "clsx"
-
 ;// CONCATENATED MODULE: external "react"
 
 ;// CONCATENATED MODULE: external "../DataGrid/DataGridContext.js"
 
 ;// CONCATENATED MODULE: external "../DataGridConstants/index.js"
 
+;// CONCATENATED MODULE: external "./getBodyClass.js"
+
+;// CONCATENATED MODULE: external "./useColumnMeasurement.js"
+
 ;// CONCATENATED MODULE: ./src/DataGridBody/DataGridBody.tsx
 
 
 
 
 
+
 /* =============================================================================
  * DataGridBody
  * ========================================================================== */ const DataGridBody = ({ className, children, ...rest })=>{
     const ctx = useContext(DataGridContext);
     const bodyRef = useRef(null);
-    /**
-	 * Measure column widths from the first body row's cells. This is needed
-	 * because sticky header/footer are absolutely positioned and can't use CSS
-	 * subgrid. We measure the body cells (which ARE in the grid flow) and report
-	 * the widths so header/footer can use the same pixel values.
-	 */ useLayoutEffect(()=>{
-        const element = bodyRef.current;
-        const needsMeasurement = ctx.columns && (ctx.stickyHeader || ctx.stickyFooter);
-        if (!element || !needsMeasurement || !ctx.setMeasuredColumnWidths) {
-            return;
-        }
-        /**
-		 * Find the first row and its cells once, reuse for both measurement and
-		 * observation.
-		 */ const firstRow = element.querySelector('[role="row"]');
-        if (!firstRow) {
-            return;
-        }
-        const cells = firstRow.querySelectorAll('[role="cell"], [role="columnheader"], [role="gridcell"]');
-        if (cells.length === 0) {
-            return;
-        }
-        const measureColumns = ()=>{
-            // Measure each cell's width.
-            const widths = Array.from(cells).map((cell)=>cell.getBoundingClientRect().width);
-            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.
-        for (const cell of cells){
-            observer.observe(cell);
-        }
-        return ()=>observer.disconnect();
-    }, [
-        ctx.columns,
-        ctx.stickyHeader,
-        ctx.stickyFooter,
-        ctx.setMeasuredColumnWidths,
-        children
-    ]);
-    /**
-	 * When columns are provided, use display:contents so the body doesn't
-	 * interfere with the grid flow. Rows will use subgrid.
-	 */ const bodyClass = ctx.columns ? clsx("contents", className) : clsx("flex flex-col", className);
+    // Measure column widths for sticky header/footer sync.
+    useColumnMeasurement(bodyRef, children);
+    const bodyClass = getBodyClass(Boolean(ctx.columns), className);
     return /*#__PURE__*/ jsx(DataGridContext.Provider, {
         value: {
             ...ctx,