@salesforcedevs/docs-components 0.53.6 → 0.54.0-alpha01

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

@@ -0,0 +1,119 @@
+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 Labels = {
+    language_english: string;
+    language_japanese: string;
+    toc_title: string;
+};
+
+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,163 @@
+import {
+    ApiDocData,
+    ApiDocLanguage,
+    ApiDocVersion,
+    ApiNavItem,
+    ContentApiOptions,
+    ContentData,
+    DocumentData,
+    DocLanguage,
+    DocVersion,
+    Labels,
+    TreeNode
+} from "./types";
+
+const LOCALE_TO_LABEL = {
+    "en-us": "language_english",
+    "ja-jp": "language_japanese"
+};
+
+export class FetchContent {
+    private apiDomain: string;
+    private labels: Labels;
+
+    constructor(apiDomain: string, labels: Labels) {
+        this.apiDomain = apiDomain;
+        this.labels = labels;
+    }
+
+    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 {
+        const labelKey = language.locale && LOCALE_TO_LABEL[language.locale];
+        return (
+            language && {
+                label:
+                    (labelKey && this.labels && this.labels[labelKey]) ||
+                    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>