@wix/auto-patterns 1.28.0 → 1.30.0

package/dist/docs/action_cell.md

@@ -144,6 +144,7 @@ Custom actions execute JavaScript code that you define. These actions receive pa
            })
          });
        },
+       biName: 'download-pet-details-action'  // MANDATORY: For analytics tracking
      };
    };
    ```
@@ -168,10 +169,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';
 
@@ -179,9 +181,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>
      );
    }
    ```
@@ -196,13 +198,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:
@@ -238,13 +248,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

package/dist/docs/app_config_structure.md

@@ -1,5 +1,33 @@
 # 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
@@ -24,6 +52,8 @@
 - **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 {
@@ -50,6 +80,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.
@@ -144,6 +175,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'
@@ -196,6 +228,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: {
@@ -301,7 +334,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
     };
@@ -333,6 +366,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: {
@@ -355,6 +389,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

package/dist/docs/app_context.md

@@ -0,0 +1,109 @@
+# 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.
+
+## 3. Refreshing Collection Data
+
+The `useAppContext` hook also provides a `refreshCollection` function that allows you to refresh the collection data from within your child components:
+
+```tsx
+import React from 'react';
+import { useAppContext } from '@wix/auto-patterns';
+
+export const RefreshButton: React.FC = () => {
+  const { refreshCollection } = useAppContext();
+
+  return (
+    <button onClick={refreshCollection}>
+      Refresh Collection
+    </button>
+  );
+};
+```
+
+### Use Cases for refreshCollection
+
+- **Manual Refresh**: Provide users with a button to manually refresh data
+- **Post-Operation Refresh**: Refresh data after completing custom operations in modals
+- **Data Synchronization**: Ensure child components have the latest data after external changes
+- **Real-time Updates**: Refresh data when receiving updates from external sources
+
+### Example: Modal with Refresh Capability
+
+```tsx
+import React from 'react';
+import { useAppContext } from '@wix/auto-patterns';
+import { Button, Modal } from '@wix/design-system';
+
+export const DataUpdateModal: React.FC = () => {
+  const { items, refreshCollection } = useAppContext();
+
+  const handleUpdate = async () => {
+    // Perform your custom update operation
+    await updateExternalData();
+
+    // Refresh the collection to show updated data
+    refreshCollection();
+  };
+
+  return (
+    <Modal>
+      <Modal.Content>
+        <p>Current items: {items.length}</p>
+        <Button onClick={handleUpdate}>
+          Update and Refresh
+        </Button>
+      </Modal.Content>
+    </Modal>
+  );
+};
+```
+
+### Important Notes
+
+- **Automatic Refresh**: The `refreshCollection` function will refresh the current collection with the same filters, sorting, and pagination settings
+- **Performance**: Use this function judiciously to avoid unnecessary API calls
+- **User Experience**: Consider showing loading states during refresh operations
+- **Error Handling**: The refresh operation will automatically handle errors and display appropriate messages to users