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

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/.npmrc

@@ -1 +0,0 @@
-//registry.npmjs.org/:_authToken=${SFDOCS_NPM_AUTH_TOKEN}