@wix/auto-patterns 1.15.0 → 1.17.0

package/dist/docs/custom_overrides.md

@@ -0,0 +1,511 @@
+# Custom Overrides
+
+## ⚠️ Override Rules
+
+- **Custom overrides are restricted to the defined areas only** - attempting to override or modify any other aspect of `AutoPatternsApp` is prohibited and can cause unexpected behavior
+- **Always verify override implementation** - when implementing custom overrides, you MUST ensure they are correctly imported and passed to the `PatternsWizardOverridesProvider`
+
+The `PatternsWizardOverridesProvider` allows you to inject custom code to override default behaviors or add additional functionality. Below are the areas where overrides can be applied:
+
+> **Note:** These are the only areas where overrides are supported. Avoid attempting to override or modify other parts of the system, as this is not supported and may lead to unexpected behavior.
+
+## Folder Structure Organization
+
+All custom overrides (components, modals, actions, columns, and other customizations) should be created in a `components` folder inside your page directory, not in a global `/src/components` folder. This keeps page-specific customizations organized alongside their respective pages.
+
+### Recommended Structure:
+
+```
+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
+    ├── actions/                       // Custom actions
+    │   ├── index.tsx
+    │   └── myCustomAction.tsx
+    ├── columns/                       // Column overrides
+    │   ├── index.tsx
+    │   ├── name.ts
+    │   └── date.ts
+    └── customComponents/              // Custom entity page components
+        ├── index.tsx
+        ├── CustomNameField.tsx
+        └── InfoCard.tsx
+```
+
+### Importing Overrides in Your Page
+
+In your page component, import from the local components folder:
+
+```tsx
+import * as modals from './components/modals';
+import * as actions from './components/actions';
+import * as columns from './components/columns';
+import * as components from './components/customComponents';
+
+<PatternsWizardOverridesProvider value={{ modals, actions, columns, components }}>
+  <AutoPatternsApp configuration={config as AppConfig} />
+</PatternsWizardOverridesProvider>
+```
+
+### Important: Updating Index Files
+
+**When adding any new implementation (action, modal, column, or component), you MUST update the corresponding `index.tsx` file to export your new implementation.** The main page component imports from these index files, so they serve as the central export point for each type of override.
+
+For example:
+- Adding a new action → Update `./components/actions/index.tsx`
+- 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`
+
+Without updating the index files, your implementations won't be available to the `PatternsWizardOverridesProvider`.
+
+## ⚠️ Common Override Mistakes to Avoid
+
+- Attempting to override unsupported areas
+- Invalid column rendering functions
+- Missing index file exports for new implementations
+- Incorrect import paths or naming mismatches
+
+## Columns
+
+Each column in the table has a default rendering based on its field type. You can override this rendering by providing a custom function for the `column.id`. This allows you to customize how specific columns are displayed.
+
+**Enhanced Column Overrides**: Column override can receive both the individual column `value` and the entire `row` data, enabling you to create complex columns that combine multiple field values from the same row.
+
+### Function Signature
+
+```typescript
+function columnOverride({ value, row }) {
+  // value: The individual column value
+  // row: The entire row object containing all field values
+  return <YourCustomRendering />;
+}
+```
+
+### Understanding Row Data
+
+**Important**: The `row` object contains all field values from the entity, where each property corresponds to a **field ID** from the collection schema. To access specific field values, use the exact field ID as defined in your collection schema.
+
+For example, if your collection schema has these fields:
+```json
+{
+  "fields": [
+    { "key": "name", "displayName": "Pet Name", "type": "TEXT" },
+    { "key": "age", "displayName": "Age", "type": "NUMBER" },
+    { "key": "isVaccinated", "displayName": "Vaccinated", "type": "BOOLEAN" },
+    { "key": "lastActivity", "displayName": "Last Activity", "type": "DATETIME" }
+  ]
+}
+```
+
+Then in your column override, you access these values using the field IDs:
+```typescript
+export function myColumn({ value, row }) {
+  // Access field values using their schema field IDs
+  const petName = row.name;           // "name" field ID
+  const petAge = row.age;             // "age" field ID
+  const isVaccinated = row.isVaccinated; // "isVaccinated" field ID
+  const lastActivity = row.lastActivity; // "lastActivity" field ID
+
+  return <YourCustomRendering />;
+}
+```
+
+### Use Cases for Row Data Access
+
+1. **Complex Display Columns**: Combine multiple fields into a single display (e.g., "Name (Age)" combining name and age fields)
+2. **Conditional Rendering**: Show different content based on other field values in the same row
+3. **Calculated Columns**: Create computed values using multiple row fields
+4. **Cross-Field Validation Display**: Show validation status based on relationships between fields
+
+### Example: Defining and Using Column Overrides
+
+In `components/columns/name.tsx`:
+
+```ts
+import React from 'react';
+
+export function name({ value, row }) {
+  // Simple value formatting
+  return <strong>{value}</strong>;
+}
+```
+
+In `components/columns/petInfo.tsx`:
+
+```ts
+import React from 'react';
+import { Box, Text } from '@wix/design-system';
+
+export function petInfo({ value, row }) {
+  // Complex column combining multiple row values
+  return (
+    <Box direction="vertical" gap={1}>
+      <Text weight="bold">{row.name}</Text>
+      <Text size="small" skin="disabled">
+        {row.age} years old • {row.type}
+      </Text>
+      {row.isVaccinated && (
+        <Text size="tiny" skin="success">✓ Vaccinated</Text>
+      )}
+    </Box>
+  );
+}
+```
+
+In `components/columns/status.tsx`:
+
+```ts
+import React from 'react';
+import { Badge } from '@wix/design-system';
+
+export function status({ value, row }) {
+  // Conditional rendering based on multiple row fields
+  if (row.isVaccinated && row.age > 1) {
+    return <Badge skin="success">Ready for Adoption</Badge>;
+  } else if (!row.isVaccinated) {
+    return <Badge skin="warning">Needs Vaccination</Badge>;
+  } else {
+    return <Badge skin="neutral">Too Young</Badge>;
+  }
+}
+```
+
+In `components/columns/fullName.tsx`:
+
+```ts
+import React from 'react';
+
+export function fullName({ value, row }) {
+  // Calculated column using multiple fields
+  return `${row.name} (owned by ${row.owner})`;
+}
+```
+
+In `components/columns/date.tsx`:
+
+```ts
+import React from 'react';
+
+export function date({ value, row }) {
+  // Access to other row data for enhanced date formatting
+  const isRecent = row.lastActivity && new Date(row.lastActivity) > new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+
+  return (
+    <span style={{ color: isRecent ? 'green' : 'inherit' }}>
+      <em>{new Date(value).toLocaleDateString()}</em>
+      {isRecent && ' (Recent)'}
+    </span>
+  );
+}
+```
+
+In `components/columns/index.tsx`:
+
+```ts
+export * from './name';
+export * from './petInfo';
+export * from './status';
+export * from './fullName';
+export * from './date';
+```
+
+**Important:** Every time you add a new column override file, you must add a corresponding export line to this `index.tsx` file. For example, if you create `price.tsx`, you must add `export * from './price';` to the index file.
+
+In the `PatternsWizardOverridesProvider`:
+
+```tsx
+import * as columns from './components/columns';
+
+<PatternsWizardOverridesProvider value={{ columns }}>
+  <AutoPatternsApp configuration={config as AppConfig} />
+</PatternsWizardOverridesProvider>
+```
+
+### Visual Representation
+
+```
+your-page/
+└── components/
+    └── columns/
+        ├── index.tsx     // Exports all column overrides
+        ├── name.tsx      // Simple value formatting
+        ├── petInfo.tsx   // Complex multi-field column
+        ├── status.tsx    // Conditional rendering column
+        ├── fullName.tsx  // Calculated column
+        └── date.tsx      // Enhanced formatting with row context
+
+PatternsWizardOverridesProvider
+ └── value.columns
+      ├── name
+      ├── petInfo
+      ├── status
+      ├── fullName
+      └── date
+```
+
+### Key Benefits of Row Data Access
+
+1. **Reduced Configuration Complexity**: Instead of adding multiple columns, create one complex column that shows related information
+2. **Better User Experience**: Present related data together in a logical, readable format
+3. **Dynamic Content**: Show different content based on the state of other fields
+4. **Data Relationships**: Highlight relationships between different field values in the same entity
+
+### Important Guidelines
+
+- **Performance**: Remember that column functions are called for every row, so keep calculations lightweight
+- **Consistency**: When using row data, ensure the column header accurately represents what's displayed
+- **Accessibility**: Maintain proper semantic structure when combining multiple values
+
+## Components
+
+Components allow you to create custom rendering for specific elements in the entity page. Each component has a unique `componentId` that corresponds to the ID specified in the layout configuration.
+
+The custom components receive two essential props:
+
+1. **form**: An instance of `UseFormReturn` from react-hook-form (re-exported through `@wix/auto-patterns/form`), giving you access to the form control, methods, and state.
+2. **entity**: A key-value object where keys are field IDs from the collection schema and values are the current field values, providing access to the entity's data.
+
+Custom components can serve two main purposes:
+
+### 1. Standalone Custom Components
+
+These components can display custom UI elements like notifications, information cards, or any other custom content that isn't directly tied to specific fields. These are useful for adding unique UI elements that enhance the entity page experience.
+
+### 2. Field Rendering Overrides
+
+You can use custom components to override the default rendering of one or more fields. This allows you to:
+- Apply custom validation logic
+- Create custom input components
+- Combine multiple fields into a single UI component
+- Add field-specific functionality not available in the default renderers
+
+### Using the useController Hook for Field Overrides
+
+When creating field overrides, use the `useController` hook from `@wix/auto-patterns/form` (a re-export of react-hook-form's hook) to connect your custom component to the form state:
+
+```tsx
+import { useController } from '@wix/auto-patterns/form'; // Always import from this path, not react-hook-form
+```
+
+The hook requires:
+- **name**: The field name you want to edit (should match the schema field ID)
+- **control**: Retrieved from `form.control`
+- **defaultValue**: Set from `entity?.[fieldId]` when it exists
+
+### Example: Defining a Custom Component
+
+Here's an example of a custom component that overrides the rendering of the "name" field:
+
+```tsx
+import React, { FC } from 'react';
+import { Box, Card, FormField, Input, Text } from '@wix/design-system';
+import { useController } from '@wix/auto-patterns/form';
+import { CustomComponentProps } from '@wix/auto-patterns/types';
+
+export const customNameField: FC<CustomComponentProps> = ({ form, entity }) => {
+  // Create a controller for the name field
+  const controller = useController({
+    name: 'name', // Field ID from the schema
+    control: form.control, // Form control
+    defaultValue: entity?.name, // Default value from entity
+  });
+
+  return (
+    <FormField
+      label="Name"
+      required={true}
+      charCount={100}
+      // Connect field state to UI
+      status={controller.fieldState.invalid ? 'error' : undefined}
+      statusMessage={controller.fieldState.error?.message}
+      dataHook={`short-text-${controller.field.name}`}
+    >
+      <Input
+        // Connect field value and onChange
+        value={controller.field.value}
+        onChange={(e) => controller.field.onChange(e.target.value)}
+        dataHook={`short-text-${controller.field.name}`}
+      />
+    </FormField>
+  );
+};
+```
+
+
+### Example: Standalone Component (Not Field-Specific)
+
+Custom components can also be used to add UI elements not tied to specific fields:
+
+```tsx
+import React, { FC } from 'react';
+import { Box, Card, Text, Button } from '@wix/design-system';
+import { CustomComponentProps } from '@wix/auto-patterns/types';
+
+export const infoCard: FC<CustomComponentProps> = ({ entity }) => {
+  return (
+    <Card>
+      <Card.Content>
+        <Box direction="vertical" gap={2}>
+          <Text weight="bold">Important Information</Text>
+          <Text>
+            This custom component can display additional information or functionality
+            that isn't directly tied to a specific field.
+          </Text>
+          {entity?.isVaccinated ? (
+            <Text skin="success">This pet is vaccinated</Text>
+          ) : (
+            <Text skin="warning">This pet needs vaccination</Text>
+          )}
+        </Box>
+      </Card.Content>
+    </Card>
+  );
+};
+```
+
+### Connecting Components in the Provider
+
+In your main page file, import and provide these components via the `PatternsWizardOverridesProvider`:
+
+```tsx
+import * as components from './components';
+
+<PatternsWizardOverridesProvider value={{ components }}>
+  <AutoPatternsApp configuration={config as AppConfig} />
+</PatternsWizardOverridesProvider>
+```
+
+### Important Guidelines for Custom Components
+
+1. **Always import from `@wix/auto-patterns/form`** instead of directly from `react-hook-form`
+2. **Follow react-hook-form best practices** - the underlying infrastructure is built on react-hook-form
+3. **Handle form state properly**:
+   - Use `controller.fieldState.invalid` for error state
+   - Use `controller.fieldState.error?.message` for error messages
+   - Connect `controller.field.value` to input values
+   - Use `controller.field.onChange` for change handlers
+4. **Component rendering**:
+   - Choose appropriate design-system components based on the field type
+   - For text fields: `Input`
+   - For multi-line text: `InputArea`
+   - For checkboxes: `Checkbox`
+   - For dates: `DatePicker`
+   - For dropdowns: `Dropdown`
+
+**Important:** Every time you create a new custom component, you must add a corresponding export line to the `./components/customComponents/index.tsx` file. For example, if you create `StatusIndicator.tsx`, you must add `export * from './StatusIndicator';` to the index file.
+
+### Understanding Reactivity in Custom Components
+
+5. **Reactivity and field value changes (IMPORTANT)**:
+   - **NEVER rely on the `entity` object for reactive UI** - it is not reactive to form changes
+   - For any reactive UI that needs to respond to field value changes in real-time:
+     - Use `form.watch('fieldName')` to observe field changes reactively
+     - Use `useController` hook when you need both read and write access to a field
+
+#### Common Reactivity Issues and Solutions
+
+##### Example: Conditional Display Based on Field Value
+
+```tsx
+// ❌ INCORRECT APPROACH (Non-reactive)
+const CustomComponent: FC<CustomComponentProps> = ({ form, entity }) => {
+  // This won't update when the user changes the name in the form
+  const showSpecialMessage = entity?.name === 'special';
+
+  return (
+    <Box>
+      <Input
+        value={form.getValues('name')}
+        onChange={(e) => form.setValue('name', e.target.value)}
+      />
+
+      {showSpecialMessage && (
+        <Text>Special message for special name!</Text>
+      )}
+    </Box>
+  );
+};
+```
+
+```tsx
+// ✅ CORRECT APPROACH (Reactive)
+const CustomComponent: FC<CustomComponentProps> = ({ form, entity }) => {
+  // This WILL update whenever the name field changes
+  const nameValue = form.watch('name');
+  const showSpecialMessage = nameValue === 'special';
+
+  return (
+    <Box>
+      <Input
+        value={nameValue}
+        onChange={(e) => form.setValue('name', e.target.value)}
+      />
+
+      {showSpecialMessage && (
+        <Text>Special message for special name!</Text>
+      )}
+    </Box>
+  );
+};
+```
+
+
+##### When to Use the Entity Object
+
+The `entity` object is useful for:
+- Setting initial values
+- Accessing read-only data that doesn't change
+- Comparing form state with original values (e.g., detecting if changes were made)
+- Initializing form fields with useController's defaultValue parameter
+
+```tsx
+// Example: Proper use of entity object with useController
+const CustomComponent: FC<CustomComponentProps> = ({ form, entity }) => {
+  // Use entity for initialization via defaultValue
+  const controller = useController({
+    name: 'name', // Field ID from the schema
+    control: form.control,
+    defaultValue: entity?.name // Initialize from entity
+  });
+
+  // Use watch for reactive updates
+  const currentName = controller.field.value;
+  const hasChanges = entity?.name !== currentName;
+
+  return (
+    <Box>
+      <FormField label="Name">
+        <Input
+          value={currentName}
+          onChange={(e) => controller.field.onChange(e.target.value)}
+        />
+      </FormField>
+      {hasChanges && (
+        <Text size="small">Original value: {entity?.name}</Text>
+      )}
+    </Box>
+  );
+};
+```
+
+### Visual Representation
+
+```
+your-page/
+└── components/
+    ├── index.tsx              // Exports all component overrides
+    ├── customNameField.tsx   // Field override component
+    ├── combinedNameFields.tsx // Multiple fields override
+    └── infoCard.tsx          // Standalone component
+
+PatternsWizardOverridesProvider
+ └── value.components
+      ├── customNameField
+      ├── combinedNameFields
+      └── infoCard
+```
+
+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.

package/dist/docs/entity_page.md

@@ -0,0 +1,104 @@
+# Entity Page Configuration
+
+## ⚠️ Entity Page Requirements
+
+All entity pages must have:
+- **A route path with descriptive segment and dynamic parameter** (e.g., `/product/:entityId`, `/pet/:entityId`) - **never just `/:entityId`** as this conflicts with collection page routing
+- **A matching `route.params` configuration** that maps the dynamic parameter
+- **A reference to their parent collection page via `parentPageId`**
+
+## Overview
+
+* Displays details for a **single entity**.
+* Always tied to a single Wix collection.
+* `entityTypeSource` is always `'cms'`.
+
+> The custom actions must be defined inside the `moreActions` array.
+
+> Note: You do not need to define a custom action to navigate to the entity page. This behavior is built-in — clicking on a row in the collection table automatically navigates to the corresponding entity page.
+
+## Entity Page Layout Configuration
+
+### 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.
+- Example: If an item has `span: 8` and the next has `span: 5`, the second item will start a new line.
+
+### Layout Structure
+
+- **Main Section**: Contains primary entity information and most important fields.
+- **Sidebar Section**: Contains secondary information, metadata, or supporting content.
+- Both sections support cards that can contain fields, containers, and components.
+
+### Detailed Layout Content Types
+
+1. **Field Type**:
+   ```typescript
+   {
+     type: 'field';
+     field: {
+       span?: number; // How many columns this field occupies (1-12)
+       fieldId: string; // Must match a valid field ID from the collection schema
+     };
+   }
+   ```
+
+2. **Container Type** (for grouping related fields):
+   ```typescript
+   {
+     type: 'container';
+     container: {
+       span?: number; // How many columns this container occupies (1-12)
+       children: LayoutContent[]; // Can nest fields, other containers, or components
+     };
+   }
+   ```
+
+3. **Component Type** (for custom rendering):
+   ```typescript
+   {
+     type: 'component';
+     component: {
+       span?: number; // How many columns this component occupies (1-12)
+       componentId: string; // ID matching a component override implementation
+     };
+   }
+   ```
+
+### Layout Best Practices
+
+1. **Field Grouping**:
+   - Group related fields using containers
+   - Place frequently used fields at the top
+   - Consider the natural flow of data entry
+
+2. **Main vs. Sidebar Usage**:
+   - Main section: Put primary entity information
+   - Sidebar: Place secondary information and metadata
+
+3. **Responsive Considerations**:
+   - Use appropriate spans for different field types
+   - Text fields often benefit from larger spans
+   - Boolean fields can use smaller spans
+
+4. **Nested Containers**:
+   - Use containers to create logical groupings
+   - Don't nest containers too deeply for clarity
+   - Consider using cards for major sections instead of deeply nested containers
+
+5. **Image Handling**:
+   - For image fields, consider providing more space (larger span)
+   - Images are automatically rendered with proper controls when using the field type
+
+## ⚠️ Common Entity Page Layout Mistakes to Avoid
+
+- Using incorrect span values causing unexpected layout breaks
+- Referencing non-existent field IDs in the layout
+- Creating overly complex nested container structures
+- Failing to properly register component overrides
+- Confusing main and sidebar section usage (putting main content in sidebar)
+- Exceeding 12 total columns in a row without realizing content will wrap
+- Forgetting to specify the `collectionPagePath` value
+- Missing required `type: 'card'` structure in layout sections