zudoku 0.3.0-dev.83 → 0.3.0-dev.85

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

@@ -0,0 +1,40 @@
+import { cn } from "../../util/cn.js";
+
+export const TextColorMap = {
+  green: "text-green-600",
+  blue: "text-sky-600",
+  yellow: "text-yellow-600",
+  red: "text-red-600",
+  purple: "text-purple-600",
+  indigo: "text-indigo-600",
+  gray: "text-gray-600",
+};
+
+export const ColorMap = {
+  green: "bg-green-400 dark:bg-green-800",
+  blue: "bg-sky-400 dark:bg-sky-800",
+  yellow: "bg-yellow-400 dark:bg-yellow-800",
+  red: "bg-red-400 dark:bg-red-800",
+  purple: "bg-purple-400 dark:bg-purple-600",
+  indigo: "bg-indigo-400 dark:bg-indigo-600",
+  gray: "bg-gray-400 dark:bg-gray-600",
+};
+
+export const SidebarBadge = ({
+  color,
+  label,
+}: {
+  color: keyof typeof ColorMap;
+  label: string;
+}) => {
+  return (
+    <span
+      className={cn(
+        "mt-0.5 flex items-center duration-200 transition-opacity text-center uppercase font-mono text-[0.65rem] font-bold rounded text-background dark:text-zinc-50 h-4 px-1",
+        ColorMap[color],
+      )}
+    >
+      {label}
+    </span>
+  );
+};

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

@@ -0,0 +1,105 @@
+import * as Collapsible from "@radix-ui/react-collapsible";
+import { ChevronRightIcon } from "lucide-react";
+import { useEffect, useState } from "react";
+import { NavLink } from "react-router-dom";
+import type { ResolvedSidebarItemCategory } from "../../../config/validators/ResolvedSidebarSchema.js";
+import { cn } from "../../util/cn.js";
+import { joinPath } from "../../util/joinPath.js";
+import { useTopNavigationItem } from "../context/DevPortalProvider.js";
+import { navigationListItem, SidebarItem } from "./SidebarItem.js";
+import { useIsCategoryOpen } from "./utils.js";
+
+export const SidebarCategory = ({
+  category,
+  level,
+}: {
+  category: ResolvedSidebarItemCategory;
+  level: number;
+}) => {
+  const topNavItem = useTopNavigationItem();
+  const isCategoryOpen = useIsCategoryOpen(category);
+
+  const isCollapsible = category.collapsible ?? true;
+  const isCollapsed = category.collapsed ?? true;
+  const isDefaultOpen = Boolean(
+    !isCollapsible || !isCollapsed || isCategoryOpen,
+  );
+  const [open, setOpen] = useState(isDefaultOpen);
+
+  useEffect(() => {
+    // this is triggered when an item from the sidebar is clicked
+    // and the sidebar, enclosing this item, is not opened
+    if (isCategoryOpen) {
+      setOpen(true);
+    }
+  }, [isCategoryOpen]);
+
+  const ToggleButton = isCollapsible && (
+    <button
+      type="button"
+      onClick={(e) => {
+        e.preventDefault();
+        setOpen((prev) => !prev);
+      }}
+    >
+      <ChevronRightIcon
+        size={16}
+        className="transition shrink-0 group-data-[state=open]:rotate-90"
+      />
+    </button>
+  );
+
+  return (
+    <Collapsible.Root
+      className={cn("flex flex-col", level === 0 && "-mx-[--padding-nav-item]")}
+      defaultOpen={isDefaultOpen}
+      open={open}
+      onOpenChange={() => setOpen(true)}
+    >
+      <Collapsible.Trigger
+        className={cn(
+          "group text-start",
+          navigationListItem({ isActive: false, isTopLevel: level === 0 }),
+          isCollapsible
+            ? "cursor-pointer"
+            : "cursor-default hover:bg-transparent",
+        )}
+        asChild
+        disabled={!isCollapsible}
+      >
+        {category.link?.type === "doc" ? (
+          <NavLink to={joinPath(topNavItem?.id, category.link.id)}>
+            {({ isActive }) => (
+              <div
+                className={cn(
+                  "flex items-center gap-2 justify-between w-full",
+                  isActive ? "text-primary font-medium" : "text-foreground/80",
+                )}
+              >
+                <div className="truncate">{category.label}</div>
+                {ToggleButton}
+              </div>
+            )}
+          </NavLink>
+        ) : (
+          <div className="flex items-center justify-between w-full">
+            <div className="flex gap-2 truncate w-full">{category.label}</div>
+            {ToggleButton}
+          </div>
+        )}
+      </Collapsible.Trigger>
+      <Collapsible.Content className="CollapsibleContent ms-[calc(var(--padding-nav-item)*1.125)]">
+        <ul className="mt-1 border-l ps-2">
+          {category.items.map((item) => (
+            <SidebarItem
+              key={item.label}
+              level={level + 1}
+              item={item}
+              // activeAnchor={activeAnchor}
+            />
+          ))}
+        </ul>
+      </Collapsible.Content>
+    </Collapsible.Root>
+  );
+};

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

