From decb7712e0101b8a5ee3aec4a179fd162669dc41 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <98355961+LadyBluenotes@users.noreply.github.com>
Date: Tue, 17 Mar 2026 12:08:20 -0700
Subject: [PATCH] fix docs navigation stability and search filter interactions

---
 src/components/CopyPageDropdown.tsx      |  5 +-
 src/components/DocsLayout.tsx            | 97 +++++++++++++++++++-----
 src/components/SearchModal.tsx           | 18 +++--
 src/routes/$libraryId/$version.docs.tsx  | 21 ++++-
 src/routes/$libraryId/$version.index.tsx | 15 +++-
 src/routes/$libraryId/$version.tsx       | 28 +++++--
 src/routes/admin/audit.tsx               |  1 +
 src/routes/admin/github-stats.tsx        |  1 +
 src/routes/admin/logins.tsx              |  1 +
 src/routes/admin/npm-stats.tsx           |  1 +
 src/routes/admin/roles.$roleId.tsx       |  1 +
 11 files changed, 147 insertions(+), 42 deletions(-)

diff --git a/src/components/CopyPageDropdown.tsx b/src/components/CopyPageDropdown.tsx
index b9e5e0c4..8f4cdf73 100644
--- a/src/components/CopyPageDropdown.tsx
+++ b/src/components/CopyPageDropdown.tsx
@@ -10,10 +10,7 @@ import {
   DropdownContent,
   DropdownItem,
 } from './Dropdown'
