zudoku 0.0.0-f06d326 → 0.0.0-f0b4321

package/src/lib/components/TopNavigation.tsx

@@ -1,119 +1,114 @@
-import { useNProgress } from "@tanem/react-nprogress";
 import { cx } from "class-variance-authority";
-import { Suspense, useEffect, useState } from "react";
-import { NavLink, useNavigation } from "react-router";
-import type { TopNavigationItem } from "../../config/validators/common.js";
+import { deepEqual } from "fast-equals";
+import { Suspense } from "react";
+import { NavLink, type NavLinkProps } from "react-router";
+import { type NavigationItem } from "../../config/validators/NavigationSchema.js";
 import { useAuth } from "../authentication/hook.js";
 import { joinUrl } from "../util/joinUrl.js";
 import { useCurrentNavigation, useZudoku } from "./context/ZudokuContext.js";
-import { traverseSidebar } from "./navigation/utils.js";
-import { Slotlet } from "./SlotletProvider.js";
-
-export const isHiddenItem =
-  (isAuthenticated?: boolean) =>
-  (item: { display?: "auth" | "anon" | "always" | "hide" }): boolean => {
-    if (item.display === "hide") return false;
-    return (
-      (item.display === "auth" && isAuthenticated) ||
-      (item.display === "anon" && !isAuthenticated) ||
-      !item.display ||
-      item.display === "always"
-    );
-  };
-
-const Progress = () => {
-  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}%`,
-      }}
-    />
-  );
-};
+import { isHiddenItem, traverseNavigationItem } from "./navigation/utils.js";
+import { Slot } from "./Slot.js";
 
 export const TopNavigation = () => {
-  const { topNavigation } = useZudoku();
+  const { navigation } = useZudoku();
   const { isAuthenticated } = useAuth();
 
-  const filteredItems = topNavigation.filter(isHiddenItem(isAuthenticated));
+  const filteredItems = navigation.filter(isHiddenItem(isAuthenticated));
 
-  if (filteredItems.length === 0) {
+  if (filteredItems.length === 0 || import.meta.env.MODE === "standalone") {
     return <style>{`:root { --top-nav-height: 0px; }`}</style>;
   }
 
   return (
     <Suspense>
-      <div className="items-center justify-between px-8 h-[--top-nav-height] hidden lg:flex text-sm relative">
+      <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}>
+              <li key={item.label + item.type}>
                 <TopNavItem {...item} />
               </li>
             ))}
           </ul>
         </nav>
-        <Slotlet name="top-navigation-side" />
-        <Progress />
+        <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;
+const getPathForItem = (item: NavigationItem): string => {
+  switch (item.type) {
+    case "doc":
+      return joinUrl(item.path);
+    case "link":
+      return item.to;
+    case "category": {
+      if (item.link?.path) {
+        return joinUrl(item.link.path);
+      }
 
-  // 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 (
+        traverseNavigationItem(item, (child) => {
+          if (child.type !== "category") {
+            return getPathForItem(child);
+          }
+        }) ?? ""
+      );
+    }
+    case "custom-page":
+      return item.path;
+  }
+};
 
+export const TopNavLink = ({
+  isActive,
+  children,
+  ...props
+}: {
+  isActive?: boolean;
+  children: React.ReactNode;
+} & NavLinkProps) => {
   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}
+      viewTransition
+      className={({ isActive: isActiveNavLink, isPending }) => {
+        const isActiveReal = isActiveNavLink || isActive;
+        return cx(
+          "flex items-center gap-2 lg:py-3.5 font-medium -mb-px transition duration-150 delay-75 relative",
+          isActiveReal || isPending
+            ? [
+                "text-foreground",
+                // underline with view transition animation
+                "after:content-[''] after:absolute after:bottom-0 after:left-0 after:right-0",
+                "after:h-0.5 after:bg-primary",
+                isActiveReal &&
+                  "after:[view-transition-name:top-nav-underline]",
+                isPending && "after:bg-primary/25",
+              ]
+            : "text-foreground/75 hover:text-foreground",
+        );
+      }}
+      {...props}
     >
-      {label}
+      {children}
     </NavLink>
   );
 };
+
+export const TopNavItem = (item: NavigationItem) => {
+  const currentNav = useCurrentNavigation();
+  const isActiveTopNavItem = deepEqual(currentNav.topNavItem, item);
+
+  const path = getPathForItem(item);
+
+  return (
+    // We don't use isActive here because it has to be inside the navigation,
+    // the top nav id doesn't necessarily start with the navigation id
+    <TopNavLink to={path} isActive={isActiveTopNavItem}>
+      {item.icon && <item.icon size={16} className="align-[-0.125em]" />}
+      {item.label}
+    </TopNavLink>
+  );
+};

package/src/lib/components/Typography.tsx

@@ -0,0 +1,14 @@
+import { cn } from "../util/cn.js";
+
+// other styles are defined in main.css .prose
+export const ProseClasses = "prose dark:prose-invert prose-neutral";
+
+export const Typography = ({
+  children,
+  className,
+}: {
+  children: React.ReactNode;
+  className?: string;
+}) => {
+  return <div className={cn(ProseClasses, className)}>{children}</div>;
+};

package/src/lib/components/Zudoku.tsx

@@ -26,9 +26,11 @@ import {
   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";
-import { SlotletProvider } from "./SlotletProvider.js";
+
+let zudokuContext: ZudokuContext | undefined;
 
 const ZudokoInner = memo(
   ({ children, ...props }: PropsWithChildren<ZudokuContextOptions>) => {
@@ -70,9 +72,7 @@ const ZudokoInner = memo(
       setDidNavigate(true);
     }, [didNavigate, navigation.location]);
 
-    const [zudokuContext] = useState(
-      () => new ZudokuContext(props, queryClient),
-    );
+    zudokuContext ??= new ZudokuContext(props, queryClient);
 
     const heads = props.plugins
       ?.flatMap((plugin) =>
@@ -87,17 +87,17 @@ const ZudokoInner = memo(
         <StaggeredRenderContext.Provider value={staggeredValue}>
           <ZudokuProvider context={zudokuContext}>
             <RouterEventsEmitter />
-            <MDXProvider components={mdxComponents}>
-              <ThemeProvider attribute="class" disableTransitionOnChange>
-                <ComponentsProvider value={components}>
-                  <SlotletProvider slotlets={props.slotlets}>
+            <SlotProvider slots={props.slots ?? props.UNSAFE_slotlets}>
+              <MDXProvider components={mdxComponents}>
+                <ThemeProvider attribute="class" disableTransitionOnChange>
+                  <ComponentsProvider value={components}>
                     <ViewportAnchorProvider>
                       {children ?? <Outlet />}
                     </ViewportAnchorProvider>
-                  </SlotletProvider>
-                </ComponentsProvider>
-              </ThemeProvider>
-            </MDXProvider>
+                  </ComponentsProvider>
+                </ThemeProvider>
+              </MDXProvider>
+            </SlotProvider>
           </ZudokuProvider>
         </StaggeredRenderContext.Provider>
       </>

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/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,7 +1,7 @@
 import {
   createContext,
+  use,
   useCallback,
-  useContext,
   useEffect,
   useMemo,
   useRef,
@@ -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);

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

@@ -1,11 +1,12 @@
 import { useQuery, useSuspenseQuery } from "@tanstack/react-query";
 import { createContext, useContext } from "react";
 import { matchPath, useLocation } from "react-router";
+import { type NavigationItem } from "../../../config/validators/NavigationSchema.js";
 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";
+import { CACHE_KEYS } from "../cache.js";
+import { traverseNavigation } from "../navigation/utils.js";
 
 export const ZudokuReactContext = createContext<ZudokuContext | undefined>(
   undefined,
@@ -30,8 +31,22 @@ export const useApiIdentities = () => {
   });
 };
 
+const getItemPath = (item: NavigationItem) => {
+  switch (item.type) {
+    case "doc":
+      return joinUrl(item.path);
+    case "category":
+      return item.link ? joinUrl(item.link.path) : undefined;
+    case "link":
+      return item.to;
+    case "custom-page":
+      return item.path;
+    default:
+      return undefined;
+  }
+};
 export const useCurrentNavigation = () => {
-  const { getPluginSidebar, sidebars, topNavigation, options } = useZudoku();
+  const { getPluginNavigation, navigation, options } = useZudoku();
   const location = useLocation();
   const auth = useAuth();
 
@@ -39,45 +54,47 @@ export const useCurrentNavigation = () => {
     matchPath(route, location.pathname),
   );
 
-  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;
-
-      if (itemId === location.pathname) {
-        return item;
-      }
-    });
+  const navItem = traverseNavigation(navigation, (item, parentCategories) => {
+    if (getItemPath(item) === location.pathname) {
+      return parentCategories.at(0) ?? item;
+    }
   });
-  const currentTopNavItem =
-    topNavigation.find((t) => t.id === currentSidebarItem?.[0]) ??
-    topNavigation.find((item) => matchPath(item.id, location.pathname));
-
-  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],
+    queryFn: () => getPluginNavigation(location.pathname),
+    queryKey: ["plugin-navigation", location.pathname],
   });
 
-  const hideSidebar =
+  let topNavItem = navItem;
+  if (!navItem && data.length > 0) {
+    // Extract base paths from plugin navigation items
+    const pluginBasePaths = data.flatMap((item) => {
+      return getItemPath(item)?.split("?").at(0)?.split("#").at(0) ?? [];
+    });
+
+    // Find top-level nav item that matches any plugin base path
+    topNavItem = navigation
+      .flatMap((item) => {
+        const itemPath = getItemPath(item);
+        return itemPath ? [{ item, path: itemPath }] : [];
+      })
+      .sort((a, b) => b.path.length - a.path.length)
+      .find(({ path }) => {
+        return pluginBasePaths.some(
+          (basePath) =>
+            matchPath({ path, end: false }, basePath) ??
+            matchPath({ path: basePath, end: false }, path),
+        );
+      })?.item;
+  }
+
+  const hasNavigation =
     auth.isAuthEnabled && !auth.isAuthenticated && isProtectedRoute;
 
   return {
-    sidebar: hideSidebar
+    navigation: hasNavigation
       ? []
-      : [...(currentSidebarItem ? currentSidebarItem[1] : []), ...data],
-    topNavItem: currentTopNavItem,
+      : [...(navItem?.type === "category" ? navItem.items : []), ...data],
+    topNavItem,
   };
 };

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

@@ -1,6 +1,7 @@
 import { useSuspenseQuery } from "@tanstack/react-query";
 import type { PropsWithChildren } from "react";
-import { ZudokuContext } from "../../core/ZudokuContext.js";
+import { type ZudokuContext } from "../../core/ZudokuContext.js";
+import { NO_DEHYDRATE } from "../cache.js";
 import { ZudokuReactContext } from "./ZudokuContext.js";
 
 export const ZudokuProvider = ({
@@ -12,7 +13,7 @@ export const ZudokuProvider = ({
       await context.initialize();
       return true;
     },
-    queryKey: ["zudoku-initialize"],
+    queryKey: ["zudoku-initialize", NO_DEHYDRATE],
   });
 
   return (

package/src/lib/components/index.ts

@@ -12,6 +12,7 @@ import {
   Bootstrap as BootstrapImport,
   BootstrapStatic as BootstrapStaticImport,
 } from "./Bootstrap.js";
+import { BuildCheck as BuildCheckImport } from "./BuildCheck.js";
 import {
   CACHE_KEYS as CACHE_KEYS_IMPORT,
   useCache as useCacheImport,
@@ -22,24 +23,16 @@ 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 { Typography as TypographyImport } from "./Typography.js";
 import { Zudoku as ZudokuImport } from "./Zudoku.js";
 
-export const useMDXComponents = /*@__PURE__*/ useMDXComponentsImport;
 export const Layout = /*@__PURE__*/ LayoutImport;
 export const RouterError = /*@__PURE__*/ RouterErrorImport;
 export const ServerError = /*@__PURE__*/ ServerErrorImport;
 export const Bootstrap = /*@__PURE__*/ BootstrapImport;
 export const BootstrapStatic = /*@__PURE__*/ BootstrapStaticImport;
 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;
@@ -47,4 +40,19 @@ export const Spinner = /*@__PURE__*/ SpinnerImport;
 export const ClientOnly = /*@__PURE__*/ ClientOnlyImport;
 export const Button = /*@__PURE__*/ ButtonImport;
 export const Link = /*@__PURE__*/ LinkImport;
+export const BuildCheck = /*@__PURE__*/ BuildCheckImport;
+export const Zudoku = /*@__PURE__*/ ZudokuImport;
+export const Typography = /*@__PURE__*/ TypographyImport;
+
+/** @deprecated Import from `zudoku/hooks` instead */
+export const useMDXComponents = /*@__PURE__*/ useMDXComponentsImport;
+/** @deprecated Import from `zudoku/hooks` instead */
+export const useZudoku = /*@__PURE__*/ useZudokuImport;
+/** @deprecated Import from `zudoku/hooks` instead */
+export const useAuth = /*@__PURE__*/ useAuthImport;
+/** @deprecated Import from `zudoku/hooks` instead */
+export const useCache = /*@__PURE__*/ useCacheImport;
+/** @deprecated Import from `zudoku/hooks` instead */
+export const CACHE_KEYS = /*@__PURE__*/ CACHE_KEYS_IMPORT;
+/** @deprecated Import from `zudoku/hooks` instead */
 export const useTheme = /*@__PURE__*/ useThemeImport;