@aleph-alpha/ui-library 1.9.0 → 1.10.0

package/src/compositions/UiDataTable/__tests__/UiDataTablePagination.test.ts

@@ -0,0 +1,274 @@
+import { render, waitFor } from '@testing-library/vue';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, test, vi } from 'vitest';
+import UiDataTablePagination from '../UiDataTablePagination.vue';
+
+// Mock table object that mimics TanStack Table's Table interface
+function createMockTable(
+  options: {
+    pageIndex?: number;
+    pageSize?: number;
+    pageCount?: number;
+    canPreviousPage?: boolean;
+    canNextPage?: boolean;
+    selectedRows?: number;
+    totalRows?: number;
+  } = {},
+) {
+  const {
+    pageIndex = 0,
+    pageSize = 10,
+    pageCount = 5,
+    canPreviousPage = false,
+    canNextPage = true,
+    selectedRows = 0,
+    totalRows = 50,
+  } = options;
+
+  return {
+    getState: vi.fn(() => ({
+      pagination: { pageIndex, pageSize },
+    })),
+    getPageCount: vi.fn(() => pageCount),
+    getCanPreviousPage: vi.fn(() => canPreviousPage),
+    getCanNextPage: vi.fn(() => canNextPage),
+    setPageIndex: vi.fn(),
+    setPageSize: vi.fn(),
+    previousPage: vi.fn(),
+    nextPage: vi.fn(),
+    getFilteredSelectedRowModel: vi.fn(() => ({
+      rows: Array(selectedRows).fill({}),
+    })),
+    getFilteredRowModel: vi.fn(() => ({
+      rows: Array(totalRows).fill({}),
+    })),
+  };
+}
+
+describe('UiDataTablePagination', () => {
+  describe('Rendering', () => {
+    // Navigation buttons are asserted with accessible names in the Navigation Buttons suite
+
+    test('renders page info with current page and total pages', () => {
+      const table = createMockTable({ pageIndex: 2, pageCount: 10 });
+      const { getByText } = render(UiDataTablePagination, {
+        props: { table },
+      });
+
+      expect(getByText('Page 3 of 10')).toBeInTheDocument();
+    });
+
+    test('renders rows per page selector by default', () => {
+      const table = createMockTable({ pageSize: 20 });
+      const { getByText } = render(UiDataTablePagination, {
+        props: { table },
+      });
+
+      expect(getByText('Rows per page')).toBeInTheDocument();
+      expect(getByText('20')).toBeInTheDocument();
+    });
+
+    test('renders selection count by default', () => {
+      const table = createMockTable({ selectedRows: 5, totalRows: 100 });
+      const { getByText } = render(UiDataTablePagination, {
+        props: { table },
+      });
+
+      expect(getByText('5 of 100 row(s) selected.')).toBeInTheDocument();
+    });
+
+    test('hides page size selector when showPageSize is false', () => {
+      const table = createMockTable();
+      const { queryByText } = render(UiDataTablePagination, {
+        props: { table, showPageSize: false },
+      });
+
+      expect(queryByText('Rows per page')).not.toBeInTheDocument();
+    });
+
+    test('hides selection count when showSelection is false', () => {
+      const table = createMockTable({ selectedRows: 5, totalRows: 100 });
+      const { queryByText } = render(UiDataTablePagination, {
+        props: { table, showSelection: false },
+      });
+
+      expect(queryByText(/selected/i)).not.toBeInTheDocument();
+    });
+  });
+
+  describe('Page Size Selector', () => {
+    test('shows default page size options', async () => {
+      const user = userEvent.setup();
+      const table = createMockTable();
+      const { getByText, getByRole } = render(UiDataTablePagination, {
+        props: { table },
+      });
+
+      // Click the page size button (displays current page size)
+      await user.click(getByText('10'));
+
+      await waitFor(() => {
+        expect(getByRole('menuitem', { name: '10' })).toBeInTheDocument();
+        expect(getByRole('menuitem', { name: '20' })).toBeInTheDocument();
+        expect(getByRole('menuitem', { name: '30' })).toBeInTheDocument();
+        expect(getByRole('menuitem', { name: '50' })).toBeInTheDocument();
+      });
+    });
+
+    test('shows custom page size options when provided', async () => {
+      const user = userEvent.setup();
+      const table = createMockTable({ pageSize: 5 });
+      const { getByRole, getByText } = render(UiDataTablePagination, {
+        props: { table, pageSizeOptions: [5, 15, 25] },
+      });
+
+      await user.click(getByText('5'));
+
+      await waitFor(() => {
+        expect(getByRole('menuitem', { name: '5' })).toBeInTheDocument();
+        expect(getByRole('menuitem', { name: '15' })).toBeInTheDocument();
+        expect(getByRole('menuitem', { name: '25' })).toBeInTheDocument();
+      });
+    });
+
+    test('changes page size when option is selected', async () => {
+      const user = userEvent.setup();
+      const table = createMockTable();
+      const { getByRole, getByText } = render(UiDataTablePagination, {
+        props: { table },
+      });
+
+      await user.click(getByText('10'));
+      await waitFor(() => expect(getByRole('menu')).toBeInTheDocument());
+
+      await user.click(getByRole('menuitem', { name: '20' }));
+
+      expect(table.setPageSize).toHaveBeenCalledWith(20);
+    });
+  });
+
+  describe('Navigation Buttons', () => {
+    test('first and previous buttons are disabled on first page', () => {
+      const table = createMockTable({ canPreviousPage: false });
+      const { getByRole } = render(UiDataTablePagination, {
+        props: { table },
+      });
+
+      expect(getByRole('button', { name: /first page/i })).toBeDisabled();
+      expect(getByRole('button', { name: /previous page/i })).toBeDisabled();
+    });
+
+    test('next and last buttons are disabled on last page', () => {
+      const table = createMockTable({ canNextPage: false });
+      const { getByRole } = render(UiDataTablePagination, {
+        props: { table },
+      });
+
+      expect(getByRole('button', { name: /next page/i })).toBeDisabled();
+      expect(getByRole('button', { name: /last page/i })).toBeDisabled();
+    });
+
+    test('navigates to first page when first button is clicked', async () => {
+      const user = userEvent.setup();
+      const table = createMockTable({ canPreviousPage: true, pageIndex: 3 });
+      const { getByRole } = render(UiDataTablePagination, {
+        props: { table },
+      });
+
+      await user.click(getByRole('button', { name: /first page/i }));
+
+      expect(table.setPageIndex).toHaveBeenCalledWith(0);
+    });
+
+    test('navigates to previous page when previous button is clicked', async () => {
+      const user = userEvent.setup();
+      const table = createMockTable({ canPreviousPage: true });
+      const { getByRole } = render(UiDataTablePagination, {
+        props: { table },
+      });
+
+      await user.click(getByRole('button', { name: /previous page/i }));
+
+      expect(table.previousPage).toHaveBeenCalled();
+    });
+
+    test('navigates to next page when next button is clicked', async () => {
+      const user = userEvent.setup();
+      const table = createMockTable({ canNextPage: true });
+      const { getByRole } = render(UiDataTablePagination, {
+        props: { table },
+      });
+
+      await user.click(getByRole('button', { name: /next page/i }));
+
+      expect(table.nextPage).toHaveBeenCalled();
+    });
+
+    test('navigates to last page when last button is clicked', async () => {
+      const user = userEvent.setup();
+      const table = createMockTable({ canNextPage: true, pageCount: 10 });
+      const { getByRole } = render(UiDataTablePagination, {
+        props: { table },
+      });
+
+      await user.click(getByRole('button', { name: /last page/i }));
+
+      expect(table.setPageIndex).toHaveBeenCalledWith(9);
+    });
+
+    test('all buttons are enabled when on middle page', () => {
+      const table = createMockTable({ canPreviousPage: true, canNextPage: true });
+      const { getByRole } = render(UiDataTablePagination, {
+        props: { table },
+      });
+
+      expect(getByRole('button', { name: /first page/i })).toBeEnabled();
+      expect(getByRole('button', { name: /previous page/i })).toBeEnabled();
+      expect(getByRole('button', { name: /next page/i })).toBeEnabled();
+      expect(getByRole('button', { name: /last page/i })).toBeEnabled();
+    });
+  });
+
+  describe('Selection Count', () => {
+    test('shows zero selected when no rows are selected', () => {
+      const table = createMockTable({ selectedRows: 0, totalRows: 50 });
+      const { getByText } = render(UiDataTablePagination, {
+        props: { table },
+      });
+
+      expect(getByText('0 of 50 row(s) selected.')).toBeInTheDocument();
+    });
+
+    test('shows correct count when some rows are selected', () => {
+      const table = createMockTable({ selectedRows: 12, totalRows: 100 });
+      const { getByText } = render(UiDataTablePagination, {
+        props: { table },
+      });
+
+      expect(getByText('12 of 100 row(s) selected.')).toBeInTheDocument();
+    });
+  });
+
+  describe('i18n Support', () => {
+    test('applies custom labels when provided', () => {
+      const table = createMockTable({ selectedRows: 3, totalRows: 20, pageIndex: 1, pageCount: 4 });
+      const { getByText, getByRole } = render(UiDataTablePagination, {
+        props: {
+          table,
+          labels: {
+            rowsPerPage: 'Zeilen pro Seite',
+            goToFirstPage: 'Zur ersten Seite',
+            pageOf: (page: number, total: number) => `Seite ${page} von ${total}`,
+            rowsSelected: (selected: number, total: number) =>
+              `${selected} von ${total} ausgewählt`,
+          },
+        },
+      });
+
+      expect(getByText('Zeilen pro Seite')).toBeInTheDocument();
+      expect(getByText('Seite 2 von 4')).toBeInTheDocument();
+      expect(getByText('3 von 20 ausgewählt')).toBeInTheDocument();
+      expect(getByRole('button', { name: 'Zur ersten Seite' })).toBeInTheDocument();
+    });
+  });
+});

