Try better block labels #18132

talldan · 2019-10-28T10:37:40Z

Description

Introduces a new __experimentalLabel( attributes, context ) function to the block api. The aim of this is to provide more context about a particular block which can be currently surfaced in two ways:

Instead of displaying the Block Title in the Block Navigator, it displays some content from the block. This is currently being used by the Navigation Block to let users differentiate their nav links:
Providing more contextual information to screen readers, this might be paragraph text or an image caption so that users can be more sure of the block content.

The new __experimentalLabel also replaces the mobile function __experimentalGetAccessibilityLabel and those labels now work across both mobile and web.

The blocks package now also has two new convenience functions for retrieving these labels:

__experimentalGetBlockLabel - returns just the output of the __experimentalLabel.
__experimentalGetAccessibleBlockLabel - returns some extra information useful to screen readers like the block title and the position in the block list.

Those functions will also strip any html (i.e. from formatting) from the labels.

How has this been tested?

Additional unit testing.

Manual testing:

Add a Navigation Block (make sure it's enabled as an experimental feature).
Ensure the navigation block has menu items.
View the Block navigator.
Observe the block labels for menu items
Inspect the block mover for a menu item using dev tools
Observe the screen reader text includes the new block label
Inspect the menu item's block wrapper
Observe the aria label includes the new block label

Other blocks worth testing for the aria-label - Paragraph, Heading, More, Image.

Types of changes

New feature (non-breaking change which adds functionality)

Checklist:

My code is tested.
My code follows the WordPress code style.
My code follows the accessibility standards.
My code has proper inline documentation.
I've included developer documentation if appropriate.

talldan · 2019-10-28T10:41:48Z

packages/blocks/package.json

@@ -33,6 +33,7 @@
 "@wordpress/html-entities": "file:../html-entities",
 "@wordpress/i18n": "file:../i18n",
 "@wordpress/is-shallow-equal": "file:../is-shallow-equal",
+ "@wordpress/rich-text": "file:../rich-text",


I imagine adding RichText as a dependency here is something to avoid. At the moment this is used to strip formatting/html from the attribute, but an alternative could be to add something to @wordpress/dom that does this.

Yes, this is definitely something that should happen. I consider it a blocker personally.

@ellatrix - can you help to extract the related logic from @wordpress/rich-text?

I've now added stripHTML to the dom package in 7bf4683, and I'm using that.

For the implementation of that function I used some stack overflow driven development:
https://stackoverflow.com/questions/822452/strip-html-from-text-javascript/47140708#47140708

As far as I can tell this works across platform. MDN has a ? against mobile safari in its browser support chart (https://developer.mozilla.org/en-US/docs/Web/API/DOMParser), but it worked in my simulator.

mtias · 2019-10-28T10:50:43Z

I don't think we need the "Menu Item" prefix there when we are already under a "Navigation Menu" block.

gziolo · 2019-10-28T10:55:49Z

packages/block-editor/src/components/block-list/block.js

- const blockLabel = sprintf( __( 'Block: %s' ), blockType.title );
- // The block as rendered in the editor is composed of general block UI
- // (mover, toolbar, wrapper) and the display of the block content.
+ const blockLabel = sprintf( __( 'Block: %s' ), __experimentalGetBlockLabel( blockType, attributes, ' - ' ) );


@hypest @koke @Tug - it didn't take a lot of time to see this experimental method useful in the web context as well :)

Hmm it is a different method though. The one used on mobile is __experimentalGetAccessibilityLabel, input parameters and the content returned is different as well. __experimentalGetAccessibilityLabel is for constructing a custom description for the block to be read by VoiceOver. It can be a long description too. For example it reads the caption and the alt text for the image block. AFAIU __experimentalGetBlockLabel is used in places where a short description of block is needed.

It would be great to have one method which would cover all those use cases through some sort of context. In your case it could be:

getBlockLabel( clientId, { context: 'screen-reader` } );

Sounds like a very good idea.

Yep, they're a bit different at the moment. I'll have a look into it and see what the options are for consolidating the two.

The Image block and Paragraph block descriptions could be pretty long for accessibility labels, but I think the others could work pretty well for both accessible and visual block labels.

This is usually not a problem if there is no important information after that long text. So if block type, level, coordinates etc., all come first, and then the actual text is last, users can always interrupt speech once they know what that block is about. One could artificially limit that character count to 100 or 150, but that runs the potential of not being enough for some.

The friends at Gutenberg Mobile already do this block labeling in their navigation layer, at least for VoiceOver on iOS. Perhaps look at what they're doing and mirror that?

I've consolidated the functionality now so that both mobile and web code uses __experimentalGetAccessibilityLabel and it should return the same format as the mobile function produced previously. I haven't tested it beyond unit tests for the function, though.

@pinarol Let me know what you think.

I think there's merit in what @gziolo proposes for the context of the labels. At the moment there's only the navigation link block that has a visual label, but others like the image, paragraph and heading block might require a slightly different label (or in some cases, no label at all).

@MarcoZehe Thanks for the feedback! For some reason I didn't see your message until after the one I posted above.

I've kept the format of the text broadly the same across web and mobile, it follows the pattern established on mobile. Having said that the labels for each block themselves still need to be implemented separately on web as they're in different files. I plan to look at some of this next.

@talldan this is looking good overall. But there's just one thing that sounds odd when VoiceOver is on and it should be fixed. If there's an unrecognized block the screen reader says 'Unrecognized block block', so there's an extra block at the end. I think it is related with the removal of this logic:

if ( name === 'core/missing' ) { // is the block unrecognized? blockName = title; }

Missing blocks are already coming with 'Unrecognized Block' title.

The rest looks good to me.

Cool, thanks for spotting that @pinarol!

noahtallen · 2019-10-29T02:55:40Z

packages/blocks/src/api/utils.js

+ const richTextValue = create( { html: attributes[ displayNameAttribute ] } );
+ const formatlessDisplayName = getTextContent( richTextValue );
+
+ return `${ blockTitle }${ separator }${ formatlessDisplayName }`;


What if I wanted to avoid using the block title and separator format? Currently, we are working on some blocks that look like this:

Before:

After:

I think we'd like to just use "Header" instead of displaying "Template: Header". To us, the "Template" block (Which is dubiously named. One shouldn't trust what they think "template" means! 😆) is just a transparent wrapper around some other blocks and isn't really meant to be understood by or visible to the user.

Good to know. A previous proposal has been to use a function or component to create the label, which is useful if the label is created from multiple attributes.

__experimentalDisplayName( { attributes, blockType } ) { return `${ blockType.title }: ${ attributes.label }` }

My concern would be a lack of consistency across blocks. Also where this is used as an aria-label, the block type might make sense, whereas in the navigator it might not.

I suppose this could be customisable by getBlockLabel:

getBlockLabel( blockType, blockAttributes, { includeBlockTitle: false } );

So that aria-labels can include the block titles, but the navigator doesn't.

How about the 3rd param is more general and contains properties like:

{ context: 'block-navigation', format: 'concise', }

Then each block's author could decide how to code the label depending on the properties passed. We could always provide a default handler which works fine in 90% of cases.

I'm still doubtful of the use case in general. We are not going to be using "Menu Item: Label" for navigation, for example. If we'd also not use it for template parts, we might be preemptively overcomplicating things here.

I'm thinking the best approach might be to have two functions getAccessibleBlockLabel and getVisualBlockLabel. The former can include the block title for some extra context. Thoughts?

I've rebased and made the change described above, though it seems at the moment there's a bug with the nav block in master, so hard to test it.

mtias · 2019-11-08T12:29:04Z

For Navigation block I think we should keep it as it is, which is much easier to browse in the navigator.

MarcoZehe

Left a spelling error suggestion.

packages/block-editor/src/components/block-list/block.js

packages/block-editor/src/components/block-mover/index.js

packages/blocks/src/api/index.js

packages/blocks/src/api/test/utils.js

packages/blocks/src/api/utils.js

talldan · 2019-12-04T03:28:02Z

Thanks for spotting that @MarcoZehe!

youknowriad · 2020-01-10T10:55:34Z

packages/block-editor/src/components/block-list/block.js

+ const [ blockLabel, setBlockLabel ] = useState( '' );
+
+ useEffect( () => {
+ const timeoutId = setTimeout( () => {


Why a timeout?

Probably because of https://github.com/WordPress/gutenberg/pull/18132/files#r359241034

Looks like this is being removed in #19597

youknowriad · 2020-01-10T10:57:14Z

packages/block-editor/src/components/block-list/block.js

@@ -560,6 +583,7 @@ const applyWithSelect = withSelect(
 hasFixedToolbar: hasFixedToolbar && isLargeViewport,
 isLast: index === blockOrder.length - 1,
 isNavigationMode: isNavigationMode(),
+ index,


We removed this explicitely some time ago for performance reasons. Adding this prop rerenders the block everytime a precedent block is removed in the list, this can be harmful for long posts. Also, We should favor the inner useSelect instead of adding new props to this component.

Looks like this is being removed in #19597

youknowriad · 2020-01-10T10:58:20Z

packages/block-editor/src/components/block-list/block.js

+
+ return blockLabel;
+};
+
 function BlockListBlock( {


This is one of the most central components of our codebase and changes here can have big performance impacts, so, a sanity check (running performance tests) would be good (with and without the PR.

youknowriad · 2020-01-10T15:38:49Z

packages/blocks/src/api/utils.js

+ *
+ * @return {string} The block label.
+ */
+export function getAccessibleBlockLabel( blockType, attributes, position, direction = 'vertical' ) {


We've moving slowly away from functions that take blockType, and attributes in favor of the whole block object. I also feel like position and direction are not necessary and can be retrieved from state if this is becomes more a selector or a component instead of a global function. cc @aduth

We've moving slowly away from functions that take blockType, and attributes in favor of the whole block object.

Right. It already raises the question: What if I wanted the label to change depending on the inner blocks? How would that be implemented today with this interface?

Also, there's some inconsistency between this utility and the others in the file; where most all of the other utilities will accept either a block type (object) or a block name (string).

I mentioned it above in another comment, but I'm now looking at moving this out of the blocks package into block-editor as selectors.

the api would be getAccessibleBlockLabel( clientId, direction ) and the selector implementation could be responsible for grabbing any other data.

aduth · 2020-01-10T16:36:51Z

packages/blocks/src/api/utils.js

+ // Strip any HTML (i.e. RichText formatting) before returning.
+ return stripHTML( label );


Can't we make this the responsibility of the block implementation in generating the label? In other words, force the block to return a plain string. There, we already have some availability of the rich-text tooling. I see there was some prior discussion about rich-text being used here, but if we would put it on the block to return, then it doesn't need to be a dependency here.

I'm not sure there exists a utility already for generating a plain-text string from a RichText value, but it would seem to align with some of the existing utilities (toTree, toDOM, toHTMLString). Something like a toPlainString (cc @ellatrix).

I am a bit worried about introducing something like a stripHTML, both for these reasons above in that it ideally should not be necessary, but also because it could become a security weakness† or a source of poor performance.

† Not to say that it's vulnerable today in how it's used, notably because we're not dangerouslySetInnerHTML, but it's one of those things where we should try to avoid this altogether if we can, for fear of future mis-use, browser inconsistencies, etc.

So I had some feedback that the __experimentalLabel api on the block needed some thought. It looks like the option is to split it into two separate things:

This for the accessibility label:

__experimentalGetAccessibilityLabel( attributes ) { return attributes.title }

and this for the visual label that might appear in the block navigator:

__experimentalLabel: 'title' // title is the name of the attribute

So it looks like the option of moving this responsibility to the block might not be possible for the latter. One option is something that @youknowriad mentioned in another comment, is that these could become selectors in the block-editor package. I started working on that, and I think that might be a good option.

Then I could change stripHTML to toPlainString (and move it to rich-text) as suggested.

aduth · 2020-01-10T16:38:47Z

packages/blocks/src/api/utils.js

+ *
+ * @return {string} The block label.
+ */
+export function getAccessibleBlockLabel( blockType, attributes, position, direction = 'vertical' ) {


We've moving slowly away from functions that take blockType, and attributes in favor of the whole block object.

Right. It already raises the question: What if I wanted the label to change depending on the inner blocks? How would that be implemented today with this interface?

Also, there's some inconsistency between this utility and the others in the file; where most all of the other utilities will accept either a block type (object) or a block name (string).

aduth · 2020-01-10T16:42:08Z

packages/blocks/src/api/utils.js

+ */
+export function getBlockLabel( blockType, attributes, context = 'visual' ) {
+ const {
+ __experimentalLabel: getLabel,


Was it intentional that this was called __experimentalLabel and not __experimentalGetLabel, as the deconstructed assignment would imply that its stable form might take?

I would expect either one of the following:

Suggested change

__experimentalLabel: getLabel,

__experimentalGetLabel: getLabel,

Suggested change

__experimentalLabel: getLabel,

__experimentalLabel: label,

While I'd grant that most functions of a block type don't have these sorts of prefixes ("get"), the reason for that as I'd see it is that they're all (to my knowledge) already in verb forms anyways: "save", "edit", etc.

👍 Yep, I wasn't sure about this, thanks for clarifying.

aduth · 2020-01-10T16:47:25Z

packages/blocks/src/api/utils.js

+ *
+ * @param {Object} blockType The block type.
+ * @param {Object} attributes The values of the block's attributes.
+ * @param {Object} context The intended use for the label.


This isn't an object. If we documented this as an union type of string literals, I think it would have helped clarify (both for us as the implementers and the future consumers) which sorts of values we're expecting to be supported.

Suggested change

* @param {Object} context The intended use for the label.

* @param {"visual"|"accessibility"} context The intended use for the label

It is a bit confusing for me though in how we expect block implementers to be handling this. Even in the implementations we've revised so far, we're only ever handling the "accessibility" case. So what's the point of "visual"? And how would we expect to treat the undefined return value from those implementations? Should have gone ahead and returned a value for the "visual" context for existing block revisions? (Getting a bit of YAGNI vibes here)

I'm now working on having two separate params in the block definition, so this won't be an issue any longer.

I'm now working on having two separate params in the block definition, so this won't be an issue any longer.

What about the second part of my comment, in which I question whether we even need two?

It is a bit confusing for me though in how we expect block implementers to be handling this. Even in the implementations we've revised so far, we're only ever handling the "accessibility" case. So what's the point of "visual"? And how would we expect to treat the undefined return value from those implementations? Should have gone ahead and returned a value for the "visual" context for existing block revisions? (Getting a bit of YAGNI vibes here)

ellatrix · 2020-01-13T12:08:40Z

I'm not super fond of the new label on the block wrapper elements, since we'll eventually remove this wrapper element entirely. Additionally, this seems more useful in navigation mode, where it's not added at all.

MarcoZehe · 2020-01-13T12:10:49Z

Yes, indeed these make the most sense on the buttons that get focus in navigation mode. Sorry I didn't catch that during my review. I believe moving these in a follow-up PR should be feasible, right?

ellatrix · 2020-01-13T12:12:54Z

@MarcoZehe Yes, no worries, it's good to improve gradually. :)

talldan · 2020-01-15T11:39:59Z

@aduth @youknowriad @ellatrix @MarcoZehe I've addressed most of the remaining feedback in #19664. Thanks for the reviews and patience!

jorgefilipecosta · 2020-02-04T14:19:07Z

Hi @talldan, is this API ready to be stabilized in WordPress 5.4?

talldan · 2020-02-06T03:25:10Z

Hi @jorgefilipecosta, at the moment there's still some follow-up work to do on on these APIs, so I think they'll have to remain experimental for 5.4.

talldan requested review from ellatrix, gziolo and youknowriad as code owners October 28, 2019 10:37

talldan self-assigned this Oct 28, 2019

talldan requested review from noisysocks, tellthemachines, draganescu, shaunandrews and mtias October 28, 2019 10:38

talldan added [Feature] List View Menu item in the top toolbar to select blocks from a list of links. [Package] Blocks /packages/blocks [Focus] Accessibility (a11y) Changes that impact accessibility and need corresponding review (e.g. markup changes). labels Oct 28, 2019

talldan commented Oct 28, 2019

View reviewed changes

gziolo reviewed Oct 28, 2019

View reviewed changes

talldan mentioned this pull request Oct 29, 2019

Try setting a block display name for the Block Navigator. #17519

Merged

5 tasks

noahtallen reviewed Oct 29, 2019

View reviewed changes

gziolo mentioned this pull request Oct 30, 2019

Audit Experimental APIs #17743

Closed

talldan mentioned this pull request Nov 8, 2019

Add block navigator movers #18014

Merged

5 tasks

ZebulanStanphill mentioned this pull request Nov 29, 2019

Try: Remove dashed outlines for child and parent blocks. #18105

Merged

talldan force-pushed the try/consistent-block-label branch from a5b655a to 619331a Compare December 3, 2019 07:53

MarcoZehe reviewed Dec 3, 2019

View reviewed changes

talldan force-pushed the try/consistent-block-label branch from bfdf709 to 07e2ee0 Compare December 4, 2019 07:53

talldan requested review from ajitbohra, jorgefilipecosta and Soean as code owners December 4, 2019 07:53

talldan added the [Status] In Progress Tracking issues with work in progress label Dec 5, 2019

talldan force-pushed the try/consistent-block-label branch from 07e2ee0 to 516c05c Compare December 11, 2019 07:24

talldan and others added 3 commits January 10, 2020 16:45

Update expected label in e2e test

58f90d0

Update test func to be dynamic

97b2c8f

Fix a comment typo that the speech synthesizer stumbled over.

40ae5cd

talldan force-pushed the try/consistent-block-label branch from ed80aa9 to 40ae5cd Compare January 10, 2020 08:46

draganescu merged commit a8f43fa into master Jan 10, 2020

draganescu deleted the try/consistent-block-label branch January 10, 2020 10:22

youknowriad reviewed Jan 10, 2020

View reviewed changes

aduth reviewed Jan 10, 2020

View reviewed changes

koke mentioned this pull request Jan 13, 2020

Update Gutenberg to master wordpress-mobile/gutenberg-mobile#1771

Merged

2 tasks

ellatrix mentioned this pull request Jan 13, 2020

Breadcrumb: add accessibility label #19597

Merged

6 tasks

talldan mentioned this pull request Jan 15, 2020

Address PR feedback on block labels #19664

Closed

6 tasks

aduth mentioned this pull request Jan 17, 2020

DOM: Mark stripHTML as unstable #19725

Merged

ellatrix added this to the Gutenberg 7.3 milestone Jan 20, 2020

jorgefilipecosta added the Needs Dev Note Requires a developer note for a major WordPress release cycle label Feb 4, 2020

pinarol mentioned this pull request Mar 10, 2020

Revisit __experimentalGetAccessibilityLabel wordpress-mobile/gutenberg-mobile#1559

Closed

youknowriad removed the Needs Dev Note Requires a developer note for a major WordPress release cycle label Apr 8, 2020

draganescu mentioned this pull request Apr 23, 2020

Show block ID attribute on navigator #16307

Closed

Copons mentioned this pull request Jul 13, 2020

Use blockLabel for BlockTitle component #23847

Merged

6 tasks

mcsf mentioned this pull request Dec 4, 2020

Display Block Information by matching block variations #27469

Merged

6 tasks

gziolo mentioned this pull request Feb 16, 2021

Incorporate getBlockLabel into useBlockDisplayInformation #29010

Closed

7 tasks

talldan mentioned this pull request Oct 14, 2021

stripHTML - preserve leading and trailing spaces and strip script and on* attributes #35539

Merged

7 tasks

		// Strip any HTML (i.e. RichText formatting) before returning.
		return stripHTML( label );

	__experimentalLabel: getLabel,
	__experimentalGetLabel: getLabel,

	* @param {Object} context The intended use for the label.
	* @param {"visual"\|"accessibility"} context The intended use for the label

Try better block labels #18132

Try better block labels #18132

Conversation

talldan commented Oct 28, 2019 • edited Loading

Description

How has this been tested?

Types of changes

Checklist:

talldan Oct 28, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mtias commented Oct 28, 2019

Choose a reason for hiding this comment

pinarol Nov 8, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

talldan Dec 4, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gziolo Oct 29, 2019 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mtias commented Nov 8, 2019

MarcoZehe left a comment

Choose a reason for hiding this comment

talldan commented Dec 4, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

talldan Jan 15, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ellatrix commented Jan 13, 2020

MarcoZehe commented Jan 13, 2020

ellatrix commented Jan 13, 2020

talldan commented Jan 15, 2020

jorgefilipecosta commented Feb 4, 2020

talldan commented Feb 6, 2020

talldan commented Oct 28, 2019 •

edited

Loading

talldan Oct 28, 2019 •

edited

Loading

pinarol Nov 8, 2019 •

edited

Loading

talldan Dec 4, 2019 •

edited

Loading

gziolo Oct 29, 2019 •

edited

Loading

talldan Jan 15, 2020 •

edited

Loading