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

package/src/modules/dx/input/input.ts

@@ -0,0 +1,238 @@
+import { LightningElement, api } from "lwc";
+import cx from "classnames";
+import { IconSize, IconSymbol } from "typings/custom";
+import { isMac } from "utils-internal/devices";
+import { isValidEmail } from "./validators";
+
+type ValidatorMap = {
+    [key: string]: {
+        validator: (value: string | null) => boolean;
+        errorMessage: string;
+    };
+};
+
+const typeValidatorMap: ValidatorMap = {
+    email: {
+        validator: isValidEmail,
+        errorMessage: "Enter valid email"
+    }
+};
+export default class Input extends LightningElement {
+    @api ariaLabel!: string;
+    @api autocomplete: string | null = null;
+    @api clearable: boolean = false;
+    @api disabled: boolean = false;
+    @api iconSize: IconSize = "medium";
+    @api iconSymbol: IconSymbol | null = null;
+    @api label?: string;
+    @api loading: boolean = false;
+    @api missingErrorMessage: string = "Complete this field";
+    @api formatErrorMessage?: string;
+    @api name?: string;
+    @api placeholder!: string;
+    @api required = false;
+    @api role: string | null = null;
+    @api shortcutKey: string | null = null;
+    @api size: "small" | "large" | "override" = "small";
+    @api submitLabel?: string | null = null;
+    @api type: string = "text";
+    @api validityOnBlur = false;
+
+    @api
+    get value() {
+        return this._value;
+    }
+    set value(value: string | null) {
+        this._value = value || "";
+    }
+
+    @api
+    get errorMessage() {
+        return this._errorMessage;
+    }
+
+    set errorMessage(value) {
+        this._errorMessage = value;
+    }
+
+    @api focus() {
+        if (this.input) {
+            this.input.focus();
+        }
+    }
+
+    @api
+    reportValidity(): boolean {
+        if (this.isRequiredAndFilled) {
+            this._errorMessage = this.missingErrorMessage;
+            return false;
+        }
+
+        const typeValidator = typeValidatorMap[this.type];
+        if (typeValidator && !typeValidator.validator(this.value)) {
+            this._errorMessage =
+                this.formatErrorMessage || typeValidator.errorMessage;
+            return false;
+        }
+
+        this._errorMessage = "";
+        return true;
+    }
+
+    private _errorMessage: string = "";
+    private focused: boolean = false;
+    private input: HTMLInputElement | null = null;
+    private _value: string | null = null;
+    private _loading: boolean = false;
+
+    private get showClearButton(): boolean {
+        return this.clearable && !!this.value;
+    }
+
+    private get showShortcutKey(): boolean {
+        return !this.showClearButton && !!this.shortcutKey;
+    }
+
+    private get ariaKeyShortcuts() {
+        return this.shortcutKey ? `meta+${this.shortcutKey}` : null;
+    }
+
+    private get inputLoading() {
+        return this.loading || this._loading;
+    }
+
+    private get inputInvalid() {
+        const typeValidator = typeValidatorMap[this.type];
+        return (
+            this.isRequiredAndFilled &&
+            typeValidator &&
+            !typeValidator.validator(this.value)
+        );
+    }
+
+    private get inputDisabled() {
+        return this.inputLoading || this.disabled;
+    }
+
+    private get className() {
+        return cx("input-group", `size-${this.size}`);
+    }
+
+    private get inputContainerClassName() {
+        return cx(
+            "input-container",
+            this.focused && "state-focused",
+            (this.showClearButton || this.showShortcutKey) &&
+                "has-floating-item",
+            !!this.errorMessage && "has-error"
+        );
+    }
+
+    private get buttonDisabled() {
+        return this.inputLoading || this.inputInvalid || this.disabled;
+    }
+
+    private get commandKey() {
+        return isMac() ? "command" : "control";
+    }
+
+    private get shortcutImgSrc() {
+        return `/assets/svg/${this.commandKey}.svg`;
+    }
+
+    private get shortcutImgAlt() {
+        return `${this.commandKey}-${this.shortcutKey} is the search shortcut`;
+    }
+
+    private get isRequiredAndFilled() {
+        return this.required && (!this.value || !this.value.trim());
+    }
+
+    connectedCallback() {
+        window.addEventListener("keydown", this.onWindowKeydown);
+    }
+
+    disconnectedCallback() {
+        window.removeEventListener("keydown", this.onWindowKeydown);
+    }
+
+    renderedCallback() {
+        if (!this.input) {
+            this.input = <HTMLInputElement>this.template.querySelector("input");
+        }
+    }
+
+    onClick() {
+        if (this.input) {
+            this.input.focus();
+        }
+    }
+
+    onInputFocus() {
+        this.focused = true;
+    }
+
+    onInputBlur() {
+        this.focused = false;
+
+        if (this.validityOnBlur) {
+            this.reportValidity();
+        }
+    }
+
+    onInputChange(e: InputEvent) {
+        if (!e || !e.target) {
+            return;
+        }
+        this.dispatchChange((<HTMLInputElement>e.target).value || "");
+    }
+
+    onButtonClick(e: Event) {
+        if (!this.buttonDisabled) {
+            e.stopPropagation();
+        }
+        this.submit();
+    }
+
+    dispatchChange(value: string) {
+        this._value = value;
+        this.dispatchEvent(new CustomEvent("change", { detail: this.value }));
+    }
+
+    clear(e?: Event) {
+        if (e) {
+            e.stopPropagation();
+        }
+        this.dispatchChange("");
+        this.dispatchEvent(new CustomEvent("clear"));
+        if (this.input) {
+            this.input.blur();
+        }
+    }
+
+    submit = async () => {
+        if (this.inputInvalid) {
+            return;
+        }
+        this.dispatchEvent(new CustomEvent("submit", { detail: this.value }));
+    };
+
+    private onKeyDown(e: KeyboardEvent) {
+        switch (e.key) {
+            case "Escape":
+                this.clear();
+                break;
+            case "Enter":
+                this.submit();
+                break;
+            default:
+        }
+    }
+
+    private onWindowKeydown = (e: KeyboardEvent) => {
+        if (this.shortcutKey && e.metaKey && e.key === this.shortcutKey) {
+            e.preventDefault();
+            this.focus();
+        }
+    };
+}

