@salesforcedevs/docs-components 1.20.17-cb-plain-loading-1 → 1.20.18-redocly1

package/lwc.config.json

@@ -20,6 +20,7 @@
         "doc/headingAnchor",
         "doc/overview",
         "doc/phase",
+        "doc/redocReference",
         "doc/specificationContent",
         "doc/versionPicker",
         "doc/xmlContent",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@salesforcedevs/docs-components",
-    "version": "1.20.17-cb-plain-loading-1",
+    "version": "1.20.18-redocly1",
     "description": "Docs Lightning web components for DSC",
     "license": "MIT",
     "main": "index.js",

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

@@ -23,6 +23,13 @@ iframe {
     height: 606px;
     min-height: var(--playground-iframe-min-height);
     max-height: var(--playground-iframe-max-height);
+    transition: height 0.3s ease, min-height 0.3s ease;
+}
+
+@media (prefers-reduced-motion: reduce) {
+    iframe {
+        transition: none;
+    }
 }
 
 .playground-container {

package/src/modules/doc/header/header.html

@@ -8,7 +8,11 @@
                 ></dx-banner>
                 <!-- To-Do: Move the devCenter as a new component and use it here, as devCenter is also used in Sidebar now -->
                 <div lwc:if={devCenter} class="dev-center-link">
-                    <a href={devCenter.link} class="dev-center-content">
+                    <a
+                        href={devCenter.link}
+                        onclick={onLinkClick}
+                        class="dev-center-content"
+                    >
                         <dx-icon symbol="back"></dx-icon>
                         <dx-icon
                             class="brand-icon"

package/src/modules/doc/header/header.ts

@@ -3,6 +3,7 @@ import cx from "classnames";
 import type { OptionWithNested, DevCenterConfig } from "typings/custom";
 import { HeaderBase } from "dxBaseElements/headerBase";
 import { toJson, normalizeBoolean } from "dxUtils/normalizers";
+import { track } from "dxUtils/analytics";
 
 const TABLET_MATCH = "980px";
 const MOBILE_MATCH = "768px";
@@ -117,4 +118,13 @@ export default class Header extends HeaderBase {
             this.showScopedNavItems && "has-scoped-nav-items"
         );
     }
+
+    private onLinkClick(event: Event): void {
+        track(event.target!, "custEv_linkClick", {
+            click_text: this.devCenter.title,
+            click_url: this.devCenter.link,
+            element_type: "link",
+            content_category: "dev-center"
+        });
+    }
 }

package/src/modules/doc/redocReference/redocReference.css

@@ -0,0 +1,7 @@
+:host {
+    --dx-footer-margin-top: 142px;
+    --doc-c-redoc-sidebar-top: calc(
+        var(--dx-g-global-header-height) + var(--dx-g-doc-header-height) +
+            var(--dx-g-spacing-xl)
+    );
+}

package/src/modules/doc/redocReference/redocReference.html

@@ -0,0 +1,13 @@
+<template>
+    <template lwc:if={showError}>
+        <dx-error
+            header="We lost communication with the space station."
+            subtitle="We encountered a server-related issue. (Don't worry, we're on it.) Refresh your browser or try again later."
+            image=""
+            code="500"
+        ></dx-error>
+    </template>
+    <template lwc:else>
+        <slot></slot>
+    </template>
+</template>

package/src/modules/doc/redocReference/redocReference.ts

