gridular 2.2.0 → 3.0.0

package/README.md

@@ -1,131 +1,112 @@
-# Gridular Data Grid
-
-Gridular is a flexible and customizable data grid component for React applications. It provides features such as sorting, filtering, pagination, and row selection, making it easy to display and manage tabular data.
-
-## Features
-
-- **Sorting**: Easily sort data by clicking on column headers.
-- **Filtering**: Filter data using a user-friendly filter menu for each column.
-- **Pagination**: Navigate through large datasets with pagination controls.
-- **Row Selection**: Select rows for actions or data manipulation.
-- **Column Resizing**: Adjust column widths to fit your data needs.
-- **Column Management**: Show/hide and reorder columns as needed.
-- **Grid State Persistence**: Maintain column widths and ordering between sessions.
-
-## Installation
-
-To install Gridular, use npm or yarn:
-
-```bash
+# Gridular v3
+
+<div align="center">
+  <img src="./public/logo.svg" alt="Gridular Logo" width="200" height="200" />
+
+  <p><strong>A high-performance virtualized React data grid with comprehensive features</strong></p>
+
+  [![npm version](https://img.shields.io/npm/v/gridular.svg)](https://www.npmjs.com/package/gridular)
+  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+  [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)
+</div>
+
+## ✨ Features
+
+- ⚡ **True Virtualization** - Handles 100,000+ rows smoothly using `@tanstack/react-virtual`
+- 📊 **Data Grouping** - Multi-level hierarchical grouping with expand/collapse
+- 🔍 **Sorting & Filtering** - Column-level sorting and filtering with custom functions
+- 📄 **Pagination** - Client-side and server-side pagination support
+- ✏️ **Column Resizing** - Drag to resize columns with persistence
+- 🔄 **Column Reordering** - Drag-and-drop column reordering
+- 👁️ **Column Management** - Show/hide columns with reset to defaults
+- 📱 **Expandable Rows** - Custom expandable row content
+- 🎯 **Cell Selection** - Individual cell selection with visual indicators
+- 💾 **State Persistence** - localStorage persistence for grid preferences
+- 🎨 **Dual Styling** - Support for both Tailwind CSS and TSS-React (CSS-in-JS)
+- 🧪 **Fully Tested** - 43 comprehensive test cases
+- 📘 **TypeScript First** - Complete type safety and IntelliSense support
+
+## 📦 Installation
+
+\`\`\`bash
+# npm
 npm install gridular
-```
-
-```bash
-yarn add gridular
-```
-
-## Usage
 
-To use the DataGrid component, import it into your React component:
+# pnpm
+pnpm add gridular
 
-```typescript
-import { DataGrid } from "gridular/components/data-grid";
-
-const MyComponent = () => {
-  const columns = [
-    { id: "name", header: "Name" },
-    { id: "age", header: "Age" },
-    // Add more columns as needed
-  ];
-
-  const data = [
-    { id: 1, name: "John Doe", age: 28 },
-    { id: 2, name: "Jane Smith", age: 34 },
-    // Add more data as needed
-  ];
-
-  return <DataGrid columns={columns} data={data} />;
-};
-```
-
-## Components
-
-- **DataGrid**: The main component that renders the grid.
-- **FilterMenu**: A component for filtering data in the grid.
-- **Pagination**: A component for managing pagination controls.
-- **TableBody**: Renders the rows of the data grid.
-- **TableCell**: Represents individual cells in the data grid.
-- **TableHeader**: Renders the header of the data grid.
-- **TableRow**: Represents individual rows in the data grid.
-- **ColumnManager**: Manages column visibility and order.
-
-## Custom Hooks
-
-Gridular provides custom hooks for managing various functionalities:
+# yarn
+yarn add gridular
+\`\`\`
 
-- **useColumnResize**: For managing column resizing.
-- **useGridPersistence**: For persisting grid preferences like - \*\*column widths and order.
+## 🚀 Quick Start
 
-## Utility Functions
+\`\`\`tsx
+import { DataGrid } from 'gridular';
+import type { ColumnDef } from 'gridular';
 
-Gridular provides several utility functions to help with styling and component customization:
+const columns: ColumnDef[] = [
+  { id: 'name', key: 'name', header: 'Name', enableSorting: true },
+  { id: 'email', key: 'email', header: 'Email', enableSorting: true },
+  { id: 'age', key: 'age', header: 'Age', enableSorting: true },
+];
 
-```typescript
-cn(...inputs: ClassValue[])
-```
+const data = [
+  { id: '1', name: 'John Doe', email: 'john@example.com', age: 28 },
+  { id: '2', name: 'Jane Smith', email: 'jane@example.com', age: 34 },
+];
 
-A utility function that combines multiple class names or conditional class expressions using clsx and tailwind-merge. This helps avoid className conflicts when using Tailwind CSS.
+function App() {
+  return <DataGrid columns={columns} data={data} enableSorting enableColumnResize />;
+}
+\`\`\`
 
-```typescript
-import { cn } from "gridular";
+## 📖 Documentation
 
