@wordpress/widget-dashboard 0.1.0

package/src/test/actions.test.tsx

@@ -0,0 +1,228 @@
+/**
+ * External dependencies
+ */
+import '@testing-library/jest-dom';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+import type { WidgetType } from '@wordpress/widget-primitives';
+
+/**
+ * Internal dependencies
+ */
+import { WidgetDashboard } from '../widget-dashboard';
+import type { DashboardWidget, WidgetGridSettings } from '../types';
+
+const widgetTypes: WidgetType[] = [];
+
+// Use a non-empty layout so the provider's auto-edit-when-empty effect
+// does not flip editMode on as a side effect of mounting.
+const layout: DashboardWidget[] = [
+	{ uuid: 'a', type: 'core/test', placement: { width: 1, height: 1 } },
+];
+
+const gridSettings: WidgetGridSettings = {
+	model: 'grid',
+	minColumnWidth: 350,
+	rowHeight: 200,
+};
+
+interface HarnessProps {
+	initialEditMode?: boolean;
+	onEditChange?: ( next: boolean ) => void;
+	onLayoutChange?: ( next: DashboardWidget[] ) => void;
+	onGridSettingsChange?: ( next: WidgetGridSettings ) => void;
+}
+
+function Harness( {
+	initialEditMode = false,
+	onEditChange,
+	onLayoutChange = () => {},
+	onGridSettingsChange,
+}: HarnessProps ) {
+	const [ editMode, setEditMode ] = useState( initialEditMode );
+
+	return (
+		<WidgetDashboard
+			layout={ layout }
+			onLayoutChange={ onLayoutChange }
+			gridSettings={ gridSettings }
+			onGridSettingsChange={ onGridSettingsChange }
+			widgetTypes={ widgetTypes }
+			editMode={ editMode }
+			onEditChange={ ( next ) => {
+				setEditMode( next );
+				onEditChange?.( next );
+			} }
+		>
+			<WidgetDashboard.Actions />
+		</WidgetDashboard>
+	);
+}
+
+describe( 'WidgetDashboard.Actions', () => {
+	let user: ReturnType< typeof userEvent.setup >;
+
+	beforeEach( () => {
+		user = userEvent.setup();
+	} );
+
+	it( 'renders the Customize button when editMode is false', () => {
+		render( <Harness /> );
+
+		expect(
+			screen.getByRole( 'button', { name: 'Customize' } )
+		).toBeInTheDocument();
+		expect(
+			screen.queryByRole( 'button', { name: 'Done' } )
+		).not.toBeInTheDocument();
+	} );
+
+	it( 'renders the Done button when editMode is true', () => {
+		render( <Harness initialEditMode /> );
+
+		expect(
+			screen.getByRole( 'button', { name: 'Done' } )
+		).toBeInTheDocument();
+		expect(
+			screen.queryByRole( 'button', { name: 'Customize' } )
+		).not.toBeInTheDocument();
+	} );
+
+	it( 'fires onEditChange with true when Customize is clicked', async () => {
+		const onEditChange = jest.fn();
+		render( <Harness onEditChange={ onEditChange } /> );
+
+		await user.click( screen.getByRole( 'button', { name: 'Customize' } ) );
+
+		expect( onEditChange ).toHaveBeenLastCalledWith( true );
+	} );
+
+	it( 'disables Done when there are no staging changes', () => {
+		render( <Harness initialEditMode /> );
+
+		expect(
+			screen.getByRole( 'button', { name: 'Done' } )
+		).toHaveAttribute( 'aria-disabled', 'true' );
+	} );
+
+	it( 'fires onEditChange with false when Cancel is clicked', async () => {
+		const onEditChange = jest.fn();
+		const onLayoutChange = jest.fn();
+		render(
+			<Harness
+				initialEditMode
+				onEditChange={ onEditChange }
+				onLayoutChange={ onLayoutChange }
+			/>
+		);
+
+		await user.click( screen.getByRole( 'button', { name: 'Cancel' } ) );
+
+		expect( onEditChange ).toHaveBeenLastCalledWith( false );
+		expect( onLayoutChange ).not.toHaveBeenCalled();
+	} );
+
+	it( 'renders nothing when onEditChange is not provided', () => {
+		render(
+			<WidgetDashboard
+				layout={ layout }
+				onLayoutChange={ () => {} }
+				widgetTypes={ widgetTypes }
+			>
+				<WidgetDashboard.Actions />
+			</WidgetDashboard>
+		);
+
+		expect(
+			screen.queryByRole( 'button', { name: 'Customize' } )
+		).not.toBeInTheDocument();
+		expect(
+			screen.queryByRole( 'button', { name: 'Done' } )
+		).not.toBeInTheDocument();
+	} );
+
+	describe( 'Layout settings', () => {
+		it( 'is hidden when editMode is false', () => {
+			render( <Harness onGridSettingsChange={ () => {} } /> );
+
+			expect(
+				screen.queryByRole( 'button', { name: 'Layout settings' } )
+			).not.toBeInTheDocument();
+		} );
+
+		it( 'is visible in the edit toolbar when grid settings are editable', () => {
+			render(
+				<Harness initialEditMode onGridSettingsChange={ () => {} } />
+			);
+
+			expect(
+				screen.getByRole( 'button', { name: 'Layout settings' } )
+			).toBeInTheDocument();
+		} );
+
+		it( 'is hidden when onGridSettingsChange is not provided', () => {
+			render( <Harness initialEditMode /> );
+
+			expect(
+				screen.queryByRole( 'button', { name: 'Layout settings' } )
+			).not.toBeInTheDocument();
+		} );
+
+		it( 'opens the layout settings drawer when clicked', async () => {
+			render(
+				<Harness initialEditMode onGridSettingsChange={ () => {} } />
+			);
+
+			await user.click(
+				screen.getByRole( 'button', { name: 'Layout settings' } )
+			);
+
+			expect(
+				await screen.findByRole( 'dialog', { name: 'Layout settings' } )
+			).toBeInTheDocument();
+		} );
+
+		it( 'is not in the more-actions menu', async () => {
+			const onLayoutReset = jest.fn();
+			render(
+				<WidgetDashboard
+					layout={ layout }
+					onLayoutChange={ () => {} }
+					onLayoutReset={ onLayoutReset }
+					gridSettings={ gridSettings }
+					onGridSettingsChange={ () => {} }
+					widgetTypes={ widgetTypes }
+					editMode
+					onEditChange={ () => {} }
+				>
+					<WidgetDashboard.Actions />
+				</WidgetDashboard>
+			);
+
+			await user.click(
+				screen.getByRole( 'button', { name: 'More options' } )
+			);
+
+			expect(
+				screen.queryByRole( 'menuitem', { name: 'Layout settings' } )
+			).not.toBeInTheDocument();
+		} );
+	} );
+
+	it( 'throws when used outside a WidgetDashboard subtree', () => {
+		const spy = jest
+			.spyOn( console, 'error' )
+			.mockImplementation( () => {} );
+
+		expect( () => render( <WidgetDashboard.Actions /> ) ).toThrow(
+			/Dashboard compound used outside a WidgetDashboard subtree/
+		);
+
+		spy.mockRestore();
+	} );
+} );

