@salesforcedevs/docs-components 0.0.1-edit → 0.0.1-superscript

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.html

@@ -7,6 +7,11 @@
             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"
@@ -29,7 +34,12 @@
                         <tr key={attribute.name}>
                             <td>
                                 <span class="code">
-                                    {attribute.nameInKebabCase}
+                                    <template lwc:if={isModelAura}>
+                                        {attribute.name}
+                                    </template>
+                                    <template lwc:else>
+                                        {attribute.nameInKebabCase}
+                                    </template>
                                 </span>
                             </td>
                             <td>{attribute.description}</td>
@@ -73,9 +83,7 @@
                         <template lwc:if={method.firstArgument}>
                             <tr key={method.name}>
                                 <td rowspan={method.arguments.length}>
-                                    <span class="code">
-                                        {method.nameInKebabCase}
-                                    </span>
+                                    <span class="code">{method.name}</span>
                                 </td>
                                 <td rowspan={method.arguments.length}>
                                     {method.description}
@@ -100,9 +108,7 @@
                         <template lwc:else>
                             <tr key={method.name}>
                                 <td>
-                                    <span class="code">
-                                        {method.nameInKebabCase}
-                                    </span>
+                                    <span class="code">{method.name}</span>
                                 </td>
                                 <td>{method.description}</td>
                                 <td colspan="3"></td>
@@ -154,11 +160,11 @@
                     </tr>
                 </thead>
                 <tbody>
-                    <template for:each={events} for:item="event">
+                    <template for:each={processedEvents} for:item="event">
                         <tr key={event.name}>
                             <td>
                                 <span class="code">
-                                    {event.nameInKebabCase}
+                                    {event.nameCapitalized}
                                 </span>
                             </td>
                             <td>{event.description}</td>

package/src/modules/doc/specificationContent/specificationContent.ts

