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

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

@@ -0,0 +1,420 @@
+// Plain (non-LWC) stateful orchestrator shared by the arch + dx search
+// wrappers. No LWC / arch / dx imports — brand specifics are injected.
+
+import {
+    DEFAULT_LIMIT,
+    fetchSearch,
+    isSortOption,
+    searchUrl,
+    SearchHttpError
+} from "docUtils/searchClient";
+import type {
+    FacetBucket,
+    SearchRequest,
+    SearchResult,
+    SortOption
+} from "docUtils/searchClient";
+import { resolveInitialLanguage } from "docUtils/searchLocale";
+import type { LocaleDeps, LocaleOption } from "docUtils/searchLocale";
+
+export type SearchStatus = "idle" | "loading" | "results" | "empty" | "error";
+
+export interface SearchViewModel {
+    status: SearchStatus;
+    query: string;
+    locale: string;
+    selectedType: string | null;
+    sort: SortOption;
+    results: SearchResult[];
+    contentTypeFacets: FacetBucket[];
+    total: number;
+    count: number;
+    limit: number;
+    offset: number;
+    page: number;
+    totalPages: number;
+    errorMessage?: string;
+}
+
+export interface SearchControllerArgs {
+    catalog: LocaleOption[];
+    defaultLanguage: string;
+    supportedIds: string[];
+    site?: string | null;
+    limit?: number;
+    basePath?: string;
+    deps: LocaleDeps;
+    instrument?: (event: string, payload: Record<string, unknown>) => void;
+    fetchImpl?: typeof fetch;
+    historyMethod?: (
+        data: unknown,
+        unused: string,
+        url?: string | null
+    ) => void;
+    debounceMs?: number;
+}
+
+export class SearchController {
+    private readonly catalog: LocaleOption[];
+    private readonly defaultLanguage: string;
+    private readonly supportedIds: string[];
+    private readonly site: string | null;
+    private readonly limit: number;
+    private readonly basePath?: string;
+    private readonly deps: LocaleDeps;
+    private readonly instrument?: SearchControllerArgs["instrument"];
+    private readonly fetchImpl: typeof fetch;
+    private readonly historyMethod: (
+        data: unknown,
+        unused: string,
+        url?: string | null
+    ) => void;
+    private readonly debounceMs: number;
+
+    // Mutable state.
+    private status: SearchStatus = "idle";
+    private query = "";
+    private locale: string;
+    private selectedType: string | null = null;
+    private sort: SortOption = "relevance";
+    private results: SearchResult[] = [];
+    private contentTypeFacets: FacetBucket[] = [];
+    private total = 0;
+    private count = 0;
+    private offset = 0;
+    private page = 1;
+    private errorMessage?: string;
+
+    private abortController?: AbortController;
+    private debounceTimer?: ReturnType<typeof setTimeout>;
+    private subscribers = new Set<(vm: SearchViewModel) => void>();
+
+    constructor(args: SearchControllerArgs) {
+        this.catalog = args.catalog;
+        this.defaultLanguage = args.defaultLanguage;
+        this.supportedIds = args.supportedIds;
+        this.site = args.site ?? null;
+        this.limit = args.limit ?? DEFAULT_LIMIT;
+        this.basePath = args.basePath;
+        this.deps = args.deps;
+        this.instrument = args.instrument;
+        this.fetchImpl = args.fetchImpl ?? fetch.bind(window);
+        this.historyMethod = (
+            args.historyMethod ?? window.history.replaceState
+        ).bind(window.history);
+        this.debounceMs = args.debounceMs ?? 250;
+        this.locale = this.defaultLanguage;
+    }
+
+    // ---- public reads -------------------------------------------------
+
+    get viewModel(): SearchViewModel {
+        return {
+            status: this.status,
+            query: this.query,
+            locale: this.locale,
+            selectedType: this.selectedType,
+            sort: this.sort,
+            results: this.results,
+            contentTypeFacets: this.contentTypeFacets,
+            total: this.total,
+            count: this.count,
+            limit: this.limit,
+            offset: this.offset,
+            page: this.page,
+            totalPages: Math.max(1, Math.ceil(this.total / this.limit)),
+            errorMessage: this.errorMessage
+        };
+    }
+
+    get localeOptions(): LocaleOption[] {
+        return this.catalog;
+    }
+
+    get showLocaleSelector(): boolean {
+        return this.catalog.length > 1;
+    }
+
+    // ---- lifecycle ----------------------------------------------------
+
+    init(): void {
+        const search = window.location.search;
+        this.locale = resolveInitialLanguage({
+            supportedIds: this.supportedIds,
+            defaultLanguage: this.defaultLanguage,
+            search,
+            navigatorLanguages:
+                typeof navigator !== "undefined"
+                    ? navigator.languages
+                    : undefined,
+            deps: this.deps
+        });
+
+        const params = new URLSearchParams(search);
+        this.query = params.get("q") ?? "";
+        this.selectedType = params.get("type") || null;
+        const rawSort = params.get("sort");
+        this.sort = isSortOption(rawSort) ? rawSort : "relevance";
+        const rawPage = parseInt(params.get("page") ?? "", 10);
+        this.page = Number.isFinite(rawPage) && rawPage >= 1 ? rawPage : 1;
+        this.offset = (this.page - 1) * this.limit;
+
+        window.addEventListener("popstate", this.handlePopState);
+
+        if (this.query.trim() !== "") {
+            this.runQuery();
+        } else {
+            // No query at boot is the resting state, not an executed empty
+            // search — keep status 'idle' so the UI can show its prompt.
+            this.status = "idle";
+            this.notify();
+        }
+    }
+
+    dispose(): void {
+        this.abortController?.abort();
+        this.abortController = undefined;
+        if (this.debounceTimer != null) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = undefined;
+        }
+        window.removeEventListener("popstate", this.handlePopState);
+        this.subscribers.clear();
+    }
+
+    // ---- subscription -------------------------------------------------
+
+    subscribe(cb: (vm: SearchViewModel) => void): () => void {
+        this.subscribers.add(cb);
+        return () => {
+            this.subscribers.delete(cb);
+        };
+    }
+
+    // ---- mutations ----------------------------------------------------
+
+    setQuery(q: string): void {
+        this.query = q;
+        this.page = 1;
+        this.offset = 0;
+
+        // Abort any prior in-flight request before scheduling/firing.
+        this.abortController?.abort();
+        this.abortController = undefined;
+        if (this.debounceTimer != null) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = undefined;
+        }
+
+        if (q.trim() === "") {
+            this.applyEmpty();
+            this.syncUrl();
+            this.notify();
+            return;
+        }
+
+        this.debounceTimer = setTimeout(() => {
+            this.debounceTimer = undefined;
+            this.syncUrl();
+            this.runQuery();
+        }, this.debounceMs);
+    }
+
+    setLanguage(id: string): void {
+        this.locale = id;
+        this.deps.setStored(id);
+        this.page = 1;
+        this.offset = 0;
+        this.syncUrl();
+        if (this.query.trim() !== "") {
+            this.runQuery();
+        } else {
+            this.applyEmpty();
+            this.notify();
+        }
+    }
+
+    setType(type: string | null): void {
+        // Disjunctive toggle: selecting the active type clears it.
+        this.selectedType = this.selectedType === type ? null : type;
+        this.page = 1;
+        this.offset = 0;
+        this.syncUrl();
+        if (this.query.trim() !== "") {
+            this.runQuery();
+        } else {
+            this.applyEmpty();
+            this.notify();
+        }
+    }
+
+    setSort(s: SortOption): void {
+        this.sort = isSortOption(s) ? s : "relevance";
+        this.page = 1;
+        this.offset = 0;
+        this.syncUrl();
+        if (this.query.trim() !== "") {
+            this.runQuery();
+        } else {
+            this.applyEmpty();
+            this.notify();
+        }
+    }
+
+    setPage(page: number): void {
+        this.page = Math.max(1, Math.floor(page));
+        this.offset = (this.page - 1) * this.limit;
+        this.syncUrl();
+        if (this.query.trim() !== "") {
+            this.runQuery();
+        } else {
+            this.applyEmpty();
+            this.notify();
+        }
+    }
+
+    // ---- URLs ---------------------------------------------------------
+
+    buildUrl(): string {
+        return searchUrl(this.currentRequest(), this.basePath);
+    }
+
+    // ---- internals ----------------------------------------------------
+
+    private currentRequest(): SearchRequest {
+        return {
+            query: this.query,
+            locale: this.locale,
+            site: this.site,
+            type: this.selectedType,
+            sort: this.sort,
+            limit: this.limit,
+            offset: this.offset
+        };
+    }
+
+    private applyEmpty(): void {
+        this.status = "empty";
+        this.total = 0;
+        this.count = 0;
+        this.results = [];
+        this.contentTypeFacets = [];
+        this.errorMessage = undefined;
+    }
+
+    private async runQuery(): Promise<void> {
+        // Empty query never fires a request.
+        if (this.query.trim() === "") {
+            this.applyEmpty();
+            this.notify();
+            return;
+        }
+
+        this.status = "loading";
+        this.errorMessage = undefined;
+        this.notify();
+
+        // Fresh controller; abort the previous one.
+        this.abortController?.abort();
+        const controller = new AbortController();
+        this.abortController = controller;
+
+        try {
+            const response = await fetchSearch(this.currentRequest(), {
+                signal: controller.signal,
+                basePath: this.basePath,
+                fetchImpl: this.fetchImpl
+            });
+
+            this.results = response.results;
+            this.contentTypeFacets = response.facets.contentType;
+            this.total = response.total;
+            this.count = response.results.length;
+            this.status = response.results.length ? "results" : "empty";
+            this.errorMessage = undefined;
+
+            if (this.instrument) {
+                this.instrument("search", {
+                    query: this.query,
+                    locale: this.locale,
+                    total: this.total
+                });
+            }
+
+            this.notify();
+        } catch (error) {
+            // A superseded/disposed request is not an error.
+            if (error instanceof Error && error.name === "AbortError") {
+                return;
+            }
+            this.status = "error";
+            this.errorMessage =
+                error instanceof SearchHttpError
+                    ? `Search failed (status ${error.status})`
+                    : error instanceof Error
+                    ? error.message
+                    : "Search failed";
+            this.notify();
+        }
+    }
+
+    private syncUrl(): void {
+        const params = new URLSearchParams(window.location.search);
+
+        if (this.query.trim() !== "") {
+            params.set("q", this.query);
+        } else {
+            params.delete("q");
+        }
+
+        params.set("lang", this.locale.toLowerCase());
+
+        if (this.selectedType) {
+            params.set("type", this.selectedType);
+        } else {
+            params.delete("type");
+        }
+
+        if (this.sort && this.sort !== "relevance") {
+            params.set("sort", this.sort);
+        } else {
+            params.delete("sort");
+        }
+
+        if (this.page > 1) {
+            params.set("page", String(this.page));
+        } else {
+            params.delete("page");
+        }
+
+        const url = new URL(window.location.href);
+        url.search = params.toString();
+        this.historyMethod({}, "", url.toString());
+    }
+
+    private notify(): void {
+        const vm = this.viewModel;
+        for (const cb of this.subscribers) {
+            cb(vm);
+        }
+    }
+
+    private handlePopState = (): void => {
+        const search = window.location.search;
+        const params = new URLSearchParams(search);
+        this.query = params.get("q") ?? "";
+        this.selectedType = params.get("type") || null;
+        const rawSort = params.get("sort");
+        this.sort = isSortOption(rawSort) ? rawSort : "relevance";
+        const rawPage = parseInt(params.get("page") ?? "", 10);
+        this.page = Number.isFinite(rawPage) && rawPage >= 1 ? rawPage : 1;
+        this.offset = (this.page - 1) * this.limit;
+
+        if (this.query.trim() !== "") {
+            this.runQuery();
+        } else {
+            this.applyEmpty();
+            this.notify();
+        }
+    };
+}

