@pulog/component 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,816 @@
-# Temporary Holding Version
+# @pulog/component
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The shared **business components** for TMS apps. Everything is imported from one place:
+`import { DataTable, ... } from '@pulog/component'`. Each component family lives in its own folder under `src/` and is
+re-exported from `src/index.ts`; adding one (e.g. shipment/order cards) is described in `docs/CONTRIBUTING.md`.
+
+Currently available: **DataTable** (this document). Primitives stay in `@pulog/ui`.
+
+---
+
+## DataTable
+
+The shared DataTable component family: `DataTable`, its contexts (filter / pagination /
+selection / sort / column visibility / column pinning), filters, pagination, selection helpers,
+query-building utilities (`buildQueryParams`, `applyFilters`, ...) and the default English strings.
+
+Extracted from `tms_billing` (the pilot). Source of truth is **this package** - never copy it into an app.
+
+## Install
+
+```bash
+npm install @pulog/component @pulog/ui @pulog/utils
+```
+
+Peer dependencies (the app already has them; the package never bundles them):
+`react`, `react-dom`, `lucide-react`, `date-fns`, `react-day-picker`, `framer-motion`, `react-i18next`.
+`@pulog/ui` and `@pulog/utils` are regular dependencies of this package, but install them in the app too
+when you import from them directly.
+
+## App setup (once per app)
+
+1. **Tailwind must scan the package.** The package ships compiled JS without CSS, so add to the app's
+   `src/index.css` (path relative to that file):
+   ```css
+   @source "../node_modules/@pulog";
+   ```
+2. **Translations.** Components call `useTranslation('datatable')`. Register the defaults:
+   ```ts
+   import { datatableEn, DATATABLE_NS } from '@pulog/component'
+   // add `datatable: datatableEn` to your i18n resources and keep 'datatable' in `ns`
+   ```
+   Override any key by merging your own object over `datatableEn`.
+3. **Portals / Shadow DOM.** Popovers, selects and dropdowns inside the table render through
+   `PortalContainerContext` from `@pulog/ui`. The app must provide that context at its Shadow DOM root
+   (see `tms_host/REMOTE_STYLE_GUIDE.md`) and must import the context from `@pulog/ui` (or a re-export of it),
+   never define its own - two contexts means portals escape the shadow tree.
+
+## Exports
+
+- Components: `DataTable`, `DataTableProvider`, `SearchFilter`, `DateFilter`, `DateRangeFilter`, `SelectFilter`,
+  `MultiSelectFilter`, `CheckboxFilter`, `RangeFilter`, `FilterPanel`, `ColumnHeaderFilter`, `DateTreeFilter`,
+  `TraditionalPagination`, `InfiniteScrollPagination`, `RowCheckbox`, `SelectAllCheckbox`, `ExpandableRow`,
+  `SelectionSummary`, `ColumnPinMenu`, `ColumnVisibilityPanel`.
+- Context providers/hooks: `FilterProvider/useFilters`, `PaginationProvider/usePagination`,
+  `SelectionProvider/useSelection`, `SortProvider/useSort`, `ColumnVisibilityProvider/useColumnVisibility`,
+  `ColumnPinningProvider/useColumnPinning`.
+- Types: `DataTableProps`, `DataTableColumn`, `DataTableState` (table level, used by `onStateChange`),
+  `DataTableQueryState` (generic query-state shape; this is `DataTableState<T>` from the old `lib/data-table/types`),
+  `FilterValue`, `FilterType`, `ColumnFilter`, `SortState`, `PaginationMeta`, `RowSelectionState`, ...
+- Utilities: everything in `src/lib` (`buildQueryParams`, `paramsToURLSearchParams`, `buildURL`, `applyFilters`,
+  `removeFilter`, `hasActiveFilters`, `formatDateKey`, `parseDateValue`, ...).
+- i18n: `datatableEn`, `DATATABLE_NS`.
+
+`mock-data` (sample users for demos) is intentionally **not** shipped.
+
+## Changing this package
+
+See the repo-level `docs/CONTRIBUTING.md`. Source: `src/`. Tests: `npm test -w @pulog/component`.
+Known issue: `src/DataTable.test.tsx` is inherited from tms_billing, stale (32 failing cases) and excluded in
+`vitest.config.ts` until it is rewritten.
+
+---
+
+# Component guide (carried over from tms_billing)
+
+Imports below use the package name. Everything else is unchanged from the original guide.
+
+# Feature-Rich DataTable Component
+
+A comprehensive, production-ready DataTable component built with React 18, TypeScript, and shadcn/ui. Includes advanced filtering, sorting, selection, pagination, and expandable rows.
+
+## Features
+
+### Filtering System (7 Filter Types)
+- **Search Filter**: Full-text search across fields
+- **Date Filter**: Single date selection
+- **Date Range Filter**: Date range filtering
+- **Select Filter**: Single-select dropdown
+- **Multi-Select Filter**: Multiple selection with badges
+- **Checkbox Filter**: Boolean toggle filtering
+- **Range Filter**: Numeric range slider
+
+### Selection & Expansion
+- Row checkboxes with individual selection
+- Select all / deselect all functionality
+- Selection summary with action buttons
+- Expandable rows with custom content renderer
+- Bulk action support for selected rows
+
+### Pagination
+- **Traditional Mode**: Page navigation with first/last/prev/next buttons
+- **Infinite Scroll Mode**: Load More button for infinite scrolling
+- Configurable page sizes (10, 25, 50, 100)
+- Total items and current range display
+
+### Sorting
+- Multi-column sortable headers
+- Ascending/Descending/None toggle
+- Visual sort indicators
+- Server-side ready query building
+
+### Additional Features
+- Top-level optional search bar
+- Scrollable table area with configurable fixed height
+- Sticky table header
+- Sticky columns on the left with automatic offset stacking
+- Column pinning — pin/unpin left or right at runtime via a per-header menu (in addition to a column's static `sticky` config)
+- Column visibility toggle
+- Loading skeleton states
+- Error state handling
+- Empty state message
+- Responsive design
+- Client & server-side ready architecture
+- React Context for state management (no external state library)
+
+## Installation & Setup
+
+### 1. Basic Setup
+
+`<DataTable>` is self-contained — it owns its filter/pagination/selection/sort/
+column-visibility state internally, so there's no separate provider to render.
+Just pass props:
+
+```tsx
+'use client';
+
+import { DataTable } from '@pulog/component';
+
+export default function MyPage() {
+  return (
+    <DataTable
+      columns={columns}
+      data={data}
+      rowKey="id"
+      pageSize={10}                 // initial rows-per-page
+      selectionMode="checkbox"      // or "radio" — only needed with showSelection
+      defaultColumnVisibility={{}}  // initial per-column visibility
+    />
+  );
+}
+```
+
+`DataTableProvider` still exists (`./contexts/DataTableProvider`) but is an
+internal implementation detail of `<DataTable>` — page code should never need
+to render it directly.
+
+**Escape hatch:** the one legitimate reason to render `DataTableProvider`
+yourself is when a *sibling* component (rendered next to `<DataTable>`, not
+passed into it via `toolbarLeft`/`toolbarRight`) needs to read the table's
+selection/filter state — e.g. a "Process selected" button above the table
+that calls `useSelection()`. Wrap both in one explicit `<DataTableProvider>`;
+`<DataTable>` detects that ambient provider and reuses it instead of creating
+a disconnected one of its own:
+
+```tsx
+function ProcessSelectedButton() {
+  const { selectedCount, getSelectedRowIds } = useSelection(); // shares state with the table below
+  return <Button disabled={!selectedCount}>Process {selectedCount}</Button>;
+}
+
+<DataTableProvider defaultPageSize={10}>
+  <ProcessSelectedButton />
+  <DataTable columns={columns} data={data} rowKey="id" pageSize={10} />
+</DataTableProvider>
+```
+
+Keep `defaultPageSize` (and `selectionMode` / `defaultColumnVisibility` if
+used) on the outer `DataTableProvider` in sync with what you'd otherwise pass
+to `<DataTable>` — with an ambient provider present, `<DataTable>`'s own
+`pageSize`/`selectionMode`/`defaultColumnVisibility` props are ignored (the
+ambient provider already owns that state).
+
+A nested `<DataTable>` that must stay **isolated** from an outer table (e.g.
+a detail table inside an expanded row, with its own independent pagination)
+should keep its own explicit `<DataTableProvider>` wrapper too — nesting a
+provider always shadows the ambient one for its own subtree, giving it a
+fresh, separate state scope.
+
+### 2. Define Column Configuration
+
+```tsx
+import { DataTableColumn } from '@pulog/component';
+
+interface User {
+  id: number;
+  name: string;
+  email: string;
+  role: string;
+}
+
+const columns: DataTableColumn<User>[] = [
+  {
+    id: 'name',
+    header: 'Name',
+    accessor: 'name',
+    sortable: true,
+    filterable: true,
+    sticky: 'left', // or `right`, or `true` for left
+    filterConfig: {
+      id: 'name',
+      label: 'Search Name',
+      type: 'search',
+      placeholder: 'Enter name...',
+    },
+  },
+  {
+    id: 'email',
+    header: 'Email',
+    accessor: 'email',
+    sortable: true,
+  },
+  {
+    id: 'role',
+    header: 'Role',
+    accessor: 'role',
+    sortable: true,
+    filterable: true,
+    filterConfig: {
+      id: 'role',
+      label: 'Select Role',
+      type: 'multiSelect',
+      options: [
+        { label: 'Admin', value: 'admin' },
+        { label: 'User', value: 'user' },
+      ],
+    },
+  },
+];
+```
+
+Sticky columns can be added to multiple visible columns. The table measures each sticky column at runtime and stacks their offsets so they do not overlap.
+Use `sticky: 'left'` or `sticky: 'right'` to pin columns on either side by default.
+
+### Runtime Column Pinning
+
+Each header cell (except tool columns) shows a pin icon that opens a menu with "Pin ke Kiri" / "Pin ke Kanan" / "Lepas Pin" — this lets users pin/unpin any column at runtime, overriding its static `sticky` config for that session. Pinned columns are automatically reordered to the corresponding edge (left-pinned first, then unpinned, then right-pinned), each group keeping its own relative order.
+
+- Disable the menu for the whole table: `enableColumnPinning={false}`
+- Disable it for one column: `pinnable: false` on that column
+- Seed initial runtime pin state: `defaultColumnPinning={{ mst_client_id: 'left' }}` (falls back to each column's `sticky` for ids left unset)
+
+### 3. Render DataTable
+
+```tsx
+<DataTable<User>
+  columns={columns}
+  data={users}
+  rowKey="id"
+  showSelection={true}
+  showExpand={true}
+  expandContent={(row) => <div>Details for {row.name}</div>}
+  paginationMode="traditional"
+  showFilters={true}
+  showSearch={true}
+  searchFields={['name', 'email']} // optional, defaults to all columns
+  tableHeight={600}
+  pageSize={10}
+/>
+```
+
+## Usage Examples
+
+### Server-Side Integration
+
+Enable server-side mode by setting the `manual*` props:
+
+```tsx
+<DataTable
+  columns={columns}
+  data={data}
+  rowKey="id"
+  manualPagination
+  manualFiltering
+  manualSorting
+  totalCount={65}
+  onStateChange={handleStateChange}
+/>
+```
+
+#### Using `onStateChange` Callback
+
+The recommended approach — `onStateChange` fires whenever pagination, filter, sort, or search state changes:
+
+```tsx
+const [data, setData] = useState([]);
+const [isLoading, setIsLoading] = useState(false);
+const [totalCount, setTotalCount] = useState(0);
+
+const handleStateChange = useCallback(async (state: DataTableState) => {
+  setIsLoading(true);
+  try {
+    const params = buildQueryParams(
+      state.pageIndex,
+      state.pageSize,
+      state.filters,
+      state.sort,
+      undefined,
+      state.search
+    );
+    const response = await fetch(`/api/data?${paramsToURLSearchParams(params)}`);
+    const result = await response.json();
+    setData(result.data);
+    setTotalCount(result.meta.pagination.totalData);
+  } finally {
+    setIsLoading(false);
+  }
+}, []);
+
+<DataTable
+  columns={columns}
+  data={data}
+  isLoading={isLoading}
+  rowKey="id"
+  manualPagination
+  manualFiltering
+  manualSorting
+  totalCount={totalCount}
+  onStateChange={handleStateChange}
+/>
+```
+
+#### Reading Table State From a Custom Toolbar Element
+
+`useFilters` / `usePagination` / `useSort` / `useSelection` / `useColumnVisibility`
+only work inside `<DataTable>`'s own subtree, since the table creates its own
+context instance internally — a sibling component sitting next to `<DataTable>`
+in JSX can't reach it. Fetching data for the table itself should use
+`onStateChange` (above), not these hooks directly.
+
+The one place these hooks are legitimately useful is a **custom toolbar
+element** passed via `toolbarLeft` / `toolbarRight` — that content is rendered
+inside `<DataTable>`'s own tree, so it shares the same context:
+
+```tsx
+function ActiveDateRangeBadge() {
+  // Works: this component is rendered *inside* <DataTable> via toolbarLeft.
+  const { filters, removeFilter } = useFilters();
+  const active = filters.find((f) => f.field === 'tanggal_valid');
+  if (!active) return null;
+  return <Badge onClick={() => removeFilter('tanggal_valid')}>Tanggal aktif ✕</Badge>;
+}
+
+<DataTable
+  columns={columns}
+  data={data}
+  rowKey="id"
+  toolbarLeft={<ActiveDateRangeBadge />}
+/>
+```
+
+### Custom Cell Rendering
+
+```tsx
+const columns: DataTableColumn<User>[] = [
+  {
+    id: 'status',
+    header: 'Status',
+    accessor: 'status',
+    cell: (row) => (
+      <Badge variant={row.status === 'active' ? 'default' : 'secondary'}>
+        {row.status}
+      </Badge>
+    ),
+  },
+];
+```
+
+### Expandable Rows with Details
+
+```tsx
+<DataTable
+  columns={columns}
+  data={data}
+  rowKey="id"
+  showExpand={true}
+  expandContent={(row) => (
+    <div className="space-y-4">
+      <div className="grid grid-cols-2 gap-4">
+        <div>
+          <p className="text-xs text-muted-foreground">Email</p>
+          <p className="font-medium">{row.email}</p>
+        </div>
+        <div>
+          <p className="text-xs text-muted-foreground">Phone</p>
+          <p className="font-medium">{row.phone}</p>
+        </div>
+      </div>
+      <p>{row.description}</p>
+    </div>
+  )}
+/>
+```
+
+### Row Selection with Bulk Actions
+
+```tsx
+import { useSelection } from '@pulog/component';
+
+function DataTableWithActions() {
+  const { getSelectedRowIds } = useSelection();
+
+  const handleBulkDelete = async () => {
+    const selectedIds = getSelectedRowIds();
+    await fetch('/api/users/bulk-delete', {
+      method: 'POST',
+      body: JSON.stringify({ ids: selectedIds }),
+    });
+  };
+
+  return (
+    <>
+      <DataTable
+        columns={columns}
+        data={data}
+        rowKey="id"
+        showSelection={true}
+      />
+      <SelectionSummary
+        actionLabel="Delete Selected"
+        onAction={handleBulkDelete}
+      />
+    </>
+  );
+}
+```
+
+## API Integration Reference
+
+### onStateChange Callback Payload
+
+When any table state changes, `onStateChange` fires with this structure:
+
+```json
+{
+  "pageIndex": 2,
+  "pageSize": 10,
+  "sort": {
+    "column": "name",
+    "order": "asc"
+  },
+  "filters": [
+    { "field": "status", "type": "select", "operator": "equals", "value": "active" },
+    { "field": "salary", "type": "range", "operator": "between", "value": [50000, 100000] }
+  ],
+  "search": {
+    "query": "john",
+    "fields": ["name", "email"]
+  }
+}
+```
+
+### buildQueryParams Output
+
+Use `buildQueryParams()` to convert state into API-friendly query parameters:
+
+```ts
+import { buildQueryParams, paramsToURLSearchParams } from '@pulog/component';
+
+const params = buildQueryParams(pageIndex, pageSize, filters, sort, additionalParams, search);
+const urlParams = paramsToURLSearchParams(params);
+// Use: fetch(`/api/data?${urlParams}`)
+```
+
+#### GET Request — Query Parameters
+
+```
+GET /api/data?pageIndex=2&pageSize=10&sortBy=name&sortOrder=asc&search=john&searchFields=name&searchFields=email&filters[status]=active&filters[salary][min]=50000&filters[salary][max]=100000
+```
+
+Full parameter reference:
+
+| Parameter | Type | Example | Description |
+|---|---|---|---|
+| `pageIndex` | number | `2` | Current page (1-indexed) |
+| `pageSize` | number | `10` | Items per page |
+| `sortBy` | string | `name` | Sort column ID |
+| `sortOrder` | string | `asc` | Sort direction: `asc` or `desc` |
+| `search` | string | `john` | Global search query |
+| `searchFields` | string[] | `name,email` | Fields to search in |
+| `filters[field]` | any | `active` | Simple filter value |
+| `filters[field][min]` | number | `50000` | Range filter min |
+| `filters[field][max]` | number | `100000` | Range filter max |
+| `filters[field][from]` | string | `2024-01-01` | Date range start |
+| `filters[field][to]` | string | `2024-12-31` | Date range end |
+| `filters[field][]` | string[] | `admin,user` | Multi-select values |
+
+#### POST Request — JSON Body
+
+```json
+POST /api/data
+Content-Type: application/json
+
+{
+  "pageIndex": 2,
+  "pageSize": 10,
+  "sortBy": "name",
+  "sortOrder": "asc",
+  "search": "john",
+  "searchFields": ["name", "email"],
+  "filters": {
+    "status": "active",
+    "role": ["admin", "user"],
+    "salary": { "min": 50000, "max": 100000 },
+    "joinDate": { "from": "2024-01-01", "to": "2024-12-31" },
+    "isVerified": true
+  }
+}
+```
+
+### Filter Types → API Format
+
+| Filter Type | Value Type | GET Example | POST Example |
+|---|---|---|---|
+| `search` | string | `filters[name]=john` | `"name": "john"` |
+| `date` | string | `filters[date]=2024-06-15` | `"date": "2024-06-15"` |
+| `dateRange` | [from, to] | `filters[dob][from]=2024-01-01&filters[dob][to]=2024-12-31` | `"dob": { "from": "2024-01-01", "to": "2024-12-31" }` |
+| `select` | string | `filters[status]=active` | `"status": "active"` |
+| `multiSelect` | string[] | `filters[role][]=admin&filters[role][]=user` | `"role": ["admin", "user"]` |
+| `checkbox` | boolean | `filters[verified]=true` | `"verified": true` |
+| `range` | [min, max] | `filters[salary][min]=50000&filters[salary][max]=100000` | `"salary": { "min": 50000, "max": 100000 }` |
+
+### API Response Format
+
+The DataTable expects API responses in this format:
+
+```json
+{
+  "status": 200,
+  "success": true,
+  "message": "success",
+  "data": [
+    { "id": 1, "name": "User 1", "email": "user1@example.com", "role": "admin" },
+    { "id": 2, "name": "User 2", "email": "user2@example.com", "role": "user" }
+  ],
+  "meta": {
+    "pagination": {
+      "pageIndex": 2,
+      "pageSize": 10,
+      "pageCount": 7,
+      "totalData": 65
+    }
+  }
+}
+```
+
+#### Response Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `status` | number | Yes | HTTP status code |
+| `success` | boolean | Yes | Request success flag |
+| `message` | string | Yes | Response message |
+| `data` | array | Yes | Array of row objects |
+| `meta.pagination.pageIndex` | number | Yes | Current page (must match request) |
+| `meta.pagination.pageSize` | number | Yes | Items per page |
+| `meta.pagination.pageCount` | number | Yes | Total number of pages |
+| `meta.pagination.totalData` | number | Yes | Total number of records (across all pages) |
+
+### Server-Side Behavior Summary
+
+| Feature | Props Required | Behavior |
+|---|---|---|
+| Server pagination | `manualPagination` + `totalCount` | Data not sliced client-side; page count from `totalCount` |
+| Server filtering | `manualFiltering` | Client search/filter skipped; filters sent via `onStateChange` |
+| Server sorting | `manualSorting` | Client sort skipped; sort sent via `onStateChange` |
+| Page reset on filter | `manualFiltering` + `manualPagination` | Auto-reset to page 1 when filters/search/sort change |
+
+## Hooks API
+
+### useFilters()
+```tsx
+const {
+  filters,           // Current filter array
+  addFilter,         // Add a filter
+  updateFilter,      // Update existing filter
+  removeFilter,      // Remove filter
+  clearFilters,      // Clear all filters
+  clearFieldFilters, // Clear filters for specific fields
+  hasActiveFilters,  // Check if any filters active
+  getFieldFilters,   // Get filters for specific field
+} = useFilters();
+```
+
+### usePagination()
+```tsx
+const {
+  pageIndex,          // Current page (1-indexed)
+  pageSize,           // Items per page
+  pageCount,          // Total pages
+  totalData,          // Total items count
+  paginationMode,     // 'traditional' | 'infinite'
+  goToPage,           // Jump to specific page
+  nextPage,           // Go to next page
+  previousPage,       // Go to previous page
+  setPageSize,        // Change page size
+  updatePaginationMeta, // Update all pagination data
+  setPaginationMode,  // Switch pagination mode
+  canGoNext,          // Can go to next?
+  canGoPrevious,      // Can go to previous?
+} = usePagination();
+```
+
+### useSelection()
+```tsx
+const {
+  rowSelection,      // Selected rows object
+  expandedRows,      // Expanded rows object
+  toggleRow,         // Toggle row selection
+  toggleAll,         // Toggle all rows
+  selectRows,        // Select multiple rows
+  deselectRows,      // Deselect multiple rows
+  clearSelection,    // Clear all selections
+  isRowSelected,     // Check if row selected
+  selectedCount,     // Count of selected rows
+  toggleExpanded,    // Toggle row expansion
+  isRowExpanded,     // Check if row expanded
+  expandedCount,     // Count of expanded rows
+  getSelectedRowIds, // Get array of selected IDs
+} = useSelection();
+```
+
+### useSort()
+```tsx
+const {
+  sort,              // { column: string | null, order: 'asc' | 'desc' | null }
+  setSort,           // Set sort column and order
+  toggleSort,        // Cycle sort: asc -> desc -> none
+  clearSort,         // Clear sorting
+  isSorted,          // Check if column sorted
+  getSortOrder,      // Get sort order for column
+} = useSort();
+```
+
+### useColumnVisibility()
+```tsx
+const {
+  visibility,        // Visibility state object
+  toggleColumn,      // Toggle column visibility
+  showColumn,        // Show column
+  hideColumn,        // Hide column
+  isColumnVisible,   // Check if visible
+  showAllColumns,    // Show all columns
+  hideAllColumns,    // Hide all columns
+  setVisibility,     // Set all visibility
+} = useColumnVisibility();
+```
+
+## Filter Types Configuration
+
+### Search Filter
+```tsx
+{
+  id: 'name',
+  label: 'Search Name',
+  type: 'search',
+  placeholder: 'Enter name...',
+}
+```
+
+### Date Filter
+```tsx
+{
+  id: 'createdAt',
+  label: 'Created Date',
+  type: 'date',
+}
+```
+
+### Date Range Filter
+```tsx
+{
+  id: 'dateRange',
+  label: 'Date Range',
+  type: 'dateRange',
+}
+```
+
+### Select Filter
+```tsx
+{
+  id: 'status',
+  label: 'Status',
+  type: 'select',
+  options: [
+    { label: 'Active', value: 'active' },
+    { label: 'Inactive', value: 'inactive' },
+  ],
+  placeholder: 'Select status...',
+}
+```
+
+### Multi-Select Filter
+```tsx
+{
+  id: 'roles',
+  label: 'Roles',
+  type: 'multiSelect',
+  options: [
+    { label: 'Admin', value: 'admin' },
+    { label: 'User', value: 'user' },
+  ],
+  placeholder: 'Select roles...',
+}
+```
+
+### Checkbox Filter
+```tsx
+{
+  id: 'isVerified',
+  label: 'Is Verified',
+  type: 'checkbox',
+}
+```
+
+### Range Filter
+```tsx
+{
+  id: 'salary',
+  label: 'Salary Range',
+  type: 'range',
+  minValue: 0,
+  maxValue: 1000000,
+}
+```
+
+## DataTable Props
+
+```tsx
+interface DataTableProps<T> {
+  // Required
+  columns: DataTableColumn<T>[];
+  data: T[];
+  rowKey: keyof T;
+
+  // Display
+  isLoading?: boolean;
+  error?: string | null;
+  onRowClick?: (row: T) => void;
+  emptyStateMessage?: string;
+
+  // Selection & Expand
+  showSelection?: boolean;
+  showExpand?: boolean;
+  stickySelection?: boolean;
+  stickyExpand?: boolean;
+  showRowNumber?: boolean;
+  stickyRowNumber?: boolean;
+  expandContent?: (row: T) => React.ReactNode;
+
+  // Pagination
+  paginationMode?: 'traditional' | 'infinite';
+  pageSize?: number;
+  pageSizeOptions?: number[];
+  tableHeight?: string | number;
+  infiniteScrollHeight?: string | number;
+
+  // Search & Filter
+  showFilters?: boolean;
+  showSearch?: boolean;
+  searchFields?: string[];
+  searchPlaceholder?: string;
+
+  // Server-side
+  manualPagination?: boolean;  // Enable server-side pagination
+  manualSorting?: boolean;     // Enable server-side sorting
+  manualFiltering?: boolean;   // Enable server-side filtering
+  totalCount?: number;         // Required when manualPagination=true
+  onStateChange?: (state: DataTableState) => void;  // Fires on any state change
+}
+```
+
+## Styling & Customization
+
+The DataTable uses Tailwind CSS classes and shadcn/ui components. Customize by:
+
+1. **Modifying component styles** - Edit the component files directly
+2. **Using Tailwind config** - Customize via `tailwind.config.ts`
+3. **Custom cell rendering** - Use the `cell` prop in column config
+4. **Custom header rendering** - Use `header` prop with JSX
+
+## Performance Considerations
+
+- **Virtual scrolling**: Consider for tables with 1000+ rows
+- **Pagination**: Use traditional or infinite scroll based on UX needs
+- **Client vs Server filtering**: Choose based on dataset size
+- **Memoization**: Use `React.memo` for expensive cell renders
+- **Key prop**: Always use a stable unique `rowKey`
+
+## Accessibility
+
+- Fully keyboard navigable (arrow keys, tab, enter)
+- ARIA labels on all interactive elements
+- Semantic HTML structure
+- Screen reader friendly
+- High contrast support
+
+## Browser Support
+
+- Chrome/Edge (latest 2 versions)
+- Firefox (latest 2 versions)
+- Safari (latest 2 versions)
+- Mobile browsers (iOS Safari, Chrome Mobile)
+
+## Demo
+
+Visit `/data-table-demo` to see all features in action!