react-kd-grid 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,421 @@
+import { CSSProperties, MouseEvent, ReactNode } from "react";
+export type FilterType = "text" | "multiselect" | "number" | "date" | "boolean";
+export type Density = "sm" | "md" | "lg";
+export interface FilterOption {
+    label: string;
+    value: any;
+}
+export interface ColumnFilter {
+    type: FilterType;
+    options?: FilterOption[];
+    placeholder?: string;
+    min?: number;
+    max?: number;
+}
+export interface GridColumn {
+    key: string;
+    header: string;
+    width?: number;
+    /**
+     * Flexible sizing. When true or a positive number, the column can expand to fill
+     * available horizontal space. If a number is provided, it represents the flex grow weight.
+     * Note: runtime support may require renderer updates; currently a type hint.
+     */
+    flex?: boolean | number;
+    /** Minimum width in pixels for this column */
+    minWidth?: number;
+    /** Maximum width in pixels for this column */
+    maxWidth?: number;
+    /** Allows column to be resizable via UI (if the header implements it) */
+    resizable?: boolean;
+    /**
+     * Whether the column is sortable. Defaults to true; set explicitly to false to disable.
+     */
+    sortable?: boolean;
+    filterable?: boolean | ColumnFilter;
+    formatter?: (value: any) => string;
+    cellRenderer?: (value: any, row: GridRow) => ReactNode;
+    visible?: boolean;
+    /**
+     * Group aggregate to compute for this column when grouping is enabled.
+     * If a function is provided, it will receive the array of raw cell values and should return the aggregate value.
+     */
+    aggregate?: "sum" | "avg" | "min" | "max" | ((values: any[]) => any);
+    /**
+     * Optional formatter for the aggregate value displayed in group footers.
+     * Falls back to the column's formatter if not provided.
+     */
+    aggregateFormatter?: (value: any) => string;
+    /**
+     * Footer aggregate to compute for this column and display at the bottom of all rows.
+     * If a function is provided, it will receive the array of raw cell values and should return the aggregate value.
+     */
+    footer_aggregate?: "count" | "sum" | "avg" | "min" | "max" | ((values: any[]) => any);
+    /**
+     * Optional formatter for the footer aggregate value.
+     * Falls back to the column's formatter if not provided.
+     */
+    footerAggregateFormatter?: (value: any) => string;
+    /**
+     * Horizontal alignment for cell content: left | center | right
+     */
+    align?: "left" | "center" | "right";
+    /**
+     * Horizontal alignment for header content: left | center | right
+     */
+    headerAlign?: "left" | "center" | "right";
+    /** Optional CSS class for body cells of this column */
+    className?: string | ((value: any, row: GridRow) => string);
+    /** Optional inline style for body cells of this column */
+    cellStyle?: CSSProperties | ((value: any, row: GridRow) => CSSProperties);
+    /** Optional CSS class for the header cell of this column */
+    headerClassName?: string;
+    /** If true, removes default padding from the cell container for this column */
+    noPadding?: boolean;
+    /** If false, do not wrap renderer output with the default truncation div */
+    wrapCellContent?: boolean;
+}
+export interface GridRow {
+    id?: string | number;
+    [key: string]: any;
+}
+export interface GroupConfig {
+    /** Ordered list of column keys to group by (multi-level). */
+    columnKeys: string[];
+    /**
+     * Expanded group paths. Each path is a stable string key built from the sequence of
+     * grouping values, e.g. "City=SF|Status=Open". Root groups are single segment.
+     */
+    expanded: Set<string>;
+}
+export interface GroupedData {
+    [groupValue: string]: {
+        rows: GridRow[];
+        count: number;
+    };
+}
+export type SearchMode = "contains" | "exact" | "startsWith" | "endsWith" | "regex";
+export type BulkAction = "delete" | "archive" | "copy" | "edit" | "export";
+export interface SavedFilter {
+    id: string;
+    name: string;
+    globalFilter: string;
+    columnFilters: Record<string, any>;
+    searchMode: SearchMode;
+}
+export interface BulkActionOption {
+    id: BulkAction;
+    label: string;
+    icon: ReactNode;
+    onClick: (selectedRows: Set<string | number>) => void;
+    disabled?: boolean;
+    destructive?: boolean;
+}
+export interface CustomDataGridProps {
+    data: GridRow[];
+    columns: GridColumn[];
+    /**
+     * Optional function to derive unique row identifier from a row object.
+     * Priority order:
+     *   1. If getRowId is provided, use it to extract the ID from the row
+     *   2. Else if row.id exists, use it
+     *   3. Else use the row's index as fallback (may cause issues with pagination/filtering)
+     *
+     * Examples:
+     *   - (row) => row.employeeId
+     *   - (row) => `${row.dept}_${row.name}` (composite key)
+     *   - (row) => row.uuid
+     *
+     * Recommendation: Always provide either row.id or getRowId prop for best results.
+     */
+    getRowId?: (row: GridRow) => string | number;
+    height?: number;
+    density?: Density;
+    onDensityChange?: (density: Density) => void;
+    /**
+     * Optional header size controls (independent of row density).
+     * - If headerHeight is provided, it takes precedence (fixed pixel height).
+     * - Else if headerDensity is provided, it maps to the density sizing (sm|md|lg).
+     * - Else defaults to medium (md).
+     */
+    headerDensity?: Density;
+    headerHeight?: number;
+    showDensityControl?: boolean;
+    onRowSelect?: (row: GridRow) => void;
+    onSelectedRowsChange?: (selectedRows: Set<string | number>) => void;
+    selectable?: boolean;
+    isRowSelectable?: (row: GridRow) => boolean;
+    showToolbar?: boolean;
+    showExport?: boolean;
+    /**
+     * Optional export options to control which formats are allowed and default filename.
+     * If not provided, only Excel ("xlsx") will be allowed by default.
+     */
+    exportOptions?: {
+        /** Allowed export formats (defaults to ["xlsx"]) */
+        formats?: Array<"csv" | "json" | "xlsx">;
+        /** Default exported filename without extension (defaults to "grid-data") */
+        filename?: string;
+        /** Enable/disable export action (defaults to true; combined with showExport) */
+        enabled?: boolean;
+        /** Export execution mode. Default: 'client'. */
+        exportMode?: "client" | "server";
+        /**
+         * Optional handler to perform server-side export when exportMode === 'server'.
+         * If exportSelected is true, selectedRowIds will contain the ids that are currently selected in the grid.
+         */
+        onServerExport?: (format: "csv" | "json" | "xlsx", exportSelected: boolean, selectedRowIds?: Array<string | number>) => void;
+    };
+    sortable?: boolean;
+    filterable?: boolean;
+    groupable?: boolean;
+    virtualized?: boolean;
+    rowHeight?: number;
+    overscan?: number;
+    rowStyle?: (row: GridRow) => CSSProperties | undefined;
+    onContextMenu?: (row: GridRow, event: MouseEvent) => void;
+    onRowDoubleClick?: (row: GridRow, event: MouseEvent) => void;
+    onRowClick?: (row: GridRow, event: MouseEvent) => void;
+    onCellClick?: (args: {
+        row: GridRow;
+        column: GridColumn;
+        value: any;
+        event: MouseEvent;
+    }) => void;
+    onCellContextMenu?: (args: {
+        row: GridRow;
+        column: GridColumn;
+        value: any;
+        displayValue: string;
+        event: MouseEvent;
+    }) => void;
+    cellFocusEnabled?: boolean;
+    onCellFocusChange?: (args: {
+        row: GridRow;
+        column: GridColumn;
+        value: any;
+        rowIndex: number;
+        colIndex: number;
+    }) => void;
+    cellSelectionEnabled?: boolean;
+    canSelectCell?: (row: GridRow, column: GridColumn) => boolean;
+    onCellSelectionChange?: (payload: {
+        bounds: {
+            rowStart: number;
+            rowEnd: number;
+            colStart: number;
+            colEnd: number;
+        } | null;
+        cells: Array<{
+            row: GridRow;
+            column: GridColumn;
+            value: any;
+            rowIndex: number;
+            colIndex: number;
+        }>;
+    }) => void;
+    onAutosizeColumn?: (columnKey: string) => void;
+    onAutosizeAllColumns?: () => void;
+    onResetColumns?: () => void;
+    pagination?: {
+        enabled?: boolean;
+        mode?: PaginationMode;
+        pageSize?: number;
+        showPageSizeSelector?: boolean;
+        pageSizeOptions?: number[];
+        serverConfig?: ServerPaginationConfig;
+    };
+    /** If provided, when total (post-filter) rows <= threshold virtualization is auto-disabled for simpler DOM (default: 300). */
+    virtualizationThreshold?: number;
+    onRefresh?: () => void;
+    isLoading?: boolean;
+    bulkActions?: BulkActionOption[];
+    savedFilters?: SavedFilter[];
+    onSaveFilter?: (filter: Omit<SavedFilter, "id">) => void;
+    onLoadFilter?: (filter: SavedFilter) => void;
+    onDeleteFilter?: (filterId: string) => void;
+    onFilterChange?: (payload: ServerFilterChangePayload) => void;
+    onSort?: (columnKey: string, direction: "asc" | "desc") => void;
+    onColumnConfigChange?: (config: ColumnConfig) => void;
+    initialColumnConfig?: Partial<ColumnConfig>;
+    toolbarLeft?: ReactNode;
+    toolbarRight?: ReactNode;
+    /**
+     * Controls the visibility of the Group Bar (the area where you can drop headers to group).
+     * - 'hidden': never show the bar
+     * - 'auto': show only when there are active grouped columns
+     * - 'visible': always show when groupable is true
+     */
+    groupBarVisibility?: "hidden" | "auto" | "visible";
+    /**
+     * How to render group aggregation footer rows when grouping is enabled.
+     * - 'chips': render a colored summary bar with chips (default)
+     * - 'columns': render a full-width colored row placing aggregate values under their respective columns
+     */
+    groupFooterVariant?: "chips" | "columns";
+    /**
+     * Optional custom renderer for actions on grouped rows.
+     * Receives information about the group and its rows.
+     */
+    renderGroupActions?: (groupInfo: {
+        groupKey: string;
+        columnKey: string;
+        groupValue: any;
+        rows: GridRow[];
+        count: number;
+        level: number;
+    }) => ReactNode;
+    /**
+     * Show expand/collapse all group buttons in the toolbar when grouping is enabled.
+     * Defaults to true.
+     */
+    showGroupExpandControls?: boolean;
+    /**
+     * Callback invoked when user copies cells (Ctrl/Cmd + C) while cell focus or rectangular selection is active.
+     * Provides the plain text that was written to the clipboard (tab/newline delimited) and metadata.
+     */
+    onCopyCells?: (payload: {
+        text: string;
+        /** Present only for rectangular selections */
+        bounds?: {
+            rowStart: number;
+            rowEnd: number;
+            colStart: number;
+            colEnd: number;
+        } | null;
+        cells: Array<{
+            row: GridRow;
+            column: GridColumn;
+            value: any;
+            rowIndex: number;
+            colIndex: number;
+        }>;
+        isRectangular: boolean;
+        isFocusedCell: boolean;
+    }) => void;
+    /** Optional controlled selection ids */
+    selectedRowIds?: Iterable<string | number> | null;
+    /** Performance optimization settings for large datasets */
+    performanceConfig?: {
+        /** Enable horizontal virtualization for large column sets (default: true) */
+        enableHorizontalVirtualization?: boolean;
+        /** Column count threshold to enable horizontal virtualization (default: 50) */
+        horizontalVirtualizationThreshold?: number;
+        /** Row count threshold to offload sorting to a Web Worker (default: 5000). Set to 0 to always sort inline. */
+        sortWorkerThreshold?: number;
+        /** Maximum cache size for filtering operations (default: 5000) */
+        maxFilterCacheSize?: number;
+        /** Enable aggressive memoization for large datasets (default: true) */
+        enableAggressiveMemoization?: boolean;
+    };
+}
+export interface ContextMenuItem {
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    onClick: (row: GridRow) => void;
+    disabled?: boolean;
+    separator?: boolean;
+}
+export type SortDirection = "asc" | "desc" | null;
+export interface SortConfig {
+    key: string | null;
+    direction: SortDirection;
+}
+export interface VirtualizedRange {
+    startIndex: number;
+    endIndex: number;
+    offsetY: number;
+}
+export interface ColumnFilterValue {
+    type: FilterType;
+    value: any;
+    operator?: "equals" | "contains" | "startsWith" | "endsWith" | "gt" | "lt" | "gte" | "lte" | "between";
+    secondValue?: any;
+}
+export interface ActiveFilters {
+    [columnKey: string]: ColumnFilterValue;
+}
+export interface ColumnConfig {
+    columnWidths: Record<string, number>;
+    columnVisibility: Record<string, boolean>;
+    pinnedColumns: string[];
+    sortConfig: SortConfig;
+    /**
+     * Persisted grouping configuration. New multi-level shape uses columnKeys.
+     * The legacy single-key field (columnKey) is retained for backward compatibility.
+     */
+    groupConfig?: {
+        columnKeys?: string[];
+        columnKey?: string | null;
+    };
+    filters: {
+        globalFilter: string;
+        columnFilters: ActiveFilters;
+    };
+    columnOrder?: string[];
+    density?: Density;
+}
+export interface PaginationConfig {
+    enabled: boolean;
+    pageSize: number;
+    currentPage: number;
+    totalPages: number;
+    totalRows: number;
+    showPageSizeSelector?: boolean;
+    pageSizeOptions?: number[];
+}
+export interface ServerPaginationConfig {
+    enabled: boolean;
+    onPageChange: (page: number, pageSize: number) => Promise<void> | void;
+    onPageSizeChange?: (pageSize: number) => Promise<void> | void;
+    loading?: boolean;
+    totalRows: number;
+}
+export type PaginationMode = "client" | "server";
+export interface FilterPopupProps {
+    column: GridColumn;
+    data: GridRow[];
+    currentFilter?: ColumnFilterValue;
+    onApplyFilter: (filter: ColumnFilterValue | null) => void;
+    onClose: () => void;
+    position: {
+        top: number;
+        left: number;
+    };
+    autoApply?: boolean;
+}
+export interface ServerFilterChangePayload {
+    globalFilter: string;
+    columnFilters: ActiveFilters;
+    filterableKeys: string[];
+    searchMode?: SearchMode;
+}
+/**
+ * Imperative handle for CustomDataGrid to allow external control of grouping.
+ * Use with React.forwardRef and useImperativeHandle in the grid component.
+ */
+export interface CustomDataGridRef {
+    /** Replace the entire ordered grouping keys */
+    setGroupKeys: (keys: string[]) => void;
+    /** Add a grouping key at the end if not already present */
+    addGroupKey: (key: string) => void;
+    /** Remove a specific grouping key */
+    removeGroupKey: (key: string) => void;
+    /** Expand all group paths for the current grouping keys */
+    expandAllGroups: () => void;
+    /** Collapse all group paths */
+    collapseAllGroups: () => void;
+    /** Toggle a specific group path, e.g. "City=SF|Status=Open" */
+    toggleGroupExpansion: (groupPath: string) => void;
+    /** Read the current in-grid grouping configuration */
+    getGroupConfig: () => GroupConfig;
+    /** Set a column filter programmatically */
+    setColumnFilter: (columnKey: string, filter: any) => void;
+    /** Clear a specific column filter */
+    clearColumnFilter: (columnKey: string) => void;
+    /** Clear all column filters */
+    clearAllFilters: () => void;
+    /** Set global filter */
+    setGlobalFilter: (value: string) => void;
+}

