zudoku 0.0.0-fd8f8ad → 0.0.0-fdf886de

package/src/lib/core/ZudokuContext.ts

@@ -1,21 +1,45 @@
-import { ReactNode } from "react";
-import type { SidebarConfig } from "../../config/validators/SidebarSchema.js";
-import { TopNavigationItem } from "../../config/validators/validate.js";
-import { type AuthenticationProvider } from "../authentication/authentication.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/v4";
+import type { Navigation } from "../../config/validators/NavigationSchema.js";
+import type {
+  CallbackContext,
+  ProtectedRoutesInput,
+} 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 { 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";
 
+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;
 }
@@ -24,6 +48,7 @@ export type ApiKeyCache = "api-keys";
 
 type Metadata = Partial<{
   title: string;
+  defaultTitle?: string;
   description: string;
   logo: string;
   favicon: string;
@@ -36,54 +61,117 @@ type Metadata = Partial<{
   publisher: string;
 }>;
 
-type Page = Partial<{
-  pageTitle?: string;
+type Site = Partial<{
+  dir?: "ltr" | "rtl";
+  showPoweredBy?: boolean;
+  title?: string;
   logo?: {
     src: {
       light: string;
       dark: string;
     };
-    width?: string;
+    width?: string | number;
     alt?: string;
+    href?: 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?: 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?: ProtectedRoutesInput;
+  syntaxHighlighting?: {
+    highlighter: HighlighterCore;
+    themes?: { light: BundledTheme; dark: BundledTheme };
+  };
+};
+
+export const transformProtectedRoutes = (
+  val: ProtectedRoutesInput,
+): Record<string, (c: CallbackContext) => boolean> | undefined => {
+  if (!val) return undefined;
+
+  if (Array.isArray(val)) {
+    return Object.fromEntries(
+      val.map((route) => [
+        route,
+        (c: CallbackContext) => c.auth.isAuthenticated,
+      ]),
+    );
+  }
+
+  return val;
 };
 
 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"];
-  private navigationPlugins: NavigationPlugin[];
-
-  constructor(config: ZudokuContextOptions) {
-    this.plugins = config.plugins ?? [];
-    this.topNavigation = config.topNavigation ?? [];
-    this.sidebars = config.sidebars ?? {};
+  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(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(transformProtectedRoutes(routes) ?? {});
+      }),
+    );
+
+    const protectedRoutes = {
+      ...pluginProtectedRoutes,
+      ...transformProtectedRoutes(options.protectedRoutes),
+    };
+
+    this.queryClient = queryClient;
+    this.options = { ...options, protectedRoutes };
+    this.plugins = options.plugins ?? [];
+    this.navigation = options.navigation ?? [];
     this.navigationPlugins = this.plugins.filter(isNavigationPlugin);
-    this.authentication = config.authentication;
-    this.meta = config.metadata;
-    this.page = config.page;
+    this.authentication = this.plugins.find(isAuthenticationPlugin);
+    this.meta = options.metadata;
+    this.site = options.site;
+    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> => {
@@ -104,25 +192,54 @@ export class ZudokuContext {
     return keys.flat();
   };
 
-  getPluginSidebar = async (path: string) => {
+  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);
+  };
+
+  getPluginNavigation = async (path: string) => {
     const navigations = await Promise.all(
       this.navigationPlugins.map((plugin) =>
-        plugin.getSidebar?.(joinPath(path)),
+        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");
     }
 
-    const accessToken = await this.authentication.getAccessToken();
+    return await this.authentication.signRequest(request);
+  };
+}
 
-    request.headers.set("Authorization", `Bearer ${accessToken}`);
+const sortByCategory =
+  (categories: string[]) =>
+  (a: ProfileNavigationItem, b: ProfileNavigationItem) => {
+    const aIndex = categories.indexOf(a.category ?? "middle");
+    const bIndex = categories.indexOf(b.category ?? "middle");
 
-    return request;
+    return aIndex - bIndex;
   };
-}

package/src/lib/core/__internal.tsx

@@ -0,0 +1,30 @@
+/**
+ * ⚠️
+ * These are re-exports consumed from the main entry point in `src/app/main.tsx`
+ * This is to ensure that they share the exact same context in React.
+ * ⚠️
+ **/
+
+import { Helmet } from "@zudoku/react-helmet-async";
+import {
+  Bootstrap as BootstrapImport,
+  BootstrapStatic as BootstrapStaticImport,
+} from "../components/Bootstrap.js";
+import { BuildCheck as BuildCheckImport } from "../components/BuildCheck.js";
+import { Layout as LayoutImport } from "../components/Layout.js";
+import { Meta as MetaImport } from "../components/Meta.js";
+import { StatusPage as StatusPageImport } from "../components/StatusPage.js";
+import { RouterError as RouterErrorImport } from "../errors/RouterError.js";
+import { ServerError as ServerErrorImport } from "../errors/ServerError.js";
+import { RouteGuard as RouteGuardImport } from "./RouteGuard.js";
+
+export const Layout = LayoutImport;
+export const RouterError = RouterErrorImport;
+export const ServerError = ServerErrorImport;
+export const Bootstrap = BootstrapImport;
+export const BootstrapStatic = BootstrapStaticImport;
+export const RouteGuard = RouteGuardImport;
+export const Head = Helmet;
+export const StatusPage = StatusPageImport;
+export const BuildCheck = BuildCheckImport;
+export const Meta = MetaImport;

package/src/lib/core/plugins.ts

@@ -1,23 +1,41 @@
-import { type ReactElement } from "react";
-import { type RouteObject } from "react-router-dom";
-import type { Sidebar } from "../../config/validators/SidebarSchema.js";
-import { MdxComponentsType } from "../util/MdxComponents.js";
-import { ZudokuContext, type ApiIdentity } from "./ZudokuContext.js";
+import type { LucideIcon } from "lucide-react";
+import type { ReactElement } from "react";
+import type { Location, RouteObject } from "react-router";
+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,
+  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>;
+  getNavigation?: (path: string, context: ZudokuContext) => Promise<Navigation>;
+  getProtectedRoutes?: () => ProtectedRoutesInput;
 }
 
+export const createApiIdentityPlugin = (
+  plugin: ApiIdentityPlugin,
+): ApiIdentityPlugin => plugin;
+
+export const createProfileMenuPlugin = (
+  plugin: ProfileMenuPlugin,
+): ProfileMenuPlugin => plugin;
+
 export interface ApiIdentityPlugin {
   getIdentities: (context: ZudokuContext) => Promise<ApiIdentity[]>;
 }
@@ -36,17 +54,29 @@ export interface ProfileMenuPlugin {
 export type ProfileNavigationItem = {
   label: string;
   path?: string;
+  weight?: number;
+  category?: "top" | "middle" | "bottom";
   children?: ProfileNavigationItem[];
+  icon?: LucideIcon;
 };
 
 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 =>
@@ -57,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,5 +1,8 @@
 // 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 { Typography } from "../components/Typography.js";
 import { ZudokuError } from "../util/invariant.js";
 
 export function ErrorAlert({ error }: { error: unknown }) {
@@ -12,24 +15,20 @@ 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>
+    <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 && (
+        <SyntaxHighlight
+          className="max-h-[400px] [&>pre]:p-4"
+          language="js"
+          code={stringError}
+        />
+      )}
+    </Typography>
   );
 }

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,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,151 @@
+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", 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", () => {
+      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;
+}