@salesforcedevs/docs-components 0.7.59-sppage-alpha2 → 0.7.76-alpha

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

@@ -0,0 +1,427 @@
+/* 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,
+                    {
+                        // 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.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

@@ -1,3 +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%;
+}

package/src/modules/doc/specificationContent/specificationContent.html

@@ -1,58 +1,130 @@
 <template>
-    <div title="properties">
-        <template if:true={hasAttributes}>
+    <div class="specification-properties">
+        <dx-spinner
+            size="large"
+            variant="brand"
+            class="loader"
+            if:true={isLoading}
+        ></dx-spinner>
+        <dx-error-fallback lwc:if={showError}></dx-error-fallback>
+        <dx-error-fallback
+            lwc:if={showNoSpecifications}
+            title="No specifications to show"
+            description="No specifications are available for this component or API module. When specifications are defined, they'll appear here."
+        ></dx-error-fallback>
+        <template lwc:if={hasAttributes}>
             <doc-heading
                 header="Attributes"
                 hash="attributes"
                 aria-level="2"
+                id="attributes"
             ></doc-heading>
             <table>
                 <thead>
                     <tr>
                         <th>Name</th>
                         <th>Description</th>
+                        <th>Type</th>
+                        <th>Default</th>
+                        <th>Required</th>
                     </tr>
                 </thead>
                 <tbody>
                     <template for:each={attributes} for:item="attribute">
                         <tr key={attribute.name}>
-                            <td>{attribute.nameInKebabCase}</td>
+                            <td>
+                                <span class="code">
+                                    <template lwc:if={isModelAura}>
+                                        {attribute.name}
+                                    </template>
+                                    <template lwc:else>
+                                        {attribute.nameInKebabCase}
+                                    </template>
+                                </span>
+                            </td>
                             <td>{attribute.description}</td>
+                            <td>{attribute.type}</td>
+                            <td>{attribute.default}</td>
+                            <td class="icon-cell">
+                                <template lwc:if={attribute.required}>
+                                    <dx-icon
+                                        symbol="success"
+                                        size="large"
+                                        color="green-vibrant-65"
+                                        class="icon"
+                                    ></dx-icon>
+                                </template>
+                            </td>
                         </tr>
                     </template>
                 </tbody>
             </table>
         </template>
 
-        <template if:true={hasMethods}>
+        <template lwc:if={hasMethods}>
             <doc-heading
                 header="Methods"
                 hash="methods"
                 aria-level="2"
+                id="methods"
             ></doc-heading>
             <table>
                 <thead>
                     <tr>
                         <th>Name</th>
                         <th>Description</th>
+                        <th>Argument Name</th>
+                        <th>Argument Type</th>
+                        <th>Argument Description</th>
                     </tr>
                 </thead>
                 <tbody>
-                    <template for:each={methods} for:item="method">
-                        <tr key={method.name}>
-                            <td>{method.nameInKebabCase}</td>
-                            <td>{method.description}</td>
-                        </tr>
+                    <template for:each={processedMethods} for:item="method">
+                        <template lwc:if={method.firstArgument}>
+                            <tr key={method.name}>
+                                <td rowspan={method.arguments.length}>
+                                    <span class="code">{method.name}</span>
+                                </td>
+                                <td rowspan={method.arguments.length}>
+                                    {method.description}
+                                </td>
+                                <td class={method.cssForMultipleArguments}>
+                                    {method.firstArgument.name}
+                                </td>
+                                <td>{method.firstArgument.type}</td>
+                                <td>{method.firstArgument.description}</td>
+                            </tr>
+                            <template
+                                for:each={method.remainingArguments}
+                                for:item="arg"
+                            >
+                                <tr key={arg.name}>
+                                    <td>{arg.name}</td>
+                                    <td>{arg.type}</td>
+                                    <td>{arg.description}</td>
+                                </tr>
+                            </template>
+                        </template>
+                        <template lwc:else>
+                            <tr key={method.name}>
+                                <td>
+                                    <span class="code">{method.name}</span>
+                                </td>
+                                <td>{method.description}</td>
+                                <td colspan="3"></td>
+                            </tr>
+                        </template>
                     </template>
                 </tbody>
             </table>
         </template>
 
-        <template if:true={hasSlots}>
+        <template lwc:if={hasSlots}>
             <doc-heading
                 header="Slots"
                 hash="slots"
                 aria-level="2"
+                id="slots"
             ></doc-heading>
             <table>
                 <thead>
@@ -64,7 +136,9 @@
                 <tbody>
                     <template for:each={slots} for:item="slot">
                         <tr key={slot.name}>
-                            <td>{slot.nameInKebabCase}</td>
+                            <td>
+                                <span class="code">{slot.nameInKebabCase}</span>
+                            </td>
                             <td>{slot.description}</td>
                         </tr>
                     </template>
@@ -72,7 +146,7 @@
             </table>
         </template>
 
-        <template if:true={hasEvents}>
+        <template lwc:if={hasEvents}>
             <doc-heading
                 header="Events"
                 hash="events"
@@ -86,10 +160,14 @@
                     </tr>
                 </thead>
                 <tbody>
-                    <template for:each={slots} for:item="slot">
-                        <tr key={slot.name}>
-                            <td>{slot.nameInKebabCase}</td>
-                            <td>{slot.description}</td>
+                    <template for:each={processedEvents} for:item="event">
+                        <tr key={event.name}>
+                            <td>
+                                <span class="code">
+                                    {event.nameCapitalized}
+                                </span>
+                            </td>
+                            <td>{event.description}</td>
                         </tr>
                     </template>
                 </tbody>