package/dist/utils/highlightText.d.ts

@@ -0,0 +1,15 @@
+import React from "react";
+/**
+ * Highlights matching text within a string based on a search query
+ * @param text - The text to highlight
+ * @param searchQuery - The search query to match against
+ * @returns JSX element with highlighted matches
+ */
+export declare const highlightText: (text: string, searchQuery: string) => React.ReactNode;
+/**
+ * Checks if a value contains the search query (case-insensitive)
+ * @param value - The value to check
+ * @param searchQuery - The search query
+ * @returns true if the value contains the search query
+ */
+export declare const containsSearchQuery: (value: any, searchQuery: string) => boolean;

package/dist/workers/dataWorker.d.ts

@@ -0,0 +1,16 @@
+export interface WorkerProcessMessage {
+    type: "process";
+    payload: {
+        rows: any[];
+        sort?: {
+            key: string;
+            direction: "asc" | "desc";
+        } | null;
+    };
+}
+export interface WorkerResultMessage {
+    type: "result";
+    payload: {
+        rows: any[];
+    };
+}

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "react-kd-grid",
+  "version": "1.0.0",
+  "description": "A feature-rich, performant React data grid component with virtualization, grouping, filtering, and export capabilities",
+  "main": "dist/index.js",
+  "module": "dist/index.esm.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.esm.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc && rollup -c",
+    "dev": "tsc --watch",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts,.tsx",
+    "format": "prettier --write src",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "react",
+    "grid",
+    "data-grid",
+    "table",
+    "virtualization",
+    "grouping",
+    "filtering",
+    "sorting",
+    "pagination",
+    "export",
+    "typescript"
+  ],
+  "author": "Your Name <your.email@example.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourusername/react-kd-grid.git"
+  },
+  "bugs": {
+    "url": "https://github.com/yourusername/react-kd-grid/issues"
+  },
+  "homepage": "https://github.com/yourusername/react-kd-grid#readme",
+  "peerDependencies": {
+    "react": ">=16.8.0",
+    "react-dom": ">=16.8.0"
+  },
+  "devDependencies": {
+    "@floating-ui/react": "^0.27.18",
+    "@rollup/plugin-commonjs": "^28.0.0",
+    "@rollup/plugin-node-resolve": "^15.2.0",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^9.0.0",
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "@types/file-saver": "^2.0.7",
+    "@typescript-eslint/eslint-plugin": "^6.0.0",
+    "@typescript-eslint/parser": "^6.0.0",
+    "date-fns": "^3.6.0",
+    "eslint": "^8.0.0",
+    "eslint-plugin-react": "^7.32.0",
+    "eslint-plugin-react-hooks": "^4.6.0",
+    "lucide-react": "^0.454.0",
+    "prettier": "^3.0.0",
+    "rollup": "^3.0.0",
+    "tslib": "^2.6.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  },
+  "dependencies": {
+    "exceljs": "^4.3.0",
+    "file-saver": "^2.0.5",
+    "lucide-react": "^0.454.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}