zudoku 0.0.0-fix-downgrade-openapi-parser.aac00796 → 0.0.0-fix-prevent-full-deref-allof.b02efbe5

package/src/lib/core/plugins.ts

@@ -1,5 +1,5 @@
 import type { LucideIcon } from "lucide-react";
-import type { ReactElement } from "react";
+import type { ReactNode } from "react";
 import type { Location, RouteObject } from "react-router";
 import type { Navigation } from "../../config/validators/NavigationSchema.js";
 import type { ProtectedRoutesInput } from "../../config/validators/ProtectedRoutesSchema.js";
@@ -64,7 +64,7 @@ export interface CommonPlugin {
   initialize?: (
     context: ZudokuContext,
   ) => Promise<void | boolean> | void | boolean;
-  getHead?: ({ location }: { location: Location }) => ReactElement | undefined;
+  getHead?: (args: { location: Location }) => ReactNode | undefined;
   getMdxComponents?: () => MdxComponentsType;
 }
 

package/src/lib/errors/ErrorAlert.tsx

@@ -17,7 +17,7 @@ export function ErrorAlert({ error }: { error: unknown }) {
   const stringError = cause instanceof Error ? String(cause.stack) : stack;
 
   return (
-    <Typography className="grid grid-cols-1 !max-w-none pt-(--padding-content-top)">
+    <Typography className="grid grid-cols-1 max-w-none! pt-(--padding-content-top)">
       <Heading level={1}>{title}</Heading>
       Error: {message}
       {hint && <DeveloperHint className="mb-4">{hint}</DeveloperHint>}

package/src/lib/errors/RouterError.tsx

@@ -1,13 +1,18 @@
 import { isRouteErrorResponse, useRouteError } from "react-router";
 import { NotFoundPage } from "../components/NotFoundPage.js";
+import { cn } from "../util/cn.js";
 import { ErrorAlert } from "./ErrorAlert.js";
 
-export function RouterError() {
+export function RouterError({ className }: { className?: string }) {
   const error = useRouteError();
 
   if (isRouteErrorResponse(error) && error.status === 404) {
     return <NotFoundPage />;
   }
 
-  return <ErrorAlert error={error} />;
+  return (
+    <div className={cn("mx-4 max-w-2xl", className)}>
+      <ErrorAlert error={error} />
+    </div>
+  );
 }

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

@@ -1,6 +1,6 @@
-import { merge as mergeAllOf } from "allof-merge";
 import { GraphQLError } from "graphql/error/index.js";
 import { OpenAPIV3, type OpenAPIV3_1 } from "openapi-types";
+import { flattenAllOfProcessor } from "../../util/flattenAllOf.js";
 import { dereference, type JSONSchema } from "./dereference/index.js";
 import { upgradeSchema } from "./upgrade/index.js";
 
@@ -25,6 +25,8 @@ 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 ArraySchemaObject =
+  DeepOmitReference<OpenAPIV3_1.ArraySchemaObject>;
 export type ServerObject = DeepOmitReference<OpenAPIV3_1.ServerObject>;
 
 export const HttpMethods = Object.values(OpenAPIV3.HttpMethods);
@@ -101,7 +103,12 @@ export const validate = async (schemaInput: unknown) => {
 
   const dereferenced = await dereference(schema);
   const upgraded = upgradeSchema(dereferenced);
-  const merged = mergeAllOf(upgraded) as OpenAPIDocument;
 
-  return merged;
+  const flattened = await flattenAllOfProcessor({
+    schema: upgraded,
+    file: "schema.json",
+    dereference: async (schema) => schema,
+  });
+
+  return flattened;
 };

package/src/lib/plugins/api-keys/ProtectedRoute.tsx

@@ -11,15 +11,19 @@ export const ProtectedRoute = () => {
     return null;
   }
 
+  if (!auth.isAuthEnabled) {
+    return (
+      <div className="flex flex-col justify-center gap-2 items-center h-1/2">
+        <DeveloperHint className="max-w-[600px]">
+          Authentication needs to be enabled for API keys to work. Enable it in
+          your Zudoku configuration under <code>authentication</code>.
+        </DeveloperHint>
+      </div>
+    );
+  }
+
   return auth.isAuthenticated ? (
     <Outlet />
-  ) : !auth.isAuthEnabled ? (
-    <div className="flex flex-col justify-center gap-2 items-center h-1/2">
-      <DeveloperHint className="max-w-[600px]">
-        Authentication needs to be enabled for API keys to work. Enable it in
-        your Zudoku configuration under <code>authentication</code>.
-      </DeveloperHint>
-    </div>
   ) : (
     <div className="flex flex-col justify-center gap-2 items-center h-1/2">
       Please login first to view this page

package/src/lib/plugins/openapi/CollapsibleCode.tsx

@@ -9,6 +9,10 @@ import {
 import { cn } from "../../util/cn.js";
 import useIsomorphicLayoutEffect from "../../util/useIsomorphicLayoutEffect.js";
 
+export const OverflowOverlay = () => (
+  <div className="absolute inset-0 bg-linear-to-b from-transparent to-zinc-50/60 dark:to-zinc-950/90 z-10 transition-all group-hover:to-transparent" />
+);
+
 export const CollapsibleCode = ({
   children,
   maxHeight = 250,
@@ -48,9 +52,7 @@ export const CollapsibleCode = ({
           !open && isOverflowing && "max-h-(--max-height)",
         )}
       >
-        {!open && isOverflowing && (
-          <div className=" absolute inset-0 bg-gradient-to-b from-transparent to-zinc-50/60 dark:to-zinc-950/90 z-10 transition-all group-hover:to-transparent"></div>
-        )}
+        {!open && isOverflowing && <OverflowOverlay />}
         <div ref={contentRef}>{children}</div>
         {!open && isOverflowing && (
           <CollapsibleTrigger

package/src/lib/plugins/openapi/DownloadSchemaButton.tsx

@@ -0,0 +1,115 @@
+import {
+  ChevronDownIcon,
+  CopyIcon,
+  DownloadIcon,
+  ExternalLinkIcon,
+} from "lucide-react";
+import type { MouseEventHandler } from "react";
+import { Button } from "zudoku/components";
+import { ButtonGroup } from "zudoku/ui/ButtonGroup.js";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "zudoku/ui/DropdownMenu.js";
+import { useCopyToClipboard } from "../../util/useCopyToClipboard.js";
+import { ChatGPTLogo } from "../markdown/assets/ChatGPTLogo.js";
+import { ClaudeLogo } from "../markdown/assets/ClaudeLogo.js";
+
+export const DownloadSchemaButton = ({
+  downloadUrl,
+}: {
+  downloadUrl: string;
+}) => {
+  const [, copyToClipboard] = useCopyToClipboard();
+
+  const handleDownload: MouseEventHandler<HTMLAnchorElement> = async (e) => {
+    const isExternal = downloadUrl.includes("://");
+
+    if (!isExternal) return;
+
+    e.preventDefault();
+    try {
+      const response = await fetch(downloadUrl);
+      if (!response.ok)
+        throw new Error(`Failed to fetch: ${response.statusText}`);
+
+      const blob = await response.blob();
+      const url = window.URL.createObjectURL(blob);
+      const a = document.createElement("a");
+      a.href = url;
+      a.download = downloadUrl.split("/").pop() || "schema.json";
+      document.body.appendChild(a);
+      a.click();
+      document.body.removeChild(a);
+      window.URL.revokeObjectURL(url);
+    } catch (error) {
+      // biome-ignore lint/suspicious/noConsole: Logging error
+      console.error("Failed to download schema:", error);
+    }
+  };
+
+  return (
+    <ButtonGroup>
+      <Button
+        variant="outline"
+        size="sm"
+        className="flex items-center gap-1.5"
+        asChild
+      >
+        <a href={downloadUrl} download onClick={handleDownload}>
+          <DownloadIcon size={14} />
+          Download schema
+        </a>
+      </Button>
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <Button size="sm" variant="outline" className="px-1.5">
+            <ChevronDownIcon size={14} />
+          </Button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="end">
+          <DropdownMenuItem asChild>
+            <a href={downloadUrl} target="_blank" rel="noopener noreferrer">
+              <ExternalLinkIcon size={14} />
+              Open in new tab
+            </a>
+          </DropdownMenuItem>
+          <DropdownMenuItem
+            onClick={async () => {
+              const response = await fetch(downloadUrl);
+              const schema = await response.text();
+              copyToClipboard(schema);
+            }}
+          >
+            <CopyIcon size={14} />
+            Copy to clipboard
+          </DropdownMenuItem>
+          <DropdownMenuItem
+            onClick={() => {
+              const prompt = encodeURIComponent(
+                `Help me understand this API: ${new URL(downloadUrl, window.location.href).href}`,
+              );
+              window.open(`https://claude.ai/new?q=${prompt}`, "_blank");
+            }}
+          >
+            <ClaudeLogo className="size-4" />
+            Use in Claude
+          </DropdownMenuItem>
+          <DropdownMenuItem
+            onClick={() => {
+              const prompt = encodeURIComponent(
+                `Help me understand this API: ${new URL(downloadUrl, window.location.href).href}`,
+              );
+              window.open(`https://chatgpt.com/?q=${prompt}`, "_blank");
+            }}
+          >
+            <ChatGPTLogo className="size-4" />
+            Use in ChatGPT
+          </DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </ButtonGroup>
+  );
+};

package/src/lib/plugins/openapi/Endpoint.tsx

@@ -32,7 +32,7 @@ const CopyButton = ({ url }: { url: string }) => {
         });
       }}
       variant="ghost"
-      size="icon"
+      size="icon-xs"
     >
       {isCopied ? (
         <CheckIcon className="text-green-600" size={14} />
@@ -53,40 +53,33 @@ export const Endpoint = () => {
   );
 
   const { servers } = result.data.schema;
-
   const firstServer = servers.at(0);
 
   if (!firstServer) return null;
 
-  if (servers.length === 1) {
-    return (
-      <div className="flex items-center gap-2">
-        <span className="font-medium text-sm">Endpoint:</span>
+  return (
+    <div className="flex items-center gap-1.5 flex-nowrap">
+      <span className="font-medium text-sm">Endpoint</span>
+      {servers.length > 1 ? (
+        <SimpleSelect
+          className="font-mono text-xs border-input bg-transparent dark:bg-input/30 dark:hover:bg-input/50 py-1.5 max-w-[450px] truncate"
+          onChange={(e) =>
+            startTransition(() => setSelectedServer(e.target.value))
+          }
+          value={selectedServer}
+          showChevrons={servers.length > 1}
+          options={servers.map((server) => ({
+            value: server.url,
+            label: server.url,
+          }))}
+        />
+      ) : (
         <InlineCode className="text-xs px-2 py-1.5" selectOnClick>
           {firstServer.url}
         </InlineCode>
-        <CopyButton url={firstServer.url} />
-      </div>
-    );
-  }
-
-  return (
-    <div className="flex flex-wrap items-center gap-2">
-      <span className="font-medium text-sm">Endpoint</span>
+      )}
 
-      <SimpleSelect
-        className="font-mono text-xs bg-border/50 dark:bg-border/70 py-1.5 max-w-[450px] truncate"
-        onChange={(e) =>
-          startTransition(() => setSelectedServer(e.target.value))
-        }
-        value={selectedServer}
-        showChevrons={servers.length > 1}
-        options={servers.map((server) => ({
-          value: server.url,
-          label: server.url,
-        }))}
-      />
-      <CopyButton url={selectedServer} />
+      <CopyButton url={servers.length > 1 ? selectedServer : firstServer.url} />
     </div>
   );
 };

package/src/lib/plugins/openapi/GeneratedExampleSidecarBox.tsx

@@ -0,0 +1,52 @@
+import { InfoIcon } from "lucide-react";
+import { SyntaxHighlight } from "zudoku/ui/SyntaxHighlight.js";
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "zudoku/ui/Tooltip.js";
+import { NonHighlightedCode } from "./components/NonHighlightedCode.js";
+import * as SidecarBox from "./SidecarBox.js";
+
+export const GeneratedExampleSidecarBox = ({
+  code,
+  isOnScreen,
+  shouldLazyHighlight,
+}: {
+  code: string;
+  isOnScreen: boolean;
+  shouldLazyHighlight?: boolean;
+}) => {
+  return (
+    <SidecarBox.Root>
+      <SidecarBox.Head className="text-xs flex justify-between items-center">
+        <div className="flex items-center gap-1.5">
+          <span className="font-medium">Example Request Body</span>
+          <TooltipProvider>
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <InfoIcon size={13} />
+              </TooltipTrigger>
+              <TooltipContent>
+                This example is auto-generated from the schema.
+              </TooltipContent>
+            </Tooltip>
+          </TooltipProvider>
+        </div>
+      </SidecarBox.Head>
+      <SidecarBox.Body className="p-0">
+        {shouldLazyHighlight && !isOnScreen ? (
+          <NonHighlightedCode code={code} />
+        ) : (
+          <SyntaxHighlight
+            embedded
+            language="json"
+            code={code}
+            className="[--scrollbar-color:gray] rounded-none text-xs max-h-[200px]"
+          />
+        )}
+      </SidecarBox.Body>
+    </SidecarBox.Root>
+  );
+};

package/src/lib/plugins/openapi/OasProvider.tsx

@@ -1,11 +1,11 @@
 import { useMemo } from "react";
 import { Outlet } from "react-router";
-import { joinPath } from "../../util/joinPath.js";
+import { joinUrl } from "../../util/joinUrl.js";
 import type { GraphQLClient } from "./client/GraphQLClient.js";
 import { GraphQLProvider } from "./client/GraphQLContext.js";
 import { OasConfigProvider } from "./context.js";
 import type { OasPluginConfig } from "./interfaces.js";
-import { getVersions } from "./util/getRoutes.js";
+import { getVersionMetadata } from "./util/getRoutes.js";
 
 export const OasProvider = ({
   basePath,
@@ -19,25 +19,38 @@ export const OasProvider = ({
   client: GraphQLClient;
 }) => {
   const value = useMemo(() => {
-    const versions = getVersions(config);
-    const firstVersion = Object.values(config.input).at(0);
-    const input =
-      config.type === "file"
-        ? {
-            type: config.type,
-            // biome-ignore lint/style/noNonNullAssertion: is guaranteed to be defined
-            input: version ? config.input[version]! : firstVersion!,
-          }
-        : { type: config.type, input: config.input };
+    const { versions: availableVersions, labels } = getVersionMetadata(config);
+    const currentVersion = version ?? availableVersions.at(0);
+
+    const versionLinks = Object.fromEntries(
+      availableVersions.map((id) => [
+        id,
+        { path: joinUrl(basePath, id), label: labels[id] ?? id },
+      ]),
+    );
+
+    const resolveInput = (): string | (() => Promise<unknown>) => {
+      if (!Array.isArray(config.input)) {
+        return config.input;
+      }
+
+      const versionConfig = currentVersion
+        ? config.input.find((v) => v.path === currentVersion)
+        : config.input[0];
+
+      if (!versionConfig) {
+        throw new Error(`No input found for version: ${currentVersion}`);
+      }
+
+      return versionConfig.input;
+    };
 
     return {
       config: {
         ...config,
-        version: version ?? versions.at(0),
-        versions: Object.fromEntries(
-          versions.map((version) => [version, joinPath(basePath, version)]),
-        ),
-        ...input,
+        version: currentVersion,
+        versions: versionLinks,
+        input: resolveInput(),
       },
     };
   }, [config, basePath, version]);

package/src/lib/plugins/openapi/OperationList.tsx

@@ -18,9 +18,12 @@ import { CategoryHeading } from "../../components/CategoryHeading.js";
 import { useApiIdentities } from "../../components/context/ZudokuContext.js";
 import { Heading } from "../../components/Heading.js";
 import { Markdown } from "../../components/Markdown.js";
+import { PagefindSearchMeta } from "../../components/PagefindSearchMeta.js";
 import { Pagination } from "../../components/Pagination.js";
+import { joinUrl } from "../../util/joinUrl.js";
 import { useCreateQuery } from "./client/useCreateQuery.js";
 import { useOasConfig } from "./context.js";
+import { DownloadSchemaButton } from "./DownloadSchemaButton.js";
 import { Endpoint } from "./Endpoint.js";
 import { graphql } from "./graphql/index.js";
 import { UNTAGGED_PATH } from "./index.js";
@@ -146,6 +149,8 @@ const OperationsForTagQuery = graphql(/* GraphQL */ `
   }
 `);
 
+const LAZY_OPERATION_LIST_THRESHOLD = 30;
+
 export const OperationList = ({
   tag,
   untagged,
@@ -153,7 +158,7 @@ export const OperationList = ({
   tag?: string;
   untagged?: boolean;
 }) => {
-  const { input, type, versions, version, options } = useOasConfig();
+  const { path, input, type, versions, version, options } = useOasConfig();
   const { tag: tagFromParams } = useParams<"tag">();
   const query = useCreateQuery(OperationsForTagQuery, {
     input,
@@ -200,6 +205,10 @@ export const OperationList = ({
 
   const { operations, next, prev, description: tagDescription } = schema.tag;
 
+  // Simple heuristic to determine if we should lazy highlight the code
+  // This is to avoid the performance issues when there are a lot of operations
+  const shouldLazyHighlight = operations.length > LAZY_OPERATION_LIST_THRESHOLD;
+
   // The summary property is preferable here as it is a short description of
   // the API, whereas the description property is typically longer and supports
   // commonmark formatting, making it ill-suited for use in the meta description
@@ -238,12 +247,20 @@ export const OperationList = ({
   const tagTitle = schema.tag.extensions?.["x-displayName"] ?? schema.tag.name;
   const helmetTitle = [tagTitle, title].filter(Boolean).join(" - ");
 
+  const downloadUrl =
+    typeof input === "string"
+      ? type === "url"
+        ? input
+        : joinUrl(path, version, input.split("/").pop())
+      : undefined;
+
   return (
     <div
       className="pt-(--padding-content-top)"
       data-pagefind-filter="section:openapi"
       data-pagefind-meta="section:openapi"
     >
+      <PagefindSearchMeta name="category">{title}</PagefindSearchMeta>
       <Helmet>
         {helmetTitle && <title>{helmetTitle}</title>}
         {metaDescription && (
@@ -256,7 +273,7 @@ export const OperationList = ({
           className="w-full"
           defaultOpen={options?.expandApiInformation}
         >
-          <div className="flex flex-col gap-y-4 sm:flex-row justify-around items-start sm:items-end">
+          <div className="flex flex-col gap-4 sm:flex-row justify-around items-start sm:items-end">
             <div className="flex flex-col flex-1 gap-2">
               <CategoryHeading>{title}</CategoryHeading>
               <Heading
@@ -276,25 +293,32 @@ export const OperationList = ({
               <Endpoint />
             </div>
             <div className="flex flex-col gap-4 sm:items-end">
-              {showVersions && (
-                <Select
-                  // biome-ignore lint/style/noNonNullAssertion: is guaranteed to be defined
-                  onValueChange={(version) => navigate(versions[version]!)}
-                  defaultValue={version}
-                  disabled={!hasMultipleVersions}
-                >
-                  <SelectTrigger className="w-[180px]">
-                    <SelectValue placeholder="Select version" />
-                  </SelectTrigger>
-                  <SelectContent>
-                    {Object.entries(versions).map(([version]) => (
-                      <SelectItem key={version} value={version}>
-                        {version}
-                      </SelectItem>
-                    ))}
-                  </SelectContent>
-                </Select>
-              )}
+              <div className="flex gap-2 items-center">
+                {showVersions && (
+                  <Select
+                    onValueChange={(version) =>
+                      // biome-ignore lint/style/noNonNullAssertion: is guaranteed to be defined
+                      navigate(versions[version]!.path)
+                    }
+                    defaultValue={version}
+                    disabled={!hasMultipleVersions}
+                  >
+                    <SelectTrigger className="w-[180px]" size="sm">
+                      <SelectValue placeholder="Select version" />
+                    </SelectTrigger>
+                    <SelectContent>
+                      {Object.entries(versions).map(([version, { label }]) => (
+                        <SelectItem key={version} value={version}>
+                          {label}
+                        </SelectItem>
+                      ))}
+                    </SelectContent>
+                  </Select>
+                )}
+                {options?.schemaDownload?.enabled && downloadUrl && (
+                  <DownloadSchemaButton downloadUrl={downloadUrl} />
+                )}
+              </div>
               {schema.description && (
                 <CollapsibleTrigger className="flex items-center gap-1 text-sm font-medium text-muted-foreground group">
                   <span>API information</span>
@@ -337,6 +361,7 @@ export const OperationList = ({
             <OperationListItem
               operationFragment={fragment}
               globalSelectedServer={globalSelectedServer}
+              shouldLazyHighlight={shouldLazyHighlight}
             />
             <hr className="my-10" />
           </div>

package/src/lib/plugins/openapi/OperationListItem.tsx

@@ -1,8 +1,9 @@
-import { VisuallyHidden } from "@radix-ui/react-visually-hidden";
 import { useState } from "react";
 import { Badge } from "zudoku/ui/Badge.js";
+import { Separator } from "zudoku/ui/Separator.js";
 import { Heading } from "../../components/Heading.js";
 import { Markdown } from "../../components/Markdown.js";
+import { PagefindSearchMeta } from "../../components/PagefindSearchMeta.js";
 import { cn } from "../../util/cn.js";
 import { groupBy } from "../../util/groupBy.js";
 import { renderIf } from "../../util/renderIf.js";
@@ -23,9 +24,11 @@ export type ParameterGroup = (typeof PARAM_GROUPS)[number];
 export const OperationListItem = ({
   operationFragment,
   globalSelectedServer,
+  shouldLazyHighlight,
 }: {
   operationFragment: FragmentType<typeof OperationsFragment>;
   globalSelectedServer?: string;
+  shouldLazyHighlight?: boolean;
 }) => {
   const operation = useFragment(OperationsFragment, operationFragment);
   const groupedParameters = groupBy(
@@ -118,19 +121,22 @@ export const OperationListItem = ({
                   []
                 ),
               )}
+            {renderIf(operation.requestBody?.content?.at(0)?.schema, () => (
+              <Separator className="my-4" />
+            ))}
             {renderIf(
               operation.requestBody?.content?.at(0)?.schema,
               (schema) => (
-                <div className="mt-4 flex flex-col gap-4">
+                <div className="flex flex-col gap-4">
                   <Heading
                     level={3}
                     className="capitalize flex items-center gap-2"
                     id={`${operation.slug}/request-body`}
                   >
                     {operation.summary && (
-                      <VisuallyHidden>
+                      <PagefindSearchMeta>
                         {operation.summary} &rsaquo;{" "}
-                      </VisuallyHidden>
+                      </PagefindSearchMeta>
                     )}
                     Request Body{" "}
                     {operation.requestBody?.required === false ? (
@@ -143,17 +149,14 @@ export const OperationListItem = ({
                 </div>
               ),
             )}
+            <Separator className="my-4" />
             {operation.responses.length > 0 && (
               <>
-                <Heading
-                  level={3}
-                  className="capitalize mt-8 pt-8 border-t"
-                  id={`${operation.slug}/responses`}
-                >
+                <Heading level={3} id={`${operation.slug}/responses`}>
                   {operation.summary && (
-                    <VisuallyHidden>
+                    <PagefindSearchMeta>
                       {operation.summary} &rsaquo;{" "}
-                    </VisuallyHidden>
+                    </PagefindSearchMeta>
                   )}
                   Responses
                 </Heading>
@@ -170,9 +173,9 @@ export const OperationListItem = ({
         {renderIf(!options?.disableSidecar && !isMCPEndpoint, () => (
           <Sidecar
             selectedResponse={selectedResponse}
-            onSelectResponse={setSelectedResponse}
             operation={operation}
             globalSelectedServer={globalSelectedServer}
+            shouldLazyHighlight={shouldLazyHighlight}
           />
         ))}
       </div>