zudoku 0.0.0-z179c4f85 → 0.0.0-z2f55b5ae

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

@@ -3,6 +3,7 @@ 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,6 +62,23 @@ 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,
@@ -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/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/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/oas/graphql/circular.test.ts

@@ -156,16 +156,20 @@ describe("handleCircularRefs", () => {
     });
   });
 
-  it("should deduplicate shared object instances with __$ref", () => {
+  it("should handle shared object instances with __$ref without marking circular", () => {
     const shared = { __$ref: "#/components/schemas/Foo", type: "string" };
     const obj = { a: shared, b: shared };
     const result = handleCircularRefs(obj);
 
+    // Both should return the cached result, not mark as circular
     expect(result.a).toEqual({
       __$ref: "#/components/schemas/Foo",
       type: "string",
     });
-    expect(result.b).toBe(`${SCHEMA_REF_PREFIX}#/components/schemas/Foo`);
+    expect(result.b).toEqual({
+      __$ref: "#/components/schemas/Foo",
+      type: "string",
+    });
   });
 
   it("should mark circular ref with property name from path", () => {
@@ -183,4 +187,35 @@ describe("handleCircularRefs", () => {
 
     expect(result.properties.child.properties.back).toContain(CIRCULAR_REF);
   });
+
+  // Exact reproduction of #1869 - shared object instances with __$ref
+  it("should NOT mark shared object instances with __$ref as circular (issue #1869)", () => {
+    // When dereferencing, the SAME object instance is returned for all refs to the same schema
+    const timestampSchema = {
+      __$ref: "#/components/schemas/timestamp",
+      type: "string",
+      format: "date-time",
+    };
+
+    // Both created_at and updated_at point to the SAME object instance
+    const obj = {
+      type: "object",
+      properties: {
+        created_at: timestampSchema,
+        updated_at: timestampSchema,
+      },
+    };
+
+    const result = handleCircularRefs(obj);
+
+    // The first one should be fully expanded
+    expect(result.properties.created_at).toEqual({
+      __$ref: "#/components/schemas/timestamp",
+      type: "string",
+      format: "date-time",
+    });
+    // The second one should ALSO be fully expanded (not marked as circular)
+    expect(typeof result.properties.updated_at).toBe("object");
+    expect(result.properties.updated_at).not.toContain(CIRCULAR_REF);
+  });
 });

package/src/lib/oas/graphql/circular.ts

@@ -1,6 +1,5 @@
 import { GraphQLScalarType } from "graphql/index.js";
 import { GraphQLJSON } from "graphql-type-json";
-import type { RecordAny } from "../../util/traverse.js";
 
 export const CIRCULAR_REF = "$[Circular Reference]";
 export const SCHEMA_REF_PREFIX = "$ref:";
@@ -17,73 +16,48 @@ const OPENAPI_PROPS = new Set([
 export const handleCircularRefs = (
   // biome-ignore lint/suspicious/noExplicitAny: Allow any type
   obj: any,
-  visited = new WeakSet(),
+  currentPath = new WeakSet(),
   refs = new WeakMap(),
   path: string[] = [],
-  seenRefPaths = new Set<string>(),
+  currentRefPaths = new Set<string>(),
   // biome-ignore lint/suspicious/noExplicitAny: Allow any type
 ): any => {
   if (obj === null || typeof obj !== "object") return obj;
 
   const refPath = obj.__$ref;
+  const isCircular =
+    currentPath.has(obj) ||
+    (typeof refPath === "string" && currentRefPaths.has(refPath));
 
-  // Check if this object has a __$ref marker (set during schema code generation)
-  // If we've already fully processed this ref path, return a reference marker
-  // instead of the full data to avoid JSON.stringify serializing duplicates
-  if (typeof refPath === "string" && seenRefPaths.has(refPath)) {
-    return SCHEMA_REF_PREFIX + refPath;
-  }
-
-  if (visited.has(obj)) {
-    const cached = refs.get(obj);
-    if (cached) {
-      return typeof refPath === "string"
-        ? // If already processed, return ref marker to avoid duplicate serialization
-          SCHEMA_REF_PREFIX + refPath
-        : cached;
-    }
+  if (isCircular) {
+    if (typeof refPath === "string") return SCHEMA_REF_PREFIX + refPath;
     const circularProp = path.find((p) => !OPENAPI_PROPS.has(p)) || path[0];
-
     return [CIRCULAR_REF, circularProp].filter(Boolean).join(":");
   }
 
-  visited.add(obj);
+  if (refs.has(obj)) return refs.get(obj);
 
-  // Add refPath BEFORE recursing to detect cycles within this branch
-  // This will be removed after processing to allow siblings with the same ref
-  if (typeof refPath === "string") {
-    seenRefPaths.add(refPath);
-  }
+  currentPath.add(obj);
+  if (typeof refPath === "string") currentRefPaths.add(refPath);
 
-  let result: RecordAny | RecordAny[];
-  if (Array.isArray(obj)) {
-    result = obj.map((item, index) =>
-      handleCircularRefs(
-        item,
-        visited,
-        refs,
-        [...path, index.toString()],
-        seenRefPaths,
-      ),
+  const recurse = (value: unknown, key: string) =>
+    handleCircularRefs(
+      value,
+      currentPath,
+      refs,
+      [...path, key],
+      currentRefPaths,
     );
-  } else {
-    result = {};
-    for (const [key, value] of Object.entries(obj)) {
-      result[key] = handleCircularRefs(
-        value,
-        visited,
-        refs,
-        [...path, key],
-        seenRefPaths,
+
+  const result = Array.isArray(obj)
+    ? obj.map((item, i) => recurse(item, i.toString()))
+    : Object.fromEntries(
+        Object.entries(obj).map(([k, v]) => [k, recurse(v, k)]),
       );
-    }
-  }
-  refs.set(obj, result);
 
-  // Remove refPath after processing so sibling refs aren't incorrectly marked
-  if (typeof refPath === "string") {
-    seenRefPaths.delete(refPath);
-  }
+  refs.set(obj, result);
+  currentPath.delete(obj);
+  if (typeof refPath === "string") currentRefPaths.delete(refPath);
 
   return result;
 };

package/src/lib/oas/parser/index.ts

@@ -1,6 +1,7 @@
 import { GraphQLError } from "graphql/error/index.js";
 import { OpenAPIV3, type OpenAPIV3_1 } from "openapi-types";
-import { flattenAllOfProcessor } from "../../util/flattenAllOf.js";
+import { flattenAllOf } from "../../util/flattenAllOf.js";
+import { traverse } from "../../util/traverse.js";
 import { dereference, type JSONSchema } from "./dereference/index.js";
 import { upgradeSchema } from "./upgrade/index.js";
 
@@ -104,11 +105,21 @@ export const validate = async (schemaInput: unknown) => {
   const dereferenced = await dereference(schema);
   const upgraded = upgradeSchema(dereferenced);
 
-  const flattened = await flattenAllOfProcessor({
-    schema: upgraded,
-    file: "schema.json",
-    dereference: async (schema) => schema,
-  });
+  const flattened = traverse(upgraded, (spec) => {
+    if (!spec || typeof spec !== "object" || Array.isArray(spec)) {
+      return spec;
+    }
+    const isSchemaObject =
+      "type" in spec ||
+      "properties" in spec ||
+      "allOf" in spec ||
+      "anyOf" in spec ||
+      "oneOf" in spec;
+
+    if (!isSchemaObject) return spec;
+
+    return flattenAllOf(spec) as typeof spec;
+  }) as OpenAPIDocument;
 
   return flattened;
 };

package/src/lib/plugins/openapi/OasProvider.tsx

@@ -19,13 +19,21 @@ export const OasProvider = ({
   client: GraphQLClient;
 }) => {
   const value = useMemo(() => {
-    const { versions: availableVersions, labels } = getVersionMetadata(config);
+    const {
+      versions: availableVersions,
+      labels,
+      downloadUrls,
+    } = getVersionMetadata(config);
     const currentVersion = version ?? availableVersions.at(0);
 
     const versionLinks = Object.fromEntries(
       availableVersions.map((id) => [
         id,
-        { path: joinUrl(basePath, id), label: labels[id] ?? id },
+        {
+          path: joinUrl(basePath, id),
+          label: labels[id] ?? id,
+          downloadUrl: downloadUrls[id],
+        },
       ]),
     );