feat(website): parse and show unstable tsdoc tag (#11187)

feat(website): parse and show unstable tsDoc tag

apps/website/src/components/Badges.tsx

@@ -13,6 +13,7 @@ export function Badge({ children, className = '' }: PropsWithChildren<{ readonly
 
 export async function Badges({ node }: { readonly node: any }) {
 	const isDeprecated = Boolean(node.summary?.deprecatedBlock?.length);
+	const isUnstable = Boolean(node.summary?.unstableBlock?.length);
 	const isProtected = node.isProtected;
 	const isStatic = node.isStatic;
 	const isAbstract = node.isAbstract;
@@ -20,8 +21,9 @@ export async function Badges({ node }: { readonly node: any }) {
 	const isOptional = node.isOptional;
 	const isExternal = node.isExternal;
 
-	// eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+	const isAny =
-	const isAny = isDeprecated || isProtected || isStatic || isAbstract || isReadonly || isOptional || isExternal;
+		// eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing
+		isDeprecated || isUnstable || isProtected || isStatic || isAbstract || isReadonly || isOptional || isExternal;
 
 	return isAny ? (
 		<div className="mb-1 flex flex-wrap gap-3">
@@ -30,6 +32,11 @@ export async function Badges({ node }: { readonly node: any }) {
 					<AlertTriangle aria-hidden size={14} /> deprecated
 				</Badge>
 			) : null}
+			{isUnstable ? (
+				<Badge className="bg-red-500/20 text-red-500">
+					<AlertTriangle aria-hidden size={14} /> unstable
+				</Badge>
+			) : null}
 			{isProtected ? <Badge className="bg-purple-500/20 text-purple-500">protected</Badge> : null}
 			{isStatic ? <Badge className="bg-purple-500/20 text-purple-500">static</Badge> : null}
 			{isAbstract ? <Badge className="bg-cyan-500/20 text-cyan-500">abstract</Badge> : null}

apps/website/src/components/DocItem.tsx

@@ -15,6 +15,7 @@ import { SummaryNode } from './SummaryNode';
 import { SyntaxHighlighter } from './SyntaxHighlighter';
 import { TypeParameterNode } from './TypeParameterNode';
 import { UnionMember } from './UnionMember';
+import { UnstableNode } from './UnstableNode';
 import { Tab, TabList, TabPanel, Tabs } from './ui/Tabs';
 
 async function OverloadNode({
@@ -81,6 +82,10 @@ export async function DocItem({
 				<DeprecatedNode deprecatedBlock={node.summary.deprecatedBlock} version={version} />
 			) : null}
 
+			{node.summary?.unstableBlock.length ? (
+				<UnstableNode unstableBlock={node.summary.unstableBlock} version={version} />
+			) : null}
+
 			{node.summary?.summarySection ? <SummaryNode node={node.summary.summarySection} version={version} /> : null}
 
 			{node.summary?.returnsBlock.length ? <ReturnNode node={node.summary.returnsBlock} version={version} /> : null}

apps/website/src/components/EnumMemberNode.tsx

@@ -12,6 +12,7 @@ import { ParameterNode } from './ParameterNode';
 import { ReturnNode } from './ReturnNode';
 import { SeeNode } from './SeeNode';
 import { SummaryNode } from './SummaryNode';
+import { UnstableNode } from './UnstableNode';
 
 export async function EnumMemberNode({
 	node,
@@ -80,6 +81,10 @@ export async function EnumMemberNode({
 								<DeprecatedNode deprecatedBlock={enumMember.summary.deprecatedBlock} version={version} />
 							) : null}
 
+							{enumMember.summary?.unstableBlock.length ? (
+								<UnstableNode unstableBlock={enumMember.summary.unstableBlock} version={version} />
+							) : null}
+
 							{enumMember.summary?.summarySection.length ? (
 								<SummaryNode node={enumMember.summary.summarySection} padding version={version} />
 							) : null}

apps/website/src/components/EventNode.tsx

@@ -11,6 +11,7 @@ import { ReturnNode } from './ReturnNode';
 import { SeeNode } from './SeeNode';
 import { SummaryNode } from './SummaryNode';
 import { TypeParameterNode } from './TypeParameterNode';
+import { UnstableNode } from './UnstableNode';
 import { Collapsible, CollapsibleContent, CollapsibleTrigger } from './ui/Collapsible';
 import { Tab, TabList, TabPanel, Tabs } from './ui/Tabs';
 
@@ -68,6 +69,10 @@ async function EventBodyNode({
 					<DeprecatedNode deprecatedBlock={event.summary.deprecatedBlock} version={version} />
 				) : null}
 
+				{event.summary?.unstableBlock.length ? (
+					<UnstableNode unstableBlock={event.summary.unstableBlock} version={version} />
+				) : null}
+
 				{event.summary?.summarySection.length ? (
 					<SummaryNode node={event.summary.summarySection} padding version={version} />
 				) : null}

apps/website/src/components/MethodNode.tsx

@@ -12,6 +12,7 @@ import { ReturnNode } from './ReturnNode';
 import { SeeNode } from './SeeNode';
 import { SummaryNode } from './SummaryNode';
 import { TypeParameterNode } from './TypeParameterNode';
+import { UnstableNode } from './UnstableNode';
 import { Collapsible, CollapsibleContent, CollapsibleTrigger } from './ui/Collapsible';
 import { Tab, TabList, TabPanel, Tabs } from './ui/Tabs';
 
@@ -70,6 +71,10 @@ async function MethodBodyNode({
 					<DeprecatedNode deprecatedBlock={method.summary.deprecatedBlock} version={version} />
 				) : null}
 
+				{method.summary?.unstableBlock.length ? (
+					<UnstableNode unstableBlock={method.summary.unstableBlock} version={version} />
+				) : null}
+
 				{method.summary?.summarySection.length ? (
 					<SummaryNode node={method.summary.summarySection} padding version={version} />
 				) : null}

apps/website/src/components/PropertyNode.tsx

@@ -9,6 +9,7 @@ import { ExcerptNode } from './ExcerptNode';
 import { InheritedFromNode } from './InheritedFromNode';
 import { SeeNode } from './SeeNode';
 import { SummaryNode } from './SummaryNode';
+import { UnstableNode } from './UnstableNode';
 import { Collapsible, CollapsibleContent, CollapsibleTrigger } from './ui/Collapsible';
 
 export async function PropertyNode({
@@ -79,6 +80,10 @@ export async function PropertyNode({
 									<DeprecatedNode deprecatedBlock={property.summary.deprecatedBlock} version={version} />
 								) : null}
 
+								{property.summary?.unstableBlock.length ? (
+									<UnstableNode unstableBlock={property.summary.unstableBlock} version={version} />
+								) : null}
+
 								{property.summary?.summarySection.length ? (
 									<SummaryNode node={property.summary.summarySection} padding version={version} />
 								) : null}

apps/website/src/components/UnstableNode.tsx

@@ -0,0 +1,18 @@
+import { DocNode } from './DocNode';
+import { Alert } from './ui/Alert';
+
+export async function UnstableNode({
+	unstableBlock,
+	version,
+}: {
+	readonly unstableBlock: any;
+	readonly version: string;
+}) {
+	return (
+		<Alert title="Unstable" type="danger">
+			<p className="break-words">
+				<DocNode node={unstableBlock} version={version} />
+			</p>
+		</Alert>
+	);
+}

packages/scripts/src/generateSplitDocumentation.ts

@@ -413,6 +413,8 @@ function itemTsDoc(item: DocNode, apiItem: ApiItem) {
 					(block) => block.blockTag.tagNameWithUpperCase === StandardTags.defaultValue.tagNameWithUpperCase,
 				);
 
+				const unstableBlock = comment.customBlocks.find((block) => block.blockTag.tagNameWithUpperCase === '@UNSTABLE');
+
 				const mixesBlocks = comment.customBlocks.filter((block) => block.blockTag.tagNameWithUpperCase === '@MIXES');
 
 				return {
@@ -442,6 +444,11 @@ function itemTsDoc(item: DocNode, apiItem: ApiItem) {
 								.flat(1)
 								.filter((val: any) => val.kind !== DocNodeKind.SoftBreak)
 						: [],
+					unstableBlock: unstableBlock
+						? createNode(unstableBlock.content)
+								.flat(1)
+								.filter((val: any) => val.kind !== DocNodeKind.SoftBreak)
+						: [],
 					exampleBlocks: exampleBlocks
 						.flatMap((block) => createNode(block.content).flat(1))
 						.filter((val: any) => val.kind !== DocNodeKind.SoftBreak),