@salesforcedevs/docs-components 1.31.0-md-alpha2 → 1.31.0-md-doctoolbar-alpha

package/lwc.config.json

@@ -18,6 +18,7 @@
         "doc/contentMedia",
         "doc/docXmlContent",
         "doc/lwcContentLayout",
+        "doc/unifiedContentLayout",
         "doc/header",
         "doc/heading",
         "doc/headingAnchor",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforcedevs/docs-components",
-  "version": "1.31.0-md-alpha2",
+  "version": "1.31.0-md-doctoolbar-alpha",
   "description": "Docs Lightning web components for DSC",
   "license": "MIT",
   "main": "index.js",

package/src/modules/doc/contentLayout/contentLayout.ts

@@ -9,7 +9,7 @@ import { buildDocLinkClickHandler } from "dxUtils/analytics";
 import ContentActionToolbar from "doc/contentActionToolbar";
 
 const CONTENT_ACTION_TOOLBAR_TAG = "doc-content-action-toolbar";
-const PAGE_HEADING_SELECTOR = "h1, doc-heading";
+const PAGE_HEADING_SELECTOR = "h1";
 
 type AnchorMap = { [key: string]: { intersect: boolean; id: string } };
 
@@ -286,8 +286,7 @@ export default class ContentLayout extends LightningElement {
 
     /**
      * Inserts the content action toolbar into the slotted content immediately
-     * after the first heading (any level) found inside the content body. This is
-     * the page's H1 when present, otherwise the first heading in document order.
+     * after the first H1 found inside this layout.
      */
     protected updateContentActionToolbar(): void {
         if (!this.showContentActionToolbar || !this.sidebarValue) {

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

@@ -1,7 +1,6 @@
 :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)
+        var(--dx-g-global-header-height) + var(--dx-g-doc-header-height)
     );
 }

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

@@ -3,9 +3,12 @@ import { createElement, LightningElement, api } from "lwc";
 import DocPhase from "doc/phase";
 import DxFooter from "dx/footer";
 import DxIcon from "dx/icon";
+import SidebarFooterNav from "dx/sidebarFooterNav";
 import SprigSurvey from "doc/sprigSurvey";
 import { throttle } from "throttle-debounce";
 import { pollUntil } from "dxUtils/async";
