@salesforcedevs/arch-components 1.28.1 → 1.29.0

package/lwc.config.json

@@ -30,6 +30,7 @@
         "arch/pageHeaderA",
         "arch/pill",
         "arch/reflectedElement",
+        "arch/searchHybrid",
         "arch/searchList",
         "arch/sectionA",
         "arch/select",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@salesforcedevs/arch-components",
-    "version": "1.28.1",
+    "version": "1.29.0",
     "description": "Architect Lightning web components",
     "license": "MIT",
     "engines": {
@@ -44,5 +44,5 @@
         "eventsourcemock": "2.0.0",
         "luxon": "3.4.4"
     },
-    "gitHead": "e0db9e8eabf2d398d8b599163aeba4261866cb29"
+    "gitHead": "5d072e2fa81d7eccadcbfb4134ee007ce2b0c7c4"
 }

package/src/modules/arch/searchHybrid/searchHybrid.css

@@ -0,0 +1,113 @@
+@import "arch/reset";
+
+:host {
+    font-size: var(--arch-font-size-md);
+    position: relative;
+    width: 100%;
+}
+
+.search-toolbar {
+    display: flex;
+    gap: var(--arch-spacing-4);
+    justify-content: flex-end;
+    margin-bottom: var(--arch-spacing-4);
+}
+
+.search-language-selector,
+.search-sort-selector {
+    display: flex;
+}
+
+.search-facets {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--arch-spacing-2);
+    margin-bottom: var(--arch-spacing-4);
+}
+
+.search-facet-chip {
+    align-items: center;
+    background-color: white;
+    border: 1px solid var(--arch-color-fog);
+    border-radius: var(--arch-radius-lg);
+    color: var(--arch-color-black);
+    cursor: pointer;
+    display: inline-flex;
+    font-family: inherit;
+    font-size: var(--arch-font-size-sm);
+    gap: var(--arch-spacing-2);
+    padding: var(--arch-spacing-1) var(--arch-spacing-3);
+}
+
+.search-facet-chip[aria-pressed="true"] {
+    background-color: var(--arch-color-meteorite);
+    border-color: var(--arch-color-meteorite);
+    color: white;
+}
+
+.search-facet-count {
+    font-size: var(--arch-font-size-xs);
+    opacity: 0.8;
+}
+
+.search-summary {
+    color: var(--arch-color-granite);
+    font-size: var(--arch-font-size-sm);
+    margin-bottom: var(--arch-spacing-4);
+}
+
+/* Semantic results list (WCAG 1.3.1) — reset the list chrome so the visual
+   is identical to the prior div-based markup. */
+.search-result-list {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+}
+
+.search-result-type {
+    color: var(--arch-color-meteorite);
+    font-size: var(--arch-font-size-sm);
+    line-height: var(--arch-line-height-snug);
+}
+
+.search-state {
+    padding: var(--arch-spacing-6) 0;
+    text-align: center;
+}
+
+.search-state-error {
+    color: var(--arch-color-error, #c23934);
+}
+
+.search-pagination {
+    align-items: center;
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--arch-spacing-2);
+    justify-content: center;
+    margin-top: var(--arch-spacing-6);
+}
+
+.search-pagination button {
+    background-color: white;
+    border: 1px solid var(--arch-color-fog);
+    border-radius: var(--arch-radius-md);
+    color: var(--arch-color-black);
+    cursor: pointer;
+    font-family: inherit;
+    font-size: var(--arch-font-size-sm);
+    min-width: 2.5rem;
+    padding: var(--arch-spacing-1) var(--arch-spacing-3);
+}
+
+.search-pagination button[disabled] {
+    cursor: default;
+    opacity: 0.5;
+}
+
+.search-pagination button[aria-current="page"] {
+    background-color: var(--arch-color-meteorite);
+    border-color: var(--arch-color-meteorite);
+    color: white;
+    opacity: 1;
+}

package/src/modules/arch/searchHybrid/searchHybrid.html

