zudoku 0.0.0-feat-openapi-docs-redesign.dab3fc6a → 0.0.0-feat-navigation-at-property.z8cd07fa5

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, filterQuery: 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
@@ -86,7 +102,9 @@ export const NavigationItem = ({
           onClick={onRequestClose}
           end
         >
-          {item.icon && <item.icon size={16} className="align-[-0.125em]" />}
+          {item.icon && (
+            <item.icon size={16} className="align-[-0.125em] shrink-0" />
+          )}
           {item.badge ? (
             <>
               {item.label && (
@@ -117,7 +135,9 @@ export const NavigationItem = ({
           })}
           onClick={onRequestClose}
         >
-          {item.icon && <item.icon size={16} className="align-[-0.125em]" />}
+          {item.icon && (
+            <item.icon size={16} className="align-[-0.125em] shrink-0" />
+          )}
           {item.badge ? (
             <>
               {item.label && <TruncatedLabel label={item.label} />}
@@ -135,7 +155,9 @@ export const NavigationItem = ({
           rel="noopener noreferrer"
           onClick={onRequestClose}
         >
-          {item.icon && <item.icon size={16} className="align-[-0.125em]" />}
+          {item.icon && (
+            <item.icon size={16} className="align-[-0.125em] shrink-0" />
+          )}
           <span className="whitespace-normal">{item.label}</span>
           {/* This prevents that the icon would be positioned in its own line if the text fills a line entirely */}
           <span className="whitespace-nowrap">

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

@@ -27,7 +27,7 @@ export const NavigationWrapper = ({
         ref={navRef}
         className={cn(
           "hidden max-w-[calc(var(--side-nav-width)+var(--padding-nav-item))] lg:flex scrollbar flex-col overflow-y-auto shrink-0 text-sm pe-3 ps-4 lg:ps-8",
-          "-mx-(--padding-nav-item) pb-[8vh] pt-(--padding-content-top) scroll-pt-2 gap-1",
+          "-mx-(--padding-nav-item) pb-[8vh] pt-(--padding-content-top) scroll-pt-2",
           // Revert the padding/margin on the first child
           "-mt-2.5",
           className,

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

@@ -6,6 +6,7 @@ import type {
 } from "../../../config/validators/NavigationSchema.js";
 import type { UseAuthReturn } from "../../authentication/hook.js";
 import type { ZudokuContext } from "../../core/ZudokuContext.js";
+import { isPositionedItem } from "../../navigation/positionItems.js";
 import { joinUrl } from "../../util/joinUrl.js";
 import { useCurrentNavigation } from "../context/ZudokuContext.js";
 
@@ -86,6 +87,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)
@@ -111,7 +119,7 @@ export const usePrevNext = (): {
 };
 
 export const navigationListItem = cva(
-  "relative flex items-center gap-2 px-(--padding-nav-item) my-0.5 py-1.5 rounded-lg hover:bg-accent tabular-nums",
+  "relative flex items-center gap-2 px-(--padding-nav-item) my-px py-1.5 rounded-lg hover:bg-accent tabular-nums",
   {
     variants: {
       isActive: {
@@ -133,9 +141,43 @@ 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,
+    context,
+    filterQuery,
+  }: {
+    auth: UseAuthReturn;
+    context: ZudokuContext;
+    filterQuery?: string;
+  }) =>
   (item: NavigationItem): boolean => {
+    if (item.type === "filter") return true;
+
+    if (isPositionedItem(item)) return false;
+
+    if (filterQuery?.trim() && !itemMatchesFilter(item, filterQuery)) {
+      return false;
+    }
+
     if (typeof item.display === "function") {
       return item.display({ context, auth });
     }

package/src/lib/core/RouteGuard.tsx

@@ -27,16 +27,31 @@ export const RouteGuard = () => {
   const shouldBypass = use(BypassProtectedRoutesContext);
   const { protectedRoutes } = zudoku.options;
 
-  const authCheckFn =
-    !shouldBypass && protectedRoutes
-      ? Object.entries(protectedRoutes).find(([path]) =>
-          matchPath({ path, end: true }, location.pathname),
-        )?.[1]
-      : undefined;
+  const protectedRouteEntry = protectedRoutes
+    ? Object.entries(protectedRoutes).find(([path]) =>
+        matchPath({ path, end: true }, location.pathname),
+      )
+    : undefined;
 
-  const isProtectedRoute = authCheckFn !== undefined;
-  const needsToSignIn =
-    isProtectedRoute && !authCheckFn({ auth, context: zudoku });
+  const isProtectedRoute = protectedRouteEntry !== undefined;
+
+  // SSR/prerendering mode: render content with search meta tag, skip all auth
+  if (shouldBypass) {
+    return (
+      <>
+        {isProtectedRoute && (
+          <Helmet>
+            <meta
+              name="pagefind"
+              data-pagefind-filter={`section:${SEARCH_PROTECTED_SECTION}`}
+              content="true"
+            />
+          </Helmet>
+        )}
+        <Outlet />
+      </>
+    );
+  }
 
   if (isProtectedRoute && !auth.isAuthEnabled) {
     throw new ZudokuError("Authentication is not enabled", {
@@ -46,6 +61,10 @@ export const RouteGuard = () => {
     });
   }
 
+  const authCheckFn = protectedRouteEntry?.[1];
+  const needsToSignIn =
+    isProtectedRoute && !authCheckFn?.({ auth, context: zudoku });
+
   if (needsToSignIn && auth.isPending && typeof window !== "undefined") {
     return null;
   }
@@ -91,7 +110,7 @@ export const RouteGuard = () => {
                 )
               }
             >
-              Login{" "}
+              Login
             </Button>
           </DialogFooter>
         </DialogContent>
@@ -99,18 +118,5 @@ export const RouteGuard = () => {
     );
   }
 
-  return (
-    <>
-      {shouldBypass && (
-        <Helmet>
-          <meta
-            name="pagefind"
-            data-pagefind-filter={`section:${SEARCH_PROTECTED_SECTION}`}
-            content="true"
-          />
-        </Helmet>
-      )}
-      <Outlet />
-    </>
-  );
+  return <Outlet />;
 };

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

@@ -1,8 +1,9 @@
 import type { LucideIcon } from "lucide-react";
-import type { ReactElement } from "react";
+import type { ReactNode } from "react";
 import type { Location, RouteObject } from "react-router";
 import type { Navigation } from "../../config/validators/NavigationSchema.js";
 import type { ProtectedRoutesInput } from "../../config/validators/ProtectedRoutesSchema.js";
+import type { ZudokuConfig } from "../../config/validators/validate.js";
 import type { AuthenticationPlugin } from "../authentication/authentication.js";
 import type { MdxComponentsType } from "../util/MdxComponents.js";
 import type {
@@ -18,7 +19,8 @@ export type ZudokuPlugin =
   | ApiIdentityPlugin
   | SearchProviderPlugin
   | EventConsumerPlugin
-  | AuthenticationPlugin;
+  | AuthenticationPlugin
+  | TransformConfigPlugin;
 
 export type { AuthenticationPlugin, RouteObject };
 
@@ -60,11 +62,28 @@ export type ProfileNavigationItem = {
   icon?: LucideIcon;
 };
 
+export interface ConfigHookContext {
+  mode: typeof process.env.ZUDOKU_ENV;
+  rootDir: string;
+  configPath: string;
+}
+
+export interface TransformConfigContext {
+  config: ZudokuConfig;
+  merge: <T extends Partial<ZudokuConfig>>(partial: T) => ZudokuConfig & T;
+}
+
+export interface TransformConfigPlugin {
+  transformConfig?: (
+    context: TransformConfigContext,
+  ) => ZudokuConfig | void | Promise<ZudokuConfig | void>;
+}
+
 export interface CommonPlugin {
   initialize?: (
     context: ZudokuContext,
   ) => Promise<void | boolean> | void | boolean;
-  getHead?: ({ location }: { location: Location }) => ReactElement | undefined;
+  getHead?: (args: { location: Location }) => ReactNode | undefined;
   getMdxComponents?: () => MdxComponentsType;
 }
 
@@ -110,3 +129,8 @@ export const isApiIdentityPlugin = (
   obj: ZudokuPlugin,
 ): obj is ApiIdentityPlugin =>
   "getIdentities" in obj && typeof obj.getIdentities === "function";
+
+export const isTransformConfigPlugin = (
+  obj: ZudokuPlugin,
+): obj is TransformConfigPlugin =>
+  "transformConfig" in obj && typeof obj.transformConfig === "function";

package/src/lib/core/react-query.ts

@@ -0,0 +1 @@
+export * from "@tanstack/react-query";

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

package/src/lib/core/transform-config.ts

@@ -0,0 +1,67 @@
+import { isValidElement } from "react";
+import type { ZudokuConfig } from "../../config/validators/validate.js";
+import { isTransformConfigPlugin } from "./plugins.js";
+
+export const isPlainObject = (
+  value: unknown,
+): value is Record<string, unknown> =>
+  typeof value === "object" &&
+  value !== null &&
+  !Array.isArray(value) &&
+  Object.getPrototypeOf(value) === Object.prototype;
+
+export const mergeConfig = <
+  T extends Record<string, unknown>,
+  S extends Record<string, unknown>,
+>(
+  target: T,
+  source: S,
+): T & S => {
+  const result = { ...target } as T & S;
+
+  for (const key of Object.keys(source) as (keyof S)[]) {
+    const sourceValue = source[key];
+    const targetValue = target[key as keyof T];
+
+    // Don't merge React elements, arrays, or non-plain objects - just replace
+    if (
+      isValidElement(sourceValue) ||
+      Array.isArray(sourceValue) ||
+      !isPlainObject(sourceValue)
+    ) {
+      (result as Record<string, unknown>)[key as string] = sourceValue;
+    } else if (isPlainObject(targetValue)) {
+      (result as Record<string, unknown>)[key as string] = mergeConfig(
+        targetValue,
+        sourceValue,
+      );
+    } else {
+      (result as Record<string, unknown>)[key as string] = sourceValue;
+    }
+  }
+
+  return result;
+};
+
+export const runPluginTransformConfig = async <T extends ZudokuConfig>(
+  config: T,
+): Promise<T> => {
+  const plugins = config.plugins ?? [];
+
+  let result = config;
+
+  for (const plugin of plugins.filter(isTransformConfigPlugin)) {
+    const merge = <T extends Record<string, unknown>>(partial: T) =>
+      mergeConfig(result, partial);
+
+    const transformed = await plugin.transformConfig?.({
+      config: result,
+      merge,
+    });
+    if (!transformed) continue;
+
+    result = transformed as T;
+  }
+
+  return result;
+};

package/src/lib/errors/ErrorAlert.tsx

@@ -1,4 +1,3 @@
-import { SyntaxHighlight } from "zudoku/ui/SyntaxHighlight.js";
 import { DeveloperHint } from "../components/DeveloperHint.js";
 import { Heading } from "../components/Heading.js";
 import { Typography } from "../components/Typography.js";
@@ -22,11 +21,7 @@ export function ErrorAlert({ error }: { error: unknown }) {
       Error: {message}
       {hint && <DeveloperHint className="mb-4">{hint}</DeveloperHint>}
       {stringError && (
-        <SyntaxHighlight
-          className="max-h-[400px] [&>pre]:p-4"
-          language="js"
-          code={stringError}
-        />
+        <pre className="max-h-[400px] [&>pre]:p-4">{stringError}</pre>
       )}
     </Typography>
   );

package/src/lib/errors/ErrorMessage.tsx

@@ -0,0 +1,38 @@
+import { Alert, AlertDescription, AlertTitle } from "zudoku/ui/Alert.js";
+import { SyntaxHighlight } from "zudoku/ui/SyntaxHighlight.js";
+import { DeveloperHint } from "../components/DeveloperHint.js";
+import { ZudokuError } from "../util/invariant.js";
+
+export function ErrorMessage({ error }: { error: unknown }) {
+  const message =
+    error instanceof Error ? error.message : "Something went wrong";
+
+  const showDeveloperHints = process.env.NODE_ENV === "development";
+
+  const hint = error instanceof ZudokuError ? error.developerHint : undefined;
+  const title =
+    error instanceof ZudokuError ? error.title : "Something went wrong";
+  const stack = error instanceof Error ? error.stack : undefined;
+  const cause = error instanceof Error ? error.cause : undefined;
+
+  const stringError = cause instanceof Error ? String(cause.stack) : stack;
+
+  return (
+    <>
+      <Alert variant="destructive">
+        <AlertTitle>{title}</AlertTitle>
+        <AlertDescription>{message}</AlertDescription>
+      </Alert>
+      {showDeveloperHints && hint && (
+        <DeveloperHint className="mb-4">{hint}</DeveloperHint>
+      )}
+      {showDeveloperHints && stringError && (
+        <SyntaxHighlight
+          className="max-h-[400px] [&>pre]:p-4"
+          language="js"
+          code={stringError}
+        />
+      )}
+    </>
+  );
+}

package/src/lib/hooks/index.ts

@@ -1,16 +1,7 @@
-import { useMDXComponents as useMDXComponentsImport } from "@mdx-js/react";
-import { useTheme as useThemeImport } from "next-themes";
-import { useAuth as useAuthImport } from "../authentication/hook.js";
-import { CACHE_KEYS, useCache as useCacheImport } from "../components/cache.js";
-import { useZudoku as useZudokuImport } from "../components/context/ZudokuContext.js";
-import { useExposedProps as useExposedPropsImport } from "../util/useExposedProps.js";
-import { useEvent as useEventImport } from "./useEvent.js";
-
-export const useEvent = /*@__PURE__*/ useEventImport;
-export const useTheme = /*@__PURE__*/ useThemeImport;
-export const useExposedProps = /*@__PURE__*/ useExposedPropsImport;
-export const useMDXComponents = /*@__PURE__*/ useMDXComponentsImport;
-export const useAuth = /*@__PURE__*/ useAuthImport;
-export const useZudoku = /*@__PURE__*/ useZudokuImport;
-export const useCache = /*@__PURE__*/ useCacheImport;
-export { CACHE_KEYS };
+export { useMDXComponents } from "@mdx-js/react";
+export { useTheme } from "next-themes";
+export { useAuth } from "../authentication/hook.js";
+export { CACHE_KEYS, useCache } from "../components/cache.js";
+export { useZudoku } from "../components/context/ZudokuContext.js";
+export { useExposedProps } from "../util/useExposedProps.js";
+export { useEvent } from "./useEvent.js";

package/src/lib/hooks/useEvent.test.tsx

@@ -13,7 +13,7 @@ import { useEvent } from "./useEvent.js";
 
 const createTestContext = () => {
   const queryClient = new QueryClient();
-  const context = new ZudokuContext({}, queryClient);
+  const context = new ZudokuContext({}, queryClient, {});
   const wrapper = ({ children }: PropsWithChildren) => (
     <QueryClientProvider client={queryClient}>
       <ZudokuProvider context={context}>{children}</ZudokuProvider>