@wordpress/widget-dashboard 0.2.0 → 0.3.0

package/src/context/dashboard-context.tsx

@@ -7,6 +7,7 @@ import type { ReactNode } from 'react';
 /**
  * WordPress dependencies
  */
+import { debounce, useEvent } from '@wordpress/compose';
 import {
 	createContext,
 	useCallback,
@@ -24,14 +25,9 @@ import type {
  * Internal dependencies
  */
 import { DEFAULT_GRID } from '../utils/default-grid';
-import { computeGridModelChange } from '../utils/grid-model-change';
 import { normalizeGridSettings } from '../utils/normalize-grid-settings';
 import { DEFAULT_ROW_HEIGHT } from '../utils/row-height-presets';
-import type {
-	WidgetGridModel,
-	WidgetGridSettings,
-	DashboardWidget,
-} from '../types';
+import type { WidgetGridSettings, DashboardWidget } from '../types';
 import { WIDGET_DASHBOARD_COLUMN_COUNT } from '../types';
 
 type GridSettingsWithColumns = WidgetGridSettings & { columns: number };
@@ -49,6 +45,12 @@ function resolveGridSettings(
 const DEFAULT_RESOLVE_WIDGET_MODULE: ResolveWidgetModule = ( moduleId ) =>
 	import( /* webpackIgnore: true */ moduleId );
 
+/**
+ * Inline widget-instance edits stage live, then publish once the user pauses.
+ * A single global timer, so editing several widgets settles into one save.
+ */
+const AUTO_SAVE_DELAY_MS = 5000;
+
 /**
  * Canonical form of `layout`: widgets sorted by `placement.order` (falling
  * back to array index), then `order` stripped since position now implies it.
@@ -80,10 +82,9 @@ function canonicalize( layout: DashboardWidget[] ): DashboardWidget[] {
  * Rich state distributed to every compound component inside `WidgetDashboard`.
  * Internal — compounds reach the full state via `useDashboardInternalContext()`.
  *
- * `layout`/`onLayoutChange` and `gridSettings`/`onGridSettingsChange` here
- * operate on the staging layer, not the committed props. Mutations from
- * compound children stay in staging until `commit` publishes them on the
- * consumer.
+ * `layout`/`onLayoutChange` here operate on the staging layer, not the
+ * committed props. Mutations from compound children stay in staging until
+ * `commit` publishes them on the consumer.
  */
 interface InternalDashboardContextValue {
 	widgetTypes: WidgetType[];
@@ -92,39 +93,32 @@ interface InternalDashboardContextValue {
 	onLayoutChange: ( layout: DashboardWidget[] ) => void;
 	onLayoutReset?: () => void;
 	gridSettings: GridSettingsWithColumns;
-	onGridSettingsChange: ( gridSettings: WidgetGridSettings ) => void;
-	canEditGridSettings: boolean;
 
 	/**
-	 * Restores the staging copy of `gridSettings` to the package's
-	 * built-in defaults. Does not touch the committed slice; the user
-	 * must `commit` to publish the reset, or `cancel` to discard it.
+	 * Publishes the staged layout when it differs from the committed
+	 * prop. By default also exits edit mode; pass `{ exitEditMode: false }`
+	 * for inline auto-saves that keep the current mode.
 	 */
-	resetGridSettings: () => void;
+	commit: ( options?: CommitOptions ) => void;
 
 	/**
-	 * Publishes staged slices that differ from their committed
-	 * counterparts. By default also exits edit mode; pass
-	 * `{ exitEditMode: false }` when committing from the layout
-	 * settings drawer so customize mode stays active.
+	 * Reverts the staged layout and exits edit mode.
 	 */
-	commit: ( options?: CommitOptions ) => void;
+	cancel: () => void;
 
 	/**
-	 * Switches the layout model, updates staging, and publishes
-	 * immediately — equivalent to changing the model in layout
-	 * settings and clicking Save.
+	 * Debounced auto-save for inline widget-instance edits. Controls call it
+	 * after staging a change; a single global timer publishes once the edits
+	 * settle. The settings drawer does not use it (it commits on Save).
 	 */
-	commitGridModelChange: ( targetModel: WidgetGridModel ) => void;
+	scheduleAutoSave: () => void;
 
 	/**
-	 * Reverts staging slices. By default reverts both layout and grid
-	 * settings and exits edit mode. Pass `{ exitEditMode: false }` when
-	 * dismissing the layout settings drawer. Pass `{ revertLayout: false }`
-	 * to revert only grid settings (preserves in-progress widget layout
-	 * edits while customize mode is active).
+	 * Publishes any pending auto-save immediately. Called when leaving the
+	 * inline surface (opening the drawer, entering customize) so staged inline
+	 * edits do not commingle with the drawer's explicit-save flow.
 	 */
-	cancel: ( options?: CancelOptions ) => void;
+	flushAutoSave: () => void;
 
 	hasUncommittedChanges: boolean;
 	editMode: boolean;
@@ -136,11 +130,6 @@ interface CommitOptions {
 	exitEditMode?: boolean;
 }
 
-interface CancelOptions {
-	exitEditMode?: boolean;
-	revertLayout?: boolean;
-}
-
 const Context = createContext< InternalDashboardContextValue | null >( null );
 
 /**
@@ -184,21 +173,15 @@ interface ProviderProps {
 
 	gridSettings?: WidgetGridSettings;
 
-	/**
-	 * Fired on commit when the staged settings differ from
-	 * `gridSettings`.
-	 */
-	onGridSettingsChange?: ( gridSettings: WidgetGridSettings ) => void;
-
 	children: ReactNode;
 }
 
 /**
- * Provider for the dashboard's staging layer. Owns staging copies of
- * `layout` and `gridSettings`; `commit` publishes whichever slice
- * differs from its committed prop, `cancel` reverts both.
+ * Provider for the dashboard's staging layer. Owns the staging copy of
+ * `layout`; `commit` publishes it when it differs from the committed
+ * prop, `cancel` reverts it.
  *
- * Staging re-syncs from the committed props on prop change. In-flight
+ * Staging re-syncs from the committed prop on prop change. In-flight
  * edits are dropped silently when an external update (cross-tab commit,
  * reset, websocket push) lands. Consumers that cannot tolerate this
  * loss should mediate the prop updates before forwarding them here.
@@ -215,7 +198,6 @@ export function WidgetDashboardProvider( {
 	onEditChange,
 	resolveWidgetModule = DEFAULT_RESOLVE_WIDGET_MODULE,
 	gridSettings: committedGridSettings = DEFAULT_GRID,
-	onGridSettingsChange,
 	children,
 }: ProviderProps ): React.ReactNode {
 	const [ stagingLayout, setStagingLayout ] =
@@ -228,17 +210,10 @@ export function WidgetDashboardProvider( {
 		setStagingLayout( committedLayout );
 	}, [ committedLayout ] );
 
-	const [ stagingGridSettings, setStagingGridSettings ] =
-		useState< WidgetGridSettings >( () =>
-			normalizeGridSettings( committedGridSettings, DEFAULT_ROW_HEIGHT )
-		);
-
-	// Same external-resync semantics as `stagingLayout`.
-	useEffect( () => {
-		setStagingGridSettings(
-			normalizeGridSettings( committedGridSettings, DEFAULT_ROW_HEIGHT )
-		);
-	}, [ committedGridSettings ] );
+	const gridSettings = useMemo(
+		() => resolveGridSettings( committedGridSettings ),
+		[ committedGridSettings ]
+	);
 
 	const hasLayoutChanges = useMemo(
 		() =>
@@ -249,12 +224,7 @@ export function WidgetDashboardProvider( {
 		[ committedLayout, stagingLayout ]
 	);
 
-	const hasGridSettingsChanges = useMemo(
-		() => ! fastDeepEqual( committedGridSettings, stagingGridSettings ),
-		[ committedGridSettings, stagingGridSettings ]
-	);
-
-	const hasUncommittedChanges = hasLayoutChanges || hasGridSettingsChanges;
+	const hasUncommittedChanges = hasLayoutChanges;
 
 	const commit = useCallback(
 		( options?: CommitOptions ) => {
@@ -262,75 +232,47 @@ export function WidgetDashboardProvider( {
 				onLayoutChange( canonicalize( stagingLayout ) );
 			}
 
-			if ( hasGridSettingsChanges ) {
-				onGridSettingsChange?.(
-					normalizeGridSettings(
-						stagingGridSettings,
-						DEFAULT_ROW_HEIGHT
-					)
-				);
-			}
-
 			if ( options?.exitEditMode !== false ) {
 				onEditChange?.( false );
 			}
 		},
-		[
-			hasLayoutChanges,
-			hasGridSettingsChanges,
-			onLayoutChange,
-			onGridSettingsChange,
-			stagingLayout,
-			stagingGridSettings,
-			onEditChange,
-		]
+		[ hasLayoutChanges, onLayoutChange, stagingLayout, onEditChange ]
 	);
 
-	const cancel = useCallback(
-		( options?: CancelOptions ) => {
-			if ( options?.revertLayout !== false ) {
-				setStagingLayout( committedLayout );
-			}
-			setStagingGridSettings( committedGridSettings );
-			if ( options?.exitEditMode !== false ) {
-				onEditChange?.( false );
-			}
-		},
-		[ committedLayout, committedGridSettings, onEditChange ]
+	// Auto-save for inline edits.
+	// A single debounced timer publishes through `useEvent`, so it always
+	// reads the latest `commit` (and so the current staging) without
+	// resetting on staging re-renders.
+	const publishAutoSave = useEvent( () => commit( { exitEditMode: false } ) );
+
+	const scheduleAutoSave = useMemo(
+		() => debounce( publishAutoSave, AUTO_SAVE_DELAY_MS ),
+		[ publishAutoSave ]
 	);
 
-	const commitGridModelChange = useCallback(
-		( targetModel: WidgetGridModel ) => {
-			const next = computeGridModelChange( {
-				layout: stagingLayout,
-				gridSettings: stagingGridSettings,
-				targetModel,
-			} );
+	const flushAutoSave = useCallback(
+		() => scheduleAutoSave.flush(),
+		[ scheduleAutoSave ]
+	);
 
-			if ( ! next ) {
-				return;
-			}
+	// Entering customize flushes any pending inline save first, so it does not
+	// commingle with the layout edit flow.
+	useEffect( () => {
+		if ( ! editMode ) {
+			return;
+		}
 
-			setStagingLayout( next.layout );
-			setStagingGridSettings( next.gridSettings );
-			onLayoutChange( canonicalize( next.layout ) );
-			onGridSettingsChange?.(
-				normalizeGridSettings( next.gridSettings, DEFAULT_ROW_HEIGHT )
-			);
-			onEditChange?.( false );
-		},
-		[
-			stagingLayout,
-			stagingGridSettings,
-			onLayoutChange,
-			onGridSettingsChange,
-			onEditChange,
-		]
-	);
+		scheduleAutoSave.flush();
+	}, [ editMode, scheduleAutoSave ] );
 
-	const resetGridSettings = useCallback( () => {
-		setStagingGridSettings( DEFAULT_GRID );
-	}, [] );
+	// Flush, not cancel, on unmount: an edit still inside the debounce window
+	// must persist when the user navigates away from the dashboard.
+	useEffect( () => () => scheduleAutoSave.flush(), [ scheduleAutoSave ] );
+
+	const cancel = useCallback( () => {
+		setStagingLayout( committedLayout );
+		onEditChange?.( false );
+	}, [ committedLayout, onEditChange ] );
 
 	useEffect( () => {
 		if ( stagingLayout.length === 0 ) {
@@ -343,8 +285,6 @@ export function WidgetDashboardProvider( {
 		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [ stagingLayout.length === 0 ] );
 
-	const canEditGridSettings = onGridSettingsChange !== undefined;
-
 	const value = useMemo< InternalDashboardContextValue >(
 		() => ( {
 			widgetTypes,
@@ -352,13 +292,11 @@ export function WidgetDashboardProvider( {
 			layout: stagingLayout,
 			onLayoutChange: setStagingLayout,
 			onLayoutReset,
-			gridSettings: resolveGridSettings( stagingGridSettings ),
-			onGridSettingsChange: setStagingGridSettings,
-			canEditGridSettings,
-			resetGridSettings,
+			gridSettings,
 			commit,
-			commitGridModelChange,
 			cancel,
+			scheduleAutoSave,
+			flushAutoSave,
 			hasUncommittedChanges,
 			editMode,
 			onEditChange,
@@ -369,12 +307,11 @@ export function WidgetDashboardProvider( {
 			isResolvingWidgetTypes,
 			stagingLayout,
 			onLayoutReset,
-			stagingGridSettings,
-			canEditGridSettings,
-			resetGridSettings,
+			gridSettings,
 			commit,
-			commitGridModelChange,
 			cancel,
+			scheduleAutoSave,
+			flushAutoSave,
 			hasUncommittedChanges,
 			editMode,
 			onEditChange,

package/src/context/ui-context.tsx

@@ -13,14 +13,10 @@ import {
 	useState,
 } from '@wordpress/element';
 
-type DrawerSide = 'left' | 'right';
-
 interface DashboardUIContextValue {
 	inserterOpen: boolean;
 	setInserterOpen: ( next: boolean ) => void;
 
-	layoutSettingsOpen: boolean;
-	setLayoutSettingsOpen: ( next: boolean ) => void;
 	resetDialogOpen: boolean;
 	setResetDialogOpen: ( next: boolean ) => void;
 
@@ -32,23 +28,6 @@ interface DashboardUIContextValue {
 	 */
 	settingsWidgetUuid: string | null;
 	setSettingsWidgetUuid: ( next: string | null ) => void;
-
-	/**
-	 * Edge the settings drawer slides in from. The gear sets it from the
-	 * widget's on-screen position so the drawer opens on the side away
-	 * from the widget, trying not to cover it.
-	 */
-	settingsDrawerSide: DrawerSide;
-	setSettingsDrawerSide: ( next: DrawerSide ) => void;
-
-	/**
-	 * Inline-start inset (px) the settings drawer is offset by when it
-	 * opens from the left, so it clears fixed page chrome (the WordPress
-	 * admin menu) instead of sliding over it. `0` when there's nothing to
-	 * clear.
-	 */
-	settingsDrawerInset: number;
-	setSettingsDrawerInset: ( next: number ) => void;
 }
 
 const Context = createContext< DashboardUIContextValue | null >( null );
@@ -80,38 +59,21 @@ interface ProviderProps {
  */
 export function WidgetDashboardUIProvider( { children }: ProviderProps ) {
 	const [ inserterOpen, setInserterOpen ] = useState( false );
-	const [ layoutSettingsOpen, setLayoutSettingsOpen ] = useState( false );
 	const [ resetDialogOpen, setResetDialogOpen ] = useState( false );
 	const [ settingsWidgetUuid, setSettingsWidgetUuid ] = useState<
 		string | null
 	>( null );
-	const [ settingsDrawerSide, setSettingsDrawerSide ] =
-		useState< DrawerSide >( 'right' );
-	const [ settingsDrawerInset, setSettingsDrawerInset ] = useState( 0 );
 
 	const value = useMemo< DashboardUIContextValue >(
 		() => ( {
 			inserterOpen,
 			setInserterOpen,
-			layoutSettingsOpen,
-			setLayoutSettingsOpen,
 			resetDialogOpen,
 			setResetDialogOpen,
 			settingsWidgetUuid,
 			setSettingsWidgetUuid,
-			settingsDrawerSide,
-			setSettingsDrawerSide,
-			settingsDrawerInset,
-			setSettingsDrawerInset,
 		} ),
-		[
-			inserterOpen,
-			layoutSettingsOpen,
-			resetDialogOpen,
-			settingsWidgetUuid,
-			settingsDrawerSide,
-			settingsDrawerInset,
-		]
+		[ inserterOpen, resetDialogOpen, settingsWidgetUuid ]
 	);
 
 	return <Context.Provider value={ value }>{ children }</Context.Provider>;

package/src/test/actions.test.tsx

@@ -15,7 +15,7 @@ import type { WidgetType } from '@wordpress/widget-primitives';
  * Internal dependencies
  */
 import { WidgetDashboard } from '../widget-dashboard';
-import type { DashboardWidget, WidgetGridSettings } from '../types';
+import type { DashboardWidget } from '../types';
 
 const widgetTypes: WidgetType[] = [];
 
@@ -25,24 +25,16 @@ 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 );
 
@@ -50,8 +42,6 @@ function Harness( {
 		<WidgetDashboard
 			layout={ layout }
 			onLayoutChange={ onLayoutChange }
-			gridSettings={ gridSettings }
-			onGridSettingsChange={ onGridSettingsChange }
 			widgetTypes={ widgetTypes }
 			editMode={ editMode }
 			onEditChange={ ( next ) => {
@@ -146,72 +136,12 @@ describe( 'WidgetDashboard.Actions', () => {
 		).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( 'does not render a Layout settings button', () => {
+		render( <Harness initialEditMode /> );
+
+		expect(
+			screen.queryByRole( 'button', { name: 'Layout settings' } )
+		).not.toBeInTheDocument();
 	} );
 
 	it( 'throws when used outside a WidgetDashboard subtree', () => {

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
-		);
-	} );
 } );