Block API: Improve ariaLabel block support

[t-hamano]

Issues and PRs related to this discussion:

• Allow defining an aria-label in group blocks #41744
• Navigation: Add ariaLabel block support #54418
• Navigation block: aria-label disappears after any change to the pattern the block belongs to #68719
  • fix: Adds ariaLabel attribute to navigation block #68735
• Add nav to the selectable elements for the group block #67407
  • Group: Make nav element selectable and add UI for ariaLabel #68611
• Fix: Accessibility issue with links listing blocks. #(64051) #66866 (Add ariaLabel block support to the Tag Cloud block)

What problem does this address?

Adding ariaLabel block support to a block makes it possible to set the aria-label attribute internally - it does not expose a UI for setting this attribute.

This attribute can be injected into a block HTML or theme template like this:

<!-- wp:navigation {"ref":1,"ariaLabel":"My Navigation"} /-->

<!-- wp:navigation {"ariaLabel":"<?php esc_attr_e( 'Privacy', 'mny-theme' ); ?>"} -->
	<!-- wp:navigation-link {"label":"<?php esc_html_e( 'Privacy Policy', 'twentytwentyfour' ); ?>","url":"#"} /-->
	<!-- wp:navigation-link {"label":"<?php esc_html_e( 'Terms and Conditions', 'twentytwentyfour' ); ?>","url":"#"} /-->
	<!-- wp:navigation-link {"label":"<?php esc_html_e( 'Contact Us', 'twentytwentyfour' ); ?>","url":"#"} /-->
<!-- /wp:navigation -->

The schema for this support references the aria-label attribute on HTML elements, but dynamic blocks do not save HTML to the database, so when you edit and save the content or template, the aria-label value is lost because it cannot be referenced.

Especially for the Navigation block, i.e. nav element, the loss of aria-label attribute values ​​is a big problem. We need to find a way to solve this problem.

What is your proposed solution?

The three approaches I can think of are:

1. Add ariaLabel "attribute" in addition to block support

The ariaLabel block support respects existing attribute definitions. By explicitly defining the ariaLabel attribute in a dynamic block, the value will not be lost as it will be preserved as part of the comment delimiter (Related discussion).

2. Extend block support

Currently, the value type of this block support is a boolean value. We may be able to extend this to allow us to decide how we want to reference the value. Something like this:

{
	"name": "core/navigation",
	"supports": {
		"ariaLabel": "delimiter"
	}
}

This approach was also attempted with anchor support (You can see the series of efforts at #51402.).

3. Change the block support schema

We could also change the block support schema itself, which means we always store values ​​as part of the comment delimiter, rather than referencing the stored content.

This approach might require us to add a block deprecation to blocks that already have this block support, and it might affect developers who already use this block support.

In the past we've run into issues with broken blocks when changing the schema for anchor support. See #48232 for more details.

Other suggestions

Although not directly related to this support failure, it's also worth discussing whether we should expose a UI for editing the aria-label attribute by default.

cc @Mamaduka @fabiankaegy @afercia @carolinan @aaronrobertshaw @talldan

[fabiankaegy]

Thanks for putting this together :)

The one thing I don't understand is why we need to store the aria-label attribute in the client side generated block markup at all? Why could we not handle it like other dynamic values and only store it in the HTML comment and then use the HTML_Tag_Processor on the render_block hook to dynamically inject it into the markup? 🤔

Regarding the block support becoming more granular. I think it would be nice to also have some options to enable / disable a UI for the setting. Today the UI is not coming from the block support which as far as I know is unique to this support. All others have an UI attached to the support.

[t-hamano]

The one thing I don't understand is why we need to store the aria-label attribute in the client side generated block markup at all?

Oh, I missed that. There are challenges to overcome, but I think it's definitely possible. I've added a "3. Change the block support schema" section to this issue.

[t-hamano]

3. Change the block support schema

We could also change the block support schema itself, which means we always store values ​​as part of the comment delimiter, rather than referencing the stored content.

This approach might require us to add a block deprecation to blocks that already have this block support, and it might affect developers who already use this block support.

I discovered that the customClassName support already had a process in place to properly handle this problem:

https://github.com/WordPress/gutenberg/blob/fix/get-allowed-blocks/packages/blocks/src/api/parser/fix-custom-classname.js

Using this logic, we may be able to make this support work for dynamic blocks as well, by injecting the ariaLabel value into the HTML comment without breaking the block.

Furthermore, this approach may also be applicable to anchor support: #51402

[t-hamano]

This comment made me realize that I was missing some server-side processing for the ariaLabel support.

For example, adding this support in the Archives block would result in an error like this:

API response:

{
    "code": "rest_invalid_param",
    "message": "Invalid parameter(s): attributes",
    "data": {
        "status": 400,
        "params": {
            "attributes": "ariaLabel is not a valid property of Object."
        },
        "details": {
            "attributes": {
                "code": "rest_additional_properties_forbidden",
                "message": "ariaLabel is not a valid property of Object.",
                "data": null
            }
        }
    }
}

[Mamaduka]

I think similar "global" attributes also require server-side registration. See #40468 and #54426.

[t-hamano]

I tried to add server-side support in this branch, but ran into some issues with backwards compatibility.

We need to support the aria-label attribute in the get_block_wrapper_attributes() function to complete the ariaLabel block support. However, the default allowed attributes are hard-coded. Additionally, this function cannot be overridden/filtered from the Gutenberg plugin side.

This means that ariaLabel support is not fully functional in older versions of core + the latest Gutenberg, meaning developers need to explicitly include aria-label in the arguments ($extra_attributes) when using the get_block_wrapper_attributes() function:

$wrapper_attributes = get_block_wrapper_attributes( array( 'aria-label' => $attributes['aria-label'] ) );

That said, this support wasn't perfect from the start, so we might not need to worry about these backwards compatibility issues. What do you think?

[Mamaduka]

The anchor support had similar issues.

I think blocks had to explicitly pass aria-label as to get_block_wrapper_attributes before recent changes as well. Your fix had not regressed that.