@salesforcedevs/dx-components 1.3.136 → 1.3.139

package/lwc.config.json

@@ -77,6 +77,8 @@
         "dx/skipNavLink",
         "dx/socials",
         "dx/spinner",
+        "dx/stepSequence",
+        "dx/stepSequenceStep",
         "dx/tabPanel",
         "dx/tabPanelList",
         "dx/tbidAvatarButton",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@salesforcedevs/dx-components",
-    "version": "1.3.136",
+    "version": "1.3.139",
     "description": "DX Lightning web components",
     "license": "MIT",
     "engines": {
@@ -40,5 +40,5 @@
         "eventsourcemock": "^2.0.0",
         "luxon": "^3.1.0"
     },
-    "gitHead": "c076bf146988d61bedc4710e6443a18d7e27b1ca"
+    "gitHead": "0b5ea068f074b865e1f5e35a92ddd97af21fe6a4"
 }

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,46 @@
+/*
+  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%;
+}
+
+.hidden {
+    visibility: hidden;
+}
+
+.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,197 @@
+/* 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 initialStepIndex: string | undefined;
+    @api animateTransitions = false;
+
+    private currentStepIndex = 0;
+    private steps: Array<HTMLElement> = [];
+    private isHiddenForInitialAnimation = true;
+
+    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;
+        }
+        history.replaceState(
+            {
+                currentStepIndex: this.currentStepIndex
+            },
+            ""
+        );
+        window.addEventListener("popstate", this.handleHistoryPopstate);
+        if (this.animateTransitions) {
+            this.addEventListener("transitionend", this.handleTransitionEnd);
+        } else {
+            this.isHiddenForInitialAnimation = false;
+        }
+    }
+
+    disconnectedCallback() {
+        window.removeEventListener("popstate", this.handleHistoryPopstate);
+        this.removeEventListener("transitionend", this.handleTransitionEnd);
+    }
+
+    // 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;
+        }
+
+        if (this.isHiddenForInitialAnimation) {
+            this.isHiddenForInitialAnimation = false;
+        }
+
+        // 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");
+    };
+
+    private changeActiveStep(nextStepIndex: number, updateHistory = true) {
+        if (nextStepIndex === this.currentStepIndex) {
+            // Should never happen, but covering all logical bases. Nothing to do here.
+            return;
+        }
+
+        if (!this.animateTransitions) {
+            this.steps[this.currentStepIndex].className = "";
+            this.steps[nextStepIndex].className = "visible active-step";
+        } else {
+            // 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 (updateHistory) {
+            history.pushState(
+                {
+                    currentStepIndex: nextStepIndex
+                },
+                ""
+            );
+        }
+        this.currentStepIndex = nextStepIndex;
+    }
+
+    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";
+        }
+    }
+
+    // This method is available in case there are scenarios where a sequence needs to "jump" in some cases
+    @api
+    public jumpToStep(stepIndex: number) {
+        if (stepIndex < 0 || stepIndex >= this.steps.length) {
+            // illegal value; ignore
+            return;
+        }
+
+        this.changeActiveStep(stepIndex);
+
+        if (this.animateTransitions) {
+            this.steps.forEach((step, index) =>
+                this.initializeStepAnimationClasses(stepIndex, step, index)
+            );
+        }
+    }
+
+    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[];
+        if (!this.animateTransitions) {
+            this.steps[this.currentStepIndex].className = "visible active-step";
+        } else {
+            // For transition animations to be visible, the container must have a height that will
+            // keep the components visible as they transition in and out. Currently this component
+            // will have at least the height of the "tallest" slotted element.
+            let minHeight = 0;
+            this.steps.forEach((step, index) => {
+                if (step.clientHeight > minHeight) {
+                    minHeight = step.clientHeight;
+                }
+                this.initializeStepAnimationClasses(
+                    this.currentStepIndex,
+                    step,
+                    index
+                );
+            });
+            if (minHeight > 0) {
+                this.template.querySelector(
+                    ".step-sequence-container"
+                )!.style.minHeight = `${minHeight}px`;
+            }
+        }
+    }
+}

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
+            })
+        );
+    }
+}