Feature/2.x/805 add default accessible label to templates using localgov prev next

[ctorgalson]

Re: #805

What does this change?

This makes several changes:

• documents existing but undocumented prop prevNextAttributes in prev-next.component.yml
• adds new prev_next_nav_aria_label prop for convenience (i.e. since this can also be set using prevNextAttributes)
• adds new prev_next_pre_content slot to add content before the Prev and Next links
• adds new prev_next_post_content slot to add content after the Prev and Next links
• uses prev_next_pre_content slot to add a labelled, visually-hidden heading to Blog template
• uses prev_next_pre_content slot to add a labelled, visually-hidden heading to Guides template
• uses prev_next_pre_content slot to add a labelled, visually-hidden heading to Publication template
• uses prev_next_pre_content slot to add a labelled, visually-hidden heading to Step by Step template

The new labels all use Drupal's stock pattern: an aria-labelledby attribute on the <nav> element referring to a visually-hidden child <h2> with a matching id attribute.

How to test

Test all of the following with demo content (not sure what module the Blog template requires):

• /publications/publications-cover-page-demo-content/petitions-scheme-publications-demo-content-1
  • browser: Prev-Next heading not visible
  • screenreader: h2 'Publication navigation' announced
• /order-copy-certificate/order-copy-certificate
  • browser: Prev-Next heading not visible
  • screenreader: h2 'Guides navigation' announced
• /adult-health-and-social-care/step-by-step/request-support-adult-step-step/choosing-how-manage-your
  • browser: Prev-Next heading not visible
  • screenreader: h2 'Step by step navigation' announced

How can we measure success?

• the various <nav> elements wrapping the Prev-Next links will now have an accessible text label by default

Have we considered potential risks?

For existing overrides of the template, a new aria-labelledby and h2 will appear:

• if the theme template uses the SDC and has not provided its own accessible label, the component will now have one; this is an improvement
• if the theme template uses the SDC has provided its own label using the only currently available method (aria-label), the <nav>'s aria-labelledby attribute plus its new label will override the theme's label; this is probably not serious but could be a problem where e.g. the new label string is not translated on a multilingual site

Images

n/a

Accessibility

• Tested with screen reader
• Navigable with keyboard
• Colour contrast passed
• The change doesn't use only colour to convey meaning

[tonypaulbarker]

We have some test failures that we need to check out.

Let's add to - "Have we considered potential risks?"
Will this break for someone who has overridden any of those templates and still includes the SDC?
Is there ever a case where we have two of these on a page and we have to consider duplicate IDs?

I think the answer to both of these will be 'no'.

[markconroy]

This looks really good, just a few small comments to look at and we're good to go.

[finnlewis]

@ctorgalson still wants to tweak something on this one before it's ready.

[ctorgalson]

@markconroy I think b8353f4 resolves the issues here if you want to give it another once-over.

[ctorgalson]

@tonypaulbarker

Let's add to - "Have we considered potential risks?"
Will this break for someone who has overridden any of those templates and still includes the SDC?
Is there ever a case where we have two of these on a page and we have to consider duplicate IDs?

I think the answer to both of these will be 'no'.

Taking the second first, since you and @markconroy suggested the same issue, I've added a random string to those generated ids. It will make them unique at the cost of using them as selectors. But since they're new, that's a non-issue.

For the first point, I tried to think how the change could break a child-theme, but I couldn't come up with a way:

• the changes to the component itself consist of a new prop and two new slots, so those won't affect anything,
• the changes to the instances using the SDC probably can't cause issues because a child-theme that implements the same templates has overridden them

But if anyone thinks of a way it could go wrong, I'm happy to try to address it in the code (and acknowledge the creativity!)

[markconroy]

LGTM