zudoku 0.0.0-e097cbb → 0.0.0-e0ffac16

package/src/lib/core/ZudokuContext.ts

@@ -2,25 +2,30 @@ import type { QueryClient } from "@tanstack/react-query";
 import { createNanoEvents } from "nanoevents";
 import type { ReactNode } from "react";
 import type { Location } from "react-router";
-import type { z } from "zod";
-import type {
-  FooterSchema,
-  TopNavigationItem,
-} from "../../config/validators/common.js";
-import type { SidebarConfig } from "../../config/validators/SidebarSchema.js";
-import type { AuthenticationProvider } from "../authentication/authentication.js";
+import type { BundledTheme, HighlighterCore } from "shiki";
+import type { z } from "zod/v4";
+import type { Navigation } from "../../config/validators/NavigationSchema.js";
+import {
+  type ProtectedRoutesInput,
+  ProtectedRoutesSchema,
+} from "../../config/validators/ProtectedRoutesSchema.js";
+import type { FooterSchema } from "../../config/validators/validate.js";
+import type { AuthenticationPlugin } from "../authentication/authentication.js";
 import { type AuthState, useAuthState } from "../authentication/state.js";
 import type { ComponentsContextType } from "../components/context/ComponentsContext.js";
-import type { Slotlets } from "../components/SlotletProvider.js";
-import { joinPath } from "../util/joinPath.js";
+import type { SlotType } from "../components/context/SlotProvider.js";
+import { joinUrl } from "../util/joinUrl.js";
 import type { MdxComponentsType } from "../util/MdxComponents.js";
 import { objectEntries } from "../util/objectEntries.js";
 import {
   isApiIdentityPlugin,
+  isAuthenticationPlugin,
   isEventConsumerPlugin,
   isNavigationPlugin,
+  isProfileMenuPlugin,
   type NavigationPlugin,
   needsInitialization,
+  type ProfileNavigationItem,
   type ZudokuPlugin,
 } from "./plugins.js";
 
@@ -55,9 +60,10 @@ type Metadata = Partial<{
   publisher: string;
 }>;
 
