@fumadocs/api-docs 0.0.1

package/dist/components/schema/client.js

@@ -0,0 +1,415 @@
+"use client";
+import { useAnchorId } from "../../auto-anchor/client.js";
+import { cn } from "../../utils/cn.js";
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "../select.js";
+import { mergeRefs } from "../../utils/merge-refs.js";
+import { Fragment, Suspense, createContext, use, useCallback, useDeferredValue, useEffect, useMemo, useRef, useState } from "react";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
+import { CheckIcon, FilterIcon, LinkIcon } from "lucide-react";
+import { buttonVariants } from "fumadocs-ui/components/ui/button";
+import { cva } from "class-variance-authority";
+import { useTranslations } from "@fuma-translate/react";
+import { Popover, PopoverContent, PopoverTrigger } from "fumadocs-ui/components/ui/popover";
+import { useCopyButton } from "fumadocs-ui/utils/use-copy-button";
+//#region src/components/schema/client.tsx
+const typeVariants = cva("text-sm text-start text-fd-muted-foreground font-mono", { variants: { variant: { trigger: "underline hover:text-fd-accent-foreground data-[state=open]:text-fd-accent-foreground" } } });
+const Context = createContext(null);
+function useStates() {
+	return use(Context);
+}
+const ExcludedFromAutoAnchor = /* @__PURE__ */ new Set();
+function SchemaUI({ name, required = false, as = "property", generated }) {
+	const rootId = useAnchorId([name]);
+	const [path, setPath] = useState(() => [{
+		$ref: generated.$root,
+		name
+	}]);
+	const ref = useRef(null);
+	const popoverRef = useCallback((element) => {
+		if (!element) return;
+		element.scrollTop = path.at(-1).scrollTop ?? 0;
+		const current = parseFloat(element.style.getPropertyValue("--min-height") || "200px");
+		element.style.setProperty("--min-height", Math.max(element.clientHeight + 2, current) + "px");
+	}, [path]);
+	useEffect(() => {
+		if (ExcludedFromAutoAnchor.has(rootId)) return;
+		const url = new URL(window.location.href);
+		const param = url.searchParams.get("path");
+		if (url.hash !== `#${rootId}` || !param) return;
+		const decoded = decodePath(param, url.searchParams.get("s-highlight"));
+		if (!decoded || decoded.length === 0 || decoded.some((item) => !generated.refs[item.$ref])) return;
+		setPath(decoded);
+		ExcludedFromAutoAnchor.add(rootId);
+		if (!decoded.at(-1).highlighted) ref.current?.scrollIntoView({ behavior: "smooth" });
+	}, [rootId, generated.refs]);
+	return /* @__PURE__ */ jsx(Context, {
+		value: useMemo(() => ({
+			rootId,
+			path,
+			generated,
+			setPath,
+			renderTypeInfoTrigger: ({ $ref, children, pathName }) => /* @__PURE__ */ jsxs(Popover, {
+				open: path.length > 1 && path[1].$ref === $ref && path[1].name === pathName && !path[0].closed,
+				onOpenChange: (v) => {
+					if (v) setPath([{
+						...path[0],
+						closed: false
+					}, {
+						name: pathName,
+						$ref
+					}]);
+					else setPath(path.map((item, i) => i === 0 ? {
+						...item,
+						closed: true
+					} : item));
+				},
+				children: [/* @__PURE__ */ jsx(PopoverTrigger, {
+					className: cn(typeVariants({ variant: "trigger" })),
+					children
+				}), /* @__PURE__ */ jsx(PopoverContent, {
+					ref: popoverRef,
+					collisionPadding: 10,
+					className: "w-[600px] max-w-(--radix-popover-content-available-width) min-h-(--min-height,200px) fd-scroll-container max-h-[460px] px-3 pt-0",
+					onScrollEnd: (e) => {
+						path.at(-1).scrollTop = e.target.scrollTop;
+					},
+					onOpenAutoFocus: (e) => {
+						const input = e.target.querySelector("input[data-object-search-input]");
+						if (!(input instanceof HTMLInputElement)) return;
+						input.focus({ preventScroll: true });
+						e.preventDefault();
+					},
+					children: /* @__PURE__ */ jsx(SchemaUIPopover, {})
+				})]
+			})
+		}), [
+			generated,
+			path,
+			rootId,
+			popoverRef
+		]),
+		children: as === "property" || generated.refs[generated.$root].type === "primitive" ? /* @__PURE__ */ jsx(ObjectProperty, {
+			ref,
+			id: rootId,
+			name,
+			$type: generated.$root,
+			parentPathIndex: 0,
+			required
+		}) : /* @__PURE__ */ jsx("div", {
+			id: rootId,
+			ref,
+			children: /* @__PURE__ */ jsx(PathItemBody, { pathIndex: 0 })
+		})
+	});
+}
+function SchemaDescription({ schema, ...props }) {
+	return /* @__PURE__ */ jsxs("div", {
+		...props,
+		className: cn("prose-no-margin py-2 empty:hidden", props.className),
+		children: [schema.description, schema.infoTags && schema.infoTags.length > 0 && /* @__PURE__ */ jsx("div", {
+			className: "flex flex-row gap-2 flex-wrap mt-2 not-prose empty:hidden",
+			children: schema.infoTags.map((tag, i) => /* @__PURE__ */ jsx(InfoTag, { tag }, i))
+		})]
+	});
+}
+function ObjectProperty({ name, $type, required, parentPathIndex, ...props }) {
+	const t = useTranslations({ note: "schema UI" });
+	const { path, generated: { refs }, rootId } = useStates();
+	const schema = refs[$type];
+	const parentItem = path[parentPathIndex];
+	const ref = useCallback((element) => {
+		if (!element || parentItem.highlighted !== name) return;
+		window.setTimeout(() => {
+			element.scrollIntoView({
+				behavior: "smooth",
+				block: "end"
+			});
+			delete parentItem.highlighted;
+		}, 300);
+	}, [parentItem, name]);
+	const [isChecked, onClick] = useCopyButton(() => {
+		const url = new URL(window.location.href);
+		url.hash = `#${rootId}`;
+		url.searchParams.set("s-highlight", name);
+		url.searchParams.set("path", encodePath(path));
+		return navigator.clipboard.writeText(url.href);
+	});
+	return /* @__PURE__ */ jsxs("div", {
+		...props,
+		ref: mergeRefs(props.ref, ref),
+		className: cn("text-sm border-t py-4 scroll-m-20 first:border-t-0", props.className),
+		children: [/* @__PURE__ */ jsxs("div", {
+			className: "flex flex-wrap items-center gap-2 not-prose",
+			children: [
+				/* @__PURE__ */ jsxs("span", {
+					className: "font-medium font-mono",
+					children: [/* @__PURE__ */ jsx("span", {
+						className: cn(parentItem.highlighted === name ? "bg-fd-primary text-fd-primary-foreground rounded-sm" : "text-fd-primary", schema.deprecated && "line-through opacity-80"),
+						children: name
+					}), required ? /* @__PURE__ */ jsx("span", {
+						className: "text-red-400",
+						children: "*"
+					}) : /* @__PURE__ */ jsx("span", {
+						className: "text-fd-muted-foreground",
+						children: "?"
+					})]
+				}),
+				schema.type === "primitive" ? /* @__PURE__ */ jsx("span", {
+					className: cn(typeVariants()),
+					children: schema.aliasName
+				}) : /* @__PURE__ */ jsx(TypeInfoTrigger, {
+					pathName: name,
+					$ref: $type,
+					children: schema.aliasName
+				}),
+				/* @__PURE__ */ jsx("div", { className: "flex-1" }),
+				schema.deprecated && /* @__PURE__ */ jsx("span", {
+					className: "text-xs font-mono text-yellow-600 dark:text-yellow-400",
+					children: t("Deprecated")
+				}),
+				/* @__PURE__ */ jsx("button", {
+					className: cn(buttonVariants({
+						size: "icon-xs",
+						variant: "ghost"
+					}), "text-fd-muted-foreground [&_svg]:size-3.5"),
+					onClick,
+					children: isChecked ? /* @__PURE__ */ jsx(CheckIcon, {}) : /* @__PURE__ */ jsx(LinkIcon, {})
+				})
+			]
+		}), /* @__PURE__ */ jsx(SchemaDescription, {
+			schema,
+			className: "pb-0"
+		})]
+	});
+}
+function PathItemBody({ pathIndex, asSchema, tabDepth = 0, objectSearchOverrides }) {
+	const { path, setPath, generated: { refs } } = useStates();
+	const schema = asSchema ?? refs[path[pathIndex].$ref];
+	if ((schema.type === "or" || schema.type === "and") && schema.items.length > 0) {
+		const value = path[pathIndex].tabValues?.[tabDepth] ?? schema.items[0].$type;
+		const items = schema.items.map((item) => ({
+			label: /* @__PURE__ */ jsx("code", {
+				className: "text-xs font-medium",
+				children: item.name
+			}),
+			value: item.$type
+		}));
+		return /* @__PURE__ */ jsxs(Select, {
+			value,
+			onValueChange: (v) => {
+				const next = [...path];
+				(next[pathIndex].tabValues ??= []).splice(tabDepth, 1, v);
+				setPath(next);
+			},
+			children: [/* @__PURE__ */ jsxs("div", {
+				className: "flex flex-row my-2 gap-2 items-center",
+				children: [
+					/* @__PURE__ */ jsx(SchemaDescription, {
+						schema,
+						className: "flex-1 py-0"
+					}),
+					/* @__PURE__ */ jsx(SelectTrigger, {
+						className: "not-prose w-fit min-w-0 mb-auto *:min-w-0",
+						children: /* @__PURE__ */ jsx(SelectValue, { children: items.find((item) => item.value === value)?.label })
+					}),
+					/* @__PURE__ */ jsx(SelectContent, { children: items.map(({ label, value }) => /* @__PURE__ */ jsx(SelectItem, {
+						value,
+						children: label
+					}, value)) })
+				]
+			}), /* @__PURE__ */ jsx(PathItemBody, {
+				asSchema: refs[value],
+				pathIndex,
+				tabDepth: tabDepth + 1
+			})]
+		});
+	}
+	if (schema.type === "object" && schema.props.length > 0) return /* @__PURE__ */ jsx(ObjectSearch, {
+		pathIndex,
+		schema,
+		...objectSearchOverrides,
+		children: /* @__PURE__ */ jsx(SchemaDescription, { schema })
+	});
+	if (schema.type === "array") return /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(SchemaDescription, { schema }), /* @__PURE__ */ jsx(ObjectProperty, {
+		name: "[index: integer]",
+		$type: schema.item.$type,
+		parentPathIndex: pathIndex
+	})] });
+	return /* @__PURE__ */ jsx(SchemaDescription, { schema });
+}
+function ObjectSearch({ variant = "default", schema, pathIndex, children }) {
+	const { path, setPath } = useStates();
+	const [search, setSearch] = useState("");
+	const deferredValue = useDeferredValue(search);
+	const firstItemRef = useRef(null);
+	const t = useTranslations({ note: "schema UI" });
+	return /* @__PURE__ */ jsxs(Fragment$1, { children: [
+		/* @__PURE__ */ jsxs("div", {
+			className: cn("flex items-center bg-fd-secondary text-fd-secondary-foreground transition-colors", variant === "in-popover" && "sticky top-10 -mx-3 ps-3 border-b focus-within:[&_svg]:text-fd-primary", variant === "default" && "border rounded-md ps-2 shadow-sm focus-within:ring-2 focus-within:ring-fd-ring"),
+			children: [/* @__PURE__ */ jsx(FilterIcon, { className: "text-fd-muted-foreground size-3.5 transition-colors" }), /* @__PURE__ */ jsx("input", {
+				value: search,
+				"data-object-search-input": "",
+				onChange: (e) => setSearch(e.target.value),
+				placeholder: t("Filter Properties"),
+				className: "text-sm ps-2 py-2 flex-1 outline-none placeholder:text-fd-muted-foreground",
+				onKeyDown: (e) => {
+					if (e.key === "Enter") {
+						const item = firstItemRef.current;
+						if (item) setPath([...path, {
+							name: item.name,
+							$ref: item.$type
+						}]);
+						e.preventDefault();
+					}
+				}
+			})]
+		}),
+		children,
+		/* @__PURE__ */ jsx(Suspense, { children: /* @__PURE__ */ jsx(ObjectSearchContent, {
+			search: deferredValue,
+			properties: schema.props,
+			firstItemRef,
+			empty: () => /* @__PURE__ */ jsxs("p", {
+				className: "text-fd-muted-foreground text-sm my-2!",
+				children: [
+					t("No property matching"),
+					" ",
+					/* @__PURE__ */ jsx("span", {
+						className: "text-fd-foreground font-medium",
+						children: `"${deferredValue}"`
+					})
+				]
+			}),
+			render: (item) => /* @__PURE__ */ jsx(ObjectProperty, {
+				name: item.name,
+				$type: item.$type,
+				required: item.required,
+				parentPathIndex: pathIndex
+			}, item.name)
+		}) })
+	] });
+}
+function ObjectSearchContent({ search: rawSearch, firstItemRef, properties, empty, render }) {
+	const filtered = useMemo(() => {
+		const search = rawSearch.trim().toLowerCase();
+		return search.length > 0 ? properties.filter((prop) => prop.name.toLowerCase().includes(search)) : properties;
+	}, [properties, rawSearch]);
+	firstItemRef.current = filtered[0] ?? null;
+	if (filtered.length === 0) return empty();
+	return filtered.map(render);
+}
+function InfoTag({ tag }) {
+	const ref = useRef(null);
+	const [open, setOpen] = useState(false);
+	return /* @__PURE__ */ jsxs("button", {
+		className: "inline-flex text-start items-start gap-2 bg-fd-secondary border rounded-lg text-xs p-1.5 shadow-md max-w-full",
+		onClick: () => setOpen((prev) => !prev),
+		children: [/* @__PURE__ */ jsx("span", {
+			className: "font-medium",
+			children: tag.label
+		}), /* @__PURE__ */ jsx("code", {
+			ref,
+			className: cn("min-w-0 flex-1 text-fd-muted-foreground", open ? "wrap-break-word" : "truncate"),
+			children: tag.value
+		})]
+	});
+}
+function SchemaUIPopover() {
+	const states = useStates();
+	const { path, setPath } = states;
+	return /* @__PURE__ */ jsxs(Context, {
+		value: useMemo(() => ({
+			...states,
+			renderTypeInfoTrigger: ({ $ref, pathName, children }) => /* @__PURE__ */ jsx("button", {
+				className: cn(typeVariants({ variant: "trigger" })),
+				onClick: () => setPath([...path, {
+					name: pathName,
+					$ref
+				}]),
+				children
+			})
+		}), [
+			states,
+			setPath,
+			path
+		]),
+		children: [/* @__PURE__ */ jsx("div", {
+			className: "sticky top-0 -mx-3 flex overflow-x-auto overflow-y-hidden items-center text-sm font-medium font-mono bg-fd-secondary text-fd-secondary-foreground px-3 h-10 border-b z-20",
+			children: path.map((item, i) => {
+				if (i === 0) return;
+				const isDuplicated = path.some((other, j) => j !== i && other.$ref === item.$ref);
+				let text;
+				const indexItemMatch = /^\[(\w+): (\w+)]$/.exec(item.name);
+				if (indexItemMatch) text = `[${indexItemMatch[1]}]`;
+				else if (i > 1) text = `.${item.name}`;
+				else text = item.name;
+				return /* @__PURE__ */ jsx("button", {
+					onClick: () => setPath(path.slice(0, i + 1)),
+					className: cn("hover:underline hover:text-fd-accent-foreground", isDuplicated && "text-orange-400"),
+					children: text
+				}, i);
+			})
+		}), /* @__PURE__ */ jsx(PathItemBody, {
+			pathIndex: path.length - 1,
+			objectSearchOverrides: { variant: "in-popover" }
+		})]
+	});
+}
+function TypeInfoTrigger({ pathName, $ref, children }) {
+	const { generated: { refs }, renderTypeInfoTrigger } = useStates();
+	const schema = refs[$ref];
+	if (schema.type === "primitive" && !schema.description && (!schema.infoTags || schema.infoTags.length === 0)) return /* @__PURE__ */ jsx("span", {
+		className: cn(typeVariants()),
+		children
+	});
+	if (schema.type === "and" || schema.type === "or") {
+		const sep = schema.type === "and" ? "&" : "|";
+		return /* @__PURE__ */ jsx("span", {
+			className: cn(typeVariants(), "flex flex-row gap-2 items-center flex-wrap"),
+			children: schema.items.map((item, i) => /* @__PURE__ */ jsxs(Fragment, { children: [i > 0 && /* @__PURE__ */ jsx("span", { children: sep }), /* @__PURE__ */ jsx(TypeInfoTrigger, {
+				pathName,
+				$ref: item.$type,
+				children: item.name
+			})] }, item.$type))
+		});
+	}
+	if (schema.type === "array") return /* @__PURE__ */ jsxs("span", {
+		className: cn(typeVariants(), "flex flex-row items-center flex-wrap"),
+		children: [
+			"array<",
+			/* @__PURE__ */ jsx(TypeInfoTrigger, {
+				pathName: `${pathName}[]`,
+				$ref: schema.item.$type,
+				children: refs[schema.item.$type].aliasName
+			}),
+			">"
+		]
+	});
+	return renderTypeInfoTrigger({
+		$ref,
+		pathName,
+		children
+	});
+}
+function encodePath(path) {
+	return path.map((item) => [
+		item.name,
+		item.$ref,
+		...item.tabValues ?? []
+	].join("\0")).join("|");
+}
+function decodePath(path, highlighted) {
+	const out = [];
+	for (const part of path.split("|")) {
+		const [name, $ref, ...tabValues] = part.split("\0");
+		out.push({
+			name,
+			$ref,
+			tabValues
+		});
+	}
+	if (highlighted && out.length > 0) out[out.length - 1].highlighted = highlighted;
+	return out;
+}
+//#endregion
+export { SchemaUI };

