@salesforcedevs/docs-components 1.34.1 → 1.34.4-topic-alpha.1

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

@@ -1,14 +1,26 @@
 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 COPIED_TOOLTIP_LABEL = "Copied!";
-const COPIED_TOOLTIP_RESET_MS = 1000;
-
-const ANALYTICS_CONTENT_CATEGORY = "content action toolbar";
-const COPY_MARKDOWN_LABEL = "Copy as Markdown";
-const VIEW_MARKDOWN_LABEL = "View as Markdown";
-const COPY_URL_LABEL = "Copy URL to Markdown";
+import {
+    DEFAULT_TOOLTIP_LABEL,
+    COPIED_TOOLTIP_LABEL,
+    COPIED_RESET_MS,
+    ANALYTICS_CONTENT_CATEGORY,
+    MORE_ACTIONS_LABEL,
+    COPY_MARKDOWN_LABEL,
+    VIEW_MARKDOWN_LABEL,
+    COPY_MARKDOWN_URL_LABEL,
+    VIEW_LLMS_LABEL,
+    COPY_LLMS_URL_LABEL,
+    LLMS_TXT_PATH,
+    ACTION_COPY_MARKDOWN,
+    ACTION_VIEW_MARKDOWN,
+    ACTION_COPY_MARKDOWN_URL,
+    ACTION_VIEW_LLMS,
+    ACTION_COPY_LLMS_URL,
+    AI_ASSISTANTS
+} from "./constants";
 
 export default class ContentActionToolbar extends LightningElement {
     @api
@@ -23,17 +35,18 @@ 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;
+    copyMarkdownTooltipVisible: boolean = false;
+    menuTooltipLabel: string = MORE_ACTIONS_LABEL;
+    menuTooltipVisible: boolean = false;
+    menuOpen: boolean = false;
 
-    /**
-     * 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 tooltipResetTimeout: number | null = null;
+    private resizeObserver: ResizeObserver | null = null;
+
+    private get absolutePageUrl(): string | null {
         if (!this.pageUrl) {
             return null;
         }
@@ -41,7 +54,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 +71,39 @@ export default class ContentActionToolbar extends LightningElement {
         return url.toString();
     }
 
+    get llmsUrl(): string {
+        return new URL(LLMS_TXT_PATH, window.location.href).toString();
+    }
+
+    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 prompt = `${intro} Read this page so I can ask questions about it. For broader context, see ${this.llmsUrl}`;
+
+        const url = new URL(base);
+        url.searchParams.set("q", prompt);
+        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 copyMarkdownButtonText(): string {
         return COPY_MARKDOWN_LABEL;
     }
@@ -58,98 +112,355 @@ 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"
+                    },
+                    ...AI_ASSISTANTS.map(({ action, label }) => ({
+                        id: action,
+                        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");
+    }
+
+    handleMenuOpen() {
+        this.menuOpen = true;
+    }
+
+    handleMenuClose() {
+        this.menuOpen = false;
+    }
+
+    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;
+            default: {
+                const assistant = AI_ASSISTANTS.find(
+                    ({ action }) => action === event.detail
+                );
+                if (assistant) {
+                    this.handleOpenAiAssistant(
+                        event,
+                        assistant.label,
+                        this.buildAiAssistantUrl(assistant.base)
+                    );
+                }
+            }
+        }
+    }
+
+    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");
+        await this.copyToClipboard(this.markdownUrl);
     }
 
-    async handleCopyUrl(event: Event) {
-        if (!this.markdownUrl) {
-            return;
-        }
+    private async handleCopyLlmsUrl(event: Event) {
+        this.trackToolbarEvent(event, COPY_LLMS_URL_LABEL, this.llmsUrl);
 
-        this.trackToolbarEvent(
-            event,
-            "custEv_linkClick",
-            COPY_URL_LABEL,
-            this.markdownUrl
-        );
+        await this.copyToClipboard(this.llmsUrl);
+    }
 
+    private async copyToClipboard(text: string) {
         try {
-            await navigator.clipboard.writeText(this.markdownUrl);
-            this.flashCopied("copyUrlLabel");
+            await navigator.clipboard.writeText(text);
+            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() {
+        this.copyMarkdownTooltipLabel = COPIED_TOOLTIP_LABEL;
+        this.copyMarkdownTooltipVisible = true;
+        this.flashCopied();
+    }
+
+    private flashMenuCopied() {
+        this.menuTooltipLabel = COPIED_TOOLTIP_LABEL;
+        this.menuTooltipVisible = true;
+        this.flashCopied();
+    }
+
+    private flashCopied() {
+        if (this.tooltipResetTimeout !== null) {
+            window.clearTimeout(this.tooltipResetTimeout);
+        }
+        this.tooltipResetTimeout = window.setTimeout(() => {
+            this.copyMarkdownTooltipLabel = DEFAULT_TOOLTIP_LABEL;
+            this.copyMarkdownTooltipVisible = false;
+            this.menuTooltipVisible = false;
+            this.menuTooltipLabel = MORE_ACTIONS_LABEL;
+            this.tooltipResetTimeout = null;
+        }, COPIED_RESET_MS);
+    }
+
+    renderedCallback(): void {
+        this.layoutToolbar();
+        this.ensureResizeObserver();
+    }
+
+    disconnectedCallback(): void {
+        this.resizeObserver?.disconnect();
+        this.resizeObserver = null;
+    }
+
+    /* Keep every visible control on one row. The menu trigger stays at the
+       end; action buttons that no longer fit are hidden, last one first. */
+    private layoutToolbar(): void {
+        const toolbar = this.template.querySelector(
+            ".toolbar"
+        ) as HTMLElement | null;
+        if (!toolbar || toolbar.clientWidth <= 0) {
+            return;
+        }
+
+        const children = ([...toolbar.children] as HTMLElement[]).filter(
+            (node) => node instanceof HTMLElement
+        );
+        children.forEach((el) => {
+            delete el.dataset.overflow;
+        });
+        // Reading layout after clearing overflow flushes styles so the
+        // measurements below see the unhidden controls.
+        const availableWidth = toolbar.clientWidth;
+
+        const gap = this.readGap(toolbar);
+        const actionItems = children.filter(
+            (node) =>
+                !node.classList.contains("toolbar-menu") &&
+                !node.classList.contains("divider_menu") &&
+                this.isShown(node)
+        );
+
+        const menuDivider = toolbar.querySelector(
+            ".divider_menu"
+        ) as HTMLElement | null;
+        const menu = toolbar.querySelector(
+            ".toolbar-menu"
+        ) as HTMLElement | null;
+        const menuPieces = [menuDivider, menu].filter(
+            (el): el is HTMLElement => !!el && this.isShown(el)
+        );
+
+        let menuWidth = 0;
+        menuPieces.forEach((el, index) => {
+            menuWidth += el.offsetWidth + (index > 0 ? gap : 0);
+        });
+
+        const groups = this.groupActions(actionItems);
+        let used = 0;
+        let fittedCount = 0;
+
+        for (const group of groups) {
+            let groupWidth = 0;
+            group.forEach((el, index) => {
+                groupWidth += el.offsetWidth + (index > 0 ? gap : 0);
+            });
+
+            const gapBefore = used > 0 ? gap : 0;
+            const gapBeforeMenu = menuWidth > 0 ? gap : 0;
+            const next =
+                used + gapBefore + groupWidth + gapBeforeMenu + menuWidth;
+
+            if (next <= availableWidth + 1) {
+                used += gapBefore + groupWidth;
+                fittedCount += group.length;
+            } else {
+                break;
+            }
+        }
+
+        actionItems.slice(fittedCount).forEach((el) => {
+            el.dataset.overflow = "true";
+        });
+    }
+
+    private ensureResizeObserver(): void {
+        if (this.resizeObserver || typeof ResizeObserver === "undefined") {
+            return;
         }
-        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);
+
+        const toolbar = this.template.querySelector(".toolbar");
+        if (!toolbar) {
+            return;
+        }
+
+        this.resizeObserver = new ResizeObserver(() => {
+            this.layoutToolbar();
+        });
+        this.resizeObserver.observe(toolbar);
+    }
+
+    private groupActions(items: HTMLElement[]): HTMLElement[][] {
+        const groups: HTMLElement[][] = [];
+        let current: HTMLElement[] = [];
+
+        items.forEach((el) => {
+            if (el.classList.contains("divider") && current.length > 0) {
+                groups.push(current);
+                current = [el];
+                return;
+            }
+            current.push(el);
+        });
+
+        if (current.length > 0) {
+            groups.push(current);
+        }
+
+        return groups;
+    }
+
+    private isShown(el: HTMLElement): boolean {
+        return getComputedStyle(el).display !== "none";
+    }
+
+    private readGap(toolbar: HTMLElement): number {
+        const value = parseFloat(getComputedStyle(toolbar).columnGap);
+        return Number.isFinite(value) ? value : 0;
     }
 }

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/redocReference/redocReference.css

@@ -3,4 +3,5 @@
     --doc-c-redoc-sidebar-top: calc(
         var(--dx-g-global-header-height) + var(--dx-g-doc-header-height)
     );
+    --doc-c-redoc-sidebar-bg: white;
 }