zudoku 0.0.0-ff3bc72 → 0.0.0-zuplo-api-keys.95df9e9

package/src/lib/components/TopNavigation.tsx

@@ -1,37 +1,107 @@
+import { useNProgress } from "@tanem/react-nprogress";
 import { cx } from "class-variance-authority";
-import { NavLink } from "react-router-dom";
+import { Suspense, useEffect, useState } from "react";
+import { NavLink, useNavigation } from "react-router";
+import type { TopNavigationItem } from "../../config/validators/validate.js";
+import { useAuth } from "../authentication/hook.js";
+import { joinUrl } from "../util/joinUrl.js";
+import { useCurrentNavigation, useZudoku } from "./context/ZudokuContext.js";
+import { isHiddenItem, traverseSidebar } from "./navigation/utils.js";
+import { Slot } from "./Slot.js";
 
-import { useZudoku } from "./context/ZudokuContext.js";
+export const PageProgress = () => {
+  const navigation = useNavigation();
+  const isNavigating = navigation.state === "loading";
+  // delay the animation to avoid flickering
+  const [isAnimating, setIsAnimating] = useState(false);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setIsAnimating(isNavigating), 100);
+
+    return () => clearTimeout(timer);
+  }, [isNavigating]);
+
+  const { isFinished, progress } = useNProgress({ isAnimating });
+
+  return (
+    <div
+      className="absolute w-0 left-0 right-0 bottom-[-1px] h-[2px] bg-primary transition-all duration-300 ease-in-out"
+      style={{
+        opacity: isFinished ? 0 : 1,
+        width: isFinished ? 0 : `${progress * 100}%`,
+      }}
+    />
+  );
+};
 
 export const TopNavigation = () => {
   const { topNavigation } = useZudoku();
+  const { isAuthenticated } = useAuth();
 
-  // Hide top nav if there is only one item
-  if (topNavigation.length <= 1) {
+  const filteredItems = topNavigation.filter(isHiddenItem(isAuthenticated));
+
+  if (filteredItems.length === 0 || import.meta.env.MODE === "standalone") {
     return <style>{`:root { --top-nav-height: 0px; }`}</style>;
   }
 
   return (
-    <nav className="hidden lg:block border-b text-sm px-12 h-[--top-nav-height]">
-      <ul className="flex flex-row items-center gap-8">
-        {topNavigation.map((item) => (
-          <li key={item.label}>
-            <NavLink
-              className={({ isActive }) =>
-                cx(
-                  "block py-3.5 font-medium -mb-px border-b-2",
-                  isActive
-                    ? "border-primary text-foreground"
-                    : "border-transparent text-foreground/75 hover:text-foreground hover:border-accent-foreground/25",
-                )
-              }
-              to={item.id}
-            >
-              {item.label}
-            </NavLink>
-          </li>
-        ))}
-      </ul>
-    </nav>
+    <Suspense>
+      <div className="items-center justify-between px-8 h-(--top-nav-height) hidden lg:flex text-sm relative">
+        <nav className="text-sm">
+          <ul className="flex flex-row items-center gap-8">
+            {filteredItems.map((item) => (
+              <li key={item.id}>
+                <TopNavItem {...item} />
+              </li>
+            ))}
+          </ul>
+        </nav>
+        <Slot.Target name="top-navigation-side" />
+      </div>
+      <PageProgress />
+    </Suspense>
+  );
+};
+
+export const TopNavItem = ({
+  id,
+  label,
+  default: defaultLink,
+}: TopNavigationItem) => {
+  const { sidebars } = useZudoku();
+  const currentSidebar = sidebars[id];
+  const currentNav = useCurrentNavigation();
+  const isNavigating = Boolean(useNavigation().location);
+  const isActive = currentNav.topNavItem?.id === id && !isNavigating;
+
+  // TODO: This is a bit of a hack to get the first link in the sidebar
+  // We should really process this when we load the config so we can validate
+  // that the sidebar is actually set. In this case we just fall back to linking
+  // to the id if we can't resolve a sidebar.
+  const first =
+    defaultLink ??
+    (currentSidebar
+      ? traverseSidebar(currentSidebar, (item) => {
+          if (item.type === "doc") return joinUrl(item.id);
+        })
+      : joinUrl(id)) ??
+    joinUrl(id);
+
+  return (
+    // We don't use isActive here because it has to be inside the sidebar,
+    // the top nav id doesn't necessarily start with the sidebar id
+    <NavLink
+      className={({ isPending }) =>
+        cx(
+          "block lg:py-3.5 font-medium -mb-px",
+          isActive || isPending
+            ? "border-primary text-foreground"
+            : "border-transparent text-foreground/75 hover:text-foreground hover:border-accent-foreground/25",
+        )
+      }
+      to={first}
+    >
+      {label}
+    </NavLink>
   );
 };

package/src/lib/components/Zudoku.tsx

@@ -0,0 +1,119 @@
+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 { SlotProvider } from "./context/SlotProvider.js";
+import { ViewportAnchorProvider } from "./context/ViewportAnchorContext.js";
+import { ZudokuProvider } from "./context/ZudokuProvider.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]);
+
+    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 />
+            <SlotProvider slots={props.slots ?? props.UNSAFE_slotlets}>
+              <MDXProvider components={mdxComponents}>
+                <ThemeProvider attribute="class" disableTransitionOnChange>
+                  <ComponentsProvider value={components}>
+                    <ViewportAnchorProvider>
+                      {children ?? <Outlet />}
+                    </ViewportAnchorProvider>
+                  </ComponentsProvider>
+                </ThemeProvider>
+              </MDXProvider>
+            </SlotProvider>
+          </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/SlotProvider.tsx

@@ -0,0 +1,149 @@
+import {
+  createContext,
+  Fragment,
+  use,
+  useMemo,
+  useRef,
+  type ComponentType,
+  type PropsWithChildren,
+  type ReactNode,
+} from "react";
+import { createStore, useStore } from "zustand";
+import {
+  useExposedProps,
+  type ExposedComponentProps,
+} from "../../util/useExposedProps.js";
+
+export type SlotType = ReactNode | ComponentType<ExposedComponentProps>;
+
+type SlotItem = {
+  id: string;
+  content: SlotType;
+  type: "prepend" | "replace" | "append";
+  sequence: number;
+};
+
+type SlotStoreState = {
+  items: Map<string, SlotItem[]>;
+  // to guarantee the order of the items when appending/prepending
+  sequences: Map<string, number>;
+  getItems: (name: string) => SlotItem[];
+  setSlot: (
+    id: string,
+    name: string,
+    content: SlotType,
+    type: "prepend" | "replace" | "append",
+  ) => void;
+  clearSlot: (id: string, name: string) => void;
+};
+
+export type SlotStore = ReturnType<typeof createSlotStore>;
+
+const createSlotStore = ({
+  slots = {},
+}: {
+  slots?: Record<string, SlotType>;
+} = {}) => {
+  const initialItems = new Map(
+    Object.entries(slots).map(([id, content]) => [
+      id,
+      [{ id, content, type: "replace", sequence: 0 } satisfies SlotItem],
+    ]),
+  );
+  const EMPTY_ITEMS: SlotItem[] = [];
+
+  return createStore<SlotStoreState>()((set, get) => ({
+    items: initialItems,
+    sequences: new Map(),
+    getItems: (name) => get().items.get(name) ?? EMPTY_ITEMS,
+    setSlot: (id, name, content, type) =>
+      set((state) => {
+        if (content == null) return state;
+
+        const items = new Map(state.items);
+        const sequences = new Map(state.sequences);
+        const existing = items.get(name) ?? [];
+        const filtered = existing.filter((item) => item.id !== id);
+
+        const currentSequence = sequences.get(name) ?? 0;
+        const newSequence = currentSequence + 1;
+        sequences.set(name, newSequence);
+
+        const newItem = {
+          id,
+          content,
+          type,
+          // Use negative sequence values for "prepend" to ensure they are sorted before positive values for "append".
+          sequence: type === "prepend" ? -newSequence : newSequence,
+        } satisfies SlotItem;
+
+        if (type === "replace") {
+          const nonReplaceItems = filtered.filter(
+            (item) => item.type !== "replace",
+          );
+          items.set(name, [...nonReplaceItems, newItem]);
+        } else {
+          items.set(name, [...filtered, newItem]);
+        }
+
+        return { items, sequences };
+      }),
+    clearSlot: (id, name) =>
+      set((state) => {
+        const items = new Map(state.items);
+        const sequences = new Map(state.sequences);
+        const existing = items.get(name) ?? [];
+        const filtered = existing.filter((item) => item.id !== id);
+
+        if (filtered.length === 0) {
+          items.delete(name);
+          sequences.delete(name);
+        } else {
+          items.set(name, filtered);
+        }
+        return { items, sequences };
+      }),
+  }));
+};
+
+const SlotContext = createContext(createSlotStore());
+
+export const SlotProvider = ({
+  children,
+  slots,
+}: PropsWithChildren<{
+  slots?: Record<string, SlotType>;
+}>) => {
+  const store = useRef<SlotStore>(createSlotStore({ slots })).current;
+  return <SlotContext value={store}>{children}</SlotContext>;
+};
+
+export function useSlotContext<T>(selector: (state: SlotStoreState) => T): T {
+  const store = use(SlotContext);
+  return useStore(store, selector);
+}
+
+const ORDER = ["prepend", "replace", "append"] as const;
+
+export const useRenderSlot = (name: string) => {
+  const exposedProps = useExposedProps();
+  const items = useSlotContext((s) => s.getItems(name));
+
+  return useMemo(() => {
+    if (items.length === 0) return [];
+
+    return items
+      .toSorted((a, b) => {
+        const typeOrder = ORDER.indexOf(a.type) - ORDER.indexOf(b.type);
+        if (typeOrder !== 0) return typeOrder;
+        return a.sequence - b.sequence;
+      })
+      .map((item) =>
+        typeof item.content === "function" ? (
+          <item.content key={item.id} {...exposedProps} />
+        ) : (
+          <Fragment key={item.id}>{item.content}</Fragment>
+        ),
+      );
+  }, [items, exposedProps]);
+};

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

@@ -1,12 +1,12 @@
 import {
-  type ReactNode,
   createContext,
+  use,
   useCallback,
-  useContext,
   useEffect,
   useMemo,
   useRef,
   useState,
+  type PropsWithChildren,
 } from "react";
 
 type AnchorContextType = {
@@ -16,21 +16,14 @@ type AnchorContextType = {
   unobserve: (element: HTMLElement | null) => void;
 };
 
-const ViewportAnchorContext = createContext<AnchorContextType | undefined>(
-  undefined,
-);
+const ViewportAnchorContext = createContext<AnchorContextType>({
+  activeAnchor: "",
+  setActiveAnchor: () => {},
+  observe: () => {},
+  unobserve: () => {},
+});
 
-export const useViewportAnchor = () => {
-  const context = useContext(ViewportAnchorContext);
-
-  if (!context) {
-    throw new Error(
-      "useViewportAnchor must be used within a CurrentAnchorProvider",
-    );
-  }
-
-  return context;
-};
+export const useViewportAnchor = () => use(ViewportAnchorContext);
 
 export const useRegisterAnchorElement = () => {
   const elementRef = useRef<HTMLElement | null>(null);
@@ -55,14 +48,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 +64,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 +87,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 +106,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 +132,6 @@ export const ViewportAnchorProvider = ({
   );
 
   return (
-    <ViewportAnchorContext.Provider value={value}>
-      {children}
-    </ViewportAnchorContext.Provider>
+    <ViewportAnchorContext value={value}>{children}</ViewportAnchorContext>
   );
 };