[#70190] Add missing accessibility semantics for Border Box Table

[myabc]

Ticket

https://community.openproject.org/work_packages/70190

What are you trying to accomplish?

Provide proper accessibility semantics for the Border Box Table component to make it easier for users of Assistive Technologies (AT) to navigate through and interpret data in Border Box Tables.

It address the following issues:

• BorderBoxTables lack proper table semantics, so screen readers interpret them as generic lists rather than tables.
• Column headers are not recognized correctly and are often read as a single block of text.
• Rows are announced as list items and may be read in full instead of cell by cell.
• Cells are not associated with their column headers, removing important contextual information for screen reader users.
• Action or button columns may have their headers skipped or announced as “blank,” making their purpose unclear.

This PR also fixes our use of BEM syntax.

Screenshots

See ticket for screenshots and notes to help review this PR.

What approach did you choose and why?

This PR has an upstream prerequisite: primer/view_components#3821

This PR uses its own BorderBox implementation to allow additional customisation. In particular, in order to adhere to Best Practices, we need to avoid applying certain roles (such as rowgroup) to list elements. See inline comment for more details.

Long term, we may want to discuss whether this is still the right strategy. Even though ARIA roles are provided to allow table semantics on on table elements, they are not recommended - the prevailing advice on accessibility is to always prefer native HTML elements.

Merge checklist

• Merge upstream changes Teach BorderBox component a list_arguments param primer/view_components#3821
• Added/updated tests
• Added/updated documentation in Lookbook (patterns, previews, etc)
• Tested major browsers (Chrome, Firefox, Edge, ...)

[Copilot]

Pull request overview

This PR adds comprehensive ARIA semantics to the Border Box Table component to improve accessibility for screen readers and other assistive technologies. The changes include adding semantic roles (table, rowgroup, row, columnheader, rowheader, cell) and ARIA attributes (colcount, colindex, colspan) to properly structure the table for accessibility. Additionally, the CSS class naming convention has been updated from BEM modifier syntax (--) to BEM element syntax (__) to better reflect the semantic structure.

Key changes:

• Added ARIA table semantics (role="table", role="rowgroup", role="row", etc.)
• Updated CSS class names from modifier to element syntax (e.g., op-border-box-grid--heading → op-border-box-grid__header)
• Added comprehensive test coverage for accessibility features
• Refactored component templates to support proper ARIA structure

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
spec/support/shared/components/border_box_table_component.rb	Updated shared examples to use new CSS class names with __ element syntax
spec/support/pages/groups.rb	Updated page object selectors to use new __row-item class name
spec/components/op_primer/border_box_table_component_spec.rb	Added comprehensive test coverage for ARIA roles and attributes (table, rowgroup, row, columnheader, cell, etc.)
app/components/op_primer/border_box_table_component.sass	Refactored CSS to use BEM element syntax (__) instead of modifier syntax (--) for better semantic clarity
app/components/op_primer/border_box_table_component.rb	Added column_count method and updated header class logic to support ARIA structure
app/components/op_primer/border_box_table_component.html.erb	Added ARIA roles and attributes to table container, headers, rows, and cells; restructured template to properly nest semantic elements
app/components/op_primer/border_box_row_component.rb	Added cell_role method to determine rowheader vs cell roles; refactored cell_classes method using class_names helper
app/components/op_primer/border_box_row_component.html.erb	Added ARIA roles to cells and actions; removed wrapper div to flatten structure for better ARIA compliance

[myabc]

See also comment over here:

primer/view_components#3821 (comment)

[bsatarnejad]

Hey @myabc
Thanks for fixing it!
It works almost good, but I find sth confusing for the AT user, for example here:

In the header, NVDA reads:
Title column 1 title, date and time column 2 date and time,....

It repeats the column name.

[myabc]

@bsatarnejad I think that is actually the default NVDA behaviour (which I find weird). Can you compare behavior with a normal/native HTML table?

[bsatarnejad]

@bsatarnejad I think that is actually the default NVDA behaviour (which I find weird). Can you compare behavior with a normal/native HTML table?

I tested a native html, it reads out like: column 1 value.
In a row (not header), all cell data is read correctly except the first cell. In my example it reads:
future meeting row 2 title column 1 link future meeting.
Project column 3 demo project.