@wix/agent-skills 1.14.0 → 1.15.1

package/skills/wix-app/references/auto-patterns-dashboard/custom-sections-override.md

@@ -0,0 +1,91 @@
+# Custom Sections Override Rules
+
+**REQUIRED**: After creating section files, you MUST update `page.tsx` to register them.
+
+## Type Definitions
+```typescript
+interface Section {
+  id: string; // Unique grouping ID
+  title: string; // Header text
+  primaryAction?: {
+    id: string;
+    label: string;
+    prefixIcon?: React.ReactElement;
+    onClick: () => void;
+  };
+  badge?: {
+    visible: boolean;
+    skin?: 'light' | 'danger' | 'neutralLight';
+  };
+}
+
+// Section Renderer Signature
+type SectionRenderer = (item: any) => Section;
+```
+
+## Configuration Schema
+```json
+{
+  "type": "collectionPage",
+  "collectionPage": {
+    "components": [
+      {
+        "layout": [
+          {
+            "type": "Table",
+            "table": {
+              "sections": {
+                "id": "groupByType" // Matches override key
+              }
+            }
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Validation Logic
+- **IF** `sections.id` is defined **THEN** matching override function MUST exist.
+- **IF** multiple items return same `id` from renderer **THEN** they will be visually grouped.
+- **NEVER** perform heavy computations in renderer; it runs for every item.
+
+## Implementation Rules
+- **MUST** be placed in `components/sections/` folder.
+- **MUST** export a `useSections` hook from `components/sections/index.tsx`.
+- **MUST** return a valid `Section` object.
+- **MUST** handle missing fields gracefully (default values).
+
+## Canonical Example
+```tsx
+// components/sections/groupByType.ts
+import { Section } from '@wix/patterns';
+
+export function groupByType(item: any): Section {
+  const type = item.type || 'other';
+  return {
+    id: type,
+    title: type.toUpperCase(),
+    badge: { visible: true, skin: 'neutralLight' }
+  };
+}
+
+// components/sections/index.tsx
+import { groupByType } from './groupByType';
+export const useSections = () => ({ groupByType });
+```
+
+## page.tsx Registration (REQUIRED)
+
+**CRITICAL: PRESERVE EXISTING OVERRIDES** - Do NOT remove existing overrides. ADD this new one alongside them.
+
+```tsx
+// 1. Add import (keep all existing imports)
+import { useSections } from './components/sections';
+
+// 2. Add hook call (keep all existing hook calls)
+const sections = useSections();
+
+// 3. Add sections to PatternsWizardOverridesProvider value (keep ALL existing overrides)
+```

package/skills/wix-app/references/auto-patterns-dashboard/custom-slots-override.md

@@ -0,0 +1,71 @@
+# Custom Slots Override Rules
+
+**REQUIRED**: After creating slot files, you MUST update `page.tsx` to register them.
+
+## Type Definitions
+```typescript
+// Slot Component Signature
+type SlotComponent = React.FC; // No props passed
+```
+
+## Configuration Schema
+```json
+{
+  "type": "collectionPage",
+  "collectionPage": {
+    "components": [
+      {
+        "type": "custom",
+        "id": "topBanner" // Matches override key
+      },
+      {
+        "type": "collection",
+        "collection": { "collectionId": "items" }
+      }
+    ]
+  }
+}
+```
+
+## Validation Logic
+- **IF** `type` is `"custom"` in components array **THEN** `id` MUST match a key in the `slots` override object.
+- **IF** implementing a slot **THEN** component MUST NOT expect any props.
+- **NEVER** assume slot position; it renders exactly where placed in the `components` array.
+
+## Implementation Rules
+- **MUST** be placed in `components/slots/` folder.
+- **MUST** export a `useSlots` hook from `components/slots/index.tsx`.
+- **MUST** be a standard React Functional Component.
+- **MUST** match the `id` in configuration exactly.
+
+## Canonical Example
+```tsx
+// components/slots/TopBanner.tsx
+import { Card, Text } from '@wix/design-system';
+
+export const TopBanner = () => (
+  <Card>
+    <Card.Content>
+      <Text>Welcome to the dashboard</Text>
+    </Card.Content>
+  </Card>
+);
+
+// components/slots/index.tsx
+import { TopBanner } from './TopBanner';
+export const useSlots = () => ({ topBanner: TopBanner });
+```
+
+## page.tsx Registration (REQUIRED)
+
+**CRITICAL: PRESERVE EXISTING OVERRIDES** - Do NOT remove existing overrides. ADD this new one alongside them.
+
+```tsx
+// 1. Add import (keep all existing imports)
+import { useSlots } from './components/slots';
+
+// 2. Add hook call (keep all existing hook calls)
+const slots = useSlots();
+
+// 3. Add slots to PatternsWizardOverridesProvider value (keep ALL existing overrides)
+```

package/skills/wix-app/references/auto-patterns-dashboard/entity-page-actions.md

@@ -0,0 +1,70 @@
+# Entity Page Action Rules (Edit Mode)
+
+## Type Definitions
+```typescript
+interface EntityPageConfig {
+  entityPage: {
+    actions: {
+      moreActions: (CustomActionItem | DividerItem)[];
+    };
+  };
+}
+
+interface CustomActionItem {
+  id: string; // Matches resolver name
+  type: 'custom';
+  label: string;
+  biName: string; // MANDATORY
+}
+
+interface DividerItem {
+  type: 'divider';
+}
+
+// Resolver Type
+type CustomEntityPageActionResolver = (params: {
+  actionParams: {
+    entity: any; // Current entity data
+    form: UseFormReturn; // react-hook-form instance
+  };
+  sdk: AutoPatternsSDK;
+}) => ResolvedAction;
+```
+
+## Validation Logic
+- **IF** mode is `'edit'` **THEN** ONLY `moreActions` is supported (`primaryActions` forbidden).
+- **IF** `type: 'custom'` **THEN** `id` MUST match exported resolver name.
+- **IF** `type: 'divider'` **THEN** NO other properties allowed.
+- **ONLY** `'custom'` and `'divider'` are valid action types in moreActions. There is NO built-in `'duplicate'`, `'copy'`, `'clone'`, `'archive'`, `'export'`, or similar action type.
+- **IF** you need any operation beyond navigation (duplicate, archive, export, share, etc.) **THEN** use `type: 'custom'` with a resolver implementation.
+
+## Implementation Rules
+- **MUST** place all custom actions in `moreActions` array for Edit Mode.
+- **MUST** include `biName` for every action.
+- **MUST** return a valid `ResolvedAction` object (see resolved_action.md).
+- **MUST** use `errorHandler` for Wix API calls.
+- **NEVER** use `primaryActions` or `secondaryActions` in Edit Mode.
+
+## Canonical Example
+```typescript
+// Config
+{
+  moreActions: [
+    { id: 'sendEmail', type: 'custom', label: 'Send Email', biName: 'send-email-action' },
+    { type: 'divider' },
+    { id: 'archive', type: 'custom', label: 'Archive', biName: 'archive-action' }
+  ]
+}
+
+// components/actions/sendEmail.tsx (use .tsx because it contains JSX icon)
+export const sendEmail: CustomEntityPageActionResolver = ({ actionParams, sdk }) => {
+  return {
+    label: 'Send Email',
+    icon: <EmailIcon />,
+    biName: 'send-email-action',
+    onClick: () => {
+      // Logic here
+    }
+  };
+};
+```

package/skills/wix-app/references/auto-patterns-dashboard/entity-page-view-actions.md

@@ -0,0 +1,73 @@
+# Entity Page Action Rules (View Mode)
+
+## Type Definitions
+```typescript
+interface EntityPageViewActions {
+  primaryActions?: ActionGroup;
+  secondaryActions?: ActionGroup;
+  moreActions?: (CustomActionItem | DividerItem)[];
+}
+
+type ActionGroup = | { type: 'action'; action: { item: ActionItem } } | { type: 'menu'; menu: { label: string; items: (ActionItem | DividerItem)[] } };
+
+interface DividerItem {
+  type: 'divider';
+}
+
+interface ActionItem {
+  id: string; // Must match resolver if custom
+  label: string;
+  type: 'create' | 'custom';
+  biName: string; // MANDATORY
+  create?: {
+    mode: 'page';
+    page: { id: string };
+  };
+}
+
+type CustomEntityPageActionResolver = (params: {
+  actionParams: { entity: any };
+  sdk: AutoPatternsSDK;
+}) => ResolvedAction;
+```
+
+## Validation Logic
+- **IF** mode is `'view'` **THEN** supports `primaryActions`, `secondaryActions`, AND `moreActions`.
+- **IF** action type is `'create'` **THEN** `create` config is **REQUIRED**.
+- **IF** action type is `'custom'` **THEN** resolver implementation is **REQUIRED**.
+
+## Implementation Rules
+- **MUST** use `primaryActions` for main workflow (e.g. Create).
+- **MUST** use `secondaryActions` for supporting workflows.
+- **MUST** use `moreActions` for less common/admin tasks.
+- **MUST** check error handling rules: `errorHandler` for Wix APIs, none for external/SDK.
+- **NEVER** manually add "Edit" action; it's automatic if an Edit Mode page exists.
+
+## Canonical Example
+```typescript
+{
+  primaryActions: {
+    type: 'action',
+    action: {
+      item: {
+        id: 'createEntity',
+        label: 'Create New',
+        type: 'create',
+        biName: 'create-entity-action',
+        create: {
+          mode: 'page',
+          page: { id: 'entity-edit-page' }
+        }
+      }
+    }
+  },
+  moreActions: [
+    {
+      id: 'duplicateEntity',
+      type: 'custom',
+      label: 'Duplicate',
+      biName: 'duplicate-entity-action'
+    }
+  ]
+}
+```

package/skills/wix-app/references/auto-patterns-dashboard/entity-page.md

@@ -0,0 +1,98 @@
+# Entity Page Rules
+
+## Type Definitions
+```typescript
+interface EntityPageConfig {
+  type: 'entityPage';
+  entityPage: {
+    mode?: 'edit' | 'view'; // Default 'edit'
+    route: { path: string; params: { id: string } };
+    parentPageId: string; // REQUIRED
+    collectionId: string;
+    entityTypeSource: 'cms' | 'custom';
+    title?: {
+      text: string;
+      badges?: { id: string }; // Dynamic badges override ID
+    };
+    subtitle?: {
+      text: string;
+      id?: string; // Dynamic subtitle override ID
+    };
+    layout?: {
+      main: CardLayout[];
+      sidebar?: CardLayout[];
+    };
+    actions?: EntityPageActions; // See Action Rules
+  };
+}
+
+interface CardLayout {
+  type: 'card';
+  card: {
+    title?: { text: string };
+    children: LayoutContent[];
+  };
+}
+
+type LayoutContent = | { type: 'field'; field: { fieldId: string; span?: number } } | { type: 'container'; container: { children: LayoutContent[]; span?: number } } | { type: 'component'; component: { componentId: string; span?: number } };
+
+// Override Types
+type EntityPageHeaderSubtitle = (entity: any) => { text: string };
+type EntityPageHeaderBadges = (entity: any) => {
+  text: string;
+  skin?: 'success' | 'warning' | 'destructive' | 'neutral' | 'premium';
+  prefixIcon?: ReactElement;
+  suffixIcon?: ReactElement;
+}[];
+```
+
+## Validation Logic
+- **IF** `mode` is undefined **THEN** defaults to `'edit'`.
+- **IF** `mode: 'edit'` **THEN** only `moreActions` supported.
+- **IF** `mode: 'view'` **THEN** `primaryActions`, `secondaryActions`, `moreActions` supported.
+- **IF** `badges.id` defined **THEN** implementation MUST return array of badge objects.
+- **IF** `subtitle.id` defined **THEN** implementation MUST return `{ text: string }`.
+
+## Implementation Rules
+- **MUST** use route format `/[segment]/:entityId` (NEVER `/:entityId`).
+- **MUST** map dynamic parameter in `route.params` (e.g. `{ id: 'entityId' }`).
+- **MUST** register overrides for `badges` and `subtitle` if IDs are used.
+- **MUST** use 12-column grid system for `span` (wraps if > 12).
+- **SHOULD** put primary info in `main` layout, metadata in `sidebar`.
+- **NEVER** return JSX from badge/subtitle functions (return data objects).
+
+## Canonical Example
+```typescript
+// Config
+{
+  type: 'entityPage',
+  entityPage: {
+    mode: 'view',
+    route: { path: '/pet/:entityId', params: { id: 'entityId' } },
+    parentPageId: 'pets-list',
+    collectionId: 'pets',
+    entityTypeSource: 'cms',
+    title: {
+      text: 'Pet Details',
+      badges: { id: 'petBadges' }
+    },
+    layout: {
+      main: [{
+        type: 'card',
+        card: {
+          title: { text: 'Info' },
+          children: [
+            { type: 'field', field: { fieldId: 'name', span: 6 } },
+            { type: 'field', field: { fieldId: 'age', span: 6 } }
+          ]
+        }
+      }]
+    }
+  }
+}
+
+// Override Implementation
+export const petBadges = (entity) => ([
+  { text: entity.status, skin: entity.status === 'Active' ? 'success' : 'neutral' }
+]);
+```

package/skills/wix-app/references/auto-patterns-dashboard/example-patterns.json

@@ -0,0 +1,278 @@
+{
+  "pages": [
+    {
+      "id": "additional-fees-collection",
+      "type": "collectionPage",
+      "appMainPage": true,
+      "collectionPage": {
+        "route": {
+          "path": "/"
+        },
+        "title": {
+          "text": "Additional Fees Configuration",
+          "hideTotal": false
+        },
+        "subtitle": {
+          "text": "Manage and configure additional fees for checkout"
+        },
+        "actions": {
+          "primaryActions": {
+            "type": "action",
+            "action": {
+              "item": {
+                "id": "create-additional-fees",
+                "type": "create",
+                "label": "Add New Fee",
+                "collection": {
+                  "collectionId": "@mirivo/mirivo-private-app-for-test2011/additional-fees",
+                  "entityTypeSource": "cms"
+                },
+                "create": {
+                  "mode": "page",
+                  "page": {
+                    "id": "additional-fees-entity"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "components": [
+          {
+            "type": "collection",
+            "layout": [
+              {
+                "type": "Table",
+                "table": {
+                  "columns": [
+                    {
+                      "id": "feeTitle",
+                      "name": "Title",
+                      "width": "200px",
+                      "sortable": true
+                    },
+                    {
+                      "id": "feeAmount",
+                      "name": "Amount",
+                      "width": "100px",
+                      "sortable": true
+                    },
+                    {
+                      "id": "feeType",
+                      "name": "Type",
+                      "width": "200px",
+                      "sortable": true
+                    },
+                    {
+                      "id": "isActive",
+                      "name": "Active",
+                      "width": "100px",
+                      "sortable": true
+                    }
+                  ],
+                  "customColumns": {
+                    "enabled": true
+                  }
+                }
+              }
+            ],
+            "entityPageId": "additional-fees-entity",
+            "collection": {
+              "collectionId": "@mirivo/mirivo-private-app-for-test2011/additional-fees",
+              "entityTypeSource": "cms"
+            },
+            "toolbarTitle": {
+              "title": "Additional Fees",
+              "subtitle": {
+                "text": "Configure fees applied during checkout process"
+              },
+              "showTotal": true
+            },
+            "filters": {
+              "items": [
+                {
+                  "id": "feeAmount-filter",
+                  "fieldId": "feeAmount",
+                  "displayName": "Fee Amount",
+                  "tagLabel": "Fee Amount",
+                  "numberConfig": {
+                    "allowedDecimals": true
+                  }
+                },
+                {
+                  "id": "isActive-filter",
+                  "fieldId": "isActive",
+                  "displayName": "Is Active",
+                  "tagLabel": "Is Active"
+                }
+              ]
+            },
+            "emptyState": {
+              "title": "No Additional Fees Configured",
+              "subtitle": "Start by adding your first additional fee for checkout",
+              "addNewCta": {
+                "id": "create-additional-fees",
+                "text": "Create First Fee"
+              }
+            },
+            "actionCell": {
+              "primaryAction": {
+                "item": {
+                  "id": "edit-additional-fees",
+                  "type": "update",
+                  "update": {
+                    "mode": "page",
+                    "page": {
+                      "id": "additional-fees-entity"
+                    }
+                  }
+                }
+              },
+              "secondaryActions": {
+                "items": [
+                  {
+                    "id": "delete-additional-fees",
+                    "type": "delete",
+                    "label": "Delete",
+                    "delete": {
+                      "mode": "modal",
+                      "modal": {
+                        "title": {
+                          "text": "Remove Additional Fee"
+                        },
+                        "description": {
+                          "text": "Are you sure you want to delete this additional fee? This will remove it from future checkouts."
+                        },
+                        "feedback": {
+                          "successToast": {
+                            "text": "Additional fee deleted successfully"
+                          },
+                          "errorToast": {
+                            "text": "Failed to delete additional fee"
+                          }
+                        }
+                      }
+                    }
+                  }
+                ]
+              }
+            },
+            "bulkActionToolbar": {
+              "primaryActions": [
+                {
+                  "type": "action",
+                  "action": {
+                    "item": {
+                      "id": "bulk-delete-additional-fees",
+                      "type": "bulkDelete",
+                      "bulkDelete": {
+                        "mode": "modal",
+                        "modal": {
+                          "title": {
+                            "text": "Remove Multiple Fees"
+                          },
+                          "description": {
+                            "text": "Are you sure you want to delete the selected additional fees? This will remove them from future checkouts."
+                          },
+                          "feedback": {
+                            "successToast": {
+                              "text": "Selected additional fees deleted successfully"
+                            },
+                            "errorToast": {
+                              "text": "Failed to delete selected additional fees"
+                            }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              ]
+            }
+          }
+        ]
+      }
+    },
+    {
+      "id": "additional-fees-entity",
+      "type": "entityPage",
+      "entityPage": {
+        "route": {
+          "path": "/additional-fee/:entityId",
+          "params": {
+            "id": "entityId"
+          }
+        },
+        "title": {
+          "text": "Fee Details"
+        },
+        "subtitle": {
+          "text": "View and edit additional fee configuration"
+        },
+        "parentPageId": "additional-fees-collection",
+        "layout": {
+          "main": [
+            {
+              "type": "card",
+              "card": {
+                "title": {
+                  "text": "Fee Information"
+                },
+                "subtitle": {
+                  "text": "Basic details for the additional fee"
+                },
+                "children": [
+                  {
+                    "type": "field",
+                    "field": {
+                      "span": 12,
+                      "fieldId": "feeTitle"
+                    }
+                  },
+                  {
+                    "type": "field",
+                    "field": {
+                      "span": 12,
+                      "fieldId": "feeAmount"
+                    }
+                  },
+                  {
+                    "type": "field",
+                    "field": {
+                      "span": 12,
+                      "fieldId": "feeType"
+                    }
+                  }
+                ]
+              }
+            }
+          ],
+          "sidebar": [
+            {
+              "type": "card",
+              "card": {
+                "title": {
+                  "text": "Fee Status"
+                },
+                "subtitle": {
+                  "text": "Activation and usage settings"
+                },
+                "children": [
+                  {
+                    "type": "field",
+                    "field": {
+                      "span": 12,
+                      "fieldId": "isActive"
+                    }
+                  }
+                ]
+              }
+            }
+          ]
+        },
+        "collectionId": "@mirivo/mirivo-private-app-for-test2011/additional-fees",
+        "entityTypeSource": "cms"
+      }
+    }
+  ]
+}