@mehdad67/apitogo 0.1.24

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

@@ -0,0 +1,137 @@
+import {
+  createContext,
+  type PropsWithChildren,
+  use,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+
+type AnchorContextType = {
+  activeAnchor?: string;
+  setActiveAnchor: (anchor: string) => void;
+  observe: (element: HTMLElement | null) => void;
+  unobserve: (element: HTMLElement | null) => void;
+};
+
+const ViewportAnchorContext = createContext<AnchorContextType>({
+  activeAnchor: "",
+  setActiveAnchor: () => {},
+  observe: () => {},
+  unobserve: () => {},
+});
+
+export const useViewportAnchor = () => use(ViewportAnchorContext);
+
+export const useRegisterAnchorElement = () => {
+  const elementRef = useRef<HTMLElement | null>(null);
+
+  const { observe, unobserve } = useViewportAnchor();
+
+  useEffect(() => {
+    const element = elementRef.current;
+
+    if (!element) return;
+
+    observe(element);
+
+    return () => unobserve(element);
+  }, [observe, unobserve]);
+
+  const setRef = useCallback((el: HTMLElement | null) => {
+    if (!el) return;
+    elementRef.current = el;
+  }, []);
+
+  return { ref: setRef };
+};
+
+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(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting && entry.target.id) {
+            setActiveAnchor(entry.target.id);
+          }
+        }
+      },
+      {
+        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();
+  }, []);
+
+  useEffect(() => {
+    const elements = registeredElements.current;
+    const handleScroll = () => {
+      const hasReachedTop = window.scrollY === 0;
+      const hasReachedBottom =
+        window.innerHeight + window.scrollY >= document.body.scrollHeight;
+
+      if (hasReachedTop) {
+        setActiveAnchor("");
+      } else if (hasReachedBottom) {
+        const lastItem = Array.from(elements).pop();
+        const lastId = lastItem?.id ?? "";
+        setActiveAnchor(lastId);
+      }
+    };
+
+    document.addEventListener("scroll", handleScroll);
+
+    return () => {
+      elements.clear();
+      document.removeEventListener("scroll", handleScroll);
+    };
+  }, []);
+
+  const observeFns = useMemo(() => {
+    return {
+      observe: (element: HTMLElement | null) => {
+        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) return;
+
+        pendingElements.current.delete(element);
+        registeredElements.current.delete(element);
+        observerRef.current?.unobserve(element);
+      },
+    };
+  }, []);
+
+  const value = useMemo(
+    () => ({ activeAnchor, setActiveAnchor, ...observeFns }),
+    [activeAnchor, observeFns],
+  );
+
+  return (
+    <ViewportAnchorContext value={value}>{children}</ViewportAnchorContext>
+  );
+};

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

