@salesforcedevs/docs-components 0.0.7 → 0.0.9-edit

package/src/modules/doc/overview/overview.css

@@ -0,0 +1,40 @@
+doc-phase {
+    --doc-c-phase-top: calc(
+        var(--dx-g-global-header-height) + var(--dx-g-doc-header-height)
+    );
+}
+
+dx-section {
+    --dx-c-section-padding-top: 0;
+    --dx-c-section-padding-bottom: var(--dx-g-spacing-2xl);
+}
+
+dx-section::part(content) {
+    max-width: 1280px;
+    margin: auto;
+}
+
+dx-group-text:first-of-type {
+    margin-top: var(--dx-g-spacing-2xl);
+}
+
+dx-group-text.features {
+    margin-top: var(--dx-g-spacing-xl);
+    margin-bottom: var(--dx-g-spacing-xl);
+}
+
+.content {
+    padding-right: var(--dx-g-spacing-xl);
+}
+
+@media (max-width: 1024px) {
+    .content {
+        padding-right: 0;
+    }
+}
+
+@media (max-width: 800px) {
+    dx-group-text.description {
+        margin-top: var(--dx-g-spacing-lg);
+    }
+}

package/src/modules/doc/overview/overview.html

@@ -0,0 +1,34 @@
+<template>
+    <div class="container">
+        <doc-phase
+            if:true={docPhaseInfo}
+            doc-phase-info={docPhaseInfo}
+        ></doc-phase>
+
+        <dx-section>
+            <dx-grid columns="two-slim-right">
+                <div class="content">
+                    <dx-group-text
+                        class="description"
+                        header={header}
+                        body={description}
+                        size="large"
+                        title-aria-level="1"
+                        primary-link={primaryLink}
+                        secondary-link={secondaryLink}
+                    ></dx-group-text>
+                </div>
+                <div>
+                    <dx-group-text
+                        header={featuresListTitle}
+                        size="medium"
+                        class="features"
+                    ></dx-group-text>
+                    <dx-features-list
+                        options={featuresListOptions}
+                    ></dx-features-list>
+                </div>
+            </dx-grid>
+        </dx-section>
+    </div>
+</template>

package/src/modules/doc/overview/overview.ts

@@ -0,0 +1,12 @@
+import { LightningElement, api } from "lwc";
+import { DocPhaseInfo, FeatureItem, Link } from "typings/custom";
+
+export default class Overview extends LightningElement {
+    @api docPhaseInfo!: DocPhaseInfo;
+    @api header!: string;
+    @api description!: string;
+    @api primaryLink!: Link;
+    @api secondaryLink!: Link;
+    @api featuresListTitle!: string;
+    @api featuresListOptions!: FeatureItem[];
+}

package/src/modules/doc/phase/phase.css

@@ -0,0 +1,70 @@
+@import "dxHelpers/reset";
+@import "dxHelpers/text";
+@import "docHelpers/status";
+
+:host {
+    --doc-c-phase-top: 0;
+    --doc-c-phase-container-align-items: flex-start;
+
+    position: sticky;
+    top: var(--doc-c-phase-top);
+
+    /* NOTE: If you are changing z-index value here, ensure it's less than z-index of dx-sidebar in contentLayout.css */
+    z-index: var(--dx-g-z-index-100);
+}
+
+.doc-phase-container {
+    display: flex;
+    flex-direction: column;
+    align-items: var(--doc-c-phase-container-align-items);
+    padding-left: var(--dx-g-global-header-padding-horizontal);
+    padding-right: var(--dx-g-global-header-padding-horizontal);
+    width: 100%;
+    border: none;
+}
+
+.doc-phase-title-container {
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    width: 100%;
+}
+
+dx-button {
+    margin-left: auto;
+}
+
+/*
+    NOTE: Here we are assuming that indicator height won't go beyond 1000px.
+
+    It's one of the suggested way to achieve the expand/collapse animation
+    Ref: https://stackoverflow.com/a/41164095
+
+    Otherwise we need to change the height when user clicks on button
+    Ref: https://stackoverflow.com/a/11837673
+*/
+
+.doc-phase-body {
+    display: block;
+    max-height: 1000px;
+    overflow: hidden;
+    padding-top: var(--dx-g-spacing-smd);
+    transition: max-height 0.25s ease, padding 0.25s ease;
+}
+
+.doc-phase-body-hidden {
+    max-height: 0;
+    padding-top: 0;
+    transition: max-height 0.1s ease-out, padding 0.25s ease-out;
+}
+
+.doc-phase-body a {
+    color: var(--dx-g-blue-vibrant-50);
+}
+
+/* Small Devices */
+@media screen and (max-width: 480px) {
+    .doc-phase-container {
+        padding: var(--doc-status-vertical-padding);
+    }
+}

package/src/modules/doc/phase/phase.html

@@ -0,0 +1,38 @@
+<template>
+    <div class={className} part="container">
+        <div class="doc-phase-title-container">
+            <dx-icon
+                class="doc-status-icon doc-phase-icon"
+                symbol={iconName}
+                size="large"
+                color="status-icon-color"
+            ></dx-icon>
+            <p class="doc-status-title doc-phase-title dx-text-body-3">
+                {docPhaseTitle}
+            </p>
+            <dx-button
+                lwc:if={dismissible}
+                aria-label="Dismiss"
+                icon-color="status-icon-color"
+                icon-size="large"
+                icon-symbol="close"
+                variant="icon-only"
+                onclick={onDismiss}
+            ></dx-button>
+            <dx-button
+                lwc:else
+                variant="inline"
+                onclick={onShowHide}
+                aria-label={hideBodyText}
+            >
+                {hideBodyText}
+            </dx-button>
+        </div>
+        <!--
+            NOTE: Here we are rendering mark up using lwc:dom & innerHTML
+            option instead of slots because the html markup will come as a
+            property to the component from a configuration
+        -->
+        <span lwc:dom="manual" class={bodyClassName}></span>
+    </div>
+</template>

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

@@ -0,0 +1,93 @@
+import { LightningElement, api } from "lwc";
+import cx from "classnames";
+
+import { DocPhaseInfo } from "typings/custom";
+import { toJson, normalizeBoolean } from "dxUtils/normalizers";
+
+export default class Phase extends LightningElement {
+    _docPhaseInfo: DocPhaseInfo | null = null;
+    _dismissible = false;
+    _iconName = "recipe";
+
+    @api
+    get docPhaseInfo(): DocPhaseInfo | null {
+        return this._docPhaseInfo;
+    }
+
+    set docPhaseInfo(value) {
+        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";
+    }
+
+    get className() {
+        return cx(
+            "doc-status-base",
+            "doc-status-container",
+            "doc-phase-container"
+        );
+    }
+
+    get bodyClassName() {
+        return cx(
+            "doc-phase-body",
+            "dx-text-body-3",
+            this.isBodyHidden && "doc-phase-body-hidden"
+        );
+    }
+
+    renderedCallback() {
+        const phaseBodyContainer =
+            this.template.querySelector(".doc-phase-body");
+        if (phaseBodyContainer && this.docPhaseInfo) {
+            // eslint-disable-next-line @lwc/lwc/no-inner-html
+            phaseBodyContainer.innerHTML = this.docPhaseInfo.body;
+        }
+    }
+
+    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,171 @@
+<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.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,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");
+    }
+}