@salesforcedevs/dx-components 0.10.0 → 0.10.1-alpha.100

package/src/modules/dx/sidebarSearch/__tests__/sidebarSearch.test.ts

@@ -0,0 +1,44 @@
+import SidebarSearch from "dx/sidebarSearch";
+import { createRenderComponent } from "utils/tests";
+import { coveoXMLDocsConfig } from "utils/coveo"; //coveoSFDocsConfig
+
+const TAG = "dx-sidebar-search";
+const render = createRenderComponent(TAG, SidebarSearch);
+
+const PROPS = coveoXMLDocsConfig;
+const QUERY = "test";
+
+const mockQuery = (q: string): void => {
+    global.window = Object.create(window);
+    const url = `http://dummy.com?q="${q}"`;
+    Object.defineProperty(window, "location", {
+        value: {
+            href: url,
+            search: `?q=${q}`
+        }
+    });
+};
+
+describe(TAG, () => {
+    it("renders with the correct initial empty query", () => {
+        const element = render(PROPS);
+
+        const input = element.shadowRoot.querySelector("dx-input");
+
+        expect(input.value).toEqual("");
+
+        return expect(element).toBeAccessible();
+    });
+
+    it("renders with the correct initial query", () => {
+        mockQuery(QUERY);
+
+        const element = render(PROPS);
+
+        const input = element.shadowRoot.querySelector("dx-input");
+
+        expect(input.value).toEqual(QUERY);
+
+        return expect(element).toBeAccessible();
+    });
+});

package/src/modules/dx/sidebarSearch/sidebarSearch.css

@@ -0,0 +1,3 @@
+.search-box {
+    --dx-c-input-width: 100%;
+}

package/src/modules/dx/sidebarSearch/sidebarSearch.html

@@ -0,0 +1,26 @@
+<template>
+    <dx-dropdown
+        aria-label="Recent Searches"
+        open={isDropdownOpen}
+        options={recentSearches}
+        onchange={onClickRecentSearch}
+        onrequestclose={onDropdownRequestClose}
+        full-width
+    >
+        <dx-input
+            class="search-box"
+            type="search"
+            placeholder="Search this list..."
+            role="search"
+            aria-label="Content Search"
+            icon-symbol="search"
+            size="small"
+            value={value}
+            onchange={onInputChange}
+            onfocus={onInputFocus}
+            onclear={onInputClear}
+            shortcut-key="j"
+            clearable
+        ></dx-input>
+    </dx-dropdown>
+</template>

package/src/modules/dx/sidebarSearch/sidebarSearch.ts