-type Page = Partial<{
-  showPoweredBy: boolean;
-  pageTitle?: string;
+type Site = Partial<{
+  dir?: "ltr" | "rtl";
+  showPoweredBy?: boolean;
+  title?: string;
   logo?: {
     src: {
       light: string;
@@ -65,6 +71,7 @@ type Page = Partial<{
     };
     width?: string | number;
     alt?: string;
+    href?: string;
   };
   banner?: {
     message: ReactNode;
@@ -78,40 +85,61 @@ export type ZudokuContextOptions = {
   basePath?: string;
   canonicalUrlOrigin?: string;
   metadata?: Metadata;
-  page?: Page;
-  authentication?: AuthenticationProvider;
-  topNavigation?: TopNavigationItem[];
-  sidebars?: SidebarConfig;
+  site?: Site;
+  authentication?: AuthenticationPlugin;
+  navigation?: Navigation;
   plugins?: ZudokuPlugin[];
-  slotlets?: Slotlets;
+  slots?: Record<string, SlotType>;
+  /**
+   * @deprecated Use `slots` instead
+   */
+  UNSAFE_slotlets?: Record<string, SlotType>;
   mdx?: {
     components?: MdxComponentsType;
   };
   overrides?: ComponentsContextType;
-  protectedRoutes?: string[];
+  protectedRoutes?: ProtectedRoutesInput;
+  syntaxHighlighting?: {
+    highlighter: HighlighterCore;
+    themes?: { light: BundledTheme; dark: BundledTheme };
+  };
 };
 
 export class ZudokuContext {
   public plugins: NonNullable<ZudokuContextOptions["plugins"]>;
-  public sidebars: SidebarConfig;
-  public topNavigation: NonNullable<ZudokuContextOptions["topNavigation"]>;
+  public navigation: Navigation;
   public meta: ZudokuContextOptions["metadata"];
-  public page: ZudokuContextOptions["page"];
-  public authentication?: ZudokuContextOptions["authentication"];
+  public site: ZudokuContextOptions["site"];
+  public readonly authentication?: ZudokuContextOptions["authentication"];
+  public readonly queryClient: QueryClient;
+  public readonly options: ZudokuContextOptions;
   private readonly navigationPlugins: NavigationPlugin[];
   private emitter = createNanoEvents<ZudokuEvents>();
 
-  constructor(
-    public readonly options: ZudokuContextOptions,
-    public readonly queryClient: QueryClient,
-  ) {
+  constructor(options: ZudokuContextOptions, queryClient: QueryClient) {
+    const pluginProtectedRoutes = Object.fromEntries(
+      (options.plugins ?? []).flatMap((plugin) => {
+        if (!isNavigationPlugin(plugin)) return [];
+        const routes = plugin.getProtectedRoutes?.();
+        if (!routes) return [];
+
+        return Object.entries(ProtectedRoutesSchema.parse(routes) ?? {});
+      }),
+    );
+
+    const protectedRoutes = {
+      ...pluginProtectedRoutes,
+      ...ProtectedRoutesSchema.parse(options.protectedRoutes),
+    };
+
+    this.queryClient = queryClient;
+    this.options = { ...options, protectedRoutes };
     this.plugins = options.plugins ?? [];
-    this.topNavigation = options.topNavigation ?? [];
-    this.sidebars = options.sidebars ?? {};
+    this.navigation = options.navigation ?? [];
     this.navigationPlugins = this.plugins.filter(isNavigationPlugin);
-    this.authentication = options.authentication;
+    this.authentication = this.plugins.find(isAuthenticationPlugin);
     this.meta = options.metadata;
-    this.page = options.page;
+    this.site = options.site;
     this.plugins.forEach((plugin) => {
       if (!isEventConsumerPlugin(plugin)) return;
 
@@ -160,16 +188,26 @@ export class ZudokuContext {
     return this.emitter.emit(event, ...data);
   };
 
-  getPluginSidebar = async (path: string) => {
+  getPluginNavigation = async (path: string) => {
     const navigations = await Promise.all(
       this.navigationPlugins.map((plugin) =>
-        plugin.getSidebar?.(joinPath(path), this),
+        plugin.getNavigation?.(joinUrl(path), this),
       ),
     );
 
     return navigations.flatMap((nav) => nav ?? []);
   };
 
+  getProfileMenuItems = () => {
+    const accountItems = this.plugins
+      .filter((p) => isProfileMenuPlugin(p))
+      .flatMap((p) => p.getProfileMenuItems(this))
+      .sort(sortByCategory(["top", "middle", "bottom"]))
+      .sort((i) => i.weight ?? 0);
+
+    return accountItems;
+  };
+
   signRequest = async (request: Request) => {
     if (!this.authentication) {
       throw new Error("No authentication provider configured");
@@ -178,3 +216,12 @@ export class ZudokuContext {
     return await this.authentication.signRequest(request);
   };
 }
+
+const sortByCategory =
+  (categories: string[]) =>
+  (a: ProfileNavigationItem, b: ProfileNavigationItem) => {
+    const aIndex = categories.indexOf(a.category ?? "middle");
+    const bIndex = categories.indexOf(b.category ?? "middle");
+
+    return aIndex - bIndex;
+  };

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/errors/ErrorAlert.tsx

@@ -2,8 +2,7 @@
 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 +18,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/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

@@ -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 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 = (
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   obj: any,
-  visited = new Map<string, string[]>(),
+  visited = new WeakSet(),
+  refs = new WeakMap(),
   path: string[] = [],
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
 ): any => {
-  if (obj === CIRCULAR_REF) return CIRCULAR_REF;
   if (obj === null || typeof obj !== "object") return obj;
 
-  const currentPath = path.join(".");
-
-  if (obj.type === "object" && obj.properties) {
-    const schemaKey = Object.keys(obj.properties).sort().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 (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/parser/index.ts

@@ -1,3 +1,4 @@
+import { merge as mergeAllOf } from "allof-merge";
 import { GraphQLError } from "graphql/error/index.js";
 import { OpenAPIV3, type OpenAPIV3_1 } from "openapi-types";
 import { dereference, type JSONSchema } from "./dereference/index.js";
@@ -87,6 +88,9 @@ const parseSchemaInput = async (
 
 /**
  * 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);
@@ -97,6 +101,7 @@ export const validate = async (schemaInput: unknown) => {
 
   const dereferenced = await dereference(schema);
   const upgraded = upgradeSchema(dereferenced);
+  const merged = mergeAllOf(upgraded) as OpenAPIDocument;
 
-  return upgraded;
+  return merged;
 };

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

@@ -10,7 +10,7 @@ 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) => {
@@ -40,26 +40,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,17 +58,54 @@ 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
+        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) => {
@@ -88,6 +116,7 @@ export const upgradeSchema = (schema: RecordAny): OpenAPIDocument => {
     return sub;
   });
 
+  // Uploading an image with base64 encoding
   schema = traverse(schema, (sub) => {
     if (sub.type === "string" && sub.format === "base64") {
       return {
@@ -99,5 +128,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"))
+  );
+}

package/src/lib/plugins/api-catalog/Catalog.tsx

@@ -13,7 +13,7 @@ export const Catalog = ({
   filterCatalogItems = (items) => items,
   label = "API Library",
   categoryLabel,
-}: Omit<ApiCatalogPluginOptions, "navigationId"> & {
+}: Omit<ApiCatalogPluginOptions, "path"> & {
   categoryLabel?: string;
 }) => {
   const auth = useAuthState();
@@ -29,7 +29,7 @@ export const Catalog = ({
   const dataSet = activeCategory ? { "data-pagefind-ignore": "all" } : {};
 
   return (
-    <section className="pt-[--padding-content-top]" {...dataSet}>
+    <section className="pt-(--padding-content-top)" {...dataSet}>
       <Helmet>
         <title>
           {categoryLabel ? `${categoryLabel} - ` : ""}