@salesforcedevs/dx-components 0.0.0

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

@@ -0,0 +1,463 @@
+import { LightningElement, api } from "lwc";
+import debounce from "debounce";
+import {
+    Result,
+    ResultList,
+    Unsubscribe,
+    ResultsPerPage,
+    SearchBox,
+    buildResultList,
+    buildResultsPerPage,
+    buildSearchBox,
+    loadAdvancedSearchQueryActions,
+    SearchEngine,
+    SearchAppState,
+    loadQueryActions
+} from "@coveo/headless";
+import { buildSearchEngine, getSidebarSearchParams } from "dxUtils/coveo";
+import { RecentSearches } from "dxUtils/recentSearches";
+import { toJson } from "dxUtils/normalizers";
+import {
+    Option,
+    PopoverRequestCloseType,
+    SidebarSearchResult
+} from "typings/custom";
+
+export const SESSION_KEY = "dx-sidebar-search-state";
+
+const DEFAULT_RESULT_COUNT = 20;
+const SEARCH_DEBOUNCE_DELAY = 780;
+
+const UserRecentSearches = new RecentSearches();
+
+const normalizeCoveoAdvancedQueryValue = (version: string): string =>
+    version.split(".").join("\\.");
+
+export default class SidebarSearch extends LightningElement {
+    @api coveoOrganizationId!: string;
+    @api coveoPublicAccessToken!: string;
+    @api coveoSearchHub!: string;
+    @api
+    get coveoAdvancedQueryConfig(): { [key: string]: any } {
+        return this._coveoAdvancedQueryConfig;
+    }
+    set coveoAdvancedQueryConfig(value) {
+        const jsonValue = toJson(value);
+        const hasChanged =
+            this._coveoAdvancedQueryConfig &&
+            Object.entries(jsonValue).some(
+                ([key, val]: [string, any]) =>
+                    this._coveoAdvancedQueryConfig[key] !== val
+            );
+        this._coveoAdvancedQueryConfig = jsonValue;
+
+        if (hasChanged && this.engine && this.value !== "") {
+            this.dispatchOnLoading(true);
+        }
+
+        if (hasChanged && this.engine) {
+            // set advanced filters needs access to the latest coveoAdvancedQueryConfig
+            this.setAdvancedFilters(this.engine);
+            this.submitSearch(true);
+        }
+    }
+
+    @api
+    public fetchMoreResults() {
+        if (this.resultList?.state?.moreResultsAvailable) {
+            this.fetchingMoreResults = true;
+            this.resultList.fetchMoreResults();
+        }
+    }
+
+    @api
+    setInputValue(searchTerm: string) {
+        if (searchTerm !== this.value) {
+            this.value = searchTerm || "";
+            this.handleValueChange(true);
+        }
+    }
+
+    private _coveoAdvancedQueryConfig!: { [key: string]: any };
+    private dropdownRequestedOpen: boolean = false;
+    private recentSearches: Option[] = [];
+    private unsubscribeFromResultList: Unsubscribe = () => {};
+    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 fetchingMoreResults: boolean = false;
+    private didRender = false;
+
+    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.value
+        );
+    }
+
+    constructor() {
+        super();
+
+        this.updateRecentSearches();
+        this.value = getSidebarSearchParams() || "";
+    }
+
+    disconnectedCallback() {
+        this.unsubscribeFromResultList();
+    }
+
+    renderedCallback() {
+        // in prod some of the critical coveo configuration attributes seem to arrive later
+        // so I needed to put this coveo startup flow here where we can wait for them to arrive
+
+        if (this.hasCorrectCoveoConfig && !this.engine) {
+            this.initializeUserSession();
+            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
+                }
+            );
+        }
+
+        // If this is the first render and there is a search value, trigger
+        // term highlighting
+        if (!this.didRender && this.value) {
+            this.dispatchHighlightedTermChange();
+        }
+
+        this.didRender = true;
+    }
+
+    private initializeUserSession() {
+        const stringified = window.sessionStorage.getItem(SESSION_KEY);
+
+        if (!stringified) {
+            return;
+        }
+
+        try {
+            const json = JSON.parse(stringified);
+
+            const hasSameConfig = Object.entries(
+                json.coveoAdvancedQueryConfig
+            ).every(
+                ([key, value]: [string, any]) =>
+                    this.coveoAdvancedQueryConfig[key] === value
+            );
+            const hasSameQuery = json?.state?.query?.q === this.value;
+
+            if (hasSameConfig && hasSameQuery) {
+                this.preloadedState = json?.state;
+            } else {
+                window.sessionStorage.removeItem(SESSION_KEY);
+            }
+        } catch (e) {
+            console.error(e);
+            window.sessionStorage.removeItem(SESSION_KEY);
+        }
+    }
+
+    private initializeCoveo = () => {
+        try {
+            this.engine = buildSearchEngine({
+                organizationId: this.coveoOrganizationId,
+                publicAccessToken: this.coveoPublicAccessToken,
+                searchHub: this.coveoSearchHub,
+                preloadedState: this.preloadedState
+            });
+        } catch (ex) {
+            console.error(`Coveo engine failed to initialize (${ex})`);
+        }
+
+        if (!this.engine) {
+            console.error("Coveo engine failed to initialize!");
+            return;
+        }
+
+        if (this.preloadedState) {
+            const actions = loadQueryActions(this.engine);
+            this.engine.dispatch(actions.updateQuery({ q: this.value || "" }));
+        }
+
+        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.unsubscribeFromResultList = this.resultList?.subscribe(
+            this.onResultListChange
+        );
+
+        if (this.value) {
+            this.dispatchHighlightedTermChange();
+        }
+
+        if (!this.preloadedState) {
+            if (this.value) {
+                this.submitSearch();
+            } else {
+                this.dispatchOnLoading(false);
+            }
+        }
+    };
+
+    private onResultListChange = () => {
+        if (!this.resultList) {
+            return;
+        }
+
+        const { isLoading, firstSearchExecuted, results } =
+            this.resultList.state;
+
+        if ((!firstSearchExecuted && !isLoading) || !this.value) {
+            // coveo search is firing off some unwanted payloads on startup
+            return;
+        }
+
+        if (!isLoading) {
+            this.dispatchOnChangeEvent(results);
+        }
+
+        if (!this.fetchingMoreResults) {
+            this.dispatchOnLoading(isLoading);
+        }
+
+        if (!isLoading && this.fetchingMoreResults) {
+            this.fetchingMoreResults = false;
+        }
+    };
+
+    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): SidebarSearchResult => {
+        // discussion about this normalization here: https://salesforce-internal.slack.com/archives/C020S6784JX/p1639506238376600
+
+        let pathname, queryParam;
+        if (sfhtml_url__c) {
+            pathname = `/docs/${sfhtml_url__c}`;
+        } else {
+            const isNestedGuide = clickUri.includes("/guide/");
+            const url = new URL(clickUri);
+            const extension =
+                isNestedGuide && !url.pathname?.endsWith(".html")
+                    ? ".html"
+                    : "";
+            pathname = `${url.pathname}${extension}`;
+            queryParam = url.search;
+        }
+
+        let href;
+        let isSelected = false;
+        const isReferenceUrl = clickUri.includes("/references/");
+        if (isReferenceUrl) {
+            if (queryParam) {
+                href = `${pathname}${queryParam}&q=${this.value}`;
+            } else {
+                href = `${pathname}?q=${this.value}`;
+            }
+
+            //NOTE: This is specific to references related comparison
+            const resultHrefWithMetaQuery = `${pathname}${queryParam}`;
+
+            const urlParams = new URLSearchParams(window.location.search);
+            const metaQueryParam = urlParams.get("meta");
+
+            let currentUrlPathWithQuery = window.location.pathname;
+            if (metaQueryParam) {
+                currentUrlPathWithQuery = `${currentUrlPathWithQuery}?meta=${metaQueryParam}`;
+            }
+
+            isSelected = resultHrefWithMetaQuery === currentUrlPathWithQuery;
+        } else {
+            href = `${pathname}?q=${this.value}`;
+            isSelected = pathname === window.location.pathname;
+        }
+
+        return {
+            title,
+            titleHighlights,
+            excerpt,
+            excerptHighlights,
+            uniqueId,
+            href,
+            selected: isSelected
+        };
+    };
+
+    private updateSessionStorage() {
+        window.sessionStorage.setItem(
+            SESSION_KEY,
+            JSON.stringify({
+                coveoAdvancedQueryConfig: this.coveoAdvancedQueryConfig,
+                state: 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: string) => ({
+            id: item,
+            label: item
+        })));
+
+    private dispatchSidebarSearchChange(searchTerm: string | undefined): void {
+        this.dispatchEvent(
+            new CustomEvent("sidebarsearchchange", {
+                detail: searchTerm ?? "",
+                bubbles: true,
+                composed: true
+            })
+        );
+    }
+
+    private submitSearch = debounce((isSyncingSearchValue = false) => {
+        if (this.searchBox) {
+            UserRecentSearches.add(this.value);
+            this.updateRecentSearches();
+
+            // When `isSyncingSearchValue` is true, we are submitting in a case
+            // where the search box is already synced correctly.
+            if (!isSyncingSearchValue) {
+                this.dispatchSidebarSearchChange(this.value);
+            }
+
+            this.searchBox.updateText(this.value || "");
+            this.searchBox.submit();
+        }
+    }, SEARCH_DEBOUNCE_DELAY);
+
+    private onClickRecentSearch(e: CustomEvent) {
+        this.value = e.detail;
+        this.dispatchSidebarSearchChange(this.value);
+        this.submitSearch(true);
+    }
+
+    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;
+
+        this.handleValueChange(false);
+        this.dispatchHighlightedTermChange();
+    }
+
+    private onInputFocus() {
+        this.dropdownRequestedOpen = true;
+    }
+
+    private onInputClear() {
+        this.dropdownRequestedOpen = false;
+    }
+
+    private handleValueChange(isSyncingSearchValue = false) {
+        if (this.value) {
+            this.dispatchOnLoading(true);
+            if (this.searchBox) {
+                this.submitSearch(isSyncingSearchValue);
+            }
+        } else {
+            // coveo's reaction to an empty value triggers a return of results
+            // bootlegging our own ux here`
+            this.dispatchOnLoading(false);
+            this.dispatchOnChangeEvent([]);
+            // Empty search values are not submitted for search, so we need to manually
+            // trigger a search change on our own here
+            this.dispatchSidebarSearchChange(this.value);
+        }
+    }
+}

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

