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

package/src/modules/dx/footer/footer.ts

@@ -0,0 +1,124 @@
+import { LightningElement, api } from "lwc";
+import cx from "classnames";
+import { toJson } from "utils/normalizers";
+import { FooterVariant, Option } from "typings/custom";
+import {
+    generalLinks,
+    termsLinks,
+    socialLinks,
+    privacyHref,
+    intellectualHref
+} from "./links";
+import { track } from "dx/instrumentation";
+
+const createNewsletterSignupHref = (email: string): string =>
+    `/newsletter?subscriberEmail=${email}`;
+
+const ANALYTICS_INFO = {
+    itemTitle: "Newsletter Sign Up Footer",
+    elementType: "button",
+    destinationType: "internal",
+    ctaClick: true
+};
+export default class Footer extends LightningElement {
+    @api locale: string | null = null;
+    @api
+    get locales() {
+        return this._locales;
+    }
+    set locales(value) {
+        this._locales = toJson(value);
+    }
+
+    private _locales?: Option[] | null = null;
+    private termsLinks = termsLinks;
+    private generalLinks = generalLinks;
+    private socialLinks = socialLinks;
+    private privacyHref = privacyHref;
+    private intellectualHref = intellectualHref;
+    private inputSubmitLabel = "Subscribe";
+    private inputPlaceholder = "Email";
+    private inputAriaLabel = "Email sign up for developer updates newsletter";
+    private _variant: FooterVariant = "small-signup";
+
+    @api
+    set variant(value: FooterVariant) {
+        if (!this.isFooterVariant(value)) {
+            console.error(
+                "Value provided for variant is invalid and should be of type FooterVariant"
+            );
+            return;
+        }
+        this._variant = value;
+    }
+    get variant() {
+        return this._variant;
+    }
+
+    get showContainerMiddle() {
+        return this.variant !== "terms-only";
+    }
+
+    get showLargeSignup() {
+        return this.variant !== "no-signup" && this.variant === "large-signup";
+    }
+
+    get showSmallSignup() {
+        return this.variant !== "no-signup" && this.variant === "small-signup";
+    }
+
+    get hasLocales() {
+        return this.locale && this.locales;
+    }
+
+    get localeLabel(): string | null {
+        let label = null;
+        if (this.locale && this.locales) {
+            const locale = this.locales.find((l) => l.id === this.locale);
+            label = locale ? locale.label : null;
+        }
+        return label;
+    }
+
+    get currentYear(): number {
+        const date = new Date();
+        return date.getFullYear();
+    }
+
+    get className() {
+        return cx(`signup-variant-${this.variant}`);
+    }
+
+    private onSubmitEmail = async (e: CustomEvent) => {
+        const href = createNewsletterSignupHref(e.detail);
+
+        track(e.currentTarget, "custEv_ctaButtonClick", {
+            ...ANALYTICS_INFO,
+            clickText: e.detail,
+            clickUrl: href,
+        });
+
+        window.location.assign(href);
+    };
+
+    private onLocaleChange(e: CustomEvent) {
+        this.dispatchEvent(
+            new CustomEvent("localechange", { detail: e.detail })
+        );
+    }
+
+    private openOneTrustInfoDisplay = () => {
+        if (window.OneTrust && window.OneTrust.ToggleInfoDisplay) {
+            window.OneTrust.ToggleInfoDisplay();
+        }
+    };
+
+    private isFooterVariant(value: string): value is FooterVariant {
+        return [
+            "no-signup",
+            "small-signup",
+            "large-signup",
+            "terms-only"
+        ].includes(value);
+    }
+}

package/src/modules/dx/footer/links.ts

