@salesforcedevs/docs-components 0.0.2-edit → 0.0.2-superscript

package/lwc.config.json

@@ -10,7 +10,6 @@
         "doc/componentPlayground",
         "doc/content",
         "doc/contentCallout",
-        "doc/chat",
         "doc/doDont",
         "doc/contentLayout",
         "doc/contentMedia",
@@ -21,7 +20,9 @@
         "doc/headingAnchor",
         "doc/overview",
         "doc/phase",
+        "doc/redocReference",
         "doc/specificationContent",
+        "doc/superscriptSubscript",
         "doc/versionPicker",
         "doc/xmlContent",
         "docUtils/utils"

package/package.json

@@ -1,29 +1,30 @@
 {
-    "name": "@salesforcedevs/docs-components",
-    "version": "0.0.2-edit",
-    "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": "4629fdd9ca18a13480044ad43515b91945d16aad"
-}
+  "name": "@salesforcedevs/docs-components",
+  "version": "0.0.2-superscript",
+  "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": "4629fdd9ca18a13480044ad43515b91945d16aad",
+  "stableVersion": "1.27.18"
+}

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}
@@ -16,10 +10,12 @@
         onexpandcollapse={onExpandCollapse}
         toc-title={tocTitle}
         toc-options={tocOptions}
+        toc-aria-level={tocAriaLevel}
         enable-slot-change="true"
         languages={languages}
         language={language}
         show-footer={enableFooter}
+        empty-state-message={emptyStateMessage}
     >
         <doc-phase
             slot="doc-phase"

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

@@ -4,7 +4,7 @@ import { sentenceCase } from "sentence-case";
 import qs from "query-string";
 import { AmfModelParser } from "doc/amfModelParser";
 import { normalizeBoolean, toJson } from "dxUtils/normalizers";