@@ -0,0 +1,96 @@
+import { cva } from "class-variance-authority";
+import { ExternalLinkIcon } from "lucide-react";
+import { NavLink } from "react-router-dom";
+
+import type { ResolvedSidebarItem } from "../../../config/validators/ResolvedSidebarSchema.js";
+import { cn } from "../../util/cn.js";
+import { joinPath } from "../../util/joinPath.js";
+import { AnchorLink } from "../AnchorLink.js";
+import { useTopNavigationItem } from "../context/DevPortalProvider.js";
+import { useViewportAnchor } from "../context/ViewportAnchorContext.js";
+import { SidebarBadge } from "./SidebarBadge.js";
+import { SidebarCategory } from "./SidebarCategory.js";
+
+export const navigationListItem = cva(
+  "flex px-[--padding-nav-item] py-1.5 rounded-lg hover:bg-accent transition-colors duration-300",
+  {
+    variants: {
+      isTopLevel: {
+        true: "font-semibold",
+      },
+      isActive: {
+        true: "text-primary font-medium",
+        false: "text-foreground/80",
+      },
+      isMuted: {
+        true: "text-foreground/30",
+        false: "",
+      },
+    },
+  },
+);
+
+export const DATA_ANCHOR_ATTR = "data-anchor";
+
+export const SidebarItem = ({
+  item,
+  level = 0,
+}: {
+  item: ResolvedSidebarItem;
+  basePath?: string;
+  level?: number;
+}) => {
+  const topNavItem = useTopNavigationItem();
+  const { activeAnchor } = useViewportAnchor();
+
+  switch (item.type) {
+    case "category":
+      return <SidebarCategory category={item} level={level} />;
+    case "doc":
+      return (
+        <NavLink
+          className={({ isActive }) =>
+            navigationListItem({ isActive, isTopLevel: level === 0 })
+          }
+          to={joinPath(topNavItem?.id, item.id)}
+        >
+          {item.label}
+          {item.badge && <SidebarBadge {...item.badge} />}
+        </NavLink>
+      );
+    case "link":
+      return item.href.startsWith("#") ? (
+        <AnchorLink
+          to={item.href}
+          {...{ [DATA_ANCHOR_ATTR]: item.href.slice(1) }}
+          className={cn(
+            "flex gap-2.5 justify-between",
+            level === 0 && "-mx-[--padding-nav-item]",
+            navigationListItem({
+              isActive: item.href.slice(1) === activeAnchor,
+            }),
+          )}
+        >
+          {item.label}
+          {item.badge && <SidebarBadge {...item.badge} />}
+        </AnchorLink>
+      ) : (
+        <a
+          className={cn(
+            navigationListItem({ isTopLevel: level === 0 }),
+            "block",
+          )}
+          href={item.href}
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          <span className="whitespace-normal">{item.label}</span>
+          {/* This prevents that the icon would be positioned in its own line if the text fills an line entirely */}
+          <span className="whitespace-nowrap">
+            &nbsp;
+            <ExternalLinkIcon className="inline ml-1" size={12} />
+          </span>
+        </a>
+      );
+  }
+};

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

@@ -1,7 +1,7 @@
 import { forwardRef, type PropsWithChildren } from "react";
 import { cn } from "../../util/cn.js";
 