package/src/compositions/UiDataTable/__tests__/UiDataTableToolbar.test.ts

@@ -0,0 +1,198 @@
+import { render } from '@testing-library/vue';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, test, vi } from 'vitest';
+import UiDataTableToolbar from '../UiDataTableToolbar.vue';
+
+// Mock table object that mimics TanStack Table's Table interface
+function createMockTable(options: { globalFilter?: string; columnFilter?: string } = {}) {
+  const { globalFilter = '', columnFilter = '' } = options;
+  const setFilterValue = vi.fn();
+
+  return {
+    getState: vi.fn(() => ({
+      globalFilter,
+    })),
+    setGlobalFilter: vi.fn(),
+    getColumn: vi.fn(() => ({
+      getFilterValue: vi.fn(() => columnFilter),
+      setFilterValue,
+    })),
+    _setFilterValue: setFilterValue,
+  };
+}
+
+describe('UiDataTableToolbar', () => {
+  describe('Rendering', () => {
+    test('renders filter input when filtering is enabled', () => {
+      const table = createMockTable();
+
+      // Test with filterColumn
+      const { getByRole: getByColumn, unmount: unmountColumn } = render(UiDataTableToolbar, {
+        props: { table, filterColumn: 'name' },
+      });
+      expect(getByColumn('textbox')).toBeInTheDocument();
+      unmountColumn();
+
+      // Test with globalFilter
+      const { getByRole: getByGlobal } = render(UiDataTableToolbar, {
+        props: { table, globalFilter: true },
+      });
+      expect(getByGlobal('textbox')).toBeInTheDocument();
+    });
+
+    test('does not render filter input when neither filterColumn nor globalFilter is set', () => {
+      const table = createMockTable();
+      const { queryByRole } = render(UiDataTableToolbar, {
+        props: { table },
+      });
+
+      expect(queryByRole('textbox')).not.toBeInTheDocument();
+    });
+
+    test('applies custom placeholder to input', () => {
+      const table = createMockTable();
+      const { getByPlaceholderText } = render(UiDataTableToolbar, {
+        props: { table, globalFilter: true, filterPlaceholder: 'Type to search...' },
+      });
+
+      expect(getByPlaceholderText('Type to search...')).toBeInTheDocument();
+    });
+
+    test('uses default placeholder when not provided', () => {
+      const table = createMockTable();
+      const { getByPlaceholderText } = render(UiDataTableToolbar, {
+        props: { table, globalFilter: true },
+      });
+
+      expect(getByPlaceholderText('Search...')).toBeInTheDocument();
+    });
+  });
+
+  describe('Column Filtering', () => {
+    test('displays current column filter value in input', () => {
+      const table = createMockTable({ columnFilter: 'John' });
+      const { getByRole } = render(UiDataTableToolbar, {
+        props: { table, filterColumn: 'name' },
+      });
+
+      expect(getByRole('textbox')).toHaveValue('John');
+    });
+
+    test('updates column filter when input value changes', async () => {
+      const user = userEvent.setup();
+      const table = createMockTable();
+      const { getByRole } = render(UiDataTableToolbar, {
+        props: { table, filterColumn: 'name' },
+      });
+
+      await user.type(getByRole('textbox'), 'test');
+
+      expect(table._setFilterValue).toHaveBeenCalled();
+    });
+
+    test('clears column filter when input is emptied', async () => {
+      const user = userEvent.setup();
+      const table = createMockTable({ columnFilter: 'John' });
+      const { getByRole } = render(UiDataTableToolbar, {
+        props: { table, filterColumn: 'name' },
+      });
+
+      await user.clear(getByRole('textbox'));
+
+      expect(table._setFilterValue).toHaveBeenCalledWith('');
+    });
+  });
+
+  describe('Global Filtering', () => {
+    test('displays current global filter value in input', () => {
+      const table = createMockTable({ globalFilter: 'search term' });
+      const { getByRole } = render(UiDataTableToolbar, {
+        props: { table, globalFilter: true },
+      });
+
+      expect(getByRole('textbox')).toHaveValue('search term');
+    });
+
+    test('updates global filter when input value changes', async () => {
+      const user = userEvent.setup();
+      const table = createMockTable();
+      const { getByRole } = render(UiDataTableToolbar, {
+        props: { table, globalFilter: true },
+      });
+
+      await user.type(getByRole('textbox'), 'query');
+
+      expect(table.setGlobalFilter).toHaveBeenCalled();
+    });
+
+    test('clears global filter when input is emptied', async () => {
+      const user = userEvent.setup();
+      const table = createMockTable({ globalFilter: 'existing' });
+      const { getByRole } = render(UiDataTableToolbar, {
+        props: { table, globalFilter: true },
+      });
+
+      await user.clear(getByRole('textbox'));
+
+      expect(table.setGlobalFilter).toHaveBeenCalledWith('');
+    });
+
+    test('global filter takes precedence over column filter', () => {
+      const table = createMockTable({ globalFilter: 'global', columnFilter: 'column' });
+      const { getByRole } = render(UiDataTableToolbar, {
+        props: { table, globalFilter: true, filterColumn: 'name' },
+      });
+
+      // Global filter value should be displayed, not column filter
+      expect(getByRole('textbox')).toHaveValue('global');
+    });
+  });
+
+  describe('Accessibility', () => {
+    test('input has aria-label for global search', () => {
+      const table = createMockTable();
+      const { getByRole } = render(UiDataTableToolbar, {
+        props: { table, globalFilter: true },
+      });
+
+      expect(getByRole('textbox')).toHaveAttribute('aria-label', 'Search all columns');
+    });
+
+    test('input has aria-label for column filter including column name', () => {
+      const table = createMockTable();
+      const { getByRole } = render(UiDataTableToolbar, {
+        props: { table, filterColumn: 'email' },
+      });
+
+      expect(getByRole('textbox')).toHaveAttribute('aria-label', 'Filter by email');
+    });
+  });
+
+  describe('i18n Support', () => {
+    test('uses custom searchAllColumns label for global filter', () => {
+      const table = createMockTable();
+      const { getByRole } = render(UiDataTableToolbar, {
+        props: {
+          table,
+          globalFilter: true,
+          labels: { searchAllColumns: 'Alle Spalten durchsuchen' },
+        },
+      });
+
+      expect(getByRole('textbox')).toHaveAttribute('aria-label', 'Alle Spalten durchsuchen');
+    });
+
+    test('uses custom filterByColumn function for column filter', () => {
+      const table = createMockTable();
+      const { getByRole } = render(UiDataTableToolbar, {
+        props: {
+          table,
+          filterColumn: 'name',
+          labels: { filterByColumn: (col: string) => `Nach ${col} filtern` },
+        },
+      });
+
+      expect(getByRole('textbox')).toHaveAttribute('aria-label', 'Nach name filtern');
+    });
+  });
+});

