@dotcms/uve 1.6.0 → 1.7.0-next.37

package/src/internal/constants.d.ts

@@ -81,3 +81,26 @@ export declare const CUSTOM_NO_COMPONENT = "CustomNoComponent";
  * @internal
  */
 export declare const DOT_SECTION_ID_PREFIX = "dot-section-";
+/**
+ * Window flag set by `@dotcms/analytics` when content analytics is initialized
+ * and active on the page.
+ *
+ * @important This value is intentionally duplicated from `@dotcms/analytics`
+ * (`ANALYTICS_WINDOWS_ACTIVE_KEY` in dot-analytics.constants.ts). The SDKs read
+ * it in live mode to decide whether to keep the minimal contentlet attributes
+ * Analytics depends on. Both constants MUST stay in sync.
+ *
+ * @internal
+ */
+export declare const ANALYTICS_ACTIVE_WINDOW_KEY = "__dotAnalyticsActive__";
+/**
+ * Event dispatched by `@dotcms/analytics` once analytics is ready. The SDKs
+ * listen for it so live-mode contentlets can re-render with the attributes
+ * Analytics needs, regardless of initialization order.
+ *
+ * @important Kept in sync with the `dotcms:analytics:ready` event dispatched by
+ * `@dotcms/analytics` (initializeContentAnalytics).
+ *
+ * @internal
+ */
+export declare const ANALYTICS_READY_EVENT = "dotcms:analytics:ready";

package/src/internal/contentlet-sentinel.constants.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Sentinel values for the placeholder contentlet used when the UVE represents
+ * an empty container (e.g. hover / selection without a real contentlet).
+ *
+ * @internal
+ */
+export declare const TEMP_EMPTY_CONTENTLET: "TEMP_EMPTY_CONTENTLET";
+/**
+ * Placeholder `contentType` for {@link TEMP_EMPTY_CONTENTLET}.
+ *
+ * @internal
+ */
+export declare const TEMP_EMPTY_CONTENTLET_TYPE: "TEMP_EMPTY_CONTENTLET_TYPE";

package/src/internal/events.d.ts

@@ -26,15 +26,22 @@ export declare function onPageReload(callback: UVEEventHandler): {
     event: UVEEventType;
 };
 /**
- * Subscribes to request bounds events in the UVE editor
+ * The single bounds-sync channel. Observes the iframe document and
+ * every `[data-dot-object="container"]` with a single ResizeObserver,
+ * debounces the trailing edge by {@link AUTO_BOUNDS_DEBOUNCE_MS}ms, and
+ * emits the full `getDotCMSPageBounds(...)` payload whenever the layout
+ * settles. Also listens on `scroll` (since scrolling moves contentlets
+ * without changing layout) and on `UVE_FLUSH_BOUNDS` (the editor's
+ * "give me bounds NOW, skip the debounce" message used during drag).
+ *
+ * Re-runs `querySelectorAll` and the observer wiring whenever a
+ * MutationObserver detects child changes that touch container nodes,
+ * so containers that mount/unmount after page-load are picked up
+ * automatically.
  *
- * @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): {
+export declare function onAutoBounds(callback: UVEEventHandler): {
     unsubscribe: () => void;
     event: UVEEventType;
 };
@@ -66,9 +73,15 @@ export declare function onScrollToSection(callback: UVEEventHandler): {
     event: UVEEventType;
 };
 /**
- * Subscribes to contentlet hover events in the UVE editor
+ * Subscribes to contentlet hover events in the UVE editor.
  *
- * @param {UVEEventHandler} callback - Function to be called when a contentlet is hovered
+ * The callback is invoked with a payload while the pointer is over a
+ * DotCMS element, and once with `null` when the pointer leaves the last
+ * reported element (transitions onto dead space). The editor uses the
+ * `null` signal to clear the hover overlay so it doesn't linger over
+ * areas that no longer have a contentlet under the pointer.
+ *
+ * @param {UVEEventHandler} callback - Function to be called when hover state changes
  * @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
@@ -78,3 +91,18 @@ export declare function onContentletHovered(callback: UVEEventHandler): {
     unsubscribe: () => void;
     event: UVEEventType;
 };
+/**
+ * Subscribes to contentlet click events in the UVE editor.
+ *
+ * The editor's hover overlay is `pointer-events: none` so wheel events pass
+ * through to the iframe. We detect the user's selection click here instead and
+ * post it back to the editor.
+ *
+ * @param {UVEEventHandler} callback - Function to be called when a contentlet is clicked
+ * @returns {Object} Object containing unsubscribe function and event type
+ * @internal
+ */
+export declare function onContentletClicked(callback: UVEEventHandler): {
+    unsubscribe: () => void;
+    event: UVEEventType;
+};

