@wix/auto-patterns 1.18.0 → 1.20.0

package/dist/docs/custom_overrides.md

@@ -11,67 +11,91 @@ The `PatternsWizardOverridesProvider` allows you to inject custom code to overri
 
 ## Folder Structure Organization
 
-All custom overrides (components, modals, actions, columns, and other customizations) should be created in a `components` folder inside your page directory, not in a global `/src/components` folder. This keeps page-specific customizations organized alongside their respective pages.
+All custom overrides (components, modals, actions, columns, sections, and other customizations) should be created in a `components` folder inside your page directory, not in a global `/src/components` folder. This keeps page-specific customizations organized alongside their respective pages.
 
 ### Recommended Structure:
 
 ```
 your-page/
 ├── page.tsx                           // Your main page component
-├── MyCollectionConfig.patterns.json   // Configuration file
+├── MyCollectionConfig.patterns.ts     // Configuration file
 └── components/                        // Page-specific components folder
-    ├── index.tsx                       // Exports all overrides for easy importing
+    ├── index.tsx                       // Exports all override hooks for easy importing
     ├── actions/                       // Custom actions
-    │   ├── index.tsx
+    │   ├── index.tsx                  // Exports useActions hook
     │   └── myCustomAction.tsx
     ├── columns/                       // Column overrides
-    │   ├── index.tsx
+    │   ├── index.tsx                  // Exports useColumns hook
     │   ├── name.ts
     │   └── date.ts
     ├── customComponents/              // Custom entity page components
-    │   ├── index.tsx
+    │   ├── index.tsx                  // Exports useComponents hook
     │   ├── CustomNameField.tsx
     │   └── InfoCard.tsx
+    ├── modals/                        // Custom modals
+    │   ├── index.tsx                  // Exports useModals hook
+    │   └── myCustomModal.tsx
     └── customDataSources/             // Custom data sources
+    │   ├── index.tsx                  // Exports useCustomDataSources hook
+    │   └── myCustomDataSource.ts
+    ├── sections/                      // Section renderers
+    │   ├── index.tsx
+    │   └── groupByType.ts
+    └── customComponents/              // Custom entity page components
         ├── index.tsx
-        └── myCustomDataSource.ts
+        ├── CustomNameField.tsx
+        └── InfoCard.tsx
 ```
 
-### Importing Overrides in Your Page
+### Using Override Hooks in Your Page
 
-In your page component, import from the local components folder:
+In your page component, use the hook-based approach to access React context and other hooks:
 
 ```tsx
-import * as modals from './components/modals';
-import * as actions from './components/actions';
-import * as columns from './components/columns';
-import * as components from './components/customComponents';
-import * as customDataSources from './components/customDataSources';
+import { useActions } from '../components/actions';
+import { useColumns } from '../components/columns';
+import { useSections } from '../components/sections';
+import { useComponents } from '../components/customComponents';
+import { useModals } from '../components/modals';
+import { useCustomDataSources } from '../components/customDataSources';
+
+export default function YourPage() {
+  const actions = useActions();
+  const columns = useColumns();
+  const sections = useSections();
+  const components = useComponents();
+  const modals = useModals();
+  const customDataSources = useCustomDataSources();
 
-<PatternsWizardOverridesProvider value={{ modals, actions, columns, components, customDataSources }}>
-  <AutoPatternsApp configuration={config as AppConfig} />
-</PatternsWizardOverridesProvider>
+  return (
+    <PatternsWizardOverridesProvider value={{ actions, columns, sections, components, modals, customDataSources }}>
+      <AutoPatternsApp configuration={config} />
+    </PatternsWizardOverridesProvider>
+  );
+}
 ```
 
-### Important: Updating Index Files
+### Important: Updating Hook Index Files
 
-**When adding any new implementation (action, modal, column, or component), you MUST update the corresponding `index.tsx` file to export your new implementation.** The main page component imports from these index files, so they serve as the central export point for each type of override.
+**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.
 
 For example:
-- Adding a new action → Update `./components/actions/index.tsx`
-- Adding a new modal → Update `./components/modals/index.tsx`
-- Adding a new column override → Update `./components/columns/index.tsx`
-- Adding a new custom component → Update `./components/customComponents/index.tsx`
-- Adding a new custom data source → Update `./components/customDataSources/index.tsx`
+- 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 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
 
