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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@salesforcedevs/docs-components",
-    "version": "1.20.13-redocly1",
+    "version": "1.20.13-redocly2",
     "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,21 @@ type ReferenceConfig = {
 };
 
 declare const Sprig: (eventType: string, eventNme: string) => void;
+const FOOTER_MARGIN_TOP = 142;
+const THROTTLE_TIMEOUT = 200;
+const REDOC_TIMEOUT = 10000;
+const REDOC_CHECK_TIMEOUT = 100;
+const LAYOUT_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 +50,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 +69,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 +85,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 +94,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 +113,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 +135,18 @@ 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(THROTTLE_TIMEOUT, () =>
+        this.adjustPosition()
+    );
+
     private getDocPhaseInfo(): string | null {
         if (this._parentDocPhaseInfo) {
             return this._parentDocPhaseInfo;
@@ -177,8 +182,9 @@ export default class RedocReference extends LightningElement {
         }
     }
 
-    private initializeRedoc(): void {
+    private async initializeRedoc(): Promise<void> {
         try {
+            await this.waitForRedoc();
             const selectedRef = this.getSelectedReference();
             if (selectedRef) {
                 this.updateUrlWithReference(selectedRef);
@@ -199,20 +205,38 @@ export default class RedocReference extends LightningElement {
                     );
                 } 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 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 insertCustomLayoutElements(): void {
         const redocContainer = this.getRedocContainer();
         const apiContentDiv = redocContainer?.querySelector(".api-content");
@@ -234,7 +258,7 @@ export default class RedocReference extends LightningElement {
 
                 this.insertFooter(apiContentDiv as HTMLElement);
             } catch (error) {
-                this.showError = true;
+                this.showServerError = true;
                 console.error(
                     "Error showing banner and footer elements",
                     error
@@ -243,7 +267,7 @@ export default class RedocReference extends LightningElement {
         } else {
             this.layoutTimeoutId = window.setTimeout(
                 () => this.insertCustomLayoutElements(),
-                100
+                LAYOUT_TIMEOUT
             );
         }
     }
@@ -270,11 +294,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);
     }
 }