@salesforcedevs/arch-components 1.20.17-alpha1

package/src/modules/shared/overflow/overflow.ts

@@ -0,0 +1,71 @@
+/**
+ * @file Utilities for dealing with element overflows (execeeding container width)
+ * Based on https://sfdc.co/uOYl6
+ */
+
+export type CalculateOverflowItem = {
+    active: boolean;
+    value?: string;
+    width: number;
+};
+
+export function calculateOverflow(
+    items: CalculateOverflowItem[],
+    containerWidth: number = 0,
+    overflowWidth: number = 0
+) {
+    const visibleItems: CalculateOverflowItem[] = [];
+    const overflowItems: CalculateOverflowItem[] = [];
+
+    const allItemsWidth = items.reduce(
+        (totalWidth, item) => totalWidth + item.width,
+        0
+    );
+
+    // If total items width is less than containerwidth or if the containerwidth is
+    // less than zero in cases where container is not yet rendered and we subtract the threshold
+    // return all items as visibleItems and overflowItems empty
+    if (allItemsWidth <= containerWidth || containerWidth <= 0) {
+        return { visibleItems: items, overflowItems };
+    }
+
+    // Not all items fit, an overflow is needed
+    let totalWidth = overflowWidth;
+
+    // Find the active item if it exists
+    const activeItem = items.find((i) => i.active);
+
+    // The active item is always shown, so reserve space for it
+    if (activeItem) {
+        totalWidth += activeItem.width;
+    }
+
+    let activeItemFitsWithoutRearrangement = false;
+
+    items.forEach((item) => {
+        if (item.active) {
+            activeItemFitsWithoutRearrangement = overflowItems.length === 0;
+            if (activeItemFitsWithoutRearrangement) {
+                visibleItems.push(item);
+            }
+        } else {
+            const itemFits = item.width + totalWidth <= containerWidth;
+            if (itemFits && overflowItems.length === 0) {
+                totalWidth += item.width;
+                visibleItems.push(item);
+            } else {
+                overflowItems.push(item);
+            }
+        }
+    });
+
+    // Place the active item at the end
+    if (activeItem && !activeItemFitsWithoutRearrangement) {
+        visibleItems.push(activeItem);
+    }
+
+    return {
+        visibleItems,
+        overflowItems
+    };
+}

package/src/modules/shared/polling-request.ts

@@ -0,0 +1,97 @@
+const DEFAULT_INTERVAL = 3000;
+const DEFAULT_RETRIES = 10;
+
+export type PollingRequestInit<T> = {
+    request: () => Promise<T>;
+    done?: (res: T) => boolean;
+    interval?: number;
+    retries?: number;
+};
+
+/**
+ * Creates a Promise-like polling request
+ * @class PollingRequest
+ * @example
+ * const res = await new PollingRequest({ ... });
+ */
+export class PollingRequest<T> {
+    // Internals
+    private resolve: (value: T | PromiseLike<T>) => void = () => {};
+    private reject: (reason?: any) => void = () => {};
+    private readonly promise: Promise<T>;
+    private timer: ReturnType<typeof setTimeout> | null = null;
+    private attempt: number = 0;
+
+    // Arguments
+    private request: () => Promise<T>;
+    private done: (res: T) => boolean;
+    private interval: number;
+    private retries: number;
+
+    constructor({ request, done, interval, retries }: PollingRequestInit<T>) {
+        this.promise = new Promise<T>((resolve, reject) => {
+            this.resolve = resolve;
+            this.reject = reject;
+        });
+
+        this.request = request;
+        this.done = done || (() => true);
+        this.interval = interval || DEFAULT_INTERVAL;
+        this.retries = retries || DEFAULT_RETRIES;
+
+        this.start();
+    }
+
+    async then(
+        onfulfilled?: (value: T) => T | PromiseLike<T>,
+        onrejected?: (reason: any) => PromiseLike<never>
+    ): Promise<T> {
+        return this.promise.then(onfulfilled, onrejected);
+    }
+
+    async catch(onRejected?: (reason: any) => PromiseLike<never>): Promise<T> {
+        return this.promise.catch(onRejected);
+    }
+
+    private start() {
+        this.poll();
+    }
+
+    private stop() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+        }
+
+        this.retries = 0;
+        this.attempt = 0;
+        this.timer = null;
+    }
+
+    private async poll() {
+        const currentAttempt = (this.attempt = this.attempt + 1);
+
+        try {
+            const res = await this.request();
+
+            // If polling was stopped before the request could complete
+            if (currentAttempt !== this.attempt) return;
+
+            if (this.done(res)) {
+                this.stop();
+                this.resolve(res);
+            }
+
+            if (this.attempt < this.retries) {
+                this.timer = setTimeout(this.poll.bind(this), this.interval);
+            } else {
+                throw new Error('timeout');
+            }
+        } catch (err) {
+            // If polling was stopped before the request could complete
+            if (currentAttempt !== this.attempt) return;
+
+            this.stop();
+            this.reject(err);
+        }
+    }
+}

