fumadocs-openapi 10.9.1 → 10.10.1

package/dist/types.d.ts

@@ -1,12 +1,10 @@
-import { MediaAdapter } from "./requests/media/adapter.js";
 import { InlineCodeUsageGenerator } from "./requests/generators/index.js";
 import { boundary_d_exports } from "./ui/client/boundary.js";
-import { OpenAPIV3, OpenAPIV3_2 } from "./_openapi/types.js";
+import { OpenAPIV3_2 } from "./_openapi/types.js";
 import { CreateAPIPageOptions } from "./ui/base.js";
 import { OpenAPIOptions } from "./server/index.js";
 import { NoReference } from "./utils/schema/index.js";
 import { DereferencedDocument } from "./utils/document/dereference.js";
-import { HTMLAttributes, ReactNode } from "react";
 
 //#region src/types.d.ts
 type Document = OpenAPIV3_2.Document;
@@ -17,14 +15,8 @@ type ReferenceObject = OpenAPIV3_2.ReferenceObject;
 type PathItemObject = OpenAPIV3_2.PathItemObject;
 type TagObject = OpenAPIV3_2.TagObject;
 type ServerObject = OpenAPIV3_2.ServerObject;
-type CallbackObject = OpenAPIV3_2.CallbackObject;
-type ServerVariableObject = OpenAPIV3.ServerVariableObject;
 type ResponseObject = OpenAPIV3_2.ResponseObject;
-type OAuth2SecurityScheme = OpenAPIV3_2.OAuth2SecurityScheme;
 type HttpMethods = OpenAPIV3_2.HttpMethods;
-type ExampleObject = OpenAPIV3_2.ExampleObject;
-type MediaTypeObject = OpenAPIV3_2.MediaTypeObject;
-type RequestBodyObject = OpenAPIV3_2.RequestBodyObject;
 type MethodInformation = NoReference<OperationObject> & {
   method: HttpMethods;
   'x-codeSamples'?: InlineCodeUsageGenerator[];
@@ -32,19 +24,14 @@ type MethodInformation = NoReference<OperationObject> & {
   'x-exclusiveCodeSample'?: string;
 };
 type RequireKeys<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
-interface RenderContext extends Pick<OpenAPIOptions, 'proxyUrl'>, Omit<RequireKeys<CreateAPIPageOptions, 'renderMarkdown' | 'generateTypeScriptDefinitions'>, 'renderCodeBlock' | 'renderHeading' | 'generateTypeScriptSchema'> {
+interface RenderContext extends Pick<OpenAPIOptions, 'proxyUrl'>, Omit<RequireKeys<CreateAPIPageOptions, 'renderMarkdown' | 'generateTypeScriptDefinitions' | 'renderCodeBlock' | 'mediaAdapters' | 'codeUsages'>, 'renderHeading' | 'generateTypeScriptSchema'> {
   /**
    * dereferenced schema
    */
   schema: DereferencedDocument;
   clientBoundary: typeof boundary_d_exports;
-  mediaAdapters: Record<string, MediaAdapter>;
-  renderHeading: (depth: number, text: string | ReactNode, props?: HTMLAttributes<HTMLHeadingElement> & {
-    id?: string;
-  }) => ReactNode;
-  renderCodeBlock: (lang: string, code: string) => ReactNode;
 }
 type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
 type Awaitable<T> = T | Promise<T>;
 //#endregion
-export { Awaitable, CallbackObject, DistributiveOmit, Document, ExampleObject, HttpMethods, MediaTypeObject, MethodInformation, OAuth2SecurityScheme, OperationObject, ParameterObject, PathItemObject, ReferenceObject, RenderContext, RequestBodyObject, ResponseObject, SecuritySchemeObject, ServerObject, ServerVariableObject, TagObject };
+export { Awaitable, DistributiveOmit, Document, HttpMethods, MethodInformation, OperationObject, ParameterObject, PathItemObject, ReferenceObject, RenderContext, ResponseObject, SecuritySchemeObject, ServerObject, TagObject };

package/dist/ui/base.d.ts

@@ -147,10 +147,11 @@ interface CreateAPIPageOptions {
       children: ReactNode;
     }) => ReactNode;
     /**
-     * replace the server-side renderer
+     * replace the renderer
      */
     render?: (props: APIPlaygroundProps) => ReactNode;
   };