-// Usage
-<div
-  className={cn(
-    "base-class",
-    isActive && "active-class",
-    isFocused ? "focused-class" : "unfocused-class"
-  )}
->
-  Content
-</div>;
-```
+See [MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md) for upgrading from v2.
 
-```typescript
-mergeStyles(tssStyles, tailwindClasses);
-```
+For complete examples, run Storybook:
+\`\`\`bash
+npm run storybook
+\`\`\`
 
-Combines TSS-React style objects with Tailwind CSS classes, making it easier to integrate both styling approaches.
+## 🔄 Migration from v2
 
-```typescript
-import { mergeStyles } from "gridular";
+**Quick changes:**
+- ✅ Add \`key\` property to all columns
+- ✅ Rename \`cell\` to \`renderCell\`
+- ✅ Remove \`ThemeProvider\` wrapper
+- ✅ Consolidate pagination props
+- ✅ Remove group icon props
 
-// Usage
-const styles = mergeStyles(
-  { color: "#000", backgroundColor: "#fff" },
-  "p-4 rounded-md hover:bg-gray-100"
-);
+See [PRODUCT_STATUS_GRID_MIGRATION.md](./PRODUCT_STATUS_GRID_MIGRATION.md) for specific ProductStatusGrid migration example.
 
-<div {...styles}>Content</div>;
-```
+## 📚 More Examples
 
