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

package/src/utils/Portal/Portal.tsx

@@ -0,0 +1,33 @@
+import React from 'react';
+import { createPortal } from 'react-dom';
+import { PortalContext } from './PortalProvider';
+
+export interface PortalProps {
+    enabled?: boolean;
+    children: React.ReactNode;
+}
+
+/**
+ * Render children in a portal outside the current DOM position
+ * (defaults to `document.body` but can be customized with the PortalContextProvider)
+ */
+export const Portal: React.FC<PortalProps> = ({ children, enabled = true }) => {
+    const init = React.useContext(PortalContext);
+    const context = React.useMemo(
+        () => {
+            return enabled ? init() : null;
+        },
+        // Only update on 'enabled'
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        [enabled],
+    );
+
+    React.useLayoutEffect(() => {
+        return context?.teardown;
+    }, [context?.teardown, enabled]);
+
+    if (!context?.container) {
+        return <>{children}</>;
+    }
+    return createPortal(children, context.container);
+};

package/src/utils/Portal/PortalProvider.stories.jsx

@@ -0,0 +1,22 @@
+import { Button } from '@lumx/react';
+import { initDemoShadowDOMPortal } from '@lumx/react/stories/utils/initDemoShadowDOMPortal';
+import { PortalProvider } from './PortalProvider';
+import { Portal } from './Portal';
+
+export default {
+    title: 'LumX components/PortalProvider',
+    component: PortalProvider,
+    args: { enabled: true },
+    parameters: { chromatic: { disable: true } },
+};
+
+/**
+ * Demonstrate how to customize portals to render into a custom shadow root
+ */
+export const RenderInShadowDOM = ({ enabled }) => (
+    <PortalProvider value={initDemoShadowDOMPortal}>
+        <Portal enabled={enabled}>
+            <Button>My button {!enabled && 'not'} in a shadow DOM portal</Button>
+        </Portal>
+    </PortalProvider>
+);

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

@@ -0,0 +1,72 @@
+import { render, screen } from '@testing-library/react';
+import { PortalInit, PortalProvider } from './PortalProvider';
+import { Portal } from './Portal';
+
+const TEST_ID = 'portal-child';
+const PORTAL_CONTAINER_ID = 'portal-container';
+
+const PortalChild = () => <div data-testid={TEST_ID}>Hello from portal</div>;
+
+describe('PortalProvider', () => {
+    it('should render portal content in the provided container', () => {
+        const portalContainer = document.createElement('div');
+        portalContainer.id = PORTAL_CONTAINER_ID;
+        document.body.appendChild(portalContainer);
+
+        const getContainer: PortalInit = () => ({ container: portalContainer });
+
+        render(
+            <PortalProvider value={getContainer}>
+                <Portal>
+                    <PortalChild />
+                </Portal>
+            </PortalProvider>,
+        );
+
+        const child = screen.getByTestId(TEST_ID);
+        expect(child.parentElement).toBe(portalContainer);
+        portalContainer.remove();
+    });
+
+    it('should call teardown on unmount', () => {
+        const teardownMock = vi.fn();
+        const portalContainer = document.createElement('div');
+        portalContainer.id = PORTAL_CONTAINER_ID;
+        document.body.appendChild(portalContainer);
+
+        const getContainer: PortalInit = () => ({
+            container: portalContainer,
+            teardown: teardownMock,
+        });
+
+        const { unmount } = render(
+            <PortalProvider value={getContainer}>
+                <Portal>
+                    <PortalChild />
+                </Portal>
+            </PortalProvider>,
+        );
+
+        expect(teardownMock).not.toHaveBeenCalled();
+        unmount();
+        expect(teardownMock).toHaveBeenCalledTimes(1);
+        portalContainer.remove();
+    });
+
+    it('should render inline if provider does not return a container', () => {
+        const getContainer: PortalInit = () => ({}); // No container
+
+        const { container } = render(
+            <div id="wrapper">
+                <PortalProvider value={getContainer}>
+                    <Portal>
+                        <PortalChild />
+                    </Portal>
+                </PortalProvider>
+            </div>,
+        );
+
+        const child = screen.getByTestId(TEST_ID);
+        expect(child.parentElement).toBe(container.querySelector('#wrapper'));
+    });
+});

