zudoku 0.0.2-dev.0

package/src/app/components/SyntaxHighlight.tsx

@@ -0,0 +1,92 @@
+import {
+  Highlight,
+  Prism,
+  themes,
+  type HighlightProps,
+} from "prism-react-renderer";
+
+import { CheckIcon, CopyIcon } from "lucide-react";
+
+if (!import.meta.env.SSR) {
+  globalThis.Prism = Prism;
+  // @ts-expect-error This is untyped
+  import("prismjs/components/prism-bash.min.js");
+  // @ts-expect-error This is untyped
+  import("prismjs/components/prism-ruby.min.js");
+  // @ts-expect-error This is untyped
+  import("prismjs/components/prism-markup-templating.js");
+  // @ts-expect-error This is untyped
+  import("prismjs/components/prism-php.min.js");
+  // @ts-expect-error This is untyped
+  import("prismjs/components/prism-json.min.js");
+}
+
+import { useState } from "react";
+import { cn } from "../util/cn.js";
+import { useTheme } from "./context/ThemeContext.js";
+
+type SyntaxHighlightProps = {
+  className?: string;
+  noBackground?: boolean;
+  wrapLines?: boolean;
+  copyable?: boolean;
+} & Omit<HighlightProps, "children">;
+
+export const SyntaxHighlight = ({
+  copyable = true,
+  ...props
+}: SyntaxHighlightProps) => {
+  const [isDark] = useTheme();
+  const [isCopied, setIsCopied] = useState(false);
+
+  return (
+    <Highlight theme={isDark ? themes.vsDark : themes.github} {...props}>
+      {({ className, style, tokens, getLineProps, getTokenProps }) => (
+        <pre
+          className={cn(
+            "group relative",
+            className,
+            props.className,
+            props.noBackground && "!bg-transparent",
+            props.wrapLines && "whitespace-pre-wrap break-words",
+          )}
+          style={style}
+        >
+          {copyable && (
+            <button
+              type="button"
+              aria-label="Copy code"
+              className="absolute top-1.5 right-3 p-3 opacity-0 group-hover:opacity-100 transition hover:bg-zinc-500/10 hover:dark:bg-zinc-700/25 rounded-lg text-sm text-gray-400 hover:text-gray-600 dark:text-gray-500 dark:hover:text-gray-400"
+              disabled={isCopied}
+              onClick={() => {
+                setIsCopied(true);
+                navigator.clipboard.writeText(
+                  tokens
+                    .map((line) => line.map(({ content }) => content).join(""))
+                    .join("\n"),
+                );
+                setTimeout(() => setIsCopied(false), 2000);
+              }}
+            >
+              {isCopied ? (
+                <CheckIcon className="text-emerald-600" size={18} />
+              ) : (
+                <CopyIcon size={18} />
+              )}
+            </button>
+          )}
+          <span className="absolute top-1.5 right-3 text-[11px] font-mono text-muted-foreground transition group-hover:opacity-0">
+            {props.language}
+          </span>
+          {tokens.map((line, i) => (
+            <div key={i} {...getLineProps({ line })}>
+              {line.map((token, key) => (
+                <span key={key} {...getTokenProps({ token })} />
+              ))}
+            </div>
+          ))}
+        </pre>
+      )}
+    </Highlight>
+  );
+};

package/src/app/components/TopNavigation.tsx

@@ -0,0 +1,32 @@
+import { cx } from "class-variance-authority";
+import { NavLink } from "react-router-dom";
+
+import { useDevPortal } from "./context/DevPortalProvider.js";
+
+export const TopNavigation = () => {
+  const { navigation } = useDevPortal();
+
+  return (
+    <nav className="border-b border-border text-sm px-12 h-[--top-nav-height]">
+      <ul className="flex flex-row items-center gap-8">
+        {navigation.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.path}
+            >
+              {item.label}
+            </NavLink>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  );
+};

package/src/app/components/context/ComponentsContext.tsx

