html-combobox-element 0.0.2 → 0.0.4

package/README.md

@@ -0,0 +1,123 @@
+# html-combobox-element
+
+The `<combo-box>` is a web component that provides dropdown/combobox functionality through `<select>` fully compatible API. 
+
+## Install
+```sh
+npm install html-combobox-element
+```
+
+```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.
+
+### 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`. 
+
+This isn't specific to this package; it affects any library adding custom elements to `JSX.IntrinsicElements` under the modern automatic JSX runtime.
+
+So, in addition to `import 'html-combobox-element'`, create and include one small file tsconfig.json, with the snippet for your framework: 
+
+<details>
+<summary><strong>React</strong> (<code>jsx: "react-jsx"</code>)</summary>
+
+```ts
+// combo-box.d.ts
+declare module 'react/jsx-runtime' {
+  namespace JSX {
+    interface IntrinsicElements {
+      'combo-box': ComboboxElementAttributes;
+      'box-option': ComboboxOptionElementAttributes;
+      'box-tag': ComboboxTagElementAttributes;
+    }
+  }
+}
+declare module 'react/jsx-dev-runtime' {
+  namespace JSX {
+    interface IntrinsicElements {
+      'combo-box': ComboboxElementAttributes;
+      'box-option': ComboboxOptionElementAttributes;
+      'box-tag': ComboboxTagElementAttributes;
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Preact</strong> (<code>jsx: "react-jsx"</code>, <code>jsxImportSource: "preact"</code>)</summary>
+
+```ts
+// combo-box.d.ts
+declare module 'preact/jsx-runtime' {
+  namespace JSX {
+    interface IntrinsicElements {
+      'combo-box': ComboboxElementAttributes;
+      'box-option': ComboboxOptionElementAttributes;
+      'box-tag': ComboboxTagElementAttributes;
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Solid</strong> (<code>jsx: "preserve"</code>, <code>jsxImportSource: "solid-js"</code>)</summary>
+
+```ts
+// combo-box.d.ts
+declare module 'solid-js/jsx-runtime' {
+  namespace JSX {
+    interface IntrinsicElements {
+      'combo-box': ComboboxElementAttributes;
+      'box-option': ComboboxOptionElementAttributes;
+      'box-tag': ComboboxTagElementAttributes;
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Vue</strong> (SFC <code>&lt;template&gt;</code>, checked via <code>vue-tsc</code>)</summary>
+
+Vue templates aren't JSX, so they're type-checked through `GlobalComponents` instead:
+
+```ts
+// combo-box.d.ts
+declare module 'vue' {
+  export interface GlobalComponents {
+    'combo-box': new () => { $props: ComboboxElementAttributes };
+    'box-option': new () => { $props: ComboboxOptionElementAttributes };
+  }
+}
+
+```
+
+This checks required props and value types for props you pass; like any native custom
+element, Vue still allows extra/unrecognized attributes through (that's expected Vue
+behavior for custom elements, not a gap in this typing). The trailing `export {};` may be 
+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/Boolean.attribute.value.normalizer.d.ts

@@ -0,0 +1,2 @@
+/** Transform invalid (nullish or stringed) values to correct boolean value */
+export declare function toBoolean(value: any): boolean;

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

@@ -0,0 +1,35 @@
+import { HTMLComboboxTagElement } from './HTML.combobox.tag.element.js';
+import { HTMLComboboxOptionElement } from './HTML.combobox.option.element.js';
+export declare class ComboboxMarkup {
+    #private;
+    tagsContainer: HTMLDivElement | null;
+    optionsContainer: HTMLDivElement | null;
+    clearAllButton: HTMLButtonElement | null;
+    dropdown: HTMLDivElement | null;
+    placeholder: HTMLDivElement | null;
+    searchInput: HTMLInputElement | null;
+    tagTemplate: HTMLComboboxTagElement | null;
+    constructor(shadowRoot: ShadowRoot, internals: ElementInternals);
+    connect(): void;
+    onHostConnected(): void;
+    disconnect(): void;
+    setPlaceholder(value: string): void;
+    setInputValue(value: string): void;
+    onClearAllFocusOut: (event: FocusEvent) => void;
+    onClickOutside: (ev: MouseEvent) => void;
+    sort(query: string): void;
+    get options(): NodeListOf<HTMLComboboxOptionElement>;
+    getTagControl(tag: HTMLComboboxTagElement): HTMLButtonElement;
+    setDropdownPosition(): void;
+    showDropdown(): void;
+    onFocusIn: () => void;
+    closeDropdown(): void;
+    onFocusOut: () => void;
+    createAndAppendTag(option: HTMLComboboxOptionElement): HTMLButtonElement;
+    getTagByValue(value: string): HTMLComboboxTagElement;
+    getOptionByValue(value: string): HTMLComboboxOptionElement;
+    get selectedOptions(): NodeListOf<HTMLComboboxOptionElement>;
+    static importCSS(urls: string[]): void;
+    static template: string;
+    static markup: HTMLTemplateElement;
+}

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

@@ -12,36 +12,74 @@ class ComboboxMarkup {
     placeholder = null;
     searchInput = null;
     tagTemplate = null;
-    options;
-    connected = false;
+    #rso;
+    #hostWidth = 0;
+    #hostHeight = 0;
+    #hostTop = 0;
     constructor(shadowRoot, internals) {
         this.#shadowRoot = shadowRoot;
         this.#internals = internals;
-        this.#shadowRoot.host.addEventListener('focus', this.showDropdown);
-        this.#shadowRoot.host.addEventListener('blur', this.hideDropdown);
-        this.#shadowRoot.host.addEventListener('click', this.showDropdown);
-        document.addEventListener('click', this.hideDropdown);
-        document.addEventListener('scroll', this.onPageScroll);
+        window.addEventListener('click', this.onClickOutside);
+        this.#shadowRoot.host.addEventListener('focusin', this.onFocusIn);
+        this.#shadowRoot.host.addEventListener('focusout', this.onFocusOut);
+        this.#rso = new ResizeObserver(this.#onDimensionsChanges);
     }
     connect() {
-        const placeholder = this.#shadowRoot.host.getAttribute('placeholder') || '';
+        const placeholder = this.#shadowRoot.host.getAttribute('placeholder') || `Выбрать`;
         this.tagsContainer = this.#shadowRoot.querySelector('#tags');
+        this.#rso.observe(this.#shadowRoot.host, { box: 'border-box' });
         this.optionsContainer = this.#shadowRoot.querySelector('[part*="options"]');
         this.clearAllButton = this.#shadowRoot.querySelector('[part*="clear-all"]');
+        this.clearAllButton?.addEventListener('focusout', this.onClearAllFocusOut);
         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.placeholder = placeholder;
+        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);
         this.tagTemplate = doc.querySelector('box-tag');
-        this.connected = true;
     }
-    invalidateOptionsCache() {
-        this.options = this.optionsContainer.querySelectorAll('box-option');
+    onHostConnected() {
+        const host = this.#shadowRoot.host;
+        const clearable = host.hasAttribute('clearable') || host.hasAttribute('multiple');
+        this.tagTemplate.toggleAttribute('visible', clearable);
     }
+    disconnect() {
+        this.#shadowRoot.host.removeEventListener('focusin', this.onFocusIn);
+        this.#shadowRoot.host.removeEventListener('focusout', this.onFocusOut);
+        this.clearAllButton?.removeEventListener('focusout', this.onClearAllFocusOut);
+        window.removeEventListener('click', this.onClickOutside);
+        this.#rso.unobserve(this.#shadowRoot.host);
+    }
+    setPlaceholder(value) {
+        if (this.placeholder) {
+            this.placeholder.innerText = value.trim() || `Выбрать`;
+        }
+    }
+    setInputValue(value) {
+        if (this.searchInput) {
+            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();
+            }
+        }
+    };
+    onClickOutside = (ev) => {
+        if (this.#internals.ariaExpanded !== 'true')
+            return;
+        if (ev.target === this.#shadowRoot.host)
+            return;
+        this.closeDropdown();
+    };
     #timer = undefined;
     sort(query) {
         clearTimeout(this.#timer);
@@ -56,68 +94,63 @@ class ComboboxMarkup {
                 }
             });
             this.dropdown.scrollTo({ top: 0, behavior: 'smooth' });
-        }, 200);
+        }, 400);
     }
-    disconnect() {
-        this.#shadowRoot.host.removeEventListener('focus', this.showDropdown);
-        this.#shadowRoot.host.removeEventListener('blur', this.hideDropdown);
-        this.#shadowRoot.host.removeEventListener('click', this.showDropdown);
-        document.removeEventListener('click', this.hideDropdown);
-        document.removeEventListener('scroll', this.onPageScroll);
-        this.connected = false;
+    get options() {
+        return this.optionsContainer.querySelectorAll('box-option');
+    }
+    getTagControl(tag) {
+        return tag.querySelector('[part*="clear-tag"]');
     }
-    onPageScroll = () => {
-        if (this.dropdown.matches(':popover-open')) {
-            this.setDropdownPosition(this.#shadowRoot.host.getBoundingClientRect());
+    #onDimensionsChanges = (entries) => {
+        const entry = entries[0];
+        if (entry) {
+            this.#hostWidth = entry.borderBoxSize[0].inlineSize;
+            this.#hostHeight = entry.borderBoxSize[0].blockSize;
         }
+        this.setDropdownPosition();
     };
-    setDropdownPosition(rect) {
+    setDropdownPosition() {
         const dropdown = this.dropdown;
         const vh = window.innerHeight;
-        const sh = rect.height;
-        const sy = rect.top;
-        if (sy < (vh - vh / 3)) {
-            dropdown.style.top = sh + sy + 'px';
-            dropdown.style.bottom = 'unset';
-            dropdown.style.transform = `unset`;
-        }
-        else {
-            dropdown.style.top = sh + sy + 'px';
-            dropdown.style.bottom = 'unset';
-            dropdown.style.transform = `translateY(calc(-1 * calc(100% + ${sh}px)))`;
-        }
-        dropdown.style.left = rect.left + 'px';
-        dropdown.style.width = rect.width + 'px';
-        dropdown.style.maxHeight = '50vh';
+        const sh = this.#hostHeight;
+        const sy = this.#hostTop;
+        // Calculate available space below and above
+        const spaceBelow = vh - (sy + sh);
+        const spaceAbove = sy;
+        // Determine if dropdown should go below or above
+        const shouldGoBelow = spaceBelow >= spaceAbove;
+        // Set dropdown to max 50vh or available space, whichever is smaller
+        const maxHeight = Math.min(50 * vh / 100, shouldGoBelow ? spaceBelow - 10 : spaceAbove - 10);
+        dropdown.style.width = this.#hostWidth + 'px';
+        dropdown.style.maxHeight = `${Math.max(100, maxHeight)}px`;
+    }
+    showDropdown() {
+        this.onFocusIn();
     }
-    showDropdown = () => {
+    onFocusIn = () => {
+        if (this.#internals.ariaExpanded === "true")
+            return;
+        this.#hostTop = this.#shadowRoot.host.getBoundingClientRect().top;
         try {
-            this.setDropdownPosition(this.#shadowRoot.host.getBoundingClientRect());
-            this.dropdown.style.display = 'flex';
             this.dropdown.showPopover();
             this.#internals.ariaExpanded = "true";
-            if (this.tagsContainer?.children.length === 0) {
-                this.searchInput?.focus();
-            }
-            this.placeholder.innerText = '';
         }
-        catch {
+        catch (e) {
             this.#internals.ariaExpanded = "false";
         }
     };
     closeDropdown() {
         try {
             this.dropdown.hidePopover();
-            this.dropdown.style.display = 'none';
             this.#internals.ariaExpanded = "false";
-            this.placeholder.innerText = this.#shadowRoot.host.getAttribute('placeholder');
         }
         catch (e) {
             this.#internals.ariaExpanded = "true";
         }
     }
-    hideDropdown = (event) => {
-        if (event.composedPath().includes(this.#shadowRoot.host))
+    onFocusOut = () => {
+        if (this.#internals.ariaExpanded !== "true")
             return;
         this.closeDropdown();
     };
@@ -147,12 +180,13 @@ class ComboboxMarkup {
             const template = this.tagTemplate;
             tag = template.cloneNode(true);
             const label = tag.querySelector('[part="tag-label"]');
-            label.textContent = option.textContent;
+            label.textContent = option.label || option.textContent;
             button = tag.querySelector('[part="clear-tag"]');
         }
         button?.setAttribute('value', value);
         tag.setAttribute('value', value);
         this.tagsContainer.appendChild(tag);
+        this.clearAllButton?.removeAttribute('disabled');
         return button;
     }
     getTagByValue(value) {
@@ -162,8 +196,7 @@ class ComboboxMarkup {
         return this.optionsContainer.querySelector(`box-option[value="${value}"]`);
     }
     get selectedOptions() {
-        return this.optionsContainer
-            .querySelectorAll('box-option[selected]');
+        return this.optionsContainer.querySelectorAll('box-option[selected]');
     }
     static importCSS(urls) {
         ComboboxMarkup.template = ComboboxMarkup.template.replace(':host {', `
@@ -177,35 +210,64 @@ ${urls.map(url => `@import "${url}";`)}
   :host {
     font-size: inherit;
     font-family: inherit;
+    display: flow-root;
+    position: relative;
+    anchor-name: --position;
+  }
+  
+  
+  
+  #internal {
+    min-block-size: 1lh;
     display: grid;
     grid-template-columns: minmax(0, max-content) 1fr;
     align-items: center;
     gap: 1px;
-    position: relative;
+    border-radius: inherit;
   }
   
-  :host([multiple]) {
+  :host([multiple]) #internal {
     grid-template-columns: minmax(0, max-content) 1fr auto;
   }
 
   #dropdown {
+    contain: layout style paint;
     inset: unset;
     margin: 0;
+    /*position: absolute;*/
     box-sizing: border-box;
     overflow-y: scroll;
     flex-direction: column;
     border-radius: inherit;
     border-color: ButtonFace;
     border-width: inherit;
+    background-color: Canvas;
+    outline: none;
+    display: none;
+    top: calc(anchor(bottom) + 2px);
+    left: anchor(left);
+    position-anchor: --position;
+    position-try: normal flip-block;
   }
   
-  [part="options"] {
+  #dropdown:popover-open {
+    display: flex;
+  }
+  
+  #dropdown::-webkit-scrollbar {
+    display: none;
+  }
+  
+  #options {
     display: flex;
     flex-direction: column;
     justify-content: start;
     gap: 2px;
