Merge pull request #5809 from uswds/jm-feature-doc-layout-order-setting

thisisdano · web-flow · commit 8cb4125680a3 · 2024-03-11T09:32:51.000-07:00
USWDS - Documentation page: Improve backwards compatibility with sidenav order
diff --git a/packages/templates/usa-documentation/includes/_usa-docs-inner.twig b/packages/templates/usa-documentation/includes/_usa-docs-inner.twig
@@ -40,14 +40,31 @@
   ]
 }%}
 
+{% set desktop_sidenav_classes = "display-none desktop:display-block desktop:grid-col-3" %}
+
+{# If true, revert to the old single sidenav behavior. #}
+{% if sidenav_reorder %}
+  {% set desktop_sidenav_classes = "" %}
+{% endif %}
+
 <div class="usa-section">
   <div class="grid-container">
     <div class="grid-row grid-gap">
-      <div class="usa-layout-docs__sidenav display-none desktop:display-block desktop:grid-col-3">
-        {% include "@components/usa-sidenav/src/usa-sidenav.twig" with sidenav_settings %}  
+      <div class="usa-layout-docs__sidenav {{ desktop_sidenav_classes }}">
+        {% include "@components/usa-sidenav/src/usa-sidenav.twig" with sidenav_settings %}
       </div>
 
       <main class="desktop:grid-col-9 usa-prose" id="main-content">
+        {% 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 %}
+
         <h1>Page heading (h1)</h1>
         <p class="usa-intro">The page heading communicates the main focus of the page. Make your page heading descriptive and keep it succinct.</p>
         <h2 id="section-heading-h2">Section heading (h2)</h2>
@@ -60,10 +77,12 @@
         <p>Read the full documentation on our side navigation on the component page.</p>
       </main>
     </div>
-      
+
+    {# Hide additional sidenav if we're using pre-3.8.0 behavior. #}
+    {% if not sidenav_reorder %}
     <div class="usa-layout-docs__sidenav desktop:display-none">
-      {% include "@components/usa-sidenav/src/usa-sidenav.twig" with sidenav_settings %}  
+      {% include "@components/usa-sidenav/src/usa-sidenav.twig" with sidenav_settings %}
     </div>
+    {% endif %}
   </div>
 </div>
-
diff --git a/packages/templates/usa-documentation/usa-docs.stories.js b/packages/templates/usa-documentation/usa-docs.stories.js
@@ -3,9 +3,18 @@ import Component from "./usa-docs.twig";
 
 export default {
   title: "Pages/Documentation Page",
+  args: DefaultContent,
 };
 
 const Template = (args) => Component(args);
 
 export const DocumentationPage = Template.bind({});
-DocumentationPage.args = DefaultContent;
+
+export const TestDocumentationReorder = Template.bind({});
+TestDocumentationReorder.argTypes = {
+  sidenav_reorder: {
+    control: { type: "boolean" },
+    defaultValue: false,
+    name: "Reorder with CSS",
+  },
+};
diff --git a/packages/usa-layout-docs/src/styles/_usa-layout-docs.scss b/packages/usa-layout-docs/src/styles/_usa-layout-docs.scss
@@ -1,9 +1,26 @@
 @use "uswds-core" as *;
 
+$sidenav-reorder-warning: "$theme-sidenav-reorder is enabled and has accessibility concerns. This behavior has a negative impact on users of assistive technologies.";
+
 .usa-layout-docs__sidenav {
   padding-top: units(4);
 
   @include at-media("desktop") {
     padding-top: 0;
   }
+
+  // Revert to >3.8.0 behavior and give a warning.
+  @if $theme-sidenav-reorder {
+    @warn $sidenav-reorder-warning;
+
+    &:first-of-type {
+      @include grid-col(12);
+      order: 2;
+
+      @include at-media("desktop") {
+        @include grid-col(3);
+        order: 0;
+      }
+    }
+  }
 }
diff --git a/packages/uswds-core/src/styles/settings/_settings-components.scss b/packages/uswds-core/src/styles/settings/_settings-components.scss
@@ -172,6 +172,7 @@ $theme-search-min-width: 27ch !default;
 // Sidenav
 $theme-sidenav-current-border-width: 0.5 !default;
 $theme-sidenav-font-family: "ui" !default;
+$theme-sidenav-reorder: false !default;
 
 // Site Alert
 $theme-site-alert-max-width: "desktop" !default;
