html-combobox-element 0.0.4 → 0.0.6

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 />
-  <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>
 `;