@@ -0,0 +1,140 @@
+import { useQuery, useSuspenseQuery } from "@tanstack/react-query";
+import { useContext, useEffect, useMemo, useRef } from "react";
+import { matchPath, useLocation } from "react-router";
+import type { NavigationItem } from "../../../config/validators/NavigationSchema.js";
+import { useAuthState } from "../../authentication/state.js";
+import { applyRules } from "../../navigation/applyRules.js";
+import { joinUrl } from "../../util/joinUrl.js";
+import { CACHE_KEYS, useCache } from "../cache.js";
+import { getItemPath, traverseNavigation } from "../navigation/utils.js";
+import { ZudokuReactContext } from "./ZudokuReactContext.js";
+
+const useApitogoContext = () => {
+  const context = useContext(ZudokuReactContext);
+
+  if (!context) {
+    throw new Error(
+      "useApitogo must be used within an ApitogoProvider (from @lukoweb/apitogo/components).",
+    );
+  }
+
+  return context;
+};
+
+/** Prefer this over {@link useZudoku}. */
+export const useApitogo = useApitogoContext;
+
+/**
+ * @deprecated Use {@link useApitogo} instead.
+ */
+export const useZudoku = useApitogoContext;
+
+export const useApiIdentities = () => {
+  const { getApiIdentities } = useApitogo();
+  const { isAuthenticated } = useAuthState();
+  const { invalidateCache } = useCache();
+
+  useEffect(() => {
+    if (!isAuthenticated) {
+      invalidateCache("API_IDENTITIES");
+    }
+  }, [isAuthenticated, invalidateCache]);
+
+  return useQuery({
+    queryFn: getApiIdentities,
+    queryKey: CACHE_KEYS.API_IDENTITIES,
+  });
+};
+
+const extractAllPaths = (items: NavigationItem[]) => {
+  const paths = new Set<string>();
+
+  const collectPaths = (items: NavigationItem[]) => {
+    for (const item of items) {
+      const itemPath = getItemPath(item)?.split("?").at(0)?.split("#").at(0);
+
+      if (itemPath) paths.add(itemPath);
+      if (item.type === "category") {
+        collectPaths(item.items);
+      }
+    }
+  };
+  collectPaths(items);
+
+  return [...paths];
+};
+
+export const useCurrentNavigation = () => {
+  const context = useApitogo();
+  const { getPluginNavigation, navigation, navigationRules } = context;
+  const location = useLocation();
+  const loggedWarnings = useRef(new Set<string>());
+
+  const pathname = joinUrl(location.pathname);
+
+  const navItem = traverseNavigation(navigation, (item, parentCategories) => {
+    if (item.type === "link") return;
+    if (getItemPath(item) === pathname) {
+      return parentCategories.at(0) ?? item;
+    }
+  });
+
+  const { data } = useSuspenseQuery({
+    queryFn: () => getPluginNavigation(pathname),
+    queryKey: ["plugin-navigation", pathname],
+  });
+
+  let topNavItem = navItem;
+
+  if (!navItem && data.length > 0) {
+    const pluginBasePaths = extractAllPaths(data);
+
+    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 finalNavigation = useMemo(() => {
+    const baseNavigation = [
+      ...(topNavItem?.type === "category" ? topNavItem.items : []),
+      ...data,
+    ];
+
+    if (topNavItem?.label && navigationRules.length > 0) {
+      const { result, warnings } = applyRules(
+        baseNavigation,
+        navigationRules,
+        topNavItem?.label,
+      );
+
+      if (import.meta.env.DEV) {
+        for (const warning of warnings) {
+          if (!loggedWarnings.current.has(warning)) {
+            loggedWarnings.current.add(warning);
+            // biome-ignore lint/suspicious/noConsole: Dev-only navigation rule warnings
+            console.warn(`[APIToGo] Navigation rule: ${warning}`);
+          }
+        }
+      }
+
+      return result;
+    }
+
+    return baseNavigation;
+  }, [topNavItem, data, navigationRules]);
+
+  return {
+    navigation: finalNavigation,
+    topNavItem,
+  };
+};

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

@@ -0,0 +1,22 @@
+import { use, type PropsWithChildren } from "react";
+import type { ZudokuContext } from "../../core/ZudokuContext.js";
+import { ZudokuReactContext } from "./ZudokuReactContext.js";
+
+const ZudokuProviderImpl = ({
+  children,
+  context,
+}: PropsWithChildren<{ context: ZudokuContext }>) => {
+  if (context.initialize) use(context.initialize);
+
+  return (
+    <ZudokuReactContext.Provider value={context}>
+      {children}
+    </ZudokuReactContext.Provider>
+  );
+};
+
+/** @deprecated Use {@link ApitogoProvider} instead. */
+export const ZudokuProvider = ZudokuProviderImpl;
+
+/** Prefer this over {@link ZudokuProvider}. */
+export const ApitogoProvider = ZudokuProviderImpl;

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

@@ -0,0 +1,17 @@
+import { type Context, createContext } from "react";
+import type { ZudokuContext } from "../../core/ZudokuContext.js";
+
+/**
+ * During SSR, Vite's module runner can load the same module multiple times
+ * (once for the main app, once for external plugins), creating duplicate
+ * React contexts that don't share state.
+ */
+declare global {
+  var __ZUDOKU_CONTEXT: Context<ZudokuContext | undefined>;
+}
+
+globalThis.__ZUDOKU_CONTEXT ??= createContext<ZudokuContext | undefined>(
+  undefined,
+);
+
+export const ZudokuReactContext = globalThis.__ZUDOKU_CONTEXT;

package/src/lib/components/index.ts

@@ -0,0 +1,36 @@
+export { Helmet as Head } from "@zudoku/react-helmet-async";
+export { Link } from "react-router";
+export { Button } from "../ui/Button.js";
+export { Callout } from "../ui/Callout.js";
+export { ApitogoError } from "../util/invariant.js";
+/** @deprecated Use {@link ApitogoError} instead. */
+export { ZudokuError } from "../util/invariant.js";
+export { ClientOnly } from "./ClientOnly.js";
+export { Footer } from "./Footer.js";
+export { Header } from "./Header.js";
+export { Heading } from "./Heading.js";
+export { Markdown } from "./Markdown.js";
+export { Search } from "./Search.js";
+export { type CustomSlotNames, Slot } from "./Slot.js";
+export { Spinner } from "./Spinner.js";
+export { Typography } from "./Typography.js";
+export { Apitogo } from "./Zudoku.js";
+/** @deprecated Use {@link Apitogo} instead. */
+export { Zudoku } from "./Zudoku.js";
+export { ApitogoProvider } from "./context/ZudokuProvider.js";
+/** @deprecated Use {@link ApitogoProvider} instead. */
+export { ZudokuProvider } from "./context/ZudokuProvider.js";
+
+//
+
+/** @deprecated Import from `apitogo/hooks` instead */
+export { useMDXComponents } from "@mdx-js/react";
+/** @deprecated Import from `apitogo/hooks` instead */
+export { useTheme } from "next-themes";
+/** @deprecated Import from `apitogo/hooks` instead */
+export { useAuth } from "../authentication/hook.js";
+/** @deprecated Import from `apitogo/hooks` instead */
+export { CACHE_KEYS, useCache } from "./cache.js";
+export { useApitogo } from "./context/ZudokuContext.js";
+/** @deprecated Import {@link useApitogo} from `apitogo/hooks` instead */
+export { useZudoku } from "./context/ZudokuContext.js";

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

@@ -0,0 +1,51 @@
+import { VisuallyHidden } from "@radix-ui/react-visually-hidden";
+import type { NavigationItem as NavigationItemType } from "../../../config/validators/NavigationSchema.js";
+import { DrawerContent, DrawerTitle } from "../../ui/Drawer.js";
+import { Slot } from "../Slot.js";
+import { NavigationFilterProvider } from "./NavigationFilterContext.js";
+import { NavigationItem } from "./NavigationItem.js";
+import { NavigationWrapper } from "./NavigationWrapper.js";
+
+export const Navigation = ({
+  onRequestClose,
+  navigation,
+}: {
+  onRequestClose?: () => void;
+  navigation: NavigationItemType[];
+}) => (
+  <NavigationFilterProvider>
+    <NavigationWrapper>
+      <Slot.Target name="navigation-before" />
+      {navigation.map((item) => (
+        <NavigationItem
+          key={
+            item.type +
+            (item.label ?? "") +
+            ("path" in item ? item.path : "") +
+            ("file" in item ? item.file : "") +
+            ("to" in item ? item.to : "")
+          }
+          item={item}
+        />
+      ))}
+      <Slot.Target name="navigation-after" />
+    </NavigationWrapper>
+    <DrawerContent
+      className="lg:hidden h-dvh start-0 w-[320px] rounded-none"
+      aria-describedby={undefined}
+    >
+      <div className="p-4 overflow-y-auto overscroll-none">
+        <VisuallyHidden>
+          <DrawerTitle>Navigation</DrawerTitle>
+        </VisuallyHidden>
+        {navigation.map((item) => (
+          <NavigationItem
+            key={item.label}
+            item={item}
+            onRequestClose={onRequestClose}
+          />
+        ))}
+      </div>
+    </DrawerContent>
+  </NavigationFilterProvider>
+);

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

@@ -0,0 +1,48 @@
+import { cn } from "../../util/cn.js";
+
+export const ColorMap = {
+  green: "bg-green-400 dark:bg-green-800",
+  blue: "bg-sky-400 dark:bg-sky-800",
+  yellow: "bg-yellow-400 dark:bg-yellow-800",
+  red: "bg-red-400 dark:bg-red-800",
+  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 NavigationBadge = ({
+  color,
+  label,
+  className,
+  invert,
+}: {
+  color: keyof typeof ColorMap;
+  label: string;
+  className?: string;
+  invert?: boolean;
+}) => {
+  return (
+    <span
+      className={cn(
+        "flex items-center duration-200 transition-opacity text-center uppercase text-[0.65rem] leading-5 font-bold rounded-sm text-background dark:text-zinc-50 h-full",
+        color === "outline" ? "px-3" : "mt-0.5 px-1",
+        invert ? ColorMapInvert[color] : ColorMap[color],
+        className,
+      )}
+    >
+      {label}
+    </span>
+  );
+};

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

@@ -0,0 +1,157 @@
+import { Button } from "@lukoweb/apitogo/ui/Button.js";
+import * as Collapsible from "@radix-ui/react-collapsible";
+import { deepEqual } from "fast-equals";
+import { ChevronRightIcon } from "lucide-react";
+import { memo, useEffect, useState } from "react";
+import { NavLink, useLocation, useMatch } from "react-router";
+import type { NavigationCategory as NavigationCategoryType } from "../../../config/validators/NavigationSchema.js";
+import { cn } from "../../util/cn.js";
+import { joinUrl } from "../../util/joinUrl.js";
+import { useNavigationFilter } from "./NavigationFilterContext.js";
+import { NavigationItem } from "./NavigationItem.js";
+import { navigationListItem, useIsCategoryOpen } from "./utils.js";
+
+const NavigationCategoryInner = ({
+  category,
+  onRequestClose,
+}: {
+  category: NavigationCategoryType;
+  onRequestClose?: () => void;
+}) => {
+  const isCategoryOpen = useIsCategoryOpen(category);
+  const [hasInteracted, setHasInteracted] = useState(false);
+  const location = useLocation();
+  const { query: filterQuery } = useNavigationFilter();
+
+  const isCollapsible = category.collapsible ?? true;
+  const isCollapsed = category.collapsed ?? true;
+  const isDefaultOpen = Boolean(
+    !isCollapsible || !isCollapsed || isCategoryOpen,
+  );
+  const [open, setOpen] = useState(isDefaultOpen);
+  const match = useMatch(category.link?.path ?? "");
+  const isActive = category.link ? match : false;
+
+  useEffect(() => {
+    // this is triggered when an item from the navigation is clicked
+    // and the navigation, enclosing this item, is not opened
+    if (isCategoryOpen) {
+      setOpen(true);
+    }
+  }, [isCategoryOpen]);
+
+  // Auto-expand when there's an active filter query
+  useEffect(() => {
+    if (filterQuery.trim()) {
+      setOpen(true);
+    }
+  }, [filterQuery]);
+
+  const ToggleButton = isCollapsible && (
+    <Button
+      onClick={(e) => {
+        e.preventDefault();
+        setOpen((prev) => !prev);
+        setHasInteracted(true);
+      }}
+      variant="ghost"
+      size="icon"
+      className="size-6 hover:bg-[hsl(from_var(--accent)_h_s_calc(l+6*var(--dark)))]"
+    >
+      <ChevronRightIcon
+        size={16}
+        className={cn(
+          hasInteracted && "transition",
+          "shrink-0 group-data-[state=open]:rotate-90 rtl:rotate-180",
+        )}
+      />
+    </Button>
+  );
+
+  const icon = category.icon && (
+    <category.icon
+      size={16}
+      className={cn("align-[-0.125em] ", isActive && "text-primary")}
+    />
+  );
+
+  const styles = navigationListItem({
+    className: [
+      "group text-start font-medium",
+      isCollapsible || typeof category.link !== "undefined"
+        ? "cursor-pointer"
+        : "cursor-default hover:bg-transparent",
+    ],
+  });
+
+  return (
+    <Collapsible.Root
+      className="flex flex-col"
+      defaultOpen={isDefaultOpen}
+      open={open}
+      onOpenChange={() => setOpen(true)}
+    >
+      <Collapsible.Trigger className="group" asChild disabled={!isCollapsible}>
+        {category.link?.type === "doc" ? (
+          <NavLink
+            to={{
+              pathname: joinUrl(category.link.path),
+              search: location.search,
+            }}
+            className={styles}
+            onClick={() => {
+              // if it is the current path and closed then open it because there's no path change to trigger the open
+              if (isActive && !open) {
+                setHasInteracted(true);
+                setOpen(true);
+              }
+            }}
+          >
+            {icon}
+            <div className="flex items-center gap-2 justify-between w-full text-foreground/80 group-aria-[current='page']:text-primary">
+              <div className="truncate">{category.label}</div>
+              {ToggleButton}
+            </div>
+          </NavLink>
+        ) : (
+          <div className={styles}>
+            {icon}
+            <div className="flex items-center justify-between w-full">
+              <div className="flex gap-2 truncate w-full">{category.label}</div>
+              {ToggleButton}
+            </div>
+          </div>
+        )}
+      </Collapsible.Trigger>
+      <Collapsible.Content
+        className={cn(
+          // CollapsibleContent class is used to animate and it should only be applied when the user has triggered the toggle
+          hasInteracted && "CollapsibleContent",
+          category.items.length === 0 && "hidden",
+          "ms-6 my-1",
+        )}
+        onAnimationEnd={() => setHasInteracted(false)}
+      >
+        <ul className="relative after:absolute after:-inset-s-(--padding-nav-item) after:translate-x-[1.5px] after:top-0 after:bottom-0 after:w-px after:bg-border">
+          {category.items.map((item) => (
+            <NavigationItem
+              key={
+                item.type +
+                (item.label ?? "") +
+                ("path" in item ? item.path : "") +
+                ("file" in item ? item.file : "") +
+                ("to" in item ? item.to : "")
+              }
+              onRequestClose={onRequestClose}
+              item={item}
+            />
+          ))}
+        </ul>
+      </Collapsible.Content>
+    </Collapsible.Root>
+  );
+};
+
+export const NavigationCategory = memo(NavigationCategoryInner, deepEqual);
+
+NavigationCategory.displayName = "NavigationCategory";

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

@@ -0,0 +1,28 @@
+import {
+  createContext,
+  type PropsWithChildren,
+  useContext,
+  useState,
+} from "react";
+
+type NavigationFilterContextType = {
+  query: string;
+  setQuery: (query: string) => void;
+};
+
+const NavigationFilterContext = createContext<NavigationFilterContextType>({
+  query: "",
+  setQuery: () => {},
+});
+
+export const NavigationFilterProvider = ({ children }: PropsWithChildren) => {
+  const [query, setQuery] = useState("");
+
+  return (
+    <NavigationFilterContext.Provider value={{ query, setQuery }}>
+      {children}
+    </NavigationFilterContext.Provider>
+  );
+};
+
+export const useNavigationFilter = () => useContext(NavigationFilterContext);

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

@@ -0,0 +1,35 @@
+import {
+  InputGroup,
+  InputGroupAddon,
+  InputGroupButton,
+  InputGroupInput,
+} from "@lukoweb/apitogo/ui/InputGroup.js";
+import { SearchIcon, XIcon } from "lucide-react";
+import { useNavigationFilter } from "./NavigationFilterContext.js";
+
+export const NavigationFilterInput = ({
+  placeholder,
+}: {
+  placeholder?: string;
+}) => {
+  const { query, setQuery } = useNavigationFilter();
+
+  return (
+    <InputGroup className="my-2">
+      <InputGroupAddon>
+        <SearchIcon className="size-3.5" />
+      </InputGroupAddon>
+      <InputGroupInput
+        type="text"
+        placeholder={placeholder}
+        value={query}
+        onChange={(e) => setQuery(e.target.value)}
+      />
+      {query && (
+        <InputGroupButton onClick={() => setQuery("")}>
+          <XIcon className="size-3" />
+        </InputGroupButton>
+      )}
+    </InputGroup>
+  );
+};