feat(website): render @deprecated and @remarks blocks (#8511)

packages/website/src/DocModel/DocItem.ts

@@ -17,6 +17,7 @@ export class DocItem<T extends ApiDeclaredItem = ApiDeclaredItem> {
 	public readonly kind: string;
 	public readonly remarks: DocNodeContainerJSON | null;
 	public readonly summary: DocNodeContainerJSON | null;
+	public readonly deprecated: DocNodeContainerJSON | null;
 	public readonly containerKey: string;
 	public readonly comment: AnyDocNodeJSON | null;
 
@@ -34,6 +35,9 @@ export class DocItem<T extends ApiDeclaredItem = ApiDeclaredItem> {
 		this.summary = item.tsdocComment?.summarySection
 			? (createCommentNode(item.tsdocComment.summarySection, model, item.parent) as DocNodeContainerJSON)
 			: null;
+		this.deprecated = item.tsdocComment?.deprecatedBlock
+			? (createCommentNode(item.tsdocComment.deprecatedBlock, model, item.parent) as DocNodeContainerJSON)
+			: null;
 		this.containerKey = item.containerKey;
 		this.comment = item.tsdocComment ? createCommentNode(item.tsdocComment, model, item.parent) : null;
 	}
@@ -63,6 +67,7 @@ export class DocItem<T extends ApiDeclaredItem = ApiDeclaredItem> {
 			excerptTokens: this.excerptTokens,
 			kind: this.kind,
 			remarks: this.remarks,
+			deprecated: this.deprecated,
 			path: this.path,
 			containerKey: this.containerKey,
 			comment: this.comment,

packages/website/src/DocModel/comment/RootComment.ts

@@ -7,6 +7,7 @@ import { DocNodeJSON, node } from './CommentNode';
 export interface DocCommentJSON extends DocNodeJSON {
 	summary: DocNodeJSON[];
 	remarks: DocNodeJSON[];
+	deprecated: DocNodeJSON[];
 	customBlocks: DocBlockJSON[];
 }
 
@@ -15,6 +16,7 @@ export function comment(comment: DocComment, model: ApiModel, parentItem?: ApiIt
 		...node(comment),
 		summary: comment.summarySection.nodes.map((node) => createCommentNode(node, model, parentItem)),
 		remarks: comment.remarksBlock?.content.nodes.map((node) => createCommentNode(node, model, parentItem)) ?? [],
+		deprecated: comment.deprecatedBlock?.content.nodes.map((node) => createCommentNode(node, model, parentItem)) ?? [],
 		customBlocks: comment.customBlocks.map((_block) => block(_block, model, parentItem)),
 	};
 }

packages/website/src/components/CodeListing.tsx

@@ -18,8 +18,9 @@ export function CodeListing({
 	readonly = false,
 	optional = false,
 	summary,
-	comment,
 	children,
+	comment,
+	deprecation,
 }: {
 	name: string;
 	separator?: CodeListingSeparatorType;
@@ -29,6 +30,7 @@ export function CodeListing({
 	summary?: ReturnType<DocItem['toJSON']>['summary'];
 	comment?: AnyDocNodeJSON | null;
 	children?: ReactNode;
+	deprecation?: AnyDocNodeJSON | null;
 }) {
 	return (
 		<Stack spacing="xs" key={name}>
@@ -44,9 +46,12 @@ export function CodeListing({
 				</Title>
 			</Group>
 			<Group>
-				{summary && <TSDoc node={summary} />}
+				<Stack>
-				{comment && <TSDoc node={comment} />}
+					{deprecation ? <TSDoc node={deprecation} /> : null}
-				{children}
+					{summary && <TSDoc node={summary} />}
+					{comment && <TSDoc node={comment} />}
+					{children}
+				</Stack>
 			</Group>
 		</Stack>
 	);

packages/website/src/components/MethodItem.tsx

@@ -43,9 +43,13 @@ export function MethodItem({ data }: { data: MethodResolvable }) {
 				</Stack>
 			</Group>
 			<Group sx={{ display: data.summary || data.parameters.length ? 'block' : 'none' }} mb="lg">
-				{data.summary ? <TSDoc node={data.summary} /> : null}
+				<Stack>
-				{data.comment ? <TSDoc node={data.comment} /> : null}
+					{data.deprecated ? <TSDoc node={data.deprecated} /> : null}
-				{data.parameters.length ? <ParameterTable data={data.parameters} /> : null}
+					{data.summary ? <TSDoc node={data.summary} /> : null}
+					{data.remarks ? <TSDoc node={data.remarks} /> : null}
+					{data.comment ? <TSDoc node={data.comment} /> : null}
+					{data.parameters.length ? <ParameterTable data={data.parameters} /> : null}
+				</Stack>
 			</Group>
 		</Stack>
 	);

packages/website/src/components/PropertyList.tsx

@@ -14,6 +14,7 @@ export function PropertyList({ data }: { data: ReturnType<DocProperty['toJSON']>
 					optional={prop.optional}
 					summary={prop.summary}
 					comment={prop.comment}
+					deprecation={prop.deprecated}
 				/>
 			))}
 		</Stack>

packages/website/src/components/tsdoc/BlockComment.tsx

@@ -1,5 +1,7 @@
+import { Alert } from '@mantine/core';
 import { StandardTags } from '@microsoft/tsdoc';
 import type { ReactNode } from 'react';
+import { VscWarning } from 'react-icons/vsc';
 
 export interface BlockProps {
 	children: ReactNode;
@@ -30,10 +32,26 @@ export function ExampleBlock({ children, exampleIndex }: ExampleBlockProps): JSX
 	return <Block title={`Example ${exampleIndex ? exampleIndex : ''}`}>{children}</Block>;
 }
 
+export function DeprecatedBlock({ children }: { children: ReactNode }): JSX.Element {
+	return (
+		<Alert icon={<VscWarning />} title="Deprecated" color="red" radius="xs">
+			{children}
+		</Alert>
+	);
+}
+
+export function RemarksBlock({ children }: { children: ReactNode }): JSX.Element {
+	return <Block title="Remarks">{children}</Block>;
+}
+
 export function BlockComment({ children, tagName, index }: BlockCommentProps): JSX.Element {
 	switch (tagName.toUpperCase()) {
 		case StandardTags.example.tagNameWithUpperCase:
 			return <ExampleBlock exampleIndex={index}>{children}</ExampleBlock>;
+		case StandardTags.deprecated.tagNameWithUpperCase:
+			return <DeprecatedBlock>{children}</DeprecatedBlock>;
+		case StandardTags.remarks.tagNameWithUpperCase:
+			return <RemarksBlock>{children}</RemarksBlock>;
 		default: // TODO: Support more blocks in the future.
 			return <></>;
 	}

packages/website/src/components/tsdoc/TSDoc.tsx

@@ -32,7 +32,7 @@ export function TSDoc({ node }: { node: AnyDocNodeJSON }): JSX.Element {
 					</Text>
 				);
 			case DocNodeKind.SoftBreak:
-				return <br key={idx} />;
+				return <></>;
 			case DocNodeKind.LinkTag: {
 				const { codeDestination, urlDestination, text } = node as DocLinkTagJSON;