@m3e/core 1.0.0-rc.1

package/src/a11y/list-key/ListKeyManager.ts

@@ -0,0 +1,350 @@
+/**
+ * Adapted from Angular Material CDK KeyManager
+ * Source: https://github.com/angular/components/blob/main/src/cdk/a11y/key-manager/list-key-manager.ts
+ *
+ * @license MIT
+ * Copyright (c) 2025 Google LLC
+ * See LICENSE file in the project root for full license text.
+ */
+
+import { hasModifierKey, isModifierAllowed, ModifierKey } from "../keycodes";
+import { isDisabledMixin } from "../../shared/mixins/Disabled";
+
+import { ListManager } from "./ListManager";
+import { Typeahead, TypeaheadItem } from "./Typeahead";
+
+/**
+ * Utility for managing keyboard events for selectable lists.
+ * @template T The type of managed item.
+ */
+export class ListKeyManager<T extends HTMLElement & TypeaheadItem> extends ListManager<T> {
+  /** @private */ #typeahead?: Typeahead<T>;
+
+  /**
+   * Whether the active item will wrap to the other end of
+   * list when there are no more items in the given direction.
+   * @default false
+   */
+  public wrap = false;
+
+  /**
+   * Whether to activate the first and last items respectively when
+   * the `HOME` or `END` key is pressed.
+   * @default false
+   */
+  public homeAndEnd = false;
+
+  /**
+   * Whether to activate every 10th (or configured) first/last item
+   * in the up/down direction when the `PAGEUP` or `PAGEDOWN` key is pressed.
+   * @default false
+   */
+  public pageUpAndDown = false;
+
+  /**
+   * The number of items to skip when the `PAGEUP` or `PAGEDOWN` key is pressed.
+   * @default 10
+   */
+  public pageDelta = 10;
+
+  /**
+   * Whether to the list is oriented vertically.
+   * @default false
+   */
+  public vertical = false;
+
+  /** The allowed modifier keys.
+   * @default []
+   */
+  public allowedModifiers: ModifierKey[] = [];
+
+  /**
+   * A function used to skip items.
+   * @param {T} item The item to test.
+   * @returns {boolean} Whether `item` should be skipped.
+   */
+  public skipPredicate: (item: T) => boolean = (item) => isDisabledMixin(item) && item.disabled;
+
+  /** @inheritdoc */
+  override setItems(items: T[]): { added: readonly T[]; removed: readonly T[] } {
+    this.#typeahead?.setItems(items);
+    return super.setItems(items);
+  }
+
+  /** @inheritdoc */
+  override updateActiveItem(item: T | null | undefined): void {
+    super.updateActiveItem(item);
+    if (this.#typeahead) {
+      this.#typeahead.setSelectedIndex(item ? this.items.indexOf(item) : -1);
+    }
+  }
+
+  /**
+   * Configures the key manager to activate the first and last items respectively when the `HOME` or `END` key is pressed.
+   * @param {boolean} [enabled = true] Whether to activate the first and last items respectively when
+   * the `HOME` or `END` key is pressed.
+   * @returns {ListKeyManager<T>} The configured key manager.
+   */
+  withHomeAndEnd(enabled: boolean = true): this {
+    this.homeAndEnd = enabled;
+    return this;
+  }
+
+  /**
+   * Configures the key manager to page up and down when the `PAGEUP` or `PAGEDOWN` key is pressed.
+   * @param {boolean} [enabled = true] Whether to activate page up and down when the `PAGEUP` or `PAGEDOWN` key is pressed.
+   * @param {number} [pageDelta=10] The number of items to skip when the `PAGEUP` or `PAGEDOWN` key is pressed.
+   * @returns {ListKeyManager<T>} The configured key manager.
+   */
+  withPageUpAndDown(enabled: boolean = true, pageDelta: number = 10): this {
+    this.pageUpAndDown = enabled;
+    this.pageDelta = pageDelta;
+    return this;
+  }
+
+  /**
+   * Configures wrapping mode, which determines whether the active item will wrap to the other end of list when there are no more items in the given direction.
+   * @param {boolean} [enabled = true] Whether the active item will wrap to the other end of
+   * list when there are no more items in the given direction.
+   * @returns {ListKeyManager<T>} The configured key manager.
+   */
+  withWrap(enabled: boolean = true): this {
+    this.wrap = enabled;
+    return this;
+  }
+
+  /**
+   * Configures whether to move the selection vertically.
+   * @param {boolean} [enabled = true] Whether to move selection vertically.
+   * @returns {ListKeyManager<T>} The configured key manager.
+   */
+  withVerticalOrientation(enabled: boolean = true): this {
+    this.vertical = enabled;
+    return this;
+  }
+
+  /**
+   * Configured allowed modifier keys.
+   * @param {ModifierKey[]} modifiers The allowed modifier keys.
+   * @returns {ListKeyManager<T>} The configured key manager.
+   */
+  withAllowedModifiers(...modifiers: ModifierKey[]): this {
+    this.allowedModifiers = modifiers;
+    return this;
+  }
+
+  /**
+   * Configures whether typeahead is enabled.
+   * @param {boolean} [enabled = true] Whether typeahead is enabled.
+   * @returns {ListKeyManager<T>} The configured key manager.
+   */
+  withTypeahead(enabled: boolean = true): this {
+    if (enabled) {
+      this.#typeahead = new Typeahead<T>({ callback: (item) => this.setActiveItem(item) });
+    } else {
+      this.#typeahead = undefined;
+    }
+    return this;
+  }
+
+  /**
+   * Configures a function used to test whether an item should be skipped.
+   * @param skipPredicate A function used to determine whether an item should be skipped.
+   * @returns {ListKeyManager<T>} The configured key manager.
+   */
+  withSkipPredicate(skipPredicate: (item: T) => boolean): this {
+    this.skipPredicate = skipPredicate;
+    return this;
+  }
+
+  /**
+   * Sets the active item depending on the key event passed in.
+   * @param {KeyboardEvent} e The keyboard event to be used for determining which element should be active.
+   */
+  onKeyDown(e: KeyboardEvent): void {
+    if (e.defaultPrevented) return;
+
+    const modifierAllowed = isModifierAllowed(e, ...this.allowedModifiers);
+
+    switch (e.key) {
+      case "Left":
+      case "ArrowLeft":
+        if (modifierAllowed && !this.vertical) {
+          e.preventDefault();
+          const prev = this.#findPrevious();
+          if (prev) {
+            this.setActiveItem(prev);
+          }
+        }
+        break;
+      case "Up":
+      case "ArrowUp":
+        if (modifierAllowed) {
+          e.preventDefault();
+          const prev = this.#findPrevious();
+          if (prev) {
+            this.setActiveItem(prev);
+          }
+        }
+
+        break;
+
+      case "Right":
+      case "ArrowRight":
+        if (modifierAllowed && !this.vertical) {
+          e.preventDefault();
+          const next = this.#findNext();
+          if (next) {
+            this.setActiveItem(next);
+          }
+        }
+        break;
+
+      case "Down":
+      case "ArrowDown":
+        if (modifierAllowed) {
+          e.preventDefault();
+          const next = this.#findNext();
+          if (next) {
+            this.setActiveItem(next);
+          }
+        }
+
+        break;
+
+      case "Home":
+        if (modifierAllowed && this.homeAndEnd) {
+          e.preventDefault();
+          const first = this.#findFirst();
+          if (first) {
+            this.setActiveItem(first);
+          }
+        }
+
+        break;
+
+      case "End":
+        if (modifierAllowed && this.homeAndEnd) {
+          e.preventDefault();
+          const last = this.#findLast();
+          if (last) {
+            this.setActiveItem(last);
+          }
+        }
+
+        break;
+
+      case "PageUp":
+        if (modifierAllowed && this.pageUpAndDown) {
+          e.preventDefault();
+          const prev = this.#findPreviousByIndex(
+            this.activeItem ? Math.max(0, this.items.indexOf(this.activeItem) - this.pageDelta) : 0
+          );
+          if (prev) {
+            this.setActiveItem(prev);
+          }
+        }
+
+        break;
+
+      case "PageDown":
+        if (modifierAllowed && this.pageUpAndDown) {
+          e.preventDefault();
+          const next = this.#findNextByIndex(
+            this.activeItem
+              ? Math.min(this.items.length - 1, this.items.indexOf(this.activeItem) + this.pageDelta)
+              : this.items.length - 1
+          );
+          if (next) {
+            this.setActiveItem(next);
+          }
+        }
+
+        break;
+
+      default:
+        if (modifierAllowed || hasModifierKey(e, "shift")) {
+          this.#typeahead?.onKeyDown(e);
+        }
+        break;
+    }
+  }
+
+  /** @private */
+  #findFirst(): T | null {
+    for (let i = 0; i < this.items.length; i++) {
+      if (this.items[i] === this.activeItem) break;
+      const test = this.items[i];
+      if (!this.skipPredicate(test)) {
+        return test;
+      }
+    }
+    return null;
+  }
+
+  /** @private */
+  #findLast(): T | null {
+    for (let i = this.items.length - 1; i >= 0; i--) {
+      if (this.items[i] === this.activeItem) break;
+      const test = this.items[i];
+      if (!this.skipPredicate(test)) {
+        return test;
+      }
+    }
+    return null;
+  }
+
+  /** @private */
+  #findNext(): T | null {
+    for (let i = 0; i < this.items.length; i++) {
+      if (this.items[i] === this.activeItem) {
+        for (let j = i + 1; j < this.items.length; j++) {
+          const test = this.items[j];
+          if (!this.skipPredicate(test)) {
+            return test;
+          }
+        }
+        break;
+      }
+    }
+    return this.wrap ? this.#findFirst() : null;
+  }
+
+  /** @private */
+  #findPrevious(): T | null {
+    for (let i = 0; i < this.items.length; i++) {
+      if (this.items[i] === this.activeItem) {
+        for (let j = i - 1; j >= 0; j--) {
+          const test = this.items[j];
+          if (!this.skipPredicate(test)) {
+            return test;
+          }
+        }
+        break;
+      }
+    }
+    return this.wrap ? this.#findLast() : null;
+  }
+
+  /** @private */
+  #findPreviousByIndex(index: number): T | null {
+    for (let i = index; i >= 0; i--) {
+      const test = this.items[i];
+      if (!this.skipPredicate(test)) {
+        return test;
+      }
+    }
+    return null;
+  }
+
+  /** @private */
+  #findNextByIndex(index: number): T | null {
+    for (let i = index; i < this.items.length; i++) {
+      const test = this.items[i];
+      if (!this.skipPredicate(test)) {
+        return test;
+      }
+    }
+    return null;
+  }
+}