-    padding-block: .5rem;
-    border-radius: inherit;
+    border-radius: inherit;  
+  }
+  
+  :host([filterable]) #options, :host([searchable]) #options {
+    padding-top: .5rem;
   }
   
   box-option {
@@ -213,8 +275,8 @@ ${urls.map(url => `@import "${url}";`)}
     border-radius: inherit;
     content-visibility: auto;
     cursor: pointer;
-    padding-inline: 2px;
-    padding-block: 1px;
+    padding: inherit;
+    padding-inline: .5lh;
   }
   
   box-option:hover {
@@ -227,29 +289,27 @@ ${urls.map(url => `@import "${url}";`)}
     pointer-events: none;
   }
   
-  [part="search-input"] { 
+  #dropdown > [part="search-input"] { 
     display: none;
     position: sticky;
     top: 0;
     z-index: 2;
-    border-radius: inherit;
-    border-style: inherit;
-    border-width: inherit;
-    border-color: inherit;
-    padding: inherit;
+    font-size: inherit;
+    outline: inherit;
   }
   
-  :host([searchable]) [part="search-input"],
-  :host([filterable]) [part="search-input"] {
-    display: flex;
+  :host([searchable]) #dropdown > [part="search-input"],
+  :host([filterable]) #dropdown > [part="search-input"] {
+    display: flow-root;
   }
   
   #placeholder {
     text-align: left;
     overflow: hidden;
     padding-inline-start: 2px;
