@dotcms/uve 0.0.1-beta.3 → 0.0.1-beta.31

package/README.md

@@ -1,7 +1,324 @@
-# 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
+> **BETA VERSION NOTICE:** This SDK is currently in beta. APIs, functionality, and documentation may change significantly in the stable release.
 
-Run `nx test sdk-uve` to execute the unit tests via [Jest](https://jestjs.io).
+## 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:
+
+- **`@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.
+
+## Getting Started
+
+To use the UVE SDK in your project, import the necessary functions:
+
+```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`
+
+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
+}
+```
+
+### 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`
+
+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
+// Edit a contentlet
+editContentlet(myContentlet);
+```
+
+#### `initInlineEditing`
+
+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.
+
+**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
+// Reorder menu starting from level 2 with depth of 3
+reorderMenu({ startLevel: 2, depth: 3 });
+```
+
+### Messaging
+
+#### `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 library functions but can be helpful if you need to trigger specific behavior by sending a message to the UVE.
+
+**Example:**
+```typescript
+sendMessageToUVE({ 
+  action: DotCMSUVEAction.CUSTOM_MESSAGE, 
+  payload: { key: 'value' } 
+});
+```
+
+### Available Message Types (DotCMSUVEAction)
+
+| **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
+
+```typescript
+// UVE State Interface
+interface UVEState {
+  mode: UVE_MODE;
+  persona: string | null;
+  variantName: string | null;
+  experimentId: string | null;
+  publishDate: string | null;
+  languageId: string | null;
+}
+
+// UVE Mode Enum
+enum UVE_MODE {
+  EDIT = 'EDIT_MODE',
+  PREVIEW = 'PREVIEW_MODE',
+  LIVE = 'LIVE',
+  UNKNOWN = 'UNKNOWN'
+}
+```
+
+### UVE Events
+
+```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'
+}
+
+// Event Subscription Interface
+interface UVEEventSubscription {
+  unsubscribe: () => void;
+  event: string;
+}
+```
+
+## Examples
+
+### 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/index.cjs.js

@@ -1,58 +1,17 @@
 'use strict';
 
-var types = require('./types.cjs.js');
+var _public = require('./public.cjs.js');
+require('@dotcms/types');
+require('@dotcms/types/internal');
 
-/**
- * Gets the current state of the Universal Visual Editor (UVE).
- *
- * This function checks if the code is running inside the DotCMS Universal Visual Editor
- * and returns information about its current state, including the editor mode.
- *
- * @export
- * @return {UVEState | undefined} Returns the UVE state object if running inside the editor,
- * undefined otherwise.
- *
- * The state includes:
- * - mode: The current editor mode (preview, edit, live)
- * - languageId: The language ID of the current page setted on the UVE
- * - persona: The persona of the current page setted on the UVE
- * - variantName: The name of the current variant
- * - experimentId: The ID of the current experiment
- * - publishDate: The publish date of the current page setted on the UVE
- *
- * @note The absence of any of these properties means that the value is the default one.
- *
- * @example
- * ```ts
- * const editorState = getUVEState();
- * if (editorState?.mode === 'edit') {
- *   // Enable editing features
- * }
- * ```
- */
-function getUVEState() {
-  if (typeof window === 'undefined' || window.parent === window || !window.location) {
-    return;
-  }
-  const url = new URL(window.location.href);
-  const possibleModes = Object.values(types.UVE_MODE);
-  let mode = url.searchParams.get('mode') ?? types.UVE_MODE.EDIT;
-  const languageId = url.searchParams.get('language_id');
-  const persona = url.searchParams.get('personaId');
-  const variantName = url.searchParams.get('variantName');
-  const experimentId = url.searchParams.get('experimentId');
-  const publishDate = url.searchParams.get('publishDate');
-  if (!possibleModes.includes(mode)) {
-    mode = types.UVE_MODE.EDIT;
-  }
-  return {
-    mode,
-    languageId,
-    persona,
-    variantName,
-    experimentId,
-    publishDate
-  };
-}
 
-exports.getUVEState = getUVEState;
+
+exports.createUVESubscription = _public.createUVESubscription;
+exports.editContentlet = _public.editContentlet;
+exports.enableBlockEditorInline = _public.enableBlockEditorInline;
+exports.getUVEState = _public.getUVEState;
+exports.initInlineEditing = _public.initInlineEditing;
+exports.initUVE = _public.initUVE;
+exports.reorderMenu = _public.reorderMenu;
+exports.sendMessageToUVE = _public.sendMessageToUVE;
+exports.updateNavigation = _public.updateNavigation;

package/index.esm.js

@@ -1,56 +1,3 @@
-import { UVE_MODE } from './types.esm.js';
-
-/**
- * Gets the current state of the Universal Visual Editor (UVE).
- *
- * This function checks if the code is running inside the DotCMS Universal Visual Editor
- * and returns information about its current state, including the editor mode.
- *
- * @export
- * @return {UVEState | undefined} Returns the UVE state object if running inside the editor,
- * undefined otherwise.
- *
- * The state includes:
- * - mode: The current editor mode (preview, edit, live)
- * - languageId: The language ID of the current page setted on the UVE
- * - persona: The persona of the current page setted on the UVE
- * - variantName: The name of the current variant
- * - experimentId: The ID of the current experiment
- * - publishDate: The publish date of the current page setted on the UVE
- *
- * @note The absence of any of these properties means that the value is the default one.
- *
- * @example
- * ```ts
- * const editorState = getUVEState();
- * if (editorState?.mode === 'edit') {
- *   // Enable editing features
- * }
- * ```
- */
-function getUVEState() {
-  if (typeof window === 'undefined' || window.parent === window || !window.location) {
-    return;
-  }
-  const url = new URL(window.location.href);
-  const possibleModes = Object.values(UVE_MODE);
-  let mode = url.searchParams.get('mode') ?? UVE_MODE.EDIT;
-  const languageId = url.searchParams.get('language_id');
-  const persona = url.searchParams.get('personaId');
-  const variantName = url.searchParams.get('variantName');
-  const experimentId = url.searchParams.get('experimentId');
-  const publishDate = url.searchParams.get('publishDate');
-  if (!possibleModes.includes(mode)) {
-    mode = UVE_MODE.EDIT;
-  }
-  return {
-    mode,
-    languageId,
-    persona,
-    variantName,
-    experimentId,
-    publishDate
-  };
-}
-
-export { getUVEState };
+export { c as createUVESubscription, e as editContentlet, a as enableBlockEditorInline, g as getUVEState, i as initInlineEditing, b as initUVE, r as reorderMenu, s as sendMessageToUVE, u as updateNavigation } from './public.esm.js';
+import '@dotcms/types';
+import '@dotcms/types/internal';

package/internal.cjs.d.ts

@@ -0,0 +1 @@
+export * from "./src/internal";

package/internal.cjs.default.js

@@ -0,0 +1 @@
+exports._default = require('./internal.cjs.js').default;

package/internal.cjs.js

@@ -0,0 +1,103 @@
+'use strict';
+
+var _public = require('./public.cjs.js');
+require('@dotcms/types');
+require('@dotcms/types/internal');
+
+/**
+ * TinyMCE default config across all versions
+ *
+ * @internal
+ */
+const __DEFAULT_TINYMCE_CONFIG__ = {
+  menubar: false,
+  inline: true,
+  valid_styles: {
+    '*': 'font-size,font-family,color,text-decoration,text-align'
+  },
+  powerpaste_word_import: 'clean',
+  powerpaste_html_import: 'clean',
+  suffix: '.min' // Suffix to use when loading resources
+};
+/**
+ * TinyMCE config to use per mode
+ *
+ * @internal
+ */
+const __BASE_TINYMCE_CONFIG_WITH_NO_DEFAULT__ = {
+  full: {
+    plugins: 'link lists autolink charmap',
+    toolbar: ['styleselect undo redo | bold italic underline | forecolor backcolor | alignleft aligncenter alignright alignfull | numlist bullist outdent indent | hr charmap removeformat | link'],
+    style_formats: [{
+      title: 'Paragraph',
+      format: 'p'
+    }, {
+      title: 'Header 1',
+      format: 'h1'
+    }, {
+      title: 'Header 2',
+      format: 'h2'
+    }, {
+      title: 'Header 3',
+      format: 'h3'
+    }, {
+      title: 'Header 4',
+      format: 'h4'
+    }, {
+      title: 'Header 5',
+      format: 'h5'
+    }, {
+      title: 'Header 6',
+      format: 'h6'
+    }, {
+      title: 'Pre',
+      format: 'pre'
+    }, {
+      title: 'Code',
+      format: 'code'
+    }]
+  },
+  plain: {
+    plugins: '',
+    toolbar: ''
+  },
+  minimal: {
+    plugins: 'link autolink',
+    toolbar: 'bold italic underline | link',
+    valid_elements: 'strong,em,span[style],a[href]'
+  }
+};
+/**
+ * TinyMCE path
+ *
+ * @internal
+ */
+const __TINYMCE_PATH_ON_DOTCMS__ = '/ext/tinymcev7/tinymce.min.js';
+
+exports.CUSTOM_NO_COMPONENT = _public.CUSTOM_NO_COMPONENT;
+exports.DEVELOPMENT_MODE = _public.DEVELOPMENT_MODE;
+exports.EMPTY_CONTAINER_STYLE_ANGULAR = _public.EMPTY_CONTAINER_STYLE_ANGULAR;
+exports.EMPTY_CONTAINER_STYLE_REACT = _public.EMPTY_CONTAINER_STYLE_REACT;
+exports.END_CLASS = _public.END_CLASS;
+exports.PRODUCTION_MODE = _public.PRODUCTION_MODE;
+exports.START_CLASS = _public.START_CLASS;
+exports.__UVE_EVENTS__ = _public.__UVE_EVENTS__;
+exports.__UVE_EVENT_ERROR_FALLBACK__ = _public.__UVE_EVENT_ERROR_FALLBACK__;
+exports.combineClasses = _public.combineClasses;
+exports.computeScrollIsInBottom = _public.computeScrollIsInBottom;
+exports.findDotCMSElement = _public.findDotCMSElement;
+exports.findDotCMSVTLData = _public.findDotCMSVTLData;
+exports.getClosestDotCMSContainerData = _public.getClosestDotCMSContainerData;
+exports.getColumnPositionClasses = _public.getColumnPositionClasses;
+exports.getContainersData = _public.getContainersData;
+exports.getContentletsInContainer = _public.getContentletsInContainer;
+exports.getDotCMSContainerData = _public.getDotCMSContainerData;
+exports.getDotCMSContentletsBound = _public.getDotCMSContentletsBound;
+exports.getDotCMSPageBounds = _public.getDotCMSPageBounds;
+exports.getDotContainerAttributes = _public.getDotContainerAttributes;
+exports.getDotContentletAttributes = _public.getDotContentletAttributes;
+exports.isValidBlocks = _public.isValidBlocks;
+exports.setBounds = _public.setBounds;
+exports.__BASE_TINYMCE_CONFIG_WITH_NO_DEFAULT__ = __BASE_TINYMCE_CONFIG_WITH_NO_DEFAULT__;
+exports.__DEFAULT_TINYMCE_CONFIG__ = __DEFAULT_TINYMCE_CONFIG__;
+exports.__TINYMCE_PATH_ON_DOTCMS__ = __TINYMCE_PATH_ON_DOTCMS__;

package/internal.cjs.mjs

@@ -0,0 +1,2 @@
+export * from './internal.cjs.js';
+export { _default as default } from './internal.cjs.default.js';

package/internal.esm.d.ts

@@ -0,0 +1 @@
+export * from "./src/internal";

package/internal.esm.js

@@ -0,0 +1,75 @@
+export { C as CUSTOM_NO_COMPONENT, D as DEVELOPMENT_MODE, h as EMPTY_CONTAINER_STYLE_ANGULAR, f as EMPTY_CONTAINER_STYLE_REACT, E as END_CLASS, P as PRODUCTION_MODE, S as START_CLASS, _ as __UVE_EVENTS__, d as __UVE_EVENT_ERROR_FALLBACK__, q as combineClasses, p as computeScrollIsInBottom, n as findDotCMSElement, o as findDotCMSVTLData, m as getClosestDotCMSContainerData, t as getColumnPositionClasses, w as getContainersData, x as getContentletsInContainer, l as getDotCMSContainerData, k as getDotCMSContentletsBound, j as getDotCMSPageBounds, y as getDotContainerAttributes, v as getDotContentletAttributes, A as isValidBlocks, z as setBounds } from './public.esm.js';
+import '@dotcms/types';
+import '@dotcms/types/internal';
+
+/**
+ * TinyMCE default config across all versions
+ *
+ * @internal
+ */
+const __DEFAULT_TINYMCE_CONFIG__ = {
+  menubar: false,
+  inline: true,
+  valid_styles: {
+    '*': 'font-size,font-family,color,text-decoration,text-align'
+  },
+  powerpaste_word_import: 'clean',
+  powerpaste_html_import: 'clean',
+  suffix: '.min' // Suffix to use when loading resources
+};
+/**
+ * TinyMCE config to use per mode
+ *
+ * @internal
+ */
+const __BASE_TINYMCE_CONFIG_WITH_NO_DEFAULT__ = {
+  full: {
+    plugins: 'link lists autolink charmap',
+    toolbar: ['styleselect undo redo | bold italic underline | forecolor backcolor | alignleft aligncenter alignright alignfull | numlist bullist outdent indent | hr charmap removeformat | link'],
+    style_formats: [{
+      title: 'Paragraph',
+      format: 'p'
+    }, {
+      title: 'Header 1',
+      format: 'h1'
+    }, {
+      title: 'Header 2',
+      format: 'h2'
+    }, {
+      title: 'Header 3',
+      format: 'h3'
+    }, {
+      title: 'Header 4',
+      format: 'h4'
+    }, {
+      title: 'Header 5',
+      format: 'h5'
+    }, {
+      title: 'Header 6',
+      format: 'h6'
+    }, {
+      title: 'Pre',
+      format: 'pre'
+    }, {
+      title: 'Code',
+      format: 'code'
+    }]
+  },
+  plain: {
+    plugins: '',
+    toolbar: ''
+  },
+  minimal: {
+    plugins: 'link autolink',
+    toolbar: 'bold italic underline | link',
+    valid_elements: 'strong,em,span[style],a[href]'
+  }
+};
+/**
+ * TinyMCE path
+ *
+ * @internal
+ */
+const __TINYMCE_PATH_ON_DOTCMS__ = '/ext/tinymcev7/tinymce.min.js';
+
+export { __BASE_TINYMCE_CONFIG_WITH_NO_DEFAULT__, __DEFAULT_TINYMCE_CONFIG__, __TINYMCE_PATH_ON_DOTCMS__ };

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@dotcms/uve",
-  "version": "0.0.1-beta.3",
+  "version": "0.0.1-beta.31",
   "description": "Official JavaScript library for interacting with Universal Visual Editor (UVE)",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/dotCMS/core.git#main"
   },
+  "devDependencies": {
+    "@dotcms/types": "next"
+  },
   "keywords": [
     "dotCMS",
     "CMS",
@@ -21,11 +24,11 @@
       "import": "./index.cjs.mjs",
       "default": "./index.cjs.js"
     },
-    "./types": {
-      "module": "./types.esm.js",
-      "types": "./types.esm.d.ts",
-      "import": "./types.cjs.mjs",
-      "default": "./types.cjs.js"
+    "./internal": {
+      "module": "./internal.esm.js",
+      "types": "./internal.esm.d.ts",
+      "import": "./internal.cjs.mjs",
+      "default": "./internal.cjs.js"
     }
   },
   "typesVersions": {
@@ -33,8 +36,8 @@
       ".": [
         "./src/index.d.ts"
       ],
-      "types": [
-        "./src/types.d.ts"
+      "internal": [
+        "./src/internal.d.ts"
       ]
     }
   },