zudoku 0.0.0-ec30b50 → 0.0.0-edd80c1

package/src/lib/core/ZudokuContext.ts

@@ -1,21 +1,42 @@
-import { ReactNode } from "react";
-import { TopNavigationItem } from "../../config/validators/common.js";
+import type { QueryClient } from "@tanstack/react-query";
+import { createNanoEvents } from "nanoevents";
+import type { ReactNode } from "react";
+import type { Location } from "react-router";
+import type { BundledTheme, HighlighterCore } from "shiki";
+import type { z } from "zod";
 import type { SidebarConfig } from "../../config/validators/SidebarSchema.js";
-import { type AuthenticationProvider } from "../authentication/authentication.js";
+import type {
+  FooterSchema,
+  TopNavigationItem,
+} 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 { Slotlets } from "../components/SlotletProvider.js";
+import type { SlotType } from "../components/context/SlotProvider.js";
 import { joinPath } from "../util/joinPath.js";
 import type { MdxComponentsType } from "../util/MdxComponents.js";
+import { objectEntries } from "../util/objectEntries.js";
 import {
   isApiIdentityPlugin,
+  isAuthenticationPlugin,
+  isEventConsumerPlugin,
   isNavigationPlugin,
   type NavigationPlugin,
   needsInitialization,
   type ZudokuPlugin,
 } from "./plugins.js";
 
+export interface ZudokuEvents {
+  location: (event: { from?: Location; to: Location }) => void;
+  auth: (auth: { prev: AuthState; next: AuthState }) => void;
+}
+
 export interface ApiIdentity {
-  authorizeRequest: (request: Request) => Request;
+  authorizeRequest: (request: Request) => Promise<Request> | Request;
+  authorizationFields?: {
+    headers?: string[];
+    queryParams?: string[];
+  };
   label: string;
   id: string;
 }
