@m3e/core 1.0.0-rc.1 → 1.0.0-rc.3

package/src/a11y/aria-reference.ts

@@ -1,51 +0,0 @@
-/**
- * Adapted from Angular Material CDK AriaDescriber
- * Source: https://github.com/angular/components/blob/main/src/cdk/a11y/aria-describer/aria-reference.ts
- *
- * @license MIT
- * Copyright (c) 2025 Google LLC
- * See LICENSE file in the project root for full license text.
- */
-
-/**
- * Gets a list of IDs referenced by an element for the specified ARIA attribute.
- * @param {Element} element The element from which to get referenced IDs.
- * @param {`aria-${string}`} attribute The ARIA attribute from which to get referenced IDs.
- * @returns {string[]} a list of IDs referenced by `element` for `attribute`.
- */
-export function getAriaReferenceIds(element: Element, attribute: `aria-${string}`): string[] {
-  return element.getAttribute(attribute)?.match(/\S+/g) ?? [];
-}
-
-/**
- * Adds an ID to the list of IDs referenced by an element for a given ARIA attribute.
- * @param {Element} element The element to which to add a referenced ID.
- * @param {`aria-${string}`} attribute The ARIA attribute to which to add an ID.
- * @param {string} id The ID to add.
- */
-export function addAriaReferencedId(element: Element, attribute: `aria-${string}`, id: string): void {
-  id = id.trim();
-
-  const ids = getAriaReferenceIds(element, attribute);
-  if (!ids.some((existingId) => existingId.trim() === id)) {
-    ids.push(id);
-    element.setAttribute(attribute, ids.join(" "));
-  }
-}
-
-/**
- * Removes an ID from a list of IDs referenced by an element for the specified ARIA attribute.
- * @param {Element} element The element from which to remove an ID.
- * @param {`aria-${string}`} attribute The ARIA attribute from which to remove an ID.
- * @param {string} id The ID to remove.
- */
-export function removeAriaReferencedId(element: Element, attribute: `aria-${string}`, id: string): void {
-  id = id.trim();
-  const ids = getAriaReferenceIds(element, attribute).filter((val) => val !== id);
-
-  if (ids.length > 0) {
-    element.setAttribute(attribute, ids.join(" "));
-  } else {
-    element.removeAttribute(attribute);
-  }
-}

package/src/a11y/index.ts

@@ -1,8 +0,0 @@
-export * from "./list-key";
-export * from "./keycodes";
-
-export * from "./aria-reference";
-export * from "./AriaDescriber";
-export * from "./FocusTrapElement";
-export * from "./InteractivityChecker";
-export * from "./LiveAnnouncer";

package/src/a11y/keycodes/KeyCode.ts

@@ -1,128 +0,0 @@
-/** Specifies known key code values. */
-export enum KeyCode {
-  Backspace = 8,
-  Tab = 9,
-  Enter = 13,
-  Shift = 16,
-  Ctrl = 17,
-  Alt = 18,
-  PauseBreak = 19,
-  CapsLock = 20,
-  Escape = 27,
-  Space = 32,
-  PageUp = 33,
-  PageDown = 34,
-  End = 35,
-  Home = 36,
-
-  LeftArrow = 37,
-  UpArrow = 38,
-  RightArrow = 39,
-  DownArrow = 40,
-
-  Insert = 45,
-  Delete = 46,
-
-  Zero = 48,
-  ClosedParen = Zero,
-  One = 49,
-  ExclamationMark = One,
-  Two = 50,
-  AtSign = Two,
-  Three = 51,
-  PoundSign = Three,
-  Hash = PoundSign,
-  Four = 52,
-  DollarSign = Four,
-  Five = 53,
-  PercentSign = Five,
-  Six = 54,
-  Caret = Six,
-  Hat = Caret,
-  Seven = 55,
-  Ampersand = Seven,
-  Eight = 56,
-  Star = Eight,
-  Asterik = Star,
-  Nine = 57,
-  OpenParen = Nine,
-
-  A = 65,
-  B = 66,
-  C = 67,
-  D = 68,
-  E = 69,
-  F = 70,
-  G = 71,
-  H = 72,
-  I = 73,
-  J = 74,
-  K = 75,
-  L = 76,
-  M = 77,
-  N = 78,
-  O = 79,
-  P = 80,
-  Q = 81,
-  R = 82,
-  S = 83,
-  T = 84,
-  U = 85,
-  V = 86,
-  W = 87,
-  X = 88,
-  Y = 89,
-  Z = 90,
-
-  LeftWindowKey = 91,
-  RightWindowKey = 92,
-  SelectKey = 93,
-
-  Numpad0 = 96,
-  Numpad1 = 97,
-  Numpad2 = 98,
-  Numpad3 = 99,
-  Numpad4 = 100,
-  Numpad5 = 101,
-  Numpad6 = 102,
-  Numpad7 = 103,
-  Numpad8 = 104,
-  Numpad9 = 105,
-
-  Multiply = 106,
-  Add = 107,
-  Subtract = 109,
-  DecimalPoint = 110,
-  Divide = 111,
-
-  F1 = 112,
-  F2 = 113,
-  F3 = 114,
-  F4 = 115,
-  F5 = 116,
-  F6 = 117,
-  F7 = 118,
-  F8 = 119,
-  F9 = 120,
-  F10 = 121,
-  F11 = 122,
-  F12 = 123,
-
-  NumLock = 144,
-  ScrollLock = 145,
-
-  SemiColon = 186,
-  Equals = 187,
-  Comma = 188,
-  Dash = 189,
-  Period = 190,
-  UnderScore = Dash,
-  PlusSign = Equals,
-  ForwardSlash = 191,
-  Tilde = 192,
-  GraveAccent = Tilde,
-
-  OpenBracket = 219,
-  ClosedBracket = 221,
-  Quote = 222,
-}

