@m3e/core 1.0.0-rc.1

package/src/shared/controllers/ResizeController.ts

@@ -0,0 +1,83 @@
+import { isServer, ReactiveControllerHost } from "lit";
+
+import { MonitorControllerBase, MonitorControllerOptions } from "./MonitorControllerBase";
+
+/** The callback function for a `ResizeController`. */
+export type ResizeControllerCallback = (...args: Parameters<ResizeObserverCallback>) => void;
+
+/** Encapsulates options used to configure a `ResizeController`. */
+export interface ResizeControllerOptions extends MonitorControllerOptions {
+  /** The callback used to process detected changes. */
+  callback: ResizeControllerCallback;
+
+  /**
+   * By default, the `callback` is invoked without changes when a
+   * target is observed in order to help maintain initial state. Use
+   * `skipInitial` to skip this step.
+   */
+  skipInitial?: boolean;
+
+  /** The configuration object for the underlying `ResizeObserver`. */
+  config?: ResizeObserverOptions;
+}
+
+/** A `ReactiveController` used to monitor when an element is resized. */
+export class ResizeController extends MonitorControllerBase {
+  /** @private */ readonly #host: ReactiveControllerHost;
+  /** @private */ readonly #callback: ResizeControllerCallback;
+  /** @private */ readonly #skipInitial: boolean;
+  /** @private */ readonly #config?: ResizeObserverOptions;
+  /** @private */ readonly #observer?: ResizeObserver;
+  /** @private */ #unobservedUpdate = true;
+
+  /**
+   * Initializes a new instance of the `ResizeController` class.
+   * @param {ReactiveControllerHost & HTMLElement} host The host element to which this controller will be added.
+   * @param {ResizeControllerOptions} options Options used to configure this controller.
+   */
+  constructor(host: ReactiveControllerHost & HTMLElement, options: ResizeControllerOptions) {
+    super(host, options);
+
+    this.#host = host;
+    this.#callback = options.callback;
+    this.#skipInitial = options.skipInitial ?? false;
+    this.#config = options.config;
+
+    if (isServer) return;
+    if (!window.ResizeObserver) {
+      console.warn("ResizeController error: the browser does not support ResizeObserver.");
+      return;
+    }
+
+    this.#observer = new ResizeObserver((entries, observer) => {
+      this.#callback(entries, observer);
+      this.#host.requestUpdate();
+    });
+  }
+
+  /** @inheritdoc */
+  override async hostUpdated(): Promise<void> {
+    if (this.#observer && !this.#skipInitial && this.#unobservedUpdate) {
+      this.#callback([], this.#observer);
+    }
+    this.#unobservedUpdate = false;
+  }
+
+  /**
+   * Starts observing the specified element.
+   * @param {HTMLElement} target The element to start observing.
+   */
+  protected override _observe(target: HTMLElement): void {
+    this.#observer?.observe(target, this.#config);
+    this.#unobservedUpdate = true;
+    this.#host.requestUpdate();
+  }
+
+  /**
+   * Stops observing the specified element.
+   * @param {HTMLElement} target The element to stop observing.
+   */
+  protected override _unobserve(target: HTMLElement): void {
+    this.#observer?.unobserve(target);
+  }
+}

package/src/shared/controllers/ScrollController.ts