-import type { OptionWithLink } from "typings/custom";
+import type { OptionWithLink, Breadcrumb } from "typings/custom";
 import type {
     AmfConfig,
     AmfMetadataTopic,
@@ -28,7 +28,8 @@ import {
 } from "./constants";
 import { restoreScroll } from "dx/scrollManager";
 import { DocPhaseInfo } from "typings/custom";
-import { logCoveoPageView, oldVersionDocInfo } from "docUtils/utils";
+import { oldVersionDocInfo } from "docUtils/utils";
+import { track as trackEvent } from "dxUtils/analytics";
 
 type NavigationItem = {
     label: string;
@@ -41,20 +42,15 @@ 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 tocAriaLevel?: string;
     @api languages!: OptionWithLink[];
     @api language!: string;
     @api hideFooter = false;
     @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 +156,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();
@@ -967,6 +946,16 @@ export default class AmfReference extends LightningElement {
         this.handleSelectedItem();
 
         this.updateDocPhase();
+
+        // Track page view when a new spec reference page is loaded
+        trackEvent(this.template.host, "doc_page_view", {
+            page_path: window.location.pathname + window.location.search,
+            reference_id: referenceId,
+            reference_type: "spec",
+            meta: meta,
+            topic_type: type,
+            article_name: this.getArticleName()
+        });
     }
 
     /**
@@ -1328,6 +1317,15 @@ export default class AmfReference extends LightningElement {
             this.isVersionFetched = true;
             this.updateDocPhase();
             this.selectedSidebarValue = window.location.pathname;
+
+            // Track page view when a new markdown reference page is loaded
+            trackEvent(this.template.host, "doc_page_view", {
+                page_path: window.location.pathname + window.location.search,
+                reference_id: selectedItemRefId,
+                reference_type: "markdown",
+                topic_meta: referenceMeta,
+                article_name: this.getArticleName()
+            });
         }
     }
 
@@ -1436,10 +1434,6 @@ export default class AmfReference extends LightningElement {
                         metaVal
                     );
 
-                    logCoveoPageView(
-                        this.coveoOrganizationId,
-                        this.coveoAnalyticsToken
-                    );
                     this.updateUrlWithSelected(parentReferencePath, metaVal);
                     this.updateTags(metadata.navTitle);
                 } else {
@@ -1471,6 +1465,23 @@ export default class AmfReference extends LightningElement {
         }
     }
 
+    private getArticleName(): string | undefined {
+        if (!this.breadcrumbs) {
+            return undefined;
+        }
+        try {
+            const breadcrumbArray = toJson(this.breadcrumbs) as Breadcrumb[];
+            if (Array.isArray(breadcrumbArray) && breadcrumbArray.length > 0) {
+                // Join all breadcrumb labels with "/" to create article name
+                // e.g., "Tooling API Objects/FieldDefinition"
+                return breadcrumbArray.map((crumb) => crumb.label).join("/");
+            }
+        } catch (e) {
+            // If parsing fails, return undefined
+        }
+        return undefined;
+    }
+
     handleSelectedItem(): void {
         // update topic view
         const { referenceId, amfId, type } = this.selectedTopic!;

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/componentPlayground/componentPlayground.css

@@ -10,13 +10,21 @@
  * 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;
-    border-radius: var(--dx-g-spacing-sm);
-    border: 1px solid var(--dx-g-gray-90);
+    min-height: var(--playground-iframe-min-height);
+    max-height: var(--playground-iframe-max-height);
 }
 
-.container {
+.playground-container {
     position: relative;
 }

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

@@ -1,5 +1,5 @@
 <template>
-    <div class="container" lwc:if={playgroundAvailable}>
+    <div class="playground-container" lwc:if={playgroundAvailable}>
         <dx-spinner
             size="large"
             variant="brand"
@@ -8,13 +8,13 @@
         <iframe
             src={playgroundSrc}
             onload={handleIframeLoad}
-            title="Component Playground"
+            title={playgroundTitle}
             allow="clipboard-write"
         ></iframe>
     </div>
     <dx-error-fallback
         lwc:else
-        title="Playground Unavailable"
-        description="This component's playground is currently unavailable. Please check again later."
+        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

@@ -1,5 +1,8 @@
 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;
@@ -8,6 +11,19 @@ export default class ComponentPlayground extends LightningElement {
 
     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 &&
@@ -23,7 +39,59 @@ export default class ComponentPlayground extends LightningElement {
         }/${this.component.toLowerCase()}.html`;
     }
 
+    connectedCallback() {
+        window.addEventListener("message", this.handleIframeMessage);
+    }
+
+    disconnectedCallback() {
+        window.removeEventListener("message", this.handleIframeMessage);
+    }
+
     handleIframeLoad() {
-        this.isLoading = false;
+        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.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",

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,

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

@@ -1,68 +1,61 @@
 <template>
     <div class="content">
-        <template lwc:if={useOldSidebar}>
-            <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}
-            >
-                <slot name="sidebar-header" slot="version-picker"></slot>
-            </dx-sidebar-old>
-        </template>
-        <template lwc:else>
-            <dx-sidebar
-                class="is-sticky left-nav-bar"
-                trees={sidebarContent}
-                value={sidebarValue}
-                header={sidebarHeader}
-                coveo-organization-id={coveoOrganizationId}
-                coveo-public-access-token={coveoPublicAccessToken}
-                coveo-search-hub={coveoSearchHub}
-                coveo-advanced-query-config={coveoAdvancedQueryConfig}
-                ontogglesidebar={onToggleSidebar}
-                languages={languages}
-                language={language}
-                bail-href={bailHref}
-                bail-label={bailLabel}
-                dev-center={devCenter}
-                brand={brand}
-            >
-                <slot name="sidebar-header" slot="version-picker"></slot>
-            </dx-sidebar>
-        </template>
+        <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">
-            <slot name="doc-phase"></slot>
-            <slot name="version-banner"></slot>
+            <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">
-                        <doc-breadcrumbs
-                            lwc:if={showBreadcrumbs}
-                            breadcrumbs={breadcrumbs}
-                        ></doc-breadcrumbs>
-                        <slot onslotchange={onSlotChange}></slot>
-                        <doc-sprig-survey
-                            lwc:if={shouldDisplayFeedback}
-                        ></doc-sprig-survey>
-                        <doc-edit-file
-                            file-name="example.txt"
-                            title="Edit File"
-                        ></doc-edit-file>
-                    </div>
-                    <div lwc:if={showToc} class="right-nav-bar is-sticky">
-                        <dx-toc
-                            header={tocTitle}
-                            options={tocOptions}
-                            value={tocValue}
-                        ></dx-toc>
+                <div class="content-body">
+                    <doc-breadcrumbs
+                        lwc:if={showBreadcrumbs}
+                        breadcrumbs={breadcrumbs}
+                    ></doc-breadcrumbs>
+                    <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>
+                    <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>
             </div>
             <div lwc:if={showFooter} class="footer-container">
                 <dx-footer variant="no-signup"></dx-footer>