@m3e/core 1.0.0-rc.1

package/src/shared/mixins/Role.ts

@@ -0,0 +1,134 @@
+import { LitElement } from "lit";
+
+import { Constructor } from "./Constructor";
+
+/** Specifies valid values for the ARIA `role` attribute. */
+export type ARIARole =
+  | "alert"
+  | "alertdialog"
+  | "button"
+  | "checkbox"
+  | "dialog"
+  | "gridcell"
+  | "link"
+  | "log"
+  | "marquee"
+  | "menuitem"
+  | "menuitemcheckbox"
+  | "menuitemradio"
+  | "option"
+  | "progressbar"
+  | "radio"
+  | "scrollbar"
+  | "searchbox"
+  | "slider"
+  | "spinbutton"
+  | "status"
+  | "switch"
+  | "tab"
+  | "tabpanel"
+  | "textbox"
+  | "timer"
+  | "tooltip"
+  | "treeitem"
+  | "combobox"
+  | "grid"
+  | "listbox"
+  | "menu"
+  | "menubar"
+  | "radiogroup"
+  | "tablist"
+  | "tree"
+  | "treegrid"
+  | "application"
+  | "article"
+  | "cell"
+  | "columnheader"
+  | "definition"
+  | "directory"
+  | "document"
+  | "feed"
+  | "figure"
+  | "group"
+  | "heading"
+  | "img"
+  | "list"
+  | "listitem"
+  | "math"
+  | "none"
+  | "note"
+  | "presentation"
+  | "region"
+  | "row"
+  | "rowgroup"
+  | "rowheader"
+  | "separator"
+  | "table"
+  | "term"
+  | "text"
+  | "toolbar"
+  | "banner"
+  | "complementary"
+  | "contentinfo"
+  | "form"
+  | "main"
+  | "navigation"
+  | "region"
+  | "search"
+  | "doc-abstract"
+  | "doc-acknowledgments"
+  | "doc-afterword"
+  | "doc-appendix"
+  | "doc-backlink"
+  | "doc-biblioentry"
+  | "doc-bibliography"
+  | "doc-biblioref"
+  | "doc-chapter"
+  | "doc-colophon"
+  | "doc-conclusion"
+  | "doc-cover"
+  | "doc-credit"
+  | "doc-credits"
+  | "doc-dedication"
+  | "doc-endnote"
+  | "doc-endnotes"
+  | "doc-epigraph"
+  | "doc-epilogue"
+  | "doc-errata"
+  | "doc-example"
+  | "doc-footnote"
+  | "doc-foreword"
+  | "doc-glossary"
+  | "doc-glossref"
+  | "doc-index"
+  | "doc-introduction"
+  | "doc-noteref"
+  | "doc-notice"
+  | "doc-pagebreak"
+  | "doc-pagelist"
+  | "doc-part"
+  | "doc-preface"
+  | "doc-prologue"
+  | "doc-pullquote"
+  | "doc-qna"
+  | "doc-subtitle"
+  | "doc-tip"
+  | "doc-toc";
+
+/**
+ * Mixin to augment an element with an ARIA role.
+ * @template T The type of the base class.
+ * @param {T} base The base class.
+ * @param {ARIARole} role The ARIA role.
+ * @returns {Constructor & T} A constructor that implements focusable behavior.
+ */
+export function Role<T extends Constructor<LitElement>>(base: T, role: ARIARole): Constructor & T {
+  abstract class _RoleMixin extends base {
+    override connectedCallback(): void {
+      this.role = this.role || role;
+      super.connectedCallback();
+    }
+  }
+
+  return _RoleMixin;
+}

