Details Block: Fix keyboard accessibility issues and allow list view selection to show up inner blocks #70056

yogeshbhutkar · 2025-05-05T09:27:20Z

What, Why, and How?

This PR enhances keyboard interaction with the Details block, enabling users to expand inner blocks using the keyboard. It also fixes a bug that previously prevented selecting an inner block from the List View; clicking an inner block in the List View now correctly selects it in the editor canvas.

With this PR, pressing the down arrow key expands the inner blocks within the Details block, while pressing the up arrow key collapses them.

Testing Instructions

Create a post and add the following block markup.

Code

<!-- wp:paragraph -->
<p>First Paragraph Block</p>
<!-- /wp:paragraph -->

<!-- wp:details -->
<details class="wp-block-details">
<summary>Details Block Summary</summary>
<!-- wp:paragraph {"placeholder":"Type / to add a hidden block"} -->
<p>Details Block Content</p>
<!-- /wp:paragraph -->
<!-- wp:paragraph -->
<p>Details Block Content</p>
<!-- /wp:paragraph -->
</details>
<!-- /wp:details -->

<!-- wp:paragraph -->
<p>Second Paragraph Block</p>
<!-- /wp:paragraph -->

Try moving through the blocks with the arrow keys.
Confirm, the inner blocks within details are accessible using the keyboard.
Open the list view and expand the details block.
Confirm that clicking on an inner block within the list view opens and selects the inner block properly.

Screencast

packages/block-library/src/details/edit.js

github-actions · 2025-05-05T11:16:36Z

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.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @armandovias.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

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

Unlinked contributors: armandovias.

Co-authored-by: yogeshbhutkar <[email protected]>
Co-authored-by: Mamaduka <[email protected]>
Co-authored-by: t-hamano <[email protected]>
Co-authored-by: alexstine <[email protected]>
Co-authored-by: joedolson <[email protected]>
Co-authored-by: megane9988 <[email protected]>

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

Mamaduka · 2025-05-05T13:03:25Z

Adding handlers for arrow keys introduces a new behavior for details, which is expanded using Space or Enter keys. Are we okay with this? It would be good to get a11y feedback on this PR before it's merged. cc @joedolson

P.S. I think @t-hamano was also working on this issue.

packages/block-library/src/details/edit.js

alexstine · 2025-05-05T14:59:53Z

@yogeshbhutkar Thanks for working on this.

@Mamaduka We need a way to expand the details block because it isn't currently possible in the editor with the keyboard alone. Give it a test on current trunk, not sure how anyone allowed a regression like this to slip by without keyboard testing. Seems like only way is the mouse at this point.

yogeshbhutkar · 2025-05-06T04:18:28Z

