@m3e/core 1.0.0-rc.1

package/src/a11y/FocusTrapElement.ts

@@ -0,0 +1,136 @@
+import { css, CSSResultGroup, html, LitElement } from "lit";
+import { customElement, query } from "lit/decorators.js";
+
+import { Disabled } from "../shared/mixins/Disabled";
+import { Role } from "../shared/mixins/Role";
+
+import { M3eInteractivityChecker } from "./InteractivityChecker";
+
+/**
+ * A non-visual element used to trap focus within nested content.
+ * @tag m3e-focus-trap
+ *
+ * @slot - Renders content for which to trap focus.
+ *
+ * @attr disabled - Disables the focus trap.
+ */
+@customElement("m3e-focus-trap")
+export class M3eFocusTrapElement extends Disabled(Role(LitElement, "none")) {
+  /** The styles of the element. */
+  static override styles: CSSResultGroup = css`
+    :host {
+      display: contents;
+    }
+    .trap {
+      outline: none;
+    }
+  `;
+
+  /** @private */ @query(".trap") private readonly _firstTrap!: HTMLElement | null;
+
+  /** @inheritdoc */
+  protected override render(): unknown {
+    const trap = html`<div
+      class="trap"
+      .inert="${this.disabled}"
+      tabindex="0"
+      aria-hidden="true"
+      @focus="${this.#onFocus}"
+    ></div>`;
+    return html`${trap}<slot></slot>${trap}`;
+  }
+
+  /** @private */
+  #onFocus(e: FocusEvent): void {
+    const [first, last] = this.#getFirstAndLastFocusableChild();
+    const isFirst = e?.target === this._firstTrap;
+    const fromFirst = e.relatedTarget === first;
+    const fromLast = e.relatedTarget === last;
+    const fromOutside = !fromFirst && !fromLast;
+
+    if ((!isFirst && fromLast) || (isFirst && fromOutside)) {
+      first?.focus();
+      return;
+    }
+    if ((isFirst && fromFirst) || (!isFirst && fromOutside)) {
+      last?.focus();
+    }
+  }
+
+  /** @private */
+  #getFirstAndLastFocusableChild(): [HTMLElement | null, HTMLElement | null] {
+    let first: HTMLElement | null = null;
+    let last: HTMLElement | null = null;
+
+    this.#walkTree(this, [], (element, parents) => {
+      if (
+        M3eInteractivityChecker.isFocusable(element, parents) &&
+        element instanceof HTMLElement &&
+        element.tabIndex >= 0
+      ) {
+        first = first ?? element;
+        last = element;
+      }
+    });
+
+    return [first, last];
+  }
+
+  /** @private */
+  #walkTree(
+    root: Element,
+    parents: readonly Element[],
+    callback: (element: Element, parents: readonly Element[]) => void
+  ): void {
+    parents = [...parents, root];
+
+    for (const node of root.childNodes) {
+      if (node.nodeType !== Node.ELEMENT_NODE) continue;
+      const element = <HTMLElement>node;
+
+      callback(element, parents);
+
+      if (element.shadowRoot) {
+        this.#walkShadowRoot(element, parents, callback);
+      } else if (element instanceof HTMLSlotElement) {
+        this.#walkSlot(element, parents, callback);
+      } else if (element.hasChildNodes()) {
+        this.#walkTree(element, parents, callback);
+      }
+    }
+  }
+
+  /** @private */
+  #walkShadowRoot(
+    root: Element,
+    parents: readonly Element[],
+    callback: (element: Element, parents: readonly Element[]) => void
+  ): void {
+    for (const node of root.shadowRoot?.childNodes ?? []) {
+      if (node.nodeType !== Node.ELEMENT_NODE) continue;
+      const element = <HTMLElement>node;
+      callback(element, parents);
+      if (!element.hasChildNodes()) continue;
+      this.#walkTree(element, parents, callback);
+    }
+  }
+
+  /** @private */
+  #walkSlot(
+    slot: HTMLSlotElement,
+    parents: readonly Element[],
+    callback: (element: Element, parents: readonly Element[]) => void
+  ) {
+    for (const node of slot.assignedElements()) {
+      callback(node, parents);
+      if (!node.hasChildNodes()) continue;
+      this.#walkTree(node, parents, callback);
+    }
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "m3e-focus-trap": M3eFocusTrapElement;
+  }
+}

