fix: HashRouter navigation not working in web component contexts

React Router v6's HashRouter doesn't properly respond to hash changes when
used in web component contexts (Custom Elements with Shadow DOM) or when
embedded in other SPA frameworks like VitePress.

This commit adds a HashRouterSync component that:
- Listens for hash change and popstate events
- Forces React Router to navigate when the browser hash changes
- Ensures content updates when users click navigation links
- Only activates when router type is 'hash'

The fix is transparent to users and requires no API changes.

Fixes navigation issues reported with Elements v9.0.12 after the React
Router v5 to v6 upgrade (commit 8520585).

Technical details:
- Created HashRouterSync component using useNavigate and useLocation hooks
- Integrated into withRouter HOC's InternalRoutes
- Syncs on mount, hashchange, and popstate events
- Prevents infinite loops by tracking current hash state

Testing: This fix has been validated in VitePress environments with
hash-based navigation, confirming that:
- URL updates correctly on navigation
- Content refreshes when clicking navigation links
- Browser back/forward buttons work properly
- No performance impact or console errors

Author: Drew Zhao

packages/elements-core/src/components/HashRouterSync/index.tsx

@@ -0,0 +1,58 @@
+import { useEffect } from 'react';
+import { useNavigate, useLocation } from 'react-router-dom';
+
+/**
+ * HashRouterSync ensures React Router v6's HashRouter properly responds to hash changes
+ * when used in web component contexts (like Custom Elements with Shadow DOM).
+ * 
+ * The issue: React Router v6's HashRouter doesn't always detect hash changes when:
+ * - Embedded in a web component
+ * - Running inside another SPA framework (e.g., VitePress)
+ * - Events don't properly bubble through Shadow DOM boundaries
+ * 
+ * This component listens for hash changes and forces React Router to navigate,
+ * ensuring content updates when users click navigation links.
+ */
+export const HashRouterSync = (): null => {
+  const navigate = useNavigate();
+  const location = useLocation();
+
+  useEffect(() => {
+    // Track the current hash to detect changes
+    let currentHash = window.location.hash;
+
+    const syncHashWithRouter = () => {
+      const newHash = window.location.hash;
+      
+      // Only navigate if the hash actually changed and doesn't match React Router's current location
+      if (newHash !== currentHash) {
+        currentHash = newHash;
+        
+        // Extract the path from the hash (e.g., "#/path" -> "/path")
+        const path = newHash.slice(1) || '/';
+        
+        // Only navigate if React Router isn't already at this path
+        if (location.pathname + location.search + location.hash !== path) {
+          navigate(path, { replace: true });
+        }
+      }
+    };
+
+    // Listen for hash changes from the browser
+    window.addEventListener('hashchange', syncHashWithRouter);
+
+    // Also listen for popstate events (browser back/forward)
+    window.addEventListener('popstate', syncHashWithRouter);
+
+    // Sync on mount to handle direct navigation to hashed URLs
+    syncHashWithRouter();
+
+    return () => {
+      window.removeEventListener('hashchange', syncHashWithRouter);
+      window.removeEventListener('popstate', syncHashWithRouter);
+    };
+  }, [navigate, location]);
+
+  return null;
+};
+

packages/elements-core/src/hoc/withRouter.tsx

@@ -2,6 +2,7 @@ import { DefaultComponentMapping } from '@stoplight/markdown-viewer';
 import * as React from 'react';
 import { Route, Routes, useInRouterContext } from 'react-router-dom';
 
+import { HashRouterSync } from '../components/HashRouterSync';
 import { LinkHeading } from '../components/LinkHeading';
 import { MarkdownComponentsProvider } from '../components/MarkdownViewer/CustomComponents/Provider';
 import { ReactRouterMarkdownLink } from '../components/MarkdownViewer/CustomComponents/ReactRouterLink';
@@ -18,14 +19,22 @@ const components: Partial<DefaultComponentMapping> = {
   h4: ({ color, ...props }) => <LinkHeading size={4} {...props} />,
 };
 
-const InternalRoutes = ({ children }: { children: React.ReactNode }): JSX.Element => {
+const InternalRoutes = ({ 
+  children, 
+  routerType 
+}: { 
+  children: React.ReactNode;
+  routerType: string;
+}): JSX.Element => {
   return (
     <Routes>
       <Route
         path="/*"
         element={
           <MarkdownComponentsProvider value={components}>
             <ScrollToHashElement />
+            {/* Sync hash changes with React Router when using HashRouter */}
+            {routerType === 'hash' && <HashRouterSync />}
             {children}
           </MarkdownComponentsProvider>
         }
@@ -48,7 +57,7 @@ export function withRouter<P extends RoutingProps>(
       return (
         <RouterTypeContext.Provider value={routerType}>
           <Router {...routerProps} key={basePath}>
-            <InternalRoutes>
+            <InternalRoutes routerType={routerType}>
               <WrappedComponent {...props} outerRouter={false} />
             </InternalRoutes>
           </Router>
@@ -58,7 +67,7 @@ export function withRouter<P extends RoutingProps>(
 
     return (
       <RouterTypeContext.Provider value={routerType}>
-        <InternalRoutes>
+        <InternalRoutes routerType={routerType}>
           <WrappedComponent {...props} outerRouter />
         </InternalRoutes>
       </RouterTypeContext.Provider>

packages/elements-core/src/index.ts

@@ -12,6 +12,7 @@ export {
 } from './components/MarkdownViewer/CustomComponents/Provider';
 export { ReactRouterMarkdownLink } from './components/MarkdownViewer/CustomComponents/ReactRouterLink';
 export { ScrollToHashElement } from './components/MarkdownViewer/CustomComponents/ScrollToHashElement';
+export { HashRouterSync } from './components/HashRouterSync';
 export { NonIdealState } from './components/NonIdealState';
 export { PoweredByLink } from './components/PoweredByLink';
 export { TableOfContents } from './components/TableOfContents';