@wix/agent-skills 1.14.0 → 1.15.1

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

@@ -0,0 +1,86 @@
+# Bulk Actions Rules
+
+## Type Definitions
+```typescript
+interface BulkActionToolbar {
+  primaryActions?: BulkActionGroup[];
+  secondaryActions?: (BulkActionItem | DividerItem)[];
+}
+
+type BulkActionGroup = | { type: 'action'; action: { item: BulkActionItem } } | { type: 'menu'; menu: { label: string; items: (BulkActionItem | DividerItem)[] } };
+
+interface DividerItem {
+  type: 'divider';
+}
+
+interface BulkActionItem {
+  id: string; // Must match custom resolver name
+  type: 'bulkDelete' | 'custom';
+  label?: string;
+  biName: string; // MANDATORY
+  bulkDelete?: {
+    mode: 'modal';
+    modal: {
+      title?: { text?: string; id?: string };
+      description?: { text: string };
+      actions?: { submit?: { text: string }; cancel?: { text: string } };
+      feedback?: { successToast?: { text: string }; errorToast?: { text: string } };
+    };
+  };
+}
+
+type CustomBulkActionsActionResolver = (params: {
+  actionParams: { selectedValues: any[]; total: number };
+  sdk: AutoPatternsSDK;
+}) => ResolvedAction;
+```
+
+## Validation Logic
+- **IF** `type: 'bulkDelete'` **THEN** `bulkDelete.mode: 'modal'` is **REQUIRED**.
+- **IF** `type: 'custom'` **THEN** resolver implementation is **REQUIRED**.
+- **IF** `primaryActions` AND `secondaryActions` both undefined **THEN** toolbar invalid.
+
+## Implementation Rules
+- **MUST** include `biName` for all bulk actions (`bulk-{action}-action`).
+- **MUST** place toolbar configuration inside `table` or `grid` object.
+- **MUST** use `CustomBulkActionsActionResolver` type for custom logic.
+- **MUST** register custom resolvers in `AutoPatternsOverridesProvider`.
+- **MUST** use `errorHandler` for Wix API calls in resolvers.
+- **NEVER** use default navigation in bulk actions; implement explicitly.
+
+## Canonical Example
+```typescript
+// Config
+bulkActionToolbar: {
+  primaryActions: [{
+    type: 'action',
+    action: {
+      item: {
+        id: 'bulkDelete',
+        type: 'bulkDelete',
+        label: 'Delete',
+        biName: 'bulk-delete-action',
+        bulkDelete: { mode: 'modal', modal: {} }
+      }
+    }
+  }],
+  secondaryActions: [
+    {
+      id: 'bulkExport',
+      type: 'custom',
+      label: 'Export',
+      biName: 'bulk-export-action'
+    }
+  ]
+}
+
+// Resolver
+export const bulkExport: CustomBulkActionsActionResolver = ({ actionParams }) => ({
+  label: 'Export',
+  icon: <Download />,
+  biName: 'bulk-export-action',
+  onClick: () => {
+    // Logic using actionParams.selectedValues
+  }
+});
+```

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

