@salesforcedevs/docs-components 1.32.0-alpha.9 → 1.32.0-docs-content-type-1

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

@@ -1,12 +1,15 @@
 /* eslint-disable @lwc/lwc/no-document-query */
-import { LightningElement, api, track } from "lwc";
-import { closest } from "kagekiri";
-import { fetchHasResults } from "dxUtils/data360Search";
+import { LightningElement, api, createElement, track } from "lwc";
+import { closest, querySelector } from "kagekiri";
 import { toJson, normalizeBoolean } from "dxUtils/normalizers";
 import { highlightTerms } from "dxUtils/highlight";
 import { SearchSyncer } from "docUtils/searchSyncer";
 import type { OptionWithLink } from "typings/custom";
 import { buildDocLinkClickHandler } from "dxUtils/analytics";
+import ContentActionToolbar from "doc/contentActionToolbar";
+
+const CONTENT_ACTION_TOOLBAR_TAG = "doc-content-action-toolbar";
+const PAGE_HEADING_SELECTOR = "h1";
 
 type AnchorMap = { [key: string]: { intersect: boolean; id: string } };
 
@@ -29,6 +32,35 @@ const HIGHLIGHTABLE_SELECTOR = [
 ].join(",");
 export const OBSERVER_ATTACH_WAIT_TIME = 500;
 
