@evolve.ui/core-components 1.0.0 → 1.1.0

package/src/Modal/components/index.ts

@@ -0,0 +1,12 @@
+// ModalTarget lives with the provider targets (single source of truth — the
+// provider mounts it) and is re-exported here to match hammer's `modal/components`
+// public surface.
+export { ModalTarget } from '../../providers/targets/ModalTarget';
+export { BackButton } from './BackButton/BackButton';
+export { CloseButton } from './CloseButton/CloseButton';
+export { ModalActions } from './ModalActions/ModalActions';
+export { ModalContent } from './ModalContent/ModalContent';
+export { ModalHeader } from './ModalHeader/ModalHeader';
+export { ModalProgressSteps } from './ModalProgressSteps/ModalProgressSteps';
+export { ModalSubTitle } from './ModalSubTitle/ModalSubTitle';
+export { ModalTitle } from './ModalTitle/ModalTitle';

package/src/Modal/context.ts

@@ -0,0 +1,33 @@
+import { atomWithReset } from 'jotai/utils';
+import { createContext } from 'react';
+
+type ModalContextType = {
+    closeModalOnBackdropClickAtom: ReturnType<typeof atomWithReset<boolean>>;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- hammer-parity: handleCloseData is an arbitrary consumer-defined payload forwarded verbatim to handleClose
+    handleClose?: (handleCloseData?: any) => void;
+    isMobileKeyboardOpen: ReturnType<typeof atomWithReset<boolean>>;
+    modalAnimationAtom: ReturnType<typeof atomWithReset<'opening' | 'closing' | ''>>;
+    modalFullScreenAtom: ReturnType<typeof atomWithReset<boolean>>;
+    modalHasFooterAtom: ReturnType<typeof atomWithReset<boolean>>;
+    modalHasProgressStepsAtom: ReturnType<typeof atomWithReset<boolean>>;
+    modalRefAtom: ReturnType<typeof atomWithReset<{ current: HTMLDialogElement | null }>>;
+    onModalCloseAnimationEnd?: () => void;
+    scrollTopAtom: ReturnType<typeof atomWithReset<number>>;
+    showBottomScrollHintAtom: ReturnType<typeof atomWithReset<boolean>>;
+    showTopScrollHintAtom: ReturnType<typeof atomWithReset<boolean>>;
+};
+
+export const defaultModalContext: ModalContextType = {
+    closeModalOnBackdropClickAtom: atomWithReset(true),
+    isMobileKeyboardOpen: atomWithReset<boolean>(false),
+    modalAnimationAtom: atomWithReset<'opening' | 'closing' | ''>(''),
+    modalFullScreenAtom: atomWithReset<boolean>(false),
+    modalHasFooterAtom: atomWithReset<boolean>(false),
+    modalHasProgressStepsAtom: atomWithReset<boolean>(false),
+    modalRefAtom: atomWithReset<{ current: HTMLDialogElement | null }>({ current: null }),
+    scrollTopAtom: atomWithReset(0),
+    showBottomScrollHintAtom: atomWithReset<boolean>(false),
+    showTopScrollHintAtom: atomWithReset<boolean>(false),
+};
+
+export const ModalContext = createContext<ModalContextType>(defaultModalContext);

package/src/Modal/hooks/useCloseModal.ts

