@mehdad67/apitogo 0.1.24

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

@@ -0,0 +1,181 @@
+import { Separator } from "@lukoweb/apitogo/ui/Separator.js";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@lukoweb/apitogo/ui/Tooltip.js";
+import { ExternalLinkIcon } from "lucide-react";
+import { Suspense, lazy, useEffect, useRef, useState } from "react";
+import { NavLink, useLocation } from "react-router";
+import type { NavigationItem as NavigationItemType } from "../../../config/validators/NavigationSchema.js";
+import { useAuth } from "../../authentication/hook.js";
+import { cn } from "../../util/cn.js";
+import { joinUrl } from "../../util/joinUrl.js";
+import { AnchorLink } from "../AnchorLink.js";
+import { useViewportAnchor } from "../context/ViewportAnchorContext.js";
+import { useZudoku } from "../context/ZudokuContext.js";
+import { NavigationBadge } from "./NavigationBadge.js";
+import { NavigationCategory } from "./NavigationCategory.js";
+import { useNavigationFilter } from "./NavigationFilterContext.js";
+import { NavigationFilterInput } from "./NavigationFilterInput.js";
+import { navigationListItem, shouldShowItem } from "./utils.js";
+
+const HastRichText = lazy(() => import("../../util/hastToJsx.js"));
+
+const TruncatedLabel = ({
+  label,
+  className,
+}: {
+  label: string;
+  className?: string;
+}) => {
+  const ref = useRef<HTMLSpanElement>(null);
+  const [isTruncated, setIsTruncated] = useState(false);
+
+  useEffect(() => {
+    if (!ref.current) return;
+
+    if (ref.current.offsetWidth < ref.current.scrollWidth) {
+      setIsTruncated(true);
+    }
+  }, []);
+
+  return (
+    <>
+      <span
+        className={cn("truncate flex-1", className)}
+        title={label}
+        ref={ref}
+      >
+        {label}
+      </span>
+      {isTruncated && (
+        <Tooltip disableHoverableContent>
+          <TooltipTrigger className="absolute inset-0 z-10" />
+          <TooltipContent className="max-w-64" side="bottom" align="center">
+            {label}
+          </TooltipContent>
+        </Tooltip>
+      )}
+    </>
+  );
+};
+
+export const DATA_ANCHOR_ATTR = "data-anchor";
+
+export const NavigationItem = ({
+  item,
+  onRequestClose,
+}: {
+  item: NavigationItemType;
+  onRequestClose?: () => void;
+}) => {
+  const location = useLocation();
+  const { activeAnchor } = useViewportAnchor();
+  const auth = useAuth();
+  const context = useZudoku();
+  const { query } = useNavigationFilter();
+
+  if (!shouldShowItem({ auth, context, filterQuery: query })(item)) {
+    return null;
+  }
+
+  switch (item.type) {
+    case "category":
+      return (
+        <NavigationCategory category={item} onRequestClose={onRequestClose} />
+      );
+    case "separator":
+      return (
+        <Separator className="my-1 mx-auto w-[calc(100%-var(--padding-nav-item)*2)]!" />
+      );
+    case "section":
+      return (
+        <div className="mt-4 px-(--padding-nav-item) text-xs font-semibold text-muted-foreground uppercase tracking-wider">
+          {item.label}
+        </div>
+      );
+    case "filter":
+      return <NavigationFilterInput placeholder={item.placeholder} />;
+    case "doc":
+      return (
+        <NavLink
+          viewTransition
+          className={({ isActive, isPending }) =>
+            navigationListItem({ isActive, isPending })
+          }
+          to={joinUrl(item.path)}
+          onClick={onRequestClose}
+          end
+        >
+          {item.icon && (
+            <item.icon size={16} className="align-[-0.125em] shrink-0" />
+          )}
+          {item.rich ? (
+            <Suspense fallback={<span>{item.label}</span>}>
+              <span>
+                <HastRichText>{item.rich}</HastRichText>
+              </span>
+            </Suspense>
+          ) : (
+            <TruncatedLabel label={item.label} className="flex-1" />
+          )}
+          {item.badge && <NavigationBadge {...item.badge} />}
+        </NavLink>
+      );
+    case "link":
+    case "custom-page": {
+      const href = item.type === "link" ? item.to : joinUrl(item.path);
+      const hasAnchor = href.includes("#");
+      return !href.startsWith("http") ? (
+        <AnchorLink
+          to={{
+            pathname: href.split("#")[0],
+            hash: href.split("#")[1],
+            search: location.search,
+          }}
+          {...{ [DATA_ANCHOR_ATTR]: href.split("#")[1] }}
+          className={navigationListItem({
+            isActive:
+              href ===
+              (hasAnchor
+                ? [joinUrl(location.pathname), activeAnchor]
+                    .filter(Boolean)
+                    .join("#")
+                : joinUrl(location.pathname)),
+          })}
+          onClick={onRequestClose}
+        >
+          {item.icon && (
+            <item.icon size={16} className="align-[-0.125em] shrink-0" />
+          )}
+          {item.badge ? (
+            <>
+              {item.label && <TruncatedLabel label={item.label} />}
+              <NavigationBadge {...item.badge} />
+            </>
+          ) : (
+            <span className="break-all">{item.label}</span>
+          )}
+        </AnchorLink>
+      ) : (
+        <a
+          className={navigationListItem()}
+          href={href}
+          target={"target" in item ? item.target : "_blank"}
+          rel="noopener noreferrer"
+          onClick={onRequestClose}
+        >
+          {item.icon && (
+            <item.icon size={16} className="align-[-0.125em] shrink-0" />
+          )}
+          <span className="whitespace-normal">{item.label}</span>
+          {/* This prevents that the icon would be positioned in its own line if the text fills a line entirely */}
+          <span className="whitespace-nowrap">
+            <ExternalLinkIcon className="inline -translate-y-0.5" size={12} />
+          </span>
+        </a>
+      );
+    }
+  }
+};

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

