USWDS - Documentation page: Improve backwards compatibility with sidenav order

[mejiaj]

Summary

Introduced a fallback for Documentation sidenav changes. A new setting $theme-sidenav-reorder allows users to reorder the sidenav to avoid visual regressions.

Caution

Setting $theme-sidenav-reorder: true has a negative impact on users of assistive technologies.

Breaking change

This is not a breaking change.

Related issue

Closes #5807.

Related pull requests

Changelog entry added to uswds/uswds-site#2495.

Preview link

Preview link: Test Documentation Reorder ⋅ Storybook

Problem statement

Without a fallback, users who update to 3.8.0 will have to update all their templates to follow new guidance. This new setting allows for incremental adoption towards this new recommendation.

Solution

This pull request adds a new component theme setting for those who are unable to make that change right now. You can do that by setting $theme-sidenav-reorder: true in theme settings.

This will give you a warning on compile and suggesting the new recommendation above.

New recommendation from #5794

#5794 introduced a potentially breaking change that requires a markup update. We recommend including a duplicate sidenav and toggling visibility based on breakpoints.

Include a duplicate sidenav and ensure the utility classes are correct. The example below shows a before/after.

<div class="grid-container">
  <div class="grid-row grid-gap">
-   <div class="usa-layout-docs__sidenav">
+   <!-- One of two sidenav's only shown in desktop breakpoints. --> 
+   <div class="usa-layout-docs__sidenav display-none desktop:display-block desktop:grid-col-3">
      {{ SIDENAV_MARKUP }}
    </div>
-   <main class="usa-layout-docs__main desktop:grid-col-9 usa-prose usa-layout-docs" id="main-content">
+   <main class="desktop:grid-col-9 usa-prose usa-layout-docs" id="main-content">
      {{ MAIN_CONTENT }}
    </main>
  </div>
+ <!-- New duplicate section only shown on mobile. -->
+  <div class="usa-layout-docs__sidenav desktop:display-none">
+    {{ SIDENAV_MARKUP }}
+  </div>
</div>

Approach

Possible limitations

The desktop breakpoint in _usa-layout-docs.scss:20 is fixed and users don't have an easy way of overriding this.

uswds/packages/usa-layout-docs/src/styles/_usa-layout-docs.scss

Lines 20 to 23 in 17600ba

	@include at-media("desktop") {
	@include grid-col(3);
	order: 0;
	}

Major changes

• New component theme setting $theme-sidenav-reorder: false !default.
• New test story & storybook control

Testing and review

There's a new test story that allow you to toggle and compare behaviors. Toggle Reorder with CSS to test old behavior.

Testing checklist

• Zero regressions in HTML output - npm run build:html.
• Documentation page by default has two sidenavs that toggle display based on breakpoint.
• Documentation page test can revert to old behavior on TRUE via StorybookJS control.
• New reorder setting in _settings-components.scss.
• New setting is FALSE by default.
• New setting reorders sidenav on TRUE and provides a warning on compile.

Todo

• Write SASS notification

[mahoneycm]

Loving this fix! Adds great flexibility to our users.

Testing checklist

• Zero regressions in HTML output - npm run build:html.
• Documentation page by default has two sidenavs that toggle display based on breakpoint.
  • Inspecting markup shows nav elements before main
• Documentation page test can revert to old behavior on TRUE via StorybookJS control.
• New reorder setting in _settings-components.scss.
• New setting is FALSE by default.
• New setting reorders sidenav on TRUE and provides a warning on compile.
• Installing and testing on sandbox works as expected
  • Warning on compile
  • Sidenav displays correctly using old markup and new setting

[mejiaj]

This doesn't display in final HTML build because it's controlled by the StorybookJS control in usa-docs.stories.js.

uswds/packages/templates/usa-documentation/usa-docs.stories.js

Lines 14 to 20 in ba608d1

	TestDocumentationReorder.argTypes = {
	sidenav_reorder: {
	control: { type: "boolean" },
	defaultValue: false,
	name: "Reorder with CSS",
	},
	};

[thisisdano]

Very nice. Thanks for thinking this through!