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

package/rollup.config.js

@@ -1,132 +0,0 @@
-import resolve from "@rollup/plugin-node-resolve";
-import terser from "@rollup/plugin-terser";
-import typescript from "@rollup/plugin-typescript";
-
-const banner = `/**
- * @license MIT
- * Copyright (c) 2025 matraic
- * See LICENSE file in the project root for full license text.
- */`;
-
-export default [
-  {
-    input: "src/index.ts",
-    output: [
-      {
-        file: "dist/index.js",
-        format: "esm",
-        sourcemap: true,
-        banner: banner,
-      },
-      {
-        file: "dist/index.min.js",
-        format: "esm",
-        sourcemap: true,
-        banner: banner,
-        plugins: [terser({ mangle: true })],
-      },
-    ],
-    external: ["lit"],
-    plugins: [resolve(), typescript()],
-  },
-  {
-    input: "src/a11y/index.ts",
-    output: [
-      {
-        file: "dist/a11y.js",
-        format: "esm",
-        sourcemap: true,
-        banner: banner,
-      },
-      {
-        file: "dist/a11y.min.js",
-        format: "esm",
-        sourcemap: true,
-        banner: banner,
-        plugins: [terser({ mangle: true })],
-      },
-    ],
-    external: ["lit"],
-    plugins: [resolve(), typescript()],
-  },
-  {
-    input: "src/anchoring/index.ts",
-    output: [
-      {
-        file: "dist/anchoring.js",
-        format: "esm",
-        sourcemap: true,
-        banner: banner,
-      },
-      {
-        file: "dist/anchoring.min.js",
-        format: "esm",
-        sourcemap: true,
-        banner: banner,
-        plugins: [terser({ mangle: true })],
-      },
-    ],
-    external: ["lit"],
-    plugins: [resolve(), typescript()],
-  },
-  {
-    input: "src/bidi/index.ts",
-    output: [
-      {
-        file: "dist/bidi.js",
-        format: "esm",
-        sourcemap: true,
-        banner: banner,
-      },
-      {
-        file: "dist/bidi.min.js",
-        format: "esm",
-        sourcemap: true,
-        banner: banner,
-        plugins: [terser({ mangle: true })],
-      },
-    ],
-    external: ["lit"],
-    plugins: [resolve(), typescript()],
-  },
-  {
-    input: "src/layout/index.ts",
-    output: [
-      {
-        file: "dist/layout.js",
-        format: "esm",
-        sourcemap: true,
-        banner: banner,
-      },
-      {
-        file: "dist/layout.min.js",
-        format: "esm",
-        sourcemap: true,
-        banner: banner,
-        plugins: [terser({ mangle: true })],
-      },
-    ],
-    external: ["lit"],
-    plugins: [resolve(), typescript()],
-  },
-  {
-    input: "src/platform/index.ts",
-    output: [
-      {
-        file: "dist/platform.js",
-        format: "esm",
-        sourcemap: true,
-        banner: banner,
-      },
-      {
-        file: "dist/platform.min.js",
-        format: "esm",
-        sourcemap: true,
-        banner: banner,
-        plugins: [terser({ mangle: true })],
-      },
-    ],
-    external: ["lit"],
-    plugins: [resolve(), typescript()],
-  },
-];

package/src/a11y/AriaDescriber.ts

