@wix/auto-patterns 1.33.0 → 1.35.0

package/docs/GETTING_STARTED.md

@@ -0,0 +1,98 @@
+# Getting Started
+*Build your first dashboard page on Patterns using Cursor.*
+
+## Library Installations
+Run the following command to install the library and its peer dependencies:
+```bash
+yarn add @wix/auto-patterns @wix/patterns @wix/design-system react-router-dom
+```
+
+## MCP Installations
+
+* [Install Business Schema MCP in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=business-schema&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAd2l4L2J1c2luZXNzLXNjaGVtYS1tY3AiXX0%3D)
+* [Install Auto Patterns MCP in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=auto-patterns&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJAd2l4L2F1dG8tcGF0dGVybnMtbWNwIl19)
+
+## Working with Auto Patterns
+A typical usage of Auto Patterns is to render a `AutoPatternsApp` component with a configuration object. You don't need to do it manually, but generate it through Cursor's chat.
+You can write a prompt like this:
+```
+I want a dashboard page for sessions, use wix.bookings.v1.sessions fqdn for that.
+```
+
+Then Cursor will retrieve the schema for the `wix.bookings.v1.sessions` FQDN and create an Auto Patterns configuration with custom data source.
+
+Then, you can run your app and see the results.
+According to the results, you can ask Cursor to improve the configuration.
+For example, you can ask Cursor to add specific filters, actions, or custom columns.
+
+## Handling Translations
+You should provide translated values everywhere you configure or render text content, just like you do in the rest of your app.
+
+Example to properties in the configuration that need a translated content:
+- Page titles
+- Column names
+- Action labels
+
+Code Example: (props that are not relevant to translation are omitted)
+```ts
+import { AppConfig, AutoPatternsApp } from '@wix/auto-patterns';
+import { useTranslation } from 'react-i18next';
+
+const MyPage = () => {
+  const { t } = useTranslation();
+
+  const config: AppConfig = {
+    pages: [
+      {
+        id: 'wixPets-collection',
+        type: 'collectionPage',
+        collectionPage: {
+          title: { text: t('pages.pets.title') },
+          actions: {
+            primaryActions: {
+              type: 'action',
+              action: {
+                item: {
+                  id: 'createPet',
+                  label: t('actions.create'),
+                  type: 'create',
+                  create: { mode: 'page', page: { id: 'wixPets-entity' } },
+                },
+              },
+            },
+          },
+          components: [
+            {
+              type: 'collection',
+              entityPageId: 'wixPets-entity',
+              layout: [
+                {
+                  type: 'Table',
+                  table: {
+                    columns: [
+                      { id: 'name', name: t('columns.name') },
+                      { id: 'age', name: t('columns.age') },
+                      { id: 'owner', name: t('columns.owner') },
+                    ],
+                  },
+                },
+              ],
+            },
+          ],
+        },
+      },
+      {
+        id: 'wixPets-entity',
+        type: 'entityPage',
+        entityPage: {
+          title: { text: t('pages.pets.detailsTitle') },
+        },
+      },
+    ],
+  };
+
+  return <AutoPatternsApp configuration={config} />;
+};
+
+export default MyPage;
+```

package/docs/OVERVIEW.md

@@ -0,0 +1,54 @@
+# Auto Patterns Overview
+
+## What is Auto Patterns?
+
+Auto Patterns is our AI-oriented library that lets anyone (Devs, PMs, UX) create rich dashboards with ease using Cursor.
+
+## Key Concepts
+
+### Configuration-Driven Development
+Instead of manually building collection pages, entity forms, and data management interfaces, Auto Patterns allows you to define everything through a TypeScript configuration object that conforms to the `AppConfig` interface. This approach:
+
+- Reduces development time
+- Makes experience intuitive and expected
+- Minimizes bugs
+- Simplifies maintenance
+
+### Relationship with @wix/patterns
+Auto Patterns serves as a **configuration layer** on top of `@wix/patterns` by:
+
+- **Configuration-driven approach**: Instead of imperatively composing `@wix/patterns` components, you define behavior through TypeScript configuration objects
+- **Pre-built component combinations**: Uses existing `@wix/patterns` components like `CollectionPage`, `Table`, `Grid`, and `EntityPage`, but configures them automatically based on your AppConfig
+- **Simplified integration**: Handles the wiring between `@wix/patterns` components, hooks, and providers so you don't need to set them up manually
+- **Declarative API**: Transforms complex component composition patterns into simple configuration properties
+
+## When to Use Auto Patterns
+
+### Perfect For:
+- **Collection management pages** (lists, tables, grids)
+- **Entity detail/edit pages** (forms, CRUD operations)
+- **Teams standardizing** UI patterns across applications
+
+## Core Components
+
+### AutoPatternsApp
+The main component that renders your entire application based on configuration:
+
+```tsx
+import { AutoPatternsApp } from '@wix/auto-patterns';
+import { config } from './myConfig.patterns';
+
+const MyPage = () => (
+  <AutoPatternsApp configuration={config} />
+);
+```
+
+### AppConfig Structure
+The heart of Auto Patterns - a TypeScript configuration that defines:
+
+- **Pages**: Collection pages (lists/tables) and entity pages (forms)
+- **Data sources**: FQDN-based Wix entities, Wix Data Collections (CMS) or custom data sources
+- **Actions**: Create, edit, delete, and custom operations
+- **Filters**: Search and filtering capabilities
+- **Layouts**: Table, grid, and form layouts
+- **Customizations**: Column overrides, custom components, and styling

