@ackplus/react-tanstack-data-table 1.0.19-beta-0.7 → 1.0.19-beta-0.8

package/README.md

@@ -0,0 +1,599 @@
+# @ackplus/react-tanstack-data-table
+
+A powerful, feature-rich, and highly customizable React data table component built with Material-UI (MUI) and TanStack Table. Perfect for building modern data-intensive applications with advanced table functionality.
+
+## ✨ Features
+
+- 🚀 **High Performance**: Built on TanStack Table for excellent performance with large datasets
+- 🎨 **Material Design**: Beautiful UI components using MUI with consistent design system
+- 📱 **Responsive**: Mobile-friendly responsive design with adaptive layouts
+- 🔍 **Advanced Filtering**: Global search, column filters, and custom filter components
+- 📊 **Multi-Column Sorting**: Powerful sorting with multiple columns support
+- 📄 **Flexible Pagination**: Client-side and server-side pagination options
+- 🎯 **Column Management**: Show/hide, resize, reorder, and pin columns
+- 📤 **Data Export**: Export to CSV/Excel with progress tracking and customization
+- 🖱️ **Row Selection**: Single and multi-row selection with bulk actions
+- ⚡ **Virtualization**: Handle large datasets efficiently with row virtualization
+- 🔄 **Server Integration**: Built-in support for server-side operations
+- 🎛️ **Highly Customizable**: Extensive customization through slots and props
+- 📝 **TypeScript**: Full TypeScript support with comprehensive type definitions
+- 🔌 **Extensible**: Plugin architecture with custom components and hooks
+
+## 📦 Installation
+
+```bash
+npm install @ackplus/react-tanstack-data-table
+```
+
+```bash
+yarn add @ackplus/react-tanstack-data-table
+```
+
+```bash
+pnpm add @ackplus/react-tanstack-data-table
+```
+
+## 🔧 Peer Dependencies
+
+Make sure you have the following peer dependencies installed:
+
+```bash
+npm install @emotion/react @emotion/styled @mui/icons-material @mui/material @tanstack/react-table @tanstack/react-virtual react react-dom
+```
+
+## 🚀 Quick Start
+
+```tsx
+import React from 'react';
+import { DataTable } from '@ackplus/react-tanstack-data-table';
+import { createColumnHelper } from '@tanstack/react-table';
+
+interface User {
+  id: number;
+  name: string;
+  email: string;
+  status: 'active' | 'inactive';
+  role: string;
+}
+
+const columnHelper = createColumnHelper<User>();
+
+const columns = [
+  columnHelper.accessor('name', {
+    header: 'Name',
+    size: 150,
+  }),
+  columnHelper.accessor('email', {
+    header: 'Email',
+    size: 200,
+  }),
+  columnHelper.accessor('status', {
+    header: 'Status',
+    cell: ({ getValue }) => (
+      <Chip 
+        label={getValue()} 
+        color={getValue() === 'active' ? 'success' : 'default'} 
+      />
+    ),
+  }),
+  columnHelper.accessor('role', {
+    header: 'Role',
+    size: 120,
+  }),
+];
+
+const data: User[] = [
+  { id: 1, name: 'John Doe', email: 'john@example.com', status: 'active', role: 'Admin' },
+  { id: 2, name: 'Jane Smith', email: 'jane@example.com', status: 'inactive', role: 'User' },
+  // ... more data
+];
+
+function MyDataTable() {
+  return (
+    <DataTable
+      columns={columns}
+      data={data}
+      enableSorting
+      enableGlobalFilter
+      enablePagination
+      enableRowSelection
+      enableColumnVisibility
+      enableExport
+    />
+  );
+}
+```
+
+## 📋 Core Props
+
+### Basic Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `columns` | `DataTableColumn<T>[]` | **Required** | Column definitions array |
+| `data` | `T[]` | `[]` | Array of data objects |
+| `idKey` | `keyof T` | `'id'` | Unique identifier key for rows |
+| `loading` | `boolean` | `false` | Loading state indicator |
+| `emptyMessage` | `string` | `'No data available'` | Message when no data |
+
+### Data Management
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `dataMode` | `'client' \| 'server'` | `'client'` | Data management mode |
+| `initialLoadData` | `boolean` | `true` | Load data on component mount |
+| `onFetchData` | `(filters) => Promise<{data, total}>` | - | Server-side data fetching |
+| `onDataStateChange` | `(state) => void` | - | Called when table state changes |
+| `totalRow` | `number` | `0` | Total rows for server-side pagination |
+
+### Selection & Interaction
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `enableRowSelection` | `boolean \| ((row) => boolean)` | `false` | Enable row selection |
+| `enableMultiRowSelection` | `boolean` | `true` | Allow multiple row selection |
+| `onRowSelectionChange` | `(selectedRows: T[]) => void` | - | Selection change callback |
+| `enableBulkActions` | `boolean` | `false` | Enable bulk actions toolbar |
+| `bulkActions` | `(selectionState: SelectionState) => ReactNode` | - | Custom bulk actions component |
+
+### Selection State
+
+The `SelectionState` interface provides detailed information about the current selection:
+
+```typescript
+interface SelectionState {
+  ids: string[];           // Array of selected/excluded row IDs
+  type: 'include' | 'exclude';  // Selection mode
+}
+```
+
+- **Include mode**: `ids` contains the selected row IDs
+- **Exclude mode**: `ids` contains the excluded row IDs (all others are selected)
+
+This allows for efficient handling of large datasets where you might select "all except these few".
+
+### Pagination
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `enablePagination` | `boolean` | `true` | Enable pagination |
+| `paginationMode` | `'client' \| 'server'` | `'client'` | Pagination mode |
+| `initialState.pagination` | `{pageIndex: number, pageSize: number}` | `{pageIndex: 0, pageSize: 50}` | Initial pagination state |
+
+### Filtering & Search
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `enableGlobalFilter` | `boolean` | `true` | Enable global search |
+| `enableColumnFilter` | `boolean` | `false` | Enable individual column filters |
+| `filterMode` | `'client' \| 'server'` | `'client'` | Filtering mode |
+| `onColumnFiltersChange` | `(filters) => void` | - | Column filters change callback |
+| `extraFilter` | `ReactNode` | - | Additional filter components |
+
+### Sorting
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `enableSorting` | `boolean` | `true` | Enable column sorting |
+| `sortingMode` | `'client' \| 'server'` | `'client'` | Sorting mode |
+| `onSortingChange` | `(sorting) => void` | - | Sorting change callback |
+
+### Column Management
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `enableColumnVisibility` | `boolean` | `true` | Show/hide columns control |
+| `enableColumnResizing` | `boolean` | `false` | Allow column resizing |
+| `enableColumnPinning` | `boolean` | `false` | Allow column pinning |
+| `draggable` | `boolean` | `false` | Enable column reordering |
+| `onColumnDragEnd` | `(order: string[]) => void` | - | Column reorder callback |
+| `onColumnPinningChange` | `(pinning) => void` | - | Column pinning callback |
+
+### Export Features
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `enableExport` | `boolean` | `true` | Enable data export |
+| `exportFilename` | `string` | `'export'` | Default export filename |
+| `onExportProgress` | `(progress) => void` | - | Export progress callback |
+| `onExportComplete` | `(result) => void` | - | Export completion callback |
+| `onExportError` | `(error) => void` | - | Export error callback |
+| `onServerExport` | `(filters) => Promise<{data, total}>` | - | Server-side export handler |
+
+### Expandable Rows
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `enableExpanding` | `boolean` | `false` | Enable row expansion |
+| `getRowCanExpand` | `(row) => boolean` | - | Determine if row can expand |
+| `renderSubComponent` | `(row) => ReactNode` | - | Render expanded row content |
+
+### Styling & Layout
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `tableSize` | `'small' \| 'medium'` | `'medium'` | Table size/density |
+| `enableHover` | `boolean` | `true` | Row hover effects |
+| `enableStripes` | `boolean` | `false` | Alternating row colors |
+| `fitToScreen` | `boolean` | `true` | Fit table to container width |
+| `enableStickyHeaderOrFooter` | `boolean` | `false` | Sticky header/footer |
+| `maxHeight` | `string \| number` | `'400px'` | Max table height |
+
+### Virtualization
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `enableVirtualization` | `boolean` | `false` | Enable row virtualization |
+| `estimateRowHeight` | `number` | `52` | Estimated row height for virtualization |
+
+### Advanced Customization
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `slots` | `Partial<DataTableSlots<T>>` | `{}` | Custom component slots |
+| `slotProps` | `PartialSlotProps<T>` | `{}` | Props for slot components |
+| `tableContainerProps` | `object` | `{}` | Props for table container |
+| `tableProps` | `object` | `{}` | Props for table element |
+
+## 🔥 Advanced Examples
+
+### Server-Side Data Management
+
+```tsx
+import { DataTable } from '@ackplus/react-tanstack-data-table';
+import { useState, useCallback } from 'react';
+
+function ServerSideTable() {
+  const [loading, setLoading] = useState(false);
+
+  const fetchData = useCallback(async (filters) => {
+    setLoading(true);
+    try {
+      const response = await fetch('/api/users', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(filters),
+      });
+      const result = await response.json();
+      return { data: result.users, total: result.total };
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  return (
+    <DataTable
+      columns={columns}
+      dataMode="server"
+      loading={loading}
+      onFetchData={fetchData}
+      enablePagination
+      enableSorting
+      enableGlobalFilter
+      paginationMode="server"
+      sortingMode="server"
+      filterMode="server"
+    />
+  );
+}
+```
+
+### Row Selection with Bulk Actions
+
+```tsx
+function SelectableTable() {
+  const [selectedUsers, setSelectedUsers] = useState([]);
+
+  const bulkActions = (selectionState) => {
+    // Calculate selected count based on selection type
+    const selectedCount = selectionState.type === 'include' 
+      ? selectionState.ids.length 
+      : data.length - selectionState.ids.length;
+
+    // Get actual selected data
+    const selectedRows = selectionState.type === 'include'
+      ? data.filter(item => selectionState.ids.includes(item.id.toString()))
+      : data.filter(item => !selectionState.ids.includes(item.id.toString()));
+
+    return (
+      <Stack direction="row" spacing={1}>
+        <Button 
+          variant="contained" 
+          color="error"
+          onClick={() => deleteUsers(selectedRows)}
+        >
+          Delete ({selectedCount})
+        </Button>
+        <Button 
+          variant="outlined"
+          onClick={() => exportUsers(selectedRows)}
+        >
+          Export Selected
+        </Button>
+      </Stack>
+    );
+  };
+
+  return (
+    <DataTable
+      columns={columns}
+      data={data}
+      enableRowSelection
+      enableMultiRowSelection
+      enableBulkActions
+      bulkActions={bulkActions}
+      onRowSelectionChange={setSelectedUsers}
+    />
+  );
+}
+```
+
+### Custom Column Filters
+
+```tsx
+const columns = [
+  {
+    accessorKey: 'status',
+    header: 'Status',
+    filterable: true,
+    type: 'select',
+    options: [
+      { value: 'active', label: 'Active' },
+      { value: 'inactive', label: 'Inactive' },
+      { value: 'pending', label: 'Pending' },
+    ],
+  },
+  {
+    accessorKey: 'priority',
+    header: 'Priority',
+    filterable: true,
+    type: 'number',
+  },
+  {
+    accessorKey: 'created',
+    header: 'Created Date',
+    filterable: true,
+    type: 'date',
+  },
+];
+
+function FilterableTable() {
+  return (
+    <DataTable
+      columns={columns}
+      data={data}
+      enableColumnFilter
+      enableGlobalFilter
+    />
+  );
+}
+```
+
+### Expandable Rows
+
+```tsx
+function ExpandableTable() {
+  const renderSubComponent = (row) => (
+    <Box p={2}>
+      <Typography variant="h6">User Details</Typography>
+      <Grid container spacing={2}>
+        <Grid item xs={6}>
+          <Typography><strong>ID:</strong> {row.original.id}</Typography>
+          <Typography><strong>Email:</strong> {row.original.email}</Typography>
+        </Grid>
+        <Grid item xs={6}>
+          <Typography><strong>Role:</strong> {row.original.role}</Typography>
+          <Typography><strong>Status:</strong> {row.original.status}</Typography>
+        </Grid>
+      </Grid>
+    </Box>
+  );
+
+  return (
+    <DataTable
+      columns={columns}
+      data={data}
+      enableExpanding
+      getRowCanExpand={(row) => row.original.details != null}
+      renderSubComponent={renderSubComponent}
+    />
+  );
+}
+```
+
+### Column Management
+
+```tsx
+function ManageableColumnsTable() {
+  const [columnOrder, setColumnOrder] = useState([]);
+  const [columnPinning, setColumnPinning] = useState({ left: [], right: [] });
+
+  return (
+    <DataTable
+      columns={columns}
+      data={data}
+      enableColumnVisibility
+      enableColumnResizing
+      enableColumnPinning
+      draggable
+      onColumnDragEnd={setColumnOrder}
+      onColumnPinningChange={setColumnPinning}
+      initialState={{
+        columnOrder,
+        columnPinning,
+      }}
+    />
+  );
+}
+```
+
+### Export with Progress Tracking
+
+```tsx
+function ExportableTable() {
+  const [exportProgress, setExportProgress] = useState(null);
+
+  const handleExportProgress = (progress) => {
+    setExportProgress(progress);
+  };
+
+  const handleExportComplete = (result) => {
+    setExportProgress(null);
+  };
+
+  return (
+    <DataTable
+      columns={columns}
+      data={data}
+      enableExport
+      exportFilename="users-export"
+      onExportProgress={handleExportProgress}
+      onExportComplete={handleExportComplete}
+      onExportError={(error) => console.error('Export failed:', error)}
+    />
+  );
+}
+```
+
+## 🎛️ API Reference
+
+### DataTable Component
+
+The main component that renders the data table with all features.
+
+```tsx
+<DataTable<T>
+  columns={DataTableColumn<T>[]}
+  data={T[]}
+  // ... other props
+/>
+```
+
+### Column Definition
+
+Columns are defined using TanStack Table's column definition format with additional properties:
+
+```tsx
+interface DataTableColumn<T> extends ColumnDef<T> {
+  // Display properties
+  align?: 'left' | 'center' | 'right';
+  // Filtering
+  filterable?: boolean;
+  type?: 'boolean' | 'number' | 'date' | 'select' | 'text';
+  options?: { label: string; value: string }[];
+  
+  // Export
+  hideInExport?: boolean;
+}
+```
+
+### useDataTableApi Hook
+
+Access the table's imperative API:
+
+```tsx
+import { useRef } from 'react';
+import { DataTable, DataTableApi } from '@ackplus/react-tanstack-data-table';
+
+function MyComponent() {
+  const tableRef = useRef<DataTableApi<User>>(null);
+
+  const handleGetData = () => {
+    const allData = tableRef.current?.data.getAllData();
+  };
+
+  return (
+    <DataTable
+      ref={tableRef}
+      columns={columns}
+      data={data}
+    />
+  );
+}
+```
+
+## 🎨 Customization
+
+### Slots System
+
+Customize any part of the table using the slots system:
+
+```tsx
+const customSlots = {
+  toolbar: MyCustomToolbar,
+  pagination: MyCustomPagination,
+  loadingRow: MyCustomLoadingRow,
+  emptyRow: MyCustomEmptyRow,
+};
+
+<DataTable
+  columns={columns}
+  data={data}
+  slots={customSlots}
+  slotProps={{
+    toolbar: { customProp: 'value' },
+    pagination: { showFirstLastButtons: true },
+  }}
+/>
+```
+
+### Available Slots
+
+- `root` - Root container
+- `toolbar` - Main toolbar
+- `bulkActionsToolbar` - Bulk actions toolbar
+- `tableContainer` - Table container
+- `table` - Table element
+- `header` - Table header
+- `body` - Table body
+- `row` - Table row
+- `cell` - Table cell
+- `footer` - Table footer
+- `pagination` - Pagination component
+- `loadingRow` - Loading state row
+- `emptyRow` - Empty state row
+
+## 🔧 Migration Guide
+
+### From v0.x to v1.x
+
+Key changes in v1.0:
+- Updated to latest TanStack Table v8
+- Improved TypeScript support
+- Enhanced slot system
+- Better server-side integration
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](https://github.com/ack-solutions/react-tanstack-data-table/blob/main/CONTRIBUTING.md) for details.
+
+## 💖 Support the Project
+
+If you find this package helpful and want to support its development, consider making a donation:
+
+<div align="center">
+
+[![PayPal](https://img.shields.io/badge/PayPal-00457C?style=for-the-badge&logo=paypal&logoColor=white)](https://www.paypal.com/paypalme/my/profile)
+[![Razorpay](https://img.shields.io/badge/Razorpay-02042B?style=for-the-badge&logo=razorpay&logoColor=white)](https://razorpay.me/@ackplus)
+
+**[💳 PayPal](https://www.paypal.com/paypalme/my/profile)** • **[💳 Razorpay](https://razorpay.me/@ackplus)**
+
+</div>
+
+Your support helps us:
+- 🛠️ Maintain and improve the library
+- 🐛 Fix bugs and add new features
+- 📚 Create better documentation
+- 🚀 Keep the project active and up-to-date
+
+## 📄 License
+
+MIT © [ACK Solutions](https://github.com/ack-solutions)
+
+## 🆘 Support
+
+- 📖 [Documentation](https://github.com/ack-solutions/react-tanstack-data-table)
+- 🐛 [Issue Tracker](https://github.com/ack-solutions/react-tanstack-data-table/issues)
+- 💬 [Discussions](https://github.com/ack-solutions/react-tanstack-data-table/discussions)
+
+If you find this package helpful, please consider giving it a ⭐ on [GitHub](https://github.com/ack-solutions/react-tanstack-data-table)!

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ackplus/react-tanstack-data-table",
   "type": "commonjs",
-  "version": "1.0.19-beta-0.7",
+  "version": "1.0.19-beta-0.8",
   "description": "A powerful React data table component built with MUI and TanStack Table",
   "keywords": [
     "react",

package/src/index.d.ts

@@ -0,0 +1,19 @@
+export { DataTable } from './lib/components/table';
+export type { DataTableProps } from './lib/components/table';
+export * from './lib/components/headers';
+export * from './lib/components/rows';
+export * from './lib/components/filters';
+export * from './lib/components/pagination';
+export * from './lib/components/droupdown/menu-dropdown';
+export { ColumnVisibilityControl, ColumnPinningControl, ColumnResetControl, TableExportControl, TableSizeControl, BulkActionsToolbar, DataTableToolbar, } from './lib/components/toolbar';
+export type { BulkActionsToolbarProps } from './lib/components/toolbar';
+export * from './lib/utils/styling-helpers';
+export * from './lib/utils/column-helpers';
+export * from './lib/utils/table-helpers';
+export * from './lib/hooks';
+export * from './lib/types';
+export type { Column, ColumnDef, Row, Table, Header, Cell, SortingState, ColumnFiltersState, VisibilityState, ColumnOrderState, ColumnPinningState, PaginationState, } from '@tanstack/react-table';
+export * from './lib/features';
+export { CustomColumnFilterExample } from './lib/examples/custom-column-filter-example';
+export { SimpleLocalExample } from './lib/examples/simple-local-example';
+export { AdvancedFeaturesExample } from './lib/examples/advanced-features-example';

package/src/index.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdvancedFeaturesExample = exports.SimpleLocalExample = exports.CustomColumnFilterExample = exports.DataTableToolbar = exports.BulkActionsToolbar = exports.TableSizeControl = exports.TableExportControl = exports.ColumnResetControl = exports.ColumnPinningControl = exports.ColumnVisibilityControl = exports.DataTable = void 0;
+const tslib_1 = require("tslib");
+var table_1 = require("./lib/components/table");
+Object.defineProperty(exports, "DataTable", { enumerable: true, get: function () { return table_1.DataTable; } });
+tslib_1.__exportStar(require("./lib/components/headers"), exports);
+tslib_1.__exportStar(require("./lib/components/rows"), exports);
+tslib_1.__exportStar(require("./lib/components/filters"), exports);
+tslib_1.__exportStar(require("./lib/components/pagination"), exports);
+tslib_1.__exportStar(require("./lib/components/droupdown/menu-dropdown"), exports);
+var toolbar_1 = require("./lib/components/toolbar");
+Object.defineProperty(exports, "ColumnVisibilityControl", { enumerable: true, get: function () { return toolbar_1.ColumnVisibilityControl; } });
+Object.defineProperty(exports, "ColumnPinningControl", { enumerable: true, get: function () { return toolbar_1.ColumnPinningControl; } });
+Object.defineProperty(exports, "ColumnResetControl", { enumerable: true, get: function () { return toolbar_1.ColumnResetControl; } });
+Object.defineProperty(exports, "TableExportControl", { enumerable: true, get: function () { return toolbar_1.TableExportControl; } });
+Object.defineProperty(exports, "TableSizeControl", { enumerable: true, get: function () { return toolbar_1.TableSizeControl; } });
+Object.defineProperty(exports, "BulkActionsToolbar", { enumerable: true, get: function () { return toolbar_1.BulkActionsToolbar; } });
+Object.defineProperty(exports, "DataTableToolbar", { enumerable: true, get: function () { return toolbar_1.DataTableToolbar; } });
+tslib_1.__exportStar(require("./lib/utils/styling-helpers"), exports);
+tslib_1.__exportStar(require("./lib/utils/column-helpers"), exports);
+tslib_1.__exportStar(require("./lib/utils/table-helpers"), exports);
+tslib_1.__exportStar(require("./lib/hooks"), exports);
+tslib_1.__exportStar(require("./lib/types"), exports);
+tslib_1.__exportStar(require("./lib/features"), exports);
+var custom_column_filter_example_1 = require("./lib/examples/custom-column-filter-example");
+Object.defineProperty(exports, "CustomColumnFilterExample", { enumerable: true, get: function () { return custom_column_filter_example_1.CustomColumnFilterExample; } });
+var simple_local_example_1 = require("./lib/examples/simple-local-example");
+Object.defineProperty(exports, "SimpleLocalExample", { enumerable: true, get: function () { return simple_local_example_1.SimpleLocalExample; } });
+var advanced_features_example_1 = require("./lib/examples/advanced-features-example");
+Object.defineProperty(exports, "AdvancedFeaturesExample", { enumerable: true, get: function () { return advanced_features_example_1.AdvancedFeaturesExample; } });

package/src/lib/components/droupdown/menu-dropdown.d.ts

@@ -0,0 +1,17 @@
+import { Menu, MenuProps, Popover } from '@mui/material';
+import { ReactElement, ReactNode } from 'react';
+type ChildrenEvent = {
+    handleClose: () => void;
+    open: boolean;
+};
+type AnchorEvent = {
+    isOpen: boolean;
+};
+export interface MenuDropdownProps extends Omit<MenuProps, 'children' | 'open'> {
+    children?: ((event: ChildrenEvent) => ReactNode) | ReactNode | any;
+    anchor?: ((event: AnchorEvent) => ReactElement<any>) | ReactElement<any>;
+    label?: ReactNode;
+    component?: typeof Popover | typeof Menu;
+}
+export declare function MenuDropdown({ children, anchor, label, component, sx, ...props }: MenuDropdownProps): import("react/jsx-runtime").JSX.Element;
+export {};