@salesforcedevs/docs-components 0.54.0 → 0.54.1-a01

package/src/modules/doc/contentCallout/contentCallout.ts

@@ -26,6 +26,11 @@ export default class ContentCallout extends LightningElement {
                 this.iconColor = "red-vibrant-50";
                 this.iconName = "alert";
                 break;
+            case "important":
+                this.cardVariant = "doc-status-container dx-callout-important";
+                this.iconColor = "gray-10";
+                this.iconName = "announcement";
+                break;
             case "note":
             default:
                 this.cardVariant = "dx-callout-note";

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

@@ -0,0 +1,98 @@
+:host {
+    --dx-c-content-vertical-spacing: var(--dx-g-spacing-lg);
+
+    display: block;
+}
+
+doc-breadcrumbs {
+    --dx-c-popover-z-index: 5;
+
+    display: block;
+    margin-bottom: var(--dx-g-spacing-2xl);
+}
+
+dx-sidebar,
+dx-sidebar-old {
+    --dx-c-sidebar-height: 100%;
+    --dx-c-sidebar-vertical-padding: var(--dx-c-content-vertical-spacing);
+
+    z-index: 6;
+}
+
+dx-toc {
+    --dx-c-toc-width: unset;
+
+    height: calc(100% - var(--dx-c-content-vertical-spacing) * 2);
+    margin: var(--dx-c-content-vertical-spacing) 0;
+    overflow-y: auto;
+}
+
+dx-sidebar,
+dx-toc {
+    display: block;
+}
+
+.content {
+    display: flex;
+}
+
+.content-body-doc-phase-container {
+    flex: 1;
+}
+
+.content-body-container {
+    display: flex;
+    flex-direction: row;
+    padding-right: var(--dx-g-page-padding-horizontal);
+}
+
+.content-body {
+    margin: var(--dx-g-spacing-sm) var(--dx-c-content-vertical-spacing)
+        var(--dx-g-spacing-xl);
+    flex: 1;
+    width: 0;
+}
+
+.is-sticky {
+    height: 100vh;
+    position: sticky;
+    top: 0;
+}
+
+.right-nav-bar {
+    max-width: 275px;
+}
+
+@media screen and (max-width: 1024px) {
+    .right-nav-bar {
+        display: none;
+    }
+}
+
+@media screen and (max-width: 800px) {
+    .content-body {
+        margin-top: var(--dx-c-content-vertical-spacing);
+    }
+}
+
+@media screen and (max-width: 768px) {
+    .content {
+        flex-direction: column;
+    }
+
+    .content-body-container {
+        padding-right: 0;
+    }
+
+    .left-nav-bar {
+        --dx-c-sidebar-height: 80vh;
+
+        height: unset;
+        z-index: 10;
+    }
+
+    .content-body {
+        margin-left: var(--dx-g-spacing-mlg, 20px);
+        margin-right: var(--dx-g-spacing-mlg, 20px);
+    }
+}

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

@@ -0,0 +1,48 @@
+<template>
+    <div class="content">
+        <template if:true={useOldSidebar}>
+            <dx-sidebar-old
+                class="is-sticky left-nav-bar"
+                trees={sidebarContent}
+                value={sidebarValue}
+                header={sidebarHeader}
+            >
+                <slot name="sidebar-header" slot="header"></slot>
+            </dx-sidebar-old>
+        </template>
+        <template if:false={useOldSidebar}>
+            <dx-sidebar
+                class="is-sticky left-nav-bar"
+                trees={sidebarContent}
+                value={sidebarValue}
+                header={sidebarHeader}
+                coveo-organization-id={coveoOrganizationId}
+                coveo-public-access-token={coveoPublicAccessToken}
+                coveo-search-hub={coveoSearchHub}
+                coveo-advanced-query-config={coveoAdvancedQueryConfig}
+            >
+                <slot name="sidebar-header" slot="header"></slot>
+            </dx-sidebar>
+        </template>
+        <div class="content-body-doc-phase-container">
+            <slot name="doc-phase"></slot>
+            <div class="content-body-container">
+                <div class="content-body">
+                    <doc-breadcrumbs
+                        if:true={breadcrumbs}
+                        breadcrumbs={breadcrumbs}
+                    ></doc-breadcrumbs>
+                    <slot onslotchange={onSlotChange}></slot>
+                </div>
+                <div class="right-nav-bar is-sticky">
+                    <dx-toc
+                        if:true={showToc}
+                        title={tocTitle}
+                        options={tocOptions}
+                        value={tocValue}
+                    ></dx-toc>
+                </div>
+            </div>
+        </div>
+    </div>
+</template>

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

@@ -0,0 +1,287 @@
+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";
+
+type AnchorMap = { [key: string]: { intersect: boolean; id: string } };
+
+const TOC_HEADER_TAG = "DOC-HEADING";
+const HIGHLIGHTABLE_SELECTOR = [
+    "p",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "li",
+    "dl",
+    "th",
+    "td"
+].join(",");
+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 coveoSearchHub!: string;
+    @api coveoAdvancedQueryConfig!: string;
+    @api useOldSidebar?: boolean = 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) {
+        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")?.setInputValue(searchTerm);
+    }
+
+    @track
+    private _sidebarContent: unknown;
+
+    private _breadcrumbs = null;
+
+    @track
+    private _tocOptions: Array<unknown>;
+
+    private anchoredElements: AnchorMap = {};
+    private lastScrollPosition: number;
+    private observer?: IntersectionObserver;
+    private searchSyncer = new SearchSyncer({
+        callbacks: {
+            onUrlChange: (nextSearchString: string): void => {
+                this.updateHighlightsAndSearch(nextSearchString);
+            },
+            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;
+    private observerTimerId = null;
+    private didScrollToSelectedHash = false;
+
+    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;
+    }
+
+    connectedCallback(): void {
+        const hasParentHighlightListener = closest(
+            "doc-xml-content",
+            this.template.host
+        );
+        if (!hasParentHighlightListener) {
+            window.addEventListener(
+                "highlightedtermchange",
+                this.updateHighlighted
+            );
+            this.searchSyncer.init();
+        }
+    }
+
+    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(
+            "highlightedtermchange",
+            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 => {
+        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();
+        });
+
+        // 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(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 {
+        if (this.observer) {
+            this.observer.disconnect();
+            this.observer = null;
+        }
+    }
+
+    // eslint-disable-next-line no-undef
+    private scrollToHash(headingElements: NodeListOf<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;
+                }
+            }
+        }
+    }
+
+    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 {
+        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;
+    }
+
+    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);
+    }
+}

