Foundations / Viewport breakpoints - Adoption in HDS (#2859)

Author: didoo

.changeset/red-rice-refuse.md

@@ -0,0 +1,11 @@
+---
+"@hashicorp/design-system-components": minor
+---
+
+`Pagination` - Replaced custom breakpoint (`1000px`) with standard `lg` (`1088px`) breakpoint
+
+`Stepper::Nav` - Replaced custom breakpoint (`550px`) with standard `sm` (`480px`) breakpoint
+
+`AppHeader` - Removed usage of `--hds-app-desktop-breakpoint` CSS variable and relied on the `@breakpoint` argument for override of mobile behaviour
+
+`AppSideNav` - Removed usage of `--hds-app-desktop-breakpoint` CSS variable, added `@breakpoint` argument, and relied on it for override of mobile behaviour

packages/components/src/components/hds/app-header/index.ts

@@ -10,6 +10,8 @@ import { tracked } from '@glimmer/tracking';
 import { registerDestructor } from '@ember/destroyable';
 import type Owner from '@ember/owner';
 
+import { hdsBreakpoints } from '@hashicorp/design-system-components/utils/hds-breakpoints';
+
 export interface HdsAppHeaderSignature {
   Args: {
     breakpoint?: string;
@@ -39,17 +41,8 @@ export default class HdsAppHeader extends Component<HdsAppHeaderSignature> {
   // Generates a unique ID for the Menu Content
   private _menuContentId = 'hds-menu-content-' + guidFor(this);
 
-  private _breakpoint = parseInt(
-    getComputedStyle(document.documentElement).getPropertyValue(
-      '--hds-app-desktop-breakpoint'
-    )
-  );
-
-  private _desktopMQVal =
-    this.args.breakpoint ??
-    getComputedStyle(document.documentElement).getPropertyValue(
-      '--hds-app-desktop-breakpoint'
-    );
+  // we use the `lg` breakpoint for `desktop` viewports, but consumers can override its value
+  private _desktopMQVal = this.args.breakpoint ?? hdsBreakpoints['lg'].px;
 
   constructor(owner: Owner, args: Record<string, never>) {
     super(owner, args);

packages/components/src/components/hds/app-side-nav/index.ts

@@ -9,11 +9,14 @@ import { action } from '@ember/object';
 import { registerDestructor } from '@ember/destroyable';
 import type Owner from '@ember/owner';
 
+import { hdsBreakpoints } from '@hashicorp/design-system-components/utils/hds-breakpoints';
+
 export interface HdsAppSideNavSignature {
   Args: {
     isResponsive?: boolean;
     isCollapsible?: boolean;
     isMinimized?: boolean;
+    breakpoint?: string;
     onToggleMinimizedStatus?: (arg: boolean) => void;
     onDesktopViewportChange?: (arg: boolean) => void;
   };
@@ -33,9 +36,8 @@ export default class HdsAppSideNav extends Component<HdsAppSideNavSignature> {
   private _desktopMQ: MediaQueryList;
   private _containersToHide!: NodeListOf<Element>;
 
-  private _desktopMQVal = getComputedStyle(
-    document.documentElement
-  ).getPropertyValue('--hds-app-desktop-breakpoint');
+  // we use the `lg` breakpoint for `desktop` viewports, but consumers can override its value
+  private _desktopMQVal = this.args.breakpoint ?? hdsBreakpoints['lg'].px;
 
   constructor(owner: Owner, args: HdsAppSideNavSignature['Args']) {
     super(owner, args);

packages/components/src/styles/components/app-side-nav/vars.scss

@@ -12,8 +12,6 @@
 // notice: they may be overwritten at consumer-level side if needed by re-defining the variables in a container element
 
 :root {
-  // breakpoint
-  --hds-app-desktop-breakpoint: 1088px; // this is used only to read its value via JS and set the `hds-app-side-nav--is-desktop` class
   // widths
   --hds-app-side-nav-width-minimized: 16px;
   --hds-app-side-nav-width-expanded: 280px;

packages/components/src/styles/components/pagination.scss

@@ -8,11 +8,7 @@
 //
 
 @use "../mixins/focus-ring" as *;
-
-// custom breakpoint for the pagination, swapping between horizontal and stacked layout
-// notice: the value is based on where the component layout potentially breaks down
-
-$hds-pagination-layout-breakpoint: 1000px;
+@use "../mixins/breakpoints" as *;
 
 // * Pagination Parent (wrapper) component
 // -------------------------------------------------------------------
@@ -25,7 +21,7 @@ $hds-pagination-layout-breakpoint: 1000px;
   align-items: center;
   margin: 0 auto;
 
-  @media screen and (max-width: $hds-pagination-layout-breakpoint) {
+  @include hds-breakpoint-below("lg") {
     display: flex;
     flex-wrap: wrap;
     justify-content: center;
@@ -37,7 +33,7 @@ $hds-pagination-layout-breakpoint: 1000px;
     justify-self: flex-start;
     margin-right: var(--token-pagination-child-spacing-horizontal);
 
-    @media screen and (max-width: $hds-pagination-layout-breakpoint) {
+    @include hds-breakpoint-below("lg") {
       margin-top: var(--token-pagination-child-spacing-vertical);
       margin-left: var(--token-pagination-child-spacing-horizontal);
     }
@@ -46,7 +42,7 @@ $hds-pagination-layout-breakpoint: 1000px;
   .hds-pagination-nav {
     grid-area: nav;
 
-    @media screen and (max-width: $hds-pagination-layout-breakpoint) {
+    @include hds-breakpoint-below("lg") {
       justify-content: center;
       order: -1;
       // Force nav to occupy a full row so other components will wrap:
@@ -59,7 +55,7 @@ $hds-pagination-layout-breakpoint: 1000px;
     justify-self: flex-end;
     margin-left: var(--token-pagination-child-spacing-horizontal);
 
-    @media screen and (max-width: $hds-pagination-layout-breakpoint) {
+    @include hds-breakpoint-below("lg") {
       margin-top: var(--token-pagination-child-spacing-vertical);
       margin-right: var(--token-pagination-child-spacing-horizontal);
     }

packages/components/src/styles/components/side-nav/vars.scss

@@ -7,15 +7,17 @@
 // SIDE-NAV - VARS
 //
 
+@use "sass:map";
 @use "../../mixins/interactive-dark-theme" as *;
+@use "../../mixins/breakpoints" as *;
 
 // LOCAL VARIABLES
 // we use `hds-app` as prefix to distinguish them from the normal tokens
 // notice: they may be overwritten at consumer-level side if needed by re-defining the variables in a container element
 
 :root {
   // breakpoint
-  --hds-app-desktop-breakpoint: 1088px; // this is used only to read its value via JS and set the `hds-side-nav--is-desktop` class
+  --hds-app-desktop-breakpoint: #{map.get($hds-breakpoints, "lg")}; // this is used only to read its value via JS and set the `hds-side-nav--is-desktop` class
   // widths
   --hds-app-sidenav-width-minimized: 48px;
   --hds-app-sidenav-width-expanded: 280px;

packages/components/src/styles/components/stepper/nav.scss

@@ -9,6 +9,7 @@
 
 @use "sass:map";
 @use "../../mixins/focus-ring" as *;
+@use "../../mixins/breakpoints" as *;
 @use "./step-indicator.scss" as *;
 
 $progress-bar-animation-duration: 0.25s;
@@ -288,7 +289,7 @@ $progress-bar-animation-duration: 0.25s;
 
 // MOBILE
 
-@media screen and (width <= 550px) {
+@include hds-breakpoint-below("sm") {
   .hds-stepper-nav {
     &::before,
     &::after {

showcase/tests/integration/components/hds/app-header/index-test.js

@@ -52,27 +52,28 @@ module('Integration | Component | hds/app-header/index', function (hooks) {
   // Note: We set a high breakpoint to force the component to render as "mobile"
 
   test('it is "mobile" on narrow viewports', async function (assert) {
-    await render(hbs`<style>:root {--hds-app-desktop-breakpoint: 10000px}</style>
-<Hds::AppHeader id='test-app-header' />`);
+    await render(
+      hbs`<Hds::AppHeader id='test-app-header' @breakpoint='10000px' />`
+    );
     assert.dom('#test-app-header').hasClass('hds-app-header--is-mobile');
   });
 
   test('it shows a menu button on narrow viewports', async function (assert) {
-    await render(hbs`<style>:root {--hds-app-desktop-breakpoint: 10000px}</style>
-<Hds::AppHeader />`);
+    await render(hbs`
+<Hds::AppHeader @breakpoint='10000px' />`);
     assert.dom('.hds-app-header__menu-button').exists();
   });
 
   // Mobile menu functionality
   test(`the actions do not display by default on narrow viewports`, async function (assert) {
-    await render(hbs`<style>:root {--hds-app-desktop-breakpoint: 10000px}</style>
-<Hds::AppHeader id='test-app-header' />`);
+    await render(hbs`
+<Hds::AppHeader id='test-app-header' @breakpoint='10000px' />`);
     assert.dom('#test-app-header').hasClass('hds-app-header--menu-is-closed');
   });
 
   test(`the actions show/hide when the menu button is pressed on narrow viewports`, async function (assert) {
-    await render(hbs`<style>:root {--hds-app-desktop-breakpoint: 10000px}</style>
-<Hds::AppHeader id='test-app-header' />`);
+    await render(hbs`
+<Hds::AppHeader id='test-app-header' @breakpoint='10000px' />`);
     assert.dom('#test-app-header').hasClass('hds-app-header--menu-is-closed');
 
     await click('.hds-app-header__menu-button');
@@ -95,8 +96,7 @@ module('Integration | Component | hds/app-header/index', function (hooks) {
   // A11Y
 
   test(`it displays the correct value for aria-expanded when actions are displayed vs hidden`, async function (assert) {
-    await render(hbs`<style>:root {--hds-app-desktop-breakpoint: 10000px}</style>
-<Hds::AppHeader />`);
+    await render(hbs`<Hds::AppHeader @breakpoint='10000px' />`);
     await click('.hds-app-header__menu-button');
     assert
       .dom('.hds-app-header__menu-button')
@@ -109,8 +109,9 @@ module('Integration | Component | hds/app-header/index', function (hooks) {
   });
 
   test('the actions menu collapses when the ESC key is pressed on narrow viewports', async function (assert) {
-    await render(hbs`<style>:root {--hds-app-desktop-breakpoint: 10000px}</style>
-<Hds::AppHeader id='test-app-header' />`);
+    await render(
+      hbs`<Hds::AppHeader id='test-app-header' @breakpoint='10000px' />`
+    );
     assert.dom('#test-app-header').hasClass('hds-app-header--menu-is-closed');
 
     await click('.hds-app-header__menu-button');
@@ -121,8 +122,7 @@ module('Integration | Component | hds/app-header/index', function (hooks) {
   });
 
   test('the menu button has an aria-controls attribute with a value matching the menu id', async function (assert) {
-    await render(hbs`<style>:root {--hds-app-desktop-breakpoint: 10000px}</style>
-<Hds::AppHeader />`);
+    await render(hbs`<Hds::AppHeader @breakpoint='10000px' />`);
     await click('.hds-app-header__menu-button');
     assert.dom('.hds-app-header__menu-button').hasAttribute('aria-controls');
     assert.dom('.hds-app-header__actions').hasAttribute('id');

showcase/tests/integration/components/hds/app-side-nav/index-test.js

@@ -88,40 +88,54 @@ module('Integration | Component | hds/app-side-nav/index', function (hooks) {
   // MOBILE
 
   test('it is "mobile" on narrow viewports', async function (assert) {
-    await render(hbs`<style>:root {--hds-app-desktop-breakpoint: 10088px}</style>
-<Hds::AppSideNav id='test-app-side-nav' />`);
+    await render(
+      hbs`<Hds::AppSideNav id='test-app-side-nav' @breakpoint='10000px' />`
+    );
     assert.dom('#test-app-side-nav').hasClass('hds-app-side-nav--is-mobile');
   });
 
   test('it is minimized/collapsed on narrow viewports by default', async function (assert) {
-    await render(hbs`<style>:root {--hds-app-desktop-breakpoint: 10088px}</style>
-<Hds::AppSideNav id='test-app-side-nav' />`);
+    await render(
+      hbs`<Hds::AppSideNav id='test-app-side-nav' @breakpoint='10000px' />`
+    );
     assert.dom('#test-app-side-nav').hasClass('hds-app-side-nav--is-minimized');
   });
 
   test('it is not minimized/collapsed on narrow viewports if `isResponsive` is false', async function (assert) {
-    await render(hbs`<style>:root {--hds-app-desktop-breakpoint: 10088px}</style>
-<Hds::AppSideNav id='test-app-side-nav' @isResponsive={{false}} />`);
+    await render(
+      hbs`<Hds::AppSideNav
+  id='test-app-side-nav'
+  @isResponsive={{false}}
+  @breakpoint='10000px'
+/>`
+    );
     assert
       .dom('#test-app-side-nav')
       .hasClass('hds-app-side-nav--is-not-minimized');
   });
 
   test('it shows a toggle button on narrow viewports by default', async function (assert) {
-    await render(hbs`<style>:root {--hds-app-desktop-breakpoint: 10088px}</style>
-<Hds::AppSideNav id='test-app-side-nav' />`);
+    await render(
+      hbs`<Hds::AppSideNav id='test-app-side-nav' @breakpoint='10000px' />`
+    );
     assert.dom('.hds-app-side-nav__toggle-button').exists();
   });
 
   test('it does not show a toggle button on narrow viewports if `isResponsive` is false', async function (assert) {
-    await render(hbs`<style>:root {--hds-app-desktop-breakpoint: 10088px}</style>
-<Hds::AppSideNav id='test-app-side-nav' @isResponsive={{false}} />`);
+    await render(
+      hbs`<Hds::AppSideNav
+  id='test-app-side-nav'
+  @isResponsive={{false}}
+  @breakpoint='10000px'
+/>`
+    );
     assert.dom('.hds-app-side-nav__toggle-button').doesNotExist();
   });
 
   test('it expands/collapses when the toggle button is pressed on narrow viewports', async function (assert) {
-    await render(hbs`<style>:root {--hds-app-desktop-breakpoint: 10088px}</style>
-<Hds::AppSideNav id='test-app-side-nav' />`);
+    await render(
+      hbs`<Hds::AppSideNav id='test-app-side-nav' @breakpoint='10000px' />`
+    );
     assert.dom('#test-app-side-nav').hasClass('hds-app-side-nav--is-minimized');
 
     await click('.hds-app-side-nav__toggle-button');
@@ -133,8 +147,7 @@ module('Integration | Component | hds/app-side-nav/index', function (hooks) {
   });
 
   test('it collapses when the ESC key is pressed on narrow viewports', async function (assert) {
-    await render(hbs`<style>:root {--hds-app-desktop-breakpoint: 10088px}</style>
-<Hds::AppSideNav id='test-app-side-nav'>
+    await render(hbs`<Hds::AppSideNav id='test-app-side-nav' @breakpoint='10000px'>
   <span id='test-app-side-nav-body' />
   <span class='hds-app-side-nav-hide-when-minimized' />
 </Hds::AppSideNav>`);