@salesforcedevs/dx-components 1.40.6-tlv-alpha-1 → 1.40.7-bug-fix-alpha

package/lwc.config.json

@@ -1,8 +1,7 @@
 {
     "modules": [
         { "dir": "src/modules" },
-        { "npm": "@salesforcedevs/dw-components" },
-        { "npm": "@salesforcedevs/docs-components" }
+        { "npm": "@salesforcedevs/dw-components" }
     ],
     "expose": [
         "dx/agenda",
@@ -111,6 +110,7 @@
         "dx/tooltip",
         "dx/trafficLabeler",
         "dx/tree",
+        "dx/versionPicker",
         "dx/typeBadge",
         "dx/vimeoPlayer",
         "dxBaseElements/headerBase",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforcedevs/dx-components",
-  "version": "1.40.6-tlv-alpha-1",
+  "version": "1.40.7-bug-fix-alpha",
   "description": "DX Lightning web components",
   "license": "MIT",
   "engines": {
@@ -43,6 +43,5 @@
     "eventsourcemock": "2.0.0",
     "luxon": "3.4.4",
     "msw": "^2.12.4"
-  },
-  "stableVersion": "1.40.5"
+  }
 }

package/src/modules/dx/codeBlock/codeBlock.ts

@@ -15,9 +15,6 @@ import { normalizeBoolean } from "dxUtils/normalizers";
     - SQL Documentation -> SQL
 */
 
-// Used for remove enclosing <pre> tag's (if occurs)
-const preTagRegexp: RegExp = /^<pre.*?>(.*)<\/pre>$/is;
-
 export const LIGHT = "light";
 export const DARK = "dark";
 export const EVENT_NAME = "dx-codeblock-theme";
