@elementor/editor-app-bar 0.1.0

package/src/locations/__tests__/menus.test.tsx

@@ -0,0 +1,229 @@
+import * as React from 'react';
+import { createMenu } from '../menus';
+import { act, fireEvent, render } from '@testing-library/react';
+import { createMockMenuAction, createMockMenuLink, createMockMenuToggleAction } from 'test-utils';
+
+describe( '@elementor/editor-app-bar - Menus API', () => {
+	it( 'should create a menu with default group when not provided', () => {
+		// Act.
+		const menu = createMenu( {
+			name: 'test',
+		} );
+
+		menu.registerAction( createMockMenuAction() );
+
+		const { getByRole } = renderMenu( menu );
+
+		// Assert.
+		expect( getByRole( 'button' ) ).toBeInTheDocument();
+	} );
+
+	it( 'should create a menu with groups and append a default group', () => {
+		// Act.
+		const menu = createMenu( {
+			name: 'test',
+			groups: [ 'testGroup' ],
+		} );
+
+		menu.registerAction( createMockMenuAction() );
+
+		menu.registerLink( {
+			...createMockMenuLink(),
+			group: 'testGroup',
+		} );
+
+		const { getByRole } = renderMenu( menu );
+
+		// Assert.
+		expect( getByRole( 'button' ) ).toBeInTheDocument();
+		expect( getByRole( 'link' ) ).toBeInTheDocument();
+	} );
+
+	it( 'should register an action', () => {
+		// Arrange.
+		const onClick = jest.fn();
+
+		// Act.
+		const menu = createMenu( {
+			name: 'test',
+		} );
+
+		menu.registerAction( createMockMenuAction( { onClick } ) );
+
+		const { getByRole } = renderMenu( menu );
+
+		// Assert.
+		const action = getByRole( 'button' );
+
+		expect( action ).toBeInTheDocument();
+		expect( action ).toHaveAttribute( 'aria-label', 'Test' );
+
+		// Act.
+		action.click();
+
+		// Assert.
+		expect( onClick ).toHaveBeenCalled();
+	} );
+
+	it( 'should register a toggle action', () => {
+		// Act.
+		const menu = createMenu( {
+			name: 'test',
+		} );
+
+		menu.registerToggleAction( createMockMenuToggleAction() );
+
+		const { getByRole } = renderMenu( menu );
+
+		// Assert.
+		const toggleAction = getByRole( 'button' );
+
+		expect( toggleAction ).toHaveAttribute( 'aria-pressed', 'false' );
+		expect( toggleAction ).toHaveAttribute( 'value', 'test-value' );
+
+		// Act.
+		toggleAction.click();
+
+		// Assert.
+		expect( toggleAction ).toHaveAttribute( 'aria-pressed', 'true' );
+
+		// Act.
+		toggleAction.click();
+
+		// Assert.
+		expect( toggleAction ).toHaveAttribute( 'aria-pressed', 'false' );
+		expect( toggleAction ).toHaveAttribute( 'disabled' );
+	} );
+
+	it( 'should register a link', () => {
+		// Act.
+		const menu = createMenu( {
+			name: 'test',
+		} );
+
+		menu.registerLink( createMockMenuLink() );
+
+		const { getByRole } = renderMenu( menu );
+
+		// Assert.
+		const link = getByRole( 'link' );
+
+		expect( link ).toBeInTheDocument();
+		expect( link ).toHaveAttribute( 'href', 'https://elementor.com' );
+		expect( link ).toHaveAttribute( 'target', '_blank' );
+		expect( link ).toHaveAttribute( 'aria-label', 'Test' );
+	} );
+
+	it( 'should not register an action when passing a non-existing group', () => {
+		// Act.
+		const menu = createMenu( {
+			name: 'test',
+		} );
+
+		menu.registerLink( {
+			...createMockMenuLink(),
+			group: 'non-existing-group' as 'default', // Emulate a runtime error.
+		} );
+
+		const { queryByRole } = renderMenu( menu );
+
+		// Assert.
+		expect( queryByRole( 'link' ) ).not.toBeInTheDocument();
+	} );
+
+	it( 'should register an action tooltip', async () => {
+		// Arrange.
+		const menu = createMenu( {
+			name: 'test',
+		} );
+
+		// Act.
+		menu.registerAction( createMockMenuAction() );
+
+		// Assert.
+		const { getByLabelText, queryByRole, findByRole } = renderMenu( menu );
+
+		const button = getByLabelText( 'Test' );
+
+		expect( queryByRole( 'tooltip' ) ).not.toBeInTheDocument();
+
+		// Act.
+		act( () => {
+			fireEvent(
+				button,
+				new MouseEvent( 'mouseover', { bubbles: true } ),
+			);
+		} );
+
+		// Assert.
+		expect( await findByRole( 'tooltip' ) ).toHaveTextContent( 'Test' );
+	} );
+
+	it( 'should register an action icon', () => {
+		// Arrange.
+		const menu = createMenu( {
+			name: 'test',
+		} );
+
+		// Act.
+		menu.registerAction( createMockMenuAction() );
+
+		// Assert.
+		const { queryByText } = renderMenu( menu );
+
+		const icon = queryByText( 'a' );
+
+		expect( icon ).toBeInTheDocument();
+		expect( icon ).toHaveTextContent( 'a' );
+	} );
+
+	it.each( [
+		{
+			type: 'action',
+			action: 'registerAction',
+		},
+		{
+			type: 'toggle action',
+			action: 'registerToggleAction',
+		},
+		{
+			type: 'link',
+			action: 'registerLink',
+		},
+	] as const )( 'should register a hidden $type', ( { type, action } ) => {
+		// Arrange.
+		const menu = createMenu( {
+			name: 'test',
+		} );
+
+		// Act.
+		menu[ action ]( {
+			name: 'hidden',
+			useProps: () => ( {
+				title: `hidden-${ type }`,
+				icon: () => <div />,
+				visible: false,
+			} ),
+		} );
+
+		// Assert.
+		const { queryByLabelText } = renderMenu( menu );
+
+		expect( queryByLabelText( `hidden-${ type }` ) ).not.toBeInTheDocument();
+	} );
+} );
+
+function renderMenu<TGroup extends string>( menu: ReturnType<typeof createMenu<TGroup>> ) {
+	const MenuComponent = () => {
+		const groupedItems = menu.useMenuItems();
+		const allItems = Object.values( groupedItems ).flat();
+
+		return (
+			<div>
+				{ allItems.map( ( { MenuItem, id } ) => <MenuItem key={ id } /> ) }
+			</div>
+		);
+	};
+
+	return render( <MenuComponent /> );
+}

