Option to set title for the Table of Contents block

[huubl]

What problem does this address?

There is no good way of setting a title for the Table of Contents block

What is your proposed solution?

Option to set a title for the Table of Contents block, something like this:

And this as HTML:

<nav class="wp-block-table-of-contents">
    <!-- POSSIBILITY TO ADD THIS: -->
    <h2 class="wp-block-table-of-contents__title">Contents on this page:</h2>
    <ol>
        <li>
            <a class="wp-block-table-of-contents__entry" href="https://test.local/#heading-page-1">heading page 1</a>
        </li>
        <li>
            <a class="wp-block-table-of-contents__entry" href="https://test.local/#heading-page-2">heading page 2</a>
        </li>
        <li>
            <a class="wp-block-table-of-contents__entry" href="https://test.local/#heading-page-3">heading page 3</a>
        </li>
    </ol>
</nav>

[afercia]

Thanks for reporting this issue.
It appears the TOC block needs some more improvements.

• By default it outputs a <nav> element. There's no way to label this element. When a page contains more than one <nav> element, they must be labelled to be distinguishable.
• Labelling can be done by teh means of an aria-label attribute, when there is no heading.
• Instead, when there is a heading, labelling should be implemented by the means of aria-labelledby pointing to the visible heading.

As an aside: an old version of the ARIA Authoring Practices used a directory role for the Table of contents. This role has been then deprecated in ARIA 1.2. In the same document, the 'Example 14' used a navigation rike fir. the Table of contents, which didn't help with clarity. ARIA 1.2 and the related Authoring practices don't provide any recommendation for Table of contents, as far as I can tell. A <nav> element seems reasonable, as long as it is labelled.

[Mamaduka]

Related #51129.

[alexstine]

Honestly, table of contents with navigation landmark can sometimes be more noise then it is truly worth. I am very much on the fense about landmarks inside landmarks because once you enter a nav inside main, there is no way to get back to main as the next logical landmark is the footer on most sites or sometimes aside.

[00travelgirl00]

@alexstine thats an intresting info. Just out of curiosity: Would you prefer a nav to stand alone or to be inside a aside? Question is not related to tables, but for post-navigtions for example.

[alexstine]

Post navigation really needs a navigation landmark but it is generally near the end of the main content so it is less of a problem. This is a clear example of how screen readers should do better but I'm not really sure how the future looks there.

[jhmonroe]

@afercia +1 yes and!

Aside from the TOC, the block editor doesn't seem to output a TITLE for any Navs. It uses the Navigation name "ie: Primary Menu" as the aria-label which is great.

See image below of what is shown in the HTML5 outline (ie: in inspector or when checking using the HTML5 Outliner browser extension.

Here I have page title, Nav, then a series of Headings in the main content:

Title attributes are able to be set in the right sidebar for individual items inside the Nav, but not for the overall Nav itself.

A simple solution for the overarching Nav would be to pull the Nav name as the Title attribute. The same way it does for aria-label.

Should this be a separate ticket or is this issue for Nav & TOC the same?

After searching all a11y tickets for nav title I came across this interesting issue (#68735) addressed by @t-hamano and others about how these things are pulled/saved/used automatically for aria-label. Perhaps this will inform the approach taken for the TITLE attribute for all Navs.

Thanks for reporting this issue. It appears the TOC block needs some more improvements.

• By default it outputs a <nav> element. There's no way to label this element. When a page contains more than one <nav> element, they must be labelled to be distinguishable.
• Labelling can be done by teh means of an aria-label attribute, when there is no heading.
• Instead, when there is a heading, labelling should be implemented by the means of aria-labelledby pointing to the visible heading.

As an aside: an old version of the ARIA Authoring Practices used a directory role for the Table of contents. This role has been then deprecated in ARIA 1.2. In the same document, the 'Example 14' used a navigation rike fir. the Table of contents, which didn't help with clarity. ARIA 1.2 and the related Authoring practices don't provide any recommendation for Table of contents, as far as I can tell. A <nav> element seems reasonable, as long as it is labelled.

[t-hamano]

Should this be a separate ticket or is this issue for Nav & TOC the same?

Issues regarding other blocks are better discussed in separate issues.

[jhmonroe]

Should this be a separate ticket or is this issue for Nav & TOC the same?

Issues regarding other blocks are better discussed in separate issues.

Both are generated in NAV tag, no?

[t-hamano]

Both are generated in NAV tag, no?

That's true, but those aren't the only two blocks that have nav elements. Furthermore, each block has slightly different implementations. The broader the scope of the issue, the more difficult it becomes to understand what needs to be addressed. As the title of this issue suggests, I recommend that we limit discussion to the ToC block in this issue.