feat(website): use dropdowns for overloads (#8630)

Co-authored-by: Almeida <almeidx@pm.me>
Co-authored-by: iCrawl <buechler.noel@outlook.com>

packages/api-extractor-utils/src/ApiNodeJSONEncoder.ts

@@ -82,12 +82,14 @@ export interface ApiMethodSignatureJSON
 		ApiTypeParameterListJSON,
 		ApiParameterListJSON,
 		ApiInheritableJSON {
+	mergedSiblings: ApiMethodSignatureJSON[];
 	optional: boolean;
 	overloadIndex: number;
 	returnTypeTokens: TokenDocumentation[];
 }
 
 export interface ApiMethodJSON extends ApiMethodSignatureJSON {
+	mergedSiblings: ApiMethodJSON[];
 	protected: boolean;
 	static: boolean;
 }
@@ -133,6 +135,7 @@ export interface ApiVariableJSON extends ApiItemJSON {
 }
 
 export interface ApiFunctionJSON extends ApiItemJSON, ApiTypeParameterListJSON, ApiParameterListJSON {
+	mergedSiblings: ApiFunctionJSON[];
 	overloadIndex: number;
 	returnTypeTokens: TokenDocumentation[];
 }
@@ -255,7 +258,7 @@ export class ApiNodeJSONEncoder {
 		};
 	}
 
