@wix/auto-patterns 1.39.0 → 1.41.0

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

@@ -248,52 +248,16 @@ export interface AppConfig {
           };
           actionCell?: {
             primaryAction?: {
-              item: {
-                id: string; // Unique identifier for the action
-                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'
-                  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
-                      };
-                    };
-                  };
-                };
-              };
+              // Single primary action configuration
+              item: ActionItem;
               alwaysVisible?: boolean; // Whether to always show the primary action (not just on hover)
+            } | {
+              // Multiple primary actions configuration
+              items: ActionItem[];
+              alwaysVisible?: boolean; // Whether to always show the primary actions (not just on hover)
             };
             secondaryActions?: {
-              items: {}[]; // Array of action configurations, same structure as primaryAction.item, can include dividers
+              items: ActionItem[]; // Array of action configurations, 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)
             };
@@ -376,6 +340,9 @@ export interface AppConfig {
              * Whether drag and drop is enabled. When enabled, the [schema](./schema_config.md) must support a "move" action.
              */
             enabled: boolean;
+            dragAndDropCancel?: {
+              id?: string; // Optional ID that maps to a dynamic drag-and-drop cancel override function
+            };
           };
           layout: [ // Array of layout items that define what components to render
             {
@@ -522,6 +489,49 @@ export interface AppConfig {
   }[];
 }
 
+type ActionItem = {
+  id: string; // Unique identifier for the action
+  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'
+    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
+        };
+      };
+    };
+  };
+};
+
 type LayoutContent =
   | {
       type: 'field';
@@ -1607,12 +1617,54 @@ The ActionCell feature adds an interactive action column to collection tables or
 
 ## Placement and Structure
 
-The ActionCell has a two-level structure:
-* `primaryAction`: A single prominent action shown directly in the table/grid row
+The ActionCell has a flexible structure supporting both single and multiple primary actions:
+* `primaryAction`: Type: `ActionCellPrimaryAction | ActionCellPrimaryActions` - Can be either a single action or multiple actions shown directly in the table/grid row
+  - **Single Primary Action** (`ActionCellPrimaryAction`): `{ item: ActionCellItemConfig, alwaysVisible?: boolean }`
+  - **Multiple Primary Actions** (`ActionCellPrimaryActions`): `{ items: ActionCellItemConfig[], alwaysVisible?: boolean }`
 * `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.
 
+### Multiple Primary Actions
+
+**New Feature**: Primary actions now support both single and multiple action configurations:
+
+#### Single Primary Action Configuration
+```json
+{
+  "primaryAction": {
+    "item": {
+      "id": "editItem",
+      "type": "update",
+      "label": "Edit",
+      "biName": "edit-item-action"
+    },
+    "alwaysVisible": false
+  }
+}
+```
+
+#### Multiple Primary Actions Configuration
+```json
+{
+  "primaryAction": {
+    "items": [
+      {
+        "id": "editItem",
+        "type": "update",
+        "label": "Edit"
+      },
+      {
+        "id": "quickApprove",
+        "type": "custom",
+        "label": "Approve"
+      }
+    ],
+    "alwaysVisible": true
+  }
+}
+```
+
 ### Primary Action Visibility Control
 
 **New Feature**: Primary actions now support visibility control through the `alwaysVisible` property. By default, primary actions follow standard table interaction patterns (typically visible on hover), but you can configure them to be always visible for improved accessibility and user discovery.
@@ -1880,25 +1932,37 @@ Follow this decision process when implementing ActionCell:
    - 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`
+2. **Primary vs Secondary**: Choose the most common/important actions as primary:
+   - **Single Primary Action**: Most common operation (typically Edit) → Place in `primaryAction.item`
+   - **Multiple Primary Actions**: 2-3 most common operations → Place in `primaryAction.items` array
    - Less common operations → Place in `secondaryActions.items` array
 
-3. **Primary Action Visibility Strategy**:
+3. **Single vs Multiple Primary Actions**:
+   - **Use Single Primary Action** when:
+     - You have one dominant action (e.g., "Edit" for most entities)
+     - Space is limited or you want a clean, minimal interface
+     - The action is contextually obvious
+   - **Use Multiple Primary Actions** when:
+     - You have 2-3 equally important actions (e.g., "Edit", "Approve", "Reject")
+     - Users frequently need to perform multiple actions in sequence
+     - Actions are complementary and often used together
+     - You want to reduce clicks by avoiding secondary menus
+
+4. **Primary Action Visibility Strategy**:
    - **Standard Visibility** (`alwaysVisible: false` or omitted): Use for most cases where actions appear on interaction
    - **Always Visible** (`alwaysVisible: true`): Use for critical actions that need constant visibility or when user discovery is important
 
-4. **Inline Secondary Actions Strategy**:
+5. **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
 
-5. **Update Action Mode**:
+6. **Update Action Mode**:
    - Complex, full-entity edits → Use `mode: "page"` to navigate to entity page
 
-6. **Custom Implementation**:
+7. **Custom Implementation**:
    - For `custom` actions, you must provide implementations in your code and register them with `AutoPatternsOverridesProvider`
 
 ### ActionCell Validation Checklist
@@ -1912,8 +1976,12 @@ AI agents should verify these requirements before generating ActionCell configur
 ✓ Delete action has a modal configuration
 ✓ Custom actions match implementations in overrides
 ✓ At least one of `primaryAction` or `secondaryActions` is provided
+✓ Primary action configuration is valid (Type: `ActionCellPrimaryAction | ActionCellPrimaryActions`):
+  - Single primary action (`ActionCellPrimaryAction`): `{ item: ActionCellItemConfig, alwaysVisible?: boolean }`
+  - Multiple primary actions (`ActionCellPrimaryActions`): `{ items: ActionCellItemConfig[], alwaysVisible?: boolean }`
 ✓ `alwaysVisible` property on primary actions (if specified) is a boolean value
 ✓ Primary action visibility is properly considered for UX (use `alwaysVisible: true` for critical actions)
+✓ Multiple primary actions are limited to 2-3 actions for optimal UX
 ✓ `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
@@ -4670,12 +4738,53 @@ Slots provide a powerful way to enhance collection pages with custom functionali
 
 **⚠️ 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.
 
+## 🚨 GOLDEN RULE: If it's a Wix Library, Wrap it with errorHandler!
+
+**Simple Rule for AI Agents:**
+- **ANY Wix SDK call** from libraries with `@wix/` prefix → **ALWAYS wrap with `errorHandler.withErrorHandler`**
+- This includes: `@wix/data`, `@wix/stores`, `@wix/events`, `@wix/bookings`, `@wix/crm`, and ALL other `@wix/*` packages
+- **NO exceptions** - all Wix SDK calls must use error handling
+
+### ❌ DON'T DO THIS (Common Mistake)
+
+```typescript
+import { items } from '@wix/data';
+
+// ❌ WRONG - No errorHandler wrapping
+async function getAllPets() {
+  try {
+    const result = await items.query('WixPets').find();
+    return result.items;
+  } catch (error) {
+    console.error(error);
+    throw error;
+  }
+}
+```
+
+### ✅ DO THIS (Correct Pattern)
+
+```typescript
+import { items } from '@wix/data';
+import { errorHandler } from '@wix/essentials';
+
+// ✅ CORRECT - Wix SDK call wrapped with errorHandler
+async function getAllPets() {
+  return errorHandler.withErrorHandler(
+    async () => {
+      const result = await items.query('WixPets').find();
+      return result.items;
+    },
+    {}
+  );
+}
+```
 ## What Requires Error Handling
 
 **ONLY the following HTTP requests** in your custom data source actions must be wrapped with `errorHandler.withErrorHandler`:
 
 - **httpClient from @wix/essentials** (e.g., `httpClient.request(getDummyEntity(...))`)
-- **Wix APIs** (e.g., `wix/data`, `wix/stores`, `items.get()`, `items.insert()`, `collections.getDataCollection()`)
+- **Wix API calls from libraries with `wix/` prefix** (e.g., `@wix/data`, `@wix/stores`, `@wix/events`, `@wix/bookings`, `collections.getDataCollection()`, etc.)
 - **httpClient.fetchWithAuth()** calls
 
 **DO NOT use errorHandler.withErrorHandler with:**
@@ -4813,12 +4922,68 @@ return errorHandler.withErrorHandler(async () => {
 }, {});
 ```
 
-**Wix APIs (wix/data, wix/stores):**
+**Wix APIs (@wix/data, @wix/stores, @wix/crm, etc.):**
 
 ```typescript
+import { items } from '@wix/data';
+import { errorHandler } from '@wix/essentials';
+
+// ✅ CORRECT: Wix Data API calls wrapped with errorHandler
 return errorHandler.withErrorHandler(async () => {
   return await items.get(collectionId, entityId);
 }, {});
+
+// ✅ CORRECT: Query operations wrapped with errorHandler
+return errorHandler.withErrorHandler(async () => {
+  return await items.query('WixPets').find();
+}, {});
+
+// ✅ CORRECT: Insert operations wrapped with errorHandler
+return errorHandler.withErrorHandler(async () => {
+  return await items.insert(collectionId, dataItem);
+}, {});
+
+// ✅ CORRECT: Update operations wrapped with errorHandler
+return errorHandler.withErrorHandler(async () => {
+  return await items.update(collectionId, dataItem);
+}, {});
+
+// ✅ CORRECT: Delete operations wrapped with errorHandler
+return errorHandler.withErrorHandler(async () => {
+  return await items.remove(collectionId, itemId);
+}, {});
+
+// ✅ CORRECT: Bulk delete operations wrapped with errorHandler
+return errorHandler.withErrorHandler(async () => {
+  return await items.bulkRemove(collectionId, itemIds);
+}, {});
+```
+
+**All Other Wix API calls from libraries with `@wix/` prefix:**
+
+```typescript
+import { stores } from '@wix/stores';
+import { events } from '@wix/events';
+import { bookings } from '@wix/bookings';
+import { contacts } from '@wix/crm';
+import { errorHandler } from '@wix/essentials';
+
+// ✅ CORRECT: All Wix API calls from @wix/* libraries must be wrapped
+return errorHandler.withErrorHandler(async () => {
+  return await stores.queryProducts().find();
+}, {});
+
+return errorHandler.withErrorHandler(async () => {
+  return await events.queryEvents().find();
+}, {});
+
+return errorHandler.withErrorHandler(async () => {
+  return await bookings.queryBookings().find();
+}, {});
+
+return errorHandler.withErrorHandler(async () => {
+  return await contacts.queryContacts().find();
+}, {});
 ```
 
 **httpClient.fetchWithAuth() calls:**
@@ -4866,25 +5031,120 @@ The error handling in your custom data source integrates seamlessly with AutoPat
 **BEFORE implementing ANY custom action or data source, AI agents MUST verify:**
 
 ### ✅ Error Handling Requirements
-- **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
+- ✅ **ALL Wix API calls from `@wix/*` libraries** are wrapped with `errorHandler.withErrorHandler`
+  - Including: `@wix/data`, `@wix/stores`, `@wix/events`, `@wix/bookings`, `@wix/crm`, and ALL other `@wix/*` packages
+- ✅ **httpClient from @wix/essentials** is 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
+
+### ✅ Correct API Signature Verification
+- ✅ **Check TypeScript/linter errors FIRST** - they tell you when the API is used incorrectly
+- ✅ **Verify imports are correct** - `import { items } from '@wix/data'` (not default imports)
+- ✅ **Use correct method signatures** - refer to the API reference section
+- ✅ **Pass correct parameters** - verify collectionId, itemId, and data structure
+- ✅ **Handle return values correctly** - `.find()` returns `{ items, ... }`, not just items array
 
 ### ✅ Implementation Checklist
-- **Read this error handling documentation** before implementing any custom action
-- **Identify the type of HTTP request** being made (Wix vs External)
-- **Apply the correct error handling pattern** based on the request type
-- **Test error scenarios** to ensure proper error handling
-- **Verify error messages** are user-friendly and actionable
+- ✅ **Read this error handling documentation** before implementing any custom action
+- ✅ **Identify the type of HTTP request** being made (Wix vs External)
+- ✅ **Apply the correct error handling pattern** based on the request type
+- ✅ **Test error scenarios** to ensure proper error handling
+- ✅ **Verify error messages** are user-friendly and actionable
+- ✅ **Run linter after implementation** to catch any API usage errors
 
 ### ✅ Common Mistakes to Avoid
 - ❌ **NEVER** wrap external API calls (fetch, axios) with errorHandler
 - ❌ **NEVER** wrap SDK methods (sdk.getOptimisticActions) with errorHandler
 - ❌ **NEVER** forget to wrap Wix HTTP requests with errorHandler
 - ❌ **NEVER** implement custom actions without reading this documentation first
+- ❌ **NEVER** use incorrect API signatures (e.g., `items.queryDataItems()` instead of `items.query()`)
+- ❌ **NEVER** ignore TypeScript/linter errors - they indicate incorrect API usage
+- ❌ **NEVER** use try-catch blocks instead of errorHandler for Wix SDK calls
+
+## 🎯 Common Wix SDK API Reference
+
+### @wix/data - Data Items API
+
+**ALWAYS use with errorHandler.withErrorHandler:**
+
+```typescript
+import { items } from '@wix/data';
+import { errorHandler } from '@wix/essentials';
+
+// Query all items
+errorHandler.withErrorHandler(async () => {
+  const result = await items.query('WixPets').find();
+  return result.items;
+}, {});
+
+// Query with filters
+errorHandler.withErrorHandler(async () => {
+  const result = await items.query('WixPets')
+    .contains('name', 'fluffy')
+    .eq('age', 5)
+    .find();
+  return result.items;
+}, {});
+
+// Get single item by ID
+errorHandler.withErrorHandler(async () => {
+  const item = await items.get('WixPets', itemId);
+  return item;
+}, {});
+
+// Insert new item
+errorHandler.withErrorHandler(async () => {
+  const newItem = await items.insert('WixPets', { name: 'Fluffy', age: 5 });
+  return newItem;
+}, {});
+
+// Update existing item
+errorHandler.withErrorHandler(async () => {
+  const updatedItem = await items.update('WixPets', { _id: itemId, name: 'Updated Name' });
+  return updatedItem;
+}, {});
+
+// Delete single item
+errorHandler.withErrorHandler(async () => {
+  await items.remove('WixPets', itemId);
+}, {});
+
+// Bulk delete items
+errorHandler.withErrorHandler(async () => {
+  await items.bulkRemove('WixPets', [itemId1, itemId2, itemId3]);
+}, {});
+```
+
+### @wix/essentials - Error Handler
+
+```typescript
+import { errorHandler } from '@wix/essentials';
+
+// Basic pattern (recommended)
+errorHandler.withErrorHandler(
+  async () => {
+    // Your Wix SDK call here
+    return await items.query('WixPets').find();
+  },
+  {
+    // Optional: Custom error handling
+    handleError: (error) => {
+      console.error('Custom error handling:', error);
+      throw error; // Re-throw to show error to user
+    },
+  }
+);
+
+// Simple pattern (empty options object)
+errorHandler.withErrorHandler(
+  async () => {
+    return await items.query('WixPets').find();
+  },
+  {}
+);
+```
 
 ## Quick Decision Tree for AI Agents
 
@@ -4895,7 +5155,7 @@ The error handling in your custom data source integrates seamlessly with AutoPat
    - **YES** → Go to step 2
 
 2. **What type of HTTP request?**
-   - **Wix APIs** (httpClient, wix/data, wix/stores) → **WRAP with errorHandler.withErrorHandler**
+   - **Wix API libraries with `@wix/` prefix** (@wix/data, @wix/stores, @wix/events, @wix/bookings, @wix/crm) → **WRAP with errorHandler.withErrorHandler**
    - **External APIs** (fetch, axios, third-party) → **NO errorHandler needed**
    - **SDK methods** (sdk.getOptimisticActions, sdk.getSchema) → **NO errorHandler needed**
 
@@ -4904,6 +5164,15 @@ The error handling in your custom data source integrates seamlessly with AutoPat
    - **External requests** are NOT wrapped
    - **SDK methods** are used directly
 
+## 🚨 TypeScript Error Detection
+
+**CRITICAL**: If you see TypeScript/linter errors when using Wix SDK methods:
+
+1. ✅ **Check the import** - Make sure you're importing from the correct package
+2. ✅ **Check the method signature** - Verify you're using the correct API signature (refer to the API reference above)
+3. ✅ **Check errorHandler wrapping** - Ensure the call is wrapped with `errorHandler.withErrorHandler`
+4. ✅ **Run linter** - Read the linter error message carefully; it tells you what's wrong
+
 ## Complete Examples for All Custom Action Types
 
 ### ActionCell Custom Actions
@@ -5096,9 +5365,44 @@ export const myCustomDataSource = async (collectionId: string, context: any) =>
 };
 ```
 
+### Actions Using Wix API Libraries (REQUIRES errorHandler)
+
+**Example 7: Action using Wix API libraries with `wix/` prefix (REQUIRES errorHandler)**
+```typescript
+import { errorHandler } from '@wix/essentials';
+import { data } from '@wix/data';
+import { stores } from '@wix/stores';
+import { CustomActionCellActionResolver } from '@wix/auto-patterns';
+
+export const syncWithWixData: CustomActionCellActionResolver = (params) => {
+  const { actionParams, sdk } = params;
+  const { item } = actionParams;
+
+  return {
+    label: 'Sync with Wix Data',
+    icon: <SyncIcon />,
+    onClick: () => {
+      // ✅ CORRECT: Wix API library calls wrapped with errorHandler
+      errorHandler.withErrorHandler(
+        async () => {
+          // Using @wix/data library
+          const dataResult = await data.query('MyCollection').eq('id', item.id).find();
+
+          // Using @wix/stores library
+          const productResult = await stores.queryProducts().eq('sku', item.sku).find();
+
+          return { dataResult, productResult };
+        },
+        {}
+      );
+    },
+  };
+};
+```
+
 ### Actions Using SDK Methods (NO errorHandler needed)
 
-**Example 7: Action using SDK methods (NO errorHandler needed)**
+**Example 8: Action using SDK methods (NO errorHandler needed)**
 ```typescript
 import { CustomActionCellActionResolver } from '@wix/auto-patterns';