-Without updating the index files, your implementations won't be available to the `PatternsWizardOverridesProvider`.
+Without updating the hook index files, your implementations won't be available to the `PatternsWizardOverridesProvider`.
 
 ## ⚠️ Common Override Mistakes to Avoid
 
 - Attempting to override unsupported areas
 - Invalid column rendering functions
-- Missing index file exports for new implementations
+- Missing hook index file exports for new implementations
 - Incorrect import paths or naming mismatches
+- Forgetting to import and use the hook in the main page component
 
 ## Columns
 
@@ -210,23 +234,40 @@ export function date({ value, row }) {
 In `components/columns/index.tsx`:
 
 ```ts
-export * from './name';
-export * from './petInfo';
-export * from './status';
-export * from './fullName';
-export * from './date';
+import { name } from './name';
+import { petInfo } from './petInfo';
+import { status } from './status';
+import { fullName } from './fullName';
+import { date } from './date';
+
+export const useColumns = () => {
+  // You can access React context and other hooks here
+  return {
+    name,
+    petInfo,
+    status,
+    fullName,
+    date
+  };
+};
 ```
 
-**Important:** Every time you add a new column override file, you must add a corresponding export line to this `index.tsx` file. For example, if you create `price.tsx`, you must add `export * from './price';` to the index file.
+**Important:** Every time you add a new column override file, you must import it and add it to the `useColumns` hook return object in this `index.tsx` file. For example, if you create `price.tsx`, you must add `import { price } from './price';` and include `price` in the return object.
 
-In the `PatternsWizardOverridesProvider`:
+In the main page component:
 
 ```tsx
-import * as columns from './components/columns';
+import { useColumns } from '../components/columns';
 
-<PatternsWizardOverridesProvider value={{ columns }}>
-  <AutoPatternsApp configuration={config as AppConfig} />
-</PatternsWizardOverridesProvider>
+export default function YourPage() {
+  const columns = useColumns();
+
+  return (
+    <PatternsWizardOverridesProvider value={{ columns }}>
+      <AutoPatternsApp configuration={config} />
+    </PatternsWizardOverridesProvider>
+  );
+}
 ```
 
 ### Visual Representation
@@ -235,7 +276,7 @@ import * as columns from './components/columns';
 your-page/
 └── components/
     └── columns/
-        ├── index.tsx     // Exports all column overrides
+        ├── index.tsx     // Exports useColumns hook
         ├── name.tsx      // Simple value formatting
         ├── petInfo.tsx   // Complex multi-field column
         ├── status.tsx    // Conditional rendering column
@@ -243,7 +284,7 @@ your-page/
         └── date.tsx      // Enhanced formatting with row context
 
 PatternsWizardOverridesProvider
- └── value.columns
+ └── value.columns (from useColumns hook)
       ├── name
       ├── petInfo
       ├── status
@@ -371,16 +412,37 @@ export const infoCard: FC<CustomComponentProps> = ({ entity }) => {
 };
 ```
 
-### Connecting Components in the Provider
+### Connecting Components with Hooks
 
-In your main page file, import and provide these components via the `PatternsWizardOverridesProvider`:
+In `components/customComponents/index.tsx`:
 
 ```tsx
-import * as components from './components';
+import { customNameField } from './customNameField';
+import { infoCard } from './infoCard';
 
-<PatternsWizardOverridesProvider value={{ components }}>
-  <AutoPatternsApp configuration={config as AppConfig} />
-</PatternsWizardOverridesProvider>
+export const useComponents = () => {
+  // You can access React context and other hooks here
+  return {
+    customNameField,
+    infoCard
+  };
+};
+```
+
+In your main page file:
+
+```tsx
+import { useComponents } from '../components/customComponents';
+
+export default function YourPage() {
+  const components = useComponents();
+
+  return (
+    <PatternsWizardOverridesProvider value={{ components }}>
+      <AutoPatternsApp configuration={config} />
+    </PatternsWizardOverridesProvider>
+  );
+}
 ```
 
 ### Important Guidelines for Custom Components
@@ -400,7 +462,7 @@ import * as components from './components';
    - For dates: `DatePicker`
    - For dropdowns: `Dropdown`
 
-**Important:** Every time you create a new custom component, you must add a corresponding export line to the `./components/customComponents/index.tsx` file. For example, if you create `StatusIndicator.tsx`, you must add `export * from './StatusIndicator';` to the index file.
+**Important:** Every time you create a new custom component, you must import it and add it to the `useComponents` hook return object in the `./components/customComponents/index.tsx` file. For example, if you create `StatusIndicator.tsx`, you must add `import { StatusIndicator } from './StatusIndicator';` and include `StatusIndicator` in the return object.
 
 ### Understanding Reactivity in Custom Components
 
@@ -501,13 +563,14 @@ const CustomComponent: FC<CustomComponentProps> = ({ form, entity }) => {
 ```
 your-page/
 └── components/
-    ├── index.tsx              // Exports all component overrides
-    ├── customNameField.tsx   // Field override component
-    ├── combinedNameFields.tsx // Multiple fields override
-    └── infoCard.tsx          // Standalone component
+    ├── customComponents/
+    │   ├── index.tsx              // Exports useComponents hook
+    │   ├── customNameField.tsx   // Field override component
+    │   ├── combinedNameFields.tsx // Multiple fields override
+    │   └── infoCard.tsx          // Standalone component
 
 PatternsWizardOverridesProvider
- └── value.components
+ └── value.components (from useComponents hook)
       ├── customNameField
       ├── combinedNameFields
       └── infoCard
@@ -534,25 +597,62 @@ 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.
+
+The sections feature supports both Table and TableGridSwitch components. When enabled, the table will render section headers that group related rows together.
+
+### Configuring Sections
+
+To enable sections, add the `sections` configuration to your table configuration:
+
+```json
+{
+  "type": "collectionPage",
+  "collectionPage": {
+    "components": [
+      {
+        "collection": {
+          "collectionId": "WixPets"
+        },
+        "layout": [
+          {
+            "type": "Table",
+            "table": {
+              "columns": [...],
+              "sections": {
+                "id": "groupByType"
+              }
+            }
+          }
+        ]
+      }
+    ]
+  }
+}
+```
 
 **Key Properties:**
 - `entityTypeSource`: Must be set to `"custom"` instead of `"cms"`
 - `custom.id`: A unique identifier for your custom data source implementation
 
-### Custom Data Source Override Structure
+### Custom Data Source Hook Structure
 
-Custom data sources are implemented through the `customDataSources` property in your `PatternsWizardOverridesProvider`:
+Custom data sources are implemented through the `useCustomDataSources` hook in your `PatternsWizardOverridesProvider`:
 
 ```tsx
-<PatternsWizardOverridesProvider value={{
-  customDataSources: {
-    myCustomDataSource: async (collectionId: string, context: any) => {
-      return customSchemaConfig; // Must return a SchemaConfig object
-    }
-  }
-}}>
-  <AutoPatternsApp configuration={config as AppConfig} />
-</PatternsWizardOverridesProvider>
+import { useCustomDataSources } from '../components/customDataSources';
+
+export default function YourPage() {
+  const customDataSources = useCustomDataSources();
+
+  return (
+    <PatternsWizardOverridesProvider value={{ customDataSources }}>
+      <AutoPatternsApp configuration={config} />
+    </PatternsWizardOverridesProvider>
+  );
+}
 ```
 
 ### Implementation Components
@@ -596,6 +696,21 @@ export const myCustomDataSource = async (collectionId: string, context: any) =>
 };
 ```
 
+### Hook Implementation
+
+In `components/customDataSources/index.tsx`:
+
+```tsx
+import { myCustomDataSource } from './myCustomDataSource';
+
+export const useCustomDataSources = () => {
+  // You can access React context and other hooks here
+  return {
+    myCustomDataSource
+  };
+};
+```
+
 ### Field Type Mapping
 
 When implementing custom data sources, you need to map your data source field types to AutoPatterns field types:
@@ -641,30 +756,162 @@ actions: {
 ```
 your-page/
 ├── page.tsx                           // Your main page component
