@salesforcedevs/docs-components 0.6.0 → 0.7.59-sppage-alpha1

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

@@ -0,0 +1,610 @@
+/* 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 type { OptionWithLink } from "typings/custom";
+
+type AnchorMap = { [key: string]: { intersect: boolean; id: string } };
+
+declare const Sprig: (eventType: string, eventNme: string) => void;
+
+const TOC_HEADER_TAG = "doc-heading";
+const RNB_BY_TAB = "docs-tab";
+const HIGHLIGHTABLE_SELECTOR = [
+    "p",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "li",
+    "dl",
+    "th",
+    "td"
+].join(",");
+export const OBSERVER_ATTACH_WAIT_TIME = 500;
+
+export default class ContentLayout extends LightningElement {
+    @api sidebarValue!: string;
+    @api sidebarHeader!: string;
+    @api tocTitle!: string;
+    @api enableSlotChange = false;
+    @api coveoOrganizationId!: string;
+    @api coveoPublicAccessToken!: string;
+    @api coveoAnalyticsToken!: string;
+    @api coveoSearchHub!: string;
+    @api coveoAdvancedQueryConfig!: string;
+    @api useOldSidebar?: boolean = false;
+    @api languages!: OptionWithLink[];
+    @api language!: string;
+    @api bailHref!: string;
+    @api bailLabel!: string;
+
+    // This is needed for now to prevent failing snapshot tests due to links in the footer
+    @api showFooter = false;
+
+    @api
+    get breadcrumbs() {
+        return this._breadcrumbs;
+    }
+
+    set breadcrumbs(value) {
+        if (value) {
+            this._breadcrumbs = toJson(value);
+        }
+    }
+
+    @api
+    get sidebarContent() {
+        return this._sidebarContent;
+    }
+
+    set sidebarContent(value: any) {
+        this._sidebarContent = toJson(value);
+    }
+
+    @api
+    get tocOptions() {
+        return this._tocOptions;
+    }
+
+    set tocOptions(value) {
+        this._tocOptions = toJson(value);
+    }
+
+    @api
+    setSidebarInputValue(searchTerm: string): void {
+        (this.template.querySelector("dx-sidebar") as any)?.setInputValue(
+            searchTerm
+        );
+    }
+
+    @track
+    private _sidebarContent: unknown;
+
+    private _breadcrumbs = null;
+
+    @track
+    private _tocOptions!: Array<unknown>;
+
+    private tocOptionIdsSet = new Set();
+    private anchoredElements: AnchorMap = {};
+    private lastScrollPosition!: number;
+    private observer?: IntersectionObserver;
+    private hasRendered: boolean = false;
+    private contentLoaded: boolean = false;
+    private sidebarOpen: boolean = false;
+    private rnbByTab: boolean = false;
+
+    get shouldDisplayFeedback() {
+        return this.contentLoaded && typeof Sprig !== "undefined";
+    }
+
+    private setRNBByTab() {
+        const tabPanelListItem: any = this.getTabPanelList();
+        this.rnbByTab = tabPanelListItem?.id === RNB_BY_TAB ? true : false;
+    }
+
+    get showTabBasedRNB() {
+        return this.rnbByTab;
+    }
+
+    onTabChanged = () => {
+        this.updateRNB();
+    };
+
+    private getTabPanelList() {
+        return document.querySelector("dx-tab-panel-list");
+    }
+
+    updateRNB = () => {
+        const headingElements = this.getHeadingElements();
+        headingElements.forEach((headingElement: any) => {
+            // Sometimes elements hash and header is not being set when slot content is wrapped with div
+            headingElement.hash = headingElement.attributes.hash?.nodeValue;
+            headingElement.header = headingElement.attributes.header?.nodeValue;
+        });
+        this.updateTocItems(headingElements);
+    };
+
+    private getHeadingElements() {
+        let headingElements = document.querySelectorAll(TOC_HEADER_TAG);
+        if (this.showTabBasedRNB) {
+            const tabPanelListItem: any = this.getTabPanelList();
+            const tabPanels =
+                tabPanelListItem?.querySelectorAll("dx-tab-panel");
+            for (const tabPanelItem of tabPanels) {
+                if (tabPanelItem.active) {
+                    headingElements =
+                        tabPanelItem.querySelectorAll(TOC_HEADER_TAG);
+                    break;
+                }
+            }
+        }
+        return headingElements;
+    }
+
+    private updateURL() {
+        const tabs = this.getAllTabs();
+        const selectedTabId = this.getSelectedTabId();
+        tabs.forEach((tab: any) => {
+            if (tab.getAttribute("aria-selected") === "true") {
+                const tabID = tab.getAttribute("aria-label");
+                const url = new URL(window.location.href);
+                if (selectedTabId !== tabID) {
+                    url.searchParams.set("type", tabID);
+                    url.hash = "";
+                    window.history.pushState({}, "", url.toString());
+                }
+            }
+        });
+    }
+
+    private searchSyncer = new SearchSyncer({
+        callbacks: {
+            onSearchChange: (nextSearchString: string): void => {
+                this.dispatchHighlightChange(
+                    new URLSearchParams(nextSearchString).get("q") || ""
+                );
+            }
+        },
+        eventName: "sidebarsearchchange",
+        historyMethod: window.history.pushState,
+        searchParam: "q",
+        shouldStopPropagation: true,
+        target: window
+    });
+    private tocValue?: string = undefined;
+    // eslint-disable-next-line no-undef
+    private observerTimerId?: NodeJS.Timeout;
+    private didScrollToSelectedHash = false;
+    private _scrollInterval = 0;
+
+    get showToc(): boolean {
+        return this.tocOptions && this.tocOptions.length > 0;
+    }
+
+    // ? This could be a good default for pathname in dx-breadcrumbs. Using this getter for now as a workaround.
+    get pathname(): string {
+        return window.location.pathname;
+    }
+
+    get showBreadcrumbs(): boolean {
+        return (
+            this.breadcrumbs != null && (this.breadcrumbs as any[]).length > 1
+        );
+    }
+
+    // This event gets triggered when navigating back/forward
+    handlePopState = (): void => {
+        if (this.showTabBasedRNB) {
+            this.restoreTabSelection();
+        }
+    };
+
+    connectedCallback(): void {
+        const hasParentHighlightListener = closest(
+            "doc-xml-content",
+            this.template.host
+        );
+        if (!hasParentHighlightListener) {
+            window.addEventListener(
+                "highlightedtermchange",
+                this.updateHighlighted
+            );
+            this.searchSyncer.init();
+        }
+        window.addEventListener("popstate", this.handlePopState);
+    }
+
+    private getSelectedTabId() {
+        const urlParams = new URLSearchParams(window.location.search);
+        const selectedTabId = urlParams.get("type");
+        return selectedTabId;
+    }
+
+    private restoreTabSelection() {
+        requestAnimationFrame(() => {
+            const selectedTabId = this.getSelectedTabId();
+            if (selectedTabId) {
+                this.selectTabById(selectedTabId);
+            }
+        });
+    }
+
+    private getAllTabs(): any[] {
+        const tabPanelListItem: any = this.getTabPanelList();
+        if (tabPanelListItem?.shadowRoot) {
+            return Array.from(
+                tabPanelListItem.shadowRoot.querySelectorAll(
+                    "dx-tab-panel-item"
+                )
+            ).map((tabPanelItem: any) =>
+                tabPanelItem.shadowRoot.querySelector("button")
+            );
+        }
+        return [];
+    }
+
+    private selectTabById(tabId: string) {
+        const tabs = this.getAllTabs();
+        tabs.forEach((tab: any) => {
+            if (tab.getAttribute("aria-label") === tabId) {
+                tab.click();
+            }
+        });
+    }
+
+    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
+        );
+
+        this.adjustNavPosition();
+        window.addEventListener("scroll", this.adjustNavPosition);
+        window.addEventListener("resize", this.adjustNavPosition);
+
+        if (!this.hasRendered) {
+            this.hasRendered = true;
+            this.setRNBByTab();
+            if (this.showTabBasedRNB) {
+                window.addEventListener("tabchanged", this.onTabChanged);
+                this.restoreTabSelection();
+            }
+            this.restoreScroll();
+        }
+    }
+
+    disconnectedCallback(): void {
+        this.disconnectObserver();
+        window.removeEventListener(
+            "highlightedtermchange",
+            this.updateHighlighted
+        );
+        window.removeEventListener("scroll", this.adjustNavPosition);
+        window.removeEventListener("resize", this.adjustNavPosition);
+        window.removeEventListener("tabchanged", this.onTabChanged);
+        window.removeEventListener("popstate", this.handlePopState);
+        this.searchSyncer.dispose();
+        this.clearRenderObserverTimer();
+
+        window.clearInterval(this._scrollInterval);
+    }
+
+    restoreScroll() {
+        document.body.scrollTop = document.documentElement.scrollTop =
+            window.history.state?.scrollValue;
+    }
+
+    clearRenderObserverTimer = () => {
+        if (this.observerTimerId) {
+            clearTimeout(this.observerTimerId);
+        }
+    };
+
+    /*
+        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 sidebarType = this.useOldSidebar
+            ? "dx-sidebar-old"
+            : "dx-sidebar";
+        const sidebarEl = this.template.querySelector(sidebarType);
+        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;
+
+        let docPhaseEl = (
+            this.template.querySelector("[name=doc-phase]")! as any
+        ).assignedElements()[0] as HTMLSlotElement;
+
+        if (!docPhaseEl) {
+            docPhaseEl = (
+                this.template.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`
+            );
+
+            // Adjusting the doc section heading on scroll.
+            docHeadingEls.forEach((docHeadingEl) => {
+                (docHeadingEl as any).style.scrollMarginTop = docPhaseEl
+                    ? `${
+                          totalHeaderHeight +
+                          docPhaseEl.getBoundingClientRect().height +
+                          40
+                      }px`
+                    : `${totalHeaderHeight + 40}px`;
+            });
+
+            // Adjusting the right nav bar on scroll.
+            if (rightNavBarEl) {
+                rightNavBarEl.style.top = docPhaseEl
+                    ? `${
+                          totalHeaderHeight +
+                          docPhaseEl.getBoundingClientRect().height
+                      }px`
+                    : `${totalHeaderHeight}px`;
+            }
+
+            // If doc phase element exists, we need to account for its sticky position. Mobile should include the sidebar height (since it becomes sticky aswell).
+            if (docPhaseEl) {
+                docPhaseEl.style.setProperty(
+                    "--doc-c-phase-top",
+                    `${
+                        window.innerWidth < 769
+                            ? globalNavHeight +
+                              docHeaderHeight +
+                              sidebarEl.getBoundingClientRect().height
+                            : globalNavHeight + docHeaderHeight
+                    }px`
+                );
+            }
+        });
+    };
+
+    updateHighlighted = (event: Event): void =>
+        highlightTerms(
+            this.querySelectorAll(HIGHLIGHTABLE_SELECTOR),
+            (event as CustomEvent<string>).detail
+        );
+
+    attachInteractionObserver = (): void => {
+        if (!this.enableSlotChange) {
+            return;
+        }
+        this.disconnectObserver();
+
+        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)
+                );
+                this.calculateActualSection();
+            },
+            {
+                rootMargin: globalNavOffset.trim()
+            }
+        );
+
+        // Note: We are doing document.querySelectorAll as a quick fix as we are not getting heading elements reference this.querySelectorAll
+        const headingElements = this.getHeadingElements();
+
+        // We only need to update URL in case of /docs and ignore if tabs are used anywhere else in DSC
+        if (this.showTabBasedRNB) {
+            this.updateURL();
+        }
+
+        for (const headingElement of headingElements as any) {
+            // 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(headingElement);
+        }
+
+        if (!this.didScrollToSelectedHash) {
+            this.didScrollToSelectedHash = true;
+            this.scrollToHash(headingElements);
+        }
+    };
+
+    onSlotChange(): void {
+        this.updateRNB();
+        this.contentLoaded = true;
+    }
+
+    // eslint-disable-next-line no-undef
+    private updateTocItems(headingElements: NodeListOf<Element>): void {
+        const tocOptions = [];
+
+        for (const headingElement of headingElements as any) {
+            headingElement.id = headingElement.hash;
+
+            // Update tocOptions from anchorTags only for H2, consider default as 2 as per component
+            const headingAriaLevel =
+                headingElement.attributes["aria-level"]?.nodeValue || "2";
+            const isH2 = headingAriaLevel === "2";
+
+            if (isH2) {
+                const tocItem = {
+                    anchor: `#${headingElement.hash}`,
+                    id: headingElement.id,
+                    label: headingElement.header
+                };
+                tocOptions.push(tocItem);
+                this.tocOptionIdsSet.add(headingElement.id);
+            }
+        }
+
+        this._tocOptions = tocOptions;
+    }
+
+    private disconnectObserver(): void {
+        if (this.observer) {
+            this.observer.disconnect();
+            this.observer = undefined;
+        }
+    }
+
+    // eslint-disable-next-line no-undef
+    private scrollToHash(headingElements: NodeListOf<Element>): void {
+        let { hash } = window.location;
+        if (hash) {
+            hash = hash.substr(1);
+
+            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) {
+                    this.scrollIntoViewWithOffset(headingElement, offset);
+                    break;
+                }
+            }
+        }
+    }
+
+    private scrollIntoViewWithOffset(
+        headingElement: HTMLElement,
+        offset: number
+    ) {
+        window.scrollTo({
+            behavior: "auto",
+            top:
+                headingElement.getBoundingClientRect().top -
+                document.body.getBoundingClientRect().top -
+                offset
+        });
+    }
+
+    private calculateActualSection(): void {
+        const currentScrollPosition = document.documentElement.scrollTop;
+        const id = Object.keys(this.anchoredElements).find(
+            (_id) => this.anchoredElements[_id].intersect
+        );
+        if (id) {
+            this.assignElementId(id);
+        } else if (currentScrollPosition < this.lastScrollPosition) {
+            // The user has scroll up since last update
+            this.assignElementId(this.calculatePreviousElementId());
+        }
+
+        this.lastScrollPosition = currentScrollPosition;
+    }
+
+    private 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 | undefined): void {
+        // Change toc(RNB) highlight only for H2
+        if (this.tocOptionIdsSet.has(id)) {
+            this.tocValue = id;
+        }
+    }
+
+    private dispatchHighlightChange(term: string): void {
+        this.dispatchEvent(
+            new CustomEvent("highlightedtermchange", {
+                detail: term,
+                bubbles: true,
+                composed: true
+            })
+        );
+    }
+
+    private updateHighlightsAndSearch(nextSearchString: string): void {
+        const nextSearchParam =
+            new URLSearchParams(nextSearchString).get("q") || "";
+        this.setSidebarInputValue(nextSearchParam);
+        this.dispatchHighlightChange(nextSearchParam);
+    }
+
+    private 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/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>

package/src/modules/doc/doDont/doDont.ts

@@ -0,0 +1,17 @@
+import { LightningElement, api } from "lwc";
+import { normalizeBoolean } from "dxUtils/normalizers";
+
+export default class DoDont extends LightningElement {
+    @api caption: string = "";
+    @api imgSrc!: string;
+    _isDo: boolean = false;
+
+    @api
+    get isDo(): boolean {
+        return this._isDo;
+    }
+
+    set isDo(value) {
+        this._isDo = normalizeBoolean(value);
+    }
+}