zudoku 0.47.2 → 0.48.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zudoku",
-  "version": "0.47.2",
+  "version": "0.48.1",
   "type": "module",
   "homepage": "https://zudoku.dev",
   "repository": {
@@ -192,6 +192,7 @@
     "fast-equals": "5.2.2",
     "framer-motion": "^12.12.2",
     "glob": "11.0.2",
+    "glob-parent": "6.0.2",
     "graphql": "16.11.0",
     "graphql-type-json": "0.3.2",
     "graphql-yoga": "5.13.5",
@@ -200,6 +201,7 @@
     "hast-util-to-string": "3.0.1",
     "html-url-attributes": "^3.0.1",
     "http-terminator": "3.2.0",
+    "json-schema-to-typescript-lite": "14.1.0",
     "loglevel": "1.9.2",
     "lru-cache": "11.0.2",
     "lucide-react": "0.488.0",
@@ -245,8 +247,8 @@
     "vite": "6.3.5",
     "yaml": "2.8.0",
     "yargs": "17.7.2",
-    "zod": "3.25.51",
-    "zod-validation-error": "3.4.1",
+    "zod": "3.25.56",
+    "zod-to-ts": "1.2.0",
     "zustand": "5.0.5"
   },
   "devDependencies": {
@@ -257,6 +259,7 @@
     "@testing-library/react": "16.3.0",
     "@types/estree": "1.0.7",
     "@types/express": "5.0.2",
+    "@types/glob-parent": "5.1.3",
     "@types/har-format": "1.2.16",
     "@types/hast": "^3.0.4",
     "@types/json-schema": "7.0.15",
@@ -275,18 +278,18 @@
     "react": "19.1.0",
     "react-dom": "19.1.0",
     "rollup-plugin-visualizer": "5.14.0",
+    "tsx": "4.19.4",
     "typescript": "5.8.3",
     "vitest": "3.2.3"
   },
   "peerDependencies": {
-    "react": ">=19",
-    "react-dom": ">=19",
     "@azure/msal-browser": "^4.13.0",
     "@clerk/clerk-js": "^5.63.1",
     "@sentry/react": "^9.12.0",
-    "@supabase/supabase-js": "^2.49.4"
+    "@supabase/supabase-js": "^2.49.4",
+    "react": ">=19",
+    "react-dom": ">=19"
   },
