@salesforcedevs/docs-components 0.54.0 → 0.54.7-alpha

package/src/modules/doc/amfTopic/amfTopic.ts

@@ -0,0 +1,94 @@
+import { LightningElement, api } from "lwc";
+import {
+    createDocumentationElement,
+    createEndpointElement,
+    createMethodElement,
+    createSecurityElement,
+    createSummaryElement,
+    createTypeElement
+} from "./utils";
+import type { TopicModel } from "./types";
+
+export default class AmfTopic extends LightningElement {
+    private _model;
+    private amf;
+    private type;
+
+    @api
+    get model(): TopicModel {
+        return this._model;
+    }
+
+    set model(value: TopicModel) {
+        if (
+            !this.amf ||
+            (value && this._model && value.amf !== this._model?.amf)
+        ) {
+            this.amf = value && clone(value.amf);
+        }
+        if (
+            !this.type ||
+            (value && this._model && value.type !== this._model?.type)
+        ) {
+            this.type = value && clone(value.type);
+        }
+
+        this._model = value;
+        if (this._model) {
+            this.update();
+        }
+        // else { Remove child? No model, seems like no component should be shown. }
+    }
+
+    update(): void {
+        const container = this.template.querySelector("div.topic-container");
+        const { id } = this.model;
+        const type = this.type;
+        const amf = this.amf;
+        const { parser } = this.model;
+        let element;
+
+        if (type === "summary") {
+            element = createSummaryElement(amf);
+        } else if (type === "endpoint") {
+            const endpointModel = parser.computeEndpointApiModel(amf, id);
+            element = createEndpointElement(amf, endpointModel, id);
+        } else if (type === "method") {
+            const endpointMethodModel = parser.computeEndpointApiMethodModel(
+                amf,
+                id
+            );
+            const methodModel = parser.computeMethodApiModel(amf, id);
+            element = createMethodElement(
+                amf,
+                endpointMethodModel,
+                methodModel
+            );
+        } else if (type === "security") {
+            const securityModel = parser.computeSecurityApiModel(amf, id);
+            element = createSecurityElement(amf, securityModel);
+        } else if (type === "type") {
+            const mediaTypes = parser.computeApiMediaTypes(amf);
+            const typeModel = parser.computeTypeApiModel(amf, id);
+            element = createTypeElement(amf, typeModel, mediaTypes);
+        } else if (type === "documentation") {
+            const docsModel = parser.computeDocsApiModel(amf, id);
+            element = createDocumentationElement(amf, docsModel);
+        }
+
+        if (container.firstChild) {
+            container.firstChild.remove();
+        }
+        container.appendChild(element);
+    }
+}
+
+/**
+ * The underlying web components we use from api-console mutate their models we pass in.
+ * Since LWC makes them Read Only, we need to copy them before passing to the Web Component.
+ * @param value JSON Serializable object to clone.
+ * @returns A copy of Value. One that has been serialized and parsed via JSON. (Functions, Regex, etc are not preserved.)
+ */
+function clone(value): object {
+    return JSON.parse(JSON.stringify(value));
+}

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

@@ -0,0 +1,54 @@
+import { Json } from "typings/custom";
+
+export type ApiSummaryElement = HTMLElement & {
+    amf: Json;
+    hideToc: boolean;
+    titleLevel: string;
+};
+
+export type ApiEndpointElement = HTMLElement & {
+    amf: Json;
+    inlineMethods: boolean;
+    noNavigation: boolean;
+    selected: string;
+    endpoint: Json;
+    noTryIt: boolean;
+};
+
+export type ApiMethodElement = HTMLElement & {
+    amf: Json;
+    noNavigation: boolean;
+    endpoint: Json;
+    method: Json;
+    noTryIt: boolean;
+};
+
+export type ApiSecurityElement = HTMLElement & {
+    amf: Json;
+    security: Json;
+};
+
+export type ApiTypeElement = HTMLElement & {
+    amf: Json;
+    type: Json;
+    mediaTypes: Json;
+};
+
+export type ApiDocElement = HTMLElement & {
+    amf: Json;
+    shape: Json;
+};
+
+export type AmfModel = Json;
+
+export interface AmfParser {
+    parse(): void;
+    parsedModel: any;
+}
+
+export interface TopicModel {
+    id: string;
+    type: string;
+    amf: AmfModel;
+    parser: AmfParser;
+}

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