@@ -0,0 +1,133 @@
+import { useSetAtom } from 'jotai';
+import { useResetAtom } from 'jotai/utils';
+import { useCallback, useContext } from 'react';
+
+import { nodeEnv } from '../../utils/nodeEnv';
+import { defaultModalContext, ModalContext } from '../context';
+
+/**
+ * Closes the modal without an animation.
+ *
+ * If possible, use `useCloseModal` instead.
+ *
+ * @param handleCloseData Data that will be passed to the `handleClose` function on the modal.
+ * By default, the close button calls with `"close"` and the backdrop calls with `"backdrop"`.
+ * @returns A function that closes the modal instantly.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- hammer-parity: handleCloseData is an arbitrary consumer-defined payload forwarded verbatim to handleClose
+export const useForceCloseModal = (handleCloseData?: any) => {
+    const modalContext = useContext(ModalContext);
+
+    if (modalContext === defaultModalContext) {
+        throw new Error(
+            'useForceCloseModal must be used within a Modal. If you need to programmatically close a modal, change show to false instead.'
+        );
+    }
+
+    const {
+        handleClose,
+        modalAnimationAtom,
+        modalHasFooterAtom,
+        onModalCloseAnimationEnd,
+        scrollTopAtom,
+        showBottomScrollHintAtom,
+        showTopScrollHintAtom,
+    } = modalContext;
+    const resetShowBottomScrollHint = useResetAtom(showBottomScrollHintAtom);
+    const resetShowTopScrollHint = useResetAtom(showTopScrollHintAtom);
+    const resetScrollTop = useResetAtom(scrollTopAtom);
+    const resetModalHasFooter = useResetAtom(modalHasFooterAtom);
+    const resetIsClosingModal = useResetAtom(modalAnimationAtom);
+
+    return useCallback(() => {
+        resetShowBottomScrollHint();
+        resetShowTopScrollHint();
+        resetScrollTop();
+        resetModalHasFooter();
+        resetIsClosingModal();
+        handleClose?.(handleCloseData);
+
+        // if we are in a test environment, we want to call the onModalCloseAnimationEnd callback since it is not called by the animation end event
+        if (nodeEnv === 'test') {
+            onModalCloseAnimationEnd?.();
+        }
+    }, [
+        resetShowBottomScrollHint,
+        resetShowTopScrollHint,
+        resetScrollTop,
+        resetModalHasFooter,
+        onModalCloseAnimationEnd,
+        resetIsClosingModal,
+        handleClose,
+        handleCloseData,
+    ]);
+};
+
+/**
+ * Closes the modal with an animation.
+ *
+ * If the animation does not finish, the modal will not be closed.
+ *
+ * If you want to close the modal without an animation, use `useForceCloseModal` instead.
+ *
+ * @param handleCloseData Data that will be passed to the `handleClose` function on the modal.
+ * By default, the close button calls with `"close"` and the backdrop calls with `"backdrop"`.
+ * @returns A function that closes the modal.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- hammer-parity: handleCloseData is an arbitrary consumer-defined payload forwarded verbatim to handleClose
+export const useCloseModal = (handleCloseData?: any) => {
+    const { modalAnimationAtom } = useContext(ModalContext);
+    const forceCloseModal = useForceCloseModal(handleCloseData);
+    const setModalAnimation = useSetAtom(modalAnimationAtom);
+    const isTestEnv = nodeEnv === 'test';
+
+    /* istanbul ignore next */
+    return useCallback(async () => {
+        if (typeof document === 'undefined') {
+            return;
+        }
+
+        let storedResolve: () => void;
+        let storedReject: () => void;
+        const promiseWeAwait = new Promise<void>((resolve, reject) => {
+            storedResolve = resolve;
+            storedReject = reject;
+        });
+
+        const timeout = setTimeout(() => {
+            // eslint-disable-next-line no-console
+            console.error(
+                'Modal reached error state: Modal show was set to `false` out of order. To fix, make sure you are using useCloseModal (and waiting for the animation to finish) or useForceCloseModal'
+            );
+            storedReject();
+        }, 450);
+
+        // These are hard coded in those components. Lets us use less refs.
+        const backdrop = document.querySelector('.hui-modal-backdrop') as HTMLElement | null;
+        const container = document.querySelector('.hui-modal-container') as HTMLElement | null;
+
+        if (isTestEnv) {
+            clearTimeout(timeout);
+            forceCloseModal();
+            return;
+        }
+
+        if (!backdrop || !container) {
+            return;
+        }
+
+        // If we are in a test environment, we want to close the modal immediately.
+
+        setModalAnimation('closing');
+
+        container.addEventListener('animationend', () => {
+            clearTimeout(timeout);
+            forceCloseModal();
+            storedResolve();
+        });
+
+        // Wait for the animation to finish.
+
+        await promiseWeAwait;
+    }, [forceCloseModal, setModalAnimation, isTestEnv]);
+};

