@lumx/react 3.20.1-alpha.20 → 3.20.1-alpha.21

package/src/stories/utils/theming.tsx

@@ -0,0 +1,166 @@
+import React from 'react';
+import { Predicate } from '@lumx/react/utils/type';
+import { FlexBox } from '@lumx/react';
+
+type Property = string | { value: string };
+interface PropertyTree {
+    [key: string]: PropertyTree | Property;
+}
+type Entry = [key: string, value: string];
+type Variables = Record<string, string>;
+
+function asValue(prop?: PropertyTree | Property): string | undefined {
+    if (typeof prop === 'string') {
+        return prop;
+    }
+    if (typeof prop === 'object' && 'value' in prop) {
+        return prop.value as string;
+    }
+    return undefined;
+}
+
+/** Convert property tree into a list of args entries ([key, value]) */
+function* toArgEntries(props: PropertyTree | Property, parent = ''): Iterable<Entry> {
+    const value = asValue(props);
+    if (value) {
+        yield [parent, value];
+    } else {
+        for (const [key, prop] of Object.entries(props)) {
+            const newParent = parent ? `${parent}-${key}` : key;
+            yield* toArgEntries(prop, newParent);
+        }
+    }
+}
+function* parseVariableEntries(cssString: string, strict = false) {
+    for (const line of cssString.split(/(?<=;)/)) {
+        if (!line.trim()) continue;
+        const match = line.match(/^\s*(--lumx[^:]+)\s*:\s*([^;]+);/m);
+        if (!match) {
+            if (strict) throw new Error(`Could not parse \`${line}\``);
+            else continue;
+        }
+        const [, variableName, variableValue] = match;
+        yield [variableName, variableValue];
+    }
+}
+
+function VariableEditor({
+    variable: [key, value],
+    setVariable,
+    defaultStyle,
+}: {
+    variable: Entry;
+    setVariable: (newVariable: Entry) => void;
+    defaultStyle: Variables;
+}) {
+    const onChange = React.useCallback<React.ChangeEventHandler<HTMLInputElement>>(
+        (evt) => {
+            setVariable([evt.target.name, evt.target.value]);
+        },
+        [setVariable],
+    );
+
+    return (
+        <FlexBox as="label" orientation="horizontal" hAlign="center" style={{ whiteSpace: 'nowrap' }}>
+            <span style={{ flexShrink: 0 }}>{key}</span>:
+            <input
+                name={key}
+                onChange={onChange}
+                style={{ border: 0, padding: 8, fieldSizing: 'content', display: 'inline' } as any}
+                value={defaultStyle[key] === value ? '' : value}
+                placeholder={value}
+            />
+            ;
+        </FlexBox>
+    );
+}
+
+function VariablesEditor({
+    style,
+    defaultStyle,
+    setStyle,
+}: {
+    style: Variables;
+    defaultStyle: Variables;
+    setStyle: (fn: (newStyle: Variables) => Variables) => void;
+}) {
+    const setVariable = React.useCallback(
+        ([key, value]: Entry) => {
+            setStyle((prevStyle) => ({ ...prevStyle, [key]: value }));
+        },
+        [setStyle],
+    );
+    return (
+        <details style={{ fontFamily: 'monospace' }} className="lumx-spacing-margin-vertical-huge">
+            <summary className="lumx-typography-subtitle2">Edit variables</summary>
+            {Object.entries(style).map((variable) => (
+                <VariableEditor
+                    key={variable[0]}
+                    defaultStyle={defaultStyle}
+                    variable={variable}
+                    setVariable={setVariable}
+                />
+            ))}
+        </details>
+    );
+}
+
+const FILTER_PROPS = ['theme', 'emphasis', 'size'];
+
+export function withTheming<P extends PropertyTree>({
+    properties,
+    values,
+}: {
+    properties?: P;
+    values?: string | Partial<P>;
+}) {
+    const initialStyle = values
+        ? Object.fromEntries(
+              typeof values === 'string'
+                  ? parseVariableEntries(values)
+                  : toArgEntries(values as PropertyTree, '--lumx'),
+          )
+        : [];
+    const defaultStyle = Object.fromEntries(properties ? Array.from(toArgEntries(properties, '--lumx')) : []);
+
+    const varNames = new Set(Object.keys(initialStyle).concat(Object.keys(defaultStyle)));
+
+    function filteredStyles(args: any) {
+        // Create predicate
+        const filterArgs = Object.entries(args)
+            .map(([argName, argValue]) => {
+                if (typeof argValue === 'string' && FILTER_PROPS.includes(argName)) {
+                    return (varName: string) =>
+                        // Has the given arg with value
+                        varName.match(new RegExp(`${argName}-${argValue}`)) ||
+                        (argName === 'emphasis' &&
+                            (argValue === 'medium' || argValue === 'low') &&
+                            varName.match(/emphasis-selected/)) ||
+                        // Or does not have the arg at all
+                        !varName.match(new RegExp(`${argName}-\\w+`));
+                }
+                return false;
+            })
+            .filter(Boolean) as Array<Predicate<string>>;
+        const styles = Object.fromEntries(
+            Array.from(varNames.values())
+                .map((varName) => {
+                    if (!filterArgs.every((filter) => filter(varName))) return null as any;
+                    return [varName, initialStyle[varName] || defaultStyle[varName]];
+                })
+                .filter(Boolean),
+        );
+        return () => styles;
+    }
+
+    return (Story: any, ctx: any) => {
+        const [style, setStyle] = React.useState<Variables>(filteredStyles(ctx.args));
+
+        return (
+            <>
+                <Story args={{ ...ctx.args, style: { ...ctx.args.style, ...style } }} />
+                <VariablesEditor style={style} defaultStyle={defaultStyle} setStyle={setStyle} />
+            </>
+        );
+    };
+}

