@apify/docusaurus-plugin-typedoc-api 3.0.0

package/src/components/Markdown.tsx

@@ -0,0 +1,241 @@
+/* eslint-disable unicorn/no-unsafe-regex */
+/* eslint-disable react/no-array-index-key */
+
+import React, { useState } from 'react';
+import { marked } from 'marked';
+import { useDocsVersion } from '@docusaurus/theme-common/internal';
+import MDX from '@theme/MDXComponents';
+import { useReflectionMap } from '../hooks/useReflectionMap';
+import { replaceLinkTokens } from '../utils/markdown';
+
+interface Admonition {
+	type: 'admonition';
+	raw: string;
+	title?: string;
+	keyword?: string;
+	text: string;
+	tokens: marked.Token[];
+}
+
+type TokensList = (Admonition | marked.Token)[];
+
+marked.setOptions({
+	gfm: true,
+	headerIds: false,
+	mangle: false,
+	smartLists: true,
+	smartypants: true,
+});
+
+const ADMONITION_START = /^:{3}([a-z]+)? *(.*)\n/;
+const ADMONITION_END = '\n:::';
+
+marked.use({
+	extensions: [
+		{
+			name: 'admonition',
+			level: 'block',
+			start(src) {
+				// eslint-disable-next-line @typescript-eslint/no-non-null-asserted-optional-chain
+				return src.match(ADMONITION_START)?.index!;
+			},
+			tokenizer(src, tokens) {
+				const match = ADMONITION_START.exec(src);
+
+				if (match) {
+					const keyword = match[1] ?? 'info';
+					const title = match[2] ? match[2].trim() : undefined;
+					const startIndex = match.index;
+					const startEndIndex = startIndex + match[0].length;
+					const endIndex = src.indexOf(ADMONITION_END, startEndIndex);
+					const endEndIndex = endIndex + 4;
+
+					const token: Admonition = {
+						type: 'admonition',
+						raw: src.slice(startIndex, endEndIndex),
+						text: src.slice(startEndIndex, endIndex),
+						title,
+						keyword,
+						tokens: [],
+					};
+
+					this.lexer.blockTokens(token.text, token.tokens);
+
+					return token;
+				}
+
+				return undefined;
+			},
+		},
+	],
+});
+
+const TOKEN_TO_TAG: Record<string, keyof JSX.IntrinsicElements> = {
+	blockquote: 'blockquote',
+	br: 'br',
+	code: 'pre',
+	codespan: 'code',
+	def: 'span', // ???
+	del: 'del',
+	em: 'em',
+	escape: 'span', // ???
+	hr: 'hr',
+	html: 'div',
+	paragraph: 'p',
+	strong: 'strong',
+	table: 'table',
+	tablecell: 'td',
+	tablerow: 'tr',
+};
+
+function convertAstToElements(ast: TokensList): React.ReactNode[] | undefined {
+	const elements: React.ReactNode[] = [];
+	let counter = 0;
+
+	// eslint-disable-next-line complexity
+	ast.forEach((token) => {
+		// Nested tokens aren't typed for some reason...
+		const children = (token as unknown as { tokens: TokensList }).tokens ?? [];
+
+		switch (token.type) {
+			case 'code':
+				elements.push(
+					<MDX.pre key={counter} className={token.lang && `language-${token.lang}`}>
+						{token.text}
+					</MDX.pre>,
+				);
+				break;
+
+			case 'codespan':
+				// Non-raw is escaped and doesn't work with JSX, so use the raw value
+				// but remove the wrapping backticks!
+				elements.push(<MDX.code key={counter}>{token.raw.slice(1, -1)}</MDX.code>);
+				break;
+
+			case 'heading': {
+				const Comp = MDX[`h${token.depth}` as 'h1'];
+				elements.push(<Comp key={counter}>{convertAstToElements(children) ?? token.text}</Comp>);
+				break;
+			}
+
+			case 'image':
+				elements.push(<MDX.img key={counter} alt={token.title} src={token.href} />);
+				break;
+
+			case 'link':
+				elements.push(
+					<MDX.a key={counter} href={token.href} title={token.title}>
+						{convertAstToElements(children) ?? token.text}
+					</MDX.a>,
+				);
+				break;
+
+			case 'list': {
+				const Comp = token.ordered ? 'ol' : 'ul';
+				elements.push(
+					<Comp key={counter}>
+						{convertAstToElements((token.items as TokensList) ?? children)}
+					</Comp>,
+				);
+				break;
+			}
+
+			case 'list_item':
+				elements.push(
+					<li key={counter}>
+						{token.task && (
+							<>
+								<input checked={token.checked} type="checkbox" />{' '}
+							</>
+						)}
+						{convertAstToElements(children) ?? token.text}
+					</li>,
+				);
+				break;
+
+			case 'space':
+				elements.push(token.raw || ' ');
+				break;
+
+			case 'table':
+				elements.push(
+					<table key={counter}>
+						<thead>
+							<tr>
+								{token.header.map((h, i) => (
+									<th key={i} align={token.align[i]!}>
+										{convertAstToElements(h.tokens as TokensList)}
+									</th>
+								))}
+							</tr>
+						</thead>
+						<tbody>
+							{token.rows.map((cells, i) => (
+								<tr key={i}>
+									{cells.map((c, i2) => (
+										<td key={i2} align={token.align[i]!}>
+											{convertAstToElements(c.tokens as TokensList)}
+										</td>
+									))}
+								</tr>
+							))}
+						</tbody>
+					</table>,
+				);
+				break;
+
+			case 'text':
+				elements.push(
+					children.length === 0 ? (
+						token.text
+					) : (
+						<React.Fragment key={counter}>{convertAstToElements(children)}</React.Fragment>
+					),
+				);
+				break;
+
+			case 'admonition':
+				elements.push(
+					<MDX.admonition key={counter} title={token.title} type={token.keyword as 'note'}>
+						{convertAstToElements(children) ?? token.text}
+					</MDX.admonition>,
+				);
+				break;
+
+			default: {
+				const Comp = TOKEN_TO_TAG[token.type] || token.type;
+				const innerText = 'text' in token ? token.text : '';
+
+				elements.push(<Comp key={counter}>{convertAstToElements(children) ?? innerText}</Comp>);
+				break;
+			}
+		}
+
+		counter += 1;
+	});
+
+	if (elements.length === 0) {
+		return undefined;
+	}
+
+	return elements;
+}
+
+export interface MarkdownProps {
+	content: string;
+}
+
+// Too bad we cant use `@mdx-js` here...
+export function Markdown({ content }: MarkdownProps) {
+	const reflections = useReflectionMap();
+	const version = useDocsVersion();
+	const [ast] = useState<TokensList>(() =>
+		marked.lexer(replaceLinkTokens(content, reflections, version)),
+	);
+
+	if (!content) {
+		return null;
+	}
+
+	return <div className="tsd-markdown markdown">{convertAstToElements(ast)}</div>;
+}

