@indico-data/design-system 2.49.0 → 2.51.0

package/lib/stylesAndAnimations/utilityClasses/UtilityClassesData.d.ts

@@ -0,0 +1,7 @@
+export type UtilityClassData = {
+    className: string;
+    css: string;
+    category: string;
+    resolvedCss?: string;
+};
+export declare const utilityClassesData: UtilityClassData[];

package/lib/stylesAndAnimations/utilityClasses/UtilityClassesTable.d.ts

@@ -0,0 +1 @@
+export declare const UtilityClassesTable: () => import("react/jsx-runtime").JSX.Element;

package/lib/stylesAndAnimations/utilityClasses/UtilityClassesTable.stories.d.ts

@@ -0,0 +1,6 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { UtilityClassesTable } from './UtilityClassesTable';
+declare const meta: Meta<typeof UtilityClassesTable>;
+export default meta;
+type Story = StoryObj<typeof UtilityClassesTable>;
+export declare const Default: Story;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indico-data/design-system",
-  "version": "2.49.0",
+  "version": "2.51.0",
   "description": "",
   "author": "",
   "main": "lib/index.js",
@@ -39,6 +39,7 @@
     "@react-types/button": "^3.9.3",
     "@react-types/checkbox": "^3.8.1",
     "@react-types/radio": "^3.8.0",
+    "@tanstack/react-table": "^8.21.2",
     "@testing-library/react": "^16.0.0",
     "classnames": "^2.5.1",
     "date-fns": "^3.6.0",

package/src/components/tanstackTable/TankstackTable.types.ts

@@ -0,0 +1,39 @@
+import { Row, ColumnDef } from '@tanstack/react-table';
+
+export type WithPaginationProps = {
+  rowsPerPage: number;
+  rowCount: number;
+  onChangePage: (page: number, perPage: number) => void;
+  currentPage: number;
+  totalEntriesText?: string;
+  showPagination: true;
+};
+
+export type WithoutPaginationProps = {
+  rowsPerPage?: number;
+  rowCount?: number;
+  onChangePage?: (page: number, perPage: number) => void;
+  currentPage?: number;
+  totalEntriesText?: string;
+  showPagination?: false;
+};
+
+export type PaginationProps = WithPaginationProps | WithoutPaginationProps;
+
+export type Props<T extends object> = {
+  data: T[];
+  columns: ColumnDef<T & { id: string }>[];
+  className?: string;
+  actionBarClassName?: string;
+  TableActions?: React.ComponentType<{ selectedItems: Row<any>[]; unselectRows: () => void }>;
+  error?: {
+    hasError: boolean;
+    errorMessage?: string;
+  };
+  enableRowSelection?: boolean | ((row: Row<T>) => boolean);
+  clearFilters?: () => void;
+  hasFilters?: boolean;
+  isLoading?: boolean;
+  defaultPinnedColumns?: string[];
+  onClickRow?: ((row: Row<T>) => void) | null;
+} & PaginationProps;

package/src/components/tanstackTable/TanstackTable.mdx

