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

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",

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 {
@@ -170,9 +170,9 @@
     margin-bottom: var(--dx-g-spacing-2xl);
 }
 
-@media screen and (max-width: 767px) {
+@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/dxHelpers/commonTreeItem/commonTreeItem.css

@@ -13,6 +13,10 @@
     color: var(--dx-g-blue-vibrant-40) !important;
 }
 
+.sidebar-item-selected-text {
+    color: var(--dx-g-blue-vibrant-40) !important;
+}
+
 .sidebar-item {
     padding: 6px var(--dx-g-spacing-lg) 6px
         var(--dx-g-global-header-padding-horizontal);

package/src/modules/dxHelpers/typeBadge/typeBadge.css

@@ -26,6 +26,28 @@
     --height: var(--dx-g-spacing-mlg);
 }
 
+.dx-badge.status-success,
+.dx-badge.status-warning,
+.dx-badge.status-error {
+    /* No spacing token maps to 10px; status badges need this exact padding. */
+    --horizontal-spacing: 10px;
+}
+
+.dx-badge.status-success {
+    --color: var(--sds-g-gray-1);
+    --background: var(--dx-g-green-vibrant-50);
+}
+
+.dx-badge.status-warning {
+    --color: var(--dx-g-gray-15);
+    --background: var(--dx-g-yellow-vibrant-80);
+}
+
+.dx-badge.status-error {
+    --color: var(--sds-g-gray-1);
+    --background: var(--dx-g-red-vibrant-40);
+}
+
 svg,
 dx-icon {
     margin-right: var(--dx-g-spacing-sm);