@wix/auto-patterns 1.27.0 → 1.29.0

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

@@ -78,6 +78,34 @@ It is configured using a TypeScript file conforming to the `AppConfig` interface
 
 # AppConfig Structure
 
+## ⚠️ CRITICAL REQUIREMENT: Mandatory `biName` Property
+
+**Every action configuration in auto-patterns MUST include a `biName` property.** This is not optional - it's a mandatory requirement for all auto-patterns applications.
+
+### Why `biName` is Mandatory:
+- **Analytics Tracking**: Enables tracking of user interactions with actions
+- **Feature Usage**: Helps understand which features are most/least used
+- **User Behavior**: Provides insights into user workflows and preferences
+- **Business Intelligence**: Supports data-driven decision making
+- **A/B Testing**: Enables testing different action configurations
+- **Compliance**: Required for proper application monitoring and reporting
+
+### `biName` Requirements:
+- **MUST be included** in every action configuration
+- **Use descriptive, kebab-case naming** (e.g., "toggle-vaccination-action")
+- **Must be unique** across the application
+- **Follow the pattern**: `{action-purpose}-action`
+
+### Example:
+```json
+{
+  "id": "toggleVaccination",
+  "type": "custom",
+  "label": "Toggle Vaccination",
+  "biName": "toggle-vaccination-action"  // MANDATORY
+}
+```
+
 ## Configuration Rules
 
 - **Configuration must come only from a TypeScript file** - never inline or from other sources
@@ -102,6 +130,8 @@ It is configured using a TypeScript file conforming to the `AppConfig` interface
 - **Missing action type properties**: Not including `create`, `update`, `delete`, or `bulkDelete` properties when required by the action type
 - **Including wrong action properties**: Adding properties from different action types in the same action configuration
 - **Action type mismatches**: Using action cell types in collection actions, or bulk action types in regular actions
+- **Missing `biName` property**: Every action configuration MUST include a `biName` property for analytics tracking
+- **Generic `biName` values**: Using generic names like "action" or "button" instead of descriptive, kebab-case names
 
 ```ts
 export interface AppConfig {
@@ -128,6 +158,7 @@ export interface AppConfig {
               id: string; // Unique identifier for the action
               type: 'create' | 'custom'; // Action type
               label?: string; // Text displayed for the action
+              biName: string; // MANDATORY: Business intelligence name for analytics tracking
               collection: {
                 collectionId: string; // ID of the Wix Data collection
                 entityTypeSource: 'cms' | 'custom'; // Data source type.
@@ -167,6 +198,7 @@ export interface AppConfig {
             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'
+            paginationMode?: 'cursor' | 'offset'; // Controls pagination strategy and expected find() return shape. 'cursor' => { items, cursor, total? }, 'offset' (default) => { items, hasNext, total? }
           };
           filters?: {
             panelTitle?: string; // Title of the filters panel
@@ -221,6 +253,7 @@ export interface AppConfig {
                 type: 'update' | 'delete' | 'custom'; // Action type
                 label?: string; // Text displayed for the action
                 skin?: string; // Visual appearance of the action button (see Action Button Skin Values section)
+                biName: string; // MANDATORY: Business intelligence name for analytics tracking
                 disabled?: boolean; // Whether the action is disabled
                 tooltip?: string; // Tooltip text shown on hover
                 update?: { // Required when type is 'update'
@@ -273,6 +306,7 @@ export interface AppConfig {
                   id: string; // Unique identifier for the bulk action
                   type: 'bulkDelete' | 'custom'; // Bulk action type
                   label?: string; // Text displayed for the action
+                  biName: string; // MANDATORY: Business intelligence name for analytics tracking
                   bulkDelete?: { // Required when type is 'bulkDelete'
                     mode: 'modal'; // Currently only 'modal' is supported
                     modal: {
@@ -378,7 +412,7 @@ export interface AppConfig {
         } |
         {
           type: 'custom'; // Component type for custom slot components
-          id: string; // Unique identifier that maps to a custom React component provided through PatternsWizardOverridesProvider slots
+          id: string; // Unique identifier that maps to a custom React component provided through AutoPatternsOverridesProvider slots
         }
       ]; // End of components array
     };
@@ -410,6 +444,7 @@ export interface AppConfig {
               id: string;
               type: 'create' | 'custom';
               label?: string;
+              biName: string; // MANDATORY: Business intelligence name for analytics tracking
               create?: { // Required when type is 'create'
                 mode: 'page';
                 page: {
@@ -432,6 +467,7 @@ export interface AppConfig {
           id: string;
           type: 'custom';
           label?: string;
+          biName: string; // MANDATORY: Business intelligence name for analytics tracking
         }[];
       };
       parentPageId?: string; // ID of the parent collection page
@@ -708,7 +744,7 @@ The `layout` array contains the rendering components for the collection. Each la
 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.
+   * Includes columns, bulkActionToolbar, etc.
 
 2. **Grid Layout Item** (`type: 'Grid'`):
    * `grid` field contains grid-specific configuration
@@ -773,7 +809,7 @@ In addition to these common properties, each action item must specify a `type` w
 ### 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`.