@@ -0,0 +1,24 @@
+import {
+  createContext,
+  useContext,
+  type ComponentProps,
+  type ComponentType,
+} from "react";
+import { Header } from "../Header.js";
+
+export const DEFAULT_COMPONENTS = {
+  Header,
+};
+
+export type ComponentsContextType = {
+  Header?: ComponentType<ComponentProps<typeof Header>>;
+};
+
+const ComponentsContext =
+  createContext<Required<ComponentsContextType>>(DEFAULT_COMPONENTS);
+
+export const ComponentsProvider = ComponentsContext.Provider;
+
+export const useComponents = () => {
+  return useContext(ComponentsContext);
+};

package/src/app/components/context/DevPortalProvider.ts

@@ -0,0 +1,54 @@
+import { useSuspenseQuery } from "@tanstack/react-query";
+import { createContext, useContext } from "react";
+import { matchPath, useLocation } from "react-router-dom";
+import { DevPortalContext } from "../../core/DevPortalContext.js";
+
+const DevPortalReactContext = createContext<DevPortalContext | undefined>(
+  undefined,
+);
+
+export const DevPortalProvider = DevPortalReactContext.Provider;
+
+export const useDevPortal = () => {
+  const context = useContext(DevPortalReactContext);
+
+  if (!context) {
+    throw new Error("useDevPortal must be used within a DevPortalProvider.");
+  }
+
+  return context;
+};
+
+export const useApiIdentities = () => {
+  const { getApiIdentities } = useDevPortal();
+  return useSuspenseQuery({
+    queryFn: getApiIdentities,
+    queryKey: ["api-keys"],
+  });
+};
+
+export const useTopNavigationItem = () => {
+  const { navigation } = useDevPortal();
+  const location = useLocation();
+
+  return navigation.find((item) =>
+    matchPath({ path: item.path, end: false }, location.pathname),
+  );
+};
+
+export const useNavigation = () => {
+  const { getNavigation } = useDevPortal();
+  const navItem = useTopNavigationItem();
+
+  const path = navItem?.path ?? "";
+
+  return useSuspenseQuery({
+    queryFn: async () => {
+      return {
+        items: [...(navItem?.categories ?? []), ...(await getNavigation(path))],
+        currentTopNavItem: navItem,
+      };
+    },
+    queryKey: ["navigation", path],
+  });
+};

package/src/app/components/context/ThemeContext.tsx

@@ -0,0 +1,46 @@
+import {
+  createContext,
+  type ReactNode,
+  useCallback,
+  useEffect,
+  useState,
+  useContext,
+} from "react";
+
+const ThemeContext = createContext<readonly [boolean, () => void]>([
+  false,
+  () => {},
+]);
+
+export const useTheme = () => {
+  const context = useContext(ThemeContext);
+  if (!context) {
+    throw new Error("useTheme must be used within a ThemeProvider");
+  }
+  return context;
+};
+
+export const ThemeProvider = (props: { children: ReactNode }) => {
+  const [dark, setDark] = useState(false);
+
+  // On mount, read the preferred theme from the persistence
+  useEffect(() => {
+    const theme = localStorage.getItem("theme");
+    const prefersDark = window.matchMedia("(prefers-color-scheme: dark)");
+    const isDark = theme === "dark" || (!theme && prefersDark.matches);
+
+    setDark(isDark);
+  }, [dark]);
+
+  // To toggle between dark and light modes
+  const toggle = useCallback(() => {
+    const toggled = !dark;
+    document.documentElement.classList.toggle("dark", toggled);
+    localStorage.setItem("theme", toggled ? "dark" : "light");
+    setDark(toggled);
+  }, [dark]);
+
+  const value = [dark, toggle] as const;
+
+  return <ThemeContext.Provider value={value} {...props} />;
+};

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

