@salesforcedevs/dx-components 0.26.1-alpha0.4 → 0.26.2

package/src/modules/dx/dropdown/dropdown.ts

@@ -0,0 +1,182 @@
+import { Option, PopperPlacement } from "typings/custom";
+import { LightningElement, api, track } from "lwc";
+import cx from "classnames";
+import get from "lodash.get";
+import { deepmapOptions } from "utils-internal/options";
+import { toJson } from "utils/normalizers";
+
+interface DropdownOption extends Option {
+    // link that gets shown as a highlighted link at end of option group
+    calloutLink?: {
+        href: string;
+        target?: string;
+        label: string;
+    };
+}
+
+export default class Dropdown extends LightningElement {
+    @api value: string | null = null; // "active option" id
+    @api valuePath: string = "id"; // path to match for the active value (useful for url matching)
+    @api stayOpenAfterChange?: boolean = false;
+
+    // props forwarded to popover:
+    @api ariaLabel: string | null = null;
+    @api tempId: string | null = null;
+    @api offset?: "small" | "medium";
+    @api open: boolean | null = null;
+    @api pagePadding?: number = 16; // padding between dropdown and the edge of the page
+    @api placement?: PopperPlacement = "bottom-start";
+    @api small?: boolean = false;
+    @api openOnHover?: boolean = false; // dropdown opens/closes with hover
+    @api width?: string | null = null;
+    @api fullWidth?: boolean | null;
+    @api navItemLabel: string | null = null;
+
+    // props forwarded to dropdown option
+    @api analyticsEvent: string | null = null;
+
+    @api
+    get options() {
+        return deepmapOptions(this._options, (option: DropdownOption) => ({
+            ...option,
+            active: this.value === get(option, this.valuePath),
+            keyValue: get(option, this.valuePath)
+        }));
+    }
+    set options(value: DropdownOption[]) {
+        this._options = toJson(value);
+    }
+
+    @api
+    get focusedValue() {
+        return this._focusedValue;
+    }
+
+    @track
+    private _options!: DropdownOption[];
+
+    // PRIVATE VARS
+
+    private _focusedValue: string | null = null;
+    private popoverEl: HTMLElement | null = null;
+
+    constructor() {
+        super();
+
+        // @ts-ignore
+        this.addEventListener("keydown", this.onKeyDown);
+    }
+
+    // GETTERS
+
+    private get role() {
+        return this.areOptionsEmpty ? null : "menu";
+    }
+
+    private get className() {
+        return cx(
+            this.isNested && "menu-nested",
+            this.isNested && this.options.length >= 2 && "menu-nested-2-col",
+            this.offset && `menu-offset-${this.offset}`,
+            this.areOptionsEmpty && "menu-hidden"
+        );
+    }
+
+    private get isNested() {
+        return this.options.some((option) => !!option.options);
+    }
+
+    private get optionsElements() {
+        return this.template.querySelectorAll("dx-dropdown-option");
+    }
+
+    private get areOptionsEmpty() {
+        return this.options.length === 0;
+    }
+
+    // CLASS FNS
+
+    private onKeyDown = (e: KeyboardEvent) => {
+        switch (e.key) {
+            case "ArrowDown":
+                e.preventDefault();
+                this.incrementOptionFocus(1);
+                break;
+            case "ArrowUp":
+                e.preventDefault();
+                this.incrementOptionFocus(-1);
+                break;
+            default:
+        }
+    };
+
+    private onOptionClick(e: CustomEvent) {
+        if (e.detail !== this.value) {
+            this.dispatchEvent(new CustomEvent("change", { detail: e.detail }));
+        }
+        if (!this.stayOpenAfterChange && this.popoverEl) {
+            this.popoverEl.closePopover();
+        }
+    }
+
+    private onOptionFocus(e: PointerEvent) {
+        if (e.target) {
+            // @ts-ignore
+            this._focusedValue = e.target.option.id;
+        }
+    }
+
+    private findOptionElementIndex(value: string) {
+        return Array.from(this.optionsElements).findIndex(
+            // @ts-ignore
+            (el) => el.option.id === value
+        );
+    }
+
+    private incrementOptionFocus(indexChange: number) {
+        if (!this._focusedValue) {
+            this.focusDefaultOption();
+            return;
+        }
+
+        const focusedOptionIndex = this.findOptionElementIndex(
+            this._focusedValue
+        );
+
+        let nextIndex = focusedOptionIndex + indexChange;
+        if (nextIndex < 0) {
+            nextIndex = this.optionsElements.length - 1;
+        }
+        if (nextIndex >= this.optionsElements.length) {
+            nextIndex = 0;
+        }
+
+        const element = this.optionsElements[nextIndex];
+        if (element) {
+            element.focus();
+        }
+    }
+
+    private onClose(): void {
+        this._focusedValue = null;
+    }
+
+    private focusDefaultOption() {
+        const defaultIndex = this.value
+            ? this.findOptionElementIndex(this.value)
+            : 0;
+
+        const optionToFocus: any =
+            this.optionsElements[defaultIndex < 0 ? 0 : defaultIndex];
+        if (optionToFocus) {
+            optionToFocus.focus();
+            this._focusedValue = optionToFocus.option.id;
+        }
+    }
+
+    renderedCallback() {
+        if (!this.popoverEl) {
+            this.popoverEl = this.template.querySelector("dx-popover");
+        }
+    }
+}

