Merge branch 'master' of github.com:MMF-FE/vue-typescript

Author: Allenice

docs/en/Api.md

@@ -0,0 +1,49 @@
+# Use APIs
+Use [axios](https://github.com/mzabriskie/axios) as default http client
+
+## http.ts
+
+**src/api/http.ts** already sealed axios. Right now it only sealed get and post methods inside. Other http request methods can be extended by yourself.
+
+### get
+
+```typescript
+function get<T>(url, data?: Types.PlainObject): Promise<T> {
+}
+```
+**T** is the type response data 
+
+```typescript
+// The /list response data type is {status: number,list: any[]}
+{
+    getList (params: any) {
+        return get<{
+            status: number
+            list: any[]
+        }>('/list', params)
+    }
+}
+```
+
+### post
+```typescript
+function post<T>(url, data?: Types.PlainObject): Promise<T> {
+}
+
+```
+
+## index.ts
+**src/api/index.ts** is server-side api configuration. It seperates different modules into several files.
+## Use Api in Components
+Each Components has **api** property by default, which comes from src/api/index.ts
+
+```typescript
+export default class Home extends Vue {
+    async created () {
+        // api example
+        let res = await this.api.getList({})
+        console.log(res.list)
+    }
+}
+
+```

docs/en/Command.md

@@ -0,0 +1,61 @@
+# Commands
+```bash
+# Start Dev
+npm run dev
+
+# Build developing environment
+npm run build:dev
+
+# Build sit environment
+npm run build:sit
+
+# Build deploy environment
+npm run deploy
+
+# Generate svg icons
+npm run svg
+
+```
+
+## Add compoents by just one command
+Use the script in **./tools/cli.js** to add components. Components templates are under tools/tpl. You can change based on your needs.
+
+```text
+Options：
+  --version, -v  show version                   [boolean]
+  --help, -h     show help manual               [boolean]
+  --type, -t     The component type
+  --root, -r     The component root path        [default: "src/components"]
+```
+Default path is **src/components**
+```bash
+# Add a component, 
+./tools/cli add [componentPath] -t [componentType]
+
+# use npm script
+npm run cli add [componentPath] -- -t [componentType]
+
+# use yarn
+yarn cli add [componentPath] -- -t [componentType]
+```
+### -t
+**-t** is used for marking the type of the component. You can add different components by using different -t parameters. Default type is based on the name of folders under componentPath. For example:
+
+```
+# component type: view
+yarn cli add views/home
+
+# component type: tag
+yarn cli add tags/hello
+
+# component type: tag
+yarn cli add views/home/list -- -t tag
+```
+
+### -r
+**-r** the parameter following is for setting the root path. If the components that you want to make is not under **src/components**, you can set the parameter to set the component's path.
+
+```bash
+yarn cli add tags/hello -- -r demo/components
+```
+the command above creates a tag component under demo/components/tags/hello

docs/en/Component.md

@@ -0,0 +1,88 @@
+# Components
+This template does not use single file component. Each component consists of 4 files. The reason to do like this is because the editor does not support *.vue files well enough.
+
+## Components structrue
+
+```
+// for example, we have a components called 'hello'.
+├── hello.scss
+├── hello.ts        
+├── hello.vue
+└── index.ts
+```
+
+## vue file
+As you can see, component template is using .vue file rather than .html file. That is because we can use vue-loader to take advantage of vue single file.
+
+```html
+<!-- vue file -->
+<template>
+    <div>
+        <h1>Hello {{name}}</h1>
+    </div>
+</template>
+<style src="./hello.scss" lang="scss" scoped></style>
+```
+
+## ts file
+we use [vue-property-decorator](https://github.com/kaorun343/vue-property-decorator) to write typescript component. For the usage, you can read their document.
+
+```typescript
+import Vue from 'components/base'
+import { Component, Prop } from 'vue-property-decorator'
+import template from './hello.vue'
+
+@Component({
+    name: 'tag-hello',
+    mixins: [template] // use mixins to mix vue file functions
+})
+export default class Hello extends Vue {
+    // define prop
+    @Prop({ default: 'World' })
+    name: string
+    
+    // computed
+    get fullname () {
+        return `hello, ${this.name}`
+    }
+    
+    // method
+    say () {
+        console.log(this.fullname)
+    }
+}
+
+
+```
+> Attention：[vue-property-decorator](https://github.com/kaorun343/vue-property-decorator) Component decorator is from [vue-class-component](https://github.com/vuejs/vue-class-component), please read the document.
+
+## Styling
+Please go to chapter [Styling](./Style.md).
+
+## index.ts
+This is component entry file, so that it will be easy to import other components.
+
+```typescript
+export * from './hello.ts'
+```
+
+The reason we don't name hello.ts as index.ts is considering editor is  always showing file name, thus you will never know which component it belongs to, unless you want to change cli compoent template.
+
+## Import other components or templates
+Import root path is src by default.
+
+```js
+// import 'src/components/tags/hello'
+import Hello from 'components/tags/hello'
+```
+If you are using vscode，please consider the following configuration：
+```json
+{
+    "editor.quickSuggestions": {
+        "other": true,
+        "comments": false,
+        "strings": true
+    }
+}
+```
+so when you import module, editor will hint the path.

docs/en/Issues.md

@@ -0,0 +1,20 @@
+# Issues
+Have quite a few compatible issues When update to vue-loader 13.x 和 webpack3.x. The existing issues are as follow:
+
+### change vue file or style will trigger browser refreshing
+This refresh operation is under build/dev-server.js
+```js
+// force page reload when html-webpack-plugin template changes
+compiler.plugin('compilation', function (compilation) {
+    compilation.plugin('html-webpack-plugin-after-emit', function (data, cb) {
+        hotMiddleware.publish({ action: 'reload' })
+        cb()
+    })
+})
+```
+Right now we comment this piece of code, so if anything is changed on html under build/tpl, you need to refresh manually.
+
+### production mode does not extract styles into css file
+When build production, styles in components are not extracted into css files. Now there is no solution for that.
+
+>  If you have any solutions or ideas, please submit [issue](https://github.com/MMF-FE/vue-typescript/issues) or [PR](https://github.com/MMF-FE/vue-typescript/pulls)

docs/en/README.md

@@ -0,0 +1,43 @@
+# Project Structure
+```text
+.
+├── build                   # Webpack build configuration directroy
+│   ├── config              # development and production mode config
+│   │   ├── index.js
+│   ├── tpl                 # html template
+│   │   └── index.html
+│   └── ...
+├── src
+│   ├── api                 # Backend APIs
+│   │   ├── http.ts
+│   │   ├── index.ts
+│   │   └── modules         # API modules
+│   │       └── ...
+│   ├── assets              # module assets (processed by webpack)
+│   │   └── svg             # svg icons source file
+│   │       └── ...
+│   ├── components          # components
+│   │   ├── base.ts         # components base. Every component inherits it 
+│   │   ├── icons           # Produced vue svg icons
+│   │   ├── pages           # Page level components
+│   │   ├── tags            # Global components (or customized tags)
+│   │   └── views           # view components
+│   ├── env                 # environment config
+│   ├── main.ts             # entry file
+│   ├── router              # router
+│   ├── store               # vuex store
+│   │   ├── modules         # vuex modules
+│   │   └── utils           # vuex utils 
+│   └── style               # styles
+├── static                  # pure static assets (directly copied)
+├── tools                   # Tool, such as cli tools
+└── typings                 # Type definitions
+│   ├── globals.d.ts        # global types
+│   └── interface           # interface
+├── tsconfig.json           # typescript config
+├── tslint.json             # tslint config
+├── .editorconfig           # editor config
+├── .npmrc                  # npm config
+├── .postcssrc.js           # postcss config
+├── .stylelintrc.js         # stylint config
+```

docs/en/SUMMARY.MD

@@ -0,0 +1,70 @@
+# Styling
+Use sass(scss) by default. Configuration is under build/utils.js shown as follow:
+
+```js
+scss: generateLoaders('sass', {
+    includePaths: [
+        path.join(__dirname, '../src/style'),
+        path.join(__dirname, '../node_modules')
+    ]
+})
+```
+import sass by default is start from src/style or node_modules, so even you have very deep directory structure, it would be easy to import style.
+> Attention：If import style from node_modules, please prefix  **~**
+
+```scss
+@import "base/base"; // import src/style/base/_base.scss
+
+@import "~normalize.css"; // import node_modules/normalize.css
+```
+
+## base.scss
+src/style/base/_base.scss can only import modules doesn't generate code, such as, variables, mixins, etc. 
+
+## Resouce path（assets）
+sass import（assets）use [postcss-assets](https://github.com/borodean/postcss-assets) reslove method. By default, root path is src/assets/images. You can modify .postcssrc.js to change or add path.
+
+```js
+// .postcssrc.js
+module.exports = {
+    "plugins": {
+        // to edit target browsers: use "browserlist" field in package.json
+        // Browser config is in package.json
+        "autoprefixer": {},
+        "postcss-assets": {
+            relative: true,
+            loadPaths: ['./src/assets/images']
+        }
+    }
+}
+```
+
+```scss
+.logo {
+    // url("src/assets/images/logo.png")
+    // The address in actually page is produced by webpack
+    background-image: resolve("logo.png");
+}
+```
+
+## scoped css
+When add components, the default style already enabled css scoped
+
+```html
+<style src="./home.scss" lang="scss" scoped></style>
+```
+The advantage of css scoped is that components styles will not affect other components styles or vice versa, and does not need to change html template like css module. If you want to override child components styles, you can use ** /deep/ **. Here is the example [scoped example](https://github.com/MMF-FE/vue-typescript/blob/master/template/src/components/views/scoped/scoped.scss)。
+
+```scss
+.parent {
+    color: red;
+    
+    /deep/ {
+        .child {
+            color: green;
+        }
+    }
+}
+```
+> If you don't use sass, you can use **>>>** instead of **/deep/**
+> Because using scoped css, please don't use too many nested selector or don't use nested.

docs/en/Structure.md

@@ -0,0 +1,2 @@
+# Unit Test
+Right now we don't add unit test. If you need unit test, please go to [vuejs-webpack](https://github.com/vuejs-templates/webpack).

docs/en/Style.md

@@ -0,0 +1,25 @@
+# Type definition
+Type definitions is under **typings**. For defining types，please go to [declaration templates](https://www.typescriptlang.org/docs/handbook/declaration-files/templates.html)
+
+
+## Types naming space
+By default, every customized type is under **Types**. You can change names based on your needs.
+
+```typescript
+// typings/interface/index.d.ts
+export as namespace Types
+
+// mix other modules type definition
+export * from './state'
+export * from './todo'
+
+export interface PlainObject {
+    [key: string]: any
+}
+```
+
+You can use **Types** in ts files directly
+
+```typescript
+let a: Types.PlainObject
+```