zudoku 0.37.1 → 0.39.0

package/src/lib/authentication/state.ts

@@ -1,4 +1,3 @@
-import { useMemo } from "react";
 import { create, type Mutate, type StoreApi } from "zustand";
 import { createJSONStorage, persist } from "zustand/middleware";
 
@@ -20,7 +19,7 @@ export type StoreWithPersist<T> = Mutate<
   [["zustand/persist", unknown]]
 >;
 
-export const withStorageDOMEvents = <T>(store: StoreWithPersist<T>) => {
+const withStorageDOMEvents = <T>(store: StoreWithPersist<T>) => {
   const storageEventCallback = (e: StorageEvent) => {
     if (e.key === store.persist.getOptions().name && e.newValue) {
       void store.persist.rehydrate();
@@ -68,36 +67,3 @@ export interface UserProfile {
   pictureUrl: string | undefined;
   [key: string]: string | boolean | undefined;
 }
-
-interface SelectedServerState {
-  selectedServer?: string;
-  setSelectedServer: (newServer: string) => void;
-}
-
-export const useSelectedServerStore = create<SelectedServerState>()(
-  persist(
-    (set) => ({
-      selectedServer: undefined,
-      setSelectedServer: (newServer: string) =>
-        set({ selectedServer: newServer }),
-    }),
-    { name: "zudoku-selected-server" },
-  ),
-);
-
-/**
- * Simple wrapper for `useSelectedServerStore` to fall back to first of the provided servers
- */
-export const useSelectedServer = (servers: Array<{ url: string }>) => {
-  const { selectedServer, setSelectedServer } = useSelectedServerStore();
-
-  const finalSelectedServer = useMemo(
-    () =>
-      selectedServer && servers.some((s) => s.url === selectedServer)
-        ? selectedServer
-        : (servers.at(0)?.url ?? ""),
-    [selectedServer, servers],
-  );
-
-  return { selectedServer: finalSelectedServer, setSelectedServer };
-};

package/src/lib/components/Layout.tsx

@@ -1,7 +1,7 @@
 import { Helmet } from "@zudoku/react-helmet-async";
 import { Suspense, useEffect, type ReactNode } from "react";
-import { Outlet, useNavigation } from "react-router";
-import { useSpinDelay } from "spin-delay";
+import { Outlet, useLocation } from "react-router";
+import { joinUrl } from "../util/joinUrl.js";
 import { useScrollToAnchor } from "../util/useScrollToAnchor.js";
 import { useScrollToTop } from "../util/useScrollToTop.js";
 import { useZudoku } from "./context/ZudokuContext.js";
@@ -17,7 +17,8 @@ const LoadingFallback = () => (
 );
 
 export const Layout = ({ children }: { children?: ReactNode }) => {
-  const { meta, authentication } = useZudoku();
+  const { meta, authentication, options } = useZudoku();
+  const location = useLocation();
 
   useScrollToAnchor();
   useScrollToTop();
@@ -27,19 +28,22 @@ export const Layout = ({ children }: { children?: ReactNode }) => {
     authentication?.onPageLoad?.();
   }, [authentication]);
 
-  // Page transition is happening: https://reactrouter.com/start/framework/pending-navigation
-  const isNavigating = Boolean(useNavigation().location);
-  const showSpinner = useSpinDelay(isNavigating, {
-    delay: 300,
-    minDuration: 500,
-  });
-
   return (
     <>
       {import.meta.env.MODE === "standalone" && (
         <style>{`:root { --top-nav-height: 0px; }`}</style>
       )}
       <Helmet titleTemplate={meta?.title}>
+        {options.canonicalUrlOrigin && (
+          <link
+            rel="canonical"
+            href={joinUrl(
+              options.canonicalUrlOrigin,
+              options.basePath,
+              location.pathname,
+            )}
+          />
+        )}
         {meta?.description && (
           <meta name="description" content={meta.description} />
         )}
@@ -50,13 +54,9 @@ export const Layout = ({ children }: { children?: ReactNode }) => {
       <Slotlet name="layout-after-head" />
 
       <div className="grid grid-cols-1 grid-rows-[min-content_1fr] lg:grid-cols-[var(--side-nav-width)_1fr] max-w-screen-2xl w-full lg:mx-auto px-4 lg:px-8 2xl:border-x">
-        {showSpinner ? (
-          <LoadingFallback />
-        ) : (
-          <Suspense fallback={<LoadingFallback />}>
-            <Main>{children ?? <Outlet />}</Main>
-          </Suspense>
-        )}
+        <Suspense fallback={<LoadingFallback />}>
+          <Main>{children ?? <Outlet />}</Main>
+        </Suspense>
       </div>
     </>
   );

package/src/lib/components/Main.tsx

@@ -1,5 +1,6 @@
 import { PanelLeftIcon } from "lucide-react";
 import { type PropsWithChildren, useState } from "react";
+import { useNavigation } from "react-router";
 import { Drawer, DrawerTrigger } from "zudoku/ui/Drawer.js";
 import { cn } from "../util/cn.js";
 import { useCurrentNavigation } from "./context/ZudokuContext.js";
@@ -10,6 +11,7 @@ export const Main = ({ children }: PropsWithChildren) => {
   const [isDrawerOpen, setDrawerOpen] = useState(false);
   const { sidebar } = useCurrentNavigation();
   const hasSidebar = sidebar.length > 0;
+  const isNavigating = useNavigation().state === "loading";
 
   return (
     <Drawer
@@ -34,8 +36,8 @@ export const Main = ({ children }: PropsWithChildren) => {
       <main
         data-pagefind-body
         className={cn(
-          "h-auto dark:border-white/10 translate-x-0",
           hasSidebar ? "lg:pl-12" : "col-span-full",
+          isNavigating && "animate-pulse",
         )}
       >
         <Slotlet name="zudoku-before-content" />

package/src/lib/components/Pagination.tsx

@@ -0,0 +1,47 @@
+import { ArrowLeftIcon, ArrowRightIcon } from "lucide-react";
+import { Link } from "react-router";
+import { cn } from "../util/cn.js";
+import { Button } from "./index.js";
+
+export const Pagination = ({
+  prev,
+  next,
+}: {
+  prev: { to: string; label: string } | undefined;
+  next: { to: string; label: string } | undefined;
+}) => {
+  const linkClass =
+    "group transition-all p-5 space-x-1 transition-all hover:text-foreground";
+
+  return (
+    <div
+      className={cn(
+        "flex my-8 -mx-4 text-muted-foreground font-semibold",
+        prev ? "justify-between" : "justify-end",
+      )}
+    >
+      {prev && (
+        <Button variant="ghost" asChild>
+          <Link to={prev.to} relative="path" className={linkClass}>
+            <ArrowLeftIcon
+              className="group-hover:motion-safe:animate-bounce-x-start"
+              size={12}
+            />
+            <span className="truncate">{prev.label}</span>
+          </Link>
+        </Button>
+      )}
+      {next && (
+        <Button variant="ghost" asChild>
+          <Link to={next.to} relative="path" className={linkClass}>
+            <span className="truncate ">{next.label}</span>
+            <ArrowRightIcon
+              className="group-hover:motion-safe:animate-bounce-x-end"
+              size={12}
+            />
+          </Link>
+        </Button>
+      )}
+    </div>
+  );
+};

package/src/lib/components/TopNavigation.tsx

@@ -1,5 +1,6 @@
+import { useNProgress } from "@tanem/react-nprogress";
 import { cx } from "class-variance-authority";
-import { Suspense } from "react";
+import { Suspense, useEffect, useState } from "react";
 import { NavLink, useNavigation } from "react-router";
 import type { TopNavigationItem } from "../../config/validators/common.js";
 import { useAuth } from "../authentication/hook.js";
@@ -20,6 +21,31 @@ export const isHiddenItem =
     );
   };
 
+const Progress = () => {
+  const navigation = useNavigation();
+  const isNavigating = navigation.state === "loading";
+  // delay the animation to avoid flickering
+  const [isAnimating, setIsAnimating] = useState(false);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setIsAnimating(isNavigating), 100);
+
+    return () => clearTimeout(timer);
+  }, [isNavigating]);
+
+  const { isFinished, progress } = useNProgress({ isAnimating });
+
+  return (
+    <div
+      className="absolute w-0 left-0 right-0 bottom-[-1px] h-[2px] bg-primary transition-all duration-300 ease-in-out"
+      style={{
+        opacity: isFinished ? 0 : 1,
+        width: isFinished ? 0 : `${progress * 100}%`,
+      }}
+    />
+  );
+};
+
 export const TopNavigation = () => {
   const { topNavigation } = useZudoku();
   const { isAuthenticated } = useAuth();
@@ -32,7 +58,7 @@ export const TopNavigation = () => {
 
   return (
     <Suspense>
-      <div className="items-center justify-between px-8 h-[--top-nav-height] hidden lg:flex text-sm">
+      <div className="items-center justify-between px-8 h-[--top-nav-height] hidden lg:flex text-sm relative">
         <nav className="text-sm">
           <ul className="flex flex-row items-center gap-8">
             {filteredItems.map((item) => (
@@ -43,6 +69,7 @@ export const TopNavigation = () => {
           </ul>
         </nav>
         <Slotlet name="top-navigation-side" />
+        <Progress />
       </div>
     </Suspense>
   );

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

@@ -3,14 +3,14 @@ import { ExternalLinkIcon } from "lucide-react";
 import { NavLink, useLocation, useSearchParams } from "react-router";
 
 import type { SidebarItem as SidebarItemType } from "../../../config/validators/SidebarSchema.js";
-import { joinPath } from "../../util/joinPath.js";
+import { joinUrl } from "../../util/joinUrl.js";
 import { AnchorLink } from "../AnchorLink.js";
 import { useViewportAnchor } from "../context/ViewportAnchorContext.js";
 import { SidebarBadge } from "./SidebarBadge.js";
 import { SidebarCategory } from "./SidebarCategory.js";
 
 export const navigationListItem = cva(
-  "flex items-center gap-2 px-[--padding-nav-item] my-0.5 py-1.5 rounded-lg hover:bg-accent",
+  "flex items-center gap-2 px-[--padding-nav-item] my-0.5 py-1.5 rounded-lg hover:bg-accent tabular-nums",
   {
     variants: {
       isActive: {
@@ -21,6 +21,10 @@ export const navigationListItem = cva(
         true: "text-foreground/30",
         false: "",
       },
+      isPending: {
+        true: "bg-accent animate-pulse",
+        false: "",
+      },
     },
     defaultVariants: {
       isActive: false,
@@ -49,8 +53,10 @@ export const SidebarItem = ({
     case "doc":
       return (
         <NavLink
-          className={({ isActive }) => navigationListItem({ isActive })}
-          to={joinPath(item.id)}
+          className={({ isActive, isPending }) =>
+            navigationListItem({ isActive, isPending })
+          }
+          to={joinUrl(item.id)}
           onClick={onRequestClose}
           end
         >

package/src/lib/{plugins/markdown → components/navigation}/Toc.tsx

@@ -7,9 +7,9 @@ import {
   type CSSProperties,
   type PropsWithChildren,
 } from "react";
-import { AnchorLink } from "../../components/AnchorLink.js";
-import { useViewportAnchor } from "../../components/context/ViewportAnchorContext.js";
 import { cn } from "../../util/cn.js";
+import { AnchorLink } from "../AnchorLink.js";
+import { useViewportAnchor } from "../context/ViewportAnchorContext.js";
 
 const DATA_ANCHOR_ATTR = "data-active";
 
@@ -24,23 +24,14 @@ const TocItem = ({
   className?: string;
 }>) => {
   return (
-    <li
-      className={cn(
-        "truncate",
-        isActive
-          ? "text-primary"
-          : "text-foreground/65 dark:text-foreground/75",
-        className,
-      )}
-      title={item.value}
-    >
+    <li className={cn("truncate", className)} title={item.value}>
       <AnchorLink
         to={`#${item.id}`}
         {...{ [DATA_ANCHOR_ATTR]: item.id }}
         className={cn(
           isActive
             ? "text-primary"
-            : "text-foreground/65 dark:text-foreground/75 hover:text-foreground",
+            : "hover:text-accent-foreground text-muted-foreground",
         )}
       >
         {item.value}
@@ -89,7 +80,7 @@ export const Toc = ({ entries }: { entries: TocEntry[] }) => {
   }, [activeAnchor]);
 
   return (
-    <aside className="sticky scrollbar top-[--header-height] h-[calc(100vh-var(--header-height))] pt-[--padding-content-top] pb-[--padding-content-bottom] overflow-y-auto ps-1 text-sm">
+    <aside className="sticky scrollbar top-8 lg:top-[--header-height] h-[calc(100vh-var(--header-height))] pt-[--padding-content-top] pb-[--padding-content-bottom] overflow-y-auto ps-1 text-sm">
       <div className="flex items-center gap-2 font-medium mb-2">
         <ListTreeIcon size={16} />
         On this page

package/src/lib/core/ZudokuContext.ts

@@ -5,6 +5,7 @@ import type { Location } from "react-router";
 import type { TopNavigationItem } from "../../config/validators/common.js";
 import type { SidebarConfig } from "../../config/validators/SidebarSchema.js";
 import type { AuthenticationProvider } from "../authentication/authentication.js";
+import { type AuthState, useAuthState } from "../authentication/state.js";
 import type { ComponentsContextType } from "../components/context/ComponentsContext.js";
 import type { Slotlets } from "../components/SlotletProvider.js";
 import { joinPath } from "../util/joinPath.js";
@@ -21,6 +22,7 @@ import {
 
 export interface ZudokuEvents {
   location: (event: { from?: Location; to: Location }) => void;
+  auth: (auth: { prev: AuthState; next: AuthState }) => void;
 }
 
 export interface ApiIdentity {
@@ -67,6 +69,8 @@ type Page = Partial<{
 }>;
 
 export type ZudokuContextOptions = {
+  basePath?: string;
+  canonicalUrlOrigin?: string;
   metadata?: Metadata;
   page?: Page;
   authentication?: AuthenticationProvider;
@@ -106,7 +110,14 @@ export class ZudokuContext {
       if (!isEventConsumerPlugin(plugin)) return;
 
       objectEntries(plugin.events).forEach(([event, handler]) => {
-        this.emitter.on(event, handler);
+        this.emitter.on(event, handler!);
+      });
+    });
+
+    useAuthState.subscribe((state, prevState) => {
+      this.emitEvent("auth", {
+        prev: prevState,
+        next: state,
       });
     });
   }
@@ -158,10 +169,6 @@ export class ZudokuContext {
       throw new Error("No authentication provider configured");
     }
 
-    const accessToken = await this.authentication.getAccessToken();
-
-    request.headers.set("Authorization", `Bearer ${accessToken}`);
-
-    return request;
+    return await this.authentication.signRequest(request);
   };
 }

package/src/lib/core/plugins.ts

@@ -65,7 +65,7 @@ export interface CommonPlugin {
 }
 
 export type EventConsumerPlugin<Event extends ZudokuEvents = ZudokuEvents> = {
-  events: { [K in keyof Event]: Event[K] };
+  events: { [K in keyof Event]?: Event[K] };
 };
 
 export const isEventConsumerPlugin = (

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

@@ -97,7 +97,7 @@ const resolveExtensions = (obj: Record<string, any>) =>
 export const getAllTags = (
   schema: OpenAPIDocument,
   slugs: ReturnType<typeof getAllSlugs>["tags"],
-): Array<TagObject & { slug?: string }> => {
+): Array<Omit<TagObject, "name"> & { name?: string; slug?: string }> => {
   const rootTags = schema.tags ?? [];
   const operationTags = new Set(
     Object.values(schema.paths ?? {})
@@ -105,6 +105,12 @@ export const getAllTags = (
       .flatMap((op) => (op as OperationObject).tags ?? []),
   );
 
+  const hasUntaggedOperations = Object.values(schema.paths ?? {}).some((path) =>
+    Object.values(path ?? {}).some(
+      (op) => !(op as OperationObject).tags?.length,
+    ),
+  );
+
   return [
     // Keep root tags that are actually used in operations
     ...rootTags
@@ -114,6 +120,8 @@ export const getAllTags = (
     ...[...operationTags]
       .filter((tag) => !rootTags.some((rt) => rt.name === tag))
       .map((tag) => ({ name: tag, slug: slugs[tag] })),
+    // Add untagged operations if there are any
+    ...(hasUntaggedOperations ? [{ name: undefined, slug: undefined }] : []),
   ];
 };
 
@@ -181,38 +189,55 @@ export const getAllOperations = (
   return operations;
 };
 
-const SchemaTag = builder
-  .objectRef<
-    Omit<TagObject, "name"> & { name?: string; slug?: string }
-  >("SchemaTag")
-  .implement({
-    fields: (t) => ({
-      name: t.exposeString("name", { nullable: true }),
-      slug: t.exposeString("slug", { nullable: true }),
-      description: t.exposeString("description", { nullable: true }),
-      operations: t.field({
-        type: [OperationItem],
-        resolve: (parent, _args, ctx) => {
-          const rootTags = ctx.tags.map((tag) => tag.name);
-
-          return ctx.operations
-            .filter((item) =>
-              parent.name
-                ? item.tags?.includes(parent.name)
-                : item.tags?.length === 0 ||
-                  // If none of the tags are present in the root tags, then show them here
-                  item.tags?.every((tag) => !rootTags.includes(tag)),
-            )
-            .map((item) => ({ ...item, parentTag: parent.name }));
-        },
-      }),
-      extensions: t.field({
-        type: JSONObjectScalar,
-        resolve: (parent) => resolveExtensions(parent),
-        nullable: true,
-      }),
+const SchemaTag = builder.objectRef<
+  Omit<TagObject, "name"> & { name?: string; slug?: string }
+>("SchemaTag");
+
+SchemaTag.implement({
+  fields: (t) => ({
+    name: t.exposeString("name", { nullable: true }),
+    slug: t.exposeString("slug", { nullable: true }),
+    isUntagged: t.field({ type: "Boolean", resolve: (parent) => !parent.name }),
+    description: t.exposeString("description", { nullable: true }),
+    operations: t.field({
+      type: [OperationItem],
+      resolve: (parent, _args, ctx) => {
+        const rootTags = ctx.tags.map((tag) => tag.name);
+
+        return ctx.operations
+          .filter((item) =>
+            parent.name
+              ? item.tags?.includes(parent.name)
+              : item.tags?.length === 0 ||
+                // If none of the tags are present in the root tags, then show them here
+                item.tags?.every((tag) => !rootTags.includes(tag)),
+          )
+          .map((item) => ({ ...item, parentTag: parent.name }));
+      },
     }),
-  });
+    prev: t.field({
+      type: SchemaTag,
+      nullable: true,
+      resolve: (parent, _args, ctx) => {
+        const index = ctx.tags.findIndex((tag) => tag.slug === parent.slug);
+        return ctx.tags[index - 1];
+      },
+    }),
+    next: t.field({
+      type: SchemaTag,
+      nullable: true,
+      resolve: (parent, _args, ctx) => {
+        const index = ctx.tags.findIndex((tag) => tag.slug === parent.slug);
+        return ctx.tags[index + 1];
+      },
+    }),
+    extensions: t.field({
+      type: JSONObjectScalar,
+      resolve: (parent) => resolveExtensions(parent),
+      nullable: true,
+    }),
+  }),
+});
 
 const ServerItem = builder.objectRef<ServerObject>("Server").implement({
   fields: (t) => ({
@@ -466,6 +491,43 @@ const OperationItem = builder
     }),
   });
 
+const SchemaItem = builder
+  .objectRef<{
+    name: string;
+    schema: SchemaObject;
+    extensions?: Record<string, any>;
+  }>("SchemaItem")
+  .implement({
+    fields: (t) => ({
+      name: t.exposeString("name"),
+      schema: t.expose("schema", { type: JSONSchemaScalar }),
+      extensions: t.expose("extensions", {
+        type: JSONObjectScalar,
+        nullable: true,
+      }),
+    }),
+  });
+
+const Components = builder.objectRef<{
+  schemas?: Record<string, SchemaObject>;
+}>("Components");
+
+Components.implement({
+  fields: (t) => ({
+    schemas: t.field({
+      type: [SchemaItem],
+      resolve: (parent) => {
+        return Object.entries(parent.schemas ?? {}).map(([name, schema]) => ({
+          name,
+          schema,
+          extensions: resolveExtensions(schema),
+        }));
+      },
+      nullable: true,
+    }),
+  }),
+});
+
 const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
   fields: (t) => ({
     openapi: t.string({ resolve: (root) => root.openapi }),
@@ -495,24 +557,30 @@ const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
           methods: Object.keys(value!) as typeof HttpMethods,
         })),
     }),
-    tags: t.field({
+    tag: t.field({
+      type: SchemaTag,
       args: {
+        slug: t.arg.string(),
         name: t.arg.string(),
+        untagged: t.arg.boolean(),
       },
-      type: [SchemaTag],
-      resolve: (_root, args, ctx) => {
-        if (args.name) {
-          return ctx.tags.filter((tag) => tag.name === args.name);
+      nullable: true,
+      resolve: (_, args, ctx) => {
+        if (args.untagged) {
+          return ctx.tags.find((tag) => tag.name === undefined);
         }
-
-        // Append empty tag which will be used to display untagged operations
-        if (ctx.operations.some((op) => !op.tags?.length)) {
-          return [...ctx.tags, { name: undefined, slug: undefined }];
+        if (args.slug) {
+          return ctx.tags.find((tag) => tag.slug === args.slug);
+        }
+        if (args.name) {
+          return ctx.tags.find((tag) => tag.name === args.name);
         }
-
-        return ctx.tags;
       },
     }),
+    tags: t.field({
+      type: [SchemaTag],
+      resolve: (_root, _args, ctx) => ctx.tags,
+    }),
     operations: t.field({
       type: [OperationItem],
       args: {
@@ -522,7 +590,7 @@ const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
         tag: t.arg.string(),
         untagged: t.arg.boolean(),
       },
-      resolve: (parent, args, ctx) =>
+      resolve: (_parent, args, ctx) =>
         ctx.operations.filter((op) => {
           return (
             (!args.operationId || op.operationId === args.operationId) &&
@@ -533,6 +601,11 @@ const Schema = builder.objectRef<OpenAPIDocument>("Schema").implement({
           );
         }),
     }),
+    components: t.field({
+      type: Components,
+      resolve: (root) => root.components,
+      nullable: true,
+    }),
     extensions: t.field({
       type: JSONObjectScalar,
       resolve: (root) => resolveExtensions(root),
@@ -553,7 +626,7 @@ builder.queryType({
         type: t.arg({ type: SchemaSource, required: true }),
         input: t.arg({ type: JSONScalar, required: true }),
       },
-      resolve: async (_, args, ctx) => {
+      resolve: async (_parent, args, ctx) => {
         if (args.type === "file" && typeof args.input === "string") {
           const loadSchema = ctx.schemaImports?.[args.input];
 

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

@@ -38,6 +38,8 @@ export const dereference = async (
         }
       } else {
         if ("$ref" in current && typeof current.$ref === "string") {
+          // Store the ref path before resolving
+          current.__$ref = current.$ref;
           for (const resolver of resolvers) {
             const resolved = await resolver(current.$ref);
             if (resolved) return await resolve(resolved, path);