package/src/stories/utils/toFlattenProps.ts

@@ -0,0 +1,28 @@
+import castArray from 'lodash/castArray';
+import { concatPath } from './concatPath';
+
+type Props = Record<string, any>;
+type OneOrMoreProps = Props | Array<Props>;
+
+/**
+ * Build a flat props object from the given nested props
+ *
+ * @example toFlattenProps({ foo: { bar: 4 } }) // => { 'foo.bar': 4 }
+ * @example toFlattenProps({ foo: [{ bar: 4 }, { bar: 5 }] }) // => { 'foo[0].bar': 4, 'foo[0].bar': 5 }
+ */
+export function toFlattenProps(props: { [prefix: string]: OneOrMoreProps }): Props {
+    const out: Props = {};
+    for (const [prefix, oneOrMoreProps] of Object.entries(props)) {
+        const propsArray = castArray(oneOrMoreProps);
+
+        for (let i = 0; i < propsArray.length; i += 1) {
+            const path = Array.isArray(oneOrMoreProps) ? concatPath(prefix, i) : prefix;
+            const subProps = propsArray[i];
+
+            for (const [key, value] of Object.entries(subProps)) {
+                out[concatPath(path, key)] = value;
+            }
+        }
+    }
+    return out;
+}

package/src/stories/utils/withCategory.ts

@@ -0,0 +1,12 @@
+import setWith from 'lodash/setWith';
+
+/**
+ * Add table.category to the provided argTypes
+ */
+export function withCategory(category: string, argTypes: Record<string, any>) {
+    const out: typeof argTypes = {};
+    for (const [key, value] of Object.entries(argTypes)) {
+        out[key] = setWith({ ...value }, 'table.category', category);
+    }
+    return out;
+}

package/src/testing/utils/ThemeSentinel.tsx

@@ -0,0 +1,10 @@
+import { useTheme } from '@lumx/react/utils/theme/ThemeContext';
+
+const TEST_ID = 'theme-sentinel';
+
+/** Test component used as sentinel to detect the value of the theme context */
+export function ThemeSentinel() {
+    const theme = useTheme();
+    return <div data-testid={TEST_ID} className={`--theme-${theme}`} />;
+}
+ThemeSentinel.testId = TEST_ID;

package/src/testing/utils/commonTestsSuiteRTL.tsx

