@salesforcedevs/docs-components 0.56.2 → 0.56.3-example

package/src/modules/doc/amfReference/constants.ts

@@ -0,0 +1,76 @@
+const NAVIGATION_ITEMS = [
+    {
+        label: "Summary",
+        name: "summary",
+        childrenPropertyName: undefined,
+        type: "summary"
+    },
+    {
+        label: "Endpoints",
+        name: "endpoints",
+        childrenPropertyName: "endpoints",
+        type: "endpoint"
+    },
+    {
+        label: "Documentation",
+        name: "documentation",
+        childrenPropertyName: "docs",
+        type: "documentation"
+    },
+    {
+        label: "Types",
+        name: "types",
+        childrenPropertyName: "types",
+        type: "type"
+    },
+    {
+        label: "Security",
+        name: "security",
+        childrenPropertyName: "security",
+        type: "security"
+    }
+];
+
+const URL_CONFIG = {
+    summary: {
+        urlIdentifer: "label"
+    },
+    endpoint: {
+        urlIdentifer: "path"
+    },
+    method: {
+        urlIdentifer: "label"
+    },
+    documentation: {
+        urlIdentifer: "label"
+    },
+    type: {
+        urlIdentifer: "label",
+        prefix: "type:"
+    },
+    security: {
+        urlIdentifer: "label",
+        prefix: "security:"
+    }
+};
+
+export const REFERENCE_TYPES = {
+    markdown: "markdown",
+    raml: "rest-raml",
+    oa2: "rest-oa2",
+    oa3: "rest-oa3"
+};
+
+const oldReferenceIdNewReferenceIdMap: Record<string, string> = {
+    "commerce-api-assignments": "assignments",
+    "commerce-api-campaigns": "campaigns",
+    "commerce-api-catalogs": "catalogs",
+    "cdn-zones": "cdn-api-process-apis",
+    "inventory-impex": "impex",
+    "inventory-reservations": "inventory-reservation-service",
+    "shopper-login-and-api-access-service": "shopper-login",
+    "shopper-login-and-api-access-service-admin": "slas-admin",
+    "einstein-recommendations": "einstein-api-quick-start-guide"
+};
+
+export { NAVIGATION_ITEMS, URL_CONFIG, oldReferenceIdNewReferenceIdMap };

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

