@wix/auto-patterns 1.41.0 → 1.42.0

package/mcp-docs/app_config_structure.md

@@ -237,6 +237,47 @@ export interface AppConfig {
             };
             showTotal?: boolean; // Show total items on toolbar. Default: false
           };
+          views?: {
+            enabled?: boolean; // Whether to enable the views feature. Default: false
+            saveViewModalProps?: {
+              placeholderName?: string; // Placeholder text for the "new view" input when saving a new view
+              learnMore?: {
+                url?: string; // URL for the help/learn-more link in the Save View modal
+              };
+            };
+            viewsDropdownProps?: {
+              showTotal?: boolean; // Show total items count next to the current view name. Default: false
+              hideAllItemsView?: boolean; // Hide the built-in "All Items" view from the dropdown. Only works when custom presets exist. Default: false
+              customAllItemsViewLabel?: string; // Custom label for the "All Items" view. Ignored if a preset has `isDefaultView: true`. Default: "All items"
+            };
+            presets?:
+              | {
+                  type: 'categories';
+                  categories: {
+                    id: string; // Unique category identifier. ⚠️ Don't use `predefined-views` and `saved-views` as these are reserved
+                    label: string; // Category display name shown in the views control
+                    views: {}[]; // Views included in this category (same structure as presets.views)
+                    icon?: {
+                      tooltipContent: string; // Tooltip text shown on hover over the help icon
+                      size?: 'small' | 'medium'; // Size of the help icon. Default: 'small'
+                    };
+                  }[];
+                }
+              | {
+                  type: 'views';
+                  views: {
+                    id: string; // Unique view identifier. ⚠️ Don't use `all-items-view` as this is reserved
+                    label: string; // Display name for the view shown in the dropdown
+                    filters?: Record<string, AutoFilterValue | null>; // Filters to apply when the view is selected. Keys must match filter IDs declared in the filters configuration
+                    columnPreferences?: { // Column preferences controlling column visibility, sort, and order for this view
+                      id: string; // Column unique identifier
+                      direction?: 'asc' | 'desc'; // Sorting direction of the column in the view
+                      show?: boolean; // Pass false to hide the column from the view
+                    }[];
+                    isDefaultView?: boolean; // Makes this view the default selection instead of the "All Items" view. Default: false
+                  }[];
+                };
+          };
           search?: {
             shown?: boolean; // Show/hide the search
           };
@@ -477,6 +518,57 @@ type LayoutContent =
       };
     };
 
+type AutoFilterValue =
+  | {
+      filterType: 'date';
+      value:
+        | {
+            preset: DateRangeOptions | DateRangePredefinedPresetOptions;
+          }
+        | {
+            // Start date. format: MM-DD-YYYY
+            from?: string;
+            // End date. format: MM-DD-YYYY
+            to?: string;
+          };
+    }
+  | {
+      filterType: 'number';
+      value: {
+        // Minimum allowed value. default is negative infinity
+        from?: number;
+        // Maximum allowed value. default is infinity
+        to?: number;
+      };
+    }
+  | {
+      filterType: 'boolean';
+      value: {
+        // checked for true, unchecked for false, all for all
+        id: 'checked' | 'unchecked' | 'all';
+        // A string that will appear on the filter tag, after the field name, when the filter is active (appears as <field-name>: <name>)
+        name: string;
+      }[];
+    }
+  | {
+      filterType: 'enum';
+      value: {
+        // The option value (from the filter config)
+        id: string;
+        // A string that will appear on the filter tag, after the field name, when the filter is active (appears as <field-name>: <name>)
+        name: string;
+      }[];
+    }
+  | {
+      filterType: 'reference';
+      value: {
+        // The option value (from the filter config)
+        id: string;
+        // A string that will appear on the filter tag, after the field name, when the filter is active (appears as <field-name>: <name>)
+        name: string;
+      }[];
+    };
+
 ---
 
 ## Filters Configuration Notes

