html-combobox-element 0.0.5 → 0.0.7

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/cjs/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/cjs/playwright.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * 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');
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.comboboxSelectorEngine = exports.COMBOBOX_ENGINE_NAME = void 0;
+exports.registerCombobox = registerCombobox;
+/** Name under which the engine is registered by default */
+exports.COMBOBOX_ENGINE_NAME = 'combobox-select-api';
+// Evaluated inside Playwright's isolated world: must be self-contained (it's sent as source text).
+function installComboboxSelectApi() {
+    const engine = { query: () => null, queryAll: () => [] };
+    // Playwright evaluates engines in the page's own world too: never patch there. Unlike the page,
+    // Chrome's isolated worlds have no custom element registry.
+    if (globalThis.customElements)
+        return engine;
+    const marker = Symbol.for('html-combobox-element/playwright');
+    if (globalThis[marker])
+        return engine;
+    globalThis[marker] = true;
+    const isCombobox = (el) => !!el && el.localName === 'combo-box';
+    const isOption = (el) => !!el && el.localName === 'box-option';
+    const text = (option) => (option.textContent || '').replace(/[\t\n\f\r ]+/g, ' ').trim();
+    // Same rules as HTMLComboboxOptionElement (and <option>)
+    const optionValue = (option) => option.getAttribute('value') ?? text(option);
+    const optionLabel = (option) => option.getAttribute('label') ?? text(option);
+    const optionsOf = (combobox) => Array.from(combobox.shadowRoot?.querySelectorAll('box-option') ?? []);
+    // Playwright checks `nodeName === 'SELECT'` before using the <select> API
+    const nodeName = Object.getOwnPropertyDescriptor(Node.prototype, 'nodeName');
+    Object.defineProperty(Node.prototype, 'nodeName', {
+        configurable: true,
+        get() { return isCombobox(this) ? 'SELECT' : nodeName.get.call(this); },
+    });
+    // On HTMLElement.prototype, so elements with their own native property (<select>, <input>,
+    // <option>, …) are unaffected; for every other element the getters return undefined as before.
+    Object.defineProperties(HTMLElement.prototype, {
+        options: {
+            configurable: true,
+            get() { return isCombobox(this) ? optionsOf(this) : undefined; },
+        },
+        selectedOptions: {
+            configurable: true,
+            get() { return isCombobox(this) ? optionsOf(this).filter((o) => o.hasAttribute('selected')) : undefined; },
+        },
+        multiple: {
+            configurable: true,
+            get() { return isCombobox(this) ? this.hasAttribute('multiple') : undefined; },
+        },
+        // For getByLabel(): <label for> / wrapping <label> (label.control is native, so it works here)
+        labels: {
+            configurable: true,
+            get() {
+                if (!isCombobox(this))
+                    return undefined;
+                return Array.from(this.ownerDocument.querySelectorAll('label')).filter((label) => label.control === this);
+            },
+        },
+        label: {
+            configurable: true,
+            get() { return isOption(this) ? optionLabel(this) : undefined; },
+        },
+        selected: {
+            configurable: true,
+            get() { return isOption(this) ? this.hasAttribute('selected') : undefined; },
+            set(value) { if (isOption(this))
+                this.toggleAttribute('selected', !!value); },
+        },
+        value: {
+            configurable: true,
+            get() {
+                if (isOption(this))
+                    return optionValue(this);
+                if (isCombobox(this))
+                    return optionsOf(this).filter((o) => o.hasAttribute('selected')).map(optionValue).join(',');
+                return undefined;
+            },
+            // Like combobox.value = x: null/undefined clear, comma-separated values select several
+            set(value) {
+                if (!isCombobox(this))
+                    return;
+                const values = value == null ? [] : String(value).split(',');
+                for (const option of optionsOf(this))
+                    option.toggleAttribute('selected', values.includes(optionValue(option)));
+            },
+        },
+    });
+    return engine;
+}
+/** Source of the selector engine, for `selectors.register(name, source, { contentScript: true })` */
+exports.comboboxSelectorEngine = `(${installComboboxSelectApi.toString()})()`;
+/**
+ * Registers the engine. Call it once per worker, before any page is created
+ * (Playwright requires selector engines to be registered before pages exist).
+ */
+function registerCombobox(selectors, name = exports.COMBOBOX_ENGINE_NAME) {
+    return selectors.register(name, exports.comboboxSelectorEngine, { contentScript: true });
+}

package/dist/cjs/tsconfig.cjs.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/dist/esm/combobox/Combobox.markup.js

