@versini/ui-datagrid 0.1.0

package/dist/DataGridSorting/sortingUtils.d.ts

@@ -0,0 +1,138 @@
+import { type SortDirection } from "../DataGridConstants/DataGridConstants";
+/**
+ * Gets the opposite sort direction.
+ */
+export declare function getOppositeSortDirection(direction: SortDirection): SortDirection;
+/**
+ * Toggles the sort direction or returns default if no current direction.
+ */
+export declare function toggleSortDirection(currentDirection?: SortDirection, defaultDirection?: SortDirection): SortDirection;
+/**
+ * Comparator function type for sorting.
+ */
+export type SortComparator<T> = (a: T, b: T) => number;
+/**
+ * Creates a sort comparator for dates. Handles Date objects, ISO strings, and
+ * timestamps.
+ *
+ * @param direction - Sort direction (asc or desc)
+ * @param nullPosition - Where to place null/undefined values ('start' or 'end')
+ *
+ * @example
+ * ```ts
+ * const items = [{ date: '2024-01-15' }, { date: '2024-01-10' }];
+ * const sorted = items.sort((a, b) =>
+ *   sortByDate('asc')(a.date, b.date)
+ * );
+ * ```
+ *
+ */
+export declare function sortByDate(direction: SortDirection, nullPosition?: "start" | "end"): SortComparator<Date | string | number | null | undefined>;
+/**
+ * Creates a sort comparator for numbers.
+ *
+ * @param direction - Sort direction (asc or desc)
+ * @param nullPosition - Where to place null/undefined values ('start' or 'end')
+ *
+ * @example
+ * ```ts
+ * const items = [{ count: 5 }, { count: 2 }, { count: 10 }];
+ * const sorted = items.sort((a, b) =>
+ *   sortByNumber('desc')(a.count, b.count)
+ * );
+ * ```
+ *
+ */
+export declare function sortByNumber(direction: SortDirection, nullPosition?: "start" | "end"): SortComparator<number | null | undefined>;
+/**
+ * Creates a sort comparator for strings. Uses localeCompare for proper Unicode
+ * sorting.
+ *
+ * @param direction - Sort direction (asc or desc)
+ * @param options - Options for string comparison
+ *
+ * @example
+ * ```ts
+ * const items = [{ name: 'Zebra' }, { name: 'apple' }];
+ * const sorted = items.sort((a, b) =>
+ *   sortByString('asc', { caseInsensitive: true })(a.name, b.name)
+ * );
+ * ```
+ *
+ */
+export declare function sortByString(direction: SortDirection, options?: {
+    nullPosition?: "start" | "end";
+    caseInsensitive?: boolean;
+    locale?: string;
+}): SortComparator<string | null | undefined>;
+/**
+ * Creates a sort comparator for booleans.
+ *
+ * @param direction - Sort direction (asc = false first, desc = true first)
+ *
+ * @example
+ * ```ts
+ * const items = [{ active: true }, { active: false }];
+ * const sorted = items.sort((a, b) =>
+ *   sortByBoolean('desc')(a.active, b.active)
+ * );
+ * // Result: [{ active: true }, { active: false }]
+ * ```
+ *
+ */
+export declare function sortByBoolean(direction: SortDirection): SortComparator<boolean | null | undefined>;
+/**
+ * Type for sort configuration.
+ */
+export type SortConfig<T extends string = string> = {
+    /**
+     * The column/field currently being sorted.
+     */
+    sortedCell: T;
+    /**
+     * Current sort direction.
+     */
+    sortDirection: SortDirection;
+};
+/**
+ * Helper to create a sort handler function. Returns the new sort config when a
+ * column header is clicked.
+ *
+ * @param currentConfig - Current sort configuration
+ * @param cellId - ID of the clicked cell
+ * @param defaultDirection - Default direction when clicking a new column
+ *
+ * @example
+ * ```tsx
+ * const [sortConfig, setSortConfig] = useState<SortConfig>({
+ *   sortedCell: 'date',
+ *   sortDirection: 'desc',
+ * });
+ *
+ * const handleSort = (cellId: string) => {
+ *   setSortConfig(getNextSortConfig(sortConfig, cellId));
+ * };
+ * ```
+ *
+ */
+export declare function getNextSortConfig<T extends string = string>(currentConfig: SortConfig<T>, cellId: T, defaultDirection?: SortDirection): SortConfig<T>;
+/**
+ * Generic sort function that sorts an array by a specified key.
+ *
+ * @param items - Array to sort
+ * @param key - Key to sort by
+ * @param direction - Sort direction
+ * @param sortType - Type of sorting ('date', 'number', 'string', 'boolean')
+ *
+ * @example
+ * ```ts
+ * const items = [
+ *   { id: 1, name: 'Alice', createdAt: '2024-01-01' },
+ *   { id: 2, name: 'Bob', createdAt: '2024-01-15' },
+ * ];
+ *
+ * const sorted = sortItems(items, 'createdAt', 'desc', 'date');
+ * ```
+ *
+ */
+export declare function sortItems<T extends Record<string, unknown>>(items: T[], key: keyof T, direction: SortDirection, sortType?: "date" | "number" | "string" | "boolean"): T[];