@@ -1,7 +1,8 @@
-import { Json } from "typings/custom";
+import { Json, DocPhaseInfo } from "typings/custom";
 
 export interface AmfTopicType {
     referenceId: string;
+    parentReferencePath: string;
     amfId: string;
     elementId: string;
     type: string;
@@ -10,6 +11,7 @@ export interface AmfTopicType {
 export interface AmfMetadataTopic extends AmfTopicType {
     meta: string;
     identifier: string;
+    navTitle?: string;
 }
 
 export interface AmfMetaTopicType extends AmfTopicType {
@@ -19,7 +21,6 @@ export interface AmfMetaTopicType extends AmfTopicType {
 export interface NavItem {
     name: string;
     label: string;
-    // TODO: Better type here
     children?: ({
         id: string;
         label?: string;
@@ -45,19 +46,38 @@ export interface AmfModelRecord {
     parsedModel: Json;
 }
 
-export type DocPhase = "pilot" | "dev-preview" | "beta";
+export type ReferenceType = "markdown" | "rest-raml" | "rest-oa2" | "rest-oa3";
 
-export type DocPhaseEntry = {
-    phase: DocPhase;
-    title: string;
-    body: string;
-};
+/**
+ * Represents parsed topic for the sidebar.
+ */
+export interface ParsedMarkdownTopic {
+    label: string;
+    name: string;
+    children: ParsedMarkdownTopic[];
+    link?: {
+        href: string;
+        target?: string;
+    };
+    isExpanded?: boolean;
+}
 
-export interface AmfConfig extends AmfModelRecord {
+export interface AmfConfig {
     id: string;
-    amf: string;
     version?: string;
-    docPhase?: DocPhaseEntry;
+    docPhase?: DocPhaseInfo;
+    title: string;
+    href: string;
+    referenceType: ReferenceType;
+
+    // determines if a reference config is the current active and selected one.
+    isSelected: boolean;
+
+    // required for spec based references
+    amf?: string;
+
+    // required for markdown based references
+    topic?: ParsedMarkdownTopic;
 }
 
 export interface ParsedTopicModel {
@@ -75,7 +95,7 @@ export interface ParsedTopicModel {
 export interface TopicModel {
     id: string;
     type: string;
-    amf: AmfModel;
+    amf: string;
     parser: AmfParser;
 }
 
@@ -84,10 +104,22 @@ export interface ReferenceVersion {
     label: string;
     deprecated?: boolean;
     selected?: boolean;
+    link: {
+        href: string;
+    };
 }
 
 export interface ReferenceSetConfig {
+    refId?: string;
     versionToRefMap?: Map<string, Array<AmfConfig>>;
     refList: Array<AmfConfig>;
-    versions?: Array<ReferenceVersion>;
+    versions: Array<ReferenceVersion>;
+}
+
+export interface RouteMeta {
+    meta: string;
+    referenceId: string;
+    topicId: string;
+    //type is only for spec based references
+    type?: string;
 }

package/src/modules/doc/amfTopic/amfTopic.css

@@ -1 +1,21 @@
 @import "docHelpers/amfStyle";
+
+:host {
+    --reference-container-margin-top: var(--dx-g-spacing-sm);
+    --api-documentation-margin-top: var(--dx-g-spacing-3xl);
+}
+
+/**
+ * 1. We need to scroll to top from the tablet size as side nav bar and content in side by side from tablet size
+ * 2. Consider global nav height, doc header height and content margins to scroll to the right position
+ */
+
+@media screen and (min-width: 769px) {
+    .topic-container {
+        scroll-margin-top: calc(
+            var(--dx-g-global-header-height) + var(--dx-g-doc-header-height) +
+                var(--reference-container-margin-top) +
+                var(--api-documentation-margin-top)
+        );
+    }
+}

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

@@ -8,14 +8,17 @@ import {
     createTypeElement
 } from "./utils";
 import type { TopicModel } from "./types";
+import { Json } from "typings/custom";
+
+const TABLE_SIZE_MATCH = "769px";
 
 export default class AmfTopic extends LightningElement {
-    private _model;
-    private amf;
-    private type;
+    private _model: TopicModel | undefined;
+    private amf: Json;
+    private type: string | undefined;
 
     @api
-    get model(): TopicModel {
+    get model(): TopicModel | undefined {
         return this._model;
     }
 
@@ -24,13 +27,17 @@ export default class AmfTopic extends LightningElement {
             !this.amf ||
             (value && this._model && value.amf !== this._model?.amf)
         ) {
-            this.amf = value && clone(value.amf);
+            try {
+                this.amf = value && JSON.parse(value.amf);
+            } catch (error) {
+                console.error(`Error parsing amf model: ${error}`);
+            }
         }
         if (
             !this.type ||
             (value && this._model && value.type !== this._model?.type)
         ) {
-            this.type = value && clone(value.type);
+            this.type = value && value.type;
         }
 
         this._model = value;
@@ -41,7 +48,11 @@ export default class AmfTopic extends LightningElement {
     }
 
     update(): void {
-        const container = this.template.querySelector("div.topic-container");
+        if (!this.model) {
+            throw new Error("Amf TopicModel undefined when trying to update");
+        }
+
+        const container = this.template.querySelector(".topic-container")!;
         const { id } = this.model;
         const type = this.type;
         const amf = this.amf;
@@ -76,19 +87,25 @@ export default class AmfTopic extends LightningElement {
             element = createDocumentationElement(amf, docsModel);
         }
 
-        if (container.firstChild) {
+        if (container?.firstChild) {
             container.firstChild.remove();
         }
-        container.appendChild(element);
+        container?.appendChild(element as Node);
+
+        const isTabletOrDesktop = window.matchMedia(
+            `(min-width: ${TABLE_SIZE_MATCH})`
+        ).matches;
+
+        if (isTabletOrDesktop) {
+            window.scrollTo(0, 0);
+        }
     }
-}
 
-/**
- * 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));
+    renderedCallback(): void {
+        try {
+            this.update();
+        } catch (error) {
+            console.error(error);
+        }
+    }
 }

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

@@ -1,4 +1,11 @@
 import { Json } from "typings/custom";
+import { AmfModelParser } from "doc/amfModelParser";
+import {
+    DomainElement,
+    EndPoint,
+    Operation,
+    Shape
+} from "@api-components/amf-helper-mixin";
 
 export type ApiSummaryElement = HTMLElement & {
     amf: Json;
@@ -11,44 +18,39 @@ export type ApiEndpointElement = HTMLElement & {
     inlineMethods: boolean;
     noNavigation: boolean;
     selected: string;
-    endpoint: Json;
+    endpoint: EndPoint;
     noTryIt: boolean;
 };
 
 export type ApiMethodElement = HTMLElement & {
     amf: Json;
     noNavigation: boolean;
-    endpoint: Json;
-    method: Json;
+    endpoint: EndPoint | undefined;
+    method: Operation | undefined;
     noTryIt: boolean;
 };
 
 export type ApiSecurityElement = HTMLElement & {
     amf: Json;
-    security: Json;
+    security: DomainElement | undefined;
 };
 
 export type ApiTypeElement = HTMLElement & {
     amf: Json;
-    type: Json;
+    type?: Shape;
     mediaTypes: Json;
 };
 
 export type ApiDocElement = HTMLElement & {
     amf: Json;
-    shape: Json;
+    shape: DomainElement | undefined;
 };
 
 export type AmfModel = Json;
 
-export interface AmfParser {
-    parse(): void;
-    parsedModel: any;
-}
-
 export interface TopicModel {
     id: string;
     type: string;
-    amf: AmfModel;
-    parser: AmfParser;
+    amf: string;
+    parser: AmfModelParser;
 }

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

@@ -1,3 +1,9 @@
+import {
+    DomainElement,
+    EndPoint,
+    Operation,
+    Shape
+} from "@api-components/amf-helper-mixin";
 import type {
     ApiDocElement,
     ApiEndpointElement,
@@ -37,7 +43,7 @@ export function createSummaryElement(amf: Json): HTMLElement {
  */
 export function createEndpointElement(
     amf: Json,
-    endpointModel: Json,
+    endpointModel: EndPoint,
     selected: string
 ): HTMLElement {
     const el: ApiEndpointElement = document.createElement(
@@ -57,8 +63,8 @@ export function createEndpointElement(
  */
 export function createMethodElement(
     amf: Json,
-    endpointMethodModel: Json,
-    methodModel: Json
+    endpointMethodModel: EndPoint | undefined,
+    methodModel: Operation | undefined
 ): HTMLElement {
     const el: ApiMethodElement = document.createElement(
         "api-method-documentation"
@@ -79,7 +85,7 @@ export function createMethodElement(
  */
 export function createSecurityElement(
     amf: Json,
-    securityModel: Json
+    securityModel: DomainElement | undefined
 ): HTMLElement {
     const el: ApiSecurityElement = document.createElement(
         "api-security-documentation"
@@ -98,7 +104,7 @@ export function createSecurityElement(
  */
 export function createTypeElement(
     amf: Json,
-    typeModel: Json,
+    typeModel: Shape | undefined,
     mediaTypes: Json
 ): HTMLElement {
     const el: ApiTypeElement = document.createElement(
@@ -119,7 +125,7 @@ export function createTypeElement(
  */
 export function createDocumentationElement(
     amf: Json,
-    docsModel: Json
+    docsModel: DomainElement | undefined
 ): HTMLElement {
     const el: ApiDocElement = document.createElement(
         "api-documentation-document"

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

@@ -4,12 +4,13 @@
 :host {
     display: flex;
     align-items: center;
+    justify-content: center;
     width: fit-content;
 }
 
 :host(.breadcrumb_long) {
     /* ensure 30 character min-width */
-    min-width: 245px;
+    min-width: 200px;
 }
 
 :host(.breadcrumb_back-arrow) {

package/src/modules/doc/breadcrumbItem/breadcrumbItem.html

@@ -1,5 +1,5 @@
 <template>
     <dx-icon if:true={isBackArrowVariant} symbol="back"></dx-icon>
-    <a if:true={href} href={href}>{label}</a>
+    <a if:true={href} href={href} onclick={onLinkClick}>{label}</a>
     <span if:false={href}>{label}</span>
 </template>

package/src/modules/doc/breadcrumbItem/breadcrumbItem.ts

@@ -1,3 +1,4 @@
+import { track } from "dxUtils/analytics";
 import { LightningElement, api } from "lwc";
 import { BreadcrumbItemVariant } from "typings/custom";
 
@@ -7,6 +8,8 @@ const BREADCRUMB_BACK_ARROW = "breadcrumb_back-arrow";
 const LONG_LABEL_NUMBER = 30;
 export default class BreadcrumbItem extends LightningElement {
     @api href?: string;
+    @api level?: string;
+    @api breadcrumbLabels?: string;
 
     @api
     get label() {
@@ -46,4 +49,23 @@ export default class BreadcrumbItem extends LightningElement {
     private get isBackArrowVariant(): boolean {
         return this._variant === "back-arrow";
     }
+
+    private onLinkClick(event: Event): void {
+        track(event.target!, "custEv_breadcrumbClick", {
+            click_text: this.label,
+            click_url: `${window.location.origin}${this.href}`,
+            element_type: "link",
+            nav_type: "breadcrumb",
+            nav_level: this.level ? this.level + 1 : 1,
+            nav_item: this.breadcrumbLabels
+        });
+
+        track(event.target!, "custEv_linkClick", {
+            click_text: this.label,
+            click_url: `${window.location.origin}${this.href}`,
+            element_title: this.label,
+            element_type: "link",
+            content_category: "cta"
+        });
+    }
 }

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

@@ -4,12 +4,13 @@
 :host {
     --dx-c-breadcrumbs-title-color: var(--dx-g-blue-vibrant-20);
     --dx-c-breadcrumbs-breadcrumb-color: var(--dx-g-blue-vibrant-20);
+
+    font-family: var(--dx-g-font-sans);
 }
 
 nav {
     display: flex;
     align-items: center;
-    height: 100%;
     position: relative;
     gap: var(--dx-g-spacing-sm);
 }
@@ -17,3 +18,10 @@ nav {
 .breadcrumb-item_slash {
     min-width: fit-content;
 }
+
+dx-dropdown {
+    --dx-c-dropdown-option-font-size: var(--dx-g-text-sm);
+    --dx-c-dropdown-option-label-color: var(
+        --dx-c-breadcrumbs-breadcrumb-color
+    );
+}

package/src/modules/doc/breadcrumbs/breadcrumbs.html

@@ -1,48 +1,58 @@
 <template>
     <nav role="navigation" aria-label={ariaLabel}>
-        <template if:false={renderSmallVariant}>
-            <template if:true={renderFirstCrumb}>
+        <template if:true={displayCrumbs}>
+            <template if:false={renderSmallVariant}>
                 <doc-breadcrumb-item
                     href={firstCrumb.href}
                     label={firstCrumb.label}
+                    breadcrumb-labels={breadcrumbLabels}
                 ></doc-breadcrumb-item>
                 <span class="breadcrumb-item_slash">/</span>
+                <template if:true={renderDropdown}>
+                    <dx-dropdown
+                        analytics-event="custEv_breadcrumbClick"
+                        analytics-payload={ANALYTICS_PAYLOAD}
+                        if:true={renderDropdown}
+                        options={dropdownOptions}
+                        open-on-hover
+                        placement="bottom"
+                        variant="indented"
+                        width="fit-content"
+                    >
+                        <dx-button
+                            aria-label="Open Breadcrumbs Dropdown"
+                            icon-size="large"
+                            icon-symbol="threedots"
+                            variant="tertiary"
+                        ></dx-button>
+                    </dx-dropdown>
+                    <span class="breadcrumb-item_slash">/</span>
+                </template>
+                <template for:each={breadcrumbItems} for:item="breadcrumb">
+                    <doc-breadcrumb-item
+                        href={breadcrumb.href}
+                        key={breadcrumb.id}
+                        label={breadcrumb.label}
+                        level={breadcrumb.level}
+                        breadcrumb-labels={breadcrumbLabels}
+                    ></doc-breadcrumb-item>
+                    <span class="breadcrumb-item_slash" key={breadcrumb.label}>
+                        /
+                    </span>
+                </template>
+                <doc-breadcrumb-item
+                    label={lastCrumb.label}
+                    breadcrumb-labels={breadcrumbLabels}
+                ></doc-breadcrumb-item>
             </template>
-            <template if:true={renderDropdown}>
-                <dx-dropdown
-                    if:true={renderDropdown}
-                    options={dropdownOptions}
-                    open-on-hover
-                    placement="bottom"
-                    width="200px"
-                >
-                    <dx-button
-                        aria-label="Open Breadcrumbs Dropdown"
-                        icon-size="large"
-                        icon-symbol="threedots"
-                        variant="tertiary"
-                    ></dx-button>
-                </dx-dropdown>
-                <span class="breadcrumb-item_slash">/</span>
-            </template>
-            <template for:each={breadcrumbItems} for:item="breadcrumb">
+            <template if:true={renderSmallVariant}>
                 <doc-breadcrumb-item
-                    href={breadcrumb.href}
-                    key={breadcrumb.label}
-                    label={breadcrumb.label}
+                    href={lastLinkCrump.href}
+                    label={lastLinkCrump.label}
+                    breadcrumb-labels={breadcrumbLabels}
+                    variant="back-arrow"
                 ></doc-breadcrumb-item>
-                <span class="breadcrumb-item_slash" key={breadcrumb.label}>
-                    /
-                </span>
             </template>
-            <doc-breadcrumb-item label={lastCrumb.label}></doc-breadcrumb-item>
-        </template>
-        <template if:true={renderSmallVariant}>
-            <doc-breadcrumb-item
-                href={lastLinkCrump.href}
-                label={lastLinkCrump.label}
-                variant="back-arrow"
-            ></doc-breadcrumb-item>
         </template>
     </nav>
 </template>