@m3e/core 1.0.0-rc.1

package/src/shared/mixins/FormSubmitter.ts

@@ -0,0 +1,123 @@
+import { LitElement } from "lit";
+import { property } from "lit/decorators.js";
+
+import { AttachInternalsMixin, internals, isAttachInternalsMixin } from "./AttachInternals";
+import { Constructor } from "./Constructor";
+import { hasKeys } from "./hasKeys";
+import { isDisabledMixin } from "./Disabled";
+import { isDisabledInteractiveMixin } from "./DisabledInteractive";
+
+/** Specifies the form submission behaviors. */
+export type FormSubmitterType = "button" | "submit" | "reset";
+
+/** Defines functionality for an element which can be used to submit a form. */
+export interface FormSubmitterMixin extends AttachInternalsMixin {
+  /**
+   * The name of the element, submitted as a pair with the element's `value`
+   * as part of form data, when the element is used to submit a form.
+   */
+  name: string;
+
+  /** The value associated with the element's name when it's submitted with form data. */
+  value: string | null;
+
+  /** The type of the element. */
+  type: FormSubmitterType;
+}
+
+/**
+ * Determines whether a value is a `FormSubmitterMixin`.
+ * @param {unknown} value The value to test.
+ * @returns {value is FormSubmitterMixin} Whether `value` is a `FormSubmitterMixin`.
+ */
+export function isFormSubmitterMixin(value: unknown): value is FormSubmitterMixin {
+  return hasKeys<FormSubmitterMixin>(value, "name", "type", "value") && isAttachInternalsMixin(value);
+}
+
+const _clickHandler = Symbol("_clickHandler");
+
+/**
+ * Mixin to augment an element with behavior used to submit a form.
+ * @template T The type of the base class.
+ * @param {T} base The base class.
+ * @returns {Constructor<FormSubmitterMixin>} A constructor that implements `FormSubmitterMixin`.
+ */
+export function FormSubmitter<T extends Constructor<LitElement & AttachInternalsMixin>>(
+  base: T
+): Constructor<FormSubmitterMixin> & T {
+  abstract class _FormSubmitterMixin extends base implements FormSubmitterMixin {
+    @property() get name() {
+      return this.getAttribute("name") ?? "";
+    }
+    set name(value: string) {
+      if (value) {
+        this.setAttribute("name", value);
+      } else {
+        this.removeAttribute("name");
+      }
+    }
+    @property() get value() {
+      return this.getAttribute("value");
+    }
+    set value(value: string | null) {
+      if (value !== null && value !== undefined) {
+        this.setAttribute("value", value);
+      } else {
+        this.removeAttribute("value");
+      }
+    }
+
+    @property() type: FormSubmitterType = "button";
+
+    override connectedCallback(): void {
+      super.connectedCallback();
+      this.addEventListener("click", this[_clickHandler]);
+    }
+
+    override disconnectedCallback(): void {
+      super.disconnectedCallback();
+      this.removeEventListener("click", this[_clickHandler]);
+    }
+
+    private [_clickHandler] = async (e: Event) => {
+      if ((isDisabledMixin(this) && this.disabled) || (isDisabledInteractiveMixin(this) && this.disabledInteractive)) {
+        return;
+      }
+
+      const form = this[internals].form;
+      if (!form || this.type === "button") {
+        return;
+      }
+
+      await new Promise<void>((resolve) => setTimeout(resolve));
+
+      if (e.defaultPrevented) {
+        return;
+      }
+
+      switch (this.type) {
+        case "reset":
+          form.reset();
+          break;
+
+        case "submit":
+          form.addEventListener(
+            "submit",
+            (e) =>
+              Object.defineProperty(e, "submitter", {
+                configurable: true,
+                enumerable: true,
+                get: () => this,
+              }),
+            { capture: true, once: true }
+          );
+
+          this[internals].setFormValue(this.value);
+          form.requestSubmit();
+          break;
+      }
+    };
+  }
+
+  return _FormSubmitterMixin;
+}

package/src/shared/mixins/HtmlFor.ts

