@salesforcedevs/docs-components 0.54.0-alpha04 → 0.54.1-a01

package/src/modules/doc/contentLayout/contentLayout.ts

@@ -20,6 +20,7 @@ const HIGHLIGHTABLE_SELECTOR = [
     "th",
     "td"
 ].join(",");
+const OBSERVER_ATTACH_WAIT_TIME = 500;
 
 export default class ContentLayout extends LightningElement {
     @api sidebarValue: string;
@@ -95,6 +96,8 @@ export default class ContentLayout extends LightningElement {
         target: window
     });
     private tocValue?: string = undefined;
+    private observerTimerId = null;
+    private didScrollToSelectedHash = false;
 
     get showToc(): boolean {
         return this.tocOptions && this.tocOptions.length > 0;
@@ -119,6 +122,18 @@ export default class ContentLayout extends LightningElement {
         }
     }
 
+    renderedCallback(): void {
+        /**
+         * Note: We are adding timeout because chrome is optimizing and not triggering recent renderedCallback though elements reference is changed
+         * Also we are considering recent renderedCallback
+         */
+        this.clearRenderObserverTimer();
+        this.observerTimerId = setTimeout(
+            this.attachInteractionObserver,
+            OBSERVER_ATTACH_WAIT_TIME
+        );
+    }
+
     disconnectedCallback(): void {
         this.disconnectObserver();
         window.removeEventListener(
@@ -126,19 +141,25 @@ export default class ContentLayout extends LightningElement {
             this.updateHighlighted
         );
         this.searchSyncer.dispose();
+        this.clearRenderObserverTimer();
     }
 
+    clearRenderObserverTimer = () => {
+        if (this.observerTimerId) {
+            clearTimeout(this.observerTimerId);
+        }
+    };
+
     updateHighlighted = (event: Event): void =>
         highlightTerms(
             this.querySelectorAll(HIGHLIGHTABLE_SELECTOR),
             (event as CustomEvent<string>).detail
         );
 
-    onSlotChange(event: Event): void {
+    attachInteractionObserver = (): void => {
         if (!this.enableSlotChange) {
             return;
         }
-
         this.disconnectObserver();
         this.observer = new IntersectionObserver((entries) => {
             entries.forEach(
@@ -150,30 +171,54 @@ export default class ContentLayout extends LightningElement {
             this.calculateActualSection();
         });
 
-        const anchoredTags = (event.target as HTMLSlotElement)
-            .assignedElements()
-            .filter(({ tagName }) => tagName === TOC_HEADER_TAG)
-            .map((tag) => {
-                tag.id = tag.hash;
-                return tag;
-            });
-
-        this._tocOptions = anchoredTags.map((tag) => ({
-            anchor: `#${tag.hash}`,
-            id: tag.id,
-            label: tag.title
-        }));
-
-        this.scrollToHash(anchoredTags);
-
-        anchoredTags.forEach((section) => {
-            const id = section.getAttribute("id");
+        // Note: We are doing document.querySelectorAll as a quick fix as we are not getting heading elements reference this.querySelectorAll
+        const headingElements = document.querySelectorAll(TOC_HEADER_TAG);
+        for (const headingElement of headingElements) {
+            // Add headingElements to intersectionObserver for highlighting respective RNB item when user scroll
+            const id = headingElement.getAttribute("id");
             this.anchoredElements[id] = {
                 id,
                 intersect: false
             };
-            this.observer.observe(section);
-        });
+            this.observer.observe(headingElement);
+        }
+        if (!this.didScrollToSelectedHash) {
+            this.didScrollToSelectedHash = true;
+            this.scrollToHash(headingElements);
+        }
+    };
+
+    onSlotChange(event: Event): void {
+        const slotElements = (
+            event.target as HTMLSlotElement
+        ).assignedElements();
+
+        if (slotElements.length) {
+            const slotContentElement = slotElements[0];
+            const headingElements =
+                slotContentElement.ownerDocument?.getElementsByTagName(
+                    TOC_HEADER_TAG
+                );
+            for (const headingElement of headingElements) {
+                // Sometimes elements hash is not being set when slot content is wrapped with div
+                headingElement.hash =
+                    headingElement.attributes.hash?.nodeValue;
+            }
+            const tocOptions = [];
+            for (const headingElement of headingElements) {
+                headingElement.id = headingElement.hash;
+
+                // Update tocOptions from anchorTags
+                const tocItem = {
+                    anchor: `#${headingElement.hash}`,
+                    id: headingElement.id,
+                    label: headingElement.title
+                };
+                tocOptions.push(tocItem);
+            }
+
+            this._tocOptions = tocOptions;
+        }
     }
 
     private disconnectObserver(): void {
@@ -183,16 +228,16 @@ export default class ContentLayout extends LightningElement {
         }
     }
 
-    private scrollToHash(anchoredTags: Array<Element>): void {
+    // eslint-disable-next-line no-undef
+    private scrollToHash(headingElements: NodeListOf<Element>): void {
         let { hash } = window.location;
-
         if (hash) {
             hash = hash.substr(1);
-            const toScrollElement = anchoredTags.find(
-                (element) => element.getAttribute("id") === hash
-            );
-            if (toScrollElement) {
-                toScrollElement.scrollIntoView({ behavior: "auto" });
+            for (const headingElement of headingElements) {
+                if (headingElement.getAttribute("id") === hash) {
+                    headingElement.scrollIntoView({ behavior: "auto" });
+                    break;
+                }
             }
         }
     }

package/src/modules/doc/header/header.ts

@@ -1,6 +1,6 @@
 import { api } from "lwc";
 import cx from "classnames";
-import type { Option } from "typings/custom";
+import type { OptionWithNested, OptionWithLink } from "typings/custom";
 import { HeaderBase } from "dxBaseElements/headerBase";
 import { toJson } from "dxUtils/normalizers";
 import get from "lodash.get";
@@ -43,8 +43,8 @@ export default class Header extends HeaderBase {
     }
 
     private _language: string | null = null;
-    private _languages!: Option[];
-    private _scopedNavItems!: Option[];
+    private _languages!: OptionWithLink[];
+    private _scopedNavItems!: OptionWithNested[];
     private smallMobile = false;
     private smallMobileMatchMedia!: MediaQueryList;
     private tablet = false;

package/src/modules/doc/headingContent/headingContent.css

@@ -34,6 +34,10 @@ dx-icon {
     --dx-c-icon-size: var(--doc-c-heading-anchor-icon-size);
 }
 
+span {
+    word-break: break-word;
+}
+
 span:last-of-type {
     padding-right: var(--dx-g-spacing-xs);
 }

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

@@ -1,9 +1,7 @@
 export type CoveoAdvancedQueryXMLConfig = {
-    objecttype?: string;
-    sflocale__c?: string;
-    sfrelease__c?: string;
-    sfdelivarable__c?: string;
-    source?: string;
+    locale?: string;
+    version?: string;
+    topicid?: string;
 };
 
 export type PageReference = {
@@ -21,17 +19,12 @@ export enum HistoryState {
     REPLACE_STATE = "replaceState"
 }
 
-export type Labels = {
-    language_english: string;
-    language_japanese: string;
-    toc_title: string;
-};
-
 export type TreeNode = {
     label: string;
     name: string;
     children?: Array<TreeNode>;
     isExpanded?: boolean;
+    parent?: TreeNode;
 };
 
 type DropdownOption = {
@@ -117,3 +110,5 @@ export type ContentApiOptions = {
     version: string;
     language: string;
 };
+
+export type TocMap = { [key: string]: TreeNode };

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

@@ -8,22 +8,19 @@ import {
     DocumentData,
     DocLanguage,
     DocVersion,
-    Labels,
-    TreeNode
+    TreeNode,
+    TocMap
 } from "./types";
-
-const LOCALE_TO_LABEL = {
-    "en-us": "language_english",
-    "ja-jp": "language_japanese"
-};
+import { Language } from "typings/custom";
+import { getLanguageDisplayTextById } from "dxUtils/language";
 
 export class FetchContent {
     private apiDomain: string;
-    private labels: Labels;
+    private languages: Array<Language> = [];
 
-    constructor(apiDomain: string, labels: Labels) {
+    constructor(apiDomain: string, languages: Array<Language>) {
         this.apiDomain = apiDomain;
-        this.labels = labels;
+        this.languages = languages;
     }
 
     async fetchDocumentData(docId: string): Promise<DocumentData | null> {
@@ -104,26 +101,26 @@ export class FetchContent {
 
     private normalizeNavItem(
         navItem: ApiNavItem,
-        tocMap: { [key: string]: TreeNode }
+        tocMap: TocMap,
+        parentNavItem?: TreeNode
     ): TreeNode {
         const name = this.calculateNavItemName(navItem, tocMap);
         const node: TreeNode = {
             label: navItem.text,
-            name
+            name,
+            parent: parentNavItem
         };
+
         if (name) {
             tocMap[name] = node;
         }
         node.children = navItem.children?.map((child) =>
-            this.normalizeNavItem(child, tocMap)
+            this.normalizeNavItem(child, tocMap, node)
         );
         return node;
     }
 
-    private calculateNavItemName(
-        navItem: ApiNavItem,
-        tocMap: { [key: string]: TreeNode }
-    ): string {
+    private calculateNavItemName(navItem: ApiNavItem, tocMap: TocMap): string {
         let href = navItem.a_attr?.href || "";
         if (href.includes("#")) {
             const [pathUrl] = href.split("#");
@@ -148,12 +145,13 @@ export class FetchContent {
     }
 
     private normalizeLanguage(language: ApiDocLanguage): DocLanguage {
-        const labelKey = language.locale && LOCALE_TO_LABEL[language.locale];
         return (
             language && {
                 label:
-                    (labelKey && this.labels && this.labels[labelKey]) ||
-                    language.label,
+                    getLanguageDisplayTextById(
+                        this.languages,
+                        language.locale
+                    ) || language.label,
                 id: language.locale,
                 code: language.code,
                 url: language.url

package/src/modules/doc/xmlContent/xmlContent.css

@@ -3,6 +3,13 @@
     --button-primary-color-hover: var(--dx-g-blue-vibrant-40);
 }
 
+doc-breadcrumbs {
+    --dx-c-popover-z-index: 5;
+
+    display: block;
+    margin-bottom: var(--dx-g-spacing-2xl);
+}
+
 dx-dropdown {
     --dx-c-dropdown-option-font-size: var(--dx-g-text-sm);
 }

package/src/modules/doc/xmlContent/xmlContent.html

@@ -9,7 +9,7 @@
         sidebar-content={sidebarContent}
         sidebar-value={sidebarValue}
         onselect={handleSelect}
-        use-old-sidebar
+        use-old-sidebar={useOldSidebar}
     >
         <div slot="sidebar-header" class="document-pickers">
             <dx-dropdown
@@ -25,6 +25,11 @@
                 </dx-button>
             </dx-dropdown>
         </div>
+        <doc-breadcrumbs
+            if:true={breadcrumbs}
+            breadcrumbs={breadcrumbs}
+            pixel-per-character={breadcrumbPixelPerCharacter}
+        ></doc-breadcrumbs>
         <doc-content
             docs-data={docContent}
             page-reference={pageReference}

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

@@ -1,22 +1,33 @@
 import { api, track } from "lwc";
-import { toJson } from "dxUtils/normalizers";
+import { normalizeBoolean } from "dxUtils/normalizers";
 import { FetchContent } from "./utils";
 import {
     CoveoAdvancedQueryXMLConfig,
     DocLanguage,
     DocVersion,
-    Labels,
     TreeNode,
     Header,
     HistoryState,
-    PageReference
+    PageReference,
+    TocMap
 } from "./types";
 import { SearchSyncer } from "docUtils/SearchSyncer";
 import { LightningElementWithState } from "docBaseElements/lightningElementWithState";
+import { Breadcrumb, Language } from "typings/custom";
 
 // 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 FIRST_CRUMB = {
+    href: "/docs",
+    label: "Documentation"
+};
+
+const PIXEL_PER_CHARACTER_MAP: { [key: string]: number } = {
+    default: 7.7,
+    "ja-jp": 12.5
+};
+
 export default class DocXmlContent extends LightningElementWithState<{
     isFetchingDocument: boolean;
     isFetchingContent: boolean;
@@ -27,15 +38,25 @@ export default class DocXmlContent extends LightningElementWithState<{
     @api coveoPublicAccessToken!: string;
 
     @api
-    get labels() {
-        return this._labels;
+    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 labels(value) {
-        this._labels = toJson(value);
+    set enableCoveo(value) {
+        this._enableCoveo = normalizeBoolean(value);
     }
 
-    private _labels: Labels = null;
     private availableLanguages: Array<DocLanguage> = [];
     private availableVersions: Array<DocVersion> = [];
     private contentProvider: FetchContent;
@@ -43,7 +64,7 @@ export default class DocXmlContent extends LightningElementWithState<{
     private language: DocLanguage = null;
     private loaded = false;
     private pdfUrl = "";
-    private tocMap = null;
+    private tocMap: TocMap = {};
     private sidebarContent: Array<TreeNode> = null;
     private version: DocVersion = null;
     private docTitle = "";
@@ -51,6 +72,8 @@ export default class DocXmlContent extends LightningElementWithState<{
     private _pathName = "";
     private _pageHeader?: Header;
     private listenerAttached = false;
+    private _enableCoveo?: boolean = false;
+
     private searchSyncer = new SearchSyncer({
         callbacks: {
             onSearchChange: (nextSearchString: string): void => {
@@ -87,8 +110,10 @@ export default class DocXmlContent extends LightningElementWithState<{
         shouldStopPropagation: true,
         target: window
     });
+    private _allLanguages: Array<Language> = [];
 
     @track private pageReference: PageReference = {};
+    @track breadcrumbs: Array<Breadcrumb> = [];
 
     constructor() {
         super();
@@ -109,8 +134,10 @@ export default class DocXmlContent extends LightningElementWithState<{
             window.location.href = "/docs";
             return;
         }
-
-        this.contentProvider = new FetchContent(this.apiDomain, this._labels);
+        this.contentProvider = new FetchContent(
+            this.apiDomain,
+            this.allLanguages
+        );
         this.fetchDocument().then(() => (this.loaded = true));
         window.addEventListener("popstate", this.handlePopState);
 
@@ -180,18 +207,33 @@ export default class DocXmlContent extends LightningElementWithState<{
         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 {
-        return {
-            // Temporary fix for empty results on apexref page
-            ...(this.deliverable === "apexref"
-                ? { source: "Sitemap - Developer Docs Atlas - Apexref" }
-                : {
-                      objecttype: "HTDeveloperDocumentsC",
-                      sflocale__c: this.languageId,
-                      sfrelease__c: this.releaseVersionId,
-                      sfdelivarable__c: this.deliverable
-                  })
+        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 {
@@ -237,6 +279,13 @@ export default class DocXmlContent extends LightningElementWithState<{
               }));
     }
 
+    private get breadcrumbPixelPerCharacter() {
+        return (
+            PIXEL_PER_CHARACTER_MAP[this.language.id] ||
+            PIXEL_PER_CHARACTER_MAP.default
+        );
+    }
+
     private handlePopState = (): void =>
         this.updatePageReference(this.getReferenceFromUrl());
 
@@ -250,15 +299,15 @@ export default class DocXmlContent extends LightningElementWithState<{
 
         if (name) {
             const hashIndex = name.indexOf("#");
-            this.pageReference.hash =
-                hashIndex > -1 ? name.slice(hashIndex) : "";
-
-            const contentId = hashIndex > -1 ? name.slice(0, hashIndex) : name;
-            if (this.pageReference.contentDocumentId !== contentId) {
-                this.pageReference.contentDocumentId = contentId;
-                this.fetchContent().catch(handleContentError);
-            }
-
+            const hash = hashIndex > -1 ? name.slice(hashIndex) : "";
+
+            const contentDocumentId =
+                hashIndex > -1 ? name.slice(0, hashIndex) : name;
+            this.updatePageReference({
+                ...this.pageReference,
+                contentDocumentId,
+                hash
+            });
             this.updateUrl();
         }
     }
@@ -291,15 +340,17 @@ export default class DocXmlContent extends LightningElementWithState<{
             return;
         }
 
-        const isSameDocId = this.pageReference.docId !== newPageReference.docId;
+        const isSameDocId = this.pageReference.docId === newPageReference.docId;
         this.pageReference = newPageReference;
 
-        if (isSameDocId) {
+        if (!isSameDocId) {
             this.fetchDocument();
             return;
         }
 
-        this.fetchContent().catch(handleContentError);
+        this.fetchContent()
+            .then(() => this.buildBreadcrumbs())
+            .catch(handleContentError);
     }
 
     getReferenceFromUrl(): PageReference {
@@ -356,6 +407,8 @@ export default class DocXmlContent extends LightningElementWithState<{
 
         this.updateHeader();
 
+        this.buildBreadcrumbs();
+
         if (this.pageReference.deliverable !== data.deliverable) {
             this.pageReference.deliverable = data.deliverable;
             this.updateUrl(HistoryState.REPLACE_STATE);
@@ -404,7 +457,11 @@ export default class DocXmlContent extends LightningElementWithState<{
             this.addMetatags();
 
             if (!this.pageReference.hash) {
-                window.scrollTo(0, 0);
+                document.querySelector("main")?.scrollIntoView({
+                    behavior: "smooth",
+                    block: "start",
+                    inline: "nearest"
+                });
             }
         }
         this.setState({
@@ -524,6 +581,32 @@ export default class DocXmlContent extends LightningElementWithState<{
         );
     }
 
+    private buildBreadcrumbs(): void {
+        const { contentDocumentId } = this.pageReference;
+        if (!contentDocumentId) {
+            return;
+        }
+
+        const currentNode = this.tocMap[contentDocumentId];
+        this.breadcrumbs = this.nodeToBreadcrumb(currentNode);
+    }
+
+    private nodeToBreadcrumb(node?: TreeNode): Breadcrumb[] {
+        if (!node) {
+            return [FIRST_CRUMB];
+        }
+        return [
+            ...this.nodeToBreadcrumb(node.parent),
+            {
+                href: this.pageReferenceToString({
+                    ...this.pageReference,
+                    contentDocumentId: node.name
+                }),
+                label: node.label
+            }
+        ];
+    }
+
     addMetatags(): void {
         const div = document.createElement("div");
         div.innerHTML = this.docContent;
@@ -549,5 +632,20 @@ export default class DocXmlContent extends LightningElementWithState<{
                 metadescription.setAttribute("content", docDescription);
             }
         }
+
+        if (this.pageReference) {
+            const metadescription = document.querySelector(
+                'link[rel="canonical"]'
+            );
+            if (metadescription) {
+                metadescription.setAttribute(
+                    "href",
+                    window.location.protocol +
+                        "//" +
+                        window.location.host +
+                        this.pageReferenceToString(this.pageReference)
+                );
+            }
+        }
     }
 }

package/src/modules/doc/amfReference/route-meta.ts

@@ -1,22 +0,0 @@
-/**
- * Represents the URL reference meta on Reference page.
- * Contains information on selected Reference ID, Topic ID, and Topic Type
- * separated by ":"
- */
-export class RouteMeta {
-    meta: string;
-    referenceId = "";
-    topicId = "";
-    type = "";
-
-    constructor(meta: string) {
-        this.meta = meta;
-
-        if (meta && meta.includes(":")) {
-            const [referenceId, type, topicId] = meta.split(":");
-            this.referenceId = referenceId;
-            this.topicId = topicId || type;
-            this.type = type;
-        }
-    }
-}