Skip to content

Code-first video & image, rendered natively on WebGPU.

3.9 KB
Raw Blame
/**
 * A component's props as documentation: name, a short type, default and
 * whether it's required come from its zod schema; the description comes from
 * the JSDoc comment above the prop in `index.ts` (zod drops comments, so the
 * source is read with the TypeScript parser).
 */
import { readFileSync } from "node:fs";
import ts from "typescript";
import { z } from "zod";

export interface PropDoc {
	name: string;
	/** A TypeScript-like summary: `number`, `"bar" | "tag"`, `string[]` … */
	type: string;
	required: boolean;
	default?: unknown;
	description?: string;
}

interface JsonSchema {
	type?: string | string[];
	enum?: unknown[];
	const?: unknown;
	items?: JsonSchema;
	anyOf?: JsonSchema[];
	oneOf?: JsonSchema[];
	properties?: Record<string, JsonSchema>;
	default?: unknown;
}

/** Docs for every prop in `shape`, in declaration order. */
export function propDocs(
	shape: Record<string, z.ZodType>,
	descriptions: Record<string, string> = {},
): PropDoc[] {
	return Object.entries(shape).map(([name, schema]) => {
		const json = z.toJSONSchema(schema, {
			unrepresentable: "any",
			io: "input",
		}) as JsonSchema;
		const doc: PropDoc = {
			name,
			type: typeOf(json),
			required: !schema.safeParse(undefined).success,
		};
		if (json.default !== undefined) doc.default = json.default;
		const description = descriptions[name] ?? schema.description;
		if (description) doc.description = description;
		return doc;
	});
}

function typeOf(s: JsonSchema, depth = 0): string {
	if (s.const !== undefined) return JSON.stringify(s.const);
	if (s.enum) return s.enum.map((v) => JSON.stringify(v)).join(" | ");
	const union = s.anyOf ?? s.oneOf;
	if (union)
		return [...new Set(union.map((u) => typeOf(u, depth + 1)))].join(" | ");
	const t = Array.isArray(s.type) ? s.type.join(" | ") : s.type;
	if (t === "integer") return "number";
	if (t === "array")
		return s.items ? `${wrap(typeOf(s.items, depth + 1))}[]` : "unknown[]";
	if (t === "object") {
		if (!s.properties || depth > 0) return "object";
		const keys = Object.keys(s.properties);
		return `{ ${keys.join(", ")} }`;
	}
	return t ?? "unknown";
}

const wrap = (t: string) => (t.includes(" ") ? `(${t})` : t);

/**
 * JSDoc text above each prop of the `props: () => ({ … })` object in a
 * component's source (or of the members of interface `iface`), by prop name.
 */
export function propComments(
	file: string,
	iface?: string,
): Record<string, string> {
	const source = ts.createSourceFile(
		file,
		readFileSync(file, "utf8"),
		ts.ScriptTarget.Latest,
		true,
	);
	const out: Record<string, string> = {};
	const visit = (node: ts.Node) => {
		if (iface && ts.isInterfaceDeclaration(node) && node.name.text === iface) {
			for (const member of node.members) {
				const text = jsDoc(member, source);
				if (text && member.name) out[member.name.getText(source)] = text;
			}
			return;
		}
		if (
			!iface &&
			ts.isPropertyAssignment(node) &&
			node.name.getText(source) === "props" &&
			ts.isArrowFunction(node.initializer)
		) {
			let body: ts.Node = node.initializer.body;
			while (ts.isParenthesizedExpression(body)) body = body.expression;
			if (ts.isObjectLiteralExpression(body)) {
				for (const prop of body.properties) {
					const text = jsDoc(prop, source);
					if (text && prop.name) out[prop.name.getText(source)] = text;
				}
				return;
			}
		}
		ts.forEachChild(node, visit);
	};
	visit(source);
	return out;
}

function jsDoc(node: ts.Node, source: ts.SourceFile): string | undefined {
	const ranges = ts.getLeadingCommentRanges(
		source.getFullText(),
		node.getFullStart(),
	);
	const last = ranges?.filter((r) =>
		source
			.getFullText()
			.slice(r.pos, r.pos + 3)
			.startsWith("/**"),
	);
	const range = last?.[last.length - 1];
	if (!range) return undefined;
	return source
		.getFullText()
		.slice(range.pos + 3, range.end - 2)
		.split("\n")
		.map((l) => l.replace(/^\s*\*\s?/, "").trim())
		.filter(Boolean)
		.join(" ");
}