@@ -0,0 +1,89 @@
+import { LitElement, PropertyValues } from "lit";
+import { property } from "lit/decorators.js";
+
+import { Constructor } from "./Constructor";
+import { hasKeys } from "./hasKeys";
+
+/** Defines functionality for an attached element associated with an interactive control. */
+export interface HtmlForMixin {
+  /** The identifier of the interactive control to which this element is attached. */
+  htmlFor: string | null;
+
+  /** The interactive element to which this element is attached. */
+  readonly control: HTMLElement | null;
+
+  /**
+   * Attaches the element to an interactive control.
+   * @param {HTMLElement} control The element that controls the attachable element.
+   */
+  attach(control: HTMLElement): void;
+
+  /** Detaches the element from its current interactive control. */
+  detach(): void;
+}
+
+/**
+ * Determines whether a value is a `HtmlForMixin`.
+ * @param {unknown} value The value to test.
+ * @returns {value is HtmlForMixin} Whether `value` is a `HtmlForMixin`.
+ */
+export function isHtmlForMixin(value: unknown): value is HtmlForMixin {
+  return hasKeys<HtmlForMixin>(value, "htmlFor", "control", "attach", "detach");
+}
+
+const _control = Symbol("_control");
+const _firstUpdated = Symbol("_firstUpdated");
+
+/**
+ * Mixin that creates an attached element associated with an interactive control.
+ * @template T The type of the base class.
+ * @param {T} base The base class.
+ * @returns {Constructor<HtmlForMixin> & T} A constructor extends `base` and implements `HtmlForMixin`.
+ */
+export function HtmlFor<T extends Constructor<LitElement>>(base: T): Constructor<HtmlForMixin> & T {
+  abstract class _HtmlForMixin extends base implements HtmlForMixin {
+    /** @private */ private [_control]: HTMLElement | null = null;
+    /** @private */ private [_firstUpdated] = false;
+
+    @property({ attribute: "for" }) htmlFor: string | null = null;
+
+    get control() {
+      return this[_control];
+    }
+
+    protected override firstUpdated(_changedProperties: PropertyValues): void {
+      super.firstUpdated(_changedProperties);
+      this[_firstUpdated] = true;
+    }
+
+    protected override update(changedProperties: PropertyValues<this>): void {
+      super.update(changedProperties);
+
+      if (changedProperties.has("htmlFor")) {
+        if (this.htmlFor) {
+          const control = (this.getRootNode() as ParentNode)?.querySelector(`#${this.htmlFor}`);
+          if (control !== this.control) {
+            if (this.control) {
+              this.detach();
+            }
+            if (control instanceof HTMLElement) {
+              this.attach(control);
+            }
+          }
+        } else if (this.control && this[_firstUpdated]) {
+          this.detach();
+        }
+      }
+    }
+
+    attach(control: HTMLElement): void {
+      this[_control] = control;
+    }
+
+    detach(): void {
+      this[_control] = null;
+    }
+  }
+
+  return _HtmlForMixin;
+}

package/src/shared/mixins/KeyboardClick.ts

