@evolve.ui/core-components 1.0.0 → 1.1.0

package/src/Table/Table.tsx

@@ -0,0 +1,474 @@
+import { cn } from '@evolve.ui/theme-system';
+import { Provider, useSetAtom } from 'jotai';
+import { ComponentProps, ReactNode, useCallback, useMemo, useState } from 'react';
+
+import { Loading } from '../Loading/Loading';
+import { AdvancedPagination, PaginationProvider } from '../Pagination';
+import { BodySecondary, H3 } from '../Typography/Text/Text';
+import { TableHeader } from './components/TableHeader/TableHeader';
+import { TableControls } from './components/TablePagination/TablePagination';
+import { TableRows } from './components/TableRow/TableRows';
+import { showLeftStickyShadowAtom, TableShadow } from './components/TableShadow/TableShadow';
+import { tableStaticsContext } from './sharedState';
+import { ColumnType, SortType, StaticData, TableBackgroundStyle, TableRowDensity } from './types';
+
+type Props<T extends StaticData> = {
+    /**
+     * Adds a checkbox to the left of each row and in the header.
+     * When checked, the row is considered selected.
+     *
+     * @see `onSelectedRowsChange`
+     */
+    actionable?: boolean;
+    /**
+     * This checkbox goes in the top left of your table.
+     *
+     * You can use this to "select all" however you'd like.
+     *
+     * Needs `actionable` to be true to show.
+     */
+    actionableCheckbox?: ReactNode;
+    /**
+     * Background color style for the table.
+     * Options: 'primary', 'secondary', 'subdued', 'disabled', or 'transparent'.
+     *
+     * primary - Uses theme.color.background.primary
+     * secondary - Uses theme.color.background.secondary
+     * subdued - Uses theme.color.background.subdued
+     * disabled - Uses theme.color.background.disabled
+     * transparent - Uses transparent background
+     *
+     * @default 'primary'
+     */
+    backgroundColor?: TableBackgroundStyle;
+    className?: string;
+    /**
+     * Specification for the columns of the table.
+     * Includes how to render each item in the column.
+     */
+    columns: ColumnType<T>[];
+    /**
+     * Whether we're currently sorting by anything, and if so, what.
+     *
+     * The first item in the tuple is the column key, and the second is the sort direction.
+     *
+     * @see `onSortChange`
+     */
+    currentSort?: undefined | [string, SortType];
+    /**
+     * The rows of data to be displayed in the table.
+     */
+    data: T[];
+    /**
+     * The default sort direction for columns that are sortable.
+     */
+    defaultSortDirection?: SortType;
+    /**
+     * The text to display when there is no data.
+     */
+    emptyStateHeaderText?: string;
+    /**
+     * The supporting text to display when there is no data.
+     */
+    emptyStateSupportingText?: string;
+    /**
+     * Whether or not to fill the width of the container.
+     *
+     * Gives equal extra space to each column.
+     */
+    fillHorizontal?: boolean;
+    /**
+     * Whether or not to show the border on the main table.
+     */
+    hideBorder?: boolean;
+    /**
+     * Whether or not to hide the dividers between rows.
+     */
+    hideDividers?: boolean;
+    /**
+     * Boolean to use advance pagination component
+     */
+    isAdvancedPagination?: boolean;
+    /**
+     * Whether or not to show a loading indicator.
+     */
+    loading?: boolean;
+    /**
+     * Callback when the selected rows change.
+     *
+     * @param selectedRows the selected rows in the form of a map of row keys to booleans
+     */
+    onSelectedRowsChange?: (selectedRow: T['key']) => void;
+    /**
+     * Callback when the sort status of a column changes.
+     *
+     * @param columnKey The key of the column that was clicked
+     * @param newSort The new sort status of the column
+     * @see `currentSort`
+     */
+    onSortChange?: (columnKey: string, newSort: SortType) => void;
+    /**
+     * The page size options for the pagination component.
+     */
+    pageSizeOptions?: number[];
+    /**
+     * If provided, the table will add a pagination component.
+     *
+     * @see `PaginationProvider`
+     */
+    pagination?: Omit<ComponentProps<typeof PaginationProvider>, 'path' | 'children'> & {
+        /**
+         * The key of the pagination provider.
+         *
+         * This is used to ensure that the pagination provider is only re-rendered when the key changes.
+         * @example key={`${currentPage}-${pageSize}-${itemCount}`}
+         */
+        key?: string;
+    };
+    /**
+     * The height of the rows in the table.
+     * - `sm` = 28px
+     * - `md` = 36px
+     * - `lg` = 48px
+     *
+     * @default md
+     */
+    rowDensity?: TableRowDensity;
+    /**
+     * The rows that are currently selected.
+     *
+     * This is a controlled prop.
+     */
+    selectedRows?: Set<T['key']>;
+    /**
+     * Adds vertical dividers between columns in both header and body cells,
+     * including the actionable checkbox column. Combine with the default row
+     * dividers (`hideDividers={false}`) and outer border (`hideBorder={false}`)
+     * for a fully bordered grid.
+     *
+     * @default false
+     */
+    showColumnDividers?: boolean;
+    /**
+     * Whether or not the columns are sortable.
+     *
+     * @see `onSortChange`
+     * @see `currentSort`
+     */
+    sortable?: boolean;
+    /**
+     * Locks the first column on horizontal scroll.
+     */
+    stickyFirstColumn?: boolean;
+    /**
+     * Make header sticky when table height is set.
+     *
+     * @default false
+     *
+     * .table-container {
+     *   height: calc(100vh - 200px);
+     * }
+     */
+    stickyHeader?: boolean;
+    /**
+     * Adds a zebra stripe to every other row.
+     */
+    zebraStripes?: boolean;
+};
+
+/**
+ * Helper function to get background color classes based on TableBackgroundStyle
+ */
+const getBackgroundColorClasses = (backgroundColor?: TableBackgroundStyle, isZebraStripe = false) => {
+    if (!backgroundColor) {
+        return 'bg-background-primary';
+    }
+
+    switch (backgroundColor) {
+        case 'secondary':
+            return 'bg-background-secondary';
+        case 'subdued':
+            return 'bg-background-subdued';
+        case 'disabled':
+            return 'bg-background-disabled';
+        case 'transparent':
+            return 'bg-transparent';
+        case 'primary':
+            if (isZebraStripe) {
+                return 'bg-background-subdued';
+            }
+            return 'bg-background-primary';
+        default:
+            return 'bg-background-primary';
+    }
+};
+
+export const Table = <T extends StaticData>({
+    actionable = false,
+    backgroundColor,
+    hideDividers = false,
+    isAdvancedPagination,
+    onSelectedRowsChange,
+    pageSizeOptions = [25, 50, 100],
+    showColumnDividers = false,
+    stickyFirstColumn = false,
+    stickyHeader = false,
+    ...props
+}: Props<T>) => {
+    const hasNoData = Boolean(props.loading) || !Boolean(props.data.length);
+
+    // Memoize the context value to prevent unnecessary re-renders
+    const contextValue = useMemo(
+        () => ({
+            actionable,
+            backgroundColor,
+            hideDividers,
+            onSelectedRowsChange,
+            pageSizeOptions,
+            showColumnDividers,
+            stickyFirstColumn: stickyFirstColumn && !hasNoData,
+        }),
+        [
+            actionable,
+            backgroundColor,
+            hideDividers,
+            onSelectedRowsChange,
+            pageSizeOptions,
+            showColumnDividers,
+            stickyFirstColumn,
+            hasNoData,
+        ]
+    );
+
+    // We need a jotai provider to isolate tables from one another.
+    return (
+        <Provider>
+            <tableStaticsContext.Provider value={contextValue}>
+                <InnerTable
+                    backgroundColor={backgroundColor}
+                    data-hui-id="Table"
+                    hasNoData={hasNoData}
+                    hideDividers={hideDividers}
+                    isAdvancedPagination={isAdvancedPagination}
+                    stickyFirstColumn={stickyFirstColumn}
+                    stickyHeader={stickyHeader}
+                    {...props}
+                />
+            </tableStaticsContext.Provider>
+        </Provider>
+    );
+};
+
+// react dev tools display name
+Table.displayName = 'Table';
+
+const InnerTable = <T extends StaticData>({
+    actionableCheckbox,
+    backgroundColor,
+    className,
+    columns,
+    currentSort,
+    data,
+    defaultSortDirection = 'descending',
+    emptyStateHeaderText = 'Empty state heading message...',
+    emptyStateSupportingText = 'Supporting message to provide further guidance on how to remedy empty state.',
+    fillHorizontal = false,
+    hasNoData,
+    hideBorder = false,
+    hideDividers = false,
+    isAdvancedPagination,
+    loading = false,
+    onSortChange,
+    pagination,
+    rowDensity = 'md',
+    selectedRows,
+    sortable = false,
+    stickyFirstColumn = false,
+    stickyHeader = false,
+    zebraStripes = false,
+}: Props<T> & {
+    hasNoData: boolean;
+}) => {
+    const [showRightScrollHint, setShowRightScrollHint] = useState(false);
+    const [showLeftScrollHint, setShowLeftScrollHint] = useState(false);
+    const [showTopScrollHint, setShowTopScrollHint] = useState(false);
+    const setShowLeftShadow = useSetAtom(showLeftStickyShadowAtom);
+
+    const handleScroll = useCallback(
+        (ref: HTMLDivElement) => {
+            setShowLeftShadow(stickyFirstColumn && ref.scrollLeft > 20);
+            setShowLeftScrollHint(!stickyFirstColumn && ref.scrollLeft > 50);
+            setShowRightScrollHint(ref.scrollLeft + ref.clientWidth < ref.scrollWidth - 50);
+            setShowTopScrollHint(ref.scrollTop !== 0);
+        },
+        [setShowLeftShadow, stickyFirstColumn]
+    );
+
+    let rowHeight = 0;
+    switch (rowDensity) {
+        case 'sm':
+            rowHeight = 28;
+            break;
+        case 'md':
+            rowHeight = 36;
+            break;
+        case 'lg':
+            rowHeight = 48;
+            break;
+        default:
+            rowHeight = 36;
+            break;
+    }
+
+    // Container classes
+    const containerClasses = cn(
+        'relative max-w-full',
+        {
+            'w-full': fillHorizontal,
+            'w-min': !fillHorizontal,
+        },
+        className,
+        'table-container'
+    );
+
+    // RelativeContainer classes
+    const relativeContainerClasses = cn(
+        'relative',
+        {
+            'border border-border-secondary': !hideBorder,
+            'border-b-0': !hideDividers && !hasNoData && !hideBorder,
+            'h-auto': !stickyHeader,
+            'h-full': stickyHeader,
+            'w-full': fillHorizontal,
+        },
+        getBackgroundColorClasses(backgroundColor)
+    );
+
+    // TableScroll classes
+    const tableScrollClasses = cn(
+        'w-full',
+        {
+            'h-auto': !stickyHeader,
+            'h-full': stickyHeader,
+            'min-h-[220px]': loading || data.length === 0,
+            'overflow-x-auto': !hasNoData,
+            'overflow-x-hidden': hasNoData,
+            'overflow-y-auto': stickyHeader,
+            'overflow-y-visible': !stickyHeader,
+        },
+        getBackgroundColorClasses(backgroundColor)
+    );
+
+    // Table classes
+    const tableClasses = cn(
+        'border-collapse',
+        {
+            'w-full': fillHorizontal,
+        },
+        getBackgroundColorClasses(backgroundColor),
+        // Row height styles using CSS custom properties for dynamic values
+        '[&_td]:h-[var(--row-height)] [&_th]:h-[var(--row-height)]',
+        // Background color for th and td elements
+        {
+            '[&_th]:bg-background-disabled': backgroundColor === 'disabled',
+            '[&_th]:bg-background-primary': backgroundColor === 'primary' || !backgroundColor,
+            '[&_th]:bg-background-secondary': backgroundColor === 'secondary',
+            '[&_th]:bg-background-subdued': backgroundColor === 'subdued',
+            '[&_th]:bg-transparent': backgroundColor === 'transparent',
+        },
+        // Scroll hint shadows using pseudo-elements
+        '[&::before]:pointer-events-none [&::before]:absolute [&::before]:z-[1] [&::before]:content-[""]',
+        '[&::before]:bottom-0 [&::before]:left-0 [&::before]:top-0 [&::before]:w-[48px]',
+        '[&::before]:opacity-0 [&::before]:transition-opacity [&::before]:duration-200',
+        '[&::before]:shadow-[8px_0px_8px_0px_rgba(0,0,0,0.1)_inset]',
+        {
+            '[&::before]:opacity-100': showLeftScrollHint && !hasNoData,
+        },
+        '[&::after]:pointer-events-none [&::after]:absolute [&::after]:z-[1] [&::after]:content-[""]',
+        '[&::after]:bottom-0 [&::after]:right-0 [&::after]:top-0 [&::after]:w-[48px]',
+        '[&::after]:opacity-0 [&::after]:transition-opacity [&::after]:duration-200',
+        '[&::after]:shadow-[-8px_0px_8px_0px_rgba(0,0,0,0.1)_inset]',
+        {
+            '[&::after]:opacity-100': showRightScrollHint && !hasNoData,
+        }
+    );
+
+    // Empty state container classes
+    const emptyStateContainerClasses = cn(
+        'absolute flex w-full flex-col items-center justify-center py-2xl text-center'
+    );
+
+    return (
+        <div
+            className={containerClasses}
+            style={{ '--row-height': `${rowHeight}px` } as React.CSSProperties}
+        >
+            <div className={relativeContainerClasses}>
+                <div
+                    className={tableScrollClasses}
+                    ref={(ref: HTMLDivElement | null) => {
+                        if (!ref) {
+                            return;
+                        }
+
+                        // Add a scroll event listener to the table scroll container
+                        // to determine if the right scroll hint should be shown
+                        ref.addEventListener('scroll', () => {
+                            handleScroll(ref);
+                        });
+
+                        handleScroll(ref);
+                    }}
+                >
+                    <table className={tableClasses}>
+                        <TableHeader
+                            actionableCheckbox={actionableCheckbox}
+                            backgroundColor={backgroundColor}
+                            columns={columns}
+                            currentSort={currentSort}
+                            data={data}
+                            defaultSortDirection={defaultSortDirection}
+                            onSortChange={onSortChange}
+                            showTopScrollHint={showTopScrollHint}
+                            sortable={sortable}
+                            stickyHeader={stickyHeader}
+                        />
+
+                        {!loading && Boolean(data.length) && (
+                            <TableRows
+                                backgroundColor={backgroundColor}
+                                columns={columns}
+                                data={data}
+                                selectedRows={selectedRows}
+                                zebraStripes={zebraStripes}
+                            />
+                        )}
+                    </table>
+                    {!hasNoData && <TableShadow />}
+
+                    {!loading && !Boolean(data.length) && (
+                        <div className={emptyStateContainerClasses}>
+                            <H3>{emptyStateHeaderText}</H3>
+                            <BodySecondary>{emptyStateSupportingText}</BodySecondary>
+                        </div>
+                    )}
+
+                    {loading && (
+                        <div className={emptyStateContainerClasses}>
+                            <Loading size={32} />
+                        </div>
+                    )}
+                </div>
+            </div>
+            {pagination && !hasNoData && (
+                <PaginationProvider
+                    {...pagination}
+                    key={pagination.key}
+                    path=""
+                >
+                    {isAdvancedPagination ? <AdvancedPagination className="px-0 py-sm" /> : <TableControls />}
+                </PaginationProvider>
+            )}
+        </div>
+    );
+};

