# Open Point DREAM-860 - Decide grid or treegrid semantics for the work package table

Project: Stream Design System
Status: needs clarification
URL: https://community.openproject.org/work_packages/DREAM-860

## Details

| Attribute | Value |
| --- | --- |
| Involved people | Behrokh Satarnejad, Alexander Coles, Lars Wassermann, Darren Cadwallader |
| Assignee | Behrokh Satarnejad |
| Decision |  |
| Date |  |
| Module |  |
| Labels |  |

## Related to

| ID | Subject | Type | Status | Assignee | Project |
| --- | --- | --- | --- | --- | --- |
| AGILE-473 | Decide the accessible role structure for Backlogs cards | Open Point | needs clarification | Alexander Coles | Stream agile |
| DREAM-858 | Expose row indices on BorderBoxTable rows for assistive technology and specs | Code maintenance | tested |  | Stream Design System |
| DREAM-885 | Treegrid semantics (ARIA roles, states and row model) for the work package table | Implementation | closed |  | Stream Design System |
| DREAM-886 | Focus model and cell navigation for the work package table | Implementation | closed |  | Stream Design System |
| DREAM-894 | Keyboard selection, context actions and selection feedback in the work package table | Implementation | closed |  | Stream Design System |
| DREAM-895 | Keyboard interaction with cell controls and editors in the work package table | Implementation | closed |  | Stream Design System |
| DREAM-938 | Accessible row positions and counts in the work package table | Implementation | closed |  | Stream Design System |
| DREAM-944 | Decide the counting model for row positions in expanded relation and children columns | Open Point | needs clarification | Behrokh Satarnejad | Stream Design System |
| DREAM-945 | Expose work package row headers in the table | Implementation | closed |  | Stream Design System |

## Description

### Decision needed

Decide which accessible role the work package table should expose in flat, grouped and hierarchy modes for <mention class="mention" data-id="DREAM-846" data-type="work_package" data-text="#DREAM-846">#DREAM-846</mention>: `grid` throughout, or `treegrid` where the table represents an expandable hierarchy.

Do not assume grouped rows and hierarchical work packages require the same semantics. Record the decision for each mode and explain any differences.

Cell navigation is required in every mode. Decide whether rows should additionally receive focus, and specify the compatible expansion/collapse, navigation and row-selection keys. A row-only navigation model does not meet DREAM-846's agreed baseline.

Define how users enter controls or an editor within a cell, move between them, and return to cell navigation. Settle the interaction sequence here rather than leaving it as an unspecified implementation choice.

Define which row categories are navigable, including group headers, sums, inline-create and empty-state rows, and how their controls are reached. Keep navigability distinct from selection eligibility and row counting.

Define the accessible row-count and row-index model for each table mode, including pagination, headers, group and sum rows, contextual ancestors, expanded relations, repeated work package occurrences, empty/create rows and collapsed rows. Distinguish query-result positions from positions in the accessible table structure.

### Decision needed (update: 26/10/2026)

The section above is the original question. This section records what has been decided since, so that the comments below can stay conversation.

