@m3e/core 1.0.0-rc.1

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

@@ -0,0 +1,131 @@
+/**
+ * Adapted from Angular Material CDK KeyManager
+ * Source: https://github.com/angular/components/blob/main/src/cdk/a11y/key-manager/typeahead.ts
+ *
+ * @license MIT
+ * Copyright (c) 2025 Google LLC
+ * See LICENSE file in the project root for full license text.
+ */
+
+import { getKeyCode, KeyCode } from "../keycodes";
+import { hasKeys } from "../../shared/mixins/hasKeys";
+
+/** A symbol through which to access an element's textual content used for typeahead search. */
+export const typeaheadLabel = Symbol("typeaheadLabel");
+
+/** Defines functionality required for an item that supports searching using typeahead. */
+export interface TypeaheadItem {
+  /** Returns the textual content to search. */
+  [typeaheadLabel]?(): string;
+}
+
+/**
+ * Determines whether a value is a `TypeaheadItem`.
+ * @param {unknown} value The value to test.
+ * @returns A value indicating whether `value` is an `TypeaheadItem`.
+ */
+export function isTypeaheadItem(value: unknown): value is TypeaheadItem {
+  return hasKeys<TypeaheadItem>(value, typeaheadLabel);
+}
+
+/** Encapsulates options used to select items based on typeahead.
+ * @template T The type of `TypeaheadItem`.
+ */
+export interface TypeaheadOptions<T extends TypeaheadItem = TypeaheadItem> {
+  /** The interval, in milliseconds, before searching items. */
+  debounceInterval?: number;
+
+  /** Function used to determine whether an item should be skipped. */
+  skipPredicate?: (item: T) => boolean;
+
+  /** Function invoked when an item is selected. */
+  callback: (item: T) => void;
+}
+
+/**
+ * Implements typeahead functionality which selects items based on keyboard input.
+ * @template T The type of `TypeaheadItem`.
+ */
+export class Typeahead<T extends TypeaheadItem = TypeaheadItem> {
+  /** @private */ #debounceInterval: number;
+  /** @private */ #timeoutId = -1;
+  /** @private */ #callback: (item: T) => void;
+  /** @private */ #skipPredicate?: (item: T) => boolean;
+
+  /** @private */ #pressedKeys = new Array<string>();
+  /** @private */ #selectedIndex = -1;
+  /** @private */ #items: readonly T[] = [];
+
+  /**
+   * Initializes a new instance of this class.
+   * @param {TypeaheadOptions<T>} options Options that control typeahead behavior.
+   */
+  constructor(options: TypeaheadOptions<T>) {
+    this.#debounceInterval = options.debounceInterval ?? 200;
+    this.#callback = options.callback;
+    this.#skipPredicate = options.skipPredicate;
+  }
+
+  /** A value indicating whether the user is currently typing. */
+  get isTyping(): boolean {
+    return this.#pressedKeys.length > 0;
+  }
+
+  /**
+   * Sets the items to search.
+   * @param {readonly T[]} items The items to search.
+   */
+  setItems(items: readonly T[]): void {
+    this.#items = items;
+  }
+
+  /**
+   * Sets the index of the selected item.
+   * @param {number} index The index of the selected item.
+   */
+  setSelectedIndex(index: number): void {
+    this.#selectedIndex = index;
+  }
+
+  /** Resets the stored sequence of typed characters. */
+  reset(): void {
+    this.#pressedKeys.length = 0;
+  }
+
+  /**
+   * Sets the selected 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.key && e.key.length === 1) {
+      this.#appendKey(e.key);
+    } else {
+      const keycode = getKeyCode(e);
+      if ((keycode >= KeyCode.A && keycode <= KeyCode.Z) || (keycode >= KeyCode.Zero && keycode <= KeyCode.Nine)) {
+        this.#appendKey(String.fromCharCode(keycode));
+      }
+    }
+  }
+
+  /** @private */
+  #appendKey(key: string): void {
+    this.#pressedKeys.push(key.toLocaleUpperCase());
+    clearTimeout(this.#timeoutId);
+    this.#timeoutId = setTimeout(() => this.#searchItems(), this.#debounceInterval);
+  }
+
+  /** @private */
+  #searchItems(): void {
+    const term = this.#pressedKeys.join("");
+    for (let i = 1; i < this.#items.length + 1; i++) {
+      const index = (this.#selectedIndex + i) % this.#items.length;
+      const item = this.#items[index];
+      const label = item[typeaheadLabel]?.().toLocaleUpperCase().trim();
+      if (!this.#skipPredicate?.(item) && label?.indexOf(term) === 0) {
+        this.#callback(item);
+        break;
+      }
+    }
+    this.reset();
+  }
+}

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

