@salesforcedevs/docs-components 1.20.13-redocly1 → 1.20.13-redocly3

package/package.json

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

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

@@ -1,8 +1,21 @@
 <template>
-    <slot></slot>
-    <dx-error-fallback
-        if:true={showError}
-        title={title}
-        description={description}
-    ></dx-error-fallback>
+    <template lwc:if={showServerError}>
+        <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:elseif={showError}>
+        <dx-error
+            header="Head back to the space station"
+            subtitle="Looks like this page vaporized"
+            code="404"
+            image="https://a.sfdcstatic.com/developer-website/images/404.svg"
+        ></dx-error>
+    </template>
+    <template lwc:else>
+        <slot></slot>
+    </template>
 </template>

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

@@ -3,6 +3,7 @@ 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 {
@@ -22,20 +23,20 @@ type ReferenceConfig = {
 };
 
 declare const Sprig: (eventType: string, eventNme: string) => void;
+const FOOTER_MARGIN_TOP = 142;
+const DEFAULT_TIMEOUT = 200;
+const REDOC_TIMEOUT = 10000;
+const REDOC_CHECK_TIMEOUT = 100;
 
 export default class RedocReference extends LightningElement {
     private _referenceConfig: ReferenceConfig = { refList: [] };
     private _parentDocPhaseInfo: string | null = null;
 
     private layoutTimeoutId: number | null = null;
-    private isScrolling: boolean = false;
-    private previousTopValue = "";
     private redocInitialized = false;
 
     showError = false;
-    title: string = "API Documentation Unavailable";
-    description: string =
-        "This API reference is currently unavailable. Please try again later.";
+    showServerError = false;
 
     @api
     get referenceConfig(): ReferenceConfig {
@@ -48,9 +49,7 @@ export default class RedocReference extends LightningElement {
                 typeof value === "string" ? JSON.parse(value) : value;
             this._referenceConfig = refConfig;
         } catch (error) {
-            this.title = "Failed to parse reference configuration data";
-            this.description =
-                "An error occurred while reading/parsing the reference configuration. Please check the config file for syntax errors or invalid references and try again.";
+            this.showServerError = true;
             console.error(
                 "Failed to parse reference configuration data",
                 error
@@ -69,12 +68,12 @@ export default class RedocReference extends LightningElement {
     }
 
     connectedCallback(): void {
-        window.addEventListener("scroll", this.handleScrollWithThrottle);
-        window.addEventListener("resize", this.handleScrollWithThrottle);
+        window.addEventListener("scroll", this.handleScroll);
+        window.addEventListener("resize", this.handleScroll);
     }
 
     renderedCallback(): void {
-        if (!this.redocInitialized && window.Redoc) {
+        if (!this.redocInitialized) {
             this.initializeRedoc();
         }
     }
@@ -85,8 +84,8 @@ export default class RedocReference extends LightningElement {
             this.layoutTimeoutId = null;
         }
 
-        window.removeEventListener("scroll", this.handleScrollWithThrottle);
-        window.removeEventListener("resize", this.handleScrollWithThrottle);
+        window.removeEventListener("scroll", this.handleScroll);
+        window.removeEventListener("resize", this.handleScroll);
     }
 
     @api
@@ -94,23 +93,17 @@ export default class RedocReference extends LightningElement {
         this._parentDocPhaseInfo = docPhaseInfo;
     }
 
-    private handleScrollWithThrottle = () => {
-        if (!this.isScrolling) {
-            this.isScrolling = true;
-
-            setTimeout(() => {
-                this.adjustPosition();
-            }, 200);
-
-            this.isScrolling = false;
-        }
-    };
-
     private adjustPosition = () => {
         const redocContainer = this.getRedocContainer();
         const sidebarMenuElement = redocContainer?.querySelector(
             ".redoc-wrap .menu-content"
         ) as HTMLElement;
+        const footer = redocContainer?.querySelector(
+            ".redoc-wrap .api-content dx-footer"
+        ) as HTMLElement;
+        const rightSidebar = redocContainer?.querySelector(
+            ".redoc-wrap > div:last-child"
+        ) as HTMLElement;
 
         requestAnimationFrame(() => {
             const globalNavElement = document.querySelector("hgf-c360nav");
@@ -119,6 +112,16 @@ export default class RedocReference extends LightningElement {
             const docHeaderElement =
                 document.querySelector(".sticky-doc-header");
 
+            if (rightSidebar) {
+                rightSidebar.style.setProperty(
+                    "bottom",
+                    `${
+                        (footer.getBoundingClientRect().height || 0) +
+                        FOOTER_MARGIN_TOP
+                    }px`
+                );
+            }
+
             if (sidebarMenuElement) {
                 const globalNavHeight =
                     globalNavElement?.getBoundingClientRect().height || 0;
@@ -131,17 +134,19 @@ export default class RedocReference extends LightningElement {
                     globalNavHeight + contextNavHeight + docHeaderHeight
                 }px`;
 
-                if (calculatedTopValue !== this.previousTopValue) {
-                    sidebarMenuElement.style.setProperty(
-                        "--doc-c-redoc-sidebar-top",
-                        calculatedTopValue
-                    );
-                    this.previousTopValue = calculatedTopValue;
-                }
+                sidebarMenuElement.style.setProperty(
+                    "--doc-c-redoc-sidebar-top",
+                    calculatedTopValue
+                );
             }
         });
     };
 
+    private handleScroll = throttle(
+        DEFAULT_TIMEOUT,
+        () => !this.showServerError && !this.showError && this.adjustPosition()
+    );
+
     private getDocPhaseInfo(): string | null {
         if (this._parentDocPhaseInfo) {
             return this._parentDocPhaseInfo;
@@ -177,8 +182,11 @@ export default class RedocReference extends LightningElement {
         }
     }
 
-    private initializeRedoc(): void {
+    private async initializeRedoc(): Promise<void> {
         try {
+            this.redocInitialized = true;
+
+            await this.waitForRedoc();
             const selectedRef = this.getSelectedReference();
             if (selectedRef) {
                 this.updateUrlWithReference(selectedRef);
@@ -186,68 +194,107 @@ export default class RedocReference extends LightningElement {
                 const specUrl = selectedRef.source;
                 const redocContainer = this.getRedocContainer();
                 if (specUrl && redocContainer) {
-                    this.redocInitialized = true;
-                    window.Redoc.init(
-                        specUrl,
-                        {
-                            expandResponses: "200,400"
-                        },
-                        redocContainer,
-                        () => {
-                            this.insertCustomLayoutElements();
-                        }
-                    );
+                    try {
+                        window.Redoc.init(
+                            specUrl,
+                            {
+                                expandResponses: "200,400"
+                            },
+                            redocContainer,
+                            () => {
+                                this.insertCustomLayoutElements();
+                            }
+                        );
+                    } catch (error) {
+                        this.showServerError = true;
+                        console.error("Failed to load Redoc:", error);
+                    }
                 } else {
                     this.showError = true;
-                    console.error(
-                        "Failed to initialize Redoc, required params missing."
-                    );
                 }
             }
         } catch (error) {
-            this.title = "Failed to load API specification";
-            this.description =
-                "An error occurred while trying to initialize Redoc. This may be due to a missing or invalid source in the configuration file, or a network connectivity issue. Please verify the source path and your internet connection and try again.";
-            console.error("Failed to load API specification", error);
-            this.showError = true;
+            this.showServerError = true;
+            console.error("Failed to initialize Redoc:", error);
         }
     }
 
-    private insertCustomLayoutElements(): void {
-        const redocContainer = this.getRedocContainer();
-        const apiContentDiv = redocContainer?.querySelector(".api-content");
-        if (apiContentDiv) {
-            (apiContentDiv as HTMLElement).setAttribute("lwc:dom", "manual");
+    private waitForRedoc(timeout = REDOC_TIMEOUT): Promise<void> {
+        return new Promise((resolve, reject) => {
+            let resolved = false;
+            const startTime = Date.now();
+
+            const check = () => {
+                if (window.Redoc && !resolved) {
+                    resolved = true;
+                    resolve();
+                    return;
+                }
+
+                if (Date.now() - startTime > timeout) {
+                    reject(new Error("Redoc load timeout"));
+                    return;
+                }
+
+                setTimeout(check, REDOC_CHECK_TIMEOUT);
+            };
+
+            check();
+        });
+    }
+
+    private async insertCustomLayoutElements(): Promise<void> {
+        try {
+            const redocContainer = this.getRedocContainer();
+
+            if (redocContainer) {
+                const apiContentDiv = await this.waitForApiContent(
+                    redocContainer
+                );
+                apiContentDiv.setAttribute("lwc:dom", "manual");
 
-            try {
                 const docPhaseInfo = this.getDocPhaseInfo();
                 if (docPhaseInfo) {
-                    this.insertDocPhase(
-                        apiContentDiv as HTMLElement,
-                        docPhaseInfo
-                    );
+                    this.insertDocPhase(apiContentDiv, docPhaseInfo);
                 }
 
                 if (typeof Sprig !== "undefined") {
-                    this.insertSprigSurvey(apiContentDiv as HTMLElement);
+                    this.insertSprigSurvey(apiContentDiv);
                 }
 
-                this.insertFooter(apiContentDiv as HTMLElement);
-            } catch (error) {
-                this.showError = true;
-                console.error(
-                    "Error showing banner and footer elements",
-                    error
-                );
+                this.insertFooter(apiContentDiv);
             }
-        } else {
-            this.layoutTimeoutId = window.setTimeout(
-                () => this.insertCustomLayoutElements(),
-                100
-            );
+        } catch (error) {
+            this.showServerError = true;
+            console.error("Failed to insert layout elements:", error);
         }
     }
 
+    private waitForApiContent(container: HTMLElement): Promise<HTMLElement> {
+        return new Promise((resolve, reject) => {
+            const start = Date.now();
+
+            const check = () => {
+                const div =
+                    container.querySelector<HTMLElement>(".api-content");
+
+                if (div) {
+                    resolve(div);
+                    return;
+                }
+
+                if (Date.now() - start > DEFAULT_TIMEOUT) {
+                    reject(new Error("API content load timeout"));
+                    return;
+                }
+
+                setTimeout(check, DEFAULT_TIMEOUT);
+            };
+
+            check();
+        });
+    }
+
     private insertDocPhase(container: HTMLElement, docPhaseInfo: string): void {
         const docPhaseElement = createElement("doc-phase", { is: DocPhase });
         Object.assign(docPhaseElement, { docPhaseInfo });
@@ -270,11 +317,9 @@ export default class RedocReference extends LightningElement {
             is: SprigSurvey
         });
 
-        // targeting the last element of middle section of page
-        const targetElement =
-            container.lastElementChild?.firstElementChild?.firstElementChild;
-        if (targetElement) {
-            targetElement.appendChild(feedbackElement);
-        }
+        const wrapper = document.createElement("div");
+        wrapper.className = "sprig-survey-wrapper";
+        wrapper.appendChild(feedbackElement);
+        container.appendChild(wrapper);
     }
 }