-    font-size: smaller;
     color: dimgrey;
+    outline: none;
+    user-select: none;
   }
 
   #tags:not(:empty) + #placeholder {
@@ -266,7 +326,6 @@ ${urls.map(url => `@import "${url}";`)}
     flex-wrap: wrap;
     overflow: hidden;
     gap: 2px;
-    border-radius: inherit;
   }
 
   box-tag {
@@ -275,13 +334,11 @@ ${urls.map(url => `@import "${url}";`)}
     box-sizing: border-box;
     display: flex;
     align-items: center;
-    border-radius: inherit;
-    padding-inline-start: 0.2lh;
-    padding-inline-end: .2rem;
+    padding-inline-start: 0.4lh;
+    padding-inline-end: 0.2lh;
     background-color: transparent;
     gap: 5px;
-    font-size: medium;
-    text-transform: uppercase;
+    border-radius: 1lh;
   }
   
   :host([multiple]) box-tag {
@@ -290,80 +347,99 @@ ${urls.map(url => `@import "${url}";`)}
     max-width: 100%;
   }
 
-  box-tag [part*="tag-label"] {
+  [part*="tag-label"] {
     white-space: nowrap;
     text-overflow: ellipsis;
     overflow: hidden;
     user-select: none;
-    font-size: 95%;
     flex-grow: 1;
   }
   
-  :host([multiple]) box-tag[part*="tag-label"] {
+  :host([multiple]) [part*="tag-label"] {
     flex-grow: unset;
   }
   
-  [part*="clear-tag"], [part*="clear-all"] {
+  [part*="clear-tag"], #internal > [part*="clear-all"] {
     border-radius: 100%;
     border: none;
     aspect-ratio: 1;
-    line-height: 0;
     padding: 0!important;
     user-select: none;
     background-color: transparent;
   }
   
   [part*="clear-tag"] {
-    inline-size: 1em;
-    block-size: 1em;
-    font-size: 80%;
+    block-size: 1lh;
+    font-size: .7lh;
+    text-transform: uppercase;
     display: none;
   }
+  
+  [part*="clear-tag"]:focus-visible, [part*="clear-tag"]:focus {
+    outline-style: solid;
+    outline-width: 1px;
+  }
 
-  :host([multiple]) [part*="clear-all"] {
+  :host([multiple]) #internal > [part*="clear-all"] {
    display: block;
   }
   
-  :host([clearable]) [part*="clear-tag"] {
-    display: block;
+  :host([clearable]) [part*="clear-tag"],
+  :host([multiple]) [part*="clear-tag"] {
+    display: grid;
+    place-content: center;
   }
 
-  [part*="clear-all"] {
+  #internal > [part*="clear-all"] {
     font-size: inherit;
-    inline-size: 1.2em;
-    block-size: 1.2em;
+    text-transform: uppercase;
+    block-size: 1lh;
     display: none;
   }
+  
+  #tags:empty + [part*="clear-all"] {
+    outline: none;
+  }
 
-  [part*="clear-all"]:hover, 
+  #internal > [part*="clear-all"]:hover, 
   [part*="clear-tag"]:hover {
     color: ActiveText;
     cursor: pointer;
   }
 
-  [part*="clear-all"]:hover {
+  #internal >[part*="clear-all"]:hover {
     background-color: ButtonFace;
   }
   
-  :host:has(#tags:empty) [part*="clear-all"] {
+  #tags:empty + [part*="clear-all"] {
     pointer-events: none;
-    color: darkgrey;
+    outline: none;
   }
+ 
 </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>
+</div>
 
-<div id="tags">&nbsp;</div>
-<div id="placeholder">&nbsp;</div>
-<button part="clear-all">✕</button>
-<div id="dropdown" popover="manual">
-  <input name="search-input" part="search-input" />
-  <div part="options"></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>
 </div>
+
 <template id='tag-template'>
   <box-tag>
     <span part="tag-label"></span>
-    <button part="clear-tag">✕</button>
+    <div part="clear-tag" role='button' tabindex='0'>✕</div>
   </box-tag>
 </template>
 `;
+    static markup;
+    static {
+        const template = document.createElement('template');
+        template.innerHTML = ComboboxMarkup.template;
+        ComboboxMarkup.markup = template;
+    }
 }
 exports.ComboboxMarkup = ComboboxMarkup;