@@ -0,0 +1,119 @@
+# Collection Page Action Rules
+
+## Type Definitions
+```typescript
+interface CollectionPageActions {
+  primaryActions?: ActionGroup;
+  secondaryActions?: ActionGroup;
+}
+
+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 custom resolver name if custom
+  type: 'create' | 'custom';
+  label?: string;
+  biName: string; // MANDATORY
+  collection?: {
+    collectionId: string;
+    entityTypeSource: 'cms' | 'custom';
+  };
+  create?: {
+    mode: 'page';
+    page: { id: string };
+  };
+}
+
+// Row Click Action (Table level)
+interface OnRowClickConfig {
+  id: string;
+  type: 'custom';
+}
+
+// Row Click Resolver Signature - NOTE: item is nested under actionParams
+type CustomActionCollectionPageActionOnRowClickResolver = (params: {
+  actionParams: { item: any };  // The clicked row's data - nested under actionParams
+  sdk: AutoPatternsSDK;
+}) => ResolvedAction;
+```
+
+## Validation Logic
+- **IF** `type: 'create'` **THEN** `create` config with `page.id` is **REQUIRED**.
+- **IF** `type: 'custom'` **THEN** `id` must match a registered resolver name.
+- **IF** `onRowClick` is configured **THEN** matching `custom` resolver is **MANDATORY**.
+- **IF** `onRowClick` is configured **THEN** default navigation is **DISABLED**.
+- **IF** `onRowClick` resolver accesses row data **THEN** use `actionParams.item` (NOT direct `item` param).
+
+## Implementation Rules
+- **MUST** include a `create` action in `primaryActions` for every collection page.
+- **MUST** include `biName` for every action (kebab-case).
+- **MUST** implement custom resolvers using `CustomActionCollectionPageActionResolver`.
+- **MUST** implement row click resolvers using `CustomActionCollectionPageActionOnRowClickResolver` returning `ResolvedAction`.
+- **MUST** place onRowClick resolvers in `components/actions/` folder (same as other custom actions).
+- **MUST** register onRowClick resolvers via `useActions` hook pattern (see **custom_actions_override**).
+- **NEVER** mix `create` logic with `custom` action types.
+- **NEVER** assume `schema` or `optimisticActions` exist without checking.
+
+## Canonical Example
+```typescript
+{
+  primaryActions: {
+    type: 'action',
+    action: {
+      item: {
+        id: 'create-pet',
+        type: 'create',
+        label: 'Add Pet',
+        biName: 'create-pet-action',
+        collection: { collectionId: 'pets', entityTypeSource: 'cms' },
+        create: {
+          mode: 'page',
+          page: { id: 'pet-details' }
+        }
+      }
+    }
+  },
+  secondaryActions: {
+    type: 'menu',
+    menu: {
+      label: 'More',
+      items: [
+        {
+          id: 'exportCollection',
+          type: 'custom',
+          label: 'Export',
+          biName: 'export-action',
+          collection: { collectionId: 'pets', entityTypeSource: 'cms' }
+        }
+      ]
+    }
+  }
+}
+```
+
+## Canonical Example (onRowClick)
+```typescript
+// Config
+{
+  "onRowClick": {
+    "id": "myRowClickAction",
+    "type": "custom"
+  }
+}
+
+// Resolver (if custom) - see custom_actions_override for full registration pattern
+export const myRowClickAction: CustomActionCollectionPageActionOnRowClickResolver = ({
+  actionParams: { item },  // item is nested under actionParams
+}) => ({
+  label: 'Custom Action',
+  icon: <MyIcon />,
+  biName: 'my-row-click-action',
+  onClick: () => {
+    // Custom onClick logic using item
+  }
+});
+```

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

@@ -0,0 +1,103 @@
+# Collection Page Rules
+
+## Type Definitions
+```typescript
+interface CollectionComponent {
+  type: 'collection';
+  entityPageId: string; // REQUIRED for navigation
+  collection: {
+    collectionId: string;
+    entityTypeSource: 'cms' | 'custom';
+    custom?: { id: string };
+  };
+  layout: LayoutItem[];
+}
+
+type LayoutItem = TableLayout | GridLayout;
+
+interface TableLayout {
+  type: 'Table';
+  table: {
+    columns: ColumnConfig[];
+    customColumns?: { enabled: boolean };
+    stickyColumns?: number;
+    showTitleBar?: boolean;
+  };
+}
+
+interface ColumnConfig {
+  id: string; // Field ID
+  name: string; // Display title
+  width: string;
+  tooltipContent?: string; // Info icon text
+  sortable?: boolean;
+  hideable?: boolean;
+}
+
+interface GridLayout {
+  type: 'Grid';
+  grid: {
+    item: {
+      titleFieldId: string; // REQUIRED Field ID
+      subtitleFieldId?: string; // Field ID
+      imageFieldId?: string; // Field ID
+      cardContentMode?: 'full' | 'title' | 'empty';
+    };
+  };
+}
+```
+
+## Validation Logic
+- **IF** `components` array length != 1 **THEN** Invalid Config (Must be exactly 1).
+- **IF** `layout` contains both 'Table' and 'Grid' **THEN** View Switcher is automatically enabled.
+- **IF** `columns` count > 5 **THEN** `customColumns.enabled` = `true`.
+- **IF** `columns` count <= 5 **THEN** `customColumns.enabled` = `false` (unless explicitly requested).
+- **IF** `type` is 'Grid' **THEN** `titleFieldId` is **REQUIRED**.
+
+## Implementation Rules
+- **MUST** reference `entityPageId` to link rows/cards to the entity page.
+- **MUST** select max 3 columns initially for the table.
+- **MUST** use `tooltipContent` to explain complex column data.
+- **SHOULD** include a primary action with `type: 'update'` in Grid view to allow easy editing.
+- **NEVER** use `onRowClick` unless custom behavior (not entity page navigation) is explicitly required.
+
+## Canonical Example
+```typescript
+{
+  type: 'collectionPage',
+  // ... page props
+  components: [
+    {
+      type: 'collection',
+      entityPageId: 'pet-details', // Links to entity page
+      collection: {
+        collectionId: 'pets',
+        entityTypeSource: 'cms'
+      },
+      layout: [
+        {
+          type: 'Table',
+          table: {
+            columns: [
+              { id: 'name', name: 'Name', width: '200px', tooltipContent: 'Pet Name' },
+              { id: 'breed', name: 'Breed', width: '150px' },
+              { id: 'age', name: 'Age', width: '100px' }
+            ],
+            customColumns: { enabled: false }
+          }
+        },
+        {
+          type: 'Grid',
+          grid: {
+            item: {
+              titleFieldId: 'name',
+              subtitleFieldId: 'breed',
+              imageFieldId: 'photo'
+            }
+          }
+        }
+      ]
+    }
+  ]
+}
+```

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

