@salesforcedevs/dx-components 1.40.6 → 1.40.7-tlv-alpha

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,52 @@ 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)
+                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,36 @@
 
 :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;
+}
+
+.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;
 }

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

@@ -28,10 +28,12 @@ export default class TreeTile extends LightningElement {
     @api isExpanded = false;
     @api hasChildren = false;
     @api isSelected = false;
+    @api isContainedSelection = false;
     @api href!: string;
     @api showArrow = false;
     @api target!: string;
     @api isExternalLink = false;
+    @api hasVersionPicker = false;
 
     get tileAriaLevel() {
         return this.treeNode.level + 2;
@@ -43,18 +45,21 @@ export default class TreeTile extends LightningElement {
      * screen reader users (WCAG 2.4.4)
      */
     get linkAriaLabel(): string | null {
-        if (!this.treeNode.redirectToChild || !this.treeNode.link?.href) {
+        if (!this.treeNode.redirectToChild) {
             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.
+         * The destination href may live on this anchor (parent-only topics do
+         * not copy it onto the parent node).
          */
         let destination = this.treeNode.children?.[0];
         while (destination?.redirectToChild) {
             destination = destination.children?.[0];
         }
-        return destination?.link?.href === this.treeNode.link.href
+        const triggerHref = this.href || this.treeNode.link?.href;
+        return destination?.link?.href && destination.link.href === triggerHref
             ? `${this.treeNode.label}, opens ${destination.label}`
             : null;
     }
@@ -101,7 +106,11 @@ export default class TreeTile extends LightningElement {
             "tile-root": this.isRoot,
             "tile-with-children": !this.isRoot && this.hasChildren,
             "tile-root-with-child": this.isRoot && this.showArrow,
-            "sidebar-item-selected": this.isSelected
+            "sidebar-item-selected":
+                this.isSelected && !this.isContainedSelection,
+            "sidebar-item-selected-text":
+                this.isSelected && this.isContainedSelection,
+            "tile-with-version-picker": this.hasVersionPicker
         });
     }
 

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

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