@wix/auto-patterns 1.15.0 → 1.17.0

package/dist/docs/entity_page_actions.md

@@ -0,0 +1,92 @@
+## Entity Page Actions: `moreActions` Support
+
+Entity pages in AutoPatternsApp support not only a primary action (such as "Save" or "Delete") but also a flexible set of **more actions** (sometimes called "secondary actions" or `moreActions`). These allow you to provide additional contextual actions for the entity, such as custom logic, or grouped actions.
+
+> **Note:** All custom actions for entity pages must be placed in the `moreActions` array. Do not place custom actions as primary actions on entity pages. The `moreActions` array is the only supported location for custom actions on entity pages.
+
+### Configuration Structure
+
+- The `moreActions` property on the entity page is an **array** of action configurations that can include divider objects for visual separation.
+- Each action in `moreActions` is a Custom Action (type: "custom") or a Divider (type: "divider")
+
+#### Example: Adding custom actions with dividers to an entity page
+```json
+{
+  "type": "entityPage",
+  "entityPage": {
+    // ... other config ...
+    "moreActions": [
+      {
+        "id": "sendEmail",
+        "type": "custom",
+        "label": "Send Email"
+      },
+      {
+        "id": "exportData",
+        "type": "custom",
+        "label": "Export Data"
+      },
+      { "type": "divider" },
+      {
+        "id": "archiveEntity",
+        "type": "custom",
+        "label": "Archive"
+      }
+    ]
+  }
+}
+```
+
+---
+
+### CustomEntityPageMoreActionsActionResolver
+
+The `CustomEntityPageMoreActionsActionResolver` type is used to implement custom actions for the `moreActions` menu on entity pages in AutoPatternsApp. Each action in the `moreActions` array must have a corresponding resolver function registered in your overrides.
+
+#### Function Signature
+
+```typescript
+import { CustomEntityPageMoreActionsActionResolver } from '@wix/auto-patterns/types';
+
+export const myMoreAction: CustomEntityPageMoreActionsActionResolver = (params) => {
+  const { actionParams: { entity, form } , sdk } = params;
+
+  return {
+    label: 'My More Action',
+    icon: <MyIcon />, // optional
+    onClick: () => {
+      // Your custom logic here
+    },
+  };
+};
+```
+
+- **entity**: The current entity data (all field values). In actionParams.
+- **form**: The react-hook-form instance for the entity page. In actionParams.
+- **sdk**: The AutoPatterns SDK (see SDK Utilities section).
+
+---
+
+#### Key Points for CustomEntityPageMoreActionsActionResolver
+
+- The action `id` in the configuration MUST exactly match the function name exported from your actions folder.
+- The implementation must use the `CustomEntityPageMoreActionsActionResolver` type.
+- The implementation must be exported as a named export (not default export).
+- The function receives `{ actionParams, sdk }` as parameters.
+- The returned object must include at least a `label` and an `onClick` handler (optionally an `icon`).
+
+---
+
+#### Validation Checklist for More Actions
+
+✓ Each action in `moreActions` has a unique `id` and correct `type` value
+✓ Each action type only includes its required field(s)
+✓ Custom actions match implementations in overrides
+✓ The resolver is exported and registered in the `actions` property of your `PatternsWizardOverridesProvider`
+✓ The function signature matches `CustomEntityPageMoreActionsActionResolver`
+✓ The returned object includes `label`, `onClick`, and optionally `icon`
+
+---
+
+**Summary:**
+The `CustomEntityPageMoreActionsActionResolver` enables you to add custom, contextual actions to the "More Actions" menu on your entity pages. Implement the resolver, export it, and reference it by `id` in your config for seamless integration.

package/dist/docs/index.md

