@vaadin/a11y-base 24.1.0 → 24.2.0-alpha1

package/index.d.ts

@@ -12,6 +12,7 @@ export {
   isKeyboardActive,
 } from './src/focus-utils.js';
 export { FocusTrapController } from './src/focus-trap-controller.js';
+export { FocusRestorationController } from './src/focus-restoration-controller.js';
 export { KeyboardDirectionMixin } from './src/keyboard-direction-mixin.js';
 export { KeyboardMixin } from './src/keyboard-mixin.js';
 export { ListMixin } from './src/list-mixin.js';

package/index.js

@@ -5,6 +5,7 @@ export { DisabledMixin } from './src/disabled-mixin.js';
 export { FieldAriaController } from './src/field-aria-controller.js';
 export { FocusMixin } from './src/focus-mixin.js';
 export { FocusTrapController } from './src/focus-trap-controller.js';
+export { FocusRestorationController } from './src/focus-restoration-controller.js';
 export {
   getFocusableElements,
   isElementFocusable,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/a11y-base",
-  "version": "24.1.0",
+  "version": "24.2.0-alpha1",
   "publishConfig": {
     "access": "public"
   },
@@ -32,13 +32,13 @@
   "dependencies": {
     "@open-wc/dedupe-mixin": "^1.3.0",
     "@polymer/polymer": "^3.0.0",
-    "@vaadin/component-base": "~24.1.0",
+    "@vaadin/component-base": "24.2.0-alpha1",
     "lit": "^2.0.0"
   },
   "devDependencies": {
     "@esm-bundle/chai": "^4.3.4",
-    "@vaadin/testing-helpers": "^0.4.0",
+    "@vaadin/testing-helpers": "^0.4.2",
     "sinon": "^13.0.2"
   },
-  "gitHead": "7fdfe7d5ceb4c305a894f8e9dc11e5b7d04cf1f2"
+  "gitHead": "0dbb118320203ab6c0c07450a3e718815367589f"
 }

package/src/aria-modal-controller.d.ts

@@ -15,6 +15,12 @@ export class AriaModalController implements ReactiveController {
    */
   host: HTMLElement;
 
+  /**
+   * The callback used to detect which element
+   * to use as a target. Defaults to the host.
+   */
+  callback: () => HTMLElement | HTMLElement[];
+
   constructor(node: HTMLElement);
 
   /**

package/src/aria-modal-controller.js

@@ -16,13 +16,21 @@ export class AriaModalController {
   /**
    * @param {HTMLElement} host
    */
-  constructor(host) {
+  constructor(host, callback) {
     /**
      * The controller host element.
      *
      * @type {HTMLElement}
      */
     this.host = host;
+
+    /**
+     * The callback used to detect which element
+     * to use as a target. Defaults to the host.
+     *
+     * @type {Function}
+     */
+    this.callback = typeof callback === 'function' ? callback : () => host;
   }
 
   /**
@@ -33,7 +41,8 @@ export class AriaModalController {
    * https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/showModal
    */
   showModal() {
-    this.__showOthers = hideOthers(this.host);
+    const targets = this.callback();
+    this.__showOthers = hideOthers(targets);
   }
 
   /**

package/src/focus-restoration-controller.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import type { Constructor } from '@open-wc/dedupe-mixin';
+
+/**
+ * A controller for saving a focused node and restoring focus to it later.
+ */
+export declare function FocusRestorationController<T extends Constructor<HTMLElement>>(
+  base: T,
+): Constructor<FocusRestorationControllerClass> & T;
+
+export declare class FocusRestorationControllerClass {
+  /**
+   * Saves the given node as a target for restoring focus to
+   * when `restoreFocus()` is called. If no node is provided,
+   * the currently focused node in the DOM is saved as a target.
+   */
+  saveFocus(node: Node | null | undefined): void;
+
+  /**
+   * Restores focus to the target node that was saved previously with `saveFocus()`.
+   */
+  restoreFocus(): void;
+}

package/src/focus-restoration-controller.js

@@ -0,0 +1,44 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2023 Vaadin Ltd.
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import { getDeepActiveElement } from './focus-utils.js';
+
+/**
+ * A controller for saving a focused node and restoring focus to it later.
+ */
+export class FocusRestorationController {
+  /**
+   * Saves the given node as a target for restoring focus to
+   * when `restoreFocus()` is called. If no node is provided,
+   * the currently focused node in the DOM is saved as a target.
+   *
+   * @param {Node | null | undefined} focusNode
+   */
+  saveFocus(focusNode) {
+    this.focusNode = focusNode || getDeepActiveElement();
+  }
+
+  /**
+   * Restores focus to the target node that was saved previously with `saveFocus()`.
+   */
+  restoreFocus() {
+    const focusNode = this.focusNode;
+    if (!focusNode) {
+      return;
+    }
+
+    if (getDeepActiveElement() === document.body) {
+      // In Firefox and Safari, focusing the node synchronously
+      // doesn't work as expected when the overlay is closing on outside click.
+      // These browsers force focus to move to the body element and retain it
+      // there until the next event loop iteration.
+      setTimeout(() => focusNode.focus());
+    } else {
+      focusNode.focus();
+    }
+
+    this.focusNode = null;
+  }
+}

package/src/styles/sr-only-styles.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2023 Vaadin Ltd..
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+import type { CSSResult } from 'lit';
+
+export const screenReaderOnly: CSSResult;

package/src/styles/sr-only-styles.js

@@ -0,0 +1,28 @@
+/**
+ * @license
+ * Copyright (c) 2021 - 2023 Vaadin Ltd..
+ * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
+ */
+
+/**
+ * @note Taken from Gaël Poupard gist
+ * @author Gaël Poupard
+ * @see https://gist.github.com/ffoodd/000b59f431e3e64e4ce1a24d5bb36034
+ */
+import { css } from 'lit';
+
+export const screenReaderOnly = css`
+  .sr-only {
+    border: 0 !important;
+    clip: rect(1px, 1px, 1px, 1px) !important;
+    -webkit-clip-path: inset(50%) !important;
+    clip-path: inset(50%) !important;
+    height: 1px !important;
+    margin: -1px !important;
+    overflow: hidden !important;
+    padding: 0 !important;
+    position: absolute !important;
+    width: 1px !important;
+    white-space: nowrap !important;
+  }
+`;