package/src/utils/Portal/PortalProvider.tsx

@@ -0,0 +1,24 @@
+import React from 'react';
+
+type Container = DocumentFragment | Element;
+
+/**
+ * Portal initializing function.
+ * If it does not provide a container, the Portal children will render in classic React tree and not in a portal.
+ */
+export type PortalInit = () => {
+    container?: Container;
+    teardown?: () => void;
+};
+
+export const PortalContext = React.createContext<PortalInit>(() => ({ container: document.body }));
+
+export interface PortalProviderProps {
+    children?: React.ReactNode;
+    value: PortalInit;
+}
+
+/**
+ * Customize where <Portal> wrapped elements render (tooltip, popover, dialog, etc.)
+ */
+export const PortalProvider: React.FC<PortalProviderProps> = PortalContext.Provider;

package/src/utils/Portal/index.tsx

@@ -0,0 +1,2 @@
+export { type PortalInit, PortalProvider, type PortalProviderProps } from './PortalProvider';
+export { type PortalProps, Portal } from './Portal';

package/src/utils/browser/DOM/findImage.tsx

@@ -0,0 +1,3 @@
+/** Find image in element including the element */
+export const findImage = (element: HTMLElement | null): HTMLImageElement | null =>
+    element?.matches('img') ? (element as HTMLImageElement) : element?.querySelector('img') || null;

package/src/utils/browser/DOM/startViewTransition.ts

@@ -0,0 +1,68 @@
+import ReactDOM from 'react-dom';
+
+import { MaybeElementOrRef } from '@lumx/react/utils/type';
+
+import { unref } from '../../react/unref';
+import { isReducedMotion } from '../isReducedMotion';
+
+function setupViewTransitionName(elementRef: MaybeElementOrRef<HTMLElement>, name: string) {
+    let originalName: string | null = null;
+    return {
+        set() {
+            const element = unref(elementRef);
+            if (!element) return;
+            originalName = element.style.viewTransitionName;
+            element.style.viewTransitionName = name;
+        },
+        unset() {
+            const element = unref(elementRef);
+            if (!element || originalName === null) return;
+            element.style.viewTransitionName = originalName;
+        },
+    };
+}
+
+/**
+ * Wrapper around the `document.startViewTransition` handling browser incompatibilities, react DOM flush and
+ * user preference.
+ *
+ * @param changes                callback containing the changes to apply within the view transition.
+ * @param setViewTransitionName  set the `viewTransitionName` style on a `source` & `target` to morph these elements.
+ */
+export async function startViewTransition({
+    changes,
+    viewTransitionName,
+}: {
+    changes: () => void;
+    viewTransitionName: {
+        source: MaybeElementOrRef<HTMLElement>;
+        target: MaybeElementOrRef<HTMLElement>;
+        name: string;
+    };
+}) {
+    const start = (document as any)?.startViewTransition?.bind(document);
+    const prefersReducedMotion = isReducedMotion();
+    const { flushSync } = ReactDOM as any;
+    if (prefersReducedMotion || !start || !flushSync || !viewTransitionName?.source || !viewTransitionName?.target) {
+        // Skip, apply changes without a transition
+        changes();
+        return;
+    }
+
+    // Setup set/unset transition name on source & target
+    const sourceTransitionName = setupViewTransitionName(viewTransitionName.source, viewTransitionName.name);
+    const targetTransitionName = setupViewTransitionName(viewTransitionName.target, viewTransitionName.name);
+
+    sourceTransitionName.set();
+
+    // Start view transition, apply changes & flush to DOM
+    await start(() => {
+        sourceTransitionName.unset();
+
+        flushSync(changes);
+
+        targetTransitionName.set();
+    }).updateCallbackDone;
+
+    targetTransitionName.unset();
+}

package/src/utils/browser/focus/constants.ts

