html-combobox-element 0.0.4 → 0.0.6

package/README.md

@@ -1,25 +1,154 @@
-# html-combobox-element
-
-The `<combo-box>` is a web component that provides dropdown/combobox functionality through `<select>` fully compatible API. 
+# HTMLComboboxElement
+A customizable, and fully `HTMLSelectElement` compatible web component, with both **dropdown** and **combobox** functionality.
+In other words – the `<select>` and `<selectedcontent>` polyfill.
+
+## Key features
+Like a native `<select>`:
+- It is seamlessly exposed to assistive technology;
+- Fully participate in HTML forms;
+- Is fully controllable by keyboard, including type-ahead;
+- Supports the same CSS pseudo-classes: `:disabled`, `:required`, `:invalid` etc.;
+- Dispatches same events: `change`, `input`, `reset` etc.;
+- Supports `single` and `multiple` modes;
+- Supports `<optgroup>` and has the same markup style.
+
+And – its fully customizable. Itself, its options and chips.
 
 ## Install
 ```sh
 npm install html-combobox-element
 ```
 
+### Register – once in app entry point
 ```ts
-// app entry point
 import 'html-combobox-element';
 ```
-This registers the `<combo-box>`, `<box-option>` and `<box-tag>` custom elements with full TS support for plain DOM/vanilla-JS usage.
+This registers the `<combo-box>`, `<box-option>` and `<box-tag>` custom elements with full TS support.
+
+### Usage
+```html
+<combo-box multiple required>
+  <box-option value="apple" selected>
+    Apple
+  </box-option>
+  
+  <optgroup label="Group">
+    <box-option value="banana" selected>
+      Banana
+    </box-option>
+    <box-option value="cherry">
+      Cherry
+    </box-option>
+  </optgroup>
+</combo-box>
+```
 
-### TypeScript + JSX
-Using `<combo-box>` in JSX or a Vue template needs one extra step, due to a TypeScript limitation: 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`. 
+### Differences from `<select>`
+- In `multiple` mode, the `combobox.value` lists every selected value, where `select.value` gives only the first;
+- In `single`mode, the `<combo-box>` without a selected option stays empty, where a `<select>` selects its first option.
+
+### Events – type: when
+- `change`: The user changed the selection. Once per action, only when the value changed.
+- `input`: The user typed in the search field. It is the field's own `InputEvent`.
+- `close`: The dropdown closed.
+- `search`: The user pressed `Enter` in the search field
+- `reset`: The form was reset
+
+Read from event:
+- `event.target.changed`: tells whether the value differs from when it opened
+- `event.target.query`: tells the search field current text
+- `event.target.query`: the combobox selection
+
+Like native form controls, changes made by script dispatch no `change`.
+Framework bindings that assume `input` means "the value changed" need the `change` event instead.
+
+### Attributes
+All `<select>`'s attributes are supported, and few extra:
+- `filterable`: Displays search field in picker; options are automatically filtered against input value
+- `searchable`: Displays search field in picker; you listen for input events and implement own filter. Usefully for fuzzy search, etc.
+- `placeholder`: The combobox own placeholder, shown when there is no selection
+- `query`: The search field input value
+
+## Options API
+Like `select.options`, `combobox.options` is a live collection too, but a fully compatible polyfill – `HTMLComboboxOptionsCollection`, because `HTMLOptionsCollection` can't be constructed or subclassed.
+The only difference between `select.options` and `combobox.options`, is that `combobox.options` will false on `instanceof HTMLOptionsCollection` check.
+
+## Accessibility
+- Roles and states are set through `ElementInternals`, and mirrored as `role` and `aria`attributes, so tools that read the DOM can see it too.
+- The host itself takes focus, so screen readers announce the combobox with its label and value.
+- The arrow keys, Home/End, PageUp/PageDown, Enter, Space, Escape and type-ahead work as in the [select-only combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-select-only/).
+- Name it with a `<label>`, `aria-label` or `aria-labelledby`.
+- With `searchable` or `filterable` attributes, the popup is a `dialog` holding the search field and the listbox.
+- With `clearable` and/or `multiple` attribute, the selected values are a list, each with a "Remove <OptionLabel>" button. Those texts can be localized:
+```ts
+import { HTMLComboboxElement } from 'html-combobox-element';
 
