@apify/docusaurus-plugin-typedoc-api 3.0.0

package/src/components/ApiItemLayout.tsx

@@ -0,0 +1,96 @@
+// This file is based on `DocItem` upstream, but since we aren't using markdown,
+// we had to duplicate it. Keep this file in sync as much as possible!
+// https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-theme-classic/src/theme/DocItem/index.tsx
+
+import React from 'react';
+import type { PropNavigation } from '@docusaurus/plugin-content-docs';
+import { ThemeClassNames, useWindowSize } from '@docusaurus/theme-common';
+import DocBreadcrumbs from '@theme/DocBreadcrumbs';
+import type { Props as DocItemProps } from '@theme/DocItem';
+import DocPaginator from '@theme/DocPaginator';
+import DocVersionBadge from '@theme/DocVersionBadge';
+import Heading from '@theme/Heading';
+import MDXContent from '@theme/MDXContent';
+import TOC from '@theme/TOC';
+import TOCCollapsible from '@theme/TOCCollapsible';
+import { useBreadcrumbs } from '../hooks/useBreadcrumbs';
+import type { TOCItem } from '../types';
+import { VersionBanner } from './VersionBanner';
+
+export interface ApiItemLayoutProps extends Pick<DocItemProps, 'route'> {
+	children: React.ReactNode;
+	heading: React.ReactNode;
+	toc: readonly TOCItem[];
+	pageMetadata?: React.ReactNode;
+	pagingMetadata?: PropNavigation;
+	name: string;
+	module?: string;
+}
+
+export default function ApiItemLayout({
+	children,
+	heading,
+	pageMetadata,
+	pagingMetadata,
+	toc,
+	name,
+	module,
+}: ApiItemLayoutProps) {
+	const windowSize = useWindowSize();
+	const breadcrumbs = useBreadcrumbs();
+
+	// Table of contents
+	const canRenderTOC = toc.length > 0;
+	const renderTocDesktop = canRenderTOC && (windowSize === 'desktop' || windowSize === 'ssr');
+
+	return (
+		<>
+			{pageMetadata}
+
+			<div className="row">
+				<div className="col apiItemCol">
+					<VersionBanner />
+
+					<div className="apiItemContainer">
+						<article>
+							{breadcrumbs && <DocBreadcrumbs />}
+
+							<DocVersionBadge />
+
+							{canRenderTOC && (
+								<TOCCollapsible
+									className={`${ThemeClassNames.docs.docTocMobile ?? ''} apiTocMobile`}
+									maxHeadingLevel={6}
+									minHeadingLevel={1}
+									toc={toc}
+								/>
+							)}
+
+							<div className={`${ThemeClassNames.docs.docMarkdown ?? ''} markdown`}>
+								<header>
+									<Heading as="h1">{heading}</Heading>
+									{module && <code className="tsd-header-member-fullname">{`${module}.${name}`}</code>}
+								</header>
+
+								<MDXContent>{children}</MDXContent>
+							</div>
+						</article>
+
+						{pagingMetadata && <DocPaginator {...pagingMetadata} />}
+					</div>
+				</div>
+
+				{renderTocDesktop && (
+					<div className="col col--3">
+						<TOC
+							className={ThemeClassNames.docs.docTocDesktop}
+							maxHeadingLevel={6}
+							minHeadingLevel={1}
+							toc={toc}
+						/>
+					</div>
+				)}
+			</div>
+		</>
+	);
+}

package/src/components/ApiPage.tsx

