// Renders TypeDoc types and comments to HTML strings. import MarkdownIt from "markdown-it"; import { createHighlighter } from "shiki"; import { type Api, hrefOf } from "./model"; import { type Comment, type CommentPart, Kind, type Reflection, type Type, } from "./types"; const theme = "github-dark"; const langs = ["ts", "tsx", "js", "jsx", "html", "css", "glsl", "json", "bash"]; const highlighter = await createHighlighter({ themes: [theme], langs }); const md = new MarkdownIt({ html: false, linkify: true, highlight: (code, lang) => highlight(code.replace(/\n$/, ""), lang), }); /** Highlighted
for a code sample. */
export function highlight(code: string, lang = "ts"): string {
const l = langs.includes(lang) ? lang : "text";
// The page styles the box. Drop shiki's inline background.
return highlighter
.codeToHtml(code, { lang: l, theme })
.replace(/^]*) style="[^"]*"/, "/g, ">")
.replace(/"/g, """);
}
//================ Comments ================//
function partsToMarkdown(api: Api, parts: CommentPart[]): string {
return parts
.map((p) => {
if (p.kind === "inline-tag") {
const text = p.text.trim();
const href =
typeof p.target === "number"
? hrefOf(api, p.target)
: undefined;
if (/^https?:/.test(text)) {
return `<${text}>`;
}
return href ? `[\`${text}\`](${href})` : `\`${text}\``;
}
return p.text;
})
.join("");
}
export function markdownHtml(
api: Api,
parts: CommentPart[] | undefined,
): string {
if (!parts || parts.length === 0) {
return "";
}
return md.render(partsToMarkdown(api, parts));
}
/** Markdown on one line, without the wrapping . */
export function inlineMarkdownHtml(
api: Api,
parts: CommentPart[] | undefined,
): string {
if (!parts || parts.length === 0) {
return "";
}
return md.renderInline(
partsToMarkdown(api, parts).replace(/\s*\n\s*/g, " "),
);
}
const blockTagTitles: Record = {
"@example": "Example",
"@throws": "Throws",
"@see": "See also",
"@remarks": "Remarks",
"@deprecated": "Deprecated",
"@defaultValue": "Default",
"@default": "Default",
};
/** Tags shown elsewhere or not at all. */
const hiddenBlockTags = new Set([
"@returns",
"@notExported",
"@param",
"@typeParam",
]);
export type BlockTag = { title: string; html: string };
export function blockTags(api: Api, comment: Comment | undefined): BlockTag[] {
return (comment?.blockTags ?? [])
.filter((t) => !hiddenBlockTags.has(t.tag))
.map((t) => ({
title:
blockTagTitles[t.tag] ??
t.tag.replace(/^@/, "").replace(/^./, (c) => c.toUpperCase()),
html: markdownHtml(api, t.content),
}));
}
export function returnsHtml(api: Api, comment: Comment | undefined): string {
const tag = comment?.blockTags?.find((t) => t.tag === "@returns");
return tag ? markdownHtml(api, tag.content) : "";
}
//================ Types ================//
const span = (cls: string, text: string) =>
`${escapeHtml(text)}`;
const punct = (text: string) => span("tp", text);
/** Signatures longer than this put each parameter on its own line. */
const maxLineLength = 80;
/** Visible characters on the first line of our own type HTML. */
function textLength(html: string): number {
let length = 0;
let inTag = false;
let inEntity = false;
for (const c of html) {
if (c === "\n") {
break;
}
if (inTag) {
inTag = c !== ">";
} else if (c === "<") {
inTag = true;
} else if (inEntity) {
inEntity = c !== ";";
} else {
// An entity like < is one character.
inEntity = c === "&";
length++;
}
}
return length;
}
/** Object types with more members than this go on several lines. */
const inlineMemberLimit = 2;
type Ctx = { api: Api; indent: number };
function pad(n: number): string {
return " ".repeat(n);
}
/** HTML for a type, with links to the API pages. */
export function typeHtml(api: Api, type: Type | undefined, indent = 0): string {
if (!type) {
return span("tk", "any");
}
return renderType({ api, indent }, type);
}
/** Whether a type needs parentheses inside an array or union. */
function needsParens(t: Type, inUnion: boolean): boolean {
switch (t.type) {
case "union":
case "conditional":
return true;
case "intersection":
return !inUnion;
case "typeOperator":
return !inUnion;
case "reflection":
return Boolean(t.declaration.signatures?.length);
default:
return false;
}
}
function wrap(ctx: Ctx, t: Type, inUnion: boolean): string {
const html = renderType(ctx, t);
return needsParens(t, inUnion) ? `${punct("(")}${html}${punct(")")}` : html;
}
function renderType(ctx: Ctx, t: Type): string {
switch (t.type) {
case "intrinsic":
return span("tk", t.name);
case "literal": {
const v = t.value;
if (v === null) {
return span("tk", "null");
}
if (typeof v === "string") {
return span("ts", JSON.stringify(v));
}
if (typeof v === "object") {
return span("tn", `${v.negative ? "-" : ""}${v.value}n`);
}
return span(typeof v === "number" ? "tn" : "tk", String(v));
}
case "reference": {
let name: string;
const href =
typeof t.target === "number" && !t.refersToTypeParameter
? hrefOf(ctx.api, t.target)
: t.externalUrl;
if (href) {
name = `${escapeHtml(t.name)}`;
} else {
name = span(t.refersToTypeParameter ? "tt" : "tr", t.name);
}
if (!t.typeArguments?.length) {
return name;
}
const args = t.typeArguments
.map((a) => renderType(ctx, a))
.join(punct(", "));
return `${name}${punct("<")}${args}${punct(">")}`;
}
case "union":
return t.types.map((u) => wrap(ctx, u, true)).join(punct(" | "));
case "intersection":
return t.types.map((u) => wrap(ctx, u, true)).join(punct(" & "));
case "array":
return `${wrap(ctx, t.elementType, false)}${punct("[]")}`;
case "tuple":
return `${punct("[")}${(t.elements ?? [])
.map((e) => renderType(ctx, e))
.join(punct(", "))}${punct("]")}`;
case "namedTupleMember":
return `${span("tm", t.name)}${punct(t.isOptional ? "?: " : ": ")}${renderType(ctx, t.element)}`;
case "optional":
return `${wrap(ctx, t.elementType, false)}${punct("?")}`;
case "rest":
return `${punct("...")}${wrap(ctx, t.elementType, false)}`;
case "typeOperator":
return `${span("tk", t.operator)} ${wrap(ctx, t.target, false)}`;
case "reflection":
return reflectionType(ctx, t.declaration);
case "conditional":
return [
wrap(ctx, t.checkType, false),
span("tk", " extends "),
renderType(ctx, t.extendsType),
punct(" ? "),
renderType(ctx, t.trueType),
punct(" : "),
renderType(ctx, t.falseType),
].join("");
case "indexedAccess":
return `${renderType(ctx, t.objectType)}${punct("[")}${renderType(ctx, t.indexType)}${punct("]")}`;
case "inferred":
return `${span("tk", "infer ")}${span("tt", t.name)}`;
case "predicate":
return [
t.asserts ? span("tk", "asserts ") : "",
span("tm", t.name),
t.targetType
? `${span("tk", " is ")}${renderType(ctx, t.targetType)}`
: "",
].join("");
case "query":
return `${span("tk", "typeof ")}${renderType(ctx, t.queryType)}`;
case "mapped": {
const ro =
t.readonlyModifier === "+"
? "readonly "
: t.readonlyModifier === "-"
? "-readonly "
: "";
const opt =
t.optionalModifier === "+"
? "?"
: t.optionalModifier === "-"
? "-?"
: "";
return [
punct("{ "),
ro ? span("tk", ro) : "",
punct("["),
span("tt", t.parameter),
span("tk", " in "),
renderType(ctx, t.parameterType),
t.nameType
? `${span("tk", " as ")}${renderType(ctx, t.nameType)}`
: "",
punct(`]${opt}: `),
renderType(ctx, t.templateType),
punct(" }"),
].join("");
}
case "templateLiteral":
return [
span("ts", `\`${t.head}`),
...t.tail.map(
([inner, text]) =>
`${span("ts", "${")}${renderType(ctx, inner)}${span("ts", `}${text}`)}`,
),
span("ts", "`"),
].join("");
case "unknown":
return escapeHtml(t.name);
default:
return escapeHtml((t as { type: string }).type);
}
}
/** An inline object or function type. */
function reflectionType(ctx: Ctx, decl: Reflection): string {
const sigs = decl.signatures ?? [];
if (sigs.length === 1 && !decl.children?.length) {
return signatureHtml(ctx.api, sigs[0], {
arrow: true,
indent: ctx.indent,
});
}
const lines: string[] = [];
for (const s of decl.indexSignatures ?? []) {
lines.push(indexSignatureHtml(ctx.api, s, ctx.indent + 1));
}
for (const s of sigs) {
lines.push(signatureHtml(ctx.api, s, { indent: ctx.indent + 1 }));
}
for (const c of decl.children ?? []) {
lines.push(memberLineHtml(ctx.api, c, ctx.indent + 1));
}
if (lines.length === 0) {
return punct("{}");
}
const multiline =
lines.length > inlineMemberLimit || lines.some((l) => l.includes("\n"));
if (!multiline) {
return `${punct("{ ")}${lines.join(punct("; "))}${punct(" }")}`;
}
const inner = lines.map((l) => `${pad(ctx.indent + 1)}${l}${punct(";")}`);
return `${punct("{")}\n${inner.join("\n")}\n${pad(ctx.indent)}${punct("}")}`;
}
/** `name?: Type` for a property, or a method signature. */
function memberLineHtml(api: Api, r: Reflection, indent: number): string {
if (r.signatures?.length) {
return r.signatures
.map((s) => signatureHtml(api, s, { indent, name: r.name }))
.join(`${punct(";")}\n${pad(indent)}`);
}
if (r.getSignature || r.setSignature) {
const t = r.getSignature?.type ?? r.setSignature?.parameters?.[0]?.type;
return `${r.setSignature ? "" : span("tk", "readonly ")}${span("tm", r.name)}${punct(": ")}${typeHtml(api, t, indent)}`;
}
return propertyHtml(api, r, indent);
}
/** `type Name = ...`. Long unions put each member on its own line. */
export function typeAliasHtml(api: Api, decl: Reflection): string {
const head = `${span("tk", "type ")}${span("tr", decl.name)}${typeParamsHtml(api, decl.typeParameters)}${punct(" =")}`;
const t = decl.type;
const oneLine = `${head} ${typeHtml(api, t)}`;
if (t?.type !== "union" || textLength(oneLine) <= maxLineLength) {
return oneLine;
}
const lines = t.types.map(
(u) => `${pad(1)}${punct("| ")}${wrap({ api, indent: 1 }, u, true)}`,
);
return `${head}\n${lines.join("\n")}`;
}
export function propertyHtml(api: Api, r: Reflection, indent = 0): string {
return [
r.flags.isReadonly ? span("tk", "readonly ") : "",
span("tm", propertyName(r.name)),
punct(r.flags.isOptional ? "?: " : ": "),
typeHtml(api, r.type, indent),
].join("");
}
function propertyName(name: string): string {
return /^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name);
}
export function indexSignatureHtml(
api: Api,
s: Reflection,
indent = 0,
): string {
const p = s.parameters?.[0];
return [
punct("["),
span("tm", p?.name ?? "key"),
punct(": "),
typeHtml(api, p?.type, indent),
punct("]: "),
typeHtml(api, s.type, indent),
].join("");
}
export function typeParamsHtml(
api: Api,
params: Reflection[] | undefined,
): string {
if (!params?.length) {
return "";
}
const items = params.map((p) =>
[
span("tt", p.name),
p.type ? `${span("tk", " extends ")}${typeHtml(api, p.type)}` : "",
p.default ? `${punct(" = ")}${typeHtml(api, p.default)}` : "",
].join(""),
);
return `${punct("<")}${items.join(punct(", "))}${punct(">")}`;
}
type SignatureOpts = {
/** `(a) => R` instead of `name(a): R`. */
arrow?: boolean;
/** Name to show. Defaults to the signature's name. */
name?: string;
indent?: number;
};
/** `name(a: A, b?: B): R` */
export function signatureHtml(
api: Api,
s: Reflection,
opts: SignatureOpts = {},
): string {
const indent = opts.indent ?? 0;
const isCtor = s.kind === Kind.ConstructorSignature;
const params = (s.parameters ?? []).map((p) =>
[
p.flags.isRest ? punct("...") : "",
span("tm", p.name),
punct(
p.flags.isOptional || p.defaultValue !== undefined
? "?: "
: ": ",
),
typeHtml(api, p.type, indent),
// Defaults show in the page's signatures, not in inline types.
p.defaultValue !== undefined && !opts.arrow
? punct(` = ${p.defaultValue}`)
: "",
].join(""),
);
const head = opts.arrow
? ""
: isCtor
? `${span("tk", "new ")}${span("tf", opts.name ?? s.name)}`
: span("tf", opts.name ?? s.name);
const ret = typeHtml(api, s.type, indent);
const oneLine = [
head,
typeParamsHtml(api, s.typeParameters),
punct("("),
params.join(punct(", ")),
punct(")"),
opts.arrow ? punct(" => ") : punct(": "),
ret,
].join("");
if (params.length < 2 || textLength(oneLine) <= maxLineLength) {
return oneLine;
}
// Long signatures: one parameter per line.
const inner = params.map((p) => `${pad(indent + 1)}${p}${punct(",")}`);
return [
head,
typeParamsHtml(api, s.typeParameters),
punct("("),
`\n${inner.join("\n")}\n${pad(indent)}`,
punct(")"),
opts.arrow ? punct(" => ") : punct(": "),
ret,
].join("");
}