@salesforcedevs/docs-components 1.28.7-alpha.9 → 1.29.0-aitoolbar-alpha

package/lwc.config.json

@@ -5,7 +5,10 @@
         { "npm": "@salesforcedevs/dw-components" }
     ],
     "expose": [
+        "doc/aiToolbar",
         "doc/amfReference",
+        "doc/banner",
+        "doc/localeBanner",
         "doc/breadcrumbs",
         "doc/componentPlayground",
         "doc/content",

package/package.json

@@ -1,29 +1,29 @@
 {
-    "name": "@salesforcedevs/docs-components",
-    "version": "1.28.7-alpha.9",
-    "description": "Docs Lightning web components for DSC",
-    "license": "MIT",
-    "main": "index.js",
-    "engines": {
-        "node": "20.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": "c742ad7d26b81c3e78806e5dc0641c23c640f898"
-}
+  "name": "@salesforcedevs/docs-components",
+  "version": "1.29.0-aitoolbar-alpha",
+  "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"
+}

package/src/modules/doc/aiToolbar/aiToolbar.css

@@ -0,0 +1,40 @@
+@import "dxHelpers/reset";
+
+:host {
+    display: inline-flex;
+}
+
+.ai-toolbar {
+    display: flex;
+    align-items: center;
+    gap: var(--dx-g-spacing-smd);
+    padding-bottom: var(--dx-g-spacing-sm);
+}
+
+.toolbar-button {
+    --dx-g-button-inline-color: var(--dx-g-blue-vibrant-50);
+    --dx-g-button-inline-color-hover: var(--dx-g-blue-vibrant-30);
+    --dx-c-button-font-size: var(--dx-g-text-sm);
+    --dx-c-button-horizontal-spacing: 0;
+    --dx-c-button-icon-vertical-align: middle;
+}
+
+.toolbar-button::part(content) {
+    font-family: var(--dx-g-font-display);
+    font-weight: var(--dx-g-font-demi);
+    line-height: var(--dx-g-spacing-mlg);
+    letter-spacing: 0.07px;
+}
+
+.divider {
+    width: 1px;
+    height: var(--dx-g-spacing-md);
+    background-color: var(--dx-g-gray-70);
+}
+
+@media screen and (max-width: 480px) {
+    .toolbar-button_copy-url,
+    .divider_copy-url {
+        display: none;
+    }
+}

package/src/modules/doc/aiToolbar/aiToolbar.html

@@ -0,0 +1,53 @@
+<template>
+    <div class="ai-toolbar">
+        <dx-tooltip placement="top-right" label={copyMarkdownLabel}>
+            <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"></div>
+
+        <dx-button
+            class="toolbar-button"
+            variant="inline"
+            size="small"
+            icon-sprite="utility"
+            icon-symbol="new_window"
+            icon-size="medium"
+            icon-position="right"
+            aria-label={viewMarkdownButtonText}
+            onclick={handleViewMarkdown}
+        >
+            {viewMarkdownButtonText}
+        </dx-button>
+
+        <div class="divider divider_copy-url"></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}
+            >
+                {copyUrlButtonText}
+            </dx-button>
+        </dx-tooltip>
+    </div>
+</template>

package/src/modules/doc/aiToolbar/aiToolbar.ts

