@salesforcedevs/docs-components 0.56.2-seo-test16 → 0.56.2-snyk

package/src/modules/doc/specificationContent/specificationContent.html

@@ -0,0 +1,164 @@
+<template>
+    <div class="specification-properties">
+        <template lwc:if={hasAttributes}>
+            <doc-heading
+                header="Attributes"
+                hash="attributes"
+                aria-level="2"
+                id="attributes"
+            ></doc-heading>
+            <table>
+                <thead>
+                    <tr>
+                        <th>Name</th>
+                        <th>Description</th>
+                        <th>Type</th>
+                        <th>Default</th>
+                        <th>Required</th>
+                    </tr>
+                </thead>
+                <tbody>
+                    <template for:each={attributes} for:item="attribute">
+                        <tr key={attribute.name}>
+                            <td>
+                                <span class="code">
+                                    {attribute.nameInKebabCase}
+                                </span>
+                            </td>
+                            <td>{attribute.description}</td>
+                            <td>{attribute.type}</td>
+                            <td>{attribute.default}</td>
+                            <td class="icon-cell">
+                                <template lwc:if={attribute.required}>
+                                    <dx-icon
+                                        symbol="success"
+                                        size="large"
+                                        color="green-vibrant-65"
+                                        class="icon"
+                                    ></dx-icon>
+                                </template>
+                            </td>
+                        </tr>
+                    </template>
+                </tbody>
+            </table>
+        </template>
+
+        <template lwc:if={hasMethods}>
+            <doc-heading
+                header="Methods"
+                hash="methods"
+                aria-level="2"
+                id="methods"
+            ></doc-heading>
+            <table>
+                <thead>
+                    <tr>
+                        <th>Name</th>
+                        <th>Description</th>
+                        <th>Argument Name</th>
+                        <th>Argument Type</th>
+                        <th>Argument Description</th>
+                    </tr>
+                </thead>
+                <tbody>
+                    <template for:each={processedMethods} for:item="method">
+                        <template lwc:if={method.firstArgument}>
+                            <tr key={method.name}>
+                                <td rowspan={method.arguments.length}>
+                                    <span class="code">
+                                        {method.nameInKebabCase}
+                                    </span>
+                                </td>
+                                <td rowspan={method.arguments.length}>
+                                    {method.description}
+                                </td>
+                                <td class={method.cssForMultipleArguments}>
+                                    {method.firstArgument.name}
+                                </td>
+                                <td>{method.firstArgument.type}</td>
+                                <td>{method.firstArgument.description}</td>
+                            </tr>
+                            <template
+                                for:each={method.remainingArguments}
+                                for:item="arg"
+                            >
+                                <tr key={arg.name}>
+                                    <td>{arg.name}</td>
+                                    <td>{arg.type}</td>
+                                    <td>{arg.description}</td>
+                                </tr>
+                            </template>
+                        </template>
+                        <template lwc:else>
+                            <tr key={method.name}>
+                                <td>
+                                    <span class="code">
+                                        {method.nameInKebabCase}
+                                    </span>
+                                </td>
+                                <td>{method.description}</td>
+                                <td colspan="3"></td>
+                            </tr>
+                        </template>
+                    </template>
+                </tbody>
+            </table>
+        </template>
+
+        <template lwc:if={hasSlots}>
+            <doc-heading
+                header="Slots"
+                hash="slots"
+                aria-level="2"
+                id="slots"
+            ></doc-heading>
+            <table>
+                <thead>
+                    <tr>
+                        <th>Name</th>
+                        <th>Description</th>
+                    </tr>
+                </thead>
+                <tbody>
+                    <template for:each={slots} for:item="slot">
+                        <tr key={slot.name}>
+                            <td>
+                                <span class="code">{slot.nameInKebabCase}</span>
+                            </td>
+                            <td>{slot.description}</td>
+                        </tr>
+                    </template>
+                </tbody>
+            </table>
+        </template>
+
+        <template lwc:if={hasEvents}>
+            <doc-heading
+                header="Events"
+                hash="events"
+                aria-level="2"
+            ></doc-heading>
+            <table>
+                <thead>
+                    <tr>
+                        <th>Name</th>
+                        <th>Description</th>
+                    </tr>
+                </thead>
+                <tbody>
+                    <template for:each={events} for:item="event">
+                        <tr key={event.name}>
+                            <td>
+                                <span class="code">
+                                    {event.nameInKebabCase}
+                                </span>
+                            </td>
+                            <td>{event.description}</td>
+                        </tr>
+                    </template>
+                </tbody>
+            </table>
+        </template>
+    </div>
+</template>

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