-  "optionalDependencies": {},
   "peerDependenciesMeta": {
     "@azure/msal-browser": {
       "optional": true
@@ -305,12 +308,12 @@
     "build": "tsc --project tsconfig.app.json",
     "build:dev": "esbuild './src/**/*.ts' --format=esm --platform=node --target=node22 --outdir=dist --splitting --log-level=warning",
     "build:vite": "vite build",
-    "generate:types": "node scripts/generate-types.js",
+    "generate:types": "tsx scripts/generate-types.js && tsx scripts/generate-flat-config.js",
     "build:standalone:vite": "vite build --mode standalone --config vite.standalone.config.ts",
     "build:standalone:html": "cp ./src/app/standalone.html ./standalone/standalone.html && cp ./src/app/demo.html ./standalone/demo.html && cp ./src/app/demo-cdn.html ./standalone/index.html && cp standalone/zudoku.css standalone/style.css",
     "clean": "tsc --build --clean",
     "codegen": "graphql-codegen --config ./src/codegen.ts",
-    "test": "vitest run"
+    "test": "vitest run --typecheck"
   },
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts"

package/src/app/ZuploBuildConfig.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v4";
 
 export const EntitlementsSchema = z.object({
   devPortalZuploBranding: z.boolean(),

package/src/app/demo.tsx

@@ -36,9 +36,10 @@ const config = {
       message: <DemoAnnouncement />,
     },
   },
-  topNavigation: [
+  navigation: [
     {
-      id: "/",
+      type: "link",
+      to: "/",
       label: "API Reference",
     },
   ],
@@ -47,7 +48,7 @@ const config = {
     openApiPlugin({
       type: "url",
       input: apiUrl,
-      navigationId: "/",
+      path: "/",
     }),
   ],
 } satisfies ZudokuConfig;

package/src/app/main.css

@@ -63,6 +63,11 @@
     @apply h-full overscroll-none;
   }
 
+  ::view-transition-old(root),
+  ::view-transition-new(root) {
+    animation: none;
+  }
+
   details summary {
     @apply cursor-pointer;
   }

package/src/app/main.tsx

@@ -6,11 +6,11 @@ import {
 } from "virtual:zudoku-api-plugins";
 import { configuredAuthProvider } from "virtual:zudoku-auth";
 import { configuredCustomPagesPlugin } from "virtual:zudoku-custom-pages-plugin";
-import { configuredDocsPlugins } from "virtual:zudoku-docs-plugins";
+import { configuredDocsPlugin } from "virtual:zudoku-docs-plugin";
+import { configuredNavigation } from "virtual:zudoku-navigation";
 import { configuredRedirectPlugin } from "virtual:zudoku-redirect-plugin";
 import { configuredSearchPlugin } from "virtual:zudoku-search-plugin";
 import { registerShiki } from "virtual:zudoku-shiki-register";
-import { configuredSidebar } from "virtual:zudoku-sidebar";
 import "virtual:zudoku-theme.css";
 import {
   BuildCheck,
@@ -49,12 +49,11 @@ export const convertZudokuConfigToOptions = (
       title: "%s - Zudoku",
       ...config.metadata,
     },
-    sidebars: configuredSidebar,
-    topNavigation: config.topNavigation,
+    navigation: configuredNavigation,
     mdx: config.mdx,
     plugins: [
       ...(configuredAuthProvider ? [configuredAuthProvider] : []),
-      ...configuredDocsPlugins,
+      ...(configuredDocsPlugin ? [configuredDocsPlugin] : []),
       ...configuredApiPlugins,
       ...(configuredSearchPlugin ? [configuredSearchPlugin] : []),
       ...(configuredRedirectPlugin ? [configuredRedirectPlugin] : []),
@@ -100,6 +99,8 @@ export const getRoutesByOptions = (
       },
     ]);
 
+  // @TODO Detect conflicts in routes and log warning
+
   return routes;
 };
 

package/src/app/standalone.tsx

@@ -31,10 +31,11 @@ const config = {
       : undefined,
     pageTitle,
   },
