From c62c0deb5a30405cdf792ec9071fd0e57962abdb Mon Sep 17 00:00:00 2001 From: TheoryOfNekomata Date: Sun, 27 Dec 2020 19:33:30 +0800 Subject: [PATCH] Improve documentation Parse descriptions as Markdown. Also improve loading of current theme. --- packages/react-common-docs/package.json | 4 +++- .../src/components/Header/Header.tsx | 22 +++++++++++-------- .../src/components/Props/Props.tsx | 19 +++++++++++++++- .../components/ThemeToggle/ThemeToggle.tsx | 4 +++- packages/react-common-docs/src/docgen.json | 12 +++++----- packages/react-common-docs/yarn.lock | 6 ++--- .../src/components/Button/Button.tsx | 10 +++++---- .../src/components/TextInput/TextInput.tsx | 2 ++ 8 files changed, 53 insertions(+), 26 deletions(-) diff --git a/packages/react-common-docs/package.json b/packages/react-common-docs/package.json index dda5c36..895c34c 100644 --- a/packages/react-common-docs/package.json +++ b/packages/react-common-docs/package.json @@ -11,6 +11,9 @@ "start": "next start", "docgen": "./scripts/docgen" }, + "resolutions": { + "styled-components": "file:./../../node_modules/styled-components" + }, "dependencies": { "@mdx-js/loader": "^1.6.19", "next": "10.0.1", @@ -22,7 +25,6 @@ "react-live": "^2.2.3", "remark-parse": "^9.0.0", "remark-react": "^8.0.0", - "styled-components": "^5.2.1", "unified": "^9.2.0" } } diff --git a/packages/react-common-docs/src/components/Header/Header.tsx b/packages/react-common-docs/src/components/Header/Header.tsx index 674c32b..db6db96 100644 --- a/packages/react-common-docs/src/components/Header/Header.tsx +++ b/packages/react-common-docs/src/components/Header/Header.tsx @@ -20,23 +20,27 @@ const Header: React.FC = ({ of: ofAttr }) => { return null } + const description = unified() + .use(parse) + .use(remark2react) + .processSync(docs.description).result as any + + const [firstDescriptionChild] = description.props.children + + const summary = typeof firstDescriptionChild as unknown === 'string' + ? firstDescriptionChild + : firstDescriptionChild.props.children[0] + return ( {docs.displayName} | {pkg['title'] || pkg.name} - +

{docs.displayName}

-

- { - unified() - .use(parse) - .use(remark2react) - .processSync(docs.description).result as any - } -

+ {description} ) } diff --git a/packages/react-common-docs/src/components/Props/Props.tsx b/packages/react-common-docs/src/components/Props/Props.tsx index 8b49672..a3a5781 100644 --- a/packages/react-common-docs/src/components/Props/Props.tsx +++ b/packages/react-common-docs/src/components/Props/Props.tsx @@ -3,6 +3,9 @@ import * as PropTypes from 'prop-types' import styled from 'styled-components' import PrismTheme from '../../utilities/prism-themes/dark' import docgen from '../../docgen.json' +import unified from 'unified' +import parse from 'remark-parse' +import remark2react from 'remark-react' const Base = styled('table')({ borderCollapse: 'collapse', @@ -86,6 +89,12 @@ const BodyCell = styled('td')({ display: 'none', }, }, + '& :first-child': { + marginTop: 0, + }, + '& :last-child': { + marginBottom: 0, + } }) const Code = styled('code')({ @@ -296,6 +305,14 @@ const Props: React.FC = ({ of: ofAttr }) => { const propName = getPropName(name, prop) const propDefaultValue = getPropDefaultValue(prop) const propType = getPropType(prop) + const propDescription = prop.description + ? ( + (unified() + .use(parse) + .use(remark2react) + .processSync(prop.description).result as any) + ) + : undefined return ( @@ -323,7 +340,7 @@ const Props: React.FC = ({ of: ofAttr }) => { } - {prop.description} + {propDescription} ) diff --git a/packages/react-common-docs/src/components/ThemeToggle/ThemeToggle.tsx b/packages/react-common-docs/src/components/ThemeToggle/ThemeToggle.tsx index 237917a..6a94e1c 100644 --- a/packages/react-common-docs/src/components/ThemeToggle/ThemeToggle.tsx +++ b/packages/react-common-docs/src/components/ThemeToggle/ThemeToggle.tsx @@ -49,7 +49,9 @@ const ThemeToggle = ({ window.localStorage.setItem('tesseract-theme', theme) return } - setTheme(getTheme()) + window.setTimeout(() => { + setTheme(getTheme()) + }) }, [theme]) React.useEffect(() => { diff --git a/packages/react-common-docs/src/docgen.json b/packages/react-common-docs/src/docgen.json index 842e6b2..55fd5e6 100644 --- a/packages/react-common-docs/src/docgen.json +++ b/packages/react-common-docs/src/docgen.json @@ -1,6 +1,6 @@ [ { - "description": "Component for performing an action upon activation (e.g. when clicked).", + "description": "Component for performing an action upon activation (e.g. when clicked).\n\nDepending on the declared props, this component can function as a hyperlink or as a button.", "displayName": "Button", "methods": [], "props": { @@ -89,7 +89,7 @@ }, "href": { "defaultValue": null, - "description": "The URL of the page to navigate to, if element is set to \"a\".", + "description": "The URL of the page to navigate to, if `element` is set to `\"a\"`.", "name": "href", "required": false, "type": { @@ -98,7 +98,7 @@ }, "target": { "defaultValue": null, - "description": "The target on where to display the page navigated to, if element is set to \"a\".", + "description": "The target on where to display the page navigated to, if `element` is set to `\"a\"`.", "name": "target", "required": false, "type": { @@ -107,7 +107,7 @@ }, "rel": { "defaultValue": null, - "description": "The relationship of the current page to the referred page in \"href\", if element is set to \"a\".", + "description": "The relationship of the current page to the referred page in `href`, if `element` is set to `\"a\"`.", "name": "rel", "required": false, "type": { @@ -118,7 +118,7 @@ "defaultValue": { "value": "button" }, - "description": "The type of the button, if element is set to \"button\".", + "description": "The type of the button, if `element` is set to `\"button\"`.", "name": "type", "required": false, "type": { @@ -525,7 +525,7 @@ } }, { - "description": "Component for inputting textual values.", + "description": "Component for inputting textual values.\n\nThis component supports multiline input and adjusts its layout accordingly.", "displayName": "TextInput", "methods": [], "props": { diff --git a/packages/react-common-docs/yarn.lock b/packages/react-common-docs/yarn.lock index ff1733e..84fdc8c 100644 --- a/packages/react-common-docs/yarn.lock +++ b/packages/react-common-docs/yarn.lock @@ -5830,10 +5830,8 @@ style-to-object@0.3.0, style-to-object@^0.3.0: dependencies: inline-style-parser "0.1.1" -styled-components@^5.2.1: - version "5.2.1" - resolved "https://registry.yarnpkg.com/styled-components/-/styled-components-5.2.1.tgz#6ed7fad2dc233825f64c719ffbdedd84ad79101a" - integrity sha512-sBdgLWrCFTKtmZm/9x7jkIabjFNVzCUeKfoQsM6R3saImkUnjx0QYdLwJHBjY9ifEcmjDamJDVfknWm1yxZPxQ== +"styled-components@file:./../../node_modules/styled-components": + version "5.1.0" dependencies: "@babel/helper-module-imports" "^7.0.0" "@babel/traverse" "^7.4.5" diff --git a/packages/react-common/src/components/Button/Button.tsx b/packages/react-common/src/components/Button/Button.tsx index cfaa3b7..fabe63c 100644 --- a/packages/react-common/src/components/Button/Button.tsx +++ b/packages/react-common/src/components/Button/Button.tsx @@ -137,19 +137,19 @@ const propTypes = { */ element: PropTypes.oneOf(['a', 'button']), /** - * The URL of the page to navigate to, if element is set to "a". + * The URL of the page to navigate to, if `element` is set to `"a"`. */ href: PropTypes.string, /** - * The target on where to display the page navigated to, if element is set to "a". + * The target on where to display the page navigated to, if `element` is set to `"a"`. */ target: PropTypes.string, /** - * The relationship of the current page to the referred page in "href", if element is set to "a". + * The relationship of the current page to the referred page in `href`, if `element` is set to `"a"`. */ rel: PropTypes.string, /** - * The type of the button, if element is set to "button". + * The type of the button, if `element` is set to `"button"`. */ type: PropTypes.oneOf(['submit', 'reset', 'button']), /** @@ -174,6 +174,8 @@ type Props = PropTypes.InferProps /** * Component for performing an action upon activation (e.g. when clicked). + * + * Depending on the declared props, this component can function as a hyperlink or as a button. */ const Button = React.forwardRef( ( diff --git a/packages/react-common/src/components/TextInput/TextInput.tsx b/packages/react-common/src/components/TextInput/TextInput.tsx index 14bdb50..d50ef18 100644 --- a/packages/react-common/src/components/TextInput/TextInput.tsx +++ b/packages/react-common/src/components/TextInput/TextInput.tsx @@ -257,6 +257,8 @@ type Props = PropTypes.InferProps /** * Component for inputting textual values. + * + * This component supports multiline input and adjusts its layout accordingly. */ const TextInput = React.forwardRef( (