@@ -0,0 +1,139 @@
+import {
+  type ReactNode,
+  createContext,
+  useCallback,
+  useContext,
+  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 | undefined>(
+  undefined,
+);
+
+export const useViewportAnchor = () => {
+  const context = useContext(ViewportAnchorContext);
+
+  if (!context) {
+    throw new Error(
+      "useViewportAnchor must be used within a CurrentAnchorProvider",
+    );
+  }
+
+  return context;
+};
+
+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,
+}: {
+  children: ReactNode;
+}) => {
+  const [activeAnchor, setActiveAnchor] = useState("");
+  const observerRef = useRef<IntersectionObserver | null>(null);
+  const registeredElements = 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);
+          }
+        }
+      },
+      {
+        // 115px is the height of the sticky header
+        // see --header-height in `main.css`
+        rootMargin: "115px 0px -80% 0px",
+        threshold: 0.75,
+      },
+    );
+
+    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) {
+        // 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 ?? "");
+        });
+      }
+    };
+
+    document.addEventListener("scroll", handleScroll);
+
+    return () => {
+      elements.clear();
+      document.removeEventListener("scroll", handleScroll);
+    };
+  }, []);
+
+  const observeFns = useMemo(() => {
+    return {
+      observe: (element: HTMLElement | null) => {
+        if (!element || !observerRef.current) return;
+        registeredElements.current.add(element);
+        observerRef.current.observe(element);
+      },
+      unobserve: (element: HTMLElement | null) => {
+        if (!element || !observerRef.current) return;
+        registeredElements.current.delete(element);
+        observerRef.current.unobserve(element);
+      },
+    };
+  }, []);
+
+  const value = useMemo(
+    () => ({ activeAnchor, setActiveAnchor, ...observeFns }),
+    [activeAnchor, setActiveAnchor, observeFns],
+  );
+
+  return (
+    <ViewportAnchorContext.Provider value={value}>
+      {children}
+    </ViewportAnchorContext.Provider>
+  );
+};

package/src/app/components/navigation/SideNavigation.tsx

@@ -0,0 +1,18 @@
+import { useRef } from "react";
+
+import { useNavigation } from "../context/DevPortalProvider.js";
+import { SideNavigationCategory } from "./SideNavigationCategory.js";
+import { SideNavigationWrapper } from "./SideNavigationWrapper.js";
+
+export const SideNavigation = () => {
+  const navRef = useRef<HTMLDivElement | null>(null);
+  const navigation = useNavigation();
+
+  return (
+    <SideNavigationWrapper ref={navRef}>
+      {navigation.data.items.map((category) => (
+        <SideNavigationCategory key={category.label} category={category} />
+      ))}
+    </SideNavigationWrapper>
+  );
+};

package/src/app/components/navigation/SideNavigationCategory.tsx

@@ -0,0 +1,74 @@
+import * as Collapsible from "@radix-ui/react-collapsible";
+import { ChevronRightIcon } from "lucide-react";
+import { useLocation } from "react-router-dom";
+import type { NavigationCategory } from "../../core/DevPortalContext.js";
+import { cn } from "../../util/cn.js";
+import { joinPath } from "../../util/joinPath.js";
+import { useTopNavigationItem } from "../context/DevPortalProvider.js";
+import { useViewportAnchor } from "../context/ViewportAnchorContext.js";
+import { SideNavigationItem } from "./SideNavigationItem.js";
+import { useNavigationCollapsibleState } from "./useNavigationCollapsibleState.js";
+import { checkHasActiveItem, isPathItem } from "./util.js";
+
+export const SideNavigationCategory = ({
+  category,
+}: {
+  category: NavigationCategory;
+}) => {
+  const { activeAnchor } = useViewportAnchor();
+  const navItem = useTopNavigationItem();
+  const location = useLocation();
+
+  const isCollapsible = category.collapsible ?? true;
+
+  const [isOpen, setIsOpen] = useNavigationCollapsibleState({
+    item: category,
+    path: navItem?.path ?? "",
+    defaultOpen: () =>
+      !isCollapsible ||
+      category.expanded ||
+      checkHasActiveItem(category, location.pathname, navItem?.path ?? ""),
+  });
+
+  return (
+    <Collapsible.Root
+      key={category.label}
+      open={isOpen}
+      onOpenChange={() => setIsOpen((prev) => !prev)}
+    >
+      {category.label.length > 0 && (
+        <Collapsible.Trigger asChild={isCollapsible} disabled={!isCollapsible}>
+          <h5
+            className={cn(
+              "flex group items-center justify-between cursor-pointer font-semibold text-foreground/90 px-[--padding-nav-item] py-1.5 rounded-lg transition-colors duration-300 -mx-[--padding-nav-item]",
+              isCollapsible ? "hover:bg-accent" : "cursor-auto",
+            )}
+          >
+            {category.label}
+            {isCollapsible && (
+              <ChevronRightIcon
+                className="group-data-[state=open]:rotate-90 transition"
+                size={16}
+              />
+            )}
+          </h5>
+        </Collapsible.Trigger>
+      )}
+      <Collapsible.Content className="CollapsibleContent -mx-[--padding-nav-item]">
+        {/* margin on Collapsible.Content will lead jumpiness when animating because it's not added to the calculated height */}
+        <ul className="space-y-0.5 mt-1.5 mb-4 ms-3">
+          {category.children.map((item) => (
+            <SideNavigationItem
+              key={isPathItem(item) ? item.path + item.label : item.href}
+              category={category}
+              item={item}
+              activeAnchor={activeAnchor}
+              currentTopNavItem={navItem}
+              basePath={joinPath(navItem?.path, category.path)}
+            />
+          ))}
+        </ul>
+      </Collapsible.Content>
+    </Collapsible.Root>
+  );
+};