@@ -0,0 +1,138 @@
+import { LightningElement } from "lwc";
+import { track } from "dxUtils/analytics";
+
+const DEFAULT_COPY_TOOLTIP_LABEL = "Click to copy";
+const COPIED_TOOLTIP_LABEL = "Copied!";
+const COPIED_TOOLTIP_RESET_MS = 2000;
+
+const ANALYTICS_CONTENT_CATEGORY = "ai toolbar";
+const COPY_MARKDOWN_LABEL = "Copy as Markdown";
+const VIEW_MARKDOWN_LABEL = "View as Markdown";
+const COPY_URL_LABEL = "Copy URL to Markdown";
+
+export default class AiToolbar extends LightningElement {
+    copyMarkdownLabel: string = DEFAULT_COPY_TOOLTIP_LABEL;
+    copyUrlLabel: string = DEFAULT_COPY_TOOLTIP_LABEL;
+
+    private copyTooltipResetTimeout: number | null = null;
+
+    get copyMarkdownButtonText(): string {
+        return COPY_MARKDOWN_LABEL;
+    }
+
+    get viewMarkdownButtonText(): string {
+        return VIEW_MARKDOWN_LABEL;
+    }
+
+    get copyUrlButtonText(): string {
+        return COPY_URL_LABEL;
+    }
+
+    async handleCopyMarkdown(event: Event) {
+        const markdownUrl = this.getMarkdownUrl();
+        if (!markdownUrl) {
+            return;
+        }
+
+        this.trackToolbarEvent(
+            event,
+            "custEv_linkClick",
+            COPY_MARKDOWN_LABEL,
+            markdownUrl
+        );
+
+        try {
+            const response = await fetch(markdownUrl);
+            if (!response.ok) {
+                return;
+            }
+            const markdown = await response.text();
+            await navigator.clipboard.writeText(markdown);
+            this.flashCopied("copyMarkdownLabel");
+        } catch (error) {
+            console.error(error);
+        }
+    }
+
+    handleViewMarkdown(event: Event) {
+        const markdownUrl = this.getMarkdownUrl();
+        if (!markdownUrl) {
+            return;
+        }
+
+        this.trackToolbarEvent(
+            event,
+            "custEv_linkClick",
+            VIEW_MARKDOWN_LABEL,
+            markdownUrl
+        );
+
+        window.open(markdownUrl, "_blank", "noopener,noreferrer");
+    }
+
+    async handleCopyUrl(event: Event) {
+        const markdownUrl = this.getMarkdownUrl();
+        if (!markdownUrl) {
+            return;
+        }
+
+        this.trackToolbarEvent(
+            event,
+            "custEv_linkClick",
+            COPY_URL_LABEL,
+            markdownUrl
+        );
+
+        try {
+            await navigator.clipboard.writeText(markdownUrl);
+            this.flashCopied("copyUrlLabel");
+        } catch (error) {
+            console.error(error);
+        }
+    }
+
+    private trackToolbarEvent(
+        event: Event,
+        eventName: "custEv_linkClick",
+        label: string,
+        url: string
+    ): void {
+        track(event.currentTarget!, eventName, {
+            click_text: label,
+            click_url: url,
+            element_type: "button_link",
+            element_title: label,
+            content_category: ANALYTICS_CONTENT_CATEGORY
+        });
+    }
+
+    /**
+     * Returns the `.md` equivalent of the current page URL with any hash and
+     * query string stripped, or `null` when the current page does not end
+     * with `.html`.
+     */
+    private getMarkdownUrl(): string | null {
+        const url = new URL(window.location.href);
+        url.hash = "";
+        url.search = "";
+
+        if (!url.pathname.endsWith(".html")) {
+            return null;
+        }
+
+        url.pathname = url.pathname.replace(/\.html$/, ".md");
+        return url.toString();
+    }
+
+    private flashCopied(labelKey: "copyMarkdownLabel" | "copyUrlLabel") {
+        if (this.copyTooltipResetTimeout !== null) {
+            window.clearTimeout(this.copyTooltipResetTimeout);
+        }
+        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);
+    }
+}

package/src/modules/doc/aiToolbar/aiToolbarMocks.ts

@@ -0,0 +1,48 @@
+import { http, HttpResponse } from "msw";
+
+/**
+ * Mocks for the AI toolbar so stories never hit the real
+ * docs backend. Any story rendering `doc-ai-toolbar` (directly or via
+ * `doc-content-layout`) must register `aiToolbarMswHandlers` and call
+ * `interceptWindowOpenForAiToolbar()`.
+ */
+export const DUMMY_MARKDOWN_CONTENT = `# Dummy Markdown
+
+Storybook serves this placeholder content in place of the real markdown
+that the docs backend would return for the current page. It exists so
+the "Copied" tooltip, the "View as Markdown" new tab, and the
+"Copy URL to Markdown" clipboard behavior are all exercisable in
+storybook without hitting the live backend.
+
+- Item 1
+- Item 2
+- Item 3
+`;
+
+export const DUMMY_MARKDOWN_DATA_URL = `data:text/markdown;charset=utf-8,${encodeURIComponent(
+    DUMMY_MARKDOWN_CONTENT
+)}`;
+
+/** Intercepts any `.md` GET request and returns the dummy markdown. */
+export const aiToolbarMswHandlers = [
+    http.get(/\.md(\?.*)?$/, () => HttpResponse.text(DUMMY_MARKDOWN_CONTENT))
+];
+
+let windowOpenIntercepted = false;
+
+/** Redirects `window.open` calls for `.md` URLs to the dummy markdown data URL (MSW does not cover new tabs). */
+export function interceptWindowOpenForAiToolbar() {
+    if (windowOpenIntercepted) {
+        return;
+    }
+    windowOpenIntercepted = true;
+
+    const originalOpen = window.open.bind(window);
+    window.open = ((url?: string | URL, target?: string, features?: string) => {
+        const stringUrl = url?.toString() ?? "";
+        if (stringUrl.endsWith(".md")) {
+            return originalOpen(DUMMY_MARKDOWN_DATA_URL, target, features);
+        }
+        return originalOpen(url ?? "", target, features);
+    }) as typeof window.open;
+}

package/src/modules/doc/amfReference/amfReference.html

@@ -17,6 +17,7 @@
         languages={languages}
         language={language}
         show-footer={enableFooter}