@@ -0,0 +1,130 @@
+import type {
+    ApiDocElement,
+    ApiEndpointElement,
+    ApiMethodElement,
+    ApiSecurityElement,
+    ApiSummaryElement,
+    ApiTypeElement
+} from "./types";
+import { Json } from "typings/custom";
+
+export function createSummaryElement(amf: Json): HTMLElement {
+    const summaryElement: ApiSummaryElement = document.createElement(
+        "api-summary"
+    ) as ApiSummaryElement;
+    summaryElement.amf = amf;
+    summaryElement.hideToc = true;
+    summaryElement.titleLevel = "1";
+    summaryElement.setAttribute(
+        "exportparts",
+        [
+            "api-title",
+            "api-title-label",
+            "api-version",
+            "marked-description",
+            "info-section",
+            "info-inline-desc",
+            "license-section",
+            "separator",
+            "toc"
+        ].join(",")
+    );
+    return summaryElement;
+}
+
+/**
+ * Creates a `api-endpoint-documentation` web element from web API and current selection.
+ */
+export function createEndpointElement(
+    amf: Json,
+    endpointModel: Json,
+    selected: string
+): HTMLElement {
+    const el: ApiEndpointElement = document.createElement(
+        "api-endpoint-documentation"
+    ) as ApiEndpointElement;
+    el.amf = amf;
+    el.inlineMethods = false;
+    el.noNavigation = true;
+    el.selected = selected;
+    el.endpoint = endpointModel;
+    el.noTryIt = true;
+    return el;
+}
+
+/**
+ * Creates a `api-method-documentation` web element from web API and current selection.
+ */
+export function createMethodElement(
+    amf: Json,
+    endpointMethodModel: Json,
+    methodModel: Json
+): HTMLElement {
+    const el: ApiMethodElement = document.createElement(
+        "api-method-documentation"
+    ) as ApiMethodElement;
+    el.amf = amf;
+    el.noNavigation = true;
+    el.endpoint = endpointMethodModel;
+    el.method = methodModel;
+    el.noTryIt = true;
+    el.setAttribute("renderSecurity", "");
+    el.setAttribute("renderCodeSnippets", "");
+    return el;
+}
+
+/**
+ * Creates a documentation element for Security AMF type
+ *
+ */
+export function createSecurityElement(
+    amf: Json,
+    securityModel: Json
+): HTMLElement {
+    const el: ApiSecurityElement = document.createElement(
+        "api-security-documentation"
+    ) as ApiSecurityElement;
+    el.setAttribute("exportparts", ["security-title"].join(","));
+    el.amf = amf;
+    el.security = securityModel;
+    return el;
+}
+
+/**
+ * Creates a documentation element for Type AMF type
+ *
+ * @param {string} amfId Reference ID as passed in from amfConfig
+ * @param {string} selected Currently selected `@id`.
+ */
+export function createTypeElement(
+    amf: Json,
+    typeModel: Json,
+    mediaTypes: Json
+): HTMLElement {
+    const el: ApiTypeElement = document.createElement(
+        "api-type-documentation"
+    ) as ApiTypeElement;
+    el.setAttribute("exportparts", ["type-title"].join(","));
+    el.amf = amf;
+    el.type = typeModel;
+    el.mediaTypes = mediaTypes;
+    return el;
+}
+
+/**
+ * Creates a documentation element for Docs AMF type
+ *
+ * @param {string} amfId Reference ID as passed in from amfConfig
+ * @param {string} selected Currently selected `@id`.
+ */
+export function createDocumentationElement(
+    amf: Json,
+    docsModel: Json
+): HTMLElement {
+    const el: ApiDocElement = document.createElement(
+        "api-documentation-document"
+    ) as ApiDocElement;
+    el.amf = amf;
+    el.shape = docsModel;
+    return el;
+}

package/src/modules/doc/breadcrumbItem/breadcrumbItem.css

