@salesforcedevs/dx-components 1.37.2 → 1.39.0-alpha1

package/lwc.config.json

@@ -72,6 +72,7 @@
         "dx/iconBadge",
         "dx/imageAndLabel",
         "dx/input",
+        "dx/instrumentation",
         "dx/interactiveImage",
         "dx/logo",
         "dx/mainContentHeader",

package/package.json

@@ -1,48 +1,48 @@
 {
-    "name": "@salesforcedevs/dx-components",
-    "version": "1.37.2",
-    "description": "DX Lightning web components",
-    "license": "MIT",
-    "engines": {
-        "node": "22.x"
-    },
-    "publishConfig": {
-        "access": "public"
-    },
-    "dependencies": {
-        "@coveo/headless": "3.22.2",
-        "@floating-ui/dom": "1.5.1",
-        "@optimizely/optimizely-sdk": "5.3.0",
-        "@shikijs/colorized-brackets": "^3.12.2",
-        "@types/throttle-debounce": "5.0.2",
-        "@vimeo/player": "2.22.0",
-        "classnames": "2.5.1",
-        "composed-offset-position": "0.0.4",
-        "coveo-search-ui": "2.10113.0",
-        "debounce": "1.2.1",
-        "js-cookie": "3.0.5",
-        "lodash.defaults": "4.2.0",
-        "lodash.get": "4.4.2",
-        "lodash.kebabcase": "4.1.1",
-        "memoize-one": "6.0.0",
-        "microtip": "0.2.2",
-        "shiki": "^3.12.2",
-        "throttle-debounce": "5.0.0",
-        "uuid": "9.0.1"
-    },
-    "devDependencies": {
-        "@types/classnames": "2.3.1",
-        "@types/debounce": "1.2.4",
-        "@types/js-cookie": "3.0.6",
-        "@types/lodash.defaults": "4.2.9",
-        "@types/lodash.get": "4.4.9",
-        "@types/lodash.kebabcase": "4.1.9",
-        "@types/luxon": "3.4.2",
-        "@types/uuid": "8.3.4",
-        "@types/vimeo__player": "2.18.3",
-        "eventsourcemock": "2.0.0",
-        "luxon": "3.4.4",
-        "msw": "^2.12.4"
-    },
-    "gitHead": "ca79eefb9b9ec80bb48c96a091fd0ce558bda710"
-}
+  "name": "@salesforcedevs/dx-components",
+  "version": "1.39.0-alpha1",
+  "description": "DX Lightning web components",
+  "license": "MIT",
+  "engines": {
+    "node": "22.x"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@coveo/headless": "3.22.2",
+    "@floating-ui/dom": "1.5.1",
+    "@optimizely/optimizely-sdk": "5.3.0",
+    "@shikijs/colorized-brackets": "^3.12.2",
+    "@types/throttle-debounce": "5.0.2",
+    "@vimeo/player": "2.22.0",
+    "classnames": "2.5.1",
+    "composed-offset-position": "0.0.4",
+    "coveo-search-ui": "2.10113.0",
+    "debounce": "1.2.1",
+    "js-cookie": "3.0.5",
+    "lodash.defaults": "4.2.0",
+    "lodash.get": "4.4.2",
+    "lodash.kebabcase": "4.1.1",
+    "memoize-one": "6.0.0",
+    "microtip": "0.2.2",
+    "shiki": "^3.12.2",
+    "throttle-debounce": "5.0.0",
+    "uuid": "9.0.1"
+  },
+  "devDependencies": {
+    "@types/classnames": "2.3.1",
+    "@types/debounce": "1.2.4",
+    "@types/js-cookie": "3.0.6",
+    "@types/lodash.defaults": "4.2.9",
+    "@types/lodash.get": "4.4.9",
+    "@types/lodash.kebabcase": "4.1.9",
+    "@types/luxon": "3.4.2",
+    "@types/uuid": "8.3.4",
+    "@types/vimeo__player": "2.18.3",
+    "eventsourcemock": "2.0.0",
+    "luxon": "3.4.4",
+    "msw": "^2.12.4"
+  },
+  "stableVersion": "1.39.0"
+}

package/src/modules/dx/footer/footer.ts