package/src/modules/doc/header/header.css

@@ -1,4 +1,4 @@
-@import "helpers/commonHeader";
+@import "dxHelpers/commonHeader";
 
 dx-logo {
     min-width: fit-content;

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

@@ -1,8 +1,8 @@
 import { api } from "lwc";
 import cx from "classnames";
-import type { Option } from "typings/custom";
-import { HeaderBase } from "base-elements/headerBase";
-import { toJson } from "utils/normalizers";
+import type { OptionWithNested, OptionWithLink } from "typings/custom";
+import { HeaderBase } from "dxBaseElements/headerBase";
+import { toJson } from "dxUtils/normalizers";
 import get from "lodash.get";
 
 const TABLET_MATCH = "980px";
@@ -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/headingAnchor/headingAnchor.css

@@ -1,4 +1,4 @@
-@import "helpers/reset";
+@import "dxHelpers/reset";
 
 button {
     opacity: 0;

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

@@ -1,4 +1,4 @@
-@import "helpers/reset";
+@import "dxHelpers/reset";
 
 :host {
     --doc-c-heading-anchor-button-bottom: 0;
@@ -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/phase/phase.css

@@ -1,6 +1,6 @@
-@import "helpers/reset";
-@import "helpers/text";
-@import "helpers/status";
+@import "dxHelpers/reset";
+@import "dxHelpers/text";
+@import "docHelpers/status";
 
 .doc-phase-container {
     display: flex;

package/src/modules/doc/phase/phase.ts

@@ -2,7 +2,7 @@ import { LightningElement, api } from "lwc";
 import cx from "classnames";
 
 import { DocPhaseInfo } from "typings/custom";
-import { toJson } from "utils/normalizers";
+import { toJson } from "dxUtils/normalizers";
 
 export default class Phase extends LightningElement {
     _docPhaseInfo: DocPhaseInfo | null = null;

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

@@ -0,0 +1,114 @@
+export type CoveoAdvancedQueryXMLConfig = {
+    locale?: string;
+    version?: string;
+    topicid?: string;
+};
+
+export type PageReference = {
+    domain?: string;
+    page?: string;
+    docId?: string;
+    deliverable?: string;
+    contentDocumentId?: string;
+    hash?: string;
+    search?: string;
+};
+
+export enum HistoryState {
+    PUSH_STATE = "pushState",
+    REPLACE_STATE = "replaceState"
+}
+
+export type TreeNode = {
+    label: string;
+    name: string;
+    children?: Array<TreeNode>;
+    isExpanded?: boolean;
+    parent?: TreeNode;
+};
+
+type DropdownOption = {
+    id: string;
+    label: string;
+};
+
+export type DocVersion = DropdownOption & {
+    releaseVersion: string;
+    url: string;
+};
+
+export type DocLanguage = DropdownOption & {
+    code: string;
+    url: string;
+};
+
+export type ApiDocVersion = {
+    version_text: string;
+    release_version: string;
+    doc_version: string;
+    version_url: string;
+};
+
+export type ApiDocLanguage = {
+    code: string;
+    label: string;
+    locale: string;
+    url: string;
+};
+
+export interface Header extends Element {
+    subtitle: string;
+    bailHref: string;
+    bailLabel: string;
+    languages: Array<DocLanguage>;
+    language: string;
+    headerHref: string;
+}
+
+export type ApiNavItem = {
+    children: Array<ApiNavItem>;
+    text: string;
+    a_attr: {
+        href: string;
+    };
+    id: string;
+};
+
+export type ApiDocData = {
+    available_languages: Array<ApiDocLanguage>;
+    available_versions: Array<ApiDocVersion>;
+    content: string;
+    content_document_id: string;
+    deliverable: string;
+    doc_title: string;
+    language: ApiDocLanguage;
+    title: string;
+    toc: Array<ApiNavItem>;
+    version: ApiDocVersion;
+    pdf_url: string;
+};
+
+export type ContentData = {
+    content: string;
+    id: string;
+    title: string;
+};
+
+export type DocumentData = ContentData & {
+    availableLanguages: Array<DocLanguage>;
+    availableVersions: Array<DocVersion>;
+    deliverable: string;
+    docTitle: string;
+    language: DocLanguage;
+    toc: Array<TreeNode>;
+    tocMap: { [key: string]: TreeNode };
+    version: DocVersion;
+    pdfUrl: string;
+};
+
+export type ContentApiOptions = {
+    version: string;
+    language: string;
+};
+
+export type TocMap = { [key: string]: TreeNode };