@wix/auto-patterns 1.14.0 → 1.16.0

package/dist/docs/auto-patterns-guide.md

@@ -0,0 +1,2447 @@
+# AI Agent Instructions for AutoPatternsApp
+
+This document serves as a comprehensive guide for AI agents to correctly generate and validate configurations for the `AutoPatternsApp` component. Follow these instructions sequentially to ensure proper implementation.
+
+## AI Usage Guidelines
+
+1. **Configuration Generation Process**:
+
+   * First, analyze the schema requirements.
+   * Then, select appropriate fields based on data types.
+   * Finally, validate against the rules before output.
+
+2. **Required Validation Steps**:
+
+   * Verify exact page count (must be 2).
+   * Confirm proper field selection (max 3 columns initially).
+   * Check all mandatory fields are present.
+   * Ensure no unsupported fields are included.
+   * Verify that every collection page has a create action that navigates to the entity page.
+
+3. **Decision-Making Priority**:
+
+   * User explicit requirements override defaults.
+   * Schema structure guides field selection.
+   * Best practices determine presentation.
+
+4. **Enum Configuration Rule (CRITICAL)**:
+
+   * When generating `enumConfig` (whether implicitly as part of another rule or explicitly upon user request), the AI **must always ask the user to provide the possible option values** for the enum field.
+   * The `value` of each option can be **any string specified by the user**, and the `label` should be derived from the `value` (e.g., if `value` is "dog", the `label` can be "Dog").
+   * The AI is strictly prohibited from guessing, inventing, or assuming the enum values or their labels.
+
+---
+
+# Core Rules
+
+## Configuration Rules
+
+* Pages array MUST contain exactly two pages.
+* Components array inside collectionPage MUST contain exactly one component with a layout array.
+* Configuration MUST come only from a JSON file.
+* DO NOT fill optional fields unless explicitly requested.
+* Select up to 3 columns initially that best represent the entity.
+* Every collection page MUST include a create action that allows users to create new entities by navigating to the entity page.
+
+## Type Binding Rules
+
+* If `type: 'collectionPage'`, only `collectionPage` field should exist.
+* If `type: 'entityPage'`, only `entityPage` field should exist.
+* No cross-mixing of types is allowed.
+
+## Override Rules
+
+* Custom overrides are restricted to documented areas only.
+* Only override columns when specific rendering is required.
+
+## Validation Rules
+
+* All configurations must align with AppConfig Structure.
+* Remove any configuration entries not in the structure.
+* Verify customColumns.enabled logic (>5 columns or explicit request).
+
+---
+
+# Instruction Guide & Best Practices
+
+This guide instructs on how to correctly integrate the `AutoPatternsApp` component from `@wix/auto-patterns` package into a Wix-based admin page.
+
+---
+
+# Component Purpose
+
+The `AutoPatternsApp` is a page-level component used to display a data collection either as a Table or Grid.
+It is configured using a JSON file conforming to the `AppConfig` interface and supports overrides for advanced use-cases.
+
+---
+
+# AppConfig Structure
+
+## ⚠️ Configuration Rules
+
+- **Configuration must come only from a JSON file** - never inline or from other sources
+- **DO NOT fill optional fields unless explicitly requested** - leave optional properties undefined to avoid unnecessary complexity
+- **After each configuration change, verify that the configuration strictly aligns with the structure described below** - any configuration entries not defined in this structure must be removed
+- **When generating config for the first time, select up to 3 columns from the schema that best represent the entity**
+
+## ⚠️ Common Configuration Mistakes to Avoid
+
+- Adding more than two pages
+- Mixing page types in a single configuration
+- Including undefined optional fields
+- Selecting too many initial columns
+- Not designating exactly one page as `appMainPage: true`
+- Missing or inconsistent page relationships (parentPageId/entityPageId)
+- Setting `stickyColumns` to invalid values (negative, zero, or exceeding column count)
+
+```ts
+export interface AppConfig {
+  pages: {
+    id: string; // Page unique identifier (must be unique across the app)
+    type: 'collectionPage' | 'entityPage'; // Defines page type
+    appMainPage?: boolean; // Designates this page as the main page (exactly one page must have this set to true)
+    collectionPage?: {
+      route: {
+        path: string; // Route path for the collection page (e.g., '/')
+      };
+      title: {
+        text: string; // Main page title
+        hideTotal?: boolean; // Hide total items in header. Default: true
+      };
+      subtitle?: {
+        text: string; // Optional page subtitle
+      };
+      actions?: { // Defines page-level actions for the collection page
+        primaryActions?: {
+          type: 'action' | 'menu'; // Type of primary actions layout
+          action?: { // Required when type is 'action'
+            item: {
+              id: string; // Unique identifier for the action
+              type: 'create' | 'custom'; // Action type
+              label?: string; // Text displayed for the action
+              collection: {
+                collectionId: string; // ID of the Wix Data collection
+                entityTypeSource: 'cms'; // Data source type. Always 'cms'
+              };
+              create?: { // Required when type is 'create'
+                mode: 'page'; // Create mode
+                page: {
+                  id: string; // Entity page ID to navigate to for creation
+                };
+              };
+            };
+          };
+          menu?: { // Required when type is 'menu'
+            label: string; // Label for the group
+            items: {}[]; // Array of action configurations, same structure as action.item, can include dividers
+          };
+        };
+        secondaryActions?: {
+          type: 'action' | 'menu'; // Type of secondary actions layout, same structure as primaryActions
+          action?: {}; // Same structure as primaryActions.action
+          menu?: {}; // Same structure as primaryActions.menu
+        };
+      };
+      components: [
+        {
+          entityPageId?: string; // ID of the entity page to navigate to when clicking a row
+          collection: {
+            collectionId: string; // ID of the Wix Data collection
+            entityTypeSource: 'cms'; // Data source type. Always 'cms'
+            reflectQueryInUrl?: boolean; // Reflects query state (search, filters, sorting) in the browser URL. Default: false
+            selectAllScope?: 'page' | 'all'; // Controls "Select All" scope. 'all' selects entire collection, 'page' selects only visible items. Default: 'all'
+            selectionUpdateMode?: 'preserve' | 'clear'; // Controls selection behavior when data changes. 'preserve' maintains selections, 'clear' clears them. Default: 'clear'
+          };
+          filters?: {
+            panelTitle?: string; // Title of the filters panel
+            items: {
+              id: string; // Unique identifier for the filter item
+              fieldId: string; // ID of the field to filter by (must be a valid type: NUMBER, DATETIME, BOOLEAN, ARRAY, ARRAY_STRING)
+              displayName?: string; // Display name of the filter item
+              openByDefault?: boolean; // Whether the filter item is open by default in the panel (accordion is open)
+              sectionTitle?: string; // Title of the filter section. Required if more than one section exists to prevent confusion
+              tagLabel?: string; // Label shown in Tag component in the table/grid when the filter is applied (e.g., "Age: 7")
+              numberConfig?: {
+                min?: number; // Minimum value
+                max?: number; // Maximum value
+                allowedDecimals?: true; // Decimal precision allowed
+              };
+              dateConfig?: {
+                mode?: 'ONLY_PREDEFINED' | 'ONLY_CUSTOM' | 'COMBINE'; // Determines filter behavior
+                presets?: (
+                  | 'SEVEN_DAYS'
+                  | 'FOURTEEN_DAYS'
+                  | 'MONTH'
+                  | 'TODAY'
+                  | 'TOMORROW'
+                  | 'NEXT_THREE_DAYS'
+                  | 'NEXT_SEVEN_DAYS'
+                  | 'NEXT_THIRTY_DAYS'
+                )[]; // Shown only if mode includes predefined presets (COMBINE or ONLY_PREDEFINED)
+                includeTime?: boolean; // Whether to allow time selection. Default is true
+              };
+              booleanConfig?: {
+                trueLabel?: string; // Label shown for the true value
+                falseLabel?: string; // Label shown for the false value
+              };
+              enumConfig?: {
+                options: {
+                  value: string; // Enum option value
+                  label: string; // Enum option label
+                }[];
+                selectionMode: 'single' | 'multiple'; // Selection behavior
+                optionType?:
+                  | 'checkbox'
+                  | 'inlineCheckbox'
+                  | 'radio'
+                  | 'select'; // Option rendering style
+              };
+            }[];
+          };
+          actionCell?: {
+            primaryAction?: {
+              item: {
+                id: string; // Unique identifier for the action
+                type: 'update' | 'delete' | 'custom'; // Action type
+                label?: string; // Text displayed for the action
+                disabled?: boolean; // Whether the action is disabled
+                tooltip?: string; // Tooltip text shown on hover
+                update?: { // Required when type is 'update'
+                  mode: 'page'; // Update mode
+                  page?: { // Required when mode is 'page'
+                    id: string; // Entity page ID to navigate to
+                  };
+                };
+                delete?: { // Required when type is 'delete'
+                  mode: 'modal'; // Currently only 'modal' is supported
+                  modal: {
+                    title?: {
+                      text: string; // Modal title
+                    };
+                    description?: {
+                      text: string; // Modal description
+                    };
+                    actions?: {
+                      submit?: {
+                        text: string; // Submit button text
+                      };
+                      cancel?: {
+                        text: string; // Cancel button text
+                      };
+                    };
+                    feedback?: {
+                      successToast?: {
+                        text: string; // Success message
+                      };
+                      errorToast?: {
+                        text: string; // Error message
+                      };
+                    };
+                  };
+                };
+              };
+            };
+            secondaryActions?: {
+              items: {}[]; // Array of action configurations, same structure as primaryAction.item, can include dividers
+              inlineCount?: number; // How many secondary actions to show inline before showing popover
+              inlineAlwaysVisible?: boolean; // Whether to always show inline actions (not just on hover)
+            };
+          };
+          bulkActionToolbar?: {
+            primaryActions?: ({
+              type: 'action' | 'menu'; // Type of bulk action item
+              action?: { // Required when type is 'action'
+                item: {
+                  id: string; // Unique identifier for the bulk action
+                  type: 'bulkDelete' | 'custom'; // Bulk action type
+                  label?: string; // Text displayed for the action
+                  bulkDelete?: { // Required when type is 'bulkDelete'
+                    mode: 'modal'; // Currently only 'modal' is supported
+                    modal: {
+                      title?: {
+                        text: string; // Modal title
+                      };
+                      description?: {
+                        text: string; // Modal description
+                      };
+                      actions?: {
+                        submit?: {
+                          text: string; // Submit button text
+                        };
+                        cancel?: {
+                          text: string; // Cancel button text
+                        };
+                      };
+                      feedback?: {
+                        successToast?: {
+                          text: string; // Success message
+                        };
+                        errorToast?: {
+                          text: string; // Error message
+                        };
+                      };
+                    };
+                  };
+                };
+              };
+              menu?: { // Required when type is 'menu'
+                label: string; // Label for the dropdown group
+                items: {}[] // Array of bulk actions configurations, same structure as action.item, can include dividers
+              };
+            })[];
+            secondaryActions?: {}[]; // Array of bulk actions configurations, same structure as primaryActions[].menu.items, can include dividers
+          };
+          toolbarTitle?: {
+            title: string; // Toolbar title above the table/grid
+            subtitle?: {
+              text: string; // Toolbar subtitle
+            };
+            showTotal?: boolean; // Show total items on toolbar. Default: false
+          };
+          search?: {
+            shown?: boolean; // Show/hide the search
+          };
+          emptyState?: {
+            title?: string; // Empty state title
+            subtitle?: string; // Empty state subtitle
+            image?: {
+              id: string; // Image ID for empty state
+            };
+            addNewCta?: {
+              id?: string; // Add New CTA ID
+              text?: string; // Add New CTA text
+            };
+            customCta?: {
+              id?: string; // Custom CTA ID
+            };
+          };
+          layout: [ // Array of layout items that define what components to render
+            {
+              type: 'Table'; // Layout item type for table rendering
+              table?: {
+                columns: {
+                  id: string; // Field ID from the collection
+                  name: string; // Column title displayed
+                  width: string; // The width of the column (required in types)
+                  sortable?: boolean; // If the column is sortable
+                  defaultSortOrder?: 'asc' | 'desc'; // Optional default sort order
+                  sortMode?: 'asc' | 'desc'; // Optional sorting mode
+                  reorderDisabled?: boolean; // Whether column reordering is disabled
+                  hideable?: boolean; // Whether column can be hidden
+                  defaultHidden?: boolean; // Whether column is hidden by default
+                  hiddenFromCustomColumnsSelection?: boolean; // Whether column is hidden from custom columns selection
+                }[];
+                customColumns?: {
+                  enabled: boolean; // Enable user customization (hide/reorder columns)
+                };
+                stickyColumns?: number; // Number of columns to make sticky from the start. Sticky columns remain visible when horizontally scrolling.
+              };
+            },
+            {
+              type: 'Grid'; // Layout item type for grid rendering
+              grid?: {
+                item: {
+                  titleFieldId: string; // Field ID to display as the item title
+                  subtitleFieldId?: string; // Field ID for the item subtitle
+                  imageFieldId?: string; // Field ID for the item image
+                  /**
+                   * Controls which content is shown in the card (preset):
+                   * - 'full': Shows both title and subtitle.
+                   * - 'title': Shows only the title.
+                   * - 'empty': Hides both title and subtitle (card appears visually empty except for image or other content).
+                   */
+                  cardContentMode?: 'full' | 'title' | 'empty';
+                  imagePlacement?: 'top' | 'side';
+                };
+              };
+            }
+          ]; // End of layout array
+        }
+      ]; // End of components array
+    };
+    entityPage?: {
+      route: {
+        path: string; // Route path for the entity page (e.g., '/product/:entityId')
+        params: {
+          id: string; // Maps dynamic parameter in path to its identifier
+        };
+      };
+      title?: {
+        text: string; // Entity page title
+      };
+      subtitle?: {
+        text: string; // Entity page subtitle
+      };
+      parentPageId?: string; // ID of the parent collection page
+      layout?: {
+        // Main layout section
+        main: {
+          type: 'card'; // Type of the card
+          card: {
+            title: {
+              text: string; // Title of the card
+            };
+            subtitle?: {
+              text: string; // Subtitle of the card
+            };
+            children: LayoutContent[]; // Array of content items that can be fields, nested containers, or components
+          };
+        }[];
+        // Sidebar layout section
+        sidebar?: {
+          type: 'card';
+          card: {
+            title: {
+              text: string; // Title of the card
+            };
+            subtitle?: {
+              text: string; // Subtitle of the card
+            };
+            children: LayoutContent[]; // Array of content items that can be fields, nested containers, or components
+          };
+        }[];
+      };
+      collectionId: string; // Related collection ID
+      entityTypeSource: 'cms'; // Data source type. Always 'cms'
+    };
+  }[];
+}
+
+type LayoutContent =
+  | {
+      type: 'field';
+      field: {
+        span?: number;
+        fieldId: string;
+      };
+    }
+  | {
+      type: 'container';
+      container: {
+        span?: number;
+        children: LayoutContent[];
+      };
+    }
+  | {
+      type: 'component';
+      component: {
+        span?: number;
+        componentId: string;
+      };
+    };
+```
+
+---
+
+# Pages Configuration
+
+## ⚠️ Critical Page Rules
+
+- **Pages array must contain exactly two pages** - one collectionPage and one entityPage
+- **Exactly one page must have `appMainPage: true`** to designate it as the main page
+- **All page IDs referenced in relationships must exist in the configuration** - validate all `parentPageId` and `entityPageId` references
+- **Bind `type` strictly to matching fields** - if `type: 'collectionPage'`, only `collectionPage` field exists (no `entityPage` field), and vice versa
+
+## Default Generation
+
+* **Always generate two pages**:
+
+  * One **collectionPage** (routePath: `/`)
+  * One **entityPage** (routePath: `/[segment]/:entityId`)
+
+    * Always use `entityId` as the dynamic URL parameter, not `id`.
+    * The route path **must** include a descriptive segment (e.g., `/product/:entityId`, `/pet/:entityId`)
+    * **Never use just `/:entityId`** - this conflicts with the collection page route and breaks routing
+
+## Type and Structure Binding
+
+* If `type: 'collectionPage'`, then **only** `collectionPage` field exists (no `entityPage` field).
+* If `type: 'entityPage'`, then **only** `entityPage` field exists (no `collectionPage` field).
+* **No cross-mixing** allowed.
+
+## Page Connection Configuration
+
+### Main Page Designation
+
+* One page must be designated as the main page using the `appMainPage` property:
+  * **Exactly one page** must have `appMainPage: true`
+  * When users navigate to the root path (`/`), they will be automatically redirected to this page
+  * This is typically set on the collection page, but can be any page based on your application's requirements
+
+### Collection-Entity Page Relationships
+
+A two-way connection must be established between collection pages and entity pages:
+
+1. **From EntityPage to CollectionPage**:
+   * Each entity page must specify its parent collection page using `parentPageId`
+   * This property on the entity page references the `id` of its parent collection page
+
+2. **From CollectionPage to EntityPage**:
+   * Each collection page's component must reference its corresponding entity page:
+   * Inside the table or grid configuration (not directly in the collectionPage), specify `entityPageId` pointing to the entity page's `id`:
+   ```json
+   "components": [
+     {
+       "type": "Table", // or "Grid"
+       "table": {       // or "grid"
+         "entityPageId": "my-entity-page-id",
+         // other table/grid configuration
+       }
+     }
+   ]
+   ```
+   * ⚠️ **IMPORTANT**: The `entityPageId` field is located within the specific component configuration (table or grid), not at the collection page level
+
+### Entity Page URL Configuration
+
+* For entity pages (`type: "entityPage"`), the following URL configuration is **mandatory**:
+
+  1. **Route Path Structure**:
+     * The `route.path` **must** include a relative path segment followed by a dynamic parameter (e.g., `/product/:entityId` or `/pets/:entityId`)
+     * **Never use just `/:entityId`** - this conflicts with the collection page route `/` and breaks routing
+     * The relative path segment should be descriptive of the entity type (e.g., `/product/`, `/pet/`, `/user/`)
+     * This parameter is typically named `:entityId` by convention, but any parameter name prefixed with `:` is valid
+
+  2. **Route Parameters Mapping**:
+     * The `route.params` property is required and must map the dynamic parameter:
+     ```json
+     "route": {
+       "path": "/product/:entityId",
+       "params": {
+         "id": "entityId"
+       }
+     }
+     ```
+     * The `id` field in `route.params` must match the parameter name used in `route.path` (without the colon)
+
+
+### Key Rules for Page Connections
+
+* **Main Page Requirement**: Exactly one page must have `appMainPage: true`
+* **Reference Validity**: All page IDs referenced in `parentPageId` and `entityPageId` must exist in the configuration
+* **Relationship Consistency**: The two-way connection must be consistent - if entity page A points to collection page B, then collection page B must point to entity page A
+* **Route Structure**: Entity pages must use `/[segment]/:entityId` format (e.g., `/product/:entityId` or `/pets/:entityId`), never just `/:entityId`
+* **Route Parameters Configuration**: All entity pages must have both a dynamic parameter in `route.path` and a matching configuration in `route.params`
+
+## ⚠️ Common Type and Route Mistakes to Avoid
+
+- Using incorrect field types
+- Missing required fields
+- Including fields from wrong page type
+- Missing route.params for entity pages
+- Using `/:entityId` instead of `/segment/:entityId` for entity page routes (causes routing conflicts)
+
+# Sticky Columns Configuration
+
+## Overview
+
+Sticky columns allow you to keep specific columns visible while users scroll horizontally through wide tables. This feature improves usability by ensuring important information (like names or IDs) remains accessible during scrolling.
+
+## Configuration Properties
+
+### stickyColumns
+
+- **Type**: `number` (optional)
+- **Description**: Number of columns to make sticky from the start of the table
+- **Behavior**: Sticky columns are always the **first N columns** in the `columns` array
+- **Default**: `undefined` (no sticky columns)
+
+## Key Behavior Rules
+
+### 🔑 **Critical Rule: Position-Based Stickiness**
+- `stickyColumns: 2` means "make the **first 2 columns** sticky" (positions 0 and 1 in the `columns` array)
+- The sticky columns are determined by **array position**, not by column content
+- If columns are reordered, the sticky behavior follows the new order
+
+### 🔒 **Important: Reorder Protection**
+- To protect specific columns from being reordered away from their sticky positions, set `reorderDisabled: true` on those columns
+- This allows `customColumns.enabled: true` while protecting sticky columns from being moved
+- Without reorder protection, users can accidentally move intended sticky columns away from the beginning
+
+### ⚠️ **Validation Rules**
+- `stickyColumns` must be a positive number
+- `stickyColumns` should not exceed the total number of columns
+- Invalid values are ignored (treated as `undefined`)
+
+---
+
+# Collection Page Configuration
+
+## ⚠️ Collection Page Rules
+
+- **Components array inside collectionPage must contain exactly one component with a layout array**
+- **All collection pages with tables/grids must reference their corresponding entity page via `entityPageId`** in the collection configuration
+- **Enable `customColumns` only based on strict logic** - enable if more than 5 columns are defined OR user explicitly requests it, otherwise disable
+- **Row click behavior**: By default, clicking a table row navigates to the entity page. Use `onRowClick` configuration only when custom row click behavior is explicitly required
+- **When generating config for first time, select up to 3 columns from the schema that best represent the entity**
+
+## Components Array
+
+* Must include **exactly one item**.
+* Each component must have:
+  * `collection`: Collection configuration with `collectionId` and `entityTypeSource: 'cms'`
+  * `layout`: Array of layout items that determine what components to render
+
+## Layout Array
+
+The `layout` array contains the rendering components for the collection. Each layout item has:
+* `type`: Either 'Table' or 'Grid'
+* Component-specific configuration (`table` or `grid` object)
+
+### Layout Item Types:
+
+1. **Table Layout Item** (`type: 'Table'`):
+   * `table` field contains table-specific configuration
+   * Used for displaying collection in a **table view**
+   * Includes columns, actionCell, bulkActionToolbar, etc.
+
+2. **Grid Layout Item** (`type: 'Grid'`):
+   * `grid` field contains grid-specific configuration
+   * Used for **grid (card) view** of collection
+   * Includes item configuration for title/subtitle/image fields
+
+### Table/Grid View Switch Behavior:
+* When **both** Table and Grid layout items are present in the layout array, AutoPatterns automatically adds a Table/Grid view switch control so users can toggle between the two views
+* Users can toggle between table and grid views
+
+## Table Configuration
+
+* Used for displaying collection in a **table view**.
+* **customColumns.enabled** logic:
+  * Enable if:
+    * More than **5 columns** are defined
+    * OR user **explicitly** requests it
+  * Otherwise, **disable** (false)
+
+## Grid Configuration
+
+* Used for **grid (card) view** of collection.
+* `item.title`, `item.subtitle`, `item.image` fields are **Field IDs** from the schema.
+* If the user does not specify, **select the most relevant fields automatically**.
+* For grid components, it is strongly recommended to implement a primary action cell with an `update` action that navigates to the entity page. This provides users with an intuitive way to access detailed information and edit individual entities directly from the grid view.
+
+---
+
+# 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`).
+
+---
+
+## 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
+
+---
+
+## 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
+
+---
+
+# Entity Page Configuration
+
+## ⚠️ Entity Page Requirements
+
+All entity pages must have:
+- **A route path with descriptive segment and dynamic parameter** (e.g., `/product/:entityId`, `/pet/:entityId`) - **never just `/:entityId`** as this conflicts with collection page routing
+- **A matching `route.params` configuration** that maps the dynamic parameter
+- **A reference to their parent collection page via `parentPageId`**
+
+## Overview
+
+* Displays details for a **single entity**.
+* Always tied to a single Wix collection.
+* `entityTypeSource` is always `'cms'`.
+
+> The custom actions must be defined inside the `moreActions` array.
+
+> Note: You do not need to define a custom action to navigate to the entity page. This behavior is built-in — clicking on a row in the collection table automatically navigates to the corresponding entity page.
+
+## Entity Page Layout Configuration
+
+### Grid System
+
+- **12-Column Grid**: The layout uses a 12-column grid system.
+- The `span` property controls how many columns an item occupies (1-12).
+- When items in a row exceed 12 columns total, the next item wraps to a new line.
+- Example: If an item has `span: 8` and the next has `span: 5`, the second item will start a new line.
+
+### Layout Structure
+
+- **Main Section**: Contains primary entity information and most important fields.
+- **Sidebar Section**: Contains secondary information, metadata, or supporting content.
+- Both sections support cards that can contain fields, containers, and components.
+
+### Detailed Layout Content Types
+
+1. **Field Type**:
+   ```typescript
+   {
+     type: 'field';
+     field: {
+       span?: number; // How many columns this field occupies (1-12)
+       fieldId: string; // Must match a valid field ID from the collection schema
+     };
+   }
+   ```
+
+2. **Container Type** (for grouping related fields):
+   ```typescript
+   {
+     type: 'container';
+     container: {
+       span?: number; // How many columns this container occupies (1-12)
+       children: LayoutContent[]; // Can nest fields, other containers, or components
+     };
+   }
+   ```
+
+3. **Component Type** (for custom rendering):
+   ```typescript
+   {
+     type: 'component';
+     component: {
+       span?: number; // How many columns this component occupies (1-12)
+       componentId: string; // ID matching a component override implementation
+     };
+   }
+   ```
+
+### Layout Best Practices
+
+1. **Field Grouping**:
+   - Group related fields using containers
+   - Place frequently used fields at the top
+   - Consider the natural flow of data entry
+
+2. **Main vs. Sidebar Usage**:
+   - Main section: Put primary entity information
+   - Sidebar: Place secondary information and metadata
+
+3. **Responsive Considerations**:
+   - Use appropriate spans for different field types
+   - Text fields often benefit from larger spans
+   - Boolean fields can use smaller spans
+
+4. **Nested Containers**:
+   - Use containers to create logical groupings
+   - Don't nest containers too deeply for clarity
+   - Consider using cards for major sections instead of deeply nested containers
+
+5. **Image Handling**:
+   - For image fields, consider providing more space (larger span)
+   - Images are automatically rendered with proper controls when using the field type
+
+## ⚠️ Common Entity Page Layout Mistakes to Avoid
+
+- Using incorrect span values causing unexpected layout breaks
+- Referencing non-existent field IDs in the layout
+- Creating overly complex nested container structures
+- Failing to properly register component overrides
+- Confusing main and sidebar section usage (putting main content in sidebar)
+- Exceeding 12 total columns in a row without realizing content will wrap
+- Forgetting to specify the `collectionPagePath` value
+- Missing required `type: 'card'` structure in layout sections
+
+---
+
+## Entity Page Actions: `moreActions` Support
+
+Entity pages in AutoPatternsApp support not only a primary action (such as "Save" or "Delete") but also a flexible set of **more actions** (sometimes called "secondary actions" or `moreActions`). These allow you to provide additional contextual actions for the entity, such as custom logic, or grouped actions.
+
+> **Note:** All custom actions for entity pages must be placed in the `moreActions` array. Do not place custom actions as primary actions on entity pages. The `moreActions` array is the only supported location for custom actions on entity pages.
+
+### Configuration Structure
+
+- The `moreActions` property on the entity page is an **array** of action configurations that can include divider objects for visual separation.
+- Each action in `moreActions` is a Custom Action (type: "custom") or a Divider (type: "divider")
+
+#### Example: Adding custom actions with dividers to an entity page
+```json
+{
+  "type": "entityPage",
+  "entityPage": {
+    // ... other config ...
+    "moreActions": [
+      {
+        "id": "sendEmail",
+        "type": "custom",
+        "label": "Send Email"
+      },
+      {
+        "id": "exportData",
+        "type": "custom",
+        "label": "Export Data"
+      },
+      { "type": "divider" },
+      {
+        "id": "archiveEntity",
+        "type": "custom",
+        "label": "Archive"
+      }
+    ]
+  }
+}
+```
+
+---
+
+### CustomEntityPageMoreActionsActionResolver
+
+The `CustomEntityPageMoreActionsActionResolver` type is used to implement custom actions for the `moreActions` menu on entity pages in AutoPatternsApp. Each action in the `moreActions` array must have a corresponding resolver function registered in your overrides.
+
+#### Function Signature
+
+```typescript
+import { CustomEntityPageMoreActionsActionResolver } from '@wix/auto-patterns/types';
+
+export const myMoreAction: CustomEntityPageMoreActionsActionResolver = (params) => {
+  const { actionParams: { entity, form } , sdk } = params;
+
+  return {
+    label: 'My More Action',
+    icon: <MyIcon />, // optional
+    onClick: () => {
+      // Your custom logic here
+    },
+  };
+};
+```
+
+- **entity**: The current entity data (all field values). In actionParams.
+- **form**: The react-hook-form instance for the entity page. In actionParams.
+- **sdk**: The AutoPatterns SDK (see SDK Utilities section).
+
+---
+
+#### Key Points for CustomEntityPageMoreActionsActionResolver
+
+- The action `id` in the configuration MUST exactly match the function name exported from your actions folder.
+- The implementation must use the `CustomEntityPageMoreActionsActionResolver` type.
+- The implementation must be exported as a named export (not default export).
+- The function receives `{ actionParams, sdk }` as parameters.
+- The returned object must include at least a `label` and an `onClick` handler (optionally an `icon`).
+
+---
+
+#### Validation Checklist for More Actions
+
+✓ Each action in `moreActions` has a unique `id` and correct `type` value
+✓ Each action type only includes its required field(s)
+✓ Custom actions match implementations in overrides
+✓ The resolver is exported and registered in the `actions` property of your `PatternsWizardOverridesProvider`
+✓ The function signature matches `CustomEntityPageMoreActionsActionResolver`
+✓ The returned object includes `label`, `onClick`, and optionally `icon`
+
+---
+
+**Summary:**
+The `CustomEntityPageMoreActionsActionResolver` enables you to add custom, contextual actions to the "More Actions" menu on your entity pages. Implement the resolver, export it, and reference it by `id` in your config for seamless integration.
+
+---
+
+# Installation & Setup
+
+## 1. Install Packages
+
+Install if necessary and doesn't exists in package.json:
+
+```bash
+npm install @wix/auto-patterns @wix/patterns @wix/design-system
+```
+
+## ⚠️ Critical Import Rules
+
+- **Import `AutoPatternsApp` only from `@wix/auto-patterns`** - never from other packages
+- **CRITICAL:** Always import `AppConfig` as a type import: `import type { AppConfig } from '@wix/auto-patterns/types'` - never import it as a value import
+
+## 2. Create AppConfig JSON
+
+Save this configuration as a `{collectionName}Config.patterns.json` file in the same directory as your page.tsx component.
+
+For example:
+- For a "WixPets" collection: `petsConfig.patterns.json`
+- For a "Products" collection: `productsConfig.patterns.json`
+- For a "Users" collection: `usersConfig.patterns.json`
+
+## Render the Collection Page Component
+
+Inside your page component, import the JSON configuration and use the `AutoPatternsApp` component. Since this is a page-level component, it should be the only component rendered on the page. Any other content or components should be removed to ensure proper functionality and avoid conflicts.
+
+### Page Component Example:
+
+```tsx
+import React, { type FC } from 'react';
+import { WixDesignSystemProvider } from '@wix/design-system';
+import '@wix/design-system/styles.global.css';
+import { WixPatternsProvider } from '@wix/patterns/provider';
+import { PatternsWizardOverridesProvider, AutoPatternsApp } from '@wix/auto-patterns';
+import type { AppConfig } from '@wix/auto-patterns/types';
+import { withDashboard } from '@wix/patterns';
+
+import config from './MyCollectionConfig.patterns.json';
+
+const Index: FC = () => {
+  return (
+    <WixDesignSystemProvider features={{ newColorsBranding: true }}>
+      <WixPatternsProvider>
+        <PatternsWizardOverridesProvider value={{ }}>
+          <AutoPatternsApp configuration={config as AppConfig} />
+        </PatternsWizardOverridesProvider>
+      </WixPatternsProvider>
+    </WixDesignSystemProvider>
+  );
+};
+
+export default withDashboard(Index);
+```
+
+---
+
+# 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.
+
+---