-This isn't specific to this package; it affects any library adding custom elements to `JSX.IntrinsicElements` under the modern automatic JSX runtime.
+HTMLComboboxElement.strings.removeTag = 'Удалить';        // "Удалить Банан"
+HTMLComboboxElement.strings.clearAll = 'Очистить выбор';
+```
 
-So, in addition to `import 'html-combobox-element'`, create and include one small file tsconfig.json, with the snippet for your framework: 
+### Example of produced accessibility tree in Chrome
+```
+combobox "Fruit"  value="Banana"  expanded=true  hasPopup=listbox  controls=…
+  listbox                         (multiselectable with `multiple`)
+    option "Apple"   selected=false
+    option "Banana"  selected=true
+    option "Cherry"  disabled=true
+```
+
+### Known Chrome limitation 
+Chrome does not expose the value of a disabled `<combo-box>`, because it computes the value of an ARIA combobox only while it is focusable.
+
+## Testing with Playwright
+Playwright's `getByRole()` / `ariaSnapshot()` and Testing Library's `*ByRole` work:
+```ts
+await page.getByRole('combobox').focus();
+await page.getByRole('option', { name: 'Cherry' }).click();
+await expect(page.getByRole('option', { selected: true })).toHaveText('Cherry');
+```
+
+Playwright's `selectOption()`, `toHaveValue()`, `toHaveValues()` and `getByLabel()` work on `<combo-box>` like on `<select>` once you register in your fixtures the helper from `html-combobox-element/playwright`:
+```ts
+// 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 }],
+});
+export { expect } from '@playwright/test';
+```
+
+```ts
+// any.spec.ts
+import { test, expect } from './fixtures';
+
+test('pick a fruit', async ({ page }) => {
+  await page.getByLabel('Fruit').selectOption('banana'); // by value or label
+  await page.getByLabel('Fruits').selectOption(['apple', 'cherry']);
+  await expect(page.getByLabel('Fruit')).toHaveValue('banana');
+  await expect(page.getByLabel('Fruits')).toHaveValues(['apple', 'cherry']);
+});
+```
+
+### Why helper is needed 
+Playwright runs its own page-side code in an **isolated** JavaScript world, 
+which shares the DOM with your page _but not its JavaScript_, so the `HTMLComboboxElement` class doesn't exist there. 
+The helper registers a selector engine with `contentScript: true`, which is the Playwright's public way to run code in that world. 
+That teaches it the `<select>` API of `<combo-box>` through the DOM only. Your page's own JavaScript is **not touched**.
+
+### One difference with screen readers 
+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. 
+
+So, in addition to `import 'html-combobox-element'`, create and include one small file in tsconfig.json, with the snippet for your framework: 
 
 <details>
 <summary><strong>React</strong> (<code>jsx: "react-jsx"</code>)</summary>
@@ -107,17 +236,3 @@ required here (without it the file is treated as a script, not a module, and the
 augmentation breaks Vue's own types).
 
 </details>
-
-### Exported types
-
-- `HTMLComboboxElement`, `HTMLComboboxOptionElement`, `HTMLComboboxTagElement` - element
-  interfaces, also usable via `document.querySelector('combo-box')` etc.
-- `ComboboxEvent`, `ComboboxInputEvent`, `ComboboxFocusEvent` - typed event objects
-  (`event.target` is a properly typed `HTMLComboboxElement`).
-- `ComboboxJsxAttributes`, `ComboboxOptionJsxAttributes` - the component's own props
-  (`value`, `multiple`, `placeholder`, `clearable`, `searchable`, `filterable`,
-  `required`, `disabled`, etc.), framework-independent.
-- `ComboboxElementAttributes`, `ComboboxOptionElementAttributes`,
-  `ComboboxTagElementAttributes` - the above plus common passthrough attributes
-  (`class`/`className`, `style`, `ref`, `children`, `data-*`, `aria-*`, `on*`). These
-  are what the snippets above use for `'combo-box'` / `'box-option'` / `'box-tag'`.

package/dist/cjs/combobox/Combobox.markup.d.ts

@@ -2,6 +2,13 @@ import { HTMLComboboxTagElement } from './HTML.combobox.tag.element.js';
 import { HTMLComboboxOptionElement } from './HTML.combobox.option.element.js';
 export declare class ComboboxMarkup {
     #private;
+    /** 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: string;
+        /** Accessible name prefix of a tag's clear button: "Remove Banana" */
+        removeTag: string;
+    };
     tagsContainer: HTMLDivElement | null;
     optionsContainer: HTMLDivElement | null;
     clearAllButton: HTMLButtonElement | null;
@@ -9,16 +16,30 @@ export declare class ComboboxMarkup {
     placeholder: HTMLDivElement | null;
     searchInput: HTMLInputElement | null;
     tagTemplate: HTMLComboboxTagElement | null;
+    internal: HTMLDivElement | null;
+    valueText: HTMLSpanElement | null;
+    /** Set by the host when it (or its fieldset) is disabled. */
+    disabled: boolean;
     constructor(shadowRoot: ShadowRoot, internals: ElementInternals);
     connect(): void;
     onHostConnected(): void;
     disconnect(): void;
     setPlaceholder(value: string): void;
     setInputValue(value: string): void;
-    onClearAllFocusOut: (event: FocusEvent) => void;
+    /** The combobox value exposed to assistive technology is the text of the selected tags. */
+    syncValueText: () => void;
+    tagLabel(tag: HTMLComboboxTagElement): string;
+    static optionLabel(option: HTMLComboboxOptionElement): string;
     onClickOutside: (ev: MouseEvent) => void;
     sort(query: string): void;
     get options(): NodeListOf<HTMLComboboxOptionElement>;
+    /** Options reachable with the keyboard: not disabled (itself or by its optgroup) and not filtered out. */
+    get navigableOptions(): HTMLComboboxOptionElement[];
+    static isOptionDisabled(option: HTMLComboboxOptionElement): boolean;
+    get hasSearch(): boolean;
+    get expanded(): boolean;
+    /** Moves focus to the host without reopening the popup. */
+    focusHost(): void;
     getTagControl(tag: HTMLComboboxTagElement): HTMLButtonElement;
     setDropdownPosition(): void;
     showDropdown(): void;

package/dist/cjs/combobox/Combobox.markup.js

@@ -3,6 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ComboboxMarkup = void 0;
 const HTML_combobox_tag_element_js_1 = require("./HTML.combobox.tag.element.js");
 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;
@@ -12,30 +19,37 @@ 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);
@@ -45,13 +59,20 @@ 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) {
@@ -59,20 +80,31 @@ 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;
@@ -99,6 +131,30 @@ 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"]');
     }
@@ -126,10 +182,15 @@ 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 {
@@ -138,9 +199,25 @@ 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";
@@ -149,10 +226,17 @@ 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;
@@ -184,16 +268,21 @@ 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]');
@@ -214,9 +303,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;
@@ -273,7 +377,6 @@ ${urls.map(url => `@import "${url}";`)}
   box-option {
     display: flex;
     border-radius: inherit;
-    content-visibility: auto;
     cursor: pointer;
     padding: inherit;
     padding-inline: .5lh;
@@ -283,6 +386,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;
@@ -417,21 +537,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 />
-  <div part="options" id='options'></div>
+  <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>
 `;

package/dist/cjs/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;