package/mcp-docs/auto-patterns-guide.md

@@ -315,6 +315,47 @@ export interface AppConfig {
             };
             showTotal?: boolean; // Show total items on toolbar. Default: false
           };
+          views?: {
+            enabled?: boolean; // Whether to enable the views feature. Default: false
+            saveViewModalProps?: {
+              placeholderName?: string; // Placeholder text for the "new view" input when saving a new view
+              learnMore?: {
+                url?: string; // URL for the help/learn-more link in the Save View modal
+              };
+            };
+            viewsDropdownProps?: {
+              showTotal?: boolean; // Show total items count next to the current view name. Default: false
+              hideAllItemsView?: boolean; // Hide the built-in "All Items" view from the dropdown. Only works when custom presets exist. Default: false
+              customAllItemsViewLabel?: string; // Custom label for the "All Items" view. Ignored if a preset has `isDefaultView: true`. Default: "All items"
+            };
+            presets?:
+              | {
+                  type: 'categories';
+                  categories: {
+                    id: string; // Unique category identifier. ⚠️ Don't use `predefined-views` and `saved-views` as these are reserved
+                    label: string; // Category display name shown in the views control
+                    views: {}[]; // Views included in this category (same structure as presets.views)
+                    icon?: {
+                      tooltipContent: string; // Tooltip text shown on hover over the help icon
+                      size?: 'small' | 'medium'; // Size of the help icon. Default: 'small'
+                    };
+                  }[];
+                }
+              | {
+                  type: 'views';
+                  views: {
+                    id: string; // Unique view identifier. ⚠️ Don't use `all-items-view` as this is reserved
+                    label: string; // Display name for the view shown in the dropdown
+                    filters?: Record<string, AutoFilterValue | null>; // Filters to apply when the view is selected. Keys must match filter IDs declared in the filters configuration
+                    columnPreferences?: { // Column preferences controlling column visibility, sort, and order for this view
+                      id: string; // Column unique identifier
+                      direction?: 'asc' | 'desc'; // Sorting direction of the column in the view
+                      show?: boolean; // Pass false to hide the column from the view
+                    }[];
+                    isDefaultView?: boolean; // Makes this view the default selection instead of the "All Items" view. Default: false
+                  }[];
+                };
+          };
           search?: {
             shown?: boolean; // Show/hide the search
           };
@@ -555,6 +596,57 @@ type LayoutContent =
       };
     };
 
+type AutoFilterValue =
+  | {
+      filterType: 'date';
+      value:
+        | {
+            preset: DateRangeOptions | DateRangePredefinedPresetOptions;
+          }
+        | {
+            // Start date. format: MM-DD-YYYY
+            from?: string;
+            // End date. format: MM-DD-YYYY
+            to?: string;
+          };
+    }
+  | {
+      filterType: 'number';
+      value: {
+        // Minimum allowed value. default is negative infinity
+        from?: number;
+        // Maximum allowed value. default is infinity
+        to?: number;
+      };
+    }
+  | {
+      filterType: 'boolean';
+      value: {
+        // checked for true, unchecked for false, all for all
+        id: 'checked' | 'unchecked' | 'all';
+        // A string that will appear on the filter tag, after the field name, when the filter is active (appears as <field-name>: <name>)
+        name: string;
+      }[];
+    }
+  | {
+      filterType: 'enum';
+      value: {
+        // The option value (from the filter config)
+        id: string;
+        // A string that will appear on the filter tag, after the field name, when the filter is active (appears as <field-name>: <name>)
+        name: string;
+      }[];
+    }
+  | {
+      filterType: 'reference';
+      value: {
+        // The option value (from the filter config)
+        id: string;
+        // A string that will appear on the filter tag, after the field name, when the filter is active (appears as <field-name>: <name>)
+        name: string;
+      }[];
+    };
+
 ---
 
 ## Filters Configuration Notes