@@ -0,0 +1,78 @@
+/* eslint-disable no-param-reassign */
+
+import '@vscode/codicons/dist/codicon.css';
+import './styles.css';
+import React, { useMemo } from 'react';
+import type { JSONOutput } from 'typedoc';
+import DocPage, { type Props as DocPageProps } from '@theme/DocPage';
+import type { ApiOptions, DeclarationReflectionMap, PackageReflectionGroup } from '../types';
+import { ApiDataContext } from './ApiDataContext';
+
+function isObject(value: unknown): value is JSONOutput.Reflection {
+	return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function deepMapReflections(
+	data: JSONOutput.Reflection,
+	map: DeclarationReflectionMap,
+	parent?: JSONOutput.Reflection,
+) {
+	Object.entries(data).forEach(([key, value]) => {
+		if (key === 'id') {
+			const hasType = 'type' in data;
+
+			// Dont overwrite with reference nodes
+			if (!hasType || (hasType && (data as unknown as { type: string }).type !== 'reference')) {
+				map[Number(value)] = data;
+
+				if (parent) {
+					data.parentId = parent.id;
+				}
+			}
+		} else if (Array.isArray(value)) {
+			value.forEach((val) => {
+				if (isObject(val)) {
+					deepMapReflections(val, map, data);
+				}
+			});
+		} else if (isObject(value)) {
+			deepMapReflections(value, map, data);
+		}
+	});
+
+	return map;
+}
+
+function mapPackagesToReflection(packages: PackageReflectionGroup[]): DeclarationReflectionMap {
+	const map: DeclarationReflectionMap = {};
+
+	packages.forEach((pkg) => {
+		pkg.entryPoints.forEach((entry) => {
+			deepMapReflections(entry.reflection, map);
+		});
+	});
+
+	return map;
+}
+
+export interface ApiPageProps extends DocPageProps {
+	options: ApiOptions;
+	packages: PackageReflectionGroup[];
+}
+
+function ApiPage({ options, packages, ...props }: ApiPageProps) {
+	const value = useMemo(
+		() => ({ options, reflections: mapPackagesToReflection(packages) }),
+		[options, packages],
+	);
+
+	return (
+		<ApiDataContext.Provider value={value}>
+			<div className="apiPage">
+				<DocPage {...props} />
+			</div>
+		</ApiDataContext.Provider>
+	);
+}
+
+export default ApiPage;

package/src/components/Breadcrumb.tsx

@@ -0,0 +1,41 @@
+// https://github.com/TypeStrong/typedoc-default-themes/blob/master/src/default/partials/breadcrumb.hbs
+
+import React from 'react';
+import type { JSONOutput } from 'typedoc';
+import Link from '@docusaurus/Link';
+import { useReflection } from '../hooks/useReflection';
+
+export interface BreadcrumbProps {
+	reflection: JSONOutput.Reflection;
+	root?: boolean;
+}
+
+export function Breadcrumb({ reflection, root = true }: BreadcrumbProps) {
+	const parent = useReflection(reflection.parentId);
+	let content: React.ReactNode = null;
+
+	if (parent) {
+		content = (
+			<>
+				<Breadcrumb reflection={parent} root={false} />
+				<li>
+					{reflection.permalink ? (
+						<Link to={reflection.permalink}>{reflection.name}</Link>
+					) : (
+						<span>{reflection.name}</span>
+					)}
+				</li>
+			</>
+		);
+	} else if (reflection.permalink) {
+		content = (
+			<li>
+				<Link to={reflection.permalink}>{reflection.name}</Link>
+			</li>
+		);
+	} else {
+		return null;
+	}
+
+	return root ? <ul className="tsd-breadcrumb">{content}</ul> : <>{content}</>;
+}

package/src/components/Comment.tsx

@@ -0,0 +1,74 @@
+// https://github.com/TypeStrong/typedoc-default-themes/blob/master/src/default/partials/comment.hbs
+
+import React from 'react';
+import type { JSONOutput } from 'typedoc';
+import { Markdown } from './Markdown';
+
+export interface CommentProps {
+	comment?: JSONOutput.Comment;
+	root?: boolean;
+	hideTags?: string[];
+}
+
+export function hasComment(comment?: JSONOutput.Comment): boolean {
+	if (!comment) {
+		return false;
+	}
+
+	return Boolean(
+		comment.summary?.some((x) => x.kind !== 'text' || x.text !== '') ||
+			(comment.blockTags && comment.blockTags?.length > 0),
+	);
+}
+
+export function displayPartsToMarkdown(parts: JSONOutput.CommentDisplayPart[]): string {
+	return parts
+		.map((part) => {
+			if (part.kind === 'inline-tag') {
+				return `{${part.tag} ${part.text}}`;
+			}
+
+			return part.text;
+		})
+		.join('');
+}
+
+export function Comment({ comment, root, hideTags = [] }: CommentProps) {
+	if (!comment || !hasComment(comment)) {
+		return null;
+	}
+
+	const blockTags =
+		comment.blockTags?.filter((tag) => {
+			if (hideTags.includes(tag.tag)) {
+				return false;
+			}
+
+			return tag.tag !== '@default';
+		}) ?? [];
+
+	return (
+		<div className={`tsd-comment tsd-typography ${root ? 'tsd-comment-root' : ''}`}>
+			{!!comment.summary && (
+				<div className="lead">
+					<Markdown content={displayPartsToMarkdown(comment.summary)} />
+				</div>
+			)}
+
+			{blockTags.length > 0 && (
+				<dl className="tsd-comment-tags">
+					{blockTags.map((tag) => (
+						<React.Fragment key={tag.tag}>
+							<dt>
+								<strong>{tag.tag}</strong>
+							</dt>
+							<dd>
+								<Markdown content={displayPartsToMarkdown(tag.content)} />
+							</dd>
+						</React.Fragment>
+					))}
+				</dl>
+			)}
+		</div>
+	);
+}

package/src/components/CommentBadges.tsx

@@ -0,0 +1,40 @@
+import React from 'react';
+import { JSONOutput } from 'typedoc';
+
+function getModifierClassName(tag: string) {
+	switch (tag) {
+		case '@beta':
+		case '@experimental':
+			return 'warning';
+		case '@alpha':
+			return 'danger';
+		default:
+			return 'info';
+	}
+}
+
+export type CommentWithModifiers = Pick<JSONOutput.Comment, 'blockTags' | 'summary'> &
+	Required<Pick<JSONOutput.Comment, 'modifierTags'>>;
+
+export function isCommentWithModifiers(
+	comment?: JSONOutput.Comment,
+): comment is CommentWithModifiers {
+	return !!comment && !!comment.modifierTags && comment.modifierTags.length > 0;
+}
+
+interface CommentBadgesProps {
+	comment: CommentWithModifiers;
+}
+
+export function CommentBadges({ comment }: CommentBadgesProps) {
+	const { modifierTags } = comment;
+	return (
+		<div className="badge-group">
+			{modifierTags.map((tag) => (
+				<span key={tag} className={`badge badge--${getModifierClassName(tag)}`}>
+					{tag.slice(1)}
+				</span>
+			))}
+		</div>
+	);
+}

package/src/components/DefaultValue.tsx

@@ -0,0 +1,48 @@
+/* eslint-disable react-perf/jsx-no-new-object-as-prop */
+
+import React from 'react';
+import type { JSONOutput } from 'typedoc';
+import { displayPartsToMarkdown } from './Comment';
+import { Type } from './Type';
+
+export interface DefaultValueProps {
+	comment?: JSONOutput.Comment;
+	type?: { type: string };
+	value?: JSONOutput.SomeType | string;
+}
+
+function extractDefaultTag(comment?: JSONOutput.Comment): string | null {
+	const tag = comment?.blockTags?.find((tag) => tag.tag === '@default');
+
+	if (!tag) {
+		return null;
+	}
+
+	return displayPartsToMarkdown(tag.content);
+}
+
+export function DefaultValue({ comment, value, type }: DefaultValueProps) {
+	if (!comment && !value) {
+		return null;
+	}
+
+	const defaultTag = extractDefaultTag(comment);
+
+	if (!defaultTag && !value) {
+		return null;
+	}
+
+	return (
+		<span className="tsd-signature-symbol tsd-signature-default-value">
+			{' = '}
+
+			{value && <>{typeof value === 'string' ? value : <Type type={value} />}</>}
+
+			{!value && defaultTag && (
+				<Type
+					type={{ type: 'literal', ...(type?.type === 'intrinsic' ? {} : type), value: defaultTag }}
+				/>
+			)}
+		</span>
+	);
+}

package/src/components/Flags.tsx

@@ -0,0 +1,29 @@
+// https://github.com/TypeStrong/typedoc-default-themes/blob/master/src/default/partials/comment.hbs
+import React from 'react';
+import type { JSONOutput } from 'typedoc';
+
+function removePrefix(value: string) {
+	return value.replace(/^is([A-Z])/, (match, char) => String(char).toLocaleLowerCase());
+}
+
+export interface FlagsProps {
+	flags?: JSONOutput.ReflectionFlags;
+}
+
+export function Flags({ flags }: FlagsProps) {
+	if (!flags) {
+		return null;
+	}
+
+	return (
+		<span className='tsd-flag-group'>
+			{Object.keys(flags)
+				.map(removePrefix)
+				.map((flag) => (
+					<span key={flag} className={`tsd-flag tsd-flag-${flag}`}>
+						{flag}
+					</span>
+				))}
+		</span>
+	);
+}

package/src/components/Footer.tsx

@@ -0,0 +1,13 @@
+import React from 'react';
+
+export function Footer() {
+	return (
+		<footer className="tsd-footer">
+			Powered by{' '}
+			<a href="https://github.com/milesj/docusaurus-plugin-typedoc-api">
+				docusaurus-plugin-typedoc-api
+			</a>{' '}
+			and <a href="https://typedoc.org/">TypeDoc</a>
+		</footer>
+	);
+}

package/src/components/Hierarchy.tsx

@@ -0,0 +1,27 @@
+// https://github.com/TypeStrong/typedoc-default-themes/blob/master/src/default/partials/hierarchy.hbs
+
+import React from 'react';
+import type { HierarchyNode } from '../utils/hierarchy';
+import { Type } from './Type';
+
+export interface HierarchyProps {
+	tree: HierarchyNode;
+}
+
+export function Hierarchy({ tree }: HierarchyProps) {
+	return (
+		<ul className="tsd-hierarchy">
+			{tree.types.map((type, i) => (
+				<li key={type.type + String(i)}>
+					{tree.isTarget ? (
+						<em className="tsd-target">{type.type === 'reference' ? type.name : 'UNKNOWN'}</em>
+					) : (
+						<Type type={type} />
+					)}
+
+					{i === tree.types.length - 1 && tree.next && <Hierarchy tree={tree.next} />}
+				</li>
+			))}
+		</ul>
+	);
+}

package/src/components/Icon.tsx

@@ -0,0 +1,20 @@
+import React from 'react';
+import type { JSONOutput } from 'typedoc';
+import { getKindIcon, getKindIconColor } from '../utils/icons';
+
+export interface IconProps {
+	reflection: JSONOutput.DeclarationReflection;
+}
+
+export function Icon({ reflection }: IconProps) {
+	const icon = getKindIcon(reflection.kind, reflection.name);
+
+	if (!icon) {
+		return null;
+	}
+
+	const color = getKindIconColor(reflection.kind);
+
+	// eslint-disable-next-line react-perf/jsx-no-new-object-as-prop
+	return <i className={`codicon codicon-${icon}`} style={{ color }} />;
+}

package/src/components/Index.tsx

@@ -0,0 +1,109 @@
+import React from 'react';
+import type { JSONOutput } from 'typedoc';
+import Link from '@docusaurus/Link';
+import { useReflection } from '../hooks/useReflection';
+import { AnchorLink } from './AnchorLink';
+import { Icon } from './Icon';
+
+export interface IndexChildProps {
+	id: number;
+}
+
+function IndexChild({ id }: IndexChildProps) {
+	const reflection = useReflection(id)!;
+
+	return (
+		<li>
+			<Link className="tsd-kind-icon" to={reflection.permalink ?? `#${reflection.name}`}>
+				<Icon reflection={reflection} />
+				{reflection.name ?? <em>{reflection.kindString}</em>}
+			</Link>
+		</li>
+	);
+}
+
+export interface IndexProps {
+	reflection: JSONOutput.DeclarationReflection;
+}
+
+export function Index({ reflection }: IndexProps) {
+	if (reflection.categories && reflection.categories.length > 0) {
+		return (
+			<section className="tsd-panel-group tsd-index-group">
+				<h2>
+					Index <AnchorLink id="Index" />
+				</h2>
+
+				<section className="tsd-panel tsd-index-panel">
+					<div className="tsd-index-content">
+						{reflection.categories.map((category) => (
+							<section key={category.title} className="tsd-index-section">
+								<h3 className="tsd-panel-header">
+									{category.title === 'CATEGORY' ? 'Other' : category.title}
+								</h3>
+
+								<div className="tsd-panel-content">
+									<ul className="tsd-index-list">
+										{category.children?.map((child) => (
+											<IndexChild key={child} id={child} />
+										))}
+									</ul>
+								</div>
+							</section>
+						))}
+					</div>
+				</section>
+			</section>
+		);
+	}
+
+	if (reflection.groups && reflection.groups.length > 0) {
+		return (
+			<section className="tsd-panel-group tsd-index-group">
+				<h2>
+					Index <AnchorLink id="Index" />
+				</h2>
+
+				<section className="tsd-panel tsd-index-panel">
+					<div className="tsd-index-content">
+						{reflection.groups.map((group) => (
+							<section key={group.title} className="tsd-index-section">
+								{group.categories && group.categories.length > 0 ? (
+									group.categories.map((category) => (
+										<React.Fragment key={category.title}>
+											<h3 className="tsd-panel-header">
+												{category.title === 'CATEGORY' ? group.title : category.title}
+											</h3>
+
+											<div className="tsd-panel-content">
+												<ul className="tsd-index-list">
+													{category.children?.map((child) => (
+														<IndexChild key={child} id={child} />
+													))}
+												</ul>
+											</div>
+										</React.Fragment>
+									))
+								) : (
+									<>
+										<h3 className="tsd-panel-header">{group.title}</h3>
+
+										<div className="tsd-panel-content">
+											<ul className="tsd-index-list">
+												{group.children?.map((child) => (
+													<IndexChild key={child} id={child} />
+												))}
+											</ul>
+										</div>
+									</>
+								)}
+							</section>
+						))}
+					</div>
+				</section>
+			</section>
+		);
+	}
+
+	return null;
+}