AppHeader: “Enterprise Nav” phase 1.5 updates (HDS-3613) (#2306)

KristinLBradley · web-flow · commit 5a3a79b762e6 · 2024-08-09T15:52:31.000-07:00
diff --git a/.changeset/fuzzy-melons-dream.md b/.changeset/fuzzy-melons-dream.md
@@ -0,0 +1,7 @@
+---
+"@hashicorp/design-system-components": minor
+---
+
+`AppHeader`:
+- Hide the closed menu content in mobile view using CSS instead of conditionally rendering/not rendering the menu content.
+- Add `NavigationNarrator` with associated arguments to provide a "skip link".
diff --git a/packages/components/src/components/hds/app-header/index.hbs b/packages/components/src/components/hds/app-header/index.hbs
@@ -4,6 +4,17 @@
 }}
 
 <div class={{this.classNames}} ...attributes>
+  {{#if (and this.hasA11yRefocus (not this.isOpen))}}
+    {{! @glint-expect-error - `ember-a11y-refocus` doesn't expose types yet }}
+    <NavigationNarrator
+      @routeChangeValidator={{@a11yRefocusRouteChangeValidator}}
+      @skipTo={{this.a11yRefocusSkipTo}}
+      @skipText={{@a11yRefocusSkipText}}
+      @navigationText={{@a11yRefocusNavigationText}}
+      @excludeAllQueryParams={{@a11yRefocusExcludeAllQueryParams}}
+    />
+  {{/if}}
+
   {{yield to="logo"}}
 
   {{#if (not this.isDesktop)}}
@@ -13,17 +24,14 @@
       @menuContentId={{this.menuContentId}}
     />
   {{/if}}
+
   <div class="hds-app-header__actions" id={{this.menuContentId}}>
-    {{#if this.showItems}}
-      <div class="hds-app-header__actions-content">
-        <div class="hds-app-header__global-actions">
-          {{yield to="globalActions"}}
-        </div>
+    <div class="hds-app-header__global-actions">
+      {{yield to="globalActions"}}
+    </div>
 
-        <div class="hds-app-header__utility-actions">
-          {{yield to="utilityActions"}}
-        </div>
-      </div>
-    {{/if}}
+    <div class="hds-app-header__utility-actions">
+      {{yield to="utilityActions"}}
+    </div>
   </div>
 </div>
diff --git a/packages/components/src/components/hds/app-header/index.ts b/packages/components/src/components/hds/app-header/index.ts
@@ -12,6 +12,12 @@ import { registerDestructor } from '@ember/destroyable';
 export interface HdsAppHeaderSignature {
   Args: {
     breakpoint?: string;
+    hasA11yRefocus?: boolean;
+    a11yRefocusSkipTo?: string;
+    a11yRefocusSkipText?: string;
+    a11yRefocusNavigationText?: string;
+    a11yRefocusRouteChangeValidator?: string;
+    a11yRefocusExcludeAllQueryParams?: boolean;
   };
   Blocks: {
     logo?: [];
@@ -24,11 +30,20 @@ export interface HdsAppHeaderSignature {
 export default class HdsAppHeaderComponent extends Component<HdsAppHeaderSignature> {
   @tracked isOpen = false;
   @tracked isDesktop = true;
+  @tracked hasOverflowContent = false;
   desktopMQ: MediaQueryList;
+  hasA11yRefocus = this.args.hasA11yRefocus ?? true;
+  a11yRefocusSkipTo = '#' + (this.args.a11yRefocusSkipTo ?? 'main');
 
   // Generates a unique ID for the Menu Content
   menuContentId = 'hds-menu-content-' + guidFor(this);
 
+  breakpoint = parseInt(
+    getComputedStyle(document.documentElement).getPropertyValue(
+      '--hds-app-desktop-breakpoint'
+    )
+  );
+
   desktopMQVal =
     this.args.breakpoint ??
     getComputedStyle(document.documentElement).getPropertyValue(
@@ -65,19 +80,20 @@ export default class HdsAppHeaderComponent extends Component<HdsAppHeaderSignatu
     );
   }
 
-  // Menu items display if is desktop, or if is mobile and the menu is open
-  get showItems(): boolean {
-    return this.isDesktop || this.isOpen;
-  }
-
   // Get the class names to apply to the component.
   get classNames(): string {
     const classes = ['hds-app-header'];
 
-    if (!this.isDesktop) {
+    if (this.isDesktop) {
+      classes.push('hds-app-header--is-desktop');
+    } else {
       classes.push('hds-app-header--is-mobile');
+    }
+
+    if (this.isOpen) {
+      classes.push('hds-app-header--menu-is-open');
     } else {
-      classes.push('hds-app-header--is-desktop');
+      classes.push('hds-app-header--menu-is-closed');
     }
 
     return classes.join(' ');
diff --git a/packages/components/src/styles/components/app-frame.scss b/packages/components/src/styles/components/app-frame.scss
@@ -53,6 +53,12 @@
 
 .hds-app-frame__main {
   grid-area: main;
+
+  // This prevents content from being hidden behind the fixed app-header when the skip link is used
+  .hds-app-frame--has-header-with-sidebar & {
+    margin-top: calc(var(--token-app-header-height) * -1);
+    padding-top: var(--token-app-header-height);
+  }
 }
 
 .hds-app-frame__footer {
diff --git a/packages/components/src/styles/components/app-header.scss b/packages/components/src/styles/components/app-header.scss
@@ -23,17 +23,39 @@
   background: var(--token-color-palette-neutral-700);
   border-bottom: 1px solid var(--token-color-palette-neutral-500);
 
+  // A11Y-REFOCUS "SKIP LINK"
+
+  .ember-a11y-refocus-skip-link {
+    top: 10px;
+    left: 10px;
+    z-index: 20;
+    width: max-content;
+    padding: 2px 10px 4px;
+    color: var(--token-color-foreground-action);
+    font-size: var(--token-typography-display-200-font-size);
+    font-family: var(--token-typography-display-200-font-family);
+    line-height: var(--token-typography-display-200-line-height);
+    background-color: var(--token-color-surface-faint);
+    border-radius: 3px;
+    transform: translateY(-200%);
+    transition: 0.6s ease-in-out;
+
+    &:focus {
+      transform: translateY(0);
+    }
+  }
+
   // RESPONSIVE VIEWS
 
-  // Desktop/large view:
+  // Desktop (large) view:
   &.hds-app-header--is-desktop {
     // Global actions are aligned next to the logo in desktop view
     .hds-app-header__global-actions {
       margin-right: auto;
     }
   }
 
-  // Mobile/small & Tablet/medium compound view:
+  // Mobile/tablet (small/medium) view:
   &.hds-app-header--is-mobile {
     // Actions content appears as a dropdown menu in mobile/tablet view
     .hds-app-header__actions {
@@ -43,15 +65,30 @@
       left: 0;
     }
 
-    .hds-app-header__actions-content {
+    // Display as dropdown menu in mobile/tablet view
+    .hds-app-header__actions {
       flex-wrap: wrap;
       align-content: flex-start;
-      height: calc(100vh - var(--token-app-header-height));
       padding: 16px;
       overflow: auto; // allow users to scroll if the content is too long
       background: var(--token-color-palette-neutral-700);
     }
 
+    &.hds-app-header--menu-is-closed {
+      .hds-app-header__actions {
+        height: 0;
+        padding-top: 0;
+        padding-bottom: 0;
+      }
+    }
+
+    &.hds-app-header--menu-is-open {
+      .hds-app-header__actions {
+        height: calc(100vh - var(--token-app-header-height));
+      }
+    }
+
+
     // Force the width of global actions to 100% in mobile/tablet view
     .hds-app-header__global-actions {
       &,
diff --git a/showcase/app/styles/showcase-pages/app-frame.scss b/showcase/app/styles/showcase-pages/app-frame.scss
@@ -18,6 +18,7 @@ body.layouts-app-frame {
   .shw-component-app-frame-container {
     position: relative;
     min-height: 0;
+    overflow: hidden; // hide the skip link which is positioned outside the frame
     border: 1px solid;
     box-shadow: 0 2px 4px rgba(0, 0, 0, 30%);
 
diff --git a/showcase/app/templates/components/app-header.hbs b/showcase/app/templates/components/app-header.hbs
@@ -14,7 +14,7 @@
 
   <Shw::Grid @columns={{1}} {{style gap="2rem"}} as |SG|>
     <SG.Item>
-      <Hds::AppHeader>
+      <Hds::AppHeader @hasA11yRefocus={{false}}>
         <:logo>
           <Shw::Placeholder @height="2em" @width="auto" @text="Logo" />
         </:logo>
@@ -39,7 +39,7 @@
 
   <Shw::Grid @columns={{1}} {{style gap="3rem"}} as |SG|>
     <SG.Item @label="With minimum recommended phase 1 content">
-      <Hds::AppHeader>
+      <Hds::AppHeader @hasA11yRefocus={{false}}>
         <:logo>
           <Hds::AppHeader::HomeLink @icon="hashicorp" @ariaLabel="HashiCorp home menu" @href="#" />
         </:logo>
@@ -76,7 +76,7 @@
     </SG.Item>
 
     <SG.Item @label="With max recommended phase 1 content & Terraform logo">
-      <Hds::AppHeader>
+      <Hds::AppHeader @hasA11yRefocus={{false}}>
         <:logo>
           <Hds::AppHeader::HomeLink @icon="terraform" @ariaLabel="Terraform home menu" @href="#" />
         </:logo>
@@ -115,7 +115,7 @@
     </SG.Item>
 
     <SG.Item @label="With max proposed future content">
-      <Hds::AppHeader>
+      <Hds::AppHeader @hasA11yRefocus={{false}}>
         <:logo>
           <Hds::AppHeader::HomeLink @icon="hashicorp" @ariaLabel="HashiCorp home menu" @href="#" />
         </:logo>
@@ -167,7 +167,7 @@
 
   <Shw::Grid @columns={{1}} {{style gap="3rem"}} as |SG|>
     <SG.Item @label="40 characters long organization name with dashes">
-      <Hds::AppHeader>
+      <Hds::AppHeader @hasA11yRefocus={{false}}>
         <:logo>
           <Hds::AppHeader::HomeLink @icon="hashicorp" @ariaLabel="HashiCorp home menu" @href="#" />
         </:logo>
@@ -203,7 +203,7 @@
     </SG.Item>
 
     <SG.Item @label="40 characters long organization name with no dashes">
-      <Hds::AppHeader>
+      <Hds::AppHeader @hasA11yRefocus={{false}}>
         <:logo>
           <Hds::AppHeader::HomeLink @icon="hashicorp" @ariaLabel="HashiCorp home menu" @href="#" />
         </:logo>
@@ -245,7 +245,7 @@
 
   <Shw::Grid @columns={{1}} {{style gap="3rem"}} as |SG|>
     <SG.Item @label="With custom breakpoint (menu button is visible at wide screen width)">
-      <Hds::AppHeader @breakpoint="20000px">
+      <Hds::AppHeader @hasA11yRefocus={{false}} @breakpoint="20000px">
         <:logo>
           <Hds::AppHeader::HomeLink @icon="hashicorp" @ariaLabel="HashiCorp home menu" @href="#" />
         </:logo>
diff --git a/showcase/app/templates/layouts/app-frame/frameless/demo-full-app-frame-with-app-header.hbs b/showcase/app/templates/layouts/app-frame/frameless/demo-full-app-frame-with-app-header.hbs
@@ -79,7 +79,7 @@
     </Hds::SideNav>
   </Frame.Sidebar>
 
-  <Frame.Main>
+  <Frame.Main id="main">
     <div class="shw-layout-app-frame__main-content-padding">
       <Hds::PageHeader as |PH|>
         <PH.Title>Page title</PH.Title>
diff --git a/showcase/app/templates/layouts/app-frame/frameless/demo-full-app-frame-with-side-nav.hbs b/showcase/app/templates/layouts/app-frame/frameless/demo-full-app-frame-with-side-nav.hbs
@@ -8,7 +8,13 @@
 
 <Hds::AppFrame @hasHeader={{false}} as |Frame|>
   <Frame.Sidebar>
-    <Hds::SideNav @isResponsive={{true}} @hasA11yRefocus={{false}} @isCollapsible={{true}} @hasHeader={{false}}>
+    <Hds::SideNav
+      @isResponsive={{true}}
+      @a11yRefocusSkipTo="main"
+      @hasA11yRefocus={{true}}
+      @isCollapsible={{true}}
+      @hasHeader={{false}}
+    >
       <:header>
         <Hds::SideNav::Header>
           <:logo>
@@ -71,7 +77,7 @@
     </Hds::SideNav>
   </Frame.Sidebar>
 
-  <Frame.Main>
+  <Frame.Main id="main">
     <div class="shw-layout-app-frame__main-content-padding">
       <Hds::PageHeader as |PH|>
         <PH.Title>Page title</PH.Title>
diff --git a/showcase/tests/integration/components/hds/app-header/index-test.js b/showcase/tests/integration/components/hds/app-header/index-test.js
diff --git a/website/docs/components/app-header/partials/code/component-api.md b/website/docs/components/app-header/partials/code/component-api.md
diff --git a/website/docs/components/app-header/partials/code/how-to-use.md b/website/docs/components/app-header/partials/code/how-to-use.md