@@ -0,0 +1,121 @@
+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;
+    @api model!: string;
+    @api namespace!: string;
+
+    private attributes: Specification[] = [];
+    private methods: Method[] = [];
+    private slots: Specification[] = [];
+    private events: 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.fetchComponentMetadata();
+    }
+
+    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();
+
+            // 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);
+            }
+        } catch (error) {
+            this.data = {};
+            console.error("fetchComponentMetadata() failed:", error);
+        }
+    }
+
+    /**
+     * 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" : ""
+            };
+        });
+    }
+
+    get hasAttributes() {
+        return this.attributes?.length > 0;
+    }
+
+    get hasMethods() {
+        return this.methods?.length > 0;
+    }
+
+    get hasSlots() {
+        return this.slots?.length > 0;
+    }
+
+    get hasEvents() {
+        return this.events?.length > 0;
+    }
+
+    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/sprigSurvey/sprigSurvey.html

@@ -0,0 +1,20 @@
+<template lwc:render-mode="light">
+    <dx-hr no-padding spacing="md"></dx-hr>
+    <div class="survey-container">
+        <div class="text-container">
+            <b>DID THIS ARTICLE SOLVE YOUR ISSUE?</b>
+            <br />
+            Let us know so we can improve!
+        </div>
+        <div class="btn-container">
+            <dx-button
+                variant="secondary"
+                aria-label="Share Your Feedback"
+                onclick={openSurvey}
+            >
+                Share your feedback
+            </dx-button>
+        </div>
+    </div>
+    <dx-hr no-padding spacing="md"></dx-hr>
+</template>

package/src/modules/doc/sprigSurvey/sprigSurvey.scoped.css

@@ -0,0 +1,16 @@
+:host .survey-container {
+    align-items: center;
+    align-content: center;
+    width: 100%;
+    display: flex;
+    flex-direction: row;
+    margin: 20px 0;
+}
+
+dx-hr:first-of-type::part(hr) {
+    margin-top: var(--dx-g-spacing-2xl);
+}
+
+.text-container {
+    width: 100%;
+}

package/src/modules/doc/sprigSurvey/sprigSurvey.ts

@@ -0,0 +1,16 @@
+import { LightningElement } from "lwc";
+import cx from "classnames";
+
+declare const Sprig: (eventType: string, eventNme: string) => void;
+
+export default class Phase extends LightningElement {
+    static renderMode = "light";
+
+    get className() {
+        return cx("container");
+    }
+
+    openSurvey() {
+        Sprig("track", "ProvideFeedback");
+    }
+}

package/src/modules/doc/toc/toc.ts

@@ -11,7 +11,7 @@ export default class Toc extends LightningElement {
         const newPageReference = { ...this.pageReference };
         // When moving to the new navigation component
         //const target = event.detail.name.split('-')
-        const target = event.currentTarget.dataset.id.split("-");
+        const target = (event.currentTarget as any).dataset.id.split("-");
         newPageReference.contentDocumentId = target[0] + ".htm";
         newPageReference.hash = target[1];
         this.dispatchEvent(

package/src/modules/doc/versionPicker/versionPicker.css

@@ -0,0 +1,64 @@
+@import "dxHelpers/reset";
+
+/* NOTE: doc-version-picker-width width variable is used by both dx-button and dx-dropdown to maintain a consistent width. */
+:host {
+    --dx-c-dropdown-option-font-weight: normal;
+    --dx-c-dropdown-option-label-color: var(--dx-g-gray-10);
+    --popover-container-open-transform: translateY(4px);
+}
+
+.version-picker-container {
+    padding: 8px var(--dx-g-spacing-lg) 8px
+        var(--dx-g-global-header-padding-horizontal);
+    border-top: 1px solid var(--dx-g-gray-90);
+    border-bottom: 1px solid var(--dx-g-gray-90);
+}
+
+.version-picker-button {
+    display: flex;
+    width: var(--doc-version-picker-width, 296px);
+}
+
+.version-picker-button:hover,
+.version-picker-button:active,
+.version-picker-button:focus {
+    --dx-c-button-secondary-color-hover: var(--dx-g-cloud-blue-vibrant-95);
+    --dx-c-button-primary-color: var(--dx-g-blue-vibrant-40);
+}
+
+/**
+ * NOTE: This CSS ensures the span inside the button stays within the parent's width, avoiding overflow.
+ * Not keeping this in common component to ensure that existing functionality works as it is.
+ */
+dx-button::part(content) {
+    width: inherit;
+    overflow: hidden;
+}
+
+.selected-version {
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+}
+
+.selected-version-label {
+    flex: 1;
+    overflow: hidden;
+    text-align: left;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+}
+
+dx-type-badge.latest-badge {
+    --dx-c-type-badge-color: var(--dx-g-green-vibrant-40);
+    --dx-c-type-badge-background: var(--dx-g-green-vibrant-95);
+
+    margin-left: var(--dx-g-spacing-sm);
+}
+
+dx-type-badge.not-latest-badge {
+    --dx-c-type-badge-color: var(--dx-g-red-vibrant-40);
+    --dx-c-type-badge-background: var(--dx-g-red-vibrant-95);
+
+    margin-left: var(--dx-g-spacing-sm);
+}

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

