@dotcms/uve 0.0.1-beta.9 → 1.0.0

package/src/index.d.ts

@@ -1 +1,2 @@
-export * from './lib/utils';
+export * from './lib/core/core.utils';
+export * from './lib/editor/public';

package/src/internal/constants.d.ts

@@ -1,11 +1,11 @@
-import { UVEEvent } from '../lib/types/editor/public';
+import { UVEEventSubscriber, UVEEventType } from '@dotcms/types';
 /**
  * Events that can be subscribed to in the UVE
  *
  * @internal
- * @type {Record<string, UVEEvent>}
+ * @type {Record<UVEEventType, UVEEventSubscriber>}
  */
-export declare const __UVE_EVENTS__: Record<string, UVEEvent>;
+export declare const __UVE_EVENTS__: Record<UVEEventType, UVEEventSubscriber>;
 /**
  * Default UVE event
  *
@@ -16,3 +16,61 @@ export declare const __UVE_EVENT_ERROR_FALLBACK__: (event: string) => {
     unsubscribe: () => void;
     event: string;
 };
+/**
+ * Development mode
+ *
+ * @internal
+ */
+export declare const DEVELOPMENT_MODE = "development";
+/**
+ * Production mode
+ *
+ * @internal
+ */
+export declare const PRODUCTION_MODE = "production";
+/**
+ * End class
+ *
+ * @internal
+ */
+export declare const END_CLASS = "col-end-";
+/**
+ * Start class
+ *
+ * @internal
+ */
+export declare const START_CLASS = "col-start-";
+/**
+ * Empty container style for React
+ *
+ * @internal
+ */
+export declare const EMPTY_CONTAINER_STYLE_REACT: {
+    width: string;
+    backgroundColor: string;
+    display: string;
+    justifyContent: string;
+    alignItems: string;
+    color: string;
+    height: string;
+};
+/**
+ * Empty container style for Angular
+ *
+ * @internal
+ */
+export declare const EMPTY_CONTAINER_STYLE_ANGULAR: {
+    width: string;
+    'background-color': string;
+    display: string;
+    'justify-content': string;
+    'align-items': string;
+    color: string;
+    height: string;
+};
+/**
+ * Custom no component
+ *
+ * @internal
+ */
+export declare const CUSTOM_NO_COMPONENT = "CustomNoComponent";

package/src/internal/events.d.ts

@@ -0,0 +1,66 @@
+import { UVEEventHandler, UVEEventType } from '@dotcms/types';
+/**
+ * Subscribes to content changes in the UVE editor
+ *
+ * @param {UVEEventHandler} callback - Function to be called when content changes are detected
+ * @returns {Object} Object containing unsubscribe function and event type
+ * @returns {Function} .unsubscribe - Function to remove the event listener
+ * @returns {UVEEventType} .event - The event type being subscribed to
+ * @internal
+ */
+export declare function onContentChanges(callback: UVEEventHandler): {
+    unsubscribe: () => void;
+    event: UVEEventType;
+};
+/**
+ * Subscribes to page reload events in the UVE editor
+ *
+ * @param {UVEEventHandler} callback - Function to be called when page reload is triggered
+ * @returns {Object} Object containing unsubscribe function and event type
+ * @returns {Function} .unsubscribe - Function to remove the event listener
+ * @returns {UVEEventType} .event - The event type being subscribed to
+ * @internal
+ */
+export declare function onPageReload(callback: UVEEventHandler): {
+    unsubscribe: () => void;
+    event: UVEEventType;
+};
+/**
+ * Subscribes to request bounds events in the UVE editor
+ *
+ * @param {UVEEventHandler} callback - Function to be called when bounds are requested
+ * @returns {Object} Object containing unsubscribe function and event type
+ * @returns {Function} .unsubscribe - Function to remove the event listener
+ * @returns {UVEEventType} .event - The event type being subscribed to
+ * @internal
+ */
+export declare function onRequestBounds(callback: UVEEventHandler): {
+    unsubscribe: () => void;
+    event: UVEEventType;
+};
+/**
+ * Subscribes to iframe scroll events in the UVE editor
+ *
+ * @param {UVEEventHandler} callback - Function to be called when iframe scroll occurs
+ * @returns {Object} Object containing unsubscribe function and event type
+ * @returns {Function} .unsubscribe - Function to remove the event listener
+ * @returns {UVEEventType} .event - The event type being subscribed to
+ * @internal
+ */
+export declare function onIframeScroll(callback: UVEEventHandler): {
+    unsubscribe: () => void;
+    event: UVEEventType;
+};
+/**
+ * Subscribes to contentlet hover events in the UVE editor
+ *
+ * @param {UVEEventHandler} callback - Function to be called when a contentlet is hovered
+ * @returns {Object} Object containing unsubscribe function and event type
+ * @returns {Function} .unsubscribe - Function to remove the event listener
+ * @returns {UVEEventType} .event - The event type being subscribed to
+ * @internal
+ */
+export declare function onContentletHovered(callback: UVEEventHandler): {
+    unsubscribe: () => void;
+    event: UVEEventType;
+};