@@ -0,0 +1,46 @@
+import { LitElement } from "lit";
+
+import { Constructor } from "./Constructor";
+import { isDisabledMixin } from "./Disabled";
+import { isDisabledInteractiveMixin } from "./DisabledInteractive";
+
+/**
+ * Mixin to augment an element with behavior emits a click event on keyboard events.
+ * @template T The type of the base class.
+ * @param {T} base The base class.
+ * @param {boolean} [allowEnter=true] Whether the `ENTER` key emits a click event.
+ * @returns {T} A class that extends `base` with keyboard click behavior.
+ */
+export function KeyboardClick<T extends Constructor<LitElement>>(base: T, allowEnter: boolean = true): T {
+  abstract class _KeyboardClickMixin extends base {
+    readonly #keyUpHandler = (e: KeyboardEvent) => this.#handleKeyUp(e);
+
+    override connectedCallback(): void {
+      super.connectedCallback();
+      this.addEventListener("keyup", this.#keyUpHandler);
+    }
+
+    override disconnectedCallback(): void {
+      super.disconnectedCallback();
+      this.removeEventListener("keyup", this.#keyUpHandler);
+    }
+
+    #handleKeyUp(e: KeyboardEvent): void {
+      if ((isDisabledMixin(this) && this.disabled) || (isDisabledInteractiveMixin(this) && this.disabledInteractive)) {
+        return;
+      }
+
+      if (e.key === " " || (allowEnter && e.key === "Enter")) {
+        // NOTE: the dispatched click event will not be trusted since it is synthetic.
+        this.dispatchEvent(
+          new MouseEvent("click", {
+            cancelable: true,
+            bubbles: true,
+            composed: true,
+          })
+        );
+      }
+    }
+  }
+  return _KeyboardClickMixin;
+}

package/src/shared/mixins/Labelled.ts

@@ -0,0 +1,88 @@
+import { LitElement, PropertyValues } from "lit";
+
+import { DesignToken } from "../tokens";
+
+import { AttachInternalsMixin, internals, isAttachInternalsMixin } from "./AttachInternals";
+import { Constructor } from "./Constructor";
+import { isDisabledMixin } from "./Disabled";
+import { isDisabledInteractiveMixin } from "./DisabledInteractive";
+import { isTouchedMixin } from "./Touched";
+import { hasKeys } from "./hasKeys";
+
+/** Defines functionality for a labelled custom element. */
+export interface LabelledMixin extends AttachInternalsMixin {
+  /** The label elements that the element is associated with. */
+  readonly labels: NodeListOf<HTMLLabelElement>;
+}
+
+/**
+ * Determines whether a value is a `LabelledMixin`.
+ * @param {unknown} value The value to test.
+ * @returns A value indicating whether `value` is a `LabelledMixin`.
+ */
+export function isLabelledMixin(value: unknown): value is LabelledMixin {
+  return hasKeys<LabelledMixin>(value, "labels") && isAttachInternalsMixin(value);
+}
+
+const _updateLabels = Symbol("_updateLabels");
+const _eventHandler = Symbol("_eventHandler");
+
+/**
+ * Mixin to augment an element with support for labelling.
+ * @template T The type of the base class.
+ * @param {T} base The base class.
+ * @returns {Constructor<FormAssociatedMixin> & T} A constructor that implements `FormAssociatedMixin`.
+ */
+export function Labelled<T extends Constructor<LitElement & AttachInternalsMixin>>(
+  base: T
+): Constructor<LabelledMixin> & T {
+  abstract class _Labelled extends base implements LabelledMixin {
+    static readonly formAssociated = true;
+
+    private readonly [_eventHandler] = (e: Event) => {
+      if (!e.defaultPrevented) {
+        this[_updateLabels]();
+      }
+    };
+
+    get labels(): NodeListOf<HTMLLabelElement> {
+      return this[internals].labels as NodeListOf<HTMLLabelElement>;
+    }
+
+    override connectedCallback(): void {
+      super.connectedCallback();
+      this.addEventListener("focusout", this[_eventHandler]);
+      this.addEventListener("change", this[_eventHandler]);
+    }
+
+    override disconnectedCallback(): void {
+      super.disconnectedCallback();
+      this.removeEventListener("focusout", this[_eventHandler]);
+      this.removeEventListener("change", this[_eventHandler]);
+    }
+
+    protected override update(changedProperties: PropertyValues): void {
+      super.update(changedProperties);
+      this[_updateLabels]();
+    }
+
+    private [_updateLabels](): void {
+      const focusable = this.hasAttribute("tabindex");
+      const disabled =
+        (isDisabledMixin(this) && this.disabled) || (isDisabledInteractiveMixin(this) && this.disabledInteractive);
+
+      for (const label of this.labels) {
+        label.style.userSelect = focusable ? "none" : "";
+        label.style.cursor = !disabled ? "pointer" : "";
+
+        label.style.color = disabled
+          ? `color-mix(in srgb, ${DesignToken.color.onSurface} 38%, transparent)`
+          : isTouchedMixin(this) && this.touched && this.ariaInvalid
+          ? `${DesignToken.color.error}`
+          : "";
+      }
+    }
+  }
+
+  return _Labelled;
+}

package/src/shared/mixins/LinkButton.ts

@@ -0,0 +1,169 @@
+import { html, LitElement, nothing } from "lit";
+import { property } from "lit/decorators.js";
+import { ifDefined } from "lit/directives/if-defined.js";
+
+import { Constructor } from "./Constructor";
+import { isDisabledInteractiveMixin } from "./DisabledInteractive";
+import { isDisabledMixin } from "./Disabled";
+import { hasKeys } from "./hasKeys";
+
+/** A symbol through which to access a function used to render a pseudo link. */
+export const renderPseudoLink = Symbol("renderPseudoLink");
+
+/** Specifies the possible targets for a link. */
+export type LinkTarget = "_self" | "_blank" | "_parent" | "_top" | (string & {});
+
+/** Defines functionality for an interactive element that functions as a link. */
+export interface LinkButtonMixin {
+  /** The URL to which the link button points. */
+  href: string;
+
+  /** The target of the link button. */
+  target: LinkTarget;
+
+  /** The relationship between the `target` of the link button and the document. */
+  rel: string;
+
+  /**
+   * A value indicating whether the `target` of the link button will be downloaded,
+   * optionally specifying the new name of the file.
+   */
+  download: string | null;
+
+  /** Function used to render a pseudo link. */
+  [renderPseudoLink](): unknown;
+}
+
+/**
+ * Determines whether a value is a `LinkButtonMixin`.
+ * @param {unknown} value The value to test.
+ * @returns {value is LinkButtonMixin} Whether `value` is a `LinkButtonMixin`.
+ */
+export function isLinkButtonMixin(value: unknown): value is LinkButtonMixin {
+  return hasKeys<LinkButtonMixin>(value, "download", "href", "rel", "target");
+}
+
+const _clickHandler = Symbol("_clickHandler");
+
+/**
+ * Mixin to augment an element with behavior that supports functioning as a link.
+ * @template T The type of the base class.
+ * @param {T} base The base class.
+ * @returns {Constructor<LinkButtonMixin>} A constructor that implements `LinkButtonMixin`.
+ */
+export function LinkButton<T extends Constructor<LitElement>>(base: T): Constructor<LinkButtonMixin> & T {
+  abstract class _LinkButtonMixin extends base implements LinkButtonMixin {
+    private [_clickHandler] = async (e: Event) => {
+      if (isDisabledInteractiveMixin(this) && this.disabledInteractive) {
+        e.preventDefault();
+        e.stopPropagation();
+      }
+
+      await new Promise<void>((resolve) => resolve());
+      if (e.defaultPrevented) {
+        return;
+      }
+
+      if (this.href) {
+        e.preventDefault();
+        e.stopImmediatePropagation();
+
+        const link = document.createElement("a");
+        link.href = this.href;
+        link.rel = this.rel;
+        link.target = this.target;
+        if (this.download != null) {
+          link.download = this.download;
+        }
+
+        link.addEventListener("click", async () => {
+          await new Promise<void>((resolve) => resolve());
+          link.remove();
+        });
+
+        document.body.appendChild(link);
+        link.click();
+      }
+    };
+
+    @property() href = "";
+    @property() target: LinkTarget = "";
+    @property() rel = "";
+
+    @property({ reflect: false }) get download(): string | null {
+      return this.getAttribute("download");
+    }
+    set download(value: string | null) {
+      const old = this.download;
+      if (old !== value) {
+        if (value) {
+          this.setAttribute("download", value);
+        } else {
+          this.removeAttribute("download");
+        }
+        this.requestUpdate("download", old);
+      }
+    }
+
+    override connectedCallback(): void {
+      super.connectedCallback();
+      this.addEventListener("click", this[_clickHandler]);
+
+      if (this.hasAttribute("href") && this.role === "button") {
+        this.role = "link";
+      }
+    }
+
+    override disconnectedCallback(): void {
+      super.disconnectedCallback();
+      this.removeEventListener("click", this[_clickHandler]);
+    }
+
+    [renderPseudoLink](): unknown {
+      const disabled = isDisabledMixin(this) && this.disabled;
+      const disabledInteractive = isDisabledInteractiveMixin(this) && this.disabledInteractive;
+
+      return !disabled && !disabledInteractive && this.href
+        ? html`<a
+            href="${this.href}"
+            target="${ifDefined(this.target || undefined)}"
+            rel="${ifDefined(this.rel || undefined)}"
+            download="${ifDefined(this.download || undefined)}"
+            tabindex="-1"
+            aria-hidden="true"
+            @pointerdown="${this.#handleLinkPointerDown}"
+            @focus="${this.#handleLinkFocus}"
+            @blur="${this.#handleLinkBlur}"
+          ></a>`
+        : nothing;
+    }
+
+    #handleLinkPointerDown(e: PointerEvent): void {
+      if (e.button !== 2) {
+        e.preventDefault();
+        e.stopImmediatePropagation();
+
+        this.dispatchEvent(
+          new MouseEvent("click", {
+            bubbles: true,
+            cancelable: true,
+            view: window,
+          })
+        );
+      } else {
+        (e.target as HTMLLinkElement).removeAttribute("aria-hidden");
+      }
+    }
+
+    #handleLinkFocus(e: Event): void {
+      (e.target as HTMLLinkElement).blur();
+      this.focus();
+    }
+
+    #handleLinkBlur(e: Event): void {
+      (e.target as HTMLLinkElement).setAttribute("aria-hidden", "true");
+    }
+  }
+
+  return _LinkButtonMixin;
+}