package/src/shared/mixins/Selected.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 selected state. */
+export interface SelectedMixin {
+  /**
+   * Whether the element is selected.
+   * @default false
+   */
+  selected: boolean;
+}
+
+/**
+ * Determines whether a value is a `SelectedMixin`.
+ * @param {unknown} value The value to test.
+ * @returns Whether `value` is a `SelectedMixin`.
+ */
+export function isSelectedMixin(value: unknown): value is SelectedMixin {
+  return hasKeys<SelectedMixin>(value, "selected");
+}
+
+/**
+ * Mixin to augment an element with behavior that supports a selected state.
+ * @template T The type of the base class.
+ * @param {T} base The base class.
+ * @returns {Constructor<SelectedMixin> & T} A constructor that implements `SelectedMixin`.
+ */
+export function Selected<T extends Constructor<LitElement>>(base: T): Constructor<SelectedMixin> & T {
+  abstract class _SelectedMixin extends base implements SelectedMixin {
+    @property({ type: Boolean, reflect: true }) selected = false;
+
+    protected override update(changedProperties: PropertyValues<this>): void {
+      super.update(changedProperties);
+
+      if (changedProperties.has("selected")) {
+        if (this.role === "button") {
+          this.ariaPressed = `${this.selected}`;
+          this.ariaSelected = null;
+        } else if (this.role && this.role !== "none" && this.role !== "presentation") {
+          this.ariaSelected = `${this.selected}`;
+          this.ariaPressed = null;
+        }
+      }
+    }
+  }
+  return _SelectedMixin;
+}

package/src/shared/mixins/Touched.ts

@@ -0,0 +1,71 @@
+import { LitElement } from "lit";
+
+import { Constructor } from "./Constructor";
+import { hasKeys } from "./hasKeys";
+
+/** Defines functionality for an element that can be marked as touched. */
+export interface TouchedMixin {
+  /** Whether the user has interacted when the element. */
+  readonly touched: boolean;
+
+  /** Whether the user has not interacted when the element. */
+  readonly untouched: boolean;
+
+  /** Marks the element as touched. */
+  markAsTouched(): void;
+
+  /** Marks the element as untouched. */
+  markAsUntouched(): void;
+}
+
+/**
+ * Determines whether a value is a `TouchedMixin`.
+ * @param {unknown} value The value to test.
+ * @returns A value indicating whether `value` is a `TouchedMixin`.
+ */
+export function isTouchedMixin(value: unknown): value is TouchedMixin {
+  return hasKeys<TouchedMixin>(value, "touched", "untouched", "markAsTouched", "markAsUntouched");
+}
+
+const _eventHandler = Symbol("_eventHandler");
+
+/**
+ * Mixin to augment an element with functionality used to mark it as touched.
+ * @template T The type of the base class.
+ * @param {T} base The base class.
+ * @returns {Constructor<TouchedMixin> & T} A constructor that implements `TouchedMixin`.
+ */
+export function Touched<T extends Constructor<LitElement>>(base: T): Constructor<TouchedMixin> & T {
+  abstract class _Touched extends base implements TouchedMixin {
+    private [_eventHandler] = () => this.markAsTouched();
+
+    get touched(): boolean {
+      return this.classList.contains("-touched");
+    }
+
+    get untouched(): boolean {
+      return !this.touched;
+    }
+
+    override connectedCallback(): void {
+      this.markAsUntouched();
+      super.connectedCallback();
+      this.addEventListener("focusout", this[_eventHandler]);
+    }
+
+    override disconnectedCallback(): void {
+      super.disconnectedCallback();
+      this.removeEventListener("focusout", this[_eventHandler]);
+    }
+
+    markAsTouched(): void {
+      this.classList.toggle("-touched", true);
+    }
+
+    markAsUntouched(): void {
+      this.classList.toggle("-touched", false);
+    }
+  }
+
+  return _Touched;
+}

package/src/shared/mixins/Vertical.ts

@@ -0,0 +1,44 @@
+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 vertical orientation. */
+export interface VerticalMixin {
+  /**
+   * Whether the element is oriented vertically.
+   * @default false
+   */
+  vertical: boolean;
+}
+
+/**
+ * Determines whether a value is a `VerticalMixin`.
+ * @param {unknown} value The value to test.
+ * @returns A value indicating whether `value` is a `VerticalMixin`.
+ */
+export function isVerticalMixin(value: unknown): value is VerticalMixin {
+  return hasKeys<VerticalMixin>(value, "vertical");
+}
+
+/**
+ * Mixin to augment an element with behavior that supports a vertical orientation.
+ * @template T The type of the base class.
+ * @param {T} base The base class.
+ * @returns {Constructor<VerticalMixin> & T} A constructor that implements `VerticalMixin`.
+ */
+export function Vertical<T extends Constructor<LitElement>>(base: T): Constructor<VerticalMixin> & T {
+  abstract class _VerticalMixin extends base implements VerticalMixin {
+    @property({ type: Boolean, reflect: true }) vertical = false;
+
+    protected override update(changedProperties: PropertyValues<this>): void {
+      super.update(changedProperties);
+
+      if (changedProperties.has("vertical")) {
+        this.ariaOrientation = this.vertical ? "vertical" : "horizontal";
+      }
+    }
+  }
+  return _VerticalMixin;
+}

