Skip to content

Commit 8d39544

Browse files
#6 Add Breadcrumb Trail
1 parent c6c975c commit 8d39544

14 files changed

Lines changed: 762 additions & 4 deletions

‎.github/FUNDING.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
github: refactorfirst

‎AGENTS.md‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,11 @@ in `out/` is served by any static host (GitHub Pages, GitLab Pages, Bitbucket).
1010

1111
**Key Features:**
1212
- Search over curated repository listing (`repositories.txt`)
13+
- Breadcrumb trail under the menu (`components/breadcrumbs.jsx` +
14+
`lib/breadcrumbs.js`): mirrors `/user/repo/branch` with linked ancestors;
15+
the repo crumb never self-links, and ReportView announces the resolved
16+
branch (`rf:branch-resolved` event) so the label matches the loaded report
17+
(`main` 404 → `master` fallback)
1318
- Reports rendered with Mustache.js (bundled template is authoritative)
1419
- Enhanced report tables: sticky headers, pagination (>20 rows), sortable
1520
columns, in-table search, CSV export, click/keyboard cell copy with toasts
@@ -61,13 +66,15 @@ app/ # Next.js App Router (static export)
6166
globals.css # css/main.css + components.css
6267
components/ # client components: report-view, repo-list,
6368
# repo-submission-form, search-combobox,
64-
# hero-search, menu-search, menu-toggle,
65-
# workflow-sample, platform-config, sentry-provider,
69+
# hero-search, menu-search, menu-toggle, breadcrumbs
70+
# (route trail under the menu), workflow-sample,
71+
# platform-config, sentry-provider,
6672
# toast-notification (copy feedback live region)
6773
lib/ # shared logic (client + RSC): routes, fetcher,
6874
# renderer, search, utils, host, rate-limiter,
6975
# cache-manager, error-handler, repo-submission,
7076
# report-view, static-params, widget-loader,
77+
# breadcrumbs,
7178
# table-operations (filter/sort/paginate/CSV/copy +
7279
# TABLE_CONFIG + REPORT_TABLES descriptors),
7380
# table-enhancer (binds toolbar/sort/pagination/
@@ -164,7 +171,7 @@ coverage there when introducing new markup patterns.
164171

165172
## Current Test Count
166173

167-
~485 unit/integration + 175 E2E (171 across three browsers + 4 basePath leg).
174+
~543 unit/integration + ~202 E2E (~198 across three browsers + 4 basePath leg).
168175

169176
WCAG 2.2 AA / HTML5 guards live in tests/unit/html5-attributes.test.js,
170177
tests/unit/report-template-wcag.test.js, tests/unit/css-a11y.test.js and

‎app/globals.css‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -224,6 +224,55 @@ pre {
224224
color: #fff;
225225
}
226226

