Skip to content

feat(dashboard): reach file viewer header path by keyboard, not only hover - #9301

Merged
bolichen97 merged 1 commit into
mainfrom
feat/fileviewer-header-path-a11y-7900
Sep 8, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
feat/fileviewer-header-path-a11y-7900

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Sep 7, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Open a file in the dashboard's right-hand file viewer. The path in the panel
header is a breadcrumb that shows only the last three segments of the path. A
deeply nested file -- for example a monorepo that nests the package name
twice, like .../MyWorkspace/src/PackageName/src/PackageName/index.ts -- shows
just src > PackageName > index.ts. The rest of the path lives in a native title
tooltip on that breadcrumb.

A title tooltip only appears on mouse hover. A keyboard user, or anyone using
a screen reader, has no way to read the full path: the element is not in the tab
order and carries no accessible name. So the one piece of information that
disambiguates two same-named files is reachable by pointer only.

Why it matters

Repos and workspaces are full of same-named files (index.ts, config.json,
AGENTS.md, SKILL.md). When the visible three segments are not enough, a
sighted mouse user hovers and reads the tooltip; a keyboard-only or screen-reader
user is stuck and has to go hunt for the path elsewhere. The header is meant to
tell you which file you are looking at, and for those users it silently does not.

What changed (motivation -> approach -> change)

The goal is to give the full path the same keyboard and screen-reader route it
already has for the pointer, without widening what is shown or adding a new
control.

The header already puts the full path on title. The gap is purely that the
breadcrumb element is a plain, non-focusable container. So the fix keeps title
(the pointer route unchanged) and adds three attributes to the same element:
tabIndex={0} puts it in the tab order, role="group" makes it an addressable
element, and aria-label={filePath} gives it the full path as its accessible
name. A keyboard user can now tab to the breadcrumb and their screen reader reads
the whole path; a focus-visible ring shows where focus landed. A sighted keyboard-only user, who hears no aria-label and to whom a
native title does not open on focus, gets a small readout that prints the full
path below the breadcrumb while it holds focus. This mirrors the
repo's existing focusable read-only regions (CodeBlock.tsx, FileRenderers.tsx),
including the same one-line eslint allowance they use.

The accessible name IS the runtime path -- data, not UI copy -- so no localized
string is added and no locale catalogue is touched. The breadcrumb markup is
factored into a small exported FileHeaderBreadcrumb so the accessibility
contract is unit-testable without mounting the whole panel (which pulls in the
editor tree). Right-click still opens the existing file-path menu.

"Full path" here means the absolute filesystem path. That is the string the
header already renders in its title and in its click-to-copy bar today, so this
change adds a keyboard route to an already-visible value rather than exposing
anything new. This is the local dashboard file viewer; the component does not
render in any shared or exported surface, so the absolute path (which can include
a home-directory name) is not newly disclosed anywhere.

Note the related PR #7935 targets a different surface -- the side-panel tab CHIP
-- and its own description says the header breadcrumb "already carries the full
path". This PR is about that header breadcrumb's keyboard/screen-reader
reachability, so the two do not overlap in behaviour.

Tests

website/src/test/MarkdownPanel.test.tsx -- a new FileHeaderBreadcrumb
accessibility block, three cases:

  • the full path is on title (pointer route), while only the tail three
    segments are visible text;
  • the full path is reachable by keyboard focus, not only pointer: the element is
    in the tab order (tabindex=0), takes focus, and its accessible name (queried
    by getByRole('group', { name: fullPath })) equals the full path;
  • two same-named files in different directories are distinguishable by that
    accessible name.

Proven as a real ratchet: with the three production attributes removed, all three
new cases fail (getByRole('group') finds nothing); with them present, all pass.

Commands run locally, one file at a time:

npx vitest run src/test/MarkdownPanel.test.tsx                                   # 38 passed
npx eslint src/components/MarkdownPanel.tsx src/test/MarkdownPanel.test.tsx      # 0 errors, 0 warnings
node scripts/check-i18n-strings.mjs                                              # OK, no new literals on added lines
node scripts/capture-fileviewer-header-path.mjs <viteBase> temp-screenshots/7900-fileviewer-header-path   # asserts role+name+focus, and that the readout stays within the 320px panel

