zudoku 0.0.0-ec30b50 → 0.0.0-ed94abf

package/src/lib/components/navigation/SidebarCategory.tsx

@@ -1,14 +1,16 @@
 import * as Collapsible from "@radix-ui/react-collapsible";
+import { deepEqual } from "fast-equals";
 import { ChevronRightIcon } from "lucide-react";
-import { useEffect, useState } from "react";
+import { memo, useEffect, useState } from "react";
 import { NavLink, useMatch } from "react-router";
+import { Button } from "zudoku/ui/Button.js";
 import type { SidebarItemCategory } from "../../../config/validators/SidebarSchema.js";
 import { cn } from "../../util/cn.js";
 import { joinPath } from "../../util/joinPath.js";
 import { navigationListItem, SidebarItem } from "./SidebarItem.js";
 import { useIsCategoryOpen } from "./utils.js";
 
-export const SidebarCategory = ({
+const SidebarCategoryInner = ({
   category,
   onRequestClose,
 }: {
@@ -35,13 +37,15 @@ export const SidebarCategory = ({
   }, [isCategoryOpen]);
 
   const ToggleButton = isCollapsible && (
-    <button
-      type="button"
+    <Button
       onClick={(e) => {
         e.preventDefault();
         setOpen((prev) => !prev);
         setHasInteracted(true);
       }}
+      variant="ghost"
+      size="icon"
+      className="size-6 hover:bg-[hsl(from_hsl(var(--accent))_h_s_calc(l-5))] hover:dark:bg-[hsl(from_hsl(var(--accent))_h_s_calc(l+5))]"
     >
       <ChevronRightIcon
         size={16}
@@ -50,7 +54,7 @@ export const SidebarCategory = ({
           "shrink-0 group-data-[state=open]:rotate-90",
         )}
       />
-    </button>
+    </Button>
   );
 
   const icon = category.icon && (
@@ -62,7 +66,7 @@ export const SidebarCategory = ({
 
   const styles = navigationListItem({
     className: [
-      "text-start font-medium",
+      "group text-start font-medium",
       isCollapsible || typeof category.link !== "undefined"
         ? "cursor-pointer"
         : "cursor-default hover:bg-transparent",
@@ -90,12 +94,7 @@ export const SidebarCategory = ({
             }}
           >
             {icon}
-            <div
-              className={cn(
-                "flex items-center gap-2 justify-between w-full",
-                isActive ? "text-primary" : "text-foreground/80",
-              )}
-            >
+            <div className="flex items-center gap-2 justify-between w-full text-foreground/80 group-aria-[current='page']:text-primary">
               <div className="truncate">{category.label}</div>
               {ToggleButton}
             </div>
@@ -135,3 +134,7 @@ export const SidebarCategory = ({
     </Collapsible.Root>
   );
 };
+
+export const SidebarCategory = memo(SidebarCategoryInner, deepEqual);
+
+SidebarCategory.displayName = "SidebarCategory";

package/src/lib/components/navigation/SidebarItem.tsx

@@ -1,26 +1,30 @@
 import { cva } from "class-variance-authority";
 import { ExternalLinkIcon } from "lucide-react";
-import { NavLink, useSearchParams } from "react-router";
+import { NavLink, useLocation, useSearchParams } from "react-router";
 
 import type { SidebarItem as SidebarItemType } from "../../../config/validators/SidebarSchema.js";
-import { joinPath } from "../../util/joinPath.js";
+import { joinUrl } from "../../util/joinUrl.js";
 import { AnchorLink } from "../AnchorLink.js";
 import { useViewportAnchor } from "../context/ViewportAnchorContext.js";
 import { SidebarBadge } from "./SidebarBadge.js";
 import { SidebarCategory } from "./SidebarCategory.js";
 
 export const navigationListItem = cva(
-  "flex items-center gap-2 px-[--padding-nav-item] py-1.5 rounded-lg hover:bg-accent",
+  "flex items-center gap-2 px-[--padding-nav-item] my-0.5 py-1.5 rounded-lg hover:bg-accent tabular-nums",
   {
     variants: {
       isActive: {
-        true: "text-primary font-medium",
+        true: "bg-accent font-medium",
         false: "text-foreground/80",
       },
       isMuted: {
         true: "text-foreground/30",
         false: "",
       },
+      isPending: {
+        true: "bg-accent animate-pulse",
+        false: "",
+      },
     },
     defaultVariants: {
       isActive: false,
@@ -37,6 +41,7 @@ export const SidebarItem = ({
   item: SidebarItemType;
   onRequestClose?: () => void;
 }) => {
+  const location = useLocation();
   const { activeAnchor } = useViewportAnchor();
   const [searchParams] = useSearchParams();
 
@@ -48,9 +53,12 @@ export const SidebarItem = ({
     case "doc":
       return (
         <NavLink
-          className={({ isActive }) => navigationListItem({ isActive })}
-          to={joinPath(item.id)}
+          className={({ isActive, isPending }) =>
+            navigationListItem({ isActive, isPending })
+          }
+          to={joinUrl(item.id)}
           onClick={onRequestClose}
+          end
         >
           {item.icon && <item.icon size={16} className="align-[-0.125em]" />}
           {item.badge ? (
@@ -66,12 +74,16 @@ export const SidebarItem = ({
         </NavLink>
       );
     case "link":
-      return item.href.startsWith("#") ? (
+      return !item.href.startsWith("http") ? (
         <AnchorLink
-          to={{ hash: item.href, search: searchParams.toString() }}
-          {...{ [DATA_ANCHOR_ATTR]: item.href.slice(1) }}
+          to={{
+            pathname: item.href.split("#")[0],
+            hash: item.href.split("#")[1],
+            search: searchParams.toString(),
+          }}
+          {...{ [DATA_ANCHOR_ATTR]: item.href.split("#")[1] }}
           className={navigationListItem({
-            isActive: item.href.slice(1) === activeAnchor,
+            isActive: item.href === [location.pathname, activeAnchor].join("#"),
             className: item.badge?.placement !== "start" && "justify-between",
           })}
           onClick={onRequestClose}
@@ -87,25 +99,6 @@ export const SidebarItem = ({
             <span className="break-all">{item.label}</span>
           )}
         </AnchorLink>
-      ) : !item.href.startsWith("http") ? (
-        <NavLink
-          className={navigationListItem({
-            isActive: item.href.split("#")[1] === activeAnchor,
-            className: item.badge?.placement !== "start" && "justify-between",
-          })}
-          to={item.href}
-        >
-          {item.badge ? (
-            <>
-              <span className="truncate" title={item.label}>
-                {item.label}
-              </span>
-              <SidebarBadge {...item.badge} />
-            </>
-          ) : (
-            <span className="break-all">{item.label}</span>
-          )}
-        </NavLink>
       ) : (
         <a
           className={navigationListItem()}

package/src/lib/components/navigation/SidebarWrapper.tsx

@@ -1,27 +1,46 @@
-import { forwardRef, type PropsWithChildren } from "react";
+import { useEffect, useRef, type PropsWithChildren } from "react";
 import { cn } from "../../util/cn.js";
+import { scrollIntoViewIfNeeded } from "../../util/scrollIntoViewIfNeeded.js";
+import { useZudoku } from "../context/ZudokuContext.js";
+import { PoweredByZudoku } from "./PoweredByZudoku.js";
 
-export const SidebarWrapper = forwardRef<
-  HTMLDivElement,
-  PropsWithChildren<{ pushMainContent?: boolean; className?: string }>
->(({ children, className, pushMainContent }, ref) => (
-  <nav
-    // this data attribute is used in `Layout.tsx` to determine if side navigation
-    // is present for the current page so the main content is pushed to the right
-    // it's also important to set `peer` class here.
-    // maybe this could be simplified by adjusting the layout
-    data-navigation={String(pushMainContent)}
-    className={cn(
-      "scrollbar peer hidden lg:flex flex-col fixed text-sm overflow-y-auto shrink-0 border-r pr-10",
-      "-mx-[--padding-nav-item] pb-20 pt-[--padding-content-top]",
-      "w-[--side-nav-width] h-[calc(100%-var(--header-height))] scroll-pt-2 gap-2",
-      !pushMainContent && "border-r-0",
-      className,
-    )}
-    ref={ref}
-  >
-    {children}
-  </nav>
-));
+export const SidebarWrapper = ({
+  children,
+  className,
+}: PropsWithChildren<{
+  className?: string;
+}>) => {
+  const { options } = useZudoku();
+  const navRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const active = navRef.current?.querySelector('[aria-current="page"]');
+    scrollIntoViewIfNeeded(active ?? null);
+  }, []);
+
+  return (
+    <div className="grid sticky top-[--header-height] lg:h-[calc(100vh-var(--header-height))] grid-rows-[1fr_min-content] border-r">
+      <nav
+        ref={navRef}
+        className={cn(
+          "hidden max-w-[calc(var(--side-nav-width)+var(--padding-nav-item))] lg:flex scrollbar flex-col overflow-y-auto shrink-0 text-sm pe-3 ps-4 lg:ps-8",
+          "-mx-[--padding-nav-item] pb-[8vh] pt-[--padding-content-top] scroll-pt-2 gap-1",
+          // Revert the padding/margin on the first child
+          "-mt-2.5",
+          className,
+        )}
+        style={{
+          maskImage: `linear-gradient(180deg, transparent 1%, rgba(0, 0, 0, 1) 20px, rgba(0, 0, 0, 1) 90%, transparent 99%)`,
+        }}
+      >
+        {children}
+      </nav>
+
+      <div className="bg-background border-t p-2 mx-5  gap-2 items-center mt-2 drop-shadow-[0_-3px_1px_rgba(0,0,0,0.015)] hidden lg:[&:has(>_:nth-child(1):last-child)]:flex">
+        {options.page?.showPoweredBy !== false && <PoweredByZudoku />}
+      </div>
+    </div>
+  );
+};
 
 SidebarWrapper.displayName = "SidebarWrapper";

package/src/lib/{plugins/markdown → components/navigation}/Toc.tsx

@@ -7,9 +7,9 @@ import {
   type CSSProperties,
   type PropsWithChildren,
 } from "react";
-import { AnchorLink } from "../../components/AnchorLink.js";
-import { useViewportAnchor } from "../../components/context/ViewportAnchorContext.js";
 import { cn } from "../../util/cn.js";
+import { AnchorLink } from "../AnchorLink.js";
+import { useViewportAnchor } from "../context/ViewportAnchorContext.js";
 
 const DATA_ANCHOR_ATTR = "data-active";
 
@@ -24,23 +24,14 @@ const TocItem = ({
   className?: string;
 }>) => {
   return (
-    <li
-      className={cn(
-        "truncate",
-        isActive
-          ? "text-primary"
-          : "text-foreground/65 dark:text-foreground/75",
-        className,
-      )}
-      title={item.value}
-    >
+    <li className={cn("truncate", className)} title={item.value}>
       <AnchorLink
         to={`#${item.id}`}
         {...{ [DATA_ANCHOR_ATTR]: item.id }}
         className={cn(
           isActive
             ? "text-primary"
-            : "text-foreground/65 dark:text-foreground/75 hover:text-foreground",
+            : "hover:text-accent-foreground text-muted-foreground",
         )}
       >
         {item.value}
@@ -89,7 +80,7 @@ export const Toc = ({ entries }: { entries: TocEntry[] }) => {
   }, [activeAnchor]);
 
   return (
-    <aside className="sticky scrollbar top-[--header-height] h-[calc(100vh-var(--header-height))] pt-[--padding-content-top] pb-[--padding-content-bottom] overflow-y-auto ps-1 text-sm">
+    <aside className="sticky scrollbar top-8 lg:top-[--header-height] h-[calc(100vh-var(--header-height))] pt-[--padding-content-top] pb-[--padding-content-bottom] overflow-y-auto ps-1 text-sm">
       <div className="flex items-center gap-2 font-medium mb-2">
         <ListTreeIcon size={16} />
         On this page

package/src/lib/components/navigation/ZudokuLogo.tsx

@@ -0,0 +1,25 @@
+import * as React from "react";
+
+const ZudokuLogo = (props: React.SVGProps<SVGSVGElement>) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 132 100"
+    fill="none"
+    {...props}
+  >
+    <path
+      fill="currentColor"
+      fillRule="evenodd"
+      d="M80.092 2.963A4.66 4.66 0 0 1 84.449 0h34.049c6.325 0 10.835 6.135 8.948 12.172L116.653 46.71a4.688 4.688 0 0 1-4.474 3.29H75c-5.178 0-7.813 4.687-9.375 9.374-1.288 3.864-11.07 28.963-14.467 37.662A4.66 4.66 0 0 1 46.801 100H12.75c-6.324 0-10.834-6.134-8.947-12.171l10.793-34.54A4.688 4.688 0 0 1 19.071 50H56.25c5.178 0 7.813-4.687 9.375-9.375 1.288-3.864 11.07-28.962 14.467-37.662Z"
+      clipRule="evenodd"
+    />
+    <path
+      fill="currentColor"
+      d="M83.54 57.813a7.813 7.813 0 0 0-7.316 5.07L63.888 95.777c-.766 2.043.744 4.222 2.926 4.222h36.828c5.211 0 9.875-3.232 11.704-8.11l8.821-23.522c1.915-5.107-1.861-10.555-7.315-10.555H83.539ZM29.17 0a12.5 12.5 0 0 0-11.704 8.111l-8.82 23.521c-1.915 5.107 1.86 10.556 7.315 10.556h33.312a7.813 7.813 0 0 0 7.316-5.07L68.924 4.223C69.691 2.18 68.18 0 65.998 0H29.17Z"
+    />
+  </svg>
+);
+
+ZudokuLogo.displayName = "ZudokuLogo";
+
+export default ZudokuLogo;

package/src/lib/components/navigation/ZuploLogo.tsx

@@ -0,0 +1,14 @@
+import type * as React from "react";
+
+const ZuploLogo = (props: React.SVGProps<SVGSVGElement>) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 76 66"
+    fill="none"
+    {...props}
+  >
+    <path d="M55.331 43.537H32.527l24.295-24.343a1.642 1.642 0 0 0-1.157-2.802H17.07V.239h42.336a16.407 16.407 0 0 1 8.81 2.438 16.471 16.471 0 0 1 6.147 6.775 16.037 16.037 0 0 1-3.167 18.201L55.331 43.535v.002Z" />
+    <path d="M20.695 21.888H43.5L19.204 46.23a1.643 1.643 0 0 0 1.158 2.802h38.595v16.153H16.621a16.406 16.406 0 0 1-8.81-2.438 16.471 16.471 0 0 1-6.147-6.775 16.038 16.038 0 0 1 3.167-18.201L20.695 21.89v-.002Z" />
+  </svg>
+);
+export default ZuploLogo;

package/src/lib/core/RouteGuard.tsx

@@ -1,26 +1,74 @@
-import { useEffect } from "react";
-import { matchPath, Outlet, useLocation } from "react-router";
+import { useQuery } from "@tanstack/react-query";
+import { Helmet } from "@zudoku/react-helmet-async";
+import { use } from "react";
+import { matchPath, Outlet, useLocation, useNavigate } from "react-router";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+} from "zudoku/ui/Dialog.js";
 import { useAuth } from "../authentication/hook.js";
+import { BypassProtectedRoutesContext } from "../components/context/BypassProtectedRoutesContext.js";
 import { useZudoku } from "../components/context/ZudokuContext.js";
 import { ZudokuError } from "../util/invariant.js";
+import { useLatest } from "../util/useLatest.js";
+
+export const SEARCH_PROTECTED_SECTION = "protected";
 
 export const RouteGuard = () => {
   const auth = useAuth();
   const zudoku = useZudoku();
+  const navigate = useNavigate();
   const location = useLocation();
+  const latestPath = useLatest(location.pathname);
+  const shouldBypass = use(BypassProtectedRoutesContext);
 
-  const isProtected = zudoku.options.protectedRoutes?.some((path) =>
-    matchPath({ path, end: true }, location.pathname),
-  );
+  const { protectedRoutes = [] } = zudoku.options;
 
-  useEffect(() => {
-    if (isProtected && !auth.isAuthenticated) {
-      void zudoku.authentication?.signIn();
-    }
-  }, [isProtected, auth.isAuthenticated, zudoku.authentication]);
+  const isProtected =
+    !shouldBypass &&
+    protectedRoutes.some((path) =>
+      matchPath({ path, end: true }, location.pathname),
+    );
+
+  useQuery({
+    queryKey: ["login-redirect"],
+    queryFn: async () => {
+      await new Promise((resolve) => setTimeout(resolve, 1200));
+      await zudoku.authentication?.signIn({
+        redirectTo: latestPath.current,
+      });
+      return true;
+    },
+    enabled:
+      typeof window !== "undefined" &&
+      isProtected &&
+      !auth.isPending &&
+      !auth.isAuthenticated,
+  });
 
   if (isProtected && !auth.isAuthenticated) {
-    return null;
+    return (
+      <Dialog
+        open={true}
+        onOpenChange={(open) => {
+          if (!open) {
+            void navigate(-1);
+          }
+        }}
+      >
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Logging you in...</DialogTitle>
+          </DialogHeader>
+          <DialogDescription>
+            Please wait while we log you in.
+          </DialogDescription>
+        </DialogContent>
+      </Dialog>
+    );
   }
 
   if (isProtected && !auth.isAuthEnabled) {
@@ -31,5 +79,18 @@ export const RouteGuard = () => {
     });
   }
 
-  return <Outlet />;
+  return (
+    <>
+      {shouldBypass && (
+        <Helmet>
+          <meta
+            name="pagefind"
+            data-pagefind-filter={`section:${SEARCH_PROTECTED_SECTION}`}
+            content="true"
+          />
+        </Helmet>
+      )}
+      <Outlet />
+    </>
+  );
 };

package/src/lib/core/ZudokuContext.ts

@@ -1,21 +1,40 @@
-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 { 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 { AuthenticationProvider } 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 { Slotlets } from "../components/SlotletProvider.js";
 import { joinPath } from "../util/joinPath.js";
 import type { MdxComponentsType } from "../util/MdxComponents.js";
+import { objectEntries } from "../util/objectEntries.js";
 import {
   isApiIdentityPlugin,
+  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 +56,14 @@ type Metadata = Partial<{
 }>;
 
 type Page = Partial<{
+  showPoweredBy: boolean;
   pageTitle?: string;
   logo?: {
     src: {
       light: string;
       dark: string;
     };
-    width?: string;
+    width?: string | number;
     alt?: string;
   };
   banner?: {
@@ -51,9 +71,12 @@ 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;
@@ -76,8 +99,12 @@ export class ZudokuContext {
   public page: ZudokuContextOptions["page"];
   public authentication?: ZudokuContextOptions["authentication"];
   private readonly navigationPlugins: NavigationPlugin[];
+  private emitter = createNanoEvents<ZudokuEvents>();
 
-  constructor(public readonly options: ZudokuContextOptions) {
+  constructor(
+    public readonly options: ZudokuContextOptions,
+    public readonly queryClient: QueryClient,
+  ) {
     this.plugins = options.plugins ?? [];
     this.topNavigation = options.topNavigation ?? [];
     this.sidebars = options.sidebars ?? {};
@@ -85,6 +112,20 @@ export class ZudokuContext {
     this.authentication = options.authentication;
     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 +146,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 +175,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,37 @@
 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 { MdxComponentsType } from "../util/MdxComponents.js";
+import type {
+  ApiIdentity,
+  ZudokuContext,
+  ZudokuEvents,
+} from "./ZudokuContext.js";
 
 export type ZudokuPlugin =
   | CommonPlugin
   | ProfileMenuPlugin
   | NavigationPlugin
   | ApiIdentityPlugin
-  | SearchProviderPlugin;
+  | SearchProviderPlugin
+  | EventConsumerPlugin;
 
 export type { RouteObject };
 
 export interface NavigationPlugin {
   getRoutes: () => RouteObject[];
-  getSidebar?: (path: string) => Promise<Sidebar>;
+  getSidebar?: (path: string, context: ZudokuContext) => Promise<Sidebar>;
 }
 
+export const createApiIdentityPlugin = (
+  plugin: ApiIdentityPlugin,
+): ApiIdentityPlugin => plugin;
+
+export const createProfileMenuPlugin = (
+  plugin: ProfileMenuPlugin,
+): ProfileMenuPlugin => plugin;
+
 export interface ApiIdentityPlugin {
   getIdentities: (context: ZudokuContext) => Promise<ApiIdentity[]>;
 }
@@ -47,10 +60,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 =>