-	public static encodeFunction(model: ApiModel, item: FunctionLike, version: string): ApiFunctionJSON {
+	public static encodeFunctionLike(model: ApiModel, item: FunctionLike, version: string) {
 		return {
 			...this.encodeItem(model, item, version),
 			...this.encodeParameterList(model, item, version),
@@ -265,16 +268,31 @@ export class ApiNodeJSONEncoder {
 		};
 	}
 
+	public static encodeFunction(model: ApiModel, item: FunctionLike, version: string, nested = false): ApiFunctionJSON {
+		return {
+			...this.encodeFunctionLike(model, item, version),
+			mergedSiblings: nested
+				? []
+				: item.getMergedSiblings().map((item) => this.encodeFunction(model, item as ApiFunction, version, true)),
+		};
+	}
+
 	public static encodeMethodSignature(
 		model: ApiModel,
 		item: ApiMethodSignature,
 		parent: ApiItemContainerMixin,
 		version: string,
+		nested = false,
 	): ApiMethodSignatureJSON {
 		return {
-			...this.encodeFunction(model, item, version),
+			...this.encodeFunctionLike(model, item, version),
 			...this.encodeInheritanceData(item, parent, version),
 			optional: item.isOptional,
+			mergedSiblings: nested
+				? []
+				: item
+						.getMergedSiblings()
+						.map((item) => this.encodeMethodSignature(model, item as ApiMethodSignature, parent, version, true)),
 		};
 	}
 
@@ -283,11 +301,15 @@ export class ApiNodeJSONEncoder {
 		item: ApiMethod,
 		parent: ApiItemContainerMixin,
 		version: string,
+		nested = false,
 	): ApiMethodJSON {
 		return {
 			...this.encodeMethodSignature(model, item, parent, version),
 			static: item.isStatic,
 			protected: item.isProtected,
+			mergedSiblings: nested
+				? []
+				: item.getMergedSiblings().map((item) => this.encodeMethod(model, item as ApiMethod, parent, version, true)),
 		};
 	}
 

packages/website/src/components/DocContainer.tsx

@@ -5,6 +5,7 @@ import type {
 	ApiClassJSON,
 	ApiInterfaceJSON,
 } from '@discordjs/api-extractor-utils';
+import type { ReactNode } from 'react';
 import { Fragment, type PropsWithChildren } from 'react';
 import { Scrollbars } from 'react-custom-scrollbars-2';
 import {
@@ -32,6 +33,7 @@ type DocContainerProps = PropsWithChildren<{
 	methods?: ApiClassJSON['methods'] | ApiInterfaceJSON['methods'] | null;
 	name: string;
 	properties?: ApiClassJSON['properties'] | ApiInterfaceJSON['properties'] | null;
+	subHeading?: ReactNode;
 	summary?: ApiItemJSON['summary'];
 	typeParams?: TypeParameterData[];
 }>;
@@ -60,6 +62,7 @@ export function DocContainer({
 	implementsTokens,
 	methods,
 	properties,
+	subHeading,
 }: DocContainerProps) {
 	const matches = useMedia('(max-width: 768px)', true);
 
@@ -71,6 +74,8 @@ export function DocContainer({
 					{name}
 				</h2>
 
+				{subHeading}
+
 				<Section title="Summary" icon={<VscListSelection size={20} />} padded dense={matches}>
 					{summary ? <TSDoc node={summary} /> : <span>No summary provided.</span>}
 					<div className="border-light-900 dark:border-dark-100 -mx-8 mt-6 border-t-2" />

packages/website/src/components/MethodItem.tsx

@@ -1,6 +1,8 @@
 import type { ApiMethodJSON, ApiMethodSignatureJSON } from '@discordjs/api-extractor-utils';
-import { useCallback, useMemo } from 'react';
+import { Menu, MenuButton, MenuItem, useMenuState } from 'ariakit';
+import { useCallback, useMemo, useState } from 'react';
 import { FiLink } from 'react-icons/fi';
+import { VscChevronDown, VscVersions } from 'react-icons/vsc';
 import { HyperlinkedText } from './HyperlinkedText';
 import { InheritanceText } from './InheritanceText';
 import { ParameterTable } from './ParameterTable';
@@ -8,6 +10,10 @@ import { TSDoc } from './tsdoc/TSDoc';
 
 export function MethodItem({ data }: { data: ApiMethodJSON | ApiMethodSignatureJSON }) {
 	const method = data as ApiMethodJSON;
+	const [overloadIndex, setOverloadIndex] = useState(1);
+	const overloadedData = method.mergedSiblings[overloadIndex - 1]!;
+	const menu = useMenuState({ gutter: 8, sameWidth: true, fitViewport: true });
+
 	const key = useMemo(
 		() => `${data.name}${data.overloadIndex && data.overloadIndex > 1 ? `:${data.overloadIndex}` : ''}`,
 		[data.name, data.overloadIndex],
@@ -54,7 +60,7 @@ export function MethodItem({ data }: { data: ApiMethodJSON | ApiMethodSignatureJ
 						</div>
 					) : null}
 					<div className="flex flex-row flex-wrap gap-1">
-						<h4 className="break-all font-mono text-lg font-bold">{getShorthandName(data)}</h4>
+						<h4 className="break-all font-mono text-lg font-bold">{getShorthandName(overloadedData)}</h4>
 						<h4 className="font-mono text-lg font-bold">:</h4>
 						<h4 className="break-all font-mono text-lg font-bold">
 							<HyperlinkedText tokens={data.returnTypeTokens} />
@@ -62,13 +68,45 @@ export function MethodItem({ data }: { data: ApiMethodJSON | ApiMethodSignatureJ
 					</div>
 				</div>
 			</div>
+			{data.mergedSiblings.length > 1 ? (
+				<div className="flex flex-row place-items-center gap-2">
+					<MenuButton
+						state={menu}
+						className="bg-light-600 hover:bg-light-700 active:bg-light-800 dark:bg-dark-600 dark:hover:bg-dark-500 dark:active:bg-dark-400 rounded p-3"
+					>
+						<div className="flex flex-row place-content-between place-items-center gap-2">
+							<VscVersions size={20} />
+							<div>
+								<span className="font-semibold">{`Overload ${overloadIndex}`}</span>
+								{` of ${data.mergedSiblings.length}`}
+							</div>
+							<VscChevronDown
+								className={`transform transition duration-150 ease-in-out ${menu.open ? 'rotate-180' : 'rotate-0'}`}
+								size={20}
+							/>
+						</div>
+					</MenuButton>
+					<Menu
+						state={menu}
+						className="dark:bg-dark-600 border-light-800 dark:border-dark-100 z-20 flex flex-col rounded border bg-white p-1"
+					>
+						{data.mergedSiblings.map((_, idx) => (
+							<MenuItem
+								key={idx}
+								className="hover:bg-light-700 active:bg-light-800 dark:bg-dark-600 dark:hover:bg-dark-500 dark:active:bg-dark-400 cursor-pointer rounded bg-white p-3 text-sm"
+								onClick={() => setOverloadIndex(idx + 1)}
+							>{`Overload ${idx + 1}`}</MenuItem>
+						))}
+					</Menu>
+				</div>
+			) : null}
 			{data.summary || data.parameters.length ? (
 				<div className="mb-4 flex flex-col gap-4">
-					{data.deprecated ? <TSDoc node={data.deprecated} /> : 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}
+					{overloadedData.deprecated ? <TSDoc node={overloadedData.deprecated} /> : null}
+					{overloadedData.summary ?? data.summary ? <TSDoc node={overloadedData.summary ?? data.summary!} /> : null}
+					{overloadedData.remarks ? <TSDoc node={overloadedData.remarks} /> : null}
+					{overloadedData.comment ? <TSDoc node={overloadedData.comment} /> : null}
+					{overloadedData.parameters.length ? <ParameterTable data={overloadedData.parameters} /> : null}
 					{data.inheritanceData ? <InheritanceText data={data.inheritanceData} /> : null}
 				</div>
 			) : null}

packages/website/src/components/MethodList.tsx

@@ -5,14 +5,16 @@ import { MethodItem } from './MethodItem';
 export function MethodList({ data }: { data: (ApiMethodJSON | ApiMethodSignatureJSON)[] }) {
 	const methodItems = useMemo(
 		() =>
-			data.map((method) => (
-				<Fragment
-					key={`${method.name}${method.overloadIndex && method.overloadIndex > 1 ? `:${method.overloadIndex}` : ''}`}
-				>
-					<MethodItem data={method} />
-					<div className="border-light-900 dark:border-dark-100 -mx-8 border-t-2" />
-				</Fragment>
-			)),
+			data
+				.filter((method) => method.overloadIndex <= 1)
+				.map((method) => (
+					<Fragment
+						key={`${method.name}${method.overloadIndex && method.overloadIndex > 1 ? `:${method.overloadIndex}` : ''}`}
+					>
+						<MethodItem data={method} />
+						<div className="border-light-900 dark:border-dark-100 -mx-8 border-t-2" />
+					</Fragment>
+				)),
 		[data],
 	);
 

packages/website/src/components/SidebarLayout.tsx

@@ -1,4 +1,4 @@
-import type { getMembers, ApiItemJSON } from '@discordjs/api-extractor-utils';
+import type { getMembers, ApiItemJSON, ApiClassJSON, ApiInterfaceJSON } from '@discordjs/api-extractor-utils';
 import { Button } from 'ariakit/button';
 import { Menu, MenuButton, MenuItem, useMenuState } from 'ariakit/menu';
 import Image from 'next/future/image';
@@ -248,7 +248,11 @@ export function SidebarLayout({
 			</nav>
 			<main
 				className={`pt-18 lg:pl-76 ${
-					data?.member?.kind === 'Class' || data?.member?.kind === 'Interface' ? 'xl:pr-64' : ''
+					(data?.member?.kind === 'Class' || data?.member?.kind === 'Interface') &&
+					((data.member as ApiClassJSON | ApiInterfaceJSON).methods?.length ||
+						(data.member as ApiClassJSON | ApiInterfaceJSON).properties?.length)
+						? 'xl:pr-64'
+						: ''
 				}`}
 			>
 				<article className="dark:bg-dark-600 bg-light-600">
@@ -258,7 +262,11 @@ export function SidebarLayout({
 					<div className="h-76 md:h-52" />
 					<footer
 						className={`dark:bg-dark-600 h-76 lg:pl-84 bg-light-600 fixed bottom-0 left-0 right-0 md:h-52 md:pl-4 md:pr-16 ${
-							data?.member?.kind === 'Class' || data?.member?.kind === 'Interface' ? 'xl:pr-76' : 'xl:pr-16'
+							(data?.member?.kind === 'Class' || data?.member?.kind === 'Interface') &&
+							((data.member as ApiClassJSON | ApiInterfaceJSON).methods?.length ||
+								(data.member as ApiClassJSON | ApiInterfaceJSON).properties?.length)
+								? 'xl:pr-76'
+								: 'xl:pr-16'
 						}`}
 					>
 						<div className="mx-auto flex max-w-6xl flex-col place-items-center gap-12 pt-12 lg:place-content-center">

packages/website/src/components/TableOfContentItems.tsx

@@ -27,6 +27,10 @@ export function TableOfContentItems({
 	const methodItems = useMemo(
 		() =>
 			methods.map((member) => {
+				if (member.overloadIndex && member.overloadIndex > 1) {
+					return null;
+				}
+
 				const key = `${member.name}${
 					member.overloadIndex && member.overloadIndex > 1 ? `:${member.overloadIndex}` : ''
 				}`;

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

@@ -1,17 +1,60 @@
 import type { ApiFunctionJSON } from '@discordjs/api-extractor-utils';
+import { Menu, MenuButton, MenuItem, useMenuState } from 'ariakit';
+import { useState } from 'react';
+import { VscChevronDown, VscVersions } from 'react-icons/vsc';
 import { DocContainer } from '../DocContainer';
 import { ParametersSection } from '../Sections';
 
 export function Function({ data }: { data: ApiFunctionJSON }) {
+	const [overloadIndex, setOverloadIndex] = useState(1);
+	const overloadedData = data.mergedSiblings[overloadIndex - 1]!;
+	const menu = useMenuState({ gutter: 8, sameWidth: true, fitViewport: true });
+
 	return (
 		<DocContainer
-			name={`${data.name}${data.overloadIndex && data.overloadIndex > 1 ? ` (${data.overloadIndex})` : ''}`}
-			kind={data.kind}
-			excerpt={data.excerpt}
-			summary={data.summary}
-			typeParams={data.typeParameters}
+			name={`${overloadedData.name}${
+				overloadedData.overloadIndex && overloadedData.overloadIndex > 1 ? ` (${overloadedData.overloadIndex})` : ''
+			}`}
+			kind={overloadedData.kind}
+			excerpt={overloadedData.excerpt}
+			summary={overloadedData.summary}
+			typeParams={overloadedData.typeParameters}
+			subHeading={
+				data.mergedSiblings.length > 1 ? (
+					<div className="flex flex-row place-items-center gap-2">
+						<MenuButton
+							state={menu}
+							className="bg-light-600 hover:bg-light-700 active:bg-light-800 dark:bg-dark-600 dark:hover:bg-dark-500 dark:active:bg-dark-400 rounded p-3"
+						>
+							<div className="flex flex-row place-content-between place-items-center gap-2">
+								<VscVersions size={20} />
+								<div>
+									<span className="font-semibold">{`Overload ${overloadIndex}`}</span>
+									{` of ${data.mergedSiblings.length}`}
+								</div>
+								<VscChevronDown
+									className={`transform transition duration-150 ease-in-out ${menu.open ? 'rotate-180' : 'rotate-0'}`}
+									size={20}
+								/>
+							</div>
+						</MenuButton>
+						<Menu
+							state={menu}
+							className="dark:bg-dark-600 border-light-800 dark:border-dark-100 z-20 flex flex-col rounded border bg-white p-1"
+						>
+							{data.mergedSiblings.map((_, idx) => (
+								<MenuItem
+									key={idx}
+									className="hover:bg-light-700 active:bg-light-800 dark:bg-dark-600 dark:hover:bg-dark-500 dark:active:bg-dark-400 cursor-pointer rounded bg-white p-3 text-sm"
+									onClick={() => setOverloadIndex(idx + 1)}
+								>{`Overload ${idx + 1}`}</MenuItem>
+							))}
+						</Menu>
+					</div>
+				) : null
+			}
 		>
-			<ParametersSection data={data.parameters} />
+			<ParametersSection data={overloadedData.parameters} />
 		</DocContainer>
 	);
 }

packages/website/src/pages/docs/[...slug].tsx

@@ -193,7 +193,9 @@ export const getStaticProps: GetStaticProps = async ({ params }) => {
 				packageName,
 				branchName,
 				data: {
-					members: pkg ? getMembers(pkg, branchName) : [],
+					members: pkg
+						? getMembers(pkg, branchName).filter((item) => item.overloadIndex === null || item.overloadIndex <= 1)
+						: [],
 					member:
 						memberName && containerKey ? findMemberByKey(model, packageName, containerKey, branchName) ?? null : null,
 					source: mdxSource,
@@ -219,7 +221,7 @@ const member = (props?: ApiItemJSON | undefined) => {
 		case 'Class':
 			return <Class data={props as ApiClassJSON} />;
 		case 'Function':
-			return <Function data={props as ApiFunctionJSON} />;
+			return <Function key={props.containerKey} data={props as ApiFunctionJSON} />;
 		case 'Interface':
 			return <Interface data={props as ApiInterfaceJSON} />;
 		case 'TypeAlias':