package/docs/documentation.yaml

@@ -0,0 +1,11 @@
+apiDoc:
+  title: Auto Patterns
+  description: Auto Patterns documentation
+  category: fe-guild
+  markdownOnlyAutoUpdate: true
+  gitUrl: https://github.com/wix-private/auto-cairo/
+  docs:
+    - file: ./GETTING_STARTED.md
+      title: Getting Started
+    - file:  ./OVERVIEW.md
+      title: Overview

package/{dist/docs → mcp-docs}/action_cell.md

@@ -40,6 +40,7 @@ Both properties are optional, but at least one should be provided for the Action
      - Browser interactions (alerts, downloads)
      - Complex operations
    - ⚠️ Requires implementation: Must register action in overrides
+   - ⚠️ **CRITICAL: Error Handling Required** - When implementing custom actions that make HTTP requests, you MUST read the "Error Handling for HTTP Requests" section and apply the correct error handling patterns. Wix HTTP requests require `errorHandler.withErrorHandler`, while external API calls should NOT use errorHandler.
 
 ### Action Appearance: The `skin` Property
 
@@ -139,7 +140,7 @@ Custom actions execute JavaScript code that you define. These actions receive pa
            },
            successToast: 'Pet details downloaded',
            errorToast: (err, {retry}) => ({
-             message: 'Download failed',
+             text: 'Download failed',
              action: { text: 'Retry', onClick: retry }
            })
          });
@@ -149,6 +150,53 @@ Custom actions execute JavaScript code that you define. These actions receive pa
    };
    ```
 
+   **⚠️ CRITICAL: Error Handling for HTTP Requests**
+
+   The example above uses SDK methods which don't require error handling. However, if your custom action makes HTTP requests, you MUST follow the error handling patterns:
+
+   **For Wix HTTP requests (httpClient, wix/data, wix/stores):**
+   ```typescript
+   import { errorHandler } from '@wix/essentials';
+
+   export const myAction: CustomActionCellSecondaryActionResolver = (params) => {
+     return {
+       label: 'My Action',
+       icon: <MyIcon />,
+       onClick: () => {
+         // ✅ CORRECT: Wix API call wrapped with errorHandler
+         errorHandler.withErrorHandler(
+           async () => {
+             const response = await httpClient.request(
+               myWixApiCall({ data: params.actionParams.item })
+             );
+             return response.data;
+           },
+           {}
+         );
+       },
+     };
+   };
+   ```
+
+   **For External API requests (fetch, axios, third-party):**
+   ```typescript
+   export const myAction: CustomActionCellSecondaryActionResolver = (params) => {
+     return {
+       label: 'My Action',
+       icon: <MyIcon />,
+       onClick: () => {
+         // ✅ CORRECT: External API call - NO errorHandler needed
+         fetch('https://api.external-service.com/endpoint', {
+           method: 'POST',
+           body: JSON.stringify(params.actionParams.item)
+         });
+       },
+     };
+   };
+   ```
+
+   **Read the "Error Handling for HTTP Requests" section for complete guidance.**
+
 3. Export your action in `actions/index.tsx`:
    ```typescript
    import { downloadPetDetails } from './downloadPetDetails';
@@ -209,7 +257,7 @@ Custom actions execute JavaScript code that you define. These actions receive pa
    - Enable analytics tracking for user interactions
 
 2. The implementation must return a `ResolvedAction` object with:
-   - `label`: Text displayed for the action 
+   - `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)