@fluid-topics/ftds-combobox 2.0.37

package/build/ftds-base-combobox.js

@@ -0,0 +1,540 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { html, nothing, } from "lit";
+import { property, query, state, } from "lit/decorators.js";
+import { ifDefined } from "lit/directives/if-defined.js";
+import { repeat } from "lit/directives/repeat.js";
+import { classMap } from "lit/directives/class-map.js";
+import { when } from "lit/directives/when.js";
+import { Debouncer, FtdsBase, ignoreComposingEvents, numberProperty, processValidationRules, Status, toFtInput, } from "@fluid-topics/ft-wc-utils";
+import { FtIcons, FtIconVariants, } from "@fluid-topics/ft-icon";
+import { isActionableListboxItem, isSelectableListboxItem, ListboxItemType, } from "./ftds-base-combobox.properties";
+import { withI18n } from "@fluid-topics/ft-i18n";
+import { baseComboboxContext, defaultBaseComboboxMessages, } from "./FtdsBaseComboboxMessages";
+import { FtdsTypography, FtdsTypographyVariants, } from "@fluid-topics/ft-typography";
+import { FtdsBaseInput } from "@fluid-topics/ft-base-input";
+import { FtdsNotice } from "@fluid-topics/ft-notice";
+// TS2562: base class expressions cannot reference class type parameters, so we
+// fix V=any here and restore the generic via `declare value: T` below.
+const FtdsBaseComboboxBase = withI18n(toFtInput(FtdsBase));
+export class FtdsBaseCombobox extends FtdsBaseComboboxBase {
+    constructor() {
+        super();
+        this.suggestionsProvider = () => [];
+        this.filterSuggestions = false;
+        this.canOfferNewValue = false;
+        this.required = false;
+        this.maxDisplayedSuggestions = 100;
+        this.newValueValidationRules = [];
+        this.isOpen = false;
+        this.inputValue = "";
+        this.activeIndex = -1;
+        this.providedSuggestions = [];
+        this.ariaLiveMessage = "";
+        this.ariaDescribedBy = "";
+        this.listboxItems = [];
+        this.listboxId = `ftds-combobox-listbox-${Math.random().toString(36).slice(2)}`;
+        // Close the menu when a click is triggered outside the listbox (inspired by W3C examples)
+        this.onBackgroundPointerUp = (event) => {
+            // Use composedPath to handle Shadow DOM correctly
+            const path = event.composedPath();
+            const clickedInside = path.includes(this);
+            if (!clickedInside) {
+                this.closeMenu();
+            }
+        };
+        this.addI18nContext(baseComboboxContext, defaultBaseComboboxMessages);
+    }
+    willUpdate(props) {
+        super.willUpdate(props);
+        if (props.has("debouncerTimeout")) {
+            this.debounceTimer = this.debouncerTimeout && this.debouncerTimeout > 0
+                ? new Debouncer(this.debouncerTimeout)
+                : undefined;
+        }
+        if (props.has("value") && props.get("value") !== undefined) {
+            this.onInput();
+        }
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        document.body.addEventListener("pointerup", this.onBackgroundPointerUp);
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        document.body.removeEventListener("pointerup", this.onBackgroundPointerUp);
+    }
+    get shouldRaiseLabel() {
+        return this.focused || this.inputValue != "";
+    }
+    get filteredSuggestions() {
+        const base = this.filterSuggestions
+            ? this.providedSuggestions
+                .filter((s) => s.label.toLowerCase().includes(this.inputValue.toLowerCase()))
+            : this.providedSuggestions;
+        return [...base];
+    }
+    get filteredSuggestionsWithLimit() {
+        return this.filteredSuggestions.slice(0, this.maxDisplayedSuggestions);
+    }
+    get appendIcon() {
+        return this.isOpen ? FtIcons.THIN_ARROW_UP : FtIcons.THIN_ARROW;
+    }
+    get activeItemId() {
+        if (!this.isOpen || this.activeIndex < 0 || this.activeIndex >= this.listboxItems.length) {
+            return undefined;
+        }
+        return this.suggestionId(this.activeIndex);
+    }
+    renderField() {
+        return html `
+            <ftds-base-input
+                .status=${this.status}
+                .size=${this.size}
+                .errorMessages=${this.errorMessages}
+                .warningMessages=${this.warningMessages}
+                .helperText=${this.helperText}
+                .label=${ifDefined(this.label)}
+                ?hideLabel=${this.hideLabel}
+                ?raiseLabel=${this.shouldRaiseLabel}
+                ?disabled=${this.disabled}
+                .appendIcon=${this.appendIcon}
+                .appendIconVariant=${FtIconVariants.fluid_topics}
+                .appendIconLabel=${this.isOpen ? baseComboboxContext.messages.closeMenu() : baseComboboxContext.messages.openMenu()}
+                @click=${() => this.onInputClick()}
+            >
+                <input
+                    role="combobox"
+                    name="${ifDefined(this.name)}"
+                    aria-autocomplete="list"
+                    aria-haspopup="listbox"
+                    aria-expanded="${this.isOpen}"
+                    aria-controls="${this.listboxId}"
+                    aria-activedescendant="${ifDefined(this.activeItemId)}"
+                    aria-label="${ifDefined(this.label)}"
+                    aria-invalid="${this.status === Status.error}"
+                    aria-disabled="${this.disabled}"
+                    aria-required="${this.required}"
+                    aria-describedby="${this.listboxId + "-described-by"}"
+                    .value=${this.inputValue}
+                    ?disabled=${this.disabled}
+                    @input=${(e) => this.onType(e)}
+                    @focus=${() => this.onFocus()}
+                    @blur=${() => this.onBlur()}
+                    @keydown=${(e) => this.onKeyDown(e)}
+                />
+            </ftds-base-input>
+            <div class="sr-only" id="${this.listboxId + "-described-by"}">${this.ariaDescribedBy}</div>
+            <div class="sr-only" role="status">${this.ariaLiveMessage}</div>
+        `;
+    }
+    renderListboxContainer(isMultiSelectable) {
+        const hidden = !this.isOpen;
+        const listboxClasses = {
+            "listbox": true,
+            ...this.getDesignSystemBaseClasses(),
+        };
+        return html `
+            <ul
+                class="${classMap(listboxClasses)}"
+                id="${this.listboxId}"
+                role="listbox"
+                aria-multiselectable="${isMultiSelectable}"
+                ?hidden=${hidden}
+            >
+                ${repeat(this.listboxItems, (s) => { var _a; return `${s.type === ListboxItemType.suggestion ? s.value : (_a = s.type) !== null && _a !== void 0 ? _a : ""}`; }, (s, i) => this.renderListboxItem(s, i))}
+            </ul>
+        `;
+    }
+    renderListboxItem(listboxItem, index) {
+        if (listboxItem.type === ListboxItemType.noResult) {
+            return this.renderNoResult(index);
+        }
+        if (listboxItem.type === ListboxItemType.maxSuggestions) {
+            return this.renderMaxSuggestionsItem(index);
+        }
+        if (listboxItem.type === ListboxItemType.newValue && isSelectableListboxItem(listboxItem)) {
+            return this.renderNewValueSuggestion(listboxItem, index);
+        }
+        if (isSelectableListboxItem(listboxItem)) {
+            return this.renderSuggestion(listboxItem, index);
+        }
+        return nothing;
+    }
+    renderSuggestion(suggestion, index) {
+        const isActive = this.activeIndex === index;
+        const isSelected = this.isSuggestionSelected(suggestion.value);
+        return html `
+            <li
+                id="${this.suggestionId(index)}"
+                class="listbox-option"
+                role="option"
+                aria-selected="${isSelected}"
+                data-active="${isActive}"
+                @mousedown=${(e) => e.preventDefault()}
+                @click=${() => this.onItemSelected(index)}
+            >
+                <div class="listbox-option--label">
+                    ${this.renderSuggestionItem(suggestion, isSelected)}
+                </div>
+            </li>`;
+    }
+    renderNewValueSuggestion(suggestion, index) {
+        const isActive = this.activeIndex === index;
+        const isSelected = this.isSuggestionSelected(suggestion.value);
+        const validationErrors = processValidationRules(this.inputValue, this.newValueValidationRules);
+        const isValidationErrors = validationErrors.length > 0;
+        const classes = classMap({
+            "listbox-option": true,
+            "listbox-option--new-value": true,
+            "listbox-option--new-value--error": isValidationErrors,
+        });
+        return html `
+            <li
+                id="${this.suggestionId(index)}"
+                class="${classes}"
+                role="option"
+                aria-selected="${isSelected}"
+                data-active="${isActive}"
+                @mousedown=${(e) => e.preventDefault()}
+                @click=${() => this.onItemSelected(index)}
+            >
+                ${this.renderNewValueTag()}
+                ${when(isValidationErrors, () => this.renderNewValueValidationErrors(validationErrors), () => this.renderNewValueLabel(suggestion, isSelected))}
+            </li>`;
+    }
+    renderNewValueTag() {
+        return html `
+            <ftds-typography
+                variant="${FtdsTypographyVariants.caption2medium}"
+                class="listbox-option--helper"
+            >
+                ${baseComboboxContext.messages.newValueLabel()}
+            </ftds-typography>`;
+    }
+    renderNewValueLabel(suggestion, isSelected) {
+        return html `
+            <div class="listbox-option--label">
+                ${this.renderSuggestionItem(suggestion, isSelected)}
+            </div>`;
+    }
+    renderNewValueValidationErrors(validationErrors) {
+        return html `${validationErrors.map((error) => html `
+            <ftds-notice
+                family="error"
+                dense>
+                ${error}
+            </ftds-notice>
+        `)}`;
+    }
+    renderMaxSuggestionsItem(index) {
+        const id = this.suggestionId(index);
+        return html `
+            <li id="${id}"
+                class="listbox-option--message--max"
+                role="option"
+                aria-hidden="true"
+            >
+                <ftds-typography variant="${FtdsTypographyVariants.body2medium}">
+                    ${baseComboboxContext.messages.maxSuggestionsLabel(this.maxDisplayedSuggestions)}
+                </ftds-typography>
+                <ftds-typography variant="${FtdsTypographyVariants.body2medium}">
+                    ${baseComboboxContext.messages.refineYourSearchLabel()}
+                </ftds-typography>
+            </li>
+        `;
+    }
+    renderNoResult(index) {
+        const id = this.suggestionId(index);
+        return html `
+            <li id="${id}"
+                class="listbox-option--message--no-option"
+                role="option"
+                aria-hidden="true"
+            >
+                <ftds-typography variant="${FtdsTypographyVariants.body2medium}">
+                    ${baseComboboxContext.messages.noResultLabel()}
+                </ftds-typography>
+            </li>
+        `;
+    }
+    async computeListboxItems() {
+        await this.computeSuggestions();
+        this.listboxItems = await this.getListboxItems();
+        void this.setAriaDescribeBy();
+    }
+    async getListboxItems() {
+        const filteredListboxItems = this.filteredSuggestions;
+        const listboxItemsWithLimit = this.filteredSuggestionsWithLimit;
+        const exactMatch = this.filteredSuggestions.some((s) => s.label.toLowerCase() === this.inputValue.toLowerCase());
+        const shouldShowNewValue = this.canOfferNewValue && this.inputValue !== "" && !exactMatch;
+        const shouldShowNoResults = !this.canOfferNewValue && this.filteredSuggestions.length === 0 && this.inputValue !== "";
+        if (shouldShowNewValue) {
+            listboxItemsWithLimit.push({ label: this.inputValue, value: this.inputValue, type: ListboxItemType.newValue });
+        }
+        else if (shouldShowNoResults) {
+            listboxItemsWithLimit.push({ type: ListboxItemType.noResult });
+        }
+        const shouldShowMaxSuggestionsReached = filteredListboxItems.length > this.maxDisplayedSuggestions;
+        if (shouldShowMaxSuggestionsReached) {
+            listboxItemsWithLimit.push({ type: ListboxItemType.maxSuggestions });
+        }
+        return listboxItemsWithLimit;
+    }
+    async setAriaDescribeBy() {
+        this.ariaLiveMessage = "";
+        await this.updateComplete;
+        if (this.filteredSuggestions.length === 0) {
+            this.ariaLiveMessage = baseComboboxContext.messages.noResultLabel();
+        }
+        if (this.maxDisplayedSuggestions < this.filteredSuggestions.length) {
+            this.ariaLiveMessage = baseComboboxContext.messages.maxSuggestionsAriaLabel(this.maxDisplayedSuggestions);
+        }
+    }
+    async computeSuggestions() {
+        var _a;
+        if (this.debouncerTimeout && this.debouncerTimeout > 0) {
+            (_a = this.debounceTimer) !== null && _a !== void 0 ? _a : (this.debounceTimer = new Debouncer(this.debouncerTimeout));
+            await this.debounceTimer.run(() => this.runSuggestionsProvider());
+        }
+        else {
+            return this.runSuggestionsProvider();
+        }
+    }
+    async runSuggestionsProvider() {
+        const suggestions = await this.suggestionsProvider(this.inputValue);
+        this.providedSuggestions = suggestions.map((s) => ({ ...s, type: ListboxItemType.suggestion }));
+    }
+    suggestionId(index) {
+        return `${this.listboxId}-option-${index}`;
+    }
+    async onType(e) {
+        if (this.disabled) {
+            return;
+        }
+        this.inputValue = e.target.value;
+        if (!this.isOpen) {
+            await this.openMenu();
+        }
+        else {
+            await this.computeListboxItems();
+        }
+        this.activeIndex = -1;
+    }
+    async onInputClick() {
+        if (this.disabled) {
+            return;
+        }
+        if (!this.isOpen) {
+            await this.openMenu();
+        }
+        else {
+            this.closeMenu();
+        }
+    }
+    onBlur() {
+        if (this.disabled) {
+            return;
+        }
+        if (this.isOpen) {
+            this.closeMenu();
+        }
+        this.handleBlurStrategy();
+        super.onBlur();
+    }
+    async openMenu() {
+        if (this.disabled || this.isOpen) {
+            return;
+        }
+        await this.computeListboxItems();
+        this.isOpen = true;
+    }
+    closeMenu() {
+        if (!this.isOpen) {
+            return;
+        }
+        this.isOpen = false;
+        this.activeIndex = -1;
+    }
+    onItemSelected(index) {
+        if (this.disabled) {
+            return;
+        }
+        const suggestion = this.listboxItems[index];
+        if (!suggestion) {
+            return;
+        }
+        if (isActionableListboxItem(suggestion)) {
+            this.commitSelection(suggestion);
+        }
+    }
+    async onKeyDown(e) {
+        var _a, _b;
+        if (this.disabled) {
+            return;
+        }
+        switch (e.key) {
+            case "ArrowDown":
+                e.preventDefault();
+                if (e.altKey) {
+                    if (!this.isOpen) {
+                        await this.openMenu();
+                    }
+                    return;
+                }
+                if (!this.isOpen) {
+                    await this.openMenu();
+                    const indices = this.getSelectableIndexes();
+                    this.activeIndex = (_a = indices[0]) !== null && _a !== void 0 ? _a : -1;
+                }
+                else {
+                    this.moveActiveIndex(1);
+                }
+                return;
+            case "ArrowUp":
+                e.preventDefault();
+                if (!this.isOpen) {
+                    await this.openMenu();
+                    const indices = this.getSelectableIndexes();
+                    this.activeIndex = (_b = indices[indices.length - 1]) !== null && _b !== void 0 ? _b : -1;
+                }
+                else {
+                    this.moveActiveIndex(-1);
+                }
+                return;
+            case "ArrowRight":
+            case "ArrowLeft":
+            case "Home":
+            case "End":
+                this.activeIndex = -1;
+                return;
+            case "Enter":
+                if (!this.isOpen) {
+                    return;
+                }
+                e.preventDefault();
+                if (this.activeIndex >= 0) {
+                    this.onItemSelected(this.activeIndex);
+                }
+                else {
+                    this.closeMenu();
+                }
+                return;
+            case "Escape":
+                e.preventDefault();
+                if (this.isOpen) {
+                    this.closeMenu();
+                }
+                else {
+                    this.inputValue = "";
+                }
+                return;
+            case "Tab":
+                if (this.isOpen) {
+                    this.closeMenu();
+                }
+                return;
+        }
+    }
+    getSelectableIndexes() {
+        return this.listboxItems.reduce((indexes, item, currentIndex) => isActionableListboxItem(item) ? [...indexes, currentIndex] : indexes, []);
+    }
+    moveActiveIndex(direction) {
+        const selectableIndices = this.getSelectableIndexes();
+        if (selectableIndices.length === 0) {
+            this.activeIndex = -1;
+            return;
+        }
+        const currentPos = selectableIndices.indexOf(this.activeIndex);
+        const nextPos = currentPos === -1
+            ? (direction === 1 ? 0 : selectableIndices.length - 1)
+            : (currentPos + direction + selectableIndices.length) % selectableIndices.length;
+        this.activeIndex = selectableIndices[nextPos];
+        this.scrollSuggestionIntoView(this.activeIndex);
+    }
+    scrollSuggestionIntoView(suggestionIndex) {
+        requestAnimationFrame(() => {
+            const elementToScrollTo = this.getElementToScrollTo(suggestionIndex);
+            if (elementToScrollTo && elementToScrollTo instanceof HTMLElement && this.listbox) {
+                const needToScrollDown = this.listbox.scrollTop + this.listbox.offsetHeight < elementToScrollTo.offsetTop + elementToScrollTo.offsetHeight;
+                const needToScrollUp = this.listbox.scrollTop > elementToScrollTo.offsetTop + 2;
+                if (needToScrollDown) {
+                    this.listbox.scrollTop = elementToScrollTo.offsetTop + elementToScrollTo.offsetHeight - this.listbox.offsetHeight;
+                }
+                else if (needToScrollUp) {
+                    this.listbox.scrollTop = elementToScrollTo.offsetTop;
+                }
+            }
+        });
+    }
+    // When reaching the last suggestion we want to scroll down more to put the max suggestions message into view
+    getElementToScrollTo(suggestionIndex) {
+        var _a, _b, _c, _d, _e;
+        const isLastSuggestion = ((_c = (_b = (_a = this.listbox) === null || _a === void 0 ? void 0 : _a.querySelectorAll(".listbox-option")) === null || _b === void 0 ? void 0 : _b.length) !== null && _c !== void 0 ? _c : 0) - 1 === suggestionIndex;
+        const maxSuggestionElement = (_d = this.listbox) === null || _d === void 0 ? void 0 : _d.querySelector(".listbox-option--message--max");
+        if (isLastSuggestion && maxSuggestionElement) {
+            return maxSuggestionElement;
+        }
+        return (_e = this.listbox) === null || _e === void 0 ? void 0 : _e.children.item(suggestionIndex);
+    }
+}
+FtdsBaseCombobox.baseComboboxElementDefinitions = {
+    "ftds-base-input": FtdsBaseInput,
+    "ftds-typography": FtdsTypography,
+    "ftds-notice": FtdsNotice,
+};
+__decorate([
+    property({ attribute: false })
+], FtdsBaseCombobox.prototype, "suggestionsProvider", void 0);
+__decorate([
+    numberProperty()
+], FtdsBaseCombobox.prototype, "debouncerTimeout", void 0);
+__decorate([
+    property({ type: Boolean })
+], FtdsBaseCombobox.prototype, "filterSuggestions", void 0);
+__decorate([
+    property({ type: Boolean })
+], FtdsBaseCombobox.prototype, "canOfferNewValue", void 0);
+__decorate([
+    property({ type: Boolean })
+], FtdsBaseCombobox.prototype, "required", void 0);
+__decorate([
+    numberProperty()
+], FtdsBaseCombobox.prototype, "maxDisplayedSuggestions", void 0);
+__decorate([
+    property()
+], FtdsBaseCombobox.prototype, "newValueValidationRules", void 0);
+__decorate([
+    state()
+], FtdsBaseCombobox.prototype, "isOpen", void 0);
+__decorate([
+    state()
+], FtdsBaseCombobox.prototype, "inputValue", void 0);
+__decorate([
+    state()
+], FtdsBaseCombobox.prototype, "activeIndex", void 0);
+__decorate([
+    state()
+], FtdsBaseCombobox.prototype, "providedSuggestions", void 0);
+__decorate([
+    state()
+], FtdsBaseCombobox.prototype, "ariaLiveMessage", void 0);
+__decorate([
+    state()
+], FtdsBaseCombobox.prototype, "ariaDescribedBy", void 0);
+__decorate([
+    state()
+], FtdsBaseCombobox.prototype, "listboxItems", void 0);
+__decorate([
+    query("input")
+], FtdsBaseCombobox.prototype, "input", void 0);
+__decorate([
+    query(".listbox")
+], FtdsBaseCombobox.prototype, "listbox", void 0);
+__decorate([
+    ignoreComposingEvents()
+], FtdsBaseCombobox.prototype, "onKeyDown", null);

