@evolve.ui/core-components 1.0.0 → 1.1.0

package/src/Drawer/Drawer.tsx

@@ -0,0 +1,446 @@
+import { cn } from '@evolve.ui/theme-system';
+import { ReactNode, useCallback, useEffect, useRef, useState } from 'react';
+
+import { effectEventListener } from '../utils/effectEventListener';
+import { keepTransition } from '../utils/keepTransition';
+import { nodeEnv } from '../utils/nodeEnv';
+import { DialogActions } from './components/DialogActions/DialogActions';
+import { DialogContent } from './components/DialogContent/DialogContent';
+import { DialogHeader } from './components/DialogHeader/DialogHeader';
+
+type ReasonForClose = 'backdrop' | 'closeButton' | 'escape' | 'external';
+
+type Props = {
+    /**
+     * Optional actions to display at the bottom of the drawer
+     * Actions container has these styles:
+     * ```css
+     * display: flex;
+     * gap: 16px;
+     * > button {
+     *      flex-grow: 1;
+     * }
+     * ```
+     *
+     * Usage:
+     * ```tsx
+     * <Drawer actions={<Button>Save</Button>} />
+     * ```
+     *
+     */
+    actions?: ReactNode;
+    /**
+     * Optional anchor for the drawer
+     *
+     * Usage:
+     * ```tsx
+     * <Drawer anchor="left" />
+     * ```
+     *
+     * @default 'right'
+     */
+    anchor?: 'left' | 'right';
+    /**
+     * Children of the drawer are the content of the drawer
+     *
+     * Usage:
+     * ```tsx
+     * <Drawer><div>Hello World</div></Drawer>
+     * ```
+     *
+     */
+    children?: ReactNode;
+    /**
+     * Optional class name for the drawer
+     *
+     * Usage:
+     * ```tsx
+     * <Drawer className="bg-red-500" />
+     * ```
+     *
+     */
+    className?: string;
+    /**
+     * Optional flag to close the drawer when the user clicks outside
+     *
+     * Usage:
+     * ```tsx
+     * <Drawer closeOnOutsideClick={false} />
+     * ```
+     *
+     * @default true
+     */
+    closeOnOutsideClick?: boolean;
+    /**
+     * Optional flag to close the drawer when the user presses the Escape key
+     *
+     * Usage:
+     * ```tsx
+     * <Drawer closeOnEscape={false} />
+     * ```
+     *
+     * @default true
+     */
+    closeOnEscape?: boolean;
+    /**
+     * Optional custom header to replace the default DialogHeader
+     *
+     * Usage:
+     * ```tsx
+     * <Drawer customHeader={<div>Custom Header</div>} />
+     * ```
+     *
+     */
+    customHeader?: ReactNode;
+    /**
+     * Optional density for the drawer
+     *
+     * Usage:
+     * ```tsx
+     * <Drawer density="compact" />
+     * ```
+     *
+     * @default 'comfortable'
+     */
+    density?: 'compact' | 'comfortable';
+    /**
+     * Optional flag to disable scrolling in the drawer content area
+     * Useful when the content has its own scrollable areas (e.g., tabs)
+     *
+     * Usage:
+     * ```tsx
+     * <Drawer disableScroll />
+     * ```
+     *
+     * @default false
+     */
+    disableScroll?: boolean;
+    /**
+     * Required function call when drawer closes, this will almost always be a call to `setShowState(false)`
+     *
+     * Usage:
+     * ```tsx
+     * const [show, setShow] = useState(false);
+     * ...
+     * <Drawer handleClose={() => setShow(false)} />
+     * ```
+     *
+     */
+    handleClose: (reason?: ReasonForClose) => void;
+    /**
+     * Optional flag that controls whether the drawer has a drop shadow
+     *
+     * Usage:
+     * ```tsx
+     * <Drawer hasShadow />
+     * ```
+     *
+     */
+    hasShadow?: boolean;
+    /**
+     * Optional header text for the drawer, appears at the top of the drawer
+     *
+     * Usage:
+     * ```tsx
+     * <Drawer headerText="Hello World" />
+     * ```
+     *
+     */
+    headerText?: string | ReactNode;
+    /**
+     * Optional alignment for the header text
+     *
+     * Usage:
+     * ```tsx
+     * <Drawer headerTextAlign="left" />
+     * ```
+     *
+     * @default 'center'
+     */
+    headerTextAlign?: 'center' | 'left' | 'right';
+    /**
+     * Optional flag to keep the drawer in the DOM while closed
+     *
+     * Usage:
+     * ```tsx
+     * <Drawer keepInDOMWhileClosed={false} />
+     * ```
+     * @default true
+     */
+    keepInDOMWhileClosed?: boolean;
+
+    /**
+     * Optional function call when the back button is clicked
+     *
+     * Usage:
+     * ```tsx
+     * <Drawer onBackButtonClick={() => console.log('Back button clicked')} />
+     * ```
+     *
+     */
+    onBackButtonClick?: () => void;
+    /**
+     * Required flag to show the drawer
+     *
+     * Usage:
+     * ```tsx
+     * <Drawer show />
+     * ```
+     *
+     */
+    show: boolean;
+    /**
+     * Optional size for the drawer
+     *
+     * Usage:
+     * ```tsx
+     * <Drawer size="wide" />
+     * ```
+     *
+     * @default 'narrow'
+     */
+    size?: 'narrow' | 'wide' | 'extended' | 'full';
+    /**
+     * Optional flag to control the action container
+     *
+     * Usage:
+     * ```tsx
+     * <Drawer useCustomButtonContainer />
+     * ```
+     *
+     */
+    useCustomButtonContainer?: boolean;
+};
+
+// Open drawers share a single body scroll-lock. Module-scoped so the lock is
+// released only when the last open drawer closes, and so the body's original
+// overflow / padding are captured once (when the first drawer opens) and
+// restored at the end rather than hardcoding values.
+let openDrawerCount = 0;
+let previousBodyOverflow = '';
+let previousBodyPaddingRight = '';
+
+// Identities of currently-open drawers, in open order. Escape only closes the
+// last one pushed (the top-most), so stacked drawers close one at a time
+// instead of all collapsing on a single keypress. Per-instance ref objects are
+// used as identities rather than useId so this doesn't consume React's id
+// sequence and shift autogenerated ids in consumer snapshots.
+const openDrawerStack: object[] = [];
+
+/**
+ * A drawer component using the `dialog` element
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog
+ */
+export const Drawer = ({
+    actions,
+    anchor = 'right',
+    children,
+    className,
+    closeOnEscape = true,
+    closeOnOutsideClick = true,
+    customHeader,
+    density = 'comfortable',
+    disableScroll = false,
+    handleClose,
+    hasShadow = false,
+    headerText,
+    headerTextAlign = 'center',
+    keepInDOMWhileClosed = true,
+    onBackButtonClick,
+    show,
+    size = 'narrow',
+    useCustomButtonContainer = false,
+}: Props) => {
+    const reasonForClose = useRef<ReasonForClose>('external');
+    // Per-instance ref instead of a shared id: several Drawers can be mounted at
+    // once, and a duplicate id would make a lookup match the wrong backdrop.
+    const backdropRef = useRef<HTMLDivElement>(null);
+    const drawerIdRef = useRef<object>({});
+    const [renderDrawer, setRenderDrawer] = useState(show);
+
+    const removeTransitionForTest = Boolean(nodeEnv === 'test') && Boolean(keepTransition() !== 'true');
+
+    const startCloseTransition = useCallback(
+        (reason: ReasonForClose) => {
+            setRenderDrawer(false);
+            reasonForClose.current = reason;
+
+            // Close the drawer immediately in test environment
+            if (removeTransitionForTest) {
+                handleClose(reason);
+            }
+        },
+        [handleClose, removeTransitionForTest]
+    );
+
+    // Close the drawer when the show prop changes to false
+    useEffect(() => {
+        if (renderDrawer && !show) {
+            startCloseTransition('external');
+        }
+    }, [renderDrawer, show, startCloseTransition]);
+
+    //  Show the drawer when the show prop changes to true
+    useEffect(() => {
+        if (show) {
+            setRenderDrawer(true);
+        }
+    }, [show]);
+
+    // Close the drawer when the escape key is pressed. Only listen while this
+    // drawer is open so a closed instance never preventDefaults Escape for
+    // other components, and only the top-most open drawer reacts so stacked
+    // drawers close one at a time rather than all at once.
+    useEffect(() => {
+        if (!renderDrawer || !closeOnEscape) {
+            return;
+        }
+
+        const drawerIdentity = drawerIdRef.current;
+        openDrawerStack.push(drawerIdentity);
+
+        const removeListener = effectEventListener(window, 'keydown', (event) => {
+            if (!(event instanceof KeyboardEvent) || event.key !== 'Escape') {
+                return;
+            }
+            if (openDrawerStack[openDrawerStack.length - 1] !== drawerIdentity) {
+                return;
+            }
+            event.preventDefault();
+            startCloseTransition('escape');
+        });
+
+        return () => {
+            const index = openDrawerStack.lastIndexOf(drawerIdentity);
+            if (index !== -1) {
+                openDrawerStack.splice(index, 1);
+            }
+            removeListener();
+        };
+    }, [renderDrawer, closeOnEscape, startCloseTransition]);
+
+    // Close the drawer when the backdrop is clicked
+    useEffect(() => {
+        const handleBackdropClick = (event: MouseEvent) => {
+            if (event.target === backdropRef.current && closeOnOutsideClick) {
+                startCloseTransition('backdrop');
+            }
+        };
+
+        window.addEventListener('click', handleBackdropClick);
+
+        return () => {
+            window.removeEventListener('click', handleBackdropClick);
+        };
+    }, [closeOnOutsideClick, startCloseTransition]);
+
+    // Prevent body scrolling while any drawer is open. Ref-counted across
+    // instances so closing one drawer does not unlock scroll while another is
+    // still open; the first drawer to open captures the body's prior overflow
+    // and padding and the last to close restores them. The scrollbar's width is
+    // added as padding-right while locked so hiding the scrollbar doesn't shift
+    // the page (mirrors modal/PreventModalScroll).
+    useEffect(() => {
+        if (!show) {
+            return;
+        }
+
+        if (openDrawerCount === 0) {
+            previousBodyOverflow = document.body.style.overflow;
+            previousBodyPaddingRight = document.body.style.paddingRight;
+
+            const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
+            if (scrollbarWidth > 0) {
+                document.body.style.paddingRight = `${scrollbarWidth}px`;
+            }
+        }
+        openDrawerCount += 1;
+        document.body.style.overflow = 'hidden';
+
+        return () => {
+            openDrawerCount -= 1;
+            if (openDrawerCount === 0) {
+                document.body.style.overflow = previousBodyOverflow;
+                document.body.style.paddingRight = previousBodyPaddingRight;
+            }
+        };
+    }, [show]);
+
+    // Render children when the drawer is closed and keepInDOMWhileClosed is true
+    const renderWhenClosed = keepInDOMWhileClosed || renderDrawer;
+
+    return (
+        <>
+            <div
+                className={cn(
+                    'hui-focus-visible-outline invisible fixed inset-0 z-30 bg-background-overlay opacity-0 duration-500 focus:m-2xs focus:transition-none',
+                    {
+                        'opacity-1 visible': renderDrawer,
+                        'pointer-events-none invisible opacity-0': !renderDrawer,
+                        'transition-none': removeTransitionForTest,
+                    }
+                )}
+                data-testid="drawer-backdrop"
+                ref={backdropRef}
+            />
+            <dialog
+                aria-label="Drawer Menu"
+                className={cn(
+                    // GENERAL
+                    'm-w-[320px] fixed top-0 z-40 flex h-full max-h-full w-full flex-col p-0',
+                    // SIZE
+                    {
+                        'h-[100vh] w-[100vw]': size === 'full',
+                        'max-w-[320px]': size === 'narrow',
+                        'max-w-[480px]': size === 'wide',
+                        'max-w-[720px]': size === 'extended',
+                    },
+                    // SHADOW
+                    { 'shadow-04': hasShadow },
+                    // ANCHOR
+                    { 'left-0 ml-0': anchor === 'left', 'right-0 mr-0': anchor === 'right' },
+                    // ANIMATION
+                    {
+                        'invisible -translate-x-full opacity-0 transition-all': !renderDrawer && anchor === 'left',
+                        'invisible translate-x-full opacity-0 transition-all': !renderDrawer && anchor === 'right',
+                        'opacity-1 -translate-x-0 transition-all': renderDrawer && anchor === 'left',
+                        'opacity-1 translate-x-0 transition-all': renderDrawer && anchor === 'right',
+                        'transition-none': removeTransitionForTest,
+                    },
+                    className
+                )}
+                data-hui-id="Drawer"
+                onTransitionEnd={() => !renderDrawer && handleClose(reasonForClose.current)}
+                open={renderDrawer}
+            >
+                {customHeader !== undefined ? (
+                    customHeader
+                ) : (
+                    <DialogHeader
+                        density={density}
+                        onBackButtonClick={onBackButtonClick}
+                        onCloseButtonClick={() => startCloseTransition('closeButton')}
+                        textAlign={headerTextAlign}
+                    >
+                        {headerText}
+                    </DialogHeader>
+                )}
+                <DialogContent
+                    density={density}
+                    disableScroll={disableScroll}
+                    renderWhenClosed={renderWhenClosed}
+                >
+                    {children}
+                </DialogContent>
+                {actions && (
+                    <DialogActions
+                        density={density}
+                        useCustomButtonContainer={useCustomButtonContainer}
+                    >
+                        {actions}
+                    </DialogActions>
+                )}
+            </dialog>
+        </>
+    );
+};

