zudoku 0.26.0 → 0.27.0

package/src/lib/components/SyntaxHighlight.tsx

@@ -41,6 +41,7 @@ type SyntaxHighlightProps = {
   copyable?: boolean;
   showLanguageIndicator?: boolean;
   language?: string;
+  title?: string;
 } & Omit<HighlightProps, "children" | "language">;
 
 const remapLang = {
@@ -50,6 +51,7 @@ const remapLang = {
 export const SyntaxHighlight = ({
   copyable = true,
   language = "plain",
+  title,
   ...props
 }: SyntaxHighlightProps) => {
   const { resolvedTheme } = useTheme();
@@ -70,12 +72,18 @@ export const SyntaxHighlight = ({
     <ClientOnly
       fallback={
         <div className="relative group">
+          {title && (
+            <div className="text-xs text-muted-foreground absolute top-2 font-mono border-b w-full pb-2 px-4 ">
+              {title}
+            </div>
+          )}
           <pre
             className={cn(
               "relative scrollbar overflow-x-auto",
               props.className,
               props.noBackground ? "!bg-transparent" : themeColorClasses,
               props.wrapLines && "whitespace-pre-wrap break-words",
+              title && "pt-10",
             )}
           >
             {props.code}
@@ -95,6 +103,11 @@ export const SyntaxHighlight = ({
       >
         {({ className, style, tokens, getLineProps, getTokenProps }) => (
           <div className="relative group">
+            {title && (
+              <div className="text-xs text-muted-foreground absolute top-2 font-mono border-b w-full pb-2 px-4 ">
+                {title}
+              </div>
+            )}
             <pre
               className={cn(
                 "relative scrollbar overflow-x-auto",
@@ -102,6 +115,7 @@ export const SyntaxHighlight = ({
                 props.className,
                 props.noBackground && "!bg-transparent",
                 props.wrapLines && "whitespace-pre-wrap break-words",
+                title && "pt-10",
               )}
               style={style}
             >

package/src/lib/components/ThemeSwitch.tsx

@@ -1,26 +1,25 @@
 import { MoonStarIcon, SunIcon } from "lucide-react";
 import { useTheme } from "next-themes";
 import { Button } from "zudoku/ui/Button.js";
-import { ClientOnly } from "./ClientOnly.js";
+import { cn } from "../util/cn.js";
 
 export const ThemeSwitch = () => {
   const { resolvedTheme, setTheme } = useTheme();
   const ThemeIcon = resolvedTheme === "dark" ? MoonStarIcon : SunIcon;
 
   return (
-    <ClientOnly>
-      <Button
-        variant="ghost"
-        aria-label={
-          resolvedTheme === "dark"
-            ? "Switch to light mode"
-            : "Switch to dark mode"
-        }
-        className="p-2.5 -m-2.5 rounded-full"
-        onClick={() => setTheme(resolvedTheme === "dark" ? "light" : "dark")}
-      >
-        <ThemeIcon size={18} />
-      </Button>
-    </ClientOnly>
+    <Button
+      variant="ghost"
+      size="icon"
+      aria-label={
+        resolvedTheme === "dark"
+          ? "Switch to light mode"
+          : "Switch to dark mode"
+      }
+      className={cn(resolvedTheme ? "opacity-100" : "opacity-0")}
+      onClick={() => setTheme(resolvedTheme === "dark" ? "light" : "dark")}
+    >
+      <ThemeIcon size={18} />
+    </Button>
   );
 };

package/src/lib/components/cache.ts

@@ -0,0 +1,15 @@
+import { useQueryClient } from "@tanstack/react-query";
+
+export const CACHE_KEYS = Object.freeze({
+  API_IDENTITIES: ["api-identities"],
+});
+
+export const useCache = () => {
+  const queryClient = useQueryClient();
+
+  return {
+    invalidateCache: async (key: keyof typeof CACHE_KEYS) => {
+      await queryClient.invalidateQueries({ queryKey: CACHE_KEYS[key] });
+    },
+  };
+};

package/src/lib/components/context/ViewportAnchorContext.tsx

@@ -63,6 +63,7 @@ export const ViewportAnchorProvider = ({
   const [activeAnchor, setActiveAnchor] = useState("");
   const observerRef = useRef<IntersectionObserver | null>(null);
   const registeredElements = useRef(new Set<HTMLElement>());
+  const pendingElements = useRef(new Set<HTMLElement>());
 
   useEffect(() => {
     observerRef.current = new IntersectionObserver(
@@ -81,6 +82,13 @@ export const ViewportAnchorProvider = ({
       },
     );
 
+    // Process any elements that tried to register before observer was ready
+    pendingElements.current.forEach((element) => {
+      registeredElements.current.add(element);
+      observerRef.current?.observe(element);
+    });
+    pendingElements.current.clear();
+
     return () => observerRef.current?.disconnect();
   }, []);
 
@@ -114,14 +122,22 @@ export const ViewportAnchorProvider = ({
   const observeFns = useMemo(() => {
     return {
       observe: (element: HTMLElement | null) => {
-        if (!element || !observerRef.current) return;
+        if (!element) return;
+
+        if (!observerRef.current) {
+          pendingElements.current.add(element);
+          return;
+        }
+
         registeredElements.current.add(element);
         observerRef.current.observe(element);
       },
       unobserve: (element: HTMLElement | null) => {
-        if (!element || !observerRef.current) return;
+        if (!element) return;
+
+        pendingElements.current.delete(element);
         registeredElements.current.delete(element);
-        observerRef.current.unobserve(element);
+        observerRef.current?.unobserve(element);
       },
     };
   }, []);
@@ -132,8 +148,6 @@ export const ViewportAnchorProvider = ({
   );
 
   return (
-    <ViewportAnchorContext.Provider value={value}>
-      {children}
-    </ViewportAnchorContext.Provider>
+    <ViewportAnchorContext value={value}>{children}</ViewportAnchorContext>
   );
 };

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

@@ -3,6 +3,7 @@ import { createContext, useContext } from "react";
 import { matchPath, useLocation } from "react-router";
 import { ZudokuContext } from "../../core/ZudokuContext.js";
 import { joinPath } from "../../util/joinPath.js";
+import { CACHE_KEYS } from "../cache.js";
 import { traverseSidebar } from "../navigation/utils.js";
 
 export const ZudokuReactContext = createContext<ZudokuContext | undefined>(
@@ -21,9 +22,10 @@ export const useZudoku = () => {
 
 export const useApiIdentities = () => {
   const { getApiIdentities } = useZudoku();
+
   return useQuery({
     queryFn: getApiIdentities,
-    queryKey: ["api-identities"],
+    queryKey: [CACHE_KEYS.API_IDENTITIES],
   });
 };
 

package/src/lib/components/index.ts

@@ -6,16 +6,21 @@ import { RouterError as RouterErrorImport } from "../errors/RouterError.js";
 import { ServerError as ServerErrorImport } from "../errors/ServerError.js";
 import { Button as ButtonImport } from "../ui/Button.js";
 import { Callout as CalloutImport } from "../ui/Callout.js";
-import { Spinner as SpinnerImport } from "./Spinner.js";
-import { Markdown as MarkdownImport } from "./Markdown.js";
 import {
   Bootstrap as BootstrapImport,
   BootstrapStatic as BootstrapStaticImport,
 } from "./Bootstrap.js";
 import { ClientOnly as ClientOnlyImport } from "./ClientOnly.js";
 import { Layout as LayoutImport } from "./Layout.js";
+import { Markdown as MarkdownImport } from "./Markdown.js";
+import { Spinner as SpinnerImport } from "./Spinner.js";
 import { Zudoku as ZudokuImport } from "./Zudoku.js";
+import {
+  CACHE_KEYS as CACHE_KEYS_IMPORT,
+  useCache as useCacheImport,
+} from "./cache.js";
 import { useZudoku as useZudokuImport } from "./context/ZudokuContext.js";
+
 export const useMDXComponents = /*@__PURE__*/ useMDXComponentsImport;
 export const Layout = /*@__PURE__*/ LayoutImport;
 export const RouterError = /*@__PURE__*/ RouterErrorImport;
@@ -27,6 +32,8 @@ export const Head = /*@__PURE__*/ Helmet;
 
 export const useZudoku = /*@__PURE__*/ useZudokuImport;
 export const useAuth = /*@__PURE__*/ useAuthImport;
+export const useCache = /*@__PURE__*/ useCacheImport;
+export const CACHE_KEYS = /*@__PURE__*/ CACHE_KEYS_IMPORT;
 export const Zudoku = /*@__PURE__*/ ZudokuImport;
 
 export const Callout = /*@__PURE__*/ CalloutImport;

package/src/lib/core/RouteGuard.tsx

@@ -0,0 +1,35 @@
+import { useEffect } from "react";
+import { matchPath, Outlet, useLocation } from "react-router";
+import { useAuth } from "../authentication/hook.js";
+import { useZudoku } from "../components/context/ZudokuContext.js";
+import { ZudokuError } from "../util/invariant.js";
+
+export const RouteGuard = () => {
+  const auth = useAuth();
+  const zudoku = useZudoku();
+  const location = useLocation();
+
+  const isProtected = zudoku.options.protectedRoutes?.some((path) =>
+    matchPath({ path, end: true }, location.pathname),
+  );
+
+  useEffect(() => {
+    if (isProtected && !auth.isAuthenticated) {
+      void zudoku.authentication?.signIn();
+    }
+  }, [isProtected, auth.isAuthenticated, zudoku.authentication]);
+
+  if (isProtected && !auth.isAuthenticated) {
+    return null;
+  }
+
+  if (isProtected && !auth.isAuthEnabled) {
+    throw new ZudokuError("Authentication is not enabled", {
+      title: "Authentication is not enabled",
+      developerHint:
+        "To use protectedRoutes you need authentication to be enabled",
+    });
+  }
+
+  return <Outlet />;
+};

package/src/lib/core/ZudokuContext.ts

@@ -65,6 +65,7 @@ export type ZudokuContextOptions = {
     components?: MdxComponentsType;
   };
   overrides?: ComponentsContextType;
+  protectedRoutes?: string[];
 };
 
 export class ZudokuContext {
@@ -74,16 +75,16 @@ export class ZudokuContext {
   public meta: ZudokuContextOptions["metadata"];
   public page: ZudokuContextOptions["page"];
   public authentication?: ZudokuContextOptions["authentication"];
-  private navigationPlugins: NavigationPlugin[];
+  private readonly navigationPlugins: NavigationPlugin[];
 
-  constructor(config: ZudokuContextOptions) {
-    this.plugins = config.plugins ?? [];
-    this.topNavigation = config.topNavigation ?? [];
-    this.sidebars = config.sidebars ?? {};
+  constructor(public readonly options: ZudokuContextOptions) {
+    this.plugins = options.plugins ?? [];
+    this.topNavigation = options.topNavigation ?? [];
+    this.sidebars = options.sidebars ?? {};
     this.navigationPlugins = this.plugins.filter(isNavigationPlugin);
-    this.authentication = config.authentication;
-    this.meta = config.metadata;
-    this.page = config.page;
+    this.authentication = options.authentication;
+    this.meta = options.metadata;
+    this.page = options.page;
   }
 
   initialize = async (): Promise<void> => {

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

@@ -0,0 +1,29 @@
+import { GraphQLJSON } from "graphql-type-json";
+import { GraphQLScalarType } from "graphql/index.js";
+
+export const CIRCULAR_REF = "$[Circular Reference]";
+const handleCircularRefs = (obj: any, visited = new WeakSet()): any => {
+  if (obj === CIRCULAR_REF) return CIRCULAR_REF;
+  if (obj === null || typeof obj !== "object") return obj;
+
+  if (visited.has(obj)) return CIRCULAR_REF;
+
+  visited.add(obj);
+
+  if (Array.isArray(obj)) {
+    return obj.map((item) => handleCircularRefs(item, visited));
+  }
+
+  const result: Record<string, any> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    result[key] = handleCircularRefs(value, visited);
+  }
+  return result;
+};
+export const GraphQLJSONSchema = new GraphQLScalarType({
+  ...GraphQLJSON,
+  name: "JSONSchema",
+  description: "OpenAPI schema scalar type that handles circular references",
+  serialize: (value: unknown) =>
+    GraphQLJSON.serialize(handleCircularRefs(value)),
+});

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

@@ -1,16 +1,15 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import SchemaBuilder from "@pothos/core";
 import {
-  slugifyWithCounter,
   type CountableSlugify,
+  slugifyWithCounter,
 } from "@sindresorhus/slugify";
 import { GraphQLJSON, GraphQLJSONObject } from "graphql-type-json";
 import { createYoga, type YogaServerOptions } from "graphql-yoga";
 import {
-  HttpMethods,
-  validate,
   type EncodingObject,
   type ExampleObject,
+  HttpMethods,
   type OpenAPIDocument,
   type OperationObject,
   type ParameterObject,
@@ -18,7 +17,9 @@ import {
   type SchemaObject,
   type ServerObject,
   type TagObject,
+  validate,
 } from "../parser/index.js";
+import { GraphQLJSONSchema } from "./circular.js";
 
 export type {
   EncodingObject,
@@ -45,10 +46,7 @@ export const createOperationSlug = (
 ) => {
   const summary =
     (operation.summary ?? "") +
-    (operation.operationId
-      ? "-" +
-        operation.operationId.slice(0, operation.summary ? Infinity : Infinity)
-      : "");
+    (operation.operationId ? "-" + operation.operationId : "");
 
   return slugify(
     (tag ? tag + "-" : "") +
@@ -65,6 +63,7 @@ const builder = new SchemaBuilder<{
   Scalars: {
     JSON: any;
     JSONObject: any;
+    JSONSchema: any;
   };
   Context: {
     schema: OpenAPIDocument;
@@ -74,6 +73,7 @@ const builder = new SchemaBuilder<{
 
 const JSONScalar = builder.addScalarType("JSON", GraphQLJSON);
 const JSONObjectScalar = builder.addScalarType("JSONObject", GraphQLJSONObject);
+const JSONSchemaScalar = builder.addScalarType("JSONSchema", GraphQLJSONSchema);
 
 const getAllTags = (schema: OpenAPIDocument): TagObject[] => {
   const tags = schema.tags ?? [];
@@ -238,7 +238,7 @@ const ParameterItem = builder
           })),
         nullable: true,
       }),
-      schema: t.expose("schema", { type: JSONScalar, nullable: true }),
+      schema: t.expose("schema", { type: JSONSchemaScalar, nullable: true }),
     }),
   });
 
@@ -252,7 +252,7 @@ const MediaTypeItem = builder
   .implement({
     fields: (t) => ({
       mediaType: t.exposeString("mediaType"),
-      schema: t.expose("schema", { type: JSONScalar, nullable: true }),
+      schema: t.expose("schema", { type: JSONSchemaScalar, nullable: true }),
       examples: t.expose("examples", { type: [ExampleItem], nullable: true }),
       encoding: t.expose("encoding", { type: [EncodingItem], nullable: true }),
     }),

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

@@ -1,10 +1,9 @@
 import type { JSONSchema4, JSONSchema6 } from "json-schema";
+import { CIRCULAR_REF } from "../../graphql/circular.js";
 import { resolveLocalRef } from "./resolveRef.js";
 
 export type JSONSchema = JSONSchema4 | JSONSchema6;
 
-export const CIRCULAR_REF = "$[Circular Reference]";
-
 type CustomResolver = (ref: string) => Promise<JSONSchema | undefined>;
 
 const cache = new Map<JSONSchema, JSONSchema>();

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

@@ -2,7 +2,7 @@ import { useMDXComponents } from "@mdx-js/react";
 import slugify from "@sindresorhus/slugify";
 import { Helmet } from "@zudoku/react-helmet-async";
 import { type PropsWithChildren, useEffect } from "react";
-import { Link } from "react-router";
+import { Link, useHref } from "react-router";
 import { CategoryHeading } from "../../components/CategoryHeading.js";
 import { Heading } from "../../components/Heading.js";
 import { ProseClasses } from "../../components/Markdown.js";
@@ -51,6 +51,13 @@ export const MdxPage = ({
   }
 >) => {
   const categoryTitle = useCurrentItem()?.categoryLabel;
+  let canonicalUrl = null;
+  const path = useHref("");
+  if (typeof window !== "undefined") {
+    const domain = window.location.origin;
+    canonicalUrl = `${domain}${path}`;
+  }
+
   const title = frontmatter.title;
   const category = frontmatter.category ?? categoryTitle;
   const hideToc = frontmatter.toc === false || defaultOptions?.toc === false;
@@ -87,6 +94,7 @@ export const MdxPage = ({
       <Helmet>
         <title>{pageTitle}</title>
         {excerpt && <meta name="description" content={excerpt} />}
+        {canonicalUrl && <link rel="canonical" href={canonicalUrl} />}
       </Helmet>
       <div
         className={cn(

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

@@ -95,7 +95,6 @@ export const OperationListItem = ({
               level={3}
               className="capitalize"
               id={`${operation.slug}/request-body`}
-              registerSidebarAnchor
             >
               Request Body
             </Heading>
@@ -108,7 +107,6 @@ export const OperationListItem = ({
               level={3}
               className="capitalize mt-8 pt-8 border-t"
               id={`${operation.slug}/responses`}
-              registerSidebarAnchor
             >
               Responses
             </Heading>

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

@@ -54,6 +54,7 @@ export const ParameterListItem = ({
           </Badge>
         )}
         {parameter.required && <Badge variant="outline">required</Badge>}
+        {parameter.style === "form" && <Badge variant="secondary">form</Badge>}
       </div>
       {parameter.description && (
         <Markdown

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

@@ -1,20 +1,24 @@
 import type { OperationListItemResult } from "./OperationList.js";
 import { PlaygroundDialog } from "./playground/PlaygroundDialog.js";
+import { Content } from "./SidecarExamples.js";
 
 export const PlaygroundDialogWrapper = ({
   server,
   servers,
   operation,
+  examples,
 }: {
   server: string;
   servers?: string[];
   operation: OperationListItemResult;
+  examples?: Content;
 }) => {
   const headers = operation.parameters
     ?.filter((p) => p.in === "header")
     .map((p) => ({
       name: p.name,
       defaultValue: p.examples?.find((x) => x.value)?.value ?? "",
+      defaultActive: false,
     }));
   const queryParams = operation.parameters
     ?.filter((p) => p.in === "query")
@@ -39,6 +43,7 @@ export const PlaygroundDialogWrapper = ({
       headers={headers}
       queryParams={queryParams}
       pathParams={pathParams}
+      examples={examples}
     />
   );
 };

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

@@ -99,7 +99,7 @@ export const Sidecar = ({
   selectedResponse?: string;
   onSelectResponse: (response: string) => void;
 }) => {
-  const { input, type } = useOasConfig();
+  const { input, type, options } = useOasConfig();
   const query = useCreateQuery(GetServerQuery, { input, type });
   const result = useSuspenseQuery(query);
 
@@ -109,7 +109,8 @@ export const Sidecar = ({
   const [, startTransition] = useTransition();
   const [selectedExample, setSelectedExample] = useState<unknown>();
 
-  const selectedLang = searchParams.get("lang") ?? "shell";
+  const selectedLang =
+    searchParams.get("lang") ?? options?.examplesDefaultLanguage ?? "shell";
 
   const requestBodyContent = operation.requestBody?.content;
 
@@ -198,6 +199,7 @@ export const Sidecar = ({
               server={result.data.schema.url}
               servers={result.data.schema.servers.map((server) => server.url)}
               operation={operation}
+              examples={requestBodyContent ?? undefined}
             />
           )}
         </SidecarBox.Head>

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

@@ -2,7 +2,6 @@ import { matchPath } from "react-router";
 import { type ZudokuPlugin } from "../../core/plugins.js";
 import { graphql } from "./graphql/index.js";
 
-import { useQuery } from "@tanstack/react-query";
 import { CirclePlayIcon, LogInIcon } from "lucide-react";
 import type { SidebarItem } from "../../../config/validators/SidebarSchema.js";
 import { useAuth } from "../../authentication/hook.js";
@@ -81,18 +80,15 @@ export const openApiPlugin = (config: OpenApiPluginOptions): ZudokuPlugin => {
         method,
         url,
         ...props
-      }: Partial<PlaygroundContentProps> & { requireAuth: boolean }) => {
+      }: Partial<PlaygroundContentProps> &
+        Pick<PlaygroundContentProps, "server"> & {
+          requireAuth: boolean;
+        }) => {
         const auth = useAuth();
-        // We don't have the GraphQL context here
-        const serverQuery = useQuery({
-          queryFn: () =>
-            client.fetch(GetCategoriesQuery, {
-              type: config.type,
-              input: config.input,
-            }),
-          enabled: !server,
-          queryKey: ["playground-server"],
-        });
+
+        if (!server) {
+          throw new Error("Server is required");
+        }
 
         if (requireAuth && !auth.isAuthenticated) {
           return (
@@ -110,9 +106,7 @@ export const openApiPlugin = (config: OpenApiPluginOptions): ZudokuPlugin => {
           <PlaygroundDialog
             url={url ?? "/"}
             method={method ?? "get"}
-            server={
-              server ?? serverQuery.data?.schema.url ?? "https://example.com"
-            }
+            server={server}
             {...props}
           >
             <Button className="gap-2 items-center" variant="outline">

package/src/lib/plugins/openapi/interfaces.ts

@@ -20,7 +20,14 @@ export type OasPluginConfig = {
   server?: string;
   navigationId?: string;
   skipPreload?: boolean;
-} & OasSource;
+} & OasPluginConfigOptions &
+  OasSource;
+
+export type OasPluginConfigOptions = {
+  options?: {
+    examplesDefaultLanguage?: string;
+  };
+};
 
 export type OasPluginContext = {
   server?: string;
@@ -28,4 +35,5 @@ export type OasPluginContext = {
   skipPreload?: boolean;
   version?: string;
   versions: Record<string, string>;
-} & ContextOasSource;
+} & ContextOasSource &
+  OasPluginConfigOptions;

package/src/lib/plugins/openapi/playground/ExamplesDropdown.tsx

@@ -0,0 +1,54 @@
+import { Button } from "zudoku/ui/Button.js";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuGroup,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "zudoku/ui/DropdownMenu.js";
+import { Content, Example } from "../SidecarExamples.js";
+
+const ExamplesDropdown = ({
+  examples,
+  onSelect,
+}: {
+  examples: Content;
+  onSelect: (example: Example) => void;
+}) => {
+  return (
+    <div className="flex flex-col gap-2 mt-2 items-end">
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <Button variant="outline">Use Example</Button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent className="w-56">
+          {examples.map((example) => {
+            return (
+              <div key={example.mediaType}>
+                <DropdownMenuLabel>{example.mediaType}</DropdownMenuLabel>
+                <DropdownMenuSeparator />
+                <DropdownMenuGroup>
+                  {example.examples?.map((example) => {
+                    return (
+                      <DropdownMenuItem
+                        key={example.name}
+                        onSelect={() => onSelect(example)}
+                        className="line-clamp-1"
+                      >
+                        {example.summary ?? example.name}
+                      </DropdownMenuItem>
+                    );
+                  })}
+                </DropdownMenuGroup>
+              </div>
+            );
+          })}
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </div>
+  );
+};
+
+export default ExamplesDropdown;