package/src/shared/mixins/hasKeys.ts

@@ -0,0 +1,10 @@
+/**
+ * Determines whether an object has keys for a given type.
+ * @template T The type to test.
+ * @param {unknown} value The value to test.
+ * @param {...keys: Array<keyof T>} keys The keys of `T` to test.
+ * @returns {boolean} Whether `value` has all `keys`.
+ */
+export function hasKeys<T extends object>(value: unknown, ...keys: Array<keyof T>): boolean {
+  return typeof value === "object" && value !== null && keys.every((x) => x in value);
+}

package/src/shared/mixins/index.ts

@@ -0,0 +1,24 @@
+export * from "./AttachInternals";
+export * from "./Checked";
+export * from "./CheckedIndeterminate";
+export * from "./CheckedOrSelected";
+export * from "./ConstraintValidation";
+export * from "./Dirty";
+export * from "./Disabled";
+export * from "./DisabledInteractive";
+export * from "./EventAttribute";
+export * from "./Focusable";
+export * from "./FormAssociated";
+export * from "./FormSubmitter";
+export * from "./hasKeys";
+export * from "./HtmlFor";
+export * from "./KeyboardClick";
+export * from "./Labelled";
+export * from "./LinkButton";
+export * from "./ReadOnly";
+export * from "./Required";
+export * from "./RequiredConstraintValidation";
+export * from "./Role";
+export * from "./Selected";
+export * from "./Touched";
+export * from "./Vertical";

package/src/shared/primitives/CollapsibleElement.ts

