@salesforcedevs/docs-components 0.0.0 → 0.0.1-superscript

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

@@ -1,4 +1,4 @@
-import { Json } from "typings/custom";
+import { Json, DocPhaseInfo } from "typings/custom";
 
 export interface AmfTopicType {
     referenceId: string;
@@ -46,14 +46,6 @@ export interface AmfModelRecord {
     parsedModel: Json;
 }
 
-export type DocPhase = "pilot" | "dev-preview" | "beta";
-
-export type DocPhaseEntry = {
-    phase: DocPhase;
-    title: string;
-    body: string;
-};
-
 export type ReferenceType = "markdown" | "rest-raml" | "rest-oa2" | "rest-oa3";
 
 /**
@@ -73,7 +65,7 @@ export interface ParsedMarkdownTopic {
 export interface AmfConfig {
     id: string;
     version?: string;
-    docPhase?: DocPhaseEntry;
+    docPhase?: DocPhaseInfo;
     title: string;
     href: string;
     referenceType: ReferenceType;
@@ -103,7 +95,7 @@ export interface ParsedTopicModel {
 export interface TopicModel {
     id: string;
     type: string;
-    amf: AmfModel;
+    amf: string;
     parser: AmfParser;
 }
 

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,27 @@ import {
     createTypeElement
 } from "./utils";
 import type { TopicModel } from "./types";
+import { Json } from "typings/custom";
+import { buildDocLinkClickHandler } from "dxUtils/analytics";
+
+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;
+    private handleLinkClick = buildDocLinkClickHandler();
+
+    disconnectedCallback(): void {
+        // Remove link click handler
+        const container = this.template.querySelector(".topic-container");
+        if (container) {
+            container.removeEventListener("click", this.handleLinkClick);
+        }
+    }
 
     @api
-    get model(): TopicModel {
+    get model(): TopicModel | undefined {
         return this._model;
     }
 
@@ -24,13 +37,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 +58,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 +97,39 @@ 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);
+
+        // Add click handler for all links in the dynamically loaded content
+        if (container) {
+            if (this.isLinkTrackingHandledByAncestor()) {
+                container.removeEventListener("click", this.handleLinkClick);
+            } else {
+                container.addEventListener("click", this.handleLinkClick);
+            }
+        }
+
+        const isTabletOrDesktop = window.matchMedia(
+            `(min-width: ${TABLE_SIZE_MATCH})`
+        ).matches;
+
+        if (isTabletOrDesktop) {
+            window.scrollTo(0, 0);
+        }
+    }
+
+    renderedCallback(): void {
+        try {
+            this.update();
+        } catch (error) {
+            console.error(error);
+        }
     }
-}
 
-/**
- * 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));
+    private isLinkTrackingHandledByAncestor(): boolean {
+        const host = this.template.host as HTMLElement | undefined;
+        return !!host?.closest?.("doc-content-layout");
+    }
 }

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.ts

@@ -1,6 +1,6 @@
 import { track } from "dxUtils/analytics";
 import { LightningElement, api } from "lwc";
-import { AnalyticsPayload, BreadcrumbItemVariant } from "typings/custom";
+import { BreadcrumbItemVariant } from "typings/custom";
 
 const BREADCRUMB_LONG = "breadcrumb_long";
 const BREADCRUMB_BACK_ARROW = "breadcrumb_back-arrow";
@@ -8,8 +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 level?: string;
+    @api breadcrumbLabels?: string;
 
     @api
     get label() {
@@ -51,14 +51,21 @@ export default class BreadcrumbItem extends LightningElement {
     }
 
     private onLinkClick(event: Event): void {
-        if (!this.analyticsEvent) {
-            return;
-        }
+        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!, this.analyticsEvent, {
-            ...this.analyticsBasePayload,
-            clickText: this.label,
-            clickUrl: this.href
+        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.html

@@ -3,21 +3,18 @@
         <template if:true={displayCrumbs}>
             <template if:false={renderSmallVariant}>
                 <doc-breadcrumb-item
-                    analytics-event={analyticsEventName}
-                    analytics-base-payload={analyticsBasePayload}
                     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"
                         if:true={renderDropdown}
-                        analytics-event={analyticsEventName}
-                        analytics-base-payload={analyticsBasePayload}
                         options={dropdownOptions}
                         open-on-hover
                         placement="bottom"
-                        suppress-gtm-nav-headings
                         variant="indented"
                         width="fit-content"
                     >
@@ -32,11 +29,11 @@
                 </template>
                 <template for:each={breadcrumbItems} for:item="breadcrumb">
                     <doc-breadcrumb-item
-                        analytics-event={analyticsEventName}
-                        analytics-base-payload={analyticsBasePayload}
                         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}>
                         /
@@ -44,14 +41,14 @@
                 </template>
                 <doc-breadcrumb-item
                     label={lastCrumb.label}
+                    breadcrumb-labels={breadcrumbLabels}
                 ></doc-breadcrumb-item>
             </template>
             <template if:true={renderSmallVariant}>
                 <doc-breadcrumb-item
-                    analytics-event={analyticsEventName}
-                    analytics-base-payload={analyticsBasePayload}
                     href={lastLinkCrump.href}
                     label={lastLinkCrump.label}
+                    breadcrumb-labels={breadcrumbLabels}
                     variant="back-arrow"
                 ></doc-breadcrumb-item>
             </template>

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

@@ -17,13 +17,6 @@ const CONSTANTS = {
     dropdownWidth: 32
 };
 
-export const ANALYTICS_EVENT_NAME = "custEv_breadcrumbClick";
-export const ANALYTICS_BASE_PAYLOAD = {
-    elementType: "breadcrumb",
-    locationOnPage: "breadcrumb",
-    ctaClick: true
-};
-
 export default class Breadcrumbs extends LightningElement {
     @api ariaLabel: string = "Documentation Breadcrumbs";
 
@@ -35,8 +28,8 @@ export default class Breadcrumbs extends LightningElement {
     set breadcrumbs(value) {
         this.normalizeAndAssignBreadcrumbs(value);
         this.calculateBreadcrumbsConfigs();
-        if (this.observer) {
-            this.updateDropdownOptionAmount();
+        if (this.isRendered) {
+            this.onWidthOrContentChange();
         }
     }
 
@@ -52,9 +45,9 @@ export default class Breadcrumbs extends LightningElement {
     private _breadcrumbs: Breadcrumb[] = [];
     private _pixelPerCharacter = CONSTANTS.pixelPerCharacter;
     private navWidth = 0;
-    private observer: ResizeObserver | null = null;
     private breadcrumbConfigs: BreadcrumbConfig[] = [];
     private dropdownOptionAmount? = 0;
+    private isRendered = false;
 
     private get renderSmallVariant(): boolean {
         return (
@@ -100,38 +93,38 @@ export default class Breadcrumbs extends LightningElement {
         return this.breadcrumbs[0];
     }
 
-    private get lastCrumb(): Breadcrumb {
-        return this.breadcrumbs[this.breadcrumbs.length - 1];
+    private get breadcrumbLabels(): string {
+        return this.breadcrumbs.map((crumb) => crumb.label).join(":");
     }
 
-    private get analyticsEventName() {
-        return ANALYTICS_EVENT_NAME;
+    private get lastCrumb(): Breadcrumb {
+        return this.breadcrumbs[this.breadcrumbs.length - 1];
     }
 
-    private get analyticsBasePayload() {
+    // this payload is only used for breadcrumb dropdown
+    private get ANALYTICS_PAYLOAD() {
         return {
-            ...ANALYTICS_BASE_PAYLOAD,
-            itemTitle: this.breadcrumbs.map((crumb) => crumb.label).join("/")
+            element_type: "link",
+            nav_type: "breadcrumb",
+            nav_level: 1
         };
     }
 
+    private onWidthOrContentChange = () => {
+        this.navWidth = this.template
+            .querySelector("nav")!
+            .getBoundingClientRect().width;
+        this.updateDropdownOptionAmount();
+    };
+
     renderedCallback(): void {
-        if (!this.observer) {
-            this.observer = new ResizeObserver((entries) => {
-                const [nav] = entries;
-                if (this.navWidth === nav.contentRect.width) {
-                    return;
-                }
-                this.navWidth = nav.contentRect.width;
-                this.updateDropdownOptionAmount();
-            });
-
-            this.observer.observe(this.template.querySelector("nav")!);
-        }
+        this.isRendered = true;
+        this.onWidthOrContentChange();
+        window.addEventListener("resize", this.onWidthOrContentChange);
     }
 
     disconnectedCallback(): void {
-        this.observer?.disconnect();
+        window.removeEventListener("resize", this.onWidthOrContentChange);
     }
 
     private normalizeAndAssignBreadcrumbs(breadcrumbs?: Breadcrumb[] | string) {
@@ -139,10 +132,13 @@ export default class Breadcrumbs extends LightningElement {
             return;
         }
 
-        this._breadcrumbs = toJson(breadcrumbs).map((crumb: Breadcrumb) => ({
-            ...crumb,
-            id: crumb.id || crumb.href
-        }));
+        this._breadcrumbs = toJson(breadcrumbs).map(
+            (crumb: Breadcrumb, index: number) => ({
+                ...crumb,
+                id: crumb.id || crumb.href,
+                level: index
+            })
+        );
     }
 
     private updateDropdownOptionAmount(): void {

package/src/modules/doc/componentPlayground/componentPlayground.css

@@ -0,0 +1,30 @@
+@import "dxHelpers/reset";
+
+/**
+ * Designs link - https://www.figma.com/design/9SalRPlJmtRDZHq03o8dL1/One-Doc-Site-Visionary-Mocks?node-id=9968-366397&m=dev
+ * Preview padding: 24px
+ * Example Selector height: 122px
+ * Example Preview min height: 150px
+ * Tab height with border: 46px(45px height and 1px border)
+ * Codeblock height: 264px(224px for codeblock and 40px for panel)
+ * Total: 606px
+**/
+
+:host {
+    --playground-iframe-min-height: 500px;
+    --playground-iframe-max-height: 5000px;
+
+    margin-top: var(--dx-g-spacing-md) !important;
+    display: block !important;
+}
+
+iframe {
+    width: 100%;
+    height: 606px;
+    min-height: var(--playground-iframe-min-height);
+    max-height: var(--playground-iframe-max-height);
+}
+
+.playground-container {
+    position: relative;
+}

package/src/modules/doc/componentPlayground/componentPlayground.html

@@ -0,0 +1,20 @@
+<template>
+    <div class="playground-container" lwc:if={playgroundAvailable}>
+        <dx-spinner
+            size="large"
+            variant="brand"
+            if:true={isLoading}
+        ></dx-spinner>
+        <iframe
+            src={playgroundSrc}
+            onload={handleIframeLoad}
+            title={playgroundTitle}
+            allow="clipboard-write"
+        ></iframe>
+    </div>
+    <dx-error-fallback
+        lwc:else
+        title="Code Examples Unavailable"
+        description="This component's code examples are currently unavailable. Please check again later."
+    ></dx-error-fallback>
+</template>

package/src/modules/doc/componentPlayground/componentPlayground.ts

@@ -0,0 +1,97 @@
+import { LightningElement, api } from "lwc";
+
+const PLAYGROUND_HEIGHT_MESSAGE = "PLAYGROUND_HEIGHT_CHANGE";
+const LOADER_TIMEOUT_MS = 2000;
+
+export default class ComponentPlayground extends LightningElement {
+    @api model!: string;
+    @api namespace!: string;
+    @api component!: string;
+    @api playgroundAppUrl!: string;
+
+    isLoading = true;
+
+    /**
+     * Returns a formatted title for the component playground
+     * Maps 'aura' model to 'Aura' and 'lwc' model to 'Lightning'
+     * Capitalizes the first letter of the component name
+     * @returns {string} Formatted playground title
+     */
+    get playgroundTitle() {
+        const modelName = this.model === "aura" ? "Aura" : "Lightning";
+        const componentName =
+            this.component.charAt(0).toUpperCase() + this.component.slice(1);
+        return `Example previews and code for ${modelName} ${componentName} component`;
+    }
+
+    get playgroundAvailable() {
+        return (
+            this.playgroundAppUrl &&
+            this.model &&
+            this.namespace &&
+            this.component
+        );
+    }
+
+    get playgroundSrc(): string {
+        return `${this.playgroundAppUrl}/playground/${this.model}/${
+            this.namespace
+        }/${this.component.toLowerCase()}.html`;
+    }
+
+    connectedCallback() {
+        window.addEventListener("message", this.handleIframeMessage);
+    }
+
+    disconnectedCallback() {
+        window.removeEventListener("message", this.handleIframeMessage);
+    }
+
+    handleIframeLoad() {
+        if (!window.ResizeObserver) {
+            // If ResizeObserver not supported, hide loader immediately (no height messages will come)
+            this.isLoading = false;
+        } else {
+            // Hide loader after 2 seconds if no height messages received
+            // This handles cases where iframe fails to load, crashes, or height reporting fails
+            setTimeout(() => {
+                this.isLoading = false;
+            }, LOADER_TIMEOUT_MS);
+        }
+    }
+
+    handleIframeMessage = (event: MessageEvent) => {
+        // Only handle height change messages from our iframe
+        if (event.data?.type !== PLAYGROUND_HEIGHT_MESSAGE) {
+            return;
+        }
+
+        const iframe = this.template.querySelector(
+            "iframe"
+        ) as HTMLIFrameElement;
+        if (!iframe || event.source !== iframe.contentWindow) {
+            return;
+        }
+
+        const height = event.data?.height;
+        if (typeof height === "number" && height > 0) {
+            const minHeight = parseInt(
+                getComputedStyle(this.template.host).getPropertyValue(
+                    "--playground-iframe-min-height"
+                ),
+                10
+            );
+            const maxHeight = parseInt(
+                getComputedStyle(this.template.host).getPropertyValue(
+                    "--playground-iframe-max-height"
+                ),
+                10
+            );
+
+            const newHeight = Math.min(Math.max(height, minHeight), maxHeight);
+            iframe.style.height = `${newHeight}px`;
+            iframe.style.minHeight = `${newHeight}px`;
+            this.isLoading = false;
+        }
+    };
+}