@wix/auto-patterns 1.40.0 → 1.42.0

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
           };
@@ -340,6 +381,9 @@ export interface AppConfig {
              * Whether drag and drop is enabled. When enabled, the [schema](./schema_config.md) must support a "move" action.
              */
             enabled: boolean;
+            dragAndDropCancel?: {
+              id?: string; // Optional ID that maps to a dynamic drag-and-drop cancel override function
+            };
           };
           layout: [ // Array of layout items that define what components to render
             {
@@ -552,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
@@ -3661,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:
@@ -3922,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
@@ -4735,12 +4867,53 @@ Slots provide a powerful way to enhance collection pages with custom functionali
 
 **⚠️ CRITICAL**: When implementing custom data sources that make HTTP requests, you **MUST** wrap specific HTTP calls with proper error handling. This ensures consistent error management, prevents unhandled promise rejections, and provides better user experience.
 
+## 🚨 GOLDEN RULE: If it's a Wix Library, Wrap it with errorHandler!
+
+**Simple Rule for AI Agents:**
+- **ANY Wix SDK call** from libraries with `@wix/` prefix → **ALWAYS wrap with `errorHandler.withErrorHandler`**
+- This includes: `@wix/data`, `@wix/stores`, `@wix/events`, `@wix/bookings`, `@wix/crm`, and ALL other `@wix/*` packages
+- **NO exceptions** - all Wix SDK calls must use error handling
+
+### ❌ DON'T DO THIS (Common Mistake)
+
+```typescript
+import { items } from '@wix/data';
+
+// ❌ WRONG - No errorHandler wrapping
+async function getAllPets() {
+  try {
+    const result = await items.query('WixPets').find();
+    return result.items;
+  } catch (error) {
+    console.error(error);
+    throw error;
+  }
+}
+```
+
+### ✅ DO THIS (Correct Pattern)
+
+```typescript
+import { items } from '@wix/data';
+import { errorHandler } from '@wix/essentials';
+
+// ✅ CORRECT - Wix SDK call wrapped with errorHandler
+async function getAllPets() {
+  return errorHandler.withErrorHandler(
+    async () => {
+      const result = await items.query('WixPets').find();
+      return result.items;
+    },
+    {}
+  );
+}
+```
 ## What Requires Error Handling
 
 **ONLY the following HTTP requests** in your custom data source actions must be wrapped with `errorHandler.withErrorHandler`:
 
 - **httpClient from @wix/essentials** (e.g., `httpClient.request(getDummyEntity(...))`)
-- **Wix APIs** (e.g., `wix/data`, `wix/stores`, `items.get()`, `items.insert()`, `collections.getDataCollection()`)
+- **Wix API calls from libraries with `wix/` prefix** (e.g., `@wix/data`, `@wix/stores`, `@wix/events`, `@wix/bookings`, `collections.getDataCollection()`, etc.)
 - **httpClient.fetchWithAuth()** calls
 
 **DO NOT use errorHandler.withErrorHandler with:**
@@ -4878,12 +5051,68 @@ return errorHandler.withErrorHandler(async () => {
 }, {});
 ```
 
-**Wix APIs (wix/data, wix/stores):**
+**Wix APIs (@wix/data, @wix/stores, @wix/crm, etc.):**
 
 ```typescript
+import { items } from '@wix/data';
+import { errorHandler } from '@wix/essentials';
+
+// ✅ CORRECT: Wix Data API calls wrapped with errorHandler
 return errorHandler.withErrorHandler(async () => {
   return await items.get(collectionId, entityId);
 }, {});
+
+// ✅ CORRECT: Query operations wrapped with errorHandler
+return errorHandler.withErrorHandler(async () => {
+  return await items.query('WixPets').find();
+}, {});
+
+// ✅ CORRECT: Insert operations wrapped with errorHandler
+return errorHandler.withErrorHandler(async () => {
+  return await items.insert(collectionId, dataItem);
+}, {});
+
+// ✅ CORRECT: Update operations wrapped with errorHandler
+return errorHandler.withErrorHandler(async () => {
+  return await items.update(collectionId, dataItem);
+}, {});
+
+// ✅ CORRECT: Delete operations wrapped with errorHandler
+return errorHandler.withErrorHandler(async () => {
+  return await items.remove(collectionId, itemId);
+}, {});
+
+// ✅ CORRECT: Bulk delete operations wrapped with errorHandler
+return errorHandler.withErrorHandler(async () => {
+  return await items.bulkRemove(collectionId, itemIds);
+}, {});
+```
+
+**All Other Wix API calls from libraries with `@wix/` prefix:**
+
+```typescript
+import { stores } from '@wix/stores';
+import { events } from '@wix/events';
+import { bookings } from '@wix/bookings';
+import { contacts } from '@wix/crm';
+import { errorHandler } from '@wix/essentials';
+
+// ✅ CORRECT: All Wix API calls from @wix/* libraries must be wrapped
+return errorHandler.withErrorHandler(async () => {
+  return await stores.queryProducts().find();
+}, {});
+
+return errorHandler.withErrorHandler(async () => {
+  return await events.queryEvents().find();
+}, {});
+
+return errorHandler.withErrorHandler(async () => {
+  return await bookings.queryBookings().find();
+}, {});
+
+return errorHandler.withErrorHandler(async () => {
+  return await contacts.queryContacts().find();
+}, {});
 ```
 
 **httpClient.fetchWithAuth() calls:**
@@ -4931,25 +5160,120 @@ The error handling in your custom data source integrates seamlessly with AutoPat
 **BEFORE implementing ANY custom action or data source, AI agents MUST verify:**
 
 ### ✅ Error Handling Requirements
-- **httpClient from @wix/essentials** is wrapped with `errorHandler.withErrorHandler`
-- **Wix APIs (wix/data, wix/stores, etc)** are wrapped with `errorHandler.withErrorHandler`
-- **httpClient.fetchWithAuth()** calls are wrapped with `errorHandler.withErrorHandler`
-- **External API calls are NOT wrapped** with errorHandler (e.g., fetch(), axios, third-party HTTP clients)
-- **SDK actions are used directly** without error handling (e.g., `sdk.getOptimisticActions()`, `sdk.getSchema()`)
-- **@wix/essentials** is installed as a dependency
+- ✅ **ALL Wix API calls from `@wix/*` libraries** are wrapped with `errorHandler.withErrorHandler`
+  - Including: `@wix/data`, `@wix/stores`, `@wix/events`, `@wix/bookings`, `@wix/crm`, and ALL other `@wix/*` packages
+- ✅ **httpClient from @wix/essentials** is wrapped with `errorHandler.withErrorHandler`
+- ✅ **httpClient.fetchWithAuth()** calls are wrapped with `errorHandler.withErrorHandler`
+- ✅ **External API calls are NOT wrapped** with errorHandler (e.g., fetch(), axios, third-party HTTP clients)
+- ✅ **SDK actions are used directly** without error handling (e.g., `sdk.getOptimisticActions()`, `sdk.getSchema()`)
+- ✅ **@wix/essentials** is installed as a dependency
+
+### ✅ Correct API Signature Verification
+- ✅ **Check TypeScript/linter errors FIRST** - they tell you when the API is used incorrectly
+- ✅ **Verify imports are correct** - `import { items } from '@wix/data'` (not default imports)
+- ✅ **Use correct method signatures** - refer to the API reference section
+- ✅ **Pass correct parameters** - verify collectionId, itemId, and data structure
+- ✅ **Handle return values correctly** - `.find()` returns `{ items, ... }`, not just items array
 
 ### ✅ Implementation Checklist
-- **Read this error handling documentation** before implementing any custom action
-- **Identify the type of HTTP request** being made (Wix vs External)
-- **Apply the correct error handling pattern** based on the request type
-- **Test error scenarios** to ensure proper error handling
-- **Verify error messages** are user-friendly and actionable
+- ✅ **Read this error handling documentation** before implementing any custom action
+- ✅ **Identify the type of HTTP request** being made (Wix vs External)
+- ✅ **Apply the correct error handling pattern** based on the request type
+- ✅ **Test error scenarios** to ensure proper error handling
+- ✅ **Verify error messages** are user-friendly and actionable
+- ✅ **Run linter after implementation** to catch any API usage errors
 
 ### ✅ Common Mistakes to Avoid
 - ❌ **NEVER** wrap external API calls (fetch, axios) with errorHandler
 - ❌ **NEVER** wrap SDK methods (sdk.getOptimisticActions) with errorHandler
 - ❌ **NEVER** forget to wrap Wix HTTP requests with errorHandler
 - ❌ **NEVER** implement custom actions without reading this documentation first
+- ❌ **NEVER** use incorrect API signatures (e.g., `items.queryDataItems()` instead of `items.query()`)
+- ❌ **NEVER** ignore TypeScript/linter errors - they indicate incorrect API usage
+- ❌ **NEVER** use try-catch blocks instead of errorHandler for Wix SDK calls
+
+## 🎯 Common Wix SDK API Reference
+
+### @wix/data - Data Items API
+
+**ALWAYS use with errorHandler.withErrorHandler:**
+
+```typescript
+import { items } from '@wix/data';
+import { errorHandler } from '@wix/essentials';
+
+// Query all items
+errorHandler.withErrorHandler(async () => {
+  const result = await items.query('WixPets').find();
+  return result.items;
+}, {});
+
+// Query with filters
+errorHandler.withErrorHandler(async () => {
+  const result = await items.query('WixPets')
+    .contains('name', 'fluffy')
+    .eq('age', 5)
+    .find();
+  return result.items;
+}, {});
+
+// Get single item by ID
+errorHandler.withErrorHandler(async () => {
+  const item = await items.get('WixPets', itemId);
+  return item;
+}, {});
+
+// Insert new item
+errorHandler.withErrorHandler(async () => {
+  const newItem = await items.insert('WixPets', { name: 'Fluffy', age: 5 });
+  return newItem;
+}, {});
+
+// Update existing item
+errorHandler.withErrorHandler(async () => {
+  const updatedItem = await items.update('WixPets', { _id: itemId, name: 'Updated Name' });
+  return updatedItem;
+}, {});
+
+// Delete single item
+errorHandler.withErrorHandler(async () => {
+  await items.remove('WixPets', itemId);
+}, {});
+
+// Bulk delete items
+errorHandler.withErrorHandler(async () => {
+  await items.bulkRemove('WixPets', [itemId1, itemId2, itemId3]);
+}, {});
+```
+
+### @wix/essentials - Error Handler
+
+```typescript
+import { errorHandler } from '@wix/essentials';
+
+// Basic pattern (recommended)
+errorHandler.withErrorHandler(
+  async () => {
+    // Your Wix SDK call here
+    return await items.query('WixPets').find();
+  },
+  {
+    // Optional: Custom error handling
+    handleError: (error) => {
+      console.error('Custom error handling:', error);
+      throw error; // Re-throw to show error to user
+    },
+  }
+);
+
+// Simple pattern (empty options object)
+errorHandler.withErrorHandler(
+  async () => {
+    return await items.query('WixPets').find();
+  },
+  {}
+);
+```
 
 ## Quick Decision Tree for AI Agents
 
@@ -4960,7 +5284,7 @@ The error handling in your custom data source integrates seamlessly with AutoPat
    - **YES** → Go to step 2
 
 2. **What type of HTTP request?**
-   - **Wix APIs** (httpClient, wix/data, wix/stores) → **WRAP with errorHandler.withErrorHandler**
+   - **Wix API libraries with `@wix/` prefix** (@wix/data, @wix/stores, @wix/events, @wix/bookings, @wix/crm) → **WRAP with errorHandler.withErrorHandler**
    - **External APIs** (fetch, axios, third-party) → **NO errorHandler needed**
    - **SDK methods** (sdk.getOptimisticActions, sdk.getSchema) → **NO errorHandler needed**
 
@@ -4969,6 +5293,15 @@ The error handling in your custom data source integrates seamlessly with AutoPat
    - **External requests** are NOT wrapped
    - **SDK methods** are used directly
 
+## 🚨 TypeScript Error Detection
+
+**CRITICAL**: If you see TypeScript/linter errors when using Wix SDK methods:
+
+1. ✅ **Check the import** - Make sure you're importing from the correct package
+2. ✅ **Check the method signature** - Verify you're using the correct API signature (refer to the API reference above)
+3. ✅ **Check errorHandler wrapping** - Ensure the call is wrapped with `errorHandler.withErrorHandler`
+4. ✅ **Run linter** - Read the linter error message carefully; it tells you what's wrong
+
 ## Complete Examples for All Custom Action Types
 
 ### ActionCell Custom Actions
@@ -5161,9 +5494,44 @@ export const myCustomDataSource = async (collectionId: string, context: any) =>
 };
 ```
 
+### Actions Using Wix API Libraries (REQUIRES errorHandler)
+
+**Example 7: Action using Wix API libraries with `wix/` prefix (REQUIRES errorHandler)**
+```typescript
+import { errorHandler } from '@wix/essentials';
+import { data } from '@wix/data';
+import { stores } from '@wix/stores';
+import { CustomActionCellActionResolver } from '@wix/auto-patterns';
+
+export const syncWithWixData: CustomActionCellActionResolver = (params) => {
+  const { actionParams, sdk } = params;
+  const { item } = actionParams;
+
+  return {
+    label: 'Sync with Wix Data',
+    icon: <SyncIcon />,
+    onClick: () => {
+      // ✅ CORRECT: Wix API library calls wrapped with errorHandler
+      errorHandler.withErrorHandler(
+        async () => {
+          // Using @wix/data library
+          const dataResult = await data.query('MyCollection').eq('id', item.id).find();
+
+          // Using @wix/stores library
+          const productResult = await stores.queryProducts().eq('sku', item.sku).find();
+
+          return { dataResult, productResult };
+        },
+        {}
+      );
+    },
+  };
+};
+```
+
 ### Actions Using SDK Methods (NO errorHandler needed)
 
-**Example 7: Action using SDK methods (NO errorHandler needed)**
+**Example 8: Action using SDK methods (NO errorHandler needed)**
 ```typescript
 import { CustomActionCellActionResolver } from '@wix/auto-patterns';
 
@@ -5192,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).
+