@@ -0,0 +1,358 @@
+import { LightningElement, api } from "lwc";
+import debounce from "debounce";
+import {
+    Result,
+    ResultList,
+    ResultsPerPage,
+    SearchBox,
+    buildResultList,
+    buildResultsPerPage,
+    buildSearchBox,
+    loadAdvancedSearchQueryActions,
+    SearchEngine,
+    buildSearchStatus,
+    SearchAppState
+} from "@coveo/headless";
+import { buildSearchEngine, getSidebarSearchParams } from "utils/coveo";
+import { RecentSearches } from "utils/recentSearches";
+import { toJson } from "utils/normalizers";
+import { Option, PopoverRequestCloseType } from "typings/custom";
+
+const DEFAULT_RESULT_COUNT = 20;
+
+const UserRecentSearches = new RecentSearches();
+
+const normalizeCoveoAdvancedQueryValue = (version: string): string =>
+    version.split(".").join("\\.");
+
+function executeFirstSearch(engine: SearchEngine) {
+    return new Promise((resolve) => {
+        const searchStatus = buildSearchStatus(engine);
+        searchStatus.subscribe(
+            () => searchStatus.state.firstSearchExecuted && resolve(true)
+        );
+        engine.executeFirstSearch();
+    });
+}
+
+export default class SidebarSearch extends LightningElement {
+    @api coveoOrganizationId!: string;
+    @api coveoPublicAccessToken!: string;
+    @api coveoSearchHub!: string;
+    @api
+    get coveoAdvancedQueryConfig() {
+        return this._coveoAdvancedQueryConfig;
+    }
+    set coveoAdvancedQueryConfig(value) {
+        this._coveoAdvancedQueryConfig = toJson(value);
+    }
+
+    @api
+    public fetchMoreResults() {
+        if (this.resultList) {
+            this.resultList.fetchMoreResults();
+        }
+    }
+
+    private _coveoAdvancedQueryConfig!: object;
+    private dropdownRequestedOpen: boolean = false;
+    private recentSearches: Option[] = [];
+    private resultList: ResultList | null = null;
+    private resultsPerPage: ResultsPerPage | null = null;
+    private preloadedState?: SearchAppState;
+    private searchBox: SearchBox | null = null;
+    private value?: string = "";
+    private engine: SearchEngine | null = null;
+
+    private get hasCorrectCoveoConfig(): boolean {
+        const coveoConfigurations = [
+            this.coveoOrganizationId,
+            this.coveoPublicAccessToken,
+            this.coveoSearchHub,
+            this.coveoAdvancedQueryConfig
+        ];
+
+        return coveoConfigurations.every(
+            (val) =>
+                !!val && (typeof val === "string" || typeof val === "object")
+        );
+    }
+
+    private get isDropdownOpen() {
+        return (
+            this.dropdownRequestedOpen &&
+            this.recentSearches &&
+            this.recentSearches.length > 0 &&
+            this.isValueEmpty
+        );
+    }
+
+    private get isValueEmpty(): boolean {
+        return !this.value || this.value === "";
+    }
+
+    constructor() {
+        super();
+
+        this.updateRecentSearches();
+        this.value = getSidebarSearchParams() || "";
+        this.initializeUserSession();
+    }
+
+    renderedCallback() {
+        if (this.hasCorrectCoveoConfig && !this.engine) {
+            this.initializeCoveo();
+        } else if (!this.hasCorrectCoveoConfig) {
+            console.error(
+                "Incorrect coveo search configuration provided. All coveo configuration attributes must be defined.",
+                {
+                    coveoOrganizationId: this.coveoOrganizationId,
+                    coveoPublicAccessToken: this.coveoPublicAccessToken,
+                    coveoSearchHub: this.coveoSearchHub,
+                    coveoAdvancedQueryConfig: this.coveoAdvancedQueryConfig
+                }
+            );
+        }
+    }
+
+    private initializeUserSession() {
+        const stringified = window.sessionStorage.getItem(
+            "dx-sidebar-search-state"
+        );
+        if (!stringified) {
+            return;
+        }
+        const state = JSON.parse(stringified);
+        console.log(
+            { state },
+            state?.query?.q,
+            this.value,
+            state?.query?.q === this.value
+        );
+        if (state?.query?.q === this.value) {
+            console.log("assigning state");
+            this.preloadedState = state;
+        }
+    }
+
+    private initializeCoveo = async () => {
+        this.engine = buildSearchEngine({
+            organizationId: this.coveoOrganizationId,
+            publicAccessToken: this.coveoPublicAccessToken,
+            searchHub: this.coveoSearchHub,
+            preloadedState: this.preloadedState
+        });
+
+        if (!this.engine) {
+            return;
+        }
+
+        this.resultList = buildResultList(this.engine, {
+            options: { fieldsToInclude: ["sfhtml_url__c"] }
+        });
+
+        this.resultsPerPage = buildResultsPerPage(this.engine, {
+            initialState: {
+                numberOfResults: DEFAULT_RESULT_COUNT
+            }
+        });
+        this.searchBox = buildSearchBox(this.engine, {
+            options: { numberOfSuggestions: 3 }
+        });
+        this.setAdvancedFilters(this.engine);
+
+        this.resultList?.subscribe(this.onResultListChange);
+
+        await executeFirstSearch(this.engine);
+
+        console.log({ resultList: this.resultList, engine: this.engine });
+
+        if (!this.isValueEmpty) {
+            this.dispatchHighlightedTermChange();
+        }
+        this.dispatchOnLoading(false); // might not be needed
+    };
+
+    private onResultListChange = () => {
+        if (!this.resultList) {
+            return;
+        }
+
+        const { isLoading, firstSearchExecuted, results } =
+            this.resultList.state;
+
+        console.log("on results list change", {
+            isLoading,
+            firstSearchExecuted,
+            results
+        });
+
+        if ((!firstSearchExecuted && !isLoading) || this.isValueEmpty) {
+            // coveo search is firing off some unwanted payloads on startup
+            console.log(
+                "returning in results list change",
+                this.value,
+                this.isValueEmpty,
+                !firstSearchExecuted && !isLoading
+            );
+            return;
+        }
+
+        if (!isLoading) {
+            console.log(results);
+            this.dispatchOnChangeEvent(results);
+        }
+
+        this.dispatchOnLoading(isLoading);
+    };
+
+    private setAdvancedFilters(engine: SearchEngine) {
+        const aq = Object.entries(this.coveoAdvancedQueryConfig).reduce(
+            (result, [key, value]) =>
+                `${result}(@${key}=="${normalizeCoveoAdvancedQueryValue(
+                    value
+                )}")`,
+            ""
+        );
+
+        const registerSearchQueryAction = loadAdvancedSearchQueryActions(
+            engine
+        ).registerAdvancedSearchQueries({
+            aq: aq
+        });
+
+        engine.dispatch(registerSearchQueryAction);
+    }
+
+    private normalizeCoveoResult = ({
+        clickUri,
+        excerpt,
+        excerptHighlights,
+        raw: { sfhtml_url__c },
+        title,
+        titleHighlights,
+        uniqueId
+    }: Result) => {
+        const pathname = sfhtml_url__c
+            ? `/docs/${sfhtml_url__c}`
+            : `${new URL(clickUri).pathname}.html`;
+        const href = `${pathname}?q=${this.value}`;
+
+        return {
+            title,
+            titleHighlights,
+            excerpt,
+            excerptHighlights,
+            uniqueId,
+            href,
+            selected: pathname === window.location.pathname
+        };
+    };
+
+    private updateSessionStorage() {
+        window.sessionStorage.setItem(
+            "dx-sidebar-search-state",
+            JSON.stringify(this.engine?.state)
+        );
+    }
+
+    private dispatchOnChangeEvent(results: Result[]) {
+        this.updateSessionStorage();
+        this.dispatchEvent(
+            new CustomEvent("change", {
+                detail: {
+                    results: results.map(this.normalizeCoveoResult),
+                    value: this.value
+                }
+            })
+        );
+    }
+
+    private dispatchOnLoading(loading: boolean) {
+        this.dispatchEvent(new CustomEvent("loading", { detail: loading }));
+    }
+
+    private dispatchHighlightedTermChange() {
+        this.dispatchEvent(
+            new CustomEvent("highlightedtermchange", {
+                detail: this.value,
+                composed: true,
+                bubbles: true
+            })
+        );
+    }
+
+    private updateRecentSearches = () =>
+        (this.recentSearches = UserRecentSearches.get().map(
+            (item: { id: string; label: string }) => ({
+                id: item,
+                label: item
+            })
+        ));
+
+    private updateHistory(): void {
+        const { pathname, hash, search } = window.location;
+        if (this.isValueEmpty) {
+            window.history.pushState({}, "", `${pathname}${hash}`);
+            return;
+        }
+
+        const queryParams = new URLSearchParams(search);
+        if (this.value) {
+            queryParams.set("q", this.value);
+        }
+        window.history.pushState({}, "", `?${queryParams.toString()}${hash}`);
+    }
+
+    private submitSearch = debounce(() => {
+        if (this.searchBox) {
+            this.searchBox.updateText(this.value || "");
+            UserRecentSearches.add(this.value);
+            this.updateRecentSearches();
+            console.log(this.value);
+            this.searchBox.submit();
+        }
+    }, 360).bind(this);
+
+    private onClickRecentSearch(e: CustomEvent) {
+        this.value = e.detail;
+        this.submitSearch();
+    }
+
+    private onDropdownRequestClose(e: CustomEvent) {
+        switch (e.detail as PopoverRequestCloseType) {
+            case "interact-outside":
+            case "keypress-escape":
+                this.dropdownRequestedOpen = false;
+                break;
+            default:
+                break;
+        }
+    }
+
+    private onInputChange(e: CustomEvent) {
+        this.value = e.detail;
+
+        if (this.searchBox && !this.isValueEmpty) {
+            this.submitSearch();
+        }
+
+        if (this.isValueEmpty) {
+            // coveo's reaction to an empty value triggers a return of results
+            // bootlegging our own ux here`
+            this.dispatchOnLoading(false);
+            this.dispatchOnChangeEvent([]);
+        }
+
+        this.dispatchHighlightedTermChange();
+        this.updateHistory();
+    }
+
+    private onInputFocus() {
+        this.dropdownRequestedOpen = true;
+    }
+
+    private onInputClear() {
+        this.dropdownRequestedOpen = false;
+    }
+}