@@ -0,0 +1,140 @@
+export const generalLinksRaw = [
+    {
+        label: "Developer Centers",
+        options: [
+            { href: "https://devcenter.heroku.com/", label: "Heroku" },
+            { href: "https://developer.mulesoft.com/", label: "MuleSoft" },
+            { href: "https://www.tableau.com/developer", label: "Tableau" },
+            {
+                href: "https://developer.commercecloud.com/s/",
+                label: "Commerce Cloud"
+            },
+            {
+                href: "https://www.lightningdesignsystem.com/",
+                label: "Lightning Design System"
+            },
+            {
+                href: "https://metamind.readme.io/",
+                label: "Einstein"
+            },
+            { href: "https://salesforce.quip.com/dev", label: "Quip" }
+        ]
+    },
+    {
+        label: "Popular Resources",
+        options: [
+            { href: "/docs", label: "Documentation" },
+            {
+                href: "/docs/component-library",
+                label: "Component Library"
+            },
+            { href: "/docs/apis", label: "APIs" },
+            { href: "https://trailhead.salesforce.com/", label: "Trailhead" },
+            {
+                href: "/code-samples-and-sdks",
+                label: "Code Samples and SDKs"
+            },
+            { href: "/podcast", label: "Podcasts" },
+            {
+                href: "https://appexchange.salesforce.com/",
+                label: "AppExchange"
+            }
+        ]
+    },
+    {
+        label: "Community",
+        options: [
+            {
+                href: "https://trailhead.salesforce.com/trailblazer-community/feed",
+                label: "Trailblazer Community"
+            },
+            {
+                href: "/forums#!/feedtype=RECENT&criteria=ALLQUESTIONS&",
+                label: "Forums"
+            },
+            { href: "/events", label: "Events and Calendar" },
+            {
+                href: "https://go.appexchange.com/partnerprogram",
+                label: "Partner Community"
+            },
+            { href: "/blogs", label: "Blog" },
+            {
+                href: "https://admin.salesforce.com/",
+                label: "Salesforce Admins"
+            },
+            {
+                href: "https://architect.salesforce.com/",
+                label: "Salesforce Architects"
+            }
+        ]
+    }
+];
+
+export const generalLinks = generalLinksRaw.map((section) => ({
+    ...section,
+    options: section.options.map((option) => {
+        const external = option.href.startsWith("http");
+        return {
+            ...option,
+            iconSymbol: external ? "new_window" : null,
+            target: external ? "_blank" : null
+        };
+    })
+}));
+
+export const privacyHref = "https://www.salesforce.com/company/privacy/";
+
+export const intellectualHref =
+    "https://www.salesforce.com/company/legal/intellectual/";
+
+export const termsLinks = [
+    { href: privacyHref, label: "Privacy Statement" },
+    {
+        href: "https://trailblazer.me/resource/documents/documents/pdf/TermsOfUse_en_US.pdf",
+        label: "Terms of Use"
+    },
+    {
+        href: "https://www.salesforce.com/company/privacy/full_privacy/#nav_info",
+        label: "Use of Cookies"
+    },
+    { href: "https://trust.salesforce.com/en/", label: "Trust" }
+];
+
+export const socialLinks = [
+    {
+        href: "https://github.com/trailheadapps",
+        iconSymbol: "github",
+        iconSprite: "brand",
+        label: "Github"
+    },
+    {
+        href: "https://www.facebook.com/salesforcedevs",
+        iconSymbol: "facebook-f",
+        iconSprite: "brand",
+        label: "Facebook"
+    },
+    {
+        href: "https://twitter.com/salesforcedevs",
+        iconSymbol: "twitter",
+        iconSprite: "brand",
+        label: "Twitter"
+    },
+    {
+        href: "https://www.linkedin.com/showcase/salesforce-developers",
+        iconSymbol: "linkedin-in",
+        iconSprite: "brand",
+        label: "LinkedIn"
+    },
+    {
+        href: "https://www.youtube.com/user/DeveloperForce",
+        iconSymbol: "youtube",
+        iconSprite: "brand",
+        label: "Youtube"
+    },
+    {
+        href: "https://developer.salesforce.com/blogs/feed",
+        iconSymbol: "rss",
+        iconSprite: "general",
+        label: "RSS"
+    }
+];

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