@@ -0,0 +1,227 @@
+/* eslint-disable @typescript-eslint/no-unsafe-declaration-merging */
+
+import { css, CSSResultGroup, html, LitElement, PropertyValues, unsafeCSS } from "lit";
+import { customElement, property } from "lit/decorators.js";
+
+import { EventAttribute, Role } from "../mixins";
+import { DesignToken } from "../tokens";
+import { prefersReducedMotion } from "../utils";
+
+/**
+ * A container used to expand and collapse content.
+ *
+ * @example
+ * ```html
+ * <m3e-collapsible>
+ *  <!-- Collapsible content -->
+ * </m3e-collapsible>
+ * ```
+ *
+ * @tag m3e-collapsible
+ *
+ * @slot - Renders the collapsible content.
+ *
+ * @attr open - Whether content is visible.
+ *
+ * @fires opening - Emitted when the collapsible begins to open.
+ * @fires opened - Emitted when the collapsible has opened.
+ * @fires closing - Emitted when the collapsible begins to close.
+ * @fires closed - Emitted when the collapsible has closed.
+ *
+ * @cssprop --m3e-collapsible-animation-duration - The duration of the expand / collapse animation.
+ */
+@customElement("m3e-collapsible")
+export class M3eCollapsibleElement extends EventAttribute(
+  Role(LitElement, "none"),
+  "opening",
+  "opened",
+  "closing",
+  "closed"
+) {
+  /** The styles of the element. */
+  static override styles: CSSResultGroup = css`
+    :host {
+      display: block;
+      height: 0px;
+      overflow: hidden;
+      transition: ${unsafeCSS(`visibility var(--m3e-collapsible-animation-duration, ${DesignToken.motion.duration.medium1})
+          ${DesignToken.motion.easing.standard},
+        height var(--m3e-collapsible-animation-duration, ${DesignToken.motion.duration.medium1})
+          ${DesignToken.motion.easing.standard},
+        padding-top var(--m3e-collapsible-animation-duration, ${DesignToken.motion.duration.medium1})
+          ${DesignToken.motion.easing.standard},
+        padding-bottom var(--m3e-collapsible-animation-duration, ${DesignToken.motion.duration.medium1})
+          ${DesignToken.motion.easing.standard}`)};
+    }
+    :host(:not(.-closing):not([open])) {
+      visibility: hidden;
+    }
+    :host([open]) {
+      visibility: visible;
+    }
+    :host(:not([open])) {
+      min-height: unset !important;
+      padding-top: 0px !important;
+      padding-bottom: 0px !important;
+    }
+    :host(.-no-animate) {
+      transition-duration: 0ms;
+    }
+    ::slotted(*) {
+      --m3e-collapsible-animation-duration: initial;
+    }
+    @media (prefers-reduced-motion) {
+      :host {
+        transition: none;
+      }
+    }
+  `;
+
+  /** @private */ #slotChanged = false;
+  /** @private */ #hasOpened = false;
+
+  /**
+   * Whether content is visible.
+   * @default false
+   */
+  @property({ type: Boolean, reflect: true }) open = false;
+
+  /** @inheritdoc */
+  protected override update(changedProperties: PropertyValues): void {
+    super.update(changedProperties);
+
+    this.classList.toggle("-no-animate", true);
+
+    if (!this.#slotChanged) {
+      if (this.open) {
+        this.#hasOpened = true;
+        this.#autoSize();
+      }
+      this.#slotChanged = true;
+      return;
+    }
+
+    this.toggleAttribute("inert", !this.open);
+
+    if (this.open) {
+      this.#hasOpened = true;
+      this.classList.toggle("-closing", false);
+      this.classList.toggle("-opening", true);
+      this.dispatchEvent(new Event("opening"));
+
+      this.#clearSize();
+      this.classList.toggle("-no-animate", false);
+      this.#actualSize();
+
+      if (prefersReducedMotion()) {
+        this.classList.toggle("-opening", false);
+        this.dispatchEvent(new Event("opened"));
+      } else {
+        this.addEventListener(
+          "transitionend",
+          () => {
+            if (this.open) {
+              this.#autoSize();
+              this.classList.toggle("-opening", false);
+              this.dispatchEvent(new Event("opened"));
+            }
+          },
+          { once: true }
+        );
+      }
+    } else {
+      this.classList.toggle("-opening", false);
+      this.classList.toggle("-closing", true);
+      this.dispatchEvent(new Event("closing"));
+
+      this.#actualSize();
+      if (this.#hasOpened) {
+        this.classList.toggle("-no-animate", false);
+      }
+
+      if (prefersReducedMotion()) {
+        this.#clearSize();
+        this.classList.toggle("-closing", false);
+        this.dispatchEvent(new Event("closed"));
+      } else {
+        requestAnimationFrame(() => {
+          this.#clearSize();
+          this.addEventListener(
+            "transitionend",
+            () => {
+              if (!this.open) {
+                this.classList.toggle("-closing", false);
+                this.dispatchEvent(new Event("closed"));
+              }
+            },
+            { once: true }
+          );
+        });
+      }
+    }
+  }
+
+  /** @inheritdoc */
+  protected override render(): unknown {
+    return html`<slot @slotchange="${this.#handleSlotChange}"></slot>`;
+  }
+
+  /** @private */
+  #handleSlotChange() {
+    this.#slotChanged = true;
+  }
+
+  /** @private */
+  #autoSize(): void {
+    this.style.height = "auto";
+  }
+
+  /** @private */
+  #clearSize(): void {
+    this.style.height = "";
+  }
+
+  /** @private */
+  #actualSize(): void {
+    this.style.height = `${this.scrollHeight}px`;
+  }
+}
+
+interface M3eCollapsibleElementEventMap extends HTMLElementEventMap {
+  opening: Event;
+  opened: Event;
+  closing: Event;
+  closed: Event;
+}
+
+export interface M3eCollapsibleElement {
+  addEventListener<K extends keyof M3eCollapsibleElementEventMap>(
+    type: K,
+    listener: (this: M3eCollapsibleElement, ev: M3eCollapsibleElementEventMap[K]) => void,
+    options?: boolean | AddEventListenerOptions
+  ): void;
+
+  addEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | AddEventListenerOptions
+  ): void;
+
+  removeEventListener<K extends keyof M3eCollapsibleElementEventMap>(
+    type: K,
+    listener: (this: M3eCollapsibleElement, ev: M3eCollapsibleElementEventMap[K]) => void,
+    options?: boolean | EventListenerOptions
+  ): void;
+
+  removeEventListener(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | EventListenerOptions
+  ): void;
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "m3e-collapsible": M3eCollapsibleElement;
+  }
+}