@@ -1,130 +0,0 @@
-/**
- * Adapted from Angular Material CDK ARIA Describer
- * Source: https://github.com/angular/components/blob/main/src/cdk/a11y/aria-describer/aria-describer.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, removeAriaReferencedId } from "./aria-reference";
-import { visuallyHide } from "./visuallyHide";
-
-/** Utility for generating visually hidden elements that convey descriptive messages using `aria-describedby`. */
-export class M3eAriaDescriber {
-  /** @private */ static #nextId = 0;
-  /** @private */ static #messageContainers = new Map<
-    ParentNode,
-    {
-      containerElement: HTMLElement;
-      messageRegistry: Map<string, { messageElement: Element; count: number }>;
-    }
-  >();
-
-  /**
-   * Adds an `aria-describedby` reference to a hidden element that contains the message.
-   * @param {Element} element The element for which to provide a visually hidden description.
-   * @param {string} message The message used to describe `element`.
-   * @param {string} [role="tooltip"] The ARIA role of the message.
-   */
-  static describe(element: Element, message: string, role: string = "tooltip"): void {
-    if (isServer) {
-      return;
-    }
-
-    const rootNode = element.getRootNode() as ParentNode;
-    if (!(rootNode instanceof ShadowRoot || rootNode instanceof Document)) {
-      return;
-    }
-
-    let container = this.#messageContainers.get(rootNode);
-    if (!container) {
-      container = {
-        containerElement: this.#createMessageContainer(),
-        messageRegistry: new Map<string, { messageElement: Element; count: number }>(),
-      };
-
-      // Append to body if document, otherwise, append as a child of shadow root.
-      (rootNode instanceof Document ? rootNode.body : rootNode).appendChild(container.containerElement);
-      this.#messageContainers.set(rootNode, container);
-    }
-
-    const key = `${role}:${message}`;
-    let entry = container.messageRegistry.get(key);
-    if (!entry) {
-      entry = { messageElement: this.#createMessageElement(message, role), count: 0 };
-      container.containerElement.appendChild(entry.messageElement);
-      container.messageRegistry.set(key, entry);
-    }
-
-    entry.count++;
-
-    addAriaReferencedId(element, "aria-describedby", entry.messageElement.id);
-  }
-
-  /**
-   * Removes an `aria-describedby` reference to a hidden element that contains the message.
-   * @param {Element} element The element from which to remove a visually hidden description.
-   * @param {string} message The message used to describe `element`.
-   * @param {string} [role="tooltip"] The ARIA role of the message.
-   */
-  static removeDescription(element: Element, message: string, role: string = "tooltip"): void {
-    if (isServer) {
-      return;
-    }
-
-    const rootNode = element.getRootNode() as ParentNode;
-    const container = this.#messageContainers.get(rootNode);
-    if (!container) {
-      return;
-    }
-
-    const key = `${role}:${message}`;
-    const entry = container.messageRegistry.get(key);
-    if (!entry) {
-      return;
-    }
-
-    entry.count--;
-    removeAriaReferencedId(element, "aria-describedby", entry.messageElement.id);
-
-    // If there are no more elements referencing the message, remove it from the DOM.
-    if (entry.count <= 0) {
-      entry.messageElement.remove();
-      container.messageRegistry.delete(key);
-    }
-
-    // If there are no more registered messages, remove the container from the DOM.
-    if (container.messageRegistry.size == 0) {
-      container.containerElement?.remove();
-      this.#messageContainers.delete(rootNode);
-    }
-  }
-
-  /** @private */
-  static #createMessageContainer(): HTMLElement {
-    const messageContainer = document.createElement("div");
-    messageContainer.classList.add("m3e-describedby-message-container");
-    visuallyHide(messageContainer.style);
-    return messageContainer;
-  }
-
-  /** @private */
-  static #createMessageElement(message: string, role: string): HTMLElement {
-    const messageElement = document.createElement("span");
-    messageElement.id = `m3e-describedby-message-${this.#nextId++}`;
-    messageElement.role = role;
-    messageElement.ariaAtomic = "true";
-    messageElement.innerText = message.trim();
-    return messageElement;
-  }
-}
-
-declare global {
-  /** Utility for generating visually hidden elements that convey descriptive messages using `aria-describedby`. */
-  var M3eAriaDescriber: M3eAriaDescriber;
-}
-
-globalThis.M3eAriaDescriber = M3eAriaDescriber;

package/src/a11y/FocusTrapElement.ts

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

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

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

@@ -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";