@@ -0,0 +1,193 @@
+import isEmpty from 'lodash/isEmpty';
+
+import { GenericProps } from '@lumx/react/utils/type';
+import { queryByClassName } from '@lumx/react/testing/utils/queries';
+import React from 'react';
+import { Theme } from '@lumx/react';
+import { RenderOptions } from '@testing-library/react';
+import { ThemeProvider } from '@lumx/react/utils/theme/ThemeContext';
+import castArray from 'lodash/castArray';
+import { invertTheme } from '@lumx/react/utils/theme/invertTheme';
+
+interface CommonSetup {
+    props: GenericProps;
+}
+
+type AffectConfig<E> = { element: E; classModifier?: 'color' | 'theme'; inverted?: boolean };
+type Not<E> = { not: E };
+
+interface Options<S extends CommonSetup> {
+    baseClassName: string;
+    forwardClassName?: keyof S;
+    forwardAttributes?: keyof S;
+    forwardRef?: keyof S;
+    applyTheme?: {
+        /** Element(s) to which we apply the theme class */
+        affects: Array<AffectConfig<keyof S> | Not<AffectConfig<keyof S>>>;
+        /** Apply theme via theme prop */
+        viaProp: boolean;
+        /** Apply theme via theme context */
+        viaContext: boolean;
+        /** Apply a default theme if no prop or context was provided */
+        defaultTheme?: Theme;
+        /** Default props to apply when testing theme */
+        defaultProps?: S['props'];
+    };
+}
+
+export type RenderWrapper = RenderOptions['wrapper'];
+export type SetupRenderOptions = { wrapper?: RenderWrapper };
+export type SetupFunction<S extends CommonSetup> = (
+    props?: GenericProps,
+    options?: SetupRenderOptions,
+) => S | Promise<S>;
+
+/**
+ * Common tests on components
+ * - Check base class name and class name forwarding
+ * - Check props forwarding
+ */
+export function commonTestsSuiteRTL<S extends CommonSetup>(setup: SetupFunction<S>, options: Options<S>): void {
+    if (isEmpty(options)) {
+        return;
+    }
+    const { baseClassName, forwardClassName, forwardAttributes, forwardRef, applyTheme } = options;
+    describe('Common tests suite', () => {
+        it('should render with base class name', async () => {
+            await setup();
+            expect(queryByClassName(document.body, baseClassName)).toBeInTheDocument();
+        });
+
+        if (forwardClassName) {
+            it('should forward any CSS class', async () => {
+                const modifiedProps = {
+                    className: 'component component--is-tested',
+                };
+                const wrappers = await setup(modifiedProps);
+                expect(wrappers[forwardClassName]).toHaveClass(modifiedProps.className);
+            });
+        }
+
+        if (forwardAttributes) {
+            it('should forward any other prop', async () => {
+                const modifiedProps = {
+                    winter: 'is coming',
+                };
+                const wrappers = await setup(modifiedProps);
+                expect(wrappers[forwardAttributes]).toHaveAttribute('winter', modifiedProps.winter);
+            });
+        }
+
+        if (forwardRef) {
+            it('should forward ref', async () => {
+                const ref = React.createRef();
+                const wrappers = await setup({ ref });
+                expect(ref.current).toBe(wrappers[forwardRef]);
+            });
+        }
+
+        if (applyTheme) {
+            describe('theme', () => {
+                const { affects, defaultTheme, viaProp, viaContext } = applyTheme;
+                const testElements = affects.map((configOrNot) => {
+                    let shouldHaveModifier: boolean = true;
+                    let config: AffectConfig<any>;
+                    if ('not' in configOrNot) {
+                        shouldHaveModifier = false;
+                        config = configOrNot.not;
+                    } else config = configOrNot;
+
+                    const {
+                        element,
+                        classModifier = 'theme',
+                        inverted = false,
+                    }: AffectConfig<any> = typeof config === 'object' ? config : { element: config };
+                    return {
+                        element,
+                        getExpectedClassModifier: (theme: Theme) =>
+                            `--${classModifier}-${inverted ? invertTheme(theme) : theme}`,
+                        shouldHaveModifier,
+                        apply: shouldHaveModifier ? 'apply' : 'not apply',
+                    };
+                });
+
+                const expectTheme = (
+                    wrappers: any,
+                    { element, getExpectedClassModifier, shouldHaveModifier }: any,
+                    theme: Theme,
+                    override: { shouldHaveModifier?: boolean } = {},
+                ) => {
+                    for (const wrapper of castArray(wrappers[element])) {
+                        let expected: any = expect(wrapper.className);
+                        if (override.shouldHaveModifier === false || !shouldHaveModifier) {
+                            expected = expected.not;
+                        }
+                        expected.toContain(getExpectedClassModifier(theme));
+                    }
+                };
+
+                if (defaultTheme) {
+                    it.each(testElements)(
+                        `should $apply default theme (${defaultTheme}) to \`$element\``,
+                        async (affectedElement) => {
+                            const wrappers = await setup(applyTheme.defaultProps);
+                            expectTheme(wrappers, affectedElement, defaultTheme);
+                        },
+                    );
+                }
+
+                // Only the elements that are affected by theme
+                const affectedElements = testElements.filter((e) => e.shouldHaveModifier);
+                if (!defaultTheme && affectedElements.length) {
+                    it.each(affectedElements)(
+                        `should not apply default theme (${defaultTheme}) to \`$element\``,
+                        async (affectedElement) => {
+                            const wrappers = await setup(applyTheme.defaultProps);
+                            expectTheme(wrappers, affectedElement, Theme.light, { shouldHaveModifier: false });
+                            expectTheme(wrappers, affectedElement, Theme.dark, { shouldHaveModifier: false });
+                        },
+                    );
+                }
+
+                if (viaProp) {
+                    const theme = invertTheme(defaultTheme || Theme.light);
+                    it.each(testElements)(
+                        `should $apply prop theme=${theme} to \`$element\``,
+                        async (affectedElement) => {
+                            const wrappers = await setup({ ...applyTheme.defaultProps, theme });
+                            expectTheme(wrappers, affectedElement, theme);
+                        },
+                    );
+                }
+
+                const contextTheme = invertTheme(defaultTheme || Theme.light);
+                it.each(testElements)(
+                    `should $apply context theme=${contextTheme} to \`$element\``,
+                    async (affectedElement) => {
+                        const Wrapper = ({ children }: any) => (
+                            <ThemeProvider value={contextTheme}>{children}</ThemeProvider>
+                        );
+                        const wrappers = await setup({}, { wrapper: Wrapper });
+                        expectTheme(wrappers, affectedElement, contextTheme, {
+                            shouldHaveModifier: !viaContext ? false : undefined,
+                        });
+                    },
+                );
+
+                if (viaProp && viaContext) {
+                    const propTheme = invertTheme(contextTheme);
+                    it.each(testElements)(
+                        `should $apply prop theme=${propTheme} to \`$element\` overriding the context theme=${contextTheme}`,
+                        async (affectedElement) => {
+                            const Wrapper = ({ children }: any) => (
+                                <ThemeProvider value={contextTheme}>{children}</ThemeProvider>
+                            );
+                            const wrappers = await setup({ theme: propTheme }, { wrapper: Wrapper });
+                            expectTheme(wrappers, affectedElement, propTheme);
+                        },
+                    );
+                }
+            });
+        }
+    });
+}