@@ -0,0 +1,164 @@
+<template>
+    <arch-section-a background="white" title="Search">
+        <div class="search-toolbar">
+            <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>
+            <div class="search-sort-selector">
+                <arch-select
+                    assistive-text="Sort results"
+                    value={sort}
+                    onchange={handleSortChange}
+                >
+                    <template for:each={sortChoices} for:item="choice">
+                        <option key={choice.id} value={choice.id}>
+                            {choice.displayText}
+                        </option>
+                    </template>
+                </arch-select>
+            </div>
+        </div>
+
+        <template lwc:if={showFacets}>
+            <div class="search-facets" role="group" aria-label="Filter by type">
+                <template for:each={contentTypeFacets} for:item="facet">
+                    <button
+                        key={facet.value}
+                        type="button"
+                        class="search-facet-chip"
+                        data-value={facet.value}
+                        aria-pressed={facet.active}
+                        onclick={handleFacetClick}
+                    >
+                        {facet.label}
+                        <span class="search-facet-count">{facet.count}</span>
+                    </button>
+                </template>
+            </div>
+        </template>
+
+        <template lwc:if={isLoading}>
+            <div class="search-state search-state-loading">
+                <arch-spinner size="medium"></arch-spinner>
+            </div>
+        </template>
+
+        <template lwc:if={isIdle}>
+            <div class="search-state search-state-idle">
+                <p>Enter a search to get started.</p>
+            </div>
+        </template>
+
+        <template lwc:if={isError}>
+            <div class="search-state search-state-error" role="alert">
+                <p>{errorMessage}</p>
+            </div>
+        </template>
+
+        <template lwc:if={isEmpty}>
+            <div class="search-state search-state-empty">
+                <center>
+                    <img
+                        src="https://developer.salesforce.com/ns-assets/ruth_search.png"
+                        alt="Search tips illustration"
+                    />
+                    <h4 style="padding-top: 8px">Here are some search tips</h4>
+                    <span style="display: block">
+                        Check the spelling of your keywords.
+                    </span>
+                    <span style="display: block">
+                        Try using fewer, different, or more general words.
+                    </span>
+                </center>
+            </div>
+        </template>
+
+        <template lwc:if={hasResults}>
+            <p class="search-summary">{summaryText}</p>
+            <ul class="search-result-list">
+                <template for:each={results} for:item="result">
+                    <li class="search-result-item" key={result.key}>
+                        <arch-summary
+                            compact
+                            display-mode="brick-tile"
+                            path={result.url}
+                            title={result.decodedTitle}
+                        >
+                            <div slot="pretitle">
+                                <template lwc:if={result.hasContentType}>
+                                    <span class="search-result-type">
+                                        {result.contentType}
+                                    </span>
+                                </template>
+                            </div>
+                            <span slot="meta-right">
+                                <template lwc:if={result.hasDate}>
+                                    <time>{result.displayDate}</time>
+                                </template>
+                            </span>
+                            <span slot="meta-left">
+                                <template lwc:if={result.hasDescription}>
+                                    {result.decodedDescription}
+                                </template>
+                            </span>
+                        </arch-summary>
+                        <!-- prettier-ignore -->
+                        <hr>
+                    </li>
+                </template>
+            </ul>
+
+            <template lwc:if={showPagination}>
+                <nav
+                    class="search-pagination"
+                    aria-label="Search results pages"
+                >
+                    <button
+                        type="button"
+                        class="search-page-prev"
+                        aria-label="Previous page"
+                        disabled={isFirstPage}
+                        onclick={handlePrevPage}
+                    >
+                        Previous
+                    </button>
+                    <template for:each={pageButtons} for:item="pageButton">
+                        <button
+                            key={pageButton.page}
+                            type="button"
+                            class="search-page-number"
+                            data-page={pageButton.page}
+                            aria-label={pageButton.label}
+                            aria-current={pageButton.ariaCurrent}
+                            disabled={pageButton.isCurrent}
+                            onclick={handlePageClick}
+                        >
+                            {pageButton.label}
+                        </button>
+                    </template>
+                    <button
+                        type="button"
+                        class="search-page-next"
+                        aria-label="Next page"
+                        disabled={isLastPage}
+                        onclick={handleNextPage}
+                    >
+                        Next
+                    </button>
+                </nav>
+            </template>
+        </template>
+    </arch-section-a>
+</template>

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