zudoku 0.0.0-feat-mermaid-component.c0baaa18 → 0.0.0-feat-navigation-at-property.z8cd07fa5

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>

package/src/lib/navigation/pathMatcher.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it } from "vitest";
+import type { NavigationItem } from "../../config/validators/NavigationSchema.js";
+import { findByPath } from "./pathMatcher.js";
+
+const mockNavigation: NavigationItem[] = [
+  {
+    type: "category",
+    label: "Shipments",
+    items: [
+      { type: "link", label: "Track a Shipment", to: "/track" },
+      { type: "link", label: "Create Shipment", to: "/create" },
+      {
+        type: "category",
+        label: "Nested Category",
+        items: [
+          { type: "link", label: "First Nested", to: "/nested/first" },
+          { type: "link", label: "Second Nested", to: "/nested/second" },
+        ],
+      },
+    ],
+  },
+  { type: "link", label: "About", to: "/about" },
+];
+
+describe("pathMatcher", () => {
+  describe("findByPath", () => {
+    it("should find item by label", () => {
+      const result = findByPath(mockNavigation, "Shipments");
+      expect(result.found).toBe(true);
+      expect(result.item?.label).toBe("Shipments");
+      expect(result.index).toBe(0);
+    });
+
+    it("should find nested item by label path", () => {
+      const result = findByPath(mockNavigation, "Shipments/Track a Shipment");
+      expect(result.found).toBe(true);
+      expect(result.item?.label).toBe("Track a Shipment");
+      expect(result.index).toBe(0);
+    });
+
+    it("should find item by index", () => {
+      const result = findByPath(mockNavigation, "Shipments/0");
+      expect(result.found).toBe(true);
+      expect(result.item?.label).toBe("Track a Shipment");
+      expect(result.index).toBe(0);
+    });
+
+    it("should find nested item by mixed path (label + index)", () => {
+      const result = findByPath(mockNavigation, "Shipments/2/0");
+      expect(result.found).toBe(true);
+      expect(result.item?.label).toBe("First Nested");
+      expect(result.index).toBe(0);
+    });
+
+    it("should be case-insensitive for label matching", () => {
+      const result = findByPath(mockNavigation, "shipments/track a shipment");
+      expect(result.found).toBe(true);
+      expect(result.item?.label).toBe("Track a Shipment");
+    });
+
+    it("should find deeply nested items", () => {
+      const result = findByPath(
+        mockNavigation,
+        "Shipments/Nested Category/Second Nested",
+      );
+      expect(result.found).toBe(true);
+      expect(result.item?.label).toBe("Second Nested");
+      expect(result.index).toBe(1);
+    });
+
+    it("should return found=false for non-existent path", () => {
+      const result = findByPath(mockNavigation, "Nonexistent/Path");
+      expect(result.found).toBe(false);
+      expect(result.item).toBeUndefined();
+    });
+
+    it("should return found=false for invalid index", () => {
+      const result = findByPath(mockNavigation, "Shipments/999");
+      expect(result.found).toBe(false);
+    });
+
+    it("should handle root-level items", () => {
+      const result = findByPath(mockNavigation, "About");
+      expect(result.found).toBe(true);
+      expect(result.item?.label).toBe("About");
+      expect(result.index).toBe(1);
+    });
+
+    it("should provide parentItems for inserting siblings", () => {
+      const result = findByPath(mockNavigation, "Shipments/0");
+      expect(result.parentItems).toBeDefined();
+      expect(result.parentItems?.length).toBe(3); // 2 links + 1 category
+    });
+
+    it("should handle empty path", () => {
+      const result = findByPath(mockNavigation, "");
+      expect(result.found).toBe(false);
+    });
+
+    it("should support negative indices (-1 for last item)", () => {
+      const result = findByPath(mockNavigation, "Shipments/-1");
+      expect(result.found).toBe(true);
+      expect(result.item?.label).toBe("Nested Category");
+    });
+
+    it("should support negative indices (-2 for second-to-last)", () => {
+      const result = findByPath(mockNavigation, "Shipments/-2");
+      expect(result.found).toBe(true);
+      expect(result.item?.label).toBe("Create Shipment");
+    });
+
+    it("should support negative indices in nested paths", () => {
+      const result = findByPath(mockNavigation, "Shipments/-1/-1");
+      expect(result.found).toBe(true);
+      expect(result.item?.label).toBe("Second Nested");
+    });
+
+    it("should handle paths with trailing slashes", () => {
+      const result = findByPath(mockNavigation, "Shipments/0/");
+      expect(result.found).toBe(true);
+      expect(result.item?.label).toBe("Track a Shipment");
+    });
+
+    it("should handle paths with double slashes", () => {
+      const result = findByPath(mockNavigation, "Shipments//0");
+      expect(result.found).toBe(true);
+      expect(result.item?.label).toBe("Track a Shipment");
+    });
+
+    it("should handle paths with leading slashes", () => {
+      const result = findByPath(mockNavigation, "/Shipments/0");
+      expect(result.found).toBe(true);
+      expect(result.item?.label).toBe("Track a Shipment");
+    });
+  });
+});

package/src/lib/navigation/pathMatcher.ts

@@ -0,0 +1,93 @@
+import type { NavigationItem } from "../../config/validators/NavigationSchema.js";
+
+type PathSegment = string | number;
+
+export type PathMatchResult = {
+  found: boolean;
+  item?: NavigationItem;
+  parentItems?: NavigationItem[];
+  index?: number;
+};
+
+const parsePath = (path: string): PathSegment[] => {
+  if (!path || path === "/") return [];
+
+  return path
+    .split("/")
+    .filter((segment) => segment !== "")
+    .map((segment) => {
+      const num = Number(segment);
+      return Number.isInteger(num) ? num : segment;
+    });
+};
+
+const matchesSegment = (
+  segment: PathSegment,
+  item: NavigationItem,
+  index: number,
+  arrayLength: number,
+): boolean => {
+  if (typeof segment === "number") {
+    // Support negative indices (-1 for last, -2 for second-to-last, etc.)
+    const normalizedIndex = segment < 0 ? arrayLength + segment : segment;
+    return normalizedIndex === index;
+  }
+
+  return item.label?.toLowerCase() === segment.toLowerCase();
+};
+
+export const findByPath = (
+  navigation: NavigationItem[],
+  pathString: string,
+): PathMatchResult => {
+  const segments = parsePath(pathString);
+
+  if (segments.length === 0) {
+    return { found: false };
+  }
+
+  let currentItems = navigation;
+  let currentItem: NavigationItem | undefined;
+  let parentItems: NavigationItem[] | undefined;
+  let itemIndex: number | undefined;
+
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+    if (segment === undefined) {
+      return { found: false };
+    }
+    const isLastSegment = i === segments.length - 1;
+
+    const foundIndex = currentItems.findIndex((item, idx) =>
+      matchesSegment(segment, item, idx, currentItems.length),
+    );
+
+    if (foundIndex === -1) {
+      return { found: false };
+    }
+
+    currentItem = currentItems[foundIndex];
+    if (!currentItem) {
+      return { found: false };
+    }
+
+    if (isLastSegment) {
+      parentItems = currentItems;
+      itemIndex = foundIndex;
+      break;
+    }
+
+    if (currentItem.type === "category") {
+      currentItems = currentItem.items;
+    } else {
+      return { found: false };
+    }
+  }
+
+  return {
+    found: true,
+    item: currentItem,
+    parentItems,
+    index: itemIndex,
+  };
+};