package/src/a11y/InteractivityChecker.ts

@@ -0,0 +1,62 @@
+/** Utility for checking the interactivity of an element, such as whether it is focusable. */
+export class M3eInteractivityChecker {
+  /**
+   * Determines whether a given element can receive focus.
+   * @param {Element} element The element to test.
+   * @param {readonly Element[]} [parents = undefined] The known parent elements to test. The default value is `undefined`.
+   * @returns {boolean} Whether `element` can receive focus.
+   */
+  static isFocusable(element: Element, parents?: readonly Element[]): boolean {
+    if (
+      element.matches(
+        ":is(button,input,select,textarea,object,:is(a,area)[href],[tabindex],[contenteditable=true]):not(:disabled,[disabled])"
+      )
+    ) {
+      return !this.#cannotFocusParent(parents);
+    }
+
+    if (
+      !element.localName.includes("-") ||
+      !element.matches(":not(:disabled,[disabled])") ||
+      element.getAttribute("aria-disabled") === "true"
+    ) {
+      return false;
+    }
+
+    if (element.shadowRoot?.delegatesFocus) {
+      return !this.#cannotFocusParent(parents);
+    }
+
+    return false;
+  }
+
+  static #cannotFocusParent(parents?: readonly Element[]): boolean {
+    return parents?.some((x) => x.matches(":is([aria-hidden='true'],:disabled,[disabled])")) ?? false;
+  }
+
+  /**
+   * Finds interactive elements that descend from the specified element.
+   * @param {HTMLElement} element The `HTMLElement` to search.
+   * @returns {HTMLElement[]} The interactive elements that descend from `element`.
+   */
+  static findInteractiveElements(element: HTMLElement): HTMLElement[] {
+    const elements = new Array<HTMLElement>();
+    const walker = element.ownerDocument.createTreeWalker(element, NodeFilter.SHOW_ELEMENT);
+
+    for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+      const element = <HTMLElement>walker.currentNode;
+      if (this.isFocusable(element)) {
+        elements.push(element);
+      }
+    }
+
+    return elements;
+  }
+}
+
+declare global {
+  /** Utility for checking the interactivity of an element, such as whether it is focusable. */
+  var M3eInteractivityChecker: M3eInteractivityChecker;
+}
+
+globalThis.M3eInteractivityChecker = M3eInteractivityChecker;

package/src/a11y/LiveAnnouncer.ts

