@salesforcedevs/dx-components 1.40.11 → 1.42.0

package/src/modules/dx/sidebarSearchResult/sidebarSearchResult.css

@@ -2,34 +2,74 @@
 @import "dxHelpers/text";
 @import "dxHelpers/commonTreeItem";
 
+/* List item states: Default, Hover (blue-vibrant-50 text only), Selected (cloud blue bar), Focus */
 a {
     display: flex;
     flex-direction: column;
 }
 
+/* Match "Results" heading alignment. Less item padding so total height unchanged when box has more inner padding. */
 .sidebar-item {
-    padding: var(--dx-g-spacing-smd) var(--dx-g-spacing-lg)
-        var(--dx-g-spacing-smd) var(--dx-g-global-header-padding-horizontal);
+    padding: 0 var(--dx-g-spacing-lg) 0 var(--dx-c-sidebar-left-padding);
+    background: transparent;
+    transition: background-color var(--dx-g-transition-hue-1x, 0.1s ease);
+    overflow: visible;
 }
 
-.sidebar-item:not(.sidebar-item-selected):focus-visible {
-    padding: var(--dx-g-spacing-smd) 0;
-    margin: 0 var(--dx-g-spacing-lg) 0
-        var(--dx-g-global-header-padding-horizontal);
-    outline: var(--dx-g-spacing-2xs) solid var(--dx-g-blue-vibrant-40);
-    border-radius: var(--dx-g-spacing-2xs);
+/* Inner block: more vertical padding (12px) so box has more space top/bottom; 8px horizontal. margin-left so text aligns with Results. */
+.search-result {
+    margin-left: calc(-1 * var(--dx-g-spacing-sm));
+    padding: var(--dx-g-spacing-smd) var(--dx-g-spacing-sm);
+    border: none;
+    border-radius: var(--dx-g-spacing-xs);
+    transition: background-color var(--dx-g-transition-hue-1x, 0.1s ease);
 }
 
+/* Hover: no background; text → blue-vibrant-50 (unselected and selected) */
+.sidebar-item:hover .title {
+    color: var(--dx-g-blue-vibrant-50);
+}
+
+.sidebar-item:hover .description {
+    --dx-g-text-body-color: var(--dx-g-blue-vibrant-50);
+}
+
+/* Selected: full-width cloud blue bar + 4px blue-vibrant-40 left accent; text matches unselected */
+.sidebar-item-selected {
+    background: var(--dx-g-cloud-blue-vibrant-95);
+    border-radius: 0;
+    box-shadow: inset var(--dx-g-spacing-xs) 0 0 0 var(--dx-g-blue-vibrant-40);
+
+    /* Override commonTreeItem selected text color so .title / .description tokens apply */
+    color: unset !important;
+}
+
+.sidebar-item-selected .search-result {
+    position: relative;
+    z-index: 1;
+    background: transparent;
+    color: inherit;
+}
+
+/* Focus: same ring for selected and unselected (inner .search-result, not full-width bar) */
+.sidebar-item:focus-visible {
+    outline: none !important;
+}
+
+/* Override commonTreeItem selected:focus padding/outline so focus matches unselected */
 .sidebar-item-selected:focus-visible {
-    padding: 0 var(--dx-g-spacing-lg) 0
-        var(--dx-g-global-header-padding-horizontal);
+    padding-top: 0;
+    padding-bottom: 0;
+    outline: none !important;
+}
+
+.sidebar-item:focus-visible .search-result {
     outline: none;
+    border-radius: var(--dx-g-spacing-xs);
+    border: none;
 
-    .search-result {
-        outline: var(--dx-g-spacing-2xs) solid var(--dx-g-blue-vibrant-40);
-        border-radius: var(--dx-g-spacing-2xs);
-        padding: var(--dx-g-spacing-smd) 0;
-    }
+    /* White inner ring reads clearly on selected (cloud 95) and hover backgrounds */
+    box-shadow: 0 0 0 2px white, 0 0 0 4px var(--dx-g-blue-vibrant-60);
 }
 
 .search-text {
@@ -41,6 +81,7 @@ a {
 }
 
 .description {
+    line-clamp: 3;
     -webkit-line-clamp: 3;
     overflow-wrap: break-word;
 
@@ -52,16 +93,13 @@ a {
 
 .title {
     color: var(--dx-g-text-heading-color);
+    line-height: 18px;
+    display: block;
+    margin-bottom: 4px;
 }
 
-.title:hover {
-    color: var(--dx-g-blue-vibrant-50);
-}
-
+/* Match full-doc search highlight: light yellow from dx-css-variables */
 .bold {
+    background-color: var(--dx-g-yellow-vibrant-90);
     font-weight: 700;
 }
-
-a > *:not(:last-child) {
-    margin-bottom: var(--dx-g-spacing-xs);
-}

package/src/modules/dx/sidebarSearchResult/sidebarSearchResult.ts

@@ -1,8 +1,9 @@
 import { LightningElement, api } from "lwc";
 import cx from "classnames";
-import { CoveoHighlights } from "typings/custom";
+import { track } from "dxUtils/analytics";
+import { HighlightedSections } from "typings/custom";
 
-const toChunks = (value: string, highlights: CoveoHighlights) => {
+const toChunks = (value: string, highlights: HighlightedSections) => {
     if (!highlights || highlights.length < 1) {
         return [
             {
@@ -51,11 +52,11 @@ const toChunks = (value: string, highlights: CoveoHighlights) => {
 
 export default class SidebarSearchResult extends LightningElement {
     @api description!: string;
-    @api descriptionHighlights!: CoveoHighlights;
+    @api descriptionHighlights!: HighlightedSections;
     @api href!: string;
     @api selected!: boolean;
     @api header!: string;
-    @api titleHighlights!: CoveoHighlights;
+    @api titleHighlights!: HighlightedSections;
     @api select!: Function;
 
     private get titleChunks() {
@@ -72,6 +73,13 @@ export default class SidebarSearchResult extends LightningElement {
 
     private onClick(e: PointerEvent) {
         e.preventDefault();
+        track(e.currentTarget!, "custEv_scopedSearchItemSelected", {
+            click_text: this.header,
+            click_url: this.href,
+            element_title: this.header,
+            element_type: "link",
+            content_category: "documentation"
+        });
         this.select();
         window.location.href = this.href;
     }

package/src/modules/dxUtils/openSearch/openSearch.ts

@@ -0,0 +1,343 @@
+/**
+ * OpenSearch API – shared endpoints and helpers for sidebar search,
+ * search results page, and has-results check.
+ */
+
+const STORAGE_KEY_PREFIX = "open-search:";
+
+/** OpenSearch API result item (title, url, matchedText) */
+export interface OpenSearchResultItem {
+    title?: string;
+    url?: string;
+    matchedText?: string;
+    sectionUrl?: string;
+    sectionTitle?: string;
+}
+
+/** Normalized result shape stored in cache (no selected/select; those are applied on restore). */
+export interface OpenSearchCacheItem {
+    title: string;
+    titleHighlights: Array<{ length: number; offset: number }>;
+    excerpt: string;
+    excerptHighlights: Array<{ length: number; offset: number }>;
+    uniqueId: string;
+    href: string;
+}
+
+export interface OpenSearchCache {
+    query: string;
+    results: OpenSearchCacheItem[];
+    /** Timestamp when stored (Date.now()); missing on older entries (treated as stale). */
+    storedAt?: number;
+}
+
+const CACHE_MAX_AGE_MS = 2 * 60 * 60 * 1000; // 2 hours
+
+export function isCacheStale(cache: OpenSearchCache | null): boolean {
+    if (!cache?.storedAt) {
+        return true;
+    }
+    return Date.now() - cache.storedAt > CACHE_MAX_AGE_MS;
+}
+
+/** True for absolute http(s) URLs and site-relative paths; rejects javascript:, data:, etc. */
+export function isSafeUrl(value: unknown): value is string {
+    if (typeof value !== "string" || !value) {
+        return false;
+    }
+    if (value.startsWith("/") && !value.startsWith("//")) {
+        return true;
+    }
+    try {
+        const { protocol } = new URL(value);
+        return protocol === "https:" || protocol === "http:";
+    } catch {
+        return false;
+    }
+}
+
+const isRange = (value: any): boolean =>
+    value &&
+    typeof value.length === "number" &&
+    typeof value.offset === "number";
+
+const isRangeList = (value: unknown): boolean =>
+    Array.isArray(value) && value.every(isRange);
+
+function isCacheItem(item: any): item is OpenSearchCacheItem {
+    return (
+        !!item &&
+        typeof item.title === "string" &&
+        typeof item.excerpt === "string" &&
+        typeof item.uniqueId === "string" &&
+        isSafeUrl(item.href) &&
+        isRangeList(item.titleHighlights) &&
+        isRangeList(item.excerptHighlights)
+    );
+}
+
+export function getStoredSearch(baseUrlPath: string): OpenSearchCache | null {
+    try {
+        const raw = localStorage.getItem(`${STORAGE_KEY_PREFIX}${baseUrlPath}`);
+        if (!raw) {
+            return null;
+        }
+        const parsed: any = JSON.parse(raw);
+        if (
+            !parsed ||
+            typeof parsed.query !== "string" ||
+            !Array.isArray(parsed.results) ||
+            !parsed.results.every(isCacheItem) ||
+            (parsed.storedAt !== undefined &&
+                typeof parsed.storedAt !== "number")
+        ) {
+            return null;
+        }
+        return parsed as OpenSearchCache;
+    } catch {
+        return null;
+    }
+}
+
+export function setStoredSearch(
+    baseUrlPath: string,
+    data: OpenSearchCache
+): void {
+    try {
+        const toStore: OpenSearchCache = {
+            ...data,
+            storedAt: Date.now()
+        };
+        localStorage.setItem(
+            `${STORAGE_KEY_PREFIX}${baseUrlPath}`,
+            JSON.stringify(toStore)
+        );
+    } catch {
+        /* ignore quota or disabled localStorage */
+    }
+}
+
+/**
+ * Search API URL, set through the SEARCH_API_PATH environment variable
+ * (injected at build time; see .storybook/main.js). When it isn't set, OpenSearch
+ * search is off and callers fall back to the keyword search in the old sidebar.
+ */
+export function getSearchPath(): string {
+    return process.env.SEARCH_API_PATH || "";
+}
+
+export function isOpenSearchConfigured(): boolean {
+    return getSearchPath() !== "";
+}
+
+const OPEN_SEARCH_DEFAULT_LANG = "en-us";
+export const OPEN_SEARCH_ORIGIN = "https://developer.salesforce.com";
+
+/**
+ * Locales the search index supports, as lowercase BCP 47 tags. These are the
+ * same tags doc URLs carry (`/docs/platform/ja-jp/...`) and the `lang` param
+ * expects. Mirrors KNOWN_LOCALES in rbw-search `src/urls.ts`.
+ */
+const SEARCH_LOCALES = new Set([
+    "en-us",
+    "ja-jp",
+    "de-de",
+    "fr-fr",
+    "es-es",
+    "es-mx",
+    "pt-br",
+    "it-it",
+    "nl-nl",
+    "sv-se",
+    "ko-kr",
+    "zh-cn",
+    "zh-tw",
+    "fi-fi",
+    "da-dk",
+    "nb-no",
+    "ru-ru"
+]);
+
+/**
+ * The `lang` value to search with, taken from the current doc URL:
+ * `/docs/<product>/<locale>/...` or `/docs/atlas.<locale>.<guide>/...`.
+ * Pages without a supported locale in the path search en-us.
+ */
+export function getSearchLang(): string {
+    const segments = window.location.pathname.split("/").filter(Boolean);
+    if (segments[0]?.toLowerCase() !== "docs" || !segments[1]) {
+        return OPEN_SEARCH_DEFAULT_LANG;
+    }
+    const atlas = segments[1].match(/^atlas\.([a-z]{2}-[a-z]{2})\./i);
+    const code = (atlas ? atlas[1] : segments[2] ?? "").toLowerCase();
+    return SEARCH_LOCALES.has(code) ? code : OPEN_SEARCH_DEFAULT_LANG;
+}
+
+export function getBaseUrlPath(): string {
+    const url = OPEN_SEARCH_ORIGIN + window.location.pathname;
+    const lastSlash = url.lastIndexOf("/");
+    return lastSlash > 0 ? url.substring(0, lastSlash) : url;
+}
+
+/**
+ * Read search query from URL: ?q=, ?keywords= (migrated to q), or #q=.
+ */
+export function getQueryFromUrl(): string {
+    const params = new URLSearchParams(window.location.search);
+    const keywords = params.get("keywords");
+    if (keywords) {
+        const url = new URL(window.location.href);
+        url.searchParams.delete("keywords");
+        url.searchParams.set("q", keywords);
+        window.history.replaceState(null, "", url.href);
+        return keywords;
+    }
+    const qFromSearch = params.get("q");
+    if (qFromSearch) {
+        return qFromSearch;
+    }
+    const hash = window.location.hash.slice(1);
+    if (hash) {
+        try {
+            const qFromHash = new URLSearchParams(hash).get("q");
+            if (qFromHash) {
+                return qFromHash;
+            }
+        } catch {
+            /* ignore */
+        }
+    }
+    return "";
+}
+
+/** Convert an API snippet (with <b> highlights and HTML entities) to plain text. */
+function stripTags(value: string): string {
+    return (
+        new DOMParser().parseFromString(value, "text/html").body.textContent ??
+        ""
+    );
+}
+
+/**
+ * Where a result should link: the matched section when the API returned one,
+ * else the page. The section link is only trusted when it is the page URL plus
+ * a fragment, so a malformed value can never send the user elsewhere.
+ */
+export function resultHref(item: OpenSearchResultItem): string {
+    const { url = "", sectionUrl } = item;
+    return typeof sectionUrl === "string" && sectionUrl.startsWith(`${url}#`)
+        ? sectionUrl
+        : url;
+}
+
+/**
+ * The API prefixes each snippet with the page title (plus the section title)
+ * and a blank line, and the chunk often starts by repeating its own heading.
+ * Drop both so the UI shows only the matched content.
+ */
+function stripLeadingTitle(
+    text: string,
+    title: string,
+    sectionTitle: string
+): string {
+    let body = text;
+    const separator = body.indexOf("\n\n");
+    if (separator !== -1) {
+        const head = body.slice(0, separator).trim();
+        if (head && title && head.startsWith(title.trim())) {
+            body = body.slice(separator + 2);
+        }
+    }
+    body = body.trim();
+    // "Add an Apex Trigger | Apex Developer Guide" -> "Add an Apex Trigger"
+    const pageHeading = title.split(" | ")[0].trim();
+    for (const heading of [pageHeading, sectionTitle.trim()]) {
+        if (heading && body.toLowerCase().startsWith(heading.toLowerCase())) {
+            body = body.slice(heading.length).trim();
+        }
+    }
+    return body;
+}
+
+/** "Add an Apex Trigger | Apex Developer Guide" -> "Add an Apex Trigger" */
+export function trimTitleSuffix(title: string): string {
+    const heading = title.split("|")[0].trim();
+    return heading || title.trim();
+}
+
+/** Single place that maps an API result to the shape the UI uses. */
+function normalizeApiResult(raw: any): OpenSearchResultItem {
+    const title = typeof raw?.title === "string" ? raw.title : "";
+    const sectionTitle =
+        typeof raw?.sectionTitle === "string" ? raw.sectionTitle : "";
+    const snippet = raw?.snippet ?? raw?.matchedText;
+    let matchedText =
+        typeof snippet === "string"
+            ? stripLeadingTitle(stripTags(snippet), title, sectionTitle)
+            : "";
+    // Snippets made only of words from the title (e.g. ": Create Apex Trigger")
+    // carry no content, so show the description instead.
+    const words = (value: string) => value.toLowerCase().match(/\w+/g) ?? [];
+    const titleWords = new Set(words(title));
+    if (words(matchedText).every((word) => titleWords.has(word))) {
+        matchedText =
+            typeof raw?.description === "string" ? raw.description : "";
+    }
+    return {
+        title:
+            typeof raw?.title === "string"
+                ? trimTitleSuffix(raw.title)
+                : raw?.title,
+        url: isSafeUrl(raw?.url) ? raw.url : "",
+        matchedText,
+        sectionUrl: isSafeUrl(raw?.sectionUrl) ? raw.sectionUrl : undefined,
+        sectionTitle: raw?.sectionTitle ?? undefined
+    };
+}
+
+/**
+ * Whether a result link points at the section currently open. A link with a
+ * fragment matches only that fragment; a page-level link matches on path alone.
+ */
+export function isCurrentLocation(href: string): boolean {
+    if (!href) {
+        return false;
+    }
+    try {
+        const target = new URL(href, window.location.origin);
+        if (target.pathname !== window.location.pathname) {
+            return false;
+        }
+        return !target.hash || target.hash === window.location.hash;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Run a OpenSearch. Returns the result items; callers normalize for UI.
+ */
+export async function fetchSearch(
+    searchQuery: string
+): Promise<OpenSearchResultItem[]> {
+    const query = searchQuery.trim();
+    if (!query || !isOpenSearchConfigured()) {
+        return [];
+    }
+    const params = new URLSearchParams({
+        keywords: query,
+        lang: getSearchLang(),
+        guide: getBaseUrlPath()
+    });
+    const res = await fetch(`${getSearchPath()}?${params}`);
+    if (!res.ok) {
+        throw new Error(`Search API error: ${res.status}`);
+    }
+    const data = await res.json();
+    const items = Array.isArray(data)
+        ? data
+        : data?.results ?? data?.data?.results ?? [];
+    return items
+        .map(normalizeApiResult)
+        .filter((item: OpenSearchResultItem) => item.url);
+}