Rename yieldToMain to splitTask and export from @wordpress/interactivity

[westonruter]

Follow up to #61885

I just realized that the new yieldToMain function isn't currently exported by @wordpress/interactivity. This should be exported because it allows for directives to reuse this logic to break up their own long tasks when they can't make use of the wp-async directive (or even if they do and still are doing a lot of work).

For example, consider this synchronous wp-on directive action which calls event.preventDefault() but then does work.

import { store, splitTask } from '@wordpress/interactivity';

store( 'foo', {
	actions: {
		showSomething: function* ( event ) => {
			event.preventDefault();
			showLoadingSpinner();
			yield splitTask();
			const data = fetchData();
			processData( data );
			yield splitTask();
			renderData( data );
		}
} );

(Granted: A developer could just re-implement yieldToMain on their own.)

If approved and backported, this will need to be mentioned in the doc updates in #62663, in particular under Async Actions.

[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: westonruter <westonruter@git.wordpress.org>
Co-authored-by: luisherranz <luisherranz@git.wordpress.org>
Co-authored-by: cbravobernal <cbravobernal@git.wordpress.org>

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

[westonruter]

Humm. In a generator context, the yieldToMain() name doesn't look so good:

yield yieldToMain();

[westonruter]

For now I've manually copied the yieldToMain() function into the Async Actions docs section in #62663.

[luisherranz]

Looks good to me.

Humm. In a generator context, the yieldToMain() name doesn't look so good:

yield yieldToMain();

I don't think it's that bad, but feel free to rename 🙂

---

By the way, shouldn't we also update this section of the documentation? Or do you want to make those changes in another pull request?

gutenberg/docs/reference-guides/interactivity-api/api-reference.md

Lines 813 to 831 in d86ecdb

	As mentioned above with [`wp-on`](#wp-on), [`wp-on-window`](#wp-on-window), and [`wp-on-document`](#wp-on-document), an async action should be used whenever the `async` versions of the aforementioned directives cannot be used due to the action requiring synchronous access to the `event` object. Synchronous access is reqired whenever the action needs to call `event.preventDefault()`, `event.stopPropagation()`, or `event.stopImmediatePropagation()`. To ensure that the action code does not contribute to a long task, you may manually yield to the main thread after calling the synchronous event API. For example:
	```js
	function toMainThread() {
	return new Promise(resolve => {
	setTimeout(resolve, 0);
	});
	}
	store("myPlugin", {
	actions: {
	handleClick: function* (event) {
	event.preventDefault();
	yield toMainThread();
	doTheWork();
	},
	},
	});
	```

[cbravobernal]

Docs have been merged with toMainThread, maybe we can rename it to that.

[luisherranz]

Docs have been merged with toMainThread, maybe we can rename it to that.

Up to you, folks 🙂

[westonruter]

Or simpler, what about just mainThread? Usage:

await mainThread();
yield mainThread();

I like this because the preposition "to" doesn't work with "await" in English (one does not just "await to something") although "to" is used with "yield" here. By removing the preposition entirely, then this awkwardness is removed. Also, by omitting a verb from the function name itself it implies that the function doesn't actually do anything on its own. Indeed, it must be used with await or yield to have any purpose.

[westonruter]

I checked with @tunetheweb and he suggested splitTask() instead.

[westonruter]

This note assumes this change will be backported.

[westonruter]

By the way, shouldn't we also update this section of the documentation? Or do you want to make those changes in another pull request?

@luisherranz This comment in the docs here I believe updates the section accordingly.

[luisherranz]

Fantastic, thank you.

[westonruter]

@cbravobernal I'll let you merge if you are satisfied.

[DAreRodz]

Nice addition. 😄 Not sure, but maybe we need to add an entry log for the splitTask() function, right?

[luisherranz]

Oh, yes please!

[westonruter]

@DAreRodz @luisherranz Like #62805?

[luisherranz]

Merged. Thanks Weston!

[ellatrix]

I just cherry-picked this PR to the wp/6.6-rc-1 branch to get it included in the next release: f37faf7