package/dist/DataGridSorting/sortingUtils.js

@@ -0,0 +1,234 @@
+/*!
+  @versini/ui-datagrid v0.1.0
+  © 2026 gizmette.com
+*/
+
+import { SortDirections } from "../DataGridConstants/DataGridConstants.js";
+
+;// CONCATENATED MODULE: external "../DataGridConstants/DataGridConstants.js"
+
+;// CONCATENATED MODULE: ./src/DataGridSorting/sortingUtils.ts
+
+/**
+ * Gets the opposite sort direction.
+ */ function getOppositeSortDirection(direction) {
+    return direction === SortDirections.ASC ? SortDirections.DESC : SortDirections.ASC;
+}
+/**
+ * Toggles the sort direction or returns default if no current direction.
+ */ function toggleSortDirection(currentDirection, defaultDirection = SortDirections.ASC) {
+    if (!currentDirection) {
+        return defaultDirection;
+    }
+    return getOppositeSortDirection(currentDirection);
+}
+/**
+ * Creates a sort comparator for dates. Handles Date objects, ISO strings, and
+ * timestamps.
+ *
+ * @param direction - Sort direction (asc or desc)
+ * @param nullPosition - Where to place null/undefined values ('start' or 'end')
+ *
+ * @example
+ * ```ts
+ * const items = [{ date: '2024-01-15' }, { date: '2024-01-10' }];
+ * const sorted = items.sort((a, b) =>
+ *   sortByDate('asc')(a.date, b.date)
+ * );
+ * ```
+ *
+ */ function sortByDate(direction, nullPosition = "end") {
+    return (a, b)=>{
+        const aIsNull = a === null || a === undefined;
+        const bIsNull = b === null || b === undefined;
+        // Handle null values.
+        if (aIsNull && bIsNull) {
+            return 0;
+        }
+        if (aIsNull) {
+            return nullPosition === "start" ? -1 : 1;
+        }
+        if (bIsNull) {
+            return nullPosition === "start" ? 1 : -1;
+        }
+        const aTime = a instanceof Date ? a.getTime() : new Date(a).getTime();
+        const bTime = b instanceof Date ? b.getTime() : new Date(b).getTime();
+        // Handle invalid dates.
+        if (Number.isNaN(aTime) && Number.isNaN(bTime)) {
+            return 0;
+        }
+        if (Number.isNaN(aTime)) {
+            return nullPosition === "start" ? -1 : 1;
+        }
+        if (Number.isNaN(bTime)) {
+            return nullPosition === "start" ? 1 : -1;
+        }
+        return direction === SortDirections.ASC ? aTime - bTime : bTime - aTime;
+    };
+}
+/**
+ * Creates a sort comparator for numbers.
+ *
+ * @param direction - Sort direction (asc or desc)
+ * @param nullPosition - Where to place null/undefined values ('start' or 'end')
+ *
+ * @example
+ * ```ts
+ * const items = [{ count: 5 }, { count: 2 }, { count: 10 }];
+ * const sorted = items.sort((a, b) =>
+ *   sortByNumber('desc')(a.count, b.count)
+ * );
+ * ```
+ *
+ */ function sortByNumber(direction, nullPosition = "end") {
+    return (a, b)=>{
+        const aIsNull = a === null || a === undefined;
+        const bIsNull = b === null || b === undefined;
+        // Handle null values.
+        if (aIsNull && bIsNull) {
+            return 0;
+        }
+        if (aIsNull) {
+            return nullPosition === "start" ? -1 : 1;
+        }
+        if (bIsNull) {
+            return nullPosition === "start" ? 1 : -1;
+        }
+        // Handle NaN.
+        const aIsNaN = Number.isNaN(a);
+        const bIsNaN = Number.isNaN(b);
+        if (aIsNaN && bIsNaN) {
+            return 0;
+        }
+        if (aIsNaN) {
+            return nullPosition === "start" ? -1 : 1;
+        }
+        if (bIsNaN) {
+            return nullPosition === "start" ? 1 : -1;
+        }
+        return direction === SortDirections.ASC ? a - b : b - a;
+    };
+}
+/**
+ * Creates a sort comparator for strings. Uses localeCompare for proper Unicode
+ * sorting.
+ *
+ * @param direction - Sort direction (asc or desc)
+ * @param options - Options for string comparison
+ *
+ * @example
+ * ```ts
+ * const items = [{ name: 'Zebra' }, { name: 'apple' }];
+ * const sorted = items.sort((a, b) =>
+ *   sortByString('asc', { caseInsensitive: true })(a.name, b.name)
+ * );
+ * ```
+ *
+ */ function sortByString(direction, options) {
+    const { nullPosition = "end", caseInsensitive = true, locale } = options ?? {};
+    return (a, b)=>{
+        const aIsNull = a === null || a === undefined || a === "";
+        const bIsNull = b === null || b === undefined || b === "";
+        // Handle null/empty values.
+        if (aIsNull && bIsNull) {
+            return 0;
+        }
+        if (aIsNull) {
+            return nullPosition === "start" ? -1 : 1;
+        }
+        if (bIsNull) {
+            return nullPosition === "start" ? 1 : -1;
+        }
+        const compareOptions = {
+            sensitivity: caseInsensitive ? "base" : "variant"
+        };
+        const comparison = locale ? a.localeCompare(b, locale, compareOptions) : a.localeCompare(b, undefined, compareOptions);
+        return direction === SortDirections.ASC ? comparison : -comparison;
+    };
+}
+/**
+ * Creates a sort comparator for booleans.
+ *
+ * @param direction - Sort direction (asc = false first, desc = true first)
+ *
+ * @example
+ * ```ts
+ * const items = [{ active: true }, { active: false }];
+ * const sorted = items.sort((a, b) =>
+ *   sortByBoolean('desc')(a.active, b.active)
+ * );
+ * // Result: [{ active: true }, { active: false }]
+ * ```
+ *
+ */ function sortByBoolean(direction) {
+    return (a, b)=>{
+        // Treat null/undefined as false for comparison.
+        const aVal = a === true ? 1 : 0;
+        const bVal = b === true ? 1 : 0;
+        return direction === SortDirections.ASC ? aVal - bVal : bVal - aVal;
+    };
+}
+/**
+ * Helper to create a sort handler function. Returns the new sort config when a
+ * column header is clicked.
+ *
+ * @param currentConfig - Current sort configuration
+ * @param cellId - ID of the clicked cell
+ * @param defaultDirection - Default direction when clicking a new column
+ *
+ * @example
+ * ```tsx
+ * const [sortConfig, setSortConfig] = useState<SortConfig>({
+ *   sortedCell: 'date',
+ *   sortDirection: 'desc',
+ * });
+ *
+ * const handleSort = (cellId: string) => {
+ *   setSortConfig(getNextSortConfig(sortConfig, cellId));
+ * };
+ * ```
+ *
+ */ function getNextSortConfig(currentConfig, cellId, defaultDirection = SortDirections.DESC) {
+    if (currentConfig.sortedCell === cellId) {
+        // Toggle direction on same column.
+        return {
+            sortedCell: cellId,
+            sortDirection: getOppositeSortDirection(currentConfig.sortDirection)
+        };
+    }
+    // New column, use default direction.
+    return {
+        sortedCell: cellId,
+        sortDirection: defaultDirection
+    };
+}
+/**
+ * Generic sort function that sorts an array by a specified key.
+ *
+ * @param items - Array to sort
+ * @param key - Key to sort by
+ * @param direction - Sort direction
+ * @param sortType - Type of sorting ('date', 'number', 'string', 'boolean')
+ *
+ * @example
+ * ```ts
+ * const items = [
+ *   { id: 1, name: 'Alice', createdAt: '2024-01-01' },
+ *   { id: 2, name: 'Bob', createdAt: '2024-01-15' },
+ * ];
+ *
+ * const sorted = sortItems(items, 'createdAt', 'desc', 'date');
+ * ```
+ *
+ */ function sortItems(items, key, direction, sortType = "string") {
+    const comparator = sortType === "date" ? sortByDate(direction) : sortType === "number" ? sortByNumber(direction) : sortType === "boolean" ? sortByBoolean(direction) : sortByString(direction);
+    return [
+        ...items
+    ].sort((a, b)=>{
+        const aVal = a[key];
+        const bVal = b[key];
+        return comparator(aVal, bVal);
+    });
+}
+
+export { getNextSortConfig, getOppositeSortDirection, sortByBoolean, sortByDate, sortByNumber, sortByString, sortItems, toggleSortDirection };

