zudoku 0.0.0-feda542 → 0.0.0-ff27e7ea

package/src/lib/core/plugins.ts

@@ -1,7 +1,9 @@
 import type { LucideIcon } from "lucide-react";
 import type { ReactElement } from "react";
 import type { Location, RouteObject } from "react-router";
-import type { Sidebar } from "../../config/validators/SidebarSchema.js";
+import type { Navigation } from "../../config/validators/NavigationSchema.js";
+import type { ProtectedRoutesInput } from "../../config/validators/ProtectedRoutesSchema.js";
+import type { AuthenticationPlugin } from "../authentication/authentication.js";
 import type { MdxComponentsType } from "../util/MdxComponents.js";
 import type {
   ApiIdentity,
@@ -15,13 +17,15 @@ export type ZudokuPlugin =
   | NavigationPlugin
   | ApiIdentityPlugin
   | SearchProviderPlugin
-  | EventConsumerPlugin;
+  | EventConsumerPlugin
+  | AuthenticationPlugin;
 
-export type { RouteObject };
+export type { AuthenticationPlugin, RouteObject };
 
 export interface NavigationPlugin {
   getRoutes: () => RouteObject[];
-  getSidebar?: (path: string, context: ZudokuContext) => Promise<Sidebar>;
+  getNavigation?: (path: string, context: ZudokuContext) => Promise<Navigation>;
+  getProtectedRoutes?: () => ProtectedRoutesInput;
 }
 
 export const createApiIdentityPlugin = (
@@ -83,6 +87,11 @@ export const isNavigationPlugin = (
 ): obj is NavigationPlugin =>
   "getRoutes" in obj && typeof obj.getRoutes === "function";
 
+export const isAuthenticationPlugin = (
+  obj: ZudokuPlugin,
+): obj is AuthenticationPlugin =>
+  "signUp" in obj && typeof obj.signUp === "function";
+
 export const isSearchPlugin = (
   obj: ZudokuPlugin,
 ): obj is SearchProviderPlugin =>

package/src/lib/core/router.ts

@@ -0,0 +1 @@
+export * from "react-router";

package/src/lib/errors/ErrorAlert.tsx

@@ -1,9 +1,7 @@
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 import { SyntaxHighlight } from "zudoku/ui/SyntaxHighlight.js";
 import { DeveloperHint } from "../components/DeveloperHint.js";
 import { Heading } from "../components/Heading.js";
-import { ProseClasses } from "../components/Markdown.js";
-import { cn } from "../util/cn.js";
+import { Typography } from "../components/Typography.js";
 import { ZudokuError } from "../util/invariant.js";
 
 export function ErrorAlert({ error }: { error: unknown }) {
@@ -19,24 +17,17 @@ export function ErrorAlert({ error }: { error: unknown }) {
   const stringError = cause instanceof Error ? String(cause.stack) : stack;
 
   return (
-    <div
-      className={cn(
-        ProseClasses,
-        "grid grid-cols-1 !max-w-none pt-[--padding-content-top]",
-      )}
-    >
+    <Typography className="grid grid-cols-1 max-w-none! pt-(--padding-content-top)">
       <Heading level={1}>{title}</Heading>
       Error: {message}
       {hint && <DeveloperHint className="mb-4">{hint}</DeveloperHint>}
       {stringError && (
-        <div>
-          <SyntaxHighlight
-            className="max-h-[400px] border mt-2"
-            language="jsstacktrace"
-            code={stringError}
-          />
-        </div>
+        <SyntaxHighlight
+          className="max-h-[400px] [&>pre]:p-4"
+          language="js"
+          code={stringError}
+        />
       )}
-    </div>
+    </Typography>
   );
 }

package/src/lib/errors/RouterError.tsx

@@ -1,13 +1,18 @@
 import { isRouteErrorResponse, useRouteError } from "react-router";
 import { NotFoundPage } from "../components/NotFoundPage.js";
+import { cn } from "../util/cn.js";
 import { ErrorAlert } from "./ErrorAlert.js";
 
-export function RouterError() {
+export function RouterError({ className }: { className?: string }) {
   const error = useRouteError();
 
   if (isRouteErrorResponse(error) && error.status === 404) {
     return <NotFoundPage />;
   }
 
-  return <ErrorAlert error={error} />;
+  return (
+    <div className={cn("mx-4 max-w-2xl", className)}>
+      <ErrorAlert error={error} />
+    </div>
+  );
 }

package/src/lib/errors/TopLevelError.tsx

@@ -1,8 +1,6 @@
-import { FallbackProps } from "react-error-boundary";
+import type { FallbackProps } from "react-error-boundary";
 import { ErrorAlert } from "./ErrorAlert.js";
 
-export function TopLevelError({ error, resetErrorBoundary }: FallbackProps) {
-  // Call resetErrorBoundary() to reset the error boundary and retry the render.
-
+export function TopLevelError({ error }: FallbackProps) {
   return <ErrorAlert error={error} />;
 }

package/src/lib/hooks/index.ts

@@ -1,5 +1,16 @@
+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 };

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

@@ -1,7 +1,7 @@
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { act, renderHook, waitFor } from "@testing-library/react";
-import { type PropsWithChildren } from "react";
-import { type Location } from "react-router";
+import type { PropsWithChildren } from "react";
+import type { Location } from "react-router";
 import { assertType, describe, expect, it, vi } from "vitest";
 import { ZudokuProvider } from "../components/context/ZudokuProvider.js";
 import { ZudokuContext, type ZudokuEvents } from "../core/ZudokuContext.js";
@@ -116,11 +116,13 @@ describe("useEvent", () => {
   describe("types", () => {
     const { wrapper } = createTestContext();
 
-    it("infers event type when no callback is provided", () => {
-      const hook = renderHook(() => useEvent("location"), { wrapper });
-      assertType<Parameters<ZudokuEvents["location"]> | undefined>(
-        hook.result.current,
-      );
+    it("infers event type when no callback is provided", async () => {
+      await act(async () => {
+        const hook = renderHook(() => useEvent("location"), { wrapper });
+        assertType<Parameters<ZudokuEvents["location"]> | undefined>(
+          hook.result.current,
+        );
+      });
     });
 
     it("infers string type from pathname callback", () => {

package/src/lib/hooks/useHotkey.ts

@@ -0,0 +1,70 @@
+import { useEffect, useRef } from "react";
+import { isAppleDevice } from "../util/os.js";
+
+const keymap = {
+  other: {
+    alt: "Alt",
+    meta: "Ctrl",
+    ctrl: "Ctrl",
+    shift: "⇧",
+    option: "Alt",
+  },
+  apple: {
+    alt: "⌥",
+    meta: "⌘",
+    ctrl: "Ctrl",
+    shift: "⇧",
+    option: "⌥",
+  },
+};
+
+export const useHotkey = (hotkey: string, callback: () => void) => {
+  const hotkeySanitized = hotkey.toLowerCase().split("+");
+  const meta = hotkeySanitized.includes("meta");
+  const shift = hotkeySanitized.includes("shift");
+  const alt =
+    hotkeySanitized.includes("option") || hotkeySanitized.includes("alt");
+  const ctrl = hotkeySanitized.includes("ctrl");
+
+  const key = hotkey.split("+").pop();
+
+  const callbackRef = useRef(callback);
+
+  useEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+
+  useEffect(() => {
+    const handler = (event: KeyboardEvent) => {
+      if (
+        (event.code === `Key${key?.toUpperCase()}` ||
+          event.code.toLowerCase() === key?.toLowerCase()) &&
+        event.metaKey === meta &&
+        event.shiftKey === shift &&
+        event.altKey === alt &&
+        event.ctrlKey === ctrl
+      ) {
+        event.preventDefault();
+        callbackRef.current();
+      }
+    };
+
+    window.addEventListener("keydown", handler);
+    return () => {
+      window.removeEventListener("keydown", handler);
+    };
+  }, [key, meta, shift, alt, ctrl]);
+
+  return {
+    trigger: () => callbackRef.current(),
+    label: hotkeySanitized.map((key: string) =>
+      key === "meta" ||
+      key === "ctrl" ||
+      key === "alt" ||
+      key === "shift" ||
+      key === "option"
+        ? keymap[isAppleDevice() ? "apple" : "other"][key]
+        : key,
+    ),
+  };
+};

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

@@ -1,43 +1,51 @@
-import { GraphQLJSON } from "graphql-type-json";
 import { GraphQLScalarType } from "graphql/index.js";
-import { RecordAny } from "../../util/traverse.js";
+import { GraphQLJSON } from "graphql-type-json";
+import type { RecordAny } from "../../util/traverse.js";
 
 export const CIRCULAR_REF = "$[Circular Reference]";
 
+const OPENAPI_PROPS = new Set([
+  "properties",
+  "items",
+  "additionalProperties",
+  "allOf",
+  "anyOf",
+  "oneOf",
+]);
+
 const handleCircularRefs = (
+  // biome-ignore lint/suspicious/noExplicitAny: Allow any type
   obj: any,
-  visited = new Map<string, string[]>(),
+  visited = new WeakSet(),
+  refs = new WeakMap(),
   path: string[] = [],
+  // biome-ignore lint/suspicious/noExplicitAny: Allow any type
 ): any => {
-  if (obj === CIRCULAR_REF) return CIRCULAR_REF;
   if (obj === null || typeof obj !== "object") return obj;
 
-  const currentPath = path.join(".");
+  if (visited.has(obj)) {
+    const cached = refs.get(obj);
+    if (cached) return cached;
+    const circularProp = path.find((p) => !OPENAPI_PROPS.has(p)) || path[0];
 
-  if (obj.type === "object" && obj.properties) {
-    const schemaKey = Object.keys(obj.properties).sort().join("-");
-
-    if (visited.has(schemaKey)) {
-      const prevPaths = visited.get(schemaKey)!;
-      if (prevPaths.some((prev) => currentPath.startsWith(prev))) {
-        return CIRCULAR_REF;
-      }
-      visited.set(schemaKey, [...prevPaths, currentPath]);
-    } else {
-      visited.set(schemaKey, [currentPath]);
-    }
+    return [CIRCULAR_REF, circularProp].filter(Boolean).join(":");
   }
 
+  visited.add(obj);
+
   if (Array.isArray(obj)) {
-    return obj.map((item, index) =>
-      handleCircularRefs(item, visited, [...path, `${index}`]),
+    const result = obj.map((item, index) =>
+      handleCircularRefs(item, visited, refs, [...path, index.toString()]),
     );
+    refs.set(obj, result);
+    return result;
   }
 
   const result: RecordAny = {};
   for (const [key, value] of Object.entries(obj)) {
-    result[key] = handleCircularRefs(value, visited, [...path, key]);
+    result[key] = handleCircularRefs(value, visited, refs, [...path, key]);
   }
+  refs.set(obj, result);
   return result;
 };
 

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

@@ -1,4 +1,4 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
+// biome-ignore-all lint/suspicious/noExplicitAny: Allow any type
 import SchemaBuilder from "@pothos/core";
 import {
   type CountableSlugify,
@@ -111,18 +111,34 @@ export const getAllTags = (
     ),
   );
 
-  return [
+  const result = [
     // Keep root tags that are actually used in operations
     ...rootTags
       .filter((tag) => operationTags.has(tag.name))
       .map((tag) => ({ ...tag, slug: slugs[tag.name] })),
     // Add tags found in operations but not defined in root tags
-    ...[...operationTags]
+    ...Array.from(operationTags)
       .filter((tag) => !rootTags.some((rt) => rt.name === tag))
       .map((tag) => ({ name: tag, slug: slugs[tag] })),
     // Add untagged operations if there are any
     ...(hasUntaggedOperations ? [{ name: undefined, slug: undefined }] : []),
   ];
+
+  // Apply x-tagGroups ordering if present
+  const tagGroups = (schema as any)["x-tagGroups"] ?? [];
+
+  if (tagGroups.length === 0) return result;
+
+  const groupOrder = tagGroups.flatMap((group: any) => group.tags);
+  return result.sort((a, b) => {
+    if (!a.name || !b.name) return 0; // Keep untagged at end
+    const indexA = groupOrder.indexOf(a.name);
+    const indexB = groupOrder.indexOf(b.name);
+    if (indexA === -1 && indexB === -1) return 0; // Keep original order for ungrouped
+    if (indexA === -1) return 1; // Ungrouped after grouped
+    if (indexB === -1) return -1; // Grouped before ungrouped
+    return indexA - indexB;
+  });
 };
 
 export const getAllSlugs = (
@@ -176,11 +192,21 @@ export const getAllOperations = (
         ...operationParameters,
       ];
 
+      // servers follow the OpenAPI 3.0 resolution hierarchy:
+      // 1. Operation-level servers (highest precedence)
+      // 2. Path-level servers
+      // 3. Global servers (handled at query time, lowest precedence)
+      const pathServers = value.servers ?? [];
+      const operationServers = operation.servers ?? [];
+      const servers =
+        operationServers.length > 0 ? operationServers : pathServers;
+
       return {
         ...operation,
         method,
         path,
         parameters,
+        servers,
         tags: operation.tags ?? [],
       } satisfies GraphQLOperationObject;
     }),
@@ -424,6 +450,15 @@ const OperationItem = builder
         type: [ParameterItem],
         nullable: true,
       }),
+      servers: t.field({
+        type: [ServerItem],
+        resolve: (parent, _, ctx) => {
+          // Return operation/path-level servers if defined, otherwise fall back to global servers
+          return parent.servers && parent.servers.length > 0
+            ? parent.servers
+            : (ctx.schema.servers ?? []);
+        },
+      }),
       requestBody: t.field({
         type: RequestBodyObject,
         resolve: (parent) => ({
@@ -554,6 +589,7 @@ const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
       resolve: (root) =>
         Object.entries(root.paths ?? {}).map(([path, value]) => ({
           path,
+          // biome-ignore lint/style/noNonNullAssertion: value is guaranteed to be defined
           methods: Object.keys(value!) as typeof HttpMethods,
         })),
     }),

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

@@ -8,7 +8,7 @@ type CustomResolver = (ref: string) => Promise<JSONSchema | undefined>;
 
 const cache = new Map<JSONSchema, JSONSchema>();
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
+// biome-ignore lint/suspicious/noExplicitAny: Allow any type
 const isIndexableObject = (obj: any): obj is Record<string, any> =>
   obj !== null && typeof obj === "object";
 
@@ -18,6 +18,7 @@ export const dereference = async (
   resolvers: CustomResolver[] = [],
 ) => {
   if (cache.has(schema)) {
+    // biome-ignore lint/style/noNonNullAssertion: Cache is guaranteed to have a value
     return cache.get(schema)!;
   }
 

package/src/lib/oas/parser/dereference/resolveRef.ts

@@ -11,13 +11,13 @@ export const resolveLocalRef = (schema: JSONSchema, ref: string): unknown => {
   }
   const schemaCache = cache.get(schema);
 
-  if (schemaCache!.has(ref)) {
-    return schemaCache!.get(ref);
+  if (schemaCache?.has(ref)) {
+    return schemaCache.get(ref);
   }
 
   const path = ref.split("/").slice(1);
 
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  // biome-ignore lint/suspicious/noExplicitAny: Allow any type
   let current: any = schema;
   for (const segment of path) {
     if (!current || typeof current !== "object") {
@@ -27,6 +27,6 @@ export const resolveLocalRef = (schema: JSONSchema, ref: string): unknown => {
     current = current[segment] ?? null;
   }
 
-  schemaCache!.set(ref, current);
+  schemaCache?.set(ref, current);
   return current;
 };

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

@@ -1,5 +1,6 @@
 import { GraphQLError } from "graphql/error/index.js";
 import { OpenAPIV3, type OpenAPIV3_1 } from "openapi-types";
+import { flattenAllOfProcessor } from "../../util/flattenAllOf.js";
 import { dereference, type JSONSchema } from "./dereference/index.js";
 import { upgradeSchema } from "./upgrade/index.js";
 
@@ -42,7 +43,7 @@ const parseSchemaInput = async (
       }
     }
     if (schemaInput.includes("://")) {
-      let response;
+      let response: Response;
       try {
         response = await fetch(schemaInput, {
           cache: "force-cache",
@@ -82,11 +83,14 @@ const parseSchemaInput = async (
 
   if (typeof schemaInput === "object") return schemaInput as JSONSchema;
 
-  throw new GraphQLError("Unsupported schema input: " + schemaInput);
+  throw new GraphQLError(`Unsupported schema input: ${schemaInput}`);
 };
 
 /**
  * Validates, dereferences and upgrades the OpenAPI schema (to v3.1) if necessary.
+ *
+ * This only happens for URL schemas (or in standalone mode).
+ * File schemas are pre-processed by the SchemaManager
  */
 export const validate = async (schemaInput: unknown) => {
   const schema = await parseSchemaInput(schemaInput);
@@ -96,6 +100,13 @@ export const validate = async (schemaInput: unknown) => {
   }
 
   const dereferenced = await dereference(schema);
+  const upgraded = upgradeSchema(dereferenced);
 
-  return upgradeSchema(dereferenced);
+  const flattened = await flattenAllOfProcessor({
+    schema: upgraded,
+    file: "schema.json",
+    dereference: async (schema) => schema,
+  });
+
+  return flattened;
 };

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

@@ -1,4 +1,3 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
 import { type RecordAny, traverse } from "../../../util/traverse.js";
 import type { OpenAPIDocument } from "../index.js";
 /**
@@ -10,11 +9,11 @@ import type { OpenAPIDocument } from "../index.js";
 
 export const upgradeSchema = (schema: RecordAny): OpenAPIDocument => {
   if (schema.openapi?.startsWith("3.0")) {
-    schema.openapi = "3.1.0";
+    schema.openapi = "3.1.1";
   }
 
   schema = traverse(schema, (sub) => {
-    if (sub.type !== "undefined" && sub.nullable === true) {
+    if (typeof sub.type !== "undefined" && sub.nullable === true) {
       sub.type = ["null", sub.type];
       delete sub.nullable;
     }
@@ -40,26 +39,17 @@ export const upgradeSchema = (schema: RecordAny): OpenAPIDocument => {
     return sub;
   });
 
-  schema = traverse(schema, (sub) => {
-    // may be null or undefined
-    if (sub.example) {
-      const isExampleObject =
-        typeof sub.example === "object" &&
-        (sub.example.summary !== undefined ||
-          sub.example.description !== undefined ||
-          sub.example.value !== undefined ||
-          sub.example.externalValue !== undefined);
-
-      const exampleValue = isExampleObject
-        ? sub.example
-        : { value: sub.example };
-
-      if (!sub.examples) {
-        sub.examples = { default: exampleValue };
+  schema = traverse(schema, (sub, path) => {
+    if (sub.example !== undefined) {
+      // Arrays in schemas
+      if (isSchemaPath(path ?? [])) {
+        sub.examples = [sub.example];
       } else {
+        // Objects everywhere else
         sub.examples = {
-          default: exampleValue,
-          ...sub.examples,
+          default: {
+            value: sub.example,
+          },
         };
       }
       delete sub.example;
@@ -67,27 +57,67 @@ export const upgradeSchema = (schema: RecordAny): OpenAPIDocument => {
     return sub;
   });
 
-  schema = traverse(schema, (sub) => {
-    if (sub.type === "object" && sub.properties !== undefined) {
-      for (const [, value] of Object.entries(sub.properties)) {
-        const v = (value ?? {}) as RecordAny;
-        if (v.type === "string" && v.format === "binary") {
-          v.contentEncoding = "application/octet-stream";
-          delete v.format;
+  // Multipart file uploads with a binary file
+  schema = traverse(schema, (schema, path) => {
+    if (schema.type === "object" && schema.properties !== undefined) {
+      // Check if this is a multipart request body schema
+      const parentPath = path?.slice(0, -1);
+      const isMultipart = parentPath?.some((segment, index) => {
+        return (
+          segment === "content" && path?.[index + 1] === "multipart/form-data"
+        );
+      });
+
+      if (isMultipart) {
+        // Types
+        // biome-ignore lint/suspicious/noExplicitAny: Allow any type
+        const entries: [string, any][] = Object.entries(schema.properties);
+
+        for (const [, value] of entries) {
+          if (
+            typeof value === "object" &&
+            value.type === "string" &&
+            value.format === "binary"
+          ) {
+            value.contentMediaType = "application/octet-stream";
+            delete value.format;
+          }
         }
       }
     }
-    return sub;
+
+    return schema;
+  });
+
+  // Uploading a binary file in a POST request
+  schema = traverse(schema, (schema, path) => {
+    if (
+      path?.includes("content") &&
+      path.includes("application/octet-stream")
+    ) {
+      return {};
+    }
+
+    if (schema.type === "string" && schema.format === "binary") {
+      return {
+        type: "string",
+        contentMediaType: "application/octet-stream",
+      };
+    }
+
+    return schema;
   });
 
   schema = traverse(schema, (sub) => {
     if (sub.type === "string" && sub.format === "binary") {
+      // biome-ignore lint/suspicious/noExplicitAny: Allow any type
       return undefined as any;
     }
 
     return sub;
   });
 
+  // Uploading an image with base64 encoding
   schema = traverse(schema, (sub) => {
     if (sub.type === "string" && sub.format === "base64") {
       return {
@@ -99,5 +129,46 @@ export const upgradeSchema = (schema: RecordAny): OpenAPIDocument => {
     return sub;
   });
 
+  schema = traverse(schema, (schema, path) => {
+    if (schema.type === "string" && schema.format === "byte") {
+      const parentPath = path?.slice(0, -1);
+      const contentMediaType = parentPath?.find(
+        (_, index) => path?.[index - 1] === "content",
+      );
+
+      return {
+        type: "string",
+        contentEncoding: "base64",
+        contentMediaType,
+      };
+    }
+
+    return schema;
+  });
+
   return schema as OpenAPIDocument;
 };
+
+export function isSchemaPath(path: string[]): boolean {
+  const schemaLocations = [
+    ["components", "schemas"],
+    "properties",
+    "items",
+    "allOf",
+    "anyOf",
+    "oneOf",
+    "not",
+    "additionalProperties",
+  ];
+
+  return (
+    schemaLocations.some((location) => {
+      if (Array.isArray(location)) {
+        return location.every((segment, index) => path[index] === segment);
+      }
+      return path.includes(location);
+    }) ||
+    path.includes("schema") ||
+    path.some((segment) => segment.endsWith("Schema"))
+  );
+}