@wix/auto-patterns 1.36.0 → 1.38.0

package/mcp-docs/bulk_actions.md

@@ -49,6 +49,66 @@ Bulk delete actions remove multiple entities with a confirmation modal.
 2. `bulkDelete.modal` object must exist
 3. The modal properties (title, description, actions, feedback) are all optional
 
+#### Dynamic Modal Titles
+
+Bulk delete modal titles can be made dynamic to reflect the number and type of selected items.
+
+**Configuration**
+
+Use the `title.id` property to reference a dynamic title resolver:
+
+```typescript
+bulkActionToolbar: {
+  primaryActions: [{
+    type: 'action',
+    action: {
+      item: {
+        id: 'bulkDelete',
+        type: 'bulkDelete',
+        bulkDelete: {
+          mode: 'modal',
+          modal: {
+            title: {
+              id: 'dynamicDeleteTitle'  // References override function
+            },
+            // ... other modal config
+          }
+        }
+      }
+    }
+  }]
+}
+```
+
+**Implementation**
+
+Create a title resolver function in your overrides:
+
+```typescript
+const useBulkDeleteModalTitle = () => ({
+  dynamicDeleteTitle: ({ selectedCount, selectedValues }) => ({
+    text: `Delete ${selectedCount} ${selectedCount === 1 ? 'item' : 'items'}?`
+  }),
+});
+
+const bulkDeleteModalTitle = useBulkDeleteModalTitle();
+// In your page component
+<AutoPatternsOverridesProvider
+  value={{
+    bulkDeleteModalTitle,
+    // ... other overrides
+  }}
+>
+  <AutoPatternsApp configuration={config} />
+</AutoPatternsOverridesProvider>
+```
+
+**Parameters**
+
+The title resolver function receives:
+- `selectedCount: number` - Total number of selected items
+- `selectedValues: any[]` - Array of selected item objects
+
 ### Custom Bulk Action Configuration
 
 Custom bulk actions execute JavaScript code that you define for bulk operations. These actions receive parameters that give them access to selected entities data and utilities. Here's how to implement a custom bulk action:

package/mcp-docs/collection_page.md

@@ -52,3 +52,37 @@ The `layout` array contains the rendering components for the collection. Each la
 * `item.title`, `item.subtitle`, `item.image` fields are **Field IDs** from the schema.
 * If the user does not specify, **select the most relevant fields automatically**.
 * For grid components, it is strongly recommended to implement a primary action cell with an `update` action that navigates to the entity page. This provides users with an intuitive way to access detailed information and edit individual entities directly from the grid view.
+
+## Column Tooltips
+
+Add tooltips to column headers using the `tooltipContent` property. When provided, an info icon appears next to the column header that users can hover over to see the tooltip content.
+
+Use tooltips to provide:
+- **Explanations** - Help users understand what the column represents
+- **Tools** - Provide guidance on how to use or interpret the column data
+- **Additional information** - Offer context about the column's purpose, data format, or usage
+
+```json
+{
+  "columns": [
+    {
+      "id": "name",
+      "name": "Name",
+      "width": "200px",
+      "tooltipContent": "The name of the pet"
+    },
+    {
+      "id": "age",
+      "name": "Age",
+      "width": "100px",
+      "tooltipContent": "Age in years. Use this to filter pets by age range."
+    },
+    {
+      "id": "lastVisit",
+      "name": "Last Visit",
+      "width": "150px",
+      "tooltipContent": "Date of the pet's last veterinary visit. Click to sort by most recent visits."
+    }
+  ]
+}
+```

package/mcp-docs/custom_overrides.md