@@ -0,0 +1,34 @@
+import FooterOption from "dx/footerOption";
+import { createRenderComponent } from "utils-internal/tests";
+import { MOCK_BUTTON_PROPS } from "./mockProps";
+
+const TAG = "dx-footer-option";
+const render = createRenderComponent(TAG, FooterOption);
+
+describe(TAG, () => {
+    it("renders a single dx-button component", () => {
+        const element = render(MOCK_BUTTON_PROPS);
+
+        const button = element.shadowRoot.querySelectorAll("dx-button");
+
+        expect(button.length).toEqual(1);
+
+        return expect(element).toBeAccessible();
+    });
+
+    it("fires sendGtm function when button is clicked", () => {
+        const sendGtmMock = jest.fn();
+        const element = render({
+            ...MOCK_BUTTON_PROPS,
+            onclick: sendGtmMock
+        });
+
+        const button = element.shadowRoot.querySelector("dx-button");
+
+        button.click();
+
+        expect(sendGtmMock).toHaveBeenCalled();
+
+        return expect(element).toBeAccessible();
+    });
+});

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

@@ -0,0 +1,7 @@
+export const MOCK_BUTTON_PROPS = {
+    generalLabel: "Popular Resources",
+    label: "Trailhead",
+    href: "https://trailhead.salesforce.com/",
+    iconSymbol: "learning",
+    iconSprite: "salesforcebrand"
+};

package/src/modules/dx/footerOption/footerOption.css

@@ -0,0 +1,4 @@
+dx-button {
+    --dx-c-button-primary-color: var(--dx-g-blue-vibrant-40);
+    --dx-c-button-inline-color-hover: var(--dx-g-blue-vibrant-20);
+}

package/src/modules/dx/footerOption/footerOption.html

@@ -0,0 +1,12 @@
+<template>
+    <dx-button
+        href={href}
+        icon-symbol={iconSymbol}
+        target={target}
+        font="sans"
+        variant="inline"
+        onclick={sendGtm}
+    >
+        {label}
+    </dx-button>
+</template>

package/src/modules/dx/footerOption/footerOption.ts

@@ -0,0 +1,19 @@
+import { LightningElement, api } from "lwc";
+import { track } from "dx/instrumentation";
+
+export default class FooterOption extends LightningElement {
+    @api href: string | null = null;
+    @api generalLabel: string | null = null;
+    @api label: string | null = null;
+    @api iconSymbol: string | null = null;
+    @api target: string | null = null;
+
+    sendGtm(e: PointerEvent) {
+        track(e.currentTarget, "custEv_bottomNavLinkClick", {
+            navHeading: this.generalLabel || undefined,
+            navSubHeading: this.label || undefined,
+            clickText: this.href || undefined,
+            pageLocation: window.location.pathname || undefined
+        });
+    }
+}

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

@@ -0,0 +1,25 @@
+/* eslint-disable jest/no-mocks-import */
+import FormattedDateTime from "dx/formattedDateTime";
+import { createRenderComponent } from "utils-internal/tests";
+import mockProps from "./mockProps";
+const TAG = "dx-formatted-date-time";
+const render = createRenderComponent(TAG, FormattedDateTime);
+
+describe(TAG, () => {
+    it("renders the date", () => {
+        const expectedDate = "Sunday, December 31, 1899, 12:00:00am GMT";
+        const component = render(mockProps);
+
+        expect(component).not.toBeNull();
+        expect(component.shadowRoot.textContent).toMatch(expectedDate);
+        return expect(component).toBeAccessible();
+    });
+
+    it("logs an error if value provided is an error", () => {
+        console.error = jest.fn();
+        const component = render({ value: undefined });
+
+        expect(component).not.toBeNull();
+        expect(console.error).toHaveBeenCalled();
+    });
+});

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

@@ -0,0 +1,13 @@
+const date = new Date(Date.UTC(0, 0, 0, 0, 0, 0));
+
+export default {
+    value: date,
+    day: "2-digit",
+    hour: "numeric",
+    minute: "numeric",
+    month: "long",
+    second: "numeric",
+    weekday: "long",
+    year: "numeric",
+    timeZoneName: "short"
+};

package/src/modules/dx/formattedDateTime/formattedDateTime.html

@@ -0,0 +1 @@
+<template>{value}</template>

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

