zudoku 0.3.0-dev.9 → 0.3.0-dev.91

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

@@ -0,0 +1,58 @@
+import { useQuery, useSuspenseQuery } from "@tanstack/react-query";
+import { createContext, useContext } from "react";
+import { useLocation } from "react-router-dom";
+import { DevPortalContext } from "../../core/DevPortalContext.js";
+
+export const ZudokuReactContext = createContext<DevPortalContext | undefined>(
+  undefined,
+);
+
+export const useZudoku = () => {
+  const context = useContext(ZudokuReactContext);
+
+  if (!context) {
+    throw new Error("useDevPortal must be used within a DevPortalProvider.");
+  }
+
+  return context;
+};
+
+export const useApiIdentities = () => {
+  const { getApiIdentities } = useZudoku();
+  return useQuery({
+    queryFn: getApiIdentities,
+    queryKey: ["api-identities"],
+  });
+};
+
+export const useTopNavigationItem = () => {
+  const { topNavigation } = useZudoku();
+  const location = useLocation();
+
+  const firstPart = location.pathname.split("/").at(1);
+  if (!firstPart) return;
+
+  return topNavigation.find((item) => item.id === firstPart);
+};
+
+export const useNavigation = () => {
+  const { getPluginSidebar, sidebars } = useZudoku();
+  const navItem = useTopNavigationItem();
+  const path = navItem?.id;
+  const currentSidebar = path ? sidebars[path] ?? [] : [];
+  const location = useLocation();
+
+  return useSuspenseQuery({
+    queryFn: async () => {
+      const pluginSidebar = path
+        ? await getPluginSidebar(path)
+        : await getPluginSidebar(location.pathname);
+
+      return {
+        items: [...currentSidebar, ...pluginSidebar],
+        currentTopNavItem: navItem,
+      };
+    },
+    queryKey: ["navigation", path],
+  });
+};

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

@@ -0,0 +1,26 @@
+import { useSuspenseQuery } from "@tanstack/react-query";
+import type { PropsWithChildren } from "react";
+import { useNavigate } from "react-router-dom";
+import { DevPortalContext } from "../../core/DevPortalContext.js";
+import { ZudokuReactContext } from "./ZudokuContext.js";
+
+export const ZudokuProvider = ({
+  children,
+  context,
+}: PropsWithChildren<{ context: DevPortalContext }>) => {
+  const navigate = useNavigate();
+
+  useSuspenseQuery({
+    queryFn: async () => {
+      await context.initialize({ navigate });
+      return true;
+    },
+    queryKey: ["zudoku-initialize"],
+  });
+
+  return (
+    <ZudokuReactContext.Provider value={context}>
+      {children}
+    </ZudokuReactContext.Provider>
+  );
+};

package/src/lib/components/index.ts

@@ -1,3 +1,25 @@
-export { useMDXComponents } from "@mdx-js/react";
-export { DevPortal } from "./DevPortal.js";
-export { Link } from "./Link.js";
+import { useMDXComponents as useMDXComponentsImport } from "@mdx-js/react";
+import { Helmet } from "@zudoku/react-helmet-async";
+import { Link as LinkImport } from "react-router-dom";
+import { RouterError as RouterErrorImport } from "../errors/RouterError.js";
+import { ServerError as ServerErrorImport } from "../errors/ServerError.js";
+import { Button as ButtonImport } from "../ui/Button.js";
+import { Callout as CalloutImport } from "../ui/Callout.js";
+import {
+  Bootstrap as BootstrapImport,
+  BootstrapStatic as BootstrapStaticImport,
+} from "./Bootstrap.js";
+import { DevPortal as DevPortalImport } from "./DevPortal.js";
+import { Layout as LayoutImport } from "./Layout.js";
+
+export const useMDXComponents = /*@__PURE__*/ useMDXComponentsImport;
+export const Callout = /*@__PURE__*/ CalloutImport;
+export const DevPortal = /*@__PURE__*/ DevPortalImport;
+export const Layout = /*@__PURE__*/ LayoutImport;
+export const Link = /*@__PURE__*/ LinkImport;
+export const RouterError = /*@__PURE__*/ RouterErrorImport;
+export const ServerError = /*@__PURE__*/ ServerErrorImport;
+export const Bootstrap = /*@__PURE__*/ BootstrapImport;
+export const BootstrapStatic = /*@__PURE__*/ BootstrapStaticImport;
+export const Button = /*@__PURE__*/ ButtonImport;
+export const Head = /*@__PURE__*/ Helmet;

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

