@salesforcedevs/arch-components 1.28.1-banner-2 → 1.28.1

package/lwc.config.json

@@ -15,7 +15,6 @@
         "arch/cardGridD",
         "arch/cardNew",
         "arch/children",
-        "arch/content",
         "arch/contentIcon",
         "arch/context",
         "arch/contextAdapter",

package/package.json

@@ -1,10 +1,10 @@
 {
     "name": "@salesforcedevs/arch-components",
-    "version": "1.28.1-banner-2",
+    "version": "1.28.1",
     "description": "Architect Lightning web components",
     "license": "MIT",
     "engines": {
-        "node": "20.x"
+        "node": "22.x"
     },
     "publishConfig": {
         "access": "public"
@@ -44,5 +44,5 @@
         "eventsourcemock": "2.0.0",
         "luxon": "3.4.4"
     },
-    "gitHead": "4f8c415f6a58d0747a9e746a4b1717d85de32122"
+    "gitHead": "e0db9e8eabf2d398d8b599163aeba4261866cb29"
 }

package/src/modules/arch/browserLocale/browserLocale.ts

@@ -0,0 +1,104 @@
+/**
+ * @file Resolves a browser's preferred language (BCP-47 tags from
+ * navigator.languages) to one of the site's supported locale ids
+ * (e.g. "en-us", "ja-jp", "zh-tw"). Used to pick a sensible default language
+ * for search when the page itself carries no locale.
+ */
+
+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.
+ *
+ * Product decisions baked in (see search locale design):
+ *   - bare "es" -> es-mx (languages.yml lists es-mx as 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"
+};
+
+/**
+ * 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);
+}
+
+/**
+ * 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).
+ * @param navigatorLanguages Ordered list of BCP-47 tags (navigator.languages).
+ * @param supportedIds Site locale ids actually offered (e.g. from the dropdown).
+ * @returns A supported locale id, or "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;
+}

package/src/modules/arch/icon/icon.ts

@@ -29,7 +29,7 @@ export default class extends LightningElement {
     private context: ContextAdapterValue = null!;
 
     private get className() {
-        return `size--${this.size}`;
+        return `size-${this.size}`;
     }
 
     private get href() {

package/src/modules/arch/localePreference/localePreference.ts

@@ -0,0 +1,72 @@
+/**
+ * @file Per-device storage for the user's chosen search language, gated behind
+ * OneTrust functional-cookie consent.
+ *
+ * There is no shared consent util in the codebase; this mirrors the consent
+ * read used on the admin site (page-events-calendar.php's one_trust_notice),
+ * which parses the OptanonConsent cookie's `groups` field and inspects the
+ * functional category. OneTrust's standard functional group id is C0003;
+ * "C0003:1" means granted, "C0003:0" means denied.
+ */
+
+const STORAGE_KEY = "arch-search-language";
+const FUNCTIONAL_GROUP_ID = "C0003";
+
+/**
+ * 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.
+ */
+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;
+    }
+}
+
+/**
+ * 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;
+    }
+}

package/src/modules/arch/searchList/searchList.css

@@ -13,6 +13,12 @@
     position: relative;
 }
 
+.search-language-selector {
+    display: flex;
+    justify-content: flex-end;
+    margin-bottom: var(--arch-spacing-4);
+}
+
 .search-input-label {
     position: absolute !important;
     height: 1px;

package/src/modules/arch/searchList/searchList.html

@@ -1,8 +1,23 @@
 <template>
     <arch-section-a background="white" title={titleSearchResults}>
-        <template if:true={results}>
+        <template lwc:if={showLanguageSelector}>
+            <div class="search-language-selector">
+                <arch-select
+                    assistive-text="Search language"
+                    value={language}
+                    onchange={handleLanguageChange}
+                >
+                    <template for:each={localeOptions} for:item="locale">
+                        <option key={locale.id} value={locale.id}>
+                            {locale.displayText}
+                        </option>
+                    </template>
+                </arch-select>
+            </div>
+        </template>
+        <template lwc:if={results}>
             <template for:each={results} for:item="result">
-                <div key={result.title}>
+                <div key={result.url}>
                     <arch-summary
                         description={result.description}
                         compact
@@ -19,7 +34,7 @@
                 </div>
             </template>
         </template>
-        <template if:true={showSearchSuggestions}>
+        <template lwc:if={showSearchSuggestions}>
             <div style="display: block">
                 <center>
                     <img

package/src/modules/arch/searchList/searchList.ts

@@ -1,5 +1,15 @@
-import { LightningElement, api, track } from "lwc";
+import { LightningElement, api } from "lwc";
 import { track as trackEvent } from "arch/instrumentation";
+import { resolveBrowserLocale } from "arch/browserLocale";
+import { getStoredLanguage, setStoredLanguage } from "arch/localePreference";
+
+const DEFAULT_LANGUAGE = "en-us";
+
+interface LocaleOption {
+    id: string;
+    displayText?: string;
+    label?: string;
+}
 
 function decodeHtmlEntities(value: unknown): string {
     if (typeof value !== "string" || value.length === 0) {
@@ -23,52 +33,189 @@ export default class SearchList extends LightningElement {
     @api algoliaAppId: string = "";
     @api algoliaApiKey: string = "";
 
-    @track results: any;
+    // The catalog of selectable locales, injected from njk as a JSON string
+    // (the doc-framework ALL_LANGUAGES global, sourced from languages.yml).
+    @api supportedLocales: string = "";
+    // The page's server-side locale, used as a fallback default.
+    @api defaultLanguage: string = DEFAULT_LANGUAGE;
+
+    // The effective search language. Resolved at runtime; not an @api so the
+    // dropdown can change it and re-query. These are reassigned wholesale (not
+    // mutated in place), so plain reactive fields suffice — no @track needed.
+    language: string = DEFAULT_LANGUAGE;
+    localeOptions: LocaleOption[] = [];
+    results: any;
+
+    private keywords: string = "";
+    private abortController?: AbortController;
 
     connectedCallback() {
+        this.localeOptions = this.parseSupportedLocales();
+        this.language = this.resolveInitialLanguage();
+
         const params = new URLSearchParams(window.location.search);
-        if (params && params.get("keywords")) {
-            const keywords = params.get("keywords") || "";
-            fetch(
-                `https://${this.algoliaAppId}-dsn.algolia.net/1/indexes/${this.algoliaIndex}?query=${keywords}&hitsPerPage=20`,
-                {
-                    headers: {
-                        "X-Algolia-Application-Id": this.algoliaAppId,
-                        "X-Algolia-API-Key": this.algoliaApiKey
-                    }
-                }
-            )
-                .then((result) => {
-                    return result.json();
-                })
-                .then((json) => {
-                    trackEvent(this.template.host, "search_executed", {
-                        searchTerm: keywords,
-                        resultCount: json.hits?.length || 0
-                    });
-                    if (json.hits && json.hits.length) {
-                        this.titleSearchResults = `Search results for "${decodeURIComponent(
-                            keywords
-                        )}"`;
-                        this.results = json.hits.map((hit: any) => ({
-                            ...hit,
-                            description: decodeHtmlEntities(hit.description)
-                        }));
-                        this.showSearchSuggestions = false;
-                    } else {
-                        this.titleSearchResults = `No results for "${decodeURIComponent(
-                            keywords
-                        )}"`;
-                        this.showSearchSuggestions = true;
-                    }
-                })
-                .catch(() => {
-                    this.titleSearchResults = `An error occured`;
-                    this.showSearchSuggestions = false;
-                });
+        if (params.get("keywords")) {
+            this.keywords = params.get("keywords") || "";
+            this.runSearch();
         } else {
             this.titleSearchResults = "No keywords provided";
             this.showSearchSuggestions = false;
         }
     }
+
+    /**
+     * Parse the injected locale catalog, restricting to entries with an id.
+     * Falls back to an empty list (which hides the dropdown) on bad input.
+     */
+    private parseSupportedLocales(): LocaleOption[] {
+        if (!this.supportedLocales) {
+            return [];
+        }
+        try {
+            const parsed = JSON.parse(this.supportedLocales);
+            if (!Array.isArray(parsed)) {
+                return [];
+            }
+            return parsed.filter(
+                (entry): entry is LocaleOption =>
+                    !!entry && typeof entry.id === "string"
+            );
+        } catch (e) {
+            return [];
+        }
+    }
+
+    private get supportedIds(): string[] {
+        return this.localeOptions.map((option) => option.id);
+    }
+
+    /**
+     * 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).
+     */
+    private resolveInitialLanguage(): string {
+        const ids = this.supportedIds;
+        const isSupported = (value: string | null | undefined): boolean =>
+            !!value && (ids.length === 0 || ids.includes(value));
+
+        const fromUrl = new URLSearchParams(window.location.search).get("lang");
+        if (isSupported(fromUrl)) {
+            return fromUrl as string;
+        }
+
+        const stored = getStoredLanguage();
+        if (isSupported(stored)) {
+            return stored as string;
+        }
+
+        if (ids.length > 0) {
+            const detected = resolveBrowserLocale(
+                navigator.languages,
+                ids
+            );
+            if (isSupported(detected)) {
+                return detected;
+            }
+        }
+
+        return isSupported(this.defaultLanguage)
+            ? this.defaultLanguage
+            : DEFAULT_LANGUAGE;
+    }
+
+    /**
+     * Run the Algolia query for the current keywords + language. Aborts any
+     * in-flight request so a fast language switch can't render stale results.
+     */
+    private runSearch() {
+        this.abortController?.abort();
+        const controller = new AbortController();
+        this.abortController = controller;
+
+        const keywords = this.keywords;
+        // Filter to the chosen language so results are isolated by locale
+        // (records are tagged with `language` by the indexer; `language` is
+        // registered as a filterOnly facet).
+        const languageFilter = encodeURIComponent(`language:${this.language}`);
+        fetch(
+            `https://${this.algoliaAppId}-dsn.algolia.net/1/indexes/${
+                this.algoliaIndex
+            }?query=${encodeURIComponent(
+                keywords
+            )}&filters=${languageFilter}&hitsPerPage=20`,
+            {
+                headers: {
+                    "X-Algolia-Application-Id": this.algoliaAppId,
+                    "X-Algolia-API-Key": this.algoliaApiKey
+                },
+                signal: controller.signal
+            }
+        )
+            .then((result) => result.json())
+            .then((json) => {
+                trackEvent(this.template.host, "search_executed", {
+                    searchTerm: keywords,
+                    language: this.language,
+                    resultCount: json.hits?.length || 0
+                });
+                if (json.hits && json.hits.length) {
+                    // keywords is already decoded by URLSearchParams.get.
+                    this.titleSearchResults = `Search results for "${keywords}"`;
+                    this.results = json.hits.map((hit: any) => ({
+                        ...hit,
+                        description: decodeHtmlEntities(hit.description)
+                    }));
+                    this.showSearchSuggestions = false;
+                } else {
+                    this.titleSearchResults = `No results for "${keywords}"`;
+                    this.showSearchSuggestions = true;
+                }
+            })
+            .catch((error) => {
+                // Ignore aborts from a superseding language switch.
+                if (error?.name === "AbortError") {
+                    return;
+                }
+                // A 400 here usually means the index has not been reindexed
+                // with the filterOnly(language) facet yet (see deploy order).
+                console.error("Algolia search request failed:", error);
+                this.titleSearchResults = `An error occurred`;
+                this.showSearchSuggestions = false;
+            });
+    }
+
+    /**
+     * Dropdown change: switch language, persist (if consented), reflect in the
+     * URL for shareability, and re-run the same search.
+     */
+    handleLanguageChange(event: CustomEvent) {
+        const selected = event.detail;
+        if (!selected || selected === this.language) {
+            return;
+        }
+        this.language = selected;
+        setStoredLanguage(selected);
+
+        const params = new URLSearchParams(window.location.search);
+        params.set("lang", selected);
+        window.history.replaceState(
+            {},
+            "",
+            `${window.location.pathname}?${params.toString()}${
+                window.location.hash
+            }`
+        );
+
+        if (this.keywords) {
+            this.runSearch();
+        }
+    }
+
+    get showLanguageSelector(): boolean {
+        return this.localeOptions.length > 1;
+    }
 }