**Interim ruling in force (2026-10-23, <https://community.openproject.org/projects/DREAM/work_packages/DREAM-860/activity#comment-1764185>):** row-first focus with cell navigation one step in; `treegrid` in flat, grouped and hierarchy mode; `aria-expanded` on the row; inline-create and empty-state rows exposed inside the treegrid but outside roving navigation (the Create button keeps a native Tab stop). Implemented by <mention class="mention" data-id="DREAM-886" data-type="work_package" data-text="#DREAM-886">#DREAM-886</mention> and <mention class="mention" data-id="DREAM-885" data-type="work_package" data-text="#DREAM-885">#DREAM-885</mention>. <mention class="mention" data-id="64880" data-type="user" data-text="@Behrokh Satarnejad">@Behrokh Satarnejad</mention>'s alternative (cell-only navigation with a dedicated disclosure cell, `grid` for flat tables, `aria-expanded` on the disclosure cell, navigable inline-create and empty-state rows, **Tab** leaving the table at in-cell control boundaries, save-on-leave) is re-tested with NVDA and VoiceOver in <mention class="mention" data-id="DREAM-897" data-type="work_package" data-text="#DREAM-897">#DREAM-897</mention>; evidence returns here.

**Cell interaction, interim for 18.0 (so that <mention class="mention" data-id="DREAM-895" data-type="work_package" data-text="#DREAM-895">#DREAM-895</mention> can proceed):**

  - Settled, both proposals agree: **F2** opens the editor; **Enter** activates a cell's single link or button; **Escape** closes a nested popup before it cancels editing; a validation failure keeps the editor open, focuses the invalid field and announces the error.
  - Contested points keep today's behaviour: **Enter** on an editable cell opens the editor; **Tab**/**Shift+Tab** at the first/last control return to cell navigation; no save-on-leave.
  - <mention class="mention" data-id="DREAM-897" data-type="work_package" data-text="#DREAM-897">#DREAM-897</mention> compares these with the alternative (**Tab** leaving the table at the boundaries, save-on-leave, an explicit Edit control for mixed cells). Any change is a follow-up decision here.
  - ~~Still to approve here before <mention class="mention" data-id="DREAM-895" data-type="work_package" data-text="#DREAM-895">#DREAM-895</mention> finalizes its bindings: the entry key and initial focus target for cells with several controls, including an editable value with adjacent controls. #DREAM-895's design proposes; the feature owner records the approval here.~~ Settled 2026-10-26 by P1-c and the walk details below: **Enter**/**F2** opens the editor, **Tab** reaches the cell's other controls in reading order.

**Tab inside the grid (ruled 2026-10-26, mob review):** **Tab** from a focused row or cell walks that row's interactive controls (work package link, hierarchy toggle, relation expander, details and context-menu buttons) in reading order and leaves the grid after the last one; **Shift+Tab** mirrors it. Implemented in <mention class="mention" data-id="DREAM-895" data-type="work_package" data-text="#DREAM-895">#DREAM-895</mention> (<https://github.com/opf/openproject/pull/26335>), not in <mention class="mention" data-id="26259" data-type="work_package" data-text="#26259">#26259</mention>.

**Cell interaction rulings for <mention class="mention" data-id="DREAM-895" data-type="work_package" data-text="#DREAM-895">#DREAM-895</mention> (2026-10-26, supersede the interim bullets above where they differ):**

  - **P1-c:** **Enter**/**F2** opens editors; **Tab** reaches controls; **Arrow Left/Right** retain the <mention class="mention" data-id="DREAM-886" data-type="work_package" data-text="#DREAM-886">#DREAM-886</mention> D2 cell-navigation behavior and never enter a cell's controls.
  - **P2 and D7:** **Tab**/**Shift+Tab** past an engaged editor's boundary parks it with its draft and focuses that field's origin cell. Explicit **Enter**/**F2** or pointer interaction re-engages it. Date and progress overlays keep their own focus trap. Recovery is suppressed only while focus is inside an editor or its owned overlay, not merely because another editor is parked.
  - **Walk details:** navigation keys on a walked control return to and act from the walk origin; menus and state links return to that origin; a cell-origin walk visits that cell and later cells without wrapping; the header row is not walked.
  - **Inline-create success:** focus returns to **Create new work package** for rapid successive creation; the new row is remembered as the roving position without stealing DOM focus.
  - **Validation:** the existing alert toast and field-label error are the announcement channels, with `aria-invalid` on the invalid input; no duplicate polite announcement.

**Open, initial entry point (raised in the mob review):** the grid is entered at the first body row (<mention class="mention" data-id="DREAM-886" data-type="work_package" data-text="#DREAM-886">#DREAM-886</mention> D1; header reachable with Up). The review leaned towards entering at the column header row so the columns are discoverable first. Trade-off: header-first costs one Down on every entry for every user; row-first hides the header from users who do not know Up reaches it. The <mention class="mention" data-id="DREAM-846" data-type="work_package" data-text="#DREAM-846">#DREAM-846</mention> text says "first navigable cell", the design and code say first navigable row: align the text when this is ruled. NVDA/VoiceOver evidence from <mention class="mention" data-id="DREAM-897" data-type="work_package" data-text="#DREAM-897">#DREAM-897</mention> decides.

**Open, focus after sorting from the column menu:** today focus returns to the sorted column header (<mention class="mention" data-id="DREAM-886" data-type="work_package" data-text="#DREAM-886">#DREAM-886</mention> D14, pinned by spec). Behrokh asked for the first row of the re-sorted table instead. Trade-off: header keeps the user's place and matches menu-return conventions; first row shows the result of the sort immediately but loses the position. Decide together with the entry point.

**Open, Left/Right on group header rows (raised in the <mention class="mention" data-id="DREAM-885" data-type="work_package" data-text="#DREAM-885">#DREAM-885</mention> review, <https://github.com/opf/openproject/pull/26288#pullrequestreview-5684680431>):** a group header has one navigable cell spanning the whole row, so cell focus and row focus look identical. Arriving from a cell with **Arrow Up/Down** lands on that cell; the first **Arrow Left** moves to the row with no visible change and only the second collapses the group. Options: (a) group headers are row-only (no navigable cell; cell-mode **Arrow Up/Down** then skip them); (b) keep the cell, but a vertical move onto a group header lands on the row, so one **Arrow Left** collapses; (c) keep the model and make cell and row focus visibly different on group headers. Recommendation: (b). To settle with <mention class="mention" data-id="64880" data-type="user" data-text="@Behrokh Satarnejad">@Behrokh Satarnejad</mention>.

**Open, focus after closing a column or row menu (raised 2026-10-29 by the <mention class="mention" data-id="DREAM-950" data-type="work_package" data-text="#DREAM-950">#DREAM-950</mention> spec, <https://github.com/opf/openproject/pull/26345>):** when a menu opened from a header button or a row control closes (**Escape** or an action), focus returns to the enclosing cell or column header, not to the button that opened the menu (<mention class="mention" data-id="DREAM-886" data-type="work_package" data-text="#DREAM-886">#DREAM-886</mention> D11; the grid adopts the restored focus onto the cell, pinned by `keyboard_navigation_spec.rb`). A screen-reader user therefore hears the column header or cell, not the control. Options: (a) keep the cell (treegrid model, one place to return to, matches sorting-return above); (b) return to the control when the menu was opened from one, so the announcement names it. Recommendation: (a), re-test under <mention class="mention" data-id="DREAM-897" data-type="work_package" data-text="#DREAM-897">#DREAM-897</mention> with a menu-close scenario.

**Row-count/index model, decided and shipped in <mention class="mention" data-id="DREAM-885" data-type="work_package" data-text="#DREAM-885">#DREAM-885</mention> / <mention class="mention" data-id="DREAM-938" data-type="work_package" data-text="#DREAM-938">#DREAM-938</mention> (<https://github.com/opf/openproject/pull/26288>, <https://github.com/opf/openproject/pull/26291>):**

  - In flat and grouped mode, the column header row is `aria-rowindex` 1; body rows take `query ordinal + 1`; `aria-rowcount` counts the header, every body row of the whole query (group headers and group sums included), the empty-results row and the trailing totals and inline-create rows.
  - Flat and grouped positions are query-wide, not page-wide: page 2 continues the numbering; group headers and sums are counted even for members on other pages (stable gaps for unloaded members).
  - Collapsing a group keeps every collapsed row's index and leaves `aria-rowcount` unchanged (stable gaps, decided 2026-10-24). Hidden structural rows (an `aria-hidden` totals row) drop their index.
  - Whenever the model cannot be trusted (any expanded relation or children column until <mention class="mention" data-id="DREAM-942" data-type="work_package" data-text="#DREAM-942">#DREAM-942</mention>, grouped results in hierarchy mode, a staged drag, a collection that does not match the rendered rows, contradictory group counts, an unclassified row) the whole family is withdrawn rather than guessed.
  - Sibling attributes (`aria-posinset` / `aria-setsize`) are not published yet.
  - Hierarchy mode numbers the rendered rows from the page's first query rank, `(page − 1) × pageSize`, contextual ancestors included, and withholds the total (`aria-rowcount="-1"`): the frontend cannot know how many ancestors earlier pages insert. An ancestor shown again on a later page takes that page's number, so indices can repeat across pages. Decided 2026-10-28 in the review of <https://github.com/opf/openproject/pull/26293> and shipped by <mention class="mention" data-id="DREAM-938" data-type="work_package" data-text="#DREAM-938">#DREAM-938</mention>; the server-side metadata of <mention class="mention" data-id="DREAM-941" data-type="work_package" data-text="#DREAM-941">#DREAM-941</mention> was rejected. Relation and children column positions wait for the counting-model decision in <mention class="mention" data-id="DREAM-944" data-type="work_package" data-text="#DREAM-944">#DREAM-944</mention>.

**Keyboard selection rulings from <mention class="mention" data-id="DREAM-894" data-type="work_package" data-text="#DREAM-894">#DREAM-894</mention> (2026-10-24):**

  - Select All from a structural row clears the anchor. No anchor is manufactured from a column header, group header, sums or totals row: **Ctrl/Cmd+A** from such a row selects all selectable rows on the current page and leaves the range anchor empty. From a work package row it still anchors the focused row.
  - Structural rows are transparent to **Shift+Arrow** ranges. **Shift+Arrow Up/Down** moves focus exactly as plain **Arrow Up/Down** does, structural rows included; the range endpoint stays at the nearest eligible occurrence in the direction of travel. While focus sits on a structural row the range does not change.
  - The first **Shift+Arrow** with no anchor replaces the selection with the occurrence it arrives at and anchors it, the same no-anchor rule as pointer **Shift**-click (<mention class="mention" data-id="OP-20383" data-type="work_package" data-text="#OP-20383">#OP-20383</mention>). Accepted consequence: a structural Select All followed by **Shift+Arrow** collapses the selection to the first eligible row reached; pinned in tests and QA hints.

**Row header (2026-10-26, with Behrokh):** every work package row exposes one `rowheader` cell: the Subject cell when the Subject column is displayed, otherwise the ID cell, otherwise none; column order does not matter. Its accessible name is the subject text or the displayed identifier; hierarchy indicator and level text do not join it. Structural rows (group headers, sums, inline-create, empty-state) have no row header. Implemented by <mention class="mention" data-id="DREAM-945" data-type="work_package" data-text="#DREAM-945">#DREAM-945</mention>; spoken behaviour verified in <mention class="mention" data-id="DREAM-897" data-type="work_package" data-text="#DREAM-897">#DREAM-897</mention>.

**Open, row name and description (raised 2026-10-30 by <mention class="mention" data-id="DREAM-945" data-type="work_package" data-text="#DREAM-945">#DREAM-945</mention>, <https://github.com/opf/openproject/pull/26380>):** each work package row is named by its row header (`aria-labelledby`: subject, or identifier when Subject is hidden). In a baseline comparison the row's baseline status is its description (`aria-describedby`). Options: (a) keep the status as description; (b) fold it into the row name; (c) leave it to the baseline cell only. Recommendation: (a), re-test the spoken result under <mention class="mention" data-id="DREAM-897" data-type="work_package" data-text="#DREAM-897">#DREAM-897</mention> scenario B13.

**Still open here:**

  - The sibling set per mode: what `aria-posinset` / `aria-setsize` count in flat, grouped and hierarchy tables and whether structural rows take part, pending the structural-row speech probe. <mention class="mention" data-id="DREAM-938" data-type="work_package" data-text="#DREAM-938">#DREAM-938</mention> ships without them; a follow-up Implementation work package publishes them once this is decided.
  - The initial entry point (header row or first body row) and the focus after sorting from the column menu (above).
  - **Arrow Left/Right** on group header rows (above).
  - Focus after closing a column or row menu: cell or control (above).
  - Role per mode, additional row focus, expansion and navigation keys, editor entry and return: confirmed or revised on \#DREAM-897's evidence.

**Closing condition:** this Open Point closes when the sibling set is decided and <mention class="mention" data-id="DREAM-897" data-type="work_package" data-text="#DREAM-897">#DREAM-897</mention> has recorded its evidence for the re-test items above. A revision after that evidence becomes a new Open Point rather than reopening this one.

### Context and constraints

<mention class="mention" data-id="DREAM-846" data-type="work_package" data-text="#DREAM-846">#DREAM-846</mention> adds keyboard navigation, row selection and context actions to the work package table only. Card view and Boards are outside its scope.

Selection follows <mention class="mention" data-id="OP-20383" data-type="work_package" data-text="#OP-20383">#OP-20383</mention> and the shared Sortable Lists anchor/range rules, with table-specific scope and eligibility. Keyboard navigation skips collapsed rows; Shift ranges and Select All include eligible collapsed rows on the current page. The page's selection scope includes result rows, contextual ancestors and expanded relation occurrences, deduplicated by work-package identity. A work package can remain selected through a contextual occurrence even when absent from query results. Collapsing preserves selection; any settled scope change intersects existing membership with the new scope without selecting newly appearing work packages. Temporary DOM removal during collapse or loading is not sufficient evidence of removal from the selection scope.

The role decision must support cell navigation, inline editing, nested links and buttons, row selection, and expanded-state feedback. Keyboard focus, selection membership, the range anchor and the work package open in the details pane remain distinct.

### Investigation

  - Compare the candidate semantics on representative flat, grouped and hierarchy tables, including expanded relations and repeated work package occurrences.
  - Check the applicable WAI-ARIA requirements and Authoring Practices guidance against the actual table structure.
  - Verify representative interactions with NVDA in Firefox and Chrome, and VoiceOver in Safari. Record versions, screen-reader modes, steps and observed behavior.
  - Evaluate whether additional row focus improves the required cell-navigation model and identify compatible selection keys.
  - Exercise text-only cells, a single link/button, several controls, editable content with adjacent controls, and an open inline editor. Compare entry keys, forward/backward traversal, first/last-control boundaries and return to navigation; distinguish page Tab order from focus movement in interaction mode.
  - Compare related <mention class="mention" data-id="DREAM-858" data-type="work_package" data-text="#DREAM-858">#DREAM-858</mention> (`OpPrimer::BorderBoxTableComponent` row indices/counts). Assess its conventions for page offsets, headers, footers and empty states against the work package table's additional structural/contextual rows. Do not assume its query-total-plus-header/footer formula fits these modes.

### Resolution criteria

  - A documented role choice exists for each table mode, with evidence and reasons for the choice.
  - Required semantics for headers, selection and expansion are identified. The row-count/index model explicitly covers every row category, pagination offsets, collapsed rows and unknown totals, with consistent indices for all exposed rows. Examples demonstrate flat, grouped and hierarchy modes with contextual/repeated occurrences and empty results.
  - Navigable row categories and access to their controls are defined separately from selection eligibility and row counts. The decision on additional row focus is explicit. Expansion/collapse and navigation keys, including Home/End destination cells, are recorded for each supported focus mode and reconciled with default cell actions and inline editing. Selection keys and limitations are explicit.
  - A complete interaction sequence defines entry to controls/editors, forward/backward traversal and return to cell navigation. It resolves Enter/default-action behavior, Tab/Shift+Tab boundaries, cancellation, saving, validation failure and mixed-content cells. It preserves the single page-tab entry in navigation mode and does not introduce keyboard manual sorting.
  - The result is incorporated into DREAM-846 before its interaction model is finalized. Any prototype used to establish the decision does not independently ship a partial grid interaction.

### Separate work

<mention class="mention" data-id="OP-20384" data-type="work_package" data-text="#OP-20384">#OP-20384</mention> retains ownership of shared Angular anchor/focus cleanup. The cross-view Ctrl/Cmd+Shift+A decision was taken in <mention class="mention" data-id="DREAM-936" data-type="work_package" data-text="#DREAM-936">#DREAM-936</mention>: the shortcut stays with the browser (<mention class="mention" data-id="DREAM-937" data-type="work_package" data-text="#DREAM-937">#DREAM-937</mention>). This Open Point does not absorb either work package.

<mention class="mention" data-id="DREAM-858" data-type="work_package" data-text="#DREAM-858">#DREAM-858</mention> is related Code maintenance for a separate table component. Coordinate row-index conventions and testing where applicable; no prerequisite relationship is assumed.