@@ -0,0 +1,76 @@
+# Auto Patterns Documentation Index
+
+This index maps user requests to the appropriate section IDs for fetching relevant content. Match user keywords/intent to section topics to determine which sections to read.
+
+---
+
+## Core Section IDs
+
+### ID: `introduction`
+**Topics**: AI agent instructions, core rules, configuration validation, enum handling
+**Keywords**: getting started, basic rules, validation, enum configuration, page count, component purpose
+
+---
+
+### 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
+
+---
+
+### ID: `pages_configuration`
+**Topics**: Page setup, relationships, routing, URL configuration, sticky columns
+**Keywords**: page configuration, page relationships, routing, URL structure, entityPage, collectionPage, navigation, appMainPage, sticky columns, parentPageId, entityPageId, route parameters
+
+### ID: `collection_page`
+**Topics**: Collection page components, table/grid layouts, column configuration
+**Keywords**: collection page, table/grid configuration, layout arrays, Table/Grid layouts, column setup, customColumns, view switching, displaying collections, list views
+
+### ID: `collection_page_actions`
+**Topics**: Page-level actions, create actions, custom collection actions, action menus
+**Keywords**: page-level actions, collection actions, create actions, adding new items, primaryActions, secondaryActions, action menus, custom actions, navigation
+
+### ID: `sdk_and_schema`
+**Topics**: SDK utilities, optimistic actions, schema usage, filters, server operations
+**Keywords**: SDK utilities, programmatic operations, optimistic actions, immediate UI updates, schema access, collection metadata, server operations, data manipulation, filters configuration, error handling, toast notifications
+
+### ID: `action_cell`
+**Topics**: Row-level actions, update/delete actions, custom row actions, action cell configuration
+**Keywords**: row actions, item-level operations, edit, delete, actionCell, row-level operations, update actions, delete confirmations, custom row actions, inline actions, secondary actions
+
+### ID: `bulk_actions`
+**Topics**: Bulk operations, bulk delete, bulk action toolbar, multi-select actions
+**Keywords**: bulk operations, multi-select actions, bulk delete, mass operations, bulkActionToolbar, selection-based actions, custom bulk operations
+
+### ID: `entity_page`
+**Topics**: Entity page layout, grid system, field layout, containers, components
+**Keywords**: entity page layout, detail page configuration, field arrangement, layout structure, grid system, column spans, main/sidebar sections, field grouping, container usage, custom components, 12-column grid
+
+### ID: `entity_page_actions`
+**Topics**: Entity page actions, moreActions, custom entity actions
+**Keywords**: entity page actions, detail page operations, moreActions, secondary actions, custom entity actions, entity-specific operations, action menus
+
+### ID: `installation`
+**Topics**: Package installation, setup process, component integration, provider setup
+**Keywords**: installation, setup, getting started, initial setup, package installation, dependencies, component integration, provider setup
+
+### ID: `custom_overrides`
+**Topics**: Customization, overrides, custom components, column customization, folder structure
+**Keywords**: customization, custom functionality, overrides, extending functionality, custom components, custom rendering, column overrides, folder structure, organization, row data access
+
+---
+
+## Recipe Section IDs (Step-by-Step Guides)
+
+| Recipe Topic | Section ID | Use Case |
+|--------------|------------|----------|
+| 🚀 First Dashboard | `recipe-first-dashboard` | Complete setup from scratch |
+| ⚡ CRUD Operations | `recipe-crud-operations` | Add Create/Edit/Delete functionality |
+| 📦 Bulk Operations | `recipe-bulk-operations` | Multi-select and bulk actions |
+| 🎨 Complete Customization | `recipe-customization` | Basic to advanced customization and integrations |
+
+## LLM Usage Instructions
+
+**Step 1**: Match user keywords to section topics/keywords above
+**Step 2**: Choose relevant section ID(s) to read
+**Step 3**: For comprehensive guides, prioritize recipe sections over individual sections

package/dist/docs/installation.md

