@dotcms/uve 0.0.1-beta.33 → 0.0.1-beta.35

package/README.md

@@ -1,324 +1,589 @@
-# DotCMS UVE SDK
+# dotCMS UVE SDK
 
-A JavaScript library to connect your dotCMS pages with the Universal Visual Editor (UVE) and enable content authors to edit pages in real time.
+The `@dotcms/uve` SDK adds live editing to your JavaScript app using the dotCMS Universal Visual Editor (UVE). It provides low-level tools that power our framework-specific SDKs, such as [`@dotcms/react`](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/react/README.md) and [`@dotcms/angular`](https://github.com/dotCMS/core/blob/main/core-web/libs/sdk/angular/README.md).
 
-> **BETA VERSION NOTICE:** This SDK is currently in beta. APIs, functionality, and documentation may change significantly in the stable release.
+> ⚠️ We **do not recommend using this SDK directly** for most use cases, you should use a [framework SDK that handles setup](#Getting Started: Recommended Examples), rendering, and event wiring for you.
+
+With `@dotcms/uve`, framework SDKs are able to:
+- Make pages and contentlets editable
+- Respond to editor events (content updates, mode changes)
+- Trigger modal or inline editing experiences
+- Sync app routing with the dotCMS editor
 
 ## Table of Contents
 
-- [Installation](#installation)
-- [Entry Points](#entry-points)
-- [Getting Started](#getting-started)
-- [API Reference](#api-reference)
-  - [Editor State](#editor-state)
-  - [Event Subscriptions](#event-subscriptions)
-  - [Content Editing](#content-editing)
-  - [Navigation & UI](#navigation--ui)
-  - [Messaging](#messaging)
-- [Types Reference](#types-reference)
-- [Examples](#examples)
-- [Contributing](#contributing)
-- [License](#license)
+-   [Before You Use @dotcms/uve](#before-you-use-dotcmsuve)
+    -   [Getting Started: Recommended Examples](#getting-started-recommended-examples)
+    -   [🚩 Custom Setup: Manual Rendering (Not Recommended)](#-custom-setup-manual-rendering-not-recommended)
+-   [Prerequisites & Setup](#prerequisites--setup)
+    -   [Get a dotCMS Environment](#get-a-dotcms-environment)
+    -   [Create a dotCMS API Key](#create-a-dotcms-api-key)
+    -   [Installation](#installation)
+    -   [Using the SDK with TypeScript](#using-the-sdk-with-typescript)
+-   [SDK Reference](#sdk-reference)
+    -   [`initUVE()`](#inituveconfig-dotcmsuveconfig)
+    -   [`getUVEState()`](#getuvestate)
+    -   [`createUVESubscription()`](#createuvesubscriptioneventtype-callback)
+    -   [`editContentlet()`](#editcontentletcontentlet)
+    -   [`initInlineEditing()`](#initinlineeditingtype-data)
+    -   [`enableBlockEditorInline()`](#enableblockeditorinlinecontentlet-fieldname)
+    -   [`updateNavigation()`](#updatenavigationpathname)
+    -   [`reorderMenu()`](#reordermenuconfig)
+    -   [`sendMessageToUVE()`](#sendmessagetouvemessage)
+-   [Troubleshooting](#troubleshooting)
+    -   [Common Issues & Solutions](#common-issues--solutions)
+    -   [Debugging Tips](#debugging-tips)
+    -   [Still Having Issues?](#still-having-issues)
+-   [dotCMS Support](#dotcms-support)
+-   [How To Contribute](#how-to-contribute)
+-   [Licensing Information](#licensing-information)
+-   [Troubleshooting](#troubleshooting)
+
+## Before You Use @dotcms/uve
+
+### Getting Started: Recommended Examples
+
+We strongly recommend using one of our official framework SDKs, which are designed to handle UVE integration, routing, rendering, and more—out of the box. These examples are the best way to get started:
+
+-   [dotCMS Angular SDK: Angular Example](https://github.com/dotCMS/core/tree/main/examples/angular) – Ideal for Angular apps 🅰️
+-   [dotCMS React SDK: NextJS Example](https://github.com/dotCMS/core/tree/main/examples/react) – Ideal for NextJS projects ⚛️
+-   [dotCMS React SDK: Astro Example](https://github.com/dotCMS/core/tree/main/examples/astro) – Ideal for Astro projects 🌌
+
+These examples handle UVE integration, routing, rendering, and more—out of the box. **If you're building a headless dotCMS front-end, start there.**
+
+### 🚩 Custom Setup: Manual Rendering (Not Recommended)
+
+> 💡 We recommend using one of our official framework SDKs, which are designed to handle UVE integration, routing, rendering, and more—out of the box.
+
+You can use `@dotcms/uve` directly, but **it’s not recommended or supported** unless you’re building a highly custom integration. Here’s how the pieces fit together:
+
+1. **You must use `@dotcms/client` to fetch content and page data.**
+2. **You must render pages based on dotCMS’s layout schema.**
+3. **You must apply the correct `data-dot-*` attributes to containers and contentlets.**
+
+Here's a minimal setup using `@dotcms/client` and `@dotcms/uve`:
+
+1. Initializa the Client and get the page response:
+
+```ts
+// getPage.ts
+import { createDotCMSClient } from '@dotcms/client/next';
+import { initUVE, createUVESubscription } from '@dotcms/uve/next';
+
+const dotCMSClient = createDotCMSClient({
+    dotcmsUrl: 'https://your-dotcms-instance.com',
+    authToken: 'your-api-key',
+    siteId: 'your-site-id'
+});
 
-## Installation
+const getPage = async () => {
+    const pageResponse = await dotCMSClient.page.get('/', {
+        languageId: '1'
+    });
 
-The UVE SDK is automatically included in DotCMS installations. For external usage:
+    return pageResponse;
+};
+```
 
-```bash
-# Using npm
-npm install @dotcms/uve-sdk
+2. Initialize the UVE and subscribe to changes:
 
-# Using yarn
-yarn add @dotcms/uve-sdk
-```
+> ⚠️ The `initUVE()` function only works with a `PageResponse` returned by `@dotcms/client`. If you try to pass in data from another source or build your own structure, it won't initialize properly.
+
+```ts
+import { initUVE, createUVESubscription } from '@dotcms/uve/next';
+import { getPage } from './getPage';
 
-## Entry Points
+const pageResponse = await getPage();
 
-The library exposes three main entry points:
+initUVE(pageResponse);
+createUVESubscription('changes', (newPageResponse) => {
+    // Handle page updates (e.g. re-render)
+});
+```
 
-- **`@dotcms/uve`**: Provides everything developers need to communicate with UVE.
+> ⚠️ This only sets up the editor connection. You are responsible for rendering the page structure (rows, columns, containers, contentlets) using your own UI components.
 
-- **`@dotcms/uve/types`**: Offers TypeScript types, interfaces, and other structures to help users organize their code properly.
+3. Create a custom render for the page:
 
-## Getting Started
+```tsx
+// 🔧 Render the page layout (you must implement this component)
+<MyDotCMSPage pageAsset={pageResponse.pageAsset} />
+```
 
-To use the UVE SDK in your project, import the necessary functions:
+> ⚠️ Below is a simplified breakdown of how dotCMS layouts are structured and how you might render them manually.
+
+#### 🔄 How to Render a dotCMS Page
+
+> 📚 For a complete guide, here is a full tutorial:
+> 👉 [dotCMS Page Rendering Architecture]( https://dev.dotcms.com/docs/dotcms-page-rendering-architecture)
+
+dotCMS pages are structured as nested layout objects:
+
+-   A `PageAsset` contains a `layout` object
+-   The `layout` includes rows, columns, containers, and contentlets
+
+Here’s a basic pseudocode outline:
+
+```jsx
+<Page>
+  {layout.body.rows.map(row => (
+    <Row>
+      {row.columns.map(column => (
+        <Column>
+          {column.containers.map(container => (
+            <Container data-dot-object="container" ...>
+              {container.contentlets.map(contentlet => (
+                <Contentlet data-dot-object="contentlet" ...>
+                  {renderContentletByType(contentlet)}
+                </Contentlet>
+              ))}
+            </Container>
+          ))}
+        </Column>
+      ))}
+    </Row>
+  ))}
+</Page>
+```
 
-```typescript
-import { getUVEState, createUVESubscription, editContentlet } from '@dotcms/uve';
-import { UVEEventType, UVE_MODE } from '@dotcms/uve/types';
-
-// Check if we're in the editor
-const uveState = getUVEState();
-if (uveState?.mode === UVE_MODE.EDIT) {
-  console.log('Running in edit mode!');
-  
-  // Subscribe to content changes
-  const subscription = createUVESubscription(UVEEventType.CONTENT_CHANGES, (changes) => {
-    console.log('Content updated:', changes);
-    // Update your UI with the new content
-  });
-  
-  // Later, when no longer needed
-  subscription.unsubscribe();
+Each contentlet is rendered according to its content type:
+
+```ts
+function renderContentletByType(contentlet) {
+  switch(contentlet.contentType) {
+    case 'text': return <TextBlock contentlet={contentlet} />;
+    case 'image': return <ImageBlock contentlet={contentlet} />;
+    case 'video': return <VideoBlock contentlet={contentlet} />;
+    default: return null;
+  }
 }
 ```
 
-## API Reference
+To make the layout editable, be sure to apply all required `data-dot-*` attributes on containers and contentlets.
 
-### Editor State
+## Prerequisites & Setup
 
-#### `getUVEState`
+### Get a dotCMS Environment
 
-Retrieves the current UVE state.
+#### Version Compatibility
 
-**Returns:**
-- A `UVEState` object if running inside the editor, or `undefined` otherwise.
+-   **Recommended**: dotCMS Evergreen
+-   **Minimum**: dotCMS v25.05
+-   **Best Experience**: Latest Evergreen release
 
-The state includes:
-- `mode`: The current editor mode (preview, edit, live).
-- `languageId`: The language ID of the current page set in the UVE.
-- `persona`: The persona of the current page set in the UVE.
-- `variantName`: The name of the current variant.
-- `experimentId`: The ID of the current experiment.
-- `publishDate`: The publish date of the current page set in the UVE.
+#### Environment Setup
 
-> **Note:** If any of these properties are absent, it means the value is the default one.
+**For Production Use:**
 
-**Example:**
-```typescript
-const editorState = getUVEState();
-if (editorState?.mode === 'edit') {
-  // Enable editing features
-}
-```
+-   ☁️ [Cloud hosting options](https://www.dotcms.com/pricing) - managed solutions with SLA
+-   🛠️ [Self-hosted options](https://dev.dotcms.com/docs/current-releases) - deploy on your infrastructure
 
-### Event Subscriptions
+**For Testing & Development:**
 
-#### `createUVESubscription`
+-   🧑🏻‍💻 [dotCMS demo site](https://demo.dotcms.com/dotAdmin/#/public/login) - perfect for trying out the SDK
+-   📘 [Learn how to use the demo site](https://dev.dotcms.com/docs/demo-site)
+-   📝 Read-only access, ideal for building proof-of-concepts
 
-Subscribe to page changes and other UVE events. Receive a callback that will be called with the updated content of the page.
+**For Local Development:**
 
-**Parameters:**
-- `eventType` - The type of event to subscribe to.
-- `callback` - The callback function that will be called when the event occurs.
+-   🐳 [Docker setup guide](https://github.com/dotCMS/core/tree/main/docker/docker-compose-examples/single-node-demo-site)
+-   💻 [Local installation guide](https://dev.dotcms.com/docs/quick-start-guide)
 
-**Returns:**
-- An event subscription that can be used to unsubscribe.
+### Configure The Universal Visual Editor App
 
-**Example:**  
-```typescript
-// Subscribe to page changes
-const subscription = createUVESubscription(UVEEventType.CONTENT_CHANGES, (changes) => {
-  console.log('Content changes:', changes);
-});
+For a step-by-step guide on setting up the Universal Visual Editor, check out our [easy-to-follow instructions](https://dev.dotcms.com/docs/uve-headless-config) and get started in no time!
+
+### Installation
 
-// Later, unsubscribe when no longer needed
-subscription.unsubscribe();
+```bash
+npm install @dotcms/uve@next
 ```
 
-### Content Editing
+### Using the SDK with TypeScript
 
-#### `editContentlet`
+All interfaces and types are available through the `@dotcms/types` package:
 
-Allows you to edit a contentlet in the editor.
+```bash
+npm install @dotcms/types@next --save-dev
+```
 
-Calling this function within the editor prompts the UVE to open a dialog to edit the specified contentlet.
+#### Common Types
 
-**Parameters:**
-- `contentlet<T>` - The contentlet to edit.
+The SDK uses several key types from `@dotcms/types`:
 
-**Example:**
 ```typescript
-// Edit a contentlet
-editContentlet(myContentlet);
+import {
+    DotCMSContentlet,
+    DotCMSPageResponse,
+    DotCMSUVEConfig,
+    DotCMSInlineEditingType,
+    UVEEventType,
+    UVEState
+} from '@dotcms/types';
 ```
 
-#### `initInlineEditing`
+For a complete reference of all available types and interfaces, please refer to the [@dotcms/types documentation](https://www.npmjs.com/package/@dotcms/types).
 
-Initializes inline editing in the editor.
+## SDK Reference
 
-**Parameters:**
-- `type` - The type of inline editing ('BLOCK_EDITOR' or 'WYSIWYG').
-- `data` - (Optional) Data for the inline editing session.
+### `initUVE(config?: DotCMSUVEConfig)`
 
-**Example:**
-```typescript
-// Initialize block editor
-initInlineEditing('BLOCK_EDITOR', {
-  inode: 'abc123',
-  language: 1,
-  contentType: 'Blog',
-  fieldName: 'body',
-  content: { /* content data */ }
-});
+`initUVE` is a function that initializes the Universal Visual Editor (UVE). It sets up the necessary communication between your app and the editor, enabling seamless integration and interaction.
+
+| Input    | Type                 | Required | Description                                 |
+| -------- | -------------------- | -------- | ------------------------------------------- |
+| `config` | `DotCMSPageResponse` | ✅       | The page Response from the `@dotcms/client` |
+
+#### Usage
+
+```ts
+const { destroyUVESubscriptions } = initUVE(pageResponse);
 ```
 
-### Navigation & UI
+> ⚠️ If you don't provide a `pageResponse`, we can't assure that the UVE will be initialized correctly.
 
-#### `reorderMenu`
+### `getUVEState()`
 
-Reorders the menu based on the provided configuration.
+`getUVEState` is a function that returns the [UVE state](#uve-state) if UVE is active.
 
-**Parameters:**
-- `config` (optional): Configuration for reordering the menu.
-  - `startLevel` (default: `1`): The starting level of the menu to reorder.
-  - `depth` (default: `2`): The depth of the menu to reorder.
+#### Usage
 
-This function constructs a URL for the reorder menu page with the specified `startLevel` and `depth`, then sends a message to the editor to perform the reorder action.
+```tsx
+import { getUVEState } from '@dotcms/uve';
+import { UVE_MODE } from '@dotcms/types';
 
-**Example:**
-```typescript
-// Reorder menu starting from level 2 with depth of 3
-reorderMenu({ startLevel: 2, depth: 3 });
+const myEditButton = () => {
+    const uveState = getUVEState();
+
+    if (uveState?.mode === UVE_MODE.EDIT) {
+        return <button>Edit</button>;
+    }
+
+    return null;
+};
 ```
 
-### Messaging
+#### UVE State
 
-#### `sendMessageToUVE`
+-   `dotCMSHost`: The host URL of the DotCMS instance
+-   `experimentId`: The ID of the current experiment
+-   `languageId`: The language ID of the current page set on the UVE
+-   `mode`: The current editor mode (`'preview'`, `'edit'`, `'live'`)
+-   `persona`: The persona of the current page set on the UVE
+-   `publishDate`: The publish date of the current page set on the UVE
+-   `variantName`: The name of the current variant
 
-The `sendMessageToUVE` function allows you to send messages to the dotCMS page editor. This is useful for triggering specific actions or updating the editor's state.
+### `createUVESubscription(eventType, callback)`
 
-This function is primarily used within other library functions but can be helpful if you need to trigger specific behavior by sending a message to the UVE.
+`createUVESubscription` is a function that allows your application to dynamically interact with UVE by subscribing to events such as content changes or navigation updates. This enables your app to respond in real-time to user actions and editor events, enhancing the interactive experience.
 
-**Example:**
-```typescript
-sendMessageToUVE({ 
-  action: DotCMSUVEAction.CUSTOM_MESSAGE, 
-  payload: { key: 'value' } 
+| Input       | Type           | Required | Description                               |
+| ----------- | -------------- | -------- | ----------------------------------------- |
+| `eventType` | `UVEEventType` | ✅       | [The event to subscribe to](#event-types) |
+| `callback`  | `Function`     | ✅       | Called when the event is triggered        |
+
+#### Usage
+
+```ts
+import { createUVESubscription } from '@dotcms/uve';
+import { UVEEventType } from '@dotcms/types';
+
+const sub = createUVESubscription(UVEEventType.CONTENT_CHANGES, (newPageResponse) => {
+    // do something when the content changes
 });
+
+// Later, when you want to unsubscribe
+sub.unsubscribe();
 ```
 
-### Available Message Types (DotCMSUVEAction)
+#### Event Types
 
-| **Type**                           | **Description**                                                                                   |
-|--------------------------------------|---------------------------------------------------------------------------------------------------|
-| `NAVIGATION_UPDATE`                  | Notifies the dotCMS editor that the page has changed.                                             |
-| `SET_BOUNDS`                         | Sends the position of rows, columns, containers, and contentlets to the editor.                  |
-| `SET_CONTENTLET`                     | Sends information about the currently hovered contentlet.                                         |
-| `IFRAME_SCROLL`                      | Informs the editor that the page is being scrolled.                                               |
-| `IFRAME_SCROLL_END`                  | Notifies the editor that scrolling has stopped.                                                   |
-| `PING_EDITOR`                        | Pings the editor to check if the page is inside the editor.                                       |
-| `INIT_INLINE_EDITING`                | Initializes the inline editing mode in the editor.                                                |
-| `COPY_CONTENTLET_INLINE_EDITING`     | Opens the "Copy Contentlet" dialog to duplicate and edit a contentlet inline.                    |
-| `UPDATE_CONTENTLET_INLINE_EDITING`   | Triggers the save action for inline-edited contentlets.                                           |
-| `REORDER_MENU`                       | Triggers the menu reorder action with a specified configuration.                                  |
-| `GET_PAGE_DATA`                      | Requests the current page information from the editor.                                            |
-| `CLIENT_READY`                       | Indicates that the client has completed initialization.                                            |
-| `EDIT_CONTENTLET`                    | Opens the contentlet editing dialog in the editor.                                                |
+-   `UVEEventType.CONTENT_CHANGES`: Triggered when the content of the page changes.
+-   `UVEEventType.PAGE_RELOAD`: Triggered when the page is reloaded.
+-   `UVEEventType.REQUEST_BOUNDS`: Triggered when the editor requests the bounds of the page.
+-   `UVEEventType.IFRAME_SCROLL`: Triggered when the iframe is scrolled.
+-   `UVEEventType.IFRAME_SCROLL_END`: Triggered when the iframe has stopped scrolling.
+-   `UVEEventType.CONTENTLET_HOVERED`: Triggered when a contentlet is hovered.
 
-## Types Reference
+### `editContentlet(contentlet)`
 
-The SDK provides TypeScript types to assist in development:
+`editContentlet` is a function that opens the dotCMS modal editor for any contentlet in or out of page area.
 
-### UVE State and Modes
+| Input        | Type               | Required | Description                      |
+| ------------ | ------------------ | -------- | -------------------------------- |
+| `contentlet` | `Contentlet<T>` | ✅       | The contentlet you want to edit. |
 
-```typescript
-// UVE State Interface
-interface UVEState {
-  mode: UVE_MODE;
-  persona: string | null;
-  variantName: string | null;
-  experimentId: string | null;
-  publishDate: string | null;
-  languageId: string | null;
-}
+#### Usage
 
-// UVE Mode Enum
-enum UVE_MODE {
-  EDIT = 'EDIT_MODE',
-  PREVIEW = 'PREVIEW_MODE',
-  LIVE = 'LIVE',
-  UNKNOWN = 'UNKNOWN'
-}
+```tsx
+import { editContentlet, getUVEState } from '@dotcms/uve';
+import { UVE_MODE } from '@dotcms/types';
+
+const myEditButton = ({ contentlet }) => {
+    const uveState = getUVEState();
+
+    if (uveState?.mode === UVE_MODE.EDIT) {
+        return <button onClick={() => editContentlet(contentlet)}>Edit</button>;
+    }
+
+    return null;
+};
 ```
 
-### UVE Events
+### `initInlineEditing(type, data)`
+
+`initInlineEditing` is a function that triggers inline editing for supported field types (WYSIWYG or Block Editor).
+
+| Input       | Type                         | Required | Description                                                                    |
+| ----------- | ---------------------------- | -------- | ------------------------------------------------------------------------------ |
+| `type`      | `DotCMSInlineEditingType`    | ✅       | `'BLOCK_EDITOR'` or `'WYSIWYG'`                                                |
+| `fieldData` | `DotCMSInlineEditingPayload` | ✅       | [Field content required to enable inline editing](#dotcmsinlineeditingpayload) |
+
+#### Usage
+
+```ts
+import { initInlineEditing, getUVEState } from "@dotcms/uve";
+import { UVE_MODE } from "@dotcms/types";
+
+const MyBanner = ({ contentlet }) => {
+  const uveState = getUVEState();
+
+  const handleClick = () => {
+    if (uveState?.mode === UVE_MODE.EDIT) {
+      const { inode, contentType, title } = contentlet;
+      initInlineEditing("BLOCK_EDITOR", {
+        inode,
+        contentType,
+        content: title,
+        fieldName: "title",
+      });
+    }
+  };
+  return (
+    <div>
+      <h1 onClick={handleClick}>{contentlet.title}</h1>
+      <p>{contentlet.description}</p>
+    </div>
+  );
+};
+```
 
-```typescript
-// Event Types Enum
-enum UVEEventType {
-  CONTENT_CHANGES = 'changes',
-  PAGE_RELOAD = 'page-reload',
-  REQUEST_BOUNDS = 'request-bounds',
-  IFRAME_SCROLL = 'iframe-scroll',
-  CONTENTLET_HOVERED = 'contentlet-hovered'
-}
+#### DotCMSInlineEditingPayload
 
-// Event Subscription Interface
-interface UVEEventSubscription {
-  unsubscribe: () => void;
-  event: string;
-}
+-   `inode` (string): The inode of the contentlet to edit.
+-   `contentType` (string): The content type of the contentlet to edit.
+-   `fieldName` (string): The name of the field to edit.
+-   `content` (string): The content of the field to edit.
+
+### `enableBlockEditorInline(contentlet, fieldName)`
+
+`enableBlockEditorInline` is a shortcut to [enable inline block editing](https://dev.dotcms.com/docs/block-editor#BlockInlineEditor) for a field.
+
+| Input        | Type                    | Required | Description                                                    |
+| ------------ | ----------------------- | -------- | -------------------------------------------------------------- |
+| `contentlet` | `DotCMSBasicContentlet` | ✅       | The target contentlet                                          |
+| `fieldName`  | `string`                | ✅       | [Name of the block field to edit](#dotcmsinlineeditingpayload) |
+
+#### Usage
+
+```tsx
+import { enableBlockEditorInline, getUVEState } from '@dotcms/uve';
+import { UVE_MODE } from '@dotcms/types';
+
+const MyBanner = ({ contentlet }) => {
+    const uveState = getUVEState();
+
+    const handleClick = () => {
+        if (uveState?.mode === UVE_MODE.EDIT) {
+            enableBlockEditorInline(contentlet, 'blockContent');
+        }
+    };
+
+    return <MyBlockEditorRender onClick={handleClick} />;
+};
 ```
 
-## Examples
+### `updateNavigation(pathname)`
 
-### Basic Usage
+`updateNavigation` is a function that notifies UVE that navigation has changed (e.g., in SPAs).
 
-```typescript
-import { getUVEState, createUVESubscription } from '@dotcms/uve';
-import { UVEEventType, UVE_MODE } from '@dotcms/uve/types';
-
-// Check if we're in the editor
-const uveState = getUVEState();
-if (uveState) {
-  console.log(`Running in ${uveState.mode} mode`);
-  
-  // Initialize components based on editor state
-  if (uveState.mode === UVE_MODE.EDIT) {
-    enableEditFeatures();
-  }
-}
+| Input      | Type     | Required | Description                |
+| ---------- | -------- | -------- | -------------------------- |
+| `pathname` | `string` | ✅       | The new pathname to update |
+
+#### Usage
+
+```tsx
+import { updateNavigation } from '@dotcms/uve';
+
+updateNavigation('/navigate-to-this-new-page');
 ```
 
-### Content Updates
+### `reorderMenu(config?)`
 
-```typescript
-import { createUVESubscription } from '@dotcms/uve';
-import { UVEEventType } from '@dotcms/uve/types';
+`reorderMenu` is a function that opens the UVE menu editor to reorder navigation links.
 
-// Subscribe to content changes
-const subscription = createUVESubscription(UVEEventType.CONTENT_CHANGES, (changes) => {
-  // Update your UI with the new content
-  updateUI(changes);
-});
+| Input     | Type                      | Required | Description                                                |
+| --------- | ------------------------- | -------- | ---------------------------------------------------------- |
+| `config?` | `DotCMSReorderMenuConfig` | ❌       | [Optional config for reordering](#dotcmsreordermenuconfig) |
 
-// Clean up when component unmounts
-function cleanup() {
-  subscription.unsubscribe();
-}
+#### Usage
+
+```ts
+import { reorderMenu } from '@dotcms/uve';
+
+reorderMenu({ startLevel: 2, depth: 3 });
 ```
 
-### Inline Editing Integration
+#### DotCMSReorderMenuConfig
 
-```typescript
-import { initInlineEditing } from '@dotcms/uve';
-
-// Integrate with a block editor component
-function setupBlockEditor(element, contentData) {
-  element.addEventListener('click', () => {
-    initInlineEditing('BLOCK_EDITOR', {
-      inode: contentData.inode,
-      language: contentData.languageId,
-      contentType: contentData.contentType,
-      fieldName: 'body',
-      content: contentData.content
-    });
-  });
-}
+-   `startLevel` (number): The level to start reordering from
+-   `depth` (number): The depth of the menu to reorder
+
+### `sendMessageToUVE(message)`
+
+`sendMessageToUVE` is a low-level function to send custom messages to UVE.
+
+| Input     | Type                                       | Required | Description                  |
+| --------- | ------------------------------------------ | -------- | ---------------------------- |
+| `message` | [`DotCMSUVEMessage<T>`](#dotcmsuvemessage) | ✅       | Object with action + payload |
+
+#### Usage
+
+```ts
+sendMessageToUVE({
+  action: DotCMSUVEAction.CUSTOM_EVENT,
+  payload: { type: 'MyEvent', data: {...} }
+});
 ```
 
-## Contributing
+#### DotCMSUVEMessage<T>
+
+| Event (DotCMSUVEAction)            | Payload (T)                                                   |
+| ---------------------------------- | ------------------------------------------------------------- | ------- |
+| `NAVIGATION_UPDATE`                | `{ url: string }`                                             |
+| `SET_BOUNDS`                       | `DotCMSContainerBound[]`                                      |
+| `SET_CONTENTLET`                   | `DotCMSBasicContentlet`                                       |
+| `IFRAME_SCROLL`                    | `'up'                                                         | 'down'` |
+| `IFRAME_SCROLL_END`                | ---                                                           |
+| `REORDER_MENU`                     | `DotCMSReorderMenuConfig`                                     |
+| `INIT_INLINE_EDITING`              | `DotCMSInlineEditingPayload`                                  |
+| `COPY_CONTENTLET_INLINE_EDITING`   | `{ dataset: { inode, language, fieldName: this.fieldName } }` |
+| `UPDATE_CONTENTLET_INLINE_EDITING` | `{ content: string, dataset: { inode, langId, fieldName } }`  |
+| `GET_PAGE_DATA`                    | ---                                                           |
+| `CLIENT_READY`                     | ---                                                           |
+| `EDIT_CONTENTLET`                  | `DotCMSBasicContentlet`                                       |
+
+## Troubleshooting
+
+### Common Issues & Solutions
 
-We welcome contributions to the UVE SDK! Please follow these steps:
+#### Memory Management
 
-1. Fork the repository
+1. **Memory Leaks**: Application experiences memory leaks
+    - **Possible Causes**:
+        - Failing to call `destroyUVESubscriptions()` on unmount
+    - **Solutions**:
+        - Always call `destroyUVESubscriptions()` when your component unmounts to clean up subscriptions
+
+#### Editor State
+
+1. **Undefined State**: `getUVEState()` returns undefined
+    - **Possible Causes**:
+        - Application not running inside the dotCMS editor
+    - **Solutions**:
+        - Ensure your application is running within the dotCMS environment when calling `getUVEState()`
+
+#### Event Handling
+
+1. **Unsubscribed Events**: Events not unsubscribed leading to unexpected behavior
+    - **Possible Causes**:
+        - Not unsubscribing from events
+    - **Solutions**:
+        - Always unsubscribe from events using the `unsubscribe()` method to prevent memory leaks
+
+#### Inline Editing
+
+1. **Invalid Contentlet or Field**: `initInlineEditing()` requires valid contentlet and field name
+    - **Possible Causes**:
+        - Incorrect contentlet or field name
+    - **Solutions**:
+        - Verify that the contentlet and field name are correct and exist in the dotCMS instance
+
+#### Non-existent Page Navigation
+
+1. **Navigation to a non-existent page**: May break content sync in UVE and make the editor redirect to the home page
+    - **Possible Causes**:
+        - Navigation to a non-existent page
+    - **Solutions**:
+        - Ensure the page exists in the dotCMS instance
+
+#### Menu Reordering
+
+1. **UI Action Requirement**: `reorderMenu()` must be called from a UI action
+    - **Possible Causes**:
+        - Attempting to auto-trigger `reorderMenu()`
+    - **Solutions**:
+        - Ensure `reorderMenu()` is triggered by a user action within the UI
+
+### Debugging Tips
+
+1. **Ensure you are in the UVE Context**
+    - Check if you are in the UVE context by calling `getUVEState()`
+    - If you are not in the UVE context, you will not be able to use the UVE SDK correctly
+2. **Check Browser Console**
+    - Check for errors in the browser console
+    - Check for errors in the browser network tab
+3. **Network Monitoring**
+    - Use browser dev tools to monitor API calls
+    - Check for 401/403 errors (auth issues)
+    - Verify asset loading paths
+
+### Still Having Issues?
+
+If you're still experiencing problems after trying these solutions:
+
+1. Search existing [GitHub issues](https://github.com/dotCMS/core/issues)
+2. Check our [community forum](https://community.dotcms.com/)
+3. Create a new issue with:
+    - Detailed reproduction steps
+    - Environment information
+    - Error messages
+    - Code samples
+
+## dotCMS Support
+
+We offer multiple channels to get help with the dotCMS UVE SDK:
+
+-   **GitHub Issues**: For bug reports and feature requests, please [open an issue](https://github.com/dotCMS/core/issues/new/choose) in the GitHub repository.
+-   **Community Forum**: Join our [community discussions](https://community.dotcms.com/) to ask questions and share solutions.
+-   **Stack Overflow**: Use the tag `dotcms-uve` when posting questions.
+
+When reporting issues, please include:
+
+-   SDK version you're using
+-   dotCMS version
+-   Minimal reproduction steps
+-   Expected vs. actual behavior
+
+Enterprise customers can access premium support through the [dotCMS Support Portal](https://dev.dotcms.com/docs/help).
+
+## How To Contribute
+
+GitHub pull requests are the preferred method to contribute code to dotCMS. We welcome contributions to the DotCMS UVE SDK! If you'd like to contribute, please follow these steps:
+
+1. Fork the repository [dotCMS/core](https://github.com/dotCMS/core)
 2. Create a feature branch (`git checkout -b feature/amazing-feature`)
 3. Commit your changes (`git commit -m 'Add some amazing feature'`)
 4. Push to the branch (`git push origin feature/amazing-feature`)
 5. Open a Pull Request
 
-## License
+Please ensure your code follows the existing style and includes appropriate tests.
+
+## Licensing Information
+
+dotCMS comes in multiple editions and as such is dual-licensed. The dotCMS Community Edition is licensed under the GPL 3.0 and is freely available for download, customization, and deployment for use within organizations of all stripes. dotCMS Enterprise Editions (EE) adds several enterprise features and is available via a supported, indemnified commercial license from dotCMS. For the differences between the editions, see [the feature page](http://www.dotcms.com/cms-platform/features).
+
+This SDK is part of dotCMS's dual-licensed platform (GPL 3.0 for Community, commercial license for Enterprise).
 
-This project is licensed under the MIT License - see the LICENSE file for details.
+[Learn more ](https://www.dotcms.com)at [dotcms.com](https://www.dotcms.com).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotcms/uve",
-  "version": "0.0.1-beta.33",
+  "version": "0.0.1-beta.35",
   "description": "Official JavaScript library for interacting with Universal Visual Editor (UVE)",
   "repository": {
     "type": "git",

package/public.cjs.js

@@ -127,7 +127,8 @@ function getClosestDotCMSContainerData(element) {
  */
 function findDotCMSElement(element) {
   if (!element) return null;
-  if (element?.dataset?.['dotObject'] === 'contentlet' || element?.dataset?.['dotObject'] === 'container' && element.children.length === 0) {
+  const emptyContent = element.querySelector('[data-dot-object="empty-content"]');
+  if (element?.dataset?.['dotObject'] === 'contentlet' || element?.dataset?.['dotObject'] === 'container' && emptyContent) {
     return element;
   }
   return findDotCMSElement(element?.['parentElement']);

package/public.esm.js

@@ -125,7 +125,8 @@ function getClosestDotCMSContainerData(element) {
  */
 function findDotCMSElement(element) {
   if (!element) return null;
-  if (element?.dataset?.['dotObject'] === 'contentlet' || element?.dataset?.['dotObject'] === 'container' && element.children.length === 0) {
+  const emptyContent = element.querySelector('[data-dot-object="empty-content"]');
+  if (element?.dataset?.['dotObject'] === 'contentlet' || element?.dataset?.['dotObject'] === 'container' && emptyContent) {
     return element;
   }
   return findDotCMSElement(element?.['parentElement']);