@itenthusiasm/custom-elements 0.0.2 → 0.7.0

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

@@ -71,8 +71,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} */
@@ -178,10 +178,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 +193,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}

package/Combobox/ComboboxField.js

@@ -31,10 +31,6 @@ const attrs = Object.freeze({
  * @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 +91,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 +118,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 +139,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 +184,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 +231,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 +291,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 +380,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 +424,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 +468,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 +494,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 +530,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 +543,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
@@ -627,10 +658,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 +691,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 +791,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 +952,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 +977,7 @@ class ComboboxField extends HTMLElement {
     }
 
     if (event.key === "Enter") {
+      if (event.defaultPrevented) return;
       // Prevent `#handleSearch` from triggering
       if (combobox.filter) event.preventDefault();
 
@@ -1019,59 +1061,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;
+    }
 
-        // Reset cursor if `combobox` is still `:focus`ed
-        if (/** @type {Document | ShadowRoot} */ (combobox.getRootNode()).activeElement !== combobox) 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 $;
+
+      /** @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 +1184,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 +1202,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();

package/Combobox/README.md

@@ -1,17 +1,268 @@
 # Combobox
 
-A robust, accessible and stylable [`Combobox`](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) [Web Component](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) whose functionality can be extended or customized with ease.
+A group of robust, extendable and stylable [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) which work together to function as an accessible [`combobox`](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).
 
 ## Features and Benefits
 
-- **Framework Agnostic**: Because the `combobox` component is just a custom `HTMLElement`, it works seamlessly in all JS Frameworks (and in pure-JS applications if that's what you fancy).
-- **Integrates with Native Web Forms**: This `combobox` integrates with the web's native `<form>` element, meaning that its value will be seen in the [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) and will be automatically [sent to the server](https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Forms/Sending_and_retrieving_form_data) when the form is submitted -- all without writing a single line of JS.
-- **Works with Various Form Libraries**: The `combobox` component emits standard DOM events like [`input`](https://developer.mozilla.org/en-US/docs/Web/API/Element/input_event) and [`change`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event), enabling it to work naturally with reputable form libraries (e.g., the [`Form Observer`](https://github.com/enthusiastic-js/form-observer), [`Conform`](https://conform.guide/), and [`React Hook Form`](https://react-hook-form.com/)).
-- **Progressive Enhacement**: When used in `Select Enhacing Mode`, the component will fallback to a regular `<select>` element if JS is disabled or unavailable for your users. This means your forms will _always_ be fully usable and accessible.
-- **Highly Customizable**: The `combobox` component is flexible enough to work with whatever CSS you provide, and its functionality can be enhanced or overriden by [extending](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/extends) it.
-- **Performant**: Unlike many other alternatives, the `combobox` component has been cleverly designed to work without complex state management tools or aggressive DOM Tree manipulation. This makes it a fast and memory-efficient solution.
-- **No Dependencies**: The `combobox` component is built on the native web platform instead of extending other frameworks or libraries, guaranteeing your bundle size remains as small as possible.
+- **Framework Agnostic**: Because this component simply uses custom `HTMLElement`s, it works seamlessly in all JS Frameworks (and in pure-JS applications if that's what you fancy).
+- **Integrates with Native Web Forms**: This component [integrates](https://web.dev/articles/more-capable-form-controls) with the web's native `<form>` element, meaning that its value will be seen in the form's [`FormData`](https://developer.mozilla.org/en-US/docs/Web/API/FormData) and will be automatically [sent to the server](https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Forms/Sending_and_retrieving_form_data) when the form is submitted &mdash; all without writing a single line of JS.
+- **Works with Various Form Libraries**: The component emits standard DOM events like [`input`](https://developer.mozilla.org/en-US/docs/Web/API/Element/input_event) and [`change`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event), enabling it to work naturally with reputable form libraries (e.g., the [`Form Observer`](https://github.com/enthusiastic-js/form-observer), [`Conform`](https://conform.guide/), and [`React Hook Form`](https://react-hook-form.com/)).
+- **Progressive Enhacement**: When used in [`Select Enhacing Mode`](#select-enhancing-mode), the component will fallback to a regular `<select>` element if JS is disabled or unavailable for your users. This means your forms will _always_ be fully usable and accessible.
+- **Highly Customizable**: The component is flexible enough to work with whatever CSS you provide, and its functionality can be enhanced or overriden through [class extension](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/extends).
+- **Performant**: Unlike many other alternatives, this component has been cleverly designed to work without complex state management tools or aggressive DOM Tree manipulation. This makes it a fast and memory-efficient solution.
+- **No Dependencies**: The component is built on the native web platform instead of extending other frameworks or libraries, guaranteeing your bundle size remains as small as possible.
 
 <!-- TODO: Link to article explaining how progressively-enhanced Form Controls _greatly_ simplify frontend code. -->
 
+## Install
+
+```
+npm install @itenthusiasm/custom-elements
+```
+
+## Quickstart
+
+```html
+<!-- HTML -->
+<form>
+  <label for="rating">Rating</label>
+  <select-enhancer>
+    <combobox-field id="rating" name="rating"></combobox-field>
+    <combobox-listbox>
+      <combobox-option>1</combobox-option>
+      <combobox-option>2</combobox-option>
+      <combobox-option>3</combobox-option>
+      <combobox-option>4</combobox-option>
+      <combobox-option selected>5</combobox-option>
+    </combobox-listbox>
+  </select-enhancer>
+</form>
+```
+
+```js
+/* JavaScript */
+import { SelectEnhancer, ComboboxField, ComboboxListbox, ComboboxOption } from "@itenthusiasm/custom-elements";
+// or import { SelectEnhancer, ComboboxField, ComboboxListbox, ComboboxOption } from "@itenthusiasm/custom-elements/Combobox";
+
+// NOTE: The order in which these Custom Elements are registered is important
+customElements.define("combobox-listbox", ComboboxListbox);
+customElements.define("combobox-field", ComboboxField);
+customElements.define("combobox-option", ComboboxOption);
+customElements.define("select-enhancer", SelectEnhancer);
+
+// Retrieve some info about the `combobox`
+const form = document.querySelector("form");
+const formData = new FormData(form);
+console.log(formData.get("rating")); // 5
+
+const combobox = document.querySelector("combobox-field");
+console.log(combobox.form === form); // true
+console.log(combobox.value); // 5
+```
+
+To use the component's built-in styles, you can use our `Combobox.css` file. If you're using a bundler like [Vite](https://vite.dev/), you can just import this directly into one of your JS files.
+
+```js
+/* JavaScript */
+import { SelectEnhancer, ComboboxField, ComboboxListbox, ComboboxOption } from "@itenthusiasm/custom-elements";
+import "@itenthusiasm/custom-elements/Combobox/Combobox.css";
+
+// ...
+```
+
+If you prefer to load the CSS in a [`<link>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/link) tag (which tends to be more efficient), you can copy the `Combobox.css` file to your project, modify it to look the way you want, and then load the CSS file the regular way in your HTML.
+
+```html
+<html>
+  <head>
+    <link rel="preload" as="style" href="/path/to/my/copy/of/Combobox.css" />
+    <!-- ... -->
+  </head>
+
+  <!-- ... -->
+</html>
+```
+
+In most cases, the `ComboboxField` custom element shown above behaves like an _enhanced_ drop-in replacement for the native [`HTMLSelectElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLSelectElement). For example, it exposes a `value` property that can be used to get or set the value of the component. The `ComboboxField`'s value will always be synchronized with the state of its `ComboboxOption`s. (This matches the behavior of the native `<select>` element.) For more details on the component's attributes and properties, see the [documentation](https://github.com/ITenthusiasm/custom-elements/tree/main/src/Combobox/docs/combobox-field.md).
+
+### Select Enhancing Mode
+
+The example HTML displayed at the [beginning](#quickstart) of this document showed the `Combobox` component being used in `Manual Setup Mode`. In `Manual Setup Mode`, the Custom Elements which make up the `Combobox` component are rendered directly to the DOM. This is recommended for SPAs.
+
+If your application is server-rendered and you would like the component to be [progressively enhanced](https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement), you can use it in `Select Enhancing Mode` instead. This mode is engaged by wrapping a regular [`<select>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/select) element with the `<select-enhancer>`:
+
+```html
+<!-- HTML -->
+<select-enhancer>
+  <select id="rank" name="rank" filter>
+    <option value="1">First</option>
+    <option value="2">Second</option>
+    <option value="3">Third</option>
+    <option value="4">Fourth</option>
+    <option value="5" selected>Fifth</option>
+  </select>
+</select-enhancer>
+```
+
+In this case, the `<select-enhancer>` will swap the `<select>` and `<option>` elements with the appropriate `<combobox-field>`, `<combobox-listbox>`, and `<combobox-option>` elements when the page loads, copying over all relevant attributes, values, and form states in the process.
+
+```html
+<!-- HTML -->
+<select-enhancer>
+  <combobox-field id="rank" name="rank" filter></combobox-field>
+  <combobox-listbox>
+    <combobox-option value="1">First</combobox-option>
+    <combobox-option value="2">Second</combobox-option>
+    <combobox-option value="3">Third</combobox-option>
+    <combobox-option value="4">Fourth</combobox-option>
+    <combobox-option value="5" selected>Fifth</combobox-option>
+  </combobox-listbox>
+</select-enhancer>
+```
+
+> If the elements are created _outside_ of the DOM, then the `<select-enhancer>` will perform this action when the elements are first mounted to the DOM instead.
+
+`Select Enhancing Mode` is great for situations where you want your form to remain usable for people who have JS Disabled (or who fail to download it for any other reason).
+
+Note that because `Select Enhancing Mode` manipulates the DOM to provide progressive enhancement, you should be careful when using this mode in JS Frameworks that expect to have _full_ control over the DOM. In general, if your list of `option`s is static, then `Select Enhancing Mode` should be safe to use regardless of which JS Framework you're using. However, if your `option`s are _dynamic_, then you should consider rendering a regular `<select>` element on initial render, then a `Manual Setup Mode` Combobox component after initial render. Examples of this can be found in the [documentation](https://github.com/ITenthusiasm/custom-elements/tree/main/src/Combobox/docs/guides/select-enhancement-in-js-frameworks.md).
+
+## Tips
+
+Below are some quick tips for using the `Combobox` component. If you want to dive deeper into the component's features, we've laid out all the details of the component's attributes, properties, methods, and more in our [documentation](https://github.com/ITenthusiasm/custom-elements/tree/main/src/Combobox/docs). We've also provided a demo of the component on [`StackBlitz`](https://stackblitz.com/edit/custom-elements-combobox?file=index.html,src%2Fmain.ts).
+
+### Filter Mode
+
+You can use the [`filter`](https://github.com/ITenthusiasm/custom-elements/tree/main/src/Combobox/docs/combobox-field.md#attributes-filter) attribute to enable users to filter the available list of options in a searchbox.
+
+```html
+<!-- Manual Setup Mode -->
+<select-enhancer>
+  <combobox-field filter></combobox-field>
+  <combobox-listbox>
+    <combobox-option value="1">One</combobox-option>
+    <combobox-option value="2">Two</combobox-option>
+    <combobox-option value="3">Three</combobox-option>
+  </combobox-listbox>
+</select-enhancer>
+
+<!-- Select Enhancing Mode -->
+<select-enhancer>
+  <select filter>
+    <option value="1">One</option>
+    <option value="2">Two</option>
+    <option value="3">Three</option>
+  </select>
+</select-enhancer>
+```
+
+Remember that in `Select Enhancing Mode`, all attributes/states will be copied from the `<select>`/`<option>` elements to the `<combobox-field>`/`<combobox-option>` elements on mount / page load.
+
+### Configuring the Allowed Values
+
+When the `combobox` is in `filter` mode, its allowed values can be configured with the [`valueis`](https://github.com/ITenthusiasm/custom-elements/tree/main/src/Combobox/docs/combobox-field.md#attributes-valueis) attribute. (This attribute does nothing if the component is not in `filter` mode.) There are 3 allowed values:
+
+<dl>
+  <dt><code>unclearable</code></dt>
+  <dd>
+    The <code>Combobox</code> component can only be given a value that matches one of its <code>option</code>s. If the user starts filtering the <code>option</code>s and leaves the <code>combobox</code> without selecting an <code>option</code>, then the searchbox text will be reset to the label of the currently-selected <code>option</code>.
+  </dd>
+  <dt><code>clearable</code> (Default)</dt>
+  <dd>
+    Same as <code>unclearable</code>, except that the component's value can be cleared. This can happen if the user empties the searchbox, or if the developer sets the <a href="https://github.com/ITenthusiasm/custom-elements/tree/main/src/Combobox/docs/combobox-field.md#properties-value"><code>ComboboxField.value</code></a> property to an empty string. When the component's value is cleared, the previously-selected <code>option</code> will be deselected (if one exists).
+  </dd>
+  <dt><code>anyvalue</code></dt>
+  <dd>
+    The <code>Combobox</code> component accepts any value, even if there is no matching <code>option</code>. If the user types into the <code>combobox</code> and leaves it without selecting an <code>option</code>, then searchbox text will be left alone, and the component will adopt the value of the search text. The component's value can also be set programmatically to any string.
+  </dd>
+</dl>
+
+```html
+<!-- Manual Setup Mode -->
+<select-enhancer>
+  <combobox-field filter valueis="anyvalue"></combobox-field>
+  <combobox-listbox>
+    <combobox-option value="1">One</combobox-option>
+    <combobox-option value="2">Two</combobox-option>
+    <combobox-option value="3">Three</combobox-option>
+  </combobox-listbox>
+</select-enhancer>
+
+<!-- Select Enhancing Mode -->
+<select-enhancer>
+  <select filter valueis="anyvalue">
+    <option value="1">One</option>
+    <option value="2">Two</option>
+    <option value="3">Three</option>
+  </select>
+</select-enhancer>
+```
+
+Remember that in `Select Enhancing Mode`, all attributes/states will be copied from the `<select>`/`<option>` elements to the `<combobox-field>`/`<combobox-option>` elements on mount / page load.
+
+### TS Usage in Other Frameworks
+
+Many JS frameworks, such as Svelte and React, often define their own "Element Namespaces". Because of this, most frameworks are not able (on their own) to recognize the correct attributes, properties, and event listeners that belong to the Custom Elements which you use. Thankfully, our library ships with TypeScript types that tell the various JS Frameworks about the existence and shape of our Custom Elements. (This also includes types for _enhanced_ elements like the enhanced `<select>` element.) To define _all_ of our library's Custom Elements within a Framework's "Element Namespace", simply import the appropriate type definition file:
+
+```ts
+import type {} from "@itenthusiasm/custom-elements/types/react";
+// For Svelte: import type {} from "@itenthusiasm/custom-elements/types/svelte";
+// For Vue: import type {} from "@itenthusiasm/custom-elements/types/vue";
+// etc. ...
+```
+
+If you only intend to use _some_ of the Custom Elements provided by this library, then you should only import the types for those components.
+
+```ts
+// Define ONLY the `Combobox` component's types in the framework's "Element Namespace"
+import type {} from "@itenthusiasm/custom-elements/Combobox/types/react";
+// For Svelte: import type {} from "@itenthusiasm/custom-elements/Combobox/types/svelte";
+// For Vue: import type {} from "@itenthusiasm/custom-elements/Combobox/types/vue";
+// etc. ...
+```
+
+### Restyling the Component
+
+For simplicity, the `Combobox` component ships with its own default styles via the `@itenthusiasm/custom-elements/Combobox/Combobox.css` file. You're welcome to use this file directly in your application if you like. However, if you intend to modify _any_ of the styles to fit your own needs, then we recommend creating your own CSS file for the component instead, using our styles as an initial template.
+
+There are some minor nuances that come with restyling the component. You can read about them in our [documentation](https://github.com/ITenthusiasm/custom-elements/tree/main/src/Combobox/docs/guides/styling-the-combobox.md).
+
+### Adding Icons / Buttons
+
+Oftentimes, people prefer to add items like caret icons to their `combobox`es. The `Combobox` component allows you to do this by simply appending or prepending elements within the `<select-enhancer>`:
+
+```html
+<!-- Manual Setup Mode -->
+<select-enhancer>
+  <combobox-field name="numbers"></combobox-field>
+  <combobox-listbox>
+    <combobox-option>1</combobox-option>
+    <combobox-option>2</combobox-option>
+    <combobox-option>3</combobox-option>
+  </combobox-listbox>
+
+  <svg viewBox="0 0 100 100"><!-- Caret Icon SVG Elements ... --></svg>
+</select-enhancer>
+
+<!-- Select Enhancing Mode -->
+<select-enhancer>
+  <select name="numbers">
+    <option>1</option>
+    <option>2</option>
+    <option>3</option>
+  </select>
+
+  <svg viewBox="0 0 100 100"><!-- Caret Icon SVG Elements ... --></svg>
+</select-enhancer>
+```
+
+Additional examples of customizing the `Combobox` component's appearance can be found in our [guides](https://github.com/ITenthusiasm/custom-elements/tree/main/src/Combobox/docs/guides/styling-the-combobox.md).
+
+## What's Next?
+
+To learn more about all that you can accomplish with the `Combobox` component, visit our [documentation](https://github.com/ITenthusiasm/custom-elements/tree/main/src/Combobox/docs). Trust us, you've only seen the beginning of what can be done with this component!
+
+If you're too excited to sit and read, you can also play with our [`StackBlitz` Demo](https://stackblitz.com/edit/custom-elements-combobox?file=index.html,src%2Fmain.ts) to see the `Combobox` component in action.
+
 <!-- TODO: Link to example of styling our `combobox` to look like GitHub's or ShadcnUI's. Probably put it alongside an example of another styling approach. -->
+
+<!-- TODO: Maybe also add some example styles for making the `<select>` look like the `<combobox-field>`? -->

package/Combobox/types/preact.d.ts

@@ -37,7 +37,7 @@ declare module "preact" {
       defaultSelected?: Signalish<ComboboxOption["defaultSelected"] | undefined>;
       disabled?: Signalish<ComboboxOption["disabled"] | undefined>;
       selected?: Signalish<ComboboxOption["selected"] | undefined>;
-      value?: Signalish<ComboboxOption["value"] | undefined>;
+      value?: Signalish<ComboboxOption["value"] | number | undefined>;
     }
   }
 }

package/Combobox/types/react.d.ts

@@ -31,7 +31,7 @@ declare module "react" {
     defaultSelected?: ComboboxOption["defaultSelected"];
     disabled?: ComboboxOption["disabled"];
     selected?: ComboboxOption["selected"];
-    value?: ComboboxOption["value"];
+    value?: ComboboxOption["value"] | number;
   }
 
   // eslint-disable-next-line @typescript-eslint/no-namespace -- Necessary for type declaration merging

package/Combobox/types/solid.d.ts

@@ -20,12 +20,16 @@ declare module "solid-js" {
       disabled?: ComboboxField["disabled"];
       filter?: ComboboxField["filter"];
       filtermethod?: ComboboxField["filterMethod"];
+      "attr:filtermethod"?: ComboboxField["filterMethod"];
       form?: string;
       name?: ComboboxField["name"];
       nomatchesmessage?: ComboboxField["noMatchesMessage"];
+      "attr:nomatchesmessage"?: ComboboxField["noMatchesMessage"];
       required?: ComboboxField["required"];
       valueis?: ComboboxField["valueIs"];
+      "attr:valueis"?: ComboboxField["valueIs"];
       valuemissingerror?: ComboboxField["valueMissingError"];
+      "attr:valuemissingerror"?: ComboboxField["valueMissingError"];
 
       onFilterchange?: EventHandlerUnion<T, Event>;
       onfilterchange?: EventHandlerUnion<T, Event>;
@@ -38,8 +42,15 @@ declare module "solid-js" {
 
     interface ComboboxOptionHTMLAttributes<T> extends HTMLAttributes<T> {
       disabled?: ComboboxOption["disabled"];
-      selected?: ComboboxOption["selected"];
-      value?: ComboboxOption["value"];
+      selected?: ComboboxOption["defaultSelected"];
+      value?: ComboboxOption["value"] | number;
+    }
+
+    interface ExplicitBoolAttributes {
+      filter?: boolean;
+      disabled?: boolean;
+      required?: boolean;
+      selected?: boolean;
     }
   }
 }

package/Combobox/types/svelte.d.ts

@@ -15,7 +15,7 @@ declare module "svelte/elements" {
     optiontag?: SelectEnhancer["optionTag"] | null;
   }
 
-  interface HTMLComboboxFieldAttributes<T extends EventTarget> extends HTMLAttributes<T> {
+  interface HTMLComboboxFieldAttributes<T extends EventTarget = ComboboxField> extends HTMLAttributes<T> {
     disabled?: ComboboxField["disabled"] | null;
     filter?: ComboboxField["filter"] | null;
     filtermethod?: ComboboxField["filterMethod"] | null;
@@ -38,6 +38,6 @@ declare module "svelte/elements" {
     defaultSelected?: ComboboxOption["defaultSelected"] | null;
     disabled?: ComboboxOption["disabled"] | null;
     selected?: ComboboxOption["selected"] | null;
-    value?: ComboboxOption["value"] | null;
+    value?: ComboboxOption["value"] | number | null;
   }
 }

package/Combobox/types/vue.d.ts

@@ -65,7 +65,7 @@ declare module "vue" {
     defaultSelected?: ComboboxOption["defaultSelected"];
     disabled?: ComboboxOption["disabled"];
     selected?: ComboboxOption["selected"];
-    value?: ComboboxOption["value"];
+    value?: ComboboxOption["value"] | number;
   }
 
   interface ComboboxOptionVueSFCType extends ComboboxOption {

package/README.md

@@ -1,3 +1,27 @@
 # @itenthusiasm/custom-elements
 
-Robust, accessible, and progressively-enhanceable Web Components for common developer needs.
+Robust, accessible, and progressively-enhanceable [Web Components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components) for common developer needs. Each component integrates seamlessly into your web applications, whether you use pure HTML/CSS/JS or you use a JS Framework.
+
+## Install
+
+```
+npm install @itenthusiasm/custom-elements
+```
+
+## Components
+
+Below are the components that this library currently provides. Each component has its own `README` which you can view to learn more about how the component operates.
+
+<dl>
+  <dt id="components-combobox">
+    <a href="./Combobox"><code>Combobox</code></a>
+  </dt>
+  <dd>
+    <p>
+      Progressively enhances the <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/select"><code>&lt;select&gt;</code></a> element, transforming it into a stylable, (optionally) filterable <a href="https://www.w3.org/TR/wai-aria-1.2/#combobox"><code>combobox</code></a> which meets WAI-ARIA's <a href="https://www.w3.org/WAI/ARIA/apg/patterns/combobox/">accessibility requirements</a>. The <code>Combobox</code> component behaves just like the native form controls, meaning that it dispatches the standard <code>input</code>/<code>change</code> events, is <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/elements">associated</a> with its owning form, and automatically participates in all form activity, <a href="https://web.dev/articles/more-capable-form-controls">including form submission</a>.
+    </p>
+    <p>
+      <a href="https://stackblitz.com/edit/custom-elements-combobox?file=index.html,src%2Fmain.ts">Stackblitz Form Integration Demo</a>
+    </p>
+  </dd>
+</dl>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@itenthusiasm/custom-elements",
   "type": "module",
-  "version": "0.0.2",
+  "version": "0.7.0",
   "sideEffects": false,
   "license": "MIT",
   "description": "Robust, accessible, and progressively-enhanceable Web Components for common developer needs",
@@ -33,11 +33,12 @@
     "progressive-enhancement"
   ],
   "files": [
-    "./**/README.md",
+    "./*/README.md",
     "./**/*.{js,css,d.ts}"
   ],
   "exports": {
     "./*.js": "./*.js",
+    "./*.css": "./*.css",
     "./*.d.ts": {
       "types": "./*.d.ts"
     },