zudoku 0.0.0-f0602bf → 0.0.0-f0b4321

package/src/lib/components/navigation/{SidebarCategory.tsx → NavigationCategory.tsx}

@@ -4,17 +4,17 @@ import { ChevronRightIcon } from "lucide-react";
 import { memo, useEffect, useState } from "react";
 import { NavLink, useLocation, useMatch } from "react-router";
 import { Button } from "zudoku/ui/Button.js";
-import type { SidebarItemCategory } from "../../../config/validators/SidebarSchema.js";
+import type { NavigationCategory as NavigationCategoryType } from "../../../config/validators/NavigationSchema.js";
 import { cn } from "../../util/cn.js";
 import { joinUrl } from "../../util/joinUrl.js";
-import { navigationListItem, SidebarItem } from "./SidebarItem.js";
-import { useIsCategoryOpen } from "./utils.js";
+import { NavigationItem } from "./NavigationItem.js";
+import { navigationListItem, useIsCategoryOpen } from "./utils.js";
 
-const SidebarCategoryInner = ({
+const NavigationCategoryInner = ({
   category,
   onRequestClose,
 }: {
-  category: SidebarItemCategory;
+  category: NavigationCategoryType;
   onRequestClose?: () => void;
 }) => {
   const isCategoryOpen = useIsCategoryOpen(category);
@@ -27,11 +27,11 @@ const SidebarCategoryInner = ({
     !isCollapsible || !isCollapsed || isCategoryOpen,
   );
   const [open, setOpen] = useState(isDefaultOpen);
-  const isActive = useMatch(category.link?.id ?? "");
+  const isActive = useMatch(category.link?.path ?? "");
 
   useEffect(() => {
-    // this is triggered when an item from the sidebar is clicked
-    // and the sidebar, enclosing this item, is not opened
+    // this is triggered when an item from the navigation is clicked
+    // and the navigation, enclosing this item, is not opened
     if (isCategoryOpen) {
       setOpen(true);
     }
@@ -85,7 +85,7 @@ const SidebarCategoryInner = ({
         {category.link?.type === "doc" ? (
           <NavLink
             to={{
-              pathname: joinUrl(category.link.id),
+              pathname: joinUrl(category.link.path),
               search: location.search,
             }}
             className={styles}
@@ -123,11 +123,13 @@ const SidebarCategoryInner = ({
       >
         <ul className="relative after:absolute after:-start-(--padding-nav-item) after:translate-x-[1.5px] after:top-0 after:bottom-0 after:w-px after:bg-border">
           {category.items.map((item) => (
-            <SidebarItem
+            <NavigationItem
               key={
-                ("id" in item ? item.id : "") +
-                ("href" in item ? item.href : "") +
-                item.label
+                item.type +
+                (item.label ?? "") +
+                ("path" in item ? item.path : "") +
+                ("file" in item ? item.file : "") +
+                ("to" in item ? item.to : "")
               }
               onRequestClose={onRequestClose}
               item={item}
@@ -139,6 +141,6 @@ const SidebarCategoryInner = ({
   );
 };
 
-export const SidebarCategory = memo(SidebarCategoryInner, deepEqual);
+export const NavigationCategory = memo(NavigationCategoryInner, deepEqual);
 
-SidebarCategory.displayName = "SidebarCategory";
+NavigationCategory.displayName = "NavigationCategory";

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

@@ -0,0 +1,151 @@
+import { ExternalLinkIcon } from "lucide-react";
+import { useEffect, useRef, useState } from "react";
+import { NavLink, useLocation } from "react-router";
+import {
+  Tooltip,
+  TooltipArrow,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "zudoku/ui/Tooltip.js";
+import type { NavigationItem as NavigationItemType } from "../../../config/validators/NavigationSchema.js";
+import { cn } from "../../util/cn.js";
+import { joinUrl } from "../../util/joinUrl.js";
+import { AnchorLink } from "../AnchorLink.js";
+import { useViewportAnchor } from "../context/ViewportAnchorContext.js";
+import { NavigationBadge } from "./NavigationBadge.js";
+import { NavigationCategory } from "./NavigationCategory.js";
+import { navigationListItem } from "./utils.js";
+
+const TruncatedLabel = ({
+  label,
+  className,
+}: {
+  label: string;
+  className?: string;
+}) => {
+  const ref = useRef<HTMLSpanElement>(null);
+  const [isTruncated, setIsTruncated] = useState(false);
+
+  useEffect(() => {
+    if (!ref.current) return;
+
+    if (ref.current.offsetWidth < ref.current.scrollWidth) {
+      setIsTruncated(true);
+    }
+  }, []);
+
+  return (
+    <>
+      <span
+        className={cn("truncate flex-1", className)}
+        title={label}
+        ref={ref}
+      >
+        {label}
+      </span>
+      {isTruncated && (
+        <TooltipProvider delayDuration={500}>
+          <Tooltip disableHoverableContent>
+            <TooltipTrigger className="absolute inset-0 z-10" />
+            <TooltipContent
+              className="max-w-64 rounded-lg"
+              side="bottom"
+              align="center"
+            >
+              <TooltipArrow />
+              {label}
+            </TooltipContent>
+          </Tooltip>
+        </TooltipProvider>
+      )}
+    </>
+  );
+};
+
+export const DATA_ANCHOR_ATTR = "data-anchor";
+
+export const NavigationItem = ({
+  item,
+  onRequestClose,
+}: {
+  item: NavigationItemType;
+  onRequestClose?: () => void;
+}) => {
+  const location = useLocation();
+  const { activeAnchor } = useViewportAnchor();
+
+  switch (item.type) {
+    case "category":
+      return (
+        <NavigationCategory category={item} onRequestClose={onRequestClose} />
+      );
+    case "doc":
+      return (
+        <NavLink
+          viewTransition
+          className={({ isActive, isPending }) =>
+            navigationListItem({ isActive, isPending })
+          }
+          to={joinUrl(item.path)}
+          onClick={onRequestClose}
+          end
+        >
+          {item.icon && <item.icon size={16} className="align-[-0.125em]" />}
+          {item.badge ? (
+            <>
+              {item.label && (
+                <TruncatedLabel label={item.label} className="flex-1" />
+              )}
+              <NavigationBadge {...item.badge} />
+            </>
+          ) : (
+            item.label
+          )}
+        </NavLink>
+      );
+    case "link":
+    case "custom-page": {
+      const href = item.type === "link" ? item.to : item.path;
+      return !href.startsWith("http") ? (
+        <AnchorLink
+          to={{
+            pathname: href.split("#")[0],
+            hash: href.split("#")[1],
+            search: location.search,
+          }}
+          {...{ [DATA_ANCHOR_ATTR]: href.split("#")[1] }}
+          className={navigationListItem({
+            isActive: href === [location.pathname, activeAnchor].join("#"),
+          })}
+          onClick={onRequestClose}
+        >
+          {item.icon && <item.icon size={16} className="align-[-0.125em]" />}
+          {item.badge ? (
+            <>
+              {item.label && <TruncatedLabel label={item.label} />}
+              <NavigationBadge {...item.badge} />
+            </>
+          ) : (
+            <span className="break-all">{item.label}</span>
+          )}
+        </AnchorLink>
+      ) : (
+        <a
+          className={navigationListItem()}
+          href={href}
+          target="_blank"
+          rel="noopener noreferrer"
+          onClick={onRequestClose}
+        >
+          {item.icon && <item.icon size={16} className="align-[-0.125em]" />}
+          <span className="whitespace-normal">{item.label}</span>
+          {/* This prevents that the icon would be positioned in its own line if the text fills a line entirely */}
+          <span className="whitespace-nowrap">
+            <ExternalLinkIcon className="inline -translate-y-0.5" size={12} />
+          </span>
+        </a>
+      );
+    }
+  }
+};

package/src/lib/components/navigation/{SidebarWrapper.tsx → NavigationWrapper.tsx}

@@ -4,7 +4,7 @@ import { scrollIntoViewIfNeeded } from "../../util/scrollIntoViewIfNeeded.js";
 import { useZudoku } from "../context/ZudokuContext.js";
 import { PoweredByZudoku } from "./PoweredByZudoku.js";
 
-export const SidebarWrapper = ({
+export const NavigationWrapper = ({
   children,
   className,
 }: PropsWithChildren<{
@@ -19,7 +19,10 @@ export const SidebarWrapper = ({
   }, []);
 
   return (
-    <div className="grid sticky top-(--header-height) lg:h-[calc(100vh-var(--header-height))] grid-rows-[1fr_min-content] border-r">
+    <div
+      className="grid sticky top-(--header-height) lg:h-[calc(100vh-var(--header-height))] grid-rows-[1fr_min-content] border-r"
+      data-pagefind-ignore="all"
+    >
       <nav
         ref={navRef}
         className={cn(
@@ -37,10 +40,10 @@ export const SidebarWrapper = ({
       </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 />}
+        {options.site?.showPoweredBy !== false && <PoweredByZudoku />}
       </div>
     </div>
   );
 };
 
-SidebarWrapper.displayName = "SidebarWrapper";
+NavigationWrapper.displayName = "NavigationWrapper";

package/src/lib/components/navigation/utils.ts

@@ -1,37 +1,38 @@
+import { cva } from "class-variance-authority";
 import { useLocation } from "react-router";
 import type {
-  SidebarItem,
-  SidebarItemCategory,
-} from "../../../config/validators/SidebarSchema.js";
-import { joinPath } from "../../util/joinPath.js";
+  NavigationCategory,
+  NavigationItem,
+} from "../../../config/validators/NavigationSchema.js";
+import { joinUrl } from "../../util/joinUrl.js";
 import { useCurrentNavigation } from "../context/ZudokuContext.js";
 
 export type TraverseCallback<T> = (
-  item: SidebarItem,
-  parentCategories: SidebarItem[],
+  item: NavigationItem,
+  parentCategories: NavigationItem[],
 ) => T | void;
 
-export const traverseSidebar = <T>(
-  sidebar: SidebarItem[],
+export const traverseNavigation = <T>(
+  navigation: NavigationItem[],
   callback: TraverseCallback<T>,
 ): T | undefined => {
-  for (const item of sidebar) {
-    const result = traverseSidebarItem(item, callback);
+  for (const item of navigation) {
+    const result = traverseNavigationItem(item, callback);
     if (result !== undefined) return result;
   }
 };
 
-export const traverseSidebarItem = <T>(
-  item: SidebarItem,
+export const traverseNavigationItem = <T>(
+  item: NavigationItem,
   callback: TraverseCallback<T>,
-  parentCategories: SidebarItem[] = [],
+  parentCategories: NavigationItem[] = [],
 ): T | undefined => {
   const result = callback(item, parentCategories);
   if (result !== undefined) return result;
 
   if (item.type === "category") {
     for (const child of item.items) {
-      const childResult = traverseSidebarItem(child, callback, [
+      const childResult = traverseNavigationItem(child, callback, [
         ...parentCategories,
         item,
       ]);
@@ -42,30 +43,28 @@ export const traverseSidebarItem = <T>(
 
 export const useCurrentItem = () => {
   const location = useLocation();
-  const nav = useCurrentNavigation();
+  const { navigation } = useCurrentNavigation();
 
-  const currentSidebar = nav.sidebar;
-
-  return traverseSidebar(currentSidebar, (item) => {
-    if (item.type === "doc" && joinPath(item.id) === location.pathname) {
+  return traverseNavigation(navigation, (item) => {
+    if (item.type === "doc" && joinUrl(item.path) === location.pathname) {
       return item;
     }
   });
 };
 
-export const useIsCategoryOpen = (category: SidebarItemCategory) => {
+export const useIsCategoryOpen = (category: NavigationCategory) => {
   const location = useLocation();
 
-  return traverseSidebarItem(category, (item) => {
+  return traverseNavigationItem(category, (item) => {
     if (item.type === "category" && item.link) {
-      const categoryLinkPath = joinPath(item.link.id);
+      const categoryLinkPath = joinUrl(item.link.path);
       if (categoryLinkPath === location.pathname) {
         return true;
       }
     }
 
     if (item.type === "doc") {
-      const docPath = joinPath(item.id);
+      const docPath = joinUrl(item.path);
       if (docPath === location.pathname) {
         return true;
       }
@@ -78,20 +77,19 @@ export const usePrevNext = (): {
   next?: { label: string; id: string };
 } => {
   const currentId = useLocation().pathname;
-  const nav = useCurrentNavigation();
-  const currentSidebar = nav.sidebar;
+  const { navigation } = useCurrentNavigation();
 
   let prev;
   let next;
 
   let foundCurrent = false;
 
-  traverseSidebar(currentSidebar, (item) => {
+  traverseNavigation(navigation, (item) => {
     const itemId =
       item.type === "doc"
-        ? joinPath(item.id)
+        ? joinUrl(item.path)
         : item.type === "category" && item.link
-          ? joinPath(item.link.id)
+          ? joinUrl(item.link.path)
           : undefined;
 
     if (!itemId) return;
@@ -111,10 +109,35 @@ export const usePrevNext = (): {
   return { prev, next };
 };
 
+export const navigationListItem = cva(
+  "relative 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: "bg-accent font-medium",
+        false: "text-foreground/80",
+      },
+      isMuted: {
+        true: "text-foreground/30",
+        false: "",
+      },
+      isPending: {
+        true: "bg-accent animate-pulse",
+        false: "",
+      },
+    },
+    defaultVariants: {
+      isActive: false,
+    },
+  },
+);
+
 export const isHiddenItem =
   (isAuthenticated?: boolean) =>
-  (item: { display?: "auth" | "anon" | "always" | "hide" }): boolean => {
+  (item: NavigationItem): boolean => {
     if (item.display === "hide") return false;
+    if (!item.label) return false;
+
     return (
       (item.display === "auth" && isAuthenticated) ||
       (item.display === "anon" && !isAuthenticated) ||

package/src/lib/core/ZudokuContext.ts

@@ -3,17 +3,14 @@ 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 { z } from "zod/v4";
+import type { Navigation } from "../../config/validators/NavigationSchema.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 { SlotType } from "../components/context/SlotProvider.js";
-import { joinPath } from "../util/joinPath.js";
+import { joinUrl } from "../util/joinUrl.js";
 import type { MdxComponentsType } from "../util/MdxComponents.js";
 import { objectEntries } from "../util/objectEntries.js";
 import {
@@ -21,8 +18,10 @@ import {
   isAuthenticationPlugin,
   isEventConsumerPlugin,
   isNavigationPlugin,
+  isProfileMenuPlugin,
   type NavigationPlugin,
   needsInitialization,
+  type ProfileNavigationItem,
   type ZudokuPlugin,
 } from "./plugins.js";
 
@@ -57,10 +56,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;
@@ -68,6 +67,7 @@ type Page = Partial<{
     };
     width?: string | number;
     alt?: string;
+    href?: string;
   };
   banner?: {
     message: ReactNode;
@@ -81,10 +81,9 @@ export type ZudokuContextOptions = {
   basePath?: string;
   canonicalUrlOrigin?: string;
   metadata?: Metadata;
-  page?: Page;
+  site?: Site;
   authentication?: AuthenticationPlugin;
-  topNavigation?: TopNavigationItem[];
-  sidebars?: SidebarConfig;
+  navigation?: Navigation;
   plugins?: ZudokuPlugin[];
   slots?: Record<string, SlotType>;
   /**
@@ -104,10 +103,9 @@ export type ZudokuContextOptions = {
 
 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 site: ZudokuContextOptions["site"];
   public readonly authentication?: ZudokuContextOptions["authentication"];
   public readonly queryClient: QueryClient;
   public readonly options: ZudokuContextOptions;
@@ -124,12 +122,11 @@ export class ZudokuContext {
     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 = this.plugins.find(isAuthenticationPlugin);
     this.meta = options.metadata;
-    this.page = options.page;
+    this.site = options.site;
     this.plugins.forEach((plugin) => {
       if (!isEventConsumerPlugin(plugin)) return;
 
@@ -178,16 +175,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");
@@ -196,3 +203,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,7 @@
 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 { AuthenticationPlugin } from "../authentication/authentication.js";
 import type { MdxComponentsType } from "../util/MdxComponents.js";
 import type {
@@ -23,7 +23,7 @@ export type { AuthenticationPlugin, RouteObject };
 
 export interface NavigationPlugin {
   getRoutes: () => RouteObject[];
-  getSidebar?: (path: string, context: ZudokuContext) => Promise<Sidebar>;
+  getNavigation?: (path: string, context: ZudokuContext) => Promise<Navigation>;
   getProtectedRoutes?: () => string[];
 }
 

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,12 +18,7 @@ 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>}
@@ -37,6 +31,6 @@ export function ErrorAlert({ error }: { error: unknown }) {
           />
         </div>
       )}
-    </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", () => {