Data Table

The Data Table is a comprehensive, application-wide component that provides users with tools to customize, manage, filter, and manipulate tabular data. It serves as the primary interface for viewing and interacting with collections of records.

1. Purpose

• Data Presentation: Display structured data in a clear, readable, and responsive grid format.
• Data Manipulation: Enable users to sort, filter, and search data to find specific records efficiently.
• Data Management: Provide tools for bulk actions, data export, and view customization.
• Consistency: Ensure a uniform user experience for data interaction across all modules of the application.

2. Scope

• Applies to all list views, reports, and data grids within the application.
• Implemented as a shared, reusable UI component (DataTable) used across all modules (e.g., Billing, Deposits, Receivables).
• Supports both client-side and server-side data models (implementation details vary, but functional behavior remains consistent).

3. Placement and Visibility

• Primary Location: Occupies the main content area of list pages (e.g., /billing/items, /deposits).
• Context: Typically positioned below the page header and breadcrumbs.
• Components:
  • Toolbar: Located immediately above the table grid.
  • Table Grid: The central data display area.
  • Pagination: Located immediately below the table grid.

4. Structure and Content

4.1 Toolbar

The toolbar provides high-level controls for managing the dataset:

• Global Search: A text input field to search across all searchable columns.
• Filter Reset: A "Reset" button (visible only when filters are active) to clear all applied column filters.
• Export: An "Export CSV" button to download the current dataset.
• View Options: A "View" dropdown menu to toggle the visibility of individual columns.

4.2 Table Header

• Column Headers: Display the field name for each column.
• Sorting Indicators: Visual arrows indicating ascending or descending sort order.
• Filter Triggers: Icons or interactive elements to access column-specific filter menus.

4.3 Table Body

• Rows: Individual data records.
• Cells: Data values for each column.
• Selection: Checkboxes (if enabled) at the start of each row for single or multi-row selection.
• Empty State: A "No results" message displayed when the dataset is empty or no records match the current filters.

4.4 Pagination

• Record Count: Displays the number of selected rows (if selection is enabled) and the total number of records found.
• Page Navigation: Controls to navigate to the first, previous, next, and last pages.
• Page Indicator: Displays the current page number and total pages (e.g., "Page 1 of 5").
• Rows Per Page: A dropdown selector to control the number of records displayed per page (10, 20, 50, 100).

5. Interaction Behavior

5.1 Sorting

• Single Column: Clicking a column header toggles sorting: Ascending -> Descending -> Unsorted.
• Multi-Column: Holding Shift while clicking headers enables multi-column sorting.
• Persistence: Sort state is maintained during pagination.

5.2 Filtering

The system supports two layers of filtering:

• Global Search: Filters rows based on a text match across all searchable fields.
• Column Filters: Specific logic based on data type:
  • Text: Contains, Equals, Starts With, Ends With.
  • Number: Equals, Greater Than, Less Than, Between.
  • Date: Specific Date, Date Range (From/To), Presets (Today, This Week, This Month).
  • Select: Multi-select from a list of available options.
• Logic: Global search and column filters operate with AND logic (records must match ALL criteria).

5.3 Column Management

• Visibility: Users can hide or show columns via the "View" menu in the toolbar to declutter the view.
• Persistence: Column visibility preferences apply to the current session.

5.4 Row Selection

• Single Select: Clicking a row (if configured) or a specific checkbox selects that record.
• Multi-Select: Clicking multiple checkboxes allows for bulk selection.
• Header Checkbox: Toggles selection for all visible rows on the current page.
• Feedback: Selected rows are visually highlighted (e.g., bg-muted).

5.5 Export

• Format: CSV (Comma Separated Values).
• Scope: Exports the current filtered dataset (respecting active filters and search).
• Content: Includes visible columns.

6. Large Dataset Handling

6.1 Pagination

• Default: Tables default to a manageable page size (e.g., 20 rows) to ensure performance.
• Navigation: Users can navigate through large datasets without loading all records into the DOM simultaneously.
• State: Pagination resets to Page 1 when filters or search criteria are changed to ensure users don't miss results.

6.2 Text Wrapping

• Truncation: By default, long text content is truncated with an ellipsis to maintain row height consistency.
• Tooltips: Hovering over truncated cells displays the full content via a native title attribute.
• Configuration: Tables can be configured to enable text wrapping (enableTextWrap) for specific use cases.

7. Accessibility Requirements

The Data Table component must comply with WCAG 2.1 AA standards.

7.1 Semantics

• Structure: Uses standard HTML <table>, <thead>, <tbody>, <tr>, <th>, and <td> elements.
• Roles: Proper ARIA roles are applied where semantic HTML is insufficient.

7.2 Keyboard Navigation

• Focus: All interactive elements (headers, buttons, inputs, checkboxes) are focusable via Tab.
• Sorting: Column headers are activatable via Enter or Space.
• Pagination: Paging controls are keyboard accessible.

7.3 Visual Accessibility

• Contrast: Text and interactive elements meet minimum contrast ratios (4.5:1).
• Focus Indicators: Clearly visible focus rings on all interactive elements.
• Sort State: aria-sort attributes indicate the current sort direction to screen readers.