package/src/modules/dx/dropdownOption/__tests__/dropdownOption.test.ts

@@ -0,0 +1,112 @@
+import DropdownOption from "dx/dropdownOption";
+import { createRenderComponent } from "utils-internal/tests";
+import { MOCK_BUTTON_PROPS, MOCK_LINK_PROPS } from "./mockProps";
+import * as instrumentation from "dx/instrumentation";
+
+const TAG = "dx-dropdown-option";
+const render = createRenderComponent(TAG, DropdownOption);
+
+const appendToMenu = (element: HTMLElement) => {
+    const menu = document.createElement("DIV");
+    document.body.appendChild(menu);
+    menu.setAttribute("role", "menu");
+    menu.appendChild(element);
+};
+
+describe(TAG, () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+
+    it("renders a button by default", () => {
+        const component = render(MOCK_BUTTON_PROPS);
+        expect(component.shadowRoot.querySelector("button")).not.toBeNull();
+
+        appendToMenu(component);
+        return expect(component).toBeAccessible();
+    });
+
+    it("renders the correct label, description, and img", () => {
+        const component = render(MOCK_BUTTON_PROPS);
+        const label =
+            component.shadowRoot.querySelector(".option_label").textContent;
+        expect(label).toEqual(MOCK_BUTTON_PROPS.option.label);
+
+        const description = component.shadowRoot.querySelector(
+            ".option_description"
+        ).textContent;
+        expect(description).toEqual(MOCK_BUTTON_PROPS.option.description);
+
+        const img = component.shadowRoot.querySelector(".option_icon");
+        expect(img).not.toBeNull();
+
+        appendToMenu(component);
+        return expect(component).toBeAccessible();
+    });
+
+    it("renders a link with the correct href when given link props", () => {
+        const component = render(MOCK_LINK_PROPS);
+
+        const href = component.shadowRoot
+            .querySelector("a")
+            .getAttribute("href");
+        expect(href).toEqual(MOCK_LINK_PROPS.option.link.href);
+
+        appendToMenu(component);
+        return expect(component).toBeAccessible();
+    });
+
+    it("applies the active class correctly", () => {
+        const component = render({ ...MOCK_BUTTON_PROPS, active: true });
+        const optionEl = component.shadowRoot.querySelector(".option-active");
+        expect(optionEl).not.toBeNull();
+
+        appendToMenu(component);
+        return expect(component).toBeAccessible();
+    });
+
+    it("can focus itself", () => {
+        const component = render(MOCK_BUTTON_PROPS);
+        component.focus();
+
+        expect(document.activeElement).toEqual(component);
+    });
+
+    it("onClick function is fired when button is clicked", () => {
+        const onClickMock = jest.fn();
+        const component = render({
+            ...MOCK_BUTTON_PROPS,
+            onclick: onClickMock
+        });
+
+        const option = component.shadowRoot.querySelector(".option");
+        option.click();
+
+        expect(onClickMock).toBeCalled();
+    });
+
+    it("fires analytics when given an analytics event", () => {
+        const track = jest.spyOn(instrumentation, "track");
+
+        const component = render({
+            ...MOCK_BUTTON_PROPS,
+            analyticsEvent: "mock"
+        });
+
+        const option = component.shadowRoot.querySelector(".option");
+        option.click();
+
+        expect(track).toHaveBeenCalledTimes(1);
+    });
+
+    it("doesn't fire analytics when not given an analytics event", () => {
+        const track = jest.spyOn(instrumentation, "track");
+
+        const component = render(MOCK_BUTTON_PROPS);
+
+        const option = component.shadowRoot.querySelector(".option");
+        option.click();
+
+        expect(track).not.toHaveBeenCalled();
+    });
+});