@@ -0,0 +1,7 @@
+export * from "./FocusKeyManager";
+export * from "./ListKeyManager";
+export * from "./ListManager";
+export * from "./RadioKeyManager";
+export * from "./RovingTabIndexManager";
+export * from "./SelectionManager";
+export * from "./Typeahead";

package/src/a11y/visuallyHide.ts

@@ -0,0 +1,18 @@
+/**
+ * Visually hides an element.
+ * @param {CSSStyleDeclaration} style The style of the element to visually hide.
+ */
+export function visuallyHide(style: CSSStyleDeclaration): void {
+  style.position = "absolute";
+  style.appearance = "none";
+  style.visibility = "hidden";
+  style.border = "0";
+  style.outline = "0";
+  style.overflow = "hidden";
+  style.left = "0";
+  style.height = "1px";
+  style.width = "1px";
+  style.margin = "-1px";
+  style.padding = "0";
+  style.whiteSpace = "nowrap";
+}

package/src/anchoring/AnchorOptions.ts

@@ -0,0 +1,19 @@
+import { AnchorPosition } from "./AnchorPosition";
+
+/** Options used to anchor an element to another. */
+export interface AnchorOptions {
+  /** The position of the element, relative to the anchor. */
+  position: AnchorPosition;
+
+  /** Whether to improve positioning for inline elements which can span multiple lines. */
+  inline?: boolean;
+
+  /** Whether the element can be shifted to keep it in view. */
+  shift?: boolean;
+
+  /** Whether the element can flip to keep it in view. */
+  flip?: boolean | AnchorPosition[];
+
+  /** The logical margin, in pixels, between element and its anchor. */
+  offset?: number;
+}

package/src/anchoring/AnchorPosition.ts

@@ -0,0 +1,14 @@
+/** Specifies the possible positions in which to anchor an element to another. */
+export type AnchorPosition =
+  | "top"
+  | "right"
+  | "bottom"
+  | "left"
+  | "top-start"
+  | "top-end"
+  | "right-start"
+  | "right-end"
+  | "bottom-start"
+  | "bottom-end"
+  | "left-start"
+  | "left-end";

package/src/anchoring/index.ts

@@ -0,0 +1,3 @@
+export * from "./AnchorOptions";
+export * from "./AnchorPosition";
+export * from "./positionAnchor";

package/src/anchoring/positionAnchor.ts

@@ -0,0 +1,53 @@
+import { autoUpdate, computePosition, flip, inline, Middleware, offset, platform, shift } from "@floating-ui/dom";
+import { offsetParent } from "composed-offset-position";
+
+import { AnchorOptions } from "./AnchorOptions";
+import { AnchorPosition } from "./AnchorPosition";
+
+/**
+ * Positions an element relative to an anchor element.
+ * @param {HTMLElement} target The element to position.
+ * @param {HTMLElement} anchor The element in which to anchor `target`.
+ * @param {AnchorOptions} options Options that control positioning relative to the anchor.
+ * @param {((x: number, y: number, position: AnchorPosition) => void) | undefined} update Callback used to position `target`.
+ * @returns {Promise<() => void>} Promise that resolves to a function used to stop updating target when the position of the anchor element changes.
+ */
+export async function positionAnchor(
+  target: HTMLElement,
+  anchor: HTMLElement,
+  options: AnchorOptions,
+  update?: (x: number, y: number, position: AnchorPosition) => void
+): Promise<() => void> {
+  async function computeAnchorPosition() {
+    const middleware = new Array<Middleware>();
+
+    if (options?.inline) {
+      middleware.push(inline());
+    }
+    if (options.flip) {
+      middleware.push(options.flip === true ? flip() : flip({ fallbackPlacements: options.flip }));
+    }
+    if (options.shift) {
+      middleware.push(shift());
+    }
+    if (options.offset && !isNaN(options.offset)) {
+      middleware.push(offset(options.offset));
+    }
+
+    const result = await computePosition(anchor, target, {
+      placement: options.position,
+      middleware: middleware,
+      platform: { ...platform, getOffsetParent: (x) => platform.getOffsetParent(x, offsetParent) },
+    });
+
+    if (!update) {
+      target.style.left = `${result.x}px`;
+      target.style.top = `${result.y}px`;
+    } else {
+      update(result.x, result.y, result.placement);
+    }
+  }
+
+  await computeAnchorPosition();
+  return autoUpdate(anchor, target, async () => await computeAnchorPosition());
+}

