@dotcms/client 0.0.1-alpha.4 → 0.0.1-alpha.40

package/src/lib/editor/listeners/listeners.ts

@@ -0,0 +1,223 @@
+import { CUSTOMER_ACTIONS, postMessageToEditor } from '../models/client.model';
+import { DotCMSPageEditorSubscription, NOTIFY_CUSTOMER } from '../models/listeners.model';
+import {
+    findVTLData,
+    findDotElement,
+    getClosestContainerData,
+    getPageElementBound,
+    scrollIsInBottom
+} from '../utils/editor.utils';
+
+declare global {
+    interface Window {
+        lastScrollYPosition: number;
+    }
+}
+
+/**
+ * Represents an array of DotCMSPageEditorSubscription objects.
+ * Used to store the subscriptions for the editor and unsubscribe later.
+ */
+export const subscriptions: DotCMSPageEditorSubscription[] = [];
+
+/**
+ * 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
+ */
+function setBounds(): void {
+    const containers = Array.from(
+        document.querySelectorAll('[data-dot-object="container"]')
+    ) as HTMLDivElement[];
+    const positionData = getPageElementBound(containers);
+
+    postMessageToEditor({
+        action: CUSTOMER_ACTIONS.SET_BOUNDS,
+        payload: positionData
+    });
+}
+
+/**
+ * Listens for editor messages and performs corresponding actions based on the received message.
+ *
+ * @private
+ * @memberof DotCMSPageEditor
+ */
+export function listenEditorMessages(): void {
+    const messageCallback = (event: MessageEvent) => {
+        switch (event.data) {
+            case NOTIFY_CUSTOMER.EMA_REQUEST_BOUNDS: {
+                setBounds();
+                break;
+            }
+        }
+
+        if (event.data.name === NOTIFY_CUSTOMER.EMA_SCROLL_INSIDE_IFRAME) {
+            const direction = event.data.direction;
+
+            if (
+                (window.scrollY === 0 && direction === 'up') ||
+                (scrollIsInBottom() && direction === 'down')
+            ) {
+                // If the iframe scroll is at the top or bottom, do not send anything.
+                // This avoids losing the scrollend event.
+                return;
+            }
+
+            const scrollY = direction === 'up' ? -120 : 120;
+            window.scrollBy({ left: 0, top: scrollY, behavior: 'smooth' });
+        }
+    };
+
+    window.addEventListener('message', messageCallback);
+
+    subscriptions.push({
+        type: 'listener',
+        event: 'message',
+        callback: messageCallback
+    });
+}
+
+/**
+ * Listens for pointer move events and extracts information about the hovered contentlet.
+ *
+ * @private
+ * @memberof DotCMSPageEditor
+ */
+export function listenHoveredContentlet(): void {
+    const pointerMoveCallback = (event: PointerEvent) => {
+        const foundElement = findDotElement(event.target as HTMLElement);
+
+        if (!foundElement) return;
+
+        const { x, y, width, height } = foundElement.getBoundingClientRect();
+
+        const isContainer = foundElement.dataset?.['dotObject'] === 'container';
+
+        const contentletForEmptyContainer = {
+            identifier: 'TEMP_EMPTY_CONTENTLET',
+            title: 'TEMP_EMPTY_CONTENTLET',
+            contentType: 'TEMP_EMPTY_CONTENTLET_TYPE',
+            inode: 'TEMPY_EMPTY_CONTENTLET_INODE',
+            widgetTitle: 'TEMP_EMPTY_CONTENTLET',
+            baseType: 'TEMP_EMPTY_CONTENTLET',
+            onNumberOfPages: 1
+        };
+
+        const contentlet = {
+            identifier: foundElement.dataset?.['dotIdentifier'],
+            title: foundElement.dataset?.['dotTitle'],
+            inode: foundElement.dataset?.['dotInode'],
+            contentType: foundElement.dataset?.['dotType'],
+            baseType: foundElement.dataset?.['dotBasetype'],
+            widgetTitle: foundElement.dataset?.['dotWidgetTitle'],
+            onNumberOfPages: foundElement.dataset?.['dotOnNumberOfPages']
+        };
+
+        const vtlFiles = findVTLData(foundElement);
+        const contentletPayload = {
+            container:
+                // Here extract dot-container from contentlet if it is Headless
+                // or search in parent container if it is VTL
+                foundElement.dataset?.['dotContainer']
+                    ? JSON.parse(foundElement.dataset?.['dotContainer'])
+                    : getClosestContainerData(foundElement),
+            contentlet: isContainer ? contentletForEmptyContainer : contentlet,
+            vtlFiles
+        };
+
+        postMessageToEditor({
+            action: CUSTOMER_ACTIONS.SET_CONTENTLET,
+            payload: {
+                x,
+                y,
+                width,
+                height,
+                payload: contentletPayload
+            }
+        });
+    };
+
+    document.addEventListener('pointermove', pointerMoveCallback);
+
+    subscriptions.push({
+        type: 'listener',
+        event: 'pointermove',
+        callback: pointerMoveCallback
+    });
+}
+
+/**
+ * Attaches a scroll event listener to the window
+ * and sends a message to the editor when the window is scrolled.
+ *
+ * @private
+ * @memberof DotCMSPageEditor
+ */
+export function scrollHandler(): void {
+    const scrollCallback = () => {
+        postMessageToEditor({
+            action: CUSTOMER_ACTIONS.IFRAME_SCROLL
+        });
+        window.lastScrollYPosition = window.scrollY;
+    };
+
+    const scrollEndCallback = () => {
+        postMessageToEditor({
+            action: CUSTOMER_ACTIONS.IFRAME_SCROLL_END
+        });
+    };
+
+    window.addEventListener('scroll', scrollCallback);
+    window.addEventListener('scrollend', scrollEndCallback);
+
+    subscriptions.push({
+        type: 'listener',
+        event: 'scroll',
+        callback: scrollEndCallback
+    });
+
+    subscriptions.push({
+        type: 'listener',
+        event: 'scroll',
+        callback: scrollCallback
+    });
+}
+
+/**
+ * Restores the scroll position of the window when an iframe is loaded.
+ * Only used in VTL Pages.
+ * @export
+ * @example
+ * ```ts
+ * preserveScrollOnIframe();
+ * ```
+ */
+export function preserveScrollOnIframe(): void {
+    const preserveScrollCallback = () => {
+        window.scrollTo(0, window.lastScrollYPosition);
+    };
+
+    window.addEventListener('load', preserveScrollCallback);
+    subscriptions.push({
+        type: 'listener',
+        event: 'scroll',
+        callback: preserveScrollCallback
+    });
+}
+
+/**
+ * Sends a message to the editor to get the page data.
+ * @param {string} pathname - The pathname of the page.
+ * @private
+ * @memberof DotCMSPageEditor
+ */
+export function fetchPageDataFromInsideUVE(pathname: string) {
+    postMessageToEditor({
+        action: CUSTOMER_ACTIONS.GET_PAGE_DATA,
+        payload: {
+            pathname
+        }
+    });
+}