-├── MyCollectionConfig.patterns.json   // Configuration file
+├── MyCollectionConfig.patterns.ts     // Configuration file
 └── components/                        // Page-specific components folder
-    ├── index.tsx                       // Exports all overrides for easy importing
+    ├── index.tsx                       // Exports all override hooks for easy importing
     ├── customDataSources/             // Custom data sources
-    │   ├── index.tsx
+    │   ├── index.tsx                  // Exports useCustomDataSources hook
     │   └── myCustomDataSource.ts
     ├── actions/                       // Custom actions
-    │   ├── index.tsx
+    │   ├── index.tsx                  // Exports useActions hook
     │   └── myCustomAction.tsx
     └── columns/                       // Column overrides
-        ├── index.tsx
+        ├── index.tsx                  // Exports useColumns hook
         └── myColumn.tsx
 ```
 
 ### Registering Custom Data Sources
 
-In your page component, import and register your custom data sources:
+In your page component, use the hook to access React context and other hooks:
+
+```tsx
+import { useCustomDataSources } from '../components/customDataSources';
+
+export default function YourPage() {
+  const customDataSources = useCustomDataSources();
+
+  return (
+    <PatternsWizardOverridesProvider value={{ customDataSources }}>
+      <AutoPatternsApp configuration={config} />
+    </PatternsWizardOverridesProvider>
+  );
+}
+```
+
+**Important:** Every time you create a new custom data source, you must import it and add it to the `useCustomDataSources` hook return object in the `./components/customDataSources/index.tsx` file. For example, if you create `myDataSource.ts`, you must add `import { myDataSource } from './myDataSource';` and include `myDataSource` in the return object.
+
+### Creating Section Renderers
+
+Section renderers are functions that determine how to group items and what information to display in section headers. They must be provided through the `PatternsWizardOverridesProvider`.
+
+#### Function Signature
+
+```tsx
+function sectionRenderer(item: any): Section
+```
+
+Where `Section` is the interface from @wix/patterns (re-exported from auto-patterns):
+
+```tsx
+interface Section {
+  id: string;
+  title: string;
+  primaryAction?: {
+    id: string;
+    label: string;
+    prefixIcon?: React.ReactElement;
+    onClick: () => void;
+  };
+}
+```
+
+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
+
+#### Example: Section Renderer Implementation
+
+In `components/sections/groupByType.ts`:
+
+```tsx
+import { ChevronDown } from '@wix/wix-ui-icons-common';
+import { Section } from '@wix/patterns';
+
+// Section renderer function that returns the Section type
+export function groupByType(item: any): Section {
+  const petType = item.type || 'other';
+
+  return {
+    id: petType.toLowerCase(),
+    title: `${petType.charAt(0).toUpperCase()}${petType.slice(1)}s`,
+    primaryAction: {
+      id: 'show-all-pets',
+      label: 'Show All',
+      prefixIcon: <ChevronDown />,
+      onClick: () => {
+        // Custom action when section header is clicked
+        console.log(`Showing all ${petType}s`);
+      },
+    },
+  };
+}
+```
+
+In `components/sections/index.tsx`:
+
+```tsx
+export * from './groupByType';
+```
+
+#### Advanced Example: Multi-Field Grouping
 
 ```tsx