@@ -0,0 +1,49 @@
+import { type PropsWithChildren, useEffect, useRef } from "react";
+import { cn } from "../../util/cn.js";
+import { scrollIntoViewIfNeeded } from "../../util/scrollIntoViewIfNeeded.js";
+import { useZudoku } from "../context/ZudokuContext.js";
+import { PoweredByZudoku } from "./PoweredByZudoku.js";
+
+export const NavigationWrapper = ({
+  children,
+  className,
+}: PropsWithChildren<{
+  className?: string;
+}>) => {
+  const { options } = useZudoku();
+  const navRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const active = navRef.current?.querySelector('[aria-current="page"]');
+    scrollIntoViewIfNeeded(active ?? null);
+  }, []);
+
+  return (
+    <div
+      className="grid sticky top-(--header-height) lg:h-[calc(100vh-var(--header-height))] grid-rows-[1fr_min-content] border-r"
+      data-pagefind-ignore="all"
+    >
+      <nav
+        ref={navRef}
+        className={cn(
+          "hidden max-w-[calc(var(--side-nav-width)+var(--padding-nav-item))] lg:flex scrollbar flex-col overflow-y-auto shrink-0 text-sm pe-3 ps-4 lg:ps-8",
+          "-mx-(--padding-nav-item) pb-[8vh] pt-(--padding-content-top) scroll-pt-2",
+          // Revert the padding/margin on the first child
+          "-mt-2.5",
+          className,
+        )}
+        style={{
+          maskImage: `linear-gradient(180deg, transparent 1%, rgba(0, 0, 0, 1) 20px, rgba(0, 0, 0, 1) 90%, transparent 99%)`,
+        }}
+      >
+        {children}
+      </nav>
+
+      <div className="bg-background border-t p-2 mx-5  gap-2 items-center mt-2 drop-shadow-[0_-3px_1px_rgba(0,0,0,0.015)] hidden lg:[&:has(>_:nth-child(1):last-child)]:flex">
+        {options.site?.showPoweredBy !== false && <PoweredByZudoku />}
+      </div>
+    </div>
+  );
+};
+
+NavigationWrapper.displayName = "NavigationWrapper";

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