package/dist/DataGridVirtual/VirtualDataGrid.d.ts

@@ -0,0 +1,114 @@
+import { type BlurEffect, type ThemeMode } from "../DataGridConstants/DataGridConstants";
+export type VirtualDataGridColumn<T> = {
+    /**
+     * Unique identifier for the column.
+     */
+    id: string;
+    /**
+     * Header content.
+     */
+    header: React.ReactNode;
+    /**
+     * Cell renderer function.
+     */
+    cell: (item: T, index: number) => React.ReactNode;
+    /**
+     * Column width (CSS value).
+     */
+    width?: string | number;
+    /**
+     * Additional class name for cells in this column.
+     */
+    className?: string;
+};
+export type VirtualDataGridProps<T> = {
+    /**
+     * Array of data items.
+     */
+    data: T[];
+    /**
+     * Column definitions.
+     */
+    columns: VirtualDataGridColumn<T>[];
+    /**
+     * Height of the container (required for virtualization).
+     */
+    height: string | number;
+    /**
+     * Theme mode.
+     * @default "system"
+     */
+    mode?: ThemeMode;
+    /**
+     * Use compact row height.
+     * @default false
+     */
+    compact?: boolean;
+    /**
+     * Keep header fixed while scrolling.
+     * @default true
+     */
+    stickyHeader?: boolean;
+    /**
+     * Blur effect for sticky header.
+     * @default BlurEffects.NONE
+     */
+    blurEffect?: BlurEffect;
+    /**
+     * Caption text for accessibility.
+     */
+    caption?: string;
+    /**
+     * Additional class name for the wrapper.
+     */
+    wrapperClassName?: string;
+    /**
+     * Additional class name for the table.
+     */
+    className?: string;
+    /**
+     * Function to get a unique key for each row.
+     */
+    getRowKey?: (item: T, index: number) => string | number;
+    /**
+     * Callback when a row is clicked.
+     */
+    onRowClick?: (item: T, index: number) => void;
+    /**
+     * Index of the active row (for highlighting).
+     */
+    activeRowIndex?: number;
+    /**
+     * Estimated row height for virtualization.
+     * @default 40
+     */
+    estimateSize?: number | ((index: number) => number);
+    /**
+     * Number of rows to render above/below visible area.
+     * @default 5
+     */
+    overscan?: number;
+    /**
+     * Whether to use React's flushSync. Set to false for React 19.
+     * @default true
+     */
+    useFlushSync?: boolean;
+};
+/**
+ * A virtualized data grid component for rendering large datasets.
+ *
+ * @example
+ * ```tsx
+ * <VirtualDataGrid
+ *   data={items}
+ *   height="500px"
+ *   columns={[
+ *     { id: 'name', header: 'Name', cell: (item) => item.name },
+ *     { id: 'date', header: 'Date', cell: (item) => formatDate(item.date) },
+ *   ]}
+ *   getRowKey={(item) => item.id}
+ * />
+ * ```
+ *
+ */
+export declare function VirtualDataGrid<T>({ data, columns, height, mode, compact, stickyHeader, blurEffect, caption, wrapperClassName, className, getRowKey, onRowClick, activeRowIndex, estimateSize, overscan, useFlushSync, }: VirtualDataGridProps<T>): import("react/jsx-runtime").JSX.Element;