package/src/testing/utils/index.ts

@@ -0,0 +1 @@
+export * from './commonTestsSuiteRTL';

package/src/testing/utils/queries.ts

@@ -0,0 +1,19 @@
+import { buildQueries } from '@testing-library/dom';
+
+export const queryAllByClassName = (container: HTMLElement, className: string) =>
+    Array.from(container.getElementsByClassName(className) as HTMLCollectionOf<HTMLElement>);
+
+export const [queryByClassName, getAllByClassName, getByClassName, findAllByClassName, findByClassName] = buildQueries(
+    queryAllByClassName,
+    (_, className) => `Multiple \`.${className}\` found`,
+    (_, className) => `No \`.${className}\` found`,
+);
+
+export const queryAllByTagName = (container: HTMLElement, tagName: string) =>
+    Array.from(container.getElementsByTagName(tagName) as HTMLCollectionOf<HTMLElement>);
+
+export const [queryByTagName, getAllByTagName, getByTagName, findAllByTagName, findByTagName] = buildQueries(
+    queryAllByTagName,
+    (_, tagName) => `Multiple \`${tagName}\` found`,
+    (_, tagName) => `No \`${tagName}\` found`,
+);

package/src/untypped-modules.d.ts

@@ -0,0 +1,9 @@
+// Extend CSSStyleDeclaration to support viewTransitionName for view transitions
+interface CSSStyleDeclaration {
+    viewTransitionName: string | null;
+}
+/**
+ * List untypped modules here to declare them as explicit any.
+ */
+declare module 'test-data-bot';
+declare module '*.jpg';