@@ -0,0 +1,7 @@
+/** CSS selector listing all tabbable elements. */
+export const TABBABLE_ELEMENTS_SELECTOR =
+    'a[href], button, textarea, input:not([type="hidden"]):not([hidden]), [tabindex]';
+
+/** CSS selector matching element that are disabled (should not receive focus). */
+export const DISABLED_SELECTOR =
+    '[hidden], [tabindex="-1"], [disabled]:not([disabled="false"]), [aria-disabled]:not([aria-disabled="false"])';

package/src/utils/browser/focus/getFirstAndLastFocusable.test.ts

@@ -0,0 +1,134 @@
+import { getFirstAndLastFocusable } from './getFirstAndLastFocusable';
+
+function htmlToElement(html: string): any {
+    const template = document.createElement('template');
+    template.innerHTML = html.trim();
+    return template.content.firstChild;
+}
+
+describe(getFirstAndLastFocusable.name, () => {
+    it('should get empty', () => {
+        const element = htmlToElement('<div></div>');
+        const focusable = getFirstAndLastFocusable(element);
+        expect(focusable).toEqual({});
+    });
+
+    it('should get single item', () => {
+        const element = htmlToElement('<div><button /></div>');
+        const focusable = getFirstAndLastFocusable(element);
+        expect(focusable.last).toBe(focusable.first);
+    });
+
+    it('should get first and last', () => {
+        const element = htmlToElement(`
+            <div>
+                <div>Non focusable div</div>
+                <button>Simple button</button>
+                <div>Non focusable div</div>
+                <input />
+                <div>Non focusable div</div>
+            </div>
+        `);
+        const focusable = getFirstAndLastFocusable(element);
+        expect(focusable.first).toMatchInlineSnapshot(`
+            <button>
+              Simple button
+            </button>
+        `);
+        expect(focusable.first).toMatchInlineSnapshot(`
+            <button>
+              Simple button
+            </button>
+        `);
+    });
+
+    describe('match focusable elements', () => {
+        it('should match input element', () => {
+            const element = htmlToElement('<div><input /></div>');
+            const focusable = getFirstAndLastFocusable(element);
+            expect(focusable.first).toMatchInlineSnapshot('<input />');
+        });
+
+        it('should match link element', () => {
+            const element = htmlToElement('<div><a href="#" /></div>');
+            const focusable = getFirstAndLastFocusable(element);
+            expect(focusable.first).toMatchInlineSnapshot(`
+                <a
+                  href="#"
+                />
+            `);
+        });
+
+        it('should match textarea element', () => {
+            const element = htmlToElement('<div><textarea /></div>');
+            const focusable = getFirstAndLastFocusable(element);
+            expect(focusable.first).toMatchInlineSnapshot(`
+                <textarea>
+                  &lt;/div&gt;
+                </textarea>
+            `);
+        });
+
+        it('should match element with tabindex', () => {
+            const element = htmlToElement('<div><span tabindex="0" /></div>');
+            const focusable = getFirstAndLastFocusable(element);
+            expect(focusable.first).toMatchInlineSnapshot(`
+                <span
+                  tabindex="0"
+                />
+            `);
+        });
+
+        it('should keep disabled=false', () => {
+            const element = htmlToElement('<div><button disabled="false" /><button /></div>');
+            const focusable = getFirstAndLastFocusable(element);
+            expect(focusable.first).toMatchInlineSnapshot(`
+                <button
+                  disabled="false"
+                />
+            `);
+        });
+
+        it('should keep aria-disabled=false', () => {
+            const element = htmlToElement('<div><button aria-disabled="false" /><button /></div>');
+            const focusable = getFirstAndLastFocusable(element);
+            expect(focusable.first).toMatchInlineSnapshot(`
+                <button
+                  aria-disabled="false"
+                />
+            `);
+        });
+    });
+
+    describe('skip disabled elements', () => {
+        it('should skip disabled', () => {
+            const element = htmlToElement('<div><button disabled /><button /></div>');
+            const focusable = getFirstAndLastFocusable(element);
+            expect(focusable.first).toMatchInlineSnapshot('<button />');
+        });
+
+        it('should skip aria-disabled', () => {
+            const element = htmlToElement('<div><button aria-disabled /><button /></div>');
+            const focusable = getFirstAndLastFocusable(element);
+            expect(focusable.first).toMatchInlineSnapshot('<button />');
+        });
+
+        it('should skip tabindex=-1', () => {
+            const element = htmlToElement('<div><button tabindex="-1" /><button /></div>');
+            const focusable = getFirstAndLastFocusable(element);
+            expect(focusable.first).toMatchInlineSnapshot('<button />');
+        });
+
+        it('should skip input type hidden', () => {
+            const element = htmlToElement('<div><input type="hidden" /><button /></div>');
+            const focusable = getFirstAndLastFocusable(element);
+            expect(focusable.first).toMatchInlineSnapshot('<button />');
+        });
+
+        it('should skip hidden input', () => {
+            const element = htmlToElement('<div><input hidden /><button /></div>');
+            const focusable = getFirstAndLastFocusable(element);
+            expect(focusable.first).toMatchInlineSnapshot('<button />');
+        });
+    });
+});