tsc -b on this host reports 30 errors, all in LexicalComposerInput.tsx /
PasteTokenNode.tsx and all Cannot find module 'lexical'; they are identical on
a pristine origin/main with this change stashed (a missing dev dependency this
host cannot install), so none is introduced here. CI provides the real type-check.

Manual verification

Captured the real component in a header-bar mimic via a Playwright harness in
both themes and both states. The default frame shows the truncation; the focused
frame shows the new keyboard focus ring around the aria-labelled breadcrumb.

Default (dark) -- only the tail three segments are shown:

header path, default, dark

Keyboard focus (dark) -- the breadcrumb is focusable and shows a focus ring; its
accessible name is the full path:

header path, keyboard focus, dark

Light theme (default + focus)

header path, default, light

header path, keyboard focus, light

Narrow panel at 320px (SIDE_PANEL_MIN_W, the narrowest the viewer allows) --
the focus readout is bounded by the panel edge and wraps inside it, so the full
path stays fully readable rather than clipping off the right edge:

header path, keyboard focus, narrow

Diff mode -- the +N/-N badge stays beside the filename (its original position;
the readout is anchored to the header bar, so the header's own layout is
unchanged), at 460px and at the narrowest 320px:

diff mode, panel 460px

diff mode, panel 320px

Screenshots / video

See Manual verification above.

Related Issues

Related a11y follow-up (same defect class on other chips, tracked not fixed here): #9312