@@ -37,13 +58,15 @@ type Metadata = Partial<{
 }>;
 
 type Page = Partial<{
+  dir?: "ltr" | "rtl";
+  showPoweredBy?: boolean;
   pageTitle?: string;
   logo?: {
     src: {
       light: string;
       dark: string;
     };
-    width?: string;
+    width?: string | number;
     alt?: string;
   };
   banner?: {
@@ -51,21 +74,32 @@ type Page = Partial<{
     color?: "note" | "tip" | "info" | "caution" | "danger" | (string & {});
     dismissible?: boolean;
   };
+  footer?: z.infer<typeof FooterSchema>;
 }>;
 
 export type ZudokuContextOptions = {
+  basePath?: string;
+  canonicalUrlOrigin?: string;
   metadata?: Metadata;
   page?: Page;
-  authentication?: AuthenticationProvider;
+  authentication?: AuthenticationPlugin;
   topNavigation?: TopNavigationItem[];
   sidebars?: SidebarConfig;
   plugins?: ZudokuPlugin[];
-  slotlets?: Slotlets;
+  slots?: Record<string, SlotType>;
+  /**
+   * @deprecated Use `slots` instead
+   */
+  UNSAFE_slotlets?: Record<string, SlotType>;
   mdx?: {
     components?: MdxComponentsType;
   };
   overrides?: ComponentsContextType;
   protectedRoutes?: string[];
+  syntaxHighlighting?: {
+    highlighter: HighlighterCore;
+    themes?: { light: BundledTheme; dark: BundledTheme };
+  };
 };
 
 export class ZudokuContext {
@@ -74,17 +108,42 @@ export class ZudokuContext {
   public topNavigation: NonNullable<ZudokuContextOptions["topNavigation"]>;
   public meta: ZudokuContextOptions["metadata"];
   public page: ZudokuContextOptions["page"];
-  public authentication?: ZudokuContextOptions["authentication"];
+  public readonly authentication?: ZudokuContextOptions["authentication"];
+  public readonly queryClient: QueryClient;
+  public readonly options: ZudokuContextOptions;
   private readonly navigationPlugins: NavigationPlugin[];
+  private emitter = createNanoEvents<ZudokuEvents>();
+
+  constructor(options: ZudokuContextOptions, queryClient: QueryClient) {
+    const protectedRoutes = (options.protectedRoutes ?? []).concat(
+      options.plugins?.flatMap((plugin) =>
+        isNavigationPlugin(plugin) ? (plugin.getProtectedRoutes?.() ?? []) : [],
+      ) ?? [],
+    );
 
-  constructor(public readonly options: ZudokuContextOptions) {
+    this.queryClient = queryClient;
+    this.options = { ...options, protectedRoutes };
     this.plugins = options.plugins ?? [];
     this.topNavigation = options.topNavigation ?? [];
     this.sidebars = options.sidebars ?? {};
     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.plugins.forEach((plugin) => {
+      if (!isEventConsumerPlugin(plugin)) return;
+
+      objectEntries(plugin.events).forEach(([event, handler]) => {
+        this.emitter.on(event, handler!);
+      });
+    });
+
+    useAuthState.subscribe((state, prevState) => {
+      this.emitEvent("auth", {
+        prev: prevState,
+        next: state,
+      });
+    });
   }
 
   initialize = async (): Promise<void> => {
@@ -105,10 +164,24 @@ export class ZudokuContext {
     return keys.flat();
   };
 
+  addEventListener<E extends keyof ZudokuEvents>(
+    event: E,
+    callback: ZudokuEvents[E],
+  ) {
+    return this.emitter.on(event, callback);
+  }
+
+  emitEvent = <E extends keyof ZudokuEvents>(
+    event: E,
+    ...data: Parameters<ZudokuEvents[E]>
+  ) => {
+    return this.emitter.emit(event, ...data);
+  };
+
   getPluginSidebar = async (path: string) => {
     const navigations = await Promise.all(
       this.navigationPlugins.map((plugin) =>
-        plugin.getSidebar?.(joinPath(path)),
+        plugin.getSidebar?.(joinPath(path), this),
       ),
     );
 
@@ -120,10 +193,6 @@ export class ZudokuContext {
       throw new Error("No authentication provider configured");
     }
 
-    const accessToken = await this.authentication.getAccessToken();
-
-    request.headers.set("Authorization", `Bearer ${accessToken}`);
-
-    return request;
+    return await this.authentication.signRequest(request);
   };
 }

package/src/lib/core/plugins.ts

@@ -1,24 +1,40 @@
 import type { LucideIcon } from "lucide-react";
-import { type ReactElement } from "react";
-import { type RouteObject } from "react-router";
+import type { ReactElement } from "react";
+import type { Location, RouteObject } from "react-router";
 import type { Sidebar } from "../../config/validators/SidebarSchema.js";
-import { MdxComponentsType } from "../util/MdxComponents.js";
-import { ZudokuContext, type ApiIdentity } from "./ZudokuContext.js";
+import type { AuthenticationPlugin } from "../authentication/authentication.js";
+import type { MdxComponentsType } from "../util/MdxComponents.js";
+import type {
+  ApiIdentity,
+  ZudokuContext,
+  ZudokuEvents,
+} from "./ZudokuContext.js";
 
 export type ZudokuPlugin =
   | CommonPlugin
   | ProfileMenuPlugin
   | NavigationPlugin
   | ApiIdentityPlugin
-  | SearchProviderPlugin;
+  | SearchProviderPlugin
+  | EventConsumerPlugin
+  | AuthenticationPlugin;
 
-export type { RouteObject };
+export type { AuthenticationPlugin, RouteObject };
 
 export interface NavigationPlugin {
   getRoutes: () => RouteObject[];
-  getSidebar?: (path: string) => Promise<Sidebar>;
+  getSidebar?: (path: string, context: ZudokuContext) => Promise<Sidebar>;
+  getProtectedRoutes?: () => string[];
 }
 
+export const createApiIdentityPlugin = (
+  plugin: ApiIdentityPlugin,
+): ApiIdentityPlugin => plugin;
+
+export const createProfileMenuPlugin = (
+  plugin: ProfileMenuPlugin,
+): ProfileMenuPlugin => plugin;
+
 export interface ApiIdentityPlugin {
   getIdentities: (context: ZudokuContext) => Promise<ApiIdentity[]>;
 }
@@ -47,10 +63,19 @@ export interface CommonPlugin {
   initialize?: (
     context: ZudokuContext,
   ) => Promise<void | boolean> | void | boolean;
-  getHead?: () => ReactElement | undefined;
+  getHead?: ({ location }: { location: Location }) => ReactElement | undefined;
   getMdxComponents?: () => MdxComponentsType;
 }
 
+export type EventConsumerPlugin<Event extends ZudokuEvents = ZudokuEvents> = {
+  events: { [K in keyof Event]?: Event[K] };
+};
+
+export const isEventConsumerPlugin = (
+  obj: ZudokuPlugin,
+): obj is EventConsumerPlugin =>
+  "events" in obj && typeof obj.events === "object";
+
 export const isProfileMenuPlugin = (
   obj: ZudokuPlugin,
 ): obj is ProfileMenuPlugin =>
@@ -61,6 +86,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

@@ -1,5 +1,9 @@
 // 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 { ZudokuError } from "../util/invariant.js";
 
 export function ErrorAlert({ error }: { error: unknown }) {
@@ -12,24 +16,27 @@ export function ErrorAlert({ error }: { error: unknown }) {
   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 (
-    <div className="flex h-screen max-h-[calc(100vh-var(--header-height))] min-h-full items-center justify-center bg-primary-background px-4 py-16 lg:px-8">
-      <div className="mx-auto max-w-[85%] sm:max-w-[50%]">
-        <h1 className="text-4xl font-bold tracking-tight text-h1-text sm:text-5xl">
-          {title}
-        </h1>
-        <p className="mt-5 text-h1-text">{message}</p>
-        {hint && <DeveloperHint className="mb-4">{hint}</DeveloperHint>}
-        {cause instanceof Error ? (
-          <pre className="mt-5 max-h-[400px] w-full overflow-scroll rounded-md border border-input-border bg-input-background p-3 text-property-name-text text-red-700">
-            {cause.stack}
-          </pre>
-        ) : stack ? (
-          <pre className="mt-5 max-h-[400px] w-full overflow-scroll rounded-md border border-input-border bg-input-background p-3 text-property-name-text text-red-700">
-            {stack}
-          </pre>
-        ) : null}
-      </div>
+    <div
+      className={cn(
+        ProseClasses,
+        "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="js"
+            code={stringError}
+          />
+        </div>
+      )}
     </div>
   );
 }

package/src/lib/hooks/index.ts

@@ -0,0 +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

@@ -0,0 +1,149 @@
+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 { assertType, describe, expect, it, vi } from "vitest";
+import { ZudokuProvider } from "../components/context/ZudokuProvider.js";
+import { ZudokuContext, type ZudokuEvents } from "../core/ZudokuContext.js";
+import { useEvent } from "./useEvent.js";
+
+/**
+ * @vitest-environment happy-dom
+ */
+
+const createTestContext = () => {
+  const queryClient = new QueryClient();
+  const context = new ZudokuContext({}, queryClient);
+  const wrapper = ({ children }: PropsWithChildren) => (
+    <QueryClientProvider client={queryClient}>
+      <ZudokuProvider context={context}>{children}</ZudokuProvider>
+    </QueryClientProvider>
+  );
+
+  return { context, wrapper };
+};
+
+const locationData = {
+  pathname: "/test",
+  hash: "",
+  search: "",
+  key: "",
+  state: {},
+} satisfies Location;
+
+describe("useEvent", () => {
+  it("returns latest event data without callback", async () => {
+    const { context, wrapper } = createTestContext();
+    const { result } = renderHook(() => useEvent("location"), { wrapper });
+
+    await act(() => Promise.resolve());
+    await act(async () => {
+      context.emitEvent("location", { to: locationData });
+    });
+
+    expect(result.current).toEqual([{ to: locationData }]);
+  });
+
+  it("transforms event data with callback", async () => {
+    const { context, wrapper } = createTestContext();
+    const { result } = renderHook(
+      () => useEvent("location", ({ to }) => to.pathname),
+      { wrapper },
+    );
+
+    await act(() => Promise.resolve());
+    await act(async () => {
+      context.emitEvent("location", { to: locationData });
+    });
+
+    await waitFor(() => expect(result.current).toEqual("/test"));
+  });
+
+  it("handles side effects without return value", async () => {
+    const { context, wrapper } = createTestContext();
+    const sideEffect = vi.fn();
+
+    const { result } = renderHook(
+      () =>
+        useEvent("location", (event) => {
+          sideEffect(event);
+        }),
+      { wrapper },
+    );
+
+    await act(() => Promise.resolve());
+    await act(async () => {
+      context.emitEvent("location", { to: locationData });
+    });
+
+    expect(result.current).toBeUndefined();
+    expect(sideEffect).toHaveBeenCalledWith({ to: locationData });
+    expect(sideEffect).toHaveBeenCalledTimes(1);
+  });
+
+  it("removes event listener on cleanup", async () => {
+    const { context, wrapper } = createTestContext();
+    const sideEffect = vi.fn();
+
+    const { unmount } = renderHook(
+      () =>
+        useEvent("location", (event) => {
+          sideEffect(event);
+        }),
+      { wrapper },
+    );
+
+    await act(() => Promise.resolve());
+
+    // First event emission
+    await act(async () => {
+      context.emitEvent("location", { to: locationData });
+    });
+    expect(sideEffect).toHaveBeenCalledTimes(1);
+
+    // Unmount the hook
+    unmount();
+
+    // Second event emission after unmount
+    await act(async () => {
+      context.emitEvent("location", { to: locationData });
+    });
+
+    // The callback should not have been called again
+    expect(sideEffect).toHaveBeenCalledTimes(1);
+  });
+
+  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 string type from pathname callback", () => {
+      const hook = renderHook(
+        () => useEvent("location", ({ to }) => to.pathname),
+        { wrapper },
+      );
+      assertType<string>(hook.result.current);
+    });
+
+    it("infers object type from object callback", () => {
+      const hook = renderHook(
+        () => useEvent("location", ({ to }) => ({ query: to.search })),
+        { wrapper },
+      );
+      assertType<{ query: string }>(hook.result.current);
+    });
+
+    it("infers void type from empty callback", () => {
+      const hook = renderHook(() => useEvent("location", () => {}), {
+        wrapper,
+      });
+      assertType<void>(hook.result.current);
+    });
+  });
+});

package/src/lib/hooks/useEvent.ts

@@ -0,0 +1,41 @@
+import { useEffect, useState } from "react";
+import { useZudoku } from "../components/context/ZudokuContext.js";
+import type { ZudokuEvents } from "../core/ZudokuContext.js";
+
+type EventParameters<Event extends keyof ZudokuEvents> = Parameters<
+  ZudokuEvents[Event]
+>;
+
+/**
+ * Hook to subscribe to Zudoku events with automatic cleanup
+ * @param event The event to subscribe to
+ * @param callback Optional callback to be called when the event is emitted
+ * @returns The latest event data if no callback is provided, or the callback's return value if it returns something
+ */
+export function useEvent<E extends keyof ZudokuEvents>(
+  event: E,
+): EventParameters<E>;
+export function useEvent<E extends keyof ZudokuEvents, R>(
+  event: E,
+  callback: (...args: EventParameters<E>) => R,
+): R;
+export function useEvent<E extends keyof ZudokuEvents, R>(
+  event: E,
+  callback?: (...args: EventParameters<E>) => R,
+) {
+  const zudoku = useZudoku();
+  const [latestData, setLatestData] = useState<R | EventParameters<E>>();
+
+  useEffect(() => {
+    return zudoku.addEventListener(event, ((...args: EventParameters<E>) => {
+      if (callback) {
+        const result = callback(...args);
+        setLatestData(result);
+      } else {
+        setLatestData(args);
+      }
+    }) as ZudokuEvents[E]);
+  }, [zudoku, event, callback]);
+
+  return latestData;
+}

package/src/lib/icons.ts

@@ -1 +1,2 @@
 export * from "lucide-react";
+export * from "./MissingIcon.js";

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;
 };