package/src/internal/index.d.ts

@@ -1 +1,2 @@
 export * from './constants';
+export * from './tinymce.config';

package/src/internal/tinymce.config.d.ts

@@ -0,0 +1,45 @@
+/**
+ * TinyMCE default config across all versions
+ *
+ * @internal
+ */
+export declare const __DEFAULT_TINYMCE_CONFIG__: {
+    menubar: boolean;
+    inline: boolean;
+    valid_styles: {
+        '*': string;
+    };
+    powerpaste_word_import: string;
+    powerpaste_html_import: string;
+    suffix: string;
+};
+/**
+ * TinyMCE config to use per mode
+ *
+ * @internal
+ */
+export declare const __BASE_TINYMCE_CONFIG_WITH_NO_DEFAULT__: {
+    full: {
+        plugins: string;
+        toolbar: string[];
+        style_formats: {
+            title: string;
+            format: string;
+        }[];
+    };
+    plain: {
+        plugins: string;
+        toolbar: string;
+    };
+    minimal: {
+        plugins: string;
+        toolbar: string;
+        valid_elements: string;
+    };
+};
+/**
+ * TinyMCE path
+ *
+ * @internal
+ */
+export declare const __TINYMCE_PATH_ON_DOTCMS__ = "/ext/tinymcev7/tinymce.min.js";

package/src/internal.d.ts

@@ -1,3 +1,3 @@
 export * from './internal/index';
-export * from './lib/types/editor/internal';
-export * from './lib/types/events/internal';
+export * from './lib/dom/dom.utils';
+export * from './lib/editor/internal';

package/src/lib/{utils.d.ts → core/core.utils.d.ts}

@@ -1,4 +1,4 @@
-import { UVECallback, UVEState, UVESubscription } from './types/editor/public';
+import { UVEState, UVEEventSubscription, UVEEventType, UVEEventPayloadMap } from '@dotcms/types';
 /**
  * Gets the current state of the Universal Visual Editor (UVE).
  *
@@ -31,15 +31,19 @@ export declare function getUVEState(): UVEState | undefined;
 /**
  * Creates a subscription to a UVE event.
  *
- * @param {string} event - The event to subscribe to.
- * @param {UVECallback} callback - The callback to call when the event is triggered.
- * @return {UnsubscribeUVE | undefined} The unsubscribe function if the event is valid, undefined otherwise.
+ * @param eventType - The type of event to subscribe to
+ * @param callback - The callback function that will be called when the event occurs
+ * @returns An event subscription that can be used to unsubscribe
  *
  * @example
  * ```ts
- * const unsubscribeChanges = createUVESubscription('changes', (payload) => {
- *   console.log(payload);
+ * // Subscribe to page changes
+ * const subscription = createUVESubscription(UVEEventType.CONTENT_CHANGES, (changes) => {
+ *   console.log('Content changes:', changes);
  * });
+ *
+ * // Later, unsubscribe when no longer needed
+ * subscription.unsubscribe();
  * ```
  */
-export declare function createUVESubscription(event: string, callback: UVECallback): UVESubscription;
+export declare function createUVESubscription<T extends UVEEventType>(eventType: T, callback: (payload: UVEEventPayloadMap[T] extends undefined ? void : UVEEventPayloadMap[T]) => void): UVEEventSubscription;

package/src/lib/dom/dom.utils.d.ts

