@salesforcedevs/docs-components 1.28.4 → 1.28.5-redoc-alpha

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@salesforcedevs/docs-components",
-  "version": "1.28.4",
+  "version": "1.28.5-redoc-alpha",
   "description": "Docs Lightning web components for DSC",
   "license": "MIT",
   "main": "index.js",
   "engines": {
-    "node": "20.x"
+    "node": "22.x"
   },
   "publishConfig": {
     "access": "public"

package/src/modules/doc/amfReference/amfReference.html

@@ -42,7 +42,18 @@
                 latest-version={latestVersion}
             ></doc-version-picker>
         </div>
-        <template lwc:if={showSpecBasedReference}>
+        <template lwc:if={showRedocReference}>
+            <doc-redoc-reference
+                reference-config={redocReferenceConfig}
+                doc-phase-info={docPhaseInfo}
+                project-title={projectTitle}
+                spec-title={redocSpecTitle}
+                origin={origin}
+            >
+                <div class="redoc-container"></div>
+            </doc-redoc-reference>
+        </template>
+        <template lwc:elseif={showSpecBasedReference}>
             <div class="container">
                 <div class="api-documentation">
                     <doc-amf-topic

package/src/modules/doc/amfReference/amfReference.ts

@@ -24,6 +24,7 @@ import {
     NAVIGATION_ITEMS,
     URL_CONFIG,
     REFERENCE_TYPES,
+    RENDER_WITH,
     oldReferenceIdNewReferenceIdMap
 } from "./constants";
 import { restoreScroll } from "dx/scrollManager";
@@ -44,6 +45,12 @@ export default class AmfReference extends LightningElement {
     /** Optional Twitter "via" handle (e.g. SalesforceDevs) for social share; passed to doc-content-layout. */
     @api twitterVia: string | null = null;
     @api sidebarHeader!: string;
+    /**
+     * Project title shown by `<doc-header>` (as its `subtitle`). Forwarded to
+     * `<doc-redoc-reference>` so it can surface the same project title inside
+     * the Redoc-rendered UI.
+     */
+    @api projectTitle: string | null = null;
     @api tocTitle?: string;
     @api tocOptions?: string;
     @api tocAriaLevel?: string;
@@ -69,7 +76,48 @@ export default class AmfReference extends LightningElement {
      * Gives if the currently selected reference is spec based or not
      */
     get showSpecBasedReference(): boolean {
-        return this.isSpecBasedReference(this._currentReferenceId);
+        return (
+            this.isSpecBasedReference(this._currentReferenceId) &&
+            !this.showRedocReference
+        );
+    }
+
+    /**
+     * Whether the currently selected reference is rendered with Redoc.
+     * Driven by the backend-supplied `renderWith` attribute on the AmfConfig.
+     */
+    get showRedocReference(): boolean {
+        return this.isRedocReference(this._currentReferenceId);
+    }
+
+    /**
+     * Serialized config consumed by `<doc-redoc-reference>`. Built from the
+     * currently selected redoc reference so Redoc has a single spec to render.
+     */
+    get redocReferenceConfig(): string {
+        const ref = this.getAmfConfigWithId(this._currentReferenceId);
+        if (!ref) {
+            return JSON.stringify({ refList: [] });
+        }
+        return JSON.stringify({
+            refList: [
+                {
+                    source: ref.source || ref.amf || "",
+                    href: ref.href,
+                    isSelected: true,
+                    docPhase: ref.docPhase ?? null
+                }
+            ]
+        });
+    }
+
+    /**
+     * Title of the currently selected spec. Forwarded to `<doc-redoc-reference>`
+     * so it can label the spec inside the Redoc UI.
+     */
+    get redocSpecTitle(): string {
+        const ref = this.getAmfConfigWithId(this._currentReferenceId);
+        return ref?.title ?? "";
     }
 
     @api
@@ -296,6 +344,16 @@ export default class AmfReference extends LightningElement {
             : false;
     }
 
+    /**
+     * @param referenceId
+     * @returns whether the reference should be rendered with Redoc rather than
+     * the AMF-based topic renderer.
+     */
+    private isRedocReference(referenceId: string): boolean {
+        const selectedReference = this.getAmfConfigWithId(referenceId);
+        return selectedReference?.renderWith === RENDER_WITH.redoc;
+    }
+
     /*
      * Refactor below method when sidebar allows sending extraData along with the name for each item.
      * See if we can refactor the below method using regex.
@@ -442,7 +500,11 @@ export default class AmfReference extends LightningElement {
         for (const [index, amfConfig] of this._amfConfigList.entries()) {
             let navItemChildren = [] as ParsedMarkdownTopic[];
             let isChildrenLoading = false;
-            if (amfConfig.referenceType !== REFERENCE_TYPES.markdown) {
+            if (amfConfig.renderWith === RENDER_WITH.redoc) {
+                // Redoc-rendered specs have no AMF model and no sub-tree; they
+                // appear as leaf items in the sidebar and open the Redoc UI on
+                // selection.
+            } else if (amfConfig.referenceType !== REFERENCE_TYPES.markdown) {
                 if (amfConfig.isSelected) {
                     const amfPromise = this.fetchAmf(amfConfig).then(
                         (amfJson) => {
@@ -862,6 +924,12 @@ export default class AmfReference extends LightningElement {
         const specBasedReference = this.isSpecBasedReference(
             this._currentReferenceId
         );
+        if (this.isRedocReference(this._currentReferenceId)) {
+            // Redoc reads its own state from referenceConfig + window.location;
+            // no metadata to sync from URL on our side.
+            restoreScroll();
+            return;
+        }
         if (specBasedReference) {
             const currentMeta: RouteMeta | undefined =
                 this.getReferenceMetaInfo(window.location.href);
@@ -896,6 +964,9 @@ export default class AmfReference extends LightningElement {
      * @param event
      */
     protected onApiNavigationChanged(): void {
+        if (this.isRedocReference(this._currentReferenceId)) {
+            return;
+        }
         const specBasedReference = this.isSpecBasedReference(
             this._currentReferenceId
         );
@@ -1165,6 +1236,12 @@ export default class AmfReference extends LightningElement {
         }
 
         const specBasedReference = this.isSpecBasedReference(referenceId);
+        const redocReference = this.isRedocReference(referenceId);
+        if (redocReference) {
+            // Redoc-rendered references have no AMF model; the redoc component
+            // handles its own URL/spec resolution from referenceConfig.
+            return;
+        }
         if (specBasedReference) {
             // Wait till the AMF is loaded.
             this.amfFetchPromiseMap[referenceId].then(() => {

package/src/modules/doc/amfReference/constants.ts

@@ -61,6 +61,10 @@ export const REFERENCE_TYPES = {
     oa3: "rest-oa3"
 };
 
+export const RENDER_WITH = {
+    redoc: "redoc"
+};
+
 const oldReferenceIdNewReferenceIdMap: Record<string, string> = {
     "commerce-api-assignments": "assignments",
     "commerce-api-campaigns": "campaigns",

package/src/modules/doc/amfReference/types.ts

@@ -78,6 +78,19 @@ export interface AmfConfig {
 
     // required for markdown based references
     topic?: ParsedMarkdownTopic;
+
+    /**
+     * Optional renderer override sent by the backend.
+     * When "redoc", spec-based references are rendered with Redoc instead of
+     * the AMF-based topic view. Other values fall back to the default pipeline.
+     */
+    renderWith?: string;
+
+    /**
+     * Spec URL consumed by alternate renderers (e.g. Redoc). For redoc-rendered
+     * references this is the OpenAPI document URL.
+     */
+    source?: string;
 }
 
 export interface ParsedTopicModel {

package/src/modules/doc/redocReference/redocReference.css

@@ -5,3 +5,27 @@
             var(--dx-g-spacing-xl)
     );
 }
+
+.redoc-project-header {
+    display: flex;
+    flex-direction: column;
+    gap: var(--dx-g-spacing-2xs);
+    padding: var(--dx-g-spacing-s) var(--dx-g-spacing-m);
+}
+
+.redoc-project-back {
+    display: inline-flex;
+    align-items: center;
+    gap: var(--dx-g-spacing-xs);
+    color: var(--dx-g-blue-vibrant-50);
+    text-decoration: none;
+    width: fit-content;
+}
+
+.redoc-project-back:hover .redoc-project-title {
+    text-decoration: underline;
+}
+
+.redoc-spec-title {
+    margin: 0;
+}

package/src/modules/doc/redocReference/redocReference.html

@@ -8,6 +8,22 @@
         ></dx-error>
     </template>
     <template lwc:else>
+        <div lwc:if={showRedocHeader} class="redoc-project-header">
+            <a
+                lwc:if={projectTitle}
+                class="redoc-project-back"
+                href="#"
+                onclick={onBackClick}
+            >
+                <dx-icon sprite="utility" symbol="back" size="small"></dx-icon>
+                <span class="redoc-project-title dx-text-body-4">
+                    {projectTitle}
+                </span>
+            </a>
+            <h2 lwc:if={specTitle} class="redoc-spec-title dx-text-display-6">
+                {specTitle}
+            </h2>
+        </div>
         <slot></slot>
     </template>
 </template>

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

@@ -71,6 +71,28 @@ 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 = null;
+
+    /** Title of the currently selected spec, shown beneath the project title. */
+    @api specTitle: string | null = null;
+
+    get showRedocHeader(): boolean {
+        return !!(this.projectTitle || this.specTitle);
+    }
+
+    /**
+     * Navigates back to the previous history entry when the user clicks the
+     * project-title back link rendered above the Redoc UI.
+     */
+    private onBackClick(event: Event): void {
+        event.preventDefault();
+        window.history.back();
+    }
+
     /** When origin is provided, pass it to the footer; otherwise use dx-footer's default. */
     get effectiveFooterOrigin(): string {
         return (
@@ -108,7 +130,13 @@ export default class RedocReference extends LightningElement {
     }
 
     private getRedocContainer(): HTMLElement | null {
-        return document.querySelector(".redoc-container");
+        // Prefer the slotted container in the consumer's light DOM so this
+        // component composes inside shadow trees; fall back to a global
+        // `.redoc-container` for legacy page-level integrations.
+        return (
+            this.querySelector<HTMLElement>(".redoc-container") ||
+            document.querySelector<HTMLElement>(".redoc-container")
+        );
     }
 
     private getSelectedReference(): ReferenceItem | null {

package/.npmrc

@@ -1 +0,0 @@
-//registry.npmjs.org/:_authToken=${SFDOCS_NPM_AUTH_TOKEN}