@@ -0,0 +1,24 @@
+import { useRef } from "react";
+
+import { useNavigation } from "../context/ZudokuContext.js";
+import { Slotlet } from "../SlotletProvider.js";
+import { SidebarItem } from "./SidebarItem.js";
+import { SidebarWrapper } from "./SidebarWrapper.js";
+
+export const Sidebar = () => {
+  const navRef = useRef<HTMLDivElement | null>(null);
+  const navigation = useNavigation();
+
+  return (
+    <SidebarWrapper
+      ref={navRef}
+      pushMainContent={navigation.data.items.length > 0}
+    >
+      <Slotlet name="zudoku-before-navigation" />
+      {navigation.data.items.map((item) => (
+        <SidebarItem key={item.label} item={item} />
+      ))}
+      <Slotlet name="zudoku-after-navigation" />
+    </SidebarWrapper>
+  );
+};

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

@@ -0,0 +1,40 @@
+import { cn } from "../../util/cn.js";
+
+export const TextColorMap = {
+  green: "text-green-600",
+  blue: "text-sky-600",
+  yellow: "text-yellow-600",
+  red: "text-red-600",
+  purple: "text-purple-600",
+  indigo: "text-indigo-600",
+  gray: "text-gray-600",
+};
+
+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",
+};
+
+export const SidebarBadge = ({
+  color,
+  label,
+}: {
+  color: keyof typeof ColorMap;
+  label: string;
+}) => {
+  return (
+    <span
+      className={cn(
+        "mt-0.5 flex items-center duration-200 transition-opacity text-center uppercase font-mono text-[0.65rem] font-bold rounded text-background dark:text-zinc-50 h-4 px-1",
+        ColorMap[color],
+      )}
+    >
+      {label}
+    </span>
+  );
+};

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

@@ -0,0 +1,105 @@
+import * as Collapsible from "@radix-ui/react-collapsible";
+import { ChevronRightIcon } from "lucide-react";
+import { useEffect, useState } from "react";
+import { NavLink } from "react-router-dom";
+import type { SidebarItemCategory } from "../../../config/validators/SidebarSchema.js";
+import { cn } from "../../util/cn.js";
+import { joinPath } from "../../util/joinPath.js";
+import { useTopNavigationItem } from "../context/ZudokuContext.js";
+import { navigationListItem, SidebarItem } from "./SidebarItem.js";
+import { useIsCategoryOpen } from "./utils.js";
+
+export const SidebarCategory = ({
+  category,
+  level,
+}: {
+  category: SidebarItemCategory;
+  level: number;
+}) => {
+  const topNavItem = useTopNavigationItem();
+  const isCategoryOpen = useIsCategoryOpen(category);
+
+  const isCollapsible = category.collapsible ?? true;
+  const isCollapsed = category.collapsed ?? true;
+  const isDefaultOpen = Boolean(
+    !isCollapsible || !isCollapsed || isCategoryOpen,
+  );
+  const [open, setOpen] = useState(isDefaultOpen);
+
+  useEffect(() => {
+    // this is triggered when an item from the sidebar is clicked
+    // and the sidebar, enclosing this item, is not opened
+    if (isCategoryOpen) {
+      setOpen(true);
+    }
+  }, [isCategoryOpen]);
+
+  const ToggleButton = isCollapsible && (
+    <button
+      type="button"
+      onClick={(e) => {
+        e.preventDefault();
+        setOpen((prev) => !prev);
+      }}
+    >
+      <ChevronRightIcon
+        size={16}
+        className="transition shrink-0 group-data-[state=open]:rotate-90"
+      />
+    </button>
+  );
+
+  return (
+    <Collapsible.Root
+      className={cn("flex flex-col", level === 0 && "-mx-[--padding-nav-item]")}
+      defaultOpen={isDefaultOpen}
+      open={open}
+      onOpenChange={() => setOpen(true)}
+    >
+      <Collapsible.Trigger
+        className={cn(
+          "group text-start",
+          navigationListItem({ isActive: false, isTopLevel: level === 0 }),
+          isCollapsible
+            ? "cursor-pointer"
+            : "cursor-default hover:bg-transparent",
+        )}
+        asChild
+        disabled={!isCollapsible}
+      >
+        {category.link?.type === "doc" ? (
+          <NavLink to={joinPath(topNavItem?.id, category.link.id)}>
+            {({ isActive }) => (
+              <div
+                className={cn(
+                  "flex items-center gap-2 justify-between w-full",
+                  isActive ? "text-primary font-medium" : "text-foreground/80",
+                )}
+              >
+                <div className="truncate">{category.label}</div>
+                {ToggleButton}
+              </div>
+            )}
+          </NavLink>
+        ) : (
+          <div className="flex items-center justify-between w-full">
+            <div className="flex gap-2 truncate w-full">{category.label}</div>
+            {ToggleButton}
+          </div>
+        )}
+      </Collapsible.Trigger>
+      <Collapsible.Content className="CollapsibleContent ms-[calc(var(--padding-nav-item)*1.125)]">
+        <ul className="mt-1 border-l ps-2">
+          {category.items.map((item) => (
+            <SidebarItem
+              key={item.label}
+              level={level + 1}
+              item={item}
+              // activeAnchor={activeAnchor}
+            />
+          ))}
+        </ul>
+      </Collapsible.Content>
+    </Collapsible.Root>
+  );
+};

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

