zudoku 0.3.0-dev.82 → 0.3.0-dev.84

package/lib/zudoku.plugin-markdown.js.map

@@ -1 +1 @@
-{"version":3,"file":"zudoku.plugin-markdown.js","sources":["../src/lib/plugins/markdown/generateRoutes.tsx","../src/lib/plugins/markdown/index.tsx"],"sourcesContent":["import { Navigate, type RouteObject } from \"react-router-dom\";\nimport { useTopNavigationItem } from \"../../components/context/DevPortalProvider.js\";\nimport { isPathItem } from \"../../components/navigation/util.js\";\nimport { traverseNavigation } from \"../../util/traverseNavigation.js\";\n\nimport {\n  MarkdownPluginDefaultOptions,\n  MarkdownPluginOptions,\n} from \"./index.js\";\n\nexport const generateRoutes = (\n  markdownFiles: MarkdownPluginOptions[\"markdownFiles\"],\n  defaultOptions?: MarkdownPluginDefaultOptions,\n): RouteObject[] => {\n  const routes = Object.entries(markdownFiles).flatMap(\n    ([file, importPromise]) => {\n      // @todo we can pass in the folder name and then filter the markdown files based on that path\n      const match = file.match(/pages\\/(.*).mdx?$/);\n      const path = match?.at(1);\n\n      if (!path) return [];\n\n      const pathSegments = path.split(\"/\");\n      const isIndexFile = pathSegments.at(-1) === \"index\";\n      const routePath = isIndexFile\n        ? pathSegments.slice(0, -1).join(\"/\")\n        : path;\n\n      return {\n        path: routePath,\n        lazy: async () => {\n          const { MdxPage } = await import(\"./MdxPage.js\");\n          const { default: Component, ...props } = await importPromise();\n          return {\n            element: (\n              <MdxPage\n                mdxComponent={Component}\n                {...props}\n                defaultOptions={defaultOptions}\n              />\n            ),\n          };\n        },\n      } satisfies RouteObject;\n    },\n  );\n\n  const rootRoutes: RouteObject[] = Array.from(\n    new Set(routes.map((route) => route.path.split(\"/\").at(0))),\n  ).map((dir) => ({\n    path: `/${dir}`,\n    element: <Redirect />,\n  }));\n\n  return [...routes, ...rootRoutes];\n};\n\nconst Redirect = () => {\n  const navItem = useTopNavigationItem();\n\n  if (!navItem) return null;\n\n  return traverseNavigation(navItem, (node, fullPath) => {\n    if (\"children\" in node || !isPathItem(node)) return;\n    return <Navigate to={fullPath} replace />;\n  });\n};\n","import type { Toc } from \"@stefanprobst/rehype-extract-toc\";\nimport type { MDXProps } from \"mdx/types.js\";\nimport type { DevPortalPlugin } from \"../../core/plugins.js\";\nimport { generateRoutes } from \"./generateRoutes.js\";\n\nexport type MarkdownPluginOptions = {\n  markdownFiles: Record<string, () => Promise<MDXImport>>;\n  defaultOptions?: MarkdownPluginDefaultOptions;\n};\nexport type MarkdownPluginDefaultOptions = Pick<\n  Frontmatter,\n  \"toc\" | \"disablePager\"\n>;\n\nexport type Frontmatter = {\n  title?: string;\n  description?: string;\n  category?: string;\n  toc?: boolean;\n  disablePager?: boolean;\n};\n\nexport type MDXImport = {\n  tableOfContents: Toc;\n  frontmatter: Frontmatter;\n  default: (props: MDXProps) => JSX.Element;\n};\n\nexport const markdownPlugin = ({\n  markdownFiles,\n  defaultOptions,\n}: MarkdownPluginOptions): DevPortalPlugin => ({\n  getRoutes: () => generateRoutes(markdownFiles, defaultOptions),\n});\n"],"names":["generateRoutes","markdownFiles","defaultOptions","routes","file","importPromise","match","path","pathSegments","MdxPage","Component","props","jsx","rootRoutes","route","dir","Redirect","navItem","useTopNavigationItem","traverseNavigation","node","fullPath","isPathItem","Navigate","markdownPlugin"],"mappings":";;AAUa,MAAAA,IAAiB,CAC5BC,GACAC,MACkB;AAClB,QAAMC,IAAS,OAAO,QAAQF,CAAa,EAAE;AAAA,IAC3C,CAAC,CAACG,GAAMC,CAAa,MAAM;AAEnB,YAAAC,IAAQF,EAAK,MAAM,mBAAmB,GACtCG,IAAOD,KAAA,gBAAAA,EAAO,GAAG;AAEnB,UAAA,CAACC,EAAM,QAAO;AAEZ,YAAAC,IAAeD,EAAK,MAAM,GAAG;AAM5B,aAAA;AAAA,QACL,MANkBC,EAAa,GAAG,EAAE,MAAM,UAExCA,EAAa,MAAM,GAAG,EAAE,EAAE,KAAK,GAAG,IAClCD;AAAA,QAIF,MAAM,YAAY;AAChB,gBAAM,EAAE,SAAAE,EAAA,IAAY,MAAM,OAAO,uBAAc,GACzC,EAAE,SAASC,GAAW,GAAGC,EAAM,IAAI,MAAMN;AACxC,iBAAA;AAAA,YACL,SACEO,gBAAAA,EAAA;AAAA,cAACH;AAAA,cAAA;AAAA,gBACC,cAAcC;AAAA,gBACb,GAAGC;AAAA,gBACJ,gBAAAT;AAAA,cAAA;AAAA,YACF;AAAA,UAAA;AAAA,QAGN;AAAA,MAAA;AAAA,IAEJ;AAAA,EAAA,GAGIW,IAA4B,MAAM;AAAA,IACtC,IAAI,IAAIV,EAAO,IAAI,CAACW,MAAUA,EAAM,KAAK,MAAM,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAAA,EAAA,EAC1D,IAAI,CAACC,OAAS;AAAA,IACd,MAAM,IAAIA,CAAG;AAAA,IACb,+BAAUC,GAAS,EAAA;AAAA,EACnB,EAAA;AAEF,SAAO,CAAC,GAAGb,GAAQ,GAAGU,CAAU;AAClC,GAEMG,IAAW,MAAM;AACrB,QAAMC,IAAUC;AAEZ,SAACD,IAEEE,EAAmBF,GAAS,CAACG,GAAMC,MAAa;AACrD,QAAI,gBAAcD,KAAQ,CAACE,EAAWF,CAAI;AAC1C,aAAQR,gBAAAA,EAAAA,IAAAW,GAAA,EAAS,IAAIF,GAAU,SAAO,GAAC,CAAA;AAAA,EAAA,CACxC,IALoB;AAMvB,GCtCaG,IAAiB,CAAC;AAAA,EAC7B,eAAAvB;AAAA,EACA,gBAAAC;AACF,OAA+C;AAAA,EAC7C,WAAW,MAAMF,EAAeC,GAAeC,CAAc;AAC/D;"}
+{"version":3,"file":"zudoku.plugin-markdown.js","sources":["../src/lib/plugins/markdown/generateRoutes.tsx","../src/lib/plugins/markdown/index.tsx"],"sourcesContent":["import { type RouteObject } from \"react-router-dom\";\n\nimport {\n  MarkdownPluginDefaultOptions,\n  MarkdownPluginOptions,\n} from \"./index.js\";\n\nexport const generateRoutes = (\n  markdownFiles: MarkdownPluginOptions[\"markdownFiles\"],\n  defaultOptions?: MarkdownPluginDefaultOptions,\n): RouteObject[] =>\n  Object.entries(markdownFiles).flatMap(([file, importPromise]) => {\n    // @todo we can pass in the folder name and then filter the markdown files based on that path\n    const match = file.match(/pages\\/(.*).mdx?$/);\n    const path = match?.at(1);\n\n    if (!path) return [];\n\n    const pathSegments = path.split(\"/\");\n    const isIndexFile = pathSegments.at(-1) === \"index\";\n    const routePath = isIndexFile ? pathSegments.slice(0, -1).join(\"/\") : path;\n\n    return {\n      path: routePath,\n      lazy: async () => {\n        const { MdxPage } = await import(\"./MdxPage.js\");\n        const { default: Component, ...props } = await importPromise();\n        return {\n          element: (\n            <MdxPage\n              mdxComponent={Component}\n              {...props}\n              defaultOptions={defaultOptions}\n            />\n          ),\n        };\n      },\n    } satisfies RouteObject;\n  });\n","import type { Toc } from \"@stefanprobst/rehype-extract-toc\";\nimport type { MDXProps } from \"mdx/types.js\";\nimport type { DevPortalPlugin } from \"../../core/plugins.js\";\nimport { generateRoutes } from \"./generateRoutes.js\";\n\nexport type MarkdownPluginOptions = {\n  markdownFiles: Record<string, () => Promise<MDXImport>>;\n  defaultOptions?: MarkdownPluginDefaultOptions;\n};\nexport type MarkdownPluginDefaultOptions = Pick<\n  Frontmatter,\n  \"toc\" | \"disablePager\"\n>;\n\nexport type Frontmatter = {\n  title?: string;\n  description?: string;\n  category?: string;\n  toc?: boolean;\n  disablePager?: boolean;\n};\n\nexport type MDXImport = {\n  tableOfContents: Toc;\n  frontmatter: Frontmatter;\n  default: (props: MDXProps) => JSX.Element;\n};\n\nexport const markdownPlugin = ({\n  markdownFiles,\n  defaultOptions,\n}: MarkdownPluginOptions): DevPortalPlugin => ({\n  getRoutes: () => generateRoutes(markdownFiles, defaultOptions),\n});\n"],"names":["generateRoutes","markdownFiles","defaultOptions","file","importPromise","match","path","pathSegments","MdxPage","Component","props","jsx","markdownPlugin"],"mappings":";AAOO,MAAMA,IAAiB,CAC5BC,GACAC,MAEA,OAAO,QAAQD,CAAa,EAAE,QAAQ,CAAC,CAACE,GAAMC,CAAa,MAAM;AAEzD,QAAAC,IAAQF,EAAK,MAAM,mBAAmB,GACtCG,IAAOD,KAAA,gBAAAA,EAAO,GAAG;AAEnB,MAAA,CAACC,EAAM,QAAO;AAEZ,QAAAC,IAAeD,EAAK,MAAM,GAAG;AAI5B,SAAA;AAAA,IACL,MAJkBC,EAAa,GAAG,EAAE,MAAM,UACZA,EAAa,MAAM,GAAG,EAAE,EAAE,KAAK,GAAG,IAAID;AAAA,IAIpE,MAAM,YAAY;AAChB,YAAM,EAAE,SAAAE,EAAA,IAAY,MAAM,OAAO,uBAAc,GACzC,EAAE,SAASC,GAAW,GAAGC,EAAM,IAAI,MAAMN;AACxC,aAAA;AAAA,QACL,SACEO,gBAAAA,EAAA;AAAA,UAACH;AAAA,UAAA;AAAA,YACC,cAAcC;AAAA,YACb,GAAGC;AAAA,YACJ,gBAAAR;AAAA,UAAA;AAAA,QACF;AAAA,MAAA;AAAA,IAGN;AAAA,EAAA;AAEJ,CAAC,GCVUU,IAAiB,CAAC;AAAA,EAC7B,eAAAX;AAAA,EACA,gBAAAC;AACF,OAA+C;AAAA,EAC7C,WAAW,MAAMF,EAAeC,GAAeC,CAAc;AAC/D;"}