package/src/Table/components/TableHeader/TableHeader.tsx

@@ -0,0 +1,166 @@
+import { cn } from '@evolve.ui/theme-system';
+import { useSetAtom } from 'jotai';
+import { ReactNode, useContext } from 'react';
+
+import { ArrowUp } from '../../../Icons';
+import { tableStaticsContext } from '../../sharedState';
+import { ColumnType, SortType, StaticData, TableBackgroundStyle } from '../../types';
+import { leftStickyShadowWidthAtom, observeFirstColumnWidth } from '../TableShadow/TableShadow';
+
+interface Props<T extends StaticData> {
+    actionableCheckbox: ReactNode;
+    backgroundColor?: TableBackgroundStyle;
+    columns: ColumnType<T>[];
+    currentSort?: [string, SortType];
+    data: T[];
+    defaultSortDirection: SortType;
+    onSortChange?: (columnKey: string, newSort: SortType) => void;
+    showTopScrollHint: boolean;
+    sortable: boolean;
+    stickyHeader: boolean;
+}
+
+export function TableHeader<T extends StaticData>({
+    actionableCheckbox,
+    backgroundColor,
+    columns,
+    currentSort,
+    defaultSortDirection,
+    onSortChange,
+    showTopScrollHint,
+    sortable,
+    stickyHeader,
+}: Props<T>) {
+    const { actionable, showColumnDividers, stickyFirstColumn } = useContext(tableStaticsContext);
+    const setLeftShadowWidth = useSetAtom(leftStickyShadowWidthAtom);
+
+    const tableBackgroundColor: TableBackgroundStyle =
+        backgroundColor === 'transparent' && stickyHeader ? 'primary' : 'transparent';
+
+    return (
+        <thead>
+            <tr
+                className={cn('relative border-b border-border-primary', {
+                    // BACKGROUND COLOR
+                    'bg-background-primary': tableBackgroundColor === 'primary',
+                    'bg-transparent': tableBackgroundColor === 'transparent',
+                    'shadow-01': stickyHeader && showTopScrollHint,
+                    // STICKY HEADER
+                    'sticky top-0 z-[5]': stickyHeader,
+                })}
+                style={{
+                    transition: stickyHeader ? '0.25s' : undefined,
+                }}
+            >
+                {actionable && (
+                    <th
+                        className={cn(
+                            'hui-text-label-strong bg-background-primary p-0 transition-colors duration-200',
+                            {
+                                'bg-background-primary': tableBackgroundColor === 'primary',
+                                'bg-transparent': tableBackgroundColor === 'transparent',
+                                // COLUMN DIVIDER
+                                'border-r border-border-secondary last:border-r-0': showColumnDividers,
+                            }
+                        )}
+                        key="actionable"
+                        scope="col"
+                        style={
+                            stickyFirstColumn
+                                ? {
+                                      left: 0,
+                                      paddingLeft: '14px',
+                                      position: 'sticky',
+                                      zIndex: 1,
+                                  }
+                                : {}
+                        }
+                    >
+                        {actionableCheckbox}
+                    </th>
+                )}
+                {columns.map((column, i) => {
+                    const newDirection =
+                        currentSort && currentSort[0] === column.key
+                            ? currentSort[1] === 'ascending'
+                                ? 'descending'
+                                : 'ascending'
+                            : defaultSortDirection;
+
+                    let ariaSort: undefined | 'none' | 'ascending' | 'descending' = undefined;
+
+                    if (currentSort && currentSort[0] === column.key) {
+                        ariaSort = currentSort[1];
+                    } else if (column.sortable) {
+                        ariaSort = 'none';
+                    }
+
+                    const isFirstColumn = i === 0;
+                    const isStickyFirstColumn = stickyFirstColumn && isFirstColumn;
+
+                    return (
+                        <th
+                            aria-sort={ariaSort}
+                            className={cn('hui-text-label-strong relative p-0 transition-colors duration-200', {
+                                'active:bg-background-pressed': sortable && column.sortable,
+                                // BACKGROUND COLOR
+                                'bg-background-primary': tableBackgroundColor === 'primary',
+                                'bg-transparent': tableBackgroundColor === 'transparent',
+                                // COLUMN DIVIDER
+                                'border-r border-border-secondary last:border-r-0': showColumnDividers,
+                                // SORTABLE STATES
+                                'group cursor-pointer': sortable && column.sortable,
+                                'hover:bg-background-hover': sortable && column.sortable,
+                                // STICKY FIRST COLUMN
+                                'sticky z-[1] shadow-02': isStickyFirstColumn,
+                            })}
+                            // Using the index as the key is fine here because the columns won't change.
+                            key={i}
+                            onClick={
+                                sortable && column.sortable && onSortChange
+                                    ? () => onSortChange(column.key as string, newDirection)
+                                    : undefined
+                            }
+                            ref={i === 0 ? observeFirstColumnWidth(setLeftShadowWidth) : undefined}
+                            scope="col"
+                            style={
+                                isStickyFirstColumn
+                                    ? {
+                                          left: actionable ? '48px' : '0',
+                                          transform: 'translateX(-1px)',
+                                      }
+                                    : {}
+                            }
+                        >
+                            <span
+                                className={cn('flex items-center gap-xs whitespace-nowrap px-sm', {
+                                    'justify-end': column.align === 'right',
+                                    'justify-start': column.align !== 'right',
+                                })}
+                            >
+                                {column.header ?? null}
+                                {sortable && column.sortable && (
+                                    <ArrowUp
+                                        className={cn('transition-all duration-200', {
+                                            'group-hover:rotate-0': ariaSort === 'descending',
+                                            'group-hover:rotate-180': ariaSort === 'ascending',
+                                            // HOVER STATE - Show on hover for unsorted columns
+                                            'group-hover:visible group-hover:opacity-100': ariaSort === 'none',
+                                            // DEFAULT STATE - Hidden for unsorted columns
+                                            'invisible opacity-0': ariaSort === 'none',
+                                            // ASCENDING STATE - Always visible, rotate on hover
+                                            'visible opacity-100': ariaSort === 'ascending',
+                                            // DESCENDING STATE - Always visible and rotated, rotate back on hover
+                                            'visible rotate-180 opacity-100': ariaSort === 'descending',
+                                        })}
+                                        size="sm"
+                                    />
+                                )}
+                            </span>
+                        </th>
+                    );
+                })}
+            </tr>
+        </thead>
+    );
+}