@@ -0,0 +1,100 @@
+import { ReactiveControllerHost } from "lit";
+
+import { MonitorControllerBase, MonitorControllerOptions } from "./MonitorControllerBase";
+import { debounce } from "../decorators";
+
+/** The callback function invoked when a scrollable ancestor is scrolled. */
+export type ScrollControllerCallback = (target: Element) => void;
+
+/** Encapsulates options used to configure a `ScrollController`. */
+export interface ScrollControllerOptions extends MonitorControllerOptions {
+  /** The callback invoked a scrollable ancestor is scrolled. */
+  callback: ScrollControllerCallback;
+
+  /** Whether to debounce scroll events. */
+  debounce?: boolean;
+}
+
+/** A `ReactiveController` used to monitor when a scroll event is emitted from a scrollable ancestor. */
+export class ScrollController extends MonitorControllerBase {
+  /** @private */ readonly #debounce: boolean;
+  /** @private */ readonly #callback: ScrollControllerCallback;
+  /** @private */ readonly #scrollHandler = (e: Event) => this.#handleScroll(e);
+  /** @private */ readonly #scrollContainers = new Map<HTMLElement, Element[]>();
+
+  /**
+   * Initializes a new instance of the `ScrollController` class.
+   * @param {ReactiveControllerHost & HTMLElement} host The host element to which this controller will be added.
+   * @param {ScrollControllerOptions} options Options used to configure this controller.
+   */
+  constructor(host: ReactiveControllerHost & HTMLElement, options: ScrollControllerOptions) {
+    super(host, options);
+    this.#debounce = options.debounce === true;
+    this.#callback = options.callback;
+  }
+
+  /**
+   * Returns the scrollable ancestors for a target element currently being observed by this controller.
+   * @param target The element whose scroll containers are currently being observed.
+   * @returns {Element[] | undefined} The scrollable ancestors, or `undefined` if `target` is not being observed.
+   */
+  getScrollContainers(target: HTMLElement): Element[] | undefined {
+    return this.#scrollContainers.get(target);
+  }
+
+  /** @inheritdoc */
+  protected override _observe(target: HTMLElement): void {
+    const scrollableAncestors = this.#getScrollContainers(target);
+    if (scrollableAncestors.length > 0) {
+      this.#scrollContainers.set(target, scrollableAncestors);
+      for (const ancestor of scrollableAncestors) {
+        (ancestor === document.documentElement ? document : ancestor).addEventListener("scroll", this.#scrollHandler, {
+          passive: true,
+        });
+      }
+    }
+  }
+
+  /** @inheritdoc */
+  protected override _unobserve(target: HTMLElement): void {
+    if (this.#scrollContainers.has(target)) {
+      for (const ancestor of this.#scrollContainers.get(target)!) {
+        (ancestor === document.documentElement ? document : ancestor).removeEventListener(
+          "scroll",
+          this.#scrollHandler
+        );
+      }
+      this.#scrollContainers.delete(target);
+    }
+  }
+
+  /** @private */
+  #getScrollContainers(element: Element): Element[] {
+    const ancestors = new Array<Element>();
+    let ancestor: Element | null = element;
+    while (ancestor) {
+      const style = getComputedStyle(ancestor);
+      if (/(auto|scroll)/.test(style.overflow + style.overflowY + style.overflowX)) {
+        ancestors.push(ancestor);
+      }
+      ancestor = ancestor.parentElement;
+    }
+    return ancestors;
+  }
+
+  /** @private */
+  #handleScroll(e: Event): void {
+    const target = e.target === document ? document.documentElement : e.target;
+    if (this.#debounce) {
+      this._debounceCallback(target as Element);
+    } else {
+      this.#callback(target as Element);
+    }
+  }
+
+  /** @private */
+  @debounce(40)
+  private _debounceCallback(target: Element): void {
+    this.#callback(target);
+  }
+}

package/src/shared/controllers/index.ts

@@ -0,0 +1,8 @@
+export * from "./FocusController";
+export * from "./HoverController";
+export * from "./IntersectionController";
+export * from "./LongPressController";
+export * from "./MutationController";
+export * from "./PressedController";
+export * from "./ResizeController";
+export * from "./ScrollController";

package/src/shared/decorators/debounce.ts

@@ -0,0 +1,19 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * A decorator that runs a function once after a given "cooldown" period.
+ * @param {number} timeout The timeout, in milliseconds, after which the function is invoked.
+ * @returns {MethodDecorator} The decorator that runs a function once after a given "cooldown" period.
+ */
+export function debounce(timeout: number): MethodDecorator {
+  const _id = Symbol("_id");
+  return (_: any, __: PropertyKey | symbol, descriptor: PropertyDescriptor) => {
+    const orig = descriptor.value;
+    descriptor.value = function (...args: any[]) {
+      // eslint-disable-next-line @typescript-eslint/no-this-alias
+      const self: any = this;
+      clearTimeout(self[_id]);
+      self[_id] = setTimeout(() => orig.apply(this, args), timeout);
+    };
+    return descriptor;
+  };
+}

