@wix/auto-patterns 1.38.0 → 1.40.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)
             };
@@ -522,6 +486,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 +1614,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 +1929,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 +1973,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