Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(Outline): following a link moves focus to the chosen section (#9045)

Cindy Zhangf73623d1bd28
diff --git a/.changeset/outline-focus-follows-link.md b/.changeset/outline-focus-follows-link.md
new file mode 100644
index 0000000000..4c4a20dcf5
--- /dev/null
+++ b/.changeset/outline-focus-follows-link.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Following an `Outline` link moves focus to the chosen section, as a native in-page link moves the focus starting point, so the next Tab continues from that section instead of jumping back to the top of the page. The section is focused without scrolling, so Outline's own scroll is unchanged (WCAG 2.2 SC 2.4.3 Focus Order).
+
+@cixzhang @duytbp
diff --git a/packages/core/src/Outline/Outline.test.tsx b/packages/core/src/Outline/Outline.test.tsx
index fd304d9684..989a1fe7c0 100644
--- a/packages/core/src/Outline/Outline.test.tsx
+++ b/packages/core/src/Outline/Outline.test.tsx
@@ -525,8 +525,10 @@ describe('Outline keyboard navigation', () => {
render(<Outline items={items} onNavigateEnd={onNavigateEnd} />);
await user.click(screen.getByRole('link', {name: 'Installation'}));
- // Arrow keys inside the outline move focus; they are prevented, so they do
- // not scroll the page and must not cancel the in-flight navigation.
+ // Following the link focuses the section; return to the outline. Arrow
+ // keys inside it move focus; they are prevented, so they do not scroll
+ // the page and must not cancel the in-flight navigation.
+ screen.getByRole('link', {name: 'Installation'}).focus();
await user.keyboard('{ArrowDown}');
expect(onNavigateEnd).not.toHaveBeenCalled();
@@ -570,6 +572,69 @@ describe('Outline navigate callbacks', () => {
vi.useRealTimers();
});
+ it('moves focus to the chosen section, so the next Tab continues there (WCAG 2.4.3)', async () => {
+ const user = userEvent.setup();
+ const cleanup = mountHeadings();
+ const install = document.getElementById('install')!;
+ const focus = vi.spyOn(install, 'focus');
+ render(<Outline items={items} />);
+
+ await user.click(screen.getByRole('link', {name: 'Installation'}));
+ expect(install).toHaveFocus();
+ // Focusing must not fight Outline's own scroll.
+ expect(focus).toHaveBeenCalledWith({preventScroll: true});
+ // A heading is made programmatically focusable only, never a Tab stop.
+ expect(install).toHaveAttribute('tabindex', '-1');
+
+ // A target that already sets its own tabindex keeps it.
+ install.blur();
+ install.setAttribute('tabindex', '0');
+ await user.click(screen.getByRole('link', {name: 'Installation'}));
+ expect(install).toHaveFocus();
+ expect(install).toHaveAttribute('tabindex', '0');
+
+ cleanup();
+ });
+
+ it("keeps a target's own tabindex when it cannot take focus", async () => {
+ const user = userEvent.setup();
+ const cleanup = mountHeadings(['intro', 'api']);
+ // A target with its own tab stop that refuses focus right now, as a
+ // hidden panel does in a browser. The test DOM focuses hidden elements,
+ // so the refusal is simulated.
+ const panel = document.createElement('div');
+ panel.id = 'install';
+ panel.setAttribute('tabindex', '0');
+ vi.spyOn(panel, 'focus').mockImplementation(() => {});
+ document.body.appendChild(panel);
+ render(<Outline items={items} />);
+
+ await user.click(screen.getByRole('link', {name: 'Installation'}));
+ expect(panel).toHaveAttribute('tabindex', '0');
+
+ panel.remove();
+ cleanup();
+ });
+
+ it('focuses a target that is already focusable without taking it out of the Tab order', async () => {
+ const user = userEvent.setup();
+ const cleanup = mountHeadings(['intro', 'api']);
+ // The "install" item points at a link, which is focusable on its own.
+ const link = document.createElement('a');
+ link.id = 'install';
+ link.href = '#install-details';
+ link.textContent = 'Install details';
+ document.body.appendChild(link);
+ render(<Outline items={items} />);
+
+ await user.click(screen.getByRole('link', {name: 'Installation'}));
+ expect(link).toHaveFocus();
+ expect(link).not.toHaveAttribute('tabindex');
+
+ link.remove();
+ cleanup();
+ });
+
it('fires onNavigateStart on click and onNavigateEnd when the scroll settles', async () => {
const user = userEvent.setup();
const cleanup = mountHeadings();
diff --git a/packages/core/src/Outline/Outline.tsx b/packages/core/src/Outline/Outline.tsx
index c6e6333c13..37fb1ff02a 100644
--- a/packages/core/src/Outline/Outline.tsx
+++ b/packages/core/src/Outline/Outline.tsx
@@ -259,6 +259,28 @@ function getIndentStyle(level: number) {
}
}
+/**
+ * A followed in-page link moves the sequential focus starting point to its
+ * target, so the next Tab continues inside that section. Outline cancels the
+ * link's default to scroll itself, so it restores that by focusing the target
+ * without scrolling (WCAG 2.4.3). A target that is not focusable becomes
+ * programmatically focusable only.
+ */
+function moveFocusTo(id: string) {
+ const target = document.getElementById(id);
+ if (target == null) {
+ return;
+ }
+ // A target that already takes focus (a link, a button) keeps its place in
+ // the Tab order; only one that refuses focus is made focusable by script.
+ target.focus({preventScroll: true});
+ // A caller's own tabindex is never overwritten.
+ if (document.activeElement !== target && !target.hasAttribute('tabindex')) {
+ target.setAttribute('tabindex', '-1');
+ target.focus({preventScroll: true});
+ }
+}
+
// =============================================================================
// Component
// =============================================================================
@@ -392,6 +414,7 @@ export function Outline({
const navigate = (id: string) => {
if (scrollTo(id)) {
window.history.pushState(null, '', `#${id}`);
+ moveFocusTo(id);
}
};