Dashboard: staging layer for in-progress layout edits#78071
Merged
Conversation
WidgetDashboardProvider now keeps an internal staging copy of the layout. In-progress mutations (drag, resize, insert, setAttributes) mutate staging only; the consumer's onLayoutChange fires once on commit. Adds hasUncommittedChanges (deep-equal between committed and staging via fast-deep-equal) plus commitLayout and cancelLayout actions. Auto-flips edit mode on when the layout becomes empty. Existing tests are updated to follow the staged commit flow (insert or setAttributes followed by Done) and the actions harness now uses a non-empty layout so the auto-edit effect does not interfere.
Replaces the placeholder console.log handlers in the dashboard toolbar with the staging-layer commit and cancel actions. Done publishes the staged layout to the consumer; Cancel discards it and exits edit mode without firing onLayoutChange.
Aligns the hook with the rest of the route's named-export convention (the local barrel and stage.tsx already imported it as named via re-export). Drops the now-stale test under the shared hooks/test directory; the test moves next to the source in a follow-up.
Moves the unit test alongside the hook implementation under hooks/use-dashboard-layout/test/, so each hook owns its tests and the shared hooks/test/ directory disappears.
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
|
Size Change: 0 B Total Size: 7.93 MB ℹ️ View Unchanged
|
The grid model assigns explicit `order: 0, 1, …` to each item after the first drag. A swap followed by an undo restores the visible arrangement but leaves explicit orders in staging, while the committed layout never had any. Deep-equal flagged this as dirty and the toolbar treated it as a pending change. Canonicalize both layouts before comparison: sort by `placement.order` (falling back to the array index when omitted), then strip `order` since the array position now encodes it. Adds a regression test that simulates a swap and its undo.
The Done button now reads `hasUncommittedChanges` from the dashboard context and renders disabled when staging matches committed. Avoids the no-op confirmation path when the user enters Customize and exits without touching the layout. Replaces the toggle-on-click test with a Customize-only assertion plus an explicit "Done is disabled when there are no staging changes" check.
retrofox
added
[Type] Experimental
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces a staging layer for the Dashboard widget layout so edits made during “Customize” accumulate locally and are only persisted to the consumer when the user clicks Done (with Cancel discarding in-progress edits). This reduces write amplification to the preferences store/REST persistence and enables clean rollback of an edit session.
Changes:
- Add staging layout state in
WidgetDashboardProvider, withcommitLayout/cancelLayoutactions and ahasUncommittedChangesflag (deep-equal). - Wire Actions toolbar to commit/cancel flows and disable Done when there are no uncommitted changes; auto-enter edit mode when layout becomes empty.
- Update and add unit tests for the staged commit behavior; switch
useDashboardLayoutto a named export and update imports accordingly; addfast-deep-equal.
Reviewed changes
Copilot reviewed 11 out of 12 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| routes/dashboard/widget-dashboard/context/dashboard-context.tsx | Adds staging layout state, commit/cancel actions, deep-equal change detection, and auto-edit-mode behavior. |
| routes/dashboard/widget-dashboard/components/actions/actions.tsx | Hooks toolbar buttons up to commit/cancel; disables Done when no staged changes. |
| routes/dashboard/widget-dashboard/types.ts | Tightens widget icon typing and updates WidgetDashboard prop docs for staged semantics. |
| routes/dashboard/package.json | Adds fast-deep-equal dependency for change detection. |
| package-lock.json | Locks the new dependency. |
| routes/dashboard/hooks/use-dashboard-layout/use-dashboard-layout.ts | Converts useDashboardLayout to a named export. |
| routes/dashboard/hooks/use-dashboard-layout/index.ts | Updates re-export to named form. |
| routes/dashboard/hooks/use-dashboard-layout/test/use-dashboard-layout.test.ts | Updates test imports to match named export and moved paths. |
| routes/dashboard/widget-dashboard/test/widget-dashboard.test.tsx | Updates attribute mutation test to assert commit-time onLayoutChange. |
| routes/dashboard/widget-dashboard/test/inserter.test.tsx | Updates inserter tests to assert commit-time onLayoutChange via Done. |
| routes/dashboard/widget-dashboard/test/actions.test.tsx | Updates Actions tests for staged semantics, Done disabled state, and Cancel behavior. |
| routes/dashboard/widget-dashboard/test/staging.test.tsx | Adds focused coverage for staging behavior, commit/cancel, and auto edit-mode on empty layout. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+274
to
278
| * The consumer owns the committed layout state; the dashboard maintains | ||
| * a staging copy internally for in-progress edits, and `onLayoutChange` | ||
| * fires only when the user commits via the Done action (or when an | ||
| * action like reset replaces the committed layout from outside). | ||
| */ |
|
|
||
| const commitLayout = useCallback( () => { | ||
| if ( hasUncommittedChanges ) { | ||
| onLayoutChange( stagingLayout ); |
The block doc for WidgetDashboardProps and the field doc for onLayoutChange were stale: the former mentioned a "reset replaces the committed layout from outside" path that does not flow through this callback, and the latter still described "every layout mutation". With the staging layer in place, onLayoutChange only fires from commitLayout (the Done action). Documents the actual contract.
commitLayout was publishing the raw stagingLayout, while hasUncommittedChanges already compared canonicalized copies. The persisted payload accumulated redundant placement.order values that the comparison treated as implicit; the publish form and the compare form had drifted. Pipe the staged layout through canonicalize() before invoking the consumer's onLayoutChange so the persisted shape is sorted by order with `order` stripped, matching the canonical comparison form. Updates the canonicalize doc to describe the dual use and adds a test that pins the publish payload.
2 tasks
| * Visual identifier. In `widget.json` this is a Dashicon slug string; | ||
| * widgets registered in JS may also pass a React node (an | ||
| * `@wordpress/icons` SVG component, or any element). | ||
| * Visual identifier shown in the widget header; dashicon string, React node, or SVG component. |
Comment on lines
176
to
+184
| const value = useMemo< InternalDashboardContextValue >( | ||
| () => ( { | ||
| widgetTypes, | ||
| layout, | ||
| onLayoutChange, | ||
| layout: stagingLayout, | ||
| onLayoutChange: setStagingLayout, | ||
| onLayoutReset, | ||
| commitLayout, | ||
| cancelLayout, | ||
| hasUncommittedChanges, |
Comment on lines
+64
to
+74
| function Harness( { layout, onLayoutChange }: HarnessProps ) { | ||
| const [ editMode, setEditMode ] = useState( true ); | ||
|
|
||
| return ( | ||
| <WidgetDashboard | ||
| layout={ layout } | ||
| onLayoutChange={ onLayoutChange } | ||
| widgetTypes={ widgetTypes } | ||
| editMode={ editMode } | ||
| onEditChange={ setEditMode } | ||
| > |
retrofox
force-pushed
the
update/dashboard-staging-layout
branch
from
d6eef0d to
cfa391b
Compare
* show success snackbar when the dashboard layout is saved Wraps the dashboard route's onLayoutChange handler so it dispatches a success notice on @wordpress/notices after persisting. The user gets a "Layout saved." snackbar on Done, matching the feedback pattern used by other admin surfaces (e.g., experimental features toggles). * Reword saving dashboard message
…s/gutenberg into update/dashboard-staging-layout
|
Flaky tests detected in 11cc3ba. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/25699602474
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What?
Introduces a staging layer in
WidgetDashboardProviderso layout edits accumulate locally during edit mode and are only persisted to the consumer when the user clicks Done.stagingLayoutmirrors the committedlayoutprop, kept in sync viauseEffectwhen the committed value changes from outside (e.g., after a reset).commitLayoutandcancelLayoutactions: Done publishes the staged layout viaonLayoutChangeand exits edit mode; Cancel discards the staging copy and exits edit mode without firingonLayoutChange.hasUncommittedChangesflag (deep-equal between committed and staging viafast-deep-equal).useDashboardLayoutswitched to a named export and its unit test moved next to the source underhooks/use-dashboard-layout/test/.Why?
Two issues with the previous behavior, both surfaced once the dashboard had real persistence wiring (PR #78066):
Every mutation persisted. Drag, resize, attribute edits, inserts and deletes each fired
onLayoutChange, which writes through to the preferences store and triggers a debounced REST PUT. A user dragging a widget around or resizing it would queue dozens of writes per second. With the staging layer, all of those mutations stay local; the network request only happens once, on commit.No way to discard a customization session. The Cancel button was a placeholder that just exited edit mode without rolling back; any change the user made was already committed. With the staging copy, Cancel cleanly restores the last committed layout and the consumer's
onLayoutChangeis never called.The staging copy also makes it natural to expose
hasUncommittedChangesto compound children that want to react to in-flight edits (e.g., disable a destructive action while there are pending changes), without requiring consumers to track diffs themselves.How?
Provider (
routes/dashboard/widget-dashboard/context/dashboard-context.tsx):stagingLayoutinuseState, initialized from the committedlayoutprop. AuseEffectkeyed oncommittedLayoutre-syncs staging whenever the committed value changes from outside (covers reset, plus any consumer-side replacement of the layout).layout: stagingLayoutandonLayoutChange: setStagingLayout. Compound children mutate the staging copy; they never see the committed layout directly. The committed layout is only referenced inside the provider for diffing.hasUncommittedChangesis a memoized deep-equal between committed and staging.commitLayoutis gated onhasUncommittedChanges(skips the no-op call when the user enters edit mode and clicks Done without changing anything), then exits edit mode.cancelLayoutresets staging back to the committed layout and exits edit mode.useEffectkeyed onstagingLayout.length === 0flips edit mode on when the layout becomes empty. The dependency is the booleanlength === 0rather than the array itself, so non-empty mutations don't re-trigger the effect. An exhaustive-deps suppression covers the intentional omission ofonEditChangefrom the deps (it would re-fire the effect on every identity change of the callback).Toolbar (
routes/dashboard/widget-dashboard/components/actions/actions.tsx):commitLayout(replaces the placeholderconsole.log( 'done' )).cancelLayout(replaces the placeholderconsole.log( 'cancel' )).Public API surface unchanged:
WidgetDashboardstill receiveslayoutandonLayoutChange. The semantics ofonLayoutChangeshift from "every mutation" to "every commit", which is a behavior change but not a type signature change. The dashboard route instage.tsxdid not need to change.Tests
Adds
routes/dashboard/widget-dashboard/test/staging.test.tsxwith five cases:onLayoutChange.commitpublishes the staged layout toonLayoutChangeexactly once, with the staged contents.cancelrestores staging to committed and never firesonLayoutChange.hasUncommittedChangesflips correctly across the same flows.)Existing test suites updated to follow the staged commit flow:
inserter.test.tsx: every insertion test now clicks Done after Select to assert the commit-time payload.widget-dashboard.test.tsx: thesetAttributestest mutates outside edit mode (the widget's content isinertin edit mode), enters Customize, then clicks Done.actions.test.tsx: harness uses a non-empty layout so the auto-edit effect does not flip edit mode under the test, and adds two new cases covering "Done with no changes does not fire onLayoutChange" and "Cancel exits edit mode without firing onLayoutChange".26 unit tests pass.
Manual testing
/wp-admin/admin-ajax.phpor the user-meta REST PUT)./wp/v2/users/mecarryingpersisted_preferencesis sent with the new layout.useEffect).Screen.Recording.2026-05-07.at.6.15.37.PM.mov