Addon-Docs: Change URL hash when TOC item is clicked, and fix TOC loading bugs #30130

Sidnioulz · 2024-12-23T23:51:01Z

Continuation of #23618.

This PR was done to help finalise a contribution from @sookmax. The original PR updated the URL when clicking on a ToC item or scrolling to a new ToC section.

What I did

I made the following changes to the original PR:

TableOfContents: The URL change on scroll was reverted, as requested by @JReinhold in the original review
TableOfContents: Missing useEffect hook dependencies were added in the ToC component
Manager API::url: Added location hash to internal navigation events so it's preserved on initial load and when globalsUpdated fires
nit: The git history was rewritten to better qualify and scope changes

As a result, the URL no longer updates when users scroll, and the page now correctly loads on the right docs subsection when loading Storybook with a location hash set.

Checklist for Contributors

Testing

Caution

The original PR did not introduce tests, and neither does this one. I'd like to be advised on how best to proceed. I've tried, without much conviction, to build a stories file but I'd need to mock the channel for this and I don't know how to.

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

stories
unit tests
integration tests
end-to-end tests

Manual testing

Checkout the repo, compile, and run storybook:ui
Open http://localhost:6006/?path=/docs/core-tags-config--docs#inheritance in your browser
Notice how a scroll event occurs and takes you to the relevant section

Section IDs with a space need to be URL encoded. The ID generated in MDX already contains %20, so that needs to be encoded to %2520 to load properly.

Checkout as above
Open http://localhost:6006/?path=/docs/core-tags-config--docs#tag%20removal this time
Notice how you do not get scrolled to the relevant section
Open http://localhost:6006/?path=/docs/core-tags-config--docs#tag%2520removal this time
Notice that now, it loads

Note

If maintainers know where I can edit the behaviour that generates header IDs in the docs addon, I'll happily adjust it to use _ instead of %20 to help keep URL hashes cleaner.

Caution

The 🔗 links next to headings in the addon-doc also need to be URL encoded so we get the %2520 link that will work with tocbot. I feel the better solution is to adjust all links to use _ rather than further mess with that code. Please let me know how you'd prefer me to proceed.

Documentation

Note

I do not think documentation changes are relevant here.

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-storybook/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>

name	before	after	diff	z	%
createSize	0 B	0 B	0 B	-	-
generateSize	77.9 MB	77.9 MB	0 B	1.54	0%
initSize	131 MB	131 MB	26.5 kB	3.14	0%
diffSize	52.9 MB	53 MB	26.5 kB	2.17	0.1%
buildSize	7.19 MB	7.21 MB	26.1 kB	1164.29	0.4%
buildSbAddonsSize	1.85 MB	1.86 MB	17.2 kB	1148.05	0.9%
buildSbCommonSize	195 kB	195 kB	0 B	-	0%
buildSbManagerSize	1.87 MB	1.87 MB	192 B	11.3	0%
buildSbPreviewSize	0 B	0 B	0 B	-	-
buildStaticSize	0 B	0 B	0 B	-	-
buildPrebuildSize	3.91 MB	3.93 MB	17.3 kB	871.41	0.4%
buildPreviewSize	3.28 MB	3.29 MB	8.76 kB	1858.89	0.3%
testBuildSize	0 B	0 B	0 B	-	-
testBuildSbAddonsSize	0 B	0 B	0 B	-	-
testBuildSbCommonSize	0 B	0 B	0 B	-	-
testBuildSbManagerSize	0 B	0 B	0 B	-	-
testBuildSbPreviewSize	0 B	0 B	0 B	-	-
testBuildStaticSize	0 B	0 B	0 B	-	-
testBuildPrebuildSize	0 B	0 B	0 B	-	-
testBuildPreviewSize	0 B	0 B	0 B	-	-

name	before	after	diff	z	%
createTime	18.3s	24.1s	5.7s	1.35	🔺24%
generateTime	20.4s	19.3s	-1s -139ms	-1.03	-5.9%
initTime	14s	13.3s	-762ms	-0.77	-5.7%
buildTime	9.4s	11.3s	1.8s	2.38	🔺16.3%
testBuildTime	0ms	0ms	0ms	-	-
devPreviewResponsive	5.4s	4.4s	-1s -13ms	-1.16	-22.8%
devManagerResponsive	4s	3.2s	-812ms	-1.23	-24.9%
devManagerHeaderVisible	766ms	548ms	-218ms	-0.97	-39.8%
devManagerIndexVisible	800ms	577ms	-223ms	-1.03	-38.6%
devStoryVisibleUncached	2s	1.9s	-98ms	0.28	-5%
devStoryVisible	801ms	578ms	-223ms	-1.06	-38.6%
devAutodocsVisible	702ms	526ms	-176ms	-0.48	-33.5%
devMDXVisible	589ms	502ms	-87ms	-0.73	-17.3%
buildManagerHeaderVisible	624ms	551ms	-73ms	-0.47	-13.2%
buildManagerIndexVisible	714ms	634ms	-80ms	-0.51	-12.6%
buildStoryVisible	592ms	533ms	-59ms	-0.53	-11.1%
buildAutodocsVisible	452ms	442ms	-10ms	-0.61	-2.3%
buildMDXVisible	457ms	426ms	-31ms	-0.82	-7.3%