package/src/utils/ClickAwayProvider/ClickAwayProvider.stories.jsx

@@ -0,0 +1,70 @@
+/* eslint-disable react-hooks/rules-of-hooks */
+/* eslint-disable @typescript-eslint/no-use-before-define */
+import { useCallback, useRef, useState } from 'react';
+import { Button } from '@lumx/react';
+import { ClickAwayProvider } from '@lumx/react/utils/ClickAwayProvider';
+import { initDemoShadowDOMPortal } from '@lumx/react/stories/utils/initDemoShadowDOMPortal';
+import { PortalProvider, Portal } from '@lumx/react/utils/Portal';
+
+export default {
+    title: 'LumX components/ClickAwayProvider',
+    parameters: {
+        // Disables Chromatic snapshot (not relevant for this story).
+        chromatic: { disable: true },
+    },
+};
+
+// eslint-disable-next-line react/display-name
+const Card = React.forwardRef(({ top, children, close }, ref) => (
+    <ClickAwayProvider callback={close} childrenRefs={useRef([ref])}>
+        <Portal>
+            <div
+                className="lumx-spacing-padding"
+                ref={ref}
+                style={{ position: 'absolute', top, border: '1px solid red' }}
+            >
+                {children}
+            </div>
+        </Portal>
+    </ClickAwayProvider>
+));
+
+const ButtonWithCard = ({ level, parentRef }) => {
+    const ref3 = useRef();
+    const [isOpen3, setOpen3] = useState(false);
+    const open3 = useCallback(() => setOpen3(true), []);
+    const close3 = useCallback(() => setOpen3(false), []);
+    const nextLevel = level + 1;
+
+    return (
+        <>
+            Level {level} - <Button onClick={open3}>Open level {nextLevel}</Button>
+            {isOpen3 && (
+                <Card ref={ref3} close={close3} top={parentRef?.current?.getBoundingClientRect().bottom || '130px'}>
+                    {nextLevel === 4 ? `Level ${nextLevel}` : <ButtonWithCard level={nextLevel} parentRef={ref3} />}
+                </Card>
+            )}
+        </>
+    );
+};
+
+/**
+ * This story showcases the detection of click away inside a nested React portal tree (i.e. not nested in the DOM)
+ */
+export const NestedClickAway = () => (
+    <>
+        <p>Clicking inside a level should close all child levels but not parent levels</p>
+        <ButtonWithCard level={0} />
+    </>
+);
+
+/**
+ * Testing close on click away for a popover rendered in a shadow DOM
+ */
+export const InShadowDOM = () => {
+    return (
+        <PortalProvider value={initDemoShadowDOMPortal}>
+            <NestedClickAway />
+        </PortalProvider>
+    );
+};

package/src/utils/ClickAwayProvider/ClickAwayProvider.tsx

@@ -0,0 +1,69 @@
+import { createContext, RefObject, useContext, useEffect, useMemo, useRef } from 'react';
+import { ClickAwayParameters, useClickAway } from '@lumx/react/hooks/useClickAway';
+
+interface ContextValue {
+    childrenRefs: Array<RefObject<HTMLElement>>;
+    addRefs(...newChildrenRefs: Array<RefObject<HTMLElement>>): void;
+}
+
+const ClickAwayAncestorContext = createContext<ContextValue | null>(null);
+
+interface ClickAwayProviderProps extends ClickAwayParameters {
+    /**
+     * (Optional) Element that should be considered as part of the parent
+     */
+    parentRef?: RefObject<HTMLElement>;
+    /**
+     * Children
+     */
+    children?: React.ReactNode;
+}
+
+/**
+ * Component combining the `useClickAway` hook with a React context to hook into the React component tree and make sure
+ * we take into account both the DOM tree and the React tree to detect click away.
+ *
+ * @return the react component.
+ */
+export const ClickAwayProvider: React.FC<ClickAwayProviderProps> = ({
+    children,
+    callback,
+    childrenRefs,
+    parentRef,
+}) => {
+    const parentContext = useContext(ClickAwayAncestorContext);
+    const currentContext = useMemo(() => {
+        const context: ContextValue = {
+            childrenRefs: [],
+            /**
+             * Add element refs to the current context and propagate to the parent context.
+             */
+            addRefs(...newChildrenRefs) {
+                // Add element refs that should be considered as inside the click away context.
+                context.childrenRefs.push(...newChildrenRefs);
+
+                if (parentContext) {
+                    // Also add then to the parent context
+                    parentContext.addRefs(...newChildrenRefs);
+                    if (parentRef) {
+                        // The parent element is also considered as inside the parent click away context but not inside the current context
+                        parentContext.addRefs(parentRef);
+                    }
+                }
+            },
+        };
+        return context;
+    }, [parentContext, parentRef]);
+
+    useEffect(() => {
+        const { current: currentRefs } = childrenRefs;
+        if (!currentRefs) {
+            return;
+        }
+        currentContext.addRefs(...currentRefs);
+    }, [currentContext, childrenRefs]);
+
+    useClickAway({ callback, childrenRefs: useRef(currentContext.childrenRefs) });
+    return <ClickAwayAncestorContext.Provider value={currentContext}>{children}</ClickAwayAncestorContext.Provider>;
+};
+ClickAwayProvider.displayName = 'ClickAwayProvider';

