html-combobox-element 0.0.6 → 0.0.7

package/README.md

@@ -145,37 +145,38 @@ Playwright names a custom element from `<label for>` only for native controls,
 so query `getByRole('combobox', { name })` with `aria-label` or `aria-labelledby` on the `<combo-box>`, or without a name.
 
 ## TypeScript and JSX
-JSX/template type-checking only picks up custom element typings from a file in your own project - not from a package's shipped `.d.ts`.
-Due to this TypeScript limitation that affects any library adding custom elements to `JSX.IntrinsicElements` under the modern automatic JSX runtime – using `<combo-box>` in JSX or a Vue template needs one extra step. 
+`import 'html-combobox-element'` also brings the typings: `document.createElement('combo-box')`, `querySelector`, `addEventListener` with the combobox's own events (`change`, `input`, `close`, `search`, `reset`, with a typed `event.target`) and `instanceof HTMLComboboxElement` all use the same `HTMLComboboxElement` type.
+
+### React
+Nothing to add: `<combo-box>`, `<box-option>` and `<box-tag>` are typed with React's own types (`ref`, `style`, every DOM handler, `aria-*`...), for `jsx: "react-jsx"`, `"react-jsxdev"` and classic `"react"`.
+
+React wraps events in its own SyntheticEvents, so handlers are typed accordingly:
+- `onChange`, `onInput`, `onFocus`, `onClick`, ... receive a SyntheticEvent: `event.target` is the `<combo-box>` (`event.target.value`, `event.target.query`), `event.nativeEvent` is the DOM event.
+- Events React doesn't know are attached by React 19 as native listeners under the exact, case-sensitive name: use `onclose` and `onsearch` (lowercase). `onClose`/`onSearch` never fire, and are type errors.
+
+```tsx
+<combo-box
+  name="fruit"
+  multiple
+  onChange={(event) => setFruits(event.target.valueAsArray)}
+  onclose={(event) => event.target.changed && save()}
+>
+  <box-option value="apple">Apple</box-option>
+</combo-box>
+```
 
-So, in addition to `import 'html-combobox-element'`, create and include one small file in tsconfig.json, with the snippet for your framework: 
+With `@types/react` 18 the framework-agnostic typings are used, as in previous versions.
 
-<details>
-<summary><strong>React</strong> (<code>jsx: "react-jsx"</code>)</summary>
+If you copied the React `combo-box.d.ts` snippet from the README of a previous version, delete it: it still compiles, but it keeps the old typings.
 
+### Monorepos
+The typings are part of a TypeScript program only if the program includes this package. A workspace package that renders `<combo-box>` but leaves the import to the app shell type-checks inside the app, but not on its own (its CI, editor, project references). Add a type-only import there - it's removed from the JS output, nothing is registered twice:
 ```ts
-// combo-box.d.ts
-declare module 'react/jsx-runtime' {
-  namespace JSX {
-    interface IntrinsicElements {
-      'combo-box': ComboboxElementAttributes;
-      'box-option': ComboboxOptionElementAttributes;
-      'box-tag': ComboboxTagElementAttributes;
-    }
-  }
-}
-declare module 'react/jsx-dev-runtime' {
-  namespace JSX {
-    interface IntrinsicElements {
-      'combo-box': ComboboxElementAttributes;
-      'box-option': ComboboxOptionElementAttributes;
-      'box-tag': ComboboxTagElementAttributes;
-    }
-  }
-}
+import type {} from 'html-combobox-element';
 ```
 
-</details>
+### Other frameworks
+JSX/template type-checking for these needs one small file in your project, with the snippet for your framework:
 
 <details>
 <summary><strong>Preact</strong> (<code>jsx: "react-jsx"</code>, <code>jsxImportSource: "preact"</code>)</summary>

package/dist/cjs/index.d.ts

@@ -1,13 +1,31 @@
+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';
+/**
+ * The `<combo-box>` constructor, typed the way lib.dom types built-in elements
+ * (`interface HTMLSelectElement` + `declare var HTMLSelectElement: { prototype; new() }`):
+ * the same `HTMLComboboxElement` type is what `document.createElement('combo-box')`,
+ * `querySelector('combo-box')`, `event.target`, refs and `instanceof HTMLComboboxElement` give.
+ *
+ * Runtime-wise this is the very same class object that `export *` exported before.
+ */
+export declare const HTMLComboboxElement: Omit<typeof ComboboxElementClass, 'prototype'> & {
+    prototype: HTMLComboboxElement;
+    new (): HTMLComboboxElement;
+};
 interface HTMLComboboxTagElement extends HTMLElement {
 }
 interface HTMLComboboxOptionElement extends HTMLOptionElement {
     value: string;
     label: string;
 }