package/src/NotificationBadge/NotificationBadge.tsx

@@ -0,0 +1,34 @@
+import { Badge } from '../Badge/Badge';
+
+type Props = {
+    /**
+     * Notifications count to render.
+     *
+     * Usage:
+     * ```tsx
+     * <NotificationBadge count={10} />
+     * ```
+     */
+    className?: string;
+    count: number;
+    maxCount?: number;
+};
+
+export const NotificationBadge = ({ className, count, maxCount = 99 }: Props) => {
+    if (count <= 0) {
+        return null;
+    }
+
+    return (
+        <Badge
+            className={className}
+            color="critical"
+            dense
+            emphasis="bold"
+            round
+            size="xs"
+        >
+            {count > maxCount ? `${maxCount}+` : count}
+        </Badge>
+    );
+};

package/src/Pagination/AdvancedPagination.tsx

@@ -0,0 +1,48 @@
+import { cn } from '@evolve.ui/theme-system';
+
+import { AdvancedPaginator } from './components/AdvancedPaginator/AdvancedPaginator';
+import { ItemCountDisplay, ItemRangeLabelArgs } from './components/ItemCountDisplay/ItemCountDisplay';
+import { ItemCountSelect } from './components/ItemCountSelect/ItemCountSelect';
+
+type Props = {
+    /** Renders the label when all items are shown (pageSize === 'all'). Forwarded to ItemCountDisplay. */
+    allItemsLabel?: (itemCount: number) => string;
+    className?: string;
+    /** Renders the label for a paginated range. Forwarded to ItemCountDisplay. */
+    itemRangeLabel?: (args: ItemRangeLabelArgs) => string;
+    /** aria-label for the next-page button. Forwarded to AdvancedPaginator. */
+    nextPageLabel?: string;
+    /** Renders the page-count suffix. Forwarded to AdvancedPaginator. */
+    ofLabel?: (pageCount: number) => string;
+    /** aria-label for the previous-page button. Forwarded to AdvancedPaginator. */
+    previousPageLabel?: string;
+    /** Label text for the results-per-page select input. Forwarded to ItemCountSelect. */
+    resultsPerPageLabel?: string;
+};
+
+export const AdvancedPagination = ({
+    allItemsLabel,
+    className,
+    itemRangeLabel,
+    nextPageLabel,
+    ofLabel,
+    previousPageLabel,
+    resultsPerPageLabel,
+}: Props) => {
+    return (
+        <div className={cn('flex items-center justify-between p-sm', className)}>
+            <AdvancedPaginator
+                nextPageLabel={nextPageLabel}
+                ofLabel={ofLabel}
+                previousPageLabel={previousPageLabel}
+            />
+            <div className="flex items-center">
+                <ItemCountSelect resultsPerPageLabel={resultsPerPageLabel} />
+                <ItemCountDisplay
+                    allItemsLabel={allItemsLabel}
+                    itemRangeLabel={itemRangeLabel}
+                />
+            </div>
+        </div>
+    );
+};

package/src/Pagination/Pagination.tsx