@@ -3664,6 +3756,40 @@ function columnOverride(props: IColumnValue<string>) {
 }
 ```
 
+### Important Guidelines for Column Functions
+
+**Column ID Naming**: Column IDs are always in camelCase, and your function names should match exactly:
+- Column ID: `petName` → Function name: `petName`
+- Column ID: `isVaccinated` → Function name: `isVaccinated`
+- Column ID: `lastActivity` → Function name: `lastActivity`
+
+**React Limitations**: Column override functions are **NOT React function components**, which means:
+- ❌ **No React hooks allowed** (useState, useEffect, useContext, etc.)
+- ❌ **No custom hook calls** inside the function
+- ✅ **Only pure rendering logic** with JSX return
+
+**Using Hooks in Column Overrides**: If you need React hooks, create a separate React component and return it from your column function:
+
+```typescript
+// ❌ WRONG - Hooks directly in column function
+export function myColumn({ value, row }: IColumnValue<string>) {
+  const [state, setState] = useState(value); // ERROR: Hooks not allowed!
+  return <span>{state}</span>;
+}
+
+// ✅ CORRECT - Hooks in separate component
+function MyColumnComponent({ value, row }: IColumnValue<string>) {
+  const [state, setState] = useState(value); // ✅ Hooks allowed in React components
+  const contextValue = useContext(MyContext); // ✅ Context hooks work here
+
+  return <span>{state} - {contextValue}</span>;
+}
+
+export function myColumn(props: IColumnValue<string>) {
+  return <MyColumnComponent {...props} />; // ✅ Return React component
+}
+```
+
 ### Type-Specific Examples
 
 The generic type `T` in `IColumnValue<T>` should match your field's data type:
@@ -3925,6 +4051,9 @@ AutoPatternsOverridesProvider
 
 ### Important Guidelines
 
+- **Function Naming**: Column function names must be in camelCase and match the column ID exactly
+- **No React Hooks**: Column functions are NOT React components - no useState, useEffect, useContext, etc.
+- **Hook Workaround**: If you need hooks, create a separate React component and return it from your column function
 - **TypeScript Usage**: Always use `IColumnValue<T>` and import it from `@wix/auto-patterns/types`
 - **Type Matching**: Ensure the generic type `T` matches your field's actual data type (string, number, boolean, etc.)
 - **Performance**: Remember that column functions are called for every row, so keep calculations lightweight
@@ -5431,3 +5560,341 @@ export const quickUpdate: CustomActionCellActionResolver = (params) => {
   };
 };
 ```
