@salesforcedevs/docs-components 1.27.21 → 1.27.22-banner-2

package/lwc.config.json

@@ -6,6 +6,7 @@
     ],
     "expose": [
         "doc/amfReference",
+        "doc/banner",
         "doc/breadcrumbs",
         "doc/componentPlayground",
         "doc/content",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@salesforcedevs/docs-components",
-    "version": "1.27.21",
+    "version": "1.27.22-banner-2",
     "description": "Docs Lightning web components for DSC",
     "license": "MIT",
     "main": "index.js",
@@ -25,5 +25,5 @@
         "@types/lodash.orderby": "4.6.9",
         "@types/lodash.uniqby": "4.7.9"
     },
-    "gitHead": "bb47c49e52267b9068ff826a16f39364f49e3086"
+    "gitHead": "c959551dac6b9344903bfe83fc5d38d17bf5989f"
 }

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

@@ -0,0 +1,211 @@
+@import "dxHelpers/reset";
+@import "dxHelpers/text";
+
+:host {
+    display: block;
+
+    --doc-banner-bg: var(--neutral-90, #e5e5e5);
+    --doc-banner-height: 44px;
+    --doc-banner-padding-x-left: 40px;
+    --doc-banner-padding-x-right: var(--dx-g-spacing-lg);
+    --doc-banner-icon-size: 18.4615px;
+    --doc-banner-icon-frame-width: calc(
+        var(--doc-banner-padding-x-left) + var(--doc-banner-icon-size) +
+            var(--dx-g-spacing-sm)
+    );
+    --doc-banner-close-color: #747474;
+    --doc-banner-primary-bg: #0176d3;
+    --doc-banner-primary-bg-hover: #0160b3;
+}
+
+.doc-notification-bar {
+    display: flex;
+    align-items: flex-start;
+    justify-content: space-between;
+    width: 100%;
+    margin: 0;
+    min-height: var(--doc-banner-height);
+    padding: 0 var(--doc-banner-padding-x-right) 0
+        var(--doc-banner-padding-x-left);
+    background: var(--doc-banner-bg);
+    box-sizing: border-box;
+}
+
+.doc-notification-bar .icon-wrap,
+.doc-notification-bar .main,
+.doc-notification-bar .content,
+.doc-notification-bar .actions,
+.doc-notification-bar .close-wrap {
+    display: flex;
+    align-items: center;
+}
+
+.doc-notification-bar .icon-wrap,
+.doc-notification-bar .close-wrap {
+    flex-shrink: 0;
+}
+
+.doc-notification-bar .main {
+    flex: 1 1 0;
+    min-width: 0;
+    align-self: flex-start;
+    padding: 6px 0;
+    gap: var(--dx-g-spacing-md);
+}
+
+.doc-notification-bar .icon-wrap {
+    width: calc(var(--doc-banner-icon-size) + var(--dx-g-spacing-sm));
+    min-height: 32px;
+    align-self: flex-start;
+    justify-content: flex-start;
+    align-items: flex-start;
+}
+
+.doc-notification-bar .icon-wrap dx-icon {
+    --dx-c-icon-size: var(--doc-banner-icon-size);
+
+    width: var(--doc-banner-icon-size);
+    height: var(--doc-banner-icon-size);
+    padding: 12px 8px 0 0;
+    box-sizing: content-box;
+}
+
+.doc-notification-bar .content {
+    flex: 0 1 auto;
+    min-width: 0;
+    max-width: 100%;
+    min-height: 32px;
+    align-items: flex-start;
+    gap: var(--dx-g-spacing-sm);
+}
+
+.doc-notification-bar .message {
+    margin: 0;
+    padding: 6px 0;
+    font-size: 14px;
+    font-weight: 400;
+    line-height: 20px;
+    color: var(--dx-g-neutral-30, #444);
+}
+
+.doc-notification-bar .message a {
+    color: var(--dx-g-cloud-blue-vibrant-50);
+    text-decoration: underline;
+}
+
+.doc-notification-bar .message a:hover {
+    opacity: 0.9;
+}
+
+.doc-notification-bar .actions {
+    flex-shrink: 0;
+    min-height: 32px;
+    gap: var(--dx-g-spacing-smd);
+    flex-wrap: wrap;
+}
+
+.doc-notification-bar .primary-btn {
+    --dx-c-button-primary-color: var(--doc-banner-primary-bg);
+    --dx-c-button-primary-color-hover: var(--doc-banner-primary-bg-hover);
+    --dx-c-button-vertical-spacing: 0;
+    --dx-c-button-horizontal-spacing: var(--dx-g-spacing-md);
+
+    min-width: min(144px, 100%);
+    height: 32px;
+    border-radius: var(--dx-g-spacing-xs);
+}
+
+.doc-notification-bar .primary-btn::part(container) {
+    min-width: min(144px, 100%);
+    width: 100%;
+    height: 32px;
+    padding: 0 var(--dx-g-spacing-md);
+    border-radius: var(--dx-g-spacing-xs);
+}
+
+.doc-notification-bar .secondary-btn {
+    font-weight: var(--dx-g-font-normal);
+}
+
+.doc-notification-bar .close-wrap {
+    align-self: flex-start;
+    justify-content: center;
+    align-items: center;
+    width: 52px;
+    height: 44px;
+    padding: 12px 8px 18px;
+    margin-left: auto;
+    box-sizing: border-box;
+}
+
+.doc-notification-bar .close-wrap .close-btn {
+    width: 100%;
+    height: 100%;
+
+    --dx-c-button-custom-color: var(--doc-banner-close-color);
+    --dx-c-button-custom-color-hover: var(--doc-banner-close-color);
+    --dx-c-button-custom-background: transparent;
+    --dx-c-button-custom-background-hover: rgb(0 0 0 / 5%);
+    --dx-c-button-custom-border: none;
+    --dx-c-button-custom-border-hover: none;
+}
+
+@media (max-width: 1279px) {
+    :host {
+        --doc-banner-padding-x-left: 32px;
+        --doc-banner-padding-x-right: var(--dx-g-spacing-md);
+    }
+
+    .doc-notification-bar {
+        position: relative;
+        max-width: 100%;
+        min-height: 78px;
+        flex-wrap: wrap;
+        align-content: space-between;
+        padding: 0 var(--doc-banner-padding-x-right) 0 0;
+    }
+
+    .doc-notification-bar .icon-wrap {
+        position: absolute;
+        left: 0;
+        top: 0;
+        bottom: 0;
+        width: var(--doc-banner-icon-frame-width);
+        min-height: 0;
+        padding: 0 0 0 var(--doc-banner-padding-x-left);
+        order: 0;
+    }
+
+    .doc-notification-bar .main {
+        order: 1;
+        flex-wrap: wrap;
+        margin-left: var(--doc-banner-icon-frame-width);
+        gap: var(--dx-g-spacing-2xs);
+    }
+
+    .doc-notification-bar .content {
+        order: 0;
+    }
+
+    .doc-notification-bar .close-wrap {
+        order: 2;
+        min-height: 44px;
+    }
+
+    .doc-notification-bar .actions {
+        order: 1;
+        flex: 0 0 100%;
+        width: 100%;
+    }
+}
+
+@media (max-width: 768px) {
+    :host {
+        --doc-banner-padding-x-left: 24px;
+        --doc-banner-padding-x-right: var(--dx-g-spacing-sm);
+    }
+
+    .doc-notification-bar {
+        min-height: 44px;
+    }
+}

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

@@ -0,0 +1,62 @@
+<template>
+    <template lwc:if={showBanner}>
+        <div class="doc-notification-bar" part="container">
+            <div class="icon-wrap" part="icon-wrap">
+                <dx-icon symbol="info" part="icon" color="#747474"></dx-icon>
+            </div>
+            <div class="main" part="main">
+                <div class="content" part="content">
+                    <p class="message dx-text-body-4" part="message">
+                        <template lwc:if={messageText}>{messageText}</template>
+                        <template lwc:if={hasMessageLink}>
+                            <a
+                                href={messageLinkUrl}
+                                target="_blank"
+                                rel="noopener noreferrer"
+                                part="message-link"
+                            >
+                                {messageLinkText}
+                            </a>
+                        </template>
+                    </p>
+                </div>
+                <div class="actions" part="actions">
+                    <template lwc:if={hasPrimaryButton}>
+                        <dx-button
+                            class="primary-btn"
+                            href={buttonHref}
+                            variant="primary"
+                            size="small"
+                            part="button"
+                        >
+                            {buttonLabel}
+                        </dx-button>
+                    </template>
+                    <template lwc:if={hasSecondaryAction}>
+                        <dx-button
+                            class="secondary-btn"
+                            variant="inline"
+                            onclick={handleSecondaryClick}
+                            part="secondary"
+                        >
+                            {secondaryLabel}
+                        </dx-button>
+                    </template>
+                </div>
+            </div>
+            <template lwc:if={showCloseButton}>
+                <div class="close-wrap" part="close-wrap">
+                    <dx-button
+                        class="close-btn"
+                        variant="icon-only"
+                        icon-symbol="close"
+                        icon-color="#747474"
+                        aria-label="Close"
+                        onclick={handleCloseClick}
+                        part="close"
+                    ></dx-button>
+                </div>
+            </template>
+        </div>
+    </template>
+</template>

package/src/modules/doc/banner/banner.ts

@@ -0,0 +1,92 @@
+import { LightningElement, api, track } from "lwc";
+import { normalizeBoolean } from "dxUtils/normalizers";
+
+const LOCALE_BANNER_STORAGE_PREFIX = "dsc-doc-locale-banner-dismissed-";
+
+export default class Banner extends LightningElement {
+    @api messageText = "";
+
+    @api messageLinkUrl = "";
+
+    @api messageLinkText = "here";
+
+    @api buttonLabel = "";
+
+    @api buttonHref = "";
+
+    @api secondaryLabel = "";
+
+    @api dismissStorageKey = "";
+
+    _showCloseButton = false;
+
+    @api
+    get showCloseButton(): boolean {
+        return this._showCloseButton;
+    }
+    set showCloseButton(value: string | boolean) {
+        this._showCloseButton = normalizeBoolean(value);
+    }
+
+    @track private _dismissed = false;
+
+    connectedCallback() {
+        if (
+            this.dismissStorageKey &&
+            typeof window !== "undefined" &&
+            window.localStorage
+        ) {
+            this._dismissed =
+                window.localStorage.getItem(
+                    `${LOCALE_BANNER_STORAGE_PREFIX}${this.dismissStorageKey}`
+                ) === "true";
+        }
+    }
+
+    get showBanner(): boolean {
+        if (!this.dismissStorageKey) {
+            return true;
+        }
+        return !this._dismissed;
+    }
+
+    get hasMessageLink(): boolean {
+        return !!this.messageLinkUrl;
+    }
+
+    get hasPrimaryButton(): boolean {
+        return !!(this.buttonLabel && this.buttonHref);
+    }
+
+    get hasSecondaryAction(): boolean {
+        return !!this.secondaryLabel;
+    }
+
+    persistDismissAndHide() {
+        if (
+            this.dismissStorageKey &&
+            typeof window !== "undefined" &&
+            window.localStorage
+        ) {
+            window.localStorage.setItem(
+                `${LOCALE_BANNER_STORAGE_PREFIX}${this.dismissStorageKey}`,
+                "true"
+            );
+        }
+        this._dismissed = true;
+    }
+
+    handleSecondaryClick() {
+        this.persistDismissAndHide();
+        this.dispatchEvent(
+            new CustomEvent("dismiss", { bubbles: true, composed: true })
+        );
+    }
+
+    handleCloseClick() {
+        this.persistDismissAndHide();
+        this.dispatchEvent(
+            new CustomEvent("dismiss", { bubbles: true, composed: true })
+        );
+    }
+}

package/src/modules/doc/contentLayout/contentLayout.html

@@ -1,76 +1,88 @@
 <template>
-    <div class="content">
-        <dx-sidebar-old
-            class="is-sticky left-nav-bar"
-            trees={sidebarContent}
-            value={sidebarValue}
-            header={sidebarHeader}
-            ontogglesidebar={onToggleSidebar}
-            languages={languages}
-            language={language}
-            bail-href={bailHref}
-            bail-label={bailLabel}
-            dev-center={devCenter}
-            brand={brand}
-            empty-state-message={emptyStateMessage}
-        >
-            <slot name="sidebar-header" slot="version-picker"></slot>
-        </dx-sidebar-old>
-        <div class="content-body-doc-phase-container">
-            <div class="doc-phase-wrapper">
-                <slot name="doc-phase"></slot>
+    <div class={contentClass}>
+        <template lwc:if={showLocaleBannerAbove}>
+            <div class="locale-notification-wrapper">
+                <slot name="locale-banner"></slot>
             </div>
-            <div class="version-wrapper">
-                <slot name="version-banner"></slot>
-            </div>
-            <div class="content-body-container">
-                <div class="content-body">
-                    <div class="breadcrumb-row" lwc:if={showBreadcrumbs}>
-                        <doc-breadcrumbs
-                            breadcrumbs={breadcrumbs}
-                        ></doc-breadcrumbs>
+        </template>
+        <div class="content-columns">
+            <dx-sidebar-old
+                class="is-sticky left-nav-bar"
+                trees={sidebarContent}
+                value={sidebarValue}
+                header={sidebarHeader}
+                ontogglesidebar={onToggleSidebar}
+                languages={languages}
+                language={language}
+                bail-href={bailHref}
+                bail-label={bailLabel}
+                dev-center={devCenter}
+                brand={brand}
+                empty-state-message={emptyStateMessage}
+            >
+                <slot name="sidebar-header" slot="version-picker"></slot>
+            </dx-sidebar-old>
+            <div class="content-body-doc-phase-container">
+                <template lwc:if={showLocaleBannerInColumn}>
+                    <div class="locale-notification-wrapper">
+                        <slot name="locale-banner"></slot>
                     </div>
-                    <div class="read" lwc:if={showReadingTime}>
-                        <svg
-                            xmlns="http://www.w3.org/2000/svg"
-                            width="18"
-                            height="18"
-                            viewBox="0 0 52 52"
-                        >
-                            <g fill="#3e3e3c">
-                                <path
-                                    d="m26 2c-13.2 0-24 10.8-24 24s10.8 24 24 24 24-10.8 24-24-10.8-24-24-24z m0 42c-9.9 0-18-8.1-18-18s8.1-18 18-18 18 8.1 18 18-8.1 18-18 18z m3.4-17.8c-0.3-0.3-0.4-0.7-0.4-1.1v-9.6c0-0.8-0.7-1.5-1.5-1.5h-3c-0.8 0-1.5 0.7-1.5 1.5v12.1c0 0.4 0.2 0.8 0.4 1.1l7.4 7.4c0.6 0.6 1.5 0.6 2.1 0l2.1-2.1c0.6-0.6 0.6-1.5 0-2.1l-5.6-5.7z"
-                                ></path>
-                            </g>
-                        </svg>
-                        {readingTime} minute read
+                </template>
+                <div class="doc-phase-wrapper">
+                    <slot name="doc-phase"></slot>
+                </div>
+                <div class="version-wrapper">
+                    <slot name="version-banner"></slot>
+                </div>
+                <div class="content-body-container">
+                    <div class="content-body">
+                        <div class="breadcrumb-row" lwc:if={showBreadcrumbs}>
+                            <doc-breadcrumbs
+                                breadcrumbs={breadcrumbs}
+                            ></doc-breadcrumbs>
+                        </div>
+                        <div class="read" lwc:if={showReadingTime}>
+                            <svg
+                                xmlns="http://www.w3.org/2000/svg"
+                                width="18"
+                                height="18"
+                                viewBox="0 0 52 52"
+                            >
+                                <g fill="#3e3e3c">
+                                    <path
+                                        d="m26 2c-13.2 0-24 10.8-24 24s10.8 24 24 24 24-10.8 24-24-10.8-24-24-24z m0 42c-9.9 0-18-8.1-18-18s8.1-18 18-18 18 8.1 18 18-8.1 18-18 18z m3.4-17.8c-0.3-0.3-0.4-0.7-0.4-1.1v-9.6c0-0.8-0.7-1.5-1.5-1.5h-3c-0.8 0-1.5 0.7-1.5 1.5v12.1c0 0.4 0.2 0.8 0.4 1.1l7.4 7.4c0.6 0.6 1.5 0.6 2.1 0l2.1-2.1c0.6-0.6 0.6-1.5 0-2.1l-5.6-5.7z"
+                                    ></path>
+                                </g>
+                            </svg>
+                            {readingTime} minute read
+                        </div>
+                        <div class="share-below-read" lwc:if={showSocialShare}>
+                            <doc-social-share
+                                title={shareTitle}
+                                url={shareUrl}
+                                twitter-via={shareTwitterVia}
+                            ></doc-social-share>
+                        </div>
+                        <slot onslotchange={onSlotChange}></slot>
+                        <doc-sprig-survey
+                            lwc:if={shouldDisplayFeedback}
+                        ></doc-sprig-survey>
                     </div>
-                    <div class="share-below-read" lwc:if={showSocialShare}>
-                        <doc-social-share
-                            title={shareTitle}
-                            url={shareUrl}
-                            twitter-via={shareTwitterVia}
-                        ></doc-social-share>
+                    <div lwc:if={showToc} class="right-nav-bar is-sticky">
+                        <dx-toc
+                            header={tocTitle}
+                            options={tocOptions}
+                            value={tocValue}
+                        ></dx-toc>
                     </div>
-                    <slot onslotchange={onSlotChange}></slot>
-                    <doc-sprig-survey
-                        lwc:if={shouldDisplayFeedback}
-                    ></doc-sprig-survey>
                 </div>
-                <div lwc:if={showToc} class="right-nav-bar is-sticky">
-                    <dx-toc
-                        header={tocTitle}
-                        options={tocOptions}
-                        value={tocValue}
-                    ></dx-toc>
+                <div lwc:if={showFooter} class="footer-container">
+                    <dx-footer
+                        variant="no-signup"
+                        mfe-config-origin={effectiveFooterOrigin}
+                    ></dx-footer>
                 </div>
             </div>
-            <div lwc:if={showFooter} class="footer-container">
-                <dx-footer
-                    variant="no-signup"
-                    mfe-config-origin={effectiveFooterOrigin}
-                ></dx-footer>
-            </div>
         </div>
     </div>
 </template>

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

@@ -42,6 +42,8 @@ export default class ContentLayout extends LightningElement {
     @api brand: any;
     @api emptyStateMessage?: string;
 
+    @api showLocaleBannerAbove = false;
+
     // This is needed for now to prevent failing snapshot tests due to links in the footer
     @api
     get showFooter() {
@@ -124,6 +126,16 @@ export default class ContentLayout extends LightningElement {
     protected contentLoaded: boolean = false;
     protected sidebarOpen: boolean = false;
 
+    get contentClass() {
+        return this.showLocaleBannerAbove
+            ? "content content-banner-above"
+            : "content";
+    }
+
+    get showLocaleBannerInColumn() {
+        return !this.showLocaleBannerAbove;
+    }
+
     get shouldDisplayFeedback() {
         return this.contentLoaded && typeof Sprig !== "undefined";
     }

package/src/modules/doc/redocReference/redocReference.ts

@@ -291,11 +291,7 @@ export default class RedocReference extends LightningElement {
                 this.insertDocPhase(apiContentDiv, docPhaseInfo);
             }
 
-            if (typeof Sprig !== "undefined") {
-                this.insertSprigSurvey(apiContentDiv);
-            }
-
-            this.insertFooter(apiContentDiv);
+            this.appendFooterItems(apiContentDiv);
 
             // Wait for footer to be rendered before updating styles
             requestAnimationFrame(() => {
@@ -358,6 +354,16 @@ export default class RedocReference extends LightningElement {
         wrapper.appendChild(feedbackElement);
     }
 
+    private appendFooterItems(parent: HTMLElement): void {
+        const container = document.createElement("div");
+        container.className = "appended-footer-container";
+        if (typeof Sprig !== "undefined") {
+            this.insertSprigSurvey(container);
+        }
+        this.insertFooter(container);
+        parent.appendChild(container);
+    }
+
     // Adjusts third column bottom position to prevent footer overlap
     private updateRedocThirdColumnStyle(redocContainer: HTMLElement): void {
         const footer = redocContainer.querySelector(

package/src/modules/doc/xmlContent/xmlContent.html

@@ -14,7 +14,20 @@
         show-footer={enableFooter}
         reading-time={computedReadingTime}
         origin={origin}
+        show-locale-banner-above={showLocaleBannerInSlot}
     >
+        <doc-banner
+            slot="locale-banner"
+            lwc:if={showLocaleBannerInSlot}
+            message-text="This text was translated using Salesforce's machine translation system. More details can be found "
+            message-link-url="https://help.salesforce.com/s/articleView?id=sf.machine_translation.htm"
+            message-link-text="here"
+            button-label="Switch to English"
+            button-href={localeBannerEnUsHref}
+            secondary-label="Not Now"
+            show-close-button="true"
+            dismiss-storage-key={deliverable}
+        ></doc-banner>
         <doc-phase
             slot="version-banner"
             lwc:if={showVersionBanner}

package/src/modules/doc/xmlContent/xmlContent.ts

@@ -48,6 +48,9 @@ export default class DocXmlContent extends LightningElementWithState<{
     /** Optional origin URL for the footer MFE (e.g. wp-json endpoint). Passed through to dx-footer-mfe. */
     @api origin: string | null = null;
 
+    /** Optional base URL for the canonical link (e.g. https://developer.salesforce.com). When set, used instead of window.location for the canonical href. */
+    @api baseUrl: string | null = null;
+
     @api
     get allLanguages(): Array<Language> {
         return this._allLanguages;
@@ -251,6 +254,39 @@ export default class DocXmlContent extends LightningElementWithState<{
         return this.pageReference.deliverable;
     }
 
+    private get showLocaleBannerInSlot(): boolean {
+        return this.shouldShowLocaleBanner;
+    }
+
+    private get shouldShowLocaleBanner(): boolean {
+        if (!this.pageReference?.deliverable) {
+            return false;
+        }
+        if (!this.language || this.language.id === "en-us") {
+            return false;
+        }
+        const hasEnUs = this.availableLanguages?.some(
+            (lang: DocLanguage) => lang.id === "en-us"
+        );
+        return !!hasEnUs;
+    }
+
+    private get localeBannerEnUsHref(): string {
+        if (!this.pageReference) {
+            return "";
+        }
+        const enUsLanguage = this.availableLanguages?.find(
+            (lang: DocLanguage) => lang.id === "en-us"
+        );
+        if (!enUsLanguage) {
+            return "";
+        }
+        return this.pageReferenceToString({
+            ...this.pageReference,
+            docId: enUsLanguage.url
+        });
+    }
+
     private get useOldSidebar(): boolean {
         // Coveo is enabled and the version is greater than  51 (within the latest 3 versions)
         // TODO: we need a better fix for version number check
@@ -766,21 +802,19 @@ export default class DocXmlContent extends LightningElementWithState<{
         }
 
         if (this.pageReference) {
-            const metadescription = document.querySelector(
+            const canonicalLink = document.querySelector(
                 'link[rel="canonical"]'
             );
-            if (metadescription) {
+            if (canonicalLink) {
                 const copyPageReference = { ...this.pageReference };
                 copyPageReference.docId = copyPageReference.docId
                     ? this.dropVersionFromDocId(copyPageReference.docId)
                     : copyPageReference.docId;
-                metadescription.setAttribute(
-                    "href",
-                    window.location.protocol +
-                        "//" +
-                        window.location.host +
-                        this.pageReferenceToString(copyPageReference)
-                );
+                const path = this.pageReferenceToString(copyPageReference);
+                const origin = this.baseUrl
+                    ? this.baseUrl.replace(/\/$/, "")
+                    : `${window.location.protocol}//${window.location.host}`;
+                canonicalLink.setAttribute("href", `${origin}${path}`);
             }
         }
 

package/src/modules/docHelpers/contentLayoutStyle/contentLayoutStyle.css

@@ -86,6 +86,21 @@ dx-toc {
     position: relative;
 }
 
+.content-banner-above {
+    flex-direction: column;
+}
+
+.locale-notification-wrapper {
+    flex-shrink: 0;
+    width: 100%;
+}
+
+.content-columns {
+    display: flex;
+    flex: 1;
+    min-width: 0;
+}
+
 .content-body-doc-phase-container {
     flex: 1;
     border-left: 1px solid var(--dx-g-gray-90);
@@ -125,7 +140,7 @@ dx-toc {
     max-width: 1000px;
     flex: 1;
     width: 0;
-    word-break: break-word;
+    overflow-wrap: break-word;
 }
 
 .is-sticky {