package/src/locations/consts.ts

@@ -0,0 +1,4 @@
+// Locations
+export const LOCATION_PAGE_INDICATION = 'editor/app-bar/page-indication' as const;
+export const LOCATION_RESPONSIVE = 'editor/app-bar/responsive' as const;
+export const LOCATION_PRIMARY_ACTION = 'editor/app-bar/primary-action' as const;

package/src/locations/index.ts

@@ -0,0 +1,29 @@
+import { createMenu } from './menus';
+import { createInjectorFor } from '@elementor/locations';
+import { LOCATION_PAGE_INDICATION, LOCATION_PRIMARY_ACTION, LOCATION_RESPONSIVE } from './consts';
+
+export * from './consts';
+
+export { createMenu } from './menus';
+
+export const injectIntoPageIndication = createInjectorFor( LOCATION_PAGE_INDICATION );
+export const injectIntoResponsive = createInjectorFor( LOCATION_RESPONSIVE );
+export const injectIntoPrimaryAction = createInjectorFor( LOCATION_PRIMARY_ACTION );
+
+export const mainMenu = createMenu( {
+	name: 'main',
+	groups: [ 'exits' ],
+} );
+
+export const toolsMenu = createMenu( {
+	name: 'tools',
+} );
+
+export const utilitiesMenu = createMenu( {
+	name: 'utilities',
+} );
+
+export const documentOptionsMenu = createMenu( {
+	name: 'document-options',
+	groups: [ 'save' ],
+} );

package/src/locations/menus.tsx

