feat(website): add extends clauses, enum members and automatic -types links (#8270)

* feat(website): add extends clauses, enum members and automatic -types links

* chore: remove vscode settings

* refactor: remove util file

packages/website/src/DocModel/DocEnum.ts

@@ -1,8 +1,11 @@
 import type { ApiEnum, ApiModel } from '@microsoft/api-extractor-model';
 import { DocItem } from './DocItem';
+import { genToken, resolveDocComment, TokenDocumentation } from '~/util/parse.server';
 
 export interface EnumMemberData {
 	name: string;
+	initializerTokens: TokenDocumentation[];
+	summary: string | null;
 }
 
 export class DocEnum extends DocItem<ApiEnum> {
@@ -13,6 +16,8 @@ export class DocEnum extends DocItem<ApiEnum> {
 
 		this.members = item.members.map((member) => ({
 			name: member.name,
+			initializerTokens: member.initializerExcerpt?.spannedTokens.map((token) => genToken(this.model, token)) ?? [],
+			summary: resolveDocComment(member),
 		}));
 	}
 

packages/website/src/components/CodeListing.tsx

@@ -0,0 +1,42 @@
+import type { ReactNode } from 'react';
+import { HyperlinkedText } from './HyperlinkedText';
+import type { TokenDocumentation } from '~/util/parse.server';
+
+export enum CodeListingSeparatorType {
+	Type = ':',
+	Value = '=',
+}
+
+export interface CodeListingProps {
+	name: string;
+	summary?: string | null;
+	typeTokens: TokenDocumentation[];
+	separator?: CodeListingSeparatorType;
+	children?: ReactNode;
+	className?: string | undefined;
+}
+
+export function CodeListing({
+	name,
+	className,
+	separator = CodeListingSeparatorType.Type,
+	summary,
+	typeTokens,
+	children,
+}: CodeListingProps) {
+	return (
+		<div className={className}>
+			<div key={name} className="flex flex-col mb-2 ml-3">
+				<div className="w-full flex flex-row">
+					<h4 className="font-mono my-0">{`${name}`}</h4>
+					<h4 className="mx-3 my-0">{separator}</h4>
+					<h4 className="font-mono color-blue-800 my-0">
+						<HyperlinkedText tokens={typeTokens} />
+					</h4>
+				</div>
+				{summary && <p className="color-slate-500 mt-2">{summary}</p>}
+				{children}
+			</div>
+		</div>
+	);
+}

packages/website/src/components/DocContainer.tsx

@@ -1,28 +1,32 @@
+import type { ReactNode } from 'react';
 import { Prism as SyntaxHighlighter } from 'react-syntax-highlighter';
 import { vs } from 'react-syntax-highlighter/dist/cjs/styles/prism';
-import { Separator } from './Seperator';
+import { HyperlinkedText } from './HyperlinkedText';
+import { Section } from './Section';
 import { TypeParamTable } from './TypeParamTable';
 import { generateIcon } from '~/util/icon';
-import type { TypeParameterData } from '~/util/parse.server';
+import type { TokenDocumentation, TypeParameterData } from '~/util/parse.server';
 
 export interface DocContainerProps {
 	name: string;
 	kind: string;
 	excerpt: string;
 	summary?: string | null;
-	children?: JSX.Element | JSX.Element[];
+	children?: ReactNode;
+	extendsTokens?: TokenDocumentation[] | null;
 	typeParams?: TypeParameterData[];
 }
 
-export function DocContainer({ name, kind, excerpt, summary, typeParams, children }: DocContainerProps) {
+export function DocContainer({ name, kind, excerpt, summary, typeParams, children, extendsTokens }: DocContainerProps) {
 	return (
 		<>
-			<div className="bg-white border-b-solid border-gray border-width-0.5 sticky top-0 px-10 py-5">
-				<h1 className="font-mono break-all m-0">
+			<div className="bg-white border-b-solid border-gray border-width-0.5 sticky top-0 px-10 py-2">
+				<h2 className="font-mono break-all m-0">
 					{generateIcon(kind, 'mr-2')}
 					{name}
-				</h1>
+				</h2>
 			</div>
+
 			<div className="p-10">
 				<div>
 					<SyntaxHighlighter
@@ -35,15 +39,21 @@ export function DocContainer({ name, kind, excerpt, summary, typeParams, childre
 						{excerpt}
 					</SyntaxHighlighter>
 				</div>
-				<h2>Summary</h2>
-				<p className="color-slate-500">{summary ?? 'No summary provided.'}</p>
-				<Separator />
+				{extendsTokens?.length ? (
+					<div className="flex flex-row items-center">
+						<h2 className="mr-5">Extends</h2>
+						<p className="font-mono">
+							<HyperlinkedText tokens={extendsTokens} />
+						</p>
+					</div>
+				) : null}
+				<Section title="Summary">
+					<p className="color-slate-500">{summary ?? 'No summary provided.'}</p>
+				</Section>
 				{typeParams?.length ? (
-					<>
-						<h2>Type Parameters</h2>
+					<Section title="Type Parameters">
 						<TypeParamTable data={typeParams} className="mb-5 p-3" />
-						<Separator />
-					</>
+					</Section>
 				) : null}
 				<div>{children}</div>
 			</div>

packages/website/src/components/HyperlinkedText.tsx

@@ -0,0 +1,30 @@
+import type { TokenDocumentation } from '~/util/parse.server';
+
+export interface HyperlinkedTextProps {
+	tokens: TokenDocumentation[];
+}
+
+/**
+ * Constructs a hyperlinked html node based on token type references
+ *
+ * @param tokens An array of documentation tokens to construct the HTML
+ *
+ * @returns An array of JSX elements and string comprising the hyperlinked text
+ */
+export function HyperlinkedText({ tokens }: HyperlinkedTextProps) {
+	return (
+		<>
+			{tokens.map((token) => {
+				if (token.path) {
+					return (
+						<a key={token.text} href={token.path}>
+							{token.text}
+						</a>
+					);
+				}
+
+				return token.text;
+			})}
+		</>
+	);
+}

packages/website/src/components/ItemSidebar.tsx

@@ -18,11 +18,11 @@ function onMenuClick() {
 export function ItemSidebar({ packageName, data }: ItemListProps) {
 	return (
 		<div className="flex flex-col max-h-full min-w-[270px] lg:border-r-solid border-b-solid border-gray border-width-0.5">
-			<div className="flex justify-between content-center items-center border-b-solid border-gray border-width-0.5">
-				<h1 className="px-2 font-mono flex items-center content-center">
+			<div className="flex justify-between content-center items-center border-b-solid border-gray border-width-0.5 py-2">
+				<h2 className="px-2 font-mono flex items-center content-center m-0">
 					<VscPackage className="px-1" />
 					{`${packageName}`}
-				</h1>
+				</h2>
 				<button className="lg:hidden mr-2 bg-transparent border-none cursor-pointer" onClick={onMenuClick}>
 					<FiMenu size={32} />
 				</button>

packages/website/src/components/MethodItem.tsx

@@ -1,8 +1,8 @@
 import { FiLink } from 'react-icons/fi';
+import { HyperlinkedText } from './HyperlinkedText';
 import { ParameterTable } from './ParameterTable';
 import type { DocMethod } from '~/DocModel/DocMethod';
 import type { DocMethodSignature } from '~/DocModel/DocMethodSignature';
-import { constructHyperlinkedText } from '~/util/util';
 
 type MethodResolvable = ReturnType<DocMethod['toJSON']> | ReturnType<DocMethodSignature['toJSON']>;
 
@@ -37,7 +37,7 @@ export function MethodItem({ data }: MethodItemProps) {
 						<h4 className="font-mono my-0 break-all">{`${getShorthandName(data)}`}</h4>
 						<h4 className="mx-3 my-0">:</h4>
 						<h4 className="font-mono color-blue-800 my-0 break-all ">
-							{constructHyperlinkedText(data.returnTypeTokens)}
+							<HyperlinkedText tokens={data.returnTypeTokens} />
 						</h4>
 					</div>
 				</div>

packages/website/src/components/MethodList.tsx

@@ -9,7 +9,6 @@ export interface MethodListProps {
 export function MethodList({ data }: MethodListProps) {
 	return (
 		<div>
-			<h2>Methods</h2>
 			<div className="flex flex-col">
 				{data.map((method) => (
 					<MethodItem key={method.name} data={method} />

packages/website/src/components/ParameterTable.tsx

@@ -1,5 +1,5 @@
+import { HyperlinkedText } from './HyperlinkedText';
 import { Table } from './Table';
-import { constructHyperlinkedText } from '../util/util';
 import type { ParameterDocumentation } from '~/util/parse.server';
 
 interface ParameterDetailProps {
@@ -10,7 +10,7 @@ interface ParameterDetailProps {
 export function ParameterTable({ data, className }: ParameterDetailProps) {
 	const rows = data.map((param) => ({
 		Name: param.name,
-		Type: constructHyperlinkedText(param.tokens),
+		Type: <HyperlinkedText tokens={param.tokens} />,
 		Optional: param.isOptional ? 'Yes' : 'No',
 		Description: 'None',
 	}));

packages/website/src/components/PropertyItem.tsx

@@ -1,19 +0,0 @@
-import type { DocProperty } from '~/DocModel/DocProperty';
-import { constructHyperlinkedText } from '~/util/util';
-
-export interface PropertyItemProps {
-	data: ReturnType<DocProperty['toJSON']>;
-}
-
-export function PropertyItem({ data }: PropertyItemProps) {
-	return (
-		<div className="flex flex-col mb-2 ml-3">
-			<div className="w-full flex flex-row">
-				<h4 className="font-mono my-0">{`${data.name}`}</h4>
-				<h4 className="mx-3 my-0">:</h4>
-				<h4 className="font-mono color-blue-800 my-0">{constructHyperlinkedText(data.propertyTypeTokens)}</h4>
-			</div>
-			{data.summary && <p className="color-slate-500 mt-2">{data.summary}</p>}
-		</div>
-	);
-}

packages/website/src/components/PropertyList.tsx

@@ -1,4 +1,4 @@
-import { PropertyItem } from './PropertyItem';
+import { CodeListing } from './CodeListing';
 import type { DocProperty } from '~/DocModel/DocProperty';
 
 export interface PropertyListProps {
@@ -8,9 +8,8 @@ export interface PropertyListProps {
 export function PropertyList({ data }: PropertyListProps) {
 	return (
 		<div className="flex flex-col">
-			<h2>Properties</h2>
 			{data.map((prop) => (
-				<PropertyItem key={prop.name} data={prop} />
+				<CodeListing key={prop.name} name={prop.name} typeTokens={prop.propertyTypeTokens} summary={prop.summary} />
 			))}
 		</div>
 	);

packages/website/src/components/Section.tsx

@@ -0,0 +1,18 @@
+import type { ReactNode } from 'react';
+import { Separator } from './Seperator';
+
+export interface SectionProps {
+	children: ReactNode;
+	title: string;
+	className?: string | undefined;
+}
+
+export function Section({ title, children, className }: SectionProps) {
+	return (
+		<div className={className}>
+			<h2>{title}</h2>
+			{children}
+			<Separator />
+		</div>
+	);
+}

packages/website/src/components/Sections.tsx

@@ -0,0 +1,42 @@
+import { MethodList } from './MethodList';
+import { ParameterTable } from './ParameterTable';
+import { PropertyList } from './PropertyList';
+import { Section } from './Section';
+import type { DocInterface } from '~/DocModel/DocInterface';
+import type { ParameterDocumentation } from '~/util/parse.server';
+
+export interface PropertiesSectionProps {
+	data: ReturnType<DocInterface['toJSON']>['properties'];
+}
+
+export function PropertiesSection({ data }: PropertiesSectionProps) {
+	return data.length ? (
+		<Section title="Properties">
+			<PropertyList data={data} />
+		</Section>
+	) : null;
+}
+
+export interface MethodsSectionProps {
+	data: ReturnType<DocInterface['toJSON']>['methods'];
+}
+
+export function MethodsSection({ data }: MethodsSectionProps) {
+	return data.length ? (
+		<Section title="Methods">
+			<MethodList data={data} />
+		</Section>
+	) : null;
+}
+
+export interface ParametersSectionProps {
+	data: ParameterDocumentation[];
+}
+
+export function ParametersSection({ data }: ParametersSectionProps) {
+	return data.length ? (
+		<Section title="Parameters">
+			<ParameterTable data={data} />
+		</Section>
+	) : null;
+}

packages/website/src/components/Table.tsx

@@ -1,3 +1,5 @@
+import type { ReactNode } from 'react';
+
 export interface RowData {
 	monospace?: boolean;
 	content: string;
@@ -6,7 +8,7 @@ export interface RowData {
 export interface TableProps {
 	columns: string[];
 	columnStyles?: Record<string, string>;
-	rows: Record<string, string | (string | JSX.Element)[]>[];
+	rows: Record<string, ReactNode>[];
 	className?: string | undefined;
 }
 
@@ -26,20 +28,16 @@ export function Table({ rows, columns, columnStyles, className }: TableProps) {
 				<tbody>
 					{rows.map((row, i) => (
 						<tr key={i}>
-							{Object.entries(row).map(([colName, val]) => {
-								console.log(colName);
-								console.log(columnStyles?.[colName]);
-								return (
-									<td
-										key={colName}
-										className={`p-2 text-sm border-b text-left border-slate-300 break-all ${
-											columnStyles?.[colName] ?? ''
-										}`}
-									>
-										{val}
-									</td>
-								);
-							})}
+							{Object.entries(row).map(([colName, val]) => (
+								<td
+									key={colName}
+									className={`p-2 text-sm border-b text-left border-slate-300 break-all ${
+										columnStyles?.[colName] ?? ''
+									}`}
+								>
+									{val}
+								</td>
+							))}
 						</tr>
 					))}
 				</tbody>

packages/website/src/components/TypeParamTable.tsx

@@ -1,6 +1,6 @@
+import { HyperlinkedText } from './HyperlinkedText';
 import { Table } from './Table';
 import type { TypeParameterData } from '~/util/parse.server';
-import { constructHyperlinkedText } from '~/util/util';
 
 export interface TableProps {
 	data: TypeParameterData[];
@@ -10,9 +10,9 @@ export interface TableProps {
 export function TypeParamTable({ data, className }: TableProps) {
 	const rows = data.map((typeParam) => ({
 		Name: typeParam.name,
-		Constraints: constructHyperlinkedText(typeParam.constraintTokens),
+		Constraints: <HyperlinkedText tokens={typeParam.constraintTokens} />,
 		Optional: typeParam.optional ? 'Yes' : 'No',
-		Default: constructHyperlinkedText(typeParam.defaultTokens),
+		Default: <HyperlinkedText tokens={typeParam.defaultTokens} />,
 		Description: 'None',
 	}));
 

packages/website/src/components/model/Class.tsx

@@ -1,7 +1,5 @@
 import { DocContainer } from '../DocContainer';
-import { MethodList } from '../MethodList';
-import { PropertyList } from '../PropertyList';
-import { Separator } from '../Seperator';
+import { MethodsSection, PropertiesSection } from '../Sections';
 import type { DocClass } from '~/DocModel/DocClass';
 
 export interface ClassProps {
@@ -16,22 +14,10 @@ export function Class({ data }: ClassProps) {
 			excerpt={data.excerpt}
 			summary={data.summary}
 			typeParams={data.typeParameterData}
+			extendsTokens={data.extendsTokens}
 		>
-			<>
-				{data.properties.length ? (
-					<>
-						<PropertyList data={data.properties} />
-						<Separator />
-					</>
-				) : null}
-
-				{data.methods.length ? (
-					<>
-						<MethodList data={data.methods} />
-						<Separator />
-					</>
-				) : null}
-			</>
+			<PropertiesSection data={data.properties} />
+			<MethodsSection data={data.methods} />
 		</DocContainer>
 	);
 }

packages/website/src/components/model/Enum.tsx

@@ -1,4 +1,6 @@
+import { CodeListing, CodeListingSeparatorType } from '../CodeListing';
 import { DocContainer } from '../DocContainer';
+import { Section } from '../Section';
 import type { DocEnum } from '~/DocModel/DocEnum';
 
 export interface EnumProps {
@@ -8,14 +10,19 @@ export interface EnumProps {
 export function Enum({ data }: EnumProps) {
 	return (
 		<DocContainer name={data.name} kind={data.kind} excerpt={data.excerpt} summary={data.summary}>
-			<>
-				<h3>Members</h3>
-				<ul>
+			<Section title="Members">
+				<div className="flex flex-col">
 					{data.members.map((member) => (
-						<li key={member.name}>{member.name}</li>
+						<CodeListing
+							key={member.name}
+							name={member.name}
+							separator={CodeListingSeparatorType.Value}
+							typeTokens={member.initializerTokens}
+							summary={member.summary}
+						/>
 					))}
-				</ul>
-			</>
+				</div>
+			</Section>
 		</DocContainer>
 	);
 }

packages/website/src/components/model/Function.tsx

@@ -1,5 +1,5 @@
 import { DocContainer } from '../DocContainer';
-import { ParameterTable } from '../ParameterTable';
+import { ParametersSection } from '../Sections';
 import type { DocFunction } from '~/DocModel/DocFunction';
 
 export interface FunctionProps {
@@ -15,8 +15,7 @@ export function Function({ data }: FunctionProps) {
 			summary={data.summary}
 			typeParams={data.typeParameterData}
 		>
-			<h2>Parameters</h2>
-			<ParameterTable data={data.parameters} />
+			<ParametersSection data={data.parameters} />
 		</DocContainer>
 	);
 }

packages/website/src/components/model/Interface.tsx

@@ -1,6 +1,5 @@
 import { DocContainer } from '../DocContainer';
-import { MethodList } from '../MethodList';
-import { PropertyList } from '../PropertyList';
+import { MethodsSection, PropertiesSection } from '../Sections';
 import type { DocInterface } from '~/DocModel/DocInterface';
 
 export interface InterfaceProps {
@@ -16,10 +15,8 @@ export function Interface({ data }: InterfaceProps) {
 			summary={data.summary}
 			typeParams={data.typeParameterData}
 		>
-			<>
-				{data.properties.length ? <PropertyList data={data.properties} /> : null}
-				{data.methods.length ? <MethodList data={data.methods} /> : null}
-			</>
+			<PropertiesSection data={data.properties} />
+			<MethodsSection data={data.methods} />
 		</DocContainer>
 	);
 }

packages/website/src/routes/docs/$branchName/packages/$packageName.tsx

@@ -39,7 +39,7 @@ export default function Package() {
 	const { packageName } = useParams();
 
 	return (
-		<div className="flex flex-col lg:flex-row overflow-hidden max-w-full h-full">
+		<div className="flex flex-col lg:flex-row overflow-hidden max-w-full h-full dark:bg-slate-800">
 			<div className="w-full lg:min-w-1/4 lg:max-w-1/4">
 				<ItemSidebar packageName={packageName!} data={data} />
 			</div>

packages/website/src/util/parse.server.ts

@@ -13,6 +13,7 @@ import {
 	type TypeParameter,
 } from '@microsoft/api-extractor-model';
 import type { DocNode, DocParagraph, DocPlainText } from '@microsoft/tsdoc';
+import { Meaning, ModuleSource } from '@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference';
 
 export function findPackage(model: ApiModel, name: string): ApiPackage | undefined {
 	return (model.findMembersByName(name)[0] ?? model.findMembersByName(`@discordjs/${name}`)[0]) as
@@ -135,6 +136,17 @@ export interface ParameterDocumentation {
 	tokens: TokenDocumentation[];
 }
 
+function createDapiTypesURL(meaning: Meaning, name: string) {
+	const base = 'https://discord-api-types.dev/api/discord-api-types-v10';
+
+	switch (meaning) {
+		case 'type':
+			return `${base}#${name}`;
+		default:
+			return `${base}/${meaning}/${name}`;
+	}
+}
+
 export function genReference(item: ApiItem) {
 	return {
 		name: resolveName(item),
@@ -148,6 +160,19 @@ export function genToken(model: ApiModel, token: ExcerptToken) {
 		token.canonicalReference._navigation = '.';
 	}
 
+	if (
+		token.canonicalReference?.source instanceof ModuleSource &&
+		token.canonicalReference.symbol &&
+		token.canonicalReference.source.packageName === 'discord-api-types' &&
+		token.canonicalReference.symbol.meaning
+	) {
+		return {
+			kind: token.kind,
+			text: token.text,
+			path: createDapiTypesURL(token.canonicalReference.symbol.meaning, token.text),
+		};
+	}
+
 	const item = token.canonicalReference
 		? model.resolveDeclarationReference(token.canonicalReference, undefined).resolvedApiItem ?? null
 		: null;

packages/website/src/util/util.tsx

@@ -1,23 +0,0 @@
-import type { TokenDocumentation } from './parse.server';
-
-/**
- * Constructs a hyperlinked html node based on token type references
- *
- * @param tokens An array of documentation tokens to construct the HTML
- *
- * @returns An array of JSX elements and string comprising the hyperlinked text
- */
-export function constructHyperlinkedText(tokens: TokenDocumentation[]) {
-	const html: (JSX.Element | string)[] = [];
-
-	for (const token of tokens) {
-		if (token.path) {
-			html.push(<a href={token.path}>{token.text}</a>);
-			continue;
-		}
-
-		html.push(token.text);
-	}
-
-	return html;
-}