zudoku 0.0.0-fed343e → 0.0.0-feda542

package/src/lib/components/Zudoku.tsx

@@ -0,0 +1,121 @@
+import { MDXProvider } from "@mdx-js/react";
+import { useQueryClient } from "@tanstack/react-query";
+import { Helmet } from "@zudoku/react-helmet-async";
+import { ThemeProvider } from "next-themes";
+import {
+  memo,
+  type PropsWithChildren,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from "react";
+import { ErrorBoundary } from "react-error-boundary";
+import { Outlet, useLocation, useNavigation } from "react-router";
+import { hasHead, isMdxProviderPlugin } from "../core/plugins.js";
+import {
+  ZudokuContext,
+  type ZudokuContextOptions,
+} from "../core/ZudokuContext.js";
+import { TopLevelError } from "../errors/TopLevelError.js";
+import { StaggeredRenderContext } from "../plugins/openapi/StaggeredRender.js";
+import { MdxComponents } from "../util/MdxComponents.js";
+import "../util/requestIdleCallbackPolyfill.js";
+import {
+  ComponentsProvider,
+  DEFAULT_COMPONENTS,
+} from "./context/ComponentsContext.js";
+import { RouterEventsEmitter } from "./context/RouterEventsEmitter.js";
+import { ViewportAnchorProvider } from "./context/ViewportAnchorContext.js";
+import { ZudokuProvider } from "./context/ZudokuProvider.js";
+import { SlotletProvider } from "./SlotletProvider.js";
+
+let zudokuContext: ZudokuContext | undefined;
+
+const ZudokoInner = memo(
+  ({ children, ...props }: PropsWithChildren<ZudokuContextOptions>) => {
+    const components = useMemo(
+      () => ({ ...DEFAULT_COMPONENTS, ...props.overrides }),
+      [props.overrides],
+    );
+
+    const location = useLocation();
+    const mdxComponents = useMemo(() => {
+      const componentsFromPlugins = (props.plugins ?? [])
+        .filter(isMdxProviderPlugin)
+        .flatMap((plugin) =>
+          plugin.getMdxComponents ? [plugin.getMdxComponents()] : [],
+        );
+
+      return {
+        ...componentsFromPlugins.reduce(
+          (acc, curr) => ({ ...acc, ...curr }),
+          {},
+        ),
+        ...MdxComponents,
+        ...props.mdx?.components,
+      };
+    }, [props.mdx?.components, props.plugins]);
+    const { stagger } = useContext(StaggeredRenderContext);
+    const [didNavigate, setDidNavigate] = useState(false);
+    const staggeredValue = useMemo(
+      () => (didNavigate ? { stagger: true } : { stagger }),
+      [stagger, didNavigate],
+    );
+    const navigation = useNavigation();
+    const queryClient = useQueryClient();
+
+    useEffect(() => {
+      if (didNavigate) {
+        return;
+      }
+      setDidNavigate(true);
+    }, [didNavigate, navigation.location]);
+
+    if (!zudokuContext) {
+      zudokuContext = new ZudokuContext(props, queryClient);
+    }
+
+    const heads = props.plugins
+      ?.flatMap((plugin) =>
+        hasHead(plugin) ? (plugin.getHead?.({ location }) ?? []) : [],
+      )
+      // eslint-disable-next-line react/no-array-index-key
+      .map((entry, i) => <Helmet key={i}>{entry}</Helmet>);
+
+    return (
+      <>
+        {heads}
+        <StaggeredRenderContext.Provider value={staggeredValue}>
+          <ZudokuProvider context={zudokuContext}>
+            <RouterEventsEmitter />
+            <MDXProvider components={mdxComponents}>
+              <ThemeProvider attribute="class" disableTransitionOnChange>
+                <ComponentsProvider value={components}>
+                  <SlotletProvider slotlets={props.slotlets}>
+                    <ViewportAnchorProvider>
+                      {children ?? <Outlet />}
+                    </ViewportAnchorProvider>
+                  </SlotletProvider>
+                </ComponentsProvider>
+              </ThemeProvider>
+            </MDXProvider>
+          </ZudokuProvider>
+        </StaggeredRenderContext.Provider>
+      </>
+    );
+  },
+);
+
+ZudokoInner.displayName = "ZudokoInner";
+
+const Zudoku = (props: ZudokuContextOptions) => {
+  return (
+    <ErrorBoundary FallbackComponent={TopLevelError}>
+      <ZudokoInner {...props} />
+    </ErrorBoundary>
+  );
+};
+Zudoku.displayName = "Zudoku";
+
+export { Zudoku };

package/src/lib/components/cache.ts

@@ -0,0 +1,23 @@
+import { useQueryClient } from "@tanstack/react-query";
+
+export const CACHE_KEYS = Object.freeze({
+  API_IDENTITIES: ["api-identities"],
+});
+
+export const useCache = () => {
+  const queryClient = useQueryClient();
+
+  return {
+    invalidateCache: async (key: keyof typeof CACHE_KEYS) => {
+      await queryClient.invalidateQueries({ queryKey: CACHE_KEYS[key] });
+    },
+  };
+};
+
+/**
+ * If a query has this key in its queryKey, it will not put its result in the dehydrated state in the SSR.
+ *
+ * This is useful if the query should only be suspended and not included in the initial HTML response.
+ * (e.g. too large in size, or not needed for the initial page load)
+ */
+export const NO_DEHYDRATE = "no-dehydrate";

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

@@ -0,0 +1,3 @@
+import { createContext } from "react";
+
+export const BypassProtectedRoutesContext = createContext(false);

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

@@ -0,0 +1,19 @@
+import { useEffect, useRef } from "react";
+import { useLocation, type Location } from "react-router";
+import { useZudoku } from "./ZudokuContext.js";
+
+export const RouterEventsEmitter = () => {
+  const location = useLocation();
+  const zudoku = useZudoku();
+  const previousLocation = useRef<Location | undefined>(undefined);
+
+  useEffect(() => {
+    zudoku.emitEvent("location", {
+      from: previousLocation.current,
+      to: location,
+    });
+    previousLocation.current = location;
+  }, [zudoku, location]);
+
+  return null;
+};

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

@@ -1,5 +1,4 @@
 import {
-  type ReactNode,
   createContext,
   useCallback,
   useContext,
@@ -7,6 +6,7 @@ import {
   useMemo,
   useRef,
   useState,
+  type PropsWithChildren,
 } from "react";
 
 type AnchorContextType = {
@@ -55,14 +55,11 @@ export const useRegisterAnchorElement = () => {
   return { ref: setRef };
 };
 
-export const ViewportAnchorProvider = ({
-  children,
-}: {
-  children: ReactNode;
-}) => {
+export const ViewportAnchorProvider = ({ children }: PropsWithChildren) => {
   const [activeAnchor, setActiveAnchor] = useState("");
   const observerRef = useRef<IntersectionObserver | null>(null);
   const registeredElements = useRef(new Set<HTMLElement>());
+  const pendingElements = useRef(new Set<HTMLElement>());
 
   useEffect(() => {
     observerRef.current = new IntersectionObserver(
@@ -74,13 +71,18 @@ export const ViewportAnchorProvider = ({
         }
       },
       {
-        // 115px is the height of the sticky header
-        // see --header-height in `main.css`
-        rootMargin: "115px 0px -80% 0px",
+        rootMargin: "0px 0px -80% 0px",
         threshold: 0.75,
       },
     );
 
+    // Process any elements that tried to register before observer was ready
+    pendingElements.current.forEach((element) => {
+      registeredElements.current.add(element);
+      observerRef.current?.observe(element);
+    });
+    pendingElements.current.clear();
+
     return () => observerRef.current?.disconnect();
   }, []);
 
@@ -92,14 +94,11 @@ export const ViewportAnchorProvider = ({
         window.innerHeight + window.scrollY >= document.body.scrollHeight;
 
       if (hasReachedTop) {
-        // reset the active anchor when we reach the top
         setActiveAnchor("");
       } else if (hasReachedBottom) {
-        requestIdleCallback(() => {
-          // set the last anchor when we reach the bottom
-          const lastItem = Array.from(elements).pop();
-          setActiveAnchor(lastItem?.id ?? "");
-        });
+        const lastItem = Array.from(elements).pop();
+        const lastId = lastItem?.id ?? "";
+        setActiveAnchor(lastId);
       }
     };
 
@@ -114,14 +113,22 @@ export const ViewportAnchorProvider = ({
   const observeFns = useMemo(() => {
     return {
       observe: (element: HTMLElement | null) => {
-        if (!element || !observerRef.current) return;
+        if (!element) return;
+
+        if (!observerRef.current) {
+          pendingElements.current.add(element);
+          return;
+        }
+
         registeredElements.current.add(element);
         observerRef.current.observe(element);
       },
       unobserve: (element: HTMLElement | null) => {
-        if (!element || !observerRef.current) return;
+        if (!element) return;
+
+        pendingElements.current.delete(element);
         registeredElements.current.delete(element);
-        observerRef.current.unobserve(element);
+        observerRef.current?.unobserve(element);
       },
     };
   }, []);
@@ -132,8 +139,6 @@ export const ViewportAnchorProvider = ({
   );
 
   return (
-    <ViewportAnchorContext.Provider value={value}>
-      {children}
-    </ViewportAnchorContext.Provider>
+    <ViewportAnchorContext value={value}>{children}</ViewportAnchorContext>
   );
 };

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

@@ -1,9 +1,13 @@
 import { useQuery, useSuspenseQuery } from "@tanstack/react-query";
 import { createContext, useContext } from "react";
-import { useLocation } from "react-router-dom";
-import { DevPortalContext } from "../../core/DevPortalContext.js";
+import { matchPath, useLocation } from "react-router";
+import { useAuth } from "../../authentication/hook.js";
+import type { ZudokuContext } from "../../core/ZudokuContext.js";
+import { joinUrl } from "../../util/joinUrl.js";
+import { CACHE_KEYS, NO_DEHYDRATE } from "../cache.js";
+import { traverseSidebar } from "../navigation/utils.js";
 
-export const ZudokuReactContext = createContext<DevPortalContext | undefined>(
+export const ZudokuReactContext = createContext<ZudokuContext | undefined>(
   undefined,
 );
 
@@ -11,7 +15,7 @@ export const useZudoku = () => {
   const context = useContext(ZudokuReactContext);
 
   if (!context) {
-    throw new Error("useDevPortal must be used within a DevPortalProvider.");
+    throw new Error("useZudoku must be used within a ZudokuProvider.");
   }
 
   return context;
@@ -19,40 +23,61 @@ export const useZudoku = () => {
 
 export const useApiIdentities = () => {
   const { getApiIdentities } = useZudoku();
+
   return useQuery({
     queryFn: getApiIdentities,
-    queryKey: ["api-identities"],
+    queryKey: CACHE_KEYS.API_IDENTITIES,
   });
 };
 
-export const useTopNavigationItem = () => {
-  const { topNavigation } = useZudoku();
+export const useCurrentNavigation = () => {
+  const { getPluginSidebar, sidebars, topNavigation, options } = useZudoku();
   const location = useLocation();
+  const auth = useAuth();
 
-  const firstPart = location.pathname.split("/").at(1);
-  if (!firstPart) return;
+  const isProtectedRoute = options.protectedRoutes?.some((route) =>
+    matchPath(route, location.pathname),
+  );
 
-  return topNavigation.find((item) => item.id === firstPart);
-};
+  let currentSidebarItem = Object.entries(sidebars).find(([, sidebar]) => {
+    return traverseSidebar(sidebar, (item) => {
+      const itemId =
+        item.type === "doc"
+          ? joinUrl(item.id)
+          : item.type === "category" && item.link
+            ? joinUrl(item.link.id)
+            : undefined;
 
-export const useNavigation = () => {
-  const { getPluginSidebar, sidebars } = useZudoku();
-  const navItem = useTopNavigationItem();
-  const path = navItem?.id;
-  const currentSidebar = path ? (sidebars[path] ?? []) : [];
-  const location = useLocation();
+      if (itemId === location.pathname) {
+        return item;
+      }
+    });
+  });
+  const currentTopNavItem =
+    topNavigation.find((t) => t.id === currentSidebarItem?.[0]) ??
+    topNavigation.find((item) => matchPath(item.id, location.pathname));
 
-  return useSuspenseQuery({
-    queryFn: async () => {
-      const pluginSidebar = path
-        ? await getPluginSidebar(path)
-        : await getPluginSidebar(location.pathname);
-
-      return {
-        items: [...currentSidebar, ...pluginSidebar],
-        currentTopNavItem: navItem,
-      };
-    },
-    queryKey: ["navigation", path],
+  if (
+    currentTopNavItem &&
+    !currentSidebarItem &&
+    currentTopNavItem.id in sidebars
+  ) {
+    currentSidebarItem = ["", sidebars[currentTopNavItem.id]!];
+  }
+
+  const { data } = useSuspenseQuery({
+    queryFn: () => getPluginSidebar(location.pathname),
+    // We just want to suspend here and don't store in SSR dehydrated state
+    queryKey: ["plugin-sidebar", NO_DEHYDRATE, location.pathname],
   });
+
+  const hideSidebar =
+    auth.isAuthEnabled && !auth.isAuthenticated && isProtectedRoute;
+
+  return {
+    sidebar: hideSidebar
+      ? []
+      : [...(currentSidebarItem ? currentSidebarItem[1] : []), ...data],
+    topNavItem: currentTopNavItem,
+  };
 };

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

@@ -1,12 +1,12 @@
 import { useSuspenseQuery } from "@tanstack/react-query";
 import type { PropsWithChildren } from "react";
-import { DevPortalContext } from "../../core/DevPortalContext.js";
+import { ZudokuContext } from "../../core/ZudokuContext.js";
 import { ZudokuReactContext } from "./ZudokuContext.js";
 
 export const ZudokuProvider = ({
   children,
   context,
-}: PropsWithChildren<{ context: DevPortalContext }>) => {
+}: PropsWithChildren<{ context: ZudokuContext }>) => {
   useSuspenseQuery({
     queryFn: async () => {
       await context.initialize();

package/src/lib/components/index.ts

@@ -1,6 +1,9 @@
 import { useMDXComponents as useMDXComponentsImport } from "@mdx-js/react";
 import { Helmet } from "@zudoku/react-helmet-async";
-import { Link as LinkImport } from "react-router-dom";
+import { useTheme as useThemeImport } from "next-themes";
+import { Link as LinkImport } from "react-router";
+import { useAuth as useAuthImport } from "../authentication/hook.js";
+import { RouteGuard as RouteGuardImport } from "../core/RouteGuard.js";
 import { RouterError as RouterErrorImport } from "../errors/RouterError.js";
 import { ServerError as ServerErrorImport } from "../errors/ServerError.js";
 import { Button as ButtonImport } from "../ui/Button.js";
@@ -9,17 +12,39 @@ import {
   Bootstrap as BootstrapImport,
   BootstrapStatic as BootstrapStaticImport,
 } from "./Bootstrap.js";
-import { DevPortal as DevPortalImport } from "./DevPortal.js";
+import {
+  CACHE_KEYS as CACHE_KEYS_IMPORT,
+  useCache as useCacheImport,
+} from "./cache.js";
+import { ClientOnly as ClientOnlyImport } from "./ClientOnly.js";
+import { useZudoku as useZudokuImport } from "./context/ZudokuContext.js";
 import { Layout as LayoutImport } from "./Layout.js";
+import { Markdown as MarkdownImport } from "./Markdown.js";
+import { Spinner as SpinnerImport } from "./Spinner.js";
+import { StatusPage as StatusPageImport } from "./StatusPage.js";
+import { Zudoku as ZudokuImport } from "./Zudoku.js";
 
 export const useMDXComponents = /*@__PURE__*/ useMDXComponentsImport;
-export const Callout = /*@__PURE__*/ CalloutImport;
-export const DevPortal = /*@__PURE__*/ DevPortalImport;
 export const Layout = /*@__PURE__*/ LayoutImport;
-export const Link = /*@__PURE__*/ LinkImport;
 export const RouterError = /*@__PURE__*/ RouterErrorImport;
 export const ServerError = /*@__PURE__*/ ServerErrorImport;
 export const Bootstrap = /*@__PURE__*/ BootstrapImport;
 export const BootstrapStatic = /*@__PURE__*/ BootstrapStaticImport;
-export const Button = /*@__PURE__*/ ButtonImport;
+export const RouteGuard = /*@__PURE__*/ RouteGuardImport;
+
 export const Head = /*@__PURE__*/ Helmet;
+
+export const useZudoku = /*@__PURE__*/ useZudokuImport;
+export const useAuth = /*@__PURE__*/ useAuthImport;
+export const useCache = /*@__PURE__*/ useCacheImport;
+export const CACHE_KEYS = /*@__PURE__*/ CACHE_KEYS_IMPORT;
+export const Zudoku = /*@__PURE__*/ ZudokuImport;
+
+export const StatusPage = /*@__PURE__*/ StatusPageImport;
+export const Callout = /*@__PURE__*/ CalloutImport;
+export const Markdown = /*@__PURE__*/ MarkdownImport;
+export const Spinner = /*@__PURE__*/ SpinnerImport;
+export const ClientOnly = /*@__PURE__*/ ClientOnlyImport;
+export const Button = /*@__PURE__*/ ButtonImport;
+export const Link = /*@__PURE__*/ LinkImport;
+export const useTheme = /*@__PURE__*/ useThemeImport;

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

@@ -0,0 +1,23 @@
+import { ChevronRightIcon } from "lucide-react";
+import { cn } from "../../util/cn.js";
+import ZudokuLogo from "./ZudokuLogo.js";
+
+export const PoweredByZudoku = ({ className }: { className?: string }) => (
+  <a
+    href="https://zudoku.dev"
+    target="_blank"
+    rel="noopener noreferrer"
+    className={cn(
+      "flex justify-between items-center w-full border border-transparent hover:border-border rounded-full hover:shadow-sm h-7 px-3 text-nowrap hover:bg-muted/80 transition-all",
+      className,
+    )}
+  >
+    <div className="opacity-70 hover:opacity-100 transition-opacity gap-1.5 text-[11px] font-medium rounded-full h-7 flex items-center text-nowrap">
+      <ZudokuLogo className="w-3.5 h-3.5 dark:fill-white" />
+      powered by Zudoku
+    </div>
+    <div className="text-xs font-medium opacity-70 hover:text-foreground transition-colors cursor-pointer">
+      <ChevronRightIcon size={12} absoluteStrokeWidth strokeWidth={1.5} />
+    </div>
+  </a>
+);

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

@@ -1,39 +1,48 @@
-import { useRef } from "react";
-
 import { VisuallyHidden } from "@radix-ui/react-visually-hidden";
+import type { SidebarItem as SidebarItemType } from "../../../config/validators/SidebarSchema.js";
 import { DrawerContent, DrawerTitle } from "../../ui/Drawer.js";
-import { useNavigation } from "../context/ZudokuContext.js";
 import { Slotlet } from "../SlotletProvider.js";
 import { SidebarItem } from "./SidebarItem.js";
 import { SidebarWrapper } from "./SidebarWrapper.js";
 
-export const Sidebar = () => {
-  const navRef = useRef<HTMLDivElement | null>(null);
-  const navigation = useNavigation();
-
-  return (
-    <>
-      <SidebarWrapper
-        ref={navRef}
-        pushMainContent={navigation.data.items.length > 0}
-      >
-        <Slotlet name="zudoku-before-navigation" />
-        {navigation.data.items.map((item) => (
-          <SidebarItem key={item.label} item={item} />
-        ))}
-        <Slotlet name="zudoku-after-navigation" />
-      </SidebarWrapper>
-      <DrawerContent
-        className="lg:hidden h-screen left-0 p-6 w-[320px] rounded-none"
-        aria-describedby={undefined}
-      >
+export const Sidebar = ({
+  onRequestClose,
+  sidebar,
+}: {
+  onRequestClose?: () => void;
+  sidebar: SidebarItemType[];
+}) => (
+  <>
+    <SidebarWrapper>
+      <Slotlet name="zudoku-before-navigation" />
+      {sidebar.map((item) => (
+        <SidebarItem
+          key={
+            ("id" in item ? item.id : "") +
+            ("href" in item ? item.href : "") +
+            item.label
+          }
+          item={item}
+        />
+      ))}
+      <Slotlet name="zudoku-after-navigation" />
+    </SidebarWrapper>
+    <DrawerContent
+      className="lg:hidden h-[100dvh] left-0 w-[320px] rounded-none"
+      aria-describedby={undefined}
+    >
+      <div className="p-4 overflow-y-auto overscroll-none">
         <VisuallyHidden>
           <DrawerTitle>Sidebar</DrawerTitle>
         </VisuallyHidden>
-        {navigation.data.items.map((item) => (
-          <SidebarItem key={item.label} item={item} />
+        {sidebar.map((item) => (
+          <SidebarItem
+            key={item.label}
+            item={item}
+            onRequestClose={onRequestClose}
+          />
         ))}
-      </DrawerContent>
-    </>
-  );
-};
+      </div>
+    </DrawerContent>
+  </>
+);

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

@@ -1,15 +1,5 @@
 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",
@@ -18,22 +8,37 @@ export const ColorMap = {
   purple: "bg-purple-400 dark:bg-purple-600",
   indigo: "bg-indigo-400 dark:bg-indigo-600",
   gray: "bg-gray-400 dark:bg-gray-600",
+  outline: "border border-border rounded-md text-foreground",
+};
+
+export const ColorMapInvert = {
+  green: "text-green-500 dark:text-green-600",
+  blue: "text-sky-400 dark:text-sky-600",
+  yellow: "text-yellow-400 dark:text-yellow-600",
+  red: "text-red-400 dark:text-red-600",
+  purple: "text-purple-400 dark:text-purple-600",
+  indigo: "text-indigo-400 dark:text-indigo-600",
+  gray: "text-gray-400 dark:text-gray-600",
+  outline: "",
 };
 
 export const SidebarBadge = ({
   color,
   label,
   className,
+  invert,
 }: {
   color: keyof typeof ColorMap;
   label: string;
   className?: string;
+  invert?: boolean;
 }) => {
   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],
+        "flex items-center duration-200 transition-opacity text-center uppercase text-[0.65rem] font-bold rounded text-background dark:text-zinc-50 h-full",
+        color === "outline" ? "px-3" : "mt-0.5 px-1",
+        invert ? ColorMapInvert[color] : ColorMap[color],
         className,
       )}
     >