mirror of
https://github.com/discordjs/discord.js.git
synced 2026-03-11 09:03:29 +01:00
refactor(website): extract layouts and use more server components (#9027)
Closes https://github.com/discordjs/discord.js/issues/8920 Closes https://github.com/discordjs/discord.js/issues/8997
This commit is contained in:
Suneet Tipirneni
12
apps/website/src/components/Anchor.tsx
Normal file
12
apps/website/src/components/Anchor.tsx
Normal file
@@ -0,0 +1,12 @@
|
||||
import { FiLink } from '@react-icons/all-files/fi/FiLink';
|
||||
|
||||
export function Anchor({ href }: { href: string }) {
|
||||
return (
|
||||
<a
|
||||
className="focus:ring-width-2 focus:ring-blurple hidden rounded outline-0 focus:ring md:inline-block"
|
||||
href={href}
|
||||
>
|
||||
<FiLink size={20} />
|
||||
</a>
|
||||
);
|
||||
}
|
||||
@@ -1,88 +0,0 @@
|
||||
'use client';
|
||||
|
||||
import type { TokenDocumentation, ApiItemJSON, AnyDocNodeJSON, InheritanceData } from '@discordjs/api-extractor-utils';
|
||||
import { FiLink } from '@react-icons/all-files/fi/FiLink';
|
||||
import type { PropsWithChildren } from 'react';
|
||||
import { HyperlinkedText } from './HyperlinkedText';
|
||||
import { InheritanceText } from './InheritanceText';
|
||||
import { TSDoc } from './tsdoc/TSDoc';
|
||||
|
||||
export enum CodeListingSeparatorType {
|
||||
Type = ':',
|
||||
Value = '=',
|
||||
}
|
||||
|
||||
export function CodeListing({
|
||||
name,
|
||||
separator = CodeListingSeparatorType.Type,
|
||||
typeTokens,
|
||||
readonly = false,
|
||||
optional = false,
|
||||
summary,
|
||||
children,
|
||||
comment,
|
||||
deprecation,
|
||||
inheritanceData,
|
||||
}: PropsWithChildren<{
|
||||
comment?: AnyDocNodeJSON | null;
|
||||
deprecation?: AnyDocNodeJSON | null;
|
||||
inheritanceData?: InheritanceData | null;
|
||||
name: string;
|
||||
optional?: boolean;
|
||||
readonly?: boolean;
|
||||
separator?: CodeListingSeparatorType;
|
||||
summary?: ApiItemJSON['summary'];
|
||||
typeTokens: TokenDocumentation[];
|
||||
}>) {
|
||||
return (
|
||||
<div className="scroll-mt-30 flex flex-col gap-4" id={name}>
|
||||
<div className="md:-ml-8.5 flex flex-col gap-2 md:flex-row md:place-items-center">
|
||||
<a
|
||||
aria-label="Anchor"
|
||||
className="focus:ring-width-2 focus:ring-blurple hidden rounded outline-0 focus:ring md:inline-block"
|
||||
href={`#${name}`}
|
||||
>
|
||||
<FiLink size={20} />
|
||||
</a>
|
||||
{deprecation || readonly || optional ? (
|
||||
<div className="flex flex-row gap-1">
|
||||
{deprecation ? (
|
||||
<div className="flex h-5 flex-row place-content-center place-items-center rounded-full bg-red-500 px-3 text-center text-xs font-semibold uppercase text-white">
|
||||
Deprecated
|
||||
</div>
|
||||
) : null}
|
||||
{readonly ? (
|
||||
<div className="bg-blurple flex h-5 flex-row place-content-center place-items-center rounded-full px-3 text-center text-xs font-semibold uppercase text-white">
|
||||
Readonly
|
||||
</div>
|
||||
) : null}
|
||||
{optional ? (
|
||||
<div className="bg-blurple flex h-5 flex-row place-content-center place-items-center rounded-full px-3 text-center text-xs font-semibold uppercase text-white">
|
||||
Optional
|
||||
</div>
|
||||
) : null}
|
||||
</div>
|
||||
) : null}
|
||||
<div className="flex flex-row flex-wrap place-items-center gap-1">
|
||||
<h4 className="break-all font-mono text-lg font-bold">
|
||||
{name}
|
||||
{optional ? '?' : ''}
|
||||
</h4>
|
||||
<h4 className="font-mono text-lg font-bold">{separator}</h4>
|
||||
<h4 className="break-all font-mono text-lg font-bold">
|
||||
<HyperlinkedText tokens={typeTokens} />
|
||||
</h4>
|
||||
</div>
|
||||
</div>
|
||||
{summary || inheritanceData ? (
|
||||
<div className="mb-4 flex flex-col gap-4">
|
||||
{deprecation ? <TSDoc node={deprecation} /> : null}
|
||||
{summary ? <TSDoc node={summary} /> : null}
|
||||
{comment ? <TSDoc node={comment} /> : null}
|
||||
{inheritanceData ? <InheritanceText data={inheritanceData} /> : null}
|
||||
{children}
|
||||
</div>
|
||||
) : null}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -1,135 +0,0 @@
|
||||
'use client';
|
||||
|
||||
import type {
|
||||
ApiItemJSON,
|
||||
TokenDocumentation,
|
||||
TypeParameterData,
|
||||
ApiClassJSON,
|
||||
ApiInterfaceJSON,
|
||||
} from '@discordjs/api-extractor-utils';
|
||||
import { Section } from '@discordjs/ui';
|
||||
import { VscListSelection } from '@react-icons/all-files/vsc/VscListSelection';
|
||||
import { VscSymbolClass } from '@react-icons/all-files/vsc/VscSymbolClass';
|
||||
import { VscSymbolEnum } from '@react-icons/all-files/vsc/VscSymbolEnum';
|
||||
import { VscSymbolInterface } from '@react-icons/all-files/vsc/VscSymbolInterface';
|
||||
import { VscSymbolMethod } from '@react-icons/all-files/vsc/VscSymbolMethod';
|
||||
import { VscSymbolParameter } from '@react-icons/all-files/vsc/VscSymbolParameter';
|
||||
import { VscSymbolVariable } from '@react-icons/all-files/vsc/VscSymbolVariable';
|
||||
import { Fragment, type PropsWithChildren } from 'react';
|
||||
import type { ReactNode } from 'react';
|
||||
import { Scrollbars } from 'react-custom-scrollbars-2';
|
||||
import { useMedia } from 'react-use';
|
||||
import { HyperlinkedText } from './HyperlinkedText';
|
||||
import { SyntaxHighlighter } from './SyntaxHighlighter';
|
||||
import { TableOfContentItems } from './TableOfContentItems';
|
||||
import { TypeParamTable } from './TypeParamTable';
|
||||
import { TSDoc } from './tsdoc/TSDoc';
|
||||
|
||||
type DocContainerProps = PropsWithChildren<{
|
||||
excerpt: string;
|
||||
extendsTokens?: TokenDocumentation[] | null;
|
||||
implementsTokens?: TokenDocumentation[][];
|
||||
kind: string;
|
||||
methods?: ApiClassJSON['methods'] | ApiInterfaceJSON['methods'] | null;
|
||||
name: string;
|
||||
properties?: ApiClassJSON['properties'] | ApiInterfaceJSON['properties'] | null;
|
||||
subHeading?: ReactNode;
|
||||
summary?: ApiItemJSON['summary'];
|
||||
typeParams?: TypeParameterData[];
|
||||
}>;
|
||||
|
||||
function generateIcon(kind: string) {
|
||||
const icons = {
|
||||
Class: <VscSymbolClass />,
|
||||
Method: <VscSymbolMethod />,
|
||||
Function: <VscSymbolMethod />,
|
||||
Enum: <VscSymbolEnum />,
|
||||
Interface: <VscSymbolInterface />,
|
||||
TypeAlias: <VscSymbolVariable />,
|
||||
};
|
||||
|
||||
return icons[kind as keyof typeof icons];
|
||||
}
|
||||
|
||||
export function DocContainer({
|
||||
name,
|
||||
kind,
|
||||
excerpt,
|
||||
summary,
|
||||
typeParams,
|
||||
children,
|
||||
extendsTokens,
|
||||
implementsTokens,
|
||||
methods,
|
||||
properties,
|
||||
subHeading,
|
||||
}: DocContainerProps) {
|
||||
const matches = useMedia('(max-width: 768px)', true);
|
||||
|
||||
return (
|
||||
<>
|
||||
<div className="flex flex-col gap-4">
|
||||
<h2 className="flex flex-row place-items-center gap-2 break-all text-2xl font-bold">
|
||||
<span>{generateIcon(kind)}</span>
|
||||
{name}
|
||||
</h2>
|
||||
{subHeading}
|
||||
<Section dense={matches} icon={<VscListSelection size={20} />} padded title="Summary">
|
||||
{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" />
|
||||
</Section>
|
||||
<SyntaxHighlighter code={excerpt} />
|
||||
{extendsTokens?.length ? (
|
||||
<div className="flex flex-row place-items-center gap-4">
|
||||
<h3 className="text-xl font-bold">Extends</h3>
|
||||
<span className="break-all font-mono">
|
||||
<HyperlinkedText tokens={extendsTokens} />
|
||||
</span>
|
||||
</div>
|
||||
) : null}
|
||||
{implementsTokens?.length ? (
|
||||
<div className="flex flex-row place-items-center gap-4">
|
||||
<h3 className="text-xl font-bold">Implements</h3>
|
||||
<span className="break-all font-mono">
|
||||
{implementsTokens.map((token, idx) => (
|
||||
<Fragment key={idx}>
|
||||
<HyperlinkedText tokens={token} />
|
||||
{idx < implementsTokens.length - 1 ? ', ' : ''}
|
||||
</Fragment>
|
||||
))}
|
||||
</span>
|
||||
</div>
|
||||
) : null}
|
||||
<div className="flex flex-col gap-4">
|
||||
{typeParams?.length ? (
|
||||
<Section
|
||||
defaultClosed
|
||||
dense={matches}
|
||||
icon={<VscSymbolParameter size={20} />}
|
||||
padded
|
||||
title="Type Parameters"
|
||||
>
|
||||
<TypeParamTable data={typeParams} />
|
||||
</Section>
|
||||
) : null}
|
||||
{children}
|
||||
</div>
|
||||
</div>
|
||||
{(kind === 'Class' || kind === 'Interface') && (methods?.length || properties?.length) ? (
|
||||
<aside className="dark:bg-dark-600 dark:border-dark-100 border-light-800 fixed top-[72px] right-0 bottom-0 z-20 hidden h-[calc(100vh_-_72px)] w-64 border-l bg-white pr-2 xl:block">
|
||||
<Scrollbars
|
||||
autoHide
|
||||
hideTracksWhenNotNeeded
|
||||
renderThumbVertical={(props) => <div {...props} className="dark:bg-dark-100 bg-light-900 z-30 rounded" />}
|
||||
renderTrackVertical={(props) => (
|
||||
<div {...props} className="absolute top-0.5 right-0.5 bottom-0.5 z-30 w-1.5 rounded" />
|
||||
)}
|
||||
universal
|
||||
>
|
||||
<TableOfContentItems methods={methods ?? []} properties={properties ?? []} />
|
||||
</Scrollbars>
|
||||
</aside>
|
||||
) : null}
|
||||
</>
|
||||
);
|
||||
}
|
||||
42
apps/website/src/components/ExcerptText.tsx
Normal file
42
apps/website/src/components/ExcerptText.tsx
Normal file
@@ -0,0 +1,42 @@
|
||||
import type { ApiModel, Excerpt } from '@microsoft/api-extractor-model';
|
||||
import { ExcerptTokenKind } from '@microsoft/api-extractor-model';
|
||||
import { ItemLink } from './ItemLink';
|
||||
import { resolveItemURI } from './documentation/util';
|
||||
|
||||
export interface ExcerptTextProps {
|
||||
/**
|
||||
* The tokens to render.
|
||||
*/
|
||||
excerpt: Excerpt;
|
||||
/**
|
||||
* The model to resolve item references from.
|
||||
*/
|
||||
model: ApiModel;
|
||||
}
|
||||
|
||||
/**
|
||||
* A component that renders excerpt tokens from an api item.
|
||||
*/
|
||||
export function ExcerptText({ model, excerpt }: ExcerptTextProps) {
|
||||
return (
|
||||
<>
|
||||
{excerpt.spannedTokens.map((token) => {
|
||||
if (token.kind === ExcerptTokenKind.Reference) {
|
||||
const item = model.resolveDeclarationReference(token.canonicalReference!, model).resolvedApiItem;
|
||||
|
||||
if (!item) {
|
||||
return token.text;
|
||||
}
|
||||
|
||||
return (
|
||||
<ItemLink className="text-blurple" itemURI={resolveItemURI(item)} key={item.containerKey}>
|
||||
{token.text}
|
||||
</ItemLink>
|
||||
);
|
||||
}
|
||||
|
||||
return token.text;
|
||||
})}
|
||||
</>
|
||||
);
|
||||
}
|
||||
@@ -1,26 +0,0 @@
|
||||
'use client';
|
||||
|
||||
import type { TokenDocumentation } from '@discordjs/api-extractor-utils';
|
||||
import Link from 'next/link';
|
||||
|
||||
export function HyperlinkedText({ tokens }: { tokens: TokenDocumentation[] }) {
|
||||
return (
|
||||
<>
|
||||
{tokens.map((token, idx) => {
|
||||
if (token.path) {
|
||||
return (
|
||||
<Link
|
||||
className="text-blurple focus:ring-width-2 focus:ring-blurple rounded outline-0 focus:ring"
|
||||
href={token.path}
|
||||
key={idx}
|
||||
>
|
||||
{token.text}
|
||||
</Link>
|
||||
);
|
||||
}
|
||||
|
||||
return <span key={idx}>{token.text}</span>;
|
||||
})}
|
||||
</>
|
||||
);
|
||||
}
|
||||
@@ -1,18 +1,17 @@
|
||||
'use client';
|
||||
import type { ApiDeclaredItem } from '@microsoft/api-extractor-model';
|
||||
import { ItemLink } from './ItemLink';
|
||||
import { resolveItemURI } from './documentation/util';
|
||||
|
||||
import type { InheritanceData } from '@discordjs/api-extractor-utils';
|
||||
import Link from 'next/link';
|
||||
|
||||
export function InheritanceText({ data }: { data: InheritanceData }) {
|
||||
export function InheritanceText({ parent }: { parent: ApiDeclaredItem }) {
|
||||
return (
|
||||
<span className="font-semibold">
|
||||
Inherited from{' '}
|
||||
<Link
|
||||
<ItemLink
|
||||
className="text-blurple focus:ring-width-2 focus:ring-blurple rounded font-mono outline-0 focus:ring"
|
||||
href={data.path}
|
||||
itemURI={resolveItemURI(parent)}
|
||||
>
|
||||
{data.parentName}
|
||||
</Link>
|
||||
{parent.displayName}
|
||||
</ItemLink>
|
||||
</span>
|
||||
);
|
||||
}
|
||||
|
||||
42
apps/website/src/components/ItemLink.tsx
Normal file
42
apps/website/src/components/ItemLink.tsx
Normal file
@@ -0,0 +1,42 @@
|
||||
'use client';
|
||||
|
||||
import type { LinkProps } from 'next/link';
|
||||
import Link from 'next/link';
|
||||
import { usePathname } from 'next/navigation';
|
||||
import type { PropsWithChildren } from 'react';
|
||||
|
||||
export interface ItemLinkProps
|
||||
extends Omit<LinkProps, 'href'>,
|
||||
React.RefAttributes<HTMLAnchorElement>,
|
||||
Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, keyof LinkProps> {
|
||||
className?: string;
|
||||
|
||||
/**
|
||||
* The URI of the api item to link to. (e.g. `/RestManager`)
|
||||
*/
|
||||
itemURI: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* A component that renders a link to an api item.
|
||||
*
|
||||
* @remarks
|
||||
* This component only needs the relative path to the item, and will automatically
|
||||
* generate the full path to the item client-side.
|
||||
*/
|
||||
export function ItemLink(props: PropsWithChildren<ItemLinkProps>) {
|
||||
const path = usePathname();
|
||||
|
||||
if (!path) {
|
||||
throw new Error('ItemLink must be used inside a Next.js page. (e.g. /docs/packages/foo/main)');
|
||||
}
|
||||
|
||||
// Check if the item is already in the current path, if so keep the current path
|
||||
const end = path?.split('/')?.length < 6 ? path?.length : -1;
|
||||
|
||||
const pathPrefix = path?.split('/').slice(0, end).join('/');
|
||||
|
||||
const { itemURI, ...linkProps } = props;
|
||||
|
||||
return <Link href={`${pathPrefix}${itemURI}`} {...linkProps} />;
|
||||
}
|
||||
@@ -1,124 +0,0 @@
|
||||
'use client';
|
||||
|
||||
import type { ApiMethodJSON, ApiMethodSignatureJSON } from '@discordjs/api-extractor-utils';
|
||||
import { FiLink } from '@react-icons/all-files/fi/FiLink';
|
||||
import { VscChevronDown } from '@react-icons/all-files/vsc/VscChevronDown';
|
||||
import { VscVersions } from '@react-icons/all-files/vsc/VscVersions';
|
||||
import { Menu, MenuButton, MenuItem, useMenuState } from 'ariakit/menu';
|
||||
import { useCallback, useMemo, useState } from 'react';
|
||||
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],
|
||||
);
|
||||
|
||||
const getShorthandName = useCallback(
|
||||
(data: ApiMethodJSON | ApiMethodSignatureJSON) =>
|
||||
`${data.name}${data.optional ? '?' : ''}(${data.parameters.reduce((prev, cur, index) => {
|
||||
if (index === 0) {
|
||||
return `${prev}${cur.isOptional ? `${cur.name}?` : cur.name}`;
|
||||
}
|
||||
|
||||
return `${prev}, ${cur.isOptional ? `${cur.name}?` : cur.name}`;
|
||||
}, '')})`,
|
||||
[],
|
||||
);
|
||||
|
||||
return (
|
||||
<div className="scroll-mt-30 flex flex-col gap-4" id={key}>
|
||||
<div className="flex flex-col">
|
||||
<div className="flex flex-col gap-2 md:-ml-9 md:flex-row md:place-items-center">
|
||||
<a
|
||||
aria-label="Anchor"
|
||||
className="focus:ring-width-2 focus:ring-blurple hidden rounded outline-0 focus:ring md:inline-block"
|
||||
href={`#${key}`}
|
||||
>
|
||||
<FiLink size={20} />
|
||||
</a>
|
||||
{data.deprecated ||
|
||||
(data.kind === 'Method' && method.protected) ||
|
||||
(data.kind === 'Method' && method.static) ? (
|
||||
<div className="flex flex-row gap-1">
|
||||
{data.deprecated ? (
|
||||
<div className="flex h-5 flex-row place-content-center place-items-center rounded-full bg-red-500 px-3 text-center text-xs font-semibold uppercase text-white">
|
||||
Deprecated
|
||||
</div>
|
||||
) : null}
|
||||
{data.kind === 'Method' && method.protected ? (
|
||||
<div className="bg-blurple flex h-5 flex-row place-content-center place-items-center rounded-full px-3 text-center text-xs font-semibold uppercase text-white">
|
||||
Protected
|
||||
</div>
|
||||
) : null}
|
||||
{data.kind === 'Method' && method.static ? (
|
||||
<div className="bg-blurple flex h-5 flex-row place-content-center place-items-center rounded-full px-3 text-center text-xs font-semibold uppercase text-white">
|
||||
Static
|
||||
</div>
|
||||
) : null}
|
||||
</div>
|
||||
) : null}
|
||||
<div className="flex flex-row flex-wrap gap-1">
|
||||
<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
|
||||
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 focus:ring-width-2 focus:ring-blurple rounded p-3 outline-0 focus:ring"
|
||||
state={menu}
|
||||
>
|
||||
<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
|
||||
className="dark:bg-dark-600 border-light-800 dark:border-dark-100 focus:ring-width-2 focus:ring-blurple z-20 flex flex-col rounded border bg-white p-1 outline-0 focus:ring"
|
||||
state={menu}
|
||||
>
|
||||
{data.mergedSiblings.map((_, idx) => (
|
||||
<MenuItem
|
||||
className="hover:bg-light-700 active:bg-light-800 dark:bg-dark-600 dark:hover:bg-dark-500 dark:active:bg-dark-400 focus:ring-width-2 focus:ring-blurple my-0.5 cursor-pointer rounded bg-white p-3 text-sm outline-0 focus:ring"
|
||||
key={idx}
|
||||
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">
|
||||
{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}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -1,24 +0,0 @@
|
||||
'use client';
|
||||
|
||||
import type { ApiMethodJSON, ApiMethodSignatureJSON } from '@discordjs/api-extractor-utils';
|
||||
import { Fragment, useMemo } from 'react';
|
||||
import { MethodItem } from './MethodItem';
|
||||
|
||||
export function MethodList({ data }: { data: (ApiMethodJSON | ApiMethodSignatureJSON)[] }) {
|
||||
const methodItems = useMemo(
|
||||
() =>
|
||||
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],
|
||||
);
|
||||
|
||||
return <div className="flex flex-col gap-4">{methodItems}</div>;
|
||||
}
|
||||
3
apps/website/src/components/NameText.tsx
Normal file
3
apps/website/src/components/NameText.tsx
Normal file
@@ -0,0 +1,3 @@
|
||||
export function NameText({ name }: { name: string }) {
|
||||
return <h4 className="break-all font-mono text-lg font-bold">{name}</h4>;
|
||||
}
|
||||
@@ -1,13 +1,13 @@
|
||||
'use client';
|
||||
|
||||
import type { getMembers } from '@discordjs/api-extractor-utils';
|
||||
import { Scrollbars } from 'react-custom-scrollbars-2';
|
||||
import { PackageSelect } from './PackageSelect';
|
||||
import { SidebarItems } from './SidebarItems';
|
||||
import { Sidebar } from './Sidebar';
|
||||
import type { SidebarSectionItemData } from './Sidebar';
|
||||
import { VersionSelect } from './VersionSelect';
|
||||
import { useNav } from '~/contexts/nav';
|
||||
|
||||
export function Nav({ members }: { members: ReturnType<typeof getMembers> }) {
|
||||
export function Nav({ members }: { members: SidebarSectionItemData[] }) {
|
||||
// eslint-disable-next-line @typescript-eslint/unbound-method
|
||||
const { opened } = useNav();
|
||||
|
||||
@@ -30,7 +30,7 @@ export function Nav({ members }: { members: ReturnType<typeof getMembers> }) {
|
||||
<PackageSelect />
|
||||
<VersionSelect />
|
||||
</div>
|
||||
<SidebarItems members={members} />
|
||||
<Sidebar members={members} />
|
||||
</Scrollbars>
|
||||
</nav>
|
||||
);
|
||||
|
||||
23
apps/website/src/components/Outline.tsx
Normal file
23
apps/website/src/components/Outline.tsx
Normal file
@@ -0,0 +1,23 @@
|
||||
'use client';
|
||||
|
||||
import { Scrollbars } from './Scrollbars';
|
||||
import type { TableOfContentsSerialized } from './TableOfContentItems';
|
||||
import { TableOfContentItems } from './TableOfContentItems';
|
||||
|
||||
export function Outline({ members }: { members: TableOfContentsSerialized[] }) {
|
||||
return (
|
||||
<aside className="dark:bg-dark-600 dark:border-dark-100 border-light-800 fixed top-[57px] right-0 bottom-0 z-20 hidden h-[calc(100vh_-_72px)] w-64 border-l bg-white pr-2 xl:block">
|
||||
<Scrollbars
|
||||
autoHide
|
||||
hideTracksWhenNotNeeded
|
||||
renderThumbVertical={(props) => <div {...props} className="dark:bg-dark-100 bg-light-900 z-30 rounded" />}
|
||||
renderTrackVertical={(props) => (
|
||||
<div {...props} className="absolute top-0.5 right-0.5 bottom-0.5 z-30 w-1.5 rounded" />
|
||||
)}
|
||||
universal
|
||||
>
|
||||
<TableOfContentItems serializedMembers={members} />
|
||||
</Scrollbars>
|
||||
</aside>
|
||||
);
|
||||
}
|
||||
54
apps/website/src/components/OverloadSwitcher.tsx
Normal file
54
apps/website/src/components/OverloadSwitcher.tsx
Normal file
@@ -0,0 +1,54 @@
|
||||
'use client';
|
||||
|
||||
import { VscChevronDown } from '@react-icons/all-files/vsc/VscChevronDown';
|
||||
import { VscVersions } from '@react-icons/all-files/vsc/VscVersions';
|
||||
import { Menu, MenuButton, MenuItem, useMenuState } from 'ariakit';
|
||||
import type { PropsWithChildren, ReactNode } from 'react';
|
||||
import { useState } from 'react';
|
||||
|
||||
export interface OverloadSwitcherProps {
|
||||
overloads: ReactNode[];
|
||||
}
|
||||
|
||||
export function OverloadSwitcher({ overloads, children }: PropsWithChildren<{ overloads: ReactNode[] }>) {
|
||||
const [overloadIndex, setOverloadIndex] = useState(1);
|
||||
const overloadedNode = overloads[overloadIndex - 1]!;
|
||||
const menu = useMenuState({ gutter: 8, sameWidth: true, fitViewport: true });
|
||||
|
||||
return (
|
||||
<div className="flex flex-col place-items-start gap-2">
|
||||
<MenuButton
|
||||
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 focus:ring-width-2 focus:ring-blurple rounded p-3 outline-0 focus:ring"
|
||||
state={menu}
|
||||
>
|
||||
<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 ${overloads.length}`}
|
||||
</div>
|
||||
<VscChevronDown
|
||||
className={`transform transition duration-150 ease-in-out ${menu.open ? 'rotate-180' : 'rotate-0'}`}
|
||||
size={20}
|
||||
/>
|
||||
</div>
|
||||
</MenuButton>
|
||||
<Menu
|
||||
className="dark:bg-dark-600 border-light-800 dark:border-dark-100 focus:ring-width-2 focus:ring-blurple z-20 flex flex-col rounded border bg-white p-1 outline-0 focus:ring"
|
||||
state={menu}
|
||||
>
|
||||
{overloads.map((_, idx) => (
|
||||
<MenuItem
|
||||
className="hover:bg-light-700 active:bg-light-800 dark:bg-dark-600 dark:hover:bg-dark-500 dark:active:bg-dark-400 focus:ring-width-2 focus:ring-blurple my-0.5 cursor-pointer rounded bg-white p-3 text-sm outline-0 focus:ring"
|
||||
key={idx}
|
||||
onClick={() => setOverloadIndex(idx + 1)}
|
||||
>
|
||||
{`Overload ${idx + 1}`}
|
||||
</MenuItem>
|
||||
))}
|
||||
</Menu>
|
||||
{children}
|
||||
{overloadedNode}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
10
apps/website/src/components/Panel.tsx
Normal file
10
apps/website/src/components/Panel.tsx
Normal file
@@ -0,0 +1,10 @@
|
||||
import type { PropsWithChildren } from 'react';
|
||||
|
||||
export function Panel({ children }: PropsWithChildren) {
|
||||
return (
|
||||
<>
|
||||
{children}
|
||||
<div className="border-light-900 dark:border-dark-100 -mx-8 border-t-2" />
|
||||
</>
|
||||
);
|
||||
}
|
||||
@@ -1,26 +1,24 @@
|
||||
'use client';
|
||||
|
||||
import type { ParameterDocumentation } from '@discordjs/api-extractor-utils';
|
||||
import type { ApiParameterListMixin } from '@microsoft/api-extractor-model';
|
||||
import { useMemo } from 'react';
|
||||
import { HyperlinkedText } from './HyperlinkedText';
|
||||
import { ExcerptText } from './ExcerptText';
|
||||
import { Table } from './Table';
|
||||
import { TSDoc } from './tsdoc/TSDoc';
|
||||
import { TSDoc } from './documentation/tsdoc/TSDoc';
|
||||
|
||||
const columnStyles = {
|
||||
Name: 'font-mono whitespace-nowrap',
|
||||
Type: 'font-mono whitespace-pre-wrap break-normal',
|
||||
};
|
||||
|
||||
export function ParameterTable({ data }: { data: ParameterDocumentation[] }) {
|
||||
export function ParameterTable({ item }: { item: ApiParameterListMixin }) {
|
||||
const rows = useMemo(
|
||||
() =>
|
||||
data.map((param) => ({
|
||||
item.parameters.map((param) => ({
|
||||
Name: param.name,
|
||||
Type: <HyperlinkedText tokens={param.tokens} />,
|
||||
Type: <ExcerptText excerpt={param.parameterTypeExcerpt} model={item.getAssociatedModel()!} />,
|
||||
Optional: param.isOptional ? 'Yes' : 'No',
|
||||
Description: param.paramCommentBlock ? <TSDoc node={param.paramCommentBlock} /> : 'None',
|
||||
Description: param.tsdocParamBlock ? <TSDoc item={item} tsdoc={param.tsdocParamBlock.content} /> : 'None',
|
||||
})),
|
||||
[data],
|
||||
[item],
|
||||
);
|
||||
|
||||
return (
|
||||
|
||||
69
apps/website/src/components/Property.tsx
Normal file
69
apps/website/src/components/Property.tsx
Normal file
@@ -0,0 +1,69 @@
|
||||
import type { ApiDeclaredItem, ApiItemContainerMixin, ApiPropertyItem } from '@microsoft/api-extractor-model';
|
||||
import type { PropsWithChildren } from 'react';
|
||||
import { Anchor } from './Anchor';
|
||||
import { ExcerptText } from './ExcerptText';
|
||||
import { InheritanceText } from './InheritanceText';
|
||||
import { TSDoc } from './documentation/tsdoc/TSDoc';
|
||||
|
||||
export enum PropertySeparatorType {
|
||||
Type = ':',
|
||||
Value = '=',
|
||||
}
|
||||
|
||||
export function Property({
|
||||
item,
|
||||
children,
|
||||
separator,
|
||||
inheritedFrom,
|
||||
}: PropsWithChildren<{
|
||||
inheritedFrom?: (ApiDeclaredItem & ApiItemContainerMixin) | undefined;
|
||||
item: ApiPropertyItem;
|
||||
separator?: PropertySeparatorType;
|
||||
}>) {
|
||||
const isDeprecated = Boolean(item.tsdocComment?.deprecatedBlock);
|
||||
const hasSummary = Boolean(item.tsdocComment?.summarySection);
|
||||
|
||||
return (
|
||||
<div className="scroll-mt-30 flex flex-col gap-4" id={item.displayName}>
|
||||
<div className="md:-ml-8.5 flex flex-col gap-2 md:flex-row md:place-items-center">
|
||||
<Anchor href={`#${item.displayName}`} />
|
||||
{isDeprecated || item.isReadonly || item.isOptional ? (
|
||||
<div className="flex flex-row gap-1">
|
||||
{isDeprecated ? (
|
||||
<div className="flex h-5 flex-row place-content-center place-items-center rounded-full bg-red-500 px-3 text-center text-xs font-semibold uppercase text-white">
|
||||
Deprecated
|
||||
</div>
|
||||
) : null}
|
||||
{item.isReadonly ? (
|
||||
<div className="bg-blurple flex h-5 flex-row place-content-center place-items-center rounded-full px-3 text-center text-xs font-semibold uppercase text-white">
|
||||
Readonly
|
||||
</div>
|
||||
) : null}
|
||||
{item.isOptional ? (
|
||||
<div className="bg-blurple flex h-5 flex-row place-content-center place-items-center rounded-full px-3 text-center text-xs font-semibold uppercase text-white">
|
||||
Optional
|
||||
</div>
|
||||
) : null}
|
||||
</div>
|
||||
) : null}
|
||||
<div className="flex flex-row flex-wrap place-items-center gap-1">
|
||||
<h4 className="break-all font-mono text-lg font-bold">
|
||||
{item.displayName}
|
||||
{item.isOptional ? '?' : ''}
|
||||
</h4>
|
||||
<h4 className="font-mono text-lg font-bold">{separator}</h4>
|
||||
<h4 className="break-all font-mono text-lg font-bold">
|
||||
<ExcerptText excerpt={item.propertyTypeExcerpt} model={item.getAssociatedModel()!} />
|
||||
</h4>
|
||||
</div>
|
||||
</div>
|
||||
{hasSummary || inheritedFrom ? (
|
||||
<div className="mb-4 flex flex-col gap-4">
|
||||
{item.tsdocComment ? <TSDoc item={item} tsdoc={item.tsdocComment} /> : null}
|
||||
{inheritedFrom ? <InheritanceText parent={inheritedFrom} /> : null}
|
||||
{children}
|
||||
</div>
|
||||
) : null}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -1,28 +1,38 @@
|
||||
'use client';
|
||||
|
||||
import type { ApiPropertyItemJSON } from '@discordjs/api-extractor-utils';
|
||||
import type {
|
||||
ApiDeclaredItem,
|
||||
ApiItem,
|
||||
ApiItemContainerMixin,
|
||||
ApiProperty,
|
||||
ApiPropertyItem,
|
||||
ApiPropertySignature,
|
||||
} from '@microsoft/api-extractor-model';
|
||||
import { ApiItemKind } from '@microsoft/api-extractor-model';
|
||||
import { Fragment, useMemo } from 'react';
|
||||
import { CodeListing } from './CodeListing';
|
||||
import { Property, PropertySeparatorType } from './Property';
|
||||
import { resolveMembers } from '~/util/members';
|
||||
|
||||
export function isPropertyLike(item: ApiItem): item is ApiProperty | ApiPropertySignature {
|
||||
return item.kind === ApiItemKind.Property || item.kind === ApiItemKind.PropertySignature;
|
||||
}
|
||||
|
||||
export function PropertyList({ item }: { item: ApiItemContainerMixin }) {
|
||||
const members = resolveMembers(item, isPropertyLike);
|
||||
|
||||
export function PropertyList({ data }: { data: ApiPropertyItemJSON[] }) {
|
||||
const propertyItems = useMemo(
|
||||
() =>
|
||||
data.map((prop) => (
|
||||
<Fragment key={prop.name}>
|
||||
<CodeListing
|
||||
comment={prop.comment}
|
||||
deprecation={prop.deprecated}
|
||||
inheritanceData={prop.inheritanceData}
|
||||
name={prop.name}
|
||||
optional={prop.optional}
|
||||
readonly={prop.readonly}
|
||||
summary={prop.summary}
|
||||
typeTokens={prop.propertyTypeTokens}
|
||||
/>
|
||||
<div className="border-light-900 dark:border-dark-100 -mx-8 border-t-2" />
|
||||
</Fragment>
|
||||
)),
|
||||
[data],
|
||||
members.map((prop) => {
|
||||
return (
|
||||
<Fragment key={prop.item.displayName}>
|
||||
<Property
|
||||
inheritedFrom={prop.inherited as ApiDeclaredItem & ApiItemContainerMixin}
|
||||
item={prop.item as ApiPropertyItem}
|
||||
separator={PropertySeparatorType.Type}
|
||||
/>
|
||||
<div className="border-light-900 dark:border-dark-100 -mx-8 border-t-2" />
|
||||
</Fragment>
|
||||
);
|
||||
}),
|
||||
[members],
|
||||
);
|
||||
|
||||
return <div className="flex flex-col gap-4">{propertyItems}</div>;
|
||||
|
||||
8
apps/website/src/components/Scrollbars.tsx
Normal file
8
apps/website/src/components/Scrollbars.tsx
Normal file
@@ -0,0 +1,8 @@
|
||||
'use client';
|
||||
|
||||
import type { ScrollbarProps } from 'react-custom-scrollbars-2';
|
||||
import { Scrollbars as ReactScrollbars2 } from 'react-custom-scrollbars-2';
|
||||
|
||||
export function Scrollbars(props: ScrollbarProps) {
|
||||
return <ReactScrollbars2 {...props} />;
|
||||
}
|
||||
16
apps/website/src/components/Section.tsx
Normal file
16
apps/website/src/components/Section.tsx
Normal file
@@ -0,0 +1,16 @@
|
||||
'use client';
|
||||
|
||||
import { Section as DJSSection, type SectionOptions } from '@discordjs/ui';
|
||||
import type { PropsWithChildren } from 'react';
|
||||
import { useMedia } from 'react-use';
|
||||
|
||||
// This is wrapper around the Section component from @discordjs/ui,
|
||||
// it simply automatically sets the dense prop to true if the screen
|
||||
// width is less than 768px. This is done to separate client-side logic
|
||||
// from server-side rendering.
|
||||
export function Section(options: PropsWithChildren<SectionOptions>) {
|
||||
const matches = useMedia('(max-width: 768px)', true);
|
||||
const modifiedOptions = { ...options, dense: matches };
|
||||
|
||||
return <DJSSection {...modifiedOptions} />;
|
||||
}
|
||||
@@ -1,99 +0,0 @@
|
||||
'use client';
|
||||
|
||||
import type {
|
||||
ApiClassJSON,
|
||||
ApiInterfaceJSON,
|
||||
ParameterDocumentation,
|
||||
ApiConstructorJSON,
|
||||
} from '@discordjs/api-extractor-utils';
|
||||
import { Section } from '@discordjs/ui';
|
||||
import { VscSymbolConstant } from '@react-icons/all-files/vsc/VscSymbolConstant';
|
||||
import { VscSymbolMethod } from '@react-icons/all-files/vsc/VscSymbolMethod';
|
||||
import { VscSymbolProperty } from '@react-icons/all-files/vsc/VscSymbolProperty';
|
||||
import { useMemo } from 'react';
|
||||
import { useMedia } from 'react-use';
|
||||
import { MethodList } from './MethodList';
|
||||
import { ParameterTable } from './ParameterTable';
|
||||
import { PropertyList } from './PropertyList';
|
||||
import { TSDoc } from './tsdoc/TSDoc';
|
||||
|
||||
export function PropertiesSection({ data }: { data: ApiClassJSON['properties'] | ApiInterfaceJSON['properties'] }) {
|
||||
const matches = useMedia('(max-width: 768px)', true);
|
||||
|
||||
return data.length ? (
|
||||
<Section dense={matches} icon={<VscSymbolProperty size={20} />} padded title="Properties">
|
||||
<PropertyList data={data} />
|
||||
</Section>
|
||||
) : null;
|
||||
}
|
||||
|
||||
export function MethodsSection({ data }: { data: ApiClassJSON['methods'] | ApiInterfaceJSON['methods'] }) {
|
||||
const matches = useMedia('(max-width: 768px)', true);
|
||||
|
||||
return data.length ? (
|
||||
<Section dense={matches} icon={<VscSymbolMethod size={20} />} padded title="Methods">
|
||||
<MethodList data={data} />
|
||||
</Section>
|
||||
) : null;
|
||||
}
|
||||
|
||||
export function ParametersSection({ data }: { data: ParameterDocumentation[] }) {
|
||||
const matches = useMedia('(max-width: 768px)', true);
|
||||
|
||||
return data.length ? (
|
||||
<Section dense={matches} icon={<VscSymbolConstant size={20} />} padded title="Parameters">
|
||||
<ParameterTable data={data} />
|
||||
</Section>
|
||||
) : null;
|
||||
}
|
||||
|
||||
export function ConstructorSection({ data }: { data: ApiConstructorJSON }) {
|
||||
const matches = useMedia('(max-width: 768px)', true);
|
||||
|
||||
const getShorthandName = useMemo(
|
||||
() =>
|
||||
`constructor(${data.parameters.reduce((prev, cur, index) => {
|
||||
if (index === 0) {
|
||||
return `${prev}${cur.isOptional ? `${cur.name}?` : cur.name}`;
|
||||
}
|
||||
|
||||
return `${prev}, ${cur.isOptional ? `${cur.name}?` : cur.name}`;
|
||||
}, '')})`,
|
||||
[data.parameters],
|
||||
);
|
||||
|
||||
return data.parameters.length ? (
|
||||
<Section dense={matches} icon={<VscSymbolMethod size={20} />} padded title="Constructor">
|
||||
<div className="scroll-mt-30 flex flex-col gap-4" id={data.name}>
|
||||
<div className="flex flex-col">
|
||||
<div className="flex flex-col gap-2 md:flex-row md:place-items-center">
|
||||
{data.deprecated || data.protected ? (
|
||||
<div className="flex flex-row gap-1">
|
||||
{data.deprecated ? (
|
||||
<div className="flex h-5 flex-row place-content-center place-items-center rounded-full bg-red-500 px-3 text-center text-xs font-semibold uppercase text-white">
|
||||
Deprecated
|
||||
</div>
|
||||
) : null}
|
||||
{data.protected ? (
|
||||
<div className="bg-blurple flex h-5 flex-row place-content-center place-items-center rounded-full px-3 text-center text-xs font-semibold uppercase text-white">
|
||||
Protected
|
||||
</div>
|
||||
) : null}
|
||||
</div>
|
||||
) : null}
|
||||
<h4 className="break-all font-mono text-lg font-bold">{getShorthandName}</h4>
|
||||
</div>
|
||||
</div>
|
||||
{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}
|
||||
</div>
|
||||
) : null}
|
||||
</div>
|
||||
</Section>
|
||||
) : null;
|
||||
}
|
||||
@@ -1,36 +1,41 @@
|
||||
'use client';
|
||||
|
||||
import type { getMembers } from '@discordjs/api-extractor-utils';
|
||||
import { Section } from '@discordjs/ui';
|
||||
import type { ApiItemKind } from '@microsoft/api-extractor-model';
|
||||
import { VscSymbolClass } from '@react-icons/all-files/vsc/VscSymbolClass';
|
||||
import { VscSymbolEnum } from '@react-icons/all-files/vsc/VscSymbolEnum';
|
||||
import { VscSymbolField } from '@react-icons/all-files/vsc/VscSymbolField';
|
||||
import { VscSymbolInterface } from '@react-icons/all-files/vsc/VscSymbolInterface';
|
||||
import { VscSymbolMethod } from '@react-icons/all-files/vsc/VscSymbolMethod';
|
||||
import { VscSymbolVariable } from '@react-icons/all-files/vsc/VscSymbolVariable';
|
||||
import Link from 'next/link';
|
||||
import { usePathname } from 'next/navigation';
|
||||
import { useMemo, useState, useEffect } from 'react';
|
||||
import { useMemo } from 'react';
|
||||
import { ItemLink } from './ItemLink';
|
||||
import { Section } from './Section';
|
||||
import { useNav } from '~/contexts/nav';
|
||||
|
||||
type Members = ReturnType<typeof getMembers>;
|
||||
|
||||
interface GroupedMembers {
|
||||
Classes: Members;
|
||||
Enums: Members;
|
||||
Functions: Members;
|
||||
Interfaces: Members;
|
||||
Types: Members;
|
||||
Variables: Members;
|
||||
export interface SidebarSectionItemData {
|
||||
href: string;
|
||||
kind: ApiItemKind;
|
||||
name: string;
|
||||
overloadIndex?: number | undefined;
|
||||
}
|
||||
|
||||
function groupMembers(members: Members): GroupedMembers {
|
||||
const Classes: Members = [];
|
||||
const Enums: Members = [];
|
||||
const Interfaces: Members = [];
|
||||
const Types: Members = [];
|
||||
const Variables: Members = [];
|
||||
const Functions: Members = [];
|
||||
interface GroupedMembers {
|
||||
Classes: SidebarSectionItemData[];
|
||||
Enums: SidebarSectionItemData[];
|
||||
Functions: SidebarSectionItemData[];
|
||||
Interfaces: SidebarSectionItemData[];
|
||||
Types: SidebarSectionItemData[];
|
||||
Variables: SidebarSectionItemData[];
|
||||
}
|
||||
|
||||
function groupMembers(members: readonly SidebarSectionItemData[]): GroupedMembers {
|
||||
const Classes: SidebarSectionItemData[] = [];
|
||||
const Enums: SidebarSectionItemData[] = [];
|
||||
const Interfaces: SidebarSectionItemData[] = [];
|
||||
const Types: SidebarSectionItemData[] = [];
|
||||
const Variables: SidebarSectionItemData[] = [];
|
||||
const Functions: SidebarSectionItemData[] = [];
|
||||
|
||||
for (const member of members) {
|
||||
switch (member.kind) {
|
||||
@@ -60,7 +65,7 @@ function groupMembers(members: Members): GroupedMembers {
|
||||
return { Classes, Functions, Enums, Interfaces, Types, Variables };
|
||||
}
|
||||
|
||||
function resolveIcon(item: keyof GroupedMembers) {
|
||||
function resolveIcon(item: string) {
|
||||
switch (item) {
|
||||
case 'Classes':
|
||||
return <VscSymbolClass size={20} />;
|
||||
@@ -77,15 +82,11 @@ function resolveIcon(item: keyof GroupedMembers) {
|
||||
}
|
||||
}
|
||||
|
||||
export function SidebarItems({ members }: { members: Members }) {
|
||||
export function Sidebar({ members }: { members: SidebarSectionItemData[] }) {
|
||||
const pathname = usePathname();
|
||||
const [asPathWithoutQueryAndAnchor, setAsPathWithoutQueryAndAnchor] = useState('');
|
||||
const asPathWithoutQueryAndAnchor = `/${pathname?.split('/').splice(-1) ?? ''}`;
|
||||
const { setOpened } = useNav();
|
||||
|
||||
useEffect(() => {
|
||||
setAsPathWithoutQueryAndAnchor(pathname?.split('?')[0]?.split('#')[0] ?? '');
|
||||
}, [pathname]);
|
||||
|
||||
const groupItems = useMemo(() => groupMembers(members), [members]);
|
||||
|
||||
return (
|
||||
@@ -95,13 +96,13 @@ export function SidebarItems({ members }: { members: Members }) {
|
||||
.map((group, idx) => (
|
||||
<Section icon={resolveIcon(group)} key={idx} title={group}>
|
||||
{groupItems[group].map((member, index) => (
|
||||
<Link
|
||||
<ItemLink
|
||||
className={`dark:border-dark-100 border-light-800 focus:ring-width-2 focus:ring-blurple ml-5 flex flex-col border-l p-[5px] pl-6 outline-0 focus:rounded focus:border-0 focus:ring ${
|
||||
asPathWithoutQueryAndAnchor === member.path
|
||||
asPathWithoutQueryAndAnchor === member.href
|
||||
? 'bg-blurple text-white'
|
||||
: 'dark:hover:bg-dark-200 dark:active:bg-dark-100 hover:bg-light-700 active:bg-light-800'
|
||||
}`}
|
||||
href={member.path}
|
||||
itemURI={member.href}
|
||||
key={index}
|
||||
onClick={() => setOpened(false)}
|
||||
title={member.name}
|
||||
@@ -112,7 +113,7 @@ export function SidebarItems({ members }: { members: Members }) {
|
||||
<span className="text-xs">{member.overloadIndex}</span>
|
||||
) : null}
|
||||
</div>
|
||||
</Link>
|
||||
</ItemLink>
|
||||
))}
|
||||
</Section>
|
||||
))}
|
||||
10
apps/website/src/components/SignatureText.tsx
Normal file
10
apps/website/src/components/SignatureText.tsx
Normal file
@@ -0,0 +1,10 @@
|
||||
import type { ApiModel, Excerpt } from '@microsoft/api-extractor-model';
|
||||
import { ExcerptText } from './ExcerptText';
|
||||
|
||||
export function SignatureText({ excerpt, model }: { excerpt: Excerpt; model: ApiModel }) {
|
||||
return (
|
||||
<h4 className="break-all font-mono text-lg font-bold">
|
||||
<ExcerptText excerpt={excerpt} model={model} />
|
||||
</h4>
|
||||
);
|
||||
}
|
||||
@@ -1,5 +1,3 @@
|
||||
'use client';
|
||||
|
||||
import { useMemo, type ReactNode } from 'react';
|
||||
|
||||
export function Table({
|
||||
|
||||
@@ -1,59 +1,88 @@
|
||||
'use client';
|
||||
|
||||
import type { ApiClassJSON, ApiInterfaceJSON } from '@discordjs/api-extractor-utils';
|
||||
import { VscListSelection } from '@react-icons/all-files/vsc/VscListSelection';
|
||||
import { VscSymbolMethod } from '@react-icons/all-files/vsc/VscSymbolMethod';
|
||||
import { VscSymbolProperty } from '@react-icons/all-files/vsc/VscSymbolProperty';
|
||||
import { useMemo } from 'react';
|
||||
|
||||
export function TableOfContentItems({
|
||||
methods,
|
||||
properties,
|
||||
}: {
|
||||
methods: ApiClassJSON['methods'] | ApiInterfaceJSON['methods'];
|
||||
properties: ApiClassJSON['properties'] | ApiInterfaceJSON['properties'];
|
||||
}) {
|
||||
export interface TableOfContentsSerializedMethod {
|
||||
kind: 'Method' | 'MethodSignature';
|
||||
name: string;
|
||||
overloadIndex?: number;
|
||||
}
|
||||
|
||||
export interface TableOfContentsSerializedProperty {
|
||||
kind: 'Property' | 'PropertySignature';
|
||||
name: string;
|
||||
}
|
||||
|
||||
export type TableOfContentsSerialized = TableOfContentsSerializedMethod | TableOfContentsSerializedProperty;
|
||||
|
||||
export interface TableOfContentsItemProps {
|
||||
serializedMembers: TableOfContentsSerialized[];
|
||||
}
|
||||
|
||||
export function TableOfContentsPropertyItem({ property }: { property: TableOfContentsSerializedProperty }) {
|
||||
return (
|
||||
<a
|
||||
className="dark:border-dark-100 border-light-800 dark:hover:bg-dark-200 dark:active:bg-dark-100 hover:bg-light-700 active:bg-light-800 pl-6.5 focus:ring-width-2 focus:ring-blurple ml-[10px] border-l p-[5px] text-sm outline-0 focus:rounded focus:border-0 focus:ring"
|
||||
href={`#${property.name}`}
|
||||
key={property.name}
|
||||
title={property.name}
|
||||
>
|
||||
<span className="line-clamp-1">{property.name}</span>
|
||||
</a>
|
||||
);
|
||||
}
|
||||
|
||||
export function TableOfContentsMethodItem({ method }: { method: TableOfContentsSerializedMethod }) {
|
||||
if (method.overloadIndex && method.overloadIndex > 1) {
|
||||
return null;
|
||||
}
|
||||
|
||||
const key = `${method.name}${method.overloadIndex && method.overloadIndex > 1 ? `:${method.overloadIndex}` : ''}`;
|
||||
|
||||
return (
|
||||
<a
|
||||
className="dark:border-dark-100 border-light-800 dark:hover:bg-dark-200 dark:active:bg-dark-100 hover:bg-light-700 active:bg-light-800 pl-6.5 focus:ring-width-2 focus:ring-blurple ml-[10px] flex flex-row place-items-center gap-2 border-l p-[5px] text-sm outline-0 focus:rounded focus:border-0 focus:ring"
|
||||
href={`#${key}`}
|
||||
key={key}
|
||||
title={method.name}
|
||||
>
|
||||
<span className="line-clamp-1">{method.name}</span>
|
||||
{method.overloadIndex && method.overloadIndex > 1 ? (
|
||||
<span className="text-xs">{method.overloadIndex}</span>
|
||||
) : null}
|
||||
</a>
|
||||
);
|
||||
}
|
||||
|
||||
export function TableOfContentItems({ serializedMembers }: TableOfContentsItemProps) {
|
||||
const propertyItems = useMemo(
|
||||
() =>
|
||||
properties.map((prop) => (
|
||||
<a
|
||||
className="dark:border-dark-100 border-light-800 dark:hover:bg-dark-200 dark:active:bg-dark-100 hover:bg-light-700 active:bg-light-800 pl-6.5 focus:ring-width-2 focus:ring-blurple ml-[10px] border-l p-[5px] text-sm outline-0 focus:rounded focus:border-0 focus:ring"
|
||||
href={`#${prop.name}`}
|
||||
key={prop.name}
|
||||
title={prop.name}
|
||||
>
|
||||
<span className="line-clamp-1">{prop.name}</span>
|
||||
</a>
|
||||
)),
|
||||
[properties],
|
||||
serializedMembers
|
||||
.filter(
|
||||
(member): member is TableOfContentsSerializedProperty =>
|
||||
member.kind === 'Property' || member.kind === 'PropertySignature',
|
||||
)
|
||||
.map((prop) => <TableOfContentsPropertyItem key={prop.name} property={prop} />),
|
||||
[serializedMembers],
|
||||
);
|
||||
|
||||
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}` : ''
|
||||
}`;
|
||||
|
||||
return (
|
||||
<a
|
||||
className="dark:border-dark-100 border-light-800 dark:hover:bg-dark-200 dark:active:bg-dark-100 hover:bg-light-700 active:bg-light-800 pl-6.5 focus:ring-width-2 focus:ring-blurple ml-[10px] flex flex-row place-items-center gap-2 border-l p-[5px] text-sm outline-0 focus:rounded focus:border-0 focus:ring"
|
||||
href={`#${key}`}
|
||||
key={key}
|
||||
title={member.name}
|
||||
>
|
||||
<span className="line-clamp-1">{member.name}</span>
|
||||
{member.overloadIndex && member.overloadIndex > 1 ? (
|
||||
<span className="text-xs">{member.overloadIndex}</span>
|
||||
) : null}
|
||||
</a>
|
||||
);
|
||||
}),
|
||||
[methods],
|
||||
serializedMembers
|
||||
.filter(
|
||||
(member): member is TableOfContentsSerializedMethod =>
|
||||
member.kind === 'Method' || member.kind === 'MethodSignature',
|
||||
)
|
||||
.map((member) => (
|
||||
<TableOfContentsMethodItem
|
||||
key={`${member.name}${member.overloadIndex ? `:${member.overloadIndex}` : ''}`}
|
||||
method={member}
|
||||
/>
|
||||
)),
|
||||
[serializedMembers],
|
||||
);
|
||||
|
||||
return (
|
||||
|
||||
@@ -1,10 +1,8 @@
|
||||
'use client';
|
||||
|
||||
import type { TypeParameterData } from '@discordjs/api-extractor-utils';
|
||||
import type { ApiTypeParameterListMixin } from '@microsoft/api-extractor-model';
|
||||
import { useMemo } from 'react';
|
||||
import { HyperlinkedText } from './HyperlinkedText';
|
||||
import { ExcerptText } from './ExcerptText';
|
||||
import { Table } from './Table';
|
||||
import { TSDoc } from './tsdoc/TSDoc';
|
||||
import { TSDoc } from './documentation/tsdoc/TSDoc';
|
||||
|
||||
const rowElements = {
|
||||
Name: 'font-mono whitespace-nowrap',
|
||||
@@ -12,17 +10,22 @@ const rowElements = {
|
||||
Default: 'font-mono whitespace-pre break-normal',
|
||||
};
|
||||
|
||||
export function TypeParamTable({ data }: { data: TypeParameterData[] }) {
|
||||
export function TypeParamTable({ item }: { item: ApiTypeParameterListMixin }) {
|
||||
const model = item.getAssociatedModel()!;
|
||||
const rows = useMemo(
|
||||
() =>
|
||||
data.map((typeParam) => ({
|
||||
item.typeParameters.map((typeParam) => ({
|
||||
Name: typeParam.name,
|
||||
Constraints: <HyperlinkedText tokens={typeParam.constraintTokens} />,
|
||||
Optional: typeParam.optional ? 'Yes' : 'No',
|
||||
Default: <HyperlinkedText tokens={typeParam.defaultTokens} />,
|
||||
Description: typeParam.commentBlock ? <TSDoc node={typeParam.commentBlock} /> : 'None',
|
||||
Constraints: <ExcerptText excerpt={typeParam.constraintExcerpt} model={model} />,
|
||||
Optional: typeParam.isOptional ? 'Yes' : 'No',
|
||||
Default: <ExcerptText excerpt={typeParam.defaultTypeExcerpt} model={model} />,
|
||||
Description: typeParam.tsdocTypeParamBlock ? (
|
||||
<TSDoc item={item} tsdoc={typeParam.tsdocTypeParamBlock.content} />
|
||||
) : (
|
||||
'None'
|
||||
),
|
||||
})),
|
||||
[data],
|
||||
[item, model],
|
||||
);
|
||||
|
||||
return (
|
||||
|
||||
@@ -0,0 +1,8 @@
|
||||
import type { PropsWithChildren } from 'react';
|
||||
|
||||
/**
|
||||
* Layout parent of documentation pages.
|
||||
*/
|
||||
export function Documentation({ children }: PropsWithChildren) {
|
||||
return <div className="w-full flex-col space-y-4">{children}</div>;
|
||||
}
|
||||
36
apps/website/src/components/documentation/Header.tsx
Normal file
36
apps/website/src/components/documentation/Header.tsx
Normal file
@@ -0,0 +1,36 @@
|
||||
import { ApiItemKind } from '@microsoft/api-extractor-model';
|
||||
import { VscSymbolClass } from '@react-icons/all-files/vsc/VscSymbolClass';
|
||||
import { VscSymbolEnum } from '@react-icons/all-files/vsc/VscSymbolEnum';
|
||||
import { VscSymbolInterface } from '@react-icons/all-files/vsc/VscSymbolInterface';
|
||||
import { VscSymbolMethod } from '@react-icons/all-files/vsc/VscSymbolMethod';
|
||||
import { VscSymbolVariable } from '@react-icons/all-files/vsc/VscSymbolVariable';
|
||||
import type { PropsWithChildren } from 'react';
|
||||
|
||||
function generateIcon(kind: ApiItemKind) {
|
||||
switch (kind) {
|
||||
case ApiItemKind.Class:
|
||||
return <VscSymbolClass />;
|
||||
case ApiItemKind.Function:
|
||||
case ApiItemKind.Method:
|
||||
return <VscSymbolMethod />;
|
||||
case ApiItemKind.Enum:
|
||||
return <VscSymbolEnum />;
|
||||
case ApiItemKind.Interface:
|
||||
return <VscSymbolInterface />;
|
||||
case ApiItemKind.TypeAlias:
|
||||
return <VscSymbolVariable />;
|
||||
default:
|
||||
return <VscSymbolMethod />;
|
||||
}
|
||||
}
|
||||
|
||||
export function Header({ kind, name }: PropsWithChildren<{ kind: ApiItemKind; name: string }>) {
|
||||
return (
|
||||
<div className="flex flex-col">
|
||||
<h2 className="flex flex-row place-items-center gap-2 break-all text-2xl font-bold">
|
||||
<span>{generateIcon(kind)}</span>
|
||||
{name}
|
||||
</h2>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
51
apps/website/src/components/documentation/HierarchyText.tsx
Normal file
51
apps/website/src/components/documentation/HierarchyText.tsx
Normal file
@@ -0,0 +1,51 @@
|
||||
import type { ApiClass, ApiInterface, Excerpt } from '@microsoft/api-extractor-model';
|
||||
import { ApiItemKind } from '@microsoft/api-extractor-model';
|
||||
import { ExcerptText } from '../ExcerptText';
|
||||
|
||||
export function HierarchyText({ item, type }: { item: ApiClass | ApiInterface; type: 'Extends' | 'Implements' }) {
|
||||
const model = item.getAssociatedModel()!;
|
||||
|
||||
if (
|
||||
(item.kind === ApiItemKind.Class &&
|
||||
(item as ApiClass).extendsType === undefined &&
|
||||
(item as ApiClass).implementsTypes.length === 0) ||
|
||||
(item.kind === ApiItemKind.Interface && !(item as ApiInterface).extendsTypes)
|
||||
) {
|
||||
return null;
|
||||
}
|
||||
|
||||
let excerpts: Excerpt[];
|
||||
|
||||
if (item.kind === ApiItemKind.Class) {
|
||||
if (type === 'Implements') {
|
||||
if ((item as ApiClass).implementsTypes.length === 0) {
|
||||
return null;
|
||||
}
|
||||
|
||||
excerpts = (item as ApiClass).implementsTypes.map((typeExcerpt) => typeExcerpt.excerpt);
|
||||
} else {
|
||||
if (!(item as ApiClass).extendsType) {
|
||||
return null;
|
||||
}
|
||||
|
||||
excerpts = [(item as ApiClass).extendsType!.excerpt];
|
||||
}
|
||||
} else {
|
||||
if ((item as ApiInterface).extendsTypes.length === 0) {
|
||||
return null;
|
||||
}
|
||||
|
||||
excerpts = (item as ApiInterface).extendsTypes.map((typeExcerpt) => typeExcerpt.excerpt);
|
||||
}
|
||||
|
||||
return (
|
||||
<div className="flex flex-row place-items-center gap-4">
|
||||
<h3 className="text-xl font-bold">{type}</h3>
|
||||
<span className="space-y-2 break-all font-mono">
|
||||
{excerpts.map((excerpt, index) => (
|
||||
<ExcerptText excerpt={excerpt} key={index} model={model} />
|
||||
))}
|
||||
</span>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,33 @@
|
||||
import type { ApiDeclaredItem, ApiItemContainerMixin, ApiTypeParameterListMixin } from '@microsoft/api-extractor-model';
|
||||
import type { ReactNode } from 'react';
|
||||
import { Outline } from '../Outline';
|
||||
import { SyntaxHighlighter } from '../SyntaxHighlighter';
|
||||
import { Documentation } from './Documentation';
|
||||
import { MethodsSection } from './section/MethodsSection';
|
||||
import { PropertiesSection } from './section/PropertiesSection';
|
||||
import { SummarySection } from './section/SummarySection';
|
||||
import { TypeParameterSection } from './section/TypeParametersSection';
|
||||
import { hasProperties, hasMethods, serializeMembers } from './util';
|
||||
|
||||
export function MemberContainerDocumentation({
|
||||
item,
|
||||
version,
|
||||
subheading,
|
||||
}: {
|
||||
item: ApiDeclaredItem & ApiItemContainerMixin & ApiTypeParameterListMixin;
|
||||
subheading?: ReactNode;
|
||||
version: string;
|
||||
}) {
|
||||
return (
|
||||
<Documentation item={item}>
|
||||
{subheading}
|
||||
<SyntaxHighlighter code={item.excerpt.text} />
|
||||
<SummarySection item={item} />
|
||||
{item.typeParameters.length ? <TypeParameterSection item={item} /> : null}
|
||||
{hasProperties(item) ? <PropertiesSection item={item} /> : null}
|
||||
{hasMethods(item) ? <MethodsSection item={item} /> : null}
|
||||
|
||||
<Outline members={serializeMembers(item)} />
|
||||
</Documentation>
|
||||
);
|
||||
}
|
||||
13
apps/website/src/components/documentation/Members.tsx
Normal file
13
apps/website/src/components/documentation/Members.tsx
Normal file
@@ -0,0 +1,13 @@
|
||||
import type { ApiDeclaredItem, ApiItemContainerMixin } from '@microsoft/api-extractor-model';
|
||||
import { MethodsSection } from './section/MethodsSection';
|
||||
import { PropertiesSection } from './section/PropertiesSection';
|
||||
import { hasProperties, hasMethods } from './util';
|
||||
|
||||
export function Members({ item }: { item: ApiDeclaredItem & ApiItemContainerMixin }) {
|
||||
return (
|
||||
<>
|
||||
{hasProperties(item) ? <PropertiesSection item={item} /> : null}
|
||||
{hasMethods(item) ? <MethodsSection item={item} /> : null}
|
||||
</>
|
||||
);
|
||||
}
|
||||
18
apps/website/src/components/documentation/ObjectHeader.tsx
Normal file
18
apps/website/src/components/documentation/ObjectHeader.tsx
Normal file
@@ -0,0 +1,18 @@
|
||||
import type { ApiDeclaredItem, ApiItemContainerMixin } from '@microsoft/api-extractor-model';
|
||||
import { SyntaxHighlighter } from '../SyntaxHighlighter';
|
||||
import { Header } from './Header';
|
||||
import { SummarySection } from './section/SummarySection';
|
||||
|
||||
export interface ObjectHeaderProps {
|
||||
item: ApiDeclaredItem & ApiItemContainerMixin;
|
||||
}
|
||||
|
||||
export function ObjectHeader({ item }: ObjectHeaderProps) {
|
||||
return (
|
||||
<>
|
||||
<Header kind={item.kind} name={item.displayName} />
|
||||
<SyntaxHighlighter code={item.excerpt.text} />
|
||||
<SummarySection item={item} />
|
||||
</>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,30 @@
|
||||
import type { ApiConstructor } from '@microsoft/api-extractor-model';
|
||||
import { VscSymbolMethod } from '@react-icons/all-files/vsc/VscSymbolMethod';
|
||||
import { useCallback } from 'react';
|
||||
import { TSDoc } from '../tsdoc/TSDoc';
|
||||
import { ResponsiveSection } from './ResponsiveSection';
|
||||
import { ParameterTable } from '~/components/ParameterTable';
|
||||
|
||||
export function ConstructorSection({ item }: { item: ApiConstructor }) {
|
||||
const getShorthandName = useCallback(
|
||||
(ctor: ApiConstructor) =>
|
||||
`constructor(${ctor.parameters.reduce((prev, cur, index) => {
|
||||
if (index === 0) {
|
||||
return `${prev}${cur.isOptional ? `${cur.name}?` : cur.name}`;
|
||||
}
|
||||
|
||||
return `${prev}, ${cur.isOptional ? `${cur.name}?` : cur.name}`;
|
||||
}, '')})`,
|
||||
[],
|
||||
);
|
||||
|
||||
return (
|
||||
<ResponsiveSection icon={<VscSymbolMethod size={20} />} padded title="Constructor">
|
||||
<div className="flex flex-col gap-2">
|
||||
<h4 className="break-all font-mono text-lg font-bold">{getShorthandName(item)}</h4>
|
||||
{item.tsdocComment ? <TSDoc item={item} tsdoc={item.tsdocComment} /> : null}
|
||||
<ParameterTable item={item} />
|
||||
</div>
|
||||
</ResponsiveSection>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,45 @@
|
||||
import type {
|
||||
ApiDeclaredItem,
|
||||
ApiItem,
|
||||
ApiItemContainerMixin,
|
||||
ApiMethod,
|
||||
ApiMethodSignature,
|
||||
} from '@microsoft/api-extractor-model';
|
||||
import { ApiItemKind } from '@microsoft/api-extractor-model';
|
||||
import { VscSymbolMethod } from '@react-icons/all-files/vsc/VscSymbolMethod';
|
||||
import { useMemo, Fragment } from 'react';
|
||||
import { ResponsiveSection } from './ResponsiveSection';
|
||||
import { Method } from '~/components/model/method/Method';
|
||||
import { resolveMembers } from '~/util/members';
|
||||
|
||||
function isMethodLike(item: ApiItem): item is ApiMethod | ApiMethodSignature {
|
||||
return (
|
||||
item.kind === ApiItemKind.Method ||
|
||||
(item.kind === ApiItemKind.MethodSignature && (item as ApiMethod).overloadIndex <= 1)
|
||||
);
|
||||
}
|
||||
|
||||
export function MethodsSection({ item }: { item: ApiItemContainerMixin }) {
|
||||
const members = resolveMembers(item, isMethodLike);
|
||||
|
||||
const methodItems = useMemo(
|
||||
() =>
|
||||
members.map(({ item: method, inherited }) => (
|
||||
<Fragment
|
||||
key={`${method.displayName}${
|
||||
method.overloadIndex && method.overloadIndex > 1 ? `:${(method as ApiMethod).overloadIndex}` : ''
|
||||
}`}
|
||||
>
|
||||
<Method inheritedFrom={inherited as ApiDeclaredItem & ApiItemContainerMixin} method={method} />
|
||||
<div className="border-light-900 dark:border-dark-100 -mx-8 border-t-2" />
|
||||
</Fragment>
|
||||
)),
|
||||
[members],
|
||||
);
|
||||
|
||||
return (
|
||||
<ResponsiveSection icon={<VscSymbolMethod size={20} />} padded title="Methods">
|
||||
<div className="flex flex-col gap-4">{methodItems}</div>
|
||||
</ResponsiveSection>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
import type { ApiParameterListMixin } from '@microsoft/api-extractor-model';
|
||||
import { VscSymbolParameter } from '@react-icons/all-files/vsc/VscSymbolParameter';
|
||||
import { ResponsiveSection } from './ResponsiveSection';
|
||||
import { ParameterTable } from '~/components/ParameterTable';
|
||||
|
||||
export function ParameterSection({ item }: { item: ApiParameterListMixin }) {
|
||||
return (
|
||||
<ResponsiveSection icon={<VscSymbolParameter size={20} />} padded title="Parameters">
|
||||
<ParameterTable item={item} />
|
||||
</ResponsiveSection>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
import type { ApiItemContainerMixin } from '@microsoft/api-extractor-model';
|
||||
import { VscSymbolProperty } from '@react-icons/all-files/vsc/VscSymbolProperty';
|
||||
import { ResponsiveSection } from './ResponsiveSection';
|
||||
import { PropertyList } from '~/components/PropertyList';
|
||||
|
||||
export function PropertiesSection({ item }: { item: ApiItemContainerMixin }) {
|
||||
return (
|
||||
<ResponsiveSection icon={<VscSymbolProperty size={20} />} padded title="Properties">
|
||||
<PropertyList item={item} />
|
||||
</ResponsiveSection>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,24 @@
|
||||
'use client';
|
||||
|
||||
import type { SectionOptions } from '@discordjs/ui';
|
||||
import { Section } from '@discordjs/ui';
|
||||
import type { PropsWithChildren } from 'react';
|
||||
import { useMedia } from 'react-use';
|
||||
|
||||
export function ResponsiveSection(opts: PropsWithChildren<SectionOptions & { separator?: boolean }>) {
|
||||
const matches = useMedia('(max-width: 768px)', true);
|
||||
|
||||
const { children, separator, ...rest } = opts;
|
||||
|
||||
const props = {
|
||||
...rest,
|
||||
dense: matches,
|
||||
};
|
||||
|
||||
return (
|
||||
<Section {...props}>
|
||||
{children}
|
||||
{separator ? <div className="border-light-900 dark:border-dark-100 -mx-8 mt-6 border-t-2" /> : null}
|
||||
</Section>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,16 @@
|
||||
import type { ApiDeclaredItem } from '@microsoft/api-extractor-model';
|
||||
import { VscListSelection } from '@react-icons/all-files/vsc/VscListSelection';
|
||||
import { TSDoc } from '../tsdoc/TSDoc';
|
||||
import { ResponsiveSection } from './ResponsiveSection';
|
||||
|
||||
export function SummarySection({ item }: { item: ApiDeclaredItem }) {
|
||||
return (
|
||||
<ResponsiveSection icon={<VscListSelection size={20} />} padded separator title="Summary">
|
||||
{item.tsdocComment?.summarySection ? (
|
||||
<TSDoc item={item} tsdoc={item.tsdocComment} />
|
||||
) : (
|
||||
<p>No summary provided.</p>
|
||||
)}
|
||||
</ResponsiveSection>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,12 @@
|
||||
import type { ApiTypeParameterListMixin } from '@microsoft/api-extractor-model';
|
||||
import { VscSymbolParameter } from '@react-icons/all-files/vsc/VscSymbolParameter';
|
||||
import { ResponsiveSection } from './ResponsiveSection';
|
||||
import { TypeParamTable } from '~/components/TypeParamTable';
|
||||
|
||||
export function TypeParameterSection({ item }: { item: ApiTypeParameterListMixin }) {
|
||||
return (
|
||||
<ResponsiveSection icon={<VscSymbolParameter size={20} />} padded title="Type Parameters">
|
||||
<TypeParamTable item={item} />
|
||||
</ResponsiveSection>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,38 @@
|
||||
import { Alert } from '@discordjs/ui';
|
||||
import type { PropsWithChildren } from 'react';
|
||||
|
||||
export function Block({ children, title }: PropsWithChildren<{ title: string }>) {
|
||||
return (
|
||||
<div className="flex flex-col gap-2">
|
||||
<h5 className="font-bold">{title}</h5>
|
||||
{children}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
export function ExampleBlock({
|
||||
children,
|
||||
exampleIndex,
|
||||
}: PropsWithChildren<{ exampleIndex?: number | undefined }>): JSX.Element {
|
||||
return <Block title={`Example ${exampleIndex ? exampleIndex : ''}`}>{children}</Block>;
|
||||
}
|
||||
|
||||
export function DefaultValueBlock({ children }: PropsWithChildren): JSX.Element {
|
||||
return <Block title="Default value">{children}</Block>;
|
||||
}
|
||||
|
||||
export function RemarksBlock({ children }: PropsWithChildren): JSX.Element {
|
||||
return <Block title="Remarks">{children}</Block>;
|
||||
}
|
||||
|
||||
export function DeprecatedBlock({ children }: PropsWithChildren): JSX.Element {
|
||||
return (
|
||||
<Alert title="Deprecated" type="danger">
|
||||
{children}
|
||||
</Alert>
|
||||
);
|
||||
}
|
||||
|
||||
export function SeeBlock({ children }: PropsWithChildren): JSX.Element {
|
||||
return <Block title="See Also">{children}</Block>;
|
||||
}
|
||||
121
apps/website/src/components/documentation/tsdoc/TSDoc.tsx
Normal file
121
apps/website/src/components/documentation/tsdoc/TSDoc.tsx
Normal file
@@ -0,0 +1,121 @@
|
||||
import type { ApiItem } from '@microsoft/api-extractor-model';
|
||||
import type { DocComment, DocFencedCode, DocLinkTag, DocNode, DocNodeContainer, DocPlainText } from '@microsoft/tsdoc';
|
||||
import { DocNodeKind, StandardTags } from '@microsoft/tsdoc';
|
||||
import Link from 'next/link';
|
||||
import { Fragment, useCallback, type ReactNode } from 'react';
|
||||
import { SyntaxHighlighter } from '../../SyntaxHighlighter';
|
||||
import { resolveItemURI } from '../util';
|
||||
import { DeprecatedBlock, ExampleBlock, RemarksBlock, SeeBlock } from './BlockComment';
|
||||
import { ItemLink } from '~/components/ItemLink';
|
||||
|
||||
export function TSDoc({ item, tsdoc }: { item: ApiItem; tsdoc: DocNode }): JSX.Element {
|
||||
const createNode = useCallback(
|
||||
(tsdoc: DocNode, idx?: number): ReactNode => {
|
||||
switch (tsdoc.kind) {
|
||||
case DocNodeKind.PlainText:
|
||||
return (
|
||||
<span className="break-words" key={idx}>
|
||||
{(tsdoc as DocPlainText).text}
|
||||
</span>
|
||||
);
|
||||
case DocNodeKind.Section:
|
||||
case DocNodeKind.Paragraph:
|
||||
return (
|
||||
<span className="break-words leading-relaxed" key={idx}>
|
||||
{(tsdoc as DocNodeContainer).nodes.map((node, idx) => createNode(node, idx))}
|
||||
</span>
|
||||
);
|
||||
case DocNodeKind.SoftBreak:
|
||||
return <Fragment key={idx} />;
|
||||
case DocNodeKind.LinkTag: {
|
||||
const { codeDestination, urlDestination, linkText } = tsdoc as DocLinkTag;
|
||||
|
||||
if (codeDestination) {
|
||||
const foundItem = item
|
||||
.getAssociatedModel()
|
||||
?.resolveDeclarationReference(codeDestination, item).resolvedApiItem;
|
||||
|
||||
if (!foundItem) return null;
|
||||
|
||||
return (
|
||||
<ItemLink
|
||||
className="text-blurple focus:ring-width-2 focus:ring-blurple rounded font-mono outline-0 focus:ring"
|
||||
itemURI={resolveItemURI(foundItem)}
|
||||
key={idx}
|
||||
>
|
||||
{linkText ?? foundItem.displayName}
|
||||
</ItemLink>
|
||||
);
|
||||
}
|
||||
|
||||
if (urlDestination) {
|
||||
return (
|
||||
<Link
|
||||
className="text-blurple focus:ring-width-2 focus:ring-blurple rounded font-mono outline-0 focus:ring"
|
||||
href={urlDestination}
|
||||
key={idx}
|
||||
>
|
||||
{linkText ?? urlDestination}
|
||||
</Link>
|
||||
);
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
case DocNodeKind.CodeSpan: {
|
||||
const { code } = tsdoc as DocFencedCode;
|
||||
return (
|
||||
<code className="font-mono text-sm" key={idx}>
|
||||
{code}
|
||||
</code>
|
||||
);
|
||||
}
|
||||
|
||||
case DocNodeKind.FencedCode: {
|
||||
const { language, code } = tsdoc as DocFencedCode;
|
||||
return <SyntaxHighlighter code={code} key={idx} language={language} />;
|
||||
}
|
||||
|
||||
case DocNodeKind.Comment: {
|
||||
const comment = tsdoc as DocComment;
|
||||
|
||||
const exampleBlocks = comment.customBlocks.filter(
|
||||
(block) => block.blockTag.tagName.toUpperCase() === StandardTags.example.tagNameWithUpperCase,
|
||||
);
|
||||
|
||||
return (
|
||||
<div className="flex flex-col space-y-2">
|
||||
{comment.deprecatedBlock ? (
|
||||
<DeprecatedBlock>{createNode(comment.deprecatedBlock.content)}</DeprecatedBlock>
|
||||
) : null}
|
||||
{comment.summarySection ? createNode(comment.summarySection) : null}
|
||||
{comment.remarksBlock ? <RemarksBlock>{createNode(comment.remarksBlock.content)}</RemarksBlock> : null}
|
||||
{exampleBlocks.length
|
||||
? exampleBlocks.map((block, idx) => <ExampleBlock key={idx}>{createNode(block.content)}</ExampleBlock>)
|
||||
: null}
|
||||
{comment.seeBlocks.length ? (
|
||||
<SeeBlock>{comment.seeBlocks.map((seeBlock, idx) => createNode(seeBlock.content, idx))}</SeeBlock>
|
||||
) : null}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
default:
|
||||
// console.log(`Captured unknown node kind: ${node.kind}`);
|
||||
return null;
|
||||
}
|
||||
},
|
||||
[item],
|
||||
);
|
||||
|
||||
return (
|
||||
<>
|
||||
{tsdoc.kind === 'Paragraph' || tsdoc.kind === 'Section' ? (
|
||||
<>{(tsdoc as DocNodeContainer).nodes.map((node, idx) => createNode(node, idx))}</>
|
||||
) : (
|
||||
createNode(tsdoc)
|
||||
)}
|
||||
</>
|
||||
);
|
||||
}
|
||||
53
apps/website/src/components/documentation/util.ts
Normal file
53
apps/website/src/components/documentation/util.ts
Normal file
@@ -0,0 +1,53 @@
|
||||
import { ApiItemKind } from '@microsoft/api-extractor-model';
|
||||
import type {
|
||||
ApiItem,
|
||||
ApiItemContainerMixin,
|
||||
ApiMethod,
|
||||
ApiMethodSignature,
|
||||
ApiProperty,
|
||||
ApiPropertySignature,
|
||||
} from '@microsoft/api-extractor-model';
|
||||
import type { TableOfContentsSerialized } from '../TableOfContentItems';
|
||||
import { resolveMembers } from '~/util/members';
|
||||
|
||||
export function hasProperties(item: ApiItemContainerMixin) {
|
||||
return resolveMembers(item, memberPredicate).some(
|
||||
({ item: member }) => member.kind === ApiItemKind.Property || member.kind === ApiItemKind.PropertySignature,
|
||||
);
|
||||
}
|
||||
|
||||
export function hasMethods(item: ApiItemContainerMixin) {
|
||||
return resolveMembers(item, memberPredicate).some(
|
||||
({ item: member }) => member.kind === ApiItemKind.Method || member.kind === ApiItemKind.MethodSignature,
|
||||
);
|
||||
}
|
||||
|
||||
export function resolveItemURI(item: ApiItem): string {
|
||||
return `/${item.displayName}:${item.kind}`;
|
||||
}
|
||||
|
||||
function memberPredicate(item: ApiItem): item is ApiMethod | ApiMethodSignature | ApiProperty | ApiPropertySignature {
|
||||
return (
|
||||
item.kind === ApiItemKind.Property ||
|
||||
item.kind === ApiItemKind.PropertySignature ||
|
||||
item.kind === ApiItemKind.Method ||
|
||||
item.kind === ApiItemKind.MethodSignature
|
||||
);
|
||||
}
|
||||
|
||||
export function serializeMembers(clazz: ApiItemContainerMixin): TableOfContentsSerialized[] {
|
||||
return resolveMembers(clazz, memberPredicate).map(({ item: member }) => {
|
||||
if (member.kind === 'Method' || member.kind === 'MethodSignature') {
|
||||
return {
|
||||
kind: member.kind as 'Method' | 'MethodSignature',
|
||||
name: member.displayName,
|
||||
};
|
||||
} else {
|
||||
return {
|
||||
kind: member.kind as 'Property' | 'PropertySignature',
|
||||
name: member.displayName,
|
||||
overloadIndex: (member as ApiMethod | ApiMethodSignature).overloadIndex,
|
||||
};
|
||||
}
|
||||
});
|
||||
}
|
||||
@@ -1,25 +1,28 @@
|
||||
'use client';
|
||||
import type { ApiClass, ApiConstructor } from '@microsoft/api-extractor-model';
|
||||
import { ApiItemKind } from '@microsoft/api-extractor-model';
|
||||
import { Outline } from '../Outline';
|
||||
import { Documentation } from '../documentation/Documentation';
|
||||
import { HierarchyText } from '../documentation/HierarchyText';
|
||||
import { Members } from '../documentation/Members';
|
||||
import { ObjectHeader } from '../documentation/ObjectHeader';
|
||||
import { ConstructorSection } from '../documentation/section/ConstructorSection';
|
||||
import { TypeParameterSection } from '../documentation/section/TypeParametersSection';
|
||||
import { serializeMembers } from '../documentation/util';
|
||||
|
||||
import type { ApiClassJSON } from '@discordjs/api-extractor-utils';
|
||||
import { DocContainer } from '../DocContainer';
|
||||
import { ConstructorSection, MethodsSection, PropertiesSection } from '../Sections';
|
||||
export function Class({ clazz }: { clazz: ApiClass }) {
|
||||
const constructor = clazz.members.find((member) => member.kind === ApiItemKind.Constructor) as
|
||||
| ApiConstructor
|
||||
| undefined;
|
||||
|
||||
export function Class({ data }: { data: ApiClassJSON }) {
|
||||
return (
|
||||
<DocContainer
|
||||
excerpt={data.excerpt}
|
||||
extendsTokens={data.extendsTokens}
|
||||
implementsTokens={data.implementsTokens}
|
||||
kind={data.kind}
|
||||
methods={data.methods}
|
||||
name={data.name}
|
||||
properties={data.properties}
|
||||
summary={data.summary}
|
||||
typeParams={data.typeParameters}
|
||||
>
|
||||
{data.constructor ? <ConstructorSection data={data.constructor} /> : null}
|
||||
<PropertiesSection data={data.properties} />
|
||||
<MethodsSection data={data.methods} />
|
||||
</DocContainer>
|
||||
<Documentation>
|
||||
<ObjectHeader item={clazz} />
|
||||
<HierarchyText item={clazz} type="Extends" />
|
||||
<HierarchyText item={clazz} type="Implements" />
|
||||
{clazz.typeParameters.length ? <TypeParameterSection item={clazz} /> : null}
|
||||
{constructor ? <ConstructorSection item={constructor} /> : null}
|
||||
<Members item={clazz} />
|
||||
<Outline members={serializeMembers(clazz)} />
|
||||
</Documentation>
|
||||
);
|
||||
}
|
||||
|
||||
@@ -1,33 +0,0 @@
|
||||
'use client';
|
||||
|
||||
import type { ApiEnumJSON } from '@discordjs/api-extractor-utils';
|
||||
import { Section } from '@discordjs/ui';
|
||||
import { VscSymbolEnumMember } from '@react-icons/all-files/vsc/VscSymbolEnumMember';
|
||||
import { Fragment } from 'react';
|
||||
import { useMedia } from 'react-use';
|
||||
import { CodeListing, CodeListingSeparatorType } from '../CodeListing';
|
||||
import { DocContainer } from '../DocContainer';
|
||||
|
||||
export function Enum({ data }: { data: ApiEnumJSON }) {
|
||||
const matches = useMedia('(max-width: 768px)', true);
|
||||
|
||||
return (
|
||||
<DocContainer excerpt={data.excerpt} kind={data.kind} name={data.name} summary={data.summary}>
|
||||
<Section dense={matches} icon={<VscSymbolEnumMember size={20} />} padded title="Members">
|
||||
<div className="flex flex-col gap-4">
|
||||
{data.members.map((member) => (
|
||||
<Fragment key={member.name}>
|
||||
<CodeListing
|
||||
name={member.name}
|
||||
separator={CodeListingSeparatorType.Value}
|
||||
summary={member.summary}
|
||||
typeTokens={member.initializerTokens}
|
||||
/>
|
||||
<div className="border-light-900 dark:border-dark-100 -mx-8 border-t-2" />
|
||||
</Fragment>
|
||||
))}
|
||||
</div>
|
||||
</Section>
|
||||
</DocContainer>
|
||||
);
|
||||
}
|
||||
@@ -1,65 +0,0 @@
|
||||
'use client';
|
||||
|
||||
import type { ApiFunctionJSON } from '@discordjs/api-extractor-utils';
|
||||
import { VscChevronDown } from '@react-icons/all-files/vsc/VscChevronDown';
|
||||
import { VscVersions } from '@react-icons/all-files/vsc/VscVersions';
|
||||
import { Menu, MenuButton, MenuItem, useMenuState } from 'ariakit/menu';
|
||||
import { useState } from 'react';
|
||||
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
|
||||
excerpt={overloadedData.excerpt}
|
||||
kind={overloadedData.kind}
|
||||
name={`${overloadedData.name}${
|
||||
overloadedData.overloadIndex && overloadedData.overloadIndex > 1 ? ` (${overloadedData.overloadIndex})` : ''
|
||||
}`}
|
||||
subHeading={
|
||||
data.mergedSiblings.length > 1 ? (
|
||||
<div className="flex flex-row place-items-center gap-2">
|
||||
<MenuButton
|
||||
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 focus:ring-width-2 focus:ring-blurple rounded p-3 outline-0 focus:ring"
|
||||
state={menu}
|
||||
>
|
||||
<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
|
||||
className="dark:bg-dark-600 border-light-800 dark:border-dark-100 focus:ring-width-2 focus:ring-blurple z-20 flex flex-col rounded border bg-white p-1 outline-0 focus:ring"
|
||||
state={menu}
|
||||
>
|
||||
{data.mergedSiblings.map((_, idx) => (
|
||||
<MenuItem
|
||||
className="hover:bg-light-700 active:bg-light-800 dark:bg-dark-600 dark:hover:bg-dark-500 dark:active:bg-dark-400 focus:ring-width-2 focus:ring-blurple my-0.5 cursor-pointer rounded bg-white p-3 text-sm outline-0 focus:ring"
|
||||
key={idx}
|
||||
onClick={() => setOverloadIndex(idx + 1)}
|
||||
>
|
||||
{`Overload ${idx + 1}`}
|
||||
</MenuItem>
|
||||
))}
|
||||
</Menu>
|
||||
</div>
|
||||
) : null
|
||||
}
|
||||
summary={overloadedData.summary}
|
||||
typeParams={overloadedData.typeParameters}
|
||||
>
|
||||
<ParametersSection data={overloadedData.parameters} />
|
||||
</DocContainer>
|
||||
);
|
||||
}
|
||||
@@ -1,22 +1,20 @@
|
||||
'use client';
|
||||
import type { ApiInterface } from '@microsoft/api-extractor-model';
|
||||
import { Outline } from '../Outline';
|
||||
import { Documentation } from '../documentation/Documentation';
|
||||
import { HierarchyText } from '../documentation/HierarchyText';
|
||||
import { Members } from '../documentation/Members';
|
||||
import { ObjectHeader } from '../documentation/ObjectHeader';
|
||||
import { TypeParameterSection } from '../documentation/section/TypeParametersSection';
|
||||
import { serializeMembers } from '../documentation/util';
|
||||
|
||||
import type { ApiInterfaceJSON } from '@discordjs/api-extractor-utils';
|
||||
import { DocContainer } from '../DocContainer';
|
||||
import { MethodsSection, PropertiesSection } from '../Sections';
|
||||
|
||||
export function Interface({ data }: { data: ApiInterfaceJSON }) {
|
||||
export function Interface({ item }: { item: ApiInterface }) {
|
||||
return (
|
||||
<DocContainer
|
||||
excerpt={data.excerpt}
|
||||
kind={data.kind}
|
||||
methods={data.methods}
|
||||
name={data.name}
|
||||
properties={data.properties}
|
||||
summary={data.summary}
|
||||
typeParams={data.typeParameters}
|
||||
>
|
||||
<PropertiesSection data={data.properties} />
|
||||
<MethodsSection data={data.methods} />
|
||||
</DocContainer>
|
||||
<Documentation>
|
||||
<ObjectHeader item={item} />
|
||||
<HierarchyText item={item} type="Extends" />
|
||||
{item.typeParameters.length ? <TypeParameterSection item={item} /> : null}
|
||||
<Members item={item} />
|
||||
<Outline members={serializeMembers(item)} />
|
||||
</Documentation>
|
||||
);
|
||||
}
|
||||
|
||||
@@ -1,16 +1,13 @@
|
||||
'use client';
|
||||
import type { ApiTypeAlias } from '@microsoft/api-extractor-model';
|
||||
import { SyntaxHighlighter } from '../SyntaxHighlighter';
|
||||
import { Documentation } from '../documentation/Documentation';
|
||||
import { SummarySection } from '../documentation/section/SummarySection';
|
||||
|
||||
import type { ApiTypeAliasJSON } from '@discordjs/api-extractor-utils';
|
||||
import { DocContainer } from '../DocContainer';
|
||||
|
||||
export function TypeAlias({ data }: { data: ApiTypeAliasJSON }) {
|
||||
export function TypeAlias({ item }: { item: ApiTypeAlias }) {
|
||||
return (
|
||||
<DocContainer
|
||||
excerpt={data.excerpt}
|
||||
kind={data.kind}
|
||||
name={data.name}
|
||||
summary={data.summary}
|
||||
typeParams={data.typeParameters}
|
||||
/>
|
||||
<Documentation item={item}>
|
||||
<SyntaxHighlighter code={item.excerpt.text} />
|
||||
<SummarySection item={item} />
|
||||
</Documentation>
|
||||
);
|
||||
}
|
||||
|
||||
@@ -1,8 +1,13 @@
|
||||
'use client';
|
||||
import type { ApiVariable } from '@microsoft/api-extractor-model';
|
||||
import { SyntaxHighlighter } from '../SyntaxHighlighter';
|
||||
import { Documentation } from '../documentation/Documentation';
|
||||
import { SummarySection } from '../documentation/section/SummarySection';
|
||||
|
||||
import type { ApiVariableJSON } from '@discordjs/api-extractor-utils';
|
||||
import { DocContainer } from '../DocContainer';
|
||||
|
||||
export function Variable({ data }: { data: ApiVariableJSON }) {
|
||||
return <DocContainer excerpt={data.excerpt} kind={data.kind} name={data.name} summary={data.summary} />;
|
||||
export function Variable({ item }: { item: ApiVariable }) {
|
||||
return (
|
||||
<Documentation item={item}>
|
||||
<SyntaxHighlighter code={item.excerpt.text} />
|
||||
<SummarySection item={item} />
|
||||
</Documentation>
|
||||
);
|
||||
}
|
||||
|
||||
26
apps/website/src/components/model/enum/Enum.tsx
Normal file
26
apps/website/src/components/model/enum/Enum.tsx
Normal file
@@ -0,0 +1,26 @@
|
||||
import type { ApiEnum } from '@microsoft/api-extractor-model';
|
||||
import { VscSymbolEnum } from '@react-icons/all-files/vsc/VscSymbolEnum';
|
||||
import { Documentation } from '../../documentation/Documentation';
|
||||
import { EnumMember } from './EnumMember';
|
||||
import { Panel } from '~/components/Panel';
|
||||
import { SyntaxHighlighter } from '~/components/SyntaxHighlighter';
|
||||
import { ResponsiveSection } from '~/components/documentation/section/ResponsiveSection';
|
||||
import { SummarySection } from '~/components/documentation/section/SummarySection';
|
||||
|
||||
export function Enum({ item }: { item: ApiEnum }) {
|
||||
return (
|
||||
<Documentation item={item}>
|
||||
<SyntaxHighlighter code={item.excerpt.text} />
|
||||
<SummarySection item={item} />
|
||||
<ResponsiveSection icon={<VscSymbolEnum size={20} />} padded title="Members">
|
||||
<div className="flex flex-col gap-4">
|
||||
{item.members.map((member) => (
|
||||
<Panel key={member.containerKey}>
|
||||
<EnumMember member={member} />
|
||||
</Panel>
|
||||
))}
|
||||
</div>
|
||||
</ResponsiveSection>
|
||||
</Documentation>
|
||||
);
|
||||
}
|
||||
20
apps/website/src/components/model/enum/EnumMember.tsx
Normal file
20
apps/website/src/components/model/enum/EnumMember.tsx
Normal file
@@ -0,0 +1,20 @@
|
||||
import type { ApiEnumMember } from '@microsoft/api-extractor-model';
|
||||
import { Anchor } from '~/components/Anchor';
|
||||
import { NameText } from '~/components/NameText';
|
||||
import { SignatureText } from '~/components/SignatureText';
|
||||
import { TSDoc } from '~/components/documentation/tsdoc/TSDoc';
|
||||
|
||||
export function EnumMember({ member }: { member: ApiEnumMember }) {
|
||||
return (
|
||||
<div className="flex flex-col">
|
||||
<div className="md:-ml-8.5 flex flex-col gap-2 md:flex-row md:place-items-center">
|
||||
<Anchor href={`#${member.displayName}`} />
|
||||
<NameText name={member.name} />
|
||||
{member.initializerExcerpt ? (
|
||||
<SignatureText excerpt={member.initializerExcerpt} model={member.getAssociatedModel()!} />
|
||||
) : null}
|
||||
</div>
|
||||
{member.tsdocComment ? <TSDoc item={member} tsdoc={member.tsdocComment.summarySection} /> : null}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
28
apps/website/src/components/model/function/Function.tsx
Normal file
28
apps/website/src/components/model/function/Function.tsx
Normal file
@@ -0,0 +1,28 @@
|
||||
import type { ApiFunction } from '@microsoft/api-extractor-model';
|
||||
import { OverloadSwitcher } from '../../OverloadSwitcher';
|
||||
import { FunctionBody } from './FunctionBody';
|
||||
import { Header } from '~/components/documentation/Header';
|
||||
|
||||
export function Function({ item }: { item: ApiFunction }) {
|
||||
const header = <Header kind={item.kind} name={item.name} />;
|
||||
|
||||
if (item.getMergedSiblings().length > 1) {
|
||||
const overloads = item
|
||||
.getMergedSiblings()
|
||||
.map((sibling, idx) => <FunctionBody item={sibling as ApiFunction} key={idx} />);
|
||||
|
||||
return (
|
||||
<div>
|
||||
{header}
|
||||
<OverloadSwitcher overloads={overloads} />
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
return (
|
||||
<div>
|
||||
<Header kind={item.kind} name={item.name} />
|
||||
<FunctionBody item={item} />
|
||||
</div>
|
||||
);
|
||||
}
|
||||
23
apps/website/src/components/model/function/FunctionBody.tsx
Normal file
23
apps/website/src/components/model/function/FunctionBody.tsx
Normal file
@@ -0,0 +1,23 @@
|
||||
import type { ApiFunction } from '@microsoft/api-extractor-model';
|
||||
import { SyntaxHighlighter } from '~/components/SyntaxHighlighter';
|
||||
import { Documentation } from '~/components/documentation/Documentation';
|
||||
import { Header } from '~/components/documentation/Header';
|
||||
import { ParameterSection } from '~/components/documentation/section/ParametersSection';
|
||||
import { SummarySection } from '~/components/documentation/section/SummarySection';
|
||||
import { TypeParameterSection } from '~/components/documentation/section/TypeParametersSection';
|
||||
|
||||
export interface FunctionBodyProps {
|
||||
mergedSiblingCount: number;
|
||||
overloadDocumentation: React.ReactNode[];
|
||||
}
|
||||
|
||||
export function FunctionBody({ item }: { item: ApiFunction }) {
|
||||
return (
|
||||
<Documentation item={item} showHeader={false}>
|
||||
<SyntaxHighlighter code={item.excerpt.text} />
|
||||
<SummarySection item={item} />
|
||||
{item.typeParameters.length ? <TypeParameterSection item={item} /> : null}
|
||||
<ParameterSection item={item} />
|
||||
</Documentation>
|
||||
);
|
||||
}
|
||||
39
apps/website/src/components/model/method/Method.tsx
Normal file
39
apps/website/src/components/model/method/Method.tsx
Normal file
@@ -0,0 +1,39 @@
|
||||
import type {
|
||||
ApiDeclaredItem,
|
||||
ApiItemContainerMixin,
|
||||
ApiMethod,
|
||||
ApiMethodSignature,
|
||||
} from '@microsoft/api-extractor-model';
|
||||
import { OverloadSwitcher } from '../../OverloadSwitcher';
|
||||
import { MethodDocumentation } from './MethodDocumentation';
|
||||
import { MethodHeader } from './MethodHeader';
|
||||
|
||||
export function Method({
|
||||
method,
|
||||
inheritedFrom,
|
||||
}: {
|
||||
inheritedFrom?: (ApiDeclaredItem & ApiItemContainerMixin) | undefined;
|
||||
method: ApiMethod | ApiMethodSignature;
|
||||
}) {
|
||||
if (method.getMergedSiblings().length > 1) {
|
||||
// We have overloads, use the overload switcher, but render
|
||||
// each overload node on the server.
|
||||
const overloads = method
|
||||
.getMergedSiblings()
|
||||
.map((sibling, idx) => <MethodDocumentation key={idx} method={sibling as ApiMethod | ApiMethodSignature} />);
|
||||
|
||||
return (
|
||||
<OverloadSwitcher overloads={overloads}>
|
||||
<MethodHeader method={method} />
|
||||
</OverloadSwitcher>
|
||||
);
|
||||
}
|
||||
|
||||
// We have just a single method, render it on the server.
|
||||
return (
|
||||
<>
|
||||
<MethodHeader method={method} />
|
||||
<MethodDocumentation inheritedFrom={inheritedFrom} method={method} />
|
||||
</>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,32 @@
|
||||
import type {
|
||||
ApiDeclaredItem,
|
||||
ApiItemContainerMixin,
|
||||
ApiMethod,
|
||||
ApiMethodSignature,
|
||||
} from '@microsoft/api-extractor-model';
|
||||
import type { DocSection } from '@microsoft/tsdoc';
|
||||
import { InheritanceText } from '~/components/InheritanceText';
|
||||
import { ParameterTable } from '~/components/ParameterTable';
|
||||
import { TSDoc } from '~/components/documentation/tsdoc/TSDoc';
|
||||
|
||||
export interface MethodDocumentationProps {
|
||||
fallbackSummary?: DocSection;
|
||||
inheritedFrom?: (ApiDeclaredItem & ApiItemContainerMixin) | undefined;
|
||||
method: ApiMethod | ApiMethodSignature;
|
||||
}
|
||||
|
||||
export function MethodDocumentation({ method, fallbackSummary, inheritedFrom }: MethodDocumentationProps) {
|
||||
const parent = method.parent as ApiDeclaredItem;
|
||||
|
||||
if (!(method.tsdocComment?.summarySection || method.parameters.length > 0)) {
|
||||
return null;
|
||||
}
|
||||
|
||||
return (
|
||||
<div className="mb-4 flex flex-col gap-4">
|
||||
{method.tsdocComment ? <TSDoc item={method} tsdoc={method.tsdocComment} /> : null}
|
||||
{method.parameters.length ? <ParameterTable item={method} /> : null}
|
||||
{inheritedFrom && parent ? <InheritanceText parent={inheritedFrom} /> : null}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
62
apps/website/src/components/model/method/MethodHeader.tsx
Normal file
62
apps/website/src/components/model/method/MethodHeader.tsx
Normal file
@@ -0,0 +1,62 @@
|
||||
import type { ApiMethod, ApiMethodSignature } from '@microsoft/api-extractor-model';
|
||||
import { ApiItemKind } from '@microsoft/api-extractor-model';
|
||||
import { useCallback, useMemo } from 'react';
|
||||
import { Anchor } from '~/components/Anchor';
|
||||
import { ExcerptText } from '~/components/ExcerptText';
|
||||
|
||||
export function MethodHeader({ method }: { method: ApiMethod | ApiMethodSignature }) {
|
||||
const isDeprecated = Boolean(method.tsdocComment?.deprecatedBlock);
|
||||
|
||||
const key = useMemo(
|
||||
() => `${method.displayName}${method.overloadIndex && method.overloadIndex > 1 ? `:${method.overloadIndex}` : ''}`,
|
||||
[method.displayName, method.overloadIndex],
|
||||
);
|
||||
|
||||
const getShorthandName = useCallback(
|
||||
(method: ApiMethod | ApiMethodSignature) =>
|
||||
`${method.name}${method.isOptional ? '?' : ''}(${method.parameters.reduce((prev, cur, index) => {
|
||||
if (index === 0) {
|
||||
return `${prev}${cur.isOptional ? `${cur.name}?` : cur.name}`;
|
||||
}
|
||||
|
||||
return `${prev}, ${cur.isOptional ? `${cur.name}?` : cur.name}`;
|
||||
}, '')})`,
|
||||
[],
|
||||
);
|
||||
|
||||
return (
|
||||
<div className="flex flex-col">
|
||||
<div className="flex flex-col gap-2 md:-ml-9 md:flex-row md:place-items-center">
|
||||
<Anchor href={`#${key}`} />
|
||||
{isDeprecated ||
|
||||
(method.kind === ApiItemKind.Method && (method as ApiMethod).isProtected) ||
|
||||
(method.kind === ApiItemKind.Method && (method as ApiMethod).isStatic) ? (
|
||||
<div className="flex flex-row gap-1">
|
||||
{isDeprecated ? (
|
||||
<div className="flex h-5 flex-row place-content-center place-items-center rounded-full bg-red-500 px-3 text-center text-xs font-semibold uppercase text-white">
|
||||
Deprecated
|
||||
</div>
|
||||
) : null}
|
||||
{method.kind === ApiItemKind.Method && (method as ApiMethod).isProtected ? (
|
||||
<div className="bg-blurple flex h-5 flex-row place-content-center place-items-center rounded-full px-3 text-center text-xs font-semibold uppercase text-white">
|
||||
Protected
|
||||
</div>
|
||||
) : null}
|
||||
{method.kind === ApiItemKind.Method && (method as ApiMethod).isStatic ? (
|
||||
<div className="bg-blurple flex h-5 flex-row place-content-center place-items-center rounded-full px-3 text-center text-xs font-semibold uppercase text-white">
|
||||
Static
|
||||
</div>
|
||||
) : null}
|
||||
</div>
|
||||
) : null}
|
||||
<div className="flex flex-row flex-wrap gap-1">
|
||||
<h4 className="break-all font-mono text-lg font-bold">{getShorthandName(method)}</h4>
|
||||
<h4 className="font-mono text-lg font-bold">:</h4>
|
||||
<h4 className="break-all font-mono text-lg font-bold">
|
||||
<ExcerptText excerpt={method.returnTypeExcerpt} model={method.getAssociatedModel()!} />
|
||||
</h4>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
@@ -1,58 +0,0 @@
|
||||
'use client';
|
||||
|
||||
import { Alert } from '@discordjs/ui';
|
||||
import { StandardTags } from '@microsoft/tsdoc';
|
||||
import type { PropsWithChildren } from 'react';
|
||||
|
||||
export function Block({ children, title }: PropsWithChildren<{ title: string }>) {
|
||||
return (
|
||||
<div className="flex flex-col gap-2">
|
||||
<h5 className="font-bold">{title}</h5>
|
||||
{children}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
|
||||
export function ExampleBlock({
|
||||
children,
|
||||
exampleIndex,
|
||||
}: PropsWithChildren<{ exampleIndex?: number | undefined }>): JSX.Element {
|
||||
return <Block title={`Example ${exampleIndex ? exampleIndex : ''}`}>{children}</Block>;
|
||||
}
|
||||
|
||||
export function DefaultValueBlock({ children }: PropsWithChildren): JSX.Element {
|
||||
return <Block title="Default value">{children}</Block>;
|
||||
}
|
||||
|
||||
export function RemarksBlock({ children }: PropsWithChildren): JSX.Element {
|
||||
return <Block title="Remarks">{children}</Block>;
|
||||
}
|
||||
|
||||
export function BlockComment({
|
||||
children,
|
||||
tagName,
|
||||
index,
|
||||
}: PropsWithChildren<{
|
||||
index?: number | undefined;
|
||||
tagName: string;
|
||||
}>): JSX.Element {
|
||||
switch (tagName.toUpperCase()) {
|
||||
case StandardTags.example.tagNameWithUpperCase:
|
||||
return <ExampleBlock exampleIndex={index}>{children}</ExampleBlock>;
|
||||
case StandardTags.deprecated.tagNameWithUpperCase:
|
||||
return (
|
||||
<Alert title="Deprecated" type="danger">
|
||||
{children}
|
||||
</Alert>
|
||||
);
|
||||
case StandardTags.remarks.tagNameWithUpperCase:
|
||||
return <RemarksBlock>{children}</RemarksBlock>;
|
||||
case StandardTags.defaultValue.tagNameWithUpperCase:
|
||||
return <DefaultValueBlock>{children}</DefaultValueBlock>;
|
||||
case StandardTags.typeParam.tagNameWithUpperCase:
|
||||
case StandardTags.param.tagNameWithUpperCase:
|
||||
return <span>{children}</span>;
|
||||
default: // TODO: Support more blocks in the future.
|
||||
return <>{children}</>;
|
||||
}
|
||||
}
|
||||
@@ -1,129 +0,0 @@
|
||||
'use client';
|
||||
|
||||
import type {
|
||||
AnyDocNodeJSON,
|
||||
DocPlainTextJSON,
|
||||
DocNodeContainerJSON,
|
||||
DocLinkTagJSON,
|
||||
DocFencedCodeJSON,
|
||||
DocBlockJSON,
|
||||
DocCommentJSON,
|
||||
} from '@discordjs/api-extractor-utils';
|
||||
import { DocNodeKind, StandardTags } from '@microsoft/tsdoc';
|
||||
import Link from 'next/link';
|
||||
import { Fragment, useCallback, type ReactNode } from 'react';
|
||||
import { SyntaxHighlighter } from '../SyntaxHighlighter';
|
||||
import { BlockComment } from './BlockComment';
|
||||
|
||||
export function TSDoc({ node }: { node: AnyDocNodeJSON }): JSX.Element {
|
||||
const createNode = useCallback((node: AnyDocNodeJSON, idx?: number): ReactNode => {
|
||||
let numberOfExamples = 0;
|
||||
let exampleIndex = 0;
|
||||
|
||||
switch (node.kind) {
|
||||
case DocNodeKind.PlainText:
|
||||
return (
|
||||
<span className="break-words" key={idx}>
|
||||
{(node as DocPlainTextJSON).text}
|
||||
</span>
|
||||
);
|
||||
case DocNodeKind.Paragraph:
|
||||
return (
|
||||
<span className="break-words leading-relaxed" key={idx}>
|
||||
{(node as DocNodeContainerJSON).nodes.map((node, idx) => createNode(node, idx))}
|
||||
</span>
|
||||
);
|
||||
case DocNodeKind.SoftBreak:
|
||||
return <Fragment key={idx} />;
|
||||
case DocNodeKind.LinkTag: {
|
||||
const { codeDestination, urlDestination, text } = node as DocLinkTagJSON;
|
||||
|
||||
if (codeDestination) {
|
||||
return (
|
||||
<Link
|
||||
className="text-blurple focus:ring-width-2 focus:ring-blurple rounded font-mono outline-0 focus:ring"
|
||||
href={codeDestination.path}
|
||||
key={idx}
|
||||
>
|
||||
{text ?? codeDestination.name}
|
||||
</Link>
|
||||
);
|
||||
}
|
||||
|
||||
if (urlDestination) {
|
||||
return (
|
||||
<Link
|
||||
className="text-blurple focus:ring-width-2 focus:ring-blurple rounded font-mono outline-0 focus:ring"
|
||||
href={urlDestination}
|
||||
key={idx}
|
||||
>
|
||||
{text ?? urlDestination}
|
||||
</Link>
|
||||
);
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
case DocNodeKind.CodeSpan: {
|
||||
const { code } = node as DocFencedCodeJSON;
|
||||
return (
|
||||
<code className="font-mono text-sm" key={idx}>
|
||||
{code}
|
||||
</code>
|
||||
);
|
||||
}
|
||||
|
||||
case DocNodeKind.FencedCode: {
|
||||
const { language, code } = node as DocFencedCodeJSON;
|
||||
return <SyntaxHighlighter code={code} key={idx} language={language} />;
|
||||
}
|
||||
|
||||
case DocNodeKind.ParamBlock:
|
||||
case DocNodeKind.Block: {
|
||||
const { tag } = node as DocBlockJSON;
|
||||
|
||||
if (tag.tagName.toUpperCase() === StandardTags.example.tagNameWithUpperCase) {
|
||||
exampleIndex++;
|
||||
}
|
||||
|
||||
const index = numberOfExamples > 1 ? exampleIndex : undefined;
|
||||
|
||||
return (
|
||||
<BlockComment index={index} key={idx} tagName={tag.tagName}>
|
||||
{(node as DocBlockJSON).content.map((node, idx) => createNode(node, idx))}
|
||||
</BlockComment>
|
||||
);
|
||||
}
|
||||
|
||||
case DocNodeKind.Comment: {
|
||||
const comment = node as DocCommentJSON;
|
||||
|
||||
if (!comment.customBlocks.length) {
|
||||
return null;
|
||||
}
|
||||
|
||||
// Cheat a bit by finding out how many comments we have beforehand...
|
||||
numberOfExamples = comment.customBlocks.filter(
|
||||
(block) => block.tag.tagName.toUpperCase() === StandardTags.example.tagNameWithUpperCase,
|
||||
).length;
|
||||
|
||||
return <div key={idx}>{comment.customBlocks.map((node, idx) => createNode(node, idx))}</div>;
|
||||
}
|
||||
|
||||
default:
|
||||
// console.log(`Captured unknown node kind: ${node.kind}`);
|
||||
return null;
|
||||
}
|
||||
}, []);
|
||||
|
||||
return (
|
||||
<>
|
||||
{node.kind === 'Paragraph' || node.kind === 'Section' ? (
|
||||
<>{(node as DocNodeContainerJSON).nodes.map((node, idx) => createNode(node, idx))}</>
|
||||
) : (
|
||||
createNode(node)
|
||||
)}
|
||||
</>
|
||||
);
|
||||
}
|
||||
Reference in New Issue
Block a user