@salesforcedevs/docs-components 0.0.0 → 0.0.1-superscript

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

@@ -1,12 +1,18 @@
+/* eslint-disable @lwc/lwc/no-document-query */
 import { LightningElement, api, track } from "lwc";
 import { closest } from "kagekiri";
 import { toJson } from "dxUtils/normalizers";
 import { highlightTerms } from "dxUtils/highlight";
-import { SearchSyncer } from "docUtils/SearchSyncer";
+import { SearchSyncer } from "docUtils/searchSyncer";
+import type { OptionWithLink } from "typings/custom";
+import { buildDocLinkClickHandler } from "dxUtils/analytics";
 
 type AnchorMap = { [key: string]: { intersect: boolean; id: string } };
 
-const TOC_HEADER_TAG = "DOC-HEADING";
+declare const Sprig: (eventType: string, eventNme: string) => void;
+
+const TOC_HEADER_TAG = "doc-heading";
+
 const HIGHLIGHTABLE_SELECTOR = [
     "p",
     "h1",
@@ -20,25 +26,33 @@ const HIGHLIGHTABLE_SELECTOR = [
     "th",
     "td"
 ].join(",");
-const OBSERVER_ATTACH_WAIT_TIME = 500;
+export const OBSERVER_ATTACH_WAIT_TIME = 500;
 
 export default class ContentLayout extends LightningElement {
-    @api sidebarValue: string;
-    @api sidebarHeader: string;
-    @api tocTitle: string;
+    @api sidebarValue!: string;
+    @api sidebarHeader!: string;
+    @api tocTitle!: string;
     @api enableSlotChange = false;
-    @api coveoOrganizationId!: string;
-    @api coveoPublicAccessToken!: string;
-    @api coveoSearchHub!: string;
-    @api coveoAdvancedQueryConfig!: string;
     @api useOldSidebar?: boolean = false;
+    @api languages!: OptionWithLink[];
+    @api language!: string;
+    @api bailHref!: string;
+    @api bailLabel!: string;
+    @api devCenter: any;
+    @api brand: any;
+    @api emptyStateMessage?: string;
+
+    // This is needed for now to prevent failing snapshot tests due to links in the footer
+    @api showFooter = false;
+
+    @api readingTime?: number;
 
     @api
     get breadcrumbs() {
         return this._breadcrumbs;
     }
 
-    set breadcrumbs(value): [] {
+    set breadcrumbs(value) {
         if (value) {
             this._breadcrumbs = toJson(value);
         }
@@ -49,7 +63,7 @@ export default class ContentLayout extends LightningElement {
         return this._sidebarContent;
     }
 
-    set sidebarContent(value) {
+    set sidebarContent(value: any) {
         this._sidebarContent = toJson(value);
     }
 
@@ -62,29 +76,41 @@ export default class ContentLayout extends LightningElement {
         this._tocOptions = toJson(value);
     }
 
+    /**
+     * The aria-level to filter headings by when building the TOC.
+     * Defaults to "2" (H2 headings).
+     */
+    @api tocAriaLevel: string = "2";
+
     @api
     setSidebarInputValue(searchTerm: string): void {
-        this.template.querySelector("dx-sidebar")?.setInputValue(searchTerm);
+        (this.template.querySelector("dx-sidebar") as any)?.setInputValue(
+            searchTerm
+        );
     }
 
     @track
-    private _sidebarContent: unknown;
+    protected _sidebarContent: unknown;
 
-    private _breadcrumbs = null;
+    protected _breadcrumbs = null;
 
     @track
-    private _tocOptions: Array<unknown>;
-
-    private anchoredElements: AnchorMap = {};
-    private lastScrollPosition: number;
-    private observer?: IntersectionObserver;
-    private hasRendered: boolean = false;
+    protected _tocOptions!: Array<unknown>;
+
+    protected tocOptionIdsSet = new Set();
+    protected anchoredElements: AnchorMap = {};
+    protected lastScrollPosition!: number;
+    protected observer?: IntersectionObserver;
+    protected hasRendered: boolean = false;
+    protected contentLoaded: boolean = false;
+    protected sidebarOpen: boolean = false;
+
+    get shouldDisplayFeedback() {
+        return this.contentLoaded && typeof Sprig !== "undefined";
+    }
 
-    private searchSyncer = new SearchSyncer({
+    protected searchSyncer = new SearchSyncer({
         callbacks: {
-            onUrlChange: (nextSearchString: string): void => {
-                this.updateHighlightsAndSearch(nextSearchString);
-            },
             onSearchChange: (nextSearchString: string): void => {
                 this.dispatchHighlightChange(
                     new URLSearchParams(nextSearchString).get("q") || ""
@@ -97,10 +123,12 @@ export default class ContentLayout extends LightningElement {
         shouldStopPropagation: true,
         target: window
     });
-    private tocValue?: string = undefined;
-    private observerTimerId = null;
-    private didScrollToSelectedHash = false;
-    private _scrollInterval = 0;
+    protected tocValue?: string = undefined;
+    // eslint-disable-next-line no-undef
+    protected observerTimerId?: NodeJS.Timeout;
+    protected didScrollToSelectedHash = false;
+    protected _scrollInterval = 0;
+    protected handleLinkClick = buildDocLinkClickHandler();
 
     get showToc(): boolean {
         return this.tocOptions && this.tocOptions.length > 0;
@@ -117,8 +145,8 @@ export default class ContentLayout extends LightningElement {
         );
     }
 
-    get docContentStyle(): string {
-        return this.showBreadcrumbs ? "" : "margin-top: 48px";
+    get showReadingTime(): boolean {
+        return this.readingTime != null && this.readingTime > 1;
     }
 
     connectedCallback(): void {
@@ -134,11 +162,13 @@ export default class ContentLayout extends LightningElement {
             this.searchSyncer.init();
         }
 
-        this._scrollInterval = window.setInterval(() => {
-            this.saveScroll();
-        }, 1000);
+        // Add click handler for all links
+        this.template.addEventListener("click", this.handleLinkClick);
     }
 
+    // Placeholder for childs renderedCallback
+    protected postRenderedCallback?(): void;
+
     renderedCallback(): void {
         /**
          * Note: We are adding timeout because chrome is optimizing and not triggering recent renderedCallback though elements reference is changed
@@ -149,9 +179,17 @@ export default class ContentLayout extends LightningElement {
             this.attachInteractionObserver,
             OBSERVER_ATTACH_WAIT_TIME
         );
+
+        this.adjustNavPosition();
+        window.addEventListener("scroll", this.adjustNavPosition);
+        window.addEventListener("resize", this.adjustNavPosition);
+
         if (!this.hasRendered) {
             this.hasRendered = true;
             this.restoreScroll();
+
+            // Dynamically call `renderedCallbackForLwcContentLayout` if it exists
+            this.postRenderedCallback?.();
         }
     }
 
@@ -161,18 +199,15 @@ export default class ContentLayout extends LightningElement {
             "highlightedtermchange",
             this.updateHighlighted
         );
+        window.removeEventListener("scroll", this.adjustNavPosition);
+        window.removeEventListener("resize", this.adjustNavPosition);
         this.searchSyncer.dispose();
         this.clearRenderObserverTimer();
 
         window.clearInterval(this._scrollInterval);
-    }
 
-    saveScroll() {
-        window.history.replaceState(
-            { scrollValue: document.body.scrollTop },
-            "",
-            window.location.href
-        );
+        // Remove link click handler
+        this.template.removeEventListener("click", this.handleLinkClick);
     }
 
     restoreScroll() {
@@ -186,98 +221,297 @@ export default class ContentLayout extends LightningElement {
         }
     };
 
+    /*
+        This is a workaround for the global nav sticky header being decoupled from the doc header & doc phase.
+        We have to account for the global nav changing height due to animations.
+    */
+    adjustNavPosition = () => {
+        const sidebarEl = this.template.querySelector("dx-sidebar-old");
+        const globalNavEl = document.querySelector(
+            "hgf-c360nav"
+        ) as HTMLElement;
+        const contextNavEl = document.querySelector(
+            "hgf-c360contextnav"
+        ) as HTMLElement;
+        const docHeaderEl = document.querySelector(
+            ".sticky-doc-header"
+        ) as HTMLElement;
+
+        const docPhaseWrapper = this.template.querySelector(
+            ".doc-phase-wrapper"
+        ) as HTMLElement;
+        const versionWrapper = this.template.querySelector(
+            ".version-wrapper"
+        ) as HTMLElement;
+
+        const docPhaseEl = (
+            docPhaseWrapper.querySelector("[name=doc-phase]")! as any
+        ).assignedElements()[0] as HTMLSlotElement;
+
+        const verBannerEl = (
+            versionWrapper.querySelector("[name=version-banner]")! as any
+        ).assignedElements()[0] as HTMLSlotElement;
+
+        if (!sidebarEl || !globalNavEl || !contextNavEl || !docHeaderEl) {
+            console.warn("One or more required elements are missing.");
+            return;
+        }
+
+        // sync with the browser to account for any reflows that may have happened
+        requestAnimationFrame(() => {
+            // ternary is a temporary fix for the global nav height reporting incorrectly on some browsers
+            const globalNavHeight =
+                (globalNavEl.getBoundingClientRect().height !== 72 ? 0 : 72) +
+                contextNavEl.getBoundingClientRect().height;
+            const docHeaderHeight = docHeaderEl.getBoundingClientRect().height;
+            const totalHeaderHeight = globalNavHeight + docHeaderHeight;
+
+            // Selecting the doc section heading and RNB here.
+            const docHeadingEls = Array.from(
+                document.querySelectorAll("doc-heading")
+            );
+            const rightNavBarEl = this.template.querySelector(".right-nav-bar");
+
+            sidebarEl.style.setProperty(
+                "--dx-c-content-sidebar-sticky-top",
+                `${globalNavHeight + docHeaderHeight}px`
+            );
+
+            docHeaderEl.style.setProperty(
+                "--dx-g-global-header-height",
+                `${globalNavHeight}px`
+            );
+
+            const docPhaseElHeight =
+                docPhaseEl || verBannerEl
+                    ? (docPhaseEl || verBannerEl).getBoundingClientRect().height
+                    : 0;
+
+            // Adjusting the doc section heading on scroll.
+            docHeadingEls.forEach((docHeadingEl) => {
+                (docHeadingEl as any).style.scrollMarginTop = `${
+                    totalHeaderHeight + docPhaseElHeight + 40
+                }px`;
+            });
+
+            // Adjusting the right nav bar on scroll.
+            // setting maxheight to make the RNB scrollable based on different parent elements
+            if (rightNavBarEl) {
+                const viewportHeight = window.innerHeight;
+                const maxHeight =
+                    viewportHeight -
+                    (docPhaseElHeight + totalHeaderHeight + 24); //added some margin of dx-toc
+
+                rightNavBarEl.style.top = `${
+                    totalHeaderHeight + docPhaseElHeight
+                }px`;
+
+                const toc = rightNavBarEl.querySelector("dx-toc");
+                const listContainer = toc?.shadowRoot?.querySelector(
+                    ".toc"
+                ) as HTMLElement;
+
+                if (listContainer) {
+                    listContainer.style.maxHeight = `${maxHeight}px`;
+                }
+            }
+
+            const docPhaseTop =
+                window.innerWidth < 769
+                    ? globalNavHeight +
+                      docHeaderHeight +
+                      sidebarEl.getBoundingClientRect().height
+                    : globalNavHeight + docHeaderHeight;
+
+            // If doc phase element exists, we need to account for its sticky position. Mobile should include the sidebar height (since it becomes sticky aswell).
+            // To handle sticky position for safari browser, position sticky given to wrapper class
+            if (docPhaseEl) {
+                docPhaseWrapper.style.top = `${docPhaseTop}px`;
+            } else if (verBannerEl) {
+                versionWrapper.style.position = "sticky";
+                versionWrapper.style.top = `${docPhaseTop}px`;
+            }
+        });
+    };
+
     updateHighlighted = (event: Event): void =>
         highlightTerms(
             this.querySelectorAll(HIGHLIGHTABLE_SELECTOR),
             (event as CustomEvent<string>).detail
         );
 
-    attachInteractionObserver = (): void => {
-        if (!this.enableSlotChange) {
-            return;
-        }
-        this.disconnectObserver();
-        this.observer = new IntersectionObserver((entries) => {
-            entries.forEach(
-                (entry) =>
-                    (this.anchoredElements[
-                        entry.target.getAttribute("id")
-                    ].intersect = entry.isIntersecting)
-            );
-            this.calculateActualSection();
-        });
-
+    protected getHeadingElements() {
         // 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) {
+        return headingElements;
+    }
+
+    updateHeadingForRNB(): void {
+        const headingElements = this.getHeadingElements();
+        this.addObserverAndScroll(headingElements);
+    }
+
+    addObserverAndScroll(headingElements: any) {
+        for (const headingElement of headingElements as any) {
             // Add headingElements to intersectionObserver for highlighting respective RNB item when user scroll
-            const id = headingElement.getAttribute("id");
+            const id = headingElement.getAttribute("id")!;
             this.anchoredElements[id] = {
                 id,
                 intersect: false
             };
-            this.observer.observe(headingElement);
+            this.observer?.observe(headingElement);
         }
+
         if (!this.didScrollToSelectedHash) {
             this.didScrollToSelectedHash = true;
             this.scrollToHash(headingElements);
         }
-    };
+    }
 
-    onSlotChange(event: Event): void {
-        const slotElements = (
-            event.target as HTMLSlotElement
-        ).assignedElements();
+    attachInteractionObserver = (): void => {
+        if (!this.enableSlotChange) {
+            return;
+        }
+        this.disconnectObserver();
 
-        if (slotElements.length) {
-            const slotContentElement = slotElements[0];
-            const headingElements =
-                slotContentElement.ownerDocument?.getElementsByTagName(
-                    TOC_HEADER_TAG
+        const globalNavOffset = `-${getComputedStyle(
+            document.documentElement
+        ).getPropertyValue("--dx-g-doc-header-main-nav-height")}`;
+
+        this.observer = new IntersectionObserver(
+            (entries) => {
+                entries.forEach(
+                    (entry) =>
+                        (this.anchoredElements[
+                            entry.target.getAttribute("id")!
+                        ].intersect = entry.isIntersecting)
                 );
-            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;
+                this.calculateActualSection();
+            },
+            {
+                rootMargin: globalNavOffset.trim()
             }
-            const tocOptions = [];
-            for (const headingElement of headingElements) {
-                headingElement.id = headingElement.hash;
+        );
+        this.updateHeadingForRNB();
+    };
+
+    // eslint-disable-next-line no-undef
+    updateTocItems(headingElements: any): void {
+        const tocOptions = [];
 
-                // Update tocOptions from anchorTags
+        const maxLevel = Number.parseInt(this.tocAriaLevel, 10) || 2;
+        const minLevel = 2;
+
+        for (const headingElement of headingElements as any) {
+            headingElement.id = headingElement.hash;
+
+            // Update tocOptions from anchorTags for aria-levels 2..tocAriaLevel (inclusive)
+            const headingAriaLevel =
+                headingElement.attributes["aria-level"]?.nodeValue || "2";
+            const headingLevel = Number.parseInt(headingAriaLevel, 10) || 2;
+            const matchesLevel =
+                headingLevel >= minLevel && headingLevel <= maxLevel;
+
+            if (matchesLevel) {
                 const tocItem = {
                     anchor: `#${headingElement.hash}`,
                     id: headingElement.id,
-                    label: headingElement.title
+                    label: headingElement.header,
+                    level: headingLevel
                 };
                 tocOptions.push(tocItem);
+                this.tocOptionIdsSet.add(headingElement.id);
             }
+        }
 
-            this._tocOptions = tocOptions;
+        this._tocOptions = tocOptions;
+    }
+
+    setHashAndHeaderForDocHeading(headingElements: any) {
+        for (const headingElement of headingElements as any) {
+            // Sometimes elements hash and header is not being set when slot content is wrapped with div
+            if (!headingElement.hash) {
+                headingElement.hash = headingElement.attributes.hash?.nodeValue;
+            }
+
+            if (!headingElement.header) {
+                headingElement.header =
+                    headingElement.attributes.header?.nodeValue;
+            }
         }
+
+        this.updateTocItems(headingElements);
+    }
+
+    updateRNB = () => {
+        const headingElements = this.getHeadingElements();
+        this.setHashAndHeaderForDocHeading(headingElements);
+    };
+
+    onSlotChange(): void {
+        this.updateRNB();
+        this.contentLoaded = true;
     }
 
-    private disconnectObserver(): void {
+    protected disconnectObserver(): void {
         if (this.observer) {
             this.observer.disconnect();
-            this.observer = null;
+            this.observer = undefined;
         }
     }
 
     // eslint-disable-next-line no-undef
-    private scrollToHash(headingElements: NodeListOf<Element>): void {
+    protected scrollToHash(headingElements: NodeListOf<Element>): void {
         let { hash } = window.location;
         if (hash) {
             hash = hash.substr(1);
-            for (const headingElement of headingElements) {
+
+            const docHeaderEl = document.querySelector(
+                ".sticky-doc-header"
+            ) as HTMLElement;
+            const globalNavEl = document.querySelector(
+                "hgf-c360nav"
+            ) as HTMLElement;
+            const contextNavEl = document.querySelector(
+                "hgf-c360contextnav"
+            ) as HTMLElement;
+
+            const headerHeight =
+                docHeaderEl?.offsetHeight +
+                globalNavEl?.offsetHeight +
+                contextNavEl?.offsetHeight;
+
+            const docPhaseEl = (
+                this.template.querySelector("[name=doc-phase]")! as any
+            ).assignedElements()[0] as HTMLSlotElement;
+
+            const offset = docPhaseEl
+                ? headerHeight + docPhaseEl.offsetHeight
+                : headerHeight;
+
+            for (const headingElement of headingElements as any) {
                 if (headingElement.getAttribute("id") === hash) {
-                    headingElement.scrollIntoView({ behavior: "auto" });
+                    this.scrollIntoViewWithOffset(headingElement, offset);
                     break;
                 }
             }
         }
     }
 
-    private calculateActualSection(): void {
+    protected scrollIntoViewWithOffset(
+        headingElement: HTMLElement,
+        offset: number
+    ) {
+        window.scrollTo({
+            behavior: "auto",
+            top:
+                headingElement.getBoundingClientRect().top -
+                document.body.getBoundingClientRect().top -
+                offset
+        });
+    }
+
+    protected calculateActualSection(): void {
         const currentScrollPosition = document.documentElement.scrollTop;
         const id = Object.keys(this.anchoredElements).find(
             (_id) => this.anchoredElements[_id].intersect
@@ -292,18 +526,21 @@ export default class ContentLayout extends LightningElement {
         this.lastScrollPosition = currentScrollPosition;
     }
 
-    private calculatePreviousElementId(): string {
+    protected calculatePreviousElementId(): string | undefined {
         const keys = Object.keys(this.anchoredElements);
         const currentIndex = keys.findIndex((id) => this.tocValue === id);
 
         return currentIndex > 0 ? keys[currentIndex - 1] : undefined;
     }
 
-    private assignElementId(id: string): void {
-        this.tocValue = id;
+    protected assignElementId(id: string | undefined): void {
+        // Change toc(RNB) highlight only for H2
+        if (this.tocOptionIdsSet.has(id)) {
+            this.tocValue = id;
+        }
     }
 
-    private dispatchHighlightChange(term: string): void {
+    protected dispatchHighlightChange(term: string): void {
         this.dispatchEvent(
             new CustomEvent("highlightedtermchange", {
                 detail: term,
@@ -313,10 +550,21 @@ export default class ContentLayout extends LightningElement {
         );
     }
 
-    private updateHighlightsAndSearch(nextSearchString: string): void {
+    protected updateHighlightsAndSearch(nextSearchString: string): void {
         const nextSearchParam =
             new URLSearchParams(nextSearchString).get("q") || "";
         this.setSidebarInputValue(nextSearchParam);
         this.dispatchHighlightChange(nextSearchParam);
     }
+
+    protected onToggleSidebar(e: CustomEvent): void {
+        this.sidebarOpen = e.detail.open;
+
+        // eslint-disable-next-line @lwc/lwc/no-document-query
+        const footer = document.querySelector("dx-footer") as HTMLElement;
+
+        if (footer) {
+            footer.style.display = this.sidebarOpen ? "none" : "block";
+        }
+    }
 }

package/src/modules/doc/contentMedia/contentMedia.css

@@ -29,7 +29,7 @@
 
 .content-media-iframe {
     position: relative;
-    padding-bottom: calc(var(--aspect-ratio, 0.5625) * 100%);
+    padding-bottom: calc(var(--aspect-ratio, 0.5626) * 100%);
     height: 0;
 }
 

package/src/modules/doc/doDont/doDont.css

@@ -0,0 +1,47 @@
+@import "dxHelpers/reset";
+@import "dxHelpers/text";
+
+.container {
+    display: flex;
+    flex-direction: column;
+    gap: var(--dx-g-spacing-md);
+    flex: 1;
+}
+
+.doc-do-dont-header {
+    display: flex;
+    align-items: center;
+    gap: var(--dx-g-spacing-sm);
+}
+
+.doc-do-dont-label {
+    font-family: var(--dx-g-font-display);
+    font-size: var(--dx-g-spacing-md);
+    font-weight: var(--dx-g-font-demi);
+    line-height: var(--dx-g-spacing-lg);
+}
+
+.doc-do-color {
+    color: var(--dx-g-green-vibrant-50);
+}
+
+.doc-dont-color {
+    color: var(--dx-g-red-vibrant-30);
+}
+
+.do-dont-image-container {
+    display: flex;
+    max-height: 480px;
+    min-height: 140px;
+    padding: var(--dx-g-spacing-3xl) var(--dx-g-spacing-2xl);
+    flex-direction: column;
+    justify-content: center;
+    align-items: center;
+    flex: 1;
+    border-radius: var(--dx-g-spacing-sm);
+    border: 1px solid var(--dx-g-brand-default-color-border-2);
+}
+
+.doc-do-dont-img {
+    object-fit: contain;
+}

package/src/modules/doc/doDont/doDont.html

@@ -0,0 +1,27 @@
+<template>
+    <div class="container">
+        <div class="doc-do-dont-header">
+            <template lwc:if={isDo}>
+                <dx-icon
+                    symbol="success"
+                    size="large"
+                    color="green-vibrant-50"
+                ></dx-icon>
+                <div class="doc-do-dont-label doc-do-color">Do</div>
+            </template>
+            <template lwc:else>
+                <dx-icon
+                    symbol="clear"
+                    size="large"
+                    color="red-vibrant-30"
+                    class="doc-do-dont-icon"
+                ></dx-icon>
+                <div class="doc-do-dont-label doc-dont-color">Don't</div>
+            </template>
+        </div>
+        <div class="do-dont-image-container">
+            <img class="doc-do-dont-img" src={imgSrc} alt={caption} />
+        </div>
+        <div class="dx-text-body-4">{caption}</div>
+    </div>
+</template>