Merge pull request #1103 from 0xProject/doc-overview-page

Implement Developer Home

9 files changed, 215 insertions, 61 deletions

diff --git a/packages/react-shared/package.json b/packages/react-shared/package.json
index 95bf849ad..490933fb3 100644
--- a/packages/react-shared/package.json
+++ b/packages/react-shared/package.json
@@ -34,6 +34,7 @@
         "typescript": "3.0.1"
     },
     "dependencies": {
+        "@0xproject/types": "^1.1.2",
         "@material-ui/core": "^3.0.1",
         "@types/is-mobile": "0.3.0",
         "@types/lodash": "4.14.104",
@@ -41,7 +42,9 @@
         "@types/node": "*",
         "@types/react": "*",
         "@types/react-dom": "*",
+        "@types/react-router-dom": "^4.0.4",
         "@types/react-scroll": "1.5.3",
+        "@types/valid-url": "^1.0.2",
         "basscss": "^8.0.3",
         "change-case": "^3.0.2",
         "is-mobile": "^0.2.2",
@@ -51,7 +54,9 @@
         "react-dom": "^16.4.2",
         "react-highlight": "0xproject/react-highlight#2f40a42e0a3f0ad126f9f42d505b97b603fc7162",
         "react-markdown": "^3.2.2",
-        "react-scroll": "0xproject/react-scroll#similar-to-pr-330"
+        "react-scroll": "0xproject/react-scroll#similar-to-pr-330",
+        "react-router-dom": "^4.1.1",
+        "valid-url": "^1.0.9"
     },
     "publishConfig": {
         "access": "public"
diff --git a/packages/react-shared/src/components/anchor_title.tsx b/packages/react-shared/src/components/anchor_title.tsx
index 8f7e4af27..a83881b67 100644
--- a/packages/react-shared/src/components/anchor_title.tsx
+++ b/packages/react-shared/src/components/anchor_title.tsx
@@ -71,7 +71,7 @@ export class AnchorTitle extends React.Component<AnchorTitleProps, AnchorTitleSt
                     hashSpy={true}
                     offset={headerSizeToScrollOffset[this.props.headerSize]}
                     duration={constants.DOCS_SCROLL_DURATION_MS}
-                    containerId={constants.DOCS_CONTAINER_ID}
+                    containerId={constants.SCROLL_CONTAINER_ID}
                 >
                     <i
                         className="zmdi zmdi-link"
diff --git a/packages/react-shared/src/components/link.tsx b/packages/react-shared/src/components/link.tsx
new file mode 100644
index 000000000..5a456109b
--- /dev/null
+++ b/packages/react-shared/src/components/link.tsx
@@ -0,0 +1,131 @@
+import * as _ from 'lodash';
+import * as React from 'react';
+import { Link as ReactRounterLink } from 'react-router-dom';
+import { Link as ScrollLink } from 'react-scroll';
+import * as validUrl from 'valid-url';
+
+import { LinkType } from '../types';
+import { constants } from '../utils/constants';
+
+interface LinkProps {
+    to: string;
+    shouldOpenInNewTab?: boolean;
+    className?: string;
+    onMouseOver?: (event: React.MouseEvent<HTMLElement>) => void;
+    onMouseLeave?: (event: React.MouseEvent<HTMLElement>) => void;
+    onMouseEnter?: (event: React.MouseEvent<HTMLElement>) => void;
+    textDecoration?: string;
+    fontColor?: string;
+}
+
+export interface LinkState {}
+
+/**
+ * A generic link component which let's the developer render internal, external and scroll-to-hash links, and
+ * their associated behaviors with a single link component. Many times we want a menu including a combination of
+ * internal, external and scroll links and the abstraction of the differences of rendering each types of link
+ * makes it much easier to do so.
+ */
+export class Link extends React.Component<LinkProps, LinkState> {
+    public static defaultProps: Partial<LinkProps> = {
+        shouldOpenInNewTab: false,
+        className: '',
+        onMouseOver: _.noop.bind(_),
+        onMouseLeave: _.noop.bind(_),
+        onMouseEnter: _.noop.bind(_),
+        textDecoration: 'none',
+        fontColor: 'inherit',
+    };
+    private _outerReactScrollSpan: HTMLSpanElement | null;
+    constructor(props: LinkProps) {
+        super(props);
+        this._outerReactScrollSpan = null;
+    }
+    public render(): React.ReactNode {
+        let type: LinkType;
+        const isReactRoute = _.startsWith(this.props.to, '/');
+        const isExternal = validUrl.isWebUri(this.props.to) || _.startsWith(this.props.to, 'mailto:');
+        if (isReactRoute) {
+            type = LinkType.ReactRoute;
+        } else if (isExternal) {
+            type = LinkType.External;
+        } else {
+            type = LinkType.ReactScroll;
+        }
+
+        if (type === LinkType.ReactScroll && this.props.shouldOpenInNewTab) {
+            throw new Error(`Cannot open LinkType.ReactScroll links in new tab. link.to: ${this.props.to}`);
+        }
+
+        const styleWithDefault = {
+            textDecoration: this.props.textDecoration,
+            cursor: 'pointer',
+            color: this.props.fontColor,
+        };
+
+        switch (type) {
+            case LinkType.External:
+                return (
+                    <a
+                        target={this.props.shouldOpenInNewTab ? '_blank' : ''}
+                        className={this.props.className}
+                        style={styleWithDefault}
+                        href={this.props.to}
+                        onMouseOver={this.props.onMouseOver}
+                        onMouseEnter={this.props.onMouseEnter}
+                        onMouseLeave={this.props.onMouseLeave}
+                    >
+                        {this.props.children}
+                    </a>
+                );
+            case LinkType.ReactRoute:
+                return (
+                    <ReactRounterLink
+                        to={this.props.to}
+                        className={this.props.className}
+                        style={styleWithDefault}
+                        target={this.props.shouldOpenInNewTab ? '_blank' : ''}
+                        onMouseOver={this.props.onMouseOver}
+                        onMouseEnter={this.props.onMouseEnter}
+                        onMouseLeave={this.props.onMouseLeave}
+                    >
+                        {this.props.children}
+                    </ReactRounterLink>
+                );
+            case LinkType.ReactScroll:
+                return (
+                    <span
+                        ref={input => (this._outerReactScrollSpan = input)}
+                        onMouseOver={this.props.onMouseOver}
+                        onMouseEnter={this.props.onMouseEnter}
+                        onMouseLeave={this.props.onMouseLeave}
+                    >
+                        <ScrollLink
+                            to={this.props.to}
+                            offset={0}
+                            hashSpy={true}
+                            duration={constants.DOCS_SCROLL_DURATION_MS}
+                            containerId={constants.SCROLL_CONTAINER_ID}
+                            className={this.props.className}
+                            style={styleWithDefault}
+                        >
+                            <span onClick={this._onClickPropagateClickEventAroundScrollLink.bind(this)}>
+                                {this.props.children}
+                            </span>
+                        </ScrollLink>
+                    </span>
+                );
+            default:
+                throw new Error(`Unrecognized LinkType: ${type}`);
+        }
+    }
+    // HACK(fabio): For some reason, the react-scroll link decided to stop the propagation of click events.
+    // We do however rely on these events being propagated in certain scenarios (e.g when the link
+    // is within a dropdown we want to close upon being clicked). Because of this, we register the
+    // click event of an inner span, and pass it around the react-scroll link to an outer span.
+    private _onClickPropagateClickEventAroundScrollLink(): void {
+        if (!_.isNull(this._outerReactScrollSpan)) {
+            this._outerReactScrollSpan.click();
+        }
+    }
+}
diff --git a/packages/react-shared/src/components/markdown_section.tsx b/packages/react-shared/src/components/markdown_section.tsx
index 09b214548..e84d2b078 100644
--- a/packages/react-shared/src/components/markdown_section.tsx
+++ b/packages/react-shared/src/components/markdown_section.tsx
@@ -8,6 +8,7 @@ import { colors } from '../utils/colors';
 import { utils } from '../utils/utils';
 
 import { AnchorTitle } from './anchor_title';
+import { Link } from './link';
 import { MarkdownCodeBlock } from './markdown_code_block';
 import { MarkdownLinkBlock } from './markdown_link_block';
 
@@ -63,13 +64,11 @@ export class MarkdownSection extends React.Component<MarkdownSectionProps, Markd
                         </div>
                         <div className="col col-4 sm-hide xs-hide right-align pr3" style={{ height: 28 }}>
                             {!_.isUndefined(githubLink) && (
-                                <a
-                                    href={githubLink}
-                                    target="_blank"
-                                    style={{ color: colors.linkBlue, textDecoration: 'none', lineHeight: 2.1 }}
-                                >
-                                    Edit on Github
-                                </a>
+                                <div style={{ lineHeight: 2.1 }}>
+                                    <Link to={githubLink} shouldOpenInNewTab={true} fontColor={colors.linkBlue}>
+                                        Edit on Github
+                                    </Link>
+                                </div>
                             )}
                         </div>
                     </div>
diff --git a/packages/react-shared/src/components/nested_sidebar_menu.tsx b/packages/react-shared/src/components/nested_sidebar_menu.tsx
index c8bddb59a..5b6076df6 100644
--- a/packages/react-shared/src/components/nested_sidebar_menu.tsx
+++ b/packages/react-shared/src/components/nested_sidebar_menu.tsx
@@ -1,24 +1,25 @@
+import { ObjectMap } from '@0xproject/types';
 import * as _ from 'lodash';
 import MenuItem from 'material-ui/MenuItem';
 import * as React from 'react';
-import { Link as ScrollLink } from 'react-scroll';
 
-import { MenuSubsectionsBySection, Styles } from '../types';
+import { ALink, Styles } from '../types';
 import { colors } from '../utils/colors';
-import { constants } from '../utils/constants';
 import { utils } from '../utils/utils';
 
+import { Link } from './link';
 import { VersionDropDown } from './version_drop_down';
 
 export interface NestedSidebarMenuProps {
-    topLevelMenu: { [topLevel: string]: string[] };
-    menuSubsectionsBySection: MenuSubsectionsBySection;
+    sectionNameToLinks: ObjectMap<ALink[]>;
+    subsectionNameToLinks?: ObjectMap<ALink[]>;
     sidebarHeader?: React.ReactNode;
     shouldDisplaySectionHeaders?: boolean;
     onMenuItemClick?: () => void;
     selectedVersion?: string;
     versions?: string[];
     onVersionSelected?: (semver: string) => void;
+    shouldReformatMenuItemNames?: boolean;
 }
 
 export interface NestedSidebarMenuState {}
@@ -42,23 +43,24 @@ export class NestedSidebarMenu extends React.Component<NestedSidebarMenuProps, N
     public static defaultProps: Partial<NestedSidebarMenuProps> = {
         shouldDisplaySectionHeaders: true,
         onMenuItemClick: _.noop.bind(_),
+        shouldReformatMenuItemNames: true,
+        subsectionNameToLinks: {},
     };
     public render(): React.ReactNode {
-        const navigation = _.map(this.props.topLevelMenu, (menuItems: string[], sectionName: string) => {
+        const navigation = _.map(this.props.sectionNameToLinks, (links: ALink[], sectionName: string) => {
             const finalSectionName = utils.convertCamelCaseToSpaces(sectionName);
             if (this.props.shouldDisplaySectionHeaders) {
                 // tslint:disable-next-line:no-unused-variable
-                const id = utils.getIdFromName(sectionName);
                 return (
-                    <div key={`section-${sectionName}`} className="py1" style={{ color: colors.grey800 }}>
-                        <div style={{ fontWeight: 'bold', fontSize: 15 }} className="py1">
+                    <div key={`section-${sectionName}`} className="py1" style={{ color: colors.linkSectionGrey }}>
+                        <div style={{ fontWeight: 'bold', fontSize: 15, letterSpacing: 0.5 }} className="py1">
                             {finalSectionName.toUpperCase()}
                         </div>
-                        {this._renderMenuItems(menuItems)}
+                        {this._renderMenuItems(links)}
                     </div>
                 );
             } else {
-                return <div key={`section-${sectionName}`}>{this._renderMenuItems(menuItems)}</div>;
+                return <div key={`section-${sectionName}`}>{this._renderMenuItems(links)}</div>;
             }
         });
         const maxWidthWithScrollbar = 307;
@@ -80,55 +82,55 @@ export class NestedSidebarMenu extends React.Component<NestedSidebarMenuProps, N
             </div>
         );
     }
-    private _renderMenuItems(menuItemNames: string[]): React.ReactNode[] {
+    private _renderMenuItems(links: ALink[]): React.ReactNode[] {
         const menuItemStyles = this.props.shouldDisplaySectionHeaders
             ? styles.menuItemWithHeaders
             : styles.menuItemWithoutHeaders;
         const menuItemInnerDivStyles = this.props.shouldDisplaySectionHeaders ? styles.menuItemInnerDivWithHeaders : {};
-        const menuItems = _.map(menuItemNames, menuItemName => {
-            const finalMenuItemName = utils.convertDashesToSpaces(menuItemName);
-            const id = utils.getIdFromName(menuItemName);
+        const menuItems = _.map(links, link => {
+            const finalMenuItemName = this.props.shouldReformatMenuItemNames
+                ? utils.convertDashesToSpaces(link.title)
+                : link.title;
             return (
-                <div key={menuItemName}>
-                    <ScrollLink
-                        key={`menuItem-${menuItemName}`}
-                        to={id}
-                        offset={0}
-                        hashSpy={true}
-                        duration={constants.DOCS_SCROLL_DURATION_MS}
-                        containerId={constants.DOCS_CONTAINER_ID}
-                    >
-                        <MenuItem style={menuItemStyles} innerDivStyle={menuItemInnerDivStyles}>
-                            <span style={{ textTransform: 'capitalize' }}>{finalMenuItemName}</span>
+                <div key={`menuItem-${finalMenuItemName}`}>
+                    <Link to={link.to} shouldOpenInNewTab={link.shouldOpenInNewTab}>
+                        <MenuItem
+                            style={menuItemStyles}
+                            innerDivStyle={menuItemInnerDivStyles}
+                            onClick={this._onMenuItemClick.bind(this)}
+                        >
+                            <span
+                                style={{
+                                    textTransform: this.props.shouldReformatMenuItemNames ? 'capitalize' : 'none',
+                                }}
+                            >
+                                {finalMenuItemName}
+                            </span>
                         </MenuItem>
-                    </ScrollLink>
-                    {this._renderMenuItemSubsections(menuItemName)}
+                    </Link>
+                    {this._renderMenuItemSubsections(link.title)}
                 </div>
             );
         });
         return menuItems;
     }
     private _renderMenuItemSubsections(menuItemName: string): React.ReactNode {
-        if (_.isUndefined(this.props.menuSubsectionsBySection[menuItemName])) {
+        if (
+            _.isUndefined(this.props.subsectionNameToLinks) ||
+            _.isUndefined(this.props.subsectionNameToLinks[menuItemName])
+        ) {
             return null;
         }
-        return this._renderMenuSubsectionsBySection(menuItemName, this.props.menuSubsectionsBySection[menuItemName]);
+        return this._renderSubsectionLinks(menuItemName, this.props.subsectionNameToLinks[menuItemName]);
     }
-    private _renderMenuSubsectionsBySection(menuItemName: string, entityNames: string[]): React.ReactNode {
+    private _renderSubsectionLinks(menuItemName: string, links: ALink[]): React.ReactNode {
         return (
             <ul style={{ margin: 0, listStyleType: 'none', paddingLeft: 0 }} key={menuItemName}>
-                {_.map(entityNames, entityName => {
-                    const name = `${menuItemName}-${entityName}`;
-                    const id = utils.getIdFromName(name);
+                {_.map(links, link => {
+                    const name = `${menuItemName}-${link.title}`;
                     return (
                         <li key={`menuSubsectionItem-${name}`}>
-                            <ScrollLink
-                                to={id}
-                                offset={0}
-                                hashSpy={true}
-                                duration={constants.DOCS_SCROLL_DURATION_MS}
-                                containerId={constants.DOCS_CONTAINER_ID}
-                            >
+                            <Link to={link.to} shouldOpenInNewTab={link.shouldOpenInNewTab}>
                                 <MenuItem
                                     style={{ minHeight: 35 }}
                                     innerDivStyle={{
@@ -136,14 +138,20 @@ export class NestedSidebarMenu extends React.Component<NestedSidebarMenuProps, N
                                         fontSize: 14,
                                         lineHeight: '35px',
                                     }}
+                                    onClick={this._onMenuItemClick.bind(this)}
                                 >
-                                    {entityName}
+                                    {link.title}
                                 </MenuItem>
-                            </ScrollLink>
+                            </Link>
                         </li>
                     );
                 })}
             </ul>
         );
     }
+    private _onMenuItemClick(): void {
+        if (!_.isUndefined(this.props.onMenuItemClick)) {
+            this.props.onMenuItemClick();
+        }
+    }
 }
diff --git a/packages/react-shared/src/index.ts b/packages/react-shared/src/index.ts
index 3b50c0117..e33b09f19 100644
--- a/packages/react-shared/src/index.ts
+++ b/packages/react-shared/src/index.ts
@@ -4,8 +4,9 @@ export { MarkdownCodeBlock } from './components/markdown_code_block';
 export { MarkdownSection } from './components/markdown_section';
 export { NestedSidebarMenu } from './components/nested_sidebar_menu';
 export { SectionHeader } from './components/section_header';
+export { Link } from './components/link';
 
-export { HeaderSizes, Styles, MenuSubsectionsBySection, EtherscanLinkSuffixes, Networks } from './types';
+export { HeaderSizes, Styles, EtherscanLinkSuffixes, Networks, ALink } from './types';
 
 export { utils } from './utils/utils';
 export { constants } from './utils/constants';
diff --git a/packages/react-shared/src/types.ts b/packages/react-shared/src/types.ts
index 88fadcc09..9e8dcb6b6 100644
--- a/packages/react-shared/src/types.ts
+++ b/packages/react-shared/src/types.ts
@@ -8,10 +8,6 @@ export enum HeaderSizes {
     H3 = 'h3',
 }
 
-export interface MenuSubsectionsBySection {
-    [section: string]: string[];
-}
-
 export enum EtherscanLinkSuffixes {
     Address = 'address',
     Tx = 'tx',
@@ -23,3 +19,15 @@ export enum Networks {
     Ropsten = 'Ropsten',
     Rinkeby = 'Rinkeby',
 }
+
+export enum LinkType {
+    External = 'EXTERNAL',
+    ReactScroll = 'REACT_SCROLL',
+    ReactRoute = 'REACT_ROUTE',
+}
+
+export interface ALink {
+    title: string;
+    to: string;
+    shouldOpenInNewTab?: boolean;
+}
diff --git a/packages/react-shared/src/utils/colors.ts b/packages/react-shared/src/utils/colors.ts
index 5a20eeaa1..596c17e83 100644
--- a/packages/react-shared/src/utils/colors.ts
+++ b/packages/react-shared/src/utils/colors.ts
@@ -9,7 +9,8 @@ const baseColors = {
     grey300: '#E0E0E0',
     beigeWhite: '#E4E4E4',
     lightBgGrey: '#EDEDED',
-    grey350: '#cacaca',
+    grey325: '#dfdfdf',
+    grey350: '#CACACA',
     grey400: '#BDBDBD',
     lightGrey: '#BBBBBB',
     grey500: '#9E9E9E',
@@ -24,10 +25,12 @@ const baseColors = {
     heroGrey: '#404040',
     projectsGrey: '#343333',
     darkestGrey: '#272727',
+    lightestBlue: '#E7F1FD',
     lightBlue: '#60A4F4',
     lightBlueA700: '#0091EA',
-    linkBlue: '#1D5CDE',
+    lightLinkBlue: '#3289F1',
     mediumBlue: '#488AEA',
+    linkBlue: '#1D5CDE',
     darkBlue: '#4D5481',
     lightTurquois: '#aefcdc',
     turquois: '#058789',
diff --git a/packages/react-shared/src/utils/constants.ts b/packages/react-shared/src/utils/constants.ts
index 562ab776b..2dca1a078 100644
--- a/packages/react-shared/src/utils/constants.ts
+++ b/packages/react-shared/src/utils/constants.ts
@@ -2,8 +2,7 @@ import { Networks } from '../types';
 
 export const constants = {
     DOCS_SCROLL_DURATION_MS: 0,
-    DOCS_CONTAINER_ID: 'documentation',
-    SCROLL_CONTAINER_ID: 'documentation',
+    SCROLL_CONTAINER_ID: 'scroll_container',
     SCROLL_TOP_ID: 'pageScrollTop',
     NETWORK_NAME_BY_ID: {
         1: Networks.Mainnet,