Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

Restore heading focus on repeated documentation links

pulse-triage[bot]9b03f9fa0f64
diff --git a/frontend-modern/browser-verification/582cc03f014bc9c4.json b/frontend-modern/browser-verification/582cc03f014bc9c4.json
new file mode 100644
index 0000000000..0be226e11d
--- /dev/null
+++ b/frontend-modern/browser-verification/582cc03f014bc9c4.json
@@ -0,0 +1,59 @@
+{
+ "version": 1,
+ "base_sha": "442ec68c841297a092e22c65af822cbf4be6e15f",
+ "verified_at": "2026-10-31T20:56:58.327Z",
+ "result": "passed",
+ "changed_paths": [
+ "frontend-modern/src/pages/Docs.tsx"
+ ],
+ "content_sha256": {
+ "frontend-modern/src/pages/Docs.tsx": "b20884635d67ccbcc5f3fc7358eba4db00cd085beab2faac6a1914960c70fd79"
+ },
+ "routes": [
+ "Existing Docs route with actual Router, Docs, Markdown renderer, styles and shipped TROUBLESHOOTING/INSTALL Markdown"
+ ],
+ "viewports": [
+ {
+ "width": 1440,
+ "height": 1000
+ },
+ {
+ "width": 320,
+ "height": 900
+ }
+ ],
+ "states": [
+ "Current fragment reactivated after scrolling away: requested heading is visible and focused",
+ "Direct async fragment and changed-fragment navigation still focus the requested heading",
+ "Held cross-document read hides prior article, then focuses only the resolved destination",
+ "Unknown document HTML fallback retains the explicit not-shipped error"
+ ],
+ "interactions": [
+ "Twice reactivate an actual shipped self-fragment link using desktop keyboard or narrow touch; observe focus/scroll and no Markdown refetch",
+ "Navigate to another fragment, then a shipped cross-document link whose local read is deliberately held and resolved",
+ "Open a synthetic missing route to exercise the real HTML-fallback rejection without API or external access"
+ ],
+ "browsers": [
+ {
+ "engine": "Chromium",
+ "version": "141.0.7390.37"
+ },
+ {
+ "engine": "WebKit",
+ "version": "26.0"
+ }
+ ],
+ "playwright_version": "1.56.1",
+ "checks": 33,
+ "captures": 8,
+ "pixel_review": "All eight captures opened with native view_image. Requested version/install headings and text are legible, with desktop focus outlines; 320px text wraps without page overflow. Loading and not-shipped text remain readable and prior articles are absent.",
+ "evidence": [
+ "RECEIPTS.md",
+ "DOCS-RETURN.json",
+ "BROWSER-SUMMARY.json",
+ "PIXEL-REVIEW.json",
+ "CURRENT.tar.xz",
+ "CAPTURES.tar.xz"
+ ],
+ "limitations": "Safe local docs fixtures, no published-runtime acceptance or original Back/reload work. A partial desktop run passes six checks/one capture then encounters a duplicate fixture locator; the remaining-only continuation completes 27 checks/seven captures, retaining the original observations and both cleanups. The parent shipped-link observation scrolls successfully but loses heading focus; the original PI off-screen observation is not reproduced here."
+}
diff --git a/frontend-modern/src/pages/Docs.tsx b/frontend-modern/src/pages/Docs.tsx
index 6402dd73ac..387acdb139 100644
--- a/frontend-modern/src/pages/Docs.tsx
+++ b/frontend-modern/src/pages/Docs.tsx
@@ -84,6 +84,16 @@ export default function Docs() {
const href = anchor?.getAttribute('href');
if (!href) return;
event.preventDefault();
+ // Re-activating the current fragment changes neither reactive dependency
+ // above. Restore its focus as well as its scroll position explicitly.
+ if (
+ article &&
+ location.hash &&
+ href === `${location.pathname}${location.search}${location.hash}`
+ ) {
+ scrollToDocFragment(article, location.hash);
+ return;
+ }
navigate(href);
};
diff --git a/frontend-modern/src/pages/__tests__/Docs.navigation.test.tsx b/frontend-modern/src/pages/__tests__/Docs.navigation.test.tsx
new file mode 100644
index 0000000000..25a1c61926
--- /dev/null
+++ b/frontend-modern/src/pages/__tests__/Docs.navigation.test.tsx
@@ -0,0 +1,176 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { cleanup, fireEvent, render, screen, waitFor } from '@solidjs/testing-library';
+import { createSignal } from 'solid-js';
+import Docs from '../Docs';
+
+// Drive the route's reactive inputs directly here; consuming browser proof
+// exercises the actual router and its asynchronous navigation transitions.
+const [route, setRoute] = createSignal(new URL('http://localhost/docs/guide#existing-section'));
+const navigateMock = vi.fn((href: string) => setRoute(new URL(href, 'http://localhost')));
+vi.mock('@solidjs/router', () => ({
+ useParams: () => ({
+ get docPath() {
+ return route().pathname.replace(/^\/docs\//, '');
+ },
+ }),
+ useLocation: () => ({
+ get pathname() {
+ return route().pathname;
+ },
+ get search() {
+ return route().search;
+ },
+ get hash() {
+ return route().hash;
+ },
+ }),
+ useNavigate: () => navigateMock,
+}));
+
+const source = `# Example guide
+
+[Return to section](guide.md#existing-section)
+
+[Other section](guide.md#other-section)
+
+[Next guide](next.md#next-section)
+
+## Existing section
+
+Some text.
+
+## Other section
+
+More text.`;
+const fetchMock = vi.fn();
+const scrollIntoView = vi.fn();
+const originalScroll = Object.getOwnPropertyDescriptor(HTMLElement.prototype, 'scrollIntoView');
+const frames = new Map<number, FrameRequestCallback>();
+let nextFrame = 0;
+const flushFrames = () => {
+ const pending = [...frames.values()];
+ frames.clear();
+ pending.forEach((callback) => callback(0));
+};
+const renderGuide = (fragment = 'existing-section') => {
+ setRoute(new URL(`http://localhost/docs/guide#${fragment}`));
+ return render(() => <Docs />);
+};
+
+beforeEach(() => {
+ frames.clear();
+ scrollIntoView.mockClear();
+ fetchMock.mockReset();
+ navigateMock.mockClear();
+ fetchMock.mockResolvedValue(new Response(source, { headers: { 'content-type': 'text/plain' } }));
+ vi.stubGlobal('fetch', fetchMock);
+ vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) => {
+ frames.set(++nextFrame, callback);
+ return nextFrame;
+ });
+ vi.stubGlobal('cancelAnimationFrame', (id: number) => frames.delete(id));
+ vi.stubGlobal('scrollTo', vi.fn());
+ Object.defineProperty(HTMLElement.prototype, 'scrollIntoView', {
+ configurable: true,
+ value: scrollIntoView,
+ });
+});
+
+afterEach(() => {
+ cleanup();
+ vi.unstubAllGlobals();
+ if (originalScroll)
+ Object.defineProperty(HTMLElement.prototype, 'scrollIntoView', originalScroll);
+ else Reflect.deleteProperty(HTMLElement.prototype, 'scrollIntoView');
+});
+
+describe('Docs section navigation', () => {
+ it('returns focus and scroll to the current fragment on every explicit activation without refetching', async () => {
+ renderGuide();
+ const heading = await screen.findByRole('heading', { name: 'Existing section' });
+ flushFrames();
+ expect(heading).toHaveFocus();
+ const link = screen.getByRole('link', { name: 'Return to section' });
+ scrollIntoView.mockClear();
+ for (let activation = 0; activation < 2; activation += 1) {
+ link.focus();
+ fireEvent.click(link);
+ expect(heading).toHaveFocus();
+ expect(scrollIntoView.mock.contexts[activation]).toBe(heading);
+ }
+ expect(scrollIntoView).toHaveBeenCalledTimes(2);
+ expect(fetchMock).toHaveBeenCalledTimes(1);
+ expect(route().hash).toBe('#existing-section');
+ expect(navigateMock).not.toHaveBeenCalled();
+ });
+
+ it('waits for an asynchronously fetched destination before focusing its fragment', async () => {
+ let resolve!: (response: Response) => void;
+ fetchMock.mockReturnValueOnce(new Promise<Response>((done) => (resolve = done)));
+ renderGuide();
+ expect(screen.getByText('Loading documentation…')).toBeInTheDocument();
+ flushFrames();
+ expect(scrollIntoView).not.toHaveBeenCalled();
+ resolve(new Response(source, { headers: { 'content-type': 'text/markdown' } }));
+ const heading = await screen.findByRole('heading', { name: 'Existing section' });
+ flushFrames();
+ expect(heading).toHaveFocus();
+ expect(scrollIntoView.mock.contexts).toEqual([heading]);
+ });
+
+ it.each(['ctrlKey', 'metaKey', 'shiftKey', 'altKey'])(
+ 'leaves modified %s activation to the browser',
+ async (modifier) => {
+ renderGuide();
+ await screen.findByRole('heading', { name: 'Existing section' });
+ flushFrames();
+ const link = screen.getByRole('link', { name: 'Return to section' });
+ link.focus();
+ scrollIntoView.mockClear();
+ fireEvent.click(link, { [modifier]: true });
+ expect(scrollIntoView).not.toHaveBeenCalled();
+ expect(link).toHaveFocus();
+ expect(fetchMock).toHaveBeenCalledTimes(1);
+ expect(navigateMock).not.toHaveBeenCalled();
+ },
+ );
+
+ it('keeps changed-fragment and cross-document navigation on the existing async path', async () => {
+ renderGuide();
+ await screen.findByRole('heading', { name: 'Existing section' });
+ flushFrames();
+ fireEvent.click(screen.getByRole('link', { name: 'Other section' }));
+ await waitFor(() => {
+ flushFrames();
+ expect(screen.getByRole('heading', { name: 'Other section' })).toHaveFocus();
+ });
+ fetchMock.mockResolvedValueOnce(new Response('# Next guide\n\n## Next section'));
+ fireEvent.click(screen.getByRole('link', { name: 'Next guide' }));
+ const next = await screen.findByRole('heading', { name: 'Next section' });
+ flushFrames();
+ expect(next).toHaveFocus();
+ expect(fetchMock).toHaveBeenCalledTimes(2);
+ });
+
+ it.each(['html fallback', 'read failure'])(
+ 'retains a truthful missing-document state on %s without targeting the prior content',
+ async (failure) => {
+ renderGuide();
+ await screen.findByRole('heading', { name: 'Existing section' });
+ flushFrames();
+ scrollIntoView.mockClear();
+ fetchMock.mockResolvedValueOnce(
+ failure === 'html fallback'
+ ? new Response('<html>SPA fallback</html>', { headers: { 'content-type': 'text/html' } })
+ : new Response('unavailable', { status: 503 }),
+ );
+ fireEvent.click(screen.getByRole('link', { name: 'Next guide' }));
+ await screen.findByText(
+ "That document is not part of this installation's shipped documentation set.",
+ );
+ flushFrames();
+ expect(scrollIntoView).not.toHaveBeenCalled();
+ expect(screen.queryByRole('heading', { name: 'Existing section' })).not.toBeInTheDocument();
+ },
+ );
+});