@salesforcedevs/docs-components 0.17.0 → 0.17.12-search-alpha

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

@@ -0,0 +1,120 @@
+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;
+    link?: {
+        href: 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;
+    headerHref: string;
+}
+
+export type SiderbarFooter = {
+    bailHref: string;
+    bailLabel: string;
+    languages: Array<DocLanguage>;
+    language?: 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 };

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

@@ -0,0 +1,163 @@
+import {
+    ApiDocData,
+    ApiDocLanguage,
+    ApiDocVersion,
+    ApiNavItem,
+    ContentApiOptions,
+    ContentData,
+    DocumentData,
+    DocLanguage,
+    DocVersion,
+    TreeNode,
+    TocMap
+} 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: TocMap,
+        parentNavItem?: TreeNode
+    ): TreeNode {
+        const name = this.calculateNavItemName(navItem, tocMap);
+        const node: TreeNode = {
+            label: navItem.text,
+            name,
+            parent: parentNavItem
+        };
+
+        if (name) {
+            tocMap[name] = node;
+        }
+        node.children = navItem.children?.map((child) =>
+            this.normalizeNavItem(child, tocMap, node)
+        );
+        return node;
+    }
+
+    private calculateNavItemName(navItem: ApiNavItem, tocMap: TocMap): 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,54 @@
+:host {
+    --button-primary-color: var(--dx-g-blue-vibrant-50);
+    --button-primary-color-hover: var(--dx-g-blue-vibrant-40);
+}
+
+doc-content-layout {
+    --dx-c-content-sidebar-sticky-top: var(--dx-g-global-header-height);
+    --dx-c-sidebar-height: calc(100vh - var(--dx-g-global-header-height));
+}
+
+doc-breadcrumbs {
+    --dx-c-popover-z-index: 5;
+
+    display: block;
+    margin-bottom: var(--dx-g-spacing-md);
+}
+
+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);
+}
+
+doc-phase {
+    --doc-c-phase-top: var(--dx-g-global-header-height);
+}
+
+@media screen and (max-width: 768px) {
+    doc-content-layout {
+        --dx-g-doc-header-main-nav-height: 41px;
+        --dx-g-doc-header-height: calc(
+            var(--dx-g-doc-header-main-nav-height) + 40px
+        );
+        --dx-c-content-sidebar-sticky-top: calc(
+            var(--dx-g-global-header-height) + var(--dx-g-doc-header-height)
+        );
+    }
+
+    doc-phase {
+        --doc-c-phase-top: calc(
+            var(--dx-g-global-header-height) + var(--dx-g-doc-header-height)
+        );
+    }
+}

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

@@ -0,0 +1,54 @@
+<template>
+    <doc-content-layout
+        lwc:if={displayContent}
+        lwc:ref="docContentLayout"
+        sidebar-header={docTitle}
+        sidebar-content={sidebarContent}
+        sidebar-value={sidebarValue}
+        onselect={handleSelect}
+        onlangchange={handleLanguageChange}
+        languages={sidebarFooterContent.languages}
+        language={sidebarFooterContent.language}
+        bail-href={sidebarFooterContent.bailHref}
+        bail-label={sidebarFooterContent.bailLabel}
+        show-footer={enableFooter}
+    >
+        <doc-phase
+            slot="version-banner"
+            lwc:if={showVersionBanner}
+            doc-phase-info={oldVersionInfo}
+            icon-name="warning"
+            dismissible="true"
+            ondismissphase={handleDismissVersionBanner}
+        ></doc-phase>
+        <div lwc:if={showVersionPicker} slot="sidebar-header">
+            <doc-version-picker
+                data-type="version"
+                analytics-event="custEv_ctaLinkClick"
+                analytics-payload={ANALYTICS_PAYLOAD}
+                versions={versionOptions}
+                selected-version={version}
+                latest-version={latestVersion}
+                hide-badge={previewVersion}
+            ></doc-version-picker>
+        </div>
+        <doc-breadcrumbs
+            lwc:if={showBreadcrumbs}
+            breadcrumbs={breadcrumbs}
+            pixel-per-character={breadcrumbPixelPerCharacter}
+        ></doc-breadcrumbs>
+        <doc-content
+            docs-data={docContent}
+            page-reference={pageReference}
+            onnavclick={handleNavClick}
+        ></doc-content>
+    </doc-content-layout>
+    <div lwc:if={display404}>
+        <dx-error
+            image="https://a.sfdcstatic.com/developer-website/images/404.svg"
+            code="404"
+            header="Beep boop. That did not compute."
+            subtitle="The document you're looking for doesn't seem to exist."
+        ></dx-error>
+    </div>
+</template>