@wix/auto-patterns 1.15.0 → 1.17.0

package/dist/docs/bulk_actions.md

@@ -0,0 +1,266 @@
+## Bulk Action Toolbar Configuration
+
+The Bulk Action Toolbar feature enables users to perform operations on multiple selected entities simultaneously in collection tables or grids. When configured, it adds checkboxes to each row and displays a toolbar with bulk actions when items are selected.
+
+### Placement and Structure
+
+The Bulk Action Toolbar is configured within the table / grid / table-grid switch configuration using the `bulkActionToolbar` property. It has a two-level structure:
+* `primaryActions`: Actions shown directly in the bulk action toolbar
+* `secondaryActions`: Additional actions organized in sections, typically shown in a dropdown menu
+
+Both properties are optional, but at least one should be provided for the bulk action toolbar to be functional.
+
+### Bulk Action Types Reference
+
+1. **Bulk Delete Action** (`type: "bulkDelete"`):
+   - ✓ Use when: Removing multiple entities with confirmation
+   - ✓ Common scenarios:
+     - Mass deletion of records
+     - Bulk cleanup operations
+   - ✓ Built-in functionality: No custom implementation needed
+
+2. **Custom Action** (`type: "custom"`):
+   - ✓ Use when: Executing custom JavaScript for bulk operations
+   - ✓ Common scenarios:
+     - Bulk API calls
+     - Bulk exports/downloads
+     - Complex bulk operations without UI
+   - ⚠️ Requires implementation: Must register action in overrides
+
+### Type Selection Decision Tree
+
+When choosing a bulk action type, follow this decision process:
+
+1. IF removing multiple entities:
+   → Use `type: "bulkDelete"`
+
+2. IF executing custom logic for bulk operations without UI:
+   → Use `type: "custom"`
+   - MUST implement action handler
+   - MUST register with `actions` override
+
+### Bulk Delete Action Configuration
+
+Bulk delete actions remove multiple entities with a confirmation modal.
+
+#### Validation Rules:
+
+1. `bulkDelete.mode` must be `"modal"` (currently only modal is supported)
+2. `bulkDelete.modal` object must exist
+3. The modal properties (title, description, actions, feedback) are all optional
+
+### Custom Bulk Action Configuration
+
+Custom bulk actions execute JavaScript code that you define for bulk operations. These actions receive parameters that give them access to selected entities data and utilities. Here's how to implement a custom bulk action:
+
+1. First, create the actions folder structure in your page folder:
+   ```
+   your-page/
+   ├── page.tsx
+   └── components/
+       └── actions/
+           ├── index.tsx                    // Exports all actions
+           └── bulkExportPets.tsx          // Your custom bulk action
+   ```
+
+2. Create your bulk action handler in `bulkExportPets.tsx`:
+   ```typescript
+   import { CustomBulkActionsActionResolver } from '@wix/auto-patterns';
+   import { Download } from '@wix/wix-ui-icons-common';
+   import React from 'react';
+
+   // IMPORTANT: Function name MUST match the action id in your configuration
+   export const bulkExportPets: CustomBulkActionsActionResolver = (params) => {
+     const { actionParams, sdk } = params;
+     const { selectedValues, total } = actionParams;
+
+     return {
+       label: 'Export Selected',
+       icon: <Download />,
+       onClick: () => {
+         // sdk is provided to custom action resolvers (see SDK Utilities section)
+         const optimisticActions = sdk.getOptimisticActions(sdk.collectionId);
+         const schema = sdk.getSchema(sdk.collectionId);
+
+         // Example: Mark pets as exported
+         const updatedItems = selectedValues.map(item => ({
+           ...item,
+           lastExported: new Date()
+         }));
+         optimisticActions.updateMany(updatedItems, {
+           submit: async (items) => {
+             // Your export logic here + update server
+             const exportData = items.map(pet => ({
+               name: pet.name,
+               age: pet.age,
+               owner: pet.owner
+             }));
+
+             // Create and download CSV
+             const csv = exportData.map(row => Object.values(row).join(',')).join('\n');
+             const blob = new Blob([csv], { type: 'text/csv' });
+             const url = URL.createObjectURL(blob);
+             const a = document.createElement('a');
+             a.href = url;
+             a.download = 'pets-export.csv';
+             a.click();
+
+             // Update server with export timestamp
+             return await schema.actions.update(items);
+           },
+           successToast: `${selectedValues.length} pets exported`,
+           errorToast: (err, {retry}) => ({
+             text: 'Export failed',
+             action: { text: 'Retry', onClick: retry }
+           })
+         });
+       },
+     };
+   };
+   ```
+
+3. Export your action in `actions/index.tsx`:
+   ```typescript
+   export * from './bulkExportPets';
+   ```
+
+4. Configure the action in your JSON configuration:
+   ```json
+   {
+     "id": "bulkExportPets",        // MUST match the function name exactly
+     "type": "custom",              // REQUIRED: Must be exactly "custom"
+     "label": "Export Selected",    // Optional: Displayed text
+   }
+   ```
+
+5. Register your action in the `PatternsWizardOverridesProvider`:
+   ```typescript
+   import * as actions from './components/actions';
+
+   <PatternsWizardOverridesProvider value={{ actions }}>
+     <AutoPatternsApp configuration={config as AppConfig} />
+   </PatternsWizardOverridesProvider>
+   ```
+
+### Key Points for Custom Bulk Actions:
+- The action `id` in the configuration MUST exactly match the function name exported from your actions folder
+- The function name and file name should follow a consistent naming convention (e.g., camelCase)
+- The implementation must be exported as a named export (not default export)
+- The implementation must use the `CustomBulkActionsActionResolver` type
+- Access selected entities through `actionParams.selectedValues`
+- Access total count through `actionParams.total`
+
+#### Validation Rules for Custom Bulk Actions:
+
+1. `id` must:
+   - Match exactly the function name of the custom bulk action implementation
+   - Be registered in the `actions` property of your `PatternsWizardOverridesProvider`
+   - Follow JavaScript identifier naming rules (camelCase recommended)
+
+2. The implementation must return an object with:
+   - `label`: Text displayed for the action
+   - `icon`: An Icon component from "@wix/wix-ui-icons-common"
+   - `onClick`: Handler function for the bulk action
+
+3. The implementation must:
+   - Use the correct type: `CustomBulkActionsActionResolver`
+   - Be exported as a named export
+   - Have a filename matching the function name
+
+### Bulk Action Toolbar Structure
+
+The bulk action toolbar uses a specific structure for organizing actions:
+
+#### Primary Actions Structure:
+```json
+"bulkActionToolbar": {
+  "primaryActions": [
+    {
+      "type": "action",
+      "action": {
+        "item": {
+          "id": "bulkCustom",
+          "type": "custom",
+          "label": "Custom Bulk",
+          "custom": {
+            "id": "MyCustomBulk"
+          }
+        }
+      }
+    },
+    {
+      "type": "menu",
+      "menu": {
+        "label": "More actions",
+        "items": [
+          {
+            "id": "exportItems",
+            "type": "custom",
+            "label": "Export Items"
+          },
+          { "type": "divider" },
+          {
+            "id": "downloadItems",
+            "type": "custom",
+            "label": "Download Items"
+          }
+        ]
+      }
+    }
+  ]
+}
+```
+
+#### Secondary Actions Structure:
+```json
+"bulkActionToolbar": {
+  "secondaryActions": [
+      {
+        "id": "bulkDeleteWithModal",
+        "label": "Bulk Delete",
+        "type": "bulkDelete",
+        "bulkDelete": {
+          "mode": "modal",
+          "modal": {
+            "title": { "text": "Delete items" },
+            "description": { "text": "Are you sure?" }
+          }
+        }
+      },
+      {
+        "id": "bulkExportPets",
+        "type": "custom",
+        "label": "Export Selected"
+      }
+  ]
+}
+```
+
+### Key Implementation Decisions
+
+Follow this decision process when implementing Bulk Action Toolbar:
+
+1. **Basic Decision**: Decide which bulk operations users need to perform:
+   - Delete multiple entities? → Use `bulkDelete` actions
+   - Custom bulk operations? → Use `custom` actions
+
+2. **Primary vs Secondary**: Choose the most common/important bulk action as primary:
+   - Most common bulk operation → Place in `primaryActions.items` array
+   - Less common bulk operations → Place in `secondaryActions` array
+
+3. **Custom Implementation**:
+   - For `custom` bulk actions, you must provide implementations in your code and register them with `PatternsWizardOverridesProvider`
+
+### Bulk Action Toolbar Validation Checklist
+
+AI agents should verify these requirements before generating Bulk Action Toolbar configurations:
+
+✓ Bulk Action Toolbar is placed directly inside `table` or `grid` configuration as `bulkActionToolbar`
+✓ Each bulk action has a unique `id` and correct `type` value
+✓ Each action type only includes its required field(s)
+✓ Bulk delete actions have modal configuration
+✓ Custom bulk actions match implementations in overrides
+✓ At least one of `primaryActions` or `secondaryActions` is provided
+✓ Primary actions use `action`/`menu` structure with proper `action` or `menu` properties
+✓ Secondary actions are an array that can include dividers
+✓ Menu items within primary actions is array that can include dividers