package/src/bidi/Directionality.ts

@@ -0,0 +1,85 @@
+/**
+ * Adapted from Angular Material CDK Directionality
+ * Source: https://github.com/angular/components/blob/main/src/cdk/bidi/directionality.ts
+ *
+ * @license MIT
+ * Copyright (c) 2025 Google LLC
+ * See LICENSE file in the project root for full license text.
+ */
+
+import { isServer } from "lit";
+
+/** Taken from `goog.i18n.bidi.isRtlLanguage`. */
+const RTL_LOCALES =
+  /^(ar|ckb|dv|he|iw|fa|nqo|ps|sd|ug|ur|yi|.*[-_](Adlm|Arab|Hebr|Nkoo|Rohg|Thaa))(?!.*[-_](Latn|Cyrl)($|-|_))($|-|_)/i;
+
+/** Specifies the directionalities for a document. */
+export type Direction = "ltr" | "rtl";
+
+/** Utility used to determine the directionality of the current document. */
+export class M3eDirectionality {
+  /** @private */ static #current: Direction = "ltr";
+  /** @private */ static readonly #observers = Array<() => void>();
+
+  static {
+    if (!isServer) {
+      this.#updateDirection();
+
+      if (MutationObserver) {
+        const init: MutationObserverInit = { attributeFilter: ["dir"] };
+        const observer = new MutationObserver(() => this.#handleChange());
+        if (document.body) {
+          observer.observe(document.body, init);
+        }
+        if (document.documentElement) {
+          observer.observe(document.documentElement, init);
+        }
+      }
+
+      window.addEventListener("languagechange", () => this.#handleChange());
+    }
+  }
+
+  /** The directionality of the current document. */
+  static get current(): Direction {
+    return this.#current;
+  }
+
+  /**
+   * Observes changes to directionality.
+   * @param {()=>void} callback Function invoked when directionality changes.
+   * @returns {()=>void} A function used to unobserve changes.
+   */
+  static observe(callback: () => void): () => void {
+    this.#observers.push(callback);
+    return () => {
+      this.#observers.splice(this.#observers.indexOf(callback), 1);
+    };
+  }
+
+  /** @private */
+  static #updateDirection() {
+    const _dir = (document?.body?.dir || document?.documentElement?.dir)?.toLowerCase() || "auto";
+    this.#current =
+      _dir === "auto" && !isServer && navigator?.language
+        ? RTL_LOCALES.test(navigator.language)
+          ? "rtl"
+          : "ltr"
+        : _dir === "rtl"
+        ? "rtl"
+        : "ltr";
+  }
+
+  /** @private */
+  static #handleChange(): void {
+    this.#updateDirection();
+    this.#observers.forEach((x) => x());
+  }
+}
+
+declare global {
+  /** Utility used to determine the directionality of the current document. */
+  var M3eDirectionality: M3eDirectionality;
+}
+
+globalThis.M3eDirectionality = M3eDirectionality;

package/src/bidi/index.ts

@@ -0,0 +1 @@
+export * from "./Directionality";

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./shared";

package/src/layout/Breakpoint.ts

