@salesforcedevs/dx-components 1.41.0 → 1.42.0-final-test

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