@salesforcedevs/docs-components 1.29.0-alpha1 → 1.29.0-llm-alpha1

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

@@ -2,12 +2,10 @@
 import { createElement, LightningElement, api } from "lwc";
 import DocPhase from "doc/phase";
 import DxFooter from "dx/footer";
+import DxIcon from "dx/icon";
 import SprigSurvey from "doc/sprigSurvey";
-import ApiPlayground from "doc/apiPlayground";
 import { throttle } from "throttle-debounce";
 import { pollUntil } from "dxUtils/async";
-import { parseOpenApiSpec } from "docUtils/openApiParser";
-import type { OperationDefinition } from "docUtils/openApiParser";
 
 declare global {
     interface Window {
@@ -17,11 +15,19 @@ declare global {
 
 declare const Sprig: (eventType: string, eventName: string) => void;
 
+type ReferenceTopic = {
+    link?: { href?: string };
+    children?: ReferenceTopic[];
+};
+
 type ReferenceItem = {
     source: string;
     href: string;
+    title?: string;
     isSelected?: boolean;
     docPhase?: string | null;
+    referenceType?: string;
+    topic?: ReferenceTopic;
 };
 
 type ReferenceConfig = {
@@ -31,6 +37,7 @@ type ReferenceConfig = {
 const SCROLL_THROTTLE_DELAY = 50;
 const ELEMENT_TIMEOUT = 10000;
 const ELEMENT_CHECK_INTERVAL = 100;
+const REFERENCES_SEGMENT = "/references/";
 
 export default class RedocReference extends LightningElement {
     private _referenceConfig: ReferenceConfig = { refList: [] };
@@ -41,11 +48,13 @@ export default class RedocReference extends LightningElement {
     private docPhaseWrapperElement: Element | null = null;
     private lastSidebarTop = 0;
 
-    showError = false;
+    /**
+     * History length captured at mount (pre-Redoc), used by `onBackClick` to
+     * distinguish in-tab navigation (> 1) from a fresh entry (=== 1).
+     */
+    private initialHistoryLength = 0;
 
-    private parsedOperations: OperationDefinition[] = [];
-    private openApiSpec: any = null;
-    private playgroundInstances: Map<string, HTMLElement> = new Map();
+    showError = false;
 
     @api
     get referenceConfig(): ReferenceConfig {
@@ -78,6 +87,75 @@ export default class RedocReference extends LightningElement {
     /** Optional origin URL for the footer MFE (e.g. wp-json endpoint). Passed through to dx-footer. */
     @api origin: string | null = null;
 
+    /**
+     * Project title (same value passed to `<doc-header>` as `subtitle`). Used
+     * inside the Redoc-rendered UI to label the parent project.
+     */
+    @api projectTitle: string | null = "All Reference";
+
+    get specTitle(): string | null {
+        return this.getSelectedReference()?.title ?? null;
+    }
+
+    /**
+     * Whether to show the project header (only for multi-spec reference sets).
+     */
+    get showRedocHeader(): boolean {
+        const refCount = this._referenceConfig?.refList?.length ?? 0;
+        const isMultiSpecSet = refCount > 1;
+        return isMultiSpecSet && !!(this.projectTitle || this.specTitle);
+    }
+
+    /**
+     * Navigates back to reference doc.
+     */
+    private onBackClick = (event: Event): void => {
+        event.preventDefault();
+        const referrerHref = this.getSameOriginReferrerHref();
+        if (referrerHref) {
+            window.location.href = referrerHref;
+            return;
+        }
+        const fallbackHref = this.getReferencesRootHref();
+        if (fallbackHref) {
+            window.location.href = fallbackHref;
+        }
+    };
+
+    /**
+     * Returns the referrer URL when the page was reached via in-tab navigation
+     * from a same-origin page; otherwise `null`. Both `initialHistoryLength`
+     * and `document.referrer` are checked since neither signal is reliable on
+     * its own.
+     */
+    private getSameOriginReferrerHref(): string | null {
+        if (this.initialHistoryLength <= 1 || !document.referrer) {
+            return null;
+        }
+        try {
+            const referrerUrl = new URL(document.referrer);
+            if (referrerUrl.origin !== window.location.origin) {
+                return null;
+            }
+            return referrerUrl.href;
+        } catch {
+            return null;
+        }
+    }
+
+    /**
+     * Derives the project's `.../references` root from the current URL by
+     * trimming any trailing reference id (and deeper segments). Returns null
+     * when the URL doesn't contain a `/references` segment.
+     */
+    private getReferencesRootHref(): string | null {
+        const { pathname } = window.location;
+        const idx = pathname.lastIndexOf(REFERENCES_SEGMENT);
+        return idx === -1
+            ? null
+            : pathname.slice(0, idx + REFERENCES_SEGMENT.length);
+    }
+
     /** When origin is provided, pass it to the footer; otherwise use dx-footer's default. */
     get effectiveFooterOrigin(): string {
         return (
@@ -86,6 +164,10 @@ export default class RedocReference extends LightningElement {
     }
 
     connectedCallback(): void {
+        // Snapshot history length before Redoc pushes its own hash entries,
+        // so it reflects real in-tab navigation rather than Redoc's churn.
+        this.initialHistoryLength = window.history.length;
+
         window.addEventListener("scroll", this.handleScrollAndResize);
         window.addEventListener("resize", this.handleScrollAndResize);
     }
@@ -106,7 +188,6 @@ export default class RedocReference extends LightningElement {
         // Clean up cached DOM element references to prevent memory leaks
         this.docHeaderElement = null;
         this.docPhaseWrapperElement = null;
-        this.playgroundInstances.clear();
     }
 
     // Displays error UI and logs error message for debugging
@@ -220,7 +301,8 @@ export default class RedocReference extends LightningElement {
             const currentUrl = window.location;
             const existingParams = currentUrl.search + currentUrl.hash;
 
-            window.history.pushState(
+            // Use replaceState to avoid creating a new history entry when the user visits /references without any reference ID
+            window.history.replaceState(
                 {},
                 "",
                 `${parentReferencePath}${existingParams}`
@@ -254,8 +336,6 @@ export default class RedocReference extends LightningElement {
                     return;
                 }
 
-                this.fetchAndParseSpec(specUrl);
-
                 window.Redoc.init(
                     specUrl,
                     {
@@ -313,10 +393,12 @@ export default class RedocReference extends LightningElement {
 
             this.appendFooterItems(apiContentDiv);
 
+            // Inject the multi-spec project header into Redoc's left menu only.
+            this.insertProjectHeaderInMenu(redocContainer);
+
             // Wait for footer to be rendered before updating styles
             requestAnimationFrame(() => {
                 this.updateRedocThirdColumnStyle(redocContainer);
-                this.injectTryItButtons();
 
                 // Fix initial hash scroll after doc phase insertion
                 this.handleInitialHashScrollFix();
@@ -326,6 +408,65 @@ export default class RedocReference extends LightningElement {
         }
     }
 
+    /**
+     * Inserts the project header into Redoc for multi-spec reference sets.
+     */
+    private insertProjectHeaderInMenu(redocContainer: HTMLElement): void {
+        if (!this.showRedocHeader) {
+            return;
+        }
+
+        // Select the LNB and content area of Redoc and insert the requried header.
+        redocContainer
+            .querySelectorAll<HTMLElement>(".menu-content, .api-content")
+            .forEach((target) => {
+                target.insertBefore(
+                    this.buildProjectHeaderDom(),
+                    target.firstChild
+                );
+            });
+    }
+
+    /**
+     * Builds a fresh project-title/spec-title header DOM node.
+     */
+    private buildProjectHeaderDom(): HTMLElement {
+        const wrapper = document.createElement("div");
+        wrapper.className = "redoc-project-header";
+
+        if (this.projectTitle) {
+            const backLink = document.createElement("a");
+            backLink.className = "redoc-project-back";
+            backLink.href = "#";
+            backLink.addEventListener("click", this.onBackClick);
+
+            const icon = createElement("dx-icon", { is: DxIcon });
+            Object.assign(icon, {
+                sprite: "utility",
+                symbol: "back",
+                size: "medium"
+            });
+            icon.classList.add("redoc-project-back-arrow");
+
+            const label = document.createElement("span");
+            label.className = "redoc-project-title";
+            label.textContent = this.projectTitle;
+
+            backLink.appendChild(icon);
+            backLink.appendChild(label);
+            wrapper.appendChild(backLink);
+        }
+
+        if (this.specTitle) {
+            const specEl = document.createElement("h2");
+            specEl.className = "redoc-spec-title dx-text-display-7";
+            specEl.textContent = this.specTitle;
+            wrapper.appendChild(specEl);
+        }
+
+        return wrapper;
+    }
+
     // Waits for Redoc's API content element to be rendered
     private async waitForApiContent(
         container: HTMLElement
@@ -359,7 +500,10 @@ export default class RedocReference extends LightningElement {
     // Appends footer component to container
     private insertFooter(container: HTMLElement): void {
         const footerElement = createElement("dx-footer", { is: DxFooter });
-        Object.assign(footerElement, { variant: "no-signup", mfeConfigOrigin: this.effectiveFooterOrigin });
+        Object.assign(footerElement, {
+            variant: "no-signup",
+            mfeConfigOrigin: this.effectiveFooterOrigin
+        });
         container.appendChild(footerElement);
     }
 
@@ -421,114 +565,6 @@ export default class RedocReference extends LightningElement {
         );
     }
 
-    // Fetches and parses the OpenAPI spec for Try It playground
-    private async fetchAndParseSpec(specUrl: string): Promise<void> {
-        try {
-            const response = await fetch(specUrl);
-            if (!response.ok) {
-                return;
-            }
-            this.openApiSpec = await response.json();
-            this.parsedOperations = parseOpenApiSpec(this.openApiSpec);
-        } catch {
-            // Non-fatal: playground simply won't be available
-        }
-    }
-
-    // Injects "Try It" toggle buttons into Redoc operation sections
-    private injectTryItButtons(): void {
-        if (this.parsedOperations.length === 0) {
-            return;
-        }
-
-        const redocContainer = this.getRedocContainer();
-        if (!redocContainer) {
-            return;
-        }
-
-        for (const operation of this.parsedOperations) {
-            const sectionId = `operation/${operation.operationId}`;
-            const section = redocContainer.querySelector(
-                `[data-section-id="${sectionId}"]`
-            );
-            if (!section) {
-                continue;
-            }
-
-            // Skip if button already injected
-            if (section.querySelector(".try-it-toggle")) {
-                continue;
-            }
-
-            const button = document.createElement("button");
-            button.className = "try-it-toggle";
-            button.textContent = "Try It";
-            button.setAttribute("type", "button");
-            button.setAttribute("aria-expanded", "false");
-            button.style.cssText =
-                "display:inline-flex;align-items:center;gap:4px;padding:4px 12px;" +
-                "border:1px solid #0070d2;border-radius:4px;background:#fff;color:#0070d2;" +
-                "font-size:12px;font-weight:600;cursor:pointer;margin-left:12px;vertical-align:middle;";
-            button.addEventListener("click", () => {
-                this.togglePlayground(operation, section as HTMLElement);
-            });
-
-            // Insert button after the first heading or at the start
-            const heading = section.querySelector("h1, h2, h3");
-            if (heading?.parentElement) {
-                heading.parentElement.insertBefore(
-                    button,
-                    heading.nextSibling
-                );
-            } else {
-                section.insertBefore(button, section.firstChild);
-            }
-        }
-    }
-
-    // Toggles the playground panel for an operation section
-    private togglePlayground(
-        operation: OperationDefinition,
-        section: HTMLElement
-    ): void {
-        const operationId = operation.operationId;
-        const existingWrapper = this.playgroundInstances.get(operationId);
-
-        if (existingWrapper) {
-            const isHidden = existingWrapper.style.display === "none";
-            existingWrapper.style.display = isHidden ? "block" : "none";
-
-            const button = section.querySelector(".try-it-toggle");
-            if (button) {
-                button.setAttribute(
-                    "aria-expanded",
-                    isHidden ? "true" : "false"
-                );
-            }
-            return;
-        }
-
-        const wrapper = document.createElement("div");
-        wrapper.className = "try-it-playground-wrapper";
-
-        const playgroundElement = createElement("doc-api-playground", {
-            is: ApiPlayground
-        });
-        Object.assign(playgroundElement, {
-            operation,
-            spec: this.openApiSpec
-        });
-
-        wrapper.appendChild(playgroundElement);
-        section.appendChild(wrapper);
-        this.playgroundInstances.set(operationId, wrapper);
-
-        const button = section.querySelector(".try-it-toggle");
-        if (button) {
-            button.setAttribute("aria-expanded", "true");
-        }
-    }
-
     // Fixes initial hash scroll positioning after doc phase insertion
     private handleInitialHashScrollFix(): void {
         const hash = window.location.hash;

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

@@ -53,7 +53,7 @@
     </doc-content-layout>
     <div lwc:if={display404}>
         <dx-error
-            image="https://a.sfdcstatic.com/developer-website/prod/images/404.svg"
+            image="https://developer.salesforce.com/ns-assets/404.svg"
             code="404"
             header="Beep boop. That did not compute."
             subtitle="The document you're looking for doesn't seem to exist."

package/src/modules/doc/xmlContent/xmlContent.ts

@@ -322,8 +322,10 @@ export default class DocXmlContent extends LightningElementWithState<{
         };
     }
 
-    private handlePopState = (event: PopStateEvent): void =>
+    private handlePopState = (event: PopStateEvent): void => {
         this.updatePageReference(this.getReferenceFromUrl(), event);
+        this.handleLocaleReload();
+    };
 
     handleDismissVersionBanner() {
         this.showVersionBanner = false;
@@ -598,6 +600,31 @@ export default class DocXmlContent extends LightningElementWithState<{
             "docs",
             this.pageReferenceToString(this.pageReference)
         );
+        this.handleLocaleReload();
+    }
+
+    /* This method reloads the page as locale banner context is not available in developer-website. */
+    private handleLocaleReload(): void {
+        const targetLocale = this.language?.id;
+        if (!targetLocale) {
+            return;
+        }
+
+        const currentPath = window.location.pathname;
+        const localePattern = /atlas\.[a-z]{2}-[a-z]{2}\./;
+
+        if (localePattern.test(currentPath)) {
+            const newPath = currentPath.replace(
+                localePattern,
+                `atlas.${targetLocale}.`
+            );
+            const newUrl =
+                window.location.origin +
+                newPath +
+                window.location.search +
+                window.location.hash;
+            window.location.href = newUrl;
+        }
     }
 
     private updateHighlighting(searchParam: string): void {

package/src/modules/doc/apiPlayground/apiPlayground.css

@@ -1,186 +0,0 @@
-:host {
-    display: block;
-}
-
-.playground-container {
-    border: 1px solid var(--dx-g-color-border-primary, #e0e0e0);
-    border-radius: 8px;
-    padding: 20px;
-    margin: 16px 0;
-    background: var(--dx-g-color-surface-primary, #ffffff);
-}
-
-.playground-header {
-    display: flex;
-    align-items: center;
-    gap: 12px;
-    margin-bottom: 20px;
-}
-
-.method-badge {
-    display: inline-block;
-    padding: 4px 10px;
-    border-radius: 4px;
-    font-size: 12px;
-    font-weight: 700;
-    text-transform: uppercase;
-    color: #fff;
-    letter-spacing: 0.5px;
-}
-
-.method-get {
-    background-color: #61affe;
-}
-
-.method-post {
-    background-color: #49cc90;
-}
-
-.method-put {
-    background-color: #fca130;
-}
-
-.method-delete {
-    background-color: #f93e3e;
-}
-
-.method-patch {
-    background-color: #50e3c2;
-}
-
-.method-options,
-.method-head {
-    background-color: #9012fe;
-}
-
-.operation-path {
-    font-family: var(--dx-g-font-family-mono, monospace);
-    font-size: 14px;
-    font-weight: 600;
-    color: var(--dx-g-color-text-primary, #181818);
-}
-
-.params-section {
-    margin-bottom: 16px;
-}
-
-.section-title {
-    font-size: 13px;
-    font-weight: 600;
-    margin: 0 0 8px 0;
-    color: var(--dx-g-color-text-secondary, #444);
-    text-transform: uppercase;
-    letter-spacing: 0.5px;
-}
-
-.field-group {
-    margin-bottom: 12px;
-}
-
-.field-label {
-    display: block;
-    font-size: 13px;
-    font-weight: 500;
-    margin-bottom: 4px;
-    color: var(--dx-g-color-text-primary, #181818);
-}
-
-.required-marker {
-    color: #f93e3e;
-    margin-left: 2px;
-}
-
-.field-input,
-.server-select {
-    width: 100%;
-    padding: 8px 12px;
-    border: 1px solid var(--dx-g-color-border-primary, #e0e0e0);
-    border-radius: 4px;
-    font-size: 14px;
-    font-family: var(--dx-g-font-family-mono, monospace);
-    background: var(--dx-g-color-surface-primary, #ffffff);
-    color: var(--dx-g-color-text-primary, #181818);
-    box-sizing: border-box;
-}
-
-.field-input:focus,
-.server-select:focus {
-    outline: none;
-    border-color: var(--dx-g-color-brand, #0070d2);
-    box-shadow: 0 0 0 1px var(--dx-g-color-brand, #0070d2);
-}
-
-.body-textarea {
-    width: 100%;
-    padding: 8px 12px;
-    border: 1px solid var(--dx-g-color-border-primary, #e0e0e0);
-    border-radius: 4px;
-    font-size: 13px;
-    font-family: var(--dx-g-font-family-mono, monospace);
-    background: var(--dx-g-color-surface-primary, #ffffff);
-    color: var(--dx-g-color-text-primary, #181818);
-    resize: vertical;
-    box-sizing: border-box;
-}
-
-.body-textarea:focus {
-    outline: none;
-    border-color: var(--dx-g-color-brand, #0070d2);
-    box-shadow: 0 0 0 1px var(--dx-g-color-brand, #0070d2);
-}
-
-.actions {
-    margin: 16px 0;
-}
-
-.error-display {
-    margin-top: 16px;
-    padding: 12px;
-    border-radius: 4px;
-    background-color: #fef0ef;
-    border: 1px solid #f93e3e;
-}
-
-.error-message {
-    color: #c23934;
-    font-size: 13px;
-    margin: 0;
-}
-
-.response-section {
-    margin-top: 16px;
-}
-
-.response-header {
-    display: flex;
-    align-items: center;
-    gap: 12px;
-    margin-bottom: 8px;
-}
-
-.status-code {
-    font-weight: 700;
-    font-size: 14px;
-    padding: 2px 8px;
-    border-radius: 4px;
-}
-
-.status-success {
-    color: #256029;
-    background-color: #e6f9ec;
-}
-
-.status-client-error {
-    color: #974b00;
-    background-color: #fff3e0;
-}
-
-.status-server-error {
-    color: #c23934;
-    background-color: #fef0ef;
-}
-
-.response-duration {
-    font-size: 12px;
-    color: var(--dx-g-color-text-tertiary, #999);
-}