Skip to content

USWDS - Documentation page: Improve backwards compatibility with sidenav order#5809

Merged
thisisdano merged 6 commits intodevelopfrom
jm-feature-doc-layout-order-setting
Mar 11, 2024
Merged

USWDS - Documentation page: Improve backwards compatibility with sidenav order#5809
thisisdano merged 6 commits intodevelopfrom
jm-feature-doc-layout-order-setting

Conversation

@mejiaj
Copy link
Contributor

@mejiaj mejiaj commented Mar 8, 2024 •
edited
Loading

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

@mejiaj mejiaj mentioned this pull request Mar 8, 2024
Merged
mejiaj pushed a commit to uswds/uswds-site that referenced this pull request Mar 8, 2024
Add changelog entries for uswds/uswds#5809
d9709ad
@mejiaj mejiaj marked this pull request as ready for review March 8, 2024 19:27
@mejiaj mejiaj requested a review from thisisdano March 8, 2024 19:27
@mejiaj mejiaj requested a review from mahoneycm March 11, 2024 13:53
mahoneycm
mahoneycm approved these changes Mar 11, 2024
View reviewed changes
Copy link
Contributor

@mahoneycm mahoneycm left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
mejiaj commented Mar 11, 2024
View reviewed changes
packages/templates/usa-documentation/includes/_usa-docs-inner.twig
Comment on lines +58 to +67
{% if sidenav_reorder %}
<style>
.usa-layout-docs__sidenav {
outline: 1px dashed orange;
}
</style>

Ensure <code>$theme-sidenav-reorder: true</code> in theme settings & in StorybookJS. The sidenav will be placed <em>after</em> main content and a compile warning should display.
{% endif %}

Copy link
Contributor Author

@mejiaj mejiaj Mar 11, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
thisisdano approved these changes Mar 11, 2024
View reviewed changes
Copy link
Contributor

@thisisdano thisisdano left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very nice. Thanks for thinking this through!

@thisisdano thisisdano merged commit 8cb4125 into develop Mar 11, 2024
@thisisdano thisisdano deleted the jm-feature-doc-layout-order-setting branch March 11, 2024 16:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

2 more reviewers

@thisisdano thisisdano thisisdano approved these changes

@mahoneycm mahoneycm mahoneycm approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

USWDS - Documentation: Allow sidenav reorder via settings

3 participants

@mejiaj @thisisdano @mahoneycm