package/src/Drawer/atoms.ts

@@ -0,0 +1,4 @@
+import { atomWithReset } from 'jotai/utils';
+
+export const showBottomScrollHintAtom = atomWithReset<boolean>(false);
+export const showTopScrollHintAtom = atomWithReset<boolean>(false);

package/src/Drawer/components/DialogActions/DialogActions.tsx

@@ -0,0 +1,33 @@
+import { cn } from '@evolve.ui/theme-system';
+import { useAtomValue } from 'jotai';
+import { ReactNode, useContext } from 'react';
+
+import { ModalContext } from '../../../Modal/context';
+
+type Props = {
+    children: ReactNode;
+    className?: string;
+    density?: 'compact' | 'comfortable';
+    useCustomButtonContainer?: boolean;
+};
+
+export const DialogActions = ({ children, className, density, useCustomButtonContainer }: Props) => {
+    const { showBottomScrollHintAtom } = useContext(ModalContext);
+    const showBottomScrollHint = useAtomValue(showBottomScrollHintAtom);
+
+    return (
+        <div
+            className={cn(
+                'flex grow-0 gap-sm p-sm',
+                {
+                    '[&_button]:grow-[1]': !useCustomButtonContainer,
+                    'p-xs': density === 'compact',
+                    'shadow-05': showBottomScrollHint,
+                },
+                className
+            )}
+        >
+            {children}
+        </div>
+    );
+};

