@elementor/editor-v1-adapters 0.1.0

package/src/hooks/__tests__/use-is-route-active.test.ts

@@ -0,0 +1,93 @@
+import { act, renderHook } from '@testing-library/react-hooks';
+import useIsRouteActive from '../use-is-route-active';
+import { dispatchRouteClose, dispatchRouteOpen } from '../../__tests__/utils';
+import { mockIsRouteActive } from './test-utils';
+
+describe( '@elementor/editor-v1-adapters - useIsRouteActive', () => {
+	it( 'should return false when a route is inactive by default', () => {
+		// Arrange.
+		const route = 'panel/menu';
+
+		mockIsRouteActive( () => false );
+
+		// Act.
+		const { result } = renderHook( () => useIsRouteActive( route ) );
+
+		// Assert.
+		expect( result.current ).toBe( false );
+	} );
+
+	it( 'should return true when a route is active by default', () => {
+		// Arrange.
+		const route = 'panel/menu';
+
+		mockIsRouteActive( () => true );
+
+		// Act.
+		const { result } = renderHook( () => useIsRouteActive( route ) );
+
+		// Assert.
+		expect( result.current ).toBe( true );
+	} );
+
+	it( 'should return true when a route gets activated', () => {
+		// Arrange.
+		const route = 'panel/menu';
+
+		mockIsRouteActive( () => false );
+
+		// Act.
+		const { result } = renderHook( () => useIsRouteActive( route ) );
+
+		act( () => {
+			mockIsRouteActive( () => true );
+			dispatchRouteOpen( route );
+		} );
+
+		// Assert.
+		expect( result.current ).toBe( true );
+	} );
+
+	it( 'should return false when a route gets deactivated', () => {
+		// Arrange.
+		const route = 'panel/menu';
+
+		mockIsRouteActive( () => true );
+
+		// Act.
+		const { result } = renderHook( () => useIsRouteActive( route ) );
+
+		act( () => {
+			mockIsRouteActive( () => false );
+			dispatchRouteClose( route );
+		} );
+
+		// Assert.
+		expect( result.current ).toBe( false );
+	} );
+
+	it( 'should re-check whether the route is active when changing it', () => {
+		// Arrange.
+		mockIsRouteActive( ( r ) => {
+			return 'active/route' === r;
+		} );
+
+		// Act.
+		const { result, rerender } = renderHook( ( { route } ) => useIsRouteActive( route ), {
+			initialProps: {
+				route: 'active/route',
+			},
+		} );
+
+		// Assert.
+		expect( result.current ).toBe( true );
+
+		// Act.
+		rerender( {
+			route: 'inactive/route',
+		} );
+
+		// Assert.
+		expect( result.current ).toBe( false );
+	} );
+} );

package/src/hooks/__tests__/use-route-status.test.ts

