@itenthusiasm/custom-elements 0.0.3 → 0.9.0

package/CheckboxGroup/types/solid.d.ts

@@ -0,0 +1,29 @@
+import type { CheckboxGroup } from "../index.js";
+
+declare module "solid-js" {
+  namespace JSX {
+    interface HTMLElementTags {
+      "checkbox-group": CheckboxGroupHTMLAttributes<CheckboxGroup>;
+    }
+
+    interface CheckboxGroupHTMLAttributes<T> extends HTMLAttributes<T> {
+      value?: CheckboxGroup["value"];
+      name?: CheckboxGroup["name"];
+      disabled?: CheckboxGroup["disabled"];
+      required?: CheckboxGroup["required"];
+      min?: CheckboxGroup["min"] | number;
+      max?: CheckboxGroup["max"] | number;
+      manual?: CheckboxGroup["manual"];
+      valuemissingerror?: CheckboxGroup["valueMissingError"];
+      "attr:valuemissingerror"?: CheckboxGroup["valueMissingError"];
+      rangeunderflowerror?: CheckboxGroup["rangeUnderflowError"];
+      "attr:rangeunderflowerror"?: CheckboxGroup["rangeUnderflowError"];
+      rangeoverflowerror?: CheckboxGroup["rangeOverflowError"];
+      "attr:rangeoverflowerror"?: CheckboxGroup["rangeOverflowError"];
+    }
+
+    interface ExplicitBoolAttributes {
+      checked?: boolean;
+    }
+  }
+}

package/CheckboxGroup/types/svelte.d.ts

@@ -0,0 +1,20 @@
+import type { CheckboxGroup } from "../index.js";
+
+declare module "svelte/elements" {
+  interface SvelteHTMLElements {
+    "checkbox-group": HTMLCheckboxGroupAttributes;
+  }
+
+  interface HTMLCheckboxGroupAttributes extends HTMLAttributes<CheckboxGroup> {
+    value?: CheckboxGroup["value"] | null;
+    name?: CheckboxGroup["name"] | null;
+    disabled?: CheckboxGroup["disabled"] | null;
+    required?: CheckboxGroup["required"] | null;
+    min?: CheckboxGroup["min"] | number | null;
+    max?: CheckboxGroup["max"] | number | null;
+    manual?: CheckboxGroup["manual"] | null;
+    valuemissingerror?: CheckboxGroup["valueMissingError"] | null;
+    rangeunderflowerror?: CheckboxGroup["rangeUnderflowError"] | null;
+    rangeoverflowerror?: CheckboxGroup["rangeOverflowError"] | null;
+  }
+}

package/CheckboxGroup/types/vue.d.ts

@@ -0,0 +1,40 @@
+import type { HTMLAttributes, PublicProps, EmitFn } from "vue";
+import type { CheckboxGroup } from "../index.js";
+
+declare module "vue" {
+  // Helper Types
+  type Booleanish = boolean | "true" | "false";
+  type VueEmitMap<T extends GlobalEventHandlersEventMap> = EmitFn<{ [K in keyof T]: (event: T[K]) => void }>;
+  interface VueGlobalHTMLAttributes extends HTMLAttributes, Omit<PublicProps, "class" | "style"> {}
+
+  /* -------------------- Register Elements -------------------- */
+  interface GlobalComponents {
+    "checkbox-group": new () => CheckboxGroupVueSFCType;
+  }
+
+  interface IntrinsicElementAttributes {
+    "checkbox-group": CheckboxGroupHTMLAttributes;
+  }
+
+  /* -------------------- Checkbox Group -------------------- */
+  interface CheckboxGroupHTMLAttributes extends VueGlobalHTMLAttributes {
+    value?: CheckboxGroup["value"];
+    name?: CheckboxGroup["name"];
+    disabled?: CheckboxGroup["disabled"];
+    required?: CheckboxGroup["required"];
+    min?: CheckboxGroup["min"] | number;
+    max?: CheckboxGroup["max"] | number;
+    manual?: CheckboxGroup["manual"];
+    valuemissingerror?: CheckboxGroup["valueMissingError"];
+    rangeunderflowerror?: CheckboxGroup["rangeUnderflowError"];
+    rangeoverflowerror?: CheckboxGroup["rangeOverflowError"];
+  }
+
+  interface CheckboxGroupVueSFCType extends CheckboxGroup {
+    /** @deprecated Only for use by Vue's templating language */
+    $props: CheckboxGroupHTMLAttributes;
+
+    /** @deprecated Only for use by Vue's templating language */
+    $emit: VueEmitMap<HTMLElementEventMap>;
+  }
+}

