@wix/auto-patterns 1.25.0 → 1.27.0

package/dist/docs/bulk_actions.md

@@ -174,11 +174,8 @@ Custom bulk actions execute JavaScript code that you define for bulk operations.
    - 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
-   - `hidden` (optional): Boolean to hide the action when true
+2. The implementation must return a `ResolvedAction`:
+   For complete field documentation, see [ResolvedAction Reference](./resolved_action.md).
 
 3. The implementation must:
    - Use the correct type: `CustomBulkActionsActionResolver`

package/dist/docs/collection_page.md

@@ -1,6 +1,6 @@
 # Collection Page Configuration
 
-## ⚠️ Collection Page Rules
+## 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

package/dist/docs/collection_page_actions.md

@@ -1,6 +1,6 @@
 # Collection Page Actions
 
-## ⚠️ Required 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
 
@@ -64,7 +64,7 @@ Custom collection page actions execute JavaScript code that you define for colle
    ```typescript
    import { CustomActionCollectionPageActionResolver } from '@wix/auto-patterns';
    import React from 'react';
-   import { Download } from '@wix/ui-icons-common';
+   import { Download } from '@wix/wix-ui-icons-common';
 
    // IMPORTANT: Function name MUST match the action id in your configuration
    export const exportCollection: CustomActionCollectionPageActionResolver = (params) => {
@@ -184,16 +184,7 @@ Row click actions are configured at the table level using the `onRowClick` prope
 
 ⚠️ **CRITICAL**: When you configure `onRowClick` in your TypeScript configuration, 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
-};
-```
+Custom row click actions use the `CustomActionCollectionPageActionOnRowClickResolver` type and MUST return a `ResolvedAction`. See [ResolvedAction Reference](./resolved_action.md) for complete field documentation.
 
 #### Complete Implementation Example:
 