package/src/modules/shared/testutils.ts

@@ -0,0 +1,118 @@
+import { html, render, TemplateResult } from 'lit-html';
+import { querySelectorAll, querySelector } from 'kagekiri';
+// @ts-ignore we are using a beta feature "setFeatureFlagForTest" that tsc doesn't like
+import { createElement, LightningElement, setFeatureFlagForTest } from 'lwc';
+
+export { html, render };
+
+export function nextTick() {
+    return new Promise((resolve) => {
+        process.nextTick(resolve);
+    });
+}
+
+export function $(selector: string, element: HTMLElement) {
+    return element.shadowRoot!.querySelectorAll(selector);
+}
+
+export function $testid(value: string, element: HTMLElement) {
+    return $(`[data-testid="${value}"]`, element);
+}
+
+export function renderIntoBody(template: TemplateResult) {
+    let element = document.createElement('div');
+    document.body.append(element);
+    render(template, element);
+    return element.children[0] as HTMLElement;
+}
+
+export async function renderIntoBodyAndWait(
+    template: TemplateResult,
+    ready:
+        | ((params: {
+              querySelector: typeof querySelector;
+              querySelectorAll: typeof querySelectorAll;
+          }) => boolean)
+        | string
+) {
+    let element = renderIntoBody(template);
+    await new Promise((resolve) => {
+        let check = () => {
+            let isReady =
+                typeof ready === 'string'
+                    ? querySelector(ready, element) !== null
+                    : ready({ querySelector, querySelectorAll });
+            if (isReady) {
+                resolve(undefined);
+            } else {
+                requestAnimationFrame(check);
+            }
+        };
+        requestAnimationFrame(check);
+    });
+    return element;
+}
+
+// LWC Component Testing Utilities
+export const renderLightningElement = (
+    element: LightningElement,
+    properties = {}
+) => {
+    Object.assign(element, properties);
+    document.body.appendChild(element as unknown as Node);
+    return element;
+};
+
+export const createRenderComponent = (
+    tag: string,
+    LWC: new () => LightningElement
+) => {
+    setFeatureFlagForTest('ENABLE_LIGHT_DOM_COMPONENTS', true);
+    return (properties = {}) => {
+        const component = createElement(tag, {
+            is: LWC
+        });
+
+        renderLightningElement(component, properties);
+        return component;
+    };
+};
+
+export const mockSlottedElement = <T extends HTMLElement>(
+    element: any,
+    elementType = 'button',
+    slotName?: string
+): { slottedElement: T; slot: HTMLSlotElement } => {
+    const slot: HTMLSlotElement = element.shadowRoot.querySelector(
+        `slot${slotName ? `[name='${slotName}']` : ''}`
+    );
+    expect(slot).not.toBeNull();
+
+    const slottedElement = document.createElement(elementType) as T;
+    slot.assignedElements = jest.fn(() => [slottedElement]);
+    slot.dispatchEvent(new Event('slotchange'));
+
+    return { slottedElement, slot };
+};
+
+const wait = () => new Promise((res) => setTimeout(res, 0));
+
+const renderAllShadowDoms = (element: {
+    shadowRoot: { children: HTMLElement };
+}) => {
+    if (element.shadowRoot) {
+        return element.shadowRoot.children;
+    }
+
+    return element;
+};
+
+export const toSnapshot = async <T extends Object>(
+    render: Function,
+    props?: T
+) => {
+    const element = render(props);
+    await wait();
+    const doc = renderAllShadowDoms(element);
+    return expect(doc).toMatchSnapshot();
+};