package/src/a11y/list-key/ListManager.ts

@@ -0,0 +1,66 @@
+/**
+ * Utility for managing a list of items which supports activation.
+ * @template T The type of managed item.
+ */
+export class ListManager<T> {
+  /** @private */ #items = new Array<T>();
+  /** @private */ #activeItem: T | null = null;
+  /** @private */ #onActiveItemChangeCallback?: () => void;
+
+  /** The items being managed. */
+  get items(): ReadonlyArray<T> {
+    return this.#items;
+  }
+
+  /** The active item. */
+  get activeItem(): T | null {
+    return this.#activeItem;
+  }
+
+  /**
+   * Sets the items to manage.
+   * @param {Array<T>} items The new items.
+   * @returns {{ added: ReadonlyArray<T>; removed: ReadonlyArray<T> }} An object specifying added and removed items.
+   */
+  setItems(items: Array<T>): { added: ReadonlyArray<T>; removed: ReadonlyArray<T> } {
+    const removed = this.items.filter((x) => !items.includes(x));
+    const added = items.filter((x) => !this.items.includes(x));
+
+    this.#items = items;
+
+    if (this.activeItem && !this.items.includes(this.activeItem)) {
+      this.updateActiveItem(null);
+    }
+
+    return { added, removed };
+  }
+
+  /**
+   * Sets the active item.
+   * @param {T | null | undefined} item The new active item.
+   */
+  setActiveItem(item: T | null | undefined): void {
+    if (this.activeItem !== item) {
+      this.updateActiveItem(item);
+      this.#onActiveItemChangeCallback?.();
+    }
+  }
+
+  /**
+   * Updates the active item.
+   * @param {T | null | undefined} item The active item.
+   */
+  updateActiveItem(item: T | null | undefined): void {
+    this.#activeItem = item ?? null;
+  }
+
+  /**
+   * Configures the list manager with a callback invoked when an item is activated.
+   * @param {() => void} callback The callback invoked when an item is activated.
+   * @returns {ListManager<T>} The configured list manager.
+   */
+  onActiveItemChange(callback: () => void): this {
+    this.#onActiveItemChangeCallback = callback;
+    return this;
+  }
+}

