feat(ui): implement sidebar scroll position preservation

apps/site/components/withSidebar.tsx

@@ -3,9 +3,11 @@
 import Sidebar from '@node-core/ui-components/Containers/Sidebar';
 import { usePathname } from 'next/navigation';
 import { useLocale, useTranslations } from 'next-intl';
+import { useRef } from 'react';
 
 import Link from '#site/components/Link';
 import { useClientContext } from '#site/hooks/client';
+import { useNavigationState } from '#site/hooks/client';
 import { useSiteNavigation } from '#site/hooks/generic';
 import { useRouter } from '#site/navigation.mjs';
 
@@ -25,10 +27,16 @@ const WithSidebar: FC<WithSidebarProps> = ({ navKeys, context, ...props }) => {
   const t = useTranslations();
   const { push } = useRouter();
   const { frontmatter } = useClientContext();
+  const sidebarRef = useRef<HTMLElement>(null);
   const sideNavigation = getSideNavigation(navKeys, context);
 
+  const localePathname = pathname.replace(`/${locale}`, '');
+
+  // Preserve sidebar scroll position across navigations
+  useNavigationState('sidebar', sidebarRef);
+
   const mappedSidebarItems =
-    // If there's only a single navigation key, use it's sub-items
+    // If there's only a single navigation key, use its sub-items
     // as our navigation.
     (navKeys.length === 1 ? sideNavigation[0][1].items : sideNavigation).map(
       ([, { label, items }]) => ({
@@ -39,8 +47,9 @@ const WithSidebar: FC<WithSidebarProps> = ({ navKeys, context, ...props }) => {
 
   return (
     <Sidebar
+      ref={sidebarRef}
       groups={mappedSidebarItems}
-      pathname={pathname.replace(`/${locale}`, '')}
+      pathname={localePathname}
       title={t('components.common.sidebar.title')}
       placeholder={frontmatter?.title}
       onSelect={push}

apps/site/hooks/client/index.ts

@@ -1,3 +1,4 @@
 export { default as useDetectOS } from './useDetectOS';
 export { default as useMediaQuery } from './useMediaQuery';
 export { default as useClientContext } from './useClientContext';
+export { default as useNavigationState } from './useNavigationState';

apps/site/hooks/client/useNavigationState.ts

@@ -0,0 +1,55 @@
+'use client';
+
+import { useCallback, useContext, useEffect, useRef } from 'react';
+
+import { NavigationStateContext } from '#site/providers/navigationStateProvider';
+
+import type { RefObject } from 'react';
+
+const useNavigationState = <T extends HTMLElement>(
+  id: string,
+  ref: RefObject<T | null>,
+  debounceTime = 300
+) => {
+  const navigationState = useContext(NavigationStateContext);
+  const timeoutRef = useRef<NodeJS.Timeout | null>(null);
+
+  const handleScroll = useCallback(() => {
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+    }
+
+    timeoutRef.current = setTimeout(() => {
+      if (ref.current) {
+        navigationState[id] = {
+          x: ref.current.scrollLeft,
+          y: ref.current.scrollTop,
+        };
+      }
+    }, debounceTime);
+  }, [id, ref, navigationState, debounceTime]);
+
+  useEffect(() => {
+    const element = ref.current;
+    if (element) {
+      if (navigationState[id] && navigationState[id].y !== element.scrollTop) {
+        element.scroll({ top: navigationState[id].y, behavior: 'auto' });
+      }
+
+      element.addEventListener('scroll', handleScroll, { passive: true });
+
+      return () => {
+        element.removeEventListener('scroll', handleScroll);
+        // Clear any pending debounced calls
+        if (timeoutRef.current) {
+          clearTimeout(timeoutRef.current);
+          timeoutRef.current = null;
+        }
+      };
+    }
+    // We need this effect to run only on mount
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+};
+
+export default useNavigationState;

packages/ui-components/src/Containers/Sidebar/index.tsx

@@ -1,8 +1,10 @@
+import { forwardRef } from 'react';
+
 import WithNoScriptSelect from '#ui/Common/Select/NoScriptSelect';
 import SidebarGroup from '#ui/Containers/Sidebar/SidebarGroup';
 
 import type { LinkLike } from '#ui/types';
-import type { ComponentProps, FC, PropsWithChildren } from 'react';
+import type { ComponentProps, PropsWithChildren } from 'react';
 
 import styles from './index.module.css';
 
@@ -17,52 +19,48 @@ type SidebarProps = {
   placeholder?: string;
 };
 
-const SideBar: FC<PropsWithChildren<SidebarProps>> = ({
-  groups,
-  pathname,
-  title,
-  onSelect,
-  as,
-  children,
-  placeholder,
-}) => {
-  const selectItems = groups.map(({ items, groupName }) => ({
-    label: groupName,
-    items: items.map(({ label, link }) => ({ value: link, label })),
-  }));
+const SideBar = forwardRef<HTMLElement, PropsWithChildren<SidebarProps>>(
+  ({ groups, pathname, title, onSelect, as, children, placeholder }, ref) => {
+    const selectItems = groups.map(({ items, groupName }) => ({
+      label: groupName,
+      items: items.map(({ label, link }) => ({ value: link, label })),
+    }));
 
-  const currentItem = selectItems
-    .flatMap(item => item.items)
-    .find(item => pathname === item.value);
+    const currentItem = selectItems
+      .flatMap(item => item.items)
+      .find(item => pathname === item.value);
 
-  return (
-    <aside className={styles.wrapper}>
-      {children}
+    return (
+      <aside ref={ref} className={styles.wrapper}>
+        {children}
 
-      {selectItems.length > 0 && (
-        <WithNoScriptSelect
-          label={title}
-          values={selectItems}
-          defaultValue={currentItem?.value}
-          placeholder={placeholder}
-          onChange={onSelect}
-          className={styles.mobileSelect}
-          as={as}
-        />
-      )}
+        {selectItems.length > 0 && (
+          <WithNoScriptSelect
+            label={title}
+            values={selectItems}
+            defaultValue={currentItem?.value}
+            placeholder={placeholder}
+            onChange={onSelect}
+            className={styles.mobileSelect}
+            as={as}
+          />
+        )}
 
-      {groups.map(({ groupName, items }) => (
-        <SidebarGroup
-          key={groupName.toString()}
-          groupName={groupName}
-          items={items}
-          pathname={pathname}
-          as={as}
-          className={styles.navigation}
-        />
-      ))}
-    </aside>
-  );
-};
+        {groups.map(({ groupName, items }) => (
+          <SidebarGroup
+            key={groupName.toString()}
+            groupName={groupName}
+            items={items}
+            pathname={pathname}
+            as={as}
+            className={styles.navigation}
+          />
+        ))}
+      </aside>
+    );
+  }
+);
+
+SideBar.displayName = 'SideBar';
 
 export default SideBar;