Release v2.0.0

.npmignore

@@ -1,5 +1,6 @@
+.DS_Store
 *.log
 .git
 node_modules
-docs
+doc
 examples

README.md

@@ -1,12 +1,12 @@
-# Vue2 Datatable
+# vue2-datatable-component
 
 [![npm version][npm-v-img]][npm-url]
 [![npm download][npm-dl-img]][npm-url]
 
-> The Best Datatable for Vue.js 2.x which never sucks  
+> The best Datatable for Vue.js 2.x which never sucks  
 > `npm i -S vue2-datatable-component`
 
-[Documentation](https://OneWayTech.github.io/vue2-datatable/docs/_book) | 
+[Documentation](https://OneWayTech.github.io/vue2-datatable/doc) | 
 [Online examples](https://OneWayTech.github.io/vue2-datatable/examples/dist)
 
 [npm-url]: https://www.npmjs.com/package/vue2-datatable-component

doc/README.md

@@ -0,0 +1,4 @@
+> Choose a language · 请选择语言
+
+  - [English](en/)
+  - [中文](zh-cn/)

doc/_coverpage.md

@@ -0,0 +1,6 @@
+# vue2-datatable-component
+
+> The best Datatable for Vue.js 2.x which never sucks
+
+[GitHub](https://github.com/OneWayTech/vue2-datatable)
+[Online examples](https://onewaytech.github.io/vue2-datatable/examples/dist)

doc/_sidebar.md

@@ -0,0 +1,3 @@
+- Languages · 语言
+  - [English](en/)
+  - [中文](zh-cn/)

doc/en/README.md

@@ -0,0 +1,20 @@
+# § Summary
+
+> This Datatable is only for Vue 2.x.  
+> But you can downgrade it according to [Migration from Vue 1.x](https://vuejs.org/v2/guide/migration.html).  
+> (In most of the time, you just have to replace `ref / key / <hooks>`)
+
+There are plenty of open-source Datatables, but none of them could meet all the scenarios.  
+(if there is, this project has no meanings at all)
+
+This documentation is dedicated to letting you comprehend the design and the source code.  
+Under this premise, you could build the most suitable Datatable for your own scenario.
+
+The dependencies of this project are shown as below:
+
+* BootStrap 3.x + Font Awesome 4.x（must available globally）
+* [lodash.orderBy](https://lodash.com/docs/4.17.4#orderBy)
+* [replace-with](https://github.com/kenberkeley/replace-with)
+
+P.S. *BootStrap* and *Font Awesome* can be replaced with other popular libraries.  
+(It seems to me that you just have to replace some classes / styles)

doc/en/_sidebar.md

@@ -0,0 +1,15 @@
+- [Summary](en/README)
+- [Preparation](en/preparation)
+- [Getting started](en/getting-started)
+- [Details (click me)](en/details/README)
+  - [`props` of Datatable](en/details/datatable-props)
+  - [`:columns`](en/details/props-columns)
+  - [`:data`](en/details/props-data)
+  - [`:query`](en/details/props-query)
+  - [`:selection`](en/details/props-selection)
+  - [`:xprops`](en/details/props-xprops)
+  - [Dynamic Components](en/details/dynamic-comps)
+- [I18N](en/i18n)
+- [DIY](en/DIY)
+- [Q & A (issues)](https://github.com/OneWayTech/vue2-datatable/issues)
+- [Changelog (releases)](https://github.com/OneWayTech/vue2-datatable/releases)

doc/en/details/README.md

@@ -0,0 +1,32 @@
+# § Details
+
+It would be better for you to understand the structure of this Datatable before the details.
+
+The source tree [`lib/`](https://github.com/OneWayTech/vue2-datatable/tree/master/lib) is shown as below:
+
+```
+lib/
+ ├─ HeaderSettings/
+ │   ├─ ColumnGroup.vue
+ │   └─ index.vue
+ ├── MainTable
+ │   ├─ _SCROLLBAR_WIDTH.js
+ │   ├─ _syncScroll.js
+ │   ├─ HeadSort.vue
+ │   ├─ index.vue
+ │   ├─ MultiSelect.vue
+ │   ├─ TableBody.vue
+ │   ├─ TableFooter.vue
+ │   ├─ TableFrame.vue
+ │   └─ TableHeader.vue
+ ├─ index.vue
+ ├─ LimitSelect.vue
+ ├─ Pagination.vue
+ └─ props.mixin.js
+```
+
+Here is the illustration for the tree above, which is captured from the advanced example (source: [`examples/src/Advanced/index.vue`](https://github.com/OneWayTech/vue2-datatable/blob/master/examples/src/Advanced/index.vue), demo: [examples#advanced](https://OneWayTech.github.io/vue2-datatable/examples/dist#advanced)):
+
+<a href="_images/structure.png" target="_blank" title="Click to enlarge">
+  <img src="_images/structure.png" alt="Structure">
+</a>

doc/en/details/datatable-props.md

@@ -0,0 +1,33 @@
+# § `props` of Datatable
+
+> Source: [`lib/props.mixin.js`](https://github.com/OneWayTech/vue2-datatable/blob/master/lib/props.mixin.js)
+
+| prop | Desc | Type | Optional values | Default value | Required |
+|---|---|---|---|---|---|
+| columns | Defination of columns | Array | - | - | Y |
+| data | Data of the current page (rows) | Array | - | - | Y |
+| total | Total number of the records | Number | - | - | Y |
+| query | Query object | Object | - | - | Y |
+| selection | Container for multi-select | Array | - | - | N |
+| summary | Summary row | Object | - | - | N |
+| xprops | Carrier for extra props passed to dynamic components | Object | - | - | N |
+| HeaderSettings | Whether to render `HeaderSettings` | Boolean | true / false | true | N |
+| Pagination | Whether to render pagination relevant | Boolean | true / false | true | N |
+| tbl-class | Classes for `<table>` | String / Object / Array | - | - | N |
+| tbl-style | Inline styles for `<table>` | String / Object / Array | - | - | N |
+| fixHeaderAndSetBodyHeight | (Just as its name implies) | Number | - | - | N |
+| support-backup | Whether to enable backup of `HeaderSettings` | Boolean | true / false | false | N |
+| support-nested | Whether to enable `nested components` feature (`accordion` mode is available) | Boolean / String | true / false / 'accordion' | false | N |
+
+> The advanced example (source: [`examples/src/Advanced/index.vue`](https://github.com/OneWayTech/vue2-datatable/blob/master/examples/src/Advanced/index.vue), demo: [examples#advanced](https://OneWayTech.github.io/vue2-datatable/examples/dist#advanced))  
+> almost covers all the usages, which is highly recommended to study and imitate.
+
+In the following sections, these props would be elaborated:  
+
+* `columns`
+* `data`
+* `query`
+* `selection`
+* `summary`
+* `xprops`
+* Dynamic components（`thComp / tdComp / nested component`）

docs/_book/en/detailed/dynamic-comps.md → doc/en/details/dynamic-comps.md

@@ -1,43 +1,46 @@
 # § Dynamic Components（`thComp / tdComp / nested component`）
 
-> The following code is excerpted from the source [`lib/index.vue`](https://github.com/OneWayTech/vue2-datatable/blob/master/lib/index.vue)
-
 ## ⊙ `thComp`
 
+> Source: [`lib/MainTable/TableHeader.vue`](https://github.com/OneWayTech/vue2-datatable/blob/master/lib/MainTable/TableHeader.vue)
+
 ```html
-<!-- table head component (thComp) -->
-<component v-if="column.thComp"
-  :is="comp[column.thComp]"
-  :column="column"
-  :field="column.field"
-  :title="column.title"
+<!-- <th> component (thComp) -->
+<component
+  v-if="col.thComp"
+  :is="comp[col.thComp]"
+  :column="col"
+  :field="col.field"
+  :title="col.title"
   v-bind="$props">
 </component>
 ```
 
 | prop | Desc | Type |
-|-----------|------------------------|--------------------|
+|---|---|---|
 | column | Defination of column | Object |
 | field | Field name | String / undefined |
 | title | Displayed title | String / undefined |
 | `...$props` | all the `props` from Datatable | (Spread) |
 
 ## ⊙ `tdComp`
 
+> Source: [`lib/MainTable/TableBody.vue`](https://github.com/OneWayTech/vue2-datatable/blob/master/lib/MainTable/TableBody.vue)
+
 ```html
-<!-- table body component (tdComp) -->
-<component v-if="column.tdComp"
-  :is="comp[column.tdComp]"
-  :row="item"
-  :field="column.field"
-  :value="item[column.field]"
-  :nested="item.__nested__"
+<!-- <td> component (tdComp) -->
+<component
+  v-if="col.tdComp"
+  :is="comp[col.tdComp]"
+  :row="summary"
+  :field="col.field"
+  :value="summary[col.field]"
   v-bind="$props">
 </component>
 ```
 
 | prop | Desc | Type |
-|-----------|------------------------|--------------------|
+|---|---|---|
 | row | Current row | Object |
 | field | Field name | String / undefined |
 | value | Value | Any |
@@ -46,6 +49,8 @@
 
 ## ⊙ `nested component`
 
+> Source: [`lib/MainTable/TableBody.vue`](https://github.com/OneWayTech/vue2-datatable/blob/master/lib/MainTable/TableBody.vue)
+
 ```html
 <!-- nested component -->
 <component
@@ -57,7 +62,7 @@
 ```
 
 | prop | Desc | Type |
-|-----------|------------------------|--------------------|
+|---|---|---|
 | row | Current row | Object |
 | nested | Controller of the related nested component（reference to `row.__nested__`） | Object / undefined |
 | `...$props` | all the `props` from Datatable | (Spread) |

doc/en/details/props-columns.md

@@ -0,0 +1,22 @@
+# `:columns`
+
+These are the properties of `columns[i]`:
+
+| Attr | Desc | Type | Optional values | Default value | Required |
+|---|---|---|---|---|---|
+| title | Displayed title | String | - | - | N |
+| label | Label in `HeaderSettings` (`title` will take its place if not set) | String | - | - | N |
+| field | Field name of the row | String | - | - | N |
+| explain | Explanation of the field (tooltip) | String | - | - | N |
+| sortable | Is sortable | Boolean | true / false | false | N |
+| visible | Is visible | Boolean / String (if the type is String, the visibility is not allowed to toggle) | true / false / 'true' / 'false' | true | N |
+| fixed | Is fixed | Boolean / String | true / false / 'left' / 'right' | - | N |
+| group | Group name | String | - | - | N |
+| colClass | Classes for the whole column | String / Object | - | - | N |
+| colStyle | Inline styles for the whole column | Object | - | - | N |
+| thClass | Classes for `<th>` | String | - | - | N |
+| thStyle | Inline styles for `<th>` | Object | - | - | N |
+| thComp | Name of dynamic component for `<th>` | String | - | - | N |
+| tdClass | Classes for `<td>` | String | - | - | N |
+| tdStyle | Inline styles for `<td>` | Object | - | - | N |
+| tdComp | Name of dynamic component for `<td>` | String | - | - | N |

doc/en/details/props-data.md

@@ -0,0 +1,91 @@
+# `:data`
+
+> In a more semantic way, it should be named `rows`.  
+> However, most of the popular Datatables prefer `data`, which should be complied with.
+
+Normally, it's not necessary to talk about this prop (it's too simple).  
+But this Datatable supports `nested components` feature by performing magic on it.
+
+It would be more direct to excerpt `watch:data` from the source code ([`lib/index.vue`](https://github.com/OneWayTech/vue2-datatable/blob/master/lib/index.vue)) to see how it works:
+
+```js
+watch: {
+  data: {
+    handler (data) {
+      const { supportNested } = this
+      // support nested components feature with extra magic
+      if (supportNested) {
+        data.forEach(item => {
+          if (!item.__nested__) {
+            this.$set(item, '__nested__', {
+              comp: '', // name of the current nested component
+              visible: false,
+              $toggle (comp, visible) {
+                switch (arguments.length) {
+                  case 0:
+                    this.visible = !this.visible
+                    break
+                  case 1:
+                    switch (typeof comp) {
+                      case 'boolean':
+                        this.visible = comp
+                        break
+                      case 'string':
+                        this.comp = comp
+                        this.visible = !this.visible
+                        break
+                    }
+                    break
+                  case 2:
+                    this.comp = comp
+                    this.visible = visible
+                    break
+                }
+              }
+            })
+            // omit the implementation of accordion...
+            Object.defineProperty(item, '__nested__', { enumerable: false })
+          }
+        })
+      }
+    },
+    immediate: true
+  }
+}
+```
+
+According to the above, an **unenumerable** property `__nested__`  is `$set` in every item (row) of data (rows), which includes three properties:
+
+| Attr | Desc | Type | Optional values / usages | Default value |
+|---|---|---|---|---|
+| comp | Name of the current nested component | String | - | '' |
+| visible | Is the nested component visible | Boolean | true / false | false |
+| $toggle | A convenient API to control `comp` and `visible` | Function | `$toggle(comp)` / `$toggle(visible)` / `$toggle(comp, visible)` | - |
+
+In the source template, `__nested__` would be passed to the related `tdComp` and `nested components`:
+
+```html
+<!-- <td> component (tdComp) -->
+<component
+  v-if="col.tdComp"
+  :is="comp[col.tdComp]"
+  :row="item"
+  :field="col.field"
+  :value="item[col.field]"
+  :nested="item.__nested__"
+  v-bind="$props">
+</component>
+
+<!-- nested component -->
+<component
+  :is="comp[item.__nested__.comp]"
+  :row="item"
+  :nested="item.__nested__"
+  v-bind="$props">
+</component>
+```
+
+By doing all these, we can control the `nested component` by `props.nested.$toggle` within the corresponding dynamic components.  
+(Of cource, you can manipulate `props.row.__nested__` directly, which is the same thing but more verbose)
+
+> In the advanced example, component [`Opt`](https://github.com/OneWayTech/vue2-datatable/blob/master/examples/src/Advanced/comps/td-Opt.vue) makes a full use of `props.nested`, which is highly recommended to study and imitate.