package/dist/docs/collection_page.md

@@ -0,0 +1,54 @@
+# Collection Page Configuration
+
+## ⚠️ Collection Page Rules
+
+- **Components array inside collectionPage must contain exactly one component with a layout array**
+- **All collection pages with tables/grids must reference their corresponding entity page via `entityPageId`** in the collection configuration
+- **Enable `customColumns` only based on strict logic** - enable if more than 5 columns are defined OR user explicitly requests it, otherwise disable
+- **Row click behavior**: By default, clicking a table row navigates to the entity page. Use `onRowClick` configuration only when custom row click behavior is explicitly required
+- **When generating config for first time, select up to 3 columns from the schema that best represent the entity**
+
+## Components Array
+
+* Must include **exactly one item**.
+* Each component must have:
+  * `collection`: Collection configuration with `collectionId` and `entityTypeSource: 'cms'`
+  * `layout`: Array of layout items that determine what components to render
+
+## Layout Array
+
+The `layout` array contains the rendering components for the collection. Each layout item has:
+* `type`: Either 'Table' or 'Grid'
+* Component-specific configuration (`table` or `grid` object)
+
+### Layout Item Types:
+
+1. **Table Layout Item** (`type: 'Table'`):
+   * `table` field contains table-specific configuration
+   * Used for displaying collection in a **table view**
+   * Includes columns, actionCell, bulkActionToolbar, etc.
+
+2. **Grid Layout Item** (`type: 'Grid'`):
+   * `grid` field contains grid-specific configuration
+   * Used for **grid (card) view** of collection
+   * Includes item configuration for title/subtitle/image fields
+
+### Table/Grid View Switch Behavior:
+* When **both** Table and Grid layout items are present in the layout array, AutoPatterns automatically adds a Table/Grid view switch control so users can toggle between the two views
+* Users can toggle between table and grid views
+
+## Table Configuration
+
+* Used for displaying collection in a **table view**.
+* **customColumns.enabled** logic:
+  * Enable if:
+    * More than **5 columns** are defined
+    * OR user **explicitly** requests it
+  * Otherwise, **disable** (false)
+
+## Grid Configuration
+
+* Used for **grid (card) view** of collection.
+* `item.title`, `item.subtitle`, `item.image` fields are **Field IDs** from the schema.
+* If the user does not specify, **select the most relevant fields automatically**.
+* For grid components, it is strongly recommended to implement a primary action cell with an `update` action that navigates to the entity page. This provides users with an intuitive way to access detailed information and edit individual entities directly from the grid view.