@@ -0,0 +1,216 @@
+import { cn } from '@evolve.ui/theme-system';
+import { useMemo } from 'react';
+
+import { IconButton } from '../IconButton/IconButton';
+import { CaretLeft, CaretRight } from '../Icons';
+import { useWindowIsDesktop } from '../providers';
+import { BodyPrimary } from '../Typography/Text/Text';
+import { usePagination } from './paginationProvider';
+import { usePaginationQueryParams } from './utils';
+
+const ellipsis = '...' as const;
+
+type Props = {
+    /**
+     * This prop is useful when multiple paginations are on the same page.
+     *
+     * For instance, if a page had a "featured items" section
+     * and a "recent activity" section, you might want to label one as
+     * "Featured Items Pagination" and the other as "Recent Activity Pagination"
+     */
+    'aria-label'?: string;
+    className?: string;
+    /** aria-label applied to the collapsed-pages ellipsis element. */
+    collapsedPagesLabel?: string;
+    /** aria-label for the next-page button (only applied when not disabled). */
+    nextPageLabel?: string;
+    /** Returns the aria-label for a specific page anchor. Receives the page number. */
+    pageLabel?: (page: number) => string;
+    /** aria-label for the previous-page button (only applied when not disabled). */
+    previousPageLabel?: string;
+};
+
+/**
+ * `1` based pagination component
+ *
+ * @see https://www.a11ymatters.com/pattern/pagination/
+ */
+export const Pagination = ({
+    'aria-label': ariaLabel = 'Pagination Navigation',
+    className,
+    collapsedPagesLabel = 'Collapsed pages',
+    nextPageLabel = 'Next Page',
+    pageLabel = (page) => `Page ${page}`,
+    previousPageLabel = 'Previous Page',
+}: Props) => {
+    const { goToPage, page, pageCount } = usePagination();
+    const isDesktop = useWindowIsDesktop();
+    const buildQueryParams = usePaginationQueryParams();
+
+    const pageList = useMemo<(typeof ellipsis | number)[]>(() => {
+        let max = isDesktop ? 9 : 6;
+        const leftEllipsis = pageCount > max + 1 && page > 5;
+        if (leftEllipsis && isDesktop) {
+            max += 1;
+        }
+
+        const increment = isDesktop ? 3 : 1;
+        const theRestFits = page - increment + (max - 3) >= pageCount;
+        let pageCounter = leftEllipsis ? (theRestFits ? pageCount - (max - 3) - 1 : page - increment) : 2;
+
+        const resultingPages: (typeof ellipsis | number)[] = [1];
+        let pagesAdded = 1;
+
+        if (leftEllipsis) {
+            pagesAdded += 1;
+            resultingPages.push(ellipsis);
+        }
+
+        while (pagesAdded < max && pageCounter <= pageCount) {
+            resultingPages.push(pageCounter);
+
+            if (pagesAdded === max - 2 && pageCounter + 2 <= pageCount) {
+                if (pageCounter + 2 === pageCount) {
+                    resultingPages.push(pageCount - 1);
+                } else {
+                    resultingPages.push(ellipsis);
+                }
+                resultingPages.push(pageCount);
+                break;
+            }
+
+            pageCounter += 1;
+            pagesAdded += 1;
+        }
+
+        return resultingPages;
+    }, [isDesktop, page, pageCount]);
+
+    const renderedList = useMemo(() => {
+        return pageList.map((item, index) => {
+            return (
+                <li
+                    className={cn({
+                        'flex h-[34px] min-w-[34px] items-center justify-center': item === ellipsis,
+                    })}
+                    key={`pagination-${item}-${index}`}
+                >
+                    {item === ellipsis ? (
+                        <BodyPrimary
+                            aria-label={collapsedPagesLabel}
+                            className="text-link-disabled"
+                        >
+                            {item}
+                        </BodyPrimary>
+                    ) : (
+                        <a
+                            aria-current={item === page ? 'page' : undefined}
+                            aria-label={pageLabel(item)}
+                            className={cn(
+                                'hui-text-body-secondary flex h-[34px] min-w-[34px] items-center justify-center rounded-full px-xs',
+                                // FOCUS
+                                'hui-focus-visible-outline',
+                                // HOVER
+                                'hover:bg-background-hover',
+                                // CURRENT
+                                {
+                                    'hui-text-label-strong border-2 border-border-selected text-link-primary':
+                                        item === page,
+                                }
+                            )}
+                            href={buildQueryParams({ page: item })}
+                            key={`content-${item}-index-${index}`}
+                            onClick={(e) => {
+                                e.preventDefault();
+                                goToPage(item);
+                            }}
+                            // `rel` is not recommended by google's seo guidelines
+                            rel={
+                                page - 1 === item && item !== 1
+                                    ? 'prev'
+                                    : page + 1 === item && item !== pageCount
+                                      ? 'next'
+                                      : undefined
+                            }
+                        >
+                            {item}
+                        </a>
+                    )}
+                </li>
+            );
+        });
+    }, [buildQueryParams, collapsedPagesLabel, goToPage, page, pageCount, pageLabel, pageList]);
+
+    const previousPage = useMemo(() => {
+        const disabled = page === 1;
+        return (
+            <li
+                className="mr-sm"
+                key={`previous-page-${page}`}
+            >
+                <IconButton
+                    aria-disabled={disabled}
+                    aria-label={disabled ? undefined : previousPageLabel}
+                    as={disabled ? 'button' : 'a'}
+                    data-testid="pagination-previous-page"
+                    disabled={disabled}
+                    href={disabled ? undefined : buildQueryParams({ page: page - 1 })}
+                    icon={CaretLeft}
+                    onClick={(event) => {
+                        event.preventDefault();
+                        if (!disabled) {
+                            goToPage(page - 1);
+                        }
+                    }}
+                    // `rel` is not recommended by google's seo guidelines
+                    rel={disabled ? undefined : 'prev'}
+                    size="sm"
+                    variant="outlined"
+                />
+            </li>
+        );
+    }, [buildQueryParams, goToPage, page, previousPageLabel]);
+
+    const nextPage = useMemo(() => {
+        const disabled = page === pageCount;
+        return (
+            <li
+                className="ml-sm"
+                key={`next-page-${page}`}
+            >
+                <IconButton
+                    aria-disabled={disabled}
+                    aria-label={disabled ? undefined : nextPageLabel}
+                    as={disabled ? 'button' : 'a'}
+                    data-testid="pagination-next-page"
+                    disabled={disabled}
+                    href={disabled ? undefined : buildQueryParams({ page: page + 1 })}
+                    icon={CaretRight}
+                    onClick={(event) => {
+                        event.preventDefault();
+                        if (!disabled) {
+                            goToPage(page + 1);
+                        }
+                    }}
+                    // `rel` is not recommended by google's seo guidelines
+                    rel={disabled ? undefined : 'next'}
+                    size="sm"
+                    variant="outlined"
+                />
+            </li>
+        );
+    }, [buildQueryParams, goToPage, nextPageLabel, page, pageCount]);
+
+    return (
+        <nav
+            aria-label={ariaLabel}
+            className={className}
+        >
+            <ul className="flex gap-2xs">
+                {previousPage}
+                {renderedList}
+                {nextPage}
+            </ul>
+        </nav>
+    );
+};

