zudoku 0.0.0-ee328ec → 0.0.0-efc60ba6

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,10 +60,10 @@ type Metadata = Partial<{
   publisher: string;
 }>;
 
-type Page = Partial<{
+type Site = Partial<{
   dir?: "ltr" | "rtl";
   showPoweredBy?: boolean;
-  pageTitle?: string;
+  title?: string;
   logo?: {
     src: {
       light: string;
@@ -66,6 +71,7 @@ type Page = Partial<{
     };
     width?: string | number;
     alt?: string;
+    href?: string;
   };
   banner?: {
     message: ReactNode;
@@ -79,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;
 
@@ -161,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");
@@ -179,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/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} - ` : ""}

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

@@ -1,6 +1,6 @@
 import slugify from "@sindresorhus/slugify";
 import { matchPath } from "react-router";
-import type { SidebarItem } from "../../../config/validators/SidebarSchema.js";
+import type { NavigationItem } from "../../../config/validators/NavigationSchema.js";
 import type { AuthState } from "../../authentication/state.js";
 import type { ZudokuPlugin } from "../../core/plugins.js";
 import { joinUrl } from "../../util/joinUrl.js";
@@ -22,46 +22,46 @@ export type CatalogCategory = {
 };
 
 export type ApiCatalogPluginOptions = {
-  navigationId: string;
+  path: string;
   label: string;
   categories?: CatalogCategory[];
   items: ApiCatalogItem[];
-  filterCatalogItems?: filterCatalogItems;
+  filterCatalogItems?: FilterCatalogItemsFn;
 };
 
 export type CatalogContext<ProviderData = unknown> = {
   auth: AuthState<ProviderData>;
 };
 
-export type filterCatalogItems<ProviderData = unknown> = (
+export type FilterCatalogItemsFn<ProviderData = unknown> = (
   items: ApiCatalogItem[],
   { auth }: CatalogContext<ProviderData>,
 ) => ApiCatalogItem[];
 
 export const apiCatalogPlugin = ({
-  navigationId,
+  path,
   items,
   label,
   categories = [],
   filterCatalogItems,
 }: {
-  navigationId: string;
+  path: string;
   label: string;
   categories?: CatalogCategory[];
   items: ApiCatalogItem[];
-  filterCatalogItems?: filterCatalogItems;
+  filterCatalogItems?: FilterCatalogItemsFn;
 }): ZudokuPlugin => {
   const paths = Object.fromEntries(
     categories.flatMap((category) =>
       [undefined, ...category.tags].map((tag) => [
-        joinUrl(navigationId, tag ? getKey(category.label, tag) : undefined),
+        joinUrl(path, tag ? getKey(category.label, tag) : undefined),
         tag,
       ]),
     ),
   );
 
   return {
-    getSidebar: async (currentPath) => {
+    getNavigation: async (currentPath) => {
       const matches = Object.keys(paths).some((path) =>
         matchPath(path, currentPath),
       );
@@ -70,13 +70,13 @@ export const apiCatalogPlugin = ({
         return [];
       }
 
-      const sidebar: SidebarItem[] = categories.map((category) => ({
-        type: "category" as const,
+      const navigation: NavigationItem[] = categories.map((category) => ({
+        type: "category",
         label: category.label,
         collapsible: false,
         items: category.tags.map((tag) => ({
-          type: "doc" as const,
-          id: joinUrl(navigationId, getKey(category.label, tag)),
+          type: "link",
+          to: joinUrl(path, getKey(category.label, tag)),
           label: tag,
           badge: {
             label: String(
@@ -84,19 +84,19 @@ export const apiCatalogPlugin = ({
                 api.categories.find((c) => c.tags.includes(tag)),
               ).length,
             ),
-            color: "outline" as const,
+            color: "outline",
           },
         })),
       }));
 
-      sidebar.unshift({
-        type: "doc" as const,
-        id: joinUrl(navigationId),
+      navigation.unshift({
+        type: "link",
+        to: joinUrl(path),
         label: "Overview",
-        badge: { label: String(items.length), color: "outline" as const },
+        badge: { label: String(items.length), color: "outline" },
       });
 
-      return sidebar;
+      return navigation;
     },
     getRoutes: () =>
       Object.entries(paths).map(([path, tag]) => ({