@@ -0,0 +1,26 @@
+/**
+ * Adapted from Angular Material CDK Breakpoints
+ * Source: https://github.com/angular/components/blob/main/src/cdk/layout/breakpoints.ts
+ *
+ * @license MIT
+ * Copyright (c) 2025 Google LLC
+ * See LICENSE file in the project root for full license text.
+ */
+
+/** Specifies predefined breakpoints. */
+export enum Breakpoint {
+  XSmall = "(max-width: 599.98px)",
+  Small = "(min-width: 600px) and (max-width: 959.98px)",
+  Medium = "(min-width: 960px) and (max-width: 1279.98px)",
+  Large = "(min-width: 1280px) and (max-width: 1919.98px)",
+  XLarge = "(min-width: 1920px)",
+  Handset = "(max-width: 599.98px) and (orientation: portrait), (max-width: 959.98px) and (orientation: landscape)",
+  Tablet = "(min-width: 600px) and (max-width: 839.98px) and (orientation: portrait), (min-width: 960px) and (max-width: 1279.98px) and (orientation: landscape)",
+  Web = "(min-width: 840px) and (orientation: portrait), (min-width: 1280px) and (orientation: landscape)",
+  HandsetPortrait = "(max-width: 599.98px) and (orientation: portrait)",
+  TabletPortrait = "(min-width: 600px) and (max-width: 839.98px) and (orientation: portrait)",
+  WebPortrait = "(min-width: 840px) and (orientation: portrait)",
+  HandsetLandscape = "(max-width: 959.98px) and (orientation: landscape)",
+  TabletLandscape = "(min-width: 960px) and (max-width: 1279.98px) and (orientation: landscape)",
+  WebLandscape = "(min-width: 1280px) and (orientation: landscape)",
+}

package/src/layout/BreakpointObserver.ts

@@ -0,0 +1,44 @@
+import { isServer } from "lit";
+
+import { Breakpoint } from "./Breakpoint";
+
+/** The callback function invoked when the viewport size changes. */
+export type BreakpointObserverCallback = (matches: Map<Breakpoint | string, boolean>) => void;
+
+/** Utility used to detect changes to viewport sizes. */
+export class M3eBreakpointObserver {
+  /**
+   * Observes changes to viewport sizes.
+   * @param {Array<Breakpoint | string>} breakpoints The breakpoints to observe.
+   * @param {BreakpointObserverCallback} callback The callback function invoked when the viewport size changes.
+   * @returns {() => void} A function used to stop observing changes to viewport sizes.
+   */
+  static observe(breakpoints: Array<Breakpoint | string>, callback: BreakpointObserverCallback): () => void {
+    if (isServer || breakpoints.length == 0) {
+      return () => {};
+    }
+
+    const mediaQueries = breakpoints.map((x) => matchMedia(x));
+    const changeHandler = () => {
+      const map = new Map<Breakpoint | string, boolean>();
+      breakpoints.forEach((x, i) => map.set(x, mediaQueries[i].matches));
+      callback(map);
+    };
+
+    mediaQueries.forEach((x) => x.addEventListener("change", changeHandler));
+
+    changeHandler();
+
+    return () => {
+      mediaQueries.forEach((x) => x.removeEventListener("change", changeHandler));
+      mediaQueries.length = 0;
+    };
+  }
+}
+
+declare global {
+  /** Utility used to detect changes to viewport sizes. */
+  var M3eBreakpointObserver: M3eBreakpointObserver;
+}
+
+globalThis.M3eBreakpointObserver = M3eBreakpointObserver;

package/src/layout/index.ts

@@ -0,0 +1,2 @@
+export * from "./Breakpoint";
+export * from "./BreakpointObserver";

package/src/platform/Platform.ts