package/dist/DataGridVirtual/VirtualDataGrid.js

@@ -0,0 +1,181 @@
+/*!
+  @versini/ui-datagrid v0.1.0
+  © 2026 gizmette.com
+*/
+
+import { jsx, jsxs } from "react/jsx-runtime";
+import clsx from "clsx";
+import { useCallback, useMemo } from "react";
+import { DataGridContext } from "../DataGrid/DataGridContext.js";
+import { getDataGridClasses } from "../DataGrid/utilities.js";
+import { BlurEffects } from "../DataGridConstants/DataGridConstants.js";
+import { getHeaderClasses } from "../DataGridHeader/DataGridHeader.js";
+import { useVirtualDataGrid } from "./useVirtualDataGrid.js";
+
+;// CONCATENATED MODULE: external "react/jsx-runtime"
+
+;// CONCATENATED MODULE: external "clsx"
+
+;// CONCATENATED MODULE: external "react"
+
+;// CONCATENATED MODULE: external "../DataGrid/DataGridContext.js"
+
+;// CONCATENATED MODULE: external "../DataGrid/utilities.js"
+
+;// CONCATENATED MODULE: external "../DataGridConstants/DataGridConstants.js"
+
+;// CONCATENATED MODULE: external "../DataGridHeader/DataGridHeader.js"
+
+;// CONCATENATED MODULE: external "./useVirtualDataGrid.js"
+
+;// CONCATENATED MODULE: ./src/DataGridVirtual/VirtualDataGrid.tsx
+
+
+
+
+
+
+
+
+/**
+ * A virtualized data grid component for rendering large datasets.
+ *
+ * @example
+ * ```tsx
+ * <VirtualDataGrid
+ *   data={items}
+ *   height="500px"
+ *   columns={[
+ *     { id: 'name', header: 'Name', cell: (item) => item.name },
+ *     { id: 'date', header: 'Date', cell: (item) => formatDate(item.date) },
+ *   ]}
+ *   getRowKey={(item) => item.id}
+ * />
+ * ```
+ *
+ */ function VirtualDataGrid({ data, columns, height, mode = "system", compact = false, stickyHeader = true, blurEffect = BlurEffects.NONE, caption, wrapperClassName, className, getRowKey, onRowClick, activeRowIndex, estimateSize = 40, overscan = 5, useFlushSync = true }) {
+    // Memoize the getItemKey function to prevent infinite re-renders.
+    const getItemKey = useCallback((index)=>getRowKey ? getRowKey(data[index], index) : index, [
+        getRowKey,
+        data
+    ]);
+    const { scrollContainerRef, totalSize, virtualItems, measureElement } = useVirtualDataGrid({
+        data,
+        estimateSize,
+        overscan,
+        getItemKey,
+        useFlushSync
+    });
+    const classes = useMemo(()=>getDataGridClasses({
+            mode,
+            className,
+            wrapperClassName,
+            stickyHeader,
+            stickyFooter: false,
+            disabled: false
+        }), [
+        mode,
+        className,
+        wrapperClassName,
+        stickyHeader
+    ]);
+    const headerClasses = useMemo(()=>getHeaderClasses({
+            stickyHeader,
+            mode,
+            blurEffect
+        }), [
+        stickyHeader,
+        mode,
+        blurEffect
+    ]);
+    const contextValue = useMemo(()=>({
+            mode,
+            compact
+        }), [
+        mode,
+        compact
+    ]);
+    const containerStyle = useMemo(()=>({
+            height: typeof height === "number" ? `${height}px` : height,
+            overflow: "auto"
+        }), [
+        height
+    ]);
+    /**
+	 * The tbody needs relative positioning for absolute row children and a height
+	 * equal to the total virtualized size.
+	 */ const tbodyStyle = useMemo(()=>({
+            display: "block",
+            height: `${totalSize}px`,
+            position: "relative"
+        }), [
+        totalSize
+    ]);
+    // Header row needs to be display: table to maintain column widths.
+    const theadStyle = useMemo(()=>({
+            display: "table",
+            width: "100%",
+            tableLayout: "fixed"
+        }), []);
+    return /*#__PURE__*/ jsx(DataGridContext.Provider, {
+        value: contextValue,
+        children: /*#__PURE__*/ jsx("div", {
+            className: classes.wrapper,
+            children: /*#__PURE__*/ jsx("div", {
+                ref: scrollContainerRef,
+                style: containerStyle,
+                children: /*#__PURE__*/ jsxs("table", {
+                    className: classes.table,
+                    "aria-label": caption,
+                    children: [
+                        caption && /*#__PURE__*/ jsx("caption", {
+                            className: classes.caption,
+                            children: caption
+                        }),
+                        /*#__PURE__*/ jsx("thead", {
+                            className: headerClasses,
+                            style: theadStyle,
+                            children: /*#__PURE__*/ jsx("tr", {
+                                children: columns.map((column)=>/*#__PURE__*/ jsx("th", {
+                                        style: {
+                                            width: column.width
+                                        },
+                                        className: clsx("px-4 py-3 font-semibold", column.className),
+                                        children: column.header
+                                    }, column.id))
+                            })
+                        }),
+                        /*#__PURE__*/ jsx("tbody", {
+                            style: tbodyStyle,
+                            children: virtualItems.map((virtualRow)=>{
+                                const isActive = activeRowIndex === virtualRow.index;
+                                return /*#__PURE__*/ jsx("tr", {
+                                    ref: measureElement,
+                                    "data-index": virtualRow.index,
+                                    onClick: onRowClick ? ()=>onRowClick(virtualRow.data, virtualRow.index) : undefined,
+                                    className: clsx("absolute flex w-full", {
+                                        "cursor-pointer": !!onRowClick,
+                                        "bg-action-dark/10 dark:bg-action-light/10": isActive
+                                    }),
+                                    style: {
+                                        height: `${virtualRow.size}px`,
+                                        transform: `translateY(${virtualRow.start}px)`
+                                    },
+                                    children: columns.map((column)=>/*#__PURE__*/ jsx("td", {
+                                            className: clsx(compact ? "px-2 py-1" : "px-4 py-3", column.className),
+                                            style: {
+                                                width: column.width
+                                            },
+                                            children: column.cell(virtualRow.data, virtualRow.index)
+                                        }, column.id))
+                                }, virtualRow.key);
+                            })
+                        })
+                    ]
+                })
+            })
+        })
+    });
+}
+
+export { VirtualDataGrid };

