@salesforcedevs/docs-components 0.56.2 → 0.56.3-example

package/src/modules/doc/phase/phase.ts

@@ -2,16 +2,12 @@ import { LightningElement, api } from "lwc";
 import cx from "classnames";
 
 import { DocPhaseInfo } from "typings/custom";
-import { toJson } from "dxUtils/normalizers";
+import { toJson, normalizeBoolean } from "dxUtils/normalizers";
 
 export default class Phase extends LightningElement {
     _docPhaseInfo: DocPhaseInfo | null = null;
-
-    isBodyHidden = false;
-
-    get docPhaseTitle() {
-        return this.docPhaseInfo?.title;
-    }
+    _dismissible = false;
+    _iconName = "recipe";
 
     @api
     get docPhaseInfo(): DocPhaseInfo | null {
@@ -22,6 +18,34 @@ export default class Phase extends LightningElement {
         this._docPhaseInfo = toJson(value);
     }
 
+    @api
+    get dismissible(): boolean {
+        return this._dismissible;
+    }
+
+    set dismissible(value) {
+        if (value) {
+            this._dismissible = normalizeBoolean(value);
+        }
+    }
+
+    @api
+    get iconName(): string {
+        return this._iconName;
+    }
+
+    set iconName(value) {
+        if (value) {
+            this._iconName = value;
+        }
+    }
+
+    isBodyHidden = false;
+
+    get docPhaseTitle() {
+        return this.docPhaseInfo?.title;
+    }
+
     get hideBodyText() {
         return this.isBodyHidden ? "Show" : "Hide";
     }
@@ -51,7 +75,19 @@ export default class Phase extends LightningElement {
         }
     }
 
-    onButtonClick() {
+    onShowHide() {
         this.isBodyHidden = !this.isBodyHidden;
     }
+
+    onDismiss() {
+        this.dispatchEvent(
+            new CustomEvent("dismissphase", {
+                detail: {
+                    docPhaseInfo: this.docPhaseInfo
+                },
+                composed: true,
+                bubbles: true
+            })
+        );
+    }
 }

package/src/modules/doc/specificationContent/specificationContent.css

@@ -0,0 +1,36 @@
+@import "dxHelpers/reset";
+@import "dxHelpers/text";
+@import "dxHelpers/table";
+
+.code {
+    color: #181818;
+    font-family: Courier, var(--dx-g-font-mono);
+    font-size: var(--dx-g-text-sm);
+    line-height: 150%;
+    background-color: #f4f4f4;
+}
+
+table {
+    width: 100%;
+}
+
+.specification-properties table {
+    display: table;
+}
+
+.left-border {
+    border-left: 1px solid var(--dx-g-gray-90);
+}
+
+.icon-cell {
+    text-align: center;
+}
+
+.icon {
+    display: inline-block;
+}
+
+.loader {
+    pointer-events: none;
+    bottom: 30%;
+}

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

@@ -0,0 +1,167 @@
+<template>
+    <div class="specification-properties">
+        <dx-spinner
+            size="large"
+            variant="brand"
+            class="loader"
+            if:true={isLoading}
+        ></dx-spinner>
+        <dx-error-fallback lwc:if={showError}></dx-error-fallback>
+        <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.name}</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.name}</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,127 @@
+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;
+
+    isLoading: boolean = true;
+    showError: boolean = false;
+
+    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 = {};
+            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" : ""
+            };
+        });
+    }
+
+    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 };