+const DEFAULT_READING_TIME_LOCALE = "en-us";
+
+/**
+ * Localized "minute read" templates. `{minutes}` is replaced with the rounded
+ * reading-time value. Only displayed when reading time is greater than 1, so
+ * plural forms are always appropriate. Keys match the locales declared in
+ * sfdocs (and the doc-locale-banner) so that a localized document automatically
+ * gets a localized reading-time label.
+ */
+export const READING_TIME_LABELS: Record<string, string> = {
+    "en-us": "{minutes} minute read",
+    "ja-jp": "読了時間 {minutes} 分",
+    "zh-cn": "阅读时间 {minutes} 分钟",
+    "zh-tw": "閱讀時間 {minutes} 分鐘",
+    "fr-fr": "Lecture de {minutes} minutes",
+    "de-de": "{minutes} Minuten Lesezeit",
+    "it-it": "{minutes} minuti di lettura",
+    "ko-kr": "읽는 데 {minutes}분",
+    "pt-br": "{minutes} minutos de leitura",
+    "es-mx": "{minutes} minutos de lectura",
+    "es-es": "{minutes} minutos de lectura",
+    "ru-ru": "Время чтения: {minutes} мин",
+    "fi-fi": "{minutes} minuutin lukuaika",
+    "da-dk": "{minutes} minutters læsning",
+    "sv-se": "{minutes} minuters läsning",
+    "nl-nl": "{minutes} minuten leestijd",
+    "nb-no": "{minutes} minutters lesetid"
+};
+
 export default class ContentLayout extends LightningElement {
     @api sidebarValue!: string;
     @api sidebarHeader!: string;
@@ -43,15 +75,6 @@ export default class ContentLayout extends LightningElement {
     @api brand: any;
     @api emptyStateMessage?: string;
 
-    @api
-    get enableDataCloudSearch() {
-        return this._enableDataCloudSearch;
-    }
-    set enableDataCloudSearch(value) {
-        this._enableDataCloudSearch = normalizeBoolean(value);
-    }
-    private _enableDataCloudSearch = false;
-
     // This is needed for now to prevent failing snapshot tests due to links in the footer
     @api
     get showFooter() {
@@ -76,6 +99,17 @@ export default class ContentLayout extends LightningElement {
     /** Optional origin URL for the footer MFE (e.g. wp-json endpoint). Passed through to dx-footer. */
     @api origin: string | null = null;
 
+    /** Controls whether the content action toolbar is displayed. */
+    @api
+    get showContentActionToolbar() {
+        return this._showContentActionToolbar;
+    }
+    set showContentActionToolbar(value) {
+        this._showContentActionToolbar = normalizeBoolean(value);
+        this.updateContentActionToolbar();
+    }
+    private _showContentActionToolbar = false;
+
     @api
     get breadcrumbs() {
         return this._breadcrumbs;
@@ -118,35 +152,9 @@ export default class ContentLayout extends LightningElement {
         );
     }
 
-    /** Show Data 360 sidebar only when not using old sidebar and the page has searchable results. */
-    protected get showDataCloudSidebar(): boolean {
-        return (
-            this.enableDataCloudSearch &&
-            !this.useOldSidebar &&
-            this.hasDataCloudResults === true
-        );
-    }
-
-    /** Show legacy sidebar when explicitly requested or when Data 360 has no results. Don't show until we know (avoids flash). */
-    protected get showOldSidebar(): boolean {
-        return (
-            this.useOldSidebar === true ||
-            !this.enableDataCloudSearch ||
-            this.hasDataCloudResults === false
-        );
-    }
-
-    /** Show a space-holding placeholder while we're deciding which sidebar to show (avoids layout shift). */
-    protected get showSidebarPlaceholder(): boolean {
-        return !this.showDataCloudSidebar && !this.showOldSidebar;
-    }
-
     @track
     protected _sidebarContent: unknown;
 
-    @track
-    protected hasDataCloudResults: boolean | null = null;
-
     protected _breadcrumbs = null;
 
     @track
@@ -159,6 +167,7 @@ export default class ContentLayout extends LightningElement {
     protected hasRendered: boolean = false;
     protected contentLoaded: boolean = false;
     protected sidebarOpen: boolean = false;
+    protected contentActionToolbarElement: HTMLElement | null = null;
 
     get shouldDisplayFeedback() {
         return this.contentLoaded && typeof Sprig !== "undefined";
@@ -209,6 +218,19 @@ export default class ContentLayout extends LightningElement {
         return this.readingTime != null && this.readingTime > 1;
     }
 
+    /**
+     * Localized "X minute read" string for the current document language.
+     * Falls back to the default (en-us) template when the language is missing
+     * or has no translation.
+     */
+    get readingTimeLabel(): string {
+        const localeKey = (this.language || "").toLowerCase();
+        const template =
+            READING_TIME_LABELS[localeKey] ||
+            READING_TIME_LABELS[DEFAULT_READING_TIME_LOCALE];
+        return template.replace("{minutes}", String(this.readingTime));
+    }
+
     /** When origin is provided, pass it to the footer; otherwise use dx-footer's default. */
     get effectiveFooterOrigin(): string {
         return (
@@ -217,11 +239,6 @@ export default class ContentLayout extends LightningElement {
     }
 
     connectedCallback(): void {
-        if (this.enableDataCloudSearch && !this.useOldSidebar) {
-            fetchHasResults().then((hasResults: boolean) => {
-                this.hasDataCloudResults = hasResults;
-            });
-        }
         const hasParentHighlightListener = closest(
             "doc-xml-content",
             this.template.host
@@ -256,6 +273,8 @@ export default class ContentLayout extends LightningElement {
         window.addEventListener("scroll", this.adjustNavPosition);
         window.addEventListener("resize", this.adjustNavPosition);
 
+        this.updateContentActionToolbar();
+
         if (!this.hasRendered) {
             this.hasRendered = true;
             this.restoreScroll();
@@ -265,6 +284,43 @@ export default class ContentLayout extends LightningElement {
         }
     }
 
+    /**
+     * Inserts the content action toolbar into the slotted content immediately
+     * after the first H1 found inside this layout.
+     */
+    protected updateContentActionToolbar(): void {
+        if (!this.showContentActionToolbar || !this.sidebarValue) {
+            this.removeContentActionToolbar();
+            return;
+        }
+
+        const heading = querySelector(
+            PAGE_HEADING_SELECTOR,
+            this.template.host
+        ) as HTMLElement | null;
+
+        if (!heading) {
+            return;
+        }
+
+        const toolbar = (this.contentActionToolbarElement ??
+            createElement(CONTENT_ACTION_TOOLBAR_TAG, {
+                is: ContentActionToolbar
+            })) as HTMLElement & { pageUrl?: string };
+
+        toolbar.pageUrl = this.sidebarValue;
+
+        if (toolbar.previousElementSibling !== heading) {
+            heading.parentNode?.insertBefore(toolbar, heading.nextSibling);
+        }
+
+        this.contentActionToolbarElement = toolbar;
+    }
+
+    protected removeContentActionToolbar(): void {
+        this.contentActionToolbarElement?.remove();
+    }
+
     disconnectedCallback(): void {
         this.disconnectObserver();
         window.removeEventListener(
@@ -280,6 +336,9 @@ export default class ContentLayout extends LightningElement {
 
         // Remove link click handler
         this.template.removeEventListener("click", this.handleLinkClick);
+
+        this.removeContentActionToolbar();
+        this.contentActionToolbarElement = null;
     }
 
     restoreScroll() {
@@ -298,9 +357,7 @@ export default class ContentLayout extends LightningElement {
         We have to account for the global nav changing height due to animations.
     */
     adjustNavPosition = () => {
-        const sidebarEl =
-            this.template.querySelector("dx-sidebar") ||
-            this.template.querySelector("dx-sidebar-old");
+        const sidebarEl = this.template.querySelector("dx-sidebar-old");
         const globalNavEl = document.querySelector(
             "hgf-c360nav"
         ) as HTMLElement;
@@ -524,6 +581,7 @@ export default class ContentLayout extends LightningElement {
 
     onSlotChange(): void {
         this.updateRNB();
+        this.updateContentActionToolbar();
         this.contentLoaded = true;
     }
 

package/src/modules/doc/header/header.html

@@ -13,7 +13,6 @@
                         onclick={onLinkClick}
                         class="dev-center-content"
                     >
-                        <dx-icon symbol="back"></dx-icon>
                         <dx-icon
                             class="brand-icon"
                             lwc:if={devCenter.icon}

package/src/modules/doc/lwcContentLayout/lwcContentLayout.html

@@ -1,7 +1,6 @@
 <template>
     <div class="content">
         <dx-sidebar-old
-            lwc:if={useOldSidebar}
             class="is-sticky left-nav-bar"
             trees={sidebarContent}
             value={sidebarValue}
@@ -16,16 +15,6 @@
         >
             <slot name="sidebar-header" slot="version-picker"></slot>
         </dx-sidebar-old>
-        <dx-sidebar
-            lwc:else
-            class="is-sticky left-nav-bar"
-            trees={sidebarContent}
-            value={sidebarValue}
-            header={sidebarHeader}
-            ontogglesidebar={onToggleSidebar}
-        >
-            <slot name="sidebar-header" slot="version-picker"></slot>
-        </dx-sidebar>
         <div class="content-body-doc-phase-container">
             <div class="doc-phase-wrapper">
                 <slot name="doc-phase"></slot>
@@ -52,7 +41,7 @@
                                 ></path>
                             </g>
                         </svg>
-                        {readingTime} minute read
+                        {readingTimeLabel}
                     </div>
                     <slot onslotchange={onSlotChange}></slot>
                     <doc-sprig-survey

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

@@ -2,9 +2,13 @@
 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 {
@@ -14,11 +18,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 = {
@@ -28,6 +40,10 @@ type ReferenceConfig = {
 const SCROLL_THROTTLE_DELAY = 50;
 const ELEMENT_TIMEOUT = 10000;
 const ELEMENT_CHECK_INTERVAL = 100;
+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: [] };
@@ -37,6 +53,13 @@ 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
+     * distinguish in-tab navigation (> 1) from a fresh entry (=== 1).
+     */
+    private initialHistoryLength = 0;
 
     showError = false;
 
@@ -71,6 +94,194 @@ 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
+    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. Shown for multi-spec reference
+     * sets, and for any docs-content spec topic so it always has a back
+     * link.
+     */
+    get showRedocHeader(): boolean {
+        return (
+            (this.isReferenceContentType && this.isMultiSpecSet) ||
+            this.isDocContentType
+        );
+    }
+
+    /**
+     * Navigates back to reference doc.
+     */
+    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) {
+            return;
+        }
+
+        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
+     * 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;
+        }
+    }
+
+    /**
+     * switching locale on this same page.
+     */
+    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. */
     get effectiveFooterOrigin(): string {
         return (
@@ -79,6 +290,13 @@ 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;
+
+        // Track the back target, preserving it across locale switches
+        this.trackBackTarget();
+
         window.addEventListener("scroll", this.handleScrollAndResize);
         window.addEventListener("resize", this.handleScrollAndResize);
     }
@@ -304,6 +522,9 @@ export default class RedocReference extends LightningElement {
 
             this.appendFooterItems(apiContentDiv);
 
+            // Inject the multi-spec project header into Redoc's left menu only.
+            this.insertSidebarNav(redocContainer);
+
             // Wait for footer to be rendered before updating styles
             requestAnimationFrame(() => {
                 this.updateRedocThirdColumnStyle(redocContainer);
@@ -316,6 +537,89 @@ export default class RedocReference extends LightningElement {
         }
     }
 
+    /**
+     * Inserts the project header and LNB footer into Redoc.
+     */
+    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
+                    );
+                });
+        }
+
+        // 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;
+    }
+
+    /**
+     * 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

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,28 @@
+<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}
+        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>