@dotcms/uve 0.0.1-beta.12 → 0.0.1-beta.13

package/README.md

@@ -1,7 +1,149 @@
-# sdk-uve
+# DotCMS UVE SDK
 
-This library was generated with [Nx](https://nx.dev).
+A JavaScript library to connect your dotCMS pages with the Universal Visual Editor (UVE) and enable content authors to edit pages in real time.  
 
-## Running unit tests
+## Installation
 
-Run `nx test sdk-uve` to execute the unit tests via [Jest](https://jestjs.io).
+The UVE SDK is automatically included in DotCMS installations. For external usage:
+
+```bash
+yarn add @dotcms/uve-sdk
+```
+
+
+## Entry Points
+
+The library exposes three main entry points:
+
+- **`@dotcms/uve`**: Provides everything developers need to communicate with UVE.
+
+- **`@dotcms/uve/types`**: Offers TypeScript types, interfaces, and other structures to help users organize their code properly.
+
+---
+
+## Functions
+
+### `createUVESubscription`
+
+Subscribe to the pages changes. Receive a callback that will be called with the updated content of the page. 
+
+**Parameters:**
+- `eventType` - The type of event to subscribe to.
+- `callback` - The callback function that will be called when the event occurs.
+
+**Returns:**
+- An event subscription that can be used to unsubscribe.
+
+**Example:**  
+***typescript
+// Subscribe to page changes
+const subscription = createUVESubscription(UVEEventType.CONTENT_CHANGES, (changes) => {
+console.log('Content changes:', changes);
+});
+
+// Unsubscribe
+
+subscription.unsubscribe()
+```
+
+---
+
+### `getUVEState`
+
+Retrieves the current UVE state.
+
+**Returns:**
+- A `UVEState` object if running inside the editor, or `undefined` otherwise.
+
+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.
+
+> **Note:** If any of these properties are absent, it means the value is the default one.
+
+**Example:**
+```typescript
+const editorState = getUVEState();
+if (editorState?.mode === 'edit') {
+  // Enable editing features
+}
+```
+
+---
+
+### `editContentlet`
+
+Allows you to edit a contentlet in the editor.
+
+Calling this function within the editor prompts the UVE to open a dialog to edit the specified contentlet.
+
+**Parameters:**
+- `contentlet<T>` - The contentlet to edit.
+
+**Example:**
+```typescript
+editContentlet(myContentlet);
+```
+
+---
+
+### `reorderMenu`
+
+Reorders the menu based on the provided configuration.
+
+**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.
+
+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.
+
+**Example:**
+```typescript
+reorderMenu({ startLevel: 2, depth: 3 });
+```
+
+---
+
+### `initInlineEditing`
+
+Initializes inline editing in the editor.
+
+**Example:**
+```typescript
+initInlineEditing();
+```
+
+---
+
+### `sendMessageToUVE`
+
+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.
+
+This function is primarily used within other libraries but can be helpful if you need to trigger specific behavior by sending a message to the UVE.
+
+**Example:**
+```typescript
+sendMessageToEditor({ type: 'CUSTOM_MESSAGE': DotCMSUVEAction, payload: { key: 'value' } });
+```
+
+### Available Message Types (DotCMSUVEAction)
+
+| **Type**                           | **Description**                                                                                   |
+|--------------------------------------|---------------------------------------------------------------------------------------------------|
+| `set-url`                            | 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.                                         |
+| `scroll`                             | Informs the editor that the page is being scrolled.                                               |
+| `scroll-end`                         | Notifies the editor that scrolling has stopped.                
+| `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 sent a GraphQL query to the editor.                                 |
+| `edit-contentlet`                    | Opens the contentlet editing dialog in the editor.                                                |

package/index.cjs.js

@@ -93,7 +93,7 @@ function createUVESubscription(eventType, callback) {
  * @template T
  * @param {DotCMSUVEMessage<T>} message
  */
-function sendMessageToEditor(message) {
+function sendMessageToUVE(message) {
   window.parent.postMessage(message, '*');
 }
 /**
@@ -106,7 +106,7 @@ function sendMessageToEditor(message) {
  * @param {Contentlet<T>} contentlet - The contentlet to edit.
  */
 function editContentlet(contentlet) {
-  sendMessageToEditor({
+  sendMessageToUVE({
     action: types.DotCMSUVEAction.EDIT_CONTENTLET,
     payload: contentlet
   });
@@ -126,7 +126,7 @@ function reorderMenu(config) {
     startLevel = 1,
     depth = 2
   } = config || {};
-  sendMessageToEditor({
+  sendMessageToUVE({
     action: types.DotCMSUVEAction.REORDER_MENU,
     payload: {
       startLevel,
@@ -150,7 +150,7 @@ function reorderMenu(config) {
  * ```
  */
 function initInlineEditing(type, data) {
-  sendMessageToEditor({
+  sendMessageToUVE({
     action: types.DotCMSUVEAction.INIT_INLINE_EDITING,
     payload: {
       type,
@@ -164,4 +164,4 @@ exports.editContentlet = editContentlet;
 exports.getUVEState = getUVEState;
 exports.initInlineEditing = initInlineEditing;
 exports.reorderMenu = reorderMenu;
-exports.sendMessageToEditor = sendMessageToEditor;
+exports.sendMessageToUVE = sendMessageToUVE;

package/index.esm.js

@@ -91,7 +91,7 @@ function createUVESubscription(eventType, callback) {
  * @template T
  * @param {DotCMSUVEMessage<T>} message
  */
-function sendMessageToEditor(message) {
+function sendMessageToUVE(message) {
   window.parent.postMessage(message, '*');
 }
 /**
@@ -104,7 +104,7 @@ function sendMessageToEditor(message) {
  * @param {Contentlet<T>} contentlet - The contentlet to edit.
  */
 function editContentlet(contentlet) {
-  sendMessageToEditor({
+  sendMessageToUVE({
     action: DotCMSUVEAction.EDIT_CONTENTLET,
     payload: contentlet
   });
@@ -124,7 +124,7 @@ function reorderMenu(config) {
     startLevel = 1,
     depth = 2
   } = config || {};
-  sendMessageToEditor({
+  sendMessageToUVE({
     action: DotCMSUVEAction.REORDER_MENU,
     payload: {
       startLevel,
@@ -148,7 +148,7 @@ function reorderMenu(config) {
  * ```
  */
 function initInlineEditing(type, data) {
-  sendMessageToEditor({
+  sendMessageToUVE({
     action: DotCMSUVEAction.INIT_INLINE_EDITING,
     payload: {
       type,
@@ -157,4 +157,4 @@ function initInlineEditing(type, data) {
   });
 }
 
-export { createUVESubscription, editContentlet, getUVEState, initInlineEditing, reorderMenu, sendMessageToEditor };
+export { createUVESubscription, editContentlet, getUVEState, initInlineEditing, reorderMenu, sendMessageToUVE };

package/package.json

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

package/src/lib/editor/public.d.ts

@@ -8,7 +8,7 @@ import { DotCMSInlineEditingPayload, DotCMSInlineEditingType } from '../types/ev
  * @template T
  * @param {DotCMSUVEMessage<T>} message
  */
-export declare function sendMessageToEditor<T = unknown>(message: DotCMSUVEMessage<T>): void;
+export declare function sendMessageToUVE<T = unknown>(message: DotCMSUVEMessage<T>): void;
 /**
  * You can use this function to edit a contentlet in the editor.
  *

package/src/script/utils.d.ts

@@ -1,4 +1,46 @@
+/**
+ * Sets up scroll event handlers for the window to notify the editor about scroll events.
+ * Adds listeners for both 'scroll' and 'scrollend' events, sending appropriate messages
+ * to the editor when these events occur.
+ */
 export declare function scrollHandler(): void;
+/**
+ * Adds 'empty-contentlet' class to contentlet elements that have no height.
+ * This helps identify and style empty contentlets in the editor view.
+ *
+ * @remarks
+ * The function queries all elements with data-dot-object="contentlet" attribute
+ * and checks their clientHeight. If an element has no height (clientHeight = 0),
+ * it adds the 'empty-contentlet' class to that element.
+ */
 export declare function addClassToEmptyContentlets(): void;
+/**
+ * Registers event handlers for various UVE (Universal Visual Editor) events.
+ *
+ * This function sets up subscriptions for:
+ * - Page reload events that refresh the window
+ * - Bounds request events to update editor boundaries
+ * - Iframe scroll events to handle smooth scrolling within bounds
+ * - Contentlet hover events to notify the editor
+ *
+ * @remarks
+ * For scroll events, the function includes logic to prevent scrolling beyond
+ * the top or bottom boundaries of the iframe, which helps maintain proper
+ * scroll event handling.
+ */
 export declare function registerUVEEvents(): void;
+/**
+ * Notifies the editor that the UVE client is ready to receive messages.
+ *
+ * This function sends a message to the editor indicating that the client-side
+ * initialization is complete and it's ready to handle editor interactions.
+ *
+ * @remarks
+ * This is typically called after all UVE event handlers and DOM listeners
+ * have been set up successfully.
+ */
 export declare function setClientIsReady(): void;
+/**
+ * Listen for block editor inline event.
+ */
+export declare const listenBlockEditorInlineEvent: () => void;