@@ -1,5 +1,5 @@
-@import "helpers/reset";
-@import "helpers/text";
+@import "dxHelpers/reset";
+@import "dxHelpers/text";
 
 :host {
     display: flex;

package/src/modules/doc/breadcrumbs/breadcrumbs.css

@@ -1,5 +1,5 @@
-@import "helpers/reset";
-@import "helpers/text";
+@import "dxHelpers/reset";
+@import "dxHelpers/text";
 
 :host {
     --dx-c-breadcrumbs-title-color: var(--dx-g-blue-vibrant-20);

package/src/modules/doc/breadcrumbs/breadcrumbs.ts

@@ -1,6 +1,6 @@
 import { LightningElement, api } from "lwc";
-import { Breadcrumb, Option } from "typings/custom";
-import { toJson } from "utils/normalizers";
+import { Breadcrumb, OptionWithLink } from "typings/custom";
+import { toJson } from "dxUtils/normalizers";
 
 type BreadcrumbConfig = {
     minWidth: number;
@@ -62,7 +62,7 @@ export default class Breadcrumbs extends LightningElement {
     private get renderDropdown(): boolean {
         return this.hasInternalBreadcrumbs && !!this.dropdownOptionAmount;
     }
-    private get dropdownOptions(): Option[] {
+    private get dropdownOptions(): OptionWithLink[] {
         return this.breadcrumbs!.slice(1, this.dropdownOptionAmount! + 1).map(
             (link) => ({
                 id: link.href!,

package/src/modules/doc/content/content.css

@@ -4,10 +4,10 @@
  * pattern validation cannot be applied
  */
 
-@import "helpers/text";
-@import "helpers/reset";
-@import "helpers/card";
-@import "helpers/table";
+@import "dxHelpers/text";
+@import "dxHelpers/reset";
+@import "dxHelpers/card";
+@import "dxHelpers/table";
 
 .doc-content {
     width: 100%;

package/src/modules/doc/content/content.ts

@@ -5,7 +5,7 @@ import ContentCallout from "doc/contentCallout";
 import CodeBlock from "dx/codeBlock";
 import ContentMedia from "doc/contentMedia";
 import Button from "dx/button";
-import { highlightTerms } from "utils/highlight";
+import { highlightTerms } from "dxUtils/highlight";
 
 const HIGHLIGHTABLE_SELECTOR = [
     "p",

package/src/modules/doc/contentCallout/contentCallout.css

@@ -1,6 +1,6 @@
-@import "helpers/reset";
-@import "helpers/text";
-@import "helpers/status";
+@import "dxHelpers/reset";
+@import "dxHelpers/text";
+@import "docHelpers/status";
 
 .dx-callout {
     border-radius: 4px;
@@ -48,4 +48,4 @@
 
 .dx-callout-base_column > dx-type-badge-group {
     margin-bottom: var(--dx-g-spacing-sm);
-}
+}

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

@@ -0,0 +1,100 @@
+:host {
+    --dx-c-content-vertical-spacing: var(--dx-g-spacing-lg);
+
+    display: block;
+}
+
+dx-sidebar,
+dx-sidebar-old {
+    --dx-c-sidebar-height: 100%;
+    --dx-c-sidebar-vertical-padding: var(--dx-c-content-vertical-spacing);
+
+    z-index: 5;
+}
+
+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;
+}
+
+dx-breadcrumbs {
+    display: block;
+    margin-bottom: var(--dx-g-spacing-2xl);
+}
+
+@media screen and (max-width: 1024px) {
+    .right-nav-bar {
+        display: none;
+    }
+}
+
+@media screen and (max-width: 800px) {
+    dx-breadcrumbs {
+        display: none;
+    }
+
+    .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,55 @@
+<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">
+                    <dx-breadcrumbs
+                        if:true={breadcrumbs}
+                        breadcrumbs={breadcrumbs}
+                        truncate
+                        hide-current-location
+                    ></dx-breadcrumbs>
+                    <dx-breadcrumbs
+                        if:false={breadcrumbs}
+                        pathname={pathname}
+                        hide-current-location
+                    ></dx-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>