@salesforcedevs/dx-components 0.0.0-alpha.0

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

@@ -0,0 +1,129 @@
+import { LightningElement, api } from "lwc";
+import cx from "classnames";
+import { FooterVariant, OptionWithLink } from "typings/custom";
+import { toJson } from "dxUtils/normalizers";
+import {
+    defaultGeneralLinks,
+    termsLinks,
+    socialLinks,
+    privacyHref,
+    intellectualHref
+} from "./links";
+import { track } from "dxUtils/analytics";
+
+const PATH = "/newsletter";
+const createNewsletterSignupHref = (email: string): string =>
+    `${PATH}?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);
+    }
+
+    @api
+    get generalLinks() {
+        return this._generalLinks;
+    }
+    set generalLinks(value) {
+        if (value) {
+            this._generalLinks = toJson(value);
+        }
+    }
+
+    private _generalLinks = defaultGeneralLinks;
+    private _locales?: OptionWithLink[] | null = null;
+    private _variant: FooterVariant = "small-signup";
+    private inputAriaLabel = "Email sign up for developer updates newsletter";
+    private inputPlaceholder = "Email";
+    private inputSubmitLabel = "Subscribe";
+    private intellectualHref = intellectualHref;
+    private privacyHref = privacyHref;
+    private socialLinks = socialLinks;
+    private termsLinks = termsLinks;
+
+    @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: this.inputSubmitLabel,
+            clickUrl: PATH
+        });
+
+        window.location.assign(href);
+    };
+
+    private onLocaleChange(e: CustomEvent) {
+        this.dispatchEvent(
+            new CustomEvent("localechange", { detail: e.detail })
+        );
+    }
+
+    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,206 @@
+import { OptionWithRequiredNested } from "typings/custom";
+
+export const generalLinksRaw: OptionWithRequiredNested[] = [
+    {
+        id: "Developer Centers",
+        label: "Developer Centers",
+        options: [
+            {
+                link: { href: "https://devcenter.heroku.com/" },
+                label: "Heroku",
+                id: "Heroku"
+            },
+            {
+                link: { href: "https://developer.mulesoft.com/" },
+                label: "MuleSoft",
+                id: "MuleSoft"
+            },
+            {
+                link: { href: "https://www.tableau.com/developer" },
+                label: "Tableau",
+                id: "Tableau"
+            },
+            {
+                link: { href: "https://developer.commercecloud.com/s/" },
+                label: "Commerce Cloud",
+                id: "Commerce Cloud"
+            },
+            {
+                link: { href: "https://www.lightningdesignsystem.com/" },
+                label: "Lightning Design System",
+                id: "Lightning Design System"
+            },
+            {
+                link: { href: "https://metamind.readme.io/" },
+                label: "Einstein",
+                id: "Einstein"
+            },
+            {
+                link: { href: "https://salesforce.quip.com/dev" },
+                label: "Quip",
+                id: "Quip"
+            }
+        ]
+    },
+    {
+        id: "Popular Resources",
+        label: "Popular Resources",
+        options: [
+            {
+                link: { href: "/docs" },
+                label: "Documentation",
+                id: "Documentation"
+            },
+            {
+                link: { href: "/docs/component-library" },
+                label: "Component Library",
+                id: "Component Library"
+            },
+            { link: { href: "/docs/apis" }, label: "APIs", id: "APIs" },
+            {
+                link: { href: "https://trailhead.salesforce.com/" },
+                label: "Trailhead",
+                id: "Trailhead"
+            },
+            {
+                link: { href: "/code-samples-and-sdks" },
+                label: "Code Samples and SDKs",
+                id: "Code Samples and SDKs"
+            },
+            { link: { href: "/podcast" }, label: "Podcasts", id: "Podcasts" },
+            {
+                link: { href: "https://appexchange.salesforce.com/" },
+                label: "AppExchange",
+                id: "AppExchange"
+            }
+        ]
+    },
+    {
+        label: "Community",
+        id: "Community",
+        options: [
+            {
+                link: {
+                    href: "https://trailhead.salesforce.com/trailblazer-community/feed"
+                },
+                label: "Trailblazer Community",
+                id: "Trailblazer Community"
+            },
+            {
+                link: {
+                    href: "/forums#!/feedtype=RECENT&criteria=ALLQUESTIONS&"
+                },
+                label: "Forums",
+                id: "Forums"
+            },
+            {
+                link: { href: "/events" },
+                label: "Events and Calendar",
+                id: "Events and Calendar"
+            },
+            {
+                link: { href: "https://go.appexchange.com/partnerprogram" },
+                label: "Partner Community",
+                id: "Partner Community"
+            },
+            { link: { href: "/blogs" }, label: "Blog", id: "Blog" },
+            {
+                link: { href: "https://admin.salesforce.com/" },
+                label: "Salesforce Admins",
+                id: "Salesforce Admins"
+            },
+            {
+                link: { href: "https://architect.salesforce.com/" },
+                label: "Salesforce Architects",
+                id: "Salesforce Architects"
+            }
+        ]
+    }
+];
+
+export const defaultGeneralLinks = generalLinksRaw.map((section) => ({
+    ...section,
+    options: section.options.map((option) => {
+        if (!option.link) {
+            return option;
+        }
+        const external = option.link.href.startsWith("http");
+        return {
+            ...option,
+            link: {
+                ...option.link,
+                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/";
+
+const openOneTrustInfoDisplay = () => {
+    if (window.OneTrust && window.OneTrust.ToggleInfoDisplay) {
+        window.OneTrust.ToggleInfoDisplay();
+    }
+};
+
+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" },
+    {
+        href: "#",
+        rel: "nofollow",
+        label: "Cookie Preferences",
+        onclick: openOneTrustInfoDisplay
+    }
+];
+
+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/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 "dxUtils/analytics";
+
+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/formattedDateTime.html

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

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

@@ -0,0 +1,77 @@
+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);
+
+        if (this._unformattedDate.toString() === "Invalid Date") {
+            // this is a fix for Safari since it doesn't support date strings with 'yyyy/mm/dd' patterns
+            this._unformattedDate = new Date(value.replace(/-/g, "/"));
+        }
+    }
+    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/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.

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

@@ -0,0 +1,74 @@
+import { LightningElement, api } from "lwc";
+import cx from "classnames";
+import { GridVariant, LightningSlotElement } from "typings/custom";
+
+const DEFAULT_COLUMNS = "three";
+
+export default class Grid extends LightningElement {
+    @api
+    get columns() {
+        if (this._columns.includes("dynamic") && this._itemCount) {
+            return this.dynamicColumns;
+        }
+        return this._columns || DEFAULT_COLUMNS;
+    }
+    set columns(value: GridVariant) {
+        this._columns = value;
+    }
+
+    _columns!: GridVariant;
+    _itemCount: number | null = null;
+
+    private get className(): string {
+        return cx("container", `col-${this.columns}`);
+    }
+
+    private isMoreIdyllicColumnNum = (a: number, b: number): boolean => {
+        if (!this._itemCount) {
+            return false;
+        }
+        const remA = this._itemCount % a;
+        const remB = this._itemCount % b;
+        const relRemA = a - remA;
+        const relRemB = b - remB;
+        if (remA === 0 && remB === 0) {
+            return b > a;
+        }
+        if (remA === 0) {
+            return false;
+        }
+        if (remB === 0) {
+            return true;
+        }
+        return relRemB < relRemA;
+    };
+
+    private get dynamicColumns(): GridVariant {
+        if (!this._itemCount) {
+            return DEFAULT_COLUMNS;
+        }
+
+        const possibleColumns = [4, 3];
+
+        let ideal = possibleColumns[0];
+        for (let i = 1; i < possibleColumns.length; i++) {
+            if (this.isMoreIdyllicColumnNum(ideal, possibleColumns[i])) {
+                ideal = possibleColumns[i];
+            }
+        }
+
+        // @ts-ignore (no clue why "two" isn't being seen as a GridVariant type)
+        return (
+            {
+                4: "four",
+                3: "three"
+            }[ideal] || DEFAULT_COLUMNS
+        );
+    }
+
+    onSlotChange(e: Event) {
+        this._itemCount = (
+            e.target as LightningSlotElement
+        ).assignedElements().length;
+    }
+}