package/build/ftds-base-combobox.properties.d.ts

@@ -0,0 +1,39 @@
+import { FtdsBaseInterface } from "@fluid-topics/ft-wc-utils/build/FtdsBase";
+import { FtInputInterface, ValidationRule } from "@fluid-topics/ft-wc-utils";
+export interface ComboboxSuggestion {
+    label: string;
+    value: string;
+}
+export declare enum ListboxItemType {
+    suggestion = 0,
+    noResult = 1,
+    newValue = 2,
+    maxSuggestions = 3,
+    all = 4
+}
+export interface SuggestionListboxItem {
+    label: string;
+    value: string;
+    type: ListboxItemType.suggestion | ListboxItemType.newValue;
+}
+export interface SelectAllListboxItem {
+    type: ListboxItemType.all;
+}
+export interface NonSelectableListboxItem {
+    type: ListboxItemType.noResult | ListboxItemType.maxSuggestions;
+}
+export type ActionableListboxItem = SuggestionListboxItem | SelectAllListboxItem;
+export type ListboxItem = ActionableListboxItem | NonSelectableListboxItem;
+export declare function isActionableListboxItem(item: ListboxItem): item is ActionableListboxItem;
+export declare function isSelectableListboxItem(item: ListboxItem): item is SuggestionListboxItem;
+export type SuggestionsProvider = (filter: string) => ComboboxSuggestion[] | Promise<ComboboxSuggestion[]>;
+export interface FtdsBaseComboboxProperties extends FtdsBaseInterface, FtInputInterface<any> {
+    required: boolean;
+    placeholder?: string;
+    suggestionsProvider: SuggestionsProvider;
+    debouncerTimeout?: number;
+    filterSuggestions: boolean;
+    canOfferNewValue: boolean;
+    maxDisplayedSuggestions: number;
+    newValueValidationRules: Array<ValidationRule<string>>;
+}

package/build/ftds-base-combobox.properties.js

@@ -0,0 +1,14 @@
+export var ListboxItemType;
+(function (ListboxItemType) {
+    ListboxItemType[ListboxItemType["suggestion"] = 0] = "suggestion";
+    ListboxItemType[ListboxItemType["noResult"] = 1] = "noResult";
+    ListboxItemType[ListboxItemType["newValue"] = 2] = "newValue";
+    ListboxItemType[ListboxItemType["maxSuggestions"] = 3] = "maxSuggestions";
+    ListboxItemType[ListboxItemType["all"] = 4] = "all";
+})(ListboxItemType || (ListboxItemType = {}));
+export function isActionableListboxItem(item) {
+    return item.type === ListboxItemType.suggestion || item.type === ListboxItemType.newValue || item.type === ListboxItemType.all;
+}
+export function isSelectableListboxItem(item) {
+    return item.type === ListboxItemType.suggestion || item.type === ListboxItemType.newValue;
+}

package/build/ftds-base-combobox.styles.d.ts

@@ -0,0 +1 @@
+export declare const baseComboboxStyles: import("lit").CSSResult;