@salesforcedevs/arch-components 1.28.5-node22-1 → 1.29.0

package/src/modules/arch/searchHybrid/searchHybrid.ts

@@ -0,0 +1,299 @@
+import { LightningElement, api, track } from "lwc";
+import { track as trackEvent } from "arch/instrumentation";
+import { resolveBrowserLocale } from "arch/browserLocale";
+import { getStoredLanguage, setStoredLanguage } from "arch/localePreference";
+import { decodeHtmlEntities, isSortOption } from "docUtils/searchClient";
+import { SearchController } from "docUtils/searchController";
+import type { SearchViewModel, SortOption } from "docUtils/searchController";
+import type { SearchResult, FacetBucket } from "docUtils/searchClient";
+import { parseSupportedLocales } from "docUtils/searchLocale";
+import type { LocaleDeps, LocaleOption } from "docUtils/searchLocale";
+
+const DEFAULT_LANGUAGE = "en-us";
+// The architect site value the search backend filters on. arch/searchList
+// pinned no explicit site to the backend (it filtered by language only against
+// Algolia), so we pin the canonical brand id "architect" here (see decisions).
+const ARCHITECT_SITE = "architect";
+
+// View-model shape used by the template — augments the controller's results
+// with already-decoded title/description so the template stays logic-free.
+interface RenderResult extends SearchResult {
+    // Iteration key for the template for:each. URL alone is NOT unique — two
+    // fused results can share a canonical URL, and a duplicate LWC key throws
+    // and fails to render the WHOLE list, so we disambiguate with the index.
+    key: string;
+    decodedTitle: string;
+    decodedDescription: string;
+    hasDescription: boolean;
+    hasContentType: boolean;
+    hasDate: boolean;
+    displayDate: string;
+}
+
+interface RenderFacet extends FacetBucket {
+    active: boolean;
+    label: string;
+}
+
+interface SortChoice {
+    id: SortOption;
+    displayText: string;
+}
+
+interface PageButton {
+    page: number;
+    label: string;
+    isCurrent: boolean;
+    ariaCurrent: "page" | null;
+}
+
+const SORT_CHOICES: SortChoice[] = [
+    { id: "relevance", displayText: "Relevance" },
+    { id: "date", displayText: "Newest" }
+];
+
+export default class SearchHybrid extends LightningElement {
+    // 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;
+
+    @track private vm: SearchViewModel | null = null;
+
+    private controller?: SearchController;
+    private unsubscribe?: () => void;
+    private localeCatalog: LocaleOption[] = [];
+
+    connectedCallback() {
+        this.localeCatalog = parseSupportedLocales(this.supportedLocales);
+        const supportedIds = this.localeCatalog.map((option) => option.id);
+
+        const deps: LocaleDeps = {
+            getStored: () => getStoredLanguage(),
+            setStored: (value: string) => setStoredLanguage(value),
+            resolveBrowser: (langs, ids) => resolveBrowserLocale(langs, ids)
+        };
+
+        const host = this.template.host;
+        this.controller = new SearchController({
+            catalog: this.localeCatalog,
+            defaultLanguage: this.defaultLanguage || DEFAULT_LANGUAGE,
+            supportedIds,
+            site: ARCHITECT_SITE,
+            deps,
+            instrument: (event, payload) => {
+                trackEvent(host, event, payload);
+            }
+        });
+
+        this.unsubscribe = this.controller.subscribe((vm) => {
+            this.vm = vm;
+        });
+        this.vm = this.controller.viewModel;
+        this.controller.init();
+    }
+
+    disconnectedCallback() {
+        this.unsubscribe?.();
+        this.controller?.dispose();
+        this.controller = undefined;
+        this.unsubscribe = undefined;
+    }
+
+    // ---- view-model derived getters (template-facing) -------------------
+
+    get localeOptions(): LocaleOption[] {
+        return this.localeCatalog;
+    }
+
+    get showLanguageSelector(): boolean {
+        return this.localeCatalog.length > 1;
+    }
+
+    get language(): string {
+        return this.vm?.locale ?? DEFAULT_LANGUAGE;
+    }
+
+    get sortChoices(): SortChoice[] {
+        return SORT_CHOICES;
+    }
+
+    get sort(): SortOption {
+        return this.vm?.sort ?? "relevance";
+    }
+
+    get isLoading(): boolean {
+        return this.vm?.status === "loading";
+    }
+
+    get isIdle(): boolean {
+        return this.vm?.status === "idle";
+    }
+
+    get isEmpty(): boolean {
+        return this.vm?.status === "empty";
+    }
+
+    get isError(): boolean {
+        return this.vm?.status === "error";
+    }
+
+    get hasResults(): boolean {
+        return this.vm?.status === "results" && this.results.length > 0;
+    }
+
+    get errorMessage(): string {
+        return this.vm?.errorMessage ?? "An error occurred.";
+    }
+
+    get summaryText(): string {
+        const vm = this.vm;
+        if (!vm) {
+            return "";
+        }
+        const query = vm.query ? ` for "${decodeHtmlEntities(vm.query)}"` : "";
+        if (vm.total === 1) {
+            return `1 result${query}`;
+        }
+        return `${vm.total} results${query}`;
+    }
+
+    get results(): RenderResult[] {
+        const list = this.vm?.results ?? [];
+        return list.map((result, index) => {
+            const description = result.description;
+            // Derive hasDate from the FORMATTED output, not the raw value, so a
+            // non-null but unparseable lastmod never yields an empty <time>.
+            const displayDate = this.formatDate(result.lastmod);
+            return {
+                ...result,
+                // Index-disambiguated so duplicate URLs can't collide (see key).
+                key: `${result.url}-${index}`,
+                decodedTitle: decodeHtmlEntities(result.title),
+                decodedDescription: decodeHtmlEntities(description),
+                hasDescription:
+                    typeof description === "string" && description.length > 0,
+                hasContentType:
+                    typeof result.contentType === "string" &&
+                    result.contentType.length > 0,
+                hasDate: displayDate.length > 0,
+                displayDate
+            };
+        });
+    }
+
+    get contentTypeFacets(): RenderFacet[] {
+        const facets = this.vm?.contentTypeFacets ?? [];
+        const selected = this.vm?.selectedType ?? null;
+        return facets.map((bucket) => ({
+            ...bucket,
+            active: selected === bucket.value,
+            // arch has no dxConstants label map; show the raw facet value.
+            label: bucket.value
+        }));
+    }
+
+    get showFacets(): boolean {
+        return this.contentTypeFacets.length > 0;
+    }
+
+    // ---- pagination (hand-rolled, null-safe) ----------------------------
+
+    get totalPages(): number {
+        return this.vm?.totalPages ?? 1;
+    }
+
+    get currentPage(): number {
+        return this.vm?.page ?? 1;
+    }
+
+    get showPagination(): boolean {
+        return this.hasResults && this.totalPages > 1;
+    }
+
+    get isFirstPage(): boolean {
+        return this.currentPage <= 1;
+    }
+
+    get isLastPage(): boolean {
+        return this.currentPage >= this.totalPages;
+    }
+
+    get pageButtons(): PageButton[] {
+        const total = this.totalPages;
+        const current = this.currentPage;
+        const buttons: PageButton[] = [];
+        for (let page = 1; page <= total; page += 1) {
+            buttons.push({
+                page,
+                label: String(page),
+                isCurrent: page === current,
+                ariaCurrent: page === current ? "page" : null
+            });
+        }
+        return buttons;
+    }
+
+    // ---- event handlers --------------------------------------------------
+
+    handleLanguageChange(event: CustomEvent) {
+        const selected = event.detail;
+        if (typeof selected !== "string" || selected === this.language) {
+            return;
+        }
+        this.controller?.setLanguage(selected);
+    }
+
+    handleSortChange(event: CustomEvent) {
+        const selected = event.detail;
+        if (typeof selected === "string" && isSortOption(selected)) {
+            this.controller?.setSort(selected);
+        }
+    }
+
+    handleFacetClick(event: Event) {
+        const value = (event.currentTarget as HTMLElement)?.dataset.value;
+        if (typeof value === "string") {
+            // Disjunctive toggle — the controller clears it if re-selected.
+            this.controller?.setType(value);
+        }
+    }
+
+    handlePrevPage() {
+        if (!this.isFirstPage) {
+            this.controller?.setPage(this.currentPage - 1);
+        }
+    }
+
+    handleNextPage() {
+        if (!this.isLastPage) {
+            this.controller?.setPage(this.currentPage + 1);
+        }
+    }
+
+    handlePageClick(event: Event) {
+        const raw = (event.currentTarget as HTMLElement)?.dataset.page;
+        const page = Number(raw);
+        if (Number.isFinite(page) && page >= 1) {
+            this.controller?.setPage(page);
+        }
+    }
+
+    // ---- helpers ---------------------------------------------------------
+
+    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"
+        });
+    }
+}

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

@@ -10,7 +10,8 @@
         ></arch-icon>
         <select
             name="arch-select"
-            id={labelText}
+            id="select"
+            aria-label={labelText}
             lwc:dom="manual"
             onchange={handleChange}
             value={value}