@wix/auto-patterns 1.14.0 → 1.16.0

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

@@ -0,0 +1,786 @@
+# Recipe 2: Adding CRUD Operations to Your Dashboard
+
+**Use Case**: "I have a basic dashboard but need to add Create, Edit, Delete functionality"
+
+---
+
+## 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`).
+
+---
+
+# 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.
+
+---
+
+## ActionCell Configuration
+
+The ActionCell feature adds an interactive action column to collection tables or grid views, enabling users to perform operations on individual entities.
+
+### Placement and Structure
+
+The ActionCell has a two-level structure:
+* `primaryAction`: A single prominent action shown directly in the table/grid row
+* `secondaryActions`: Additional actions shown in a dropdown menu
+
+Both properties are optional, but at least one should be provided for the ActionCell to be useful.
+
+### Inline Secondary Actions
+
+**New Feature**: By default, all secondary actions are hidden in a popover menu that appears when the user hovers over or clicks the "more actions" button. However, you can now configure some secondary actions to display inline directly in the table row for improved accessibility and reduced clicks.
+
+### Action Types Reference
+
+1. **Update Action** (`type: "update"`):
+   - ✓ Use when: Editing entity fields or navigating to a detailed edit page
+   - ✓ Common scenarios:
+     - Full entity editing (use page mode)
+   - ✓ Built-in functionality: No custom implementation needed
+
+2. **Delete Action** (`type: "delete"`):
+   - ✓ Use when: Removing entities with confirmation
+   - ✓ Common scenarios:
+     - Deleting records with confirmation
+     - Soft-delete with status update
+   - ✓ Built-in functionality: No custom implementation needed
+
+3. **Custom Action** (`type: "custom"`):
+   - ✓ Use when: Executing custom JavaScript without UI
+   - ✓ Common scenarios:
+     - API calls
+     - Browser interactions (alerts, downloads)
+     - Complex operations
+   - ⚠️ Requires implementation: Must register action in overrides
+
+### Type Selection Decision Tree
+
+When choosing an action type, follow this decision process:
+
+1. IF editing entity fields:
+   → Use `type: "update"`
+   a. IF complex edits → Use `mode: "page"`
+
+2. IF removing entities:
+   → Use `type: "delete"`
+
+3. IF executing custom logic without UI:
+   → Use `type: "custom"`
+   - MUST implement action handler
+   - MUST register with `actions` override
+
+### Update Action Configuration
+
+Update actions edit entities by navigating to an entity page.
+
+#### Validation Rules:
+
+1. If `update.mode` is `"page"`:
+   - `update.page` must exist
+   - `update.page.id` must match an entity page ID in the configuration
+
+### Delete Action Configuration
+
+Delete actions remove entities with a confirmation modal.
+
+#### Validation Rules:
+
+1. `delete.mode` must be `"modal"` (currently only modal is supported)
+2. `delete.modal` object must exist
+3. The modal properties (title, description, actions, feedback) are all optional
+
+### Custom Action Configuration
+
+Custom actions execute JavaScript code that you define. These actions receive parameters that give them access to entity data and utilities. Here's how to implement a custom action:
+
+1. First, create the actions folder structure in your page folder:
+   ```
+   your-page/
+   ├── page.tsx
+   └── components/
+       └── actions/
+           ├── index.tsx                    // Exports all actions
+           └── downloadPetDetails.tsx       // Your custom action (name = action id)
+   ```
+
+2. Create your action handler in `downloadPetDetails.tsx` (note: the filename and function name MUST match your action id):
+   ```typescript
+   import { CustomActionCellActionResolver } 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 downloadPetDetails: CustomActionCellActionResolver = (params) => {
+     const { actionParams, sdk } = params;
+     const { item } = actionParams;
+
+     return {
+       label: 'Download Details',
+       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 pet as downloaded
+         const updatedItem = { ...item, lastDownloaded: new Date() };
+         optimisticActions.updateOne(updatedItem, {
+           submit: async (items) => {
+             // Your download logic here + update server
+             return await schema.actions.update(items[0]);
+           },
+           successToast: 'Pet details downloaded',
+           errorToast: (err, {retry}) => ({
+             text: 'Download failed',
+             action: { text: 'Retry', onClick: retry }
+           })
+         });
+       },
+     };
+   };
+   ```
+
+3. Export your action in `actions/index.tsx`:
+   ```typescript
+   export * from './downloadPetDetails';
+   ```
+
+   **Important:** Every time you create a new action, you must add a corresponding export line to this `index.tsx` file. For example, if you create `sendEmail.tsx`, you must add `export * from './sendEmail';` to the index file.
+
+4. Configure the action in your JSON configuration:
+   ```ts
+   {
+     "id": "downloadPetDetails",        // MUST match the function name exactly
+     "type": "custom",                  // REQUIRED: Must be exactly "custom"
+     "label": "Download Details",       // 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 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 `CustomActionCellActionResolver` type
+
+#### Validation Rules for Custom Actions:
+
+1. `id` must:
+   - Match exactly the function name of the custom 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 action
+
+3. The implementation must:
+   - Use the correct type: `CustomActionCellActionResolver`
+   - Be exported as a named export
+   - Have a filename matching the function name
+
+### Key Implementation Decisions
+
+Follow this decision process when implementing ActionCell:
+
+1. **Basic Decision**: Decide which actions users need to perform on entities:
+   - Edit entities? → Use `update` actions
+   - Delete entities? → Use `delete` actions
+   - Custom operations? → Use `custom` actions
+
+2. **Primary vs Secondary**: Choose the most common/important action as primary:
+   - Most common operation (typically Edit) → Place in `primaryAction.item`
+   - Less common operations → Place in `secondaryActions.items` array
+
+3. **Inline Secondary Actions Strategy**:
+   - **Action Prioritization**: Order `secondaryActions.items` by frequency of use (most used first)
+   - **Inline Count**: Use `inlineCount: 1-3` for optimal UX (avoid cluttering)
+   - **Visibility Control**:
+     - Use `inlineAlwaysVisible: false` (default) for cleaner visual appearance
+     - Use `inlineAlwaysVisible: true` only for critical actions requiring constant visibility
+
+4. **Update Action Mode**:
+   - Complex, full-entity edits → Use `mode: "page"` to navigate to entity page
+
+5. **Custom Implementation**:
+   - For `custom` actions, you must provide implementations in your code and register them with `PatternsWizardOverridesProvider`
+
+### ActionCell Validation Checklist
+
+AI agents should verify these requirements before generating ActionCell configurations:
+
+✓ ActionCell is placed directly inside `table` or `grid` configuration
+✓ Each action has a unique `id` and correct `type` value
+✓ Each action type only includes its required field(s)
+✓ Update page action refers to a valid entity page ID
+✓ Delete action has a modal configuration
+✓ Custom actions match implementations in overrides
+✓ At least one of `primaryAction` or `secondaryActions` is provided
+✓ `inlineCount` (if specified) is a non-negative number ≤ total secondary actions count
+✓ `inlineAlwaysVisible` (if specified) is a boolean value
+✓ Inline secondary actions configuration is applied only when secondary actions exist
+
+---