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

package/lwc.config.json

@@ -27,6 +27,9 @@
         "doc/specificationContent",
         "doc/versionPicker",
         "doc/xmlContent",
+        "docUtils/searchClient",
+        "docUtils/searchController",
+        "docUtils/searchLocale",
         "docUtils/utils"
     ]
 }

package/package.json

@@ -1,29 +1,29 @@
 {
-    "name": "@salesforcedevs/docs-components",
-    "version": "1.30.1",
-    "description": "Docs Lightning web components for DSC",
-    "license": "MIT",
-    "main": "index.js",
-    "engines": {
-        "node": "22.x"
-    },
-    "publishConfig": {
-        "access": "public"
-    },
-    "dependencies": {
-        "@api-components/amf-helper-mixin": "4.5.29",
-        "classnames": "2.5.1",
-        "dompurify": "3.2.4",
-        "kagekiri": "1.4.2",
-        "lodash.orderby": "4.6.0",
-        "lodash.uniqby": "4.7.0",
-        "query-string": "7.1.3",
-        "sentence-case": "3.0.4"
-    },
-    "devDependencies": {
-        "@types/classnames": "2.3.1",
-        "@types/lodash.orderby": "4.6.9",
-        "@types/lodash.uniqby": "4.7.9"
-    },
-    "gitHead": "1ef01ecd6afcd77c06384577bbf7afa48907d82a"
-}
+  "name": "@salesforcedevs/docs-components",
+  "version": "1.31.0-md-alpha",
+  "description": "Docs Lightning web components for DSC",
+  "license": "MIT",
+  "main": "index.js",
+  "engines": {
+    "node": "22.x"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@api-components/amf-helper-mixin": "4.5.29",
+    "classnames": "2.5.1",
+    "dompurify": "3.2.4",
+    "kagekiri": "1.4.2",
+    "lodash.orderby": "4.6.0",
+    "lodash.uniqby": "4.7.0",
+    "query-string": "7.1.3",
+    "sentence-case": "3.0.4"
+  },
+  "devDependencies": {
+    "@types/classnames": "2.3.1",
+    "@types/lodash.orderby": "4.6.9",
+    "@types/lodash.uniqby": "4.7.9"
+  },
+  "gitHead": "4629fdd9ca18a13480044ad43515b91945d16aad"
+}

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

@@ -10,6 +10,8 @@ import ContentActionToolbar from "doc/contentActionToolbar";
 
 const CONTENT_ACTION_TOOLBAR_TAG = "doc-content-action-toolbar";
 const PAGE_HEADING_SELECTOR = "h1";
+const FALLBACK_HEADING_SELECTOR = "h1, h2, h3, h4, h5, h6";
+const CONTENT_BODY_SELECTOR = ".content-body-container .content-body";
 
 type AnchorMap = { [key: string]: { intersect: boolean; id: string } };
 
@@ -286,7 +288,8 @@ export default class ContentLayout extends LightningElement {
 
     /**
      * Inserts the content action toolbar into the slotted content immediately
-     * after the first H1 found inside this layout.
+     * after the first H1 found inside this layout, falling back to the first
+     * heading of any level if no H1 exists.
      */
     protected updateContentActionToolbar(): void {
         if (!this.showContentActionToolbar || !this.sidebarValue) {
@@ -294,11 +297,21 @@ export default class ContentLayout extends LightningElement {
             return;
         }
 
-        const heading = querySelector(
-            PAGE_HEADING_SELECTOR,
+        const contentBody = querySelector(
+            CONTENT_BODY_SELECTOR,
             this.template.host
         ) as HTMLElement | null;
 
+        if (!contentBody) {
+            return;
+        }
+
+        const heading = (querySelector(PAGE_HEADING_SELECTOR, contentBody) ??
+            querySelector(
+                FALLBACK_HEADING_SELECTOR,
+                contentBody
+            )) as HTMLElement | null;
+
         if (!heading) {
             return;
         }

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

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.