@hashicorp/design-system-components 2.1.0 → 2.3.0

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # @hashicorp/design-system-components
 
+## 2.3.0
+
+### Minor Changes
+
+- [#1283](https://github.com/hashicorp/design-system/pull/1283) [`d0ae66503`](https://github.com/hashicorp/design-system/commit/d0ae665033e6b83a65c2dcde8630985f76872901) Thanks [@KristinLBradley](https://github.com/KristinLBradley)! - - Add new `TooltipButton` component and `hds-tooltip` modifier
+
+  - Add design tokens for `Tooltip`
+
+- [#1316](https://github.com/hashicorp/design-system/pull/1316) [`5763ffbca`](https://github.com/hashicorp/design-system/commit/5763ffbca564d3a23b8a497393acc43729d92de8) Thanks [@alex-ju](https://github.com/alex-ju)! - Add `SegmentedGroup` component
+
+### Patch Changes
+
+- [#1329](https://github.com/hashicorp/design-system/pull/1329) [`216ce51a8`](https://github.com/hashicorp/design-system/commit/216ce51a81383f2e8a5d1f989c5148edf74268f6) Thanks [@didoo](https://github.com/didoo)! - `SideNav::Portal::Target` - Removed extra call to `commitStyles`
+
+- [#1328](https://github.com/hashicorp/design-system/pull/1328) [`095caf4d4`](https://github.com/hashicorp/design-system/commit/095caf4d430d459d848647ed3c1dba3155c358cf) Thanks [@didoo](https://github.com/didoo)! - `SideNav::Portal::Target` - Made the `:hover:focus` state (the one the links finds itself once clicked) identical to the `:active/.active` state
+
+- [#1334](https://github.com/hashicorp/design-system/pull/1334) [`f6fa1e15e`](https://github.com/hashicorp/design-system/commit/f6fa1e15ee52bc8962fc244a73640dd57d62769a) Thanks [@didoo](https://github.com/didoo)! - `SideNav` - added missing override of `Dropdown::ToggleButton`
+
+- Updated dependencies [[`d0ae66503`](https://github.com/hashicorp/design-system/commit/d0ae665033e6b83a65c2dcde8630985f76872901)]:
+  - @hashicorp/design-system-tokens@1.5.0
+
+## 2.2.0
+
+### Minor Changes
+
+- [#1284](https://github.com/hashicorp/design-system/pull/1284) [`050a2afa5`](https://github.com/hashicorp/design-system/commit/050a2afa5bd539e15ff21728bb6ac27ac2b90dc6) Thanks [@didoo](https://github.com/didoo)! - Added `AppFrame` component
+
+- [#1321](https://github.com/hashicorp/design-system/pull/1321) [`6cb5f55b1`](https://github.com/hashicorp/design-system/commit/6cb5f55b1a47d9718960e17c68c7ad3b8bcad04c) Thanks [@didoo](https://github.com/didoo)! - Extracted `Hds::SideNav::Base` from the `Hds::SideNav` component
+
+- [#1304](https://github.com/hashicorp/design-system/pull/1304) [`038d8306a`](https://github.com/hashicorp/design-system/commit/038d8306aee38711ba846e4d7272d237b93733e5) Thanks [@didoo](https://github.com/didoo)! - Extended the `Hds::SideNav` component to support responsiveness (animation/transition) and content portaling by adapting existing implementation for Cloud UI
+
+- [#1315](https://github.com/hashicorp/design-system/pull/1315) [`e900dbcca`](https://github.com/hashicorp/design-system/commit/e900dbcca7df1592559245e2b2031d0b2a9ec617) Thanks [@didoo](https://github.com/didoo)! - Added a `@isInline` argument to the `Hds::Dropdown` component
+
+- [#1309](https://github.com/hashicorp/design-system/pull/1309) [`ef7eeff66`](https://github.com/hashicorp/design-system/commit/ef7eeff66d1d9b81b53cf082085eb1fa636263ef) Thanks [@jorytindall](https://github.com/jorytindall)! - Add `Hds::Flyout::Footer` as generic block to `Hds::Flyout`
+
+- [#1317](https://github.com/hashicorp/design-system/pull/1317) [`fa3a328a1`](https://github.com/hashicorp/design-system/commit/fa3a328a1806af8482bcedee002c8bc3232f3968) Thanks [@didoo](https://github.com/didoo)! - Changed order of "modal" container element in the DOM for the `AppFrame` component
+
+### Patch Changes
+
+- [#1312](https://github.com/hashicorp/design-system/pull/1312) [`cd1527ef5`](https://github.com/hashicorp/design-system/commit/cd1527ef5de743e1fdf9b982bff7aa1bbc18ac54) Thanks [@alex-ju](https://github.com/alex-ju)! - Add `min-height` to `Hds::Textarea`
+
+- [#1313](https://github.com/hashicorp/design-system/pull/1313) [`5a2f5778d`](https://github.com/hashicorp/design-system/commit/5a2f5778d5e1d57a7d0d080f01319492e1a5a8b7) Thanks [@didoo](https://github.com/didoo)! - Added design tokens for `SideNav` component
+
+- [#1306](https://github.com/hashicorp/design-system/pull/1306) [`e993f6c42`](https://github.com/hashicorp/design-system/commit/e993f6c42a502f4d43cce2e1e7b1a7a8cfd90cdd) Thanks [@alex-ju](https://github.com/alex-ju)! - Fix `PowerSelectMultiple` style overrides when search is enabled
+
+- Updated dependencies [[`5a2f5778d`](https://github.com/hashicorp/design-system/commit/5a2f5778d5e1d57a7d0d080f01319492e1a5a8b7)]:
+  - @hashicorp/design-system-tokens@1.4.2
+
 ## 2.1.0
 
 ### Minor Changes

package/HOW-TO-TEST-A-COMPONENT-IN-CLOUD-UI.md

@@ -1,8 +1,17 @@
 # How to test a component in Cloud UI
 
-To test a new component (or a component that has been modified) using your local environment as source for the `@hashicorp/design-system-components` package, you have to follow a few steps.
+To test a component that is under development (or because it’s new or has been modified) you have a few options:
 
-## Prepare the Cloud UI project
+- you can use your local environment as source for the `@hashicorp/design-system-components` package
+- you can install the `@hashicorp/design-system-components` package using a branch available on GitHub
+
+This is the case when the component has not yet been released as an npm package, of course.
+
+## Using your local environment (via symlink)
+
+This approach is the preferable one, if there is an ongoing development of the component and you want to see the changes reflected immediately in the application (automatically rebuilt/refreshed whenever you save the HDS files).
+
+### Prepare the Cloud UI project
 
 For simplicity, you will need three CLI/terminal windows/tabs opened.
 
@@ -13,7 +22,7 @@ In in the first terminal window go the folder containing your local version of t
 - run `rm -fr node_modules/` to start from a blank slate
 - run `yarn` to make sure all the packages are installed
 
-## Replace the installed `@hashicorp/design-system-components` package in Cloud UI with the local one
+### Replace the installed `@hashicorp/design-system-components` package in Cloud UI with the local one
 
 In the second terminal window:
 
@@ -52,3 +61,19 @@ Everything should work and you should be able to do whatever you need to do in t
 - run `rm design-system-components` (no need for the `-fr` option, it's a symlink file not a folder)
 - go to the root of the Cloud UI project
 - run `yarn` to reinstall all the missing packages (including `@hashicorp/design-system-components` from NPM)
+
+## Using a remote branch (via GitHub)
+
+This approach is more suitable for one-off testing before releasing a package, less so for ongoing development.
+
+### Override the package resolution in the `package.json` file in the root
+
+You can override every dependency declared in the engines' `package.json` files with a single entry in the `package.json` file in the root of the project folder, by adding this line to the `"resolutions"` block:
+
+```
+"@hashicorp/design-system-components": "https://github.com/hashicorp/design-system#head=BRANCH-NAME&workspace=@hashicorp/design-system-components"
+```
+
+Once done run `yarn install` to use the "remote" version of the package, update the `node_modules` and the `yarn.lock` file.
+
+**IMPORTANT**: the way in which yarn works in this case is that it resolves in a hash referencing a commit in `yarn.lock`; so if you make changes to the branch, they’re not reflected in the local `node_modules` unless you change the hash manually in the `yarn.lock` to point to another commit, and re-run the `yarn install` command.

package/addon/components/hds/app-frame/index.hbs

@@ -0,0 +1,24 @@
+{{!
+  Copyright (c) HashiCorp, Inc.
+  SPDX-License-Identifier: MPL-2.0
+}}
+<div class="hds-app-frame" ...attributes>
+  {{#if this.hasHeader}}
+    {{yield (hash Header=(component "hds/app-frame/parts/header"))}}
+  {{/if}}
+  {{#if this.hasSidebar}}
+    {{yield (hash Sidebar=(component "hds/app-frame/parts/sidebar"))}}
+  {{/if}}
+  {{!
+    IMPORTANT: since the modals may be injected via portal or `in-element` with code that lives in the "main" container,
+    the "modal" container needs to be present in the DOM _before_ the "main" block, otherwise it may cause errors
+    where the target DOM element is not found (for example in tests where the modal may be immediately opened on first render).
+  }}
+  {{#if this.hasModals}}
+    {{yield (hash Modals=(component "hds/app-frame/parts/modals"))}}
+  {{/if}}
+  {{yield (hash Main=(component "hds/app-frame/parts/main"))}}
+  {{#if this.hasFooter}}
+    {{yield (hash Footer=(component "hds/app-frame/parts/footer"))}}
+  {{/if}}
+</div>

package/addon/components/hds/app-frame/index.js

@@ -0,0 +1,52 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+import Component from '@glimmer/component';
+
+export default class HdsAppFrameIndexComponent extends Component {
+  /**
+   * Indicates if the "header" container should be displayed
+   *
+   * @param hasHeader
+   * @type {boolean}
+   * @default true
+   */
+  get hasHeader() {
+    return this.args.hasHeader ?? true;
+  }
+
+  /**
+   * Indicates if the "sidebar" container should be displayed
+   *
+   * @param hasSidebar
+   * @type {boolean}
+   * @default true
+   */
+  get hasSidebar() {
+    return this.args.hasSidebar ?? true;
+  }
+
+  /**
+   * Indicates if the "footer" container should be displayed
+   *
+   * @param hasFooter
+   * @type {boolean}
+   * @default true
+   */
+  get hasFooter() {
+    return this.args.hasFooter ?? true;
+  }
+
+  /**
+   * Indicates if the "modals" container should be displayed
+   *
+   * @param hasModals
+   * @type {boolean}
+   * @default true
+   */
+  get hasModals() {
+    return this.args.hasModals ?? true;
+  }
+}

package/addon/components/hds/app-frame/parts/footer.hbs

@@ -0,0 +1,7 @@
+{{!
+  Copyright (c) HashiCorp, Inc.
+  SPDX-License-Identifier: MPL-2.0
+}}
+<footer class="hds-app-frame__footer" ...attributes>
+  {{yield}}
+</footer>

package/addon/components/hds/app-frame/parts/header.hbs

@@ -0,0 +1,7 @@
+{{!
+  Copyright (c) HashiCorp, Inc.
+  SPDX-License-Identifier: MPL-2.0
+}}
+<header class="hds-app-frame__header" ...attributes>
+  {{yield}}
+</header>

package/addon/components/hds/app-frame/parts/main.hbs

@@ -0,0 +1,7 @@
+{{!
+  Copyright (c) HashiCorp, Inc.
+  SPDX-License-Identifier: MPL-2.0
+}}
+<main class="hds-app-frame__main" ...attributes>
+  {{yield}}
+</main>

package/addon/components/hds/app-frame/parts/modals.hbs

@@ -0,0 +1,6 @@
+{{!
+  Copyright (c) HashiCorp, Inc.
+  SPDX-License-Identifier: MPL-2.0
+}}
+{{! we use `:empty` in CSS so we have to avoid whitespaces }}
+<div class="hds-app-frame__modals" ...attributes>{{~yield~}}</div>

package/addon/components/hds/app-frame/parts/sidebar.hbs

@@ -0,0 +1,7 @@
+{{!
+  Copyright (c) HashiCorp, Inc.
+  SPDX-License-Identifier: MPL-2.0
+}}
+<aside class="hds-app-frame__sidebar" ...attributes>
+  {{yield}}
+</aside>

package/addon/components/hds/application-state/footer.js

@@ -1,3 +1,8 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
 import Component from '@glimmer/component';
 
 export default class HdsApplicationStateFooterComponent extends Component {

package/addon/components/hds/dropdown/index.hbs

@@ -2,7 +2,7 @@
   Copyright (c) HashiCorp, Inc.
   SPDX-License-Identifier: MPL-2.0
 }}
-<Hds::Disclosure class="hds-dropdown" @onClose={{@onClose}} ...attributes>
+<Hds::Disclosure class={{this.classNames}} @onClose={{@onClose}} ...attributes>
   <:toggle as |t|>
     {{yield
       (hash
@@ -12,7 +12,7 @@
     }}
   </:toggle>
   <:content as |c|>
-    <div class={{this.classNames}} {{style width=@width height=@height}}>
+    <div class={{this.classNamesContent}} {{style width=@width height=@height}}>
       {{yield (hash Header=(component "hds/dropdown/header"))}}
       <ul class="hds-dropdown__list" {{did-insert this.didInsertList}}>
         {{yield

package/addon/components/hds/dropdown/index.js

@@ -39,11 +39,27 @@ export default class HdsDropdownIndexComponent extends Component {
   }
 
   /**
-   * Get the class names to apply to the content
+   * Get the class names to apply to the element
    * @method classNames
-   * @return {string} The "class" attribute to apply to the disclosed content
+   * @return {string} The "class" attribute to apply to the root element
    */
   get classNames() {
+    let classes = ['hds-dropdown'];
+
+    // add a class based on the @isInline argument
+    if (this.args.isInline) {
+      classes.push('hds-dropdown--is-inline');
+    }
+
+    return classes.join(' ');
+  }
+
+  /**
+   * Get the class names to apply to the content
+   * @method classNamesContent
+   * @return {string} The "class" attribute to apply to the disclosed content
+   */
+  get classNamesContent() {
     let classes = ['hds-dropdown__content'];
 
     // add a class based on the @listPosition argument

package/addon/components/hds/flyout/footer.hbs

@@ -0,0 +1,7 @@
+{{!
+  Copyright (c) HashiCorp, Inc.
+  SPDX-License-Identifier: MPL-2.0
+}}
+<div class="hds-flyout__footer" ...attributes>
+  {{yield (hash close=@onDismiss)}}
+</div>

package/addon/components/hds/flyout/index.hbs

@@ -12,6 +12,7 @@
   {{yield (hash Header=(component "hds/flyout/header" id=this.id onDismiss=this.onDismiss))}}
   {{yield (hash Description=(component "hds/flyout/description"))}}
   {{yield (hash Body=(component "hds/flyout/body"))}}
+  {{yield (hash Footer=(component "hds/flyout/footer" onDismiss=this.onDismiss))}}
 </dialog>
 {{#if this.isOpen}}
   <div class="hds-flyout__overlay"></div>

package/addon/components/hds/form/checkbox/field.hbs

@@ -13,7 +13,6 @@
   {{yield (hash Label=F.Label HelperText=F.HelperText Error=F.Error)}}
   <F.Control>
     <Hds::Form::Checkbox::Base
-      class="hds-form-field__control"
       @value={{@value}}
       name={{@name}}
       required={{@isRequired}}

package/addon/components/hds/form/field/index.hbs

@@ -24,7 +24,9 @@
       )
     )
   }}
-  {{yield (hash Control=(component "hds/yield") id=this.id ariaDescribedBy=this.ariaDescribedBy)}}
+  <div class="hds-form-field__control">
+    {{yield (hash Control=(component "hds/yield") id=this.id ariaDescribedBy=this.ariaDescribedBy)}}
+  </div>
   {{yield
     (hash
       Error=(component

package/addon/components/hds/form/radio/field.hbs

@@ -13,7 +13,6 @@
   {{yield (hash Label=F.Label HelperText=F.HelperText Error=F.Error)}}
   <F.Control>
     <Hds::Form::Radio::Base
-      class="hds-form-field__control"
       @value={{@value}}
       name={{@name}}
       required={{@isRequired}}

package/addon/components/hds/form/select/field.hbs

@@ -15,7 +15,6 @@
   {{yield (hash HelperText=F.HelperText Error=F.Error)}}
   <F.Control>
     <Hds::Form::Select::Base
-      class="hds-form-field__control"
       @value={{@value}}
       @isInvalid={{@isInvalid}}
       @width={{@width}}

package/addon/components/hds/form/text-input/field.hbs

@@ -15,7 +15,6 @@
   {{yield (hash HelperText=F.HelperText Error=F.Error)}}
   <F.Control>
     <Hds::Form::TextInput::Base
-      class="hds-form-field__control"
       @type={{@type}}
       @value={{@value}}
       @isInvalid={{@isInvalid}}

package/addon/components/hds/form/textarea/field.hbs

@@ -15,7 +15,6 @@
   {{yield (hash HelperText=F.HelperText Error=F.Error)}}
   <F.Control>
     <Hds::Form::Textarea::Base
-      class="hds-form-field__control"
       @value={{@value}}
       @isInvalid={{@isInvalid}}
       @width={{@width}}

package/addon/components/hds/form/toggle/base.hbs

@@ -2,7 +2,7 @@
   Copyright (c) HashiCorp, Inc.
   SPDX-License-Identifier: MPL-2.0
 }}
-<div class={{this.classNames}}>
+<div class="hds-form-toggle">
   <input class="hds-form-toggle__control" type="checkbox" ...attributes value={{@value}} role="switch" />
   <div class="hds-form-toggle__facade"></div>
 </div>

package/addon/components/hds/form/toggle/field.hbs

@@ -13,8 +13,6 @@
   {{yield (hash Label=F.Label HelperText=F.HelperText Error=F.Error)}}
   <F.Control>
     <Hds::Form::Toggle::Base
-      {{! template-lint-disable no-capital-arguments }}
-      @_wrapperClass="hds-form-field__control"
       @value={{@value}}
       required={{@isRequired}}
       ...attributes

package/addon/components/hds/segmented-group/index.hbs

@@ -0,0 +1,15 @@
+{{!
+  Copyright (c) HashiCorp, Inc.
+  SPDX-License-Identifier: MPL-2.0
+}}
+<div class="hds-segmented-group" ...attributes>
+  {{yield
+    (hash
+      Button=(component "hds/button")
+      Dropdown=(component "hds/dropdown")
+      Select=(component "hds/form/select/base")
+      TextInput=(component "hds/form/text-input/base")
+      Generic=(component "hds/yield")
+    )
+  }}
+</div>

package/addon/components/hds/side-nav/base.hbs

@@ -0,0 +1,14 @@
+<div class="hds-side-nav" ...attributes>
+  <div class="hds-side-nav__wrapper">
+    {{yield to="root"}}
+    <div class="hds-side-nav__wrapper-header">
+      {{yield to="header"}}
+    </div>
+    <div class="hds-side-nav__wrapper-body">
+      {{yield to="body"}}
+    </div>
+    <div class="hds-side-nav__wrapper-footer">
+      {{yield to="footer"}}
+    </div>
+  </div>
+</div>

package/addon/components/hds/side-nav/{home-link.js → header/home-link.js}

@@ -6,7 +6,7 @@
 import Component from '@glimmer/component';
 import { assert } from '@ember/debug';
 
-export default class HdsSideNavHomeLinkComponent extends Component {
+export default class HdsSideNavHeaderHomeLinkComponent extends Component {
   /**
    * @param ariaLabel
    * @type {string}
@@ -16,7 +16,7 @@ export default class HdsSideNavHomeLinkComponent extends Component {
     let { ariaLabel } = this.args;
 
     assert(
-      '@ariaLabel for "Hds::SideNav::HomeLink" must have a valid value',
+      '@ariaLabel for "Hds::SideNav::Header::HomeLink" ("Logo") must have a valid value',
       ariaLabel !== undefined
     );
 

package/addon/components/hds/side-nav/{icon-button.js → header/icon-button.js}

@@ -6,7 +6,7 @@
 import Component from '@glimmer/component';
 import { assert } from '@ember/debug';
 
-export default class HdsSideNavIconButtonComponent extends Component {
+export default class HdsSideNavHeaderIconButtonComponent extends Component {
   /**
    * @param ariaLabel
    * @type {string}
@@ -16,7 +16,7 @@ export default class HdsSideNavIconButtonComponent extends Component {
     let { ariaLabel } = this.args;
 
     assert(
-      '@ariaLabel for "Hds::SideNav::IconButton" must have a valid value',
+      '@ariaLabel for "Hds::SideNav::Header::IconButton" must have a valid value',
       ariaLabel !== undefined
     );
 

package/addon/components/hds/side-nav/{header.hbs → header/index.hbs}

@@ -4,10 +4,10 @@
 }}
 
 <div class="hds-side-nav-header" ...attributes>
-  <div class="hds-side-nav-header__logo">
+  <div class="hds-side-nav-header__logo-container">
     {{yield to="logo"}}
   </div>
-  <div class="hds-side-nav-header__actions">
+  <div class="hds-side-nav-header__actions-container hds-side-nav-hide-when-minimized">
     {{yield to="actions"}}
   </div>
 </div>

package/addon/components/hds/side-nav/index.hbs

@@ -0,0 +1,40 @@
+{{!
+  Copyright (c) HashiCorp, Inc.
+  SPDX-License-Identifier: MPL-2.0
+}}
+
+<Hds::SideNav::Base class={{this.classNames}} ...attributes {{focus-trap isActive=this.shouldTrapFocus}}>
+  <:root>
+    {{#if this.hasA11yRefocus}}
+      <NavigationNarrator
+        @routeChangeValidator={{@a11yRefocusRouteChangeValidator}}
+        @skipTo="#{{@a11yRefocusSkipTo}}"
+        @skipText={{@a11yRefocusSkipText}}
+        @navigationText={{@a11yRefocusNavigationText}}
+      />
+    {{/if}}
+    {{#if this.isResponsive}}
+      {{! template-lint-disable no-invalid-interactive}}
+      <div class="hds-side-nav__overlay" {{on "click" this.toggleMinimizedStatus}} />
+      {{! template-lint-enable no-invalid-interactive}}
+      <button
+        class="hds-side-nav__menu-toggle-button"
+        type="button"
+        {{on "click" this.toggleMinimizedStatus}}
+        {{! To be localized - see: https://hashicorp.atlassian.net/browse/HDS-567 }}
+        aria-label={{if this.isMinimized "Open menu" "Close menu"}}
+      >
+        <FlightIcon @name={{if this.isMinimized "menu" "x"}} @size="24" @stretched={{true}} />
+      </button>
+    {{/if}}
+  </:root>
+  <:header as |Header|>
+    {{yield (hash Header=Header isMinimized=this.isMinimized) to="header"}}
+  </:header>
+  <:body as |Body|>
+    {{yield (hash Body=Body isMinimized=this.isMinimized) to="body"}}
+  </:body>
+  <:footer as |Footer|>
+    {{yield (hash Footer=Footer isMinimized=this.isMinimized) to="footer"}}
+  </:footer>
+</Hds::SideNav::Base>

package/addon/components/hds/side-nav/index.js

@@ -0,0 +1,107 @@
+/**
+ * Copyright (c) HashiCorp, Inc.
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+import Component from '@glimmer/component';
+import { action } from '@ember/object';
+import { tracked } from '@glimmer/tracking';
+import { assert } from '@ember/debug';
+import { registerDestructor } from '@ember/destroyable';
+
+export default class HdsSideNavComponent extends Component {
+  @tracked isResponsive = this.args.isResponsive ?? true;
+  @tracked isMinimized = this.isResponsive; // we set it minimized by default so that if we switch viewport from desktop to mobile its already minimized
+  @tracked isDesktop = true;
+  hasA11yRefocus = this.args.hasA11yRefocus ?? true;
+
+  desktopMQVal = getComputedStyle(document.documentElement).getPropertyValue(
+    '--hds-app-desktop-breakpoint'
+  );
+
+  constructor() {
+    super(...arguments);
+    this.desktopMQ = window.matchMedia(`(min-width:${this.desktopMQVal})`);
+    this.addEventListeners();
+    registerDestructor(this, () => {
+      this.removeEventListeners();
+    });
+
+    if (this.args.hasA11yRefocus) {
+      assert(
+        '@a11yRefocusSkipTo for NavigatorNarrator (a11y-refocus) in "Hds::SideNav" must have a valid value',
+        this.args.a11yRefocusSkipTo !== undefined
+      );
+    }
+  }
+
+  addEventListeners() {
+    document.addEventListener('keydown', this.escapePress, true);
+    this.desktopMQ.addEventListener('change', this.updateDesktopVariable, true);
+    // set initial state based on viewport
+    this.updateDesktopVariable({ matches: this.desktopMQ.matches });
+  }
+
+  removeEventListeners() {
+    document.removeEventListener('keydown', this.escapePress, true);
+    this.desktopMQ.removeEventListener(
+      'change',
+      this.updateDesktopVariable,
+      true
+    );
+  }
+
+  get shouldTrapFocus() {
+    return this.isResponsive && !this.isDesktop && !this.isMinimized;
+  }
+
+  get classNames() {
+    let classes = []; // `hds-side-nav` is already set by the "Hds::SideNav::Base" component
+
+    // add specific class names for the different possible states
+    if (this.isDesktop) {
+      classes.push('hds-side-nav--is-desktop');
+    } else {
+      classes.push('hds-side-nav--is-mobile');
+    }
+    if (this.isResponsive) {
+      classes.push('hds-side-nav--is-responsive');
+    }
+    if (this.isMinimized) {
+      classes.push('hds-side-nav--is-minimized');
+    } else {
+      classes.push('hds-side-nav--is-not-minimized');
+    }
+
+    return classes.join(' ');
+  }
+
+  @action
+  escapePress(event) {
+    if (event.key === 'Escape' && !this.isMinimized) {
+      this.isMinimized = true;
+    }
+  }
+
+  @action
+  toggleMinimizedStatus() {
+    this.isMinimized = !this.isMinimized;
+
+    let { onToggleMinimizedStatus } = this.args;
+
+    if (typeof onToggleMinimizedStatus === 'function') {
+      onToggleMinimizedStatus(this.isMinimized);
+    }
+  }
+
+  @action
+  updateDesktopVariable(event) {
+    this.isDesktop = event.matches;
+
+    let { onDesktopViewportChange } = this.args;
+
+    if (typeof onDesktopViewportChange === 'function') {
+      onDesktopViewportChange(this.isDesktop);
+    }
+  }
+}

package/addon/components/hds/side-nav/list/index.hbs

@@ -4,6 +4,7 @@
 }}
 
 <nav class="hds-side-nav__list-wrapper" ...attributes>
+  {{yield (hash extraBefore=(component "hds/yield"))}}
   <ul class="hds-side-nav__list" role="list">
     {{yield
       (hash
@@ -14,4 +15,5 @@
       )
     }}
   </ul>
+  {{yield (hash extraAfter=(component "hds/yield"))}}
 </nav>

package/addon/components/hds/side-nav/portal/index.hbs

@@ -0,0 +1,12 @@
+{{!
+  Copyright (c) HashiCorp, Inc.
+  SPDX-License-Identifier: MPL-2.0
+}}
+
+<Portal @target={{if @targetName @targetName "hds-side-nav-portal-target"}}>
+  <div class="hds-side-nav__content-panel" ...attributes>
+    <Hds::SideNav::List aria-label={{@ariaLabel}} as |ListElements|>
+      {{yield ListElements}}
+    </Hds::SideNav::List>
+  </div>
+</Portal>

package/addon/components/hds/side-nav/portal/target.hbs

@@ -0,0 +1,14 @@
+{{!
+  Copyright (c) HashiCorp, Inc.
+  SPDX-License-Identifier: MPL-2.0
+}}
+
+<div class="hds-side-nav__content" ...attributes>
+  <PortalTarget
+    @multiple={{true}}
+    @onChange={{this.panelsChanged}}
+    @name={{if @targetName @targetName "hds-side-nav-portal-target"}}
+    class="hds-side-nav__content-panels hds-side-nav-hide-when-minimized"
+    {{did-update this.didUpdateSubnav this.numSubnavs}}
+  />
+</div>