package/lib/zudoku.plugin-openapi.js

@@ -1,12 +1,14 @@
-import "./jsx-runtime-CJBdjYYx.js";
-import { o as f } from "./index-Bl6YeerK.js";
+import "./jsx-runtime-B6kdoens.js";
+import { o as l } from "./index-CgCPw6Jn.js";
 import "./urql-DrBfkb92.js";
-import "./DevPortalProvider-BWeAysxF.js";
+import "./DevPortalProvider-CTxoCHIT.js";
 import "zudoku/openapi-worker";
-import "./Combination-C442XfGG.js";
-import "./Markdown-QsZ-PHET.js";
+import "./Combination-DkycFHkm.js";
+import "./Markdown-B_Gax7at.js";
+import "./joinPath-VeNuJa7y.js";
 import "./router-BiRCp01d.js";
+import "./index-7kcHaXD6.js";
 export {
-  f as openApiPlugin
+  l as openApiPlugin
 };
 //# sourceMappingURL=zudoku.plugin-openapi.js.map

package/lib/zudoku.plugin-openapi.js.map

@@ -1 +1 @@
-{"version":3,"file":"zudoku.plugin-openapi.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;"}
+{"version":3,"file":"zudoku.plugin-openapi.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zudoku",
-  "version": "0.3.0-dev.82",
+  "version": "0.3.0-dev.84",
   "type": "module",
   "files": [
     "dist",
@@ -102,9 +102,11 @@
     "class-variance-authority": "0.7.0",
     "dotenv": "16.4.5",
     "express": "4.19.2",
+    "glob": "^11.0.0",
     "graphql": "16.9.0",
     "graphql-type-json": "0.3.2",
     "graphql-yoga": "5.2.0",
+    "gray-matter": "^4.0.3",
     "loglevel": "^1.9.1",
     "lru-cache": "10.2.0",
     "mdx": "0.3.1",
@@ -170,6 +172,7 @@
     "react-markdown": "9.0.1",
     "react-router-dom": "6.25.1",
     "rollup-plugin-visualizer": "^5.12.0",
+    "tsx": "4.16.5",
     "typescript": "5.5.3"
   },
   "peerDependencies": {

package/src/app/demo.tsx

@@ -32,14 +32,15 @@ createRoot(document.getElementById("root")!).render(
         },
         pageTitle: "Developer Portal",
       }}
