@salesforcedevs/docs-components 1.34.0-tlv-alpha → 1.34.1-ai-toolbar-action

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforcedevs/docs-components",
-  "version": "1.34.0-tlv-alpha",
+  "version": "1.34.1-ai-toolbar-action",
   "description": "Docs Lightning web components for DSC",
   "license": "MIT",
   "main": "index.js",
@@ -25,5 +25,6 @@
     "@types/lodash.orderby": "4.6.9",
     "@types/lodash.uniqby": "4.7.9"
   },
-  "gitHead": "4629fdd9ca18a13480044ad43515b91945d16aad"
+  "gitHead": "4629fdd9ca18a13480044ad43515b91945d16aad",
+  "stableVersion": "1.34.1"
 }

package/src/modules/doc/contentActionToolbar/contentActionToolbar.css

@@ -24,9 +24,63 @@
     background-color: var(--dx-g-gray-70);
 }
 
-@media screen and (max-width: 480px) {
-    .toolbar-button_copy-url,
-    .divider_copy-url {
-        display: none;
+.toolbar-button_view-markdown,
+.divider_view-markdown,
+.toolbar-button_view-llms,
+.divider_view-llms {
+    display: none;
+}
+
+.toolbar_no-markdown .toolbar-button_view-llms {
+    display: inline-flex;
+}
+
+.toolbar:not(.toolbar_no-markdown) .divider_menu {
+    display: none;
+}
+
+.menu-trigger-wrap {
+    position: relative;
+    display: inline-flex;
+}
+
+.menu-trigger {
+    --dx-c-button-custom-color: var(--dx-g-gray-50);
+    --dx-c-button-custom-color-hover: var(--dx-g-gray-10);
+}
+
+.menu-trigger-copied {
+    position: absolute;
+    bottom: 100%;
+    right: calc(-1 * var(--dx-g-spacing-xs));
+    margin-bottom: var(--dx-g-spacing-xs);
+    padding: var(--dx-g-spacing-2xs) var(--dx-g-spacing-sm);
+    background: var(--dx-g-gray-50);
+    color: white;
+    font-family: var(--dx-g-font-sans);
+    font-size: var(--dx-g-text-xs);
+    white-space: nowrap;
+    border-radius: 4px;
+    pointer-events: none;
+}
+
+@media screen and (min-width: 480px) {
+    .toolbar-button_view-markdown,
+    .divider_view-markdown {
+        display: inline-flex;
+    }
+
+    .toolbar:not(.toolbar_no-markdown) .divider_menu {
+        display: block;
+    }
+}
+
+@media screen and (min-width: 768px) {
+    .toolbar-button_view-llms {
+        display: inline-flex;
+    }
+
+    .toolbar:not(.toolbar_no-markdown) .divider_view-llms {
+        display: inline-flex;
     }
 }

package/src/modules/doc/contentActionToolbar/contentActionToolbar.html

@@ -1,53 +1,85 @@
 <template>
-    <div class="toolbar" lwc:if={markdownUrl}>
-        <dx-tooltip placement="top-right" label={copyMarkdownLabel}>
+    <div class={toolbarClass}>
+        <template lwc:if={hasMarkdown}>
+            <dx-tooltip placement="top-right" label={copyMarkdownTooltipLabel}>
+                <dx-button
+                    class="toolbar-button"
+                    variant="inline"
+                    size="small"
+                    icon-sprite="utility"
+                    icon-symbol="copy"
+                    icon-size="medium"
+                    icon-position="right"
+                    aria-label={copyMarkdownButtonText}
+                    onclick={handleCopyMarkdown}
+                >
+                    {copyMarkdownButtonText}
+                </dx-button>
+            </dx-tooltip>
+
+            <div class="divider divider_view-markdown"></div>
+
             <dx-button
-                class="toolbar-button"
+                class="toolbar-button toolbar-button_view-markdown"
                 variant="inline"
                 size="small"
                 icon-sprite="utility"
-                icon-symbol="copy"
+                icon-symbol="new_window"
                 icon-size="medium"
                 icon-position="right"
-                aria-label={copyMarkdownButtonText}
-                onclick={handleCopyMarkdown}
+                aria-label={viewMarkdownButtonText}
+                onclick={handleViewMarkdown}
             >
-                {copyMarkdownButtonText}
+                {viewMarkdownButtonText}
             </dx-button>
-        </dx-tooltip>
+        </template>
 
-        <div class="divider"></div>
+        <div class="divider divider_view-llms"></div>
 
         <dx-button
-            class="toolbar-button"
+            class="toolbar-button toolbar-button_view-llms"
             variant="inline"
             size="small"
             icon-sprite="utility"
             icon-symbol="new_window"
             icon-size="medium"
             icon-position="right"
-            aria-label={viewMarkdownButtonText}
-            onclick={handleViewMarkdown}
+            aria-label={viewLlmsButtonText}
+            onclick={handleViewLlms}
         >
-            {viewMarkdownButtonText}
+            {viewLlmsButtonText}
         </dx-button>
 
-        <div class="divider divider_copy-url"></div>
+        <div class="divider divider_menu"></div>
 
-        <dx-tooltip placement="top-right" label={copyUrlLabel}>
-            <dx-button
-                class="toolbar-button toolbar-button_copy-url"
-                variant="inline"
-                size="small"
-                icon-sprite="utility"
-                icon-symbol="link"
-                icon-size="medium"
-                icon-position="right"
-                aria-label={copyUrlButtonText}
-                onclick={handleCopyUrl}
+        <span class="menu-trigger-wrap">
+            <dx-tooltip placement="top-right" label={moreActionsLabel}>
+                <dx-dropdown
+                    class="toolbar-menu"
+                    options={menuOptions}
+                    placement="bottom-end"
+                    width-mode="fit-content"
+                    aria-label={moreActionsLabel}
+                    onchange={handleMenuSelect}
+                >
+                    <dx-button
+                        class="menu-trigger"
+                        variant="icon-only"
+                        size="small"
+                        icon-sprite="utility"
+                        icon-symbol="threedots"
+                        icon-size="medium"
+                        aria-label={moreActionsLabel}
+                    ></dx-button>
+                </dx-dropdown>
+            </dx-tooltip>
+            <span
+                class="menu-trigger-copied"
+                if:true={showCopiedFlash}
+                role="status"
             >
-                {copyUrlButtonText}
-            </dx-button>
-        </dx-tooltip>
+                {copiedLabel}
+            </span>
+        </span>
     </div>
 </template>

package/src/modules/doc/contentActionToolbar/contentActionToolbar.ts

@@ -1,14 +1,39 @@
 import { LightningElement, api } from "lwc";
+import cx from "classnames";
+import { OptionWithNested } from "typings/custom";
 import { track } from "dxUtils/analytics";
 
-const DEFAULT_COPY_TOOLTIP_LABEL = "Click to copy";
+const DEFAULT_TOOLTIP_LABEL = "Click to copy";
 const COPIED_TOOLTIP_LABEL = "Copied!";
-const COPIED_TOOLTIP_RESET_MS = 1000;
+const COPIED_RESET_MS = 1000;
 
 const ANALYTICS_CONTENT_CATEGORY = "content action toolbar";
+const MORE_ACTIONS_LABEL = "More actions";
+
 const COPY_MARKDOWN_LABEL = "Copy as Markdown";
 const VIEW_MARKDOWN_LABEL = "View as Markdown";
-const COPY_URL_LABEL = "Copy URL to Markdown";
+const COPY_MARKDOWN_URL_LABEL = "Copy URL to Markdown";
+const VIEW_LLMS_LABEL = "View llms.txt";
+const COPY_LLMS_URL_LABEL = "Copy URL to llms.txt";
+const OPEN_CHATGPT_LABEL = "Open in ChatGPT";
+const OPEN_CLAUDE_LABEL = "Open in Claude";
+const OPEN_PERPLEXITY_LABEL = "Open in Perplexity";
+
+const LLMS_TXT_PATH = "/docs/llms.txt";
+const CHATGPT_URL = "https://chatgpt.com/";
+const CLAUDE_URL = "https://claude.ai/new";
+const PERPLEXITY_URL = "https://www.perplexity.ai/search";
+
+const LLMS_TXT_CONTEXT_URL = "https://developer.salesforce.com/docs/llms.txt";
+
+const ACTION_COPY_MARKDOWN = "copy-markdown";
+const ACTION_VIEW_MARKDOWN = "view-markdown";
+const ACTION_COPY_MARKDOWN_URL = "copy-markdown-url";
+const ACTION_VIEW_LLMS = "view-llms";
+const ACTION_COPY_LLMS_URL = "copy-llms-url";
+const ACTION_OPEN_CHATGPT = "open-chatgpt";
+const ACTION_OPEN_CLAUDE = "open-claude";
+const ACTION_OPEN_PERPLEXITY = "open-perplexity";
 
 export default class ContentActionToolbar extends LightningElement {
     @api
@@ -23,17 +48,15 @@ export default class ContentActionToolbar extends LightningElement {
     }
     private _pageUrl?: string;
 
-    copyMarkdownLabel: string = DEFAULT_COPY_TOOLTIP_LABEL;
-    copyUrlLabel: string = DEFAULT_COPY_TOOLTIP_LABEL;
+    @api pageTitle?: string;
 
-    private copyTooltipResetTimeout: number | null = null;
+    copyMarkdownTooltipLabel: string = DEFAULT_TOOLTIP_LABEL;
+    copiedLabel: string | null = null;
 
-    /**
-     * Returns the `.md` equivalent of `pageUrl` with any hash and query
-     * string stripped, or `null` when `pageUrl` is not set or does not end
-     * with `.html`.
-     */
-    get markdownUrl(): string | null {
+    private copyMarkdownResetTimeout: number | null = null;
+    private menuCopiedResetTimeout: number | null = null;
+
+    private get absolutePageUrl(): string | null {
         if (!this.pageUrl) {
             return null;
         }
@@ -41,7 +64,15 @@ export default class ContentActionToolbar extends LightningElement {
         const url = new URL(this.pageUrl, window.location.href);
         url.hash = "";
         url.search = "";
+        return url.toString();
+    }
+
+    get markdownUrl(): string | null {
+        if (!this.absolutePageUrl) {
+            return null;
+        }
 
+        const url = new URL(this.absolutePageUrl);
         if (!url.pathname.endsWith(".html")) {
             return null;
         }
@@ -50,6 +81,57 @@ export default class ContentActionToolbar extends LightningElement {
         return url.toString();
     }
 
+    get llmsUrl(): string {
+        return new URL(LLMS_TXT_PATH, window.location.href).toString();
+    }
+
+    get chatGptUrl(): string | null {
+        return this.buildAiAssistantUrl(CHATGPT_URL);
+    }
+
+    get claudeUrl(): string | null {
+        return this.buildAiAssistantUrl(CLAUDE_URL);
+    }
+
+    get perplexityUrl(): string | null {
+        return this.buildAiAssistantUrl(PERPLEXITY_URL);
+    }
+
+    private buildAiAssistantUrl(base: string): string | null {
+        if (!this.absolutePageUrl) {
+            return null;
+        }
+
+        const title = this.pageTitle?.trim();
+        const intro = title
+            ? `I'm reading "${title}" at ${this.absolutePageUrl}.`
+            : `I'm reading ${this.absolutePageUrl}.`;
+
+        const url = new URL(base);
+        url.searchParams.set(
+            "q",
+            `${intro} Read this page so I can ask questions about it. ` +
+                `For broader context, see ${LLMS_TXT_CONTEXT_URL}`
+        );
+        return url.toString();
+    }
+
+    get hasMarkdown(): boolean {
+        return Boolean(this.markdownUrl);
+    }
+
+    get toolbarClass(): string {
+        return cx("toolbar", !this.hasMarkdown && "toolbar_no-markdown");
+    }
+
+    get moreActionsLabel(): string {
+        return MORE_ACTIONS_LABEL;
+    }
+
+    get showCopiedFlash(): boolean {
+        return this.copiedLabel !== null;
+    }
+
     get copyMarkdownButtonText(): string {
         return COPY_MARKDOWN_LABEL;
     }
@@ -58,98 +140,241 @@ export default class ContentActionToolbar extends LightningElement {
         return VIEW_MARKDOWN_LABEL;
     }
 
-    get copyUrlButtonText(): string {
-        return COPY_URL_LABEL;
+    get viewLlmsButtonText(): string {
+        return VIEW_LLMS_LABEL;
+    }
+
+    get menuOptions(): OptionWithNested[] {
+        const groups: OptionWithNested[] = [];
+
+        if (this.hasMarkdown) {
+            groups.push({
+                id: "this-page",
+                label: "This Page",
+                options: [
+                    {
+                        id: ACTION_COPY_MARKDOWN,
+                        label: COPY_MARKDOWN_LABEL,
+                        iconSprite: "utility",
+                        iconSymbol: "copy"
+                    },
+                    {
+                        id: ACTION_VIEW_MARKDOWN,
+                        label: VIEW_MARKDOWN_LABEL,
+                        iconSprite: "utility",
+                        iconSymbol: "new_window"
+                    },
+                    {
+                        id: ACTION_COPY_MARKDOWN_URL,
+                        label: COPY_MARKDOWN_URL_LABEL,
+                        iconSprite: "utility",
+                        iconSymbol: "link"
+                    },
+                    {
+                        id: ACTION_OPEN_CHATGPT,
+                        label: OPEN_CHATGPT_LABEL,
+                        iconSprite: "utility",
+                        iconSymbol: "new_window"
+                    },
+                    {
+                        id: ACTION_OPEN_CLAUDE,
+                        label: OPEN_CLAUDE_LABEL,
+                        iconSprite: "utility",
+                        iconSymbol: "new_window"
+                    },
+                    {
+                        id: ACTION_OPEN_PERPLEXITY,
+                        label: OPEN_PERPLEXITY_LABEL,
+                        iconSprite: "utility",
+                        iconSymbol: "new_window"
+                    }
+                ]
+            });
+        }
+
+        groups.push({
+            id: "all-documentation",
+            label: "All Documentation",
+            options: [
+                {
+                    id: ACTION_VIEW_LLMS,
+                    label: VIEW_LLMS_LABEL,
+                    iconSprite: "utility",
+                    iconSymbol: "new_window"
+                },
+                {
+                    id: ACTION_COPY_LLMS_URL,
+                    label: COPY_LLMS_URL_LABEL,
+                    iconSprite: "utility",
+                    iconSymbol: "link"
+                }
+            ]
+        });
+
+        return groups;
     }
 
     async handleCopyMarkdown(event: Event) {
+        if (await this.copyMarkdown(event)) {
+            this.flashCopyMarkdownTooltip();
+        }
+    }
+
+    handleViewMarkdown(event: Event) {
         if (!this.markdownUrl) {
             return;
         }
 
-        this.trackToolbarEvent(
-            event,
-            "custEv_linkClick",
-            COPY_MARKDOWN_LABEL,
-            this.markdownUrl
-        );
+        this.trackToolbarEvent(event, VIEW_MARKDOWN_LABEL, this.markdownUrl);
+        window.open(this.markdownUrl, "_blank", "noopener,noreferrer");
+    }
+
+    handleViewLlms(event: Event) {
+        this.trackToolbarEvent(event, VIEW_LLMS_LABEL, this.llmsUrl);
+        window.open(this.llmsUrl, "_blank", "noopener,noreferrer");
+    }
+
+    private handleOpenAiAssistant(
+        event: Event,
+        label: string,
+        url: string | null
+    ) {
+        if (!url) {
+            return;
+        }
+
+        this.trackToolbarEvent(event, label, url);
+        window.open(url, "_blank", "noopener,noreferrer");
+    }
+
+    async handleMenuSelect(event: CustomEvent) {
+        switch (event.detail) {
+            case ACTION_COPY_MARKDOWN:
+                if (await this.copyMarkdown(event)) {
+                    this.flashMenuCopied();
+                }
+                return;
+            case ACTION_VIEW_MARKDOWN:
+                this.handleViewMarkdown(event);
+                return;
+            case ACTION_COPY_MARKDOWN_URL:
+                await this.handleCopyMarkdownUrl(event);
+                return;
+            case ACTION_VIEW_LLMS:
+                this.handleViewLlms(event);
+                return;
+            case ACTION_COPY_LLMS_URL:
+                await this.handleCopyLlmsUrl(event);
+                return;
+            case ACTION_OPEN_CHATGPT:
+                this.handleOpenAiAssistant(
+                    event,
+                    OPEN_CHATGPT_LABEL,
+                    this.chatGptUrl
+                );
+                return;
+            case ACTION_OPEN_CLAUDE:
+                this.handleOpenAiAssistant(
+                    event,
+                    OPEN_CLAUDE_LABEL,
+                    this.claudeUrl
+                );
+                return;
+            case ACTION_OPEN_PERPLEXITY:
+                this.handleOpenAiAssistant(
+                    event,
+                    OPEN_PERPLEXITY_LABEL,
+                    this.perplexityUrl
+                );
+                break;
+            default:
+        }
+    }
+
+    private async copyMarkdown(event: Event): Promise<boolean> {
+        if (!this.markdownUrl) {
+            return false;
+        }
+
+        this.trackToolbarEvent(event, COPY_MARKDOWN_LABEL, this.markdownUrl);
 
         try {
             const response = await fetch(this.markdownUrl);
             if (!response.ok) {
-                return;
+                return false;
             }
             const markdown = await response.text();
             await navigator.clipboard.writeText(markdown);
-            this.flashCopied("copyMarkdownLabel");
+            return true;
         } catch (error) {
             console.error(error);
+            return false;
         }
     }
 
-    handleViewMarkdown(event: Event) {
+    private async handleCopyMarkdownUrl(event: Event) {
         if (!this.markdownUrl) {
             return;
         }
 
         this.trackToolbarEvent(
             event,
-            "custEv_linkClick",
-            VIEW_MARKDOWN_LABEL,
+            COPY_MARKDOWN_URL_LABEL,
             this.markdownUrl
         );
 
-        window.open(this.markdownUrl, "_blank", "noopener,noreferrer");
-    }
-
-    async handleCopyUrl(event: Event) {
-        if (!this.markdownUrl) {
-            return;
+        try {
+            await navigator.clipboard.writeText(this.markdownUrl);
+            this.flashMenuCopied();
+        } catch (error) {
+            console.error(error);
         }
+    }
 
-        this.trackToolbarEvent(
-            event,
-            "custEv_linkClick",
-            COPY_URL_LABEL,
-            this.markdownUrl
-        );
+    private async handleCopyLlmsUrl(event: Event) {
+        this.trackToolbarEvent(event, COPY_LLMS_URL_LABEL, this.llmsUrl);
 
         try {
-            await navigator.clipboard.writeText(this.markdownUrl);
-            this.flashCopied("copyUrlLabel");
+            await navigator.clipboard.writeText(this.llmsUrl);
+            this.flashMenuCopied();
         } catch (error) {
             console.error(error);
         }
     }
 
-    private trackToolbarEvent(
-        event: Event,
-        eventName: "custEv_linkClick",
-        label: string,
-        url: string
-    ): void {
-        track(event.currentTarget!, eventName, {
+    private trackToolbarEvent(event: Event, label: string, url: string): void {
+        track(event.currentTarget!, "custEv_linkClick", {
             click_text: label,
             click_url: url,
             element_type: "button_link",
             element_title: label,
             content_category: ANALYTICS_CONTENT_CATEGORY,
             // Source page the CTA was clicked from; `click_url` above is the
-            // `.md` destination. Uses the same `page_path` expression as the
+            // destination. Uses the same `page_path` expression as the
             // amfReference doc_page_view events.
             page_path: window.location.pathname + window.location.search
         });
     }
 
-    private flashCopied(labelKey: "copyMarkdownLabel" | "copyUrlLabel") {
-        if (this.copyTooltipResetTimeout !== null) {
-            window.clearTimeout(this.copyTooltipResetTimeout);
+    private flashCopyMarkdownTooltip() {
+        if (this.copyMarkdownResetTimeout !== null) {
+            window.clearTimeout(this.copyMarkdownResetTimeout);
+        }
+        this.copyMarkdownTooltipLabel = COPIED_TOOLTIP_LABEL;
+        this.copyMarkdownResetTimeout = window.setTimeout(() => {
+            this.copyMarkdownTooltipLabel = DEFAULT_TOOLTIP_LABEL;
+            this.copyMarkdownResetTimeout = null;
+        }, COPIED_RESET_MS);
+    }
+
+    private flashMenuCopied() {
+        if (this.menuCopiedResetTimeout !== null) {
+            window.clearTimeout(this.menuCopiedResetTimeout);
         }
-        this[labelKey] = COPIED_TOOLTIP_LABEL;
-        this.copyTooltipResetTimeout = window.setTimeout(() => {
-            this.copyMarkdownLabel = DEFAULT_COPY_TOOLTIP_LABEL;
-            this.copyUrlLabel = DEFAULT_COPY_TOOLTIP_LABEL;
-            this.copyTooltipResetTimeout = null;
-        }, COPIED_TOOLTIP_RESET_MS);
+        this.copiedLabel = COPIED_TOOLTIP_LABEL;
+        this.menuCopiedResetTimeout = window.setTimeout(() => {
+            this.copiedLabel = null;
+            this.menuCopiedResetTimeout = null;
+        }, COPIED_RESET_MS);
     }
 }

package/src/modules/doc/contentActionToolbar/contentActionToolbarMocks.ts

@@ -40,7 +40,7 @@ export function interceptWindowOpenForContentActionToolbar() {
     const originalOpen = window.open.bind(window);
     window.open = ((url?: string | URL, target?: string, features?: string) => {
         const stringUrl = url?.toString() ?? "";
-        if (stringUrl.endsWith(".md")) {
+        if (stringUrl.endsWith(".md") || stringUrl.endsWith("/llms.txt")) {
             return originalOpen(DUMMY_MARKDOWN_DATA_URL, target, features);
         }
         return originalOpen(url ?? "", target, features);

package/src/modules/doc/contentLayout/contentLayout.ts

@@ -307,9 +307,10 @@ export default class ContentLayout extends LightningElement {
         const toolbar = (this.contentActionToolbarElement ??
             createElement(CONTENT_ACTION_TOOLBAR_TAG, {
                 is: ContentActionToolbar
-            })) as HTMLElement & { pageUrl?: string };
+            })) as HTMLElement & { pageUrl?: string; pageTitle?: string };
 
         toolbar.pageUrl = this.sidebarValue;
+        toolbar.pageTitle = heading.textContent?.trim() || undefined;
 
         if (toolbar.previousElementSibling !== heading) {
             heading.parentNode?.insertBefore(toolbar, heading.nextSibling);

package/src/modules/doc/header/header.ts

@@ -74,6 +74,13 @@ export default class Header extends HeaderBase {
         return (this.hideDocHeader && !this.mobile) || this.showDocDivider;
     }
 
+    private get isDocsPath(): boolean {
+        return (
+            window.location.pathname.includes("/docs/") &&
+            window.location.pathname !== "/docs/apis"
+        );
+    }
+
     connectedCallback(): void {
         super.connectedCallback();
         this.tabletMatchMedia = window.matchMedia(
@@ -83,9 +90,7 @@ export default class Header extends HeaderBase {
         this.tabletMatchMedia.addEventListener("change", this.onTabletChange);
 
         if (
-            (!this.shouldHideHeader &&
-                window.location.pathname.includes("/docs/") &&
-                window.location.pathname !== "/docs/apis") ||
+            (!this.shouldHideHeader && this.isDocsPath) ||
             window.location.pathname ===
                 "/tableau/embedding-playground/overview" ||
             isStorybook()
@@ -109,6 +114,12 @@ export default class Header extends HeaderBase {
         );
     }
 
+    renderedCallback(): void {
+        if (this.hideDocHeader) {
+            this.shouldRender = !this.shouldHideHeader && this.isDocsPath;
+        }
+    }
+
     private onTabletChange = (e: MediaQueryListEvent | MediaQueryList) =>
         (this.tablet = e.matches);
 

package/src/modules/doc/unifiedContentLayout/unifiedContentLayout.ts

@@ -10,11 +10,38 @@ import type { OptionWithLink, TreeNode } from "typings/custom";
  */
 const TOPIC_TYPE_SPEC = "spec";
 
+/**
+ * Walks down the first-child chain and returns the first markdown content
+ * page found, descending through nested content-less parents. Returns
+ * undefined if the chain breaks on a spec or external link before reaching a
+ * content page.
+ */
+function firstChildContentPage(node: TreeNode): TreeNode | undefined {
+    const firstChild = node.children?.[0];
+    if (!firstChild) {
+        return undefined;
+    }
+
+    const isSpec =
+        (firstChild as { topicType?: string }).topicType === TOPIC_TYPE_SPEC;
+    const isExternal = firstChild.link?.target === "_blank";
+    if (isSpec || isExternal) {
+        return undefined;
+    }
+
+    if (firstChild.link?.href) {
+        return firstChild;
+    }
+
+    return firstChildContentPage(firstChild);
+}
+
 /**
  * Translates per-topic `topicType` into the generic `showForwardArrow` flag
- * that `dx-tree-tile` reads (spec topics get the forward arrow icon for Redoc).
+ * that `dx-tree-tile` reads (spec topics get the forward arrow icon for Redoc),
+ * and redirects content-less parent topics whose first child is a content page
  */
-function decorateTopicsWithForwardArrow(
+function decorateTopics(
     topics: Array<TreeNode & { topicType?: string }> | undefined
 ): TreeNode[] | undefined {
     return topics?.map((topic) => {
@@ -23,10 +50,23 @@ function decorateTopicsWithForwardArrow(
             decorated.showForwardArrow = true;
         }
         if (decorated.children) {
-            decorated.children = decorateTopicsWithForwardArrow(
-                decorated.children
-            );
+            decorated.children = decorateTopics(decorated.children);
         }
+
+        /** Redirect a parent that has no content of its own to its first child
+         * but only when that first child is itself a content page
+         */
+        const isContentlessParent =
+            !!decorated.children?.length && !decorated.link?.href;
+
+        if (isContentlessParent) {
+            decorated.redirectToChild = true;
+            const firstChild = firstChildContentPage(topic);
+            if (firstChild?.link) {
+                decorated.link = { ...firstChild.link };
+            }
+        }
+
         return decorated;
     });
 }
@@ -77,9 +117,7 @@ export default class UnifiedContentLayout extends LightningElement {
     }
 
     set sidebarContent(value: string) {
-        this._sidebarContent = decorateTopicsWithForwardArrow(
-            toJson(value)?.topics
-        );
+        this._sidebarContent = decorateTopics(toJson(value)?.topics);
     }
 
     private get enableFooter(): boolean {

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

@@ -62,115 +62,3 @@ dx-type-badge.not-latest-badge {
 
     margin-left: var(--dx-g-spacing-sm);
 }
-
-/* ------------------------------------------------------------------ *
- * Small "dot" variant (opt-in via `small`). Additive 
- * ------------------------------------------------------------------ */
-
-/* Scoped hooks so the shared dx-popover/dx-dropdown-option keep their defaults. */
-.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-lg);
-    --dx-c-dropdown-option-border-radius: 0;
-    --dx-c-popover-border: none;
-    --dx-c-popover-padding: var(--dx-g-spacing-sm) 0;
-}
-
-.version-picker-button-small {
-    display: flex;
-    width: fit-content;
-    max-width: 104px;
-    border-radius: var(--dx-g-spacing-xs);
-
-    --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: 18px;
-    --dx-g-button-icon-color: var(--dx-g-gray-50);
-    --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;
-}
-
-.version-picker-button-small::part(container),
-.version-picker-readonly-small {
-    box-sizing: border-box;
-    height: var(--dx-g-spacing-lg);
-    padding: 0 var(--dx-g-spacing-xs);
-    border-radius: var(--dx-g-spacing-xs);
-}
-
-/* Border is an inset box-shadow, not a real border, so thickening it on
-   hover/focus doesn't widen the fit-content box (no horizontal shift). */
-.version-picker-button-small::part(container) {
-    /* width:100% re-ties to the 104px-capped host (container is width:inherit,
-       which copies width but not max-width). */
-    width: 100%;
-    background: white;
-    box-shadow: inset 0 0 0 1px var(--dx-g-gray-50);
-    color: var(--dx-g-gray-10);
-}
-
-.version-picker-button-small::part(container):hover {
-    background: var(--dx-g-blue-vibrant-95);
-    box-shadow: inset 0 0 0 2px var(--dx-g-blue-vibrant-20);
-}
-
-.version-picker-button-small:hover,
-.version-picker-button-small:focus-within,
-.version-picker-button-small[aria-expanded="true"] {
-    --dx-g-button-icon-color: var(--dx-g-blue-vibrant-20);
-}
-
-/* Also matches aria-expanded so the ring stays while the menu is open (opening
-   moves focus into the menu, which would otherwise drop :focus-within). */
-.version-picker-button-small:focus-within::part(container),
-.version-picker-button-small[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-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);
-}
-
-.version-picker-readonly-small {
-    display: inline-block;
-    width: fit-content;
-    max-width: 104px;
-    margin: 0;
-    border: 1px solid var(--dx-g-gray-80);
-    overflow: hidden;
-    color: var(--dx-g-gray-10);
-    text-overflow: ellipsis;
-    white-space: nowrap;
-    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,58 +1,37 @@
 <template>
     <div lwc:if={showVersionPicker} class="version-picker-container">
-        <!-- Small read-only: plain value, no dropdown -->
-        <p lwc:if={readOnly} class={readOnlyClass}>
-            {selectedVersion.label}
-        </p>
-
         <dx-dropdown
-            lwc:else
-            class={dropdownClass}
             options={versions}
             analytics-event="custEv_docVersionSelect"
             analytics-payload={analyticsPayload}
             value={selectedVersion.id}
-            width={dropdownWidth}
+            width="var(--doc-version-picker-width)"
             onchange={onVersionChange}
         >
             <dx-button
-                class={triggerClass}
+                class="version-picker-button"
                 variant="tertiary"
                 size="small"
-                font={triggerFont}
                 icon-symbol="chevrondown"
-                icon-size={triggerIconSize}
-                aria-label={triggerAriaLabel}
+                icon-size="medium"
             >
-                <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">
-                            {selectedVersion.label}
-                        </p>
-                    </template>
-                    <!-- Default: trailing Latest/Not-Latest badge -->
-                    <template lwc:else>
-                        <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>
-                        </template>
+                <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>
                     </template>
                 </div>
             </dx-button>

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

@@ -1,5 +1,4 @@
 import { LightningElement, api, track } from "lwc";
-import cx from "classnames";
 
 import { AnalyticsPayload, OptionWithNested } from "typings/custom";
 
@@ -13,8 +12,6 @@ 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() {
@@ -54,27 +51,6 @@ 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;
     }
@@ -83,73 +59,6 @@ export default class VersionPicker extends LightningElement {
         return !this.hideBadge;
     }
 
-    // Read-only currently only has a small-variant style.
-    private get readOnlyClass(): string {
-        return "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; the default
-    // returns undefined so those attributes are omitted (keeps default output
-    // unchanged for xmlContent/amfReference).
-
-    // 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 dropdownWidth(): string | undefined {
-        return this.small ? undefined : "var(--doc-version-picker-width)";
-    }
-
-    private get triggerClass(): string {
-        return cx(
-            "version-picker-button",
-            this.small && "version-picker-button-small"
-        );
-    }
-
-    private get triggerFont(): string {
-        return this.small ? "sans" : "display";
-    }
-
-    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 }));
     }