-export const SideNavigationWrapper = forwardRef<
+export const SidebarWrapper = forwardRef<
   HTMLDivElement,
   PropsWithChildren<{ pushMainContent?: boolean; className?: string }>
 >(function SideNavigation({ children, className, pushMainContent }, ref) {

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

@@ -0,0 +1,120 @@
+import { useLocation } from "react-router-dom";
+import type {
+  ResolvedSidebarItem,
+  ResolvedSidebarItemCategory,
+} from "../../../config/validators/ResolvedSidebarSchema.js";
+import { joinPath } from "../../util/joinPath.js";
+import {
+  useDevPortal,
+  useTopNavigationItem,
+} from "../context/DevPortalProvider.js";
+
+export type TraverseCallback<T> = (
+  item: ResolvedSidebarItem,
+  parentCategories: ResolvedSidebarItem[],
+) => T | void;
+
+export const traverseSidebar = <T>(
+  sidebar: ResolvedSidebarItem[],
+  callback: TraverseCallback<T>,
+): T | undefined => {
+  for (const item of sidebar) {
+    const result = traverseSidebarItem(item, callback);
+    if (result !== undefined) return result;
+  }
+};
+
+export const traverseSidebarItem = <T>(
+  item: ResolvedSidebarItem,
+  callback: TraverseCallback<T>,
+  parentCategories: ResolvedSidebarItem[] = [],
+): 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, [
+        ...parentCategories,
+        item,
+      ]);
+      if (childResult !== undefined) return childResult;
+    }
+  }
+};
+
+export const useCurrentItem = () => {
+  const location = useLocation();
+  const topNavItem = useTopNavigationItem();
+  const { sidebars } = useDevPortal();
+  const currentSidebar = topNavItem?.id ? sidebars[topNavItem.id] : [];
+
+  return traverseSidebar(currentSidebar, (item) => {
+    if (
+      item.type === "doc" &&
+      joinPath(topNavItem?.id, item.id) === location.pathname
+    ) {
+      return item;
+    }
+  });
+};
+
+export const useIsCategoryOpen = (category: ResolvedSidebarItemCategory) => {
+  const location = useLocation();
+  const topNavItem = useTopNavigationItem();
+
+  return traverseSidebarItem(category, (item) => {
+    if (item.type === "category" && item.link) {
+      const categoryLinkPath = joinPath(topNavItem?.id, item.link.id);
+      if (categoryLinkPath === location.pathname) {
+        return true;
+      }
+    }
+
+    if (item.type === "doc") {
+      const docPath = joinPath(topNavItem?.id, item.id);
+      if (docPath === location.pathname) {
+        return true;
+      }
+    }
+  });
+};
+
+export const usePrevNext = (): {
+  prev?: { label: string; id: string };
+  next?: { label: string; id: string };
+} => {
+  const currentId = useLocation().pathname;
+  const { sidebars } = useDevPortal();
+  const topNavItem = useTopNavigationItem();
+  const currentSidebar = topNavItem?.id ? sidebars[topNavItem.id] : [];
+
+  let prev;
+  let next;
+
+  let foundCurrent = false;
+
+  traverseSidebar(currentSidebar, (item) => {
+    const itemId =
+      item.type === "doc"
+        ? joinPath(topNavItem?.id, item.id)
+        : item.type === "category" && item.link
+          ? joinPath(topNavItem?.id, item.link.id)
+          : undefined;
+
+    if (!itemId) return;
+
+    if (foundCurrent) {
+      next = { label: item.label, id: itemId };
+      return true;
+    }
+
+    if (currentId === itemId) {
+      foundCurrent = true;
+    } else {
+      prev = { label: item.label, id: itemId };
+    }
+  });
+
+  return { prev, next };
+};

package/src/lib/core/DevPortalContext.ts

@@ -1,10 +1,10 @@
 import { QueryClient } from "@tanstack/react-query";
-import { type ReactNode } from "react";
 import { NavigateFunction } from "react-router-dom";
+import type { ResolvedSidebarConfig } from "../../config/validators/ResolvedSidebarSchema.js";
 import { type AuthenticationProvider } from "../authentication/authentication.js";
 import type { ComponentsContextType } from "../components/context/ComponentsContext.js";
-import { type DevPortalPath } from "../components/DevPortal.js";
 import { Slotlets } from "../components/SlotletProvider.js";