package/src/lib/editor/models/client.model.ts

@@ -0,0 +1,84 @@
+/**
+ * Actions send to the dotcms editor
+ *
+ * @export
+ * @enum {number}
+ */
+export enum CUSTOMER_ACTIONS {
+    /**
+     * Tell the dotcms editor that page change
+     */
+    NAVIGATION_UPDATE = 'set-url',
+    /**
+     * Send the element position of the rows, columnsm containers and contentlets
+     */
+    SET_BOUNDS = 'set-bounds',
+    /**
+     * Send the information of the hovered contentlet
+     */
+    SET_CONTENTLET = 'set-contentlet',
+    /**
+     * Tell the editor that the page is being scrolled
+     */
+    IFRAME_SCROLL = 'scroll',
+    /**
+     * Tell the editor that the page has stopped scrolling
+     */
+    IFRAME_SCROLL_END = 'scroll-end',
+    /**
+     * Ping the editor to see if the page is inside the editor
+     */
+    PING_EDITOR = 'ping-editor',
+    /**
+     * Tell the editor to init the inline editing editor.
+     */
+    INIT_INLINE_EDITING = 'init-inline-editing',
+    /**
+     * Tell the editor to open the Copy-contentlet dialog
+     * To copy a content and then edit it inline.
+     */
+    COPY_CONTENTLET_INLINE_EDITING = 'copy-contentlet-inline-editing',
+    /**
+     * Tell the editor to save inline edited contentlet
+     */
+    UPDATE_CONTENTLET_INLINE_EDITING = 'update-contentlet-inline-editing',
+    /**
+     * Tell the editor to trigger a menu reorder
+     */
+    REORDER_MENU = 'reorder-menu',
+    /**
+     * Tell the editor to send the page info to iframe
+     */
+    GET_PAGE_DATA = 'get-page-data',
+    /**
+     * Tell the editor an user send a graphql query
+     */
+    CLIENT_READY = 'client-ready',
+    /**
+     * Tell the editor to do nothing
+     */
+    NOOP = 'noop'
+}
+
+/**
+ * Post message props
+ *
+ * @export
+ * @template T
+ * @interface PostMessageProps
+ */
+type PostMessageProps<T> = {
+    action: CUSTOMER_ACTIONS;
+    payload?: T;
+};
+
+/**
+ * Post message to dotcms page editor
+ *
+ * @export
+ * @template T
+ * @param {PostMessageProps<T>} message
+ */
+export function postMessageToEditor<T = unknown>(message: PostMessageProps<T>) {
+    window.parent.postMessage(message, '*');
+}

