@wix/auto-patterns 1.17.0 → 1.18.0

package/dist/docs/sdk_and_schema.md

@@ -1,215 +0,0 @@
-## 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.
-
----
-
-## SchemaConfig Usage
-
-SchemaConfig provides complete collection metadata and server actions. Essential for dynamic operations and accessing collection structure information.
-
-### 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
-  - Example: `schema.fields.name.type === 'TEXT'`
-
-• **actions** - Server operation functions
-  - Pre-configured API calls for CRUD operations
-  - Use with optimistic actions for best UX
-  - 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
-
-### 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
-
-### 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
-- **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`).