+    *   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 `AutoPatternsOverridesProvider`. 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.
@@ -862,6 +898,7 @@ Custom collection page actions execute JavaScript code that you define for colle
      "id": "exportCollection",        // MUST match the function name exactly
      "type": "custom",                // REQUIRED: Must be exactly "custom"
      "label": "Export Collection",    // Optional: Displayed text
+     "biName": "export-collection-action",  // MANDATORY: Analytics tracking identifier
      "collection": {
        "collectionId": "WixPets",
        "entityTypeSource": "cms"
@@ -869,7 +906,7 @@ Custom collection page actions execute JavaScript code that you define for colle
    }
    ```
 
-5. Register your action in the `PatternsWizardOverridesProvider`:
+5. Register your action in the `AutoPatternsOverridesProvider`:
    ```typescript
    import { useActions } from '../components/actions';
 
@@ -877,9 +914,9 @@ Custom collection page actions execute JavaScript code that you define for colle
      const actions = useActions();
 
      return (
-       <PatternsWizardOverridesProvider value={{ actions }}>
+       <AutoPatternsOverridesProvider value={{ actions }}>
          <AutoPatternsApp configuration={config} />
-       </PatternsWizardOverridesProvider>
+       </AutoPatternsOverridesProvider>
      );
    }
    ```
@@ -951,6 +988,7 @@ export const handleRowClick: CustomActionCollectionPageActionOnRowClickResolver
 
       // Your custom logic...
     },
+    biName: 'view-details-action'    // MANDATORY: For analytics tracking
   };
 };
 ```
@@ -986,6 +1024,7 @@ export const openSidePanel: CustomActionCollectionPageActionOnRowClickResolver =
       // Or use a modal service/context that you've set up
       // modalService.openSidePanel(item);
     },
+    biName: 'open-side-panel-action'  // MANDATORY: For analytics tracking
   };
 };
 ```
@@ -1015,7 +1054,7 @@ export const useActions = () => {
 }
 ```
 
-**Step 4: Register in `PatternsWizardOverridesProvider`**:
+**Step 4: Register in `AutoPatternsOverridesProvider`**:
 ```typescript
 import { useActions } from '../components/actions';
 
@@ -1023,9 +1062,9 @@ export default function YourPage() {
   const actions = useActions();
 
   return (
-    <PatternsWizardOverridesProvider value={{ actions }}>
+    <AutoPatternsOverridesProvider value={{ actions }}>
       <AutoPatternsApp configuration={config} />
-    </PatternsWizardOverridesProvider>
+    </AutoPatternsOverridesProvider>
   );
 }
 ```
@@ -1062,6 +1101,7 @@ export const quickToggle: CustomActionCollectionPageActionOnRowClickResolver = (
         })
       });
     },
