zudoku 0.3.0-dev.7 → 0.3.0-dev.70

package/src/lib/components/InlineCode.tsx

@@ -0,0 +1,19 @@
+import type { ReactNode } from "react";
+import { cn } from "../util/cn.js";
+
+export const InlineCode = ({
+  className,
+  children,
+}: {
+  className?: string;
+  children: ReactNode;
+}) => (
+  <code
+    className={cn(
+      className,
+      "font-mono border p-1 py-0.5 rounded bg-border/50 dark:bg-border/70 whitespace-nowrap",
+    )}
+  >
+    {children}
+  </code>
+);

package/src/lib/components/Layout.tsx

@@ -1,12 +1,14 @@
+import { Helmet } from "@zudoku/react-helmet-async";
 import { Suspense, useEffect, useRef, type ReactNode } from "react";
 import { Outlet, useLocation } from "react-router-dom";
-import { Helmet } from "../core/helmet.js";
+import { cn } from "../util/cn.js";
 import { useScrollToAnchor } from "../util/useScrollToAnchor.js";
 import { useScrollToTop } from "../util/useScrollToTop.js";
 import { useDevPortal } from "./context/DevPortalProvider.js";
 import { useViewportAnchor } from "./context/ViewportAnchorContext.js";
 import { Header } from "./Header.js";
 import { SideNavigation } from "./navigation/SideNavigation.js";
