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

package/src/modules/doc/specificationContent/specificationContent.ts

@@ -1,56 +1,166 @@
 import { LightningElement, track, api } from "lwc";
+import { Method, Specification } from "typings/custom";
+import debounce from "debounce";
 
+const CX_ROUTER_API: string = "/cx-router/components";
 export default class SpecificationContent extends LightningElement {
     @track data: any;
-    @api component: string = "button";
-    @api type: string = "lightning";
 
-    private attributes = [];
-    private methods = [];
-    private slots = [];
-    private events = [];
+    @api component!: string;
+    @api model!: string;
+    @api namespace!: string;
+
+    isLoading: boolean = true;
+    showError: boolean = false;
+
+    private attributes: Specification[] = [];
+    private methods: Method[] = [];
+    private slots: Specification[] = [];
+    private events: Specification[] = [];
+    private _processedEvents: Specification[] = [];
+
+    /* TODO: For now setting the timeout to 300ms,
+     * post integration with CX-Router API will test and change if required.
+     */
+    private debouncedNotifyDataRendered = debounce(() => {
+        this.notifySpecificationDataRendered();
+    }, 300);
 
     connectedCallback() {
-        this.fetchPropertiesData();
+        this.fetchComponentMetadata();
     }
 
-    async fetchPropertiesData() {
-        const url = `http://localhost:3002/get-properties?component=${this.component}&type=${this.type}`;
+    async fetchComponentMetadata() {
+        const componentQueryParams = {
+            model: this.model,
+            namespace: this.namespace,
+            component: this.component
+        };
+
+        const queryString = new URLSearchParams(
+            componentQueryParams
+        ).toString();
+        const url = `${CX_ROUTER_API}?${queryString}`;
 
         try {
             const response = await fetch(url);
 
             if (!response.ok) {
+                // TODO: Will add loader and show error as follow-up
                 throw new Error(`Failed to fetch: ${response.statusText}`);
             }
 
             const result = await response.json();
-            this.data = result;
-            ({
-                attributes: this.attributes,
-                methods: this.methods,
-                slots: this.slots,
-                events: this.events
-            } = this.data);
+
+            // Due to middleware the data is sent as part of response now.
+            this.data = result?.response;
+            if (this.data) {
+                ({
+                    attributes: this.attributes,
+                    methods: this.methods,
+                    slots: this.slots,
+                    events: this.events
+                } = this.data);
+
+                // Process events once when data is set
+                this._processedEvents = this.events
+                    ? this.events.map((event) => {
+                          const capitalizedName = event.name
+                              ? event.name.charAt(0).toUpperCase() +
+                                event.name.slice(1)
+                              : "";
+                          return {
+                              ...event,
+                              nameCapitalized: capitalizedName
+                          };
+                      })
+                    : [];
+            }
         } catch (error) {
             this.data = {};
-            console.error("fetchPropertiesData() failed for:" + url);
+            this.showError = true;
+            console.error("fetchComponentMetadata() failed:", error);
+        } finally {
+            this.isLoading = false;
         }
     }
 
+    /**
+     * This getter is to preprocess the methods for easier rendering in the template.
+     * Each method is augmented with additional properties:
+     * - `firstArgument`: The first argument (if any).
+     * - `remainingArguments`: All other arguments (if any).
+     * - `hasArguments`: A boolean indicating whether the method has arguments or not.
+     */
+    get processedMethods(): Method[] {
+        return this.methods.map((method) => {
+            const [firstArgument, ...remainingArguments] =
+                method.arguments || [];
+            return {
+                ...method,
+                firstArgument,
+                remainingArguments,
+                hasArguments: method.arguments && method.arguments.length > 0,
+                cssForMultipleArguments:
+                    remainingArguments.length > 0 ? "left-border" : ""
+            };
+        });
+    }
+
+    /**
+     * Returns the preprocessed events for easier rendering in the template.
+     * Each event is augmented with a capitalized name property that capitalizes the first letter
+     * while maintaining camelCase format.
+     */
+    get processedEvents(): Specification[] {
+        return this._processedEvents;
+    }
+
     get hasAttributes() {
-        return this.attributes;
+        return this.attributes?.length > 0;
     }
 
     get hasMethods() {
-        return this.methods;
+        return this.methods?.length > 0;
     }
 
     get hasSlots() {
-        return this.slots;
+        return this.slots?.length > 0;
     }
 
     get hasEvents() {
-        return this.events;
+        return this.events?.length > 0;
+    }
+
+    get showNoSpecifications() {
+        return (
+            !this.showError &&
+            !this.isLoading &&
+            !this.hasAttributes &&
+            !this.hasMethods &&
+            !this.hasSlots &&
+            !this.hasEvents
+        );
+    }
+
+    get isModelAura() {
+        return this.model === "aura";
+    }
+
+    renderedCallback(): void {
+        if (this.data) {
+            this.debouncedNotifyDataRendered();
+        }
+    }
+
+    notifySpecificationDataRendered() {
+        // Dispatch a custom event to notify the specification tab has rendered.
+        this.dispatchEvent(
+            new CustomEvent("specificationdatarendered", {
+                detail: { name: "doc-specification-content" },
+                bubbles: true,
+                composed: true
+            })
+        );
     }
 }

package/src/modules/doc/versionPicker/versionPicker.html

@@ -2,6 +2,8 @@
     <div lwc:if={showVersionPicker} class="version-picker-container">
         <dx-dropdown
             options={versions}
+            analytics-event="custEv_docVersionSelect"
+            analytics-payload={analyticsPayload}
             value={selectedVersion.id}
             width="var(--doc-version-picker-width)"
             onchange={onVersionChange}

package/src/modules/doc/xmlContent/xmlContent.css

@@ -31,10 +31,6 @@ dx-dropdown > dx-button:hover {
     --border-color: var(--button-primary-color-hover);
 }
 
-doc-phase {
-    --doc-c-phase-top: var(--dx-g-global-header-height);
-}
-
 @media screen and (max-width: 768px) {
     doc-content-layout {
         --dx-g-doc-header-main-nav-height: 41px;
@@ -45,10 +41,4 @@ doc-phase {
             var(--dx-g-global-header-height) + var(--dx-g-doc-header-height)
         );
     }
-
-    doc-phase {
-        --doc-c-phase-top: calc(
-            var(--dx-g-global-header-height) + var(--dx-g-doc-header-height)
-        );
-    }
 }

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

@@ -1,23 +1,18 @@
 <template>
     <doc-content-layout
-        lwc:if={loaded}
+        lwc:if={displayContent}
         lwc:ref="docContentLayout"
-        coveo-organization-id={coveoOrganizationId}
-        coveo-public-access-token={coveoPublicAccessToken}
-        coveo-analytics-token={coveoAnalyticsToken}
-        coveo-search-hub={coveoSearchHub}
-        coveo-advanced-query-config={coveoAdvancedQueryConfig}
         sidebar-header={docTitle}
         sidebar-content={sidebarContent}
         sidebar-value={sidebarValue}
         onselect={handleSelect}
-        use-old-sidebar={useOldSidebar}
         onlangchange={handleLanguageChange}
         languages={sidebarFooterContent.languages}
         language={sidebarFooterContent.language}
         bail-href={sidebarFooterContent.bailHref}
         bail-label={sidebarFooterContent.bailLabel}
         show-footer={enableFooter}
+        reading-time={computedReadingTime}
     >
         <doc-phase
             slot="version-banner"
@@ -30,7 +25,7 @@
         <div lwc:if={showVersionPicker} slot="sidebar-header">
             <doc-version-picker
                 data-type="version"
-                analytics-event="custEv_ctaLinkClick"
+                analytics-event="custEv_linkClick"
                 analytics-payload={ANALYTICS_PAYLOAD}
                 versions={versionOptions}
                 selected-version={version}
@@ -49,4 +44,12 @@
             onnavclick={handleNavClick}
         ></doc-content>
     </doc-content-layout>
+    <div lwc:if={display404}>
+        <dx-error
+            image="https://a.sfdcstatic.com/developer-website/prod/images/404.svg"
+            code="404"
+            header="Beep boop. That did not compute."
+            subtitle="The document you're looking for doesn't seem to exist."
+        ></dx-error>
+    </div>
 </template>

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

@@ -1,9 +1,7 @@
 /* eslint-disable @lwc/lwc/no-document-query */
 import { api, track } from "lwc";
-import { normalizeBoolean } from "dxUtils/normalizers";
 import { FetchContent } from "./utils";
 import {
-    CoveoAdvancedQueryXMLConfig,
     DocLanguage,
     DocVersion,
     TreeNode,
@@ -11,13 +9,15 @@ import {
     SiderbarFooter,
     HistoryState,
     PageReference,
-    TocMap
+    TocMap,
+    ContentData
 } from "./types";
 import { SearchSyncer } from "docUtils/searchSyncer";
 import { LightningElementWithState } from "dxBaseElements/lightningElementWithState";
-import { logCoveoPageView, oldVersionDocInfo } from "docUtils/utils";
+import { oldVersionDocInfo } from "docUtils/utils";
 import { Breadcrumb, DocPhaseInfo, Language } from "typings/custom";
 import { track as trackGTM } from "dxUtils/analytics";
+import DOMPurify from "dompurify";
 
 // TODO: Imitating from actual implementation as doc-content use it like this. We should refactor it later.
 const handleContentError = (error: any): void => console.log(error);
@@ -40,11 +40,8 @@ export default class DocXmlContent extends LightningElementWithState<{
     internalLinkClicked: boolean;
 }> {
     @api apiDomain = "https://developer.salesforce.com";
-    @api coveoOrganizationId!: string;
-    @api coveoPublicAccessToken!: string;
-    @api coveoAnalyticsToken!: string;
-    @api coveoSearchHub!: string;
     @api hideFooter = false;
+    @api displayReadingTime = false;
 
     @api
     get allLanguages(): Array<Language> {
@@ -57,21 +54,13 @@ export default class DocXmlContent extends LightningElementWithState<{
         }
     }
 
-    @api
-    get enableCoveo() {
-        return this._enableCoveo;
-    }
-
-    set enableCoveo(value) {
-        this._enableCoveo = normalizeBoolean(value);
-    }
-
     private availableLanguages: Array<DocLanguage> = [];
     @track private availableVersions: Array<DocVersion> = [];
     private contentProvider?: FetchContent;
     private docContent = "";
     private language?: DocLanguage | null = null;
-    private loaded = false;
+    private displayContent = false;
+    private display404 = false;
     private _pageHeader?: Header;
     private pdfUrl = "";
     private tocMap: TocMap = {};
@@ -80,7 +69,6 @@ export default class DocXmlContent extends LightningElementWithState<{
     private docTitle = "";
     private _pathName = "";
     private listenerAttached = false;
-    private _enableCoveo?: boolean = false;
     private sidebarFooterContent: SiderbarFooter = { ...defaultSidebarFooter };
     private latestVersion = false;
     private previewVersion = false;
@@ -89,6 +77,10 @@ export default class DocXmlContent extends LightningElementWithState<{
         return !this.hideFooter;
     }
 
+    private get computedReadingTime(): number | undefined {
+        return this.displayReadingTime ? this.readingTime : undefined;
+    }
+
     private searchSyncer = new SearchSyncer({
         callbacks: {
             onSearchChange: (nextSearchString: string): void => {
@@ -160,6 +152,7 @@ export default class DocXmlContent extends LightningElementWithState<{
 
     @track private pageReference: PageReference = {};
     @track breadcrumbs: Array<Breadcrumb> = [];
+    @track readingTime?: number;
 
     constructor() {
         super();
@@ -184,7 +177,13 @@ export default class DocXmlContent extends LightningElementWithState<{
             this.apiDomain,
             this.allLanguages
         );
-        this.fetchDocument().then(() => (this.loaded = true));
+        this.fetchDocument().then((content: any) => {
+            if (content) {
+                this.displayContent = true;
+            } else {
+                this.display404 = true;
+            }
+        });
         window.addEventListener("popstate", this.handlePopState);
 
         this.searchSyncer.init();
@@ -251,35 +250,13 @@ export default class DocXmlContent extends LightningElementWithState<{
         // 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
         return !(
-            this.enableCoveo &&
-            this.coveoOrganizationId &&
-            this.coveoPublicAccessToken &&
-            (!this.version?.releaseVersion ||
-                (this.version?.releaseVersion &&
-                    parseInt(
-                        this.version.releaseVersion.replace("v", ""),
-                        10
-                    ) >= 53))
+            !this.version?.releaseVersion ||
+            (this.version?.releaseVersion &&
+                parseInt(this.version.releaseVersion.replace("v", ""), 10) >=
+                    53)
         );
     }
 
-    private get coveoAdvancedQueryConfig(): CoveoAdvancedQueryXMLConfig {
-        const config: {
-            locale?: string;
-            topicid?: string;
-            version?: string;
-        } = {
-            locale: this.languageId,
-            topicid: this.deliverable
-        };
-
-        if (this.releaseVersionId && this.releaseVersionId !== "noversion") {
-            config.version = this.releaseVersionId;
-        }
-
-        return config;
-    }
-
     private get pageHeader(): Header {
         if (!this._pageHeader) {
             this._pageHeader = document.querySelector("doc-header")!;
@@ -384,7 +361,7 @@ export default class DocXmlContent extends LightningElementWithState<{
         );
         this.pageReference.docId = this.language!.url;
 
-        trackGTM(event.target!, "custEv_ctaLinkClick", {
+        trackGTM(event.target!, "custEv_linkClick", {
             click_text: event.detail,
             element_title: "language selector",
             click_url: `${window.location.origin}${this.pageReferenceToString(
@@ -425,9 +402,19 @@ export default class DocXmlContent extends LightningElementWithState<{
             .catch(handleContentError);
     }
 
+    private sanitizeUrlPart(part: string | undefined): string | undefined {
+        if (!part) {
+            return part;
+        }
+        return DOMPurify.sanitize(part);
+    }
+
     getReferenceFromUrl(): PageReference {
         const [page, docId, deliverable, contentDocumentId] =
-            window.location.pathname.substr(1).split("/");
+            window.location.pathname
+                .substr(1)
+                .split("/")
+                .map(this.sanitizeUrlPart);
 
         const { origin: domain, hash, search } = window.location;
 
@@ -436,9 +423,9 @@ export default class DocXmlContent extends LightningElementWithState<{
             deliverable,
             docId,
             domain,
-            hash,
+            hash: this.sanitizeUrlPart(hash),
             page,
-            search
+            search: this.sanitizeUrlPart(search)
         };
     }
 
@@ -452,10 +439,11 @@ export default class DocXmlContent extends LightningElementWithState<{
         );
     }
 
-    async fetchDocument(): Promise<void> {
+    async fetchDocument(): Promise<string> {
         this.setState({
             isFetchingDocument: true
         });
+
         const data = await this.contentProvider!.fetchDocumentData(
             this.pageReference.docId!
         );
@@ -465,7 +453,7 @@ export default class DocXmlContent extends LightningElementWithState<{
             this.setState({
                 isFetchingDocument: false
             });
-            return;
+            return "";
         }
 
         this.docTitle = data.docTitle;
@@ -497,11 +485,11 @@ export default class DocXmlContent extends LightningElementWithState<{
             data.id
         ) {
             try {
-                await this.fetchContent();
+                const moreData = await this.fetchContent();
                 this.setState({
                     isFetchingDocument: false
                 });
-                return;
+                return moreData.content;
             } catch (error) {
                 this.pageReference.contentDocumentId = `${data.id}.htm`;
                 this.pageReference.hash = "";
@@ -511,13 +499,15 @@ export default class DocXmlContent extends LightningElementWithState<{
         }
 
         this.docContent = data.content;
+        this.calculateReadingTime(data.content);
         this.addMetatags();
         this.setState({
             isFetchingDocument: false
         });
+        return data.content;
     }
 
-    async fetchContent(): Promise<void> {
+    async fetchContent(): Promise<ContentData> {
         this.setState({
             isFetchingContent: true
         });
@@ -532,6 +522,7 @@ export default class DocXmlContent extends LightningElementWithState<{
 
         if (data) {
             this.docContent = data.content;
+            this.calculateReadingTime(data.content);
             this.addMetatags();
 
             if (!this.pageReference.hash) {
@@ -541,6 +532,7 @@ export default class DocXmlContent extends LightningElementWithState<{
         this.setState({
             isFetchingContent: false
         });
+        return data;
     }
 
     updateHeaderAndSidebarFooter(): void {
@@ -567,7 +559,6 @@ export default class DocXmlContent extends LightningElementWithState<{
     }
 
     updateUrl(method = HistoryState.PUSH_STATE): void {
-        logCoveoPageView(this.coveoOrganizationId, this.coveoAnalyticsToken);
         window.history[method](
             {},
             "docs",
@@ -700,7 +691,7 @@ export default class DocXmlContent extends LightningElementWithState<{
 
     addMetatags(): void {
         const div = document.createElement("div");
-        div.innerHTML = this.docContent;
+        div.innerHTML = DOMPurify.sanitize(this.docContent);
         const docDescription = div.querySelector(".shortdesc")?.textContent;
         const topicTitle = div.querySelector("h1")?.textContent;
 
@@ -777,4 +768,32 @@ export default class DocXmlContent extends LightningElementWithState<{
     private get showVersionPicker(): boolean {
         return !this.disableVersion;
     }
+
+    private calculateReadingTime(content: string): void {
+        if (!this.displayReadingTime) {
+            this.readingTime = undefined;
+            return;
+        }
+
+        if (!content) {
+            this.readingTime = undefined;
+            return;
+        }
+
+        // Strip HTML tags and get text content
+        const div = document.createElement("div");
+        div.innerHTML = DOMPurify.sanitize(content);
+        const textContent = div.textContent || div.innerText || "";
+
+        // Count words (split by whitespace and filter out empty strings)
+        const wordCount = textContent
+            .trim()
+            .split(/\s+/)
+            .filter((word) => word.length > 0).length;
+
+        // Calculate reading time: (wordCount / 240) + 1, rounded
+        const readingTimeMinutes = Math.round(wordCount / 240 + 1);
+        this.readingTime =
+            readingTimeMinutes > 0 ? readingTimeMinutes : undefined;
+    }
 }

package/src/modules/docHelpers/amfStyle/amfStyle.css

@@ -174,8 +174,6 @@ api-security-documentation {
     --http-code-snippet-container-background-color: rgb(250 250 250);
     --http-code-snippet-container-padding: var(--dx-g-spacing-md);
 
-    /* prism */
-
     /* --code-operator-value-background-color */
 }