new: alpha beta experimental modifiers (#53)

* new: alpha, beta, and experimental modifiers

This adds badges to entities that are marked with stabilitity modifiers. I'm open to
suggestions on better ways of rendering this information.

* move labels around

fixtures/monorepo/standard/src/index.ts

@@ -1,10 +1,50 @@
+/**
+ * a type
+ * @beta
+ */
 export type Type = 'standard';
 
+/**
+ * newy new guy
+ * @param a a thing
+ * @param b b thing
+ * @alpha
+ */
+export function bizz(a: string, b: string): string;
+
+/**
+ * newy new guy
+ * @param a a thing
+ * @param b b thing
+ * @param c c thing
+ * @beta
+ */
+export function bizz(a: string, b: string, c: string): string;
+
 /**
  * a thing for a thing
  * @param a id
  * @returns returns the param
+ * @beta
+ */
+export function bizz(...args: string[]): string {
+	return args[0];
+}
+
+/**
+ * thing for a thing
+ * @beta
  */
-export function bizz(a: string): string {
-  return a;
-}
+export interface Foo {
+	/**
+	 * very experimental
+	 * @alpha
+	 */
+	foo: string;
+
+	/**
+	 * very experimental
+	 * @experimental
+	 */
+	a: string;
+}

packages/plugin/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>
+	);
+}

packages/plugin/src/components/Member.tsx

@@ -6,6 +6,7 @@ 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';
@@ -20,7 +21,7 @@ export interface MemberProps {
 export function Member({ id }: MemberProps) {
 	const reflections = useReflectionMap();
 	const reflection = useReflection(id)!;
-
+	const { comment } = reflection;
 	let content: React.ReactNode = null;
 
 	if (reflection.signatures) {
@@ -46,6 +47,7 @@ export function Member({ id }: MemberProps) {
 				<SourceLink sources={reflection.sources} />
 				<Flags flags={reflection.flags} />
 				{reflection.name}
+				{isCommentWithModifiers(comment) && <CommentBadges comment={comment} />}
 			</h3>
 
 			{content}

packages/plugin/src/components/MemberSignatureBody.tsx

@@ -4,6 +4,7 @@ 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';
@@ -34,11 +35,11 @@ export interface MemberSignatureBodyProps {
 	sig: JSONOutput.SignatureReflection;
 }
 
-function excludeBlockTags(comment?: JSONOutput.Comment):  JSONOutput.Comment | undefined {
+function excludeBlockTags(comment?: JSONOutput.Comment): JSONOutput.Comment | undefined {
 	if (comment) {
 		const { blockTags, ...rest } = comment;
 		return rest;
- 	}
+	}
 	return undefined;
 }
 
@@ -50,8 +51,8 @@ function intoReturnComment(comment?: JSONOutput.Comment): JSONOutput.Comment | u
 			const index = tags.indexOf('@returns');
 
 			return {
-				summary: comment.blockTags[index].content
-			}
+				summary: comment.blockTags[index].content,
+			};
 		}
 	}
 
@@ -69,6 +70,8 @@ export function MemberSignatureBody({ hideSources, sig }: MemberSignatureBodyPro
 		<>
 			{!hideSources && <MemberSources reflection={sig} />}
 
+			{isCommentWithModifiers(sig.comment) && <CommentBadges comment={sig.comment} />}
+
 			<Comment comment={excludeBlockTags(sig.comment)} />
 
 			{hasComment(sig.comment) && (showTypes || showParams || showReturn) && (

packages/plugin/src/components/Reflection.tsx

@@ -4,6 +4,7 @@ import React, { useMemo } from 'react';
 import type { JSONOutput } from 'typedoc';
 import { createHierarchy } from '../utils/hierarchy';
 import { Comment, hasComment } from './Comment';
+import { CommentBadges, isCommentWithModifiers } from './CommentBadges';
 import { Hierarchy } from './Hierarchy';
 import { Icon } from './Icon';
 import { Index } from './Index';
@@ -19,13 +20,13 @@ export interface ReflectionProps {
 		| JSONOutput.Reflection
 		| JSONOutput.SignatureReflection;
 }
-
 // eslint-disable-next-line complexity
 export function Reflection({ reflection }: ReflectionProps) {
 	const hierarchy = useMemo(() => createHierarchy(reflection), [reflection]);
 
 	return (
 		<>
+			{isCommentWithModifiers(reflection.comment) && <CommentBadges comment={reflection.comment} />}
 			{hasComment(reflection.comment) && <Comment root comment={reflection.comment} />}
 
 			{'typeParameter' in reflection &&

packages/plugin/src/components/styles.css

@@ -204,6 +204,23 @@ html[data-theme='light'] .tsd-panel-content {
 	vertical-align: middle;
 }
 
+/* MODIFIERS */
+
+.badge-group {
+	font-size: var(--tsd-font-small);
+	vertical-align: middle;
+}
+
+.tsd-panel-header .badge-group {
+	display: inline-block;
+	margin-left: .25em;
+}
+
+.badge-group > span {
+	margin-right: 0.25rem;
+}
+
+
 /* SYNTAX */
 
 .tsd-generics {