@wix/auto-patterns 1.21.0 → 1.22.0

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

@@ -147,8 +147,9 @@ export interface AppConfig {
           menu?: {}; // Same structure as primaryActions.menu
         };
       };
-      components: [
+      components: [ // Array of component configurations that can be collection components or custom slot components
         {
+          type: 'collection'; // Component type for collection rendering (table/grid with full features)
           entityPageId?: string; // ID of the entity page to navigate to when clicking a row
           collection: {
             collectionId: string; // ID of the Wix Data collection
@@ -249,6 +250,7 @@ export interface AppConfig {
                   };
                 };
               };
+              alwaysVisible?: boolean; // Whether to always show the primary action (not just on hover)
             };
             secondaryActions?: {
               items: {}[]; // Array of action configurations, same structure as primaryAction.item, can include dividers
@@ -366,6 +368,10 @@ export interface AppConfig {
               };
             }
           ]; // End of layout array
+        } |
+        {
+          type: 'custom'; // Component type for custom slot components
+          id: string; // Unique identifier that maps to a custom React component provided through PatternsWizardOverridesProvider slots
         }
       ]; // End of components array
     };
@@ -1356,6 +1362,10 @@ The ActionCell has a two-level structure:
 
 Both properties are optional, but at least one should be provided for the ActionCell to be useful.
 
+### Primary Action Visibility Control
+
+**New Feature**: Primary actions now support visibility control through the `alwaysVisible` property. By default, primary actions follow standard table interaction patterns (typically visible on hover), but you can configure them to be always visible for improved accessibility and user discovery.
+
 ### Inline Secondary Actions
 
 **New Feature**: By default, all secondary actions are hidden in a popover menu that appears when the user hovers over or clicks the "more actions" button. However, you can now configure some secondary actions to display inline directly in the table row for improved accessibility and reduced clicks.
@@ -1560,17 +1570,21 @@ Follow this decision process when implementing ActionCell:
    - Most common operation (typically Edit) → Place in `primaryAction.item`
    - Less common operations → Place in `secondaryActions.items` array
 
-3. **Inline Secondary Actions Strategy**:
+3. **Primary Action Visibility Strategy**:
+   - **Standard Visibility** (`alwaysVisible: false` or omitted): Use for most cases where actions appear on interaction
+   - **Always Visible** (`alwaysVisible: true`): Use for critical actions that need constant visibility or when user discovery is important
+
+4. **Inline Secondary Actions Strategy**:
    - **Action Prioritization**: Order `secondaryActions.items` by frequency of use (most used first)
    - **Inline Count**: Use `inlineCount: 1-3` for optimal UX (avoid cluttering)
    - **Visibility Control**:
      - Use `inlineAlwaysVisible: false` (default) for cleaner visual appearance
      - Use `inlineAlwaysVisible: true` only for critical actions requiring constant visibility
 
-4. **Update Action Mode**:
+5. **Update Action Mode**:
    - Complex, full-entity edits → Use `mode: "page"` to navigate to entity page
 
-5. **Custom Implementation**:
+6. **Custom Implementation**:
    - For `custom` actions, you must provide implementations in your code and register them with `PatternsWizardOverridesProvider`
 
 ### ActionCell Validation Checklist
@@ -1584,6 +1598,8 @@ AI agents should verify these requirements before generating ActionCell configur
 ✓ Delete action has a modal configuration
 ✓ Custom actions match implementations in overrides
 ✓ At least one of `primaryAction` or `secondaryActions` is provided
+✓ `alwaysVisible` property on primary actions (if specified) is a boolean value
+✓ Primary action visibility is properly considered for UX (use `alwaysVisible: true` for critical actions)
 ✓ `inlineCount` (if specified) is a non-negative number ≤ total secondary actions count
 ✓ `inlineAlwaysVisible` (if specified) is a boolean value
 ✓ Inline secondary actions configuration is applied only when secondary actions exist
@@ -2163,6 +2179,10 @@ your-page/
     │   ├── index.tsx                  // Exports useColumns hook
     │   ├── name.ts
     │   └── date.ts
+    ├── slots/                         // Custom slot components for collection pages
+    │   ├── index.tsx                  // Exports useSlots hook
+    │   ├── TopBannerComponent.tsx
+    │   └── BottomStatsComponent.tsx
     ├── customComponents/              // Custom entity page components
     │   ├── index.tsx                  // Exports useComponents hook
     │   ├── CustomNameField.tsx
@@ -2170,16 +2190,12 @@ your-page/
     ├── modals/                        // Custom modals
     │   ├── index.tsx                  // Exports useModals hook
     │   └── myCustomModal.tsx
-    └── customDataSources/             // Custom data sources
+    ├── customDataSources/             // Custom data sources
     │   ├── index.tsx                  // Exports useCustomDataSources hook
     │   └── myCustomDataSource.ts
