@itenthusiasm/custom-elements 0.0.1

package/Combobox/Combobox.css

@@ -0,0 +1,100 @@
+select-enhancer {
+  --blocks: 5; /* Number of option blocks to display before needing to scroll */
+
+  position: relative;
+  display: inline-block;
+  box-sizing: border-box;
+  width: inherit;
+  height: inherit;
+
+  @media only screen and (min-width: 600px) {
+    --blocks: 10;
+  }
+
+  & > [role="combobox"] {
+    --border-width: 1.5px;
+
+    display: block;
+    box-sizing: border-box;
+    width: 100%;
+    height: 100%;
+    padding: 8px;
+    border: var(--border-width) solid #cecece;
+    border-radius: 4px;
+    outline: none;
+    overflow-x: auto;
+
+    cursor: pointer;
+    white-space: pre;
+    text-align: center;
+    font-size: inherit;
+    font-family: inherit;
+    color: currentcolor;
+    background-color: white;
+
+    &[filter] {
+      cursor: auto;
+    }
+
+    &:focus {
+      border-color: dodgerblue;
+    }
+
+    & + [role="listbox"] {
+      --listbox-border: 2px;
+      --option-height: 38px;
+      --option-padding: 8px;
+
+      position: absolute;
+      z-index: 2;
+
+      box-sizing: border-box;
+      width: 100%;
+      max-height: calc(var(--option-height) * var(--blocks) + var(--listbox-border) * 2);
+      padding: 0;
+      border: var(--listbox-border) solid #cecece;
+      border-radius: 4px;
+      margin: 0;
+
+      overflow: auto;
+      background-color: white;
+
+      &:is([role="combobox"]:not([aria-expanded="true"]) + [role="listbox"]) {
+        display: none;
+      }
+
+      & > [role="option"],
+      &:where([role="combobox"][data-bad-filter] + [role="listbox"])::after {
+        display: block;
+        box-sizing: border-box;
+        height: var(--option-height);
+        padding: var(--option-padding);
+        cursor: pointer;
+
+        &[data-active="true"]:not([aria-selected="true"]) {
+          background-color: #bddaff; /* `background-color` for `selected` items, brightened by 70% */
+        }
+
+        &[aria-selected="true"] {
+          color: white;
+          background-color: #2684ff;
+        }
+
+        &[data-filtered-out] {
+          display: none;
+          visibility: hidden; /* Needed to hide filtered-out `option`s in Safari + VoiceOver (Bug in Browser) */
+        }
+
+        /* TODO: Add clearer `disabled` styles. */
+        &[aria-disabled="true"] {
+          cursor: auto;
+        }
+      }
+
+      &:where([role="combobox"][data-bad-filter] + [role="listbox"])::after {
+        content: attr(nomatchesmessage, "No options found") / "";
+        cursor: auto;
+      }
+    }
+  }
+}

package/Combobox/ComboboxField.d.ts