package/src/utils/browser/focus/getFirstAndLastFocusable.ts

@@ -0,0 +1,21 @@
+import { getFocusableElements } from './getFocusableElements';
+
+/**
+ * Get first and last elements focusable in an element.
+ *
+ * @param parentElement The element in which to search focusable elements.
+ * @return first and last focusable elements
+ */
+export function getFirstAndLastFocusable(parentElement: HTMLElement | ShadowRoot) {
+    const focusableElements = getFocusableElements(parentElement);
+
+    // First non disabled element.
+    const first = focusableElements[0];
+    // Last non disabled element.
+    const last = focusableElements[focusableElements.length - 1];
+
+    if (last && first) {
+        return { first, last };
+    }
+    return {};
+}

package/src/utils/browser/focus/getFocusableElements.test.ts

@@ -0,0 +1,151 @@
+import { getFocusableElements } from './getFocusableElements';
+
+function htmlToElement(html: string): any {
+    const template = document.createElement('template');
+    template.innerHTML = html.trim();
+    return template.content.firstChild;
+}
+
+describe(getFocusableElements.name, () => {
+    it('should get empty', () => {
+        const element = htmlToElement('<div></div>');
+        const focusable = getFocusableElements(element);
+        expect(focusable).toEqual([]);
+    });
+
+    it('should get single item', () => {
+        const element = htmlToElement('<div><button /></div>');
+        const focusable = getFocusableElements(element);
+        expect(focusable).toMatchInlineSnapshot(`
+            [
+              <button />,
+            ]
+        `);
+    });
+
+    describe('match focusable elements', () => {
+        it('should match input element', () => {
+            const element = htmlToElement('<div><input /></div>');
+            const focusable = getFocusableElements(element);
+            expect(focusable).toMatchInlineSnapshot(`
+                [
+                  <input />,
+                ]
+            `);
+        });
+
+        it('should match link element', () => {
+            const element = htmlToElement('<div><a href="#" /></div>');
+            const focusable = getFocusableElements(element);
+            expect(focusable).toMatchInlineSnapshot(`
+                [
+                  <a
+                    href="#"
+                  />,
+                ]
+            `);
+        });
+
+        it('should match textarea element', () => {
+            const element = htmlToElement('<div><textarea /></div>');
+            const focusable = getFocusableElements(element);
+            expect(focusable).toMatchInlineSnapshot(`
+                [
+                  <textarea>
+                    &lt;/div&gt;
+                  </textarea>,
+                ]
+            `);
+        });
+
+        it('should match element with tabindex', () => {
+            const element = htmlToElement('<div><span tabindex="0" /></div>');
+            const focusable = getFocusableElements(element);
+            expect(focusable).toMatchInlineSnapshot(`
+                [
+                  <span
+                    tabindex="0"
+                  />,
+                ]
+            `);
+        });
+
+        it('should keep disabled=false', () => {
+            const element = htmlToElement('<div><button disabled="false" /><button /></div>');
+            const focusable = getFocusableElements(element);
+            expect(focusable).toMatchInlineSnapshot(`
+                [
+                  <button
+                    disabled="false"
+                  />,
+                  <button />,
+                ]
+            `);
+        });
+
+        it('should keep aria-disabled=false', () => {
+            const element = htmlToElement('<div><button aria-disabled="false" /><button /></div>');
+            const focusable = getFocusableElements(element);
+            expect(focusable).toMatchInlineSnapshot(`
+                [
+                  <button
+                    aria-disabled="false"
+                  />,
+                  <button />,
+                ]
+            `);
+        });
+    });
+
+    describe('skip disabled elements', () => {
+        it('should skip disabled', () => {
+            const element = htmlToElement('<div><button disabled /><button /></div>');
+            const focusable = getFocusableElements(element);
+            expect(focusable).toMatchInlineSnapshot(`
+                [
+                  <button />,
+                ]
+            `);
+        });
+
+        it('should skip aria-disabled', () => {
+            const element = htmlToElement('<div><button aria-disabled /><button /></div>');
+            const focusable = getFocusableElements(element);
+            expect(focusable).toMatchInlineSnapshot(`
+                [
+                  <button />,
+                ]
+            `);
+        });
+
+        it('should skip tabindex=-1', () => {
+            const element = htmlToElement('<div><button tabindex="-1" /><button /></div>');
+            const focusable = getFocusableElements(element);
+            expect(focusable).toMatchInlineSnapshot(`
+                [
+                  <button />,
+                ]
+            `);
+        });
+
+        it('should skip input type hidden', () => {
+            const element = htmlToElement('<div><input type="hidden" /><button /></div>');
+            const focusable = getFocusableElements(element);
+            expect(focusable).toMatchInlineSnapshot(`
+                [
+                  <button />,
+                ]
+            `);
+        });
+
+        it('should skip hidden input', () => {
+            const element = htmlToElement('<div><input hidden /><button /></div>');
+            const focusable = getFocusableElements(element);
+            expect(focusable).toMatchInlineSnapshot(`
+                [
+                  <button />,
+                ]
+            `);
+        });
+    });
+});