-    ├── sections/                      // Section renderers
-    │   ├── index.tsx
-    │   └── groupByType.ts
-    └── customComponents/              // Custom entity page components
+    └── sections/                      // Section renderers
         ├── index.tsx
-        ├── CustomNameField.tsx
-        └── InfoCard.tsx
+        └── groupByType.ts
 ```
 
 ### Using Override Hooks in Your Page
@@ -2189,6 +2205,7 @@ In your page component, use the hook-based approach to access React context and
 ```tsx
 import { useActions } from '../components/actions';
 import { useColumns } from '../components/columns';
+import { useSlots } from '../components/slots';
 import { useSections } from '../components/sections';
 import { useComponents } from '../components/customComponents';
 import { useModals } from '../components/modals';
@@ -2197,13 +2214,14 @@ import { useCustomDataSources } from '../components/customDataSources';
 export default function YourPage() {
   const actions = useActions();
   const columns = useColumns();
+  const slots = useSlots();
   const sections = useSections();
   const components = useComponents();
   const modals = useModals();
   const customDataSources = useCustomDataSources();
 
   return (
-    <PatternsWizardOverridesProvider value={{ actions, columns, sections, components, modals, customDataSources }}>
+    <PatternsWizardOverridesProvider value={{ actions, columns, slots, sections, components, modals, customDataSources }}>
       <AutoPatternsApp configuration={config} />
     </PatternsWizardOverridesProvider>
   );
@@ -2212,12 +2230,13 @@ export default function YourPage() {
 
 ### Important: Updating Hook Index Files
 
-**When adding any new implementation (action, modal, column, 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.
+**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
+- Adding a new slot component → Update `../components/slots/index.tsx` to include the new slot in the `useSlots` hook
 - 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
@@ -2947,6 +2966,10 @@ interface Section {
     prefixIcon?: React.ReactElement;
     onClick: () => void;
   };
+  badge?: {
+    visible: boolean;
+    skin?: 'light' | 'danger' | 'neutralLight';
+  };
 }
 ```
 
@@ -2954,6 +2977,7 @@ 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
+- **badge** (optional): A badge configuration displayed in the section header
 
 #### Example: Section Renderer Implementation
 
@@ -2979,6 +3003,10 @@ export function groupByType(item: any): Section {
         console.log(`Showing all ${petType}s`);
       },
     },
+    badge: {
+      visible: true,
+      skin: 'light',
+    },
   };
 }
 ```
@@ -3001,16 +3029,20 @@ export function groupByAgeAndVaccination(item: any): Section {
 
   let sectionId: string;
   let sectionTitle: string;
+  let badgeSkin: 'light' | 'danger' | 'neutralLight' = 'light';
 
   if (age < 1) {
     sectionId = 'puppies';
     sectionTitle = 'Puppies (Under 1 year)';
+    badgeSkin = 'neutralLight';
   } else if (age >= 1 && age <= 5) {
     sectionId = isVaccinated ? 'young-vaccinated' : 'young-unvaccinated';
     sectionTitle = `Young Adults (1-5 years) - ${isVaccinated ? 'Vaccinated' : 'Not Vaccinated'}`;
+    badgeSkin = isVaccinated ? 'light' : 'danger';
   } else {
     sectionId = 'seniors';
     sectionTitle = 'Senior Pets (5+ years)';
+    badgeSkin = 'light';
   }
 
   return {
@@ -3023,6 +3055,10 @@ export function groupByAgeAndVaccination(item: any): Section {
         // Show special care information for puppies
       },
     } : undefined,
+    badge: {
+      visible: true,
+      skin: badgeSkin,
+    },
   };
 }
 ```
@@ -3051,4 +3087,156 @@ import * as actions from './components/actions';
 
 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
+
+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
+- Implementing page-specific functionality that doesn't fit into standard patterns
+
+### Configuration Structure
+
+Slots are configured in the collection page configuration using the `CustomComponentConfig` structure:
+
+```json
+{
+  "type": "custom",
+  "id": "myCustomSlot"
+}
+```
+
+**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
+
+### Component Positioning
+
+Slot components can be positioned anywhere within the `components` array of a collection page. They will be rendered in the exact order specified in the configuration:
+
+```json
+{
+  "type": "collectionPage",
+  "collectionPage": {
+    "components": [
+      {
+        "type": "custom",
+        "id": "topBanner"
+      },
+      {
+        "type": "collection",
+        "collection": {
+          "collectionId": "MyCollection"
+        },
+        "layout": [...]
+      },
+      {
+        "type": "custom",
+        "id": "bottomStats"
+      }
+    ]
+  }
+}
+```
+
+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
+
+### Implementation Structure
+
+#### Creating Slot Components
+
+Slot components are standard React functional components that take no props:
+
+```tsx
+import React from 'react';
+import { Box, Card, Text, Button } from '@wix/design-system';
+
+export const TopBannerComponent: React.FC = () => {
+  return (
+    <Card>
+      <Card.Content>
+        <Box direction="vertical" gap={2}>
+          <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>
+      </Card.Content>
+    </Card>
+  );
+};
+
+export const BottomStatsComponent: React.FC = () => {
+  return (
+    <Card>
+      <Card.Content>
+        <Box direction="horizontal" gap={4}>
+          <Box direction="vertical" gap={1}>
+            <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="small">Available for Adoption</Text>
+          </Box>
+        </Box>
+      </Card.Content>
+    </Card>
+  );
+};
+```
+
+#### Creating the Slots Hook
+
+In `components/slots/index.tsx`:
+
+```tsx
+import { TopBannerComponent } from './TopBannerComponent';
+import { BottomStatsComponent } from './BottomStatsComponent';
+
+export const useSlots = () => {
+  // You can access React context and other hooks here
+  return {
+    topBanner: TopBannerComponent,
+    bottomStats: BottomStatsComponent
+  };
+};
+```
+
+**Important:** Every time you create a new slot component, you must import it and add it to the `useSlots` hook return object. The key in the return object must match the `id` specified in your JSON configuration.
+
+#### Registering Slots in Your Page
+
+In your main page component:
+
+```tsx
+import { useSlots } from '../components/slots';
+
+export default function YourPage() {
+  const slots = useSlots();
+
+  return (
+    <PatternsWizardOverridesProvider value={{ slots }}>
+      <AutoPatternsApp configuration={config} />
+    </PatternsWizardOverridesProvider>
+  );
+}
+```
+
+### Important Guidelines for Slots
+
+1. **Component Signature**: Slot components must be React functional components with no props: `React.FC`
+2. **Rendering Order**: Components render in the exact order specified in the `components` array
+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.
+
 ---

package/dist/docs/custom_overrides.md

@@ -28,6 +28,10 @@ your-page/
     │   ├── index.tsx                  // Exports useColumns hook
     │   ├── name.ts
     │   └── date.ts
+    ├── slots/                         // Custom slot components for collection pages
+    │   ├── index.tsx                  // Exports useSlots hook
+    │   ├── TopBannerComponent.tsx
+    │   └── BottomStatsComponent.tsx
     ├── customComponents/              // Custom entity page components
     │   ├── index.tsx                  // Exports useComponents hook
     │   ├── CustomNameField.tsx
@@ -35,16 +39,12 @@ your-page/
     ├── modals/                        // Custom modals
     │   ├── index.tsx                  // Exports useModals hook
     │   └── myCustomModal.tsx
-    └── customDataSources/             // Custom data sources
+    ├── customDataSources/             // Custom data sources
     │   ├── index.tsx                  // Exports useCustomDataSources hook
     │   └── myCustomDataSource.ts
-    ├── sections/                      // Section renderers
-    │   ├── index.tsx
-    │   └── groupByType.ts
-    └── customComponents/              // Custom entity page components
+    └── sections/                      // Section renderers
         ├── index.tsx
-        ├── CustomNameField.tsx
-        └── InfoCard.tsx
+        └── groupByType.ts
 ```
 
 ### Using Override Hooks in Your Page
@@ -54,6 +54,7 @@ In your page component, use the hook-based approach to access React context and
 ```tsx
 import { useActions } from '../components/actions';
 import { useColumns } from '../components/columns';
+import { useSlots } from '../components/slots';
 import { useSections } from '../components/sections';
 import { useComponents } from '../components/customComponents';
 import { useModals } from '../components/modals';
@@ -62,13 +63,14 @@ import { useCustomDataSources } from '../components/customDataSources';
 export default function YourPage() {
   const actions = useActions();
   const columns = useColumns();
+  const slots = useSlots();
   const sections = useSections();
   const components = useComponents();
   const modals = useModals();
   const customDataSources = useCustomDataSources();
 
   return (
-    <PatternsWizardOverridesProvider value={{ actions, columns, sections, components, modals, customDataSources }}>
+    <PatternsWizardOverridesProvider value={{ actions, columns, slots, sections, components, modals, customDataSources }}>
       <AutoPatternsApp configuration={config} />
     </PatternsWizardOverridesProvider>
   );
@@ -77,12 +79,13 @@ export default function YourPage() {
 
 ### Important: Updating Hook Index Files
 
-**When adding any new implementation (action, modal, column, 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.
+**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
+- Adding a new slot component → Update `../components/slots/index.tsx` to include the new slot in the `useSlots` hook
 - 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
@@ -812,6 +815,10 @@ interface Section {
     prefixIcon?: React.ReactElement;
     onClick: () => void;
   };
+  badge?: {
+    visible: boolean;
+    skin?: 'light' | 'danger' | 'neutralLight';
+  };
 }
 ```
 
@@ -819,6 +826,7 @@ 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
+- **badge** (optional): A badge configuration displayed in the section header
 
 #### Example: Section Renderer Implementation
 
@@ -844,6 +852,10 @@ export function groupByType(item: any): Section {
         console.log(`Showing all ${petType}s`);
       },
     },
