+
+
+ )
+ }
+};
+
+// ============================================================================
+// VISUAL CUSTOMIZATION
+// ============================================================================
+// Stories showcasing different visual styles and layout options
+
+/**
+ * - **Headerless Design**: Table without column headers for cleaner presentation.
+ * - **Context-Dependent**: Useful when column meanings are clear from surrounding UI.
+ * - **Simplified Layout**: Focuses attention entirely on the data content.
+ */
+export const WithoutHeader: Story = {
+ args: {
+ items: sampleData.slice(0, 5),
+ columns: basicColumns,
+ hideHeader: true
+ }
+};
+
+/**
+ * - **Alternating Colors**: Zebra-striped rows improve data readability and visual tracking.
+ * - **Enhanced Scanning**: Makes it easier to follow data across columns in long tables.
+ * - **Professional Appearance**: Provides a polished look for data-heavy interfaces.
+ */
+export const StripedRows: Story = {
+ args: {
+ items: sampleData,
+ columns: basicColumns,
+ isStriped: true
+ }
+};
+
+/**
+ * - **Dense Layout**: Reduced padding and spacing for maximum data density.
+ * - **Space Efficient**: Ideal for dashboards and limited screen real estate.
+ * - **Information Rich**: Allows more rows to be visible simultaneously.
+ */
+export const Compact: Story = {
+ args: {
+ items: sampleData,
+ columns: basicColumns,
+ isCompact: true
+ }
+};
+
+// ============================================================================
+// SELECTION MODES
+// ============================================================================
+// Stories demonstrating single, multiple, and constrained selection patterns
+
+/**
+ * - **Single Selection**: Allows selecting only one row at a time with radio button behavior.
+ * - **Exclusive Choice**: Automatically deselects previous selection when new row is chosen.
+ * - **Console Logging**: Selection events are logged to browser console for development.
+ */
+export const SingleRowSelection: Story = {
+ parameters: {
+ docs: {
+ source: {
+ language: 'tsx',
+ code: `
+import { useState } from 'react';
+import Table from './Table';
+
+const SingleSelectionTable = () => {
+ const [selectedKeys, setSelectedKeys] = useStateNo users found
+Get started by creating a new user.
+
+
+
+
+ 
+
+ ),
+ allowsSorting: true,
+ sortValue: (row: UserData) => row.name
+ },
+ {
+ key: 'department',
+ header: 'Department',
+ cell: (row: UserData) => (
+
+
+ {row.name}
+ {row.email}
+ {row.location}
+
+
+ ),
+ allowsSorting: true
+ },
+ {
+ key: 'compensation',
+ header: 'Compensation',
+ cell: (row: UserData) => (
+
+ {row.team}
+
+ {row.role}
+
+
+ ),
+ allowsSorting: true,
+ sortValue: (row: UserData) => row.salary || 0
+ },
+ {
+ key: 'tenure',
+ header: 'Tenure',
+ cell: (row: UserData) => {
+ if (!row.joinDate) {
+ return 'N/A';
+ }
+ const joinDate = new Date(row.joinDate);
+ const now = new Date();
+ const diffTime = Math.abs(now.getTime() - joinDate.getTime());
+ const diffDays = Math.ceil(diffTime / (1000 * 60 * 60 * 24));
+ const years = Math.floor(diffDays / 365);
+ const months = Math.floor((diffDays % 365) / 30);
+
+ return (
+
+ {row.salary ? `€${row.salary.toLocaleString()}` : 'N/A'}
+
+ Annual
+
+
+ );
+ },
+ allowsSorting: true,
+ sortValue: (row: UserData) => row.joinDate || ''
+ },
+ {
+ key: 'status',
+ header: 'Status',
+ cell: (row: UserData) =>
+ {years > 0 ? `${years}y ${months}m` : `${months}m`}
+
+ {joinDate.toLocaleDateString()}
+
+
+
+
+ )
+ }
+ ];
+
+ return (
+
+
+ {!hideHeader && (
+
+
+
+ ),
+ [
+ getWrapperClasses,
+ className,
+ getTableClasses,
+ hideHeader,
+ getHeaderClasses,
+ selectionMode,
+ showSelectionCheckboxes,
+ getHeaderCellClasses,
+ columns,
+ classNames.tbody,
+ pageSize,
+ getCellClasses
+ ]
+ );
+
+ const renderEmptyState = useCallback(
+ () => (
+
+ Loading table data...
+
+ | , -1)} + role='columnheader' + aria-label='Selection' + > + + | + )} + {columns.map((column, index) => ( ++ {column.header} + | + ))} +
|---|---|
| + + | + )} + {columns.map((column, colIndex) => ( ++ + | + ))} +
+
+ Loading data...
+
+
+
+ {!hideHeader && (
+
+
+
+ ),
+ [
+ getWrapperClasses,
+ className,
+ getTableClasses,
+ hideHeader,
+ getHeaderClasses,
+ selectionMode,
+ showSelectionCheckboxes,
+ getHeaderCellClasses,
+ columns,
+ tableState.sortDescriptor,
+ renderSortIcon,
+ classNames.tbody,
+ emptyContent
+ ]
+ );
+
+ if (tableState.isLoading) {
+ return renderLoadingState();
+ }
+
+ const actualDataSource = items?.length > 0 ? items : data || [];
+ const hasOriginalData = actualDataSource && actualDataSource.length > 0;
+ const hasActiveFilters = Object.values(tableState.filterValues).some((value) => value && value.trim() !== '');
+ const hasFilteredResults = tableState.filteredData && tableState.filteredData.length > 0;
+
+ if (!hasOriginalData) {
+ return renderEmptyState();
+ }
+
+ const tableContent = (
+ | , -1)} + role='columnheader' + aria-label='Selection' + > + {selectionMode === 'multiple' ? ( + + ) : ( + + )} + | + )} + {columns.map((column, index) => ( +
+
+ {column.header}
+ {(column.allowsSorting || column.sortable) && renderSortIcon(column)}
+ {column.filterable && (
+ <>
+
+
+ Enter text to filter the {column.header} column
+
+ tableState.setFilter(String(column.key), e.target.value)}
+ className='ml-2 p-1 border rounded-md text-sm bg-white dark:bg-gray-dark-800 border-gray-light-300 dark:border-gray-dark-600 text-text-light dark:text-text-dark placeholder-gray-light-400 dark:placeholder-gray-dark-400 focus:ring-primary focus:border-primary w-20'
+ aria-label={`Filter by ${column.header}`}
+ aria-describedby={`filter-help-${column.key}`}
+ onClick={(e) => e.stopPropagation()}
+ />
+
+ )}
+ |
+ ))}
+
|---|---|
| + {emptyContent || 'No data to display.'} + | +
+
+ );
+
+ return tableContent;
+}
+
+export default Table;
diff --git a/src/components/atoms/table/index.ts b/src/components/atoms/table/index.ts
new file mode 100644
index 00000000..323fab0a
--- /dev/null
+++ b/src/components/atoms/table/index.ts
@@ -0,0 +1,15 @@
+export { default as Table } from './Table';
+export type {
+ TableProps,
+ CompleteTableProps,
+ TableColumn as TableColumnType,
+ TableEvents,
+ SortDescriptor,
+ Selection,
+ SelectionMode,
+ SelectionBehavior
+} from './types';
+export { useTable } from './useTable';
+
+import Table from './Table';
+export default Table;
diff --git a/src/components/atoms/table/types.ts b/src/components/atoms/table/types.ts
new file mode 100644
index 00000000..1d198ed0
--- /dev/null
+++ b/src/components/atoms/table/types.ts
@@ -0,0 +1,317 @@
+import { type VariantProps, cva } from 'class-variance-authority';
+import type * as React from 'react';
+
+// ========================================
+// CVA VARIANTS
+// ========================================
+
+export const tableVariants = cva(['table-wrapper relative overflow-auto w-full'], {
+ variants: {
+ shadow: {
+ none: '',
+ sm: 'shadow-sm dark:shadow-gray-dark-900',
+ md: 'shadow-md dark:shadow-gray-dark-900',
+ lg: 'shadow-lg dark:shadow-gray-dark-900'
+ },
+ radius: {
+ none: 'rounded-none',
+ sm: 'rounded-sm',
+ md: 'rounded-md',
+ lg: 'rounded-lg'
+ }
+ },
+ defaultVariants: {
+ shadow: 'sm',
+ radius: 'md'
+ }
+});
+
+export const tableElementVariants = cva(
+ ['table w-full border-collapse bg-white dark:bg-gray-dark-800 transition-colors'],
+ {
+ variants: {
+ layout: {
+ auto: 'table-auto',
+ fixed: 'table-fixed'
+ },
+ fullWidth: {
+ true: 'w-full',
+ false: 'w-auto'
+ }
+ },
+ defaultVariants: {
+ layout: 'auto',
+ fullWidth: true
+ }
+ }
+);
+
+export const tableHeaderVariants = cva(
+ [
+ 'table-header bg-gray-light-100 dark:bg-gray-dark-700',
+ 'border-b-2 border-gray-light-300 dark:border-gray-dark-600',
+ 'transition-colors'
+ ],
+ {
+ variants: {
+ isSticky: {
+ true: 'sticky top-0 z-10',
+ false: 'relative'
+ }
+ },
+ defaultVariants: {
+ isSticky: false
+ }
+ }
+);
+
+export const tableHeaderCellVariants = cva(
+ [
+ 'table-header-cell font-secondary-bold text-text-light dark:text-text-dark',
+ 'border-b border-gray-light-300 dark:border-gray-dark-600',
+ 'transition-colors select-none'
+ ],
+ {
+ variants: {
+ size: {
+ sm: 'px-2 py-1 fs-small tablet:fs-small-tablet',
+ md: 'px-4 py-2 fs-base tablet:fs-base-tablet',
+ lg: 'px-6 py-3 fs-h6 tablet:fs-h6-tablet'
+ },
+ align: {
+ start: 'text-left',
+ center: 'text-center',
+ end: 'text-right'
+ },
+ allowsSorting: {
+ true: 'cursor-pointer hover:bg-gray-light-200 dark:hover:bg-gray-dark-600',
+ false: ''
+ }
+ },
+ defaultVariants: {
+ size: 'md',
+ align: 'start',
+ allowsSorting: false
+ }
+ }
+);
+
+export const tableRowVariants = cva(
+ ['table-row transition-colors', 'border-b border-gray-light-200 dark:border-gray-dark-700', 'last:border-b-0'],
+ {
+ variants: {
+ isStriped: {
+ true: 'even:bg-gray-light-50 dark:even:bg-gray-dark-750',
+ false: ''
+ },
+ isSelectable: {
+ true: 'cursor-pointer hover:bg-gray-light-100 dark:hover:bg-gray-dark-600',
+ false: ''
+ },
+ isSelected: {
+ true: 'bg-secondary/10 dark:bg-secondary/20 hover:bg-secondary/20 dark:hover:bg-secondary/30',
+ false: ''
+ },
+ isDisabled: {
+ true: 'opacity-50 cursor-not-allowed pointer-events-none',
+ false: ''
+ }
+ },
+ defaultVariants: {
+ isStriped: false,
+ isSelectable: false,
+ isSelected: false,
+ isDisabled: false
+ }
+ }
+);
+
+export const tableCellVariants = cva(['table-cell text-text-light dark:text-text-dark transition-colors'], {
+ variants: {
+ size: {
+ sm: 'px-2 py-1 fs-small tablet:fs-small-tablet',
+ md: 'px-4 py-2 fs-base tablet:fs-base-tablet',
+ lg: 'px-6 py-3 fs-h6 tablet:fs-h6-tablet'
+ },
+ align: {
+ start: 'text-left',
+ center: 'text-center',
+ end: 'text-right'
+ },
+ isCompact: {
+ true: 'py-1',
+ false: ''
+ }
+ },
+ defaultVariants: {
+ size: 'md',
+ align: 'start',
+ isCompact: false
+ }
+});
+
+export const loadingOverlayVariants = cva(
+ [
+ 'loading-overlay absolute inset-0 z-20',
+ 'bg-white/80 dark:bg-gray-dark-800/80',
+ 'backdrop-blur-sm',
+ 'flex items-center justify-center',
+ 'transition-opacity'
+ ],
+ {
+ variants: {
+ isVisible: {
+ true: 'opacity-100',
+ false: 'opacity-0 pointer-events-none'
+ }
+ },
+ defaultVariants: {
+ isVisible: false
+ }
+ }
+);
+
+// ========================================
+// TYPE DEFINITIONS
+// ========================================
+
+export type Selection = 'all' | Set
+
+
+ {pagination && (
+
+
+ {!hideHeader && (
+
+
+
+
+ Table with {tableState.filteredData.length} data rows
+ {selectionMode !== 'none' || showSelectionCheckboxes ? ' with selection enabled' : ''}
+ {tableState.sortDescriptor && ' sorted by ' + tableState.sortDescriptor.column}
+
+ | , -1)} + role='columnheader' + aria-label='Selection' + aria-colindex={1} + > + {selectionMode === 'multiple' ? ( + 0 + } + onChange={tableState.toggleAllRowsSelection} + aria-label='Select all rows' + disabled={disallowEmptySelection && tableState.selectedRows.length === 1} + /> + ) : ( + Select + )} + | + )} + {columns.map((column, index) => ( + {
+ if (column.allowsSorting || column.sortable) {
+ tableState.handleSort(column.key);
+ }
+ }}
+ onKeyDown={(e) => {
+ if ((e.key === 'Enter' || e.key === ' ') && (column.allowsSorting || column.sortable)) {
+ e.preventDefault();
+ tableState.handleSort(column.key);
+ }
+ }}
+ >
+
+ {column.header}
+ {(column.allowsSorting || column.sortable) && renderSortIcon(column)}
+ {column.filterable && (
+ <>
+
+
+ Enter text to filter the {column.header} column
+
+ tableState.setFilter(String(column.key), e.target.value)}
+ className='ml-2 p-1 border rounded-md text-sm bg-white dark:bg-gray-dark-800 border-gray-light-300 dark:border-gray-dark-600 text-text-light dark:text-text-dark placeholder-gray-light-400 dark:placeholder-gray-dark-400 focus:ring-primary focus:border-primary w-20'
+ aria-label={`Filter by ${column.header}`}
+ aria-describedby={`filter-help-${column.key}`}
+ onClick={(e) => e.stopPropagation()}
+ />
+
+ )}
+ |
+ ))}
+
|---|---|
| + No results found for the applied filters. Try modifying the search criteria. + | +|
| e.stopPropagation()} + > + { + if (!isDisabled) { + tableState.toggleRowSelection(row); + } + }} + aria-label={`${selectionMode === 'single' ? 'Select row' : 'Select row'} ${actualRowIndex + 1}`} + disabled={ + isDisabled || + (disallowEmptySelection && isSelected && tableState.selectedRows.length === 1) + } + /> + | + )} + {columns.map((column, colIndex) => ( +{ + e.stopPropagation(); + handleCellClick(actualRowIndex, colIndex, row); + }} + > + {column.cell ? column.cell(row) : String((row as any)[String(column.key)] || '')} + | + ))} +
+
+
+ Page {tableState.currentPage} of {tableState.totalPages}
+
+
+
+ )}
+