@@ -0,0 +1,243 @@
+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} */
+    static get formAssociated(): true;
+    static get observedAttributes(): readonly ["id", "required", "filter", "valueis", "nomatchesmessage", "valuemissingerror"];
+    /** Internally used to indicate when the `combobox` is actively transitioning out of {@link filter} mode. */
+    static "__#private@#filterDisabedKey": symbol;
+    static defaultNoMatchesMessage: string;
+    /**
+     * @param {MouseEvent} event
+     * @returns {void}
+     */
+    static "__#private@#handleClick"(event: MouseEvent): void;
+    /**
+     * Used to determine if a {@link filter filterable} `combobox` was `:focus`ed by a `click` event.
+     * @param {MouseEvent} event
+     * @returns {void}
+     */
+    static "__#private@#handleMousedown"(event: MouseEvent): void;
+    /**
+     * (For {@link filter filtered} `combobox`es only)
+     * @param {FocusEvent} event
+     * @returns {void}
+     */
+    static "__#private@#handleFocus"(event: FocusEvent): void;
+    /**
+     * @param {FocusEvent} event
+     * @returns {void}
+     */
+    static "__#private@#handleBlur"(event: FocusEvent): void;
+    /**
+     * @param {MouseEvent} event
+     * @returns {void}
+     */
+    static "__#private@#handleDelegatedOptionHover"(event: MouseEvent): void;
+    /**
+     * @param {MouseEvent} event
+     * @returns {void}
+     */
+    static "__#private@#handleDelegatedOptionClick"(event: MouseEvent): void;
+    /**
+     * @param {MouseEvent} event
+     * @returns {void}
+     */
+    static "__#private@#handleDelegatedMousedown"(event: MouseEvent): void;
+    /**
+     * @param {MutationRecord[]} mutations
+     * @returns {void}
+     */
+    static "__#private@#preserveTextNode"(mutations: MutationRecord[]): void;
+    /**
+     * @param {MutationRecord[]} mutations
+     * @returns {void}
+     */
+    static "__#private@#watchActiveDescendant"(mutations: MutationRecord[]): void;
+    /**
+     * @param {typeof ComboboxField.observedAttributes[number]} name
+     * @param {string | null} oldValue
+     * @param {string | null} newValue
+     * @returns {void}
+     */
+    attributeChangedCallback(name: (typeof ComboboxField.observedAttributes)[number], oldValue: string | null, newValue: string | null): void;
+    /** @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} */
+    connectedCallback(): void;
+    set noMatchesMessage(value: string);
+    /**
+     * The message displayed to users when none of the `combobox`'s `option`s match their filter.
+     * @returns {string}
+     */
+    get noMatchesMessage(): string;
+    /** "On Unmount" for Custom Elements @returns {void} */
+    disconnectedCallback(): void;
+    /**
+     * Updates the {@link ComboboxOption.filteredOut `filteredOut`} property for all of the `option`s,
+     * then returns the `option`s that match the user's current filter.
+     *
+     * @returns {GetFilteredOptionsReturnType}
+     */
+    getFilteredOptions(): {
+        /**
+         * The `option`s which match the user's current filter
+         */
+        matchingOptions: ComboboxOption[];
+        /**
+         * (Optional): The `option` which is a candidate for
+         * automatic selection. See: {@link ComboboxField.autoselectableOption}.
+         */
+        autoselectableOption?: ComboboxOption | undefined;
+    };
+    /**
+     * @typedef GetFilteredOptionsReturnType
+     * @property {ComboboxOption[]} matchingOptions The `option`s which match the user's current filter
+     * @property {ComboboxOption} [autoselectableOption] (Optional): The `option` which is a candidate for
+     * automatic selection. See: {@link ComboboxField.autoselectableOption}.
+     */
+    /**
+     * The logic used by {@link filter filterable} `combobox`es to determine if an `option` matches the user's filter.
+     *
+     * **Note**: If {@link getFilteredOptions} is overridden, this method will do nothing unless it is
+     * used directly within the new implementation.
+     *
+     * @param {ComboboxOption} option
+     * @returns {boolean}
+     */
+    optionMatchesFilter(option: ComboboxOption): boolean;
+    /**
+     * Coerces the value and filter of the `combobox` to an empty string, and deselects the currently-selected `option`
+     * if one exists (including any `option` whose value is an empty string).
+     *
+     * @returns {void}
+     * @throws {TypeError} if the `combobox` is not {@link filter filterable}, or if its value
+     * {@link valueIs cannot be cleared}.
+     */
+    forceEmptyValue(): void;
+    /**
+     * Retrieves the `option` with the provided `value` (if it exists)
+     * @param {string} value
+     * @returns {ComboboxOption | null}
+     */
+    getOptionByValue(value: string): ComboboxOption | null;
+    set name(value: HTMLInputElement["name"]);
+    /** @returns {HTMLInputElement["name"]} */
+    get name(): HTMLInputElement["name"];
+    set disabled(value: HTMLInputElement["disabled"]);
+    /** @returns {HTMLInputElement["disabled"]} */
+    get disabled(): HTMLInputElement["disabled"];
+    set required(value: HTMLInputElement["required"]);
+    /** @returns {HTMLInputElement["required"]} */
+    get required(): HTMLInputElement["required"];
+    /**
+     * The `listbox` that this `combobox` controls.
+     * @returns {ListboxWithChildren<ComboboxOption>}
+     */
+    get listbox(): ListboxWithChildren<ComboboxOption>;
+    /**
+     * The _singular_ {@link Text} Node associated with the `combobox`.
+     *
+     * To alter the `combobox`'s text content, update this node **_instead of_** using {@link textContent}.
+     * @returns {Text}
+     */
+    get text(): Text;
+    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 | "length" | "toString" | "charAt" | "charCodeAt" | "concat" | "indexOf" | "lastIndexOf" | "localeCompare" | "match" | "replace" | "search" | "slice" | "split" | "substring" | "toLowerCase" | "toLocaleLowerCase" | "toUpperCase" | "toLocaleUpperCase" | "trim" | "substr" | "valueOf" | "codePointAt" | "includes" | "endsWith" | "normalize" | "repeat" | "startsWith" | "anchor" | "big" | "blink" | "bold" | "fixed" | "fontcolor" | "fontsize" | "italics" | "link" | "small" | "strike" | "sub" | "sup" | "padStart" | "padEnd" | "trimEnd" | "trimStart" | "trimLeft" | "trimRight" | "matchAll" | "replaceAll" | "at" | "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.
+     * - `includes`: {@link String.includes} will be used to filter the `option`s.
+     *
+     * **Note**: This property does nothing if {@link optionMatchesFilter} or {@link getFilteredOptions} is overridden.
+     *
+     * @returns {Extract<keyof String, "startsWith" | "includes">}
+     */
+    get filterMethod(): Extract<number | typeof Symbol.iterator | "length" | "toString" | "charAt" | "charCodeAt" | "concat" | "indexOf" | "lastIndexOf" | "localeCompare" | "match" | "replace" | "search" | "slice" | "split" | "substring" | "toLowerCase" | "toLocaleLowerCase" | "toUpperCase" | "toLocaleUpperCase" | "trim" | "substr" | "valueOf" | "codePointAt" | "includes" | "endsWith" | "normalize" | "repeat" | "startsWith" | "anchor" | "big" | "blink" | "bold" | "fixed" | "fontcolor" | "fontsize" | "italics" | "link" | "small" | "strike" | "sub" | "sup" | "padStart" | "padEnd" | "trimEnd" | "trimStart" | "trimLeft" | "trimRight" | "matchAll" | "replaceAll" | "at" | "isWellFormed" | "toWellFormed", "startsWith" | "includes">;
+    set valueIs(value: "unclearable" | "clearable" | "anyvalue");
+    /**
+     * Indicates how a `combobox`'s value will behave.
+     * - `unclearable`: The field's {@link value `value`} must be a string matching one of the `option`s,
+     * and it cannot be cleared. (Default when {@link filter `filter`} mode is off.)
+     * - `clearable`: The field's `value` must be a string matching one of the `option`s,
+     * but it can be cleared. (Default in `filter` mode. Requires enabling `filter` mode.)
+     * - `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
+     * -->
+     *
+     * @returns {"unclearable" | "clearable" | "anyvalue"}
+     */
+    get valueIs(): "unclearable" | "clearable" | "anyvalue";
+    /**
+     * @param {string} value
+     * @returns {boolean} `true` if the `combobox` will accept the provided `value` when no corresponding `option` exists.
+     * Otherwise, returns `false`.
+     */
+    acceptsValue(value: string): boolean;
+    /**
+     * 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 `combobox`'s text content was altered by a `value` change
+     * - The `combobox` was just recently expanded
+     * @returns {ComboboxOption | null}
+     */
+    get autoselectableOption(): ComboboxOption | null;
+    set valueMissingError(value: string);
+    /** The error message displayed to users when the `combobox`'s `required` constraint is broken. @returns {string} */
+    get valueMissingError(): string;
+    /** @returns {ElementInternals["labels"]} */
+    get labels(): ElementInternals["labels"];
+    /** @returns {ElementInternals["form"]} */
+    get form(): ElementInternals["form"];
+    /** @returns {ElementInternals["validity"]} */
+    get validity(): ElementInternals["validity"];
+    /** @returns {ElementInternals["validationMessage"]} */
+    get validationMessage(): ElementInternals["validationMessage"];
+    /** @returns {ElementInternals["willValidate"]} */
+    get willValidate(): ElementInternals["willValidate"];
+    checkValidity(): boolean;
+    reportValidity(): boolean;
+    setCustomValidity(error: string): void;
+    /** @returns {void} */
+    formResetCallback(): void;
+    /**
+     * @param {string} state
+     * @param {"restore" | "autocomplete"} _mode
+     * @returns {void}
+     */
+    formStateRestoreCallback(state: string, _mode: "restore" | "autocomplete"): void;
+    /**
+     * @param {boolean} disabled
+     * @returns {void}
+     */
+    formDisabledCallback(disabled: boolean): void;
+    /** @private @type {string | null} */ private [valueOnFocusKey];
+    /** @private @type {boolean} */ private [editingKey];
+    #private;
+}
+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. */
+declare const valueOnFocusKey: unique symbol;
+/** Internally used to determine if the `combobox`'s value is actively being modified through user's filter changes. */
+declare const editingKey: unique symbol;