@wix/agent-skills 1.13.0 → 1.15.0

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"
+      }
+    }
+  ]
+}

package/skills/wix-app/references/auto-patterns-dashboard/pages-configuration.md

@@ -0,0 +1,94 @@
+# Pages Configuration Rules
+
+## Type Definitions
+```typescript
+interface PageConfig {
+  id: string; // Unique ID
+  type: 'collectionPage' | 'entityPage';
+  appMainPage?: boolean; // EXACTLY ONE page must have true
+}
+
+interface CollectionPage extends PageConfig {
+  type: 'collectionPage';
+  collectionPage: {
+    route: { path: '/' };
+    components: [{
+      entityPageId: string; // REQUIRED: Links to entity page ID
+      // ... component config
+    }];
+  };
+}
+
+interface EntityPage extends PageConfig {
+  type: 'entityPage';
+  entityPage: {
+    parentPageId: string; // REQUIRED: Links to collection page ID
+    route: {
+      path: string; // MUST be '/[segment]/:entityId'
+      params: { id: 'entityId' };
+    };
+  };
+}
+
+interface StickyConfig {
+  stickyColumns?: number; // Count of columns to stick from left
+  columns: Array<{
+    reorderDisabled?: boolean; // Recommended for sticky cols
+  }>;
+}
+```
+
+## Validation Logic
+- **IF** `pages` array length != 2 **THEN** Invalid (Must be exactly 2).
+- **IF** `appMainPage: true` count != 1 **THEN** Invalid (Must be exactly 1).
+- **IF** `type: 'entityPage'` **THEN** `route.path` MUST match `/[segment]/:entityId`.
+- **IF** `route.path` is `/:entityId` **THEN** Invalid (Conflict with root).
+- **IF** `stickyColumns` is set **THEN** value must be > 0 AND <= total columns.
+
+## Implementation Rules
+- **MUST** generate exactly one `collectionPage` and one `entityPage`.
+- **MUST** link pages bidirectionally:
+    - `collectionPage` references `entityPageId` (in component).
+    - `entityPage` references `parentPageId` (in page config).
+- **MUST** use `entityId` as the dynamic parameter name.
+- **MUST** use position-based stickiness (first N columns).
+- **SHOULD** set `reorderDisabled: true` for sticky columns to prevent user breakage.
+
+## Canonical Example
+```typescript
+[
+  {
+    id: 'product-list',
+    type: 'collectionPage',
+    appMainPage: true,
+    collectionPage: {
+      route: { path: '/' },
+      components: [{
+        type: 'collection',
+        entityPageId: 'product-details', // Link to Entity Page
+        layout: [{
+          type: 'Table',
+          table: {
+            stickyColumns: 1,
+            columns: [
+              { id: 'name', name: 'Name', reorderDisabled: true }, // Sticky & Locked
+              { id: 'price', name: 'Price' }
+            ]
+          }
+        }]
+      }]
+    }
+  },
+  {
+    id: 'product-details',
+    type: 'entityPage',
+    entityPage: {
+      parentPageId: 'product-list', // Link to Collection Page
+      route: {
+        path: '/product/:entityId', // Correct format
+        params: { id: 'entityId' }
+      }
+    }
+  }
+]
+```

package/skills/wix-app/references/auto-patterns-dashboard/resolved-action.md

