@wix/auto-patterns 1.17.0 → 1.18.0

package/dist/docs/config_schema.md

@@ -0,0 +1,184 @@
+## SchemaConfig Usage
+
+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: ComputedQuery<any>,
+      options?: {
+        searchableFieldIds?: string[];
+        filterFieldMapping?: Record<string, { fieldId: string }>;
+      },
+    ) => Promise<{ items: any[]; total: number }>;
+  };
+}
+```
+
+### 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`
+  - Collection identifier (e.g., "WixPets")
+  - Example: `schema.id === "WixPets"`
+
+• **idField** - `string`
+  - Primary key field name (usually "_id")
+  - Required for all update/delete operations
+  - Example: `const id = item[schema.idField]`
+
+• **displayField** - `string`
+  - Main field for displaying items (name, title, etc.)
+  - Used in UI components for item identification
+  - Example: `const label = item[schema.displayField]`
+
+• **fields** - `Record<string, Field | undefined>`
+  - Complete field definitions with types and metadata
+  - Useful for dynamic form generation or validation
+  - 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
+
+#### 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`: ComputedQuery object with filtering and sorting criteria
+  - `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
+
+Before using schema in operations:
+
+✓ Check if schema exists: `if (!schema) return;`
+✓ Verify required fields exist on items
+✓ 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.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
+- **Field Validation**: Use `schema.fields[fieldId].validation` for form validation rules
+- **Query Building**: Use `schema.fields[fieldId].capabilities.supportedQueryOperators` to build dynamic filters
+
+### Example Usage
+
+```typescript
+// Using schema for dynamic operations
+const handleUpdateEntity = async (updatedItem: any) => {
+  const schema = sdk.getSchema(collectionId);
+
+  if (!schema) {
+    throw new Error('Schema not available');
+  }
+
+  // Validate required fields
+  const nameField = schema.fields.name;
+  if (nameField?.validation?.required && !updatedItem.name) {
+    throw new Error(`${nameField.displayName} is required`);
+  }
+
+  // Perform update
+  await schema.actions.update(updatedItem);
+
+  // Show success message using display field
+  const displayValue = updatedItem[schema.displayField];
+  console.log(`Updated ${displayValue} successfully`);
+};
+```

package/dist/docs/custom_overrides.md

@@ -28,10 +28,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
@@ -43,8 +46,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>
 ```
@@ -58,6 +62,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`.
 
@@ -509,3 +514,157 @@ 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/index.md

@@ -30,10 +30,6 @@ This index maps user requests to the appropriate section IDs for fetching releva
 **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
 
-### ID: `sdk_and_schema`
-**Topics**: SDK utilities, optimistic actions, schema usage, filters, server operations
-**Keywords**: SDK utilities, programmatic operations, optimistic actions, immediate UI updates, schema access, collection metadata, server operations, data manipulation, filters configuration, error handling, toast notifications
-
 ### ID: `action_cell`
 **Topics**: Row-level actions, update/delete actions, custom row actions, action cell configuration
 **Keywords**: row actions, item-level operations, edit, delete, actionCell, row-level operations, update actions, delete confirmations, custom row actions, inline actions, secondary actions
@@ -58,15 +54,17 @@ This index maps user requests to the appropriate section IDs for fetching releva
 **Topics**: Customization, overrides, custom components, column customization, folder structure
 **Keywords**: customization, custom functionality, overrides, extending functionality, custom components, custom rendering, column overrides, folder structure, organization, row data access
 
+### ID: `wix_fqdn_custom_data_source`
+**Topics**: FQDN-based custom data sources, Wix Business API integration, schema mapping, custom data source implementation
+**Keywords**: FQDN, Wix Business API, custom data source, schema mapping, client library, field type mapping, custom implementation, entityTypeSource custom, Business API integration, schema extraction
+
 ---
 
 ## Recipe Section IDs (Step-by-Step Guides)
 
 | Recipe Topic | Section ID | Use Case |
 |--------------|------------|----------|
-| 🚀 First Dashboard | `recipe-first-dashboard` | Complete setup from scratch |
-| ⚡ CRUD Operations | `recipe-crud-operations` | Add Create/Edit/Delete functionality |
-| 📦 Bulk Operations | `recipe-bulk-operations` | Multi-select and bulk actions |
+| 🚀 First Dashboard | `recipe-first-dashboard` | Complete setup from scratch, replacing existing pages with dashboard pages, creating new dashboard pages, setting up collection management interfaces, building admin panels, or implementing any data-driven dashboard interface |
 | 🎨 Complete Customization | `recipe-customization` | Basic to advanced customization and integrations |
 
 ## LLM Usage Instructions

package/dist/docs/schema_config.md

@@ -0,0 +1,174 @@
+## SchemaConfig Usage
+
+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`
+  - Collection identifier (e.g., "WixPets")
+  - Example: `schema.id === "WixPets"`
+
+• **idField** - `string`
+  - Primary key field name (usually "_id")
+  - Required for all update/delete operations
+  - Example: `const id = item[schema.idField]`
+
+• **displayField** - `string`
+  - Main field for displaying items (name, title, etc.)
+  - Used in UI components for item identification
+  - Example: `const label = item[schema.displayField]`
+
+• **fields** - `Record<string, Field | undefined>`
+  - Complete field definitions with types and metadata
+  - Useful for dynamic form generation or validation
+  - 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
+
+#### 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
+
+Before using schema in operations:
+
+✓ Check if schema exists: `if (!schema) return;`
+✓ Verify required fields exist on items
+✓ 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.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
+- **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

