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

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/api-keys/SettingsApiKeys.tsx

@@ -34,6 +34,17 @@ export const SettingsApiKeys = ({ service }: { service: ApiKeyService }) => {
     },
   });
 
+  const rollKeyMutation = useMutation({
+    mutationFn: (id: string) => {
+      if (!service.rollKey) {
+        throw new Error("rollKey not implemented");
+      }
+
+      return service.rollKey(id, context);
+    },
+    onSuccess: () => queryClient.invalidateQueries({ queryKey: ["api-keys"] }),
+  });
+
   return (
     <div className="max-w-screen-lg h-full pt-[--padding-content-top] pb-[--padding-content-bottom]">
       <Slotlet name="api-keys-list-page" />
@@ -50,14 +61,14 @@ export const SettingsApiKeys = ({ service }: { service: ApiKeyService }) => {
       <Slotlet name="api-keys-list-page-before-keys" />
 
       {data.length === 0 ? (
-        <div className="flex flex-col justify-center gap-4 items-center h-1/2 my-8">
-          <div className="text-center">
+        <div className="flex flex-col justify-center gap-4 items-center p-8 border rounded bg-muted/30 text-muted-foreground">
+          <p className="text-center">
             No API keys created yet.
             <br />
-            Get started and create the first one now
-          </div>
+            Get started and create your first key.
+          </p>
           {service.createKey && (
-            <Button asChild>
+            <Button asChild variant="outline">
               <Link to="/settings/api-keys/new">Create API Key</Link>
             </Button>
           )}
@@ -94,7 +105,18 @@ export const SettingsApiKeys = ({ service }: { service: ApiKeyService }) => {
               </div>
               <div className="flex gap-2">
                 {service.rollKey && (
-                  <Button size="icon">
+                  <Button
+                    size="icon"
+                    title="Roll this key"
+                    variant="ghost"
+                    onClick={() => {
+                      if (!confirm("Do you want to roll this key?")) {
+                        return;
+                      }
+
+                      rollKeyMutation.mutate(key.id);
+                    }}
+                  >
                     <RotateCwIcon size={16} />
                   </Button>
                 )}
@@ -128,10 +150,9 @@ const RevealApiKey = ({ apiKey }: { apiKey: string }) => {
 
   return (
     <div className="flex gap-2 items-center text-sm w-full">
-      <input
-        className="border rounded bg-gray-100 dark:bg-gray-950 p-1 font-mono max-w-min"
-        value={revealed ? apiKey : "•".repeat(apiKey.length)}
-      />
+      <div className="border rounded bg-gray-100 dark:bg-gray-950 p-1 font-mono w-fit overflow-x-scroll h-9 items-center flex px-2">
+        {revealed ? apiKey : "•".repeat(apiKey.length)}
+      </div>
       <Button
         variant="outline"
         onClick={() => setRevealed((prev) => !prev)}

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

@@ -54,6 +54,16 @@ const createDefaultHandler = (endpoint: string): ApiKeyService => {
       const response = await fetch(request);
       invariant(response.ok, "Failed to delete API key");
     },
+    rollKey: async (id, context) => {
+      const response = await fetch(
+        await context.signRequest(
+          new Request(endpoint + `/v1/developer/api-keys/${id}/key`, {
+            method: "DELETE",
+          }),
+        ),
+      );
+      invariant(response.ok, "Failed to delete API key");
+    },
     createKey: async (apiKey, context) => {
       const request = new Request(endpoint + `/v1/developer/api-keys`, {
         method: "POST",

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 →

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

@@ -1,7 +1,4 @@
-import { Navigate, type RouteObject } from "react-router-dom";
-import { useTopNavigationItem } from "../../components/context/DevPortalProvider.js";
-import { isPathItem } from "../../components/navigation/util.js";
-import { traverseNavigation } from "../../util/traverseNavigation.js";
+import { type RouteObject } from "react-router-dom";
 
 import {
   MarkdownPluginDefaultOptions,
@@ -11,57 +8,32 @@ import {
 export const generateRoutes = (
   markdownFiles: MarkdownPluginOptions["markdownFiles"],
   defaultOptions?: MarkdownPluginDefaultOptions,
-): RouteObject[] => {
-  const routes = Object.entries(markdownFiles).flatMap(
-    ([file, importPromise]) => {
-      // @todo we can pass in the folder name and then filter the markdown files based on that path
-      const match = file.match(/pages\/(.*).mdx?$/);
-      const path = match?.at(1);
-
-      if (!path) return [];
-
-      const pathSegments = path.split("/");
-      const isIndexFile = pathSegments.at(-1) === "index";
-      const routePath = isIndexFile
-        ? pathSegments.slice(0, -1).join("/")
-        : path;
-
-      return {
-        path: routePath,
-        lazy: async () => {
-          const { MdxPage } = await import("./MdxPage.js");
-          const { default: Component, ...props } = await importPromise();
-          return {
-            element: (
-              <MdxPage
-                mdxComponent={Component}
-                {...props}
-                defaultOptions={defaultOptions}
-              />
-            ),
-          };
-        },
-      } satisfies RouteObject;
-    },
-  );
-
-  const rootRoutes: RouteObject[] = Array.from(
-    new Set(routes.map((route) => route.path.split("/").at(0))),
-  ).map((dir) => ({
-    path: `/${dir}`,
-    element: <Redirect />,
-  }));
-
-  return [...routes, ...rootRoutes];
-};
-
-const Redirect = () => {
-  const navItem = useTopNavigationItem();
-
-  if (!navItem) return null;
-
-  return traverseNavigation(navItem, (node, fullPath) => {
-    if ("children" in node || !isPathItem(node)) return;
-    return <Navigate to={fullPath} replace />;
+): RouteObject[] =>
+  Object.entries(markdownFiles).flatMap(([file, importPromise]) => {
+    // @todo we can pass in the folder name and then filter the markdown files based on that path
+    const match = file.match(/pages\/(.*).mdx?$/);
+    const path = match?.at(1);
+
+    if (!path) return [];
+
+    const pathSegments = path.split("/");
+    const isIndexFile = pathSegments.at(-1) === "index";
+    const routePath = isIndexFile ? pathSegments.slice(0, -1).join("/") : path;
+
+    return {
+      path: routePath,
+      lazy: async () => {
+        const { MdxPage } = await import("./MdxPage.js");
+        const { default: Component, ...props } = await importPromise();
+        return {
+          element: (
+            <MdxPage
+              mdxComponent={Component}
+              {...props}
+              defaultOptions={defaultOptions}
+            />
+          ),
+        };
+      },
+    } satisfies RouteObject;
   });
-};

package/src/lib/plugins/openapi/Sidecar.tsx

@@ -1,13 +1,13 @@
 import { HTTPSnippet } from "@zudoku/httpsnippet";
 import { Fragment, useMemo, useTransition } from "react";
 import { useSearchParams } from "react-router-dom";
+import { TextColorMap } from "../../components/navigation/SidebarBadge.js";
 import { SyntaxHighlight } from "../../components/SyntaxHighlight.js";
 import type { SchemaObject } from "../../oas/parser/index.js";
 import { cn } from "../../util/cn.js";
 import { ColorizedParam } from "./ColorizedParam.js";
 import { useOasConfig } from "./context.js";
 import { graphql } from "./graphql/index.js";
-import { MethodTextColorMap } from "./MethodBadge.js";
 import type { OperationListItemResult } from "./OperationList.js";
 import { PlaygroundDialogWrapper } from "./PlaygroundDialogWrapper.js";
 import { RequestBodySidecarBox } from "./RequestBodySidecarBox.js";
@@ -71,6 +71,17 @@ export const GetServerQuery = graphql(/* GraphQL */ `
 
 const context = { suspense: true };
 
+const methodToColor = {
+  get: TextColorMap.green,
+  post: TextColorMap.blue,
+  put: TextColorMap.yellow,
+  delete: TextColorMap.red,
+  patch: TextColorMap.purple,
+  options: TextColorMap.indigo,
+  head: TextColorMap.gray,
+  trace: TextColorMap.gray,
+};
+
 export const Sidecar = ({
   operation,
 }: {
@@ -83,7 +94,9 @@ export const Sidecar = ({
     context,
   });
   const methodTextColor =
-    MethodTextColorMap[operation.method as keyof typeof MethodTextColorMap];
+    methodToColor[
+      operation.method.toLocaleLowerCase() as keyof typeof methodToColor
+    ] ?? TextColorMap.gray;
 
   const [searchParams, setSearchParams] = useSearchParams();
   const [, startTransition] = useTransition();

package/src/lib/plugins/openapi/index.tsx

@@ -1,10 +1,6 @@
 import { matchPath, useRouteError, type RouteObject } from "react-router-dom";
-import {
-  type DevPortalPlugin,
-  type PluginNavigationCategory,
-} from "../../core/plugins.js";
+import { type DevPortalPlugin } from "../../core/plugins.js";
 import { graphql } from "./graphql/index.js";
-import { MethodBadge } from "./MethodBadge.js";
 import {
   Client as UrqlClient,
   cacheExchange,
@@ -14,10 +10,12 @@ import {
 import { useQuery } from "@tanstack/react-query";
 import { CirclePlayIcon, LogInIcon } from "lucide-react";
 import { createClient } from "zudoku/openapi-worker";
+import type { ResolvedSidebarItem } from "../../../config/validators/ResolvedSidebarSchema.js";
 import { useAuth } from "../../authentication/hook.js";
 import { ErrorPage } from "../../components/ErrorPage.js";
 import { SyntaxHighlight } from "../../components/SyntaxHighlight.js";
 import { Button } from "../../ui/Button.js";
+import { joinPath } from "../../util/joinPath.js";
 import { OasPluginConfig } from "./interfaces.js";
 import type { PlaygroundContentProps } from "./playground/Playground.js";
 import { PlaygroundDialog } from "./playground/PlaygroundDialog.js";
@@ -62,7 +60,7 @@ type InternalOasPluginConfig = { inMemory?: boolean };
 export const openApiPlugin = (
   config: OasPluginConfig & InternalOasPluginConfig,
 ): DevPortalPlugin => {
-  const basePath = config.path ?? "/reference";
+  const basePath = joinPath(config.navigationId ?? "/reference");
 
   const client = config.server
     ? new UrqlClient({
@@ -152,30 +150,26 @@ export const openApiPlugin = (
 
       const categories = data.schema.tags
         .filter((tag) => tag.operations.length > 0)
-        .map<PluginNavigationCategory>((tag) => ({
-          path,
+        .map<ResolvedSidebarItem>((tag) => ({
+          type: "category",
           label: tag.name ?? "",
           collapsible: false,
-          children: tag.operations.map((operation) => ({
-            path: `#${operation.slug}`,
-            muted: !!operation.deprecated,
-            title: operation.summary ?? operation.path,
-            label: (
-              <div className="flex flex-1 min-w-0 justify-between gap-2">
-                <span className="truncate">
-                  {operation.summary ?? operation.path}
-                </span>
-                <MethodBadge method={operation.method} />
-              </div>
-            ),
+          collapsed: false,
+          items: tag.operations.map((operation) => ({
+            type: "link",
+            label: operation.summary ?? operation.path,
+            href: `#${operation.slug}`,
+            badge: {
+              label: operation.method,
+              color: "green",
+            },
           })),
         }));
 
       categories.unshift({
-        path,
+        type: "link",
         label: "Overview",
-        collapsible: false,
-        children: [{ path: "#description", label: "Description" }],
+        href: "#description",
       });
 
       return categories;