@@ -0,0 +1,67 @@
+/**
+ * Adapted from Angular Material CDK Platform
+ * Source: https://github.com/angular/components/blob/main/src/cdk/platform/platform.ts
+ *
+ * @license MIT
+ * Copyright (c) 2025 Google LLC
+ * See LICENSE file in the project root for full license text.
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { isServer } from "lit";
+
+let hasV8BreakIterator: boolean;
+
+try {
+  hasV8BreakIterator = typeof Intl !== "undefined" && (Intl as any).v8BreakIterator;
+} catch {
+  hasV8BreakIterator = false;
+}
+
+/** Utility used to detect the current platform. */
+export class M3ePlatform {
+  /** A value indicating whether the platform is a browser. */
+  static readonly isBrowser = !isServer && typeof document === "object" && !!document;
+
+  /** A value indicating whether the current browser is Microsoft Edge. */
+  static readonly Edge = M3ePlatform.isBrowser && /(edge)/i.test(navigator.userAgent);
+
+  /** A value indicating whether the current rendering engine is Microsoft Trident. */
+  static readonly Trident = M3ePlatform.isBrowser && /(msie|trident)/i.test(navigator.userAgent);
+
+  /** A value indicating whether the current rendering engine is Blink. */
+  static readonly Blink =
+    M3ePlatform.isBrowser &&
+    !!((window as any).chrome || hasV8BreakIterator) &&
+    typeof CSS !== "undefined" &&
+    !M3ePlatform.Edge &&
+    !M3ePlatform.Trident;
+
+  /** A value indicating whether the current rendering engine is WebKit. */
+  static readonly WebKit =
+    M3ePlatform.isBrowser &&
+    /AppleWebKit/i.test(navigator.userAgent) &&
+    !M3ePlatform.Blink &&
+    !M3ePlatform.Edge &&
+    !M3ePlatform.Trident;
+
+  /** A value indicating whether the current platform is Apply iOS. */
+  static readonly iOS =
+    M3ePlatform.isBrowser && /iPad|iPhone|iPod/.test(navigator.userAgent) && !("MSStream" in window);
+
+  /** A value indicating whether the current browser is Firefox. */
+  static readonly Firefox = M3ePlatform.isBrowser && /(firefox|minefield)/i.test(navigator.userAgent);
+
+  /** A value indicating whether the current platform is Android. */
+  static readonly Android = M3ePlatform.isBrowser && /android/i.test(navigator.userAgent) && !M3ePlatform.Trident;
+
+  /** A value indicating whether the current browser is Safari. */
+  static readonly Safari = M3ePlatform.isBrowser && /safari/i.test(navigator.userAgent) && M3ePlatform.WebKit;
+}
+
+declare global {
+  /** Utility used to detect the current platform. */
+  var M3ePlatform: M3ePlatform;
+}
+
+globalThis.M3ePlatform = M3ePlatform;

package/src/platform/index.ts

@@ -0,0 +1 @@
+export * from "./Platform";

package/src/shared/controllers/FocusController.ts

@@ -0,0 +1,60 @@
+import { ReactiveControllerHost } from "lit";
+
+import { MonitorControllerBase, MonitorControllerOptions } from "./MonitorControllerBase";
+
+/** The callback function invoked when the focused state of an element changes. */
+export type FocusControllerCallback = (focused: boolean, focusVisible: boolean, target: HTMLElement) => void;
+
+/** Encapsulates options used to configure a `FocusController`. */
+export interface FocusControllerOptions extends MonitorControllerOptions {
+  /** The callback invoked when the focused state of an element changes. */
+  callback: FocusControllerCallback;
+}
+
+/** A `ReactiveController` used to monitor the focused state of one or more elements. */
+export class FocusController extends MonitorControllerBase {
+  /** @private */ readonly #callback: FocusControllerCallback;
+  /** @private */ readonly #focusInHandler = (e: Event) => this.#handleFocusIn(e);
+  /** @private */ readonly #focusOutHandler = (e: Event) => this.#handleFocusOut(e);
+
+  /**
+   * Initializes a new instance of this class.
+   * @param {ReactiveControllerHost & HTMLElement} host The host element to which this controller will be added.
+   * @param {FocusControllerOptions} options Options used to configure this controller.
+   */
+  constructor(host: ReactiveControllerHost & HTMLElement, options: FocusControllerOptions) {
+    super(host, options);
+    this.#callback = options.callback;
+  }
+
+  /**
+   * Starts observing the specified element.
+   * @param {HTMLElement} target The element to start observing.
+   */
+  protected override _observe(target: HTMLElement): void {
+    target.addEventListener("keydown", this.#focusInHandler);
+    target.addEventListener("focusin", this.#focusInHandler);
+    target.addEventListener("focusout", this.#focusOutHandler);
+  }
+
+  /**
+   * Stops observing the specified element.
+   * @param {HTMLElement} target The element to stop observing.
+   */
+  protected override _unobserve(target: HTMLElement): void {
+    target.removeEventListener("keydown", this.#focusInHandler);
+    target.removeEventListener("focusin", this.#focusInHandler);
+    target.removeEventListener("focusout", this.#focusOutHandler);
+  }
+
+  /** @private */
+  #handleFocusIn(e: Event): void {
+    const target = e.target as HTMLElement;
+    this.#callback(true, target.matches(":focus-visible") || matchMedia("(forced-colors: active)").matches, target);
+  }
+
+  /** @private */
+  #handleFocusOut(e: Event): void {
+    this.#callback(false, false, e.target as HTMLElement);
+  }
+}