@vaadin/a11y-base 25.2.0-alpha8 → 25.2.0-beta1

package/custom-elements.json

@@ -10,7 +10,22 @@
           "kind": "mixin",
           "description": "A mixin to toggle the `active` attribute.\n\nThe attribute is set whenever the user activates the element by a pointer\nor presses an activation key on the element from the keyboard.\n\nThe attribute is removed as soon as the element is deactivated\nby the pointer or by releasing the activation key.",
           "name": "ActiveMixin",
-          "members": [],
+          "members": [
+            {
+              "kind": "field",
+              "name": "disabled",
+              "privacy": "public",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "If true, the user cannot interact with this element.",
+              "attribute": "disabled",
+              "inheritedFrom": {
+                "name": "DisabledMixin",
+                "module": "src/disabled-mixin.js"
+              }
+            }
+          ],
           "mixins": [
             {
               "name": "DisabledMixin",
@@ -25,6 +40,20 @@
             {
               "name": "superclass"
             }
+          ],
+          "attributes": [
+            {
+              "name": "disabled",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "If true, the user cannot interact with this element.",
+              "fieldName": "disabled",
+              "inheritedFrom": {
+                "name": "DisabledMixin",
+                "module": "src/disabled-mixin.js"
+              }
+            }
           ]
         }
       ],
