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

package/README.md

@@ -1,16 +1,37 @@
 # 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.  
+A JavaScript library to connect your dotCMS pages with the Universal Visual Editor (UVE) and enable content authors to edit pages in real time.
+
+> **BETA VERSION NOTICE:** This SDK is currently in beta. APIs, functionality, and documentation may change significantly in the stable release.
+
+## 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)
 
 ## Installation
 
 The UVE SDK is automatically included in DotCMS installations. For external usage:
 
 ```bash
+# Using npm
+npm install @dotcms/uve-sdk
+
+# Using yarn
 yarn add @dotcms/uve-sdk
 ```
 
-
 ## Entry Points
 
 The library exposes three main entry points:
@@ -19,36 +40,35 @@ The library exposes three main entry points:
 
 - **`@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.
+## Getting Started
 
-**Returns:**
-- An event subscription that can be used to unsubscribe.
+To use the UVE SDK in your project, import the necessary functions:
 
-**Example:**  
-***typescript
-// Subscribe to page changes
-const subscription = createUVESubscription(UVEEventType.CONTENT_CHANGES, (changes) => {
-console.log('Content changes:', changes);
-});
-
-// Unsubscribe
-
-subscription.unsubscribe()
+```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();
+}
 ```
 
----
+## API Reference
+
+### Editor State
 
-### `getUVEState`
+#### `getUVEState`
 
 Retrieves the current UVE state.
 
@@ -73,9 +93,33 @@ if (editorState?.mode === 'edit') {
 }
 ```
 
----
+### Event Subscriptions
+
+#### `createUVESubscription`
+
+Subscribe to page changes and other UVE events. 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);
+});
+
+// Later, unsubscribe when no longer needed
+subscription.unsubscribe();
+```
+
+### Content Editing
 
-### `editContentlet`
+#### `editContentlet`
 
 Allows you to edit a contentlet in the editor.
 
@@ -86,12 +130,33 @@ Calling this function within the editor prompts the UVE to open a dialog to edit
 
 **Example:**
 ```typescript
+// Edit a contentlet
 editContentlet(myContentlet);
 ```
 
----
+#### `initInlineEditing`
 
-### `reorderMenu`
+Initializes inline editing in the editor.
+
+**Parameters:**
+- `type` - The type of inline editing ('BLOCK_EDITOR' or 'WYSIWYG').
+- `data` - (Optional) Data for the inline editing session.
+
+**Example:**
+```typescript
+// Initialize block editor
+initInlineEditing('BLOCK_EDITOR', {
+  inode: 'abc123',
+  language: 1,
+  contentType: 'Blog',
+  fieldName: 'body',
+  content: { /* content data */ }
+});
+```
+
+### Navigation & UI
+
+#### `reorderMenu`
 
 Reorders the menu based on the provided configuration.
 
@@ -104,46 +169,156 @@ This function constructs a URL for the reorder menu page with the specified `sta
 
 **Example:**
 ```typescript
+// Reorder menu starting from level 2 with depth of 3
 reorderMenu({ startLevel: 2, depth: 3 });
 ```
 
----
+### Messaging
 
-### `initInlineEditing`
+#### `sendMessageToUVE`
 
-Initializes inline editing in the editor.
+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 library functions but can be helpful if you need to trigger specific behavior by sending a message to the UVE.
 
 **Example:**
 ```typescript
-initInlineEditing();
+sendMessageToUVE({ 
+  action: DotCMSUVEAction.CUSTOM_MESSAGE, 
+  payload: { key: 'value' } 
+});
 ```
 
----
+### Available Message Types (DotCMSUVEAction)
 
-### `sendMessageToUVE`
+| **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.                                                |
+
+## Types Reference
+
+The SDK provides TypeScript types to assist in development:
+
+### UVE State and Modes
 
-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.
+```typescript
+// UVE State Interface
+interface UVEState {
+  mode: UVE_MODE;
+  persona: string | null;
+  variantName: string | null;
+  experimentId: string | null;
+  publishDate: string | null;
+  languageId: string | null;
+}
 
-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.
+// UVE Mode Enum
+enum UVE_MODE {
+  EDIT = 'EDIT_MODE',
+  PREVIEW = 'PREVIEW_MODE',
+  LIVE = 'LIVE',
+  UNKNOWN = 'UNKNOWN'
+}
+```
+
+### UVE Events
 
-**Example:**
 ```typescript
-sendMessageToEditor({ type: 'CUSTOM_MESSAGE': DotCMSUVEAction, payload: { key: 'value' } });
+// Event Types Enum
+enum UVEEventType {
+  CONTENT_CHANGES = 'changes',
+  PAGE_RELOAD = 'page-reload',
+  REQUEST_BOUNDS = 'request-bounds',
+  IFRAME_SCROLL = 'iframe-scroll',
+  CONTENTLET_HOVERED = 'contentlet-hovered'
+}
+
+// Event Subscription Interface
+interface UVEEventSubscription {
+  unsubscribe: () => void;
+  event: string;
+}
 ```
 
-### Available Message Types (DotCMSUVEAction)
+## Examples
 