-## Parameters:
+- [Storybook](https://gridular.vercel.app)
+- Run locally: \`npm run storybook\`
 
--- tssStyles: A TSS-React style object (CSSObject)
--- tailwindClasses: A string or array of strings containing -- Tailwind class names Returns an object with merged styles that can be spread into React components.
+## 🧪 Testing
 
-## Theming
+\`\`\`bash
+npm test              # Run tests
+npm run test:ui       # Tests with UI
+npm run test:coverage # With coverage
+\`\`\`
 
-Gridular includes a built-in theme provider that allows you to customize the appearance of your data grids:
+## 📝 License
 
--- ThemeProvider: Context provider for styling your data grids.
--- ThemeSwitcher: Component for toggling between light and dark themes.
--- ThemeWrapper: Utility component for wrapping your components with theme context.
+MIT © [Michael Teagle](https://github.com/mkteagle)
 
-## Contributing
+## 🌟 Built With
 
-Contributions are welcome! Please open an issue or submit a pull request for any enhancements or bug fixes.
+- [@tanstack/react-virtual](https://tanstack.com/virtual) - Virtualization
+- [Radix UI](https://www.radix-ui.com/) - Accessible components
+- [Tailwind CSS](https://tailwindcss.com/) - Styling
+- [TSS-React](https://www.tss-react.dev/) - CSS-in-JS
 
-## License
+---
 
-This project is licensed under the MIT License. See the LICENSE file for details.
+<div align="center">
+  Made with ❤️ by <a href="https://github.com/mkteagle">Michael Teagle</a>
+</div>

package/dist/DataGrid.d.ts

@@ -0,0 +1,3 @@
+import { VirtualizedGridProps } from './types';
+export declare function DataGrid<T extends Record<string, any> = Record<string, any>>({ columns: propColumns, data, pagination, virtualizationThreshold, rowHeight, overscan, sortState: controlledSortState, onSortChange, enableSorting, sortIconVariant, filterState: controlledFilterState, onFilterChange: _onFilterChange, enableFiltering, selectedRows: controlledSelectedRows, onRowSelectionChange: _onRowSelectionChange, enableRowSelection: _enableRowSelection, enableCellSelection, selectedCell: controlledSelectedCell, onCellSelect, enableColumnResize, columnWidths: controlledColumnWidths, onColumnWidthsChange, enableColumnReorder, columnOrder: controlledColumnOrder, onColumnOrderChange, enableColumnMenu, defaultColumnMenuItems, onColumnAction, renderFilterMenu, renderColumnMenu, renderColumnMenuTrigger, enableGrouping, groupingState: controlledGroupingState, onGroupingChange, renderGroupRow, enableExpandableRows, expandedRows: controlledExpandedRows, onExpandedRowsChange, renderExpandedRow, isLoading: _isLoading, emptyMessage: _emptyMessage, loadingMessage: _loadingMessage, className, classes, renderCell, renderHeader: _renderHeader, renderSortIcon: _renderSortIcon, renderFilterIcon: _renderFilterIcon, onRowClick, onRowMouseDown, onRowMouseEnter, getRowId, onScroll, gridId, hideColumnManager, hideGroupControls, }: VirtualizedGridProps<T>): import("react/jsx-runtime").JSX.Element;
+export default DataGrid;

package/dist/Pagination.d.ts

@@ -0,0 +1,12 @@
+import { GridClasses } from './types';
+export interface PaginationProps {
+    pageIndex: number;
+    pageSize: number;
+    totalRows: number;
+    onPageChange: (page: number) => void;
+    onPageSizeChange?: (size: number) => void;
+    pageSizeOptions?: number[];
+    classes?: GridClasses;
+    className?: string;
+}
+export declare function Pagination({ pageIndex, pageSize, totalRows, onPageChange, onPageSizeChange, pageSizeOptions, classes, className, }: PaginationProps): import("react/jsx-runtime").JSX.Element;

package/dist/__tests__/DataGrid.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/utils.d.ts

@@ -0,0 +1,17 @@
+import { ReactElement } from 'react';
+import { RenderOptions, RenderResult } from '@testing-library/react';
+import { default as userEvent } from '@testing-library/user-event';
+export * from '@testing-library/react';
+interface CustomRenderResult extends RenderResult {
+    user: ReturnType<typeof userEvent.setup>;
+}
+/**
+ * Custom render function that wraps the component
+ * and sets up userEvent.
+ *
+ * @param ui - The React component to render
+ * @param options - Additional render options
+ * @returns The render result with added user property for userEvent
+ */
+declare function render(ui: ReactElement, options?: Omit<RenderOptions, 'wrapper'>): CustomRenderResult;
+export { render };

package/dist/components/ColumnManager.d.ts

@@ -0,0 +1,13 @@
+import { ColumnDef, GridClasses } from '../types';
+interface ColumnManagerProps<T> {
+    columns: ColumnDef<T>[];
+    visibleColumns: string[];
+    toggleColumnVisibility: (columnId: string, visible: boolean) => void;
+    resetGridPreferences: () => void;
+    align?: 'start' | 'center' | 'end';
+    showResetButton?: boolean;
+    className?: string;
+    classes?: GridClasses;
+}
+export declare function ColumnManager<T>({ columns, visibleColumns, toggleColumnVisibility, resetGridPreferences, align, showResetButton, className, classes, }: ColumnManagerProps<T>): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/GroupManager.d.ts

@@ -0,0 +1,11 @@
+import { ColumnDef, GridClasses } from '../types';
+interface GroupManagerProps<T> {
+    columns: ColumnDef<T>[];
+    groupByColumns: string[];
+    updateGroupByColumns: (groupByColumns: string[]) => void;
+    align?: 'start' | 'center' | 'end';
+    className?: string;
+    classes?: GridClasses;
+}
+export declare function GroupManager<T>({ columns, groupByColumns, updateGroupByColumns, align, className, classes, }: GroupManagerProps<T>): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/Skeleton.d.ts

@@ -0,0 +1,7 @@
+interface SkeletonProps {
+    className?: string;
+    width?: string | number;
+    height?: string | number;
+}
+export declare function Skeleton({ className, width, height }: SkeletonProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/gridular.css

@@ -0,0 +1 @@
+@import"https://fonts.googleapis.com/css2?family=Syne:wght@400;500;600;700;800&family=Manrope:wght@300;400;500;600;700&display=swap";:root{--vg-charcoal: #1a1a1a;--vg-charcoal-light: #2a2a2a;--vg-ivory: #faf8f6;--vg-ivory-dark: #f0ede9;--vg-copper: #b87333;--vg-copper-light: #d4935a;--vg-copper-dark: #9a5e28;--vg-border: rgba(184, 115, 51, .15);--vg-shadow: rgba(26, 26, 26, .08);--vg-font-display: "Manrope", sans-serif;--vg-font-ui: "Syne", sans-serif;--vg-spacing-xs: .5rem;--vg-spacing-sm: .75rem;--vg-spacing-md: 1.25rem;--vg-spacing-lg: 2rem}.virtualized-grid-container{position:relative;width:100%;height:100%;background:var(--vg-ivory);border:1px solid var(--vg-border);border-radius:2px;overflow:hidden;font-family:var(--vg-font-ui);isolation:isolate;display:flex;flex-direction:column}.grain-overlay{position:absolute;inset:0;pointer-events:none;opacity:.03;mix-blend-mode:overlay;background-image:url("data:image/svg+xml,%3Csvg viewBox='0 0 400 400' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='noiseFilter'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='2.5' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23noiseFilter)'/%3E%3C/svg%3E");z-index:10}.virtualized-grid-header{display:flex;background:linear-gradient(180deg,var(--vg-charcoal) 0%,var(--vg-charcoal-light) 100%);border-bottom:2px solid var(--vg-copper);position:sticky;top:0;z-index:5;box-shadow:0 4px 12px var(--vg-shadow)}.virtualized-grid-header-cell{position:relative;padding:var(--vg-spacing-md) var(--vg-spacing-md);display:flex;flex-direction:column;justify-content:center;border-right:1px solid rgba(184,115,51,.2);animation:fadeInDown .6s cubic-bezier(.16,1,.3,1) both;overflow:hidden}.virtualized-grid-header-cell:last-child{border-right:none}.header-text{font-family:var(--vg-font-ui);font-size:.75rem;font-weight:600;letter-spacing:.1em;text-transform:uppercase;color:var(--vg-ivory);position:relative;z-index:1}.header-accent{position:absolute;bottom:0;left:0;right:0;height:2px;background:linear-gradient(90deg,transparent 0%,var(--vg-copper) 50%,transparent 100%);opacity:0;transition:opacity .4s cubic-bezier(.16,1,.3,1)}.virtualized-grid-header-cell:hover .header-accent{opacity:1}.virtualized-grid-body{overflow:auto;flex:1;position:relative;scrollbar-width:thin;scrollbar-color:var(--vg-copper) var(--vg-ivory-dark);user-select:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none}.virtualized-grid-body::-webkit-scrollbar{width:12px;height:12px}.virtualized-grid-body::-webkit-scrollbar-track{background:var(--vg-ivory-dark)}.virtualized-grid-body::-webkit-scrollbar-thumb{background:var(--vg-copper);border-radius:6px;border:2px solid var(--vg-ivory-dark);transition:background .3s ease}.virtualized-grid-body::-webkit-scrollbar-thumb:hover{background:var(--vg-copper-dark)}.virtualized-grid-row{display:flex;border-bottom:1px solid var(--vg-border);background-color:var(--vg-ivory);transition:all .3s cubic-bezier(.16,1,.3,1);position:relative;isolation:isolate}.virtualized-grid-row.clickable{cursor:pointer}.virtualized-grid-row:hover:not([class*=bg-]):not([style*=background]){background-color:var(--vg-ivory-dark)}.virtualized-grid-row:hover{border-bottom-color:var(--vg-copper-light);box-shadow:0 2px 8px var(--vg-shadow);z-index:1}.virtualized-grid-row.selected{background-color:#b873331f;border-bottom-color:var(--vg-copper);box-shadow:inset 3px 0 0 var(--vg-copper),0 2px 8px var(--vg-shadow);z-index:2}.virtualized-grid-row.selected:hover{background-color:#b873332e;box-shadow:inset 3px 0 0 var(--vg-copper-dark),0 2px 12px var(--vg-shadow)}.virtualized-grid-row.selected .cell-content{color:var(--vg-copper-dark);font-weight:600}.virtualized-grid-row:hover .row-shimmer{opacity:1;transform:translate(100%)}.row-shimmer{position:absolute;top:0;left:0;width:100%;height:100%;background:linear-gradient(90deg,transparent 0%,rgba(184,115,51,.1) 50%,transparent 100%);opacity:0;transform:translate(-100%);transition:transform .8s cubic-bezier(.16,1,.3,1),opacity .3s ease;pointer-events:none;z-index:-1}.virtualized-grid-cell{padding:var(--vg-spacing-md);display:flex;align-items:center;border-right:1px solid rgba(184,115,51,.08);position:relative}.virtualized-grid-cell:last-child{border-right:none}.cell-content{font-family:var(--vg-font-display);font-size:.9375rem;font-weight:500;color:var(--vg-charcoal);line-height:1.5;letter-spacing:-.01em;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;transition:all .3s cubic-bezier(.16,1,.3,1)}.virtualized-grid-row:hover:not([class*=text-]) .cell-content:not([class*=text-]){color:var(--vg-copper-dark)}.virtualized-grid-row:hover .cell-content{transform:translate(2px)}.skeleton-shimmer{background:linear-gradient(90deg,var(--vg-ivory-dark) 0%,var(--vg-ivory) 50%,var(--vg-ivory-dark) 100%);background-size:200% 100%;animation:shimmer 1.5s infinite;border-radius:4px}@keyframes fadeInDown{0%{opacity:0;transform:translateY(-10px)}to{opacity:1;transform:translateY(0)}}@keyframes shimmer{0%{background-position:-200% 0}to{background-position:200% 0}}.virtualized-grid-container.loading{pointer-events:none}.virtualized-grid-container.loading:after{content:"";position:absolute;inset:0;background:linear-gradient(90deg,transparent 0%,rgba(250,248,246,.8) 50%,transparent 100%);animation:shimmer 2s infinite;z-index:20}@media(max-width:768px){.virtualized-grid-header-cell,.virtualized-grid-cell{padding:var(--vg-spacing-sm)}.header-text{font-size:.625rem}.cell-content{font-size:1rem}}.virtualized-grid-context-menu{position:fixed;z-index:50;background:var(--vg-ivory);border:2px solid var(--vg-copper);border-radius:2px;box-shadow:0 8px 24px #1a1a1a26,0 2px 8px #b873331a;padding:4px 0;min-width:180px;animation:contextMenuFadeIn .15s cubic-bezier(.16,1,.3,1);font-family:var(--vg-font-ui)}.virtualized-grid-context-menu button{width:100%;padding:10px 16px;text-align:left;border:none;background:none;cursor:pointer;font-family:var(--vg-font-display);font-size:.875rem;font-weight:500;color:var(--vg-charcoal);transition:all .2s cubic-bezier(.16,1,.3,1);position:relative;overflow:hidden}.virtualized-grid-context-menu button:before{content:"";position:absolute;left:0;top:0;bottom:0;width:3px;background:var(--vg-copper);transform:translate(-3px);transition:transform .2s cubic-bezier(.16,1,.3,1)}.virtualized-grid-context-menu button:hover{background:linear-gradient(90deg,rgba(184,115,51,.08) 0%,transparent 100%);color:var(--vg-copper-dark);padding-left:20px}.virtualized-grid-context-menu button:hover:before{transform:translate(0)}.virtualized-grid-context-menu button:active{background:#b873331f}.virtualized-grid-context-menu-divider{height:1px;background:linear-gradient(90deg,transparent 0%,var(--vg-copper) 50%,transparent 100%);opacity:.3;margin:4px 8px}.virtualized-grid-context-menu-header{padding:8px 16px 4px;font-family:var(--vg-font-ui);font-size:.6875rem;font-weight:700;letter-spacing:.1em;text-transform:uppercase;color:var(--vg-copper)}.virtualized-grid-context-menu button.danger{color:#b91c1c}.virtualized-grid-context-menu button.danger:hover{background:linear-gradient(90deg,rgba(185,28,28,.08) 0%,transparent 100%);color:#991b1b}.virtualized-grid-context-menu button.danger:before{background:#b91c1c}@keyframes contextMenuFadeIn{0%{opacity:0;transform:scale(.95) translateY(-4px)}to{opacity:1;transform:scale(1) translateY(0)}}@media(prefers-contrast:high){.virtualized-grid-container{border-width:2px}.virtualized-grid-row{border-bottom-width:2px}}@media(prefers-reduced-motion:reduce){*,*:before,*:after{animation-duration:.01ms!important;animation-iteration-count:1!important;transition-duration:.01ms!important}}

package/dist/hooks/useDataGrouping.d.ts

@@ -0,0 +1,14 @@
+import { GroupingState } from '../types';
+export interface GroupRow {
+    isGroupRow: true;
+    groupKey: string;
+    groupValue: any;
+    columnId: string;
+    depth: number;
+    count: number;
+    children: any[];
+}
+export declare function useDataGrouping<T>(data: T[], groupingState: GroupingState, _idAccessor: (row: T) => string): {
+    rows: (GroupRow | T)[];
+    flattenedRows: any[];
+};

package/dist/hooks/useGridPersistence.d.ts

@@ -0,0 +1,12 @@
+import { GridPreferences } from '../types';
+export declare function useGridPersistence(gridId: string, columns: {
+    id: string;
+}[], defaultColumnWidth?: number): {
+    preferences: GridPreferences;
+    updateColumnWidth: (columnId: string, width: number) => void;
+    updateColumnOrder: (newOrder: string[]) => void;
+    toggleColumnVisibility: (columnId: string, visible: boolean) => void;
+    updateGroupByColumns: (groupByColumns: string[]) => void;
+    toggleGroupExpanded: (groupKey: string, expanded: boolean) => void;
+    resetPreferences: () => void;
+};

package/dist/hooks/useSelectCell.d.ts

@@ -0,0 +1,10 @@
+export interface CellPosition {
+    rowId: string;
+    columnId: string;
+}
+export declare function useSelectCell(): {
+    selectedCell: CellPosition | null;
+    selectCell: (rowId: string, columnId: string) => void;
+    clearSelection: () => void;
+    isCellSelected: (rowId: string, columnId: string) => boolean;
+};