@@ -44,9 +73,76 @@
       "path": "src/delegate-focus-mixin.js",
       "declarations": [
         {
-          "kind": "variable",
+          "kind": "mixin",
+          "description": "",
           "name": "DelegateFocusMixin",
-          "description": "A mixin to forward focus to an element in the light DOM."
+          "members": [
+            {
+              "kind": "field",
+              "name": "autofocus",
+              "privacy": "public",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Specify that this control should have input focus when the page loads.",
+              "attribute": "autofocus"
+            },
+            {
+              "kind": "field",
+              "name": "disabled",
+              "privacy": "public",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "If true, the user cannot interact with this element.",
+              "attribute": "disabled",
+              "inheritedFrom": {
+                "name": "DisabledMixin",
+                "module": "src/disabled-mixin.js"
+              }
+            }
+          ],
+          "attributes": [
+            {
+              "name": "autofocus",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Specify that this control should have input focus when the page loads.",
+              "fieldName": "autofocus"
+            },
+            {
+              "name": "disabled",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "If true, the user cannot interact with this element.",
+              "fieldName": "disabled",
+              "inheritedFrom": {
+                "name": "DisabledMixin",
+                "module": "src/disabled-mixin.js"
+              }
+            }
+          ],
+          "mixins": [
+            {
+              "name": "FocusMixin",
+              "module": "src/focus-mixin.js"
+            },
+            {
+              "name": "TabindexMixin",
+              "module": "src/tabindex-mixin.js"
+            },
+            {
+              "name": "dedupeMixin",
+              "package": "@open-wc/dedupe-mixin"
+            }
+          ],
+          "parameters": [
+            {
+              "name": "superclass"
+            }
+          ]
         }
       ],
       "exports": [
@@ -65,9 +161,42 @@
       "path": "src/disabled-mixin.js",
       "declarations": [
         {
-          "kind": "variable",
+          "kind": "mixin",
+          "description": "",
           "name": "DisabledMixin",
-          "description": "A mixin to provide disabled property for field components."
+          "members": [
+            {
+              "kind": "field",
+              "name": "disabled",
+              "privacy": "public",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "If true, the user cannot interact with this element.",
+              "attribute": "disabled"
+            }
+          ],
+          "attributes": [
+            {
+              "name": "disabled",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "If true, the user cannot interact with this element.",
+              "fieldName": "disabled"
+            }
+          ],
+          "parameters": [
+            {
+              "name": "superclass"
+            }
+          ],
+          "mixins": [
+            {
+              "name": "dedupeMixin",
+              "package": "@open-wc/dedupe-mixin"
+            }
+          ]
         }
       ],
       "exports": [
@@ -86,9 +215,21 @@
       "path": "src/focus-mixin.js",
       "declarations": [
         {
-          "kind": "variable",
+          "kind": "mixin",
+          "description": "",
           "name": "FocusMixin",
-          "description": "A mixin to handle `focused` and `focus-ring` attributes based on focus."
+          "members": [],
+          "parameters": [
+            {
+              "name": "superclass"
+            }
+          ],
+          "mixins": [
+            {
+              "name": "dedupeMixin",
+              "package": "@open-wc/dedupe-mixin"
+            }
+          ]
         }
       ],
       "exports": [
@@ -140,9 +281,21 @@
       "path": "src/keyboard-mixin.js",
       "declarations": [
         {
-          "kind": "variable",
+          "kind": "mixin",
+          "description": "",
           "name": "KeyboardMixin",
-          "description": "A mixin that manages keyboard handling.\nThe mixin subscribes to the keyboard events while an actual implementation\nfor the event handlers is left to the client (a component or another mixin)."
+          "members": [],
+          "parameters": [
+            {
+              "name": "superclass"
+            }
+          ],
+          "mixins": [
+            {
+              "name": "dedupeMixin",
+              "package": "@open-wc/dedupe-mixin"
+            }
+          ]
         }
       ],
       "exports": [
@@ -265,8 +418,36 @@
           "kind": "mixin",
           "description": "A mixin to toggle the `tabindex` attribute.\n\nThe attribute is set to -1 whenever the user disables the element\nand restored with the last known value once the element is enabled.",
           "name": "TabindexMixin",
-          "members": [],
-          "attributes": [],
+          "members": [
+            {
+              "kind": "field",
+              "name": "disabled",
+              "privacy": "public",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "If true, the user cannot interact with this element.",
+              "attribute": "disabled",
+              "inheritedFrom": {
+                "name": "DisabledMixin",
+                "module": "src/disabled-mixin.js"
+              }
+            }
+          ],
+          "attributes": [
+            {
+              "name": "disabled",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "If true, the user cannot interact with this element.",
+              "fieldName": "disabled",
+              "inheritedFrom": {
+                "name": "DisabledMixin",
+                "module": "src/disabled-mixin.js"
+              }
+            }
+          ],
           "mixins": [
             {
               "name": "DisabledMixin",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vaadin/a11y-base",
-  "version": "25.2.0-alpha8",
+  "version": "25.2.0-beta1",
   "publishConfig": {
     "access": "public"
   },
@@ -32,15 +32,15 @@
   ],
   "dependencies": {
     "@open-wc/dedupe-mixin": "^1.3.0",
-    "@vaadin/component-base": "25.2.0-alpha8",
+    "@vaadin/component-base": "25.2.0-beta1",
     "lit": "^3.0.0"
   },
   "devDependencies": {
-    "@vaadin/chai-plugins": "25.2.0-alpha8",
-    "@vaadin/test-runner-commands": "25.2.0-alpha8",
+    "@vaadin/chai-plugins": "25.2.0-beta1",
+    "@vaadin/test-runner-commands": "25.2.0-beta1",
     "@vaadin/testing-helpers": "^2.0.0",
     "sinon": "^21.0.2"
   },
   "customElements": "custom-elements.json",
-  "gitHead": "2b82e20cdfc605b1187e9a24ae42869e1500ab68"
+  "gitHead": "471a23f60d1eb725f98a33f62cb9664d9c0a4163"
 }

package/src/active-mixin.js

@@ -15,10 +15,6 @@ import { KeyboardMixin } from './keyboard-mixin.js';
  *
  * The attribute is removed as soon as the element is deactivated
  * by the pointer or by releasing the activation key.
- *
- * @polymerMixin
- * @mixes DisabledMixin
- * @mixes KeyboardMixin
  */
 export const ActiveMixin = (superclass) =>
   class ActiveMixinClass extends DisabledMixin(KeyboardMixin(superclass)) {

package/src/announce.js

@@ -23,7 +23,7 @@ let alertDebouncer;
  */
 export function announce(text, options = {}) {
   const mode = options.mode || 'polite';
-  const timeout = options.timeout === undefined ? 150 : options.timeout;
+  const timeout = options.timeout ?? 150;
 
   if (mode === 'alert') {
     region.removeAttribute('aria-live');

package/src/aria-hidden.js

@@ -27,7 +27,7 @@ let lockCount = 0;
  * @param {?Node} node
  * @return {boolean}
  */
-const isElement = (node) => node && node.nodeType === Node.ELEMENT_NODE;
+const isElement = (node) => node?.nodeType === Node.ELEMENT_NODE;
 
 /**
  * @param  {...unknown} args

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

@@ -3,13 +3,12 @@
  * Copyright (c) 2021 - 2026 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
-import type { ReactiveController } from 'lit';
 
 /**
  * A controller for handling modal state on the elements with `dialog` and `alertdialog` role.
  * See https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-modal
  */
-export class AriaModalController implements ReactiveController {
+export class AriaModalController {
   /**
    * The controller host element.
    */
@@ -21,7 +20,7 @@ export class AriaModalController implements ReactiveController {
    */
   callback: () => HTMLElement | HTMLElement[];
 
-  constructor(node: HTMLElement);
+  constructor(host: HTMLElement, callback?: () => HTMLElement | HTMLElement[]);
 
   /**
    * Make the controller host element modal by trapping focus inside it and hiding

package/src/delegate-focus-mixin.js

@@ -9,237 +9,236 @@ import { TabindexMixin } from './tabindex-mixin.js';
 
 /**
  * A mixin to forward focus to an element in the light DOM.
- *
- * @polymerMixin
- * @mixes FocusMixin
- * @mixes TabindexMixin
  */
-export const DelegateFocusMixin = dedupeMixin(
-  (superclass) =>
-    class DelegateFocusMixinClass extends FocusMixin(TabindexMixin(superclass)) {
-      static get properties() {
-        return {
-          /**
-           * Specify that this control should have input focus when the page loads.
-           */
-          autofocus: {
-            type: Boolean,
-          },
-
-          /**
-           * A reference to the focusable element controlled by the mixin.
-           * It can be an input, textarea, button or any element with tabindex > -1.
-           *
-           * Any component implementing this mixin is expected to provide it
-           * by using `this._setFocusElement(input)` Polymer API.
-           *
-           * Toggling `tabindex` attribute on the host element propagates its value to `focusElement`.
-           *
-           * @protected
-           * @type {!HTMLElement}
-           */
-          focusElement: {
-            type: Object,
-            readOnly: true,
-            observer: '_focusElementChanged',
-            sync: true,
-          },
-
-          /**
-           * Override the property from `TabIndexMixin`
-           * to ensure the `tabindex` attribute of the focus element
-           * will be restored to `0` after re-enabling the element.
-           *
-           * @protected
-           * @override
-           */
-          _lastTabIndex: {
-            value: 0,
-          },
-        };
-      }
-
-      constructor() {
-        super();
-
-        this._boundOnBlur = this._onBlur.bind(this);
-        this._boundOnFocus = this._onFocus.bind(this);
-      }
-
-      /** @protected */
-      ready() {
-        super.ready();
-
-        if (this.autofocus && !this.disabled) {
-          requestAnimationFrame(() => {
-            this.focus();
-          });
-        }
-      }
-
-      /**
-       * @param {FocusOptions=} options
-       * @protected
-       * @override
-       */
-      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', '');
-          }
-        }
-      }
-
-      /**
-       * @protected
-       * @override
-       */
-      blur() {
-        if (this.focusElement) {
-          this.focusElement.blur();
+const DelegateFocusMixinImplementation = (superclass) => {
+  return class DelegateFocusMixinClass extends FocusMixin(TabindexMixin(superclass)) {
+    static get properties() {
+      return {
+        /**
+         * Specify that this control should have input focus when the page loads.
+         */
+        autofocus: {
+          type: Boolean,
+        },
+
+        /**
+         * A reference to the focusable element controlled by the mixin.
+         * It can be an input, textarea, button or any element with tabindex > -1.
+         *
+         * Any component implementing this mixin is expected to provide it
+         * by using `this._setFocusElement(input)` Polymer API.
+         *
+         * Toggling `tabindex` attribute on the host element propagates its value to `focusElement`.
+         *
+         * @protected
+         * @type {!HTMLElement}
+         */
+        focusElement: {
+          type: Object,
+          readOnly: true,
+          observer: '_focusElementChanged',
+          sync: true,
+        },
+
+        /**
+         * Override the property from `TabIndexMixin`
+         * to ensure the `tabindex` attribute of the focus element
+         * will be restored to `0` after re-enabling the element.
+         *
+         * @protected
+         * @override
+         */
+        _lastTabIndex: {
+          value: 0,
+        },
+      };
+    }
+
+    constructor() {
+      super();
+
+      this._boundOnBlur = this._onBlur.bind(this);
+      this._boundOnFocus = this._onFocus.bind(this);
+    }
+
+    /** @protected */
+    ready() {
+      super.ready();
+
+      if (this.autofocus && !this.disabled) {
+        requestAnimationFrame(() => {
+          this.focus();
+        });
+      }
+    }
+
+    /**
+     * @param {FocusOptions=} options
+     * @protected
+     * @override
+     */
+    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?.focusVisible !== false) {
+          this.setAttribute('focus-ring', '');
         }
       }
-
-      /**
-       * @protected
-       * @override
-       */
-      click() {
-        if (this.focusElement && !this.disabled) {
-          this.focusElement.click();
+    }
+
+    /**
+     * @protected
+     * @override
+     */
+    blur() {
+      if (this.focusElement) {
+        this.focusElement.blur();
+      }
+    }
+
+    /**
+     * @protected
+     * @override
+     */
+    click() {
+      if (this.focusElement && !this.disabled) {
+        this.focusElement.click();
+      }
+    }
+
+    /** @protected */
+    _focusElementChanged(element, oldElement) {
+      if (element) {
+        element.disabled = this.disabled;
+        this._addFocusListeners(element);
+        this.__forwardTabIndex(this.tabindex);
+      } else if (oldElement) {
+        this._removeFocusListeners(oldElement);
+      }
+    }
+
+    /**
+     * @param {HTMLElement} element
+     * @protected
+     */
+    _addFocusListeners(element) {
+      element.addEventListener('blur', this._boundOnBlur);
+      element.addEventListener('focus', this._boundOnFocus);
+    }
+
+    /**
+     * @param {HTMLElement} element
+     * @protected
+     */
+    _removeFocusListeners(element) {
+      element.removeEventListener('blur', this._boundOnBlur);
+      element.removeEventListener('focus', this._boundOnFocus);
+    }
+
+    /**
+     * Focus event does not bubble, so we dispatch it manually
+     * on the host element to support adding focus listeners
+     * when the focusable element is placed in light DOM.
+     * @param {FocusEvent} event
+     * @protected
+     */
+    _onFocus(event) {
+      event.stopPropagation();
+      /** @internal to not document it in CEM */
+      this.dispatchEvent(new Event('focus'));
+    }
+
+    /**
+     * Blur event does not bubble, so we dispatch it manually
+     * on the host element to support adding blur listeners
+     * when the focusable element is placed in light DOM.
+     * @param {FocusEvent} event
+     * @protected
+     */
+    _onBlur(event) {
+      event.stopPropagation();
+      /** @internal to not document it in CEM */
+      this.dispatchEvent(new Event('blur'));
+    }
+
+    /**
+     * @param {FocusEvent} event
+     * @return {boolean}
+     * @protected
+     * @override
+     */
+    _shouldSetFocus(event) {
+      return event.target === this.focusElement;
+    }
+
+    /**
+     * @param {FocusEvent} event
+     * @return {boolean}
+     * @protected
+     * @override
+     */
+    _shouldRemoveFocus(event) {
+      return event.target === this.focusElement;
+    }
+
+    /**
+     * @param {boolean} disabled
+     * @param {boolean} oldDisabled
+     * @protected
+     * @override
+     */
+    _disabledChanged(disabled, oldDisabled) {
+      super._disabledChanged(disabled, oldDisabled);
+
+      if (this.focusElement) {
+        this.focusElement.disabled = disabled;
+      }
+
+      if (disabled) {
+        this.blur();
+      }
+    }
+
+    /**
+     * Override an observer from `TabindexMixin`.
+     * Do not call super to remove tabindex attribute
+     * from the host after it has been forwarded.
+     * @param {string} tabindex
+     * @protected
+     * @override
+     */
+    _tabindexChanged(tabindex) {
+      this.__forwardTabIndex(tabindex);
+    }
+
+    /** @private */
+    __forwardTabIndex(tabindex) {
+      if (tabindex !== undefined && this.focusElement) {
+        this.focusElement.tabIndex = tabindex;
+
+        // Preserve tabindex="-1" on the host element
+        if (tabindex !== -1) {
+          this.tabindex = undefined;
         }
       }
 
-      /** @protected */
-      _focusElementChanged(element, oldElement) {
-        if (element) {
-          element.disabled = this.disabled;
-          this._addFocusListeners(element);
-          this.__forwardTabIndex(this.tabindex);
-        } else if (oldElement) {
-          this._removeFocusListeners(oldElement);
+      if (this.disabled && tabindex) {
+        // If tabindex attribute was changed while component was disabled
+        if (tabindex !== -1) {
+          this._lastTabIndex = tabindex;
         }
+        this.tabindex = undefined;
       }
 
-      /**
-       * @param {HTMLElement} element
-       * @protected
-       */
-      _addFocusListeners(element) {
-        element.addEventListener('blur', this._boundOnBlur);
-        element.addEventListener('focus', this._boundOnFocus);
-      }
-
-      /**
-       * @param {HTMLElement} element
-       * @protected
-       */
-      _removeFocusListeners(element) {
-        element.removeEventListener('blur', this._boundOnBlur);
-        element.removeEventListener('focus', this._boundOnFocus);
-      }
-
-      /**
-       * Focus event does not bubble, so we dispatch it manually
-       * on the host element to support adding focus listeners
-       * when the focusable element is placed in light DOM.
-       * @param {FocusEvent} event
-       * @protected
-       */
-      _onFocus(event) {
-        event.stopPropagation();
-        this.dispatchEvent(new Event('focus'));
-      }
-
-      /**
-       * Blur event does not bubble, so we dispatch it manually
-       * on the host element to support adding blur listeners
-       * when the focusable element is placed in light DOM.
-       * @param {FocusEvent} event
-       * @protected
-       */
-      _onBlur(event) {
-        event.stopPropagation();
-        this.dispatchEvent(new Event('blur'));
+      // Lit does not remove attribute when setting property to undefined
+      if (tabindex === undefined && this.hasAttribute('tabindex')) {
+        this.removeAttribute('tabindex');
       }
+    }
+  };
+};
 
-      /**
-       * @param {FocusEvent} event
-       * @return {boolean}
-       * @protected
-       * @override
-       */
-      _shouldSetFocus(event) {
-        return event.target === this.focusElement;
-      }
-
-      /**
-       * @param {FocusEvent} event
-       * @return {boolean}
-       * @protected
-       * @override
-       */
-      _shouldRemoveFocus(event) {
-        return event.target === this.focusElement;
-      }
-
-      /**
-       * @param {boolean} disabled
-       * @param {boolean} oldDisabled
-       * @protected
-       * @override
-       */
-      _disabledChanged(disabled, oldDisabled) {
-        super._disabledChanged(disabled, oldDisabled);
-
-        if (this.focusElement) {
-          this.focusElement.disabled = disabled;
-        }
-
-        if (disabled) {
-          this.blur();
-        }
-      }
-
-      /**
-       * Override an observer from `TabindexMixin`.
-       * Do not call super to remove tabindex attribute
-       * from the host after it has been forwarded.
-       * @param {string} tabindex
-       * @protected
-       * @override
-       */
-      _tabindexChanged(tabindex) {
-        this.__forwardTabIndex(tabindex);
-      }
-
-      /** @private */
-      __forwardTabIndex(tabindex) {
-        if (tabindex !== undefined && this.focusElement) {
-          this.focusElement.tabIndex = tabindex;
-
-          // Preserve tabindex="-1" on the host element
-          if (tabindex !== -1) {
-            this.tabindex = undefined;
-          }
-        }
-
-        if (this.disabled && tabindex) {
-          // If tabindex attribute was changed while component was disabled
-          if (tabindex !== -1) {
-            this._lastTabIndex = tabindex;
-          }
-          this.tabindex = undefined;
-        }
-
-        // Lit does not remove attribute when setting property to undefined
-        if (tabindex === undefined && this.hasAttribute('tabindex')) {
-          this.removeAttribute('tabindex');
-        }
-      }
-    },
-);
+export const DelegateFocusMixin = dedupeMixin(DelegateFocusMixinImplementation);

package/src/disabled-mixin.js

@@ -7,57 +7,56 @@ import { dedupeMixin } from '@open-wc/dedupe-mixin';
 
 /**
  * A mixin to provide disabled property for field components.
- *
- * @polymerMixin
  */
-export const DisabledMixin = dedupeMixin(
-  (superclass) =>
-    class DisabledMixinClass extends superclass {
-      static get properties() {
-        return {
-          /**
-           * If true, the user cannot interact with this element.
-           */
-          disabled: {
-            type: Boolean,
-            value: false,
-            observer: '_disabledChanged',
-            reflectToAttribute: true,
-            sync: true,
-          },
-        };
-      }
+const DisabledMixinImplementation = (superclass) => {
+  return class DisabledMixinClass extends superclass {
+    static get properties() {
+      return {
+        /**
+         * If true, the user cannot interact with this element.
+         */
+        disabled: {
+          type: Boolean,
+          value: false,
+          observer: '_disabledChanged',
+          reflectToAttribute: true,
+          sync: true,
+        },
+      };
+    }
 
-      /**
-       * @param {boolean} disabled
-       * @protected
-       */
-      _disabledChanged(disabled) {
-        this._setAriaDisabled(disabled);
-      }
+    /**
+     * @param {boolean} disabled
+     * @protected
+     */
+    _disabledChanged(disabled) {
+      this._setAriaDisabled(disabled);
+    }
 
-      /**
-       * @param {boolean} disabled
-       * @protected
-       */
-      _setAriaDisabled(disabled) {
-        if (disabled) {
-          this.setAttribute('aria-disabled', 'true');
-        } else {
-          this.removeAttribute('aria-disabled');
-        }
+    /**
+     * @param {boolean} disabled
+     * @protected
+     */
+    _setAriaDisabled(disabled) {
+      if (disabled) {
+        this.setAttribute('aria-disabled', 'true');
+      } else {
+        this.removeAttribute('aria-disabled');
       }
+    }
 
-      /**
-       * Overrides the default element `click` method in order to prevent
-       * firing the `click` event when the element is disabled.
-       * @protected
-       * @override
-       */
-      click() {
-        if (!this.disabled) {
-          super.click();
-        }
+    /**
+     * Overrides the default element `click` method in order to prevent
+     * firing the `click` event when the element is disabled.
+     * @protected
+     * @override
+     */
+    click() {
+      if (!this.disabled) {
+        super.click();
       }
-    },
-);
+    }
+  };
+};
+
+export const DisabledMixin = dedupeMixin(DisabledMixinImplementation);

package/src/focus-mixin.js

@@ -8,101 +8,100 @@ import { isKeyboardActive } from './focus-utils.js';
 
 /**
  * A mixin to handle `focused` and `focus-ring` attributes based on focus.
- *
- * @polymerMixin
  */
-export const FocusMixin = dedupeMixin(
-  (superclass) =>
-    class FocusMixinClass extends superclass {
-      /**
-       * @protected
-       * @return {boolean}
-       */
-      get _keyboardActive() {
-        return isKeyboardActive();
-      }
+const FocusMixinImplementation = (superclass) => {
+  return class FocusMixinClass extends superclass {
+    /**
+     * @protected
+     * @return {boolean}
+     */
+    get _keyboardActive() {
+      return isKeyboardActive();
+    }
 
-      /** @protected */
-      ready() {
-        this.addEventListener('focusin', (e) => {
-          if (this._shouldSetFocus(e)) {
-            this._setFocused(true);
-          }
-        });
+    /** @protected */
+    ready() {
+      this.addEventListener('focusin', (e) => {
+        if (this._shouldSetFocus(e)) {
+          this._setFocused(true);
+        }
+      });
 
-        this.addEventListener('focusout', (e) => {
-          if (this._shouldRemoveFocus(e)) {
-            this._setFocused(false);
-          }
-        });
+      this.addEventListener('focusout', (e) => {
+        if (this._shouldRemoveFocus(e)) {
+          this._setFocused(false);
+        }
+      });
 
-        // In super.ready() other 'focusin' and 'focusout' listeners might be
-        // added, so we call it after our own ones to ensure they execute first.
-        // Issue to watch out: when incorrect, <vaadin-combo-box> refocuses the
-        // input field on iOS after "Done" is pressed.
-        super.ready();
-      }
+      // In super.ready() other 'focusin' and 'focusout' listeners might be
+      // added, so we call it after our own ones to ensure they execute first.
+      // Issue to watch out: when incorrect, <vaadin-combo-box> refocuses the
+      // input field on iOS after "Done" is pressed.
+      super.ready();
+    }
 
-      /** @protected */
-      disconnectedCallback() {
-        super.disconnectedCallback();
+    /** @protected */
+    disconnectedCallback() {
+      super.disconnectedCallback();
 
-        // In non-Chrome browsers, blur does not fire on the element when it is disconnected.
-        // reproducible in `<vaadin-date-picker>` when closing on `Cancel` or `Today` click.
-        if (this.hasAttribute('focused')) {
-          this._setFocused(false);
-        }
+      // In non-Chrome browsers, blur does not fire on the element when it is disconnected.
+      // reproducible in `<vaadin-date-picker>` when closing on `Cancel` or `Today` click.
+      if (this.hasAttribute('focused')) {
+        this._setFocused(false);
       }
+    }
 
-      /**
-       * @param {FocusOptions=} options
-       * @protected
-       * @override
-       */
-      focus(options) {
-        super.focus(options);
+    /**
+     * @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', '');
-        }
+      // Set focus-ring attribute on programmatic focus by default
+      // unless explicitly disabled by `{ focusVisible: false }`.
+      if (options?.focusVisible !== false) {
+        this.setAttribute('focus-ring', '');
       }
+    }
 
-      /**
-       * Override to change how focused and focus-ring attributes are set.
-       *
-       * @param {boolean} focused
-       * @protected
-       */
-      _setFocused(focused) {
-        this.toggleAttribute('focused', focused);
+    /**
+     * Override to change how focused and focus-ring attributes are set.
+     *
+     * @param {boolean} focused
+     * @protected
+     */
+    _setFocused(focused) {
+      this.toggleAttribute('focused', focused);
 
-        // Focus-ring is true when the element was focused from the keyboard.
-        // Focus Ring [A11ycasts]: https://youtu.be/ilj2P5-5CjI
-        this.toggleAttribute('focus-ring', focused && this._keyboardActive);
-      }
+      // Focus-ring is true when the element was focused from the keyboard.
+      // Focus Ring [A11ycasts]: https://youtu.be/ilj2P5-5CjI
+      this.toggleAttribute('focus-ring', focused && this._keyboardActive);
+    }
 
-      /**
-       * Override to define if the field receives focus based on the event.
-       *
-       * @param {FocusEvent} _event
-       * @return {boolean}
-       * @protected
-       */
-      _shouldSetFocus(_event) {
-        return true;
-      }
+    /**
+     * Override to define if the field receives focus based on the event.
+     *
+     * @param {FocusEvent} _event
+     * @return {boolean}
+     * @protected
+     */
+    _shouldSetFocus(_event) {
+      return true;
+    }
 
-      /**
-       * Override to define if the field loses focus based on the event.
-       *
-       * @param {FocusEvent} _event
-       * @return {boolean}
-       * @protected
-       */
-      _shouldRemoveFocus(_event) {
-        return true;
-      }
-    },
-);
+    /**
+     * Override to define if the field loses focus based on the event.
+     *
+     * @param {FocusEvent} _event
+     * @return {boolean}
+     * @protected
+     */
+    _shouldRemoveFocus(_event) {
+      return true;
+    }
+  };
+};
+
+export const FocusMixin = dedupeMixin(FocusMixinImplementation);

package/src/keyboard-direction-mixin.js

@@ -8,9 +8,6 @@ import { KeyboardMixin } from './keyboard-mixin.js';
 
 /**
  * A mixin for navigating items with keyboard.
- *
- * @polymerMixin
- * @mixes KeyboardMixin
  */
 export const KeyboardDirectionMixin = (superclass) =>
   class KeyboardDirectionMixinClass extends KeyboardMixin(superclass) {
@@ -127,7 +124,7 @@ export const KeyboardDirectionMixin = (superclass) =>
 
       if (idx >= 0) {
         event.preventDefault();
-        this._focus(idx, { focusVisible: true }, true);
+        this._focus(idx, { focusVisible: true, preventScroll: true }, true);
       }
     }
 

package/src/keyboard-mixin.js

@@ -9,77 +9,76 @@ import { dedupeMixin } from '@open-wc/dedupe-mixin';
  * A mixin that manages keyboard handling.
  * The mixin subscribes to the keyboard events while an actual implementation
  * for the event handlers is left to the client (a component or another mixin).
- *
- * @polymerMixin
  */
-export const KeyboardMixin = dedupeMixin(
-  (superclass) =>
-    class KeyboardMixinClass extends superclass {
-      /** @protected */
-      ready() {
-        super.ready();
+const KeyboardMixinImplementation = (superclass) => {
+  return class KeyboardMixinClass extends superclass {
+    /** @protected */
+    ready() {
+      super.ready();
 
-        this.addEventListener('keydown', (event) => {
-          this._onKeyDown(event);
-        });
+      this.addEventListener('keydown', (event) => {
+        this._onKeyDown(event);
+      });
 
-        this.addEventListener('keyup', (event) => {
-          this._onKeyUp(event);
-        });
-      }
+      this.addEventListener('keyup', (event) => {
+        this._onKeyUp(event);
+      });
+    }
 
-      /**
-       * A handler for the `keydown` event. By default, it calls
-       * separate methods for handling "Enter" and "Escape" keys.
-       * Override the method to implement your own behavior.
-       *
-       * @param {KeyboardEvent} event
-       * @protected
-       */
-      _onKeyDown(event) {
-        switch (event.key) {
-          case 'Enter':
-            this._onEnter(event);
-            break;
-          case 'Escape':
-            this._onEscape(event);
-            break;
-          default:
-            break;
-        }
+    /**
+     * A handler for the `keydown` event. By default, it calls
+     * separate methods for handling "Enter" and "Escape" keys.
+     * Override the method to implement your own behavior.
+     *
+     * @param {KeyboardEvent} event
+     * @protected
+     */
+    _onKeyDown(event) {
+      switch (event.key) {
+        case 'Enter':
+          this._onEnter(event);
+          break;
+        case 'Escape':
+          this._onEscape(event);
+          break;
+        default:
+          break;
       }
+    }
 
-      /**
-       * A handler for the `keyup` event. By default, it does nothing.
-       * Override the method to implement your own behavior.
-       *
-       * @param {KeyboardEvent} _event
-       * @protected
-       */
-      _onKeyUp(_event) {
-        // To be implemented.
-      }
+    /**
+     * A handler for the `keyup` event. By default, it does nothing.
+     * Override the method to implement your own behavior.
+     *
+     * @param {KeyboardEvent} _event
+     * @protected
+     */
+    _onKeyUp(_event) {
+      // To be implemented.
+    }
 
-      /**
-       * A handler for the "Enter" key. By default, it does nothing.
-       * Override the method to implement your own behavior.
-       *
-       * @param {KeyboardEvent} _event
-       * @protected
-       */
-      _onEnter(_event) {
-        // To be implemented.
-      }
+    /**
+     * A handler for the "Enter" key. By default, it does nothing.
+     * Override the method to implement your own behavior.
+     *
+     * @param {KeyboardEvent} _event
+     * @protected
+     */
+    _onEnter(_event) {
+      // To be implemented.
+    }
 
-      /**
-       * A handler for the "Escape" key. By default, it does nothing.
-       * Override the method to implement your own behavior.
-       *
-       * @param {KeyboardEvent} _event
-       * @protected
-       */
-      _onEscape(_event) {
-        // To be implemented.
-      }
-    },
-);
+    /**
+     * A handler for the "Escape" key. By default, it does nothing.
+     * Override the method to implement your own behavior.
+     *
+     * @param {KeyboardEvent} _event
+     * @protected
+     */
+    _onEscape(_event) {
+      // To be implemented.
+    }
+  };
+};
+
+export const KeyboardMixin = dedupeMixin(KeyboardMixinImplementation);

package/src/list-mixin.js

@@ -12,9 +12,6 @@ import { KeyboardDirectionMixin } from './keyboard-direction-mixin.js';
 
 /**
  * A mixin for list elements, facilitating navigation and selection of items.
- *
- * @polymerMixin
- * @mixes KeyboardDirectionMixin
  */
 export const ListMixin = (superClass) =>
   class ListMixinClass extends KeyboardDirectionMixin(superClass) {
@@ -285,40 +282,19 @@ export const ListMixin = (superClass) =>
       });
       this._setFocusable(idx);
       this._scrollToItem(idx);
-      super._focus(idx, options);
+      super._focus(idx, options ?? { preventScroll: true });
     }
 
     /**
-     * Scroll the container to have the next item by the edge of the viewport.
+     * Scroll the container to have the item visible.
      * @param {number} idx
      * @protected
      */
     _scrollToItem(idx) {
-      const item = this.items[idx];
-      if (!item) {
-        return;
+      const item = this._getItems()[idx];
+      if (item) {
+        item.scrollIntoView({ block: 'nearest', inline: 'nearest' });
       }
-
-      const props = this._vertical ? ['top', 'bottom'] : this._isRTL ? ['right', 'left'] : ['left', 'right'];
-
-      const scrollerRect = this._scrollerElement.getBoundingClientRect();
-      const nextItemRect = (this.items[idx + 1] || item).getBoundingClientRect();
-      const prevItemRect = (this.items[idx - 1] || item).getBoundingClientRect();
-
-      let scrollDistance = 0;
-      if (
-        (!this._isRTL && nextItemRect[props[1]] >= scrollerRect[props[1]]) ||
-        (this._isRTL && nextItemRect[props[1]] <= scrollerRect[props[1]])
-      ) {
-        scrollDistance = nextItemRect[props[1]] - scrollerRect[props[1]];
-      } else if (
-        (!this._isRTL && prevItemRect[props[0]] <= scrollerRect[props[0]]) ||
-        (this._isRTL && prevItemRect[props[0]] >= scrollerRect[props[0]])
-      ) {
-        scrollDistance = prevItemRect[props[0]] - scrollerRect[props[0]];
-      }
-
-      this._scroll(scrollDistance);
     }
 
     /**
@@ -336,11 +312,18 @@ export const ListMixin = (superClass) =>
     }
 
     /**
-     * Fired when the selection is changed.
-     * Not fired when used in `multiple` selection mode.
+     * Override method inherited from `KeyboardDirectionMixin` to allow
+     * focusing disabled items that are configured so.
      *
-     * @event selected-changed
-     * @param {Object} detail
-     * @param {Object} detail.value the index of the item selected in the items array.
+     * @param {Element} item
+     * @protected
+     * @override
      */
+    _isItemFocusable(item) {
+      if (item.disabled && item.__shouldAllowFocusWhenDisabled) {
+        return item.__shouldAllowFocusWhenDisabled();
+      }
+
+      return super._isItemFocusable(item);
+    }
   };

package/src/tabindex-mixin.js

@@ -10,9 +10,6 @@ import { DisabledMixin } from './disabled-mixin.js';
  *
  * The attribute is set to -1 whenever the user disables the element
  * and restored with the last known value once the element is enabled.
- *
- * @polymerMixin
- * @mixes DisabledMixin
  */
 export const TabindexMixin = (superclass) =>
   class TabindexMixinClass extends DisabledMixin(superclass) {