package/src/shared/mixins/ReadOnly.ts

@@ -0,0 +1,48 @@
+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 read-only state. */
+export interface ReadOnlyMixin {
+  /**
+   * A value indicating whether the element is read-only.
+   * @default false
+   */
+  readOnly: boolean;
+}
+
+/**
+ * Determines whether a value is a `ReadOnlyMixin`.
+ * @param {unknown} value The value to test.
+ * @returns A value indicating whether `value` is a `ReadOnlyMixin`.
+ */
+export function isReadOnlyMixin(value: unknown): value is ReadOnlyMixin {
+  return hasKeys<ReadOnlyMixin>(value, "readOnly");
+}
+
+/**
+ * Mixin to augment an element with behavior that supports a read-only state.
+ * @template T The type of the base class.
+ * @param {T} base The base class.
+ * @param {boolean} reflect A value indicating whether the read-only state is reflected as an attribute. The default value is `true`.
+ * @returns {Constructor<ReadOnlyMixin> & T} A constructor that implements `ReadOnlyMixin`.
+ */
+export function ReadOnly<T extends Constructor<LitElement>>(
+  base: T,
+  reflect: boolean = true
+): Constructor<ReadOnlyMixin> & T {
+  abstract class _ReadOnlyMixin extends base implements ReadOnlyMixin {
+    @property({ attribute: "readonly", type: Boolean, reflect: reflect }) readOnly = false;
+
+    protected override update(changedProperties: PropertyValues<this>): void {
+      super.update(changedProperties);
+
+      if (changedProperties.has("readOnly")) {
+        this.ariaReadOnly = this.readOnly ? "true" : null;
+      }
+    }
+  }
+  return _ReadOnlyMixin;
+}