Closes #7900

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@chenmingwei23
chenmingwei23 requested review from a team and pepmach September 7, 2026 20:06
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Intent: Give the file viewer header's full path the same keyboard-focus and screen-reader route it already has for pointer hover, so a keyboard-only user can disambiguate same-named files.
Not a goal: Changing what the breadcrumb shows, adding a new control or copy affordance, adding any localized string, or touching the side-panel tab chip (that is #7935's surface).

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 7, 2026
@github-actions

github-actions Bot commented Sep 7, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of 8645246a457099852d09e25f40e8c1f7c59af434 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

All precedents check out — CodeBlock/FileRenderers use the same focusable read-only region pattern, the capture harness and temp-screenshots/ are established conventions with hundreds of prior examples, and the tests genuinely pin the accessibility contract. The design is sound.

Design-Verdict: PASS

A real pointer-only gap closed at the right layer, mirroring the repo's existing focusable-region pattern, with the contract pinned by unit tests.

Suggestions

  • The readout is stated as keyboard-only ("shown only while it holds focus... for a sighted keyboard-only user") but onFocus also fires on mouse click, so pointer users now get a floating box overlaying the panel content on click; gating it on :focus-visible (as the ring already is) would match the stated intent.

[DESIGN-REVIEWED] 8645246

@github-actions

github-actions Bot commented Sep 7, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

Reviewed 8645246a457099852d09e25f40e8c1f7c59af434 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 8645246

Verdict parsed from the review's SHA-scoped output markers for commit 8645246a457099852d09e25f40e8c1f7c59af434.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 8645246a457099852d09e25f40e8c1f7c59af434: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 7, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — ✅ PASS

UX-level review of 8645246a457099852d09e25f40e8c1f7c59af434 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

The change is narrow: the existing breadcrumb becomes keyboard-focusable with a focus ring and a focus-only full-path readout. Reconciling the blind read against the diff: the reader correctly identified the breadcrumb ("the file's name and the folders it lives in"), the focus ring ("the app showing me this part is currently selected, the way things light up when you press Tab"), and the readout ("a pop-up tip telling me the file's full address... since the short trail above can't show it all") — all matching exactly what the diff implements. The "blank rounded square" the reader could not identify is a capture-harness placeholder (<span className="w-[26px] h-[26px] rounded-md bg-bg-hover" /> in fileviewer-header-path.tsx), not product UI in this diff. All states (default/focused, dark/light, 320/460px, diff mode) are screenshotted; the readout wraps inside the 320px panel with no clipping. No persistent element changes form or place (the readout appears on focus and leaves on blur — an overlay, not a swap), so no recording is required.

One genuine data point survives: the reader could not tell whether the truncated trail was "skipping some steps" or the file really sits in duplicate folders — the trail gives no sign it is elided.

UX-Verdict: PASS

Blind reader correctly understood the focus ring and full-path readout unaided; every added state is screenshotted in both themes and widths.

Suggestions

  • In FileHeaderBreadcrumb, prepend a muted "…" crumb when breadcrumbSegments drops leading segments — the blind reader could not tell the trail was elided ("I cannot tell whether… the short trail is just skipping some steps"), and the marker also hints there is more path to discover on hover/focus.

[UX-REVIEWED] 8645246

@github-actions

github-actions Bot commented Sep 7, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 8645246a457099852d09e25f40e8c1f7c59af434 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

FilePathMenu shows only action rows (Open/Reveal/Copy path), never the path string itself, so the new focus readout is not a second spelling of an existing mechanism. All items check out: the eslint-disable/focusable-region pattern has 18 existing sites (CodeBlock.tsx:54, FileRenderers.tsx:495, etc.), the capture harness matches 235 sibling files in website/capture/ and 474 scripts in website/scripts/, and committed screenshots are the documented convention in temp-screenshots/README.md (which explicitly says reviewers should not ask authors to delete them). The sibling defect class is declared and tracked in #9312.

First-Principles-Verdict: PASS

A pointer-only path made keyboard/screen-reader reachable; every item is declared, derived from a browser rule, and matches a counted repo convention.

What this change ships

Intent: let a keyboard or screen-reader user read the file viewer's full path, which today lives only in a hover tooltip. This is a FIX (#7900).

  1. Header breadcrumb is now a tab stop with a focus ring — justified (native title is pointer-only; the defect).
  2. Screen reader announces the full path on focus via aria-label — justified.
  3. Full path prints below the header while the breadcrumb holds focus — justified (declared; sighted keyboard user hears no aria-label, and FilePathMenu never displays the path string — grepped, its items are Open/Reveal/Copy only).
  4. Breadcrumb extracted as exported FileHeaderBreadcrumb — justified (1 product consumer, but mirrors this file's existing test-exported siblings OverflowMenu, breadcrumbSegments).
  5. New capture harness + script — justified (declared; convention: 235 files in website/capture/, 474 in website/scripts/).
  6. Seven committed screenshots under temp-screenshots/7900-… — justified (documented convention, temp-screenshots/README.md; the cleanup workflow owns removal).

Sibling instances of the same title-only defect on other chips are declared and deferred to #9312 with the count of overlap against #7935 addressed in the description, so no point-patch finding stands.

[FIRST-PRINCIPLES-REVIEWED] 8645246

@github-actions

github-actions Bot commented Sep 7, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 8645246a457099852d09e25f40e8c1f7c59af434 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 8645246

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 8645246a457099852d09e25f40e8c1f7c59af434: <one-sentence reason>

@chenmingwei23
chenmingwei23 force-pushed the feat/fileviewer-header-path-a11y-7900 branch from fa24e44 to 616fd93 Compare September 7, 2026 20:22
@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • breadcrumb full path not visible to sighted keyboard-only users (span=5f7a964d27b4)

Fixed in 616fd93. The finding is legitimate for the sighted-keyboard-only class: they hear no aria-label and a native title does not open on keyboard focus, so the focus ring alone did not let them read the full path.
Addressed by construction, not by narrowing: while the breadcrumb holds keyboard focus it now renders a small on-screen readout printing the full path below it (onFocus/onBlur state). The readout is aria-hidden so a screen reader is not told the path twice (it already has the group's aria-label). No new localized string: the readout text IS the runtime path.
This covers the class, not one instance: every keyboard user now has a route to the full path -- screen reader via aria-label, sighted via the readout, pointer via title.

self-added: yes
mechanism: focus-state readout in FileHeaderBreadcrumb that renders the full path on screen while the breadcrumb has keyboard focus

@chenmingwei23
chenmingwei23 force-pushed the feat/fileviewer-header-path-a11y-7900 branch from 616fd93 to 7fb4a3d Compare September 7, 2026 20:32
@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • focus readout width sized to compressed breadcrumb at narrow panel widths (span=5f7a964d27b4)

Fixed in 7fb4a3d. The readout now uses w-max max-w-[min(420px,90vw)] instead of max-w-[420px]: w-max sizes it to its content up to the cap, and the cap is viewport-relative, so its width no longer follows the compressed breadcrumb. A deep path in a narrow (320px) panel wraps into a readable multi-line block that stays on screen; the box grows downward via break-all and is never clipped (it is absolutely positioned below the header, not inside a fixed-height row).
Class-level ruling for this span: the full-path readout is width-robust independent of the breadcrumb's own width, so any later "the readout is sized to X" variant is covered -- its width is bounded only by the viewport.
Evidence: PR body now carries a 320px focused frame showing the block, not a squeezed column.

self-added: yes
mechanism: viewport-capped w-max readout so the on-screen full path is independent of the breadcrumb width

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Sep 7, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/fileviewer-header-path-a11y-7900 branch from 7fb4a3d to 5dc6dfc Compare September 7, 2026 21:02
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Sep 7, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • focus readout clips at the panel edge in the narrow case it exists for (span=5f7a964d27b4)

Fixed in 5dc6dfc, presentation only -- the keyboard route (tabIndex + role=group + aria-label) is unchanged and no second affordance was added. The readout is now anchored left-0 right-0 to a full-width wrapper whose positioning context spans the header, so its right edge IS the panel's inner edge: a long path wraps (break-all) inside the panel and the box grows downward, never past the edge.
The narrowest width the viewer allows is 320px (SIDE_PANEL_MIN_W, also the mobile floor). Verified at 320px inside a wide window (the embedded case where the panel, not the viewport, clips): the capture harness models the panel with overflow-hidden and the driver ASSERTS the readout's rect stays within the panel rect before shooting; header-path-dark-focused-narrow.png shows the full path fully readable.
Class-level: the readout's width is bounded by the panel it lives in at any panel width, so no width variant of this span can recur.

self-added: yes
mechanism: readout anchored left-0/right-0 to a full-width header wrapper, bounding it to the panel edge (replaces the old flex spacer)

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Sep 7, 2026
…nly hover

The file viewer header breadcrumb shows only the last three path segments; the full path was in a native title tooltip, which is pointer-only. Add a keyboard-focus and screen-reader route (tabIndex + role=group + aria-label) so a keyboard user can disambiguate same-named files. The label is the runtime path, so no i18n string is added.
@chenmingwei23
chenmingwei23 force-pushed the feat/fileviewer-header-path-a11y-7900 branch from 5dc6dfc to 8645246 Compare September 7, 2026 21:37
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Sep 7, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • flex-1 wrapper silently relocated the diff-mode +N/-N badge to the far right (span=ux-diff-badge-move)

Fixed in 8645246. The breadcrumb wrapper is content-sized again and the old flex-1 min-w-[8px] spacer is restored, so the header order is exactly as before: breadcrumb, then the +N/-N badge beside the filename, then the spacer, then the actions. The badge no longer moves.
The readout kept its panel-bound behaviour by a different anchor: the header bar is now relative and the readout is absolute left-3 right-3 top-full against it (matching the bar's px-3), so its width is the panel's without the wrapper having to be flex-1. Layout side effect removed; the a11y route is unchanged.
Evidence gap closed: committed diff-mode screenshots at 460px and 320px show the badge beside the filename (header-path-dark-diffmode-460.png / -320.png).

self-added: yes
mechanism: readout anchored to the relative header bar (left-3/right-3) instead of a flex-1 breadcrumb wrapper, so the header layout is untouched

@chenmingwei23

Copy link
Copy Markdown
Contributor Author
  • pointer-only-path defect class survives on other chips this PR leaves untouched (span=fp-pointer-only-siblings)

Accepted and deferred to #9312 (label deferred-finding, assignee set, Due 2026-09-21). The finding is correct: the same class exists at ChatPageMessageContent.tsx:566 (folder chip, non-onOpen branch) and ChatInput.tsx:770 (attachment tile), both verified by content on main. These are separate INSTANCES of the class, not other entry points to the header mechanism this PR fixes, so there is no false promise in the header PR to correct -- widening this PR to them would couple unrelated surfaces and needs a shared-primitive design decision. The PR body now links #9312.

On the Subtraction (delete the no-noninteractive-element-interactions disable): NOT applied -- it is not dead in the shipped structure. The finding was measured against an earlier head; in 8645246 the div carries onFocus/onBlur, and eslint src/components/MarkdownPanel.tsx flags jsx-a11y/no-noninteractive-element-interactions on that element when the directive is removed (I verified: removing it yields one warning, restoring it clears it). The cited precedents carry only the tabindex disable because their focusable elements have no focus/blur handlers; this one does, to drive the visible readout. Keeping the directive with this rationale rather than deleting a live suppression.

self-added: yes
mechanism: deferred sibling-chip a11y to tracked issue #9312; retained the element-interactions eslint-disable because the onFocus/onBlur handlers make it live

@github-actions github-actions Bot removed the readiness: checking Automated validation is still running label Sep 7, 2026
@github-actions github-actions Bot added the readiness: passed Eligible automated validation passed for the current revision label Sep 7, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tech Lead review — approved.

Accessibility correctness. The focus target is the real breadcrumb element, not a proxy: tabIndex={0} puts it in the tab order in DOM/visual order (icon → breadcrumb → diff badge → spacer → actions), so tab order stays coherent. role="group" takes its name from the author rather than from contents, so aria-label={filePath} names the region without hiding the visible crumbs from assistive tech. title is not used for the accessible name once aria-label is present, so the pointer route survives with no double announcement, and the sighted-keyboard readout is aria-hidden="true" so a screen reader is not told the path twice. focus-visible:ring-1 scopes the ring to keyboard focus. Three genuinely distinct routes, one per user class, no redundancy.

Scope. Real code is one component (+73/-13) plus its tests (+65/-1); the other ten files are the repo's own established evidence conventions (website/capture/, website/scripts/, temp-screenshots/). Nothing outside the stated surface, and the side-panel tab chip (#7935) is left alone.

i18n. No localized string is added and no locale catalogue is touched, correctly — the accessible name and the readout both ARE the runtime path, i.e. data, not UI copy. Automated Rule Check and Inclusive Language are green on this head.

Blocking findings. None outstanding. All five AI lanes are clean on 8645246a4 (GPT and Opus no findings; Design, UX and First Principles PASS), no inline comments, no CHANGES_REQUESTED. The six cancelled check-runs are superseded duplicates — every one has a same-named success run on this same sha, started 21s later. The two surviving lane suggestions are advisory: gating the readout on :focus-visible (a left-click currently also opens it, which is benign and arguably useful), and a muted elision crumb. Neither is a defect, and neither warrants added mechanism here.

The tests are a real ratchet, not a tautology: they assert focus actually lands (toHaveFocus), query by accessible name (getByRole('group', { name: fullPath })), and pin the blur teardown.

@bolichen97
bolichen97 merged commit 113ea47 into main Sep 8, 2026
66 of 72 checks passed
@bolichen97
bolichen97 deleted the feat/fileviewer-header-path-a11y-7900 branch September 8, 2026 00:42
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 8, 2026
amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
…nly hover (kirodotdev#9301)

The file viewer header breadcrumb shows only the last three path segments; the full path was in a native title tooltip, which is pointer-only. Add a keyboard-focus and screen-reader route (tabIndex + role=group + aria-label) so a keyboard user can disambiguate same-named files. The label is the runtime path, so no i18n string is added.
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.

Show the full file path on hover in the dashboard file viewer panel

2 participants