@vaadin/app-layout 22.0.1 → 23.0.0-alpha3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/app-layout",
-  "version": "22.0.1",
+  "version": "23.0.0-alpha3",
   "publishConfig": {
     "access": "public"
   },
@@ -32,19 +32,18 @@
     "polymer"
   ],
   "dependencies": {
-    "@polymer/iron-resizable-behavior": "^3.0.0",
     "@polymer/polymer": "^3.0.0",
-    "@vaadin/button": "^22.0.1",
-    "@vaadin/component-base": "^22.0.1",
-    "@vaadin/vaadin-lumo-styles": "^22.0.1",
-    "@vaadin/vaadin-material-styles": "^22.0.1",
-    "@vaadin/vaadin-themable-mixin": "^22.0.1"
+    "@vaadin/button": "23.0.0-alpha3",
+    "@vaadin/component-base": "23.0.0-alpha3",
+    "@vaadin/vaadin-lumo-styles": "23.0.0-alpha3",
+    "@vaadin/vaadin-material-styles": "23.0.0-alpha3",
+    "@vaadin/vaadin-themable-mixin": "23.0.0-alpha3"
   },
   "devDependencies": {
     "@esm-bundle/chai": "^4.3.4",
-    "@vaadin/tabs": "^22.0.1",
+    "@vaadin/tabs": "23.0.0-alpha3",
     "@vaadin/testing-helpers": "^0.3.2",
     "sinon": "^9.2.1"
   },
-  "gitHead": "2b0a2bff0369d6020f7cc33ad35506aa2d1f6f68"
+  "gitHead": "490037919a9e054cc002c1b3be0c94a1603e1a44"
 }

package/src/detect-ios-navbar.js

@@ -1,11 +1,11 @@
 /**
  * @license
- * Copyright (c) 2021 Vaadin Ltd.
+ * Copyright (c) 2018 - 2022 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { isIOS } from '@vaadin/component-base/src/browser-utils.js';
 
-export const _detectIosNavbar = function () {
+export function _detectIosNavbar() {
   /* c8 ignore next 11 */
   if (isIOS) {
     const innerHeight = window.innerHeight;
@@ -18,7 +18,7 @@ export const _detectIosNavbar = function () {
       document.documentElement.style.setProperty('--vaadin-viewport-offset-bottom', '');
     }
   }
-};
+}
 
 _detectIosNavbar();
 window.addEventListener('resize', _detectIosNavbar);

package/src/vaadin-app-layout.d.ts

@@ -1,11 +1,16 @@
 /**
  * @license
- * Copyright (c) 2021 Vaadin Ltd.
+ * Copyright (c) 2018 - 2022 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
+import { ControllerMixin } from '@vaadin/component-base/src/controller-mixin.js';
 import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 
+export interface AppLayoutI18n {
+  drawer: string;
+}
+
 /**
  * Fired when the `drawerOpened` property changes.
  */
@@ -118,7 +123,29 @@ export type AppLayoutEventMap = HTMLElementEventMap & AppLayoutCustomEventMap;
  * @fires {CustomEvent} overlay-changed - Fired when the `overlay` property changes.
  * @fires {CustomEvent} primary-section-changed - Fired when the `primarySection` property changes.
  */