package/src/Drawer/components/DialogContent/DialogContent.tsx

@@ -0,0 +1,80 @@
+import { cn } from '@evolve.ui/theme-system';
+import { useSetAtom } from 'jotai';
+import { ReactNode, useCallback, useContext, useEffect, useRef } from 'react';
+
+import { ModalContext } from '../../../Modal/context';
+import { effectEventListener } from '../../../utils/effectEventListener';
+
+type Props = {
+    children: ReactNode;
+    density?: 'compact' | 'comfortable';
+    disableScroll?: boolean;
+    renderWhenClosed: boolean;
+};
+
+export const DialogContent = ({ children, density, disableScroll = false, renderWhenClosed }: Props) => {
+    const { showBottomScrollHintAtom, showTopScrollHintAtom } = useContext(ModalContext);
+    const setShowBottomScrollHint = useSetAtom(showBottomScrollHintAtom);
+    const setShowTopScrollHint = useSetAtom(showTopScrollHintAtom);
+
+    const handleScroll = useCallback(
+        (contentRef: HTMLDivElement) => () => {
+            if (contentRef.scrollHeight > contentRef.clientHeight + 32) {
+                const atTheBottom =
+                    Math.round(contentRef.scrollHeight - contentRef.scrollTop) - 5 < contentRef.clientHeight;
+                const atTheTop = contentRef.scrollTop < 25;
+
+                setShowBottomScrollHint(!atTheBottom);
+                setShowTopScrollHint(!atTheTop);
+            } else if (contentRef.scrollTop === 0) {
+                setShowBottomScrollHint(false);
+                setShowTopScrollHint(false);
+            }
+        },
+        [setShowBottomScrollHint, setShowTopScrollHint]
+    );
+
+    const onScrollRef = useRef<ReturnType<typeof handleScroll>>(null);
+
+    // Trigger handleScroll on window resize
+    useEffect(() => {
+        return effectEventListener(window, 'resize', () => onScrollRef.current?.());
+    }, [handleScroll]);
+
+    return (
+        <div
+            className={cn('grow-[1] border-y border-solid border-border-secondary', {
+                'flex flex-col overflow-hidden': disableScroll,
+                'h-[100vh] overflow-y-auto': !disableScroll,
+                'p-sm': !disableScroll && density !== 'compact',
+                'p-xs': !disableScroll && density === 'compact',
+            })}
+            data-testid="dialog-content"
+            ref={(ref) => {
+                if (!ref) {
+                    return;
+                }
+
+                const onScroll = handleScroll(ref);
+                onScrollRef.current = onScroll;
+
+                const resizeObserver = new ResizeObserver(() => {
+                    const scrollHeight = ref.scrollHeight;
+                    const clientHeight = ref.clientHeight;
+
+                    if (scrollHeight === clientHeight + 32) {
+                        setShowBottomScrollHint(false);
+                        setShowTopScrollHint(false);
+                    } else {
+                        onScroll();
+                    }
+                });
+
+                resizeObserver.observe(ref);
+                ref.addEventListener('scroll', onScroll);
+            }}
+        >
+            {renderWhenClosed ? children : null}
+        </div>
+    );
+};