+
+---
+
+# Views Configuration (Collection Level)
+
+Views let users quickly switch between predefined table or grid configurations (filters, column visibility/sort), and optionally save their own configurations.
+
+To configure views in a `collectionPage`, add a `views` property inside the page's component configuration object.
+
+### Key Guidelines
+
+* **enabled**: Must be set to `true` to activate the views feature.
+* **Precedence over toolbarTitle**: When views are enabled, they take precedence over `toolbarTitle` configuration.
+* **Column preferences**: To control column visibility and order in views, you must enable custom columns in your table config (`table.customColumns.enabled: true`).
+* **Filter references**: Filters used in preset views must reference existing filter IDs from your `filters.items` configuration.
+* **Reserved identifiers**: Don't use reserved IDs like `predefined-views`, `saved-views`, or `all-items-view`.
+
+### Views vs Categories
+
+* **Individual views** (`type: 'views'`): Use for simple preset configurations
+* **Categories** (`type: 'categories'`): Use to group related views together under labeled sections
+
+### Default View Behavior
+
+* By default, the "All Items" view is shown as the first option
+* Set `isDefaultView: true` on any preset view to make it the default instead
+* Use `hideAllItemsView: true` to hide the "All Items" view when custom presets exist
+* Use `customAllItemsViewLabel` to change the "All Items" label (ignored if a preset is set as default)
+
+## Configuration
+
+For the complete interface definitions and detailed field documentation, see the views section in [app_config_structure.md](./app_config_structure.md#views-configuration-notes)
+
+## Usage Examples - Basic
+
+### Simple setup
+Enable the views feature and manage views (save, rename, delete, set as default).
+
+```ts
+views: {
+  enabled: true
+}
+```
+
+### Preset view
+Create a preset view.
+
+For example a view that displays the `name` column in ascending order.
+```ts
+views: {
+  enabled: true,
+  presets: {
+    type: 'views',
+    views: [
+      {
+        id: 'ascending-name',
+        label: 'Ascending names',
+        columnPreferences: [{ id: 'name', direction: 'asc' }],
+      },
+    ],
+  },
+}
+```
+
+### Presets Categories
+Group views under labeled categories.
+
+For example, two views that sort the `price` column ascending and descending, grouped under 'Price' category
+
+```ts
+views: {
+  enabled: true,
+  presets: {
+    type: 'categories',
+    categories: [
+      {
+        id: 'price',
+        label: 'Price',
+        views: [
+          {
+            id: 'price-low-to-high',
+            label: 'Low to High',
+            columnPreferences: [{ id: 'price', direction: 'asc' }],
+          },
+          {
+            id: 'price-high-to-low',
+            label: 'High to Low',
+            columnPreferences: [{ id: 'price', direction: 'desc' }],
+          },
+        ],
+      },
+    ],
+  },
+}
+```
+
+### Category help tooltip icon
+Add a help tooltip icon next to the category name using the `icon` property.
+
+```ts
+views: {
+  enabled: true,
+  presets: {
+    type: 'categories',
+    categories: [
+      {
+        id: 'price',
+        label: 'Price',
+        icon: {
+          tooltipContent: 'These views sort by the item price.',
+          size: 'small',
+        },
+        views: [
+          // some views...
+        ],
+      },
+    ],
+  },
+}
+```
+
+## Usage Examples - Advanced presets
+
+### Columns visibility and order
+```
+Note that when controlling columns visibility, you always need to specify which columns you wish to show. a column without `{show: true}` will be hidden.
+If you wish to hide a certain column or columns - you must pass all the other ids.
+```
+
+The `columnPreferences` array controls both visibility and order together. The array order determines the display order, and `show: true` controls visibility.
+
+Examples:
+
+```ts
+views: {
+  enabled: true,
+  presets: {
+    type: 'views',
+    views: [
+      {
+        id: 'compact-view',
+        label: 'Compact',
+        columnPreferences: [
+          // The columns will be displayed in this order, re-order the array to control the columns' order
+          { id: 'name', show: true},
+          { id: 'price', show: true },
+          { id: 'age', show: true },
+        ],
+      }
+    ],
+  },
+}
+```
+
+### Filters
+
+#### Date filter
+Apply a filter for date data type. A 'fixed' period can be used (last week, last month, next week...) or a custom range between actual dates.
+
+Examples:
+```ts
+filters: {
+  // some date filter definition with filterId: 'createdAt-filter', supporting presets and custom ranges
+},
+views: {
+  enabled: true,
+  presets: {
+    type: 'views',
+    views: [
+      {
+        // Fixed preset (last 7 days)
+        id: 'recent-created',
+        label: 'Created: Last 7 days',
+        filters: {
+          'createdAt-filter': { filterType: 'date', value: { preset: 'SEVEN_DAYS' } },
+        },
+      },
+      {
+        // Closed range (between two dates)
+        id: 'created-in-2025',
+        label: 'Created in 2025',
+        filters: {
+          'createdAt-filter': { filterType: 'date', value: { from: '01-01-2025', to: '12-31-2025' } },
+        },
+      },
+    ],
+  },
+}
+```
+
+#### Number filter
+Apply a filter for numeric data type. You can filter by minimum only, maximum only, or a closed range.
+
+Examples:
+```ts
+filters: {
+  // some number filter definition with filterId: 'price-filter' and lower boundary of 0
+},
+views: {
+  enabled: true,
+  presets: {
+    type: 'views',
+    views: [
+      {
+        // Closed range — 10 ≤ price ≤ 100
+        id: 'price-10-to-100',
+        label: 'Price: 10–100',
+        filters: {
+          'price-filter': { filterType: 'number', value: { from: 10, to: 100 } },
+        },
+      },
+    ],
+  },
+}
+```
+
+#### Boolean filter
+Apply a filter for boolean data type. Choose items where the value is true or false. You can use the `name` field to control what will be written in the filter label when it's applied.
+
+Examples:
+```ts
+filters: {
+  // some boolean filter definition with filterId: 'inStock-filter'
+},
+views: {
+  enabled: true,
+  presets: {
+    type: 'views',
+    views: [
+      {
+        // Items where value is true
+        id: 'only-in-stock',
+        label: 'In stock only',
+        // we will use id: 'unchecked' for false
+        filters: {
+          'inStock-filter': { filterType: 'boolean', value: [{ id: 'checked', name: 'In stock' }] },
+        },
+      },
+    ],
+  },
+}
+```
+
+#### Enum filter
+Apply a filter for enum (options) data type. The value is an array of selected options. You can use the `name` field to control what will be written in the filter label when it's applied
+
+Examples:
+```ts
+filters: {
+  // some enum filter definiton with filterId: 'category-filter', and options that include the values 'pets' and 'toys'
+},
+views: {
+  enabled: true,
+  presets: {
+    type: 'views',
+    views: [
+      {
+        id: 'pets-and-toys',
+        label: 'Categories: Pets & Toys',
+        filters: {
+          'category-filter': {
+            filterType: 'enum',
+            value: [
+              { id: 'pets', name: 'Pets' },
+              { id: 'toys', name: 'Toys' },
+            ],
+          },
+        },
+      },
+    ],
+  },
+}
+```
+
+#### Reference filter
+Apply a filter for reference data type. The value is an array of selected options. You can use the `name` field to control what will be written in the filter label when it's applied
+
+Examples:
+```ts
+filters: {
+  // some reference filter definition with filterId: 'owner-filter'
+},
+views: {
+  enabled: true,
+  presets: {
+    type: 'views',
+    views: [
+      {
+        id: 'owners-a-b',
+        label: 'Owners: A & B',
+        filters: {
+          'owner-filter': {
+            filterType: 'reference',
+            value: [
+              { id: 'owner-a-id', name: 'Owner A' },
+              { id: 'owner-b-id', name: 'Owner B' },
+            ],
+          },
+        },
+      },
+    ],
+  },
+}
+```
+
+## About Column Preferences
+⚠️ **Note**: To control column visibility and order in a view, you must enable custom columns in your table config (`table.customColumns.enabled: true`). See the App Config Structure doc: [app_config_structure.md](./app_config_structure.md).
+
+Column preferences allows to control:
+1. Column's sorting
+2. Column's visibility and order
+
+### Sorting
+The `direction` field can be used to decide the sorting for a column in a preset view.
+
+Note that the column must be configured with `sortable: true` in the columns config.
+
+For example, to sort the column `age`:
+```ts
+columnPreferences: [
+  {
+    id: `age`, // the column id
+    direction: 'asc', // we can also use 'desc'
+  }
+]
+```
+
+### Visibility & Order
+Columns visibility and order are controlled together via the `show` field on `columnPreferences`.
+If you wish to change visibility and order: list ALL the columns you want to see with `{ show: true }` and they’ll be shown in exactly that order. Columns that can’t be hidden (`hideable: false` or `hiddenFromCustomColumnsSelection: true`) are always shown even if you don’t list them. Columns marked `reorderDisabled: true` keep their original position and ignore reordering.
+
+## About Filters (in a preset view)
+Filters used in a preset are referenced by their filter item `id` from your app config. If a referenced filter id does not exist in the app config, it is ignored. Ensure all used filters are defined under `filters.items`.
+
+Example usages available here: [Filters examples](#filters)
+
+**Supported filter value shapes**: See the complete `AutoFilterValue` type definition and all related filter value types (`DateFilterValue`, `NumberFilterValue`, `BooleanFilterValue`, `EnumFilterValue`, `ReferenceFilterValue`) in [app_config_structure.md](./app_config_structure.md).
+

package/mcp-docs/custom_overrides.md

@@ -179,6 +179,40 @@ function columnOverride(props: IColumnValue<string>) {
 }
 ```
 
+### Important Guidelines for Column Functions
+
+**Column ID Naming**: Column IDs are always in camelCase, and your function names should match exactly:
+- Column ID: `petName` → Function name: `petName`
+- Column ID: `isVaccinated` → Function name: `isVaccinated`
+- Column ID: `lastActivity` → Function name: `lastActivity`
+
+**React Limitations**: Column override functions are **NOT React function components**, which means:
+- ❌ **No React hooks allowed** (useState, useEffect, useContext, etc.)
+- ❌ **No custom hook calls** inside the function
+- ✅ **Only pure rendering logic** with JSX return
+
+**Using Hooks in Column Overrides**: If you need React hooks, create a separate React component and return it from your column function:
+
+```typescript
+// ❌ WRONG - Hooks directly in column function
+export function myColumn({ value, row }: IColumnValue<string>) {
+  const [state, setState] = useState(value); // ERROR: Hooks not allowed!
+  return <span>{state}</span>;
+}
+
+// ✅ CORRECT - Hooks in separate component
+function MyColumnComponent({ value, row }: IColumnValue<string>) {
+  const [state, setState] = useState(value); // ✅ Hooks allowed in React components
+  const contextValue = useContext(MyContext); // ✅ Context hooks work here
+
+  return <span>{state} - {contextValue}</span>;
+}
+
+export function myColumn(props: IColumnValue<string>) {
+  return <MyColumnComponent {...props} />; // ✅ Return React component
+}
+```
+
 ### Type-Specific Examples
 
 The generic type `T` in `IColumnValue<T>` should match your field's data type:
@@ -440,6 +474,9 @@ AutoPatternsOverridesProvider
 
 ### Important Guidelines
 
+- **Function Naming**: Column function names must be in camelCase and match the column ID exactly
+- **No React Hooks**: Column functions are NOT React components - no useState, useEffect, useContext, etc.
+- **Hook Workaround**: If you need hooks, create a separate React component and return it from your column function
 - **TypeScript Usage**: Always use `IColumnValue<T>` and import it from `@wix/auto-patterns/types`
 - **Type Matching**: Ensure the generic type `T` matches your field's actual data type (string, number, boolean, etc.)
 - **Performance**: Remember that column functions are called for every row, so keep calculations lightweight

package/mcp-docs/index.md

@@ -26,6 +26,10 @@ This index maps user requests to the appropriate section IDs for fetching releva
 **Topics**: Collection page components, table/grid layouts, column configuration
 **Keywords**: collection page, table/grid configuration, layout arrays, Table/Grid layouts, column setup, customColumns, view switching, displaying collections, list views
 
+### ID: `views`
+**Topics**: Views configuration, presets, categories, filters integration, column preferences, default view
+**Keywords**: views, presets, categories, columnPreferences, filters, default view, All items, learnMore, placeholder, showTotal
+
 ### ID: `collection_page_actions`
 **Topics**: Page-level actions, create actions, custom collection actions, action menus
 **Keywords**: page-level actions, collection actions, create actions, adding new items, primaryActions, secondaryActions, action menus, custom actions, navigation