@@ -0,0 +1,122 @@
+import { Canvas, Meta, Controls } from '@storybook/blocks';
+import * as TableStories from './TanstackTable.stories';
+
+<Meta title="Layout/Tanstack Table" name="TanstackTable" />
+
+# Table
+
+This component facilitates the rapid creation of responsive and paginated tables. It was built using the React TanStack Table library as a foundation. For more details on additional configuration options and features that are not covered in this documentation, please refer to the official TanStack Table documentation at this [link](https://tanstack.com/table/latest/docs/introduction).
+
+<Canvas of={TableStories.Default} />
+
+<Controls of={TableStories.Default} />
+
+# Data Structure
+These are some examples of how we would set up data for our table.
+
+## Data
+You can define your data for your columns the following way.
+```tsx
+const data = [
+{
+    firstName: 'John',
+    lastName: 'Doe',
+    age: 28,
+    visits: 10,
+    progress: 75,
+    status: 'single',
+    id: '1',
+    country: 'USA',
+    city: 'New York',
+    civility: 'Mr.',
+  },
+  {
+    firstName: 'Jane',
+    lastName: 'Smith',
+    age: 32,
+    visits: 15,
+    progress: 50,
+    status: 'relationship',
+    id: '2',
+    country: 'USA',
+    city: 'Los Angeles',
+    civility: 'Ms.',
+  },
+];
+```
+
+## Headers/Columns
+You can define your structure for your headers and columns in the following way.
+```tsx
+const columns = [
+  {
+    id: 'select',
+    size: 48,
+    meta: {
+      styles: {
+        definedColumnSize: true,
+        header: {
+          hasNoPadding: true,
+        },
+        cell: {
+          hasNoPadding: true,
+        },
+      },
+    },
+    header: ({ table }) => (
+      <CheckboxContainer>
+        <Checkbox
+          name="select-all"
+          id="select-all"
+          label=""
+          isChecked={table.getIsAllPageRowsSelected()}
+          onChange={() => {
+            table
+              .getRowModel()
+              .rows.forEach((row) =>
+                row.toggleSelected(!table.getRowModel().rows[0].getIsSelected()),
+              );
+          }}
+          isDisabled={false}
+          aria-label="select-rows-header"
+        />
+      </CheckboxContainer>
+    ),
+    cell: ({ row }) => (
+      <CheckboxContainer>
+        <Checkbox
+          name="select"
+          id={row.id}
+          label=""
+          aria-label={`checkbox-${row.id}`}
+          isChecked={row.getIsSelected()}
+          isDisabled={!row.getCanSelect()}
+          onChange={row.getToggleSelectedHandler()}
+        />
+      </CheckboxContainer>
+    ),
+  },
+  {
+    id: 'firstName',
+    accessorKey: 'firstName',
+    header: ({ header }) => (
+      <PinHeaderColumns
+        content="First Name"
+        onPinClick={() => header.column.pin(header.column.getIsPinned() ? false : 'left')}
+        isPinned={header.column.getIsPinned() === 'left' ? true : false}
+      />
+    ),
+    cell: (info) => info.getValue(),
+    footer: (props) => props.column.id,
+  },
+  ...
+];
+
+```
+
+# Future Upgrades
+- Only pin checkboxes by defaultif the table is responsive (or has a scrollbar that requires pinning)
+- More examples of table setups with code previews.
+- Visual Testing.
+- Prebuilt filter components for the header that follow our universal design for tables.
+- Items per Page Dropdown

package/src/components/tanstackTable/TanstackTable.stories.tsx

@@ -0,0 +1,260 @@
+import { Meta, StoryObj } from '@storybook/react';
+
+import { TanstackTable } from './TanstakTable';
+import { people, Person } from './mock-data/mock-data';
+import { columns } from './mock-data/table-configuration';
+import { ColumnDef, Row } from '@tanstack/react-table';
+import { Button } from '../button';
+
+const meta: Meta = {
+  title: 'Layout/Tanstack Table',
+  component: TanstackTable,
+  args: {
+    data: people as (Person & { id: string })[],
+    columns: columns as ColumnDef<Person & { id: string }>[],
+    rowCount: people.length,
+    currentPage: 0,
+    rowsPerPage: 1000,
+    defaultPinnedColumns: ['select'],
+    clearFilters: () => {},
+    hasFilters: false,
+    isLoading: false,
+    enableRowSelection: true,
+    showPagination: false,
+    onClickRow: null,
+  },
+  argTypes: {
+    data: {
+      description:
+        'Array of data items. These are the items that will be displayed in the table cell.',
+      control: false,
+      table: {
+        category: 'Props',
+        type: { summary: 'T[{}]' },
+      },
+    },
+    columns: {
+      description:
+        'Column definitions including an `id` field. This is how you define your table structure.',
+      control: false,
+      table: {
+        category: 'Props',
+        type: { summary: 'ColumnDef<T & { id: string }>[]' },
+      },
+    },
+    className: {
+      description: 'Additional option for class names.',
+      control: false,
+      table: {
+        category: 'Props',
+        type: { summary: 'string' },
+      },
+    },
+    actionBarClassName: {
+      description: 'class name for styling the action bar.',
+      control: false,
+      table: {
+        category: 'Props',
+        type: { summary: 'string' },
+      },
+    },
+    TableActions: {
+      description: 'Component for table actions with selected items.',
+      control: false,
+      table: {
+        category: 'Props',
+        type: {
+          summary: 'React.ComponentType<{ selectedItems: Row<any>[]; unselectRows: () => void }>',
+        },
+      },
+    },
+    error: {
+      description: 'Error state of the table.',
+      control: false,
+      table: {
+        category: 'Props',
+        type: { summary: '{ hasError: boolean; errorMessage?: string }' },
+      },
+    },
+    enableRowSelection: {
+      description: 'Enables row selection or defines selection conditions.',
+      control: { type: 'boolean' },
+      table: {
+        category: 'Props',
+        type: { summary: 'boolean | ((row: Row<T>) => boolean)' },
+      },
+    },
+    clearFilters: {
+      description: 'Function to clear applied filters.',
+      action: 'clearFilters',
+      control: false,
+      table: {
+        category: 'Callbacks',
+        type: { summary: '() => void' },
+      },
+    },
+    hasFilters: {
+      description: 'Indicates if filters are applied.',
+      control: { type: 'boolean' },
+      table: {
+        category: 'Props',
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    isLoading: {
+      description: 'When this is true, the table is considered to be in a loading state.',
+      control: { type: 'boolean' },
+      table: {
+        category: 'Props',
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    defaultPinnedColumns: {
+      description: 'Columns that are pinned by default.',
+      control: false,
+      table: {
+        category: 'Props',
+        type: { summary: 'string[]' },
+      },
+    },
+    onClickRow: {
+      description: 'Callback when a row is clicked.',
+      action: 'onClickRow',
+      control: false,
+      table: {
+        category: 'Callbacks',
+        type: { summary: '(row: Row<T>) => void' },
+      },
+    },
+    showPagination: {
+      description: 'Toggles pagination display.',
+      control: { type: 'boolean' },
+      table: {
+        category: 'Props',
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'true' },
+      },
+    },
+    rowsPerPage: {
+      description: 'Number of rows to display per pagination page.',
+      control: { type: 'number' },
+      table: {
+        category: 'Props',
+        type: { summary: 'number' },
+        defaultValue: { summary: '1000' },
+      },
+    },
+    rowCount: {
+      description: 'Total number of rows in the table.',
+      control: { type: 'number' },
+      table: {
+        category: 'Props',
+        type: { summary: 'number' },
+        defaultValue: { summary: '1000' },
+      },
+    },
+    onChangePage: {
+      description: 'Callback when the page changes.',
+      action: 'onChangePage',
+      control: false,
+      table: {
+        category: 'Callbacks',
+        type: { summary: '(page: number, perPage: number) => void' },
+      },
+    },
+    currentPage: {
+      description: 'Current page number.',
+      control: { type: 'number' },
+      table: {
+        category: 'Props',
+        type: { summary: 'number' },
+        defaultValue: { summary: '1' },
+      },
+    },
+    totalEntriesText: {
+      description: 'Text to display for the total number of entries.',
+      control: false,
+      table: {
+        category: 'Props',
+        type: { summary: 'string' },
+      },
+    },
+  },
+  decorators: [
+    (Story) => (
+      <div style={{ width: '100%', height: '500px', overflow: 'hidden' }}>
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+
+type Story = StoryObj<typeof TanstackTable<Person>>;
+
+export const Default: Story = {};
+
+export const WithRowClick: Story = {
+  args: {
+    onClickRow: (row: Row<Person>) => {
+      console.log(row);
+    },
+  },
+};
+
+export const PinnedColumns: Story = {
+  args: {
+    defaultPinnedColumns: ['select', 'firstName', 'lastName'],
+    actionBarClassName: 'tanstack-table__action-bar-test',
+  },
+  render: (args) => (
+    <div style={{ width: '700px', height: '500px', overflow: 'hidden' }}>
+      <TanstackTable<Person> {...args} />
+    </div>
+  ),
+};
+
+export const WithTableActions: Story = {
+  args: {
+    TableActions: () => <Button ariaLabel="Actions">Actions</Button>,
+  },
+};
+
+export const NoResults: Story = {
+  args: {
+    data: [],
+  },
+};
+
+export const NoResultsWithFilters: Story = {
+  args: {
+    data: [],
+    hasFilters: true,
+  },
+};
+
+export const IsLoading: Story = {
+  args: {
+    isLoading: true,
+    data: [],
+  },
+};
+
+export const IsLoadingWithData: Story = {
+  args: {
+    isLoading: true,
+  },
+};
+
+export const WithPagination: Story = {
+  args: {
+    showPagination: true,
+    rowCount: people.length,
+    currentPage: 1,
+    rowsPerPage: 20,
+    onChangePage: () => {},
+  },
+};

package/src/components/tanstackTable/TanstakTable.tsx

@@ -0,0 +1,157 @@
+import { useEffect, useRef } from 'react';
+
+import { useReactTable, getCoreRowModel, ColumnDef } from '@tanstack/react-table';
+import classNames from 'classnames';
+
+import { ActionBar } from './components/ActionBar';
+import { NoResults } from './components/NoResults';
+import { isNil } from 'lodash';
+import { TablePagination } from './components/TablePagination';
+import { Props } from './TankstackTable.types';
+import { useTanstackTable } from './useTanstackTable';
+import { TableHeader } from './components/TableHeader';
+import { TableBody } from './components/TableBody';
+
+export function TanstackTable<T extends object>({
+  columns: defaultColumns,
+  data,
+  className,
+  currentPage,
+  rowCount,
+  rowsPerPage = 1000,
+  onChangePage,
+  totalEntriesText,
+  TableActions,
+  error,
+  enableRowSelection = true,
+  clearFilters,
+  hasFilters,
+  showPagination = true,
+  isLoading = false,
+  defaultPinnedColumns,
+  onClickRow = null,
+  actionBarClassName,
+}: Props<T & { id: string }>) {
+  const {
+    columns,
+    defaultData,
+    windowWidth,
+    rowSelection,
+    setRowSelection,
+    formattedColumns,
+    setFormattedColumns,
+    isClickedRow,
+    setIsClickedRow,
+  } = useTanstackTable({
+    defaultColumns,
+  });
+
+  const thRefs = useRef<Record<string, HTMLTableCellElement | null>>({});
+
+  // Sets formattedColumns with correct column widths
+  useEffect(() => {
+    const updatedColumns: ColumnDef<T & { id: string }>[] = [];
+
+    formattedColumns.forEach((column) => {
+      const columnWidth = thRefs.current[column.id as keyof typeof thRefs.current]!.offsetWidth;
+
+      updatedColumns.push({
+        ...column,
+        size: columnWidth,
+      });
+    });
+    setFormattedColumns(updatedColumns);
+  }, [data, columns, windowWidth]);
+
+  const table = useReactTable({
+    data: data ?? defaultData,
+    columns: formattedColumns,
+    state: {
+      rowSelection,
+    },
+    enableRowSelection,
+    onRowSelectionChange: setRowSelection,
+    getCoreRowModel: getCoreRowModel(),
+    manualPagination: true,
+    debugTable: true,
+    initialState: {
+      columnPinning: {
+        left: defaultPinnedColumns,
+      },
+    },
+  });
+
+  const totalRowsOnPage = table.getRowModel().rows.length;
+  const hasPaginationProps =
+    !isNil(currentPage) &&
+    !isNil(rowCount) &&
+    !isNil(totalRowsOnPage) &&
+    onChangePage !== undefined;
+
+  const hasSelectedRows = Object.keys(rowSelection).length > 0;
+
+  const hasErrorAndIsNotLoading = error?.hasError && !isLoading;
+  const hasNoResults = data.length === 0 && !isLoading;
+  const shouldRenderPagination = showPagination && hasPaginationProps;
+
+  const renderBody = () => {
+    if (hasErrorAndIsNotLoading || hasNoResults) {
+      return (
+        <tr className="tanstack-table__tbody__tr">
+          <td className="tanstack-table__centered-row" colSpan={columns.length}>
+            <NoResults
+              clearFilters={clearFilters}
+              hasFilters={hasFilters}
+              message={
+                hasErrorAndIsNotLoading
+                  ? error?.errorMessage ?? 'There was an error isLoading the data.'
+                  : 'No results found.'
+              }
+            />
+          </td>
+        </tr>
+      );
+    }
+
+    return (
+      <TableBody<T & { id: string }>
+        table={table}
+        onClickRow={onClickRow}
+        isLoading={isLoading}
+        columnsLength={columns.length}
+        isClickedRow={isClickedRow}
+        setIsClickedRow={setIsClickedRow}
+      />
+    );
+  };
+
+  return (
+    <div className="tanstack-table__outer-container">
+      <div className="tanstack-table__container">
+        <table
+          className={classNames('tanstack-table', className, {
+            'is-Loading': isLoading,
+          })}
+        >
+          <thead className="tanstack-table__thead">
+            <TableHeader table={table} ref={thRefs} />
+          </thead>
+          <tbody className="tanstack-table__tbody">{renderBody()}</tbody>
+        </table>
+
+        {hasSelectedRows && (
+          <ActionBar table={table} TableActions={TableActions} className={actionBarClassName} />
+        )}
+      </div>
+      {shouldRenderPagination ? (
+        <TablePagination
+          currentPage={currentPage}
+          rowCount={rowCount}
+          onChangePage={onChangePage}
+          rowsPerPage={rowsPerPage}
+          totalEntriesText={totalEntriesText ?? `${totalRowsOnPage} of ${rowCount} entries`}
+        />
+      ) : null}
+    </div>
+  );
+}

package/src/components/tanstackTable/__tests__/TanstackTable.test.tsx

@@ -0,0 +1,87 @@
+import { render, screen, fireEvent } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { TanstackTable } from '../TanstakTable';
+import { data, columns } from './__mocks__/test-mock-data';
+
+describe('Tanstack Table Component', () => {
+  test('renders the table with provided data', () => {
+    render(<TanstackTable columns={columns} data={data} />);
+    expect(screen.getByText('Name')).toBeInTheDocument();
+    expect(screen.getByText('Age')).toBeInTheDocument();
+    expect(screen.getByText('Alice')).toBeInTheDocument();
+    expect(screen.getByText('Bob')).toBeInTheDocument();
+  });
+
+  test('displays loading state when loading is true', () => {
+    render(<TanstackTable columns={columns} data={[]} isLoading={true} />);
+    expect(screen.getByTestId('loading-indicator')).toBeInTheDocument();
+  });
+
+  test('shows error message when error exists', () => {
+    render(
+      <TanstackTable
+        columns={columns}
+        data={[]}
+        error={{ hasError: true, errorMessage: 'Failed to load data' }}
+      />,
+    );
+    expect(screen.getByText('Failed to load data')).toBeInTheDocument();
+  });
+
+  test('handles click on checkbox to select row', () => {
+    render(<TanstackTable columns={columns} data={data} enableRowSelection={true} />);
+    const indexRow = 0;
+    const firstCheckbox = screen.getByTestId(`checkbox-${indexRow}`);
+    fireEvent.click(firstCheckbox);
+    const firstRow = screen.getByText(data[indexRow].name).closest('tr');
+    expect(firstRow).toHaveClass('is-selected');
+  });
+
+  test('handles click on a row with onClickRow property', () => {
+    const onClickRow = jest.fn();
+    render(
+      <TanstackTable
+        columns={columns}
+        data={data}
+        enableRowSelection={true}
+        onClickRow={onClickRow}
+      />,
+    );
+    const firstRow = screen.getByText(data[0].name);
+    fireEvent.click(firstRow);
+    expect(onClickRow).toHaveBeenCalled();
+  });
+
+  test('renders pagination when showPagination is true', () => {
+    render(
+      <TanstackTable
+        columns={columns}
+        data={data}
+        currentPage={1}
+        rowCount={10}
+        rowsPerPage={5}
+        onChangePage={jest.fn()}
+        showPagination={true}
+      />,
+    );
+    expect(screen.getByTestId('tanstack-table-pagination')).toBeInTheDocument();
+  });
+
+  test('renders No Result when data is empty', () => {
+    render(
+      <TanstackTable
+        columns={columns}
+        data={[]}
+        currentPage={1}
+        rowCount={10}
+        rowsPerPage={5}
+        onChangePage={jest.fn()}
+        showPagination={true}
+      />,
+    );
+    expect(screen.getByTestId('tanstack-table-no-results')).toBeInTheDocument();
+  });
+});
+
+// may require visual testing
+it.todo('Test pinned columns');