@vaadin/a11y-base 25.0.0-alpha9 → 25.0.0-beta2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/a11y-base",
-  "version": "25.0.0-alpha9",
+  "version": "25.0.0-beta2",
   "publishConfig": {
     "access": "public"
   },
@@ -31,14 +31,14 @@
   ],
   "dependencies": {
     "@open-wc/dedupe-mixin": "^1.3.0",
-    "@vaadin/component-base": "25.0.0-alpha9",
+    "@vaadin/component-base": "25.0.0-beta2",
     "lit": "^3.0.0"
   },
   "devDependencies": {
-    "@vaadin/chai-plugins": "25.0.0-alpha9",
-    "@vaadin/test-runner-commands": "25.0.0-alpha9",
+    "@vaadin/chai-plugins": "25.0.0-beta2",
+    "@vaadin/test-runner-commands": "25.0.0-beta2",
     "@vaadin/testing-helpers": "^2.0.0",
-    "sinon": "^18.0.0"
+    "sinon": "^21.0.0"
   },
-  "gitHead": "bbe4720721e0955ffc87a79b412bee38b1f0eb1e"
+  "gitHead": "e078f8371ae266f05c7ca1ec25686cc489c83f24"
 }

package/src/aria-hidden.js

@@ -115,7 +115,7 @@ const applyAttributeToOthers = (originalTarget, parentNode, markerName, controlA
   targets.forEach(keep);
 
   /**
-   * @param {?Node} el
+   * @param {?Node} parent
    */
   const deep = (parent) => {
     if (!parent || elementsToStop.has(parent)) {

package/src/aria-id-reference.js

@@ -17,7 +17,7 @@ const attributeToTargets = new Map();
  *
  * @param {string} attr the attribute name used as key in the map
  *
- * @returns {WeakMap<HTMLElement, Set<string>} a weak map with the stored values for the elements being controlled by the helper
+ * @return {WeakMap<HTMLElement, Set<string>>} a weak map with the stored values for the elements being controlled by the helper
  */
 function getAttrMap(attr) {
   if (!attributeToTargets.has(attr)) {
@@ -32,8 +32,6 @@ function getAttrMap(attr) {
  *
  * @param {HTMLElement} target
  * @param {string} attr the attribute to be cleared
- * @param {boolean} storeValue whether or not the current value of the attribute should be stored on the map
- * @returns
  */
 function cleanAriaIDReference(target, attr) {
   if (!target) {

package/src/delegate-focus-mixin.js

@@ -73,18 +73,24 @@ export const DelegateFocusMixin = dedupeMixin(
         if (this.autofocus && !this.disabled) {
           requestAnimationFrame(() => {
             this.focus();
-            this.setAttribute('focus-ring', '');
           });
         }
       }
 
       /**
+       * @param {FocusOptions=} options
        * @protected
        * @override
        */
-      focus() {
+      focus(options) {
         if (this.focusElement && !this.disabled) {
           this.focusElement.focus();
+
+          // Set focus-ring attribute on programmatic focus by default
+          // unless explicitly disabled by `{ focusVisible: false }`.
+          if (!(options && options.focusVisible === false)) {
+            this.setAttribute('focus-ring', '');
+          }
         }
       }
 

package/src/focus-mixin.js

@@ -54,6 +54,21 @@ export const FocusMixin = dedupeMixin(
         }
       }
 
+      /**
+       * @param {FocusOptions=} options
+       * @protected
+       * @override
+       */
+      focus(options) {
+        super.focus(options);
+
+        // Set focus-ring attribute on programmatic focus by default
+        // unless explicitly disabled by `{ focusVisible: false }`.
+        if (!(options && options.focusVisible === false)) {
+          this.setAttribute('focus-ring', '');
+        }
+      }
+
       /**
        * Override to change how focused and focus-ring attributes are set.
        *

package/src/focus-restoration-controller.js

@@ -29,16 +29,19 @@ export class FocusRestorationController {
       return;
     }
 
-    const preventScroll = options ? options.preventScroll : false;
+    const focusOptions = {
+      preventScroll: options ? options.preventScroll : false,
+      focusVisible: options ? options.focusVisible : false,
+    };
 
     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({ preventScroll }));
+      setTimeout(() => focusNode.focus(focusOptions));
     } else {
-      focusNode.focus({ preventScroll });
+      focusNode.focus(focusOptions);
     }
 
     this.focusNode = null;

package/src/focus-trap-controller.js

@@ -3,7 +3,7 @@
  * Copyright (c) 2021 - 2025 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
-import { getFocusableElements, isElementFocused } from './focus-utils.js';
+import { getFocusableElements, isElementFocused, isKeyboardActive } from './focus-utils.js';
 
 const instances = [];
 
@@ -87,7 +87,7 @@ export class FocusTrapController {
     instances.push(this);
 
     if (this.__focusedElementIndex === -1) {
-      this.__focusableElements[0].focus();
+      this.__focusableElements[0].focus({ focusVisible: isKeyboardActive() });
     }
   }
 
@@ -147,7 +147,7 @@ export class FocusTrapController {
     const currentIndex = this.__focusedElementIndex;
     const nextIndex = (focusableElements.length + currentIndex + step) % focusableElements.length;
     const element = focusableElements[nextIndex];
-    element.focus();
+    element.focus({ focusVisible: true });
     if (element.localName === 'input') {
       element.select();
     }

package/src/keyboard-direction-mixin.d.ts

@@ -32,12 +32,12 @@ export declare class KeyboardDirectionMixinClass {
   /**
    * Focus the item at given index. Override this method to add custom logic.
    */
-  protected _focus(index: number, navigating: boolean): void;
+  protected _focus(index: number, options: FocusOptions, navigating: boolean): void;
 
   /**
    * Focus the given item. Override this method to add custom logic.
    */
-  protected _focusItem(item: Element, navigating: boolean): void;
+  protected _focusItem(item: Element, options: FocusOptions, navigating: boolean): void;
 
   /**
    * Returns whether the item is focusable. By default,

package/src/keyboard-direction-mixin.js

@@ -38,17 +38,29 @@ export const KeyboardDirectionMixin = (superclass) =>
       return false;
     }
 
-    /** @protected */
-    focus() {
-      const items = this._getItems();
-      if (Array.isArray(items)) {
-        const idx = this._getAvailableIndex(items, 0, null, (item) => !isElementHidden(item));
-        if (idx >= 0) {
-          this._focus(idx);
-        }
+    /**
+     * @param {FocusOptions=} options
+     * @protected
+     * @override
+     */
+    focus(options) {
+      const idx = this._getFocusableIndex();
+      if (idx >= 0) {
+        this._focus(idx, options);
       }
     }
 
+    /**
+     * Get the index of a first focusable item, if any.
+     *
+     * @return {Element[]}
+     * @protected
+     */
+    _getFocusableIndex() {
+      const items = this._getItems();
+      return Array.isArray(items) ? this._getAvailableIndex(items, 0, null, (item) => !isElementHidden(item)) : -1;
+    }
+
     /**
      * Get the list of items participating in keyboard navigation.
      * By default, it treats all the light DOM children as items.
@@ -104,17 +116,18 @@ export const KeyboardDirectionMixin = (superclass) =>
       if (
         this._tabNavigation &&
         key === 'Tab' &&
-        ((idx > currentIdx && event.shiftKey) || (idx < currentIdx && !event.shiftKey))
+        ((idx > currentIdx && event.shiftKey) || (idx < currentIdx && !event.shiftKey) || idx === currentIdx)
       ) {
         // Prevent "roving tabindex" logic and let the normal Tab behavior if
         // - currently on the first focusable item and Shift + Tab is pressed,
-        // - currently on the last focusable item and Tab is pressed.
+        // - currently on the last focusable item and Tab is pressed,
+        // - currently on the only focusable item and Tab is pressed
         return;
       }
 
       if (idx >= 0) {
         event.preventDefault();
-        this._focus(idx, true);
+        this._focus(idx, { focusVisible: true }, true);
       }
     }
 
@@ -150,30 +163,27 @@ export const KeyboardDirectionMixin = (superclass) =>
      * Focus the item at given index. Override this method to add custom logic.
      *
      * @param {number} index
+     * @param {FocusOptions=} options
      * @param {boolean} navigating
      * @protected
      */
-    _focus(index, navigating = false) {
+    _focus(index, options, navigating = false) {
       const items = this._getItems();
 
-      this._focusItem(items[index], navigating);
+      this._focusItem(items[index], options, navigating);
     }
 
     /**
      * Focus the given item. Override this method to add custom logic.
      *
      * @param {Element} item
+     * @param {FocusOptions=} options
      * @param {boolean} navigating
      * @protected
      */
-    _focusItem(item) {
+    _focusItem(item, options) {
       if (item) {
-        item.focus();
-
-        // Generally, the items are expected to implement `FocusMixin`
-        // that would set this attribute based on the `keydown` event.
-        // We set it manually to handle programmatic focus() calls.
-        item.setAttribute('focus-ring', '');
+        item.focus(options);
       }
     }
 

package/src/list-mixin.d.ts

@@ -36,15 +36,9 @@ export declare class ListMixinClass {
   orientation: 'horizontal' | 'vertical';
 
   /**
-   * The list of items from which a selection can be made.
+   * A read-only list of items from which a selection can be made.
    * It is populated from the elements passed to the light DOM,
    * and updated dynamically when adding or removing items.
-   *
-   * The item elements must implement `Vaadin.ItemMixin`.
-   *
-   * Note: unlike `<vaadin-combo-box>`, this property is read-only,
-   * so if you want to provide items by iterating array of data,
-   * you have to use `dom-repeat` and place it to the light DOM.
    */
   readonly items: Element[] | undefined;
 

package/src/list-mixin.js

@@ -6,7 +6,6 @@
 import { timeOut } from '@vaadin/component-base/src/async.js';
 import { Debouncer } from '@vaadin/component-base/src/debounce.js';
 import { getNormalizedScrollLeft, setNormalizedScrollLeft } from '@vaadin/component-base/src/dir-utils.js';
-import { getFlattenedElements } from '@vaadin/component-base/src/dom-utils.js';
 import { SlotObserver } from '@vaadin/component-base/src/slot-observer.js';
 import { isElementHidden } from './focus-utils.js';
 import { KeyboardDirectionMixin } from './keyboard-direction-mixin.js';
@@ -56,15 +55,9 @@ export const ListMixin = (superClass) =>
         },
 
         /**
-         * The list of items from which a selection can be made.
+         * A read-only list of items from which a selection can be made.
          * It is populated from the elements passed to the light DOM,
          * and updated dynamically when adding or removing items.
-         *
-         * The item elements must implement `Vaadin.ItemMixin`.
-         *
-         * Note: unlike `<vaadin-combo-box>`, this property is read-only,
-         * so if you want to provide items by iterating array of data,
-         * you have to use `dom-repeat` and place it to the light DOM.
          * @type {!Array<!Element> | undefined}
          */
         items: {
@@ -114,7 +107,12 @@ export const ListMixin = (superClass) =>
       return this.orientation !== 'horizontal';
     }
 
-    focus() {
+    /**
+     * @param {FocusOptions=} options
+     * @protected
+     * @override
+     */
+    focus(options) {
       // In initialization (e.g vaadin-select) observer might not been run yet.
       if (this._observer) {
         this._observer.flush();
@@ -123,10 +121,10 @@ export const ListMixin = (superClass) =>
       const items = Array.isArray(this.items) ? this.items : [];
       const idx = this._getAvailableIndex(items, 0, null, (item) => item.tabIndex === 0 && !isElementHidden(item));
       if (idx >= 0) {
-        this._focus(idx);
+        this._focus(idx, options);
       } else {
         // Call `KeyboardDirectionMixin` logic to focus first non-disabled item.
-        super.focus();
+        super.focus(options);
       }
     }
 
@@ -138,7 +136,7 @@ export const ListMixin = (superClass) =>
 
       const slot = this.shadowRoot.querySelector('slot:not([name])');
       this._observer = new SlotObserver(slot, () => {
-        this._setItems(this._filterItems(getFlattenedElements(this)));
+        this._setItems(this._filterItems([...this.children]));
       });
     }
 
@@ -282,13 +280,13 @@ export const ListMixin = (superClass) =>
      * @param {number} idx
      * @protected
      */
-    _focus(idx) {
+    _focus(idx, options) {
       this.items.forEach((e, index) => {
         e.focused = index === idx;
       });
       this._setFocusable(idx);
       this._scrollToItem(idx);
-      super._focus(idx);
+      super._focus(idx, options);
     }
 
     /**

package/src/tabindex-mixin.js

@@ -95,12 +95,13 @@ export const TabindexMixin = (superclass) =>
      * `tabindex` to -1 does not prevent the element from being
      * programmatically focusable.
      *
+     * @param {FocusOptions=} options
      * @protected
      * @override
      */
-    focus() {
+    focus(options) {
       if (!this.disabled || this.__shouldAllowFocusWhenDisabled()) {
-        super.focus();
+        super.focus(options);
       }
     }