package/src/internal/index.d.ts

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

package/src/internal.d.ts

@@ -1,6 +1,5 @@
 export * from './internal/index';
 export * from './lib/core/core.utils';
-export * from './lib/dom/document-height-observer';
 export * from './lib/dom/dom.utils';
 export * from './lib/editor/internal';
 export { defineStyleEditorSchema, normalizeForm, registerStyleEditorSchemas } from './lib/style-editor/internal';

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

@@ -1,5 +1,5 @@
 import { DotCMSBasicContentlet, DotCMSColumnContainer, DotCMSPageAsset, DotPageAssetLayoutColumn, EditableContainerData } from '@dotcms/types';
-import { DotCMSContainerBound, DotCMSContentletBound, DotContainerAttributes, DotContentletAttributes } from '@dotcms/types/internal';
+import { DotAnalyticsContentletAttributes, DotCMSContainerBound, DotCMSContentletBound, DotContainerAttributes, DotContentletAttributes } from '@dotcms/types/internal';
 /**
  * Calculates the bounding information for each page element within the given containers.
  *
@@ -152,6 +152,28 @@ export declare const getColumnPositionClasses: (column: DotPageAssetLayoutColumn
  * @returns {DotContentletAttributes} The dotCMS data attributes
  */
 export declare function getDotContentletAttributes(contentlet: DotCMSBasicContentlet, container: string): DotContentletAttributes;
+/**
+ *
+ * Returns the minimal set of contentlet data attributes required by DotCMS
+ * Analytics (impression & click tracking) to identify a contentlet.
+ *
+ * Used in live mode where the full editor metadata is stripped but Analytics
+ * still needs to resolve the contentlet behind an impression/click.
+ *
+ * @param {DotCMSBasicContentlet} contentlet - The contentlet to get the attributes for
+ * @returns {DotAnalyticsContentletAttributes} The Analytics-required data attributes
+ */
+export declare function getAnalyticsContentletAttributes(contentlet: DotCMSBasicContentlet): DotAnalyticsContentletAttributes;
+/**
+ *
+ * Checks whether DotCMS Analytics is initialized and active on the page.
+ *
+ * The SDKs use this in live mode to decide whether to keep the minimal
+ * contentlet attributes Analytics depends on.
+ *
+ * @returns {boolean} `true` when analytics is active, otherwise `false`
+ */
+export declare function isDotAnalyticsActive(): boolean;
 /**
  *
  *
@@ -203,3 +225,40 @@ export declare const getContentletsInContainer: (dotCMSPageAsset: DotCMSPageAsse
  * // Returns: { 'data-dot-object': 'container', 'data-dot-identifier': 'cont1', ... }
  */
 export declare function getDotContainerAttributes({ uuid, identifier, acceptTypes, maxContentlets }: EditableContainerData): DotContainerAttributes;