Greptile Summary

Here's my concise review of the changes focused on fixing Table of Contents URL handling and navigation:

Updates Table of Contents functionality to properly handle URL hash navigation and preserve hash fragments across state changes, focusing on consistent URL behavior.

Added hash preservation in code/core/src/manager-api/modules/url.ts for navigation events and state updates
Fixed URL hash handling in code/lib/blocks/src/components/TableOfContents.tsx by emitting proper NAVIGATE_URL events
Updated useNavigate hook in code/core/src/router/router.tsx to handle empty hash navigation correctly
Added missing cleanup for setTimeout and error handling in code/lib/blocks/src/blocks/DocsContainer.tsx

_{💡 (5/5) You can turn off certain types of comments like style here!}

greptile-apps

_{4 file(s) reviewed, 4 comment(s)}
_{Edit PR Review Bot Settings | Greptile}

code/core/src/manager-api/modules/url.ts

code/lib/blocks/src/components/TableOfContents.tsx

code/core/src/manager-api/modules/url.ts

greptile-apps · 2024-12-23T23:51:40Z

code/core/src/router/router.tsx

    if (typeof to === 'string' && to.startsWith('#')) {
-      document.location.hash = to;
+      if (to === '#') {
+        navigate(document.location.search);
+      } else {
+        document.location.hash = to;
+      }
      return undefined;


logic: this new hash handling could cause issues if document.location.search is empty - consider falling back to '/' or preserving the current path

false positive, prior PR code

nx-cloud · 2024-12-23T23:55:35Z

View your CI Pipeline Execution ↗ for commit c1b9a94.

Command	Status	Duration	Result
`nx run-many -t build --parallel=3`	✅ Succeeded	1m 35s	View ↗

☁️ Nx Cloud last updated this comment at 2025-01-15 11:03:45 UTC

Sidnioulz · 2024-12-24T00:38:39Z

Note the failing unit tests on https://github.com/storybookjs/storybook/actions/runs/12474578164/job/34816789722?pr=30130.

RouterData is supposed to always contain a location object, but it appears to be null in some states. I could address this in the code by using optional chaining when initialising hash, but there might be something to fix in these unit tests' context too. WDYT?

JReinhold · 2025-01-13T14:16:43Z

Let's try to improve the slugs of heading's IDs, turning spaces into dashes to avoid %20 in the URL. I think this is currently done via https://github.com/rehypejs/rehype-slug

Co-authored-by: Norbert de Langen <[email protected]>

…section

Sidnioulz · 2025-01-15T09:49:00Z

Let's try to improve the slugs of heading's IDs, turning spaces into dashes to avoid %20 in the URL. I think this is currently done via https://github.com/rehypejs/rehype-slug

Turns out the block responsible for those headings was not yet using slugs. I've used github-slugger which is internally used by rehype-slug in the relevant component. I find it odd that rehype-slug is listed as a devDep for the addon-docs though rather than a runtime dep. I've added github-slugger as a runtime dep to blocks but that can be adjusted if needed.

Will now wait for CI to run and then address the failing tests.

storybook-pr-benchmarking · 2025-01-15T10:01:30Z

Package Benchmarks

^{Commit: c1b9a94, ran on 15 January 2025 at 11:08:43 UTC}

The following packages have significant changes to their size or dependencies:

`@storybook/addon-docs`

	Before	After	Difference
Dependency count	17	18	🚨 +1 🚨
Self size	2.20 MB	2.20 MB	0 B
Dependency size	7.88 MB	7.90 MB	🚨 +17 KB 🚨
Bundle Size Analyzer	Link	Link

`@storybook/addon-essentials`

	Before	After	Difference
Dependency count	36	37	🚨 +1 🚨
Self size	12 KB	12 KB	0 B
Dependency size	13.83 MB	13.86 MB	🚨 +26 KB 🚨
Bundle Size Analyzer	Link	Link

`@storybook/blocks`

	Before	After	Difference
Dependency count	4	5	🚨 +1 🚨
Self size	604 KB	605 KB	🚨 +887 B 🚨
Dependency size	1.49 MB	1.51 MB	🚨 +16 KB 🚨
Bundle Size Analyzer	Link	Link

Sidnioulz · 2025-01-17T08:22:07Z

@JReinhold CI now passing, this should be ready for review :)