package/src/modules/docUtils/searchLocale/searchLocale.ts

@@ -0,0 +1,85 @@
+// Brand-neutral locale cascade for the DWO unified-search UI (P4.1).
+// Lifted from arch/searchList (parseSupportedLocales + resolveInitialLanguage),
+// with browser-match and consent-gated storage INJECTED so the core never
+// imports arch/* or dx/*.
+
+export interface LocaleOption {
+    id: string;
+    displayText?: string;
+    label?: string;
+}
+
+export interface LocaleDeps {
+    getStored: () => string | null;
+    setStored: (v: string) => boolean;
+    resolveBrowser: (
+        langs: readonly string[] | undefined,
+        ids: string[]
+    ) => string;
+}
+
+export const DEFAULT_LANGUAGE = "en-us";
+
+/**
+ * Parse an injected locale catalog (a JSON string), restricting to entries
+ * with a string id. Returns [] on bad / non-array JSON.
+ */
+export function parseSupportedLocales(json: string): LocaleOption[] {
+    if (!json) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(json);
+        if (!Array.isArray(parsed)) {
+            return [];
+        }
+        return parsed.filter(
+            (entry): entry is LocaleOption =>
+                !!entry && typeof entry.id === "string"
+        );
+    } catch (e) {
+        return [];
+    }
+}
+
+/**
+ * Resolve the language to search in, most-explicit-wins:
+ *   1. ?lang= URL param (shared/bookmarked links)
+ *   2. stored preference (consented, from a prior visit)
+ *   3. browser preferred language mapped to a supported id
+ *   4. the page's server locale, else en-us
+ * Any candidate must be in the supported catalog (when one was provided).
+ * An unsupported ?lang is IGNORED (we fall through to the next candidate).
+ */
+export function resolveInitialLanguage(args: {
+    supportedIds: string[];
+    defaultLanguage: string;
+    search: string;
+    navigatorLanguages: readonly string[] | undefined;
+    deps: LocaleDeps;
+}): string {
+    const { supportedIds, defaultLanguage, search, navigatorLanguages, deps } =
+        args;
+    const ids = supportedIds;
+    const isSupported = (value: string | null | undefined): boolean =>
+        !!value && (ids.length === 0 || ids.includes(value));
+
+    const fromUrl = new URLSearchParams(search).get("lang");
+    if (isSupported(fromUrl)) {
+        return fromUrl as string;
+    }
+
+    const stored = deps.getStored();
+    if (isSupported(stored)) {
+        return stored as string;
+    }
+
+    if (ids.length > 0) {
+        const detected = deps.resolveBrowser(navigatorLanguages, ids);
+        if (isSupported(detected)) {
+            return detected;
+        }
+    }
+
+    return isSupported(defaultLanguage) ? defaultLanguage : DEFAULT_LANGUAGE;
+}

package/LICENSE

@@ -1,12 +0,0 @@
-Copyright (c) 2020, Salesforce.com, Inc.
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-
-* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-
-* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-
-* Neither the name of Salesforce.com nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.