package/src/a11y/list-key/RadioKeyManager.ts

@@ -0,0 +1,49 @@
+import { LitElement } from "lit";
+
+import { CheckedOrSelectedMixin, isCheckedOrSelected } from "../../shared/mixins/CheckedOrSelected";
+import { DisabledMixin } from "../../shared/mixins/Disabled";
+
+import { RovingTabIndexManager } from "./RovingTabIndexManager";
+
+/**
+ * Utility for managing keyboard events for selectable lists whose items behave like a radio.
+ * @template T The type of managed item.
+ */
+export class RadioKeyManager<
+  T extends LitElement & DisabledMixin & CheckedOrSelectedMixin
+> extends RovingTabIndexManager<T> {
+  /** @private */ #disabled = false;
+
+  /** A value indicating whether managed items are disabled. */
+  get disabled(): boolean {
+    return this.#disabled;
+  }
+  set disabled(value: boolean) {
+    this.#disabled = value;
+    this.items.forEach((x) => (x.disabled = value));
+  }
+
+  /** @inheritdoc */
+  override setItems(items: T[]): { added: readonly T[]; removed: readonly T[] } {
+    if (this.disabled) {
+      items.forEach((x) => (x.disabled = true));
+    }
+
+    const { added, removed } = super.setItems(items);
+
+    if (added.length > 0 || removed.length > 0) {
+      if (!this.activeItem) {
+        this.updateActiveItem(added.find((x) => !this.skipPredicate(x)) ?? null);
+      }
+
+      if (this.activeItem && (this.activeItem.disabled || !isCheckedOrSelected(this.activeItem))) {
+        const checked = added.find((x) => !this.skipPredicate(x) && isCheckedOrSelected(x));
+        if (checked) {
+          this.updateActiveItem(checked);
+        }
+      }
+    }
+
+    return { added, removed };
+  }
+}