greptile-apps bot reviewed Dec 23, 2024

View reviewed changes

Sidnioulz mentioned this pull request Dec 23, 2024

Addon-Docs: Change URL hash when TOC item is clicked and when scrolling #23618

Closed

5 tasks

Sidnioulz force-pushed the update-23618-fix-toc-onclick branch from 3663df5 to c9d5743 Compare December 24, 2024 00:02

Sidnioulz changed the title ~~Update 23618 fix toc onclick~~ Addon-Docs: Change URL hash when TOC item is clicked, and fix TOC loading bugs Dec 24, 2024

This was referenced Dec 24, 2024

[Bug]: docs-mode table-of-contents does not change URL when clicking on an anchor #26345

Open

[Bug]: hash navigation does not work #29361

Open

Sidnioulz self-assigned this Dec 24, 2024

Sidnioulz added bug core addon: docs ci:normal labels Dec 24, 2024

JReinhold self-assigned this Jan 13, 2025

JReinhold self-requested a review January 13, 2025 14:17

sookmax and others added 6 commits January 14, 2025 17:06

Addon-docs: Change URL hash when ToC item is clicked and when scrolling

8d95435

Router: Strengthen detection of empty URL hash

ea41c44

Co-authored-by: Norbert de Langen <[email protected]>

Addon-docs: Revert updating the URL hash when scrolling to a new ToC …

3b216e1

…section

Core: Preserve location hash in URL Core API

5f4bf17

Addon-docs: URL encode anchor IDs when clicking in ToC

b60c15b

Addon-docs: Make Table of Content click handler safer

51f4b60

Sidnioulz force-pushed the update-23618-fix-toc-onclick branch from f07cf4a to 51f4b60 Compare January 14, 2025 16:06

Blocks: Ensure Subheading slugs heading IDs to remove spaces

961f458

Manager: Fix state management in URL tests

c1b9a94

kroeder mentioned this pull request Jan 17, 2025

Search: Add docs headings to index #26531

Draft

11 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Addon-Docs: Change URL hash when TOC item is clicked, and fix TOC loading bugs #30130

Addon-Docs: Change URL hash when TOC item is clicked, and fix TOC loading bugs #30130

Sidnioulz commented Dec 23, 2024 •

edited by storybook-pr-benchmarking bot

Loading

greptile-apps bot left a comment

greptile-apps bot Dec 23, 2024

Sidnioulz Dec 24, 2024

nx-cloud bot commented Dec 23, 2024 •

edited

Loading

Sidnioulz commented Dec 24, 2024

JReinhold commented Jan 13, 2025

Sidnioulz commented Jan 15, 2025

storybook-pr-benchmarking bot commented Jan 15, 2025 •

edited

Loading

Sidnioulz commented Jan 17, 2025

Addon-Docs: Change URL hash when TOC item is clicked, and fix TOC loading bugs #30130

Are you sure you want to change the base?

Addon-Docs: Change URL hash when TOC item is clicked, and fix TOC loading bugs #30130

Conversation

Sidnioulz commented Dec 23, 2024 • edited by storybook-pr-benchmarking bot Loading

What I did

Checklist for Contributors

Testing

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

Manual testing

Documentation

Checklist for Maintainers

🦋 Canary release

Greptile Summary

greptile-apps bot left a comment

Choose a reason for hiding this comment

greptile-apps bot Dec 23, 2024

Choose a reason for hiding this comment

Sidnioulz Dec 24, 2024

Choose a reason for hiding this comment

nx-cloud bot commented Dec 23, 2024 • edited Loading

Sidnioulz commented Dec 24, 2024

JReinhold commented Jan 13, 2025

Sidnioulz commented Jan 15, 2025

storybook-pr-benchmarking bot commented Jan 15, 2025 • edited Loading

Package Benchmarks

@storybook/addon-docs

@storybook/addon-essentials

@storybook/blocks

Sidnioulz commented Jan 17, 2025

Sidnioulz commented Dec 23, 2024 •

edited by storybook-pr-benchmarking bot

Loading

nx-cloud bot commented Dec 23, 2024 •

edited

Loading

storybook-pr-benchmarking bot commented Jan 15, 2025 •

edited

Loading

`@storybook/addon-docs`

`@storybook/addon-essentials`

`@storybook/blocks`