-declare class AppLayout extends ElementMixin(ThemableMixin(HTMLElement)) {
+declare class AppLayout extends ElementMixin(ThemableMixin(ControllerMixin(HTMLElement))) {
+  /**
+   * The object used to localize this component.
+   * To change the default localization, replace the entire
+   * `i18n` object with a custom one.
+   *
+   * To update individual properties, extend the existing i18n object as follows:
+   * ```js
+   * appLayout.i18n = {
+   *   ...appLayout.i18n,
+   *   drawer: 'Drawer'
+   * }
+   * ```
+   *
+   * The object has the following structure and default values:
+   * ```
+   * {
+   *   drawer: 'Drawer'
+   * }
+   * ```
+   */
+  i18n: AppLayoutI18n;
+
   /**
    * Defines whether navbar or drawer will come first visually.
    * - By default (`primary-section="navbar"`), the navbar takes the full available width and moves the drawer down.

package/src/vaadin-app-layout.js

@@ -1,18 +1,22 @@
 /**
  * @license
- * Copyright (c) 2021 Vaadin Ltd.
+ * Copyright (c) 2018 - 2022 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import './safe-area-inset.js';
 import './detect-ios-navbar.js';
-import { IronResizableBehavior } from '@polymer/iron-resizable-behavior/iron-resizable-behavior.js';
-import { mixinBehaviors } from '@polymer/polymer/lib/legacy/class.js';
 import { FlattenedNodesObserver } from '@polymer/polymer/lib/utils/flattened-nodes-observer.js';
 import { afterNextRender, beforeNextRender } from '@polymer/polymer/lib/utils/render-status.js';
 import { html, PolymerElement } from '@polymer/polymer/polymer-element.js';
+import { ControllerMixin } from '@vaadin/component-base/src/controller-mixin.js';
 import { ElementMixin } from '@vaadin/component-base/src/element-mixin.js';
+import { FocusTrapController } from '@vaadin/component-base/src/focus-trap-controller.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
 
+/**
+ * @typedef {import('./vaadin-app-layout.js').AppLayoutI18n} AppLayoutI18n
+ */
+
 /**
  * `<vaadin-app-layout>` is a Web Component providing a quick and easy way to get a common application layout structure done.
  *
@@ -103,8 +107,9 @@ import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mix
  * @extends HTMLElement
  * @mixes ElementMixin
  * @mixes ThemableMixin
+ * @mixes ControllerMixin
  */
-class AppLayout extends ElementMixin(ThemableMixin(mixinBehaviors([IronResizableBehavior], PolymerElement))) {
+class AppLayout extends ElementMixin(ThemableMixin(ControllerMixin(PolymerElement))) {
   static get template() {
     return html`
       <style>
@@ -199,16 +204,20 @@ class AppLayout extends ElementMixin(ThemableMixin(mixinBehaviors([IronResizable
           right: auto;
           bottom: var(--vaadin-app-layout-navbar-offset-bottom, var(--vaadin-viewport-offset-bottom, 0));
           left: var(--vaadin-app-layout-navbar-offset-left, 0);
-          transition: transform var(--vaadin-app-layout-transition);
+          transition: transform var(--vaadin-app-layout-transition), visibility var(--vaadin-app-layout-transition);
           transform: translateX(-100%);
           max-width: 90%;
           width: 16em;
           box-sizing: border-box;
           padding: var(--safe-area-inset-top) 0 var(--safe-area-inset-bottom) var(--safe-area-inset-left);
           outline: none;
+          /* The drawer should be inaccessible by the tabbing navigation when it is closed. */
+          visibility: hidden;
         }
 
         :host([drawer-opened]) [part='drawer'] {
+          /* The drawer should be accessible by the tabbing navigation when it is opened. */
+          visibility: visible;
           transform: translateX(0%);
           touch-action: manipulation;
         }
@@ -285,7 +294,7 @@ class AppLayout extends ElementMixin(ThemableMixin(mixinBehaviors([IronResizable
         <slot name="navbar"></slot>
       </div>
       <div part="backdrop" on-click="_close" on-touchstart="_close"></div>
-      <div part="drawer" id="drawer">
+      <div part="drawer" id="drawer" on-keydown="__onDrawerKeyDown">
         <slot name="drawer" id="drawerSlot"></slot>
       </div>
       <div content>
@@ -304,6 +313,39 @@ class AppLayout extends ElementMixin(ThemableMixin(mixinBehaviors([IronResizable
 
   static get properties() {
     return {
+      /**
+       * The object used to localize this component.
+       * To change the default localization, replace the entire
+       * `i18n` object with a custom one.
+       *
+       * To update individual properties, extend the existing i18n object as follows:
+       * ```js
+       * appLayout.i18n = {
+       *   ...appLayout.i18n,
+       *   drawer: 'Drawer'
+       * }
+       * ```
+       *
+       * The object has the following structure and default values:
+       * ```
+       * {
+       *   drawer: 'Drawer'
+       * }
+       * ```
+       *
+       * @type {AppLayoutI18n}
+       * @default {English/US}
+       */
+      i18n: {
+        type: Object,
+        observer: '__i18nChanged',
+        value: () => {
+          return {
+            drawer: 'Drawer'
+          };
+        }
+      },
+
       /**
        * Defines whether navbar or drawer will come first visually.
        * - By default (`primary-section="navbar"`), the navbar takes the full available width and moves the drawer down.
@@ -316,7 +358,7 @@ class AppLayout extends ElementMixin(ThemableMixin(mixinBehaviors([IronResizable
         value: 'navbar',
         notify: true,
         reflectToAttribute: true,
-        observer: '_primarySectionObserver'
+        observer: '__primarySectionChanged'
       },
 
       /**
@@ -332,7 +374,7 @@ class AppLayout extends ElementMixin(ThemableMixin(mixinBehaviors([IronResizable
         notify: true,
         value: true,
         reflectToAttribute: true,
-        observer: '_drawerOpenedObserver'
+        observer: '__drawerOpenedChanged'
       },
 
       /**
@@ -369,6 +411,9 @@ class AppLayout extends ElementMixin(ThemableMixin(mixinBehaviors([IronResizable
     this.__boundResizeListener = this._resize.bind(this);
     this.__drawerToggleClickListener = this._drawerToggleClick.bind(this);
     this.__closeOverlayDrawerListener = this.__closeOverlayDrawer.bind(this);
+    this.__trapFocusInDrawer = this.__trapFocusInDrawer.bind(this);
+    this.__releaseFocusFromDrawer = this.__releaseFocusFromDrawer.bind(this);
+    this.__focusTrapController = new FocusTrapController(this);
   }
 
   /** @protected */
@@ -402,6 +447,12 @@ class AppLayout extends ElementMixin(ThemableMixin(mixinBehaviors([IronResizable
     window.addEventListener('close-overlay-drawer', this.__closeOverlayDrawerListener);
   }
 
+  /** @protected */
+  ready() {
+    super.ready();
+    this.addController(this.__focusTrapController);
+  }
+
   /** @protected */
   disconnectedCallback() {
     super.disconnectedCallback();
@@ -421,29 +472,55 @@ class AppLayout extends ElementMixin(ThemableMixin(mixinBehaviors([IronResizable
     window.dispatchEvent(new CustomEvent('close-overlay-drawer'));
   }
 
-  /** @private */
-  _primarySectionObserver(value) {
-    const isValid = ['navbar', 'drawer'].indexOf(value) !== -1;
+  /**
+   * A callback for the `primarySection` property observer.
+   *
+   * Ensures the property is set to its default value `navbar`
+   * whenever the new value is not one of the valid values: `navbar`, `drawer`.
+   *
+   * @param {string} value
+   * @private
+   */
+  __primarySectionChanged(value) {
+    const isValid = ['navbar', 'drawer'].includes(value);
     if (!isValid) {
       this.set('primarySection', 'navbar');
     }
   }
 
-  /** @private */
-  _drawerOpenedObserver() {
-    const drawer = this.$.drawer;
-
-    drawer.removeAttribute('tabindex');
-
+  /**
+   * A callback for the `drawerOpened` property observer.
+   *
+   * When the drawer opens, the method ensures the drawer has a proper height and sets focus on it.
+   * As long as the drawer is open, the focus is trapped within the drawer.
+   *
+   * When the drawer closes, the method releases focus from the drawer, setting focus on the drawer toggle.
+   *
+   * @param {boolean} drawerOpened
+   * @param {boolean} oldDrawerOpened
+   * @private
+   */
+  __drawerOpenedChanged(drawerOpened, oldDrawerOpened) {
     if (this.overlay) {
-      if (this.drawerOpened) {
-        drawer.setAttribute('tabindex', 0);
-        drawer.focus();
+      if (drawerOpened) {
         this._updateDrawerHeight();
+        this.__trapFocusInDrawer();
+      } else if (oldDrawerOpened) {
+        this.__releaseFocusFromDrawer();
       }
     }
+  }
 
-    this.notifyResize();
+  /**
+   * A callback for the `i18n` property observer.
+   *
+   * The method ensures the drawer has ARIA attributes updated
+   * once the `i18n` property changes.
+   *
+   * @private
+   */
+  __i18nChanged() {
+    this.__updateDrawerAriaAttributes();
   }
 
   /** @protected */
@@ -500,8 +577,6 @@ class AppLayout extends ElementMixin(ThemableMixin(mixinBehaviors([IronResizable
     const drawerRect = drawer.getBoundingClientRect();
 
     this.style.setProperty('--_vaadin-app-layout-drawer-offset-size', drawerRect.width + 'px');
-
-    this.notifyResize();
   }
 
   /** @protected */
@@ -513,8 +588,7 @@ class AppLayout extends ElementMixin(ThemableMixin(mixinBehaviors([IronResizable
 
   /** @protected */
   _updateOverlayMode() {
-    const overlay = this._getCustomPropertyValue('--vaadin-app-layout-drawer-overlay') == 'true';
-    const drawer = this.$.drawer;
+    const overlay = this._getCustomPropertyValue('--vaadin-app-layout-drawer-overlay') === 'true';
 
     if (!this.overlay && overlay) {
       // Changed from not overlay to overlay
@@ -524,28 +598,105 @@ class AppLayout extends ElementMixin(ThemableMixin(mixinBehaviors([IronResizable
 
     this._setOverlay(overlay);
 
+    if (!this.overlay && this._drawerStateSaved) {
+      this.drawerOpened = this._drawerStateSaved;
+      this._drawerStateSaved = null;
+    }
+
+    this._updateDrawerHeight();
+    this.__updateDrawerAriaAttributes();
+  }
+
+  /**
+   * Updates ARIA attributes on the drawer depending on the drawer mode.
+   *
+   * - In the overlay mode, the method marks the drawer with ARIA attributes as a dialog
+   * labelled with the `i18n.drawer` property.
+   * - In the normal mode, the method removes the ARIA attributes that has been set for the overlay mode.
+   *
+   * @private
+   */
+  __updateDrawerAriaAttributes() {
+    const drawer = this.$.drawer;
     if (this.overlay) {
       drawer.setAttribute('role', 'dialog');
       drawer.setAttribute('aria-modal', 'true');
-      drawer.setAttribute('aria-label', 'drawer');
+      drawer.setAttribute('aria-label', this.i18n.drawer);
     } else {
-      if (this._drawerStateSaved) {
-        this.drawerOpened = this._drawerStateSaved;
-        this._drawerStateSaved = null;
-      }
-
       drawer.removeAttribute('role');
       drawer.removeAttribute('aria-modal');
       drawer.removeAttribute('aria-label');
     }
+  }
 
-    this._updateDrawerHeight();
+  /**
+   * Returns a promise that resolves when the drawer opening/closing CSS transition ends.
+   *
+   * The method relies on the `--vaadin-app-layout-transition` CSS variable to detect whether
+   * the drawer has a CSS transition that needs to be awaited. If the CSS variable equals `none`,
+   * the promise resolves immediately.
+   *
+   * @return {Promise}
+   * @private
+   */
+  __drawerTransitionComplete() {
+    return new Promise((resolve) => {
+      if (this._getCustomPropertyValue('--vaadin-app-layout-transition') === 'none') {
+        resolve();
+        return;
+      }
 
-    if (this.overlay !== overlay) {
-      this.notifyResize();
+      this.$.drawer.addEventListener('transitionend', resolve, { once: true });
+    });
+  }
+
+  /** @private */
+  async __trapFocusInDrawer() {
+    // Wait for the drawer CSS transition before focusing the drawer
+    // in order for VoiceOver to have a proper outline.
+    await this.__drawerTransitionComplete();
+
+    if (!this.drawerOpened) {
+      // The drawer has been closed during the CSS transition.
+      return;
+    }
+
+    this.$.drawer.setAttribute('tabindex', '0');
+    this.__focusTrapController.trapFocus(this.$.drawer);
+  }
+
+  /** @private */
+  async __releaseFocusFromDrawer() {
+    // Wait for the drawer CSS transition in order to restore focus to the toggle
+    // only after `visibility` becomes `hidden`, that is, the drawer becomes inaccessible by the tabbing navigation.
+    await this.__drawerTransitionComplete();
+
+    if (this.drawerOpened) {
+      // The drawer has been opened during the CSS transition.
+      return;
     }
 
-    // TODO(jouni): ARIA attributes. The drawer should act similar to a modal dialog when in ”overlay” mode
+    this.__focusTrapController.releaseFocus();
+    this.$.drawer.removeAttribute('tabindex');
+
+    // Move focus to the drawer toggle when closing the drawer.
+    const toggle = this.querySelector('vaadin-drawer-toggle');
+    if (toggle) {
+      toggle.focus();
+      toggle.setAttribute('focus-ring', 'focus');
+    }
+  }
+
+  /**
+   * Closes the drawer on Escape press if it has been opened in the overlay mode.
+   *
+   * @param {KeyboardEvent} event
+   * @private
+   */
+  __onDrawerKeyDown(event) {
+    if (event.key === 'Escape' && this.overlay) {
+      this.drawerOpened = false;
+    }
   }
 
   /** @private */

package/src/vaadin-drawer-toggle.d.ts

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright (c) 2021 Vaadin Ltd.
+ * Copyright (c) 2018 - 2022 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { Button } from '@vaadin/button/src/vaadin-button.js';

package/src/vaadin-drawer-toggle.js

@@ -1,6 +1,6 @@
 /**
  * @license
- * Copyright (c) 2021 Vaadin Ltd.
+ * Copyright (c) 2018 - 2022 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
 import { html } from '@polymer/polymer/lib/utils/html-tag.js';