fix(root): focus section headings from contents navigation

[sylvesterkaczmarek]

Summary

Keep the page contents navigation in sync with the section currently being read, and move focus to section headings when contents links are activated.

Problem

On pages with short sections, including Design principles, observing only the heading elements could cause contents entries to be skipped while scrolling. The previous change also did not reliably move screen-reader focus to the selected heading.

Fix

• derive the active contents item from the latest heading above the activation line, so each section remains active until the next heading is reached;
• select the final contents item when the page bottom is reached;
• update the URL hash, scroll to, and focus the target heading when a contents link is activated;
• keep section headings programmatically focusable with tabIndex={-1}.

Validation

• verified all nine Design principles headings activate in order while scrolling in a browser;
• verified contents-link activation moves DOM focus to the selected heading and updates the hash;
• npm run prettier, npm run verify-ts, npm run lint, npm test, and npm run build pass locally.

Closes #1266

[GCHQ-Developer-530]

Please can you rebase this pull request?

[sylvesterkaczmarek]

Rebased onto the latest develop. Thanks!

[GCHQ-Developer-299]

I'm not sure this Pull Request remedies the ticket. I think that's partly an issue with the ticket lacking descriptiveness.

My understanding is that the ticket's problem is that (specifically on the design principles page) when you scroll down the page, some of the items in the Table of Contents are skipped, instead of being highlighted as you go.
I think this is because each section on the design principles page only contains a line or two of text, so the window for that Heading to be active is very small.

This pull request doesn't fix the issue with titles being skipped, nor does it move the focus of NVDA screenreader when I tested locally. The former behaviour being similar between main branch and this is shown below:

Screen.Recording.2026-08-27.at.12.44.42.mov

[sylvesterkaczmarek]

Thanks for clarifying the expected behaviour. I’ve reworked the fix around the Design Principles case: each section now remains active until the next heading reaches the activation line, so the short sections are no longer skipped. Selecting a contents link also explicitly updates the hash, scrolls to the heading, and moves DOM focus to it.

I rebased onto current develop and verified all nine Design Principles headings activate in order in a browser. I also verified focus lands on the selected heading. Prettier, TypeScript, lint, Jest, and the full production build pass locally. Thanks again for the helpful review.