@salesforcedevs/dx-components 1.40.4 → 1.40.5-final-alpha

package/lwc.config.json

@@ -140,6 +140,7 @@
         "dxUtils/lwc",
         "dxUtils/urlWatcher",
         "dxUtils/normalizers",
+        "dxUtils/topicVersion",
         "dxUtils/queryCoordinator",
         "dxUtils/recentSearches",
         "dxUtils/regexps",

package/package.json

@@ -1,48 +1,47 @@
 {
-    "name": "@salesforcedevs/dx-components",
-    "version": "1.40.4",
-    "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": "37647f2998066bc5a3e345e3bfdbd70dfefa5adc"
-}
+  "name": "@salesforcedevs/dx-components",
+  "version": "1.40.5-final-alpha",
+  "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"
+  }
+}

package/src/modules/dx/button/button.css

@@ -86,11 +86,11 @@
 }
 
 .button.icon-right:not(.slot-empty) > *:nth-child(2) {
-    margin-left: var(--dx-g-spacing-sm);
+    margin-left: var(--dx-c-button-icon-gap, var(--dx-g-spacing-sm));
 }
 
 .button.icon-left:not(.slot-empty) > *:nth-child(2) {
-    margin-right: var(--dx-g-spacing-sm);
+    margin-right: var(--dx-c-button-icon-gap, var(--dx-g-spacing-sm));
 }
 
 .button.style-icon.slot-empty {

package/src/modules/dx/dropdown/dropdown.css

@@ -14,12 +14,40 @@
     display: none;
 }
 
+/* Opt-in fit-content menu: hugs the labels (so it can be as narrow as the
+   shortest one) and stops at --dx-c-dropdown-menu-max-width. Defaults still
+   truncate; set --dx-c-dropdown-fit-white-space: normal to wrap instead. */
+.menu-fit-content::part(content) {
+    box-sizing: border-box;
+    width: max-content;
+    max-width: var(
+        --dx-c-dropdown-menu-max-width,
+        calc(100vw - var(--dx-g-spacing-lg))
+    );
+}
+
 .menu-fit-content {
+    --dx-c-dropdown-option-min-width: 0;
+    --dx-c-dropdown-option-label-display: block;
+    --dx-c-dropdown-option-white-space: var(
+        --dx-c-dropdown-fit-white-space,
+        nowrap
+    );
+    --dx-c-dropdown-option-overflow: var(--dx-c-dropdown-fit-overflow, hidden);
+    --dx-c-dropdown-option-text-overflow: var(
+        --dx-c-dropdown-fit-text-overflow,
+        ellipsis
+    );
+}
+
+/* Nested fit-content menus (content action toolbar). Flat fit-content menus,
+   including the version picker, keep the option rules above. */
+.menu-fit-content.menu-nested {
     --dx-c-popover-width: max-content;
     --dx-c-popover-padding: var(--dx-g-spacing-sm) 0;
 }
 
