From 236c7921c2666e6877f97fee4135b9a1d614131e Mon Sep 17 00:00:00 2001 From: Sam Date: Sun, 23 Aug 2020 17:07:30 -0400 Subject: [PATCH] feat(v2): Provide docs plugin typing --- .../package.json | 1 + .../src/index.ts | 2 +- .../src/plugin-content-docs.d.ts | 101 ++++++++++++++++++ .../src/props.ts | 8 +- .../src/slug.ts | 2 +- .../src/types.ts | 26 ----- .../docusaurus-theme-classic/package.json | 1 + .../src/theme/DocItem/index.tsx | 3 +- .../src/theme/DocPage/index.tsx | 15 ++- .../docusaurus-theme-classic/src/types.d.ts | 1 + 10 files changed, 125 insertions(+), 35 deletions(-) create mode 100644 packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts diff --git a/packages/docusaurus-plugin-content-docs/package.json b/packages/docusaurus-plugin-content-docs/package.json index b24a95022e48..f5940d7d5d49 100644 --- a/packages/docusaurus-plugin-content-docs/package.json +++ b/packages/docusaurus-plugin-content-docs/package.json @@ -3,6 +3,7 @@ "version": "2.0.0-alpha.61", "description": "Docs content plugin for Docusaurus", "main": "lib/index.js", + "types": "src/plugin-content-docs.d.ts", "scripts": { "build": "tsc", "watch": "tsc --watch" diff --git a/packages/docusaurus-plugin-content-docs/src/index.ts b/packages/docusaurus-plugin-content-docs/src/index.ts index 6d451b2b0306..011091015c02 100644 --- a/packages/docusaurus-plugin-content-docs/src/index.ts +++ b/packages/docusaurus-plugin-content-docs/src/index.ts @@ -22,7 +22,6 @@ import { PluginOptions, LoadedContent, SourceToPermalink, - PermalinkToSidebar, DocMetadataBase, DocMetadata, GlobalPluginData, @@ -32,6 +31,7 @@ import { DocFile, DocsMarkdownOption, } from './types'; +import {PermalinkToSidebar} from '@docusaurus/plugin-content-docs-types'; import {RuleSetRule} from 'webpack'; import {cliDocsVersionCommand} from './cli'; import {VERSIONS_JSON_FILE} from './constants'; diff --git a/packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts b/packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts new file mode 100644 index 000000000000..90a801977a53 --- /dev/null +++ b/packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts @@ -0,0 +1,101 @@ +/** + * Copyright (c) Facebook, Inc. and its affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +/* eslint-disable camelcase */ + +declare module '@docusaurus/plugin-content-docs-types' { + export type VersionName = string; + + export type PermalinkToSidebar = { + [permalink: string]: string; + }; + + export type PropVersionMetadata = { + version: VersionName; + docsSidebars: PropSidebars; + permalinkToSidebar: PermalinkToSidebar; + }; + + export type PropSidebarItemLink = { + type: 'link'; + href: string; + label: string; + }; + + export type PropSidebarItemCategory = { + type: 'category'; + label: string; + items: PropSidebarItem[]; + collapsed?: boolean; + }; + + export type PropSidebarItem = PropSidebarItemLink | PropSidebarItemCategory; + + export type PropSidebars = { + [sidebarId: string]: PropSidebarItem[]; + }; +} + +declare module '@theme/DocItem' { + import type {MarkdownRightTableOfContents} from '@docusaurus/types'; + + export type DocumentRoute = { + readonly component: () => JSX.Element; + readonly exact: boolean; + readonly path: string; + }; + + export type FrontMatter = { + readonly id: string; + readonly title: string; + readonly image?: string; + readonly keywords?: readonly string[]; + readonly hide_title?: boolean; + readonly hide_table_of_contents?: boolean; + }; + + export type Metadata = { + readonly description?: string; + readonly title?: string; + readonly permalink?: string; + readonly editUrl?: string; + readonly lastUpdatedAt?: number; + readonly lastUpdatedBy?: string; + readonly version?: string; + }; + + export type Props = { + readonly route: DocumentRoute; + readonly content: { + readonly frontMatter: FrontMatter; + readonly metadata: Metadata; + readonly rightToc: MarkdownRightTableOfContents; + (): JSX.Element; + }; + }; + + const DocItem: (props: Props) => JSX.Element; + export default DocItem; +} + +declare module '@theme/DocPage' { + import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs-types'; + import type {DocumentRoute} from '@theme/DocItem'; + + export type Props = { + readonly location: {readonly pathname: string}; + readonly versionMetadata: PropVersionMetadata; + readonly route: { + readonly path: string; + readonly component: () => JSX.Element; + readonly routes: readonly DocumentRoute[]; + }; + }; + + const DocPage: (props: Props) => JSX.Element; + export default DocPage; +} diff --git a/packages/docusaurus-plugin-content-docs/src/props.ts b/packages/docusaurus-plugin-content-docs/src/props.ts index f194648db697..2715ba9a1bb6 100644 --- a/packages/docusaurus-plugin-content-docs/src/props.ts +++ b/packages/docusaurus-plugin-content-docs/src/props.ts @@ -7,13 +7,15 @@ import { LoadedVersion, - PropSidebars, SidebarItemDoc, SidebarItemLink, - PropVersionMetadata, SidebarItem, - PropSidebarItem, } from './types'; +import { + PropSidebars, + PropVersionMetadata, + PropSidebarItem, +} from '@docusaurus/plugin-content-docs-types'; import {keyBy, mapValues} from 'lodash'; export function toSidebarsProp(loadedVersion: LoadedVersion): PropSidebars { diff --git a/packages/docusaurus-plugin-content-docs/src/slug.ts b/packages/docusaurus-plugin-content-docs/src/slug.ts index 465d0d534398..4c25aae6358d 100644 --- a/packages/docusaurus-plugin-content-docs/src/slug.ts +++ b/packages/docusaurus-plugin-content-docs/src/slug.ts @@ -20,7 +20,7 @@ export default function getSlug({ baseID: string; frontmatterSlug?: string; dirName: string; -}) { +}): string { const baseSlug: string = frontmatterSlug || baseID; let slug: string; if (baseSlug.startsWith('/')) { diff --git a/packages/docusaurus-plugin-content-docs/src/types.ts b/packages/docusaurus-plugin-content-docs/src/types.ts index 9528f5758b51..a7c53edfad78 100644 --- a/packages/docusaurus-plugin-content-docs/src/types.ts +++ b/packages/docusaurus-plugin-content-docs/src/types.ts @@ -119,11 +119,6 @@ export type DocMetadata = DocMetadataBase & { export type SourceToPermalink = { [source: string]: string; }; - -export type PermalinkToSidebar = { - [permalink: string]: string; -}; - export type LoadedVersion = VersionMetadata & { versionPath: string; mainDocId: string; @@ -155,27 +150,6 @@ export type GlobalPluginData = { versions: GlobalVersion[]; }; -export type PropVersionMetadata = { - version: VersionName; - docsSidebars: PropSidebars; - permalinkToSidebar: PermalinkToSidebar; -}; - -export type PropSidebarItemLink = SidebarItemLink; // same - -export type PropSidebarItemCategory = { - type: 'category'; - label: string; - items: PropSidebarItem[]; - collapsed?: boolean; -}; - -export type PropSidebarItem = PropSidebarItemLink | PropSidebarItemCategory; - -export type PropSidebars = { - [sidebarId: string]: PropSidebarItem[]; -}; - export type BrokenMarkdownLink = { filePath: string; version: VersionMetadata; diff --git a/packages/docusaurus-theme-classic/package.json b/packages/docusaurus-theme-classic/package.json index e6fee495d9e7..4cf5ecd08d14 100644 --- a/packages/docusaurus-theme-classic/package.json +++ b/packages/docusaurus-theme-classic/package.json @@ -38,6 +38,7 @@ "peerDependencies": { "@docusaurus/core": "^2.0.0", "@docusaurus/plugin-content-blog": "^2.0.0-alpha.61", + "@docusaurus/plugin-content-docs": "^2.0.0-alpha.61", "react": "^16.8.4", "react-dom": "^16.8.4" }, diff --git a/packages/docusaurus-theme-classic/src/theme/DocItem/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocItem/index.tsx index c80df4067c0c..35c497d21b2c 100644 --- a/packages/docusaurus-theme-classic/src/theme/DocItem/index.tsx +++ b/packages/docusaurus-theme-classic/src/theme/DocItem/index.tsx @@ -12,12 +12,13 @@ import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; import useBaseUrl from '@docusaurus/useBaseUrl'; import DocPaginator from '@theme/DocPaginator'; import DocVersionSuggestions from '@theme/DocVersionSuggestions'; +import type {Props} from '@theme/DocItem'; import TOC from '@theme/TOC'; import clsx from 'clsx'; import styles from './styles.module.css'; -function DocItem(props): JSX.Element { +function DocItem(props: Props): JSX.Element { const {siteConfig = {}} = useDocusaurusContext(); const {url: siteUrl, title: siteTitle} = siteConfig; const {content: DocContent} = props; diff --git a/packages/docusaurus-theme-classic/src/theme/DocPage/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocPage/index.tsx index 64ac1a1d7350..5c5daabf5219 100644 --- a/packages/docusaurus-theme-classic/src/theme/DocPage/index.tsx +++ b/packages/docusaurus-theme-classic/src/theme/DocPage/index.tsx @@ -5,24 +5,33 @@ * LICENSE file in the root directory of this source tree. */ -import React from 'react'; +import React, {ReactNode} from 'react'; import {MDXProvider} from '@mdx-js/react'; import useDocusaurusContext from '@docusaurus/useDocusaurusContext'; import renderRoutes from '@docusaurus/renderRoutes'; +import type {PropVersionMetadata} from '@docusaurus/plugin-content-docs-types'; import Layout from '@theme/Layout'; import DocSidebar from '@theme/DocSidebar'; import MDXComponents from '@theme/MDXComponents'; import NotFound from '@theme/NotFound'; +import type {DocumentRoute} from '@theme/DocItem'; +import type {Props} from '@theme/DocPage'; import {matchPath} from '@docusaurus/router'; import styles from './styles.module.css'; +type DocPageContentProps = { + readonly currentDocRoute: DocumentRoute; + readonly versionMetadata: PropVersionMetadata; + readonly children: ReactNode; +}; + function DocPageContent({ currentDocRoute, versionMetadata, children, -}): JSX.Element { +}: DocPageContentProps): JSX.Element { const {siteConfig, isClient} = useDocusaurusContext(); const {permalinkToSidebar, docsSidebars, version} = versionMetadata; const sidebarName = permalinkToSidebar[currentDocRoute.path]; @@ -49,7 +58,7 @@ function DocPageContent({ ); } -function DocPage(props) { +function DocPage(props: Props): JSX.Element { const { route: {routes: docRoutes}, versionMetadata, diff --git a/packages/docusaurus-theme-classic/src/types.d.ts b/packages/docusaurus-theme-classic/src/types.d.ts index 7ef7ad3d2a30..b08a3df20ea9 100644 --- a/packages/docusaurus-theme-classic/src/types.d.ts +++ b/packages/docusaurus-theme-classic/src/types.d.ts @@ -8,3 +8,4 @@ /* eslint-disable spaced-comment */ /// /// +///