docs: S2 docs layout + general improvements #9159

reidbarber · 2025-11-06T23:10:49Z

Add Adobe copyright footer
Make the SideNav / ToC widths static
Fix page min height on mobile
Fix search menu closing when opening links in new tab (listen for custom navigation event)
Show error toast if client route and error page 404 (lost connection or server down)
Show error toast if clipboard copies fail
Move the markdown copy button into area below table of contents
Add "Open in ChatGPT" and "Open in Claude" links to markdown menu
Add skeleton page loading (+ pre-filled page title, + optimistically render sidebar and ToC )
Added prefetching via pointerover listener

✅ Pull Request Checklist:

Included link to corresponding React Spectrum GitHub Issue.
Added/updated unit tests and storybook for this change (for new code or code which already has tests).
Filled out test instructions.
Updated documentation (if it already exists for this component).
Looked at the Accessibility Practices for this feature - Aria Practices

📝 Test Instructions:

🧢 Your Project:

…vements

rspbot · 2025-11-06T23:15:37Z

Build successful! 🎉

majornista · 2025-11-06T23:24:10Z

I think we need to add scroll-padding-block-start: 60px; scroll-padding-block-end: 6px; in the SearchMenu where we have a TagGroup that uses position: sticky that sits on top of the ComponentCardView. We may need to do this with break points, because when the page is resized or scaled, the TagGroup can wrap, which means the scroll-padding-block-start will need to be larger.

react-spectrum/packages/dev/s2-docs/src/SearchMenu.tsx

Line 356 in ab5e6f3

    
           <div className={style({height: 'full', overflow: 'auto', paddingX: 16, paddingBottom: 16})}>

snowystinger

It's strange, there's still a delay moving to the new page with the skeleton. Then the skeleton appears and disappears so fast that it doesn't feel like it's helping with the transition.

devongovett · 2025-11-07T00:34:02Z

@majornista fyi I removed the sticky positioning in this PR: #9135

devongovett

nice! would be cool if we could get optimistic updates working for the sidenav, so when you click a link the selection moves instantly as soon as the skeleton appears. might be able to do that with useOptimistic. ideally the skeleton would also not appear at all if the page load is fast.

packages/dev/s2-docs/src/PageSkeleton.tsx

packages/dev/s2-docs/src/NavigationSuspense.tsx

packages/dev/s2-docs/src/PageSkeleton.tsx

packages/dev/s2-docs/src/NavigationSuspense.tsx

devongovett · 2025-11-07T00:59:02Z

packages/dev/s2-docs/src/Layout.tsx

+                </ScrollableToc>
+                <div className={style({flexShrink: 0})}>
+                  <Divider size="S" styles={style({marginY: 12})} />
+                  <MarkdownMenu url={currentPage.url} />


Question for the team: do we prefer this at the bottom of the page or at the top (i.e. above "on this page")? Most sites seem to have it at the top. I don't mind the bottom but it's a little less prominent. Also moves around a bit depending on the length of the toc.

My reasoning was that the table of contents is more useful most of the time, so it's better when scanning to read that first. Also if we end up adding more actions (feedback button, etc.) it might crowd the top. Definitely open to changing this though.

Also for pages with many sections it renders at the bottom and the ToC has scrolling.

IMO I like it at the bottom, but it really depends on how prominent we want to make it

packages/dev/s2-docs/src/client.tsx

rspbot · 2025-11-07T19:53:10Z

Build successful! 🎉

rspbot · 2025-11-07T20:36:14Z

Build successful! 🎉

rspbot · 2025-11-07T20:56:50Z

Build successful! 🎉

rspbot · 2025-11-07T23:23:20Z

Build successful! 🎉

rspbot · 2025-11-10T16:26:58Z

Build successful! 🎉

rspbot · 2025-11-10T16:49:17Z

Build successful! 🎉

LFDanLu

Looks good to me, approving for testing. Just one small comment

packages/dev/s2-docs/src/SearchMenu.tsx

devongovett · 2025-11-10T18:24:41Z

packages/dev/s2-docs/src/Nav.tsx

+  // Reset pending state when navigation completes
+  useEffect(() => {
+    setPendingPage(null);
+  }, [currentPage.url]);


Did you try useOptimistic for this? With that you setState and it will automatically reset whenever the props change.

devongovett · 2025-11-10T18:27:24Z

packages/dev/s2-docs/src/NavigationSuspense.tsx

+  }
+
+  const [basePathname] = pathname.split('?');
+  const [cleanPathname] = basePathname.split('#');


If you parsed it with new URL then this shouldn't happen. If it didn't start with http then you could assume it's a relative url to the current location? new URL(urlOrPathname, location.href)

devongovett · 2025-11-10T18:33:05Z

packages/dev/s2-docs/src/client.tsx

