@wix/auto-patterns 1.17.0 → 1.18.0

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

@@ -147,7 +147,10 @@ export interface AppConfig {
           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'
+            entityTypeSource: 'cms' | 'custom'; // Data source type.
+            custom?: {
+              id: string;
+            };
             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'
@@ -434,6 +437,67 @@ type LayoutContent =
 
 ---
 
+## Filters Configuration Notes
+
+To configure filters in a `collectionPage`, add a `filters` property inside the page's component configuration object. Each filter must reference a valid field by its `fieldId`, and the supported types are:
+
+* `numberConfig`: used with fields of type `NUMBER`
+* `dateConfig`: used with fields of type `DATETIME`
+* `booleanConfig`: used with fields of type `BOOLEAN`
+* `enumConfig`: used with fields of type `ARRAY` or `ARRAY_STRING`
+
+### Enum Configuration Implementation
+
+When implementing enum filters, you must ask the user to provide the possible option values. Never invent or assume enum values. Here's how to properly handle enumConfig:
+
+#### Example: User-Provided Enum Implementation
+
+1. First, collect the possible values from the user:
+   ```
+   User requests: "I need a filter for pet types."
+   You ask: "What are the possible values for pet types that should be available in the filter?"
+   User responds: "dog, cat, bird, rabbit, fish"
+   ```
+
+2. Then, create the `enumConfig` structure:
+   ```json
+   "enumConfig": {
+     "options": [
+       { "value": "dog", "label": "Dog" },
+       { "value": "cat", "label": "Cat" },
+       { "value": "bird", "label": "Bird" },
+       { "value": "rabbit", "label": "Rabbit" },
+       { "value": "fish", "label": "Fish" }
+     ],
+     "selectionMode": "multiple",
+     "optionType": "checkbox"
+   }
+   ```
+
+Notice how the `label` is derived from the `value` by capitalizing the first letter. The user's exact values become the `value` property.
+
+### Grouping Filters with Section Title
+
+* Filters can be grouped by sections using the `sectionTitle` property.
+* If multiple filter items share the same `sectionTitle`, they will be displayed together in a grouped section in the UI.
+* Filters without a `sectionTitle` will appear in a default section or be displayed individually.
+* Grouping helps maintain clarity, especially when dealing with multiple filter options.
+
+### Key Guidelines
+
+* **openByDefault**: Automatically expands the filter accordion when the filters panel is opened.
+* **tagLabel**: Specifies the label displayed in a Tag component on the table or grid once the filter is active. For example, if the tagLabel is "Age", the filter display might show: `Age: 7`.
+* **maxInlineFilters**: Limits the number of filters shown inline in the table toolbar. Others are accessible via the panel. Default is 0.
+* **dateConfig.mode**:
+
+  * `ONLY_PREDEFINED`: user can select only from preset options
+  * `ONLY_CUSTOM`: user must select a custom date range manually (no presets)
+  * `COMBINE`: both options available
+* **dateConfig.presets** must be omitted if mode is `ONLY_CUSTOM`.
+* **dateConfig.includeTime**: Controls whether time selection is also enabled alongside date (default is `true`).
+
+---
+
 # Pages Configuration
 
 ## ⚠️ Critical Page Rules
@@ -580,7 +644,7 @@ Sticky columns allow you to keep specific columns visible while users scroll hor
 
 * Must include **exactly one item**.
 * Each component must have:
-  * `collection`: Collection configuration with `collectionId` and `entityTypeSource: 'cms'`
+  * `collection`: Collection configuration with `collectionId` and `entityTypeSource`
   * `layout`: Array of layout items that determine what components to render
 
 ## Layout Array
@@ -1073,6 +1137,87 @@ interface ToastConfig {
 
 SchemaConfig provides complete collection metadata and server actions. Essential for dynamic operations and accessing collection structure information.
 
+### TypeScript Interface Definition
+
+```typescript
+export interface SchemaConfig {
+  id: string;
+  fields: Record<string, Field | undefined>;
+  displayField: string;
+  idField: string;
+  actions: {
+    get: (entityId: string) => Promise<any>;
+    create: (newEntity: Partial<any>) => Promise<any>;
+    update: (updatedEntity: any) => Promise<any>;
+    delete: (entityId: string) => Promise<any>;
+    bulkDelete: (entityIds: string[]) => Promise<any>;
+    find: (
+      query: Query,
+      options?: {
+        searchableFieldIds?: string[];
+        filterFieldMapping?: Record<string, { fieldId: string }>;
+      },
+    ) => Promise<{ items: any[]; total: number }>;
+  };
+}
+
+export interface Query {
+  limit: number;                    // Maximum number of items to return per request (controls page size)
+  offset: number;                   // Number of items to skip from the beginning (for pagination)
+  page: number;                     // Current page number (1-based, works with limit for pagination)
+  search?: string;                  // Text search query applied to searchable fields
+  cursor?: string | null;           // Cursor-based pagination token (alternative to offset-based pagination)
+  filters: Record<string, any>;     // Field-specific filter conditions (keys = field IDs, values = filter criteria)
+  sort?: {                          // Sorting configuration for result ordering
+    fieldName: string;              // Field ID to sort by (must be sortable per field capabilities)
+    order: 'asc' | 'desc';         // Sort direction
+  }[];
+}
+```
+
+### Supporting Type Definitions
+
+```typescript
+export type PatternsFieldType =
+  | 'SHORT_TEXT'
+  | 'LONG_TEXT'
+  | 'NUMBER'
+  | 'BOOLEAN'
+  | 'DATE'
+  | 'DATETIME'
+  | 'URL'
+  | 'ARRAY'
+  | 'REFERENCE'
+  | 'IMAGE';
+
+interface BaseField {
+  id: string;
+  displayName: string;
+  validation?: {
+    numberRange?: NumberRange;
+    stringLengthRange?: StringLengthRange;
+    required: boolean;
+  };
+  capabilities: {
+    supportedQueryOperators: QueryOperator[];
+    sortable: boolean;
+  };
+}
+
+export interface ReferenceField extends BaseField {
+  type: 'REFERENCE';
+  referenceMetadata: {
+    referencedCollectionId: string;
+  };
+}
+
+export interface NonReferenceField extends BaseField {
+  type: Exclude<PatternsFieldType, 'REFERENCE'>;
+}
+
+export type Field = ReferenceField | NonReferenceField;
+```
+
 ### Key Properties
 
 • **id** - `string`
@@ -1092,20 +1237,53 @@ SchemaConfig provides complete collection metadata and server actions. Essential
 • **fields** - `Record<string, Field | undefined>`
   - Complete field definitions with types and metadata
   - Useful for dynamic form generation or validation
-  - Example: `schema.fields.name.type === 'TEXT'`
+  - Each field contains type information, validation rules, and capabilities
+  - Example: `schema.fields.name.type === 'SHORT_TEXT'`
 
 • **actions** - Server operation functions
   - Pre-configured API calls for CRUD operations
   - Use with optimistic actions for best UX
+  - All actions return Promises and handle server communication
   - Example: `await schema.actions.update(item)`
 
 ### Available Schema Actions
 
-- schema.actions.create(item)        // Create single item
-- schema.actions.update(item)        // Update single item
-- schema.actions.delete(itemId)      // Delete by ID
-- schema.actions.bulkUpdate(updates) // Update multiple items
-- schema.actions.bulkDelete(itemIds) // Delete multiple items
+#### Individual Entity Operations
+- **schema.actions.get(entityId)** - Retrieve a single entity by ID
+- **schema.actions.create(newEntity)** - Create a new entity
+- **schema.actions.update(updatedEntity)** - Update an existing entity
+- **schema.actions.delete(entityId)** - Delete a single entity by ID
+
+#### Bulk Operations
+- **schema.actions.bulkDelete(entityIds)** - Delete multiple entities by their IDs
+
+#### Query Operations
+- **schema.actions.find(query, options)** - Search and filter entities
+  - `query`: Query object with pagination, filtering, sorting, and search criteria (see Query Interface section)
+  - `options.searchableFieldIds`: Array of field IDs that support text search
+  - `options.filterFieldMapping`: Maps filter IDs to actual field IDs for complex filtering
+  - Returns: `{ items: any[], total: number }`
+
+### Field Type Information
+
+Each field in the `fields` record contains:
+
+- **id**: Unique field identifier
+- **displayName**: Human-readable field name
+- **type**: One of the supported `PatternsFieldType` values
+- **validation**: Optional validation rules including:
+  - `numberRange`: Min/max values for numeric fields
+  - `stringLengthRange`: Min/max length for text fields
+  - `required`: Whether the field is mandatory
+- **capabilities**: Field behavior configuration:
+  - `supportedQueryOperators`: Array of operators this field supports for filtering
+  - `sortable`: Whether this field can be used for sorting
+
+### Reference Fields
+
+Reference fields have additional metadata:
+- **referenceMetadata.referencedCollectionId**: ID of the collection being referenced
+- Used for establishing relationships between different collections
 
 ### Schema Validation Checklist
 
@@ -1116,74 +1294,19 @@ Before using schema in operations:
 ✓ Use `schema.idField` for ID operations
 ✓ Use `schema.displayField` for UI display
 ✓ Use `schema.actions` for server operations
+✓ Check field capabilities before applying filters or sorting
 
 ### Common Usage Patterns
 
 - **ActionCell**: Use `schema.actions.update()` or `schema.actions.delete()` for single item operations
-- **BulkActions**: Use `schema.actions.bulkUpdate()` or `schema.actions.bulkDelete()` for multiple items
+- **BulkActions**: Use `schema.actions.bulkDelete()` for multiple items
 - **Dynamic UI**: Use `schema.fields` to build forms or validate data
 - **Error Messages**: Use `schema.displayField` to create meaningful user feedback
-
----
-
-## Filters Configuration Notes
-
-To configure filters in a `collectionPage`, add a `filters` property inside the page's component configuration object. Each filter must reference a valid field by its `fieldId`, and the supported types are:
-
-* `numberConfig`: used with fields of type `NUMBER`
-* `dateConfig`: used with fields of type `DATETIME`
-* `booleanConfig`: used with fields of type `BOOLEAN`
-* `enumConfig`: used with fields of type `ARRAY` or `ARRAY_STRING`
-
-### Enum Configuration Implementation
-
-When implementing enum filters, you must ask the user to provide the possible option values. Never invent or assume enum values. Here's how to properly handle enumConfig:
-
-#### Example: User-Provided Enum Implementation
-
-1. First, collect the possible values from the user:
-   ```
-   User requests: "I need a filter for pet types."
-   You ask: "What are the possible values for pet types that should be available in the filter?"
-   User responds: "dog, cat, bird, rabbit, fish"
-   ```
-
-2. Then, create the `enumConfig` structure:
-   ```json
-   "enumConfig": {
-     "options": [
-       { "value": "dog", "label": "Dog" },
-       { "value": "cat", "label": "Cat" },
-       { "value": "bird", "label": "Bird" },
-       { "value": "rabbit", "label": "Rabbit" },
-       { "value": "fish", "label": "Fish" }
-     ],
-     "selectionMode": "multiple",
-     "optionType": "checkbox"
-   }
-   ```
-
-Notice how the `label` is derived from the `value` by capitalizing the first letter. The user's exact values become the `value` property.
-
-### Grouping Filters with Section Title
-
-* Filters can be grouped by sections using the `sectionTitle` property.
-* If multiple filter items share the same `sectionTitle`, they will be displayed together in a grouped section in the UI.
-* Filters without a `sectionTitle` will appear in a default section or be displayed individually.
-* Grouping helps maintain clarity, especially when dealing with multiple filter options.
-
-### Key Guidelines
-
-* **openByDefault**: Automatically expands the filter accordion when the filters panel is opened.
-* **tagLabel**: Specifies the label displayed in a Tag component on the table or grid once the filter is active. For example, if the tagLabel is "Age", the filter display might show: `Age: 7`.
-* **maxInlineFilters**: Limits the number of filters shown inline in the table toolbar. Others are accessible via the panel. Default is 0.
-* **dateConfig.mode**:
-
-  * `ONLY_PREDEFINED`: user can select only from preset options
-  * `ONLY_CUSTOM`: user must select a custom date range manually (no presets)
-  * `COMBINE`: both options available
-* **dateConfig.presets** must be omitted if mode is `ONLY_CUSTOM`.
-* **dateConfig.includeTime**: Controls whether time selection is also enabled alongside date (default is `true`).
+- **Field Validation**: Use `schema.fields[fieldId].validation` for form validation rules
+- **Query Building**: Use `schema.fields[fieldId].capabilities.supportedQueryOperators` to build dynamic filters
+- **Data Fetching**: Use `schema.actions.find()` with Query interface for complex data retrieval with pagination, search, and filtering
+- **Pagination**: Combine `limit`, `offset`, and `page` properties in Query for consistent pagination behavior
+- **Search Implementation**: Use `search` property with `searchableFieldIds` option for full-text search across multiple fields
 
 ---
 
@@ -1191,7 +1314,7 @@ Notice how the `label` is derived from the `value` by capitalizing the first let
 
 The ActionCell feature adds an interactive action column to collection tables or grid views, enabling users to perform operations on individual entities.
 
-### Placement and Structure
+## Placement and Structure
 
 The ActionCell has a two-level structure:
 * `primaryAction`: A single prominent action shown directly in the table/grid row
@@ -1427,7 +1550,7 @@ AI agents should verify these requirements before generating ActionCell configur
 
 The Bulk Action Toolbar feature enables users to perform operations on multiple selected entities simultaneously in collection tables or grids. When configured, it adds checkboxes to each row and displays a toolbar with bulk actions when items are selected.
 
-### Placement and Structure
+## Placement and Structure
 
 The Bulk Action Toolbar is configured within the table / grid / table-grid switch configuration using the `bulkActionToolbar` property. It has a two-level structure:
 * `primaryActions`: Actions shown directly in the bulk action toolbar
@@ -1982,10 +2105,13 @@ your-page/
     │   ├── index.tsx
     │   ├── name.ts
     │   └── date.ts
-    └── customComponents/              // Custom entity page components
+    ├── customComponents/              // Custom entity page components
+    │   ├── index.tsx
+    │   ├── CustomNameField.tsx
+    │   └── InfoCard.tsx
+    └── customDataSources/             // Custom data sources
         ├── index.tsx
-        ├── CustomNameField.tsx
-        └── InfoCard.tsx
+        └── myCustomDataSource.ts
 ```
 
 ### Importing Overrides in Your Page
@@ -1997,8 +2123,9 @@ import * as modals from './components/modals';
 import * as actions from './components/actions';
 import * as columns from './components/columns';
 import * as components from './components/customComponents';
+import * as customDataSources from './components/customDataSources';
 
-<PatternsWizardOverridesProvider value={{ modals, actions, columns, components }}>
+<PatternsWizardOverridesProvider value={{ modals, actions, columns, components, customDataSources }}>
   <AutoPatternsApp configuration={config as AppConfig} />
 </PatternsWizardOverridesProvider>
 ```
@@ -2012,6 +2139,7 @@ For example:
 - Adding a new modal → Update `./components/modals/index.tsx`
 - Adding a new column override → Update `./components/columns/index.tsx`
 - Adding a new custom component → Update `./components/customComponents/index.tsx`
+- Adding a new custom data source → Update `./components/customDataSources/index.tsx`
 
 Without updating the index files, your implementations won't be available to the `PatternsWizardOverridesProvider`.
 
@@ -2464,4 +2592,158 @@ PatternsWizardOverridesProvider
 
 By using these component overrides, you can tailor the behavior and appearance of your `AutoPatternsApp` to meet specific requirements beyond what the default rendering provides.
 
+## Custom Data Sources
+
+Custom data sources allow you to connect AutoPatternsApp to any data source beyond the default CMS collections. This enables you to integrate with external APIs, custom databases, or any other data sources that require custom implementation.
+
+### Configuration Structure
+
+When implementing a custom data source, you need to modify the `collection` configuration in your AppConfig:
+
+```json
+{
+  "collection": {
+    "collectionId": "myCustomCollection",
+    "entityTypeSource": "custom",
+    "custom": {
+      "id": "myCustomDataSource"
+    }
+  }
+}
+```
+
+**Key Properties:**
+- `entityTypeSource`: Must be set to `"custom"` instead of `"cms"`
+- `custom.id`: A unique identifier for your custom data source implementation
+
+### Custom Data Source Override Structure
+
+Custom data sources are implemented through the `customDataSources` property in your `PatternsWizardOverridesProvider`:
+
+```tsx
+<PatternsWizardOverridesProvider value={{
+  customDataSources: {
+    myCustomDataSource: async (collectionId: string, context: any) => {
+      return customSchemaConfig; // Must return a SchemaConfig object
+    }
+  }
+}}>
+  <AutoPatternsApp configuration={config as AppConfig} />
+</PatternsWizardOverridesProvider>
+```
+
+### Implementation Components
+
+#### Custom Data Source Function
+
+You must implement a custom data source function that:
+- Takes `collectionId` and `context` parameters
+- Returns a Promise that resolves to a `SchemaConfig` object
+- The `SchemaConfig` object must include:
+  - **id**: Collection identifier
+  - **fields**: Field definitions with types and metadata
+  - **displayField**: Primary field for displaying items
+  - **idField**: Primary key field name
+  - **actions**: CRUD operation functions that handle:
+    - Individual entity operations (get, create, update, delete)
+    - Bulk operations (bulkDelete)
+    - Query operations with pagination, search, filtering, and sorting
+
+### Example Implementation Structure
+
+```tsx
+// customDataSources/myCustomDataSource.ts
+export const myCustomDataSource = async (collectionId: string, context: any) => {
+  return {
+    id: 'myCustomCollection',
+    fields: {
+      // Field definitions based on your data source schema
+    },
+    displayField: 'name',
+    idField: '_id',
+    actions: {
+      get: async (entityId: string) => { /* Implementation */ },
+      create: async (newEntity: any) => { /* Implementation */ },
+      update: async (updatedEntity: any) => { /* Implementation */ },
+      delete: async (entityId: string) => { /* Implementation */ },
+      bulkDelete: async (entityIds: string[]) => { /* Implementation */ },
+      find: async (query: Query, options?: any) => { /* Implementation */ }
+    }
+  };
+};
+```
+
+### Field Type Mapping
+
+When implementing custom data sources, you need to map your data source field types to AutoPatterns field types:
+
+- **Text fields** → `'SHORT_TEXT'` or `'LONG_TEXT'`
+- **Numeric fields** → `'NUMBER'`
+- **Boolean fields** → `'BOOLEAN'`
+- **Date fields** → `'DATE'` or `'DATETIME'`
+- **Image fields** → `'IMAGE'`
+- **Array fields** → `'ARRAY'`
+- **Reference fields** → `'REFERENCE'`
+- **URL fields** → `'URL'`
+
+### Error Handling
+
+Custom data sources should include proper error handling:
+
+```tsx
+actions: {
+  get: async (entityId: string) => {
+    try {
+      const result = await yourDataSourceCall(entityId);
+      return result;
+    } catch (error) {
+      throw new Error(`Failed to fetch entity: ${error.message}`);
+    }
+  }
+}
+```
+
+### Validation Requirements
+
+- **Function Signature**: Custom data source must be a function with signature `(collectionId: string, context: any) => Promise<SchemaConfig>`
+- **Return Type**: Must return a Promise that resolves to a complete SchemaConfig object
+- All schema actions must return Promises
+- Field IDs must match between schema definition and data source responses
+- The `find` action must support the complete Query interface
+- Custom data sources must handle pagination, search, and filtering
+- Error responses should be meaningful and actionable
+
+### Folder Structure for Custom Data Sources
+
+```
+your-page/
+├── page.tsx                           // Your main page component
+├── MyCollectionConfig.patterns.json   // Configuration file
+└── components/                        // Page-specific components folder
+    ├── index.tsx                       // Exports all overrides for easy importing
+    ├── customDataSources/             // Custom data sources
+    │   ├── index.tsx
+    │   └── myCustomDataSource.ts
+    ├── actions/                       // Custom actions
+    │   ├── index.tsx
+    │   └── myCustomAction.tsx
+    └── columns/                       // Column overrides
+        ├── index.tsx
+        └── myColumn.tsx
+```
+
+### Registering Custom Data Sources
+
+In your page component, import and register your custom data sources:
+
+```tsx
+import * as customDataSources from './components/customDataSources';
+
+<PatternsWizardOverridesProvider value={{ customDataSources }}>
+  <AutoPatternsApp configuration={config as AppConfig} />
+</PatternsWizardOverridesProvider>
+```
+
+**Important:** Every time you create a new custom data source, you must add a corresponding export line to the `./components/customDataSources/index.tsx` file. For example, if you create `myDataSource.ts`, you must add `export * from './myDataSource';` to the index file.
+
 ---

package/dist/docs/bulk_actions.md

@@ -2,7 +2,7 @@
 
 The Bulk Action Toolbar feature enables users to perform operations on multiple selected entities simultaneously in collection tables or grids. When configured, it adds checkboxes to each row and displays a toolbar with bulk actions when items are selected.
 
-### Placement and Structure
+## Placement and Structure
 
 The Bulk Action Toolbar is configured within the table / grid / table-grid switch configuration using the `bulkActionToolbar` property. It has a two-level structure:
 * `primaryActions`: Actions shown directly in the bulk action toolbar

package/dist/docs/collection_page.md

@@ -12,7 +12,7 @@
 
 * Must include **exactly one item**.
 * Each component must have:
-  * `collection`: Collection configuration with `collectionId` and `entityTypeSource: 'cms'`
+  * `collection`: Collection configuration with `collectionId` and `entityTypeSource`
   * `layout`: Array of layout items that determine what components to render
 
 ## Layout Array