lite-table-js-v2 1.0.1

package/README.md

@@ -0,0 +1,205 @@
+# lite-table-js
+
+A high-performance, feature-rich React data table component library inspired by AG Grid and MUI DataGrid.
+
+## Features
+
+- **Dynamic column configuration** with custom renderers
+- **Sorting** — single and multi-column
+- **Filtering** — column-level (text, number, select, date) and global search
+- **Pagination** — client-side and server-side
+- **Row selection** — single, multiple, select-all with indeterminate state
+- **Inline editing** — double-click to edit, custom editors
+- **Column resizing** — drag column borders
+- **Column reordering** — drag-and-drop headers
+- **Virtual scrolling** — render thousands of rows efficiently
+- **Theming** — CSS custom properties for full style control
+- **Row expansion** — expandable detail rows
+- **CSV export** — one-click data export
+- **Footer aggregation** — column footers with custom renderers
+- **Status bar** — row count, selection count, active filters
+- **TypeScript** — full type definitions
+- **Tree-shakeable** — modular hooks + components
+
+## Installation
+
+```bash
+npm install lite-table-js
+```
+
+## Quick Start
+
+```tsx
+import { DataTable, ColumnDef } from 'lite-table-js';
+import 'lite-table-js/dist/styles.css';
+
+interface User {
+  id: number;
+  name: string;
+  email: string;
+  age: number;
+}
+
+const columns: ColumnDef<User>[] = [
+  { id: 'name', header: 'Name', accessor: 'name', sortable: true },
+  { id: 'email', header: 'Email', accessor: 'email', sortable: true },
+  { id: 'age', header: 'Age', accessor: 'age', sortable: true, align: 'right' },
+];
+
+const data: User[] = [
+  { id: 1, name: 'Alice', email: 'alice@example.com', age: 30 },
+  { id: 2, name: 'Bob', email: 'bob@example.com', age: 25 },
+];
+
+function App() {
+  return (
+    <DataTable
+      columns={columns}
+      data={data}
+      rowKey="id"
+      sortable
+      filterable
+      paginated
+      selectionMode="multiple"
+    />
+  );
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `columns` | `ColumnDef<T>[]` | required | Column definitions |
+| `data` | `T[]` | required | Data rows |
+| `rowKey` | `keyof T \| (row: T) => string` | required | Unique row identifier |
+| `sortable` | `boolean` | `false` | Enable sorting |
+| `multiSort` | `boolean` | `false` | Enable multi-column sort |
+| `filterable` | `boolean` | `false` | Enable column filters |
+| `globalFilterEnabled` | `boolean` | `false` | Enable global search |
+| `paginated` | `boolean` | `false` | Enable pagination |
+| `pageSizeOptions` | `number[]` | `[10,25,50,100]` | Page size options |
+| `selectionMode` | `'none'\|'single'\|'multiple'` | `'none'` | Row selection mode |
+| `editable` | `boolean` | `false` | Enable inline editing |
+| `columnResizing` | `boolean` | `false` | Enable column resize |
+| `columnReordering` | `boolean` | `false` | Enable column reorder |
+| `virtualScrolling` | `boolean` | `false` | Enable virtual scroll |
+| `rowHeight` | `number` | `42` | Row height (px) |
+| `theme` | `DataTableTheme` | — | Theme overrides |
+| `striped` | `boolean` | `false` | Alternating row colors |
+| `dense` | `boolean` | `false` | Compact mode |
+| `bordered` | `boolean` | `true` | Show cell borders |
+| `loading` | `boolean` | `false` | Show loading overlay |
+| `exportable` | `boolean` | `false` | Show CSV export button |
+| `expandable` | `boolean` | `false` | Enable row expansion |
+| `showFooter` | `boolean` | `false` | Show footer row |
+| `showStatusBar` | `boolean` | `false` | Show status bar |
+
+## Column Definition
+
+```ts
+interface ColumnDef<T> {
+  id: string;                    // Unique column ID
+  header: string | ReactNode;   // Header content
+  accessor: keyof T | (row: T) => any;  // Data accessor
+  cell?: (value, row, index) => ReactNode;  // Custom cell renderer
+  width?: number;                // Column width
+  minWidth?: number;             // Min width for resize
+  maxWidth?: number;             // Max width for resize
+  sortable?: boolean;            // Enable sorting
+  filterable?: boolean;          // Enable filtering
+  editable?: boolean;            // Enable inline edit
+  resizable?: boolean;           // Enable resize
+  align?: 'left' | 'center' | 'right';
+  filterType?: 'text' | 'number' | 'select' | 'date';
+  filterOptions?: { label: string; value: any }[];
+  footer?: string | (rows: T[]) => ReactNode;
+  pinned?: 'left' | 'right' | false;
+}
+```
+
+## Custom Cell Renderer
+
+```tsx
+const columns: ColumnDef<User>[] = [
+  {
+    id: 'status',
+    header: 'Status',
+    accessor: 'status',
+    cell: (value) => (
+      <span style={{ color: value === 'Active' ? 'green' : 'red' }}>
+        {value}
+      </span>
+    ),
+  },
+];
+```
+
+## Server-Side Data
+
+```tsx
+<DataTable
+  columns={columns}
+  data={[]}
+  rowKey="id"
+  serverSide={{
+    getRows: async ({ page, pageSize, sortModel, filterModel }) => {
+      const res = await fetch(`/api/users?page=${page}&size=${pageSize}`);
+      const json = await res.json();
+      return { rows: json.data, totalRows: json.total };
+    },
+  }}
+  paginated
+  sortable
+/>
+```
+
+## Theming
+
+```tsx
+<DataTable
+  theme={{
+    primaryColor: '#6366f1',
+    headerBg: '#1e1b4b',
+    headerColor: '#e0e7ff',
+    rowHoverBg: '#eef2ff',
+    borderRadius: '8px',
+  }}
+  // ...
+/>
+```
+
+## Using Hooks Independently
+
+All hooks are exported for custom table implementations:
+
+```tsx
+import { useSort, useFilter, usePagination, useSelection } from 'lite-table-js';
+
+function CustomTable({ data, columns }) {
+  const { sortedData, toggleSort } = useSort({ columns, data });
+  const { filteredData, setColumnFilter } = useFilter({ columns, data: sortedData });
+  const { paginatedData, pagination } = usePagination({ data: filteredData });
+  // Build your own UI...
+}
+```
+
+## Scripts
+
+```bash
+npm run build        # Build the package
+npm run test         # Run tests
+npm run storybook    # Launch Storybook
+npm run build-storybook  # Build Storybook
+```
+
+## Build & Publish
+
+```bash
+npm run build
+npm publish
+```
+
+## License
+
+MIT