@salesforcedevs/dx-components 1.32.0-alpha.9 → 1.32.0-docs-content-type-1

package/src/modules/dx/globalHeader/globalHeader.ts

@@ -1,31 +1,59 @@
 import kebabCase from "lodash.kebabcase";
 import { LightningElement, api } from "lwc";
 
-const defaultDomain = "https://developer.salesforce.com";
+const defaultDomain = ""; // empty domain means the header settings will be loaded from the same domain as the current page
 const defaultLocale = "en-us";
 const defaultHeaderSettingsBasePath = "/c/public/header-settings";
-const headerSettingsJsonKeys = ['regionSelectorOverride', 'contactLinksOverride'];
+const defaultPropertyTitle = "Developers";
+const headerSettingsJsonKeys = [
+    "regionSelectorOverride",
+    "contactLinksOverride"
+];
 
 export default class DevExNavigation extends LightningElement {
+    static renderMode = "light"; // Light DOM currently required due to other elements reading from this element's DOM; we should fix that and use existing nav CSS variables in those other elements (TODO)
+
     @api locale: string = defaultLocale;
     @api path: string = defaultHeaderSettingsBasePath;
     @api domain: string = defaultDomain;
+    @api propertyTitle: string = defaultPropertyTitle; // used only as a fallback in the "barebones" nav
+
+    // Fallback basic nav config used when the header settings are not available
+    private get barebonesNavConfig() {
+        return {
+            headerSettings: {
+                origin: "",
+                contextNavEnabled: "true"
+            },
+            navItems: {
+                variation: "static",
+                propertyTitle: {
+                    label: this.propertyTitle,
+                    url: "/"
+                },
+                menuGroup: {}
+            }
+        };
+    }
 
     async connectedCallback(): Promise<void> {
+        let navConfig = null;
         try {
-            const headerSettingsResponse = await fetch(`${this.domain}${this.path}/${this.locale}.json`, {
-                headers: {
-                    "Content-Type": "application/json",
-                },
-            });
+            const headerSettingsResponse = await fetch(
+                `${this.domain}${this.path}/${this.locale}.json`,
+                {
+                    headers: {
+                        "Content-Type": "application/json"
+                    }
+                }
+            );
             if (headerSettingsResponse.ok) {
-                this.createFullNav(await headerSettingsResponse.json());
-            } else {
-                this.createBarebonesNav();
+                navConfig = await headerSettingsResponse.json();
             }
         } catch (ex) {
-            console.error(`Navigation error: ${ex}`);
-            this.createBarebonesNav();
+            console.error(`Header settings error: ${ex}`);
+        } finally {
+            this.createFullNav(navConfig || this.barebonesNavConfig);
         }
     }
 
@@ -55,22 +83,4 @@ export default class DevExNavigation extends LightningElement {
         containerEl.appendChild(hgfNav);
         containerEl.appendChild(hgfNavContext);
     }
-
-    private createBarebonesNav(): void {
-        const hgfNav = this.createGlobalNav({
-            origin: "",
-            contextNavEnabled: "true",
-        });
-        const hgfNavContext = this.createContextNav({
-            variation: "static",
-            propertyTitle: {
-                label: "Developers",
-                url: "/",
-            },
-            menuGroup: {},
-        });
-        const containerEl = this.refs.globalNavContainer as Element;
-        containerEl.appendChild(hgfNav);
-        containerEl.appendChild(hgfNavContext);
-    }
 }

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