@@ -0,0 +1,205 @@
+import { EditableContainerData, DotCMSColumnContainer, DotCMSBasicContentlet, DotCMSPageAsset, DotPageAssetLayoutColumn } from '@dotcms/types';
+import { DotCMSContainerBound, DotCMSContentletBound, DotContainerAttributes, DotContentletAttributes } from '@dotcms/types/internal';
+/**
+ * Calculates the bounding information for each page element within the given containers.
+ *
+ * @export
+ * @param {HTMLDivElement[]} containers - An array of HTMLDivElement representing the containers.
+ * @return {DotCMSContainerBound[]} An array of objects containing the bounding information for each page element.
+ * @example
+ * ```ts
+ * const containers = document.querySelectorAll('.container');
+ * const bounds = getDotCMSPageBounds(containers);
+ * console.log(bounds);
+ * ```
+ */
+export declare function getDotCMSPageBounds(containers: HTMLDivElement[]): DotCMSContainerBound[];
+/**
+ * Calculates the bounding information for each contentlet inside a container.
+ *
+ * @export
+ * @param {DOMRect} containerRect - The bounding rectangle of the container.
+ * @param {HTMLDivElement[]} contentlets - An array of HTMLDivElement representing the contentlets.
+ * @return {DotCMSContentletBound[]} An array of objects containing the bounding information for each contentlet.
+ * @example
+ * ```ts
+ * const containerRect = container.getBoundingClientRect();
+ * const contentlets = container.querySelectorAll('.contentlet');
+ * const bounds = getDotCMSContentletsBound(containerRect, contentlets);
+ * console.log(bounds); // Element bounds within the container
+ * ```
+ */
+export declare function getDotCMSContentletsBound(containerRect: DOMRect, contentlets: HTMLDivElement[]): DotCMSContentletBound[];
+/**
+ * Get container data from VTLS.
+ *
+ * @export
+ * @param {HTMLElement} container - The container element.
+ * @return {object} An object containing the container data.
+ * @example
+ * ```ts
+ * const container = document.querySelector('.container');
+ * const data = getContainerData(container);
+ * console.log(data);
+ * ```
+ */
+export declare function getDotCMSContainerData(container: HTMLElement): {
+    acceptTypes: string;
+    identifier: string;
+    maxContentlets: string;
+    uuid: string;
+};
+/**
+ * Get the closest container data from the contentlet.
+ *
+ * @export
+ * @param {Element} element - The contentlet element.
+ * @return {object | null} An object containing the closest container data or null if no container is found.
+ * @example
+ * ```ts
+ * const contentlet = document.querySelector('.contentlet');
+ * const data = getClosestDotCMSContainerData(contentlet);
+ * console.log(data);
+ * ```
+ */
+export declare function getClosestDotCMSContainerData(element: Element): {
+    acceptTypes: string;
+    identifier: string;
+    maxContentlets: string;
+    uuid: string;
+} | null;
+/**
+ * Find the closest contentlet element based on HTMLElement.
+ *
+ * @export
+ * @param {HTMLElement | null} element - The starting element.
+ * @return {HTMLElement | null} The closest contentlet element or null if not found.
+ * @example
+ * const element = document.querySelector('.some-element');
+ * const contentlet = findDotCMSElement(element);
+ * console.log(contentlet);
+ */
+export declare function findDotCMSElement(element: HTMLElement | null): HTMLElement | null;
+/**
+ * Find VTL data within a target element.
+ *
+ * @export
+ * @param {HTMLElement} target - The target element to search within.
+ * @return {Array<{ inode: string, name: string }> | null} An array of objects containing VTL data or null if none found.
+ * @example
+ * ```ts
+ * const target = document.querySelector('.target-element');
+ * const vtlData = findDotCMSVTLData(target);
+ * console.log(vtlData);
+ * ```
+ */
+export declare function findDotCMSVTLData(target: HTMLElement): {
+    inode: string | undefined;
+    name: string | undefined;
+}[] | null;
+/**
+ * Check if the scroll position is at the bottom of the page.
+ *
+ * @export
+ * @return {boolean} True if the scroll position is at the bottom, otherwise false.
+ * @example
+ * ```ts
+ * if (dotCMSScrollIsInBottom()) {
+ *     console.log('Scrolled to the bottom');
+ * }
+ * ```
+ */
+export declare function computeScrollIsInBottom(): boolean;
+/**
+ *
+ *
+ * Combine classes into a single string.
+ *
+ * @param {string[]} classes
+ * @returns {string} Combined classes
+ */
+export declare const combineClasses: (classes: string[]) => string;
+/**
+ *
+ *
+ * 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
+ */
+export declare const getColumnPositionClasses: (column: DotPageAssetLayoutColumn) => {
+    startClass: string;
+    endClass: string;
+};
+/**
+ *
+ *
+ * Helper function that returns an object containing the dotCMS data attributes.
+ * @param {DotCMSBasicContentlet} contentlet - The contentlet to get the attributes for
+ * @param {string} container - The container to get the attributes for
+ * @returns {DotContentletAttributes} The dotCMS data attributes
+ */
+export declare function getDotContentletAttributes(contentlet: DotCMSBasicContentlet, container: string): DotContentletAttributes;
+/**
+ *
+ *
+ * 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 }
+ */
+export declare const getContainersData: (dotCMSPageAsset: DotCMSPageAsset, columContainer: DotCMSColumnContainer) => EditableContainerData | null;
+/**
+ *
+ *
+ * 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 {DotCMSBasicContentlet[]} Array of contentlets in the container
+ *
+ * @example
+ * const contentlets = getContentletsInContainer(pageAsset, containerRef);
+ * // Returns: [{ identifier: 'cont1', ... }, { identifier: 'cont2', ... }]
+ */
+export declare const getContentletsInContainer: (dotCMSPageAsset: DotCMSPageAsset, columContainer: DotCMSColumnContainer) => DotCMSBasicContentlet[];
+/**
+ *
+ *
+ * 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', ... }
+ */
+export declare function getDotContainerAttributes({ uuid, identifier, acceptTypes, maxContentlets }: EditableContainerData): DotContainerAttributes;

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

