@wix/auto-patterns 1.44.0 → 1.46.0

package/mcp-docs/settings_page.md

@@ -0,0 +1,599 @@
+# Settings Page Configuration
+
+## Overview
+
+The Settings Page is a dedicated page type for managing application settings and preferences. It provides a form-based interface with automatic save/cancel functionality, validation, and a flexible card-based layout system. The Settings Page uses the same custom data source pattern as Collection Pages for consistency across the framework.
+
+## Key Features
+
+- **Custom Data Source Pattern**: Uses SchemaConfig with standard CRUD actions (same as Collection Pages)
+- **Form-based Interface**: Built-in form state management with `@wix/patterns/form`
+- **Auto Save/Cancel**: Automatic save and cancel button handling
+- **Validation Support**: Field validation with focus on invalid fields
+- **Flexible Layout**: Card-based layout with main content and optional sidebar
+- **Header Configuration**: Title, subtitle, and more actions support
+
+## Page Type
+
+Set `type: 'settingsPage'` in your page configuration:
+
+```json
+{
+  "id": "settings",
+  "type": "settingsPage",
+  "appMainPage": true,
+  "settingsPage": {
+    "entityTypeSource": "custom",
+    "custom": {
+      "id": "app-settings"
+    }
+  }
+}
+```
+
+## Settings Page Configuration
+
+### Required Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `route.path` | `string` | Route path for the settings page (e.g., `/settings`) |
+| `entityTypeSource` | `'custom'` | Must be `'custom'` - settings pages use custom data sources |
+| `custom.id` | `string` | ID matching the custom data source identifier |
+
+### Optional Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `title` | `object` | Page title configuration |
+| `subtitle` | `object` | Page subtitle with optional learn more link |
+| `actions.moreActions` | `MoreActionsType` | Additional actions menu (export, import, reset, etc.) |
+| `layout` | `object` | Card layout for main and sidebar content |
+
+## Custom Data Source
+
+The settings page requires a custom data source that provides the schema and CRUD actions. This follows the same pattern as Collection Pages. See the [Complete Configuration Example](#complete-configuration-example) section for a full implementation.
+
+### Registering the Data Source
+
+Create a hook to register your custom data source:
+
+```typescript
+// useCustomDataSources.tsx
+import { appSettingsDataSource } from './appSettingsDataSource';
+
+export const useCustomDataSources = () => {
+  return {
+    'app-settings': appSettingsDataSource,
+  };
+};
+```
+
+### Supported Field Types
+
+- `SHORT_TEXT` - Single-line text input
+- `LONG_TEXT` - Multi-line text area
+- `BOOLEAN` - Toggle/checkbox
+- `NUMBER` - Numeric input
+- `URL` - URL input with validation
+- `DATE` - Date picker
+- `DATETIME` - Date and time picker
+
+## Actions Configuration
+
+### More Actions (Custom Actions)
+
+Define custom actions in the `actions.moreActions` array. See the [Complete Configuration Example](#complete-configuration-example) for the full configuration.
+
+### Custom Action Resolvers
+
+Create action resolvers using `CustomFormPageActionResolver`:
+
+```tsx
+// actions/exportSettings.tsx
+import React from 'react';
+import { CustomFormPageActionResolver } from '@wix/auto-patterns';
+import { Download } from '@wix/wix-ui-icons-common';
+
+export const exportSettings: CustomFormPageActionResolver = (params) => {
+  // params.form provides access to form state if needed
+  return {
+    label: 'Export settings',
+    icon: <Download />,
+    onClick: () => {
+      // Export logic here
+      console.log('Exporting settings');
+    },
+    biName: 'export-settings-action',
+  };
+};
+```
+
+```tsx
+// actions/importSettings.tsx
+import React from 'react';
+import { CustomFormPageActionResolver } from '@wix/auto-patterns';
+import { Upload } from '@wix/wix-ui-icons-common';
+
+export const importSettings: CustomFormPageActionResolver = () => {
+  return {
+    label: 'Import settings',
+    icon: <Upload />,
+    onClick: () => console.log('Importing settings'),
+    biName: 'import-settings-action',
+  };
+};
+```
+
+```tsx
+// actions/resetSettings.tsx
+import React from 'react';
+import { CustomFormPageActionResolver } from '@wix/auto-patterns';
+import { Undo } from '@wix/wix-ui-icons-common';
+
+export const resetSettings: CustomFormPageActionResolver = () => {
+  return {
+    label: 'Reset settings',
+    icon: <Undo />,
+    onClick: () => console.log('Resetting to defaults'),
+    biName: 'reset-settings-action',
+  };
+};
+```
+
+### Registering Actions
+
+Create a hook to register your custom actions:
+
+```typescript
+// useActions.tsx
+import { exportSettings, importSettings, resetSettings } from './actions';
+
+export const useActions = () => {
+  return {
+    exportSettings,
+    importSettings,
+    resetSettings,
+  };
+};
+```
+
+## Header Configuration
+
+The header supports `title` and `subtitle` with optional `learnMore` link. See the [Complete Configuration Example](#complete-configuration-example) for usage.
+
+## Layout Configuration
+
+The settings page uses a card-based layout with main content and optional sidebar areas.
+
+### Layout Structure
+
+```typescript
+layout: {
+  main: CardLayout[];      // Main content area (required)
+  sidebar?: CardLayout[];  // Sidebar area (optional)
+}
+```
+
+### Card Layout
+
+Each card in the layout has the following structure:
+
+```typescript
+{
+  type: 'card',
+  card: {
+    title: { text: 'Card Title' },
+    subtitle?: { text: 'Optional subtitle' },
+    children: LayoutContent[]
+  }
+}
+```
+
+### Layout Content Types
+
+#### 1. Field Content
+
+Renders a form field from the data source schema:
+
+```typescript
+{
+  type: 'field',
+  field: {
+    fieldId: 'name',  // Must match a field ID from the data source schema
+    span?: 6          // Grid columns (1-12), default is 12
+  }
+}
+```
+
+#### 2. Container Content
+
+Groups related content items:
+
+```typescript
+{
+  type: 'container',
+  container: {
+    span?: 12,           // Grid columns (1-12)
+    children: [          // Nested layout content
+      { type: 'field', field: { fieldId: 'field1', span: 4 } },
+      { type: 'field', field: { fieldId: 'field2', span: 4 } },
+      { type: 'field', field: { fieldId: 'field3', span: 4 } }
+    ]
+  }
+}
+```
+
+#### 3. Component Content
+
+Renders a custom component via overrides:
+
+```typescript
+{
+  type: 'component',
+  component: {
+    componentId: 'myCustomComponent',  // Matches override key
+    span?: 12                           // Grid columns (1-12)
+  }
+}
+```
+
+### Grid System
+
+- **12-Column Grid**: The layout uses a 12-column grid system
+- The `span` property controls how many columns an item occupies (1-12)
+- When items in a row exceed 12 columns total, the next item wraps to a new line
+
+## Complete Configuration Example
+
+### App Config (settingPageConfig.patterns.ts)
+
+```typescript
+import type { AppConfig } from '@wix/auto-patterns';
+
+export const appConfig: AppConfig = {
+  pages: [
+    {
+      id: 'settings',
+      type: 'settingsPage',
+      appMainPage: true,
+      settingsPage: {
+        route: {
+          path: '/settings',
+        },
+        entityTypeSource: 'custom',
+        custom: {
+          id: 'app-settings',
+        },
+
+        // Header
+        title: {
+          text: 'App Settings',
+        },
+        subtitle: {
+          text: 'Configure your application preferences and defaults',
+          learnMore: {
+            url: 'https://support.wix.com/en/article/wix-apps',
+            label: 'Learn more',
+          },
+        },
+
+        // Custom actions
+        actions: {
+          moreActions: [
+            {
+              id: 'exportSettings',
+              type: 'custom',
+              label: 'Export Settings',
+              biName: 'export-settings',
+            },
+            {
+              id: 'importSettings',
+              type: 'custom',
+              label: 'Import Settings',
+              biName: 'import-settings',
+            },
+            {
+              id: 'resetSettings',
+              type: 'custom',
+              label: 'Reset to Defaults',
+              biName: 'reset-settings',
+            },
+          ],
+        },
+
+        // Layout
+        layout: {
+          main: [
+            {
+              type: 'card',
+              card: {
+                title: { text: 'General Settings' },
+                subtitle: { text: 'Basic configuration for your application' },
+                children: [
+                  { type: 'field', field: { fieldId: 'name', span: 6 } },
+                  { type: 'field', field: { fieldId: 'description', span: 6 } },
+                ],
+              },
+            },
+            {
+              type: 'card',
+              card: {
+                title: { text: 'Display Options' },
+                subtitle: { text: 'Customize how content appears to users' },
+                children: [
+                  {
+                    type: 'container',
+                    container: {
+                      span: 12,
+                      children: [
+                        { type: 'field', field: { fieldId: 'showHeader', span: 4 } },
+                        { type: 'field', field: { fieldId: 'showFooter', span: 4 } },
+                        { type: 'field', field: { fieldId: 'showSidebar', span: 4 } },
+                      ],
+                    },
+                  },
+                  { type: 'field', field: { fieldId: 'maxItemsPerPage', span: 6 } },
+                ],
+              },
+            },
+            {
+              type: 'card',
+              card: {
+                title: { text: 'Notification Settings' },
+                children: [
+                  { type: 'field', field: { fieldId: 'emailNotifications', span: 6 } },
+                  { type: 'field', field: { fieldId: 'pushNotifications', span: 6 } },
+                  { type: 'field', field: { fieldId: 'notificationEmail', span: 12 } },
+                ],
+              },
+            },
+          ],
+          sidebar: [
+            {
+              type: 'card',
+              card: {
+                title: { text: 'Branding' },
+                subtitle: { text: 'Set your website URL' },
+                children: [
+                  { type: 'field', field: { fieldId: 'websiteUrl', span: 12 } },
+                ],
+              },
+            },
+          ],
+        },
+      },
+    },
+  ],
+};
+```
+
+### Data Source (appSettingsDataSource.ts)
+
+```typescript
+import type { SchemaConfig } from '@wix/auto-patterns';
+
+export const appSettingsDataSource = async (
+  _collectionId: string,
+  _context: any,
+): Promise<SchemaConfig> => {
+  return {
+    id: 'app-settings',
+    displayField: 'name',
+    idField: 'id',
+    fields: {
+      id: {
+        id: 'id',
+        type: 'SHORT_TEXT',
+        displayName: 'ID',
+        validation: { required: true },
+      },
+      name: {
+        id: 'name',
+        type: 'SHORT_TEXT',
+        displayName: 'App Name',
+        validation: { required: true },
+      },
+      description: {
+        id: 'description',
+        type: 'LONG_TEXT',
+        displayName: 'Description',
+      },
+      showHeader: {
+        id: 'showHeader',
+        type: 'BOOLEAN',
+        displayName: 'Show Header',
+      },
+      showFooter: {
+        id: 'showFooter',
+        type: 'BOOLEAN',
+        displayName: 'Show Footer',
+      },
+      showSidebar: {
+        id: 'showSidebar',
+        type: 'BOOLEAN',
+        displayName: 'Show Sidebar',
+      },
+      maxItemsPerPage: {
+        id: 'maxItemsPerPage',
+        type: 'NUMBER',
+        displayName: 'Max Items Per Page',
+      },
+      emailNotifications: {
+        id: 'emailNotifications',
+        type: 'BOOLEAN',
+        displayName: 'Email Notifications',
+      },
+      pushNotifications: {
+        id: 'pushNotifications',
+        type: 'BOOLEAN',
+        displayName: 'Push Notifications',
+      },
+      notificationEmail: {
+        id: 'notificationEmail',
+        type: 'SHORT_TEXT',
+        displayName: 'Notification Email',
+      },
+      websiteUrl: {
+        id: 'websiteUrl',
+        type: 'URL',
+        displayName: 'Website URL',
+      },
+    },
+    actions: {
+      get: async (entityId: string) => {
+        console.log('Getting settings:', entityId);
+        return {
+          id: 'app-settings',
+          name: 'My App',
+          description: 'App description',
+          showHeader: true,
+          showFooter: true,
+          showSidebar: false,
+          maxItemsPerPage: 10,
+          emailNotifications: true,
+          pushNotifications: false,
+          notificationEmail: 'admin@example.com',
+          websiteUrl: 'https://example.com',
+        };
+      },
+      create: async (newEntity: any) => {
+        console.log('Creating settings:', newEntity);
+        return newEntity;
+      },
+      update: async (updatedEntity: any) => {
+        console.log('Saving settings:', updatedEntity);
+        return updatedEntity;
+      },
+      delete: async (entityId: string) => {
+        console.log('Deleting settings:', entityId);
+        return { id: entityId };
+      },
+      bulkDelete: async (entityIds: string[]) => {
+        console.log('Bulk deleting settings:', entityIds);
+        return entityIds.map((id) => ({ id }));
+      },
+      find: async () => {
+        console.log('Fetching settings...');
+        return {
+          items: [
+            {
+              id: 'app-settings',
+              name: 'My App',
+              description: 'App description',
+              showHeader: true,
+              showFooter: true,
+              showSidebar: false,
+              maxItemsPerPage: 10,
+              emailNotifications: true,
+              pushNotifications: false,
+              notificationEmail: 'admin@example.com',
+              websiteUrl: 'https://example.com',
+            },
+          ],
+          hasNext: false,
+          total: 1,
+        };
+      },
+    },
+  };
+};
+```
+
+## Usage with AutoPatternsApp
+
+```tsx
+import React from 'react';
+import { WixDesignSystemProvider } from '@wix/design-system';
+import '@wix/design-system/styles.global.css';
+import {
+  AutoPatternsOverridesProvider,
+  AutoPatternsApp,
+} from '@wix/auto-patterns';
+import { WixPatternsBMProvider } from '@wix/patterns/bm';
+import { appConfig } from './settingPageConfig.patterns';
+import { useActions } from './useActions';
+import { useCustomDataSources } from './useCustomDataSources';
+
+const App = () => {
+  const actions = useActions();
+  const customDataSources = useCustomDataSources();
+
+  return (
+    <WixDesignSystemProvider features={{ newColorsBranding: true }}>
+      <WixPatternsBMProvider>
+        <AutoPatternsOverridesProvider
+          value={{
+            actions,
+            customDataSources,
+          }}
+        >
+          <AutoPatternsApp configuration={appConfig} />
+        </AutoPatternsOverridesProvider>
+      </WixPatternsBMProvider>
+    </WixDesignSystemProvider>
+  );
+};
+```
+
+## Validation
+
+Field validation is configured in the data source schema:
+
+```typescript
+fields: {
+  email: {
+    id: 'email',
+    type: 'SHORT_TEXT',
+    displayName: 'Email',
+    validation: { required: true },
+  },
+}
+```
+
+When a user attempts to save with invalid fields:
+1. The first invalid field is focused
+2. The save action is prevented
+3. An error is thrown to indicate form validation failure
+
+## Best Practices
+
+1. **Use Custom Data Source Pattern**: Settings pages use the same data source pattern as collection pages for consistency
+2. **Group Related Settings**: Use cards to organize related settings together
+3. **Use Descriptive Labels**: Field `displayName` should clearly describe the setting
+4. **Provide Context**: Use card subtitles and learn more links to help users understand settings
+5. **Validate Required Fields**: Mark essential settings as required in the schema
+6. **Handle Errors**: Implement proper error handling in data source actions
+7. **Use Appropriate Field Types**: Choose the right field type for each setting (BOOLEAN for toggles, NUMBER for numeric values, etc.)
+
+## Common Mistakes to Avoid
+
+- Missing `entityTypeSource: 'custom'` and `custom.id` configuration
+- Not registering the custom data source in `AutoPatternsOverridesProvider`
+- Field IDs in layout not matching field definitions in the data source schema
+- Forgetting to wrap with required providers (WixDesignSystemProvider, WixPatternsBMProvider, AutoPatternsOverridesProvider)
+- Not handling async errors in data source actions
+- Using span values that exceed 12 columns per row
+- Forgetting to export and register custom actions
+
+## File Structure
+
+A typical settings page implementation has the following structure:
+
+```
+src/
+├── components/
+│   └── Settings/
+│       ├── settingPageConfig.patterns.ts  # AppConfig with page configuration
+│       ├── appSettingsDataSource.ts       # Custom data source with schema and actions
+│       ├── useCustomDataSources.tsx       # Hook to register data source
+│       ├── useActions.tsx                 # Hook to register custom actions
+│       └── actions/
+│           ├── index.ts                   # Export all actions
+│           ├── exportSettings.tsx         # Export action resolver
+│           ├── importSettings.tsx         # Import action resolver
+│           └── resetSettings.tsx          # Reset action resolver
+└── pages/
+    └── settings/
+        └── index.tsx                      # Page component with providers
+```