-| **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.                                                |
+### Basic Usage
+
+```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();
+  }
+}
+```
+
+### Content Updates
+
+```typescript
+import { createUVESubscription } from '@dotcms/uve';
+import { UVEEventType } from '@dotcms/uve/types';
+
+// Subscribe to content changes
+const subscription = createUVESubscription(UVEEventType.CONTENT_CHANGES, (changes) => {
+  // Update your UI with the new content
+  updateUI(changes);
+});
+
+// Clean up when component unmounts
+function cleanup() {
+  subscription.unsubscribe();
+}
+```
+
+### Inline Editing Integration
+
+```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
+    });
+  });
+}
+```
+
+## Contributing
+
+We welcome contributions to the UVE SDK! Please follow these steps:
+
+1. Fork the repository
+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
+
+This project is licensed under the MIT License - see the LICENSE file for details.

package/internal.cjs.js

@@ -210,6 +210,167 @@ function computeScrollIsInBottom() {
   const scrollY = window.scrollY;
   return scrollY + viewportHeight >= documentHeight;
 }
+/**
+ *
+ *
+ * Combine classes into a single string.
+ *
+ * @param {string[]} classes
+ * @returns {string} Combined classes
+ */
+const combineClasses = classes => classes.filter(Boolean).join(' ');
+/**
+ *
+ *
+ * Calculates and returns the CSS Grid positioning classes for a column based on its configuration.
+ * Uses a 12-column grid system where columns are positioned using grid-column-start and grid-column-end.
+ *
+ * @example
+ * ```typescript
+ * const classes = getColumnPositionClasses({
+ *   leftOffset: 1, // Starts at the first column
+ *   width: 6      // Spans 6 columns
+ * });
+ * // Returns: { startClass: 'col-start-1', endClass: 'col-end-7' }
+ * ```
+ *
+ * @param {DotPageAssetLayoutColumn} column - Column configuration object
+ * @param {number} column.leftOffset - Starting position (0-based) in the grid
+ * @param {number} column.width - Number of columns to span
+ * @returns {{ startClass: string, endClass: string }} Object containing CSS class names for grid positioning
+ */
+const getColumnPositionClasses = column => {
+  const {
+    leftOffset,
+    width
+  } = column;
+  const startClass = `${START_CLASS}${leftOffset}`;
+  const endClass = `${END_CLASS}${leftOffset + width}`;
+  return {
+    startClass,
+    endClass
+  };
+};
+/**
+ *
+ *
+ * Helper function that returns an object containing the dotCMS data attributes.
+ * @param {DotCMSContentlet} contentlet - The contentlet to get the attributes for
+ * @param {string} container - The container to get the attributes for
+ * @returns {DotContentletAttributes} The dotCMS data attributes
+ */
+function getDotContentletAttributes(contentlet, container) {
+  return {
+    'data-dot-identifier': contentlet?.identifier,
+    'data-dot-basetype': contentlet?.baseType,
+    'data-dot-title': contentlet?.['widgetTitle'] || contentlet?.title,
+    'data-dot-inode': contentlet?.inode,
+    'data-dot-type': contentlet?.contentType,
+    'data-dot-container': container,
+    'data-dot-on-number-of-pages': contentlet?.['onNumberOfPages']
+  };
+}
+/**
+ *
+ *
+ * Retrieves container data from a DotCMS page asset using the container reference.
+ * This function processes the container information and returns a standardized format
+ * for container editing.
+ *
+ * @param {DotCMSPageAsset} dotCMSPageAsset - The page asset containing all containers data
+ * @param {DotCMSColumnContainer} columContainer - The container reference from the layout
+ * @throws {Error} When page asset is invalid or container is not found
+ * @returns {EditableContainerData} Formatted container data for editing
+ *
+ * @example
+ * const containerData = getContainersData(pageAsset, containerRef);
+ * // Returns: { uuid: '123', identifier: 'cont1', acceptTypes: 'type1,type2', maxContentlets: 5 }
+ */
+const getContainersData = (dotCMSPageAsset, columContainer) => {
+  const {
+    identifier,
+    uuid
+  } = columContainer;
+  const dotContainer = dotCMSPageAsset.containers[identifier];
+  if (!dotContainer) {
+    return null;
+  }
+  const {
+    containerStructures,
+    container
+  } = dotContainer;
+  const acceptTypes = containerStructures?.map(structure => structure.contentTypeVar).join(',') ?? '';
+  const variantId = container?.parentPermissionable?.variantId;
+  const maxContentlets = container?.maxContentlets ?? 0;
+  const path = container?.path;
+  return {
+    uuid,
+    variantId,
+    acceptTypes,
+    maxContentlets,
+    identifier: path ?? identifier
+  };
+};
+/**
+ *
+ *
+ * Retrieves the contentlets (content items) associated with a specific container.
+ * Handles different UUID formats and provides warning for missing contentlets.
+ *
+ * @param {DotCMSPageAsset} dotCMSPageAsset - The page asset containing all containers data
+ * @param {DotCMSColumnContainer} columContainer - The container reference from the layout
+ * @returns {DotCMSContentlet[]} Array of contentlets in the container
+ *
+ * @example
+ * const contentlets = getContentletsInContainer(pageAsset, containerRef);
+ * // Returns: [{ identifier: 'cont1', ... }, { identifier: 'cont2', ... }]
+ */
+const getContentletsInContainer = (dotCMSPageAsset, columContainer) => {
+  const {
+    identifier,
+    uuid
+  } = columContainer;
+  const {
+    contentlets
+  } = dotCMSPageAsset.containers[identifier];
+  const contentletsInContainer = contentlets[`uuid-${uuid}`] || contentlets[`uuid-dotParser_${uuid}`] || [];
+  if (!contentletsInContainer) {
+    console.warn(`We couldn't find the contentlets for the container with the identifier ${identifier} and the uuid ${uuid} becareful by adding content to this container.\nWe recommend to change the container in the layout and add the content again.`);
+  }
+  return contentletsInContainer;
+};
+/**
+ *
+ *
+ * Generates the required DotCMS data attributes for a container element.
+ * These attributes are used by DotCMS for container identification and functionality.
+ *
+ * @param {EditableContainerData} params - Container data including uuid, identifier, acceptTypes, and maxContentlets
+ * @returns {DotContainerAttributes} Object containing all necessary data attributes
+ *
+ * @example
+ * const attributes = getDotContainerAttributes({
+ *   uuid: '123',
+ *   identifier: 'cont1',
+ *   acceptTypes: 'type1,type2',
+ *   maxContentlets: 5
+ * });
+ * // Returns: { 'data-dot-object': 'container', 'data-dot-identifier': 'cont1', ... }
+ */
+function getDotContainerAttributes({
+  uuid,
+  identifier,
+  acceptTypes,
+  maxContentlets
+}) {
+  return {
+    'data-dot-object': 'container',
+    'data-dot-accept-types': acceptTypes,
+    'data-dot-identifier': identifier,
+    'data-max-contentlets': maxContentlets.toString(),
+    'data-dot-uuid': uuid
+  };
+}
 
 /**
  * Subscribes to content changes in the UVE editor
@@ -408,13 +569,84 @@ const __UVE_EVENT_ERROR_FALLBACK__ = event => {
     event
   };
 };
+/**
+ * Development mode
+ *
+ * @internal
+ */
+const DEVELOPMENT_MODE = 'development';
+/**
+ * Production mode
+ *
+ * @internal
+ */
+const PRODUCTION_MODE = 'production';
+/**
+ * End class
+ *
+ * @internal
+ */
+const END_CLASS = 'col-end-';
+/**
+ * Start class
+ *
+ * @internal
+ */
+const START_CLASS = 'col-start-';
+/**
+ * Empty container style for React
+ *
+ * @internal
+ */
+const EMPTY_CONTAINER_STYLE_REACT = {
+  width: '100%',
+  backgroundColor: '#ECF0FD',
+  display: 'flex',
+  justifyContent: 'center',
+  alignItems: 'center',
+  color: '#030E32',
+  height: '10rem'
+};
+/**
+ * Empty container style for Angular
+ *
+ * @internal
+ */
+const EMPTY_CONTAINER_STYLE_ANGULAR = {
+  width: '100%',
+  'background-color': '#ECF0FD',
+  display: 'flex',
+  'justify-content': 'center',
+  'align-items': 'center',
+  color: '#030E32',
+  height: '10rem'
+};
+/**
+ * Custom no component
+ *
+ * @internal
+ */
+const CUSTOM_NO_COMPONENT = 'CustomNoComponent';
 