@@ -0,0 +1,23 @@
+import { BlockEditorContent } from '@dotcms/types';
+import { BlockEditorState, DotCMSContainerBound } from '@dotcms/types/internal';
+/**
+ * Sets the bounds of the containers in the editor.
+ * Retrieves the containers from the DOM and sends their position data to the editor.
+ * @private
+ * @memberof DotCMSPageEditor
+ */
+export declare function setBounds(bounds: DotCMSContainerBound[]): void;
+/**
+ * Validates the structure of a Block Editor block.
+ *
+ * This function checks that:
+ * 1. The blocks parameter is a valid object
+ * 2. The block has a 'doc' type
+ * 3. The block has a valid content array that is not empty
+ *
+ * @param {Block} blocks - The blocks structure to validate
+ * @returns {BlockEditorState} Object containing validation state and any error message
+ * @property {boolean} BlockEditorState.isValid - Whether the blocks structure is valid
+ * @property {string | null} BlockEditorState.error - Error message if invalid, null if valid
+ */
+export declare const isValidBlocks: (blocks: BlockEditorContent) => BlockEditorState;

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

@@ -0,0 +1,86 @@
+import { Contentlet, DotCMSInlineEditingPayload, DotCMSInlineEditingType, DotCMSBasicContentlet, DotCMSPageResponse } from '@dotcms/types';
+import { DotCMSReorderMenuConfig, DotCMSUVEMessage } from '@dotcms/types/internal';
+/**
+ * Updates the navigation in the editor.
+ *
+ * @param {string} pathname - The pathname to update the navigation with.
+ * @memberof DotCMSPageEditor
+ * @example
+ * updateNavigation('/home'); // Sends a message to the editor to update the navigation to '/home'
+ */
+export declare function updateNavigation(pathname: string): void;
+/**
+ * Post message to dotcms page editor
+ *
+ * @export
+ * @template T
+ * @param {DotCMSUVEMessage<T>} message
+ */
+export declare function sendMessageToUVE<T = unknown>(message: DotCMSUVEMessage<T>): void;
+/**
+ * You can use this function to edit a contentlet in the editor.
+ *
+ * Calling this function inside the editor, will prompt the UVE to open a dialog to edit the contentlet.
+ *
+ * @export
+ * @template T
+ * @param {Contentlet<T>} contentlet - The contentlet to edit.
+ */
+export declare function editContentlet<T>(contentlet: Contentlet<T>): void;
+export declare function reorderMenu(config?: DotCMSReorderMenuConfig): void;
+/**
+ * Initializes the inline editing in the editor.
+ *
+ * @export
+ * @param {INLINE_EDITING_EVENT_KEY} type
+ * @param {InlineEditEventData} eventData
+ * @return {*}
+ *
+ *  * @example
+ * ```html
+ * <div onclick="initInlineEditing('BLOCK_EDITOR', { inode, languageId, contentType, fieldName, content })">
+ *      ${My Content}
+ * </div>
+ * ```
+ */
+export declare function initInlineEditing(type: DotCMSInlineEditingType, data?: DotCMSInlineEditingPayload): void;
+/**
+ * Initializes the block editor inline editing for a contentlet field.
+ *
+ * @example
+ * ```html
+ * <div onclick="enableBlockEditorInline(contentlet, 'MY_BLOCK_EDITOR_FIELD_VARIABLE')">
+ *      ${My Content}
+ * </div>
+ * ```
+ *
+ * @export
+ * @param {DotCMSBasicContentlet} contentlet
+ * @param {string} fieldName
+ * @return {*}  {void}
+ */
+export declare function enableBlockEditorInline<T extends DotCMSBasicContentlet>(contentlet: T extends DotCMSBasicContentlet ? T : never, fieldName: keyof T): void;
+/**
+ * Initializes the Universal Visual Editor (UVE) with required handlers and event listeners.
+ *
+ * This function sets up:
+ * - Scroll handling
+ * - Empty contentlet styling
+ * - Block editor inline event listening
+ * - Client ready state
+ * - UVE event subscriptions
+ *
+ * @returns {Object} An object containing the cleanup function
+ * @returns {Function} destroyUVESubscriptions - Function to clean up all UVE event subscriptions
+ *
+ * @example
+ * ```typescript
+ * const { destroyUVESubscriptions } = initUVE();
+ *
+ * // When done with UVE
+ * destroyUVESubscriptions();
+ * ```
+ */
+export declare function initUVE(config?: DotCMSPageResponse): {
+    destroyUVESubscriptions: () => void;
+};

