zudoku 0.0.0-ff3bc72 → 0.0.0-zuplo-api-keys.534c6f8

package/src/lib/core/ZudokuContext.ts

@@ -0,0 +1,198 @@
+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 {
+  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 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) => Promise<Request> | Request;
+  authorizationFields?: {
+    headers?: string[];
+    queryParams?: string[];
+  };
+  label: string;
+  id: string;
+}
+
+export type ApiKeyCache = "api-keys";
+
+type Metadata = Partial<{
+  title: string;
+  description: string;
+  logo: string;
+  favicon: string;
+  generator: string;
+  applicationName: string;
+  referrer: string;
+  keywords: string[];
+  authors: string[];
+  creator: string;
+  publisher: string;
+}>;
+
+type Page = Partial<{
+  dir?: "ltr" | "rtl";
+  showPoweredBy?: boolean;
+  pageTitle?: string;
+  logo?: {
+    src: {
+      light: string;
+      dark: string;
+    };
+    width?: string | number;
+    alt?: string;
+  };
+  banner?: {
+    message: ReactNode;
+    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?: AuthenticationPlugin;
+  topNavigation?: TopNavigationItem[];
+  sidebars?: SidebarConfig;
+  plugins?: ZudokuPlugin[];
+  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 {
+  public plugins: NonNullable<ZudokuContextOptions["plugins"]>;
+  public sidebars: SidebarConfig;
+  public topNavigation: NonNullable<ZudokuContextOptions["topNavigation"]>;
+  public meta: ZudokuContextOptions["metadata"];
+  public page: ZudokuContextOptions["page"];
+  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?.() ?? []) : [],
+      ) ?? [],
+    );
+
+    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 = 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> => {
+    await Promise.all(
+      this.plugins
+        .filter(needsInitialization)
+        .map((plugin) => plugin.initialize?.(this)),
+    );
+  };
+
+  getApiIdentities = async () => {
+    const keys = await Promise.all(
+      this.plugins
+        .filter(isApiIdentityPlugin)
+        .map((plugin) => plugin.getIdentities(this)),
+    );
+
+    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), this),
+      ),
+    );
+
+    return navigations.flatMap((nav) => nav ?? []);
+  };
+
+  signRequest = async (request: Request) => {
+    if (!this.authentication) {
+      throw new Error("No authentication provider configured");
+    }
+
+    return await this.authentication.signRequest(request);
+  };
+}

package/src/lib/core/plugins.ts

@@ -1,23 +1,42 @@
-import { type ReactElement } from "react";
-import { type RouteObject } from "react-router-dom";
+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 { MdxComponentsType } from "../util/MdxComponents.js";
-import { DevPortalContext, type ApiIdentity } from "./DevPortalContext.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 DevPortalPlugin =
+export type ZudokuPlugin =
   | CommonPlugin
   | ProfileMenuPlugin
   | NavigationPlugin
   | ApiIdentityPlugin