@@ -353,7 +344,7 @@ export const quickToggle: CustomActionCollectionPageActionOnRowClickResolver = (
 - **MANDATORY IMPLEMENTATION**: If you configure `onRowClick` in TypeScript configuration, 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
+- **Required Return Object**: Must return a `ResolvedAction` object - see [ResolvedAction Reference](./resolved_action.md)
 - 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

package/dist/docs/custom_overrides.md

@@ -1,6 +1,6 @@
 # Custom Overrides
 
-## ⚠️ Override Rules
+## Override Rules
 
 - **Custom overrides are restricted to the defined areas only** - attempting to override or modify any other aspect of `AutoPatternsApp` is prohibited and can cause unexpected behavior
 - **Always verify override implementation** - when implementing custom overrides, you MUST ensure they are correctly imported and passed to the `PatternsWizardOverridesProvider`
@@ -42,9 +42,15 @@ your-page/
     ├── customDataSources/             // Custom data sources
     │   ├── index.tsx                  // Exports useCustomDataSources hook
     │   └── myCustomDataSource.ts
-    └── sections/                      // Section renderers
-        ├── index.tsx
-        └── groupByType.ts
+    ├── sections/                      // Section renderers
+    │   ├── index.tsx
+    │   └── groupByType.ts
+    ├── entityPageHeaderSubtitle/      // Entity page dynamic subtitle functions
+    │   ├── index.tsx                  // Exports useEntityPageHeaderSubtitle hook
+    │   └── mySubtitle.ts
+    └── entityPageHeaderBadges/        // Entity page dynamic badges functions
+        ├── index.tsx                  // Exports useEntityPageHeaderBadges hook
+        └── myBadges.ts
 ```
 
 ### Using Override Hooks in Your Page
@@ -59,6 +65,8 @@ import { useSections } from '../components/sections';
 import { useComponents } from '../components/customComponents';
 import { useModals } from '../components/modals';
 import { useCustomDataSources } from '../components/customDataSources';
+import { useEntityPageHeaderSubtitle } from '../components/entityPageHeaderSubtitle';
+import { useEntityPageHeaderBadges } from '../components/entityPageHeaderBadges';
 
 export default function YourPage() {
   const actions = useActions();
@@ -68,9 +76,11 @@ export default function YourPage() {
   const components = useComponents();
   const modals = useModals();
   const customDataSources = useCustomDataSources();
+  const entityPageHeaderSubtitle = useEntityPageHeaderSubtitle();
+  const entityPageHeaderBadges = useEntityPageHeaderBadges();
 
   return (
-    <PatternsWizardOverridesProvider value={{ actions, columns, slots, sections, components, modals, customDataSources }}>
+    <PatternsWizardOverridesProvider value={{ actions, columns, slots, sections, components, modals, customDataSources, entityPageHeaderSubtitle, entityPageHeaderBadges }}>
       <AutoPatternsApp configuration={config} />
     </PatternsWizardOverridesProvider>
   );
@@ -89,10 +99,12 @@ For example:
 - 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
+- Adding a new subtitle override → Update `../components/entityPageHeaderSubtitle/index.tsx` to include the new subtitle in the `useEntityPageHeaderSubtitle` hook
+- Adding a new badges override → Update `../components/entityPageHeaderBadges/index.tsx` to include the new badges in the `useEntityPageHeaderBadges` hook
 
 Without updating the hook index files, your implementations won't be available to the `PatternsWizardOverridesProvider`.
 
-## ⚠️ Common Override Mistakes to Avoid
+## Common Override Mistakes to Avoid
 
 - Attempting to override unsupported areas
 - Invalid column rendering functions

package/dist/docs/entity_page.md

@@ -1,6 +1,6 @@
 # Entity Page Configuration
 
-## ⚠️ Entity Page Requirements
+## Entity Page Requirements
 
 All entity pages must have:
 - **A route path with descriptive segment and dynamic parameter** (e.g., `/product/:entityId`, `/pet/:entityId`) - **never just `/:entityId`** as this conflicts with collection page routing
@@ -12,6 +12,20 @@ All entity pages must have:
 * Displays details for a **single entity**.
 * Always tied to a single Wix collection.
 * Supports **two distinct modes**: **view mode** and **edit mode** with separate page configurations.
+* Supports **dynamic subtitle** that adapt based on entity data (see [Entity Page Dynamic Subtitle](#entity-page-dynamic-subtitle)).
+* Supports **dynamic badges** in the page title that adapt based on entity data (see [Entity Page Dynamic Badges](#entity-page-dynamic-badges)).
+
+## 🏷️ **Understanding Badges Requests**
+
+When a user asks to "add badges to the entity page", understand that they want:
+
+1. **Custom component overrides** - NOT direct configuration in JSON
+2. **Function that returns badge objects** - NOT JSX components
+3. **Badge properties** like `text`, `skin`, `prefixIcon`, etc.
+4. **Registration in PatternsWizardOverridesProvider** under `entityPageHeaderBadges`
+
+**Example Request**: "Add 2 badges with random skins and text 'wow'"
+**Correct Implementation**: Create a function that returns `[{text: 'wow', skin: 'success'}, {text: 'wow', skin: 'premium'}]`
 
 ## Entity Page Modes
 
@@ -40,6 +54,284 @@ This pattern allows:
 - Clear distinction between view and edit URLs
 - Natural navigation flow between modes
 
+## Entity Page Dynamic Subtitle
+
+Entity pages support dynamic subtitles that adapt based on entity data, providing contextual information below the main title.
+
+### Configuration
+
+Add an `id` property to the entity page subtitle configuration:
+
+```json
+{
+  "subtitle": {
+    "text": "Default subtitle text",
+    "id": "mySubtitleOverride"
+  }
+}
+```
+
+### Subtitle Override Implementation
+
+Create a subtitle override function that returns an object with a `text` property:
+
+```typescript
+const mySubtitleOverride = (entity: Record<string, any>): { text: string } => {
+  return { text: `Pet: ${entity.name || 'Unknown'}` };
+};
+```
+
+### Complete Implementation Guide
+
+#### Step 1: Create the Subtitle Function
+
+**File**: `src/dashboard/components/entityPageHeaderSubtitle/entityPageHeaderSubtitle.ts`
+
+```typescript
+export const entityPageHeaderSubtitle = (entity: Record<string, any>): { text: string } => {
+  return { text: `Pet: ${entity.name || 'Unknown'}` };
+};
+```
+
+#### Step 2: Create/Update Index File
+
+**File**: `src/dashboard/components/entityPageHeaderSubtitle/index.ts`
+
+```typescript
+import { entityPageHeaderSubtitle } from './entityPageHeaderSubtitle';
+
+export const useEntityPageHeaderSubtitle = () => {
+  return entityPageHeaderSubtitle;
+};
+```
+
+#### Step 3: Update Main Page Overrides
+
+**File**: `src/dashboard/pages/page.tsx`
+
+```typescript
+import { useEntityPageHeaderSubtitle } from '../components/entityPageHeaderSubtitle';
+
+const Index: FC = () => {
+  const entityPageHeaderSubtitle = useEntityPageHeaderSubtitle();
+
+  return (
+    <PatternsWizardOverridesProvider
+      value={{
+        // ... other overrides
+        entityPageHeaderSubtitle: {
+          entityPageHeaderSubtitle,
+        },
+      }}
+    >
+      <WixPetsPage />
+    </PatternsWizardOverridesProvider>
+  );
+};
+```
+
+#### Step 4: Update Configuration
+
+**File**: `src/dashboard/pages/wixPetsConfig.patterns.ts`
+
+```typescript
+{
+  id: 'wixPets-entity',
+  type: 'entityPage',
+  entityPage: {
+    subtitle: {
+      text: 'Default subtitle text',
+      id: 'entityPageHeaderSubtitle', // ⚠️ CRITICAL: This must match the override key
+    },
+    // ... rest of config
+  },
+}
+```
+
+### Required File Structure
+
+```
+src/dashboard/
+├── components/
+│   └── entityPageHeaderSubtitle/
+│       ├── index.ts                    # ✅ MUST EXIST (hook exports)
+│       └── entityPageHeaderSubtitle.ts # ✅ MUST EXIST (subtitle function)
+├── pages/
+│   ├── page.tsx                        # ✅ MUST REGISTER OVERRIDES
+│   └── wixPetsConfig.patterns.ts       # ✅ MUST HAVE SUBTITLE CONFIG
+```
+
+
+**Example**:
+```typescript
+// Config
+subtitle: { id: 'mySubtitleOverride' }
+
+// Overrides
+entityPageHeaderSubtitle: { mySubtitleOverride: myFunction }
+
+// Function
+export const myFunction = (entity) => { ... }
+```
+
+### Integration
+
+Register your subtitle override in the `PatternsWizardOverridesProvider`:
+
+```typescript
+<PatternsWizardOverridesProvider value={{
+  entityPageHeaderSubtitle: {
+    mySubtitleOverride,
+  },
+}}>
+  <AutoPatternsApp configuration={config} />
+</PatternsWizardOverridesProvider>
+```
+
+## Entity Page Dynamic Badges
+
+Entity pages support dynamic badges in the page title that display contextual information about the entity.
+
+
+### Badge Skin Options
+
+The `skin` property accepts values from the `BadgeSkin` type of `@wix/design-system`:
+
+### Badge Properties
+
+Each badge can have the following properties:
+
+```typescript
+{
+  text: string;                    // Required: Text to display
+  skin?: BadgeSkin;               // Optional: Visual styling
+  prefixIcon?: React.ReactElement; // Optional: Icon before text (from @wix/wix-ui-icons-common)
+  suffixIcon?: React.ReactElement; // Optional: Icon after text (from @wix/wix-ui-icons-common)
+}
+```
+
+
+## ⚠️ **CRITICAL: Understanding Badges Implementation**
+
+When implementing badges for entity pages, understand these key points:
+
+1. **Badges are CUSTOM COMPONENT OVERRIDES** - NOT direct configuration
+2. **Badge function returns an ARRAY of badge objects** - NOT JSX components
+3. **Each badge object has properties** like `text`, `skin`, `prefixIcon`, etc.
+4. **Must be registered in PatternsWizardOverridesProvider** under `entityPageHeaderBadges`
+
+### Complete Implementation Guide
+
+#### Step 1: Create the Badge Function
+
+**File**: `src/dashboard/components/entityPageHeaderBadges/entityPageHeaderBadges.ts`
+
+```typescript
+export const entityPageHeaderBadges = (entity: Record<string, any>) => {
+  // Define available badge skins
+  const badgeSkins = ['success', 'warning', 'destructive', 'neutral', 'premium'] as const;
+
+  // Get random skins for the two badges
+  const randomSkin1 = badgeSkins[Math.floor(Math.random() * badgeSkins.length)];
+  const randomSkin2 = badgeSkins[Math.floor(Math.random() * badgeSkins.length)];
+
+  return [
+    {
+      text: 'wow',
+      skin: randomSkin1,
+    },
+    {
+      text: 'wow',
+      skin: randomSkin2,
+    },
+  ];
+};
+```
+
+#### Step 2: Create/Update Index File
+
+**File**: `src/dashboard/components/entityPageHeaderBadges/index.ts`
+
+```typescript
+import { entityPageHeaderBadges } from './entityPageHeaderBadges';
+
+export const useEntityPageHeaderBadges = () => {
+  return entityPageHeaderBadges;
+};
+```
+
+#### Step 3: Update Main Page Overrides
+
+**File**: `src/dashboard/pages/page.tsx`
+
+```typescript
+import { useEntityPageHeaderSubtitle } from '../components/entityPageHeaderSubtitle';
+import { useEntityPageHeaderBadges } from '../components/entityPageHeaderBadges';
+
+const Index: FC = () => {
+  const entityPageHeaderSubtitle = useEntityPageHeaderSubtitle();
+  const entityPageHeaderBadges = useEntityPageHeaderBadges();
+
+  return (
+    <PatternsWizardOverridesProvider
+      value={{
+        // ... other overrides
+        entityPageHeaderSubtitle: {
+          entityPageHeaderSubtitle,
+        },
+        entityPageHeaderBadges: {
+          entityPageHeaderBadges, // ⚠️ CRITICAL: This must match the ID in config
+        },
+      }}
+    >
+      <WixPetsPage />
+    </PatternsWizardOverridesProvider>
+  );
+};
+```
+
+#### Step 4: Update Configuration
+
+**File**: `src/dashboard/pages/wixPetsConfig.patterns.ts`
+
+```typescript
+{
+  id: 'wixPets-entity',
+  type: 'entityPage',
+  entityPage: {
+    title: {
+      text: 'WixPet Details',
+      badges: {
+        id: 'entityPageHeaderBadges', // ⚠️ CRITICAL: This must match the override key
+      },
+    },
+    // ... rest of config
+  },
+}
+```
+
+### Required File Structure
+
+```
+src/dashboard/
+├── components/
+│   └── entityPageHeaderBadges/
+│       ├── index.ts                    # ✅ MUST EXIST (badges hook exports)
+│       └── entityPageHeaderBadges.ts   # ✅ MUST EXIST (badges function)
+├── pages/
+│   ├── page.tsx                        # ✅ MUST REGISTER OVERRIDES
+│   └── wixPetsConfig.patterns.ts       # ✅ MUST HAVE BADGES CONFIG
+```
+
+### ⚠️ **Common Badges Mistakes to Avoid**
+
+1. **❌ DON'T return JSX components** - Return badge objects instead
+2. **❌ DON'T use direct configuration** - Use custom component overrides
+3. **❌ DON'T forget to register in PatternsWizardOverridesProvider**
+5. **❌ DON'T forget to export from index.ts** - Must export the function
+
+
+
 ## View Mode: Purpose and API
 
 ### Purpose of View Mode
@@ -155,7 +447,7 @@ Entity page action configuration depends on the mode:
    - For image fields, consider providing more space (larger span)
    - Images are automatically rendered with proper controls when using the field type
 
-## ⚠️ Common Entity Page Layout Mistakes to Avoid
+## Common Entity Page Layout Mistakes to Avoid
 
 - Using incorrect span values causing unexpected layout breaks
 - Referencing non-existent field IDs in the layout

package/dist/docs/entity_page_actions.md

@@ -55,7 +55,7 @@ export const myMoreAction: CustomEntityPageActionResolver = (params) => {
 
   return {
     label: 'My More Action',
-    icon: <MyIcon />, // optional
+    icon: <MyIcon />, // required
     onClick: () => {
       // Your custom logic here
     },
@@ -75,7 +75,7 @@ export const myMoreAction: CustomEntityPageActionResolver = (params) => {
 - The implementation must use the `CustomEntityPageActionResolver` 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`).
