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

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

@@ -2,55 +2,34 @@
 @import "dxHelpers/text";
 @import "dxHelpers/commonTreeItem";
 
-/* List item states per spec: Default, Hover (#F7F7F7), Selected (#E6F2FF), Focus (blue outline), Focus+Selected */
 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: 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;
+    padding: var(--dx-g-spacing-smd) var(--dx-g-spacing-lg)
+        var(--dx-g-spacing-smd) var(--dx-g-global-header-padding-horizontal);
 }
 
-/* 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);
+.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);
 }
 
-/* Hover: light grey background in box shape only */
-.sidebar-item:not(.sidebar-item-selected):hover .search-result {
-    background: var(--dx-g-gray-95);
-}
-
-/* Selected: light blue background in box shape only */
-.sidebar-item-selected {
-    box-shadow: none;
-    color: var(--dx-g-blue-vibrant-40) !important;
-}
-
-.sidebar-item-selected .search-result {
-    background: var(--dx-g-cloud-blue-vibrant-95);
-    color: inherit;
-}
-
-/* Focus: only one box – remove anchor outline (from commonTreeItem), draw single blue outline on .search-result only */
-.sidebar-item:focus-visible {
-    outline: none !important;
-}
+.sidebar-item-selected:focus-visible {
+    padding: 0 var(--dx-g-spacing-lg) 0
+        var(--dx-g-global-header-padding-horizontal);
+    outline: none;
 
-.sidebar-item:focus-visible .search-result {
-    outline: 2px solid var(--dx-g-blue-vibrant-50);
-    outline-offset: 0;
-    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;
+    }
 }
 
 .search-text {
@@ -73,13 +52,16 @@ a {
 
 .title {
     color: var(--dx-g-text-heading-color);
-    line-height: 18px;
-    display: block;
-    margin-bottom: 4px;
 }
 
-/* Match full-doc search highlight: light yellow from dx-css-variables */
+.title:hover {
+    color: var(--dx-g-blue-vibrant-50);
+}
+
 .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,9 +1,8 @@
 import { LightningElement, api } from "lwc";
 import cx from "classnames";
-import { track } from "dxUtils/analytics";
-import { HighlightedSections } from "typings/custom";
+import { CoveoHighlights } from "typings/custom";
 
-const toChunks = (value: string, highlights: HighlightedSections) => {
+const toChunks = (value: string, highlights: CoveoHighlights) => {
     if (!highlights || highlights.length < 1) {
         return [
             {
@@ -52,11 +51,11 @@ const toChunks = (value: string, highlights: HighlightedSections) => {
 
 export default class SidebarSearchResult extends LightningElement {
     @api description!: string;
-    @api descriptionHighlights!: HighlightedSections;
+    @api descriptionHighlights!: CoveoHighlights;
     @api href!: string;
     @api selected!: boolean;
     @api header!: string;
-    @api titleHighlights!: HighlightedSections;
+    @api titleHighlights!: CoveoHighlights;
     @api select!: Function;
 
     private get titleChunks() {
@@ -73,13 +72,6 @@ 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/dx/tree/treeHandler.ts

@@ -64,7 +64,8 @@ export class TreeHandler {
             isExpanded: node.isExpanded || false,
             isChildrenLoading: node.isChildrenLoading || false,
             link: node.link,
-            method: node.method
+            method: node.method,
+            showForwardArrow: node.showForwardArrow
         };
 
         const mapItem = { node: convertedNode, parent };

package/src/modules/dx/treeTile/treeTile.css

@@ -58,6 +58,10 @@
     margin-left: var(--dx-g-spacing-xs);
 }
 
+.tile-forward-arrow {
+    margin-left: auto;
+}
+
 .whitespace-nowrap {
     white-space: nowrap;
 }

package/src/modules/dx/treeTile/treeTile.html

@@ -37,6 +37,16 @@
                 value={methodText}
                 color={metadataBadgeColor}
             ></dx-metadata-badge>
+            <div
+                class="flex tile-icon tile-forward-arrow"
+                if:true={showForwardArrow}
+            >
+                <dx-icon
+                    sprite="utility"
+                    symbol="forward"
+                    size={iconSize}
+                ></dx-icon>
+            </div>
         </div>
     </a>
 </template>

package/src/modules/dx/treeTile/treeTile.ts

@@ -52,6 +52,10 @@ export default class TreeTile extends LightningElement {
         return this.treeNode.method && !this.hasChildren;
     }
 
+    private get showForwardArrow() {
+        return this.treeNode.showForwardArrow;
+    }
+
     private get methodText() {
         if (this.treeNode.method && this.treeNode.method in methodTextMap) {
             return methodTextMap[this.treeNode.method];

package/src/modules/dxUtils/async/async.ts

@@ -43,3 +43,35 @@ export function pollUntil(
         }
     });
 }
+
+/**
+ * Returns the same settled value or rejection as `promise`, or rejects after `forMaximumMs`
+ * if it does not settle in time. When `forMaximumMs` is omitted or non-positive, returns
+ * `promise` unchanged. Clears the timeout when `promise` settles first.
+ */
+export function waitUntilResolved<T>(
+    promise: Promise<T>,
+    forMaximumMs?: number,
+    timeoutMessage = "Timed out waiting for promise to settle."
+): Promise<T> {
+    if (forMaximumMs == null || forMaximumMs <= 0) {
+        return promise;
+    }
+
+    return new Promise<T>((resolve, reject) => {
+        const timeoutId = setTimeout(() => {
+            reject(new Error(timeoutMessage));
+        }, forMaximumMs);
+
+        promise.then(
+            (value) => {
+                clearTimeout(timeoutId);
+                resolve(value);
+            },
+            (reason: unknown) => {
+                clearTimeout(timeoutId);
+                reject(reason);
+            }
+        );
+    });
+}

package/src/modules/dxUtils/searchLocalePrefs/searchLocalePrefs.ts

@@ -0,0 +1,193 @@
+/**
+ * @file Developer-site implementation of docUtils `LocaleDeps` for the unified
+ * hybrid search UI (P4.1). Supplies per-device storage of the user's chosen
+ * search language (consent-gated behind OneTrust functional-cookie consent) and
+ * a browser-language -> supported-locale resolver.
+ *
+ * dx has no equivalent of arch/localePreference or arch/browserLocale and no
+ * shared consent util, so this mirrors the consent read used elsewhere in the
+ * org (the OptanonConsent cookie's `groups` field, functional category C0003).
+ * OneTrust's standard functional group id is C0003; "C0003:1" means granted,
+ * "C0003:0" means denied. We never persist a preference without an explicit
+ * grant.
+ *
+ * Exposes `searchLocalePrefs`, an object implementing the docUtils LocaleDeps
+ * shape ({ getStored, setStored, resolveBrowser }), plus a `buildSearchLocalePrefs`
+ * factory for tests / dependency injection.
+ */
+
+import type { LocaleDeps } from "docUtils/searchLocale";
+
+export const STORAGE_KEY = "dx-search-language";
+export const FUNCTIONAL_GROUP_ID = "C0003";
+export const DEFAULT_LOCALE = "en-us";
+
+/**
+ * Region/script-aware overrides for cases a plain language-only match can't
+ * resolve. Keys are normalized lowercase BCP-47 tags (or language-only codes);
+ * values are site locale ids. Order of checks: exact id -> these rules ->
+ * language-only first match -> default.
+ *
+ * Mirrors the product decisions baked into arch/browserLocale:
+ *   - bare "es" -> es-mx (es-mx is the generic Spanish)
+ *   - any pt-* -> pt-br (only Brazilian Portuguese is published)
+ *   - no/nb/nn -> nb-no (only Norwegian id)
+ *   - Chinese is matched on script/region, never collapsed to language-only.
+ */
+const TAG_OVERRIDES: Record<string, string> = {
+    // Chinese — Traditional
+    "zh-tw": "zh-tw",
+    "zh-hant": "zh-tw",
+    "zh-hk": "zh-tw",
+    "zh-mo": "zh-tw",
+    // Chinese — Simplified (and bare "zh")
+    zh: "zh-cn",
+    "zh-cn": "zh-cn",
+    "zh-hans": "zh-cn",
+    "zh-sg": "zh-cn",
+    // Spanish
+    es: "es-mx",
+    "es-es": "es-es",
+    // Portuguese (only pt-br exists)
+    pt: "pt-br",
+    "pt-pt": "pt-br",
+    // Norwegian (only nb-no exists)
+    no: "nb-no",
+    nb: "nb-no",
+    nn: "nb-no"
+};
+
+/**
+ * Read the OptanonConsent cookie and return whether the functional group is
+ * granted. Defensive: if OneTrust hasn't loaded or the cookie is absent
+ * (tests, pre-consent, non-prod), returns false so we never persist without an
+ * explicit grant.
+ */
+export function hasFunctionalConsent(): boolean {
+    try {
+        const cookie = document.cookie
+            .split("; ")
+            .find((row) => row.startsWith("OptanonConsent="));
+        if (!cookie) {
+            return false;
+        }
+        // The cookie value is URL-encoded querystring-style, e.g.
+        // "...&groups=C0001:1,C0003:1,C0002:0&...".
+        const value = decodeURIComponent(cookie.split("=").slice(1).join("="));
+        const groups = new URLSearchParams(value).get("groups");
+        if (!groups) {
+            return false;
+        }
+        return groups
+            .split(",")
+            .some((entry) => entry.trim() === `${FUNCTIONAL_GROUP_ID}:1`);
+    } catch (e) {
+        return false;
+    }
+}
+
+/**
+ * Map a single language-only code (e.g. "ja", "de") to its site locale id by
+ * finding the first supported id whose language subtag matches.
+ */
+function languageOnlyMatch(
+    language: string,
+    supportedIds: string[]
+): string | undefined {
+    return supportedIds.find((id) => id.split("-")[0] === language);
+}
+
+/**
+ * Get the stored language preference, or null if none / unavailable. Reading an
+ * already-stored preference is low-risk, so it is NOT consent-gated.
+ */
+export function getStoredLanguage(): string | null {
+    try {
+        return window.localStorage.getItem(STORAGE_KEY);
+    } catch (e) {
+        return null;
+    }
+}
+
+/**
+ * Persist the chosen language, but only if the user has granted functional
+ * consent. Returns true if the value was written, false if it was skipped (no
+ * consent) or failed. When skipped, the choice still applies for the current
+ * page/session via in-memory state and the ?lang= URL param.
+ */
+export function setStoredLanguage(language: string): boolean {
+    if (!language || !hasFunctionalConsent()) {
+        return false;
+    }
+    try {
+        window.localStorage.setItem(STORAGE_KEY, language);
+        return true;
+    } catch (e) {
+        return false;
+    }
+}
+
+/**
+ * Resolve the best site locale id for the given browser languages. The first
+ * browser language that maps to a supported id wins; earlier entries take
+ * precedence over later ones (matching navigator.languages ordering).
+ * Returns "en-us" if nothing matches.
+ */
+export function resolveBrowserLocale(
+    navigatorLanguages: readonly string[] | undefined,
+    supportedIds: string[]
+): string {
+    if (!navigatorLanguages || navigatorLanguages.length === 0) {
+        return DEFAULT_LOCALE;
+    }
+
+    const supported = new Set(supportedIds);
+
+    for (const raw of navigatorLanguages) {
+        if (!raw) {
+            continue;
+        }
+        const tag = raw.toLowerCase();
+
+        // 1. Exact id match (e.g. "ja-jp" -> ja-jp).
+        if (supported.has(tag)) {
+            return tag;
+        }
+
+        // 2. Region/script override (e.g. "zh-tw" -> zh-tw, "es" -> es-mx).
+        const overridden = TAG_OVERRIDES[tag];
+        if (overridden && supported.has(overridden)) {
+            return overridden;
+        }
+
+        // 3. Language-only fall-through (e.g. "de-ch" -> de -> de-de).
+        const language = tag.split("-")[0];
+        const overriddenLang = TAG_OVERRIDES[language];
+        if (overriddenLang && supported.has(overriddenLang)) {
+            return overriddenLang;
+        }
+        const matched = languageOnlyMatch(language, supportedIds);
+        if (matched) {
+            return matched;
+        }
+    }
+
+    return DEFAULT_LOCALE;
+}
+
+/**
+ * Build a docUtils LocaleDeps bundle for the developer site. Exposed as a
+ * factory so tests / callers can inject overrides; the default-exported
+ * `searchLocalePrefs` is the production singleton.
+ */
+export function buildSearchLocalePrefs(
+    overrides: Partial<LocaleDeps> = {}
+): LocaleDeps {
+    return {
+        getStored: overrides.getStored ?? getStoredLanguage,
+        setStored: overrides.setStored ?? setStoredLanguage,
+        resolveBrowser: overrides.resolveBrowser ?? resolveBrowserLocale
+    };
+}
+
+export const searchLocalePrefs: LocaleDeps = buildSearchLocalePrefs();

package/LICENSE

@@ -1,12 +0,0 @@
-Copyright (c) 2020, Salesforce.com, Inc.
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-
-* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-
-* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-
-* Neither the name of Salesforce.com nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/src/modules/dxUtils/data360Search/data360Search.ts

@@ -1,168 +0,0 @@
-/**
- * Data 360 search API – shared endpoints and helpers for sidebar search,
- * search results page, and has-results check.
- */
-
-const STORAGE_KEY_PREFIX = "data360-search:";
-
-/** Data 360 Search API result item (title, url, matchedText) */
-export interface Data360SearchResultItem {
-    title?: string;
-    url?: string;
-    matchedText?: string;
-}
-
-/** Normalized result shape stored in cache (no selected/select; those are applied on restore). */
-export interface Data360SearchCacheItem {
-    title: string;
-    titleHighlights: Array<{ length: number; offset: number }>;
-    excerpt: string;
-    excerptHighlights: Array<{ length: number; offset: number }>;
-    uniqueId: string;
-    href: string;
-}
-
-export interface Data360SearchCache {
-    query: string;
-    results: Data360SearchCacheItem[];
-    /** 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: Data360SearchCache | null): boolean {
-    if (!cache?.storedAt) {
-        return true;
-    }
-    return Date.now() - cache.storedAt > CACHE_MAX_AGE_MS;
-}
-
-export function getStoredSearch(
-    baseUrlPath: string
-): Data360SearchCache | null {
-    try {
-        const raw = localStorage.getItem(`${STORAGE_KEY_PREFIX}${baseUrlPath}`);
-        if (!raw) {
-            return null;
-        }
-        const parsed = JSON.parse(raw) as Data360SearchCache;
-        if (
-            !parsed ||
-            typeof parsed.query !== "string" ||
-            !Array.isArray(parsed.results)
-        ) {
-            return null;
-        }
-        return parsed;
-    } catch {
-        return null;
-    }
-}
-
-export function setStoredSearch(
-    baseUrlPath: string,
-    data: Data360SearchCache
-): void {
-    try {
-        const toStore: Data360SearchCache = {
-            ...data,
-            storedAt: Date.now()
-        };
-        localStorage.setItem(
-            `${STORAGE_KEY_PREFIX}${baseUrlPath}`,
-            JSON.stringify(toStore)
-        );
-    } catch {
-        /* ignore quota or disabled localStorage */
-    }
-}
-
-export const DATA_360_SEARCH_PATH = "/data-360-search/search";
-export const DATA_360_HAS_RESULTS_PATH = "/data-360-search/has-results";
-export const DATA_360_SEARCH_ORIGIN = "https://developer.salesforce.com";
-
-export function getBaseUrlPath(): string {
-    const url = DATA_360_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 "";
-}
-
-/**
- * Quick check if the current page has searchable results.
- * Only when this returns true should the Data 360 sidebar be shown.
- */
-export async function fetchHasResults(): Promise<boolean> {
-    try {
-        const res = await fetch(DATA_360_HAS_RESULTS_PATH, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ baseUrlPath: getBaseUrlPath() })
-        });
-        if (!res.ok) {
-            return false;
-        }
-        const data = await res.json();
-        return data.hasResults === true;
-    } catch {
-        return false;
-    }
-}
-
-/**
- * Run a Data 360 search. Returns the raw result items; callers normalize for UI.
- */
-export async function fetchSearch(
-    searchQuery: string
-): Promise<Data360SearchResultItem[]> {
-    const query = searchQuery.trim();
-    if (!query) {
-        return [];
-    }
-    const res = await fetch(DATA_360_SEARCH_PATH, {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({
-            searchQuery: query,
-            baseUrlPath: getBaseUrlPath()
-        })
-    });
-    if (!res.ok) {
-        throw new Error(`Search API error: ${res.status}`);
-    }
-    const data = await res.json();
-    return Array.isArray(data)
-        ? data
-        : data?.results ?? data?.data?.results ?? [];
-}