227+
/* ---- Breadcrumbs (user/report trail under the top menu) ---- */
228+
.breadcrumbs {
229+
/* Same column as the top menu: #top-menu is capped by mvp.css at
230+
--width-content, so reuse the variable — the two can never drift apart.
231+
border-box (not mvp's default content-box) so the horizontal padding
232+
insets crumbs exactly like .menu-bar's padding insets the brand; with
233+
content-box, symmetric padding on a centered block never moves the
234+
content edge. */
235+
max-width: var(--width-content);
236+
box-sizing: border-box;
237+
/* mvp.css gives bare nav a 7rem bottom margin, bold text and a spaced flex
238+
row — reset all three so the trail hugs the menu like a sub-bar. */
239+
margin: 0 auto;
240+
font-weight: normal;
241+
display: block;
242+
padding: 0 0.8rem;
243+
font-size: 0.85rem;
244+
}
245+
246+
.breadcrumbs ol {
247+
display: flex;
248+
flex-wrap: wrap;
249+
align-items: center;
250+
gap: 0 0.35rem;
251+
list-style: none;
252+
margin: 0;
253+
padding: 0.1rem 0;
254+
}
255+
256+
/* Path-style separator, pure CSS so it stays decorative for screen readers
257+
(the ordered list already conveys the hierarchy). */
258+
.breadcrumbs li + li::before {
259+
content: "/";
260+
margin-right: 0.35rem;
261+
color: var(--muted-color);
262+
}
263+
264+
.breadcrumbs a,
265+
.breadcrumbs [aria-current] {
266+
display: inline-block;
267+
/* No left padding: the first crumb's glyph edge must sit at the menu
268+
column left edge (the flex-gap + separator space the rest). */
269+
padding: 0.2rem 0;
270+
}
271+
272+
.breadcrumbs [aria-current] {
273+
color: var(--muted-color);
274+
}
275+
227276
/* ---- Search results ---- */
228277
.search-results {
229278
position: absolute;

‎app/layout.jsx‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
1+
import { Suspense } from 'react';
12
import SiteHeader from '../components/site-header';
23
import SiteFooter from '../components/site-footer';
4+
import Breadcrumbs from '../components/breadcrumbs';
35
import SentryProvider from '../components/sentry-provider';
46
import { loadListedRepositories } from '../lib/repositories.js';
57
import './globals.css';
@@ -35,6 +37,12 @@ export default function RootLayout({ children }) {
3537
</head>
3638
<body>
3739
<SiteHeader repositories={repositories} />
40+
{/* Breadcrumb trail under the menu (report/user routes only). Suspense
41+
is required because useSearchParams deopts otherwise (static
42+
export; the fallback keeps prerendered HTML crumb-free). */}
43+
<Suspense fallback={null}>
44+
<Breadcrumbs />
45+
</Suspense>
3846
<main id="app" tabIndex={-1}>{children}</main>
3947
<SiteFooter />
4048
<SentryProvider />

‎components/breadcrumbs.jsx‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
'use client';
2+
3+
// Breadcrumb trail rendered under the top menu: mirrors the current
4+
// /<user>/<repo>/<branch> route so report viewers can navigate back up the
5+
// hierarchy. Ancestor crumbs are links; the last crumb is the current page
6+
// (plain text with aria-current="page"). Non-report routes render nothing.
7+
//
8+
// The report fetch announces the branch it actually loaded (a main 404 falls
9+
// back to master) via BRANCH_RESOLVED_EVENT; the current crumb is relabelled
10+
// to the resolved branch so the trail identifies the displayed report.
11+
import { useEffect, useState } from 'react';
12+
import Link from 'next/link';
13+
import { usePathname, useSearchParams } from 'next/navigation';
14+
import {
15+
breadcrumbsFor,
16+
reportMatchesFor,
17+
BRANCH_RESOLVED_EVENT
18+
} from '../lib/breadcrumbs.js';
19+
20+
export default function Breadcrumbs() {
21+
const pathname = usePathname();
22+
const searchParams = useSearchParams();
23+
const search = searchParams ? searchParams.toString() : '';
24+
const routeKey = `${pathname}?${search}`;
25+
// The announced branch is keyed to the route it was announced on; a route
26+
// change resets it during render (the React-sanctioned alternative to a
27+
// setState call inside an effect).
28+
const [resolved, setResolved] = useState({ key: routeKey, branch: null });
29+
if (resolved.key !== routeKey) {
30+
setResolved({ key: routeKey, branch: null });
31+
}
32+
33+
useEffect(() => {
34+
const onBranchResolved = event => {
35+
if (!reportMatchesFor(pathname || '/', event.detail)) return;
36+
const { branch } = event.detail;
37+
if (branch) setResolved({ key: routeKey, branch });
38+
};
39+
window.addEventListener(BRANCH_RESOLVED_EVENT, onBranchResolved);
40+
return () => window.removeEventListener(BRANCH_RESOLVED_EVENT, onBranchResolved);
41+
}, [pathname, routeKey]);
42+
43+
const crumbs = breadcrumbsFor(
44+
pathname || '/',
45+
search,
46+
resolved.key === routeKey ? resolved.branch : null
47+
);
48+
if (crumbs.length === 0) return null;
49+
return (
50+
<nav className="breadcrumbs" aria-label="Breadcrumb">
51+
<ol>
52+
{crumbs.map(crumb => (
53+
<li key={crumb.label}>
54+
{crumb.current ? (
55+
<span aria-current="page">{crumb.label}</span>
56+
) : crumb.href ? (
57+
<Link href={crumb.href}>{crumb.label}</Link>
58+
) : (
59+
<span>{crumb.label}</span>
60+
)}
61+
</li>
62+
))}
63+
</ol>
64+
</nav>
65+
);
66+
}

‎components/report-view.jsx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ import Script from 'next/script';
1414
import { withBasePath } from '../lib/base-path';
1515
import { detectHostingEnvironment, getPlatformBaseUrl, readMetaTag } from '../lib/host';
1616
import { fetchReport } from '../lib/fetcher';
17+
import { announceResolvedBranch } from '../lib/breadcrumbs.js';
1718
import { renderTemplate, prepareReportData } from '../lib/renderer';
1819
import {
1920
enhanceReport,
@@ -127,6 +128,9 @@ export default function ReportView({
127128
});
128129

129130
if (controller.signal.aborted) return;
131+
// Tell the breadcrumb trail which branch actually loaded (a main
132+
// 404 falls back to master) so its label matches the report shown.
133+
announceResolvedBranch(window, { username, repository, branch: resolvedBranch });
130134
setTableStates({});
131135
setPayload({ template, data, resolvedBranch });
132136
} catch (error) {

‎lib/breadcrumbs.js‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
// Pure breadcrumb model: maps the current route to the trail rendered under
2+
// the top menu. Each crumb is { label, href } for navigable ancestors,
3+
// { label, current: true } for the page being viewed, or a plain { label }
4+
// when the only sensible link target would be the page itself (crumbs never
5+
// self-link). Routes that are not a user listing or repository report get no
6+
// trail (empty array), so landing and static content pages stay crumb-free.
7+
import { classifyRoute, buildReportUrl, getQueryParam } from './routes.js';
8+
9+
// CustomEvent dispatched by ReportView once the report fetch resolves the
10+
// branch actually loaded (a `main` 404 falls back to `master`). Breadcrumbs
11+
// listens and relabels the current crumb so it identifies the report being
12+
// displayed instead of the default guess.
13+
export const BRANCH_RESOLVED_EVENT = 'rf:branch-resolved';
14+
15+
// Construct the event in the dispatch target's own realm: jsdom EventTargets
16+
// reject events from another realm, and Bun's CustomEvent global is not an
17+
// Event subclass at all (plain-node unit-test runs).
18+
function branchResolvedEvent(target, detail) {
19+
const realm =
20+
(target && target.window === target && target) || // a Window
21+
target?.ownerDocument?.defaultView || // a DOM Node
22+
null;
23+
if (realm && typeof realm.CustomEvent === 'function') {
24+
return new realm.CustomEvent(BRANCH_RESOLVED_EVENT, { detail });
25+
}
26+
if (typeof CustomEvent === 'function' && new CustomEvent('') instanceof Event) {
27+
return new CustomEvent(BRANCH_RESOLVED_EVENT, { detail });
28+
}
29+
return Object.assign(new Event(BRANCH_RESOLVED_EVENT), { detail });
30+
}
31+
32+
function userHref(username) {
33+
return `/${encodeURIComponent(username)}`;
34+
}
35+
36+
/**
37+
* Announces the branch a report fetch actually resolved to.
38+
*
39+
* @param {EventTarget} target - Dispatch target (window in the browser).
40+
* @param {{username: string, repository: string, branch: string}} report
41+
* The report identity plus its resolved branch.
42+
*/
43+
export function announceResolvedBranch(target, { username, repository, branch }) {
44+
target.dispatchEvent(
45+
branchResolvedEvent(target, { username, repository, branch })
46+
);
47+
}
48+
49+
/**
50+
* Checks whether a branch-resolution announcement belongs to the report
51+
* route currently being viewed (stale announcements from a previous page
52+
* must not relabel it).
53+
*
54+
* @param {string} path - Current pathname.
55+
* @param {{username?: string, repository?: string}} detail - Event detail.
56+
* @returns {boolean} True when the announcement matches the viewed report.
57+
*/
58+
export function reportMatchesFor(path, detail = {}) {
59+
const route = classifyRoute(path);
60+
return route.type === 'report'
61+
&& route.username === detail.username
62+
&& route.repository === detail.repository;
63+
}
64+
65+
/**
66+
* Builds the breadcrumb trail for a path.
67+
*
68+
* @param {string} path - Current pathname (basePath already stripped by Next).
69+
* @param {string} [search] - Query string conveying ?branch= on deep links.
70+
* @param {string|null} [resolvedBranch] - Branch the report actually loaded
71+
* from (announced by ReportView after the fetch; null beforehand).
72+
* @returns {Array<{label: string, href?: string, current?: boolean}>} Crumbs
73+
* in hierarchical order; the last crumb is the current page.
74+
*/
75+
export function breadcrumbsFor(path, search = '', resolvedBranch = null) {
76+
const route = classifyRoute(path);
77+
78+
if (route.type === 'user') {
79+
return [
80+
{ label: 'Home', href: '/' },
81+
{ label: route.username, current: true }
82+
];
83+
}
84+
85+
if (route.type === 'report') {
86+
const hasBranchSegment = path.split('/').filter(Boolean).length > 2;
87+
const explicitBranch = hasBranchSegment
88+
? route.branch
89+
: getQueryParam(search, 'branch');
90+
// The resolved branch outranks any explicit/requested branch: when main
91+
// 404s and the fallback loads master, the label must say "master".
92+
const branch = resolvedBranch || explicitBranch || null;
93+
94+
const crumbs = [
95+
{ label: 'Home', href: '/' },
96+
{ label: route.username, href: userHref(route.username) }
97+
];
98+
99+
if (!branch) {
100+
// Plain /user/repo before the report announces its branch: the
101+
// repository crumb IS the current page (linking it would self-link),
102+
// and the branch is not guessed — main may resolve to master.
103+
crumbs.push({ label: route.repository, current: true });
104+
return crumbs;
105+
}
106+
107+
// With an explicit branch (path segment or ?branch=), the repository
108+
// crumb navigates back up to the default-branch report. Without one the
109+
// only target would be the current page, so the crumb stays unlinked.
110+
crumbs.push(
111+
explicitBranch
112+
? { label: route.repository, href: buildReportUrl(route.username, route.repository) }
113+
: { label: route.repository },
114+
{ label: branch, current: true }
115+
);
116+
return crumbs;
117+
}
118+
119+
return [];
120+
}

0 commit comments

Comments
 (0)