@@ -0,0 +1,55 @@
+# Installation & Setup
+
+## 1. Install Packages
+
+Install if necessary and doesn't exists in package.json:
+
+```bash
+npm install @wix/auto-patterns @wix/patterns @wix/design-system
+```
+
+## ⚠️ 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
+
+## 2. Create AppConfig JSON
+
+Save this configuration as a `{collectionName}Config.patterns.json` 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`
+
+## 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.
+
+### Page Component Example:
+
+```tsx
+import React, { type FC } from 'react';
+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';
+
+const Index: FC = () => {
+  return (
+    <WixDesignSystemProvider features={{ newColorsBranding: true }}>
+      <WixPatternsProvider>
+        <PatternsWizardOverridesProvider value={{ }}>
+          <AutoPatternsApp configuration={config as AppConfig} />
+        </PatternsWizardOverridesProvider>
+      </WixPatternsProvider>
+    </WixDesignSystemProvider>
+  );
+};
+
+export default withDashboard(Index);
+```

package/dist/docs/introduction.md

@@ -0,0 +1,74 @@
+# AI Agent Instructions for AutoPatternsApp
+
+This document serves as a comprehensive guide for AI agents to correctly generate and validate configurations for the `AutoPatternsApp` component. Follow these instructions sequentially to ensure proper implementation.
+
+## AI Usage Guidelines
+
+1. **Configuration Generation Process**:
+
+   * First, analyze the schema requirements.
+   * Then, select appropriate fields based on data types.
+   * Finally, validate against the rules before output.
+
+2. **Required Validation Steps**:
+
+   * Verify exact page count (must be 2).
+   * Confirm proper field selection (max 3 columns initially).
+   * Check all mandatory fields are present.
+   * Ensure no unsupported fields are included.
+   * Verify that every collection page has a create action that navigates to the entity page.
+
+3. **Decision-Making Priority**:
+
+   * User explicit requirements override defaults.
+   * Schema structure guides field selection.
+   * Best practices determine presentation.
+
+4. **Enum Configuration Rule (CRITICAL)**:
+
+   * When generating `enumConfig` (whether implicitly as part of another rule or explicitly upon user request), the AI **must always ask the user to provide the possible option values** for the enum field.
+   * The `value` of each option can be **any string specified by the user**, and the `label` should be derived from the `value` (e.g., if `value` is "dog", the `label` can be "Dog").
+   * The AI is strictly prohibited from guessing, inventing, or assuming the enum values or their labels.
+
+---
+
+# Core Rules
+
+## Configuration Rules
+
+* 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.
+* 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.
+
+## Type Binding Rules
+
+* If `type: 'collectionPage'`, only `collectionPage` field should exist.
+* If `type: 'entityPage'`, only `entityPage` field should exist.
+* No cross-mixing of types is allowed.
+
+## Override Rules
+
+* Custom overrides are restricted to documented areas only.
+* Only override columns when specific rendering is required.
+
+## Validation Rules
+
+* All configurations must align with AppConfig Structure.
+* Remove any configuration entries not in the structure.
+* Verify customColumns.enabled logic (>5 columns or explicit request).
+
+---
+
+# Instruction Guide & Best Practices
+
+This guide instructs on how to correctly integrate the `AutoPatternsApp` component from `@wix/auto-patterns` package into a Wix-based admin page.
+
+---
+
+# 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.

package/dist/docs/pages_configuration.md

@@ -0,0 +1,129 @@
+# Pages Configuration
+
+## ⚠️ 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
+- **All page IDs referenced in relationships must exist in the configuration** - validate all `parentPageId` and `entityPageId` references
+- **Bind `type` strictly to matching fields** - if `type: 'collectionPage'`, only `collectionPage` field exists (no `entityPage` field), and vice versa
+
+## Default Generation
+
+* **Always generate two pages**:
+
+  * One **collectionPage** (routePath: `/`)
+  * One **entityPage** (routePath: `/[segment]/:entityId`)
+
+    * Always use `entityId` as the dynamic URL parameter, not `id`.
+    * The route path **must** include a descriptive segment (e.g., `/product/:entityId`, `/pet/:entityId`)
+    * **Never use just `/:entityId`** - this conflicts with the collection page route and breaks routing
+
+## Type and Structure Binding
+
+* If `type: 'collectionPage'`, then **only** `collectionPage` field exists (no `entityPage` field).
+* If `type: 'entityPage'`, then **only** `entityPage` field exists (no `collectionPage` field).
+* **No cross-mixing** allowed.
+
+## Page Connection Configuration
+
+### Main Page Designation
+
+* One page must be designated as the main page using the `appMainPage` property:
+  * **Exactly one page** must have `appMainPage: true`
+  * When users navigate to the root path (`/`), they will be automatically redirected to this page
+  * This is typically set on the collection page, but can be any page based on your application's requirements
+
+### Collection-Entity Page Relationships
+
+A two-way connection must be established between collection pages and entity pages:
+
+1. **From EntityPage to CollectionPage**:
+   * Each entity page must specify its parent collection page using `parentPageId`
+   * This property on the entity page references the `id` of its parent collection page
+
+2. **From CollectionPage to EntityPage**:
+   * Each collection page's component must reference its corresponding entity page:
+   * Inside the table or grid configuration (not directly in the collectionPage), specify `entityPageId` pointing to the entity page's `id`:
+   ```json
+   "components": [
+     {
+       "type": "Table", // or "Grid"
+       "table": {       // or "grid"
+         "entityPageId": "my-entity-page-id",
+         // other table/grid configuration
+       }
+     }
+   ]
+   ```
+   * ⚠️ **IMPORTANT**: The `entityPageId` field is located within the specific component configuration (table or grid), not at the collection page level
+
+### Entity Page URL Configuration
+
+* For entity pages (`type: "entityPage"`), the following URL configuration is **mandatory**:
+
+  1. **Route Path Structure**:
+     * The `route.path` **must** include a relative path segment followed by a dynamic parameter (e.g., `/product/:entityId` or `/pets/:entityId`)
+     * **Never use just `/:entityId`** - this conflicts with the collection page route `/` and breaks routing
+     * The relative path segment should be descriptive of the entity type (e.g., `/product/`, `/pet/`, `/user/`)
+     * This parameter is typically named `:entityId` by convention, but any parameter name prefixed with `:` is valid
+
+  2. **Route Parameters Mapping**:
+     * The `route.params` property is required and must map the dynamic parameter:
+     ```json
+     "route": {
+       "path": "/product/:entityId",
+       "params": {
+         "id": "entityId"
+       }
+     }
+     ```
+     * The `id` field in `route.params` must match the parameter name used in `route.path` (without the colon)
+
+
+### Key Rules for Page Connections
+
+* **Main Page Requirement**: Exactly one page must have `appMainPage: true`
+* **Reference Validity**: All page IDs referenced in `parentPageId` and `entityPageId` must exist in the configuration
+* **Relationship Consistency**: The two-way connection must be consistent - if entity page A points to collection page B, then collection page B must point to entity page A
+* **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 Type and Route Mistakes to Avoid
+
+- Using incorrect field types
+- Missing required fields
+- Including fields from wrong page type
+- Missing route.params for entity pages
+- Using `/:entityId` instead of `/segment/:entityId` for entity page routes (causes routing conflicts)
+
+# Sticky Columns Configuration
+
+## Overview
+
+Sticky columns allow you to keep specific columns visible while users scroll horizontally through wide tables. This feature improves usability by ensuring important information (like names or IDs) remains accessible during scrolling.
+
+## Configuration Properties
+
+### stickyColumns
+
+- **Type**: `number` (optional)
+- **Description**: Number of columns to make sticky from the start of the table
+- **Behavior**: Sticky columns are always the **first N columns** in the `columns` array
+- **Default**: `undefined` (no sticky columns)
+
+## Key Behavior Rules
+
+### 🔑 **Critical Rule: Position-Based Stickiness**
+- `stickyColumns: 2` means "make the **first 2 columns** sticky" (positions 0 and 1 in the `columns` array)
+- The sticky columns are determined by **array position**, not by column content
+- If columns are reordered, the sticky behavior follows the new order
+
+### 🔒 **Important: Reorder Protection**
+- To protect specific columns from being reordered away from their sticky positions, set `reorderDisabled: true` on those columns
+- This allows `customColumns.enabled: true` while protecting sticky columns from being moved
+- Without reorder protection, users can accidentally move intended sticky columns away from the beginning
+
+### ⚠️ **Validation Rules**
+- `stickyColumns` must be a positive number
+- `stickyColumns` should not exceed the total number of columns
+- Invalid values are ignored (treated as `undefined`)