Skip to content

feat(macos): Expose heading levels and table structure - #830

Open
xiaolai wants to merge 1 commit into
AccessKit:mainfrom
xiaolai:macos-heading-table-structure
Open

xiaolai wants to merge 1 commit into
AccessKit:mainfrom
xiaolai:macos-heading-table-structure

Conversation

@xiaolai

@xiaolai xiaolai commented Oct 18, 2026

Copy link
Copy Markdown

What

On macOS, headings and tables currently expose almost no structure:

  • Role::Heading maps to the role string "Heading", which is not a standard AX role, and the node's level is never read.
  • Tables, grids and tree grids get the right roles, but no AXRows, AXRowCount, AXColumnCount, AXIndex, cell ranges or column headers (issue Computed table information #10 covers the related computed-table case).

This PR:

  • maps Role::Heading to AXHeading (NSAccessibilityHeadingRole, macOS 26), and exposes the level as AXHeadingLevel (1-based) and as AXValue, as WebKit and Chromium do for releases before macOS 26;
  • for Table, Grid and TreeGrid: AXRows (row children plus the rows inside RowGroup children), AXRowCount, AXColumnCount and AXColumnHeaderUIElements (the ColumnHeader cells of its rows);
  • for rows: AXIndex; for cells (Cell, GridCell, ColumnHeader, RowHeader): AXRowIndexRange and AXColumnIndexRange.

Counts and indices come only from the provider (row_count, column_count, row_index, column_index, spans). When the provider gives none, AXRowCount falls back to the number of rows exposed, and every other structural attribute is withheld through isAccessibilitySelectorAllowed: rather than reported as 0.

AXColumns is not implemented (AppKit marks it optional), and neither are per-cell header links, since AccessKit has no property for them.

accessibilityAttributeValue: now returns NSObject instead of NSString, so that it can return an NSNumber for AXHeadingLevel; the existing string attributes are unchanged.

Testing

On macOS 27 (Apple silicon), with a winit host exposing a book chapter with four headings (levels 1, 2, 1, 2) and a 3 × 2 table with a header row, queried through AXUIElement:

  • before: role Heading, role description "Heading", no level; table with no AXRows or counts;
  • after: role AXHeading, description "heading", AXHeadingLevel 1, 2, 1, 2; AXRows holding exactly the 3 rows, AXRowCount 3, AXColumnCount 2, each row's AXIndex, each cell's row and column range, and AXColumnHeaderUIElements equal to the two header cells;

cargo fmt --check, cargo clippy -p accesskit_macos --all-targets -- -D warnings and cargo test -p accesskit_macos pass. The adapter has no unit tests to extend; I have not built with Rust 1.87 locally, and nothing here uses newer language or library features. VoiceOver itself has not yet been run against this build.

Headings now use the AXHeading role (NSAccessibilityHeadingRole, macOS 26)
instead of the non-standard "Heading" string, and expose their level both as
AXHeadingLevel (1-based) and as AXValue, as WebKit and Chromium do for older
releases.

Tables, grids and tree grids now expose AXRows (their rows, including rows
inside row groups), AXRowCount, AXColumnCount and
AXColumnHeaderUIElements; rows expose AXIndex; cells expose
AXRowIndexRange and AXColumnIndexRange. Counts and indices come from the
provider. When the provider gives none, AXRowCount falls back to the
number of rows exposed and every other structural attribute is withheld
through isAccessibilitySelectorAllowed: instead of being reported as 0.
@charlesjhlee

Copy link
Copy Markdown

Thanks for this. We have done the table side for a virtualised grid and aligned the heading part with yours (AXHeading, AXHeadingLevel, the level as AXValue before macOS 26; note Node::level is documented as zero-based, so we expose level + 1). Our macOS patch in https://gist.github.com/charlesjhlee/7c608375a2df156c88d33b92d655e055 adds, on the consumer helpers from #10: accessibilityCellForColumn:row:, column and row header elements for the table and each cell, index ranges, selected and visible cells, custom actions (NSAccessibilityCustomAction), AXRowCountChanged and AXSelectedCellsChanged, and the logical size of a virtualised table: VoiceOver sizes a table by its AXRows array, so accessibilityArrayAttributeCount: answers AXRows with the logical count, and AXARIARowCount/ AXARIARowIndex follow Core-AAM. With it VoiceOver says "column 1, row 4000001" and "6 columns, 10,000,000 rows" on a 10,000,000-row grid and moves by row and column. Glad to rebase onto your change once it lands, or to help with it, whichever you prefer.

@PanicIsReal

Copy link
Copy Markdown

Here is a VoiceOver result for the heading part, since the description says VoiceOver has not been run against this yet.

We made the same two heading changes as this PR as a local patch on accesskit_macos 0.26.3: the role AXHeading, and the level as AXValue. We did not add AXHeadingLevel. We ran it on macOS 27.0.1 with VoiceOver:

  • Before: VO-Cmd-H said "Heading not found", and the AX tree showed role="Heading" with no value.
  • After: VO-Cmd-H and previous-heading reached every heading. They said "heading level 1, Computers", then "heading level 2, Local", and so on. VO-Left and VO-Right also landed on the headings.

Our app sets one-based levels, so AXValue matched the level VoiceOver spoke. With the zero-based Node::level noted above, an app that follows the documentation needs the + 1.

We have not tested the table part of this PR. We found the heading problem while testing RDX, a remote-desktop app whose new interface is built on GPUI (Zed's UI framework, which drives AccessKit).


Written with the help of an AI assistant from our test notes. The speech quoted came from VoiceOver.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants