@salesforcedevs/dx-components 1.40.4-new-brand → 1.40.5-topic-alpha.1

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-new-brand",
-  "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.40.4"
-}
+    "name": "@salesforcedevs/dx-components",
+    "version": "1.40.5-topic-alpha.1",
+    "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,30 +14,30 @@
     display: none;
 }
 
-.menu-fit-content {
-    --dx-c-popover-width: max-content;
-    --dx-c-popover-padding: var(--dx-g-spacing-sm) 0;
+/* 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 .menu_list {
-    width: 100%;
-    align-items: flex-start;
-    gap: var(--dx-g-spacing-sm);
-}
-
-.menu-fit-content.menu-nested .menu_option:not(:first-child) {
-    border-top: var(--border);
-    margin-top: 0;
-    padding-top: var(--dx-g-spacing-sm);
-}
-
-.menu-fit-content .menu_heading {
-    margin: 0;
-    padding: var(--dx-g-spacing-smd) var(--dx-g-spacing-lg);
-    font-family: var(--dx-g-font-sans);
-    line-height: var(--dx-g-spacing-mlg);
-    text-transform: none;
-    color: var(--dx-g-gray-10);
+.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
+    );
 }
 
 @media screen and (max-width: 1000px) {

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);
+
+    /* Opt-in hooks; defaults preserve today's look. */
+    padding: var(--dx-c-dropdown-option-padding, var(--dx-g-spacing-sm));
     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;
@@ -59,6 +65,9 @@
     font-family: var(--dx-g-font-sans);
     font-size: var(--dx-g-text-sm);
     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 +77,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 {

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

@@ -106,7 +106,11 @@ 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);
         if (this.openOnHover) {
             document.removeEventListener(
@@ -132,7 +136,11 @@ export default class Popover extends LightningElement {
     // LIFECYCLE METHODS
 
     disconnectedCallback() {
-        document.removeEventListener("click", this.interactOutsideListener);
+        document.removeEventListener(
+            "click",
+            this.interactOutsideListener,
+            true
+        );
         document.removeEventListener("mousemove", this.interactOutsideListener);
         document.removeEventListener("focusout", this.interactOutsideListener);
         this.removeControlListeners();
@@ -295,7 +303,11 @@ export default class Popover extends LightningElement {
     }
 
     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);
         if (this.openOnHover) {
             document.addEventListener(

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,47 @@ 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
+            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);
+        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

@@ -4,6 +4,33 @@
     display: block;
 }
 
+/* Lift this row above later sibling pickers while its menu is open. */
+:host(:focus-within) {
+    position: relative;
+    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);
+}
+
+.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 {
     width: 100%;
     text-align: left;

package/src/modules/dx/treeItem/treeItem.html

@@ -1,5 +1,5 @@
 <template>
-    <a href={href} target={target} onclick={onLinkClick} tabindex="-1">
+    <div class={rowClass}>
         <dx-tree-tile
             href={href}
             is-root={isRoot}
@@ -7,12 +7,26 @@
             is-expanded={isExpanded}
             has-children={hasChildren}
             is-selected={isSelected}
+            is-contained-selection={isContainedSelection}
             oniconclick={onIconClick}
             show-arrow={isParent}
             target={target}
             is-external-link={isExternalLink}
+            has-version-picker={showVersionPicker}
+            onclick={onLinkClick}
         ></dx-tree-tile>
-    </a>
+        <doc-version-picker
+            if:true={showVersionPicker}
+            class="tree-item-version-picker"
+            small="true"
+            versions={versionPickerOptions}
+            selected-version={selectedVersion}
+            latest-version={isLatestVersion}
+            onchange={onVersionChange}
+            onclick={onVersionPickerClick}
+            onmousedown={onVersionPickerClick}
+        ></doc-version-picker>
+    </div>
     <img
         if:true={showChildrenLoading}
         class="tree-children-loading"

package/src/modules/dx/treeItem/treeItem.ts

@@ -2,9 +2,24 @@ import { LightningElement, api } from "lwc";
 import { InternalTreeNode } from "typings/custom";
 import { track } from "dxUtils/analytics";
 import { isInViewport } from "dxUtils/browser";
+import type { TopicVersionOption } from "dxUtils/topicVersion";
+import {
+    firstContentNode,
+    getTopicVersionKey,
+    getVersionPickerOptions,
+    isParentOnlyTopic,
+    normalizePath,
+    persistTopicVersion,
+    resolveSelectedVersion,
+    shouldShowTopicVersionPicker
+} from "dxUtils/topicVersion";
 
 const DEFAULT_TARGET = "_self";
 
+type VersionedInternalTreeNode = InternalTreeNode & {
+    versions?: TopicVersionOption[];
+};
+
 export default class TreeItem extends LightningElement {
     @api selectedKey?: string;
     @api isRoot: boolean = false;
@@ -20,7 +35,7 @@ export default class TreeItem extends LightningElement {
         this.isChildrenLoading = (node && node.isChildrenLoading) || false;
     }
 
-    private _treeNode!: InternalTreeNode;
+    private _treeNode!: VersionedInternalTreeNode;
     private isExpanded: boolean = false;
     private isChildrenLoading: boolean = false;
     private rootParentLabel: string = "";
@@ -30,9 +45,22 @@ export default class TreeItem extends LightningElement {
     }
 
     private get isSelected(): boolean {
+        if (isParentOnlyTopic(this._treeNode)) {
+            return false;
+        }
         return this._treeNode.key === this.selectedKey && !this.isExternalLink;
     }
 
+    private get rowClass(): string {
+        return this.isSelected && this.showVersionPicker
+            ? "tree-item-row tree-item-row-selected"
+            : "tree-item-row";
+    }
+
+    private get isContainedSelection(): boolean {
+        return this.isSelected && this.showVersionPicker;
+    }
+
     private get hasChildren(): boolean {
         return !!(
             this.treeNode &&
@@ -83,8 +111,44 @@ export default class TreeItem extends LightningElement {
         return `${parentLabels.reverse().join(":")}:${this.treeNode.label}`;
     }
 
+    private get versions(): TopicVersionOption[] | undefined {
+        return this._treeNode?.versions;
+    }
+
+    private get versionPickerOptions(): TopicVersionOption[] | undefined {
+        return getVersionPickerOptions(this._treeNode);
+    }
+
+    private get showVersionPicker(): boolean {
+        return shouldShowTopicVersionPicker(
+            this.versions,
+            this._treeNode?.showForwardArrow
+        );
+    }
+
+    private get selectedVersion(): TopicVersionOption | undefined {
+        return resolveSelectedVersion(this._treeNode);
+    }
+
+    private get isLatestVersion(): boolean {
+        return (
+            !!this.selectedVersion &&
+            this.selectedVersion.id === this.versions?.[0]?.id
+        );
+    }
+
     private get href(): string | undefined {
+        if (isParentOnlyTopic(this._treeNode)) {
+            const contentNode = firstContentNode(this._treeNode);
+            return (
+                contentNode?.link?.href ||
+                contentNode?.name ||
+                this.selectedVersion?.link?.href ||
+                ""
+            );
+        }
         return (
+            this.selectedVersion?.link?.href ||
             (this._treeNode.link && this._treeNode.link.href) ||
             this._treeNode.name ||
             ""
@@ -104,6 +168,23 @@ export default class TreeItem extends LightningElement {
                 setExpanded: this.setExpanded.bind(this)
             });
         }
+
+        // Remember this topic's resolved version (own URL, descendant URL, or
+        // session) so sibling pickers stay independent for the tab.
+        const selected = resolveSelectedVersion(this._treeNode);
+        const topicKey = getTopicVersionKey(this._treeNode);
+        if (this.versions?.length && selected && topicKey) {
+            persistTopicVersion(topicKey, selected.id);
+        }
+    }
+
+    private onVersionChange(event: CustomEvent): void {
+        event.stopPropagation();
+        persistTopicVersion(getTopicVersionKey(this._treeNode), event.detail);
+    }
+
+    private onVersionPickerClick(event: Event): void {
+        event.stopPropagation();
     }
 
     renderedCallback(): void {
@@ -134,8 +215,8 @@ export default class TreeItem extends LightningElement {
     private preventDefaultLinkBehavior(event: Event) {
         // prevent page refresh if href isn't present or link is already active
         if (
-            !this._treeNode.link?.href ||
-            this._treeNode.link?.href === window.location.pathname
+            !this.href ||
+            normalizePath(this.href) === normalizePath(window.location.pathname)
         ) {
             event.preventDefault();
         }
@@ -167,8 +248,12 @@ export default class TreeItem extends LightningElement {
         }
 
         this.sendGtm(event);
+        const contentNode = isParentOnlyTopic(this._treeNode)
+            ? firstContentNode(this._treeNode)
+            : undefined;
         this.fireEvent("tileselected", {
-            name: this._treeNode.name,
+            name: contentNode?.name || this._treeNode.name,
+            ...(contentNode?.key ? { key: contentNode.key } : {}),
             isExternalLink: this.isExternalLink
         });
     }
@@ -186,8 +271,8 @@ export default class TreeItem extends LightningElement {
         this.dispatchEvent(
             new CustomEvent(type, {
                 detail: {
-                    ...detail,
-                    key: this._treeNode.key
+                    key: this._treeNode.key,
+                    ...detail
                 },
                 bubbles: true,
                 composed: true

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

@@ -66,6 +66,10 @@
     white-space: nowrap;
 }
 
+.tile-with-version-picker {
+    padding-right: var(--dx-g-spacing-xs);
+}
+
 .tile-with-children .tile-label {
     order: 2;
 }