@salesforcedevs/dx-components 1.40.11 → 1.42.0-final-test

package/src/modules/dx/sidebarSearchResult/sidebarSearchResult.css

@@ -2,34 +2,74 @@
 @import "dxHelpers/text";
 @import "dxHelpers/commonTreeItem";
 
+/* List item states: Default, Hover (blue-vibrant-50 text only), Selected (cloud blue bar), Focus */
 a {
     display: flex;
     flex-direction: column;
 }
 
+/* Match "Results" heading alignment. Less item padding so total height unchanged when box has more inner padding. */
 .sidebar-item {
-    padding: var(--dx-g-spacing-smd) var(--dx-g-spacing-lg)
-        var(--dx-g-spacing-smd) var(--dx-g-global-header-padding-horizontal);
+    padding: 0 var(--dx-g-spacing-lg) 0 var(--dx-c-sidebar-left-padding);
+    background: transparent;
+    transition: background-color var(--dx-g-transition-hue-1x, 0.1s ease);
+    overflow: visible;
 }
 
-.sidebar-item:not(.sidebar-item-selected):focus-visible {
-    padding: var(--dx-g-spacing-smd) 0;
-    margin: 0 var(--dx-g-spacing-lg) 0
-        var(--dx-g-global-header-padding-horizontal);
-    outline: var(--dx-g-spacing-2xs) solid var(--dx-g-blue-vibrant-40);
-    border-radius: var(--dx-g-spacing-2xs);
+/* Inner block: more vertical padding (12px) so box has more space top/bottom; 8px horizontal. margin-left so text aligns with Results. */
+.search-result {
+    margin-left: calc(-1 * var(--dx-g-spacing-sm));
+    padding: var(--dx-g-spacing-smd) var(--dx-g-spacing-sm);
+    border: none;
+    border-radius: var(--dx-g-spacing-xs);
+    transition: background-color var(--dx-g-transition-hue-1x, 0.1s ease);
 }
 
+/* Hover: no background; text → blue-vibrant-50 (unselected and selected) */
+.sidebar-item:hover .title {
+    color: var(--dx-g-blue-vibrant-50);
+}
+
+.sidebar-item:hover .description {
+    --dx-g-text-body-color: var(--dx-g-blue-vibrant-50);
+}
+
+/* Selected: full-width cloud blue bar + 4px blue-vibrant-40 left accent; text matches unselected */
+.sidebar-item-selected {
+    background: var(--dx-g-cloud-blue-vibrant-95);
+    border-radius: 0;
+    box-shadow: inset var(--dx-g-spacing-xs) 0 0 0 var(--dx-g-blue-vibrant-40);
+
+    /* Override commonTreeItem selected text color so .title / .description tokens apply */
+    color: unset !important;
+}
+
+.sidebar-item-selected .search-result {
+    position: relative;
+    z-index: 1;
+    background: transparent;
+    color: inherit;
+}
+
+/* Focus: same ring for selected and unselected (inner .search-result, not full-width bar) */
+.sidebar-item:focus-visible {
+    outline: none !important;
+}
+
+/* Override commonTreeItem selected:focus padding/outline so focus matches unselected */
 .sidebar-item-selected:focus-visible {
-    padding: 0 var(--dx-g-spacing-lg) 0
-        var(--dx-g-global-header-padding-horizontal);
+    padding-top: 0;
+    padding-bottom: 0;
+    outline: none !important;
+}
+
+.sidebar-item:focus-visible .search-result {
     outline: none;
+    border-radius: var(--dx-g-spacing-xs);
+    border: none;
 
-    .search-result {
-        outline: var(--dx-g-spacing-2xs) solid var(--dx-g-blue-vibrant-40);
-        border-radius: var(--dx-g-spacing-2xs);
-        padding: var(--dx-g-spacing-smd) 0;
-    }
+    /* White inner ring reads clearly on selected (cloud 95) and hover backgrounds */
+    box-shadow: 0 0 0 2px white, 0 0 0 4px var(--dx-g-blue-vibrant-60);
 }
 
 .search-text {
@@ -41,6 +81,7 @@ a {
 }
 
 .description {
+    line-clamp: 3;
     -webkit-line-clamp: 3;
     overflow-wrap: break-word;
 
@@ -52,16 +93,13 @@ a {
 
 .title {
     color: var(--dx-g-text-heading-color);
+    line-height: 18px;
+    display: block;
+    margin-bottom: 4px;
 }
 
-.title:hover {
-    color: var(--dx-g-blue-vibrant-50);
-}
-
+/* Match full-doc search highlight: light yellow from dx-css-variables */
 .bold {
+    background-color: var(--dx-g-yellow-vibrant-90);
     font-weight: 700;
 }
-
-a > *:not(:last-child) {
-    margin-bottom: var(--dx-g-spacing-xs);
-}

package/src/modules/dx/sidebarSearchResult/sidebarSearchResult.ts

@@ -1,8 +1,9 @@
 import { LightningElement, api } from "lwc";
 import cx from "classnames";
-import { CoveoHighlights } from "typings/custom";
+import { track } from "dxUtils/analytics";
+import { HighlightedSections } from "typings/custom";
 
-const toChunks = (value: string, highlights: CoveoHighlights) => {
+const toChunks = (value: string, highlights: HighlightedSections) => {
     if (!highlights || highlights.length < 1) {
         return [
             {
@@ -51,11 +52,11 @@ const toChunks = (value: string, highlights: CoveoHighlights) => {
 
 export default class SidebarSearchResult extends LightningElement {
     @api description!: string;
-    @api descriptionHighlights!: CoveoHighlights;
+    @api descriptionHighlights!: HighlightedSections;
     @api href!: string;
     @api selected!: boolean;
     @api header!: string;
-    @api titleHighlights!: CoveoHighlights;
+    @api titleHighlights!: HighlightedSections;
     @api select!: Function;
 
     private get titleChunks() {
@@ -72,6 +73,13 @@ export default class SidebarSearchResult extends LightningElement {
 
     private onClick(e: PointerEvent) {
         e.preventDefault();
+        track(e.currentTarget!, "custEv_scopedSearchItemSelected", {
+            click_text: this.header,
+            click_url: this.href,
+            element_title: this.header,
+            element_type: "link",
+            content_category: "documentation"
+        });
         this.select();
         window.location.href = this.href;
     }

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

@@ -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;
 };
@@ -10,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 = {};
     }
@@ -21,7 +35,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 +65,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, this._language)
+            : 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 +109,57 @@ 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
+            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)
+        // 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)
             );
         }
 
         this._nodeMap[convertedNode.key] = mapItem;
-        this._nameKeyMap[convertedNode.name] = convertedNode.key;
+        this.indexName(convertedNode.name, convertedNode.key);
+        // A redirect parent can carry a child's href. This index runs after
+        // the child, so recording it would make the parent win selection.
+        if (!convertedNode.redirectToChild) {
+            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

@@ -2,6 +2,47 @@
 
 :host {
     display: block;
+
+    /* Keep a stable containing block; z-index still lifts the open menu. */
+    position: relative;
+}
+
+/* Lift this row above later sibling pickers while its menu is open. */
+:host(:focus-within) {
+    z-index: 2;
+}
+
+.tree-item-row {
+    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.
+   z-index lifts the open menu above the child items under this row.
+   :host(:focus-within) only stacks this item above sibling rows. */
+.tree-item-row:focus-within {
+    isolation: isolate;
+    z-index: 1;
+}
+
+.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);
+    overflow: visible;
+}
+
+.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 {

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>
+        <dx-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}
+        ></dx-version-picker>
+    </div>
     <img
         if:true={showChildrenLoading}
         class="tree-children-loading"
@@ -25,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

@@ -2,12 +2,28 @@ 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;
+    @api language?: string;
 
     @api
     public get treeNode() {
@@ -20,7 +36,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 +46,22 @@ export default class TreeItem extends LightningElement {
     }
 
     private get isSelected(): boolean {
+        if (isParentOnlyTopic(this._treeNode)) {
+            return false;
+        }
         return this._treeNode.key === this.selectedKey && !this.isExternalLink;
     }
 
+    private get rowClass(): string {
+        return this.isSelected && this.showVersionPicker
+            ? "tree-item-row tree-item-row-selected"
+            : "tree-item-row";
+    }
+
+    private get isContainedSelection(): boolean {
+        return this.isSelected && this.showVersionPicker;
+    }
+
     private get hasChildren(): boolean {
         return !!(
             this.treeNode &&
@@ -83,8 +112,48 @@ 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, this.language);
+    }
+
+    private get topicVersionKey(): string {
+        return getTopicVersionKey(this._treeNode, this.language);
+    }
+
+    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 +173,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 = this.selectedVersion;
+        const topicKey = this.topicVersionKey;
+        if (this.versions?.length && selected && topicKey) {
+            persistTopicVersion(topicKey, selected.id);
+        }
+    }
+
+    private onVersionChange(event: CustomEvent): void {
+        event.stopPropagation();
+        persistTopicVersion(this.topicVersionKey, event.detail);
+    }
+
+    private onVersionPickerClick(event: Event): void {
+        event.stopPropagation();
     }
 
     renderedCallback(): void {
@@ -132,10 +218,14 @@ 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 ||
-            this._treeNode.link?.href === window.location.pathname
+            (!this._treeNode.link?.href &&
+                !isParentOnlyTopic(this._treeNode)) ||
+            !this.href ||
+            normalizePath(this.href) === normalizePath(window.location.pathname)
         ) {
             event.preventDefault();
         }
@@ -155,10 +245,14 @@ export default class TreeItem extends LightningElement {
                 this.sendGtm(event);
                 return;
             }
-            const isSelectAction = false;
-            this.doExpand(isSelectAction);
-            this.sendGtm(event);
-            return;
+            // No copied destination. A markdown descendant is selected below.
+            // A chain with no content page only expands.
+            if (!firstContentNode(this._treeNode)?.link?.href) {
+                const isSelectAction = false;
+                this.doExpand(isSelectAction);
+                this.sendGtm(event);
+                return;
+            }
         }
 
         if (this.isParent) {
@@ -167,8 +261,12 @@ export default class TreeItem extends LightningElement {
         }
 
         this.sendGtm(event);
+        const contentNode = isParentOnlyTopic(this._treeNode)
+            ? firstContentNode(this._treeNode)
+            : undefined;
         this.fireEvent("tileselected", {
-            name: this._treeNode.name,
+            name: contentNode?.name || this._treeNode.name,
+            ...(contentNode?.key ? { key: contentNode.key } : {}),
             isExternalLink: this.isExternalLink
         });
     }
@@ -186,8 +284,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;
 }
@@ -213,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);
+}