@salesforcedevs/docs-components 0.0.0 → 0.0.1-superscript

package/src/modules/doc/phase/phase.ts

@@ -2,16 +2,12 @@ import { LightningElement, api } from "lwc";
 import cx from "classnames";
 
 import { DocPhaseInfo } from "typings/custom";
-import { toJson } from "dxUtils/normalizers";
+import { toJson, normalizeBoolean } from "dxUtils/normalizers";
 
 export default class Phase extends LightningElement {
     _docPhaseInfo: DocPhaseInfo | null = null;
-
-    isBodyHidden = false;
-
-    get docPhaseTitle() {
-        return this.docPhaseInfo?.title;
-    }
+    _dismissible = false;
+    _iconName = "recipe";
 
     @api
     get docPhaseInfo(): DocPhaseInfo | null {
@@ -22,6 +18,34 @@ export default class Phase extends LightningElement {
         this._docPhaseInfo = toJson(value);
     }
 
+    @api
+    get dismissible(): boolean {
+        return this._dismissible;
+    }
+
+    set dismissible(value) {
+        if (value) {
+            this._dismissible = normalizeBoolean(value);
+        }
+    }
+
+    @api
+    get iconName(): string {
+        return this._iconName;
+    }
+
+    set iconName(value) {
+        if (value) {
+            this._iconName = value;
+        }
+    }
+
+    isBodyHidden = false;
+
+    get docPhaseTitle() {
+        return this.docPhaseInfo?.title;
+    }
+
     get hideBodyText() {
         return this.isBodyHidden ? "Show" : "Hide";
     }
@@ -51,7 +75,19 @@ export default class Phase extends LightningElement {
         }
     }
 
-    onButtonClick() {
+    onShowHide() {
         this.isBodyHidden = !this.isBodyHidden;
     }
+
+    onDismiss() {
+        this.dispatchEvent(
+            new CustomEvent("dismissphase", {
+                detail: {
+                    docPhaseInfo: this.docPhaseInfo
+                },
+                composed: true,
+                bubbles: true
+            })
+        );
+    }
 }

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,425 @@
+/* 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";
+import { pollUntil } from "dxUtils/async";
+
+declare global {
+    interface Window {
+        Redoc: any;
+    }
+}
+
+declare const Sprig: (eventType: string, eventName: string) => void;
+
+type ReferenceItem = {
+    source: string;
+    href: string;
+    isSelected?: boolean;
+    docPhase?: string | null;
+};
+
+type ReferenceConfig = {
+    refList: ReferenceItem[];
+};
+
+const SCROLL_THROTTLE_DELAY = 50;
+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;
+
+    private docHeaderElement: Element | null = null;
+    private docPhaseWrapperElement: Element | null = null;
+    private lastSidebarTop = 0;
+
+    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._referenceConfig = { refList: [] };
+            this.showErrorUI(
+                "Failed to parse reference configuration data",
+                error
+            );
+        }
+    }
+
+    @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.redocInitialized = true;
+            this.initializeRedoc();
+        }
+    }
+
+    disconnectedCallback(): void {
+        window.removeEventListener("scroll", this.handleScrollAndResize);
+        window.removeEventListener("resize", this.handleScrollAndResize);
+
+        this.handleScrollAndResize?.cancel?.();
+
+        // Clean up cached DOM element references to prevent memory leaks
+        this.docHeaderElement = null;
+        this.docPhaseWrapperElement = null;
+    }
+
+    // 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
+        ).getPropertyValue(variableName);
+        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 {
+        const rowHeight = this.getGlobalCSSVariableValue(
+            "--dx-g-global-header-nav-row-height"
+        );
+        const rowCount = this.getGlobalCSSVariableValue(
+            "--dx-g-global-header-nav-row-count"
+        );
+        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;
+    }
+
+    // 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 currentSidebarTop = this.calculateHeaderOffset();
+            if (currentSidebarTop === this.lastSidebarTop) {
+                return;
+            }
+
+            const sidebarTopValue = `${currentSidebarTop}px`;
+            this.template.host.style.setProperty(
+                "--doc-c-redoc-sidebar-top",
+                sidebarTopValue
+            );
+            this.lastSidebarTop = currentSidebarTop;
+        });
+    };
+
+    // Updates browser URL while preserving query params and hash
+    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 handleScrollAndResize = throttle(
+        SCROLL_THROTTLE_DELAY,
+        () => !this.showError && this.updateSidebarPosition()
+    );
+
+    // Initializes Redoc library with selected reference configuration
+    private async initializeRedoc(): Promise<void> {
+        try {
+            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;
+                if (!specUrl) {
+                    this.showErrorUI("Spec URL not found.");
+                    return;
+                }
+
+                window.Redoc.init(
+                    specUrl,
+                    {
+                        // 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.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,
+            ELEMENT_CHECK_INTERVAL,
+            timeout
+        );
+
+        if (!success) {
+            throw new Error(
+                "Redoc library failed to load within timeout period"
+            );
+        }
+    }
+
+    // Integrates custom elements (doc phase, footer, survey) into Redoc container
+    private async integrateCustomComponents(): Promise<void> {
+        try {
+            const redocContainer = this.getRedocContainer();
+            if (!redocContainer) {
+                return;
+            }
+
+            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);
+
+            // 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.showErrorUI("Failed to integrate custom components:", error);
+        }
+    }
+
+    // Waits for Redoc's API content element to be rendered
+    private async waitForApiContent(
+        container: HTMLElement
+    ): Promise<HTMLElement> {
+        const success = await pollUntil(
+            () => !!container.querySelector(".api-content"),
+            ELEMENT_CHECK_INTERVAL,
+            ELEMENT_TIMEOUT
+        );
+
+        if (!success) {
+            throw new Error(
+                "Redoc API content element not found within timeout period"
+            );
+        }
+
+        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";
+        container.appendChild(wrapper);
+
+        const feedbackElement = createElement("doc-sprig-survey", {
+            is: SprigSurvey
+        });
+        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;
+        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 (!redocThirdColumnElement) {
+            console.warn(
+                "Third column element not found, skipping third column styling"
+            );
+            return;
+        }
+
+        const footerHeight = footer.getBoundingClientRect()?.height || 0;
+        const footerMarginTop = parseInt(
+            getComputedStyle(this.template.host).getPropertyValue(
+                "--dx-footer-margin-top"
+            ),
+            10
+        );
+
+        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"
+            });
+        });
+    }
+}

package/src/modules/doc/specificationContent/specificationContent.css

@@ -0,0 +1,36 @@
+@import "dxHelpers/reset";
+@import "dxHelpers/text";
+@import "dxHelpers/table";
+
+.code {
+    color: #181818;
+    font-family: Courier, var(--dx-g-font-mono);
+    font-size: var(--dx-g-text-sm);
+    line-height: 150%;
+    background-color: #f4f4f4;
+}
+
+table {
+    width: 100%;
+}
+
+.specification-properties table {
+    display: table;
+}
+
+.left-border {
+    border-left: 1px solid var(--dx-g-gray-90);
+}
+
+.icon-cell {
+    text-align: center;
+}
+
+.icon {
+    display: inline-block;
+}
+
+.loader {
+    pointer-events: none;
+    bottom: 30%;
+}