diff options
Diffstat (limited to 'packages/react-docs/src/components')
12 files changed, 97 insertions, 62 deletions
diff --git a/packages/react-docs/src/components/badge.tsx b/packages/react-docs/src/components/badge.tsx index b342f2dca..d34f8a0fc 100644 --- a/packages/react-docs/src/components/badge.tsx +++ b/packages/react-docs/src/components/badge.tsx @@ -1,5 +1,4 @@ import { Styles } from '@0xproject/react-shared'; -import * as _ from 'lodash'; import * as React from 'react'; const styles: Styles = { @@ -31,7 +30,7 @@ export class Badge extends React.Component<BadgeProps, BadgeState> { isHovering: false, }; } - public render() { + public render(): React.ReactNode { const badgeStyle = { ...styles.badge, backgroundColor: this.props.backgroundColor, @@ -48,7 +47,7 @@ export class Badge extends React.Component<BadgeProps, BadgeState> { </div> ); } - private _setHoverState(isHovering: boolean) { + private _setHoverState(isHovering: boolean): void { this.setState({ isHovering, }); diff --git a/packages/react-docs/src/components/comment.tsx b/packages/react-docs/src/components/comment.tsx index 0d63d4d31..c3687c510 100644 --- a/packages/react-docs/src/components/comment.tsx +++ b/packages/react-docs/src/components/comment.tsx @@ -1,5 +1,4 @@ import { MarkdownCodeBlock } from '@0xproject/react-shared'; -import * as _ from 'lodash'; import * as React from 'react'; import * as ReactMarkdown from 'react-markdown'; diff --git a/packages/react-docs/src/components/custom_enum.tsx b/packages/react-docs/src/components/custom_enum.tsx index 1fe55eedc..c4252d9e2 100644 --- a/packages/react-docs/src/components/custom_enum.tsx +++ b/packages/react-docs/src/components/custom_enum.tsx @@ -3,7 +3,6 @@ import * as _ from 'lodash'; import * as React from 'react'; import { CustomType } from '../types'; -import { utils } from '../utils/utils'; const STRING_ENUM_CODE_PREFIX = ' strEnum('; @@ -14,7 +13,7 @@ export interface CustomEnumProps { // This component renders custom string enums that was a work-around for versions of // TypeScript <2.4.0 that did not support them natively. We keep it around to support // older versions of 0x.js <0.9.0 -export function CustomEnum(props: CustomEnumProps) { +export const CustomEnum = (props: CustomEnumProps) => { const type = props.type; if (!_.startsWith(type.defaultValue, STRING_ENUM_CODE_PREFIX)) { logUtils.log('We do not yet support `Variable` types that are not strEnums'); @@ -31,4 +30,4 @@ export function CustomEnum(props: CustomEnumProps) { {`}`} </span> ); -} +}; diff --git a/packages/react-docs/src/components/documentation.tsx b/packages/react-docs/src/components/documentation.tsx index 14fe175cf..ff33220d2 100644 --- a/packages/react-docs/src/components/documentation.tsx +++ b/packages/react-docs/src/components/documentation.tsx @@ -3,7 +3,6 @@ import { constants as sharedConstants, EtherscanLinkSuffixes, MarkdownSection, - MenuSubsectionsBySection, NestedSidebarMenu, Networks, SectionHeader, @@ -13,13 +12,12 @@ import { import * as _ from 'lodash'; import CircularProgress from 'material-ui/CircularProgress'; import * as React from 'react'; -import { scroller } from 'react-scroll'; +import * as semver from 'semver'; import { DocsInfo } from '../docs_info'; import { AddressByContractName, DocAgnosticFormat, - DoxityDocObj, Event, Property, SolidityMethod, @@ -29,7 +27,6 @@ import { TypescriptMethod, } from '../types'; import { constants } from '../utils/constants'; -import { utils } from '../utils/utils'; import { Badge } from './badge'; import { Comment } from './comment'; @@ -71,19 +68,19 @@ export class Documentation extends React.Component<DocumentationProps, Documenta isHoveringSidebar: false, }; } - public componentDidMount() { + public componentDidMount(): void { window.addEventListener('hashchange', this._onHashChanged.bind(this), false); } - public componentWillUnmount() { + public componentWillUnmount(): void { window.removeEventListener('hashchange', this._onHashChanged.bind(this), false); } - public componentDidUpdate(prevProps: DocumentationProps, prevState: DocumentationState) { + public componentDidUpdate(prevProps: DocumentationProps, _prevState: DocumentationState): void { if (!_.isEqual(prevProps.docAgnosticFormat, this.props.docAgnosticFormat)) { const hash = window.location.hash.slice(1); sharedUtils.scrollToHash(hash, sharedConstants.SCROLL_CONTAINER_ID); } } - public render() { + public render(): React.ReactNode { const styles: Styles = { mainContainers: { position: 'absolute', @@ -91,7 +88,7 @@ export class Documentation extends React.Component<DocumentationProps, Documenta left: 0, bottom: 0, right: 0, - overflowZ: 'hidden', + overflowX: 'hidden', overflowY: 'scroll', minHeight: `calc(100vh - ${this.props.topBarHeight}px)`, WebkitOverflowScrolling: 'touch', @@ -157,7 +154,7 @@ export class Documentation extends React.Component<DocumentationProps, Documenta </div> ); } - private _renderLoading(mainContainersStyles: React.CSSProperties) { + private _renderLoading(mainContainersStyles: React.CSSProperties): React.ReactNode { return ( <div className="col col-12" style={mainContainersStyles}> <div @@ -184,7 +181,20 @@ export class Documentation extends React.Component<DocumentationProps, Documenta return renderedSections; } private _renderSection(typeDefinitionByName: TypeDefinitionByName, sectionName: string): React.ReactNode { - const markdownFileIfExists = this.props.docsInfo.sectionNameToMarkdown[sectionName]; + const markdownVersions = _.keys(this.props.docsInfo.sectionNameToMarkdownByVersion); + const eligibleVersions = _.filter(markdownVersions, mdVersion => { + return semver.lte(mdVersion, this.props.selectedVersion); + }); + if (_.isEmpty(eligibleVersions)) { + throw new Error( + `No eligible markdown sections found for ${this.props.docsInfo.displayName} version ${ + this.props.selectedVersion + }.`, + ); + } + const sortedEligibleVersions = eligibleVersions.sort(semver.rcompare.bind(semver)); + const closestVersion = sortedEligibleVersions[0]; + const markdownFileIfExists = this.props.docsInfo.sectionNameToMarkdownByVersion[closestVersion][sectionName]; if (!_.isUndefined(markdownFileIfExists)) { return ( <MarkdownSection @@ -289,7 +299,7 @@ export class Documentation extends React.Component<DocumentationProps, Documenta </div> ); } - private _renderNetworkBadgesIfExists(sectionName: string) { + private _renderNetworkBadgesIfExists(sectionName: string): React.ReactNode { if (this.props.docsInfo.type !== SupportedDocJson.Doxity) { return null; } @@ -337,7 +347,7 @@ export class Documentation extends React.Component<DocumentationProps, Documenta return ( <div key={`property-${property.name}-${property.type.name}`} className="pb3"> <code className={`hljs ${constants.TYPE_TO_SYNTAX[this.props.docsInfo.type]}`}> - {property.name}: + {property.name}:{' '} <Type type={property.type} sectionName={sectionName} docsInfo={this.props.docsInfo} /> </code> {property.source && ( @@ -368,17 +378,17 @@ export class Documentation extends React.Component<DocumentationProps, Documenta /> ); } - private _onSidebarHover(event: React.FormEvent<HTMLInputElement>) { + private _onSidebarHover(_event: React.FormEvent<HTMLInputElement>): void { this.setState({ isHoveringSidebar: true, }); } - private _onSidebarHoverOff() { + private _onSidebarHoverOff(): void { this.setState({ isHoveringSidebar: false, }); } - private _onHashChanged(event: any) { + private _onHashChanged(_event: any): void { const hash = window.location.hash.slice(1); sharedUtils.scrollToHash(hash, sharedConstants.SCROLL_CONTAINER_ID); } diff --git a/packages/react-docs/src/components/enum.tsx b/packages/react-docs/src/components/enum.tsx index 37f82f26e..dee866790 100644 --- a/packages/react-docs/src/components/enum.tsx +++ b/packages/react-docs/src/components/enum.tsx @@ -7,8 +7,8 @@ export interface EnumProps { values: EnumValue[]; } -export function Enum(props: EnumProps) { - const values = _.map(props.values, (value, i) => { +export const Enum = (props: EnumProps) => { + const values = _.map(props.values, value => { const defaultValueIfAny = !_.isUndefined(value.defaultValue) ? ` = ${value.defaultValue}` : ''; return `\n\t${value.name}${defaultValueIfAny},`; }); @@ -20,4 +20,4 @@ export function Enum(props: EnumProps) { {`}`} </span> ); -} +}; diff --git a/packages/react-docs/src/components/event_definition.tsx b/packages/react-docs/src/components/event_definition.tsx index 67729ac87..b4dc729a9 100644 --- a/packages/react-docs/src/components/event_definition.tsx +++ b/packages/react-docs/src/components/event_definition.tsx @@ -24,7 +24,7 @@ export class EventDefinition extends React.Component<EventDefinitionProps, Event shouldShowAnchor: false, }; } - public render() { + public render(): React.ReactNode { const event = this.props.event; const id = `${this.props.sectionName}-${event.name}`; return ( @@ -49,7 +49,7 @@ export class EventDefinition extends React.Component<EventDefinitionProps, Event </div> ); } - private _renderEventCode() { + private _renderEventCode(): React.ReactNode { const indexed = <span style={{ color: colors.green }}> indexed</span>; const eventArgs = _.map(this.props.event.eventArgs, (eventArg: EventArg) => { const type = ( @@ -76,7 +76,7 @@ export class EventDefinition extends React.Component<EventDefinitionProps, Event </span> ); } - private _setAnchorVisibility(shouldShowAnchor: boolean) { + private _setAnchorVisibility(shouldShowAnchor: boolean): void { this.setState({ shouldShowAnchor, }); diff --git a/packages/react-docs/src/components/interface.tsx b/packages/react-docs/src/components/interface.tsx index 541e164e3..a881c7fec 100644 --- a/packages/react-docs/src/components/interface.tsx +++ b/packages/react-docs/src/components/interface.tsx @@ -13,13 +13,13 @@ export interface InterfaceProps { docsInfo: DocsInfo; } -export function Interface(props: InterfaceProps) { +export const Interface = (props: InterfaceProps) => { const type = props.type; const properties = _.map(type.children, property => { return ( <span key={`property-${property.name}-${property.type}-${type.name}`}> {property.name}:{' '} - {property.type.typeDocType !== TypeDocTypes.Reflection ? ( + {property.type && property.type.typeDocType !== TypeDocTypes.Reflection ? ( <Type type={property.type} sectionName={props.sectionName} docsInfo={props.docsInfo} /> ) : ( <Signature @@ -27,7 +27,6 @@ export function Interface(props: InterfaceProps) { returnType={property.type.method.returnType} parameters={property.type.method.parameters} typeParameter={property.type.method.typeParameter} - callPath={property.type.method.callPath} sectionName={props.sectionName} shouldHideMethodName={true} shouldUseArrowSyntax={true} @@ -64,4 +63,4 @@ export function Interface(props: InterfaceProps) { {`}`} </span> ); -} +}; diff --git a/packages/react-docs/src/components/signature.tsx b/packages/react-docs/src/components/signature.tsx index 83fb1e246..77e9cc909 100644 --- a/packages/react-docs/src/components/signature.tsx +++ b/packages/react-docs/src/components/signature.tsx @@ -1,6 +1,5 @@ import * as _ from 'lodash'; import * as React from 'react'; -import * as ReactDOM from 'react-dom'; import { DocsInfo } from '../docs_info'; import { Parameter, Type as TypeDef, TypeDefinitionByName, TypeParameter } from '../types'; @@ -88,9 +87,10 @@ function renderParameters( docsInfo: DocsInfo, sectionName: string, typeDefinitionByName?: TypeDefinitionByName, -) { +): React.ReactNode[] { const params = _.map(parameters, (p: Parameter) => { const isOptional = p.isOptional; + const hasDefaultValue = !_.isUndefined(p.defaultValue); const type = ( <Type type={p.type} @@ -103,6 +103,7 @@ function renderParameters( <span key={`param-${p.type}-${p.name}`}> {p.name} {isOptional && '?'}: {type} + {hasDefaultValue && ` = ${p.defaultValue}`} </span> ); }); @@ -114,7 +115,7 @@ function renderTypeParameter( docsInfo: DocsInfo, sectionName: string, typeDefinitionByName?: TypeDefinitionByName, -) { +): React.ReactNode { const typeParam = ( <span> {`<${typeParameter.name} extends `} diff --git a/packages/react-docs/src/components/signature_block.tsx b/packages/react-docs/src/components/signature_block.tsx index 6475d3995..9e5198e16 100644 --- a/packages/react-docs/src/components/signature_block.tsx +++ b/packages/react-docs/src/components/signature_block.tsx @@ -42,7 +42,7 @@ export class SignatureBlock extends React.Component<SignatureBlockProps, Signatu shouldShowAnchor: false, }; } - public render() { + public render(): React.ReactNode { const method = this.props.method; if (typeDocUtils.isPrivateOrProtectedProperty(method.name)) { return null; @@ -111,14 +111,14 @@ export class SignatureBlock extends React.Component<SignatureBlockProps, Signatu </div> ); } - private _renderChip(text: string) { + private _renderChip(text: string): React.ReactNode { return ( <div className="p1 mr1" style={styles.chip}> {text} </div> ); } - private _renderParameterDescriptions(parameters: Parameter[]) { + private _renderParameterDescriptions(parameters: Parameter[]): React.ReactNode { const descriptions = _.map(parameters, parameter => { const isOptional = parameter.isOptional; return ( @@ -146,7 +146,7 @@ export class SignatureBlock extends React.Component<SignatureBlockProps, Signatu }); return descriptions; } - private _setAnchorVisibility(shouldShowAnchor: boolean) { + private _setAnchorVisibility(shouldShowAnchor: boolean): void { this.setState({ shouldShowAnchor, }); diff --git a/packages/react-docs/src/components/source_link.tsx b/packages/react-docs/src/components/source_link.tsx index 89956a507..c60435ea6 100644 --- a/packages/react-docs/src/components/source_link.tsx +++ b/packages/react-docs/src/components/source_link.tsx @@ -1,5 +1,4 @@ import { colors } from '@0xproject/react-shared'; -import * as _ from 'lodash'; import * as React from 'react'; import { Source } from '../types'; @@ -10,7 +9,7 @@ export interface SourceLinkProps { version: string; } -export function SourceLink(props: SourceLinkProps) { +export const SourceLink = (props: SourceLinkProps) => { const src = props.source; const sourceCodeUrl = `${props.sourceUrl}/${src.fileName}#L${src.line}`; return ( @@ -20,4 +19,4 @@ export function SourceLink(props: SourceLinkProps) { </a> </div> ); -} +}; diff --git a/packages/react-docs/src/components/type.tsx b/packages/react-docs/src/components/type.tsx index fd4562ce3..e453349ef 100644 --- a/packages/react-docs/src/components/type.tsx +++ b/packages/react-docs/src/components/type.tsx @@ -1,4 +1,5 @@ import { colors, constants as sharedConstants, utils as sharedUtils } from '@0xproject/react-shared'; +import { errorUtils } from '@0xproject/utils'; import * as _ from 'lodash'; import * as React from 'react'; import { Link as ScrollLink } from 'react-scroll'; @@ -6,22 +7,10 @@ import * as ReactTooltip from 'react-tooltip'; import { DocsInfo } from '../docs_info'; import { Type as TypeDef, TypeDefinitionByName, TypeDocTypes } from '../types'; -import { constants } from '../utils/constants'; -import { utils } from '../utils/utils'; import { Signature } from './signature'; import { TypeDefinition } from './type_definition'; -const typeToSection: { [typeName: string]: string } = { - ExchangeWrapper: 'exchange', - TokenWrapper: 'token', - TokenRegistryWrapper: 'tokenRegistry', - EtherTokenWrapper: 'etherToken', - ProxyWrapper: 'proxy', - TokenTransferProxyWrapper: 'proxy', - OrderStateWatcher: 'orderWatcher', -}; - export interface TypeProps { type: TypeDef; docsInfo: DocsInfo; @@ -109,7 +98,6 @@ export function Type(props: TypeProps): any { returnType={type.method.returnType} parameters={type.method.parameters} typeParameter={type.method.typeParameter} - callPath={type.method.callPath} sectionName={props.sectionName} shouldHideMethodName={true} shouldUseArrowSyntax={true} @@ -141,7 +129,7 @@ export function Type(props: TypeProps): any { break; default: - throw utils.spawnSwitchErr('type.typeDocType', type.typeDocType); + throw errorUtils.spawnSwitchErr('type.typeDocType', type.typeDocType); } // HACK: Normalize BigNumber to simply BigNumber. For some reason the type // name is unpredictably one or the other. diff --git a/packages/react-docs/src/components/type_definition.tsx b/packages/react-docs/src/components/type_definition.tsx index 7a1c86da5..c4bd7359a 100644 --- a/packages/react-docs/src/components/type_definition.tsx +++ b/packages/react-docs/src/components/type_definition.tsx @@ -1,11 +1,11 @@ import { AnchorTitle, colors, HeaderSizes } from '@0xproject/react-shared'; +import { errorUtils } from '@0xproject/utils'; import * as _ from 'lodash'; import * as React from 'react'; import { DocsInfo } from '../docs_info'; import { CustomType, CustomTypeChild, KindString, TypeDocTypes } from '../types'; import { constants } from '../utils/constants'; -import { utils } from '../utils/utils'; import { Comment } from './comment'; import { CustomEnum } from './custom_enum'; @@ -35,7 +35,7 @@ export class TypeDefinition extends React.Component<TypeDefinitionProps, TypeDef shouldShowAnchor: false, }; } - public render() { + public render(): React.ReactNode { const customType = this.props.customType; if (!this.props.docsInfo.isPublicType(customType.name)) { return null; // no-op @@ -96,7 +96,7 @@ export class TypeDefinition extends React.Component<TypeDefinitionProps, TypeDef break; default: - throw utils.spawnSwitchErr('type.kindString', customType.kindString); + throw errorUtils.spawnSwitchErr('type.kindString', customType.kindString); } const typeDefinitionAnchorId = `${this.props.sectionName}-${customType.name}`; @@ -122,14 +122,55 @@ export class TypeDefinition extends React.Component<TypeDefinitionProps, TypeDef </pre> </div> <div style={{ maxWidth: 620 }}> - {customType.comment && <Comment comment={customType.comment} className="py2" />} + {customType.comment && ( + <Comment comment={this._formatComment(customType.comment)} className="py2" /> + )} </div> </div> ); } - private _setAnchorVisibility(shouldShowAnchor: boolean) { + private _setAnchorVisibility(shouldShowAnchor: boolean): void { this.setState({ shouldShowAnchor, }); } + /** + * Type definition comments usually describe the type as a whole or the individual + * properties within the type. Since TypeDoc just treats these comments simply as + * one paragraph, we do some additional formatting so that we can display individual + * property comments on their own lines. + * E.g: + * Interface SomeConfig + * { + * networkId: number, + * derivationPath: string, + * } + * networkId: The ethereum networkId to set as the chainId from EIP155 + * derivationPath: Initial derivation path to use e.g 44'/60'/0' + * + * Each property description should be on a new line. + */ + private _formatComment(text: string): string { + const NEW_LINE_REGEX = /(\r\n|\n|\r)/gm; + const sanitizedText = text.replace(NEW_LINE_REGEX, ' '); + const PROPERTY_DESCRIPTION_DIVIDER = ':'; + if (!_.includes(sanitizedText, PROPERTY_DESCRIPTION_DIVIDER)) { + return sanitizedText; + } + const segments = sanitizedText.split(PROPERTY_DESCRIPTION_DIVIDER); + _.each(segments, (s: string, i: number) => { + if (i === 0) { + segments[i] = `**${s}**`; + return; + } else if (i === segments.length - 1) { + return; + } + const words = s.split(' '); + const property = words[words.length - 1]; + words[words.length - 1] = `\n\n**${property}**`; + segments[i] = words.join(' '); + }); + const final = segments.join(PROPERTY_DESCRIPTION_DIVIDER); + return final; + } } |