package/src/compositions/UiDataTable/constants.ts

@@ -0,0 +1,77 @@
+/**
+ * Default labels for UiDataTable components.
+ * Override these by passing custom labels to component props.
+ */
+
+/** TanStack Table's default column size - columns without explicit size use this value */
+export const DEFAULT_COLUMN_SIZE = 150;
+
+export const DATA_TABLE_LABELS = {
+  /** UiDataTable */
+  emptyText: 'No results.',
+
+  /** UiDataTableColumnHeader */
+  sortAscending: 'Asc',
+  sortDescending: 'Desc',
+  sortedAscending: 'sorted ascending',
+  sortedDescending: 'sorted descending',
+  clickToSort: 'click to sort',
+
+  /** UiDataTablePagination */
+  rowsPerPage: 'Rows per page',
+  goToFirstPage: 'Go to first page',
+  goToPreviousPage: 'Go to previous page',
+  goToNextPage: 'Go to next page',
+  goToLastPage: 'Go to last page',
+  pageOf: (page: number, total: number) => `Page ${page} of ${total}`,
+  rowsSelected: (selected: number, total: number) => `${selected} of ${total} row(s) selected.`,
+
+  /** UiDataTableToolbar */
+  filterPlaceholder: 'Search...',
+  searchAllColumns: 'Search all columns',
+  filterByColumn: (column: string) => `Filter by ${column}`,
+} as const;
+
+export type DataTableLabels = typeof DATA_TABLE_LABELS;
+
+/** Labels for UiDataTableColumnHeader */
+export interface ColumnHeaderLabels {
+  /** Label for ascending sort menu item */
+  sortAscending?: string;
+  /** Label for descending sort menu item */
+  sortDescending?: string;
+  /** Aria label suffix when sorted ascending */
+  sortedAscending?: string;
+  /** Aria label suffix when sorted descending */
+  sortedDescending?: string;
+  /** Aria label suffix when not sorted */
+  clickToSort?: string;
+}
+
+/** Labels for UiDataTablePagination */
+export interface PaginationLabels {
+  /** Label for rows per page selector */
+  rowsPerPage?: string;
+  /** Aria label for first page button */
+  goToFirstPage?: string;
+  /** Aria label for previous page button */
+  goToPreviousPage?: string;
+  /** Aria label for next page button */
+  goToNextPage?: string;
+  /** Aria label for last page button */
+  goToLastPage?: string;
+  /** Function to generate page info text */
+  pageOf?: (page: number, total: number) => string;
+  /** Function to generate selection count text */
+  rowsSelected?: (selected: number, total: number) => string;
+}
+
+/** Labels for UiDataTableToolbar */
+export interface ToolbarLabels {
+  /** Placeholder text for filter input */
+  filterPlaceholder?: string;
+  /** Aria label for global search input */
+  searchAllColumns?: string;
+  /** Function to generate aria label for column filter */
+  filterByColumn?: (column: string) => string;
+}