@@ -0,0 +1,100 @@
+import { cva } from "class-variance-authority";
+import { ExternalLinkIcon } from "lucide-react";
+import { NavLink } from "react-router-dom";
+
+import type { SidebarItem as SidebarItemType } from "../../../config/validators/SidebarSchema.js";
+import { cn } from "../../util/cn.js";
+import { joinPath } from "../../util/joinPath.js";
+import { AnchorLink } from "../AnchorLink.js";
+import { useViewportAnchor } from "../context/ViewportAnchorContext.js";
+import { useTopNavigationItem } from "../context/ZudokuContext.js";
+import { SidebarBadge } from "./SidebarBadge.js";
+import { SidebarCategory } from "./SidebarCategory.js";
+
+export const navigationListItem = cva(
+  "flex px-[--padding-nav-item] py-1.5 rounded-lg hover:bg-accent transition-colors duration-300",
+  {
+    variants: {
+      isTopLevel: {
+        true: "font-semibold",
+      },
+      isActive: {
+        true: "text-primary font-medium",
+        false: "text-foreground/80",
+      },
+      isMuted: {
+        true: "text-foreground/30",
+        false: "",
+      },
+    },
+  },
+);
+
+export const DATA_ANCHOR_ATTR = "data-anchor";
+
+export const SidebarItem = ({
+  item,
+  level = 0,
+}: {
+  item: SidebarItemType;
+  basePath?: string;
+  level?: number;
+}) => {
+  const topNavItem = useTopNavigationItem();
+  const { activeAnchor } = useViewportAnchor();
+
+  switch (item.type) {
+    case "category":
+      return <SidebarCategory category={item} level={level} />;
+    case "doc":
+      return (
+        <NavLink
+          className={({ isActive }) =>
+            navigationListItem({ isActive, isTopLevel: level === 0 })
+          }
+          to={joinPath(topNavItem?.id, item.id)}
+        >
+          {item.label}
+          {item.badge && <SidebarBadge {...item.badge} />}
+        </NavLink>
+      );
+    case "link":
+      return item.href.startsWith("#") ? (
+        <AnchorLink
+          to={item.href}
+          {...{ [DATA_ANCHOR_ATTR]: item.href.slice(1) }}
+          className={cn(
+            "flex gap-2.5 justify-between",
+            level === 0 && "-mx-[--padding-nav-item]",
+            navigationListItem({
+              isActive: item.href.slice(1) === activeAnchor,
+            }),
+          )}
+        >
+          {item.label}
+          {item.badge && <SidebarBadge {...item.badge} />}
+        </AnchorLink>
+      ) : item.href.startsWith("http") ? (
+        <a
+          className={cn(
+            navigationListItem({ isTopLevel: level === 0 }),
+            "block",
+          )}
+          href={item.href}
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          <span className="whitespace-normal">{item.label}</span>
+          {/* This prevents that the icon would be positioned in its own line if the text fills an line entirely */}
+          <span className="whitespace-nowrap">
+            &nbsp;
+            <ExternalLinkIcon className="inline ml-1" size={12} />
+          </span>
+        </a>
+      ) : (
+        <NavLink className={cn(navigationListItem({}), "block")} to={item.href}>
+          {item.label}
+        </NavLink>
+      );
+  }
+};

package/src/lib/components/navigation/{SideNavigationWrapper.tsx → SidebarWrapper.tsx}

@@ -1,7 +1,7 @@
 import { forwardRef, type PropsWithChildren } from "react";
 import { cn } from "../../util/cn.js";
 
-export const SideNavigationWrapper = forwardRef<
+export const SidebarWrapper = forwardRef<
   HTMLDivElement,
   PropsWithChildren<{ pushMainContent?: boolean; className?: string }>
 >(function SideNavigation({ children, className, pushMainContent }, ref) {

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

@@ -0,0 +1,117 @@
+import { useLocation } from "react-router-dom";
+import type {
+  SidebarItem,
+  SidebarItemCategory,
+} from "../../../config/validators/SidebarSchema.js";
+import { joinPath } from "../../util/joinPath.js";
+import { useTopNavigationItem, useZudoku } from "../context/ZudokuContext.js";
+
+export type TraverseCallback<T> = (
+  item: SidebarItem,
+  parentCategories: SidebarItem[],
+) => T | void;
+
+export const traverseSidebar = <T>(
+  sidebar: SidebarItem[],
+  callback: TraverseCallback<T>,
+): T | undefined => {
+  for (const item of sidebar) {
+    const result = traverseSidebarItem(item, callback);
+    if (result !== undefined) return result;
+  }
+};
+
+export const traverseSidebarItem = <T>(
+  item: SidebarItem,
+  callback: TraverseCallback<T>,
+  parentCategories: SidebarItem[] = [],
+): T | undefined => {
+  const result = callback(item, parentCategories);
+  if (result !== undefined) return result;
+
+  if (item.type === "category") {
+    for (const child of item.items) {
+      const childResult = traverseSidebarItem(child, callback, [
+        ...parentCategories,
+        item,
+      ]);
+      if (childResult !== undefined) return childResult;
+    }
+  }
+};
+
+export const useCurrentItem = () => {
+  const location = useLocation();
+  const topNavItem = useTopNavigationItem();
+  const { sidebars } = useZudoku();
+  const currentSidebar = topNavItem?.id ? sidebars[topNavItem.id] : [];
+
+  return traverseSidebar(currentSidebar, (item) => {
+    if (
+      item.type === "doc" &&
+      joinPath(topNavItem?.id, item.id) === location.pathname
+    ) {
+      return item;
+    }
+  });
+};
+
+export const useIsCategoryOpen = (category: SidebarItemCategory) => {
+  const location = useLocation();
+  const topNavItem = useTopNavigationItem();
+
+  return traverseSidebarItem(category, (item) => {
+    if (item.type === "category" && item.link) {
+      const categoryLinkPath = joinPath(topNavItem?.id, item.link.id);
+      if (categoryLinkPath === location.pathname) {
+        return true;
+      }
+    }
+
+    if (item.type === "doc") {
+      const docPath = joinPath(topNavItem?.id, item.id);
+      if (docPath === location.pathname) {
+        return true;
+      }
+    }
+  });
+};
+
+export const usePrevNext = (): {
+  prev?: { label: string; id: string };
+  next?: { label: string; id: string };
+} => {
+  const currentId = useLocation().pathname;
+  const { sidebars } = useZudoku();
+  const topNavItem = useTopNavigationItem();
+  const currentSidebar = topNavItem?.id ? sidebars[topNavItem.id] : [];
+
+  let prev;
+  let next;
+
+  let foundCurrent = false;
+
+  traverseSidebar(currentSidebar, (item) => {
+    const itemId =
+      item.type === "doc"
+        ? joinPath(topNavItem?.id, item.id)
+        : item.type === "category" && item.link
+          ? joinPath(topNavItem?.id, item.link.id)
+          : 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 };
+};