@lion/ui 0.22.0 → 0.23.0

package/components/menu/src/InteractiveListMixin.js

@@ -0,0 +1,867 @@
+/* eslint-disable max-classes-per-file */
+/* eslint-disable import/no-extraneous-dependencies */
+import { html, css, LitElement } from 'lit';
+import { SlotMixin, DisabledMixin, uuid } from '@lion/ui/core.js';
+import { dedupeMixin } from '@open-wc/dedupe-mixin';
+import { MoreButtonMenuMixin } from './MoreButtonMenuMixin.js';
+import { isInView } from './utils/isInView.js';
+import {
+  isDisabled,
+  isChecked,
+  setChecked,
+  toggleChecked,
+  isActive,
+  setActive,
+  getValue,
+} from './utils/listItemInteractions.js';
+
+/**
+ * @typedef {import('../types/InteractiveListMixinTypes.js').InteractiveListItemRole} InteractiveListItemRole
+ * @typedef {import('../types/InteractiveListMixinTypes.js').InteractiveListMixin} InteractiveListMixinType
+ */
+
+/**
+ * Platform alignment: this mixin is the equivalent of the
+ * [focusgroup](https://open-ui.org/components/focusgroup.explainer/) attribute (arrow key
+ * navigation inside a composite widget). The name stays: it is a public export and it covers
+ * listbox, menu/menubar, toolbar and tree alike. Its own api speaks the focusgroup vocabulary
+ * (`axis` with `inline`/`block`, `wrap`, `multiple`), so implementations that follow the platform
+ * proposal find the same names here.
+ */
+
+// TODO: make all available in controller/directive (same logic with an elegant prop-to-host-mapping)
+
+/**
+ * @param {Element} potentialFocusable
+ * @returns {Element|null}
+ */
+function isFocusableElement(potentialFocusable) {
+  // @ts-ignore - returns Element or falsy value
+  return (
+    potentialFocusable &&
+    (potentialFocusable.hasAttribute('tabindex') ||
+      ['BUTTON', 'A'].includes(potentialFocusable.tagName))
+  );
+}
+
+/**
+ * Lightweight component supporting InteractiveListItemRole as a type.
+ *
+ * Supports:
+ * - 1. menu item
+ * <lion-item> Item label </lion-item>
+ * - 2. sub menu
+ * <lion-item>
+ *   <button slot="invoker"> Item label </button>
+ *   <lion-menu slot="subitems"> ... </lion-menu>
+ * </lion-item>
+ *
+ * Sets the role property on the right element. For case 1, this would be the item itself,
+ * for case 2 it would be the [slot=invoker].
+ */
+export class LionItem extends LitElement {
+  /** @type {any} */
+  static get properties() {
+    return {
+      type: { type: String },
+    };
+  }
+
+  get _invokerNode() {
+    return /** @type {HTMLElement[]} */ (Array.from(this.children)).find(
+      child => child.slot === 'invoker',
+    );
+  }
+
+  static styles = [
+    css`
+      :host {
+        display: block;
+      }
+    `,
+  ];
+
+  constructor() {
+    super();
+    /** @type {InteractiveListItemRole |''} */
+    this.type = '';
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+
+    if (!this._computedType) {
+      this._computedType = this.type || 'listitem';
+    }
+    if (this._invokerNode) {
+      this._invokerNode.setAttribute('role', this._computedType);
+    } else {
+      this.setAttribute('role', this._computedType);
+    }
+  }
+
+  render() {
+    return html`
+      <slot name="invoker"></slot>
+      <slot></slot>
+    `;
+  }
+}
+
+export class LionMenuitem extends LionItem {
+  connectedCallback() {
+    this._computedType = `menuitem${this.type}`;
+    super.connectedCallback();
+  }
+}
+
+/**
+ * Handles keyboard interaction plus bookkeeping for active and selected states.
+ * Can be used as a fundament for:
+ * - [role="menu|menubar"] having children with [role="menuitem|menuitemcheckbox|menuitemradio"]
+ * - [role="listbox"] having children with [role="option"]
+ * - [role="toolbar"] having children with [role="radiogroup|radio|group|checkbox|spinbutton"]
+ * - [role="tree"] having children with [role="group|treeitem"]
+ *
+ * An interactive list accepts two types of items:
+ * - 'smart' items: responsible for registering themselves and reflecting accessibility properties,
+ * for example LionOption
+ * - 'regular' items with a [role="menuitem|menuitemcheckbox|menuitemradio|option|radio|checkbox|treeitem|listitem]
+ *
+ * Features:
+ * - keyboard navigation according to [aria specs](https://www.w3.org/TR/wai-aria-practices-1.1) for role
+ * - types
+ *
+ * @param {import('@open-wc/dedupe-mixin').Constructor<import('lit').LitElement>} superclass
+ */
+/**
+ * @type {InteractiveListMixinType}
+ * @param {import('@open-wc/dedupe-mixin').Constructor<import('lit').LitElement>} superclass
+ */
+// prettier-ignore
+const InteractiveListMixinImplementation = /** @type {InteractiveListMixinType} */ (superclass =>
+  class InteractiveListMixin extends DisabledMixin(SlotMixin(MoreButtonMenuMixin(superclass))) {
+    /** @type {any} */
+    static styles = [
+      css`
+        :host {
+          display: block;
+        }
+
+        :host([hidden]) {
+          display: none;
+        }
+
+        :host([disabled]) {
+          color: #adadad;
+        }
+
+        :host([axis='inline']) ::slotted([slot='list']) {
+          display: flex;
+        }
+      `,
+    ];
+
+    render() {
+      return html`
+        <slot name="list"></slot>
+        <slot></slot>
+      `;
+    }
+
+    static get properties() {
+      return {
+        /**
+         * The axis arrow keys navigate along, in the vocabulary of the
+         * [focusgroup](https://open-ui.org/components/focusgroup.explainer/) api: `'block'`
+         * (default: up/down) or `'inline'` (left/right).
+         */
+        axis: { type: String, reflect: true },
+        /**
+         * Whether more than one item can be checked. The platform name for this is `multiple`
+         * (`<select multiple>`); selection is explicitly not part of the focusgroup api.
+         */
+        multiple: { type: Boolean, attribute: 'multiple' },
+        /**
+         * Whether checking an item follows the active item. ARIA/APG vocabulary; selection is out of
+         * scope for the focusgroup api.
+         */
+        selectionFollowsFocus: { type: Boolean, attribute: 'selection-follows-focus' },
+        /**
+         * Whether arrow key navigation wraps around at the first/last item: the `wrap` modifier of
+         * the focusgroup api.
+         */
+        wrap: { type: Boolean, attribute: 'wrap' },
+        /**
+         * Whether no item is selected on initial render (`checkedIndex` stays -1). The platform name
+         * for the initial selectedness is "default selected" (`HTMLOptionElement.defaultSelected`,
+         * `HTMLInputElement.defaultChecked`, the HTML selectedness-setting algorithm); the opt-out is
+         * named the way the platform names its own opt-outs (`novalidate`, `nomodule`). Same property
+         * as `ListboxMixin` has, so a listbox and a menu can be configured alike.
+         */
+        hasNoDefaultSelected: { type: Boolean, reflect: true, attribute: 'has-no-default-selected' },
+
+        // TODO: implement, for now we start with only more-menu. See instructions in code about more menu.
+        // Values:
+        // - 'more-menu'
+        // - 'scroll-buttons' (think of those material design tab bars)
+        // - 'scroll-bar' (puts overflow: scroll on it) (think of tab bars, tables etc.)
+        itemWrap: { type: Boolean, attribute: 'item-wrap' },
+
+        _activateOnTypedChars: { type: Boolean },
+        _hasSmartListItems: { type: Boolean },
+        _activeMode: { type: String },
+      };
+    }
+
+    get slots() {
+      return {
+        ...super.slots,
+        list: () => document.createElement('div'),
+      };
+    }
+
+    /**
+     * This is the (usually focusable, unless combobox) element that will contain [aria-activedescendant]
+     * Depending on the children, role will be "listbox|menu|menubar|tree|toolbar"
+     * @type {HTMLElement}
+     */
+    get _listNode() {
+      return /** @type {HTMLElement} */ (Array.from(this.children).find(c => c.slot === 'list'));
+    }
+
+    get _scrollTargetNode() {
+      return this;
+    }
+
+    /**
+     * Place in the template that contains children with ._childrenRoles
+     * @type {HTMLSlotElement}
+     */
+    get _listItemsSlot() {
+      const slots = Array.from(
+        /** @type {ShadowRoot} */ (this.shadowRoot).querySelectorAll('slot'),
+      );
+      return /** @type {HTMLSlotElement} */ (slots.find(s => !s.name));
+    }
+
+    /**
+     * When used with FormRegistrarMixin, children will register themselves. Otherwise,
+     * __listItems are gathered via a slotchange listener
+     * @type {HTMLElement[]}
+     */
+    get listItems() {
+      // @ts-ignore
+      return this.__listItems || this.formElements;
+    }
+
+    /**
+     * The roles to look for when children are registered to listItems
+     * @overridable
+     * @type {InteractiveListItemRole[]}
+     */
+    // eslint-disable-next-line class-methods-use-this
+    get _childrenRoles() {
+      // @ts-ignore - string type in array of InteractiveListItemRole
+      return [...this._interactiveChildrenRoles, 'listitem', 'group'];
+    }
+
+    // eslint-disable-next-line class-methods-use-this
+    get _interactiveChildrenRoles() {
+      return ['menuitem', 'menuitemcheckbox', 'menuitemradio', 'option', 'treeitem'];
+    }
+
+    get activeIndex() {
+      return this.listItems.findIndex(el => isActive(el));
+    }
+
+    set activeIndex(index) {
+      const activeItem = this.listItems[index];
+
+      if (!activeItem) return;
+
+      const prevActiveEl = this.activeItem;
+      // This can be a focusable element or a wrapper thereof
+      const el = this.listItems[index];
+
+      // Unset siblings
+      this.listItems.forEach(item => {
+        setActive(item, true);
+      });
+      setActive(el);
+
+      // Determine focusableEl and prevFocusableEl
+
+      let focusableEl;
+      let prevFocusableEl;
+
+      if (this._activeMode === 'activedescendant') {
+        focusableEl = el;
+        prevFocusableEl = prevActiveEl;
+      }
+      // activeMode is 'roving-tabindex' or 'tabbable-disclosure'
+      else {
+        // are we a focusable element or a wrapper thereof?
+        focusableEl = isFocusableElement(el) ? el : el.firstElementChild;
+        prevFocusableEl =
+          prevActiveEl &&
+          (isFocusableElement(prevActiveEl) ? prevActiveEl : prevActiveEl.firstElementChild);
+      }
+
+      if (!focusableEl) return;
+
+      // Update 'active mode'
+      if (this._activeMode === 'activedescendant') {
+        this._listNode.setAttribute('aria-activedescendant', focusableEl.id);
+      } else if (
+        this._activeMode === 'roving-tabindex' ||
+        this._activeMode === 'tabbable-disclosure'
+      ) {
+        // @ts-ignore - Element extends HTMLElement for focus
+        focusableEl.focus();
+      }
+
+      // @ts-ignore - focusableEl is safely used as HTMLElement here
+      if (this.axis === 'block' && !isInView(this._scrollTargetNode, focusableEl)) {
+        focusableEl.scrollIntoView({ behavior: 'smooth', block: 'nearest' });
+      }
+
+      if (this._activeMode === 'roving-tabindex') {
+        if (prevFocusableEl) {
+          prevFocusableEl.setAttribute('tabindex', '-1');
+        }
+        focusableEl.setAttribute('tabindex', '0');
+      }
+    }
+
+    get activeItem() {
+      return this.listItems[this.activeIndex];
+    }
+
+    /**
+     * @type {number | number[]}
+     */
+    get checkedIndex() {
+      if (!this.multiple) {
+        return this.listItems.findIndex(o => isChecked(o));
+      }
+      return this.listItems.filter(o => isChecked(o)).map(o => this.listItems.indexOf(o));
+    }
+
+    /**
+     * @deprecated
+     * This setter exists for backwards compatibility of single choice groups.
+     * A setter api would be confusing for a multiple group. Use `setCheckedIndex` instead.
+     * @param {number} index
+     */
+    set checkedIndex(index) {
+      this.setCheckedIndex(index);
+    }
+
+    /**
+     * When `multiple` is false, will toggle, else will check provided index
+     * @param {Number} index
+     */
+    setCheckedIndex(index) {
+      const item = this.listItems[index];
+      if (!item) return;
+      if (!this.multiple) {
+        // Uncheck all
+        this.listItems.forEach(listItem => {
+          setChecked(listItem, true);
+        });
+        setChecked(this.listItems[index]);
+      } else {
+        toggleChecked(this.listItems[index]);
+      }
+    }
+
+    /**
+     * Since we cannot check instanceof with mixins, use this getter instead.
+     * This way, the outside world can confirm the type of an element
+     */
+    // eslint-disable-next-line class-methods-use-this
+    get isInteractiveList() {
+      return true;
+    }
+
+    constructor() {
+      super();
+
+      // TODO: copy descriptions from ListboxMixin and ChoiceGroupMixin to here
+      /** @type {'inline' | 'block'} */
+      this.axis = 'block';
+      this.multiple = false;
+      this.selectionFollowsFocus = false;
+      this.wrap = false;
+
+      /**
+       * By default, checkedIndex is set to 0. When hasNoDefaultSelected is true,
+       * checkedIndex will not be set
+       * @type {boolean}
+       */
+      this.hasNoDefaultSelected = false;
+
+      /**
+       * Whenever possible (for [role="listbox|menu"], usually with one level) we use an
+       * [active descendant](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_focus_activedescendant).
+       * For [role=toolbar], we use a [roving tabindex](https://www.w3.org/TR/wai-aria-practices-1.1/#kbd_roving_tabindex)
+       * Other examples:
+       * - [role="menubar"](https://www.w3.org/TR/wai-aria-practices-1.1/examples/menubar/menubar-1/menubar-1.html)
+       * - [role="tree"](https://www.w3.org/TR/wai-aria-practices-1.1/examples/treeview/treeview-1/treeview-1b.html)
+       * For disclosure menus, we need keyboard navigation, but treat every list item
+       * (more precisely its anchor child) as a tab stop.
+       * @type {'activedescendant'|'roving-tabindex'|'tabbable-disclosure'|'none'}
+       */
+      this._activeMode = 'activedescendant';
+
+      /**
+       * When children are 'smart' (like LionOption), checked and active states will be set
+       * to them and they are responsible for setting [aria-selected].
+       * When false, `get listItems()` needs to be configured to point to the list items.
+       * @type {boolean}
+       */
+      this._hasSmartChildren = false;
+
+      /**
+       * The role that will be put on _listNode
+       * @type {'menu'|'menubar'|'listbox'|'tree'|'toolbar'}
+       */
+      this._listRole = 'menu';
+
+      /**
+       * @type {HTMLElement[]}
+       */
+      this.__listItems = [];
+
+      /**
+       * By default, a typed character (or a sequence thereof) will be matched against
+       * the values of list items. The first and closest match, becomes active
+       * (focused or activedescendant depending on _matchMode)
+       * @type {boolean}
+       */
+      this._activateOnTypedChars = false;
+
+      /**
+       * The pending char sequence that will set active list item
+       * @type {number}
+       */
+      this._activateOnCharTimeout = 2000;
+
+      /**
+       * @type {string[]}
+       */
+      this.__typedChars = [];
+
+      this._onListClick = this._onListClick.bind(this);
+      this._onListKeyUp = this._onListKeyUp.bind(this);
+      this._onListKeyDown = this._onListKeyDown.bind(this);
+      this._onListFocusIn = this._onListFocusIn.bind(this);
+    }
+
+    connectedCallback() {
+      super.connectedCallback();
+      window.addEventListener('popstate', this._onPopState);
+    }
+
+    disconnectedCallback() {
+      super.disconnectedCallback();
+      window.removeEventListener('popstate', this._onPopState);
+    }
+
+    /**
+     * @param {import('lit').PropertyValues } changedProperties
+     */
+    firstUpdated(changedProperties) {
+      super.firstUpdated(changedProperties);
+      this._setupList();
+    }
+
+    /**
+     * @param {Node[]} nodes
+     */
+    #identifyNewItemsAndInitListItems(nodes) {
+      /**
+       *
+       * @param {HTMLElement} node
+       * @param {{ newItems: HTMLElement[], level?: number }} opts
+       * @returns
+       */
+      const handleInteractiveListAdditionLevel = (node, { newItems, level = 1 }) => {
+        // Move list item to element with aria-activedescendant ([role="listbox|menu|menubar"])
+        if (level === 1) {
+          this._listNode.appendChild(node);
+          if (this._hasSmartChildren || !(node instanceof Element)) {
+            return;
+          }
+        }
+        /**
+         * When [role=group], we can have a grouped set within a level, like multiple
+         * menuitemradios or -checkboxes.
+         * When no role at all, we might deal with a wrapped node (for instance triggering a
+         * submenu)
+         * Alternatively, when _activeMode is ['tabbable-disclosure'](https://www.w3.org/TR/wai-aria-practices-1.1/examples/disclosure/disclosure-navigation.html),
+         * we search for a[href]
+         */
+        if (node.getAttribute('role') === 'group') {
+          // @ts-ignore - HTMLCollection is iterable
+          for (const child of node.children) {
+            // @ts-ignore
+            handleInteractiveListAdditionLevel(child, { newItems, level: level + 1 });
+          }
+          return;
+        }
+        // Also support scenarios like these: https://adrianroselli.com/2019/06/link-disclosure-widget-navigation.html
+        // TODO: For now, we only allow direct children. Should we consider deeper nesting?
+        const focusableChildren = Array.from(node.children).filter(c => isFocusableElement(c));
+        if (focusableChildren.length) {
+          for (const focusableChild of focusableChildren) {
+            // @ts-ignore - focusableChild is HTMLElement
+            newItems.push(focusableChild);
+          }
+        } else {
+          // Then we must be focusable (either via activedescendant, tabindex)
+          newItems.push(node);
+        }
+      };
+
+      /** @type {HTMLElement[]} */
+      const newItems = [];
+
+      // Move items to _listNode and add interactive node references (with [role]) to listItems
+      nodes.forEach(node => {
+        handleInteractiveListAdditionLevel(/** @type {HTMLElement} */ (node), { newItems });
+      });
+
+      if (this.itemWrap && nodes.length) {
+        this._initMoreButtonMenu();
+      }
+
+      newItems.forEach(item => {
+        if (!this.__listItems.includes(item)) {
+          this.__listItems.push(item);
+        }
+      });
+
+      this._initListItems(newItems);
+    }
+
+    _setupList() {
+      // /**
+      //  * @param {HTMLElement} node
+      //  */
+      // const shouldAddItem = node => {
+      //   const role = /** @type {InteractiveListItemRole|'group'} */ (node.getAttribute('role'));
+      //   return (
+      //     (role && this._interactiveChildrenRoles.includes(role)) || node.hasAttribute('data-item')
+      //   );
+      // };
+
+      this._listItemsSlot.addEventListener('slotchange', () => {
+        // N.B. we do not use `this._listItemsSlot.assignedNodes()`, as it omits comment nodes.
+        // Comment nodes are really important for lit-html)
+        const nodes = Array.from(
+          (this._listItemsSlot.assignedSlot || this).childNodes || [],
+          // @ts-expect-error
+        ).filter(n => !n.slot);
+        this.#identifyNewItemsAndInitListItems(nodes);
+      });
+
+      this._listNode.setAttribute('role', this._listRole);
+      this._listNode.setAttribute(
+        'tabindex',
+        this._activeMode === 'tabbable-disclosure' ? '-1' : '0',
+      );
+      this._listNode.addEventListener('click', this._onListClick);
+      this._listNode.addEventListener('keyup', this._onListKeyUp);
+      this._listNode.addEventListener('keydown', this._onListKeyDown);
+      this._listNode.addEventListener('focusin', this._onListFocusIn);
+
+      // TODO: add "more menu" functionality here... when itemWrap is set. We only support "more-menu" (for now):
+      // 1. we can measure the width (if the axis is inline) of this._listNode
+      // and see how its children fit, moving them to an overlayController
+      // having hideVisually as hide mechanism (opening on focus, closing on blur).
+      // N.B. this._listNode has `display:flex`. This means we need to add `text-wrap: nowrap;`
+      // to avoid elems going over two lines, or give them a max-height based on measuring the height of one item.
+      // 2. N.B. hideVisually needs to be implemented in OverlayController.
+      // 3. when the more menu opens a next level, MultiLevelListMixin will be applied to the host as well.
+      // That means it knows when a child menu is open. If _subListMap of one of the items is open, we should hide more menu like this:
+      // https://jsfiddle.net/a4ocktfp/19/
+    }
+
+    /**
+     * When _listItemsSlot receives new items, they are initialized via this method
+     * @param {LionItem[]|HTMLElement[]} newItems the newly added items needing initialization
+     */
+    _initListItems(newItems) {
+      if (this._activeMode === 'roving-tabindex') {
+        // Make item focusable, but not part of tab sequence
+        newItems.forEach(item => item.setAttribute?.('tabindex', '-1'));
+      } else if (this._activeMode === 'activedescendant') {
+        newItems.forEach(item => {
+          // eslint-disable-next-line no-param-reassign
+          item.id = item.id || `${this.localName}-item-${uuid()}`;
+        });
+      } // for 'tabbable-disclosure', we assume items are already focusable and part of tab sequence
+
+      if (!this.hasNoDefaultSelected && this.checkedIndex === -1) {
+        this.checkedIndex = 0;
+      }
+      newItems.forEach(item => {
+        if (!item.hasAttribute('checked')) {
+          setChecked(item, true);
+        } else {
+          setChecked(item);
+        }
+      });
+
+      this._syncCurrentPageWithLocationHref(window.location);
+    }
+
+    /**
+     * Handles various keyboard controls
+     * @param {KeyboardEvent} ev - the keydown event object
+     */
+    _onListKeyDown(ev) {
+      if (isDisabled(this)) {
+        return;
+      }
+
+      const charHandled = this.__onKeydownActivateTypedChars(ev);
+      if (charHandled) {
+        return;
+      }
+
+      const { key } = ev;
+
+      switch (key) {
+        case 'Enter':
+        case ' ':
+          ev.preventDefault();
+          // ev.stopPropagation(); // prevent nested menus from conflicting
+          this.setCheckedIndex(this.activeIndex);
+          break;
+        case 'ArrowUp':
+          ev.preventDefault();
+          if (this.axis === 'block' || this._activeMode === 'tabbable-disclosure') {
+            this.activeIndex = this._getPreviousEnabledOption(this.activeIndex);
+          }
+          break;
+        case 'ArrowLeft':
+          if (this.axis === 'inline' || this._activeMode === 'tabbable-disclosure') {
+            this.activeIndex = this._getPreviousEnabledOption(this.activeIndex);
+          }
+          break;
+        case 'ArrowDown':
+          ev.preventDefault();
+          if (this.axis === 'block' || this._activeMode === 'tabbable-disclosure') {
+            this.activeIndex = this._getNextEnabledOption(this.activeIndex);
+          }
+          break;
+        case 'ArrowRight':
+          if (this.axis === 'inline' || this._activeMode === 'tabbable-disclosure') {
+            this.activeIndex = this._getNextEnabledOption(this.activeIndex);
+          }
+          break;
+        case 'Home':
+          ev.preventDefault();
+          this.activeIndex = this._getNextEnabledOption(0, 0);
+          break;
+        case 'End':
+          ev.preventDefault();
+          this.activeIndex = this._getPreviousEnabledOption(this.listItems.length - 1, 0);
+          break;
+        /* no default */
+      }
+
+      const keys = ['ArrowUp', 'ArrowDown', 'Home', 'End'];
+      if (keys.includes(key) && this.selectionFollowsFocus && !this.multiple) {
+        this.setCheckedIndex(this.activeIndex);
+      }
+    }
+
+    /**
+     * @param {KeyboardEvent} ev - the keydown event object
+     * @returns {boolean} whether a character key or a number was typed
+     */
+    __onKeydownActivateTypedChars(ev) {
+      if (!this._activateOnTypedChars) {
+        return false;
+      }
+
+      const { key, code } = ev;
+
+      if (code.startsWith('Key') || code.startsWith('Digit') || code.startsWith('Numpad')) {
+        this.__typedChars.push(key);
+        // TODO: schedule in updated loop for perf
+        const chars = this.__typedChars.join('');
+        const matchItem = this.listItems.find(item =>
+          this._matchCharsAgainstItem({ chars: [chars], item }),
+        );
+        // @ts-ignore - matchItem might be undefined
+        this.activeIndex = this.listItems.indexOf(matchItem);
+
+        // @ts-ignore - __clearCharTimeout can be a function
+        if (typeof this.__clearCharTimeout === 'function') {
+          // @ts-ignore
+          this.__clearCharTimeout();
+        }
+        this.__clearCharTimeout = setTimeout(() => {
+          this.__typedChars = [];
+        }, this._activateOnCharTimeout);
+
+        return true;
+      }
+      return false;
+    }
+
+    /**
+     * @overridable
+     * @param {{chars: string[], item: HTMLElement}} config
+     */
+    // eslint-disable-next-line class-methods-use-this
+    _matchCharsAgainstItem({ chars, item }) {
+      const value = getValue(item).toLowerCase();
+      return value.startsWith(chars);
+    }
+
+    /**
+     * @param {KeyboardEvent} ev
+     */
+    __preventScrollingWithArrowKeys(ev) {
+      if (this.disabled) {
+        return;
+      }
+      const { key } = ev;
+      switch (key) {
+        case 'ArrowUp':
+        case 'ArrowDown':
+        case 'Home':
+        case 'End':
+          ev.preventDefault();
+        /* no default */
+      }
+    }
+
+    /**
+     * @overridable
+     * @param {FocusEvent} ev
+     */
+    _onListFocusIn(ev) {
+      /** @type {HTMLElement} */
+      // @ts-ignore - target is EventTarget
+      const { target } = ev;
+      // const item = /** @type {HTMLElement} */ (target.closest('[role]'));
+      // @ts-ignore - target is HTMLElement
+      const foundIndex = this.listItems.indexOf(target);
+      if (foundIndex > -1 && foundIndex !== this.activeIndex) {
+        this.activeIndex = foundIndex;
+      }
+    }
+
+    /**
+     * @overridable
+     * @param {MouseEvent} ev
+     */
+    // eslint-disable-next-line class-methods-use-this, no-unused-vars
+    _onListClick(ev) {
+      /** @type {HTMLElement} */
+      // @ts-ignore - target is EventTarget
+      const { target } = ev;
+      const item = /** @type {HTMLElement} */ (target.closest('[role]')); // TODO: we might need a more specific contract
+      const foundIndex = this.listItems.indexOf(item);
+      if (foundIndex > -1) {
+        this.activeIndex = foundIndex;
+        this.setCheckedIndex(foundIndex);
+      }
+    }
+
+    /**
+     * @overridable
+     * @param {KeyboardEvent} ev
+     */
+    // eslint-disable-next-line class-methods-use-this, no-unused-vars
+    _onListKeyUp(ev) {
+      if (this.disabled) {
+        return;
+      }
+      const { key } = ev;
+      // eslint-disable-next-line default-case
+      switch (key) {
+        case 'ArrowUp':
+        case 'ArrowDown':
+        case 'Home':
+        case 'End':
+        case ' ':
+        case 'Enter':
+          ev.preventDefault();
+      }
+    }
+
+    /**
+     * @param {number} currentIndex
+     * @param {number} offset
+     */
+    __getNextOption(currentIndex, offset) {
+      /**
+       * @param {number} i
+       */
+      const until = i => (offset === 1 ? i < this.listItems.length : i >= 0);
+
+      for (let i = currentIndex + offset; until(i); i += offset) {
+        if (this.listItems[i] && !isDisabled(this.listItems[i])) {
+          return i;
+        }
+      }
+
+      if (this.wrap) {
+        const startIndex = offset === -1 ? this.listItems.length - 1 : 0;
+        for (let i = startIndex; until(i); i += 1) {
+          if (this.listItems[i] && !isDisabled(this.listItems[i])) {
+            return i;
+          }
+        }
+      }
+      return currentIndex;
+    }
+
+    /**
+     * @param {number} currentIndex
+     * @param {number} [offset=1]
+     */
+    _getNextEnabledOption(currentIndex, offset = 1) {
+      return this.__getNextOption(currentIndex, offset);
+    }
+
+    /**
+     * @param {number} currentIndex
+     * @param {number} [offset=-1]
+     */
+    _getPreviousEnabledOption(currentIndex, offset = -1) {
+      return this.__getNextOption(currentIndex, offset);
+    }
+
+    /**
+     * @param {Location} location
+     */
+    _syncCurrentPageWithLocationHref(location) {
+      this.listItems.forEach(item => {
+        if (/** @type {HTMLAnchorElement} */ (item).href) {
+          const pathname = location.href.endsWith('/')
+            ? location.href.substring(0, location.href.length - 1)
+            : location.href;
+          if (pathname === /** @type {HTMLAnchorElement} */ (item).href) {
+            setChecked(item);
+          } else {
+            setChecked(item, true);
+          }
+        }
+      });
+    }
+
+    /** @protected */
+    _onPopState = () => {
+      this._syncCurrentPageWithLocationHref(document.location);
+    };
+  });
+export const InteractiveListMixin = dedupeMixin(InteractiveListMixinImplementation);