+    badge: {
+      visible: true,
+      skin: 'light',
+    },
   };
 }
 ```
@@ -866,16 +878,20 @@ export function groupByAgeAndVaccination(item: any): Section {
 
   let sectionId: string;
   let sectionTitle: string;
+  let badgeSkin: 'light' | 'danger' | 'neutralLight' = 'light';
 
   if (age < 1) {
     sectionId = 'puppies';
     sectionTitle = 'Puppies (Under 1 year)';
+    badgeSkin = 'neutralLight';
   } else if (age >= 1 && age <= 5) {
     sectionId = isVaccinated ? 'young-vaccinated' : 'young-unvaccinated';
     sectionTitle = `Young Adults (1-5 years) - ${isVaccinated ? 'Vaccinated' : 'Not Vaccinated'}`;
+    badgeSkin = isVaccinated ? 'light' : 'danger';
   } else {
     sectionId = 'seniors';
     sectionTitle = 'Senior Pets (5+ years)';
+    badgeSkin = 'light';
   }
 
   return {
@@ -888,6 +904,10 @@ export function groupByAgeAndVaccination(item: any): Section {
         // Show special care information for puppies
       },
     } : undefined,
+    badge: {
+      visible: true,
+      skin: badgeSkin,
+    },
   };
 }
 ```