-  | SearchProviderPlugin;
+  | SearchProviderPlugin
+  | EventConsumerPlugin
+  | AuthenticationPlugin;
+
+export type { 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: DevPortalContext) => Promise<ApiIdentity[]>;
+  getIdentities: (context: ZudokuContext) => Promise<ApiIdentity[]>;
 }
 
 export interface SearchProviderPlugin {
@@ -28,52 +47,65 @@ export interface SearchProviderPlugin {
 }
 
 export interface ProfileMenuPlugin {
-  getProfileMenuItems: (context: DevPortalContext) => ProfileNavigationItem[];
+  getProfileMenuItems: (context: ZudokuContext) => ProfileNavigationItem[];
 }
 
 export type ProfileNavigationItem = {
   label: string;
   path?: string;
+  weight?: number;
+  category?: "top" | "middle" | "bottom";
   children?: ProfileNavigationItem[];
+  icon?: LucideIcon;
 };
 
 export interface CommonPlugin {
   initialize?: (
-    context: DevPortalContext,
+    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: DevPortalPlugin,
+  obj: ZudokuPlugin,
 ): obj is ProfileMenuPlugin =>
   "getProfileMenuItems" in obj && typeof obj.getProfileMenuItems === "function";
 
 export const isNavigationPlugin = (
-  obj: DevPortalPlugin,
+  obj: ZudokuPlugin,
 ): 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: DevPortalPlugin,
+  obj: ZudokuPlugin,
 ): obj is SearchProviderPlugin =>
   "renderSearch" in obj && typeof obj.renderSearch === "function";
 
-export const needsInitialization = (
-  obj: DevPortalPlugin,
-): obj is CommonPlugin =>
+export const needsInitialization = (obj: ZudokuPlugin): obj is CommonPlugin =>
   "initialize" in obj && typeof obj.initialize === "function";
 
-export const hasHead = (obj: DevPortalPlugin): obj is CommonPlugin =>
+export const hasHead = (obj: ZudokuPlugin): obj is CommonPlugin =>
   "getHead" in obj && typeof obj.getHead === "function";
 
-export const isMdxProviderPlugin = (
-  obj: DevPortalPlugin,
-): obj is CommonPlugin =>
+export const isMdxProviderPlugin = (obj: ZudokuPlugin): obj is CommonPlugin =>
   "getMdxComponents" in obj && typeof obj.getMdxComponents === "function";
 
 export const isApiIdentityPlugin = (
-  obj: DevPortalPlugin,
+  obj: ZudokuPlugin,
 ): obj is ApiIdentityPlugin =>
   "getIdentities" in obj && typeof obj.getIdentities === "function";

package/src/lib/errors/ErrorAlert.tsx

@@ -1,21 +1,42 @@
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export function ErrorAlert({ error }: { error: any }) {
-  const message = error?.message ?? "Something went wrong";
-  const stack = error?.stack;
+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 }) {
+  const message =
+    error instanceof Error ? error.message : "Something went wrong";
+
+  const hint = error instanceof ZudokuError ? error.developerHint : undefined;
+  const title =
+    error instanceof ZudokuError ? error.title : "Something went wrong";
+  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-screen 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">
-          Something went wrong
-        </h1>
-        <p className="mt-5 text-h1-text">{message}</p>
-        {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/errors/RouterError.tsx

@@ -1,4 +1,4 @@
-import { isRouteErrorResponse, useRouteError } from "react-router-dom";
+import { isRouteErrorResponse, useRouteError } from "react-router";
 import { NotFoundPage } from "../components/NotFoundPage.js";
 import { ErrorAlert } from "./ErrorAlert.js";
 

package/src/lib/hooks/index.ts

@@ -0,0 +1,5 @@
+import { useTheme as useThemeImport } from "next-themes";
+import { useEvent as useEventImport } from "./useEvent.js";
+
+export const useEvent = /*@__PURE__*/ useEventImport;
+export const useTheme = /*@__PURE__*/ useThemeImport;

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

@@ -0,0 +1,58 @@
+import { GraphQLJSON } from "graphql-type-json";
+import { GraphQLScalarType } from "graphql/index.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 WeakSet(),
+  refs = new WeakMap(),
+  path: string[] = [],
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+): any => {
+  if (obj === null || typeof obj !== "object") return obj;
+
+  if (visited.has(obj)) {
+    const cached = refs.get(obj);
+    if (cached) return cached;
+    const circularProp = path.find((p) => !OPENAPI_PROPS.has(p)) || path[0];
+
+    return [CIRCULAR_REF, circularProp].filter(Boolean).join(":");
+  }
+
+  visited.add(obj);
+
+  if (Array.isArray(obj)) {
+    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, refs, [...path, key]);
+  }
+  refs.set(obj, result);
+  return result;
+};
+
+export const GraphQLJSONSchema = new GraphQLScalarType({
+  ...GraphQLJSON,
+  name: "JSONSchema",
+  description: "OpenAPI schema scalar type that handles circular references",
+  serialize: (value: unknown) =>
+    GraphQLJSON.serialize(handleCircularRefs(value)),
+});