-import * as customDataSources from './components/customDataSources';
+import { Badge } from '@wix/design-system';
+import { Section } from '@wix/patterns';
 
-<PatternsWizardOverridesProvider value={{ customDataSources }}>
+export function groupByAgeAndVaccination(item: any): Section {
+  const age = item.age || 0;
+  const isVaccinated = item.isVaccinated || false;
+
+  let sectionId: string;
+  let sectionTitle: string;
+
+  if (age < 1) {
+    sectionId = 'puppies';
+    sectionTitle = 'Puppies (Under 1 year)';
+  } else if (age >= 1 && age <= 5) {
+    sectionId = isVaccinated ? 'young-vaccinated' : 'young-unvaccinated';
+    sectionTitle = `Young Adults (1-5 years) - ${isVaccinated ? 'Vaccinated' : 'Not Vaccinated'}`;
+  } else {
+    sectionId = 'seniors';
+    sectionTitle = 'Senior Pets (5+ years)';
+  }
+
+  return {
+    id: sectionId,
+    title: sectionTitle,
+    primaryAction: age < 1 ? {
+      id: 'special-care',
+      label: 'Special Care Info',
+      onClick: () => {
+        // Show special care information for puppies
+      },
+    } : undefined,
+  };
+}
+```
+
+### Using Sections in Your Page
+
+Import and register your section renderers:
+
+```tsx
+import * as sections from './components/sections';
+import * as columns from './components/columns';
+import * as actions from './components/actions';
+
+<PatternsWizardOverridesProvider value={{ sections, columns, actions }}>
   <AutoPatternsApp configuration={config as AppConfig} />
 </PatternsWizardOverridesProvider>
 ```
 
-**Important:** Every time you create a new custom data source, you must add a corresponding export line to the `./components/customDataSources/index.tsx` file. For example, if you create `myDataSource.ts`, you must add `export * from './myDataSource';` to the index file.
+### Important Notes
+
+- **Grouping Logic**: Items are grouped by the `id` returned from the section renderer. Items with the same `id` will appear under the same section header.
+- **Section Order**: Sections appear in the order they first appear in the data, not alphabetically.
+- **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.

package/dist/docs/entity_page.md

@@ -11,7 +11,6 @@ All entity pages must have:
 
 * Displays details for a **single entity**.
 * Always tied to a single Wix collection.
-* `entityTypeSource` is always `'cms'`.
 
 > The custom actions must be defined inside the `moreActions` array.
 

package/dist/docs/index.md

@@ -14,7 +14,7 @@ This index maps user requests to the appropriate section IDs for fetching releva
 
 ### ID: `app_config_structure`
 **Topics**: Complete AppConfig interface, data structure, type definitions, field specifications
-**Keywords**: configuration structure, JSON schema, properties, types, filters, bulkActionToolbar, actionCell, modal configuration, route configuration, data types, interface definitions
+**Keywords**: configuration structure, TypeScript schema, properties, types, filters, bulkActionToolbar, actionCell, modal configuration, route configuration, data types, interface definitions
 
 ---
 

package/dist/docs/installation.md

@@ -13,18 +13,18 @@ npm install @wix/auto-patterns @wix/patterns @wix/design-system
 - **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
 
-## 2. Create AppConfig JSON
+## 2. Create AppConfig TypeScript File
 
-Save this configuration as a `{collectionName}Config.patterns.json` file in the same directory as your page.tsx component.
+Save this configuration as a `{collectionName}Config.patterns.ts` file in the same directory as your page.tsx component.
 
 For example:
-- For a "WixPets" collection: `petsConfig.patterns.json`
-- For a "Products" collection: `productsConfig.patterns.json`
-- For a "Users" collection: `usersConfig.patterns.json`
+- For a "WixPets" collection: `petsConfig.patterns.ts`
+- For a "Products" collection: `productsConfig.patterns.ts`
+- For a "Users" collection: `usersConfig.patterns.ts`
 
 ## Render the Collection Page Component
 
-Inside your page component, import the JSON configuration and use the `AutoPatternsApp` component. Since this is a page-level component, it should be the only component rendered on the page. Any other content or components should be removed to ensure proper functionality and avoid conflicts.
+Inside your page component, import the TypeScript configuration and use the `AutoPatternsApp` component. Since this is a page-level component, it should be the only component rendered on the page. Any other content or components should be removed to ensure proper functionality and avoid conflicts.
 
 ### Page Component Example:
 
@@ -34,17 +34,16 @@ import { WixDesignSystemProvider } from '@wix/design-system';
 import '@wix/design-system/styles.global.css';
 import { WixPatternsProvider } from '@wix/patterns/provider';
 import { PatternsWizardOverridesProvider, AutoPatternsApp } from '@wix/auto-patterns';
-import type { AppConfig } from '@wix/auto-patterns/types';
 import { withDashboard } from '@wix/patterns';
 
-import config from './MyCollectionConfig.patterns.json';
+import { config } from './MyCollectionConfig.patterns';
 
 const Index: FC = () => {
   return (
     <WixDesignSystemProvider features={{ newColorsBranding: true }}>
       <WixPatternsProvider>
         <PatternsWizardOverridesProvider value={{ }}>
-          <AutoPatternsApp configuration={config as AppConfig} />
+          <AutoPatternsApp configuration={config} />
         </PatternsWizardOverridesProvider>
       </WixPatternsProvider>
     </WixDesignSystemProvider>

package/dist/docs/introduction.md

@@ -38,7 +38,7 @@ This document serves as a comprehensive guide for AI agents to correctly generat
 
 * Pages array MUST contain exactly two pages.
 * Components array inside collectionPage MUST contain exactly one component with a layout array.
-* Configuration MUST come only from a JSON file.
+* Configuration MUST come only from a TypeScript file.
 * DO NOT fill optional fields unless explicitly requested.
 * Select up to 3 columns initially that best represent the entity.
 * Every collection page MUST include a create action that allows users to create new entities by navigating to the entity page.
@@ -71,4 +71,5 @@ This guide instructs on how to correctly integrate the `AutoPatternsApp` compone
 # Component Purpose
 
 The `AutoPatternsApp` is a page-level component used to display a data collection either as a Table or Grid.
-It is configured using a JSON file conforming to the `AppConfig` interface and supports overrides for advanced use-cases.
+It is configured using a TypeScript file conforming to the `AppConfig` interface and supports overrides for advanced use-cases.
+