@salesforcedevs/docs-components 0.54.0 → 0.54.1-a01

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,15 +1,16 @@
-@import "helpers/reset";
-@import "helpers/text";
+@import "dxHelpers/reset";
+@import "dxHelpers/text";
 
 :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,5 +1,6 @@
+import { track } from "dxUtils/analytics";
 import { LightningElement, api } from "lwc";
-import { BreadcrumbItemVariant } from "typings/custom";
+import { AnalyticsPayload, BreadcrumbItemVariant } from "typings/custom";
 
 const BREADCRUMB_LONG = "breadcrumb_long";
 const BREADCRUMB_BACK_ARROW = "breadcrumb_back-arrow";
@@ -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 analyticsEvent!: string;
+    @api analyticsBasePayload!: AnalyticsPayload;
 
     @api
     get label() {
@@ -46,4 +49,17 @@ export default class BreadcrumbItem extends LightningElement {
     private get isBackArrowVariant(): boolean {
         return this._variant === "back-arrow";
     }
+
+    private onLinkClick(event: Event): void {
+        if (!this.analyticsEvent) {
+            return;
+        }
+
+        track(event.target!, this.analyticsEvent, {
+            ...this.analyticsBasePayload,
+            clickText: this.label,
+            itemTitle: this.label,
+            pageLocation: window.location.pathname
+        });
+    }
 }

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

@@ -1,15 +1,16 @@
-@import "helpers/reset";
-@import "helpers/text";
+@import "dxHelpers/reset";
+@import "dxHelpers/text";
 
 :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

@@ -3,6 +3,8 @@
         <template if:false={renderSmallVariant}>
             <template if:true={renderFirstCrumb}>
                 <doc-breadcrumb-item
+                    analytics-event={analyticsEventName}
+                    analytics-base-payload={analyticsBasePayload}
                     href={firstCrumb.href}
                     label={firstCrumb.label}
                 ></doc-breadcrumb-item>
@@ -11,10 +13,14 @@
             <template if:true={renderDropdown}>
                 <dx-dropdown
                     if:true={renderDropdown}
+                    analytics-event={analyticsEventName}
+                    analytics-base-payload={analyticsBasePayload}
                     options={dropdownOptions}
                     open-on-hover
                     placement="bottom"
-                    width="200px"
+                    suppress-gtm-nav-headings
+                    variant="indented"
+                    width="fit-content"
                 >
                     <dx-button
                         aria-label="Open Breadcrumbs Dropdown"
@@ -27,8 +33,10 @@
             </template>
             <template for:each={breadcrumbItems} for:item="breadcrumb">
                 <doc-breadcrumb-item
+                    analytics-event={analyticsEventName}
+                    analytics-base-payload={analyticsBasePayload}
                     href={breadcrumb.href}
-                    key={breadcrumb.label}
+                    key={breadcrumb.id}
                     label={breadcrumb.label}
                 ></doc-breadcrumb-item>
                 <span class="breadcrumb-item_slash" key={breadcrumb.label}>
@@ -39,6 +47,8 @@
         </template>
         <template if:true={renderSmallVariant}>
             <doc-breadcrumb-item
+                analytics-event={analyticsEventName}
+                analytics-base-payload={analyticsBasePayload}
                 href={lastLinkCrump.href}
                 label={lastLinkCrump.label}
                 variant="back-arrow"

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;
@@ -8,13 +8,23 @@ type BreadcrumbConfig = {
 };
 
 const GAP = 8;
+
+// Unit in pixels based on Salesforce Sans font-family.
 const CONSTANTS = {
-    pixelPerCharacter: 7.2,
-    pixelPerCrumbSpace: GAP * 2 + 4.6,
-    minWidthPerCrumb: 245,
+    pixelPerCharacter: 7.7,
+    pixelPerCrumbSpace: GAP * 2 + 8.6,
+    minWidthPerCrumb: 200,
     dropdownWidth: 32
 };
 
+export const ANALYTICS_EVENT_NAME = "custEv_breadcrumbClick";
+export const ANALYTICS_BASE_PAYLOAD = {
+    elementType: "breadcrumb",
+    locationOnPage: "breadcrumb",
+    ctaClick: true,
+    pageLocation: window.location.pathname
+};
+
 export default class Breadcrumbs extends LightningElement {
     @api ariaLabel: string = "Documentation Breadcrumbs";
 
@@ -22,15 +32,26 @@ export default class Breadcrumbs extends LightningElement {
     get breadcrumbs(): Breadcrumb[] {
         return this._breadcrumbs;
     }
+
     set breadcrumbs(value) {
-        this._breadcrumbs = toJson(value) || [];
+        this.normalizeAndAssignBreadcrumbs(value);
         this.calculateBreadcrumbsConfigs();
         if (this.observer) {
             this.updateDropdownOptionAmount();
         }
     }
 
+    @api
+    get pixelPerCharacter(): number {
+        return this._pixelPerCharacter;
+    }
+
+    set pixelPerCharacter(value: number | string) {
+        this._pixelPerCharacter = +value;
+    }
+
     private _breadcrumbs: Breadcrumb[] = [];
+    private _pixelPerCharacter = CONSTANTS.pixelPerCharacter;
     private navWidth = 0;
     private observer: ResizeObserver | null = null;
     private breadcrumbConfigs: BreadcrumbConfig[] = [];
@@ -62,10 +83,10 @@ 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!,
+                id: link.id!,
                 label: link.label,
                 link: { href: link.href! }
             })
@@ -84,6 +105,14 @@ export default class Breadcrumbs extends LightningElement {
         return this.breadcrumbs[this.breadcrumbs.length - 1];
     }
 
+    private get analyticsEventName() {
+        return ANALYTICS_EVENT_NAME;
+    }
+
+    private get analyticsBasePayload() {
+        return ANALYTICS_BASE_PAYLOAD;
+    }
+
     renderedCallback(): void {
         if (!this.observer) {
             this.observer = new ResizeObserver((entries) => {
@@ -103,6 +132,17 @@ export default class Breadcrumbs extends LightningElement {
         this.observer?.disconnect();
     }
 
+    private normalizeAndAssignBreadcrumbs(breadcrumbs?: Breadcrumb[] | string) {
+        if (!breadcrumbs) {
+            return;
+        }
+
+        this._breadcrumbs = toJson(breadcrumbs).map((crumb: Breadcrumb) => ({
+            ...crumb,
+            id: crumb.id || crumb.href
+        }));
+    }
+
     private updateDropdownOptionAmount(): void {
         this.dropdownOptionAmount = this.breadcrumbConfigs.find(
             ({ minWidth }) => minWidth <= this.navWidth
@@ -135,7 +175,8 @@ export default class Breadcrumbs extends LightningElement {
             (previousValue, element) =>
                 previousValue +
                 Math.min(
-                    element.label.length * CONSTANTS.pixelPerCharacter,
+                    element.label.length *
+                        (this.pixelPerCharacter || CONSTANTS.pixelPerCharacter),
                     CONSTANTS.minWidthPerCrumb
                 ),
             (breadcrumbs.length - 1) * CONSTANTS.pixelPerCrumbSpace + offset

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%;
@@ -66,31 +66,47 @@ td > img.content-image:first-child:last-child[alt="No"] {
 
 h1 {
     font-family: var(--dx-g-font-display);
-    font-size: 40px;
+    font-size: var(--dx-g-text-4xl);
 
     /* not registered */
     color: var(--dx-g-blue-vibrant-20);
     letter-spacing: -0.4px;
-    line-height: 40px;
+    line-height: 56px;
 }
 
 h2 {
     font-family: var(--dx-g-font-display);
-    font-size: var(--dx-g-text-xl);
+    font-size: var(--dx-g-text-3xl);
     color: var(--dx-g-blue-vibrant-20);
     letter-spacing: -0.1px;
-    line-height: var(--dx-g-spacing-lg);
+    line-height: var(--dx-g-spacing-3xl);
 }
 
 h3 {
     font-family: var(--dx-g-font-display);
-    font-size: var(--dx-g-text-lg);
+    font-size: 32px;
     color: var(--dx-g-blue-vibrant-20);
     letter-spacing: -0.1px;
-    line-height: var(--dx-g-spacing-lg);
+    line-height: var(--dx-g-spacing-2xl);
 }
 
 h4 {
+    font-family: var(--dx-g-font-display);
+    font-size: var(--dx-g-text-xl);
+    color: var(--dx-g-blue-vibrant-20);
+    letter-spacing: 0;
+    line-height: var(--dx-g-spacing-xl);
+}
+
+h5 {
+    font-family: var(--dx-g-font-display);
+    font-size: var(--dx-g-text-lg);
+    color: var(--dx-g-blue-vibrant-20);
+    letter-spacing: 0;
+    line-height: 28px;
+}
+
+h6 {
     font-family: var(--dx-g-font-display);
     font-size: var(--dx-g-text-base);
     color: var(--dx-g-blue-vibrant-20);
@@ -116,6 +132,12 @@ p,
     margin-bottom: var(--dx-g-spacing-md);
 }
 
+dd > p,
+dd > .p {
+    margin-top: 0;
+    margin-bottom: 0;
+}
+
 .li {
     font-family: var(--dx-g-font-sans);
     font-size: var(--dx-g-text-base);
@@ -175,7 +197,8 @@ a,
     margin-right: var(--dx-g-spacing-lg);
 }
 
-.codeph {
+.codeph,
+.filepath {
     font-family: var(--dx-g-font-mono);
     font-size: var(--dx-g-text-sm);
     line-height: var(--dx-g-text-lg);
@@ -239,6 +262,7 @@ dd {
     letter-spacing: 0;
     line-height: var(--dx-g-spacing-lg);
     margin-left: var(--dx-g-spacing-smd);
+    margin-bottom: var(--dx-g-spacing-md);
 }
 
 li {

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",
@@ -150,11 +150,26 @@ export default class Content extends LightningElement {
                     is: ContentCallout
                 });
                 const detailEls = calloutEl.querySelectorAll(
-                    "p, div.data, ol, ul, .codeSection, .mediaBd > span.ph"
+                    "p, div.data, ol, ul, p+.codeSection, .mediaBd > span.ph"
                 );
                 detailEls.forEach((detailEl) => {
-                    calloutCompEl.appendChild(detailEl);
+                    if (detailEl.innerHTML.trim() !== "") {
+                        calloutCompEl.appendChild(detailEl);
+                    }
                 });
+
+                let flag = 1;
+                for (let i = 0; i < detailEls.length; i++) {
+                    flag &= detailEls[i].innerHTML.trim() === "";
+                }
+
+                if (flag) {
+                    const codeEls = calloutEl.querySelectorAll(".codeSection");
+                    codeEls.forEach((codeEl) => {
+                        calloutCompEl.appendChild(codeEl);
+                    });
+                }
+
                 const type = calloutEl.querySelector("h4").textContent;
                 const typeLower = type.toLowerCase();
                 Object.assign(calloutCompEl, {

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);
-}
+}