@salesforcedevs/docs-components 0.0.0 → 0.0.1-superscript

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

@@ -1,36 +1,47 @@
+/* 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,
+    SiderbarFooter,
     HistoryState,
     PageReference,
-    TocMap
+    TocMap,
+    ContentData
 } from "./types";
-import { SearchSyncer } from "docUtils/SearchSyncer";
-import { LightningElementWithState } from "docBaseElements/lightningElementWithState";
-import { Breadcrumb, Language } from "typings/custom";
+import { SearchSyncer } from "docUtils/searchSyncer";
+import { LightningElementWithState } from "dxBaseElements/lightningElementWithState";
+import { oldVersionDocInfo } from "docUtils/utils";
+import { Breadcrumb, DocPhaseInfo, Language } from "typings/custom";
+import { track as trackGTM } from "dxUtils/analytics";
+import DOMPurify from "dompurify";
 
 // TODO: Imitating from actual implementation as doc-content use it like this. We should refactor it later.
-const handleContentError = (error): void => console.log(error);
+const handleContentError = (error: any): void => console.log(error);
 
 const PIXEL_PER_CHARACTER_MAP: { [key: string]: number } = {
     default: 7.7,
     "ja-jp": 12.5
 };
 
+const defaultSidebarFooter: SiderbarFooter = {
+    bailHref: "",
+    bailLabel: "",
+    languages: [],
+    language: ""
+};
 export default class DocXmlContent extends LightningElementWithState<{
     isFetchingDocument: boolean;
     isFetchingContent: boolean;
     lastHighlightedSearch: string;
+    internalLinkClicked: boolean;
 }> {
     @api apiDomain = "https://developer.salesforce.com";
-    @api coveoOrganizationId!: string;
-    @api coveoPublicAccessToken!: string;
+    @api hideFooter = false;
+    @api displayReadingTime = false;
 
     @api
     get allLanguages(): Array<Language> {
@@ -43,31 +54,32 @@ export default class DocXmlContent extends LightningElementWithState<{
         }
     }
 
-    @api
-    get enableCoveo() {
-        return this._enableCoveo;
-    }
-
-    set enableCoveo(value) {
-        this._enableCoveo = normalizeBoolean(value);
-    }
-
     private availableLanguages: Array<DocLanguage> = [];
-    private availableVersions: Array<DocVersion> = [];
-    private contentProvider: FetchContent;
+    @track private availableVersions: Array<DocVersion> = [];
+    private contentProvider?: FetchContent;
     private docContent = "";
-    private language: DocLanguage = null;
-    private loaded = false;
+    private language?: DocLanguage | null = null;
+    private displayContent = false;
+    private display404 = false;
+    private _pageHeader?: Header;
     private pdfUrl = "";
     private tocMap: TocMap = {};
-    private sidebarContent: Array<TreeNode> = null;
-    private version: DocVersion = null;
+    private sidebarContent: Array<TreeNode> | null = null;
+    private version: DocVersion | null = null;
     private docTitle = "";
-    private analyticsEvent = "custEv_ctaLinkClick";
     private _pathName = "";
-    private _pageHeader?: Header;
     private listenerAttached = false;
-    private _enableCoveo?: boolean = false;
+    private sidebarFooterContent: SiderbarFooter = { ...defaultSidebarFooter };
+    private latestVersion = false;
+    private previewVersion = false;
+
+    private get enableFooter(): boolean {
+        return !this.hideFooter;
+    }
+
+    private get computedReadingTime(): number | undefined {
+        return this.displayReadingTime ? this.readingTime : undefined;
+    }
 
     private searchSyncer = new SearchSyncer({
         callbacks: {
@@ -107,8 +119,40 @@ export default class DocXmlContent extends LightningElementWithState<{
     });
     private _allLanguages: Array<Language> = [];
 
+    private 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);
+                    } else if (
+                        parseFloat(this.version.id) > parseFloat(versionNo)
+                    ) {
+                        this.previewVersion = true;
+                    }
+                } 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 private pageReference: PageReference = {};
     @track breadcrumbs: Array<Breadcrumb> = [];
+    @track readingTime?: number;
 
     constructor() {
         super();
@@ -133,7 +177,13 @@ export default class DocXmlContent extends LightningElementWithState<{
             this.apiDomain,
             this.allLanguages
         );
-        this.fetchDocument().then(() => (this.loaded = true));
+        this.fetchDocument().then((content: any) => {
+            if (content) {
+                this.displayContent = true;
+            } else {
+                this.display404 = true;
+            }
+        });
         window.addEventListener("popstate", this.handlePopState);
 
         this.searchSyncer.init();
@@ -142,8 +192,8 @@ export default class DocXmlContent extends LightningElementWithState<{
     renderedCallback(): void {
         this.setState({ internalLinkClicked: true });
         const urlSectionLink =
-            this.pageReference?.hash?.split("#").length > 1
-                ? this.pageReference.hash.split("#")[1]
+            this.pageReference?.hash?.split("#").length! > 1
+                ? this.pageReference.hash!.split("#")[1]
                 : this.pageReference?.hash;
 
         const contentEl = this.template.querySelector("doc-content");
@@ -156,6 +206,7 @@ export default class DocXmlContent extends LightningElementWithState<{
 
         if (anchorEl) {
             anchorEl.scrollIntoView();
+
             this.setState({ internalLinkClicked: false });
         }
 
@@ -181,24 +232,17 @@ export default class DocXmlContent extends LightningElementWithState<{
     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 {
-        return this.language.id.replace("-", "_");
+    private get languageId(): string | undefined {
+        return this.language?.id.replace("-", "_");
     }
 
-    private get releaseVersionId(): string {
-        return this.version.id;
+    private get releaseVersionId(): string | undefined {
+        return this.version?.id;
     }
 
-    private get deliverable(): string {
+    private get deliverable(): string | undefined {
         return this.pageReference.deliverable;
     }
 
@@ -206,34 +250,16 @@ export default class DocXmlContent extends LightningElementWithState<{
         // 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))
+            !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");
+            this._pageHeader = document.querySelector("doc-header")!;
         }
 
         return this._pageHeader;
@@ -276,13 +302,24 @@ export default class DocXmlContent extends LightningElementWithState<{
 
     private get breadcrumbPixelPerCharacter() {
         return (
-            PIXEL_PER_CHARACTER_MAP[this.language.id] ||
+            PIXEL_PER_CHARACTER_MAP[this.language!.id] ||
             PIXEL_PER_CHARACTER_MAP.default
         );
     }
 
-    private handlePopState = (): void =>
-        this.updatePageReference(this.getReferenceFromUrl());
+    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();
@@ -314,7 +351,7 @@ export default class DocXmlContent extends LightningElementWithState<{
         this.updateUrl();
     }
 
-    handleLanguageChange = (event: CustomEvent<string>): Promise<void> => {
+    handleLanguageChange = (event: any) => {
         if (this.language && this.language.id === event.detail) {
             return;
         }
@@ -322,12 +359,26 @@ export default class DocXmlContent extends LightningElementWithState<{
         this.language = this.availableLanguages.find(
             ({ id }) => id === event.detail
         );
-        this.pageReference.docId = this.language.url;
+        this.pageReference.docId = this.language!.url;
+
+        trackGTM(event.target!, "custEv_linkClick", {
+            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): void {
+    updatePageReference(
+        newPageReference: PageReference,
+        event: PopStateEvent | undefined = undefined
+    ): void {
         this.pageReference.hash = newPageReference.hash;
         this.pageReference.search = newPageReference.search;
 
@@ -344,13 +395,26 @@ export default class DocXmlContent extends LightningElementWithState<{
         }
 
         this.fetchContent()
-            .then(() => this.buildBreadcrumbs())
+            .then(() => {
+                this.buildBreadcrumbs();
+                document.body.scrollTop = event?.state?.scroll?.value || 0;
+            })
             .catch(handleContentError);
     }
 
+    private sanitizeUrlPart(part: string | undefined): string | undefined {
+        if (!part) {
+            return part;
+        }
+        return DOMPurify.sanitize(part);
+    }
+
     getReferenceFromUrl(): PageReference {
         const [page, docId, deliverable, contentDocumentId] =
-            window.location.pathname.substr(1).split("/");
+            window.location.pathname
+                .substr(1)
+                .split("/")
+                .map(this.sanitizeUrlPart);
 
         const { origin: domain, hash, search } = window.location;
 
@@ -359,9 +423,9 @@ export default class DocXmlContent extends LightningElementWithState<{
             deliverable,
             docId,
             domain,
-            hash,
+            hash: this.sanitizeUrlPart(hash),
             page,
-            search
+            search: this.sanitizeUrlPart(search)
         };
     }
 
@@ -375,12 +439,13 @@ export default class DocXmlContent extends LightningElementWithState<{
         );
     }
 
-    async fetchDocument(): Promise<void> {
+    async fetchDocument(): Promise<string> {
         this.setState({
             isFetchingDocument: true
         });
-        const data = await this.contentProvider.fetchDocumentData(
-            this.pageReference.docId
+
+        const data = await this.contentProvider!.fetchDocumentData(
+            this.pageReference.docId!
         );
 
         // This could be a 404 scenario.
@@ -388,7 +453,7 @@ export default class DocXmlContent extends LightningElementWithState<{
             this.setState({
                 isFetchingDocument: false
             });
-            return;
+            return "";
         }
 
         this.docTitle = data.docTitle;
@@ -400,7 +465,7 @@ export default class DocXmlContent extends LightningElementWithState<{
         this.availableVersions = data.availableVersions;
         this.pdfUrl = data.pdfUrl;
 
-        this.updateHeader();
+        this.updateHeaderAndSidebarFooter();
 
         this.buildBreadcrumbs();
 
@@ -409,16 +474,22 @@ export default class DocXmlContent extends LightningElementWithState<{
             this.updateUrl(HistoryState.REPLACE_STATE);
         }
 
+        if (this.oldVersionInfo) {
+            this.showVersionBanner = true;
+        } else {
+            this.latestVersion = true;
+        }
+
         if (
             this.pageReference?.contentDocumentId?.replace(/\.htm$/, "") !==
             data.id
         ) {
             try {
-                await this.fetchContent();
+                const moreData = await this.fetchContent();
                 this.setState({
                     isFetchingDocument: false
                 });
-                return;
+                return moreData.content;
             } catch (error) {
                 this.pageReference.contentDocumentId = `${data.id}.htm`;
                 this.pageReference.hash = "";
@@ -428,43 +499,69 @@ export default class DocXmlContent extends LightningElementWithState<{
         }
 
         this.docContent = data.content;
+        this.calculateReadingTime(data.content);
         this.addMetatags();
         this.setState({
             isFetchingDocument: false
         });
+
+        // Track page view when a new document is loaded
+        trackGTM(this.template.host, "doc_page_view", {
+            page_path: this.pageReferenceToString(this.pageReference),
+            doc_id: this.pageReference.docId,
+            content_document_id: this.pageReference.contentDocumentId,
+            deliverable: this.pageReference.deliverable,
+            language: this.language?.id,
+            version: this.version?.id,
+            article_name: this.getArticleName()
+        });
+
+        return data.content;
     }
 
-    async fetchContent(): Promise<void> {
+    async fetchContent(): Promise<ContentData> {
         this.setState({
             isFetchingContent: true
         });
-        const data = await this.contentProvider.fetchContent(
-            this.pageReference.deliverable,
-            this.pageReference.contentDocumentId,
+        const data = await this.contentProvider!.fetchContent(
+            this.pageReference.deliverable!,
+            this.pageReference.contentDocumentId!,
             {
-                language: this.language.id,
-                version: this.version.id
+                language: this.language!.id,
+                version: this.version!.id
             }
         );
 
         if (data) {
             this.docContent = data.content;
+            this.calculateReadingTime(data.content);
             this.addMetatags();
 
             if (!this.pageReference.hash) {
-                document.querySelector("main")?.scrollIntoView({
-                    behavior: "smooth",
-                    block: "start",
-                    inline: "nearest"
-                });
+                document.body.scrollIntoView();
             }
+
+            // Track page view when new content is loaded (navigation within same document)
+            // Note: breadcrumbs will be built after this in updatePageReference,
+            // but we need to build them here to get article_name
+            this.buildBreadcrumbs();
+            trackGTM(this.template.host, "doc_page_view", {
+                page_path: this.pageReferenceToString(this.pageReference),
+                doc_id: this.pageReference.docId,
+                content_document_id: this.pageReference.contentDocumentId,
+                deliverable: this.pageReference.deliverable,
+                language: this.language?.id,
+                version: this.version?.id,
+                article_name: this.getArticleName()
+            });
         }
         this.setState({
             isFetchingContent: false
         });
+        return data;
     }
 
-    updateHeader(): void {
+    updateHeaderAndSidebarFooter(): void {
         if (!this.pageHeader) {
             return;
         }
@@ -474,20 +571,12 @@ export default class DocXmlContent extends LightningElementWithState<{
         }
 
         if (this.pdfUrl) {
-            this.pageHeader.bailHref = this.pdfUrl;
-            this.pageHeader.bailLabel = "PDF";
+            this.sidebarFooterContent.bailHref = this.pdfUrl;
+            this.sidebarFooterContent.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;
+        this.sidebarFooterContent.languages = this.availableLanguages;
+        this.sidebarFooterContent.language = this.language?.id;
 
         if (this.pageReference) {
             const { docId, deliverable, page } = this.pageReference;
@@ -511,23 +600,24 @@ export default class DocXmlContent extends LightningElementWithState<{
     }
 
     private updateSearchInput(searchParam: string): void {
-        this.template
-            .querySelector("doc-content-layout")
-            ?.setSidebarInputValue(searchParam);
+        (this.refs.docContentLayout 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
+            search!
         )}${this.normalizeHash(hash)}`;
     }
 
-    private normalizeUrlPart(part: string, sentinel: string): string {
+    private normalizeUrlPart(
+        part: string | undefined,
+        sentinel: string
+    ): string {
         return (
             (part &&
-                (part.startsWith(sentinel) ? part : `${sentinel}${part}`)) ||
+                (part.startsWith(sentinel!) ? part : `${sentinel}${part}`)) ||
             ""
         );
     }
@@ -536,16 +626,16 @@ export default class DocXmlContent extends LightningElementWithState<{
         return this.normalizeUrlPart(search, "?");
     }
 
-    private normalizeHash(hash: string): string {
+    private normalizeHash(hash?: string): string {
         return this.normalizeUrlPart(hash, "#");
     }
 
     private getComposedTitle(
-        topicTitle: string | undefined,
+        topicTitle: string | null | undefined,
         docTitle: string | undefined
     ): string {
         // map to avoid duplicates
-        const titleMap = {};
+        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
@@ -580,8 +670,13 @@ export default class DocXmlContent extends LightningElementWithState<{
         return this.breadcrumbs && this.breadcrumbs.length > 1;
     }
 
-    get docContentStyle(): string {
-        return this.showBreadcrumbs ? "" : "margin-top: 48px";
+    private getArticleName(): string | undefined {
+        if (!this.breadcrumbs || this.breadcrumbs.length === 0) {
+            return undefined;
+        }
+        // Join all breadcrumb labels with "/" to create article name
+        // e.g., "Tooling API Objects/FieldDefinition"
+        return this.breadcrumbs.map((crumb) => crumb.label).join("/");
     }
 
     private buildBreadcrumbs(): void {
@@ -615,16 +710,30 @@ export default class DocXmlContent extends LightningElementWithState<{
         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;
+        div.innerHTML = DOMPurify.sanitize(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) {
+        if (title && title.textContent) {
             title.textContent = composedTitle;
         }
         const metatitle = document.querySelector('meta[name="title"]');
@@ -646,14 +755,80 @@ export default class DocXmlContent extends LightningElementWithState<{
                 '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(this.pageReference)
+                        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);
+        }
+    }
+
+    private get showVersionPicker(): boolean {
+        return !this.disableVersion;
+    }
+
+    private calculateReadingTime(content: string): void {
+        if (!this.displayReadingTime) {
+            this.readingTime = undefined;
+            return;
+        }
+
+        if (!content) {
+            this.readingTime = undefined;
+            return;
+        }
+
+        // Strip HTML tags and get text content
+        const div = document.createElement("div");
+        div.innerHTML = DOMPurify.sanitize(content);
+        const textContent = div.textContent || div.innerText || "";
+
+        // Count words (split by whitespace and filter out empty strings)
+        const wordCount = textContent
+            .trim()
+            .split(/\s+/)
+            .filter((word) => word.length > 0).length;
+
+        // Calculate reading time: (wordCount / 240) + 1, rounded
+        const readingTimeMinutes = Math.round(wordCount / 240 + 1);
+        this.readingTime =
+            readingTimeMinutes > 0 ? readingTimeMinutes : undefined;
     }
 }