+        show-ai-toolbar={showAiToolbar}
         empty-state-message={emptyStateMessage}
         origin={origin}
     >

package/src/modules/doc/amfReference/amfReference.ts

@@ -37,6 +37,7 @@ type NavigationItem = {
     isExpanded: boolean;
     children: ParsedMarkdownTopic[];
     isChildrenLoading: boolean;
+    showForwardArrow?: boolean;
 };
 
 export default class AmfReference extends LightningElement {
@@ -72,6 +73,16 @@ export default class AmfReference extends LightningElement {
         return this.isSpecBasedReference(this._currentReferenceId);
     }
 
+    /**
+     * AI toolbar is only enabled for markdown-based references in the en-us locale.
+     */
+    get showAiToolbar(): boolean {
+        return (
+            !this.showSpecBasedReference &&
+            this.language?.toLowerCase() === "en-us"
+        );
+    }
+
     @api
     get referenceSetConfig(): ReferenceSetConfig {
         return this._referenceSetConfig;
@@ -204,6 +215,7 @@ export default class AmfReference extends LightningElement {
 
     _boundOnApiNavigationChanged;
     _boundUpdateSelectedItemFromUrlQuery;
+    _boundOnPageShow;
 
     constructor() {
         super();
@@ -212,6 +224,7 @@ export default class AmfReference extends LightningElement {
             this.onApiNavigationChanged.bind(this);
         this._boundUpdateSelectedItemFromUrlQuery =
             this.updateSelectedItemFromUrlQuery.bind(this);
+        this._boundOnPageShow = this.onPageShow.bind(this);
     }
 
     connectedCallback(): void {
@@ -223,6 +236,7 @@ export default class AmfReference extends LightningElement {
             "popstate",
             this._boundUpdateSelectedItemFromUrlQuery
         );
+        window.addEventListener("pageshow", this._boundOnPageShow);
     }
 
     disconnectedCallback(): void {
@@ -234,6 +248,22 @@ export default class AmfReference extends LightningElement {
             "popstate",
             this._boundUpdateSelectedItemFromUrlQuery
         );
+        window.removeEventListener("pageshow", this._boundOnPageShow);
+    }
+
+    /**
+     * On bfcache restore, reset the sidebar selection so the tree re-syncs
+     * its highlighted tile with the current URL.
+     */
+    protected onPageShow(event: PageTransitionEvent): void {
+        if (!event.persisted) {
+            return;
+        }
+        const currentPath = window.location.pathname;
+        this.selectedSidebarValue = "";
+        Promise.resolve().then(() => {
+            this.selectedSidebarValue = currentPath;
+        });
     }
 
     renderedCallback(): void {
@@ -443,16 +473,21 @@ export default class AmfReference extends LightningElement {
             let navItemChildren = [] as ParsedMarkdownTopic[];
             let isChildrenLoading = false;
             if (amfConfig.referenceType !== REFERENCE_TYPES.markdown) {
-                if (amfConfig.isSelected) {
-                    const amfPromise = this.fetchAmf(amfConfig).then(
-                        (amfJson) => {
-                            this.updateModel(amfConfig.id, amfJson);
-                            this.assignNavigationItemsFromAmf(amfConfig, index);
-                        }
-                    );
-                    this.amfFetchPromiseMap[amfConfig.id] = amfPromise;
+                if (amfConfig.amf) {
+                    if (amfConfig.isSelected) {
+                        const amfPromise = this.fetchAmf(amfConfig).then(
+                            (amfJson) => {
+                                this.updateModel(amfConfig.id, amfJson);
+                                this.assignNavigationItemsFromAmf(
+                                    amfConfig,
+                                    index
+                                );
+                            }
+                        );
+                        this.amfFetchPromiseMap[amfConfig.id] = amfPromise;
+                    }
+                    isChildrenLoading = true;
                 }
-                isChildrenLoading = true;
             } else {
                 const isExpandChildrenEnabled = this.isExpandChildrenEnabled(
                     amfConfig.id
@@ -473,13 +508,30 @@ export default class AmfReference extends LightningElement {
                     amfConfig.isSelected ||
                     this.isExpandChildrenEnabled(amfConfig.id),
                 children: navItemChildren,
-                isChildrenLoading
+                isChildrenLoading,
+                showForwardArrow: this.resolveNavRenderWith(amfConfig)
             };
             this.parentReferenceUrls.push(amfConfig.href);
         }
         this.navigation = navAmfOrder;
     }
 
+    /**
+     * Determines whether the sidebar tile should render a forward arrow for
+     * this reference. Honors `redoc` set on the config, and also infers it
+     * for non-markdown references that have no AMF URL (i.e. those rendered
+     * by Redoc).
+     */
+    private resolveNavRenderWith(amfConfig: AmfConfig): boolean {
+        if (amfConfig.renderWith) {
+            return amfConfig.renderWith === "redoc";
+        }
+        return (
+            amfConfig.referenceType !== REFERENCE_TYPES.markdown &&
+            !amfConfig.amf
+        );
+    }
+
     /**
      * Returns a boolean indicating whether the children should be expanded or not.
      */

package/src/modules/doc/amfReference/types.ts

@@ -78,6 +78,11 @@ export interface AmfConfig {
 
     // required for markdown based references
     topic?: ParsedMarkdownTopic;
+
+    /**
+     * Required for rendering the arrow on LNB
+     */
+    renderWith?: string;
 }
 
 export interface ParsedTopicModel {

package/src/modules/doc/banner/banner.css

@@ -0,0 +1,88 @@
+@import "dxHelpers/reset";
+@import "dxHelpers/text";
+
+:host {
+    display: block;
+
+    --doc-banner-padding-left: var(--dx-g-spacing-2xl);
+    --doc-banner-padding-right: var(--dx-g-spacing-lg);
+}
+
+.container {
+    display: flex;
+    align-items: flex-start;
+    background: var(--dx-g-gray-90);
+    padding: 0 var(--doc-banner-padding-right) 0 var(--doc-banner-padding-left);
+}
+
+.icon {
+    --dx-c-icon-size: var(--dx-g-icon-size-lg);
+
+    flex-shrink: 0;
+    margin-top: var(--dx-g-spacing-smd);
+    margin-right: var(--dx-g-spacing-sm);
+}
+
+.main {
+    flex: 1;
+    min-width: 0;
+    display: flex;
+    flex-wrap: wrap;
+    align-items: flex-start;
+    column-gap: var(--dx-g-spacing-md);
+    padding: calc((var(--dx-g-spacing-xs) + var(--dx-g-spacing-sm)) / 2) 0;
+}
+
+.message {
+    flex: 0 1 auto;
+    font-size: var(--dx-g-text-sm);
+    color: var(--dx-g-gray-10);
+    padding: calc((var(--dx-g-spacing-xs) + var(--dx-g-spacing-sm)) / 2) 0;
+}
+
+.message a {
+    color: var(--dx-g-cloud-blue-vibrant-50);
+    text-decoration: underline;
+}
+
+.actions {
+    flex: 0 0 auto;
+    display: flex;
+    align-items: center;
+    gap: var(--dx-g-spacing-smd);
+}
+
+.actions dx-button {
+    --dx-c-button-font-size: var(--dx-g-text-sm);
+    --dx-c-button-font-weight: var(--dx-g-font-normal);
+
+    flex: 0 0 auto;
+}
+
+.close {
+    --dx-c-icon-size: var(--dx-g-icon-size-lg);
+
+    flex-shrink: 0;
+    align-self: flex-start;
+    width: calc(var(--dx-g-spacing-3xl) + var(--dx-g-spacing-xs));
+    height: calc(var(--dx-g-spacing-2xl) + var(--dx-g-spacing-xs));
+    margin-left: auto;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    cursor: pointer;
+}
+
+@media (max-width: 1279px) {
+    :host {
+        --doc-banner-padding-left: var(--dx-g-spacing-xl);
+        --doc-banner-padding-right: var(--dx-g-spacing-md);
+    }
+}
+
+@media (max-width: 768px) {
+    :host {
+        --doc-banner-padding-left: var(--dx-g-spacing-lg);
+        --doc-banner-padding-right: var(--dx-g-spacing-sm);
+    }
+}

package/src/modules/doc/banner/banner.html

@@ -0,0 +1,47 @@
+<template>
+    <template lwc:if={showBanner}>
+        <div class="container" part="container">
+            <dx-icon
+                class="icon"
+                symbol="info"
+                size="override"
+                color="gray-50"
+                part="icon"
+            ></dx-icon>
+            <div class="main">
+                <div class="message" part="message" lwc:dom="manual"></div>
+                <div class="actions" part="actions">
+                    <template lwc:if={hasPrimaryButton}>
+                        <dx-button
+                            href={buttonHref}
+                            variant="primary"
+                            size="small"
+                            part="button"
+                        >
+                            {buttonLabel}
+                        </dx-button>
+                    </template>
+                    <template lwc:if={hasSecondaryAction}>
+                        <dx-button
+                            variant="inline"
+                            onclick={handleSecondaryClick}
+                            part="secondary"
+                        >
+                            {secondaryLabel}
+                        </dx-button>
+                    </template>
+                </div>
+            </div>
+            <dx-button
+                class="close"
+                variant="icon-only"
+                icon-symbol="close"
+                icon-size="override"
+                icon-color="gray-50"
+                aria-label="Close"
+                onclick={handleCloseClick}
+                part="close"
+            ></dx-button>
+        </div>
+    </template>
+</template>