package/src/components/Member.tsx

@@ -0,0 +1,64 @@
+// https://github.com/TypeStrong/typedoc-default-themes/blob/master/src/default/partials/members.hbs
+
+import React from 'react';
+import type { JSONOutput } from 'typedoc';
+import { useReflection } from '../hooks/useReflection';
+import { useReflectionMap } from '../hooks/useReflectionMap';
+import { hasOwnDocument } from '../utils/visibility';
+import { AnchorLink } from './AnchorLink';
+import { CommentBadges, isCommentWithModifiers } from './CommentBadges';
+import { Flags } from './Flags';
+import { MemberDeclaration } from './MemberDeclaration';
+import { MemberGetterSetter } from './MemberGetterSetter';
+import { MemberReference } from './MemberReference';
+import { MemberSignatures } from './MemberSignatures';
+import { SourceLink } from './SourceLink';
+
+export interface MemberProps {
+	id: number;
+}
+
+export function Member({ id }: MemberProps) {
+	const reflections = useReflectionMap();
+	const reflection = useReflection(id)!;
+	const { comment } = reflection;
+	let content: React.ReactNode = null;
+
+	if (reflection.signatures) {
+		content = <MemberSignatures inPanel sigs={reflection.signatures} />;
+	} else if (reflection.getSignature || reflection.setSignature) {
+		content = (
+			<MemberGetterSetter
+				inPanel
+				getter={reflection.getSignature}
+				setter={reflection.setSignature}
+			/>
+		);
+	} else if ('target' in reflection && (reflection as JSONOutput.ReferenceReflection).target) {
+		content = <MemberReference reflection={reflection as JSONOutput.ReferenceReflection} />;
+	} else {
+		content = <MemberDeclaration id={id} />;
+	}
+
+	return (
+		<section className="tsd-panel tsd-member">
+			<h3 className="tsd-panel-header">
+				<AnchorLink id={reflection.name} />
+				<SourceLink sources={reflection.sources} />
+				<Flags flags={reflection.flags} />
+				{reflection.name}
+				{isCommentWithModifiers(comment) && <CommentBadges comment={comment} />}
+			</h3>
+
+			{content}
+
+			{reflection.groups?.map((group) => (
+				<React.Fragment key={group.title}>
+					{group.children?.map((child) =>
+						hasOwnDocument(child, reflections) ? null : <Member key={child} id={child} />,
+					)}
+				</React.Fragment>
+			))}
+		</section>
+	);
+}