-import {
-  getPackageManager,
-  PACKAGE_MANAGERS,
-} from '~/utils/markdown/installCommand'
+import { getPackageManager } from '~/utils/markdown/installCommand'
 
 // Markdown icon component matching the screenshot
 function MarkdownIcon({ className }: { className?: string }) {
diff --git a/src/components/DocsLayout.tsx b/src/components/DocsLayout.tsx
index c94b8ae7..2bf17a34 100644
--- a/src/components/DocsLayout.tsx
+++ b/src/components/DocsLayout.tsx
@@ -534,28 +534,59 @@ export function DocsLayout({
       d.status === 'active' && d.name !== 'Nozzle.io' && d.id !== 'fireship',
   )
 
-  const menuItems = menuConfig.map((group, i) => {
-    const WrapperComp = group.collapsible ? 'details' : 'div'
-    const LabelComp = group.collapsible ? 'summary' : 'div'
+  const groupInitialOpenState = React.useMemo(() => {
+    return menuConfig.reduce<Record<string, boolean>>((acc, group, index) => {
+      const isChildActive = group.children.some((child) => child.to === _splat)
+      const key = `${index}:${String(group.label)}`
 
-    const isChildActive = group.children.some((d) => d.to === _splat)
-    const configGroupOpenState =
-      typeof group.defaultCollapsed !== 'undefined'
-        ? !group.defaultCollapsed // defaultCollapsed is true means the group is closed
-        : undefined
-    const isOpen = isChildActive ? true : (configGroupOpenState ?? false)
+      acc[key] = isChildActive
+        ? true
+        : typeof group.defaultCollapsed !== 'undefined'
+          ? !group.defaultCollapsed
+          : false
 
-    const detailsProps = group.collapsible ? { open: isOpen } : {}
+      return acc
+    }, {})
+  }, [menuConfig, _splat])
 
-    return (
-      <WrapperComp
-        key={`group-${i}`}
-        className="[&>summary]:before:mr-1 [&>summary]:marker:text-[0.8em] [&>summary]:marker:leading-4 relative select-none"
-        {...detailsProps}
-      >
-        <LabelComp className="text-[.8em] font-bold leading-4 px-2 ts-sidebar-label">
-          {group?.label}
-        </LabelComp>
+  const [openGroups, setOpenGroups] = React.useState(groupInitialOpenState)
+
+  React.useEffect(() => {
+    setOpenGroups((prev) => {
+      let hasChanged = false
+      const next = { ...prev }
+
+      Object.entries(groupInitialOpenState).forEach(([key, isOpen]) => {
+        if (!(key in next)) {
+          next[key] = isOpen
+          hasChanged = true
+          return
+        }
+
+        if (isOpen && !next[key]) {
+          next[key] = true
+          hasChanged = true
+        }
+      })
+
+      return hasChanged ? next : prev
+    })
+  }, [groupInitialOpenState])
+
+  const menuItems = menuConfig.map((group, i) => {
+    const groupKey = `${i}:${String(group.label)}`
+
+    const groupContent = (
+      <>
+        {group.collapsible ? (
+          <summary className="text-[.8em] font-bold leading-4 px-2 ts-sidebar-label">
+            {group.label}
+          </summary>
+        ) : (
+          <div className="text-[.8em] font-bold leading-4 px-2 ts-sidebar-label">
+            {group.label}
+          </div>
+        )}
         <div className="h-2" />
         <ul className="text-[.85em] leading-snug list-none">
           {group?.children?.map((child, i) => {
@@ -580,6 +611,7 @@ export function DocsLayout({
                     onClick={() => {
                       detailsRef.current.removeAttribute('open')
                     }}
+                    preload={false}
                     activeOptions={{
                       exact: true,
                       includeHash: false,
@@ -614,7 +646,32 @@ export function DocsLayout({
             )
           })}
         </ul>
-      </WrapperComp>
+      </>
+    )
+
+    return group.collapsible ? (
+      <details
+        key={`group-${i}`}
+        className="[&>summary]:before:mr-1 [&>summary]:marker:text-[0.8em] [&>summary]:marker:leading-4 relative select-none"
+        open={openGroups[groupKey] ?? false}
+        onToggle={(event) => {
+          const nextOpen = event.currentTarget.open
+          setOpenGroups((prev) =>
+            prev[groupKey] === nextOpen
+              ? prev
+              : { ...prev, [groupKey]: nextOpen },
+          )
+        }}
+      >
+        {groupContent}
+      </details>
+    ) : (
+      <div
+        key={`group-${i}`}
+        className="[&>summary]:before:mr-1 [&>summary]:marker:text-[0.8em] [&>summary]:marker:leading-4 relative select-none"
+      >
+        {groupContent}
+      </div>
     )
   })
 
diff --git a/src/components/SearchModal.tsx b/src/components/SearchModal.tsx
index eb00b314..1c7c7130 100644
--- a/src/components/SearchModal.tsx
+++ b/src/components/SearchModal.tsx
@@ -565,9 +565,12 @@ function LibraryRefinement() {
   const currentLibrary = libraries.find((l) => l.id === selectedLibrary)
 
   return (
-    <Dropdown>
-      <DropdownTrigger asChild={false}>
-        <button className="flex items-center gap-1 text-sm focus:outline-none cursor-pointer font-bold">
+    <Dropdown modal={false}>
+      <DropdownTrigger>
+        <button
+          type="button"
+          className="flex items-center gap-1 text-sm focus:outline-none cursor-pointer font-bold"
+        >
           {currentLibrary ? (
             <span className="uppercase font-black [letter-spacing:-.05em]">
               <span className="opacity-50">TanStack</span>{' '}
@@ -637,9 +640,12 @@ function FrameworkRefinement() {
   )
 
   return (
-    <Dropdown>
-      <DropdownTrigger asChild={false}>
-        <button className="flex items-center gap-1 text-sm font-bold focus:outline-none cursor-pointer">
+    <Dropdown modal={false}>
+      <DropdownTrigger>
+        <button
+          type="button"
+          className="flex items-center gap-1 text-sm font-bold focus:outline-none cursor-pointer"
+        >
           {currentFramework && (
             <img
               src={currentFramework.logo}
diff --git a/src/routes/$libraryId/$version.docs.tsx b/src/routes/$libraryId/$version.docs.tsx
index 915da403..3dee7ff1 100644
--- a/src/routes/$libraryId/$version.docs.tsx
+++ b/src/routes/$libraryId/$version.docs.tsx
@@ -1,13 +1,22 @@
-import { Outlet, useMatch, createFileRoute } from '@tanstack/react-router'
+import {
+  Outlet,
+  useMatch,
+  notFound,
+  createFileRoute,
+} from '@tanstack/react-router'
 import { DocsLayout } from '~/components/DocsLayout'
-import { getLibrary } from '~/libraries'
+import { findLibrary } from '~/libraries'
 import { seo } from '~/utils/seo'
 import type { ConfigSchema } from '~/utils/config'
 
 export const Route = createFileRoute('/$libraryId/$version/docs')({
   head: (ctx) => {
     const { libraryId } = ctx.params
-    const library = getLibrary(libraryId)
+    const library = findLibrary(libraryId)
+
+    if (!library) {
+      throw notFound()
+    }
 
     return {
       meta: seo({
@@ -27,7 +36,11 @@ export const Route = createFileRoute('/$libraryId/$version/docs')({
 
 function DocsRoute() {
   const { libraryId, version } = Route.useParams()
-  const library = getLibrary(libraryId)
+  const library = findLibrary(libraryId)
+
+  if (!library) {
+    throw notFound()
+  }
   const versionMatch = useMatch({ from: '/$libraryId/$version' })
   const { config } = versionMatch.loaderData as { config: ConfigSchema }
 
diff --git a/src/routes/$libraryId/$version.index.tsx b/src/routes/$libraryId/$version.index.tsx
index 002da917..2e1f47ac 100644
--- a/src/routes/$libraryId/$version.index.tsx
+++ b/src/routes/$libraryId/$version.index.tsx
@@ -2,10 +2,11 @@ import {
   useMatch,
   redirect,
   Link,
+  notFound,
   createFileRoute,
 } from '@tanstack/react-router'
 import { DocsLayout } from '~/components/DocsLayout'
-import { getLibrary } from '~/libraries'
+import { findLibrary } from '~/libraries'
 import type { LibraryId } from '~/libraries'
 import { seo } from '~/utils/seo'
 
@@ -52,7 +53,11 @@ const landingComponents: Partial<Record<LibraryId, ComponentType>> = {
 export const Route = createFileRoute('/$libraryId/$version/')({
   head: (ctx) => {
     const { libraryId } = ctx.params
-    const library = getLibrary(libraryId)
+    const library = findLibrary(libraryId)
+
+    if (!library) {
+      throw notFound()
+    }
 
     return {
       meta: seo({
@@ -79,7 +84,11 @@ export const Route = createFileRoute('/$libraryId/$version/')({
 
 function LibraryVersionIndex() {
   const { libraryId, version } = Route.useParams()
-  const library = getLibrary(libraryId)
+  const library = findLibrary(libraryId)
+
+  if (!library) {
+    throw notFound()
+  }
   const versionMatch = useMatch({ from: '/$libraryId/$version' })
   const { config } = versionMatch.loaderData as { config: ConfigSchema }
 
diff --git a/src/routes/$libraryId/$version.tsx b/src/routes/$libraryId/$version.tsx
index 82f9feb9..58987812 100644
--- a/src/routes/$libraryId/$version.tsx
+++ b/src/routes/$libraryId/$version.tsx
@@ -1,13 +1,22 @@
-import { Outlet, redirect, createFileRoute } from '@tanstack/react-router'
+import {
+  Outlet,
+  redirect,
+  notFound,
+  createFileRoute,
+} from '@tanstack/react-router'
 import { RedirectVersionBanner } from '~/components/RedirectVersionBanner'
-import { getBranch, getLibrary } from '~/libraries'
+import { findLibrary, getBranch } from '~/libraries'
 import { getTanstackDocsConfig } from '~/utils/config'
 
 export const Route = createFileRoute('/$libraryId/$version')({
   staleTime: 1000 * 60 * 5,
   beforeLoad: (ctx) => {
     const { libraryId, version } = ctx.params
-    const library = getLibrary(libraryId)
+    const library = findLibrary(libraryId)
+
+    if (!library) {
+      throw notFound()
+    }
 
     library.handleRedirects?.(ctx.location.href)
 
@@ -19,7 +28,12 @@ export const Route = createFileRoute('/$libraryId/$version')({
   },
   loader: async (ctx) => {
     const { libraryId, version } = ctx.params
-    const library = getLibrary(libraryId)
+    const library = findLibrary(libraryId)
+
+    if (!library) {
+      throw notFound()
+    }
+
     const branch = getBranch(library, version)
     const config = await getTanstackDocsConfig({
       data: {
@@ -36,7 +50,11 @@ export const Route = createFileRoute('/$libraryId/$version')({
 
 function RouteForm() {
   const { libraryId, version } = Route.useParams()
-  const library = getLibrary(libraryId)
+  const library = findLibrary(libraryId)
+
+  if (!library) {
+    throw notFound()
+  }
 
   return (
     <>
diff --git a/src/routes/admin/audit.tsx b/src/routes/admin/audit.tsx
index bf39827d..d13994cc 100644
--- a/src/routes/admin/audit.tsx
+++ b/src/routes/admin/audit.tsx
@@ -354,6 +354,7 @@ function AuditPage() {
     [],
   )
 
+  // eslint-disable-next-line react-hooks/incompatible-library
   const table = useReactTable({
     data: (auditQuery?.data?.page || []) as AuditLogEntry[],
     columns,
diff --git a/src/routes/admin/github-stats.tsx b/src/routes/admin/github-stats.tsx
index cead5714..5b595deb 100644
--- a/src/routes/admin/github-stats.tsx
+++ b/src/routes/admin/github-stats.tsx
@@ -302,6 +302,7 @@ function GitHubStatsAdmin() {
     [refreshingKey, refreshAllMutation, refreshMutation],
   )
 
+  // eslint-disable-next-line react-hooks/incompatible-library
   const table = useReactTable({
     data: cacheEntries ?? [],
     columns,
diff --git a/src/routes/admin/logins.tsx b/src/routes/admin/logins.tsx
index dd676d80..42eded77 100644
--- a/src/routes/admin/logins.tsx
+++ b/src/routes/admin/logins.tsx
@@ -250,6 +250,7 @@ function LoginsPage() {
     [],
   )
 
+  // eslint-disable-next-line react-hooks/incompatible-library
   const table = useReactTable({
     data: (loginsQuery?.data?.page || []) as LoginHistoryEntry[],
     columns,
diff --git a/src/routes/admin/npm-stats.tsx b/src/routes/admin/npm-stats.tsx
index 2f417b2d..5cad1047 100644
--- a/src/routes/admin/npm-stats.tsx
+++ b/src/routes/admin/npm-stats.tsx
@@ -268,6 +268,7 @@ function NpmStatsAdmin() {
     [refreshPackageMutation],
   )
 
+  // eslint-disable-next-line react-hooks/incompatible-library
   const libraryTable = useReactTable({
     data: libraryStats ?? [],
     columns: libraryColumns,
diff --git a/src/routes/admin/roles.$roleId.tsx b/src/routes/admin/roles.$roleId.tsx
index 2a579c45..9653017f 100644
--- a/src/routes/admin/roles.$roleId.tsx
+++ b/src/routes/admin/roles.$roleId.tsx
@@ -207,6 +207,7 @@ function RoleDetailPage() {
     [selectedUserIds, usersWithRole, toggleAllSelection, toggleUserSelection],
   )
 
+  // eslint-disable-next-line react-hooks/incompatible-library
   const table = useReactTable({
     data: usersWithRole || [],
     columns,