On a separate note, while spacebar toggling makes sense on the front end, it disrupts the editing experience (I understand it's the default behavior). Disabling this behavior when typing in the summary's rich text would be better. I'd appreciate any accessibility feedback on this.

Observe, pressing the spacebar while typing toggles the hidden content, which could be confusing for users in the editor.

alexstine · 2025-05-06T04:23:41Z

@yogeshbhutkar Yes, absolutely. If you can detect focus in the summary rich text, space keyboard event needs to be prevented for expand/collapse.

t-hamano

Thanks for the PR! The approach that uses keyboard events to collapse or expand the content is an interesting approach.

The only concern is that the summary text can span multiple lines. In this case, the content is toggled every time you move from one line to another can be annoying.

Another approach I can think of may be using the Enter key. Additionally, ~~let screenreader users know the details block was toggled by the speak() method~~. In other words, the code would be like this:

<summary
	onKeyDown={ ( event ) => {
		if ( event.key === 'Enter' && ! event.shiftKey ) {
			setIsOpen( ! isOpen );
			event.preventDefault();
		}
	} }
>

Finally, I think we also need to add some e2e tests to avoid regressions.

t-hamano · 2025-05-06T11:46:37Z

Another thing to note is that in CJK languages, an IME (Input Method Editor) is used to input complex characters.

There is a higher-order function to ignore keyboard events during IME composition. We will probably need to wrap keydown events in this function in your Details block as well.

See the following PRs for more details:

alexstine · 2025-05-06T14:13:20Z

That looks good @t-hamano. Shift enter will insert new line while enter will expand/collapse. I'm not overly thrilled with the UX but it is 100% better than trunk today. Also, can we fix the list view here as well? Any time a hidden block is selected, auto-expand the summary?

Thanks.

t-hamano · 2025-05-06T14:30:20Z

@alexstine

Also, can we fix the list view here as well? Any time a hidden block is selected, auto-expand the summary?

I think you can confirm that this issue has already been fixed in this PR. This is because when an inner block is selected in the List View, hasSelectedInnerBlock is true and the open attribute of the details element is true:

https://github.com/WordPress/gutenberg/pull/70056/files#diff-20d83620db8197c679e5617a73e78de6306074dff49588bb00fd5ee35a17793bR105

joedolson · 2025-05-06T15:51:52Z

This looks like it's progressing well; thanks for getting on this! I think that you all have this well in hand, but if you need a 2nd review once everything is ready, let me know.

alexstine · 2025-05-06T17:05:00Z

This is working much better indeed. For sure need to do something about the expanding content though. If I insert a new line with enter and then down arrow to it, all I hear is expanded. So I do like the idea of shift+enter to insert a new line, enter will trigger expand/collapse, and arrows should navigate the content only.

t-hamano

Thanks for the update, @yogeshbhutkar!

I think this PR is going pretty well.

Any time a hidden block is selected, auto-expand the summary?

Can we add an e2e test for this? The steps should be like this:

Insert a Details block
Open the List view
Press the right arrow key: The inner blocks of the Details block are displayed in the List View
Press the down arrow key: The first inner block is focused in the List View
Press the enter key: The first inner block should be focused in the editor canvas

packages/block-library/src/details/edit.js

t-hamano · 2025-05-08T02:56:44Z

packages/components/src/private-apis.ts

@@ -18,5 +19,6 @@ lock( privateApis, {
 	Theme,
 	Menu,
 	kebabCase,
+	withIgnoreIMEEvents,


@WordPress/gutenberg-components

We export this HOF as a private API. We need this function in the block library to prevent the Details content from being toggled by the Enter key event fired by the IME event.

Update: Let's test whether it works without this HOF.

Update: If the HOF is not used, unintended events occur in the IME and it does not work properly (See #70056 (comment)). Therefore, it is necessary to use HOF as a private API.

test/e2e/specs/editor/blocks/details.spec.js

megane9988 · 2025-05-08T04:44:27Z

I tested it.

OS: macOS 15.4.1（24E263）
Browser: Chrome 135.0.7049.115
IME: Google 日本語入力 ( https://www.google.co.jp/ime/ )

Test Steps

Adding a Details Block
Pressing the Enter key on the Summary text should toggle the content open and closed.
Pressing Enter + Shift on the Summary text should insert a line break without toggling the content.
Key operations while inputting Japanese (such as the Enter key and Space key) should be ignored, and the content should not toggle.

2025-05-08.13.35.24.mov

It worked well.

megane9988 · 2025-05-08T05:05:07Z

I tested it.

OS: macOS 15.4.1（24E263）
Browser: Safari 18.4 (20621.1.15.11.10)
IME: Google 日本語入力 ( https://www.google.co.jp/ime/ )

Test Steps

Adding a Details Block
Pressing the Enter key on the Summary text should toggle the content open and closed.
Pressing Enter + Shift on the Summary text should insert a line break without toggling the content.
Key operations while inputting Japanese (such as the Enter key and Space key) should be ignored, and the content should not toggle.

2025-05-08.14.01.21.mov

It also worked well.

megane9988 · 2025-05-08T05:13:50Z

I also tested using ことえり ( macOS default IME ) in both browsers (Chrome and Safari).
It also worked well.

2025-05-08.14.10.21.mov

yogeshbhutkar · 2025-05-08T06:50:58Z

I've incorporated all the feedback. A few follow-ups for the details block (separate from this PR):

We should add e2e coverage for drag-and-drop, as it previously caused a regression and remains a risk.
Keyboard navigation should also be possible when the block is collapsed. As of now, hidden blocks restrict the movement, and removing them might not be good for accessibility.
When inserting inner blocks, only the first shows the correct / placeholder (Type / to add a hidden block). Subsequent ones revert to the default. We should persist the template message while adding hidden blocks to avoid confusion. Coming out of details requires double enter, but the editor screen shows no feedback. Plus, if we are adding a hidden block, the message should always state so.

I'd like to know the opinion of others on this.

* Adds using inner block content wherever required * Adds an e2e test to verify list view auto expand and focus

Manual testing with IMEs showed that the HOF can safely be applied just to the key down events

yogeshbhutkar · 2025-06-02T04:36:57Z

This PR appears to have gone stale. Given that we've already completed the initial round of accessibility feedback and considering that this PR clearly enhances accessibility overall, I'd suggest proceeding with this PR. Any remaining or future accessibility concerns can be addressed as a follow-up.

cc: @t-hamano

t-hamano · 2025-06-02T06:00:52Z

This PR appears to have gone stale. Given that we've already completed the initial round of accessibility feedback and considering that this PR clearly enhances accessibility overall, I'd suggest proceeding with this PR. Any remaining or future accessibility concerns can be addressed as a follow-up.

I agree. This PR is much better than the trunk one, so if there are improvements to the label reading, let's address them in a follow-up.

joedolson · 2025-06-08T20:55:46Z

Thanks for moving forward with this! I definitely agree that this is much better than the trunk version, and it makes far more sense to ship the improvements and iterate, rather than continue to need to refactor the patch when it's gone out of date.

t-hamano · 2025-06-18T02:04:21Z

I am checking the PRs with the "Backport to WP Minor Release" label applied to clarify which PRs should be backported to the WordPress 6.8.2 release.

I believe this PR should be backported to the 6.8.2 release since it is a regression that occurred in 6.8.

joedolson · 2025-06-18T03:15:07Z

Agreed!

…selection to show up inner blocks (#70056) * fix: use key down to open/close the details block * chore: fix import order * fix: do not conditionally render details children * feat: expose `withIgnoreIMEEvents` to private api * feat: wrap handler within `withIgnoreIMEEvents` * chore(test): add e2e test for details block * fix: prevent space in rich-text from toggling details * chore: add CHANGELOG * fix: wrap key up handler with `withIgnoreIMEEvents` * chore(e2e): updated tests * Adds using inner block content wherever required * Adds an e2e test to verify list view auto expand and focus * chore: move `CHANGELOG` to unreleased * chore: revert usage of `withIgnoreIMEEvents` * fix: apply `withIgnoreIMEEvents` to key down Manual testing with IMEs showed that the HOF can safely be applied just to the key down events * feat: add visually hidden instructions for expanding/collapsing details * fix: add `aria-describedby` and add it to RichText * fix: update aria-label for RichText * fix: remove the usage of `aria-describedby` * chore: move `CHANGELOG` to unreleased Unlinked contributors: armandovias. Co-authored-by: yogeshbhutkar <[email protected]> Co-authored-by: Mamaduka <[email protected]> Co-authored-by: t-hamano <[email protected]> Co-authored-by: alexstine <[email protected]> Co-authored-by: joedolson <[email protected]> Co-authored-by: megane9988 <[email protected]>

…selection to show up inner blocks (WordPress#70056) * fix: use key down to open/close the details block * chore: fix import order * fix: do not conditionally render details children * feat: expose `withIgnoreIMEEvents` to private api * feat: wrap handler within `withIgnoreIMEEvents` * chore(test): add e2e test for details block * fix: prevent space in rich-text from toggling details * chore: add CHANGELOG * fix: wrap key up handler with `withIgnoreIMEEvents` * chore(e2e): updated tests * Adds using inner block content wherever required * Adds an e2e test to verify list view auto expand and focus * chore: move `CHANGELOG` to unreleased * chore: revert usage of `withIgnoreIMEEvents` * fix: apply `withIgnoreIMEEvents` to key down Manual testing with IMEs showed that the HOF can safely be applied just to the key down events * feat: add visually hidden instructions for expanding/collapsing details * fix: add `aria-describedby` and add it to RichText * fix: update aria-label for RichText * fix: remove the usage of `aria-describedby` * chore: move `CHANGELOG` to unreleased Unlinked contributors: armandovias. Co-authored-by: yogeshbhutkar <[email protected]> Co-authored-by: Mamaduka <[email protected]> Co-authored-by: t-hamano <[email protected]> Co-authored-by: alexstine <[email protected]> Co-authored-by: joedolson <[email protected]> Co-authored-by: megane9988 <[email protected]>

…selection to show up inner blocks (#70056) * fix: use key down to open/close the details block * chore: fix import order * fix: do not conditionally render details children * feat: expose `withIgnoreIMEEvents` to private api * feat: wrap handler within `withIgnoreIMEEvents` * chore(test): add e2e test for details block * fix: prevent space in rich-text from toggling details * chore: add CHANGELOG * fix: wrap key up handler with `withIgnoreIMEEvents` * chore(e2e): updated tests * Adds using inner block content wherever required * Adds an e2e test to verify list view auto expand and focus * chore: move `CHANGELOG` to unreleased * chore: revert usage of `withIgnoreIMEEvents` * fix: apply `withIgnoreIMEEvents` to key down Manual testing with IMEs showed that the HOF can safely be applied just to the key down events * feat: add visually hidden instructions for expanding/collapsing details * fix: add `aria-describedby` and add it to RichText * fix: update aria-label for RichText * fix: remove the usage of `aria-describedby` * chore: move `CHANGELOG` to unreleased Unlinked contributors: armandovias. Co-authored-by: yogeshbhutkar <[email protected]> Co-authored-by: Mamaduka <[email protected]> Co-authored-by: t-hamano <[email protected]> Co-authored-by: alexstine <[email protected]> Co-authored-by: joedolson <[email protected]> Co-authored-by: megane9988 <[email protected]>

t-hamano · 2025-07-08T10:40:33Z

This PR was cherry-picked into the wp/6.8 branch for the WP 6.8.2 release: #70557

yogeshbhutkar commented May 5, 2025

View reviewed changes

packages/block-library/src/details/edit.js Outdated Show resolved Hide resolved

yogeshbhutkar marked this pull request as ready for review May 5, 2025 11:16

yogeshbhutkar requested review from ajitbohra and fabiankaegy as code owners May 5, 2025 11:16

Mamaduka reviewed May 5, 2025

View reviewed changes

packages/block-library/src/details/edit.js Outdated Show resolved Hide resolved

t-hamano reviewed May 6, 2025

View reviewed changes

t-hamano added the Backport to WP Minor Release Pull request that needs to be backported to a WordPress minor release label May 6, 2025

t-hamano added this to WordPress 6.8.x Editor Tasks May 6, 2025

t-hamano moved this to 🔎 Needs Review in WordPress 6.8.x Editor Tasks May 6, 2025

yogeshbhutkar force-pushed the fix-70047/details-block branch from 5f6261a to fdea3e4 Compare May 7, 2025 06:41

t-hamano reviewed May 8, 2025

View reviewed changes

yogeshbhutkar force-pushed the fix-70047/details-block branch from fdea3e4 to c1154ba Compare May 8, 2025 05:47

yogeshbhutkar requested a review from t-hamano May 8, 2025 06:52

yogeshbhutkar added 14 commits June 2, 2025 08:55

feat: expose withIgnoreIMEEvents to private api

6e93dc7

feat: wrap handler within withIgnoreIMEEvents

6e496b3

chore(test): add e2e test for details block

a7464e9

fix: prevent space in rich-text from toggling details

60e3607

chore: add CHANGELOG

8d9a80f

fix: wrap key up handler with withIgnoreIMEEvents

66646d5

chore(e2e): updated tests

181a8ae

* Adds using inner block content wherever required * Adds an e2e test to verify list view auto expand and focus

chore: move CHANGELOG to unreleased

51ee2b9

chore: revert usage of withIgnoreIMEEvents

adac974

fix: apply withIgnoreIMEEvents to key down

e51bae0

Manual testing with IMEs showed that the HOF can safely be applied just to the key down events

feat: add visually hidden instructions for expanding/collapsing details

ade7309

fix: add aria-describedby and add it to RichText

25820e1

fix: update aria-label for RichText

4dc9cf0

fix: remove the usage of aria-describedby

f3d5d6b

yogeshbhutkar force-pushed the fix-70047/details-block branch from d4d2699 to f3d5d6b Compare June 2, 2025 03:28

chore: move CHANGELOG to unreleased

0b2c3af

t-hamano merged commit 0af268b into WordPress:trunk Jun 2, 2025
91 of 92 checks passed

github-actions bot added this to the Gutenberg 21.0 milestone Jun 2, 2025

t-hamano moved this from 🔎 Needs Review to ✅ Done in WordPress 6.8.x Editor Tasks Jun 11, 2025

t-hamano mentioned this pull request Jun 30, 2025

Cherry-picked bug fixes for 6.8.2 #70557

Merged

t-hamano removed the Backport to WP Minor Release Pull request that needs to be backported to a WordPress minor release label Jul 8, 2025

Details Block: Fix keyboard accessibility issues and allow list view selection to show up inner blocks #70056

Details Block: Fix keyboard accessibility issues and allow list view selection to show up inner blocks #70056

Uh oh!

Conversation

yogeshbhutkar commented May 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What, Why, and How?

Testing Instructions

Screencast

Uh oh!

Uh oh!

github-actions bot commented May 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Unlinked Accounts

Uh oh!

Mamaduka commented May 5, 2025

Uh oh!

Uh oh!

alexstine commented May 5, 2025

Uh oh!

yogeshbhutkar commented May 6, 2025

Uh oh!

alexstine commented May 6, 2025

Uh oh!

t-hamano left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

t-hamano commented May 6, 2025

Uh oh!

alexstine commented May 6, 2025

Uh oh!

t-hamano commented May 6, 2025

Uh oh!

joedolson commented May 6, 2025

Uh oh!

alexstine commented May 6, 2025

Uh oh!

t-hamano left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

t-hamano May 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

t-hamano May 8, 2025

Choose a reason for hiding this comment

Uh oh!

t-hamano May 13, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

megane9988 commented May 8, 2025

Test Steps

Uh oh!

megane9988 commented May 8, 2025

Test Steps

Uh oh!

megane9988 commented May 8, 2025

Uh oh!

yogeshbhutkar commented May 8, 2025

Uh oh!

yogeshbhutkar commented Jun 2, 2025

Uh oh!

t-hamano commented Jun 2, 2025

Uh oh!

Uh oh!

joedolson commented Jun 8, 2025

Uh oh!

t-hamano commented Jun 18, 2025

Uh oh!

joedolson commented Jun 18, 2025

Uh oh!

t-hamano commented Jul 8, 2025

Uh oh!

Uh oh!

yogeshbhutkar commented May 5, 2025 •

edited

Loading

github-actions bot commented May 5, 2025 •

edited

Loading

t-hamano left a comment •

edited

Loading

t-hamano May 8, 2025 •

edited

Loading