html-combobox-element 0.0.5 → 0.0.6

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/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,6 +1,6 @@
 {
   "name": "html-combobox-element",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "The combo-box web-component & customizable select polyfill",
   "type": "module",
   "scripts": {
@@ -9,18 +9,21 @@
     "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"
   },
   "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",
     "c8": "10.1.2",
@@ -54,6 +57,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"
+      }
     }
   }
 }