@@ -915,3 +935,155 @@ import * as actions from './components/actions';
 
 
 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
+
+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
+- Implementing page-specific functionality that doesn't fit into standard patterns
+
+### Configuration Structure
+
+Slots are configured in the collection page configuration using the `CustomComponentConfig` structure:
+
+```json
+{
+  "type": "custom",
+  "id": "myCustomSlot"
+}
+```
+
+**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
+
+### Component Positioning
+
+Slot components can be positioned anywhere within the `components` array of a collection page. They will be rendered in the exact order specified in the configuration:
+
+```json
+{
+  "type": "collectionPage",
+  "collectionPage": {
+    "components": [
+      {
+        "type": "custom",
+        "id": "topBanner"
+      },
+      {
+        "type": "collection",
+        "collection": {
+          "collectionId": "MyCollection"
+        },
+        "layout": [...]
+      },
+      {
+        "type": "custom",
+        "id": "bottomStats"
+      }
+    ]
+  }
+}
+```
+
+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
+
+### Implementation Structure
+
+#### Creating Slot Components
+
+Slot components are standard React functional components that take no props:
+
+```tsx
+import React from 'react';
+import { Box, Card, Text, Button } from '@wix/design-system';
+
+export const TopBannerComponent: React.FC = () => {
+  return (
+    <Card>
+      <Card.Content>
+        <Box direction="vertical" gap={2}>
+          <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>
+      </Card.Content>
+    </Card>
+  );
+};
+
+export const BottomStatsComponent: React.FC = () => {
+  return (
+    <Card>
+      <Card.Content>
+        <Box direction="horizontal" gap={4}>
+          <Box direction="vertical" gap={1}>
+            <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="small">Available for Adoption</Text>
+          </Box>
+        </Box>
+      </Card.Content>
+    </Card>
+  );
+};
+```
+
+#### Creating the Slots Hook
+
+In `components/slots/index.tsx`:
+
+```tsx
+import { TopBannerComponent } from './TopBannerComponent';
+import { BottomStatsComponent } from './BottomStatsComponent';
+
+export const useSlots = () => {
+  // You can access React context and other hooks here
+  return {
+    topBanner: TopBannerComponent,
+    bottomStats: BottomStatsComponent
+  };
+};
+```
+
+**Important:** Every time you create a new slot component, you must import it and add it to the `useSlots` hook return object. The key in the return object must match the `id` specified in your JSON configuration.
+
+#### Registering Slots in Your Page
+
+In your main page component:
+
+```tsx
+import { useSlots } from '../components/slots';
+
+export default function YourPage() {
+  const slots = useSlots();
+
+  return (
+    <PatternsWizardOverridesProvider value={{ slots }}>
+      <AutoPatternsApp configuration={config} />
+    </PatternsWizardOverridesProvider>
+  );
+}
+```
+
+### Important Guidelines for Slots
+
+1. **Component Signature**: Slot components must be React functional components with no props: `React.FC`
+2. **Rendering Order**: Components render in the exact order specified in the `components` array
+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.