zudoku 0.3.0-dev.6 → 0.3.0-dev.61

package/src/lib/components/DevPortal.tsx

@@ -1,28 +1,33 @@
 import { MDXProvider } from "@mdx-js/react";
 import { QueryClientProvider } from "@tanstack/react-query";
-import { memo, Suspense, useEffect, useMemo } from "react";
+import { Helmet } from "@zudoku/react-helmet-async";
+import {
+  Fragment,
+  memo,
+  type PropsWithChildren,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from "react";
+import { ErrorBoundary } from "react-error-boundary";
+import { useNavigation } from "react-router-dom";
 import {
   DevPortalContext,
   queryClient,
-  type NavigationItem,
+  ZudokuContextOptions,
 } from "../core/DevPortalContext.js";
-import { HelmetProvider } from "../core/helmet.js";
-import { type DevPortalPlugin } from "../core/plugins.js";
-
-import { AuthenticationProvider } from "../authentication/authentication.js";
-import {
-  MdxComponents,
-  type MdxComponentsType,
-} from "../util/MdxComponents.js";
+import { hasHead } from "../core/plugins.js";
+import { TopLevelError } from "../errors/TopLevelError.js";
+import { StaggeredRenderContext } from "../plugins/openapi/StaggeredRender.js";
+import { MdxComponents } from "../util/MdxComponents.js";
 import {
   ComponentsProvider,
   DEFAULT_COMPONENTS,
-  type ComponentsContextType,
 } from "./context/ComponentsContext.js";
 import { DevPortalProvider } from "./context/DevPortalProvider.js";
 import { ThemeProvider } from "./context/ThemeContext.js";
 import { ViewportAnchorProvider } from "./context/ViewportAnchorContext.js";
-import { Router } from "./Router.js";
 
 export const DevPortalSystemPaths = {
   Settings: "/settings",
@@ -32,31 +37,33 @@ export type DevPortalPath =
   | string
   | (typeof DevPortalSystemPaths)[keyof typeof DevPortalSystemPaths];
 
-export type DevPortalProps = {
-  meta?: Partial<{
-    headerTitle: string;
-    pageTitle: string;
-    description: string;
-    logo: string;
-    favicon: string;
-  }>;
-  authentication?: AuthenticationProvider;
-  navigation: NavigationItem[];
-  plugins?: DevPortalPlugin[];
-  mdxComponents?: MdxComponentsType;
-  overrides?: ComponentsContextType;
-};
-
-const DevPortalInner = (props: DevPortalProps) => {
+const DevPortalInner = ({
+  children,
+  ...props
+}: PropsWithChildren<ZudokuContextOptions>) => {
   const components = useMemo(
     () => ({ ...DEFAULT_COMPONENTS, ...props.overrides }),
     [props.overrides],
   );
 
   const mdxComponents = useMemo(
-    () => ({ ...MdxComponents, ...props.mdxComponents }),
-    [props.mdxComponents],
+    () => ({ ...MdxComponents, ...props.mdx?.components }),
+    [props.mdx?.components],
+  );
+  const { stagger } = useContext(StaggeredRenderContext);
+  const [didNavigate, setDidNavigate] = useState(false);
+  const staggeredValue = useMemo(
+    () => (didNavigate ? { stagger: true } : { stagger }),
+    [stagger, didNavigate],
   );
+  const navigation = useNavigation();
+
+  useEffect(() => {
+    if (didNavigate) {
+      return;
+    }
+    setDidNavigate(true);
+  }, [didNavigate, navigation.location]);
 
   const devPortalContext = useMemo(() => new DevPortalContext(props), [props]);
 
@@ -64,39 +71,38 @@ const DevPortalInner = (props: DevPortalProps) => {
     void devPortalContext.initialize();
   }, [devPortalContext]);
 
+  const heads = props.plugins
+    ?.filter(hasHead)
+    // eslint-disable-next-line react/no-array-index-key
+    .map((plugin, i) => <Fragment key={i}>{plugin.getHead?.()}</Fragment>);
+
   return (
     <QueryClientProvider client={queryClient}>
-      <HelmetProvider>
+      <Helmet>{heads}</Helmet>
+      <StaggeredRenderContext.Provider value={staggeredValue}>
         <DevPortalProvider value={devPortalContext}>
           <MDXProvider components={mdxComponents}>
             <ThemeProvider>
               <ComponentsProvider value={components}>
-                <ViewportAnchorProvider>
-                  <Suspense
-                    fallback={
-                      <div className="grid place-items-center h-full">
-                        Loading...
-                      </div>
-                    }
-                  >
-                    <Router
-                      plugins={[
-                        ...(props.plugins ?? []),
-                        ...(props.authentication ? [props.authentication] : []),
-                      ]}
-                    />
-                  </Suspense>
-                </ViewportAnchorProvider>
+                <ViewportAnchorProvider>{children}</ViewportAnchorProvider>
               </ComponentsProvider>
             </ThemeProvider>
           </MDXProvider>
         </DevPortalProvider>
-      </HelmetProvider>
+      </StaggeredRenderContext.Provider>
     </QueryClientProvider>
   );
 };
 
-const DevPortal = memo(DevPortalInner);
+const Inner = memo(DevPortalInner);
+
+const DevPortal = (props: ZudokuContextOptions) => {
+  return (
+    <ErrorBoundary FallbackComponent={TopLevelError}>
+      <Inner {...props} />
+    </ErrorBoundary>
+  );
+};
 DevPortal.displayName = "DevPortal";
 
 export { DevPortal };

package/src/lib/components/DeveloperHint.tsx

@@ -0,0 +1,25 @@
+import type { ReactNode } from "react";
+import { Callout } from "../ui/Callout.js";
+
+export const DeveloperHint = ({
+  children,
+  className,
+}: {
+  children: ReactNode;
+  className?: string;
+}) => {
+  // TODO: figure out a way to do that in consumer dev mode not "internal"
+  //  so this doesn't get stripped out in the build
+  if (!import.meta.env.DEV) return;
+
+  return (
+    <Callout type="caution" title="Developer hint" className={className}>
+      <div className="flex flex-col gap-2">
+        <div>{children}</div>
+        <small className="italic">
+          Note: This hint is only shown in development mode.
+        </small>
+      </div>
+    </Callout>
+  );
+};

package/src/lib/components/ErrorPage.tsx

@@ -0,0 +1,28 @@
+import type { ReactNode } from "react";
+import { Link } from "react-router-dom";
+import { CategoryHeading } from "./CategoryHeading.js";
+import { Heading } from "./Heading.js";
+import { ProseClasses } from "./Markdown.js";
+
+export const ErrorPage = ({
+  title = "An error occurred",
+  message,
+  category,
+}: {
+  title?: ReactNode;
+  message?: ReactNode;
+  category?: ReactNode;
+}) => {
+  return (
+    <div className={ProseClasses + " h-full pt-[--padding-content-top]"}>
+      {category && <CategoryHeading>{category}</CategoryHeading>}
+      {title && (
+        <Heading level={1} className="flex gap-3.5 items-center">
+          {title}
+        </Heading>
+      )}
+      <p>{message}</p>
+      <Link to="/">Go back home</Link>
+    </div>
+  );
+};

package/src/lib/components/Header.tsx

@@ -1,64 +1,125 @@
-import { MoonStarIcon, SearchIcon, SunIcon } from "lucide-react";
+import { MoonStarIcon, SunIcon } from "lucide-react";
 import { memo } from "react";
 
+import { Link } from "react-router-dom";
 import { useAuth } from "../authentication/hook.js";
+import { isProfileMenuPlugin, NavigationItem } from "../core/plugins.js";
+import { Button } from "../ui/Button.js";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuPortal,
+  DropdownMenuSeparator,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger,
+  DropdownMenuTrigger,
+} from "../ui/DropdownMenu.js";
+import { cn } from "../util/cn.js";
 import { TopNavigation } from "./TopNavigation.js";
 import { useDevPortal } from "./context/DevPortalProvider.js";
 import { useTheme } from "./context/ThemeContext.js";
 
+const RecursiveMenu = ({ item }: { item: NavigationItem }) => {
+  return item.children ? (
+    <DropdownMenuSub key={item.label}>
+      <DropdownMenuSubTrigger>{item.label}</DropdownMenuSubTrigger>
+      <DropdownMenuPortal>
+        <DropdownMenuSubContent>
+          {item.children.map((item, i) => (
+            // eslint-disable-next-line react/no-array-index-key
+            <RecursiveMenu key={i} item={item} />
+          ))}
+        </DropdownMenuSubContent>
+      </DropdownMenuPortal>
+    </DropdownMenuSub>
+  ) : (
+    <Link to={item.path ?? ""}>
+      <DropdownMenuItem key={item.label}>{item.label}</DropdownMenuItem>
+    </Link>
+  );
+};
+
 export const Header = memo(function HeaderInner() {
   const [isDark, toggleTheme] = useTheme();
   const { isAuthenticated, profile, isAuthEnabled, login, logout } = useAuth();
-  const { meta } = useDevPortal();
+  const context = useDevPortal();
+  const { page, plugins } = context;
 
   const ThemeIcon = isDark ? MoonStarIcon : SunIcon;
 
   return (
     <header className="fixed top-0 w-full z-10 bg-background/80 backdrop-blur">
       <div className="max-w-screen-2xl mx-auto">
-        <div className="grid grid-cols-[calc(var(--side-nav-width))_1fr] lg:gap-12 items-center border-b border-border px-12 h-[--top-header-height]">
+        <div className="grid grid-cols-[calc(var(--side-nav-width))_1fr] lg:gap-12 items-center border-b px-12 h-[--top-header-height]">
           <div className="flex items-center gap-3.5">
-            {meta?.logo && (
-              <img src={meta.logo} alt="My Dev Portal" className="h-10" />
+            {page?.logo && (
+              <>
+                <img
+                  src={page.logo.src.light}
+                  alt={page.logo.alt ?? page.pageTitle}
+                  style={{ width: page.logo.width }}
+                  className={cn("h-10", isDark && "hidden")}
+                  loading="lazy"
+                />
+                <img
+                  src={page.logo.src.dark}
+                  alt={page.logo.alt ?? page.pageTitle}
+                  style={{ width: page.logo.width }}
+                  className={cn("h-10", !isDark && "hidden")}
+                  loading="lazy"
+                />
+              </>
             )}
             <span className="font-bold text-2xl text-foreground/85 tracking-wide">
-              {meta?.headerTitle}
+              {page?.pageTitle}
             </span>
           </div>
           <div className="grid grid-cols-[--sidecar-grid-cols] items-center gap-8">
             <div className="w-full max-w-prose">
-              <button className="flex items-center border border-input hover:bg-accent hover:text-accent-foreground p-4 relative h-8 justify-start rounded-lg bg-background text-sm text-muted-foreground shadow-none w-40 sm:w-72">
+              {/*<button className="flex items-center border border-input hover:bg-accent hover:text-accent-foreground p-4 relative h-8 justify-start rounded-lg bg-background text-sm text-muted-foreground shadow-none w-40 sm:w-72">
                 <div className="flex items-center gap-2 flex-grow">
                   <SearchIcon size={14} />
                   Search
                 </div>
-                <kbd className="absolute right-[0.3rem] top-[0.3rem] hidden h-5 select-none items-center gap-1 rounded border border-border bg-muted px-1.5 font-mono text-[11px] font-medium opacity-100 sm:flex">
+                <kbd className="absolute right-[0.3rem] top-[0.3rem] hidden h-5 select-none items-center gap-1 rounded border bg-muted px-1.5 font-mono text-[11px] font-medium opacity-100 sm:flex">
                   ⌘K
                 </kbd>
-              </button>
+              </button>*/}
             </div>
 
-            <div className="items-center justify-self-end text-sm hidden lg:flex">
-              {isAuthEnabled && (
-                <>
-                  {isAuthenticated ? (
-                    <button
-                      className="cursor-pointer hover:bg-secondary p-1 px-2 mx-2 rounded text-nowrap"
-                      onClick={logout}
-                    >
-                      Logout {profile?.email ? `(${profile.email})` : null}
-                    </button>
-                  ) : (
-                    <button
-                      className="cursor-pointer hover:bg-secondary p-1 px-2 mx-2 rounded"
-                      onClick={login}
-                    >
-                      Login
-                    </button>
-                  )}
-                </>
+            <div className="items-center justify-self-end text-sm hidden lg:flex gap-2">
+              {isAuthEnabled && !isAuthenticated ? (
+                <Button variant="ghost" asChild>
+                  <Link to="/signin">Login</Link>
+                </Button>
+              ) : (
+                <DropdownMenu>
+                  <DropdownMenuTrigger asChild>
+                    <Button variant="ghost">
+                      {profile?.email ? `${profile.email}` : "My Account"}
+                    </Button>
+                  </DropdownMenuTrigger>
+                  <DropdownMenuContent className="w-56">
+                    <DropdownMenuLabel>My Account</DropdownMenuLabel>
+                    <DropdownMenuSeparator />
+                    {plugins
+                      .filter((p) => isProfileMenuPlugin(p))
+                      .flatMap((p) => p.getProfileMenuItems(context))
+                      .map((i) => (
+                        <RecursiveMenu key={i.label} item={i} />
+                      ))}
+                  </DropdownMenuContent>
+                </DropdownMenu>
               )}
+
               <button
+                type="button"
+                aria-label={
+                  isDark ? "Switch to light mode" : "Switch to dark mode"
+                }
                 className="cursor-pointer hover:bg-secondary p-2.5 -m-2.5 rounded-full"
                 onClick={toggleTheme}
               >

package/src/lib/components/Heading.tsx

@@ -1,7 +1,24 @@
-import { type ReactNode } from "react";
-import { cn } from "../util/cn.js";
+import React, { type ReactNode } from "react";
 import { useRegisterAnchorElement } from "./context/ViewportAnchorContext.js";
 
+import { cva, type VariantProps } from "class-variance-authority";
+
+const heading = cva("group relative", {
+  variants: {
+    level: {
+      6: "text-md",
+      5: "text-lg",
+      4: "text-xl",
+      3: "text-xl font-semibold",
+      2: "text-2xl font-bold",
+      1: "text-4xl font-extrabold",
+    },
+  },
+  defaultVariants: {
+    level: 1,
+  },
+});
+
 const getComponent = (level: number) => {
   switch (level) {
     case 1:
@@ -21,27 +38,29 @@ const getComponent = (level: number) => {
   }
 };
 
-export type HeadingProps = {
+export interface HeadingProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof heading> {
   children: ReactNode;
   className?: string;
   id?: string;
   level?: 1 | 2 | 3 | 4 | 5 | 6;
   registerSidebarAnchor?: boolean;
-};
+}
 
-export const Heading = ({
+export const Heading: React.FC<HeadingProps> = ({
   level,
   children,
   id,
   className,
   registerSidebarAnchor,
-}: HeadingProps) => {
+}) => {
   const Component = getComponent(level ?? 1);
   const { ref } = useRegisterAnchorElement();
 
   return (
     <Component
-      className={cn("group relative", className)}
+      className={heading({ className, level })}
       ref={registerSidebarAnchor ? ref : undefined}
       id={id}
     >

package/src/lib/components/InlineCode.tsx

@@ -0,0 +1,19 @@
+import type { ReactNode } from "react";
+import { cn } from "../util/cn.js";
+
+export const InlineCode = ({
+  className,
+  children,
+}: {
+  className?: string;
+  children: ReactNode;
+}) => (
+  <code
+    className={cn(
+      className,
+      "font-mono border p-1 py-0.5 rounded bg-border/50 dark:bg-border/70 whitespace-nowrap",
+    )}
+  >
+    {children}
+  </code>
+);

package/src/lib/components/Layout.tsx

@@ -1,6 +1,7 @@
+import { Helmet } from "@zudoku/react-helmet-async";
 import { Suspense, useEffect, useRef, type ReactNode } from "react";
 import { Outlet, useLocation } from "react-router-dom";
-import { Helmet } from "../core/helmet.js";
+import { cn } from "../util/cn.js";
 import { useScrollToAnchor } from "../util/useScrollToAnchor.js";
 import { useScrollToTop } from "../util/useScrollToTop.js";
 import { useDevPortal } from "./context/DevPortalProvider.js";
@@ -29,8 +30,7 @@ export const Layout = ({ children }: { children?: ReactNode }) => {
 
   return (
     <>
-      <Helmet titleTemplate={meta?.pageTitle}>
-        <title>Home</title>
+      <Helmet titleTemplate={meta?.title}>
         {meta?.description && (
           <meta name="description" content={meta.description} />
         )}
@@ -48,10 +48,12 @@ export const Layout = ({ children }: { children?: ReactNode }) => {
         >
           <SideNavigation />
           <main
-            className="dark:border-white/10 translate-x-0 h-full
-          lg:overflow-visible
-          lg:peer-data-[navigation=true]:w-[calc(100%-var(--side-nav-width))]
-          lg:peer-data-[navigation=true]:translate-x-[--side-nav-width] peer-data-[navigation=true]:pl-12"
+            className={cn(
+              "dark:border-white/10 translate-x-0 h-full",
+              "lg:overflow-visible",
+              "lg:peer-data-[navigation=true]:w-[calc(100%-var(--side-nav-width))]",
+              "lg:peer-data-[navigation=true]:translate-x-[--side-nav-width] lg:peer-data-[navigation=true]:pl-12",
+            )}
           >
             {children ?? <Outlet />}
           </main>

package/src/lib/components/NotFoundPage.tsx

@@ -0,0 +1,33 @@
+import { UnlinkIcon } from "lucide-react";
+import { Link, useParams } from "react-router-dom";
+import { CategoryHeading } from "./CategoryHeading.js";
+import { DeveloperHint } from "./DeveloperHint.js";
+import { Heading } from "./Heading.js";
+import { ProseClasses } from "./Markdown.js";
+
+export const NotFoundPage = () => {
+  const params = useParams();
+
+  return (
+    <div className={ProseClasses + " h-full pt-[--padding-content-top]"}>
+      <CategoryHeading>404</CategoryHeading>
+      <Heading level={1} className="flex gap-3.5 items-center">
+        Page not found
+        <UnlinkIcon size={24} />
+      </Heading>
+      <DeveloperHint>
+        Start by adding a file at{" "}
+        <code>
+          {"{PROJECT_ROOT}"}/{params["*"]}.mdx
+        </code>{" "}
+        and add some content to make this error go away.
+      </DeveloperHint>
+      <p>
+        It seems that the page you are looking for does not exist or may have
+        been moved. Please check the URL for any typos or use the navigation
+        menu to find the correct page.
+      </p>
+      <Link to="/">Go back home</Link>
+    </div>
+  );
+};

package/src/lib/components/SyntaxHighlight.tsx

@@ -7,21 +7,23 @@ import {
 
 import { CheckIcon, CopyIcon } from "lucide-react";
 
-if (!import.meta.env.SSR) {
-  globalThis.Prism = Prism;
-  // @ts-expect-error This is untyped
-  import("prismjs/components/prism-bash.min.js");
-  // @ts-expect-error This is untyped
-  import("prismjs/components/prism-ruby.min.js");
-  // @ts-expect-error This is untyped
-  import("prismjs/components/prism-markup-templating.js");
-  // @ts-expect-error This is untyped
-  import("prismjs/components/prism-php.min.js");
-  // @ts-expect-error This is untyped
-  import("prismjs/components/prism-json.min.js");
-  // @ts-expect-error This is untyped
-  import("prismjs/components/prism-java.min.js");
-}
+globalThis.Prism = Prism;
+// @ts-expect-error This is untyped
+import("prismjs/components/prism-bash.min.js");
+// @ts-expect-error This is untyped
+import("prismjs/components/prism-ruby.min.js");
+// @ts-expect-error This is untyped
+import("prismjs/components/prism-markup-templating.js");
+// @ts-expect-error This is untyped
+import("prismjs/components/prism-php.min.js");
+// @ts-expect-error This is untyped
+import("prismjs/components/prism-json.min.js");
+// @ts-expect-error This is untyped
+import("prismjs/components/prism-java.min.js");
+// @ts-expect-error This is untyped
+import("prismjs/components/prism-csharp.min.js");
+// @ts-expect-error This is untyped
+import("prismjs/components/prism-objectivec.min.js");
 
 import { useState } from "react";
 import { cn } from "../util/cn.js";
@@ -33,10 +35,12 @@ type SyntaxHighlightProps = {
   wrapLines?: boolean;
   copyable?: boolean;
   showLanguageIndicator?: boolean;
-} & Omit<HighlightProps, "children">;
+  language?: string;
+} & Omit<HighlightProps, "children" | "language">;
 
 export const SyntaxHighlight = ({
   copyable = true,
+  language = "plain",
   ...props
 }: SyntaxHighlightProps) => {
   const [isDark] = useTheme();
@@ -47,7 +51,11 @@ export const SyntaxHighlight = ({
   }
 
   return (
-    <Highlight theme={isDark ? themes.vsDark : themes.github} {...props}>
+    <Highlight
+      theme={isDark ? themes.vsDark : themes.github}
+      language={language}
+      {...props}
+    >
       {({ className, style, tokens, getLineProps, getTokenProps }) => (
         <pre
           className={cn(
@@ -84,7 +92,7 @@ export const SyntaxHighlight = ({
           )}
           {props.showLanguageIndicator && (
             <span className="absolute top-1.5 right-3 text-[11px] font-mono text-muted-foreground transition group-hover:opacity-0">
-              {props.language}
+              {language}
             </span>
           )}
           {tokens.map((line, i) => (

package/src/lib/components/TopNavigation.tsx

@@ -6,8 +6,13 @@ import { useDevPortal } from "./context/DevPortalProvider.js";
 export const TopNavigation = () => {
   const { navigation } = useDevPortal();
 
+  // Hide tope nav if there is only one item
+  if (navigation.length <= 1) {
+    return null;
+  }
+
   return (
-    <nav className="border-b border-border text-sm px-12 h-[--top-nav-height]">
+    <nav className="border-b text-sm px-12 h-[--top-nav-height]">
       <ul className="flex flex-row items-center gap-8">
         {navigation.map((item) => (
           <li key={item.label}>

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

@@ -1,7 +1,8 @@
-import { useSuspenseQuery } from "@tanstack/react-query";
+import { useQuery, useSuspenseQuery } from "@tanstack/react-query";
 import { createContext, useContext } from "react";
 import { matchPath, useLocation } from "react-router-dom";
 import { DevPortalContext } from "../../core/DevPortalContext.js";
+import { traverseNavigation } from "../../util/traverseNavigation.js";
 
 const DevPortalReactContext = createContext<DevPortalContext | undefined>(
   undefined,
@@ -21,7 +22,7 @@ export const useDevPortal = () => {
 
 export const useApiIdentities = () => {
   const { getApiIdentities } = useDevPortal();
-  return useSuspenseQuery({
+  return useQuery({
     queryFn: getApiIdentities,
     queryKey: ["api-identities"],
   });
@@ -31,8 +32,27 @@ export const useTopNavigationItem = () => {
   const { navigation } = useDevPortal();
   const location = useLocation();
 
-  return navigation.find((item) =>
-    matchPath({ path: item.path, end: false }, location.pathname),
+  // 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;
+      }
+    });
+
+    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),
   );
 };