package/src/modules/shared/track/track.ts

@@ -0,0 +1,23 @@
+type TrackingPayload = {
+    label?: string;
+    ctaType?: string;
+};
+
+export const track = (
+    element: HTMLElement,
+    eventName: string,
+    payload: TrackingPayload
+) => {
+    const trackEvent = new CustomEvent('trailhead_track', {
+        bubbles: true,
+        composed: true,
+        detail: {
+            eventName,
+            payload: {
+                ...payload,
+                ...{ pageLocation: element.tagName }
+            }
+        }
+    });
+    element.dispatchEvent(trackEvent);
+};

package/src/modules/shared/trailhead.ts

@@ -0,0 +1,123 @@
+/**
+ * @file Utilites for interacting with the Trailhead platform.
+ */
+import { fetch, fetchJSON, postJSON, csrfHeader } from './fetch/fetch';
+import { PollingRequest, PollingRequestInit } from './polling-request';
+import logger from './logger/logger';
+// Org type definition (orgPicker/types module not found)
+type Org = {
+    [key: string]: any;
+};
+
+const CSRF_WARNING =
+    'A CSRF token required for this request. Set it using fromTrailhead.configure().';
+
+const DEFAULT_BASE_URL = '';
+
+type TrailheadAPIClientInit = {
+    baseUrl?: string;
+    csrfToken?: string;
+};
+
+/**
+ * Client for interacting with Trailhead via API requests
+ * @example
+ * const fromTrailhead = new TrailheadAPIClient({ csrfToken: "XXX" });
+ * fromTrailhead.get("/user_orgs");
+ */
+export class TrailheadAPIClient {
+    baseUrl: string = DEFAULT_BASE_URL;
+    csrfToken: string | undefined;
+
+    constructor(args: TrailheadAPIClientInit = {}) {
+        this.configure(args);
+    }
+
+    configure({
+        baseUrl = process.env.API_HOST,
+        csrfToken
+    }: TrailheadAPIClientInit) {
+        this.baseUrl = baseUrl || DEFAULT_BASE_URL;
+        this.csrfToken = csrfToken;
+    }
+
+    async get<T>(path: string) {
+        return fetchJSON<T>(this.makeUrl(path));
+    }
+
+    async post<T>(path: string, body?: object) {
+        this.checkRequest();
+        return postJSON<T>(this.makeUrl(path), body, {
+            headers: { ...csrfHeader(this.csrfToken) }
+        });
+    }
+
+    async patch<T>(path: string, body?: object) {
+        this.checkRequest();
+        return postJSON<T>(this.makeUrl(path), body, {
+            method: 'PATCH',
+            headers: {
+                ...csrfHeader(this.csrfToken)
+            }
+        });
+    }
+
+    async delete<T>(path: string) {
+        this.checkRequest();
+        return fetchJSON<T>(this.makeUrl(path), {
+            method: 'DELETE',
+            headers: { ...csrfHeader(this.csrfToken) }
+        });
+    }
+
+    async poll<T>(args: PollingRequestInit<T>) {
+        return new PollingRequest<T>(args);
+    }
+
+    makeUrl(path: string) {
+        return [this.baseUrl, path]
+            .map((s) => s.replace(/^\/|\/$/g, ''))
+            .join('/');
+    }
+
+    private checkRequest() {
+        if (!this.csrfToken) {
+            logger.warn(CSRF_WARNING);
+        }
+    }
+}
+
+/**
+ * Determine if an org is reachable (after creation) by
+ * requesting open endpoints. The org is reachable if the
+ * user's client resolves the freshly propagated DNS entries.
+ */
+export async function isOrgReachable(org: Org): Promise<boolean> {
+    const subdomain = org.instance_url.split('.')[0];
+
+    const responses = await Promise.all([
+        fetch(
+            `${subdomain}.my.salesforce.com/.well-known/openid-configuration`
+        ),
+        fetch(
+            `${subdomain}--c.documentforce.com/.well-known/openid-configuration`,
+            {
+                mode: 'no-cors'
+            }
+        ),
+        fetch(
+            `${subdomain}--th-con-app.visualforce.com/.well-known/openid-configuration`,
+            {
+                mode: 'no-cors'
+            }
+        ),
+        fetch(
+            `${subdomain}.lightning.force.com/.well-known/openid-configuration`,
+            {
+                mode: 'no-cors'
+            }
+        )
+    ]).catch(() => Promise.resolve([{ status: 404 }]));
+
+    return responses.every((r) => r.status === 200 || r.status === 0);
+}