package/src/lib/editor/models/editor.model.ts

@@ -0,0 +1,53 @@
+/**
+ * @description Custom client parameters for fetching data.
+ */
+export type CustomClientParams = {
+    depth: string;
+};
+
+/**
+ * @description Union type for fetch configurations.
+ * @typedef {GraphQLFetchConfig | PageAPIFetchConfig} DotCMSFetchConfig
+ */
+export type EditorConfig =
+    | {
+          params: CustomClientParams;
+      }
+    | {
+          query: string;
+      };
+
+/**
+ * Represents the configuration options for the DotCMS page editor.
+ * @export
+ * @interface DotCMSPageEditorConfig
+ */
+export interface DotCMSPageEditorConfig {
+    /**
+     * The pathname of the page being edited. Optional.
+     * @type {string}
+     */
+    pathname: string;
+    /**
+     *
+     * @type {DotCMSFetchConfig}
+     * @memberof DotCMSPageEditorConfig
+     * @description The configuration custom params for data fetching on Edit Mode.
+     * @example <caption>Example with Custom GraphQL query</caption>
+     * const config: DotCMSPageEditorConfig = {
+     *   editor: { query: 'query { ... }' }
+     * };
+     *
+     * @example <caption>Example usage with Custom Page API parameters</caption>
+     * const config: DotCMSPageEditorConfig = {
+     *   editor: { params: { depth: '2' } }
+     * };
+     */
+    editor?: EditorConfig;
+    /**
+     * The reload function to call when the page is reloaded.
+     * @deprecated In future implementation we will be listening for the changes from the editor to update the page state so reload will not be needed.
+     * @type {Function}
+     */
+    onReload?: () => void;
+}

package/src/lib/editor/models/listeners.model.ts

@@ -0,0 +1,50 @@
+/**
+ * Actions received from the dotcms editor
+ *
+ * @export
+ * @enum {number}
+ */
+export enum NOTIFY_CUSTOMER {
+    /**
+     * Request to page to reload
+     */
+    EMA_RELOAD_PAGE = 'ema-reload-page',
+    /**
+     * Request the bounds for the elements
+     */
+    EMA_REQUEST_BOUNDS = 'ema-request-bounds',
+    /**
+     * Received pong from the editor
+     */
+    EMA_EDITOR_PONG = 'ema-editor-pong',
+    /**
+     * Received scroll event trigger from the editor
+     */
+    EMA_SCROLL_INSIDE_IFRAME = 'scroll-inside-iframe'
+}
+
+type ListenerCallbackMessage = (event: MessageEvent) => void;
+type ListenerCallbackPointer = (event: PointerEvent) => void;
+
+/**
+ * Listener for the dotcms editor
+ *
+ * @interface DotCMSPageEditorListener
+ */
+interface DotCMSPageEditorListener {
+    type: 'listener';
+    event: string;
+    callback: ListenerCallbackMessage | ListenerCallbackPointer;
+}
+
+/**
+ * Observer for the dotcms editor
+ *
+ * @interface DotCMSPageEditorObserver
+ */
+interface DotCMSPageEditorObserver {
+    type: 'observer';
+    observer: MutationObserver;
+}
+
+export type DotCMSPageEditorSubscription = DotCMSPageEditorListener | DotCMSPageEditorObserver;