package/src/app/components/navigation/SideNavigationItem.tsx

@@ -0,0 +1,143 @@
+import * as Collapsible from "@radix-ui/react-collapsible";
+import { cva } from "class-variance-authority";
+import { ChevronRightIcon, ExternalLinkIcon } from "lucide-react";
+import { NavLink, useLocation } from "react-router-dom";
+
+import type {
+  NavigationCategory,
+  NavigationCategoryItem,
+  NavigationItem,
+} from "../../core/DevPortalContext.js";
+import { cn } from "../../util/cn.js";
+import { joinPath } from "../../util/joinPath.js";
+import { AnchorLink } from "../AnchorLink.js";
+import { DynamicIcon, isValidIcon } from "../DynamicIcon.js";
+import { useNavigationCollapsibleState } from "./useNavigationCollapsibleState.js";
+import { checkHasActiveItem, isLinkItem, isPathItem } from "./util.js";
+
+export const linkItem = cva(
+  "flex px-[--padding-nav-item] py-1.5 rounded-lg hover:bg-accent transition-colors duration-300",
+  {
+    variants: {
+      isActive: {
+        true: "text-primary font-medium",
+        false: "text-foreground/80",
+      },
+    },
+  },
+);
+
+export const DATA_ANCHOR_ATTR = "data-anchor";
+
+export const SideNavigationItem = ({
+  category,
+  item,
+  activeAnchor,
+  currentTopNavItem,
+  basePath = "",
+}: {
+  category: NavigationCategory;
+  item: NavigationCategoryItem;
+  activeAnchor?: string;
+  currentTopNavItem?: NavigationItem;
+  basePath?: string;
+}) => {
+  const currentPath = isPathItem(item) ? joinPath(basePath, item.path) : "";
+  const location = useLocation();
+
+  const [isOpen, setIsOpen] = useNavigationCollapsibleState({
+    item,
+    path: currentPath,
+    defaultOpen: () => checkHasActiveItem(item, location.pathname, currentPath),
+  });
+
+  if (isLinkItem(item)) {
+    const classes = cn(
+      "flex items-center gap-2",
+      linkItem({ isActive: item.href === location.pathname }),
+    );
+    return item.href.startsWith("http") ? (
+      <a
+        className={classes}
+        href={item.href}
+        target="_blank"
+        rel="noopener noreferrer"
+      >
+        {item.label}
+        <ExternalLinkIcon size={14} />
+      </a>
+    ) : (
+      <NavLink className={classes} to={item.href}>
+        {item.label}
+      </NavLink>
+    );
+  }
+
+  const linkContent = (
+    <div className="flex justify-between w-full">
+      <div className="flex items-center gap-2 truncate w-full">
+        {isValidIcon(item.icon) && <DynamicIcon name={item.icon} size={16} />}
+        {typeof item.label !== "string" ? (
+          item.label
+        ) : (
+          <span className="truncate">{item.label}</span>
+        )}
+      </div>
+      {item.children && (
+        <ChevronRightIcon
+          size={16}
+          className="transition shrink-0 group-data-[state=open]:rotate-90"
+        />
+      )}
+    </div>
+  );
+
+  return (
+    <li title={typeof item.label === "string" ? item.label : item.title}>
+      {item.children ? (
+        <Collapsible.Root
+          open={isOpen}
+          onOpenChange={() => setIsOpen((prev) => !prev)}
+          className="flex flex-col"
+        >
+          <Collapsible.Trigger
+            className={cn("group text-start", linkItem({ isActive: false }))}
+          >
+            {linkContent}
+          </Collapsible.Trigger>
+          <Collapsible.Content className="CollapsibleContent ms-[calc(var(--padding-nav-item)*1.125)]">
+            <ul className="mt-1 border-border border-l ps-1.5">
+              {item.children.map((child) => (
+                <SideNavigationItem
+                  key={isPathItem(child) ? child.path : child.href}
+                  category={category}
+                  item={child}
+                  activeAnchor={activeAnchor}
+                  currentTopNavItem={currentTopNavItem}
+                  basePath={currentPath}
+                />
+              ))}
+            </ul>
+          </Collapsible.Content>
+        </Collapsible.Root>
+      ) : item.path.startsWith("#") ? (
+        <AnchorLink
+          to={item.path}
+          {...{ [DATA_ANCHOR_ATTR]: item.path }}
+          className={linkItem({
+            isActive: item.path.slice(1) === activeAnchor,
+          })}
+        >
+          {linkContent}
+        </AnchorLink>
+      ) : (
+        <NavLink
+          className={({ isActive }) => linkItem({ isActive })}
+          to={currentPath}
+        >
+          {linkContent}
+        </NavLink>
+      )}
+    </li>
+  );
+};

