Sync with upstream

src/v2/examples/index.md

@@ -6,4 +6,4 @@ order: 0
 
 > Dead simple Markdown editor.
 
-<iframe width="100%" height="500" src="https://jsfiddle.net/chrisvfritz/rdjjpc7a/embedded/result,html,js,css" allowfullscreen="allowfullscreen" frameborder="0"></iframe>
+<iframe width="100%" height="500" src="https://jsfiddle.net/chrisvfritz/0dzvcf4d/embedded/result,html,js,css" allowfullscreen="allowfullscreen" frameborder="0"></iframe>

src/v2/guide/components.md

@@ -10,7 +10,7 @@ Components are one of the most powerful features of Vue. They help you extend ba
 
 ## Using Components
 
-### Registration
+### Global Registration
 
 We've learned in the previous sections that we can create a new Vue instance with:
 

src/v2/guide/custom-directive.md

@@ -43,6 +43,9 @@ If you want to register a directive locally instead, components also accept a `d
 directives: {
   focus: {
     // directive definition
+    inserted: function (el) {
+      el.focus()
+    }
   }
 }
 ```

src/v2/guide/instance.md

@@ -120,7 +120,7 @@ new Vue({
 
 Các hook khác như [`mounted`](../api/#mounted), [`updated`](../api/#updated), và [`destroyed`](../api/#destroyed) cũng được gọi vào các giai đoạn khác nhau trong vòng đời của đối tượng. Tất cả các hook này đều được thực thi với ngữ cảnh `this` trỏ đến đối tượng Vue hiện hành.
 
-<p class="tip">Đừng dùng [hàm mũi tên (arrow functions)](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Functions/Arrow_functions) cho các thuộc tính tùy chọn hoặc callback như là `created: () => console.log(this.a)` hoặc `vm.$watch('a', newValue => this.myMethod())`. Vì hàm mũi tên được bind vào ngữ cảnh cha (parent context), `this` sẽ không trỏ đến đối tượng Vue hiện hành và do đó `this.a` hoặc `this.myMethod` sẽ không trả về giá trị mà bạn mong đợi.</p>
+<p class="tip">Đừng dùng [hàm mũi tên (arrow functions)](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Functions/Arrow_functions) cho các thuộc tính tùy chọn hoặc callback như là `created: () => console.log(this.a)` hoặc `vm.$watch('a', newValue => this.myMethod())`. Vì hàm mũi tên được bind vào ngữ cảnh cha (parent context), `this` sẽ không trỏ đến đối tượng Vue hiện hành. Do vậy `this.a` hoặc `this.myMethod` sẽ không trả về giá trị mà bạn mong đợi, mà thay vào đó thường là các lỗi `Uncaught TypeError: Cannot read property of undefined` hoặc `Uncaught TypeError: this.myMethod is not a function`.</p>
 
 ## Sơ đồ vòng đời
 

src/v2/guide/single-file-components.md

@@ -50,6 +50,10 @@ Even if you don't like the idea of Single-File Components, you can still leverag
 
 ## Getting Started
 
+### Example Sandbox
+
+If you want to dive right in and start playing with single-file components, check out [this simple todo app](https://codesandbox.io/s/o29j95wx9) on CodeSandbox.
+
 ### For Users New to Module Build Systems in JavaScript
 
 With `.vue` components, we're entering the realm of advanced JavaScript applications. That means learning to use a few additional tools if you haven't already:
@@ -58,11 +62,9 @@ With `.vue` components, we're entering the realm of advanced JavaScript applicat
 
 - **Modern JavaScript with ES2015/16**: Read through Babel's [Learn ES2015 guide](https://babeljs.io/docs/learn-es2015/). You don't have to memorize every feature right now, but keep this page as a reference you can come back to.
 
-After you've taken a day to dive into these resources, we recommend checking out the [webpack-simple](https://github.com/vuejs-templates/webpack-simple) template. Follow the instructions and you should have a Vue project with `.vue` components, ES2015 and hot-reloading running in no time!
-
-The template uses [Webpack](https://webpack.js.org/), a module bundler that takes a number of "modules" and then bundles them into your final application. To learn more about Webpack itself, check out [their official docs](https://webpack.js.org/configuration/) and [Webpack Academy](https://webpack.academy/p/the-core-concepts).
+After you've taken a day to dive into these resources, we recommend checking out the [webpack](https://vuejs-templates.github.io/webpack) template. Follow the instructions and you should have a Vue project with `.vue` components, ES2015, and hot-reloading in no time!
 
-In Webpack, each module can be transformed by a "loader" before being included in the bundle, and Vue offers the [vue-loader](https://github.com/vuejs/vue-loader) plugin to take care of translating `.vue` single-file components. The [webpack-simple](https://github.com/vuejs-templates/webpack-simple) template has already set up everything for you, but if you'd like to learn more about how `.vue` components work with Webpack, you can read [the docs for vue-loader](https://vue-loader.vuejs.org).
+To learn more about Webpack itself, check out [their official docs](https://webpack.js.org/configuration/) and [Webpack Academy](https://webpack.academy/p/the-core-concepts). In Webpack, each file can be transformed by a "loader" before being included in the bundle, and Vue offers the [vue-loader](https://vue-loader.vuejs.org) plugin to translate single-file (`.vue`) components.
 
 ### For Advanced Users
 

src/v2/style-guide/index.md

@@ -30,7 +30,7 @@ Where multiple, equally good options exist, an arbitrary choice can be made to e
 
 1. train your brain to more easily parse most of the community code you encounter
 2. be able to copy and paste most community code examples without modification
-2. often find new hires are already accustomed to your preferred coding style, at least in regards to Vue
+3. often find new hires are already accustomed to your preferred coding style, at least in regards to Vue
 
 ### Priority D: Use with Caution
 
@@ -352,7 +352,7 @@ Beyond the `scoped` attribute, using unique class names can help ensure that 3rd
   <button class="button button-close">X</button>
 </template>
 
-<!-- Using the scoped attribute -->
+<!-- Using the `scoped` attribute -->
 <style scoped>
 .button {
   border: none;
@@ -684,6 +684,42 @@ components/
 
 If a component only makes sense in the context of a single parent component, that relationship should be evident in its name. Since editors typically organize files alphabetically, this also keeps these related files next to each other.
 
+{% raw %}
+<details>
+<summary>
+  <h4>Detailed Explanation</h4>
+</summary>
+{% endraw %}
+
+You might be tempted to solve this problem by nesting child components in directories named after their parent. For example:
+
+```
+components/
+|- TodoList/
+   |- Item/
+      |- index.vue
+      |- Button.vue
+   |- index.vue
+```
+
+or:
+
+```
+components/
+|- TodoList/
+   |- Item/
+      |- Button.vue
+   |- Item.vue
+|- TodoList.vue
+```
+
+This isn't recommended, as it results in:
+
+- Many files with similar names, making rapid file switching in code editors more difficult.
+- Many nested sub-directories, which increases the time it takes to browse components in an editor's sidebar.
+
+{% raw %}</details>{% endraw %}
+
 {% raw %}<div class="style-example example-bad">{% endraw %}
 #### Bad
 
@@ -847,7 +883,7 @@ Unfortunately, HTML doesn't allow custom elements to be self-closing - only [off
 
 ### Component name casing in templates <sup data-p="b">strongly recommended</sup>
 
-**Component names should always be PascalCase in [single-file components](../guide/single-file-components.html) and string templates - but kebab-case in DOM templates.**
+**In most projects, component names should always be PascalCase in [single-file components](../guide/single-file-components.html) and string templates - but kebab-case in DOM templates.**
 
 PascalCase has a few advantages over kebab-case:
 
@@ -857,6 +893,8 @@ PascalCase has a few advantages over kebab-case:
 
 Unfortunately, due to HTML's case insensitivity, DOM templates must still use kebab-case.
 
+Also note that if you've already invested heavily in kebab-case, consistency with HTML conventions and being able to use the same casing across all your projects may be more important than the advantages listed above. In those cases, **using kebab-case everywhere is also acceptable.**
+
 {% raw %}<div class="style-example example-bad">{% endraw %}
 #### Bad
 
@@ -865,11 +903,6 @@ Unfortunately, due to HTML's case insensitivity, DOM templates must still use ke
 <mycomponent/>
 ```
 
-``` html
-<!-- In single-file components and string templates -->
-<my-component/>
-```
-
 ``` html
 <!-- In single-file components and string templates -->
 <myComponent/>
@@ -893,6 +926,13 @@ Unfortunately, due to HTML's case insensitivity, DOM templates must still use ke
 <!-- In DOM templates -->
 <my-component></my-component>
 ```
+
+OR
+
+``` html
+<!-- Everywhere -->
+<my-component></my-component>
+```
 {% raw %}</div>{% endraw %}
 
 
@@ -913,7 +953,8 @@ In JavaScript, PascalCase is the convention for classes and prototype constructo
 However, for applications that use **only** global component definitions via `Vue.component`, we recommend kebab-case instead. The reasons are:
 
 - It's rare that global components are ever referenced in JavaScript, so following a convention for JavaScript makes less sense.
-- These applications always include many in-DOM components, where kebab-case [**must** be used](#Component-name-casing-in-templates).
+- These applications always include many in-DOM templates, where [kebab-case **must** be used](#Component-name-casing-in-templates-strongly-recommended).
+
 {% raw %}</details>{% endraw %}
 
 {% raw %}<div class="style-example example-bad">{% endraw %}
@@ -1076,7 +1117,7 @@ In JavaScript, splitting objects with multiple properties over multiple lines is
 
 
 
-### Complex expressions in templates <sup data-p="b">strongly recommended</sup>
+### Simple expressions in templates <sup data-p="b">strongly recommended</sup>
 
 **Component templates should only include simple expressions, with more complex expressions refactored into computed properties or methods.**
 
@@ -1116,7 +1157,7 @@ computed: {
 
 
 
-### Complex computed properties <sup data-p="b">strongly recommended</sup>
+### Simple computed properties <sup data-p="b">strongly recommended</sup>
 
 **Complex computed properties should be split into as many simpler properties as possible.**
 
@@ -1589,7 +1630,7 @@ button {
 
 
 
-### Parent-child communication <sup data-p="d">use with caution</sup>
+### Implicit parent-child communication <sup data-p="d">use with caution</sup>
 
 **Props and events should be preferred for parent-child component communication, instead of `this.$parent` or mutating props.**
 
@@ -1682,7 +1723,7 @@ Vue.component('TodoItem', {
 
 
 
-### Global state management <sup data-p="d">use with caution</sup>
+### Non-flux state management <sup data-p="d">use with caution</sup>
 
 **[Vuex](https://github.com/vuejs/vuex) should be preferred for global state management, instead of `this.$root` or a global event bus.**
 

themes/vue/layout/partials/ecosystem_dropdown.ejs

@@ -1,25 +1,32 @@
 <li class="nav-dropdown-container ecosystem">
   <a class="nav-link">Hệ sinh thái</a><span class="arrow"></span>
   <ul class="nav-dropdown">
-    <li><a href="https://github.com/vuejs/roadmap" class="nav-link" target="_blank">Lộ trình phát triển</a></li>
     <li><h4>Hỗ trợ</h4></li>
     <li><ul>
       <li><a href="https://forum.vuejs.org/" class="nav-link" target="_blank">Diễn đàn</a></li>
       <li><a href="https://chat.vuejs.org/" class="nav-link" target="_blank">Chat</a></li>
-      <li><a href="https://github.com/vuejs-templates" class="nav-link" target="_blank">Templates</a></li>
+    </ul></li>
+    <li><h4>Công cụ</h4></li>
+    <li>
+      <ul>
+        <li><a href="https://github.com/vuejs/vue-devtools" class="nav-link" target="_blank">Vue Devtools</a></li>
+        <li><a href="https://vuejs-templates.github.io/webpack" class="nav-link" target="_blank">Webpack Template</a></li>
+        <li><a href="https://vue-loader.vuejs.org" class="nav-link" target="_blank">Vue Loader</a></li>
+      </ul>
+    </li>
+    <li><h4>Thư viện chính thức</h4></li>
+    <li><ul>
+      <li><a href="https://router.vuejs.org/" class="nav-link" target="_blank">Vue Router</a></li>
+      <li><a href="https://vuex.vuejs.org/" class="nav-link" target="_blank">Vuex</a></li>
+      <li><a href="https://ssr.vuejs.org/" class="nav-link" target="_blank">Vue Server Renderer</a></li>
     </ul></li>
     <li><h4>Tin tức</h4></li>
     <li><ul>
+      <li><a href="https://github.com/vuejs/roadmap" class="nav-link" target="_blank">Lộ trình phát triển</a></li>
       <li><a href="https://twitter.com/vuejs" class="nav-link" target="_blank">Twitter</a></li>
       <li><a href="https://medium.com/the-vue-point" class="nav-link" target="_blank">Blog</a></li>
       <li><a href="https://vuejobs.com/?ref=vuejs" class="nav-link" target="_blank">Việc làm</a></li>
     </ul></li>
-    <li><h4>Plugin chính thức</h4></li>
-    <li><ul>
-      <li><a href="https://router.vuejs.org/" class="nav-link" target="_blank">Vue Router</a></li>
-      <li><a href="https://vuex.vuejs.org/" class="nav-link" target="_blank">Vuex</a></li>
-      <li><a href="https://ssr.vuejs.org/" class="nav-link" target="_blank">Vue Server Renderer</a></li>
-    </ul></li>
     <li><h4>Tài nguyên</h4></li>
     <li><ul>
       <li><a href="https://github.com/vuejs" class="nav-link" target="_blank">Nhóm Vue.js trên GitHub</a></li>
@@ -28,5 +35,3 @@
     </ul></li>
   </ul>
 </li>
-
-

themes/vue/source/css/_style-guide.styl

@@ -36,6 +36,11 @@ $style-guide-priority-d-color = white
     background-color #eee
   details
     position relative
+    &:not([open]) summary
+      &::after
+        content "..."
+      &:hover
+        background rgba(255, 255, 255, .3)
   summary
     cursor pointer
     padding 1.6em

themes/vue/source/css/page.styl

@@ -185,7 +185,7 @@
   .content.with-sidebar
     margin-left: 290px
   #ad
-    z-index: 7
+    z-index: 1
     position: relative
     padding: 0
     bottom: 0