package/src/Drawer/components/DialogHeader/DialogHeader.tsx

@@ -0,0 +1,68 @@
+import { cn } from '@evolve.ui/theme-system';
+import { useAtomValue } from 'jotai';
+import { ReactNode, useContext } from 'react';
+
+import { IconButton } from '../../../IconButton/IconButton';
+import { ArrowLeft, Close } from '../../../Icons';
+import { ModalContext } from '../../../Modal/context';
+import { H2 } from '../../../Typography/Text/Text';
+
+type Props = {
+    children?: ReactNode;
+    density: 'compact' | 'comfortable';
+    onBackButtonClick?: () => void;
+    onCloseButtonClick: () => void;
+    textAlign?: 'center' | 'left' | 'right';
+};
+
+export const DialogHeader = ({
+    children,
+    density = 'comfortable',
+    onBackButtonClick,
+    onCloseButtonClick,
+    textAlign = 'center',
+}: Props) => {
+    const { showTopScrollHintAtom } = useContext(ModalContext);
+    const showTopScrollHint = useAtomValue(showTopScrollHintAtom);
+
+    return (
+        <div
+            className={cn('relative grid grid-cols-[42px_1fr_42px] gap-[4px] p-sm', {
+                'p-xs': density === 'compact',
+                'shadow-01': showTopScrollHint,
+            })}
+        >
+            {onBackButtonClick !== undefined && (
+                <IconButton
+                    aria-label="Go Back"
+                    className={cn('col-start-1 col-end-2')}
+                    data-testid="back-button"
+                    hideTooltip
+                    icon={ArrowLeft}
+                    onClick={onBackButtonClick}
+                    size="md"
+                    type="button"
+                />
+            )}
+            <div
+                className={cn('col-start-2 col-end-3 flex', {
+                    'justify-center text-center': textAlign === 'center',
+                    'justify-end text-right': textAlign === 'right',
+                    'justify-start text-left': textAlign === 'left',
+                })}
+                data-testid="dialog-header-text-container"
+            >
+                {typeof children === 'string' ? <H2 className="pt-[6px]">{children}</H2> : children}
+            </div>
+            <IconButton
+                className={cn('col-start-3 col-end-4')}
+                data-testid="close-button"
+                hideTooltip
+                icon={Close}
+                onClick={onCloseButtonClick}
+                size="md"
+                type="button"
+            />
+        </div>
+    );
+};