@wix/auto-patterns 1.24.0 → 1.26.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. package/dist/cjs/components/AutoPatternsEntityPage/EditModeEntityPage.js +10 -9
  2. package/dist/cjs/components/AutoPatternsEntityPage/EditModeEntityPage.js.map +1 -1
  3. package/dist/cjs/components/AutoPatternsEntityPage/ViewModeEntityPage.js +90 -36
  4. package/dist/cjs/components/AutoPatternsEntityPage/ViewModeEntityPage.js.map +1 -1
  5. package/dist/cjs/dataSourceAdapters/cms/cmsAdapter.js +2 -1
  6. package/dist/cjs/dataSourceAdapters/cms/cmsAdapter.js.map +1 -1
  7. package/dist/cjs/hooks/useActionCell.js +2 -1
  8. package/dist/cjs/hooks/useActionCell.js.map +1 -1
  9. package/dist/cjs/hooks/useBulkActionToolbar.js +2 -1
  10. package/dist/cjs/hooks/useBulkActionToolbar.js.map +1 -1
  11. package/dist/cjs/hooks/useCollectionPageActions.js +2 -1
  12. package/dist/cjs/hooks/useCollectionPageActions.js.map +1 -1
  13. package/dist/cjs/hooks/useEntityPageActions.js +2 -1
  14. package/dist/cjs/hooks/useEntityPageActions.js.map +1 -1
  15. package/dist/cjs/hooks/useEntityPageHeaderTexts.js +48 -9
  16. package/dist/cjs/hooks/useEntityPageHeaderTexts.js.map +1 -1
  17. package/dist/cjs/hooks/useEntityPageMoreActions.js +1 -1
  18. package/dist/cjs/hooks/useEntityPageMoreActions.js.map +1 -1
  19. package/dist/cjs/providers/ErrorContext.js +6 -3
  20. package/dist/cjs/providers/ErrorContext.js.map +1 -1
  21. package/dist/cjs/providers/PatternsWizardOverridesContext.js +1 -1
  22. package/dist/cjs/providers/PatternsWizardOverridesContext.js.map +1 -1
  23. package/dist/cjs/types/EntityPageConfig.js.map +1 -1
  24. package/dist/cjs/types/actions/actionCell.js.map +1 -1
  25. package/dist/cjs/utils/actions/types.js.map +1 -1
  26. package/dist/docs/action_cell.md +5 -4
  27. package/dist/docs/app_config_structure.md +6 -2
  28. package/dist/docs/auto-patterns-guide.md +353 -20
  29. package/dist/docs/bulk_actions.md +1 -0
  30. package/dist/docs/collection_page.md +1 -1
  31. package/dist/docs/collection_page_actions.md +1 -1
  32. package/dist/docs/custom_overrides.md +18 -6
  33. package/dist/docs/entity_page.md +294 -2
  34. package/dist/docs/index.md +8 -0
  35. package/dist/docs/installation.md +25 -2
  36. package/dist/docs/pages_configuration.md +2 -2
  37. package/dist/esm/components/AutoPatternsEntityPage/EditModeEntityPage.js +2 -1
  38. package/dist/esm/components/AutoPatternsEntityPage/EditModeEntityPage.js.map +1 -1
  39. package/dist/esm/components/AutoPatternsEntityPage/ViewModeEntityPage.js +47 -18
  40. package/dist/esm/components/AutoPatternsEntityPage/ViewModeEntityPage.js.map +1 -1
  41. package/dist/esm/dataSourceAdapters/cms/cmsAdapter.js +2 -1
  42. package/dist/esm/dataSourceAdapters/cms/cmsAdapter.js.map +1 -1
  43. package/dist/esm/hooks/useActionCell.js +2 -1
  44. package/dist/esm/hooks/useActionCell.js.map +1 -1
  45. package/dist/esm/hooks/useBulkActionToolbar.js +2 -1
  46. package/dist/esm/hooks/useBulkActionToolbar.js.map +1 -1
  47. package/dist/esm/hooks/useCollectionPageActions.js +2 -1
  48. package/dist/esm/hooks/useCollectionPageActions.js.map +1 -1
  49. package/dist/esm/hooks/useEntityPageActions.js +2 -1
  50. package/dist/esm/hooks/useEntityPageActions.js.map +1 -1
  51. package/dist/esm/hooks/useEntityPageHeaderTexts.js +48 -9
  52. package/dist/esm/hooks/useEntityPageHeaderTexts.js.map +1 -1
  53. package/dist/esm/hooks/useEntityPageMoreActions.js +1 -1
  54. package/dist/esm/hooks/useEntityPageMoreActions.js.map +1 -1
  55. package/dist/esm/providers/ErrorContext.js +4 -1
  56. package/dist/esm/providers/ErrorContext.js.map +1 -1
  57. package/dist/esm/providers/PatternsWizardOverridesContext.js.map +1 -1
  58. package/dist/esm/types/EntityPageConfig.js.map +1 -1
  59. package/dist/esm/types/actions/actionCell.js.map +1 -1
  60. package/dist/esm/utils/actions/types.js.map +1 -1
  61. package/dist/types/components/AutoPatternsEntityPage/EditModeEntityPage.d.ts.map +1 -1
  62. package/dist/types/components/AutoPatternsEntityPage/ViewModeEntityPage.d.ts.map +1 -1
  63. package/dist/types/dataSourceAdapters/cms/cmsAdapter.d.ts.map +1 -1
  64. package/dist/types/hooks/useActionCell.d.ts.map +1 -1
  65. package/dist/types/hooks/useEntityPageHeaderTexts.d.ts +10 -1
  66. package/dist/types/hooks/useEntityPageHeaderTexts.d.ts.map +1 -1
  67. package/dist/types/providers/ErrorContext.d.ts +7 -0
  68. package/dist/types/providers/ErrorContext.d.ts.map +1 -1
  69. package/dist/types/providers/PatternsWizardOverridesContext.d.ts +12 -2
  70. package/dist/types/providers/PatternsWizardOverridesContext.d.ts.map +1 -1
  71. package/dist/types/types/EntityPageConfig.d.ts +5 -1
  72. package/dist/types/types/EntityPageConfig.d.ts.map +1 -1
  73. package/dist/types/types/actions/actionCell.d.ts +7 -1
  74. package/dist/types/types/actions/actionCell.d.ts.map +1 -1
  75. package/dist/types/utils/actions/customAction.d.ts +1 -1
  76. package/dist/types/utils/actions/customAction.d.ts.map +1 -1
  77. package/dist/types/utils/actions/resolveAction.d.ts +1 -0
  78. package/dist/types/utils/actions/resolveAction.d.ts.map +1 -1
  79. package/dist/types/utils/actions/types.d.ts +1 -0
  80. package/dist/types/utils/actions/types.d.ts.map +1 -1
  81. package/package.json +17 -16
