Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
#!/usr/bin/env node
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
// bento/dash grid ACCESSIBILITY rig — the semantics a screen reader reads.
//
// node scripts/test-dash-a11y.ts (Node ≥ 23.6 strips types natively)
//
// WHAT THIS PROVES. Before this, grid.ts contained not one `role` and not one
// `aria-` attribute, and after clicking a cell `document.activeElement` was
// BODY. The keyboard model was complete and good the whole time, which is what
// makes the gap fixable — and also what makes it invisible, because everything
// works when you can see it. Every check below guards a failure that is silent
// to a sighted developer:
//
// 1. THE ROW NUMBER A VIRTUALISED GRID REPORTS. This is the one that matters.
// About forty rows of a 5,000-row view exist in the DOM, so a row's
// position among its SIBLINGS is meaningless — `aria-rowindex` has to be
// its position in the whole view. Get it wrong and a screen reader
// confidently announces "row 3 of 40" in a five-thousand-row sheet, which
// is worse than announcing nothing, because it is trusted. The same
// applies across: a spreadsheet windows its COLUMNS too, so a painted
// column's `aria-colindex` must be its position on the sheet and not its
// offset in the painted strip.
// 2. AN UNBOUNDED SHEET WITH A FINITE COUNT. The spreadsheet kind's extent is
// a frontier that grows with the cursor and the window. Publishing it as
// `aria-rowcount` would announce a size that is both wrong and stale on
// the next scroll; ARIA's answer for "not known" is -1, and that is the
// honest one.
// 3. FOCUS THAT GOES NOWHERE. Every paint replaces the body's innerHTML, so
// the focused cell is destroyed roughly forty times a second while an
// arrow key is held. Without restoration, focus lands on BODY on the first
// keystroke, the roving tabindex has no owner, and the grid stops being
// something a keyboard user is INSIDE. The check is on
// `document.activeElement` after a click and after a move, because that is
// the exact thing the audit measured.
// 4. MORE THAN ONE TAB STOP. A grid where every cell is focusable takes three
// hundred Tab presses to escape, and Tab already means "next cell" here.
// Exactly one element in the grid may carry `tabindex="0"`.
// 5. A SORT NOBODY IS TOLD ABOUT. The ▲ in the header is the only sort
// indicator there was. `aria-sort` has to track `this.sorts` — including
// the second key of a shift-click — and unsorted-but-sortable columns must
// say `none` rather than omit the attribute, which would claim they cannot
// be sorted at all.
// 6. A CHATTY LIVE REGION. The view status ("4 of 8 rows · Sorted by Value ▼")
// has to reach assistive technology, and the lazy way is `aria-live`,
// which would then interrupt the reader on every sort, filter, sheet
// switch and structural edit. It is an `aria-describedby` target instead,
// and this rig fails if anything in the grid ever grows an `aria-live`.
//
// The DOM is `scripts/lib/dash-dom.ts` — a parser and a node tree, not a
// browser. It cannot tell you whether the grid LOOKS right; it can tell you
// exactly what markup the grid emitted, which is all an accessibility tree is
// built from.
import { registerHooks } from 'node:module'
// grid.ts reaches find.ts, which imports its own stylesheet — Vite's job, not
// Node's. The same stub every dash rig with a UI import uses.
registerHooks({
load(url, context, next) {
if (url.endsWith('.css')) {
return { format: 'module', source: 'export {}', shortCircuit: true }
}
return next(url, context)
},
})
const { installDom, mousedown } = await import('./lib/dash-dom.ts')
type El = import('./lib/dash-dom.ts').El
const dom = installDom()
const { parseDoc } = await import('../dash/src/model.ts')
const { Store } = await import('../dash/src/store.ts')
const { Grid, ariaRowIndex, ariaColIndex, ariaRowCount, ariaColCount, ARIA_UNKNOWN } =
await import('../dash/src/grid.ts')
type DashDoc = import('../dash/src/model.ts').DashDoc
let failures = 0
let checks = 0
function ok(cond: boolean, msg: string) {
checks++
if (!cond) { failures++; console.log(` FAIL ${msg}`) }
else console.log(` ok ${msg}`)
}
// --------------------------------------------------------------- fixtures
/** A dataset of `n` rows — big enough that the window is a small fraction. */
function dataset(n: number): DashDoc {
const r = parseDoc(JSON.stringify({
format: 'bento/dash', version: 1, policy: 'bento-dash-1', docId: 'd', title: 't',
sheets: [{
id: 's1', name: 'Sales', kind: 'table',
columns: [
{ id: 'region', name: 'Region', type: 'text' },
{ id: 'value', name: 'Value', type: 'number' },
],
rids: [[1, n]],
data: {
region: { enc: 'raw', v: Array.from({ length: n }, (_, i) => `R${i % 4}`) },
value: { enc: 'raw', v: Array.from({ length: n }, (_, i) => i) },
},
}],
}))
if (!r.ok) throw new Error(`fixture: ${JSON.stringify(r.findings)}`)
return r.doc
}
function spreadsheet(cells: Record<string, unknown>): DashDoc {
const r = parseDoc(JSON.stringify({
format: 'bento/dash', version: 1, policy: 'bento-dash-1', docId: 'd', title: 't',
sheets: [{ id: 'cv1', name: 'Scratch', kind: 'canvas', cells }],
}))
if (!r.ok) throw new Error(`fixture: ${JSON.stringify(r.findings)}`)
return r.doc
}
/** Mount a grid into a fresh host with a viewport of a stated size. */
function mount(doc: DashDoc, sheetId: string, view = { h: 600, w: 900 }) {
const host = dom.doc.createElement('div')
dom.doc.body.appendChild(host)
const store = new Store(doc)
const grid = new Grid({ el: host as never, store, sheetId })
const scroll = host.querySelector('.dg-scroll')!
scroll.clientHeight = view.h
scroll.clientWidth = view.w
grid.paint()
return { host, store, grid, scroll }
}
const rowsOf = (host: El): El[] => host.querySelectorAll('.dg-sizer .dg-row')
const ariaRow = (el: El): number => Number(el.getAttribute('aria-rowindex'))
const gridOf = (host: El): El => host.querySelector('.dg-table')!
// --------------------------------------------------- 1. the coordinate maths
console.log('\nthe aria coordinate system')
ok(ariaRowIndex(0) === 2 && ariaColIndex(0) === 2,
'both axes are 1-based and both count the furniture: the header is row 1 and ' +
'the row-number gutter is column 1, so the first data cell is (2, 2)')
ok(ariaRowCount(8, false, false) === 9,
'a plain 8-row view is 8 rows plus the header')
ok(ariaRowCount(8, true, true) === 11,
'the appender and the totals row are rows too — they carry an aria-rowindex, ' +
'so a count that omitted them would be SMALLER than the largest index in the ' +
'grid, which is the one arithmetic error a reader cannot recover from')
ok(ariaColCount(2) === 3, 'the gutter is a column, so two data columns make three')
// ------------------------------------- 2. THE HEADLINE: indices under a window
console.log('\nthe row index describes the view, not the DOM window')
{
const N = 5000
const { host, grid, scroll } = mount(dataset(N), 's1')
scroll.scrollTop = 3000 * 20 // ROW_H is 20; park the window at row 3000
grid.paint()
const rows = rowsOf(host)
ok(rows.length > 0 && rows.length < 100,
`the window is small — ${rows.length} of ${N} rows are in the DOM, which is ` +
'the entire reason aria-rowindex has to be stated explicitly')
// The first painted row is `data-row` in view coordinates; aria has to be
// that number plus the header, and NOT its position among its siblings.
const first = rows[0]
const viewRow = Number(first.getAttribute('data-row'))
ok(viewRow > 2900,
'the painted window really is deep in the sheet (guarding the guard: a ' +
'window stuck at row 0 would pass the next check for the wrong reason)')
ok(ariaRow(first) === ariaRowIndex(viewRow),
`the first painted row reports aria-rowindex ${ariaRow(first)} for view row ` +
`${viewRow} — its place in the FULL view`)
ok(ariaRow(first) !== 2,
'and it is emphatically not 2, which is what indexing by DOM position gives')
ok(rows.every((r, i) => ariaRow(r) === ariaRow(rows[0]) + i),
'the indices run contiguously through the window, so stepping down a row ' +
'steps the announced number by one')
ok(Number(gridOf(host).getAttribute('aria-rowcount')) === ariaRowCount(N, true, true),
`aria-rowcount is ${N} rows + header + appender + totals, not the ${rows.length} ` +
'rows that happen to exist — "40 rows" in a 5,000-row sheet is a confident lie')
ok(Number(gridOf(host).getAttribute('aria-colcount')) === 3,
'aria-colcount counts the gutter and the two columns')
}
// ------------------------------------------- 3. the same thing, sideways
console.log('\nand the column index describes the sheet, not the painted strip')
{
// A spreadsheet windows COLUMNS as well as rows — it has 16,384 of them —
// so the horizontal case is a real one and not a symmetry argument.
const { host, grid, scroll } = mount(spreadsheet({ A1: { v: 1 }, BA2: { v: 2 } }), 'cv1')
scroll.scrollLeft = 40 * 100 // CANVAS_COL_W is 100; scroll past column AN
grid.paint()
const head = host.querySelectorAll('.dg-head-row .dg-h')
ok(head.length > 0 && head.length < 60, `${head.length} column headers painted, not 16,384`)
const ci = Number(head[0].getAttribute('data-ci'))
ok(ci > 30, 'the painted strip really does start well to the right')
ok(Number(head[0].getAttribute('aria-colindex')) === ariaColIndex(ci),
'the leftmost painted column reports its position on the SHEET, not its ' +
'position in the strip — the DOM to its left is one spacer div')
const cells = host.querySelectorAll('.dg-sizer .dg-row .dg-cell[data-ci]')
ok(cells.length > 0 &&
cells.every((c) => Number(c.getAttribute('aria-colindex')) === ariaColIndex(Number(c.getAttribute('data-ci')))),
'and every painted cell agrees with its own data-ci')
}
// ----------------------------------------- 4. an unbounded sheet says so
console.log('\na spreadsheet reports its size as unknown')
{
const { host } = mount(spreadsheet({ A1: { v: 1 } }), 'cv1')
ok(Number(gridOf(host).getAttribute('aria-rowcount')) === ARIA_UNKNOWN &&
Number(gridOf(host).getAttribute('aria-colcount')) === ARIA_UNKNOWN,
'aria-rowcount and aria-colcount are -1, which is ARIA\'s "the total is not ' +
'known" — publishing the frontier instead would announce a size that grows ' +
'when the reader scrolls')
ok(host.querySelectorAll('.dg-head-row .dg-h[aria-sort]').length === 0,
'and its columns carry no aria-sort at all: a spreadsheet column cannot be ' +
'sorted, and "none" would claim it can be but is not')
}
// --------------------------------------------------- 5. the structure itself
console.log('\nthe grid is a grid')
{
const { host } = mount(dataset(12), 's1')
ok(gridOf(host).getAttribute('role') === 'grid', '.dg-table is role="grid"')
ok(host.querySelector('.dg-head-row')!.getAttribute('role') === 'row' &&
host.querySelector('.dg-head-row')!.getAttribute('aria-rowindex') === '1',
'the header is row 1')
ok(host.querySelector('.dg-sizer')!.getAttribute('role') === 'rowgroup',
'the sizer is a rowgroup — it sits BETWEEN the grid and its rows, and a ' +
'grid whose children are plain divs has no rows at all as far as a screen ' +
'reader is concerned')
const body = rowsOf(host)
ok(body.every((r) => r.getAttribute('role') === 'row'), 'every body row is a row')
ok(body.every((r) => r.querySelector('.dg-gutter')!.getAttribute('role') === 'rowheader' &&
r.querySelector('.dg-gutter')!.getAttribute('aria-colindex') === '1'),
'the row number is the row\'s header, at column 1')
ok(host.querySelectorAll('.dg-sizer .dg-cell[data-ci]')
.every((c) => c.getAttribute('role') === 'gridcell'),
'every data cell is a gridcell')
ok(host.querySelectorAll('.dg-head-row .dg-h')
.every((c) => c.getAttribute('role') === 'columnheader'),
'every column header is a columnheader')
ok(host.querySelector('.dg-corner')!.getAttribute('role') === 'columnheader' &&
host.querySelector('.dg-corner')!.getAttribute('aria-colindex') === '1',
'the corner box is the gutter column\'s header')
const foot = host.querySelector('.dg-foot-row')!
ok(foot.getAttribute('role') === 'row' &&
Number(foot.getAttribute('aria-rowindex')) > Number(body[body.length - 1].getAttribute('aria-rowindex')),
'the totals row is a row, and it comes after the last body row')
ok(gridOf(host).getAttribute('aria-label') === 'Sales',
'the grid is named by its sheet — data, not a UI string, so nothing to translate')
}
// ------------------------------------------------------- 6. sort and filter
console.log('\nsorted and filtered state is announced')
{
const { host, grid } = mount(dataset(12), 's1')
const headOf = (col: string): El =>
host.querySelector(`.dg-head-row .dg-h[data-col="${col}"]`)!
ok(headOf('value').getAttribute('aria-sort') === 'none' &&
headOf('region').getAttribute('aria-sort') === 'none',
'an unsorted column says "none" — SORTABLE but not sorted. Omitting the ' +
'attribute would say the column cannot be sorted')
grid.addSort('value', 'asc')
grid.paint()
ok(headOf('value').getAttribute('aria-sort') === 'ascending',
'sorting ascending says so')
ok(headOf('region').getAttribute('aria-sort') === 'none',
'and the other column is untouched')
grid.addSort('region', 'desc')
grid.paint()
ok(headOf('value').getAttribute('aria-sort') === 'ascending' &&
headOf('region').getAttribute('aria-sort') === 'descending',
'a shift-click\'s SECOND key is announced too — aria-sort is read off the ' +
'whole `sorts` list, not off the single `sort` the ▲ is drawn from')
grid.clearView()
grid.setFilter('region', { col: 'region', pred: { op: 'isOneOf', set: new Set(['R0']) } })
grid.paint()
const label = headOf('region').getAttribute('aria-label') ?? ''
ok(label.includes('Region') && label !== 'Region',
`the filtered column's accessible NAME says it is filtered ("${label}") — ARIA ` +
'has no attribute for it, and without this the one column hiding rows ' +
'sounds exactly like the ones that are not')
ok((headOf('value').getAttribute('aria-label') ?? null) === null,
'and an unfiltered column keeps its plain text name')
}
// ------------------------------------------------------- 7. the description
console.log('\nthe view status reaches assistive technology, quietly')
{
const { host, grid } = mount(dataset(12), 's1')
const id = gridOf(host).getAttribute('aria-describedby')
ok(!!id, 'the grid is aria-describedby something')
const desc = host.querySelector(`#${id}`)
ok(!!desc, 'and that something exists in the same subtree')
grid.setFilter('value', { col: 'value', pred: { op: 'greater', v: 5 } })
grid.paint()
ok((desc!.textContent ?? '').includes('of 12 rows'),
`the filtered row count is in the description ("${desc!.textContent}") — a ` +
'sighted reader gets it from the status bar and a screen-reader user got it ' +
'from nowhere at all')
// Scoped to the grid and its description. The find bar's result count IS a
// polite live region and should be — it answers a question the reader just
// asked, once, on demand. The view status is not that: it changes on its own.
ok(gridOf(host).querySelectorAll('[aria-live]').length === 0 &&
!desc!.hasAttribute('aria-live'),
'and NOTHING in the grid is a live region. The status changes on every sort, ' +
'filter, sheet switch and structural edit; a polite live region would read ' +
'the row count over the top of whatever the reader was doing. Described, it ' +
'is read on entering the grid and whenever the reader asks')
}
// ----------------------------------------------------- 8. focus and tab stops
console.log('\nfocus is a real thing that lands on a real cell')
{
const { host, grid, scroll } = mount(dataset(40), 's1')
ok(dom.doc.activeElement === dom.doc.body, 'nothing is focused before the click')
const cell = host.querySelector('.dg-row[data-row="3"] .dg-cell[data-ci="1"]')!
mousedown(cell)
const active = dom.doc.activeElement
ok(active !== dom.doc.body,
'after clicking a cell, document.activeElement is NOT body — which is ' +
'exactly what the audit measured, and why the grid was invisible to AT')
ok(active.getAttribute('role') === 'gridcell' &&
active.getAttribute('data-ci') === '1' &&
active.parentElement!.getAttribute('data-row') === '3',
'it is the cell that was clicked, identified by its own coordinates — the ' +
'paint that the click triggers destroys the node, so this is the FRESH one')
const one = (): El[] => host.querySelectorAll('[tabindex="0"]')
ok(one().length === 1 && one()[0] === dom.doc.activeElement,
'exactly one tab stop in the whole grid, and it is the cursor cell (roving ' +
'tabindex). 300 focusable cells is 300 Tab presses to get past the grid')
// Now the case that actually killed it: a repaint.
const moved = grid.handleKey({
key: 'ArrowDown', shiftKey: false, metaKey: false, ctrlKey: false, altKey: false,
preventDefault() {}, stopPropagation() {},
} as never)
ok(moved, 'ArrowDown is still handled — the keyboard model is not regressed')
ok(dom.doc.activeElement !== dom.doc.body,
'and focus SURVIVED the repaint. Every paint replaces the body innerHTML, so ' +
'without restoration the first keystroke drops focus to body and never gets ' +
'it back')
ok(dom.doc.activeElement.parentElement!.getAttribute('data-row') === '4',
'focus followed the cursor down one row rather than staying on a detached node')
ok(host.querySelectorAll('[tabindex="0"]').length === 1,
'and the tab stop moved with it — still exactly one')
// Scroll the cursor clean out of the window. Focus must not fall to BODY.
scroll.scrollTop = 30 * 20
grid.paint()
ok(!host.querySelector('.dg-row[data-row="4"]'),
'the cursor row is no longer painted (guarding the guard)')
ok(dom.doc.activeElement !== dom.doc.body,
'focus falls back to the scroller, never to BODY — a virtualised grid can ' +
'always scroll its cursor out of existence, and dropping the reader out of ' +
'the grid when they scroll is not an option')
ok(host.querySelectorAll('[tabindex="0"]').length === 1,
'and there is still exactly one tab stop, so Tab can get back in')
}
// ---------------------------------------------------------- 9. selected state
console.log('\nselection is a state, not just a colour')
{
const { host, grid } = mount(dataset(12), 's1')
grid.sel.moveTo(2, 0)
grid.sel.extendTo(4, 1)
grid.paint()
const sel = host.querySelectorAll('.dg-sizer .dg-cell[aria-selected="true"]')
ok(sel.length === 6,
`a 3x2 selection reports six aria-selected cells (got ${sel.length}) — the ` +
'tint on screen is invisible to a reader who is not looking at it')
ok(host.querySelectorAll('.dg-sizer .dg-cell[aria-selected="false"]').length > 0,
'and the unselected cells say so explicitly rather than omitting the attribute')
}
console.log(`\n${checks - failures}/${checks} checks passed`)
if (failures) process.exit(1)