Summary

Added the ability to customize which headings will be pulled into the in-page navigation link list.
Use the new data-heading-elements attribute to designate the heading levels that should be included in the component.

The headings should be listed with a space in between. Here is a sample implementation:

<aside 
    class="usa-in-page-nav" 
    data-heading-elements="h3 h4"
</aside>

If this attribute is not added to the component or has an empty value, it will default to pulling h2 and h3 headers.

Breaking change

This is not a breaking change.

Related issue

Closes #5030

Related pull requests

Changelog PR

This work originated in #5034.

Preview link

In-page navigation - custom header selector test

Problem statement

The in-page navigation component is hard-coded to pull all h2 and h3 headers from the designated main content region. However, there are valid use cases where teams would want to control which headings will be included in their component.

Solution

Creating data-heading-elements attribute will allow users select which header levels they want to include in the component link list. This attribute can accept multiple values (between h1-h6), each separated by a space. If the attribute is not added or is left blank, the component will pull the default h2 and h3 headers.

Testing and review

• Confirm the attribute name is intuitive and follows convention
• Confirm the correct headings are pulled when the data-heading-elements attribute is present
• Confirm that bolded text styles are added to the top-level header in the link list. All other headers in the link list should receive a normal font weight.
• Confirm code follows convention
• Confirm the storybook controls make sense

To test in Storybook:

1. Open the In-page navigation - test custom header selector page
2. In the controls, choose different selections in the "Include these headers in link list" control. Reload the page after each selection change.
3. Confirm that only the expected headers are pulled into the in-page navigation link list.
   1. "Default" should pull h2 and h3 headers
   2. "All" should pull h1-h6 headers
   3. "Error" should show an error in the console and not add any headers to the link list
   4. "Empty" should pull h2 and h3 headers
   5. Single header types should pull only the selected header type
4. Confirm that bolded text styles are added to the highest-level header in the link list. All other headers should have a normal font weight.

To test in a project:

1. Install this branch and copy the updated JS into your project
2. Add the following test markup

   <div class="usa-in-page-nav-container">
     <aside class="usa-in-page-nav"
       data-heading-elements="h2">
     </aside>
     <main>
       <h1>H1 heading</h1>
       <h2>H2 heading</h2>
       <h3>H3 heading</h3>
       <h4>H4 heading</h4>
       <h5>H5 heading</h5>
       <h6>H6 heading</h6>
     </main>
   </div>

3. Change the value of data-heading-elements to any mix of headings and confirm that the link list pulls the correct headings.