@wix/auto-patterns 1.15.0 → 1.16.0

package/dist/docs/recipe-bulk-operations.md

@@ -0,0 +1,1352 @@
+# Recipe 3: Implementing Bulk Operations
+
+**Use Case**: "I need users to select multiple items and perform bulk actions (delete, export, archive, etc.)"
+
+---
+
+## Bulk Action Toolbar Configuration
+
+The Bulk Action Toolbar feature enables users to perform operations on multiple selected entities simultaneously in collection tables or grids. When configured, it adds checkboxes to each row and displays a toolbar with bulk actions when items are selected.
+
+### Placement and Structure
+
+The Bulk Action Toolbar is configured within the table / grid / table-grid switch configuration using the `bulkActionToolbar` property. It has a two-level structure:
+* `primaryActions`: Actions shown directly in the bulk action toolbar
+* `secondaryActions`: Additional actions organized in sections, typically shown in a dropdown menu
+
+Both properties are optional, but at least one should be provided for the bulk action toolbar to be functional.
+
+### Bulk Action Types Reference
+
+1. **Bulk Delete Action** (`type: "bulkDelete"`):
+   - ✓ Use when: Removing multiple entities with confirmation
+   - ✓ Common scenarios:
+     - Mass deletion of records
+     - Bulk cleanup operations
+   - ✓ Built-in functionality: No custom implementation needed
+
+2. **Custom Action** (`type: "custom"`):
+   - ✓ Use when: Executing custom JavaScript for bulk operations
+   - ✓ Common scenarios:
+     - Bulk API calls
+     - Bulk exports/downloads
+     - Complex bulk operations without UI
+   - ⚠️ Requires implementation: Must register action in overrides
+
+### Type Selection Decision Tree
+
+When choosing a bulk action type, follow this decision process:
+
+1. IF removing multiple entities:
+   → Use `type: "bulkDelete"`
+
+2. IF executing custom logic for bulk operations without UI:
+   → Use `type: "custom"`
+   - MUST implement action handler
+   - MUST register with `actions` override
+
+### Bulk Delete Action Configuration
+
+Bulk delete actions remove multiple entities with a confirmation modal.
+
+#### Validation Rules:
+
+1. `bulkDelete.mode` must be `"modal"` (currently only modal is supported)
+2. `bulkDelete.modal` object must exist
+3. The modal properties (title, description, actions, feedback) are all optional
+
+### Custom Bulk Action Configuration
+
+Custom bulk actions execute JavaScript code that you define for bulk operations. These actions receive parameters that give them access to selected entities data and utilities. Here's how to implement a custom bulk action:
+
+1. First, create the actions folder structure in your page folder:
+   ```
+   your-page/
+   ├── page.tsx
+   └── components/
+       └── actions/
+           ├── index.tsx                    // Exports all actions
+           └── bulkExportPets.tsx          // Your custom bulk action
+   ```
+
+2. Create your bulk action handler in `bulkExportPets.tsx`:
+   ```typescript
+   import { CustomBulkActionsActionResolver } from '@wix/auto-patterns';
+   import { Download } from '@wix/wix-ui-icons-common';
+   import React from 'react';
+
+   // IMPORTANT: Function name MUST match the action id in your configuration
+   export const bulkExportPets: CustomBulkActionsActionResolver = (params) => {
+     const { actionParams, sdk } = params;
+     const { selectedValues, total } = actionParams;
+
+     return {
+       label: 'Export Selected',
+       icon: <Download />,
+       onClick: () => {
+         // sdk is provided to custom action resolvers (see SDK Utilities section)
+         const optimisticActions = sdk.getOptimisticActions(sdk.collectionId);
+         const schema = sdk.getSchema(sdk.collectionId);
+
+         // Example: Mark pets as exported
+         const updatedItems = selectedValues.map(item => ({
+           ...item,
+           lastExported: new Date()
+         }));
+         optimisticActions.updateMany(updatedItems, {
+           submit: async (items) => {
+             // Your export logic here + update server
+             const exportData = items.map(pet => ({
+               name: pet.name,
+               age: pet.age,
+               owner: pet.owner
+             }));
+
+             // Create and download CSV
+             const csv = exportData.map(row => Object.values(row).join(',')).join('\n');
+             const blob = new Blob([csv], { type: 'text/csv' });
+             const url = URL.createObjectURL(blob);
+             const a = document.createElement('a');
+             a.href = url;
+             a.download = 'pets-export.csv';
+             a.click();
+
+             // Update server with export timestamp
+             return await schema.actions.update(items);
+           },
+           successToast: `${selectedValues.length} pets exported`,
+           errorToast: (err, {retry}) => ({
+             text: 'Export failed',
+             action: { text: 'Retry', onClick: retry }
+           })
+         });
+       },
+     };
+   };
+   ```
+
+3. Export your action in `actions/index.tsx`:
+   ```typescript
+   export * from './bulkExportPets';
+   ```
+
+4. Configure the action in your JSON configuration:
+   ```json
+   {
+     "id": "bulkExportPets",        // MUST match the function name exactly
+     "type": "custom",              // REQUIRED: Must be exactly "custom"
+     "label": "Export Selected",    // Optional: Displayed text
+   }
+   ```
+
+5. Register your action in the `PatternsWizardOverridesProvider`:
+   ```typescript
+   import * as actions from './components/actions';
+
+   <PatternsWizardOverridesProvider value={{ actions }}>
+     <AutoPatternsApp configuration={config as AppConfig} />
+   </PatternsWizardOverridesProvider>
+   ```
+
+### Key Points for Custom Bulk Actions:
+- The action `id` in the configuration MUST exactly match the function name exported from your actions folder
+- The function name and file name should follow a consistent naming convention (e.g., camelCase)
+- The implementation must be exported as a named export (not default export)
+- The implementation must use the `CustomBulkActionsActionResolver` type
+- Access selected entities through `actionParams.selectedValues`
+- Access total count through `actionParams.total`
+
+#### Validation Rules for Custom Bulk Actions:
+
+1. `id` must:
+   - Match exactly the function name of the custom bulk action implementation
+   - Be registered in the `actions` property of your `PatternsWizardOverridesProvider`
+   - Follow JavaScript identifier naming rules (camelCase recommended)
+
+2. The implementation must return an object with:
+   - `label`: Text displayed for the action
+   - `icon`: An Icon component from "@wix/wix-ui-icons-common"
+   - `onClick`: Handler function for the bulk action
+
+3. The implementation must:
+   - Use the correct type: `CustomBulkActionsActionResolver`
+   - Be exported as a named export
+   - Have a filename matching the function name
+
+### Bulk Action Toolbar Structure
+
+The bulk action toolbar uses a specific structure for organizing actions:
+
+#### Primary Actions Structure:
+```json
+"bulkActionToolbar": {
+  "primaryActions": [
+    {
+      "type": "action",
+      "action": {
+        "item": {
+          "id": "bulkCustom",
+          "type": "custom",
+          "label": "Custom Bulk",
+          "custom": {
+            "id": "MyCustomBulk"
+          }
+        }
+      }
+    },
+    {
+      "type": "menu",
+      "menu": {
+        "label": "More actions",
+        "items": [
+          {
+            "id": "exportItems",
+            "type": "custom",
+            "label": "Export Items"
+          },
+          { "type": "divider" },
+          {
+            "id": "downloadItems",
+            "type": "custom",
+            "label": "Download Items"
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+#### Secondary Actions Structure:
+```json
+"bulkActionToolbar": {
+  "secondaryActions": [
+      {
+        "id": "bulkDeleteWithModal",
+        "label": "Bulk Delete",
+        "type": "bulkDelete",
+        "bulkDelete": {
+          "mode": "modal",
+          "modal": {
+            "title": { "text": "Delete items" },
+            "description": { "text": "Are you sure?" }
+          }
+        }
+      },
+      {
+        "id": "bulkExportPets",
+        "type": "custom",
+        "label": "Export Selected"
+      }
+  ]
+}
+```
+
+### Key Implementation Decisions
+
+Follow this decision process when implementing Bulk Action Toolbar:
+
+1. **Basic Decision**: Decide which bulk operations users need to perform:
+   - Delete multiple entities? → Use `bulkDelete` actions
+   - Custom bulk operations? → Use `custom` actions
+
+2. **Primary vs Secondary**: Choose the most common/important bulk action as primary:
+   - Most common bulk operation → Place in `primaryActions.items` array
+   - Less common bulk operations → Place in `secondaryActions` array
+
+3. **Custom Implementation**:
+   - For `custom` bulk actions, you must provide implementations in your code and register them with `PatternsWizardOverridesProvider`
+
+### Bulk Action Toolbar Validation Checklist
+
+AI agents should verify these requirements before generating Bulk Action Toolbar configurations:
+
+✓ Bulk Action Toolbar is placed directly inside `table` or `grid` configuration as `bulkActionToolbar`
+✓ Each bulk action has a unique `id` and correct `type` value
+✓ Each action type only includes its required field(s)
+✓ Bulk delete actions have modal configuration
+✓ Custom bulk actions match implementations in overrides
+✓ At least one of `primaryActions` or `secondaryActions` is provided
+✓ Primary actions use `action`/`menu` structure with proper `action` or `menu` properties
+✓ Secondary actions are an array that can include dividers
+✓ Menu items within primary actions is array that can include dividers
+
+---
+
+# Collection Page Actions
+
+## ⚠️ Required Actions
+
+- **Every collection page must include a create action that navigates to the entity page for adding new entities** - this is essential for user workflow
+
+The `actions` property is an optional object within the `collectionPage` configuration, but it is strongly recommended to always include primaryActions with a create action for better user experience.
+
+## `primaryActions` and `secondaryActions` Structure
+
+Both `primaryActions` and `secondaryActions` are optional and share the same underlying structure for defining how actions are displayed. They can be configured in one of two ways:
+
+### A. Action Layout (`type: "action"`)
+*   **Description**: This layout is used to display a single, prominent page-level action. For example, a "Create New Item" button.
+*   **`action.item`**: Contains the configuration for the single action.
+
+### B. Action Menu Layout (`type: "menu"`)
+*   **Description**: This layout groups several page-level actions, often rendered as a dropdown menu or a set of related buttons under a common label.
+*   **`menu.label`**: A string that serves as the title or accessible label for the group of actions.
+*   **`menu.items`**: A flat array of action configurations, which can include divider objects for visual separation.
+
+## Individual Action Configuration
+
+Each individual action, whether standalone in an `action` layout or part of an `items` array in a `menu` layout, is defined by the action item structure (see `AppConfig Structure`).
+
+In addition to these common properties, each action item must specify a `type` which determines the action's behavior and additional required configuration.
+
+### 1. `type: "create"`
+*   **Purpose**: Navigates to an entity page, allowing the user to create a new item in the specified collection.
+*   **Details**:
+    *   `create.mode`: Must be `'page'`.
+    *   `create.page.id`: Must be the `id` of an existing `entityPage` in your `AppConfig`. This entity page should be set up to handle the creation of new entities for the `collection.collectionId`.
+
+### 2. `type: "custom"`
+*   **Purpose**: Executes custom JavaScript logic defined in your application's overrides.
+*   **Details**:
+    *   The `custom` object in the configuration is typically empty. The functionality is determined by a custom action resolver function that you implement and register in the `actions` section of your `PatternsWizardOverridesProvider`. The `id` of this action item must exactly match the name (key) of the registered custom action resolver. The resolver will receive parameters including `collectionId`.
+
+### 3. `type: "divider"`
+*   **Purpose**: Creates a visual separator between action groups in menus and lists.
+*   **Details**:
+    *   Divider actions require no additional configuration beyond `{ "type": "divider" }`.
+    *   Used within flat arrays to create logical groupings.
+
+## Note on `secondaryActions`
+
+`secondaryActions` follow the exact same structural rules (`type: "action"` or `type: "menu"`) and use the same action item options as `primaryActions`. They are typically used for less prominent or less frequently used page-level actions, often rendered in a secondary position or within a "more options" style menu.
+
+## Custom Collection Page Action Configuration
+
+Custom collection page actions execute JavaScript code that you define for collection-level operations. These actions receive parameters that give them access to collection context and utilities. Here's how to implement a custom collection page action:
+
+1. First, create the actions folder structure in your page folder:
+   ```
+   your-page/
+   ├── page.tsx
+   └── components/
+       └── actions/
+           ├── index.tsx                    // Exports all actions
+           └── exportCollection.tsx        // Your custom collection action
+   ```
+
+2. Create your collection action handler in `exportCollection.tsx`:
+   ```typescript
+   import { CustomActionCollectionPageActionResolver } from '@wix/auto-patterns';
+   import React from 'react';
+   import { Download } from '@wix/ui-icons-common';
+
+   // IMPORTANT: Function name MUST match the action id in your configuration
+   export const exportCollection: CustomActionCollectionPageActionResolver = (params) => {
+     const { actionParams, sdk } = params;
+     const { collectionId } = actionParams;
+
+     return {
+       label: 'Export Collection',
+       icon: <Download />,
+       onClick: () => {
+         // sdk is provided to custom action resolvers (see SDK Utilities section)
+         const optimisticActions = sdk.getOptimisticActions(collectionId);
+         const schema = sdk.getSchema(collectionId);
+
+         // Example: Mark entire collection as exported
+         optimisticActions.updateAll(
+           (item) => ({ lastExported: new Date() }),
+           {
+             submit: async () => {
+               // Your collection export logic here
+               console.log(`Exporting collection: ${collectionId}`);
+               // Export and update all items on server
+               return await schema.actions.bulkUpdate({ lastExported: new Date() });
+             },
+             successToast: 'Collection exported successfully',
+             errorToast: (err, {retry}) => ({
+               text: 'Export failed',
+               action: { text: 'Retry', onClick: retry }
+             })
+           }
+         );
+       },
+     };
+   };
+   ```
+
+3. Export your action in `actions/index.tsx`:
+   ```typescript
+   export * from './exportCollection';
+   ```
+
+4. Configure the action in your JSON configuration:
+   ```json
+   {
+     "id": "exportCollection",        // MUST match the function name exactly
+     "type": "custom",                // REQUIRED: Must be exactly "custom"
+     "label": "Export Collection",    // Optional: Displayed text
+     "collection": {
+       "collectionId": "WixPets",
+       "entityTypeSource": "cms"
+     }
+   }
+   ```
+
+5. Register your action in the `PatternsWizardOverridesProvider`:
+   ```typescript
+   import * as actions from './components/actions';
+
+   <PatternsWizardOverridesProvider value={{ actions }}>
+     <AutoPatternsApp configuration={config as AppConfig} />
+   </PatternsWizardOverridesProvider>
+   ```
+
+## Key Points for Custom Collection Page Actions:
+- The action `id` in the configuration MUST exactly match the function name exported from your actions folder
+- The function name and file name should follow a consistent naming convention (e.g., camelCase)
+- The implementation must be exported as a named export (not default export)
+- The implementation must use the `CustomActionCollectionPageActionResolver` type
+- Access collection context through `actionParams.collectionId`
+
+---
+
+## Custom Row Click Actions
+
+In addition to page-level actions, you can also customize what happens when users click on individual rows in your collection table. By default, clicking a row navigates to the entity page, but you can override this behavior with custom logic.
+
+**Before You Start:**
+- Only configure `onRowClick` if you need custom behavior (e.g., opening modals, side panels, custom actions)
+- If you just want navigation to entity page, don't configure `onRowClick` - it's the default behavior
+- Once you configure `onRowClick`, you must provide a complete working implementation
+
+### Configuration
+
+Row click actions are configured at the table level using the `onRowClick` property:
+
+```json
+{
+  "type": "Table",
+  "table": {
+    "columns": [...],
+    "onRowClick": {
+      "id": "handleRowClick",        // MUST match the function name exactly
+      "type": "custom",              // REQUIRED: Must be exactly "custom"
+    }
+  }
+}
+```
+
+### Implementation Requirements
+
+⚠️ **CRITICAL**: When you configure `onRowClick` in your JSON, you MUST provide a complete working implementation. The Auto Patterns framework cannot function without it.
+
+Custom row click actions use the `CustomActionCollectionPageActionOnRowClickResolver` type and MUST return a `ResolvedAction` object with all required properties:
+
+#### Required Return Object Structure:
+```typescript
+return {
+  label: string,        // REQUIRED: Action label
+  icon: ReactElement,   // REQUIRED: Icon component
+  onClick: () => void   // REQUIRED: Click handler function
+};
+```
+
+#### Complete Implementation Example:
+
+```typescript
+import { CustomActionCollectionPageActionOnRowClickResolver } from '@wix/auto-patterns';
+import React from 'react';
+import { More } from '@wix/wix-ui-icons-common';
+
+// IMPORTANT: Function name MUST match the action id in your configuration
+export const handleRowClick: CustomActionCollectionPageActionOnRowClickResolver = (params) => {
+  const { actionParams, sdk } = params;
+  const { item } = actionParams; // The clicked row's data
+
+  return {
+    label: 'View Details',           // REQUIRED
+    icon: <More />,                  // REQUIRED
+    onClick: () => {                 // REQUIRED
+      // Your custom row click logic here
+      console.log('Row clicked:', item);
+
+      // Example: Show a custom modal, perform an action, etc.
+      // You can access all SDK utilities here (see SDK Utilities section)
+      const optimisticActions = sdk.getOptimisticActions(sdk.collectionId);
+      const schema = sdk.getSchema(sdk.collectionId);
+
+      // Your custom logic...
+    },
+  };
+};
+```
+
+### Common Use Cases and Complete Examples
+
+#### 1. Opening a Side Panel Modal
+
+This is a complete working example for opening a side panel when clicking a row:
+
+**Step 1: Create the row click action** (`components/actions/openSidePanel.tsx`):
+```typescript
+import { CustomActionCollectionPageActionOnRowClickResolver } from '@wix/auto-patterns';
+import React from 'react';
+import { More } from '@wix/wix-ui-icons-common';
+
+export const openSidePanel: CustomActionCollectionPageActionOnRowClickResolver = (params) => {
+  const { actionParams, sdk } = params;
+  const { item } = actionParams;
+
+  return {
+    label: 'View Details',
+    icon: <More />,
+    onClick: () => {
+      // Open a custom modal with the item data
+      // You need to implement the modal opening mechanism
+      // This could be through a modal context, state management, etc.
+      console.log('Opening side panel for:', item);
+
+      // Example: Using a global modal state (you need to implement this)
+      // window.dispatchEvent(new CustomEvent('openSidePanel', { detail: item }));
+
+      // Or use a modal service/context that you've set up
+      // modalService.openSidePanel(item);
+    },
+  };
+};
+```
+
+**Step 2: Configure in JSON**:
+```json
+{
+  "type": "Table",
+  "table": {
+    "onRowClick": {
+      "id": "openSidePanel",
+      "type": "custom"
+    },
+    "columns": [...]
+  }
+}
+```
+
+**Step 3: Export and Register**:
+```typescript
+// components/actions/index.tsx
+export * from './openSidePanel';
+
+// page.tsx
+import * as actions from './components/actions';
+
+<PatternsWizardOverridesProvider value={{ actions }}>
+  <AutoPatternsApp configuration={config as AppConfig} />
+</PatternsWizardOverridesProvider>
+```
+
+#### 2. Direct Data Manipulation
+
+```typescript
+export const quickToggle: CustomActionCollectionPageActionOnRowClickResolver = (params) => {
+  const { actionParams, sdk } = params;
+  const { item } = actionParams;
+
+  return {
+    label: 'Quick Toggle',
+    icon: <Toggle />,
+    onClick: () => {
+      const optimisticActions = sdk.getOptimisticActions(sdk.collectionId);
+      const schema = sdk.getSchema(sdk.collectionId);
+
+      // Example: Toggle a boolean field
+      const updatedItem = { ...item, isActive: !item.isActive };
+
+      optimisticActions.updateOne(updatedItem, {
+        submit: async (items) => schema.actions.update(items[0]),
+        successToast: `${item.name} toggled successfully`,
+        errorToast: (err, {retry}) => ({
+          text: 'Toggle failed',
+          action: { text: 'Retry', onClick: retry }
+        })
+      });
+    },
+  };
+};
+```
+
+### Default vs Custom Behavior
+
+**Default Behavior (when `onRowClick` is not configured):**
+- Clicking a row automatically navigates to the entity page
+- Uses the `entityPageId` configuration to determine the target page
+- Passes the selected item's data to the entity page
+
+**Custom Behavior (when `onRowClick` is configured):**
+- Default navigation is **disabled**
+- Your custom action function is executed instead
+- You have complete control over the row click behavior
+- You can still navigate to the entity page programmatically if needed using the SDK navigation utilities
+
+### Key Points for Custom Row Click Actions:
+- **MANDATORY IMPLEMENTATION**: If you configure `onRowClick` in JSON, you MUST provide a complete working implementation - the framework cannot function without it
+- The action `id` in the configuration MUST exactly match the function name exported from your actions folder
+- The implementation must use the `CustomActionCollectionPageActionOnRowClickResolver` type
+- **Required Return Object**: Must return an object with `label`, `icon`, and `onClick` properties - all are required
+- Access the clicked item's data through `actionParams.item`
+- The implementation must be exported as a named export and registered in your `PatternsWizardOverridesProvider`
+- When `onRowClick` is configured, the default navigation to entity page is completely disabled
+- **Complete Setup Required**: You need to create the action file, export it in the index, and register it in the provider - missing any step will cause errors
+
+## Validation Checklist for Collection Page Actions
+
+✓ Every collection page must include a create action.
+✓ `actions` is an optional property of `collectionPage`.
+✓ `primaryActions` and `secondaryActions` (if defined) have a valid `type` ("action" or "menu").
+✓ If `type: "action"`, `action.item` is a valid action item configuration.
+✓ If `type: "menu"`, `menu.items` is an array of valid action item configurations that can include dividers.
+✓ Each action item contains a unique `id`, and the full `collection` object (`collectionId`, `entityTypeSource: 'cms'`).
+✓ Each action item has a supported `type` (`create`, `custom`) and its corresponding configuration block (e.g., `create` block for `type: "create"`).
+✓ `create` actions specify a `create.page.id` that matches an existing `entityPage` ID in the configuration.
+✓ `custom` actions (identified by their main `id`) correspond to an action resolver function name registered in the `actions` override.
+✓ Divider actions use `{ "type": "divider" }` format and require no additional properties.
+✓ If `onRowClick` is configured in table layout, it must have a valid `id` and `type: "custom"`.
+✓ **CRITICAL**: Custom row click actions must have corresponding implementations registered in the `actions` override - configuration without implementation will cause errors.
+✓ Custom row click action implementations must return an object with `label`, `icon`, and `onClick` properties - all are required.
+✓ Custom row click action implementations must be exported as named exports and included in the actions index file.
+✓ `onRowClick` is optional - when not configured, rows navigate to entity page by default.
+✓ **IMPORTANT**: Configuring `onRowClick` completely disables default navigation - you must handle all row click logic in your custom implementation.
+
+---
+
+## SDK Utilities
+
+The `sdk` parameter provides access to Auto Patterns utilities and context. Available in custom actions across all action types (ActionCell, BulkActions, CollectionPage actions, and EntityPage Actions).
+
+### Key SDK Utilities
+The only functions exist in sdk are:
+
+• **closeModal** - `closeModal(): void`
+  - Closes the currently open modal
+  - Example: `sdk.closeModal()` after saving or canceling
+
+• **getOptimisticActions** - `getOptimisticActions(collectionId): OptimisticActions`
+  - Provides optimistic UI updates for immediate user feedback
+  - Supports create, update, delete operations with automatic rollback on failure
+  - Example: `sdk.getOptimisticActions(sdk.collectionId).updateOne(item, { ... })`
+
+• **getSchema** - `getSchema(collectionId): SchemaConfig | undefined`
+  - Access to collection schema information (fields, types, validation)
+  - Useful for dynamic operations based on collection structure
+  - Example: `const schema = sdk.getSchema(sdk.collectionId)`
+
+• **collectionId** - `string`
+  - Current collection context identifier
+  - Available in all action contexts for referencing the active collection
+  - Example: `sdk.collectionId` to get the current collection ID
+
+---
+
+## OptimisticActions
+
+Provides immediate UI updates with automatic server synchronization and error recovery.
+
+### Usage Rules
+
+**Use OptimisticActions for:**
+- Data modification operations (create, update, delete)
+- Operations requiring immediate visual feedback
+
+**Do NOT use for:**
+- Read-only operations
+- Operations requiring server confirmation first
+
+### Core Pattern
+
+```typescript
+// Get instances from SDK (see SDK Utilities section)
+const optimisticActions = sdk.getOptimisticActions(sdk.collectionId);
+const schema = sdk.getSchema(sdk.collectionId);
+
+optimisticActions.operation(items, {
+  submit: async (items) => schema.actions.serverMethod(items),
+  successToast: 'Success message',
+  errorToast: (err, {retry}) => ({ text: 'Error message', action: { text: 'Retry', onClick: retry }})
+});
+```
+
+### Available Operations
+
+#### Create Operations
+- `createOne(item: T, params: OptimisticParams<T>): void`
+- `createMany(items: T[], params: OptimisticParams<T>): void`
+
+#### Update Operations
+- `updateOne(item: T, params: OptimisticParams<T>): void`
+- `updateMany(items: T[], params: OptimisticParams<T>): void`
+- `updateAll(transformFn: (item: T) => Partial<T>, params: OptimisticParams<T>): void`
+
+#### Delete Operations
+- `deleteOne(item: T, params: OptimisticParams<T> & { showUndoToast: true }): void`
+- `deleteMany(items: T[], params: OptimisticParams<T> & { showUndoToast: true }): void`
+- `deleteAll(params: OptimisticParams<T> & { showUndoToast: true }): void`
+
+### Type Definitions
+
+```typescript
+interface OptimisticParams<T> {
+  submit: (items: T[]) => Promise<any>;
+  successToast: string | ToastConfig;
+  errorToast: (error: Error, actions: { retry: () => void }) => ToastConfig | string;
+  showUndoToast?: boolean; // Required: true for delete operations
+}
+
+interface ToastConfig {
+  text: string;
+  action?: { text: string; onClick: () => void };
+}
+```
+
+### Validation Requirements
+
+**Before using optimistic actions:**
+- Verify `sdk.getOptimisticActions(collectionId)` returns valid instance
+- Verify `sdk.getSchema(collectionId)` returns valid schema
+- For delete operations: `showUndoToast: true` is mandatory
+- All `submit` functions must return a Promise
+
+**SDK Parameter:** Available in custom actions and modals. See SDK Utilities section for complete interface.
+
+---
+
+## SchemaConfig Usage
+
+SchemaConfig provides complete collection metadata and server actions. Essential for dynamic operations and accessing collection structure information.
+
+### Key Properties
+
+• **id** - `string`
+  - Collection identifier (e.g., "WixPets")
+  - Example: `schema.id === "WixPets"`
+
+• **idField** - `string`
+  - Primary key field name (usually "_id")
+  - Required for all update/delete operations
+  - Example: `const id = item[schema.idField]`
+
+• **displayField** - `string`
+  - Main field for displaying items (name, title, etc.)
+  - Used in UI components for item identification
+  - Example: `const label = item[schema.displayField]`
+
+• **fields** - `Record<string, Field | undefined>`
+  - Complete field definitions with types and metadata
+  - Useful for dynamic form generation or validation
+  - Example: `schema.fields.name.type === 'TEXT'`
+
+• **actions** - Server operation functions
+  - Pre-configured API calls for CRUD operations
+  - Use with optimistic actions for best UX
+  - Example: `await schema.actions.update(item)`
+
+### Available Schema Actions
+
+- schema.actions.create(item)        // Create single item
+- schema.actions.update(item)        // Update single item
+- schema.actions.delete(itemId)      // Delete by ID
+- schema.actions.bulkUpdate(updates) // Update multiple items
+- schema.actions.bulkDelete(itemIds) // Delete multiple items
+
+### Schema Validation Checklist
+
+Before using schema in operations:
+
+✓ Check if schema exists: `if (!schema) return;`
+✓ Verify required fields exist on items
+✓ Use `schema.idField` for ID operations
+✓ Use `schema.displayField` for UI display
+✓ Use `schema.actions` for server operations
+
+### Common Usage Patterns
+
+- **ActionCell**: Use `schema.actions.update()` or `schema.actions.delete()` for single item operations
+- **BulkActions**: Use `schema.actions.bulkUpdate()` or `schema.actions.bulkDelete()` for multiple items
+- **Dynamic UI**: Use `schema.fields` to build forms or validate data
+- **Error Messages**: Use `schema.displayField` to create meaningful user feedback
+
+---
+
+## Filters Configuration Notes
+
+To configure filters in a `collectionPage`, add a `filters` property inside the page's component configuration object. Each filter must reference a valid field by its `fieldId`, and the supported types are:
+
+* `numberConfig`: used with fields of type `NUMBER`
+* `dateConfig`: used with fields of type `DATETIME`
+* `booleanConfig`: used with fields of type `BOOLEAN`
+* `enumConfig`: used with fields of type `ARRAY` or `ARRAY_STRING`
+
+### Enum Configuration Implementation
+
+When implementing enum filters, you must ask the user to provide the possible option values. Never invent or assume enum values. Here's how to properly handle enumConfig:
+
+#### Example: User-Provided Enum Implementation
+
+1. First, collect the possible values from the user:
+   ```
+   User requests: "I need a filter for pet types."
+   You ask: "What are the possible values for pet types that should be available in the filter?"
+   User responds: "dog, cat, bird, rabbit, fish"
+   ```
+
+2. Then, create the `enumConfig` structure:
+   ```json
+   "enumConfig": {
+     "options": [
+       { "value": "dog", "label": "Dog" },
+       { "value": "cat", "label": "Cat" },
+       { "value": "bird", "label": "Bird" },
+       { "value": "rabbit", "label": "Rabbit" },
+       { "value": "fish", "label": "Fish" }
+     ],
+     "selectionMode": "multiple",
+     "optionType": "checkbox"
+   }
+   ```
+
+Notice how the `label` is derived from the `value` by capitalizing the first letter. The user's exact values become the `value` property.
+
+### Grouping Filters with Section Title
+
+* Filters can be grouped by sections using the `sectionTitle` property.
+* If multiple filter items share the same `sectionTitle`, they will be displayed together in a grouped section in the UI.
+* Filters without a `sectionTitle` will appear in a default section or be displayed individually.
+* Grouping helps maintain clarity, especially when dealing with multiple filter options.
+
+### Key Guidelines
+
+* **openByDefault**: Automatically expands the filter accordion when the filters panel is opened.
+* **tagLabel**: Specifies the label displayed in a Tag component on the table or grid once the filter is active. For example, if the tagLabel is "Age", the filter display might show: `Age: 7`.
+* **maxInlineFilters**: Limits the number of filters shown inline in the table toolbar. Others are accessible via the panel. Default is 0.
+* **dateConfig.mode**:
+
+  * `ONLY_PREDEFINED`: user can select only from preset options
+  * `ONLY_CUSTOM`: user must select a custom date range manually (no presets)
+  * `COMBINE`: both options available
+* **dateConfig.presets** must be omitted if mode is `ONLY_CUSTOM`.
+* **dateConfig.includeTime**: Controls whether time selection is also enabled alongside date (default is `true`).
+
+---
+
+# Custom Overrides
+
+## ⚠️ Override Rules
+
+- **Custom overrides are restricted to the defined areas only** - attempting to override or modify any other aspect of `AutoPatternsApp` is prohibited and can cause unexpected behavior
+- **Always verify override implementation** - when implementing custom overrides, you MUST ensure they are correctly imported and passed to the `PatternsWizardOverridesProvider`
+
+The `PatternsWizardOverridesProvider` allows you to inject custom code to override default behaviors or add additional functionality. Below are the areas where overrides can be applied:
+
+> **Note:** These are the only areas where overrides are supported. Avoid attempting to override or modify other parts of the system, as this is not supported and may lead to unexpected behavior.
+
+## Folder Structure Organization
+
+All custom overrides (components, modals, actions, columns, and other customizations) should be created in a `components` folder inside your page directory, not in a global `/src/components` folder. This keeps page-specific customizations organized alongside their respective pages.
+
+### Recommended Structure:
+
+```
+your-page/
+├── page.tsx                           // Your main page component
+├── MyCollectionConfig.patterns.json   // Configuration file
+└── components/                        // Page-specific components folder
+    ├── index.tsx                       // Exports all overrides for easy importing
+    ├── actions/                       // Custom actions
+    │   ├── index.tsx
+    │   └── myCustomAction.tsx
+    ├── columns/                       // Column overrides
+    │   ├── index.tsx
+    │   ├── name.ts
+    │   └── date.ts
+    └── customComponents/              // Custom entity page components
+        ├── index.tsx
+        ├── CustomNameField.tsx
+        └── InfoCard.tsx
+```
+
+### Importing Overrides in Your Page
+
+In your page component, import from the local components folder:
+
+```tsx
+import * as modals from './components/modals';
+import * as actions from './components/actions';
+import * as columns from './components/columns';
+import * as components from './components/customComponents';
+
+<PatternsWizardOverridesProvider value={{ modals, actions, columns, components }}>
+  <AutoPatternsApp configuration={config as AppConfig} />
+</PatternsWizardOverridesProvider>
+```
+
+### Important: Updating Index Files
+
+**When adding any new implementation (action, modal, column, or component), you MUST update the corresponding `index.tsx` file to export your new implementation.** The main page component imports from these index files, so they serve as the central export point for each type of override.
+
+For example:
+- Adding a new action → Update `./components/actions/index.tsx`
+- Adding a new modal → Update `./components/modals/index.tsx`
+- Adding a new column override → Update `./components/columns/index.tsx`
+- Adding a new custom component → Update `./components/customComponents/index.tsx`
+
+Without updating the index files, your implementations won't be available to the `PatternsWizardOverridesProvider`.
+
+## ⚠️ Common Override Mistakes to Avoid
+
+- Attempting to override unsupported areas
+- Invalid column rendering functions
+- Missing index file exports for new implementations
+- Incorrect import paths or naming mismatches
+
+## Columns
+
+Each column in the table has a default rendering based on its field type. You can override this rendering by providing a custom function for the `column.id`. This allows you to customize how specific columns are displayed.
+
+**Enhanced Column Overrides**: Column override can receive both the individual column `value` and the entire `row` data, enabling you to create complex columns that combine multiple field values from the same row.
+
+### Function Signature
+
+```typescript
+function columnOverride({ value, row }) {
+  // value: The individual column value
+  // row: The entire row object containing all field values
+  return <YourCustomRendering />;
+}
+```
+
+### Understanding Row Data
+
+**Important**: The `row` object contains all field values from the entity, where each property corresponds to a **field ID** from the collection schema. To access specific field values, use the exact field ID as defined in your collection schema.
+
+For example, if your collection schema has these fields:
+```json
+{
+  "fields": [
+    { "key": "name", "displayName": "Pet Name", "type": "TEXT" },
+    { "key": "age", "displayName": "Age", "type": "NUMBER" },
+    { "key": "isVaccinated", "displayName": "Vaccinated", "type": "BOOLEAN" },
+    { "key": "lastActivity", "displayName": "Last Activity", "type": "DATETIME" }
+  ]
+}
+```
+
+Then in your column override, you access these values using the field IDs:
+```typescript
+export function myColumn({ value, row }) {
+  // Access field values using their schema field IDs
+  const petName = row.name;           // "name" field ID
+  const petAge = row.age;             // "age" field ID
+  const isVaccinated = row.isVaccinated; // "isVaccinated" field ID
+  const lastActivity = row.lastActivity; // "lastActivity" field ID
+
+  return <YourCustomRendering />;
+}
+```
+
+### Use Cases for Row Data Access
+
+1. **Complex Display Columns**: Combine multiple fields into a single display (e.g., "Name (Age)" combining name and age fields)
+2. **Conditional Rendering**: Show different content based on other field values in the same row
+3. **Calculated Columns**: Create computed values using multiple row fields
+4. **Cross-Field Validation Display**: Show validation status based on relationships between fields
+
+### Example: Defining and Using Column Overrides
+
+In `components/columns/name.tsx`:
+
+```ts
+import React from 'react';
+
+export function name({ value, row }) {
+  // Simple value formatting
+  return <strong>{value}</strong>;
+}
+```
+
+In `components/columns/petInfo.tsx`:
+
+```ts
+import React from 'react';
+import { Box, Text } from '@wix/design-system';
+
+export function petInfo({ value, row }) {
+  // Complex column combining multiple row values
+  return (
+    <Box direction="vertical" gap={1}>
+      <Text weight="bold">{row.name}</Text>
+      <Text size="small" skin="disabled">
+        {row.age} years old • {row.type}
+      </Text>
+      {row.isVaccinated && (
+        <Text size="tiny" skin="success">✓ Vaccinated</Text>
+      )}
+    </Box>
+  );
+}
+```
+
+In `components/columns/status.tsx`:
+
+```ts
+import React from 'react';
+import { Badge } from '@wix/design-system';
+
+export function status({ value, row }) {
+  // Conditional rendering based on multiple row fields
+  if (row.isVaccinated && row.age > 1) {
+    return <Badge skin="success">Ready for Adoption</Badge>;
+  } else if (!row.isVaccinated) {
+    return <Badge skin="warning">Needs Vaccination</Badge>;
+  } else {
+    return <Badge skin="neutral">Too Young</Badge>;
+  }
+}
+```
+
+In `components/columns/fullName.tsx`:
+
+```ts
+import React from 'react';
+
+export function fullName({ value, row }) {
+  // Calculated column using multiple fields
+  return `${row.name} (owned by ${row.owner})`;
+}
+```
+
+In `components/columns/date.tsx`:
+
+```ts
+import React from 'react';
+
+export function date({ value, row }) {
+  // Access to other row data for enhanced date formatting
+  const isRecent = row.lastActivity && new Date(row.lastActivity) > new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+
+  return (
+    <span style={{ color: isRecent ? 'green' : 'inherit' }}>
+      <em>{new Date(value).toLocaleDateString()}</em>
+      {isRecent && ' (Recent)'}
+    </span>
+  );
+}
+```
+
+In `components/columns/index.tsx`:
+
+```ts
+export * from './name';
+export * from './petInfo';
+export * from './status';
+export * from './fullName';
+export * from './date';
+```
+
+**Important:** Every time you add a new column override file, you must add a corresponding export line to this `index.tsx` file. For example, if you create `price.tsx`, you must add `export * from './price';` to the index file.
+
+In the `PatternsWizardOverridesProvider`:
+
+```tsx
+import * as columns from './components/columns';
+
+<PatternsWizardOverridesProvider value={{ columns }}>
+  <AutoPatternsApp configuration={config as AppConfig} />
+</PatternsWizardOverridesProvider>
+```
+
+### Visual Representation
+
+```
+your-page/
+└── components/
+    └── columns/
+        ├── index.tsx     // Exports all column overrides
+        ├── name.tsx      // Simple value formatting
+        ├── petInfo.tsx   // Complex multi-field column
+        ├── status.tsx    // Conditional rendering column
+        ├── fullName.tsx  // Calculated column
+        └── date.tsx      // Enhanced formatting with row context
+
+PatternsWizardOverridesProvider
+ └── value.columns
+      ├── name
+      ├── petInfo
+      ├── status
+      ├── fullName
+      └── date
+```
+
+### Key Benefits of Row Data Access
+
+1. **Reduced Configuration Complexity**: Instead of adding multiple columns, create one complex column that shows related information
+2. **Better User Experience**: Present related data together in a logical, readable format
+3. **Dynamic Content**: Show different content based on the state of other fields
+4. **Data Relationships**: Highlight relationships between different field values in the same entity
+
+### Important Guidelines
+
+- **Performance**: Remember that column functions are called for every row, so keep calculations lightweight
+- **Consistency**: When using row data, ensure the column header accurately represents what's displayed
+- **Accessibility**: Maintain proper semantic structure when combining multiple values
+
+## Components
+
+Components allow you to create custom rendering for specific elements in the entity page. Each component has a unique `componentId` that corresponds to the ID specified in the layout configuration.
+
+The custom components receive two essential props:
+
+1. **form**: An instance of `UseFormReturn` from react-hook-form (re-exported through `@wix/auto-patterns/form`), giving you access to the form control, methods, and state.
+2. **entity**: A key-value object where keys are field IDs from the collection schema and values are the current field values, providing access to the entity's data.
+
+Custom components can serve two main purposes:
+
+### 1. Standalone Custom Components
+
+These components can display custom UI elements like notifications, information cards, or any other custom content that isn't directly tied to specific fields. These are useful for adding unique UI elements that enhance the entity page experience.
+
+### 2. Field Rendering Overrides
+
+You can use custom components to override the default rendering of one or more fields. This allows you to:
+- Apply custom validation logic
+- Create custom input components
+- Combine multiple fields into a single UI component
+- Add field-specific functionality not available in the default renderers
+
+### Using the useController Hook for Field Overrides
+
+When creating field overrides, use the `useController` hook from `@wix/auto-patterns/form` (a re-export of react-hook-form's hook) to connect your custom component to the form state:
+
+```tsx
+import { useController } from '@wix/auto-patterns/form'; // Always import from this path, not react-hook-form
+```
+
+The hook requires:
+- **name**: The field name you want to edit (should match the schema field ID)
+- **control**: Retrieved from `form.control`
+- **defaultValue**: Set from `entity?.[fieldId]` when it exists
+
+### Example: Defining a Custom Component
+
+Here's an example of a custom component that overrides the rendering of the "name" field:
+
+```tsx
+import React, { FC } from 'react';
+import { Box, Card, FormField, Input, Text } from '@wix/design-system';
+import { useController } from '@wix/auto-patterns/form';
+import { CustomComponentProps } from '@wix/auto-patterns/types';
+
+export const customNameField: FC<CustomComponentProps> = ({ form, entity }) => {
+  // Create a controller for the name field
+  const controller = useController({
+    name: 'name', // Field ID from the schema
+    control: form.control, // Form control
+    defaultValue: entity?.name, // Default value from entity
+  });
+
+  return (
+    <FormField
+      label="Name"
+      required={true}
+      charCount={100}
+      // Connect field state to UI
+      status={controller.fieldState.invalid ? 'error' : undefined}
+      statusMessage={controller.fieldState.error?.message}
+      dataHook={`short-text-${controller.field.name}`}
+    >
+      <Input
+        // Connect field value and onChange
+        value={controller.field.value}
+        onChange={(e) => controller.field.onChange(e.target.value)}
+        dataHook={`short-text-${controller.field.name}`}
+      />
+    </FormField>
+  );
+};
+```
+
+
+### Example: Standalone Component (Not Field-Specific)
+
+Custom components can also be used to add UI elements not tied to specific fields:
+
+```tsx
+import React, { FC } from 'react';
+import { Box, Card, Text, Button } from '@wix/design-system';
+import { CustomComponentProps } from '@wix/auto-patterns/types';
+
+export const infoCard: FC<CustomComponentProps> = ({ entity }) => {
+  return (
+    <Card>
+      <Card.Content>
+        <Box direction="vertical" gap={2}>
+          <Text weight="bold">Important Information</Text>
+          <Text>
+            This custom component can display additional information or functionality
+            that isn't directly tied to a specific field.
+          </Text>
+          {entity?.isVaccinated ? (
+            <Text skin="success">This pet is vaccinated</Text>
+          ) : (
+            <Text skin="warning">This pet needs vaccination</Text>
+          )}
+        </Box>
+      </Card.Content>
+    </Card>
+  );
+};
+```
+
+### Connecting Components in the Provider
+
+In your main page file, import and provide these components via the `PatternsWizardOverridesProvider`:
+
+```tsx
+import * as components from './components';
+
+<PatternsWizardOverridesProvider value={{ components }}>
+  <AutoPatternsApp configuration={config as AppConfig} />
+</PatternsWizardOverridesProvider>
+```
+
+### Important Guidelines for Custom Components
+
+1. **Always import from `@wix/auto-patterns/form`** instead of directly from `react-hook-form`
+2. **Follow react-hook-form best practices** - the underlying infrastructure is built on react-hook-form
+3. **Handle form state properly**:
+   - Use `controller.fieldState.invalid` for error state
+   - Use `controller.fieldState.error?.message` for error messages
+   - Connect `controller.field.value` to input values
+   - Use `controller.field.onChange` for change handlers
+4. **Component rendering**:
+   - Choose appropriate design-system components based on the field type
+   - For text fields: `Input`
+   - For multi-line text: `InputArea`
+   - For checkboxes: `Checkbox`
+   - For dates: `DatePicker`
+   - For dropdowns: `Dropdown`
+
+**Important:** Every time you create a new custom component, you must add a corresponding export line to the `./components/customComponents/index.tsx` file. For example, if you create `StatusIndicator.tsx`, you must add `export * from './StatusIndicator';` to the index file.
+
+### Understanding Reactivity in Custom Components
+
+5. **Reactivity and field value changes (IMPORTANT)**:
+   - **NEVER rely on the `entity` object for reactive UI** - it is not reactive to form changes
+   - For any reactive UI that needs to respond to field value changes in real-time:
+     - Use `form.watch('fieldName')` to observe field changes reactively
+     - Use `useController` hook when you need both read and write access to a field
+
+#### Common Reactivity Issues and Solutions
+
+##### Example: Conditional Display Based on Field Value
+
+```tsx
+// ❌ INCORRECT APPROACH (Non-reactive)
+const CustomComponent: FC<CustomComponentProps> = ({ form, entity }) => {
+  // This won't update when the user changes the name in the form
+  const showSpecialMessage = entity?.name === 'special';
+
+  return (
+    <Box>
+      <Input
+        value={form.getValues('name')}
+        onChange={(e) => form.setValue('name', e.target.value)}
+      />
+
+      {showSpecialMessage && (
+        <Text>Special message for special name!</Text>
+      )}
+    </Box>
+  );
+};
+```
+
+```tsx
+// ✅ CORRECT APPROACH (Reactive)
+const CustomComponent: FC<CustomComponentProps> = ({ form, entity }) => {
+  // This WILL update whenever the name field changes
+  const nameValue = form.watch('name');
+  const showSpecialMessage = nameValue === 'special';
+
+  return (
+    <Box>
+      <Input
+        value={nameValue}
+        onChange={(e) => form.setValue('name', e.target.value)}
+      />
+
+      {showSpecialMessage && (
+        <Text>Special message for special name!</Text>
+      )}
+    </Box>
+  );
+};
+```
+
+
+##### When to Use the Entity Object
+
+The `entity` object is useful for:
+- Setting initial values
+- Accessing read-only data that doesn't change
+- Comparing form state with original values (e.g., detecting if changes were made)
+- Initializing form fields with useController's defaultValue parameter
+
+```tsx
+// Example: Proper use of entity object with useController
+const CustomComponent: FC<CustomComponentProps> = ({ form, entity }) => {
+  // Use entity for initialization via defaultValue
+  const controller = useController({
+    name: 'name', // Field ID from the schema
+    control: form.control,
+    defaultValue: entity?.name // Initialize from entity
+  });
+
+  // Use watch for reactive updates
+  const currentName = controller.field.value;
+  const hasChanges = entity?.name !== currentName;
+
+  return (
+    <Box>
+      <FormField label="Name">
+        <Input
+          value={currentName}
+          onChange={(e) => controller.field.onChange(e.target.value)}
+        />
+      </FormField>
+      {hasChanges && (
+        <Text size="small">Original value: {entity?.name}</Text>
+      )}
+    </Box>
+  );
+};
+```
+
+### Visual Representation
+
+```
+your-page/
+└── components/
+    ├── index.tsx              // Exports all component overrides
+    ├── customNameField.tsx   // Field override component
+    ├── combinedNameFields.tsx // Multiple fields override
+    └── infoCard.tsx          // Standalone component
+
+PatternsWizardOverridesProvider
+ └── value.components
+      ├── customNameField
+      ├── combinedNameFields
+      └── infoCard
+```
+
+By using these component overrides, you can tailor the behavior and appearance of your `AutoPatternsApp` to meet specific requirements beyond what the default rendering provides.
+
+---