@@ -0,0 +1,124 @@
+import { renderHook } from '@testing-library/react-hooks';
+import useRouteStatus from '../use-route-status';
+import { mockGetCurrentEditMode, mockIsRouteActive } from './test-utils';
+
+describe( '@elementor/editor-v1-adapters - useRouteStatus', () => {
+	it.each( [
+		{
+			input: {
+				isRouteActive: true,
+				isKitRouteActive: false,
+				isPreviewMode: false,
+				options: {},
+			},
+			expected: true,
+		},
+		{
+			input: {
+				isRouteActive: true,
+				isKitRouteActive: false,
+				isPreviewMode: true,
+				options: {
+					blockOnPreviewMode: false,
+				},
+			},
+			expected: true,
+		},
+		{
+			input: {
+				isRouteActive: false,
+				isKitRouteActive: false,
+				isPreviewMode: false,
+				options: {},
+			},
+			expected: false,
+		},
+		{
+			input: {
+				isRouteActive: true,
+				isKitRouteActive: false,
+				isPreviewMode: true,
+				options: {},
+			},
+			expected: false,
+		},
+	] )( 'should check if the route is active: isRouteActive = $input.isRouteActive, isPreviewMode = $input.isPreviewMode, options: $input.options', ( {
+		input: { isRouteActive, isKitRouteActive, isPreviewMode, options },
+		expected,
+	} ) => {
+		// Arrange
+		mockIsRouteActive( ( route ) => route === 'panel/global' ? isKitRouteActive : isRouteActive );
+		mockGetCurrentEditMode( () => isPreviewMode ? 'preview' : 'edit' );
+
+		// Act.
+		const { result } = renderHook( () => useRouteStatus( 'panel/page-settings', options ) );
+
+		// Assert.
+		expect( result.current.isActive ).toBe( expected );
+	} );
+
+	it.each( [
+		{
+			input: {
+				isRouteActive: false,
+				isKitRouteActive: false,
+				isPreviewMode: false,
+				options: {},
+			},
+			expected: false,
+		},
+		{
+			input: {
+				isRouteActive: false,
+				isKitRouteActive: false,
+				isPreviewMode: true,
+				options: {
+					blockOnPreviewMode: false,
+				},
+			},
+			expected: false,
+		},
+		{
+			input: {
+				isRouteActive: false,
+				isKitRouteActive: true,
+				isPreviewMode: false,
+				options: {
+					blockOnKitRoutes: false,
+				},
+			},
+			expected: false,
+		},
+		{
+			input: {
+				isRouteActive: false,
+				isKitRouteActive: true,
+				isPreviewMode: false,
+				options: {},
+			},
+			expected: true,
+		},
+		{
+			input: {
+				isRouteActive: false,
+				isKitRouteActive: false,
+				isPreviewMode: true,
+				options: {},
+			},
+			expected: true,
+		},
+	] )( 'should check if the route is blocked: isKitRouteActive = $input.isKitRouteActive, isPreviewMode = $input.isPreviewMode, options: $input.options', ( {
+		input: { isRouteActive, isKitRouteActive, isPreviewMode, options },
+		expected,
+	} ) => {
+		// Arrange
+		mockIsRouteActive( ( route ) => route === 'panel/global' ? isKitRouteActive : isRouteActive );
+		mockGetCurrentEditMode( () => isPreviewMode ? 'preview' : 'edit' );
+
+		// Act.
+		const { result } = renderHook( () => useRouteStatus( 'panel/page-settings', options ) );
+
+		// Assert.
+		expect( result.current.isBlocked ).toBe( expected );
+	} );
+} );

package/src/hooks/index.ts

@@ -0,0 +1,4 @@
+export { default as useIsPreviewMode } from './use-is-preview-mode';
+export { default as useIsRouteActive } from './use-is-route-active';
+export { default as useListenTo } from './use-listen-to';
+export { default as useRouteStatus } from './use-route-status';

package/src/hooks/use-is-preview-mode.ts

@@ -0,0 +1,10 @@
+import useListenTo from './use-listen-to';
+import { getCurrentEditMode } from '../readers';
+import { editModeChangeEvent } from '../listeners';
+
+export default function useIsPreviewMode() {
+	return useListenTo(
+		editModeChangeEvent(),
+		() => getCurrentEditMode() === 'preview'
+	);
+}

package/src/hooks/use-is-route-active.ts

@@ -0,0 +1,14 @@
+import useListenTo from './use-listen-to';
+import { isRouteActive } from '../readers';
+import { routeCloseEvent, routeOpenEvent, RouteEventDescriptor } from '../listeners';
+
+export default function useIsRouteActive( route: RouteEventDescriptor['name'] ) {
+	return useListenTo(
+		[
+			routeOpenEvent( route ),
+			routeCloseEvent( route ),
+		],
+		() => isRouteActive( route ),
+		[ route ]
+	);
+}

package/src/hooks/use-listen-to.ts

@@ -0,0 +1,21 @@
+import { useEffect, useState } from 'react';
+import { EventDescriptor, listenTo } from '../listeners';
+
+export default function useListenTo<T>(
+	event: EventDescriptor | EventDescriptor[],
+	getSnapshot: () => T,
+	deps: unknown[] = []
+) {
+	const [ snapshot, setSnapshot ] = useState( () => getSnapshot() );
+
+	useEffect( () => {
+		const updateState = () => setSnapshot( getSnapshot() );
+
+		// Ensure the state is re-calculated when the dependencies have been changed.
+		updateState();
+
+		return listenTo( event, updateState );
+	}, deps ); // eslint-disable-line react-hooks/exhaustive-deps
+
+	return snapshot;
+}