@@ -1,5 +1,12 @@
 import { HTMLComboboxTagElement } from './HTML.combobox.tag.element.js';
 export class ComboboxMarkup {
+    /** Texts used only by assistive technology. Override them to localize, e.g. `HTMLComboboxElement.strings.clearAll = 'Очистить'` */
+    static strings = {
+        /** Accessible name of the clear-all button */
+        clearAll: 'Clear selection',
+        /** Accessible name prefix of a tag's clear button: "Remove Banana" */
+        removeTag: 'Remove',
+    };
     #shadowRoot;
     #internals;
     tagsContainer = null;
@@ -9,30 +16,37 @@ export class ComboboxMarkup {
     placeholder = null;
     searchInput = null;
     tagTemplate = null;
+    internal = null;
+    valueText = null;
     #rso;
+    #tagsObserver;
     #hostWidth = 0;
     #hostHeight = 0;
     #hostTop = 0;
+    /** Set while focus is moved back to the host programmatically, so that focusin doesn't reopen the popup. */
+    #suppressOpen = false;
+    /** Set by the host when it (or its fieldset) is disabled. */
+    disabled = false;
     constructor(shadowRoot, internals) {
         this.#shadowRoot = shadowRoot;
         this.#internals = internals;
-        window.addEventListener('click', this.onClickOutside);
-        this.#shadowRoot.host.addEventListener('focusin', this.onFocusIn);
-        this.#shadowRoot.host.addEventListener('focusout', this.onFocusOut);
+        this.#internals.ariaExpanded = 'false';
         this.#rso = new ResizeObserver(this.#onDimensionsChanges);
+        this.#tagsObserver = new MutationObserver(this.syncValueText);
     }
     connect() {
         const placeholder = this.#shadowRoot.host.getAttribute('placeholder') || `Выбрать`;
         this.tagsContainer = this.#shadowRoot.querySelector('#tags');
-        this.#rso.observe(this.#shadowRoot.host, { box: 'border-box' });
+        this.internal = this.#shadowRoot.querySelector('#internal');
+        this.valueText = this.#shadowRoot.querySelector('#value');
         this.optionsContainer = this.#shadowRoot.querySelector('[part*="options"]');
         this.clearAllButton = this.#shadowRoot.querySelector('[part*="clear-all"]');
-        this.clearAllButton?.addEventListener('focusout', this.onClearAllFocusOut);
+        this.clearAllButton?.setAttribute('aria-label', ComboboxMarkup.strings.clearAll);
         this.dropdown = this.#shadowRoot.querySelector('#dropdown');
         this.placeholder = this.#shadowRoot.querySelector('#placeholder');
         this.placeholder.innerText = placeholder;
         this.searchInput = this.#shadowRoot.querySelector('[part*="search-input"]');
-        this.searchInput.value = this.#shadowRoot.host.getAttribute('query');
+        this.searchInput.value = this.#shadowRoot.host.getAttribute('query') ?? '';
         this.searchInput.style.setProperty('--search-input-placeholder-color', this.placeholder.style.color);
         const innerTemplate = this.#shadowRoot.querySelector('#tag-template');
         const doc = document.importNode(innerTemplate.content, true);
@@ -42,13 +56,20 @@ export class ComboboxMarkup {
         const host = this.#shadowRoot.host;
         const clearable = host.hasAttribute('clearable') || host.hasAttribute('multiple');
         this.tagTemplate.toggleAttribute('visible', clearable);
+        window.addEventListener('click', this.onClickOutside);
+        host.addEventListener('focusin', this.onFocusIn);
+        host.addEventListener('focusout', this.onFocusOut);
+        this.#rso.observe(host, { box: 'border-box' });
+        this.#tagsObserver.observe(this.tagsContainer, { childList: true });
+        this.syncValueText();
     }
     disconnect() {
-        this.#shadowRoot.host.removeEventListener('focusin', this.onFocusIn);
-        this.#shadowRoot.host.removeEventListener('focusout', this.onFocusOut);
-        this.clearAllButton?.removeEventListener('focusout', this.onClearAllFocusOut);
+        const host = this.#shadowRoot.host;
+        host.removeEventListener('focusin', this.onFocusIn);
+        host.removeEventListener('focusout', this.onFocusOut);
         window.removeEventListener('click', this.onClickOutside);
-        this.#rso.unobserve(this.#shadowRoot.host);
+        this.#rso.unobserve(host);
+        this.#tagsObserver.disconnect();
     }
     setPlaceholder(value) {
         if (this.placeholder) {
@@ -56,20 +77,31 @@ export class ComboboxMarkup {
         }
     }
     setInputValue(value) {
-        if (this.searchInput) {
+        // Typing writes the query attribute, which comes back here: don't reset the caret
+        if (this.searchInput && this.searchInput.value !== value) {
             this.searchInput.value = value;
         }
     }
-    onClearAllFocusOut = (event) => {
-        event.preventDefault();
-        event.stopPropagation();
-        if (event.relatedTarget == null) {
-            const host = this.#shadowRoot.host;
-            if (!host.hasAttribute('searchable') && !host.hasAttribute('filterable')) {
-                this.closeDropdown();
-            }
-        }
+    /** The combobox value exposed to assistive technology is the text of the selected tags. */
+    syncValueText = () => {
+        if (!this.valueText || !this.tagsContainer)
+            return;
+        const labels = Array.from(this.tagsContainer.querySelectorAll('box-tag'), (tag) => this.tagLabel(tag));
+        const text = labels.filter(Boolean).join(', ');
+        if (this.valueText.textContent !== text)
+            this.valueText.textContent = text;
+        this.clearAllButton?.toggleAttribute('disabled', labels.length === 0);
     };
+    tagLabel(tag) {
+        const option = tag.value ? this.getOptionByValue(tag.value) : null;
+        if (option)
+            return ComboboxMarkup.optionLabel(option);
+        const label = tag.querySelector('[part*="tag-label"]') ?? tag;
+        return label.textContent?.trim() ?? '';
+    }
+    static optionLabel(option) {
+        return (option.label || option.textContent || option.value || '').trim();
+    }
     onClickOutside = (ev) => {
         if (this.#internals.ariaExpanded !== 'true')
             return;
@@ -96,6 +128,30 @@ export class ComboboxMarkup {
     get options() {
         return this.optionsContainer.querySelectorAll('box-option');
     }
+    /** Options reachable with the keyboard: not disabled (itself or by its optgroup) and not filtered out. */
+    get navigableOptions() {
+        return Array.from(this.options).filter((option) => !ComboboxMarkup.isOptionDisabled(option) && option.style.display !== 'none' && !option.hidden);
+    }
+    static isOptionDisabled(option) {
+        return option.disabled || Boolean(option.closest('optgroup')?.disabled);
+    }
+    get hasSearch() {
+        const host = this.#shadowRoot.host;
+        return host.hasAttribute('searchable') || host.hasAttribute('filterable');
+    }
+    get expanded() {
+        return this.#internals.ariaExpanded === 'true';
+    }
+    /** Moves focus to the host without reopening the popup. */
+    focusHost() {
+        this.#suppressOpen = true;
+        try {
+            this.#shadowRoot.host.focus();
+        }
+        finally {
+            this.#suppressOpen = false;
+        }
+    }
     getTagControl(tag) {
         return tag.querySelector('[part*="clear-tag"]');
     }
@@ -123,10 +179,15 @@ export class ComboboxMarkup {
         dropdown.style.maxHeight = `${Math.max(100, maxHeight)}px`;
     }
     showDropdown() {
-        this.onFocusIn();
+        this.#open();
     }
     onFocusIn = () => {
-        if (this.#internals.ariaExpanded === "true")
+        if (this.#suppressOpen)
+            return;
+        this.#open();
+    };
+    #open() {
+        if (this.disabled || this.expanded)
             return;
         this.#hostTop = this.#shadowRoot.host.getBoundingClientRect().top;
         try {
@@ -135,9 +196,25 @@ export class ComboboxMarkup {
         }
         catch (e) {
             this.#internals.ariaExpanded = "false";
+            return;
         }
-    };
+        // When the combobox has focus and the dialog opens, move into the search field (if it asks
+        // for autofocus). The popover's own autofocus doesn't apply when the host is the focus target,
+        // and focusing synchronously from focusin would be undone by the host's own focus, so defer.
+        if (this.hasSearch && this.searchInput?.hasAttribute('autofocus')) {
+            setTimeout(() => {
+                const host = this.#shadowRoot.host;
+                const hostFocused = document.activeElement === host && !this.#shadowRoot.activeElement;
+                if (hostFocused && this.expanded && this.searchInput?.hasAttribute('autofocus'))
+                    this.searchInput.focus();
+            });
+        }
+    }
     closeDropdown() {
+        if (!this.dropdown.matches(':popover-open')) {
+            this.#internals.ariaExpanded = "false";
+            return;
+        }
         try {
             this.dropdown.hidePopover();
             this.#internals.ariaExpanded = "false";
@@ -146,10 +223,17 @@ export class ComboboxMarkup {
             this.#internals.ariaExpanded = "true";
         }
     }
+    // Focus moving between the host and its own shadow content is not "leaving" the combobox.
+    // Wait for the focus to settle, then close only if it is really gone.
     onFocusOut = () => {
-        if (this.#internals.ariaExpanded !== "true")
+        if (!this.expanded)
             return;
-        this.closeDropdown();
+        setTimeout(() => {
+            const host = this.#shadowRoot.host;
+            if (document.activeElement === host || host.matches(':focus-within'))
+                return;
+            this.closeDropdown();
+        });
     };
     createAndAppendTag(option) {
         const value = option.value;
@@ -181,16 +265,21 @@ export class ComboboxMarkup {
             button = tag.querySelector('[part="clear-tag"]');
         }
         button?.setAttribute('value', value);
+        if (button && !button.hasAttribute('aria-label') && !button.hasAttribute('aria-labelledby')) {
+            button.setAttribute('aria-label', `${ComboboxMarkup.strings.removeTag} ${ComboboxMarkup.optionLabel(option)}`);
+        }
         tag.setAttribute('value', value);
         this.tagsContainer.appendChild(tag);
-        this.clearAllButton?.removeAttribute('disabled');
+        this.syncValueText();
         return button;
     }
     getTagByValue(value) {
-        return this.tagsContainer.querySelector(`box-tag[value="${value}"]`);
+        return this.tagsContainer.querySelector(`box-tag[value="${CSS.escape(value)}"]`);
     }
+    // Compared through the property, not a [value] selector: an option without a value attribute
+    // takes its text as value, like <option>
     getOptionByValue(value) {
-        return this.optionsContainer.querySelector(`box-option[value="${value}"]`);
+        return Array.from(this.options).find((option) => option.value === value) ?? null;
     }
     get selectedOptions() {
         return this.optionsContainer.querySelectorAll('box-option[selected]');
@@ -211,9 +300,24 @@ ${urls.map(url => `@import "${url}";`)}
     position: relative;
     anchor-name: --position;
   }
+
+  :host(:state(disabled)) {
+    pointer-events: none;
+  }
   
   
   
+  /* Carries the accessible value of the combobox (the selected labels), like the
+     displayed text of a native <select>. Visually hidden, the tags show it visually. */
+  #value {
+    position: absolute;
+    inline-size: 1px;
+    block-size: 1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+
   #internal {
     min-block-size: 1lh;
     display: grid;
@@ -270,7 +374,6 @@ ${urls.map(url => `@import "${url}";`)}
   box-option {
     display: flex;
     border-radius: inherit;
-    content-visibility: auto;
     cursor: pointer;
     padding: inherit;
     padding-inline: .5lh;
@@ -280,6 +383,23 @@ ${urls.map(url => `@import "${url}";`)}
     background-color: color-mix(in srgb, Highlight, transparent 70%);
   }
   
+  /* Like <option label="Plum"></option>: an empty option displays its label, while its text and
+     value stay empty. Generated content is part of the option's accessible name. */
+  box-option[label]:empty::before {
+    content: attr(label);
+  }
+
+  box-option[disabled] {
+    color: GrayText;
+    cursor: not-allowed;
+    pointer-events: none;
+  }
+
+  box-option:focus-visible {
+    outline: 1px solid Highlight;
+    outline-offset: -1px;
+  }
+
   box-option[selected] {
     background-color: Highlight;
     cursor: not-allowed;
@@ -414,21 +534,22 @@ ${urls.map(url => `@import "${url}";`)}
   }
  
 </style>
-<div id='internal' part='internal'>
-  <div id="tags" part='tags'></div>
-  <div id="placeholder" part='placeholder' tabindex='0'>Выбрать</div>
-  <button part="clear-all">✕</button>
+<span id="value" part="value"></span>
+<div id='internal' part='internal' role="group">
+  <div id="tags" part='tags' role="list"></div>
+  <div id="placeholder" part='placeholder' aria-hidden="true">Выбрать</div>
+  <button part="clear-all" type="button">✕</button>
 </div>
 
 <div id="dropdown" popover="manual" part='dropdown' >
-  <input placeholder='Поиск' name="search-input" part="search-input" inputmode='search' autofocus />
+  <input placeholder='Поиск' name="search-input" part="search-input" inputmode='search' autocomplete="off" aria-controls="options" aria-autocomplete="list" autofocus />
   <div part="options" id='options' role="listbox"></div>
 </div>
 
 <template id='tag-template'>
   <box-tag>
     <span part="tag-label"></span>
-    <div part="clear-tag" role='button' tabindex='0'>✕</div>
+    <div part="clear-tag" role='button' tabindex='0'><span aria-hidden="true">✕</span></div>
   </box-tag>
 </template>
 `;