@@ -0,0 +1,103 @@
+import { html } from "lit-html";
+
+export default {
+    title: "dx/dx-formatted-date-time",
+    component: "dx-formatted-date-time"
+};
+
+const date = new Date().toISOString();
+
+const createStyles = () => html`
+    <style>
+        span.date-label {
+            color: grey;
+        }
+
+        dx-formatted-date-time {
+            display: block;
+            margin-bottom: 25px;
+        }
+    </style>
+`;
+
+export const Base = () => html`
+    ${createStyles()}
+    <span class="date-label">Date with Time</span>
+    <dx-formatted-date-time
+        value="${date}"
+        day="2-digit"
+        hour="2-digit"
+        minute="2-digit"
+        month="long"
+        second="2-digit"
+        time-zone-name="short"
+        weekday="long"
+        year="numeric"
+    ></dx-formatted-date-time>
+
+    <span class="date-label">Date with "long" Month</span>
+    <dx-formatted-date-time
+        value="${date}"
+        day="2-digit"
+        month="long"
+        year="numeric"
+    ></dx-formatted-date-time>
+
+    <span class="date-label">Date with Short Month</span>
+    <dx-formatted-date-time
+        value="${date}"
+        day="2-digit"
+        month="short"
+        year="numeric"
+    ></dx-formatted-date-time>
+
+    <span>Date all Digits</span>
+    <dx-formatted-date-time
+        value="${date}"
+        day="2-digit"
+        month="2-digit"
+        year="numeric"
+    ></dx-formatted-date-time>
+
+    <span class="date-label">Date with Day of Week</span>
+    <dx-formatted-date-time
+        value="${date}"
+        day="2-digit"
+        month="long"
+        weekday="long"
+        year="numeric"
+    ></dx-formatted-date-time>
+
+    <span class="date-label">Time</span>
+    <dx-formatted-date-time
+        value="${date}"
+        hour="2-digit"
+        minute="2-digit"
+        second="2-digit"
+    ></dx-formatted-date-time>
+
+    <span class="date-label">Time as Numeric without Seconds</span>
+    <dx-formatted-date-time
+        value="${date}"
+        hour="numeric"
+        minute="2-digit"
+    ></dx-formatted-date-time>
+
+    <span class="date-label">Time with Timezone</span>
+    <dx-formatted-date-time
+        value="${date}"
+        hour="2-digit"
+        minute="2-digit"
+        second="2-digit"
+        time-zone-name="short"
+        weekday="long"
+    ></dx-formatted-date-time>
+
+    <span class="date-label">Day of Week with Time</span>
+    <dx-formatted-date-time
+        value="${date}"
+        hour="2-digit"
+        minute="2-digit"
+        weekday="long"
+    ></dx-formatted-date-time>
+`;

package/src/modules/dx/formattedDateTime/formattedDateTime.ts

@@ -0,0 +1,72 @@
+import { LightningElement, api } from "lwc";
+import {
+    formattedDateDay,
+    formattedDateHour,
+    formattedDateMinute,
+    formattedDateMonth,
+    formattedDateOptions,
+    formattedDateSecond,
+    formattedDateTimeZoneName,
+    formattedDateWeekday,
+    formattedDateYear
+} from "typings/custom";
+
+export default class FormattedDateTime extends LightningElement {
+    @api weekday: formattedDateWeekday;
+    @api year: formattedDateYear;
+    @api month: formattedDateMonth;
+    @api day: formattedDateDay;
+    @api hour: formattedDateHour;
+    @api minute: formattedDateMinute;
+    @api second: formattedDateSecond;
+    @api timeZoneName: formattedDateTimeZoneName;
+    @api
+    set value(value) {
+        if (!value) {
+            console.error("Value provided to FormattedDateTime is invalid");
+            return;
+        }
+
+        this._unformattedDate = new Date(value);
+    }
+    get value() {
+        const options = this.getOptions();
+        this._formattedDate = this.formatDate(this._unformattedDate, options);
+        return this._formattedDate;
+    }
+
+    private _formattedDate!: string;
+    private _unformattedDate!: Date;
+
+    formatDate(unformattedDate: Date, options: formattedDateOptions) {
+        const locale = navigator.language;
+        let formattedDateTime = Intl.DateTimeFormat(locale, options).format(
+            unformattedDate
+        ) as String;
+        formattedDateTime = this.updateDayPeriodFormatting(formattedDateTime);
+        return formattedDateTime;
+    }
+
+    updateDayPeriodFormatting(formattedDateTime: String) {
+        if (formattedDateTime.includes("AM")) {
+            formattedDateTime = formattedDateTime.replace(" AM", "am");
+        } else if (formattedDateTime.includes("PM")) {
+            formattedDateTime = formattedDateTime.replace(" PM", "pm");
+        }
+        return formattedDateTime;
+    }
+
+    getOptions() {
+        const options = {
+            weekday: this.weekday || undefined,
+            year: this.year || undefined,
+            month: this.month || undefined,
+            day: this.day || undefined,
+            hour: this.hour || undefined,
+            minute: this.minute || undefined,
+            second: this.second,
+            timeZoneName: this.timeZoneName || undefined
+        };
+        return options;
+    }
+}

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

