@salesforcedevs/docs-components 0.7.59-sppage-alpha1 → 0.7.76-alpha

package/lwc.config.json

@@ -7,17 +7,20 @@
     "expose": [
         "doc/amfReference",
         "doc/breadcrumbs",
+        "doc/componentPlayground",
         "doc/content",
         "doc/contentCallout",
         "doc/doDont",
         "doc/contentLayout",
         "doc/contentMedia",
         "doc/docXmlContent",
+        "doc/lwcContentLayout",
         "doc/header",
         "doc/heading",
         "doc/headingAnchor",
         "doc/overview",
         "doc/phase",
+        "doc/redocReference",
         "doc/specificationContent",
         "doc/versionPicker",
         "doc/xmlContent",

package/package.json

@@ -1,18 +1,19 @@
 {
     "name": "@salesforcedevs/docs-components",
-    "version": "0.7.59-sppage-alpha1",
+    "version": "0.7.76-alpha",
     "description": "Docs Lightning web components for DSC",
     "license": "MIT",
     "main": "index.js",
     "engines": {
-        "node": ">= 14.x"
+        "node": "20.x"
     },
     "publishConfig": {
         "access": "public"
     },
     "dependencies": {
-        "@api-components/amf-helper-mixin": "4.5.24",
+        "@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",
@@ -24,5 +25,9 @@
         "@types/lodash.orderby": "4.6.9",
         "@types/lodash.uniqby": "4.7.9"
     },
-    "gitHead": "4629fdd9ca18a13480044ad43515b91945d16aad"
+    "gitHead": "4629fdd9ca18a13480044ad43515b91945d16aad",
+    "volta": {
+        "node": "20.19.0",
+        "yarn": "1.22.19"
+    }
 }

package/src/modules/doc/amfReference/amfReference.css

@@ -1,10 +1,3 @@
-doc-phase {
-    --doc-c-phase-top: calc(
-        var(--dx-g-global-header-height) + var(--dx-g-doc-header-height) +
-            var(--dx-g-spacing-xl)
-    );
-}
-
 /* We need to apply some borders when there are two doc phases */
 doc-phase:not(:only-of-type)::part(container) {
     border-top: 1px solid var(--dx-g-yellow-vibrant-90);
@@ -15,11 +8,6 @@ doc-phase:nth-child(2)::part(container) {
     border-bottom: 1px solid var(--dx-g-yellow-vibrant-90);
 }
 
-/* We don't want second component to sticky as we need to handle different cases like position */
-doc-phase:nth-child(2) {
-    position: static;
-}
-
 .api-documentation {
     margin-top: 48px;
 }

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

@@ -1,13 +1,7 @@
 <template>
     <doc-content-layout
         lwc:if={isVersionFetched}
-        use-old-sidebar={useOldSidebar}
         class="content-type content-type-reference"
-        coveo-organization-id={coveoOrganizationId}
-        coveo-public-access-token={coveoPublicAccessToken}
-        coveo-analytics-token={coveoAnalyticsToken}
-        coveo-search-hub={coveoSearchHub}
-        coveo-advanced-query-config={coveoAdvancedQueryConfig}
         breadcrumbs={breadcrumbs}
         sidebar-header={sidebarHeader}
         sidebar-value={selectedSidebarValue}
@@ -20,6 +14,7 @@
         languages={languages}
         language={language}
         show-footer={enableFooter}
+        empty-state-message={emptyStateMessage}
     >
         <doc-phase
             slot="doc-phase"

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

@@ -3,7 +3,7 @@ import { noCase } from "no-case";
 import { sentenceCase } from "sentence-case";
 import qs from "query-string";
 import { AmfModelParser } from "doc/amfModelParser";
-import { normalizeBoolean, toJson } from "dxUtils/normalizers";
+import { normalizeBoolean } from "dxUtils/normalizers";
 import type { OptionWithLink } from "typings/custom";
 import type {
     AmfConfig,
@@ -28,7 +28,7 @@ import {
 } from "./constants";
 import { restoreScroll } from "dx/scrollManager";
 import { DocPhaseInfo } from "typings/custom";
-import { logCoveoPageView, oldVersionDocInfo } from "docUtils/utils";
+import { oldVersionDocInfo } from "docUtils/utils";
 
 type NavigationItem = {
     label: string;
@@ -41,11 +41,6 @@ type NavigationItem = {
 export default class AmfReference extends LightningElement {
     @api breadcrumbs: string | null = null;
     @api sidebarHeader!: string;
-    @api coveoOrganizationId!: string;
-    @api coveoPublicAccessToken!: string;
-    @api coveoAnalyticsToken!: string;
-    @api coveoSearchHub!: string;
-    @api useOldSidebar: boolean = false;
     @api tocTitle?: string;
     @api tocOptions?: string;
     @api languages!: OptionWithLink[];
@@ -54,7 +49,6 @@ export default class AmfReference extends LightningElement {
     @track navigation = [] as NavigationItem[];
     @track versions: Array<ReferenceVersion> = [];
     @track showVersionBanner = false;
-    @track _coveoAdvancedQueryConfig!: { [key: string]: any };
 
     // Update this to update what component gets rendered in the content block
     @track
@@ -160,35 +154,18 @@ export default class AmfReference extends LightningElement {
         this._expandChildren = normalizeBoolean(value);
     }
 
-    /*
-     * The get coveoAdvancedQueryConfig() method returns this._coveoAdvancedQueryConfig,
-     * but before returning it, it checks if there are multiple versions (this.versions.length > 1)
-     * and if a version is selected (this.selectedVersion). If both conditions are met,
-     * it updates the version property of this._coveoAdvancedQueryConfig with the selected version.
-     */
-    @api
-    get coveoAdvancedQueryConfig(): { [key: string]: any } {
-        const coveoConfig = this._coveoAdvancedQueryConfig;
-        if (this.versions.length > 1 && this.selectedVersion) {
-            const currentGAVersionRef = this.versions[0];
-            if (this.selectedVersion.id !== currentGAVersionRef.id) {
-                // Currently Coveo only supports query without "v"
-                const version = this.selectedVersion.id.replace("v", "");
-                coveoConfig.version = version;
-                this._coveoAdvancedQueryConfig = coveoConfig;
-            }
-        }
-        return this._coveoAdvancedQueryConfig;
-    }
-
-    set coveoAdvancedQueryConfig(config) {
-        this._coveoAdvancedQueryConfig = toJson(config);
-    }
-
     private get enableFooter(): boolean {
         return !this.hideFooter;
     }
 
+    private get emptyStateMessage(): string {
+        return JSON.stringify([
+            "Select a relevant API specification",
+            "Please consider misspellings",
+            "Try different search keywords"
+        ]);
+    }
+
     // model
     protected _amfConfigList: AmfConfig[] = [];
     protected _amfConfigMap: Map<string, AmfConfig> = new Map();
@@ -1436,10 +1413,6 @@ export default class AmfReference extends LightningElement {
                         metaVal
                     );
 
-                    logCoveoPageView(
-                        this.coveoOrganizationId,
-                        this.coveoAnalyticsToken
-                    );
                     this.updateUrlWithSelected(parentReferencePath, metaVal);
                     this.updateTags(metadata.navTitle);
                 } else {

package/src/modules/doc/amfTopic/amfTopic.ts

@@ -9,6 +9,7 @@ import {
 } from "./utils";
 import type { TopicModel } from "./types";
 import { Json } from "typings/custom";
+import { buildDocLinkClickHandler } from "dxUtils/analytics";
 
 const TABLE_SIZE_MATCH = "769px";
 
@@ -16,6 +17,15 @@ export default class AmfTopic extends LightningElement {
     private _model: TopicModel | undefined;
     private amf: Json;
     private type: string | undefined;
+    private handleLinkClick = buildDocLinkClickHandler();
+
+    disconnectedCallback(): void {
+        // Remove link click handler
+        const container = this.template.querySelector(".topic-container");
+        if (container) {
+            container.removeEventListener("click", this.handleLinkClick);
+        }
+    }
 
     @api
     get model(): TopicModel | undefined {
@@ -92,6 +102,15 @@ export default class AmfTopic extends LightningElement {
         }
         container?.appendChild(element as Node);
 
+        // Add click handler for all links in the dynamically loaded content
+        if (container) {
+            if (this.isLinkTrackingHandledByAncestor()) {
+                container.removeEventListener("click", this.handleLinkClick);
+            } else {
+                container.addEventListener("click", this.handleLinkClick);
+            }
+        }
+
         const isTabletOrDesktop = window.matchMedia(
             `(min-width: ${TABLE_SIZE_MATCH})`
         ).matches;
@@ -108,4 +127,9 @@ export default class AmfTopic extends LightningElement {
             console.error(error);
         }
     }
+
+    private isLinkTrackingHandledByAncestor(): boolean {
+        const host = this.template.host as HTMLElement | undefined;
+        return !!host?.closest?.("doc-content-layout");
+    }
 }

package/src/modules/doc/breadcrumbs/breadcrumbs.html

@@ -11,7 +11,6 @@
                 <template if:true={renderDropdown}>
                     <dx-dropdown
                         analytics-event="custEv_breadcrumbClick"
-                        analytics-payload={ANALYTICS_PAYLOAD}
                         if:true={renderDropdown}
                         options={dropdownOptions}
                         open-on-hover

package/src/modules/doc/breadcrumbs/breadcrumbs.ts

@@ -28,8 +28,8 @@ export default class Breadcrumbs extends LightningElement {
     set breadcrumbs(value) {
         this.normalizeAndAssignBreadcrumbs(value);
         this.calculateBreadcrumbsConfigs();
-        if (this.observer) {
-            this.updateDropdownOptionAmount();
+        if (this.isRendered) {
+            this.onWidthOrContentChange();
         }
     }
 
@@ -45,9 +45,9 @@ export default class Breadcrumbs extends LightningElement {
     private _breadcrumbs: Breadcrumb[] = [];
     private _pixelPerCharacter = CONSTANTS.pixelPerCharacter;
     private navWidth = 0;
-    private observer: ResizeObserver | null = null;
     private breadcrumbConfigs: BreadcrumbConfig[] = [];
     private dropdownOptionAmount? = 0;
+    private isRendered = false;
 
     private get renderSmallVariant(): boolean {
         return (
@@ -110,30 +110,21 @@ export default class Breadcrumbs extends LightningElement {
         };
     }
 
+    private onWidthOrContentChange = () => {
+        this.navWidth = this.template
+            .querySelector("nav")!
+            .getBoundingClientRect().width;
+        this.updateDropdownOptionAmount();
+    };
+
     renderedCallback(): void {
-        if (!this.observer) {
-            try {
-                this.observer = new ResizeObserver((entries) => {
-                    const [nav] = entries;
-                    if (this.navWidth === nav.contentRect.width) {
-                        return;
-                    }
-                    this.navWidth = nav.contentRect.width;
-                    this.updateDropdownOptionAmount();
-                });
-
-                this.observer.observe(this.template.querySelector("nav")!);
-            } catch (error) {
-                console.error(
-                    "Error occured while setting up ResizeObserver on breadcrumbs",
-                    error
-                );
-            }
-        }
+        this.isRendered = true;
+        this.onWidthOrContentChange();
+        window.addEventListener("resize", this.onWidthOrContentChange);
     }
 
     disconnectedCallback(): void {
-        this.observer?.disconnect();
+        window.removeEventListener("resize", this.onWidthOrContentChange);
     }
 
     private normalizeAndAssignBreadcrumbs(breadcrumbs?: Breadcrumb[] | string) {

package/src/modules/doc/componentPlayground/componentPlayground.css

@@ -0,0 +1,30 @@
+@import "dxHelpers/reset";
+
+/**
+ * Designs link - https://www.figma.com/design/9SalRPlJmtRDZHq03o8dL1/One-Doc-Site-Visionary-Mocks?node-id=9968-366397&m=dev
+ * Preview padding: 24px
+ * Example Selector height: 122px
+ * Example Preview min height: 150px
+ * Tab height with border: 46px(45px height and 1px border)
+ * Codeblock height: 264px(224px for codeblock and 40px for panel)
+ * Total: 606px
+**/
+
+:host {
+    --playground-iframe-min-height: 500px;
+    --playground-iframe-max-height: 5000px;
+
+    margin-top: var(--dx-g-spacing-md) !important;
+    display: block !important;
+}
+
+iframe {
+    width: 100%;
+    height: 606px;
+    min-height: var(--playground-iframe-min-height);
+    max-height: var(--playground-iframe-max-height);
+}
+
+.playground-container {
+    position: relative;
+}

package/src/modules/doc/componentPlayground/componentPlayground.html

@@ -0,0 +1,20 @@
+<template>
+    <div class="playground-container" lwc:if={playgroundAvailable}>
+        <dx-spinner
+            size="large"
+            variant="brand"
+            if:true={isLoading}
+        ></dx-spinner>
+        <iframe
+            src={playgroundSrc}
+            onload={handleIframeLoad}
+            title={playgroundTitle}
+            allow="clipboard-write"
+        ></iframe>
+    </div>
+    <dx-error-fallback
+        lwc:else
+        title="Code Examples Unavailable"
+        description="This component's code examples are currently unavailable. Please check again later."
+    ></dx-error-fallback>
+</template>

package/src/modules/doc/componentPlayground/componentPlayground.ts

@@ -0,0 +1,97 @@
+import { LightningElement, api } from "lwc";
+
+const PLAYGROUND_HEIGHT_MESSAGE = "PLAYGROUND_HEIGHT_CHANGE";
+const LOADER_TIMEOUT_MS = 2000;
+
+export default class ComponentPlayground extends LightningElement {
+    @api model!: string;
+    @api namespace!: string;
+    @api component!: string;
+    @api playgroundAppUrl!: string;
+
+    isLoading = true;
+
+    /**
+     * Returns a formatted title for the component playground
+     * Maps 'aura' model to 'Aura' and 'lwc' model to 'Lightning'
+     * Capitalizes the first letter of the component name
+     * @returns {string} Formatted playground title
+     */
+    get playgroundTitle() {
+        const modelName = this.model === "aura" ? "Aura" : "Lightning";
+        const componentName =
+            this.component.charAt(0).toUpperCase() + this.component.slice(1);
+        return `Example previews and code for ${modelName} ${componentName} component`;
+    }
+
+    get playgroundAvailable() {
+        return (
+            this.playgroundAppUrl &&
+            this.model &&
+            this.namespace &&
+            this.component
+        );
+    }
+
+    get playgroundSrc(): string {
+        return `${this.playgroundAppUrl}/playground/${this.model}/${
+            this.namespace
+        }/${this.component.toLowerCase()}.html`;
+    }
+
+    connectedCallback() {
+        window.addEventListener("message", this.handleIframeMessage);
+    }
+
+    disconnectedCallback() {
+        window.removeEventListener("message", this.handleIframeMessage);
+    }
+
+    handleIframeLoad() {
+        if (!window.ResizeObserver) {
+            // If ResizeObserver not supported, hide loader immediately (no height messages will come)
+            this.isLoading = false;
+        } else {
+            // Hide loader after 2 seconds if no height messages received
+            // This handles cases where iframe fails to load, crashes, or height reporting fails
+            setTimeout(() => {
+                this.isLoading = false;
+            }, LOADER_TIMEOUT_MS);
+        }
+    }
+
+    handleIframeMessage = (event: MessageEvent) => {
+        // Only handle height change messages from our iframe
+        if (event.data?.type !== PLAYGROUND_HEIGHT_MESSAGE) {
+            return;
+        }
+
+        const iframe = this.template.querySelector(
+            "iframe"
+        ) as HTMLIFrameElement;
+        if (!iframe || event.source !== iframe.contentWindow) {
+            return;
+        }
+
+        const height = event.data?.height;
+        if (typeof height === "number" && height > 0) {
+            const minHeight = parseInt(
+                getComputedStyle(this.template.host).getPropertyValue(
+                    "--playground-iframe-min-height"
+                ),
+                10
+            );
+            const maxHeight = parseInt(
+                getComputedStyle(this.template.host).getPropertyValue(
+                    "--playground-iframe-max-height"
+                ),
+                10
+            );
+
+            const newHeight = Math.min(Math.max(height, minHeight), maxHeight);
+            iframe.style.height = `${newHeight}px`;
+            iframe.style.minHeight = `${newHeight}px`;
+            this.isLoading = false;
+        }
+    };
+}

package/src/modules/doc/content/content.html

@@ -1,4 +1,5 @@
 <template>
+    <dx-redirect-checker></dx-redirect-checker>
     <template if:true={docsData}>
         <div class="container" data-name="content" lwc:dom="manual"></div>
     </template>

package/src/modules/doc/content/content.ts

@@ -6,7 +6,6 @@ import Button from "dx/button";
 import { highlightTerms } from "dxUtils/highlight";
 import ContentCallout from "doc/contentCallout";
 import ContentMedia from "doc/contentMedia";
-
 const HIGHLIGHTABLE_SELECTOR = [
     "p",
     ".p",
@@ -43,26 +42,10 @@ export default class Content extends LightningElement {
         return this.docContent;
     }
 
-    @api
-    set codeBlockTheme(value) {
-        this._codeBlockTheme = value;
-    }
-
-    get codeBlockTheme() {
-        return this._codeBlockTheme;
-    }
-
     @track docContent: DocContent = "";
-    _codeBlockTheme: string = "dark";
     _docRendered: boolean = false;
-    originalCodeBlockThemeValue: String = "";
 
     connectedCallback() {
-        this.template.addEventListener(
-            "themechange",
-            this.updateTheme.bind(this) // eslint-disableline no-use-before-define
-        );
-
         window.addEventListener(
             "highlightedtermchange",
             this.updateHighlighted
@@ -76,15 +59,6 @@ export default class Content extends LightningElement {
         );
     }
 
-    updateTheme() {
-        this._codeBlockTheme =
-            this._codeBlockTheme === "dark" ? "light" : "dark";
-        const codeBlockEls = this.template.querySelectorAll("dx-code-block");
-        codeBlockEls.forEach((codeBlockEl) => {
-            codeBlockEl.setAttribute("theme", this._codeBlockTheme);
-        });
-    }
-
     renderPaginationButton(anchorEl: HTMLElement) {
         const isNext = anchorEl.textContent!.includes("Next →");
         anchorEl.innerHTML = "";
@@ -116,11 +90,11 @@ export default class Content extends LightningElement {
             const codeBlockEls = divEl.querySelectorAll(".codeSection");
             codeBlockEls.forEach((codeBlockEl) => {
                 codeBlockEl.setAttribute("lwc:dom", "manual");
-                const classList = (codeBlockEl.firstChild as any).classList;
+                const classList = codeBlockEl.firstElementChild?.classList;
                 let language = "";
-                for (const key in classList) {
-                    if (typeof classList[key] === "string") {
-                        const className = classList[key];
+                if (classList) {
+                    for (let i = 0; i < classList.length; i++) {
+                        const className = classList[i];
                         if (className.startsWith("brush:")) {
                             language = className.split(":")[1];
                         }
@@ -133,7 +107,6 @@ export default class Content extends LightningElement {
                     codeBlock: codeBlockEl.innerHTML,
                     // ! Hot fix for incoming html tags from couchdb for xml blocks, fix me soon please
                     language: LANGUAGE_MAP[language] || language,
-                    theme: this.codeBlockTheme,
                     header: "", // Default no title.
                     variant: this.codeBlockType,
                     isEncoded: true
@@ -158,6 +131,7 @@ export default class Content extends LightningElement {
                     }
                 });
 
+                // Set a flag to 1 (true) if and only if all detailEls have no content.
                 let flag = 1;
                 for (let i: number = 0; i < detailEls.length; i++) {
                     flag &= (detailEls[i].innerHTML.trim() === "") as any; // Dark Magic TM
@@ -359,7 +333,7 @@ export default class Content extends LightningElement {
         );
 
     @api
-    public navigateToHash(hash: String) {
+    public navigateToHash = (hash: String) => {
         const splitHash = hash.split("#");
         if (splitHash.length === 2) {
             hash = splitHash[1];
@@ -370,7 +344,7 @@ export default class Content extends LightningElement {
         } else {
             window.scrollTo({ top: 0, behavior: "smooth" });
         }
-    }
+    };
 
     renderedCallback() {
         if (this._docRendered) {

package/src/modules/doc/contentCallout/contentCallout.css

@@ -4,6 +4,7 @@
 
 .dx-callout {
     border-radius: 4px;
+    margin: var(--dx-g-spacing-md) 0;
 }
 
 .dx-callout-base,