-.menu-fit-content .menu_list {
+.menu-fit-content.menu-nested .menu_list {
     width: 100%;
     align-items: flex-start;
     gap: var(--dx-g-spacing-sm);

package/src/modules/dx/dropdown/dropdown.html

@@ -9,7 +9,7 @@
         open-on-hover={openOnHover}
         open={open}
         page-padding={pagePadding}
-        placement={placement}
+        placement={effectivePlacement}
         small={small}
         width={effectiveWidth}
     >

package/src/modules/dx/dropdown/dropdown.ts

@@ -82,20 +82,35 @@ export default class Dropdown extends LightningElement {
         return this.areOptionsEmpty ? null : "menu";
     }
 
+    // "fit-end" is fit-content, aligned to the trigger's end edge.
+    // "full" matches the trigger width. "fixed" and "fit-content" are unchanged.
     private get isFitContent() {
-        return this.widthMode === "fit-content";
+        return this.widthMode === "fit-content" || this.widthMode === "fit-end";
     }
 
+    private get effectivePlacement(): PopperPlacement | undefined {
+        return this.widthMode === "fit-end" ? "bottom-end" : this.placement;
+    }
+
+    // fit-content takes precedence; the misuse is surfaced in className() below.
     private get effectiveWidth() {
         return this.isFitContent ? null : this.width;
     }
 
     private get effectiveFullWidth() {
+        if (this.widthMode === "full") {
+            return true;
+        }
         return this.isFitContent ? false : this.fullWidth;
     }
 
     private get className() {
         const fitContent = this.isFitContent;
+        if (fitContent && (this.width || this.fullWidth)) {
+            console.error(
+                'The "width-mode=fit-content" and "width"/"full-width" properties cannot be provided simultaneously. "width-mode=fit-content" is prioritized; "width"/"full-width" are ignored.'
+            );
+        }
         return cx(
             this.isNested && "menu-nested",
             this.isNested &&

package/src/modules/dx/dropdownOption/dropdownOption.css

@@ -25,8 +25,14 @@
     display: flex;
     font-family: var(--dx-g-font-sans);
     width: 100%;
-    padding: var(--dx-g-spacing-sm);
-    font-size: var(--dx-g-text-sm);
+
+    /* Opt-in hooks; defaults preserve today's look. */
+    padding: var(--dx-c-dropdown-option-padding, var(--dx-g-spacing-sm));
+    font-size: var(--dx-c-dropdown-option-font-size, var(--dx-g-text-sm));
+    border-radius: var(
+        --dx-c-dropdown-option-border-radius,
+        var(--dx-g-spacing-xs)
+    );
     transition: var(--dx-g-transition-hue-1x);
     align-items: center;
     outline: none !important;
@@ -47,7 +53,10 @@
 }
 
 .option-active {
-    --dx-c-dropdown-option-label-color: var(--dx-g-blue-vibrant-50);
+    --dx-c-dropdown-option-label-color: var(
+        --dx-c-dropdown-option-active-label-color,
+        var(--dx-g-blue-vibrant-50)
+    );
 
     background: var(--dx-g-cloud-blue-vibrant-95);
 }
@@ -57,8 +66,12 @@
     flex-direction: column;
     justify-content: center;
     font-family: var(--dx-g-font-sans);
-    font-size: var(--dx-g-text-sm);
+    font-size: var(--dx-c-dropdown-option-font-size, var(--dx-g-text-sm));
+    color: var(--dx-c-dropdown-option-label-color, inherit);
     text-align: left;
+
+    /* Opt-in: set to 0 to let a long label truncate instead of overflow. */
+    min-width: var(--dx-c-dropdown-option-min-width, auto);
 }
 
 .option-indented .option_details {
@@ -68,10 +81,20 @@
 
 .option_label {
     color: var(--dx-c-dropdown-option-label-color, var(--dx-g-blue-vibrant-50));
-    display: flex;
+
+    /* Opt-in: set to block so text-overflow:ellipsis applies (ignored on flex). */
+    display: var(--dx-c-dropdown-option-label-display, flex);
     align-items: center;
     font-weight: var(--dx-c-dropdown-option-font-weight, var(--dx-g-font-bold));
     font-size: var(--dx-c-dropdown-option-font-size, var(--dx-g-text-base));
+
+    /* Opt-in truncation: consumers set --dx-c-dropdown-option-white-space:
+       nowrap to truncate labels with an ellipsis instead of wrapping.
+       Defaults preserve today's wrapping behavior. */
+    white-space: var(--dx-c-dropdown-option-white-space, normal);
+    overflow: var(--dx-c-dropdown-option-overflow, visible);
+    overflow-wrap: var(--dx-c-dropdown-option-overflow-wrap, normal);
+    text-overflow: var(--dx-c-dropdown-option-text-overflow, clip);
 }
 
 .option-indented .option_label {
@@ -130,7 +153,10 @@
 }
 
 .option-fit-content.option-active .option_label {
-    color: var(--dx-g-blue-vibrant-50);
+    color: var(
+        --dx-c-dropdown-option-active-label-color,
+        var(--dx-g-blue-vibrant-50)
+    );
 }
 
 .option-fit-content .option_icon {

package/src/modules/dx/popover/popover.ts

@@ -89,7 +89,15 @@ export default class Popover extends LightningElement {
 
             this.dispatchEvent(new CustomEvent("open"));
 
-            setTimeout(() => {
+            this.clearOpenListenersTimer();
+            // Defer so the opening click is not treated as an outside click.
+            // Drop the callback if the popover closes before it runs, or the
+            // document listeners attach with nothing left to remove them.
+            this.openListenersTimer = setTimeout(() => {
+                this.openListenersTimer = undefined;
+                if (!this._open) {
+                    return;
+                }
                 this.setPosition();
                 this.attachListenersTopopover();
             });
@@ -98,7 +106,15 @@ export default class Popover extends LightningElement {
 
     @api
     closePopover(focusControl: boolean = false) {
+        this.clearOpenListenersTimer();
+        if (!this._open) {
+            return;
+        }
         this._open = false;
+        // Hide before aria-expanded changes. :has([aria-expanded]) / :focus-within
+        // stacking rules would otherwise drop position:relative while this menu
+        // is still visible, flashing it against a different offset parent.
+        this.popover?.classList.remove("popover-container_open");
         this.autoUpdateCleanup?.();
         if (focusControl && this.control && this.control.focus) {
             this.control.focus();
@@ -106,20 +122,28 @@ export default class Popover extends LightningElement {
         if (this.control) {
             this.control.setAttribute("aria-expanded", "false");
         }
-        document.removeEventListener("click", this.interactOutsideListener);
+        document.removeEventListener(
+            "click",
+            this.interactOutsideListener,
+            true
+        );
         document.removeEventListener("focusout", this.interactOutsideListener);
+        document.removeEventListener("keydown", this.onDocumentKeydown, true);
         if (this.openOnHover) {
             document.removeEventListener(
                 "mousemove",
                 this.interactOutsideListener
             );
         }
+        this.pointerOpened = false;
         this.dispatchEvent(new CustomEvent("close"));
     }
 
     // PRIVATE VARS
 
     private controlled: boolean = false;
+    private pointerOpened: boolean = false;
+    private openListenersTimer?: ReturnType<typeof setTimeout>;
     private _open: boolean = false;
     private _rendered: boolean = isPrerender();
     private _role: string | null = null;
@@ -132,9 +156,15 @@ export default class Popover extends LightningElement {
     // LIFECYCLE METHODS
 
     disconnectedCallback() {
-        document.removeEventListener("click", this.interactOutsideListener);
+        this.clearOpenListenersTimer();
+        document.removeEventListener(
+            "click",
+            this.interactOutsideListener,
+            true
+        );
         document.removeEventListener("mousemove", this.interactOutsideListener);
         document.removeEventListener("focusout", this.interactOutsideListener);
+        document.removeEventListener("keydown", this.onDocumentKeydown, true);
         this.removeControlListeners();
     }
 
@@ -226,17 +256,91 @@ export default class Popover extends LightningElement {
         switch (e.key) {
             case "ArrowDown": {
                 e.preventDefault();
+                this.pointerOpened = false;
                 if (!this.open) {
                     this.openPopover();
                 }
                 this.dispatchEvent(new CustomEvent("controlarrowdown"));
                 break;
             }
+            case "Esc":
+            case "Escape":
+                this.closeOnEscape(e);
+                break;
             default:
         }
     };
 
-    private onControlClick = () => {
+    // Capture on document: click-open leaves focus on the trigger, and slotted
+    // menu options live outside this shadow tree, so the panel's onkeydown
+    // never sees Escape. Only the innermost popover in the event path handles
+    // it, so Escape in another control does not close this menu or cancel that
+    // control's own Escape behavior.
+    private onDocumentKeydown = (e: KeyboardEvent) => {
+        if ((e.key !== "Escape" && e.key !== "Esc") || !this.handlesEscape(e)) {
+            return;
+        }
+        this.closeOnEscape(e);
+    };
+
+    private handlesEscape(e: KeyboardEvent): boolean {
+        if (!this._open || e.defaultPrevented) {
+            return false;
+        }
+        const host = this.template.host;
+        const path = e.composedPath();
+        for (const node of path) {
+            if (node instanceof Element && node.localName === "dx-popover") {
+                return node === host;
+            }
+        }
+        // A non-composed event fired in this shadow or on the trigger does
+        // not list the host. The panel and control listeners still apply.
+        return (
+            (this.popover !== null && path.includes(this.popover)) ||
+            (this.control !== null && path.includes(this.control))
+        );
+    }
+
+    private clearOpenListenersTimer() {
+        if (this.openListenersTimer !== undefined) {
+            clearTimeout(this.openListenersTimer);
+            this.openListenersTimer = undefined;
+        }
+    }
+
+    private closeOnEscape(e: KeyboardEvent) {
+        if (!this.open) {
+            return;
+        }
+        e.preventDefault();
+        this.dispatchRequestCloseEvent("keypress-escape");
+        // Click-open + Escape upgrades :focus-visible on the trigger. Blur so
+        // the closed picker shows hover (pointer still over it) or default,
+        // not the keyboard halo. Keyboard-opened menus still restore focus.
+        const openedWithPointer = this.pointerOpened;
+        this.closePopover(!openedWithPointer);
+        if (openedWithPointer) {
+            this.blurControl();
+        }
+    }
+
+    private blurControl() {
+        const host = this.control;
+        if (!host) {
+            return;
+        }
+        const inner = host.shadowRoot?.activeElement as HTMLElement | null;
+        if (inner && typeof inner.blur === "function") {
+            inner.blur();
+            return;
+        }
+        if (typeof host.blur === "function") {
+            host.blur();
+        }
+    }
+
+    private onControlClick = (e: MouseEvent) => {
         if (this.controlled && this.open) {
             this.dispatchRequestCloseEvent("click-control");
             return;
@@ -257,6 +361,10 @@ export default class Popover extends LightningElement {
             return;
         }
 
+        // Enter/Space on a button synthesizes a click with detail 0. Only a
+        // pointer click should blur the trigger on Escape; keyboard activation
+        // must leave focus on the control.
+        this.pointerOpened = e.detail > 0;
         this.openPopover();
     };
 
@@ -287,16 +395,20 @@ export default class Popover extends LightningElement {
         switch (e.key) {
             case "Esc":
             case "Escape":
-                this.dispatchRequestCloseEvent("keypress-escape");
-                this.closePopover(true);
+                this.closeOnEscape(e);
                 break;
             default:
         }
     }
 
     private attachListenersTopopover() {
-        document.addEventListener("click", this.interactOutsideListener);
+        // Capture so a click still counts as outside when a descendant
+        // calls stopPropagation (topic version pickers do, so the tree row
+        // does not navigate). Without this, opening a second picker leaves
+        // the first menu open.
+        document.addEventListener("click", this.interactOutsideListener, true);
         document.addEventListener("focusout", this.interactOutsideListener);
+        document.addEventListener("keydown", this.onDocumentKeydown, true);
         if (this.openOnHover) {
             document.addEventListener(
                 "mousemove",

package/src/modules/dx/tree/treeHandler.ts

@@ -1,6 +1,18 @@
 import type { InternalTreeNode, TreeNode } from "typings/custom";
+import type { TopicVersionOption } from "dxUtils/topicVersion";
+import {
+    applyVersionToHref,
+    normalizePath,
+    resolveSelectedVersion
+} from "dxUtils/topicVersion";
+
+type VersionedTreeNode = TreeNode & { versions?: TopicVersionOption[] };
+type VersionedInternalTreeNode = InternalTreeNode & {
+    versions?: TopicVersionOption[];
+};
+
 type MapItem = {
-    node: InternalTreeNode;
+    node: VersionedInternalTreeNode;
     parent?: MapItem;
     setExpanded?: Function;
 };
@@ -21,7 +33,10 @@ export class TreeHandler {
     }
 
     getKeyByName(name: string): string | undefined {
-        return name && this._nameKeyMap[name];
+        if (!name) {
+            return undefined;
+        }
+        return this._nameKeyMap[name] || this._nameKeyMap[normalizePath(name)];
     }
 
     initialize(treeRoot: TreeNode): InternalTreeNode {
@@ -48,12 +63,41 @@ export class TreeHandler {
     }
 
     private convert(
-        node: TreeNode,
+        node: VersionedTreeNode,
         level: number = 0,
         parent?: MapItem,
-        position?: number
-    ): InternalTreeNode {
-        const convertedNode: InternalTreeNode = {
+        position?: number,
+        ancestorVersion?: {
+            selected: TopicVersionOption;
+            versions: TopicVersionOption[];
+        }
+    ): VersionedInternalTreeNode {
+        const ownSelected = node.versions?.length
+            ? resolveSelectedVersion(node)
+            : undefined;
+        const versionContext =
+            ownSelected && node.versions
+                ? { selected: ownSelected, versions: node.versions }
+                : ancestorVersion;
+
+        let link = node.link;
+        if (
+            versionContext &&
+            !node.versions?.length &&
+            link?.href &&
+            link.target !== "_blank"
+        ) {
+            const rewritten = applyVersionToHref(
+                link.href,
+                versionContext.selected,
+                versionContext.versions
+            );
+            if (rewritten && rewritten !== link.href) {
+                link = { ...link, href: rewritten };
+            }
+        }
+
+        const convertedNode: VersionedInternalTreeNode = {
             label: node.label,
             name: node.name,
             key: this.calculateKey(
@@ -63,24 +107,52 @@ export class TreeHandler {
             level: level,
             isExpanded: node.isExpanded || false,
             isChildrenLoading: node.isChildrenLoading || false,
-            link: node.link,
+            link,
             method: node.method,
             showForwardArrow: node.showForwardArrow,
-            redirectToChild: node.redirectToChild
+            redirectToChild: node.redirectToChild,
+            versions: node.versions
         };
 
         const mapItem = { node: convertedNode, parent };
         if (node.children && node.children.length > 0) {
             convertedNode.children = node.children.map((child, index) =>
-                this.convert(child, level + 1, mapItem, index)
+                this.convert(child, level + 1, mapItem, index, versionContext)
             );
         }
 
         this._nodeMap[convertedNode.key] = mapItem;
-        this._nameKeyMap[convertedNode.name] = convertedNode.key;
+        this.indexName(convertedNode.name, convertedNode.key);
+        // A redirect parent can carry a child's href. This index runs after
+        // the child, so recording it would make the parent win selection.
+        if (!convertedNode.redirectToChild) {
+            this.indexName(convertedNode.link?.href, convertedNode.key);
+        }
+        // Index this topic's own versioned URLs only. Parent-only switching
+        // URLs point at a child with content and must not steal that child's
+        // selection.
+        if (node.name && node.versions) {
+            for (const version of node.versions) {
+                this.indexName(
+                    applyVersionToHref(node.name, version, node.versions),
+                    convertedNode.key
+                );
+            }
+        }
         return convertedNode;
     }
 
+    private indexName(name: string | undefined, key: string): void {
+        if (!name) {
+            return;
+        }
+        this._nameKeyMap[name] = key;
+        const normalized = normalizePath(name);
+        if (normalized && normalized !== name) {
+            this._nameKeyMap[normalized] = key;
+        }
+    }
+
     private calculateKey(parentKey: string, position?: number): string {
         if (position === undefined) {
             return parentKey;

package/src/modules/dx/treeItem/treeItem.css

@@ -2,6 +2,36 @@
 
 :host {
     display: block;
+
+    /* Keep a stable containing block; z-index still lifts the open menu. */
+    position: relative;
+}
+
+/* Lift this row above later sibling pickers while its menu is open. */
+:host(:focus-within) {
+    z-index: 2;
+}
+
+.tree-item-row {
+    display: flex;
+    align-items: center;
+    min-width: 0;
+}
+
+.tree-item-row dx-tree-tile {
+    flex: 1;
+    min-width: 0;
+}
+
+.tree-item-version-picker {
+    flex: 0 0 auto;
+    margin-right: var(--dx-g-spacing-lg);
+    overflow: visible;
+}
+
+.tree-item-row-selected {
+    background: var(--dx-g-cloud-blue-vibrant-95);
+    box-shadow: inset var(--dx-g-spacing-xs) 0 0 0 var(--dx-g-blue-vibrant-40);
 }
 
 button {