zudoku 0.0.0-z179c4f85 → 0.0.0-z2f55b5ae

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zudoku",
-  "version": "0.0.0-z179c4f85",
+  "version": "0.0.0-z2f55b5ae",
   "type": "module",
   "homepage": "https://zudoku.dev",
   "repository": {
@@ -18,6 +18,7 @@
     "src/lib",
     "src/app",
     "src/shiki",
+    "src/zuplo",
     "client.d.ts"
   ],
   "bin": {
@@ -184,18 +185,18 @@
     "@radix-ui/react-visually-hidden": "1.2.4",
     "@scalar/openapi-parser": "0.23.2",
     "@sentry/node": "10.27.0",
-    "@shikijs/engine-javascript": "3.20.0",
-    "@shikijs/langs": "3.20.0",
-    "@shikijs/rehype": "3.20.0",
-    "@shikijs/themes": "3.20.0",
-    "@shikijs/transformers": "3.20.0",
+    "@shikijs/engine-javascript": "3.21.0",
+    "@shikijs/langs": "3.21.0",
+    "@shikijs/rehype": "3.21.0",
+    "@shikijs/themes": "3.21.0",
+    "@shikijs/transformers": "3.21.0",
     "@sindresorhus/slugify": "3.0.0",
     "@stefanprobst/rehype-extract-toc": "3.0.0",
     "@tailwindcss/typography": "0.5.19",
     "@tailwindcss/vite": "4.1.16",
     "@tanem/react-nprogress": "5.0.56",
     "@tanstack/react-query": "5.90.12",
-    "@types/react": "19.2.7",
+    "@types/react": "19.2.10",
     "@types/react-dom": "19.2.3",
     "@vitejs/plugin-react": "5.1.0",
     "@x0k/json-schema-merge": "1.0.2",
@@ -232,10 +233,10 @@
     "pagefind": "1.5.0-beta.1",
     "picocolors": "1.1.1",
     "piscina": "5.1.4",
-    "posthog-node": "5.14.1",
+    "posthog-node": "5.21.2",
     "react-error-boundary": "6.0.0",
     "react-hook-form": "7.66.0",
-    "react-is": "19.2.3",
+    "react-is": "19.2.4",
     "react-markdown": "10.1.0",
     "react-router": "7.12.0",
     "rehype-mdx-import-media": "1.2.0",
@@ -249,7 +250,7 @@
     "remark-mdx-frontmatter": "5.2.0",
     "rollup": "4.52.5",
     "semver": "7.7.2",
-    "shiki": "3.20.0",
+    "shiki": "3.21.0",
     "sitemap": "9.0.0",
     "strip-ansi": "7.1.2",
     "tailwind-merge": "3.4.0",
@@ -262,12 +263,12 @@
     "vite": "6.4.1",
     "yaml": "2.8.1",
     "yargs": "18.0.0",
-    "zod": "4.1.12",
+    "zod": "4.3.6",
     "zustand": "5.0.8"
   },
   "devDependencies": {
     "@graphql-codegen/cli": "6.1.0",
-    "@inkeep/cxkit-types": "0.5.101",
+    "@inkeep/cxkit-types": "0.5.113",
     "@testing-library/dom": "10.4.1",
     "@testing-library/jest-dom": "6.9.1",
     "@testing-library/react": "16.3.0",
@@ -288,8 +289,8 @@
     "esbuild": "0.27.0",
     "happy-dom": "20.0.10",
     "mdast-util-mdx": "3.0.0",
-    "react": "19.2.3",
-    "react-dom": "19.2.3",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
     "rollup-plugin-visualizer": "6.0.5",
     "tsx": "4.20.6",
     "typescript": "5.9.3",
@@ -307,6 +308,13 @@
     "react": ">=19.2.0",
     "react-dom": ">=19.2.0"
   },
