Skip to content

Commit

Permalink
feat(website): use dropdowns for overloads (#8630)
Browse files Browse the repository at this point in the history
Co-authored-by: Almeida <almeidx@pm.me>
Co-authored-by: iCrawl <buechler.noel@outlook.com>
  • Loading branch information
3 people committed Sep 17, 2022
1 parent 0785353 commit 678ceaa
Show file tree
Hide file tree
Showing 8 changed files with 152 additions and 28 deletions.
26 changes: 24 additions & 2 deletions packages/api-extractor-utils/src/ApiNodeJSONEncoder.ts
Expand Up @@ -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;
}
Expand Down Expand Up @@ -133,6 +135,7 @@ export interface ApiVariableJSON extends ApiItemJSON {
}

export interface ApiFunctionJSON extends ApiItemJSON, ApiTypeParameterListJSON, ApiParameterListJSON {
mergedSiblings: ApiFunctionJSON[];
overloadIndex: number;
returnTypeTokens: TokenDocumentation[];
}
Expand Down Expand Up @@ -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),
Expand All @@ -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)),
};
}

Expand All @@ -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)),
};
}

Expand Down
5 changes: 5 additions & 0 deletions packages/website/src/components/DocContainer.tsx
Expand Up @@ -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 {
Expand Down Expand Up @@ -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[];
}>;
Expand Down Expand Up @@ -60,6 +62,7 @@ export function DocContainer({
implementsTokens,
methods,
properties,
subHeading,
}: DocContainerProps) {
const matches = useMedia('(max-width: 768px)', true);

Expand All @@ -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" />
Expand Down
52 changes: 45 additions & 7 deletions packages/website/src/components/MethodItem.tsx
@@ -1,13 +1,19 @@
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';
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],
Expand Down Expand Up @@ -54,21 +60,53 @@ 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} />
</h4>
</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}
Expand Down
18 changes: 10 additions & 8 deletions packages/website/src/components/MethodList.tsx
Expand Up @@ -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],
);

Expand Down
14 changes: 11 additions & 3 deletions 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';
Expand Down Expand Up @@ -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">
Expand All @@ -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">
Expand Down
4 changes: 4 additions & 0 deletions packages/website/src/components/TableOfContentItems.tsx
Expand Up @@ -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}` : ''
}`;
Expand Down
55 changes: 49 additions & 6 deletions 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>
);
}
6 changes: 4 additions & 2 deletions packages/website/src/pages/docs/[...slug].tsx
Expand Up @@ -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,
Expand All @@ -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':
Expand Down

1 comment on commit 678ceaa

@vercel
Copy link

@vercel vercel bot commented on 678ceaa Sep 17, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please sign in to comment.