Tables
Version: v3.0.0 Status: Normative (text), Illustrative (diagrams only) Scope: Displaying, sorting, paginating, and interacting with tabular data Domain: TABLES
Statement
The system shall provide reusable table components for displaying data in rows and columns, with capabilities for sorting, pagination, row selection, column visibility configuration, and large dataset export handling.
Tables are a foundational UI component used across multiple application screens. They interface with the filter system for column-based filtering, the export/print functionality for data extraction, and the notification system for background export completion alerts. Individual table implementations define context-specific behaviors such as which columns are sortable, what actions row clicks trigger, and how row states are visually differentiated.
Behavior Overview (Illustrative)
This diagram illustrates the high-level behavior. It does not specify UI layout, styling, or interaction details.
Definitions
| Term | Definition |
|---|---|
| Sortable Column | A column whose data can be reordered by the user via header interaction |
| Selectable Row | A table row that can be highlighted to indicate user focus or selection |
| Pagination | Division of large datasets into discrete pages with navigation controls |
| Items Per Page | The configurable number of data rows displayed in a single page view |
| Background Export | An asynchronous export operation that allows the user to continue working while processing completes |
Functional Requirements
Data Display (REQ-TABLES-001)
FR-TABLES-001 Display Data in Tabular Format
The system shall display data in a tabular format with columns and rows.
Acceptance Criteria:
Data Structure:
- Display data organized in rows and columns
- Display column headers identifying each data column
- Support grouped column headers where a parent header spans multiple child columns
Visual Presentation:
- Indicate row state through visual differentiation
- Provide vertical scrolling when content exceeds the visible display area
Error Handling:
- No data available: Display an empty table with column headers and an indication that no data exists
- Data retrieval failure: Display an error message indicating the data could not be loaded
Trace: Source: 3.0.0-Tables (Row 1, 2, 11) | Jira: BT-2416 | Tests: See scenarios
Sorting (REQ-TABLES-002)
FR-TABLES-002 Sort Table Data by Column
The system shall allow users to sort table data by sortable columns.
Acceptance Criteria:
Sort Indication:
- Indicate which columns are sortable
- Indicate the current sort state (unsorted, ascending, descending) for each sortable column
Sort Behavior:
- Sort data in ascending order on first activation of a sortable column
- Toggle sort direction between ascending and descending on subsequent activations
- Enforce single-column sorting (sorting by a new column shall clear the previous sort)
- Apply chronological ordering for date-type columns
Trace: Source: 3.0.0-Tables (Row 3, 4, 5, 6, 7) | Jira: BT-2416 | Tests: See scenarios
Row Interaction (REQ-TABLES-003)
FR-TABLES-003 Select and Interact with Table Rows
The system shall allow users to select and interact with table rows.
Acceptance Criteria:
Selection:
- Visually distinguish selected rows from unselected rows
- Support row selection via interaction with selectable columns
Actions:
- Support column-specific actions where different columns trigger different behaviors
- Enforce action availability based on user permissions
Assumptions:
- The specific actions available for each column are defined by individual table implementations
Open Questions:
| ID | Question | Resolution |
|---|---|---|
| OQ-01 | Should multi-row selection be supported? | Resolved: Yes, optional feature (multiselect on/off configurable per table) |
Trace: Source: 3.0.0-Tables (Row 8, 9, 10) | Jira: BT-2416 | Tests: See scenarios
Pagination (REQ-TABLES-004)
FR-TABLES-004 Navigate Paginated Data
The system shall provide pagination controls for navigating large datasets.
Acceptance Criteria:
Items Per Page:
- Allow users to select items per page from predefined options (10, 20, 30, 50)
- Immediately refresh the table display when items per page changes
Page Navigation:
- Provide navigation to the previous page
- Provide navigation to the next page
- Disable previous-page navigation when on the first page
- Disable next-page navigation when on the last page
Page Indicators:
- Indicate the current page
- Provide direct navigation to specific page numbers
- Display a maximum of 5 page number buttons at a time
- Display page numbers with first pages, ellipsis indicator, and last page when total pages exceed 5
Direct Page Input:
- Allow users to navigate directly to a specified page number via input
- Prevent navigation to invalid page numbers
- Navigate to page 1 when the user enters zero or a negative number
Trace: Source: 3.0.0-Tables (Row 12-28) | Jira: BT-2416 | Tests: See scenarios
Large Data Export (REQ-TABLES-005)
FR-TABLES-005 Handle Large Data Exports
The system shall handle export and print operations for datasets exceeding real-time processing limits.
Acceptance Criteria:
Export Limits:
- Limit synchronous export operations to prevent timeouts
- Limit synchronous exports to 1000 records with truncation message
User Notification:
- Notify users when requested data exceeds the real-time export limit
Export Options:
- Offer users the option to proceed with truncated data
- Offer users the option to queue a background export for complete data
- Offer users the option to cancel the export operation
Background Export:
- Notify users when background export completes according to user notification preferences
- Support notification via email, in-app, or both channels per user preference
Error Handling:
- Background export fails: Notify users of the failure and provide retry option
- Export timeout during synchronous operation: Display truncation warning and provide background export option
Trace: Source: 3.0.0-Tables (Row 29, 30) | Jira: BT-2560 | Tests: See scenarios | Related: Notification system for background export completion
Column Visibility (REQ-TABLES-006)
FR-TABLES-006 Configure Column Visibility
The system shall allow users to configure which columns are visible in a table.
Acceptance Criteria:
Configuration Access:
- Provide access to column visibility configuration
- Display all available columns with their current visibility state
Visibility Control:
- Allow users to toggle visibility for individual columns
- Apply visibility changes upon user confirmation
- Discard visibility changes upon user cancellation
Filter Behavior:
- Maintain filter functionality on hidden columns
Trace: Source: 3.0.0-Tables (Row 31, 32, 33, 34) | Jira: BT-2416 | Tests: See scenarios
Configuration Options
| Option | Default | Description | Affects |
|---|---|---|---|
default_items_per_page | 20 | Default number of items displayed per page | REQ-TABLES-004 |
max_realtime_export_records | 1000 | Maximum records for synchronous export before truncation | REQ-TABLES-005 |
background_export_enabled | true | Whether background export option is available | REQ-TABLES-005 |
Assumptions
- Users have appropriate role permissions to access screens containing tables
- Tables are rendered within a web browser supporting standard DOM operations
- Network connectivity is available for data retrieval and export operations
- Individual table implementations define context-specific behaviors (which columns are sortable, row click actions, etc.)
UI Notes (Illustrative)
FR-TABLES-001 UI Specifications
Row State Visual Indicators:
- Green background: patient wells with exportable outcome
- Blue background: control wells
- Yellow background: warning states
- Red background: error states
Column Header Layout:
- Grouped headers: parent header spans child columns visually
- Headers may include merged rows for hierarchical display
Screenshots: media/image203.png (grouped column headers)
FR-TABLES-002 UI Specifications
Sort Indicator Icons:
- Not sortable: no indicator displayed
- Sortable but not sorted: neutral sort icon
- Ascending sort: up arrow indicator
- Descending sort: down arrow indicator
Screenshots: media/image204.png (not sortable), media/image205.png (sortable not set), media/image206.png (ascending), media/image207.png (descending)
FR-TABLES-003 UI Specifications
Selection Visual Treatment:
- Entire row is highlighted when selected
- Distinct visual style separates selected from unselected rows
Screenshots: media/image208.png (row selection)
FR-TABLES-004 UI Specifications
Pagination Control Layout:
- Items per page dropdown
- Previous button
- Page number buttons (up to 5)
- Ellipsis indicator for hidden pages
- Next button
- Go to page input with submit button
Visual Styling:
- Current page: blue font
- Other pages: black font
- Disabled buttons: grayed appearance
Page Number Display Patterns:
- 5 or fewer pages: all page numbers displayed
- More than 5 pages, early pages: 1, 2, 3, ..., [last]
- More than 5 pages, later pages: 1, ..., [n-2], [n-1], [n]
Screenshots: media/image209.png (items per page), media/image210.png (prev/next), media/image211.png (go to page), media/image212.png (early pages), media/image213.png (later pages)
FR-TABLES-005 UI Specifications
Large Export Dialog:
- Message: "Selected data is too large to export in real time. Export will be truncated. Do you want to:"
- Options: "Continue" (truncated), "Export all data in the background", "Cancel"
FR-TABLES-006 UI Specifications
Column Visibility Control:
- Eye icon indicates show/hide columns feature
- Dialog lists all columns with toggle controls
- Save and Cancel buttons for confirmation/cancellation
Screenshots: media/image214.png (eye icon), media/image215.png (dialog)
Implementation (Illustrative)
The Tables domain is primarily implemented in Vue.js frontend components. The backend provides sorting infrastructure via the Sortable trait, pagination via Laravel's LengthAwarePaginator, and large export handling via background job infrastructure.
| Component | Type | Path | Requirements |
|---|---|---|---|
Sortable | Trait | code/app/Sortable.php | REQ-TABLES-002 |
ListRunsAction | Action | code/app/Actions/Runs/ListRunsAction.php | REQ-TABLES-002, REQ-TABLES-004 |
LengthAwarePaginator | Laravel Class | Laravel framework | REQ-TABLES-004 |
PaginatedPatientWellCollection | Resource | code/app/Http/Resources/PatientWells/PaginatedPatientWellCollection.php | REQ-TABLES-004 |
GetPaginateNotificationsAction | Action | code/app/Actions/Notifications/GetPaginateNotificationsAction.php | REQ-TABLES-004 |
RunResultExportJob | Job | code/app/Jobs/RunResultExportJob.php | REQ-TABLES-005 |
AuditExportJob | Job | code/app/Jobs/AuditExportJob.php | REQ-TABLES-005 |
TrendsReportExport | Export | code/app/Exports/TrendsReportExport.php | REQ-TABLES-005 |
LjReportExport | Export | code/app/Exports/LjReportExport.php | REQ-TABLES-005 |
Backend Notes:
- The
Sortabletrait interprets sort direction from request parameter prefix: no prefix = ascending,-prefix = descending (e.g.,-created_at) - Pagination uses Laravel's paginator with
perPageparameter; response includescurrent_page,last_page,total,per_pagemetadata - Large export pattern: controller checks count against threshold (1000), offers truncated/background options, background exports queued as jobs, completion triggers notification
Frontend-Implemented Requirements:
| Requirement | Frontend Notes |
|---|---|
| REQ-TABLES-001 | Table rendering, column headers, row state styling |
| REQ-TABLES-003 | Row selection, click handlers, column actions |
| REQ-TABLES-006 | Column visibility toggle, local storage persistence |
Frontend Locations:
| Component Type | Location |
|---|---|
| View | views/TableHandler.vue (cross-cutting) |
| Components | components/column-visibility/, components/table-components/ |
Traceability Matrix
| Requirement | Title | Verification | Implementation | Test Cases | Status |
|---|---|---|---|---|---|
| REQ-TABLES-001 | Display Data in Tabular Format | Test | Frontend (Vue.js) | See scenarios | Draft |
| REQ-TABLES-002 | Sort Table Data by Column | Test | Sortable trait, ListRunsAction | See scenarios | Draft |
| REQ-TABLES-003 | Select and Interact with Table Rows | Test | Frontend (Vue.js) | See scenarios | Draft |
| REQ-TABLES-004 | Navigate Paginated Data | Test | LengthAwarePaginator, Action classes | See scenarios | Draft |
| REQ-TABLES-005 | Handle Large Data Exports | Test | Job classes, Export classes | See scenarios | Draft |
| REQ-TABLES-006 | Configure Column Visibility | Test | Frontend (Vue.js) | See scenarios | Draft |
Notes
- Individual table implementations define context-specific behaviors including which columns are sortable, selectable, or trigger actions
- Background color meanings are context-specific to each table instance
- The ellipsis ("...") in pagination is informational only and has no click action
- See BT-2560 for original timeout bug: "The Oops message is displayed after exporting or printing large recordsets in tables"
Open Questions
| ID | Question | Source | Owner | Date Raised | Resolution |
|---|---|---|---|---|---|
| OQ-01 | Should multi-row selection be supported? | REQ-TABLES-003 | - | - | Resolved: Yes, optional feature (multiselect on/off configurable per table) |
Acceptance Tests
Test: REQ-TABLES-001
Test: Verify table structure
Given: User navigates to a screen with tabular data
When: The table is rendered
Then: Data shall be displayed in rows and columns
And: Column headers shall be visible
And: Grouped headers shall span multiple sub-columns where configured
Test: Verify state indicators
Given: Table contains items in different states
When: The table is rendered
Then: Items in different states shall be visually distinguished
Test: Verify vertical scrolling
Given: Table contains more rows than visible area
When: User views the table
Then: Vertical scrolling shall be available
Test: Verify empty state
Given: No data is available for the table
When: The table is rendered
Then: Column headers shall be displayed
And: An indication that no data exists shall be shown
Test: Verify error handling
Given: Data retrieval fails due to network or server error
When: The table attempts to load
Then: An error message indicating data could not be loaded shall be displayed
Test: REQ-TABLES-002
Test: Verify sort indicators
Given: Table with sortable columns
When: User views column headers
Then: Non-sortable columns shall show no sort indicator
And: Sortable columns shall show a sort indicator
And: Currently sorted column shall show direction
Test: Verify single column sort enforcement
Given: Table sorted by Column A ascending
When: User activates sorting on Column B
Then: Column B shall be sorted ascending
And: Column A sort shall be cleared
Test: Verify sort toggle behavior
Given: Table with unsorted sortable column
When: User activates column sorting once
Then: Column shall be sorted ascending
When: User activates same column again
Then: Column shall be sorted descending
When: User activates same column again
Then: Column shall be sorted ascending
Test: Verify date column chronological sorting
Given: Table with a date-type sortable column
When: User sorts by the date column ascending
Then: Rows shall be ordered from earliest to latest date
When: User sorts by the date column descending
Then: Rows shall be ordered from latest to earliest date
Test: REQ-TABLES-003
Test: Verify row selection
Given: Table with selectable rows
When: User interacts with a selectable column in a row
Then: The entire row shall be visually distinguished as selected
Test: Verify column-specific actions
Given: Table where different columns trigger different actions
When: User interacts with an action-triggering column
Then: The corresponding action shall be performed
Test: Verify permission-based action availability
Given: User with limited permissions viewing a table
When: User attempts to interact with a restricted action column
Then: The action shall not be available or shall be denied
Test: REQ-TABLES-004
Test: Verify items per page selection
Given: Table with more than 50 items
When: User selects "10" from items per page
Then: Table shall display 10 items
When: User selects "50" from items per page
Then: Table shall display 50 items
Test: Verify previous/next navigation
Given: Table on page 2 of 5
When: User activates previous page navigation
Then: Page 1 shall be displayed
Given: Table on page 1
Then: Previous page navigation shall be disabled
Given: Table on last page
Then: Next page navigation shall be disabled
Test: Verify page number navigation
Given: Table with 10 pages, currently on page 1
When: User views page numbers
Then: Page numbers shall indicate available pages with current page distinguished
When: User selects page 5
Then: Page 5 shall be displayed
Test: Verify direct page navigation
Given: Table with 10 pages
When: User enters "5" and confirms navigation
Then: Page 5 shall be displayed
When: User enters "15"
Then: Navigation shall be prevented (invalid page)
When: User enters "0" and confirms
Then: Page 1 shall be displayed
When: User enters "-1" and confirms
Then: Page 1 shall be displayed
Test: Verify page number display for many pages
Given: Table with 20 pages, currently on page 1
When: User views page numbers
Then: Page numbers 1, 2, 3 shall be displayed
And: An ellipsis indicator shall be displayed
And: Page 20 shall be displayed
And: Maximum of 5 page number buttons shall be shown
Given: Table with 20 pages, currently on page 18
When: User views page numbers
Then: Page 1 shall be displayed
And: An ellipsis indicator shall be displayed
And: Pages 18, 19, 20 shall be displayed
Test: REQ-TABLES-005
Test: Verify large export handling
Given: Table with more than 1000 records
When: User initiates export
Then: User shall be notified that data exceeds limit
And: User shall be offered truncated export option
And: User shall be offered background export option
And: User shall be offered cancel option
Test: Verify truncated export
Given: User is notified of large dataset exceeding 1000 records
When: User selects truncated export option
Then: Export shall proceed with 1000 records
And: Truncation message shall be included
Test: Verify background export
Given: User is notified of large dataset
When: User selects background export option
Then: Export shall be queued
And: User shall be able to continue working
When: Background export completes
Then: User shall be notified according to preferences (email, in-app, or both)
Test: Verify export cancellation
Given: User is notified of large dataset
When: User selects cancel option
Then: Export operation shall be cancelled
And: No data shall be exported
Test: Verify background export failure handling
Given: User has queued a background export
When: The background export fails
Then: User shall be notified of the failure
And: User shall be provided a retry option
Test: REQ-TABLES-006
Test: Verify column visibility access
Given: Table with configurable column visibility
When: User accesses column visibility configuration
Then: All columns shall be listed with current visibility state
Test: Verify hide column
Given: Column visibility configuration is open
When: User hides Column A and confirms
Then: Column A shall no longer be visible in the table
Test: Verify show hidden column
Given: Column A is currently hidden
When: User accesses column visibility configuration
And: User shows Column A and confirms
Then: Column A shall be visible in the table
Test: Verify cancel discards changes
Given: Column visibility configuration is open
When: User modifies visibility settings and cancels
Then: All columns shall retain their previous visibility state
Test: Verify filter on hidden column
Given: Column A is hidden from view
When: Filter is applied to Column A
Then: Filter shall operate correctly on the hidden column data
And: Matching rows shall be displayed (without Column A visible)
Related Design Documents
| Design Document | Relevant Sections |
|---|---|
| STD UI Testability | HTML Attributes (table and cell attributes for automated testing) |
Appendix: Process Artifacts
Completion Checklist
- All requirements are capability-level (describe behavior, not UI)
- Requirement variants consolidated (no requirement explosion)
- UI details are fully demoted to Illustrative section
- Configuration options are not encoded as requirements
- Acceptance criteria describe behavior, not UI mechanics
- Every requirement has acceptance criteria and source traceability
- Error handling addressed for I/O, validation, and external system requirements
- Open questions documented with resolutions
- Consolidations documented in Reviewer Notes with reversibility info
- Module can survive a full UI redesign unchanged
- Refinements folded into acceptance criteria
- Traceability matrix is complete
Reviewer Notes
Conversion Notes:
This document was converted from output/srs/tables.md to the new SRS readability format. The 6 source requirements represent distinct table capabilities:
| Source Requirement | Capability | Disposition |
|---|---|---|
| REQ-TABLES-001 | Data display in rows/columns | Preserved as FR-TABLES-001 |
| REQ-TABLES-002 | Column sorting | Preserved as FR-TABLES-002 |
| REQ-TABLES-003 | Row selection and interaction | Preserved as FR-TABLES-003 |
| REQ-TABLES-004 | Pagination navigation | Preserved as FR-TABLES-004 |
| REQ-TABLES-005 | Large data export handling | Preserved as FR-TABLES-005 |
| REQ-TABLES-006 | Column visibility configuration | Preserved as FR-TABLES-006 |
No Consolidation Required: These requirements represent orthogonal capabilities that are independently testable. REQ-TABLES-001 handles display structure, REQ-TABLES-002 handles sorting behavior, REQ-TABLES-003 handles row interaction, REQ-TABLES-004 handles pagination, REQ-TABLES-005 handles export limits, and REQ-TABLES-006 handles column visibility.
Format Changes:
- Added Statement section for quick understanding
- Added Mermaid behavior overview diagram
- Grouped acceptance criteria by concern with blank lines before bullets
- Changed "Non-normative" to "Illustrative" throughout
- Moved tests to end with back-links to requirements
- Consolidated inline Trace references
- Former refinements (items per page options, page button limits, record limits) already folded into acceptance criteria in source
Reversibility: Source file preserved at output/srs/tables.md