package/src/Table/components/TablePagination/TablePagination.tsx

@@ -0,0 +1,18 @@
+import { ItemCountDisplay } from './components/ItemCountDisplay/ItemCountDisplay';
+import { ItemCountSelect } from './components/ItemCountSelect/ItemCountSelect';
+import { Pagination } from './components/TablePaginator/TablePaginator';
+
+export const TableControls = () => {
+    return (
+        <div
+            className="flex items-center justify-between pt-4"
+            data-hui-id="TableControls"
+        >
+            <ItemCountSelect />
+            <ItemCountDisplay />
+            <Pagination />
+        </div>
+    );
+};
+
+TableControls.displayName = 'TableControls';

package/src/Table/components/TablePagination/components/ItemCountDisplay/ItemCountDisplay.tsx

@@ -0,0 +1,17 @@
+import { usePagination } from '../../../../../Pagination';
+import { BodyPrimary } from '../../../../../Typography/Text/Text';
+
+export const ItemCountDisplay = () => {
+    const { itemCount, page, pageSize } = usePagination();
+
+    if (pageSize === 'all') {
+        return <BodyPrimary>{itemCount} Items</BodyPrimary>;
+    }
+
+    return (
+        <BodyPrimary>{`${(page - 1) * pageSize + 1} - ${Math.min(
+            page * pageSize,
+            itemCount
+        )} of ${itemCount} Items`}</BodyPrimary>
+    );
+};