@salesforcedevs/docs-components 1.21.1-redocly2 → 1.21.1-redocly3

package/package.json

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

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

@@ -35,6 +35,8 @@ export default class RedocReference extends LightningElement {
     private redocInitialized = false;
 
     private docHeaderElement: Element | null = null;
+    private docPhaseWrapperElement: Element | null = null;
+    private lastSidebarTop = 0;
 
     showError = false;
 
@@ -49,12 +51,11 @@ export default class RedocReference extends LightningElement {
                 typeof value === "string" ? JSON.parse(value) : value;
             this._referenceConfig = refConfig;
         } catch (error) {
-            this.showError = true;
-            console.error(
+            this._referenceConfig = { refList: [] };
+            this.showErrorUI(
                 "Failed to parse reference configuration data",
                 error
             );
-            this._referenceConfig = { refList: [] };
         }
     }
 
@@ -81,13 +82,40 @@ export default class RedocReference extends LightningElement {
     disconnectedCallback(): void {
         window.removeEventListener("scroll", this.handleScrollAndResize);
         window.removeEventListener("resize", this.handleScrollAndResize);
+
+        // Clean up cached DOM element references to prevent memory leaks
+        this.docHeaderElement = null;
+        this.docPhaseWrapperElement = null;
     }
 
-    @api
-    setDocPhaseInfo(docPhaseInfo: string): void {
-        this._parentDocPhaseInfo = docPhaseInfo;
+    // Displays error UI and logs error message for debugging
+    private showErrorUI(message: string, error?: any): void {
+        this.showError = true;
+        console.error(message, error);
+    }
+
+    private getRedocContainer(): HTMLElement | null {
+        return document.querySelector(".redoc-container");
     }
 
+    private getSelectedReference(): ReferenceItem | null {
+        return (
+            this._referenceConfig?.refList?.find((ref) => ref.isSelected) ||
+            this._referenceConfig?.refList?.[0]
+        );
+    }
+
+    private getDocPhaseInfo(): string | null {
+        if (this._parentDocPhaseInfo) {
+            return this._parentDocPhaseInfo;
+        }
+        const selectedRef = this.getSelectedReference();
+        return selectedRef?.docPhase
+            ? JSON.stringify(selectedRef.docPhase)
+            : null;
+    }
+
+    // Extracts numeric value from CSS custom properties
     private getGlobalCSSVariableValue(variableName: string): number {
         const value = getComputedStyle(
             document.documentElement
@@ -95,11 +123,11 @@ export default class RedocReference extends LightningElement {
         return parseInt(value, 10) || 0;
     }
 
+    /*
+     ** Since we could not use --dx-g-global-header-height as getPropertyValue returns a calc expression,
+     ** we are using the respective CSS variables to calculate the height.
+     */
     private getGlobalHeaderHeight(): number {
-        /*
-         ** Since we could not use --dx-g-global-header-height as getPropertyValue returns a calc expression,
-         ** we are using the respective CSS variables to calculate the height.
-         */
         const rowHeight = this.getGlobalCSSVariableValue(
             "--dx-g-global-header-nav-row-height"
         );
@@ -109,59 +137,62 @@ export default class RedocReference extends LightningElement {
         return rowHeight * rowCount;
     }
 
+    // Gets doc header height with element caching for performance
     private getDocHeaderHeight(): number {
         if (!this.docHeaderElement) {
             this.docHeaderElement =
                 document.querySelector(".sticky-doc-header");
         }
-        return this.docHeaderElement?.getBoundingClientRect().height || 0;
+        return this.docHeaderElement?.getBoundingClientRect()?.height || 0;
     }
 
-    private handleLayoutChange = () => {
+    // Gets doc phase wrapper height with element caching for performance
+    private getDocPhaseWrapperHeight(): number {
+        if (!this.docPhaseWrapperElement) {
+            this.docPhaseWrapperElement =
+                document.querySelector(".doc-phase-wrapper");
+        }
+        return (
+            this.docPhaseWrapperElement?.getBoundingClientRect()?.height || 0
+        );
+    }
+
+    calculateHeaderOffset = () => {
+        const globalHeaderHeight = this.getGlobalHeaderHeight();
+        const docHeaderHeight = this.getDocHeaderHeight();
+        return globalHeaderHeight + docHeaderHeight;
+    };
+
+    // Dynamic scroll offset calculation that Redoc will call
+    calculateScrollYOffset = () => {
+        const headerOffset = this.calculateHeaderOffset();
+        const phaseHeight = this.getDocPhaseWrapperHeight();
+        return headerOffset + phaseHeight;
+    };
+
+    // Updates sidebar positioning based on current header heights
+    private updateSidebarPosition = () => {
         requestAnimationFrame(() => {
             const redocContainer = this.getRedocContainer();
             if (!redocContainer) {
                 return;
             }
 
-            const globalNavHeight = this.getGlobalHeaderHeight();
-            const docHeaderHeight = this.getDocHeaderHeight();
-            const calculatedTopValue = `${globalNavHeight + docHeaderHeight}px`;
+            const currentSidebarTop = this.calculateHeaderOffset();
+            if (currentSidebarTop === this.lastSidebarTop) {
+                return;
+            }
 
-            // Set updated top value for the sidebar and doc phase
+            const sidebarTopValue = `${currentSidebarTop}px`;
             this.template.host.style.setProperty(
                 "--doc-c-redoc-sidebar-top",
-                calculatedTopValue
+                sidebarTopValue
             );
+            this.lastSidebarTop = currentSidebarTop;
         });
     };
 
-    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?.find((ref) => ref.isSelected) ||
-            this._referenceConfig?.refList?.[0]
-        );
-    }
-
-    private getRedocContainer(): HTMLElement | null {
-        return document.querySelector(".redoc-container");
-    }
-
+    // Updates browser URL while preserving query params and hash
     private updateUrlWithReference(selectedRef: ReferenceItem): void {
         if (selectedRef?.href) {
             const parentReferencePath = selectedRef.href;
@@ -176,46 +207,62 @@ export default class RedocReference extends LightningElement {
         }
     }
 
+    private handleScrollAndResize = throttle(
+        SCROLL_THROTTLE_DELAY,
+        () => !this.showError && this.updateSidebarPosition()
+    );
+
+    // Initializes Redoc library with selected reference configuration
     private async initializeRedoc(): Promise<void> {
         try {
             this.redocInitialized = true;
-
             await this.waitForRedoc();
+
+            const redocContainer = this.getRedocContainer();
+            if (!redocContainer) {
+                this.showErrorUI("Redoc container is not found.");
+                return;
+            }
+
             const selectedRef = this.getSelectedReference();
             if (selectedRef) {
                 this.updateUrlWithReference(selectedRef);
 
                 const specUrl = selectedRef.source;
-                const redocContainer = this.getRedocContainer();
-                if (specUrl && redocContainer) {
-                    window.Redoc.init(
-                        specUrl,
-                        {
-                            expandResponses: "200,400"
-                        },
-                        redocContainer,
-                        (error: any) => {
-                            if (error) {
-                                this.showError = true;
-                                console.error(
-                                    "Failed to show Reference UI using Redoc: ",
-                                    error
-                                );
-                            } else {
-                                this.insertCustomLayoutElements();
-                            }
-                        }
+                if (!specUrl) {
+                    this.showErrorUI(
+                        "Spec URL or Redoc container is not found."
                     );
-                } else {
-                    this.showError = true;
+                    return;
                 }
+
+                window.Redoc.init(
+                    specUrl,
+                    {
+                        // Auto-expand HTTP 200 and 400 response sections
+                        expandResponses: "200,400",
+                        // Dynamic scroll offset to account for headers
+                        scrollYOffset: this.calculateScrollYOffset
+                    },
+                    redocContainer,
+                    (error: any) => {
+                        if (error) {
+                            this.showErrorUI(
+                                "Failed to show Reference UI using Redoc: ",
+                                error
+                            );
+                        } else {
+                            this.integrateCustomComponents();
+                        }
+                    }
+                );
             }
         } catch (error) {
-            this.showError = true;
-            console.error("Failed to load Redoc library:", error);
+            this.showErrorUI("Failed to load Redoc library:", error);
         }
     }
 
+    // Polls for Redoc library availability with timeout
     private async waitForRedoc(timeout = ELEMENT_TIMEOUT): Promise<void> {
         const success = await pollUntil(
             () => !!window.Redoc,
@@ -230,39 +277,41 @@ export default class RedocReference extends LightningElement {
         }
     }
 
-    private async insertCustomLayoutElements(): Promise<void> {
+    // Integrates custom elements (doc phase, footer, survey) into Redoc container
+    private async integrateCustomComponents(): Promise<void> {
         try {
             const redocContainer = this.getRedocContainer();
+            if (!redocContainer) {
+                return;
+            }
 
-            if (redocContainer) {
-                const apiContentDiv = await this.waitForApiContent(
-                    redocContainer
-                );
-                apiContentDiv.setAttribute("lwc:dom", "manual");
+            const apiContentDiv = await this.waitForApiContent(redocContainer);
+            apiContentDiv.setAttribute("lwc:dom", "manual");
 
-                const docPhaseInfo = this.getDocPhaseInfo();
-                if (docPhaseInfo) {
-                    this.insertDocPhase(apiContentDiv, docPhaseInfo);
-                }
+            const docPhaseInfo = this.getDocPhaseInfo();
+            if (docPhaseInfo) {
+                this.insertDocPhase(apiContentDiv, docPhaseInfo);
+            }
 
-                if (typeof Sprig !== "undefined") {
-                    this.insertSprigSurvey(apiContentDiv);
-                }
+            if (typeof Sprig !== "undefined") {
+                this.insertSprigSurvey(apiContentDiv);
+            }
 
-                this.insertFooter(apiContentDiv);
+            this.insertFooter(apiContentDiv);
 
-                // Wait for footer to be rendered before updating styles
-                requestAnimationFrame(() => {
-                    // Update third column bottom position to avoid footer overlap.
-                    this.updateRedocThirdColumnStyle(redocContainer);
-                });
-            }
+            // Wait for footer to be rendered before updating styles
+            requestAnimationFrame(() => {
+                this.updateRedocThirdColumnStyle(redocContainer);
+
+                // Fix initial hash scroll after doc phase insertion
+                this.handleInitialHashScrollFix();
+            });
         } catch (error) {
-            this.showError = true;
-            console.error("Failed to insert layout elements:", error);
+            this.showErrorUI("Failed to integrate custom components:", error);
         }
     }
 
+    // Waits for Redoc's API content element to be rendered
     private async waitForApiContent(
         container: HTMLElement
     ): Promise<HTMLElement> {
@@ -281,24 +330,25 @@ export default class RedocReference extends LightningElement {
         return container.querySelector<HTMLElement>(".api-content")!;
     }
 
+    // Creates and inserts doc phase component at container start
     private insertDocPhase(container: HTMLElement, docPhaseInfo: string): void {
         const wrapper = document.createElement("div");
         wrapper.className = "doc-phase-wrapper";
-
         container.insertBefore(wrapper, container.firstChild);
 
         const docPhaseElement = createElement("doc-phase", { is: DocPhase });
         Object.assign(docPhaseElement, { docPhaseInfo });
-
         wrapper.appendChild(docPhaseElement);
     }
 
+    // Appends footer component to container
     private insertFooter(container: HTMLElement): void {
         const footerElement = createElement("dx-footer", { is: DxFooter });
         Object.assign(footerElement, { variant: "no-signup" });
         container.appendChild(footerElement);
     }
 
+    // Appends Sprig survey component to container
     private insertSprigSurvey(container: HTMLElement): void {
         const wrapper = document.createElement("div");
         wrapper.className = "sprig-survey-wrapper";
@@ -310,24 +360,29 @@ export default class RedocReference extends LightningElement {
         wrapper.appendChild(feedbackElement);
     }
 
+    // Adjusts third column bottom position to prevent footer overlap
     private updateRedocThirdColumnStyle(redocContainer: HTMLElement): void {
         const footer = redocContainer.querySelector(
             ".redoc-wrap .api-content dx-footer"
         ) as HTMLElement;
-        const thirdColumnContainer = redocContainer.querySelector(
+        if (!footer) {
+            console.warn(
+                "Footer element not found, skipping third column styling"
+            );
+            return;
+        }
+
+        const redocThirdColumnElement = redocContainer.querySelector(
             ".redoc-wrap > div:last-child"
         ) as HTMLElement;
-
-        if (!thirdColumnContainer || !footer) {
+        if (!redocThirdColumnElement) {
             console.warn(
-                !thirdColumnContainer
-                    ? "Redoc Third column container not found"
-                    : "Footer not found in DOM, skipping third column styling"
+                "Third column element not found, skipping third column styling"
             );
             return;
         }
 
-        const footerHeight = footer.getBoundingClientRect().height || 0;
+        const footerHeight = footer.getBoundingClientRect()?.height || 0;
         const footerMarginTop = parseInt(
             getComputedStyle(this.template.host).getPropertyValue(
                 "--dx-footer-margin-top"
@@ -335,9 +390,38 @@ export default class RedocReference extends LightningElement {
             10
         );
 
-        thirdColumnContainer.style.setProperty(
+        redocThirdColumnElement.style.setProperty(
             "bottom",
             `${footerHeight + footerMarginTop}px`
         );
     }
+
+    // Fixes initial hash scroll positioning after doc phase insertion
+    private handleInitialHashScrollFix(): void {
+        const hash = window.location.hash;
+        if (!hash || hash.length <= 1) {
+            return;
+        }
+
+        // Small delay to ensure all components are fully rendered
+        requestAnimationFrame(() => {
+            const targetId = hash.substring(1);
+            const targetElement = document.getElementById(targetId);
+
+            if (!targetElement) {
+                return;
+            }
+
+            const elementTop =
+                (targetElement.getBoundingClientRect()?.top || 0) +
+                window.pageYOffset;
+            const scrollOffset = this.calculateScrollYOffset();
+            const correctedScrollPosition = elementTop - scrollOffset;
+
+            window.scrollTo({
+                top: correctedScrollPosition,
+                behavior: "smooth"
+            });
+        });
+    }
 }