package/src/components/MemberDeclaration.tsx

@@ -0,0 +1,67 @@
+// https://github.com/TypeStrong/typedoc-default-themes/blob/master/src/default/partials/member.declaration.hbs
+
+import React from 'react';
+import { useMinimalLayout } from '../hooks/useMinimalLayout';
+import { useReflection } from '../hooks/useReflection';
+import { Comment, hasComment } from './Comment';
+import { DefaultValue } from './DefaultValue';
+import { Icon } from './Icon';
+import { MemberSources } from './MemberSources';
+import { Parameter } from './Parameter';
+import { Type } from './Type';
+import { TypeParameters } from './TypeParameters';
+import { TypeParametersGeneric } from './TypeParametersGeneric';
+
+export interface MemberDeclarationProps {
+	id: number;
+}
+
+export function MemberDeclaration({ id }: MemberDeclarationProps) {
+	const reflection = useReflection(id)!;
+	const minimal = useMinimalLayout();
+	const showTypes = reflection.typeParameters && reflection.typeParameters.length > 0;
+	const showDeclaration = !minimal && reflection.type?.declaration;
+
+	return (
+		<>
+			<div className="tsd-panel-content">
+				<div className="tsd-signature tsd-kind-icon">
+					<Icon reflection={reflection} />
+					{reflection.name}
+					<TypeParametersGeneric params={reflection.typeParameters} />
+					<span className="tsd-signature-symbol">{reflection.flags?.isOptional && '?'}: </span>{' '}
+					<Type type={reflection.type} />
+					<DefaultValue
+						comment={reflection.comment}
+						type={reflection.type}
+						value={reflection.defaultValue}
+					/>
+				</div>
+			</div>
+
+			<div className="tsd-panel-content">
+				<MemberSources reflection={reflection} />
+
+				<Comment comment={reflection.comment} />
+
+				{hasComment(reflection.comment) && (showTypes || showDeclaration) && (
+					<hr className="tsd-divider" />
+				)}
+
+				{showTypes && (
+					<div className="tds-type-parameters">
+						<h4 className="tsd-type-parameters-title">Type parameters</h4>
+						<TypeParameters params={reflection.typeParameters} />
+					</div>
+				)}
+
+				{showDeclaration && (
+					<div className="tsd-type-declaration">
+						<h4>Type declaration</h4>
+						<Parameter param={reflection.type?.declaration} />
+					</div>
+				)}
+			</div>
+		</>
+	);
+}

package/src/components/MemberGetterSetter.tsx

@@ -0,0 +1,69 @@
+// https://github.com/TypeStrong/typedoc-default-themes/blob/master/src/default/partials/member.getterSetter.hbs
+
+import React from 'react';
+import type { JSONOutput } from 'typedoc';
+import { useMinimalLayout } from '../hooks/useMinimalLayout';
+import { Icon } from './Icon';
+import { hasSigBody, MemberSignatureBody } from './MemberSignatureBody';
+import { MemberSignatureTitle } from './MemberSignatureTitle';
+
+export interface MemberGetterSetterProps {
+	inPanel?: boolean;
+	getter?: JSONOutput.DeclarationReflection['getSignature'];
+	setter?: JSONOutput.DeclarationReflection['setSignature'];
+}
+
+// eslint-disable-next-line complexity
+export function MemberGetterSetter({ inPanel, getter, setter }: MemberGetterSetterProps) {
+	const minimal = useMinimalLayout();
+
+	if (!getter && !setter) {
+		return null;
+	}
+
+	return (
+		<>
+			{(getter || setter) && (
+				<div className={inPanel ? 'tsd-panel-content' : ''}>
+					<ul className="tsd-signatures">
+						{getter && (
+							<li className="tsd-signature tsd-kind-icon">
+								<Icon reflection={getter} />
+								<span className="tsd-signature-symbol">get </span>
+								{getter.name}
+								<MemberSignatureTitle hideName sig={getter} />
+							</li>
+						)}
+
+						{setter && (
+							<li className="tsd-signature tsd-kind-icon">
+								<Icon reflection={setter} />
+								<span className="tsd-signature-symbol">set </span>
+								{setter.name}
+								<MemberSignatureTitle hideName sig={setter} />
+							</li>
+						)}
+					</ul>
+				</div>
+			)}
+
+			{(hasSigBody(getter, minimal) || hasSigBody(setter, minimal)) && (
+				<div className={inPanel ? 'tsd-panel-content' : ''}>
+					<ul className="tsd-descriptions">
+						{getter && (
+							<li className="tsd-description">
+								<MemberSignatureBody sig={getter} />
+							</li>
+						)}
+
+						{setter && (
+							<li className="tsd-description">
+								<MemberSignatureBody sig={setter} />
+							</li>
+						)}
+					</ul>
+				</div>
+			)}
+		</>
+	);
+}