+import { Slotlet } from "./SlotletProvider.js";
 import { Spinner } from "./Spinner.js";
 
 export const Layout = ({ children }: { children?: ReactNode }) => {
@@ -29,8 +31,7 @@ export const Layout = ({ children }: { children?: ReactNode }) => {
 
   return (
     <>
-      <Helmet titleTemplate={meta?.pageTitle}>
-        <title>Home</title>
+      <Helmet titleTemplate={meta?.title}>
         {meta?.description && (
           <meta name="description" content={meta.description} />
         )}
@@ -48,12 +49,16 @@ export const Layout = ({ children }: { children?: ReactNode }) => {
         >
           <SideNavigation />
           <main
-            className="dark:border-white/10 translate-x-0 h-full
-          lg:overflow-visible
-          lg:peer-data-[navigation=true]:w-[calc(100%-var(--side-nav-width))]
-          lg:peer-data-[navigation=true]:translate-x-[--side-nav-width] peer-data-[navigation=true]:pl-12"
+            className={cn(
+              "dark:border-white/10 translate-x-0 h-full",
+              "lg:overflow-visible",
+              "lg:peer-data-[navigation=true]:w-[calc(100%-var(--side-nav-width))]",
+              "lg:peer-data-[navigation=true]:translate-x-[--side-nav-width] lg:peer-data-[navigation=true]:pl-12",
+            )}
           >
+            <Slotlet name="zudoku-before-content" />
             {children ?? <Outlet />}
+            <Slotlet name="zudoku-after-content" />
           </main>
         </Suspense>
       </div>

package/src/lib/components/NotFoundPage.tsx

@@ -0,0 +1,33 @@
+import { UnlinkIcon } from "lucide-react";
+import { Link, useParams } from "react-router-dom";
+import { CategoryHeading } from "./CategoryHeading.js";
+import { DeveloperHint } from "./DeveloperHint.js";
+import { Heading } from "./Heading.js";
+import { ProseClasses } from "./Markdown.js";
+
+export const NotFoundPage = () => {
+  const params = useParams();
+
+  return (
+    <div className={ProseClasses + " h-full pt-[--padding-content-top]"}>
+      <CategoryHeading>404</CategoryHeading>
+      <Heading level={1} className="flex gap-3.5 items-center">
+        Page not found
+        <UnlinkIcon size={24} />
+      </Heading>
+      <DeveloperHint>
+        Start by adding a file at{" "}
+        <code>
+          {"{PROJECT_ROOT}"}/{params["*"]}.mdx
+        </code>{" "}
+        and add some content to make this error go away.
+      </DeveloperHint>
+      <p>
+        It seems that the page you are looking for does not exist or may have
+        been moved. Please check the URL for any typos or use the navigation
+        menu to find the correct page.
+      </p>
+      <Link to="/">Go back home</Link>
+    </div>
+  );
+};

package/src/lib/components/SlotletProvider.tsx

@@ -0,0 +1,25 @@
+import React, { ReactNode, useContext } from "react";
+
+export type Slotlets = Record<string, ReactNode>;
+
+const SlotletContext = React.createContext<Slotlets | undefined>({});
+
+export const SlotletProvider = ({
+  slotlets,
+  children,
+}: {
+  children: ReactNode;
+  slotlets?: Slotlets;
+}) => {
+  return (
+    <SlotletContext.Provider value={slotlets}>
+      {children}
+    </SlotletContext.Provider>
+  );
+};
+
+export const Slotlet = ({ name }: { name: string }) => {
+  const x = useContext(SlotletContext);
+
+  return x?.[name];
+};

package/src/lib/components/SyntaxHighlight.tsx

@@ -7,25 +7,23 @@ import {
 
 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");
-  // @ts-expect-error This is untyped
-  import("prismjs/components/prism-java.min.js");
-  // @ts-expect-error This is untyped
-  import("prismjs/components/prism-csharp.min.js");
-  // @ts-expect-error This is untyped
-  import("prismjs/components/prism-objectivec.min.js");
-}
+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");
+// @ts-expect-error This is untyped
+import("prismjs/components/prism-java.min.js");
+// @ts-expect-error This is untyped
+import("prismjs/components/prism-csharp.min.js");
+// @ts-expect-error This is untyped
+import("prismjs/components/prism-objectivec.min.js");
 
 import { useState } from "react";
 import { cn } from "../util/cn.js";
@@ -37,10 +35,12 @@ type SyntaxHighlightProps = {
   wrapLines?: boolean;
   copyable?: boolean;
   showLanguageIndicator?: boolean;
-} & Omit<HighlightProps, "children">;
+  language?: string;
+} & Omit<HighlightProps, "children" | "language">;
 
 export const SyntaxHighlight = ({
   copyable = true,
+  language = "plain",
   ...props
 }: SyntaxHighlightProps) => {
   const [isDark] = useTheme();
@@ -51,23 +51,44 @@ export const SyntaxHighlight = ({
   }
 
   return (
-    <Highlight theme={isDark ? themes.vsDark : themes.github} {...props}>
+    <Highlight
+      theme={isDark ? themes.vsDark : themes.github}
+      language={language}
+      {...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",
+        <div className="relative group">
+          <pre
+            className={cn(
+              "relative overflow-x-auto",
+              className,
+              props.className,
+              props.noBackground && "!bg-transparent",
+              props.wrapLines && "whitespace-pre-wrap break-words",
+            )}
+            style={style}
+          >
+            {tokens.map((line, i) => (
+              // eslint-disable-next-line react/no-array-index-key
+              <div key={i} {...getLineProps({ line })}>
+                {line.map((token, key) => (
+                  // eslint-disable-next-line react/no-array-index-key
+                  <span key={key} {...getTokenProps({ token })} />
+                ))}
+              </div>
+            ))}
+          </pre>
+          {props.showLanguageIndicator && (
+            <span className="absolute top-1.5 right-3 text-[11px] font-mono text-muted-foreground transition group-hover:opacity-0">
+              {language}
+            </span>
           )}
-          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"
+              title="Copy code"
+              className="absolute top-1.5 right-1.5 p-2.5 opacity-0 group-hover:opacity-100 group-hover:bg-zinc-100 group-hover:dark:bg-zinc-700 hover:outline hover:outline-border/75 dark:hover:outline-border rounded-md text-sm text-gray-400 hover:text-gray-600 dark:text-gray-500 dark:hover:text-gray-400 transition"
               disabled={isCopied}
               onClick={() => {
                 setIsCopied(true);
@@ -86,19 +107,7 @@ export const SyntaxHighlight = ({
               )}
             </button>
           )}
-          {props.showLanguageIndicator && (
-            <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>
+        </div>
       )}
     </Highlight>
   );

package/src/lib/components/TopNavigation.tsx

@@ -6,8 +6,13 @@ import { useDevPortal } from "./context/DevPortalProvider.js";
 export const TopNavigation = () => {
   const { navigation } = useDevPortal();
 
+  // Hide tope nav if there is only one item
+  if (navigation.length <= 1) {
+    return null;
+  }
+
   return (
-    <nav className="border-b border-border text-sm px-12 h-[--top-nav-height]">
+    <nav className="border-b text-sm px-12 h-[--top-nav-height]">
       <ul className="flex flex-row items-center gap-8">
         {navigation.map((item) => (
           <li key={item.label}>

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

@@ -1,7 +1,8 @@
-import { useSuspenseQuery } from "@tanstack/react-query";
+import { useQuery, useSuspenseQuery } from "@tanstack/react-query";
 import { createContext, useContext } from "react";
 import { matchPath, useLocation } from "react-router-dom";
 import { DevPortalContext } from "../../core/DevPortalContext.js";
+import { traverseNavigation } from "../../util/traverseNavigation.js";
 
 const DevPortalReactContext = createContext<DevPortalContext | undefined>(
   undefined,
@@ -21,7 +22,7 @@ export const useDevPortal = () => {
 
 export const useApiIdentities = () => {
   const { getApiIdentities } = useDevPortal();
-  return useSuspenseQuery({
+  return useQuery({
     queryFn: getApiIdentities,
     queryKey: ["api-identities"],
   });
@@ -31,8 +32,27 @@ export const useTopNavigationItem = () => {
   const { navigation } = useDevPortal();
   const location = useLocation();
 
-  return navigation.find((item) =>
-    matchPath({ path: item.path, end: false }, location.pathname),
+  // The `/` path needs this logic because it would always match:
+  // Only if a leaf node actually matches the current path it is active
+  for (const item of navigation) {
+    const foundNavItem = traverseNavigation(item, (_node, fullPath) => {
+      if (location.pathname === fullPath) {
+        return item;
+      }
+    });
+
+    if (foundNavItem) {
+      return foundNavItem;
+    }
+  }
+  if (location.pathname === "/") {
+    return navigation.find((item) => item.path === "/");
+  }
+
+  return navigation.find(
+    (item) =>
+      item.path !== "/" &&
+      matchPath({ path: item.path, end: false }, location.pathname),
   );
 };
 

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/SideNavigation.tsx

@@ -1,6 +1,7 @@
 import { useRef } from "react";
 
 import { useNavigation } from "../context/DevPortalProvider.js";
+import { Slotlet } from "../SlotletProvider.js";
 import { SideNavigationCategory } from "./SideNavigationCategory.js";
 import { SideNavigationWrapper } from "./SideNavigationWrapper.js";
 
@@ -13,9 +14,11 @@ export const SideNavigation = () => {
       ref={navRef}
       pushMainContent={navigation.data.items.length > 0}
     >
+      <Slotlet name="zudoku-before-navigation" />
       {navigation.data.items.map((category) => (
         <SideNavigationCategory key={category.label} category={category} />
       ))}
+      <Slotlet name="zudoku-after-navigation" />
     </SideNavigationWrapper>
   );
 };

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

@@ -8,7 +8,7 @@ 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";
+import { checkHasActiveItem } from "./util.js";
 
 export const SideNavigationCategory = ({
   category,
@@ -21,7 +21,7 @@ export const SideNavigationCategory = ({
 
   const isCollapsible = category.collapsible ?? true;
 
-  const [isOpen, setIsOpen] = useNavigationCollapsibleState({
+  const collapsibleProps = useNavigationCollapsibleState({
     item: category,
     path: navItem?.path ?? "",
     defaultOpen: () =>
@@ -31,11 +31,7 @@ export const SideNavigationCategory = ({
   });
 
   return (
-    <Collapsible.Root
-      key={category.label}
-      open={isOpen}
-      onOpenChange={() => setIsOpen((prev) => !prev)}
-    >
+    <Collapsible.Root key={category.label} {...collapsibleProps}>
       {category.label.length > 0 ? (
         <Collapsible.Trigger asChild={isCollapsible} disabled={!isCollapsible}>
           <h5
@@ -59,9 +55,9 @@ export const SideNavigationCategory = ({
       <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) => (
+          {category.children.map((item, i) => (
             <SideNavigationItem
-              key={isPathItem(item) ? item.path + item.label : item.href}
+              key={i}
               category={category}
               item={item}
               activeAnchor={activeAnchor}

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

@@ -14,7 +14,7 @@ import { AnchorLink } from "../AnchorLink.js";
 import { useNavigationCollapsibleState } from "./useNavigationCollapsibleState.js";
 import { checkHasActiveItem, isLinkItem, isPathItem } from "./util.js";
 
-export const navigationListItem = cva(
+const navigationListItem = cva(
   "flex px-[--padding-nav-item] py-1.5 rounded-lg hover:bg-accent transition-colors duration-300",
   {
     variants: {
@@ -48,10 +48,10 @@ export const SideNavigationItem = ({
   const currentPath = isPathItem(item) ? joinPath(basePath, item.path) : "";
   const location = useLocation();
 
-  const [isOpen, setIsOpen] = useNavigationCollapsibleState({
+  const collapsibleProps = useNavigationCollapsibleState({
     item,
     path: currentPath,
-    defaultOpen: () => checkHasActiveItem(item, location.pathname, currentPath),
+    defaultOpen: () => checkHasActiveItem(item, location.pathname, basePath),
   });
 
   if (isLinkItem(item)) {
@@ -100,11 +100,7 @@ export const SideNavigationItem = ({
   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.Root {...collapsibleProps} className="flex flex-col">
           <Collapsible.Trigger
             className={cn(
               "group text-start",
@@ -114,7 +110,7 @@ export const SideNavigationItem = ({
             {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">
+            <ul className="mt-1 border-l ps-1.5">
               {item.children.map((child) => (
                 <SideNavigationItem
                   key={isPathItem(child) ? child.path : child.href}

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

@@ -1,3 +1,4 @@
+import type { CollapsibleProps } from "@radix-ui/react-collapsible";
 import { useEffect, useRef, useState } from "react";
 import { useLocation } from "react-router-dom";
 import type { NavigationNode } from "../../util/traverseNavigation.js";
@@ -11,17 +12,31 @@ export const useNavigationCollapsibleState = ({
   item: NavigationNode;
   defaultOpen: () => boolean;
   path: string;
-}) => {
-  const [isOpen, setIsOpen] = useState(defaultOpen);
+}): Partial<CollapsibleProps> & { "data-animate": boolean } => {
+  const [open, setOpen] = useState(defaultOpen);
   const location = useLocation();
   const previousLocationPath = useRef(location.pathname);
+  const [shouldAnimate, setShouldAnimate] = useState(false);
 
   useEffect(() => {
-    if (!isOpen && previousLocationPath.current !== location.pathname) {
-      setIsOpen(checkHasActiveItem(item, location.pathname, path));
+    if (!open && previousLocationPath.current !== location.pathname) {
+      setOpen(checkHasActiveItem(item, location.pathname, path));
     }
     previousLocationPath.current = location.pathname;
-  }, [isOpen, item, path, location.pathname]);
+  }, [open, item, path, location.pathname]);
 
-  return [isOpen, setIsOpen] as const;
+  const onOpenChange = () => {
+    setShouldAnimate(true);
+    setOpen((prev) => !prev);
+  };
+
+  useEffect(() => {
+    setShouldAnimate(false);
+  }, []);
+
+  return {
+    open,
+    onOpenChange,
+    "data-animate": shouldAnimate,
+  };
 };

package/src/lib/core/DevPortalContext.ts

@@ -1,17 +1,16 @@
 import { QueryClient } from "@tanstack/react-query";
 import { type ReactNode } from "react";
-import { create } from "zustand";
 import { type AuthenticationProvider } from "../authentication/authentication.js";
+import type { ComponentsContextType } from "../components/context/ComponentsContext.js";
+import { type DevPortalPath } from "../components/DevPortal.js";
+import { Slotlets } from "../components/SlotletProvider.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 {
@@ -55,40 +54,72 @@ export type NavigationItem = {
   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;
+  navigation: NavigationItem[];
+  plugins?: DevPortalPlugin[];
+  slotlets?: Slotlets;
+  mdx?: {
+    components?: MdxComponentsType;
+  };
+  overrides?: ComponentsContextType;
+};
+
 export class DevPortalContext {
-  private plugins: DevPortalPlugin[] = [];
+  public plugins: NonNullable<ZudokuContextOptions["plugins"]> = [];
+  public navigation: ZudokuContextOptions["navigation"];
+  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.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([
       this.plugins
         .filter(needsInitialization)
-        .map((plugin) => plugin.initialize(this)),
+        .map((plugin) => plugin.initialize?.(this)),
     ]);
   };
 
@@ -116,7 +147,7 @@ export class DevPortalContext {
     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 +157,5 @@ export class DevPortalContext {
     request.headers.set("Authorization", `Bearer ${accessToken}`);
 
     return request;
-  }
+  };
 }