package/src/modules/dx/sidebarSearch/utils.ts

@@ -0,0 +1,2 @@
+export const getSidebarSearchParams = () =>
+    new URLSearchParams(window.location.search).get("q");

package/src/modules/dx/sidebarSearchResult/__tests__/sidebarSearchResult.test.ts

@@ -0,0 +1,55 @@
+import SidebarSearchResult from "dx/sidebarSearchResult";
+import { createRenderComponent } from "utils/tests";
+
+const TAG = "dx-sidebar-search-result";
+const render = createRenderComponent(TAG, SidebarSearchResult);
+
+const PROPS = {
+    description: "test description here",
+    descriptionHighlights: [{ length: 5, offset: 5 }],
+    href: "/test",
+    selected: false,
+    title: "test title here",
+    titleHighlights: [{ length: 5, offset: 5 }]
+};
+
+describe(TAG, () => {
+    it("renders a result with the correct highlighted content", () => {
+        const element = render(PROPS);
+
+        const titleBolds = element.shadowRoot.querySelectorAll(".title .bold");
+        expect(titleBolds.length).toEqual(1);
+        expect(titleBolds[0].textContent).toEqual("title");
+
+        const descriptionBolds =
+            element.shadowRoot.querySelectorAll(".description .bold");
+        expect(descriptionBolds.length).toEqual(1);
+        expect(descriptionBolds[0].textContent).toEqual("descr");
+
+        return expect(element).toBeAccessible();
+    });
+
+    it("renders a result as selected when specified", () => {
+        const element = render({ ...PROPS, selected: true });
+
+        const selected = element.shadowRoot.querySelector(
+            ".sidebar-item-selected"
+        );
+        expect(selected).not.toBeNull();
+
+        return expect(element).toBeAccessible();
+    });
+
+    it("doesn't add bold class when there is no highlighted term", () => {
+        const element = render({
+            ...PROPS,
+            descriptionHighlights: [],
+            titleHighlights: []
+        });
+
+        const selected = element.shadowRoot.querySelector(".bold");
+        expect(selected).toBeNull();
+
+        return expect(element).toBeAccessible();
+    });
+});

