@wix/auto-patterns 1.15.0 → 1.17.0

package/dist/docs/recipe-customization.md

@@ -0,0 +1,1703 @@
+# Recipe: Complete Customization Guide
+
+**Use Case**: "I want to customize my dashboard - from basic styling to complex custom behavior and integrations"
+
+This comprehensive guide covers customization from basic visual changes to advanced programmatic control.
+
+---
+
+# AppConfig Structure
+
+## ⚠️ Configuration Rules
+
+- **Configuration must come only from a JSON file** - never inline or from other sources
+- **DO NOT fill optional fields unless explicitly requested** - leave optional properties undefined to avoid unnecessary complexity
+- **After each configuration change, verify that the configuration strictly aligns with the structure described below** - any configuration entries not defined in this structure must be removed
+- **When generating config for the first time, select up to 3 columns from the schema that best represent the entity**
+
+## ⚠️ Common Configuration Mistakes to Avoid
+
+- Adding more than two pages
+- Mixing page types in a single configuration
+- Including undefined optional fields
+- Selecting too many initial columns
+- Not designating exactly one page as `appMainPage: true`
+- Missing or inconsistent page relationships (parentPageId/entityPageId)
+- Setting `stickyColumns` to invalid values (negative, zero, or exceeding column count)
+
+```ts
+export interface AppConfig {
+  pages: {
+    id: string; // Page unique identifier (must be unique across the app)
+    type: 'collectionPage' | 'entityPage'; // Defines page type
+    appMainPage?: boolean; // Designates this page as the main page (exactly one page must have this set to true)
+    collectionPage?: {
+      route: {
+        path: string; // Route path for the collection page (e.g., '/')
+      };
+      title: {
+        text: string; // Main page title
+        hideTotal?: boolean; // Hide total items in header. Default: true
+      };
+      subtitle?: {
+        text: string; // Optional page subtitle
+      };
+      actions?: { // Defines page-level actions for the collection page
+        primaryActions?: {
+          type: 'action' | 'menu'; // Type of primary actions layout
+          action?: { // Required when type is 'action'
+            item: {
+              id: string; // Unique identifier for the action
+              type: 'create' | 'custom'; // Action type
+              label?: string; // Text displayed for the action
+              collection: {
+                collectionId: string; // ID of the Wix Data collection
+                entityTypeSource: 'cms'; // Data source type. Always 'cms'
+              };
+              create?: { // Required when type is 'create'
+                mode: 'page'; // Create mode
+                page: {
+                  id: string; // Entity page ID to navigate to for creation
+                };
+              };
+            };
+          };
+          menu?: { // Required when type is 'menu'
+            label: string; // Label for the group
+            items: {}[]; // Array of action configurations, same structure as action.item, can include dividers
+          };
+        };
+        secondaryActions?: {
+          type: 'action' | 'menu'; // Type of secondary actions layout, same structure as primaryActions
+          action?: {}; // Same structure as primaryActions.action
+          menu?: {}; // Same structure as primaryActions.menu
+        };
+      };
+      components: [
+        {
+          entityPageId?: string; // ID of the entity page to navigate to when clicking a row
+          collection: {
+            collectionId: string; // ID of the Wix Data collection
+            entityTypeSource: 'cms'; // Data source type. Always 'cms'
+            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'
+          };
+          filters?: {
+            panelTitle?: string; // Title of the filters panel
+            items: {
+              id: string; // Unique identifier for the filter item
+              fieldId: string; // ID of the field to filter by (must be a valid type: NUMBER, DATETIME, BOOLEAN, ARRAY, ARRAY_STRING)
+              displayName?: string; // Display name of the filter item
+              openByDefault?: boolean; // Whether the filter item is open by default in the panel (accordion is open)
+              sectionTitle?: string; // Title of the filter section. Required if more than one section exists to prevent confusion
+              tagLabel?: string; // Label shown in Tag component in the table/grid when the filter is applied (e.g., "Age: 7")
+              numberConfig?: {
+                min?: number; // Minimum value
+                max?: number; // Maximum value
+                allowedDecimals?: true; // Decimal precision allowed
+              };
+              dateConfig?: {
+                mode?: 'ONLY_PREDEFINED' | 'ONLY_CUSTOM' | 'COMBINE'; // Determines filter behavior
+                presets?: (
+                  | 'SEVEN_DAYS'
+                  | 'FOURTEEN_DAYS'
+                  | 'MONTH'
+                  | 'TODAY'
+                  | 'TOMORROW'
+                  | 'NEXT_THREE_DAYS'
+                  | 'NEXT_SEVEN_DAYS'
+                  | 'NEXT_THIRTY_DAYS'
+                )[]; // Shown only if mode includes predefined presets (COMBINE or ONLY_PREDEFINED)
+                includeTime?: boolean; // Whether to allow time selection. Default is true
+              };
+              booleanConfig?: {
+                trueLabel?: string; // Label shown for the true value
+                falseLabel?: string; // Label shown for the false value
+              };
+              enumConfig?: {
+                options: {
+                  value: string; // Enum option value
+                  label: string; // Enum option label
+                }[];
+                selectionMode: 'single' | 'multiple'; // Selection behavior
+                optionType?:
+                  | 'checkbox'
+                  | 'inlineCheckbox'
+                  | 'radio'
+                  | 'select'; // Option rendering style
+              };
+            }[];
+          };
+          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)
+                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
+                      };
+                    };
+                  };
+                };
+              };
+            };
+            secondaryActions?: {
+              items: {}[]; // Array of action configurations, same structure as primaryAction.item, 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)
+            };
+          };
+          bulkActionToolbar?: {
+            primaryActions?: ({
+              type: 'action' | 'menu'; // Type of bulk action item
+              action?: { // Required when type is 'action'
+                item: {
+                  id: string; // Unique identifier for the bulk action
+                  type: 'bulkDelete' | 'custom'; // Bulk action type
+                  label?: string; // Text displayed for the action
+                  bulkDelete?: { // Required when type is 'bulkDelete'
+                    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
+                        };
+                      };
+                    };
+                  };
+                };
+              };
+              menu?: { // Required when type is 'menu'
+                label: string; // Label for the dropdown group
+                items: {}[] // Array of bulk actions configurations, same structure as action.item, can include dividers
+              };
+            })[];
+            secondaryActions?: {}[]; // Array of bulk actions configurations, same structure as primaryActions[].menu.items, can include dividers
+          };
+          toolbarTitle?: {
+            title: string; // Toolbar title above the table/grid
+            subtitle?: {
+              text: string; // Toolbar subtitle
+            };
+            showTotal?: boolean; // Show total items on toolbar. Default: false
+          };
+          search?: {
+            shown?: boolean; // Show/hide the search
+          };
+          emptyState?: {
+            title?: string; // Empty state title
+            subtitle?: string; // Empty state subtitle
+            image?: {
+              id: string; // Image ID for empty state
+            };
+            addNewCta?: {
+              id?: string; // Add New CTA ID
+              text?: string; // Add New CTA text
+            };
+            customCta?: {
+              id?: string; // Custom CTA ID
+            };
+          };
+          layout: [ // Array of layout items that define what components to render
+            {
+              type: 'Table'; // Layout item type for table rendering
+              table?: {
+                columns: {
+                  id: string; // Field ID from the collection
+                  name: string; // Column title displayed
+                  width: string; // The width of the column (required in types)
+                  sortable?: boolean; // If the column is sortable
+                  defaultSortOrder?: 'asc' | 'desc'; // Optional default sort order
+                  sortMode?: 'asc' | 'desc'; // Optional sorting mode
+                  reorderDisabled?: boolean; // Whether column reordering is disabled
+                  hideable?: boolean; // Whether column can be hidden
+                  defaultHidden?: boolean; // Whether column is hidden by default
+                  hiddenFromCustomColumnsSelection?: boolean; // Whether column is hidden from custom columns selection
+                }[];
+                customColumns?: {
+                  enabled: boolean; // Enable user customization (hide/reorder columns)
+                };
+                stickyColumns?: number; // Number of columns to make sticky from the start. Sticky columns remain visible when horizontally scrolling.
+              };
+            },
+            {
+              type: 'Grid'; // Layout item type for grid rendering
+              grid?: {
+                item: {
+                  titleFieldId: string; // Field ID to display as the item title
+                  subtitleFieldId?: string; // Field ID for the item subtitle
+                  imageFieldId?: string; // Field ID for the item image
+                  /**
+                   * Controls which content is shown in the card (preset):
+                   * - 'full': Shows both title and subtitle.
+                   * - 'title': Shows only the title.
+                   * - 'empty': Hides both title and subtitle (card appears visually empty except for image or other content).
+                   */
+                  cardContentMode?: 'full' | 'title' | 'empty';
+                  imagePlacement?: 'top' | 'side';
+                };
+              };
+            }
+          ]; // End of layout array
+        }
+      ]; // End of components array
+    };
+    entityPage?: {
+      route: {
+        path: string; // Route path for the entity page (e.g., '/product/:entityId')
+        params: {
+          id: string; // Maps dynamic parameter in path to its identifier
+        };
+      };
+      title?: {
+        text: string; // Entity page title
+      };
+      subtitle?: {
+        text: string; // Entity page subtitle
+      };
+      parentPageId?: string; // ID of the parent collection page
+      layout?: {
+        // Main layout section
+        main: {
+          type: 'card'; // Type of the card
+          card: {
+            title: {
+              text: string; // Title of the card
+            };
+            subtitle?: {
+              text: string; // Subtitle of the card
+            };
+            children: LayoutContent[]; // Array of content items that can be fields, nested containers, or components
+          };
+        }[];
+        // Sidebar layout section
+        sidebar?: {
+          type: 'card';
+          card: {
+            title: {
+              text: string; // Title of the card
+            };
+            subtitle?: {
+              text: string; // Subtitle of the card
+            };
+            children: LayoutContent[]; // Array of content items that can be fields, nested containers, or components
+          };
+        }[];
+      };
+      collectionId: string; // Related collection ID
+      entityTypeSource: 'cms'; // Data source type. Always 'cms'
+    };
+  }[];
+}
+
+type LayoutContent =
+  | {
+      type: 'field';
+      field: {
+        span?: number;
+        fieldId: string;
+      };
+    }
+  | {
+      type: 'container';
+      container: {
+        span?: number;
+        children: LayoutContent[];
+      };
+    }
+  | {
+      type: 'component';
+      component: {
+        span?: number;
+        componentId: string;
+      };
+    };
+```
+
+---
+
+# Custom Overrides
+
+## ⚠️ Override Rules
+
+- **Custom overrides are restricted to the defined areas only** - attempting to override or modify any other aspect of `AutoPatternsApp` is prohibited and can cause unexpected behavior
+- **Always verify override implementation** - when implementing custom overrides, you MUST ensure they are correctly imported and passed to the `PatternsWizardOverridesProvider`
+
+The `PatternsWizardOverridesProvider` allows you to inject custom code to override default behaviors or add additional functionality. Below are the areas where overrides can be applied:
+
+> **Note:** These are the only areas where overrides are supported. Avoid attempting to override or modify other parts of the system, as this is not supported and may lead to unexpected behavior.
+
+## Folder Structure Organization
+
+All custom overrides (components, modals, actions, columns, and other customizations) should be created in a `components` folder inside your page directory, not in a global `/src/components` folder. This keeps page-specific customizations organized alongside their respective pages.
+
+### Recommended Structure:
+
+```
+your-page/
+├── page.tsx                           // Your main page component
+├── MyCollectionConfig.patterns.json   // Configuration file
+└── components/                        // Page-specific components folder
+    ├── index.tsx                       // Exports all overrides for easy importing
+    ├── actions/                       // Custom actions
+    │   ├── index.tsx
+    │   └── myCustomAction.tsx
+    ├── columns/                       // Column overrides
+    │   ├── index.tsx
+    │   ├── name.ts
+    │   └── date.ts
+    └── customComponents/              // Custom entity page components
+        ├── index.tsx
+        ├── CustomNameField.tsx
+        └── InfoCard.tsx
+```
+
+### Importing Overrides in Your Page
+
+In your page component, import from the local components folder:
+
+```tsx
+import * as modals from './components/modals';
+import * as actions from './components/actions';
+import * as columns from './components/columns';
+import * as components from './components/customComponents';
+
+<PatternsWizardOverridesProvider value={{ modals, actions, columns, components }}>
+  <AutoPatternsApp configuration={config as AppConfig} />
+</PatternsWizardOverridesProvider>
+```
+
+### Important: Updating Index Files
+
+**When adding any new implementation (action, modal, column, or component), you MUST update the corresponding `index.tsx` file to export your new implementation.** The main page component imports from these index files, so they serve as the central export point for each type of override.
+
+For example:
+- Adding a new action → Update `./components/actions/index.tsx`
+- Adding a new modal → Update `./components/modals/index.tsx`
+- Adding a new column override → Update `./components/columns/index.tsx`
+- Adding a new custom component → Update `./components/customComponents/index.tsx`
+
+Without updating the index files, your implementations won't be available to the `PatternsWizardOverridesProvider`.
+
+## ⚠️ Common Override Mistakes to Avoid
+
+- Attempting to override unsupported areas
+- Invalid column rendering functions
+- Missing index file exports for new implementations
+- Incorrect import paths or naming mismatches
+
+## Columns
+
+Each column in the table has a default rendering based on its field type. You can override this rendering by providing a custom function for the `column.id`. This allows you to customize how specific columns are displayed.
+
+**Enhanced Column Overrides**: Column override can receive both the individual column `value` and the entire `row` data, enabling you to create complex columns that combine multiple field values from the same row.
+
+### Function Signature
+
+```typescript
+function columnOverride({ value, row }) {
+  // value: The individual column value
+  // row: The entire row object containing all field values
+  return <YourCustomRendering />;
+}
+```
+
+### Understanding Row Data
+
+**Important**: The `row` object contains all field values from the entity, where each property corresponds to a **field ID** from the collection schema. To access specific field values, use the exact field ID as defined in your collection schema.
+
+For example, if your collection schema has these fields:
+```json
+{
+  "fields": [
+    { "key": "name", "displayName": "Pet Name", "type": "TEXT" },
+    { "key": "age", "displayName": "Age", "type": "NUMBER" },
+    { "key": "isVaccinated", "displayName": "Vaccinated", "type": "BOOLEAN" },
+    { "key": "lastActivity", "displayName": "Last Activity", "type": "DATETIME" }
+  ]
+}
+```
+
+Then in your column override, you access these values using the field IDs:
+```typescript
+export function myColumn({ value, row }) {
+  // Access field values using their schema field IDs
+  const petName = row.name;           // "name" field ID
+  const petAge = row.age;             // "age" field ID
+  const isVaccinated = row.isVaccinated; // "isVaccinated" field ID
+  const lastActivity = row.lastActivity; // "lastActivity" field ID
+
+  return <YourCustomRendering />;
+}
+```
+
+### Use Cases for Row Data Access
+
+1. **Complex Display Columns**: Combine multiple fields into a single display (e.g., "Name (Age)" combining name and age fields)
+2. **Conditional Rendering**: Show different content based on other field values in the same row
+3. **Calculated Columns**: Create computed values using multiple row fields
+4. **Cross-Field Validation Display**: Show validation status based on relationships between fields
+
+### Example: Defining and Using Column Overrides
+
+In `components/columns/name.tsx`:
+
+```ts
+import React from 'react';
+
+export function name({ value, row }) {
+  // Simple value formatting
+  return <strong>{value}</strong>;
+}
+```
+
+In `components/columns/petInfo.tsx`:
+
+```ts
+import React from 'react';
+import { Box, Text } from '@wix/design-system';
+
+export function petInfo({ value, row }) {
+  // Complex column combining multiple row values
+  return (
+    <Box direction="vertical" gap={1}>
+      <Text weight="bold">{row.name}</Text>
+      <Text size="small" skin="disabled">
+        {row.age} years old • {row.type}
+      </Text>
+      {row.isVaccinated && (
+        <Text size="tiny" skin="success">✓ Vaccinated</Text>
+      )}
+    </Box>
+  );
+}
+```
+
+In `components/columns/status.tsx`:
+
+```ts
+import React from 'react';
+import { Badge } from '@wix/design-system';
+
+export function status({ value, row }) {
+  // Conditional rendering based on multiple row fields
+  if (row.isVaccinated && row.age > 1) {
+    return <Badge skin="success">Ready for Adoption</Badge>;
+  } else if (!row.isVaccinated) {
+    return <Badge skin="warning">Needs Vaccination</Badge>;
+  } else {
+    return <Badge skin="neutral">Too Young</Badge>;
+  }
+}
+```
+
+In `components/columns/fullName.tsx`:
+
+```ts
+import React from 'react';
+
+export function fullName({ value, row }) {
+  // Calculated column using multiple fields
+  return `${row.name} (owned by ${row.owner})`;
+}
+```
+
+In `components/columns/date.tsx`:
+
+```ts
+import React from 'react';
+
+export function date({ value, row }) {
+  // Access to other row data for enhanced date formatting
+  const isRecent = row.lastActivity && new Date(row.lastActivity) > new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+
+  return (
+    <span style={{ color: isRecent ? 'green' : 'inherit' }}>
+      <em>{new Date(value).toLocaleDateString()}</em>
+      {isRecent && ' (Recent)'}
+    </span>
+  );
+}
+```
+
+In `components/columns/index.tsx`:
+
+```ts
+export * from './name';
+export * from './petInfo';
+export * from './status';
+export * from './fullName';
+export * from './date';
+```
+
+**Important:** Every time you add a new column override file, you must add a corresponding export line to this `index.tsx` file. For example, if you create `price.tsx`, you must add `export * from './price';` to the index file.
+
+In the `PatternsWizardOverridesProvider`:
+
+```tsx
+import * as columns from './components/columns';
+
+<PatternsWizardOverridesProvider value={{ columns }}>
+  <AutoPatternsApp configuration={config as AppConfig} />
+</PatternsWizardOverridesProvider>
+```
+
+### Visual Representation
+
+```
+your-page/
+└── components/
+    └── columns/
+        ├── index.tsx     // Exports all column overrides
+        ├── name.tsx      // Simple value formatting
+        ├── petInfo.tsx   // Complex multi-field column
+        ├── status.tsx    // Conditional rendering column
+        ├── fullName.tsx  // Calculated column
+        └── date.tsx      // Enhanced formatting with row context
+
+PatternsWizardOverridesProvider
+ └── value.columns
+      ├── name
+      ├── petInfo
+      ├── status
+      ├── fullName
+      └── date
+```
+
+### Key Benefits of Row Data Access
+
+1. **Reduced Configuration Complexity**: Instead of adding multiple columns, create one complex column that shows related information
+2. **Better User Experience**: Present related data together in a logical, readable format
+3. **Dynamic Content**: Show different content based on the state of other fields
+4. **Data Relationships**: Highlight relationships between different field values in the same entity
+
+### Important Guidelines
+
+- **Performance**: Remember that column functions are called for every row, so keep calculations lightweight
+- **Consistency**: When using row data, ensure the column header accurately represents what's displayed
+- **Accessibility**: Maintain proper semantic structure when combining multiple values
+
+## Components
+
+Components allow you to create custom rendering for specific elements in the entity page. Each component has a unique `componentId` that corresponds to the ID specified in the layout configuration.
+
+The custom components receive two essential props:
+
+1. **form**: An instance of `UseFormReturn` from react-hook-form (re-exported through `@wix/auto-patterns/form`), giving you access to the form control, methods, and state.
+2. **entity**: A key-value object where keys are field IDs from the collection schema and values are the current field values, providing access to the entity's data.
+
+Custom components can serve two main purposes:
+
+### 1. Standalone Custom Components
+
+These components can display custom UI elements like notifications, information cards, or any other custom content that isn't directly tied to specific fields. These are useful for adding unique UI elements that enhance the entity page experience.
+
+### 2. Field Rendering Overrides
+
+You can use custom components to override the default rendering of one or more fields. This allows you to:
+- Apply custom validation logic
+- Create custom input components
+- Combine multiple fields into a single UI component
+- Add field-specific functionality not available in the default renderers
+
+### Using the useController Hook for Field Overrides
+
+When creating field overrides, use the `useController` hook from `@wix/auto-patterns/form` (a re-export of react-hook-form's hook) to connect your custom component to the form state:
+
+```tsx
+import { useController } from '@wix/auto-patterns/form'; // Always import from this path, not react-hook-form
+```
+
+The hook requires:
+- **name**: The field name you want to edit (should match the schema field ID)
+- **control**: Retrieved from `form.control`
+- **defaultValue**: Set from `entity?.[fieldId]` when it exists
+
+### Example: Defining a Custom Component
+
+Here's an example of a custom component that overrides the rendering of the "name" field:
+
+```tsx
+import React, { FC } from 'react';
+import { Box, Card, FormField, Input, Text } from '@wix/design-system';
+import { useController } from '@wix/auto-patterns/form';
+import { CustomComponentProps } from '@wix/auto-patterns/types';
+
+export const customNameField: FC<CustomComponentProps> = ({ form, entity }) => {
+  // Create a controller for the name field
+  const controller = useController({
+    name: 'name', // Field ID from the schema
+    control: form.control, // Form control
+    defaultValue: entity?.name, // Default value from entity
+  });
+
+  return (
+    <FormField
+      label="Name"
+      required={true}
+      charCount={100}
+      // Connect field state to UI
+      status={controller.fieldState.invalid ? 'error' : undefined}
+      statusMessage={controller.fieldState.error?.message}
+      dataHook={`short-text-${controller.field.name}`}
+    >
+      <Input
+        // Connect field value and onChange
+        value={controller.field.value}
+        onChange={(e) => controller.field.onChange(e.target.value)}
+        dataHook={`short-text-${controller.field.name}`}
+      />
+    </FormField>
+  );
+};
+```
+
+
+### Example: Standalone Component (Not Field-Specific)
+
+Custom components can also be used to add UI elements not tied to specific fields:
+
+```tsx
+import React, { FC } from 'react';
+import { Box, Card, Text, Button } from '@wix/design-system';
+import { CustomComponentProps } from '@wix/auto-patterns/types';
+
+export const infoCard: FC<CustomComponentProps> = ({ entity }) => {
+  return (
+    <Card>
+      <Card.Content>
+        <Box direction="vertical" gap={2}>
+          <Text weight="bold">Important Information</Text>
+          <Text>
+            This custom component can display additional information or functionality
+            that isn't directly tied to a specific field.
+          </Text>
+          {entity?.isVaccinated ? (
+            <Text skin="success">This pet is vaccinated</Text>
+          ) : (
+            <Text skin="warning">This pet needs vaccination</Text>
+          )}
+        </Box>
+      </Card.Content>
+    </Card>
+  );
+};
+```
+
+### Connecting Components in the Provider
+
+In your main page file, import and provide these components via the `PatternsWizardOverridesProvider`:
+
+```tsx
+import * as components from './components';
+
+<PatternsWizardOverridesProvider value={{ components }}>
+  <AutoPatternsApp configuration={config as AppConfig} />
+</PatternsWizardOverridesProvider>
+```
+
+### Important Guidelines for Custom Components
+
+1. **Always import from `@wix/auto-patterns/form`** instead of directly from `react-hook-form`
+2. **Follow react-hook-form best practices** - the underlying infrastructure is built on react-hook-form
+3. **Handle form state properly**:
+   - Use `controller.fieldState.invalid` for error state
+   - Use `controller.fieldState.error?.message` for error messages
+   - Connect `controller.field.value` to input values
+   - Use `controller.field.onChange` for change handlers
+4. **Component rendering**:
+   - Choose appropriate design-system components based on the field type
+   - For text fields: `Input`
+   - For multi-line text: `InputArea`
+   - For checkboxes: `Checkbox`
+   - For dates: `DatePicker`
+   - For dropdowns: `Dropdown`
+
+**Important:** Every time you create a new custom component, you must add a corresponding export line to the `./components/customComponents/index.tsx` file. For example, if you create `StatusIndicator.tsx`, you must add `export * from './StatusIndicator';` to the index file.
+
+### Understanding Reactivity in Custom Components
+
+5. **Reactivity and field value changes (IMPORTANT)**:
+   - **NEVER rely on the `entity` object for reactive UI** - it is not reactive to form changes
+   - For any reactive UI that needs to respond to field value changes in real-time:
+     - Use `form.watch('fieldName')` to observe field changes reactively
+     - Use `useController` hook when you need both read and write access to a field
+
+#### Common Reactivity Issues and Solutions
+
+##### Example: Conditional Display Based on Field Value
+
+```tsx
+// ❌ INCORRECT APPROACH (Non-reactive)
+const CustomComponent: FC<CustomComponentProps> = ({ form, entity }) => {
+  // This won't update when the user changes the name in the form
+  const showSpecialMessage = entity?.name === 'special';
+
+  return (
+    <Box>
+      <Input
+        value={form.getValues('name')}
+        onChange={(e) => form.setValue('name', e.target.value)}
+      />
+
+      {showSpecialMessage && (
+        <Text>Special message for special name!</Text>
+      )}
+    </Box>
+  );
+};
+```
+
+```tsx
+// ✅ CORRECT APPROACH (Reactive)
+const CustomComponent: FC<CustomComponentProps> = ({ form, entity }) => {
+  // This WILL update whenever the name field changes
+  const nameValue = form.watch('name');
+  const showSpecialMessage = nameValue === 'special';
+
+  return (
+    <Box>
+      <Input
+        value={nameValue}
+        onChange={(e) => form.setValue('name', e.target.value)}
+      />
+
+      {showSpecialMessage && (
+        <Text>Special message for special name!</Text>
+      )}
+    </Box>
+  );
+};
+```
+
+
+##### When to Use the Entity Object
+
+The `entity` object is useful for:
+- Setting initial values
+- Accessing read-only data that doesn't change
+- Comparing form state with original values (e.g., detecting if changes were made)
+- Initializing form fields with useController's defaultValue parameter
+
+```tsx
+// Example: Proper use of entity object with useController
+const CustomComponent: FC<CustomComponentProps> = ({ form, entity }) => {
+  // Use entity for initialization via defaultValue
+  const controller = useController({
+    name: 'name', // Field ID from the schema
+    control: form.control,
+    defaultValue: entity?.name // Initialize from entity
+  });
+
+  // Use watch for reactive updates
+  const currentName = controller.field.value;
+  const hasChanges = entity?.name !== currentName;
+
+  return (
+    <Box>
+      <FormField label="Name">
+        <Input
+          value={currentName}
+          onChange={(e) => controller.field.onChange(e.target.value)}
+        />
+      </FormField>
+      {hasChanges && (
+        <Text size="small">Original value: {entity?.name}</Text>
+      )}
+    </Box>
+  );
+};
+```
+
+### Visual Representation
+
+```
+your-page/
+└── components/
+    ├── index.tsx              // Exports all component overrides
+    ├── customNameField.tsx   // Field override component
+    ├── combinedNameFields.tsx // Multiple fields override
+    └── infoCard.tsx          // Standalone component
+
+PatternsWizardOverridesProvider
+ └── value.components
+      ├── customNameField
+      ├── combinedNameFields
+      └── infoCard
+```
+
+By using these component overrides, you can tailor the behavior and appearance of your `AutoPatternsApp` to meet specific requirements beyond what the default rendering provides.
+
+---
+
+# Collection Page Configuration
+
+## ⚠️ Collection Page Rules
+
+- **Components array inside collectionPage must contain exactly one component with a layout array**
+- **All collection pages with tables/grids must reference their corresponding entity page via `entityPageId`** in the collection configuration
+- **Enable `customColumns` only based on strict logic** - enable if more than 5 columns are defined OR user explicitly requests it, otherwise disable
+- **Row click behavior**: By default, clicking a table row navigates to the entity page. Use `onRowClick` configuration only when custom row click behavior is explicitly required
+- **When generating config for first time, select up to 3 columns from the schema that best represent the entity**
+
+## Components Array
+
+* Must include **exactly one item**.
+* Each component must have:
+  * `collection`: Collection configuration with `collectionId` and `entityTypeSource: 'cms'`
+  * `layout`: Array of layout items that determine what components to render
+
+## Layout Array
+
+The `layout` array contains the rendering components for the collection. Each layout item has:
+* `type`: Either 'Table' or 'Grid'
+* Component-specific configuration (`table` or `grid` object)
+
+### Layout Item Types:
+
+1. **Table Layout Item** (`type: 'Table'`):
+   * `table` field contains table-specific configuration
+   * Used for displaying collection in a **table view**
+   * Includes columns, actionCell, bulkActionToolbar, etc.
+
+2. **Grid Layout Item** (`type: 'Grid'`):
+   * `grid` field contains grid-specific configuration
+   * Used for **grid (card) view** of collection
+   * Includes item configuration for title/subtitle/image fields
+
+### Table/Grid View Switch Behavior:
+* When **both** Table and Grid layout items are present in the layout array, AutoPatterns automatically adds a Table/Grid view switch control so users can toggle between the two views
+* Users can toggle between table and grid views
+
+## Table Configuration
+
+* Used for displaying collection in a **table view**.
+* **customColumns.enabled** logic:
+  * Enable if:
+    * More than **5 columns** are defined
+    * OR user **explicitly** requests it
+  * Otherwise, **disable** (false)
+
+## Grid Configuration
+
+* Used for **grid (card) view** of collection.
+* `item.title`, `item.subtitle`, `item.image` fields are **Field IDs** from the schema.
+* If the user does not specify, **select the most relevant fields automatically**.
+* For grid components, it is strongly recommended to implement a primary action cell with an `update` action that navigates to the entity page. This provides users with an intuitive way to access detailed information and edit individual entities directly from the grid view.
+
+---
+
+# Collection Page Actions
+
+## ⚠️ Required Actions
+
+- **Every collection page must include a create action that navigates to the entity page for adding new entities** - this is essential for user workflow
+
+The `actions` property is an optional object within the `collectionPage` configuration, but it is strongly recommended to always include primaryActions with a create action for better user experience.
+
+## `primaryActions` and `secondaryActions` Structure
+
+Both `primaryActions` and `secondaryActions` are optional and share the same underlying structure for defining how actions are displayed. They can be configured in one of two ways:
+
+### A. Action Layout (`type: "action"`)
+*   **Description**: This layout is used to display a single, prominent page-level action. For example, a "Create New Item" button.
+*   **`action.item`**: Contains the configuration for the single action.
+
+### B. Action Menu Layout (`type: "menu"`)
+*   **Description**: This layout groups several page-level actions, often rendered as a dropdown menu or a set of related buttons under a common label.
+*   **`menu.label`**: A string that serves as the title or accessible label for the group of actions.
+*   **`menu.items`**: A flat array of action configurations, which can include divider objects for visual separation.
+
+## Individual Action Configuration
+
+Each individual action, whether standalone in an `action` layout or part of an `items` array in a `menu` layout, is defined by the action item structure (see `AppConfig Structure`).
+
+In addition to these common properties, each action item must specify a `type` which determines the action's behavior and additional required configuration.
+
+### 1. `type: "create"`
+*   **Purpose**: Navigates to an entity page, allowing the user to create a new item in the specified collection.
+*   **Details**:
+    *   `create.mode`: Must be `'page'`.
+    *   `create.page.id`: Must be the `id` of an existing `entityPage` in your `AppConfig`. This entity page should be set up to handle the creation of new entities for the `collection.collectionId`.
+
+### 2. `type: "custom"`
+*   **Purpose**: Executes custom JavaScript logic defined in your application's overrides.
+*   **Details**:
+    *   The `custom` object in the configuration is typically empty. The functionality is determined by a custom action resolver function that you implement and register in the `actions` section of your `PatternsWizardOverridesProvider`. The `id` of this action item must exactly match the name (key) of the registered custom action resolver. The resolver will receive parameters including `collectionId`.
+
+### 3. `type: "divider"`
+*   **Purpose**: Creates a visual separator between action groups in menus and lists.
+*   **Details**:
+    *   Divider actions require no additional configuration beyond `{ "type": "divider" }`.
+    *   Used within flat arrays to create logical groupings.
+
+## Note on `secondaryActions`
+
+`secondaryActions` follow the exact same structural rules (`type: "action"` or `type: "menu"`) and use the same action item options as `primaryActions`. They are typically used for less prominent or less frequently used page-level actions, often rendered in a secondary position or within a "more options" style menu.
+
+## Custom Collection Page Action Configuration
+
+Custom collection page actions execute JavaScript code that you define for collection-level operations. These actions receive parameters that give them access to collection context and utilities. Here's how to implement a custom collection page action:
+
+1. First, create the actions folder structure in your page folder:
+   ```
+   your-page/
+   ├── page.tsx
+   └── components/
+       └── actions/
+           ├── index.tsx                    // Exports all actions
+           └── exportCollection.tsx        // Your custom collection action
+   ```
+
+2. Create your collection action handler in `exportCollection.tsx`:
+   ```typescript
+   import { CustomActionCollectionPageActionResolver } from '@wix/auto-patterns';
+   import React from 'react';
+   import { Download } from '@wix/ui-icons-common';
+
+   // IMPORTANT: Function name MUST match the action id in your configuration
+   export const exportCollection: CustomActionCollectionPageActionResolver = (params) => {
+     const { actionParams, sdk } = params;
+     const { collectionId } = actionParams;
+
+     return {
+       label: 'Export Collection',
+       icon: <Download />,
+       onClick: () => {
+         // sdk is provided to custom action resolvers (see SDK Utilities section)
+         const optimisticActions = sdk.getOptimisticActions(collectionId);
+         const schema = sdk.getSchema(collectionId);
+
+         // Example: Mark entire collection as exported
+         optimisticActions.updateAll(
+           (item) => ({ lastExported: new Date() }),
+           {
+             submit: async () => {
+               // Your collection export logic here
+               console.log(`Exporting collection: ${collectionId}`);
+               // Export and update all items on server
+               return await schema.actions.bulkUpdate({ lastExported: new Date() });
+             },
+             successToast: 'Collection exported successfully',
+             errorToast: (err, {retry}) => ({
+               text: 'Export failed',
+               action: { text: 'Retry', onClick: retry }
+             })
+           }
+         );
+       },
+     };
+   };
+   ```
+
+3. Export your action in `actions/index.tsx`:
+   ```typescript
+   export * from './exportCollection';
+   ```
+
+4. Configure the action in your JSON configuration:
+   ```json
+   {
+     "id": "exportCollection",        // MUST match the function name exactly
+     "type": "custom",                // REQUIRED: Must be exactly "custom"
+     "label": "Export Collection",    // Optional: Displayed text
+     "collection": {
+       "collectionId": "WixPets",
+       "entityTypeSource": "cms"
+     }
+   }
+   ```
+
+5. Register your action in the `PatternsWizardOverridesProvider`:
+   ```typescript
+   import * as actions from './components/actions';
+
+   <PatternsWizardOverridesProvider value={{ actions }}>
+     <AutoPatternsApp configuration={config as AppConfig} />
+   </PatternsWizardOverridesProvider>
+   ```
+
+## Key Points for Custom Collection Page Actions:
+- The action `id` in the configuration MUST exactly match the function name exported from your actions folder
+- The function name and file name should follow a consistent naming convention (e.g., camelCase)
+- The implementation must be exported as a named export (not default export)
+- The implementation must use the `CustomActionCollectionPageActionResolver` type
+- Access collection context through `actionParams.collectionId`
+
+---
+
+## Custom Row Click Actions
+
+In addition to page-level actions, you can also customize what happens when users click on individual rows in your collection table. By default, clicking a row navigates to the entity page, but you can override this behavior with custom logic.
+
+**Before You Start:**
+- Only configure `onRowClick` if you need custom behavior (e.g., opening modals, side panels, custom actions)
+- If you just want navigation to entity page, don't configure `onRowClick` - it's the default behavior
+- Once you configure `onRowClick`, you must provide a complete working implementation
+
+### Configuration
+
+Row click actions are configured at the table level using the `onRowClick` property:
+
+```json
+{
+  "type": "Table",
+  "table": {
+    "columns": [...],
+    "onRowClick": {
+      "id": "handleRowClick",        // MUST match the function name exactly
+      "type": "custom",              // REQUIRED: Must be exactly "custom"
+    }
+  }
+}
+```
+
+### Implementation Requirements
+
+⚠️ **CRITICAL**: When you configure `onRowClick` in your JSON, you MUST provide a complete working implementation. The Auto Patterns framework cannot function without it.
+
+Custom row click actions use the `CustomActionCollectionPageActionOnRowClickResolver` type and MUST return a `ResolvedAction` object with all required properties:
+
+#### Required Return Object Structure:
+```typescript
+return {
+  label: string,        // REQUIRED: Action label
+  icon: ReactElement,   // REQUIRED: Icon component
+  onClick: () => void   // REQUIRED: Click handler function
+};
+```
+
+#### Complete Implementation Example:
+
+```typescript
+import { CustomActionCollectionPageActionOnRowClickResolver } from '@wix/auto-patterns';
+import React from 'react';
+import { More } from '@wix/wix-ui-icons-common';
+
+// IMPORTANT: Function name MUST match the action id in your configuration
+export const handleRowClick: CustomActionCollectionPageActionOnRowClickResolver = (params) => {
+  const { actionParams, sdk } = params;
+  const { item } = actionParams; // The clicked row's data
+
+  return {
+    label: 'View Details',           // REQUIRED
+    icon: <More />,                  // REQUIRED
+    onClick: () => {                 // REQUIRED
+      // Your custom row click logic here
+      console.log('Row clicked:', item);
+
+      // Example: Show a custom modal, perform an action, etc.
+      // You can access all SDK utilities here (see SDK Utilities section)
+      const optimisticActions = sdk.getOptimisticActions(sdk.collectionId);
+      const schema = sdk.getSchema(sdk.collectionId);
+
+      // Your custom logic...
+    },
+  };
+};
+```
+
+### Common Use Cases and Complete Examples
+
+#### 1. Opening a Side Panel Modal
+
+This is a complete working example for opening a side panel when clicking a row:
+
+**Step 1: Create the row click action** (`components/actions/openSidePanel.tsx`):
+```typescript
+import { CustomActionCollectionPageActionOnRowClickResolver } from '@wix/auto-patterns';
+import React from 'react';
+import { More } from '@wix/wix-ui-icons-common';
+
+export const openSidePanel: CustomActionCollectionPageActionOnRowClickResolver = (params) => {
+  const { actionParams, sdk } = params;
+  const { item } = actionParams;
+
+  return {
+    label: 'View Details',
+    icon: <More />,
+    onClick: () => {
+      // Open a custom modal with the item data
+      // You need to implement the modal opening mechanism
+      // This could be through a modal context, state management, etc.
+      console.log('Opening side panel for:', item);
+
+      // Example: Using a global modal state (you need to implement this)
+      // window.dispatchEvent(new CustomEvent('openSidePanel', { detail: item }));
+
+      // Or use a modal service/context that you've set up
+      // modalService.openSidePanel(item);
+    },
+  };
+};
+```
+
+**Step 2: Configure in JSON**:
+```json
+{
+  "type": "Table",
+  "table": {
+    "onRowClick": {
+      "id": "openSidePanel",
+      "type": "custom"
+    },
+    "columns": [...]
+  }
+}
+```
+
+**Step 3: Export and Register**:
+```typescript
+// components/actions/index.tsx
+export * from './openSidePanel';
+
+// page.tsx
+import * as actions from './components/actions';
+
+<PatternsWizardOverridesProvider value={{ actions }}>
+  <AutoPatternsApp configuration={config as AppConfig} />
+</PatternsWizardOverridesProvider>
+```
+
+#### 2. Direct Data Manipulation
+
+```typescript
+export const quickToggle: CustomActionCollectionPageActionOnRowClickResolver = (params) => {
+  const { actionParams, sdk } = params;
+  const { item } = actionParams;
+
+  return {
+    label: 'Quick Toggle',
+    icon: <Toggle />,
+    onClick: () => {
+      const optimisticActions = sdk.getOptimisticActions(sdk.collectionId);
+      const schema = sdk.getSchema(sdk.collectionId);
+
+      // Example: Toggle a boolean field
+      const updatedItem = { ...item, isActive: !item.isActive };
+
+      optimisticActions.updateOne(updatedItem, {
+        submit: async (items) => schema.actions.update(items[0]),
+        successToast: `${item.name} toggled successfully`,
+        errorToast: (err, {retry}) => ({
+          text: 'Toggle failed',
+          action: { text: 'Retry', onClick: retry }
+        })
+      });
+    },
+  };
+};
+```
+
+### Default vs Custom Behavior
+
+**Default Behavior (when `onRowClick` is not configured):**
+- Clicking a row automatically navigates to the entity page
+- Uses the `entityPageId` configuration to determine the target page
+- Passes the selected item's data to the entity page
+
+**Custom Behavior (when `onRowClick` is configured):**
+- Default navigation is **disabled**
+- Your custom action function is executed instead
+- You have complete control over the row click behavior
+- You can still navigate to the entity page programmatically if needed using the SDK navigation utilities
+
+### Key Points for Custom Row Click Actions:
+- **MANDATORY IMPLEMENTATION**: If you configure `onRowClick` in JSON, you MUST provide a complete working implementation - the framework cannot function without it
+- The action `id` in the configuration MUST exactly match the function name exported from your actions folder
+- The implementation must use the `CustomActionCollectionPageActionOnRowClickResolver` type
+- **Required Return Object**: Must return an object with `label`, `icon`, and `onClick` properties - all are required
+- Access the clicked item's data through `actionParams.item`
+- The implementation must be exported as a named export and registered in your `PatternsWizardOverridesProvider`
+- When `onRowClick` is configured, the default navigation to entity page is completely disabled
+- **Complete Setup Required**: You need to create the action file, export it in the index, and register it in the provider - missing any step will cause errors
+
+## Validation Checklist for Collection Page Actions
+
+✓ Every collection page must include a create action.
+✓ `actions` is an optional property of `collectionPage`.
+✓ `primaryActions` and `secondaryActions` (if defined) have a valid `type` ("action" or "menu").
+✓ If `type: "action"`, `action.item` is a valid action item configuration.
+✓ If `type: "menu"`, `menu.items` is an array of valid action item configurations that can include dividers.
+✓ Each action item contains a unique `id`, and the full `collection` object (`collectionId`, `entityTypeSource: 'cms'`).
+✓ Each action item has a supported `type` (`create`, `custom`) and its corresponding configuration block (e.g., `create` block for `type: "create"`).
+✓ `create` actions specify a `create.page.id` that matches an existing `entityPage` ID in the configuration.
+✓ `custom` actions (identified by their main `id`) correspond to an action resolver function name registered in the `actions` override.
+✓ Divider actions use `{ "type": "divider" }` format and require no additional properties.
+✓ If `onRowClick` is configured in table layout, it must have a valid `id` and `type: "custom"`.
+✓ **CRITICAL**: Custom row click actions must have corresponding implementations registered in the `actions` override - configuration without implementation will cause errors.
+✓ Custom row click action implementations must return an object with `label`, `icon`, and `onClick` properties - all are required.
+✓ Custom row click action implementations must be exported as named exports and included in the actions index file.
+✓ `onRowClick` is optional - when not configured, rows navigate to entity page by default.
+✓ **IMPORTANT**: Configuring `onRowClick` completely disables default navigation - you must handle all row click logic in your custom implementation.
+
+---
+
+## SDK Utilities
+
+The `sdk` parameter provides access to Auto Patterns utilities and context. Available in custom actions across all action types (ActionCell, BulkActions, CollectionPage actions, and EntityPage Actions).
+
+### Key SDK Utilities
+The only functions exist in sdk are:
+
+• **closeModal** - `closeModal(): void`
+  - Closes the currently open modal
+  - Example: `sdk.closeModal()` after saving or canceling
+
+• **getOptimisticActions** - `getOptimisticActions(collectionId): OptimisticActions`
+  - Provides optimistic UI updates for immediate user feedback
+  - Supports create, update, delete operations with automatic rollback on failure
+  - Example: `sdk.getOptimisticActions(sdk.collectionId).updateOne(item, { ... })`
+
+• **getSchema** - `getSchema(collectionId): SchemaConfig | undefined`
+  - Access to collection schema information (fields, types, validation)
+  - Useful for dynamic operations based on collection structure
+  - Example: `const schema = sdk.getSchema(sdk.collectionId)`
+
+• **collectionId** - `string`
+  - Current collection context identifier
+  - Available in all action contexts for referencing the active collection
+  - Example: `sdk.collectionId` to get the current collection ID
+
+---
+
+## OptimisticActions
+
+Provides immediate UI updates with automatic server synchronization and error recovery.
+
+### Usage Rules
+
+**Use OptimisticActions for:**
+- Data modification operations (create, update, delete)
+- Operations requiring immediate visual feedback
+
+**Do NOT use for:**
+- Read-only operations
+- Operations requiring server confirmation first
+
+### Core Pattern
+
+```typescript
+// Get instances from SDK (see SDK Utilities section)
+const optimisticActions = sdk.getOptimisticActions(sdk.collectionId);
+const schema = sdk.getSchema(sdk.collectionId);
+
+optimisticActions.operation(items, {
+  submit: async (items) => schema.actions.serverMethod(items),
+  successToast: 'Success message',
+  errorToast: (err, {retry}) => ({ text: 'Error message', action: { text: 'Retry', onClick: retry }})
+});
+```
+
+### Available Operations
+
+#### Create Operations
+- `createOne(item: T, params: OptimisticParams<T>): void`
+- `createMany(items: T[], params: OptimisticParams<T>): void`
+
+#### Update Operations
+- `updateOne(item: T, params: OptimisticParams<T>): void`
+- `updateMany(items: T[], params: OptimisticParams<T>): void`
+- `updateAll(transformFn: (item: T) => Partial<T>, params: OptimisticParams<T>): void`
+
+#### Delete Operations
+- `deleteOne(item: T, params: OptimisticParams<T> & { showUndoToast: true }): void`
+- `deleteMany(items: T[], params: OptimisticParams<T> & { showUndoToast: true }): void`
+- `deleteAll(params: OptimisticParams<T> & { showUndoToast: true }): void`
+
+### Type Definitions
+
+```typescript
+interface OptimisticParams<T> {
+  submit: (items: T[]) => Promise<any>;
+  successToast: string | ToastConfig;
+  errorToast: (error: Error, actions: { retry: () => void }) => ToastConfig | string;
+  showUndoToast?: boolean; // Required: true for delete operations
+}
+
+interface ToastConfig {
+  text: string;
+  action?: { text: string; onClick: () => void };
+}
+```
+
+### Validation Requirements
+
+**Before using optimistic actions:**
+- Verify `sdk.getOptimisticActions(collectionId)` returns valid instance
+- Verify `sdk.getSchema(collectionId)` returns valid schema
+- For delete operations: `showUndoToast: true` is mandatory
+- All `submit` functions must return a Promise
+
+**SDK Parameter:** Available in custom actions and modals. See SDK Utilities section for complete interface.
+
+---
+
+## SchemaConfig Usage
+
+SchemaConfig provides complete collection metadata and server actions. Essential for dynamic operations and accessing collection structure information.
+
+### Key Properties
+
+• **id** - `string`
+  - Collection identifier (e.g., "WixPets")
+  - Example: `schema.id === "WixPets"`
+
+• **idField** - `string`
+  - Primary key field name (usually "_id")
+  - Required for all update/delete operations
+  - Example: `const id = item[schema.idField]`
+
+• **displayField** - `string`
+  - Main field for displaying items (name, title, etc.)
+  - Used in UI components for item identification
+  - Example: `const label = item[schema.displayField]`
+
+• **fields** - `Record<string, Field | undefined>`
+  - Complete field definitions with types and metadata
+  - Useful for dynamic form generation or validation
+  - Example: `schema.fields.name.type === 'TEXT'`
+
+• **actions** - Server operation functions
+  - Pre-configured API calls for CRUD operations
+  - Use with optimistic actions for best UX
+  - Example: `await schema.actions.update(item)`
+
+### Available Schema Actions
+
+- schema.actions.create(item)        // Create single item
+- schema.actions.update(item)        // Update single item
+- schema.actions.delete(itemId)      // Delete by ID
+- schema.actions.bulkUpdate(updates) // Update multiple items
+- schema.actions.bulkDelete(itemIds) // Delete multiple items
+
+### Schema Validation Checklist
+
+Before using schema in operations:
+
+✓ Check if schema exists: `if (!schema) return;`
+✓ Verify required fields exist on items
+✓ Use `schema.idField` for ID operations
+✓ Use `schema.displayField` for UI display
+✓ Use `schema.actions` for server operations
+
+### Common Usage Patterns
+
+- **ActionCell**: Use `schema.actions.update()` or `schema.actions.delete()` for single item operations
+- **BulkActions**: Use `schema.actions.bulkUpdate()` or `schema.actions.bulkDelete()` for multiple items
+- **Dynamic UI**: Use `schema.fields` to build forms or validate data
+- **Error Messages**: Use `schema.displayField` to create meaningful user feedback
+
+---
+
+## Filters Configuration Notes
+
+To configure filters in a `collectionPage`, add a `filters` property inside the page's component configuration object. Each filter must reference a valid field by its `fieldId`, and the supported types are:
+
+* `numberConfig`: used with fields of type `NUMBER`
+* `dateConfig`: used with fields of type `DATETIME`
+* `booleanConfig`: used with fields of type `BOOLEAN`
+* `enumConfig`: used with fields of type `ARRAY` or `ARRAY_STRING`
+
+### Enum Configuration Implementation
+
+When implementing enum filters, you must ask the user to provide the possible option values. Never invent or assume enum values. Here's how to properly handle enumConfig:
+
+#### Example: User-Provided Enum Implementation
+
+1. First, collect the possible values from the user:
+   ```
+   User requests: "I need a filter for pet types."
+   You ask: "What are the possible values for pet types that should be available in the filter?"
+   User responds: "dog, cat, bird, rabbit, fish"
+   ```
+
+2. Then, create the `enumConfig` structure:
+   ```json
+   "enumConfig": {
+     "options": [
+       { "value": "dog", "label": "Dog" },
+       { "value": "cat", "label": "Cat" },
+       { "value": "bird", "label": "Bird" },
+       { "value": "rabbit", "label": "Rabbit" },
+       { "value": "fish", "label": "Fish" }
+     ],
+     "selectionMode": "multiple",
+     "optionType": "checkbox"
+   }
+   ```
+
+Notice how the `label` is derived from the `value` by capitalizing the first letter. The user's exact values become the `value` property.
+
+### Grouping Filters with Section Title
+
+* Filters can be grouped by sections using the `sectionTitle` property.
+* If multiple filter items share the same `sectionTitle`, they will be displayed together in a grouped section in the UI.
+* Filters without a `sectionTitle` will appear in a default section or be displayed individually.
+* Grouping helps maintain clarity, especially when dealing with multiple filter options.
+
+### Key Guidelines
+
+* **openByDefault**: Automatically expands the filter accordion when the filters panel is opened.
+* **tagLabel**: Specifies the label displayed in a Tag component on the table or grid once the filter is active. For example, if the tagLabel is "Age", the filter display might show: `Age: 7`.
+* **maxInlineFilters**: Limits the number of filters shown inline in the table toolbar. Others are accessible via the panel. Default is 0.
+* **dateConfig.mode**:
+
+  * `ONLY_PREDEFINED`: user can select only from preset options
+  * `ONLY_CUSTOM`: user must select a custom date range manually (no presets)
+  * `COMBINE`: both options available
+* **dateConfig.presets** must be omitted if mode is `ONLY_CUSTOM`.
+* **dateConfig.includeTime**: Controls whether time selection is also enabled alongside date (default is `true`).
+
+---
+
+# Entity Page Configuration
+
+## ⚠️ Entity Page Requirements
+
+All entity pages must have:
+- **A route path with descriptive segment and dynamic parameter** (e.g., `/product/:entityId`, `/pet/:entityId`) - **never just `/:entityId`** as this conflicts with collection page routing
+- **A matching `route.params` configuration** that maps the dynamic parameter
+- **A reference to their parent collection page via `parentPageId`**
+
+## Overview
+
+* Displays details for a **single entity**.
+* Always tied to a single Wix collection.
+* `entityTypeSource` is always `'cms'`.
+
+> The custom actions must be defined inside the `moreActions` array.
+
+> Note: You do not need to define a custom action to navigate to the entity page. This behavior is built-in — clicking on a row in the collection table automatically navigates to the corresponding entity page.
+
+## Entity Page Layout Configuration
+
+### Grid System
+
+- **12-Column Grid**: The layout uses a 12-column grid system.
+- The `span` property controls how many columns an item occupies (1-12).
+- When items in a row exceed 12 columns total, the next item wraps to a new line.
+- Example: If an item has `span: 8` and the next has `span: 5`, the second item will start a new line.
+
+### Layout Structure
+
+- **Main Section**: Contains primary entity information and most important fields.
+- **Sidebar Section**: Contains secondary information, metadata, or supporting content.
+- Both sections support cards that can contain fields, containers, and components.
+
+### Detailed Layout Content Types
+
+1. **Field Type**:
+   ```typescript
+   {
+     type: 'field';
+     field: {
+       span?: number; // How many columns this field occupies (1-12)
+       fieldId: string; // Must match a valid field ID from the collection schema
+     };
+   }
+   ```
+
+2. **Container Type** (for grouping related fields):
+   ```typescript
+   {
+     type: 'container';
+     container: {
+       span?: number; // How many columns this container occupies (1-12)
+       children: LayoutContent[]; // Can nest fields, other containers, or components
+     };
+   }
+   ```
+
+3. **Component Type** (for custom rendering):
+   ```typescript
+   {
+     type: 'component';
+     component: {
+       span?: number; // How many columns this component occupies (1-12)
+       componentId: string; // ID matching a component override implementation
+     };
+   }
+   ```
+
+### Layout Best Practices
+
+1. **Field Grouping**:
+   - Group related fields using containers
+   - Place frequently used fields at the top
+   - Consider the natural flow of data entry
+
+2. **Main vs. Sidebar Usage**:
+   - Main section: Put primary entity information
+   - Sidebar: Place secondary information and metadata
+
+3. **Responsive Considerations**:
+   - Use appropriate spans for different field types
+   - Text fields often benefit from larger spans
+   - Boolean fields can use smaller spans
+
+4. **Nested Containers**:
+   - Use containers to create logical groupings
+   - Don't nest containers too deeply for clarity
+   - Consider using cards for major sections instead of deeply nested containers
+
+5. **Image Handling**:
+   - For image fields, consider providing more space (larger span)
+   - Images are automatically rendered with proper controls when using the field type
+
+## ⚠️ Common Entity Page Layout Mistakes to Avoid
+
+- Using incorrect span values causing unexpected layout breaks
+- Referencing non-existent field IDs in the layout
+- Creating overly complex nested container structures
+- Failing to properly register component overrides
+- Confusing main and sidebar section usage (putting main content in sidebar)
+- Exceeding 12 total columns in a row without realizing content will wrap
+- Forgetting to specify the `collectionPagePath` value
+- Missing required `type: 'card'` structure in layout sections
+
+---
+
+## Entity Page Actions: `moreActions` Support
+
+Entity pages in AutoPatternsApp support not only a primary action (such as "Save" or "Delete") but also a flexible set of **more actions** (sometimes called "secondary actions" or `moreActions`). These allow you to provide additional contextual actions for the entity, such as custom logic, or grouped actions.
+
+> **Note:** All custom actions for entity pages must be placed in the `moreActions` array. Do not place custom actions as primary actions on entity pages. The `moreActions` array is the only supported location for custom actions on entity pages.
+
+### Configuration Structure
+
+- The `moreActions` property on the entity page is an **array** of action configurations that can include divider objects for visual separation.
+- Each action in `moreActions` is a Custom Action (type: "custom") or a Divider (type: "divider")
+
+#### Example: Adding custom actions with dividers to an entity page
+```json
+{
+  "type": "entityPage",
+  "entityPage": {
+    // ... other config ...
+    "moreActions": [
+      {
+        "id": "sendEmail",
+        "type": "custom",
+        "label": "Send Email"
+      },
+      {
+        "id": "exportData",
+        "type": "custom",
+        "label": "Export Data"
+      },
+      { "type": "divider" },
+      {
+        "id": "archiveEntity",
+        "type": "custom",
+        "label": "Archive"
+      }
+    ]
+  }
+}
+```
+
+---
+
+### CustomEntityPageMoreActionsActionResolver
+
+The `CustomEntityPageMoreActionsActionResolver` type is used to implement custom actions for the `moreActions` menu on entity pages in AutoPatternsApp. Each action in the `moreActions` array must have a corresponding resolver function registered in your overrides.
+
+#### Function Signature
+
+```typescript
+import { CustomEntityPageMoreActionsActionResolver } from '@wix/auto-patterns/types';
+
+export const myMoreAction: CustomEntityPageMoreActionsActionResolver = (params) => {
+  const { actionParams: { entity, form } , sdk } = params;
+
+  return {
+    label: 'My More Action',
+    icon: <MyIcon />, // optional
+    onClick: () => {
+      // Your custom logic here
+    },
+  };
+};
+```
+
+- **entity**: The current entity data (all field values). In actionParams.
+- **form**: The react-hook-form instance for the entity page. In actionParams.
+- **sdk**: The AutoPatterns SDK (see SDK Utilities section).
+
+---
+
+#### Key Points for CustomEntityPageMoreActionsActionResolver
+
+- The action `id` in the configuration MUST exactly match the function name exported from your actions folder.
+- The implementation must use the `CustomEntityPageMoreActionsActionResolver` type.
+- The implementation must be exported as a named export (not default export).
+- The function receives `{ actionParams, sdk }` as parameters.
+- The returned object must include at least a `label` and an `onClick` handler (optionally an `icon`).
+
+---
+
+#### Validation Checklist for More Actions
+
+✓ Each action in `moreActions` has a unique `id` and correct `type` value
+✓ Each action type only includes its required field(s)
+✓ Custom actions match implementations in overrides
+✓ The resolver is exported and registered in the `actions` property of your `PatternsWizardOverridesProvider`
+✓ The function signature matches `CustomEntityPageMoreActionsActionResolver`
+✓ The returned object includes `label`, `onClick`, and optionally `icon`
+
+---
+
+**Summary:**
+The `CustomEntityPageMoreActionsActionResolver` enables you to add custom, contextual actions to the "More Actions" menu on your entity pages. Implement the resolver, export it, and reference it by `id` in your config for seamless integration.
+
+---