@salesforcedevs/dx-components 1.40.3 → 1.40.4-final-alpha1

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.3",
-    "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": "c8c3bb1003d40a55fdd5733c7891dcca3931fb24"
-}
+  "name": "@salesforcedevs/dx-components",
+  "version": "1.40.4-final-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"
+  }
+}

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/tooltip/tooltip.css

@@ -8,6 +8,12 @@
     display: inherit;
 }
 
+[aria-label][role~="tooltip"].is-visible::before,
+[aria-label][role~="tooltip"].is-visible::after {
+    opacity: 1;
+    pointer-events: auto;
+}
+
 [aria-label][role~="tooltip"].is-suppressed:is(:hover, :focus)::before,
 [aria-label][role~="tooltip"].is-suppressed:is(:hover, :focus)::after {
     opacity: 0;

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

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

@@ -28,10 +28,12 @@ export default class TreeTile extends LightningElement {
     @api isExpanded = false;
     @api hasChildren = false;
     @api isSelected = false;
+    @api isContainedSelection = false;
     @api href!: string;
     @api showArrow = false;
     @api target!: string;
     @api isExternalLink = false;
+    @api hasVersionPicker = false;
 
     get tileAriaLevel() {
         return this.treeNode.level + 2;
@@ -101,7 +103,11 @@ export default class TreeTile extends LightningElement {
             "tile-root": this.isRoot,
             "tile-with-children": !this.isRoot && this.hasChildren,
             "tile-root-with-child": this.isRoot && this.showArrow,
-            "sidebar-item-selected": this.isSelected
+            "sidebar-item-selected":
+                this.isSelected && !this.isContainedSelection,
+            "sidebar-item-selected-text":
+                this.isSelected && this.isContainedSelection,
+            "tile-with-version-picker": this.hasVersionPicker
         });
     }
 

package/src/modules/dx/typeBadge/typeBadge.ts

@@ -7,6 +7,7 @@ import {
     IconSprite,
     IconData,
     IconSymbol,
+    StatusBadgeVariant,
     TypeBadgeSize
 } from "typings/custom";
 import { colorToDxColors, buildStyleColorVariables } from "dxUtils/css";
@@ -20,9 +21,16 @@ import {
     getContentTypeColorVariables
 } from "dxUtils/contentTypes";
 
+// Opt-in solid status variants (status-success/-warning/-error).
+export const STATUS_BADGE_VARIANTS: StatusBadgeVariant[] = [
+    "status-success",
+    "status-warning",
+    "status-error"
+];
+
 export default class TypeBadge extends LightningElement {
     @api size: TypeBadgeSize = "default";
-    @api variant: Brand | ContentType = "default";
+    @api variant: Brand | ContentType | StatusBadgeVariant = "default";
     @api color?: Color;
     @api dark?: false;
 
@@ -87,11 +95,24 @@ export default class TypeBadge extends LightningElement {
         return isContentType(this.variant);
     }
 
+    private get isStatus(): boolean {
+        return STATUS_BADGE_VARIANTS.includes(
+            this.variant as StatusBadgeVariant
+        );
+    }
+
     private get className(): string {
-        return cx("dx-badge", `size-${this.size}`);
+        return cx(
+            "dx-badge",
+            `size-${this.size}`,
+            this.isStatus && this.variant
+        );
     }
 
     private get style(): string {
+        if (this.isStatus) {
+            return "";
+        }
         if (this.dark) {
             return buildStyleColorVariables({
                 background: "--dx-g-purple-vibrant-40",

package/src/modules/dxHelpers/commonTreeItem/commonTreeItem.css

@@ -13,6 +13,10 @@
     color: var(--dx-g-blue-vibrant-40) !important;
 }
 
+.sidebar-item-selected-text {
+    color: var(--dx-g-blue-vibrant-40) !important;
+}
+
 .sidebar-item {
     padding: 6px var(--dx-g-spacing-lg) 6px
         var(--dx-g-global-header-padding-horizontal);

package/src/modules/dxHelpers/typeBadge/typeBadge.css

@@ -26,6 +26,28 @@
     --height: var(--dx-g-spacing-mlg);
 }
 
+.dx-badge.status-success,
+.dx-badge.status-warning,
+.dx-badge.status-error {
+    /* No spacing token maps to 10px; status badges need this exact padding. */
+    --horizontal-spacing: 10px;
+}
+
+.dx-badge.status-success {
+    --color: var(--sds-g-gray-1);
+    --background: var(--dx-g-green-vibrant-50);
+}
+
+.dx-badge.status-warning {
+    --color: var(--dx-g-gray-15);
+    --background: var(--dx-g-yellow-vibrant-80);
+}
+
+.dx-badge.status-error {
+    --color: var(--sds-g-gray-1);
+    --background: var(--dx-g-red-vibrant-40);
+}
+
 svg,
 dx-icon {
     margin-right: var(--dx-g-spacing-sm);

package/src/modules/dxUtils/topicVersion/topicVersion.ts

@@ -0,0 +1,467 @@
+export const TOPIC_VERSION_SESSION_KEY = "sfdocs-topic-version-selections";
+
+export type TopicVersionOption = {
+    id: string;
+    label: string;
+    deprecated?: boolean;
+    selected?: boolean;
+    link?: {
+        href?: string;
+        target?: string;
+    };
+};
+
+export type VersionedNode = {
+    name?: string;
+    label?: string;
+    key?: string;
+    link?: {
+        href?: string;
+        target?: string;
+    };
+    children?: VersionedNode[];
+    versions?: TopicVersionOption[];
+    /** Set on Redoc spec tiles after the docs layout decorates the TOC. */
+    showForwardArrow?: boolean;
+    /** Docs TOC topic type (`markdown` | `spec`). May be stripped after decoration. */
+    topicType?: string;
+};
+
+type VersionPathDelta = {
+    prefix: string;
+    inserted: string;
+};
+
+function isBrowser(): boolean {
+    return typeof window !== "undefined";
+}
+
+export function normalizePath(href?: string): string {
+    if (!href) {
+        return "";
+    }
+
+    try {
+        const url = href.startsWith("http")
+            ? new URL(href)
+            : new URL(
+                  href,
+                  isBrowser() ? window.location.origin : "http://localhost"
+              );
+        return url.pathname.replace(/\/$/, "") || "/";
+    } catch {
+        return href.replace(/\/$/, "");
+    }
+}
+
+export function hrefMatchesCurrentPage(href?: string): boolean {
+    if (!isBrowser()) {
+        return false;
+    }
+    return normalizePath(href) === normalizePath(window.location.pathname);
+}
+
+export function readTopicVersionSelections(): Record<string, string> {
+    if (!isBrowser() || !window.sessionStorage) {
+        return {};
+    }
+
+    try {
+        const raw = window.sessionStorage.getItem(TOPIC_VERSION_SESSION_KEY);
+        return raw ? JSON.parse(raw) : {};
+    } catch {
+        return {};
+    }
+}
+
+export function persistTopicVersion(
+    topicName: string,
+    versionId: string
+): void {
+    if (!topicName || !versionId || !isBrowser() || !window.sessionStorage) {
+        return;
+    }
+
+    const stored = readTopicVersionSelections();
+    stored[topicName] = versionId;
+    window.sessionStorage.setItem(
+        TOPIC_VERSION_SESSION_KEY,
+        JSON.stringify(stored)
+    );
+}
+
+/**
+ * Stable session key for a versioned topic. Parent-only sections have an empty
+ * `name`/`href`, so fall back to the latest switching URL (then the label).
+ */
+export function getTopicVersionKey(node: VersionedNode | undefined): string {
+    if (!node) {
+        return "";
+    }
+    if (node.name) {
+        return node.name;
+    }
+    const latestHref = node.versions?.[0]?.link?.href;
+    if (latestHref) {
+        return latestHref;
+    }
+    return node.label || "";
+}
+
+/** Section header with children but no page of its own. */
+export function isParentOnlyTopic(node: VersionedNode | undefined): boolean {
+    if (!node) {
+        return false;
+    }
+    const ownHref = node.link?.href || node.name;
+    return !ownHref && !!node.children?.length;
+}
+
+function isSpecNode(node: VersionedNode): boolean {
+    return node.showForwardArrow === true || node.topicType === "spec";
+}
+
+/**
+ * First descendant that has a markdown page (own href/name). Specs (Redoc)
+ * and external links are skipped so parent-only sections land on the first
+ * markdown topic even when a spec is authored first in the TOC.
+ */
+export function firstContentNode(
+    node: VersionedNode | undefined
+): VersionedNode | undefined {
+    if (!node || node.link?.target === "_blank" || isSpecNode(node)) {
+        return undefined;
+    }
+    if (node.link?.href || node.name) {
+        return node;
+    }
+    for (const child of node.children || []) {
+        const found = firstContentNode(child);
+        if (found) {
+            return found;
+        }
+    }
+    return undefined;
+}
+
+export function shouldShowTopicVersionPicker(
+    versions?: TopicVersionOption[],
+    showForwardArrow?: boolean
+): boolean {
+    return !showForwardArrow && Array.isArray(versions) && versions.length > 1;
+}
+
+/**
+ * Difference between a picker's latest switching URL and an older one.
+ *
+ * latest:  /docs/project/errors.html
+ * v1:      /docs/project/v1/errors.html
+ * → prefix `/docs/project/`, inserted `v1/`
+ */
+function getVersionPathDelta(
+    latestPath: string,
+    selectedPath: string
+): VersionPathDelta | undefined {
+    const latestDirEnd = latestPath.lastIndexOf("/") + 1;
+    if (latestDirEnd <= 0) {
+        return undefined;
+    }
+
+    const prefix = latestPath.slice(0, latestDirEnd);
+    const latestSlug = latestPath.slice(latestDirEnd);
+    if (!selectedPath.startsWith(prefix) || !latestSlug) {
+        return undefined;
+    }
+
+    const selectedAfterPrefix = selectedPath.slice(prefix.length);
+    if (!selectedAfterPrefix.endsWith(latestSlug)) {
+        return undefined;
+    }
+
+    const inserted = selectedAfterPrefix.slice(
+        0,
+        selectedAfterPrefix.length - latestSlug.length
+    );
+    if (!inserted) {
+        return undefined;
+    }
+
+    return { prefix, inserted };
+}
+
+function applyVersionPathDelta(
+    hrefPath: string,
+    delta: VersionPathDelta
+): string | undefined {
+    if (!hrefPath.startsWith(delta.prefix)) {
+        return undefined;
+    }
+
+    const rest = hrefPath.slice(delta.prefix.length);
+    if (rest.startsWith(delta.inserted)) {
+        return hrefPath;
+    }
+
+    return delta.prefix + delta.inserted + rest;
+}
+
+function stripVersionPathDelta(
+    hrefPath: string,
+    delta: VersionPathDelta
+): string | undefined {
+    if (!hrefPath.startsWith(delta.prefix)) {
+        return undefined;
+    }
+
+    const rest = hrefPath.slice(delta.prefix.length);
+    if (!rest.startsWith(delta.inserted)) {
+        return undefined;
+    }
+
+    return delta.prefix + rest.slice(delta.inserted.length);
+}
+
+/**
+ * Maps a canonical (latest) href onto another version using the picker's
+ * latest vs selected switching URLs as the template.
+ *
+ * latest parent:  /docs/project/errors.html
+ * v1 parent:      /docs/project/v1/errors.html
+ * latest child:   /docs/project/extra-child-a.html
+ * → v1 child:     /docs/project/v1/extra-child-a.html
+ */
+export function applyVersionToHref(
+    canonicalHref: string | undefined,
+    selectedVersion: TopicVersionOption | undefined,
+    versions?: TopicVersionOption[]
+): string | undefined {
+    if (!canonicalHref) {
+        return canonicalHref;
+    }
+    if (!selectedVersion || !versions?.length) {
+        return canonicalHref;
+    }
+
+    const latest = versions[0];
+    if (!latest || selectedVersion.id === latest.id) {
+        return canonicalHref;
+    }
+
+    const latestPath = normalizePath(latest.link?.href);
+    const selectedPath = normalizePath(selectedVersion.link?.href);
+    const hrefPath = normalizePath(canonicalHref);
+
+    if (!latestPath || !selectedPath || latestPath === selectedPath) {
+        return insertVersionBeforeSlug(canonicalHref, selectedVersion.id);
+    }
+
+    const delta = getVersionPathDelta(latestPath, selectedPath);
+    return (
+        (delta && applyVersionPathDelta(hrefPath, delta)) ||
+        insertVersionBeforeSlug(canonicalHref, selectedVersion.id)
+    );
+}
+
+function insertVersionBeforeSlug(href: string, versionId: string): string {
+    const path = normalizePath(href);
+    const lastSlash = path.lastIndexOf("/");
+    if (lastSlash <= 0 || !versionId) {
+        return href;
+    }
+    const dir = path.slice(0, lastSlash);
+    const slug = path.slice(lastSlash);
+    if (dir.endsWith(`/${versionId}`)) {
+        return path;
+    }
+    return `${dir}/${versionId}${slug}`;
+}
+
+export function toCanonicalHref(
+    href: string | undefined,
+    versions?: TopicVersionOption[]
+): string {
+    if (!href) {
+        return "";
+    }
+    if (!versions?.length) {
+        return normalizePath(href);
+    }
+
+    const latestPath = normalizePath(versions[0].link?.href);
+    const hrefPath = normalizePath(href);
+    if (!latestPath) {
+        return hrefPath;
+    }
+
+    for (const version of versions) {
+        if (version.id === versions[0].id) {
+            continue;
+        }
+        const delta = getVersionPathDelta(
+            latestPath,
+            normalizePath(version.link?.href)
+        );
+        const stripped = delta && stripVersionPathDelta(hrefPath, delta);
+        if (stripped) {
+            return stripped;
+        }
+    }
+
+    return hrefPath;
+}
+
+function hrefMatchesVersion(
+    href: string | undefined,
+    version: TopicVersionOption,
+    versions: TopicVersionOption[]
+): boolean {
+    return hrefMatchesCurrentPage(applyVersionToHref(href, version, versions));
+}
+
+function collectSubtreeCanonicalHrefs(
+    node: VersionedNode,
+    includeSelf = true
+): string[] {
+    const hrefs: string[] = [];
+    const own = node.link?.href || node.name;
+    if (includeSelf && own) {
+        hrefs.push(own);
+    }
+    for (const child of node.children || []) {
+        if (child.versions?.length || child.link?.target === "_blank") {
+            continue;
+        }
+        hrefs.push(...collectSubtreeCanonicalHrefs(child));
+    }
+    return hrefs;
+}
+
+export function isCurrentPageInSubtree(
+    node: VersionedNode,
+    versions?: TopicVersionOption[]
+): boolean {
+    if (!isBrowser() || !versions?.length) {
+        return false;
+    }
+
+    return collectSubtreeCanonicalHrefs(node).some((href) =>
+        versions.some((version) => hrefMatchesVersion(href, version, versions))
+    );
+}
+
+/**
+ * Picker option hrefs. When the current page is this topic or a descendant,
+ * each option points at that same topic in the chosen version so the child
+ * stays selected. Otherwise keep the backend switching URL (parent page, or
+ * first content child for parent-only sections).
+ */
+export function getVersionPickerOptions(
+    node: VersionedNode | undefined
+): TopicVersionOption[] | undefined {
+    const versions = node?.versions;
+    if (!node || !versions?.length) {
+        return versions;
+    }
+    if (!isCurrentPageInSubtree(node, versions)) {
+        return versions;
+    }
+
+    const canonical = toCanonicalHref(window.location.pathname, versions);
+    return versions.map((version) => ({
+        ...version,
+        link: {
+            ...version.link,
+            href:
+                applyVersionToHref(canonical, version, versions) ||
+                version.link?.href
+        }
+    }));
+}
+
+/**
+ * Version whose page (or a descendant of it) is the current URL.
+ * Ignores the session-stored picker selection, which can remember an older
+ * version while the reader is still on the latest page.
+ */
+export function versionForCurrentPage(
+    node: VersionedNode | undefined
+): TopicVersionOption | undefined {
+    const versions = node?.versions;
+    if (!node || !versions?.length || !isBrowser()) {
+        return undefined;
+    }
+
+    const hrefs = collectSubtreeCanonicalHrefs(node);
+    const matches = (version: TopicVersionOption) =>
+        hrefMatchesCurrentPage(version.link?.href) ||
+        hrefs.some((href) => hrefMatchesVersion(href, version, versions));
+
+    // Older versions first so a rewritten child URL is not mistaken for latest.
+    const older = versions.find(
+        (version) => version.id !== versions[0].id && matches(version)
+    );
+    if (older) {
+        return older;
+    }
+
+    return matches(versions[0]) ? versions[0] : undefined;
+}
+
+/**
+ * Deepest versioned topic that contains the current page, with the version
+ * the URL selects. Nested versioned topics own their pages.
+ */
+export function findTopicVersionForCurrentPage(
+    nodes: VersionedNode[] | undefined | null
+): { node: VersionedNode; version: TopicVersionOption } | undefined {
+    let match: { node: VersionedNode; version: TopicVersionOption } | undefined;
+    const walk = (list?: VersionedNode[] | null) => {
+        for (const node of list || []) {
+            const version = versionForCurrentPage(node);
+            if (version) {
+                match = { node, version };
+            }
+            walk(node.children);
+        }
+    };
+    walk(nodes);
+    return match;
+}
+
+/**
+ * Current page rewritten onto the latest topic version. Falls back to the
+ * latest switching URL when the path delta cannot be applied.
+ */
+export function latestHrefForCurrentPage(
+    versions: TopicVersionOption[] | undefined
+): string | undefined {
+    const latest = versions?.[0];
+    if (!latest) {
+        return undefined;
+    }
+    if (!isBrowser()) {
+        return latest.link?.href;
+    }
+
+    const canonical = toCanonicalHref(window.location.pathname, versions);
+    return applyVersionToHref(canonical, latest, versions) || latest.link?.href;
+}
+
+export function resolveSelectedVersion(
+    node: VersionedNode | undefined
+): TopicVersionOption | undefined {
+    const versions = node?.versions;
+    if (!node || !versions?.length) {
+        return undefined;
+    }
+
+    // The open page wins, including a canonical child opened from "View Latest".
+    // Session is only for a picker whose topic is not the current page.
+    const fromUrl = versionForCurrentPage(node);
+    if (fromUrl) {
+        return fromUrl;
+    }
+
+    const storedId = readTopicVersionSelections()[getTopicVersionKey(node)];
+    return versions.find((version) => version.id === storedId) || versions[0];
+}

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.