package/src/modules/arch/select/select.html

@@ -2,7 +2,7 @@
     <label class={labelClassName} for="select">{labelText}</label>
     <div class={containerClassName}>
         <arch-icon
-            class="select-icon select-icon--left"
+            class="select-icon select-icon-left"
             if:true={iconSymbol}
             size="medium"
             sprite={iconSprite}
@@ -10,13 +10,14 @@
         ></arch-icon>
         <select
             name="arch-select"
-            id={labelText}
+            id="select"
+            aria-label={labelText}
             lwc:dom="manual"
             onchange={handleChange}
             value={value}
         ></select>
         <arch-icon
-            class="select-icon select-icon--right"
+            class="select-icon select-icon-right"
             size="small"
             symbol="chevrondown"
         ></arch-icon>

package/src/modules/arch/select/select.ts

@@ -13,7 +13,7 @@ export default class extends ReflectedElement {
 
     private get containerClassName() {
         return classnames("select-container", {
-            "select-container--icon": this.iconSymbol
+            "select-container-icon": this.iconSymbol
         });
     }
 
@@ -38,7 +38,7 @@ export default class extends ReflectedElement {
         );
     }
 
-    private handleChange(event) {
+    private handleChange(event: Event) {
         this.dispatchEvent(
             new CustomEvent("change", {
                 detail: this.contentElement.value