@@ -87,12 +84,7 @@ export default class CodeBlock extends LightningElement {
     set codeBlock(value: string) {
         this._codeBlockRendered = false;
         this._isCbHeightCalculated = false;
-        let match;
-        this._codeBlock = (
-            (match = preTagRegexp.exec(value.trim())) === null
-                ? value.trim()
-                : match[1]
-        ).trim();
+        this._codeBlock = value.trim();
     }
 
     @api

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

@@ -29,10 +29,7 @@
     /* Opt-in hooks; defaults preserve today's look. */
     padding: var(--dx-c-dropdown-option-padding, var(--dx-g-spacing-sm));
     font-size: var(--dx-c-dropdown-option-font-size, var(--dx-g-text-sm));
-    border-radius: var(
-        --dx-c-dropdown-option-border-radius,
-        var(--dx-g-spacing-xs)
-    );
+    border-radius: var(--dx-c-dropdown-option-border-radius, 0);
     transition: var(--dx-g-transition-hue-1x);
     align-items: center;
     outline: none !important;

package/src/modules/dx/searchHybrid/searchHybrid.html

@@ -106,7 +106,7 @@
                                     {result.contentTypeLabel}
                                 </span>
                             </div>
-                            <a href={result.url} class="dx-result-title">
+                            <a href={result.href} class="dx-result-title">
                                 {result.title}
                             </a>
                             <p if:true={result.hasDate} class="dx-result-date">

package/src/modules/dx/searchHybrid/searchHybrid.ts

@@ -8,6 +8,7 @@ import {
     decodeHtmlEntities,
     highlightedSnippetHtml,
     isSortOption,
+    resultHref,
     SORT_OPTIONS,
     type SearchResult,
     type SortOption
@@ -30,6 +31,8 @@ const SORT_LABELS: Record<SortOption, string> = {
 interface DisplayResult {
     key: string;
     url: string;
+    // Matched-section link; falls back to the page url.
+    href: string;
     title: string;
     description: string | null;
     hasDescription: boolean;
@@ -167,6 +170,7 @@ export default class SearchHybrid extends LightningElement {
             return {
                 key: `${r.url}-${i}`,
                 url: r.url,
+                href: resultHref(r),
                 title: decodeHtmlEntities(r.title),
                 description,
                 hasDescription: description !== null,

package/src/modules/dx/sidebar/sidebar.html

@@ -102,6 +102,7 @@
                 for:each={trees}
                 for:item="tree"
                 key={tree.key}
+                language={language}
                 tree-root={tree.tree}
                 onselect={onSelect}
                 value={value}

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

@@ -71,6 +71,7 @@
                     for:each={filteredTrees}
                     for:item="tree"
                     key={tree.key}
+                    language={language}
                     tree-root={tree.tree}
                     onselect={onSelect}
                     value={value}

package/src/modules/dx/tree/tree.html

@@ -4,6 +4,7 @@
         is-root
         tree-node={treeRoot}
         selected-key={selectedKey}
+        language={language}
         ontileselected={onTileSelected}
         onexpandcollapse={onExpandCollapse}
         onregister={onRegister}

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

@@ -4,6 +4,10 @@ import { toJson } from "dxUtils/normalizers";
 import { TreeHandler } from "./treeHandler";
 
 export default class Tree extends LightningElement {
+    // Must be set before `treeRoot`. Both sidebar templates pass `language`
+    // first; the tree resolves stored topic versions with it while being built.
+    @api language?: string;
+
     @api
     get treeRoot() {
         return this._treeRoot!;
@@ -11,7 +15,7 @@ export default class Tree extends LightningElement {
 
     set treeRoot(value: TreeNode | string) {
         value = toJson(value);
-        this._treeHandler = new TreeHandler();
+        this._treeHandler = new TreeHandler(this.language);
         this._treeRoot = this._treeHandler.initialize(value as TreeNode);
         if (this._value) {
             this.selectedKey = this._treeHandler.getKeyByName(this._value);

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

@@ -22,8 +22,10 @@ const ROOT_KEY = "0";
 export class TreeHandler {
     private _nodeMap: { [key: string]: MapItem };
     private _nameKeyMap: { [key: string]: string };
+    private _language?: string;
 
-    constructor() {
+    constructor(language?: string) {
+        this._language = language;
         this._nodeMap = {};
         this._nameKeyMap = {};
     }
@@ -73,7 +75,7 @@ export class TreeHandler {
         }
     ): VersionedInternalTreeNode {
         const ownSelected = node.versions?.length
-            ? resolveSelectedVersion(node)
+            ? resolveSelectedVersion(node, this._language)
             : undefined;
         const versionContext =
             ownSelected && node.versions
@@ -115,8 +117,13 @@ export class TreeHandler {
         };
 
         const mapItem = { node: convertedNode, parent };
-        if (node.children && node.children.length > 0) {
-            convertedNode.children = node.children.map((child, index) =>
+        // Prefer the selected version's own topic list when the server sent one.
+        // Otherwise keep the latest children and rewrite their hrefs.
+        const childNodes = Array.isArray(ownSelected?.children)
+            ? ownSelected.children
+            : node.children;
+        if (childNodes && childNodes.length > 0) {
+            convertedNode.children = childNodes.map((child, index) =>
                 this.convert(child, level + 1, mapItem, index, versionContext)
             );
         }

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

@@ -16,6 +16,14 @@
     display: flex;
     align-items: center;
     min-width: 0;
+    position: relative;
+}
+
+/* The tile's keyboard focus layers fill this row, picker included. isolate
+   keeps the fill above the row's background and below its content. Only while
+   focus is inside: a row that is always isolated traps its picker's menu. */
+.tree-item-row:focus-within {
+    isolation: isolate;
 }
 
 .tree-item-row dx-tree-tile {

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

@@ -15,7 +15,7 @@
             has-version-picker={showVersionPicker}
             onclick={onLinkClick}
         ></dx-tree-tile>
-        <doc-version-picker
+        <dx-version-picker
             if:true={showVersionPicker}
             class="tree-item-version-picker"
             small="true"
@@ -25,7 +25,7 @@
             onchange={onVersionChange}
             onclick={onVersionPickerClick}
             onmousedown={onVersionPickerClick}
-        ></doc-version-picker>
+        ></dx-version-picker>
     </div>
     <img
         if:true={showChildrenLoading}
@@ -39,6 +39,7 @@
                 key={child.key}
                 tree-node={child}
                 selected-key={selectedKey}
+                language={language}
             ></dx-tree-item>
         </template>
     </template>

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

@@ -23,6 +23,7 @@ type VersionedInternalTreeNode = InternalTreeNode & {
 export default class TreeItem extends LightningElement {
     @api selectedKey?: string;
     @api isRoot: boolean = false;
+    @api language?: string;
 
     @api
     public get treeNode() {
@@ -127,7 +128,11 @@ export default class TreeItem extends LightningElement {
     }
 
     private get selectedVersion(): TopicVersionOption | undefined {
-        return resolveSelectedVersion(this._treeNode);
+        return resolveSelectedVersion(this._treeNode, this.language);
+    }
+
+    private get topicVersionKey(): string {
+        return getTopicVersionKey(this._treeNode, this.language);
     }
 
     private get isLatestVersion(): boolean {
@@ -171,8 +176,8 @@ export default class TreeItem extends LightningElement {
 
         // 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);
+        const selected = this.selectedVersion;
+        const topicKey = this.topicVersionKey;
         if (this.versions?.length && selected && topicKey) {
             persistTopicVersion(topicKey, selected.id);
         }
@@ -180,7 +185,7 @@ export default class TreeItem extends LightningElement {
 
     private onVersionChange(event: CustomEvent): void {
         event.stopPropagation();
-        persistTopicVersion(getTopicVersionKey(this._treeNode), event.detail);
+        persistTopicVersion(this.topicVersionKey, event.detail);
     }
 
     private onVersionPickerClick(event: Event): void {
@@ -213,8 +218,12 @@ export default class TreeItem extends LightningElement {
     }
 
     private preventDefaultLinkBehavior(event: Event) {
-        // prevent page refresh if href isn't present or link is already active
+        // Nodes with no link.href (AMF items use name) must not follow the
+        // anchor. Parent-only topics are excluded: their href is the child page.
+        // Otherwise cancel only an empty href or a click on the current path.
         if (
+            (!this._treeNode.link?.href &&
+                !isParentOnlyTopic(this._treeNode)) ||
             !this.href ||
             normalizePath(this.href) === normalizePath(window.location.pathname)
         ) {

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

@@ -217,3 +217,56 @@ a:visited.tile-root,
 a:link.tile-root {
     color: var(--dx-g-blue-vibrant-20);
 }
+
+/* Keyboard focus matches dx-dropdown-option: a light fill, a 2px blue inset
+   ring, and a white inner band. The layers fill dx-tree-item's row (it sets
+   position: relative), so a version picker beside the link sits inside the
+   focus box. Undo the shared tree item focus box (commonTreeItem) first. */
+:host .sidebar-item:focus-visible {
+    margin: 0;
+    padding: 6px var(--dx-g-spacing-lg) 6px
+        var(--dx-g-global-header-padding-horizontal);
+    outline: none;
+    border-radius: 0;
+}
+
+/* Keep the picker row's 4px right padding on focus, so the label does not rewrap. */
+:host .tile-with-version-picker:focus-visible {
+    padding-right: var(--dx-g-spacing-xs);
+}
+
+:host .sidebar-item:focus-visible .indentation {
+    padding-top: 0;
+    padding-bottom: 0;
+    outline: none;
+}
+
+:host .sidebar-item:focus-visible::before,
+:host .sidebar-item:focus-visible::after {
+    content: "";
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+}
+
+:host .sidebar-item:focus-visible::before {
+    z-index: -1;
+    background: var(--dx-g-cloud-blue-vibrant-95);
+}
+
+:host .sidebar-item:focus-visible::after {
+    z-index: 1;
+    box-shadow: inset 0 0 0 2px var(--dx-g-blue-vibrant-60),
+        inset 0 0 0 4px white;
+}
+
+/* A selected item keeps its left bar, inside the ring, when it also has keyboard focus. */
+:host
+    .sidebar-item:is(
+        .sidebar-item-selected,
+        .sidebar-item-selected-text
+    ):focus-visible::after {
+    box-shadow: inset 0 0 0 2px var(--dx-g-blue-vibrant-60),
+        inset 0 0 0 4px white,
+        inset calc(2 * var(--dx-g-spacing-xs)) 0 0 0 var(--dx-g-blue-vibrant-40);
+}

package/src/modules/dx/versionPicker/versionPicker.css

@@ -0,0 +1,248 @@
+@import "dxHelpers/reset";
+
+/* NOTE: dx-version-picker-width is used by both dx-button and dx-dropdown to maintain a consistent width. */
+:host {
+    /* Always positioned so the popover's containing block stays the picker.
+       Toggling position with aria-expanded lets the menu jump to the sidebar
+       (top of the ToC) for a frame before LWC hides it. */
+    position: relative;
+
+    --dx-c-dropdown-option-font-weight: normal;
+    --dx-c-dropdown-option-font-size: var(--dx-g-text-base);
+    --dx-c-dropdown-option-label-color: var(--dx-g-gray-10);
+    --dx-c-dropdown-option-active-label-color: var(--dx-g-gray-10);
+    --dx-c-dropdown-option-padding: var(--dx-g-spacing-sm)
+        var(--dx-g-spacing-lg);
+    --dx-c-popover-padding: var(--dx-g-spacing-sm) 0;
+    --popover-container-open-transform: translateY(4px);
+    --dx-c-version-picker-focus-ring: 0 0 0 2px white,
+        0 0 0 4px var(--dx-g-blue-vibrant-60);
+}
+
+/* Open menus must stack above later sibling pickers in the sidebar. */
+:host(:has([aria-expanded="true"])) {
+    z-index: 2;
+}
+
+.version-picker-container {
+    /* Override --dx-version-picker-padding to change the inset (e.g. when the
+       picker sits inside an already-padded container). */
+    padding: var(
+        --dx-version-picker-padding,
+        var(--dx-g-spacing-sm) var(--dx-g-spacing-lg) var(--dx-g-spacing-sm)
+            var(--dx-g-global-header-padding-horizontal)
+    );
+
+    /* Override --dx-version-picker-divider (e.g. `none`) to restyle dividers. */
+    border-top: var(--dx-version-picker-divider, 1px solid var(--dx-g-gray-90));
+    border-bottom: var(
+        --dx-version-picker-divider,
+        1px solid var(--dx-g-gray-90)
+    );
+}
+
+/* Inline sidebar variant: drop the header-slot chrome so the picker sits
+   beside a tree node without extra padding or divider lines. */
+.version-picker-container-small {
+    display: flex;
+    align-items: center;
+    padding: 0;
+    border: none;
+}
+
+.version-picker-button {
+    display: flex;
+    width: var(--dx-version-picker-width, 296px);
+    overflow: visible;
+
+    --dx-c-button-horizontal-spacing: var(--dx-g-spacing-sm);
+    --dx-g-button-icon-color: var(--dx-g-gray-50);
+}
+
+.version-picker-button:hover,
+.version-picker-button[aria-expanded="true"] {
+    --dx-g-button-icon-color: var(--dx-g-blue-vibrant-20);
+}
+
+/**
+ * NOTE: This CSS ensures the span inside the button stays within the parent's width, avoiding overflow.
+ * Not keeping this in common component to ensure that existing functionality works as it is.
+ */
+dx-button::part(content) {
+    width: inherit;
+    overflow: hidden;
+}
+
+/* Border width stays 1px in every state. Hover, open, and focus paint the
+   2px blue stroke with an inset shadow so the box does not grow.
+   Tertiary's hover border is overridden. */
+.version-picker-button::part(container) {
+    box-sizing: border-box;
+    background: white;
+    border: 1px solid var(--dx-g-gray-50);
+    border-radius: var(--dx-g-spacing-xs);
+    box-shadow: none;
+    color: var(--dx-g-gray-10);
+    outline: none;
+    transition: var(--dx-g-transition-hue-1x), box-shadow 0.15s linear;
+}
+
+/* Hover only (not open): 2px #032D60 on #EEF4FF, no ring.
+   Border color matches the fill so the 1px border does not add a third
+   pixel around the inset stroke.
+   :focus-visible is included so click-open + Escape (which upgrades the
+   trigger to keyboard focus) still looks like hover while the pointer is on
+   the picker. */
+.version-picker-button:hover:not([aria-expanded="true"])::part(container),
+.version-picker-button:hover:not([aria-expanded="true"])::part(
+        container
+    ):focus-visible {
+    background: var(--dx-g-blue-vibrant-95);
+    border: 1px solid var(--dx-g-blue-vibrant-95);
+    box-shadow: inset 0 0 0 2px var(--dx-g-blue-vibrant-20);
+}
+
+/* Open keeps the fill and the 2px stroke. The focus ring is keyboard-only,
+   on the closed picker below. */
+.version-picker-button[aria-expanded="true"]::part(container) {
+    background: var(--dx-g-blue-vibrant-95);
+    border: 1px solid var(--dx-g-blue-vibrant-95);
+    border-radius: var(--dx-g-spacing-xs);
+    box-shadow: inset 0 0 0 2px var(--dx-g-blue-vibrant-20);
+}
+
+/* Keyboard focus while closed. */
+.version-picker-button:not([aria-expanded="true"])::part(
+        container
+    ):focus-visible {
+    --dx-g-button-icon-color: var(--dx-g-blue-vibrant-20);
+
+    background: var(--dx-g-blue-vibrant-95);
+    border: 1px solid var(--dx-g-blue-vibrant-95);
+    border-radius: var(--dx-g-spacing-xs);
+    box-shadow: inset 0 0 0 2px var(--dx-g-blue-vibrant-20),
+        var(--dx-c-version-picker-focus-ring);
+}
+
+.selected-version {
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+}
+
+.selected-version-label {
+    flex: 1;
+    overflow: hidden;
+    text-align: left;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+dx-type-badge.latest-badge,
+dx-type-badge.not-latest-badge {
+    margin-left: var(--dx-g-spacing-sm);
+}
+
+/* ------------------------------------------------------------------ *
+ * Small "dot" variant (opt-in via `small`). Additive 
+ * ------------------------------------------------------------------ */
+
+/* Menu is capped at the ToC width (296px), not the 104px trigger, so options
+   keep the same 16px / 8px 24px / gray-10 type as the default picker. */
+.version-picker-dropdown-small {
+    --dx-c-dropdown-option-font-size: var(--dx-g-text-base);
+    --dx-c-dropdown-option-padding: var(--dx-g-spacing-sm)
+        var(--dx-g-spacing-lg);
+    --dx-c-dropdown-option-label-color: var(--dx-g-gray-10);
+    --dx-c-dropdown-option-border-radius: 0;
+    --dx-c-popover-border: none;
+
+    /* Hug the labels (down to the shortest) but never wider than the ToC
+       content: 296px on desktop, and on the smallest breakpoint the sidebar
+       variable grows with the viewport up to 720px. Long labels wrap inside
+       that cap. */
+    --dx-c-dropdown-menu-max-width: var(--dx-version-picker-width, 296px);
+    --dx-c-dropdown-fit-white-space: normal;
+    --dx-c-dropdown-fit-overflow: hidden;
+    --dx-c-dropdown-fit-text-overflow: clip;
+    --dx-c-dropdown-option-overflow-wrap: anywhere;
+}
+
+.version-picker-button-small {
+    width: fit-content;
+    max-width: 104px;
+
+    --dx-c-button-font-size: var(--dx-g-text-xs);
+    --dx-c-button-font-weight: var(--dx-g-font-normal);
+    --dx-c-button-line-height: var(--dx-g-spacing-lg);
+    --dx-c-button-icon-gap: var(--dx-g-spacing-2xs);
+}
+
+/* min-width: 0 on each flex ancestor lets the label truncate: a flex item's
+   default min-width: auto refuses to shrink below its content and overrides the
+   host's max-width, so without this the trigger overflows instead. */
+.version-picker-button-small::part(content) {
+    display: flex;
+    flex: 1;
+    min-width: 0;
+    width: auto;
+    overflow: hidden;
+}
+
+/* width:100% re-ties to the 104px-capped host (container is width:inherit,
+   which copies width but not max-width). Border/bg/states are shared above. */
+.version-picker-button-small::part(container) {
+    width: 100%;
+    height: var(--dx-g-spacing-lg);
+    padding: 0 var(--dx-g-spacing-xs);
+}
+
+.selected-version-small {
+    flex: 1;
+    min-width: 0;
+}
+
+.version-picker-dot {
+    flex: 0 0 auto;
+    width: var(--dx-g-spacing-sm);
+    height: var(--dx-g-spacing-sm);
+    margin-right: var(--dx-g-spacing-xs);
+    border-radius: 50%;
+}
+
+.version-picker-dot-latest {
+    background: var(--dx-g-green-vibrant-60);
+}
+
+.version-picker-dot-not-latest {
+    background: var(--dx-g-yellow-vibrant-80);
+}
+
+/* inline-block (not flex) so the label can truncate; line-height centers it. */
+.version-picker-readonly {
+    box-sizing: border-box;
+    display: inline-block;
+    width: var(--dx-version-picker-width, 296px);
+    height: var(--dx-g-spacing-xl);
+    margin: 0;
+    padding: 0 var(--dx-g-spacing-sm);
+    border: 1px solid var(--dx-g-gray-80);
+    border-radius: var(--dx-g-spacing-xs);
+    overflow: hidden;
+    color: var(--dx-g-gray-10);
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    font: var(--dx-g-font-normal) var(--dx-g-text-sm) / var(--dx-g-spacing-xl)
+            var(--dx-g-font-sans),
+        sans-serif;
+}
+
+.version-picker-readonly-small {
+    width: fit-content;
+    max-width: 104px;
+    height: var(--dx-g-spacing-lg);
+    padding: 0 var(--dx-g-spacing-xs);
+    font: var(--dx-g-font-normal) var(--dx-g-text-xs) / var(--dx-g-spacing-lg)
+            var(--dx-g-font-sans),
+        sans-serif;
+}

package/src/modules/dx/versionPicker/versionPicker.html

@@ -0,0 +1,73 @@
+<template>
+    <div lwc:if={showVersionPicker} class={containerClass}>
+        <!-- Small read-only: plain value, no dropdown -->
+        <p
+            lwc:if={readOnly}
+            class={readOnlyClass}
+            title={selectedVersion.label}
+        >
+            {selectedVersion.label}
+        </p>
+
+        <dx-dropdown
+            lwc:else
+            class={dropdownClass}
+            options={versions}
+            analytics-event="custEv_docVersionSelect"
+            analytics-payload={analyticsPayload}
+            value={selectedVersion.id}
+            width-mode={dropdownWidthMode}
+            onchange={onVersionChange}
+        >
+            <dx-button
+                class={triggerClass}
+                variant="tertiary"
+                size="small"
+                font="sans"
+                icon-symbol="chevrondown"
+                icon-size={triggerIconSize}
+                aria-label={triggerAriaLabel}
+            >
+                <div class={selectedVersionClass}>
+                    <!-- Small: leading colored dot -->
+                    <template lwc:if={small}>
+                        <template lwc:if={showLatestTag}>
+                            <span class={dotClass} aria-hidden="true"></span>
+                        </template>
+                        <p
+                            class="selected-version-label"
+                            title={selectedVersion.label}
+                        >
+                            {selectedVersion.label}
+                        </p>
+                    </template>
+                    <!-- Default: trailing Latest/Not-Latest badge -->
+                    <template lwc:else>
+                        <p
+                            class="selected-version-label"
+                            title={selectedVersion.label}
+                        >
+                            {selectedVersion.label}
+                        </p>
+                        <template lwc:if={showLatestTag}>
+                            <dx-type-badge
+                                class="latest-badge"
+                                lwc:if={latestVersion}
+                                variant="status-success"
+                                value="Latest"
+                                size="small"
+                            ></dx-type-badge>
+                            <dx-type-badge
+                                class="not-latest-badge"
+                                lwc:else
+                                variant="status-warning"
+                                value="Not Latest"
+                                size="small"
+                            ></dx-type-badge>
+                        </template>
+                    </template>
+                </div>
+            </dx-button>
+        </dx-dropdown>
+    </div>
+</template>

package/src/modules/dx/versionPicker/versionPicker.ts

@@ -0,0 +1,157 @@
+import { LightningElement, api, track } from "lwc";
+import cx from "classnames";
+
+import { AnalyticsPayload, OptionWithNested } from "typings/custom";
+
+import { toJson, normalizeBoolean } from "dxUtils/normalizers";
+
+export default class VersionPicker extends LightningElement {
+    @api analyticsEvent?: string;
+    @api analyticsPayload?: AnalyticsPayload;
+
+    @track private _versions!: OptionWithNested[];
+    private _selectedVersion?: OptionWithNested;
+    private _latestVersion: boolean = false;
+    private _hideBadge: boolean = false;
+    private _small: boolean = false;
+    private _readOnly: boolean = false;
+
+    @api
+    get versions() {
+        return this._versions;
+    }
+
+    set versions(value: OptionWithNested[]) {
+        this._versions = toJson(value);
+    }
+
+    @api
+    get selectedVersion(): OptionWithNested | undefined {
+        return this._selectedVersion || this.versions[0];
+    }
+
+    set selectedVersion(value: OptionWithNested) {
+        if (value) {
+            this._selectedVersion = toJson(value);
+        }
+    }
+
+    @api
+    get latestVersion() {
+        return this._latestVersion;
+    }
+
+    set latestVersion(value) {
+        this._latestVersion = normalizeBoolean(value);
+    }
+
+    @api
+    get hideBadge() {
+        return this._hideBadge;
+    }
+
+    set hideBadge(value) {
+        this._hideBadge = normalizeBoolean(value);
+    }
+
+    // Opt-in compact "dot" variant (24px, abbreviated label). Off by default so
+    // existing consumers render the default trigger unchanged.
+    @api
+    get small() {
+        return this._small;
+    }
+
+    set small(value) {
+        this._small = normalizeBoolean(value);
+    }
+
+    // Opt-in read-only state: plain value, no dropdown menu.
+    @api
+    get readOnly() {
+        return this._readOnly;
+    }
+
+    set readOnly(value) {
+        this._readOnly = normalizeBoolean(value);
+    }
+
+    private get showVersionPicker() {
+        return this._versions && this._versions.length !== 0;
+    }
+
+    private get containerClass(): string {
+        return this.small
+            ? "version-picker-container-small"
+            : "version-picker-container";
+    }
+
+    private get showLatestTag(): boolean {
+        return !this.hideBadge;
+    }
+
+    private get readOnlyClass(): string {
+        return cx(
+            "version-picker-readonly",
+            this.small && "version-picker-readonly-small"
+        );
+    }
+
+    private get dotClass(): string {
+        return `version-picker-dot ${
+            this.latestVersion
+                ? "version-picker-dot-latest"
+                : "version-picker-dot-not-latest"
+        }`;
+    }
+
+    // Accessible name for the small trigger: includes the latest state so it
+    // isn't conveyed by the dot's color alone (WCAG 1.4.1). Omits the state
+    // when the indicator is hidden.
+    private get smallTriggerAriaLabel(): string {
+        const label = this.selectedVersion?.label ?? "";
+        if (!this.showLatestTag) {
+            return label;
+        }
+        return `${label}, ${this.latestVersion ? "Latest" : "Not Latest"}`;
+    }
+
+    // --- Per-variant values for the shared dropdown/button markup below. The
+    // small variant opts into extra classes and a compact chevron.
+
+    // Not cx(): the default must have NO class attribute (cx returns "", which
+    // would render class="" and break the frozen consumer snapshots).
+    private get dropdownClass(): string | undefined {
+        return this.small ? "version-picker-dropdown-small" : undefined;
+    }
+
+    // "full" matches the trigger (ToC width). "fit-end" sizes to the labels,
+    // caps at the ToC width, and opens inward.
+    private get dropdownWidthMode(): "full" | "fit-end" {
+        return this.small ? "fit-end" : "full";
+    }
+
+    private get triggerClass(): string {
+        return cx(
+            "version-picker-button",
+            this.small && "version-picker-button-small"
+        );
+    }
+
+    private get triggerIconSize(): string {
+        return this.small ? "xsmall" : "medium";
+    }
+
+    // Default returns "" (dx-button's own default) so the trigger's rendered
+    // aria-label is unchanged for the default variant.
+    private get triggerAriaLabel(): string {
+        return this.small ? this.smallTriggerAriaLabel : "";
+    }
+
+    private get selectedVersionClass(): string {
+        return cx("selected-version", this.small && "selected-version-small");
+    }
+
+    private onVersionChange(e: CustomEvent) {
+        this.dispatchEvent(new CustomEvent("change", { detail: e.detail }));
+    }
+}

package/src/modules/dxHelpers/commonSidebar/commonSidebar.css

@@ -11,7 +11,7 @@
     --dx-c-sidebar-button-border-hover: var(--dx-g-blue-vibrant-50);
     --dx-c-sidebar-left-padding: var(--dx-g-global-header-padding-horizontal);
     --dx-c-sidebar-vertical-padding: var(--dx-g-spacing-md);
-    --doc-version-picker-width: 296px;
+    --dx-version-picker-width: 296px;
 }
 
 .header {
@@ -172,7 +172,7 @@
 
 @media screen and (max-width: 768px) {
     :host {
-        --doc-version-picker-width: calc(
+        --dx-version-picker-width: calc(
             100vw - var(--dx-c-sidebar-left-padding) - var(--dx-g-spacing-lg)
         );
     }

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

@@ -1,4 +1,9 @@
 export const TOPIC_VERSION_SESSION_KEY = "sfdocs-topic-version-selections";
+export const DOCS_PATH_SEGMENT = "docs";
+// Locale position in the path segments: `/docs/<locale>` for Docs,
+// `/docs/<brand>/<locale>` for Guides/References.
+export const DOCS_LOCALE_SEGMENT_INDEX = 1;
+export const REFERENCES_LOCALE_SEGMENT_INDEX = 2;
 
 export type TopicVersionOption = {
     id: string;
@@ -9,6 +14,10 @@ export type TopicVersionOption = {
         href?: string;
         target?: string;
     };
+    /** Topics authored under this version. Absent when the client only rewrites hrefs. */
+    // VersionedNode also points back here through `versions`.
+    // eslint-disable-next-line no-use-before-define
+    children?: VersionedNode[];
 };
 
 export type VersionedNode = {
@@ -90,20 +99,48 @@ export function persistTopicVersion(
     );
 }
 
+/**
+ * Normalizes the path, then removes `locale` when it sits in the docs or
+ * references locale position, so every locale shares one session key.
+ */
+function stripLocaleFromPath(path: string, locale?: string): string {
+    const normalized = normalizePath(path);
+    const segments = normalized.split("/").filter(Boolean);
+    const normalizedLocale = locale?.toLowerCase();
+    if (!normalizedLocale || segments[0] !== DOCS_PATH_SEGMENT) {
+        return normalized;
+    }
+
+    const localeIndex = [
+        DOCS_LOCALE_SEGMENT_INDEX,
+        REFERENCES_LOCALE_SEGMENT_INDEX
+    ].find((index) => segments[index]?.toLowerCase() === normalizedLocale);
+    if (localeIndex === undefined) {
+        return normalized;
+    }
+
+    segments.splice(localeIndex, 1);
+    return `/${segments.join("/")}`;
+}
+
 /**
  * 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).
+ * The locale is stripped so a selection carries across locales.
  */
-export function getTopicVersionKey(node: VersionedNode | undefined): string {
+export function getTopicVersionKey(
+    node: VersionedNode | undefined,
+    locale?: string
+): string {
     if (!node) {
         return "";
     }
     if (node.name) {
-        return node.name;
+        return stripLocaleFromPath(node.name, locale);
     }
     const latestHref = node.versions?.[0]?.link?.href;
     if (latestHref) {
-        return latestHref;
+        return stripLocaleFromPath(latestHref, locale);
     }
     return node.label || "";
 }
@@ -336,11 +373,18 @@ export function collectSubtreeCanonicalHrefs(
     if (includeSelf && own) {
         hrefs.push(own);
     }
-    for (const child of node.children || []) {
-        if (child.versions?.length || child.link?.target === "_blank") {
-            continue;
+    const collectChildHrefs = (children?: VersionedNode[]) => {
+        for (const child of children || []) {
+            if (child.versions?.length || child.link?.target === "_blank") {
+                continue;
+            }
+            hrefs.push(...collectSubtreeCanonicalHrefs(child));
         }
-        hrefs.push(...collectSubtreeCanonicalHrefs(child));
+    };
+    collectChildHrefs(node.children);
+    // Topics that exist only on an older version are not in `children`.
+    for (const version of node.versions || []) {
+        collectChildHrefs(version.children);
     }
     return hrefs;
 }
@@ -431,6 +475,9 @@ export function findTopicVersionForCurrentPage(
                 match = { node, version };
             }
             walk(node.children);
+            for (const versionOption of node.versions || []) {
+                walk(versionOption.children);
+            }
         }
     };
     walk(nodes);
@@ -457,7 +504,8 @@ export function latestHrefForCurrentPage(
 }
 
 export function resolveSelectedVersion(
-    node: VersionedNode | undefined
+    node: VersionedNode | undefined,
+    locale?: string
 ): TopicVersionOption | undefined {
     const versions = node?.versions;
     if (!node || !versions?.length) {
@@ -471,6 +519,7 @@ export function resolveSelectedVersion(
         return fromUrl;
     }
 
-    const storedId = readTopicVersionSelections()[getTopicVersionKey(node)];
+    const storedId =
+        readTopicVersionSelections()[getTopicVersionKey(node, locale)];
     return versions.find((version) => version.id === storedId) || versions[0];
 }