fix(jsref): nest member sub-pages in the JS reference sidebar by caugner · Pull Request #728 · mdn/rari

caugner · 2026-05-26T15:42:29Z

Description

Generalize the JS reference sidebar so that any member entry (constructor, method, property) whose page has its own sub-pages renders those sub-pages nested below it, inside a <details> element with the parent's link in the <summary>. In practice this covers:

Proxy/Proxy/* handler traps now nest under the Proxy() constructor entry (which lives in the shared Proxy sidebar that all Proxy/* pages use).
Intl/Segmenter/segment/Segments (and Segments/containing, Segments/[Symbol.iterator]) now nest under the segment() instance method — previously they were surfaced as a separate sidebar via special cases.

Motivation

The previous Proxy/Proxy → Proxy/handler slug mapping pointed at a page that never existed, producing templ-redirected-link flaws across the Proxy reference pages.
Handler trap pages (Proxy/Proxy/apply, .get, .set, …) rendered under a separate, partially-broken sidebar instead of sharing the surrounding Proxy sidebar.
Existing one-off special cases (Proxy handler, Intl/Segmenter/segment/Segments) all want the same thing: surface sub-pages where they belong in the hierarchy. Doing it generically removes the special cases and avoids needing a new one each time another member grows sub-pages.

Additional details

JSRefItem now carries a sub_pages: HashMap<String, Vec<Page>> keyed by parent page slug. get_sub_pages for the class walks the whole sub-tree (depth None); depth-1 pages are bucketed by PageType as before, depth-≥2 pages go into sub_pages.
A new build_member_entry helper recursively constructs each entry, attaching MetaChildren::Children from sub_pages when present and setting Details::Closed so entries with children are collapsible and start closed (regardless of the surrounding group's open/closed state).
The unified (label, list) loop now also covers the Constructor group — there is no separate code path for it.
slug_to_object_name no longer has a Proxy/Proxy or Intl/Segmenter/segment/Segments special case — both fall through to the normal class resolution. GROUP_DATA loses the [Segments, Intl.Segmenter] entry. JSRefItem::from_obj_str loses its Segments-only title override.
The redundant ["Proxy", "Proxy/handler"] related-pages entry is removed.
test_slug_to_object_name gets assertions for Proxy, Proxy/Proxy, Proxy/Proxy/get, Intl/Segmenter/segment/Segments, and Intl/Segmenter/segment/Segments/containing.

Screenshots

`Proxy` page

Before	After

`Proxy()` constructor page

Before	After

`handler.apply()` trap page

Before	After

`Intl.Segmenter` page

Before	After

`Intl.Segmenter.segment()` page

Before	After

`Intl.Segmenter.segment()` -> `Segments` page

Before	After

Related issues and pull requests

Fixes #706.
Closes #732.

Supersedes #707.

All `Proxy/*` pages now share one sidebar with handler traps listed under a new "Handler methods" group sourced from `Proxy/Proxy/*` sub-pages. Drops the broken `Proxy/Proxy/*` → `Proxy/handler` slug mapping (the page never existed) and the redundant `Proxy/handler` related-pages entry. Requires `Handler_methods` in `L10n-Common.json`.

github-actions · 2026-05-26T15:46:12Z

dd20530 was deployed to: https://rari-pr728.review.mdn.allizom.net/

Rename the `pages` binding inside the `obj == "Proxy"` block to `handler_pages` so it does not shadow the outer `pages` from the generic sub-page fetch, making the scope obvious to readers.

Previously, any sub-page of `Proxy/Proxy` whose page type was not `JavascriptInstanceMethod` would be silently dropped from the sidebar. Emit a `tracing::warn!` instead so non-trap sub-pages (e.g. a future data property) surface in build logs and can be triaged.

caugner · 2026-05-26T16:49:46Z

@Josh-Cena Can you take a look at the screenshots and let me know if this looks good? 🙂

Handler methods are properties on a separate `handler` object passed to the `Proxy()` constructor, not members of the `Proxy` class itself. Move the group to the end of the sidebar so it reads as a distinct concept rather than splitting the static-methods/static-properties pairing.

Josh-Cena · 2026-05-27T03:46:43Z

I'm not fond of this design. These methods should be under the constructor, not the class.

Drop the separate `Handler methods` group at the class level and instead render the traps as children of the `Proxy()` constructor entry, matching their slug location (`Proxy/Proxy/*`). This also removes the dependency on the `Handler_methods` L10n key.

Put the `Proxy()` link inside `<summary>` and the trap list below it, so the entry can be collapsed/expanded like the surrounding groups.

Drop the `handler_methods` field on `JSRefItem` and the corresponding `if obj == \"Proxy\"` branch in `from_obj_str`. The fetch now lives in `proxy_handler_trap_entries()`, called from the constructor-entry builder where it's actually used. Keeps the per-class data struct free of Proxy-specific quirks.

Generalize the Proxy-specific nesting into a depth-aware fetch and recursive entry builder. For each class, `get_sub_pages` now walks the whole sub-tree; depth-1 pages are still bucketed by `PageType`, and depth-≥2 pages are kept in a `sub_pages` map keyed by parent slug. A new `build_member_entry` helper recursively constructs sidebar entries and nests sub-pages under their parent, using `<details>` whenever an entry has children. This subsumes: - `Proxy/Proxy/*` handler traps (now generic, not Proxy-specific). - `Intl/Segmenter/segment/Segments` (and `Segments/containing`, `Segments/[Symbol.iterator]`), which previously appeared as a separate sidebar via special cases in `slug_to_object_name` and `GROUP_DATA`. Both special cases are removed.

`rsplit_once('/')` already yields the parent slug we need for the nested-pages bucket; comparing it to `class_slug` tells us whether the page is a direct member without an extra `strip_prefix` + `contains` pass.

Top-level groups like Constructor or Instance methods still open by default for the current class, but the nested `<details>` for a member that has its own sub-pages (e.g. `Proxy()` with handler traps, or `segment()` with `Segments`) now starts collapsed.

The field holds descendants at depth >= 2 keyed by their immediate parent slug, and `build_member_entry` walks it recursively — the prior wording suggested it was specific to depth-1 members.

`get_sub_pages` only returns descendants of the class slug, so every page here has a parent component. Replace the let-else `continue` with an `expect` that documents the invariant.

Switching `get_sub_pages` from `depth: Some(1)` to `None` widens the directory walk per class, but `read_sub_folders_internal` is `#[memoize]`-cached, so the cost isn't paid per sidebar build. Call that out so the next reader doesn't worry about a hot-path cost.

caugner · 2026-05-27T14:06:34Z

I'm not fond of this design. These methods should be under the constructor, not the class.

Please have another look, I think this is what you're expecting.

Josh-Cena · 2026-05-27T16:38:27Z

Yes, love this one! Thank you!

caugner · 2026-05-27T18:34:06Z

@mdn/content-team Do you have any concerns with this change?

LeoMcA · 2026-05-28T10:46:23Z

I'll defer my code review until content have had a look

caugner · 2026-07-13T10:30:21Z

ping @mdn/content-team

Rumyra · 2026-07-17T15:17:24Z

Agree with @Josh-Cena - this is great - thank you!

This was referenced May 26, 2026

chore(jsondata): add Handler_methods L10n key mdn/content#44264

Closed

chore(jsref): change Proxy/handler group to Proxy/Proxy #707

Closed

caugner temporarily deployed to review May 26, 2026 15:45 — with GitHub Actions Inactive

caugner added 2 commits May 26, 2026 18:03

refactor(jsref): name Proxy handler trap pages variable

3c6c5e9

Rename the `pages` binding inside the `obj == "Proxy"` block to `handler_pages` so it does not shadow the outer `pages` from the generic sub-page fetch, making the scope obvious to readers.

caugner changed the title ~~feat(jsref): unify Proxy/* sidebar with Handler methods group~~ fix(jsref): unify Proxy/* sidebar with Handler methods group May 26, 2026

caugner temporarily deployed to review May 26, 2026 16:12 — with GitHub Actions Inactive

caugner temporarily deployed to review May 26, 2026 16:19 — with GitHub Actions Inactive

caugner marked this pull request as ready for review May 26, 2026 16:49

caugner requested a review from a team as a code owner May 26, 2026 16:49

caugner requested a review from LeoMcA May 26, 2026 16:49

caugner force-pushed the 707-refine-Proxy-sidebar branch from b741af8 to 2ff51cb Compare May 26, 2026 17:05

caugner temporarily deployed to review May 26, 2026 17:09 — with GitHub Actions Inactive

caugner added 2 commits May 27, 2026 11:05

feat(jsref): wrap Proxy() entry in <details> for handler traps

fef475d

Put the `Proxy()` link inside `<summary>` and the trap list below it, so the entry can be collapsed/expanded like the surrounding groups.

caugner marked this pull request as draft May 27, 2026 09:10

caugner temporarily deployed to review May 27, 2026 09:12 — with GitHub Actions Inactive

caugner mentioned this pull request May 27, 2026

jsref: generalize sidebar nesting for member pages with sub-pages #732

Open

caugner added 2 commits May 27, 2026 12:28

caugner temporarily deployed to review May 27, 2026 12:29 — with GitHub Actions Inactive

caugner changed the title ~~fix(jsref): unify Proxy/* sidebar with Handler methods group~~ fix(jsref): nest member sub-pages in the JS reference sidebar May 27, 2026

refactor(jsref): split parent slug once instead of two scans

b4f43f5

`rsplit_once('/')` already yields the parent slug we need for the nested-pages bucket; comparing it to `class_slug` tells us whether the page is a direct member without an extra `strip_prefix` + `contains` pass.

caugner temporarily deployed to review May 27, 2026 12:40 — with GitHub Actions Inactive

caugner added 3 commits May 27, 2026 15:41

docs(jsref): clarify sub_pages scope and recursion

e4125db

The field holds descendants at depth >= 2 keyed by their immediate parent slug, and `build_member_entry` walks it recursively — the prior wording suggested it was specific to depth-1 members.

refactor(jsref): expect slug always has / for sub-page descendants

a1c7eb2

`get_sub_pages` only returns descendants of the class slug, so every page here has a parent component. Replace the let-else `continue` with an `expect` that documents the invariant.

caugner temporarily deployed to review May 27, 2026 13:56 — with GitHub Actions Inactive

caugner temporarily deployed to review May 27, 2026 14:02 — with GitHub Actions Inactive

caugner marked this pull request as ready for review May 27, 2026 18:32

LeoMcA added the needs content decision label Jun 8, 2026

Merge branch 'main' into 707-refine-Proxy-sidebar

27fde71

caugner temporarily deployed to review July 13, 2026 10:33 — with GitHub Actions Inactive

Merge branch 'main' into 707-refine-Proxy-sidebar

8a542f6

caugner removed the needs content decision label Jul 17, 2026

caugner deployed to review July 17, 2026 15:52 — with GitHub Actions View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(jsref): nest member sub-pages in the JS reference sidebar#728

fix(jsref): nest member sub-pages in the JS reference sidebar#728
caugner wants to merge 15 commits into
mainfrom
707-refine-Proxy-sidebar

caugner commented May 26, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 26, 2026 •

edited

Loading

Uh oh!

caugner commented May 26, 2026

Uh oh!

Josh-Cena commented May 27, 2026

Uh oh!

caugner commented May 27, 2026

Uh oh!

Josh-Cena commented May 27, 2026

Uh oh!

caugner commented May 27, 2026

Uh oh!

LeoMcA commented May 28, 2026

Uh oh!

caugner commented Jul 13, 2026

Uh oh!

Rumyra commented Jul 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

caugner commented May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Motivation

Additional details

Screenshots

Proxy page

Proxy() constructor page

handler.apply() trap page

Intl.Segmenter page

Intl.Segmenter.segment() page

Intl.Segmenter.segment() -> Segments page

Related issues and pull requests

Uh oh!

github-actions Bot commented May 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

caugner commented May 26, 2026

Uh oh!

Josh-Cena commented May 27, 2026

Uh oh!

caugner commented May 27, 2026

Uh oh!

Josh-Cena commented May 27, 2026

Uh oh!

caugner commented May 27, 2026

Uh oh!

LeoMcA commented May 28, 2026

Uh oh!

caugner commented Jul 13, 2026

Uh oh!

Rumyra commented Jul 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

caugner commented May 26, 2026 •

edited

Loading

`Proxy` page

`Proxy()` constructor page

`handler.apply()` trap page

`Intl.Segmenter` page

`Intl.Segmenter.segment()` page

`Intl.Segmenter.segment()` -> `Segments` page

github-actions Bot commented May 26, 2026 •

edited

Loading