+    biName: 'quick-toggle-action'     // MANDATORY: For analytics tracking
   };
 };
 ```
@@ -1085,7 +1125,7 @@ export const quickToggle: CustomActionCollectionPageActionOnRowClickResolver = (
 - The implementation must use the `CustomActionCollectionPageActionOnRowClickResolver` type
 - **Required Return Object**: Must return a `ResolvedAction` object - see [ResolvedAction Reference](./resolved_action.md)
 - Access the clicked item's data through `actionParams.item`
-- The implementation must be exported as a named export and registered in your `PatternsWizardOverridesProvider`
+- The implementation must be exported as a named export and registered in your `AutoPatternsOverridesProvider`
 - 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
 
@@ -1103,10 +1143,13 @@ export const quickToggle: CustomActionCollectionPageActionOnRowClickResolver = (
 ✓ 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 return a `ResolvedAction` object with `label`, `icon`, `onClick`, and `biName` properties - all are required. See [ResolvedAction Reference](./resolved_action.md) for complete field documentation.
 ✓ 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.
+✓ **MANDATORY**: Every action configuration MUST include a `biName` property for analytics tracking.
+✓ **MANDATORY**: `biName` must use descriptive, kebab-case naming (e.g., "export-collection-action").
+✓ **MANDATORY**: `biName` must be unique across the application and follow the pattern `{action-purpose}-action`.
 
 ---
 
@@ -1235,19 +1278,25 @@ export interface SchemaConfig {
     update: (updatedEntity: any) => Promise<any>;
     delete: (entityId: string) => Promise<any>;
     bulkDelete: (entityIds: string[]) => Promise<any>;
+    // The return shape depends on pagination mode (see AppConfig.collection.paginationMode)
+    // - Cursor mode: { items, cursor, total? }
+    // - Offset mode (default): { items, hasNext, total? }
     find: (
       query: Query,
       options?: {
         searchableFieldIds?: string[];
         filterFieldMapping?: Record<string, { fieldId: string }>;
       },
-    ) => Promise<{ items: any[]; total: number }>;
+    ) => Promise<
+      | { items: any[]; cursor?: string | null; total?: number | null }
+      | { items: any[]; hasNext?: boolean; total?: number | null }
+    >;
   };
 }
 
 export interface Query {
   limit: number;                    // Maximum number of items to return per request (controls page size)
-  offset: number;                   // Number of items to skip from the beginning (for pagination)
+  offset?: number;                   // Number of items to skip from the beginning (for pagination)
   page: number;                     // Current page number (1-based, works with limit for pagination)
   search?: string;                  // Text search query applied to searchable fields
   cursor?: string | null;           // Cursor-based pagination token (alternative to offset-based pagination)
@@ -1346,7 +1395,9 @@ export type Field = ReferenceField | NonReferenceField;
   - `query`: Query object with pagination, filtering, sorting, and search criteria (see Query Interface section)
   - `options.searchableFieldIds`: Array of field IDs that support text search
   - `options.filterFieldMapping`: Maps filter IDs to actual field IDs for complex filtering
-  - Returns: `{ items: any[], total: number }`
+  - Returns (depends on pagination mode):
+    - Cursor mode: `{ items: any[]; cursor?: string | null; total?: number | null }`
+    - Offset mode (default): `{ items: any[]; hasNext?: boolean; total?: number | null }`
 
 ### Field Type Information
 
@@ -1540,6 +1591,7 @@ Custom actions execute JavaScript code that you define. These actions receive pa
            })
          });
        },
+       biName: 'download-pet-details-action'  // MANDATORY: For analytics tracking
      };
    };
    ```
@@ -1564,10 +1616,11 @@ Custom actions execute JavaScript code that you define. These actions receive pa
      "id": "downloadPetDetails",        // MUST match the function name exactly
      "type": "custom",                  // REQUIRED: Must be exactly "custom"
      "label": "Download Details",       // Optional: Displayed text
+     "biName": "download-pet-details-action"  // MANDATORY: Analytics tracking identifier
    }
    ```
 
-5. Register your action in the `PatternsWizardOverridesProvider`:
+5. Register your action in the `AutoPatternsOverridesProvider`:
    ```typescript
    import { useActions } from '../components/actions';
 
@@ -1575,9 +1628,9 @@ Custom actions execute JavaScript code that you define. These actions receive pa
      const actions = useActions();
 
      return (
-       <PatternsWizardOverridesProvider value={{ actions }}>
+       <AutoPatternsOverridesProvider value={{ actions }}>
          <AutoPatternsApp configuration={config} />
-       </PatternsWizardOverridesProvider>
+       </AutoPatternsOverridesProvider>
      );
    }
    ```
@@ -1592,13 +1645,21 @@ Custom actions execute JavaScript code that you define. These actions receive pa
 
 1. `id` must:
    - Match exactly the function name of the custom action implementation
-   - Be registered in the `actions` property of your `PatternsWizardOverridesProvider`
+   - Be registered in the `actions` property of your `AutoPatternsOverridesProvider`
    - Follow JavaScript identifier naming rules (camelCase recommended)
 
-2. The implementation must return an object with:
-   - `label`: Text displayed for the action
+2. `biName` must:
+   - Be included in every action configuration (MANDATORY)
+   - Use descriptive, kebab-case naming (e.g., "download-pet-details-action")
+   - Be unique across the application
+   - Follow the pattern: `{action-purpose}-action`
+   - Enable analytics tracking for user interactions
+
+2. The implementation must return a `ResolvedAction` object with:
+   - `label`: Text displayed for the action 
    - `icon`: An Icon component from "@wix/wix-ui-icons-common"
    - `onClick`: Handler function for the action
+   - `biName`: Business intelligence name for analytics tracking. Must match the `biName` in your action configuration (required)
    - `hidden` (optional): Boolean to hide the action when true
 
 3. The implementation must:
@@ -1634,13 +1695,13 @@ Follow this decision process when implementing ActionCell:
    - Complex, full-entity edits → Use `mode: "page"` to navigate to entity page
 
 6. **Custom Implementation**:
-   - For `custom` actions, you must provide implementations in your code and register them with `PatternsWizardOverridesProvider`
+   - For `custom` actions, you must provide implementations in your code and register them with `AutoPatternsOverridesProvider`
 
 ### ActionCell Validation Checklist
 
 AI agents should verify these requirements before generating ActionCell configurations:
 
-✓ ActionCell is placed directly inside `table` or `grid` configuration
+✓ ActionCell is placed at the collection component level (`collectionPage.components[*].actionCell`) as a sibling to `collection`, `layout`, etc. — NOT inside `table` or `grid`
 ✓ 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
@@ -1779,6 +1840,7 @@ Custom bulk actions execute JavaScript code that you define for bulk operations.
            })
          });
        },
+       biName: 'bulk-export-pets-action'  // MANDATORY: For analytics tracking
      };
    };
    ```