package/src/a11y/keycodes/ModifierKeys.ts

@@ -1,5 +0,0 @@
-/** Specifies the keyboard modifier keys. */
-export type ModifierKey = "alt" | "shift" | "ctrl" | "meta";
-
-/** The modifier keys. */
-export const ModifierKeys: readonly ModifierKey[] = ["alt", "shift", "ctrl", "meta"];

package/src/a11y/keycodes/getKeyCode.ts

@@ -1,8 +0,0 @@
-/**
- * Resolves the key code for the specified `KeyboardEvent`.
- * @param {KeyboardEvent} e The `KeyboardEvent` for which to resolve the key code.
- * @returns {number} The key code for `e`.
- */
-export function getKeyCode(e: KeyboardEvent): number {
-  return e.which || e.charCode || e.keyCode;
-}

package/src/a11y/keycodes/hasModifierKey.ts

@@ -1,11 +0,0 @@
-import { ModifierKey } from "./ModifierKeys";
-
-/**
- * Determines whether a modifier key is pressed.
- * @param {KeyboardEvent} e The `KeyboardEvent` to test.
- * @param {ModifierKey[]} modifiers The modifier keys to test.
- * @returns {boolean} A value indicating whether a modifier key is pressed.
- */
-export function hasModifierKey(e: KeyboardEvent, ...modifiers: ModifierKey[]): boolean {
-  return modifiers.length ? modifiers.some((x) => e[`${x}Key`]) : e.altKey || e.shiftKey || e.ctrlKey || e.metaKey;
-}

package/src/a11y/keycodes/index.ts

@@ -1,5 +0,0 @@
-export * from "./ModifierKeys";
-export * from "./KeyCode";
-export * from "./getKeyCode";
-export * from "./hasModifierKey";
-export * from "./isModifierAllowed";

package/src/a11y/keycodes/isModifierAllowed.ts

@@ -1,12 +0,0 @@
-import { hasModifierKey } from "./hasModifierKey";
-import { ModifierKey, ModifierKeys } from "./ModifierKeys";
-
-/**
- * Determines whether the specified modifier keys are allowed.
- * @param {KeyboardEvent} e The `KeyboardEvent` to test.
- * @param {ModifierKey[]} modifiers The allowed modifier keys.
- * @returns {boolean} A value indicating whether `modifiers` are allowed.
- */
-export function isModifierAllowed(e: KeyboardEvent, ...modifiers: ModifierKey[]): boolean {
-  return ModifierKeys.every((x) => !hasModifierKey(e, x) || modifiers.includes(x));
-}

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

@@ -1,25 +0,0 @@
-import { ListKeyManager } from "./ListKeyManager";
-
-/**
- * Utility for managing keyboard events for selectable lists whose items directly receive focus.
- * @template T The type of managed item.
- */
-export class FocusKeyManager<T extends HTMLElement> extends ListKeyManager<T> {
-  /** @private */ #focusOptions?: FocusOptions;
-
-  /** @inheritdoc */
-  override setActiveItem(item: T | null | undefined): void {
-    super.setActiveItem(item);
-    item?.focus(this.#focusOptions);
-  }
-
-  /**
-   * Configures the key manager with options used to focus items.
-   * @param {FocusOptions} options Options used to focus items.
-   * @returns {FocusKeyManager<T>} The configured key manager.
-   */
-  withOptions(options: FocusOptions): this {
-    this.#focusOptions = options;
-    return this;
-  }
-}

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

@@ -1,350 +0,0 @@
-/**
- * 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

@@ -1,66 +0,0 @@
-/**
- * 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;
-  }
-}