package/dist/docs/collection_page_actions.md

@@ -0,0 +1,343 @@
+# Collection Page Actions
+
+## ⚠️ Required Actions
+
+- **Every collection page must include a create action that navigates to the entity page for adding new entities** - this is essential for user workflow
+
+The `actions` property is an optional object within the `collectionPage` configuration, but it is strongly recommended to always include primaryActions with a create action for better user experience.
+
+## `primaryActions` and `secondaryActions` Structure
+
+Both `primaryActions` and `secondaryActions` are optional and share the same underlying structure for defining how actions are displayed. They can be configured in one of two ways:
+
+### A. Action Layout (`type: "action"`)
+*   **Description**: This layout is used to display a single, prominent page-level action. For example, a "Create New Item" button.
+*   **`action.item`**: Contains the configuration for the single action.
+
+### B. Action Menu Layout (`type: "menu"`)
+*   **Description**: This layout groups several page-level actions, often rendered as a dropdown menu or a set of related buttons under a common label.
+*   **`menu.label`**: A string that serves as the title or accessible label for the group of actions.
+*   **`menu.items`**: A flat array of action configurations, which can include divider objects for visual separation.
+
+## Individual Action Configuration
+
+Each individual action, whether standalone in an `action` layout or part of an `items` array in a `menu` layout, is defined by the action item structure (see `AppConfig Structure`).
+
+In addition to these common properties, each action item must specify a `type` which determines the action's behavior and additional required configuration.
+
+### 1. `type: "create"`
+*   **Purpose**: Navigates to an entity page, allowing the user to create a new item in the specified collection.
+*   **Details**:
+    *   `create.mode`: Must be `'page'`.
+    *   `create.page.id`: Must be the `id` of an existing `entityPage` in your `AppConfig`. This entity page should be set up to handle the creation of new entities for the `collection.collectionId`.
+
+### 2. `type: "custom"`
+*   **Purpose**: Executes custom JavaScript logic defined in your application's overrides.
+*   **Details**:
+    *   The `custom` object in the configuration is typically empty. The functionality is determined by a custom action resolver function that you implement and register in the `actions` section of your `PatternsWizardOverridesProvider`. The `id` of this action item must exactly match the name (key) of the registered custom action resolver. The resolver will receive parameters including `collectionId`.
+
+### 3. `type: "divider"`
+*   **Purpose**: Creates a visual separator between action groups in menus and lists.
+*   **Details**:
+    *   Divider actions require no additional configuration beyond `{ "type": "divider" }`.
+    *   Used within flat arrays to create logical groupings.
+
+## Note on `secondaryActions`
+
+`secondaryActions` follow the exact same structural rules (`type: "action"` or `type: "menu"`) and use the same action item options as `primaryActions`. They are typically used for less prominent or less frequently used page-level actions, often rendered in a secondary position or within a "more options" style menu.
+
+## Custom Collection Page Action Configuration
+
+Custom collection page actions execute JavaScript code that you define for collection-level operations. These actions receive parameters that give them access to collection context and utilities. Here's how to implement a custom collection page action:
+
+1. First, create the actions folder structure in your page folder:
+   ```
+   your-page/
+   ├── page.tsx
+   └── components/
+       └── actions/
+           ├── index.tsx                    // Exports all actions
+           └── exportCollection.tsx        // Your custom collection action
+   ```
+
+2. Create your collection action handler in `exportCollection.tsx`:
+   ```typescript
+   import { CustomActionCollectionPageActionResolver } from '@wix/auto-patterns';
+   import React from 'react';
+   import { Download } from '@wix/ui-icons-common';
+
+   // IMPORTANT: Function name MUST match the action id in your configuration
+   export const exportCollection: CustomActionCollectionPageActionResolver = (params) => {
+     const { actionParams, sdk } = params;
+     const { collectionId } = actionParams;
+
+     return {
+       label: 'Export Collection',
+       icon: <Download />,
+       onClick: () => {
+         // sdk is provided to custom action resolvers (see SDK Utilities section)
+         const optimisticActions = sdk.getOptimisticActions(collectionId);
+         const schema = sdk.getSchema(collectionId);
+
+         // Example: Mark entire collection as exported
+         optimisticActions.updateAll(
+           (item) => ({ lastExported: new Date() }),
+           {
+             submit: async () => {
+               // Your collection export logic here
+               console.log(`Exporting collection: ${collectionId}`);
+               // Export and update all items on server
+               return await schema.actions.bulkUpdate({ lastExported: new Date() });
+             },
+             successToast: 'Collection exported successfully',
+             errorToast: (err, {retry}) => ({
+               text: 'Export failed',
+               action: { text: 'Retry', onClick: retry }
+             })
+           }
+         );
+       },
+     };
+   };
+   ```
+
+3. Export your action in `actions/index.tsx`:
+   ```typescript
+   export * from './exportCollection';
+   ```
+
+4. Configure the action in your JSON configuration:
+   ```json
+   {
+     "id": "exportCollection",        // MUST match the function name exactly
+     "type": "custom",                // REQUIRED: Must be exactly "custom"
+     "label": "Export Collection",    // Optional: Displayed text
+     "collection": {
+       "collectionId": "WixPets",
+       "entityTypeSource": "cms"
+     }
+   }
+   ```
+
+5. Register your action in the `PatternsWizardOverridesProvider`:
+   ```typescript
+   import * as actions from './components/actions';
+
+   <PatternsWizardOverridesProvider value={{ actions }}>
+     <AutoPatternsApp configuration={config as AppConfig} />
+   </PatternsWizardOverridesProvider>
+   ```
+
+## Key Points for Custom Collection Page Actions:
+- The action `id` in the configuration MUST exactly match the function name exported from your actions folder
+- The function name and file name should follow a consistent naming convention (e.g., camelCase)
+- The implementation must be exported as a named export (not default export)
+- The implementation must use the `CustomActionCollectionPageActionResolver` type
+- Access collection context through `actionParams.collectionId`
+
+---
+
+## Custom Row Click Actions
+
+In addition to page-level actions, you can also customize what happens when users click on individual rows in your collection table. By default, clicking a row navigates to the entity page, but you can override this behavior with custom logic.
+
+**Before You Start:**
+- Only configure `onRowClick` if you need custom behavior (e.g., opening modals, side panels, custom actions)
+- If you just want navigation to entity page, don't configure `onRowClick` - it's the default behavior
+- Once you configure `onRowClick`, you must provide a complete working implementation
+
+### Configuration
+
+Row click actions are configured at the table level using the `onRowClick` property:
+
+```json
+{
+  "type": "Table",
+  "table": {
+    "columns": [...],
+    "onRowClick": {
+      "id": "handleRowClick",        // MUST match the function name exactly
+      "type": "custom",              // REQUIRED: Must be exactly "custom"
+    }
+  }
+}
+```
+
+### Implementation Requirements
+
+⚠️ **CRITICAL**: When you configure `onRowClick` in your JSON, you MUST provide a complete working implementation. The Auto Patterns framework cannot function without it.
+
+Custom row click actions use the `CustomActionCollectionPageActionOnRowClickResolver` type and MUST return a `ResolvedAction` object with all required properties:
+
+#### Required Return Object Structure:
+```typescript
+return {
+  label: string,        // REQUIRED: Action label
+  icon: ReactElement,   // REQUIRED: Icon component
+  onClick: () => void   // REQUIRED: Click handler function
+};
+```
+
+#### Complete Implementation Example:
+
+```typescript
+import { CustomActionCollectionPageActionOnRowClickResolver } from '@wix/auto-patterns';
+import React from 'react';
+import { More } from '@wix/wix-ui-icons-common';
+
+// IMPORTANT: Function name MUST match the action id in your configuration
+export const handleRowClick: CustomActionCollectionPageActionOnRowClickResolver = (params) => {
+  const { actionParams, sdk } = params;
+  const { item } = actionParams; // The clicked row's data
+
+  return {
+    label: 'View Details',           // REQUIRED
+    icon: <More />,                  // REQUIRED
+    onClick: () => {                 // REQUIRED
+      // Your custom row click logic here
+      console.log('Row clicked:', item);
+
+      // Example: Show a custom modal, perform an action, etc.
+      // You can access all SDK utilities here (see SDK Utilities section)
+      const optimisticActions = sdk.getOptimisticActions(sdk.collectionId);
+      const schema = sdk.getSchema(sdk.collectionId);
+
+      // Your custom logic...
+    },
+  };
+};
+```
+
+### Common Use Cases and Complete Examples
+
+#### 1. Opening a Side Panel Modal
+
+This is a complete working example for opening a side panel when clicking a row:
+
+**Step 1: Create the row click action** (`components/actions/openSidePanel.tsx`):
+```typescript
+import { CustomActionCollectionPageActionOnRowClickResolver } from '@wix/auto-patterns';
+import React from 'react';
+import { More } from '@wix/wix-ui-icons-common';
+
+export const openSidePanel: CustomActionCollectionPageActionOnRowClickResolver = (params) => {
+  const { actionParams, sdk } = params;
+  const { item } = actionParams;
+
+  return {
+    label: 'View Details',
+    icon: <More />,
+    onClick: () => {
+      // Open a custom modal with the item data
+      // You need to implement the modal opening mechanism
+      // This could be through a modal context, state management, etc.
+      console.log('Opening side panel for:', item);
+
+      // Example: Using a global modal state (you need to implement this)
+      // window.dispatchEvent(new CustomEvent('openSidePanel', { detail: item }));
+
+      // Or use a modal service/context that you've set up
+      // modalService.openSidePanel(item);
+    },
+  };
+};
+```
+
+**Step 2: Configure in JSON**:
+```json
+{
+  "type": "Table",
+  "table": {
+    "onRowClick": {
+      "id": "openSidePanel",
+      "type": "custom"
+    },
+    "columns": [...]
+  }
+}
+```
+
+**Step 3: Export and Register**:
+```typescript
+// components/actions/index.tsx
+export * from './openSidePanel';
+
+// page.tsx
+import * as actions from './components/actions';
+
+<PatternsWizardOverridesProvider value={{ actions }}>
+  <AutoPatternsApp configuration={config as AppConfig} />
+</PatternsWizardOverridesProvider>
+```
+
+#### 2. Direct Data Manipulation
+
+```typescript
+export const quickToggle: CustomActionCollectionPageActionOnRowClickResolver = (params) => {
+  const { actionParams, sdk } = params;
+  const { item } = actionParams;
+
+  return {
+    label: 'Quick Toggle',
+    icon: <Toggle />,
+    onClick: () => {
+      const optimisticActions = sdk.getOptimisticActions(sdk.collectionId);
+      const schema = sdk.getSchema(sdk.collectionId);
+
+      // Example: Toggle a boolean field
+      const updatedItem = { ...item, isActive: !item.isActive };
+
+      optimisticActions.updateOne(updatedItem, {
+        submit: async (items) => schema.actions.update(items[0]),
+        successToast: `${item.name} toggled successfully`,
+        errorToast: (err, {retry}) => ({
+          text: 'Toggle failed',
+          action: { text: 'Retry', onClick: retry }
+        })
+      });
+    },
+  };
+};
+```
+
+### Default vs Custom Behavior
+
+**Default Behavior (when `onRowClick` is not configured):**
+- Clicking a row automatically navigates to the entity page
+- Uses the `entityPageId` configuration to determine the target page
+- Passes the selected item's data to the entity page
+
+**Custom Behavior (when `onRowClick` is configured):**
+- Default navigation is **disabled**
+- Your custom action function is executed instead
+- You have complete control over the row click behavior
+- You can still navigate to the entity page programmatically if needed using the SDK navigation utilities
+
+### Key Points for Custom Row Click Actions:
+- **MANDATORY IMPLEMENTATION**: If you configure `onRowClick` in JSON, you MUST provide a complete working implementation - the framework cannot function without it
+- The action `id` in the configuration MUST exactly match the function name exported from your actions folder
+- The implementation must use the `CustomActionCollectionPageActionOnRowClickResolver` type
+- **Required Return Object**: Must return an object with `label`, `icon`, and `onClick` properties - all are required
+- Access the clicked item's data through `actionParams.item`
+- The implementation must be exported as a named export and registered in your `PatternsWizardOverridesProvider`
+- When `onRowClick` is configured, the default navigation to entity page is completely disabled
+- **Complete Setup Required**: You need to create the action file, export it in the index, and register it in the provider - missing any step will cause errors
+
+## Validation Checklist for Collection Page Actions
+
+✓ Every collection page must include a create action.
+✓ `actions` is an optional property of `collectionPage`.
+✓ `primaryActions` and `secondaryActions` (if defined) have a valid `type` ("action" or "menu").
+✓ If `type: "action"`, `action.item` is a valid action item configuration.
+✓ If `type: "menu"`, `menu.items` is an array of valid action item configurations that can include dividers.
+✓ Each action item contains a unique `id`, and the full `collection` object (`collectionId`, `entityTypeSource: 'cms'`).
+✓ Each action item has a supported `type` (`create`, `custom`) and its corresponding configuration block (e.g., `create` block for `type: "create"`).
+✓ `create` actions specify a `create.page.id` that matches an existing `entityPage` ID in the configuration.
+✓ `custom` actions (identified by their main `id`) correspond to an action resolver function name registered in the `actions` override.
+✓ Divider actions use `{ "type": "divider" }` format and require no additional properties.
+✓ If `onRowClick` is configured in table layout, it must have a valid `id` and `type: "custom"`.
+✓ **CRITICAL**: Custom row click actions must have corresponding implementations registered in the `actions` override - configuration without implementation will cause errors.
+✓ Custom row click action implementations must return an object with `label`, `icon`, and `onClick` properties - all are required.
+✓ Custom row click action implementations must be exported as named exports and included in the actions index file.
+✓ `onRowClick` is optional - when not configured, rows navigate to entity page by default.
+✓ **IMPORTANT**: Configuring `onRowClick` completely disables default navigation - you must handle all row click logic in your custom implementation.