@@ -0,0 +1,43 @@
+# ResolvedAction Rules
+
+## Type Definitions
+```typescript
+interface ResolvedAction {
+  label: string; // Display text
+  icon: IconElement; // React Icon Component
+  onClick: () => void; // async handlers compile due to TS void-return bivariance
+  biName?: string; // type-optional; project convention is to ALWAYS set it (see Implementation Rules)
+  disabled?: boolean;
+  hidden?: boolean;
+  tooltip?: string;
+  skin?: string; // recommended values: 'standard' | 'inverted' | 'premium' | 'dark' | 'destructive'
+}
+```
+
+## Validation Logic
+- **IF** `disabled` is true **THEN** `tooltip` is **RECOMMENDED**.
+- **IF** implementing a custom action **THEN** return object MUST match `ResolvedAction`.
+- **IF** `biName` is provided **THEN** value MUST match configuration `biName`.
+
+## Implementation Rules
+- **MUST** include `label`, `icon`, `onClick`, and `biName`.
+- **MUST** use valid icon element (e.g. `<Icon />`).
+- **MUST** handle async `onClick` operations properly (use try/catch or SDK helpers).
+- **SHOULD** use `hidden` for permission checks.
+- **SHOULD** use `skin="destructive"` for delete/dangerous actions.
+
+## Canonical Example
+```typescript
+// Resolver Function Return Value
+return {
+  label: 'Export',
+  icon: <Download />,
+  biName: 'export-action',
+  onClick: async () => {
+    // Action logic
+  },
+  disabled: !hasData,
+  tooltip: !hasData ? 'No data to export' : undefined,
+  skin: 'standard'
+};
+```

package/skills/wix-app/references/auto-patterns-dashboard/sdk-utilities.md

@@ -0,0 +1,66 @@
+# SDK Utilities Rules
+
+## Type Definitions
+```typescript
+interface AutoPatternsSDK {
+  closeModal: () => void;
+  getOptimisticActions: (collectionId: string) => OptimisticActions;
+  getSchema: (collectionId: string) => SchemaConfig | undefined;
+  refreshCollection: () => void;
+  collectionId: string;
+}
+
+interface OptimisticActions {
+  createOne: (item: any, params: OptimisticParams) => void;
+  createMany: (items: any[], params: OptimisticParams) => void;
+  updateOne: (item: any, params: OptimisticParams) => void;
+  updateMany: (items: any[], params: OptimisticParams) => void;
+  updateAll: (transformFn: (item: any) => Partial<any>, params: OptimisticParams) => void;
+  deleteOne: (item: any, params: DeleteParams) => void;
+  deleteMany: (items: any[], params: DeleteParams) => void;
+  deleteAll: (params: DeleteParams) => void;
+}
+
+interface OptimisticParams {
+  submit: (items: any[]) => Promise<any>;
+  successToast: string | ToastConfig;
+  errorToast: (error: Error, actions: { retry: () => void }) => string | ToastConfig;
+}
+
+type DeleteParams = OptimisticParams & { showUndoToast: true };
+
+interface ToastConfig {
+  message: string; // Must use 'message' (not 'text')
+  action?: { text: string; onClick: () => void };
+}
+```
+
+## Validation Logic
+- **IF** using `delete*` operations **THEN** `showUndoToast: true` is **REQUIRED**.
+- **IF** returning `ToastConfig` **THEN** use `message` property (NOT `text`).
+- **IF** using schema in submit **THEN** check `schema` existence first (can be undefined).
+
+## Implementation Rules
+- **MUST** use `optimisticActions` for data mutations (create/update/delete).
+- **MUST** handle async submit failures in `errorToast`.
+- **MUST** use `sdk.collectionId` for current context.
+- **NEVER** use OptimisticActions for read-only operations.
+
+## Canonical Example
+```typescript
+const optimisticActions = sdk.getOptimisticActions(sdk.collectionId);
+const schema = sdk.getSchema(sdk.collectionId);
+
+optimisticActions.updateOne(item, {
+  submit: async (items) => {
+    // Check schema existence
+    if (!schema) return items[0];
+    return await schema.actions.update(items[0]);
+  },
+  successToast: 'Item updated successfully',
+  errorToast: (err, { retry }) => ({
+    message: 'Update failed', // Use 'message'
+    action: { text: 'Retry', onClick: retry }
+  })
+});
+```

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