package/src/components/MemberReference.tsx

@@ -0,0 +1,43 @@
+// https://github.com/TypeStrong/typedoc-default-themes/blob/master/src/default/partials/member.reference.hbs
+
+import React from 'react';
+import type { JSONOutput } from 'typedoc';
+import Link from '@docusaurus/Link';
+import { useReflection } from '../hooks/useReflection';
+
+export interface MemberReferenceProps {
+	reflection: JSONOutput.ReferenceReflection;
+}
+
+export function MemberReference({ reflection }: MemberReferenceProps) {
+	const target = useReflection(reflection.target);
+	let content: React.ReactNode = null;
+
+	if (!target) {
+		content = (
+			<>
+				Re-exports <span className="tsd-signature-type">{reflection.name}</span>
+			</>
+		);
+	} else if (reflection.name === target.name) {
+		content = (
+			<>
+				Re-exports{' '}
+				<Link className="tsd-signature-type" to={target.permalink}>
+					{target.name}
+				</Link>
+			</>
+		);
+	} else {
+		content = (
+			<>
+				Renames and re-exports{' '}
+				<Link className="tsd-signature-type" to={target.permalink}>
+					{target.name}
+				</Link>
+			</>
+		);
+	}
+
+	return <div className="tsd-panel-content">{content}</div>;
+}

package/src/components/MemberSignatureBody.tsx

@@ -0,0 +1,121 @@
+// https://github.com/TypeStrong/typedoc-default-themes/blob/master/src/default/partials/member.signature.body.hbs
+
+import React from 'react';
+import type { JSONOutput } from 'typedoc';
+import { useMinimalLayout } from '../hooks/useMinimalLayout';
+import { Comment, hasComment } from './Comment';
+import { CommentBadges, isCommentWithModifiers } from './CommentBadges';
+import { DefaultValue } from './DefaultValue';
+import { Flags } from './Flags';
+import { hasSources, MemberSources } from './MemberSources';
+import { Parameter } from './Parameter';
+import { Type } from './Type';
+import { TypeParameters } from './TypeParameters';
+
+export function hasSigBody(
+	sig: JSONOutput.SignatureReflection | undefined,
+	minimal: boolean,
+	hideSources: boolean = false,
+) {
+	if (!sig) {
+		return false;
+	}
+
+	return (
+		(!hideSources && hasSources(sig)) ||
+		hasComment(sig.comment) ||
+		(sig.typeParameter && sig.typeParameter.length > 0) ||
+		(!minimal && sig.parameters && sig.parameters.length > 0) ||
+		(!minimal && sig.type)
+	);
+}
+
+export interface MemberSignatureBodyProps {
+	hideSources?: boolean;
+	sig: JSONOutput.SignatureReflection;
+}
+
+function intoReturnComment(comment?: JSONOutput.Comment): JSONOutput.Comment | undefined {
+	if (comment?.blockTags) {
+		const tags = comment.blockTags.map((tag) => tag.tag);
+
+		if (tags.includes('@returns')) {
+			const index = tags.indexOf('@returns');
+
+			return {
+				summary: comment.blockTags[index].content,
+			};
+		}
+	}
+
+	return undefined;
+}
+
+const HIDE_TAGS = ['@returns', '@param'];
+
+// eslint-disable-next-line complexity
+export function MemberSignatureBody({ hideSources, sig }: MemberSignatureBodyProps) {
+	const minimal = useMinimalLayout();
+	const showTypes = sig.typeParameter && sig.typeParameter.length > 0;
+	const showParams = !minimal && sig.parameters && sig.parameters.length > 0;
+	const showReturn = !minimal && sig.type;
+
+	return (
+		<>
+			{!hideSources && <MemberSources reflection={sig} />}
+
+			{isCommentWithModifiers(sig.comment) && <CommentBadges comment={sig.comment} />}
+
+			<Comment comment={sig.comment} hideTags={HIDE_TAGS} />
+
+			{hasComment(sig.comment) && (showTypes || showParams || showReturn) && (
+				<hr className="tsd-divider" />
+			)}
+
+			{showTypes && (
+				<>
+					<h4 className="tsd-type-parameters-title">Type parameters</h4>
+					<TypeParameters params={sig.typeParameter} />
+				</>
+			)}
+
+			{showParams && (
+				<>
+					<h4 className="tsd-parameters-title">Parameters</h4>
+
+					<ul className="tsd-parameters">
+						{sig.parameters?.map((param) => (
+							<li key={param.id}>
+								<h5>
+									{param.flags?.isRest && <span className="tsd-signature-symbol">...</span>}
+									{`${param.name}: `}
+									<Type type={param.type} />
+									<DefaultValue
+										comment={param.comment}
+										type={param.type}
+										value={param.defaultValue}
+									/>
+									<Flags flags={param.flags} />
+								</h5>
+
+								<Comment comment={param.comment} />
+							</li>
+						))}
+					</ul>
+				</>
+			)}
+
+			{showReturn && (
+				<>
+					<h4 className="tsd-returns-title">
+						Returns <Type type={sig.type} />
+					</h4>
+
+					<Comment comment={intoReturnComment(sig.comment)} />
+
+					<Parameter param={sig.type?.declaration} />
+				</>
+			)}
+		</>
+	);
+}

