ia-table 0.1.0

package/README.md

@@ -0,0 +1,431 @@
+# ia-table
+
+A powerful, feature-rich React data table component for enterprise applications.
+
+[![NPM](https://img.shields.io/npm/v/ia-table.svg)](https://www.npmjs.com/package/ia-table)
+
+## Installation
+
+```bash
+npm install --save ia-table
+```
+
+## Quick Start
+
+```jsx
+import { IATable } from 'ia-table';
+import 'ia-table/dist/style.css'; // Import styles
+
+const App = () => {
+  const data = [
+    { id: 1, name: 'Product A', price: 100 },
+    { id: 2, name: 'Product B', price: 200 },
+  ];
+
+  const columns = [
+    { field: 'id', headerName: 'ID' },
+    { field: 'name', headerName: 'Name' },
+    { field: 'price', headerName: 'Price' },
+  ];
+
+  return (
+    <IATable 
+      data={data}
+      columns={columns}
+      height="400px"
+      uniqueIdField="id"
+    />
+  );
+};
+```
+
+For detailed documentation on publishing this package, see [PUBLISHING.md](./PUBLISHING.md).
+
+## Features
+
+### Core Table Features
+
+- **Data Display**:
+
+  - Renders tabular data with fully customizable columns
+  - Supports complex data objects and nested properties
+  - Handles large datasets efficiently with virtualization
+  - Displays empty state and loading indicators
+
+- **Responsive Layout**:
+
+  - Adapts to container size with proper overflow handling
+  - Horizontal scrolling for tables wider than their container
+  - Maintains header alignment with body cells during scroll
+  - Supports fixed height or auto-expanding layouts
+
+- **Dynamic Column Configuration**:
+  - Configure width, alignment, sorting, filtering, and resizing per column
+  - Support for complex column hierarchies with nested column groups
+  - Custom cell renderers for advanced content formatting
+  - Header customization with custom renderers
+  - Column freezing/pinning for better navigation of wide tables
+  - Show/hide columns via the column toggle menu
+
+### Data Management
+
+- **Sorting**:
+
+  - Sort data by any column in ascending or descending order
+  - Visual indicators for sort direction
+  - Support for custom sort functions
+  - Multi-column sorting capability
+  - Maintains sort state between renders
+
+- **Pagination**:
+
+  - Built-in pagination with customizable page size
+  - Page navigation controls (previous, next, first, last)
+  - Dynamic calculation of total pages
+  - Efficient page switching without re-rendering the entire table
+  - Customizable page size options
+
+- **Filtering**:
+  - Global search functionality across all columns or specific columns
+  - Column-specific filtering with custom filter inputs
+  - Advanced filter panel with multiple filter conditions
+  - Filter operators include: contains, equals, startsWith, endsWith, etc.
+  - Support for numeric filters (greater than, less than)
+  - Date filtering capabilities
+  - Boolean filters (is/is not)
+  - Empty/not empty filters
+
+### Row Features
+
+- **Row Selection**:
+
+  - Single or multi-row selection with checkbox support
+  - Select all/deselect all functionality
+  - Selection persistence between page changes
+  - Selection state callbacks for external state management
+  - Visual indication of selected rows
+  - Access to selection data through context
+
+- **Row Expansion**:
+
+  - Expandable rows with custom content
+  - Expand/collapse indicators with animation
+  - Customizable expanded content renderer
+  - Independent expansion state for each row
+  - Context-aware expansion tracking
+
+- **Row Grouping**:
+
+  - Support for hierarchical data with parent-child relationships
+  - Configurable grouping fields
+  - Visual indicators for grouped data
+  - Expand/collapse functionality for group items
+  - Custom renderers for group rows
+  - Supports multiple levels of nesting
+
+- **Row Virtualization**:
+  - Performance optimization for large datasets (>100 rows)
+  - Only renders visible rows and a small buffer
+  - Seamless scrolling through thousands of rows
+  - Dynamic height calculation for varying row heights
+  - Memory efficient for very large datasets
+  - Maintains scroll position during updates
+
+### UI Components
+
+- **Table Header**:
+
+  - Customizable with sort indicators
+  - Support for multi-level column groups
+  - Column resizing via drag handles
+  - Fixed positioning during scroll
+  - Context menu for column operations
+  - Support for custom header cell renderers
+
+- **Table Body**:
+
+  - Efficient rendering with virtualization for large datasets
+  - Custom cell renderers for complex content
+  - Row and cell event handlers (click, hover, etc.)
+  - Support for keyboard navigation
+  - Proper handling of null/undefined values
+  - Type-aware cell formatting
+
+- **Table Footer**:
+
+  - Optional with pagination controls
+  - Summary row capabilities
+  - Aggregate function support (sum, average, count, etc.)
+  - Fixed positioning for easy access
+  - Custom footer renderers
+
+- **Toolbar**:
+
+  - Search functionality with debounced input
+  - Column visibility toggle
+  - Export options (CSV, Excel, etc.)
+  - Custom action buttons
+  - Responsive design for mobile compatibility
+
+- **Column Toggle Menu**:
+
+  - Show/hide columns dynamically
+  - Drag and drop column reordering
+  - Reset to default option
+  - Search columns functionality
+  - Column group management
+
+- **Filter Panel**:
+  - Complex filtering interface
+  - Add/remove filter conditions
+  - Combine multiple filters
+  - Filter operator selection
+  - Type-aware filter inputs
+  - Save filter presets
+
+### Visual Customization
+
+- **Column Resizing**:
+
+  - Drag handles to adjust column widths
+  - Visual feedback during resize operation
+  - Minimum/maximum width constraints
+  - Double-click to auto-size based on content
+  - Persist column width preferences
+
+- **Styling**:
+
+  - Comprehensive CSS for enterprise appearance
+  - Support for theming and custom styles
+  - Responsive design principles
+  - Accessible color schemes
+  - Row alternating colors
+  - Hover and selection styles
+
+- **Custom Cell Rendering**:
+  - Format cell content with custom renderers
+  - Support for complex components within cells
+  - Cell editor integration
+  - Conditional formatting based on cell values
+  - Support for images, icons, and rich content
+
+### Performance Optimizations
+
+- **Virtualized Rendering**:
+
+  - Only renders visible rows for large datasets
+  - Significantly improves performance for tables with thousands of rows
+  - Dynamic buffer size calculation
+  - Smooth scrolling experience
+  - Efficient DOM reuse
+
+- **Memoization**:
+
+  - Efficient re-rendering using React.useMemo
+  - Prevents unnecessary calculations during renders
+  - Smart component updates based on changed props
+  - Optimized context usage to prevent re-renders
+
+- **Optimized Filtering**:
+  - Smart filter application for large datasets
+  - Debounced search input to prevent excessive filtering
+  - Cached filter results when possible
+  - Progressive filtering for complex conditions
+  - Background processing for non-blocking UX
+
+## Usage
+
+```jsx
+import CustomTable from "./components/CustomTable";
+
+// Sample data
+const data = [
+  { id: 1, name: "Product A", category: "Electronics", price: 299.99 },
+  { id: 2, name: "Product B", category: "Furniture", price: 599.99 },
+  // ...more rows
+];
+
+// Column definitions
+const columns = [
+  {
+    field: "id",
+    headerName: "ID",
+    width: 80,
+    sortable: true,
+  },
+  {
+    field: "name",
+    headerName: "Product Name",
+    width: 200,
+    sortable: true,
+    filterable: true,
+  },
+  {
+    field: "category",
+    headerName: "Category",
+    width: 150,
+    sortable: true,
+    filterable: true,
+  },
+  {
+    field: "price",
+    headerName: "Price",
+    width: 120,
+    align: "right",
+    sortable: true,
+    filterable: true,
+    cellRenderer: ({ value }) => `$${value.toFixed(2)}`,
+  },
+];
+
+// Component implementation
+const MyTable = () => {
+  return (
+    <CustomTable
+      data={data}
+      columns={columns}
+      height="500px"
+      uniqueIdField="id"
+      selectable={true}
+      pagination={true}
+      pageSize={10}
+    />
+  );
+};
+```
+
+## Props
+
+| Prop            | Type     | Default         | Description                                        |
+| --------------- | -------- | --------------- | -------------------------------------------------- |
+| `data`          | Array    | `[]`            | Array of data objects to display                   |
+| `columns`       | Array    | `[]`            | Column definitions                                 |
+| `height`        | String   | `'auto'`        | Table height                                       |
+| `uniqueIdField` | String   | `'store_code'`  | Field to use as unique row identifier              |
+| `childKeyField` | String   | `'status_obj1'` | Field containing child items for hierarchical data |
+| `showHeader`    | Boolean  | `true`          | Whether to show the table header                   |
+| `showFooter`    | Boolean  | `false`         | Whether to show the table footer                   |
+| `showToolbar`   | Boolean  | `true`          | Whether to show the toolbar                        |
+| `showFilters`   | Boolean  | `false`         | Whether to show the filter panel                   |
+| `selectable`    | Boolean  | `false`         | Enable row selection                               |
+| `expandable`    | Boolean  | `false`         | Enable row expansion                               |
+| `pagination`    | Boolean  | `false`         | Enable pagination                                  |
+| `pageSize`      | Number   | `10`            | Items per page when pagination is enabled          |
+| `onRowClick`    | Function | -               | Row click handler                                  |
+| `onCellClick`   | Function | -               | Cell click handler                                 |
+
+## Column Definition
+
+```typescript
+interface ColumnDefinition {
+  field: string; // The field name in the data object
+  headerName: string; // The display name for the column header
+  width?: number; // The width of the column in pixels (default: 100)
+  sortable?: boolean; // Whether the column is sortable (default: true)
+  filterable?: boolean; // Whether the column is filterable (default: true)
+  resizable?: boolean; // Whether the column can be resized (default: true)
+  cellRenderer?: Function; // Custom cell renderer function
+  headerRenderer?: Function; // Custom header renderer function
+  align?: "left" | "center" | "right"; // Text alignment (default: 'left')
+  pinned?: boolean | "left"; // Whether the column is pinned (true = right, 'left' = left)
+  hidden?: boolean; // Whether the column is initially hidden
+  children?: ColumnDefinition[]; // Child columns for grouping headers
+}
+```
+
+## Project Setup
+
+This project was bootstrapped with [Create React App](https://github.com/facebook/create-react-app).
+
+### Available Scripts
+
+In the project directory, you can run:
+
+#### `npm start`
+
+Runs the app in the development mode.\
+Open [http://localhost:3000](http://localhost:3000) to view it in your browser.
+
+#### `npm test`
+
+Launches the test runner in the interactive watch mode.
+
+#### `npm run build`
+
+Builds the app for production to the `build` folder.
+
+# Advanced Data Caching System for React Tables
+
+A high-performance caching system for handling extremely large datasets (50M+ rows) in React applications with support for both pagination and infinite scrolling patterns.
+
+## Core Components
+
+- **InfiniteCache**: Block-based cache management with multiple purge strategies
+- **InfiniteRowModel**: Virtual row model to efficiently handle rows and viewport
+- **InfiniteDataSource**: Data provider with client-side and server-side implementations
+- **InfiniteBlock**: Data block for efficient memory management and cache operations
+- **StreamingDataAdapter**: Enables streaming large datasets in chunks
+- **LargeDataStorage**: Optimized storage for extremely large datasets
+- **LargeDataSourceAdapter**: Adapter for connecting large storage to data sources
+- **Web Workers**: Background processing for heavy operations
+  - `worker.js`: Standard worker for data processing
+  - `enhanced-worker.js`: WebAssembly-enhanced worker for extreme performance
+
+## Key Features
+
+- **Virtual Rendering**: Only renders visible rows with intelligent row recycling
+- **Block-Based Caching**: Stores data in blocks for efficient memory use
+- **Multiple Purge Strategies**:
+  - LRU (Least Recently Used)
+  - Furthest From Viewport
+  - Memory Optimized
+- **Persistence Options**: Save cache state between sessions
+- **Automatic Memory Management**: Monitors and optimizes memory usage
+- **Extreme Dataset Optimizations**:
+  - Web Worker offloading
+  - IndexedDB integration
+  - Binary data format
+  - Streaming data loading
+  - WebAssembly acceleration
+
+## Performance Characteristics
+
+- **Dataset Size**: Efficiently handles 50M+ rows
+- **Memory Usage**: Optimized for low memory footprint
+- **Rendering Performance**: Maintains 60fps scrolling
+- **Initial Load Time**: Fast initial loading with progressive enhancements
+- **Server-Side Operations**: Optimized for REST/GraphQL pagination
+
+## Usage
+
+The system can be used via the `useInfiniteCache` hook:
+
+```jsx
+const { visibleData, getRows, setVisibleRange, refreshCache, analytics } =
+  useInfiniteCache(data, {
+    threshold: 1000,
+    blockSize: 100,
+    maxBlocksInCache: 10,
+    enableEnhancedWorker: true,
+  });
+```
+
+Perfect for:
+
+- Data grids/tables
+- Virtual lists
+- Infinite scrolling feeds
+- Paginated data displays
+
+## Advanced Configuration
+
+- **Block Size**: Configure memory/performance tradeoff
+- **Cache Size**: Adjust total blocks kept in memory
+- **Worker Options**: Enable/disable WebAssembly optimization
+- **Storage Options**: Configure persistence and compression
+- **Streaming Options**: Fine-tune loading behavior
+- **IndexedDB Integration**: Offload memory pressure for extreme datasets
+
+## Industry Compatibility
+
+Implements the same caching architecture as AG Grid Enterprise (v27), ensuring familiar patterns and optimal performance for massive datasets.