@@ -0,0 +1,143 @@
+/**
+ * Adapted from Angular Material CDK Live Announcer
+ * Source: https://github.com/angular/components/blob/main/src/cdk/a11y/live-announcer/live-announcer.ts
+ *
+ * @license MIT
+ * Copyright (c) 2025 Google LLC
+ * See LICENSE file in the project root for full license text.
+ */
+
+import { isServer } from "lit";
+
+import { addAriaReferencedId } from "./aria-reference";
+import { visuallyHide } from "./visuallyHide";
+
+/** Specifies the possible politeness levels in which to announce messages. */
+export type ARIALivePoliteness = "off" | "polite" | "assertive";
+
+/** Utility for announcing messages to screen readers. */
+export class M3eLiveAnnouncer {
+  /** @private */ static #nextId = 0;
+  /** @private */ static #liveElement?: HTMLElement;
+  /** @private */ static #previousTimeout: number;
+  /** @private */ static #currentPromise?: Promise<void>;
+  /** @private */ static #currentResolve?: () => void;
+
+  /**
+   * Announces the specified message to screen readers.
+   * @param {string} message The message to announce.
+   * @returns {Promise<void>} A `Promise` that resolves when `message` is added to the DOM.
+   */
+  static announce(message: string): Promise<void>;
+
+  /**
+   * Announces the specified message to screen readers.
+   * @param {string} message The message to announce.
+   * @param {ARIALivePoliteness | undefined} politeness The politeness in which to announce `message`.
+   * @returns {Promise<void>} A `Promise` that resolves when `message` is added to the DOM.
+   */
+  static announce(message: string, politeness?: ARIALivePoliteness): Promise<void>;
+
+  /**
+   * Announces the specified message to screen readers.
+   * @param {string} message The message to announce.
+   * @param {number | undefined} duration The duration, in milliseconds, after which to clear the announcement. Note
+   * that this takes effect after the message has been added to the DOM, which can be up to
+   * 100ms after `announce` has been called.
+   * @returns {Promise<void>} A `Promise` that resolves when `message` is added to the DOM.
+   */
+  static announce(message: string, duration?: number): Promise<void>;
+
+  /**
+   * Announces the specified message to screen readers.
+   * @param {string} message The message to announce.
+   * @param {ARIALivePoliteness | undefined} politeness The politeness in which to announce `message`.
+   * @param {number | undefined} duration The duration, in milliseconds, after which to clear the announcement. Note
+   * that this takes effect after the message has been added to the DOM, which can be up to 100ms after `announce` has been called.
+   * @returns {Promise<void>} A `Promise` that resolves when `message` is added to the DOM.
+   */
+  static announce(message: string, politeness?: ARIALivePoliteness, duration?: number): Promise<void>;
+
+  static announce(message: string, ...args: any[]): Promise<void> {
+    if (isServer) {
+      return Promise.resolve();
+    }
+
+    this.#liveElement = this.#liveElement ?? this.#createLiveElement();
+
+    let politeness: ARIALivePoliteness | undefined;
+    let duration: number | undefined;
+
+    if (args.length === 1 && typeof args[0] === "number") {
+      duration = args[0];
+    } else {
+      [politeness, duration] = args;
+    }
+
+    this.clear();
+    clearTimeout(this.#previousTimeout);
+
+    this.#liveElement.setAttribute("aria-live", politeness ?? "polite");
+
+    for (const modal of document.querySelectorAll("m3e-dialog")) {
+      addAriaReferencedId(modal, "aria-owns", this.#liveElement.id);
+    }
+
+    this.#currentPromise = this.#currentPromise ?? new Promise((resolve) => (this.#currentResolve = resolve));
+    clearTimeout(this.#previousTimeout);
+
+    this.#previousTimeout = setTimeout(() => {
+      if (!this.#liveElement) {
+        return;
+      }
+
+      this.#liveElement.textContent = message;
+      if (duration !== undefined) {
+        this.#previousTimeout = setTimeout(() => this.clear(), duration);
+      }
+
+      this.#currentResolve?.();
+      this.#currentPromise = this.#currentResolve = undefined;
+    }, 100);
+
+    return this.#currentPromise;
+  }
+
+  /**
+   * Clears the current text from the announcer element. Can be used to prevent
+   * screen readers from reading the text out again while the user is going
+   * through page landmarks.
+   */
+  static clear() {
+    if (this.#liveElement) {
+      this.#liveElement.textContent = "";
+    }
+  }
+
+  /** @private */
+  static #createLiveElement(): HTMLElement {
+    const prev = document.getElementsByClassName("m3e-live-announcer");
+    for (let i = 0; i < prev.length; i++) {
+      prev[i].remove();
+    }
+
+    const liveAnnouncer = document.createElement("div");
+    liveAnnouncer.classList.add("m3e-live-announcer");
+    liveAnnouncer.setAttribute("aria-atomic", "true");
+    liveAnnouncer.setAttribute("aria-live", "polite");
+    liveAnnouncer.id = `m3e-live-announcer-${this.#nextId++}`;
+
+    visuallyHide(liveAnnouncer.style);
+
+    document.body.append(liveAnnouncer);
+
+    return liveAnnouncer;
+  }
+}
+
+declare global {
+  /** Utility for announcing messages to screen readers. */
+  var M3eLiveAnnouncer: M3eLiveAnnouncer;
+}
+
+globalThis.M3eLiveAnnouncer = M3eLiveAnnouncer;

package/src/a11y/aria-reference.ts

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

@@ -0,0 +1,8 @@
+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

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

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

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

@@ -0,0 +1,11 @@
+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

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

package/src/a11y/keycodes/isModifierAllowed.ts

@@ -0,0 +1,12 @@
+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

@@ -0,0 +1,25 @@
+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;
+  }
+}