package/src/utils/browser/focus/getFocusableElements.ts

@@ -0,0 +1,7 @@
+import { DISABLED_SELECTOR, TABBABLE_ELEMENTS_SELECTOR } from './constants';
+
+const isNotDisabled = (element: HTMLElement) => !element.matches(DISABLED_SELECTOR);
+
+export function getFocusableElements(element: HTMLElement | ShadowRoot): HTMLElement[] {
+    return Array.from(element.querySelectorAll<HTMLElement>(TABBABLE_ELEMENTS_SELECTOR)).filter(isNotDisabled);
+}

package/src/utils/browser/isFocusVisible.ts

@@ -0,0 +1,9 @@
+/** Check if the focus is visible on the given element */
+export const isFocusVisible = (element?: HTMLElement) => {
+    try {
+        return element?.matches?.(':focus-visible, [data-focus-visible-added]');
+    } catch (_ignored) {
+        // Can fail on non browser env
+        return true;
+    }
+};

package/src/utils/browser/isHoverNotSupported.test.js

@@ -0,0 +1,24 @@
+import { isHoverNotSupported } from './isHoverNotSupported';
+
+const originalMatchMedia = global.matchMedia;
+
+describe('isHoverNotSupported', () => {
+    afterAll(() => {
+        global.matchMedia = originalMatchMedia;
+    });
+
+    it('should return `false` on browsers that do not support matchMedia', () => {
+        global.matchMedia = undefined;
+        expect(isHoverNotSupported()).toBe(false);
+    });
+
+    it('should return `false` on browsers that support matchMedia and does support hover', () => {
+        global.matchMedia = () => ({ matches: false });
+        expect(isHoverNotSupported()).toBe(false);
+    });
+
+    it('should return `true` on browsers that support matchMedia and does not support hover', () => {
+        global.matchMedia = () => ({ matches: true });
+        expect(isHoverNotSupported()).toBe(true);
+    });
+});

