@salesforcedevs/dx-components 1.40.0-docs-feedback-4 → 1.40.0-integration-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,6 +1,6 @@
 {
   "name": "@salesforcedevs/dx-components",
-  "version": "1.40.0-docs-feedback-4",
+  "version": "1.40.0-integration-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.0"
+  }
 }

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/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,28 @@
     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);
+}
+
 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="tree-item-row">
         <dx-tree-tile
             href={href}
             is-root={isRoot}
@@ -11,8 +11,21 @@
             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,6 +45,9 @@ export default class TreeItem extends LightningElement {
     }
 
     private get isSelected(): boolean {
+        if (isParentOnlyTopic(this._treeNode)) {
+            return false;
+        }
         return this._treeNode.key === this.selectedKey && !this.isExternalLink;
     }
 
@@ -49,10 +67,6 @@ export default class TreeItem extends LightningElement {
         return this.hasChildren || this.isChildrenLoading;
     }
 
-    private get isContentlessParent(): boolean {
-        return this.isParent && !!this._treeNode?.redirectToChild;
-    }
-
     private get showChildren(): boolean {
         return this.isExpanded && this.hasChildren;
     }
@@ -83,8 +97,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 +154,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 +201,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();
         }
@@ -144,31 +211,18 @@ export default class TreeItem extends LightningElement {
     private onLinkClick(event: Event): void {
         this.preventDefaultLinkBehavior(event);
 
-        /**
-         * A content-less parent that redirects to a content child navigates
-         * like a normal link (navigation handles selection and ancestor
-         * expansion). A content-less parent whose chain has no content page to
-         * redirect to only expands, it is never selected.
-         */
-        if (this.isContentlessParent) {
-            if (this._treeNode.link?.href) {
-                this.sendGtm(event);
-                return;
-            }
-            const isSelectAction = false;
-            this.doExpand(isSelectAction);
-            this.sendGtm(event);
-            return;
-        }
-
         if (this.isParent) {
             const isSelectAction = true;
             this.doExpand(isSelectAction);
         }
 
         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 +240,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.html

@@ -1,5 +1,5 @@
 <template>
-    <a href={href} class={tileClass} target={target} aria-label={linkAriaLabel}>
+    <a href={href} class={tileClass} target={target}>
         <div class="flex indentation" role="heading" aria-level={tileAriaLevel}>
             <div class="flex tile-expand-icon tile-icon" if:true={showArrow}>
                 <dx-icon

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

@@ -32,33 +32,12 @@ export default class TreeTile extends LightningElement {
     @api showArrow = false;
     @api target!: string;
     @api isExternalLink = false;
+    @api hasVersionPicker = false;
 
     get tileAriaLevel() {
         return this.treeNode.level + 2;
     }
 
-    /**
-     * Accessible name for the link. If a parent redirects to its first child,
-     * include both the parent and child labels so the destination is clear to
-     * screen reader users (WCAG 2.4.4)
-     */
-    get linkAriaLabel(): string | null {
-        if (!this.treeNode.redirectToChild || !this.treeNode.link?.href) {
-            return null;
-        }
-        /**
-         * The redirect can target a deep descendant, so walk the first-child
-         * chain to the node that owns the destination link and name it.
-         */
-        let destination = this.treeNode.children?.[0];
-        while (destination?.redirectToChild) {
-            destination = destination.children?.[0];
-        }
-        return destination?.link?.href === this.treeNode.link.href
-            ? `${this.treeNode.label}, opens ${destination.label}`
-            : null;
-    }
-
     private get iconSize() {
         return "xsmall";
     }
@@ -101,7 +80,8 @@ 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,
+            "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/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,401 @@
+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[];
+};
+
+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;
+}
+
+/**
+ * First descendant that has a page (own href/name). Used so parent-only
+ * sections select and navigate to content instead of an empty header.
+ */
+export function firstContentNode(
+    node: VersionedNode | undefined
+): VersionedNode | undefined {
+    if (!node || node.link?.target === "_blank") {
+        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];
+}