package/src/shared/decorators/index.ts

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

package/src/shared/directives/index.ts

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

package/src/shared/directives/safeStyleMap.ts

@@ -0,0 +1,108 @@
+import { noChange, nothing } from "lit";
+import { AttributePart, directive, Directive, DirectiveParameters, PartInfo, PartType } from "lit/directive.js";
+
+/**
+ * A key-value set of CSS properties and values.
+ *
+ * The key should be either a valid CSS property name string, like
+ * `'background-color'`, or a valid JavaScript camel case property name
+ * for CSSStyleDeclaration like `backgroundColor`.
+ */
+export interface StyleInfo {
+  [name: string]: string | number | undefined | null;
+}
+
+const important = "important";
+// The leading space is important
+const importantFlag = " !" + important;
+// How many characters to remove from a value, as a negative number
+const flagTrim = 0 - importantFlag.length;
+
+class SafeStyleMapDirective extends Directive {
+  private _previousStyleProperties?: Set<string>;
+
+  constructor(partInfo: PartInfo) {
+    super(partInfo);
+    if (partInfo.type !== PartType.ATTRIBUTE || partInfo.name !== "style" || (partInfo.strings?.length as number) > 2) {
+      throw new Error(
+        "The `styleMap` directive must be used in the `style` attribute " +
+          "and must be the only part in the attribute."
+      );
+    }
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render(_: Readonly<StyleInfo>) {
+    return nothing;
+  }
+
+  override update(part: AttributePart, [styleInfo]: DirectiveParameters<this>) {
+    const { style } = part.element as HTMLElement;
+
+    if (this._previousStyleProperties === undefined) {
+      this._previousStyleProperties = new Set(Object.keys(styleInfo));
+    }
+
+    // Remove old properties that no longer exist in styleInfo
+    for (const name of this._previousStyleProperties) {
+      // If the name isn't in styleInfo or it's null/undefined
+      if (styleInfo[name] == null) {
+        this._previousStyleProperties!.delete(name);
+        if (name.includes("-")) {
+          style.removeProperty(name);
+        } else {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          (style as any)[name] = null;
+        }
+      }
+    }
+
+    // Add or update properties
+    for (const name in styleInfo) {
+      const value = styleInfo[name];
+      if (value != null) {
+        this._previousStyleProperties.add(name);
+        const isImportant = typeof value === "string" && value.endsWith(importantFlag);
+        if (name.includes("-") || isImportant) {
+          style.setProperty(
+            name,
+            isImportant ? (value as string).slice(0, flagTrim) : (value as string),
+            isImportant ? important : ""
+          );
+        } else {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          (style as any)[name] = value;
+        }
+      }
+    }
+    return noChange;
+  }
+}
+
+/**
+ * A directive that applies CSS properties to an element.
+ *
+ * `safeStyleMap` can only be used in the `style` attribute and must be the only
+ * expression in the attribute. It takes the property names in the
+ * {@link StyleInfo styleInfo} object and adds the properties to the inline
+ * style of the element.
+ *
+ * Property names with dashes (`-`) are assumed to be valid CSS
+ * property names and set on the element's style object using `setProperty()`.
+ * Names without dashes are assumed to be camelCased JavaScript property names
+ * and set on the element's style object using property assignment, allowing the
+ * style object to translate JavaScript-style names to CSS property names.
+ *
+ * For example `safeStyleMap({backgroundColor: 'red', 'border-top': '5px', '--size':
+ * '0'})` sets the `background-color`, `border-top` and `--size` properties.
+ *
+ * @param styleInfo
+ * @see {@link https://lit.dev/docs/templates/directives/#stylemap styleMap code samples on Lit.dev}
+ */
+export const safeStyleMap = directive(SafeStyleMapDirective);
+
+/**
+ * The type of the class that powers this directive. Necessary for naming the
+ * directive's return type.
+ */
+export type { SafeStyleMapDirective };

package/src/shared/index.ts

@@ -0,0 +1,7 @@
+export * from "./controllers";
+export * from "./decorators";
+export * from "./directives";
+export * from "./mixins";
+export * from "./primitives";
+export * from "./tokens";
+export * from "./utils";

package/src/shared/mixins/AttachInternals.ts

@@ -0,0 +1,48 @@
+import { LitElement } from "lit";
+
+import { Constructor } from "./Constructor";
+import { hasKeys } from "./hasKeys";
+
+/** A symbol through which to access the `ElementInternals` attached to an element. */
+export const internals = Symbol("internals");
+
+/** Defines functionality for an element attached to `ElementInternals`. */
+export interface AttachInternalsMixin {
+  /** The `ElementInternals` attached to the element. */
+  readonly [internals]: ElementInternals;
+}
+
+/**
+ * Determines whether a value is an `AttachInternalsMixin`.
+ * @param {unknown} value The value to test.
+ * @returns Whether `value` is an `AttachInternalsMixin`.
+ */
+export function isAttachInternalsMixin(value: unknown): value is AttachInternalsMixin {
+  return hasKeys<AttachInternalsMixin>(value, internals);
+}
+
+const _internals = Symbol("_internals");
+
+/**
+ * Mixin to augment an element with behavior that attaches to `ElementInternals`.
+ * @template T The type of the base class.
+ * @param {T} base The base class.
+ * @param {boolean | undefined} formAssociated Whether the element is "Form Associated".
+ * @returns {Constructor<AttachInternalsMixin> & T} A constructor that implements `AttachInternalsMixin`.
+ */
+export function AttachInternals<T extends Constructor<LitElement>>(
+  base: T,
+  formAssociated?: boolean
+): Constructor<AttachInternalsMixin> & T {
+  abstract class _AttachInternals extends base implements AttachInternalsMixin {
+    static readonly formAssociated = formAssociated;
+
+    private [_internals]?: ElementInternals;
+
+    get [internals](): ElementInternals {
+      return this[_internals] ?? (this[_internals] = this.attachInternals());
+    }
+  }
+
+  return _AttachInternals;
+}

package/src/shared/mixins/Checked.ts

@@ -0,0 +1,50 @@
+import { LitElement, PropertyValues } from "lit";
+import { property } from "lit/decorators.js";
+
+import { Constructor } from "./Constructor";
+import { hasKeys } from "./hasKeys";
+
+/** Defines functionality for an element which supports a checked state. */
+export interface CheckedMixin {
+  /**
+   * Whether the element is checked.
+   * @default false
+   */
+  checked: boolean;
+}
+
+/**
+ * Determines whether a value is a `CheckedMixin`.
+ * @param {unknown} value The value to test.
+ * @returns Whether `value` is a `CheckedMixin`.
+ */
+export function isCheckedMixin(value: unknown): value is CheckedMixin {
+  return hasKeys<CheckedMixin>(value, "checked");
+}
+
+/**
+ * Mixin to augment an element with behavior that supports a checked state.
+ * @template T The type of the base class.
+ * @param {T} base The base class.
+ * @returns {Constructor<CheckedMixin> & T} A constructor that implements `CheckedMixin`.
+ */
+export function Checked<T extends Constructor<LitElement>>(base: T): Constructor<CheckedMixin> & T {
+  abstract class _CheckedMixin extends base implements CheckedMixin {
+    @property({ type: Boolean, reflect: true }) checked = false;
+
+    protected override update(changedProperties: PropertyValues<this>): void {
+      super.update(changedProperties);
+
+      if (changedProperties.has("checked")) {
+        if (this.role === "button") {
+          this.ariaPressed = `${this.checked}`;
+          this.ariaChecked = null;
+        } else if (this.role && this.role !== "none" && this.role !== "presentation") {
+          this.ariaChecked = `${this.checked}`;
+          this.ariaPressed = null;
+        }
+      }
+    }
+  }
+  return _CheckedMixin;
+}

package/src/shared/mixins/CheckedIndeterminate.ts

@@ -0,0 +1,47 @@
+import { LitElement, PropertyValues } from "lit";
+import { property } from "lit/decorators.js";
+
+import { Checked, CheckedMixin, isCheckedMixin } from "./Checked";
+import { Constructor } from "./Constructor";
+import { hasKeys } from "./hasKeys";
+
+/** Defines functionality for an element which supports a mixed checked state. */
+export interface CheckedIndeterminateMixin extends CheckedMixin {
+  /**
+   * Whether the element's checked state is indeterminate.
+   * @default false
+   */
+  indeterminate: boolean;
+}
+
+/**
+ * Determines whether a value is a `CheckedIndeterminateMixin`.
+ * @param {unknown} value The value to test.
+ * @returns Whether `value` is a `CheckedIndeterminateMixin`.
+ */
+export function isCheckedIndeterminateMixin(value: unknown): value is CheckedIndeterminateMixin {
+  return hasKeys<CheckedIndeterminateMixin>(value, "indeterminate") && isCheckedMixin(value);
+}
+
+/**
+ * Mixin to augment an element with behavior that supports a mixed checked state.
+ * @template T The type of the base class.
+ * @param {T} base The base class.
+ * @returns {Constructor<CheckedIndeterminateMixin> & T} A constructor that implements `CheckedIndeterminateMixin`.
+ */
+export function CheckedIndeterminate<T extends Constructor<LitElement>>(
+  base: T
+): Constructor<CheckedIndeterminateMixin> & T {
+  abstract class _CheckedIndeterminateMixin extends Checked(base) implements CheckedIndeterminateMixin {
+    @property({ type: Boolean, reflect: true }) indeterminate = false;
+
+    protected override update(changedProperties: PropertyValues<this>): void {
+      super.update(changedProperties);
+
+      if (changedProperties.has("indeterminate") && this.role && this.role !== "none" && this.role !== "presentation") {
+        this.ariaChecked = !this.checked && this.indeterminate ? "mixed" : `${this.checked}`;
+      }
+    }
+  }
+  return _CheckedIndeterminateMixin;
+}

package/src/shared/mixins/CheckedOrSelected.ts

@@ -0,0 +1,36 @@
+import { CheckedMixin, isCheckedMixin } from "./Checked";
+import { isSelectedMixin, SelectedMixin } from "./Selected";
+
+/** Defines functionality for an element which supports either a checked or selected state. */
+export type CheckedOrSelectedMixin = CheckedMixin | SelectedMixin;
+
+/**
+ * Determines whether a value is a `CheckedOrSelectedMixin`.
+ * @param {unknown} value The value to test.
+ * @returns Whether `value` is a `CheckedOrSelectedMixin`.
+ */
+export function isCheckedOrSelectedMixin(value: unknown): value is CheckedOrSelectedMixin {
+  return isCheckedMixin(value) || isSelectedMixin(value);
+}
+
+/**
+ * Determines whether the state of an element is checked or selected.
+ * @param {CheckedOrSelectedMixin} element The element to test.
+ * @return {boolean} Whether `element` is checked or selected.
+ */
+export function isCheckedOrSelected(element: CheckedOrSelectedMixin): boolean {
+  return (isCheckedMixin(element) && element.checked) || (isSelectedMixin(element) && element.selected);
+}
+
+/**
+ * Sets the checked or selected state of an element.
+ * @param {CheckedOrSelectedMixin} element The element for which to set the checked or selected state.
+ * @param {boolean} checkedOrSelected The checked or selected state.
+ */
+export function checkOrSelect(element: CheckedOrSelectedMixin, checkedOrSelected: boolean): void {
+  if (isCheckedMixin(element)) {
+    element.checked = checkedOrSelected;
+  } else {
+    element.selected = checkedOrSelected;
+  }
+}