@salesforcedevs/docs-components 1.30.1-node22-3 → 1.31.0

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

@@ -1,11 +1,15 @@
 /* eslint-disable @lwc/lwc/no-document-query */
-import { LightningElement, api, track } from "lwc";
-import { closest } from "kagekiri";
+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 } };
 
@@ -28,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;
@@ -66,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;
@@ -123,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";
@@ -173,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 (
@@ -215,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();
@@ -224,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(
@@ -239,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() {
@@ -481,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

@@ -41,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,6 +2,7 @@
 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 { throttle } from "throttle-debounce";
 import { pollUntil } from "dxUtils/async";
@@ -14,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 = {
@@ -28,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: [] };
@@ -38,6 +48,12 @@ export default class RedocReference extends LightningElement {
     private docPhaseWrapperElement: Element | null = null;
     private lastSidebarTop = 0;
 
+    /**
+     * 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;
 
     @api
@@ -71,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 (
@@ -79,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);
     }
@@ -304,6 +393,9 @@ 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);
@@ -316,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

package/src/modules/docUtils/searchClient/searchClient.ts

@@ -0,0 +1,160 @@
+// Neutral shared core for the DWO unified-search UI (P4.1).
+// The ONLY place a /api/search URL is built, and the ONLY place the HTTP
+// contract lives. No LWC / arch / dx imports — browser DOM APIs only.
+
+export interface SearchResult {
+    url: string;
+    title: string;
+    description: string | null;
+    locale: string;
+    site: string | null;
+    contentType: string | null;
+    lastmod: string | null;
+    score: number;
+    lexScore: number;
+    semScore: number;
+    matchType: string;
+}
+
+export interface FacetBucket {
+    value: string;
+    count: number;
+}
+
+export type SortOption = "relevance" | "date";
+
+export interface SearchResponse {
+    query: string;
+    locale: string;
+    site: string | null;
+    sort: SortOption;
+    limit: number;
+    offset: number;
+    total: number;
+    count: number;
+    facets: { contentType: FacetBucket[] };
+    results: SearchResult[];
+}
+
+export interface SearchRequest {
+    query: string;
+    locale: string;
+    site?: string | null;
+    type?: string | null;
+    sort?: SortOption;
+    limit?: number;
+    offset?: number;
+    page?: number;
+}
+
+export const DEFAULT_LIMIT = 20;
+
+export const SORT_OPTIONS: SortOption[] = ["relevance", "date"];
+
+export function isSortOption(v: unknown): v is SortOption {
+    return v === "relevance" || v === "date";
+}
+
+/**
+ * Build the query string for a /api/search request.
+ *  - 'q' always carries the query.
+ *  - 'lang' (lowercased) ONLY when the query has non-whitespace content.
+ *  - 'site' / 'type' ONLY when truthy.
+ *  - 'sort' ONLY when it is a known SortOption (never send an unknown sort).
+ *  - 'limit' when provided.
+ *  - OFFSET WINS OVER PAGE: if offset is given, emit it; otherwise derive
+ *    offset from page. Never emit both, and never emit 'page'.
+ */
+export function buildSearchParams(req: SearchRequest): URLSearchParams {
+    const params = new URLSearchParams();
+
+    params.set("q", req.query);
+
+    if (req.query.trim() !== "") {
+        params.set("lang", req.locale.toLowerCase());
+    }
+
+    if (req.site) {
+        params.set("site", req.site);
+    }
+    if (req.type) {
+        params.set("type", req.type);
+    }
+    if (isSortOption(req.sort)) {
+        params.set("sort", req.sort);
+    }
+    if (req.limit != null) {
+        params.set("limit", String(req.limit));
+    }
+
+    if (req.offset != null) {
+        params.set("offset", String(req.offset));
+    } else if (req.page != null) {
+        const limit = req.limit || DEFAULT_LIMIT;
+        const offset = (Math.max(1, req.page) - 1) * limit;
+        params.set("offset", String(offset));
+    }
+
+    return params;
+}
+
+export function searchUrl(
+    req: SearchRequest,
+    basePath = "/api/search"
+): string {
+    return `${basePath}?${buildSearchParams(req)}`;
+}
+
+export class SearchHttpError extends Error {
+    readonly status: number;
+
+    constructor(status: number, message?: string) {
+        super(message ?? `Search request failed with status ${status}`);
+        this.name = "SearchHttpError";
+        this.status = status;
+    }
+}
+
+export async function fetchSearch(
+    req: SearchRequest,
+    opts?: { signal?: AbortSignal; basePath?: string; fetchImpl?: typeof fetch }
+): Promise<SearchResponse> {
+    const fetchImpl = opts?.fetchImpl ?? fetch.bind(window);
+    const url = searchUrl(req, opts?.basePath);
+
+    const response = await fetchImpl(url, { signal: opts?.signal });
+
+    if (!response.ok) {
+        throw new SearchHttpError(response.status);
+    }
+
+    const data = (await response.json()) as Partial<SearchResponse>;
+
+    if (
+        !Array.isArray(data.results) ||
+        typeof data.total !== "number" ||
+        !data.facets ||
+        !Array.isArray(data.facets.contentType)
+    ) {
+        throw new Error(
+            "Malformed search response: missing results/total/facets"
+        );
+    }
+
+    return data as SearchResponse;
+}
+
+/**
+ * Decode HTML entities in a backend-supplied string (a response-normalization
+ * concern, ported from arch/searchList). No-op on plain strings.
+ */
+export function decodeHtmlEntities(value: unknown): string {
+    if (typeof value !== "string" || value.length === 0) {
+        return String(value ?? "");
+    }
+    if (!value.includes("&")) {
+        return value;
+    }
+    const doc = new DOMParser().parseFromString(value, "text/html");
+    return doc.documentElement.textContent ?? "";
+}

package/src/modules/docUtils/searchController/__mocks__/searchController.ts

@@ -0,0 +1,90 @@
+// Manual mock of SearchController for wrapper-test isolation.
+//
+// USE THE AUTOMOCK FORM — bare jest.mock with NO factory:
+//
+//   jest.mock("docUtils/searchController");
+//
+// Despite docUtils/* being remapped by jest's moduleNameMapper ($1/$2/$2),
+// jest still resolves the bare jest.mock() to this adjacent __mocks__ folder
+// (verified by probe). Do NOT use a factory that re-requires the BARE
+// specifier `docUtils/searchController/__mocks__/searchController` — the
+// mapper rewrites it to .../__mocks__/searchController/searchController and
+// jest cannot find it (also verified by probe). If a factory is ever needed,
+// use a RELATIVE require: require("../__mocks__/searchController").
+
+import type {
+    SearchControllerArgs,
+    SearchViewModel
+} from "docUtils/searchController";
+
+const baseViewModel: SearchViewModel = {
+    status: "idle",
+    query: "",
+    locale: "en-us",
+    selectedType: null,
+    sort: "relevance",
+    results: [],
+    contentTypeFacets: [],
+    total: 0,
+    count: 0,
+    limit: 20,
+    offset: 0,
+    page: 1,
+    totalPages: 1,
+    errorMessage: undefined
+};
+
+export class SearchController {
+    // eslint-disable-next-line no-use-before-define
+    static instances: SearchController[] = [];
+
+    args: SearchControllerArgs;
+    vm: SearchViewModel = { ...baseViewModel };
+    private subscribers = new Set<(vm: SearchViewModel) => void>();
+
+    init = jest.fn();
+    setQuery = jest.fn();
+    setLanguage = jest.fn();
+    setType = jest.fn();
+    setSort = jest.fn();
+    setPage = jest.fn();
+    buildUrl = jest.fn(() => "/api/search?q=&lang=en-us");
+    dispose = jest.fn();
+
+    constructor(args: SearchControllerArgs) {
+        this.args = args;
+        this.vm = {
+            ...baseViewModel,
+            locale: args.defaultLanguage ?? baseViewModel.locale,
+            limit: args.limit ?? baseViewModel.limit
+        };
+        SearchController.instances.push(this);
+    }
+
+    get viewModel(): SearchViewModel {
+        return this.vm;
+    }
+
+    get localeOptions() {
+        return this.args.catalog;
+    }
+
+    get showLocaleSelector(): boolean {
+        return this.args.catalog.length > 1;
+    }
+
+    subscribe = jest.fn((cb: (vm: SearchViewModel) => void): (() => void) => {
+        this.subscribers.add(cb);
+        return () => {
+            this.subscribers.delete(cb);
+        };
+    });
+
+    /** Test helper: push a (partial) view-model to all subscribers. */
+    __emit(vm: Partial<SearchViewModel>): void {
+        this.vm = { ...this.vm, ...vm };
+        for (const cb of this.subscribers) {
+            cb(this.vm);
+        }
+    }
+}