package/src/modules/shared/types.d.ts

@@ -0,0 +1 @@
+export type BooleanAttr = boolean | string | null;

package/src/modules/shared/useEffectAttr.ts

@@ -0,0 +1,16 @@
+export function useEffectAttr(fn: Function, deps: Array<string>, context: any) {
+    let prevValues = new Map<string, any>();
+    return () => {
+        let prev = deps.map((key) => prevValues.get(key));
+        let next = deps.map((key) => context[key]);
+        for (let i in prev) {
+            if (next[i] !== prev[i]) {
+                fn.call(context);
+                break;
+            }
+        }
+        for (let k of deps) {
+            prevValues.set(k, context[k]);
+        }
+    };
+}

package/src/modules/shared/withState.ts

@@ -0,0 +1,21 @@
+import { directive, NodePart } from 'lit-html';
+
+export type WithStateState = any;
+export type WithStateSetState = (state: any) => void;
+
+/**
+ * lit-html directive for creating thin, stateful renderings
+ * @example
+ * html`${withState((state, setState) => html`state.msg`, { msg: 'hello!' })}`
+ */
+export default directive((render, initialState = {}) => (part: NodePart) => {
+    let prevState = initialState;
+
+    function setState(nextState: WithStateState) {
+        part.setValue(render({ ...prevState, ...nextState }, setState));
+        part.commit();
+        prevState = { ...prevState, ...nextState };
+    }
+
+    part.setValue(render(initialState, setState));
+});

package/src/modules/tds/appLauncher/__fixtures__/index.ts

@@ -0,0 +1,34 @@
+import { App } from '../types';
+
+export const apps: App[] = [
+    {
+        link: { href: '/#a' },
+        imageUrl: '/images/app-trailhead.svg',
+        label: 'Trailhead'
+    },
+    {
+        link: { href: '/#b' },
+        imageUrl: '/images/app-trailhead.svg',
+        label: 'Trailblazer Community'
+    },
+    {
+        link: { href: '/#c' },
+        imageUrl: '/images/app-trailhead.svg',
+        label: 'AppExchange'
+    },
+    {
+        link: { href: '/#d' },
+        imageUrl: '/images/app-trailhead.svg',
+        label: 'IdeaExchange'
+    },
+    {
+        link: { href: '/#e' },
+        imageUrl: '/images/app-trailhead.svg',
+        label: 'Events'
+    },
+    {
+        link: { href: '/#f' },
+        imageUrl: '/images/app-trailhead.svg',
+        label: 'Salesforce Help'
+    }
+];

package/src/modules/tds/appLauncher/__tests__/appLauncher.test.ts

