@wix/auto-patterns 1.25.0 → 1.26.0

package/dist/docs/auto-patterns-guide.md

@@ -78,7 +78,7 @@ It is configured using a TypeScript file conforming to the `AppConfig` interface
 
 # AppConfig Structure
 
-## ⚠️ Configuration Rules
+## Configuration Rules
 
 - **Configuration must come only from a TypeScript file** - never inline or from other sources
 - **Always use proper TypeScript typing**: `export const config: AppConfig = { ... }`
@@ -86,7 +86,7 @@ It is configured using a TypeScript file conforming to the `AppConfig` interface
 - **After each configuration change, verify that the configuration strictly aligns with the structure described below** - any configuration entries not defined in this structure must be removed
 - **When generating config for the first time, select up to 3 columns from the schema that best represent the entity**
 
-## ⚠️ Common Configuration Mistakes to Avoid
+## Common Configuration Mistakes to Avoid
 
 - Adding more than two pages
 - Mixing page types in a single configuration
@@ -392,9 +392,13 @@ export interface AppConfig {
       };
       title?: {
         text: string; // Entity page title
+        badges?: {
+          id?: string; // Optional ID that maps to a dynamic badges override function
+        };
       };
       subtitle?: {
         text: string; // Entity page subtitle
+        id?: string; // Optional ID that maps to a dynamic subtitle override function
       };
       actions?: { // Action configuration varies by mode
         // Edit mode: only moreActions supported
@@ -556,7 +560,7 @@ Notice how the `label` is derived from the `value` by capitalizing the first let
 
 # Pages Configuration
 
-## ⚠️ Critical Page Rules
+## Critical Page Rules
 
 - **Pages array must contain exactly two pages** - one collectionPage and one entityPage
 - **Exactly one page must have `appMainPage: true`** to designate it as the main page
@@ -637,7 +641,7 @@ A two-way connection must be established between collection pages and entity pag
 * **Route Structure**: Entity pages must use `/[segment]/:entityId` format (e.g., `/product/:entityId` or `/pets/:entityId`), never just `/:entityId`
 * **Route Parameters Configuration**: All entity pages must have both a dynamic parameter in `route.path` and a matching configuration in `route.params`
 
-## ⚠️ Common Route and Configuration Mistakes to Avoid
+## Common Route and Configuration Mistakes to Avoid
 
 - Missing route.params for entity pages
 - Using `/:entityId` instead of `/segment/:entityId` for entity page routes (causes routing conflicts)
@@ -678,7 +682,7 @@ Sticky columns allow you to keep specific columns visible while users scroll hor
 
 # Collection Page Configuration
 
-## ⚠️ Collection Page Rules
+## Collection Page Rules
 
 - **Components array inside collectionPage must contain exactly one component with a layout array**
 - **All collection pages with tables/grids must reference their corresponding entity page via `entityPageId`** in the collection configuration
@@ -735,7 +739,7 @@ The `layout` array contains the rendering components for the collection. Each la
 
 # Collection Page Actions
 
-## ⚠️ Required Actions
+## Required Actions
 
 - **Every collection page must include a create action that navigates to the entity page for adding new entities** - this is essential for user workflow
 
@@ -1949,7 +1953,7 @@ AI agents should verify these requirements before generating Bulk Action Toolbar
 
 # Entity Page Configuration
 
-## ⚠️ Entity Page Requirements
+## 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
@@ -1961,6 +1965,20 @@ All entity pages must have:
 * Displays details for a **single entity**.
 * Always tied to a single Wix collection.
 * Supports **two distinct modes**: **view mode** and **edit mode** with separate page configurations.
+* Supports **dynamic subtitle** that adapt based on entity data (see [Entity Page Dynamic Subtitle](#entity-page-dynamic-subtitle)).
+* Supports **dynamic badges** in the page title that adapt based on entity data (see [Entity Page Dynamic Badges](#entity-page-dynamic-badges)).
+
+## 🏷️ **Understanding Badges Requests**
+
+When a user asks to "add badges to the entity page", understand that they want:
+
+1. **Custom component overrides** - NOT direct configuration in JSON
+2. **Function that returns badge objects** - NOT JSX components
+3. **Badge properties** like `text`, `skin`, `prefixIcon`, etc.
+4. **Registration in PatternsWizardOverridesProvider** under `entityPageHeaderBadges`
+
+**Example Request**: "Add 2 badges with random skins and text 'wow'"
+**Correct Implementation**: Create a function that returns `[{text: 'wow', skin: 'success'}, {text: 'wow', skin: 'premium'}]`
 
 ## Entity Page Modes
 
@@ -1989,6 +2007,284 @@ This pattern allows:
 - Clear distinction between view and edit URLs
 - Natural navigation flow between modes
 
+## Entity Page Dynamic Subtitle
+
+Entity pages support dynamic subtitles that adapt based on entity data, providing contextual information below the main title.
+
+### Configuration
+
+Add an `id` property to the entity page subtitle configuration:
+
+```json
+{
+  "subtitle": {
+    "text": "Default subtitle text",
+    "id": "mySubtitleOverride"
+  }
+}
+```
+
+### Subtitle Override Implementation
+
+Create a subtitle override function that returns an object with a `text` property:
+
+```typescript
+const mySubtitleOverride = (entity: Record<string, any>): { text: string } => {
+  return { text: `Pet: ${entity.name || 'Unknown'}` };
+};
+```
+
+### Complete Implementation Guide
+
+#### Step 1: Create the Subtitle Function
+
+**File**: `src/dashboard/components/entityPageHeaderSubtitle/entityPageHeaderSubtitle.ts`
+
+```typescript
+export const entityPageHeaderSubtitle = (entity: Record<string, any>): { text: string } => {
+  return { text: `Pet: ${entity.name || 'Unknown'}` };
+};
+```
+
+#### Step 2: Create/Update Index File
+
+**File**: `src/dashboard/components/entityPageHeaderSubtitle/index.ts`
+
+```typescript
+import { entityPageHeaderSubtitle } from './entityPageHeaderSubtitle';
+
+export const useEntityPageHeaderSubtitle = () => {
+  return entityPageHeaderSubtitle;
+};
+```
+
+#### Step 3: Update Main Page Overrides
+
+**File**: `src/dashboard/pages/page.tsx`
+
+```typescript
+import { useEntityPageHeaderSubtitle } from '../components/entityPageHeaderSubtitle';
+
+const Index: FC = () => {
+  const entityPageHeaderSubtitle = useEntityPageHeaderSubtitle();
+
+  return (
+    <PatternsWizardOverridesProvider
+      value={{
+        // ... other overrides
+        entityPageHeaderSubtitle: {
+          entityPageHeaderSubtitle,
+        },
+      }}
+    >
+      <WixPetsPage />
+    </PatternsWizardOverridesProvider>
+  );
+};
+```
+
+#### Step 4: Update Configuration
+
+**File**: `src/dashboard/pages/wixPetsConfig.patterns.ts`
+
+```typescript
+{
+  id: 'wixPets-entity',
+  type: 'entityPage',
+  entityPage: {
+    subtitle: {
+      text: 'Default subtitle text',
+      id: 'entityPageHeaderSubtitle', // ⚠️ CRITICAL: This must match the override key
+    },
+    // ... rest of config
+  },
+}
+```
+
+### Required File Structure
+
+```
+src/dashboard/
+├── components/
+│   └── entityPageHeaderSubtitle/
+│       ├── index.ts                    # ✅ MUST EXIST (hook exports)
+│       └── entityPageHeaderSubtitle.ts # ✅ MUST EXIST (subtitle function)
+├── pages/
+│   ├── page.tsx                        # ✅ MUST REGISTER OVERRIDES
+│   └── wixPetsConfig.patterns.ts       # ✅ MUST HAVE SUBTITLE CONFIG
+```
+
+
+**Example**:
+```typescript
+// Config
+subtitle: { id: 'mySubtitleOverride' }
+
+// Overrides
+entityPageHeaderSubtitle: { mySubtitleOverride: myFunction }
+
+// Function
+export const myFunction = (entity) => { ... }
+```
+
+### Integration
+
+Register your subtitle override in the `PatternsWizardOverridesProvider`:
+
+```typescript
+<PatternsWizardOverridesProvider value={{
+  entityPageHeaderSubtitle: {
+    mySubtitleOverride,
+  },
+}}>
+  <AutoPatternsApp configuration={config} />
+</PatternsWizardOverridesProvider>
+```
+
+## Entity Page Dynamic Badges
+
+Entity pages support dynamic badges in the page title that display contextual information about the entity.
+
+
+### Badge Skin Options
+
+The `skin` property accepts values from the `BadgeSkin` type of `@wix/design-system`:
+
+### Badge Properties
+
+Each badge can have the following properties:
+
+```typescript
+{
+  text: string;                    // Required: Text to display
+  skin?: BadgeSkin;               // Optional: Visual styling
+  prefixIcon?: React.ReactElement; // Optional: Icon before text (from @wix/wix-ui-icons-common)
+  suffixIcon?: React.ReactElement; // Optional: Icon after text (from @wix/wix-ui-icons-common)
+}
+```
+
+
+## ⚠️ **CRITICAL: Understanding Badges Implementation**
+
+When implementing badges for entity pages, understand these key points:
+
+1. **Badges are CUSTOM COMPONENT OVERRIDES** - NOT direct configuration
+2. **Badge function returns an ARRAY of badge objects** - NOT JSX components
+3. **Each badge object has properties** like `text`, `skin`, `prefixIcon`, etc.
+4. **Must be registered in PatternsWizardOverridesProvider** under `entityPageHeaderBadges`
+
+### Complete Implementation Guide
+
+#### Step 1: Create the Badge Function
+
+**File**: `src/dashboard/components/entityPageHeaderBadges/entityPageHeaderBadges.ts`
+
+```typescript
+export const entityPageHeaderBadges = (entity: Record<string, any>) => {
+  // Define available badge skins
+  const badgeSkins = ['success', 'warning', 'destructive', 'neutral', 'premium'] as const;
+
+  // Get random skins for the two badges
+  const randomSkin1 = badgeSkins[Math.floor(Math.random() * badgeSkins.length)];
+  const randomSkin2 = badgeSkins[Math.floor(Math.random() * badgeSkins.length)];
+
+  return [
+    {
+      text: 'wow',
+      skin: randomSkin1,
+    },
+    {
+      text: 'wow',
+      skin: randomSkin2,
+    },
+  ];
+};
+```
+
+#### Step 2: Create/Update Index File
+
+**File**: `src/dashboard/components/entityPageHeaderBadges/index.ts`
+
+```typescript
+import { entityPageHeaderBadges } from './entityPageHeaderBadges';
+
+export const useEntityPageHeaderBadges = () => {
+  return entityPageHeaderBadges;
+};
+```
+
+#### Step 3: Update Main Page Overrides
+
+**File**: `src/dashboard/pages/page.tsx`
+
+```typescript
+import { useEntityPageHeaderSubtitle } from '../components/entityPageHeaderSubtitle';
+import { useEntityPageHeaderBadges } from '../components/entityPageHeaderBadges';
+
+const Index: FC = () => {
+  const entityPageHeaderSubtitle = useEntityPageHeaderSubtitle();
+  const entityPageHeaderBadges = useEntityPageHeaderBadges();
+
+  return (
+    <PatternsWizardOverridesProvider
+      value={{
+        // ... other overrides
+        entityPageHeaderSubtitle: {
+          entityPageHeaderSubtitle,
+        },
+        entityPageHeaderBadges: {
+          entityPageHeaderBadges, // ⚠️ CRITICAL: This must match the ID in config
+        },
+      }}
+    >
+      <WixPetsPage />
+    </PatternsWizardOverridesProvider>
+  );
+};
+```
+
+#### Step 4: Update Configuration
+
+**File**: `src/dashboard/pages/wixPetsConfig.patterns.ts`
+
+```typescript
+{
+  id: 'wixPets-entity',
+  type: 'entityPage',
+  entityPage: {
+    title: {
+      text: 'WixPet Details',
+      badges: {
+        id: 'entityPageHeaderBadges', // ⚠️ CRITICAL: This must match the override key
+      },
+    },
+    // ... rest of config
+  },
+}
+```
+
+### Required File Structure
+
+```
+src/dashboard/
+├── components/
+│   └── entityPageHeaderBadges/
+│       ├── index.ts                    # ✅ MUST EXIST (badges hook exports)
+│       └── entityPageHeaderBadges.ts   # ✅ MUST EXIST (badges function)
+├── pages/
+│   ├── page.tsx                        # ✅ MUST REGISTER OVERRIDES
+│   └── wixPetsConfig.patterns.ts       # ✅ MUST HAVE BADGES CONFIG
+```
+
+### ⚠️ **Common Badges Mistakes to Avoid**
+
+1. **❌ DON'T return JSX components** - Return badge objects instead
+2. **❌ DON'T use direct configuration** - Use custom component overrides
+3. **❌ DON'T forget to register in PatternsWizardOverridesProvider**
+5. **❌ DON'T forget to export from index.ts** - Must export the function
+
+
+
 ## View Mode: Purpose and API
 
 ### Purpose of View Mode
@@ -2104,7 +2400,7 @@ Entity page action configuration depends on the mode:
    - 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
+## Common Entity Page Layout Mistakes to Avoid
 
 - Using incorrect span values causing unexpected layout breaks
 - Referencing non-existent field IDs in the layout
@@ -2358,13 +2654,36 @@ export const duplicateProduct: CustomEntityPageActionResolver = (params) => {
 
 ## 1. Install Packages
 
-Install if necessary and doesn't exists in package.json:
+Install if doesn't exists in package.json:
 
 ```bash
 npm install @wix/auto-patterns @wix/patterns @wix/design-system
 ```
 
-## ⚠️ Critical Import Rules
+### React Router dependency
+
+`react-router-dom` is required. Install a version that matches your React version:
+
+- React 16.x (and 17.x): use `react-router-dom@^6`
+- React 18+ : use `react-router-dom@^7`
+
+Check your React version:
+
+```bash
+npm ls react --depth=0
+```
+
+Then install the matching router version:
+
+```bash
+# For React 16.x or 17.x
+npm install react-router-dom@^6
+
+# For React 18+
+npm install react-router-dom@^7
+```
+
+## Critical Import Rules
 
 - **Import `AutoPatternsApp` only from `@wix/auto-patterns`** - never from other packages
 - **CRITICAL:** Always import `AppConfig` as a type import: `import type { AppConfig } from '@wix/auto-patterns/types'` - never import it as a value import
@@ -2413,7 +2732,7 @@ export default withDashboard(Index);
 
 # Custom Overrides
 
-## ⚠️ Override Rules
+## 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`
@@ -2455,9 +2774,15 @@ your-page/
     ├── customDataSources/             // Custom data sources
     │   ├── index.tsx                  // Exports useCustomDataSources hook
     │   └── myCustomDataSource.ts
-    └── sections/                      // Section renderers
-        ├── index.tsx
-        └── groupByType.ts
+    ├── sections/                      // Section renderers
+    │   ├── index.tsx
+    │   └── groupByType.ts
+    ├── entityPageHeaderSubtitle/      // Entity page dynamic subtitle functions
+    │   ├── index.tsx                  // Exports useEntityPageHeaderSubtitle hook
+    │   └── mySubtitle.ts
+    └── entityPageHeaderBadges/        // Entity page dynamic badges functions
+        ├── index.tsx                  // Exports useEntityPageHeaderBadges hook
+        └── myBadges.ts
 ```
 
 ### Using Override Hooks in Your Page
@@ -2472,6 +2797,8 @@ import { useSections } from '../components/sections';
 import { useComponents } from '../components/customComponents';
 import { useModals } from '../components/modals';
 import { useCustomDataSources } from '../components/customDataSources';
+import { useEntityPageHeaderSubtitle } from '../components/entityPageHeaderSubtitle';
+import { useEntityPageHeaderBadges } from '../components/entityPageHeaderBadges';
 
 export default function YourPage() {
   const actions = useActions();
@@ -2481,9 +2808,11 @@ export default function YourPage() {
   const components = useComponents();
   const modals = useModals();
   const customDataSources = useCustomDataSources();
+  const entityPageHeaderSubtitle = useEntityPageHeaderSubtitle();
+  const entityPageHeaderBadges = useEntityPageHeaderBadges();
 
   return (
-    <PatternsWizardOverridesProvider value={{ actions, columns, slots, sections, components, modals, customDataSources }}>
+    <PatternsWizardOverridesProvider value={{ actions, columns, slots, sections, components, modals, customDataSources, entityPageHeaderSubtitle, entityPageHeaderBadges }}>
       <AutoPatternsApp configuration={config} />
     </PatternsWizardOverridesProvider>
   );
@@ -2502,10 +2831,12 @@ For example:
 - Adding a new section renderer → Update `../components/sections/index.tsx` to include the new section in the `useSections` hook
 - Adding a new custom component → Update `../components/customComponents/index.tsx` to include the new component in the `useComponents` hook
 - Adding a new custom data source → Update `../components/customDataSources/index.tsx` to include the new data source in the `useCustomDataSources` hook
+- Adding a new subtitle override → Update `../components/entityPageHeaderSubtitle/index.tsx` to include the new subtitle in the `useEntityPageHeaderSubtitle` hook
+- Adding a new badges override → Update `../components/entityPageHeaderBadges/index.tsx` to include the new badges in the `useEntityPageHeaderBadges` hook
 
 Without updating the hook index files, your implementations won't be available to the `PatternsWizardOverridesProvider`.
 
-## ⚠️ Common Override Mistakes to Avoid
+## Common Override Mistakes to Avoid
 
 - Attempting to override unsupported areas
 - Invalid column rendering functions

package/dist/docs/collection_page.md

@@ -1,6 +1,6 @@
 # Collection Page Configuration
 
-## ⚠️ Collection Page Rules
+## Collection Page Rules
 
 - **Components array inside collectionPage must contain exactly one component with a layout array**
 - **All collection pages with tables/grids must reference their corresponding entity page via `entityPageId`** in the collection configuration

package/dist/docs/collection_page_actions.md

@@ -1,6 +1,6 @@
 # Collection Page Actions
 
-## ⚠️ Required Actions
+## Required Actions
 
 - **Every collection page must include a create action that navigates to the entity page for adding new entities** - this is essential for user workflow
 

package/dist/docs/custom_overrides.md

@@ -1,6 +1,6 @@
 # Custom Overrides
 
-## ⚠️ Override Rules
+## 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`
@@ -42,9 +42,15 @@ your-page/
     ├── customDataSources/             // Custom data sources
     │   ├── index.tsx                  // Exports useCustomDataSources hook
     │   └── myCustomDataSource.ts
-    └── sections/                      // Section renderers
-        ├── index.tsx
-        └── groupByType.ts
+    ├── sections/                      // Section renderers
+    │   ├── index.tsx
+    │   └── groupByType.ts
+    ├── entityPageHeaderSubtitle/      // Entity page dynamic subtitle functions
+    │   ├── index.tsx                  // Exports useEntityPageHeaderSubtitle hook
+    │   └── mySubtitle.ts
+    └── entityPageHeaderBadges/        // Entity page dynamic badges functions
+        ├── index.tsx                  // Exports useEntityPageHeaderBadges hook
+        └── myBadges.ts
 ```
 
 ### Using Override Hooks in Your Page
@@ -59,6 +65,8 @@ import { useSections } from '../components/sections';
 import { useComponents } from '../components/customComponents';
 import { useModals } from '../components/modals';
 import { useCustomDataSources } from '../components/customDataSources';
+import { useEntityPageHeaderSubtitle } from '../components/entityPageHeaderSubtitle';
+import { useEntityPageHeaderBadges } from '../components/entityPageHeaderBadges';
 
 export default function YourPage() {
   const actions = useActions();
@@ -68,9 +76,11 @@ export default function YourPage() {
   const components = useComponents();
   const modals = useModals();
   const customDataSources = useCustomDataSources();
+  const entityPageHeaderSubtitle = useEntityPageHeaderSubtitle();
+  const entityPageHeaderBadges = useEntityPageHeaderBadges();
 
   return (
-    <PatternsWizardOverridesProvider value={{ actions, columns, slots, sections, components, modals, customDataSources }}>
+    <PatternsWizardOverridesProvider value={{ actions, columns, slots, sections, components, modals, customDataSources, entityPageHeaderSubtitle, entityPageHeaderBadges }}>
       <AutoPatternsApp configuration={config} />
     </PatternsWizardOverridesProvider>
   );
@@ -89,10 +99,12 @@ For example:
 - Adding a new section renderer → Update `../components/sections/index.tsx` to include the new section in the `useSections` hook
 - Adding a new custom component → Update `../components/customComponents/index.tsx` to include the new component in the `useComponents` hook
 - Adding a new custom data source → Update `../components/customDataSources/index.tsx` to include the new data source in the `useCustomDataSources` hook
+- Adding a new subtitle override → Update `../components/entityPageHeaderSubtitle/index.tsx` to include the new subtitle in the `useEntityPageHeaderSubtitle` hook
+- Adding a new badges override → Update `../components/entityPageHeaderBadges/index.tsx` to include the new badges in the `useEntityPageHeaderBadges` hook
 
 Without updating the hook index files, your implementations won't be available to the `PatternsWizardOverridesProvider`.
 
-## ⚠️ Common Override Mistakes to Avoid
+## Common Override Mistakes to Avoid
 
 - Attempting to override unsupported areas
 - Invalid column rendering functions