feat(a11y): add keyboard navigation to sidebar page tree (#1150)

Implement WAI-ARIA Treeview keyboard navigation pattern for the sidebar
page tree. Arrow keys move focus between visible items, ArrowRight/Left
expand/collapse parents, Enter navigates, Home/End jump to first/last.

Uses roving tabindex: only the focused item has tabindex=0, all others
have tabindex=-1. Focus ring uses ring-1 ring-accent.

Added getVisibleItems and findParentNode utilities to page-tree.ts.

Co-authored-by: Ona <no-reply@ona.com>

Author: sw-factory-automations

.agents/conventions.md

@@ -2025,6 +2025,28 @@ submission or validation failure.
 on all elements. Do not add CSS transitions or animations without verifying they
 respect this rule. Tailwind's `animate-*` utilities are covered automatically.
 
+### Keyboard navigation — roving tabindex for composite widgets
+
+Composite widgets (`role="tree"`, `role="listbox"`, `role="toolbar"`) use the
+roving tabindex pattern so the widget is a single Tab stop. Only the currently
+focused item has `tabindex="0"`; all others have `tabindex="-1"`.
+
+Implementation pattern (see `page-tree.tsx` for a full example):
+
+1. **State**: maintain `focusedId` in the container component.
+2. **tabbableId**: compute which item gets `tabindex="0"` — the `focusedId` if set,
+   otherwise the first visible item (so the widget is reachable via Tab).
+3. **onKeyDown** on the container: handle Arrow keys, Home, End, Enter.
+   Call `setFocusedId(id)` then `element.focus()` to move focus.
+4. **onFocus** on the container (event delegation): sync `focusedId` when an item
+   receives focus via click or programmatic `.focus()`. Use `instanceof HTMLElement`
+   guard — never cast `e.target as HTMLElement`.
+5. **Focus ring**: apply `ring-1 ring-accent outline-none` on the focused item.
+6. **Child items**: receive `focusedId` (for focus ring) and `tabbableId` (for
+   tabIndex) as props. Inner interactive elements (buttons, links) use `tabIndex={-1}`.
+
+Reference: [WAI-ARIA Treeview pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/).
+
 ### axe-core audit
 
 `e2e/accessibility.spec.ts` runs axe-core on key pages (sign-in, workspace home,

.agents/quality.md

@@ -17,7 +17,7 @@ Tracks code quality per domain. Updated by automations as a side effect of featu
 | Infrastructure | A | Sentry (client + server + edge), proxy with session refresh, health endpoint with tests (9 tests), PWA manifest, global error boundary, Supabase clients (browser + server + proxy). JetBrains Mono font correctly configured. Dark-only oklch theme tokens. Migration validation tests (33 tests). API route error-handling consistency tests (6 tests). |
 | Auth | A | Sign-in, sign-up, invite accept pages. OAuth sign-in with GitHub and Google fully functional. Auth guard in app layout with redirect. Error boundaries on all auth routes (5 error.tsx files, 22 tests). Loading state for invite page. Typography regression test (2 tests). Sign-in unit tests (10 tests): form validation, error handling, redirect logic, loading state. Sign-up unit tests (11 tests): form validation, error handling, redirect logic, loading state. Auth callback route tests (7 tests). Root page tests (4 tests). OAuth buttons unit tests (10 tests). E2E spec covers form rendering, redirect, and sign-in flow (8 tests). |
 | Workspaces | A | Workspace home, settings (name/slug/delete), workspace switcher with create dialog. Slug generation utility with unit tests (12 tests). Settings form unit tests (17 tests): validation, save, slug sanitization, delete confirmation flow, error handling. Create workspace dialog unit tests (5 tests). E2E specs cover workspace creation (3 tests), workspace settings (3 tests), and workspace limit enforcement (2 tests). Max 3 workspace limit enforced via DB trigger. |
-| Pages | A | Page view with title + editor, page tree with CRUD + drag-and-drop + nest/unnest. Page menu with export/import markdown. Page icon picker with emoji support. Cover images, backlinks, version history, favorites, trash/soft-delete, page duplication, inline page link search. Keyboard shortcuts for duplicate (⌘D) and export (⌘⇧E). Tree logic extracted to `src/lib/page-tree.ts` with 37 unit tests covering build, reorder, nest, unnest, and drop computation. Page tree actions hook tests (35 tests): create, create-database, duplicate (regular + database), delete with descendant cleanup, move up/down, nest/unnest, toggle favorite with optimistic updates and error rollback. Page tree keyboard shortcut tests (5 tests). Page icon design spec tests (1 test). Page visit error handling tests (2 tests). Persisted tree expansion tests (9 tests). 12 E2E specs: page CRUD (5), sidebar drag (2), page icon (4), page cover (5), page duplicate (4), favorites (7), trash (7), version history (5), page link search (4), page shortcuts (4), backlinks (1), title advance (3) — 51 tests total. |
+| Pages | A | Page view with title + editor, page tree with CRUD + drag-and-drop + nest/unnest + keyboard navigation (WAI-ARIA Treeview pattern with roving tabindex). Page menu with export/import markdown. Page icon picker with emoji support. Cover images, backlinks, version history, favorites, trash/soft-delete, page duplication, inline page link search. Keyboard shortcuts for duplicate (⌘D) and export (⌘⇧E). Tree logic extracted to `src/lib/page-tree.ts` with 46 unit tests covering build, reorder, nest, unnest, drop computation, visible item traversal, and parent lookup. Page tree actions hook tests (35 tests): create, create-database, duplicate (regular + database), delete with descendant cleanup, move up/down, nest/unnest, toggle favorite with optimistic updates and error rollback. Page tree keyboard shortcut tests (5 tests). Page icon design spec tests (1 test). Page visit error handling tests (2 tests). Persisted tree expansion tests (9 tests). 13 E2E specs: page CRUD (5), sidebar drag (2), sidebar keyboard nav (10), page icon (4), page cover (5), page duplicate (4), favorites (7), trash (7), version history (5), page link search (4), page shortcuts (4), backlinks (1), title advance (3) — 61 tests total. |
 | Editor | A | Full Lexical editor: slash commands, floating toolbar (with font family selector), floating link editor, drag-and-drop blocks, code highlighting, image upload, clipboard image paste, callouts, collapsible/toggle blocks, table support. Markdown import/export with shortcuts. Word count and reading time utility (18 tests). 18 unit test files (162 tests): theme mapping (9), markdown utils (8), design spec compliance (11), Node.contains safety (1), Lexical dispatch safety (1), collapsible toggle (12), callout node (5), image plugin (6), markdown shortcuts (12), emoji picker design spec (7), floating image toolbar (21), image node (19), word count (18), auto-link plugin (12), table serialization (6), save error handling (5), version save error handling (3), save debounce (6). 16 E2E specs (editor-auto-link, editor-auto-save, editor-callout-collapsible, editor-code-paste, editor-drag, editor-focus-mode, editor-font-family, editor-image-paste, editor-image-upload, editor-link, editor-list-indent, editor-markdown-shortcuts, editor-slash-commands, editor-table, editor-toolbar, editor-turn-into — 64 tests total). Auto-save with debounce. Sentry error capture on save failures and image uploads. |
 | Search | A | Full-text search via PostgreSQL tsvector + tsquery. API route with integration tests (14 tests) including transient network retry regression tests. Sidebar search component with unit tests (12 tests). Sentry error capture. E2E spec covers search flow (`e2e/search.spec.ts`, 5 tests). |
 | Import/Export | A | Markdown export (download .md) and import (parse .md, create page) via page menu and workspace home. Shared `useMarkdownImport` hook. Markdown utils with unit tests (8 tests). E2E specs: import-export flow plus edge cases (`e2e/import-export.spec.ts`, 7 tests), workspace home import (`e2e/workspace-home-import.spec.ts`, 3 tests) — 10 E2E tests total. |
@@ -33,16 +33,16 @@ Tracks code quality per domain. Updated by automations as a side effect of featu
 
 | Category | Files | Tests |
 |---|---|---|
-| Unit/Integration (Vitest) | 144 | 1962 |
-| E2E (Playwright) | 85 | 415 |
-| **Total** | **229** | **2377** |
+| Unit/Integration (Vitest) | 144 | 1971 |
+| E2E (Playwright) | 86 | 425 |
+| **Total** | **230** | **2396** |
 
 ### Test files by domain
 
 - **Auth**: `sign-in/page.test.tsx` (10 tests), `sign-in/error.test.ts` (4 tests), `sign-up/page.test.tsx` (11 tests), `sign-up/error.test.ts` (4 tests), `forgot-password/error.test.ts` (4 tests), `reset-password/error.test.ts` (4 tests), `invite/[token]/error.test.ts` (6 tests), `auth-typography.test.ts` (2 tests), `callback/route.test.ts` (7 tests), `page.test.tsx` (4 tests), `oauth-buttons.test.tsx` (10 tests), `e2e/auth.spec.ts` (8 tests)
 - **Workspaces**: `workspace.test.ts` (12 tests), `workspace-settings-form.test.tsx` (17 tests), `create-workspace-dialog.test.tsx` (5 tests), `e2e/workspace.spec.ts` (3 tests), `e2e/workspace-settings.spec.ts` (3 tests), `e2e/workspace-limit.spec.ts` (2 tests)
 - **Editor**: `theme.test.ts` (9), `markdown-utils.test.ts` (8), `design-spec-compliance.test.ts` (11), `node-contains-safety.test.ts` (1), `lexical-dispatch-safety.test.ts` (1), `callout-node.test.ts` (5), `collapsible-toggle.test.ts` (12), `image-plugin.test.ts` (6), `markdown-shortcuts.test.ts` (12), `emoji-picker-design-spec.test.ts` (7), `floating-image-toolbar.test.ts` (21), `image-node.test.ts` (19), `word-count.test.ts` (18), `auto-link-plugin.test.ts` (12), `table-serialization.test.ts` (6), `save-error-handling.test.ts` (5), `version-save-error-handling.test.ts` (3), `save-debounce.test.ts` (6), `e2e/editor-auto-link.spec.ts` (5), `e2e/editor-auto-save.spec.ts` (2), `e2e/editor-callout-collapsible.spec.ts` (3), `e2e/editor-code-paste.spec.ts` (2), `e2e/editor-drag.spec.ts` (4), `e2e/editor-focus-mode.spec.ts` (5), `e2e/editor-font-family.spec.ts` (5), `e2e/editor-image-upload.spec.ts` (2), `e2e/editor-image-paste.spec.ts` (2), `e2e/editor-link.spec.ts` (3), `e2e/editor-list-indent.spec.ts` (3), `e2e/editor-markdown-shortcuts.spec.ts` (4), `e2e/editor-slash-commands.spec.ts` (6), `e2e/editor-table.spec.ts` (8), `e2e/editor-toolbar.spec.ts` (4), `e2e/editor-turn-into.spec.ts` (6)
-- **Pages**: `page-tree.test.ts` (37 tests), `use-page-tree-actions.test.ts` (35 tests), `page-tree-shortcut.test.tsx` (5 tests), `page-icon-design-spec.test.ts` (1 test), `page-visit.test.ts` (2 tests), `use-persisted-expanded.test.ts` (9 tests), `e2e/page-crud.spec.ts` (5), `e2e/page-icon.spec.ts` (4), `e2e/sidebar-drag.spec.ts` (2), `e2e/page-cover.spec.ts` (5), `e2e/page-duplicate.spec.ts` (4), `e2e/favorites.spec.ts` (7), `e2e/trash.spec.ts` (7), `e2e/version-history.spec.ts` (5), `e2e/page-link-search.spec.ts` (4), `e2e/page-shortcuts.spec.ts` (4), `e2e/backlinks.spec.ts` (1), `e2e/title-advance.spec.ts` (3)
+- **Pages**: `page-tree.test.ts` (46 tests), `use-page-tree-actions.test.ts` (35 tests), `page-tree-shortcut.test.tsx` (5 tests), `page-icon-design-spec.test.ts` (1 test), `page-visit.test.ts` (2 tests), `use-persisted-expanded.test.ts` (9 tests), `e2e/page-crud.spec.ts` (5), `e2e/page-icon.spec.ts` (4), `e2e/sidebar-drag.spec.ts` (2), `e2e/sidebar-keyboard-nav.spec.ts` (10), `e2e/page-cover.spec.ts` (5), `e2e/page-duplicate.spec.ts` (4), `e2e/favorites.spec.ts` (7), `e2e/trash.spec.ts` (7), `e2e/version-history.spec.ts` (5), `e2e/page-link-search.spec.ts` (4), `e2e/page-shortcuts.spec.ts` (4), `e2e/backlinks.spec.ts` (1), `e2e/title-advance.spec.ts` (3)
 - **Search**: `search/route.test.ts` (14 tests), `page-search.test.tsx` (12 tests), `e2e/search.spec.ts` (5 tests)
 - **Import/Export**: `e2e/import-export.spec.ts` (7 tests), `e2e/workspace-home-import.spec.ts` (3 tests)
 - **Database**: `database.test.ts` (55 tests), `column-helpers.test.ts` (65 tests), `database-duplicate.test.ts` (11 tests), `database-filters.test.ts` (54 tests), `formula.test.ts` (80 tests), `csv-export.test.ts` (38 tests), `property-type-picker.test.ts` (14 tests), `property-type-picker-completeness.test.ts` (5 tests), `table-view-value-format.test.ts` (33 tests), `table-defaults.test.ts` (27 tests), `table-cell.test.tsx` (40 tests), `database-width.test.ts` (3 tests), `database-view-client.test.tsx` (6 tests), `filter-bar.test.tsx` (20 tests), `filter-value-editor.test.tsx` (34 tests), `sort-menu.test.tsx` (19 tests), `rename-property-dialog.test.tsx` (14 tests), `row-properties-header.test.tsx` (17 tests), `view-tabs.test.tsx` (24 tests), `use-database-filters.test.ts` (18 tests), `use-database-properties.test.ts` (20 tests), `use-database-rows.test.ts` (23 tests), `use-database-views.test.ts` (24 tests), `checkbox.test.tsx` (8 tests), `computed.test.tsx` (15 tests), `date.test.tsx` (12 tests), `email.test.tsx` (8 tests), `files.test.tsx` (11 tests), `formula.test.tsx` (6 tests), `multi-select.test.tsx` (10 tests), `number.test.tsx` (14 tests), `person.test.tsx` (9 tests), `phone.test.tsx` (10 tests), `relation.test.tsx` (12 tests), `select-dropdown.test.tsx` (32 tests), `select.test.tsx` (11 tests), `status.test.tsx` (14 tests), `text.test.tsx` (10 tests), `url.test.tsx` (10 tests), `board-view-helpers.test.ts` (18 tests), `board-view.test.tsx` (13 tests), `calendar-keyboard.test.ts` (25 tests), `calendar-view-helpers.test.ts` (35 tests), `calendar-view.test.tsx` (15 tests), `database-empty-state.test.tsx` (14 tests), `gallery-view.test.tsx` (17 tests), `list-keyboard.test.ts` (14 tests), `list-view.test.tsx` (22 tests), `row-count-announcer.test.tsx` (7 tests), `row-count-status-bar.test.tsx` (5 tests), `formula-design-spec.test.ts` (2 tests), `person-skeleton-design-spec.test.ts` (1 test), `calendar-view-design-spec.test.ts` (1 test), `gallery-view-design-spec.test.ts` (3 tests), `filter-sort-toolbar-design-spec.test.ts` (2 tests), `e2e/database-crud.spec.ts` (11 tests), `e2e/database-duplicate.spec.ts` (2), `e2e/database-duplicate-row.spec.ts` (3), `e2e/database-add-property-types.spec.ts` (10), `e2e/database-board.spec.ts` (4), `e2e/database-board-keyboard.spec.ts` (6), `e2e/database-calendar.spec.ts` (4), `e2e/database-calendar-keyboard.spec.ts` (7), `e2e/database-column-reorder.spec.ts` (3), `e2e/database-column-resize.spec.ts` (4), `e2e/database-csv-export.spec.ts` (3), `e2e/database-error-recovery.spec.ts` (4), `e2e/database-files.spec.ts` (4), `e2e/database-filter-keyboard.spec.ts` (6), `e2e/database-filter-types.spec.ts` (4), `e2e/database-formula.spec.ts` (3), `e2e/database-gallery.spec.ts` (4), `e2e/database-gallery-keyboard.spec.ts` (5), `e2e/database-inline.spec.ts` (4), `e2e/database-list.spec.ts` (4), `e2e/database-list-keyboard.spec.ts` (6), `e2e/database-person.spec.ts` (5), `e2e/database-relation.spec.ts` (3), `e2e/database-row-page.spec.ts` (7), `e2e/database-search.spec.ts` (2), `e2e/database-select-options.spec.ts` (6), `e2e/database-table-editor-portal.spec.ts` (4), `e2e/database-table-keyboard.spec.ts` (6), `e2e/database-view-config.spec.ts` (4), `e2e/database-views.spec.ts` (10), `use-row-selection.test.ts` (10 tests), `e2e/database-bulk-select.spec.ts` (7)
@@ -164,5 +164,6 @@ Tracks code quality per domain. Updated by automations as a side effect of featu
 | 2026-05-18 | Fixed 11 E2E test failures (#1142). Fixed account-deletion tests (hydration timing with retry pattern), database-bulk-select tests (optimistic row ID race condition, aria-checked assertions), database-column-reorder tests (checkbox column offset in getColumnOrder), database-csv-export tests (gridcell count mismatch from checkbox column). Added `data-row-id` attribute to table rows for temp-ID detection. Fixed DeleteAccountSection component to avoid AlertDialogTrigger + controlled open pattern. Updated visual regression baselines. Test totals unchanged: 144 Vitest files (1953 tests), 84 E2E specs (412 tests). |
 | 2026-05-18 | Title Enter/Tab focuses editor (#1137). Added `onAdvance` callback to `PageTitle`, wired in `PageViewClient` to focus Lexical editor on Enter/Tab. Added 1 new E2E spec: `e2e/title-advance.spec.ts` (3 tests). Added `WithAdvance` Storybook story and visual regression baseline. Test totals: 144 Vitest files (1953 tests), 85 E2E specs (415 tests). |
 | 2026-05-18 | Add aria-live region to editor save status indicator (#1138). Added sr-only `role="status"` span to editor save status div so screen readers announce terminal states (Saved, Save failed) without noisy Saving... announcements. No new test files. Test totals: 144 Vitest files (1962 tests), 85 E2E specs (415 tests). |
+| 2026-05-19 | Add keyboard navigation to sidebar page tree (#1150). Added WAI-ARIA Treeview keyboard navigation (ArrowUp/Down, ArrowLeft/Right expand/collapse, Enter, Home, End) with roving tabindex pattern. Added `getVisibleItems` and `findParentNode` to `page-tree.ts`. Updated `page-tree.test.ts` (37→46): 9 new tests for visible item traversal and parent lookup. Added 1 new E2E spec: `e2e/sidebar-keyboard-nav.spec.ts` (10 tests). Test totals: 144 Vitest files (1971 tests), 86 E2E specs (425 tests). |