package/src/components/MemberSignatureTitle.tsx

@@ -0,0 +1,65 @@
+/* eslint-disable no-nested-ternary */
+// https://github.com/TypeStrong/typedoc-default-themes/blob/master/src/default/partials/member.signature.title.hbs
+
+import React from 'react';
+import { JSONOutput } from 'typedoc';
+import { Type } from './Type';
+import { TypeParametersGeneric } from './TypeParametersGeneric';
+
+export interface MemberSignatureTitleProps {
+	useArrow?: boolean;
+	hideName?: boolean;
+	sig: JSONOutput.SignatureReflection & { modifiers?: string[] };
+}
+
+export function MemberSignatureTitle({ useArrow, hideName, sig }: MemberSignatureTitleProps) {
+	// add `*` before the first keyword-only parameter
+	const parametersCopy = sig.parameters?.slice() ?? [];
+	const firstKeywordOnlyIndex = parametersCopy.findIndex((param) => Object.keys(param.flags).includes('keyword-only'));
+	if (firstKeywordOnlyIndex >= 0) {
+		parametersCopy.splice(firstKeywordOnlyIndex, 0, {
+			id: 999_999,
+			name: '*',
+			kind: 32_768,
+			flags: { },
+			permalink: '',
+		});
+	}
+
+	return (
+		<>
+			{!hideName && sig.name !== '__type' ? (
+				<span>{(sig.modifiers ?? []).join(' ')}<b>{sig.name}</b></span>
+			) : sig.kindString === 'Constructor signature' ? (
+				<>
+					{sig.flags?.isAbstract && <span className="tsd-signature-symbol">abstract </span>}
+					<span className="tsd-signature-symbol">new </span>
+				</>
+			) : null}
+
+			<TypeParametersGeneric params={sig.typeParameter} />
+
+			<span className="tsd-signature-symbol">(</span>
+
+			{parametersCopy.map((param, index) => (
+				<React.Fragment key={param.id}>
+					{index > 0 && <span className="tsd-signature-symbol">, </span>}
+
+					<span>
+						{param.flags?.isRest && <span className="tsd-signature-symbol">...</span>}
+						{param.name}
+					</span>
+				</React.Fragment>
+			))}
+
+			<span className="tsd-signature-symbol">)</span>
+
+			{sig.type && (
+				<>
+					<span className="tsd-signature-symbol">{useArrow ? ' => ' : ': '}</span>
+					<Type type={sig.type} />
+				</>
+			)}
+		</>
+	);
+}