+- The returned object must be a `ResolvedAction`. See [ResolvedAction Reference](./resolved_action.md) for complete documentation.
 
 ---
 
@@ -86,7 +86,7 @@ export const myMoreAction: CustomEntityPageActionResolver = (params) => {
 ✓ Custom actions match implementations in overrides
 ✓ The resolver is exported and registered in the `actions` property of your `PatternsWizardOverridesProvider`
 ✓ The function signature matches `CustomEntityPageActionResolver`
-✓ The returned object includes `label`, `onClick`, and optionally `icon`
+✓ The returned object is a `ResolvedAction` (see [ResolvedAction Reference](./resolved_action.md))
 
 ---
 

package/dist/docs/entity_page_view_actions.md

@@ -96,7 +96,7 @@ View mode actions follow the same resolver patterns as collection page actions:
 These actions are handled automatically by the AutoPatterns framework using the configuration provided.
 
 ### For Custom Actions
-Custom actions require resolver implementations:
+Custom actions require resolver implementations that return a `ResolvedAction` object. See [ResolvedAction Reference](./resolved_action.md) for complete field documentation.
 
 ```typescript
 import { CustomEntityPageActionResolver } from '@wix/auto-patterns/types';
@@ -107,7 +107,7 @@ export const duplicateProduct: CustomEntityPageActionResolver = (params) => {
   const schema = sdk.getSchema(sdk.collectionId);
   return {
     label: 'Duplicate Product',
-    icon: <DuplicateIcon />, // optional
+    icon: <DuplicateIcon />, // required
     onClick: async () => {
       // Your custom duplication logic here
       await schema.actions.create({

package/dist/docs/index.md

@@ -46,10 +46,22 @@ This index maps user requests to the appropriate section IDs for fetching releva
 **Topics**: Entity page edit mode actions, moreActions, custom entity actions
 **Keywords**: entity page actions, edit mode actions, moreActions, custom entity actions, entity-specific operations, action menus
 
+### ID: `entity_page_badges`
+**Topics**: Entity page badges, dynamic badges, badge configuration, badge overrides
+**Keywords**: badges, entity page badges, dynamic badges, badge configuration, badge overrides, title badges, header badges, badge skins, badge text, badge icons
+
+### ID: `entity_page_subtitle`
+**Topics**: Entity page dynamic subtitle, subtitle overrides, dynamic text generation
+**Keywords**: subtitle, entity page subtitle, dynamic subtitle, subtitle overrides, header subtitle, title subtitle, dynamic text, contextual subtitle, entity-based subtitle
+
 ### ID: `entity_page_view_actions`
 **Topics**: Entity page view mode actions, primaryActions, secondaryActions, collection-style actions
 **Keywords**: view mode actions, primaryActions, secondaryActions, read-only entity actions, entity page view operations, collection-style entity actions, navigation actions
 
+### ID: `resolved_action`
+**Topics**: ResolvedAction interface, common return type for custom actions, field documentation
+**Keywords**: ResolvedAction, action return type, custom action interface, action fields, label, icon, onClick, disabled, hidden, tooltip, skin
+
 ### 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

package/dist/docs/installation.md

@@ -2,13 +2,36 @@
 
 ## 1. Install Packages
 
-Install if necessary and doesn't exists in package.json:
+Install if doesn't exists in package.json:
 
 ```bash
 npm install @wix/auto-patterns @wix/patterns @wix/design-system
 ```
 
-## ⚠️ Critical Import Rules
+### React Router dependency
+
+`react-router-dom` is required. Install a version that matches your React version:
+
+- React 16.x (and 17.x): use `react-router-dom@^6`
+- React 18+ : use `react-router-dom@^7`
+
+Check your React version:
+
+```bash
+npm ls react --depth=0
+```
+
+Then install the matching router version:
+
+```bash
+# For React 16.x or 17.x
+npm install react-router-dom@^6
+
+# For React 18+
+npm install react-router-dom@^7
+```
+
+## 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

package/dist/docs/pages_configuration.md

@@ -1,6 +1,6 @@
 # Pages Configuration
 
-## ⚠️ Critical Page Rules
+## 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
@@ -81,7 +81,7 @@ A two-way connection must be established between collection pages and entity pag
 * **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 Route and Configuration Mistakes to Avoid
+## Common Route and Configuration Mistakes to Avoid
 
 - Missing route.params for entity pages
 - Using `/:entityId` instead of `/segment/:entityId` for entity page routes (causes routing conflicts)

package/dist/docs/resolved_action.md

@@ -0,0 +1,106 @@
+# ResolvedAction: Common Return Type for Custom Actions
+
+All custom action resolvers in Auto Patterns must return a `ResolvedAction`. This applies to:
+- Collection page actions (primary, secondary, menus) and `onRowClick`
+- Entity page actions (view mode: primary/secondary/more; edit mode: moreActions)
+- Bulk action toolbar actions
+- Action Cell actions
+
+## Type Definition
+
+From `@wix/auto-patterns`:
+
+```typescript
+export interface ResolvedAction {
+  label: string;
+  icon: IconElement;
+  onClick: () => void;
+  disabled?: boolean;
+  hidden?: boolean;
+  tooltip?: string;
+  skin?: string;
+}
+```
+
+## Field Reference
+
+### Required Fields
+
+- **`label`** (string): Text displayed in the button or menu item.
+- **`icon`** (IconElement): An icon component, typically from `@wix/wix-ui-icons-common`. Example: `icon: <Delete />`.
+- **`onClick`** (function): Handler function invoked when the user triggers the action. Can be async.
+
+### Optional Fields
+
+- **`disabled`** (boolean): When `true`, renders the action as disabled. Pair with `tooltip` to explain why the action is unavailable.
+- **`hidden`** (boolean): When `true`, the action is completely omitted from the UI. Useful for permission-based or state-based visibility control.
+- **`tooltip`** (string): Tooltip text displayed on hover. Especially useful when the action is disabled.
+- **`skin`** (string): Visual style of the action button. Availability may vary by placement context. Recommended values:
+  - Primary actions: `"standard"`, `"inverted"`, `"premium"`
+  - Secondary/more/menu items: `"dark"`, `"destructive"`, `"premium"`
+  - If unsure, omit `skin` or use `"standard"` for primary actions and `"dark"` for secondary actions.
+
+## Examples
+
+### Minimal Example
+
+```typescript
+import { Add } from '@wix/wix-ui-icons-common';
+
+return {
+  label: 'Create',
+  icon: <Add />,
+  onClick: () => {
+    // Your action logic here
+  }
+};
+```
+
+### Complete Example with State Control
+
+```typescript
+import { Download } from '@wix/wix-ui-icons-common';
+
+return {
+  label: 'Export',
+  icon: <Download />,
+  onClick: async () => {
+    try {
+      // Perform export logic using SDK
+      await performExport();
+    } catch (error) {
+      // Handle errors, show toast, etc.
+    }
+  },
+  disabled: total === 0,
+  tooltip: total === 0 ? 'Select at least one item to export' : undefined,
+  hidden: !userHasExportPermission,
+  skin: 'premium'
+};
+```
+
+## Context-Specific Notes
+
+### Collection Page Actions
+- **onRowClick**: Access clicked item data via `actionParams.item`
+- **Collection-level actions**: Access collection context via `actionParams.collectionId`
+
+### Entity Page Actions
+- **View/Edit mode**: Access entity data via `actionParams.entity`
+- **Edit mode only**: Access form instance via `actionParams.form`
+
+### Bulk Actions
+- **Selection data**: Use `actionParams.selectedValues` and `actionParams.total`
+- **State control**: Commonly use `disabled: selectedValues.length === 0`
+
+### Action Cell Actions
+- **Row context**: Access item and position via `actionParams.item` and `actionParams.index`
+
+## See Also
+
+- [Collection Page Actions](./collection_page_actions.md)
+- [Entity Page Actions](./entity_page_actions.md) (edit mode)
+- [Entity Page View Actions](./entity_page_view_actions.md)
+- [Bulk Actions Toolbar](./bulk_actions.md)
+- [Action Cell](./action_cell.md)
+- [App Config Structure](./app_config_structure.md) (action item `skin` property)