@@ -78,7 +78,7 @@ It is configured using a TypeScript file conforming to the `AppConfig` interface
78
78
 
79
79
  # AppConfig Structure
80
80
 
81
- ## ⚠️ Configuration Rules
81
+ ## Configuration Rules
82
82
 
83
83
  - **Configuration must come only from a TypeScript file** - never inline or from other sources
84
84
  - **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
86
86
  - **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
87
87
  - **When generating config for the first time, select up to 3 columns from the schema that best represent the entity**
88
88
 
89
- ## ⚠️ Common Configuration Mistakes to Avoid
89
+ ## Common Configuration Mistakes to Avoid
90
90
 
91
91
  - Adding more than two pages
92
92
  - Mixing page types in a single configuration
@@ -392,9 +392,13 @@ export interface AppConfig {
392
392
  };
393
393
  title?: {
394
394
  text: string; // Entity page title
395
+ badges?: {
396
+ id?: string; // Optional ID that maps to a dynamic badges override function
397
+ };
395
398
  };
396
399
  subtitle?: {
397
400
  text: string; // Entity page subtitle
401
+ id?: string; // Optional ID that maps to a dynamic subtitle override function
398
402
  };
399
403
  actions?: { // Action configuration varies by mode
400
404
  // Edit mode: only moreActions supported
@@ -556,7 +560,7 @@ Notice how the `label` is derived from the `value` by capitalizing the first let
556
560
 
557
561
  # Pages Configuration
558
562
 
559
- ## ⚠️ Critical Page Rules
563
+ ## Critical Page Rules
560
564
 
561
565
  - **Pages array must contain exactly two pages** - one collectionPage and one entityPage
562
566
  - **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
637
641
  * **Route Structure**: Entity pages must use `/[segment]/:entityId` format (e.g., `/product/:entityId` or `/pets/:entityId`), never just `/:entityId`
638
642
  * **Route Parameters Configuration**: All entity pages must have both a dynamic parameter in `route.path` and a matching configuration in `route.params`
639
643
 
640
- ## ⚠️ Common Route and Configuration Mistakes to Avoid
644
+ ## Common Route and Configuration Mistakes to Avoid
641
645
 
642
646
  - Missing route.params for entity pages
643
647
  - 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
678
682
 
679
683
  # Collection Page Configuration
680
684
 
681
- ## ⚠️ Collection Page Rules
685
+ ## Collection Page Rules
682
686
 
683
687
  - **Components array inside collectionPage must contain exactly one component with a layout array**
684
688
  - **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
735
739
 
736
740
  # Collection Page Actions
737
741
 
738
- ## ⚠️ Required Actions
742
+ ## Required Actions
739
743
 
740
744
  - **Every collection page must include a create action that navigates to the entity page for adding new entities** - this is essential for user workflow
741
745
 
@@ -1510,12 +1514,12 @@ Custom actions execute JavaScript code that you define. These actions receive pa
1510
1514
 
1511
1515
  2. Create your action handler in `downloadPetDetails.tsx` (note: the filename and function name MUST match your action id):
1512
1516
  ```typescript
1513
- import { CustomActionCellActionResolver } from '@wix/auto-patterns';
1517
+ import { CustomActionCellSecondaryActionResolver } from '@wix/auto-patterns';
1514
1518
  import { Download } from '@wix/wix-ui-icons-common';
1515
1519
  import React from 'react';
1516
1520
 
1517
1521
  // IMPORTANT: Function name MUST match the action id in your configuration
1518
- export const downloadPetDetails: CustomActionCellActionResolver = (params) => {
1522
+ export const downloadPetDetails: CustomActionCellSecondaryActionResolver = (params) => {
1519
1523
  const { actionParams, sdk } = params;
1520
1524
  const { item } = actionParams;
1521
1525
 
@@ -1591,7 +1595,7 @@ Custom actions execute JavaScript code that you define. These actions receive pa
1591
1595
  - The action `id` in the configuration MUST exactly match the function name exported from your actions folder
1592
1596
  - The function name and file name should follow a consistent naming convention (e.g., camelCase)
1593
1597
  - The implementation must be exported as a named export (not default export)
1594
- - The implementation must use the `CustomActionCellActionResolver` type
1598
+ - The implementation must use either `CustomActionCellPrimaryActionResolver` or `CustomActionCellSecondaryActionResolver` type depending on your use case
1595
1599
 
1596
1600
  #### Validation Rules for Custom Actions:
1597
1601
 
@@ -1604,9 +1608,10 @@ Custom actions execute JavaScript code that you define. These actions receive pa
1604
1608
  - `label`: Text displayed for the action
1605
1609
  - `icon`: An Icon component from "@wix/wix-ui-icons-common"
1606
1610
  - `onClick`: Handler function for the action
1611
+ - `hidden` (optional): Boolean to hide the action when true
1607
1612
 
1608
1613
  3. The implementation must:
1609
- - Use the correct type: `CustomActionCellActionResolver`
1614
+ - Use the correct type: `CustomActionCellPrimaryActionResolver` for primary actions (with prefixIcon/suffixIcon) or `CustomActionCellSecondaryActionResolver` for secondary actions (with icon)
1610
1615
  - Be exported as a named export
1611
1616
  - Have a filename matching the function name
1612
1617
 
@@ -1842,6 +1847,7 @@ Custom bulk actions execute JavaScript code that you define for bulk operations.
1842
1847
  - `label`: Text displayed for the action
1843
1848
  - `icon`: An Icon component from "@wix/wix-ui-icons-common"
1844
1849
  - `onClick`: Handler function for the bulk action
1850
+ - `hidden` (optional): Boolean to hide the action when true
1845
1851
 
1846
1852
  3. The implementation must:
1847
1853
  - Use the correct type: `CustomBulkActionsActionResolver`
@@ -1947,7 +1953,7 @@ AI agents should verify these requirements before generating Bulk Action Toolbar
1947
1953
 
1948
1954
  # Entity Page Configuration
1949
1955
 
1950
- ## ⚠️ Entity Page Requirements
1956
+ ## Entity Page Requirements
1951
1957
 
1952
1958
  All entity pages must have:
1953
1959
  - **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
@@ -1959,6 +1965,20 @@ All entity pages must have:
1959
1965
  * Displays details for a **single entity**.
1960
1966
  * Always tied to a single Wix collection.
1961
1967
  * Supports **two distinct modes**: **view mode** and **edit mode** with separate page configurations.
1968
+ * Supports **dynamic subtitle** that adapt based on entity data (see [Entity Page Dynamic Subtitle](#entity-page-dynamic-subtitle)).
1969
+ * Supports **dynamic badges** in the page title that adapt based on entity data (see [Entity Page Dynamic Badges](#entity-page-dynamic-badges)).
1970
+
1971
+ ## 🏷️ **Understanding Badges Requests**
1972
+
1973
+ When a user asks to "add badges to the entity page", understand that they want:
1974
+
1975
+ 1. **Custom component overrides** - NOT direct configuration in JSON
1976
+ 2. **Function that returns badge objects** - NOT JSX components
1977
+ 3. **Badge properties** like `text`, `skin`, `prefixIcon`, etc.
1978
+ 4. **Registration in PatternsWizardOverridesProvider** under `entityPageHeaderBadges`
1979
+
1980
+ **Example Request**: "Add 2 badges with random skins and text 'wow'"
1981
+ **Correct Implementation**: Create a function that returns `[{text: 'wow', skin: 'success'}, {text: 'wow', skin: 'premium'}]`
1962
1982
 
1963
1983
  ## Entity Page Modes
1964
1984
 
@@ -1987,6 +2007,284 @@ This pattern allows:
1987
2007
  - Clear distinction between view and edit URLs
1988
2008
  - Natural navigation flow between modes
1989
2009
 
2010
+ ## Entity Page Dynamic Subtitle
2011
+
2012
+ Entity pages support dynamic subtitles that adapt based on entity data, providing contextual information below the main title.
2013
+
2014
+ ### Configuration
2015
+
2016
+ Add an `id` property to the entity page subtitle configuration:
2017
+
2018
+ ```json
2019
+ {
2020
+ "subtitle": {
2021
+ "text": "Default subtitle text",
2022
+ "id": "mySubtitleOverride"
2023
+ }
2024
+ }
2025
+ ```
2026
+
2027
+ ### Subtitle Override Implementation
2028
+
2029
+ Create a subtitle override function that returns an object with a `text` property:
2030
+
2031
+ ```typescript
2032
+ const mySubtitleOverride = (entity: Record<string, any>): { text: string } => {
2033
+ return { text: `Pet: ${entity.name || 'Unknown'}` };
2034
+ };
2035
+ ```
2036
+
2037
+ ### Complete Implementation Guide
2038
+
2039
+ #### Step 1: Create the Subtitle Function
2040
+
2041
+ **File**: `src/dashboard/components/entityPageHeaderSubtitle/entityPageHeaderSubtitle.ts`
2042
+
2043
+ ```typescript
2044
+ export const entityPageHeaderSubtitle = (entity: Record<string, any>): { text: string } => {
2045
+ return { text: `Pet: ${entity.name || 'Unknown'}` };
2046
+ };
2047
+ ```
2048
+
2049
+ #### Step 2: Create/Update Index File
2050
+
2051
+ **File**: `src/dashboard/components/entityPageHeaderSubtitle/index.ts`
2052
+
2053
+ ```typescript
2054
+ import { entityPageHeaderSubtitle } from './entityPageHeaderSubtitle';
2055
+
2056
+ export const useEntityPageHeaderSubtitle = () => {
2057
+ return entityPageHeaderSubtitle;
2058
+ };
2059
+ ```
2060
+
2061
+ #### Step 3: Update Main Page Overrides
2062
+
2063
+ **File**: `src/dashboard/pages/page.tsx`
2064
+
2065
+ ```typescript
2066
+ import { useEntityPageHeaderSubtitle } from '../components/entityPageHeaderSubtitle';
2067
+
2068
+ const Index: FC = () => {
2069
+ const entityPageHeaderSubtitle = useEntityPageHeaderSubtitle();
2070
+
2071
+ return (
2072
+ <PatternsWizardOverridesProvider
2073
+ value={{
2074
+ // ... other overrides
2075
+ entityPageHeaderSubtitle: {
2076
+ entityPageHeaderSubtitle,
2077
+ },
2078
+ }}
2079
+ >
2080
+ <WixPetsPage />
2081
+ </PatternsWizardOverridesProvider>
2082
+ );
2083
+ };
2084
+ ```
2085
+
2086
+ #### Step 4: Update Configuration
2087
+
2088
+ **File**: `src/dashboard/pages/wixPetsConfig.patterns.ts`
2089
+
2090
+ ```typescript
2091
+ {
2092
+ id: 'wixPets-entity',
2093
+ type: 'entityPage',
2094
+ entityPage: {
2095
+ subtitle: {
2096
+ text: 'Default subtitle text',
2097
+ id: 'entityPageHeaderSubtitle', // ⚠️ CRITICAL: This must match the override key
2098
+ },
2099
+ // ... rest of config
2100
+ },
2101
+ }
2102
+ ```
2103
+
2104
+ ### Required File Structure
2105
+
2106
+ ```
2107
+ src/dashboard/
2108
+ ├── components/
2109
+ │ └── entityPageHeaderSubtitle/
2110
+ │ ├── index.ts # ✅ MUST EXIST (hook exports)
2111
+ │ └── entityPageHeaderSubtitle.ts # ✅ MUST EXIST (subtitle function)
2112
+ ├── pages/
2113
+ │ ├── page.tsx # ✅ MUST REGISTER OVERRIDES
2114
+ │ └── wixPetsConfig.patterns.ts # ✅ MUST HAVE SUBTITLE CONFIG
2115
+ ```
2116
+
2117
+
2118
+ **Example**:
2119
+ ```typescript
2120
+ // Config
2121
+ subtitle: { id: 'mySubtitleOverride' }
2122
+
2123
+ // Overrides
2124
+ entityPageHeaderSubtitle: { mySubtitleOverride: myFunction }
2125
+
2126
+ // Function
2127
+ export const myFunction = (entity) => { ... }
2128
+ ```
2129
+
2130
+ ### Integration
2131
+
2132
+ Register your subtitle override in the `PatternsWizardOverridesProvider`:
2133
+
2134
+ ```typescript
2135
+ <PatternsWizardOverridesProvider value={{
2136
+ entityPageHeaderSubtitle: {
2137
+ mySubtitleOverride,
2138
+ },
2139
+ }}>
2140
+ <AutoPatternsApp configuration={config} />
2141
+ </PatternsWizardOverridesProvider>
2142
+ ```
2143
+
2144
+ ## Entity Page Dynamic Badges
2145
+
2146
+ Entity pages support dynamic badges in the page title that display contextual information about the entity.
2147
+
2148
+
2149
+ ### Badge Skin Options
2150
+
2151
+ The `skin` property accepts values from the `BadgeSkin` type of `@wix/design-system`:
2152
+
2153
+ ### Badge Properties
2154
+
2155
+ Each badge can have the following properties:
2156
+
2157
+ ```typescript
2158
+ {
2159
+ text: string; // Required: Text to display
2160
+ skin?: BadgeSkin; // Optional: Visual styling
2161
+ prefixIcon?: React.ReactElement; // Optional: Icon before text (from @wix/wix-ui-icons-common)
2162
+ suffixIcon?: React.ReactElement; // Optional: Icon after text (from @wix/wix-ui-icons-common)
2163
+ }
2164
+ ```
2165
+
2166
+
2167
+ ## ⚠️ **CRITICAL: Understanding Badges Implementation**
2168
+
2169
+ When implementing badges for entity pages, understand these key points:
2170
+
2171
+ 1. **Badges are CUSTOM COMPONENT OVERRIDES** - NOT direct configuration
2172
+ 2. **Badge function returns an ARRAY of badge objects** - NOT JSX components
2173
+ 3. **Each badge object has properties** like `text`, `skin`, `prefixIcon`, etc.
2174
+ 4. **Must be registered in PatternsWizardOverridesProvider** under `entityPageHeaderBadges`
2175
+
2176
+ ### Complete Implementation Guide
2177
+
2178
+ #### Step 1: Create the Badge Function
2179
+
2180
+ **File**: `src/dashboard/components/entityPageHeaderBadges/entityPageHeaderBadges.ts`
2181
+
2182
+ ```typescript
2183
+ export const entityPageHeaderBadges = (entity: Record<string, any>) => {
2184
+ // Define available badge skins
2185
+ const badgeSkins = ['success', 'warning', 'destructive', 'neutral', 'premium'] as const;
2186
+
2187
+ // Get random skins for the two badges
2188
+ const randomSkin1 = badgeSkins[Math.floor(Math.random() * badgeSkins.length)];
2189
+ const randomSkin2 = badgeSkins[Math.floor(Math.random() * badgeSkins.length)];
2190
+
2191
+ return [
2192
+ {
2193
+ text: 'wow',
2194
+ skin: randomSkin1,
2195
+ },
2196
+ {
2197
+ text: 'wow',
2198
+ skin: randomSkin2,
2199
+ },
2200
+ ];
2201
+ };
2202
+ ```
2203
+
2204
+ #### Step 2: Create/Update Index File
2205
+
2206
+ **File**: `src/dashboard/components/entityPageHeaderBadges/index.ts`
2207
+
2208
+ ```typescript
2209
+ import { entityPageHeaderBadges } from './entityPageHeaderBadges';
2210
+
2211
+ export const useEntityPageHeaderBadges = () => {
2212
+ return entityPageHeaderBadges;
2213
+ };
2214
+ ```
2215
+
2216
+ #### Step 3: Update Main Page Overrides
2217
+
2218
+ **File**: `src/dashboard/pages/page.tsx`
2219
+
2220
+ ```typescript
2221
+ import { useEntityPageHeaderSubtitle } from '../components/entityPageHeaderSubtitle';
2222
+ import { useEntityPageHeaderBadges } from '../components/entityPageHeaderBadges';
2223
+
2224
+ const Index: FC = () => {
2225
+ const entityPageHeaderSubtitle = useEntityPageHeaderSubtitle();
2226
+ const entityPageHeaderBadges = useEntityPageHeaderBadges();
2227
+
2228
+ return (
2229
+ <PatternsWizardOverridesProvider
2230
+ value={{
2231
+ // ... other overrides
2232
+ entityPageHeaderSubtitle: {
2233
+ entityPageHeaderSubtitle,
2234
+ },
2235
+ entityPageHeaderBadges: {
2236
+ entityPageHeaderBadges, // ⚠️ CRITICAL: This must match the ID in config
2237
+ },
2238
+ }}
2239
+ >
2240
+ <WixPetsPage />
2241
+ </PatternsWizardOverridesProvider>
2242
+ );
2243
+ };
2244
+ ```
2245
+
2246
+ #### Step 4: Update Configuration
2247
+
2248
+ **File**: `src/dashboard/pages/wixPetsConfig.patterns.ts`
2249
+
2250
+ ```typescript
2251
+ {
2252
+ id: 'wixPets-entity',
2253
+ type: 'entityPage',
2254
+ entityPage: {
2255
+ title: {
2256
+ text: 'WixPet Details',
2257
+ badges: {
2258
+ id: 'entityPageHeaderBadges', // ⚠️ CRITICAL: This must match the override key
2259
+ },
2260
+ },
2261
+ // ... rest of config
2262
+ },
2263
+ }
2264
+ ```
2265
+
2266
+ ### Required File Structure
2267
+
2268
+ ```
2269
+ src/dashboard/
2270
+ ├── components/
2271
+ │ └── entityPageHeaderBadges/
2272
+ │ ├── index.ts # ✅ MUST EXIST (badges hook exports)
2273
+ │ └── entityPageHeaderBadges.ts # ✅ MUST EXIST (badges function)
2274
+ ├── pages/
2275
+ │ ├── page.tsx # ✅ MUST REGISTER OVERRIDES
2276
+ │ └── wixPetsConfig.patterns.ts # ✅ MUST HAVE BADGES CONFIG
2277
+ ```
2278
+
2279
+ ### ⚠️ **Common Badges Mistakes to Avoid**
2280
+
2281
+ 1. **❌ DON'T return JSX components** - Return badge objects instead
2282
+ 2. **❌ DON'T use direct configuration** - Use custom component overrides
2283
+ 3. **❌ DON'T forget to register in PatternsWizardOverridesProvider**
2284
+ 5. **❌ DON'T forget to export from index.ts** - Must export the function
2285
+
2286
+
2287
+
1990
2288
  ## View Mode: Purpose and API
1991
2289
 
1992
2290
  ### Purpose of View Mode
@@ -2102,7 +2400,7 @@ Entity page action configuration depends on the mode:
2102
2400
  - For image fields, consider providing more space (larger span)
2103
2401
  - Images are automatically rendered with proper controls when using the field type
2104
2402
 
2105
- ## ⚠️ Common Entity Page Layout Mistakes to Avoid
2403
+ ## Common Entity Page Layout Mistakes to Avoid
2106
2404
 
2107
2405
  - Using incorrect span values causing unexpected layout breaks
2108
2406
  - Referencing non-existent field IDs in the layout
@@ -2356,13 +2654,36 @@ export const duplicateProduct: CustomEntityPageActionResolver = (params) => {
2356
2654
 
2357
2655
  ## 1. Install Packages
2358
2656
 
2359
- Install if necessary and doesn't exists in package.json:
2657
+ Install if doesn't exists in package.json:
2360
2658
 
2361
2659
  ```bash
2362
2660
  npm install @wix/auto-patterns @wix/patterns @wix/design-system
2363
2661
  ```
2364
2662
 
2365
- ## ⚠️ Critical Import Rules
2663
+ ### React Router dependency
2664
+
2665
+ `react-router-dom` is required. Install a version that matches your React version:
2666
+
2667
+ - React 16.x (and 17.x): use `react-router-dom@^6`
2668
+ - React 18+ : use `react-router-dom@^7`
2669
+
2670
+ Check your React version:
2671
+
2672
+ ```bash
2673
+ npm ls react --depth=0
2674
+ ```
2675
+
2676
+ Then install the matching router version:
2677
+
2678
+ ```bash
2679
+ # For React 16.x or 17.x
2680
+ npm install react-router-dom@^6
2681
+
2682
+ # For React 18+
2683
+ npm install react-router-dom@^7
2684
+ ```
2685
+
2686
+ ## Critical Import Rules
2366
2687
 
2367
2688
  - **Import `AutoPatternsApp` only from `@wix/auto-patterns`** - never from other packages
2368
2689
  - **CRITICAL:** Always import `AppConfig` as a type import: `import type { AppConfig } from '@wix/auto-patterns/types'` - never import it as a value import
@@ -2411,7 +2732,7 @@ export default withDashboard(Index);
2411
2732
 
2412
2733
  # Custom Overrides
2413
2734
 
2414
- ## ⚠️ Override Rules
2735
+ ## Override Rules
2415
2736
 
2416
2737
  - **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
2417
2738
  - **Always verify override implementation** - when implementing custom overrides, you MUST ensure they are correctly imported and passed to the `PatternsWizardOverridesProvider`
@@ -2453,9 +2774,15 @@ your-page/
2453
2774
  ├── customDataSources/ // Custom data sources
2454
2775
  │ ├── index.tsx // Exports useCustomDataSources hook
2455
2776
  │ └── myCustomDataSource.ts
2456
- └── sections/ // Section renderers
2457
- ├── index.tsx
2458
- └── groupByType.ts
2777
+ ├── sections/ // Section renderers
2778
+ ├── index.tsx
2779
+ └── groupByType.ts
2780
+ ├── entityPageHeaderSubtitle/ // Entity page dynamic subtitle functions
2781
+ │ ├── index.tsx // Exports useEntityPageHeaderSubtitle hook
2782
+ │ └── mySubtitle.ts
2783
+ └── entityPageHeaderBadges/ // Entity page dynamic badges functions
2784
+ ├── index.tsx // Exports useEntityPageHeaderBadges hook
2785
+ └── myBadges.ts
2459
2786
  ```
2460
2787
 
2461
2788
  ### Using Override Hooks in Your Page
@@ -2470,6 +2797,8 @@ import { useSections } from '../components/sections';
2470
2797
  import { useComponents } from '../components/customComponents';
2471
2798
  import { useModals } from '../components/modals';
2472
2799
  import { useCustomDataSources } from '../components/customDataSources';
2800
+ import { useEntityPageHeaderSubtitle } from '../components/entityPageHeaderSubtitle';
2801
+ import { useEntityPageHeaderBadges } from '../components/entityPageHeaderBadges';
2473
2802
 
2474
2803
  export default function YourPage() {
2475
2804
  const actions = useActions();
@@ -2479,9 +2808,11 @@ export default function YourPage() {
2479
2808
  const components = useComponents();
2480
2809
  const modals = useModals();
2481
2810
  const customDataSources = useCustomDataSources();
2811
+ const entityPageHeaderSubtitle = useEntityPageHeaderSubtitle();
2812
+ const entityPageHeaderBadges = useEntityPageHeaderBadges();
2482
2813
 
2483
2814
  return (
2484
- <PatternsWizardOverridesProvider value={{ actions, columns, slots, sections, components, modals, customDataSources }}>
2815
+ <PatternsWizardOverridesProvider value={{ actions, columns, slots, sections, components, modals, customDataSources, entityPageHeaderSubtitle, entityPageHeaderBadges }}>
2485
2816
  <AutoPatternsApp configuration={config} />
2486
2817
  </PatternsWizardOverridesProvider>
2487
2818
  );
@@ -2500,10 +2831,12 @@ For example:
2500
2831
  - Adding a new section renderer → Update `../components/sections/index.tsx` to include the new section in the `useSections` hook
2501
2832
  - Adding a new custom component → Update `../components/customComponents/index.tsx` to include the new component in the `useComponents` hook
2502
2833
  - Adding a new custom data source → Update `../components/customDataSources/index.tsx` to include the new data source in the `useCustomDataSources` hook
2834
+ - Adding a new subtitle override → Update `../components/entityPageHeaderSubtitle/index.tsx` to include the new subtitle in the `useEntityPageHeaderSubtitle` hook
2835
+ - Adding a new badges override → Update `../components/entityPageHeaderBadges/index.tsx` to include the new badges in the `useEntityPageHeaderBadges` hook
2503
2836
 
2504
2837
  Without updating the hook index files, your implementations won't be available to the `PatternsWizardOverridesProvider`.
2505
2838
 
2506
- ## ⚠️ Common Override Mistakes to Avoid
2839
+ ## Common Override Mistakes to Avoid
2507
2840
 
2508
2841
  - Attempting to override unsupported areas
2509
2842
  - Invalid column rendering functions
@@ -178,6 +178,7 @@ Custom bulk actions execute JavaScript code that you define for bulk operations.
178
178
  - `label`: Text displayed for the action
179
179
  - `icon`: An Icon component from "@wix/wix-ui-icons-common"
180
180
  - `onClick`: Handler function for the bulk action
181
+ - `hidden` (optional): Boolean to hide the action when true
181
182
 
182
183
  3. The implementation must:
183
184
  - Use the correct type: `CustomBulkActionsActionResolver`
@@ -1,6 +1,6 @@
1
1
  # Collection Page Configuration
2
2
 
3
- ## ⚠️ Collection Page Rules
3
+ ## Collection Page Rules
4
4
 
5
5
  - **Components array inside collectionPage must contain exactly one component with a layout array**
6
6
  - **All collection pages with tables/grids must reference their corresponding entity page via `entityPageId`** in the collection configuration
@@ -1,6 +1,6 @@
1
1
  # Collection Page Actions
2
2
 
3
- ## ⚠️ Required Actions
3
+ ## Required Actions
4
4
 
5
5
  - **Every collection page must include a create action that navigates to the entity page for adding new entities** - this is essential for user workflow
6
6
 
@@ -1,6 +1,6 @@
1
1
  # Custom Overrides
2
2
 
3
- ## ⚠️ Override Rules
3
+ ## Override Rules
4
4
 
5
5
  - **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
6
6
  - **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/
42
42
  ├── customDataSources/ // Custom data sources
43
43
  │ ├── index.tsx // Exports useCustomDataSources hook
44
44
  │ └── myCustomDataSource.ts
45
- └── sections/ // Section renderers
46
- ├── index.tsx
47
- └── groupByType.ts
45
+ ├── sections/ // Section renderers
46
+ ├── index.tsx
47
+ └── groupByType.ts
48
+ ├── entityPageHeaderSubtitle/ // Entity page dynamic subtitle functions
49
+ │ ├── index.tsx // Exports useEntityPageHeaderSubtitle hook
50
+ │ └── mySubtitle.ts
51
+ └── entityPageHeaderBadges/ // Entity page dynamic badges functions
52
+ ├── index.tsx // Exports useEntityPageHeaderBadges hook
53
+ └── myBadges.ts
48
54
  ```
49
55
 
50
56
  ### Using Override Hooks in Your Page
@@ -59,6 +65,8 @@ import { useSections } from '../components/sections';
59
65
  import { useComponents } from '../components/customComponents';
60
66
  import { useModals } from '../components/modals';
61
67
  import { useCustomDataSources } from '../components/customDataSources';
68
+ import { useEntityPageHeaderSubtitle } from '../components/entityPageHeaderSubtitle';
69
+ import { useEntityPageHeaderBadges } from '../components/entityPageHeaderBadges';
62
70
 
63
71
  export default function YourPage() {
64
72
  const actions = useActions();
@@ -68,9 +76,11 @@ export default function YourPage() {
68
76
  const components = useComponents();
69
77
  const modals = useModals();
70
78
  const customDataSources = useCustomDataSources();
79
+ const entityPageHeaderSubtitle = useEntityPageHeaderSubtitle();
80
+ const entityPageHeaderBadges = useEntityPageHeaderBadges();
71
81
 
72
82
  return (
73
- <PatternsWizardOverridesProvider value={{ actions, columns, slots, sections, components, modals, customDataSources }}>
83
+ <PatternsWizardOverridesProvider value={{ actions, columns, slots, sections, components, modals, customDataSources, entityPageHeaderSubtitle, entityPageHeaderBadges }}>
74
84
  <AutoPatternsApp configuration={config} />
75
85
  </PatternsWizardOverridesProvider>
76
86
  );
@@ -89,10 +99,12 @@ For example:
89
99
  - Adding a new section renderer → Update `../components/sections/index.tsx` to include the new section in the `useSections` hook
90
100
  - Adding a new custom component → Update `../components/customComponents/index.tsx` to include the new component in the `useComponents` hook
91
101
  - Adding a new custom data source → Update `../components/customDataSources/index.tsx` to include the new data source in the `useCustomDataSources` hook
102
+ - Adding a new subtitle override → Update `../components/entityPageHeaderSubtitle/index.tsx` to include the new subtitle in the `useEntityPageHeaderSubtitle` hook
103
+ - Adding a new badges override → Update `../components/entityPageHeaderBadges/index.tsx` to include the new badges in the `useEntityPageHeaderBadges` hook
92
104
 
93
105
  Without updating the hook index files, your implementations won't be available to the `PatternsWizardOverridesProvider`.
94
106
 
95
- ## ⚠️ Common Override Mistakes to Avoid
107
+ ## Common Override Mistakes to Avoid
96
108
 
97
109
  - Attempting to override unsupported areas
98
110
  - Invalid column rendering functions