@versini/ui-datagrid 0.2.0 → 0.2.2

package/README.md

@@ -4,6 +4,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
 - **Animated Height**: Smooth height transitions when content changes
 - **Sorting**: Built-in sorting utilities and sortable column headers
@@ -56,7 +57,9 @@ import {
   getNextSortConfig,
   getOppositeSortDirection,
   toggleSortDirection,
-  SortDirections
+  SortDirections,
+  type SortConfig,
+  type SortComparator
 } from "@versini/ui-datagrid/sorting";
 
 // Constants
@@ -99,6 +102,43 @@ function MyTable({ data }) {
 }
 ```
 
+## CSS Grid Columns
+
+Use the `columns` prop to define column widths with CSS Grid track sizes:
+
+```tsx
+<DataGrid
+  columns={["200px", "1fr", "auto"]}
+  maxHeight="400px"
+  stickyHeader
+>
+  <DataGridHeader caption="User List">
+    <DataGridRow>
+      <DataGridCell>Name</DataGridCell>
+      <DataGridCell>Email</DataGridCell>
+      <DataGridCell>Actions</DataGridCell>
+    </DataGridRow>
+  </DataGridHeader>
+  <DataGridBody>
+    {data.map((item) => (
+      <DataGridRow key={item.id}>
+        <DataGridCell>{item.name}</DataGridCell>
+        <DataGridCell>{item.email}</DataGridCell>
+        <DataGridCell>Edit</DataGridCell>
+      </DataGridRow>
+    ))}
+  </DataGridBody>
+</DataGrid>
+```
+
+Supported column values include:
+- Fixed sizes: `"200px"`, `"10rem"`, `"5em"`
+- Flexible sizes: `"1fr"`, `"2fr"`
+- Auto sizing: `"auto"`, `"min-content"`, `"max-content"`
+- Functions: `"minmax(100px, 1fr)"`, `"fit-content(200px)"`
+- Repeat: `"repeat(3, 1fr)"`, `"repeat(auto-fill, minmax(100px, 1fr))"`
+- CSS variables and calc: `"var(--col-width)"`, `"calc(100% - 200px)"`
+
 ## Infinite Scroll
 
 For datasets with hundreds to thousands of rows, use progressive loading:
@@ -229,16 +269,66 @@ function MySortableTable({ data }) {
 
 ### DataGrid
 
-| Prop           | Type                                            | Default    | Description                        |
-| -------------- | ----------------------------------------------- | ---------- | ---------------------------------- |
-| `mode`         | `'dark' \| 'light' \| 'system' \| 'alt-system'` | `'system'` | Theme mode                         |
-| `compact`      | `boolean`                                       | `false`    | Reduced padding                    |
-| `stickyHeader` | `boolean`                                       | `false`    | Fixed header while scrolling       |
-| `stickyFooter` | `boolean`                                       | `false`    | Fixed footer while scrolling       |
-| `blurEffect`   | `'none' \| 'small' \| 'medium' \| 'large'`      | `'none'`   | Blur intensity for sticky elements |
-| `maxHeight`    | `string`                                        | -          | Max height (required for sticky)   |
-| `disabled`     | `boolean`                                       | `false`    | Show loading overlay               |
-| `caption`      | `ReactNode`                                     | -          | Table caption for accessibility    |
+| Prop               | Type                                            | Default    | Description                                        |
+| ------------------ | ----------------------------------------------- | ---------- | -------------------------------------------------- |
+| `mode`             | `'dark' \| 'light' \| 'system' \| 'alt-system'` | `'system'` | Theme mode                                         |
+| `compact`          | `boolean`                                       | `false`    | Reduced padding                                    |
+| `stickyHeader`     | `boolean`                                       | `false`    | Fixed header while scrolling                       |
+| `stickyFooter`     | `boolean`                                       | `false`    | Fixed footer while scrolling                       |
+| `blurEffect`       | `'none' \| 'small' \| 'medium' \| 'large'`      | `'none'`   | Blur intensity for sticky elements                 |
+| `maxHeight`        | `string`                                        | -          | Max height (required for sticky)                   |
+| `disabled`         | `boolean`                                       | `false`    | Show loading overlay with spinner                  |
+| `columns`          | `string[]`                                      | -          | CSS Grid track sizes for column widths             |
+| `summary`          | `string`                                        | -          | Alternative text for screen readers                |
+| `className`        | `string`                                        | -          | CSS class for the grid element                     |
+| `wrapperClassName` | `string`                                        | -          | CSS class for the wrapper container                |
+
+### DataGridHeader
+
+| Prop               | Type        | Default | Description                       |
+| ------------------ | ----------- | ------- | --------------------------------- |
+| `caption`          | `ReactNode` | -       | Caption/title displayed above header row |
+| `captionClassName` | `string`    | -       | CSS class for the caption element |
+| `className`        | `string`    | -       | CSS class for the header          |
+
+### DataGridBody / DataGridFooter
+
+| Prop        | Type     | Default | Description              |
+| ----------- | -------- | ------- | ------------------------ |
+| `className` | `string` | -       | CSS class for the element |
+
+### DataGridRow
+
+| Prop        | Type      | Default | Description                          |
+| ----------- | --------- | ------- | ------------------------------------ |
+| `active`    | `boolean` | `false` | Show left border indicator           |
+| `className` | `string`  | -       | CSS class for the row                |
+
+### DataGridCell
+
+| Prop        | Type                           | Default | Description                   |
+| ----------- | ------------------------------ | ------- | ----------------------------- |
+| `align`     | `'left' \| 'center' \| 'right'`| `'left'`| Horizontal alignment          |
+| `colSpan`   | `number`                       | `1`     | Number of columns to span     |
+| `active`    | `boolean`                      | `false` | Show left border indicator    |
+| `className` | `string`                       | -       | CSS class for the cell        |
+
+### DataGridCellSort
+
+| Prop              | Type                                            | Default        | Description                          |
+| ----------------- | ----------------------------------------------- | -------------- | ------------------------------------ |
+| `cellId`          | `string`                                        | **required**   | Unique identifier for the column     |
+| `children`        | `string`                                        | **required**   | Label text for the column header     |
+| `onSort`          | `(cellId, direction?) => void`                  | -              | Handler when sort button is clicked  |
+| `sortDirection`   | `'asc' \| 'desc' \| false`                      | **required**   | Current sort direction               |
+| `sortedCell`      | `string`                                        | **required**   | ID of the currently sorted column    |
+| `align`           | `'left' \| 'center' \| 'right'`                 | `'left'`       | Horizontal alignment                 |
+| `mode`            | `'dark' \| 'light' \| 'system' \| 'alt-system'` | `'alt-system'` | Theme mode for sort button           |
+| `focusMode`       | `'dark' \| 'light' \| 'system' \| 'alt-system'` | `'alt-system'` | Focus mode for sort button           |
+| `slotLeft`        | `ReactNode`                                     | -              | Content to display left of label     |
+| `slotRight`       | `ReactNode`                                     | -              | Content to display right of label    |
+| `className`       | `string`                                        | -              | CSS class for the cell               |
+| `buttonClassName` | `string`                                        | -              | CSS class for the sort button        |
 
 ### useInfiniteScroll
 

package/dist/DataGrid/DataGrid.d.ts

@@ -1,2 +1,2 @@
 import type { DataGridProps } from "./DataGridTypes";
-export declare const DataGrid: ({ caption, className, wrapperClassName, children, mode, compact, stickyHeader, stickyFooter, blurEffect, maxHeight, disabled, columns, ...rest }: DataGridProps) => import("react/jsx-runtime").JSX.Element;
+export declare const DataGrid: ({ className, wrapperClassName, children, mode, compact, stickyHeader, stickyFooter, blurEffect, maxHeight, disabled, columns, ...rest }: DataGridProps) => import("react/jsx-runtime").JSX.Element;

package/dist/DataGrid/DataGrid.js

@@ -1,10 +1,10 @@
 /*!
-  @versini/ui-datagrid v0.2.0
+  @versini/ui-datagrid v0.2.2
   © 2026 gizmette.com
 */
 
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { useId, useMemo } from "react";
+import { Children, isValidElement, useCallback, useMemo, useState } from "react";
 import { BlurEffects } from "../DataGridConstants/DataGridConstants.js";
 import { DataGridContext } from "./DataGridContext.js";
 import { getDataGridClasses } from "./utilities.js";
@@ -25,47 +25,89 @@ import { getDataGridClasses } from "./utilities.js";
 
 
 
+/**
+ * Helper to check component type by displayName.
+ * This allows tree-shaking since we don't need to import the actual component.
+ */ const isComponentType = (child, displayName)=>{
+    if (!/*#__PURE__*/ isValidElement(child)) {
+        return false;
+    }
+    const type = child.type;
+    return type?.displayName === displayName;
+};
 /* =============================================================================
  * DataGrid (main component)
- * ========================================================================== */ const DataGrid = ({ caption, className, wrapperClassName, children, mode = "system", compact = false, stickyHeader = false, stickyFooter = false, blurEffect = BlurEffects.NONE, maxHeight, disabled = false, columns, ...rest })=>{
-    const captionId = useId();
+ * ========================================================================== */ const DataGrid = ({ className, wrapperClassName, children, mode = "system", compact = false, stickyHeader = false, stickyFooter = false, blurEffect = BlurEffects.NONE, maxHeight, disabled = false, columns, ...rest })=>{
+    /**
+	 * Auto-detect if DataGridHeader and DataGridFooter children exist.
+	 * This prevents applying sticky styles when the component doesn't exist.
+	 * Uses displayName comparison to enable tree-shaking.
+	 */ const hasHeader = useMemo(()=>{
+        return Children.toArray(children).some((child)=>isComponentType(child, "DataGridHeader"));
+    }, [
+        children
+    ]);
+    const hasFooter = useMemo(()=>{
+        return Children.toArray(children).some((child)=>isComponentType(child, "DataGridFooter"));
+    }, [
+        children
+    ]);
+    /**
+	 * 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 && hasHeader;
+    const effectiveStickyFooter = stickyFooter && hasFooter;
+    /**
+	 * Auto-detect if any DataGridHeader child has a caption prop.
+	 * This eliminates the need for a separate hasCaption prop.
+	 */ const hasCaption = useMemo(()=>{
+        return Children.toArray(children).some((child)=>isComponentType(child, "DataGridHeader") && /*#__PURE__*/ isValidElement(child) && Boolean(child.props.caption));
+    }, [
+        children
+    ]);
+    /**
+	 * State to hold the caption ID registered by DataGridHeader.
+	 * Used for aria-labelledby on the grid element for accessibility.
+	 */ const [captionId, setCaptionId] = useState(undefined);
+    const handleSetCaptionId = useCallback((id)=>{
+        setCaptionId(id);
+    }, []);
     const classes = useMemo(()=>getDataGridClasses({
             mode,
             className,
             wrapperClassName,
-            stickyHeader,
-            stickyFooter,
+            stickyHeader: effectiveStickyHeader,
+            stickyFooter: effectiveStickyFooter,
             disabled,
-            hasCaption: Boolean(caption),
+            hasCaption,
             hasColumns: Boolean(columns)
         }), [
         mode,
         className,
         wrapperClassName,
-        stickyHeader,
-        stickyFooter,
+        effectiveStickyHeader,
+        effectiveStickyFooter,
         disabled,
-        caption,
+        hasCaption,
         columns
     ]);
     const contextValue = useMemo(()=>({
             mode,
             compact,
-            stickyHeader,
-            stickyFooter,
+            stickyHeader: effectiveStickyHeader,
+            stickyFooter: effectiveStickyFooter,
             blurEffect,
-            disabled,
-            hasCaption: Boolean(caption),
-            columns
+            columns,
+            setCaptionId: handleSetCaptionId
         }), [
         mode,
         compact,
-        stickyHeader,
-        stickyFooter,
+        effectiveStickyHeader,
+        effectiveStickyFooter,
         blurEffect,
-        disabled,
-        caption,
-        columns
+        columns,
+        handleSetCaptionId
     ]);
     const wrapperStyle = maxHeight ? {
         maxHeight: typeof maxHeight === "number" ? `${maxHeight}px` : maxHeight
@@ -74,7 +116,7 @@ import { getDataGridClasses } from "./utilities.js";
 	 * 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 = stickyHeader || stickyFooter;
+	 */ 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.
@@ -83,8 +125,8 @@ import { getDataGridClasses } from "./utilities.js";
     } : undefined;
     const gridContent = /*#__PURE__*/ jsx("div", {
         role: "grid",
+        "aria-labelledby": captionId,
         className: classes.grid,
-        "aria-labelledby": caption ? captionId : undefined,
         style: gridStyle,
         ...rest,
         children: children
@@ -113,21 +155,14 @@ import { getDataGridClasses } from "./utilities.js";
                         })
                     ]
                 }),
-                /*#__PURE__*/ jsxs("div", {
+                /*#__PURE__*/ jsx("div", {
                     className: classes.wrapper,
                     style: wrapperStyle,
-                    children: [
-                        caption && /*#__PURE__*/ jsx("div", {
-                            id: captionId,
-                            className: classes.caption,
-                            children: caption
-                        }),
-                        hasSticky ? /*#__PURE__*/ jsx("div", {
-                            className: classes.scrollableContent,
-                            style: wrapperStyle,
-                            children: gridContent
-                        }) : gridContent
-                    ]
+                    children: hasSticky ? /*#__PURE__*/ jsx("div", {
+                        className: classes.scrollableContent,
+                        style: wrapperStyle,
+                        children: gridContent
+                    }) : gridContent
                 })
             ]
         })

package/dist/DataGrid/DataGridContext.js

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

package/dist/DataGrid/index.js

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

package/dist/DataGrid/utilities.d.ts

@@ -1,22 +1,11 @@
-import { type BlurEffect, type ThemeMode } from "../DataGridConstants/DataGridConstants";
-/**
- * Common classes for sticky header/footer with optional blur effect.
- */
-export declare const getStickyBlurClasses: ({ blurEffect, }: {
-    blurEffect?: BlurEffect;
-}) => string;
-export declare const getCaptionBackgroundClasses: ({ mode }: {
-    mode: ThemeMode;
-}) => string;
-export declare const getCaptionCopyClasses: ({ mode }: {
-    mode: ThemeMode;
-}) => string;
+import { type ThemeMode } from "../DataGridConstants/DataGridConstants";
 /**
  * Generates classes for the main DataGrid wrapper and grid. When sticky
- * header/footer is enabled, uses the Panel-like approach:
+ * header/footer is enabled:
  * - Outer wrapper has overflow-hidden
- * - Scrollable area is a separate inner container
- * - Header/footer are absolutely positioned overlays
+ * - Scrollable area is a separate inner container with padding for header/footer
+ * - Header/footer use position:absolute to overlay scrollbar
+ * - Padding is auto-calculated based on whether caption is present
  *
  * When columns prop is provided, the grid uses CSS Grid layout with subgrid
  * support for proper column alignment across all rows.
@@ -37,10 +26,10 @@ export declare const getDataGridClasses: ({ mode, className, wrapperClassName, s
     spinner: string;
     wrapper: string;
     /**
-     * Scrollable content area - like Panel's scrollableContent Has padding to
-     * make room for absolutely positioned header/footer rounded-[inherit] clips
-     * the scrollbar at the rounded corners.
-     * When there's a caption, add extra padding for caption (~36px) + header (~40px).
+     * Scrollable content area with padding for absolute-positioned header/footer.
+     * Header height varies based on whether caption is present:
+     * - pt-10 (40px): header row only
+     * - pt-19 (76px): header row + caption
      */
     scrollableContent: string;
     /**
@@ -48,5 +37,4 @@ export declare const getDataGridClasses: ({ mode, className, wrapperClassName, s
      * consistent column alignment. Otherwise, use flexbox.
      */
     grid: string;
-    caption: string;
 };

package/dist/DataGrid/utilities.js

@@ -1,18 +1,14 @@
 /*!
-  @versini/ui-datagrid v0.2.0
+  @versini/ui-datagrid v0.2.2
   © 2026 gizmette.com
 */
 
 import clsx from "clsx";
-import { BlurEffects } from "../DataGridConstants/DataGridConstants.js";
 
 ;// CONCATENATED MODULE: external "clsx"
 
-;// CONCATENATED MODULE: external "../DataGridConstants/DataGridConstants.js"
-
 ;// CONCATENATED MODULE: ./src/DataGrid/utilities.ts
 
-
 /**
  * Generates classes for the loading spinner.
  */ const getSpinnerClasses = ({ mode })=>{
@@ -35,37 +31,13 @@ import { BlurEffects } from "../DataGridConstants/DataGridConstants.js";
         })
     };
 };
-/**
- * Common classes for sticky header/footer with optional blur effect.
- */ const getStickyBlurClasses = ({ blurEffect })=>{
-    return clsx({
-        "backdrop-blur-sm": blurEffect === BlurEffects.SMALL,
-        "backdrop-blur-md": blurEffect === BlurEffects.MEDIUM,
-        "backdrop-blur-lg": blurEffect === BlurEffects.LARGE
-    });
-};
-const getCaptionBackgroundClasses = ({ mode })=>{
-    return clsx({
-        "bg-surface-darker": mode === "dark" || mode === "system",
-        "bg-surface-light": mode === "light" || mode === "alt-system",
-        "dark:bg-surface-light": mode === "system",
-        "dark:bg-surface-darker": mode === "alt-system"
-    });
-};
-const getCaptionCopyClasses = ({ mode })=>{
-    return clsx({
-        "text-copy-light": mode === "dark",
-        "text-copy-dark": mode === "light",
-        "text-copy-light dark:text-copy-dark": mode === "system",
-        "text-copy-dark dark:text-copy-light": mode === "alt-system"
-    });
-};
 /**
  * Generates classes for the main DataGrid wrapper and grid. When sticky
- * header/footer is enabled, uses the Panel-like approach:
+ * header/footer is enabled:
  * - Outer wrapper has overflow-hidden
- * - Scrollable area is a separate inner container
- * - Header/footer are absolutely positioned overlays
+ * - Scrollable area is a separate inner container with padding for header/footer
+ * - Header/footer use position:absolute to overlay scrollbar
+ * - Padding is auto-calculated based on whether caption is present
  *
  * When columns prop is provided, the grid uses CSS Grid layout with subgrid
  * support for proper column alignment across all rows.
@@ -93,10 +65,10 @@ const getCaptionCopyClasses = ({ mode })=>{
             "text-copy-dark dark:text-copy-light": mode === "alt-system"
         }, wrapperClassName),
         /**
-		 * Scrollable content area - like Panel's scrollableContent Has padding to
-		 * make room for absolutely positioned header/footer rounded-[inherit] clips
-		 * the scrollbar at the rounded corners.
-		 * When there's a caption, add extra padding for caption (~36px) + header (~40px).
+		 * Scrollable content area with padding for absolute-positioned header/footer.
+		 * Header height varies based on whether caption is present:
+		 * - pt-10 (40px): header row only
+		 * - pt-19 (76px): header row + caption
 		 */ scrollableContent: clsx("overflow-y-auto overflow-x-hidden rounded-[inherit]", {
             "pt-10": stickyHeader && !hasCaption,
             "pt-19": stickyHeader && hasCaption,
@@ -110,16 +82,8 @@ const getCaptionCopyClasses = ({ mode })=>{
             "text-copy-dark": mode === "light",
             "text-copy-light dark:text-copy-dark": mode === "system",
             "text-copy-dark dark:text-copy-light": mode === "alt-system"
-        }),
-        caption: clsx("py-2 text-sm text-center font-bold", {
-            // When stickyHeader is enabled, caption is absolutely positioned at top
-            "absolute left-0 right-0 z-20 top-0 rounded-t-lg": stickyHeader
-        }, getCaptionBackgroundClasses({
-            mode
-        }), getCaptionCopyClasses({
-            mode
-        }))
+        })
     };
 };
 
-export { getCaptionBackgroundClasses, getCaptionCopyClasses, getDataGridClasses, getStickyBlurClasses };
+export { getDataGridClasses };

package/dist/DataGridAnimated/AnimatedWrapper.js

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

package/dist/DataGridAnimated/index.js

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

package/dist/DataGridAnimated/useAnimatedHeight.js

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

package/dist/DataGridBody/DataGridBody.js

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

package/dist/DataGridBody/index.js

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

package/dist/DataGridCell/DataGridCell.js

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

package/dist/DataGridCell/index.js

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

package/dist/DataGridCellSort/DataGridCellSort.js

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

package/dist/DataGridCellSort/index.js

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

package/dist/DataGridConstants/DataGridConstants.js

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

package/dist/DataGridConstants/index.js

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

package/dist/DataGridFooter/DataGridFooter.d.ts

@@ -13,4 +13,7 @@ export declare const getFooterClasses: ({ className, stickyFooter, mode, blurEff
     hasColumns?: boolean;
     stickyFooter?: boolean;
 }) => string;
-export declare const DataGridFooter: ({ className, children, ...rest }: DataGridFooterProps) => import("react/jsx-runtime").JSX.Element;
+export declare const DataGridFooter: {
+    ({ className, children, ...rest }: DataGridFooterProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/DataGridFooter/DataGridFooter.js

@@ -1,21 +1,21 @@
 /*!
-  @versini/ui-datagrid v0.2.0
+  @versini/ui-datagrid v0.2.2
   © 2026 gizmette.com
 */
 
 import { jsx } from "react/jsx-runtime";
 import clsx from "clsx";
+import { getHeaderFooterBackgroundClasses, getStickyBlurClasses } from "../common/utilities.js";
 import { DataGridContext } from "../DataGrid/DataGridContext.js";
-import { getStickyBlurClasses } from "../DataGrid/utilities.js";
 import { BlurEffects, CellWrapper } from "../DataGridConstants/DataGridConstants.js";
 
 ;// CONCATENATED MODULE: external "react/jsx-runtime"
 
 ;// CONCATENATED MODULE: external "clsx"
 
-;// CONCATENATED MODULE: external "../DataGrid/DataGridContext.js"
+;// CONCATENATED MODULE: external "../common/utilities.js"
 
-;// CONCATENATED MODULE: external "../DataGrid/utilities.js"
+;// CONCATENATED MODULE: external "../DataGrid/DataGridContext.js"
 
 ;// CONCATENATED MODULE: external "../DataGridConstants/DataGridConstants.js"
 
@@ -37,7 +37,7 @@ import { BlurEffects, CellWrapper } from "../DataGridConstants/DataGridConstants
 	 */ if (hasColumns && !stickyFooter) {
         return clsx("contents", className);
     }
-    const hasBlur = blurEffect && blurEffect !== BlurEffects.NONE;
+    const hasBlur = Boolean(blurEffect && blurEffect !== BlurEffects.NONE);
     return clsx("flex flex-col", {
         /**
 			 * Absolute positioning like Panel's footer: absolute left-0 right-0 z-20
@@ -47,18 +47,12 @@ import { BlurEffects, CellWrapper } from "../DataGridConstants/DataGridConstants
         "shadow-[rgb(190_190_190_/20%)_0_-0.5rem_1rem]": stickyFooter && mode === "dark",
         "shadow-[rgb(190_190_190_/20%)_0_-0.5rem_1rem] dark:shadow-[rgb(65_65_65_/30%)_0_-0.5rem_1rem]": stickyFooter && mode === "system",
         "shadow-[rgb(65_65_65_/30%)_0_-0.5rem_1rem]": stickyFooter && mode === "light",
-        "shadow-[rgb(65_65_65_/30%)_0_-0.5rem_1rem] dark:shadow-[rgb(190_190_190_/20%)_0_-0.5rem_1rem]": stickyFooter && mode === "alt-system",
-        // Semi-transparent backgrounds for blur effect.
-        "bg-table-head-dark/50": hasBlur && stickyFooter && (mode === "dark" || mode === "system"),
-        "bg-table-head-light/50": hasBlur && stickyFooter && (mode === "light" || mode === "alt-system"),
-        "dark:bg-table-head-light/50": hasBlur && stickyFooter && mode === "system",
-        "dark:bg-table-head-dark/50": hasBlur && stickyFooter && mode === "alt-system",
-        // Solid backgrounds when no blur effect.
-        "bg-table-head-dark": !hasBlur && stickyFooter && (mode === "dark" || mode === "system"),
-        "bg-table-head-light": !hasBlur && stickyFooter && (mode === "light" || mode === "alt-system"),
-        "dark:bg-table-head-light": !hasBlur && stickyFooter && mode === "system",
-        "dark:bg-table-head-dark": !hasBlur && stickyFooter && mode === "alt-system"
-    }, stickyFooter && getStickyBlurClasses({
+        "shadow-[rgb(65_65_65_/30%)_0_-0.5rem_1rem] dark:shadow-[rgb(190_190_190_/20%)_0_-0.5rem_1rem]": stickyFooter && mode === "alt-system"
+    }, getHeaderFooterBackgroundClasses({
+        mode,
+        hasBlur,
+        sticky: Boolean(stickyFooter)
+    }), stickyFooter && getStickyBlurClasses({
         blurEffect
     }), className);
 };
@@ -88,5 +82,6 @@ import { BlurEffects, CellWrapper } from "../DataGridConstants/DataGridConstants
             })
     });
 };
+DataGridFooter.displayName = "DataGridFooter";
 
 export { DataGridFooter, getFooterClasses };

package/dist/DataGridFooter/index.js

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

package/dist/DataGridHeader/DataGridHeader.d.ts

@@ -1,18 +1,31 @@
 import type { DataGridHeaderProps } from "../DataGrid/DataGridTypes";
 import { type BlurEffect, type ThemeMode } from "../DataGridConstants/DataGridConstants";
 /**
- * Generates classes for the DataGridHeader. Uses absolute positioning like
- * Panel - header floats above the scrollable content.
+ * Generates classes for the DataGridHeader wrapper.
  *
- * When columns are provided (subgrid mode), uses display:contents so the
- * header doesn't break the parent grid flow.
+ * When stickyHeader is true, uses position:absolute so the header overlays
+ * the scrollbar area. The parent DataGrid auto-detects caption presence and
+ * applies appropriate padding to the scrollable content.
+ *
+ * When columns are provided (subgrid mode) and not sticky, uses display:contents
+ * so the header doesn't break the parent grid flow.
  */
-export declare const getHeaderClasses: ({ className, stickyHeader, mode, blurEffect, hasCaption, hasColumns, }: {
+export declare const getHeaderClasses: ({ className, stickyHeader, mode, blurEffect, hasColumns, }: {
     mode: ThemeMode;
     blurEffect?: BlurEffect;
     className?: string;
-    hasCaption?: boolean;
     hasColumns?: boolean;
     stickyHeader?: boolean;
 }) => string;
-export declare const DataGridHeader: ({ className, children, ...rest }: DataGridHeaderProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * Generates classes for the caption element inside DataGridHeader.
+ * When hasColumns is true (subgrid mode), adds col-span-full to span all columns.
+ */
+export declare const getCaptionClasses: ({ captionClassName, hasColumns, }: {
+    captionClassName?: string;
+    hasColumns?: boolean;
+}) => string;
+export declare const DataGridHeader: {
+    ({ caption, captionClassName, className, children, ...rest }: DataGridHeaderProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/DataGridHeader/DataGridHeader.js

@@ -1,21 +1,24 @@
 /*!
-  @versini/ui-datagrid v0.2.0
+  @versini/ui-datagrid v0.2.2
   © 2026 gizmette.com
 */
 
-import { jsx } from "react/jsx-runtime";
+import { jsx, jsxs } from "react/jsx-runtime";
 import clsx from "clsx";
+import { useEffect, useId } from "react";
+import { getHeaderFooterBackgroundClasses, getHeaderFooterCopyClasses, getStickyBlurClasses } from "../common/utilities.js";
 import { DataGridContext } from "../DataGrid/DataGridContext.js";
-import { getCaptionBackgroundClasses, getCaptionCopyClasses, getStickyBlurClasses } from "../DataGrid/utilities.js";
-import { CellWrapper } from "../DataGridConstants/DataGridConstants.js";
+import { BlurEffects, CellWrapper } from "../DataGridConstants/DataGridConstants.js";
 
 ;// CONCATENATED MODULE: external "react/jsx-runtime"
 
 ;// CONCATENATED MODULE: external "clsx"
 
-;// CONCATENATED MODULE: external "../DataGrid/DataGridContext.js"
+;// CONCATENATED MODULE: external "react"
+
+;// CONCATENATED MODULE: external "../common/utilities.js"
 
-;// CONCATENATED MODULE: external "../DataGrid/utilities.js"
+;// CONCATENATED MODULE: external "../DataGrid/DataGridContext.js"
 
 ;// CONCATENATED MODULE: external "../DataGridConstants/DataGridConstants.js"
 
@@ -25,60 +28,115 @@ import { CellWrapper } from "../DataGridConstants/DataGridConstants.js";
 
 
 
+
 /**
- * Generates classes for the DataGridHeader. Uses absolute positioning like
- * Panel - header floats above the scrollable content.
+ * Generates classes for the DataGridHeader wrapper.
  *
- * When columns are provided (subgrid mode), uses display:contents so the
- * header doesn't break the parent grid flow.
- */ const getHeaderClasses = ({ className, stickyHeader, mode, blurEffect, hasCaption, hasColumns })=>{
+ * When stickyHeader is true, uses position:absolute so the header overlays
+ * the scrollbar area. The parent DataGrid auto-detects caption presence and
+ * applies appropriate padding to the scrollable content.
+ *
+ * When columns are provided (subgrid mode) and not sticky, uses display:contents
+ * so the header doesn't break the parent grid flow.
+ */ const getHeaderClasses = ({ className, stickyHeader, mode, blurEffect, hasColumns })=>{
+    const hasBlur = Boolean(blurEffect && blurEffect !== BlurEffects.NONE);
     /**
 	 * When columns are provided and not sticky, use display:contents so the
 	 * rowgroup doesn't interfere with the grid flow. The rows will use subgrid.
 	 */ if (hasColumns && !stickyHeader) {
-        return clsx("contents", getCaptionBackgroundClasses({
-            mode
-        }), getCaptionCopyClasses({
+        return clsx("contents", getHeaderFooterBackgroundClasses({
+            mode,
+            hasBlur,
+            sticky: Boolean(stickyHeader)
+        }), getHeaderFooterCopyClasses({
             mode
         }), className);
     }
     return clsx("flex flex-col", {
-        "absolute left-0 right-0 z-20": stickyHeader,
-        "top-0": stickyHeader && !hasCaption,
-        "top-9": stickyHeader && hasCaption,
-        "rounded-t-lg": stickyHeader && !hasCaption
-    }, getCaptionBackgroundClasses({
-        mode
-    }), getCaptionCopyClasses({
+        // Absolute positioning to overlay scrollbar, matching footer behavior
+        "absolute left-0 right-0 z-20 top-0 rounded-t-lg": stickyHeader
+    }, getHeaderFooterBackgroundClasses({
+        mode,
+        hasBlur,
+        sticky: Boolean(stickyHeader)
+    }), getHeaderFooterCopyClasses({
         mode
     }), stickyHeader && getStickyBlurClasses({
         blurEffect
     }), className);
 };
+/**
+ * Generates classes for the caption element inside DataGridHeader.
+ * When hasColumns is true (subgrid mode), adds col-span-full to span all columns.
+ */ const getCaptionClasses = ({ captionClassName, hasColumns })=>{
+    return clsx("py-2 text-sm text-center font-bold", // In subgrid mode, caption needs to span all columns
+    hasColumns && "col-span-full", captionClassName);
+};
 /* =============================================================================
  * DataGridHeader
- * ========================================================================== */ const DataGridHeader = ({ className, children, ...rest })=>{
+ * ========================================================================== */ const DataGridHeader = ({ caption, captionClassName, className, children, ...rest })=>{
+    const captionId = useId();
     return /*#__PURE__*/ jsx(DataGridContext.Consumer, {
-        children: (ctx)=>/*#__PURE__*/ jsx(DataGridContext.Provider, {
-                value: {
-                    ...ctx,
-                    cellWrapper: CellWrapper.HEADER
-                },
-                children: /*#__PURE__*/ jsx("div", {
-                    role: "rowgroup",
-                    className: getHeaderClasses({
-                        className,
-                        stickyHeader: ctx.stickyHeader,
-                        mode: ctx.mode,
-                        blurEffect: ctx.blurEffect,
-                        hasCaption: ctx.hasCaption,
-                        hasColumns: Boolean(ctx.columns)
-                    }),
-                    ...rest,
-                    children: children
-                })
+        children: (ctx)=>/*#__PURE__*/ jsx(DataGridHeaderInner, {
+                caption: caption,
+                captionClassName: captionClassName,
+                captionId: captionId,
+                className: className,
+                ctx: ctx,
+                ...rest,
+                children: children
             })
     });
 };
+DataGridHeader.displayName = "DataGridHeader";
+/**
+ * Inner component to handle the useEffect for registering captionId.
+ * Separated to avoid hooks inside Consumer render prop.
+ */ const DataGridHeaderInner = ({ caption, captionClassName, captionId, className, ctx, children, ...rest })=>{
+    const hasColumns = Boolean(ctx.columns);
+    // Register the caption ID with the parent DataGrid for aria-labelledby
+    useEffect(()=>{
+        if (caption && ctx.setCaptionId) {
+            ctx.setCaptionId(captionId);
+        }
+        return ()=>{
+            if (ctx.setCaptionId) {
+                ctx.setCaptionId(undefined);
+            }
+        };
+    }, [
+        caption,
+        captionId,
+        ctx.setCaptionId
+    ]);
+    return /*#__PURE__*/ jsx(DataGridContext.Provider, {
+        value: {
+            ...ctx,
+            cellWrapper: CellWrapper.HEADER
+        },
+        children: /*#__PURE__*/ jsxs("div", {
+            role: "rowgroup",
+            className: getHeaderClasses({
+                className,
+                stickyHeader: ctx.stickyHeader,
+                mode: ctx.mode,
+                blurEffect: ctx.blurEffect,
+                hasColumns
+            }),
+            ...rest,
+            children: [
+                caption && /*#__PURE__*/ jsx("div", {
+                    id: captionId,
+                    className: getCaptionClasses({
+                        captionClassName,
+                        hasColumns
+                    }),
+                    children: caption
+                }),
+                children
+            ]
+        })
+    });
+};
 
-export { DataGridHeader, getHeaderClasses };
+export { DataGridHeader, getCaptionClasses, getHeaderClasses };

package/dist/DataGridHeader/index.js

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

package/dist/DataGridInfinite/InfiniteScrollMarker.js

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

package/dist/DataGridInfinite/index.js

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

package/dist/DataGridInfinite/useInfiniteScroll.js

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

package/dist/DataGridRow/DataGridRow.js

@@ -1,5 +1,5 @@
 /*!
-  @versini/ui-datagrid v0.2.0
+  @versini/ui-datagrid v0.2.2
   © 2026 gizmette.com
 */
 
@@ -25,25 +25,14 @@ import { CellWrapper } from "../DataGridConstants/index.js";
 
 
 
-const getRowClasses = ({ mode, className, cellWrapper, stickyHeader, stickyFooter })=>{
+const getRowClasses = ({ mode, className, cellWrapper })=>{
     // Always use CSS Grid for proper column alignment, with vertical centering
     const layoutClass = "grid items-center";
     if (cellWrapper === CellWrapper.HEADER || cellWrapper === CellWrapper.FOOTER) {
         /**
 		 * When in a sticky header/footer, don't apply background to row since the
 		 * background is applied to the rowgroup for blur effect to work.
-		 */ const isSticky = cellWrapper === CellWrapper.HEADER && stickyHeader || cellWrapper === CellWrapper.FOOTER && stickyFooter;
-        if (isSticky) {
-            // No background on row - it's on the rowgroup.
-            return clsx(layoutClass, className);
-        }
-        // Non-sticky header/footer still gets background on row.
-        return clsx(layoutClass, {
-            "bg-table-head-dark": mode === "dark" || mode === "system",
-            "bg-table-head-light": mode === "light" || mode === "alt-system",
-            "dark:bg-table-head-light": mode === "system",
-            "dark:bg-table-head-dark": mode === "alt-system"
-        }, className);
+		 */ return clsx(layoutClass, className);
     }
     return clsx(layoutClass, "border-b last:border-0", {
         "border-table-dark": mode === "dark" || mode === "system",
@@ -57,7 +46,7 @@ const getRowClasses = ({ mode, className, cellWrapper, stickyHeader, stickyFoote
         "odd:bg-table-dark-odd even:bg-table-dark-even dark:odd:bg-table-light-odd dark:even:bg-table-light-even": mode === "system",
         "hover:bg-table-dark-hover dark:hover:bg-table-light-hover": mode === "system",
         "odd:bg-table-light-odd even:bg-table-light-even dark:odd:bg-table-dark-odd dark:even:bg-table-dark-even": mode === "alt-system",
-        "hover:bg-table-light-hover dark:hover:bg-table-dark-hover": mode === "alt-system"
+        "hover:bg-table-light-hover dark::hover:bg-table-dark-hover": mode === "alt-system"
     }, className);
 };
 /* =============================================================================
@@ -109,9 +98,7 @@ const getRowClasses = ({ mode, className, cellWrapper, stickyHeader, stickyFoote
                 className: getRowClasses({
                     mode,
                     className,
-                    cellWrapper,
-                    stickyHeader,
-                    stickyFooter
+                    cellWrapper
                 }),
                 style: {
                     ...rowStyle,

package/dist/DataGridRow/index.js

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

package/dist/DataGridSorting/index.js

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

package/dist/DataGridSorting/sortingUtils.js

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

package/dist/common/utilities.d.ts

@@ -0,0 +1,15 @@
+import { type BlurEffect, type ThemeMode } from "../DataGridConstants/DataGridConstants";
+export declare const getHeaderFooterBackgroundClasses: ({ mode, hasBlur, sticky, }: {
+    mode: ThemeMode;
+    hasBlur: boolean;
+    sticky: boolean;
+}) => string;
+export declare const getHeaderFooterCopyClasses: ({ mode }: {
+    mode: ThemeMode;
+}) => string;
+/**
+ * Common classes for sticky header/footer with optional blur effect.
+ */
+export declare const getStickyBlurClasses: ({ blurEffect, }: {
+    blurEffect?: BlurEffect;
+}) => string;

package/dist/common/utilities.js

@@ -0,0 +1,48 @@
+/*!
+  @versini/ui-datagrid v0.2.2
+  © 2026 gizmette.com
+*/
+
+import clsx from "clsx";
+import { BlurEffects } from "../DataGridConstants/DataGridConstants.js";
+
+;// CONCATENATED MODULE: external "clsx"
+
+;// CONCATENATED MODULE: external "../DataGridConstants/DataGridConstants.js"
+
+;// CONCATENATED MODULE: ./src/common/utilities.ts
+
+
+const getHeaderFooterBackgroundClasses = ({ mode, hasBlur, sticky })=>{
+    return clsx({
+        // Semi-transparent backgrounds for blur effect.
+        "bg-surface-darkest/50": hasBlur && sticky && (mode === "dark" || mode === "system"),
+        "bg-surface-light/50": hasBlur && sticky && (mode === "light" || mode === "alt-system"),
+        "dark:bg-surface-light/50": hasBlur && sticky && mode === "system",
+        "dark:bg-surface-darkest/50": hasBlur && sticky && mode === "alt-system",
+        // Solid backgrounds when no blur effect.
+        "bg-surface-darkest": !hasBlur && (mode === "dark" || mode === "system"),
+        "bg-surface-light": !hasBlur && (mode === "light" || mode === "alt-system"),
+        "dark:bg-surface-light": !hasBlur && mode === "system",
+        "dark:bg-surface-darkest": !hasBlur && mode === "alt-system"
+    });
+};
+const getHeaderFooterCopyClasses = ({ mode })=>{
+    return clsx({
+        "text-copy-light": mode === "dark",
+        "text-copy-dark": mode === "light",
+        "text-copy-light dark:text-copy-dark": mode === "system",
+        "text-copy-dark dark:text-copy-light": mode === "alt-system"
+    });
+};
+/**
+ * Common classes for sticky header/footer with optional blur effect.
+ */ const getStickyBlurClasses = ({ blurEffect })=>{
+    return clsx({
+        "backdrop-blur-sm": blurEffect === BlurEffects.SMALL,
+        "backdrop-blur-md": blurEffect === BlurEffects.MEDIUM,
+        "backdrop-blur-lg": blurEffect === BlurEffects.LARGE
+    });
+};
+
+export { getHeaderFooterBackgroundClasses, getHeaderFooterCopyClasses, getStickyBlurClasses };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@versini/ui-datagrid",
-	"version": "0.2.0",
+	"version": "0.2.2",
 	"license": "MIT",
 	"author": "Arno Versini",
 	"publishConfig": {
@@ -94,5 +94,5 @@
 	"sideEffects": [
 		"**/*.css"
 	],
-	"gitHead": "51fb2afed4cea9931d78243b1587e5699024d03e"
+	"gitHead": "f23e7cccc6798893b412edd01aec4d767ec94c9f"
 }