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

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

@@ -0,0 +1,87 @@
+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;
+
+    /** 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;
+    }
+}

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

@@ -2,7 +2,6 @@
     <doc-content-layout
         lwc:if={displayContent}
         lwc:ref="docContentLayout"
-        enable-data-cloud-search
         sidebar-header={docTitle}
         sidebar-content={sidebarContent}
         sidebar-value={sidebarValue}

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

@@ -254,6 +254,17 @@ export default class DocXmlContent extends LightningElementWithState<{
         return this.pageReference.deliverable;
     }
 
+    private get useOldSidebar(): boolean {
+        // Coveo is enabled and the version is greater than  51 (within the latest 3 versions)
+        // TODO: we need a better fix for version number check
+        return !(
+            !this.version?.releaseVersion ||
+            (this.version?.releaseVersion &&
+                parseInt(this.version.releaseVersion.replace("v", ""), 10) >=
+                    53)
+        );
+    }
+
     private get pageHeader(): Header {
         if (!this._pageHeader) {
             this._pageHeader = document.querySelector("doc-header")!;

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);
+        }
+    }
+}