docs: S2 docs skeleton loading improvements (#9186)

reidbarber · devongovett · web-flow · commit 382b9351f97a · 2025-11-14T22:21:26.000Z
* add delay for showing page skeleton

* use fake image for SkeletonVisualExample in PageSkeleton

* fix optimistic rendering of the sidenav

* move delay into skeleton and fix clicking already selected link

---------

Co-authored-by: Devon Govett &lt;devongovett@gmail.com&gt;
diff --git a/packages/dev/s2-docs/src/Layout.tsx b/packages/dev/s2-docs/src/Layout.tsx
@@ -1,5 +1,5 @@
 import {ExampleList} from './ExampleList';
-import {Nav, PendingPageProvider} from '../src/Nav';
+import {Nav} from '../src/Nav';
 import {OptimisticMobileToc, OptimisticToc} from './OptimisticToc';
 import type {Page, PageProps} from '@parcel/rsc';
 import React, {ReactElement} from 'react';
@@ -254,93 +254,91 @@ export function Layout(props: PageProps & {children: ReactElement<any>}) {
             }
           })}>
           <Header pages={pages} currentPage={currentPage} />
-          <PendingPageProvider currentPage={currentPage}>
-            <MobileHeader
-              toc={<OptimisticMobileToc currentPage={currentPage} />}
-              pages={pages}
-              currentPage={currentPage} />
-            <div className={style({display: 'flex', width: 'full', flexGrow: {default: 1, lg: 0}})}>
-              {currentPage.exports?.hideNav ? null : <Nav pages={pages} currentPage={currentPage} />}
-              <main
-                key={currentPage.url}
-                style={{borderBottomLeftRadius: 0, borderBottomRightRadius: 0}}
+          <MobileHeader
+            toc={<OptimisticMobileToc currentPage={currentPage} pages={pages} />}
+            pages={pages}
+            currentPage={currentPage} />
+          <div className={style({display: 'flex', width: 'full', flexGrow: {default: 1, lg: 0}})}>
+            {currentPage.exports?.hideNav ? null : <Nav pages={pages} currentPage={currentPage} />}
+            <main
+              key={currentPage.url}
+              style={{borderBottomLeftRadius: 0, borderBottomRightRadius: 0}}
+              className={style({
+                isolation: 'isolate',
+                backgroundColor: 'base',
+                padding: {
+                  default: 12,
+                  lg: 40
+                },
+                borderRadius: {
+                  default: 'none',
+                  lg: 'xl'
+                },
+                boxShadow: {
+                  lg: 'emphasized'
+                },
+                width: 'full',
+                boxSizing: 'border-box',
+                flexGrow: 1,
+                display: 'flex',
+                justifyContent: 'space-between',
+                position: 'relative',
+                height: {
+                  lg: '[calc(100vh - 72px)]'
+                },
+                overflow: {
+                  lg: 'auto'
+                }
+              })}>
+              <div
                 className={style({
-                  isolation: 'isolate',
-                  backgroundColor: 'base',
-                  padding: {
-                    default: 12,
-                    lg: 40
-                  },
-                  borderRadius: {
-                    default: 'none',
-                    lg: 'xl'
-                  },
-                  boxShadow: {
-                    lg: 'emphasized'
-                  },
-                  width: 'full',
-                  boxSizing: 'border-box',
-                  flexGrow: 1,
                   display: 'flex',
-                  justifyContent: 'space-between',
-                  position: 'relative',
+                  flexDirection: 'column',
+                  flexGrow: 1,
+                  width: 'full'
+                })}>
+                <CodePlatterProvider library={getLibraryFromUrl(currentPage.url)}>
+                  <NavigationSuspense pages={pages}>
+                    <article
+                      className={articleStyles({isWithToC: hasToC})}>
+                      {currentPage.exports?.version && <VersionBadge version={currentPage.exports.version} />}
+                      {React.cloneElement(children, {
+                        components: isSubpage ?
+                          subPageComponents(parentPage) :
+                          components,
+                        pages
+                      })}
+                      {currentPage.exports?.relatedPages && (
+                        <MobileRelatedPages pages={currentPage.exports.relatedPages} />
+                      )}
+                    </article>
+                  </NavigationSuspense>
+                </CodePlatterProvider>
+                <Footer />
+              </div>
+              {hasToC && <aside
+                className={style({
+                  position: 'sticky',
+                  top: 0,
                   height: {
+                    default: 'fit',
                     lg: '[calc(100vh - 72px)]'
                   },
-                  overflow: {
-                    lg: 'auto'
-                  }
+                  paddingY: 32,
+                  paddingX: 4,
+                  boxSizing: 'border-box',
+                  width: 180,
+                  flexShrink: 0,
+                  display: {
+                    default: 'none',
+                    lg: 'flex'
+                  },
+                  flexDirection: 'column'
                 })}>
-                <div
-                  className={style({
-                    display: 'flex',
-                    flexDirection: 'column',
-                    flexGrow: 1,
-                    width: 'full'
-                  })}>
-                  <CodePlatterProvider library={getLibraryFromUrl(currentPage.url)}>
-                    <NavigationSuspense pages={pages}>
-                      <article
-                        className={articleStyles({isWithToC: hasToC})}>
-                        {currentPage.exports?.version && <VersionBadge version={currentPage.exports.version} />}
-                        {React.cloneElement(children, {
-                          components: isSubpage ?
-                            subPageComponents(parentPage) :
-                            components,
-                          pages
-                        })}
-                        {currentPage.exports?.relatedPages && (
-                          <MobileRelatedPages pages={currentPage.exports.relatedPages} />
-                        )}
-                      </article>
-                    </NavigationSuspense>
-                  </CodePlatterProvider>
-                  <Footer />
-                </div>
-                {hasToC && <aside
-                  className={style({
-                    position: 'sticky',
-                    top: 0,
-                    height: {
-                      default: 'fit',
-                      lg: '[calc(100vh - 72px)]'
-                    },
-                    paddingY: 32,
-                    paddingX: 4,
-                    boxSizing: 'border-box',
-                    width: 180,
-                    flexShrink: 0,
-                    display: {
-                      default: 'none',
-                      lg: 'flex'
-                    },
-                    flexDirection: 'column'
-                  })}>
-                  <OptimisticToc currentPage={currentPage} />
-                </aside>}
-              </main>
-            </div>
-          </PendingPageProvider>
+                <OptimisticToc currentPage={currentPage} pages={pages} />
+              </aside>}
+            </main>
+          </div>
         </div>
         <ToastContainer placement="bottom" />
       </body>
