`SideNav` component - Porting of advanced features from `HcNav` #1304

didoo · 2023-04-13T14:21:43Z

📌 Summary

This is a large PR that takes the existing Hds::SideNav implementation and extends it to include advanced features like responsiveness (animation/transition) and content "portaling", by adopting (and adapting) the implementation in Cloud UI (then extracted and refactored by @meirish as reusable/standalone component in https://github.com/hashicorp/ember-shared-components).

🛠️ Detailed description

Unfortunately, it's not been possible to break down the PR in smaller commits: some of the work has been done in other PRs (see related PRs below) and ported in this PR all together, other work involved large renaming/refactoring of the main component (SideNav) as well as its children/sub-components. I'll try to give an overview of what the code changes are, and why they've been done.

added new dependencies
- ember-a11y-refocus - used to add a navigator narrator to the SideNav (it's optionally controlled by the consumers)
- ember-stargate - used for content "portaling" (see the Cloud UI implementation to understand how this works
updated SideNav component porting advanced features from HcNav (responsiveness/animation/portaling)
- SideNav
  - "merged" the layout provided by the SideNav::Wrapper container, with the high-level functionalities provided by the HcNav implementation:
    - accessibility improvements
      - added support for a11y-refocus <NavigatorNarrator> element
        
        it's added by default but can be disabled via hasA11yRefocus argument
        
        we expose a set of arguments to customise its behaviour
      - added focus trapping for the navigation (when is "responsive", is in "mobile" mode and is "expanded")
    - responsiveness
      - made the "responsive" behaviour optional (true by default)
        
        it adds a button that toggles the minimized/expanded states when in "mobile" viewport (the button itself changes visual state)
      - exposed the header/body/footer containers of the "sidenav" as named blocks and exposed the isMinimized tracked property so it can be used for custom behaviours if necessary
      - the consumers can "override" some of the default properties (eg. breaking point between "mobile" and "desktop" views) using CSS custom props (eg. --hds-app-desktop-breakpoint)
      - when in "mobile" + "expanded" mode
        
        an overlay is shown (if clicked it minimizes the sidenav)
        
        a keyboard event listener for esc is added (if triggered it minimizes the sidenav)
      - two callbacks are exposed: onDesktopViewportChange and onToggleMinimizedStatus so consumers can hook on these if they need
      - a special hds-side-nav-hide-when-minimized class name is provided so consumers can use it with custom element, to control how they respond to changes in the "minimised" state
- SideNav::Wrapper
  - removed this component because it's not needed anymore as standalone element, now it's possible to use directly the SideNav top-level component (with/without responsiveness)
- SideNav::Header
  - renamed a couple of classes and added a specific class used to fade-in/out the action on "minimize" toggle
  - moved SideNav::HomeLink and SideNav::IconButton under the "header" folder for better file organization
- SideNav::List
  - added "extra" generic containers before/after the
  - SideNav::PortalTarget + SideNav::Portal
    - added these two new components to allow users to inject content in the navigation via "portals"
    - this were an almost direct porting of the existing implementation, I've just removed some extra stuff that was not needed anymore
- updated (and added) integration tests
  - updated the existing tests in HDS for SideNav component and sub-components
  - ported most of the tests from https://github.com/hashicorp/ember-shared-components/tree/main/packages/hc-app-frame/test-app/tests/integration/components/hc-app-frame
- updated the website documentation
  - temporarily hidden the "how to use" section and replaced it with a banner explaining that the docs are being updated
  - updated the "component API" section to align it with the latest changes introduced in this refactoring
👀 Previews
- 👉 Showcase: https://hds-showcase-git-app-sidenav-component-hashicorp.vercel.app/components/side-nav
- 👉 Website: https://hds-website-git-app-sidenav-component-hashicorp.vercel.app/components/side-nav?tab=code
  - a separate PR will be opened later to update the "how to use" section of the documentation (see TODO below)
- 👉 Production (Cloud UI spike deployment): https://cloud-ui-remote-kyzvof0x2-hashicorp.vercel.app/
  - a password is needed to access this deploy (it's available in 1password)
🚧 Todo
- ~~add JSON design tokens for the CSS variables~~
  - will be done in a separate PR - HDS-1696
- ~~update the "how to use" section of the documentation~~
  - will be done in a separate PR - HDS-1826
- ~~standardize z-index values and expose them as design tokens (JSON + CSS variables)~~
  - will be done in Q2FY24 - HDS-1803
🔗 External links

Jira tickets:
- https://hashicorp.atlassian.net/browse/HDS-1691
- https://hashicorp.atlassian.net/browse/HDS-1750
Related PRs:
- HDS
  - SideNav component (HDS-1143) #1163
  - AppFrame component #1284
- Cloud UI
- Ember Shared Components
  - https://github.com/hashicorp/ember-shared-components/pull/2
  - https://github.com/hashicorp/ember-shared-components/pull/3
👀 Reviewer's checklist:
- +1 Percy if applicable
- Confirm that PR has a changelog update via Changesets if needed
💬 Please consider using conventional comments when reviewing this PR.

vercel · 2023-04-13T14:21:48Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
hds-showcase	✅ Ready (Inspect)	Visit Preview	Apr 20, 2023 9:26am
hds-website	✅ Ready (Inspect)	Visit Preview	Apr 20, 2023 9:26am

… container can be used

alex-ju

Impressive work! 👏

I couldn't spot anything off in my tests so far. Thanks for setting up a preview in Cloud UI, helped a lot to test it in context!

alex-ju · 2023-04-18T15:05:52Z

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

+  }
+
+  addEventListeners() {
+    document.addEventListener('keydown', this.escapePress, true);


not sure if there's a non-convoluted way to add this listener to sidenav's outermost element instead of document

@meirish I think you wrote this code (according to this commit: https://github.com/hashicorp/cloud-ui/commit/f8a3e3a9387a967654742fde2512cae816a1b79d#diff-571b3895fafd8c25954e1f6a914ed1b575c8a7211246259004b521459d5d2e4b)

any ideas/suggestion? specific reasons for attaching the listener to the document ?

packages/components/addon/components/hds/side-nav/portal/target.js

packages/components/app/styles/components/side-nav/header.scss

see: hashicorp/cloud-ui#5507

KristinLBradley · 2023-04-19T21:43:36Z

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

+
+  {{#if this.isResponsive}}
+    {{! template-lint-disable no-invalid-interactive}}
+    <div class="hds-side-nav__overlay" {{on "click" this.toggleMinimizedStatus}} />


Just curious why this needs to be a div vs. a button?

no strong reasons, apart from:

I've ported as is from the existing Cloud UI implementation

it would be weird to have a huge button covering the entire page (I know it's silly, but the idea makes me nervous)

packages/components/app/styles/components/side-nav/a11y-refocus.scss

packages/components/app/styles/components/side-nav/content.scss

packages/components/app/styles/components/side-nav/header.scss

packages/components/app/styles/components/side-nav/main.scss

website/docs/components/side-nav/partials/code/component-api.md

website/docs/components/side-nav/partials/code/how-to-use_OLD.md

website/docs/components/side-nav/partials/code/how-to-use_TEMP.md

website/docs/layouts/app-frame/partials/code/how-to-use.md

KristinLBradley

Looks great to me! I just added a few very minor comments, questions, and suggested edits.

Co-authored-by: Kristin Bradley <kristin.bradley@hashicorp.com>

didoo changed the base branch from main to app-frame-component April 13, 2023 14:22

didoo mentioned this pull request Apr 13, 2023

AppFrame component #1284

Merged

2 tasks

Base automatically changed from app-frame-component to main April 13, 2023 15:06

didoo force-pushed the app-sidenav-component branch from 0ab64b9 to 7d7c068 Compare April 13, 2023 15:12

vercel bot deployed to Preview – hds-showcase April 13, 2023 15:14 View deployment

vercel bot deployed to Preview – hds-website April 13, 2023 15:16 View deployment

didoo force-pushed the app-sidenav-component branch from 7d7c068 to 2747ce6 Compare April 13, 2023 15:17

vercel bot had a problem deploying to Preview – hds-website April 13, 2023 15:17 Failure

vercel bot had a problem deploying to Preview – hds-showcase April 13, 2023 15:17 Failure

didoo force-pushed the app-sidenav-component branch from 2747ce6 to d9fd175 Compare April 13, 2023 19:52

vercel bot deployed to Preview – hds-showcase April 13, 2023 19:54 View deployment

vercel bot deployed to Preview – hds-website April 13, 2023 19:55 View deployment

didoo force-pushed the app-sidenav-component branch from d9fd175 to 4f4eb84 Compare April 13, 2023 20:49

vercel bot deployed to Preview – hds-showcase April 13, 2023 20:51 View deployment

vercel bot deployed to Preview – hds-website April 13, 2023 20:52 View deployment

didoo force-pushed the app-sidenav-component branch from 4f4eb84 to cd004de Compare April 13, 2023 21:06

vercel bot deployed to Preview – hds-showcase April 13, 2023 21:08 View deployment

vercel bot deployed to Preview – hds-website April 13, 2023 21:10 View deployment

didoo force-pushed the app-sidenav-component branch from cd004de to 6b2e711 Compare April 13, 2023 21:13

vercel bot deployed to Preview – hds-showcase April 13, 2023 21:16 View deployment

vercel bot deployed to Preview – hds-website April 13, 2023 21:17 View deployment

didoo force-pushed the app-sidenav-component branch from 6b2e711 to 80d8eb8 Compare April 13, 2023 21:17

vercel bot deployed to Preview – hds-showcase April 13, 2023 21:19 View deployment

vercel bot deployed to Preview – hds-website April 13, 2023 21:20 View deployment

didoo force-pushed the app-sidenav-component branch from 80d8eb8 to bbeb6ac Compare April 13, 2023 21:29

vercel bot deployed to Preview – hds-showcase April 13, 2023 21:32 View deployment

vercel bot deployed to Preview – hds-website April 13, 2023 21:33 View deployment

didoo force-pushed the app-sidenav-component branch from bbeb6ac to f115c0b Compare April 13, 2023 21:33

vercel bot deployed to Preview – hds-showcase April 13, 2023 21:36 View deployment

small update to the AppFrame documentation to clarify how the “modal”…

a45b246

… container can be used

vercel bot deployed to Preview – hds-showcase April 18, 2023 08:38 View deployment

vercel bot deployed to Preview – hds-website April 18, 2023 08:38 View deployment

didoo added the packages/components label Apr 18, 2023

alex-ju approved these changes Apr 18, 2023

View reviewed changes

fixed display of header__logo-container

964f1b3

vercel bot deployed to Preview – hds-showcase April 18, 2023 16:36 View deployment

vercel bot deployed to Preview – hds-website April 18, 2023 16:37 View deployment

ported “debounce” updates to the animation function from PR in Cloud UI

7daaee8

see: hashicorp/cloud-ui#5507

vercel bot deployed to Preview – hds-showcase April 19, 2023 09:47 View deployment

vercel bot deployed to Preview – hds-website April 19, 2023 09:48 View deployment