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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@salesforcedevs/docs-components",
-    "version": "1.20.13-redocly",
+    "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="API Documentation Unavailable"
-        description="This API reference is currently unavailable. Please try again later."
-    ></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 {
@@ -21,16 +22,22 @@ type ReferenceConfig = {
     refList: ReferenceItem[];
 };
 
+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;
+    showServerError = false;
 
     @api
     get referenceConfig(): ReferenceConfig {
@@ -42,7 +49,12 @@ export default class RedocReference extends LightningElement {
             const refConfig =
                 typeof value === "string" ? JSON.parse(value) : value;
             this._referenceConfig = refConfig;
-        } catch (e) {
+        } catch (error) {
+            this.showServerError = true;
+            console.error(
+                "Failed to parse reference configuration data",
+                error
+            );
             this._referenceConfig = { refList: [] };
         }
     }
@@ -57,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();
         }
     }
@@ -73,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
@@ -82,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");
@@ -107,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;
@@ -119,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;
@@ -165,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);
@@ -190,11 +208,35 @@ export default class RedocReference extends LightningElement {
                 }
             }
         } catch (error) {
-            this.showError = true;
-            console.error("Failed to load data:", error);
+            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");
@@ -209,9 +251,14 @@ export default class RedocReference extends LightningElement {
                         docPhaseInfo
                     );
                 }
-                this.insertSprigSurvey(apiContentDiv as HTMLElement);
+
+                if (typeof Sprig !== "undefined") {
+                    this.insertSprigSurvey(apiContentDiv as HTMLElement);
+                }
+
                 this.insertFooter(apiContentDiv as HTMLElement);
             } catch (error) {
+                this.showServerError = true;
                 console.error(
                     "Error showing banner and footer elements",
                     error
@@ -220,7 +267,7 @@ export default class RedocReference extends LightningElement {
         } else {
             this.layoutTimeoutId = window.setTimeout(
                 () => this.insertCustomLayoutElements(),
-                100
+                LAYOUT_TIMEOUT
             );
         }
     }
@@ -248,9 +295,8 @@ export default class RedocReference extends LightningElement {
         });
 
         const wrapper = document.createElement("div");
-        wrapper.className = "feedback-wrapper";
+        wrapper.className = "sprig-survey-wrapper";
         wrapper.appendChild(feedbackElement);
-
         container.appendChild(wrapper);
     }
 }