+exports.CUSTOM_NO_COMPONENT = CUSTOM_NO_COMPONENT;
+exports.DEVELOPMENT_MODE = DEVELOPMENT_MODE;
+exports.EMPTY_CONTAINER_STYLE_ANGULAR = EMPTY_CONTAINER_STYLE_ANGULAR;
+exports.EMPTY_CONTAINER_STYLE_REACT = EMPTY_CONTAINER_STYLE_REACT;
+exports.END_CLASS = END_CLASS;
+exports.PRODUCTION_MODE = PRODUCTION_MODE;
+exports.START_CLASS = START_CLASS;
 exports.__UVE_EVENTS__ = __UVE_EVENTS__;
 exports.__UVE_EVENT_ERROR_FALLBACK__ = __UVE_EVENT_ERROR_FALLBACK__;
+exports.combineClasses = combineClasses;
 exports.computeScrollIsInBottom = computeScrollIsInBottom;
 exports.findDotCMSElement = findDotCMSElement;
 exports.findDotCMSVTLData = findDotCMSVTLData;
 exports.getClosestDotCMSContainerData = getClosestDotCMSContainerData;
+exports.getColumnPositionClasses = getColumnPositionClasses;
+exports.getContainersData = getContainersData;
+exports.getContentletsInContainer = getContentletsInContainer;
 exports.getDotCMSContainerData = getDotCMSContainerData;
 exports.getDotCMSContentletsBound = getDotCMSContentletsBound;
 exports.getDotCMSPageBounds = getDotCMSPageBounds;
+exports.getDotContainerAttributes = getDotContainerAttributes;
+exports.getDotContentletAttributes = getDotContentletAttributes;