Per-version tag routes, smart version switching, and nav animation fix

Author: dan-lee

examples/cosmo-cargo/schema/fleet-ops.json

@@ -8,6 +8,20 @@ const buildConfig: ZudokuBuildConfig = {
 
       return schema;
     },
+    ({ schema, params }) => {
+      const prefix = params.prefix;
+      if (!prefix) return schema;
+
+      return {
+        ...schema,
+        info: { ...schema.info, version: prefix },
+        paths: Object.fromEntries(
+          Object.entries(schema.paths ?? {}).filter(([path]) =>
+            path.startsWith(prefix),
+          ),
+        ),
+      };
+    },
   ],
   prerender: {
     workers: Math.floor(os.cpus().length * 0.75),

examples/cosmo-cargo/zudoku.build.ts

@@ -372,6 +372,28 @@ const config: ZudokuConfig = {
       path: "/catalog/api-cargo-containers",
       categories: [{ label: "General", tags: ["Containers", "Booking"] }],
     },
+    {
+      type: "file",
+      input: [
+        {
+          input: "./schema/fleet-ops.json?prefix=/v3",
+          path: "v3",
+          label: "v3 (Quantum)",
+        },
+        {
+          input: "./schema/fleet-ops.json?prefix=/v2",
+          path: "v2",
+          label: "v2 (Warp)",
+        },
+        {
+          input: "./schema/fleet-ops.json?prefix=/v1",
+          path: "v1",
+          label: "v1 (Sublight)",
+        },
+      ],
+      path: "/catalog/api-fleet-ops",
+      categories: [{ label: "General", tags: ["Fleet Command"] }],
+    },
   ],
   theme: {
     light: {

examples/cosmo-cargo/zudoku.config.tsx

@@ -100,9 +100,9 @@ const NavigationCategoryInner = ({
             }}
             className={styles}
             onClick={() => {
-              setHasInteracted(true);
               // if it is the current path and closed then open it because there's no path change to trigger the open
               if (isActive && !open) {
+                setHasInteracted(true);
                 setOpen(true);
               }
             }}
@@ -114,14 +114,7 @@ const NavigationCategoryInner = ({
             </div>
           </NavLink>
         ) : (
-          // biome-ignore lint/a11y/noStaticElementInteractions: This is only to track if the user has interacted
-          <div
-            onClick={() => setHasInteracted(true)}
-            onKeyUp={(e) => {
-              if (e.key === "Enter" || e.key === " ") setHasInteracted(true);
-            }}
-            className={styles}
-          >
+          <div className={styles}>
             {icon}
             <div className="flex items-center justify-between w-full">
               <div className="flex gap-2 truncate w-full">{category.label}</div>
@@ -137,6 +130,7 @@ const NavigationCategoryInner = ({
           category.items.length === 0 && "hidden",
           "ms-6 my-1",
         )}
+        onAnimationEnd={() => setHasInteracted(false)}
       >
         <ul className="relative after:absolute after:-inset-s-(--padding-nav-item) after:translate-x-[1.5px] after:top-0 after:bottom-0 after:w-px after:bg-border">
           {category.items.map((item) => (

packages/zudoku/src/lib/components/navigation/NavigationCategory.tsx

@@ -18,13 +18,15 @@ import { Heading } from "../../components/Heading.js";
 import { Markdown } from "../../components/Markdown.js";
 import { useOasConfig } from "./context.js";
 import { DownloadSchemaButton } from "./DownloadSchemaButton.js";
+import { buildVersionSwitchUrl } from "./util/getRoutes.js";
 
 type ApiHeaderProps = {
   title: string;
   heading: ReactNode;
   headingId: string;
   description?: string;
   children?: ReactNode;
+  tag?: string;
 };
 
 export const ApiHeader = ({
@@ -33,11 +35,12 @@ export const ApiHeader = ({
   headingId,
   description,
   children,
+  tag,
 }: ApiHeaderProps) => {
   const { input, type, versions, version, options } = useOasConfig();
   const navigate = useNavigate();
 
-  const hasMultipleVersions = Object.entries(versions).length > 1;
+  const hasMultipleVersions = Object.keys(versions).length > 1;
   const showVersions =
     options?.showVersionSelect === "always" ||
     (hasMultipleVersions && options?.showVersionSelect !== "hide");
@@ -50,6 +53,13 @@ export const ApiHeader = ({
         : currentVersion?.downloadUrl
       : undefined;
 
+  const handleVersionChange = (newVersion: string) => {
+    const target = versions[newVersion];
+    if (!target) return;
+
+    navigate(buildVersionSwitchUrl(target, tag));
+  };
+
   return (
     <Collapsible className="w-full" defaultOpen={options?.expandApiInformation}>
       <div className="flex flex-col gap-4 sm:flex-row justify-around items-start sm:items-end">
@@ -70,11 +80,8 @@ export const ApiHeader = ({
           <div className="flex gap-2 items-center">
             {showVersions && (
               <Select
-                onValueChange={(v) =>
-                  // biome-ignore lint/style/noNonNullAssertion: is guaranteed to be defined
-                  navigate(versions[v]!.path)
-                }
-                defaultValue={version}
+                onValueChange={handleVersionChange}
+                value={version}
                 disabled={!hasMultipleVersions}
               >
                 <SelectTrigger className="w-[180px]" size="sm">

packages/zudoku/src/lib/plugins/openapi/ApiHeader.tsx

@@ -19,22 +19,23 @@ export const OasProvider = ({
   client: GraphQLClient;
 }) => {
   const value = useMemo(() => {
-    const {
-      versions: availableVersions,
-      labels,
-      downloadUrls,
-    } = getVersionMetadata(config);
+    const { versions: availableVersions, versionMap } =
+      getVersionMetadata(config);
     const currentVersion = version ?? availableVersions.at(0);
 
-    const versionLinks = Object.fromEntries(
-      availableVersions.map((id) => [
-        id,
-        {
-          path: joinUrl(basePath, id),
-          label: labels[id] ?? id,
-          downloadUrl: downloadUrls[id],
-        },
-      ]),
+    const versions = Object.fromEntries(
+      availableVersions.map((id) => {
+        const meta = versionMap[id];
+        return [
+          id,
+          {
+            path: joinUrl(basePath, id),
+            label: meta?.label ?? id,
+            downloadUrl: meta?.downloadUrl,
+            tagPages: meta?.tagPages,
+          },
+        ];
+      }),
     );
 
     const resolveInput = (): string | (() => Promise<unknown>) => {
@@ -57,7 +58,7 @@ export const OasProvider = ({
       config: {
         ...config,
         version: currentVersion,
-        versions: versionLinks,
+        versions,
         input: resolveInput(),
       },
     };

packages/zudoku/src/lib/plugins/openapi/OasProvider.tsx

@@ -258,6 +258,7 @@ export const OperationList = ({
           heading={tagTitle}
           headingId="description"
           description={description ?? undefined}
+          tag={tag ?? tagFromParams}
         >
           <Endpoint />
         </ApiHeader>

packages/zudoku/src/lib/plugins/openapi/OperationList.tsx

@@ -12,6 +12,7 @@ export type VersionedInput<T = string> = {
   label?: string;
   input: T;
   hasUntaggedOperations?: boolean;
+  tagPages?: string[];
 };
 
 type OasSource =
@@ -85,11 +86,15 @@ type BaseOasConfig = {
 
 export type OasPluginConfig = BaseOasConfig & OasSource;
 
+export type VersionEntry = {
+  path: string;
+  label: string;
+  downloadUrl?: string;
+  tagPages?: string[];
+};
+
 export type OasPluginContext = BaseOasConfig &
   ContextOasSource & {
     version?: string;
-    versions: Record<
-      string,
-      { path: string; label: string; downloadUrl?: string }
-    >;
+    versions: Record<string, VersionEntry>;
   };

packages/zudoku/src/lib/plugins/openapi/interfaces.ts

@@ -1,7 +1,11 @@
 import { describe, expect, it } from "vitest";
 import type { GraphQLClient } from "../client/GraphQLClient.js";
 import type { OpenApiPluginOptions } from "../index.js";
-import { getRoutes, getVersionMetadata } from "./getRoutes.js";
+import {
+  buildVersionSwitchUrl,
+  getRoutes,
+  getVersionMetadata,
+} from "./getRoutes.js";
 
 const mockClient = {} as GraphQLClient;
 
@@ -13,23 +17,15 @@ const baseConfig: OpenApiPluginOptions = {
 describe("getVersionMetadata", () => {
   it("returns empty metadata for raw type", () => {
     const result = getVersionMetadata({ type: "raw", input: "{}" });
-    expect(result).toEqual({
-      versions: [],
-      labels: {},
-      downloadUrls: {},
-    });
+    expect(result).toEqual({ versions: [], versionMap: {} });
   });
 
   it("returns empty metadata for non-array input", () => {
     const result = getVersionMetadata({
       type: "url",
       input: "https://example.com/openapi.json",
     });
-    expect(result).toEqual({
-      versions: [],
-      labels: {},
-      downloadUrls: {},
-    });
+    expect(result).toEqual({ versions: [], versionMap: {} });
   });
 
   it("extracts versions, labels and download URLs from versioned input", () => {
@@ -50,12 +46,17 @@ describe("getVersionMetadata", () => {
       ],
     });
 
-    expect(result).toEqual({
-      versions: ["v1", "v2"],
-      labels: { v1: "Version 1", v2: "v2" },
-      downloadUrls: {
-        v1: "https://example.com/v1.json",
-        v2: "https://example.com/v2.json",
+    expect(result.versions).toEqual(["v1", "v2"]);
+    expect(result.versionMap).toEqual({
+      v1: {
+        label: "Version 1",
+        downloadUrl: "https://example.com/v1.json",
+        tagPages: undefined,
+      },
+      v2: {
+        label: "v2",
+        downloadUrl: "https://example.com/v2.json",
+        tagPages: undefined,
       },
     });
   });
@@ -66,8 +67,11 @@ describe("getVersionMetadata", () => {
       input: [{ path: "v3", input: "https://example.com/v3.json" }],
     });
 
-    expect(result.labels).toEqual({ v3: "v3" });
-    expect(result.downloadUrls).toEqual({ v3: undefined });
+    expect(result.versionMap.v3).toEqual({
+      label: "v3",
+      downloadUrl: undefined,
+      tagPages: undefined,
+    });
   });
 
   it("extracts metadata from file type with versioned input", () => {
@@ -83,10 +87,11 @@ describe("getVersionMetadata", () => {
       ],
     });
 
-    expect(result).toEqual({
-      versions: ["v1"],
-      labels: { v1: "File V1" },
-      downloadUrls: { v1: "https://example.com/v1.json" },
+    expect(result.versions).toEqual(["v1"]);
+    expect(result.versionMap.v1).toEqual({
+      label: "File V1",
+      downloadUrl: "https://example.com/v1.json",
+      tagPages: undefined,
     });
   });
 });
@@ -466,3 +471,29 @@ describe("getRoutes", () => {
     ).toBeDefined();
   });
 });
+
+describe("buildVersionSwitchUrl", () => {
+  it("preserves tag when it exists in target version", () => {
+    const target = {
+      path: "/api/v2",
+      label: "V2",
+      tagPages: ["users", "posts"],
+    };
+    expect(buildVersionSwitchUrl(target, "users")).toBe("/api/v2/users");
+  });
+
+  it("falls back to version root when tag missing in target", () => {
+    const target = { path: "/api/v2", label: "V2", tagPages: ["users"] };
+    expect(buildVersionSwitchUrl(target, "analytics")).toBe("/api/v2");
+  });
+
+  it("preserves tag when target has no tagPages (URL schemas)", () => {
+    const target = { path: "/api/v2", label: "V2" };
+    expect(buildVersionSwitchUrl(target, "users")).toBe("/api/v2/users");
+  });
+
+  it("returns version root when no current tag", () => {
+    const target = { path: "/api/v2", label: "V2", tagPages: ["users"] };
+    expect(buildVersionSwitchUrl(target, undefined)).toBe("/api/v2");
+  });
+});