+  if (raceResult === 'error') {
+    clearPendingPage();
+    if (loadingShown) {
+      setNavigationLoading(false);


Wonder if we could use the promise returned by fetchRSC as the promise that we use() in the suspense boundary instead of managing a separate state here?

devongovett · 2025-11-10T18:34:38Z

packages/dev/s2-docs/src/client.tsx

+  let rscPath = basePath.replace('.html', '.rsc');
+
+  // Use prefetched result if available, otherwise fetch
+  const prefetchedPromise = getPrefetchedPromise(rscPath);


One question is how long the prefetched promises are kept around? If someone loads a docs page and then comes back to the tab a week later and clicks a link, will it use a previously cached result or re-fetch? We may be able to rely on the browser cache to handle this as well – if we just call fetchRSC again it should return a cached result if it's still valid.

devongovett · 2025-11-10T18:49:09Z

packages/dev/s2-docs/src/client.tsx

-    let res = await fetchRSC<ReactElement>(pathname.replace('.html', '.rsc'));
+    raceResult = await Promise.race([
+      fetchPromise.then(() => 'fast' as const).catch(() => 'error' as const),
+      delayPromise.then(() => 'slow' as const)


We may not need the delay - we kinda want the skeleton to show up as fast as possible so the user knows something is happening, but just not when the result is already cached. We can experiment with it.

rspbot · 2025-11-10T18:54:03Z

Build successful! 🎉

reidbarber added 11 commits November 5, 2025 17:13

close SearchMenu on client navigation

2c7e674

add footer

5cb61c3

made Nav and ToC widths static

33f0724

fix min-height issue on mobile

35069c4

show Toast if route can't load

5e84727

add toast for clipboard copy failures

9122573

fix React insertion effect

45ec5f7

improve markdown menu

81f27fb

add skeleton loading for client routing

c35adb7

copy update

c7b2c20

Merge remote-tracking branch 'origin/main' into s2-docs-general-impro…

217f3df

…vements

reidbarber added the ready for review label Nov 6, 2025

snowystinger reviewed Nov 7, 2025

View reviewed changes

devongovett reviewed Nov 7, 2025

View reviewed changes

reidbarber added 4 commits November 7, 2025 09:49

remote extra startTransitions and use use hook

df6fe71

improve skeleton loading and optimistic render link selection + ToC

2bbe51f

add delay to showing skeleton

93dca54

fix getPageInfo logic

9338497

reidbarber removed the ready for review label Nov 7, 2025

reidbarber changed the title ~~docs: S2 docs layout + general improvements~~ WIP: docs: S2 docs layout + general improvements Nov 7, 2025

try fixing getPageInfo again

dc3309a

try fixing normalizePathname on build

25297d3

reidbarber changed the title ~~WIP: docs: S2 docs layout + general improvements~~ docs: S2 docs layout + general improvements Nov 7, 2025

add prefetch onPressStart

aa6ba15

revert optimistic UI and show error toast if fetch fails

9cd4e02

reidbarber changed the title ~~docs: S2 docs layout + general improvements~~ WIP: docs: S2 docs layout + general improvements Nov 7, 2025

fix skeleton title

fbd63dd

don't clear targetPathname until new navigation

31683a3

reidbarber changed the title ~~WIP: docs: S2 docs layout + general improvements~~ docs: S2 docs layout + general improvements Nov 10, 2025

LFDanLu previously approved these changes Nov 10, 2025

View reviewed changes

packages/dev/s2-docs/src/SearchMenu.tsx Show resolved Hide resolved

reidbarber added 2 commits November 10, 2025 12:42

move prefetch to a global pointerover listener

4970161

close search menu when navigation starts

cf27fd3

reidbarber dismissed LFDanLu’s stale review via cf27fd3 November 10, 2025 18:45

devongovett reviewed Nov 10, 2025

View reviewed changes

LFDanLu added the release label Nov 10, 2025

docs: S2 docs layout + general improvements #9159

Are you sure you want to change the base?

docs: S2 docs layout + general improvements #9159

Uh oh!

Conversation

reidbarber commented Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Pull Request Checklist:

📝 Test Instructions:

🧢 Your Project:

Uh oh!

rspbot commented Nov 6, 2025

Uh oh!

majornista commented Nov 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

snowystinger left a comment

Choose a reason for hiding this comment

Uh oh!

devongovett commented Nov 7, 2025

Uh oh!

devongovett left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

devongovett Nov 7, 2025

Choose a reason for hiding this comment

Uh oh!

reidbarber Nov 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LFDanLu Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rspbot commented Nov 7, 2025

Uh oh!

rspbot commented Nov 7, 2025

Uh oh!

rspbot commented Nov 7, 2025

Uh oh!

rspbot commented Nov 7, 2025

Uh oh!

rspbot commented Nov 10, 2025

Uh oh!

rspbot commented Nov 10, 2025

Uh oh!

LFDanLu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

devongovett Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

devongovett Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

devongovett Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

devongovett Nov 10, 2025

Choose a reason for hiding this comment

Uh oh!

devongovett Nov 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rspbot commented Nov 10, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

reidbarber commented Nov 6, 2025 •

edited

Loading

majornista commented Nov 6, 2025 •

edited

Loading

reidbarber Nov 7, 2025 •

edited

Loading

devongovett Nov 10, 2025 •

edited

Loading