package/src/modules/dx/input/validators.ts

@@ -0,0 +1,5 @@
+export const isValidEmail = (value: string | null) =>
+    // eslint-disable-next-line
+    /^(([^<>()\[\]\\.,;:\s@"]+(\.[^<>()\[\]\\.,;:\s@"]+)*)|(".+"))@((\[[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\])|(([a-zA-Z\-0-9]+\.)+[a-zA-Z]{2,}))$/.test(
+        value || ""
+    );

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

@@ -0,0 +1,86 @@
+import { track, developerwebTrackEventListener } from "dx/instrumentation";
+import InstrumentationTest from "test-components/instrumentationTest";
+import { createRenderComponent } from "utils-internal/tests";
+
+const TAG = "dx-instrumentation";
+const render = createRenderComponent(
+    "dx-instrumentation-test",
+    InstrumentationTest
+);
+
+describe(TAG, () => {
+    afterEach(() => {
+        delete (window as any).dataLayer;
+        delete (window as any).__DX_INSTRUMENTATION_QUEUE__;
+        delete (window as any).__DX_INSTRUMENTATION_IS_INITIALIZED__;
+    });
+
+    it("catches bubbled events", () => {
+        const element = render();
+
+        const button = element.shadowRoot.querySelector("button");
+        button.dispatchEvent(new MouseEvent("click"));
+        expect((window as any).dataLayer.length).toBe(1);
+        expect((window as any).dataLayer[0]).toEqual({
+            event: "buttonClick",
+            buttonName: "default"
+        });
+    });
+
+    it("flushes events dispatched prior to render", () => {
+        track(document, "testEvent", { isSentBeforeRender: "yes" });
+        expect((window as any).__DX_INSTRUMENTATION_QUEUE__.length).toBe(1);
+
+        render();
+
+        expect((window as any).__DX_INSTRUMENTATION_IS_INITIALIZED__).toBe(
+            true
+        );
+        expect((window as any).dataLayer.length).toBe(1);
+        expect((window as any).dataLayer[0]).toEqual({
+            event: "testEvent",
+            isSentBeforeRender: "yes"
+        });
+    });
+
+    // Because Jest runs tests in parallel, and because these tests interact
+    // with global scope, this `describe` block needs to remain within the
+    // parent one to ensure that it's working with a cleaned-up environment.
+    describe("developerwebTrackEventListener", () => {
+        let t: ReturnType<developerwebTrackEventListener> | null = null;
+
+        afterEach(() => {
+            if (t !== null) {
+                t.remove();
+            }
+            delete (window as any).dataLayer;
+        });
+
+        it("catches tracked events", () => {
+            // Marked instrumentation as initialized, so we can capture the event
+            (window as any).__DX_INSTRUMENTATION_IS_INITIALIZED__ = true;
+
+            const spy = { track: jest.fn() };
+            t = developerwebTrackEventListener([spy]);
+            t.add();
+            track(document, "testEvent", { isTestEvent: "yes" });
+
+            expect(spy.track).toHaveBeenCalledTimes(1);
+            const { detail, composed, bubbles } = spy.track.mock.calls[0][0];
+            expect(detail).toEqual({
+                event: "testEvent",
+                payload: {
+                    isTestEvent: "yes"
+                }
+            });
+            expect(composed).toBe(true);
+            expect(bubbles).toBe(true);
+        });
+
+        it("throws an exception if no trackerFns provided", () => {
+            expect(() => developerwebTrackEventListener([])).toThrow(
+                "No tracker functions passed"
+            );
+        });
+    });
+});

package/src/modules/dx/instrumentation/instrumentation.html

@@ -0,0 +1 @@
+<template></template>

package/src/modules/dx/instrumentation/instrumentation.ts

@@ -0,0 +1,116 @@
+import { LightningElement, api } from "lwc";
+
+const TRACKING_EVENT_NAME = "developerwebsite_track";
+const LISTENER_QUEUE = "__DX_INSTRUMENTATION_QUEUE__";
+const LISTENER_INDICATOR = "__DX_INSTRUMENTATION_IS_INITIALIZED__";
+
+export function track(
+    element: EventTarget,
+    event: string,
+    payload: Record<string, unknown>
+): void {
+    const detail = { event, payload };
+    // if window.LISTENER_INDICATOR is undefined, `dx-instrumentation` has not
+    // been mounted, and the listener hasn't been attached.
+    if ((window as any)[LISTENER_INDICATOR] === undefined) {
+        (window as any)[LISTENER_QUEUE] = (window as any)[LISTENER_QUEUE] || [];
+        (window as any)[LISTENER_QUEUE].push(detail);
+    } else {
+        const e = new CustomEvent(TRACKING_EVENT_NAME, {
+            bubbles: true,
+            composed: true,
+            detail
+        });
+        element.dispatchEvent(e);
+    }
+}
+
+const googleTagManager = {
+    track: function (e: Event) {
+        if ((window as any).dataLayer === undefined) {
+            (window as any).dataLayer = [];
+        }
+        const { event, payload } = (e as CustomEvent).detail;
+        (window as any).dataLayer.push({ ...payload, event });
+    }
+};
+
+interface TrackEventListener {
+    add: () => void;
+    remove: () => void;
+}
+
+export function developerwebTrackEventListener(
+    trackerFns: { track: (e: Event) => void }[] = []
+): TrackEventListener {
+    if (trackerFns.length === 0) {
+        throw new Error("No tracker functions passed");
+    }
+
+    const trackdeveloperwebEvent = (e: Event) => {
+        trackerFns.forEach((tracker) => {
+            tracker.track(e);
+        });
+    };
+
+    const attachEventListener = () => {
+        document.addEventListener(TRACKING_EVENT_NAME, trackdeveloperwebEvent);
+    };
+
+    const removeEventListener = () => {
+        document.removeEventListener(
+            TRACKING_EVENT_NAME,
+            trackdeveloperwebEvent
+        );
+    };
+
+    return {
+        add: attachEventListener,
+        remove: removeEventListener
+    };
+}
+
+export default class Instrumentation extends LightningElement {
+    @api useGoogleTagManager = false;
+
+    private tracker: TrackEventListener | null = null;
+
+    private setupTracker() {
+        const trackerFunctions = this.useGoogleTagManager
+            ? [googleTagManager]
+            : [];
+        this.tracker = developerwebTrackEventListener(trackerFunctions);
+        this.tracker.add();
+        (window as any)[LISTENER_INDICATOR] = true;
+    }
+
+    private dispatchQueuedEvents() {
+        while ((window as any)[LISTENER_QUEUE].length > 0) {
+            const event = (window as any)[LISTENER_QUEUE].pop() as {
+                event: string;
+                payload: Record<string, unknown>;
+            };
+            track(this, event.event, event.payload);
+        }
+    }
+
+    renderedCallback() {
+        if (this.tracker === null) {
+            this.setupTracker();
+
+            if (
+                (window as any)[LISTENER_QUEUE] !== undefined &&
+                (window as any)[LISTENER_QUEUE].length > 0
+            ) {
+                this.dispatchQueuedEvents();
+            }
+        }
+    }
+
+    disconnectedCallback() {
+        if (this.tracker !== null) {
+            this.tracker.remove();
+            this.tracker = null;
+        }
+    }
+}

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

@@ -0,0 +1,83 @@
+import Dropdown from "dx/dropdown";
+import InteractiveImage from "dx/interactiveImage";
+import { createRenderComponent } from "utils-internal/tests";
+import {
+    mockSingleDownloadPropsAsArray,
+    mockSingleDownloadPropsAsString,
+    mockMultipleDownloadProps,
+    mockMultipleDownloadOptions
+} from "./mockProps";
+
+const TAG = "dx-interactive-image";
+const render = createRenderComponent(TAG, InteractiveImage);
+
+describe(TAG, () => {
+    describe("single download", () => {
+        it("is accessible", () => {
+            const element = render(mockSingleDownloadPropsAsArray);
+
+            const sectionEl = element.shadowRoot.querySelector("article");
+            expect(sectionEl).not.toBeNull();
+            return expect(sectionEl).toBeAccessible();
+        });
+
+        it("has the right download URL when URL passed as string", () => {
+            const element = render(mockSingleDownloadPropsAsString);
+
+            const dropdownEl = element.shadowRoot.querySelector("dx-dropdown");
+            expect(dropdownEl).toBeNull();
+            const buttonEl =
+                element.shadowRoot.querySelector("header dx-button");
+            expect(buttonEl).not.toBeNull();
+            expect(buttonEl.href).toBe(
+                mockSingleDownloadPropsAsString.downloadUrls
+            );
+            expect(buttonEl.download).toBe("FUsyxR5.jpg");
+            return expect(element).toBeAccessible();
+        });
+
+        it("has the right download URL when URL passed as array", () => {
+            const element = render(mockSingleDownloadPropsAsArray);
+
+            const dropdownEl = element.shadowRoot.querySelector("dx-dropdown");
+            expect(dropdownEl).toBeNull();
+            const buttonEl =
+                element.shadowRoot.querySelector("header dx-button");
+            expect(buttonEl).not.toBeNull();
+            expect(buttonEl.href).toBe(
+                mockSingleDownloadPropsAsArray.downloadUrls[0]
+            );
+            expect(buttonEl.download).toBe("FUsyxR5.jpg");
+            return expect(element).toBeAccessible();
+        });
+    });
+
+    describe("multiple downloads", () => {
+        it("is accessible", () => {
+            const element = render(mockMultipleDownloadProps);
+
+            const sectionEl = element.shadowRoot.querySelector("article");
+            expect(sectionEl).not.toBeNull();
+            return expect(sectionEl).toBeAccessible();
+        });
+
+        it("renders a dropdown", () => {
+            const element = render(mockMultipleDownloadProps);
+
+            const dropdownEl: Dropdown =
+                element.shadowRoot.querySelector("dx-dropdown");
+            expect(dropdownEl).not.toBeNull();
+            const { options } = dropdownEl;
+
+            expect(options).toHaveLength(mockMultipleDownloadOptions.length);
+            options.forEach((option, index) => {
+                expect(option.id).toBe(mockMultipleDownloadOptions[index].id);
+                expect(option.label).toBe(
+                    mockMultipleDownloadOptions[index].label
+                );
+            });
+
+            return expect(element).toBeAccessible();
+        });
+    });
+});

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

@@ -0,0 +1,39 @@
+export const mockSingleDownloadPropsAsString = {
+    title:
+        "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, pellentesque eu",
+    featuredSrc: "https://i.imgur.com/FUsyxR5.jpg",
+    downloadUrls: "https://i.imgur.com/FUsyxR5.jpg"
+};
+
+export const mockSingleDownloadPropsAsArray = {
+    title:
+        "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, pellentesque eu",
+    featuredSrc: "https://i.imgur.com/FUsyxR5.jpg",
+    downloadUrls: ["https://i.imgur.com/FUsyxR5.jpg"]
+};
+
+export const mockMultipleDownloadProps = {
+    title:
+        "Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, pellentesque eu",
+    featuredSrc: "https://i.imgur.com/FUsyxR5.jpg",
+    downloadUrls: [
+        "https://i.imgur.com/FUsyxR5.jpg",
+        "https://i.imgur.com/FUsyxR5.png",
+        "https://i.imgur.com/FUsyxR5.bmp"
+    ]
+};
+
+export const mockMultipleDownloadOptions = [
+    {
+        label: "Download as JPG",
+        id: mockMultipleDownloadProps.downloadUrls[0]
+    },
+    {
+        label: "Download as PNG",
+        id: mockMultipleDownloadProps.downloadUrls[1]
+    },
+    {
+        label: "Download as BMP",
+        id: mockMultipleDownloadProps.downloadUrls[2]
+    }
+];

package/src/modules/dx/interactiveImage/interactiveImage.css

@@ -0,0 +1,59 @@
+@import "helpers/reset";
+@import "helpers/text";
+
+article {
+    border: 1px solid var(--dx-g-gray-90);
+    border-radius: 0.3125rem;
+}
+
+header {
+    display: flex;
+    align-items: flex-start;
+    justify-content: space-between;
+    border-radius: 0.3125rem 0.3125rem 0 0;
+    background-color: var(--dx-g-gray-95);
+    font-family: var(--dx-g-font-sans);
+    color: var(--dx-g-gray-10);
+    padding: var(--dx-g-spacing-sm);
+}
+
+header span {
+    padding: var(--dx-g-spacing-sm) var(--dx-g-spacing-md);
+    font-size: var(--dx-g-text-sm);
+}
+
+footer {
+    border-radius: 0 0 0.3125rem 0.3125rem;
+}
+
+.body {
+    margin: var(--dx-g-spacing-md);
+    overflow-x: auto;
+}
+
+.body img {
+    min-width: 650px;
+}
+
+.controls {
+    display: flex;
+    align-items: center;
+    justify-content: flex-end;
+}
+
+/* Breakpoints for mobile */
+
+@media screen and (max-width: 640px) {
+    header {
+        flex-direction: column;
+        align-items: flex-end;
+    }
+}
+
+@media screen and (max-width: 320px) {
+    .controls,
+    .controls dx-dropdown,
+    .controls dx-button {
+        width: 100%;
+    }
+}

package/src/modules/dx/interactiveImage/interactiveImage.html

@@ -0,0 +1,32 @@
+<template>
+    <article>
+        <header>
+            <span>{title}</span>
+            <div class="controls">
+                <template if:true={isSingleDownload}>
+                    <dx-button
+                        icon-symbol="download"
+                        href={singleDownloadHref}
+                        download={singleDownloadFilename}
+                    >
+                        {downloadButtonLabel}
+                    </dx-button>
+                </template>
+                <template if:false={isSingleDownload}>
+                    <dx-dropdown
+                        options={urls}
+                        onchange={handleDownloadOptionChange}
+                        placement="bottom-end"
+                    >
+                        <dx-button variant="primary" icon-symbol="chevrondown">
+                            {downloadButtonLabel}
+                        </dx-button>
+                    </dx-dropdown>
+                </template>
+            </div>
+        </header>
+        <div class="body">
+            <img src={featuredSrc} alt={title} />
+        </div>
+    </article>
+</template>

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

@@ -0,0 +1,31 @@
+import { html } from "lit-html";
+import { mockMultipleDownloadProps } from "./__tests__/mockProps";
+
+export default {
+    title: "dx/dx-interactive-image",
+    component: "dx-interactive-image"
+};
+
+// prettier-ignore
+const createStyles = () => html `
+    <style>
+        #root {
+            max-width: 800px;
+        }
+    </style>`;
+
+const urls = JSON.stringify(mockMultipleDownloadProps.downloadUrls);
+
+export const SingleDownload = () => html` ${createStyles()}
+    <dx-interactive-image
+        title="Lorem ipsum dolor sit amet, consectetuer adipiscing elit. "
+        featured-src="https://i.imgur.com/FUsyxR5.jpg"
+        download-urls="https://i.imgur.com/FUsyxR5.jpg"
+    ></dx-interactive-image>`;
+
+export const MultipleDownloads = () => html` ${createStyles()}
+    <dx-interactive-image
+        title="Lorem ipsum dolor sit amet, consectetuer adipiscing elit. "
+        featured-src="https://i.imgur.com/FUsyxR5.jpg"
+        download-urls="${urls}"
+    ></dx-interactive-image>`;