@salesforcedevs/docs-components 1.3.205 → 1.3.209-alpha1

package/src/modules/doc/xmlContent/baseContentElement.ts

@@ -0,0 +1,787 @@
+/* eslint-disable @lwc/lwc/no-document-query */
+import { api, track } from "lwc";
+import { normalizeBoolean } from "dxUtils/normalizers";
+import { FetchContent } from "./utils";
+import {
+    CoveoAdvancedQueryXMLConfig,
+    DocLanguage,
+    DocVersion,
+    TreeNode,
+    Header,
+    HistoryState,
+    PageReference,
+    TocMap
+} from "./types";
+import { SearchSyncer } from "docUtils/searchSyncer";
+import { LightningElementWithState } from "dxBaseElements/lightningElementWithState";
+import { logCoveoPageView, oldVersionDocInfo } from "docUtils/utils";
+import { Breadcrumb, DocPhaseInfo, Language } from "typings/custom";
+import { track as trackGTM } from "dxUtils/analytics";
+
+// TODO: Imitating from actual implementation as doc-content use it like this. We should refactor it later.
+const handleContentError = (error: any): void => console.log(error);
+
+const PIXEL_PER_CHARACTER_MAP: { [key: string]: number } = {
+    default: 7.7,
+    "ja-jp": 12.5
+};
+
+export abstract class BaseContentElement extends LightningElementWithState<{
+    isFetchingDocument: boolean;
+    isFetchingContent: boolean;
+    lastHighlightedSearch: string;
+    internalLinkClicked: boolean;
+}> {
+    @api apiDomain = "https://developer.salesforce.com";
+    @api coveoOrganizationId!: string;
+    @api coveoPublicAccessToken!: string;
+    @api coveoAnalyticsToken!: string;
+    @api coveoSearchHub!: string;
+
+    @api
+    get allLanguages(): Array<Language> {
+        return this._allLanguages;
+    }
+
+    set allLanguages(value: string) {
+        if (value) {
+            this._allLanguages = JSON.parse(value);
+        }
+    }
+
+    @api
+    get enableCoveo() {
+        return this._enableCoveo;
+    }
+
+    set enableCoveo(value) {
+        this._enableCoveo = normalizeBoolean(value);
+    }
+
+    availableLanguages: Array<DocLanguage> = [];
+    availableVersions: Array<DocVersion> = [];
+    contentProvider?: FetchContent;
+    docContent = "";
+    language?: DocLanguage | null = null;
+    private loaded = false;
+    pdfUrl = "";
+    tocMap: TocMap = {};
+    sidebarContent: Array<TreeNode> | null = null;
+    version: DocVersion | null = null;
+    docTitle = "";
+    private _pathName = "";
+    private _pageHeader?: Header;
+    private listenerAttached = false;
+    private _enableCoveo?: boolean = false;
+
+    private searchSyncer = new SearchSyncer({
+        callbacks: {
+            onSearchChange: (nextSearchString: string): void => {
+                if (nextSearchString !== this.pageReference.search) {
+                    this.updatePageReference({
+                        ...this.pageReference,
+                        search: nextSearchString
+                    });
+                }
+                if (nextSearchString !== this.state.lastHighlightedSearch) {
+                    this.updateHighlighting(
+                        new URLSearchParams(nextSearchString).get("q") || ""
+                    );
+                }
+            },
+            onUrlChange: (nextSearchString: string): void => {
+                if (nextSearchString !== this.pageReference.search) {
+                    this.updatePageReference({
+                        ...this.pageReference,
+                        search: nextSearchString
+                    });
+                }
+                const nextSearchParam =
+                    new URLSearchParams(nextSearchString).get("q") || "";
+                this.updateSearchInput(nextSearchParam);
+                if (nextSearchString !== this.state.lastHighlightedSearch) {
+                    this.updateHighlighting(nextSearchParam);
+                }
+            }
+        },
+        eventName: "sidebarsearchchange",
+        historyMethod: window.history.pushState,
+        searchParam: "q",
+        shouldStopPropagation: true,
+        target: window
+    });
+    private _allLanguages: Array<Language> = [];
+
+    get oldVersionInfo(): DocPhaseInfo | null {
+        let info = null;
+        if (!this.disableVersion) {
+            const currentGAVersion = this.versionOptions.find(
+                (version) => !version.url.includes(version.id)
+            );
+            if (currentGAVersion?.link?.href && this.version?.id) {
+                const versionNo = currentGAVersion.id;
+                /**
+                 * Need to show old version doc banner only if the version is less than the current ga version
+                 * We should not show it to the preview version whose version is more than ga
+                 **/
+                try {
+                    if (parseFloat(this.version.id) < parseFloat(versionNo)) {
+                        info = oldVersionDocInfo(currentGAVersion.link.href);
+                    }
+                } catch (exception) {
+                    /* Ideally this use case should not happen, but just added to not to break the page*/
+                    console.warn(exception);
+                }
+            }
+        }
+        return info;
+    }
+
+    @track showVersionBanner = false;
+
+    @track pageReference: PageReference = {};
+    @track breadcrumbs: Array<Breadcrumb> = [];
+
+    constructor() {
+        super();
+        this.pageReference = this.getReferenceFromUrl();
+        // In order to prevent dispatching unnecessary highlight changes, we
+        // track these items and use their previous values for comparisons in
+        // `renderedCallback`:
+        this.state = {
+            isFetchingContent: false,
+            isFetchingDocument: false,
+            lastHighlightedSearch: "",
+            internalLinkClicked: false
+        };
+    }
+
+    connectedCallback(): void {
+        if (!this.pageReference?.deliverable) {
+            window.location.href = "/docs";
+            return;
+        }
+        this.contentProvider = new FetchContent(
+            this.apiDomain,
+            this.allLanguages
+        );
+        this.fetchDocument().then(() => (this.loaded = true));
+        window.addEventListener("popstate", this.handlePopState);
+
+        this.searchSyncer.init();
+    }
+
+    renderedCallback(): void {
+        this.setState({ internalLinkClicked: true });
+        const urlSectionLink =
+            this.pageReference?.hash?.split("#").length! > 1
+                ? this.pageReference.hash!.split("#")[1]
+                : this.pageReference?.hash;
+
+        const contentEl = this.template.querySelector("doc-content");
+        const anchorEl =
+            urlSectionLink &&
+            (contentEl?.shadowRoot?.querySelector(`[id='${urlSectionLink}']`) ||
+                contentEl?.shadowRoot?.querySelector(
+                    `[name='${urlSectionLink}']`
+                ));
+
+        if (anchorEl) {
+            anchorEl.scrollIntoView();
+
+            this.setState({ internalLinkClicked: false });
+        }
+
+        if (
+            (this.prevState.isFetchingContent &&
+                !this.state.isFetchingContent) ||
+            (this.prevState.isFetchingDocument &&
+                !this.state.isFetchingDocument)
+        ) {
+            const prevSearchParam =
+                new URLSearchParams(this.state.lastHighlightedSearch).get(
+                    "q"
+                ) || "";
+            const nextSearchParam =
+                new URLSearchParams(this.pageReference.search).get("q") || "";
+            this.updateHighlighting(nextSearchParam);
+            if (prevSearchParam !== nextSearchParam) {
+                this.updateSearchInput(nextSearchParam);
+            }
+        }
+    }
+
+    disconnectedCallback(): void {
+        window.removeEventListener("popstate", this.handlePopState);
+        this.searchSyncer.dispose();
+        if (this.listenerAttached) {
+            this.pageHeader.removeEventListener(
+                "langchange",
+                this.handleLanguageChange
+            );
+            this.listenerAttached = false;
+        }
+    }
+
+    private get languageId(): string | undefined {
+        return this.language?.id.replace("-", "_");
+    }
+
+    private get releaseVersionId(): string | undefined {
+        return this.version?.id;
+    }
+
+    private get deliverable(): string | undefined {
+        return this.pageReference.deliverable;
+    }
+
+    private get useOldSidebar(): boolean {
+        // Coveo is enabled and the version is greater than  51 (within the latest 3 versions)
+        // TODO: we need a better fix for version number check
+        return !(
+            this.enableCoveo &&
+            this.coveoOrganizationId &&
+            this.coveoPublicAccessToken &&
+            (!this.version?.releaseVersion ||
+                (this.version?.releaseVersion &&
+                    parseInt(
+                        this.version.releaseVersion.replace("v", ""),
+                        10
+                    ) >= 53))
+        );
+    }
+
+    private get coveoAdvancedQueryConfig(): CoveoAdvancedQueryXMLConfig {
+        const config: {
+            locale?: string;
+            topicid?: string;
+            version?: string;
+        } = {
+            locale: this.languageId,
+            topicid: this.deliverable
+        };
+
+        if (this.releaseVersionId && this.releaseVersionId !== "noversion") {
+            config.version = this.releaseVersionId;
+        }
+
+        return config;
+    }
+
+    private get pageHeader(): Header {
+        if (!this._pageHeader) {
+            this._pageHeader = document.querySelector("doc-header")!;
+        }
+
+        return this._pageHeader;
+    }
+
+    private get sidebarValue(): string {
+        if (this.pageReference?.contentDocumentId) {
+            const hashedUri = `${
+                this.pageReference.contentDocumentId
+            }${this.normalizeHash(this.pageReference.hash)}`;
+            if (hashedUri in this.tocMap) {
+                return hashedUri;
+            }
+
+            if (this.pageReference.contentDocumentId in this.tocMap) {
+                return this.pageReference.contentDocumentId;
+            }
+        }
+
+        return "";
+    }
+
+    private get disableVersion(): boolean {
+        return !this.availableVersions || this.availableVersions.length <= 1;
+    }
+
+    private get versionOptions(): Array<DocVersion> {
+        return this.disableVersion
+            ? this.availableVersions
+            : this.availableVersions.map((version) => ({
+                  ...version,
+                  link: {
+                      href: this.pageReferenceToString({
+                          ...this.pageReference,
+                          docId: version.url
+                      })
+                  }
+              }));
+    }
+
+    private get breadcrumbPixelPerCharacter() {
+        return (
+            PIXEL_PER_CHARACTER_MAP[this.language!.id] ||
+            PIXEL_PER_CHARACTER_MAP.default
+        );
+    }
+
+    private get ANALYTICS_PAYLOAD() {
+        return {
+            element_title: "version picker",
+            content_category: "cta"
+        };
+    }
+
+    private handlePopState = (event: PopStateEvent): void =>
+        this.updatePageReference(this.getReferenceFromUrl(), event);
+
+    handleDismissVersionBanner() {
+        this.showVersionBanner = false;
+    }
+
+    handleSelect(event: CustomEvent<{ name: string }>): void {
+        event.stopPropagation();
+        const { name } = event.detail;
+
+        if (this.sidebarValue === name) {
+            return;
+        }
+
+        if (name) {
+            const hashIndex = name.indexOf("#");
+            const hash = hashIndex > -1 ? name.slice(hashIndex) : "";
+
+            const contentDocumentId =
+                hashIndex > -1 ? name.slice(0, hashIndex) : name;
+            this.updatePageReference({
+                ...this.pageReference,
+                contentDocumentId,
+                hash
+            });
+            this.updateUrl();
+        }
+    }
+
+    handleNavClick(event: CustomEvent<{ pageReference: PageReference }>): void {
+        event.stopPropagation();
+        const { pageReference } = event.detail;
+        this.updatePageReference(pageReference);
+        this.updateUrl();
+    }
+
+    handleLanguageChange = (event: any) => {
+        if (this.language && this.language.id === event.detail) {
+            return;
+        }
+
+        this.language = this.availableLanguages.find(
+            ({ id }) => id === event.detail
+        );
+        this.pageReference.docId = this.language!.url;
+
+        trackGTM(event.target!, "custEv_ctaLinkClick", {
+            click_text: event.detail,
+            element_title: "language selector",
+            click_url: `${window.location.origin}${this.pageReferenceToString(
+                this.pageReference
+            )}`,
+            element_type: "link",
+            content_category: "cta"
+        });
+
+        this.updateUrl();
+        this.fetchDocument();
+    };
+
+    updatePageReference(
+        newPageReference: PageReference,
+        event: PopStateEvent | undefined = undefined
+    ): void {
+        this.pageReference.hash = newPageReference.hash;
+        this.pageReference.search = newPageReference.search;
+
+        if (this.isSamePage(newPageReference)) {
+            return;
+        }
+
+        const isSameDocId = this.pageReference.docId === newPageReference.docId;
+        this.pageReference = newPageReference;
+
+        if (!isSameDocId) {
+            this.fetchDocument();
+            return;
+        }
+
+        this.fetchContent()
+            .then(() => {
+                this.buildBreadcrumbs();
+                document.body.scrollTop = event?.state?.scroll?.value || 0;
+            })
+            .catch(handleContentError);
+    }
+
+    abstract getReferenceFromUrl(): PageReference;
+    // getReferenceFromUrl(): PageReference {
+    //     const [
+    //         page,
+    //         docId,
+    //         deliverable,
+    //         contentDocumentId
+    //     ] = window.location.pathname.substr(1).split("/");
+
+    //     const { origin: domain, hash, search } = window.location;
+
+    //     return {
+    //         contentDocumentId,
+    //         deliverable,
+    //         docId,
+    //         domain,
+    //         hash,
+    //         page,
+    //         search
+    //     };
+    // }
+
+    isSamePage(reference: PageReference): boolean {
+        return (
+            this.pageReference.contentDocumentId ===
+                reference.contentDocumentId &&
+            this.pageReference.docId === reference.docId &&
+            this.pageReference.page === reference.page &&
+            this.pageReference.deliverable === reference.deliverable
+        );
+    }
+
+    abstract fetchDocument(): Promise<void>;
+    abstract fetchContent(): Promise<void>;
+    // async fetchDocument(): Promise<void> {
+    //     this.setState({
+    //         isFetchingDocument: true
+    //     });
+    //     const data = await this.contentProvider!.fetchDocumentData(
+    //         this.pageReference.docId!
+    //     );
+
+    //     // This could be a 404 scenario.
+    //     if (!data) {
+    //         this.setState({
+    //             isFetchingDocument: false
+    //         });
+    //         return;
+    //     }
+
+    //     this.docTitle = data.docTitle;
+    //     this.tocMap = data.tocMap;
+    //     this.sidebarContent = data.toc;
+    //     this.version = data.version;
+    //     this.language = data.language;
+    //     this.availableLanguages = data.availableLanguages;
+    //     this.availableVersions = data.availableVersions;
+    //     this.pdfUrl = data.pdfUrl;
+
+    //     this.updateHeader();
+
+    //     this.buildBreadcrumbs();
+
+    //     if (this.pageReference.deliverable !== data.deliverable) {
+    //         this.pageReference.deliverable = data.deliverable;
+    //         this.updateUrl(HistoryState.REPLACE_STATE);
+    //     }
+
+    //     if (this.oldVersionInfo) {
+    //         this.showVersionBanner = true;
+    //     }
+
+    //     if (
+    //         this.pageReference?.contentDocumentId?.replace(/\.htm$/, "") !==
+    //         data.id
+    //     ) {
+    //         try {
+    //             await this.fetchContent();
+    //             this.setState({
+    //                 isFetchingDocument: false
+    //             });
+    //             return;
+    //         } catch (error) {
+    //             this.pageReference.contentDocumentId = `${data.id}.htm`;
+    //             this.pageReference.hash = "";
+    //             this.pageReference.search = "";
+    //             this.updateUrl(HistoryState.REPLACE_STATE);
+    //         }
+    //     }
+
+    //     this.docContent = data.content;
+    //     this.addMetatags();
+    //     this.setState({
+    //         isFetchingDocument: false
+    //     });
+    // }
+
+    // async fetchContent(): Promise<void> {
+    //     this.setState({
+    //         isFetchingContent: true
+    //     });
+    //     const data = await this.contentProvider!.fetchContent(
+    //         this.pageReference.deliverable!,
+    //         this.pageReference.contentDocumentId!,
+    //         {
+    //             language: this.language!.id,
+    //             version: this.version!.id
+    //         }
+    //     );
+
+    //     if (data) {
+    //         this.docContent = data.content;
+    //         this.addMetatags();
+
+    //         if (!this.pageReference.hash) {
+    //             document.body.scrollIntoView();
+    //         }
+    //     }
+    //     this.setState({
+    //         isFetchingContent: false
+    //     });
+    // }
+
+    updateHeader(): void {
+        if (!this.pageHeader) {
+            return;
+        }
+
+        if (this.docTitle) {
+            this.pageHeader.subtitle = this.docTitle;
+        }
+
+        if (this.pdfUrl) {
+            this.pageHeader.bailHref = this.pdfUrl;
+            this.pageHeader.bailLabel = "PDF";
+        }
+
+        if (!this.listenerAttached) {
+            this.pageHeader.addEventListener(
+                "langchange",
+                this.handleLanguageChange
+            );
+            this.listenerAttached = true;
+        }
+
+        this.pageHeader.languages = this.availableLanguages;
+        this.pageHeader.language = this.language?.id;
+
+        if (this.pageReference) {
+            const { docId, deliverable, page } = this.pageReference;
+            this.pageHeader.headerHref = `/${page}/${docId}/${deliverable}/`;
+        }
+    }
+
+    updateUrl(method = HistoryState.PUSH_STATE): void {
+        //TODO: Revert this commenting - commented to work on storybook - window object is not working there.
+        
+        //logCoveoPageView(this.coveoOrganizationId, this.coveoAnalyticsToken);
+        // window.history[method](
+        //     {},
+        //     "docs",
+        //     this.pageReferenceToString(this.pageReference)
+        // );
+    }
+
+    private updateHighlighting(searchParam: string): void {
+        this.dispatchHighlightChange(searchParam);
+        this.setState({
+            lastHighlightedSearch: this.pageReference.search
+        });
+    }
+
+    private updateSearchInput(searchParam: string): void {
+        (this.template.querySelector(
+            "doc-content-layout"
+        ) as any)?.setSidebarInputValue(searchParam);
+    }
+
+    private pageReferenceToString(reference: PageReference): string {
+        const {
+            page,
+            docId,
+            deliverable,
+            contentDocumentId,
+            hash,
+            search
+        } = reference;
+        return `/${page}/${docId}/${deliverable}/${contentDocumentId}${this.normalizeSearch(
+            search!
+        )}${this.normalizeHash(hash)}`;
+    }
+
+    private normalizeUrlPart(
+        part: string | undefined,
+        sentinel: string
+    ): string {
+        return (
+            (part &&
+                (part.startsWith(sentinel!) ? part : `${sentinel}${part}`)) ||
+            ""
+        );
+    }
+
+    private normalizeSearch(search: string): string {
+        return this.normalizeUrlPart(search, "?");
+    }
+
+    private normalizeHash(hash?: string): string {
+        return this.normalizeUrlPart(hash, "#");
+    }
+
+    private getComposedTitle(
+        topicTitle: string | null | undefined,
+        docTitle: string | undefined
+    ): string {
+        // map to avoid duplicates
+        const titleMap: { [key: string]: any } = {};
+        if (topicTitle) {
+            // sometimes the h1 tag text (which is docSubTitle) contains text with new line character. For e.g, "Bulk API 2.0 Older\n  Documentation",
+            // here it contains \n in the text context which needs to be removed
+            // also, there are multiple spaces in between the text, which needs to be replaced with a single space
+            const docTopicTitle = topicTitle
+                .replace(/[\t\r\n]/g, " ")
+                .replace(/ +/g, " ")
+                .trim();
+            titleMap[docTopicTitle] = true;
+        }
+
+        if (docTitle) {
+            titleMap[docTitle] = true;
+        }
+
+        titleMap["Salesforce Developers"] = true;
+
+        return Object.keys(titleMap).join(" | ");
+    }
+
+    private dispatchHighlightChange(term: string): void {
+        this.dispatchEvent(
+            new CustomEvent("highlightedtermchange", {
+                detail: term,
+                bubbles: true,
+                composed: true
+            })
+        );
+    }
+
+    get showBreadcrumbs(): boolean {
+        return this.breadcrumbs && this.breadcrumbs.length > 1;
+    }
+
+    buildBreadcrumbs(): void {
+        const { contentDocumentId } = this.pageReference;
+        if (!contentDocumentId) {
+            return;
+        }
+
+        const currentNode = this.tocMap[contentDocumentId];
+
+        if (currentNode?.parent) {
+            this.breadcrumbs = this.nodeToBreadcrumb(currentNode);
+        } else {
+            this.breadcrumbs = [];
+        }
+    }
+
+    private nodeToBreadcrumb(node: TreeNode): Breadcrumb[] {
+        const item = {
+            href: this.pageReferenceToString({
+                ...this.pageReference,
+                contentDocumentId: node.name
+            }),
+            label: node.label
+        };
+
+        if (node.parent) {
+            return [...this.nodeToBreadcrumb(node.parent), item];
+        }
+
+        return [item];
+    }
+
+    // This method take docId and drops the version from the docId.
+    // Example:
+    // Takes input string: docId = "atlas.en-us.238.0.b2b_b2c_comm_dev.meta"
+    // Output string: filteredDocId = "atlas.en-us.b2b_b2c_comm_dev.meta"
+    dropVersionFromDocId(docId: string): string {
+        if (!this.version?.id) {
+            return docId;
+        }
+
+        const curVersion = this.version.id + ".";
+        const filteredDocId = docId.replace(curVersion, "");
+        return filteredDocId;
+    }
+
+    addMetatags(): void {
+        const div = document.createElement("div");
+        div.innerHTML = this.docContent;
+        const docDescription = div.querySelector(".shortdesc")?.textContent;
+        const topicTitle = div.querySelector("h1")?.textContent;
+
+        const title = document.querySelector("title");
+        const composedTitle = this.getComposedTitle(topicTitle, this.docTitle);
+
+        if (title) {
+            title.textContent = composedTitle;
+        }
+        const metatitle = document.querySelector('meta[name="title"]');
+        if (metatitle) {
+            metatitle.setAttribute("content", composedTitle);
+        }
+
+        if (docDescription) {
+            const metadescription = document.querySelector(
+                'meta[name="description"]'
+            );
+            if (metadescription) {
+                metadescription.setAttribute("content", docDescription);
+            }
+        }
+
+        if (this.pageReference) {
+            const metadescription = document.querySelector(
+                'link[rel="canonical"]'
+            );
+            if (metadescription) {
+                const copyPageReference = { ...this.pageReference };
+                copyPageReference.docId = copyPageReference.docId
+                    ? this.dropVersionFromDocId(copyPageReference.docId)
+                    : copyPageReference.docId;
+                metadescription.setAttribute(
+                    "href",
+                    window.location.protocol +
+                        "//" +
+                        window.location.host +
+                        this.pageReferenceToString(copyPageReference)
+                );
+            }
+        }
+
+        this.addNoIndexMetaForOlderDocVersions();
+    }
+
+    /**
+     * Method adds noindex, follow meta tag to the older Couch DB doc pages.
+     * Fixes W-12547462.
+     */
+    private addNoIndexMetaForOlderDocVersions() {
+        // eslint-disable-next-line @lwc/lwc/no-document-query
+        const headTag = document.getElementsByTagName("head");
+        // this checks if the selected version is not the latest version,
+        // then it adds the noindex, follow meta tag to the older version pages.
+        const versionId = this.version!.id;
+        const docId = this.pageReference.docId;
+
+        // SEO fix:
+        // Doc id without version id is always considered latest and should be used for SEO.
+        // Condition is to find a docId which includes version id,
+        // these docs are always considered as old and should not be indexed including the preview docs.
+        if (
+            headTag.length &&
+            docId?.includes(versionId) &&
+            !document.querySelector('meta[name="robots"]')
+        ) {
+            const robotsMeta = document.createElement("meta");
+            robotsMeta.setAttribute("name", "robots");
+            robotsMeta.setAttribute("content", "noindex, follow");
+            headTag[0].appendChild(robotsMeta);
+        }
+    }
+}