Addon-docs: Add opt-in table of contents

[shilman]

Closes N/A

What I did

Added opt-in TOC to docs page to address the sidebar navigation issues caused by the 7.0 docs changes.

This is the "built-in" version of https://github.com/storybookjs/addon-toc/pull/1

Added:

• docs.toc parameter
• Example stories to demonstrate the key configuration parameters

How to test

1. Spin up a sandbox.
2. Browse to the added addon-docs/toc stories which demonstrate different configurations
3. Add docs.toc = { } parameter to .storybook/preview.js to see how it looks for all the pages

[socket-security]

👍 Dependency issues cleared. Learn more about Socket for GitHub ↗︎

This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored.

[socket-security]

New dependencies detected. Learn more about Socket for GitHub ↗︎

Packages	Version	New capabilities	Transitives	Size	Publisher
tocbot	4.21.0	network, environment	+0	807 kB	tscanlin

[kylegach]

Love this, and I think a lot of users will too. ❤️

Strangely, when I spun up a sandbox (yarn task --task sandbox --template react-vite/default-ts) the TOC was rendered despite seemingly no opting-in in either preview.ts or any of the CSF files (i.e. I didn't modify anything and it was there). 🤷‍♂️

I also have some UI-related feedback:

1. Rather than hide for narrow viewports, could we render it under the component description in a <details>? So it's still usable, but doesn't take up a bunch of vertical room unless expanded. I can provide that code, if helpful.

2. The "highlight the active item" logic is a bit buggy in my testing. It seems to work OK when just scrolling. But while clicking an item correctly scrolls to it in the viewport, it doesn't highlight most of the time. If we can't polish it right now, I'd prefer we simply disable the behavior entirely, if possible.

[kylegach]

Oh, and a small process meta note: We use the "Docs" PR title area for documentation updates. Would "Addon docs" be better here, to differentiate? Should documentation updates use something else?

[ndelangen]

@shilman I marked this ready for review, do you agree we can move this forwards?

[JReinhold]

Can we add stories for this? Maybe that's a bit complicated, but then at least some MDX files that shows it off. (maybe in a separate PR)

[shilman]

@JReinhold I added stories to the PR

@kylegach I fixed the bug where TOC is always enabled. Open to UI improvements to this -- we're just using the default behavior of tocbot and I feel it's quite rough. I'm not sure whether it's our usage or whether that's just the fault of the library.

[JReinhold]

Everything looks good, only minor comments. 💪

@kylegach

Rather than hide for narrow viewports, could we render it under the component description in a <details>? So it's still usable, but doesn't take up a bunch of vertical room unless expanded. I can provide that code, if helpful.

I agree this would be an interesting improvement if we can get the design right, but it shouldn't block this initial implementation

The "highlight the active item" logic is a bit buggy in my testing. It seems to work OK when just scrolling. But while clicking an item correctly scrolls to it in the viewport, it doesn't highlight most of the time. If we can't polish it right now, I'd prefer we simply disable the behavior entirely, if possible.

This buggy behaviour is pretty noticeable in our case, because story headings often don't fully scroll to the top. From the tocbot code it looks like this is just how it works and there's no way to configure it: https://github.com/tscanlin/tocbot/blob/master/src/js/build-html.js#L179-L197

There might be hacky workarounds for this, but no easy fix.

[JReinhold]

Do I understand this correctly, that if a user has toc in project annotations, and for a single component have disable, we always show the TOC container (but sometimes empty), so that layout won't shift?

But if the user doesn't have toc set global, but just for a single story, then we'll have layout shifts?

I think this is a good solution, I just want to make sure my understanding is correct.

[shilman]

I believe so. This is @cdedreuille 's comment I believe.