@salesforcedevs/dx-components 1.3.136 → 1.3.137-j2s

package/src/modules/dx/scrollManager/scrollManager.ts

@@ -166,6 +166,7 @@ export default class ScrollManager extends LightningElement {
     saveScroll = throttle(100, () => {
         window.history.replaceState(
             {
+                ...window.history.state,
                 scroll: {
                     value: document.body.scrollTop,
                     docSize: document.body.scrollHeight

package/src/modules/dx/sectionBanner/sectionBanner.html

@@ -11,7 +11,7 @@
                 {title}
             </h3>
             <div class="content-body-container">
-                <img if:true={hasQuote} src="/assets/svg/quotes.svg" alt="" />
+                <img if:true={hasQuote} src={quoteGraphicSrc} alt="" />
                 <div class={quoteContentStyle}>
                     <p class={contentBodyStyle}>{body}</p>
                     <p if:true={footNote} class="foot-note dx-text-display-7">

package/src/modules/dx/sectionBanner/sectionBanner.ts

@@ -11,6 +11,7 @@ export default class SectionBanner extends LightningElement {
     @api hideTopGraphic = false;
     @api backgroundColor = "indigo-vibrant-20";
     @api hasQuote = false;
+    @api quoteGraphicSrc?: string;
 
     get containerStyle() {
         return cx("container", !this.hideTopGraphic && "top-margin");

package/src/modules/dx/stepSequence/stepSequence.css

@@ -0,0 +1,42 @@
+/*
+  This CSS will automatically handle the displaying of child dx-step-sequence-step components,
+  including animations, if they are enabled. There is no other UI for this component.
+*/
+::slotted(*) {
+    position: absolute;
+    top: 0;
+    transition: transform 0.4s ease, opacity 0.4s ease;
+    width: 100%;
+}
+
+.no-animations ::slotted(*) {
+    display: none;
+}
+
+::slotted(.visible) {
+    display: block;
+}
+
+::slotted(.active-step) {
+    position: relative;
+}
+
+::slotted(.animate-left-out) {
+    opacity: 0;
+    transform: translateX(-100%);
+}
+
+::slotted(.animate-in) {
+    opacity: 1;
+    transform: translateX(0);
+}
+
+::slotted(.animate-right-out) {
+    opacity: 0;
+    transform: translateX(100%);
+}
+
+.step-sequence-container {
+    overflow: hidden;
+    position: relative;
+}

package/src/modules/dx/stepSequence/stepSequence.html

@@ -0,0 +1,9 @@
+<template>
+    <div class={containerClassName}>
+        <slot
+            onslotchange={handleSlotChange}
+            onstepincrement={handleStepIncrement}
+            onstepdecrement={handleStepDecrement}
+        ></slot>
+    </div>
+</template>

package/src/modules/dx/stepSequence/stepSequence.ts

@@ -0,0 +1,271 @@
+/* eslint-disable no-restricted-globals */
+import { api, LightningElement } from "lwc";
+import cx from "classnames";
+
+// This is a UI-agnostic wrapper component that turns its children components into a sequence of
+// of steps. The children must be dx-step-sequence-step components. Navigation works both via the browser's
+// forward/back buttons and via any action buttons defined in the dx-step-sequence-step components (see that
+// component for details on the action buttons).
+export default class StepSequence extends LightningElement {
+    @api animateTransitions = false;
+    @api communicateStepChanges = false;
+    @api initialStepIndex: string | undefined;
+    @api sessionStorageId = "";
+    @api useHistory = false;
+
+    private currentStepIndex = 0;
+    private defaultScrollRestorationValue = history.scrollRestoration;
+    private isHiddenForInitialAnimation = true;
+    private numPendingInitialTransitions = 0;
+    private steps: Array<HTMLElement> = [];
+
+    private get containerClassName() {
+        return cx("step-sequence-container", {
+            "no-animations": !this.animateTransitions,
+            hidden: this.isHiddenForInitialAnimation
+        });
+    }
+
+    connectedCallback() {
+        const initialStepIndex = parseInt(this.initialStepIndex as string, 10);
+
+        if (!isNaN(initialStepIndex)) {
+            this.currentStepIndex = initialStepIndex;
+        }
+
+        if (this.useHistory) {
+            this.defaultScrollRestorationValue = history.scrollRestoration;
+            history.scrollRestoration = "manual";
+            history.replaceState(
+                {
+                    ...window.history.state,
+                    currentStepIndex: this.currentStepIndex
+                },
+                ""
+            );
+            window.addEventListener("popstate", this.handleHistoryPopstate);
+        }
+
+        if (this.sessionStorageId) {
+            sessionStorage.setItem(
+                this.sessionStorageId,
+                JSON.stringify({
+                    currentStepIndex: this.currentStepIndex
+                })
+            );
+        }
+
+        if (this.animateTransitions) {
+            this.addEventListener("transitionend", this.handleTransitionEnd);
+        } else {
+            this.isHiddenForInitialAnimation = false;
+        }
+    }
+
+    disconnectedCallback() {
+        window.removeEventListener("popstate", this.handleHistoryPopstate);
+        this.removeEventListener("transitionend", this.handleTransitionEnd);
+        history.scrollRestoration = this.defaultScrollRestorationValue;
+    }
+
+    private scrollToStepTop() {
+        this.template.host.scrollIntoView();
+    }
+
+    // Used only if this.animateTransitions is truthy
+    private handleTransitionEnd = ({ target }: Event) => {
+        if (
+            (target as HTMLElement).tagName?.toLowerCase() !==
+            "dx-step-sequence-step"
+        ) {
+            // Ignore transitions of other nested elements
+            return;
+        }
+
+        // Ensure subsequent steps are no longer visible:
+        const prevStep = this.steps[this.currentStepIndex - 1];
+        const nextStep = this.steps[this.currentStepIndex + 1];
+        if (prevStep?.classList.contains("visible")) {
+            prevStep.classList.remove("visible");
+        }
+        if (nextStep?.classList.contains("visible")) {
+            nextStep.classList.remove("visible");
+        }
+
+        // Mark the current step as fully active:
+        this.steps[this.currentStepIndex].classList.add("active-step");
+
+        if (
+            this.isHiddenForInitialAnimation &&
+            this.numPendingInitialTransitions > 0
+        ) {
+            // Initial animation; allow subsequent animations to be visible when ready
+            this.numPendingInitialTransitions =
+                this.numPendingInitialTransitions - 1;
+            if (this.numPendingInitialTransitions === 0) {
+                this.isHiddenForInitialAnimation = false;
+            }
+        }
+    };
+
+    private changeActiveStep(nextStepIndex: number, updateHistory = true) {
+        if (
+            nextStepIndex === this.currentStepIndex ||
+            !this.isStepIndexWithinBounds(nextStepIndex)
+        ) {
+            // Should never happen, but covering all logical bases. Nothing to do here.
+            return;
+        }
+
+        this.scrollToStepTop();
+
+        if (!this.animateTransitions) {
+            this.steps[this.currentStepIndex].className = "";
+            this.steps[nextStepIndex].className = "visible active-step";
+        } else {
+            this.template.querySelector(
+                ".step-sequence-container"
+            )!.style.minHeight = `${this.steps[nextStepIndex].clientHeight}px`;
+            // If animations are enabled, we need to animate in the correct directions:
+            if (nextStepIndex > this.currentStepIndex) {
+                this.steps[this.currentStepIndex].className =
+                    "visible animate-left-out";
+                this.steps[nextStepIndex].className = "visible animate-in";
+            } else {
+                this.steps[this.currentStepIndex].className =
+                    "visible animate-right-out";
+                this.steps[nextStepIndex].className = "visible animate-in";
+            }
+        }
+
+        if (this.useHistory && updateHistory) {
+            history.pushState(
+                {
+                    currentStepIndex: nextStepIndex
+                },
+                ""
+            );
+        }
+
+        if (this.sessionStorageId) {
+            sessionStorage.setItem(
+                this.sessionStorageId,
+                JSON.stringify({
+                    currentStepIndex: nextStepIndex
+                })
+            );
+        }
+
+        this.currentStepIndex = nextStepIndex;
+
+        if (this.communicateStepChanges) {
+            this.dispatchEvent(
+                new CustomEvent("stepsequencechange", {
+                    detail: {
+                        stepIndex: this.currentStepIndex
+                    },
+                    composed: true,
+                    bubbles: true
+                })
+            );
+        }
+    }
+
+    private initializeStepAnimationClasses(
+        currentStepIndex: number,
+        step: HTMLElement,
+        stepIndex: number
+    ) {
+        // All steps to the "left" of the current step are treated as though they've already
+        // animated out in that direction, and similarly for all steps to the "right." Only
+        // the current step is initialized as visible and active.
+        if (stepIndex < currentStepIndex) {
+            step.className = "animate-left-out";
+        } else if (stepIndex > currentStepIndex) {
+            step.className = "animate-right-out";
+        } else {
+            step.className = "visible active-step";
+        }
+    }
+
+    @api
+    public getCurrentStepIndex(): number {
+        return this.currentStepIndex;
+    }
+
+    // This method is available in case there are scenarios where a sequence needs to "jump" in some cases
+    @api
+    public jumpToStep(stepIndex: number) {
+        if (!this.isStepIndexWithinBounds(stepIndex)) {
+            // illegal value; ignore
+            return;
+        }
+
+        this.changeActiveStep(stepIndex);
+
+        if (this.animateTransitions) {
+            this.steps.forEach((step, index) =>
+                this.initializeStepAnimationClasses(stepIndex, step, index)
+            );
+        }
+    }
+
+    private isStepIndexWithinBounds(stepIndex: number) {
+        return stepIndex >= 0 && stepIndex < this.steps.length;
+    }
+
+    handleHistoryPopstate = ({ state }: PopStateEvent) => {
+        if (typeof state.currentStepIndex === "number") {
+            this.changeActiveStep(state.currentStepIndex, false);
+        }
+    };
+
+    handleStepDecrement(e: CustomEvent) {
+        e.stopPropagation();
+        if (this.currentStepIndex <= 0) {
+            return;
+        }
+        this.changeActiveStep(this.currentStepIndex - 1);
+    }
+
+    handleStepIncrement(e: CustomEvent) {
+        e.stopPropagation();
+        if (this.currentStepIndex >= this.steps.length - 1) {
+            return;
+        }
+        this.changeActiveStep(this.currentStepIndex + 1);
+    }
+
+    // Assign steps and appropriate classNames when slots are loaded. This component was built on
+    // the assumption that the slotChange will only happen at initial load, though it SHOULD still
+    // work even if the slots are changed later (though note that the value of
+    // `this.currentStepIndex` will be applied to the new slotted elements; call `jumpToStep` to
+    // change it).
+    handleSlotChange(e: Event) {
+        const slot = e.target as HTMLSlotElement;
+        this.steps = slot.assignedElements() as HTMLElement[];
+        let numPendingInitialTransitions = 0;
+
+        this.steps.forEach((step, index) => {
+            if (this.animateTransitions) {
+                this.initializeStepAnimationClasses(
+                    this.currentStepIndex,
+                    step,
+                    index
+                );
+                if (index !== this.currentStepIndex) {
+                    const numTransitionsForStep =
+                        getComputedStyle(step)?.transition?.split(",").length;
+                    if (numTransitionsForStep) {
+                        numPendingInitialTransitions =
+                            numPendingInitialTransitions +
+                            numTransitionsForStep;
+                    }
+                }
+            }
+        });
+
+        this.numPendingInitialTransitions = numPendingInitialTransitions;
+        this.steps[this.currentStepIndex].className = "visible active-step";
+    }
+}

package/src/modules/dx/stepSequenceStep/stepSequenceStep.html

@@ -0,0 +1,3 @@
+<template>
+    <slot onslotchange={handleSlotChange}></slot>
+</template>

package/src/modules/dx/stepSequenceStep/stepSequenceStep.ts

@@ -0,0 +1,60 @@
+import { LightningElement } from "lwc";
+
+// A UI-agnostic component meant to be used as a child of dx-step-sequence. The component
+// automatically enables "go forward" and "go back" functionality for any slotted element's
+// ".primary-action" child and ".secondary-action" child, respectively. If the
+// dx-step-sequence has `animateTransitions` set to `true`, the transitions will auto-animate.
+// Child component action buttons can still perform whatever actions they want before the
+// step proceeds.
+export default class StepSequenceStep extends LightningElement {
+    handleSlotChange(e: Event) {
+        const slot = e.target as HTMLSlotElement;
+        const rootElement = slot.assignedElements()[0];
+        const primaryActionElement = rootElement.querySelector(
+            ".primary-action"
+        ) as HTMLElement | undefined;
+        const secondaryActionElement = rootElement.querySelector(
+            ".secondary-action"
+        ) as HTMLElement | undefined;
+
+        if (primaryActionElement) {
+            const assignedOnClick = primaryActionElement.onclick;
+            primaryActionElement.onclick = (event: MouseEvent) => {
+                assignedOnClick?.call(primaryActionElement, event);
+                // Child elements can prevent the default "go forward" action.
+                if (!event.defaultPrevented) {
+                    this.goForward();
+                }
+            };
+        }
+
+        if (secondaryActionElement) {
+            const assignedOnClick = secondaryActionElement.onclick;
+            secondaryActionElement.onclick = (event: MouseEvent) => {
+                assignedOnClick?.call(secondaryActionElement, event);
+                // Child elements can prevent the default "go back" action.
+                if (!event.defaultPrevented) {
+                    this.goBack();
+                }
+            };
+        }
+    }
+
+    goForward() {
+        this.dispatchEvent(
+            new CustomEvent("stepincrement", {
+                bubbles: true,
+                composed: true
+            })
+        );
+    }
+
+    goBack() {
+        this.dispatchEvent(
+            new CustomEvent("stepdecrement", {
+                bubbles: true,
+                composed: true
+            })
+        );
+    }
+}

package/src/modules/dxBaseElements/lightningElementWithState/lightningElementWithState.ts

@@ -0,0 +1,93 @@
+import { LightningElement, track } from "lwc";
+
+/**
+ * This is a helper class for when you want your LWC component to have state
+ * that is automatically tracked _along with_ its previous state, in a React-
+ * like fashion, so that you can compare current state with previous state
+ * after a render (like React's `commponentDidUpdate`). One benefit of doing
+ * things this way is that you can put all of your reactions to state changes
+ * in one place, in `renderedCallback`, rather than having them in various
+ * places throughout the component.
+ *
+ * The API consists in `this.prevState`, `this.state`, and `this.setState`.
+ *
+ * Usage:
+ *
+ * ```
+ * type MyState = {
+ *     isFetchingContent: boolean;
+ * };
+ *
+ * class MyFetchingComponent extends LightningElementWithState<MyState> {
+ *     constructor() {
+ *         // `this.state` can only be initialized once
+ *         this.state = {
+ *             isFetchingContent: false
+ *         };
+ *     }
+ *
+ *     // Queued for execution whenever a `setState` call completes
+ *     renderedCallback() {
+ *         if (this.prevState.isFetchingContent && !this.state.isFetchingContent) {
+ *             // Do something knowing that we just finished fetching.
+ *             notifyFetchSuccessful();
+ *         }
+ *     }
+ *
+ *     fetchSomething() {
+ *         this.setState({
+ *             isFetchingContent: true
+ *         });
+ *
+ *         fetch(whatever).then(() => {
+ *             this.setState({
+ *                 isFetching: false
+ *             }
+ *         });
+ *     }
+ * }
+ * ```
+ */
+export abstract class LightningElementWithState<
+    T extends { [key: string]: unknown }
+> extends LightningElement {
+    private _prevState = {} as T;
+    @track private _state = {} as T;
+
+    private _didInitializeState = false;
+
+    protected get prevState(): T {
+        return Object.freeze({
+            ...this._prevState
+        });
+    }
+
+    protected get state(): T {
+        return Object.freeze({
+            ...this._state
+        });
+    }
+
+    protected set state(initialState: T) {
+        if (!this._didInitializeState) {
+            this._state = {
+                ...initialState
+            };
+            this._didInitializeState = true;
+        } else {
+            throw new Error(
+                "To mutate state after initialization, use `this.setState`."
+            );
+        }
+    }
+
+    protected setState = (state: Partial<T>): void => {
+        this._prevState = {
+            ...this._state
+        };
+        this._state = {
+            ...this._state,
+            ...state
+        };
+    };
+}

package/src/modules/dxUtils/list/list.ts

@@ -0,0 +1,11 @@
+import { v4 as createUuid } from "uuid";
+
+export const getListWithUuids = <T extends object>(
+    list: T[],
+    idKey?: string
+) => {
+    return list.map((listItem) => ({
+        ...listItem,
+        [idKey || "id"]: createUuid()
+    }));
+};