package/dist/components/schema/index.d.ts

@@ -0,0 +1,102 @@
+import { ParsedSchema, SchemaResolver } from "../../schema/index.js";
+import { SchemaUIProps } from "./client.js";
+import { ReactNode } from "react";
+
+//#region src/components/schema/index.d.ts
+interface FieldBase {
+  description?: ReactNode;
+  infoTags?: InfoTag[];
+  typeName: string;
+  aliasName: string;
+  deprecated?: boolean;
+}
+interface InfoTag {
+  label: ReactNode;
+  value: string;
+}
+interface SchemaDataObjectProperty {
+  name: string;
+  $type: string;
+  required: boolean;
+}
+type SchemaData = FieldBase & ({
+  type: 'primitive';
+} | {
+  type: 'object';
+  props: SchemaDataObjectProperty[];
+} | {
+  type: 'array';
+  item: {
+    $type: string;
+  };
+} | {
+  type: 'or';
+  items: {
+    name: string;
+    $type: string;
+  }[];
+} | {
+  type: 'and';
+  items: {
+    name: string;
+    $type: string;
+  }[];
+});
+interface SchemaUIOptions {
+  root: ParsedSchema;
+  client: Omit<SchemaUIProps, 'generated'>;
+  resolver: SchemaResolver;
+  renderMarkdown: (md: string) => ReactNode;
+  /**
+   * include read only props
+   */
+  readOnly?: boolean;
+  /**
+   * include write only props
+   */
+  writeOnly?: boolean;
+  /**
+   * Show example values as tags
+   *
+   * @default false
+   */
+  showExample?: boolean;
+}
+interface SchemaUIGeneratedData {
+  $root: string;
+  refs: Record<string, SchemaData>;
+}
+interface SchemaUILabels {
+  default: string;
+  match: string;
+  format: string;
+  multipleOf: string;
+  range: string;
+  length: string;
+  properties: string;
+  items: string;
+  valueIn: string;
+  example: string;
+}
+declare function Schema({
+  client,
+  root,
+  readOnly,
+  writeOnly,
+  resolver,
+  showExample,
+  renderMarkdown
+}: SchemaUIOptions): import("react").JSX.Element;
+declare function generateSchemaUI({
+  root,
+  resolver,
+  renderMarkdown,
+  readOnly,
+  writeOnly,
+  showExample,
+  labels
+}: Omit<SchemaUIOptions, 'client'> & {
+  labels: SchemaUILabels;
+}): SchemaUIGeneratedData;
+//#endregion
+export { FieldBase, InfoTag, Schema, SchemaData, SchemaDataObjectProperty, SchemaUIGeneratedData, SchemaUIOptions, generateSchemaUI };