Skip to content

Commit 763b7d5

Browse files
Add JSDoc for the root layout, breadcrumbs, and breadcrumb test helpers
1 parent 8d39544 commit 763b7d5

5 files changed

Lines changed: 55 additions & 3 deletions

File tree

‎app/layout.jsx‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,13 @@ export const metadata = {
2121
icons: { icon: '/assets/logo.png' },
2222
};
2323

24+
/**
25+
* Renders the site shell with navigation, breadcrumbs, and page content.
26+
*
27+
* @param {object} props - Layout props.
28+
* @param {import('react').ReactNode} props.children - Content of the active page.
29+
* @returns {import('react').ReactElement} The root HTML document.
30+
*/
2431
export default function RootLayout({ children }) {
2532
const repositories = loadListedRepositories();
2633
return (

‎components/breadcrumbs.jsx‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,12 @@ import {
1717
BRANCH_RESOLVED_EVENT
1818
} from '../lib/breadcrumbs.js';
1919

20+
/**
21+
* Renders the current route's breadcrumb trail and tracks the loaded branch.
22+
*
23+
* @returns {import('react').ReactElement|null} Breadcrumb navigation, or null
24+
* when the route is neither a user listing nor a repository report.
25+
*/
2026
export default function Breadcrumbs() {
2127
const pathname = usePathname();
2228
const searchParams = useSearchParams();
@@ -31,6 +37,13 @@ export default function Breadcrumbs() {
3137
}
3238

3339
useEffect(() => {
40+
/**
41+
* Updates the branch label for announcements matching the current report.
42+
*
43+
* @param {CustomEvent<{username: string, repository: string, branch: string}>} event
44+
* Report identity and the branch that successfully loaded.
45+
* @returns {void}
46+
*/
3447
const onBranchResolved = event => {
3548
if (!reportMatchesFor(pathname || '/', event.detail)) return;
3649
const { branch } = event.detail;

‎lib/breadcrumbs.js‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,9 +12,16 @@ import { classifyRoute, buildReportUrl, getQueryParam } from './routes.js';
1212
// displayed instead of the default guess.
1313
export const BRANCH_RESOLVED_EVENT = 'rf:branch-resolved';
1414

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).
15+
/**
16+
* Creates a branch-resolution event in the dispatch target's realm.
17+
* Falls back to an Event carrying detail when CustomEvent is unavailable or
18+
* incompatible with Event in the current runtime.
19+
*
20+
* @param {EventTarget} target - Window, DOM node, or standalone event target.
21+
* @param {{username: string, repository: string, branch: string}} detail
22+
* The report identity and resolved branch carried by the event.
23+
* @returns {Event & {detail: object}} An event compatible with the target.
24+
*/
1825
function branchResolvedEvent(target, detail) {
1926
const realm =
2027
(target && target.window === target && target) || // a Window
@@ -29,6 +36,12 @@ function branchResolvedEvent(target, detail) {
2936
return Object.assign(new Event(BRANCH_RESOLVED_EVENT), { detail });
3037
}
3138

39+
/**
40+
* Builds a user-listing path with the username encoded as one URL segment.
41+
*
42+
* @param {string} username - Repository owner's username.
43+
* @returns {string} The user-listing path, without a deployment base path.
44+
*/
3245
function userHref(username) {
3346
return `/${encodeURIComponent(username)}`;
3447
}

‎tests/e2e/breadcrumbs.spec.js‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,12 @@ test.beforeEach(async ({ page }) => {
2323
});
2424
});
2525

26+
/**
27+
* Locates breadcrumb list items within the navigation landmark.
28+
*
29+
* @param {import('@playwright/test').Locator} nav - Breadcrumb navigation locator.
30+
* @returns {import('@playwright/test').Locator} Locator for the ordered trail items.
31+
*/
2632
function trail(nav) {
2733
return nav.locator('ol li');
2834
}

‎tests/integration/breadcrumbs.test.jsx‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,12 +21,25 @@ import { announceResolvedBranch } from '../../lib/breadcrumbs.js';
2121

2222
installRtlDom();
2323

24+
/**
25+
* Sets the mocked route and mounts the breadcrumb component for assertions.
26+
*
27+
* @param {string} pathname - Path exposed by the navigation mock.
28+
* @param {string} [search=''] - Query string exposed by the navigation mock.
29+
* @returns {import('@testing-library/react').RenderResult} Rendered test utilities.
30+
*/
2431
function renderBreadcrumbs(pathname, search = '') {
2532
currentPath = pathname;
2633
currentSearch = search;
2734
return render(_jsx(Breadcrumbs, {}));
2835
}
2936

37+
/**
38+
* Collects the rendered breadcrumb list items in navigation order.
39+
*
40+
* @param {HTMLElement} container - Root container returned by the test renderer.
41+
* @returns {HTMLLIElement[]} The breadcrumb items within the container.
42+
*/
3043
function crumbs(container) {
3144
return Array.from(
3245
container.querySelectorAll('nav[aria-label="Breadcrumb"] ol li')

0 commit comments

Comments
 (0)