package/src/modules/dx/dropdownOption/__tests__/mockProps.ts

@@ -0,0 +1,20 @@
+export const MOCK_BUTTON_PROPS = {
+    option: {
+        id: "documentation",
+        label: "Documentation",
+        description: "Documentation is kewl",
+        iconSymbol: "heroku",
+        iconSprite: "salesforcebrand"
+    }
+};
+
+export const MOCK_LINK_PROPS = {
+    option: {
+        id: "documentation",
+        label: "Documentation",
+        link: {
+            href: "/documentation",
+            target: null
+        }
+    }
+};

package/src/modules/dx/dropdownOption/dropdownOption.css

@@ -0,0 +1,61 @@
+@import "helpers/reset";
+
+.option {
+    display: flex;
+    font-family: var(--dx-g-font-sans);
+    width: 100%;
+    padding: var(--dx-g-spacing-sm);
+    font-size: var(--dx-g-text-sm);
+    border-radius: var(--dx-g-spacing-xs);
+    transition: var(--dx-g-transition-hue-1x);
+    align-items: center;
+    outline: none !important;
+}
+
+.option:focus {
+    box-shadow: inset 0 0 0 1px var(--dx-g-blue-vibrant-50);
+}
+
+.option:active {
+    background: var(--dx-g-blue-vibrant-95) !important;
+}
+
+.option:not(.option-active):hover {
+    background: var(--dx-g-gray-95);
+}
+
+.option-active {
+    background: var(--dx-g-blue-vibrant-95);
+}
+
+.option_details {
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
+    font-family: var(--dx-g-font-sans);
+    font-size: var(--dx-g-text-sm);
+    text-align: left;
+}
+
+.option_label {
+    color: var(--dx-g-blue-vibrant-50);
+    display: flex;
+    align-items: center;
+    font-weight: var(--dx-g-font-bold);
+    font-size: var(--dx-c-dropdown-option-font-size, var(--dx-g-text-base));
+}
+
+.option_label > *:last-child {
+    margin-left: var(--dx-g-spacing-sm);
+}
+
+.option_description {
+    color: var(--dx-g-gray-30);
+    margin-top: var(--dx-g-spacing-xs);
+    line-height: 18px;
+}
+
+.option_icon {
+    margin-right: var(--dx-g-spacing-md);
+    flex-shrink: 0;
+}

package/src/modules/dx/dropdownOption/dropdownOption.html

@@ -0,0 +1,53 @@
+<template>
+    <a
+        if:true={option.link}
+        class={className}
+        href={option.link.href}
+        target={option.link.target}
+        key={option.id}
+        role="menuitem"
+        tabindex="-1"
+        onclick={onClick}
+    >
+        <dx-icon
+            class="option_icon"
+            symbol={option.iconSymbol}
+            sprite={option.iconSprite}
+            if:true={option.iconSymbol}
+            size="large"
+        ></dx-icon>
+        <div class="option_details">
+            <div class="option_label">
+                {option.label}
+                <dx-icon
+                    symbol="new_window"
+                    if:true={option.link.target}
+                ></dx-icon>
+            </div>
+            <div if:true={option.description} class="option_description">
+                {option.description}
+            </div>
+        </div>
+    </a>
+    <button
+        if:false={option.link}
+        class={className}
+        role="menuitem"
+        tabindex="-1"
+        onclick={onClick}
+    >
+        <dx-icon
+            class="option_icon"
+            symbol={option.iconSymbol}
+            sprite={option.iconSprite}
+            if:true={option.iconSymbol}
+            size="large"
+        ></dx-icon>
+        <div class="option_details">
+            <div class="option_label">{option.label}</div>
+            <div if:true={option.description} class="option_description">
+                {option.description}
+            </div>
+        </div>
+    </button>
+</template>

