@salesforcedevs/dx-components 0.17.0 → 0.17.1-review-diff1

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

@@ -0,0 +1,10 @@
+<template>
+    <div class={containerClassName} role="region" aria-live="polite">
+        <slot
+            class={slotClassName}
+            onslotchange={handleSlotChange}
+            onstepincrement={handleStepIncrement}
+            onstepdecrement={handleStepDecrement}
+        ></slot>
+    </div>
+</template>

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

@@ -0,0 +1,334 @@
+/* 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 containerScrollToId = "";
+    @api forceInitiallyVisible = false;
+    @api initialStepIndex: string | undefined;
+    @api optimizePositionAfterAnimation = false;
+    @api sessionStorageId = "";
+    @api useHistory = false;
+
+    private currentStepIndex = 0;
+    private defaultScrollRestorationValue = history.scrollRestoration;
+    private didInitiallyBecomeVisible = false;
+    private isHiddenForInitialAnimation = true;
+    private measuredStepHeights: number[] = [];
+    private slotClassName = "step-sequence-steps-slot";
+    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"; // Step component must override scroll behavior to work properly with history and maintain scrollTo behavior of component
+            window.addEventListener("popstate", this.handleHistoryPopstate);
+            window.addEventListener("hashchange", this.handleHashChange);
+        }
+
+        if (this.sessionStorageId) {
+            sessionStorage.setItem(
+                this.sessionStorageId,
+                JSON.stringify({
+                    currentStepIndex: this.currentStepIndex
+                })
+            );
+        }
+
+        if (this.animateTransitions) {
+            this.addEventListener("transitionend", this.handleTransitionEnd);
+        } else {
+            this.isHiddenForInitialAnimation = false;
+        }
+    }
+
+    renderedCallback() {
+        // If we're not animating and we want to force visible, we can do it right on first render.
+        // If we're animating, this is handled after the initial animations end (to avoid seeing weird flashes).
+        if (this.forceInitiallyVisible && !this.didInitiallyBecomeVisible) {
+            this.didInitiallyBecomeVisible = true;
+
+            if (!this.animateTransitions) {
+                this.scrollToStepTop();
+            } else {
+                setTimeout(() => {
+                    this.isHiddenForInitialAnimation = false;
+                    requestAnimationFrame(() => {
+                        this.scrollToStepTop();
+                    });
+                }, 400);
+            }
+        }
+    }
+
+    disconnectedCallback() {
+        window.removeEventListener("popstate", this.handleHistoryPopstate);
+        window.removeEventListener("hashchange", this.handleHashChange);
+        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");
+        // Remove temporary minHeight set for nice animations, so that component will resize properly:
+        this.template.querySelector(
+            ".step-sequence-container"
+        )!.style.minHeight = "auto";
+    };
+
+    // NOTE: This is the ultimate coordinator of step transitions; it should all go through here.
+    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;
+        }
+
+        if (this.optimizePositionAfterAnimation) {
+            this.scrollToStepTop();
+        }
+
+        if (!this.animateTransitions) {
+            this.steps[this.currentStepIndex].className = "";
+            this.steps[nextStepIndex].className = "visible active-step";
+        } else {
+            // Set minHeight temporarily to ensure nice animations:
+            this.template.querySelector(
+                ".step-sequence-container"
+            )!.style.minHeight = `${
+                this.measuredStepHeights[nextStepIndex] ||
+                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";
+            }
+            // Ensure focus cannot drift to invisible off-screen components
+            this.steps[nextStepIndex].removeAttribute("inert");
+            this.steps[this.currentStepIndex].setAttribute("inert", "true");
+            this.steps[nextStepIndex].focus();
+        }
+
+        if (this.useHistory && updateHistory) {
+            if (typeof history.state?.currentStepIndex !== "number") {
+                // This is a "new" interaction with the step component, so we store the current
+                // component state in history so that going back from the next step works right
+                history.pushState(
+                    {
+                        currentStepIndex: this.currentStepIndex
+                    },
+                    "",
+                    this.containerScrollToId // update browser hash for correct "feel" to in-page navigation
+                );
+            }
+            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)
+            );
+        }
+    }
+
+    @api
+    public remeasureSteps() {
+        this.measuredStepHeights = this.steps.map((step) => step.clientHeight);
+    }
+
+    private isStepIndexWithinBounds(stepIndex: number) {
+        return stepIndex >= 0 && stepIndex < this.steps.length;
+    }
+
+    handleHistoryPopstate = ({ state }: PopStateEvent) => {
+        if (
+            typeof state?.currentStepIndex !== "number" ||
+            state.currentStepIndex === this.currentStepIndex
+        ) {
+            // This history item is not a step change, so bail early.
+            return;
+        }
+
+        this.remeasureSteps();
+        this.changeActiveStep(state.currentStepIndex, false);
+        this.scrollToStepTop();
+    };
+
+    handleHashChange = ({ newURL }: HashChangeEvent) => {
+        const newHash = new URL(newURL).hash;
+        const oldScrollValue = history.state?.scroll?.value;
+
+        if (typeof oldScrollValue === "number") {
+            window.scrollTo({
+                top: oldScrollValue
+            });
+        } else if (newHash) {
+            document.querySelector(newHash)?.scrollIntoView();
+        } else {
+            // No hash and no old scroll value means this was the initial history item
+            window.scrollTo({
+                top: 0
+            });
+        }
+    };
+
+    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;
+
+        if (slot.className !== this.slotClassName) {
+            return;
+        }
+
+        this.steps = slot.assignedElements() as HTMLElement[];
+
+        this.steps.forEach((step, index) => {
+            if (this.animateTransitions) {
+                this.initializeStepAnimationClasses(
+                    this.currentStepIndex,
+                    step,
+                    index
+                );
+                if (index !== this.currentStepIndex) {
+                    // Ensure focus cannot drift to invisible off-screen components
+                    step.setAttribute("inert", "true");
+                }
+            }
+        });
+
+        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/dx/tab/tab.css

@@ -1,4 +1,4 @@
-@import "helpers/reset";
+@import "dxHelpers/reset";
 
 a {
     text-decoration: none;
@@ -11,22 +11,31 @@ a {
     );
 
     position: relative;
+    height: var(--dx-g-spacing-3xl);
+    border-radius: var(--dx-g-spacing-sm) var(--dx-g-spacing-sm) 0 0;
+}
+
+.nav-list-item_default {
+    padding: var(--dx-g-spacing-smd) var(--dx-g-spacing-lg);
+    justify-content: center;
     display: flex;
-    align-items: center;
-    height: var(--dx-g-spacing-xl);
-    font-family: var(--dx-g-font-display);
-    white-space: nowrap;
+    font-family: var(--dx-g-font-sans);
+    font-size: var(--dx-g-text-base);
+    line-height: var(--dx-g-spacing-lg);
+    font-weight: var(--dx-g-font-normal);
+}
+
+.nav-list-item_default:hover {
+    border-radius: var(--dx-g-spacing-sm) var(--dx-g-spacing-sm) 0 0;
+    background: var(--dx-g-cloud-blue-vibrant-95);
     color: var(--dx-g-blue-vibrant-20);
-    transition: var(--dx-g-transition-hue-1x);
-    cursor: pointer;
-    outline-offset: -1px;
 }
 
-.nav-list-item_default {
-    border: 0;
-    border-radius: var(--dx-g-spacing-md);
-    font-size: var(--dx-g-text-sm);
-    padding: 0 var(--horizontal-spacing);
+.nav-list-item_default:focus-visible {
+    border-radius: var(--dx-g-spacing-sm) var(--dx-g-spacing-sm) 0 0;
+    background: var(--dx-g-cloud-blue-vibrant-95);
+    color: var(--dx-g-blue-vibrant-20);
+    outline: 2px solid var(--dx-g-blue-vibrant-60);
 }
 
 .nav-list-item_small {
@@ -38,10 +47,6 @@ a {
     margin: 0 var(--horizontal-spacing);
 }
 
-.nav-list-item > span {
-    margin-top: var(--dx-g-spacing-xs);
-}
-
 button.nav-list-item_default > dx-icon {
     margin-left: var(--dx-g-spacing-sm);
 }
@@ -50,8 +55,6 @@ button.nav-list-item_small > dx-icon {
     margin-left: var(--dx-g-spacing-xs);
 }
 
-.nav-list-item_default:hover,
-.nav-list-item_default:active,
 :host([aria-expanded="true"]) button.nav-list-item_default {
     background: var(
         --dx-g-brand-current-button-color-background-inactive,
@@ -80,11 +83,26 @@ button.nav-list-item:active > dx-icon,
 }
 
 .nav-list-item_default.state-active {
-    background: var(
-        --dx-g-brand-current-button-color-background-active,
-        var(--dx-g-brand-default-button-color-background-active)
-    );
-    color: var(--dx-g-brand-current-color, var(--dx-g-brand-default-color));
+    color: var(--dx-g-blue-vibrant-50);
+    font-weight: var(--dx-g-font-bold);
+    padding: var(--dx-g-spacing-smd) var(--dx-g-spacing-lg)
+        var(--dx-g-spacing-sm) var(--dx-g-spacing-lg);
+    border-bottom: var(--dx-g-spacing-xs) solid var(--dx-g-blue-vibrant-50);
+}
+
+.nav-list-item_default.state-active:hover {
+    border-radius: var(--dx-g-spacing-sm) var(--dx-g-spacing-sm) 0 0;
+    background: var(--dx-g-cloud-blue-vibrant-95);
+    border-bottom: var(--dx-g-spacing-xs) solid var(--dx-g-blue-vibrant-20);
+    color: var(--dx-g-blue-vibrant-20);
+}
+
+.nav-list-item_default.state-active:focus-visible {
+    border-radius: var(--dx-g-spacing-sm) var(--dx-g-spacing-sm) 0 0;
+    background: var(--dx-g-cloud-blue-vibrant-95);
+    border-bottom: var(--dx-g-spacing-xs) solid var(--dx-g-blue-vibrant-20);
+    outline: 2px solid var(--dx-g-blue-vibrant-60);
+    color: var(--dx-g-blue-vibrant-20);
 }
 
 @media (max-width: 1160px) {
@@ -104,3 +122,10 @@ button.nav-list-item:active > dx-icon,
         );
     }
 }
+
+@media (max-width: 768px) {
+    .nav-list-item {
+        height: var(--dx-g-spacing-3xl);
+        display: flex;
+    }
+}

package/src/modules/dx/tab/tab.ts

@@ -1,8 +1,8 @@
 import { LightningElement, api } from "lwc";
-import { track } from "dx/instrumentation";
+import { track } from "dxUtils/analytics";
 import cx from "classnames";
 import { TabVariant } from "typings/custom";
-import { normalizeBoolean } from "utils/normalizers";
+import { normalizeBoolean } from "dxUtils/normalizers";
 
 export default class Tab extends LightningElement {
     @api label: string | null = null;
@@ -32,9 +32,20 @@ export default class Tab extends LightningElement {
 
     private sendGtm(e: PointerEvent) {
         track(e.currentTarget!, "custEv_topNavLinkClick", {
-            navHeading: this.label || undefined,
-            clickText: this.href || undefined,
-            pageLocation: window.location.pathname
+            click_text: this.label || undefined,
+            click_url: this.href || undefined,
+            nav_level: "1",
+            nav_item: this.label || undefined,
+            element_type: "link",
+            nav_type: "global"
+        });
+
+        track(e.currentTarget!, "custEv_linkClick", {
+            click_text: this.label,
+            element_title: this.label,
+            click_url: this.href,
+            element_type: "link",
+            content_category: "cta"
         });
     }
 

package/src/modules/dx/tabPanel/tabPanel.css

@@ -0,0 +1,20 @@
+@import "dxHelpers/reset";
+
+:host {
+    --dx-c-tab-panel-margin-top: var(--dx-g-spacing-3xl);
+    --dx-c-tab-panel-gap: var(--dx-g-spacing-md);
+}
+
+.tabpanel {
+    display: none;
+}
+
+.tabpanel-active {
+    display: block;
+}
+
+@media screen and (max-width: 640px) {
+    .tabpanel-active {
+        --dx-c-tab-panel-margin-top: 36px;
+    }
+}

package/src/modules/dx/tabPanel/tabPanel.html

@@ -0,0 +1,13 @@
+<template>
+    <div
+        role="tabpanel"
+        part="tabpanel"
+        id={panelId}
+        class={className}
+        tabindex={activeTabIndex}
+        aria-labelledby={tabId}
+        hidden={panelHidden}
+    >
+        <slot></slot>
+    </div>
+</template>

package/src/modules/dx/tabPanel/tabPanel.ts

@@ -0,0 +1,27 @@
+import { LightningElement, api } from "lwc";
+import cx from "classnames";
+export default class TabPanel extends LightningElement {
+    @api index!: number;
+    @api groupId!: string;
+    @api active: boolean = false;
+
+    private get tabId() {
+        return `tabs--${this.groupId}--tab--${this.index}`;
+    }
+
+    private get panelId() {
+        return `tabs--${this.groupId}--panel--${this.index}`;
+    }
+
+    private get activeTabIndex() {
+        return this.active ? 0 : -1;
+    }
+
+    private get className() {
+        return cx("tabpanel", this.active && "tabpanel-active");
+    }
+
+    private get panelHidden() {
+        return !this.active;
+    }
+}

package/src/modules/dx/tabPanelItem/tabPanelItem.css

@@ -0,0 +1,54 @@
+@import "dxHelpers/reset";
+
+.tab {
+    color: var(--dx-g-blue-vibrant-20);
+    font-family: var(--dx-g-font-sans);
+    font-size: var(--dx-g-text-base);
+    font-weight: var(--dx-g-font-normal);
+    line-height: var(--dx-g-spacing-lg);
+    padding: var(--dx-g-spacing-sm) var(--dx-g-spacing-lg);
+    border-top-left-radius: var(--dx-g-spacing-sm);
+    border-top-right-radius: var(--dx-g-spacing-sm);
+    border-bottom: var(--dx-g-spacing-xs) solid transparent;
+    white-space: nowrap;
+    margin-right: var(--dx-g-spacing-md);
+}
+
+button:focus {
+    outline: none;
+}
+
+.tab:hover {
+    background-color: var(--dx-g-blue-vibrant-95);
+    color: var(--dx-g-blue-vibrant-20);
+}
+
+.tab-active {
+    color: var(--dx-g-blue-vibrant-50);
+    font-weight: var(--dx-g-font-bold);
+    border-bottom: var(--dx-g-spacing-xs) solid var(--dx-g-blue-vibrant-50);
+}
+
+.tab-active:focus-visible,
+.tab-active:hover {
+    border-bottom: var(--dx-g-spacing-xs) solid var(--dx-g-blue-vibrant-20);
+    color: var(--dx-g-blue-vibrant-20);
+}
+
+.tab:focus-visible {
+    background: var(--dx-g-cloud-blue-vibrant-95);
+    color: var(--dx-g-blue-vibrant-20);
+    outline: 2px solid var(--dx-g-blue-vibrant-60);
+}
+
+@media screen and (max-width: 640px) {
+    .tab {
+        font-size: var(--dx-g-text-base);
+        font-family: var(--dx-g-font-sans);
+        font-weight: var(--dx-g-font-normal);
+    }
+
+    .tab-active {
+        font-weight: var(--dx-g-font-bold);
+    }
+}