package/src/script/sdk-editor.d.ts

@@ -0,0 +1,6 @@
+declare global {
+    interface Window {
+        dotUVE: unknown;
+    }
+}
+export {};

package/src/script/utils.d.ts

@@ -0,0 +1,53 @@
+import { DotCMSPageResponse } from '@dotcms/types';
+/**
+ * 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(): {
+    destroyScrollHandler: () => 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(): {
+    subscriptions: import("@dotcms/types").UVEEventSubscription[];
+};
+/**
+ * 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(config?: DotCMSPageResponse): void;
+/**
+ * Listen for block editor inline event.
+ */
+export declare function listenBlockEditorInlineEvent(): {
+    destroyListenBlockEditorInlineEvent: () => void;
+};

package/src/lib/types/editor/internal.d.ts

@@ -1,44 +0,0 @@
-import { DotCMSUVEAction } from './public';
-/**
- * @description Custom client parameters for fetching data.
- */
-export type DotCMSCustomerParams = {
-    depth: string;
-};
-/**
- * Configuration for reordering a menu.
- */
-export interface DotCMSReorderMenuConfig {
-    /**
-     * The starting level of the menu to be reordered.
-     */
-    startLevel: number;
-    /**
-     * The depth of the menu levels to be reordered.
-     */
-    depth: number;
-}
-declare global {
-    interface Window {
-        dotCMSUVE: DotCMSUVE;
-    }
-}
-/**
- * Post message props
- *
- * @export
- * @template T
- * @interface DotCMSUVEMessage
- */
-export type DotCMSUVEMessage<T> = {
-    action: DotCMSUVEAction;
-    payload?: T;
-};
-type DotCMSUVEFunction = (...args: any[]) => void;
-export interface DotCMSUVE {
-    editContentlet: DotCMSUVEFunction;
-    initInlineEditing: DotCMSUVEFunction;
-    reorderMenu: DotCMSUVEFunction;
-    lastScrollYPosition: number;
-}
-export {};