package/dist/DataGridVirtual/index.d.ts

@@ -0,0 +1,6 @@
+export type { VirtualItem, Virtualizer } from "@tanstack/react-virtual";
+export { useVirtualizer, useWindowVirtualizer } from "@tanstack/react-virtual";
+export type { UseVirtualDataGridOptions, UseVirtualDataGridReturn, } from "./useVirtualDataGrid";
+export { useVirtualDataGrid } from "./useVirtualDataGrid";
+export type { VirtualDataGridColumn, VirtualDataGridProps, } from "./VirtualDataGrid";
+export { VirtualDataGrid } from "./VirtualDataGrid";

package/dist/DataGridVirtual/index.js

@@ -0,0 +1,22 @@
+/*!
+  @versini/ui-datagrid v0.1.0
+  © 2026 gizmette.com
+*/
+
+import { useVirtualizer, useWindowVirtualizer } from "@tanstack/react-virtual";
+import { useVirtualDataGrid } from "./useVirtualDataGrid.js";
+import { VirtualDataGrid } from "./VirtualDataGrid.js";
+
+;// CONCATENATED MODULE: external "@tanstack/react-virtual"
+
+;// CONCATENATED MODULE: external "./useVirtualDataGrid.js"
+
+;// CONCATENATED MODULE: external "./VirtualDataGrid.js"
+
+;// CONCATENATED MODULE: ./src/DataGridVirtual/index.ts
+// Re-export from @tanstack/react-virtual for convenience.
+
+
+
+
+export { VirtualDataGrid, useVirtualDataGrid, useVirtualizer, useWindowVirtualizer };