@@ -0,0 +1,38 @@
+<template>
+    <div lwc:if={showVersionPicker} class="version-picker-container">
+        <dx-dropdown
+            options={versions}
+            value={selectedVersion.id}
+            width="var(--doc-version-picker-width)"
+            onchange={onVersionChange}
+        >
+            <dx-button
+                class="version-picker-button"
+                variant="tertiary"
+                size="small"
+                icon-symbol="chevrondown"
+                icon-size="medium"
+            >
+                <div class="selected-version">
+                    <p class="selected-version-label">
+                        {selectedVersion.label}
+                    </p>
+                    <template lwc:if={showLatestTag}>
+                        <dx-type-badge
+                            class="latest-badge"
+                            lwc:if={latestVersion}
+                            value="Latest"
+                            size="small"
+                        ></dx-type-badge>
+                        <dx-type-badge
+                            class="not-latest-badge"
+                            lwc:else
+                            value="Not Latest"
+                            size="small"
+                        ></dx-type-badge>
+                    </template>
+                </div>
+            </dx-button>
+        </dx-dropdown>
+    </div>
+</template>

package/src/modules/doc/versionPicker/versionPicker.ts

@@ -0,0 +1,65 @@
+import { LightningElement, api, track } from "lwc";
+
+import { AnalyticsPayload, OptionWithNested } from "typings/custom";
+
+import { toJson, normalizeBoolean } from "dxUtils/normalizers";
+
+export default class VersionPicker extends LightningElement {
+    @api analyticsEvent?: string;
+    @api analyticsPayload?: AnalyticsPayload;
+
+    @track private _versions!: OptionWithNested[];
+    private _selectedVersion?: OptionWithNested;
+    private _latestVersion: boolean = false;
+    private _hideBadge: boolean = false;
+
+    @api
+    get versions() {
+        return this._versions;
+    }
+
+    set versions(value: OptionWithNested[]) {
+        this._versions = toJson(value);
+    }
+
+    @api
+    get selectedVersion(): OptionWithNested | undefined {
+        return this._selectedVersion || this.versions[0];
+    }
+
+    set selectedVersion(value: OptionWithNested) {
+        if (value) {
+            this._selectedVersion = toJson(value);
+        }
+    }
+
+    @api
+    get latestVersion() {
+        return this._latestVersion;
+    }
+
+    set latestVersion(value) {
+        this._latestVersion = normalizeBoolean(value);
+    }
+
+    @api
+    get hideBadge() {
+        return this._hideBadge;
+    }
+
+    set hideBadge(value) {
+        this._hideBadge = normalizeBoolean(value);
+    }
+
+    private get showVersionPicker() {
+        return this._versions && this._versions.length !== 0;
+    }
+
+    private get showLatestTag(): boolean {
+        return !this.hideBadge;
+    }
+
+    private onVersionChange(e: CustomEvent) {
+        this.dispatchEvent(new CustomEvent("change", { detail: e.detail }));
+    }
+}

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