@@ -0,0 +1,36 @@
+@import "dxHelpers/reset";
+@import "dxHelpers/text";
+@import "dxHelpers/commonTreeItem";
+
+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,70 @@
+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 }, i) => {
+        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
+        };
+
+        let chunks =
+            plainValue.length > 0
+                ? [...acc, plainChunk, boldChunk]
+                : [...acc, boldChunk];
+
+        const remaining = value.slice(endIndex);
+        if (remaining.length > 0 && highlights.length - 1 === i) {
+            chunks = [
+                ...chunks,
+                {
+                    value: remaining,
+                    id: value.length
+                }
+            ];
+        }
+
+        return chunks;
+    }, []);
+};
+
+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/skipNavLink/skipNavLink.css

@@ -0,0 +1,21 @@
+@import "dxHelpers/text";
+
+a {
+    left: 0;
+    top: 0;
+    position: absolute;
+    padding: 0 var(--dx-g-spacing-mlg);
+    height: var(--dx-g-spacing-3xl);
+    transform: translateY(-1000%);
+    background: var(--dx-g-indigo-natural-20);
+    border-radius: 0 5px 5px 0;
+    z-index: 100000000;
+    text-decoration: none;
+    display: flex;
+    justify-content: center;
+    align-items: center;
+}
+
+a:focus {
+    transform: translateY(var(--dx-g-spacing-xl));
+}