@@ -0,0 +1,39 @@
+import { ChevronRightIcon } from "lucide-react";
+import { cn } from "../../util/cn.js";
+import ZuploLogo from "./ZuploLogo.js";
+
+export const PoweredByZudoku = ({ className }: { className?: string }) => (
+  <a
+    href={
+      import.meta.env.IS_ZUPLO ? "https://zuplo.com" : "https://apitogo.com"
+    }
+    target="_blank"
+    rel="noopener noreferrer"
+    className={cn(
+      "flex justify-between items-center w-full border border-transparent hover:border-border rounded-full hover:shadow-xs 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">
+      {import.meta.env.IS_ZUPLO ? (
+        <ZuploLogo className="w-3.5 h-3.5 dark:fill-white" />
+      ) : (
+        <img
+          src="/Icon.png"
+          alt=""
+          aria-hidden="true"
+          className="w-3.5 h-3.5"
+        />
+      )}
+      powered by {import.meta.env.IS_ZUPLO ? "Zuplo" : "apitogo"}
+    </div>
+    <div className="text-xs font-medium opacity-70 hover:text-foreground transition-colors cursor-pointer">
+      <ChevronRightIcon
+        size={12}
+        absoluteStrokeWidth
+        strokeWidth={1.5}
+        className="rtl:rotate-180"
+      />
+    </div>
+  </a>
+);

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

@@ -0,0 +1,137 @@
+import { ListTreeIcon } from "lucide-react";
+import {
+  type CSSProperties,
+  type PropsWithChildren,
+  Suspense,
+  lazy,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+import type { TocEntry } from "../../../vite/mdx/rehype-extract-toc-with-jsx.js";
+import { cn } from "../../util/cn.js";
+import { AnchorLink } from "../AnchorLink.js";
+import { useViewportAnchor } from "../context/ViewportAnchorContext.js";
+import { InlineCode } from "../InlineCode.js";
+
+const HastRichText = lazy(() => import("../../util/hastToJsx.js"));
+
+const DATA_ANCHOR_ATTR = "data-active";
+
+const TocItem = ({
+  item,
+  children,
+  className,
+  isActive,
+}: PropsWithChildren<{
+  item: TocEntry;
+  isActive: boolean;
+  className?: string;
+}>) => (
+  <li className={cn("truncate", className)} title={item.text}>
+    <AnchorLink
+      to={`#${item.id}`}
+      {...{ [DATA_ANCHOR_ATTR]: item.id }}
+      className={cn(
+        isActive
+          ? "text-primary"
+          : "hover:text-accent-foreground text-muted-foreground",
+      )}
+    >
+      {item.rich ? (
+        <Suspense fallback={item.text}>
+          <HastRichText overrides={{ code: InlineCode, pre: "pre" }}>
+            {item.rich}
+          </HastRichText>
+        </Suspense>
+      ) : (
+        item.text
+      )}
+    </AnchorLink>
+    {children}
+  </li>
+);
+
+export const Toc = ({ entries }: { entries: TocEntry[] }) => {
+  const { activeAnchor } = useViewportAnchor();
+  const listWrapperRef = useRef<HTMLUListElement>(null);
+  const paintedOnce = useRef(false);
+  const [indicatorStyle, setIndicatorStyles] = useState<CSSProperties>({
+    top: 0,
+    opacity: 0,
+  });
+
+  // synchronize active anchor indicator with the scroll position
+  useEffect(() => {
+    if (!listWrapperRef.current) return;
+
+    const activeElement = listWrapperRef.current.querySelector(
+      `[${DATA_ANCHOR_ATTR}='${activeAnchor}']`,
+    );
+
+    if (!activeElement) {
+      setIndicatorStyles({ top: 0, opacity: 0 });
+      return;
+    }
+
+    const topParent = listWrapperRef.current.getBoundingClientRect().top;
+    const topElement = activeElement.getBoundingClientRect().top;
+
+    setIndicatorStyles({
+      opacity: 1,
+      top: `${topElement - topParent}px`,
+    });
+
+    if (paintedOnce.current) return;
+
+    // after all is painted, the indicator should animate
+    requestIdleCallback(() => {
+      paintedOnce.current = true;
+    });
+  }, [activeAnchor]);
+
+  return (
+    <aside className="sticky scrollbar top-8 lg:top-(--header-height) h-[calc(100vh-var(--header-height))] pt-(--padding-content-top) pb-(--padding-content-bottom) overflow-y-auto ps-1 text-sm">
+      <div className="flex items-center gap-2 font-medium mb-2">
+        <ListTreeIcon size={16} />
+        On this page
+      </div>
+      <div className="relative ms-px ps-4">
+        <div className="absolute inset-0 end-auto bg-border w-[1.5px]" />
+        <div
+          className={cn(
+            "absolute inset-s-0 -translate-y-1 h-6 w-[2.5px] bg-primary",
+            paintedOnce.current &&
+              "ease-out [transition:top_150ms,opacity_325ms]",
+          )}
+          style={indicatorStyle}
+        />
+        <ul
+          ref={listWrapperRef}
+          className="relative font-medium list-none space-y-2"
+        >
+          {entries.map((item) => (
+            <TocItem
+              isActive={item.id === activeAnchor}
+              key={item.id}
+              item={item}
+              className="ps-0"
+            >
+              {item.children && (
+                <ul className="list-none ps-4 pt-2 space-y-2">
+                  {item.children.map((child) => (
+                    <TocItem
+                      item={child}
+                      isActive={child.id === activeAnchor}
+                      key={child.id}
+                    />
+                  ))}
+                </ul>
+              )}
+            </TocItem>
+          ))}
+        </ul>
+      </div>
+    </aside>
+  );
+};

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

@@ -0,0 +1,25 @@
+import type * as React from "react";
+
+const ZudokuLogo = (props: React.SVGProps<SVGSVGElement>) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 132 100"
+    fill="none"
+    {...props}
+  >
+    <path
+      fill="currentColor"
+      fillRule="evenodd"
+      d="M80.092 2.963A4.66 4.66 0 0 1 84.449 0h34.049c6.325 0 10.835 6.135 8.948 12.172L116.653 46.71a4.688 4.688 0 0 1-4.474 3.29H75c-5.178 0-7.813 4.687-9.375 9.374-1.288 3.864-11.07 28.963-14.467 37.662A4.66 4.66 0 0 1 46.801 100H12.75c-6.324 0-10.834-6.134-8.947-12.171l10.793-34.54A4.688 4.688 0 0 1 19.071 50H56.25c5.178 0 7.813-4.687 9.375-9.375 1.288-3.864 11.07-28.962 14.467-37.662Z"
+      clipRule="evenodd"
+    />
+    <path
+      fill="currentColor"
+      d="M83.54 57.813a7.813 7.813 0 0 0-7.316 5.07L63.888 95.777c-.766 2.043.744 4.222 2.926 4.222h36.828c5.211 0 9.875-3.232 11.704-8.11l8.821-23.522c1.915-5.107-1.861-10.555-7.315-10.555H83.539ZM29.17 0a12.5 12.5 0 0 0-11.704 8.111l-8.82 23.521c-1.915 5.107 1.86 10.556 7.315 10.556h33.312a7.813 7.813 0 0 0 7.316-5.07L68.924 4.223C69.691 2.18 68.18 0 65.998 0H29.17Z"
+    />
+  </svg>
+);
+
+ZudokuLogo.displayName = "ZudokuLogo";
+
+export default ZudokuLogo;

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

@@ -0,0 +1,14 @@
+import type * as React from "react";
+
+const ZuploLogo = (props: React.SVGProps<SVGSVGElement>) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 76 66"
+    fill="none"
+    {...props}
+  >
+    <path d="M55.331 43.537H32.527l24.295-24.343a1.642 1.642 0 0 0-1.157-2.802H17.07V.239h42.336a16.407 16.407 0 0 1 8.81 2.438 16.471 16.471 0 0 1 6.147 6.775 16.037 16.037 0 0 1-3.167 18.201L55.331 43.535v.002Z" />
+    <path d="M20.695 21.888H43.5L19.204 46.23a1.643 1.643 0 0 0 1.158 2.802h38.595v16.153H16.621a16.406 16.406 0 0 1-8.81-2.438 16.471 16.471 0 0 1-6.147-6.775 16.038 16.038 0 0 1 3.167-18.201L20.695 21.89v-.002Z" />
+  </svg>
+);
+export default ZuploLogo;

package/src/lib/components/navigation/utils.ts

@@ -0,0 +1,234 @@
+import { cva } from "class-variance-authority";
+import { useLocation } from "react-router";
+import type {
+  NavigationCategory,
+  NavigationItem,
+} from "../../../config/validators/NavigationSchema.js";
+import type { UseAuthReturn } from "../../authentication/hook.js";
+import type { ZudokuContext } from "../../core/ZudokuContext.js";
+import { joinUrl } from "../../util/joinUrl.js";
+import { useCurrentNavigation } from "../context/ZudokuContext.js";
+
+export type TraverseCallback<T> = (
+  item: NavigationItem,
+  parentCategories: NavigationItem[],
+) => T | void;
+
+export const traverseNavigation = <T>(
+  navigation: NavigationItem[],
+  callback: TraverseCallback<T>,
+): T | undefined => {
+  for (const item of navigation) {
+    const result = traverseNavigationItem(item, callback);
+    if (result !== undefined) return result;
+  }
+};
+
+export const traverseNavigationItem = <T>(
+  item: NavigationItem,
+  callback: TraverseCallback<T>,
+  parentCategories: NavigationItem[] = [],
+): T | undefined => {
+  const result = callback(item, parentCategories);
+  if (result !== undefined) return result;
+
+  if (item.type === "category") {
+    for (const child of item.items) {
+      const childResult = traverseNavigationItem(child, callback, [
+        ...parentCategories,
+        item,
+      ]);
+      if (childResult !== undefined) return childResult;
+    }
+  }
+};
+
+export const getItemPath = (item: NavigationItem): string | undefined => {
+  switch (item.type) {
+    case "doc":
+    case "custom-page":
+      return joinUrl(item.path);
+    case "link":
+      return item.to;
+    case "category":
+      return item.link ? joinUrl(item.link.path) : undefined;
+    default:
+      return undefined;
+  }
+};
+
+export const getFirstMatchingPath = (item: NavigationItem): string => {
+  switch (item.type) {
+    case "doc":
+    case "custom-page":
+      return joinUrl(item.path);
+    case "link":
+      return item.to;
+    case "category": {
+      if (item.link?.path) {
+        return joinUrl(item.link.path);
+      }
+      return (
+        traverseNavigationItem(item, (child) => {
+          if (
+            child.type !== "category" &&
+            child.type !== "separator" &&
+            child.type !== "section" &&
+            child.type !== "filter"
+          ) {
+            return getFirstMatchingPath(child);
+          }
+        }) ?? ""
+      );
+    }
+    default:
+      return "";
+  }
+};
+
+export const useCurrentItem = () => {
+  const pathname = joinUrl(useLocation().pathname);
+  const { navigation } = useCurrentNavigation();
+
+  return traverseNavigation(navigation, (item) => {
+    if (item.type === "doc" && joinUrl(item.path) === pathname) {
+      return item;
+    }
+  });
+};
+
+export const useIsCategoryOpen = (category: NavigationCategory) => {
+  const pathname = joinUrl(useLocation().pathname);
+
+  return traverseNavigationItem(category, (item) => {
+    switch (item.type) {
+      case "category":
+        if (!item.link) {
+          return undefined;
+        }
+        return joinUrl(item.link.path) === pathname ? true : undefined;
+      case "custom-page":
+      case "doc":
+        return joinUrl(item.path) === pathname ? true : undefined;
+      default:
+        return undefined;
+    }
+  });
+};
+
+export const usePrevNext = (): {
+  prev?: { label?: string; id: string };
+  next?: { label?: string; id: string };
+} => {
+  const currentId = joinUrl(useLocation().pathname);
+  const { navigation } = useCurrentNavigation();
+
+  let prev: { label?: string; id: string } | undefined;
+  let next: { label?: string; id: string } | undefined;
+
+  let foundCurrent = false;
+
+  traverseNavigation(navigation, (item) => {
+    if (
+      item.type === "separator" ||
+      item.type === "section" ||
+      item.type === "filter"
+    )
+      return;
+
+    const itemId =
+      item.type === "doc"
+        ? joinUrl(item.path)
+        : item.type === "category" && item.link
+          ? joinUrl(item.link.path)
+          : undefined;
+
+    if (!itemId) return;
+
+    if (foundCurrent) {
+      next = { label: item.label, id: itemId };
+      return true;
+    }
+
+    if (currentId === itemId) {
+      foundCurrent = true;
+    } else {
+      prev = { label: item.label, id: itemId };
+    }
+  });
+
+  return { prev, next };
+};
+
+export const navigationListItem = cva(
+  "relative flex items-center gap-2 px-(--padding-nav-item) my-px py-1.5 rounded-lg hover:bg-accent tabular-nums",
+  {
+    variants: {
+      isActive: {
+        true: "bg-accent font-medium",
+        false: "text-foreground/80",
+      },
+      isMuted: {
+        true: "text-foreground/30",
+        false: "",
+      },
+      isPending: {
+        true: "bg-accent animate-pulse",
+        false: "",
+      },
+    },
+    defaultVariants: {
+      isActive: false,
+    },
+  },
+);
+
+export const itemMatchesFilter = (
+  item: NavigationItem,
+  query: string,
+): boolean => {
+  if (["separator", "section", "filter"].includes(item.type)) {
+    return true;
+  }
+  if (item.label?.toLowerCase().includes(query.toLowerCase())) {
+    return true;
+  }
+
+  if (item.type === "category") {
+    return item.items.some((child) => itemMatchesFilter(child, query));
+  }
+
+  return false;
+};
+
+export const shouldShowItem =
+  ({
+    auth,
+    context,
+    filterQuery,
+  }: {
+    auth: UseAuthReturn;
+    context: ZudokuContext;
+    filterQuery?: string;
+  }) =>
+  (item: NavigationItem): boolean => {
+    if (item.type === "filter") return true;
+
+    if (filterQuery?.trim() && !itemMatchesFilter(item, filterQuery)) {
+      return false;
+    }
+
+    if (typeof item.display === "function") {
+      return item.display({ context, auth });
+    }
+
+    if (item.display === "hide") return false;
+    if (!item.label) return false;
+
+    return (
+      (item.display === "auth" && auth.isAuthenticated) ||
+      (item.display === "anon" && !auth.isAuthenticated) ||
+      !item.display ||
+      item.display === "always"
+    );
+  };