zudoku 0.0.0-zce59fc03 → 0.0.0-zd57c18df

package/src/lib/components/Slot.test.tsx

@@ -20,7 +20,7 @@ import { Slot } from "./Slot.js";
 
 const createWrapper = (slots: Record<string, ReactNode> = {}) => {
   const queryClient = new QueryClient();
-  const context = new ZudokuContext({}, queryClient);
+  const context = new ZudokuContext({}, queryClient, {});
 
   const wrapper = ({ children }: PropsWithChildren) => (
     <MemoryRouter initialEntries={["/", "/page"]}>

package/src/lib/components/TopNavigation.tsx

@@ -2,6 +2,7 @@ import { cx } from "class-variance-authority";
 import { deepEqual } from "fast-equals";
 import { Suspense } from "react";
 import { NavLink, type NavLinkProps } from "react-router";
+import { Separator } from "zudoku/ui/Separator.js";
 import type { NavigationItem } from "../../config/validators/NavigationSchema.js";
 import { useAuth } from "../authentication/hook.js";
 import { joinUrl } from "../util/joinUrl.js";
@@ -24,11 +25,17 @@ export const TopNavigation = () => {
       <div className="items-center justify-between px-8 h-(--top-nav-height) hidden lg:flex text-sm relative">
         <nav className="text-sm">
           <ul className="flex flex-row items-center gap-8">
-            {filteredItems.map((item) => (
-              <li key={item.label + item.type}>
-                <TopNavItem {...item} />
-              </li>
-            ))}
+            {filteredItems.map((item) =>
+              item.type === "separator" ? (
+                <li key={item.label} className="-mx-4 h-7">
+                  <Separator orientation="vertical" />
+                </li>
+              ) : item.type !== "section" && item.type !== "filter" ? (
+                <li key={item.label + item.type}>
+                  <TopNavItem {...item} />
+                </li>
+              ) : null,
+            )}
           </ul>
         </nav>
         <Slot.Target name="top-navigation-side" />
@@ -51,7 +58,11 @@ const getPathForItem = (item: NavigationItem): string => {
 
       return (
         traverseNavigationItem(item, (child) => {
-          if (child.type !== "category") {
+          if (
+            child.type !== "category" &&
+            child.type !== "separator" &&
+            child.type !== "section"
+          ) {
             return getPathForItem(child);
           }
         }) ?? ""
@@ -59,6 +70,8 @@ const getPathForItem = (item: NavigationItem): string => {
     }
     case "custom-page":
       return item.path;
+    default:
+      return "";
   }
 };
 
@@ -97,7 +110,12 @@ export const TopNavLink = ({
   );
 };
 
-export const TopNavItem = (item: NavigationItem) => {
+export const TopNavItem = (
+  item: Exclude<
+    NavigationItem,
+    { type: "separator" } | { type: "section" } | { type: "filter" }
+  >,
+) => {
   const currentNav = useCurrentNavigation();
   const isActiveTopNavItem = deepEqual(currentNav.topNavItem, item);
 

package/src/lib/components/Zudoku.tsx

@@ -5,7 +5,7 @@ import { ThemeProvider } from "next-themes";
 import {
   memo,
   type PropsWithChildren,
-  useContext,
+  Suspense,
   useEffect,
   useMemo,
   useState,
@@ -18,7 +18,6 @@ import {
   type ZudokuContextOptions,
 } from "../core/ZudokuContext.js";
 import { TopLevelError } from "../errors/TopLevelError.js";
-import { StaggeredRenderContext } from "../plugins/openapi/StaggeredRender.js";
 import { MdxComponents } from "../util/MdxComponents.js";
 import "../util/requestIdleCallbackPolyfill.js";
 import {
@@ -33,7 +32,13 @@ import { ZudokuProvider } from "./context/ZudokuProvider.js";
 let zudokuContext: ZudokuContext | undefined;
 
 const ZudokuInner = memo(
-  ({ children, ...props }: PropsWithChildren<ZudokuContextOptions>) => {
+  ({
+    children,
+    env,
+    ...props
+  }: PropsWithChildren<
+    ZudokuContextOptions & { env: Record<string, string> }
+  >) => {
     const components = useMemo(
       () => ({ ...DEFAULT_COMPONENTS, ...props.overrides }),
       [props.overrides],
@@ -56,12 +61,7 @@ const ZudokuInner = memo(
         ...props.mdx?.components,
       };
     }, [props.mdx?.components, props.plugins]);
-    const { stagger } = useContext(StaggeredRenderContext);
     const [didNavigate, setDidNavigate] = useState(false);
-    const staggeredValue = useMemo(
-      () => (didNavigate ? { stagger: true } : { stagger }),
-      [stagger, didNavigate],
-    );
     const navigation = useNavigation();
     const queryClient = useQueryClient();
 
@@ -72,7 +72,7 @@ const ZudokuInner = memo(
       setDidNavigate(true);
     }, [didNavigate, navigation.location]);
 
-    zudokuContext ??= new ZudokuContext(props, queryClient);
+    zudokuContext ??= new ZudokuContext(props, queryClient, env);
 
     const heads = props.plugins?.flatMap((plugin) =>
       hasHead(plugin) ? (plugin.getHead?.({ location }) ?? []) : [],
@@ -81,8 +81,8 @@ const ZudokuInner = memo(
     return (
       <>
         <Helmet>{heads}</Helmet>
-        <StaggeredRenderContext.Provider value={staggeredValue}>
-          <ZudokuProvider context={zudokuContext}>
+        <ZudokuProvider context={zudokuContext}>
+          <Suspense fallback={<div>Zudoku Loading...</div>}>
             <RouterEventsEmitter />
             <SlotProvider slots={props.slots ?? props.UNSAFE_slotlets}>
               <MDXProvider components={mdxComponents}>
@@ -95,8 +95,8 @@ const ZudokuInner = memo(
                 </ThemeProvider>
               </MDXProvider>
             </SlotProvider>
-          </ZudokuProvider>
-        </StaggeredRenderContext.Provider>
+          </Suspense>
+        </ZudokuProvider>
       </>
     );
   },
@@ -104,7 +104,11 @@ const ZudokuInner = memo(
 
 ZudokuInner.displayName = "ZudokuInner";
 
-const Zudoku = (props: ZudokuContextOptions) => {
+const Zudoku = (
+  props: PropsWithChildren<
+    ZudokuContextOptions & { env: Record<string, string> }
+  >,
+) => {
   return (
     <ErrorBoundary FallbackComponent={TopLevelError}>
       <ZudokuInner {...props} />

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

@@ -1,16 +1,12 @@
 import { useQuery, useSuspenseQuery } from "@tanstack/react-query";
-import { createContext, useContext, useEffect } from "react";
+import { useContext, useEffect } from "react";
 import { matchPath, useLocation } from "react-router";
 import type { NavigationItem } from "../../../config/validators/NavigationSchema.js";
 import { useAuthState } from "../../authentication/state.js";
-import type { ZudokuContext } from "../../core/ZudokuContext.js";
 import { joinUrl } from "../../util/joinUrl.js";
 import { CACHE_KEYS, useCache } from "../cache.js";
 import { traverseNavigation } from "../navigation/utils.js";
-
-export const ZudokuReactContext = createContext<ZudokuContext | undefined>(
-  undefined,
-);
+import { ZudokuReactContext } from "./ZudokuReactContext.js";
 
 export const useZudoku = () => {
   const context = useContext(ZudokuReactContext);
@@ -77,6 +73,7 @@ export const useCurrentNavigation = () => {
   const location = useLocation();
 
   const navItem = traverseNavigation(navigation, (item, parentCategories) => {
+    if (item.type === "link") return;
     if (getItemPath(item) === location.pathname) {
       return parentCategories.at(0) ?? item;
     }

package/src/lib/components/context/ZudokuProvider.tsx

@@ -2,7 +2,7 @@ import { useSuspenseQuery } from "@tanstack/react-query";
 import type { PropsWithChildren } from "react";
 import type { ZudokuContext } from "../../core/ZudokuContext.js";
 import { NO_DEHYDRATE } from "../cache.js";
-import { ZudokuReactContext } from "./ZudokuContext.js";
+import { ZudokuReactContext } from "./ZudokuReactContext.js";
 
 export const ZudokuProvider = ({
   children,

package/src/lib/components/context/ZudokuReactContext.tsx

@@ -0,0 +1,17 @@
+import { type Context, createContext } from "react";
+import type { ZudokuContext } from "../../core/ZudokuContext.js";
+
+/**
+ * During SSR, Vite's module runner can load the same module multiple times
+ * (once for the main app, once for external plugins), creating duplicate
+ * React contexts that don't share state.
+ */
+declare global {
+  var __ZUDOKU_CONTEXT: Context<ZudokuContext | undefined>;
+}
+
+globalThis.__ZUDOKU_CONTEXT ??= createContext<ZudokuContext | undefined>(
+  undefined,
+);
+
+export const ZudokuReactContext = globalThis.__ZUDOKU_CONTEXT;

package/src/lib/components/navigation/Navigation.tsx

@@ -2,6 +2,7 @@ import { VisuallyHidden } from "@radix-ui/react-visually-hidden";
 import type { NavigationItem as NavigationItemType } from "../../../config/validators/NavigationSchema.js";
 import { DrawerContent, DrawerTitle } from "../../ui/Drawer.js";
 import { Slot } from "../Slot.js";
+import { NavigationFilterProvider } from "./NavigationFilterContext.js";
 import { NavigationItem } from "./NavigationItem.js";
 import { NavigationWrapper } from "./NavigationWrapper.js";
 
@@ -12,7 +13,7 @@ export const Navigation = ({
   onRequestClose?: () => void;
   navigation: NavigationItemType[];
 }) => (
-  <>
+  <NavigationFilterProvider>
     <NavigationWrapper>
       <Slot.Target name="navigation-before" />
       {navigation.map((item) => (
@@ -30,7 +31,7 @@ export const Navigation = ({
       <Slot.Target name="navigation-after" />
     </NavigationWrapper>
     <DrawerContent
-      className="lg:hidden h-[100dvh] start-0 w-[320px] rounded-none"
+      className="lg:hidden h-dvh start-0 w-[320px] rounded-none"
       aria-describedby={undefined}
     >
       <div className="p-4 overflow-y-auto overscroll-none">
@@ -46,5 +47,5 @@ export const Navigation = ({
         ))}
       </div>
     </DrawerContent>
-  </>
+  </NavigationFilterProvider>
 );

package/src/lib/components/navigation/NavigationCategory.tsx

@@ -7,6 +7,7 @@ import { Button } from "zudoku/ui/Button.js";
 import type { NavigationCategory as NavigationCategoryType } from "../../../config/validators/NavigationSchema.js";
 import { cn } from "../../util/cn.js";
 import { joinUrl } from "../../util/joinUrl.js";
+import { useNavigationFilter } from "./NavigationFilterContext.js";
 import { NavigationItem } from "./NavigationItem.js";
 import { navigationListItem, useIsCategoryOpen } from "./utils.js";
 
@@ -20,6 +21,7 @@ const NavigationCategoryInner = ({
   const isCategoryOpen = useIsCategoryOpen(category);
   const [hasInteracted, setHasInteracted] = useState(false);
   const location = useLocation();
+  const { query: filterQuery } = useNavigationFilter();
 
   const isCollapsible = category.collapsible ?? true;
   const isCollapsed = category.collapsed ?? true;
@@ -37,6 +39,13 @@ const NavigationCategoryInner = ({
     }
   }, [isCategoryOpen]);
 
+  // Auto-expand when there's an active filter query
+  useEffect(() => {
+    if (filterQuery.trim()) {
+      setOpen(true);
+    }
+  }, [filterQuery]);
+
   const ToggleButton = isCollapsible && (
     <Button
       onClick={(e) => {

package/src/lib/components/navigation/NavigationFilterContext.tsx

@@ -0,0 +1,28 @@
+import {
+  createContext,
+  type PropsWithChildren,
+  useContext,
+  useState,
+} from "react";
+
+type NavigationFilterContextType = {
+  query: string;
+  setQuery: (query: string) => void;
+};
+
+const NavigationFilterContext = createContext<NavigationFilterContextType>({
+  query: "",
+  setQuery: () => {},
+});
+
+export const NavigationFilterProvider = ({ children }: PropsWithChildren) => {
+  const [query, setQuery] = useState("");
+
+  return (
+    <NavigationFilterContext.Provider value={{ query, setQuery }}>
+      {children}
+    </NavigationFilterContext.Provider>
+  );
+};
+
+export const useNavigationFilter = () => useContext(NavigationFilterContext);

package/src/lib/components/navigation/NavigationFilterInput.tsx

@@ -0,0 +1,35 @@
+import { SearchIcon, XIcon } from "lucide-react";
+import {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupInput,
+} from "zudoku/ui/InputGroup.js";
+import { useNavigationFilter } from "./NavigationFilterContext.js";
+
+export const NavigationFilterInput = ({
+  placeholder,
+}: {
+  placeholder?: string;
+}) => {
+  const { query, setQuery } = useNavigationFilter();
+
+  return (
+    <InputGroup className="my-2">
+      <InputGroupAddon>
+        <SearchIcon className="size-3.5" />
+      </InputGroupAddon>
+      <InputGroupInput
+        type="text"
+        placeholder={placeholder}
+        value={query}
+        onChange={(e) => setQuery(e.target.value)}
+      />
+      {query && (
+        <InputGroupButton onClick={() => setQuery("")}>
+          <XIcon className="size-3" />
+        </InputGroupButton>
+      )}
+    </InputGroup>
+  );
+};

package/src/lib/components/navigation/NavigationItem.tsx

@@ -1,6 +1,7 @@
 import { ExternalLinkIcon } from "lucide-react";
 import { useEffect, useRef, useState } from "react";
 import { NavLink, useLocation } from "react-router";
+import { Separator } from "zudoku/ui/Separator.js";
 import { Tooltip, TooltipContent, TooltipTrigger } from "zudoku/ui/Tooltip.js";
 import type { NavigationItem as NavigationItemType } from "../../../config/validators/NavigationSchema.js";
 import { useAuth } from "../../authentication/hook.js";
@@ -11,6 +12,8 @@ import { useViewportAnchor } from "../context/ViewportAnchorContext.js";
 import { useZudoku } from "../context/ZudokuContext.js";
 import { NavigationBadge } from "./NavigationBadge.js";
 import { NavigationCategory } from "./NavigationCategory.js";
+import { useNavigationFilter } from "./NavigationFilterContext.js";
+import { NavigationFilterInput } from "./NavigationFilterInput.js";
 import { navigationListItem, shouldShowItem } from "./utils.js";
 
 const TruncatedLabel = ({
@@ -65,8 +68,9 @@ export const NavigationItem = ({
   const { activeAnchor } = useViewportAnchor();
   const auth = useAuth();
   const context = useZudoku();
+  const { query } = useNavigationFilter();
 
-  if (!shouldShowItem(auth, context)(item)) {
+  if (!shouldShowItem(auth, context, query)(item)) {
     return null;
   }
 
@@ -75,6 +79,18 @@ export const NavigationItem = ({
       return (
         <NavigationCategory category={item} onRequestClose={onRequestClose} />
       );
+    case "separator":
+      return (
+        <Separator className="my-1 mx-auto w-[calc(100%-var(--padding-nav-item)*2)]!" />
+      );
+    case "section":
+      return (
+        <div className="mt-4 px-(--padding-nav-item) text-xs font-semibold text-muted-foreground uppercase tracking-wider">
+          {item.label}
+        </div>
+      );
+    case "filter":
+      return <NavigationFilterInput placeholder={item.placeholder} />;
     case "doc":
       return (
         <NavLink

package/src/lib/components/navigation/utils.ts

@@ -86,6 +86,13 @@ export const usePrevNext = (): {
   let foundCurrent = false;
 
   traverseNavigation(navigation, (item) => {
+    if (
+      item.type === "separator" ||
+      item.type === "section" ||
+      item.type === "filter"
+    )
+      return;
+
     const itemId =
       item.type === "doc"
         ? joinUrl(item.path)
@@ -133,9 +140,33 @@ export const navigationListItem = cva(
   },
 );
 
+export const itemMatchesFilter = (
+  item: NavigationItem,
+  query: string,
+): boolean => {
+  if (["separator", "section", "filter"].includes(item.type)) {
+    return true;
+  }
+  if (item.label?.toLowerCase().includes(query.toLowerCase())) {
+    return true;
+  }
+
+  if (item.type === "category") {
+    return item.items.some((child) => itemMatchesFilter(child, query));
+  }
+
+  return false;
+};
+
 export const shouldShowItem =
-  (auth: UseAuthReturn, context: ZudokuContext) =>
+  (auth: UseAuthReturn, context: ZudokuContext, filterQuery?: string) =>
   (item: NavigationItem): boolean => {
+    if (item.type === "filter") return true;
+
+    if (filterQuery?.trim() && !itemMatchesFilter(item, filterQuery)) {
+      return false;
+    }
+
     if (typeof item.display === "function") {
       return item.display({ context, auth });
     }

package/src/lib/core/ZudokuContext.ts

@@ -132,10 +132,15 @@ export class ZudokuContext {
   public readonly getAuthState: () => AuthState;
   public readonly queryClient: QueryClient;
   public readonly options: ZudokuContextOptions;
+  public readonly env: Record<string, string | undefined>;
   private readonly navigationPlugins: NavigationPlugin[];
   private emitter = createNanoEvents<ZudokuEvents>();
 
-  constructor(options: ZudokuContextOptions, queryClient: QueryClient) {
+  constructor(
+    options: ZudokuContextOptions,
+    queryClient: QueryClient,
+    env: Record<string, string | undefined>,
+  ) {
     const pluginProtectedRoutes = Object.fromEntries(
       (options.plugins ?? []).flatMap((plugin) => {
         if (!isNavigationPlugin(plugin)) return [];
@@ -152,6 +157,7 @@ export class ZudokuContext {
     };
 
     this.queryClient = queryClient;
+    this.env = env;
     this.options = { ...options, protectedRoutes };
     this.plugins = options.plugins ?? [];
     this.navigation = options.navigation ?? [];

package/src/lib/core/__internal.tsx

@@ -17,6 +17,7 @@ import { StatusPage as StatusPageImport } from "../components/StatusPage.js";
 import { RouterError as RouterErrorImport } from "../errors/RouterError.js";
 import { ServerError as ServerErrorImport } from "../errors/ServerError.js";
 import { RouteGuard as RouteGuardImport } from "./RouteGuard.js";
+import { runPluginTransformConfig as runPluginTransformConfigImport } from "./transform-config.js";
 
 export const Layout = LayoutImport;
 export const RouterError = RouterErrorImport;
@@ -28,3 +29,4 @@ export const Head = Helmet;
 export const StatusPage = StatusPageImport;
 export const BuildCheck = BuildCheckImport;
 export const Meta = MetaImport;
+export const runPluginTransformConfig = runPluginTransformConfigImport;

package/src/lib/core/plugins.ts

@@ -68,11 +68,15 @@ export interface ConfigHookContext {
   configPath: string;
 }
 
+export interface TransformConfigContext {
+  config: ZudokuConfig;
+  merge: <T extends Partial<ZudokuConfig>>(partial: T) => ZudokuConfig & T;
+}
+
 export interface TransformConfigPlugin {
   transformConfig?: (
-    config: ZudokuConfig,
-    ctx: ConfigHookContext,
-  ) => Partial<ZudokuConfig> | void | Promise<Partial<ZudokuConfig> | void>;
+    context: TransformConfigContext,
+  ) => ZudokuConfig | void | Promise<ZudokuConfig | void>;
 }
 
 export interface CommonPlugin {

package/src/lib/core/transform-config.test.tsx

@@ -0,0 +1,99 @@
+import { describe, expect, test } from "vitest";
+import { isPlainObject, mergeConfig } from "./transform-config.js";
+
+describe("isPlainObject", () => {
+  test("returns true for plain objects", () => {
+    expect(isPlainObject({})).toBe(true);
+    expect(isPlainObject({ a: 1 })).toBe(true);
+  });
+
+  test("returns false for arrays", () => {
+    expect(isPlainObject([])).toBe(false);
+    expect(isPlainObject([1, 2, 3])).toBe(false);
+  });
+
+  test("returns false for null and undefined", () => {
+    expect(isPlainObject(null)).toBe(false);
+    expect(isPlainObject(undefined)).toBe(false);
+  });
+
+  test("returns false for class instances", () => {
+    expect(isPlainObject(new Date())).toBe(false);
+    expect(isPlainObject(new Map())).toBe(false);
+    expect(isPlainObject(/regex/)).toBe(false);
+  });
+});
+
+describe("mergeConfig", () => {
+  test("merges flat objects", () => {
+    const target = { a: 1, b: 2 };
+    const source = { b: 3, c: 4 };
+    expect(mergeConfig(target, source)).toEqual({ a: 1, b: 3, c: 4 });
+  });
+
+  test("merges nested objects", () => {
+    const target = { nested: { a: 1, b: 2 } } as Record<string, unknown>;
+    const source = { nested: { b: 3, c: 4 } };
+    expect(mergeConfig(target, source)).toEqual({
+      nested: { a: 1, b: 3, c: 4 },
+    });
+  });
+
+  test("replaces arrays instead of merging", () => {
+    const target = { arr: [1, 2, 3] };
+    const source = { arr: [4, 5] };
+    expect(mergeConfig(target, source)).toEqual({ arr: [4, 5] });
+  });
+
+  test("preserves React elements without deep cloning", () => {
+    const element = <div className="test">Hello</div>;
+    const target = { banner: { message: "old" } };
+    const source = { banner: { message: element } };
+
+    const result = mergeConfig(target, source);
+
+    // Should be the exact same reference, not a clone
+    expect(result.banner.message).toBe(element);
+  });
+
+  test("does not clone React element children", () => {
+    const child = <strong>Bold</strong>;
+    const element = <div>{child} text</div>;
+    const target = { site: { banner: {} } };
+    const source = { site: { banner: { message: element } } };
+
+    const result = mergeConfig(target, source);
+
+    // The element should be identical (same reference)
+    expect(result.site.banner.message).toBe(element);
+    // Children should be preserved exactly
+    expect(result.site.banner.message.props.children).toBe(
+      element.props.children,
+    );
+  });
+
+  test("handles null and undefined values", () => {
+    const target = { a: 1, b: 2 };
+    const source = { a: null, c: undefined };
+    expect(mergeConfig(target, source)).toEqual({
+      a: null,
+      b: 2,
+      c: undefined,
+    });
+  });
+
+  test("replaces non-plain objects", () => {
+    const date = new Date("2024-01-01");
+    const target = { date: new Date("2020-01-01") };
+    const source = { date };
+    const result = mergeConfig(target, source);
+    expect(result.date).toBe(date);
+  });
+
+  test("does not mutate target", () => {
+    const target = { a: 1, nested: { b: 2 } };
+    const source = { a: 2, nested: { c: 3 } };
+    mergeConfig(target, source);
+    expect(target).toEqual({ a: 1, nested: { b: 2 } });
+  });
+});