package/src/utils/browser/isHoverNotSupported.ts

@@ -0,0 +1,2 @@
+/** Return true if the browser does not support pointer hover */
+export const isHoverNotSupported = (): boolean => !!window.matchMedia?.('(hover: none)').matches;

package/src/utils/browser/isReducedMotion.ts

@@ -0,0 +1,6 @@
+import { WINDOW } from '@lumx/react/constants';
+
+/** Check if user prefers reduced motion */
+export function isReducedMotion() {
+    return WINDOW?.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+}

package/src/utils/date/addMonthResetDay.test.ts

@@ -0,0 +1,13 @@
+import { addMonthResetDay } from '@lumx/react/utils/date/addMonthResetDay';
+
+describe(addMonthResetDay.name, () => {
+    it('should add month to date', () => {
+        const actual = addMonthResetDay(new Date('2017-01-30'), 1);
+        expect(actual).toEqual(new Date('2017-02-01'));
+    });
+
+    it('should remove months to date', () => {
+        const actual = addMonthResetDay(new Date('2017-01-30'), -2);
+        expect(actual).toEqual(new Date('2016-11-01'));
+    });
+});

package/src/utils/date/addMonthResetDay.ts

@@ -0,0 +1,9 @@
+/**
+ * Add a number of months from a date while resetting the day to prevent month length mismatches.
+ */
+export function addMonthResetDay(date: Date, monthOffset: number) {
+    const newDate = new Date(date.getTime());
+    newDate.setDate(1);
+    newDate.setMonth(date.getMonth() + monthOffset);
+    return newDate;
+}

package/src/utils/date/formatDayNumber.test.ts

@@ -0,0 +1,12 @@
+import { formatDayNumber } from '@lumx/react/utils/date/formatDayNumber';
+
+describe(formatDayNumber, () => {
+    it('should format ', () => {
+        // Standard numerical formatting.
+        expect(formatDayNumber('en', new Date('2024-05-11'))).toEqual('11');
+        // Keep only the numerical part (if any). Raw formatted day number here is '11日'.
+        expect(formatDayNumber('ja', new Date('2024-05-11'))).toEqual('11');
+        // Else Keep the non-numerical formatting
+        expect(formatDayNumber('ar-eg', new Date('2024-05-11'))).toEqual('١١');
+    });
+});

package/src/utils/date/formatDayNumber.ts

@@ -0,0 +1,5 @@
+export function formatDayNumber(locale: string, date: Date): string {
+    const formattedDate = date.toLocaleDateString(locale, { day: 'numeric' });
+    if (formattedDate.match(/\d/)) return formattedDate.replace(/\D*(\d+)\D*/g, '$1');
+    return formattedDate;
+}

package/src/utils/date/getFirstDayOfWeek.test.ts

@@ -0,0 +1,20 @@
+import { Locale } from '@lumx/react/utils/locale/types';
+import { parseLocale } from '../locale/parseLocale';
+import { getFirstDayOfWeek } from './getFirstDayOfWeek';
+
+describe(getFirstDayOfWeek.name, () => {
+    it('should return for a valid locales', () => {
+        expect(getFirstDayOfWeek(parseLocale('fa-ir') as Locale)).toBe(6);
+        expect(getFirstDayOfWeek(parseLocale('ar-ma') as Locale)).toBe(1);
+        expect(getFirstDayOfWeek(parseLocale('ar') as Locale)).toBe(6);
+        expect(getFirstDayOfWeek(parseLocale('en') as Locale)).toBe(0);
+    });
+
+    it('should return for the lang locale if available', () => {
+        // Test for a specific locale and its root locale
+        const localeWithRoot = parseLocale('es-ES') as Locale; // Spanish (Spain) with root locale es
+        const expectedFirstDay = getFirstDayOfWeek(parseLocale('es') as Locale); // First day for root locale 'es'
+
+        expect(getFirstDayOfWeek(localeWithRoot)).toBe(expectedFirstDay);
+    });
+});