@salesforcedevs/dx-components 1.33.1 → 1.35.0

package/lwc.config.json

@@ -86,6 +86,7 @@
         "dx/redirectChecker",
         "dx/relativeDateTime",
         "dx/scrollManager",
+        "dx/searchHybrid",
         "dx/searchResults",
         "dx/section",
         "dx/sectionBanner",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@salesforcedevs/dx-components",
-    "version": "1.33.1",
+    "version": "1.35.0",
     "description": "DX Lightning web components",
     "license": "MIT",
     "engines": {
@@ -44,5 +44,5 @@
         "luxon": "3.4.4",
         "msw": "^2.12.4"
     },
-    "gitHead": "326cef8d08d8563c98e58e757cbd40b6a06878e5"
+    "gitHead": "7f00db154db1ca528e2bed2c33226a3ff674cd17"
 }

package/src/modules/dx/agentMiawUi/agentMiawUi.ts

@@ -57,6 +57,24 @@ function loadMiawUiScript(): Promise<void> {
     return scriptLoaded;
 }
 
+function dropCookie(cookieDomain: string) {
+    const { hostname, protocol } = window.location;
+    const onCookieDomain =
+        !!cookieDomain &&
+        (hostname === cookieDomain || hostname.endsWith(`.${cookieDomain}`));
+
+    document.cookie = [
+        "show_agent=true",
+        "Path=/",
+        "Max-Age=2592000",
+        "SameSite=Lax",
+        protocol === "https:" ? "Secure" : null,
+        onCookieDomain ? `Domain=${cookieDomain}` : null
+    ]
+        .filter(Boolean)
+        .join("; ");
+}
+
 export default class AgentMiawUi extends LightningElement {
     private static readonly SIDEBAR_OPEN_ATTR = "data-xsf-agent-sidebar-open";
     private static readonly AGENT_ROOT_SELECTOR = '[data-testid="agent-root"]';
@@ -78,6 +96,16 @@ export default class AgentMiawUi extends LightningElement {
     /** When set, forwarded to the embed as `welcome-text` (greeting / headline copy). */
     @api welcomeText?: string;
     @api agentforceEnv?: string;
+    /**
+     * When true, mounting of the agent is gated behind the `showAgent=true` query param
+     * or `show_agent=true` cookie opt-in; otherwise (and by default), gating is off.
+     */
+    @api hideAgentConditionally: boolean = false;
+    /**
+     * Apex domain that the opt-in cookie targets (covers subdomains); applied only when the
+     * current host matches it, so local dev / preview hosts fall back to a host-only cookie.
+     */
+    @api cookieDomain?: string;
 
     /** After first mount attempt is scheduled, we do not run it again for this instance. */
     private hasRendered = false;
@@ -87,7 +115,9 @@ export default class AgentMiawUi extends LightningElement {
     renderedCallback(): void {
         if (!this.hasRendered) {
             this.hasRendered = true;
-            this.mountMiawHost();
+            if (this.shouldMount()) {
+                this.mountMiawHost();
+            }
         }
     }
 
@@ -96,6 +126,39 @@ export default class AgentMiawUi extends LightningElement {
         this.sidebarStateObserver = null;
     }
 
+    /**
+     * Decide whether the agent should mount. If conditional gating is off, always mount.
+     * If conditional gating of the agent is on, return `true` only when the user has opted in
+     * via the `showAgent=true` query param or the `show_agent=true` cookie. (When only the
+     * param is present, persists a sticky opt-in cookie (~30 days) as a side effect so the
+     * choice carries across pages and subdomains.)
+     *
+     * CROSS-SITE CONTRACT: the param key/value, cookie token, Max-Age, SameSite, Secure and
+     * Domain-scoping logic are MIRRORED in architect-sf, since both serve pages for Architect.
+     * Changing these values requires a coordinated change in all repos.
+     */
+    private shouldMount(): boolean {
+        if (!this.hideAgentConditionally) {
+            return true;
+        }
+
+        // When the agent should be conditionally hidden, we check for special query param or
+        // cookie required for actually mounting/rendering it.
+        const hasParam =
+            new URLSearchParams(window.location.search).get("showAgent") ===
+            "true";
+        const hasCookie = /(?:^|;\s*)show_agent=true(?:;|$)/.test(
+            document.cookie
+        );
+
+        // If the user doesn't have the cookie yet but does have the param, set the cookie
+        if (hasParam && !hasCookie) {
+            dropCookie(this.cookieDomain || "");
+        }
+
+        return hasParam || hasCookie;
+    }
+
     private async mountMiawHost(): Promise<void> {
         try {
             await loadMiawUiScript();
@@ -114,10 +177,7 @@ export default class AgentMiawUi extends LightningElement {
                 this.richComponentVersion
             );
             if (this.routingAttributes) {
-                el.setAttribute(
-                    "routing-attributes",
-                    this.routingAttributes
-                );
+                el.setAttribute("routing-attributes", this.routingAttributes);
             }
             if (this.prompts) {
                 el.setAttribute("prompts", this.prompts);
@@ -134,7 +194,9 @@ export default class AgentMiawUi extends LightningElement {
     }
 
     private setSidebarOpenState(isOpen: boolean): void {
-        const targets = document.querySelectorAll(this.sidebarStateTargetSelector);
+        const targets = document.querySelectorAll(
+            this.sidebarStateTargetSelector
+        );
         targets.forEach((target) => {
             target.setAttribute(
                 AgentMiawUi.SIDEBAR_OPEN_ATTR,

package/src/modules/dx/searchHybrid/searchHybrid.css

@@ -0,0 +1,165 @@
+:host {
+    display: block;
+    font-family: var(--dx-g-font-sans);
+}
+
+.dx-search-hybrid {
+    background-color: #fafaf9;
+}
+
+/* Header --------------------------------------------------------------- */
+.dx-search-header {
+    padding: var(--dx-g-spacing-xl);
+    background: linear-gradient(
+        77deg,
+        var(--dx-g-indigo-vibrant-30) 40.1%,
+        var(--dx-g-indigo-vibrant-40) 99.07%
+    );
+    color: white;
+}
+
+.dx-search-header-container {
+    margin: 0 auto;
+    max-width: 1200px;
+}
+
+.dx-search-header-title {
+    font-size: var(--dx-g-text-lg);
+    line-height: var(--dx-g-text-lg);
+    font-weight: var(--dx-g-font-normal);
+    margin-bottom: var(--dx-g-spacing-md);
+}
+
+.dx-search-header-title-results {
+    font-weight: var(--dx-g-font-bold);
+}
+
+.dx-search-header-query {
+    font-family: var(--dx-g-font-display);
+    font-size: var(--dx-g-text-2xl);
+    line-height: var(--dx-g-text-2xl);
+    font-weight: var(--dx-g-font-demi);
+    margin-top: var(--dx-g-spacing-md);
+}
+
+/* Body + toolbar ------------------------------------------------------- */
+.dx-search-body {
+    margin: 0 auto;
+    max-width: 1200px;
+    padding: var(--dx-g-spacing-xl);
+}
+
+.dx-search-toolbar {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: flex-end;
+    justify-content: space-between;
+    gap: var(--dx-g-spacing-md);
+    margin-bottom: var(--dx-g-spacing-lg);
+}
+
+.dx-facet-row {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--dx-g-spacing-sm);
+}
+
+.dx-facet-chip {
+    background-color: white;
+    color: var(--dx-g-blue-vibrant-20);
+    border: 1px solid var(--dx-g-blue-vibrant-50);
+    border-radius: 500px;
+    padding: 6px 14px;
+    font-size: var(--dx-g-text-sm);
+    cursor: pointer;
+}
+
+.dx-facet-chip:hover {
+    background-color: var(--dx-g-blue-vibrant-95);
+}
+
+.dx-facet-chip_active {
+    background-color: var(--dx-g-blue-vibrant-50);
+    color: white;
+    font-weight: var(--dx-g-font-demi);
+}
+
+.dx-facet-chip-count {
+    margin-left: 6px;
+    opacity: 0.75;
+}
+
+.dx-search-controls {
+    display: flex;
+    gap: var(--dx-g-spacing-md);
+}
+
+/* Status states -------------------------------------------------------- */
+.dx-search-status {
+    display: flex;
+    justify-content: center;
+    padding: var(--dx-g-spacing-2xl) 0;
+}
+
+.dx-search-error {
+    color: var(--dx-g-red-vibrant-40, #ba0517);
+}
+
+/* Result cards (ported from dx/searchResults visual style) ------------- */
+.dx-result-list {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+}
+
+.dx-result {
+    background: white;
+    border-radius: 16px;
+    border: 1px solid rgb(24 24 24 / 4%);
+    box-shadow: 0 0 2px 0 rgb(24 24 24 / 8%), 0 2px 4px 1px rgb(24 24 24 / 16%);
+    padding: 20px;
+    margin-bottom: var(--dx-g-spacing-lg);
+}
+
+.dx-result-info {
+    display: flex;
+    gap: 12px;
+    margin-bottom: var(--dx-g-spacing-smd);
+}
+
+.dx-badge {
+    display: inline-flex;
+    align-items: center;
+    border-radius: 4px;
+    padding: 2px 8px;
+    font-size: var(--dx-g-text-xs);
+    background-color: var(--dx-g-blue-vibrant-95);
+    color: var(--dx-g-blue-vibrant-20);
+}
+
+.dx-result-title {
+    color: var(--dx-g-blue-vibrant-20);
+    display: block;
+    font-family: var(--dx-g-font-display);
+    font-size: var(--dx-g-text-lg);
+    margin: 0 0 var(--dx-g-spacing-sm);
+}
+
+.dx-result-date {
+    color: #555;
+    font-size: var(--dx-g-text-xs);
+    margin: 0 0 var(--dx-g-spacing-xs);
+}
+
+.dx-result-excerpt {
+    color: var(--dx-g-gray-10);
+    font-size: 14px;
+    line-height: 20px;
+    margin: 0;
+}
+
+/* Pagination ----------------------------------------------------------- */
+.dx-pagination-container {
+    margin: 0 auto;
+    width: fit-content;
+}

package/src/modules/dx/searchHybrid/searchHybrid.html

@@ -0,0 +1,136 @@
+<template>
+    <div class="dx-search-hybrid">
+        <!-- Header: result count + query (?q-driven; no input box per D15.3) -->
+        <div if:true={hasQuery} class="dx-search-header">
+            <div class="dx-search-header-container">
+                <p class="dx-search-header-title">
+                    <span class="dx-search-header-title-results">{total}</span>
+                    &nbsp;results for
+                </p>
+                <p class="dx-search-header-query">&ldquo;{query}&rdquo;</p>
+            </div>
+        </div>
+
+        <div class="dx-search-body">
+            <!-- Toolbar: content-type facets + sort + locale selector -->
+            <div class="dx-search-toolbar">
+                <div
+                    if:true={hasFacets}
+                    class="dx-facet-row"
+                    role="group"
+                    aria-label="Filter by content type"
+                >
+                    <template for:each={facetChips} for:item="chip">
+                        <button
+                            key={chip.value}
+                            type="button"
+                            class={chip.cssClass}
+                            data-value={chip.value}
+                            aria-pressed={chip.active}
+                            onclick={handleFacetClick}
+                        >
+                            {chip.label}
+                            <span class="dx-facet-chip-count">
+                                {chip.count}
+                            </span>
+                        </button>
+                    </template>
+                </div>
+
+                <div class="dx-search-controls">
+                    <div if:true={showLocaleSelector} class="dx-search-locale">
+                        <dx-select
+                            label="Language"
+                            options={localeSelectOptions}
+                            value={localeValue}
+                            onchange={handleLocaleChange}
+                        ></dx-select>
+                    </div>
+                    <div class="dx-search-sort">
+                        <dx-select
+                            label="Sort by"
+                            options={sortOptions}
+                            value={sortValue}
+                            onchange={handleSortChange}
+                        ></dx-select>
+                    </div>
+                </div>
+            </div>
+
+            <!-- Loading -->
+            <template if:true={isLoading}>
+                <div class="dx-search-status" aria-live="polite">
+                    <dx-spinner size="medium" variant="base"></dx-spinner>
+                </div>
+            </template>
+
+            <!-- Idle prompt (no query yet) -->
+            <template if:true={isIdle}>
+                <div class="dx-search-status" aria-live="polite">
+                    <dx-empty-state
+                        header="Search the developer site"
+                        subtitle="Enter a search term to get started."
+                        variant="alt"
+                    ></dx-empty-state>
+                </div>
+            </template>
+
+            <!-- Empty (query ran, no results) -->
+            <template if:true={isEmpty}>
+                <div class="dx-search-status" aria-live="polite">
+                    <dx-empty-state
+                        header="No results found"
+                        subtitle="Try different keywords or check your spelling."
+                        variant="alt"
+                    ></dx-empty-state>
+                </div>
+            </template>
+
+            <!-- Error -->
+            <template if:true={isError}>
+                <div class="dx-search-status dx-search-error" role="alert">
+                    <p>{errorMessage}</p>
+                </div>
+            </template>
+
+            <!-- Results -->
+            <template if:true={hasResults}>
+                <ul class="dx-result-list">
+                    <template for:each={displayResults} for:item="result">
+                        <li key={result.key} class="dx-result">
+                            <div
+                                if:true={result.hasBadge}
+                                class="dx-result-info"
+                            >
+                                <span class="dx-badge">
+                                    {result.contentTypeLabel}
+                                </span>
+                            </div>
+                            <a href={result.url} class="dx-result-title">
+                                {result.title}
+                            </a>
+                            <p if:true={result.hasDate} class="dx-result-date">
+                                {result.displayDate}
+                            </p>
+                            <p
+                                if:true={result.hasDescription}
+                                class="dx-result-excerpt"
+                            >
+                                {result.description}
+                            </p>
+                        </li>
+                    </template>
+                </ul>
+
+                <div if:true={showPagination} class="dx-pagination-container">
+                    <dx-pagination
+                        current-page={currentPage}
+                        total-pages={totalPages}
+                        pages-to-show="5"
+                        onpagechange={handlePageChange}
+                    ></dx-pagination>
+                </div>
+            </template>
+        </div>
+    </div>
+</template>

package/src/modules/dx/searchHybrid/searchHybrid.ts

@@ -0,0 +1,306 @@
+import { LightningElement, api, track } from "lwc";
+import {
+    SearchController,
+    type SearchViewModel
+} from "docUtils/searchController";
+import type { LocaleOption } from "docUtils/searchLocale";
+import {
+    decodeHtmlEntities,
+    isSortOption,
+    SORT_OPTIONS,
+    type SearchResult,
+    type SortOption
+} from "docUtils/searchClient";
+import { searchLocalePrefs } from "dxUtils/searchLocalePrefs";
+import { track as trackGTM } from "dxUtils/analytics";
+import { CONTENT_TYPE_LABELS } from "dxConstants/contentTypes";
+import { parseSupportedLocales } from "docUtils/searchLocale";
+
+// The developer site pins itself as the "developer" site in the unified
+// search corpus (matches the dx search call; the SSG/WordPress developer docs
+// are ingested under this site value).
+const DX_SITE = "developer";
+
+const SORT_LABELS: Record<SortOption, string> = {
+    relevance: "Relevance",
+    date: "Most recent"
+};
+
+interface DisplayResult {
+    key: string;
+    url: string;
+    title: string;
+    description: string | null;
+    hasDescription: boolean;
+    contentTypeLabel: string | null;
+    hasBadge: boolean;
+    displayDate: string;
+    hasDate: boolean;
+}
+
+interface FacetChip {
+    value: string;
+    label: string;
+    count: number;
+    active: boolean;
+    cssClass: string;
+}
+
+interface SortSelectOption {
+    value: string;
+    label: string;
+}
+
+export default class SearchHybrid extends LightningElement {
+    /**
+     * JSON string of the supported locale catalog (LocaleOption[]). Injected by
+     * the host page. Drives both the controller catalog and the locale selector.
+     */
+    @api locales?: string;
+
+    /** The page's server locale, used as the default search language. */
+    @api defaultLanguage: string = "en-us";
+
+    /** Results per page. */
+    @api limit?: number;
+
+    /** Override the /api/search base path (mostly for tests / storybook). */
+    @api basePath?: string;
+
+    @track private vm: SearchViewModel | null = null;
+
+    private controller: SearchController | null = null;
+    private unsubscribe: (() => void) | null = null;
+
+    connectedCallback(): void {
+        const catalog = parseSupportedLocales(this.locales ?? "");
+        const supportedIds = catalog.map((l: LocaleOption) => l.id);
+
+        this.controller = new SearchController({
+            catalog,
+            defaultLanguage: this.defaultLanguage,
+            supportedIds,
+            site: DX_SITE,
+            limit: this.limit,
+            basePath: this.basePath,
+            deps: searchLocalePrefs,
+            instrument: (event, payload) => {
+                // dxUtils/analytics.track requires an EventTarget; route through
+                // the host element so the instrumentation listener can capture it.
+                trackGTM(this as unknown as EventTarget, event, payload);
+            }
+        });
+
+        this.unsubscribe = this.controller.subscribe((vm) => {
+            this.vm = vm;
+        });
+        this.vm = this.controller.viewModel;
+        this.controller.init();
+    }
+
+    disconnectedCallback(): void {
+        this.unsubscribe?.();
+        this.unsubscribe = null;
+        this.controller?.dispose();
+        this.controller = null;
+    }
+
+    // ---- status flags -----------------------------------------------------
+
+    get isIdle(): boolean {
+        return this.vm?.status === "idle";
+    }
+
+    get isLoading(): boolean {
+        return this.vm?.status === "loading";
+    }
+
+    get isError(): boolean {
+        return this.vm?.status === "error";
+    }
+
+    get isEmpty(): boolean {
+        return this.vm?.status === "empty";
+    }
+
+    get hasResults(): boolean {
+        return this.vm?.status === "results";
+    }
+
+    get errorMessage(): string {
+        return this.vm?.errorMessage || "Something went wrong. Try again.";
+    }
+
+    get query(): string {
+        return this.vm?.query ?? "";
+    }
+
+    get hasQuery(): boolean {
+        return this.query !== "";
+    }
+
+    get total(): number {
+        return this.vm?.total ?? 0;
+    }
+
+    // ---- results ----------------------------------------------------------
+
+    get displayResults(): DisplayResult[] {
+        const results = this.vm?.results ?? [];
+        return results.map((r: SearchResult, i: number) => {
+            const description =
+                r.description != null && r.description !== ""
+                    ? decodeHtmlEntities(r.description)
+                    : null;
+            const label = this.contentTypeLabel(r.contentType);
+            const displayDate = this.formatDate(r.lastmod);
+            return {
+                key: `${r.url}-${i}`,
+                url: r.url,
+                title: decodeHtmlEntities(r.title),
+                description,
+                hasDescription: description !== null,
+                contentTypeLabel: label,
+                hasBadge: label !== null,
+                displayDate,
+                // Tie hasDate to the FORMATTED output so a non-null but
+                // unparseable lastmod renders no date element (no raw ISO).
+                hasDate: displayDate.length > 0
+            };
+        });
+    }
+
+    /**
+     * Null/NaN-safe date formatter (mirrors arch/searchHybrid). lastmod is null
+     * for the entire SSG corpus (the common case → ""); the WordPress portion
+     * of the developer corpus emits an ISO timestamp, which we render as a
+     * human date rather than the raw machine string.
+     */
+    private formatDate(lastmod: string | null): string {
+        if (typeof lastmod !== "string" || lastmod.length === 0) {
+            return "";
+        }
+        const date = new Date(lastmod);
+        if (Number.isNaN(date.getTime())) {
+            return "";
+        }
+        return date.toLocaleDateString(undefined, {
+            year: "numeric",
+            month: "short",
+            day: "numeric"
+        });
+    }
+
+    /**
+     * Null-safe content-type label lookup. contentType is null for the entire
+     * SSG corpus and is the common case; unknown values fall back to the raw
+     * value so we never render an empty badge or crash.
+     */
+    private contentTypeLabel(contentType: string | null): string | null {
+        if (contentType == null || contentType === "") {
+            return null;
+        }
+        const labels = CONTENT_TYPE_LABELS as Record<string, string>;
+        return labels[contentType] ?? contentType;
+    }
+
+    // ---- content-type facet chips (disjunctive) ---------------------------
+
+    get facetChips(): FacetChip[] {
+        const facets = this.vm?.contentTypeFacets ?? [];
+        const selected = this.vm?.selectedType ?? null;
+        return facets
+            .filter((b) => b.value != null && b.value !== "")
+            .map((b) => {
+                const active = selected === b.value;
+                return {
+                    value: b.value,
+                    label: this.contentTypeLabel(b.value) ?? b.value,
+                    count: b.count,
+                    active,
+                    cssClass: active
+                        ? "dx-facet-chip dx-facet-chip_active"
+                        : "dx-facet-chip"
+                };
+            });
+    }
+
+    get hasFacets(): boolean {
+        return this.facetChips.length > 0;
+    }
+
+    // ---- sort + locale select options -------------------------------------
+
+    get sortOptions(): SortSelectOption[] {
+        return SORT_OPTIONS.map((value) => ({
+            value,
+            label: SORT_LABELS[value]
+        }));
+    }
+
+    get sortValue(): string {
+        return this.vm?.sort ?? "relevance";
+    }
+
+    get showLocaleSelector(): boolean {
+        return this.controller?.showLocaleSelector ?? false;
+    }
+
+    get localeSelectOptions(): SortSelectOption[] {
+        const options = this.controller?.localeOptions ?? [];
+        return options.map((l: LocaleOption) => ({
+            value: l.id,
+            label: l.displayText ?? l.label ?? l.id
+        }));
+    }
+
+    get localeValue(): string {
+        return this.vm?.locale ?? this.defaultLanguage;
+    }
+
+    // ---- pagination -------------------------------------------------------
+
+    get currentPage(): string {
+        return String(this.vm?.page ?? 1);
+    }
+
+    get totalPages(): string {
+        return String(this.vm?.totalPages ?? 1);
+    }
+
+    get showPagination(): boolean {
+        return (this.vm?.totalPages ?? 1) > 1;
+    }
+
+    // ---- event handlers ---------------------------------------------------
+
+    handleSortChange(event: CustomEvent<{ value: string }>): void {
+        const value = event.detail?.value;
+        if (isSortOption(value)) {
+            this.controller?.setSort(value);
+        }
+    }
+
+    handleLocaleChange(event: CustomEvent<{ value: string }>): void {
+        const value = event.detail?.value;
+        if (value) {
+            this.controller?.setLanguage(value);
+        }
+    }
+
+    handleFacetClick(event: Event): void {
+        const value = (event.currentTarget as HTMLElement)?.dataset?.value;
+        if (value) {
+            // Disjunctive toggle: the controller clears it if it is already
+            // active.
+            this.controller?.setType(value);
+        }
+    }
+
+    handlePageChange(event: CustomEvent<number>): void {
+        const page = event.detail;
+        if (typeof page === "number" && page >= 1) {
+            this.controller?.setPage(page);
+        }
+    }
+}

package/src/modules/dxUtils/searchLocalePrefs/searchLocalePrefs.ts

@@ -0,0 +1,193 @@
+/**
+ * @file Developer-site implementation of docUtils `LocaleDeps` for the unified
+ * hybrid search UI (P4.1). Supplies per-device storage of the user's chosen
+ * search language (consent-gated behind OneTrust functional-cookie consent) and
+ * a browser-language -> supported-locale resolver.
+ *
+ * dx has no equivalent of arch/localePreference or arch/browserLocale and no
+ * shared consent util, so this mirrors the consent read used elsewhere in the
+ * org (the OptanonConsent cookie's `groups` field, functional category C0003).
+ * OneTrust's standard functional group id is C0003; "C0003:1" means granted,
+ * "C0003:0" means denied. We never persist a preference without an explicit
+ * grant.
+ *
+ * Exposes `searchLocalePrefs`, an object implementing the docUtils LocaleDeps
+ * shape ({ getStored, setStored, resolveBrowser }), plus a `buildSearchLocalePrefs`
+ * factory for tests / dependency injection.
+ */
+
+import type { LocaleDeps } from "docUtils/searchLocale";
+
+export const STORAGE_KEY = "dx-search-language";
+export const FUNCTIONAL_GROUP_ID = "C0003";
+export const DEFAULT_LOCALE = "en-us";
+
+/**
+ * Region/script-aware overrides for cases a plain language-only match can't
+ * resolve. Keys are normalized lowercase BCP-47 tags (or language-only codes);
+ * values are site locale ids. Order of checks: exact id -> these rules ->
+ * language-only first match -> default.
+ *
+ * Mirrors the product decisions baked into arch/browserLocale:
+ *   - bare "es" -> es-mx (es-mx is the generic Spanish)
+ *   - any pt-* -> pt-br (only Brazilian Portuguese is published)
+ *   - no/nb/nn -> nb-no (only Norwegian id)
+ *   - Chinese is matched on script/region, never collapsed to language-only.
+ */
+const TAG_OVERRIDES: Record<string, string> = {
+    // Chinese — Traditional
+    "zh-tw": "zh-tw",
+    "zh-hant": "zh-tw",
+    "zh-hk": "zh-tw",
+    "zh-mo": "zh-tw",
+    // Chinese — Simplified (and bare "zh")
+    zh: "zh-cn",
+    "zh-cn": "zh-cn",
+    "zh-hans": "zh-cn",
+    "zh-sg": "zh-cn",
+    // Spanish
+    es: "es-mx",
+    "es-es": "es-es",
+    // Portuguese (only pt-br exists)
+    pt: "pt-br",
+    "pt-pt": "pt-br",
+    // Norwegian (only nb-no exists)
+    no: "nb-no",
+    nb: "nb-no",
+    nn: "nb-no"
+};
+
+/**
+ * Read the OptanonConsent cookie and return whether the functional group is
+ * granted. Defensive: if OneTrust hasn't loaded or the cookie is absent
+ * (tests, pre-consent, non-prod), returns false so we never persist without an
+ * explicit grant.
+ */
+export function hasFunctionalConsent(): boolean {
+    try {
+        const cookie = document.cookie
+            .split("; ")
+            .find((row) => row.startsWith("OptanonConsent="));
+        if (!cookie) {
+            return false;
+        }
+        // The cookie value is URL-encoded querystring-style, e.g.
+        // "...&groups=C0001:1,C0003:1,C0002:0&...".
+        const value = decodeURIComponent(cookie.split("=").slice(1).join("="));
+        const groups = new URLSearchParams(value).get("groups");
+        if (!groups) {
+            return false;
+        }
+        return groups
+            .split(",")
+            .some((entry) => entry.trim() === `${FUNCTIONAL_GROUP_ID}:1`);
+    } catch (e) {
+        return false;
+    }
+}
+
+/**
+ * Map a single language-only code (e.g. "ja", "de") to its site locale id by
+ * finding the first supported id whose language subtag matches.
+ */
+function languageOnlyMatch(
+    language: string,
+    supportedIds: string[]
+): string | undefined {
+    return supportedIds.find((id) => id.split("-")[0] === language);
+}
+
+/**
+ * Get the stored language preference, or null if none / unavailable. Reading an
+ * already-stored preference is low-risk, so it is NOT consent-gated.
+ */
+export function getStoredLanguage(): string | null {
+    try {
+        return window.localStorage.getItem(STORAGE_KEY);
+    } catch (e) {
+        return null;
+    }
+}
+
+/**
+ * Persist the chosen language, but only if the user has granted functional
+ * consent. Returns true if the value was written, false if it was skipped (no
+ * consent) or failed. When skipped, the choice still applies for the current
+ * page/session via in-memory state and the ?lang= URL param.
+ */
+export function setStoredLanguage(language: string): boolean {
+    if (!language || !hasFunctionalConsent()) {
+        return false;
+    }
+    try {
+        window.localStorage.setItem(STORAGE_KEY, language);
+        return true;
+    } catch (e) {
+        return false;
+    }
+}
+
+/**
+ * Resolve the best site locale id for the given browser languages. The first
+ * browser language that maps to a supported id wins; earlier entries take
+ * precedence over later ones (matching navigator.languages ordering).
+ * Returns "en-us" if nothing matches.
+ */
+export function resolveBrowserLocale(
+    navigatorLanguages: readonly string[] | undefined,
+    supportedIds: string[]
+): string {
+    if (!navigatorLanguages || navigatorLanguages.length === 0) {
+        return DEFAULT_LOCALE;
+    }
+
+    const supported = new Set(supportedIds);
+
+    for (const raw of navigatorLanguages) {
+        if (!raw) {
+            continue;
+        }
+        const tag = raw.toLowerCase();
+
+        // 1. Exact id match (e.g. "ja-jp" -> ja-jp).
+        if (supported.has(tag)) {
+            return tag;
+        }
+
+        // 2. Region/script override (e.g. "zh-tw" -> zh-tw, "es" -> es-mx).
+        const overridden = TAG_OVERRIDES[tag];
+        if (overridden && supported.has(overridden)) {
+            return overridden;
+        }
+
+        // 3. Language-only fall-through (e.g. "de-ch" -> de -> de-de).
+        const language = tag.split("-")[0];
+        const overriddenLang = TAG_OVERRIDES[language];
+        if (overriddenLang && supported.has(overriddenLang)) {
+            return overriddenLang;
+        }
+        const matched = languageOnlyMatch(language, supportedIds);
+        if (matched) {
+            return matched;
+        }
+    }
+
+    return DEFAULT_LOCALE;
+}
+
+/**
+ * Build a docUtils LocaleDeps bundle for the developer site. Exposed as a
+ * factory so tests / callers can inject overrides; the default-exported
+ * `searchLocalePrefs` is the production singleton.
+ */
+export function buildSearchLocalePrefs(
+    overrides: Partial<LocaleDeps> = {}
+): LocaleDeps {
+    return {
+        getStored: overrides.getStored ?? getStoredLanguage,
+        setStored: overrides.setStored ?? setStoredLanguage,
+        resolveBrowser: overrides.resolveBrowser ?? resolveBrowserLocale
+    };
+}
+
+export const searchLocalePrefs: LocaleDeps = buildSearchLocalePrefs();