@wordpress/widget-dashboard 0.1.1 → 0.3.1-next.v.202607070741.0

package/src/test/commands.test.tsx

@@ -60,23 +60,20 @@ function CommandsProbe( { names }: { names: string[] } ) {
 const COMMAND_NAMES = [
 	'core/dashboard/customize',
 	'core/dashboard/add-widgets',
+	'core/dashboard/reset-to-default',
+	// Removed commands, probed to assert they stay unregistered.
 	'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 );
 
@@ -88,10 +85,6 @@ function Harness( {
 			editMode={ editMode }
 			onEditChange={ setEditMode }
 			onLayoutReset={ withLayoutReset ? async () => {} : undefined }
-			gridSettings={
-				withGridSettings ? { model: gridModel, columns: 6 } : undefined
-			}
-			onGridSettingsChange={ withGridSettings ? () => {} : undefined }
 		>
 			<WidgetDashboard.Commands />
 			<CommandsProbe names={ COMMAND_NAMES } />
@@ -105,7 +98,7 @@ function getRegistered( probe: HTMLElement ): Record< string, boolean > {
 
 describe( 'WidgetDashboard.Commands', () => {
 	it( 'sets the dashboard command context and registers core commands', () => {
-		render( <Harness withGridSettings withLayoutReset /> );
+		render( <Harness withLayoutReset /> );
 		const probe = screen.getByTestId( 'commands-probe' );
 		const registered = getRegistered( probe );
 
@@ -119,7 +112,7 @@ describe( 'WidgetDashboard.Commands', () => {
 	} );
 
 	it( 'unregisters Customize while edit mode is active', () => {
-		render( <Harness initialEditMode withGridSettings withLayoutReset /> );
+		render( <Harness initialEditMode withLayoutReset /> );
 		const registered = getRegistered(
 			screen.getByTestId( 'commands-probe' )
 		);
@@ -128,15 +121,8 @@ describe( 'WidgetDashboard.Commands', () => {
 		expect( registered[ 'core/dashboard/add-widgets' ] ).toBe( true );
 	} );
 
-	it( 'disables layout commands while edit mode is active', () => {
-		render(
-			<Harness
-				initialEditMode
-				withGridSettings
-				withLayoutReset
-				gridModel="grid"
-			/>
-		);
+	it( 'does not register layout-model switch commands', () => {
+		render( <Harness withLayoutReset /> );
 		const registered = getRegistered(
 			screen.getByTestId( 'commands-probe' )
 		);
@@ -148,29 +134,4 @@ describe( 'WidgetDashboard.Commands', () => {
 			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/staging.test.tsx

@@ -15,7 +15,7 @@ import type { WidgetType } from '@wordpress/widget-primitives';
  */
 import { useDashboardInternalContext } from '../context/dashboard-context';
 import { WidgetDashboard } from '../widget-dashboard';
-import type { DashboardWidget, WidgetGridSettings } from '../types';
+import type { DashboardWidget } from '../types';
 
 const widgetTypes: WidgetType[] = [];
 
@@ -26,16 +26,13 @@ const initialLayout: DashboardWidget[] = [
 
 interface ProbeApi {
 	layout: DashboardWidget[];
-	gridSettings: WidgetGridSettings;
 	hasUncommittedChanges: boolean;
 	editMode: boolean;
 	mutate: ( next: DashboardWidget[] ) => void;
-	mutateGridSettings: ( next: WidgetGridSettings ) => void;
 	commit: ( options?: { exitEditMode?: boolean } ) => void;
-	cancel: ( options?: {
-		exitEditMode?: boolean;
-		revertLayout?: boolean;
-	} ) => void;
+	cancel: () => void;
+	scheduleAutoSave: () => void;
+	flushAutoSave: () => void;
 }
 
 const probeRef: { current: ProbeApi | null } = { current: null };
@@ -45,13 +42,13 @@ function Probe() {
 	useEffect( () => {
 		probeRef.current = {
 			layout: ctx.layout,
-			gridSettings: ctx.gridSettings,
 			hasUncommittedChanges: ctx.hasUncommittedChanges,
 			editMode: ctx.editMode,
 			mutate: ctx.onLayoutChange,
-			mutateGridSettings: ctx.onGridSettingsChange,
 			commit: ctx.commit,
 			cancel: ctx.cancel,
+			scheduleAutoSave: ctx.scheduleAutoSave,
+			flushAutoSave: ctx.flushAutoSave,
 		};
 	} );
 	return null;
@@ -67,24 +64,20 @@ function readProbe(): ProbeApi {
 interface HarnessProps {
 	layout: DashboardWidget[];
 	onLayoutChange: ( next: DashboardWidget[] ) => void;
-	gridSettings?: WidgetGridSettings;
-	onGridSettingsChange?: ( next: WidgetGridSettings ) => void;
+	initialEditMode?: boolean;
 }
 
 function Harness( {
 	layout,
 	onLayoutChange,
-	gridSettings,
-	onGridSettingsChange,
+	initialEditMode = true,
 }: HarnessProps ) {
-	const [ editMode, setEditMode ] = useState( true );
+	const [ editMode, setEditMode ] = useState( initialEditMode );
 
 	return (
 		<WidgetDashboard
 			layout={ layout }
 			onLayoutChange={ onLayoutChange }
-			gridSettings={ gridSettings }
-			onGridSettingsChange={ onGridSettingsChange }
 			widgetTypes={ widgetTypes }
 			editMode={ editMode }
 			onEditChange={ setEditMode }
@@ -286,191 +279,136 @@ describe( 'WidgetDashboard staging layer', () => {
 		expect( readProbe().editMode ).toBe( true );
 	} );
 
-	describe( 'grid settings staging', () => {
-		const initialSettings: WidgetGridSettings = {
-			model: 'grid',
-			rowHeight: 200,
-		};
+	it( 'stays in edit mode when commit passes exitEditMode: false', () => {
+		const onLayoutChange = jest.fn();
+		render(
+			<Harness
+				layout={ initialLayout }
+				onLayoutChange={ onLayoutChange }
+			/>
+		);
 
-		it( 'keeps settings mutations in staging without firing onGridSettingsChange', () => {
-			const onLayoutChange = jest.fn();
-			const onGridSettingsChange = jest.fn();
-			render(
-				<Harness
-					layout={ initialLayout }
-					onLayoutChange={ onLayoutChange }
-					gridSettings={ initialSettings }
-					onGridSettingsChange={ onGridSettingsChange }
-				/>
-			);
+		act( () => {
+			readProbe().mutate( [ initialLayout[ 0 ] ] );
+		} );
 
-			expect( readProbe().hasUncommittedChanges ).toBe( false );
+		act( () => {
+			readProbe().commit( { exitEditMode: false } );
+		} );
 
-			act( () => {
-				readProbe().mutateGridSettings( {
-					...initialSettings,
-					rowHeight: 300,
-				} );
-			} );
+		expect( readProbe().editMode ).toBe( true );
+		expect( onLayoutChange ).toHaveBeenCalledTimes( 1 );
+	} );
+
+	describe( 'inline auto-save', () => {
+		const moved: DashboardWidget[] = [
+			{ ...initialLayout[ 1 ] },
+			{ ...initialLayout[ 0 ] },
+		];
+
+		beforeEach( () => {
+			jest.useFakeTimers();
+		} );
 
-			expect( onGridSettingsChange ).not.toHaveBeenCalled();
-			expect( readProbe().hasUncommittedChanges ).toBe( true );
-			expect( readProbe().gridSettings.rowHeight ).toBe( 300 );
+		afterEach( () => {
+			jest.useRealTimers();
 		} );
 
-		it( 'publishes both layout and settings on commit', () => {
+		it( 'publishes a scheduled edit once the debounce elapses, staying in normal mode', () => {
 			const onLayoutChange = jest.fn();
-			const onGridSettingsChange = jest.fn();
 			render(
 				<Harness
 					layout={ initialLayout }
 					onLayoutChange={ onLayoutChange }
-					gridSettings={ initialSettings }
-					onGridSettingsChange={ onGridSettingsChange }
+					initialEditMode={ false }
 				/>
 			);
 
 			act( () => {
-				readProbe().mutate( [ initialLayout[ 0 ] ] );
-				readProbe().mutateGridSettings( {
-					...initialSettings,
-					model: 'masonry',
-				} );
+				readProbe().mutate( moved );
+				readProbe().scheduleAutoSave();
 			} );
 
+			expect( onLayoutChange ).not.toHaveBeenCalled();
+
 			act( () => {
-				readProbe().commit();
+				jest.runOnlyPendingTimers();
 			} );
 
 			expect( onLayoutChange ).toHaveBeenCalledTimes( 1 );
-			expect( onGridSettingsChange ).toHaveBeenCalledTimes( 1 );
-			expect( onGridSettingsChange.mock.calls[ 0 ][ 0 ] ).toMatchObject( {
-				model: 'masonry',
-			} );
+			expect(
+				onLayoutChange.mock.calls[ 0 ][ 0 ].map(
+					( w: DashboardWidget ) => w.uuid
+				)
+			).toEqual( [ 'b', 'a' ] );
+			expect( readProbe().editMode ).toBe( false );
 		} );
 
-		it( 'reverts settings on cancel', () => {
+		it( 'publishes a pending edit immediately on flushAutoSave', () => {
 			const onLayoutChange = jest.fn();
-			const onGridSettingsChange = jest.fn();
 			render(
 				<Harness
 					layout={ initialLayout }
 					onLayoutChange={ onLayoutChange }
-					gridSettings={ initialSettings }
-					onGridSettingsChange={ onGridSettingsChange }
+					initialEditMode={ false }
 				/>
 			);
 
 			act( () => {
-				readProbe().mutateGridSettings( {
-					...initialSettings,
-					model: 'masonry',
-				} );
+				readProbe().mutate( moved );
+				readProbe().scheduleAutoSave();
 			} );
 
-			expect( readProbe().hasUncommittedChanges ).toBe( true );
-
 			act( () => {
-				readProbe().cancel();
+				readProbe().flushAutoSave();
 			} );
 
-			expect( onGridSettingsChange ).not.toHaveBeenCalled();
-			expect( readProbe().hasUncommittedChanges ).toBe( false );
-			expect( readProbe().gridSettings.model ).toBe( 'grid' );
+			expect( onLayoutChange ).toHaveBeenCalledTimes( 1 );
 		} );
 
-		it( 'skips publishing settings when only the layout changed', () => {
+		it( 'flushes a pending edit on unmount instead of dropping it', () => {
 			const onLayoutChange = jest.fn();
-			const onGridSettingsChange = jest.fn();
-			render(
+			const { unmount } = render(
 				<Harness
 					layout={ initialLayout }
 					onLayoutChange={ onLayoutChange }
-					gridSettings={ initialSettings }
-					onGridSettingsChange={ onGridSettingsChange }
+					initialEditMode={ false }
 				/>
 			);
 
 			act( () => {
-				readProbe().mutate( [ initialLayout[ 0 ] ] );
+				readProbe().mutate( moved );
+				readProbe().scheduleAutoSave();
 			} );
 
-			act( () => {
-				readProbe().commit();
-			} );
+			expect( onLayoutChange ).not.toHaveBeenCalled();
 
-			expect( onLayoutChange ).toHaveBeenCalledTimes( 1 );
-			expect( onGridSettingsChange ).not.toHaveBeenCalled();
-		} );
-	} );
-
-	it( 'reverts only grid settings when cancel passes revertLayout: false', () => {
-		const onLayoutChange = jest.fn();
-		const onGridSettingsChange = jest.fn();
-		const initialSettings: WidgetGridSettings = {
-			model: 'grid',
-			minColumnWidth: 350,
-			rowHeight: 200,
-		};
-		render(
-			<Harness
-				layout={ initialLayout }
-				onLayoutChange={ onLayoutChange }
-				gridSettings={ initialSettings }
-				onGridSettingsChange={ onGridSettingsChange }
-			/>
-		);
+			unmount();
 
-		act( () => {
-			readProbe().mutate( [ initialLayout[ 0 ] ] );
-			readProbe().mutateGridSettings( {
-				...initialSettings,
-				minColumnWidth: 420,
-			} );
+			expect( onLayoutChange ).toHaveBeenCalledTimes( 1 );
+			expect(
+				onLayoutChange.mock.calls[ 0 ][ 0 ].map(
+					( w: DashboardWidget ) => w.uuid
+				)
+			).toEqual( [ 'b', 'a' ] );
 		} );
 
-		expect( readProbe().hasUncommittedChanges ).toBe( true );
+		it( 'does not publish unscheduled staging on unmount', () => {
+			const onLayoutChange = jest.fn();
+			const { unmount } = render(
+				<Harness
+					layout={ initialLayout }
+					onLayoutChange={ onLayoutChange }
+				/>
+			);
 
-		act( () => {
-			readProbe().cancel( {
-				exitEditMode: false,
-				revertLayout: false,
+			act( () => {
+				readProbe().mutate( moved );
 			} );
-		} );
 
-		expect( readProbe().hasUncommittedChanges ).toBe( true );
-		expect( readProbe().layout ).toHaveLength( 1 );
-		expect( readProbe().gridSettings.minColumnWidth ).toBe( 350 );
-	} );
+			unmount();
 
-	it( 'stays in edit mode when commit or cancel passes exitEditMode: false', () => {
-		const onLayoutChange = jest.fn();
-		render(
-			<Harness
-				layout={ initialLayout }
-				onLayoutChange={ onLayoutChange }
-			/>
-		);
-
-		act( () => {
-			readProbe().mutate( [ initialLayout[ 0 ] ] );
-		} );
-
-		act( () => {
-			readProbe().commit( { exitEditMode: false } );
+			expect( onLayoutChange ).not.toHaveBeenCalled();
 		} );
-
-		expect( readProbe().editMode ).toBe( true );
-		expect( onLayoutChange ).toHaveBeenCalledTimes( 1 );
-
-		act( () => {
-			readProbe().mutate( [ initialLayout[ 0 ] ] );
-		} );
-
-		act( () => {
-			readProbe().cancel( { exitEditMode: false } );
-		} );
-
-		expect( readProbe().editMode ).toBe( true );
 	} );
 } );

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

@@ -45,6 +45,10 @@ const widgetTypes: WidgetType[] = [
 		apiVersion: 1,
 		name: 'test/greet',
 		title: 'Greet',
+		help: {
+			content: 'Greetings at a glance.',
+			links: [ { label: 'Learn more', href: 'options-general.php' } ],
+		},
 		renderModule: 'test-greet-module',
 	},
 ];
@@ -101,6 +105,26 @@ describe( 'WidgetDashboard', () => {
 		);
 	} );
 
+	it( 'surfaces the widget type help note in the header', async () => {
+		render( <Harness /> );
+
+		// The infotip trigger opens a popover holding the note.
+		await userEvent.click(
+			await screen.findByRole( 'button', {
+				name: 'More information',
+			} )
+		);
+
+		expect(
+			await screen.findByText( 'Greetings at a glance.' )
+		).toBeInTheDocument();
+
+		// The note's declared links render in the popover.
+		expect(
+			screen.getByRole( 'link', { name: 'Learn more' } )
+		).toBeInTheDocument();
+	} );
+
 	it( 'threads setAttributes into onLayoutChange on commit with merged attributes', async () => {
 		const onChange = jest.fn();
 		render( <Harness onLayoutChange={ onChange } /> );

package/src/types.ts

@@ -34,10 +34,10 @@ export type MasonryTilePlacement = Omit< DashboardLanesLayoutItem, 'key' >;
  * Structurally a union of every supported per-model shape, but the
  * intended invariant is stronger than the type suggests: every
  * placement in a given layout must match the shape of the currently
- * active `gridSettings.model`. `migrateLayout` is the only correct
- * way to transition placements across model changes; the render
- * layer is allowed to trust the active model and treat each
- * placement as the matching shape.
+ * active `gridSettings.model`. Consumers that switch the model must
+ * supply placements in the new shape; the render layer is allowed to
+ * trust the active model and treat each placement as the matching
+ * shape.
  *
  * The type system cannot enforce that invariant on its own (there is
  * no discriminator on the placement itself), so consider this union a
@@ -74,7 +74,7 @@ export interface DashboardWidget< Item = unknown > {
 	 * Grid-model-specific placement (column/row spans, ordering,
 	 * etc.). Must match the shape implied by the dashboard's active
 	 * `gridSettings.model`; see `DashboardTilePlacement` for the
-	 * invariant and `migrateLayout` for the transition mechanism.
+	 * invariant.
 	 */
 	placement?: DashboardTilePlacement;
 }
@@ -115,8 +115,8 @@ export type WidgetGridModel = 'grid' | 'masonry';
 
 /**
  * Maximum column count for the widget dashboard on wide containers.
- * Not exposed in layout settings; container width steps the count down
- * to two and one column at fixed breakpoints.
+ * Not user-configurable; container width steps the count down to two
+ * and one column at fixed breakpoints.
  */
 export const WIDGET_DASHBOARD_COLUMN_COUNT = 4;
 
@@ -244,17 +244,10 @@ export interface WidgetDashboardProps {
 
 	/**
 	 * Grid model configuration. See `WidgetGridSettings` for the shape.
+	 * Read-only for the dashboard: the consumer owns the settings and
+	 * their persistence.
 	 */
 	gridSettings?: WidgetGridSettings;
 
-	/**
-	 * Called when the user commits in-progress grid-settings edits via
-	 * the Done action. The dashboard maintains a staging copy of
-	 * settings internally; mutations stay local until commit. When
-	 * omitted, the `Layout settings` button in the customize toolbar is
-	 * hidden, since there is nowhere to persist the change.
-	 */
-	onGridSettingsChange?: ( gridSettings: WidgetGridSettings ) => void;
-
 	children?: ReactNode;
 }

package/src/utils/index.ts

@@ -1,2 +1 @@
 export { createDashboardWidget } from './create-dashboard-widget';
-export { migrateLayout } from './migrate-layout';

package/src/widget-dashboard.tsx

@@ -5,7 +5,6 @@ import { WidgetDashboardProvider } from './context/dashboard-context';
 import { WidgetDashboardUIProvider } from './context/ui-context';
 import { Actions } from './components/actions';
 import { Commands } from './components/commands';
-import { LayoutSettings } from './components/layout-settings';
 import { NoWidgetsState } from './components/no-widgets-state';
 import { ResetConfirmation } from './components/reset-confirmation';
 import { WidgetChrome } from './components/widget-chrome';
@@ -48,10 +47,10 @@ import type { WidgetDashboardProps } from './types';
  *
  * Children compose the dashboard's triggers and chrome: `Actions`,
  * `Widgets`, `Commands`, `NoWidgetsState`. The targets they open (the
- * widget inserter, the layout and widget settings editors, the reset
- * confirmation) are mounted by the engine and driven by shared UI state, so
- * a trigger works wherever it is composed without a matching target in the
- * tree. Omitting `children` renders the default arrangement.
+ * widget inserter, the widget settings editor, the reset confirmation) are
+ * mounted by the engine and driven by shared UI state, so a trigger works
+ * wherever it is composed without a matching target in the tree. Omitting
+ * `children` renders the default arrangement.
  */
 export const WidgetDashboard = Object.assign(
 	function WidgetDashboard( {
@@ -64,7 +63,6 @@ export const WidgetDashboard = Object.assign(
 		onEditChange,
 		resolveWidgetModule,
 		gridSettings,
-		onGridSettingsChange,
 		children,
 	}: WidgetDashboardProps ) {
 		return (
@@ -78,7 +76,6 @@ export const WidgetDashboard = Object.assign(
 				onEditChange={ onEditChange }
 				resolveWidgetModule={ resolveWidgetModule }
 				gridSettings={ gridSettings }
-				onGridSettingsChange={ onGridSettingsChange }
 			>
 				<WidgetDashboardUIProvider>
 					{ children ?? (
@@ -91,7 +88,6 @@ export const WidgetDashboard = Object.assign(
 					) }
 
 					<WidgetInserter />
-					<LayoutSettings />
 					<WidgetSettings />
 					<ResetConfirmation />
 				</WidgetDashboardUIProvider>

package/build/components/layout-settings/index.cjs.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../src/components/layout-settings/index.ts"],
-  "sourcesContent": ["export { LayoutSettings } from './layout-settings';\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,6BAA+B;",
-  "names": []
-}