diff --git a/packages/dev/s2-docs/src/Nav.tsx b/packages/dev/s2-docs/src/Nav.tsx
@@ -2,36 +2,11 @@
 
 import {focusRing, size, style} from '@react-spectrum/s2/style' with {type: 'macro'};
 import {getLibraryFromPage} from './library';
+import {getPageFromPathname, getSnapshot, subscribe} from './NavigationSuspense';
 import {Link} from 'react-aria-components';
 import type {Page, PageProps} from '@parcel/rsc';
 import {Picker, pressScale} from '@react-spectrum/s2';
-import React, {createContext, startTransition, useContext, useEffect, useOptimistic, useRef, useState} from 'react';
-
-export function PendingPageProvider({children, currentPage}: {children: React.ReactNode, currentPage: Page}) {
-  let [displayPage, setDisplayPage] = useOptimistic(
-    currentPage,
-    (_, pendingPage: Page) => pendingPage
-  );
-  
-  useEffect(() => {
-    const unsubscribe = subscribeToClearPendingPage(() => {
-      startTransition(() => {
-        setDisplayPage(currentPage);
-      });
-    });
-    return unsubscribe;
-  }, [currentPage, setDisplayPage]);
-
-  let pendingPage = displayPage.url !== currentPage.url ? displayPage : null;
-
-  return (
-    <PendingPageContext.Provider value={pendingPage}>
-      <PendingNavContext.Provider value={setDisplayPage}>
-        {children}
-      </PendingNavContext.Provider>
-    </PendingPageContext.Provider>
-  );
-}
+import React, {createContext, useContext, useEffect, useRef, useState, useSyncExternalStore} from 'react';
 
 export function Nav({pages, currentPage}: PageProps) {
   let currentLibrary = getLibraryFromPage(currentPage);
@@ -56,7 +31,8 @@ export function Nav({pages, currentPage}: PageProps) {
   }
 
   let [maskSize, setMaskSize] = useState(0);
-  let pendingPage = usePendingPage();
+  const snapshot = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  const pendingPage = snapshot.pathname ? getPageFromPathname(pages, snapshot.pathname) : null;
   let displayUrl = pendingPage?.url ?? currentPage.url;
 
   let sortedSections = [...sections].sort((a, b) => {
@@ -137,24 +113,10 @@ function SideNavSection({title, children}) {
 }
 
 const SideNavContext = createContext('');
-const PendingNavContext = createContext<React.Dispatch<Page> | null>(null);
-const PendingPageContext = createContext<Page | null>(null);
-
-let clearPendingPageListeners = new Set<() => void>();
-
-function subscribeToClearPendingPage(callback: () => void): () => void {
-  clearPendingPageListeners.add(callback);
-  return () => {
-    void clearPendingPageListeners.delete(callback);
-  };
-}
 
-export function clearPendingPage() {
-  clearPendingPageListeners.forEach(callback => callback());
-}
-
-export function usePendingPage() {
-  return useContext(PendingPageContext);
+export function usePendingPage(pages: Page[]): Page | null {
+  const snapshot = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+  return snapshot.pathname ? getPageFromPathname(pages, snapshot.pathname) : null;
 }
 
 export function SideNav({children, isNested = false}) {
@@ -194,22 +156,14 @@ export function SideNavItem(props) {
 export function SideNavLink(props) {
   let linkRef = useRef(null);
   let selected = useContext(SideNavContext);
-  let setPendingPage = useContext(PendingNavContext);
-  let {page, ...linkProps} = props;
+  let {...linkProps} = props;
   
   return (
     <Link
       {...linkProps}
       ref={linkRef}
       aria-current={props.isSelected || selected === props.href ? 'page' : undefined}
       style={pressScale(linkRef)}
-      onPress={() => {
-        if (setPendingPage && page) {
-          startTransition(() => {
-            setPendingPage(page);
-          });
-        }
-      }}
       className={style({
         ...focusRing(),
         minHeight: 32,
diff --git a/packages/dev/s2-docs/src/NavigationSuspense.tsx b/packages/dev/s2-docs/src/NavigationSuspense.tsx
@@ -2,19 +2,21 @@
 
 import type {Page} from '@parcel/rsc';
 import {PageSkeleton} from './PageSkeleton';
-import React, {Suspense, use, useSyncExternalStore} from 'react';
+import React, {Suspense, use, useEffect, useState, useSyncExternalStore} from 'react';
+
+const SKELETON_DELAY = 150;
 
 let navigationPromise: Promise<void> | null = null;
 let targetPathname: string | null = null;
 let listeners = new Set<() => void>();
 let cachedSnapshot: {promise: Promise<void> | null, pathname: string | null} = {promise: null, pathname: null};
 
-function subscribe(callback: () => void) {
+export function subscribe(callback: () => void) {
   listeners.add(callback);
   return () => listeners.delete(callback);
 }
 
-function getSnapshot() {
+export function getSnapshot() {
   if (cachedSnapshot.promise !== navigationPromise || cachedSnapshot.pathname !== targetPathname) {
     cachedSnapshot = {promise: navigationPromise, pathname: targetPathname};
   }
@@ -66,9 +68,9 @@ function getPageTitle(page: Page): string {
   return page.exports?.title ?? page.tableOfContents?.[0]?.title ?? page.name;
 }
 
-function getPageInfo(pages: Page[], pathname: string | null): {title?: string, section?: string, hasToC?: boolean} {
+export function getPageFromPathname(pages: Page[], pathname: string | null): Page | null {
   if (!pathname) {
-    return {};
+    return null;
   }
   
   let publicUrl = process.env.PUBLIC_URL || '/';
@@ -85,6 +87,12 @@ function getPageInfo(pages: Page[], pathname: string | null): {title?: string, s
           normalizedPageUrl === normalizedPathname + '.html';
   });
   
+  return targetPage ?? null;
+}
+
+function getPageInfo(pages: Page[], pathname: string | null): {title?: string, section?: string, hasToC?: boolean} {
+  const targetPage = getPageFromPathname(pages, pathname);
+  
   if (!targetPage) {
     return {};
   }
@@ -99,9 +107,22 @@ function getPageInfo(pages: Page[], pathname: string | null): {title?: string, s
 function NavigationContent({children}: {children: React.ReactNode}) {
   // Subscribe to navigation promise changes to ensure React re-renders when setNavigationPromise() is called.
   const snapshot = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
-  if (snapshot.promise) {
-    use(snapshot.promise);
+  let [delayedPromise, setDelayedPromise] = useState<Promise<void> | null>(null);
+  useEffect(() => {
+    let promise = snapshot.promise;
+    if (!promise) {
+      return;
+    }
+    let timeout = setTimeout(() => {
+      setDelayedPromise(promise);
+    }, SKELETON_DELAY);
+    return () => clearTimeout(timeout);
+  }, [snapshot]);
+
+  if (delayedPromise) {
+    use(delayedPromise);
   }
+
   return <>{children}</>;
 }
 
diff --git a/packages/dev/s2-docs/src/OptimisticToc.tsx b/packages/dev/s2-docs/src/OptimisticToc.tsx
@@ -43,8 +43,8 @@ function renderMobileToc(toc: TocNode[], seen = new Map()) {
   });
 }
 
-export function OptimisticToc({currentPage}: {currentPage: Page}) {
-  let pendingPage = usePendingPage();
+export function OptimisticToc({currentPage, pages}: {currentPage: Page, pages: Page[]}) {
+  let pendingPage = usePendingPage(pages);
   let displayPage = pendingPage ?? currentPage;
   
   return (
@@ -61,8 +61,8 @@ export function OptimisticToc({currentPage}: {currentPage: Page}) {
   );
 }
 
-export function OptimisticMobileToc({currentPage}: {currentPage: Page}) {
-  let pendingPage = usePendingPage();
+export function OptimisticMobileToc({currentPage, pages}: {currentPage: Page, pages: Page[]}) {
+  let pendingPage = usePendingPage(pages);
   let displayPage = pendingPage ?? currentPage;
   
   if ((displayPage.tableOfContents?.[0]?.children?.length ?? 0) <= 1) {
diff --git a/packages/dev/s2-docs/src/PageSkeleton.tsx b/packages/dev/s2-docs/src/PageSkeleton.tsx
diff --git a/packages/dev/s2-docs/src/client.tsx b/packages/dev/s2-docs/src/client.tsx