package/src/modules/dx/dropdownOption/dropdownOption.ts

@@ -0,0 +1,39 @@
+import { LightningElement, api } from "lwc";
+import cx from "classnames";
+import { Option } from "typings/custom";
+import { track } from "dx/instrumentation";
+
+export default class DropdownOption extends LightningElement {
+    @api option!: Option;
+    @api keyValue!: string;
+    @api active: boolean = false;
+    @api navItemLabel: String | null = null;
+    @api analyticsEvent: string | null = null;
+
+    @api focus() {
+        const option = this.template.querySelector(".option");
+        if (!option) {
+            return;
+        }
+        option.focus();
+    }
+
+    private get className(): string {
+        return cx("option", this.active && "option-active");
+    }
+
+    private onClick(e: PointerEvent) {
+        this.dispatchEvent(
+            new CustomEvent("select", { detail: this.keyValue })
+        );
+
+        if (this.analyticsEvent && e.currentTarget) {
+            track(e.currentTarget, this.analyticsEvent, {
+                navHeading: this.navItemLabel || undefined,
+                navSubHeading: this.option.label || undefined,
+                clickText: this.keyValue || undefined,
+                pageLocation: window.location.pathname || undefined
+            });
+        }
+    }
+}

package/src/modules/dx/emptyState/__tests__/emptyState.test.ts

@@ -0,0 +1,52 @@
+import EmptyState from "dx/emptyState";
+import { createRenderComponent } from "utils-internal/tests";
+import mockProps from "./mockProps";
+
+const TAG = "dx-empty-state";
+const render = createRenderComponent(TAG, EmptyState);
+
+describe(TAG, () => {
+    it("renders", () => {
+        const element = render(mockProps);
+        const container: HTMLElement =
+            element.shadowRoot.querySelector(".container");
+        const renderedTitle: HTMLElement =
+            element.shadowRoot.querySelector("h3");
+        const renderedSubTitle: HTMLElement =
+            element.shadowRoot.querySelector("p");
+        const image: HTMLImageElement = element.shadowRoot.querySelector("img");
+
+        expect(renderedTitle).not.toBeNull();
+        expect(renderedSubTitle).not.toBeNull();
+        expect(container).not.toBeNull();
+        expect(image).not.toBeNull();
+
+        expect(renderedSubTitle.textContent).toEqual(mockProps.subtitle);
+        expect(renderedTitle.textContent).toEqual(mockProps.title);
+
+        return expect(element).toBeAccessible();
+    });
+
+    it("renders as the large variant by default", () => {
+        const element = render(mockProps);
+        const container: HTMLElement =
+            element.shadowRoot.querySelector(".container");
+        const image: HTMLImageElement = element.shadowRoot.querySelector("img");
+        expect(container.classList).toContain("size-large");
+        expect(container.classList).toHaveLength(2);
+        expect(image.src).not.toContain("-small.svg");
+    });
+
+    it("renders as the small variant when specified", () => {
+        const element = render({
+            ...mockProps,
+            size: "small"
+        });
+        const container: HTMLElement =
+            element.shadowRoot.querySelector(".container");
+        const image: HTMLImageElement = element.shadowRoot.querySelector("img");
+        expect(container.classList).toContain("size-small");
+        expect(container.classList).toHaveLength(2);
+        expect(image.src).toContain("-small.svg");
+    });
+});

package/src/modules/dx/emptyState/__tests__/mockProps.ts