package/src/Pagination/components/AdvancedPaginator/AdvancedPaginator.tsx

@@ -0,0 +1,52 @@
+import { IconButton } from '../../../IconButton/IconButton';
+import { CaretLeft, CaretRight } from '../../../Icons';
+import { BodyPrimary } from '../../../Typography/Text/Text';
+import { usePagination } from '../../paginationProvider';
+import { PageSelect } from './components/PageSelect/PageSelect';
+
+type Props = {
+    /** aria-label for the next-page button. */
+    nextPageLabel?: string;
+    /** Renders the page-count suffix. Receives total page count. */
+    ofLabel?: (pageCount: number) => string;
+    /** aria-label for the previous-page button. */
+    previousPageLabel?: string;
+};
+
+export const AdvancedPaginator = ({
+    nextPageLabel = 'Next Page',
+    ofLabel = (pageCount) => `of ${pageCount}`,
+    previousPageLabel = 'Previous Page',
+}: Props) => {
+    const { goToPage, page, pageCount } = usePagination();
+
+    return (
+        <div className="flex items-center">
+            <IconButton
+                aria-label={previousPageLabel}
+                data-testid="previous-page"
+                disabled={page === 1}
+                icon={CaretLeft}
+                onClick={() => {
+                    if (page !== 1) {
+                        goToPage(page - 1);
+                    }
+                }}
+                size="sm"
+            />
+            <PageSelect /> <BodyPrimary className="whitespace-nowrap px-xs">{ofLabel(pageCount)}</BodyPrimary>
+            <IconButton
+                aria-label={nextPageLabel}
+                data-testid="next-page"
+                disabled={page === pageCount}
+                icon={CaretRight}
+                onClick={() => {
+                    if (page !== pageCount) {
+                        goToPage(page + 1);
+                    }
+                }}
+                size="sm"
+            />
+        </div>
+    );
+};