package/src/test/commands.test.tsx

@@ -0,0 +1,176 @@
+/**
+ * External dependencies
+ */
+import '@testing-library/jest-dom';
+import { render, screen } from '@testing-library/react';
+
+/**
+ * WordPress dependencies
+ */
+import { useMemo, useState } from '@wordpress/element';
+import { useSelect } from '@wordpress/data';
+import { store as commandsStore } from '@wordpress/commands';
+import type { WidgetType } from '@wordpress/widget-primitives';
+
+/**
+ * Internal dependencies
+ */
+import { WidgetDashboard } from '../widget-dashboard';
+import { DASHBOARD_COMMAND_CONTEXT } from '../components/commands';
+import type { DashboardWidget } from '../types';
+
+const widgetTypes: WidgetType[] = [];
+
+const layout: DashboardWidget[] = [
+	{ uuid: 'a', type: 'core/test', placement: { width: 1, height: 1 } },
+];
+
+function CommandsProbe( { names }: { names: string[] } ) {
+	const context = useSelect(
+		( select ) => select( commandsStore ).getContext(),
+		[]
+	);
+	const contextualCommands = useSelect(
+		( select ) => select( commandsStore ).getCommands( true ),
+		[]
+	);
+
+	const registered = useMemo(
+		() =>
+			Object.fromEntries(
+				names.map( ( name ) => [
+					name,
+					contextualCommands.some(
+						( command ) => command.name === name
+					),
+				] )
+			),
+		[ names, contextualCommands ]
+	);
+
+	return (
+		<div
+			data-testid="commands-probe"
+			data-context={ context }
+			data-registered={ JSON.stringify( registered ) }
+		/>
+	);
+}
+
+const COMMAND_NAMES = [
+	'core/dashboard/customize',
+	'core/dashboard/add-widgets',
+	'core/dashboard/switch-to-masonry-layout',
+	'core/dashboard/switch-to-grid-layout',
+	'core/dashboard/reset-to-default',
+];
+
+interface HarnessProps {
+	initialEditMode?: boolean;
+	withGridSettings?: boolean;
+	withLayoutReset?: boolean;
+	gridModel?: 'grid' | 'masonry';
+}
+
+function Harness( {
+	initialEditMode = false,
+	withGridSettings = false,
+	withLayoutReset = false,
+	gridModel = 'grid',
+}: HarnessProps ) {
+	const [ editMode, setEditMode ] = useState( initialEditMode );
+
+	return (
+		<WidgetDashboard
+			layout={ layout }
+			onLayoutChange={ () => {} }
+			widgetTypes={ widgetTypes }
+			editMode={ editMode }
+			onEditChange={ setEditMode }
+			onLayoutReset={ withLayoutReset ? async () => {} : undefined }
+			gridSettings={
+				withGridSettings ? { model: gridModel, columns: 6 } : undefined
+			}
+			onGridSettingsChange={ withGridSettings ? () => {} : undefined }
+		>
+			<WidgetDashboard.Commands />
+			<CommandsProbe names={ COMMAND_NAMES } />
+		</WidgetDashboard>
+	);
+}
+
+function getRegistered( probe: HTMLElement ): Record< string, boolean > {
+	return JSON.parse( probe.getAttribute( 'data-registered' ) ?? '{}' );
+}
+
+describe( 'WidgetDashboard.Commands', () => {
+	it( 'sets the dashboard command context and registers core commands', () => {
+		render( <Harness withGridSettings withLayoutReset /> );
+		const probe = screen.getByTestId( 'commands-probe' );
+		const registered = getRegistered( probe );
+
+		expect( probe ).toHaveAttribute(
+			'data-context',
+			DASHBOARD_COMMAND_CONTEXT
+		);
+		expect( registered[ 'core/dashboard/customize' ] ).toBe( true );
+		expect( registered[ 'core/dashboard/add-widgets' ] ).toBe( true );
+		expect( registered[ 'core/dashboard/reset-to-default' ] ).toBe( true );
+	} );
+
+	it( 'unregisters Customize while edit mode is active', () => {
+		render( <Harness initialEditMode withGridSettings withLayoutReset /> );
+		const registered = getRegistered(
+			screen.getByTestId( 'commands-probe' )
+		);
+
+		expect( registered[ 'core/dashboard/customize' ] ).toBe( false );
+		expect( registered[ 'core/dashboard/add-widgets' ] ).toBe( true );
+	} );
+
+	it( 'disables layout commands while edit mode is active', () => {
+		render(
+			<Harness
+				initialEditMode
+				withGridSettings
+				withLayoutReset
+				gridModel="grid"
+			/>
+		);
+		const registered = getRegistered(
+			screen.getByTestId( 'commands-probe' )
+		);
+
+		expect( registered[ 'core/dashboard/switch-to-masonry-layout' ] ).toBe(
+			false
+		);
+		expect( registered[ 'core/dashboard/switch-to-grid-layout' ] ).toBe(
+			false
+		);
+	} );
+
+	it( 'only registers the active layout-model switch command', () => {
+		render( <Harness withGridSettings withLayoutReset gridModel="grid" /> );
+		const registered = getRegistered(
+			screen.getByTestId( 'commands-probe' )
+		);
+
+		expect( registered[ 'core/dashboard/switch-to-masonry-layout' ] ).toBe(
+			true
+		);
+		expect( registered[ 'core/dashboard/switch-to-grid-layout' ] ).toBe(
+			false
+		);
+	} );
+
+	it( 'omits grid-settings commands when grid settings are not editable', () => {
+		render( <Harness withLayoutReset /> );
+		const registered = getRegistered(
+			screen.getByTestId( 'commands-probe' )
+		);
+
+		expect( registered[ 'core/dashboard/switch-to-masonry-layout' ] ).toBe(
+			false
+		);
+	} );
+} );