@@ -17,6 +17,7 @@ export default class SpecificationContent extends LightningElement {
     private methods: Method[] = [];
     private slots: Specification[] = [];
     private events: Specification[] = [];
+    private _processedEvents: Specification[] = [];
 
     /* TODO: For now setting the timeout to 300ms,
      * post integration with CX-Router API will test and change if required.
@@ -60,6 +61,20 @@ export default class SpecificationContent extends LightningElement {
                     slots: this.slots,
                     events: this.events
                 } = this.data);
+
+                // Process events once when data is set
+                this._processedEvents = this.events
+                    ? this.events.map((event) => {
+                          const capitalizedName = event.name
+                              ? event.name.charAt(0).toUpperCase() +
+                                event.name.slice(1)
+                              : "";
+                          return {
+                              ...event,
+                              nameCapitalized: capitalizedName
+                          };
+                      })
+                    : [];
             }
         } catch (error) {
             this.data = {};
@@ -92,6 +107,15 @@ export default class SpecificationContent extends LightningElement {
         });
     }
 
+    /**
+     * Returns the preprocessed events for easier rendering in the template.
+     * Each event is augmented with a capitalized name property that capitalizes the first letter
+     * while maintaining camelCase format.
+     */
+    get processedEvents(): Specification[] {
+        return this._processedEvents;
+    }
+
     get hasAttributes() {
         return this.attributes?.length > 0;
     }
@@ -108,6 +132,21 @@ export default class SpecificationContent extends LightningElement {
         return this.events?.length > 0;
     }
 
+    get showNoSpecifications() {
+        return (
+            !this.showError &&
+            !this.isLoading &&
+            !this.hasAttributes &&
+            !this.hasMethods &&
+            !this.hasSlots &&
+            !this.hasEvents
+        );
+    }
+
+    get isModelAura() {
+        return this.model === "aura";
+    }
+
     renderedCallback(): void {
         if (this.data) {
             this.debouncedNotifyDataRendered();

package/src/modules/doc/superscriptSubscript/superscriptSubscript.html

@@ -0,0 +1,8 @@
+<template>
+    <template lwc:if={isSuper}>
+        <sup>{value}</sup>
+    </template>
+    <template lwc:else>
+        <sub>{value}</sub>
+    </template>
+</template>

package/src/modules/doc/superscriptSubscript/superscriptSubscript.ts

@@ -0,0 +1,16 @@
+import { LightningElement, api } from "lwc";
+import { normalizeBoolean } from "dxUtils/normalizers";
+
+export default class SuperscriptSubscript extends LightningElement {
+    _isSuper: boolean = true;
+    @api value: string | null = null;
+
+    @api
+    get isSuper(): boolean {
+        return this._isSuper;
+    }
+
+    set isSuper(value) {
+        this._isSuper = normalizeBoolean(value);
+    }
+}

package/src/modules/doc/versionPicker/versionPicker.html

@@ -2,6 +2,8 @@
     <div lwc:if={showVersionPicker} class="version-picker-container">
         <dx-dropdown
             options={versions}
+            analytics-event="custEv_docVersionSelect"
+            analytics-payload={analyticsPayload}
             value={selectedVersion.id}
             width="var(--doc-version-picker-width)"
             onchange={onVersionChange}

package/src/modules/doc/xmlContent/xmlContent.css

@@ -31,10 +31,6 @@ dx-dropdown > dx-button:hover {
     --border-color: var(--button-primary-color-hover);
 }
 
-doc-phase {
-    --doc-c-phase-top: var(--dx-g-global-header-height);
-}
-
 @media screen and (max-width: 768px) {
     doc-content-layout {
         --dx-g-doc-header-main-nav-height: 41px;
@@ -45,10 +41,4 @@ doc-phase {
             var(--dx-g-global-header-height) + var(--dx-g-doc-header-height)
         );
     }
-
-    doc-phase {
-        --doc-c-phase-top: calc(
-            var(--dx-g-global-header-height) + var(--dx-g-doc-header-height)
-        );
-    }
 }

package/src/modules/doc/xmlContent/xmlContent.html

@@ -1,23 +1,18 @@
 <template>
     <doc-content-layout
-        lwc:if={loaded}
+        lwc:if={displayContent}
         lwc:ref="docContentLayout"
-        coveo-organization-id={coveoOrganizationId}
-        coveo-public-access-token={coveoPublicAccessToken}
-        coveo-analytics-token={coveoAnalyticsToken}
-        coveo-search-hub={coveoSearchHub}
-        coveo-advanced-query-config={coveoAdvancedQueryConfig}
         sidebar-header={docTitle}
         sidebar-content={sidebarContent}
         sidebar-value={sidebarValue}
         onselect={handleSelect}
-        use-old-sidebar={useOldSidebar}
         onlangchange={handleLanguageChange}
         languages={sidebarFooterContent.languages}
         language={sidebarFooterContent.language}
         bail-href={sidebarFooterContent.bailHref}
         bail-label={sidebarFooterContent.bailLabel}
         show-footer={enableFooter}
+        reading-time={computedReadingTime}
     >
         <doc-phase
             slot="version-banner"
@@ -30,7 +25,7 @@
         <div lwc:if={showVersionPicker} slot="sidebar-header">
             <doc-version-picker
                 data-type="version"
-                analytics-event="custEv_ctaLinkClick"
+                analytics-event="custEv_linkClick"
                 analytics-payload={ANALYTICS_PAYLOAD}
                 versions={versionOptions}
                 selected-version={version}
@@ -49,4 +44,12 @@
             onnavclick={handleNavClick}
         ></doc-content>
     </doc-content-layout>
+    <div lwc:if={display404}>
+        <dx-error
+            image="https://a.sfdcstatic.com/developer-website/prod/images/404.svg"
+            code="404"
+            header="Beep boop. That did not compute."
+            subtitle="The document you're looking for doesn't seem to exist."
+        ></dx-error>
+    </div>
 </template>