@@ -103,7 +103,9 @@ class Footer extends LightningElement {
 // This encapsulates the old non-MFE footer functionality that should be removed once the footer MFE supports rendering in non-full-width contexts.
 // It's encapsulated like this solely for ease of deletion later.
 function augmentWithNonMFEFooterFunctionality(FooterClass: typeof Footer) {
-    const baseSocialIconUrl = `/assets/icons/brand-sprite/svg/symbols.svg`;
+    // Prefix with the deploy asset base path (e.g. "/PR-123"); empty in local dev.
+    const assetBasePath = (globalThis as any)?.LWR?.env?.assetBasePath || "";
+    const baseSocialIconUrl = `${assetBasePath}/assets/icons/brand-sprite/svg/symbols.svg`;
 
     return class NonMFEFooter extends FooterClass {
         private didRequestFooterConfig = false;

package/src/modules/dx/icon/icon.ts

@@ -40,7 +40,10 @@ export default class Icon extends LightningElement {
     }
 
     private get assetUrl() {
-        return `/assets/icons/${this.sprite}-sprite/svg/symbols.svg`;
+        // Prefix with the deploy asset base path (e.g. "/PR-123") so icons resolve
+        // when the site is served under a sub-path. Empty in local dev, so no-op there.
+        const assetBasePath = (globalThis as any)?.LWR?.env?.assetBasePath || "";
+        return `${assetBasePath}/assets/icons/${this.sprite}-sprite/svg/symbols.svg`;
     }
 
     private get href() {

package/src/modules/dx/instrumentation/instrumentation.html

@@ -0,0 +1 @@
+<template></template>

package/src/modules/dx/instrumentation/instrumentation.ts

@@ -0,0 +1,200 @@
+import { LightningElement, api } from "lwc";
+import {
+    TRACKING_EVENT_NAME as DX_TRACKING_EVENT_NAME,
+    LISTENER_QUEUE as DX_LISTENER_QUEUE,
+    LISTENER_INDICATOR as DX_LISTENER_INDICATOR,
+    track as dxTrack
+} from "dxUtils/analytics";
+
+// Architect ("architectssite_track") namespace. These mirror the constants used
+// by <arch-instrumentation> in @salesforcedevs/arch-components. They are declared
+// locally rather than imported because dx-components does not depend on
+// arch-components.
+const ARCH_TRACKING_EVENT_NAME = "architectssite_track";
+const ARCH_LISTENER_QUEUE = "__TDS_INSTRUMENTATION_QUEUE__";
+const ARCH_LISTENER_INDICATOR = "__TDS_INSTRUMENTATION_IS_INITIALIZED__";
+
+// Arch-namespace equivalent of dxUtils/analytics `track`: either dispatch the
+// architect tracking event (once the listener is mounted) or queue it. Used to
+// replay events that were queued in __TDS_INSTRUMENTATION_QUEUE__ before this
+// component mounted.
+function archTrack(
+    element: EventTarget,
+    event: string,
+    payload: Record<string, unknown>
+): void {
+    const detail = { event, payload };
+    if ((window as any)[ARCH_LISTENER_INDICATOR] === undefined) {
+        (window as any)[ARCH_LISTENER_QUEUE] =
+            (window as any)[ARCH_LISTENER_QUEUE] || [];
+        (window as any)[ARCH_LISTENER_QUEUE].push(detail);
+    } else {
+        const e = new CustomEvent(ARCH_TRACKING_EVENT_NAME, {
+            bubbles: true,
+            composed: true,
+            detail
+        });
+        element.dispatchEvent(e);
+    }
+}
+
+interface NamespaceConfig {
+    eventName: string;
+    queue: string;
+    indicator: string;
+    replay: (
+        element: EventTarget,
+        event: string,
+        payload: Record<string, unknown>
+    ) => void;
+}
+
+// The two tracking-event namespaces dx-instrumentation can bridge. Keyed by the
+// values accepted by the `namespaces` attribute.
+const NAMESPACE_CONFIGS: Record<"developer" | "architect", NamespaceConfig> = {
+    developer: {
+        eventName: DX_TRACKING_EVENT_NAME,
+        queue: DX_LISTENER_QUEUE,
+        indicator: DX_LISTENER_INDICATOR,
+        replay: dxTrack
+    },
+    architect: {
+        eventName: ARCH_TRACKING_EVENT_NAME,
+        queue: ARCH_LISTENER_QUEUE,
+        indicator: ARCH_LISTENER_INDICATOR,
+        replay: archTrack
+    }
+};
+
+// Maps the `namespaces` attribute to the configs it activates.
+function resolveNamespaceConfigs(namespaces: string): NamespaceConfig[] {
+    switch (namespaces) {
+        case "developer":
+            return [NAMESPACE_CONFIGS.developer];
+        case "architect":
+            return [NAMESPACE_CONFIGS.architect];
+        case "both":
+        default:
+            return [NAMESPACE_CONFIGS.developer, NAMESPACE_CONFIGS.architect];
+    }
+}
+
+const googleTagManager = {
+    track: function (e: Event) {
+        if ((window as any).dataLayer === undefined) {
+            (window as any).dataLayer = [];
+        }
+        const { event, payload } = (e as CustomEvent).detail;
+        (window as any).dataLayer.push({ ...payload, event });
+    }
+};
+
+interface TrackEventListener {
+    add: () => void;
+    remove: () => void;
+}
+
+/**
+ * Attaches a listener for each of the given tracking event names (e.g.
+ * `developerwebsite_track` and/or `architectssite_track`), forwarding every
+ * caught event to every tracker function. A single component can therefore
+ * bridge one or both event namespaces into the dataLayer.
+ */
+export function instrumentationTrackEventListener(
+    trackerFns: { track: (e: Event) => void }[] = [],
+    eventNames: string[] = [DX_TRACKING_EVENT_NAME, ARCH_TRACKING_EVENT_NAME]
+): TrackEventListener {
+    if (trackerFns.length === 0) {
+        throw new Error("No tracker functions passed");
+    }
+
+    const handleTrackEvent = (e: Event) => {
+        trackerFns.forEach((tracker) => {
+            tracker.track(e);
+        });
+    };
+
+    const attachEventListener = () => {
+        eventNames.forEach((eventName) => {
+            document.addEventListener(eventName, handleTrackEvent);
+        });
+    };
+
+    const removeEventListener = () => {
+        eventNames.forEach((eventName) => {
+            document.removeEventListener(eventName, handleTrackEvent);
+        });
+    };
+
+    return {
+        add: attachEventListener,
+        remove: removeEventListener
+    };
+}
+
+/**
+ * Unified instrumentation bridge. Mount a single <dx-instrumentation> to forward
+ * developer-website and/or architect-website tracking events into the GTM
+ * dataLayer. Renders nothing.
+ *
+ * By default (`namespaces="both"`) it bridges both the developer
+ * (`developerwebsite_track`) and architect (`architectssite_track`) namespaces,
+ * replacing the need to mount <dw-instrumentation> and <arch-instrumentation>
+ * separately. Set `namespaces="developer"` (or `"architect"`) to bridge only one
+ * — e.g. on a site whose header analytics already reach the dataLayer through
+ * another path, so draining the architect queue here would double-count.
+ */
+export default class Instrumentation extends LightningElement {
+    @api useGoogleTagManager = false;
+
+    // "both" (default) | "developer" | "architect"
+    @api namespaces = "both";
+
+    private tracker: TrackEventListener | null = null;
+
+    private setupTracker() {
+        const configs = resolveNamespaceConfigs(this.namespaces);
+        const trackerFunctions = this.useGoogleTagManager
+            ? [googleTagManager]
+            : [];
+        this.tracker = instrumentationTrackEventListener(
+            trackerFunctions,
+            configs.map((c) => c.eventName)
+        );
+        this.tracker.add();
+        // Mark each active namespace initialized so track() calls from that
+        // stack dispatch live events instead of queueing.
+        configs.forEach((c) => {
+            (window as any)[c.indicator] = true;
+        });
+    }
+
+    private dispatchQueuedEvents() {
+        resolveNamespaceConfigs(this.namespaces).forEach((config) => {
+            const queue = (window as any)[config.queue];
+            if (Array.isArray(queue)) {
+                while (queue.length > 0) {
+                    const event = queue.pop() as {
+                        event: string;
+                        payload: Record<string, unknown>;
+                    };
+                    config.replay(this, event.event, event.payload);
+                }
+            }
+        });
+    }
+
+    renderedCallback() {
+        if (this.tracker === null) {
+            this.setupTracker();
+            this.dispatchQueuedEvents();
+        }
+    }
+
+    disconnectedCallback() {
+        if (this.tracker !== null) {
+            this.tracker.remove();
+            this.tracker = null;
+        }
+    }
+}

package/src/modules/dx/searchResults/resultsTemplate.js

@@ -5,6 +5,9 @@
 */
 const html = String.raw;
 
+// Prefix hardcoded asset URLs with the deploy asset base path (e.g. "/PR-123"); empty in local dev.
+const assetBasePath = (globalThis && globalThis.LWR && globalThis.LWR.env && globalThis.LWR.env.assetBasePath) || "";
+
 export default html`
     <div class="coveo-show-if-no-results">
         <div class="no-results">
@@ -70,7 +73,7 @@ export default html`
                 >
                     <%- title %>
                     <% if (!raw.uri.includes('developer.salesforce.com') && !raw.uri.includes('developer-website-s.herokuapp.com')) { %>
-                        <svg xmlns="http://www.w3.org/2000/svg" style="display: inline; vertical-align: baseline;" fill="var(--dx-g-blue-vibrant-20)" width="20" height="20" part="svg" aria-hidden="true"><use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#new_window"></use></svg>
+                        <svg xmlns="http://www.w3.org/2000/svg" style="display: inline; vertical-align: baseline;" fill="var(--dx-g-blue-vibrant-20)" width="20" height="20" part="svg" aria-hidden="true"><use xlink:href="${assetBasePath}/assets/icons/utility-sprite/svg/symbols.svg#new_window"></use></svg>
                     <% } %>
                 </a>
                 <span class="CoveoFieldValue" data-field="@sflastmodifieddate" data-helper="postedDate" data-html-value="true"></span>
@@ -121,7 +124,7 @@ export default html`
                         <%- uri %>
                     <% } %>
                     <% if (!raw.uri.includes('developer.salesforce.com') && !raw.uri.includes('developer-website-s.herokuapp.com')) { %>
-                            <svg xmlns="http://www.w3.org/2000/svg" style="display: inline; vertical-align: baseline;" fill="var(--dx-g-blue-vibrant-20)" width="20" height="20" part="svg" aria-hidden="true"><use xlink:href="/assets/icons/utility-sprite/svg/symbols.svg#new_window"></use></svg>
+                            <svg xmlns="http://www.w3.org/2000/svg" style="display: inline; vertical-align: baseline;" fill="var(--dx-g-blue-vibrant-20)" width="20" height="20" part="svg" aria-hidden="true"><use xlink:href="${assetBasePath}/assets/icons/utility-sprite/svg/symbols.svg#new_window"></use></svg>
                     <% } %>
                 </a>
                 <span class="CoveoFieldValue" data-field="@sflastmodifieddate" data-helper="postedDate" data-html-value="true"></span>

package/src/modules/dx/searchResults/searchResults.ts

@@ -54,6 +54,8 @@ const buildTemplateHelperBadge = (value: keyof typeof CONTENT_TYPE_LABELS) => {
     const style = getContentTypeColorVariables(value);
     const label = CONTENT_TYPE_LABELS[value];
     const { iconSprite, iconSymbol } = CONTENT_TYPE_ICONS[value];
+    // Prefix with the deploy asset base path (e.g. "/PR-123"); empty in local dev.
+    const assetBasePath = (globalThis as any)?.LWR?.env?.assetBasePath || "";
     return `
             <div style="${style}" class="dx-badge">
                 <svg

package/src/modules/dx/sidebarSearch/sidebarSearch.ts

@@ -317,9 +317,12 @@ export default class SidebarSearch extends LightningElement {
 
         // discussion about this normalization here: https://salesforce-internal.slack.com/archives/C020S6784JX/p1639506238376600
 
+        // Deploy base path (e.g. "/PR-123"); empty in local dev. window.location.pathname
+        // is served under this prefix, so route hrefs and comparisons must include it.
+        const basePath = (globalThis as any)?.LWR?.env?.basePath || "";
         let pathname, queryParam;
         if (sfhtml_url__c) {
-            pathname = `/docs/${sfhtml_url__c}`;
+            pathname = `${basePath}/docs/${sfhtml_url__c}`;
         } else {
             const isNestedGuide = clickUri.includes("/guide/");
             const url = new URL(clickUri);

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.