feat(ui): group overloaded functions into tabs by moshams272 · Pull Request #1047 · nodejs/doc-kit

moshams272 · 2026-08-19T21:58:12Z

Description

This PR introduces a new tabbed UI for overloaded functions. This implementation is a direct result of the discussions in #1038. It updates the MDX AST to group overloads into CodeTabs component and remove duplicate signatures.

Note: Using AI to write JSDocs & traverse some errors ;)

Validation

Add tests, and there are visual results:

Before:

After:

Related Issues

None

Check List

I have read the Contributing Guidelines and made commit messages that follow the guideline.
I have run node --run test and all tests passed.
I have check code formatting with node --run format:check & node --run lint.
I've covered new added functionality with unit tests if necessary.

vercel · 2026-08-19T21:58:17Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api-docs-tooling	Ready	Preview	Aug 27, 2026 8:37am

moshams272 · 2026-08-19T22:05:01Z

You can view the changes from here: vercel-preview

avivkeller · 2026-08-20T02:09:58Z

It's an interesting idea, but I think it makes searching harder, e.g. if I want to search for Buffer.from(buffer): Buffer, I need to make sure I'm on the right tab

avivkeller · 2026-08-20T02:10:24Z

Oddly enough, I'm fine with the showing of multiple overloads in our current state, and consumers can reformat their docs how they like.

Thanks for this demo, however :-)!

moshams272 · 2026-08-20T13:04:08Z

Hmm, fair enough! Thanks for your time 🤍

ovflowd · 2026-08-20T16:05:10Z

I actually have a different opinion and was thinking of this differently. Instead of the simple 1, 2 on the Overload headers which makes distinction hard, I feel that it could look like Code Tabs; So it becomes pretty apparent that there are more versions of this method.

What it means is that the main method signature is always the same (the initial tiny snippet box under the header) and only the attributes and descriptions/etc are under "codetabs"

I still feel that this would be much simpler.

and consumers can reformat their docs how they like.

Well I do feel our web generator could have a default stance on overloads, as it is already an opinionated style.

ovflowd · 2026-08-20T16:07:40Z

It's an interesting idea, but I think it makes searching harder, e.g. if I want to search for Buffer.from(buffer): Buffer, I need to make sure I'm on the right tab

That much I agree. I think that anchorinhg can be solved with the tab being switched to the right one based on the click... For pure command+f/ctrl+f searches, I'm unsure of either, we could either think a bit more about this or keep the current status quo.

My goal was to make overloads simpler to identify / consume less vertical space and be better organized.

moshams272 · 2026-08-20T17:48:56Z

I initially thought about using the signatures/parameters as the tab titles, but I hit two major edge cases:

Extremely long parameters: If an overload has 4-5 parameters or long variable names, the tab title becomes massive and completely breaks the UI. (AugustinMauroy actually pointed out a similar issue).
Identical signature, different types: If we only show the signature, the tabs will look identical!

That's why I retreated to indexes, and to make clear that tabs are for overloads, I've placed a header before the component itself (above indexes) contains "Overloads".

After Aviv's comment, I searched about it and found that the web standard solution is using
Accordion(details & summary tags) , It'll solve the search problem but it'll be vertical, not horizontal. we can put the signature also, but I imagined that design and I hate it, so I closed this PR ;)

ovflowd · 2026-08-21T16:56:29Z

Extremely long parameters: If an overload has 4-5 parameters or long variable names, the tab title becomes massive and completely breaks the UI. (AugustinMauroy actually pointed out a similar #1038 (comment)).

Could you show an example of what you're thinking? Are you referring to header sections?

Identical signature, different types: If we only show the signature, the tabs will look identical!

Im unsure I got what you're saying. Im saying that the initial signature box should be shared across overloads and the only tabbed pieces are the attributes/descriptions/examples

So this is not tabbed, but the below gets tabbed

And the tabbing design could be that the whole thing gets surrounded by the same box/tabbing header we use for code tabs, but instead of the content being code, it is the actual content of that overload (the attributes table, description, example, code boxes...) and the title of each tab is "Overload #1", "Overload #2"

moshams272 · 2026-08-22T17:17:29Z

Could you show an example of what you're thinking? Are you referring to header sections?
Imagne that the function signature has 10 params...

That header "Overloads" tells the developers that they r overloads:

you can review the "After" image in description of that PR as well.

Im unsure I got what you're saying. Im saying that the initial signature box should be shared across overloads and the only tabbed pieces are the attributes/descriptions/examples
And the tabbing design could be that the whole thing gets surrounded by the same box/tabbing header we use for code tabs, but instead of the content being code, it is the actual content of that overload (the attributes table, description, example, code boxes...) and the title of each tab is "Overload #1", "Overload #2"

Overloads siganture not always the same to do that 👀, For example:

lol(option, callback)
lol(index, option, callback)

ovflowd · 2026-08-22T22:10:24Z

Overloads siganture not always the same to do that 👀, For example:
lol(option, callback)
lol(index, option, callback)

Fair, but since we show a typescript-representable version of a type, shouldn't then we also render it in a way that renders overloads? Like instead of one line, you could argue it has two lines then with the two overloads? Just trying to think out loud of ways to represent this. You could maybe throw the problem at Claude to deep search how other docs do overloads and see different examples?

moshams272 · 2026-08-22T22:38:08Z

I actually saw that design before in mdn, lemme search...

moshams272 · 2026-08-22T22:43:02Z

Oh here it is: MDN/Date, Did u mean like that?

plus this:

...and the title of each tab is "Overload #1", "Overload #2"

I'm +1

ovflowd · 2026-08-23T00:52:30Z

Oh here it is: MDN/Date, Did u mean like that?

plus this:

...and the title of each tab is "Overload #1", "Overload #2"

I'm +1

Can you give it a try?

moshams272 · 2026-08-23T03:34:29Z

WIP, with new PR 👀

Or I should do it in this PR?!

codecov · 2026-08-23T07:27:41Z

Codecov Report

❌ Patch coverage is 96.70782% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.76%. Comparing base (18b9423) to head (23d5927).

Files with missing lines	Patch %	Lines
packages/react/src/jsx-ast/utils/buildContent.mjs	97.08%	3 Missing and 1 partial ⚠️
packages/react/src/jsx-ast/utils/signature.mjs	0.00%	3 Missing ⚠️
.../src/jsx-ast/utils/__tests__/buildContent.test.mjs	99.02%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1047      +/-   ##
==========================================
+ Coverage   89.67%   89.76%   +0.09%     
==========================================
  Files         205      205              
  Lines       19208    19447     +239     
  Branches     1795     1818      +23     
==========================================
+ Hits        17224    17456     +232     
- Misses       1976     1981       +5     
- Partials        8       10       +2

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

github-actions · 2026-08-23T07:29:22Z