package/src/compositions/UiDataTable/index.ts

@@ -0,0 +1,6 @@
+export { default as UiDataTable } from './UiDataTable.vue';
+export { default as UiDataTableColumnHeader } from './UiDataTableColumnHeader.vue';
+export { default as UiDataTablePagination } from './UiDataTablePagination.vue';
+export { default as UiDataTableToolbar } from './UiDataTableToolbar.vue';
+export * from './types';
+export * from './constants';

package/src/compositions/UiDataTable/types.ts

@@ -0,0 +1,39 @@
+import type { ColumnDef, Row } from '@tanstack/vue-table';
+
+/**
+ * A feature-rich data table with sorting, filtering, and pagination.
+ * Use for displaying and managing large datasets with interactive features.
+ *
+ * @category Layout
+ * @useCases data grid, admin table, user list, product catalog, reports
+ * @keywords datatable, grid, sorting, filtering, pagination, data, list
+ * @related UiTable
+ */
+export interface UiDataTableProps<TData, TValue> {
+  /**
+   * The column definitions for the table.
+   */
+  columns: ColumnDef<TData, TValue>[];
+  /**
+   * The data to display in the table.
+   */
+  data: TData[];
+  /**
+   * Text to display when there are no results.
+   * @default "No results."
+   */
+  emptyText?: string;
+  /**
+   * Function to derive a unique ID for each row. Important for proper row selection
+   * and state management when data changes. Defaults to using the row index.
+   * @example (row) => row.id
+   */
+  getRowId?: (originalRow: TData, index: number, parent?: Row<TData>) => string;
+  /**
+   * Minimum height for the table container. Useful for preventing layout shifts
+   * during pagination. The last row will have a visible bottom border even when
+   * the container is taller than the content.
+   * @example "400px"
+   */
+  tableMinHeight?: string;
+}