package/src/utils/ClickAwayProvider/index.ts

@@ -0,0 +1 @@
+export * from './ClickAwayProvider';

package/src/utils/MaterialThemeSwitcher/MaterialThemeSwitcher.tsx

@@ -0,0 +1,54 @@
+import { useCallback, useState } from 'react';
+import { Switch } from '@lumx/react/components/switch';
+import { Alignment } from '@lumx/react';
+
+// Global state used to
+const globalState = {
+    isEnabled: false,
+    styleSheet: null as any,
+};
+
+/** Toggle apply the material CSS override. */
+export async function toggleMaterialTheme(wasEnabled: boolean) {
+    globalState.isEnabled = !wasEnabled;
+
+    // Inject the material theme CSS file.
+    if (!globalState.styleSheet) {
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore
+        const cssCode = await import('!!raw-loader!@lumx/core/css/material.css');
+
+        // Inject CSS override in a <style> node in <head>
+        const style = document.createElement('style');
+        style.textContent = cssCode.default;
+        document.head.appendChild(style);
+
+        globalState.styleSheet = style.sheet;
+    }
+    // Disable/Enable stylesheet
+    globalState.styleSheet.disabled = !globalState.isEnabled;
+}
+
+export const MaterialThemeSwitcher: React.FC<any> = ({ theme }) => {
+    const [isEnabled, setEnabled] = useState(globalState.isEnabled);
+    const toggleTheme = useCallback(
+        () =>
+            setEnabled((wasEnabled) => {
+                toggleMaterialTheme(wasEnabled);
+                return !wasEnabled;
+            }),
+        [],
+    );
+
+    return (
+        <Switch
+            className="material-theme-switcher"
+            isChecked={isEnabled}
+            onChange={toggleTheme}
+            position={Alignment.right}
+            theme={theme}
+        >
+            Material theme
+        </Switch>
+    );
+};

package/src/utils/MaterialThemeSwitcher/index.ts

@@ -0,0 +1 @@
+export * from './MaterialThemeSwitcher';

package/src/utils/Portal/Portal.test.tsx

@@ -0,0 +1,31 @@
+import { render, screen } from '@testing-library/react';
+import { Portal } from './Portal';
+
+const TEST_ID = 'portal-child';
+const PortalChild = () => <div data-testid={TEST_ID}>Hello from portal</div>;
+
+describe(Portal, () => {
+    it('should render portal content in document.body by default', () => {
+        render(
+            <Portal>
+                <PortalChild />
+            </Portal>,
+        );
+
+        const child = screen.getByTestId(TEST_ID);
+        expect(child.parentElement).toBe(document.body);
+    });
+
+    it('should render inline when enabled is false', () => {
+        const { container } = render(
+            <div id="wrapper">
+                <Portal enabled={false}>
+                    <PortalChild />
+                </Portal>
+            </div>,
+        );
+
+        const child = screen.getByTestId(TEST_ID);
+        expect(child.parentElement).toBe(container.querySelector('#wrapper'));
+    });
+});