package/src/shared/mixins/Required.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 required state. */
+export interface RequiredMixin {
+  /**
+   * Whether a value is required for the element.
+   * @default false
+   */
+  required: boolean;
+
+  /** Whether a value is not required for the element. */
+  readonly optional: boolean;
+}
+
+/**
+ * Determines whether a value is a `RequiredMixin`.
+ * @param {unknown} value The value to test.
+ * @returns A value indicating whether `value` is a `RequiredMixin`.
+ */
+export function isRequiredMixin(value: unknown): value is RequiredMixin {
+  return hasKeys<RequiredMixin>(value, "required", "optional");
+}
+
+/**
+ * Mixin to augment an element with behavior that supports a required state.
+ * @template T The type of the base class.
+ * @param {T} base The base class.
+ * @returns {Constructor<RequiredMixin> & T} A constructor that implements `RequiredMixin`.
+ */
+export function Required<T extends Constructor<LitElement>>(base: T): Constructor<RequiredMixin> & T {
+  abstract class _RequiredMixin extends base implements RequiredMixin {
+    @property({ type: Boolean, reflect: true }) required = false;
+
+    get optional() {
+      return !this.required;
+    }
+
+    protected override update(changedProperties: PropertyValues<this>): void {
+      super.update(changedProperties);
+      if (changedProperties.has("required")) {
+        this.ariaRequired = `${this.required}`;
+      }
+    }
+  }
+  return _RequiredMixin;
+}

package/src/shared/mixins/RequiredConstraintValidation.ts

@@ -0,0 +1,45 @@
+import { LitElement } from "lit";
+
+import { Constructor } from "./Constructor";
+import { ConstraintValidationMixin, isConstraintValidationMixin, validate } from "./ConstraintValidation";
+import { isCheckedMixin } from "./Checked";
+import { isRequiredMixin, RequiredMixin } from "./Required";
+
+/** Defines functionality for an element which supports validating a required state. */
+export interface RequiredConstraintValidationMixin extends RequiredMixin, ConstraintValidationMixin {}
+
+/**
+ * Determines whether a value is a `RequiredConstraintValidationMixin`.
+ * @param {unknown} value The value to test.
+ * @returns A value indicating whether `value` is a `RequiredConstraintValidationMixin`.
+ */
+export function isRequiredConstraintValidationMixin(value: unknown): value is RequiredConstraintValidationMixin {
+  return isRequiredMixin(value) && isConstraintValidationMixin(value);
+}
+
+/**
+ * Mixin to augment an element with behavior that supports a required state.
+ * @template T The type of the base class.
+ * @param {T} base The base class.
+ * @returns {Constructor<RequiredConstraintValidationMixin> & T} A constructor that implements `RequiredConstraintValidationMixin`.
+ */
+export function RequiredConstraintValidation<
+  T extends Constructor<LitElement & RequiredMixin & ConstraintValidationMixin>
+>(base: T): Constructor<RequiredConstraintValidationMixin> & T {
+  abstract class _RequiredConstraintValidation extends base implements RequiredConstraintValidationMixin {
+    override [validate](): ValidityStateFlags | undefined {
+      const validity = super[validate]();
+      if (!validity && this.required) {
+        if (isCheckedMixin(this) && !this.checked) {
+          return { valueMissing: true };
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        if (!(<any>this).value) {
+          return { valueMissing: true };
+        }
+      }
+      return validity;
+    }
+  }
+  return _RequiredConstraintValidation;
+}