html-combobox-element 0.0.5 → 0.0.7

package/dist/types/combobox/HTML.combobox.element.d.ts

@@ -1,7 +1,9 @@
 import { HTMLComboboxOptionElement } from './HTML.combobox.option.element.js';
+import { HTMLComboboxOptionsCollection } from './HTML.combobox.options.collection.js';
 export declare class HTMLComboboxElement extends HTMLElement {
     #private;
     static OWN_IDL: Set<string>;
+    static observedAttributes: string[];
     static observerOptions: {
         childList: boolean;
     };
@@ -9,6 +11,11 @@ export declare class HTMLComboboxElement extends HTMLElement {
     static formAssociated: boolean;
     shadowRoot: ShadowRoot;
     constructor();
+    /** Texts used only by assistive technology, override them to localize. */
+    static get strings(): {
+        clearAll: string;
+        removeTag: string;
+    };
     connectedCallback(): void;
     insertBefore: <T extends Node>(node: T, referenceNode: Node | null) => T;
     appendChild: <T extends Node>(node: T) => T;
@@ -19,8 +26,9 @@ export declare class HTMLComboboxElement extends HTMLElement {
     replaceChild: <T extends Node>(newChild: Node, oldChild: T) => T;
     get changed(): boolean;
     disconnectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
     formResetCallback(): void;
-    formDisabledCallback(): void;
+    formDisabledCallback(disabled: boolean): void;
     get valueAsArray(): string[];
     get query(): string;
     set query(value: string);
@@ -37,22 +45,41 @@ export declare class HTMLComboboxElement extends HTMLElement {
     get form(): HTMLFormElement;
     get labels(): NodeList;
     get length(): number;
+    /** Like `select.length = n`: appends blank options, or removes the last ones */
+    set length(value: number);
     get multiple(): boolean;
     set multiple(value: boolean);
+    /** The options, as a live `HTMLOptionsCollection`-like list (like `select.options`) */
+    get options(): HTMLComboboxOptionsCollection;
     get required(): boolean;
     set required(value: boolean);
+    /** Index of the first selected option, or -1. Setting it selects only that option. */
+    get selectedIndex(): number;
+    set selectedIndex(value: number);
     get selectedOptions(): NodeListOf<HTMLComboboxOptionElement>;
     get type(): "select-multiple" | "select-one";
     get validationMessage(): string;
     get validity(): ValidityState;
     get willValidate(): boolean;
-    get value(): string;
-    set value(value: string);
-    checkValidity(): void;
+    get value(): string | null | undefined;
+    set value(value: string | null | undefined);
+    /** Like `select.add()`: inserts an option or optgroup before `before` (an element or an index), or at the end */
+    add(element: HTMLComboboxOptionElement | HTMLOptGroupElement, before?: HTMLElement | number | null): void;
+    checkValidity(): boolean;
     item(index: number): HTMLComboboxOptionElement;
-    reportValidity(): void;
+    /** The first option whose `id` or `name` attribute is `name` */
+    namedItem(name: string): HTMLComboboxOptionElement;
+    /**
+     * Overloaded like `select.remove()`: without an argument removes the combobox itself
+     * (`Element.remove()`), with an index removes that option.
+     */
+    remove(): void;
+    remove(index: number): void;
+    reportValidity(): boolean;
     setCustomValidity(message: string): void;
     showPicker(): void;
+    /** Closes the dropdown, if open */
+    hidePicker(): void;
     setAttribute(name: string, value: any): void;
     removeAttribute(name: string): void;
     static loadCssFromUrls(urls: string[]): void;

package/dist/types/combobox/HTML.combobox.option.element.d.ts

@@ -1,24 +1,45 @@
+/**
+ * The `<option>` of `<combo-box>`.
+ *
+ * The browser only knows what `selected`/`disabled` mean on a native `<option>`, so the role and
+ * both states are set through ElementInternals, and mirrored as `role`, `aria-selected` and
+ * `aria-disabled` attributes. Internals are invisible from outside the element, so the attributes
+ * are what tools reading the DOM (Playwright's getByRole, Testing Library, axe) can see.
+ * Both say the same thing; for the browser an attribute takes precedence over internals.
+ *
+ * Attributes and properties:
+ * - Setters (and the setAttribute/removeAttribute overrides that route to them) only normalize
+ *   the value and write the attribute.
+ * - attributeChangedCallback applies the side effects (state, ARIA, notifying the combobox).
+ *   It's the one hook the browser calls for every way an attribute can change: the setters,
+ *   the native Element.prototype methods, setAttributeNS/setAttributeNode, DevTools, and other
+ *   JavaScript worlds (test runners, extensions) that can't see this class at all.
+ */
 export declare class HTMLComboboxOptionElement extends HTMLElement {
     #private;
     static OWN_IDL: Set<string>;
+    static observedAttributes: string[];
     static EventInit: {
         bubbles: boolean;
         cancelable: boolean;
         composed: boolean;
     };
-    static captureFocus(event: FocusEvent): void;
-    static onNavigate(event: KeyboardEvent): void;
+    constructor();
     connectedCallback(): void;
-    disconnectedCallback(): void;
+    /** Like <option>: the value attribute, or the text when there is none */
     get value(): string;
     set value(value: string);
+    /** Like <option>: the label attribute when present, otherwise the text */
     get label(): string;
     set label(value: string);
+    /** Like <option>: the text content with whitespace stripped and collapsed */
+    get text(): string;
+    set text(value: string);
     get selected(): boolean;
     set selected(value: boolean);
     get disabled(): boolean;
     set disabled(value: boolean);
+    attributeChangedCallback(name: 'selected' | 'disabled', _oldValue: string | null, newValue: string | null): void;
     setAttribute(name: string, value: string): void;
     removeAttribute(name: string): void;
-    toggleAttribute(name: string, force?: boolean): boolean;
 }

package/dist/types/combobox/HTML.combobox.options.collection.d.ts

@@ -0,0 +1,37 @@
+import { HTMLComboboxOptionElement } from './HTML.combobox.option.element.js';
+interface CollectionSource {
+    /** The listbox the options live in (inside the combobox shadow root) */
+    container: () => HTMLElement;
+    /** Live list of the options, in tree order (optgroup children included) */
+    options: () => NodeListOf<HTMLComboboxOptionElement>;
+}
+/**
+ * The `options` of a `<combo-box>`: an implementation of `HTMLOptionsCollection`, whose constructor
+ * is not exposed (it can't be constructed or subclassed). Same behaviour as `select.options`:
+ * it is live, supports `options[i]` (also as an assignment target), `length` (also settable),
+ * `item()`, `namedItem()`, `add()`, `remove()`, `selectedIndex` and iteration.
+ */
+export declare class HTMLComboboxOptionsCollection {
+    #private;
+    [index: number]: HTMLComboboxOptionElement;
+    constructor(source: CollectionSource);
+    get [Symbol.toStringTag](): string;
+    [Symbol.iterator](): IterableIterator<HTMLComboboxOptionElement>;
+    get length(): number;
+    /** Like `select.options.length = n`: appends blank options, or removes the last ones. */
+    set length(value: number);
+    item(index: number): HTMLComboboxOptionElement | null;
+    /** The first option whose `id` or `name` attribute is `name` */
+    namedItem(name: string): HTMLComboboxOptionElement | null;
+    /**
+     * Inserts an option (or optgroup) before `before` (an option/optgroup of this list, or an index),
+     * or at the end. Throws like `select.options.add()`.
+     */
+    add(element: HTMLComboboxOptionElement | HTMLOptGroupElement, before?: HTMLElement | number | null): void;
+    /** Removes the option at `index` (does nothing when out of range) */
+    remove(index: number): void;
+    /** Index of the first selected option, or -1. Setting it selects only that option. */
+    get selectedIndex(): number;
+    set selectedIndex(value: number);
+}
+export {};

package/dist/types/combobox/HTML.combobox.tag.element.d.ts

@@ -1,12 +1,18 @@
+/**
+ * A selected value shown inside `<combo-box>`. The tags are exposed as a list of items,
+ * each with a "Remove …" button when the combobox is `clearable` or `multiple`.
+ */
 export declare class HTMLComboboxTagElement extends HTMLElement {
+    #private;
     static EventInit: {
         bubbles: boolean;
         cancelable: boolean;
         composed: boolean;
     };
+    constructor();
     get value(): string;
     connectedCallback(): void;
     disconnectedCallback(): void;
     static onClearTag(event: Event): void;
-    static captureFocus(event: Event): void;
+    static onControlKeyDown(event: KeyboardEvent): void;
 }

package/dist/types/combobox/index.d.ts

@@ -1 +1,2 @@
 export * from './HTML.combobox.element.js';
+export * from './HTML.combobox.options.collection.js';

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/dist/types/playwright.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Makes Playwright's `selectOption()`, `toHaveValue()` and `toHaveValues()` work on `<combo-box>`
+ * as they do on `<select>`.
+ *
+ * Why it's needed: Playwright runs its page-side code in an isolated JavaScript world. That world
+ * shares the DOM with the page, but not the page's JavaScript: the `<combo-box>` class (its
+ * `options`, `value`, `multiple`, …) doesn't exist there, so Playwright sees a plain element and
+ * refuses it ("Element is not a <select> element").
+ *
+ * What it does: Playwright's custom selector engines registered with `contentScript: true` are
+ * evaluated in that isolated world. This "engine" selects nothing; evaluating it teaches the
+ * isolated world the `<select>` API of `<combo-box>`/`<box-option>`, implemented through the DOM
+ * only (attributes, shadow root). `<combo-box>` reacts to `selected` attributes changed from any
+ * world, so this drives the real component.
+ *
+ * It never touches the page's own world, so the application under test sees no difference.
+ *
+ * @example
+ * // fixtures.ts
+ * import { test as base } from '@playwright/test';
+ * import { registerCombobox } from 'html-combobox-element/playwright';
+ *
+ * export const test = base.extend<{}, { combobox: void }>({
+ *   combobox: [async ({ playwright }, use) => {
+ *     await registerCombobox(playwright.selectors);
+ *     await use();
+ *   }, { scope: 'worker', auto: true }],
+ * });
+ *
+ * // in a test
+ * await page.getByLabel('Fruit').selectOption('banana');
+ * await expect(page.getByLabel('Fruit')).toHaveValue('banana');
+ */
+/** The part of Playwright's `Selectors` this module uses (no dependency on Playwright) */
+export interface SelectorsLike {
+    register(name: string, script: string, options?: {
+        contentScript?: boolean;
+    }): Promise<void>;
+}
+/** Name under which the engine is registered by default */
+export declare const COMBOBOX_ENGINE_NAME = "combobox-select-api";
+/** Source of the selector engine, for `selectors.register(name, source, { contentScript: true })` */
+export declare const comboboxSelectorEngine: string;
+/**
+ * Registers the engine. Call it once per worker, before any page is created
+ * (Playwright requires selector engines to be registered before pages exist).
+ */
+export declare function registerCombobox(selectors: SelectorsLike, name?: string): Promise<void>;

package/dist/types/tsconfig.types.tsbuildinfo

@@ -1 +1 @@
-{"root":["../../src/index.ts","../../src/combobox/boolean.attribute.value.normalizer.ts","../../src/combobox/combobox.markup.ts","../../src/combobox/html.combobox.element.ts","../../src/combobox/html.combobox.option.element.ts","../../src/combobox/html.combobox.tag.element.ts","../../src/combobox/index.ts"],"version":"5.9.3"}
+{"root":["../../src/index.ts","../../src/playwright.ts","../../src/combobox/boolean.attribute.value.normalizer.ts","../../src/combobox/combobox.markup.ts","../../src/combobox/html.combobox.element.ts","../../src/combobox/html.combobox.option.element.ts","../../src/combobox/html.combobox.options.collection.ts","../../src/combobox/html.combobox.tag.element.ts","../../src/combobox/index.ts"],"version":"5.9.3"}

package/package.json

@@ -1,28 +1,37 @@
 {
   "name": "html-combobox-element",
-  "version": "0.0.5",
+  "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",
     "build:combobox": "tsc -b configs/tsconfig.cjs.json configs/tsconfig.esm.json configs/tsconfig.types.json",
     "build": "npm-run-all clean build:combobox",
     "postbuild": "node scripts/fix-dual-package.mjs",
-    "check-types": "tsc --noEmit"
+    "check-types": "tsc --noEmit",
+    "test": "playwright test",
+    "test:ui": "playwright test --ui",
+    "test:types": "playwright test -c playwright.types.config.ts"
   },
   "keywords": [
-    "web-components",
-    "custom elements",
     "combo-box",
-    "combobox"
+    "combobox",
+    "dropdown",
+    "select"
   ],
   "author": "Roman Konstantin",
   "license": "MIT",
   "devDependencies": {
     "@espcom/eslint-config": "latest",
+    "@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",
@@ -30,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",
@@ -54,6 +88,16 @@
         "types": "./dist/cjs/index.d.ts",
         "default": "./dist/cjs/index.js"
       }
+    },
+    "./playwright": {
+      "import": {
+        "types": "./dist/types/playwright.d.ts",
+        "default": "./dist/esm/playwright.js"
+      },
+      "require": {
+        "types": "./dist/cjs/playwright.d.ts",
+        "default": "./dist/cjs/playwright.js"
+      }
     }
   }
 }