package/Combobox/Combobox.css

@@ -4,7 +4,7 @@ select-enhancer {
   position: relative;
   display: inline-block;
   box-sizing: border-box;
-  width: inherit;
+  width: min(100%, 200px);
   height: inherit;
 
   @media only screen and (min-width: 600px) {
@@ -26,7 +26,7 @@ select-enhancer {
 
     cursor: pointer;
     white-space: pre;
-    text-align: center;
+    text-align: left;
     font-size: inherit;
     font-family: inherit;
     color: currentcolor;
@@ -64,15 +64,16 @@ select-enhancer {
       }
 
       & > [role="option"],
-      &:where([role="combobox"][data-bad-filter] + [role="listbox"])::after {
+      &:where([role="combobox"][data-bad-filter] + [role="listbox"])::before {
         display: block;
         box-sizing: border-box;
         height: var(--option-height);
         padding: var(--option-padding);
+        align-content: center;
         cursor: pointer;
 
         &[data-active="true"]:not([aria-selected="true"]) {
-          background-color: #bddaff; /* `background-color` for `selected` items, brightened by 70% */
+          background-color: #bddaff; /* This color is the `background-color` for `selected` items, brightened by 70% */
         }
 
         &[aria-selected="true"] {
@@ -85,13 +86,13 @@ select-enhancer {
           visibility: hidden; /* Needed to hide filtered-out `option`s in Safari + VoiceOver (Bug in Browser) */
         }
 
-        /* TODO: Add clearer `disabled` styles. */
+        /* TODO: Add clearer/better `disabled` styles. */
         &[aria-disabled="true"] {
-          cursor: auto;
+          cursor: not-allowed;
         }
       }
 
-      &:where([role="combobox"][data-bad-filter] + [role="listbox"])::after {
+      &:where([role="combobox"][data-bad-filter] + [role="listbox"])::before {
         content: attr(nomatchesmessage, "No options found") / "";
         cursor: auto;
       }

package/Combobox/ComboboxField.d.ts

@@ -1,14 +1,4 @@
 export default ComboboxField;
-export type ExposedInternals = Pick<ElementInternals, "labels" | "form" | "validity" | "validationMessage" | "willValidate" | "checkValidity" | "reportValidity">;
-export type FieldPropertiesAndMethods = Pick<HTMLInputElement, "name" | "required" | "disabled" | "setCustomValidity">;
-/**
- * @typedef {Pick<ElementInternals,
-     "labels" | "form" | "validity" | "validationMessage" | "willValidate" | "checkValidity" | "reportValidity"
-   >} ExposedInternals
- */
-/**
- * @typedef {Pick<HTMLInputElement, "name" | "required" | "disabled" | "setCustomValidity">} FieldPropertiesAndMethods
- */
 /** @implements {ExposedInternals} @implements {FieldPropertiesAndMethods} */
 declare class ComboboxField extends HTMLElement implements ExposedInternals, FieldPropertiesAndMethods {
     /** @returns {true} */
@@ -71,8 +61,8 @@ declare class ComboboxField extends HTMLElement implements ExposedInternals, Fie
      * @returns {void}
      */
     attributeChangedCallback(name: (typeof ComboboxField.observedAttributes)[number], oldValue: string | null, newValue: string | null): void;
-    /** @param {string} v */
-    set value(v: string);
+    /** @param {string} V */
+    set value(V: string);
     /** Sets or retrieves the `value` of the `combobox` @returns {string | null} */
     get value(): string | null;
     /** "On Mount" for Custom Elements @returns {void} */
@@ -157,7 +147,7 @@ declare class ComboboxField extends HTMLElement implements ExposedInternals, Fie
     set filter(value: boolean);
     /** Activates a textbox that can be used to filter the list of `combobox` `option`s. @returns {boolean} */
     get filter(): boolean;
-    set filterMethod(value: Extract<number | typeof Symbol.iterator | "normalize" | "link" | "search" | "small" | "sub" | "sup" | "length" | "toString" | "concat" | "slice" | "indexOf" | "lastIndexOf" | "includes" | "at" | "charAt" | "charCodeAt" | "localeCompare" | "match" | "replace" | "split" | "substring" | "toLowerCase" | "toLocaleLowerCase" | "toUpperCase" | "toLocaleUpperCase" | "trim" | "substr" | "valueOf" | "codePointAt" | "endsWith" | "repeat" | "startsWith" | "anchor" | "big" | "blink" | "bold" | "fixed" | "fontcolor" | "fontsize" | "italics" | "strike" | "padStart" | "padEnd" | "trimEnd" | "trimStart" | "trimLeft" | "trimRight" | "matchAll" | "replaceAll" | "isWellFormed" | "toWellFormed", "startsWith" | "includes">);
+    set filterMethod(value: Extract<number | "normalize" | typeof Symbol.iterator | "length" | "toString" | "concat" | "slice" | "indexOf" | "lastIndexOf" | "includes" | "at" | "link" | "search" | "small" | "sub" | "sup" | "big" | "blink" | "strike" | "charAt" | "charCodeAt" | "localeCompare" | "match" | "replace" | "split" | "substring" | "toLowerCase" | "toLocaleLowerCase" | "toUpperCase" | "toLocaleUpperCase" | "trim" | "substr" | "valueOf" | "codePointAt" | "endsWith" | "repeat" | "startsWith" | "anchor" | "bold" | "fixed" | "fontcolor" | "fontsize" | "italics" | "padStart" | "padEnd" | "trimEnd" | "trimStart" | "trimLeft" | "trimRight" | "matchAll" | "replaceAll" | "isWellFormed" | "toWellFormed", "startsWith" | "includes">);
     /**
      * Determines the method used to filter the `option`s as the user types.
      * - `startsWith`: {@link String.startsWith} will be used to filter the `option`s.
@@ -167,7 +157,7 @@ declare class ComboboxField extends HTMLElement implements ExposedInternals, Fie
      *
      * @returns {Extract<keyof String, "startsWith" | "includes">}
      */
-    get filterMethod(): Extract<number | typeof Symbol.iterator | "normalize" | "link" | "search" | "small" | "sub" | "sup" | "length" | "toString" | "concat" | "slice" | "indexOf" | "lastIndexOf" | "includes" | "at" | "charAt" | "charCodeAt" | "localeCompare" | "match" | "replace" | "split" | "substring" | "toLowerCase" | "toLocaleLowerCase" | "toUpperCase" | "toLocaleUpperCase" | "trim" | "substr" | "valueOf" | "codePointAt" | "endsWith" | "repeat" | "startsWith" | "anchor" | "big" | "blink" | "bold" | "fixed" | "fontcolor" | "fontsize" | "italics" | "strike" | "padStart" | "padEnd" | "trimEnd" | "trimStart" | "trimLeft" | "trimRight" | "matchAll" | "replaceAll" | "isWellFormed" | "toWellFormed", "startsWith" | "includes">;
+    get filterMethod(): Extract<number | "normalize" | typeof Symbol.iterator | "length" | "toString" | "concat" | "slice" | "indexOf" | "lastIndexOf" | "includes" | "at" | "link" | "search" | "small" | "sub" | "sup" | "big" | "blink" | "strike" | "charAt" | "charCodeAt" | "localeCompare" | "match" | "replace" | "split" | "substring" | "toLowerCase" | "toLocaleLowerCase" | "toUpperCase" | "toLocaleUpperCase" | "trim" | "substr" | "valueOf" | "codePointAt" | "endsWith" | "repeat" | "startsWith" | "anchor" | "bold" | "fixed" | "fontcolor" | "fontsize" | "italics" | "padStart" | "padEnd" | "trimEnd" | "trimStart" | "trimLeft" | "trimRight" | "matchAll" | "replaceAll" | "isWellFormed" | "toWellFormed", "startsWith" | "includes">;
     set valueIs(value: "unclearable" | "clearable" | "anyvalue");
     /**
      * Indicates how a `combobox`'s value will behave.
@@ -178,10 +168,7 @@ declare class ComboboxField extends HTMLElement implements ExposedInternals, Fie
      * - `anyvalue`: The field's `value` can be any string, and it will automatically be set to
      * whatever value the user types. (Requires enabling `filter` mode.)
      *
-     * <!--
-     * TODO: Link to Documentation for More Details (like TS does for MDN). The deeper details of the behavior
-     * are too sophisticated to place them all in a JSDoc, which should be [sufficiently] clear and succinct
-     * -->
+     * [API Reference](https://github.com/ITenthusiasm/custom-elements/blob/main/src/Combobox/docs/combobox-field.md#attributes-valueis)
      *
      * @returns {"unclearable" | "clearable" | "anyvalue"}
      */
@@ -196,7 +183,7 @@ declare class ComboboxField extends HTMLElement implements ExposedInternals, Fie
      * Returns the `option` whose `label` matches the user's most recent filter input (if one exists).
      *
      * Value will be `null` if:
-     * - The user's filter didn't match any `option`s
+     * - The user's filter didn't match any (enabled) `option`s
      * - The `combobox`'s text content was altered by a `value` change
      * - The `combobox` was just recently expanded
      * @returns {ComboboxOption | null}
@@ -235,6 +222,8 @@ declare class ComboboxField extends HTMLElement implements ExposedInternals, Fie
     /** @private @type {boolean} */ private [editingKey];
     #private;
 }
+import type { ExposedInternals } from "../types/helpers.js";
+import type { FieldPropertiesAndMethods } from "../types/helpers.js";
 import ComboboxOption from "./ComboboxOption.js";
 import type { ListboxWithChildren } from "./types/helpers.js";
 /** Internally used to retrieve the value that the `combobox` had when it was focused. */

package/Combobox/ComboboxField.js

@@ -1,4 +1,5 @@
 /** @import {ListboxWithChildren} from "./types/helpers.js" */
+/** @import {ExposedInternals, FieldPropertiesAndMethods} from "../types/helpers.js" */
 import { setAttributeFor } from "../utils/dom.js";
 import ComboboxOption from "./ComboboxOption.js";
 import ComboboxListbox from "./ComboboxListbox.js";
@@ -21,20 +22,6 @@ const attrs = Object.freeze({
   "aria-expanded": "aria-expanded",
 });
 
-/** 
- * @typedef {Pick<ElementInternals,
-     "labels" | "form" | "validity" | "validationMessage" | "willValidate" | "checkValidity" | "reportValidity"
-   >} ExposedInternals
- */
-
-/**
- * @typedef {Pick<HTMLInputElement, "name" | "required" | "disabled" | "setCustomValidity">} FieldPropertiesAndMethods
- */
-
-/*
- * TODO: Some of our functionality requires (or recommends) CSS to be properly implemented (e.g., hiding `listbox`,
- * properly showing white spaces, etc.). We should probably explain all such things to developers.
- */
 /** @implements {ExposedInternals} @implements {FieldPropertiesAndMethods} */
 class ComboboxField extends HTMLElement {
   /* ------------------------------ Custom Element Settings ------------------------------ */
@@ -95,7 +82,7 @@ class ComboboxField extends HTMLElement {
    * @returns {void}
    */
   attributeChangedCallback(name, oldValue, newValue) {
-    if (name === "id" && newValue !== oldValue) {
+    if (name === "id" && this.#mounted && newValue !== oldValue) {
       this.listbox.id = `${this.id}-listbox`;
       for (let option = this.listbox.firstElementChild; option; option = /** @type {any} */ (option.nextElementSibling))
         option.id = `${this.id}-option-${option.value}`;
@@ -122,16 +109,19 @@ class ComboboxField extends HTMLElement {
         oldValue === "anyvalue" || oldValue === "unclearable" ? oldValue : "clearable";
       if (trueNewValue === trueOldValue && !filterModeIsBeingDisabled) return;
 
+      const hasOptions = this.listbox.children.length !== 0;
+
       // `anyvalue` activated
       if (trueNewValue === "anyvalue" && !filterModeIsBeingDisabled) {
         if (this.text.data === "") return this.forceEmptyValue();
-        if (this.getAttribute(attrs["aria-expanded"]) !== String(true)) return; // A valid value should already exist
+        if (this.getAttribute(attrs["aria-expanded"]) !== String(true) && hasOptions) return; // A valid value should already exist
 
         if (this.#autoselectableOption) this.value = this.#autoselectableOption.value;
         else this.value = this.text.data;
       }
       // `clearable` activated (default when `filter` mode is ON)
       else if (trueNewValue === "clearable" && !filterModeIsBeingDisabled) {
+        if (!hasOptions && trueOldValue === "anyvalue") return this.#forceNullValue();
         if (this.text.data === "") return this.forceEmptyValue();
         if (trueOldValue !== "anyvalue") return; // A valid value should already exist
 
@@ -140,6 +130,7 @@ class ComboboxField extends HTMLElement {
       }
       // `unclearable` activated (default when `filter` mode is OFF)
       else {
+        if (!hasOptions && (trueOldValue === "anyvalue" || filterModeIsBeingDisabled)) return this.#forceNullValue();
         /** @type {ComboboxOption | null | undefined} */ let option;
 
         if (trueOldValue !== "unclearable" && this.text.data === "") option = this.getOptionByValue("");
@@ -184,6 +175,10 @@ class ComboboxField extends HTMLElement {
         // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- This is due to our own TS Types. :\
         this.#matchingOptions ??= Array.from(this.listbox?.children ?? []);
 
+        if (this.#value === null && this.valueIs === "anyvalue") {
+          this.attributeChangedCallback("valueis", /** @satisfies {this["valueIs"]} */ ("unclearable"), this.valueIs);
+        }
+
         if (this.isConnected) {
           if (/** @type {Document | ShadowRoot} */ (this.getRootNode()).activeElement === this) {
             this.ownerDocument.getSelection()?.setBaseAndExtent(this.text, 0, this.text, this.text.length);
@@ -227,7 +222,11 @@ class ComboboxField extends HTMLElement {
     // Setup Mutation Observers
     this.#optionNodesObserver.observe(this.listbox, { childList: true });
     this.#textNodeObserver.observe(this, { childList: true });
-    this.#expansionObserver.observe(this, { attributes: true, attributeFilter: [attrs["aria-expanded"]] });
+    this.#expansionObserver.observe(this, {
+      attributes: true,
+      attributeFilter: [attrs["aria-expanded"]],
+      attributeOldValue: true,
+    });
     this.#activeDescendantObserver.observe(this, {
       attributes: true,
       attributeFilter: [attrs["aria-activedescendant"]],
@@ -283,7 +282,6 @@ class ComboboxField extends HTMLElement {
   #handleTypeahead = (event) => {
     const combobox = /** @type {ComboboxField} */ (event.currentTarget);
     const { listbox } = combobox;
-    // TODO: This will probably be faster with getElementById?
     const activeOption = listbox.querySelector(":scope [role='option'][data-active='true']");
 
     if (event.key.length === 1 && !event.altKey && !event.ctrlKey && !event.metaKey) {
@@ -373,7 +371,6 @@ class ComboboxField extends HTMLElement {
     if (prevOption?.selected) prevOption.selected = false;
     this.#validateRequiredConstraint();
 
-    // TODO: We might want to document that this `InputEvent` is not cancelable (and why)
     combobox[editingKey] = true;
     combobox.dispatchEvent(
       new InputEvent("input", {
@@ -418,7 +415,7 @@ class ComboboxField extends HTMLElement {
     for (let option = this.listbox.firstElementChild; option; option = /** @type {any} */ (option.nextElementSibling)) {
       if (!this.optionMatchesFilter(option)) option.filteredOut = true;
       else {
-        if (option.textContent === search) autoselectableOption = option;
+        if (option.textContent === search && !option.disabled) autoselectableOption = option;
 
         option.filteredOut = false;
         this.#matchingOptions[matches++] = option;
@@ -462,6 +459,12 @@ class ComboboxField extends HTMLElement {
    * @returns {void}
    */
   #resetOptions() {
+    /*
+     * TODO: If we ever decide to create a public, overridable `getResetOptions()` method, we should consider
+     * using this private internal method to initialize the component's `option`s onMount if no `#matchingOptions`
+     * exist yet. The reason is that doing so will GUARANTEE that the developer's `matchingOption`s will be kept
+     * in sync with ours from the get go.
+     */
     let i = 0;
     for (let option = this.listbox.firstElementChild; option; option = /** @type {any} */ (option.nextElementSibling)) {
       option.filteredOut = false;
@@ -482,8 +485,9 @@ class ComboboxField extends HTMLElement {
     return this.#value;
   }
 
-  /** @param {string} v */
-  set value(v) {
+  /** @param {string} V */
+  set value(V) {
+    const v = typeof V === "string" ? V : String(V);
     const newOption = this.getOptionByValue(v);
     if (v === this.#value && newOption?.selected === true) return;
 
@@ -517,9 +521,8 @@ class ComboboxField extends HTMLElement {
     if (this.valueIs !== "anyvalue" && this.valueIs !== "clearable") {
       throw new TypeError('Method requires `filter` mode to be on and `valueis` to be "anyvalue" or "clearable"');
     }
-    if (this.valueIs === "clearable" && this.#value === null) {
-      throw new TypeError('Cannot coerce value to `""` for a `clearable` `combobox` that owns no `option`s');
-    }
+    // Cannot coerce value to `""` for a `clearable` `combobox` that owns no `option`s
+    if (this.valueIs === "clearable" && this.#value === null) return;
 
     const prevOption = this.#value == null ? null : this.getOptionByValue(this.#value);
 
@@ -531,6 +534,25 @@ class ComboboxField extends HTMLElement {
     this.#validateRequiredConstraint();
   }
 
+  /**
+   * Coerces the `combobox`'s value to `null` and empties its text content.
+   *
+   * **NOTE: This method should only be called when an `(un)clearable` `combobox` is found to have no `option`s during
+   * a non-trivial state transition.**
+   * @returns {void}
+   */
+  #forceNullValue() {
+    // NOTE: This error is only intended to help with internal development. If it causes problems for devs, remove it.
+    if (this.listbox.children.length || this.valueIs === "anyvalue") {
+      throw new TypeError("Method can only be called when an `(un)clearable` `combobox` has no `option`s");
+    }
+
+    this.#value = null;
+    this.#internals.setFormValue(null);
+    this.text.data = "";
+    this.#validateRequiredConstraint();
+  }
+
   /**
    * Retrieves the `option` with the provided `value` (if it exists)
    * @param {string} value
@@ -557,7 +579,7 @@ class ComboboxField extends HTMLElement {
   }
 
   set disabled(value) {
-    this.toggleAttribute("disabled", Boolean(value));
+    this.toggleAttribute("disabled", value);
   }
 
   /** @returns {HTMLInputElement["required"]} */
@@ -566,7 +588,7 @@ class ComboboxField extends HTMLElement {
   }
 
   set required(value) {
-    this.toggleAttribute("required", Boolean(value));
+    this.toggleAttribute("required", value);
   }
 
   /**
@@ -597,7 +619,7 @@ class ComboboxField extends HTMLElement {
   }
 
   set filter(value) {
-    this.toggleAttribute("filter", Boolean(value));
+    this.toggleAttribute("filter", value);
   }
 
   /**
@@ -627,10 +649,7 @@ class ComboboxField extends HTMLElement {
    * - `anyvalue`: The field's `value` can be any string, and it will automatically be set to
    * whatever value the user types. (Requires enabling `filter` mode.)
    *
-   * <!--
-   * TODO: Link to Documentation for More Details (like TS does for MDN). The deeper details of the behavior
-   * are too sophisticated to place them all in a JSDoc, which should be [sufficiently] clear and succinct
-   * -->
+   * [API Reference](https://github.com/ITenthusiasm/custom-elements/blob/main/src/Combobox/docs/combobox-field.md#attributes-valueis)
    *
    * @returns {"unclearable" | "clearable" | "anyvalue"}
    */
@@ -663,7 +682,7 @@ class ComboboxField extends HTMLElement {
    * Returns the `option` whose `label` matches the user's most recent filter input (if one exists).
    *
    * Value will be `null` if:
-   * - The user's filter didn't match any `option`s
+   * - The user's filter didn't match any (enabled) `option`s
    * - The `combobox`'s text content was altered by a `value` change
    * - The `combobox` was just recently expanded
    * @returns {ComboboxOption | null}
@@ -763,7 +782,7 @@ class ComboboxField extends HTMLElement {
     const defaultOption = listbox.querySelector(":scope [role='option']:nth-last-child(1 of [selected])");
 
     if (defaultOption) this.value = defaultOption.value;
-    else if (this.valueIs === "anyvalue" || this.valueIs === "clearable") this.value = "";
+    else if (this.valueIs === "anyvalue" || this.valueIs === "clearable") this.forceEmptyValue();
     else if (listbox.firstElementChild) this.value = listbox.firstElementChild.value;
   }
 
@@ -924,6 +943,19 @@ class ComboboxField extends HTMLElement {
     }
 
     if (event.key === " ") {
+      /*
+       * TODO: Right now, we only support blocking `SpaceBar` and `Enter`. Should we support blocking ALL event keys?
+       * Doing so would require us to allow blocking the `typeahead` functionality as well (to keep things consistent).
+       * (Note: Filtering can already be blocked today because `beforeinput` handlers don't run if the `keydown` event
+       * is prevented.)
+       *
+       * If we decide to support blocking ALL keys, then we'll have to refactor the way we're using `#handleTypeahead`.
+       * More than likely, we'd have to call it inside `#handleKeydown` to make sure that SpaceBar searching doesn't
+       * break when `event.preventDefault()` is called from within the `#handleKeydown` event handler.
+       *
+       * But before we start rearranging method calls, we need to know if devs actually care about this kind of feature.
+       */
+      if (event.defaultPrevented) return;
       if (combobox.filter) return; // Defer to `#handleSearch` instead
       event.preventDefault(); // Don't scroll
 
@@ -936,6 +968,7 @@ class ComboboxField extends HTMLElement {
     }
 
     if (event.key === "Enter") {
+      if (event.defaultPrevented) return;
       // Prevent `#handleSearch` from triggering
       if (combobox.filter) event.preventDefault();
 
@@ -1019,59 +1052,69 @@ class ComboboxField extends HTMLElement {
    * @returns {void}
    */
   #watchExpansion(mutations) {
-    for (let i = 0; i < mutations.length; i++) {
-      const mutation = mutations[i];
-      const combobox = /** @type {ComboboxField} */ (mutation.target);
-      const expanded = combobox.getAttribute(attrs["aria-expanded"]) === String(true);
-
-      // Open Combobox
-      if (expanded) {
-        /*
-         * NOTE: If the user opens the `combobox` with search/typeahead, then `aria-activedescendant` will already
-         * exist and this expansion logic will be irrelevant. Remember that `MutationObserver` callbacks are run
-         * asynchronously, so this check would happen AFTER the search/typeahead handler completed. It's also
-         * possible for this condition to be met if we redundantly set `aria-expanded`. Although we should be
-         * be able to avoid that, we can't prevent Developers from accidentally doing that themselves.
-         */
-        if (combobox.getAttribute(attrs["aria-activedescendant"]) !== "") return;
-
-        /** @type {ComboboxOption | null} */
-        const selectedOption = combobox.value == null ? null : combobox.getOptionByValue(combobox.value);
-        let activeOption = selectedOption ?? combobox.listbox.firstElementChild;
-        if (combobox.filter && activeOption?.filteredOut) [activeOption] = this.#matchingOptions;
-
-        if (combobox.filter) {
-          this.#autoselectableOption = null;
-          this.#activeIndex = activeOption ? this.#matchingOptions.indexOf(activeOption) : -1;
-        }
+    const combobox = /** @type {ComboboxField} */ (mutations[0].target);
+    const ariaExpanded = combobox.getAttribute(attrs["aria-expanded"]);
 
-        if (activeOption) combobox.setAttribute(attrs["aria-activedescendant"], activeOption.id);
-      }
-      // Close Combobox
-      else {
-        combobox.setAttribute(attrs["aria-activedescendant"], "");
-        this.#searchString = "";
+    const oldState = mutations[0].oldValue === String(true) ? "open" : "closed";
+    const newState = ariaExpanded === String(true) ? "open" : "closed";
+    const event = new ToggleEvent("toggle", { newState, oldState });
 
-        // See if logic _exclusive_ to `filter`ed `combobox`es needs to be run
-        if (!combobox.filter || combobox.value == null) return;
-        this.#resetOptions();
-
-        // Reset `combobox` display if needed
-        // NOTE: `option` CAN be `null` or unselected if `combobox` is `clearable`, empty, and `collapsed` with a non-empty filter
-        const textNode = combobox.text;
-        if (!combobox.acceptsValue(textNode.data)) {
-          const option = combobox.getOptionByValue(combobox.value);
-          if (combobox.valueIs === "clearable" && !combobox.value && !option?.selected) textNode.data = "";
-          else if (textNode.data !== option?.textContent) textNode.data = /** @type {string} */ (option?.textContent);
-        }
+    if (newState === oldState) {
+      if (mutations.some((m) => m.oldValue !== ariaExpanded)) combobox.dispatchEvent(event);
+      return;
+    }
+
+    // Open Combobox
+    /* eslint-disable no-labels, no-restricted-syntax */
+    $: if (newState === "open") {
+      /*
+       * NOTE: If the user opens the `combobox` with search/typeahead, then `aria-activedescendant` will already
+       * exist and this expansion logic will be irrelevant. Remember that `MutationObserver` callbacks are run
+       * asynchronously, so this check would happen AFTER the search/typeahead handler completed. It's also
+       * possible for this condition to be met if we redundantly set `aria-expanded`. Although we should be
+       * be able to avoid that, we can't prevent Developers from accidentally doing that themselves.
+       */
+      if (combobox.getAttribute(attrs["aria-activedescendant"]) !== "") break $;
 
-        // Reset cursor if `combobox` is still `:focus`ed
-        if (/** @type {Document | ShadowRoot} */ (combobox.getRootNode()).activeElement !== combobox) return;
+      /** @type {ComboboxOption | null} */
+      const selectedOption = combobox.value == null ? null : combobox.getOptionByValue(combobox.value);
+      let activeOption = selectedOption ?? combobox.listbox.firstElementChild;
+      if (combobox.filter && activeOption?.filteredOut) [activeOption] = this.#matchingOptions;
 
-        const selection = /** @type {Selection} */ (combobox.ownerDocument.getSelection());
-        selection.setBaseAndExtent(textNode, textNode.length, textNode, textNode.length);
+      if (combobox.filter) {
+        this.#autoselectableOption = null;
+        this.#activeIndex = activeOption ? this.#matchingOptions.indexOf(activeOption) : -1;
       }
+
+      if (activeOption) combobox.setAttribute(attrs["aria-activedescendant"], activeOption.id);
     }
+    // Close Combobox
+    else {
+      combobox.setAttribute(attrs["aria-activedescendant"], "");
+      this.#searchString = "";
+
+      // See if logic _exclusive_ to `filter`ed `combobox`es needs to be run
+      if (!combobox.filter || combobox.value == null) break $;
+      this.#resetOptions();
+
+      // Reset `combobox` display if needed
+      // NOTE: `option` CAN be `null` or unselected if `combobox` is `clearable`, empty, and `collapsed` with a non-empty filter
+      const textNode = combobox.text;
+      if (!combobox.acceptsValue(textNode.data)) {
+        const option = combobox.getOptionByValue(combobox.value);
+        if (combobox.valueIs === "clearable" && !combobox.value && !option?.selected) textNode.data = "";
+        else if (textNode.data !== option?.textContent) textNode.data = /** @type {string} */ (option?.textContent);
+      }
+
+      // Reset cursor if `combobox` is still `:focus`ed
+      if (/** @type {Document | ShadowRoot} */ (combobox.getRootNode()).activeElement !== combobox) break $;
+
+      const selection = /** @type {Selection} */ (combobox.ownerDocument.getSelection());
+      selection.setBaseAndExtent(textNode, textNode.length, textNode, textNode.length);
+    }
+    /* eslint-enable no-labels, no-restricted-syntax */
+
+    combobox.dispatchEvent(event);
   }
 
   /**
@@ -1132,12 +1175,7 @@ class ComboboxField extends HTMLElement {
 
     if (!this.listbox.children.length) {
       if (!nullable) this.value = textNode.data;
-      else {
-        this.#value = null;
-        this.#internals.setFormValue(null);
-        textNode.data = "";
-        this.#validateRequiredConstraint();
-      }
+      else this.#forceNullValue();
 
       if (this.filter) this.#filterOptions(); // Clean up internal data and show "No Matches" Message
       return;
@@ -1155,13 +1193,13 @@ class ComboboxField extends HTMLElement {
           if (this.valueIs !== "clearable") this.value = node.value;
           else {
             this.#value = "";
-            this.forceEmptyValue();
+            this.#internals.setFormValue("");
           }
         }
       });
 
       mutation.removedNodes.forEach((node) => {
-        if (!(node instanceof ComboboxOption)) return;
+        if (!(node instanceof ComboboxOption) || this.listbox.contains(node)) return;
         if (this.#autoselectableOption === node) this.#autoselectableOption = null;
         if (node.selected) {
           if (nullable) this.formResetCallback();