-interface HTMLComboboxElement extends HTMLSelectElement {
+export 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
      *
@@ -45,11 +63,11 @@ interface HTMLComboboxElement extends HTMLSelectElement {
      * */
     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<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 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<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 {
@@ -62,6 +80,12 @@ interface ComboboxEventMap extends HTMLElementEventMap {
     "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,6 +133,10 @@ 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 {
     value: string;
@@ -173,29 +201,45 @@ declare global {
     }
 }
 declare module 'react' {
-    namespace JSX {
-        interface IntrinsicElements {
-            'combo-box': ComboboxElementAttributes;
-            'box-option': ComboboxOptionElementAttributes;
-            'box-tag': ComboboxTagElementAttributes;
-        }
+    /** A React event whose `target` is the element (events from the shadow DOM are retargeted to it). */
+    type ComboboxSyntheticEvent<T, E extends globalThis.Event = globalThis.Event> = import('react').SyntheticEvent<T, E> & {
+        target: EventTarget & T;
+    };
+    type ComboboxBaseHTMLAttributes<T> = import('react').HTMLAttributes<T>;
+    type ComboboxBaseHostAttributes<T> = Omit<import('react').HTMLAttributes<T>, 'onInput'>;
+    interface ComboboxHTMLAttributes<T> extends ComboboxBaseHostAttributes<T>, ComboboxJsxAttributes {
+        class?: string | undefined;
+        /** The user changed the selection (`event.target.value` is the new value). */
+        onChange?: import('react').EventHandler<ComboboxSyntheticEvent<T>> | undefined;
+        /** The user typed in the search field (`event.target.query`); `nativeEvent` is its InputEvent. */
+        onInput?: import('react').EventHandler<ComboboxSyntheticEvent<T, globalThis.InputEvent>> | undefined;
+        onInvalid?: import('react').EventHandler<ComboboxSyntheticEvent<T>> | 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;
     }
-}
-declare module 'react/jsx-runtime' {
-    namespace JSX {
-        interface IntrinsicElements {
-            'combo-box': ComboboxElementAttributes;
-            'box-option': ComboboxOptionElementAttributes;
-            'box-tag': ComboboxTagElementAttributes;
-        }
+    interface ComboboxOptionHTMLAttributes<T> extends ComboboxBaseHTMLAttributes<T>, ComboboxOptionJsxAttributes {
+        class?: string | undefined;
     }
-}
-declare module 'react/jsx-dev-runtime' {
+    interface ComboboxTagHTMLAttributes<T> extends ComboboxBaseHTMLAttributes<T> {
+        class?: string | undefined;
+    }
+    /**
+     * @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 (catch-all `on*`,
+     * native event types): with React 18 types the global entries are kept as they are.
+     * @types/react 19 has no global JSX namespace: React.JSX gets React-typed props.
+     * (React 18 types declare the HTML elements in the global namespace, React 19 types don't.)
+     */
+    type ComboboxIntrinsicElement<Global, Typed> = globalThis.JSX.IntrinsicElements extends {
+        div: unknown;
+    } ? Global : Typed;
     namespace JSX {
         interface IntrinsicElements {
-            'combo-box': ComboboxElementAttributes;
-            'box-option': ComboboxOptionElementAttributes;
-            'box-tag': ComboboxTagElementAttributes;
+            'combo-box': ComboboxIntrinsicElement<ComboboxElementAttributes, import('react').ClassAttributes<HTMLComboboxElement> & ComboboxHTMLAttributes<HTMLComboboxElement>>;
+            'box-option': ComboboxIntrinsicElement<ComboboxOptionElementAttributes, import('react').ClassAttributes<HTMLComboboxOptionElement> & ComboboxOptionHTMLAttributes<HTMLComboboxOptionElement>>;
+            'box-tag': ComboboxIntrinsicElement<ComboboxTagElementAttributes, import('react').ClassAttributes<HTMLComboboxTagElement> & ComboboxTagHTMLAttributes<HTMLComboboxTagElement>>;
         }
     }
 }

package/dist/cjs/index.js

@@ -14,4 +14,15 @@ 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);
+/**
+ * The `<combo-box>` constructor, typed the way lib.dom types built-in elements
+ * (`interface HTMLSelectElement` + `declare var HTMLSelectElement: { prototype; new() }`):
+ * the same `HTMLComboboxElement` type is what `document.createElement('combo-box')`,
+ * `querySelector('combo-box')`, `event.target`, refs and `instanceof HTMLComboboxElement` give.
+ *
+ * Runtime-wise this is the very same class object that `export *` exported before.
+ */
+exports.HTMLComboboxElement = HTML_combobox_element_js_1.HTMLComboboxElement;

package/dist/esm/index.js

@@ -1 +1,11 @@
+import { HTMLComboboxElement as ComboboxElementClass } from './combobox/HTML.combobox.element.js';
 export * from './combobox/index.js';
+/**
+ * The `<combo-box>` constructor, typed the way lib.dom types built-in elements
+ * (`interface HTMLSelectElement` + `declare var HTMLSelectElement: { prototype; new() }`):
+ * the same `HTMLComboboxElement` type is what `document.createElement('combo-box')`,
+ * `querySelector('combo-box')`, `event.target`, refs and `instanceof HTMLComboboxElement` give.
+ *
+ * Runtime-wise this is the very same class object that `export *` exported before.
+ */
+export const HTMLComboboxElement = ComboboxElementClass;

package/dist/types/index.d.ts

@@ -1,13 +1,31 @@
+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';
+/**
+ * The `<combo-box>` constructor, typed the way lib.dom types built-in elements
+ * (`interface HTMLSelectElement` + `declare var HTMLSelectElement: { prototype; new() }`):
+ * the same `HTMLComboboxElement` type is what `document.createElement('combo-box')`,
+ * `querySelector('combo-box')`, `event.target`, refs and `instanceof HTMLComboboxElement` give.
+ *
+ * Runtime-wise this is the very same class object that `export *` exported before.
+ */
+export declare const HTMLComboboxElement: Omit<typeof ComboboxElementClass, 'prototype'> & {
+    prototype: HTMLComboboxElement;
+    new (): HTMLComboboxElement;
+};
 interface HTMLComboboxTagElement extends HTMLElement {
 }
 interface HTMLComboboxOptionElement extends HTMLOptionElement {
     value: string;
     label: string;
 }
-interface HTMLComboboxElement extends HTMLSelectElement {
+export 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
      *
@@ -45,11 +63,11 @@ interface HTMLComboboxElement extends HTMLSelectElement {
      * */
     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<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 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<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 {
@@ -62,6 +80,12 @@ interface ComboboxEventMap extends HTMLElementEventMap {
     "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,6 +133,10 @@ 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 {
     value: string;
@@ -173,29 +201,45 @@ declare global {
     }
 }
 declare module 'react' {
-    namespace JSX {
-        interface IntrinsicElements {
-            'combo-box': ComboboxElementAttributes;
-            'box-option': ComboboxOptionElementAttributes;
-            'box-tag': ComboboxTagElementAttributes;
-        }
+    /** A React event whose `target` is the element (events from the shadow DOM are retargeted to it). */
+    type ComboboxSyntheticEvent<T, E extends globalThis.Event = globalThis.Event> = import('react').SyntheticEvent<T, E> & {
+        target: EventTarget & T;
+    };
+    type ComboboxBaseHTMLAttributes<T> = import('react').HTMLAttributes<T>;
+    type ComboboxBaseHostAttributes<T> = Omit<import('react').HTMLAttributes<T>, 'onInput'>;
+    interface ComboboxHTMLAttributes<T> extends ComboboxBaseHostAttributes<T>, ComboboxJsxAttributes {
+        class?: string | undefined;
+        /** The user changed the selection (`event.target.value` is the new value). */
+        onChange?: import('react').EventHandler<ComboboxSyntheticEvent<T>> | undefined;
+        /** The user typed in the search field (`event.target.query`); `nativeEvent` is its InputEvent. */
+        onInput?: import('react').EventHandler<ComboboxSyntheticEvent<T, globalThis.InputEvent>> | undefined;
+        onInvalid?: import('react').EventHandler<ComboboxSyntheticEvent<T>> | 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;
     }
-}
-declare module 'react/jsx-runtime' {
-    namespace JSX {
-        interface IntrinsicElements {
-            'combo-box': ComboboxElementAttributes;
-            'box-option': ComboboxOptionElementAttributes;
-            'box-tag': ComboboxTagElementAttributes;
-        }
+    interface ComboboxOptionHTMLAttributes<T> extends ComboboxBaseHTMLAttributes<T>, ComboboxOptionJsxAttributes {
+        class?: string | undefined;
     }
-}
-declare module 'react/jsx-dev-runtime' {
+    interface ComboboxTagHTMLAttributes<T> extends ComboboxBaseHTMLAttributes<T> {
+        class?: string | undefined;
+    }
+    /**
+     * @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 (catch-all `on*`,
+     * native event types): with React 18 types the global entries are kept as they are.
+     * @types/react 19 has no global JSX namespace: React.JSX gets React-typed props.
+     * (React 18 types declare the HTML elements in the global namespace, React 19 types don't.)
+     */
+    type ComboboxIntrinsicElement<Global, Typed> = globalThis.JSX.IntrinsicElements extends {
+        div: unknown;
+    } ? Global : Typed;
     namespace JSX {
         interface IntrinsicElements {
-            'combo-box': ComboboxElementAttributes;
-            'box-option': ComboboxOptionElementAttributes;
-            'box-tag': ComboboxTagElementAttributes;
+            'combo-box': ComboboxIntrinsicElement<ComboboxElementAttributes, import('react').ClassAttributes<HTMLComboboxElement> & ComboboxHTMLAttributes<HTMLComboboxElement>>;
+            'box-option': ComboboxIntrinsicElement<ComboboxOptionElementAttributes, import('react').ClassAttributes<HTMLComboboxOptionElement> & ComboboxOptionHTMLAttributes<HTMLComboboxOptionElement>>;
+            'box-tag': ComboboxIntrinsicElement<ComboboxTagElementAttributes, import('react').ClassAttributes<HTMLComboboxTagElement> & ComboboxTagHTMLAttributes<HTMLComboboxTagElement>>;
         }
     }
 }

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "html-combobox-element",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "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",