@salesforcedevs/docs-components 0.0.0 → 0.0.1-superscript

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

@@ -0,0 +1,177 @@
+<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>
+        <dx-error-fallback
+            lwc:if={showNoSpecifications}
+            title="No specifications to show"
+            description="No specifications are available for this component or API module. When specifications are defined, they'll appear here."
+        ></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">
+                                    <template lwc:if={isModelAura}>
+                                        {attribute.name}
+                                    </template>
+                                    <template lwc:else>
+                                        {attribute.nameInKebabCase}
+                                    </template>
+                                </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={processedEvents} for:item="event">
+                        <tr key={event.name}>
+                            <td>
+                                <span class="code">
+                                    {event.nameCapitalized}
+                                </span>
+                            </td>
+                            <td>{event.description}</td>
+                        </tr>
+                    </template>
+                </tbody>
+            </table>
+        </template>
+    </div>
+</template>

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

@@ -0,0 +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;
+    @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.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);
+
+                // 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 = {};
+            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?.length > 0;
+    }
+
+    get hasMethods() {
+        return this.methods?.length > 0;
+    }
+
+    get hasSlots() {
+        return this.slots?.length > 0;
+    }
+
+    get hasEvents() {
+        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/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/superscriptSubscript/superscriptSubscript.html

@@ -0,0 +1,8 @@
+<template>
+    <template lwc:if={isSuper}>
+        <sup>{value}</sup>
+    </template>
+    <template lwc:else>
+        <sub>{value}</sub>
+    </template>
+</template>

package/src/modules/doc/superscriptSubscript/superscriptSubscript.ts

@@ -0,0 +1,16 @@
+import { LightningElement, api } from "lwc";
+import { normalizeBoolean } from "dxUtils/normalizers";
+
+export default class SuperscriptSubscript extends LightningElement {
+    _isSuper: boolean = true;
+    @api value: string | null = null;
+
+    @api
+    get isSuper(): boolean {
+        return this._isSuper;
+    }
+
+    set isSuper(value) {
+        this._isSuper = normalizeBoolean(value);
+    }
+}

package/src/modules/doc/toc/toc.html

@@ -96,9 +96,7 @@
                                                                     <a
                                                                         href={child5.a_attr.href}
                                                                         data-id={child5.id}
-                                                                        class="
-                                                                            nav1
-                                                                        "
+                                                                        class="nav1"
                                                                         onclick={handleNavClick}
                                                                     >
                                                                         {child5.text}

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/toolbar/toolbar.ts

@@ -40,9 +40,9 @@ export default class Toolbar extends LightningElement {
             "select[name=languages]"
         ) as HTMLSelectElement;
         if (languageEl) {
-            const languageValue = (
-                languageEl[languageEl.selectedIndex] as HTMLOptionElement
-            ).value;
+            const languageValue = (languageEl[
+                languageEl.selectedIndex
+            ] as HTMLOptionElement).value;
             this.dispatchEvent(
                 new CustomEvent("languageselected", {
                     detail: {
@@ -61,9 +61,9 @@ export default class Toolbar extends LightningElement {
             "select[name=versions]"
         ) as HTMLSelectElement;
         if (versionEl) {
-            const versionValue = (
-                versionEl[versionEl.selectedIndex] as HTMLOptionElement
-            ).value;
+            const versionValue = (versionEl[
+                versionEl.selectedIndex
+            ] as HTMLOptionElement).value;
             this.dispatchEvent(
                 new CustomEvent("versionselected", {
                     detail: {

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,40 @@
+<template>
+    <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}
+        >
+            <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

@@ -35,6 +35,9 @@ type DropdownOption = {
 export type DocVersion = DropdownOption & {
     releaseVersion: string;
     url: string;
+    link?: {
+        href: string;
+    };
 };
 
 export type DocLanguage = DropdownOption & {
@@ -58,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>;

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

@@ -87,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>;
     } {