@elyx-code/editor-ui 0.0.2

package/src/services/editor/CanvasPopup.tsx

@@ -0,0 +1,749 @@
+import React, { useCallback, useEffect, useMemo } from 'react';
+import { createRoot, ReactRoot } from '../../utils/react';
+import { RelativeObject, RelativeObjectsState } from '../../lib/canvas';
+import { Placement } from '../../lib/canvas/defs';
+import { onClickAway } from '../../utils/DOM';
+import { Logger } from '@elyx-code/common-ts-utils';
+import { EditorService } from './EditorService';
+
+export interface ICanvasPopupProps {
+	// The parent canvas object that will hold the popup
+	// Sometimes popups are nested, so the parent canvas object might be another popup
+	parentCanvasObject: RelativeObjectsState;
+	editor: EditorService;
+	placement?: Placement;
+	id?: string;
+	anchorQuerySelector: string;
+	arrowClasses?: string[];
+	persisted?: boolean;
+	arrowContainerSelector?: string;
+	offset?: number;
+}
+
+/*
+	This component is an abstraction on the popups used inside the canvas
+	The canvas engine works in a way that makes most popup positioning libraries not work correctly
+
+	The canvas engine offers an alternaive through "RelativeObjects"
+	which are elements that are relative to another canvas element (objects)
+
+	The common use cases are for tooltips and popup menus
+
+	Relative objects an be nested, meaning, you can have a tooltip hovering over a popup menu
+	That would mean a relative object inside another relative object
+*/
+export default class CanvasPopup {
+	// Fallback to random unique id to reference in DOM if no id is provided
+	id: string;
+	anchor: HTMLElement | null = null;
+
+	self: RelativeObject | null = null;
+
+	initialized: boolean = false;
+	destroyed: boolean = false;
+
+	anchorRef: (node: HTMLElement) => void;
+
+	hoverOptions: {
+		openDelay: number;
+		closeDelay: number;
+	} | null = null;
+
+	// The parent canvas object that will hold the popup
+	// Sometimes popups are nested, so the parent canvas object might be another popup
+	parentCanvasObject: RelativeObjectsState;
+	node: ReactRoot | null = null;
+	element: HTMLElement | null = null;
+	placement?: Placement;
+	anchorQuerySelector: string;
+	arrowClasses?: string[];
+	persisted?: boolean;
+	arrowContainerSelector?: string;
+	offset?: number;
+	editor: EditorService;
+
+	openTimeout: ReturnType<typeof setTimeout>;
+	closeTimeout: ReturnType<typeof setTimeout>;
+
+	hasRenderedBody: boolean = false;
+
+	bodyCallback: (canvasObject: CanvasPopup) => React.ReactNode;
+	bodyAsyncCallback: (
+		canvasObject: CanvasPopup
+	) =>
+		| [
+				string | number | boolean | React.FC<any> | React.ComponentType<any>,
+				{ [key: string]: any }
+		  ]
+		| [
+				string | number | boolean | React.FC<any> | React.ComponentType<any>,
+				{ [key: string]: any },
+				React.ReactNode
+		  ];
+
+	onBeforeShowCallback: (e: MouseEvent, popup: CanvasPopup) => boolean;
+
+	onClickAwayAsyncRenderCleanup: () => void;
+	onClickAwayRenderCleanup: () => void;
+
+	private _subscribedEvents: Array<{
+		event: string;
+		listener: EventListenerOrEventListenerObject;
+		element: HTMLElement;
+	}> = [];
+
+	static globalCanvasPopups: { [id: string]: CanvasPopup } = {};
+
+	static init(props: ICanvasPopupProps) {
+		// If the popup already exists, return it
+		if (CanvasPopup.globalCanvasPopups[props.id]) {
+			return CanvasPopup.globalCanvasPopups[props.id];
+		}
+
+		const popup = new CanvasPopup(props);
+
+		CanvasPopup.globalCanvasPopups[popup.id] = popup;
+
+		return popup;
+	}
+
+	static register(popup: CanvasPopup): CanvasPopup {
+		CanvasPopup.globalCanvasPopups[popup.id] = popup;
+
+		return popup;
+	}
+
+	constructor(props: ICanvasPopupProps) {
+		this.id = props.id || Math.random().toString(36).substring(2, 9);
+		this.parentCanvasObject = props.parentCanvasObject;
+		this.anchorQuerySelector = props.anchorQuerySelector;
+		this.arrowClasses = props.arrowClasses;
+		this.persisted = props.persisted;
+		this.arrowContainerSelector = props.arrowContainerSelector;
+		this.placement = props.placement;
+		this.offset = props.offset;
+		this.editor = props.editor;
+
+		if (!this.editor) {
+			throw new Error('Missing editor instance in props')
+		}
+
+		this.onClickAway = this.onClickAway.bind(this);
+		this.onEscapeKeyPress = this.onEscapeKeyPress.bind(this);
+	}
+
+	get open(): boolean {
+		return !!(
+			this.self !== null &&
+			this.node !== null &&
+			this.element &&
+			this.element.style.display !== 'none'
+		);
+	}
+
+	// The popup is ready to be rendered when there is
+	// a body callback
+	// and has been initialized
+	get ready(): boolean {
+		return !!this.bodyCallback && this.initialized;
+	}
+
+	toProps(): ICanvasPopupProps {
+		return {
+			parentCanvasObject: this.parentCanvasObject,
+			placement: this.placement,
+			id: this.id,
+			anchorQuerySelector: this.anchorQuerySelector,
+			arrowClasses: this.arrowClasses,
+			persisted: this.persisted,
+			arrowContainerSelector: this.arrowContainerSelector,
+			offset: this.offset,
+			editor: this.editor,
+		};
+	}
+
+	// If the anchor element is not in the state, re-query it
+	getAnchorElement(): HTMLElement {
+		if (!this.anchor) {
+			this.anchor = document.querySelector(this.anchorQuerySelector);
+		}
+
+		return this.anchor;
+	}
+
+	// Callback to run before showing the popup
+	// User must returns true or false, true for showing, false for preventing the popup from showing
+	onBeforeShow(
+		callback: (e: MouseEvent, popup: CanvasPopup) => boolean
+	): CanvasPopup {
+		this.onBeforeShowCallback = callback;
+
+		return this;
+	}
+
+	showTooltip = (e: MouseEvent) => {
+		if (this.onBeforeShowCallback && !this.onBeforeShowCallback(e, this)) {
+			return;
+		}
+
+		this.openTimeout = setTimeout(() => {
+			if (!!this.closeTimeout) {
+				clearTimeout(this.closeTimeout);
+			}
+
+			this.show(false, e);
+			// this.self?.calculatePosition();
+		}, this.hoverOptions?.openDelay || 0);
+	};
+
+	onMouseEnter = (e: Event) => {
+		if (!!this.closeTimeout) {
+			clearTimeout(this.closeTimeout);
+		}
+	};
+
+	hideTooltip = (e: Event) => {
+		this.closeTimeout = setTimeout(() => {
+			if (!!this.openTimeout) {
+				clearTimeout(this.openTimeout);
+			}
+
+			this.hide();
+		}, this.hoverOptions?.closeDelay || 0);
+	};
+
+	setupHover(
+		{
+			openDelay,
+			closeDelay,
+		}: {
+			openDelay?: number;
+			closeDelay?: number;
+		} = {
+			openDelay: 0,
+			closeDelay: 0,
+		}
+	): CanvasPopup {
+		this.hoverOptions = {
+			openDelay,
+			closeDelay,
+		};
+
+		const anchor = this.getAnchorElement();
+
+		if (!this.node) {
+			return this;
+		}
+
+		if (!anchor) {
+			Logger.warn(
+				'Anchor element not found for canvas popup: ',
+				this.anchorQuerySelector
+			);
+			return this;
+		}
+
+		this._subscribedEvents.forEach(({ event, listener, element }) => {
+			element?.removeEventListener(event as any, listener as any);
+		});
+		this._subscribedEvents = [];
+
+		this._subscribedEvents.push({
+			event: 'mouseenter',
+			listener: this.onMouseEnter,
+			element: this.element!,
+		});
+		this._subscribedEvents.push({
+			event: 'mouseleave',
+			listener: this.hideTooltip,
+			element: this.element!,
+		});
+
+		this.element?.addEventListener('mouseenter', this.onMouseEnter);
+
+		this.element?.addEventListener('mouseleave', this.hideTooltip);
+
+		const events = [
+			['mouseenter', this.showTooltip],
+			['mouseleave', this.hideTooltip],
+			['focus', this.showTooltip],
+			['blur', this.hideTooltip],
+		];
+
+		events.forEach(([event, listener]) => {
+			anchor?.addEventListener(event as any, listener as any);
+			this._subscribedEvents.push({
+				event: event as any,
+				listener: listener as any,
+				element: anchor!,
+			});
+		});
+
+		return this;
+	}
+
+	body(callback: (canvasObject: CanvasPopup) => React.ReactNode): CanvasPopup {
+		this.bodyCallback = callback;
+
+		this.render();
+
+		return this;
+	}
+
+	async bodyAsync(
+		callback: (canvasObject: CanvasPopup) =>
+			| [
+					string | number | boolean | React.FC<any> | React.ComponentType<any>,
+					{
+						[key: string]: any;
+					}
+			  ]
+			| [
+					string | number | boolean | React.FC<any> | React.ComponentType<any>,
+					{
+						[key: string]: any;
+					},
+					React.ReactNode
+			  ]
+	): Promise<CanvasPopup> {
+		this.bodyAsyncCallback = callback;
+
+		await this.renderAsync();
+
+		return this;
+	}
+
+	onClickAway() {
+		if (!this.self?.persisted) {
+			this.hide();
+		}
+	}
+
+	async renderAsync() {
+		if (this.destroyed) {
+			return this;
+		}
+
+		if (this.editor.destroyed) {
+			return this;
+		}
+
+		if (!this.parentCanvasObject) {
+			Logger.warn(
+				'Parent canvas object not found for canvas popup: ',
+				this.anchorQuerySelector
+			);
+			return this;
+		}
+
+		if (!this.bodyAsyncCallback) {
+			Logger.warn(
+				'Body async callback not found for canvas popup: ',
+				this.anchorQuerySelector
+			);
+			return this;
+		}
+
+		const bodyParts = this.bodyAsyncCallback(this);
+
+		if (!this.node) {
+			// Create a new DOM tree
+			this.node = createRoot('#' + this.id);
+		}
+
+		await this.node.render(bodyParts[0], bodyParts[1], bodyParts[2], {
+			onError: (error) => {
+				Logger.log('Error rendering canvas popup: ', error);
+				this.editor.events.emit('canvas-react-error', error);
+			},
+		});
+
+		if (!!this.hoverOptions) {
+			this.setupHover({
+				openDelay: this.hoverOptions.openDelay,
+				closeDelay: this.hoverOptions.closeDelay,
+			});
+		}
+
+		if (this.self) {
+			this.self.element = this.element;
+
+			this.self.setup();
+		}
+
+		this.hide();
+
+		this.onClickAwayAsyncRenderCleanup?.();
+		this.onClickAwayRenderCleanup?.();
+
+		const cleanup = onClickAway(this.node.ref, this.onClickAway);
+
+		this.onClickAwayAsyncRenderCleanup = cleanup;
+
+		return this;
+	}
+
+	render(): CanvasPopup {
+		if (this.destroyed) {
+			return this;
+		}
+
+		if (this.editor.destroyed) {
+			return this;
+		}
+
+		if (!this.parentCanvasObject) {
+			Logger.warn(
+				'Parent canvas object not found for canvas popup: ',
+				this.anchorQuerySelector
+			);
+			return this;
+		}
+
+		if (!this.bodyCallback) {
+			Logger.warn(
+				'Body callback not found for canvas popup: ',
+				this.anchorQuerySelector
+			);
+			return this;
+		}
+
+		const body = this.bodyCallback(this);
+		if (!this.node) {
+			// Create a new DOM tree
+			this.node = createRoot('#' + this.id);
+		}
+
+		this.node.renderRaw(body);
+
+		if (!!body) {
+			this.hasRenderedBody = true;
+		}
+
+		if (!!this.hoverOptions) {
+			this.setupHover({
+				openDelay: this.hoverOptions.openDelay,
+				closeDelay: this.hoverOptions.closeDelay,
+			});
+		}
+
+		if (this.self) {
+			this.self.element = this.element;
+			this.self.setup();
+		}
+
+		this.onClickAwayAsyncRenderCleanup?.();
+		this.onClickAwayRenderCleanup?.();
+
+		const cleanup = onClickAway(this.node.ref, this.onClickAway);
+
+		this.onClickAwayRenderCleanup = cleanup;
+
+		return this;
+	}
+
+	// Triggered by the body react component when it has finished rendering
+	onBodyReady() {
+		this.self?.setupArrowElement();
+		this.self?.calculatePosition();
+	}
+
+	onEscapeKeyPress() {
+		this.hide();
+	}
+
+	setup(): CanvasPopup {
+		if (this.destroyed) {
+			return this;
+		}
+
+		if (this.editor.destroyed) {
+			return this;
+		}
+
+		this.editor.on('escape-key-press', this.onEscapeKeyPress);
+
+		const parentCanvasObject = this.parentCanvasObject;
+
+		if (!parentCanvasObject) {
+			Logger.warn(
+				'Parent canvas object not found for canvas popup: ',
+				this.anchorQuerySelector
+			);
+			return this;
+		}
+
+		// Use native canvas service to create a new relative position element
+		// For this draggable object and the header element as the anchor
+		const anchor = this.getAnchorElement();
+		if (!anchor) {
+			Logger.warn(
+				'Anchor element not found for canvas popup: ',
+				this.anchorQuerySelector
+			);
+			return this;
+		}
+
+		this.element = document.createElement('span');
+
+		// Append to canvas
+		this.parentCanvasObject.canvas.canvasElement.appendChild(this.element);
+
+		this.self = parentCanvasObject.addRelativeObject({
+			anchor: anchor,
+			placement: this.placement || 'right',
+			id: this.id,
+			// Temporary element
+			element: this.element,
+			arrowClasses: ['popup-arrow', ...(this.arrowClasses || [])],
+			persisted: this.persisted,
+			arrowContainerSelector: this.arrowContainerSelector,
+			offset: this.offset,
+		});
+
+		this.self.onBeforeDelete(() => {
+			this.self = null;
+			// If the parent element is deleted, the canvas engine will delete the relative object too
+			this.destroy();
+		});
+
+		this.hide();
+
+		this.initialized = true;
+
+		return this;
+	}
+
+	show(
+		hideUnrelated: boolean = true,
+		e: MouseEvent | null = null
+	): CanvasPopup {
+		if (this.onBeforeShowCallback && !this.onBeforeShowCallback(e, this)) {
+			return;
+		}
+
+		if (this.destroyed) {
+			return this;
+		}
+
+		// Enrich all
+		if (!this.self) {
+			this.setup();
+		}
+
+		const anchor = this.getAnchorElement();
+		if (!anchor) {
+			Logger.warn(
+				'Anchor element not found for canvas popup: ',
+				this.anchorQuerySelector
+			);
+			return this;
+		}
+
+		this.self.anchor = anchor;
+
+		if (this.self) {
+			if (hideUnrelated) {
+				const parentCanvasObject = this.parentCanvasObject;
+
+				if (!parentCanvasObject) {
+					Logger.warn(
+						'Parent canvas object not found for canvas popup: ',
+						this.anchorQuerySelector
+					);
+					return this;
+				}
+
+				const canvas = parentCanvasObject.canvas;
+
+				canvas.hideAllRelativeObjectsExcept(this.self);
+			}
+
+			if (!!this.bodyAsyncCallback) {
+				this.renderAsync().then(() => {
+					setTimeout(() => {
+						if (!this.self) return;
+
+						this.self.show();
+
+						// Regenerate arrow if it doesn't exist anymore
+						if (
+							!this.self.arrowElement ||
+							!this.element.contains(this.self.arrowElement)
+						) {
+							this.self.setupArrowElement();
+						}
+
+						this.self?.calculatePosition();
+					}, 16);
+				});
+			} else {
+				this.render();
+
+				setTimeout(() => {
+					if (!this.self) return;
+					this.self.show();
+
+					// Regenerate arrow if it doesn't exist anymore
+					if (
+						!this.self.arrowElement ||
+						!this.element.contains(this.self.arrowElement)
+					) {
+						this.self.setupArrowElement();
+					}
+
+					this.self?.calculatePosition();
+				}, 16);
+			}
+		}
+
+		return this;
+	}
+
+	hide(): CanvasPopup {
+		if (this.self) {
+			this.self.hide();
+		}
+
+		return this;
+	}
+
+	toggle(
+		hideUnrelated: boolean = true,
+		e: MouseEvent | null = null
+	): CanvasPopup {
+		if (this.open) {
+			this.hide();
+		} else {
+			this.show(hideUnrelated, e);
+		}
+
+		return this;
+	}
+
+	// Updates the dom element
+	refresh(
+		callback: (canvasObject: CanvasPopup) => React.ReactNode = this.bodyCallback
+	): CanvasPopup {
+		this.bodyCallback = callback;
+
+		this.render();
+
+		return this;
+	}
+
+	async refreshAsync(
+		callback: (
+			canvasObject: CanvasPopup
+		) =>
+			| [
+					string | number | boolean | React.FC<any> | React.ComponentType<any>,
+					{ [key: string]: any }
+			  ]
+			| [
+					string | number | boolean | React.FC<any> | React.ComponentType<any>,
+					{ [key: string]: any },
+					React.ReactNode
+			  ]
+	): Promise<CanvasPopup> {
+		this.bodyAsyncCallback = callback;
+
+		await this.renderAsync();
+
+		return this;
+	}
+
+	async destroy() {
+		this.destroyed = true;
+		this.initialized = false;
+
+		// Remove from global popups
+		delete CanvasPopup.globalCanvasPopups[this.id];
+
+		this._subscribedEvents.forEach(({ event, listener, element }) => {
+			element?.removeEventListener(event as any, listener as any);
+		});
+		this._subscribedEvents = [];
+
+		this.onClickAwayAsyncRenderCleanup?.();
+		this.onClickAwayRenderCleanup?.();
+		this.onClickAwayAsyncRenderCleanup = null;
+		this.onClickAwayRenderCleanup = null;
+
+		if (this.node && this.node.mounted && !this.node.unmounting) {
+			await this.node.unmount();
+			this.node = null;
+		}
+
+		if (this.self) {
+			this.parentCanvasObject?.removeRelativeObject(this.self);
+			// Remove tree
+			this.self = null;
+		}
+
+		if (this.element && window.document.body.contains(this.element)) {
+			this.element.remove();
+			this.element = null;
+		}
+
+		this.editor.off('escape-key-press', this.onEscapeKeyPress);
+	}
+}
+
+// Custom react hook to instanciate the popup:
+// only after render,
+// without duplication
+// and destroy it when the component is unmounted
+export function useCanvasPopup(
+	props: ICanvasPopupProps,
+	body: (popup: CanvasPopup) => React.ReactNode,
+	dependencies: any[] = []
+): CanvasPopup {
+	// 1. Memoize popup creation so it's stable per component instance
+	const popup = useMemo(() => CanvasPopup.init(props), [props.id]);
+
+	// 2. Memoize the body function. This is CRITICAL.
+	// We pass `popup` as a dependency, which is stable.
+	const memoizedBody = useCallback(body, [popup, ...dependencies]);
+
+	// 3. This anchorRef callback *only* sets the anchor. It does not setup or destroy.
+	const anchorRef = useCallback(
+		(anchorElement: HTMLElement | null) => {
+			if (anchorElement) {
+				popup.anchor = anchorElement;
+			}
+		},
+		[popup]
+	);
+	popup.anchorRef = anchorRef;
+
+	popup.bodyCallback = memoizedBody;
+
+	// 4. This useEffect handles setup AND refresh.
+	// It runs when the anchor is set, or when the body/props change.
+	useEffect(() => {
+		// Only setup if the anchor is actually set and in the DOM
+		if (popup.anchor && document.contains(popup.anchor)) {
+			if (!popup.initialized) {
+				// First time setup
+				CanvasPopup.register(popup);
+				popup.destroyed = false;
+				popup.setup().body(memoizedBody);
+			} else {
+				// Just refresh the body content
+				popup.refresh(memoizedBody);
+			}
+		}
+	}, [popup, memoizedBody, props.parentCanvasObject, popup.anchor]); // Re-run if anchor, body, or parent changes
+
+	// 5. This is the SINGLE source of truth for cleanup.
+	// It runs ONLY when the component using this hook unmounts.
+	useEffect(() => {
+		return () => {
+			Logger.log('useCanvasPopup unmounting, destroying:', popup.id);
+			popup.destroy();
+		};
+	}, [popup]); // This dependency is stable and correct.
+
+	return popup;
+}