package/dist/docs/sdk_utilities.md

@@ -0,0 +1,97 @@
+## SDK Utilities
+
+The `sdk` parameter provides access to Auto Patterns utilities and context. Available in custom actions across all action types (ActionCell, BulkActions, CollectionPage actions, and EntityPage Actions).
+
+### Key SDK Utilities
+The only functions exist in sdk are:
+
+• **closeModal** - `closeModal(): void`
+  - Closes the currently open modal
+  - Example: `sdk.closeModal()` after saving or canceling
+
+• **getOptimisticActions** - `getOptimisticActions(collectionId): OptimisticActions`
+  - Provides optimistic UI updates for immediate user feedback
+  - Supports create, update, delete operations with automatic rollback on failure
+  - Example: `sdk.getOptimisticActions(sdk.collectionId).updateOne(item, { ... })`
+
+• **getSchema** - `getSchema(collectionId): SchemaConfig | undefined`
+  - Access to collection schema information (fields, types, validation)
+  - Useful for dynamic operations based on collection structure
+  - Example: `const schema = sdk.getSchema(sdk.collectionId)`
+
+• **collectionId** - `string`
+  - Current collection context identifier
+  - Available in all action contexts for referencing the active collection
+  - Example: `sdk.collectionId` to get the current collection ID
+
+---
+
+## OptimisticActions
+
+Provides immediate UI updates with automatic server synchronization and error recovery.
+
+### Usage Rules
+
+**Use OptimisticActions for:**
+- Data modification operations (create, update, delete)
+- Operations requiring immediate visual feedback
+
+**Do NOT use for:**
+- Read-only operations
+- Operations requiring server confirmation first
+
+### Core Pattern
+
+```typescript
+// Get instances from SDK (see SDK Utilities section)
+const optimisticActions = sdk.getOptimisticActions(sdk.collectionId);
+const schema = sdk.getSchema(sdk.collectionId);
+
+optimisticActions.operation(items, {
+  submit: async (items) => schema.actions.serverMethod(items),
+  successToast: 'Success message',
+  errorToast: (err, {retry}) => ({ text: 'Error message', action: { text: 'Retry', onClick: retry }})
+});
+```
+
+### Available Operations
+
+#### Create Operations
+- `createOne(item: T, params: OptimisticParams<T>): void`
+- `createMany(items: T[], params: OptimisticParams<T>): void`
+
+#### Update Operations
+- `updateOne(item: T, params: OptimisticParams<T>): void`
+- `updateMany(items: T[], params: OptimisticParams<T>): void`
+- `updateAll(transformFn: (item: T) => Partial<T>, params: OptimisticParams<T>): void`
+
+#### Delete Operations
+- `deleteOne(item: T, params: OptimisticParams<T> & { showUndoToast: true }): void`
+- `deleteMany(items: T[], params: OptimisticParams<T> & { showUndoToast: true }): void`
+- `deleteAll(params: OptimisticParams<T> & { showUndoToast: true }): void`
+
+### Type Definitions
+
+```typescript
+interface OptimisticParams<T> {
+  submit: (items: T[]) => Promise<any>;
+  successToast: string | ToastConfig;
+  errorToast: (error: Error, actions: { retry: () => void }) => ToastConfig | string;
+  showUndoToast?: boolean; // Required: true for delete operations
+}
+
+interface ToastConfig {
+  text: string;
+  action?: { text: string; onClick: () => void };
+}
+```
+
+### Validation Requirements
+
+**Before using optimistic actions:**
+- Verify `sdk.getOptimisticActions(collectionId)` returns valid instance
+- Verify `sdk.getSchema(collectionId)` returns valid schema
+- For delete operations: `showUndoToast: true` is mandatory
+- All `submit` functions must return a Promise
+
+**SDK Parameter:** Available in custom actions and modals. See SDK Utilities section for complete interface.