@@ -0,0 +1,141 @@
+import * as React from 'react';
+import { ComponentPropsWithoutRef, ElementType, useMemo } from 'react';
+import { inject, useInjectionsOf } from '@elementor/locations';
+import Action from '../components/actions/action';
+import ToggleAction from '../components/actions/toggle-action';
+import Link from '../components/actions/link';
+
+type MenuName = string;
+type GroupName = string;
+
+type Menu<TGroup extends GroupName = 'default'> = {
+	name: MenuName,
+	groups: TGroup[],
+};
+
+type MenuWithOptionalGroups<TGroup extends GroupName> = Omit<Menu<TGroup>, 'groups'> & { groups?: TGroup[] };
+
+type MenuGroup<TGroup extends GroupName> = TGroup | 'default';
+
+type GroupedItems<TGroup extends GroupName> = Record<MenuGroup<TGroup>, Array<{ id: string, MenuItem: ElementType }>>;
+
+type MenuItem<
+	TGroup extends GroupName,
+	TComponent extends ElementType,
+> = {
+	name: string,
+	group?: TGroup,
+	priority?: number,
+	overwrite?: boolean,
+} & (
+	{ props: ComponentPropsWithoutRef<TComponent>, useProps?: never } |
+	{ useProps: () => ComponentPropsWithoutRef<TComponent>, props?: never }
+)
+
+export function createMenu<TGroup extends GroupName = 'default'>( { name: menuName, groups = [] }: MenuWithOptionalGroups<TGroup> ) {
+	const menuGroups: MenuGroup<TGroup>[] = [
+		...groups,
+		'default' as const,
+	];
+
+	const registerAction = createRegisterMenuItem( {
+		menuName,
+		menuGroups,
+		component: Action,
+	} );
+
+	const registerToggleAction = createRegisterMenuItem( {
+		menuName,
+		menuGroups,
+		component: ToggleAction,
+	} );
+
+	const registerLink = createRegisterMenuItem( {
+		menuName,
+		menuGroups,
+		component: Link,
+	} );
+
+	const useMenuItems = createUseMenuItems( {
+		menuName,
+		menuGroups,
+	} );
+
+	return {
+		registerAction,
+		registerToggleAction,
+		registerLink,
+		useMenuItems,
+	};
+}
+
+function createRegisterMenuItem<
+	TMenuName extends MenuName,
+	TGroup extends GroupName,
+	TComponent extends ElementType,
+>( { menuName, menuGroups, component }: {
+	menuName: TMenuName,
+	menuGroups: MenuGroup<TGroup>[],
+	component: TComponent,
+} ) {
+	return ( { group = 'default', name, overwrite, priority, ...args }: MenuItem<MenuGroup<TGroup>, TComponent> ) => {
+		if ( ! menuGroups.includes( group ) ) {
+			return;
+		}
+
+		const useProps = 'props' in args ? () => args.props : args.useProps;
+
+		const Component = component as ElementType;
+
+		const Filler = ( props: object ) => {
+			const componentProps = useProps();
+
+			return <Component { ...props } { ...componentProps } />;
+		};
+
+		const location = getMenuLocationId( menuName, group );
+
+		inject( {
+			location,
+			name,
+			filler: Filler,
+			options: {
+				priority,
+				overwrite,
+			},
+		} );
+	};
+}
+
+function createUseMenuItems<
+	TMenuName extends MenuName,
+	TGroup extends GroupName,
+>( { menuName, menuGroups }: {
+	menuName: TMenuName,
+	menuGroups: MenuGroup<TGroup>[],
+} ) {
+	const locations = menuGroups.map( ( group ) => getMenuLocationId( menuName, group ) );
+
+	return () => {
+		const injectionsGroups = useInjectionsOf( locations );
+
+		// Normalize the injections groups to an object with the groups as keys.
+		return useMemo( () => {
+			return injectionsGroups.reduce<GroupedItems<TGroup>>( ( acc, injections, index ) => {
+				const groupName = menuGroups[ index ];
+
+				return {
+					...acc,
+					[ groupName ]: injections.map( ( injection ) => ( {
+						id: injection.id,
+						MenuItem: injection.filler,
+					} ) ),
+				};
+			}, {} as GroupedItems<TGroup> );
+		}, [ injectionsGroups ] );
+	};
+}
+
+function getMenuLocationId( menu: MenuName, group: GroupName ) {
+	return `editor/app-bar/${ menu }/${ group }` as const;
+}

package/src/sync/__tests__/redirect-old-menus.test.ts

@@ -0,0 +1,34 @@
+import { openRoute } from '@elementor/editor-v1-adapters';
+import redirectOldMenus from '../redirect-old-menus';
+
+jest.mock( '@elementor/editor-v1-adapters', () => ( {
+	...jest.requireActual( '@elementor/editor-v1-adapters' ),
+	openRoute: jest.fn(),
+} ) );
+
+describe( '@elementor/editor-app-bar - Redirect old menus', () => {
+	it( 'should redirect old hamburger menu to the default elements panel', () => {
+		// Arrange.
+		redirectOldMenus();
+
+		// Act.
+		window.dispatchEvent( new CustomEvent( 'elementor/routes/open', {
+			detail: {
+				route: 'panel/menu',
+			},
+		} ) );
+
+		// Assert.
+		expect( openRoute ).toHaveBeenCalledWith( 'panel/elements/categories' );
+
+		// Act - Change to non-related route.
+		window.dispatchEvent( new CustomEvent( 'elementor/routes/open', {
+			detail: {
+				route: 'some/other/route',
+			},
+		} ) );
+
+		// Assert - Should not be called again.
+		expect( openRoute ).toHaveBeenCalledTimes( 1 );
+	} );
+} );

package/src/sync/redirect-old-menus.ts

@@ -0,0 +1,9 @@
+import { listenTo, openRoute, routeOpenEvent } from '@elementor/editor-v1-adapters';
+
+export default function redirectOldMenus() {
+	// Currently, in V1, when you click `esc` it opens the hamburger menu in the panel.
+	// In V2, we don't have this panel, so we redirect the user to the elements panel instead.
+	listenTo( routeOpenEvent( 'panel/menu' ), () => {
+		openRoute( 'panel/elements/categories' );
+	} );
+}

package/src/types.ts

@@ -0,0 +1,3 @@
+export type { Props as ActionProps } from './components/actions/action';
+export type { Props as ToggleActionProps } from './components/actions/toggle-action';
+export type { Props as LinkProps } from './components/actions/link';