@@ -24,6 +24,7 @@ export type TreeNode = {
     name: string;
     children?: Array<TreeNode>;
     isExpanded?: boolean;
+    parent?: TreeNode;
 };
 
 type DropdownOption = {
@@ -34,6 +35,9 @@ type DropdownOption = {
 export type DocVersion = DropdownOption & {
     releaseVersion: string;
     url: string;
+    link?: {
+        href: string;
+    };
 };
 
 export type DocLanguage = DropdownOption & {
@@ -57,12 +61,15 @@ export type ApiDocLanguage = {
 
 export interface Header extends Element {
     subtitle: string;
+    headerHref: string;
+}
+
+export type SiderbarFooter = {
     bailHref: string;
     bailLabel: string;
     languages: Array<DocLanguage>;
-    language: string;
-    headerHref: string;
-}
+    language?: string;
+};
 
 export type ApiNavItem = {
     children: Array<ApiNavItem>;
@@ -109,3 +116,5 @@ export type ContentApiOptions = {
     version: string;
     language: string;
 };
+
+export type TocMap = { [key: string]: TreeNode };

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

@@ -8,7 +8,8 @@ import {
     DocumentData,
     DocLanguage,
     DocVersion,
-    TreeNode
+    TreeNode,
+    TocMap
 } from "./types";
 import { Language } from "typings/custom";
 import { getLanguageDisplayTextById } from "dxUtils/language";
@@ -86,7 +87,9 @@ export class FetchContent {
         return json;
     }
 
-    private normalizeToc(apiToc: Array<ApiNavItem>): {
+    private normalizeToc(
+        apiToc: Array<ApiNavItem>
+    ): {
         tocMap: { [key: string]: TreeNode };
         normalizedToc: Array<TreeNode>;
     } {
@@ -100,26 +103,26 @@ export class FetchContent {
 
     private normalizeNavItem(
         navItem: ApiNavItem,
-        tocMap: { [key: string]: TreeNode }
+        tocMap: TocMap,
+        parentNavItem?: TreeNode
     ): TreeNode {
         const name = this.calculateNavItemName(navItem, tocMap);
         const node: TreeNode = {
             label: navItem.text,
-            name
+            name,
+            parent: parentNavItem
         };
+
         if (name) {
             tocMap[name] = node;
         }
         node.children = navItem.children?.map((child) =>
-            this.normalizeNavItem(child, tocMap)
+            this.normalizeNavItem(child, tocMap, node)
         );
         return node;
     }
 
-    private calculateNavItemName(
-        navItem: ApiNavItem,
-        tocMap: { [key: string]: TreeNode }
-    ): string {
+    private calculateNavItemName(navItem: ApiNavItem, tocMap: TocMap): string {
         let href = navItem.a_attr?.href || "";
         if (href.includes("#")) {
             const [pathUrl] = href.split("#");
@@ -144,11 +147,13 @@ export class FetchContent {
     }
 
     private normalizeLanguage(language: ApiDocLanguage): DocLanguage {
-
         return (
             language && {
-                label: getLanguageDisplayTextById(this.languages, language.locale) || 
-                    language.label,
+                label:
+                    getLanguageDisplayTextById(
+                        this.languages,
+                        language.locale
+                    ) || language.label,
                 id: language.locale,
                 code: language.code,
                 url: language.url

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

@@ -3,6 +3,18 @@
     --button-primary-color-hover: var(--dx-g-blue-vibrant-40);
 }
 
+doc-content-layout {
+    --dx-c-content-sidebar-sticky-top: var(--dx-g-global-header-height);
+    --dx-c-sidebar-height: calc(100vh - var(--dx-g-global-header-height));
+}
+
+doc-breadcrumbs {
+    --dx-c-popover-z-index: 5;
+
+    display: block;
+    margin-bottom: var(--dx-g-spacing-md);
+}
+
 dx-dropdown {
     --dx-c-dropdown-option-font-size: var(--dx-g-text-sm);
 }
@@ -19,7 +31,24 @@ dx-dropdown > dx-button:hover {
     --border-color: var(--button-primary-color-hover);
 }
 
-.document-pickers {
-    margin-left: auto;
-    margin-right: var(--dx-g-spacing-sm);
+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;
+        --dx-g-doc-header-height: calc(
+            var(--dx-g-doc-header-main-nav-height) + 40px
+        );
+        --dx-c-content-sidebar-sticky-top: calc(
+            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)
+        );
+    }
 }