@wix/auto-patterns 1.41.0 → 1.43.0

package/mcp-docs/views.md

@@ -0,0 +1,335 @@
+# 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/auto-patterns",
-  "version": "1.41.0",
+  "version": "1.43.0",
   "license": "UNLICENSED",
   "author": {
     "name": "Matvey Oklander",
@@ -35,6 +35,12 @@
       "require": "./dist/cjs/exports/testkit/puppeteer.js",
       "import": "./dist/esm/exports/testkit/puppeteer.js",
       "types": "./dist/types/exports/testkit/puppeteer.d.ts"
+    },
+    "./mcp-docs/auto-patterns-guide.md": {
+      "default": "./mcp-docs/auto-patterns-guide.md"
+    },
+    "./mcp-docs/wix_fqdn_custom_data_source.md": {
+      "default": "./mcp-docs/wix_fqdn_custom_data_source.md"
     }
   },
   "files": [
@@ -63,7 +69,7 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.28.4",
-    "@wix/data": "^1.0.316",
+    "@wix/data": "^1.0.323",
     "@wix/wix-ui-icons-common": "^3.100.0",
     "@wix/wix-ui-test-utils": "^1.3.3",
     "lodash": "^4.17.21"
@@ -79,22 +85,22 @@
     "@types/node": "^16.18.126",
     "@types/node-fetch": "^2.6.13",
     "@types/react": "^16.14.67",
-    "@wix/crm": "^1.0.1117",
+    "@wix/crm": "^1.0.1175",
     "@wix/design-system": "^1.223.0",
-    "@wix/eslint-config-yoshi": "^6.161.0",
+    "@wix/eslint-config-yoshi": "^6.162.0",
     "@wix/fe-essentials-standalone": "^1.1380.0",
-    "@wix/jest-yoshi-preset": "^6.161.0",
-    "@wix/patterns": "^1.294.0",
-    "@wix/sdk": "^1.17.1",
+    "@wix/jest-yoshi-preset": "^6.162.0",
+    "@wix/patterns": "^1.299.0",
+    "@wix/sdk": "^1.17.2",
     "@wix/sdk-testkit": ">=0.1.9",
-    "@wix/wix-data-items-common": "^1.0.255",
-    "@wix/wix-data-items-sdk": "^1.0.450",
-    "@wix/yoshi-flow-library": "^6.161.0",
-    "@wix/yoshi-style-dependencies": "^6.161.0",
+    "@wix/wix-data-items-common": "^1.0.264",
+    "@wix/wix-data-items-sdk": "^1.0.460",
+    "@wix/yoshi-flow-library": "^6.162.0",
+    "@wix/yoshi-style-dependencies": "^6.162.0",
     "chance": "^1.1.13",
     "date-fns": "^2.30.0",
     "express": "^4.21.2",
-    "fetch-mock": "^12.5.5",
+    "fetch-mock": "^12.6.0",
     "jest": "^27.5.1",
     "node-fetch": "^2.7.0",
     "react": "16.14.0",
@@ -106,7 +112,7 @@
     "@wix/design-system": "^1.204.0",
     "@wix/essentials": "^0.1.26",
     "@wix/patterns": "^1.254.0",
-    "react": "^16.8.0",
+    "react": "^16.8.0 || ^18.0.0",
     "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "jest": {
@@ -153,5 +159,5 @@
   "wallaby": {
     "autoDetect": true
   },
-  "falconPackageHash": "22d551f0337bd0d5e5de5a5cb32af3a84c6f8c8e1139cb9d4dbcd3f1"
+  "falconPackageHash": "a978db4a0bda96b3424d12b714abc59c92db2bef425e42fa25136858"
 }