@wix/auto-patterns 1.15.0 → 1.17.0

package/dist/docs/recipe-first-dashboard.md

@@ -0,0 +1,795 @@
+# Recipe 1: Creating Your First Dashboard from Scratch
+
+**Use Case**: "I want to create a complete dashboard to manage my collection (users, products, orders, etc.)"
+
+---
+
+# AI Agent Instructions for AutoPatternsApp
+
+This document serves as a comprehensive guide for AI agents to correctly generate and validate configurations for the `AutoPatternsApp` component. Follow these instructions sequentially to ensure proper implementation.
+
+## AI Usage Guidelines
+
+1. **Configuration Generation Process**:
+
+   * First, analyze the schema requirements.
+   * Then, select appropriate fields based on data types.
+   * Finally, validate against the rules before output.
+
+2. **Required Validation Steps**:
+
+   * Verify exact page count (must be 2).
+   * Confirm proper field selection (max 3 columns initially).
+   * Check all mandatory fields are present.
+   * Ensure no unsupported fields are included.
+   * Verify that every collection page has a create action that navigates to the entity page.
+
+3. **Decision-Making Priority**:
+
+   * User explicit requirements override defaults.
+   * Schema structure guides field selection.
+   * Best practices determine presentation.
+
+4. **Enum Configuration Rule (CRITICAL)**:
+
+   * When generating `enumConfig` (whether implicitly as part of another rule or explicitly upon user request), the AI **must always ask the user to provide the possible option values** for the enum field.
+   * The `value` of each option can be **any string specified by the user**, and the `label` should be derived from the `value` (e.g., if `value` is "dog", the `label` can be "Dog").
+   * The AI is strictly prohibited from guessing, inventing, or assuming the enum values or their labels.
+
+---
+
+# Core Rules
+
+## Configuration Rules
+
+* Pages array MUST contain exactly two pages.
+* Components array inside collectionPage MUST contain exactly one component with a layout array.
+* Configuration MUST come only from a JSON file.
+* DO NOT fill optional fields unless explicitly requested.
+* Select up to 3 columns initially that best represent the entity.
+* Every collection page MUST include a create action that allows users to create new entities by navigating to the entity page.
+
+## Type Binding Rules
+
+* If `type: 'collectionPage'`, only `collectionPage` field should exist.
+* If `type: 'entityPage'`, only `entityPage` field should exist.
+* No cross-mixing of types is allowed.
+
+## Override Rules
+
+* Custom overrides are restricted to documented areas only.
+* Only override columns when specific rendering is required.
+
+## Validation Rules
+
+* All configurations must align with AppConfig Structure.
+* Remove any configuration entries not in the structure.
+* Verify customColumns.enabled logic (>5 columns or explicit request).
+
+---
+
+# Instruction Guide & Best Practices
+
+This guide instructs on how to correctly integrate the `AutoPatternsApp` component from `@wix/auto-patterns` package into a Wix-based admin page.
+
+---
+
+# Component Purpose
+
+The `AutoPatternsApp` is a page-level component used to display a data collection either as a Table or Grid.
+It is configured using a JSON file conforming to the `AppConfig` interface and supports overrides for advanced use-cases.
+
+---
+
+# Installation & Setup
+
+## 1. Install Packages
+
+Install if necessary and doesn't exists in package.json:
+
+```bash
+npm install @wix/auto-patterns @wix/patterns @wix/design-system
+```
+
+## ⚠️ Critical Import Rules
+
+- **Import `AutoPatternsApp` only from `@wix/auto-patterns`** - never from other packages
+- **CRITICAL:** Always import `AppConfig` as a type import: `import type { AppConfig } from '@wix/auto-patterns/types'` - never import it as a value import
+
+## 2. Create AppConfig JSON
+
+Save this configuration as a `{collectionName}Config.patterns.json` file in the same directory as your page.tsx component.
+
+For example:
+- For a "WixPets" collection: `petsConfig.patterns.json`
+- For a "Products" collection: `productsConfig.patterns.json`
+- For a "Users" collection: `usersConfig.patterns.json`
+
+## Render the Collection Page Component
+
+Inside your page component, import the JSON configuration and use the `AutoPatternsApp` component. Since this is a page-level component, it should be the only component rendered on the page. Any other content or components should be removed to ensure proper functionality and avoid conflicts.
+
+### Page Component Example:
+
+```tsx
+import React, { type FC } from 'react';
+import { WixDesignSystemProvider } from '@wix/design-system';
+import '@wix/design-system/styles.global.css';
+import { WixPatternsProvider } from '@wix/patterns/provider';
+import { PatternsWizardOverridesProvider, AutoPatternsApp } from '@wix/auto-patterns';
+import type { AppConfig } from '@wix/auto-patterns/types';
+import { withDashboard } from '@wix/patterns';
+
+import config from './MyCollectionConfig.patterns.json';
+
+const Index: FC = () => {
+  return (
+    <WixDesignSystemProvider features={{ newColorsBranding: true }}>
+      <WixPatternsProvider>
+        <PatternsWizardOverridesProvider value={{ }}>
+          <AutoPatternsApp configuration={config as AppConfig} />
+        </PatternsWizardOverridesProvider>
+      </WixPatternsProvider>
+    </WixDesignSystemProvider>
+  );
+};
+
+export default withDashboard(Index);
+```
+
+---
+
+# 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;
+      };
+    };
+```
+
+---
+
+# Pages Configuration
+
+## ⚠️ Critical Page Rules
+
+- **Pages array must contain exactly two pages** - one collectionPage and one entityPage
+- **Exactly one page must have `appMainPage: true`** to designate it as the main page
+- **All page IDs referenced in relationships must exist in the configuration** - validate all `parentPageId` and `entityPageId` references
+- **Bind `type` strictly to matching fields** - if `type: 'collectionPage'`, only `collectionPage` field exists (no `entityPage` field), and vice versa
+
+## Default Generation
+
+* **Always generate two pages**:
+
+  * One **collectionPage** (routePath: `/`)
+  * One **entityPage** (routePath: `/[segment]/:entityId`)
+
+    * Always use `entityId` as the dynamic URL parameter, not `id`.
+    * The route path **must** include a descriptive segment (e.g., `/product/:entityId`, `/pet/:entityId`)
+    * **Never use just `/:entityId`** - this conflicts with the collection page route and breaks routing
+
+## Type and Structure Binding
+
+* If `type: 'collectionPage'`, then **only** `collectionPage` field exists (no `entityPage` field).
+* If `type: 'entityPage'`, then **only** `entityPage` field exists (no `collectionPage` field).
+* **No cross-mixing** allowed.
+
+## Page Connection Configuration
+
+### Main Page Designation
+
+* One page must be designated as the main page using the `appMainPage` property:
+  * **Exactly one page** must have `appMainPage: true`
+  * When users navigate to the root path (`/`), they will be automatically redirected to this page
+  * This is typically set on the collection page, but can be any page based on your application's requirements
+
+### Collection-Entity Page Relationships
+
+A two-way connection must be established between collection pages and entity pages:
+
+1. **From EntityPage to CollectionPage**:
+   * Each entity page must specify its parent collection page using `parentPageId`
+   * This property on the entity page references the `id` of its parent collection page
+
+2. **From CollectionPage to EntityPage**:
+   * Each collection page's component must reference its corresponding entity page:
+   * Inside the table or grid configuration (not directly in the collectionPage), specify `entityPageId` pointing to the entity page's `id`:
+   ```json
+   "components": [
+     {
+       "type": "Table", // or "Grid"
+       "table": {       // or "grid"
+         "entityPageId": "my-entity-page-id",
+         // other table/grid configuration
+       }
+     }
+   ]
+   ```
+   * ⚠️ **IMPORTANT**: The `entityPageId` field is located within the specific component configuration (table or grid), not at the collection page level
+
+### Entity Page URL Configuration
+
+* For entity pages (`type: "entityPage"`), the following URL configuration is **mandatory**:
+
+  1. **Route Path Structure**:
+     * The `route.path` **must** include a relative path segment followed by a dynamic parameter (e.g., `/product/:entityId` or `/pets/:entityId`)
+     * **Never use just `/:entityId`** - this conflicts with the collection page route `/` and breaks routing
+     * The relative path segment should be descriptive of the entity type (e.g., `/product/`, `/pet/`, `/user/`)
+     * This parameter is typically named `:entityId` by convention, but any parameter name prefixed with `:` is valid
+
+  2. **Route Parameters Mapping**:
+     * The `route.params` property is required and must map the dynamic parameter:
+     ```json
+     "route": {
+       "path": "/product/:entityId",
+       "params": {
+         "id": "entityId"
+       }
+     }
+     ```
+     * The `id` field in `route.params` must match the parameter name used in `route.path` (without the colon)
+
+
+### Key Rules for Page Connections
+
+* **Main Page Requirement**: Exactly one page must have `appMainPage: true`
+* **Reference Validity**: All page IDs referenced in `parentPageId` and `entityPageId` must exist in the configuration
+* **Relationship Consistency**: The two-way connection must be consistent - if entity page A points to collection page B, then collection page B must point to entity page A
+* **Route Structure**: Entity pages must use `/[segment]/:entityId` format (e.g., `/product/:entityId` or `/pets/:entityId`), never just `/:entityId`
+* **Route Parameters Configuration**: All entity pages must have both a dynamic parameter in `route.path` and a matching configuration in `route.params`
+
+## ⚠️ Common Type and Route Mistakes to Avoid
+
+- Using incorrect field types
+- Missing required fields
+- Including fields from wrong page type
+- Missing route.params for entity pages
+- Using `/:entityId` instead of `/segment/:entityId` for entity page routes (causes routing conflicts)
+
+# Sticky Columns Configuration
+
+## Overview
+
+Sticky columns allow you to keep specific columns visible while users scroll horizontally through wide tables. This feature improves usability by ensuring important information (like names or IDs) remains accessible during scrolling.
+
+## Configuration Properties
+
+### stickyColumns
+
+- **Type**: `number` (optional)
+- **Description**: Number of columns to make sticky from the start of the table
+- **Behavior**: Sticky columns are always the **first N columns** in the `columns` array
+- **Default**: `undefined` (no sticky columns)
+
+## Key Behavior Rules
+
+### 🔑 **Critical Rule: Position-Based Stickiness**
+- `stickyColumns: 2` means "make the **first 2 columns** sticky" (positions 0 and 1 in the `columns` array)
+- The sticky columns are determined by **array position**, not by column content
+- If columns are reordered, the sticky behavior follows the new order
+
+### 🔒 **Important: Reorder Protection**
+- To protect specific columns from being reordered away from their sticky positions, set `reorderDisabled: true` on those columns
+- This allows `customColumns.enabled: true` while protecting sticky columns from being moved
+- Without reorder protection, users can accidentally move intended sticky columns away from the beginning
+
+### ⚠️ **Validation Rules**
+- `stickyColumns` must be a positive number
+- `stickyColumns` should not exceed the total number of columns
+- Invalid values are ignored (treated as `undefined`)
+
+---
+
+# 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.
+
+---
+
+# 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
+
+---