+/**
+ * Read a contentlet's dataset attributes off a DOM element and return a
+ * normalized contentlet object. Mirrors the shape consumed by the editor's
+ * SET_BOUNDS and CONTENTLET_CLICKED events. Optionally parses the
+ * `dotStyleProperties` JSON when present.
+ */
+export declare function readContentletDataset(element: HTMLElement): {
+    dotStyleProperties?: any;
+    identifier: string | undefined;
+    title: string | undefined;
+    inode: string | undefined;
+    contentType: string | undefined;
+    baseType: string | undefined;
+    widgetTitle: string | undefined;
+    onNumberOfPages: string | undefined;
+};
+/**
+ * Returns Zone.js's *unpatched* native `addEventListener` / `removeEventListener`
+ * bound to `target`, falling back to the standard methods when Zone.js is absent.
+ *
+ * UVE reuses a single iframe and rewrites it with `document.open()/write()/close()`
+ * on every in-editor navigation. When Zone.js is loaded inside that iframe it runs
+ * in global-events mode: one native "gateway" listener per (target, eventType)
+ * plus a JS-level task list stored on the target node. `document.open()` tears down
+ * the native gateway on the persistent `window`/`document` nodes, but the task list
+ * survives on them, so Zone sees "already registered" on re-init and skips
+ * re-installing the native gateway — the listener silently goes dead after the
+ * first navigation.
+ *
+ * Hover/click dodge this by binding to `document.documentElement`, a node that
+ * `write()` recreates fresh. `scroll`/`message` (on `window`) and
+ * `DOMContentLoaded` (on `document`) can't: none of them fire on `<html>`, so
+ * there is no fresh node to rebind to. Going through Zone's native (untracked)
+ * methods sidesteps the dedup entirely, so the listener rebinds cleanly after
+ * every rewrite.
+ */
+export declare function getNativeEventBinder<T extends Window | Document>(target: T): Pick<T, 'addEventListener' | 'removeEventListener'>;

package/src/script/utils.d.ts

@@ -51,34 +51,6 @@ export declare function setClientIsReady(config?: DotCMSPageResponse): void;
 export declare function listenBlockEditorInlineEvent(): {
     destroyListenBlockEditorInlineEvent: () => void;
 };
-/**
- * Returns whether iframe height must be synchronized via postMessage.
- *
- * Same-origin parents can measure iframe content directly, so they do not need
- * child-driven height reporting. Cross-origin parents cannot access the iframe
- * DOM, so they still need the reporter fallback.
- */
-export declare function shouldReportIframeHeightToParent(): boolean;
-/**
- * Reports the iframe document height to the parent UVE shell via postMessage.
- *
- * Uses ResizeObserver on <html> for viewport/font/image-driven size changes, and
- * MutationObserver on <body> to catch DOM removals (e.g. contentlets deleted by
- * the editor) that shrink the page without triggering a resize event.
- *
- * Measurement reads `document.documentElement.offsetHeight` — the actual rendered
- * height of the <html> element after layout. `scrollHeight` is intentionally avoided
- * because it does not reliably decrease when content is removed from the DOM.
- *
- * Height sends are coalesced to at most one per double-requestAnimationFrame pair
- * so they always run after layout and paint have settled.
- *
- * @returns {{ destroyHeightReporter: () => void }} Cleanup function that removes
- * all listeners and disconnects the observers.
- */
-export declare function reportIframeHeight(): {
-    destroyHeightReporter: () => void;
-};
 /**
  * Injects UVE editor styles for empty containers and contentlets into the page.
  * Provides visual placeholders so editors can identify and interact with empty areas.

package/src/lib/dom/document-height-observer.d.ts

@@ -1,18 +0,0 @@
-export interface ObserveDocumentHeightOptions {
-    onHeightChange: (height: number) => void;
-    documentRef?: Document;
-    windowRef?: Window;
-    debounceMs?: number;
-}
-export interface DocumentHeightObserverHandle {
-    destroy: () => void;
-}
-/**
- * Observes rendered document height changes and notifies the caller after layout settles.
- *
- * Uses ResizeObserver on <html> for layout/viewport-driven changes and MutationObserver
- * on <body> to catch DOM additions/removals that may shrink the page without a resize.
- * Measurement reads `body.offsetHeight`, which tracks actual content height and
- * decreases correctly after DOM removals, unaffected by CSS min-height on the html element.
- */
-export declare function observeDocumentHeight({ onHeightChange, documentRef, windowRef, debounceMs }: ObserveDocumentHeightOptions): DocumentHeightObserverHandle;