@@ -0,0 +1,326 @@
+/* eslint-disable @lwc/lwc/no-document-query */
+import { createElement, LightningElement, api } from "lwc";
+import DocPhase from "doc/phase";
+import DxFooter from "dx/footer";
+import SprigSurvey from "doc/sprigSurvey";
+import { throttle } from "throttle-debounce";
+
+declare global {
+    interface Window {
+        Redoc: any;
+    }
+}
+
+type ReferenceItem = {
+    source: string;
+    href: string;
+    isSelected?: boolean;
+    docPhase?: string | null;
+};
+
+type ReferenceConfig = {
+    refList: ReferenceItem[];
+};
+
+declare const Sprig: (eventType: string, eventName: string) => void;
+const SCROLL_THROTTLE_DELAY = 200;
+const ELEMENT_TIMEOUT = 10000;
+const ELEMENT_CHECK_INTERVAL = 100;
+
+export default class RedocReference extends LightningElement {
+    private _referenceConfig: ReferenceConfig = { refList: [] };
+    private _parentDocPhaseInfo: string | null = null;
+    private redocInitialized = false;
+
+    showError = false;
+
+    @api
+    get referenceConfig(): ReferenceConfig {
+        return this._referenceConfig;
+    }
+
+    set referenceConfig(value: string | ReferenceConfig) {
+        try {
+            const refConfig =
+                typeof value === "string" ? JSON.parse(value) : value;
+            this._referenceConfig = refConfig;
+        } catch (error) {
+            this.showError = true;
+            console.error(
+                "Failed to parse reference configuration data",
+                error
+            );
+            this._referenceConfig = { refList: [] };
+        }
+    }
+
+    @api
+    get docPhaseInfo(): string | null {
+        return this._parentDocPhaseInfo;
+    }
+
+    set docPhaseInfo(value: string) {
+        this._parentDocPhaseInfo = value;
+    }
+
+    connectedCallback(): void {
+        window.addEventListener("scroll", this.handleScrollAndResize);
+        window.addEventListener("resize", this.handleScrollAndResize);
+    }
+
+    renderedCallback(): void {
+        if (!this.redocInitialized) {
+            this.initializeRedoc();
+        }
+    }
+
+    disconnectedCallback(): void {
+        window.removeEventListener("scroll", this.handleScrollAndResize);
+        window.removeEventListener("resize", this.handleScrollAndResize);
+    }
+
+    @api
+    setDocPhaseInfo(docPhaseInfo: string): void {
+        this._parentDocPhaseInfo = docPhaseInfo;
+    }
+
+    private handleLayoutChange = () => {
+        requestAnimationFrame(() => {
+            const redocContainer = this.getRedocContainer();
+            if (!redocContainer) {
+                return;
+            }
+
+            const globalNavElement = document.querySelector("hgf-c360nav");
+            const contextNavElement =
+                document.querySelector("hgf-c360contextnav");
+            const docHeaderElement =
+                document.querySelector(".sticky-doc-header");
+
+            const globalNavHeight =
+                globalNavElement?.getBoundingClientRect().height || 0;
+            const contextNavHeight =
+                contextNavElement?.getBoundingClientRect().height || 0;
+            const docHeaderHeight =
+                docHeaderElement?.getBoundingClientRect().height || 0;
+
+            const calculatedTopValue = `${
+                globalNavHeight + contextNavHeight + docHeaderHeight
+            }px`;
+
+            // Set updated top value for the sidebar and doc phase
+            this.template.host.style.setProperty(
+                "--doc-c-redoc-sidebar-top",
+                calculatedTopValue
+            );
+
+            // Update thirdColumnContainer bottom positioning
+            const footer = redocContainer.querySelector(
+                ".redoc-wrap .api-content dx-footer"
+            ) as HTMLElement;
+            const thirdColumnContainer = redocContainer.querySelector(
+                ".redoc-wrap > div:last-child"
+            ) as HTMLElement;
+
+            if (thirdColumnContainer && footer) {
+                const footerHeight = footer.getBoundingClientRect().height || 0;
+                const footerMarginTop = parseInt(
+                    getComputedStyle(this.template.host).getPropertyValue(
+                        "--dx-footer-margin-top"
+                    ) || "142",
+                    10
+                );
+                thirdColumnContainer.style.setProperty(
+                    "bottom",
+                    `${footerHeight + footerMarginTop}px`
+                );
+            }
+        });
+    };
+
+    private handleScrollAndResize = throttle(
+        SCROLL_THROTTLE_DELAY,
+        () => !this.showError && this.handleLayoutChange()
+    );
+
+    private getDocPhaseInfo(): string | null {
+        if (this._parentDocPhaseInfo) {
+            return this._parentDocPhaseInfo;
+        }
+        const selectedRef = this.getSelectedReference();
+        return selectedRef?.docPhase
+            ? JSON.stringify(selectedRef.docPhase)
+            : null;
+    }
+
+    private getSelectedReference(): ReferenceItem | null {
+        return this._referenceConfig?.refList?.length
+            ? this._referenceConfig.refList.find((ref) => ref.isSelected) ||
+                  this._referenceConfig.refList[0]
+            : null;
+    }
+
+    private getRedocContainer(): HTMLElement | null {
+        return document.querySelector(".redoc-container");
+    }
+
+    private updateUrlWithReference(selectedRef: ReferenceItem): void {
+        if (selectedRef?.href) {
+            const parentReferencePath = selectedRef.href;
+            const currentUrl = window.location;
+            const existingParams = currentUrl.search + currentUrl.hash;
+
+            window.history.pushState(
+                {},
+                "",
+                `${parentReferencePath}${existingParams}`
+            );
+        }
+    }
+
+    private async initializeRedoc(): Promise<void> {
+        try {
+            this.redocInitialized = true;
+
+            await this.waitForRedoc();
+            const selectedRef = this.getSelectedReference();
+            if (selectedRef) {
+                this.updateUrlWithReference(selectedRef);
+
+                const specUrl = selectedRef.source;
+                const redocContainer = this.getRedocContainer();
+                if (specUrl && redocContainer) {
+                    try {
+                        window.Redoc.init(
+                            specUrl,
+                            {
+                                expandResponses: "200,400"
+                            },
+                            redocContainer,
+                            () => {
+                                this.insertCustomLayoutElements();
+                            }
+                        );
+                    } catch (error) {
+                        this.showError = true;
+                        console.error(
+                            "Failed to show Reference UI using Redoc:",
+                            error
+                        );
+                    }
+                } else {
+                    this.showError = true;
+                }
+            }
+        } catch (error) {
+            this.showError = true;
+            console.error("Failed to load Redoc library:", error);
+        }
+    }
+
+    /**
+     * Waits until a condition is ready/satisfied within a timeout period
+     * @param readinessCheck - Function that returns truthy when condition is satisfied
+     * @param timeoutErrorMessage - Error message if timeout occurs
+     * @param maxWaitTime - Maximum time to wait in milliseconds
+     */
+    private waitUntilReady(
+        readinessCheck: () => boolean | HTMLElement | null,
+        timeoutErrorMessage: string,
+        maxWaitTime = ELEMENT_TIMEOUT
+    ): Promise<void> {
+        return new Promise((resolve, reject) => {
+            const pollingStartTime = Date.now();
+
+            const performReadinessCheck = () => {
+                if (readinessCheck()) {
+                    resolve();
+                    return;
+                }
+
+                const elapsedTime = Date.now() - pollingStartTime;
+                if (elapsedTime > maxWaitTime) {
+                    reject(new Error(timeoutErrorMessage));
+                    return;
+                }
+
+                setTimeout(performReadinessCheck, ELEMENT_CHECK_INTERVAL);
+            };
+
+            performReadinessCheck();
+        });
+    }
+
+    private waitForRedoc(timeout = ELEMENT_TIMEOUT): Promise<void> {
+        return this.waitUntilReady(
+            () => !!window.Redoc,
+            "Redoc library failed to load within timeout period",
+            timeout
+        );
+    }
+
+    private async insertCustomLayoutElements(): Promise<void> {
+        try {
+            const redocContainer = this.getRedocContainer();
+
+            if (redocContainer) {
+                const apiContentDiv = await this.waitForApiContent(
+                    redocContainer
+                );
+                apiContentDiv.setAttribute("lwc:dom", "manual");
+
+                const docPhaseInfo = this.getDocPhaseInfo();
+                if (docPhaseInfo) {
+                    this.insertDocPhase(apiContentDiv, docPhaseInfo);
+                }
+
+                if (typeof Sprig !== "undefined") {
+                    this.insertSprigSurvey(apiContentDiv);
+                }
+
+                this.insertFooter(apiContentDiv);
+            }
+        } catch (error) {
+            this.showError = true;
+            console.error("Failed to insert layout elements:", error);
+        }
+    }
+
+    private async waitForApiContent(
+        container: HTMLElement
+    ): Promise<HTMLElement> {
+        await this.waitUntilReady(
+            () => container.querySelector<HTMLElement>(".api-content"),
+            "Redoc API content element not found within timeout period"
+        );
+        return container.querySelector<HTMLElement>(".api-content")!;
+    }
+
+    private insertDocPhase(container: HTMLElement, docPhaseInfo: string): void {
+        const docPhaseElement = createElement("doc-phase", { is: DocPhase });
+        Object.assign(docPhaseElement, { docPhaseInfo });
+
+        const wrapper = document.createElement("div");
+        wrapper.className = "doc-phase-wrapper";
+        wrapper.appendChild(docPhaseElement);
+
+        container.insertBefore(wrapper, container.firstChild);
+    }
+
+    private insertFooter(container: HTMLElement): void {
+        const footerElement = createElement("dx-footer", { is: DxFooter });
+        Object.assign(footerElement, { variant: "no-signup" });
+        container.appendChild(footerElement);
+    }
+
+    private insertSprigSurvey(container: HTMLElement): void {
+        const feedbackElement = createElement("doc-sprig-survey", {
+            is: SprigSurvey
+        });
+
+        const wrapper = document.createElement("div");
+        wrapper.className = "sprig-survey-wrapper";
+        wrapper.appendChild(feedbackElement);
+        container.appendChild(wrapper);
+    }
+}