Addon Docs: Fix scroll and highlight

[GustavoCostaHenriques]

Closes #26347

What I did

In docs page, if you click on a table-of-contents item, and there is not enough height available in the docs page, it does not change the current state of the table-of-contents. To fix this bug a blank space is added at the end of the page to give it enough height. To add a blank space I created a constant 'Spacer' and then, when the table of contents is exported it's returned this constant.

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

• stories
• unit tests
• integration tests
• end-to-end tests

Manual testing

This section is mandatory for all contributions. If you believe no manual test is necessary, please state so explicitly. Thanks!

Documentation

• Add or update documentation reflecting your changes
• If you are deprecating/removing a feature, make sure to update
  MIGRATION.MD

Checklist for Maintainers

• When this PR is ready for testing, make sure to add ci:normal, ci:merged or ci:daily GH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found in code/lib/cli/src/sandbox-templates.ts

• Make sure this PR contains one of the labels below:

  Available labels

  • bug: Internal changes that fixes incorrect behavior.
  • maintenance: User-facing maintenance tasks.
  • dependencies: Upgrading (sometimes downgrading) dependencies.
  • build: Internal-facing build tooling & test updates. Will not show up in release changelog.
  • cleanup: Minor cleanup style change. Will not show up in release changelog.
  • documentation: Documentation only changes. Will not show up in release changelog.
  • feature request: Introducing a new feature.
  • BREAKING CHANGE: Changes that break compatibility in some way with current major version.
  • other: Changes that don't fit in the above categories.

🦋 Canary release

This PR does not have a canary release associated. You can request a canary release of this pull request by mentioning the @storybookjs/core team here.

core team members can create a canary release here or locally with gh workflow run --repo storybookjs/storybook canary-release-pr.yml --field pr=<PR_NUMBER>

[nx-cloud]

☁️ Nx Cloud Report

CI is running/has finished running commands for commit 843e70c. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this CI Pipeline Execution

---

✅ Successfully ran 1 target

• nx run-many -t build -c production --parallel=3

---

Sent with 💌 from NxCloud.

[tscanlin]

ty!

[Sidnioulz]

The proposed solution looks worse than the problem to me. There is now a page's worth of blank space on pages where the issue occurs:
.

I suggest a fix be found inside tocbot instead. The situation described in the issue is supposed to have an option for handling it (see https://tscanlin.github.io/tocbot/#troubleshooting), which does not work.

[tscanlin]

The proposed solution looks worse than the problem to me. There is now a page's worth of blank space on pages where the issue occurs: .

I suggest a fix be found inside tocbot instead. The situation described in the issue is supposed to have an option for handling it (see https://tscanlin.github.io/tocbot/#troubleshooting), which does not work.

That troubleshooting tip is meant for TOC's with lots of items not one with two items like you have here so I'd say that it doesn't really apply or help here. I have addressed this previously for another user that had a similar question here:
tscanlin/tocbot#277 (comment)

Having whitespace at the bottom of the document to handle this may not seem ideal but I can't think of another way to handle this that's better, can you @Sidnioulz?

[Sidnioulz]

That troubleshooting tip is meant for TOC's with lots of items not one with two items like you have here so I'd say that it doesn't really apply or help here. I have addressed this previously for another user that had a similar question here: tscanlin/tocbot#277 (comment)

Thanks for the context Tim!

Having whitespace at the bottom of the document to handle this may not seem ideal but I can't think of another way to handle this that's better, can you @Sidnioulz?

I have one but it will need a lot more work :)

Let's start with what we know/assume:

• The list of headings is linearly ordered (assumption)
• This issue occurs when you can't scroll down enough to put a heading at the top of the view (+- scroll-margin)
• This is a blind spot of tocbot's item highlight logic; it cannot be fixed without editing the logic

What we can easily deduce:

• There is a specific heading acting as a threshold between the world of headings that can be scrolled to, and those that cannot

My proposal is to apply another logic for handling these last few items starting from the threshold. It should trigger on two conditions:

• When an item is clicked in the tocbot heading
• When a programmatic API endpoint is called with an anchor matching an existing item (we'll need that in Storybook to keep the logic consistent when someone clicks the 🔗 link next to a heading)

When the new logic triggers (item clicked or API call with valid anchor):

• The selected item should first be scrolled to (current behaviour)
• The algorithm should compute the view height, bottom of the view, and vertical position of the item
• If the view height is larger than the delta of bottom and vertical position, we know the scrolling could not work, and therefore the item isn't highlighted
• The algorithm should enter 'bottom mode' and force-highlight the selected item

These JS computations should be acceptable performance-wise:

• They are triggered on atomic user-triggered events that cannot fire more than a few times a second, not by layout/size changes or during render functions
• You can fetch all the necessary geometry data in an animation frame to avoid blocking the main thread
• You can apply best practice to avoid layout thrashing

When to resume the original logic (highlight on scroll only)?

• When the threshold item leaves view from the block end direction (through an IntersectionObserver)

What other events should/could occur?

• You could move the highlight up to the nearest visible heading whenever the currently highlighted item leaves screen (same IntersectionObserver applied to basically all headings between threshold and currently highlighted, so you can check their status all at once in the same observer callback)

---

TL;DR: The current logic has a blind spot that cannot be avoided; an alternative logic needs to be used and crafting it will require significant work.

[tscanlin]

Sorry for the delay @Sidnioulz I was busy with family stuff and was out of town due to the holidays.
But I hear what you are saying and agree that this experience can be made better. I took a stab at updating the highlighting logic in this PR: /~https://github.com/tscanlin/tocbot/pull/370/files

I think it fulfills the requirements of making the other links clickable without having to scroll to them. It also allows for programatic changing as well using a hash change listener. Let me know if you have any feedback.