@graupl/core 1.0.0-beta.19 → 1.0.0-beta.21

package/src/js/disclosure/Disclosure.js

@@ -0,0 +1,1378 @@
+/**
+ * @file
+ * The Disclosure class.
+ */
+
+import {
+  isValidInstance,
+  isValidClassList,
+  isValidType,
+  isValidState,
+  isValidEvent,
+  isTag,
+  isQuerySelector,
+} from "../validate.js";
+import { addClass, removeClass } from "../domHelpers.js";
+import { keyPress, preventEvent } from "../eventHandlers.js";
+import storage from "../storage.js";
+import { TransactionalValue } from "../TransactionalValue.js";
+
+class Disclosure {
+  /**
+   * The DOM elements within the disclosure.
+   *
+   * @protected
+   *
+   * @type {Object<HTMLElement>}
+   *
+   * @property {HTMLElement} controller - The disclosure toggle element.
+   * @property {HTMLElement} disclosure - The disclosure element.
+   * @property {HTMLElement} content    - The disclosure content element.
+   */
+  _dom = {
+    controller: null,
+    disclosure: null,
+    content: null,
+  };
+
+  /**
+   * The DOM elements within the disclosure that cannot be reset or generated by the disclosure itself.
+   *
+   * @protected
+   *
+   * @type {string[]}
+   */
+  _domLock = ["controller", "disclosure"];
+
+  /**
+   * The query selectors used by the disclosure.
+   *
+   * @protected
+   *
+   * @type {Object<string>}
+   *
+   * @property {string} content - The query selector for the disclosure content.
+   */
+  _selectors = {
+    content: "",
+  };
+
+  /**
+   * The classes to apply when the disclosure is in various states.
+   *
+   * @protected
+   *
+   * @type {Object<string, string[]>}
+   *
+   * @property {string|string[]} open       - The class(es) to apply when the disclosure is open.
+   * @property {string|string[]} close      - The class(es) to apply when the disclousre is closed.
+   * @property {string|string[]} tranistion - The class(es) to apply when the disclosure is transitioning between states.
+   * @property {string|string[]} initialize - The class(es) to apply when the disclosure is initializing.
+   */
+  _classes = {
+    open: "show",
+    close: "hide",
+    transition: "transitioning",
+    initialize: "initializing",
+  };
+
+  /**
+   * The duration times (in milliseconds) for various things throughout the disclosure.
+   *
+   * @protected
+   *
+   * @type {Object<number>}
+   *
+   * @property {number} transition - The duration time (in milliseconds) for the transition between open and closed states.
+   * @property {number} open       - The duration time (in milliseconds) for the transition from closed to open states.
+   * @property {number} close      - The duration time (in milliseconds) for the transition from open to closed states.
+   */
+  _durations = {
+    transition: 5000,
+    open: -1,
+    close: -1,
+  };
+
+  /**
+   * The current state of the disclosure's focus.
+   *
+   * @protected
+   *
+   * @type {string}
+   */
+  _focusState = "none";
+
+  /**
+   * This last event triggered on the disclosure.
+   *
+   * @protected
+   *
+   * @type {string}
+   */
+  _currentEvent = "none";
+
+  /**
+   * The open state of the disclosure.
+   *
+   * @protected
+   *
+   * @type {TransactionalValue<boolean>}
+   */
+  _open = new TransactionalValue(false);
+
+  /**
+   * A value to force the disclosure open when the breakpoint width is passed.
+   *
+   * @protected
+   *
+   * @type {boolean}
+   */
+  _shouldOpen = false;
+
+  /**
+   * Whether or not to close the disclosure when it loses focus in the DOM.
+   *
+   * @protected
+   *
+   * @type {boolean}
+   */
+  _closeOnBlur = false;
+
+  /**
+   * The width of the screen (in pixels) that the disclosure will automatically open/close itself.
+   *
+   * @protected
+   *
+   * @type {number}
+   */
+  _breakpointWidth = -1;
+
+  /**
+   * This ResizeObserver for the disclosure.
+   *
+   * @protected
+   *
+   * @type {ResizeObserver|null}
+   */
+  _observer = null;
+
+  /**
+   * The event that is triggered when the disclosure expands.
+   *
+   * @protected
+   *
+   * @event grauplDisclosureExpand
+   *
+   * @type {CustomEvent}
+   *
+   * @property {boolean}            bubbles - A flag to bubble the event.
+   * @property {Object<Disclosure>} details - The details object containing the Disclosure itself.
+   */
+  _expandEvent = new CustomEvent("grauplDisclosureExpand", {
+    bubbles: true,
+    detail: { disclosure: this },
+  });
+
+  /**
+   * The event that is triggered when the disclosure collapses.
+   *
+   * @protected
+   *
+   * @event grauplDisclosureCollapse
+   *
+   * @type {CustomEvent}
+   *
+   * @property {boolean}            bubbles - A flag to bubble the event.
+   * @property {Object<Disclosure>} details - The details object containing the Disclosure itself.
+   */
+  _collapseEvent = new CustomEvent("grauplDisclosureCollapse", {
+    bubbles: true,
+    detail: { disclosure: this },
+  });
+
+  /**
+   * The prefix to use for CSS custom properties.
+   *
+   * @protected
+   *
+   * @type {string}
+   */
+  _prefix = "graupl-";
+
+  /**
+   * An array of error messages generated by the disclosure.
+   *
+   * @protected
+   *
+   * @type {string[]}
+   */
+  _errors = [];
+
+  /**
+   * Constructs a new `Disclosure`.
+   *
+   * @param {object}             options                                                   - The options for generating the disclosure.
+   * @param {HTMLElement}        options.disclosureElement                                 - The disclosure element in the DOM.
+   * @param {HTMLElement}        options.controllerElement                                 - The disclosure toggle element in the DOM.
+   * @param {string}             [options.disclosureContentSelector = .disclosure-content] - The query selector string for the disclosure content.
+   * @param {?(string|string[])} [options.openClass = show]                                - The class to apply when a disclosure is "open".
+   * @param {?(string|string[])} [options.closeClass = hide]                               - The class to apply when a disclosure is "closed".
+   * @param {?(string|string[])} [options.transitionClass = transitioning]                 - The class to apply when a disclosure is transitioning between "open" and "closed" states.
+   * @param {number}             [options.transitionDuration = 250]                        - The duration of the transition between "open" and "closed" states (in milliseconds).
+   * @param {boolean}            [options.openDuration = -1]                               - The duration of the transition from "closed" to "open" states (in milliseconds).
+   * @param {boolean}            [options.closeDuration = -1]                              - The duration of the transition from "open" to "closed" states (in milliseconds).
+   * @param {boolean}            [options.closeOnBlur = false]                             - Whether to close the disclosure when it loses focus in the dom.
+   * @param {boolean}            [options.minWidth = -1]                                   - The width of the screen (in pixels) that the disclosure will automatically open/close itself.
+   * @param {boolean}            [options.autoOpen = false]                                - Whether to automatically open when above the minWidth.
+   * @param {?string}            [options.prefix = graupl-]                                - The prefix to use for CSS custom properties.
+   * @param {?(string|string[])} [options.initializeClass = initializing]                  - The class to apply when a disclosure is initialzing.
+   * @param {boolean}            [options.initialize = false]                              - Whether to initialize the disclosure upon construction.
+   */
+  constructor({
+    disclosureElement,
+    controllerElement,
+    disclosureContentSelector = ".disclosure-content",
+    openClass = "show",
+    closeClass = "hide",
+    transitionClass = "transitioning",
+    transitionDuration = 250,
+    openDuration = -1,
+    closeDuration = -1,
+    closeOnBlur = false,
+    minWidth = -1,
+    autoOpen = false,
+    prefix = "graupl-",
+    initializeClass = "initializing",
+    initialize = false,
+  }) {
+    // Set the DOM elements.
+    this._dom.disclosure = disclosureElement;
+    this._dom.controller = controllerElement;
+
+    // Set the DOM selectors.
+    this._selectors.content = disclosureContentSelector;
+
+    // Set the classes.
+    this._classes.open = openClass || "";
+    this._classes.close = closeClass || "";
+    this._classes.transition = transitionClass || "";
+    this._classes.initialize = initializeClass || "";
+
+    // Set the transition durations.
+    this._durations.transition = transitionDuration;
+    this._durations.open = openDuration;
+    this._durations.close = closeDuration;
+
+    // Set close on blur.
+    this._closeOnBlur = closeOnBlur;
+
+    // Set collapse width and auto open functionality.
+    this._breakpointWidth = minWidth;
+    this._shouldOpen = autoOpen;
+
+    // Set the prefix.
+    this._prefix = prefix;
+
+    if (initialize) {
+      this.initialize();
+    }
+  }
+
+  /**
+   * Initializes the disclosure.
+   */
+  initialize() {
+    try {
+      if (!this._validate()) {
+        throw new Error(
+          `Graupl Disclosure: cannot initialize disclosure. The following errors have been found:\n - ${this.errors.join(
+            "\n - "
+          )}`
+        );
+      }
+
+      addClass(this._classes.initialize, this.dom.disclosure);
+
+      // Set up the DOM.
+      this._generateKey();
+      this._setDOMElements();
+      this._setIds();
+      this._setAriaAttributes();
+
+      // Handle events.
+      this._handleFocus();
+      this._handleClick();
+      this._handleKeydown();
+      this._handleKeyup();
+      this._handleResize();
+
+      // Set the custom props.
+      this._setTransitionDurations();
+
+      // Set up the storage.
+      storage.initializeStorage("disclosures");
+      storage.initializeStorage("disclosures");
+      storage.pushToStorage("disclosures", this.dom.disclosure.id, this);
+
+      if (
+        this.dom.controller.getAttribute("aria-expanded") === "true" ||
+        (this.shouldOpen && window.matchMedia(this.openQuery).matches)
+      ) {
+        this._expand(false, false);
+      } else {
+        this._collapse(false, false);
+      }
+
+      requestAnimationFrame(() => {
+        removeClass(this._classes.initialize, this.dom.disclosure);
+      });
+    } catch (error) {
+      console.error(error);
+    }
+  }
+
+  /**
+   * The DOM elements within the disclosure.
+   *
+   * @readonly
+   *
+   * @type {Object<HTMLElement>}
+   *
+   * @see _dom
+   */
+  get dom() {
+    return this._dom;
+  }
+
+  /**
+   * The query selectors used by the disclosure.
+   *
+   * @readonly
+   *
+   * @type {Object<string>}
+   *
+   * @see _selectors
+   */
+  get selectors() {
+    return this._selectors;
+  }
+
+  /**
+   * The class(es) to apply when the disclosure is open.
+   *
+   * @type {string|string[]}
+   *
+   * @see _classes.open
+   */
+  get openClass() {
+    return this._classes.open;
+  }
+
+  set openClass(value) {
+    isValidClassList({ openClass: value });
+
+    if (this._classes.open !== value) {
+      this._classes.open = value;
+    }
+  }
+
+  /**
+   * The class(es) to apply when the disclosure is closed.
+   *
+   * @type {string|string[]}
+   *
+   * @see _classes.close
+   */
+  get closeClass() {
+    return this._classes.close;
+  }
+
+  set closeClass(value) {
+    isValidClassList({ closeClass: value });
+
+    if (this._classes.close !== value) {
+      this._classes.close = value;
+    }
+  }
+
+  /**
+   * The class(es) to apply when the disclosure is transitioning between open and closed.
+   *
+   * @type {string|string[]}
+   *
+   * @see _classes.transition
+   */
+  get transitionClass() {
+    return this._classes.transition;
+  }
+
+  set transitionClass(value) {
+    isValidClassList({ transitionClass: value });
+
+    if (this._classes.transition !== value) {
+      this._classes.transition = value;
+    }
+  }
+
+  /**
+   * The class(es) to apply to the shelf when the disclosure is initializing.
+   *
+   * @type {string|string[]}
+   *
+   * @see _classes
+   */
+  get initializeClass() {
+    return this._classes.initialize;
+  }
+
+  set initializeClass(value) {
+    isValidClassList({ initializeClass: value });
+
+    if (this._classes.initialize !== value) {
+      this._classes.initialize = value;
+    }
+  }
+
+  /**
+   * The duration time (in milliseconds) for the transition between open and closed states.
+   *
+   * Setting this value will also set the --graupl-transition-duration CSS custom property on the disclosure.
+   *
+   * @type {number}
+   *
+   * @see _durations.transition
+   */
+  get transitionDuration() {
+    return this._durations.transition;
+  }
+
+  set transitionDuration(value) {
+    isValidType("number", { value });
+
+    if (this._durations.transition !== value) {
+      this._durations.transition = value;
+      this._setTransitionDurations();
+    }
+  }
+
+  /**
+   * The duration time (in milliseconds) for the transition from closed to open states.
+   *
+   * If openDuration is set to -1, the transitionDuration value will be used instead.
+   *
+   * Setting this value will also set the --graupl-open-transition-duration CSS custom property on the disclosure.
+   *
+   * @type {number}
+   *
+   * @see _durations.open
+   */
+  get openDuration() {
+    if (this._durations.open === -1) return this.transitionDuration;
+
+    return this._durations.open;
+  }
+
+  set openDuration(value) {
+    isValidType("number", { value });
+
+    if (this._durations.open !== value) {
+      this._durations.open = value;
+      this._setTransitionDurations();
+    }
+  }
+
+  /**
+   * The duration time (in milliseconds) for the transition from open to closed states.
+   *
+   * If closeDuration is set to -1, the transitionDuration value will be used instead.
+   *
+   * Setting this value will also set the --graupl-close-transition-duration CSS custom property on the disclosure.
+   *
+   * @type {number}
+   *
+   * @see _durations.close
+   */
+  get closeDuration() {
+    if (this._durations.close === -1) return this.transitionDuration;
+
+    return this._durations.close;
+  }
+
+  set closeDuration(value) {
+    isValidType("number", { value });
+
+    if (this._durations.close !== value) {
+      this._durations.close = value;
+      this._setTransitionDurations();
+    }
+  }
+
+  /**
+   * The width of the screen (in pixels) that the disclosure will automatically open/close itself.
+   *
+   * @type {number}
+   *
+   * @see _breakpointWidth
+   */
+  get minWidth() {
+    return this._breakpointWidth;
+  }
+
+  set minWidth(value) {
+    isValidType("number", { value });
+
+    if (this._breakpointWidth !== value) {
+      this._breakpointWidth = value;
+    }
+  }
+
+  /**
+   * Whether to close the disclosure when it loses focus in the DOM.
+   *
+   * @type {boolean}
+   *
+   * @see _closeOnBlur
+   */
+  get closeOnBlur() {
+    return this._closeOnBlur;
+  }
+
+  set closeOnBlur(value) {
+    isValidType("boolean", { value });
+
+    if (this._closeOnBlur !== value) {
+      this._closeOnBlur = value;
+    }
+  }
+
+  /**
+   * The current state of the disclosure's focus.
+   *
+   * @type {string}
+   *
+   * @see _focusState
+   */
+  get focusState() {
+    return this._focusState;
+  }
+
+  set focusState(value) {
+    isValidState({ value });
+
+    if (this._focusState !== value) {
+      this._focusState = value;
+    }
+  }
+
+  /**
+   * The last event triggered on the disclosure.
+   *
+   * @type {string}
+   *
+   * @see _currentEvent
+   */
+  get currentEvent() {
+    return this._currentEvent;
+  }
+
+  set currentEvent(value) {
+    isValidEvent({ value });
+
+    if (this._currentEvent !== value) {
+      this._currentEvent = value;
+    }
+  }
+
+  /**
+   * The prefix to use for CSS custom properties.
+   *
+   * @type {string}
+   *
+   * @see _prefix
+   */
+  get prefix() {
+    return this._prefix;
+  }
+
+  set prefix(value) {
+    isValidType("string", { value });
+
+    if (this._prefix !== value) {
+      this._prefix = value;
+      this._setTransitionDurations();
+    }
+  }
+
+  /**
+   * The open state of the disclosure.
+   *
+   * @readonly
+   *
+   * @type {boolean}
+   *
+   * @see _open
+   */
+  get isOpen() {
+    return this._open.value;
+  }
+
+  /**
+   * The open state of the disclosure that the user specifically triggered.
+   *
+   * @readonly
+   *
+   * @type {boolean}
+   *
+   * @see _open
+   */
+  get hasOpened() {
+    return this._open.committed;
+  }
+
+  /**
+   * A value to force opening reguardless of user interaction.
+   *
+   * @type {boolean}
+   *
+   * @see _shouldOpen
+   */
+  get shouldOpen() {
+    return this._shouldOpen;
+  }
+
+  set shouldOpen(value) {
+    isValidType("boolean", { value });
+
+    if (this._shouldOpen !== value) {
+      this._shouldOpen = value;
+    }
+  }
+
+  /**
+   * A media query for when the disclosure should open.
+   *
+   * Will return an empty string if no min width is set.
+   *
+   * @readonly
+   *
+   * @type {string}
+   */
+  get openQuery() {
+    if (this.minWidth === -1) {
+      return "";
+    }
+
+    return `(width > ${this.minWidth}px)`;
+  }
+
+  /**
+   * A media query for when the disclosure should close.
+   *
+   * Will return an empty string if no min width is set.
+   *
+   * @readonly
+   *
+   * @type {string}
+   */
+  get closeQuery() {
+    if (this.minWidth === -1) {
+      return "";
+    }
+
+    return `(width <= ${this.minWidth}px)`;
+  }
+
+  /**
+   * A flag to check if the disclosure's focus methods should _actually_ move the focus in the DOM.
+   *
+   * This will be `false` unless any of the following criteria are met:
+   * - The disclosure's current event is "keyboard".
+   *
+   * @readonly
+   *
+   * @type {boolean}
+   */
+  get shouldFocus() {
+    let check = false;
+
+    if (this.currentEvent === "keyboard") {
+      check = true;
+    }
+
+    return check;
+  }
+
+  /**
+   * An array of error messages generated by the disclosure.
+   *
+   * @readonly
+   *
+   * @type {string[]}
+   *
+   * @see _errors
+   */
+  get errors() {
+    return this._errors;
+  }
+
+  /**
+   * Validates all aspects on the disclosure to ensure proper functionality.
+   *
+   * @protected
+   *
+   * @return {boolean} - The result of the validation.
+   */
+  _validate() {
+    let check = true;
+
+    // HTML element checks.
+    const htmlElementChecks = isValidInstance(HTMLElement, {
+      disclosureElement: this._dom.disclosure,
+      controllerElement: this._dom.controller,
+    });
+
+    if (!htmlElementChecks.status) {
+      this._errors.push(htmlElementChecks.error.message);
+      check = false;
+    }
+
+    // Query selector checks.
+    const querySelectorChecks = isQuerySelector({
+      disclosureContentSelector: this._selectors.content,
+    });
+
+    if (!querySelectorChecks.status) {
+      this._errors.push(querySelectorChecks.error.message);
+      check = false;
+    }
+
+    // Class list checks.
+    const classes = {};
+
+    for (const className of Object.keys(this._classes)) {
+      if (this._classes[className] === "") {
+        continue;
+      }
+
+      classes[`${className}Class`] = this._classes[className];
+    }
+
+    const classListChecks = isValidClassList(classes);
+
+    if (!classListChecks.status) {
+      this._errors.push(classListChecks.error.message);
+      check = false;
+    }
+
+    // Duration checks.
+    const durations = {};
+
+    for (const durationName of Object.keys(this._durations)) {
+      durations[`${durationName}Duration`] = this._durations[durationName];
+    }
+
+    const durationChecks = isValidType("number", durations);
+
+    if (!durationChecks.status) {
+      this._errors.push(durationChecks.error.message);
+      check = false;
+    }
+
+    // Prefix check.
+    const prefixCheck = isValidType("string", { prefix: this._prefix });
+
+    if (!prefixCheck.status) {
+      this._errors.push(prefixCheck.error.message);
+      check = false;
+    }
+
+    return check;
+  }
+
+  /**
+   * Generates a key for the disclosure.
+   *
+   * @param {boolean} [regenerate = false] - A flag to determine if the key should be regenerated.
+   */
+  _generateKey(regenerate = false) {
+    if (this.key === "" || regenerate) {
+      this.key = Math.random()
+        .toString(36)
+        .replace(/[^a-z]+/g, "")
+        .substring(0, 10);
+    }
+  }
+
+  /**
+   * Sets the IDs of the disclosure and it's controller if they do not already exist.
+   *
+   * The generated IDs use the key and follow the format:
+   *  - disclosure: `disclosure-${key}`
+   *  - controller: `disclosure-controller-${key}`
+   *
+   * @protected
+   */
+  _setIds() {
+    this.dom.disclosure.id = this.dom.disclosure.id || `disclosure-${this.key}`;
+    this.dom.controller.id =
+      this.dom.controller.id || `disclosure-controller-${this.key}`;
+  }
+
+  /**
+   * Sets the ARIA attributes on the disclosure and its controller.
+   *
+   * The first steps are to ensure that the controlled has `aria-expanded` set to "false"
+   * if it's not already explicity set to "true".
+   *
+   * Then, set the `aria-controls` attribute on the controller to the disclosure's ID.
+   *
+   * Finally, ensure the controller element has a role of "button" if it is not a native button element.
+   *
+   * @protected
+   */
+  _setAriaAttributes() {
+    // If the controller element doesn't have aria-expanded set to true, set it to false.
+    if (this.dom.controller.getAttribute("aria-expanded") !== "true") {
+      this.dom.controller.setAttribute("aria-expanded", "false");
+    }
+
+    // Set the aria-controls attribute on the controller to the disclosure's ID.
+    this.dom.controller.setAttribute("aria-controls", this.dom.disclosure.id);
+
+    // If the controller element is not a button, set its role to button.
+    if (!isTag("button", { controller: this.dom.controller })) {
+      this.dom.controller.setAttribute("role", "button");
+    }
+  }
+
+  /**
+   * Sets the transition durations of the disclosure as a CSS custom properties.
+   *
+   * The custom properties are:
+   *   - `--graupl-disclosure-transition-duration`,
+   *   - `--graupl-disclosure-open-transition-duration`, and
+   *   - `--graupl-disclosure-close-transition-duration`.
+   *
+   * The prefix of `graupl-` can be changed by setting the disclosure's prefix value.
+   *
+   * @protected
+   */
+  _setTransitionDurations() {
+    this.dom.disclosure.style.setProperty(
+      `--${this.prefix}disclosure-transition-duration`,
+      `${this.transitionDuration}ms`
+    );
+
+    this.dom.disclosure.style.setProperty(
+      `--${this.prefix}disclosure-open-transition-duration`,
+      `${this.openDuration}ms`
+    );
+
+    this.dom.disclosure.style.setProperty(
+      `--${this.prefix}disclosure-close-transition-duration`,
+      `${this.closeDuration}ms`
+    );
+  }
+
+  /**
+   * Sets DOM elements.
+   *
+   * Elements listed in _domLock cannot be set using this method.
+   *
+   * @protected
+   *
+   * @param {string}                      elementType                          - The type of element to populate.
+   * @param {Object<HTMLElement,boolean>} [options = {}]                       - The options for setting the DOM element type.
+   * @param {HTMLElement}                 [options.base = this.dom.disclosure] - The element used as the base for the querySelector.
+   * @param {boolean}                     [options.overwrite = true]           - A flag to set if the existing elements will be overwritten.
+   * @param {boolean}                     [options.strict = true]              - A flag to set if the elements must be direct children of the base.
+   */
+  _setDOMElementType(
+    elementType,
+    { base = this.dom.disclosure, overwrite = true, strict = true } = {}
+  ) {
+    if (typeof this.selectors[elementType] === "string") {
+      if (this._domLock.includes(elementType)) {
+        throw new Error(
+          `Graupl ${this.constructor.name}: "${elementType}" element cannot be set through _setDOMElementType.`
+        );
+      }
+
+      if (base !== this.dom.disclosure) isValidInstance(HTMLElement, { base });
+
+      // Get the all elements matching the selector in the base.
+      const domElements = Array.from(
+        base.querySelectorAll(this.selectors[elementType])
+      );
+
+      // Filter the elements so only direct children of the base are kept.
+      const filteredElements = domElements.filter((item) =>
+        strict ? item.parentElement === base : true
+      );
+
+      if (overwrite) {
+        if (Array.isArray(this._dom[elementType])) {
+          this._dom[elementType] = filteredElements;
+        } else {
+          this._dom[elementType] = filteredElements[0] || null;
+        }
+      } else {
+        if (Array.isArray(this._dom[elementType])) {
+          this._dom[elementType] = [
+            ...this._dom[elementType],
+            ...filteredElements,
+          ];
+        } else {
+          this._dom[elementType] = filteredElements[0] || null;
+        }
+      }
+    } else {
+      throw new Error(
+        `Graupl ${this.constructor.name}: "${elementType}" is not a valid element type.`
+      );
+    }
+  }
+
+  /**
+   * Resets DOM elements.
+   *
+   * Elements listed in _domLock cannot be reset using this method.
+   *
+   * @protected
+   *
+   * @param {string} elementType - The type of element to clear.
+   */
+  _resetDOMElementType(elementType) {
+    if (typeof this.selectors[elementType] === "string") {
+      if (this._domLock.includes(elementType)) {
+        throw new Error(
+          `Graupl ${this.constructor.name}: "${elementType}" element cannot be reset through _resetDOMElementType.`
+        );
+      }
+
+      if (Array.isArray(this._dom[elementType])) {
+        this._dom[elementType] = [];
+      } else {
+        this._dom[elementType] = null;
+      }
+    } else {
+      throw new Error(
+        `Graupl ${this.constructor.name}: "${elementType}" is not a valid element type.`
+      );
+    }
+  }
+
+  /**
+   * Sets all DOM elements within the disclosure.
+   *
+   * Utilizes _setDOMElementType and
+   * _resetDOMElementType.
+   *
+   * @protected
+   */
+  _setDOMElements() {
+    this._resetDOMElementType("content");
+    this._setDOMElementType("content");
+  }
+
+  /**
+   * Expands the disclosure.
+   *
+   * Sets the controller's `aria-expanded` to "true", adds the
+   * open class to the disclosure, and removes the closed class from the disclosure.
+   *
+   * @protected
+   *
+   * @fires grauplDisclosureExpand
+   *
+   * @param {boolean} [emit = true]       - Emit the expand event once expanded.
+   * @param {boolean} [transition = true] - Respect the transition class.
+   */
+  _expand(emit = true, transition = true) {
+    this.dom.controller.setAttribute("aria-expanded", "true");
+
+    // If we're dealing with transition classes, then we need to utilize
+    // requestAnimationFrame to add the transition class, remove the close class,
+    // add the open class, and finally remove the transition class.
+    if (transition && this.transitionlass !== "") {
+      // this.dom.disclosure.style.height = `${this.dom.disclosure.getBoundingClientRect().height}px`;
+      // console.log(this.dom.disclosure.style.height);
+      addClass(this.transitionClass, this.dom.disclosure);
+
+      requestAnimationFrame(() => {
+        removeClass(this.closeClass, this.dom.disclosure);
+
+        // this.dom.disclosure.style.height = `${this.dom.disclosure.getBoundingClientRect().height}px`;
+        // console.log(this.dom.disclosure.style.height);
+
+        requestAnimationFrame(() => {
+          addClass(this.openClass, this.dom.disclosure);
+
+          // this.dom.disclosure.style.height = `${this.dom.content.getBoundingClientRect().height}px`;
+          // console.log(this.dom.disclosure.style.height);
+
+          requestAnimationFrame(() => {
+            setTimeout(() => {
+              removeClass(this.transitionClass, this.dom.disclosure);
+
+              // this.dom.disclosure.style.height = "";
+              // console.log(this.dom.disclosure.style.height);
+            }, this.openDuration);
+          });
+        });
+      });
+    } else {
+      // Add the open class
+      addClass(this.openClass, this.dom.disclosure);
+
+      // Remove the close class.
+      removeClass(this.closeClass, this.dom.disclosure);
+    }
+
+    this.dom.content.removeAttribute("inert");
+
+    if (emit) {
+      this.dom.controller.dispatchEvent(this._expandEvent);
+    }
+  }
+
+  /**
+   * Collapses the disclosure.
+   *
+   * Sets the controller's `aria-expanded` to "false", adds the
+   * close class to the disclosure, and removes the open class from the disclosure.
+   *
+   * @protected
+   *
+   * @fires grauplDisclosureCollapse
+   *
+   * @param {boolean} [emit = true]       - Emit the collapse event once collapsed.
+   * @param {boolean} [transition = true] - Respect the transition class.
+   */
+  _collapse(emit = true, transition = true) {
+    this.dom.controller.setAttribute("aria-expanded", "false");
+
+    // If we're dealing with transition classes, then we need to utilize
+    // requestAnimationFrame to add the transition class, remove the open class,
+    // add the close class, and finally remove the transition class.
+    if (transition && this.transitionClass !== "") {
+      // this.dom.disclosure.style.height = `${this.dom.content.getBoundingClientRect().height}px`;
+      // console.log(this.dom.disclosure.style.height);
+
+      addClass(this.transitionClass, this.dom.disclosure);
+
+      requestAnimationFrame(() => {
+        removeClass(this.openClass, this.dom.disclosure);
+
+        // this.dom.disclosure.style.height = `${this.dom.content.getBoundingClientRect().height}px`;
+        // console.log(this.dom.disclosure.style.height);
+
+        requestAnimationFrame(() => {
+          addClass(this.closeClass, this.dom.disclosure);
+
+          // this.dom.disclosure.style.height = `${this.dom.disclosure.getBoundingClientRect().height}px`;
+          // console.log(this.dom.disclosure.style.height);
+
+          requestAnimationFrame(() => {
+            setTimeout(() => {
+              removeClass(this.transitionClass, this.dom.disclosure);
+
+              this.dom.content.innert = true;
+
+              // this.dom.disclosure.style.height = "";
+              // console.log(this.dom.disclosure.style.height);
+            }, this.closeDuration);
+          });
+        });
+      });
+    } else {
+      // Add the close class
+      addClass(this.closeClass, this.dom.disclosure);
+
+      // Remove the open class.
+      removeClass(this.openClass, this.dom.disclosure);
+    }
+
+    this.dom.content.setAttribute("inert", "true");
+
+    if (emit) {
+      this.dom.controller.dispatchEvent(this._collapseEvent);
+    }
+  }
+
+  _handleResize() {
+    if (this._breakpointWidth <= 0) {
+      return;
+    }
+
+    let width = 0;
+
+    this._observer = new ResizeObserver((entries) => {
+      requestAnimationFrame(() => {
+        for (const entry of entries) {
+          const boxSize = Array.isArray(entry.contentBoxSize)
+            ? entry.contentBoxSize[0]
+            : entry.contentBoxSize;
+          const inlineSize =
+            boxSize && typeof boxSize.inlineSize === "number"
+              ? boxSize.inlineSize
+              : entry.contentRect.width;
+
+          if (typeof inlineSize !== "number") continue;
+
+          if (width === inlineSize) continue;
+
+          const belowBreakpoint = inlineSize <= this.minWidth;
+          const aboveBreakpoint = inlineSize > this.minWidth;
+
+          if (belowBreakpoint && this.isOpen) {
+            this.close({ preserveState: true });
+          } else if (
+            aboveBreakpoint &&
+            !this.isOpen &&
+            (this.hasOpened || this.shouldOpen)
+          ) {
+            this.open();
+          }
+
+          width = inlineSize;
+        }
+      });
+    });
+    this._observer.observe(document.body);
+  }
+
+  /**
+   * Handles focus events throughout the disclosure.
+   *
+   * - Adds a `focusout` listener to the disclosure so when the disclosure loses focus it will close.
+   */
+  _handleFocus() {
+    this.dom.disclosure.addEventListener("focusout", (event) => {
+      if (
+        !this.closeOnBlur ||
+        this.currentEvent !== "keyboard" ||
+        event.relatedTarget === null ||
+        this.dom.disclosure.contains(event.relatedTarget) ||
+        this.dom.controller === event.relatedTarget
+      ) {
+        return;
+      }
+
+      this.close();
+    });
+  }
+
+  /**
+   * Handles click events throughout the disclosure.
+   *
+   * - Adds a `pointerup` listener to the controller that toggles the disclosure.
+   * - Adds a `pointerup` listener to the `document` so if the user clicks outside the disclosure it will close.
+   */
+  _handleClick() {
+    this.dom.controller.addEventListener("pointerup", (event) => {
+      this.currentEvent = "mouse";
+
+      if (event.button !== 0) return;
+
+      preventEvent(event);
+      this.toggle();
+    });
+
+    document.addEventListener("pointerup", (event) => {
+      if (this.focusState !== "self" || !this.closeOnBlur) return;
+
+      this.currentEvent = "mouse";
+
+      if (
+        !this.dom.disclosure.contains(event.target) &&
+        this.dom.controller !== event.target
+      ) {
+        this.close();
+      }
+    });
+  }
+
+  /**
+   * Handles keydown events throughout the disclosure.
+   *
+   * This method exists to assist the _handleKeyup method.
+   *
+   * - Adds a `keydown` listener to the controller.
+   *   - Blocks propagation on "Space" and "Enter" keys.
+   * - Adds a `keydown` listener to the disclosure.
+   *   - Blocks propagation on "Escape" keys.
+   */
+  _handleKeydown() {
+    this.dom.controller.addEventListener("keydown", (event) => {
+      this.currentEvent = "keyboard";
+
+      const key = keyPress(event);
+
+      switch (key) {
+        case "Space":
+        case "Enter":
+          preventEvent(event);
+
+          break;
+      }
+    });
+
+    this.dom.disclosure.addEventListener("keydown", (event) => {
+      this.currentEvent = "keyboard";
+
+      const key = keyPress(event);
+
+      switch (key) {
+        case "Escape":
+          preventEvent(event);
+
+          break;
+      }
+    });
+  }
+
+  /**
+   * Handles keyup events throughout the disclosure.
+   *
+   * - Adds a `keyup` listener to the controller.
+   *   - Toggles the disclosure on "Space" and "Enter" keys.
+   * - Adds a `keyup` listener to the disclosure.
+   *   - Closes the disclosure on "Escape" keys.
+   */
+  _handleKeyup() {
+    this.dom.controller.addEventListener("keyup", (event) => {
+      this.currentEvent = "keyboard";
+
+      const key = keyPress(event);
+
+      switch (key) {
+        case "Space":
+        case "Enter":
+          this.toggle();
+
+          preventEvent(event);
+
+          break;
+      }
+    });
+
+    this.dom.disclosure.addEventListener("keyup", (event) => {
+      this.currentEvent = "keyboard";
+
+      const key = keyPress(event);
+
+      switch (key) {
+        case "Escape":
+          this.close();
+
+          preventEvent(event);
+
+          break;
+      }
+    });
+  }
+
+  /**
+   * Opens the disclosure.
+   *
+   * Sets the disclosure's focus state to "self", calls expand, and sets isOpen to `true`.
+   *
+   * @public
+   *
+   * @param {Object<boolean>} [options = {}]                  - Options for opening the disclosure.
+   * @param {boolean}         [options.force = false]         - Whether to force the open action.
+   * @param {boolean}         [options.preserveState = false] - Whether to preserve the open state.
+   */
+  open({ force = false, preserveState = false } = {}) {
+    if (this.isOpen && !force) return;
+
+    // Set the focus state.
+    this.focusState = "self";
+
+    // Expand the disclosure.
+    this._expand();
+
+    // Set the open state.
+    this._open.value = true;
+
+    if (!preserveState) {
+      this._open.commit();
+    }
+  }
+
+  /**
+   * Opens the disclosure without entering it.
+   *
+   * Sets the disclosure's focus state to "none", calls expand, and sets isOpen to `true`.
+   *
+   * @public
+   *
+   * @param {Object<boolean>} [options = {}]                  - Options for previewing the disclosure.
+   * @param {boolean}         [options.force = false]         - Whether to force the preview action.
+   * @param {boolean}         [options.preserveState = false] - Whether to preserve the open state.
+   */
+  preview({ force = false, preserveState = false } = {}) {
+    if (this.isOpen && !force) return;
+
+    // Set the focus state.
+    this.focusState = "none";
+
+    // Expand the disclosure.
+    this._expand();
+
+    // Set the open state.
+    this._open.value = true;
+
+    if (!preserveState) {
+      this._open.commit();
+    }
+  }
+
+  /**
+   * Closes the disclosure.
+   *
+   * Sets the disclosure's focus state to "none", calls collapse, and sets isOpen to `false`.
+   *
+   * @public
+   *
+   * @param {Object<boolean>} [options = {}]                  - Options for closing the disclosure.
+   * @param {boolean}         [options.force = false]         - Whether to force the close action.
+   * @param {boolean}         [options.preserveState = false] - Whether to preserve the open state.
+   */
+  close({ force = false, preserveState = false } = {}) {
+    if (!this.isOpen && !force) return;
+
+    // Set the focus state.
+    this.focusState = "none";
+
+    // Collapse the disclosure.
+    this._collapse();
+
+    // Set the open state.
+    this._open.value = false;
+
+    if (!preserveState) {
+      this._open.commit();
+    }
+  }
+
+  /**
+   * Toggles the open state of the disclosure.
+   *
+   * @public
+   *
+   * @param {Object<boolean>} [options = {}]                  - Options for toggling the disclosure.
+   * @param {boolean}         [options.force = false]         - Whether to force the open or close action.
+   * @param {boolean}         [options.preserveState = false] - Whether to preserve the open state.
+   */
+  toggle({ force = false, preserveState = false } = {}) {
+    if (this.isOpen) {
+      this.close({ force, preserveState });
+    } else {
+      this.open({ force, preserveState });
+    }
+  }
+}
+
+export default Disclosure;