@salesforcedevs/docs-components 1.29.0-alpha1 → 1.29.0

package/LICENSE

@@ -0,0 +1,12 @@
+Copyright (c) 2020, Salesforce.com, Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+* Neither the name of Salesforce.com nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/lwc.config.json

@@ -5,8 +5,9 @@
         { "npm": "@salesforcedevs/dw-components" }
     ],
     "expose": [
-        "doc/apiPlayground",
         "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.29.0-alpha1",
-  "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"
-  },
-  "stableVersion": "1.29.0-alpha1"
-}
+    "name": "@salesforcedevs/docs-components",
+    "version": "1.29.0",
+    "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": "0dce435f5845187b50577dc005de80ddc3002b9d"
+}

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 {
@@ -204,6 +205,7 @@ export default class AmfReference extends LightningElement {
 
     _boundOnApiNavigationChanged;
     _boundUpdateSelectedItemFromUrlQuery;
+    _boundOnPageShow;
 
     constructor() {
         super();
@@ -212,6 +214,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 +226,7 @@ export default class AmfReference extends LightningElement {
             "popstate",
             this._boundUpdateSelectedItemFromUrlQuery
         );
+        window.addEventListener("pageshow", this._boundOnPageShow);
     }
 
     disconnectedCallback(): void {
@@ -234,6 +238,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 +463,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 +498,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>

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

@@ -0,0 +1,73 @@
+import { LightningElement, api } from "lwc";
+
+const BANNER_STORAGE_PREFIX = "doc-banner-";
+
+export default class Banner extends LightningElement {
+    @api message = "";
+
+    @api buttonLabel = "";
+
+    @api buttonHref = "";
+
+    @api secondaryLabel = "";
+
+    @api dismissStorageKey = "";
+
+    private _dismissed = false;
+
+    connectedCallback() {
+        if (this.dismissStorageKey && window?.sessionStorage) {
+            this._dismissed =
+                window.sessionStorage.getItem(
+                    `${BANNER_STORAGE_PREFIX}${this.dismissStorageKey}`
+                ) === "true";
+        }
+    }
+
+    renderedCallback() {
+        if (this.message) {
+            const messageElement = this.template.querySelector(".message");
+            if (messageElement) {
+                messageElement.innerHTML = this.message;
+            }
+        }
+    }
+
+    get showBanner(): boolean {
+        return !this._dismissed;
+    }
+
+    get hasPrimaryButton(): boolean {
+        return !!(this.buttonLabel && this.buttonHref);
+    }
+
+    get hasSecondaryAction(): boolean {
+        return !!this.secondaryLabel;
+    }
+
+    private dismissBanner() {
+        if (this.dismissStorageKey && window?.sessionStorage) {
+            window.sessionStorage.setItem(
+                `${BANNER_STORAGE_PREFIX}${this.dismissStorageKey}`,
+                "true"
+            );
+        }
+        this._dismissed = true;
+        this.dispatchEvent(
+            new CustomEvent("dismissbanner", {
+                bubbles: true,
+                composed: true
+            })
+        );
+    }
+
+    @api
+    handleSecondaryClick() {
+        this.dismissBanner();
+    }
+
+    @api
+    handleCloseClick() {
+        this.dismissBanner();
+    }
+}

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

@@ -43,7 +43,7 @@
                                 ></path>
                             </g>
                         </svg>
-                        {readingTime} minute read
+                        {readingTimeLabel}
                     </div>
                     <div class="share-below-read" lwc:if={showSocialShare}>
                         <doc-social-share

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

@@ -28,6 +28,35 @@ const HIGHLIGHTABLE_SELECTOR = [
 ].join(",");
 export const OBSERVER_ATTACH_WAIT_TIME = 500;
 
+const DEFAULT_READING_TIME_LOCALE = "en-us";
+
+/**
+ * Localized "minute read" templates. `{minutes}` is replaced with the rounded
+ * reading-time value. Only displayed when reading time is greater than 1, so
+ * plural forms are always appropriate. Keys match the locales declared in
+ * sfdocs (and the doc-locale-banner) so that a localized document automatically
+ * gets a localized reading-time label.
+ */
+export const READING_TIME_LABELS: Record<string, string> = {
+    "en-us": "{minutes} minute read",
+    "ja-jp": "読了時間 {minutes} 分",
+    "zh-cn": "阅读时间 {minutes} 分钟",
+    "zh-tw": "閱讀時間 {minutes} 分鐘",
+    "fr-fr": "Lecture de {minutes} minutes",
+    "de-de": "{minutes} Minuten Lesezeit",
+    "it-it": "{minutes} minuti di lettura",
+    "ko-kr": "읽는 데 {minutes}분",
+    "pt-br": "{minutes} minutos de leitura",
+    "es-mx": "{minutes} minutos de lectura",
+    "es-es": "{minutes} minutos de lectura",
+    "ru-ru": "Время чтения: {minutes} мин",
+    "fi-fi": "{minutes} minuutin lukuaika",
+    "da-dk": "{minutes} minutters læsning",
+    "sv-se": "{minutes} minuters läsning",
+    "nl-nl": "{minutes} minuten leestijd",
+    "nb-no": "{minutes} minutters lesetid"
+};
+
 export default class ContentLayout extends LightningElement {
     @api sidebarValue!: string;
     @api sidebarHeader!: string;
@@ -173,6 +202,19 @@ export default class ContentLayout extends LightningElement {
         return this.readingTime != null && this.readingTime > 1;
     }
 
+    /**
+     * Localized "X minute read" string for the current document language.
+     * Falls back to the default (en-us) template when the language is missing
+     * or has no translation.
+     */
+    get readingTimeLabel(): string {
+        const localeKey = (this.language || "").toLowerCase();
+        const template =
+            READING_TIME_LABELS[localeKey] ||
+            READING_TIME_LABELS[DEFAULT_READING_TIME_LOCALE];
+        return template.replace("{minutes}", String(this.readingTime));
+    }
+
     /** When origin is provided, pass it to the footer; otherwise use dx-footer's default. */
     get effectiveFooterOrigin(): string {
         return (

package/src/modules/doc/header/header.html

@@ -13,7 +13,6 @@
                         onclick={onLinkClick}
                         class="dev-center-content"
                     >
-                        <dx-icon symbol="back"></dx-icon>
                         <dx-icon
                             class="brand-icon"
                             lwc:if={devCenter.icon}

package/src/modules/doc/localeBanner/localeBanner.css

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

package/src/modules/doc/localeBanner/localeBanner.html

@@ -0,0 +1,9 @@
+<template>
+    <doc-banner
+        message={bannerMessage}
+        button-label={bannerButtonLabel}
+        button-href={bannerButtonHref}
+        secondary-label={bannerSecondaryLabel}
+        dismiss-storage-key={dismissStorageKey}
+    ></doc-banner>
+</template>