@@ -0,0 +1,32 @@
+import Grid from "dx/grid";
+import { createRenderComponent } from "utils-internal/tests";
+
+const TAG = "dx-grid";
+const render = createRenderComponent(TAG, Grid);
+
+describe(TAG, () => {
+    [
+        [4, "four", "dynamic"],
+        [8, "four", "dynamic"],
+        [7, "four", "dynamic"],
+        [3, "three", "dynamic"],
+        [6, "three", "dynamic"],
+        [5, "three", "dynamic"],
+        [2, "three", "dynamic"],
+        [1, "three", "dynamic"]
+    ].forEach(([numElements, calculatedColumns, columns]) =>
+        it(`choses ${calculatedColumns} columns when there are ${numElements} elements`, () => {
+            const element = render({ columns });
+            const slot: HTMLSlotElement =
+                element.shadowRoot.querySelector("slot");
+            const div = document.createElement("div");
+            slot.assignedElements = jest
+                .fn()
+                // @ts-ignore
+                .mockReturnValue(new Array(numElements).fill(div));
+            slot.dispatchEvent(new Event("slotchange"));
+
+            return expect(element.columns).toEqual(calculatedColumns);
+        })
+    );
+});

package/src/modules/dx/grid/grid.css

@@ -0,0 +1,48 @@
+.container {
+    --one-third-width: calc((100% - 2 * var(--dx-g-page-grid-gap)) / 3);
+
+    display: grid;
+    gap: var(--dx-g-page-grid-gap);
+    grid-template-rows: repeat(auto-fill, 1fr);
+    grid-template-columns: 1fr;
+    justify-items: stretch;
+    align-items: stretch;
+    position: relative;
+}
+
+.col-one {
+    /* This class intentionally left blank. */
+}
+
+@media (min-width: 600px) {
+    .col-two,
+    .col-three,
+    .col-four {
+        grid-template-columns: repeat(2, 1fr);
+    }
+}
+
+@media (min-width: 768px) {
+    .col-two-slim-left {
+        grid-template-columns: var(--one-third-width) calc(
+                2 * var(--one-third-width) + var(--dx-g-page-grid-gap)
+            );
+    }
+
+    .col-three {
+        grid-template-columns: repeat(3, 1fr);
+    }
+
+    .col-two-slim-right {
+        grid-template-columns:
+            calc(2 * var(--one-third-width) + var(--dx-g-page-grid-gap))
+            var(--one-third-width);
+    }
+}
+
+/* special breakpoint for four col */
+@media (min-width: 1200px) {
+    .col-four {
+        grid-template-columns: repeat(4, 1fr);
+    }
+}

package/src/modules/dx/grid/grid.html

@@ -0,0 +1,3 @@
+<template>
+    <div class={className}><slot onslotchange={onSlotChange}></slot></div>
+</template>

package/src/modules/dx/grid/grid.md

@@ -0,0 +1,14 @@
+# Breakpoint Guidelines for Card Grids
+
+_Mobile (599 or less)_ --> One col
+_Small Tablet (600 - 767)_ --> Two col max
+_Tablet & Desktop (768 and up)_ --> 3 col min / 3 & 4 col
+_Widescreen (1920 and up)_ --> 4 col min / 4 & 5 col.
+
+# Dynamic columns
+
+Dynamic column mode will only assign 3 or 4 cols for desktop as anything less makes cards far too large (stretches imagery, etc).
+
+# Naming strategy
+
+Column namings are desktop-oriented, i.e. 4 col refers to layout that is 4 columns on desktop -- but this layout would be actually 2 column on tablet and 1 column on mobile.