@salesforcedevs/docs-components 0.57.1-flex-ref1 → 0.60.0

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

@@ -0,0 +1,22 @@
+/**
+ * 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;
+        }
+    }
+}

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

@@ -2,7 +2,6 @@ import { Json } from "typings/custom";
 
 export interface AmfTopicType {
     referenceId: string;
-    parentReferencePath: string;
     amfId: string;
     elementId: string;
     type: string;
@@ -11,7 +10,6 @@ export interface AmfTopicType {
 export interface AmfMetadataTopic extends AmfTopicType {
     meta: string;
     identifier: string;
-    navTitle?: string;
 }
 
 export interface AmfMetaTopicType extends AmfTopicType {
@@ -55,37 +53,11 @@ export type DocPhaseEntry = {
     body: string;
 };
 
-export type ReferenceType = "markdown" | "rest-raml" | "rest-oa2" | "rest-oa3";
-
-/**
- * Represents parsed topic for the sidebar.
- */
-export interface ParsedMarkdownTopic {
-    label: string;
-    name: string;
-    children: ParsedMarkdownTopic[];
-    link?: {
-        href: string;
-        target?: string;
-    };
-}
-
-export interface AmfConfig {
+export interface AmfConfig extends AmfModelRecord {
     id: string;
+    amf: string;
     version?: string;
     docPhase?: DocPhaseEntry;
-    title: string;
-    href: string;
-    referenceType: ReferenceType;
-
-    // determines if a reference config is the current active and selected one.
-    isSelected: boolean;
-
-    // required for spec based references
-    amf?: string;
-
-    // required for markdown based references
-    topic?: ParsedMarkdownTopic;
 }
 
 export interface ParsedTopicModel {
@@ -112,22 +84,10 @@ export interface ReferenceVersion {
     label: string;
     deprecated?: boolean;
     selected?: boolean;
-    link: {
-        href: string;
-    };
 }
 
 export interface ReferenceSetConfig {
-    refId?: string;
     versionToRefMap?: Map<string, Array<AmfConfig>>;
     refList: Array<AmfConfig>;
-    versions: Array<ReferenceVersion>;
-}
-
-export interface RouteMeta {
-    meta: string;
-    referenceId: string;
-    topicId: string;
-    //type is only for spec based references
-    type?: string;
+    versions?: Array<ReferenceVersion>;
 }

package/src/modules/doc/breadcrumbItem/breadcrumbItem.css

@@ -4,12 +4,13 @@
 :host {
     display: flex;
     align-items: center;
+    justify-content: center;
     width: fit-content;
 }
 
 :host(.breadcrumb_long) {
     /* ensure 30 character min-width */
-    min-width: 245px;
+    min-width: 200px;
 }
 
 :host(.breadcrumb_back-arrow) {

package/src/modules/doc/breadcrumbs/breadcrumbs.css

@@ -4,6 +4,8 @@
 :host {
     --dx-c-breadcrumbs-title-color: var(--dx-g-blue-vibrant-20);
     --dx-c-breadcrumbs-breadcrumb-color: var(--dx-g-blue-vibrant-20);
+
+    font-family: var(--dx-g-font-sans);
 }
 
 nav {

package/src/modules/doc/breadcrumbs/breadcrumbs.html

@@ -36,7 +36,7 @@
                     analytics-event={analyticsEventName}
                     analytics-base-payload={analyticsBasePayload}
                     href={breadcrumb.href}
-                    key={breadcrumb.label}
+                    key={breadcrumb.id}
                     label={breadcrumb.label}
                 ></doc-breadcrumb-item>
                 <span class="breadcrumb-item_slash" key={breadcrumb.label}>

package/src/modules/doc/breadcrumbs/breadcrumbs.ts

@@ -8,10 +8,12 @@ type BreadcrumbConfig = {
 };
 
 const GAP = 8;
+
+// Unit in pixels based on Salesforce Sans font-family.
 const CONSTANTS = {
-    pixelPerCharacter: 7.2,
-    pixelPerCrumbSpace: GAP * 2 + 4.6,
-    minWidthPerCrumb: 245,
+    pixelPerCharacter: 7.7,
+    pixelPerCrumbSpace: GAP * 2 + 8.6,
+    minWidthPerCrumb: 200,
     dropdownWidth: 32
 };
 
@@ -29,15 +31,26 @@ export default class Breadcrumbs extends LightningElement {
     get breadcrumbs(): Breadcrumb[] {
         return this._breadcrumbs;
     }
+
     set breadcrumbs(value) {
-        this._breadcrumbs = toJson(value) || [];
+        this.normalizeAndAssignBreadcrumbs(value);
         this.calculateBreadcrumbsConfigs();
         if (this.observer) {
             this.updateDropdownOptionAmount();
         }
     }
 
+    @api
+    get pixelPerCharacter(): number {
+        return this._pixelPerCharacter;
+    }
+
+    set pixelPerCharacter(value: number | string) {
+        this._pixelPerCharacter = +value;
+    }
+
     private _breadcrumbs: Breadcrumb[] = [];
+    private _pixelPerCharacter = CONSTANTS.pixelPerCharacter;
     private navWidth = 0;
     private observer: ResizeObserver | null = null;
     private breadcrumbConfigs: BreadcrumbConfig[] = [];
@@ -72,7 +85,7 @@ export default class Breadcrumbs extends LightningElement {
     private get dropdownOptions(): OptionWithLink[] {
         return this.breadcrumbs!.slice(1, this.dropdownOptionAmount! + 1).map(
             (link) => ({
-                id: link.href!,
+                id: link.id!,
                 label: link.label,
                 link: { href: link.href! }
             })
@@ -118,6 +131,17 @@ export default class Breadcrumbs extends LightningElement {
         this.observer?.disconnect();
     }
 
+    private normalizeAndAssignBreadcrumbs(breadcrumbs?: Breadcrumb[] | string) {
+        if (!breadcrumbs) {
+            return;
+        }
+
+        this._breadcrumbs = toJson(breadcrumbs).map((crumb: Breadcrumb) => ({
+            ...crumb,
+            id: crumb.id || crumb.href
+        }));
+    }
+
     private updateDropdownOptionAmount(): void {
         this.dropdownOptionAmount = this.breadcrumbConfigs.find(
             ({ minWidth }) => minWidth <= this.navWidth
@@ -150,7 +174,8 @@ export default class Breadcrumbs extends LightningElement {
             (previousValue, element) =>
                 previousValue +
                 Math.min(
-                    element.label.length * CONSTANTS.pixelPerCharacter,
+                    element.label.length *
+                        (this.pixelPerCharacter || CONSTANTS.pixelPerCharacter),
                     CONSTANTS.minWidthPerCrumb
                 ),
             (breadcrumbs.length - 1) * CONSTANTS.pixelPerCrumbSpace + offset

package/src/modules/doc/contentLayout/contentLayout.css

@@ -56,7 +56,7 @@ dx-toc {
     max-width: 275px;
 }
 
-dx-breadcrumbs {
+doc-breadcrumbs {
     display: block;
     margin-bottom: var(--dx-g-spacing-2xl);
 }
@@ -68,10 +68,6 @@ dx-breadcrumbs {
 }
 
 @media screen and (max-width: 800px) {
-    dx-breadcrumbs {
-        display: none;
-    }
-
     .content-body {
         margin-top: var(--dx-c-content-vertical-spacing);
     }

package/src/modules/doc/contentLayout/contentLayout.html

@@ -28,17 +28,10 @@
             <slot name="doc-phase"></slot>
             <div class="content-body-container">
                 <div class="content-body">
-                    <dx-breadcrumbs
+                    <doc-breadcrumbs
                         if:true={breadcrumbs}
                         breadcrumbs={breadcrumbs}
-                        truncate
-                        hide-current-location
-                    ></dx-breadcrumbs>
-                    <dx-breadcrumbs
-                        if:false={breadcrumbs}
-                        pathname={pathname}
-                        hide-current-location
-                    ></dx-breadcrumbs>
+                    ></doc-breadcrumbs>
                     <slot onslotchange={onSlotChange}></slot>
                 </div>
                 <div class="right-nav-bar is-sticky">

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

@@ -20,7 +20,6 @@ const HIGHLIGHTABLE_SELECTOR = [
     "th",
     "td"
 ].join(",");
-const OBSERVER_ATTACH_WAIT_TIME = 500;
 
 export default class ContentLayout extends LightningElement {
     @api sidebarValue: string;
@@ -96,8 +95,6 @@ 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;
@@ -122,18 +119,6 @@ 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(
@@ -141,25 +126,19 @@ 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
         );
 
-    attachInteractionObserver = (): void => {
+    onSlotChange(event: Event): void {
         if (!this.enableSlotChange) {
             return;
         }
+
         this.disconnectObserver();
         this.observer = new IntersectionObserver((entries) => {
             entries.forEach(
@@ -171,54 +150,30 @@ export default class ContentLayout extends LightningElement {
             this.calculateActualSection();
         });
 
-        // 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");
+        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");
             this.anchoredElements[id] = {
                 id,
                 intersect: false
             };
-            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;
-        }
+            this.observer.observe(section);
+        });
     }
 
     private disconnectObserver(): void {
@@ -228,16 +183,16 @@ export default class ContentLayout extends LightningElement {
         }
     }
 
-    // eslint-disable-next-line no-undef
-    private scrollToHash(headingElements: NodeListOf<Element>): void {
+    private scrollToHash(anchoredTags: Array<Element>): void {
         let { hash } = window.location;
+
         if (hash) {
             hash = hash.substr(1);
-            for (const headingElement of headingElements) {
-                if (headingElement.getAttribute("id") === hash) {
-                    headingElement.scrollIntoView({ behavior: "auto" });
-                    break;
-                }
+            const toScrollElement = anchoredTags.find(
+                (element) => element.getAttribute("id") === hash
+            );
+            if (toScrollElement) {
+                toScrollElement.scrollIntoView({ behavior: "auto" });
             }
         }
     }

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

@@ -24,6 +24,7 @@ export type TreeNode = {
     name: string;
     children?: Array<TreeNode>;
     isExpanded?: boolean;
+    parent?: TreeNode;
 };
 
 type DropdownOption = {
@@ -109,3 +110,5 @@ export type ContentApiOptions = {
     version: string;
     language: string;
 };
+
+export type TocMap = { [key: string]: TreeNode };

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

@@ -8,7 +8,8 @@ import {
     DocumentData,
     DocLanguage,
     DocVersion,
-    TreeNode
+    TreeNode,
+    TocMap
 } from "./types";
 import { Language } from "typings/custom";
 import { getLanguageDisplayTextById } from "dxUtils/language";
@@ -100,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("#");
@@ -144,11 +145,13 @@ export class FetchContent {
     }
 
     private normalizeLanguage(language: ApiDocLanguage): DocLanguage {
-
         return (
             language && {
-                label: getLanguageDisplayTextById(this.languages, language.locale) || 
-                    language.label,
+                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,11 @@
     --button-primary-color-hover: var(--dx-g-blue-vibrant-40);
 }
 
+doc-breadcrumbs {
+    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

@@ -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

@@ -8,15 +8,26 @@ import {
     TreeNode,
     Header,
     HistoryState,
-    PageReference
+    PageReference,
+    TocMap
 } from "./types";
 import { SearchSyncer } from "docUtils/SearchSyncer";
 import { LightningElementWithState } from "docBaseElements/lightningElementWithState";
-import { Language } from "typings/custom";
+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;
@@ -53,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 = "";
@@ -102,6 +113,7 @@ export default class DocXmlContent extends LightningElementWithState<{
     private _allLanguages: Array<Language> = [];
 
     @track private pageReference: PageReference = {};
+    @track breadcrumbs: Array<Breadcrumb> = [];
 
     constructor() {
         super();
@@ -267,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());
 
@@ -280,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();
         }
     }
@@ -321,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 {
@@ -386,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);
@@ -558,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;