@salesforcedevs/dx-components 1.39.0 → 1.40.0-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.39.0",
-    "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": "055e2a716cf3e946add92e953e136835730bc5fc"
-}
+  "name": "@salesforcedevs/dx-components",
+  "version": "1.40.0-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,6 +14,20 @@
     display: none;
 }
 
+/* Opt-in fit-content menu: grows to content (capped at the popover's viewport
+   max-width); long labels truncate instead of wrapping. */
+.menu-fit-content::part(content) {
+    width: max-content;
+}
+
+.menu-fit-content {
+    --dx-c-dropdown-option-min-width: 0;
+    --dx-c-dropdown-option-label-display: block;
+    --dx-c-dropdown-option-white-space: nowrap;
+    --dx-c-dropdown-option-overflow: hidden;
+    --dx-c-dropdown-option-text-overflow: ellipsis;
+}
+
 @media screen and (max-width: 1000px) {
     .menu-nested .menu_option:not(:first-child) {
         border-top: var(--border);

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

@@ -2,7 +2,7 @@
     <dx-popover
         aria-label={ariaLabel}
         class={className}
-        full-width={fullWidth}
+        full-width={effectiveFullWidth}
         offset={offset}
         onclose={onClose}
         open-on-hover={openOnHover}
@@ -10,7 +10,7 @@
         page-padding={pagePadding}
         placement={placement}
         small={small}
-        width={width}
+        width={effectiveWidth}
     >
         <slot slot="control"></slot>
         <div

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

@@ -2,7 +2,8 @@ import {
     AnalyticsPayload,
     OptionWithNested,
     PopperPlacement,
-    DropdownVariant
+    DropdownVariant,
+    DropdownWidthMode
 } from "typings/custom";
 import { LightningElement, api, track } from "lwc";
 import cx from "classnames";
@@ -37,6 +38,7 @@ export default class Dropdown extends LightningElement {
     @api fullWidth?: boolean | null;
     @api navItemLabel: string | null = null;
     @api variant: DropdownVariant = "base";
+    @api widthMode: DropdownWidthMode = "fixed";
 
     // props forwarded to dropdown option
     @api analyticsEvent?: string;
@@ -80,12 +82,32 @@ export default class Dropdown extends LightningElement {
         return this.areOptionsEmpty ? null : "menu";
     }
 
+    private get isFitContent() {
+        return this.widthMode === "fit-content";
+    }
+
+    // fit-content takes precedence; the misuse is surfaced in className() below.
+    private get effectiveWidth() {
+        return this.isFitContent ? null : this.width;
+    }
+
+    private get effectiveFullWidth() {
+        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 && this.options.length >= 2 && "menu-nested-2-col",
             this.offset && `menu-offset-${this.offset}`,
-            this.areOptionsEmpty && "menu-hidden"
+            this.areOptionsEmpty && "menu-hidden",
+            fitContent && "menu-fit-content"
         );
     }
 

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

@@ -25,9 +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-g-spacing-xs);
+    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;
@@ -58,6 +63,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 {
@@ -67,10 +75,19 @@
 
 .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);
+    text-overflow: var(--dx-c-dropdown-option-text-overflow, clip);
 }
 
 .option-indented .option_label {

package/src/modules/dx/sidebarOld/sidebarOld.html

@@ -30,7 +30,6 @@
                     <div class="header-wrapper">
                         <div lwc:if={devCenter} class="link-row">
                             <a href={devCenter.link}>
-                                <dx-icon symbol="back"></dx-icon>
                                 <dx-icon
                                     class="brand-icon"
                                     lwc:if={devCenter.icon}

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,23 +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
+            showForwardArrow: node.showForwardArrow,
+            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 &&
@@ -79,8 +107,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 ||
             ""
@@ -100,6 +164,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 {
@@ -130,8 +211,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();
         }
@@ -146,8 +227,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
         });
     }
@@ -165,8 +250,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;
@@ -79,7 +81,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,410 @@
+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
+        }
+    }));
+}
+
+export function resolveSelectedVersion(
+    node: VersionedNode | undefined
+): TopicVersionOption | undefined {
+    const versions = node?.versions;
+    if (!node || !versions?.length) {
+        return undefined;
+    }
+
+    const fromOwnUrl = versions.find((version) =>
+        hrefMatchesCurrentPage(version.link?.href)
+    );
+    if (fromOwnUrl) {
+        return fromOwnUrl;
+    }
+
+    const descendantHrefs = collectSubtreeCanonicalHrefs(node, false);
+    const fromDescendant = versions.find(
+        (version) =>
+            version.id !== versions[0].id &&
+            descendantHrefs.some((href) =>
+                hrefMatchesVersion(href, version, versions)
+            )
+    );
+    if (fromDescendant) {
+        return fromDescendant;
+    }
+
+    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.