@wix/auto-patterns 1.27.0 → 1.29.0

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.
@@ -89,6 +120,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
@@ -143,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'
@@ -195,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: {
@@ -300,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
     };
@@ -332,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: {
@@ -354,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,45 @@
+# 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.