@@ -1801,10 +1863,11 @@ Custom bulk actions execute JavaScript code that you define for bulk operations.
      "id": "bulkExportPets",        // MUST match the function name exactly
      "type": "custom",              // REQUIRED: Must be exactly "custom"
      "label": "Export Selected",    // Optional: Displayed text
+     "biName": "bulk-export-pets-action"  // MANDATORY: Analytics tracking identifier
    }
    ```
 
-5. Register your action in the `PatternsWizardOverridesProvider`:
+5. Register your action in the `AutoPatternsOverridesProvider`:
    ```typescript
    import { useActions } from '../components/actions';
 
@@ -1812,9 +1875,9 @@ Custom bulk actions execute JavaScript code that you define for bulk operations.
      const actions = useActions();
 
      return (
-       <PatternsWizardOverridesProvider value={{ actions }}>
+       <AutoPatternsOverridesProvider value={{ actions }}>
          <AutoPatternsApp configuration={config} />
-       </PatternsWizardOverridesProvider>
+       </AutoPatternsOverridesProvider>
      );
    }
    ```
@@ -1831,7 +1894,7 @@ Custom bulk actions execute JavaScript code that you define for bulk operations.
 
 1. `id` must:
    - Match exactly the function name of the custom bulk action implementation
-   - Be registered in the `actions` property of your `PatternsWizardOverridesProvider`
+   - Be registered in the `actions` property of your `AutoPatternsOverridesProvider`
    - Follow JavaScript identifier naming rules (camelCase recommended)
 
 2. The implementation must return a `ResolvedAction`:
@@ -1921,7 +1984,7 @@ Follow this decision process when implementing Bulk Action Toolbar:
    - 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`
+   - For `custom` bulk actions, you must provide implementations in your code and register them with `AutoPatternsOverridesProvider`
 
 ### Bulk Action Toolbar Validation Checklist
 
@@ -1936,6 +1999,9 @@ AI agents should verify these requirements before generating Bulk Action Toolbar
 ✓ 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
+✓ **MANDATORY**: Every action configuration MUST include a `biName` property for analytics tracking
+✓ **MANDATORY**: `biName` must use descriptive, kebab-case naming (e.g., "bulk-export-pets-action")
+✓ **MANDATORY**: `biName` must be unique across the application and follow the pattern `bulk-{action}-action`
 
 ---
 
@@ -1963,7 +2029,7 @@ When a user asks to "add badges to the entity page", understand that they want:
 1. **Custom component overrides** - NOT direct configuration in JSON
 2. **Function that returns badge objects** - NOT JSX components
 3. **Badge properties** like `text`, `skin`, `prefixIcon`, etc.
-4. **Registration in PatternsWizardOverridesProvider** under `entityPageHeaderBadges`
+4. **Registration in AutoPatternsOverridesProvider** under `entityPageHeaderBadges`
 
 **Example Request**: "Add 2 badges with random skins and text 'wow'"
 **Correct Implementation**: Create a function that returns `[{text: 'wow', skin: 'success'}, {text: 'wow', skin: 'premium'}]`
