pablohpsilva / vuejs-component-style-guide Goto Github PK

Options is a riot term. In Vue it's props. Options usually refers to the component's definition options.

// methods
watch: {}.
methods: {}

My question is, watch supposed to be a watcher instead of methods.
It would be better change to

// watch and methods
watch: {},
methods: {}

As you can see below, i have a question... How correctly to name components here?

https://github.com/pablohpsilva/vuejs-component-style-guide#why-6

Again, grouping makes the component easier to read (name; extends; props, data and computed; components; watch and methods; lifecycle methods, etc.);

export default {
    // Do not forget this little guy
    name: 'RangeSlider',
    // share common functionality with component mixins
    mixins: [],
    // compose new components
    extends: {},
    // component properties/variables
    props: {
      bar: {}, // Alphabetized
      foo: {},
      fooBar: {},
    },
    // variables
    data() {},
    computed: {},
    // when component uses other components
    components: {},
    // methods
    watch: {},
    methods: {},
    // component Lifecycle hooks
    beforeCreate() {},
    mounted() {},
};

I suggest components be placed after extends and before props,
because it is intensively related to the<template> on top, and nothing else.

like: https://github.com/vuejs/vue-hackernews-2.0/blob/master/src/views/ItemList.vue

I suffer from scrolling too much, and think it is not relational(rational).
Any thoughts?
Cheers!

I developed this template https://github.com/InCuca/vue-standalone-component/ using my experience with Polymer components: paper, iron, etc. In this template I tried to create a standalone component using https://github.com/vue-styleguidist/vue-styleguidist, the next step is add karma tests for a full self-contained component strucuture.

What do you think about linking some of the community made templates in the docs (there are more in github)?

Have you considered creating a basic example application which uses all these various "rules" and "guides"

Particularly this sentence: "app- namespaced: if very generic and otherwise 1 word, so that it can easily be reused in other projects."

Very generic components should have "app" as a namespace? Or should they have your app's name as a namespace ("myapp-")? Or is it using app as a namespace because in the example it is descriptive ( app-header for the header of the app)

Couldn't very generic components be easily used elsewhere? It sounds like it's saying to app-namespace things if they're very generic and otherwise make them one word, but this sentence could be read in 2 different ways.

Am I supposed to literally add app- in front of all components that are 1 word AND generic and not to any other ones?

I'm happy to try and clarify this if I can make it make sense to myself :)

A section showing best practice application structure. I'll setup a pull request if you think its a good idea 😄

.
| ── build/ # exported app files
| |--- ...
| -- src/
| | -- app.js # app entry file
| |-- components/ # Vue components
| │ | ---- ...
| | --- assets/ # module assets (processed by webpack)
| | --- ...
| -- index.html # index.html template
--- package.json # build scripts and dependencies

谨慎使用 this.$refs标题下第一段第二排：在使用的的时候，多了一个的

Sample code in the Keep component props primitive section contains several typos:

<range-slider
  :values="[10, 20]"
  min="0" <!-- Should be :min="..." for evaluating as JS expression to Number -->
  max="100" <!-- Should be :max="..." for evaluating as JS expression to Number -->
  step="5"  <!-- Should be :step="..." for evaluating as JS expression to Number -->
  :on-slide="updateInputs"   <!-- Should be @on-slide="..." -->
  :on-end="updateResults"> <!-- Should be @on-end="..." -->
</range-slider>

See also Literal vs. Dynamic

https://github.com/pablohpsilva/vuejs-component-style-guide#how-6

I'd update this example to to follow your naming scheme name: 'RangerWrapper', just to be consistent so it's not 1 word.

Thank you for the guide, it will definitely help.

In the Why of Harness your component options states Use type conversion to cast option values to expected type. As Vue doesn't support props conversions, I must assume the conversion is expected to be done by a computed property or when used. It would be interesting to put some more words and example of best practice about it.

This question comes regularly to head for any web component interface.

We learned that a component should be self sufficient and reusable.

The problem is:

• The smaller the components, the more you get. (Your project gets flooded, harder to make components communicate)
• You build less components, the biggest they get. (Harder to maintain, less reusability)

It's always complicated to find the right balance.
I wonder if there are key points/ideas that can help bring better web component interfaces.

Imagine a page having the following specifications:

• Search field
• Filter toolbar
• Result list

Search field

I think the search field could be a component and assume that it is reusable.
Just so you get an idea of what I have in mind:

var searchField = {
  // One prop for the url to call on Field keypress.enter or search button clicked.
  props: {
    request: String
  },
  data() {
    return {
      // The input value
      searchValue: ''
    };
  },
  methods: {
    search() {
      // Request the server with `${this.request}?q=${this.searchValue}`
    }
  }
};

It could also be emitting a search event to inform the parent of any search trigger, instead of having a prop.

Filter toolbar

This component could allow sorting (date, specific data, ...) or even different layouts.
It will have to be strongly coupled to the Result list component. Since it filters the result list.

Should Filter toolbar and Result list components be as one?
Otherwise I'd be creating a component that only works properly with only one of my component library.

Result list

This is just a v-for of anything actually.
So basically it shouldn't require a component.

But note that the list could be paginated, infinite scrolled, etc.
So maybe there should be some kind of list component?
Something like:

var list = {
  props: {
    layout: String,
    validator(value) {
      return value === 'paging' || value === 'infinite' || value === 'scroll';
    },
    default: 'scroll'
  }
};

Conclusion

Note the above is just an example!
Feel free to compare the idea to any other situation.

I would like to hear about other's experience on separating components, building pages.

I hope we can find some best practices or key points on that matter.

Very good the guide.

I would like to know your opinions about /deep/ selector.

It turns out that the father needs a change in the child only in the visual. I do not know if this violates FIRST.

This feature is implemented in 12.2.0 (vue-loader) May 2017
Issue: vuejs/vue-loader#661

I like this feature because it avoids increasing the code in the child components.
For example, create a props in the child just to increase the space (margin/padding) in style inline and then one more props to change other styles. It does not sound good to me.

/deep/ selector example:

<template>
    <icon name="phone" />
</template>

<style scoped>
    .link:hover /deep/ .icon svg {
        fill: white;
    }
</style>

While reading the paragraph about avoiding this.$refs I thought it wasn't clear enough that you mean "avoid it to access subcomponents".

this.$refs can also be used to access any DOM element's native API and in this case it is pretty useful and can't be done otherwise.

Would you prefer a PR ?

Hello.

It is great to have found your style guide.

While learning Vue I found it is flexible; allowing multiple ways to accomplish the same functionality. The flexibility also presents a challenge when trying to determine which approach to take.

Your approach of using Why/How to describe a uniform set of patterns is excellent. Thank you.

Having read your explanations for the directory structure in your recent post regarding the vue-material-boilerplate, I'd like to suggest adding a version of it to this style guide.

Thanks again. I found your style guide yesterday while looking for tips on a good directory structure and then today saw your post. Both helped answer my questions.

I hope you're kiddin with this recommendation. Nowadays most IDEs got nice defaults for <script> and, hey, HTML5 went towards simplification, not exausting developers by endless useless xmlns and other stuff. For example Webstorm insists that you'll use type="text/babel" for script tag to correctly interpret ES6 (skipping defaults). But it only means that this IDE is buggy and we'll need to force their devs to fix this bug. There are many IDEs on the market, and you have a freedom to choose the right one.

Anyway, thank you for sharing this doc. Our team has internal document on component styling for Vue.js, part of it is comparable with your proposal, but definitely you have a worth things that we missed.

I also should say that it would be nice to take 1.0 into account.

I would say this section is opinionated outside of the scope of Vue components, into a field of CSS which is controversial. It advises BEM and OOCSS which are methodologies which some people choose not to subscribe to knowingly.

Also exemplifies a kind of nesting one should probably avoid for a few reasons: MyCompoennt li {}

Also advises to use both <style scoped> along with css scoping, without explaining any substantial benefit.

https://github.com/pablohpsilva/vuejs-component-style-guide#use-component-name-as-style-scope

I really appreciate the time put for creating this guide. But I do not agree too much with the order proposed for <template> before <script>.

• The exposed argument about people going to spend more time dealing with HTML seems to be a bit unconfirmmed. Particularly I had spent more time with the component logic (JavaScript) and not with the visual structure (HTML).
• Another point is that keeping <template> and <style> next each other simplifies to think about structure and style together, without having to scroll up and down all the time while writing the styles.

Anyway, I know it's just my personal opinion, but I'd like to see more people contributing with the discussion about advantages and disadvantages of each approach.

I am rising this ticket to discuss about a best practice for the below, and if results of interest add it as a style guide.

A collection of components can be registered globally or locally as required. Both would have the same output but there are different implications.

Global approach

Is easier to use, set it once and use as required. It will bloat the code, as the entire library get installed. Seem good approach for prototyping, tests, etc.

import Vue from 'vue'
import MyLibrary from 'my-library'

Vue.install(MyLibrary)

export default {
  template: '<my-lib-button></my-lib-button>'
}

Local approach

You only import what you use making it possible to take advantage of tree-shaking.

import Button from 'my-library/lib/button'

export default {
  components: { 'MyButton': Button },
  template: '<my-button></my-button>'
}

This section stipulates this:

assigning this to a variable named component the variable tells developers it's bound to the component instance wherever it's used.

The code example attached does not define any variable named component. It's confusing.

位置：Component event names
Events should either end in verbs in the infinitive form (e.g. client-api-load) or nouns (e.g drive-upload-success) (source);
事件命名应该以动词（如 client-api-load） 或是 形容词（如 drive-upload-success）结尾。
形容词 应为 名词。

如果一个组件需要访问其父组件的上下文，那么该组件将不能再其它上下文中复用。

“再”写错了。

Can you tell more about this topic? I am confused how to implement this instead of using const self = this

When using the dom as the template there are limitations and one is particullary annoying. As the browser will lowercase the entire tag, events listeners declared as @myEvent would be saved as myevent and thus ignored when the component emmits myEvent. The same happens with props names, but in my tests seems Vue does the conversion.

As best practice the events should be named always as kebab case, $emit('my-event').

#use-script-inside-component anchor is not found in this line

「 put script inside a <script> component」

this url from the description is broken
https://pablohpsilva.github.io/vuejs-component-style-guide