npm package: @skars1705/advanced-table-engine
Description: A comprehensive, feature-rich React data grid library with sorting, filtering, grouping, virtualization, and export capabilities
Author: skars1705
Latest version: 0.1.0

# Advanced Table Engine

A high-performance, architecture-driven React toolkit for managing large-scale enterprise data.

## Key Features

- **Virtualization**: Fluid performance for 100k+ rows via `@tanstack/react-virtual`.
- **Atomic Batching**: Efficient updates for large selections via `onUpdateDataBatch`.
- **Recursive Grouping**: Multi-level data aggregation with conditional rule support.
- **Row & Group Summarization**: Built-in calculation engine for totals, averages, median, mode, and counts at both the table footer and group header levels.
- **Expandable Rows**: Master-detail view support with high-performance CSS-driven animations, decoupled virtualization integration, and flexible content rendering.
- **Combined Columns**: Create composite columns (e.g., "First" + "Last" = "Full Name") dynamically. Uses **Lazy Evaluation** to resolve values on-the-fly, ensuring zero initial load penalty.
- **Data Export**: Native support for CSV and Excel exports with data formatting preservation.
- **Theming & Dark Mode**: Full Light/Dark mode support using Semantic CSS Tokens and `ThemeContext`.
- **Slot-Based Customization**: Fine-grained styling overrides via `classNames` prop and `tailwind-merge`.
- **Resilient UI**: Context-aware Error Boundaries with localized recovery.
- **WAI-ARIA Compliance**: Full keyboard and screen-reader support for tables and tabs.

## Installation

```bash
npm install @skars1705/advanced-table-engine
```

### Peer Dependencies

```bash
npm install react react-dom
```

### Optional Dependencies

```bash
# Required for Excel export functionality
npm install exceljs
```

## Quick Start

### Basic Table Implementation

```tsx
import { useMemo } from 'react';
import {
  ReusableTable,
  ClientDataSource,
  ThemeProvider,
  type Column,
  type ViewConfiguration
} from '@skars1705/advanced-table-engine';

// 1. Define Data Type
interface User {
  id: number;
  name: string;
  salary: number;
}

const MyComponent = ({ users }: { users: User[] }) => {
  // 2. Define Columns (Memoized)
  const columns = useMemo<Column<User>[]>(() => [
    { header: 'Name', accessor: 'name', sortable: true },
    { header: 'Salary', accessor: 'salary', dataType: 'currency', currencyOptions: { locale: 'en-US', currency: 'USD' } }
  ], []);

  // 3. Initialize Data Source (Memoized)
  const dataSource = useMemo(() => new ClientDataSource(users, columns), [users, columns]);

  // 4. Configure View
  const viewConfig: ViewConfiguration<User> = {
    id: 'default',
    name: 'Default',
    visibleColumns: ['name', 'salary'],
    groupBy: [],
    sortConfig: [],
    filterConfig: [],
    summarization: {
      enabled: true,
      position: 'bottom',
      sticky: true,
      columns: [
        { column: 'salary', function: 'sum', label: 'Total' },
        { column: 'salary', function: 'average', label: 'Avg' }
      ]
    },
    combinedColumns: []
  };

  return (
    <ThemeProvider>
      <ReusableTable
        tableId="users-grid"
        allColumns={columns}
        dataSource={dataSource}
        viewConfig={viewConfig}
        exportOptions={{
          fileName: 'users-export',
          allowExcel: true,
          allowCsv: true
        }}
        classNames={{
          header: 'bg-gray-100 dark:bg-gray-800 text-blue-600',
          row: 'hover:bg-blue-50 dark:hover:bg-blue-900/20'
        }}
      />
    </ThemeProvider>
  );
};
```

### Implementing Resilience

Wrap high-risk components in `ErrorBoundary` to prevent total application crashes.

```tsx
import { ErrorBoundary, ReusableTable } from '@skars1705/advanced-table-engine';

<ErrorBoundary name="Inventory Panel" onReset={() => resetStore()}>
  <ReusableTable {...props} />
</ErrorBoundary>
```

## Core Exports

### Components
- `ReusableTable` - Main table component with full feature set
- `ViewEditor` - View configuration UI for columns, grouping, and summaries
- `ThemeProvider` - Theme context provider for light/dark mode
- `Pagination` - Pagination controls
- `ErrorBoundary` - Error handling wrapper with recovery support
- `Tabs` / `Tab` - Accessible tab components with keyboard navigation

### Hooks
- `useTable` - Core table state management and query coordination
- `useExpandableRows` - Expandable row state management
- `useSummarization` - Aggregation calculations
- `useInlineEdit` - Cell editing state and validation
- `useCombinedColumns` - Combined column definitions

### Data Sources
- `ClientDataSource` - Client-side data operations with filtering, sorting, and grouping

### Utilities
- `downloadCSV` - Export data to CSV (Excel-compatible UTF-8)
- `downloadExcel` - Export data to Excel (.xlsx)
- `copyToClipboard` - Copy table data to clipboard

## Aggregation Functions

| Function | Description |
|----------|-------------|
| `sum` | Sum of all values |
| `average` | Arithmetic mean |
| `min` / `max` | Minimum / Maximum value |
| `median` | Middle value |
| `mode` | Most frequent value |
| `count` | Total count |
| `countUnique` | Unique values count |
| `countEmpty` / `countNonEmpty` | Empty/non-empty count |
| `percentEmpty` / `percentNonEmpty` | Percentage empty/non-empty |
| `range` | Difference between max and min |
| `earliest` / `latest` | Date range functions |
| `custom` | Custom aggregation function |

## Documentation

Detailed guides can be found in the `/Project Documentation` folder:
- [API Reference](./Project%20Documentation/API_Reference.md)
- [Architecture & Design Patterns](./Project%20Documentation/Architecture.md)
- [Accessibility Guide](./Project%20Documentation/Do's%20&%20Dont's.md)

## Development

```bash
# Install dependencies
npm install

# Run demo app
npm run dev

# Build library for distribution
npm run build:lib
```

## License

MIT