@salesforcedevs/docs-components 1.34.0 → 1.34.1-proj-ver-picker-1

package/package.json

@@ -1,29 +1,30 @@
 {
-    "name": "@salesforcedevs/docs-components",
-    "version": "1.34.0",
-    "description": "Docs Lightning web components for DSC",
-    "license": "MIT",
-    "main": "index.js",
-    "engines": {
-        "node": "22.x"
-    },
-    "publishConfig": {
-        "access": "public"
-    },
-    "dependencies": {
-        "@api-components/amf-helper-mixin": "4.5.29",
-        "classnames": "2.5.1",
-        "dompurify": "3.2.4",
-        "kagekiri": "1.4.2",
-        "lodash.orderby": "4.6.0",
-        "lodash.uniqby": "4.7.0",
-        "query-string": "7.1.3",
-        "sentence-case": "3.0.4"
-    },
-    "devDependencies": {
-        "@types/classnames": "2.3.1",
-        "@types/lodash.orderby": "4.6.9",
-        "@types/lodash.uniqby": "4.7.9"
-    },
-    "gitHead": "db75cd19dd7a77fe4e09856439c4905c32e64d1f"
-}
+  "name": "@salesforcedevs/docs-components",
+  "version": "1.34.1-proj-ver-picker-1",
+  "description": "Docs Lightning web components for DSC",
+  "license": "MIT",
+  "main": "index.js",
+  "engines": {
+    "node": "22.x"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@api-components/amf-helper-mixin": "4.5.29",
+    "classnames": "2.5.1",
+    "dompurify": "3.2.4",
+    "kagekiri": "1.4.2",
+    "lodash.orderby": "4.6.0",
+    "lodash.uniqby": "4.7.0",
+    "query-string": "7.1.3",
+    "sentence-case": "3.0.4"
+  },
+  "devDependencies": {
+    "@types/classnames": "2.3.1",
+    "@types/lodash.orderby": "4.6.9",
+    "@types/lodash.uniqby": "4.7.9"
+  },
+  "gitHead": "4629fdd9ca18a13480044ad43515b91945d16aad",
+  "stableVersion": "1.34.0"
+}

package/src/modules/doc/versionPicker/versionPicker.css

@@ -4,6 +4,9 @@
 :host {
     --dx-c-dropdown-option-font-weight: normal;
     --dx-c-dropdown-option-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);
 }
 
@@ -17,13 +20,15 @@
 .version-picker-button {
     display: flex;
     width: var(--doc-version-picker-width, 296px);
+
+    --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:active,
-.version-picker-button:focus {
-    --dx-c-button-secondary-color-hover: var(--dx-g-cloud-blue-vibrant-95);
-    --dx-c-button-primary-color: var(--dx-g-blue-vibrant-40);
+.version-picker-button:focus-within,
+.version-picker-button[aria-expanded="true"] {
+    --dx-g-button-icon-color: var(--dx-g-blue-vibrant-20);
 }
 
 /**
@@ -35,6 +40,27 @@ dx-button::part(content) {
     overflow: hidden;
 }
 
+/* The border is an inset box-shadow so thickening it on hover/focus doesn't
+   resize the small variant's fit-content box. */
+.version-picker-button::part(container) {
+    background: white;
+    box-shadow: inset 0 0 0 1px var(--dx-g-gray-50);
+    color: var(--dx-g-gray-10);
+}
+
+.version-picker-button::part(container):hover {
+    background: var(--dx-g-blue-vibrant-95);
+    box-shadow: inset 0 0 0 2px var(--dx-g-blue-vibrant-20);
+}
+
+/* aria-expanded keeps the focus ring while the menu is open. */
+.version-picker-button:focus-within::part(container),
+.version-picker-button[aria-expanded="true"]::part(container) {
+    background: var(--dx-g-blue-vibrant-95);
+    box-shadow: inset 0 0 0 2px var(--dx-g-blue-vibrant-20), 0 0 0 2px white,
+        0 0 0 4px var(--dx-g-blue-vibrant-60);
+}
+
 .selected-version {
     display: flex;
     flex-direction: row;
@@ -49,16 +75,100 @@ dx-button::part(content) {
     white-space: nowrap;
 }
 
-dx-type-badge.latest-badge {
-    --dx-c-type-badge-color: var(--dx-g-green-vibrant-40);
-    --dx-c-type-badge-background: var(--dx-g-green-vibrant-95);
-
+dx-type-badge.latest-badge,
+dx-type-badge.not-latest-badge {
     margin-left: var(--dx-g-spacing-sm);
 }
 
-dx-type-badge.not-latest-badge {
-    --dx-c-type-badge-color: var(--dx-g-red-vibrant-40);
-    --dx-c-type-badge-background: var(--dx-g-red-vibrant-95);
+/* ------------------------------------------------------------------ *
+ * Small "dot" variant (opt-in via `small`). Additive 
+ * ------------------------------------------------------------------ */
 
-    margin-left: var(--dx-g-spacing-sm);
+/* Option padding is sm both axes: the small menu tracks the ~104px trigger, so
+   the default 24px horizontal would crowd the labels. */
+.version-picker-dropdown-small {
+    --dx-c-dropdown-option-font-size: var(--dx-g-text-xs);
+    --dx-c-dropdown-option-padding: var(--dx-g-spacing-sm)
+        var(--dx-g-spacing-sm);
+    --dx-c-dropdown-option-border-radius: 0;
+    --dx-c-popover-border: none;
+}
+
+.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(--doc-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/doc/versionPicker/versionPicker.html

@@ -1,37 +1,70 @@
 <template>
     <div lwc:if={showVersionPicker} class="version-picker-container">
+        <!-- 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="var(--doc-version-picker-width)"
+            full-width="true"
             onchange={onVersionChange}
         >
             <dx-button
-                class="version-picker-button"
+                class={triggerClass}
                 variant="tertiary"
                 size="small"
+                font="sans"
                 icon-symbol="chevrondown"
-                icon-size="medium"
+                icon-size={triggerIconSize}
+                aria-label={triggerAriaLabel}
             >
-                <div class="selected-version">
-                    <p class="selected-version-label">
-                        {selectedVersion.label}
-                    </p>
-                    <template lwc:if={showLatestTag}>
-                        <dx-type-badge
-                            class="latest-badge"
-                            lwc:if={latestVersion}
-                            value="Latest"
-                            size="small"
-                        ></dx-type-badge>
-                        <dx-type-badge
-                            class="not-latest-badge"
-                            lwc:else
-                            value="Not Latest"
-                            size="small"
-                        ></dx-type-badge>
+                <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>

package/src/modules/doc/versionPicker/versionPicker.ts

@@ -1,4 +1,5 @@
 import { LightningElement, api, track } from "lwc";
+import cx from "classnames";
 
 import { AnalyticsPayload, OptionWithNested } from "typings/custom";
 
@@ -12,6 +13,8 @@ export default class VersionPicker extends LightningElement {
     private _selectedVersion?: OptionWithNested;
     private _latestVersion: boolean = false;
     private _hideBadge: boolean = false;
+    private _small: boolean = false;
+    private _readOnly: boolean = false;
 
     @api
     get versions() {
@@ -51,6 +54,27 @@ export default class VersionPicker extends LightningElement {
         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;
     }
@@ -59,6 +83,62 @@ export default class VersionPicker extends LightningElement {
         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;
+    }
+
+    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/LICENSE

@@ -1,12 +0,0 @@
-Copyright (c) 2020, Salesforce.com, Inc.
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-
-* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-
-* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-
-* Neither the name of Salesforce.com nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.