package/src/modules/dx/sidebarSearchResult/sidebarSearchResult.css

@@ -0,0 +1,36 @@
+@import "helpers/reset";
+@import "helpers/text";
+@import "helpers/sidebar";
+
+a {
+    display: flex;
+    flex-direction: column;
+}
+
+.sidebar-item {
+    padding: var(--dx-g-spacing-smd) var(--dx-g-spacing-md);
+}
+
+.search-text {
+    font-size: var(--dx-g-text-xs);
+    font-family: var(--dx-g-font-sans);
+    line-height: 18px;
+    overflow-wrap: break-word;
+}
+
+.description {
+    -webkit-line-clamp: 3;
+    overflow-wrap: break-word;
+}
+
+.title {
+    color: var(--dx-g-text-heading-color);
+}
+
+.bold {
+    font-weight: 700;
+}
+
+a > *:not(:last-child) {
+    margin-bottom: 2px;
+}

package/src/modules/dx/sidebarSearchResult/sidebarSearchResult.html

@@ -0,0 +1,14 @@
+<template>
+    <a class={className} href={href}>
+        <span class="title search-text">
+            <template for:each={titleChunks} for:item="chunk">
+                <span class={chunk.class} key={chunk.id}>{chunk.value}</span>
+            </template>
+        </span>
+        <span class="description dx-text-body-3 sidebar-item-truncate-text">
+            <template for:each={descriptionChunks} for:item="chunk">
+                <span class={chunk.class} key={chunk.id}>{chunk.value}</span>
+            </template>
+        </span>
+    </a>
+</template>

