@jmruthers/pace-core 0.4.1 → 0.5.1

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

@@ -8,9 +8,11 @@ The PACE Core DataTable is an enterprise-grade data table component built on Tan
 
 - **🚀 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
 
@@ -55,8 +57,8 @@ const columns: DataTableColumn<User>[] = [
     cell: ({ row }) => (
       <span className={`px-2 py-1 rounded text-xs ${
         row.original.status === 'active'
-          ? 'bg-green-100 text-green-800'
-          : 'bg-red-100 text-red-800'
+          ? 'bg-main-100 text-main-800'
+          : 'bg-acc-100 text-acc-800'
       }`}>
         {row.original.status}
       </span>
@@ -82,6 +84,7 @@ function UserTable() {
         sorting: true,
         filtering: true,
       }}
+      columnOrder={['name', 'email', 'role', 'status']} // Control column order
       // Performance and other settings can be configured via performance prop
     />
   );
@@ -141,19 +144,22 @@ The DataTable component has a comprehensive prop interface. Here are the key pro
 - `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
+- `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
-- `onDeleteSelected?: (selectedRows: Record<string, boolean>) => void` - Bulk delete 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
@@ -165,6 +171,30 @@ The DataTable component has a comprehensive prop interface. Here are the key pro
 
 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
@@ -183,25 +213,17 @@ The DataTable component uses a unified `features` prop to control all table func
     export: true,
     
     // Row Operations
-    selection: true,
+    selection: true,        // Required for row selection
     creation: true,
     editing: true,
-    deletion: true,
-    deleteSelected: true,
+    deletion: true,         // Required for delete functionality
+    deleteSelected: true,   // Required for delete selected button
     
     // Table Customization
     grouping: true,
     columnVisibility: true,
     columnReordering: true,
-    
-    // Performance
-    virtualization: true,
-    performanceMetrics: true,
-    
-    // Advanced Features
-    inlineEditing: true,
-    bulkOperations: true,
-    rowActions: true,
+    autoColumnSizing: true,  // Enable automatic column width adjustment
   }}
 />
 ```
@@ -239,17 +261,93 @@ For a full-featured data management table:
     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 }}
 />
 ```
 
@@ -361,6 +459,275 @@ const columns: DataTableColumn<User>[] = [
 ];
 ```
 
+## 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
@@ -402,6 +769,35 @@ const columns: DataTableColumn<User>[] = [
 />
 ```
 
+#### 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
@@ -439,6 +835,24 @@ Row actions are handled through the `actions` prop, which provides full flexibil
       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),
@@ -464,6 +878,155 @@ Each action supports the following properties:
 - `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:
@@ -496,11 +1059,218 @@ Toolbar actions are automatically generated based on the enabled features. Custo
 </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<RowSelectionState>({});
+  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
@@ -508,23 +1278,44 @@ function SelectableUserTable() {
       columns={columns}
       features={{
         selection: true,
+        deletion: true,        // Required for delete functionality
+        deleteSelected: true,  // Enables the delete selected button
         bulkOperations: true,
-        deleteSelected: true,
       }}
-      rowSelection={selectedRows}
       onRowSelectionChange={setSelectedRows}
       onDeleteSelected={handleBulkDelete}
-      bulkOperationsConfig={{
-        enabled: true,
-        operations: [
-          {
-            label: 'Delete Selected',
-            action: 'delete',
-            variant: 'destructive',
-            requiresConfirmation: true,
-          },
-        ],
+      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}
     />
   );
 }
@@ -680,8 +1471,191 @@ function SecureUserTable() {
 }
 ```
 
+## 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
@@ -897,6 +1871,14 @@ const columns: DataTableColumn<User>[] = [
 - 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: