zudoku 0.3.0-dev.9 → 0.3.0-dev.90

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 };
+};

package/src/lib/core/DevPortalContext.ts

@@ -1,17 +1,17 @@
 import { QueryClient } from "@tanstack/react-query";
-import { type ReactNode } from "react";
-import { create } from "zustand";
+import { NavigateFunction } from "react-router-dom";
+import type { SidebarConfig } from "../../config/validators/SidebarSchema.js";
 import { type AuthenticationProvider } from "../authentication/authentication.js";
+import type { ComponentsContextType } from "../components/context/ComponentsContext.js";
+import { Slotlets } from "../components/SlotletProvider.js";
+import { joinPath } from "../util/joinPath.js";
+import type { MdxComponentsType } from "../util/MdxComponents.js";
 import {
-  type DevPortalPath,
-  type DevPortalProps,
-} from "../components/DevPortal.js";
-import {
+  type DevPortalPlugin,
   isApiIdentityPlugin,
   isNavigationPlugin,
-  needsInitialization,
-  type DevPortalPlugin,
   type NavigationPlugin,
+  needsInitialization,
 } from "./plugins.js";
 
 export interface ApiIdentity {
@@ -20,76 +20,80 @@ export interface ApiIdentity {
   id: string;
 }
 
-type BaseNavigationCategoryItem = {
-  label: ReactNode;
-  title?: string;
-  muted?: boolean;
-  icon?: ReactNode;
-};
-
-export type PathNavigationCategoryItem = BaseNavigationCategoryItem & {
-  path: string;
-  children?: NavigationCategoryItem[];
-};
-
-export type HrefNavigationCategoryItem = BaseNavigationCategoryItem & {
-  href: string;
-};
-
-export type NavigationCategoryItem =
-  | PathNavigationCategoryItem
-  | HrefNavigationCategoryItem;
-
-export type NavigationCategory = {
-  label: string;
-  path?: string;
-  expanded?: boolean;
-  collapsible?: boolean;
-  icon?: ReactNode;
-  children: NavigationCategoryItem[];
-};
-
-export type NavigationItem = {
-  label: string;
-  path: DevPortalPath;
-  categories?: NavigationCategory[];
-};
-
-export type RoutingState = {
-  path?: string;
-};
-
 export const queryClient = new QueryClient();
 
-export const useRoutingState = create<RoutingState>(() => ({}));
-
 export type ApiKeyCache = "api-keys";
 export type DevPortalCacheKey = ApiKeyCache | string;
 
+type Metadata = Partial<{
+  title: string;
+  description: string;
+  logo: string;
+  favicon: string;
+  generator: string;
+  applicationName: string;
+  referrer: string;
+  keywords: string[];
+  authors: string[];
+  creator: string;
+  publisher: string;
+}>;
+
+type Page = Partial<{
+  pageTitle?: string;
+  logo?: {
+    src: {
+      light: string;
+      dark: string;
+    };
+    width?: string;
+    alt?: string;
+  };
+}>;
+
+export type ZudokuContextOptions = {
+  metadata?: Metadata;
+  page?: Page;
+  authentication?: AuthenticationProvider;
+  topNavigation?: Array<{ id: string; label: string }>;
+  sidebars?: SidebarConfig;
+  plugins?: DevPortalPlugin[];
+  slotlets?: Slotlets;
+  mdx?: {
+    components?: MdxComponentsType;
+  };
+  overrides?: ComponentsContextType;
+};
+
 export class DevPortalContext {
-  private plugins: DevPortalPlugin[] = [];
+  public plugins: NonNullable<ZudokuContextOptions["plugins"]>;
+  public sidebars: NonNullable<ZudokuContextOptions["sidebars"]>;
+  public topNavigation: NonNullable<ZudokuContextOptions["topNavigation"]>;
+  public meta: ZudokuContextOptions["metadata"];
+  public page: ZudokuContextOptions["page"];
+  public authentication?: ZudokuContextOptions["authentication"];
   private navigationPlugins: NavigationPlugin[];
 
-  public navigation: NavigationItem[];
-  public meta: DevPortalProps["meta"];
-  public authentication?: AuthenticationProvider;
-  public state: typeof useRoutingState;
-
-  constructor(config: DevPortalProps) {
+  constructor(config: ZudokuContextOptions) {
     this.plugins = config.plugins ?? [];
-    this.navigation = config.navigation;
+    this.topNavigation = config.topNavigation ?? [];
+    this.sidebars = config.sidebars ?? {};
     this.navigationPlugins = this.plugins.filter(isNavigationPlugin);
     this.authentication = config.authentication;
-    this.meta = config.meta;
-    this.state = useRoutingState;
+    this.meta = config.metadata;
+    this.page = config.page;
   }
 
-  initialize = async () => {
-    await Promise.all([
+  initialize = async ({
+    navigate,
+  }: {
+    navigate: NavigateFunction;
+  }): Promise<void> => {
+    await Promise.all(
       this.plugins
         .filter(needsInitialization)
-        .map((plugin) => plugin.initialize(this)),
-    ]);
+        .map((plugin) => plugin.initialize?.(this, { navigate })),
+    );
   };
 
   invalidateCache = async (key: DevPortalCacheKey[]) => {
@@ -106,17 +110,17 @@ export class DevPortalContext {
     return keys.flat();
   };
 
-  getNavigation = async (path: string) => {
+  getPluginSidebar = async (path: string) => {
     const navigations = await Promise.all(
-      this.navigationPlugins.map(async (plugin) =>
-        plugin.getNavigation?.(path),
+      this.navigationPlugins.map((plugin) =>
+        plugin.getSidebar?.(joinPath(path)),
       ),
     );
 
     return navigations.flatMap((nav) => nav ?? []);
   };
 
-  async signRequest(request: Request) {
+  signRequest = async (request: Request) => {
     if (!this.authentication) {
       throw new Error("No authentication provider configured");
     }
@@ -126,5 +130,5 @@ export class DevPortalContext {
     request.headers.set("Authorization", `Bearer ${accessToken}`);
 
     return request;
-  }
+  };
 }