package/src/modules/dx/sidebarSearchResult/sidebarSearchResult.ts

@@ -0,0 +1,56 @@
+import { LightningElement, api } from "lwc";
+import cx from "classnames";
+import { CoveoHighlights } from "typings/custom";
+
+const toChunks = (value: string, highlights: CoveoHighlights) => {
+    if (!highlights || highlights.length < 1) {
+        return [
+            {
+                value,
+                id: 0
+            }
+        ];
+    }
+
+    let endIndex = 0;
+    return highlights.reduce((acc, { length, offset }) => {
+        const plainValue = value.slice(endIndex, offset);
+        const plainChunk = {
+            value: plainValue,
+            id: endIndex
+        };
+
+        endIndex = offset + length;
+        const boldValue = value.slice(offset, endIndex);
+        const boldChunk = {
+            value: boldValue,
+            class: "bold",
+            id: offset
+        };
+
+        return plainValue.length > 0
+            ? [...acc, plainChunk, boldChunk]
+            : [...acc, boldChunk];
+    }, []);
+};
+
+export default class SidebarSearchResult extends LightningElement {
+    @api description!: string;
+    @api descriptionHighlights!: CoveoHighlights;
+    @api href!: string;
+    @api selected!: boolean;
+    @api title!: string;
+    @api titleHighlights!: CoveoHighlights;
+
+    private get titleChunks() {
+        return toChunks(this.title, this.titleHighlights);
+    }
+
+    private get descriptionChunks() {
+        return toChunks(this.description, this.descriptionHighlights);
+    }
+
+    private get className(): string {
+        return cx("sidebar-item", this.selected && "sidebar-item-selected");
+    }
+}

package/src/modules/dx/spinner/__tests__/spinner.test.ts

@@ -0,0 +1,37 @@
+import Spinner from "dx/spinner";
+import { createRenderComponent } from "utils/tests";
+
+const TAG = "dx-spinner";
+const render = createRenderComponent(TAG, Spinner);
+
+describe(TAG, () => {
+    it("renders", () => {
+        const component: HTMLElement = render();
+
+        expect(component.classList).toHaveLength(1);
+        expect(component.classList).toContain("spinner_container");
+        const container = component.shadowRoot!.querySelector(".spinner");
+
+        expect(container).not.toBeNull();
+        expect(container?.classList).toHaveLength(2);
+        expect(container?.classList).toContain(`spinner_medium`);
+
+        return expect(component).toBeAccessible();
+    });
+
+    it("renders with size and variant", () => {
+        const size = "large";
+        const variant = "inverse";
+        const component: HTMLElement = render({
+            size,
+            variant
+        });
+
+        const container = component.shadowRoot?.querySelector(".spinner");
+        expect(container?.classList).toHaveLength(3);
+        expect(container?.classList).toContain(`spinner_${size}`);
+        expect(container?.classList).toContain(`spinner_${variant}`);
+
+        return expect(component).toBeAccessible();
+    });
+});