+  "typesVersions": {
+    "*": {
+      "ui/*": [
+        "./src/lib/ui/*"
+      ]
+    }
+  },
   "peerDependenciesMeta": {
     "@azure/msal-browser": {
       "optional": true
@@ -335,7 +343,7 @@
   },
   "scripts": {
     "build": "tsc --project tsconfig.app.json",
-    "build:dev": "esbuild './src/**/*.ts' --format=esm --platform=node --target=node22 --outdir=dist --splitting --log-level=warning",
+    "build:dev": "esbuild './src/**/*.ts' './src/**/*.tsx' --format=esm --platform=node --target=node22 --outdir=dist --splitting --log-level=warning",
     "build:vite": "vite build",
     "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",

package/src/app/defaultTheme.css

@@ -20,6 +20,8 @@
   --accent: oklch(0.967 0.001 286.375);
   --accent-foreground: oklch(0.21 0.006 285.885);
   --destructive: oklch(0.577 0.245 27.325);
+  --warning: oklch(0.84 0.16 84);
+  --warning-foreground: oklch(0.47 0.14 46.2);
   --border: oklch(0.92 0.004 286.32);
   --input: oklch(0.92 0.004 286.32);
   --ring: oklch(0.705 0.015 286.067);
@@ -54,6 +56,8 @@
   --accent: oklch(0.274 0.006 286.033);
   --accent-foreground: oklch(0.985 0 0);
   --destructive: oklch(0.704 0.191 22.216);
+  --warning: oklch(0.41 0.11 46);
+  --warning-foreground: oklch(0.99 0.02 95);
   --border: oklch(1 0 0 / 10%);
   --input: oklch(1 0 0 / 15%);
   --ring: oklch(0.552 0.016 285.938);

package/src/app/main.css

@@ -8,6 +8,8 @@
 @custom-variant dark (&:is(.dark *));
 
 @theme inline {
+  --color-warning: var(--warning);
+  --color-warning-foreground: var(--warning-foreground);
   --color-background: var(--background);
   --color-foreground: var(--foreground);
   --color-card: var(--card);

package/src/app/main.tsx

@@ -111,7 +111,7 @@ export const getRoutesByConfig = (config: ZudokuConfig): RouteObject[] => {
   return [
     {
       element: (
-        <Zudoku {...options}>
+        <Zudoku {...options} env={import.meta.env}>
           <BuildCheck
             buildId={import.meta.env.ZUPLO_BUILD_ID}
             environmentType={import.meta.env.ZUPLO_ENVIRONMENT_TYPE}

package/src/lib/components/Bootstrap.tsx

@@ -12,7 +12,6 @@ import {
   StaticRouterProvider,
 } from "react-router";
 import { RouterProvider } from "react-router/dom";
-import { StaggeredRenderContext } from "../plugins/openapi/StaggeredRender.js";
 import { BypassProtectedRoutesContext } from "./context/BypassProtectedRoutesContext.js";
 
 const queryClient = new QueryClient({
@@ -36,9 +35,7 @@ const Bootstrap = ({
       <HydrationBoundary state={hydrate ? (window as any).DATA : undefined}>
         <BypassProtectedRoutesContext value={false}>
           <HelmetProvider>
-            <StaggeredRenderContext.Provider value={{ stagger: !hydrate }}>
-              <RouterProvider router={router} />
-            </StaggeredRenderContext.Provider>
+            <RouterProvider router={router} />
           </HelmetProvider>
         </BypassProtectedRoutesContext>
       </HydrationBoundary>

package/src/lib/components/MobileTopNavigation.tsx

@@ -1,6 +1,7 @@
 import { VisuallyHidden } from "@radix-ui/react-visually-hidden";
 import { MenuIcon } from "lucide-react";
 import { useState } from "react";
+import { Separator } from "zudoku/ui/Separator.js";
 import { Skeleton } from "zudoku/ui/Skeleton.js";
 import { useAuth } from "../authentication/hook.js";
 import {
@@ -43,7 +44,7 @@ export const MobileTopNavigation = () => {
         <PageProgress />
       </div>
       <DrawerContent
-        className="lg:hidden h-[100dvh] end-0 start-auto w-[320px] rounded-none"
+        className="lg:hidden h-dvh end-0 start-auto w-[320px] rounded-none"
         aria-describedby={undefined}
       >
         <div className="p-4 overflow-y-auto overscroll-none h-full flex flex-col justify-between">
@@ -84,13 +85,17 @@ export const MobileTopNavigation = () => {
                   )}
                 </ClientOnly>
               )}
-              {filteredItems.map((item) => (
-                <li key={item.label}>
-                  <button type="button" onClick={() => setDrawerOpen(false)}>
-                    <TopNavItem {...item} />
-                  </button>
-                </li>
-              ))}
+              {filteredItems.map((item) =>
+                item.type === "separator" ? (
+                  <Separator className="w-full" key={item.label} />
+                ) : item.type !== "section" && item.type !== "filter" ? (
+                  <li key={item.label}>
+                    <button type="button" onClick={() => setDrawerOpen(false)}>
+                      <TopNavItem {...item} />
+                    </button>
+                  </li>
+                ) : null,
+              )}
               {isAuthEnabled && isAuthenticated && accountItems.length > 0 && (
                 <ClientOnly
                   fallback={<Skeleton className="rounded-sm h-5 w-24 mr-4" />}

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/index.ts

@@ -1,46 +1,26 @@
-import { useMDXComponents as useMDXComponentsImport } from "@mdx-js/react";
-import { Helmet } from "@zudoku/react-helmet-async";
-import { useTheme as useThemeImport } from "next-themes";
-import { Link as LinkImport } from "react-router";
-import { useAuth as useAuthImport } from "../authentication/hook.js";
-import { Button as ButtonImport } from "../ui/Button.js";
-import { Callout as CalloutImport } from "../ui/Callout.js";
-import { ZudokuError as ZudokuErrorImport } from "../util/invariant.js";
-import { ClientOnly as ClientOnlyImport } from "./ClientOnly.js";
-import {
-  CACHE_KEYS as CACHE_KEYS_IMPORT,
-  useCache as useCacheImport,
-} from "./cache.js";
-import { useZudoku as useZudokuImport } from "./context/ZudokuContext.js";
-import { Heading as HeadingImport } from "./Heading.js";
-import { Markdown as MarkdownImport } from "./Markdown.js";
-import { Slot as SlotImport } from "./Slot.js";
-import { Spinner as SpinnerImport } from "./Spinner.js";
-import { Typography as TypographyImport } from "./Typography.js";
-import { Zudoku as ZudokuImport } from "./Zudoku.js";
+export { Helmet as Head } from "@zudoku/react-helmet-async";
+export { Link } from "react-router";
+export { Button } from "../ui/Button.js";
+export { Callout } from "../ui/Callout.js";
+export { ZudokuError } from "../util/invariant.js";
+export { ClientOnly } from "./ClientOnly.js";
+export { Heading } from "./Heading.js";
+export { Markdown } from "./Markdown.js";
+export { Search } from "./Search.js";
+export { Slot } from "./Slot.js";
+export { Spinner } from "./Spinner.js";
+export { Typography } from "./Typography.js";
+export { Zudoku } from "./Zudoku.js";
 
-export const Head = /*@__PURE__*/ Helmet;
-export const Heading = /*@__PURE__*/ HeadingImport;
-export const Callout = /*@__PURE__*/ CalloutImport;
-export const Markdown = /*@__PURE__*/ MarkdownImport;
-export const Spinner = /*@__PURE__*/ SpinnerImport;
-export const ClientOnly = /*@__PURE__*/ ClientOnlyImport;
-export const Button = /*@__PURE__*/ ButtonImport;
-export const Link = /*@__PURE__*/ LinkImport;
-export const Zudoku = /*@__PURE__*/ ZudokuImport;
-export const Typography = /*@__PURE__*/ TypographyImport;
-export const Slot = /*@__PURE__*/ SlotImport;
-export const ZudokuError = /*@__PURE__*/ ZudokuErrorImport;
+//
 
 /** @deprecated Import from `zudoku/hooks` instead */
-export const useMDXComponents = /*@__PURE__*/ useMDXComponentsImport;
+export { useMDXComponents } from "@mdx-js/react";
 /** @deprecated Import from `zudoku/hooks` instead */
-export const useZudoku = /*@__PURE__*/ useZudokuImport;
+export { useTheme } from "next-themes";
 /** @deprecated Import from `zudoku/hooks` instead */
-export const useAuth = /*@__PURE__*/ useAuthImport;
+export { useAuth } from "../authentication/hook.js";
 /** @deprecated Import from `zudoku/hooks` instead */
-export const useCache = /*@__PURE__*/ useCacheImport;
+export { CACHE_KEYS, useCache } from "./cache.js";
 /** @deprecated Import from `zudoku/hooks` instead */
-export const CACHE_KEYS = /*@__PURE__*/ CACHE_KEYS_IMPORT;
-/** @deprecated Import from `zudoku/hooks` instead */
-export const useTheme = /*@__PURE__*/ useThemeImport;
+export { useZudoku } from "./context/ZudokuContext.js";

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>
+  );
+};