+  /** @deprecated no longer used */
   renderHeading?: (props: HTMLAttributes<HTMLHeadingElement>, depth: number) => ReactNode;
   renderCodeBlock?: (props: {
     lang: string;

package/dist/ui/base.js

@@ -1,14 +1,14 @@
 import { parseSecurities } from "../utils/schema/index.js";
 import { defaultAdapters } from "../requests/media/adapter.js";
+import { createCodeUsageGeneratorRegistry } from "../requests/generators/index.js";
+import { registerDefault } from "../requests/generators/all.js";
 import { ClientCodeBlockProvider } from "./components/codeblock.js";
 import { encodeInternalRef } from "../utils/schema/ref.js";
 import { APIPage } from "./api-page.js";
 import { pickSchema } from "../utils/schema/pick.js";
 import { PlaygroundAuthProvider } from "./client/boundary.lazy.js";
-import Slugger from "github-slugger";
 import * as JsxRuntime from "react/jsx-runtime";
 import { jsx } from "react/jsx-runtime";
-import { Heading } from "fumadocs-ui/components/heading";
 import { createRehypeCode } from "fumadocs-core/mdx-plugins/rehype-code.core";
 import { remarkGfm } from "fumadocs-core/mdx-plugins/remark-gfm";
 import defaultMdxComponents from "fumadocs-ui/mdx";
@@ -62,7 +62,6 @@ function createAPIPage(server, options) {
 		let processed;
 		if (typeof document === "string") processed = await server.getSchema(document);
 		else processed = document;
-		const slugger = new Slugger();
 		const { ApiProvider, PlaygroundClient, SchemaUI, ServerProvider, UsageTab, UsageTabsSelector } = await import("./client/boundary.lazy.js");
 		const ctx = {
 			schema: processed,
@@ -76,6 +75,7 @@ function createAPIPage(server, options) {
 				UsageTabsSelector
 			},
 			...options,
+			codeUsages: options.codeUsages ?? registerDefault(createCodeUsageGeneratorRegistry()),
 			mediaAdapters: {
 				...defaultAdapters,
 				...options.mediaAdapters
@@ -85,21 +85,6 @@ function createAPIPage(server, options) {
 				provider: options.playground?.provider ?? renderPlaygroundProviderDefault,
 				render: options.playground?.render ?? renderPlaygroundDefault
 			},
-			renderHeading(depth, text, props) {
-				const id = typeof text === "string" ? slugger.slug(text) : props?.id;
-				if (!id) throw new Error("missing 'id' for non-string children");
-				if (options.renderHeading) return options.renderHeading({
-					id,
-					children: text,
-					...props
-				}, depth);
-				return /* @__PURE__ */ jsx(Heading, {
-					id,
-					as: `h${depth}`,
-					...props,
-					children: text
-				}, id);
-			},
 			generateTypeScriptDefinitions: options.generateTypeScriptDefinitions ?? ((schema, ctx) => {
 				if (options.generateTypeScriptSchema && ctx._internal_legacy) {
 					const { statusCode, contentType } = ctx._internal_legacy;
@@ -122,7 +107,7 @@ function createAPIPage(server, options) {
 				processor ??= createMarkdownProcessor();
 				return (await processor.process({ value: text })).result;
 			},
-			async renderCodeBlock(lang, code) {
+			async renderCodeBlock({ lang, code }) {
 				if (options.renderCodeBlock) return options.renderCodeBlock({
 					lang,
 					code

package/dist/ui/client/index.d.ts

@@ -2,12 +2,24 @@ import { MediaAdapter } from "../../requests/media/adapter.js";
 import { PlaygroundClientOptions } from "../../playground/client.js";
 import { CodeUsageGeneratorRegistry } from "../../requests/generators/index.js";
 import { ExampleRequestItem } from "../operation/get-example-requests.js";
-import { FC } from "react";
+import { ComponentProps, FC } from "react";
 
 //#region src/ui/client/index.d.ts
 interface APIPageClientOptions {
   playground?: PlaygroundClientOptions;
-  operation?: OperationClientOptions;
+  operation?: {
+    APIExampleSelector?: FC<{
+      items: ExampleRequestItem[];
+      value: string | undefined;
+      onValueChange: (id: string) => void;
+    }>;
+  };
+  components?: {
+    Heading?: FC<ComponentProps<'h1'> & {
+      id: string;
+      depth: number;
+    }>;
+  };
   /**
    * Set a prefix for `localStorage` keys.
    *
@@ -25,13 +37,6 @@ interface APIPageClientOptions {
    */
   codeUsages?: CodeUsageGeneratorRegistry;
 }
-interface OperationClientOptions {
-  APIExampleSelector?: FC<{
-    items: ExampleRequestItem[];
-    value: string | undefined;
-    onValueChange: (id: string) => void;
-  }>;
-}
 declare function defineClientConfig(options?: APIPageClientOptions): APIPageClientOptions;
 //#endregion
-export { APIPageClientOptions, OperationClientOptions, defineClientConfig };
+export { APIPageClientOptions, defineClientConfig };

package/dist/ui/components/accordion.js

@@ -1,27 +1,52 @@
 "use client";
 import { cn } from "../../utils/cn.js";
+import { anchorIdStartsWith } from "../../utils/auto-anchor.js";
+import { AnchorSection, useAnchorId } from "../../utils/auto-anchor.client.js";
+import { createContext, use, useEffect, useMemo, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { ChevronRight } from "lucide-react";
 import * as Primitive from "@radix-ui/react-accordion";
 //#region src/ui/components/accordion.tsx
-function Accordions(props) {
-	return /* @__PURE__ */ jsx(Primitive.Root, {
-		...props,
-		className: cn("divide-y divide-fd-border", props.className)
+const Context = createContext(null);
+function Accordions({ type, defaultValue, ...props }) {
+	const [value, setValue] = useState(() => type === "multiple" ? defaultValue ?? [] : defaultValue ?? "");
+	return /* @__PURE__ */ jsx(Context, {
+		value: useMemo(() => ({
+			type,
+			setValue
+		}), [type]),
+		children: /* @__PURE__ */ jsx(Primitive.Root, {
+			type,
+			value,
+			onValueChange: setValue,
+			...props
+		})
 	});
 }
-function AccordionItem(props) {
-	return /* @__PURE__ */ jsx(Primitive.Item, {
-		...props,
-		className: cn("scroll-m-20", props.className),
-		children: props.children
+function AccordionItem({ value, className, anchorSegments, ...props }) {
+	const ctx = use(Context);
+	const id = useAnchorId(anchorSegments ?? false);
+	useEffect(() => {
+		if (id && anchorIdStartsWith(window.location.hash.slice(1), id)) ctx.setValue(ctx.type === "single" ? value : [value]);
+	}, [
+		value,
+		id,
+		ctx
+	]);
+	const content = /* @__PURE__ */ jsx(Primitive.Item, {
+		value,
+		className: cn("scroll-m-20 border-b last:border-b-0", className),
+		...props
 	});
+	return anchorSegments ? /* @__PURE__ */ jsx(AnchorSection, {
+		segments: anchorSegments,
+		children: content
+	}) : content;
 }
 function AccordionContent(props) {
 	return /* @__PURE__ */ jsx(Primitive.Content, {
 		...props,
-		className: cn("overflow-hidden data-[state=closed]:animate-fd-accordion-up data-[state=open]:animate-fd-accordion-down", props.className),
-		children: props.children
+		className: cn("overflow-hidden data-[state=closed]:animate-fd-accordion-up data-[state=open]:animate-fd-accordion-down", props.className)
 	});
 }
 function AccordionHeader(props) {

package/dist/ui/components/dialog.js

@@ -1,7 +1,6 @@
 "use client";
 import { useTranslations } from "../client/i18n.js";
 import { cn } from "../../utils/cn.js";
-import * as React from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { X } from "lucide-react";
 import { buttonVariants } from "fumadocs-ui/components/ui/button";
@@ -10,13 +9,14 @@ import * as DialogPrimitive from "@radix-ui/react-dialog";
 const Dialog = DialogPrimitive.Root;
 const DialogTrigger = DialogPrimitive.Trigger;
 const DialogPortal = DialogPrimitive.Portal;
-const DialogOverlay = React.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(DialogPrimitive.Overlay, {
-	ref,
-	className: cn("fixed inset-0 z-50 bg-black/30 backdrop-blur-sm data-[state=open]:animate-fd-fade-in data-[state=closed]:animate-fd-fade-out", className),
-	...props
-}));
-DialogOverlay.displayName = DialogPrimitive.Overlay.displayName;
-const DialogContent = React.forwardRef(({ className, children, ...props }, ref) => {
+function DialogOverlay({ className, ref, ...props }) {
+	return /* @__PURE__ */ jsx(DialogPrimitive.Overlay, {
+		ref,
+		className: cn("fixed inset-0 z-50 bg-black/30 backdrop-blur-sm data-[state=open]:animate-fd-fade-in data-[state=closed]:animate-fd-fade-out", className),
+		...props
+	});
+}
+function DialogContent({ className, children, ref, ...props }) {
 	const t = useTranslations();
 	return /* @__PURE__ */ jsxs(DialogPortal, { children: [/* @__PURE__ */ jsx(DialogOverlay, {}), /* @__PURE__ */ jsxs(DialogPrimitive.Content, {
 		ref,
@@ -31,29 +31,26 @@ const DialogContent = React.forwardRef(({ className, children, ...props }, ref)
 			children: /* @__PURE__ */ jsx(X, {})
 		})]
 	})] });
-});
-DialogContent.displayName = DialogPrimitive.Content.displayName;
-const DialogHeader = ({ className, ...props }) => /* @__PURE__ */ jsx("div", {
-	className: cn("flex flex-col gap-1.5 text-center sm:text-start", className),
-	...props
-});
-DialogHeader.displayName = "DialogHeader";
-const DialogFooter = ({ className, ...props }) => /* @__PURE__ */ jsx("div", {
-	className: cn("flex flex-col-reverse sm:flex-row sm:justify-end sm:gap-2", className),
-	...props
-});
-DialogFooter.displayName = "DialogFooter";
-const DialogTitle = React.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(DialogPrimitive.Title, {
-	ref,
-	className: cn("text-lg font-semibold leading-none tracking-tight", className),
-	...props
-}));
-DialogTitle.displayName = DialogPrimitive.Title.displayName;
-const DialogDescription = React.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(DialogPrimitive.Description, {
-	ref,
-	className: cn("text-sm text-fd-muted-foreground", className),
-	...props
-}));
-DialogDescription.displayName = DialogPrimitive.Description.displayName;
+}
+function DialogHeader({ className, ...props }) {
+	return /* @__PURE__ */ jsx("div", {
+		className: cn("flex flex-col gap-1.5 text-center sm:text-start", className),
+		...props
+	});
+}
+function DialogTitle({ className, ref, ...props }) {
+	return /* @__PURE__ */ jsx(DialogPrimitive.Title, {
+		ref,
+		className: cn("text-lg font-semibold leading-none tracking-tight", className),
+		...props
+	});
+}
+function DialogDescription({ className, ref, ...props }) {
+	return /* @__PURE__ */ jsx(DialogPrimitive.Description, {
+		ref,
+		className: cn("text-sm text-fd-muted-foreground", className),
+		...props
+	});
+}
 //#endregion
 export { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle, DialogTrigger };

package/dist/ui/components/heading.js

@@ -0,0 +1,22 @@
+"use client";
+import { useApiContext } from "../contexts/api.js";
+import { useAnchorId } from "../../utils/auto-anchor.client.js";
+import { jsx } from "react/jsx-runtime";
+import { Heading } from "fumadocs-ui/components/heading";
+//#region src/ui/components/heading.tsx
+function Heading$1({ id: _id, depth, ...props }) {
+	const id = useAnchorId([_id]);
+	const Component = useApiContext().client.components?.Heading;
+	if (Component) return /* @__PURE__ */ jsx(Component, {
+		id,
+		depth,
+		...props
+	});
+	return /* @__PURE__ */ jsx(Heading, {
+		id,
+		as: `h${depth}`,
+		...props
+	});
+}
+//#endregion
+export { Heading$1 as Heading };

package/dist/ui/components/select-tab.js

@@ -1,7 +1,9 @@
 "use client";
 import { cn } from "../../utils/cn.js";
 import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "./select.js";
-import { createContext, use, useMemo, useState } from "react";
+import { anchorIdStartsWith } from "../../utils/auto-anchor.js";
+import { AnchorSection, useAnchorId } from "../../utils/auto-anchor.client.js";
+import { createContext, use, useEffect, useMemo, useState } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 //#region src/ui/components/select-tab.tsx
 const Context = createContext(null);
@@ -15,14 +17,24 @@ function SelectTabs({ defaultValue, children }) {
 		children
 	});
 }
-function SelectTab({ value, ...props }) {
-	if (value !== use(Context)?.value) return;
-	return /* @__PURE__ */ jsx("div", {
-		...props,
-		children: props.children
-	});
+function SelectTab({ value, anchorSegments, ...props }) {
+	const { value: currentValue, setValue } = use(Context);
+	const id = useAnchorId(anchorSegments ?? false);
+	useEffect(() => {
+		if (id && anchorIdStartsWith(window.location.hash.slice(1), id)) setValue(value);
+	}, [
+		id,
+		value,
+		setValue
+	]);
+	if (value !== currentValue) return;
+	const content = /* @__PURE__ */ jsx("div", { ...props });
+	return anchorSegments ? /* @__PURE__ */ jsx(AnchorSection, {
+		segments: anchorSegments,
+		children: content
+	}) : content;
 }
-function SelectTabTrigger({ items, className, ...props }) {
+function SelectTabTrigger({ items, className, placeholder, ...props }) {
 	const { value, setValue } = use(Context);
 	return /* @__PURE__ */ jsxs(Select, {
 		value: value ?? "",
@@ -30,7 +42,10 @@ function SelectTabTrigger({ items, className, ...props }) {
 		children: [/* @__PURE__ */ jsx(SelectTrigger, {
 			className: cn("not-prose w-fit min-w-0 *:min-w-0", className),
 			...props,
-			children: /* @__PURE__ */ jsx(SelectValue, { children: value && items.find((item) => item.value === value)?.label })
+			children: /* @__PURE__ */ jsx(SelectValue, {
+				placeholder,
+				children: value && items.find((item) => item.value === value)?.label
+			})
 		}), /* @__PURE__ */ jsx(SelectContent, { children: items.map(({ label, value }) => /* @__PURE__ */ jsx(SelectItem, {
 			value,
 			children: label

package/dist/ui/contexts/api.js

@@ -21,16 +21,10 @@ function useServerContext() {
 function ApiProvider({ children, shikiOptions, client, schemes }) {
 	return /* @__PURE__ */ jsx(ApiContext, {
 		value: useMemo(() => {
-			let codeUsages;
-			if (client.codeUsages) codeUsages = createCodeUsageGeneratorRegistry(client.codeUsages);
-			else {
-				codeUsages = createCodeUsageGeneratorRegistry();
-				registerDefault(codeUsages);
-			}
 			return {
 				shikiOptions,
 				client,
-				codeUsages,
+				codeUsages: client.codeUsages ?? registerDefault(createCodeUsageGeneratorRegistry()),
 				schemes,
 				mediaAdapters: {
 					...defaultAdapters,

package/dist/ui/create-client.d.ts

@@ -1,3 +1,4 @@
+import { APIPageClientOptions } from "./client/index.js";
 import { ApiPageProps } from "./api-page.js";
 import { CreateAPIPageOptions } from "./base.js";
 import { Document } from "../types.js";
@@ -11,7 +12,7 @@ interface ClientApiPagePayload {
   bundled: Document;
   proxyUrl?: string;
 }
-type CreateClientAPIPageOptions = Omit<Partial<CreateAPIPageOptions>, 'generateTypeScriptSchema'>;
+type CreateClientAPIPageOptions = Partial<Omit<CreateAPIPageOptions, 'generateTypeScriptSchema' | 'client'> & Omit<APIPageClientOptions, 'mediaAdapters' | 'codeUsages'>>;
 /**
  * Create `<APIPage />` for non-RSC environment, note that this may be unstable, and doesn't support the full set of features.
  */

package/dist/ui/create-client.js

@@ -1,15 +1,16 @@
+"use client";
 import { parseSecurities } from "../utils/schema/index.js";
 import { defaultAdapters } from "../requests/media/adapter.js";
+import { createCodeUsageGeneratorRegistry } from "../requests/generators/index.js";
+import { registerDefault } from "../requests/generators/all.js";
 import { ClientCodeBlock, ClientCodeBlockProvider } from "./components/codeblock.js";
 import { AuthProvider } from "../playground/auth.js";
 import { dereferenceDocument } from "../utils/document/dereference.js";
 import { APIPage } from "./api-page.js";
 import { boundary_exports } from "./client/boundary.js";
-import { slug } from "github-slugger";
 import { Children, useMemo } from "react";
 import * as JsxRuntime from "react/jsx-runtime";
 import { jsx } from "react/jsx-runtime";
-import { Heading } from "fumadocs-ui/components/heading";
 import { remarkGfm } from "fumadocs-core/mdx-plugins/remark-gfm";
 import defaultMdxComponents from "fumadocs-ui/mdx";
 import { remark } from "remark";
@@ -80,7 +81,9 @@ function createClientAPIPage({ shiki = defaultShikiFactory, shikiOptions = { the
 			shikiOptions,
 			generateTypeScriptDefinitions,
 			clientBoundary: boundary_exports,
+			client: options,
 			...options,
+			codeUsages: options.codeUsages ?? registerDefault(createCodeUsageGeneratorRegistry()),
 			mediaAdapters: {
 				...defaultAdapters,
 				...options.mediaAdapters
@@ -90,35 +93,14 @@ function createClientAPIPage({ shiki = defaultShikiFactory, shikiOptions = { the
 				provider: options.playground?.provider ?? renderPlaygroundProviderDefault,
 				render: options.playground?.render ?? renderPlaygroundDefault
 			},
-			renderHeading(depth, text, props) {
-				const id = typeof text === "string" ? slug(text) : props?.id;
-				if (!id) throw new Error("missing 'id' for non-string children");
-				if (options.renderHeading) return options.renderHeading({
-					id,
-					children: text,
-					...props
-				}, depth);
-				return /* @__PURE__ */ jsx(Heading, {
-					id,
-					as: `h${depth}`,
-					...props,
-					children: text
-				}, id);
-			},
 			renderMarkdown(text) {
 				if (options.renderMarkdown) return options.renderMarkdown(text);
 				processor ??= createMarkdownProcessor();
 				return processor.processSync({ value: text }).result;
 			},
-			renderCodeBlock(lang, code) {
-				if (options.renderCodeBlock) return options.renderCodeBlock({
-					lang,
-					code
-				});
-				return /* @__PURE__ */ jsx(ClientCodeBlock, {
-					lang,
-					code
-				});
+			renderCodeBlock(props) {
+				if (options.renderCodeBlock) return options.renderCodeBlock(props);
+				return /* @__PURE__ */ jsx(ClientCodeBlock, { ...props });
 			}
 		}), [payload.proxyUrl, processed]);
 		return /* @__PURE__ */ jsx(ClientCodeBlockProvider, {

package/dist/ui/operation/client.js

@@ -56,7 +56,7 @@ function CopyTypeScriptPanel({ name, code, className }) {
 	const t = useTranslations();
 	const useTypeText = t.useTypeInTypeScript.replace("{name}", name);
 	return /* @__PURE__ */ jsxs("div", {
-		className: cn("flex items-start justify-between gap-2 bg-fd-card text-fd-card-foreground border rounded-xl p-3 not-prose mb-4 last:mb-0", className),
+		className: cn("flex items-start justify-between gap-2 bg-fd-card text-fd-card-foreground border rounded-xl p-3 not-prose", className),
 		children: [/* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsx("p", {
 			className: "font-medium text-sm mb-2",
 			children: t.typeScriptDefinitions