@@ -2057,7 +2123,7 @@ const Index: FC = () => {
   const entityPageHeaderSubtitle = useEntityPageHeaderSubtitle();
 
   return (
-    <PatternsWizardOverridesProvider
+    <AutoPatternsOverridesProvider
       value={{
         // ... other overrides
         entityPageHeaderSubtitle: {
@@ -2066,7 +2132,7 @@ const Index: FC = () => {
       }}
     >
       <WixPetsPage />
-    </PatternsWizardOverridesProvider>
+    </AutoPatternsOverridesProvider>
   );
 };
 ```
@@ -2117,16 +2183,16 @@ export const myFunction = (entity) => { ... }
 
 ### Integration
 
-Register your subtitle override in the `PatternsWizardOverridesProvider`:
+Register your subtitle override in the `AutoPatternsOverridesProvider`:
 
 ```typescript
-<PatternsWizardOverridesProvider value={{
+<AutoPatternsOverridesProvider value={{
   entityPageHeaderSubtitle: {
     mySubtitleOverride,
   },
 }}>
   <AutoPatternsApp configuration={config} />
-</PatternsWizardOverridesProvider>
+</AutoPatternsOverridesProvider>
 ```
 
 ## Entity Page Dynamic Badges
@@ -2159,7 +2225,7 @@ When implementing badges for entity pages, understand these key points:
 1. **Badges are CUSTOM COMPONENT OVERRIDES** - NOT direct configuration
 2. **Badge function returns an ARRAY of badge objects** - NOT JSX components
 3. **Each badge object has properties** like `text`, `skin`, `prefixIcon`, etc.
-4. **Must be registered in PatternsWizardOverridesProvider** under `entityPageHeaderBadges`
+4. **Must be registered in AutoPatternsOverridesProvider** under `entityPageHeaderBadges`
 
 ### Complete Implementation Guide
 
@@ -2214,7 +2280,7 @@ const Index: FC = () => {
   const entityPageHeaderBadges = useEntityPageHeaderBadges();
 
   return (
-    <PatternsWizardOverridesProvider
+    <AutoPatternsOverridesProvider
       value={{
         // ... other overrides
         entityPageHeaderSubtitle: {
@@ -2226,7 +2292,7 @@ const Index: FC = () => {
       }}
     >
       <WixPetsPage />
-    </PatternsWizardOverridesProvider>
+    </AutoPatternsOverridesProvider>
   );
 };
 ```
@@ -2268,7 +2334,7 @@ src/dashboard/
 
 1. **❌ DON'T return JSX components** - Return badge objects instead
 2. **❌ DON'T use direct configuration** - Use custom component overrides
-3. **❌ DON'T forget to register in PatternsWizardOverridesProvider**
+3. **❌ DON'T forget to register in AutoPatternsOverridesProvider**
 5. **❌ DON'T forget to export from index.ts** - Must export the function
 
 
@@ -2424,18 +2490,21 @@ Entity pages in **edit mode** support not only built-in actions (such as "Save"
       {
         "id": "sendEmail",
         "type": "custom",
-        "label": "Send Email"
+        "label": "Send Email",
+        "biName": "send-email-action"
       },
       {
         "id": "exportData",
         "type": "custom",
-        "label": "Export Data"
+        "label": "Export Data",
+        "biName": "export-data-action"
       },
       { "type": "divider" },
       {
         "id": "archiveEntity",
         "type": "custom",
-        "label": "Archive"
+        "label": "Archive",
+        "biName": "archive-entity-action"
       }
     ]
   }
@@ -2462,6 +2531,7 @@ export const myMoreAction: CustomEntityPageActionResolver = (params) => {
     onClick: () => {
       // Your custom logic here
     },
+    biName: 'my-more-action'  // MANDATORY: For analytics tracking
   };
 };
 ```
@@ -2487,9 +2557,12 @@ export const myMoreAction: CustomEntityPageActionResolver = (params) => {
 ✓ 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 resolver is exported and registered in the `actions` property of your `AutoPatternsOverridesProvider`
 ✓ The function signature matches `CustomEntityPageActionResolver`
 ✓ The returned object is a `ResolvedAction` (see [ResolvedAction Reference](./resolved_action.md))
+✓ **MANDATORY**: Every action configuration MUST include a `biName` property for analytics tracking
+✓ **MANDATORY**: `biName` must use descriptive, kebab-case naming (e.g., "send-email-action")
+✓ **MANDATORY**: `biName` must be unique across the application and follow the pattern `{action-purpose}-action`
 
 ---
 
@@ -2659,6 +2732,7 @@ export interface ResolvedAction {
   hidden?: boolean;
   tooltip?: string;
   skin?: string;
+  biName?: string;
 }
 ```
 
@@ -2669,6 +2743,7 @@ export interface ResolvedAction {
 - **`label`** (string): Text displayed in the button or menu item.
 - **`icon`** (IconElement): An icon component, typically from `@wix/wix-ui-icons-common`. Example: `icon: <Delete />`.
 - **`onClick`** (function): Handler function invoked when the user triggers the action. Can be async.
+- **`biName`** (string): Business intelligence name for analytics tracking. Used to identify the action in analytics and reporting systems. The value should match the `biName` specified in your action configuration.
 
 ### Optional Fields
 
@@ -2692,7 +2767,8 @@ return {
   icon: <Add />,
   onClick: () => {
     // Your action logic here
-  }
+  },
+  biName: 'create-action'  // MANDATORY: For analytics tracking
 };
 ```
 
@@ -2715,7 +2791,8 @@ return {
   disabled: total === 0,
   tooltip: total === 0 ? 'Select at least one item to export' : undefined,
   hidden: !userHasExportPermission,
-  skin: 'premium'
+  skin: 'premium',
+  biName: 'export_selected_items' // MANDATORY: For analytics tracking
 };
 ```
 
@@ -2805,7 +2882,7 @@ 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 { AutoPatternsOverridesProvider, AutoPatternsApp } from '@wix/auto-patterns';
 import { withDashboard } from '@wix/patterns';
 
 import { config } from './MyCollectionConfig.patterns';
@@ -2814,9 +2891,9 @@ const Index: FC = () => {
   return (
     <WixDesignSystemProvider features={{ newColorsBranding: true }}>
       <WixPatternsProvider>
-        <PatternsWizardOverridesProvider value={{ }}>
+        <AutoPatternsOverridesProvider value={{ }}>
           <AutoPatternsApp configuration={config} />
-        </PatternsWizardOverridesProvider>
+        </AutoPatternsOverridesProvider>
       </WixPatternsProvider>
     </WixDesignSystemProvider>
   );
@@ -2827,14 +2904,63 @@ export default withDashboard(Index);
 
 ---
 
+# AppContext
+
+The AppContext feature allows you to add components outside the main AutoPatternsApp flow while still accessing the collection data.
+
+## 1. Adding Components as Children
+
+Components that need to be rendered outside the main AutoPatternsApp interface (such as modals or side panels) should be passed as children:
+
+```tsx
+import { AutoPatternsApp } from '@wix/auto-patterns';
+import { MyModal } from './MyModal';
+import { MySidePanel } from './MySidePanel';
+
+<AutoPatternsApp configuration={config}>
+  <MyModal />
+  <MySidePanel />
+</AutoPatternsApp>
+```
+
+These children components are typically:
+- **Modals** - for custom actions, forms, or dialogs
+- **Side Panels** - for additional information or controls
+- **Overlay Components** - that need to appear on top of the main interface
+
+## 2. Accessing Collection Data
+
+Use the `useAppContext` hook to access the current collection items from within your child components:
+
+```tsx
+import React from 'react';
+import { useAppContext } from '@wix/auto-patterns';
+
+export const MyModal: React.FC = () => {
+  const { items } = useAppContext();
+
+  return (
+    <div>
+      <p>Current collection has {items.length} items</p>
+      {/* Your modal content */}
+    </div>
+  );
+};
+```
+
+The `items` array contains the current filtered and paginated collection data that matches what's displayed in the table/grid.
+
+---
+
 # 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`
+- **Always verify override implementation** - when implementing custom overrides, you MUST ensure they are correctly imported and passed to the `AutoPatternsOverridesProvider`
+- **CRITICAL: Error handling for custom actions** - Custom actions that make external API calls (using `fetch()`, `axios`, etc.) should NOT use `errorHandler.withErrorHandler`. Only Wix HTTP requests (httpClient from @wix/essentials, Wix APIs like wix/data and wix/stores, and httpClient.fetchWithAuth()) require errorHandler wrapping. See the "Error Handling for HTTP Requests" section for details.
 
-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:
+The `AutoPatternsOverridesProvider` 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.
 
@@ -2909,9 +3035,9 @@ export default function YourPage() {
   const entityPageHeaderBadges = useEntityPageHeaderBadges();
 
   return (
-    <PatternsWizardOverridesProvider value={{ actions, columns, slots, sections, components, modals, customDataSources, entityPageHeaderSubtitle, entityPageHeaderBadges }}>
+    <AutoPatternsOverridesProvider value={{ actions, columns, slots, sections, components, modals, customDataSources, entityPageHeaderSubtitle, entityPageHeaderBadges }}>
       <AutoPatternsApp configuration={config} />
-    </PatternsWizardOverridesProvider>
+    </AutoPatternsOverridesProvider>
   );
 }
 ```
@@ -2931,7 +3057,7 @@ For example:
 - Adding a new subtitle override → Update `../components/entityPageHeaderSubtitle/index.tsx` to include the new subtitle in the `useEntityPageHeaderSubtitle` hook
 - Adding a new badges override → Update `../components/entityPageHeaderBadges/index.tsx` to include the new badges in the `useEntityPageHeaderBadges` hook
 
-Without updating the hook index files, your implementations won't be available to the `PatternsWizardOverridesProvider`.
+Without updating the hook index files, your implementations won't be available to the `AutoPatternsOverridesProvider`.
 
 ## Common Override Mistakes to Avoid
 
@@ -3176,9 +3302,9 @@ export default function YourPage() {
   const columns = useColumns();
 
   return (
-    <PatternsWizardOverridesProvider value={{ columns }}>
+    <AutoPatternsOverridesProvider value={{ columns }}>
       <AutoPatternsApp configuration={config} />
-    </PatternsWizardOverridesProvider>
+    </AutoPatternsOverridesProvider>
   );
 }
 ```
@@ -3196,7 +3322,7 @@ your-page/
         ├── fullName.tsx  // Calculated column
         └── date.tsx      // Enhanced formatting with row context
 
-PatternsWizardOverridesProvider
+AutoPatternsOverridesProvider
  └── value.columns (from useColumns hook)
       ├── name
       ├── petInfo
@@ -3353,9 +3479,9 @@ export default function YourPage() {
   const components = useComponents();
 
   return (
-    <PatternsWizardOverridesProvider value={{ components }}>
+    <AutoPatternsOverridesProvider value={{ components }}>
       <AutoPatternsApp configuration={config} />
-    </PatternsWizardOverridesProvider>
+    </AutoPatternsOverridesProvider>
   );
 }
 ```
@@ -3484,7 +3610,7 @@ your-page/
     │   ├── combinedNameFields.tsx // Multiple fields override
     │   └── infoCard.tsx          // Standalone component
 
-PatternsWizardOverridesProvider
+AutoPatternsOverridesProvider
  └── value.components (from useComponents hook)
       ├── customNameField
       ├── combinedNameFields
@@ -3554,7 +3680,7 @@ To enable sections, add the `sections` configuration to your table configuration
 
 ### Custom Data Source Hook Structure
 
-Custom data sources are implemented through the `useCustomDataSources` hook in your `PatternsWizardOverridesProvider`:
+Custom data sources are implemented through the `useCustomDataSources` hook in your `AutoPatternsOverridesProvider`:
 
 ```tsx
 import { useCustomDataSources } from '../components/customDataSources';
@@ -3563,9 +3689,9 @@ export default function YourPage() {
   const customDataSources = useCustomDataSources();
 
   return (
-    <PatternsWizardOverridesProvider value={{ customDataSources }}>
+    <AutoPatternsOverridesProvider value={{ customDataSources }}>
       <AutoPatternsApp configuration={config} />
-    </PatternsWizardOverridesProvider>
+    </AutoPatternsOverridesProvider>
   );
 }
 ```
@@ -3639,22 +3765,7 @@ When implementing custom data sources, you need to map your data source field ty
 - **Reference fields** → `'REFERENCE'`
 - **URL fields** → `'URL'`
 
-### Error Handling
-
-Custom data sources should include proper error handling:
 
-```tsx
-actions: {
-  get: async (entityId: string) => {
-    try {
-      const result = await yourDataSourceCall(entityId);
-      return result;
-    } catch (error) {
-      throw new Error(`Failed to fetch entity: ${error.message}`);
-    }
-  }
-}
-```
 
 ### Validation Requirements
 
@@ -3696,9 +3807,9 @@ export default function YourPage() {
   const customDataSources = useCustomDataSources();
 
   return (
-    <PatternsWizardOverridesProvider value={{ customDataSources }}>
+    <AutoPatternsOverridesProvider value={{ customDataSources }}>
       <AutoPatternsApp configuration={config} />
-    </PatternsWizardOverridesProvider>
+    </AutoPatternsOverridesProvider>
   );
 }
 ```
@@ -3707,7 +3818,7 @@ export default function YourPage() {
 
 ### Creating Section Renderers
 
-Section renderers are functions that determine how to group items and what information to display in section headers. They must be provided through the `PatternsWizardOverridesProvider`.
+Section renderers are functions that determine how to group items and what information to display in section headers. They must be provided through the `AutoPatternsOverridesProvider`.
 
 #### Function Signature
 
@@ -3833,9 +3944,9 @@ import * as sections from './components/sections';
 import * as columns from './components/columns';
 import * as actions from './components/actions';
 
-<PatternsWizardOverridesProvider value={{ sections, columns, actions }}>
+<AutoPatternsOverridesProvider value={{ sections, columns, actions }}>
   <AutoPatternsApp configuration={config} />
-</PatternsWizardOverridesProvider>
+</AutoPatternsOverridesProvider>
 ```
 
 ### Important Notes
@@ -3981,9 +4092,9 @@ export default function YourPage() {
   const slots = useSlots();
 
   return (
-    <PatternsWizardOverridesProvider value={{ slots }}>
+    <AutoPatternsOverridesProvider value={{ slots }}>
       <AutoPatternsApp configuration={config} />
-    </PatternsWizardOverridesProvider>
+    </AutoPatternsOverridesProvider>
   );
 }
 ```
@@ -4001,3 +4112,141 @@ export default function YourPage() {
 Slots provide a powerful way to enhance collection pages with custom functionality while maintaining the structure and features of the AutoPatterns system.
 
 ---
+
+# Error Handling for HTTP Requests
+
+**⚠️ CRITICAL**: When implementing custom data sources that make HTTP requests, you **MUST** wrap specific HTTP calls with proper error handling. This ensures consistent error management, prevents unhandled promise rejections, and provides better user experience.
+
+## What Requires Error Handling
+
+**ONLY the following HTTP requests** in your custom data source actions must be wrapped with `errorHandler`:
+
+- **httpClient from @wix/essentials** (e.g., `httpClient.request(getDummyEntity(...))`)
+- **Wix APIs** (e.g., `wix/data`, `wix/stores`, `items.get()`, `items.insert()`, `collections.getDataCollection()`)
+- **httpClient.fetchWithAuth()** calls
+
+**DO NOT use errorHandler with:**
+
+- **External API calls** using `fetch()`, `axios.get()`, or other HTTP libraries
+- **Custom HTTP clients** (e.g., any non-Wix HTTP request library)
+- **Third-party API calls** using non-Wix HTTP methods
+
+**EXCEPTION**: SDK actions that you get from the AutoPatterns SDK (e.g., `sdk.getOptimisticActions()`, `sdk.getSchema()`) do NOT need error handling as they are already handled internally.
+
+## Why Error Handling is Required
+
+Custom data sources often make HTTP requests to Wix APIs and services. Without proper error handling:
+
+- **Unhandled Promise Rejections**: HTTP failures can crash your application
+- **Poor User Experience**: Users don't get meaningful error messages
+- **Inconsistent Error Management**: Different parts of your app handle errors differently
+- **Debugging Difficulties**: Hard to trace and diagnose API failures
+
+## Using @wix/essentials errorHandler
+
+The recommended approach is to use the `errorHandler` from `@wix/essentials` package, which provides consistent error handling patterns across Wix applications.
+
+### Installation
+
+First, ensure `@wix/essentials` is installed in your project:
+
+```bash
+npm install @wix/essentials
+```
+
+### Basic Error Handling Pattern
+
+Wrap Wix HTTP requests in your custom data source actions with `errorHandler.withErrorHandler`:
+
+```typescript
+import { errorHandler } from '@wix/essentials';
+
+// In your custom data source actions
+actions: {
+  get: async (entityId: string) => {
+    return errorHandler.withErrorHandler(
+      async () => {
+        const response = await httpClient.request(
+          getDummyEntity({ dummyEntityId: entityId })
+        );
+        return response.data.dummyEntity;
+      },
+      {}
+    );
+  },
+}
+```
+
+### Examples of HTTP Requests That Need Error Handling
+
+**httpClient from @wix/essentials:**
+
+```typescript
+return errorHandler.withErrorHandler(async () => {
+  const response = await httpClient.request(
+    getDummyEntity({ dummyEntityId: entityId })
+  );
+  return response.data.dummyEntity;
+}, {});
+```
+
+**Wix APIs (wix/data, wix/stores):**
+
+```typescript
+return errorHandler.withErrorHandler(async () => {
+  return await items.get(collectionId, entityId);
+}, {});
+```
+
+**httpClient.fetchWithAuth() calls:**
+
+```typescript
+return errorHandler.withErrorHandler(async () => {
+  const response = await httpClient.fetchWithAuth("/api/data");
+  return await response.json();
+}, {});
+```
+
+### Examples of HTTP Requests That Do NOT Need Error Handling
+
+**External API calls (using fetch, axios, etc.):**
+
+```typescript
+// ✅ CORRECT - No error handling needed for external APIs
+const response = await fetch("https://api.example.com/data");
+return await response.json();
+
+// ✅ CORRECT - No error handling needed for axios
+const response = await axios.get("https://api.example.com/data");
+return response.data;
+```
+
+**Third-party HTTP libraries:**
+
+```typescript
+// ✅ CORRECT - No error handling needed for third-party HTTP clients
+const response = await someThirdPartyHttpClient.get("/data");
+return response.data;
+```
+
+## Integration with AutoPatterns Error Handling
+
+The error handling in your custom data source integrates seamlessly with AutoPatterns' built-in error handling:
+
+1. **User-Friendly Messages**: Errors are displayed to users in a consistent format
+2. **Retry Mechanisms**: Users can retry failed operations
+3. **Loading States**: Proper loading states during HTTP requests
+4. **Error Boundaries**: Errors are caught and handled gracefully
+
+## Validation Checklist
+
+Before deploying your custom data source, ensure:
+
+✅ **httpClient from @wix/essentials** is wrapped with `errorHandler.withErrorHandler`
+✅ **Wix APIs (wix/data, wix/stores, etc)** are wrapped with `errorHandler.withErrorHandler`
+✅ **httpClient.fetchWithAuth()** calls are wrapped with `errorHandler.withErrorHandler`
+✅ **External API calls are NOT wrapped** with errorHandler (e.g., fetch(), axios, third-party HTTP clients)
+✅ **SDK actions are used directly** without error handling (e.g., `sdk.getOptimisticActions()`, `sdk.getSchema()`)
+✅ **@wix/essentials** is installed as a dependency
+
+---