package/src/app/components/navigation/SideNavigationWrapper.tsx

@@ -0,0 +1,15 @@
+import { forwardRef, type PropsWithChildren } from "react";
+
+export const SideNavigationWrapper = forwardRef<
+  HTMLDivElement,
+  PropsWithChildren
+>(({ children }, ref) => {
+  return (
+    <nav
+      className="hidden lg:flex flex-col fixed text-sm overflow-y-auto shrink-0 p-[--padding-nav-item] -mx-[--padding-nav-item] pb-20 pt-[--padding-content-top] w-[--side-nav-width] h-[calc(100%-var(--header-height))] scroll-pt-2 gap-2"
+      ref={ref}
+    >
+      {children}
+    </nav>
+  );
+});

package/src/app/components/navigation/useNavigationCollapsibleState.ts

@@ -0,0 +1,27 @@
+import { useEffect, useRef, useState } from "react";
+import { useLocation } from "react-router-dom";
+import type { NavigationNode } from "../../util/traverseNavigation.js";
+import { checkHasActiveItem } from "./util.js";
+
+export const useNavigationCollapsibleState = ({
+  item,
+  defaultOpen,
+  path,
+}: {
+  item: NavigationNode;
+  defaultOpen: () => boolean;
+  path: string;
+}) => {
+  const [isOpen, setIsOpen] = useState(defaultOpen);
+  const location = useLocation();
+  const previousLocationPath = useRef(location.pathname);
+
+  useEffect(() => {
+    if (!isOpen && previousLocationPath.current !== location.pathname) {
+      setIsOpen(checkHasActiveItem(item, location.pathname, path));
+    }
+    previousLocationPath.current = location.pathname;
+  }, [isOpen, item, path, location.pathname]);
+
+  return [isOpen, setIsOpen] as const;
+};