@wix/auto-patterns 1.40.0 → 1.42.0

package/mcp-docs/custom_overrides.md

@@ -179,6 +179,40 @@ function columnOverride(props: IColumnValue<string>) {
 }
 ```
 
+### Important Guidelines for Column Functions
+
+**Column ID Naming**: Column IDs are always in camelCase, and your function names should match exactly:
+- Column ID: `petName` → Function name: `petName`
+- Column ID: `isVaccinated` → Function name: `isVaccinated`
+- Column ID: `lastActivity` → Function name: `lastActivity`
+
+**React Limitations**: Column override functions are **NOT React function components**, which means:
+- ❌ **No React hooks allowed** (useState, useEffect, useContext, etc.)
+- ❌ **No custom hook calls** inside the function
+- ✅ **Only pure rendering logic** with JSX return
+
+**Using Hooks in Column Overrides**: If you need React hooks, create a separate React component and return it from your column function:
+
+```typescript
+// ❌ WRONG - Hooks directly in column function
+export function myColumn({ value, row }: IColumnValue<string>) {
+  const [state, setState] = useState(value); // ERROR: Hooks not allowed!
+  return <span>{state}</span>;
+}
+
+// ✅ CORRECT - Hooks in separate component
+function MyColumnComponent({ value, row }: IColumnValue<string>) {
+  const [state, setState] = useState(value); // ✅ Hooks allowed in React components
+  const contextValue = useContext(MyContext); // ✅ Context hooks work here
+
+  return <span>{state} - {contextValue}</span>;
+}
+
+export function myColumn(props: IColumnValue<string>) {
+  return <MyColumnComponent {...props} />; // ✅ Return React component
+}
+```
+
 ### Type-Specific Examples
 
 The generic type `T` in `IColumnValue<T>` should match your field's data type:
@@ -440,6 +474,9 @@ AutoPatternsOverridesProvider
 
 ### Important Guidelines
 
+- **Function Naming**: Column function names must be in camelCase and match the column ID exactly
+- **No React Hooks**: Column functions are NOT React components - no useState, useEffect, useContext, etc.
+- **Hook Workaround**: If you need hooks, create a separate React component and return it from your column function
 - **TypeScript Usage**: Always use `IColumnValue<T>` and import it from `@wix/auto-patterns/types`
 - **Type Matching**: Ensure the generic type `T` matches your field's actual data type (string, number, boolean, etc.)
 - **Performance**: Remember that column functions are called for every row, so keep calculations lightweight

package/mcp-docs/error_handling.md

@@ -11,12 +11,53 @@
 
 **⚠️ 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:**
@@ -154,12 +195,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:**
@@ -207,25 +304,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
 
@@ -236,7 +428,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**
 
@@ -245,6 +437,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
@@ -437,9 +638,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';
 

package/mcp-docs/index.md

@@ -26,6 +26,10 @@ This index maps user requests to the appropriate section IDs for fetching releva
 **Topics**: Collection page components, table/grid layouts, column configuration
 **Keywords**: collection page, table/grid configuration, layout arrays, Table/Grid layouts, column setup, customColumns, view switching, displaying collections, list views
 
+### ID: `views`
+**Topics**: Views configuration, presets, categories, filters integration, column preferences, default view
+**Keywords**: views, presets, categories, columnPreferences, filters, default view, All items, learnMore, placeholder, showTotal
+
 ### ID: `collection_page_actions`
 **Topics**: Page-level actions, create actions, custom collection actions, action menus
 **Keywords**: page-level actions, collection actions, create actions, adding new items, primaryActions, secondaryActions, action menus, custom actions, navigation