-      navigation={[
+      topNavigation={[
         {
+          id: "demo",
           label: "API Reference",
-          path: "/demo",
-          categories: [],
         },
       ]}
-      plugins={[openApiPlugin({ type: "url", input: apiUrl!, path: "/demo" })]}
+      plugins={[
+        openApiPlugin({ type: "url", input: apiUrl!, navigationId: "demo" }),
+      ]}
     />
   </StrictMode>,
 );

package/src/app/main.css

@@ -137,10 +137,10 @@
     --slide-offset: -0.75rem;
     @apply overflow-hidden;
   }
-  [data-animate="true"] .CollapsibleContent[data-state="open"] {
+  .CollapsibleContent[data-state="open"] {
     animation: slideDown 300ms var(--easing);
   }
-  [data-animate="true"] .CollapsibleContent[data-state="closed"] {
+  .CollapsibleContent[data-state="closed"] {
     animation: slideUp 300ms var(--easing);
   }
 

package/src/app/main.tsx

@@ -4,6 +4,7 @@ import { configuredApiPlugins } from "virtual:zudoku-api-plugins";
 import { configuredAuthProvider } from "virtual:zudoku-auth";
 import { configuredDocsPlugins } from "virtual:zudoku-docs-plugins";
 import { configuredRedirectPlugin } from "virtual:zudoku-redirect-plugin";
+import { configuredSidebar } from "virtual:zudoku-sidebar";
 import "virtual:zudoku-theme.css";
 import { DevPortal, Layout, RouterError } from "zudoku/components";
 import { isNavigationPlugin } from "zudoku/internal";
@@ -35,8 +36,9 @@ export const convertZudokuConfigToOptions = (
       title: "%s | Developer Portal",
       ...config.metadata,
     },
+    sidebars: configuredSidebar,
+    topNavigation: config.topNavigation,
     mdx: config.mdx,
-    navigation: config.navigation ?? [],
     authentication: configuredAuthProvider,
     plugins: [
       ...configuredDocsPlugins,

package/src/app/standalone.tsx

@@ -38,14 +38,15 @@ createRoot(root).render(
         // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
         pageTitle: pageTitle ?? "Developer Portal",
       }}
-      navigation={[
+      topNavigation={[
         {
+          id: "demo",
           label: "API Reference",
-          path: "/",
-          categories: [],
         },
       ]}
-      plugins={[openApiPlugin({ type: "url", input: apiUrl!, path: "/" })]}
+      plugins={[
+        openApiPlugin({ type: "url", input: apiUrl!, navigationId: "/" }),
+      ]}
     />
   </StrictMode>,
 );

package/src/lib/components/DevPortal.tsx

@@ -28,7 +28,7 @@ import {
   DEFAULT_COMPONENTS,
 } from "./context/ComponentsContext.js";
 import { DevPortalProvider } from "./context/DevPortalProvider.js";
-import { ThemeProvider } from "./context/ThemeContext.js";
+import { ThemeProvider } from "./context/ThemeProvider.js";
 import { ViewportAnchorProvider } from "./context/ViewportAnchorContext.js";
 import { SlotletProvider } from "./SlotletProvider.js";
 

package/src/lib/components/Header.tsx

@@ -3,7 +3,7 @@ import { memo } from "react";
 
 import { Link, useLocation } from "react-router-dom";
 import { useAuth } from "../authentication/hook.js";
-import { isProfileMenuPlugin, NavigationItem } from "../core/plugins.js";
+import { isProfileMenuPlugin, ProfileNavigationItem } from "../core/plugins.js";
 import { Button } from "../ui/Button.js";
 import {
   DropdownMenu,
@@ -22,7 +22,7 @@ import { TopNavigation } from "./TopNavigation.js";
 import { useDevPortal } from "./context/DevPortalProvider.js";
 import { useTheme } from "./context/ThemeContext.js";
 
-const RecursiveMenu = ({ item }: { item: NavigationItem }) => {
+const RecursiveMenu = ({ item }: { item: ProfileNavigationItem }) => {
   return item.children ? (
     <DropdownMenuSub key={item.label}>
       <DropdownMenuSubTrigger>{item.label}</DropdownMenuSubTrigger>

package/src/lib/components/Layout.tsx

@@ -7,7 +7,7 @@ import { useScrollToTop } from "../util/useScrollToTop.js";
 import { useDevPortal } from "./context/DevPortalProvider.js";
 import { useViewportAnchor } from "./context/ViewportAnchorContext.js";
 import { Header } from "./Header.js";
-import { SideNavigation } from "./navigation/SideNavigation.js";
+import { Sidebar } from "./navigation/Sidebar.js";
 import { Slotlet } from "./SlotletProvider.js";
 import { Spinner } from "./Spinner.js";
 
@@ -47,7 +47,7 @@ export const Layout = ({ children }: { children?: ReactNode }) => {
             </div>
           }
         >
-          <SideNavigation />
+          <Sidebar />
           <main
             className={cn(
               "dark:border-white/10 translate-x-0 h-full",

package/src/lib/components/TopNavigation.tsx

@@ -4,17 +4,17 @@ import { NavLink } from "react-router-dom";
 import { useDevPortal } from "./context/DevPortalProvider.js";
 
 export const TopNavigation = () => {
-  const { navigation } = useDevPortal();
+  const { topNavigation } = useDevPortal();
 
-  // Hide tope nav if there is only one item
-  if (navigation.length <= 1) {
+  // Hide top nav if there is only one item
+  if (topNavigation.length <= 1) {
     return null;
   }
 
   return (
     <nav className="border-b text-sm px-12 h-[--top-nav-height]">
       <ul className="flex flex-row items-center gap-8">
-        {navigation.map((item) => (
+        {topNavigation.map((item) => (
           <li key={item.label}>
             <NavLink
               className={({ isActive }) =>
@@ -25,7 +25,7 @@ export const TopNavigation = () => {
                     : "border-transparent text-foreground/75 hover:text-foreground hover:border-accent-foreground/25",
                 )
               }
-              to={item.path}
+              to={item.id}
             >
               {item.label}
             </NavLink>

package/src/lib/components/context/DevPortalProvider.ts

@@ -1,8 +1,7 @@
 import { useQuery, useSuspenseQuery } from "@tanstack/react-query";
 import { createContext, useContext } from "react";
-import { matchPath, useLocation } from "react-router-dom";
+import { useLocation } from "react-router-dom";
 import { DevPortalContext } from "../../core/DevPortalContext.js";
-import { traverseNavigation } from "../../util/traverseNavigation.js";
 
 const DevPortalReactContext = createContext<DevPortalContext | undefined>(
   undefined,
@@ -29,43 +28,27 @@ export const useApiIdentities = () => {
 };
 
 export const useTopNavigationItem = () => {
-  const { navigation } = useDevPortal();
+  const { topNavigation } = useDevPortal();
   const location = useLocation();
 
-  // The `/` path needs this logic because it would always match:
-  // Only if a leaf node actually matches the current path it is active
-  for (const item of navigation) {
-    const foundNavItem = traverseNavigation(item, (_node, fullPath) => {
-      if (location.pathname === fullPath) {
-        return item;
-      }
-    });
+  const firstPart = location.pathname.split("/").at(1);
+  if (!firstPart) return;
 
-    if (foundNavItem) {
-      return foundNavItem;
-    }
-  }
-  if (location.pathname === "/") {
-    return navigation.find((item) => item.path === "/");
-  }
-
-  return navigation.find(
-    (item) =>
-      item.path !== "/" &&
-      matchPath({ path: item.path, end: false }, location.pathname),
-  );
+  return topNavigation.find((item) => item.id === firstPart);
 };
 
 export const useNavigation = () => {
-  const { getNavigation } = useDevPortal();
+  const { getPluginNavigation, sidebars } = useDevPortal();
   const navItem = useTopNavigationItem();
-
-  const path = navItem?.path ?? "";
+  const path = navItem?.id;
+  const currentSidebar = path ? sidebars[path] ?? [] : [];
 
   return useSuspenseQuery({
     queryFn: async () => {
+      const pluginSidebar = path ? await getPluginNavigation(path) : [];
+
       return {
-        items: [...(navItem?.categories ?? []), ...(await getNavigation(path))],
+        items: [...currentSidebar, ...pluginSidebar],
         currentTopNavItem: navItem,
       };
     },

package/src/lib/components/context/ThemeContext.tsx

@@ -1,46 +1,8 @@
-import {
-  createContext,
-  type ReactNode,
-  useCallback,
-  useContext,
-  useEffect,
-  useState,
-} from "react";
+import { createContext, useContext } from "react";
 
-const ThemeContext = createContext<readonly [boolean, () => void]>([
+export const ThemeContext = createContext<readonly [boolean, () => void]>([
   false,
   () => {},
 ]);
 
-export const useTheme = () => {
-  const context = useContext(ThemeContext);
-  if (!context) {
-    throw new Error("useTheme must be used within a ThemeProvider");
-  }
-  return context;
-};
-
-export const ThemeProvider = (props: { children: ReactNode }) => {
-  const [dark, setDark] = useState(false);
-
-  // On mount, read the preferred theme from the persistence
-  useEffect(() => {
-    const theme = localStorage.getItem("theme");
-    const prefersDark = window.matchMedia("(prefers-color-scheme: dark)");
-    const isDark = theme === "dark" || (!theme && prefersDark.matches);
-
-    setDark(isDark);
-  }, [dark]);
-
-  // To toggle between dark and light modes
-  const toggle = useCallback(() => {
-    const toggled = !dark;
-    document.documentElement.classList.toggle("dark", toggled);
-    localStorage.setItem("theme", toggled ? "dark" : "light");
-    setDark(toggled);
-  }, [dark]);
-
-  const value = [dark, toggle] as const;
-
-  return <ThemeContext.Provider value={value} {...props} />;
-};
+export const useTheme = () => useContext(ThemeContext);

package/src/lib/components/context/ThemeProvider.tsx

@@ -0,0 +1,27 @@
+import { ReactNode, useCallback, useEffect, useState } from "react";
+import { ThemeContext } from "./ThemeContext.js";
+
+export const ThemeProvider = (props: { children: ReactNode }) => {
+  const [dark, setDark] = useState(false);
+
+  // On mount, read the preferred theme from the persistence
+  useEffect(() => {
+    const theme = localStorage.getItem("theme");
+    const prefersDark = window.matchMedia("(prefers-color-scheme: dark)");
+    const isDark = theme === "dark" || (!theme && prefersDark.matches);
+
+    setDark(isDark);
+  }, [dark]);
+
+  // To toggle between dark and light modes
+  const toggle = useCallback(() => {
+    const toggled = !dark;
+    document.documentElement.classList.toggle("dark", toggled);
+    localStorage.setItem("theme", toggled ? "dark" : "light");
+    setDark(toggled);
+  }, [dark]);
+
+  const value = [dark, toggle] as const;
+
+  return <ThemeContext.Provider value={value} {...props} />;
+};

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

@@ -2,23 +2,23 @@ import { useRef } from "react";
 
 import { useNavigation } from "../context/DevPortalProvider.js";
 import { Slotlet } from "../SlotletProvider.js";
-import { SideNavigationCategory } from "./SideNavigationCategory.js";
-import { SideNavigationWrapper } from "./SideNavigationWrapper.js";
+import { SidebarItem } from "./SidebarItem.js";
+import { SidebarWrapper } from "./SidebarWrapper.js";
 
-export const SideNavigation = () => {
+export const Sidebar = () => {
   const navRef = useRef<HTMLDivElement | null>(null);
   const navigation = useNavigation();
 
   return (
-    <SideNavigationWrapper
+    <SidebarWrapper
       ref={navRef}
       pushMainContent={navigation.data.items.length > 0}
     >
       <Slotlet name="zudoku-before-navigation" />
-      {navigation.data.items.map((category) => (
-        <SideNavigationCategory key={category.label} category={category} />
+      {navigation.data.items.map((item) => (
+        <SidebarItem key={item.label} item={item} />
       ))}
       <Slotlet name="zudoku-after-navigation" />
-    </SideNavigationWrapper>
+    </SidebarWrapper>
   );
 };

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) {