package/src/hooks/use-route-status.ts

@@ -0,0 +1,32 @@
+import useIsPreviewMode from './use-is-preview-mode';
+import useIsRouteActive from './use-is-route-active';
+import { RouteEventDescriptor } from '../listeners';
+
+type Options = {
+	blockOnKitRoutes?: boolean,
+	blockOnPreviewMode?: boolean,
+}
+
+export default function useRouteStatus(
+	route: RouteEventDescriptor['name'],
+	{
+		blockOnKitRoutes = true,
+		blockOnPreviewMode = true,
+	}: Options = {}
+) {
+	const isRouteActive = useIsRouteActive( route );
+	const isKitRouteActive = useIsRouteActive( 'panel/global' );
+	const isPreviewMode = useIsPreviewMode();
+
+	const isActive = isRouteActive && ! ( blockOnPreviewMode && isPreviewMode );
+
+	const isBlocked = (
+		( blockOnPreviewMode && isPreviewMode ) ||
+		( blockOnKitRoutes && isKitRouteActive )
+	);
+
+	return {
+		isActive,
+		isBlocked,
+	};
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './dispatchers';
+export * from './hooks';
+export * from './listeners';
+export * from './readers';

package/src/listeners/__tests__/index.test.ts

@@ -0,0 +1,343 @@
+import {
+	commandEndEvent,
+	commandStartEvent,
+	dispatchReadyEvent,
+	listenTo,
+	routeOpenEvent,
+	routeCloseEvent,
+	windowEvent,
+	v1ReadyEvent,
+	setReady,
+	ExtendedWindow,
+} from '../';
+
+import {
+	dispatchCommandAfter,
+	dispatchCommandBefore,
+	dispatchRouteClose,
+	dispatchRouteOpen,
+	dispatchWindowEvent,
+} from '../../__tests__/utils';
+
+describe( '@elementor/editor-v1-adapters/listeners', () => {
+	beforeEach( () => {
+		jest.useFakeTimers();
+	} );
+
+	afterEach( () => {
+		jest.useRealTimers();
+	} );
+
+	it( 'should listen to command start', () => {
+		// Arrange.
+		const commandToListen = 'editor/documents/open',
+			anotherCommand = 'non/related/command',
+			callback = jest.fn();
+
+		// Act.
+		listenTo(
+			commandStartEvent( commandToListen ),
+			callback
+		);
+
+		// Dispatch the command to test.
+		dispatchCommandBefore( commandToListen );
+		dispatchCommandAfter( commandToListen );
+
+		// Dispatch another command to make sure we don't listen to it.
+		dispatchCommandBefore( anotherCommand );
+		dispatchCommandAfter( anotherCommand );
+
+		// Assert.
+		expect( callback ).toHaveBeenCalledTimes( 1 );
+		expect( callback ).toHaveBeenCalledWith( {
+			type: 'command',
+			command: 'editor/documents/open',
+			originalEvent: expect.any( CustomEvent ),
+		} );
+	} );
+
+	it( 'should listen to command end', () => {
+		// Arrange.
+		const commandToListen = 'editor/documents/open',
+			anotherCommand = 'non/related/command',
+			callback = jest.fn();
+
+		// Act.
+		listenTo(
+			commandEndEvent( commandToListen ),
+			callback
+		);
+
+		// Dispatch the command to test.
+		dispatchCommandBefore( commandToListen );
+		dispatchCommandAfter( commandToListen );
+
+		// Dispatch another command to make sure we don't listen to it.
+		dispatchCommandBefore( anotherCommand );
+		dispatchCommandAfter( anotherCommand );
+
+		// Assert.
+		expect( callback ).toHaveBeenCalledTimes( 1 );
+		expect( callback ).toHaveBeenCalledWith( {
+			type: 'command',
+			command: 'editor/documents/open',
+			originalEvent: expect.any( CustomEvent ),
+		} );
+	} );
+
+	it( 'should listen to route open', () => {
+		// Arrange.
+		const routeToListen = 'panel/menu',
+			anotherRoute = 'non/related/route',
+			callback = jest.fn();
+
+		// Act.
+		listenTo(
+			routeOpenEvent( routeToListen ),
+			callback
+		);
+
+		// Dispatch the route to test.
+		dispatchRouteOpen( routeToListen );
+
+		// Dispatch another route to make sure we don't listen to it.
+		dispatchRouteOpen( anotherRoute );
+
+		// Assert.
+		expect( callback ).toHaveBeenCalledTimes( 1 );
+		expect( callback ).toHaveBeenCalledWith( {
+			type: 'route',
+			route: 'panel/menu',
+			originalEvent: expect.any( CustomEvent ),
+		} );
+	} );
+
+	it( 'should listen to route close', () => {
+		// Arrange.
+		const routeToListen = 'panel/menu',
+			anotherRoute = 'non/related/route',
+			callback = jest.fn();
+
+		// Act.
+		listenTo(
+			routeCloseEvent( routeToListen ),
+			callback
+		);
+
+		// Dispatch the route to test.
+		dispatchRouteClose( routeToListen );
+
+		// Dispatch another route to make sure we don't listen to it.
+		dispatchRouteClose( anotherRoute );
+
+		// Assert.
+		expect( callback ).toHaveBeenCalledTimes( 1 );
+		expect( callback ).toHaveBeenCalledWith( {
+			type: 'route',
+			route: 'panel/menu',
+			originalEvent: expect.any( CustomEvent ),
+		} );
+	} );
+
+	it( 'should listen to window events', () => {
+		// Arrange.
+		const event = 'test-event',
+			callback = jest.fn();
+
+		// Act.
+		listenTo(
+			windowEvent( event ),
+			callback
+		);
+
+		// Dispatch events.
+		dispatchWindowEvent( event );
+
+		// Assert.
+		expect( callback ).toHaveBeenCalledTimes( 1 );
+		expect( callback ).toHaveBeenCalledWith( {
+			type: 'window-event',
+			event: 'test-event',
+			originalEvent: expect.any( Event ),
+		} );
+	} );
+
+	it( 'should listen to the same event with multiple callbacks', () => {
+		// Arrange.
+		const event = 'test-event',
+			callback1 = jest.fn(),
+			callback2 = jest.fn();
+
+		// Act.
+		listenTo(
+			windowEvent( event ),
+			callback1
+		);
+
+		listenTo(
+			windowEvent( event ),
+			callback2
+		);
+
+		// Dispatch events.
+		dispatchWindowEvent( event );
+
+		// Assert.
+		expect( callback1 ).toHaveBeenCalledTimes( 1 );
+		expect( callback2 ).toHaveBeenCalledTimes( 1 );
+	} );
+
+	it( 'should listen to an array of events', () => {
+		// Arrange.
+		const command = 'test-command',
+			route = 'test-route',
+			event = 'test-event',
+			callback = jest.fn();
+
+		// Act.
+		listenTo( [
+			windowEvent( event ),
+			commandStartEvent( command ),
+			routeOpenEvent( route ),
+		], callback );
+
+		// Dispatch events.
+		dispatchCommandBefore( command );
+		dispatchCommandAfter( command );
+
+		dispatchRouteOpen( route );
+		dispatchRouteClose( route );
+
+		dispatchWindowEvent( event );
+
+		// Assert.
+		expect( callback ).toHaveBeenCalledTimes( 3 );
+
+		expect( callback ).toHaveBeenNthCalledWith( 1, {
+			type: 'command',
+			command: 'test-command',
+			originalEvent: expect.any( CustomEvent ),
+		} );
+
+		expect( callback ).toHaveBeenNthCalledWith( 2, {
+			type: 'route',
+			route: 'test-route',
+			originalEvent: expect.any( CustomEvent ),
+		} );
+
+		expect( callback ).toHaveBeenNthCalledWith( 3, {
+			type: 'window-event',
+			event: 'test-event',
+			originalEvent: expect.any( Event ),
+		} );
+	} );
+
+	it( 'should cleanup listeners', () => {
+		// Arrange.
+		const event1 = 'test-event-1',
+			event2 = 'test-event-2',
+			callback1 = jest.fn(),
+			callback2 = jest.fn();
+
+		const cleanup1 = listenTo(
+			[
+				windowEvent( event1 ),
+				windowEvent( event2 ),
+			],
+			callback1,
+		);
+
+		const cleanup2 = listenTo(
+			windowEvent( event1 ),
+			callback2,
+		);
+
+		// Act.
+		cleanup1();
+		cleanup2();
+
+		// Dispatch events.
+		dispatchWindowEvent( event1 );
+		dispatchWindowEvent( event2 );
+
+		// Assert.
+		expect( callback1 ).toHaveBeenCalledTimes( 0 );
+		expect( callback2 ).toHaveBeenCalledTimes( 0 );
+	} );
+
+	it( 'should not fail when calling the same cleanup twice', () => {
+		// Arrange.
+		const event = 'test-event',
+			callback = jest.fn();
+
+		const cleanup = listenTo(
+			windowEvent( event ),
+			callback,
+		);
+
+		// Act.
+		cleanup();
+		cleanup();
+
+		// Dispatch events.
+		dispatchWindowEvent( event );
+
+		// Assert.
+		expect( callback ).toHaveBeenCalledTimes( 0 );
+	} );
+
+	it( 'should trigger v1 ready when v1 is loaded after v2', async () => {
+		// Arrange.
+		const callback = jest.fn();
+		const extendedWindow = ( window as unknown as ExtendedWindow );
+
+		extendedWindow.__elementorEditorV1LoadingPromise = new Promise( ( resolve ) => {
+			setTimeout( resolve, 1000 );
+		} );
+
+		// Act.
+		listenTo(
+			v1ReadyEvent(),
+			callback
+		);
+
+		dispatchReadyEvent();
+
+		await jest.runAllTimers();
+
+		// Assert.
+		expect( callback ).toHaveBeenCalledTimes( 1 );
+	} );
+
+	it( 'should not trigger callback when the application is not ready', () => {
+		// Arrange
+		setReady( false );
+
+		const event = 'test-event';
+		const callback = jest.fn();
+
+		// Act.
+		listenTo(
+			windowEvent( event ),
+			callback
+		);
+
+		// Dispatch events.
+		dispatchWindowEvent( event );
+
+		// Assert.
+		expect( callback ).not.toHaveBeenCalled();
+	} );
+
+	it( 'should throw when v1 is not loaded', async () => {
+		// Act & Assert.
+		try {
+			await dispatchReadyEvent();
+		} catch ( e ) {
+			expect( e ).toBe( 'Elementor Editor V1 is not loaded' );
+		}
+
+		expect.assertions( 1 );
+	} );
+} );

package/src/listeners/event-creators.ts

@@ -0,0 +1,48 @@
+import { CommandEventDescriptor, RouteEventDescriptor, WindowEventDescriptor } from './types';
+
+export const commandStartEvent = ( command: CommandEventDescriptor['name'] ): CommandEventDescriptor => {
+	return {
+		type: 'command',
+		name: command,
+		state: 'before',
+	};
+};
+
+export const commandEndEvent = ( command: CommandEventDescriptor['name'] ): CommandEventDescriptor => {
+	return {
+		type: 'command',
+		name: command,
+		state: 'after',
+	};
+};
+
+export const routeOpenEvent = ( route: RouteEventDescriptor['name'] ): RouteEventDescriptor => {
+	return {
+		type: 'route',
+		name: route,
+		state: 'open',
+	};
+};
+
+export const routeCloseEvent = ( route: RouteEventDescriptor['name'] ): RouteEventDescriptor => {
+	return {
+		type: 'route',
+		name: route,
+		state: 'close',
+	};
+};
+
+export const windowEvent = ( event: WindowEventDescriptor['name'] ): WindowEventDescriptor => {
+	return {
+		type: 'window-event',
+		name: event,
+	};
+};
+
+export const v1ReadyEvent = () => {
+	return windowEvent( 'elementor/initialized' );
+};
+
+export const editModeChangeEvent = () => {
+	return windowEvent( 'elementor/edit-mode/change' );
+};

package/src/listeners/index.ts

@@ -0,0 +1,5 @@
+export * from './event-creators';
+export * from './listeners';
+export * from './types';
+export * from './is-ready';
+export { dispatchReadyEvent } from './utils';