@salesforcedevs/docs-components 1.29.0-newct-alpha2 → 1.29.0-toolbar-alpha

package/lwc.config.json

@@ -5,6 +5,7 @@
         { "npm": "@salesforcedevs/dw-components" }
     ],
     "expose": [
+        "doc/contentActionToolbar",
         "doc/amfReference",
         "doc/banner",
         "doc/localeBanner",
@@ -17,7 +18,6 @@
         "doc/contentMedia",
         "doc/docXmlContent",
         "doc/lwcContentLayout",
-        "doc/unifiedContentLayout",
         "doc/header",
         "doc/heading",
         "doc/headingAnchor",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforcedevs/docs-components",
-  "version": "1.29.0-newct-alpha2",
+  "version": "1.29.0-toolbar-alpha",
   "description": "Docs Lightning web components for DSC",
   "license": "MIT",
   "main": "index.js",

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

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

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

@@ -73,6 +73,17 @@ export default class AmfReference extends LightningElement {
         return this.isSpecBasedReference(this._currentReferenceId);
     }
 
+    /**
+     * Content action toolbar is only enabled for markdown-based references in the en-us locale.
+     */
+    get showContentActionToolbar(): boolean {
+        if (this.showSpecBasedReference) {
+            return false;
+        }
+        const locale = this.language?.toLowerCase() ?? "en-us";
+        return locale === "en-us";
+    }
+
     @api
     get referenceSetConfig(): ReferenceSetConfig {
         return this._referenceSetConfig;

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

@@ -0,0 +1,31 @@
+@import "dxHelpers/reset";
+
+:host {
+    display: block;
+    margin-bottom: var(--dx-g-spacing-lg);
+}
+
+.toolbar {
+    display: flex;
+    align-items: center;
+    gap: var(--dx-g-spacing-smd);
+}
+
+.toolbar-button {
+    --dx-c-button-font-weight: var(--dx-g-font-demi);
+    --dx-c-button-line-height: var(--dx-g-spacing-mlg);
+    --dx-c-button-letter-spacing: 0.005em;
+}
+
+.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/contentActionToolbar/contentActionToolbar.html

@@ -0,0 +1,53 @@
+<template>
+    <div class="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/contentActionToolbar/contentActionToolbar.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 = "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";
+
+export default class ContentActionToolbar 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/contentActionToolbar/contentActionToolbarMocks.ts

@@ -0,0 +1,48 @@
+import { http, HttpResponse } from "msw";
+
+/**
+ * Mocks for the content action toolbar so stories never hit the real
+ * docs backend. Any story rendering `doc-content-action-toolbar` (directly or
+ * via `doc-content-layout`) must register `contentActionToolbarMswHandlers`
+ * and call `interceptWindowOpenForContentActionToolbar()`.
+ */
+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 contentActionToolbarMswHandlers = [
+    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 interceptWindowOpenForContentActionToolbar() {
+    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/contentLayout/contentLayout.ts

@@ -1,11 +1,15 @@
 /* eslint-disable @lwc/lwc/no-document-query */
-import { LightningElement, api, track } from "lwc";
-import { closest } from "kagekiri";
+import { LightningElement, api, createElement, track } from "lwc";
+import { closest, querySelector } from "kagekiri";
 import { toJson, normalizeBoolean } from "dxUtils/normalizers";
 import { highlightTerms } from "dxUtils/highlight";
 import { SearchSyncer } from "docUtils/searchSyncer";
 import type { OptionWithLink } from "typings/custom";
 import { buildDocLinkClickHandler } from "dxUtils/analytics";
+import ContentActionToolbar from "doc/contentActionToolbar";
+
+const CONTENT_ACTION_TOOLBAR_TAG = "doc-content-action-toolbar";
+const PAGE_HEADING_SELECTOR = "h1";
 
 type AnchorMap = { [key: string]: { intersect: boolean; id: string } };
 
@@ -95,6 +99,17 @@ export default class ContentLayout extends LightningElement {
     /** Optional origin URL for the footer MFE (e.g. wp-json endpoint). Passed through to dx-footer. */
     @api origin: string | null = null;
 
+    /** Controls whether the content action toolbar is displayed. */
+    @api
+    get showContentActionToolbar() {
+        return this._showContentActionToolbar;
+    }
+    set showContentActionToolbar(value) {
+        this._showContentActionToolbar = normalizeBoolean(value);
+        this.updateContentActionToolbar();
+    }
+    private _showContentActionToolbar = false;
+
     @api
     get breadcrumbs() {
         return this._breadcrumbs;
@@ -152,6 +167,7 @@ export default class ContentLayout extends LightningElement {
     protected hasRendered: boolean = false;
     protected contentLoaded: boolean = false;
     protected sidebarOpen: boolean = false;
+    protected contentActionToolbarElement: HTMLElement | null = null;
 
     get shouldDisplayFeedback() {
         return this.contentLoaded && typeof Sprig !== "undefined";
@@ -257,6 +273,8 @@ export default class ContentLayout extends LightningElement {
         window.addEventListener("scroll", this.adjustNavPosition);
         window.addEventListener("resize", this.adjustNavPosition);
 
+        this.updateContentActionToolbar();
+
         if (!this.hasRendered) {
             this.hasRendered = true;
             this.restoreScroll();
@@ -266,6 +284,47 @@ export default class ContentLayout extends LightningElement {
         }
     }
 
+    /**
+     * Inserts the content action toolbar into the slotted content immediately
+     * after the first H1 found inside this layout.
+     */
+    protected updateContentActionToolbar(): void {
+        if (!this.showContentActionToolbar) {
+            this.removeContentActionToolbar();
+            return;
+        }
+
+        const heading = querySelector(
+            PAGE_HEADING_SELECTOR,
+            this.template.host
+        ) as HTMLElement | null;
+
+        if (!heading) {
+            return;
+        }
+
+        if (
+            this.contentActionToolbarElement?.previousElementSibling === heading
+        ) {
+            return;
+        }
+
+        this.removeContentActionToolbar();
+
+        const toolbar = createElement(CONTENT_ACTION_TOOLBAR_TAG, {
+            is: ContentActionToolbar
+        }) as unknown as HTMLElement;
+        heading.parentNode?.insertBefore(toolbar, heading.nextSibling);
+        this.contentActionToolbarElement = toolbar;
+    }
+
+    protected removeContentActionToolbar(): void {
+        if (this.contentActionToolbarElement) {
+            this.contentActionToolbarElement.remove();
+            this.contentActionToolbarElement = null;
+        }
+    }
+
     disconnectedCallback(): void {
         this.disconnectObserver();
         window.removeEventListener(
@@ -281,6 +340,8 @@ export default class ContentLayout extends LightningElement {
 
         // Remove link click handler
         this.template.removeEventListener("click", this.handleLinkClick);
+
+        this.removeContentActionToolbar();
     }
 
     restoreScroll() {
@@ -523,6 +584,7 @@ export default class ContentLayout extends LightningElement {
 
     onSlotChange(): void {
         this.updateRNB();
+        this.updateContentActionToolbar();
         this.contentLoaded = true;
     }
 

package/src/modules/doc/unifiedContentLayout/unifiedContentLayout.css

@@ -1,3 +0,0 @@
-:host {
-    display: block;
-}

package/src/modules/doc/unifiedContentLayout/unifiedContentLayout.html

@@ -1,34 +0,0 @@
-<template>
-    <doc-content-layout
-        class="content-type content-type-markdown content-type-docs"
-        breadcrumbs={breadcrumbs}
-        share-title={shareTitle}
-        share-twitter-via={twitterVia}
-        sidebar-header={sidebarHeader}
-        sidebar-value={sidebarValue}
-        sidebar-content={sidebarContent}
-        toc-title={tocTitle}
-        toc-options={tocOptions}
-        toc-aria-level={tocAriaLevel}
-        enable-slot-change="true"
-        languages={languages}
-        language={language}
-        show-footer={enableFooter}
-        origin={origin}
-    >
-        <doc-phase
-            slot="doc-phase"
-            lwc:if={docPhaseInfo}
-            doc-phase-info={docPhaseInfo}
-        ></doc-phase>
-
-        <template lwc:if={isMarkdownTopic}>
-            <slot></slot>
-        </template>
-        <!--
-            TODO(W-22340752): render OAS specs via doc-redoc-reference when
-            topicType === "spec". The docs content-type parser currently 404s
-            spec topics until that path lands.
-        -->
-    </doc-content-layout>
-</template>

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

@@ -1,94 +0,0 @@
-import { LightningElement, api } from "lwc";
-import { toJson, normalizeBoolean } from "dxUtils/normalizers";
-import type { OptionWithLink } from "typings/custom";
-
-/**
- * Topic types emitted by the docs content-type parser
- * (see @salesforcedevs/sfdocs-doc-framework: `TopicTypeEnum`).
- */
-const TOPIC_TYPE_MARKDOWN = "markdown";
-const TOPIC_TYPE_SPEC = "spec";
-
-/**
- * Wrapper around `doc-content-layout` for the "docs" content type emitted by
- * the `DocsContentTypeParser`.
- *
- * Mirrors the role that `doc-amf-reference` plays for the "reference" content
- * type: it owns content-type-aware concerns (markdown body vs. OAS spec via
- * Redoc) and forwards the chrome (sidebar, breadcrumbs, TOC, footer) to
- * `doc-content-layout`.
- *
- * Only the markdown topic type is wired up today. OAS spec rendering via Redoc
- * is tracked separately (W-22340752) and currently 404s upstream in the parser.
- */
-export default class UnifiedContentLayout extends LightningElement {
-    @api breadcrumbs: string | null = null;
-    @api sidebarHeader?: string;
-    @api sidebarValue?: string;
-    @api tocTitle?: string;
-    @api tocOptions?: string;
-    @api tocAriaLevel?: string;
-    @api languages?: OptionWithLink[];
-    @api language?: string;
-
-    /** Optional origin URL for the footer MFE (e.g. wp-json endpoint). */
-    @api origin: string | null = null;
-
-    /** Article name from breadcrumbs, used as share title (e.g. for social share). */
-    @api shareTitle: string | null = null;
-
-    /** Optional Twitter "via" handle (e.g. SalesforceDevs) for social share. */
-    @api twitterVia: string | null = null;
-
-    @api hideFooter = false;
-
-    /**
-     * Topic type forwarded from the layout template. The docs parser supports
-     * `markdown` today and `spec` (OAS via Redoc) in a follow-up.
-     */
-    @api topicType: string = TOPIC_TYPE_MARKDOWN;
-
-    private _docPhaseInfo: string | null = null;
-    private _sidebarContent: unknown = null;
-
-    @api
-    get docPhaseInfo(): string | null {
-        return this._docPhaseInfo;
-    }
-
-    set docPhaseInfo(value: string | null) {
-        this._docPhaseInfo = value || null;
-    }
-
-    @api
-    get sidebarContent(): unknown {
-        return this._sidebarContent;
-    }
-
-    set sidebarContent(value: string | { topics?: unknown } | null) {
-        this._sidebarContent = value ? toJson(value)?.topics ?? null : null;
-    }
-
-    private _expandChildren = false;
-
-    @api
-    get expandChildren(): boolean {
-        return this._expandChildren;
-    }
-
-    set expandChildren(value: boolean | string) {
-        this._expandChildren = normalizeBoolean(value);
-    }
-
-    get isMarkdownTopic(): boolean {
-        return this.topicType === TOPIC_TYPE_MARKDOWN;
-    }
-
-    get isSpecTopic(): boolean {
-        return this.topicType === TOPIC_TYPE_SPEC;
-    }
-
-    private get enableFooter(): boolean {
-        return !this.hideFooter;
-    }
-}