-  topNavigation: [
+  navigation: [
     {
-      id: "/",
+      type: "link",
       label: "API Reference",
+      to: "/",
     },
   ],
   plugins: [
@@ -42,7 +43,7 @@ const config = {
     openApiPlugin({
       type: "url",
       input: apiUrl!,
-      navigationId: "/",
+      path: "/",
     }),
   ],
 } satisfies ZudokuConfig;

package/src/lib/components/BuildCheck.tsx

@@ -1,6 +1,6 @@
 import { useQuery } from "@tanstack/react-query";
 import { CircleFadingArrowUpIcon, LoaderCircleIcon } from "lucide-react";
-import { z } from "zod";
+import { z } from "zod/v4";
 import { Button } from "../ui/Button.js";
 
 const BuildStatusSchema = z.object({

package/src/lib/components/Header.tsx

@@ -25,6 +25,7 @@ import { Banner } from "./Banner.js";
 import { ClientOnly } from "./ClientOnly.js";
 import { useZudoku } from "./context/ZudokuContext.js";
 import { MobileTopNavigation } from "./MobileTopNavigation.js";
+import { PageProgress } from "./PageProgress.js";
 import { Search } from "./Search.js";
 import { Slot } from "./Slot.js";
 import { ThemeSwitch } from "./ThemeSwitch.js";
@@ -82,8 +83,9 @@ export const Header = memo(function HeaderInner() {
   return (
     <header className="sticky lg:top-0 z-10 bg-background/80 backdrop-blur w-full">
       <Banner />
-      <div className={borderBottom}>
-        <div className="max-w-screen-2xl mx-auto flex relative items-center justify-between h-(--top-header-height) px-4 lg:px-8 border-transparent">
+      <div className={cn(borderBottom, "relative")}>
+        <PageProgress />
+        <div className="max-w-screen-2xl mx-auto flex items-center justify-between h-(--top-header-height) px-4 lg:px-8 border-transparent">
           <div className="flex">
             <Link to="/">
               <div className="flex items-center gap-3.5">
@@ -182,7 +184,7 @@ export const Header = memo(function HeaderInner() {
         </div>
       </div>
       <div className={cn("hidden lg:block", borderBottom)}>
-        <div className="max-w-screen-2xl mx-auto border-transparent">
+        <div className="max-w-screen-2xl mx-auto border-transparent relative">
           <Slot.Target name="top-navigation-before" />
           <TopNavigation />
           <Slot.Target name="top-navigation-after" />

package/src/lib/components/Heading.tsx

@@ -46,7 +46,11 @@ export type HeadingProps = HTMLAttributes<HTMLHeadingElement> &
     className?: string;
     id?: string;
     level?: 1 | 2 | 3 | 4 | 5 | 6;
-    registerSidebarAnchor?: boolean;
+    /**
+     * This is to set labels as active when the heading is in the viewport.
+     * It's used in the navigation/toc to highlight the current section.
+     */
+    registerNavigationAnchor?: boolean;
   };
 
 export const Heading = ({
@@ -54,7 +58,7 @@ export const Heading = ({
   children,
   id,
   className,
-  registerSidebarAnchor,
+  registerNavigationAnchor,
 }: HeadingProps) => {
   const Component = getComponent(level ?? 1);
   const { ref } = useRegisterAnchorElement();
@@ -65,7 +69,7 @@ export const Heading = ({
         className: cn(className, "flex items-center gap-[0.33em]"),
         level,
       })}
-      ref={registerSidebarAnchor ? ref : undefined}
+      ref={registerNavigationAnchor ? ref : undefined}
       id={id}
     >
       {children}

package/src/lib/components/Main.tsx

@@ -4,13 +4,13 @@ import { useNavigation } from "react-router";
 import { Drawer, DrawerTrigger } from "zudoku/ui/Drawer.js";
 import { cn } from "../util/cn.js";
 import { useCurrentNavigation, useZudoku } from "./context/ZudokuContext.js";
-import { Sidebar } from "./navigation/Sidebar.js";
+import { Navigation } from "./navigation/Navigation.js";
 import { Slot } from "./Slot.js";
 
 export const Main = ({ children }: PropsWithChildren) => {
   const [isDrawerOpen, setDrawerOpen] = useState(false);
-  const { sidebar } = useCurrentNavigation();
-  const hasSidebar = sidebar.length > 0;
+  const { navigation } = useCurrentNavigation();
+  const hasNavigation = navigation.length > 0;
   const isNavigating = useNavigation().state === "loading";
   const { options } = useZudoku();
 
@@ -20,13 +20,13 @@ export const Main = ({ children }: PropsWithChildren) => {
       open={isDrawerOpen}
       onOpenChange={(open) => setDrawerOpen(open)}
     >
-      {hasSidebar && (
-        <Sidebar
+      {hasNavigation && (
+        <Navigation
           onRequestClose={() => setDrawerOpen(false)}
-          sidebar={sidebar}
+          navigation={navigation}
         />
       )}
-      {hasSidebar && (
+      {hasNavigation && (
         <div className="lg:hidden -mx-4 px-4 py-2 sticky bg-background/80 backdrop-blur-xs z-10 top-0 start-0 end-0 border-b">
           <DrawerTrigger className="flex items-center gap-2 px-4">
             <PanelLeftIcon size={16} strokeWidth={1.5} />
@@ -38,7 +38,7 @@ export const Main = ({ children }: PropsWithChildren) => {
         data-pagefind-body
         className={cn(
           "px-4 lg:pe-8 lg:px-8",
-          !hasSidebar && "col-span-full",
+          !hasNavigation && "col-span-full",
           isNavigating && "animate-pulse",
         )}
       >

package/src/lib/components/MobileTopNavigation.tsx

@@ -11,16 +11,19 @@ import {
 import { useZudoku } from "./context/ZudokuContext.js";
 import { PoweredByZudoku } from "./navigation/PoweredByZudoku.js";
 import { isHiddenItem } from "./navigation/utils.js";
+import { PageProgress } from "./PageProgress.js";
 import { Search } from "./Search.js";
 import { Slot } from "./Slot.js";
 import { ThemeSwitch } from "./ThemeSwitch.js";
-import { PageProgress, TopNavItem } from "./TopNavigation.js";
+import { TopNavItem } from "./TopNavigation.js";
 
 export const MobileTopNavigation = () => {
-  const { topNavigation, options } = useZudoku();
+  const { navigation, options } = useZudoku();
   const { isAuthenticated } = useAuth();
   const [drawerOpen, setDrawerOpen] = useState(false);
 
+  const filteredItems = navigation.filter(isHiddenItem(isAuthenticated));
+
   return (
     <Drawer
       direction={options.page?.dir === "rtl" ? "left" : "right"}
@@ -50,15 +53,13 @@ export const MobileTopNavigation = () => {
               <li>
                 <ThemeSwitch />
               </li>
-              {topNavigation
-                .filter(isHiddenItem(isAuthenticated))
-                .map((item) => (
-                  <li key={item.label}>
-                    <button type="button" onClick={() => setDrawerOpen(false)}>
-                      <TopNavItem {...item} />
-                    </button>
-                  </li>
-                ))}
+              {filteredItems.map((item) => (
+                <li key={item.label}>
+                  <button type="button" onClick={() => setDrawerOpen(false)}>
+                    <TopNavItem {...item} />
+                  </button>
+                </li>
+              ))}
             </ul>
           </div>
           {options.page?.showPoweredBy !== false && (

package/src/lib/components/PageProgress.tsx

@@ -0,0 +1,28 @@
+import { useNProgress } from "@tanem/react-nprogress";
+import { useEffect, useState } from "react";
+import { useNavigation } from "react-router";
+
+export const PageProgress = () => {
+  const navigation = useNavigation();
+  const isNavigating = navigation.state === "loading";
+  // delay the animation to avoid flickering
+  const [isAnimating, setIsAnimating] = useState(false);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setIsAnimating(isNavigating), 200);
+
+    return () => clearTimeout(timer);
+  }, [isNavigating]);
+
+  const { isFinished, progress } = useNProgress({ isAnimating });
+
+  return (
+    <div
+      className="absolute w-0 left-0 right-0 bottom-[-1px] h-[2px] bg-primary transition-all duration-300 ease-in-out"
+      style={{
+        opacity: isFinished ? 0 : 1,
+        width: isFinished ? 0 : `${progress * 100}%`,
+      }}
+    />
+  );
+};

package/src/lib/components/TopNavigation.tsx

@@ -1,44 +1,19 @@
-import { useNProgress } from "@tanem/react-nprogress";
 import { cx } from "class-variance-authority";
-import { Suspense, useEffect, useState } from "react";
-import { NavLink, useNavigation } from "react-router";
-import type { TopNavigationItem } from "../../config/validators/validate.js";
+import { deepEqual } from "fast-equals";
+import { Suspense } from "react";
+import { NavLink } from "react-router";
+import { type NavigationItem } from "../../config/validators/NavigationSchema.js";
 import { useAuth } from "../authentication/hook.js";
 import { joinUrl } from "../util/joinUrl.js";
 import { useCurrentNavigation, useZudoku } from "./context/ZudokuContext.js";
-import { isHiddenItem, traverseSidebar } from "./navigation/utils.js";
+import { isHiddenItem, traverseNavigationItem } from "./navigation/utils.js";
 import { Slot } from "./Slot.js";
 
-export const PageProgress = () => {
-  const navigation = useNavigation();
-  const isNavigating = navigation.state === "loading";
-  // delay the animation to avoid flickering
-  const [isAnimating, setIsAnimating] = useState(false);
-
-  useEffect(() => {
-    const timer = setTimeout(() => setIsAnimating(isNavigating), 100);
-
-    return () => clearTimeout(timer);
-  }, [isNavigating]);
-
-  const { isFinished, progress } = useNProgress({ isAnimating });
-
-  return (
-    <div
-      className="absolute w-0 left-0 right-0 bottom-[-1px] h-[2px] bg-primary transition-all duration-300 ease-in-out"
-      style={{
-        opacity: isFinished ? 0 : 1,
-        width: isFinished ? 0 : `${progress * 100}%`,
-      }}
-    />
-  );
-};
-
 export const TopNavigation = () => {
-  const { topNavigation } = useZudoku();
+  const { navigation } = useZudoku();
   const { isAuthenticated } = useAuth();
 
-  const filteredItems = topNavigation.filter(isHiddenItem(isAuthenticated));
+  const filteredItems = navigation.filter(isHiddenItem(isAuthenticated));
 
   if (filteredItems.length === 0 || import.meta.env.MODE === "standalone") {
     return <style>{`:root { --top-nav-height: 0px; }`}</style>;
@@ -50,7 +25,7 @@ export const TopNavigation = () => {
         <nav className="text-sm">
           <ul className="flex flex-row items-center gap-8">
             {filteredItems.map((item) => (
-              <li key={item.id}>
+              <li key={item.label + item.type}>
                 <TopNavItem {...item} />
               </li>
             ))}
@@ -58,50 +33,66 @@ export const TopNavigation = () => {
         </nav>
         <Slot.Target name="top-navigation-side" />
       </div>
-      <PageProgress />
+      {/* <PageProgress /> */}
     </Suspense>
   );
 };
 
-export const TopNavItem = ({
-  id,
-  label,
-  default: defaultLink,
-}: TopNavigationItem) => {
-  const { sidebars } = useZudoku();
-  const currentSidebar = sidebars[id];
+const getPathForItem = (item: NavigationItem): string => {
+  switch (item.type) {
+    case "doc":
+      return joinUrl(item.path);
+    case "link":
+      return item.to;
+    case "category": {
+      if (item.link?.path) {
+        return joinUrl(item.link.path);
+      }
+
+      return (
+        traverseNavigationItem(item, (child) => {
+          if (child.type !== "category") {
+            return getPathForItem(child);
+          }
+        }) ?? ""
+      );
+    }
+    case "custom-page":
+      return item.path;
+  }
+};
+
+export const TopNavItem = (item: NavigationItem) => {
   const currentNav = useCurrentNavigation();
-  const isNavigating = Boolean(useNavigation().location);
-  const isActive = currentNav.topNavItem?.id === id && !isNavigating;
+  const isActiveTopNavItem = deepEqual(currentNav.topNavItem, item);
 
-  // TODO: This is a bit of a hack to get the first link in the sidebar
-  // We should really process this when we load the config so we can validate
-  // that the sidebar is actually set. In this case we just fall back to linking
-  // to the id if we can't resolve a sidebar.
-  const first =
-    defaultLink ??
-    (currentSidebar
-      ? traverseSidebar(currentSidebar, (item) => {
-          if (item.type === "doc") return joinUrl(item.id);
-        })
-      : joinUrl(id)) ??
-    joinUrl(id);
+  const path = getPathForItem(item);
 
   return (
-    // We don't use isActive here because it has to be inside the sidebar,
-    // the top nav id doesn't necessarily start with the sidebar id
+    // We don't use isActive here because it has to be inside the navigation,
+    // the top nav id doesn't necessarily start with the navigation id
     <NavLink
-      className={({ isPending }) =>
-        cx(
-          "block lg:py-3.5 font-medium -mb-px",
+      viewTransition
+      to={path}
+      className={({ isActive: isActiveNavLink, isPending }) => {
+        const isActive = isActiveNavLink || isActiveTopNavItem;
+        return cx(
+          "flex items-center gap-2 lg:py-3.5 font-medium -mb-px transition duration-150 delay-75 relative",
           isActive || isPending
-            ? "border-primary text-foreground"
-            : "border-transparent text-foreground/75 hover:text-foreground hover:border-accent-foreground/25",
-        )
-      }
-      to={first}
+            ? [
+                "text-foreground",
+                // underline with view transition animation
+                "after:content-[''] after:absolute after:bottom-0 after:left-0 after:right-0",
+                "after:h-0.5 after:bg-primary",
+                isActive && "after:[view-transition-name:top-nav-underline]",
+                isPending && "after:bg-primary/25",
+              ]
+            : "text-foreground/75 hover:text-foreground",
+        );
+      }}
     >
-      {label}
+      {item.icon && <item.icon size={16} className="align-[-0.125em]" />}
+      {item.label}
     </NavLink>
   );
 };

package/src/lib/components/context/ZudokuContext.ts

@@ -1,11 +1,12 @@
 import { useQuery, useSuspenseQuery } from "@tanstack/react-query";
 import { createContext, useContext } from "react";
 import { matchPath, useLocation } from "react-router";
+import { type NavigationItem } from "../../../config/validators/NavigationSchema.js";
 import { useAuth } from "../../authentication/hook.js";
 import type { ZudokuContext } from "../../core/ZudokuContext.js";
 import { joinUrl } from "../../util/joinUrl.js";
 import { CACHE_KEYS } from "../cache.js";
-import { traverseSidebar } from "../navigation/utils.js";
+import { traverseNavigation } from "../navigation/utils.js";
 
 export const ZudokuReactContext = createContext<ZudokuContext | undefined>(
   undefined,
@@ -30,8 +31,22 @@ export const useApiIdentities = () => {
   });
 };
 
+const getItemPath = (item: NavigationItem) => {
+  switch (item.type) {
+    case "doc":
+      return joinUrl(item.path);
+    case "category":
+      return item.link ? joinUrl(item.link.path) : undefined;
+    case "link":
+      return item.to;
+    case "custom-page":
+      return item.path;
+    default:
+      return undefined;
+  }
+};
 export const useCurrentNavigation = () => {
-  const { getPluginSidebar, sidebars, topNavigation, options } = useZudoku();
+  const { getPluginNavigation, navigation, options } = useZudoku();
   const location = useLocation();
   const auth = useAuth();
 
@@ -39,44 +54,47 @@ export const useCurrentNavigation = () => {
     matchPath(route, location.pathname),
   );
 
-  let currentSidebarItem = Object.entries(sidebars).find(([, sidebar]) => {
-    return traverseSidebar(sidebar, (item) => {
-      const itemId =
-        item.type === "doc"
-          ? joinUrl(item.id)
-          : item.type === "category" && item.link
-            ? joinUrl(item.link.id)
-            : undefined;
-
-      if (itemId === location.pathname) {
-        return item;
-      }
-    });
+  const navItem = traverseNavigation(navigation, (item, parentCategories) => {
+    if (getItemPath(item) === location.pathname) {
+      return parentCategories.at(0) ?? item;
+    }
   });
-  const currentTopNavItem =
-    topNavigation.find((t) => t.id === currentSidebarItem?.[0]) ??
-    topNavigation.find((item) => matchPath(item.id, location.pathname));
-
-  if (
-    currentTopNavItem &&
-    !currentSidebarItem &&
-    currentTopNavItem.id in sidebars
-  ) {
-    currentSidebarItem = ["", sidebars[currentTopNavItem.id]!];
-  }
 
   const { data } = useSuspenseQuery({
-    queryFn: () => getPluginSidebar(location.pathname),
-    queryKey: ["plugin-sidebar", location.pathname],
+    queryFn: () => getPluginNavigation(location.pathname),
+    queryKey: ["plugin-navigation", location.pathname],
   });
 
-  const hideSidebar =
+  let topNavItem = navItem;
+  if (!navItem && data.length > 0) {
+    // Extract base paths from plugin navigation items
+    const pluginBasePaths = data.flatMap((item) => {
+      return getItemPath(item)?.split("?").at(0)?.split("#").at(0) ?? [];
+    });
+
+    // Find top-level nav item that matches any plugin base path
+    topNavItem = navigation
+      .flatMap((item) => {
+        const itemPath = getItemPath(item);
+        return itemPath ? [{ item, path: itemPath }] : [];
+      })
+      .sort((a, b) => b.path.length - a.path.length)
+      .find(({ path }) => {
+        return pluginBasePaths.some(
+          (basePath) =>
+            matchPath({ path, end: false }, basePath) ??
+            matchPath({ path: basePath, end: false }, path),
+        );
+      })?.item;
+  }
+
+  const hasNavigation =
     auth.isAuthEnabled && !auth.isAuthenticated && isProtectedRoute;
 
   return {
-    sidebar: hideSidebar
+    navigation: hasNavigation
       ? []
-      : [...(currentSidebarItem ? currentSidebarItem[1] : []), ...data],
-    topNavItem: currentTopNavItem,
+      : [...(navItem?.type === "category" ? navItem.items : []), ...data],
+    topNavItem,
   };
 };