+import { toJson } from "dxUtils/normalizers";
+import type { OptionWithLink } from "typings/custom";
 
 declare global {
     interface Window {
@@ -37,7 +40,10 @@ type ReferenceConfig = {
 const SCROLL_THROTTLE_DELAY = 50;
 const ELEMENT_TIMEOUT = 10000;
 const ELEMENT_CHECK_INTERVAL = 100;
-const REFERENCES_SEGMENT = "/references/";
+const DEFAULT_PROJECT_TITLE = "All Reference";
+const BACK_TARGET_STORAGE_KEY = "redoc-back-target";
+const DOCS_PATH_SEGMENT = "docs";
+const DEFAULT_LOCALE = "en-us";
 
 export default class RedocReference extends LightningElement {
     private _referenceConfig: ReferenceConfig = { refList: [] };
@@ -47,6 +53,7 @@ export default class RedocReference extends LightningElement {
     private docHeaderElement: Element | null = null;
     private docPhaseWrapperElement: Element | null = null;
     private lastSidebarTop = 0;
+    private _languages: OptionWithLink[] = [];
 
     /**
      * History length captured at mount (pre-Redoc), used by `onBackClick` to
@@ -91,19 +98,86 @@ export default class RedocReference extends LightningElement {
      * 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";
+    @api
+    get projectTitle(): string | null {
+        return this.isDocContentType
+            ? this._projectTitle
+            : DEFAULT_PROJECT_TITLE;
+    }
+    set projectTitle(value: string | null) {
+        this._projectTitle = value;
+    }
+    private _projectTitle: string | null = null;
+
+    /**
+     * Href to navigate to when the back link is clicked AND there is no
+     * usable referrer (e.g. the user opened the page directly in a fresh
+     * tab).
+     */
+    @api headerHref: string | null = null;
+
+    @api
+    get contentType(): string {
+        return this._contentType;
+    }
+    set contentType(value: string) {
+        this._contentType = value;
+    }
+    private _contentType: string = "";
+
+    @api
+    get languages(): OptionWithLink[] {
+        return this._languages;
+    }
+    set languages(value: string | OptionWithLink[]) {
+        this._languages = toJson(value) || [];
+    }
+
+    @api language: string | null = null;
 
     get specTitle(): string | null {
         return this.getSelectedReference()?.title ?? null;
     }
 
+    get isDocContentType(): boolean {
+        return this.contentType === "docs";
+    }
+
+    get isReferenceContentType(): boolean {
+        return this.contentType === "references";
+    }
+
+    get isMultiSpecSet(): boolean {
+        const refCount = this.referenceConfig?.refList?.length ?? 0;
+        return refCount > 1;
+    }
+
+    // Reads stored back target
+    private getBackTargetFromSession(): string | null {
+        return sessionStorage.getItem(BACK_TARGET_STORAGE_KEY);
+    }
+
+    private setBackTargetInSession(href: string): void {
+        sessionStorage.setItem(BACK_TARGET_STORAGE_KEY, href);
+    }
+
+    /**
+     * when more than one localized spec is available
+     */
+    get hasLocalePicker(): boolean {
+        return this.languages.length > 1;
+    }
+
     /**
-     * Whether to show the project header (only for multi-spec reference sets).
+     * Whether to show the project header. Shown for multi-spec reference
+     * sets, and for any docs-content spec topic so it always has a back
+     * link.
      */
     get showRedocHeader(): boolean {
-        const refCount = this._referenceConfig?.refList?.length ?? 0;
-        const isMultiSpecSet = refCount > 1;
-        return isMultiSpecSet && !!(this.projectTitle || this.specTitle);
+        return (
+            (this.isReferenceContentType && this.isMultiSpecSet) ||
+            this.isDocContentType
+        );
     }
 
     /**
@@ -111,16 +185,68 @@ export default class RedocReference extends LightningElement {
      */
     private onBackClick = (event: Event): void => {
         event.preventDefault();
+
+        const target = this.getTranslatedBackTarget() ?? this.headerHref;
+
+        if (target) {
+            window.location.assign(target);
+        }
+    };
+
+    private getTranslatedBackTarget(): string | null {
+        const stored = this.getBackTargetFromSession();
+        if (stored) {
+            return this.language
+                ? this.translateToCurrentLocale(stored)
+                : stored;
+        }
+
+        const referrer = this.getSameOriginReferrerHref();
+        return referrer && !this.isLocaleHref(new URL(referrer).pathname)
+            ? referrer
+            : null;
+    }
+
+    /* The locale segment sits after "docs" for docs pages,
+     * and after the product segment for references.
+     */
+    private translateToCurrentLocale(storedHref: string): string {
+        const url = new URL(storedHref, window.location.origin);
+        const localeIds = this.languages.map((loc) => loc.id);
+        const segments = url.pathname.split("/").filter(Boolean);
+
+        // docs -> right after "docs"; references -> after the product segment.
+        const localeIndex = this.isDocContentType ? 1 : 2;
+
+        if (segments[0] === DOCS_PATH_SEGMENT) {
+            // Drop the existing locale segment, if any
+            if (localeIds.includes(segments[localeIndex])) {
+                segments.splice(localeIndex, 1);
+            }
+            // Add the current locale
+            if (this.language && this.language !== DEFAULT_LOCALE) {
+                segments.splice(localeIndex, 0, this.language);
+            }
+        }
+
+        url.pathname = "/" + segments.join("/");
+        return url.href;
+    }
+
+    // Preserves target across locale switches, updates on normal navigation
+    private trackBackTarget(): void {
         const referrerHref = this.getSameOriginReferrerHref();
-        if (referrerHref) {
-            window.location.href = referrerHref;
+        if (!referrerHref) {
             return;
         }
-        const fallbackHref = this.getReferencesRootHref();
-        if (fallbackHref) {
-            window.location.href = fallbackHref;
+
+        const referrerUrl = new URL(referrerHref);
+        if (this.isLocaleHref(referrerUrl.pathname)) {
+            return;
         }
-    };
+
+        this.setBackTargetInSession(referrerHref);
+    }
 
     /**
      * Returns the referrer URL when the page was reached via in-tab navigation
@@ -144,16 +270,16 @@ export default class RedocReference extends LightningElement {
     }
 
     /**
-     * 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.
+     * switching locale on this same page.
      */
-    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);
+    private isLocaleHref(pathname: string): boolean {
+        return this.languages.some((locale) => {
+            const href = locale?.link?.href;
+            return (
+                !!href &&
+                new URL(href, window.location.origin).pathname === pathname
+            );
+        });
     }
 
     /** When origin is provided, pass it to the footer; otherwise use dx-footer's default. */
@@ -168,6 +294,9 @@ export default class RedocReference extends LightningElement {
         // so it reflects real in-tab navigation rather than Redoc's churn.
         this.initialHistoryLength = window.history.length;
 
+        // Track the back target, preserving it across locale switches
+        this.trackBackTarget();
+
         window.addEventListener("scroll", this.handleScrollAndResize);
         window.addEventListener("resize", this.handleScrollAndResize);
     }
@@ -394,7 +523,7 @@ export default class RedocReference extends LightningElement {
             this.appendFooterItems(apiContentDiv);
 
             // Inject the multi-spec project header into Redoc's left menu only.
-            this.insertProjectHeaderInMenu(redocContainer);
+            this.insertSidebarNav(redocContainer);
 
             // Wait for footer to be rendered before updating styles
             requestAnimationFrame(() => {
@@ -409,22 +538,46 @@ export default class RedocReference extends LightningElement {
     }
 
     /**
-     * Inserts the project header into Redoc for multi-spec reference sets.
+     * Inserts the project header and LNB footer into Redoc.
      */
-    private insertProjectHeaderInMenu(redocContainer: HTMLElement): void {
-        if (!this.showRedocHeader) {
-            return;
+    private insertSidebarNav(redocContainer: HTMLElement): void {
+        // Select the LNB and content area of Redoc and insert the requried header.
+        if (this.showRedocHeader) {
+            redocContainer
+                .querySelectorAll<HTMLElement>(".menu-content, .api-content")
+                .forEach((target) => {
+                    target.insertBefore(
+                        this.buildProjectHeaderDom(),
+                        target.firstChild
+                    );
+                });
         }
 
-        // 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
-                );
-            });
+        // Locale picker
+        if (this.hasLocalePicker) {
+            const menuContent = redocContainer.querySelector(".menu-content");
+            menuContent?.appendChild(this.buildLocalePickerDom());
+        }
+    }
+
+    /**
+     * Builds the locale picker DOM by reusing `dx-sidebar-footer-nav`
+     */
+    private buildLocalePickerDom(): HTMLElement {
+        const wrapper = document.createElement("div");
+        wrapper.className = "redoc-footer-nav";
+
+        const picker = createElement("dx-sidebar-footer-nav", {
+            is: SidebarFooterNav
+        });
+
+        Object.assign(picker, {
+            languages: this.languages,
+            language: this.language
+        });
+        wrapper.appendChild(picker);
+
+        return wrapper;
     }
 
     /**

package/src/modules/doc/unifiedContentLayout/unifiedContentLayout.css

@@ -0,0 +1,19 @@
+:host {
+    display: block;
+}
+
+.content-type-docs doc-phase {
+    --doc-c-phase-top: calc(
+        var(--dx-g-global-header-height) + var(--dx-g-doc-header-height) +
+            var(--dx-g-spacing-xl)
+    );
+}
+
+@media screen and (max-width: 768px) {
+    .content-type-docs doc-phase {
+        --doc-c-phase-top: calc(
+            var(--dx-g-global-header-height) + var(--dx-g-doc-header-height) +
+                40px
+        );
+    }
+}

package/src/modules/doc/unifiedContentLayout/unifiedContentLayout.html

@@ -0,0 +1,29 @@
+<template>
+    <doc-content-layout
+        class="content-type content-type-markdown content-type-docs"
+        breadcrumbs={breadcrumbs}
+        share-title={shareTitle}
+        share-twitter-via={twitterVia}
+        sidebar-header={sidebarHeader}
+        sidebar-value={sidebarValue}
+        sidebar-content={sidebarContent}
+        toc-title={tocTitle}
+        toc-options={tocOptions}
+        toc-aria-level={tocAriaLevel}
+        enable-slot-change="true"
+        languages={languages}
+        language={language}
+        show-footer={enableFooter}
+        show-content-action-toolbar={showContentActionToolbar}
+        origin={origin}
+        dev-center={devCenter}
+        brand={brand}
+    >
+        <doc-phase
+            slot="doc-phase"
+            lwc:if={docPhaseInfo}
+            doc-phase-info={docPhaseInfo}
+        ></doc-phase>
+        <slot></slot>
+    </doc-content-layout>
+</template>

package/src/modules/doc/unifiedContentLayout/unifiedContentLayout.ts

@@ -0,0 +1,88 @@
+import { LightningElement, api } from "lwc";
+import { toJson } from "dxUtils/normalizers";
+import type { OptionWithLink, TreeNode } from "typings/custom";
+
+/**
+ * Per-topic type emitted by the docs content-type parser
+ * (see @salesforcedevs/sfdocs-doc-framework: `TopicTypeEnum`). Only `spec`
+ * is meaningful inside this component; everything else renders as a plain
+ * markdown-style tile.
+ */
+const TOPIC_TYPE_SPEC = "spec";
+
+/**
+ * Translates per-topic `topicType` into the generic `showForwardArrow` flag
+ * that `dx-tree-tile` reads (spec topics get the forward arrow icon for Redoc).
+ */
+function decorateTopicsWithForwardArrow(
+    topics: Array<TreeNode & { topicType?: string }> | undefined
+): TreeNode[] | undefined {
+    return topics?.map((topic) => {
+        const { topicType, ...decorated } = topic;
+        if (topicType === TOPIC_TYPE_SPEC) {
+            decorated.showForwardArrow = true;
+        }
+        if (decorated.children) {
+            decorated.children = decorateTopicsWithForwardArrow(
+                decorated.children
+            );
+        }
+        return decorated;
+    });
+}
+
+/**
+ * Wrapper around `doc-content-layout` for the "docs" content type emitted by
+ * the `DocsContentTypeParser`.
+ */
+export default class UnifiedContentLayout extends LightningElement {
+    @api breadcrumbs: string | null = null;
+    @api sidebarHeader?: string;
+    @api sidebarValue?: string;
+    @api tocTitle?: string;
+    @api tocOptions?: string;
+    @api tocAriaLevel?: string;
+    @api languages?: OptionWithLink[];
+    @api language?: string;
+    @api devCenter: any = null;
+    @api brand: any = null;
+    @api showContentActionToolbar = false;
+
+    /** Optional origin URL for the footer MFE (e.g. wp-json endpoint). */
+    @api origin: string | null = null;
+
+    /** Article name from breadcrumbs, used as share title (e.g. for social share). */
+    @api shareTitle: string | null = null;
+
+    /** Optional Twitter "via" handle (e.g. SalesforceDevs) for social share. */
+    @api twitterVia: string | null = null;
+
+    @api hideFooter = false;
+
+    private _docPhaseInfo: string | null = null;
+    private _sidebarContent: unknown = null;
+
+    @api
+    get docPhaseInfo(): string | null {
+        return this._docPhaseInfo;
+    }
+
+    set docPhaseInfo(value: string | null) {
+        this._docPhaseInfo = value || null;
+    }
+
+    @api
+    get sidebarContent(): unknown {
+        return this._sidebarContent;
+    }
+
+    set sidebarContent(value: string) {
+        this._sidebarContent = decorateTopicsWithForwardArrow(
+            toJson(value)?.topics
+        );
+    }
+
+    private get enableFooter(): boolean {
+        return !this.hideFooter;
+    }
+}