zudoku 0.47.2 → 0.48.0

package/src/lib/components/navigation/{Sidebar.tsx → Navigation.tsx}

@@ -1,42 +1,44 @@
 import { VisuallyHidden } from "@radix-ui/react-visually-hidden";
-import type { SidebarItem as SidebarItemType } from "../../../config/validators/SidebarSchema.js";
+import type { NavigationItem as NavigationItemType } from "../../../config/validators/NavigationSchema.js";
 import { DrawerContent, DrawerTitle } from "../../ui/Drawer.js";
 import { Slot } from "../Slot.js";
-import { SidebarItem } from "./SidebarItem.js";
-import { SidebarWrapper } from "./SidebarWrapper.js";
+import { NavigationItem } from "./NavigationItem.js";
+import { NavigationWrapper } from "./NavigationWrapper.js";
 
-export const Sidebar = ({
+export const Navigation = ({
   onRequestClose,
-  sidebar,
+  navigation,
 }: {
   onRequestClose?: () => void;
-  sidebar: SidebarItemType[];
+  navigation: NavigationItemType[];
 }) => (
   <>
-    <SidebarWrapper>
+    <NavigationWrapper>
       <Slot.Target name="navigation-before" />
-      {sidebar.map((item) => (
-        <SidebarItem
+      {navigation.map((item) => (
+        <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 : "")
           }
           item={item}
         />
       ))}
       <Slot.Target name="navigation-after" />
-    </SidebarWrapper>
+    </NavigationWrapper>
     <DrawerContent
       className="lg:hidden h-[100dvh] start-0 w-[320px] rounded-none"
       aria-describedby={undefined}
     >
       <div className="p-4 overflow-y-auto overscroll-none">
         <VisuallyHidden>
-          <DrawerTitle>Sidebar</DrawerTitle>
+          <DrawerTitle>Navigation</DrawerTitle>
         </VisuallyHidden>
-        {sidebar.map((item) => (
-          <SidebarItem
+        {navigation.map((item) => (
+          <NavigationItem
             key={item.label}
             item={item}
             onRequestClose={onRequestClose}

package/src/lib/components/navigation/{SidebarBadge.tsx → NavigationBadge.tsx}

@@ -22,7 +22,7 @@ export const ColorMapInvert = {
   outline: "",
 };
 
-export const SidebarBadge = ({
+export const NavigationBadge = ({
   color,
   label,
   className,

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 { SidebarItem } from "./SidebarItem.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/{SidebarItem.tsx → NavigationItem.tsx}

@@ -8,13 +8,13 @@ import {
   TooltipProvider,
   TooltipTrigger,
 } from "zudoku/ui/Tooltip.js";
-import type { SidebarItem as SidebarItemType } from "../../../config/validators/SidebarSchema.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 { SidebarBadge } from "./SidebarBadge.js";
-import { SidebarCategory } from "./SidebarCategory.js";
+import { NavigationBadge } from "./NavigationBadge.js";
+import { NavigationCategory } from "./NavigationCategory.js";
 import { navigationListItem } from "./utils.js";
 
 const TruncatedLabel = ({
@@ -65,11 +65,11 @@ const TruncatedLabel = ({
 
 export const DATA_ANCHOR_ATTR = "data-anchor";
 
-export const SidebarItem = ({
+export const NavigationItem = ({
   item,
   onRequestClose,
 }: {
-  item: SidebarItemType;
+  item: NavigationItemType;
   onRequestClose?: () => void;
 }) => {
   const location = useLocation();
@@ -78,23 +78,26 @@ export const SidebarItem = ({
   switch (item.type) {
     case "category":
       return (
-        <SidebarCategory category={item} onRequestClose={onRequestClose} />
+        <NavigationCategory category={item} onRequestClose={onRequestClose} />
       );
     case "doc":
       return (
         <NavLink
+          viewTransition
           className={({ isActive, isPending }) =>
             navigationListItem({ isActive, isPending })
           }
-          to={joinUrl(item.id)}
+          to={joinUrl(item.path)}
           onClick={onRequestClose}
           end
         >
           {item.icon && <item.icon size={16} className="align-[-0.125em]" />}
           {item.badge ? (
             <>
-              <TruncatedLabel label={item.label} className="flex-1" />
-              <SidebarBadge {...item.badge} />
+              {item.label && (
+                <TruncatedLabel label={item.label} className="flex-1" />
+              )}
+              <NavigationBadge {...item.badge} />
             </>
           ) : (
             item.label
@@ -102,24 +105,26 @@ export const SidebarItem = ({
         </NavLink>
       );
     case "link":
-      return !item.href.startsWith("http") ? (
+    case "custom-page": {
+      const href = item.type === "link" ? item.to : item.path;
+      return !href.startsWith("http") ? (
         <AnchorLink
           to={{
-            pathname: item.href.split("#")[0],
-            hash: item.href.split("#")[1],
+            pathname: href.split("#")[0],
+            hash: href.split("#")[1],
             search: location.search,
           }}
-          {...{ [DATA_ANCHOR_ATTR]: item.href.split("#")[1] }}
+          {...{ [DATA_ANCHOR_ATTR]: href.split("#")[1] }}
           className={navigationListItem({
-            isActive: item.href === [location.pathname, activeAnchor].join("#"),
+            isActive: href === [location.pathname, activeAnchor].join("#"),
           })}
           onClick={onRequestClose}
         >
           {item.icon && <item.icon size={16} className="align-[-0.125em]" />}
           {item.badge ? (
             <>
-              <TruncatedLabel label={item.label} />
-              <SidebarBadge {...item.badge} />
+              {item.label && <TruncatedLabel label={item.label} />}
+              <NavigationBadge {...item.badge} />
             </>
           ) : (
             <span className="break-all">{item.label}</span>
@@ -128,7 +133,7 @@ export const SidebarItem = ({
       ) : (
         <a
           className={navigationListItem()}
-          href={item.href}
+          href={href}
           target="_blank"
           rel="noopener noreferrer"
           onClick={onRequestClose}
@@ -141,5 +146,6 @@ export const SidebarItem = ({
           </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<{
@@ -43,4 +43,4 @@ export const SidebarWrapper = ({
   );
 };
 
-SidebarWrapper.displayName = "SidebarWrapper";
+NavigationWrapper.displayName = "NavigationWrapper";

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

@@ -1,38 +1,38 @@
 import { cva } from "class-variance-authority";
 import { useLocation } from "react-router";
 import type {
-  SidebarItem,
-  SidebarItemCategory,
-} from "../../../config/validators/SidebarSchema.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,
       ]);
@@ -43,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" && joinUrl(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 = joinUrl(item.link.id);
+      const categoryLinkPath = joinUrl(item.link.path);
       if (categoryLinkPath === location.pathname) {
         return true;
       }
     }
 
     if (item.type === "doc") {
-      const docPath = joinUrl(item.id);
+      const docPath = joinUrl(item.path);
       if (docPath === location.pathname) {
         return true;
       }
@@ -79,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"
-        ? joinUrl(item.id)
+        ? joinUrl(item.path)
         : item.type === "category" && item.link
-          ? joinUrl(item.link.id)
+          ? joinUrl(item.link.path)
           : undefined;
 
     if (!itemId) return;
@@ -137,8 +134,10 @@ export const navigationListItem = cva(
 
 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 {
@@ -83,8 +80,7 @@ export type ZudokuContextOptions = {
   metadata?: Metadata;
   page?: Page;
   authentication?: AuthenticationPlugin;
-  topNavigation?: TopNavigationItem[];
-  sidebars?: SidebarConfig;
+  navigation?: Navigation;
   plugins?: ZudokuPlugin[];
   slots?: Record<string, SlotType>;
   /**
@@ -104,8 +100,7 @@ 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 readonly authentication?: ZudokuContextOptions["authentication"];
@@ -124,8 +119,7 @@ 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;
@@ -178,10 +172,10 @@ 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),
       ),
     );
 

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/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", () => {

package/src/lib/plugins/api-catalog/Catalog.tsx

@@ -13,7 +13,7 @@ export const Catalog = ({
   filterCatalogItems = (items) => items,
   label = "API Library",
   categoryLabel,
-}: Omit<ApiCatalogPluginOptions, "navigationId"> & {
+}: Omit<ApiCatalogPluginOptions, "path"> & {
   categoryLabel?: string;
 }) => {
   const auth = useAuthState();

package/src/lib/plugins/api-catalog/index.tsx

@@ -1,6 +1,6 @@
 import slugify from "@sindresorhus/slugify";
 import { matchPath } from "react-router";
-import type { SidebarItem } from "../../../config/validators/SidebarSchema.js";
+import type { NavigationItem } from "../../../config/validators/NavigationSchema.js";
 import type { AuthState } from "../../authentication/state.js";
 import type { ZudokuPlugin } from "../../core/plugins.js";
 import { joinUrl } from "../../util/joinUrl.js";
@@ -22,46 +22,46 @@ export type CatalogCategory = {
 };
 
 export type ApiCatalogPluginOptions = {
-  navigationId: string;
+  path: string;
   label: string;
   categories?: CatalogCategory[];
   items: ApiCatalogItem[];
-  filterCatalogItems?: filterCatalogItems;
+  filterCatalogItems?: FilterCatalogItemsFn;
 };
 
 export type CatalogContext<ProviderData = unknown> = {
   auth: AuthState<ProviderData>;
 };
 
-export type filterCatalogItems<ProviderData = unknown> = (
+export type FilterCatalogItemsFn<ProviderData = unknown> = (
   items: ApiCatalogItem[],
   { auth }: CatalogContext<ProviderData>,
 ) => ApiCatalogItem[];
 
 export const apiCatalogPlugin = ({
-  navigationId,
+  path,
   items,
   label,
   categories = [],
   filterCatalogItems,
 }: {
-  navigationId: string;
+  path: string;
   label: string;
   categories?: CatalogCategory[];
   items: ApiCatalogItem[];
-  filterCatalogItems?: filterCatalogItems;
+  filterCatalogItems?: FilterCatalogItemsFn;
 }): ZudokuPlugin => {
   const paths = Object.fromEntries(
     categories.flatMap((category) =>
       [undefined, ...category.tags].map((tag) => [
-        joinUrl(navigationId, tag ? getKey(category.label, tag) : undefined),
+        joinUrl(path, tag ? getKey(category.label, tag) : undefined),
         tag,
       ]),
     ),
   );
 
   return {
-    getSidebar: async (currentPath) => {
+    getNavigation: async (currentPath) => {
       const matches = Object.keys(paths).some((path) =>
         matchPath(path, currentPath),
       );
@@ -70,13 +70,13 @@ export const apiCatalogPlugin = ({
         return [];
       }
 
-      const sidebar: SidebarItem[] = categories.map((category) => ({
-        type: "category" as const,
+      const navigation: NavigationItem[] = categories.map((category) => ({
+        type: "category",
         label: category.label,
         collapsible: false,
         items: category.tags.map((tag) => ({
-          type: "doc" as const,
-          id: joinUrl(navigationId, getKey(category.label, tag)),
+          type: "link",
+          to: joinUrl(path, getKey(category.label, tag)),
           label: tag,
           badge: {
             label: String(
@@ -84,19 +84,19 @@ export const apiCatalogPlugin = ({
                 api.categories.find((c) => c.tags.includes(tag)),
               ).length,
             ),
-            color: "outline" as const,
+            color: "outline",
           },
         })),
       }));
 
-      sidebar.unshift({
-        type: "doc" as const,
-        id: joinUrl(navigationId),
+      navigation.unshift({
+        type: "link",
+        to: joinUrl(path),
         label: "Overview",
-        badge: { label: String(items.length), color: "outline" as const },
+        badge: { label: String(items.length), color: "outline" },
       });
 
-      return sidebar;
+      return navigation;
     },
     getRoutes: () =>
       Object.entries(paths).map(([path, tag]) => ({