Add a “waitForTransition” data API

[adamsilverstein]

What?

Add a new "subscribeOnChange" API.

Why?

Based on feedback from @youknowriad - #17632 (comment) this API helps address a common request for a "Post Published Hook". (or really a "post anything hook").

How?

Developers can now call subscribeOnChange with a callback function and a test they want to trigger "After", for example saving a post would be monitored with a callback using isSavingPost.

Testing Instructions

1. Open or create a test post.
2. Paste the following snippet into the console:
   wp.data.subscribeOnChange( () => { console.log( "Post saved." ); }, () => wp.data.select( 'core/editor' ).isSavingPost() );
3. Save the post. Note that "Post Saved" is triggered once (and only once) after the post save completes

Open questions

• Does always watching for true/false make sense or should the API accept values to test for start/end
• Have I exposed and documented the API correctly? The data package structure is complex and I'm not sure I did this right
• Currently the function fires only once, should it instead "reset", waiting for false again first (then true and false again before triggering)? As is developers would need to re-add the listener each time
• Should the function return an unsubscribe function (similar to subscribe) so developers can unhook their listeners?

[gaambo]

Hi, is this still being considered or are there any things to help with?
Such a hook would be great for non-React JavaScript to run certain things (eg metaboxes or other customized editor implementations).

[adamsilverstein]

@gaambo I haven't had a chance to revisit, see the last comment on the thread (#41169 (comment)) for what needs work next here if you want to give it a try.

[adamsilverstein]

Hi, is this still being considered or are there any things to help with? Such a hook would be great for non-React JavaScript to run certain things (eg metaboxes or other customized editor implementations).

Hey @gaambo thanks for the offer of help! One way to help would be to test the approach to see if it works for you; another would be to add some tests that covered this function. Do you want to try to work on one of those?

[gaambo]

Hey @gaambo thanks for the offer of help! One way to help would be to test the approach to see if it works for you; another would be to add some tests that covered this function. Do you want to try to work on one of those?

Hi, sorry I never got to do more with this issue. I tried a few things, but that stuff was above my head 😅

In the project I initially needed this I solved it like this:

window.wp.data.subscribe(() => {
    const isSavingMetaBoxes = window.wp.data
        .select("core/edit-post")
        .isSavingMetaBoxes();

    const isDoneSaving = wasSaving && !isSavingMetaBoxes;

    if (isSavingMetaBoxes && !hasChangedInputs) {
        // Do something while/before saving
    }
    if (isDoneSaving) {
        // Do something after saving
    }

    wasSaving = isSavingMetaBoxes;
});

Which comes down to

window.wp.data.subscribe(() => {
    const isSavingMetaBoxes = window.wp.data
        .select("core/edit-post")
        .isSavingMetaBoxes();
});

And I'm not sure if the solution after this PR is so much better/shorter.

waitForTransition(  () => wp.data.select( 'core/editor' ).isSavingPost() ).then( () => {
  // Do something when the post is done saving.
  console.log( 'Post saved!' );
} );

I think my main concern with my current implementation was, that I'm afraid the subscribe callback would be called on each and every (=any) change in the datastore. But it seems the implementation in PR also has this "problem"?

I see in this PR, it unsubscribes after triggering = it will only get triggered once. In my case I needed it to run on every save again.

[jsnajdr]

I see in this PR, it unsubscribes after triggering = it will only get triggered once. In my case I needed it to run on every save again.

In that case you can run waitForTransition in a loop:

while ( true ) {
  await waitForTransition( ... );
  console.log( 'Post saved!' )
}

The downside of this is that transitions that happen outside the waitForTransition call will not be catched. For example, when there is a transition that happens during the console.log call, or the user code that would replace it in real-live code.

We'd need to start using Observables to create an "async stream of transition events".

I'm afraid the subscribe callback would be called on each and every (=any) change in the datastore.

Yes, this will be happening and it's not a problem. There's no other way to detect "relevant changes" other than inspecting "all changes".

[github-actions]

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 props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: adamsilverstein <adamsilverstein@git.wordpress.org>
Co-authored-by: jsnajdr <jsnajdr@git.wordpress.org>
Co-authored-by: gaambo <gaambo@git.wordpress.org>
Co-authored-by: Mamaduka <mamaduka@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[Mamaduka]

Thanks for continuing working on this, @adamsilverstein!

I would feel more comfortable merging this if we had one use case in the core or at least some unit tests for the new method.

[adamsilverstein]

Thanks for continuing working on this, @adamsilverstein!

I would feel more comfortable merging this if we had one use case in the core or at least some unit tests for the new method.

I added some tests.

Usage Examples

Here are existing codebases examples Claude found that implement the manual wasSavingPost pattern that waitForTransition would simplify:

1. Gutenberg Core - Meta Box Save Trigger (historical)

• Permalink: https://github.com/WordPress/gutenberg/blob/v7.0.0/packages/edit-post/src/store/effects.js#L50-L72
• The core Gutenberg codebase itself used this exact pattern to trigger metabox saves after post save completion

2. ACF (Advanced Custom Fields) - Metabox Save Workaround

• Issue: Custom Fields do not save when creating a new page AdvancedCustomFields/acf#653
• Users had to implement the full subscribe/wasSaving pattern to trigger metabox saves when WordPress failed to detect dynamically-added metaboxes
• This led to a fix that was eventually merged into Gutenberg 14.5 / WordPress 6.2

3. Trigger Action After Save Pattern Gist

• Gist: https://gist.github.com/adamsilverstein/79c4698b1e9e3aac79ad18081b0d3554
• Shows the standard pattern developers need to implement

4. Custom Admin Notices Pattern

• Gist: https://gist.github.com/davidfcarr/a26bf62b16e845b74b6f7e1b4ad4a3e7
• RSVPMaker plugin author's pattern for dispatching notices after save completion

5. Yoast SEO - Gutenberg Data API Subscription

• PR: Subscribe to Gutenberg's data API Yoast/wordpress-seo#9080
• Implements subscription to Gutenberg's data API for SEO analysis after content changes

6. Edit Flow Plugin

• PR: Fix custom status error with Gutenberg 7.2+ Automattic/edit-flow#584
• Needed save completion detection for custom post status handling

7. Original Feature Request Context

• Issue: Add hook for successful post save #17632 documents use cases like Elasticsearch indexing and Apple News publishing that need post-save callbacks

All of these implement variations of this pattern:
let wasSaving = select('core/editor').isSavingPost();
subscribe(() => {
const isSaving = select('core/editor').isSavingPost();
if (wasSaving && !isSaving) { /* action */ }
wasSaving = isSaving;
});

With waitForTransition, this becomes:
waitForTransition(() => select('core/editor').isSavingPost())
.then(() => { /* action */ });