html-combobox-element 0.0.6 → 0.0.8

package/dist/types/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/package.json

@@ -1,8 +1,12 @@
 {
   "name": "html-combobox-element",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "The combo-box web-component & customizable select polyfill",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nihil-pro/html-combobox-element.git"
+  },
   "scripts": {
     "prepare": "husky",
     "clean": "rm -rf dist",
@@ -11,7 +15,8 @@
     "postbuild": "node scripts/fix-dual-package.mjs",
     "check-types": "tsc --noEmit",
     "test": "playwright test",
-    "test:ui": "playwright test --ui"
+    "test:ui": "playwright test --ui",
+    "test:types": "playwright test -c playwright.types.config.ts"
   },
   "keywords": [
     "combo-box",
@@ -26,6 +31,7 @@
     "@playwright/test": "^1.65.0",
     "@types/node": "22.8.6",
     "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
     "c8": "10.1.2",
     "esbuild": "0.25.5",
     "husky": "9.1.5",
@@ -33,12 +39,37 @@
     "npm-run-all": "^4.1.5",
     "preact": "^10.28.4",
     "react": "^19.2.4",
+    "react-dom": "^19.2.4",
     "solid-js": "^1.9.11",
     "tsx": "^4.19.2",
     "typescript": "5.9.3",
     "vue": "^3.5.28",
     "xml-splitter": "1.2.1"
   },
+  "peerDependencies": {
+    "@types/react": "*",
+    "react": "*",
+    "preact": "*",
+    "solid-js": "*",
+    "vue": "*"
+  },
+  "peerDependenciesMeta": {
+    "@types/react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "preact": {
+      "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
   "sideEffect": false,
   "files": [
     "dist",