package/src/modules/dx/skipNavLink/skipNavLink.html

@@ -0,0 +1,3 @@
+<template>
+    <a class="dx-text-button-light" href="#maincontent">Skip Navigation</a>
+</template>

package/src/modules/dx/skipNavLink/skipNavLink.ts

@@ -0,0 +1,3 @@
+import { LightningElement } from "lwc";
+
+export default class SkipNavLink extends LightningElement {}

package/src/modules/dx/socials/socials.css

@@ -0,0 +1,35 @@
+:host {
+    display: inline-block;
+}
+
+.details-section {
+    color: var(--dx-g-gray-30);
+    font-family: var(--dx-g-font-display);
+    font-size: var(--dx-g-text-xs);
+    letter-spacing: 0.7px;
+    margin-bottom: var(--dx-g-spacing-sm);
+    text-transform: uppercase;
+}
+
+.details-section span {
+    display: block;
+    line-height: var(--dx-g-spacing-md);
+}
+
+.socials-group {
+    display: flex;
+}
+
+.socials-group a:not(:last-child) {
+    margin-right: var(--dx-g-spacing-md);
+}
+
+dx-icon-badge {
+    --dx-c-icon-badge-background-color: var(--dx-g-blue-vibrant-50);
+    --dx-c-icon-badge-size: 34px;
+    --dx-c-icon-badge-icon-size: 18px;
+}
+
+dx-icon-badge:hover {
+    --dx-c-icon-badge-background-color: var(--dx-g-blue-vibrant-40);
+}

package/src/modules/dx/socials/socials.html

@@ -0,0 +1,22 @@
+<template>
+    <div class="details-section" if:true={hasDetails}>
+        <template for:each={details} for:item="detail">
+            <span key={detail}>{detail}</span>
+        </template>
+    </div>
+    <div class="socials-group">
+        <template for:each={socials} for:item="social">
+            <a
+                href={social.href}
+                key={social.name}
+                target={linksTarget}
+                title={social.name}
+            >
+                <dx-icon-badge
+                    sprite={spriteName}
+                    symbol={social.symbol}
+                ></dx-icon-badge>
+            </a>
+        </template>
+    </div>
+</template>