package/src/Pagination/components/AdvancedPaginator/components/PageSelect/PageSelect.tsx

@@ -0,0 +1,43 @@
+import { useMemo } from 'react';
+import { components, SingleValueProps } from 'react-select';
+
+import { OptionType, Select } from '../../../../../Select/Select';
+import { usePagination } from '../../../../paginationProvider';
+
+const SingleValue = ({ children, ...props }: SingleValueProps) => {
+    return <components.SingleValue {...props}>{children}</components.SingleValue>;
+};
+
+export const PageSelect = () => {
+    const { goToPage, page, pageCount } = usePagination();
+
+    const options = useMemo(
+        () =>
+            new Array(pageCount).fill(0).map((_, i) => ({
+                label: `${i + 1}`,
+                value: i + 1,
+            })),
+        [pageCount]
+    );
+
+    return (
+        <Select
+            autoComplete="off"
+            className="pl-sm"
+            components={{ SingleValue }}
+            defaultValue={pageCount}
+            isInsideLabel
+            labelText="Page:"
+            onChange={(event?: OptionType) => goToPage(event?.value)}
+            options={options}
+            small
+            styles={{
+                singleValue: (base) => ({
+                    ...base,
+                    overflow: 'visible',
+                }),
+            }}
+            value={options[page - 1]}
+        />
+    );
+};

package/src/Pagination/components/ItemCountDisplay/ItemCountDisplay.tsx

@@ -0,0 +1,32 @@
+import { BodyPrimary } from '../../../Typography/Text/Text';
+import { usePagination } from '../../paginationProvider';
+
+export type ItemRangeLabelArgs = { end: number; start: number; total: number };
+
+type Props = {
+    /** Renders the label when all items are shown (pageSize === 'all'). Receives total item count. */
+    allItemsLabel?: (itemCount: number) => string;
+    /** Renders the label for a paginated range. Receives start, end, and total item count. */
+    itemRangeLabel?: (args: ItemRangeLabelArgs) => string;
+};
+
+export const ItemCountDisplay = ({
+    allItemsLabel = (itemCount) => `${itemCount} Items`,
+    itemRangeLabel = ({ end, start, total }) => `${start} - ${end} of ${total}`,
+}: Props) => {
+    const { itemCount, page, pageSize } = usePagination();
+
+    if (pageSize === 'all') {
+        return <BodyPrimary>{allItemsLabel(itemCount)}</BodyPrimary>;
+    }
+
+    return (
+        <BodyPrimary>
+            {itemRangeLabel({
+                end: Math.min(page * pageSize, itemCount),
+                start: (page - 1) * pageSize + 1,
+                total: itemCount,
+            })}
+        </BodyPrimary>
+    );
+};

package/src/Pagination/components/ItemCountSelect/ItemCountSelect.tsx

@@ -0,0 +1,33 @@
+import { useMemo } from 'react';
+
+import { OptionType, Select } from '../../../Select/Select';
+import { usePagination } from '../../paginationProvider';
+
+type Props = {
+    /** Label text for the results-per-page select input. */
+    resultsPerPageLabel?: string;
+};
+
+export const ItemCountSelect = ({ resultsPerPageLabel = 'Results per page:' }: Props) => {
+    const { pageSize, pageSizeOptions, setPageSize } = usePagination();
+
+    const generatedOptions: OptionType[] = useMemo(() => {
+        return pageSizeOptions.map((option) => {
+            return { label: option.toString(), value: option };
+        });
+    }, [pageSizeOptions]);
+
+    return (
+        <Select
+            autoComplete="off"
+            className="mr-sm w-[224px]"
+            defaultValue={pageSize}
+            isInsideLabel
+            labelText={resultsPerPageLabel}
+            onChange={(event?: OptionType) => setPageSize(event?.value)}
+            options={generatedOptions}
+            small
+            value={{ label: pageSize, value: pageSize }}
+        />
+    );
+};

package/src/Pagination/index.tsx

@@ -0,0 +1,3 @@
+export * from './paginationProvider';
+export * from './Pagination';
+export * from './AdvancedPagination';