@@ -0,0 +1,76 @@
+# Custom Actions Override Rules
+
+**REQUIRED**: After creating action files, you MUST update `page.tsx` to register them.
+
+## Type Definitions
+```typescript
+interface ResolvedAction {
+  label: string;
+  icon?: React.ReactElement;
+  onClick: () => void | Promise<void>;
+  disabled?: boolean;
+  hidden?: boolean;
+}
+
+// Action Resolver Signature
+type CustomActionResolver = (params: {
+  item: any;
+  selectedItems?: any[];
+}) => ResolvedAction;
+```
+
+## Configuration Schema
+```json
+{
+  "actions": [
+    {
+      "type": "custom",
+      "id": "myAction" // Matches override key
+    }
+  ]
+}
+```
+
+## Validation Logic
+- **IF** `type` is `"custom"` **THEN** `id` MUST match key in `actions` override.
+- **IF** action is async **THEN** `onClick` SHOULD return a Promise.
+- **IF** action requires selection **THEN** check `selectedItems`.
+
+## Implementation Rules
+- **MUST** be placed in `components/actions/` folder.
+- **MUST** use `.tsx` extension if the file contains JSX (icons, React elements). Use `.ts` only for pure logic files.
+- **MUST** export `useActions` hook from `components/actions/index.tsx`.
+- **MUST** return `ResolvedAction` object.
+- **MUST** handle errors (use `try/catch` or `errorHandler` for Wix APIs).
+- **APPLIES TO** all custom action types: actionCell, collectionPageActions, onRowClick, bulkActions.
+- **NEVER** place action resolvers directly in page.tsx or overrides.tsx - always use components/actions/ folder.
+
+## Canonical Example
+```tsx
+// components/actions/myAction.tsx (use .tsx when file contains JSX like icons)
+export const myAction = ({ item }) => ({
+  label: 'Approve',
+  icon: <Check />,
+  onClick: async () => {
+    await approveItem(item.id);
+  }
+});
+
+// components/actions/index.tsx
+import { myAction } from './myAction';
+export const useActions = () => ({ myAction });
+```
+
+## 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 { useActions } from './components/actions';
+
+// 2. Add hook call (keep all existing hook calls)
+const actions = useActions();
+
+// 3. Add actions to PatternsWizardOverridesProvider value (keep ALL existing overrides)
+```

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

@@ -0,0 +1,82 @@
+# Custom Columns Override Rules
+
+**REQUIRED**: After creating column files, you MUST update `page.tsx` to register them.
+
+## Type Definitions
+```typescript
+interface IColumnValue<T> {
+  value: T; // The individual column value
+  row: Record<string, any>; // The entire row object containing all field values
+}
+
+// Override Function Signature
+type ColumnOverride<T> = (props: IColumnValue<T>) => React.ReactNode;
+```
+
+## Configuration Schema
+```json
+{
+  "type": "collectionPage",
+  "collectionPage": {
+    "components": [
+      {
+        "layout": [
+          {
+            "type": "Table",
+            "table": {
+              "columns": [
+                {
+                  "id": "myCustomColumn" // Matches key in override object
+                }
+              ]
+            }
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Validation Logic
+- **IF** overriding a column **THEN** function name MUST match the `column.id` in AppConfig.
+- **IF** needing React hooks (useState, useEffect) **THEN** MUST wrap implementation in a separate React component and return it.
+- **IF** accessing row data **THEN** MUST use exact field IDs from schema as keys on `row` object.
+- **NEVER** use React hooks directly inside the column override function (it is a render function, not a component).
+
+## Implementation Rules
+- **MUST** be placed in `components/columns/` folder.
+- **MUST** export a `useColumns` hook from `components/columns/index.tsx`.
+- **MUST** import type `IColumnValue` from `@wix/auto-patterns` for type safety.
+- **MUST** return a ReactNode (JSX) or null.
+
+## Canonical Example
+```tsx
+// components/columns/status.tsx
+import type { IColumnValue } from '@wix/auto-patterns';
+import { Badge } from '@wix/design-system';
+
+export function status({ value, row }: IColumnValue<string>) {
+  // Pure rendering logic - NO HOOKS here
+  const skin = value === 'Active' ? 'success' : 'danger';
+  return <Badge skin={skin}>{value}</Badge>;
+}
+
+// components/columns/index.tsx
+import { status } from './status';
+export const useColumns = () => ({ status });
+```
+
+## 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 { useColumns } from './components/columns';
+
+// 2. Add hook call (keep all existing hook calls)
+const columns = useColumns();
+
+// 3. Add columns to PatternsWizardOverridesProvider value (keep ALL existing overrides)
+```

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

@@ -0,0 +1,89 @@
+# Custom Components Override Rules
+
+**REQUIRED**: After creating component files, you MUST update `page.tsx` to register them.
+
+## Type Definitions
+```typescript
+interface CustomComponentProps {
+  form: UseFormReturn; // react-hook-form instance
+  entity: Record<string, any>; // Initial entity state (static)
+}
+
+// Override Component Signature
+type CustomComponent = React.FC<CustomComponentProps>;
+```
+
+## Configuration Schema
+```json
+{
+  "layout": [
+    {
+      "type": "Form",
+      "form": {
+        "groups": [
+          {
+            "fields": [
+              {
+                "id": "myCustomField",
+                "type": "custom",
+                "componentId": "myCustomComponent" // Matches override key
+              }
+            ]
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+## Validation Logic
+- **IF** overriding an input field **THEN** MUST use `useController` from `@wix/patterns/form` to bind to form state.
+- **IF** needing reactivity **THEN** MUST use `form.watch()`, NEVER rely on `entity` prop for updates (it is initial state only).
+- **IF** implementing a standalone widget (not input) **THEN** can use `entity` for display-only static data.
+- **NEVER** import `useController` from `react-hook-form` directly; use `@wix/patterns/form`.
+
+## Implementation Rules
+- **MUST** be placed in `components/customComponents/` folder.
+- **MUST** export a `useComponents` hook from `components/customComponents/index.tsx`.
+- **MUST** handle form state (invalid, error message, onChange) properly via controller.
+
+## Canonical Example
+```tsx
+// components/customComponents/CustomInput.tsx
+import { useController } from '@wix/patterns/form';
+import type { CustomComponentProps } from '@wix/auto-patterns';
+import { Input, FormField } from '@wix/design-system';
+
+export const CustomInput: React.FC<CustomComponentProps> = ({ form, entity }) => {
+  const { field, fieldState } = useController({
+    name: 'title', // Matches schema field ID
+    control: form.control,
+    defaultValue: entity?.title
+  });
+
+  return (
+    <FormField label="Title" status={fieldState.error ? 'error' : undefined}>
+      <Input {...field} />
+    </FormField>
+  );
+};
+
+// components/customComponents/index.tsx
+import { CustomInput } from './CustomInput';
+export const useComponents = () => ({ CustomInput });
+```
+
+## 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 { useComponents } from './components/customComponents';
+
+// 2. Add hook call (keep all existing hook calls)
+const components = useComponents();
+
+// 3. Add components to PatternsWizardOverridesProvider value (keep ALL existing overrides)
+```

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

@@ -0,0 +1,124 @@
+# Custom Entity Header Override Rules
+
+**REQUIRED**: After creating header override files, you MUST update `page.tsx` to register them.
+
+## Type Definitions
+```typescript
+// Subtitle Override
+type SubtitleResolver = (entity: Record<string, any>) => { text: string };
+
+// Badge Override
+interface BadgeObject {
+  text: string;                     // Required: Text to display
+  skin?: BadgeSkin;                 // Optional: Visual styling
+  prefixIcon?: React.ReactElement;  // Optional: Icon before text (from @wix/wix-ui-icons-common)
+  suffixIcon?: React.ReactElement;  // Optional: Icon after text (from @wix/wix-ui-icons-common)
+}
+
+type BadgeSkin = 'success' | 'warning' | 'destructive' | 'neutral' | 'premium';
+
+type BadgesResolver = (entity: Record<string, any>) => BadgeObject[];
+```
+
+## Configuration Schema
+```json
+{
+  "entityPage": {
+    "title": {
+      "text": "Entity Details",
+      "badges": {
+        "id": "entityPageHeaderBadges"  // Must match override key
+      }
+    },
+    "subtitle": {
+      "text": "Default subtitle text",
+      "id": "entityPageHeaderSubtitle"  // Must match override key
+    }
+  }
+}
+```
+
+## Validation Logic
+- **IF** overriding subtitle **THEN** function MUST return `{ text: string }` object.
+- **IF** overriding badges **THEN** function MUST return array of `BadgeObject` (NOT JSX components).
+- **IF** `badges.id` or `subtitle.id` defined in config **THEN** matching override MUST exist.
+- **IF** logic depends on entity data **THEN** check for field existence (entity might be partial).
+- **IF** `id` in config does not match override key **THEN** override will not render.
+
+## Implementation Rules
+- **MUST** be placed in `components/entityPageHeaderSubtitle/` or `components/entityPageHeaderBadges/`.
+- **MUST** export `useEntityPageHeaderSubtitle` / `useEntityPageHeaderBadges` hooks from respective index files.
+- **MUST** be pure functions (no hooks inside the resolver functions).
+- **MUST** ensure `id` in config matches the key in override object exactly.
+- **NEVER** return JSX from badge/subtitle functions (return data objects only).
+
+## Canonical Example
+
+### 1. Subtitle Override
+```typescript
+// components/entityPageHeaderSubtitle/entityPageHeaderSubtitle.ts
+export const entityPageHeaderSubtitle = (entity: Record<string, any>) => {
+  return { text: `Created by ${entity.owner || 'Unknown'} on ${entity.date || 'N/A'}` };
+};
+
+// components/entityPageHeaderSubtitle/index.ts
+import { entityPageHeaderSubtitle } from './entityPageHeaderSubtitle';
+export const useEntityPageHeaderSubtitle = () => ({ entityPageHeaderSubtitle });
+```
+
+### 2. Badges Override
+```typescript
+// components/entityPageHeaderBadges/entityPageHeaderBadges.ts
+export const entityPageHeaderBadges = (entity: Record<string, any>) => {
+  const badges = [];
+
+  // Add status badge
+  if (entity.isActive) {
+    badges.push({ text: 'Active', skin: 'success' });
+  } else {
+    badges.push({ text: 'Inactive', skin: 'neutral' });
+  }
+
+  // Add premium badge if applicable
+  if (entity.isPremium) {
+    badges.push({ text: 'Premium', skin: 'premium' });
+  }
+
+  // Add warning badge if needed
+  if (entity.needsAttention) {
+    badges.push({ text: 'Needs Attention', skin: 'warning' });
+  }
+
+  return badges;
+};
+
+// components/entityPageHeaderBadges/index.ts
+import { entityPageHeaderBadges } from './entityPageHeaderBadges';
+export const useEntityPageHeaderBadges = () => ({ entityPageHeaderBadges });
+```
+
+## page.tsx Registration (REQUIRED)
+
+**CRITICAL: PRESERVE EXISTING OVERRIDES** - Do NOT remove existing overrides. ADD this new one alongside them.
+
+### For Subtitle Override:
+```tsx
+// 1. Add import (keep all existing imports)
+import { useEntityPageHeaderSubtitle } from './components/entityPageHeaderSubtitle';
+
+// 2. Add hook call (keep all existing hook calls)
+const entityPageHeaderSubtitle = useEntityPageHeaderSubtitle();
+
+// 3. Add entityPageHeaderSubtitle to AutoPatternsOverridesProvider value (keep ALL existing overrides)
+```
+
+### For Badges Override:
+```tsx
+// 1. Add import (keep all existing imports)
+import { useEntityPageHeaderBadges } from './components/entityPageHeaderBadges';
+
+// 2. Add hook call (keep all existing hook calls)
+const entityPageHeaderBadges = useEntityPageHeaderBadges();
+
+// 3. Add entityPageHeaderBadges to AutoPatternsOverridesProvider value (keep ALL existing overrides)
+```