@@ -0,0 +1,4 @@
+export default {
+    title: "No matches",
+    subtitle: "Try searching for different words"
+};

package/src/modules/dx/emptyState/emptyState.css

@@ -0,0 +1,64 @@
+@import "helpers/reset";
+@import "helpers/text";
+
+:host {
+    --dx-c-empty-state-background: var(--dx-g-gray-95);
+    --dx-c-empty-state-image-width: 600px;
+
+    width: 100%;
+}
+
+.container {
+    position: relative;
+    background: var(--dx-c-empty-state-background);
+    border-radius: var(--dx-g-spacing-md);
+    padding: var(--dx-g-spacing-2xl) 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    overflow: hidden;
+}
+
+img {
+    width: var(--dx-c-empty-state-image-width);
+    min-width: var(--dx-c-empty-state-image-width);
+}
+
+.size-small img {
+    max-width: 250px;
+    min-width: unset;
+    width: calc(100% - 40px);
+}
+
+.text {
+    position: absolute;
+    top: 35%;
+    min-height: 15%;
+    left: 0;
+    width: 100%;
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    flex-direction: column;
+    text-align: center;
+    padding: 0 var(--dx-g-spacing-xl);
+}
+
+.size-small .text {
+    top: 40%;
+}
+
+.title {
+    font-size: var(--dx-g-text-2xl);
+}
+
+.size-small .title {
+    font-size: var(--dx-g-text-base);
+    white-space: nowrap;
+}
+
+.subtitle {
+    padding-top: var(--dx-g-spacing-sm);
+    color: var(--dx-g-text-heading-color);
+    font-weight: bold;
+}

package/src/modules/dx/emptyState/emptyState.html

@@ -0,0 +1,9 @@
+<template>
+    <div class={containerClassName} part="container">
+        <img src={imageAssetPath} alt="Mountains" />
+        <div class="text">
+            <h3 class="title dx-text-heading-3">{title}</h3>
+            <p class="subtitle dx-text-body-2" if:true={subtitle}>{subtitle}</p>
+        </div>
+    </div>
+</template>

package/src/modules/dx/emptyState/emptyState.stories.ts

@@ -0,0 +1,45 @@
+import { html } from "lit-html";
+
+export default {
+    title: "dx/dx-empty-state",
+    component: "dx-empty-state"
+};
+
+const createStyles = () => html`
+    <style>
+        body {
+            padding: 12px !important;
+        }
+        .title {
+            font-weight: bold;
+            margin: 24px;
+        }
+        #styled {
+            --dx-c-empty-state-background: var(--sds-g-gray-2);
+            --dx-c-empty-state-image-width: 400px;
+            width: 300px;
+            display: block;
+        }
+        .small-container {
+            width: 250px;
+        }
+    </style>
+`;
+
+const title = (value: string) => html`<p class="title">${value}</p>`;
+
+export const Base = () => html`
+    ${createStyles()} ${title("Default")}
+    <dx-empty-state
+        title="Beep boop. That did not compute."
+        subtitle="No results"
+    ></dx-empty-state>
+
+    ${title("No subtitle and customized with style hooks")}
+    <dx-empty-state id="styled" title="No Results"></dx-empty-state>
+
+    ${title("Small variant")}
+    <div class="small-container">
+        <dx-empty-state title="No Results" size="small"></dx-empty-state>
+    </div>
+`;

package/src/modules/dx/emptyState/emptyState.ts

@@ -0,0 +1,20 @@
+import { LightningElement, api } from "lwc";
+import { EmptyStateSize } from "typings/custom";
+
+export default class EmptyState extends LightningElement {
+    @api title: string = "";
+    @api subtitle?: string | null = null;
+    @api size?: EmptyStateSize = "large";
+
+    get containerClassName() {
+        return `container ${
+            !this.size || this.size === "large" ? "size-large" : "size-small"
+        }`;
+    }
+
+    get imageAssetPath() {
+        return `/assets/svg/docs-empty-state${
+            this.size === "small" ? "-small" : ""
+        }.svg`;
+    }
+}