package/src/lib/editor/sdk-editor-vtl.ts

@@ -0,0 +1,31 @@
+import {
+    listenEditorMessages,
+    listenHoveredContentlet,
+    preserveScrollOnIframe,
+    scrollHandler
+} from './listeners/listeners';
+import { isInsideEditor, addClassToEmptyContentlets } from './sdk-editor';
+
+declare global {
+    interface Window {
+        lastScrollYPosition: number;
+    }
+}
+
+/**
+ * This is the main entry point for the SDK VTL.
+ * This is added to VTL Script in the EditPage
+ *
+ * @remarks
+ * This module sets up the necessary listeners and functionality for the SDK VTL.
+ * It checks if the script is running inside the editor and then initializes the client by pinging the editor,
+ * listening for editor messages, hovered contentlet changes, and content changes.
+ *
+ */
+if (isInsideEditor()) {
+    listenEditorMessages();
+    scrollHandler();
+    preserveScrollOnIframe();
+    listenHoveredContentlet();
+    addClassToEmptyContentlets();
+}

package/src/lib/editor/sdk-editor.spec.ts

@@ -0,0 +1,116 @@
+import {
+    listenEditorMessages,
+    listenHoveredContentlet,
+    fetchPageDataFromInsideUVE,
+    scrollHandler
+} from './listeners/listeners';
+import { postMessageToEditor, CUSTOMER_ACTIONS } from './models/client.model';
+import {
+    addClassToEmptyContentlets,
+    initEditor,
+    isInsideEditor,
+    updateNavigation
+} from './sdk-editor';
+
+jest.mock('./models/client.model', () => ({
+    postMessageToEditor: jest.fn(),
+    CUSTOMER_ACTIONS: {
+        NAVIGATION_UPDATE: 'set-url',
+        SET_BOUNDS: 'set-bounds',
+        SET_CONTENTLET: 'set-contentlet',
+        IFRAME_SCROLL: 'scroll',
+        PING_EDITOR: 'ping-editor',
+        CONTENT_CHANGE: 'content-change',
+        NOOP: 'noop'
+    }
+}));
+
+jest.mock('./listeners/listeners', () => ({
+    pingEditor: jest.fn(),
+    listenEditorMessages: jest.fn(),
+    listenHoveredContentlet: jest.fn(),
+    scrollHandler: jest.fn(),
+    listenContentChange: jest.fn(),
+    fetchPageDataFromInsideUVE: jest.fn()
+}));
+
+describe('DotCMSPageEditor', () => {
+    describe('is NOT inside editor', () => {
+        beforeEach(() => {
+            const mockWindow = {
+                ...window,
+                parent: window
+            };
+
+            const spy = jest.spyOn(global, 'window', 'get');
+            spy.mockReturnValueOnce(mockWindow as unknown as Window & typeof globalThis);
+        });
+
+        afterEach(() => {
+            jest.clearAllMocks();
+        });
+
+        it('should initialize without any listener', () => {
+            const addEventListenerSpy = jest.spyOn(window, 'addEventListener');
+
+            expect(isInsideEditor()).toBe(false);
+            expect(addEventListenerSpy).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('is inside editor', () => {
+        beforeEach(() => {
+            const mockWindow = {
+                ...window,
+                parent: null
+            };
+
+            const spy = jest.spyOn(global, 'window', 'get');
+            spy.mockReturnValue(mockWindow as unknown as Window & typeof globalThis);
+        });
+
+        afterEach(() => {
+            jest.clearAllMocks();
+        });
+
+        it('should initialize properly', () => {
+            expect(isInsideEditor()).toBe(true);
+        });
+
+        it('should update navigation', () => {
+            updateNavigation('/');
+            expect(postMessageToEditor).toHaveBeenCalledWith({
+                action: CUSTOMER_ACTIONS.NAVIGATION_UPDATE,
+                payload: {
+                    url: 'index'
+                }
+            });
+        });
+
+        it('should init editor calling listeners', () => {
+            initEditor({ pathname: 'some-url' });
+            expect(fetchPageDataFromInsideUVE).toHaveBeenCalledWith('some-url');
+            expect(listenEditorMessages).toHaveBeenCalled();
+            expect(listenHoveredContentlet).toHaveBeenCalled();
+            expect(scrollHandler).toHaveBeenCalled();
+        });
+    });
+
+    describe('Add Class to Empty Contentets', () => {
+        it('should add class to empty contentlets', () => {
+            const contentlet = document.createElement('div');
+            contentlet.setAttribute('data-dot-object', 'contentlet');
+            Object.defineProperty(contentlet, 'clientHeight', { value: 100 }); // Emulate a contentlet with height in the DOM
+            document.body.appendChild(contentlet);
+
+            const emptyContentlet = document.createElement('div');
+            emptyContentlet.setAttribute('data-dot-object', 'contentlet');
+            document.body.appendChild(emptyContentlet);
+
+            addClassToEmptyContentlets();
+
+            expect(emptyContentlet.classList.contains('empty-contentlet')).toBe(true);
+            expect(contentlet.classList.contains('empty-contentlet')).toBe(false);
+        });
+    });
+});

package/src/lib/editor/sdk-editor.ts

@@ -0,0 +1,105 @@
+import {
+    fetchPageDataFromInsideUVE,
+    listenEditorMessages,
+    listenHoveredContentlet,
+    scrollHandler,
+    subscriptions
+} from './listeners/listeners';
+import { CUSTOMER_ACTIONS, postMessageToEditor } from './models/client.model';
+import { DotCMSPageEditorConfig } from './models/editor.model';
+
+/**
+ * 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 function updateNavigation(pathname: string): void {
+    postMessageToEditor({
+        action: CUSTOMER_ACTIONS.NAVIGATION_UPDATE,
+        payload: {
+            url: pathname === '/' ? 'index' : pathname?.replace('/', '')
+        }
+    });
+}
+
+/**
+ * Checks if the code is running inside an editor.
+ *
+ * @returns {boolean} Returns true if the code is running inside an editor, otherwise false.
+ * @example
+ * ```ts
+ * if (isInsideEditor()) {
+ *     console.log('Running inside the editor');
+ * } else {
+ *     console.log('Running outside the editor');
+ * }
+ * ```
+ */
+export function isInsideEditor(): boolean {
+    if (typeof window === 'undefined') {
+        return false;
+    }
+
+    return window.parent !== window;
+}
+
+/**
+ * Initializes the DotCMS page editor.
+ *
+ * @param {DotCMSPageEditorConfig} config - Optional configuration for the editor.
+ * @example
+ * ```ts
+ * const config = { pathname: '/home' };
+ * initEditor(config); // Initializes the editor with the provided configuration
+ * ```
+ */
+export function initEditor(config: DotCMSPageEditorConfig): void {
+    fetchPageDataFromInsideUVE(config.pathname);
+    listenEditorMessages();
+    listenHoveredContentlet();
+    scrollHandler();
+}
+
+/**
+ * Destroys the editor by removing event listeners and disconnecting observers.
+ *
+ * @example
+ * ```ts
+ * destroyEditor(); // Cleans up the editor by removing all event listeners and disconnecting observers
+ * ```
+ */
+export function destroyEditor(): void {
+    subscriptions.forEach((subscription) => {
+        if (subscription.type === 'listener') {
+            window.removeEventListener(subscription.event, subscription.callback as EventListener);
+        }
+
+        if (subscription.type === 'observer') {
+            subscription.observer.disconnect();
+        }
+    });
+}
+
+/**
+ * Adds a style class to empty contentlets.
+ *
+ * @export
+ * @example
+ * ```ts
+ * addClassToEmptyContentlets(); // Adds the 'empty-contentlet' class to all contentlets that have no height
+ * ```
+ */
+export function addClassToEmptyContentlets(): void {
+    const contentlets = document.querySelectorAll('[data-dot-object="contentlet"]');
+
+    contentlets.forEach((contentlet) => {
+        if (contentlet.clientHeight) {
+            return;
+        }
+
+        contentlet.classList.add('empty-contentlet');
+    });
+}