package/src/test/create-dashboard-widget.test.ts

@@ -0,0 +1,59 @@
+/**
+ * WordPress dependencies
+ */
+import type { WidgetType } from '@wordpress/widget-primitives';
+
+/**
+ * Internal dependencies
+ */
+import { createDashboardWidget } from '../utils/create-dashboard-widget';
+
+const baseType: WidgetType = {
+	apiVersion: 1,
+	name: 'core/example',
+	title: 'Example',
+	renderModule: 'https://example.test/widget.js',
+};
+
+describe( 'createDashboardWidget', () => {
+	it( 'stamps the type name and a unique uuid', () => {
+		const a = createDashboardWidget( baseType );
+		const b = createDashboardWidget( baseType );
+
+		expect( a.type ).toBe( 'core/example' );
+		expect( b.type ).toBe( 'core/example' );
+		expect( a.uuid ).not.toBe( b.uuid );
+		expect( a.uuid ).toMatch( /^[0-9a-f-]{36}$/ );
+	} );
+
+	it( 'applies default placement values', () => {
+		const instance = createDashboardWidget( baseType );
+		expect( instance.placement ).toEqual( {
+			width: 1,
+			height: 2,
+			order: 0,
+		} );
+	} );
+
+	it( 'uses initialAttributes when provided', () => {
+		const instance = createDashboardWidget< { greeting: string } >(
+			baseType,
+			{ greeting: 'hi' }
+		);
+		expect( instance.attributes ).toEqual( { greeting: 'hi' } );
+	} );
+
+	it( 'falls back to the type example attributes when no attributes are supplied', () => {
+		const typeWithExample: WidgetType = {
+			...baseType,
+			example: { attributes: { greeting: 'default' } },
+		};
+		const instance = createDashboardWidget( typeWithExample );
+		expect( instance.attributes ).toEqual( { greeting: 'default' } );
+	} );
+
+	it( 'leaves attributes undefined when no example and no initial provided', () => {
+		const instance = createDashboardWidget( baseType );
+		expect( instance.attributes ).toBeUndefined();
+	} );
+} );

package/src/test/dashboard-context.test.tsx

@@ -0,0 +1,26 @@
+/**
+ * External dependencies
+ */
+import { render } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import { useWidgetContext } from '../context/widget-context';
+
+function CaptureWidgetContext( {
+	onRender,
+}: {
+	onRender: ( value: ReturnType< typeof useWidgetContext > ) => void;
+} ) {
+	onRender( useWidgetContext() );
+	return null;
+}
+
+describe( 'useWidgetContext', () => {
+	it( 'returns null outside a widget render subtree', () => {
+		const handler = jest.fn();
+		render( <CaptureWidgetContext onRender={ handler } /> );
+		expect( handler ).toHaveBeenCalledWith( null );
+	} );
+} );