@jmruthers/pace-core 0.2.4

package/docs/implementation-guides/data-tables.md

@@ -0,0 +1,1898 @@
+# Data Tables
+
+This guide covers implementing data tables with PACE Core's DataTable component, including basic usage, advanced features, and best practices.
+
+## Overview
+
+The PACE Core DataTable is an enterprise-grade data table component built on TanStack Table that provides:
+
+- **🚀 Performance Optimized** - Virtual scrolling, intelligent chunking, and automatic mode detection
+- **📊 Data Management** - Sorting, filtering, pagination, search, export/import
+- **🌳 Hierarchical Rows** - Parent/child row relationships with expand/collapse all and smart sorting ([Detailed Guide](./hierarchical-datatable.md))
+- **✏️ Inline Editing** - Row editing, creation, and deletion
+- **🎯 Actions** - Custom row actions and toolbar buttons
+- **📈 Grouping** - Data grouping with aggregation functions
+- **📏 Auto Column Sizing** - Automatic column width adjustment based on content
+- **🎨 Customizable** - Column visibility, responsive design, accessibility
+- **🔧 TypeScript** - Full TypeScript support with strict typing
+
+## Basic Usage
+
+### Simple Data Table
+
+```tsx
+import { DataTable, type DataTableColumn } from '@jmruthers/pace-core';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: string;
+  status: 'active' | 'inactive';
+}
+
+const columns: DataTableColumn<User>[] = [
+  {
+    accessorKey: 'name',
+    header: 'Name',
+    sortable: true,
+    features: { search: true },
+  },
+  {
+    accessorKey: 'email',
+    header: 'Email',
+    sortable: true,
+    features: { search: true },
+  },
+  {
+    accessorKey: 'role',
+    header: 'Role',
+    sortable: true,
+    enableGrouping: true,
+  },
+  {
+    accessorKey: 'status',
+    header: 'Status',
+    sortable: true,
+    cell: ({ row }) => (
+      <span className={`px-2 py-1 rounded text-xs ${
+        row.original.status === 'active'
+          ? 'bg-main-100 text-main-800'
+          : 'bg-acc-100 text-acc-800'
+      }`}>
+        {row.original.status}
+      </span>
+    ),
+  },
+];
+
+const data: User[] = [
+  { id: '1', name: 'John Doe', email: 'john@example.com', role: 'Admin', status: 'active' },
+  { id: '2', name: 'Jane Smith', email: 'jane@example.com', role: 'User', status: 'active' },
+];
+
+function UserTable() {
+  return (
+    <DataTable
+      data={data}
+      columns={columns}
+      title="Users"
+      description="Manage your users"
+      features={{
+        search: true,
+        pagination: true,
+        sorting: true,
+        filtering: true,
+      }}
+      columnOrder={['name', 'email', 'role', 'status']} // Control column order
+      // Performance and other settings can be configured via performance prop
+    />
+  );
+}
+```
+
+### With Permission Enforcement
+
+```tsx
+import { DataTable, PagePermissionGuard, PAGE_IDS } from '@jmruthers/pace-core';
+
+function UsersPage() {
+  return (
+    <PagePermissionGuard pageId={PAGE_IDS.USER_MANAGEMENT}>
+      {(permissions) => (
+        <DataTable
+          data={users}
+          columns={columns}
+          title="User Management"
+          description="Manage system users"
+          features={{
+            search: true,
+            pagination: true,
+            creation: permissions.canCreate,
+            editing: permissions.canUpdate,
+            deletion: permissions.canDelete,
+          }}
+          onEditRow={permissions.canUpdate ? (row) => navigate(`/users/${row.id}/edit`) : undefined}
+          onDeleteRow={permissions.canDelete ? handleDeleteUser : undefined}
+          // Custom actions can be added via the deprecated actions prop
+          actions={
+            permissions.canUpdate || permissions.canDelete ? [
+              ...(permissions.canUpdate ? [{
+                label: 'View Details',
+                onClick: (row) => navigate(`/users/${row.id}`),
+              }] : [])
+            ] : []
+          }
+        />
+      )}
+    </PagePermissionGuard>
+  );
+}
+```
+
+## DataTable Props Interface
+
+The DataTable component has a comprehensive prop interface. Here are the key properties:
+
+### Core Props
+- `data: TData[]` - Array of data records to display
+- `columns: any[]` - Column definitions (supports TanStack Table format)
+- `features: DataTableFeatureConfig` - **Required** - Feature configuration object
+
+### Display Props
+- `title?: string` - Table title
+- `description?: string` - Table description  
+- `variant?: 'default' | 'compact' | 'spacious'` - Visual variant
+- `className?: string` - Additional CSS classes
+- `columnOrder?: string[]` - **Column ordering** - Array of column IDs in desired order
+
+### Event Handlers
+- `onEditRow?: (row: TData, data: Partial<TData>) => void` - Row edit handler
+- `onDeleteRow?: (row: TData) => void` - Row deletion handler (also used as fallback for bulk delete)
+- `onCreateRow?: (data: Partial<TData>) => void` - Row creation handler
+- `onImport?: (data: TData[]) => void | Promise<void>` - Import handler
+- `onRowSelectionChange?: (selection: Record<string, boolean>) => void` - Row selection change handler
+- `onDeleteSelected?: (selectedRows: Record<string, boolean>) => void` - **Bulk delete handler** - Called when delete selected button is clicked
+
+### Performance Props
+- `performance?: PerformanceConfig` - Performance optimization settings
+- `serverSide?: ServerSideConfig<TData>` - Server-side data fetching
+- `virtualHeight?: number` - Virtual scrolling height (default: 600)
+- `showPerformanceMetrics?: boolean` - Show performance metrics
+- `initialPageSize?: number` - Initial page size for pagination (default: 10)
+
+### Feature-Specific Configuration
+- `bulkOperationsConfig?: BulkOperationsConfig` - Bulk operations config
+
+### Row Actions
+- `actions?: any[]` - Custom row actions for each row
+
+## Feature Configuration
+
+The DataTable component uses a unified `features` prop to control all table functionality. This provides a consistent and intuitive way to enable or disable features.
+
+### DataTableFeatureConfig Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| **Core Features** |
+| `search` | `boolean` | `false` | Enable global search functionality |
+| `pagination` | `boolean` | `false` | Enable pagination controls |
+| `sorting` | `boolean` | `false` | Enable column sorting |
+| `filtering` | `boolean` | `false` | Enable column filtering |
+| **Data Management** |
+| `import` | `boolean` | `false` | Enable data import functionality |
+| `export` | `boolean` | `false` | Enable data export functionality |
+| **Row Operations** |
+| `selection` | `boolean` | `false` | Enable row selection for bulk operations |
+| `creation` | `boolean` | `false` | Enable row creation |
+| `editing` | `boolean` | `false` | Enable row editing |
+| `deletion` | `boolean` | `false` | Enable row deletion |
+| `deleteSelected` | `boolean` | `false` | Enable bulk deletion of selected rows |
+| **Table Customization** |
+| `grouping` | `boolean` | `false` | Enable data grouping |
+| `columnVisibility` | `boolean` | `false` | Enable column visibility controls |
+| `columnReordering` | `boolean` | `false` | Enable column reordering |
+| `autoColumnSizing` | `boolean` | `false` | Enable automatic column width adjustment based on content |
+
+### Basic Feature Configuration
+
+```tsx
+<DataTable
+  data={data}
+  columns={columns}
+  features={{
+    // Core Features
+    search: true,
+    pagination: true,
+    sorting: true,
+    filtering: true,
+    
+    // Data Management
+    import: true,
+    export: true,
+    
+    // Row Operations
+    selection: true,        // Required for row selection
+    creation: true,
+    editing: true,
+    deletion: true,         // Required for delete functionality
+    deleteSelected: true,   // Required for delete selected button
+    
+    // Table Customization
+    grouping: true,
+    columnVisibility: true,
+    columnReordering: true,
+    autoColumnSizing: true,  // Enable automatic column width adjustment
+  }}
+/>
+```
+
+### Minimal Configuration
+
+For a simple read-only table:
+
+```tsx
+<DataTable
+  data={data}
+  columns={columns}
+  features={{
+    search: true,
+    pagination: true,
+    sorting: true,
+  }}
+/>
+```
+
+### Advanced Configuration
+
+For a full-featured data management table:
+
+```tsx
+<DataTable
+  data={data}
+  columns={columns}
+  features={{
+    search: true,
+    pagination: true,
+    sorting: true,
+    filtering: true,
+    selection: true,
+    creation: true,
+    editing: true,
+    deletion: true,
+    deleteSelected: true,  // Enable delete selected functionality
+    export: true,
+    import: true,
+    grouping: true,
+    columnVisibility: true,
+    bulkOperations: true,
+  }}
+  columnOrder={['select', 'name', 'email', 'role', 'status', 'actions']} // Custom column order
+  onEditRow={handleEdit}
+  onDeleteRow={handleDelete}
+  onCreateRow={handleCreate}
+  onImport={handleImport}
+  onRowSelectionChange={handleSelectionChange}
+  onDeleteSelected={handleBulkDelete}
+  getRowId={(row) => row.id} // Important: Required for selection and delete operations
+/>
+```
+
+## Auto Column Sizing
+
+The DataTable component includes automatic column width adjustment based on content, which helps optimize space usage and improve readability.
+
+### How Auto-Sizing Works
+
+When `autoColumnSizing: true` is enabled:
+
+1. **Content Analysis**: Analyzes both header text and data content to determine optimal widths
+2. **Smart Calculation**: Uses character count estimation (8px per character + padding)
+3. **Constraints**: Respects min-width (80px) and max-width (400px) limits
+4. **Performance**: Only samples first 100 rows for large datasets
+5. **Table Layout**: Switches from `tableLayout: 'fixed'` to `tableLayout: 'auto'`
+
+### Benefits
+
+- **Better Space Utilization**: Columns automatically adjust to content width
+- **Improved Readability**: Long text gets more space, short text takes less space
+- **No Text Wrapping**: Prevents unnecessary text wrapping in narrow columns
+- **Consistent Layout**: Maintains proper spacing and alignment
+
+### Enabling Auto-Sizing
+
+```tsx
+<DataTable
+  data={data}
+  columns={columns}
+  features={{
+    search: true,
+    pagination: true,
+    sorting: true,
+    autoColumnSizing: true,  // Enable automatic column width adjustment
+  }}
+/>
+```
+
+### Auto-Sizing vs Fixed Widths
+
+**With Auto-Sizing (Recommended):**
+- Columns automatically adjust to content width
+- Long text gets more space, short text takes less space
+- Better space utilization
+- Improved readability
+
+**Without Auto-Sizing:**
+- All columns have equal width
+- Long text may wrap unnecessarily
+- Short columns have wasted space
+- Consistent but potentially inefficient layout
+
+### Example: Content-Based Sizing
+
+```tsx
+const data = [
+  { id: '1', name: 'John', description: 'A short description' },
+  { id: '2', name: 'Jane', description: 'A very long description that should make this column wider' },
+  { id: '3', name: 'Bob', description: 'Medium length description' }
+];
+
+const columns = [
+  { accessorKey: 'name', header: 'Name' },
+  { accessorKey: 'description', header: 'Description' }
+];
+
+// With auto-sizing: Description column will be wider than Name column
+<DataTable
+  data={data}
+  columns={columns}
+  features={{ autoColumnSizing: true }}
+/>
+```
+
+### Feature-Based Conditional Rendering
+
+When features are disabled, the corresponding UI elements are automatically hidden:
+
+```tsx
+// This will show only search and pagination controls
+// No edit, delete, or action buttons will appear
+<DataTable
+  data={data}
+  columns={columns}
+  features={{
+    search: true,
+    pagination: true,
+    // All other features disabled by default
+  }}
+/>
+```
+
+## Column Configuration
+
+### Basic Column Properties
+
+```tsx
+const columns: DataTableColumn<User>[] = [
+  {
+    accessorKey: 'name',        // Data field to access
+    header: 'Name',             // Column header
+    sortable: true,             // Enable sorting
+    features: { search: true },           // Enable search
+    enableGrouping: true,       // Enable grouping
+    size: 200,                  // Column width
+    minSize: 100,               // Minimum width
+    maxSize: 300,               // Maximum width
+  },
+];
+```
+
+### Custom Cell Rendering
+
+```tsx
+const columns: DataTableColumn<User>[] = [
+  {
+    accessorKey: 'avatar',
+    header: 'Avatar',
+    cell: ({ row }) => (
+      <Avatar>
+        <AvatarImage src={row.original.avatarUrl} />
+        <AvatarFallback>
+          {row.original.name.charAt(0).toUpperCase()}
+        </AvatarFallback>
+      </Avatar>
+    ),
+  },
+  {
+    accessorKey: 'status',
+    header: 'Status',
+    cell: ({ row }) => (
+      <Badge variant={row.original.status === 'active' ? 'default' : 'secondary'}>
+        {row.original.status}
+      </Badge>
+    ),
+  },
+  {
+    accessorKey: 'lastLogin',
+    header: 'Last Login',
+    cell: ({ row }) => (
+      <span className="text-sm text-muted-foreground">
+        {formatDate(row.original.lastLogin)}
+      </span>
+    ),
+  },
+];
+```
+
+### Advanced Column Features
+
+```tsx
+const columns: DataTableColumn<User>[] = [
+  {
+    accessorKey: 'name',
+    header: 'Name',
+    sortable: true,
+    features: { search: true },
+    enableColumnFilter: true,
+    filterFn: 'includesString',
+  },
+  {
+    accessorKey: 'role',
+    header: 'Role',
+    enableGrouping: true,
+    enableColumnFilter: true,
+    filterFn: 'equals',
+    cell: ({ row }) => (
+      <Select value={row.original.role} onValueChange={(value) => handleRoleChange(row.original.id, value)}>
+        <SelectTrigger>
+          <SelectValue />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="admin">Admin</SelectItem>
+          <SelectItem value="user">User</SelectItem>
+          <SelectItem value="guest">Guest</SelectItem>
+        </SelectContent>
+      </Select>
+    ),
+  },
+];
+```
+
+## Column Ordering
+
+The DataTable component supports custom column ordering through the `columnOrder` prop, allowing you to control the exact position of columns including selection and actions columns.
+
+### Basic Column Ordering
+
+```tsx
+<DataTable
+  data={data}
+  columns={columns}
+  features={{
+    selection: true,
+    sorting: true,
+    filtering: true,
+  }}
+  columnOrder={['select', 'name', 'email', 'role', 'status']}
+/>
+```
+
+### Column Order Behavior
+
+#### When `columnOrder` is provided:
+- **Exact positioning**: Columns appear in the exact order specified
+- **Selection column**: Include `'select'` in the array to position the selection column
+- **Actions column**: Include `'actions'` in the array to position the actions column
+- **Data columns**: Use the column's `accessorKey` or `id` to reference data columns
+
+#### When `columnOrder` is not provided:
+- **Default behavior**: Selection column first (if enabled), then data columns, then actions column
+- **Automatic ordering**: Columns appear in the order they're defined in the `columns` array
+
+### Selection Column Positioning
+
+The selection column can be positioned anywhere in the column order:
+
+```tsx
+// Selection column first (default when not in columnOrder)
+<DataTable
+  data={data}
+  columns={columns}
+  features={{ selection: true }}
+  columnOrder={['select', 'name', 'email', 'role']}
+/>
+
+// Selection column in the middle
+<DataTable
+  data={data}
+  columns={columns}
+  features={{ selection: true }}
+  columnOrder={['name', 'select', 'email', 'role']}
+/>
+
+// Selection column last
+<DataTable
+  data={data}
+  columns={columns}
+  features={{ selection: true }}
+  columnOrder={['name', 'email', 'role', 'select']}
+/>
+
+// Selection column not in columnOrder - defaults to first position
+<DataTable
+  data={data}
+  columns={columns}
+  features={{ selection: true }}
+  columnOrder={['name', 'email', 'role']} // selection will be first
+/>
+```
+
+### Actions Column Positioning
+
+The actions column can also be positioned anywhere:
+
+```tsx
+// Actions column last (default when not in columnOrder)
+<DataTable
+  data={data}
+  columns={columns}
+  features={{ editing: true, deletion: true }}
+  columnOrder={['name', 'email', 'role', 'actions']}
+/>
+
+// Actions column first
+<DataTable
+  data={data}
+  columns={columns}
+  features={{ editing: true, deletion: true }}
+  columnOrder={['actions', 'name', 'email', 'role']}
+/>
+
+// Actions column in the middle
+<DataTable
+  data={data}
+  columns={columns}
+  features={{ editing: true, deletion: true }}
+  columnOrder={['name', 'actions', 'email', 'role']}
+/>
+```
+
+### Complete Column Ordering Example
+
+```tsx
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: string;
+  status: 'active' | 'inactive';
+  createdAt: Date;
+}
+
+const columns: DataTableColumn<User>[] = [
+  {
+    accessorKey: 'name',
+    header: 'Name',
+    sortable: true,
+  },
+  {
+    accessorKey: 'email',
+    header: 'Email',
+    sortable: true,
+  },
+  {
+    accessorKey: 'role',
+    header: 'Role',
+    sortable: true,
+    enableGrouping: true,
+  },
+  {
+    accessorKey: 'status',
+    header: 'Status',
+    sortable: true,
+  },
+  {
+    accessorKey: 'createdAt',
+    header: 'Created',
+    sortable: true,
+  },
+];
+
+function UserTable() {
+  return (
+    <DataTable
+      data={users}
+      columns={columns}
+      title="User Management"
+      features={{
+        selection: true,
+        sorting: true,
+        filtering: true,
+        editing: true,
+        deletion: true,
+      }}
+      // Custom column order: selection first, then name, email, role, status, actions, created last
+      columnOrder={['select', 'name', 'email', 'role', 'status', 'actions', 'createdAt']}
+      onEditRow={handleEdit}
+      onDeleteRow={handleDelete}
+    />
+  );
+}
+```
+
+### Column Ordering with Hierarchical Data
+
+When using hierarchical data, column ordering works the same way:
+
+```tsx
+<DataTable
+  data={hierarchicalData}
+  columns={columns}
+  features={{
+    hierarchical: true,
+    selection: true,
+    editing: true,
+    deletion: true,
+  }}
+  hierarchical={{
+    enabled: true,
+    defaultExpanded: false,
+  }}
+  // Custom order for hierarchical table
+  columnOrder={['select', 'name', 'ingredient', 'quantity', 'actions']}
+/>
+```
+
+### Dynamic Column Ordering
+
+You can dynamically change column order based on user preferences or application state:
+
+```tsx
+function DynamicUserTable() {
+  const [columnOrder, setColumnOrder] = useState(['select', 'name', 'email', 'role', 'status']);
+  
+  const handleColumnReorder = (newOrder: string[]) => {
+    setColumnOrder(newOrder);
+    // Save to localStorage or user preferences
+    localStorage.setItem('userTableColumnOrder', JSON.stringify(newOrder));
+  };
+
+  return (
+    <DataTable
+      data={users}
+      columns={columns}
+      features={{
+        selection: true,
+        sorting: true,
+        columnReordering: true, // Enable drag-and-drop reordering
+      }}
+      columnOrder={columnOrder}
+      onColumnOrderChange={handleColumnReorder}
+    />
+  );
+}
+```
+
+### Column Ordering Best Practices
+
+#### 1. **Consistent Ordering**
+```tsx
+// ✅ Good - Consistent ordering across similar tables
+const userTableOrder = ['select', 'name', 'email', 'role', 'status', 'actions'];
+const productTableOrder = ['select', 'name', 'sku', 'price', 'status', 'actions'];
+
+// ❌ Avoid - Inconsistent ordering
+const userTableOrder = ['select', 'name', 'email', 'role', 'status', 'actions'];
+const productTableOrder = ['name', 'select', 'sku', 'actions', 'price', 'status'];
+```
+
+#### 2. **Logical Grouping**
+```tsx
+// ✅ Good - Logical grouping of related columns
+columnOrder={[
+  'select',           // Selection controls
+  'name', 'email',    // Identity information
+  'role', 'status',   // Access and state
+  'createdAt',        // Metadata
+  'actions'           // Actions
+]}
+
+// ❌ Avoid - Random column order
+columnOrder={['email', 'actions', 'name', 'select', 'status', 'role', 'createdAt']}
+```
+
+#### 3. **User Experience Considerations**
+```tsx
+// ✅ Good - Most important columns first
+columnOrder={['select', 'name', 'email', 'role', 'status', 'actions']}
+
+// ✅ Good - Actions column last (standard pattern)
+columnOrder={['select', 'name', 'email', 'role', 'status', 'actions']}
+
+// ❌ Avoid - Actions column in the middle (confusing)
+columnOrder={['select', 'name', 'actions', 'email', 'role', 'status']}
+```
+
+#### 4. **Responsive Considerations**
+```tsx
+// For mobile-first design, put most important columns first
+const mobileColumnOrder = ['select', 'name', 'status', 'actions'];
+const desktopColumnOrder = ['select', 'name', 'email', 'role', 'status', 'createdAt', 'actions'];
+
+<DataTable
+  data={users}
+  columns={columns}
+  features={{ selection: true, sorting: true }}
+  columnOrder={isMobile ? mobileColumnOrder : desktopColumnOrder}
+/>
+```
+
+## Data Management
+
+### Sorting
+
+```tsx
+<DataTable
+  data={data}
+  columns={columns}
+  features={{ sorting: true }}
+  defaultSorting={[
+    { id: 'name', desc: false },
+    { id: 'createdAt', desc: true }
+  ]}
+/>
+```
+
+### Filtering
+
+```tsx
+<DataTable
+  data={data}
+  columns={columns}
+  features={{ filtering: true }}
+  globalFilterFn="includesString"
+  columnFilters={[
+    { id: 'status', value: 'active' },
+    { id: 'role', value: 'admin' }
+  ]}
+/>
+```
+
+### Pagination
+
+```tsx
+<DataTable
+  data={data}
+  columns={columns}
+  features={{ pagination: true }}
+/>
+```
+
+#### Custom Initial Page Size
+
+```tsx
+<DataTable
+  data={data}
+  columns={columns}
+  features={{ pagination: true }}
+  initialPageSize={25} // Start with 25 items per page instead of default 10
+/>
+```
+
+#### Page Size Validation
+
+The DataTable automatically validates the `initialPageSize` against available page size options:
+
+```tsx
+<DataTable
+  data={data}
+  columns={columns}
+  features={{ pagination: true }}
+  initialPageSize={15} // Will fallback to closest valid option (10) with console warning
+/>
+```
+
+**Available page size options by mode:**
+- **Client mode**: `[10, 25, 50]` or `[10, 25, 50, 100]` (depending on data size)
+- **Hybrid mode**: `[50, 100, 250, 500]`
+- **Server mode**: `[25, 50, 100, 250]`
+
+### Search
+
+```tsx
+<DataTable
+  data={data}
+  columns={columns}
+  features={{ search: true }}
+  searchKey="name" // Default search field
+  searchPlaceholder="Search users..."
+  searchDebounceMs={300}
+/>
+```
+
+## Advanced Features
+
+### Row Actions
+
+Row actions are handled through the `actions` prop, which provides full flexibility for custom action buttons:
+
+```tsx
+<DataTable
+  data={data}
+  columns={columns}
+  features={{ 
+    editing: true,
+    deletion: true,
+  }}
+  onEditRow={handleEdit}
+  onDeleteRow={handleDelete}
+  // Custom actions using the actions prop
+  actions={[
+    {
+      label: 'View Details',
+      onClick: (row) => navigate(`/users/${row.original.id}`),
+      icon: EyeIcon,
+      variant: 'default',
+    },
+    {
+      label: 'Edit',
+      onClick: (row) => editUser(row.original.id),
+      icon: EditIcon,
+      variant: 'outline',
+    },
+    {
+      label: 'Share',
+      onClick: (row) => shareUser(row.original.id),
+      icon: ShareIcon,
+      variant: 'secondary',
+    },
+    {
+      label: 'More Options',
+      onClick: (row) => showMoreOptions(row.original.id),
+      icon: MoreHorizontalIcon,
+      variant: 'ghost',
+    },
+    {
+      label: 'Archive',
+      onClick: (row) => archiveUser(row.original.id),
+      icon: ArchiveIcon,
+      variant: 'destructive',
+      disabled: (row) => row.original.status === 'archived',
+    },
+  ]}
+/>
+```
+
+#### Action Configuration
+
+Each action supports the following properties:
+
+- `label: string` - Display label for the action
+- `onClick: (row: TData) => void` - Action handler function
+- `icon?: ComponentType` - Optional icon component
+- `variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost'` - Button variant
+- `disabled?: (row: TData) => boolean` - Function to determine if action is disabled
+- `testId?: string` - Test ID for testing
+- `visible?: boolean | (row: TData) => boolean` - Control visibility
+- `showInEditMode?: boolean` - Show in edit mode (default: true)
+- `hideInViewMode?: boolean` - Hide in view mode (default: false)
+
+#### Action Variants Guide
+
+The DataTable supports 5 action variants, each designed for specific use cases:
+
+```tsx
+const actions = [
+  // DEFAULT - Primary actions (most important)
+  {
+    label: 'View Details',
+    onClick: (row) => viewDetails(row.original.id),
+    icon: EyeIcon,
+    variant: 'default', // Solid background, primary color
+  },
+  
+  // OUTLINE - Secondary actions (important but not primary)
+  {
+    label: 'Edit',
+    onClick: (row) => editItem(row.original.id),
+    icon: EditIcon,
+    variant: 'outline', // Bordered, transparent background
+  },
+  
+  // SECONDARY - Supporting actions (less prominent)
+  {
+    label: 'Share',
+    onClick: (row) => shareItem(row.original.id),
+    icon: ShareIcon,
+    variant: 'secondary', // Muted background, subtle styling
+  },
+  
+  // GHOST - Subtle actions (minimal visual impact)
+  {
+    label: 'More Options',
+    onClick: (row) => showMoreOptions(row.original.id),
+    icon: MoreHorizontalIcon,
+    variant: 'ghost', // No background, minimal styling
+  },
+  
+  // DESTRUCTIVE - Dangerous actions (require caution)
+  {
+    label: 'Delete',
+    onClick: (row) => deleteItem(row.original.id),
+    icon: TrashIcon,
+    variant: 'destructive', // Red styling to indicate danger
+    disabled: (row) => row.original.status === 'locked',
+  },
+];
+```
+
+**Variant Usage Guidelines:**
+
+- **`default`**: Use for the most important action (e.g., "View Details", "Open")
+- **`outline`**: Use for important secondary actions (e.g., "Edit", "Download")
+- **`secondary`**: Use for supporting actions (e.g., "Share", "Copy", "Export")
+- **`ghost`**: Use for subtle actions (e.g., "More Options", "Settings")
+- **`destructive`**: Use for dangerous actions (e.g., "Delete", "Archive", "Remove")
+
+#### Hierarchical Actions
+
+When using hierarchical rows, you can define different action icons and labels for parent vs child rows:
+
+```tsx
+<DataTable
+  data={hierarchicalData}
+  columns={columns}
+  features={{ 
+    hierarchical: true,
+    editing: true,
+    deletion: true,
+  }}
+  hierarchical={{
+    enabled: true,
+    defaultExpanded: false,
+  }}
+  actions={[
+    {
+      label: 'View Details',
+      icon: EyeIcon,
+      // Different icons for parent vs child rows
+      parentIcon: EyeIcon,
+      childIcon: InfoIcon,
+      // Different labels for parent vs child rows
+      parentLabel: 'View Recipe',
+      childLabel: 'View Ingredient',
+      onClick: (row) => {
+        console.log('Viewing:', row.isParent ? 'Recipe' : 'Ingredient', row.name);
+      },
+      variant: 'default',
+    },
+    {
+      label: 'Edit',
+      icon: PencilIcon,
+      parentIcon: SettingsIcon,
+      childIcon: PencilIcon,
+      parentLabel: 'Edit Recipe',
+      childLabel: 'Edit Ingredient',
+      onClick: (row) => {
+        console.log('Editing:', row.isParent ? 'Recipe' : 'Ingredient', row.name);
+      },
+      variant: 'default',
+    },
+    {
+      label: 'Copy Recipe',
+      icon: CopyIcon,
+      parentIcon: CopyIcon,
+      parentLabel: 'Duplicate Recipe',
+      onClick: (row) => {
+        console.log('Copying recipe:', row.name);
+      },
+      variant: 'outline',
+      // Only show for parent rows
+      showForParent: true,
+    },
+    {
+      label: 'Export',
+      icon: DownloadIcon,
+      childIcon: DownloadIcon,
+      childLabel: 'Export Ingredient',
+      onClick: (row) => {
+        console.log('Exporting ingredient:', row.item);
+      },
+      variant: 'ghost',
+      // Only show for child rows
+      showForChild: true,
+    },
+  ]}
+/>
+```
+
+##### Hierarchical Action Properties
+
+When using hierarchical rows, actions support additional properties:
+
+- `showForParent?: boolean` - Only show this action for parent rows
+- `showForChild?: boolean` - Only show this action for child rows
+- `parentIcon?: ComponentType` - Icon to use for parent rows (overrides `icon`)
+- `childIcon?: ComponentType` - Icon to use for child rows (overrides `icon`)
+- `parentLabel?: string` - Label to use for parent rows (overrides `label`)
+- `childLabel?: string` - Label to use for child rows (overrides `label`)
+
+##### Action Visibility Logic
+
+The action visibility is determined by the following logic:
+
+1. **Hierarchical filtering**: If `showForParent` is true, action only shows for parent rows
+2. **Hierarchical filtering**: If `showForChild` is true, action only shows for child rows
+3. **Standard filtering**: Uses `visible`, `showInEditMode`, `hideInViewMode` properties
+4. **Disabled state**: Uses `disabled` function to determine if action is disabled
+
+### Toolbar Actions
+
+Toolbar actions are automatically generated based on the enabled features. Custom toolbar buttons are not directly supported in the current interface, but you can implement them outside the DataTable component:
+
+```tsx
+// Toolbar actions are handled through feature configuration
+<div>
+  {/* Custom toolbar */}
+  <div className="flex gap-2 mb-4">
+    <Button onClick={() => navigate('/users/create')}>
+      <PlusIcon className="h-4 w-4 mr-2" />
+      Add User
+    </Button>
+  </div>
+  
+  <DataTable
+    data={data}
+    columns={columns}
+    features={{
+      search: true,
+      pagination: true,
+      export: true,
+      import: true,
+      creation: true, // Enables built-in create functionality if onCreateRow is provided
+    }}
+    onCreateRow={handleCreate}
+    onImport={handleImport}
+    exportFilename="users"
+  />
+</div>
+```
+
+### Hierarchical Parent/Child Rows
+
+The DataTable supports hierarchical parent/child row relationships with built-in expand/collapse functionality, expand/collapse all controls, and proper column rendering for different row types.
+
+#### Data Structure
+
+Your data must conform to the `HierarchicalDataRow` interface:
+
+```typescript
+interface HierarchicalDataRow extends DataRecord {
+  /** Whether this row is a parent row */
+  isParent: boolean;
+  /** For child rows, references the parent row ID */
+  parentId?: string;
+  /** Unique identifier for this row */
+  id: string;
+  // ... your actual data properties
+}
+```
+
+#### Configuration
+
+Enable hierarchical functionality through the `features` prop and configure it with the `hierarchical` prop:
+
+```tsx
+<DataTable
+  data={hierarchicalData}
+  columns={columns}
+  features={{
+    // ... other features
+    hierarchical: true, // Enable hierarchical functionality
+  }}
+  hierarchical={{
+    enabled: true,
+    defaultExpanded: false, // true = all expanded, false = all collapsed, array = specific IDs
+    onExpandedChange: (expandedIds) => console.log('Expanded:', expandedIds),
+    expandButton: CustomExpandButton, // Optional custom expand button
+    indentSize: 24, // Indentation for child rows in pixels
+    parentRowClassName: 'bg-main-50 font-medium', // Custom styling for parent rows
+    childRowClassName: 'bg-sec-25', // Custom styling for child rows
+  }}
+```
+
+**Default Collapsed State:**
+To make parent rows collapsed by default (recommended for better UX), set `defaultExpanded: false`. This ensures users see only parent rows initially and must click to expand and view child rows.
+
+#### Column Configuration
+
+Configure how columns render for different row types:
+
+```tsx
+const columns: DataTableColumn<YourDataType>[] = [
+  {
+    accessorKey: 'code',
+    header: 'Code',
+    // Render differently for parent vs child rows
+    renderForParent: (row) => (
+      <div className="flex items-center gap-2">
+        <strong>{row.code}</strong>
+      </div>
+    ),
+    renderForChild: () => '', // Blank for child rows
+    hideForChild: true, // Hide this column for child rows
+  },
+  {
+    accessorKey: 'name',
+    header: 'Name',
+    renderForParent: (row) => <strong>{row.name}</strong>,
+    renderForChild: () => '', // Blank for child rows
+    hideForChild: true,
+  },
+  {
+    accessorKey: 'ingredient',
+    header: 'Ingredient',
+    renderForParent: () => '', // Blank for parent rows
+    renderForChild: (row) => <span className="ml-4">{row.ingredient}</span>,
+    hideForParent: true, // Hide this column for parent rows
+  },
+];
+```
+
+#### Column Properties
+
+- `renderForParent?: (row: TData) => React.ReactNode` - Custom renderer for parent rows
+- `renderForChild?: (row: TData) => React.ReactNode` - Custom renderer for child rows
+- `hideForParent?: boolean` - Hide this column for parent rows
+- `hideForChild?: boolean` - Hide this column for child rows
+
+#### Expand/Collapse All Controls
+
+The DataTable automatically adds an expand/collapse all button in the header when hierarchical mode is enabled:
+
+**Features:**
+- **Expand All Button (▶️)**: Expands all parent rows to show their children
+- **Collapse All Button (🔽)**: Collapses all parent rows to hide their children
+- **Smart State Detection**: Button automatically updates based on current expansion state
+- **Accessibility**: Proper ARIA labels and keyboard navigation support
+
+**Usage:**
+```tsx
+<DataTable
+  data={hierarchicalData}
+  columns={columns}
+  features={{ hierarchical: true }}
+  hierarchical={{
+    enabled: true,
+    defaultExpanded: false, // Start with all collapsed
+    onExpandedChange: (expandedIds) => {
+      console.log('Expanded rows:', expandedIds);
+    },
+  }}
+/>
+```
+
+**Button Behavior:**
+- Shows ▶️ when some or all parent rows are collapsed
+- Shows 🔽 when all parent rows are expanded
+- Only appears when there are parent rows with children
+- Positioned in the first column of the table header
+
+#### Hierarchical Sorting
+
+When hierarchical mode is enabled, sorting behavior is optimized to preserve the parent-child relationship structure:
+
+**Parent Row Sorting:**
+- Parent rows maintain their original order and are not affected by sorting
+- Only child rows within each parent group are sorted
+- This prevents parent rows from being moved to unexpected positions
+
+**Child Row Sorting:**
+- Child rows are sorted within their parent group only
+- Sorting by a child-specific column (e.g., "Diet", "Ingredient") will sort children within each parent
+- The parent row remains at the top of its group
+
+**Example:**
+```tsx
+// When sorting by "Diet" column:
+// ✅ Correct behavior:
+// Parent: Caesar Salad
+//   ├─ Child: Dairy Free (Sour cream)
+//   ├─ Child: Egg Free (Mayonnaise)
+//   └─ Child: GF & Vegan (Lettuce)
+// Parent: Beef Stir Fry
+//   ├─ Child: GF & Vegan (Vegetables)
+//   └─ Child: Halal (Beef)
+
+// ❌ Incorrect behavior (what we prevent):
+// Child: Dairy Free (Sour cream)
+// Child: Egg Free (Mayonnaise)
+// Child: GF & Vegan (Lettuce)
+// Child: GF & Vegan (Vegetables)
+// Child: Halal (Beef)
+// Parent: Caesar Salad (moved to end)
+// Parent: Beef Stir Fry (moved to end)
+```
+
+**Sorting Configuration:**
+- All existing sorting features work with hierarchical data
+- Multi-column sorting is supported
+- Server-side sorting is compatible
+- Column-specific sorting behavior is preserved
+
+#### Example Use Case
+
+```tsx
+// Dishes and ingredients example
+const dishData = [
+  // Parent rows (dishes)
+  { id: 'dish-1', isParent: true, code: 'D001', name: 'Caesar Salad', type: 'Salad' },
+  { id: 'dish-2', isParent: true, code: 'D002', name: 'Beef Stir Fry', type: 'Main Course' },
+  
+  // Child rows (ingredients) for Caesar Salad
+  { id: 'ing-1-1', isParent: false, parentId: 'dish-1', ingredient: 'Lettuce', quantity: '200g' },
+  { id: 'ing-1-2', isParent: false, parentId: 'dish-1', ingredient: 'Chicken', quantity: '150g' },
+  
+  // Child rows (ingredients) for Beef Stir Fry
+  { id: 'ing-2-1', isParent: false, parentId: 'dish-2', ingredient: 'Beef Strips', quantity: '250g' },
+  { id: 'ing-2-2', isParent: false, parentId: 'dish-2', ingredient: 'Mixed Vegetables', quantity: '200g' },
+];
+```
+
+### Row Selection and Bulk Operations
+
+```tsx
+function SelectableUserTable() {
+  const [selectedRows, setSelectedRows] = useState<Record<string, boolean>>({});
+  const [data, setData] = useState<User[]>(initialData);
+
+  const handleBulkDelete = (selectedRows: Record<string, boolean>) => {
+    // Get the selected row IDs
+    const selectedRowIds = Object.keys(selectedRows).filter(id => selectedRows[id]);
+    
+    // Get the actual data for selected rows
+    const selectedData = data.filter(row => {
+      const rowId = getRowId ? getRowId(row, data.indexOf(row)) : row.id;
+      return selectedRowIds.includes(rowId);
+    });
+    
+    // Perform your deletion logic
+    console.log('Deleting selected rows:', selectedData);
+    
+    // Update your data state
+    setData(prevData => 
+      prevData.filter(row => {
+        const rowId = getRowId ? getRowId(row, prevData.indexOf(row)) : row.id;
+        return !selectedRowIds.includes(rowId);
+      })
+    );
+    
+    // Clear selection after deletion
+    setSelectedRows({});
+  };
+
+  return (
+    <DataTable
+      data={data}
+      columns={columns}
+      features={{
+        selection: true,
+        deletion: true,        // Required for delete functionality
+        deleteSelected: true,  // Enables the delete selected button
+        bulkOperations: true,
+      }}
+      onRowSelectionChange={setSelectedRows}
+      onDeleteSelected={handleBulkDelete}
+      getRowId={(row) => row.id} // Important: provide getRowId for proper row identification
+    />
+  );
+}
+```
+
+#### Alternative: Using Individual onDeleteRow (Fallback)
+
+If you don't provide `onDeleteSelected`, the DataTable will automatically fall back to calling `onDeleteRow` for each selected row:
+
+```tsx
+function SelectableUserTable() {
+  const [data, setData] = useState<User[]>(initialData);
+
+  const handleDeleteRow = (row: User) => {
+    console.log('Deleting row:', row);
+    
+    // Update your data state
+    setData(prevData => prevData.filter(item => item.id !== row.id));
+  };
+
+  return (
+    <DataTable
+      data={data}
+      columns={columns}
+      features={{
+        selection: true,
+        deletion: true,
+        deleteSelected: true,
+      }}
+      onDeleteRow={handleDeleteRow} // This will be called for each selected row
+      getRowId={(row) => row.id}
+    />
+  );
+}
+```
+
+### Column Visibility
+
+```tsx
+<DataTable
+  data={data}
+  columns={columns}
+  features={{ columnVisibility: true }}
+  defaultColumnVisibility={{
+    id: false,
+    createdAt: false,
+  }}
+/>
+```
+
+### Data Grouping
+
+```tsx
+<DataTable
+  data={data}
+  columns={columns}
+  features={{ grouping: true }}
+  grouping={['role', 'status']}
+/>
+```
+
+## Performance Optimization
+
+### Virtual Scrolling
+
+```tsx
+<DataTable
+  data={largeDataset}
+  columns={columns}
+  features={{ virtualization: true }}
+  virtualHeight={600} // Height of the virtual scrolling container
+  performance={{
+    virtualScrolling: true,
+    memoryOptimization: true,
+  }}
+/>
+```
+
+### Lazy Loading
+
+```tsx
+function LazyLoadingTable() {
+  const [data, setData] = useState<User[]>([]);
+  const [loading, setLoading] = useState(false);
+  const [hasMore, setHasMore] = useState(true);
+
+  const loadMoreData = async () => {
+    setLoading(true);
+    const newData = await fetchUsers(data.length, 50);
+    setData(prev => [...prev, ...newData]);
+    setHasMore(newData.length === 50);
+    setLoading(false);
+  };
+
+  return (
+    <DataTable
+      data={data}
+      columns={columns}
+      loading={loading}
+      onLoadMore={hasMore ? loadMoreData : undefined}
+      hasMore={hasMore}
+    />
+  );
+}
+```
+
+### Optimized Rendering
+
+```tsx
+<DataTable
+  data={data}
+  columns={columns}
+  features={{
+    virtualization: true,
+    performanceMetrics: true,
+  }}
+  performance={{
+    virtualScrolling: true,
+    memoryOptimization: true,
+    renderOptimization: true,
+  }}
+  showPerformanceMetrics={true}
+  virtualHeight={600}
+/>
+```
+
+## Integration with RBAC
+
+### Permission-Based Actions
+
+```tsx
+function SecureUserTable() {
+  const { checkPermission } = usePermissionCache();
+
+  const [permissions, setPermissions] = useState({
+    canCreate: false,
+    canUpdate: false,
+    canDelete: false,
+  });
+
+  useEffect(() => {
+    const loadPermissions = async () => {
+      const results = await Promise.all([
+        checkPermission('create', 'user-management'),
+        checkPermission('update', 'user-management'),
+        checkPermission('delete', 'user-management'),
+      ]);
+
+      setPermissions({
+        canCreate: results[0],
+        canUpdate: results[1],
+        canDelete: results[2],
+      });
+    };
+
+    loadPermissions();
+  }, [checkPermission]);
+
+  return (
+    <DataTable
+      data={users}
+      columns={columns}
+      features={{
+        search: true,
+        pagination: true,
+        creation: permissions.canCreate,
+        editing: permissions.canUpdate,
+        deletion: permissions.canDelete,
+        rowActions: permissions.canUpdate || permissions.canDelete,
+      }}
+      onEditRow={permissions.canUpdate ? (row) => navigate(`/users/${row.original.id}/edit`) : undefined}
+      onDeleteRow={permissions.canDelete ? (row) => handleDelete(row.original.id) : undefined}
+      // Custom actions using deprecated actions prop (still supported)
+      actions={
+        permissions.canUpdate || permissions.canDelete ? [
+          {
+            label: 'View Details',
+            onClick: (row) => navigate(`/users/${row.original.id}`),
+          }
+        ] : []
+      }
+    />
+  );
+}
+```
+
+## Practical Examples
+
+### Custom Page Size Configuration
+
+Here's a complete example showing how to configure a DataTable with custom initial page size:
+
+```tsx
+import { DataTable, type DataTableColumn } from '@jmruthers/pace-core';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: string;
+  status: 'active' | 'inactive';
+}
+
+const columns: DataTableColumn<User>[] = [
+  {
+    accessorKey: 'name',
+    header: 'Name',
+    sortable: true,
+    searchable: true,
+  },
+  {
+    accessorKey: 'email',
+    header: 'Email',
+    sortable: true,
+    searchable: true,
+  },
+  {
+    accessorKey: 'role',
+    header: 'Role',
+    sortable: true,
+    enableGrouping: true,
+  },
+  {
+    accessorKey: 'status',
+    header: 'Status',
+    sortable: true,
+    cell: ({ row }) => (
+      <span className={`px-2 py-1 rounded text-xs ${
+        row.original.status === 'active' 
+          ? 'bg-main-100 text-main-800'
+          : 'bg-acc-100 text-acc-800'
+      }`}>
+        {row.original.status}
+      </span>
+    ),
+  },
+];
+
+function UserManagementTable() {
+  const [users, setUsers] = useState<User[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    // Load users data
+    loadUsers().then(setUsers).finally(() => setLoading(false));
+  }, []);
+
+  return (
+    <DataTable
+      data={users}
+      columns={columns}
+      title="User Management"
+      description="Manage system users with custom page size"
+      features={{
+        search: true,
+        pagination: true,
+        sorting: true,
+        filtering: true,
+        selection: true,
+        creation: true,
+        editing: true,
+        deletion: true,
+        deleteSelected: true,
+        export: true,
+        import: true,
+        grouping: true,
+        columnVisibility: true,
+        columnReordering: true,
+        autoColumnSizing: true,
+      }}
+      initialPageSize={25} // Start with 25 users per page
+      isLoading={loading}
+      onEditRow={(row, data) => {
+        console.log('Editing user:', row.id, data);
+        // Handle user edit
+      }}
+      onDeleteRow={(row) => {
+        console.log('Deleting user:', row.id);
+        // Handle user deletion
+      }}
+      onCreateRow={(data) => {
+        console.log('Creating user:', data);
+        // Handle user creation
+      }}
+      onImport={(data) => {
+        console.log('Importing users:', data);
+        // Handle user import
+      }}
+      onRowSelectionChange={(selection) => {
+        console.log('Selection changed:', selection);
+        // Handle selection changes
+      }}
+      onDeleteSelected={(selectedRows) => {
+        console.log('Bulk deleting users:', selectedRows);
+        // Handle bulk deletion
+      }}
+    />
+  );
+}
+```
+
+### Page Size Validation Example
+
+```tsx
+// This will show a console warning and use the closest valid option
+<DataTable
+  data={largeDataset}
+  columns={columns}
+  features={{ pagination: true }}
+  initialPageSize={15} // Invalid - will fallback to 10 with warning
+  paginationMode="client" // Uses [10, 25, 50] options
+/>
+
+// This will work correctly
+<DataTable
+  data={largeDataset}
+  columns={columns}
+  features={{ pagination: true }}
+  initialPageSize={25} // Valid option
+  paginationMode="client"
+/>
+```
+
+## Best Practices
+
+### Data Processing Best Practices
+- **Stable Data References**: Ensure your data processing doesn't create new object references on every render
+- **Memoization**: Use `useMemo` with proper dependency arrays to prevent unnecessary re-computations
+- **Avoid Complex Transformations in useMemo**: Move complex data transformations to the backend or data fetching layer when possible
+- **Data Comparison**: Use shallow comparison to detect actual data changes before updating state
+
+#### ✅ Good Data Processing Patterns
+```tsx
+// Simple, stable data processing
+const processedData = useMemo(() => {
+  if (!data || data.length === 0) return [];
+  return data; // Direct usage, no transformations
+}, [data]);
+
+// Complex processing with stable references
+const processedData = useMemo(() => {
+  if (!data || data.length === 0) return [];
+  
+  // Use stable references and avoid creating new objects unnecessarily
+  return data.map(item => ({
+    ...item,
+    // Simple transformations only
+    displayName: item.firstName + ' ' + item.lastName,
+  }));
+}, [data]); // Single dependency
+```
+
+#### ❌ Avoid These Patterns
+```tsx
+// This can cause infinite loops
+const processedData = useMemo(() => {
+  return data.map(item => ({
+    ...item,
+    // Complex transformations that create new objects
+    computed_field: relatedData?.find(rel => rel.id === item.relation_id)?.name || 'Unknown',
+    formatted_date: item.date ? format(new Date(item.date), 'MMM dd, yyyy') : 'No date',
+  }));
+}, [data, relatedData]); // Multiple dependencies with complex processing
+```
+
+#### 🔧 Recommended Solutions for Complex Data
+1. **Backend Processing**: Move complex transformations to your API layer
+2. **Supabase Relations**: Use database relations instead of client-side lookups
+3. **Separate Hooks**: Create dedicated hooks for data processing
+4. **Stable References**: Use `useCallback` and `useMemo` with proper dependencies
+
+### 1. Use the Features Configuration Properly
+
+```tsx
+// ✅ Good - Clear feature configuration
+<DataTable
+  data={data}
+  columns={columns}
+  features={{
+    search: true,
+    pagination: true,
+    editing: userCanEdit,
+    deletion: userCanDelete,
+  }}
+  onEditRow={handleEdit}
+  onDeleteRow={handleDelete}
+/>
+
+// ❌ Avoid - Don't enable features without handlers
+<DataTable
+  data={data}
+  columns={columns}
+  features={{
+    editing: true,  // But no onEditRow handler
+    deletion: true, // But no onDeleteRow handler
+  }}
+/>
+
+// ❌ Avoid - Don't use deprecated individual props
+<DataTable
+  data={data}
+  columns={columns}
+  // These props are deprecated and should not be used
+  // Use the features prop instead
+/>
+```
+
+### 2. Use Proper TypeScript Types
+
+```tsx
+// ✅ Good - Strong typing
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: UserRole;
+  status: UserStatus;
+  createdAt: Date;
+}
+
+const columns: DataTableColumn<User>[] = [
+  {
+    accessorKey: 'name',
+    header: 'Name',
+    sortable: true,
+  },
+];
+
+// ❌ Avoid - Weak typing
+const columns = [
+  {
+    accessorKey: 'name',
+    header: 'Name',
+  },
+];
+```
+
+### 2. Optimize for Performance
+
+```tsx
+// ✅ Good - Memoized components with performance optimization
+const UserTable = React.memo(() => {
+  const [data, setData] = useState<User[]>([]);
+  
+  return (
+    <DataTable
+      data={data}
+      columns={columns}
+      features={{ virtualization: true }}
+      performance={{
+        memoryOptimization: true,
+        renderOptimization: true,
+      }}
+    />
+  );
+});
+
+// ❌ Avoid - Unnecessary re-renders
+function UserTable() {
+  return (
+    <DataTable
+      data={data}
+      columns={columns}
+    />
+  );
+}
+```
+
+### 3. Handle Loading States
+
+```tsx
+// ✅ Good - Proper loading states
+function UserTable() {
+  const [loading, setLoading] = useState(true);
+  const [data, setData] = useState<User[]>([]);
+
+  useEffect(() => {
+    loadUsers().then(setData).finally(() => setLoading(false));
+  }, []);
+
+  return (
+    <DataTable
+      data={data}
+      columns={columns}
+      isLoading={loading}
+      // loadingText is not directly supported - use custom loadingComponent if needed
+    />
+  );
+}
+```
+
+### 4. Implement Error Handling
+
+```tsx
+// ✅ Good - Error handling
+function UserTable() {
+  const [error, setError] = useState<string | null>(null);
+
+  const handleDelete = async (userId: string) => {
+    try {
+      await deleteUser(userId);
+      // Refresh data
+    } catch (err) {
+      setError('Failed to delete user');
+    }
+  };
+
+  return (
+    <div>
+      {error && (
+        <Alert variant="destructive">
+          <AlertDescription>{error}</AlertDescription>
+        </Alert>
+      )}
+      <DataTable
+        data={data}
+        columns={columns}
+        features={{
+          search: true,
+          pagination: true,
+          deletion: true,
+          rowActions: true,
+        }}
+        onDeleteRow={(row) => handleDelete(row.id)}
+      />
+    </div>
+  );
+}
+```
+
+### 5. Use Consistent Styling
+
+```tsx
+// ✅ Good - Consistent styling
+const columns: DataTableColumn<User>[] = [
+  {
+    accessorKey: 'status',
+    header: 'Status',
+    cell: ({ row }) => (
+      <Badge 
+        variant={row.original.status === 'active' ? 'default' : 'secondary'}
+        className="capitalize"
+      >
+        {row.original.status}
+      </Badge>
+    ),
+  },
+];
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. Performance issues with large datasets
+- Enable virtualization: `features={{ virtualization: true }}`
+- Use performance optimization: `performance={{ memoryOptimization: true }}`
+- Set appropriate virtual height: `virtualHeight={600}`
+- Consider server-side sorting/filtering with `serverSide` prop
+
+#### 2. TypeScript errors
+- Ensure proper column typing: `DataTableColumn<YourType>[]`
+- Use proper accessor keys that match your data structure
+- Check that custom cell components return valid JSX
+
+#### 3. Sorting not working
+- Enable sorting: `features={{ sorting: true }}`
+- Set `sortable: true` on columns
+- Ensure data types are consistent for sorting
+
+#### 4. Search not working
+- Enable search: `features={{ search: true }}`
+- Set `searchable: true` on columns
+- Check `searchKey` matches your data structure
+
+#### 5. Actions not appearing
+- Enable row actions: `features={{ rowActions: true }}`
+- Check permissions if using RBAC
+- Ensure action arrays are properly structured
+- Verify onClick handlers are defined
+
+#### 6. Features not working
+- Ensure features are enabled in the `features` prop
+- Check that required event handlers are provided (e.g., `onEditRow` for editing)
+- Verify that the feature configuration matches your use case
+
+#### 7. Delete selected rows not working
+- **Check feature configuration**: Ensure `features={{ selection: true, deletion: true, deleteSelected: true }}`
+- **Provide onDeleteSelected callback**: Implement the callback to handle bulk deletion
+- **Verify getRowId function**: Ensure you provide a `getRowId` function that returns unique IDs
+- **Check button visibility**: The delete button only appears when all three features are enabled and rows are selected
+- **Debug selection state**: Add console logs to verify `onRowSelectionChange` is being called with correct data
+- **Fallback option**: If you don't provide `onDeleteSelected`, the table will fall back to calling `onDeleteRow` for each selected row
+
+### Debug Mode
+
+Enable debug logging for DataTable issues:
+
+```tsx
+<DataTable
+  data={data}
+  columns={columns}
+  features={{ performanceMetrics: true }}
+  showPerformanceMetrics={true}
+  onPerformanceMetrics={(metrics) => {
+    console.log('Performance metrics:', metrics);
+  }}
+/>
+```
+
+This comprehensive DataTable guide provides everything you need to build powerful, performant data interfaces with PACE Core.