@@ -0,0 +1,119 @@
+import { querySelector } from 'kagekiri';
+
+import { html, renderIntoBody, nextTick } from 'shared/testutils';
+
+import { apps, apps as mockApps } from '../__fixtures__';
+import { App } from '../types';
+
+import AppLauncher from '../appLauncher';
+
+customElements.define('tds-app-launcher', AppLauncher.CustomElementConstructor);
+
+interface ElementOptions {
+    open?: boolean;
+    label?: string;
+    apps?: App[];
+}
+
+describe('tds-app-launcher', () => {
+    let element: HTMLElement;
+    let shadow: ShadowRoot;
+
+    const renderElement = (options?: ElementOptions) => {
+        const { label, apps, open } = {
+            label: 'App Launcher',
+            apps: mockApps,
+            open: false,
+            ...options
+        };
+        return renderIntoBody(html`
+      <tds-app-launcher
+        open=${open}
+        label=${label}
+        .apps=${apps}
+        ></tds-user-menu>
+    `);
+    };
+
+    beforeEach(() => {
+        element = renderElement();
+        shadow = element.shadowRoot!;
+    });
+
+    it('opens the menu when the container is clicked', async () => {
+        let clickEvent = new MouseEvent('click', {
+            bubbles: false,
+            cancelable: true
+        });
+        expect(shadow.querySelector('.menu')).toHaveAttribute(
+            'aria-hidden',
+            'true'
+        );
+        shadow
+            .querySelector('[data-menu="trigger"]')!
+            .dispatchEvent(clickEvent);
+        await nextTick();
+        expect(shadow.querySelector('.menu')).toHaveAttribute(
+            'aria-hidden',
+            'false'
+        );
+    });
+
+    it('render the label', () => {
+        let $button = querySelector(
+            'tds-button-icon button',
+            renderElement({ label: 'Fancy Apps' })
+        )!;
+        expect($button.getAttribute('aria-label')).toBe('Fancy Apps');
+    });
+
+    it('renders each app', async () => {
+        let apps = [...mockApps];
+        let $items = shadow.querySelectorAll('.menu__item')!;
+        apps.forEach((app, index) => {
+            expect($items[index].getAttribute('href')).toBe(app.link.href);
+            expect($items[index].textContent).toBe(app.label);
+            expect(
+                ($items[index].firstChild! as HTMLElement).getAttribute('src')
+            ).toBe(app.imageUrl);
+        });
+    });
+
+    describe('tracking', () => {
+        it('app_launcher_clicked', async () => {
+            let clickEvent = new MouseEvent('click', {
+                bubbles: false,
+                cancelable: true
+            });
+            let handler = jest.fn();
+            document.addEventListener('trailhead_track', handler);
+            shadow
+                .querySelector('[data-menu="trigger"]')!
+                .dispatchEvent(clickEvent);
+            await nextTick();
+            expect(handler.mock.calls[0][0].detail).toEqual(
+                expect.objectContaining({
+                    eventName: 'app_launcher_clicked'
+                })
+            );
+        });
+        it('app_launcher_link_clicked', async () => {
+            let clickEvent = new MouseEvent('click', {
+                bubbles: false,
+                cancelable: true
+            });
+            let handler = jest.fn();
+            document.addEventListener('trailhead_track', handler);
+            shadow
+                .querySelector('[data-menu="item"]')!
+                .dispatchEvent(clickEvent);
+            await nextTick();
+            expect(handler.mock.calls[0][0].detail).toEqual(
+                expect.objectContaining({
+                    eventName: 'app_launcher_link_clicked',
+                    payload: expect.objectContaining({ label: apps[0].label })
+                })
+            );
+        });
+    });
+});

package/src/modules/tds/appLauncher/appLauncher.css

@@ -0,0 +1,65 @@
+@import 'tds/reset';
+
+a,
+a:active,
+a:visited {
+    text-decoration: none;
+}
+
+.root {
+    position: relative;
+}
+
+.menu {
+    --item-size: 7.5rem;
+    background-color: var(--tds-color-white);
+    border-radius: var(--tds-radius-lg);
+    box-shadow: var(--tds-shadow-lg);
+    box-sizing: border-box;
+    margin-top: var(--tds-spacing-2);
+    padding: var(--tds-spacing-4);
+    position: absolute;
+    top: 100%;
+    right: 0;
+    width: var(
+        --tds-app-launcher_menu-width,
+        calc((var(--item-size) * 3) + (var(--tds-spacing-4) * 2))
+    );
+    z-index: 9999;
+}
+
+.menu[aria-hidden='true'] {
+    display: none;
+}
+
+.menu__items {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(var(--item-size), 1fr));
+}
+
+.menu__item {
+    align-items: center;
+    border: 1px solid var(--tds-color-white);
+    border-radius: var(--tds-radius-lg);
+    color: var(--tds-color-black);
+    display: flex;
+    flex-direction: column;
+    justify-content: flex-start;
+    font-size: var(--tds-font-size-sm);
+    padding: var(--tds-spacing-4);
+    text-align: center;
+    text-decoration: none;
+}
+
+[data-focus-visible='true'] .menu__item[data-active='true'],
+.menu__item:hover {
+    border-color: var(--tds-color-fog);
+}
+
+.menu__item img {
+    margin-bottom: var(--tds-spacing-2);
+}
+
+[data-focus-visible='false'] .menu {
+    outline: none;
+}