Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Interactivity API docs: Add wp-async directives doc #62663

Merged
merged 5 commits into from
Jun 19, 2024

Conversation

cbravobernal
Copy link
Contributor

What?

Add documentation for data-wp-async directives.

Completes #61885

Copy link

github-actions bot commented Jun 18, 2024

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

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

Copy link
Member

@westonruter westonruter left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for adding these!

Should there also be notes added to the wp-on, wp-on-window, and wp-on-document sections to call out the async alternatives?

docs/reference-guides/interactivity-api/api-reference.md Outdated Show resolved Hide resolved
docs/reference-guides/interactivity-api/api-reference.md Outdated Show resolved Hide resolved
@@ -383,6 +392,10 @@ store( "myPlugin", {

The callback passed as the reference receives [the event](https://developer.mozilla.org/en-US/docs/Web/API/Event) (`event`), and the returned value by this callback is ignored. When the element is removed from the DOM, the event listener is also removed.

### `wp-on-document-async`

Similar to `wp-on-async`. An optimized version of `wp-on-document` that prevents blocking the main thread on long tasks. Use this directive for any `wp-on-document` that doesn't need the `event` object (`event.preventDefault()`, `event.stopPropagation()`, etc.)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Similar to `wp-on-async`. An optimized version of `wp-on-document` that prevents blocking the main thread on long tasks. Use this directive for any `wp-on-document` that doesn't need the `event` object (`event.preventDefault()`, `event.stopPropagation()`, etc.)
Similar to `wp-on-async`. An optimized version of `wp-on-document` that prevents blocking the main thread on long tasks. Use this directive for any `wp-on` that doesn't need synchronous access to the `event` object, in particular the methods `event.preventDefault()`, `event.stopPropagation()`, and `event.stopImmediatePropagation()`. This event listener is also added as `passive`.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in e3b0497

@westonruter
Copy link
Member

See also #62665 which would impact the docs here, especially the "async actions" section.

Copy link

Flaky tests detected in e3b0497.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/9571563158
📝 Reported issues:

@cbravobernal cbravobernal merged commit cc74558 into trunk Jun 19, 2024
60 checks passed
@cbravobernal cbravobernal deleted the docs/data-wp-on-async branch June 19, 2024 07:42
@github-actions github-actions bot added this to the Gutenberg 18.7 milestone Jun 19, 2024
@ellatrix ellatrix added the Backport to WP 6.7 Beta/RC Pull request that needs to be backported to the WordPress major release that's currently in beta label Jun 25, 2024
ellatrix pushed a commit that referenced this pull request Jun 25, 2024
* Add wp-async directives doc

* Changes requested

* Add notes to use async and further refine copy

* Add links including to async actions section

* Add async action example which yields to the main thread

---------

Co-authored-by: cbravobernal <cbravobernal@git.wordpress.org>
Co-authored-by: westonruter <westonruter@git.wordpress.org>
@ellatrix
Copy link
Member

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

@ellatrix ellatrix added Backported to WP Core Pull request that has been successfully merged into WP Core and removed Backport to WP 6.7 Beta/RC Pull request that needs to be backported to the WordPress major release that's currently in beta labels Jun 25, 2024
ellatrix pushed a commit that referenced this pull request Jun 25, 2024
* Add wp-async directives doc

* Changes requested

* Add notes to use async and further refine copy

* Add links including to async actions section

* Add async action example which yields to the main thread

---------

Co-authored-by: cbravobernal <cbravobernal@git.wordpress.org>
Co-authored-by: westonruter <westonruter@git.wordpress.org>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Backported to WP Core Pull request that has been successfully merged into WP Core [Type] Developer Documentation Documentation for developers
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants