zudoku 0.0.0-f471fb8 → 0.0.0-f52e8af

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

@@ -86,10 +86,10 @@ export const Toc = ({ entries }: { entries: TocEntry[] }) => {
         On this page
       </div>
       <div className="relative ms-2 ps-4">
-        <div className="absolute inset-0 right-auto bg-border w-[2px]" />
+        <div className="absolute inset-0 end-auto bg-border w-[2px]" />
         <div
           className={cn(
-            "absolute -left-px -translate-y-1 h-6 w-[4px] rounded bg-primary",
+            "absolute -start-px -translate-y-1 h-6 w-[4px] rounded bg-primary",
             paintedOnce.current &&
               "ease-out [transition:top_150ms,opacity_325ms]",
           )}
@@ -104,10 +104,10 @@ export const Toc = ({ entries }: { entries: TocEntry[] }) => {
               isActive={item.id === activeAnchor}
               key={item.id}
               item={item}
-              className="pl-0"
+              className="ps-0"
             >
               {item.children && (
-                <ul className="list-none pl-4 pt-2 space-y-2">
+                <ul className="list-none ps-4 pt-2 space-y-2">
                   {item.children.map((child) => (
                     <TocItem
                       item={child}

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

@@ -0,0 +1,25 @@
+import * as React from "react";
+
+const ZudokuLogo = (props: React.SVGProps<SVGSVGElement>) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 132 100"
+    fill="none"
+    {...props}
+  >
+    <path
+      fill="currentColor"
+      fillRule="evenodd"
+      d="M80.092 2.963A4.66 4.66 0 0 1 84.449 0h34.049c6.325 0 10.835 6.135 8.948 12.172L116.653 46.71a4.688 4.688 0 0 1-4.474 3.29H75c-5.178 0-7.813 4.687-9.375 9.374-1.288 3.864-11.07 28.963-14.467 37.662A4.66 4.66 0 0 1 46.801 100H12.75c-6.324 0-10.834-6.134-8.947-12.171l10.793-34.54A4.688 4.688 0 0 1 19.071 50H56.25c5.178 0 7.813-4.687 9.375-9.375 1.288-3.864 11.07-28.962 14.467-37.662Z"
+      clipRule="evenodd"
+    />
+    <path
+      fill="currentColor"
+      d="M83.54 57.813a7.813 7.813 0 0 0-7.316 5.07L63.888 95.777c-.766 2.043.744 4.222 2.926 4.222h36.828c5.211 0 9.875-3.232 11.704-8.11l8.821-23.522c1.915-5.107-1.861-10.555-7.315-10.555H83.539ZM29.17 0a12.5 12.5 0 0 0-11.704 8.111l-8.82 23.521c-1.915 5.107 1.86 10.556 7.315 10.556h33.312a7.813 7.813 0 0 0 7.316-5.07L68.924 4.223C69.691 2.18 68.18 0 65.998 0H29.17Z"
+    />
+  </svg>
+);
+
+ZudokuLogo.displayName = "ZudokuLogo";
+
+export default ZudokuLogo;

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

@@ -0,0 +1,14 @@
+import type * as React from "react";
+
+const ZuploLogo = (props: React.SVGProps<SVGSVGElement>) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 76 66"
+    fill="none"
+    {...props}
+  >
+    <path d="M55.331 43.537H32.527l24.295-24.343a1.642 1.642 0 0 0-1.157-2.802H17.07V.239h42.336a16.407 16.407 0 0 1 8.81 2.438 16.471 16.471 0 0 1 6.147 6.775 16.037 16.037 0 0 1-3.167 18.201L55.331 43.535v.002Z" />
+    <path d="M20.695 21.888H43.5L19.204 46.23a1.643 1.643 0 0 0 1.158 2.802h38.595v16.153H16.621a16.406 16.406 0 0 1-8.81-2.438 16.471 16.471 0 0 1-6.147-6.775 16.038 16.038 0 0 1 3.167-18.201L20.695 21.89v-.002Z" />
+  </svg>
+);
+export default ZuploLogo;

package/src/lib/core/RouteGuard.tsx

@@ -1,4 +1,6 @@
 import { useQuery } from "@tanstack/react-query";
+import { Helmet } from "@zudoku/react-helmet-async";
+import { use } from "react";
 import { matchPath, Outlet, useLocation, useNavigate } from "react-router";
 import {
   Dialog,
@@ -8,21 +10,28 @@ import {
   DialogTitle,
 } from "zudoku/ui/Dialog.js";
 import { useAuth } from "../authentication/hook.js";
+import { BypassProtectedRoutesContext } from "../components/context/BypassProtectedRoutesContext.js";
 import { useZudoku } from "../components/context/ZudokuContext.js";
 import { ZudokuError } from "../util/invariant.js";
 import { useLatest } from "../util/useLatest.js";
 
+export const SEARCH_PROTECTED_SECTION = "protected";
+
 export const RouteGuard = () => {
   const auth = useAuth();
   const zudoku = useZudoku();
   const navigate = useNavigate();
   const location = useLocation();
   const latestPath = useLatest(location.pathname);
+  const shouldBypass = use(BypassProtectedRoutesContext);
+
   const { protectedRoutes = [] } = zudoku.options;
 
-  const isProtected = protectedRoutes.some((path) =>
-    matchPath({ path, end: true }, location.pathname),
-  );
+  const isProtected =
+    !shouldBypass &&
+    protectedRoutes.some((path) =>
+      matchPath({ path, end: true }, location.pathname),
+    );
 
   useQuery({
     queryKey: ["login-redirect"],
@@ -70,5 +79,18 @@ export const RouteGuard = () => {
     });
   }
 
-  return <Outlet />;
+  return (
+    <>
+      {shouldBypass && (
+        <Helmet>
+          <meta
+            name="pagefind"
+            data-pagefind-filter={`section:${SEARCH_PROTECTED_SECTION}`}
+            content="true"
+          />
+        </Helmet>
+      )}
+      <Outlet />
+    </>
+  );
 };

package/src/lib/core/ZudokuContext.ts

@@ -2,7 +2,12 @@ import type { QueryClient } from "@tanstack/react-query";
 import { createNanoEvents } from "nanoevents";
 import type { ReactNode } from "react";
 import type { Location } from "react-router";
-import type { TopNavigationItem } from "../../config/validators/common.js";
+import type { BundledTheme, HighlighterCore } from "shiki";
+import type { z } from "zod";
+import type {
+  FooterSchema,
+  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";
@@ -52,13 +57,15 @@ type Metadata = Partial<{
 }>;
 
 type Page = Partial<{
+  dir?: "ltr" | "rtl";
+  showPoweredBy?: boolean;
   pageTitle?: string;
   logo?: {
     src: {
       light: string;
       dark: string;
     };
-    width?: string;
+    width?: string | number;
     alt?: string;
   };
   banner?: {
@@ -66,6 +73,7 @@ type Page = Partial<{
     color?: "note" | "tip" | "info" | "caution" | "danger" | (string & {});
     dismissible?: boolean;
   };
+  footer?: z.infer<typeof FooterSchema>;
 }>;
 
 export type ZudokuContextOptions = {
@@ -83,6 +91,10 @@ export type ZudokuContextOptions = {
   };
   overrides?: ComponentsContextType;
   protectedRoutes?: string[];
+  syntaxHighlighting?: {
+    highlighter: HighlighterCore;
+    themes?: { light: BundledTheme; dark: BundledTheme };
+  };
 };
 
 export class ZudokuContext {

package/src/lib/errors/ErrorAlert.tsx

@@ -32,7 +32,7 @@ export function ErrorAlert({ error }: { error: unknown }) {
         <div>
           <SyntaxHighlight
             className="max-h-[400px] border mt-2"
-            language="jsstacktrace"
+            language="js"
             code={stringError}
           />
         </div>

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

@@ -1,43 +1,51 @@
 import { GraphQLJSON } from "graphql-type-json";
 import { GraphQLScalarType } from "graphql/index.js";
-import { RecordAny } from "../../util/traverse.js";
+import type { RecordAny } from "../../util/traverse.js";
 
 export const CIRCULAR_REF = "$[Circular Reference]";
 
+const OPENAPI_PROPS = new Set([
+  "properties",
+  "items",
+  "additionalProperties",
+  "allOf",
+  "anyOf",
+  "oneOf",
+]);
+
 const handleCircularRefs = (
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
   obj: any,
-  visited = new Map<string, string[]>(),
+  visited = new WeakSet(),
+  refs = new WeakMap(),
   path: string[] = [],
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
 ): any => {
-  if (obj === CIRCULAR_REF) return CIRCULAR_REF;
   if (obj === null || typeof obj !== "object") return obj;
 
-  const currentPath = path.join(".");
-
-  if (obj.type === "object" && obj.properties) {
-    const schemaKey = Object.keys(obj.properties).sort().join("-");
+  if (visited.has(obj)) {
+    const cached = refs.get(obj);
+    if (cached) return cached;
+    const circularProp = path.find((p) => !OPENAPI_PROPS.has(p)) || path[0];
 
-    if (visited.has(schemaKey)) {
-      const prevPaths = visited.get(schemaKey)!;
-      if (prevPaths.some((prev) => currentPath.startsWith(prev))) {
-        return CIRCULAR_REF;
-      }
-      visited.set(schemaKey, [...prevPaths, currentPath]);
-    } else {
-      visited.set(schemaKey, [currentPath]);
-    }
+    return [CIRCULAR_REF, circularProp].filter(Boolean).join(":");
   }
 
+  visited.add(obj);
+
   if (Array.isArray(obj)) {
-    return obj.map((item, index) =>
-      handleCircularRefs(item, visited, [...path, `${index}`]),
+    const result = obj.map((item, index) =>
+      handleCircularRefs(item, visited, refs, [...path, index.toString()]),
     );
+    refs.set(obj, result);
+    return result;
   }
 
   const result: RecordAny = {};
   for (const [key, value] of Object.entries(obj)) {
-    result[key] = handleCircularRefs(value, visited, [...path, key]);
+    result[key] = handleCircularRefs(value, visited, refs, [...path, key]);
   }
+  refs.set(obj, result);
   return result;
 };
 

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

@@ -1,3 +1,4 @@
+import { merge as mergeAllOf } from "allof-merge";
 import { GraphQLError } from "graphql/error/index.js";
 import { OpenAPIV3, type OpenAPIV3_1 } from "openapi-types";
 import { dereference, type JSONSchema } from "./dereference/index.js";
@@ -87,6 +88,9 @@ const parseSchemaInput = async (
 
 /**
  * Validates, dereferences and upgrades the OpenAPI schema (to v3.1) if necessary.
+ *
+ * This only happens for URL schemas (or in standalone mode).
+ * File schemas are pre-processed by the SchemaManager
  */
 export const validate = async (schemaInput: unknown) => {
   const schema = await parseSchemaInput(schemaInput);
@@ -96,6 +100,8 @@ export const validate = async (schemaInput: unknown) => {
   }
 
   const dereferenced = await dereference(schema);
+  const upgraded = upgradeSchema(dereferenced);
+  const merged = mergeAllOf(upgraded) as OpenAPIDocument;
 
-  return upgradeSchema(dereferenced);
+  return merged;
 };

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

@@ -10,11 +10,11 @@ import type { OpenAPIDocument } from "../index.js";
 
 export const upgradeSchema = (schema: RecordAny): OpenAPIDocument => {
   if (schema.openapi?.startsWith("3.0")) {
-    schema.openapi = "3.1.0";
+    schema.openapi = "3.1.1";
   }
 
   schema = traverse(schema, (sub) => {
-    if (sub.type !== "undefined" && sub.nullable === true) {
+    if (typeof sub.type !== "undefined" && sub.nullable === true) {
       sub.type = ["null", sub.type];
       delete sub.nullable;
     }
@@ -40,26 +40,17 @@ export const upgradeSchema = (schema: RecordAny): OpenAPIDocument => {
     return sub;
   });
 
-  schema = traverse(schema, (sub) => {
-    // may be null or undefined
-    if (sub.example) {
-      const isExampleObject =
-        typeof sub.example === "object" &&
-        (sub.example.summary !== undefined ||
-          sub.example.description !== undefined ||
-          sub.example.value !== undefined ||
-          sub.example.externalValue !== undefined);
-
-      const exampleValue = isExampleObject
-        ? sub.example
-        : { value: sub.example };
-
-      if (!sub.examples) {
-        sub.examples = { default: exampleValue };
+  schema = traverse(schema, (sub, path) => {
+    if (sub.example !== undefined) {
+      // Arrays in schemas
+      if (isSchemaPath(path ?? [])) {
+        sub.examples = [sub.example];
       } else {
+        // Objects everywhere else
         sub.examples = {
-          default: exampleValue,
-          ...sub.examples,
+          default: {
+            value: sub.example,
+          },
         };
       }
       delete sub.example;
@@ -67,17 +58,54 @@ export const upgradeSchema = (schema: RecordAny): OpenAPIDocument => {
     return sub;
   });
 
-  schema = traverse(schema, (sub) => {
-    if (sub.type === "object" && sub.properties !== undefined) {
-      for (const [, value] of Object.entries(sub.properties)) {
-        const v = (value ?? {}) as RecordAny;
-        if (v.type === "string" && v.format === "binary") {
-          v.contentEncoding = "application/octet-stream";
-          delete v.format;
+  // Multipart file uploads with a binary file
+  schema = traverse(schema, (schema, path) => {
+    if (schema.type === "object" && schema.properties !== undefined) {
+      // Check if this is a multipart request body schema
+      const parentPath = path?.slice(0, -1);
+      const isMultipart = parentPath?.some((segment, index) => {
+        return (
+          segment === "content" && path?.[index + 1] === "multipart/form-data"
+        );
+      });
+
+      if (isMultipart) {
+        // Types
+        const entries: [string, any][] = Object.entries(schema.properties);
+
+        for (const [, value] of entries) {
+          if (
+            typeof value === "object" &&
+            value.type === "string" &&
+            value.format === "binary"
+          ) {
+            value.contentMediaType = "application/octet-stream";
+            delete value.format;
+          }
         }
       }
     }
-    return sub;
+
+    return schema;
+  });
+
+  // Uploading a binary file in a POST request
+  schema = traverse(schema, (schema, path) => {
+    if (
+      path?.includes("content") &&
+      path.includes("application/octet-stream")
+    ) {
+      return {};
+    }
+
+    if (schema.type === "string" && schema.format === "binary") {
+      return {
+        type: "string",
+        contentMediaType: "application/octet-stream",
+      };
+    }
+
+    return schema;
   });
 
   schema = traverse(schema, (sub) => {
@@ -88,6 +116,7 @@ export const upgradeSchema = (schema: RecordAny): OpenAPIDocument => {
     return sub;
   });
 
+  // Uploading an image with base64 encoding
   schema = traverse(schema, (sub) => {
     if (sub.type === "string" && sub.format === "base64") {
       return {
@@ -99,5 +128,46 @@ export const upgradeSchema = (schema: RecordAny): OpenAPIDocument => {
     return sub;
   });
 
+  schema = traverse(schema, (schema, path) => {
+    if (schema.type === "string" && schema.format === "byte") {
+      const parentPath = path?.slice(0, -1);
+      const contentMediaType = parentPath?.find(
+        (_, index) => path?.[index - 1] === "content",
+      );
+
+      return {
+        type: "string",
+        contentEncoding: "base64",
+        contentMediaType,
+      };
+    }
+
+    return schema;
+  });
+
   return schema as OpenAPIDocument;
 };
+
+export function isSchemaPath(path: string[]): boolean {
+  const schemaLocations = [
+    ["components", "schemas"],
+    "properties",
+    "items",
+    "allOf",
+    "anyOf",
+    "oneOf",
+    "not",
+    "additionalProperties",
+  ];
+
+  return (
+    schemaLocations.some((location) => {
+      if (Array.isArray(location)) {
+        return location.every((segment, index) => path[index] === segment);
+      }
+      return path.includes(location);
+    }) ||
+    path.includes("schema") ||
+    path.some((segment) => segment.endsWith("Schema"))
+  );
+}

package/src/lib/plugins/api-catalog/Catalog.tsx

@@ -29,10 +29,7 @@ export const Catalog = ({
   const dataSet = activeCategory ? { "data-pagefind-ignore": "all" } : {};
 
   return (
-    <section
-      className="pt-[--padding-content-top] pb-[--padding-content-bottom]"
-      {...dataSet}
-    >
+    <section className="pt-[--padding-content-top]" {...dataSet}>
       <Helmet>
         <title>
           {categoryLabel ? `${categoryLabel} - ` : ""}

package/src/lib/plugins/markdown/MdxPage.tsx

@@ -96,7 +96,7 @@ export const MdxPage = ({
       <div
         className={cn(
           ProseClasses,
-          "max-w-full xl:w-full xl:max-w-3xl flex-1 flex-shrink pt-[--padding-content-top] pb-[--padding-content-bottom]",
+          "max-w-full xl:w-full xl:max-w-3xl flex-1 flex-shrink pt-[--padding-content-top]",
         )}
       >
         {(category || title) && (
@@ -114,10 +114,11 @@ export const MdxPage = ({
         />
         {!hidePager && (
           <>
-            <hr />
+            <hr className="my-10" />
             <Pagination
               prev={prev ? { to: prev.id, label: prev.label } : undefined}
               next={next ? { to: next.id, label: next.label } : undefined}
+              className="mb-4"
             />
           </>
         )}

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

@@ -49,7 +49,7 @@ export const CollapsibleCode = ({
         )}
       >
         {!open && isOverflowing && (
-          <div className=" absolute inset-0 bg-gradient-to-b from-transparent to-zinc-50/60 dark:to-zinc-950/90 z-10 group-hover:to-transparent"></div>
+          <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>
         )}
         <div ref={contentRef}>{children}</div>
         {!open && isOverflowing && (
@@ -59,7 +59,7 @@ export const CollapsibleCode = ({
           >
             <div>
               <Button variant="outline" className="hidden group-hover:flex">
-                <UnfoldVerticalIcon size={14} className="mr-1.5" />
+                <UnfoldVerticalIcon size={14} className="me-1.5" />
                 Click to expand
               </Button>
             </div>
@@ -68,12 +68,15 @@ export const CollapsibleCode = ({
       </CollapsibleContent>
       {isOverflowing && (
         <div
-          className={cn("flex justify-center w-full mb-2", !open && "hidden")}
+          className={cn(
+            "flex justify-center w-full py-2 bg-muted/50",
+            !open && "hidden",
+          )}
         >
           <CollapsibleTrigger asChild>
             <Button variant="outline" size="sm">
               Collapse
-              <FoldVerticalIcon size={14} className="ml-1.5" />
+              <FoldVerticalIcon size={14} className="ms-1.5" />
             </Button>
           </CollapsibleTrigger>
         </div>

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

@@ -90,7 +90,7 @@ export const ColorizedParam = ({
       {...{ [DATA_ATTR]: normalizedSlug }}
       className={cn(
         // This may not contain (inline-)flex or (inline-)block otherwise it breaks the browser's full text search
-        "relative rounded transition-all duration-100 rounded-lg",
+        "relative transition-all duration-100 rounded-lg",
         "border border-[--border-color] p-0.5 text-[--param-color] bg-[--background-color]",
         "data-[active=true]:border-[--param-color] data-[active=true]:shadow data-[active=true]:bottom-px",
         className,

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

@@ -2,7 +2,7 @@ import { type ResultOf } from "@graphql-typed-document-node/core";
 import { useQuery, useSuspenseQuery } from "@tanstack/react-query";
 import { Helmet } from "@zudoku/react-helmet-async";
 import { ChevronsDownUpIcon, ChevronsUpDownIcon } from "lucide-react";
-import { useNavigate } from "react-router";
+import { useNavigate, useParams } from "react-router";
 import {
   Collapsible,
   CollapsibleContent,
@@ -151,10 +151,11 @@ export const OperationList = ({
   untagged?: boolean;
 }) => {
   const { input, type, versions, version, options } = useOasConfig();
+  const { tag: tagFromParams } = useParams<"tag">();
   const query = useCreateQuery(OperationsForTagQuery, {
     input,
     type,
-    tag,
+    tag: tag ?? tagFromParams,
     untagged,
   });
   const result = useSuspenseQuery(query);
@@ -178,7 +179,18 @@ export const OperationList = ({
   // Prefetch for Playground
   useApiIdentities();
 
-  if (!schema.tag) return null;
+  if (!schema.tag) {
+    return (
+      <div className="flex flex-col h-full items-center justify-center text-center">
+        <div className="text-muted-foreground font-medium">
+          No operations found
+        </div>
+        <div className="mt-2 text-sm text-muted-foreground">
+          This API doesn't have any operations defined yet.
+        </div>
+      </div>
+    );
+  }
 
   const { operations, next, prev, description: tagDescription } = schema.tag;
 
@@ -224,7 +236,7 @@ export const OperationList = ({
       <div className="mb-8">
         <Collapsible className="w-full">
           <div className="flex flex-col gap-y-4 sm:flex-row justify-around items-start sm:items-end">
-            <div className="flex-1">
+            <div className="flex flex-col flex-1 gap-2">
               <CategoryHeading>{title}</CategoryHeading>
               <Heading
                 level={1}
@@ -234,12 +246,13 @@ export const OperationList = ({
               >
                 {schema.tag.name ?? "Other endpoints"}
                 {showVersions && (
-                  <span className="text-xl text-muted-foreground ml-1.5">
+                  <span className="text-xl text-muted-foreground ms-1.5">
                     {" "}
                     ({version})
                   </span>
                 )}
               </Heading>
+              <Endpoint />
             </div>
             <div className="flex flex-col gap-4 sm:items-end">
               {showVersions && (
@@ -262,7 +275,7 @@ export const OperationList = ({
               )}
               {schema.description && (
                 <CollapsibleTrigger className="flex items-center gap-1 text-sm font-medium text-muted-foreground group">
-                  <span>Schema description</span>
+                  <span>API information</span>
 
                   <ChevronsUpDownIcon
                     className="group-data-[state=open]:hidden translate-y-px"
@@ -304,20 +317,18 @@ export const OperationList = ({
         )}
       </div>
       <hr />
-      <Pagination {...paginationProps} />
-      <div className="my-4 flex items-center justify-end gap-4">
-        <Endpoint />
-      </div>
       {/* px, -mx is so that `content-visibility` doesn't cut off overflown heading anchor links '#' */}
-      <div className="px-6 -mx-6 [content-visibility:auto]">
+      <div className="px-6 mt-6 -mx-6 [content-visibility:auto]">
         {operations.map((fragment) => (
-          <OperationListItem
-            serverUrl={selectedServer}
-            key={fragment.slug}
-            operationFragment={fragment}
-          />
+          <div key={fragment.slug}>
+            <OperationListItem
+              serverUrl={selectedServer}
+              operationFragment={fragment}
+            />
+            <hr className="my-10" />
+          </div>
         ))}
-        <Pagination {...paginationProps} />
+        <Pagination className="mb-4" {...paginationProps} />
       </div>
     </div>
   );