@@ -0,0 +1,76 @@
+# Views Configuration Rules
+
+## Type Definitions
+```typescript
+interface ViewsConfig {
+  enabled?: boolean;
+  presets?: ViewsPreset | CategoriesPreset;
+  saveViewModalProps?: { placeholderName?: string; learnMore?: { url?: string } };
+  viewsDropdownProps?: {
+    showTotal?: boolean;
+    hideAllItemsView?: boolean;
+    customAllItemsViewLabel?: string;
+  };
+}
+
+interface ViewsPreset {
+  type: 'views';
+  views: PresetView[];
+}
+
+interface CategoriesPreset {
+  type: 'categories';
+  categories: {
+    id: string;
+    label: string;
+    views: PresetView[];
+    icon?: { tooltipContent: string; size?: 'small' | 'medium' };
+  }[];
+}
+
+interface PresetView {
+  id: string; // Forbidden: predefined-views, saved-views, all-items-view
+  label: string;
+  isDefaultView?: boolean;
+  columnPreferences?: { id: string; direction?: 'asc' | 'desc'; show?: boolean }[];
+  filters?: Record<string, AutoFilterValue>; // Key matches filter config ID
+}
+```
+
+## Validation Logic
+- **IF** `views.enabled` is false **THEN** all other settings ignored.
+- **IF** controlling columns in views **THEN** `table.customColumns.enabled` MUST be true.
+- **IF** setting `columnPreferences` **THEN** must list ALL visible columns if reordering/hiding.
+- **IF** setting filters **THEN** keys MUST match defined filter IDs.
+
+## Implementation Rules
+- **MUST** set `enabled: true` to activate.
+- **MUST** use valid filter structures (Date/Number/Boolean/Enum/Reference) matching `AppConfig`.
+- **MUST** avoid reserved IDs (`predefined-views`, `saved-views`, `all-items-view`).
+- **SHOULD** set `isDefaultView: true` on exactly one preset if default override needed.
+
+## Canonical Example
+```typescript
+views: {
+  enabled: true,
+  presets: {
+    type: 'categories',
+    categories: [{
+      id: 'status-cat',
+      label: 'By Status',
+      views: [{
+        id: 'active-items',
+        label: 'Active Only',
+        isDefaultView: true,
+        filters: {
+          'status-filter': { filterType: 'boolean', value: [{ id: 'checked', name: 'Active' }] }
+        },
+        columnPreferences: [
+          { id: 'name', show: true },
+          { id: 'status', show: true, direction: 'asc' }
+        ]
+      }]
+    }]
+  }
+}
+```

package/skills/wix-app/references/editor-react-component/ACCESSIBILITY.md

@@ -13,20 +13,6 @@ Rules and patterns for ARIA accessibility support in Editor React components.
 - The `A11y` type includes: `ariaLabel`, `ariaDescribedBy`, `ariaLabelledBy`, `role`, `ariaHidden`, `ariaLive`, and all other ARIA attributes.
 - Users provide ARIA values through the `a11y` prop: `<Component a11y={{ ariaLabel: "..." }} />`
 
-### Stable IDs for Element Relationships
-
-ARIA relationships (`aria-controls`, `aria-labelledby`, `aria-describedby`) and `htmlFor` need element ids. Generate them with `useStableId` from `@wix/react-component-utils` — passing the `id` prop as the override — never `Math.random()`, a manual counter, or a bare `React.useId()` (those break SSR/hydration). See [`SSR.md`](SSR.md) for the full rule.
-
-```tsx
-import { useStableId } from '@wix/react-component-utils';
-
-const rootId = useStableId(id);
-const panelId = `${rootId}-panel`;
-
-<button aria-controls={panelId}>{label}</button>
-<div id={panelId} role="tabpanel">{content}</div>
-```
-
 ### ARIA Label Rules
 
 ARIA labels are user-facing content and must NEVER be hardcoded as string literals in JSX.
@@ -150,3 +136,4 @@ export interface TabsProps {
 ```
 
 **Why:** The `A11y` type from `@wix/editor-react-types` provides a standardized way to handle ALL ARIA attributes (ariaLabel, ariaDescribedBy, ariaLabelledBy, role, ariaHidden, ariaLive, etc.). Individual ARIA props fragment the API and make it harder to use.
+