@salesforcedevs/docs-components 0.54.0 → 0.54.7-alpha

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

@@ -0,0 +1,242 @@
+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(",");
+
+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;
+
+    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();
+        }
+    }
+
+    disconnectedCallback(): void {
+        this.disconnectObserver();
+        window.removeEventListener(
+            "highlightedtermchange",
+            this.updateHighlighted
+        );
+        this.searchSyncer.dispose();
+    }
+
+    updateHighlighted = (event: Event): void =>
+        highlightTerms(
+            this.querySelectorAll(HIGHLIGHTABLE_SELECTOR),
+            (event as CustomEvent<string>).detail
+        );
+
+    onSlotChange(event: Event): 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();
+        });
+
+        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(section);
+        });
+    }
+
+    private disconnectObserver(): void {
+        if (this.observer) {
+            this.observer.disconnect();
+            this.observer = null;
+        }
+    }
+
+    private scrollToHash(anchoredTags: Array<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" });
+            }
+        }
+    }
+
+    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;

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,113 @@
+export type CoveoAdvancedQueryXMLConfig = {
+    objecttype?: string;
+    sflocale__c?: string;
+    sfrelease__c?: string;
+    sfdelivarable__c?: string;
+    source?: 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;
+};
+
+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;
+};

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

@@ -0,0 +1,158 @@
+import {
+    ApiDocData,
+    ApiDocLanguage,
+    ApiDocVersion,
+    ApiNavItem,
+    ContentApiOptions,
+    ContentData,
+    DocumentData,
+    DocLanguage,
+    DocVersion,
+    TreeNode
+} from "./types";
+import { Language } from "typings/custom";
+import { getLanguageDisplayTextById } from "dxUtils/language";
+
+export class FetchContent {
+    private apiDomain: string;
+    private languages: Array<Language> = [];
+
+    constructor(apiDomain: string, languages: Array<Language>) {
+        this.apiDomain = apiDomain;
+        this.languages = languages;
+    }
+
+    async fetchDocumentData(docId: string): Promise<DocumentData | null> {
+        try {
+            const {
+                available_languages,
+                available_versions,
+                toc,
+                content,
+                version,
+                language,
+                content_document_id,
+                title,
+                doc_title,
+                pdf_url,
+                deliverable
+            } = await this.fetchResource<ApiDocData>(
+                `${this.apiDomain}/docs/get_document/${docId}`
+            );
+
+            const { normalizedToc, tocMap } = this.normalizeToc(toc);
+            return {
+                availableLanguages:
+                    available_languages &&
+                    available_languages.map(this.normalizeLanguage.bind(this)),
+                availableVersions:
+                    available_versions &&
+                    available_versions.map(this.normalizeVersion.bind(this)),
+                content,
+                version: this.normalizeVersion(version),
+                id: content_document_id,
+                language: this.normalizeLanguage(language),
+                title,
+                toc: normalizedToc,
+                tocMap,
+                docTitle: doc_title,
+                pdfUrl: pdf_url,
+                deliverable
+            };
+        } catch (error) {
+            console.log(error);
+            return null;
+        }
+    }
+
+    fetchContent(
+        deliverable: string,
+        contentId: string,
+        options: ContentApiOptions
+    ): Promise<ContentData> {
+        return this.fetchResource<ContentData>(
+            `${this.apiDomain}/docs/get_document_content/${deliverable}/${contentId}/${options.language}/${options.version}`
+        );
+    }
+
+    private async fetchResource<T>(url: string): Promise<T> {
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new Error(response.statusText);
+        }
+
+        const json = await response.json();
+
+        return json;
+    }
+
+    private normalizeToc(apiToc: Array<ApiNavItem>): {
+        tocMap: { [key: string]: TreeNode };
+        normalizedToc: Array<TreeNode>;
+    } {
+        const tocMap = {};
+        const normalizedToc =
+            apiToc &&
+            apiToc.map((navItem) => this.normalizeNavItem(navItem, tocMap));
+
+        return { normalizedToc, tocMap };
+    }
+
+    private normalizeNavItem(
+        navItem: ApiNavItem,
+        tocMap: { [key: string]: TreeNode }
+    ): TreeNode {
+        const name = this.calculateNavItemName(navItem, tocMap);
+        const node: TreeNode = {
+            label: navItem.text,
+            name
+        };
+        if (name) {
+            tocMap[name] = node;
+        }
+        node.children = navItem.children?.map((child) =>
+            this.normalizeNavItem(child, tocMap)
+        );
+        return node;
+    }
+
+    private calculateNavItemName(
+        navItem: ApiNavItem,
+        tocMap: { [key: string]: TreeNode }
+    ): string {
+        let href = navItem.a_attr?.href || "";
+        if (href.includes("#")) {
+            const [pathUrl] = href.split("#");
+            href = pathUrl in tocMap ? href : pathUrl;
+        }
+        return href || navItem.id;
+    }
+
+    private normalizeVersion(version: ApiDocVersion): DocVersion {
+        return (
+            version && {
+                label: version.version_text,
+                releaseVersion:
+                    version.release_version &&
+                    !version.release_version.startsWith("v")
+                        ? `v${version.release_version}`
+                        : version.release_version,
+                id: version.doc_version,
+                url: version.version_url
+            }
+        );
+    }
+
+    private normalizeLanguage(language: ApiDocLanguage): DocLanguage {
+
+        return (
+            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

@@ -0,0 +1,25 @@
+:host {
+    --button-primary-color: var(--dx-g-blue-vibrant-50);
+    --button-primary-color-hover: var(--dx-g-blue-vibrant-40);
+}
+
+dx-dropdown {
+    --dx-c-dropdown-option-font-size: var(--dx-g-text-sm);
+}
+
+dx-dropdown > dx-button {
+    --dx-c-button-primary-color: var(--button-primary-color);
+    --dx-c-button-primary-color-hover: var(--button-primary-color-hover);
+    --border-color: var(--button-primary-color);
+
+    border-bottom: 1px dashed var(--border-color);
+}
+
+dx-dropdown > dx-button:hover {
+    --border-color: var(--button-primary-color-hover);
+}
+
+.document-pickers {
+    margin-left: auto;
+    margin-right: var(--dx-g-spacing-sm);
+}

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

@@ -0,0 +1,34 @@
+<template>
+    <doc-content-layout
+        if:true={loaded}
+        coveo-organization-id={coveoOrganizationId}
+        coveo-public-access-token={coveoPublicAccessToken}
+        coveo-search-hub="Developer_Docs_SS"
+        coveo-advanced-query-config={coveoAdvancedQueryConfig}
+        sidebar-header="Pages"
+        sidebar-content={sidebarContent}
+        sidebar-value={sidebarValue}
+        onselect={handleSelect}
+        use-old-sidebar
+    >
+        <div slot="sidebar-header" class="document-pickers">
+            <dx-dropdown
+                data-type="version"
+                suppress-gtm-nav-headings
+                analytics-event={analyticsEvent}
+                options={versionOptions}
+                value={version.id}
+                width="290px"
+            >
+                <dx-button variant="inline" disabled={disableVersion}>
+                    {version.releaseVersion}
+                </dx-button>
+            </dx-dropdown>
+        </div>
+        <doc-content
+            docs-data={docContent}
+            page-reference={pageReference}
+            onnavclick={handleNavClick}
+        ></doc-content>
+    </doc-content-layout>
+</template>