zudoku 0.0.0-e3f7e48 → 0.0.0-e4d0ea8

package/src/lib/components/ErrorPage.tsx

@@ -1,5 +1,4 @@
 import type { ReactNode } from "react";
-import { Link } from "react-router-dom";
 import { CategoryHeading } from "./CategoryHeading.js";
 import { Heading } from "./Heading.js";
 import { ProseClasses } from "./Markdown.js";
@@ -22,7 +21,6 @@ export const ErrorPage = ({
         </Heading>
       )}
       <p>{message}</p>
-      <Link to="/">Go back home</Link>
     </div>
   );
 };

package/src/lib/components/Header.tsx

@@ -70,14 +70,22 @@ export const Header = memo(function HeaderInner() {
                 {page?.logo && (
                   <>
                     <img
-                      src={page.logo.src.light}
+                      src={
+                        /https?:\/\//.test(page.logo.src.light)
+                          ? page.logo.src.light
+                          : import.meta.env.BASE_URL + page.logo.src.light
+                      }
                       alt={page.logo.alt ?? page.pageTitle}
                       style={{ width: page.logo.width }}
                       className={cn("h-10", isDark && "hidden")}
                       loading="lazy"
                     />
                     <img
-                      src={page.logo.src.dark}
+                      src={
+                        /https?:\/\//.test(page.logo.src.dark)
+                          ? page.logo.src.dark
+                          : import.meta.env.BASE_URL + page.logo.src.dark
+                      }
                       alt={page.logo.alt ?? page.pageTitle}
                       style={{ width: page.logo.width }}
                       className={cn("h-10", !isDark && "hidden")}
@@ -92,7 +100,7 @@ export const Header = memo(function HeaderInner() {
             </Link>
           </div>
           <div className="grid grid-cols-2 md:grid-cols-[--sidecar-grid-cols] items-center gap-8">
-            <div className="w-full justify-center flex">
+            <div className="w-full justify-center hidden md:flex ">
               <Search />
             </div>
 
@@ -133,7 +141,9 @@ export const Header = memo(function HeaderInner() {
             </div>
           </div>
         </div>
+        <Slotlet name="top-navigation-before" />
         <TopNavigation />
+        <Slotlet name="top-navigation-after" />
       </div>
     </header>
   );

package/src/lib/components/InlineCode.tsx

@@ -4,11 +4,21 @@ import { cn } from "../util/cn.js";
 export const InlineCode = ({
   className,
   children,
+  selectOnClick,
 }: {
   className?: string;
   children: ReactNode;
+  selectOnClick?: boolean;
 }) => (
   <code
+    onClick={(e) => {
+      if (!selectOnClick) return;
+      const selection = window.getSelection();
+      const range = document.createRange();
+      range.selectNodeContents(e.currentTarget);
+      selection?.removeAllRanges();
+      selection?.addRange(range);
+    }}
     className={cn(
       "font-mono border p-1 py-0.5 rounded bg-border/50 dark:bg-border/70 whitespace-nowrap",
       className,

package/src/lib/components/Layout.tsx

@@ -49,11 +49,12 @@ export const Layout = ({ children }: { children?: ReactNode }) => {
       </Helmet>
       <Slotlet name="layout-before-head" />
       <Header />
+      <Slotlet name="layout-after-head" />
 
       <div className="w-full max-w-screen-2xl mx-auto px-10 lg:px-12">
         <Suspense
           fallback={
-            <main className="grid h-full place-items-center">
+            <main className="grid h-[calc(100vh-var(--header-height))] place-items-center">
               <Spinner />
             </main>
           }

package/src/lib/components/MobileTopNavigation.tsx

@@ -10,6 +10,7 @@ import {
   DrawerTrigger,
 } from "../ui/Drawer.js";
 import { useZudoku } from "./context/ZudokuContext.js";
+import { Search } from "./Search.js";
 
 export const MobileTopNavigation = () => {
   const { topNavigation } = useZudoku();
@@ -27,6 +28,7 @@ export const MobileTopNavigation = () => {
         <VisuallyHidden>
           <DrawerTitle>Navigation</DrawerTitle>
         </VisuallyHidden>
+        <Search />
         <ul className="flex flex-col items-center gap-4 p-4">
           {topNavigation.map((item) => (
             <li key={item.label}>

package/src/lib/components/SlotletProvider.tsx

@@ -1,6 +1,15 @@
-import React, { type ReactElement, ReactNode, useContext } from "react";
+import React, {
+  type ComponentType,
+  type ReactElement,
+  ReactNode,
+  useContext,
+} from "react";
 import { isValidElementType } from "react-is";
-export type Slotlets = Record<string, ReactNode | ReactElement>;
+import { useLocation } from "react-router-dom";
+export type Slotlets = Record<
+  string,
+  ReactNode | ReactElement | ComponentType<SlotletComponentProps>
+>;
 
 const SlotletContext = React.createContext<Slotlets | undefined>({});
 
@@ -18,13 +27,20 @@ export const SlotletProvider = ({
   );
 };
 
+export type SlotletComponentProps = {
+  location: Location;
+};
+
 export const Slotlet = ({ name }: { name: string }) => {
   const context = useContext(SlotletContext);
   const componentOrElement = context?.[name];
+  const location = useLocation();
 
   if (isValidElementType(componentOrElement)) {
-    return React.createElement(componentOrElement);
+    return React.createElement(componentOrElement, {
+      location,
+    });
   }
 
-  return componentOrElement;
+  return componentOrElement as ReactNode;
 };

package/src/lib/components/TopNavigation.tsx

@@ -1,7 +1,10 @@
 import { cx } from "class-variance-authority";
-import { NavLink } from "react-router-dom";
-
-import { useZudoku } from "./context/ZudokuContext.js";
+import { Suspense } from "react";
+import { Link } from "react-router-dom";
+import { TopNavigationItem } from "../../config/validators/validate.js";
+import { joinPath } from "../util/joinPath.js";
+import { useCurrentNavigation, useZudoku } from "./context/ZudokuContext.js";
+import { traverseSidebar } from "./navigation/utils.js";
 
 export const TopNavigation = () => {
   const { topNavigation } = useZudoku();
@@ -12,26 +15,57 @@ export const TopNavigation = () => {
   }
 
   return (
-    <nav className="hidden lg:block border-b text-sm px-12 h-[--top-nav-height]">
-      <ul className="flex flex-row items-center gap-8">
-        {topNavigation.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.id}
-            >
-              {item.label}
-            </NavLink>
-          </li>
-        ))}
-      </ul>
-    </nav>
+    <Suspense>
+      <nav className="hidden lg:block border-b text-sm px-12 h-[--top-nav-height]">
+        <ul className="flex flex-row items-center gap-8">
+          {topNavigation.map((item) => (
+            <li key={item.id}>
+              <TopNavItem {...item} />
+            </li>
+          ))}
+        </ul>
+      </nav>
+    </Suspense>
+  );
+};
+
+const TopNavItem = ({ id, label, default: defaultLink }: TopNavigationItem) => {
+  const { sidebars } = useZudoku();
+  const nav = useCurrentNavigation();
+  const currentSidebar = sidebars[id];
+
+  // TODO: This is a bit of a hack to get the first link in the sidebar
+  // We should really process this when we load the config so we can validate
+  // that the sidebar is actually set. In this case we just fall back to linking
+  // to the id if we can't resolve a sidebar.
+  const first =
+    defaultLink ??
+    (currentSidebar
+      ? traverseSidebar(currentSidebar, (item) => {
+          if (item.type === "doc") return joinPath(item.id);
+        })
+      : joinPath(id));
+
+  if (!first) {
+    throw new Error(
+      `No links found in top navigation for top navigation '${id}'. Check that the sidebar isn't empty or that a default link set.`,
+    );
+  }
+
+  // Manually set the active sidebar based on our logic of what is active
+  const isActive = nav.data.topNavItem?.id === id;
+
+  return (
+    <Link
+      className={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={first}
+    >
+      {label}
+    </Link>
   );
 };

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

@@ -1,7 +1,9 @@
 import { useQuery, useSuspenseQuery } from "@tanstack/react-query";
 import { createContext, useContext } from "react";
-import { useLocation } from "react-router-dom";
+import { matchPath, useLocation } from "react-router-dom";
 import { DevPortalContext } from "../../core/DevPortalContext.js";
+import { joinPath } from "../../util/joinPath.js";
+import { traverseSidebar } from "../navigation/utils.js";
 
 export const ZudokuReactContext = createContext<DevPortalContext | undefined>(
   undefined,
@@ -25,34 +27,40 @@ export const useApiIdentities = () => {
   });
 };
 
-export const useTopNavigationItem = () => {
-  const { topNavigation } = useZudoku();
+export const useCurrentNavigation = () => {
+  const { getPluginSidebar, sidebars, topNavigation } = useZudoku();
   const location = useLocation();
 
-  const firstPart = location.pathname.split("/").at(1);
-  if (!firstPart) return;
+  const currentSidebarItem = Object.entries(sidebars).find(([, sidebar]) => {
+    return traverseSidebar(sidebar, (item) => {
+      const itemId =
+        item.type === "doc"
+          ? joinPath(item.id)
+          : item.type === "category" && item.link
+            ? joinPath(item.link.id)
+            : undefined;
 
-  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();
+      if (itemId === location.pathname) {
+        return item;
+      }
+    });
+  });
+  const currentTopNavItem =
+    topNavigation.find((t) => t.id === currentSidebarItem?.[0]) ??
+    topNavigation.find((item) => matchPath(item.id, location.pathname));
 
   return useSuspenseQuery({
     queryFn: async () => {
-      const pluginSidebar = path
-        ? await getPluginSidebar(path)
-        : await getPluginSidebar(location.pathname);
+      const pluginSidebar = await getPluginSidebar(location.pathname);
 
       return {
-        items: [...currentSidebar, ...pluginSidebar],
-        currentTopNavItem: navItem,
+        sidebar: [
+          ...(currentSidebarItem ? currentSidebarItem[1] : []),
+          ...pluginSidebar,
+        ],
+        topNavItem: currentTopNavItem,
       };
     },
-    queryKey: ["navigation", path],
+    queryKey: ["navigation", location.pathname],
   });
 };

package/src/lib/components/index.ts

@@ -16,7 +16,7 @@ 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 Link: typeof LinkImport = /*@__PURE__*/ LinkImport;
 export const RouterError = /*@__PURE__*/ RouterErrorImport;
 export const ServerError = /*@__PURE__*/ ServerErrorImport;
 export const Bootstrap = /*@__PURE__*/ BootstrapImport;

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

@@ -2,23 +2,23 @@ import { useRef } from "react";
 
 import { VisuallyHidden } from "@radix-ui/react-visually-hidden";
 import { DrawerContent, DrawerTitle } from "../../ui/Drawer.js";
-import { useNavigation } from "../context/ZudokuContext.js";
+import { useCurrentNavigation } 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();
+  const navigation = useCurrentNavigation();
 
   return (
     <>
       <SidebarWrapper
         ref={navRef}
-        pushMainContent={navigation.data.items.length > 0}
+        pushMainContent={navigation.data.sidebar.length > 0}
       >
         <Slotlet name="zudoku-before-navigation" />
-        {navigation.data.items.map((item) => (
+        {navigation.data.sidebar.map((item) => (
           <SidebarItem key={item.label} item={item} />
         ))}
         <Slotlet name="zudoku-after-navigation" />
@@ -30,7 +30,7 @@ export const Sidebar = () => {
         <VisuallyHidden>
           <DrawerTitle>Sidebar</DrawerTitle>
         </VisuallyHidden>
-        {navigation.data.items.map((item) => (
+        {navigation.data.sidebar.map((item) => (
           <SidebarItem key={item.label} item={item} />
         ))}
       </DrawerContent>

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

@@ -5,7 +5,6 @@ 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";
 
@@ -16,7 +15,6 @@ export const SidebarCategory = ({
   category: SidebarItemCategory;
   level: number;
 }) => {
-  const topNavItem = useTopNavigationItem();
   const isCategoryOpen = useIsCategoryOpen(category);
   const [hasInteracted, setHasInteracted] = useState(false);
 
@@ -79,7 +77,7 @@ export const SidebarCategory = ({
           )}
           {category.link?.type === "doc" ? (
             <NavLink
-              to={joinPath(topNavItem?.id, category.link.id)}
+              to={joinPath(category.link.id)}
               className="flex-1"
               onClick={() => setHasInteracted(true)}
             >

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

@@ -7,7 +7,6 @@ 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";
 
@@ -40,7 +39,6 @@ export const SidebarItem = ({
   basePath?: string;
   level?: number;
 }) => {
-  const topNavItem = useTopNavigationItem();
   const { activeAnchor } = useViewportAnchor();
   const [searchParams] = useSearchParams();
 
@@ -53,7 +51,7 @@ export const SidebarItem = ({
           className={({ isActive }) =>
             navigationListItem({ isActive, isTopLevel: level === 0 })
           }
-          to={joinPath(topNavItem?.id, item.id)}
+          to={joinPath(item.id)}
         >
           {item.icon && <item.icon size={16} className="align-[-0.125em]" />}
           {item.badge ? (

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

@@ -4,7 +4,7 @@ import type {
   SidebarItemCategory,
 } from "../../../config/validators/SidebarSchema.js";
 import { joinPath } from "../../util/joinPath.js";
-import { useTopNavigationItem, useZudoku } from "../context/ZudokuContext.js";
+import { useCurrentNavigation } from "../context/ZudokuContext.js";
 
 export type TraverseCallback<T> = (
   item: SidebarItem,
@@ -42,15 +42,12 @@ export const traverseSidebarItem = <T>(
 
 export const useCurrentItem = () => {
   const location = useLocation();
-  const topNavItem = useTopNavigationItem();
-  const { sidebars } = useZudoku();
-  const currentSidebar = topNavItem?.id ? sidebars[topNavItem.id] : [];
+  const nav = useCurrentNavigation();
+
+  const currentSidebar = nav.data.sidebar;
 
   return traverseSidebar(currentSidebar, (item) => {
-    if (
-      item.type === "doc" &&
-      joinPath(topNavItem?.id, item.id) === location.pathname
-    ) {
+    if (item.type === "doc" && joinPath(item.id) === location.pathname) {
       return item;
     }
   });
@@ -58,18 +55,17 @@ export const useCurrentItem = () => {
 
 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);
+      const categoryLinkPath = joinPath(item.link.id);
       if (categoryLinkPath === location.pathname) {
         return true;
       }
     }
 
     if (item.type === "doc") {
-      const docPath = joinPath(topNavItem?.id, item.id);
+      const docPath = joinPath(item.id);
       if (docPath === location.pathname) {
         return true;
       }
@@ -82,9 +78,8 @@ export const usePrevNext = (): {
   next?: { label: string; id: string };
 } => {
   const currentId = useLocation().pathname;
-  const { sidebars } = useZudoku();
-  const topNavItem = useTopNavigationItem();
-  const currentSidebar = topNavItem?.id ? sidebars[topNavItem.id] : [];
+  const nav = useCurrentNavigation();
+  const currentSidebar = nav.data.sidebar;
 
   let prev;
   let next;
@@ -94,9 +89,9 @@ export const usePrevNext = (): {
   traverseSidebar(currentSidebar, (item) => {
     const itemId =
       item.type === "doc"
-        ? joinPath(topNavItem?.id, item.id)
+        ? joinPath(item.id)
         : item.type === "category" && item.link
-          ? joinPath(topNavItem?.id, item.link.id)
+          ? joinPath(item.link.id)
           : undefined;
 
     if (!itemId) return;

package/src/lib/core/DevPortalContext.ts

@@ -1,6 +1,7 @@
 import { QueryClient } from "@tanstack/react-query";
 import { ReactNode } from "react";
 import type { SidebarConfig } from "../../config/validators/SidebarSchema.js";
+import { TopNavigationItem } from "../../config/validators/validate.js";
 import { type AuthenticationProvider } from "../authentication/authentication.js";
 import type { ComponentsContextType } from "../components/context/ComponentsContext.js";
 import { Slotlets } from "../components/SlotletProvider.js";
@@ -51,7 +52,7 @@ type Page = Partial<{
   };
   banner?: {
     message: ReactNode;
-    color?: "note" | "tip" | "info" | "caution" | "danger";
+    color?: "note" | "tip" | "info" | "caution" | "danger" | (string & {});
     dismissible?: boolean;
   };
 }>;
@@ -60,7 +61,7 @@ export type ZudokuContextOptions = {
   metadata?: Metadata;
   page?: Page;
   authentication?: AuthenticationProvider;
-  topNavigation?: Array<{ id: string; label: string; default?: string }>;
+  topNavigation?: TopNavigationItem[];
   sidebars?: SidebarConfig;
   plugins?: DevPortalPlugin[];
   slotlets?: Slotlets;
@@ -72,7 +73,7 @@ export type ZudokuContextOptions = {
 
 export class DevPortalContext {
   public plugins: NonNullable<ZudokuContextOptions["plugins"]>;
-  public sidebars: NonNullable<ZudokuContextOptions["sidebars"]>;
+  public sidebars: SidebarConfig;
   public topNavigation: NonNullable<ZudokuContextOptions["topNavigation"]>;
   public meta: ZudokuContextOptions["metadata"];
   public page: ZudokuContextOptions["page"];

package/src/lib/core/plugins.ts

@@ -11,6 +11,8 @@ export type DevPortalPlugin =
   | ApiIdentityPlugin
   | SearchProviderPlugin;
 
+export type { RouteObject };
+
 export interface NavigationPlugin {
   getRoutes: () => RouteObject[];
   getSidebar?: (path: string) => Promise<Sidebar>;

package/src/lib/oas/graphql/index.ts

@@ -18,6 +18,7 @@ import {
   type ParameterObject,
   type PathsObject,
   type SchemaObject,
+  type ServerObject,
   type TagObject,
 } from "../parser/index.js";
 
@@ -57,9 +58,10 @@ export const createOperationSlug = (
   );
 };
 
-const cache = new LRUCache<string, Promise<OpenAPIDocument>>({
+const cache = new LRUCache<string, OpenAPIDocument>({
   ttl: 60 * 10 * 1000,
   ttlAutopurge: true,
+  fetchMethod: (_key, _oldValue, { context }) => validate(context as string),
 });
 
 const builder = new SchemaBuilder<{
@@ -158,6 +160,13 @@ const SchemaTag = builder.objectRef<TagObject>("SchemaTag").implement({
   }),
 });
 
+const ServerItem = builder.objectRef<ServerObject>("Server").implement({
+  fields: (t) => ({
+    url: t.exposeString("url"),
+    description: t.exposeString("description", { nullable: true }),
+  }),
+});
+
 const PathItem = builder
   .objectRef<{
     path: string;
@@ -371,6 +380,10 @@ const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
   fields: (t) => ({
     openapi: t.string({ resolve: (root) => root.openapi }),
     url: t.string({ resolve: (root) => root.servers?.at(0)?.url ?? "/" }),
+    servers: t.field({
+      type: [ServerItem],
+      resolve: (root) => root.servers ?? [],
+    }),
     title: t.string({ resolve: (root) => root.info.title }),
     version: t.string({ resolve: (root) => root.info.version }),
     description: t.string({
@@ -417,16 +430,7 @@ const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
 
 const loadOpenAPISchema = async (input: NonNullable<unknown>) => {
   const hash = hashit(input);
-
-  if (cache.has(hash)) {
-    return cache.get(hash)!;
-  }
-
-  const schema = validate(input);
-
-  cache.set(hash, schema);
-
-  return schema;
+  return await cache.forceFetch(hash, { context: input });
 };
 
 const SchemaSource = builder.enumType("SchemaType", {

package/src/lib/oas/parser/index.ts

@@ -20,6 +20,7 @@ export type TagObject = DeepOmitReference<OpenAPIV3_1.TagObject>;
 export type ExampleObject = DeepOmitReference<OpenAPIV3_1.ExampleObject>;
 export type EncodingObject = DeepOmitReference<OpenAPIV3_1.EncodingObject>;
 export type SchemaObject = DeepOmitReference<OpenAPIV3_1.SchemaObject>;
+export type ServerObject = DeepOmitReference<OpenAPIV3_1.ServerObject>;
 
 export const HttpMethods = Object.values(OpenAPIV3.HttpMethods);
 

package/src/lib/plugins/{custom-page → custom-pages}/index.tsx

@@ -3,13 +3,13 @@ import type { RouteObject } from "react-router-dom";
 import { ProseClasses } from "../../components/Markdown.js";
 import type { DevPortalPlugin, NavigationPlugin } from "../../core/plugins.js";
 
-type CustomPageConfig = Array<{
+type CustomPagesConfig = Array<{
   path: string;
   element: ReactNode;
 }>;
 
-export const customPagePlugin = (
-  config: CustomPageConfig,
+export const customPagesPlugin = (
+  config: CustomPagesConfig,
 ): DevPortalPlugin & NavigationPlugin => {
   return {
     getRoutes: (): RouteObject[] =>