@@ -82,7 +82,19 @@ export default function YourPage() {
   const entityPageHeaderBadges = useEntityPageHeaderBadges();
 
   return (
-    <AutoPatternsOverridesProvider value={{ actions, columns, slots, sections, components, modals, customDataSources, entityPageHeaderSubtitle, entityPageHeaderBadges }}>
+    <AutoPatternsOverridesProvider
+      value={{
+        actions,
+        columns,
+        slots,
+        sections,
+        components,
+        modals,
+        customDataSources,
+        entityPageHeaderSubtitle,
+        entityPageHeaderBadges,
+      }}
+    >
       <AutoPatternsApp configuration={config} />
     </AutoPatternsOverridesProvider>
   );
@@ -94,6 +106,7 @@ export default function YourPage() {
 **When adding any new implementation (action, modal, column, slot, section or component), you MUST update the corresponding hook in the `index.tsx` file to include your new implementation.** The main page component uses these hooks, so they serve as the central export point for each type of override.
 
 For example:
+
 - Adding a new action → Update `../components/actions/index.tsx` to include the new action in the `useActions` hook
 - Adding a new modal → Update `../components/modals/index.tsx` to include the new modal in the `useModals` hook
 - Adding a new column override → Update `../components/columns/index.tsx` to include the new column in the `useColumns` hook
@@ -114,6 +127,38 @@ Without updating the hook index files, your implementations won't be available t
 - Incorrect import paths or naming mismatches
 - Forgetting to import and use the hook in the main page component
 
+## Bulk Delete Modal Titles
+
+Dynamic title generation for bulk delete confirmation modals.
+
+```typescript
+bulkDeleteModalTitle?: Record<
+  string,
+  (params: { selectedCount: number; selectedValues: any[] }) => { text: string }
+>;
+```
+
+**Usage Example:**
+```typescript
+const useBulkDeleteModalTitle = () => ({
+  dynamicProductDelete: ({ selectedCount }) => ({
+    text: `Delete ${selectedCount} ${selectedCount === 1 ? 'product' : 'products'}?`
+  }),
+});
+```
+
+**Integration:**
+```typescript
+
+const bulkDeleteModalTitle = useBulkDeleteModalTitle();
+
+<AutoPatternsOverridesProvider
+  value={{
+    bulkDeleteModalTitle,
+  }}
+>
+```
+
 ## 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.
@@ -145,8 +190,8 @@ import { Badge } from '@wix/design-system';
 
 /* The `IColumnValue<T>` interface provides type safety for column override functions: */
 interface IColumnValue<T> {
-  value: T;                    // The individual column value (strongly typed)
-  row: Record<string, any>;    // The entire row object with all field values
+  value: T; // The individual column value (strongly typed)
+  row: Record<string, any>; // The entire row object with all field values
 }
 
 // For TEXT fields
@@ -157,9 +202,7 @@ export function petName({ value, row }: IColumnValue<string>) {
 // For NUMBER fields
 export function age({ value, row }: IColumnValue<number>) {
   return (
-    <Badge skin={value > 5 ? 'warning' : 'success'}>
-      {value} years old
-    </Badge>
+    <Badge skin={value > 5 ? 'warning' : 'success'}>{value} years old</Badge>
   );
 }
 
@@ -194,23 +237,29 @@ export function hobbies({ value, row }: IColumnValue<string[]>) {
 **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" }
+    {
+      "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 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
 
@@ -260,7 +309,9 @@ export function petInfo({ value, row }: IColumnValue<string>) {
         {row.age} years old • {row.type}
       </Text>
       {row.isVaccinated && (
-        <Text size="tiny" skin="success">✓ Vaccinated</Text>
+        <Text size="tiny" skin="success">
+          ✓ Vaccinated
+        </Text>
       )}
     </Box>
   );
@@ -306,7 +357,9 @@ import { IColumnValue } from '@wix/auto-patterns/types';
 
 export function date({ value, row }: IColumnValue<string>) {
   // 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);
+  const isRecent =
+    row.lastActivity &&
+    new Date(row.lastActivity) > new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
 
   return (
     <span style={{ color: isRecent ? 'green' : 'inherit' }}>
@@ -333,7 +386,7 @@ export const useColumns = () => {
     petInfo,
     status,
     fullName,
-    date
+    date,
   };
 };
 ```
@@ -411,6 +464,7 @@ These components can display custom UI elements like notifications, information
 ### 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
@@ -425,6 +479,7 @@ import { useController } from '@wix/auto-patterns/form'; // Always import from t
 ```
 
 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
@@ -468,7 +523,6 @@ export const customNameField: FC<CustomComponentProps> = ({ form, entity }) => {
 };
 ```
 
-
 ### Example: Standalone Component (Not Field-Specific)
 
 Custom components can also be used to add UI elements not tied to specific fields:
@@ -485,8 +539,8 @@ export const infoCard: FC<CustomComponentProps> = ({ entity }) => {
         <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.
+            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>
@@ -512,7 +566,7 @@ export const useComponents = () => {
   // You can access React context and other hooks here
   return {
     customNameField,
-    infoCard
+    infoCard,
   };
 };
 ```
@@ -577,9 +631,7 @@ const CustomComponent: FC<CustomComponentProps> = ({ form, entity }) => {
         onChange={(e) => form.setValue('name', e.target.value)}
       />
 
-      {showSpecialMessage && (
-        <Text>Special message for special name!</Text>
-      )}
+      {showSpecialMessage && <Text>Special message for special name!</Text>}
     </Box>
   );
 };
@@ -599,18 +651,16 @@ const CustomComponent: FC<CustomComponentProps> = ({ form, entity }) => {
         onChange={(e) => form.setValue('name', e.target.value)}
       />
 
-      {showSpecialMessage && (
-        <Text>Special message for special name!</Text>
-      )}
+      {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)
@@ -623,7 +673,7 @@ const CustomComponent: FC<CustomComponentProps> = ({ form, entity }) => {
   const controller = useController({
     name: 'name', // Field ID from the schema
     control: form.control,
-    defaultValue: entity?.name // Initialize from entity
+    defaultValue: entity?.name, // Initialize from entity
   });
 
   // Use watch for reactive updates
@@ -638,9 +688,7 @@ const CustomComponent: FC<CustomComponentProps> = ({ form, entity }) => {
           onChange={(e) => controller.field.onChange(e.target.value)}
         />
       </FormField>
-      {hasChanges && (
-        <Text size="small">Original value: {entity?.name}</Text>
-      )}
+      {hasChanges && <Text size="small">Original value: {entity?.name}</Text>}
     </Box>
   );
 };
@@ -685,6 +733,7 @@ When implementing a custom data source, you need to modify the `collection` conf
   }
 }
 ```
+
 ## Sections
 
 Sections allow you to group table rows under section headers, making it easier to organize and navigate through large datasets. This feature is especially useful when you want to categorize entities by specific criteria.
@@ -722,6 +771,7 @@ To enable sections, add the `sections` configuration to your table configuration
 ```
 
 **Key Properties:**
+
 - `entityTypeSource`: Must be set to `"custom"` instead of `"cms"`
 - `custom.id`: A unique identifier for your custom data source implementation
 
@@ -748,6 +798,7 @@ export default function YourPage() {
 #### 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:
@@ -763,8 +814,12 @@ You must implement a custom data source function that:
 ### Example Implementation Structure
 
 ```tsx
+import { SchemaConfig } from '@wix/auto-patterns/types';
 // customDataSources/myCustomDataSource.ts
-export const myCustomDataSource = async (collectionId: string, context: any) => {
+export const myCustomDataSource = async (
+  collectionId: string,
+  context: any,
+): Promise<SchemaConfig> => {
   return {
     id: 'myCustomCollection',
     fields: {
@@ -773,17 +828,31 @@ export const myCustomDataSource = async (collectionId: string, context: any) =>
     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 */ }
-    }
+      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 */
+      },
+    },
   };
 };
 ```
 
+> This is a simplified example of a custom data source implementation, do not use it as-is. You must implement the actual logic to connect to the FQDN schema.
+
 ### Hook Implementation
 
 In `components/customDataSources/index.tsx`:
@@ -794,7 +863,7 @@ import { myCustomDataSource } from './myCustomDataSource';
 export const useCustomDataSources = () => {
   // You can access React context and other hooks here
   return {
-    myCustomDataSource
+    myCustomDataSource,
   };
 };
 ```
@@ -812,8 +881,6 @@ When implementing custom data sources, you need to map your data source field ty
 - **Reference fields** → `'REFERENCE'`
 - **URL fields** → `'URL'`
 
-
-
 ### Validation Requirements
 
 - **Function Signature**: Custom data source must be a function with signature `(collectionId: string, context: any) => Promise<SchemaConfig>`
@@ -870,7 +937,7 @@ Section renderers are functions that determine how to group items and what infor
 #### Function Signature
 
 ```tsx
-function sectionRenderer(item: any): Section
+function sectionRenderer(item: any): Section;
 ```
 
 Where `Section` is the interface from @wix/patterns (re-exported from auto-patterns):
@@ -893,6 +960,7 @@ interface Section {
 ```
 
 The section renderer receives an item and returns:
+
 - **id**: A unique identifier for the section (items with the same id are grouped together)
 - **title**: The text displayed in the section header
 - **primaryAction** (optional): An action button displayed in the section header
@@ -956,7 +1024,9 @@ export function groupByAgeAndVaccination(item: any): Section {
     badgeSkin = 'neutralLight';
   } else if (age >= 1 && age <= 5) {
     sectionId = isVaccinated ? 'young-vaccinated' : 'young-unvaccinated';
-    sectionTitle = `Young Adults (1-5 years) - ${isVaccinated ? 'Vaccinated' : 'Not Vaccinated'}`;
+    sectionTitle = `Young Adults (1-5 years) - ${
+      isVaccinated ? 'Vaccinated' : 'Not Vaccinated'
+    }`;
     badgeSkin = isVaccinated ? 'light' : 'danger';
   } else {
     sectionId = 'seniors';
@@ -967,13 +1037,16 @@ export function groupByAgeAndVaccination(item: any): Section {
   return {
     id: sectionId,
     title: sectionTitle,
-    primaryAction: age < 1 ? {
-      id: 'special-care',
-      label: 'Special Care Info',
-      onClick: () => {
-        // Show special care information for puppies
-      },
-    } : undefined,
+    primaryAction:
+      age < 1
+        ? {
+            id: 'special-care',
+            label: 'Special Care Info',
+            onClick: () => {
+              // Show special care information for puppies
+            },
+          }
+        : undefined,
     badge: {
       visible: true,
       skin: badgeSkin,
@@ -993,7 +1066,7 @@ import * as actions from './components/actions';
 
 <AutoPatternsOverridesProvider value={{ sections, columns, actions }}>
   <AutoPatternsApp configuration={config} />
-</AutoPatternsOverridesProvider>
+</AutoPatternsOverridesProvider>;
 ```
 
 ### Important Notes
@@ -1003,7 +1076,6 @@ import * as actions from './components/actions';
 - **Performance**: Section renderers are called for every item, so keep the logic lightweight.
 - **TableGridSwitch**: Sections work in both table and grid views when using TableGridSwitch.
 
-
 By implementing sections, you can significantly improve the user experience when dealing with large datasets by providing logical groupings that make information easier to find and understand.
 
 ## Slots
@@ -1011,6 +1083,7 @@ By implementing sections, you can significantly improve the user experience when
 Slots allow you to inject custom React components into collection pages at specific points in the component hierarchy. Unlike other overrides that modify existing functionality, slots enable you to add entirely custom UI elements anywhere within the collection page components array.
 
 Slots are useful for:
+
 - Adding custom banners or announcements above or below the table/grid
 - Inserting analytics widgets or dashboards
 - Adding custom promotional content
@@ -1028,6 +1101,7 @@ Slots are configured in the collection page configuration using the `CustomCompo
 ```
 
 **Key Properties:**
+
 - `type`: Must be set to `"custom"` to identify this as a slot component
 - `id`: A unique identifier that maps to your slot component implementation
 
@@ -1061,6 +1135,7 @@ Slot components can be positioned anywhere within the `components` array of a co
 ```
 
 This configuration will render:
+
 1. The custom `topBanner` component at the top
 2. The main collection component (table/grid) in the middle
 3. The custom `bottomStats` component at the bottom
@@ -1080,7 +1155,9 @@ export const TopBannerComponent: React.FC = () => {
     <Card>
       <Card.Content>
         <Box direction="vertical" gap={2}>
-          <Text size="large" weight="bold">Welcome to Pet Management</Text>
+          <Text size="large" weight="bold">
+            Welcome to Pet Management
+          </Text>
           <Text>Manage all your pets from this central dashboard.</Text>
           <Button size="small">Get Started</Button>
         </Box>
@@ -1095,11 +1172,15 @@ export const BottomStatsComponent: React.FC = () => {
       <Card.Content>
         <Box direction="horizontal" gap={4}>
           <Box direction="vertical" gap={1}>
-            <Text size="large" weight="bold">47</Text>
+            <Text size="large" weight="bold">
+              47
+            </Text>
             <Text size="small">Total Pets</Text>
           </Box>
           <Box direction="vertical" gap={1}>
-            <Text size="large" weight="bold">12</Text>
+            <Text size="large" weight="bold">
+              12
+            </Text>
             <Text size="small">Available for Adoption</Text>
           </Box>
         </Box>
@@ -1121,7 +1202,7 @@ export const useSlots = () => {
   // You can access React context and other hooks here
   return {
     topBanner: TopBannerComponent,
-    bottomStats: BottomStatsComponent
+    bottomStats: BottomStatsComponent,
   };
 };
 ```
@@ -1153,7 +1234,6 @@ export default function YourPage() {
 3. **Performance**: Slot components re-render with the page, so optimize for performance if needed
 4. **Styling**: Follow the design system patterns and responsive design principles
 
-
 **Important:** Every time you create a new slot component, you must import it and add it to the `useSlots` hook return object in the `./components/slots/index.tsx` file. The key must match the `id` specified in your JSON configuration.
 
 Slots provide a powerful way to enhance collection pages with custom functionality while maintaining the structure and features of the AutoPatterns system.