html-combobox-element 0.0.6 → 0.0.8

package/dist/cjs/index.d.ts

@@ -1,67 +1,86 @@
+import { HTMLComboboxElement as ComboboxElementClass } from './combobox/HTML.combobox.element.js';
+import type { HTMLComboboxOptionsCollection } from './combobox/HTML.combobox.options.collection.js';
 export * from './combobox/index.js';
-interface HTMLComboboxTagElement extends HTMLElement {
-}
-interface HTMLComboboxOptionElement extends HTMLOptionElement {
-    value: string;
-    label: string;
-}
-interface HTMLComboboxElement extends HTMLSelectElement {
-    /** List of selected options value attribute */
-    valueAsArray: string[];
-    multiple: boolean;
-    /** The value of internal input
-     *
-     * Internal input is visible when either "searchable" or "filterable" attribute is presented */
-    query: string;
-    /** The placeholder of internal input
-     *
-     * Internal input is visible when either "searchable" or "filterable" attribute is presented
-     *
-     * When <combo-box> is empty, this value is also shown as <combo-box> placeholder itself
-     * */
-    placeholder: string;
-    /** When is true, the clear-all-button is shown in the <combo-box> itself,
-     * and the clear-button is shown for each selected tag.
-     *
-     * If multiple attribute is set to "true", this is also enabled.
-     *
-     * If multiple attribute is set to "false", i.e. the <combo-box> is used as a <select>,
-     * then setting this attribute to "true" will make the clear-button of selected tag visible
-     * */
-    clearable: boolean;
-    /** When is true, the internal input is shown.
-     *
-     * When user type something, available options are not filtered by this query.
-     * You have to set an "input" listener to the <combo-box> and filter options by yourself
-     *
-     * Setting both "searchable" and "filterable" make no sense, the "searchable" will have priority
-     * */
-    searchable: boolean;
-    /** When is true, the internal input is shown.
-     *
-     * When user type something, available options are filtered by this query.
-     *
-     * Setting both "filterable" and "searchable" make no sense, the "searchable" will have priority
-     * */
-    filterable: boolean;
-    selectedOptions: HTMLCollectionOf<HTMLComboboxOptionElement>;
-    addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLComboboxElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
-    addEventListener<K extends keyof ComboboxEventMap>(type: K, listener: (this: HTMLComboboxElement, ev: ComboboxEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
-    addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
-    removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLComboboxElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
-    removeEventListener<K extends keyof ComboboxEventMap>(type: K, listener: (this: HTMLComboboxElement, ev: ComboboxEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
-    removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
-}
-interface ComboboxEventMap extends HTMLElementEventMap {
-    "change": ComboboxEvent;
-    "blur": ComboboxFocusEvent;
-    "focus": ComboboxFocusEvent;
-    "focusin": ComboboxFocusEvent;
-    "focusout": ComboboxFocusEvent;
-    "input": ComboboxInputEvent;
-    "invalid": ComboboxEvent;
-    "selectionchange": ComboboxEvent;
-    "selectstart": ComboboxEvent;
+export declare const HTMLComboboxElement: Omit<typeof ComboboxElementClass, 'prototype'> & {
+    prototype: HTMLComboboxElement;
+    new (): HTMLComboboxElement;
+};
+export type HTMLComboboxElement = globalThis.HTMLComboboxElement;
+declare global {
+    interface HTMLComboboxTagElement extends HTMLElement {
+    }
+    interface HTMLComboboxOptionElement extends HTMLOptionElement {
+        value: string;
+        label: string;
+    }
+    interface HTMLComboboxElement extends HTMLSelectElement {
+        /** List of selected options value attribute */
+        valueAsArray: string[];
+        /** Whether the value differs from when the picker opened (read it in a `close` listener). */
+        readonly changed: boolean;
+        /** A live `HTMLOptionsCollection`-compatible collection (not `instanceof HTMLOptionsCollection`). */
+        readonly options: HTMLOptionsCollection & HTMLComboboxOptionsCollection;
+        multiple: boolean;
+        /** The value of internal input
+         *
+         * Internal input is visible when either "searchable" or "filterable" attribute is presented */
+        query: string;
+        /** The placeholder of internal input
+         *
+         * Internal input is visible when either "searchable" or "filterable" attribute is presented
+         *
+         * When <combo-box> is empty, this value is also shown as <combo-box> placeholder itself
+         * */
+        placeholder: string;
+        /** When is true, the clear-all-button is shown in the <combo-box> itself,
+         * and the clear-button is shown for each selected tag.
+         *
+         * If multiple attribute is set to "true", this is also enabled.
+         *
+         * If multiple attribute is set to "false", i.e. the <combo-box> is used as a <select>,
+         * then setting this attribute to "true" will make the clear-button of selected tag visible
+         * */
+        clearable: boolean;
+        /** When is true, the internal input is shown.
+         *
+         * When user type something, available options are not filtered by this query.
+         * You have to set an "input" listener to the <combo-box> and filter options by yourself
+         *
+         * Setting both "searchable" and "filterable" make no sense, the "searchable" will have priority
+         * */
+        searchable: boolean;
+        /** When is true, the internal input is shown.
+         *
+         * When user type something, available options are filtered by this query.
+         *
+         * Setting both "filterable" and "searchable" make no sense, the "searchable" will have priority
+         * */
+        filterable: boolean;
+        selectedOptions: HTMLCollectionOf<HTMLComboboxOptionElement>;
+        addEventListener<K extends keyof ComboboxEventMap>(type: K, listener: (this: HTMLComboboxElement, ev: ComboboxEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLComboboxElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;
+        addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+        removeEventListener<K extends keyof ComboboxEventMap>(type: K, listener: (this: HTMLComboboxElement, ev: ComboboxEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: (this: HTMLComboboxElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | EventListenerOptions): void;
+        removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+    }
+    interface ComboboxEventMap extends HTMLElementEventMap {
+        "change": ComboboxEvent;
+        "blur": ComboboxFocusEvent;
+        "focus": ComboboxFocusEvent;
+        "focusin": ComboboxFocusEvent;
+        "focusout": ComboboxFocusEvent;
+        "input": ComboboxInputEvent;
+        "invalid": ComboboxEvent;
+        "selectionchange": ComboboxEvent;
+        "selectstart": ComboboxEvent;
+        /** The picker closed (read `event.target.changed`) */
+        "close": ComboboxEvent;
+        /** Enter was pressed in the search field */
+        "search": ComboboxEvent;
+        /** The owner form was reset */
+        "reset": ComboboxEvent;
+    }
 }
 /** Own attributes/properties of `<combo-box>`, shared by every JSX integration below. */
 export interface ComboboxJsxAttributes {
@@ -109,11 +128,20 @@ export interface ComboboxJsxAttributes {
     /** A Boolean attribute indicating that at least one option must be selected. */
     required?: boolean;
     disabled?: boolean;
+    /** The name the value is submitted under (`<combo-box>` is form-associated). */
+    name?: string;
+    /** The id of the `<form>` this combobox belongs to, when it isn't inside it. */
+    form?: string;
 }
 export interface ComboboxOptionJsxAttributes {
+    /** The value submitted and reported (`combobox.value`, `valueAsArray`) when this option is selected. */
     value: string;
+    /** The option's label; defaults to its text content. */
     label?: string;
+    /** Initially selected. `false`, `undefined` or removing the prop deselects it. */
     selected?: boolean;
+    /** Can't be selected by the user. `false`, `undefined` or removing the prop enables it. */
+    disabled?: boolean;
 }
 /**
  * Generic HTML/JSX passthrough attributes (class, style, event handlers, `data-*`, `aria-*`, ...).
@@ -125,21 +153,72 @@ export interface ComboboxOptionJsxAttributes {
  */
 export interface ComboboxCommonAttributes {
     id?: string;
+    /** CSS classes (Preact, Vue, Solid, React 19). */
     class?: string;
+    /** CSS classes (React). */
     className?: string;
+    /** Inline styles, in the framework's own format (a string or an object). */
     style?: unknown;
     slot?: string;
     title?: string;
     tabIndex?: number;
     hidden?: boolean;
     children?: unknown;
+    /** The element: `HTMLElementTagNameMap['combo-box']` (a ref object or callback, per framework). */
     ref?: unknown;
     key?: string | number;
+    /**
+     * The user changed the selection; `event.target.value` / `.valueAsArray` is the new value.
+     * - Preact, Solid, Vue: called with the DOM event.
+     * - React 19: called with a SyntheticEvent (`event.nativeEvent` is the DOM event).
+     * - React 18: **never called** - listen with `ref` + `addEventListener('change', ...)`.
+     */
     onChange?: (event: ComboboxEvent) => void;
+    /**
+     * The user typed in the search field; `event.target.query` is the text.
+     * Preact, Solid, Vue: the DOM InputEvent. React 18 and 19: a SyntheticEvent.
+     */
     onInput?: (event: ComboboxInputEvent) => void;
+    /** Focus moved into the combobox. Preact, Solid, Vue: the DOM event. React: a SyntheticEvent. */
     onFocus?: (event: ComboboxFocusEvent) => void;
+    /** Focus left the combobox. Preact, Solid, Vue: the DOM event. React: a SyntheticEvent. */
     onBlur?: (event: ComboboxFocusEvent) => void;
+    /**
+     * Validation failed (e.g. `required` and empty) on form submit or `checkValidity()`.
+     * - Preact, Solid, Vue: called, in either casing (`onInvalid` or `oninvalid`), with the DOM event.
+     * - React 19: only as `oninvalid` (lowercase).
+     * - React 18: **never called** - use `ref` + `addEventListener('invalid', ...)`.
+     */
     onInvalid?: (event: ComboboxEvent) => void;
+    /** Same event as `onInvalid`. React 19 needs this lowercase spelling; React 18 never calls it. */
+    oninvalid?: (event: ComboboxEvent) => void;
+    /**
+     * The value was reset: the owner `<form>` was reset, or the user cleared all (`clearable`).
+     * - Preact, Solid, Vue: called, in either casing (`onReset` or `onreset`), with the DOM event.
+     * - React 19: only as `onreset` (lowercase).
+     * - React 18: **never called** - use `ref` + `addEventListener('reset', ...)`.
+     */
+    onReset?: (event: ComboboxEvent) => void;
+    /** Same event as `onReset`. React 19 needs this lowercase spelling; React 18 never calls it. */
+    onreset?: (event: ComboboxEvent) => void;
+    /**
+     * The picker closed; `event.target.changed` tells whether the value changed meanwhile.
+     * - Preact, Solid, Vue: called, in either casing (`onClose` or `onclose`), with the DOM event.
+     * - React 19: only as `onclose` (lowercase).
+     * - React 18: **never called** - use `ref` + `addEventListener('close', ...)`.
+     */
+    onClose?: (event: ComboboxEvent) => void;
+    /** Same event as `onClose`. React 19 needs this lowercase spelling; React 18 never calls it. */
+    onclose?: (event: ComboboxEvent) => void;
+    /**
+     * Enter was pressed in the search field; `event.target.query` is the text.
+     * - Preact, Solid, Vue: called, in either casing, with the DOM event.
+     * - React 19: only as `onsearch` (lowercase).
+     * - React 18: **never called** - use `ref` + `addEventListener('search', ...)`.
+     */
+    onSearch?: (event: ComboboxEvent) => void;
+    /** Same event as `onSearch`. React 19 needs this lowercase spelling; React 18 never calls it. */
+    onsearch?: (event: ComboboxEvent) => void;
     [key: `data-${string}`]: unknown;
     [key: `aria-${string}`]: unknown;
     [key: `on${string}`]: ((event: any) => void) | undefined;
@@ -172,30 +251,97 @@ declare global {
         }
     }
 }
+// #region react-type-fallbacks
+/*
+ * Module-private stand-ins for the React types the augmentation below uses. Inside
+ * `declare module 'react'` React's own HTMLAttributes/Key/Ref take precedence; these only resolve
+ * when React's types aren't in the program (React not installed, or - on TypeScript 7 - not
+ * imported by any checked file). Then the augmentation is inert, and without them a project with
+ * `skipLibCheck: false` would get "Cannot find name"/"Cannot find module 'react'" errors from it.
+ * (`import('react').X` can't be used for the same reason.)
+ * The declaration emitter drops them as unused (React is installed here), so
+ * scripts/fix-dual-package.mjs copies this region into the emitted index.d.ts files.
+ */
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type HTMLAttributes<T> = object;
+type Key = string | number | bigint;
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+type Ref<T> = unknown;
+// #endregion react-type-fallbacks
 declare module 'react' {
-    namespace JSX {
-        interface IntrinsicElements {
-            'combo-box': ComboboxElementAttributes;
-            'box-option': ComboboxOptionElementAttributes;
-            'box-tag': ComboboxTagElementAttributes;
-        }
+    /**
+     * The event React passes to the handlers it manages: React's SyntheticEvent (same members), with
+     * `target` being the element (events from the shadow DOM are retargeted to it).
+     */
+    interface ComboboxSyntheticEvent<T, E extends globalThis.Event = globalThis.Event> {
+        nativeEvent: E;
+        currentTarget: EventTarget & T;
+        target: EventTarget & T;
+        bubbles: boolean;
+        cancelable: boolean;
+        defaultPrevented: boolean;
+        eventPhase: number;
+        isTrusted: boolean;
+        timeStamp: number;
+        type: string;
+        preventDefault(): void;
+        isDefaultPrevented(): boolean;
+        stopPropagation(): void;
+        isPropagationStopped(): boolean;
+        persist(): void;
     }
-}
-declare module 'react/jsx-runtime' {
-    namespace JSX {
-        interface IntrinsicElements {
-            'combo-box': ComboboxElementAttributes;
-            'box-option': ComboboxOptionElementAttributes;
-            'box-tag': ComboboxTagElementAttributes;
-        }
+    /** Bivariant like React's EventHandler, so React's own handler types (ChangeEventHandler...) fit. */
+    type ComboboxEventHandler<E> = {
+        bivarianceHack(event: E): void;
+    }['bivarianceHack'];
+    /** React's ClassAttributes: `key` and a typed `ref`. */
+    interface ComboboxClassAttributes<T> {
+        key?: Key | null | undefined;
+        ref?: Ref<T> | undefined;
     }
-}
-declare module 'react/jsx-dev-runtime' {
+    type ComboboxBaseHTMLAttributes<T extends EventTarget, Own> = Omit<HTMLAttributes<T>, keyof Own | 'class'> & Own & {
+        class?: string | undefined;
+    };
+    type ComboboxHTMLAttributes<T extends EventTarget> = ComboboxBaseHTMLAttributes<T, ComboboxJsxAttributes & {
+        /** The user changed the selection (`event.target.value` is the new value). */
+        onChange?: ComboboxEventHandler<ComboboxSyntheticEvent<T>> | undefined;
+        /** The user typed in the search field (`event.target.query`); `nativeEvent` is its InputEvent. */
+        onInput?: ComboboxEventHandler<ComboboxSyntheticEvent<T, globalThis.InputEvent>> | undefined;
+        /** Never called by React 19 for custom elements (the event doesn't bubble) - use `oninvalid`. */
+        onInvalid?: undefined;
+        /** Never called by React 19 for custom elements (the event doesn't bubble) - use `onreset`. */
+        onReset?: undefined;
+        /** Native listener: the picker closed (`event.target.changed`). Lowercase - `onClose` never fires. */
+        onclose?: ((event: ComboboxEvent) => void) | undefined;
+        /** Native listener: Enter in the search field. Lowercase - `onSearch` never fires. */
+        onsearch?: ((event: ComboboxEvent) => void) | undefined;
+        /** Native listener: the owner form was reset, or the user cleared all. Lowercase - `onReset` never fires. */
+        onreset?: ((event: ComboboxEvent) => void) | undefined;
+        /** Native listener: validation failed (e.g. `required` and empty). Lowercase - `onInvalid` never fires. */
+        oninvalid?: ((event: ComboboxEvent) => void) | undefined;
+    }>;
+    type ComboboxOptionHTMLAttributes<T extends EventTarget> = ComboboxBaseHTMLAttributes<T, ComboboxOptionJsxAttributes>;
+    type ComboboxTagHTMLAttributes<T extends EventTarget> = ComboboxBaseHTMLAttributes<T, {}>;
+    /**
+     * Which props to use:
+     * - @types/react 19: React-typed props (SyntheticEvents, typed ref, React's attributes).
+     * - @types/react 18 builds React.JSX.IntrinsicElements on top of the global JSX namespace, so
+     *   its entries must stay assignable to the framework-agnostic global ones: those are kept.
+     *   (React 18 types declare the HTML elements in the global namespace, React 19 types don't.)
+     * - preact/compat aliased as 'react': its JSX is Preact's, and Preact passes native DOM events,
+     *   so the framework-agnostic props - the same ones the 'preact' augmentation declares.
+     *   (Preact's JSX accepts `class`, React's doesn't.)
+     */
+    type ComboboxIntrinsicElement<Global, Typed> = globalThis.JSX.IntrinsicElements extends {
+        div: unknown;
+    } ? Global : JSX.IntrinsicElements extends {
+        div: infer Div;
+    } ? ('class' extends keyof Div ? Global : Typed) : Typed;
     namespace JSX {
         interface IntrinsicElements {
-            'combo-box': ComboboxElementAttributes;
-            'box-option': ComboboxOptionElementAttributes;
-            'box-tag': ComboboxTagElementAttributes;
+            'combo-box': ComboboxIntrinsicElement<ComboboxElementAttributes, ComboboxClassAttributes<HTMLComboboxElement> & ComboboxHTMLAttributes<HTMLComboboxElement>>;
+            'box-option': ComboboxIntrinsicElement<ComboboxOptionElementAttributes, ComboboxClassAttributes<HTMLComboboxOptionElement> & ComboboxOptionHTMLAttributes<HTMLComboboxOptionElement>>;
+            'box-tag': ComboboxIntrinsicElement<ComboboxTagElementAttributes, ComboboxClassAttributes<HTMLComboboxTagElement> & ComboboxTagHTMLAttributes<HTMLComboboxTagElement>>;
         }
     }
 }

package/dist/cjs/index.js

@@ -14,4 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.HTMLComboboxElement = void 0;
+const HTML_combobox_element_js_1 = require("./combobox/HTML.combobox.element.js");
 __exportStar(require("./combobox/index.js"), exports);
+exports.HTMLComboboxElement = HTML_combobox_element_js_1.HTMLComboboxElement;

package/dist/esm/combobox/Boolean.attribute.value.normalizer.js

@@ -1,4 +1,8 @@
-/** Transform invalid (nullish or stringed) values to correct boolean value */
+/**
+ * An ATTRIBUTE value as a boolean: present means true (`multiple=""`, `multiple="multiple"`),
+ * absent (`null`) means false. The string "false" also means false, so `multiple="false"` from a
+ * template or a framework that stringifies values doesn't turn the feature on.
+ */
 export function toBoolean(value) {
     if (value == null || value === 'false' || value === false)
         value = false;
@@ -6,3 +10,14 @@ export function toBoolean(value) {
         value = true;
     return Boolean(value);
 }
+/**
+ * A PROPERTY value as a boolean, like native boolean properties (`select.multiple = ''` is false):
+ * JavaScript truthiness, except the string "false", which stays false as with attributes.
+ *
+ * Frameworks that set properties rely on this: Preact clears a removed or `undefined` prop with
+ * `element.multiple = ''`, which must turn the feature off. Attribute values (`setAttribute`,
+ * the initial attributes) go through `toBoolean` instead.
+ */
+export function propertyToBoolean(value) {
+    return value !== 'false' && Boolean(value);
+}

package/dist/esm/combobox/HTML.combobox.element.js

@@ -1,6 +1,6 @@
 import { ComboboxMarkup } from './Combobox.markup.js';
 import { HTMLComboboxOptionElement } from './HTML.combobox.option.element.js';
-import { toBoolean } from './Boolean.attribute.value.normalizer.js';
+import { propertyToBoolean, toBoolean } from './Boolean.attribute.value.normalizer.js';
 import { HTMLComboboxOptionsCollection } from './HTML.combobox.options.collection.js';
 export class HTMLComboboxElement extends HTMLElement {
     static OWN_IDL = new Set(['required', 'disabled', 'clearable', 'multiple', 'filterable', 'searchable', 'value', 'placeholder', 'query']);
@@ -249,26 +249,26 @@ export class HTMLComboboxElement extends HTMLElement {
         return this.hasAttribute('clearable');
     }
     set clearable(value) {
-        super.toggleAttribute('clearable', toBoolean(value));
+        super.toggleAttribute('clearable', propertyToBoolean(value));
     }
     get filterable() {
         return this.hasAttribute('filterable');
     }
     set filterable(value) {
-        super.toggleAttribute('filterable', toBoolean(value));
+        super.toggleAttribute('filterable', propertyToBoolean(value));
     }
     get searchable() {
         return this.hasAttribute('searchable');
     }
     set searchable(value) {
-        super.toggleAttribute('searchable', toBoolean(value));
+        super.toggleAttribute('searchable', propertyToBoolean(value));
     }
     // <select> specific properties (implements HTMLSelectElement)
     get disabled() {
         return this.hasAttribute('disabled');
     }
     set disabled(value) {
-        super.toggleAttribute('disabled', toBoolean(value));
+        super.toggleAttribute('disabled', propertyToBoolean(value));
     }
     get form() {
         return this.#internals.form;
@@ -287,7 +287,7 @@ export class HTMLComboboxElement extends HTMLElement {
         return this.hasAttribute('multiple');
     }
     set multiple(value) {
-        super.toggleAttribute('multiple', toBoolean(value));
+        super.toggleAttribute('multiple', propertyToBoolean(value));
     }
     /** The options, as a live `HTMLOptionsCollection`-like list (like `select.options`) */
     get options() {
@@ -301,7 +301,7 @@ export class HTMLComboboxElement extends HTMLElement {
         return this.hasAttribute('required');
     }
     set required(value) {
-        super.toggleAttribute('required', toBoolean(value));
+        super.toggleAttribute('required', propertyToBoolean(value));
     }
     /** Index of the first selected option, or -1. Setting it selects only that option. */
     get selectedIndex() {
@@ -393,7 +393,8 @@ export class HTMLComboboxElement extends HTMLElement {
     // Overwritten methods
     setAttribute(name, value) {
         if (HTMLComboboxElement.OWN_IDL.has(name)) {
-            Reflect.set(this, name, value);
+            // through the setter, with attribute semantics: setAttribute('multiple', '') turns it on
+            Reflect.set(this, name, HTMLComboboxElement.#BOOLEAN_ATTRIBUTES.has(name) ? toBoolean(value) : value);
         }
         else {
             super.setAttribute(name, value);
@@ -834,7 +835,8 @@ export class HTMLComboboxElement extends HTMLElement {
             // `value = null` would clear it
             if (key === 'value' && !this.hasAttribute('value'))
                 continue;
-            this[key] = this.getAttribute(key);
+            const attribute = this.getAttribute(key);
+            Reflect.set(this, key, HTMLComboboxElement.#BOOLEAN_ATTRIBUTES.has(key) ? toBoolean(attribute) : attribute);
         }
     }
     static loadCssFromUrls(urls) {

package/dist/esm/combobox/HTML.combobox.option.element.js

@@ -1,4 +1,4 @@
-import { toBoolean } from './Boolean.attribute.value.normalizer.js';
+import { propertyToBoolean, toBoolean } from './Boolean.attribute.value.normalizer.js';
 /**
  * The `<option>` of `<combo-box>`.
  *
@@ -18,6 +18,7 @@ import { toBoolean } from './Boolean.attribute.value.normalizer.js';
  */
 export class HTMLComboboxOptionElement extends HTMLElement {
     static OWN_IDL = new Set(['value', 'label', 'selected', 'disabled']);
+    static #BOOLEAN_ATTRIBUTES = new Set(['selected', 'disabled']);
     static observedAttributes = ['selected', 'disabled'];
     static EventInit = { bubbles: true, cancelable: true, composed: true };
     #internals;
@@ -75,13 +76,13 @@ export class HTMLComboboxOptionElement extends HTMLElement {
     }
     // Normalization only: the side effects run in attributeChangedCallback
     set selected(value) {
-        super.toggleAttribute('selected', toBoolean(value));
+        super.toggleAttribute('selected', propertyToBoolean(value));
     }
     get disabled() {
         return this.hasAttribute('disabled');
     }
     set disabled(value) {
-        super.toggleAttribute('disabled', toBoolean(value));
+        super.toggleAttribute('disabled', propertyToBoolean(value));
     }
     attributeChangedCallback(name, _oldValue, newValue) {
         // A path that skipped the setters can leave a value they'd never write, e.g. selected="false".
@@ -136,12 +137,14 @@ export class HTMLComboboxOptionElement extends HTMLElement {
     }
     #initialAttributesSynchronization() {
         for (const key of HTMLComboboxOptionElement.OWN_IDL) {
-            this[key] = this.getAttribute(key);
+            const attribute = this.getAttribute(key);
+            Reflect.set(this, key, HTMLComboboxOptionElement.#BOOLEAN_ATTRIBUTES.has(key) ? toBoolean(attribute) : attribute);
         }
     }
     setAttribute(name, value) {
         if (HTMLComboboxOptionElement.OWN_IDL.has(name)) {
-            this[name] = value;
+            // through the setter, with attribute semantics: setAttribute('selected', '') selects
+            Reflect.set(this, name, HTMLComboboxOptionElement.#BOOLEAN_ATTRIBUTES.has(name) ? toBoolean(value) : value);
         }
         else {
             super.setAttribute(name, value);

package/dist/esm/index.js

@@ -1 +1,3 @@
+import { HTMLComboboxElement as ComboboxElementClass } from './combobox/HTML.combobox.element.js';
 export * from './combobox/index.js';
+export const HTMLComboboxElement = ComboboxElementClass;

package/dist/types/combobox/Boolean.attribute.value.normalizer.d.ts

@@ -1,2 +1,15 @@
-/** Transform invalid (nullish or stringed) values to correct boolean value */
+/**
+ * An ATTRIBUTE value as a boolean: present means true (`multiple=""`, `multiple="multiple"`),
+ * absent (`null`) means false. The string "false" also means false, so `multiple="false"` from a
+ * template or a framework that stringifies values doesn't turn the feature on.
+ */
 export declare function toBoolean(value: any): boolean;
+/**
+ * A PROPERTY value as a boolean, like native boolean properties (`select.multiple = ''` is false):
+ * JavaScript truthiness, except the string "false", which stays false as with attributes.
+ *
+ * Frameworks that set properties rely on this: Preact clears a removed or `undefined` prop with
+ * `element.multiple = ''`, which must turn the feature off. Attribute values (`setAttribute`,
+ * the initial attributes) go through `toBoolean` instead.
+ */
+export declare function propertyToBoolean(value: unknown): boolean;