package/src/a11y/list-key/RovingTabIndexManager.ts

@@ -0,0 +1,56 @@
+import { FocusKeyManager } from "./FocusKeyManager";
+
+/**
+ * Utility for managing keyboard events and a roving tab index for selectable lists whose items directly receive focus.
+ * @template T The type of managed item.
+ */
+export class RovingTabIndexManager<T extends HTMLElement> extends FocusKeyManager<T> {
+  /** @private */ #disableRovingTabIndex = false;
+
+  /** @inheritdoc */
+  override updateActiveItem(item: T | null | undefined): void {
+    super.updateActiveItem(item);
+
+    if (!this.#disableRovingTabIndex) {
+      item?.setAttribute("tabindex", "0");
+      for (const other of this.items) {
+        if (other !== item && other.hasAttribute("tabindex")) {
+          other.setAttribute("tabindex", "-1");
+        }
+      }
+    }
+  }
+
+  /** @inheritdoc */
+  override setItems(items: T[]): { added: readonly T[]; removed: readonly T[] } {
+    const result = super.setItems(items);
+
+    if (!this.#disableRovingTabIndex) {
+      for (const added of result.added) {
+        if (added !== this.activeItem && !this.skipPredicate(added)) {
+          added.setAttribute("tabindex", "-1");
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Configures whether roving tab index is disabled.
+   * @param {boolean} [disabled=true] Whether the roving tab index is disabled.
+   * @returns {RovingTabIndexManager<T>} The configured roving tab index manager.
+   */
+  disableRovingTabIndex(disabled: boolean = true): this {
+    if (disabled !== this.#disableRovingTabIndex) {
+      this.#disableRovingTabIndex = disabled;
+      for (const item of this.items) {
+        if (!this.skipPredicate(item)) {
+          item?.setAttribute("tabindex", this.#disableRovingTabIndex || item === this.activeItem ? "0" : "-1");
+        }
+      }
+    }
+
+    return this;
+  }
+}

package/src/a11y/list-key/SelectionManager.ts

@@ -0,0 +1,132 @@
+import { LitElement } from "lit";
+
+import { CheckedOrSelectedMixin, checkOrSelect, isCheckedOrSelected } from "../../shared/mixins/CheckedOrSelected";
+import { DisabledMixin } from "../../shared/mixins/Disabled";
+
+import { RadioKeyManager } from "./RadioKeyManager";
+
+/** A symbol through which to access an element's selection manager. */
+export const selectionManager = Symbol("selectionManager");
+
+/**
+ * Utility for managing keyboard events for selectable lists where one or more items can be selected.
+ * @template T The type of managed item.
+ */
+export class SelectionManager<
+  T extends LitElement & DisabledMixin & CheckedOrSelectedMixin
+> extends RadioKeyManager<T> {
+  /** @private */ #onSelectedItemsChangeCallback?: () => void;
+  /** @private */ #selectedItems = new Array<T>();
+  /** @private */ #multi = false;
+
+  /** A value indicating whether multiple items can be selected. */
+  get multi(): boolean {
+    return this.#multi;
+  }
+  set multi(value: boolean) {
+    this.#multi = value;
+    this.#enforceSingleSelect(true);
+  }
+
+  /** The selected items. */
+  get selectedItems(): readonly T[] {
+    return this.#selectedItems;
+  }
+
+  /**
+   * Selects or deselects the item based on the item's checked or selected state.
+   * @param {T} item The item whose selection state has changed.
+   */
+  notifySelectionChange(item: T): void {
+    if (this.items.includes(item)) {
+      if (isCheckedOrSelected(item)) {
+        this.select(item);
+      } else {
+        this.deselect(item);
+      }
+    }
+  }
+
+  /**
+   * Deselects the specified item.
+   * @param {T} item The item to deselect.
+   */
+  deselect(item: T): void {
+    if (this.items.includes(item)) {
+      if (isCheckedOrSelected(item)) {
+        checkOrSelect(item, false);
+      }
+
+      const index = this.#selectedItems.indexOf(item);
+      if (index >= 0) {
+        this.#selectedItems.splice(index, 1);
+        this.#onSelectedItemsChangeCallback?.();
+      }
+    }
+  }
+
+  /**
+   * Updates the selected item.
+   * @param {T | null | undefined} item The selected item.
+   * @param {boolean} [activate=true] A value indicating whether to activate the item.
+   */
+  select(item: T | null | undefined, activate: boolean = true): void {
+    if (!item || this.items.includes(item)) {
+      if (!this.multi) {
+        for (const selected of this.#selectedItems) {
+          if (selected !== item) {
+            checkOrSelect(selected, false);
+          }
+        }
+        this.#selectedItems.length = 0;
+      }
+
+      if (item) {
+        this.#selectedItems.push(item);
+        if (!isCheckedOrSelected(item)) {
+          checkOrSelect(item, true);
+        }
+      }
+
+      if (activate) {
+        this.updateActiveItem(item);
+      }
+
+      this.#onSelectedItemsChangeCallback?.();
+    }
+  }
+
+  /** @inheritdoc */
+  override setItems(items: T[]): { added: readonly T[]; removed: readonly T[] } {
+    const { added, removed } = super.setItems(items);
+
+    this.#selectedItems = this.#selectedItems.filter((x) => !removed.includes(x));
+    this.#selectedItems.push(...added.filter((x) => isCheckedOrSelected(x)));
+    this.#enforceSingleSelect();
+    this.#onSelectedItemsChangeCallback?.();
+    return { added, removed };
+  }
+
+  /**
+   * Configures the selection manager with a callback invoked when selected items change.
+   * @param {() => void} callback The callback invoked when selected items change.
+   * @returns {SelectionManager<T>} The configured selection manager.
+   */
+  onSelectedItemsChange(callback: () => void): this {
+    this.#onSelectedItemsChangeCallback = callback;
+    return this;
+  }
+
+  /** @private */
+  #enforceSingleSelect(emit = false): void {
+    if (!this.multi && this.#selectedItems.length > 1) {
+      for (let i = 1; i < this.#selectedItems.length; i++) {
+        checkOrSelect(this.#selectedItems[i], false);
+      }
+      this.#selectedItems.length = 1;
+      if (emit) {
+        this.#onSelectedItemsChangeCallback?.();
+      }
+    }
+  }
+}