+import { joinPath } from "../util/joinPath.js";
 import type { MdxComponentsType } from "../util/MdxComponents.js";
 import {
   type DevPortalPlugin,
@@ -20,41 +20,6 @@ export interface ApiIdentity {
   id: string;
 }
 
-type BaseNavigationCategoryItem = {
-  label: ReactNode;
-  title?: string;
-  muted?: boolean;
-  icon?: ReactNode;
-};
-
-export type PathNavigationCategoryItem = BaseNavigationCategoryItem & {
-  path: string;
-  children?: NavigationCategoryItem[];
-};
-
-export type HrefNavigationCategoryItem = BaseNavigationCategoryItem & {
-  href: string;
-};
-
-export type NavigationCategoryItem =
-  | PathNavigationCategoryItem
-  | HrefNavigationCategoryItem;
-
-export type NavigationCategory = {
-  label: string;
-  path?: string;
-  expanded?: boolean;
-  collapsible?: boolean;
-  icon?: ReactNode;
-  children: NavigationCategoryItem[];
-};
-
-export type NavigationItem = {
-  label: string;
-  path: DevPortalPath;
-  categories?: NavigationCategory[];
-};
-
 export const queryClient = new QueryClient();
 
 export type ApiKeyCache = "api-keys";
@@ -90,7 +55,8 @@ export type ZudokuContextOptions = {
   metadata?: Metadata;
   page?: Page;
   authentication?: AuthenticationProvider;
-  navigation: NavigationItem[];
+  topNavigation?: Array<{ id: string; label: string }>;
+  sidebars?: ResolvedSidebarConfig;
   plugins?: DevPortalPlugin[];
   slotlets?: Slotlets;
   mdx?: {
@@ -100,8 +66,9 @@ export type ZudokuContextOptions = {
 };
 
 export class DevPortalContext {
-  public plugins: NonNullable<ZudokuContextOptions["plugins"]> = [];
-  public navigation: ZudokuContextOptions["navigation"];
+  public plugins: NonNullable<ZudokuContextOptions["plugins"]>;
+  public sidebars: NonNullable<ZudokuContextOptions["sidebars"]>;
+  public topNavigation: NonNullable<ZudokuContextOptions["topNavigation"]>;
   public meta: ZudokuContextOptions["metadata"];
   public page: ZudokuContextOptions["page"];
   public authentication?: ZudokuContextOptions["authentication"];
@@ -109,7 +76,8 @@ export class DevPortalContext {
 
   constructor(config: ZudokuContextOptions) {
     this.plugins = config.plugins ?? [];
-    this.navigation = config.navigation;
+    this.topNavigation = config.topNavigation ?? [];
+    this.sidebars = config.sidebars ?? {};
     this.navigationPlugins = this.plugins.filter(isNavigationPlugin);
     this.authentication = config.authentication;
     this.meta = config.metadata;
@@ -142,10 +110,10 @@ export class DevPortalContext {
     return keys.flat();
   };
 
-  getNavigation = async (path: string) => {
+  getPluginNavigation = async (path: string) => {
     const navigations = await Promise.all(
-      this.navigationPlugins.map(async (plugin) =>
-        plugin.getNavigation?.(path),
+      this.navigationPlugins.map((plugin) =>
+        plugin.getNavigation?.(joinPath(path)),
       ),
     );
 

package/src/lib/core/plugins.ts

@@ -1,15 +1,8 @@
 import { type ReactElement } from "react";
 import { NavigateFunction, type RouteObject } from "react-router-dom";
+import type { ResolvedSidebar } from "../../config/validators/ResolvedSidebarSchema.js";
 import { MdxComponentsType } from "../util/MdxComponents.js";
-import {
-  DevPortalContext,
-  type ApiIdentity,
-  type NavigationCategory,
-} from "./DevPortalContext.js";
-
-export type PluginNavigationCategory = {
-  path: string;
-} & NavigationCategory;
+import { DevPortalContext, type ApiIdentity } from "./DevPortalContext.js";
 
 export type DevPortalPlugin =
   | CommonPlugin
@@ -19,7 +12,7 @@ export type DevPortalPlugin =
 
 export interface NavigationPlugin {
   getRoutes: () => RouteObject[];
-  getNavigation?: (path: string) => Promise<PluginNavigationCategory[]>;
+  getNavigation?: (path: string) => Promise<ResolvedSidebar>;
 }
 
 export interface ApiIdentityPlugin {
@@ -27,13 +20,13 @@ export interface ApiIdentityPlugin {
 }
 
 export interface ProfileMenuPlugin {
-  getProfileMenuItems: (context: DevPortalContext) => NavigationItem[];
+  getProfileMenuItems: (context: DevPortalContext) => ProfileNavigationItem[];
 }
 
-export type NavigationItem = {
+export type ProfileNavigationItem = {
   label: string;
   path?: string;
-  children?: NavigationItem[];
+  children?: ProfileNavigationItem[];
 };
 
 export interface CommonPlugin {

package/src/lib/plugins/markdown/MdxPage.tsx

@@ -1,16 +1,17 @@
 import { useMDXComponents } from "@mdx-js/react";
 import { Helmet } from "@zudoku/react-helmet-async";
-import { useMemo, type PropsWithChildren, type ReactNode } from "react";
-import { Link, useLocation } from "react-router-dom";
+import { type PropsWithChildren } from "react";
+import { Link } from "react-router-dom";
 import { CategoryHeading } from "../../components/CategoryHeading.js";
 import { Heading } from "../../components/Heading.js";
 import { ProseClasses } from "../../components/Markdown.js";
-import { useTopNavigationItem } from "../../components/context/DevPortalProvider.js";
-import { isPathItem } from "../../components/navigation/util.js";
+import {
+  useCurrentItem,
+  usePrevNext,
+} from "../../components/navigation/utils.js";
 import type { MdxComponentsType } from "../../util/MdxComponents.js";
 import { cn } from "../../util/cn.js";
 import slugify from "../../util/slugify.js";
-import { traverseNavigation } from "../../util/traverseNavigation.js";
 import { Toc } from "./Toc.js";
 import { MarkdownPluginDefaultOptions, MDXImport } from "./index.js";
 
@@ -39,17 +40,7 @@ export const MdxPage = ({
     defaultOptions?: MarkdownPluginDefaultOptions;
   }
 >) => {
-  const navItem = useTopNavigationItem();
-  const location = useLocation();
-
-  const categoryTitle = navItem
-    ? traverseNavigation(navItem, (_node, fullPath, parentNodes) => {
-        if (fullPath === location.pathname) {
-          return parentNodes.at(0)?.label;
-        }
-      })
-    : undefined;
-
+  const categoryTitle = useCurrentItem()?.categoryLabel;
   const title = frontmatter.title;
   const category = frontmatter.category ?? categoryTitle;
   const hideToc = frontmatter.toc === false || defaultOptions?.toc === false;
@@ -65,30 +56,7 @@ export const MdxPage = ({
 
   const showToc = !hideToc && tocEntries.length > 0;
 
-  const { prev, next } = useMemo(() => {
-    let prev = { path: "", label: "" as ReactNode };
-    let next = { path: "", label: "" as ReactNode };
-    let shouldStop = false;
-
-    if (!navItem) return { prev, next };
-
-    traverseNavigation(navItem, (node, fullPath) => {
-      const item = { path: fullPath, label: node.label };
-
-      if (shouldStop && isPathItem(node) && !node.children?.length) {
-        next = item;
-        return true;
-      }
-      if (fullPath === location.pathname) {
-        shouldStop = true;
-      }
-      if (!shouldStop && isPathItem(node) && !node.children?.length) {
-        prev = item;
-      }
-    });
-
-    return { prev, next } as const;
-  }, [navItem, location.pathname]);
+  const { prev, next } = usePrevNext();
 
   return (
     <div className="xl:grid grid-cols-[--sidecar-grid-cols] gap-8 justify-between">
@@ -119,13 +87,11 @@ export const MdxPage = ({
           <>
             <hr />
             <div className="not-prose flex items-center justify-between gap-8">
-              {prev.path ? (
+              {prev ? (
                 <Link
-                  to={prev.path}
+                  to={prev.id}
                   className="flex flex-col items-stretch gap-2 flex-1 truncate border rounded px-6 py-4 text-start hover:border-primary/85 transition shadow-sm hover:shadow-md"
-                  title={
-                    typeof prev.label === "string" ? prev.label : undefined
-                  }
+                  title={prev.label}
                 >
                   <div className="text-sm text-muted-foreground">
                     ← Previous page
@@ -137,13 +103,11 @@ export const MdxPage = ({
               ) : (
                 <div className="flex-1" />
               )}
-              {next.path ? (
+              {next ? (
                 <Link
-                  to={next.path}
+                  to={next.id}
                   className="flex flex-col items-stretch gap-2 flex-1 truncate border rounded px-6 py-4 text-end hover:border-primary/85 transition shadow-sm hover:shadow-md"
-                  title={
-                    typeof next.label === "string" ? next.label : undefined
-                  }
+                  title={next.label}
                 >
                   <div className="text-sm text-muted-foreground">
                     Next page →