mirror of
https://github.com/tenrok/vue-select.git
synced 2026-06-16 09:10:33 +03:00
docs: first pass at auto-generating API docs for props
This commit is contained in:
Jeff
@@ -1,13 +1,173 @@
|
||||
<template>
|
||||
$END$
|
||||
<div>
|
||||
<h1>Vue Select Props</h1>
|
||||
|
||||
<div class="search-box">
|
||||
<input id="props-search" type="search" v-model="query" placeholder="Search for props...">
|
||||
</div>
|
||||
|
||||
<ul>
|
||||
<li v-for="prop in filtered">
|
||||
<h2 :id="prop.name">
|
||||
<a :href="`#${prop.name}`" aria-hidden="true" class="header-anchor">#</a>
|
||||
{{ prop.name }}
|
||||
|
||||
<small><code>{{ prop.type }}</code></small>
|
||||
|
||||
<template v-if="prop.since.hasOwnProperty('version')">
|
||||
<a :href="prop.since.link">
|
||||
<Badge :text="`+${prop.since.version}`" />
|
||||
</a>
|
||||
</template>
|
||||
</h2>
|
||||
|
||||
<div v-html="markdown(prop.description)"></div>
|
||||
|
||||
<ul v-if="prop.see">
|
||||
<li v-for="see in prop.see"><a :href="see">{{ see }}</a></li>
|
||||
</ul>
|
||||
|
||||
<pre><code v-html="prop.defaultRendered"></code></pre>
|
||||
|
||||
<Content :slot-key="prop.name"></Content>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</template>
|
||||
|
||||
<script>
|
||||
import documentation from '@dynamic/api'
|
||||
import { highlight, languages } from 'prismjs';
|
||||
import Markdown from 'markdown-it';
|
||||
|
||||
const md = new Markdown();
|
||||
|
||||
export default {
|
||||
name: "ApiDocs"
|
||||
name: "ApiDocs",
|
||||
methods: {
|
||||
markdown: snippet => md.render(snippet),
|
||||
highlight: snippet => highlight(snippet, languages.javascript, 'javascript'),
|
||||
/**
|
||||
* @param tag
|
||||
* @return {Object}
|
||||
*/
|
||||
formatTag (tag, type) {
|
||||
let rendered = `@${tag.title}`;
|
||||
if (tag.hasOwnProperty('type')) {
|
||||
rendered += ' {' + tag.type.name + '}'
|
||||
}
|
||||
if (tag.hasOwnProperty('name')) {
|
||||
rendered += ` ${tag.name} `
|
||||
}
|
||||
if (tag.hasOwnProperty('description')) {
|
||||
rendered += ` ${tag.description}`
|
||||
}
|
||||
return rendered;
|
||||
},
|
||||
getSince (tags) {
|
||||
const since = {};
|
||||
if (tags.hasOwnProperty('since')) {
|
||||
since.version = tags.since[0].description;
|
||||
since.link = `https://github.com/sagalbot/vue-select/releases/tag/v${tags.since[0].description}`
|
||||
}
|
||||
return since;
|
||||
},
|
||||
getSee (tags) {
|
||||
const since = [];
|
||||
if (tags.hasOwnProperty('see')) {
|
||||
tags.see.forEach(({description}) => since.push(description));
|
||||
}
|
||||
return since;
|
||||
},
|
||||
getParams (tags) {
|
||||
const params = [];
|
||||
if (tags.hasOwnProperty('params')) {
|
||||
tags.params.forEach((tag) => params.push(this.formatTag(tag)));
|
||||
}
|
||||
return params;
|
||||
},
|
||||
getType (prop) {
|
||||
if (prop.hasOwnProperty('type')) {
|
||||
let type = prop.type.name;
|
||||
if (type === 'func') {
|
||||
type = 'function';
|
||||
}
|
||||
return type.charAt(0).toUpperCase() + type.slice(1)
|
||||
}
|
||||
return 'mixed';
|
||||
},
|
||||
getDefaultVal (prop, params) {
|
||||
let declaration = '';
|
||||
let returnDeclaration = '';
|
||||
|
||||
if (prop.tags.hasOwnProperty('return')) {
|
||||
console.log(prop.tags);
|
||||
returnDeclaration = prop.tags.return[0];
|
||||
}
|
||||
|
||||
if (params.length || returnDeclaration.length) {
|
||||
declaration += '/*\n';
|
||||
params.forEach(param => declaration += ' * ' + param + '\n');
|
||||
declaration += ` * @return ${returnDeclaration}\n`;
|
||||
declaration += ' */ \n';
|
||||
}
|
||||
|
||||
if (prop.hasOwnProperty('defaultValue')) {
|
||||
declaration += 'default: ' + prop.defaultValue.value;
|
||||
}
|
||||
|
||||
return this.highlight(declaration);
|
||||
}
|
||||
},
|
||||
data () {
|
||||
return {
|
||||
query: ''
|
||||
}
|
||||
},
|
||||
computed: {
|
||||
filtered () {
|
||||
return this.props.filter(prop => this.query.length ? prop.name.includes(this.query) : true);
|
||||
},
|
||||
props () {
|
||||
return documentation.props.map(prop => {
|
||||
const since = this.getSince(prop.tags);
|
||||
const see = this.getSee(prop.tags);
|
||||
const params = this.getParams(prop.tags);
|
||||
const type = this.getType(prop);
|
||||
const defaultRendered = this.getDefaultVal(prop, params);
|
||||
|
||||
return {
|
||||
...prop,
|
||||
since,
|
||||
see,
|
||||
params,
|
||||
type,
|
||||
defaultRendered
|
||||
}
|
||||
}).sort((a, b) => a.name > b.name);
|
||||
},
|
||||
},
|
||||
}
|
||||
</script>
|
||||
|
||||
<style scoped>
|
||||
h2 {
|
||||
margin-top: -3.1rem;
|
||||
padding-top: 4.6rem;
|
||||
margin-bottom: 0;
|
||||
}
|
||||
|
||||
ul {
|
||||
list-style: none;
|
||||
padding: 0;
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
.search-box {
|
||||
width: 100%;
|
||||
}
|
||||
|
||||
.search-box [type=search] {
|
||||
width: 100%;
|
||||
}
|
||||
</style>
|
||||
|
||||
+1
-391
@@ -1,391 +1 @@
|
||||
## value
|
||||
|
||||
Contains the currently selected value. Very similar to a
|
||||
`value` attribute on an `<input>`. You can listen for changes
|
||||
using 'change' event using v-on.
|
||||
|
||||
```js
|
||||
value: {
|
||||
default: null
|
||||
},
|
||||
```
|
||||
|
||||
## options
|
||||
|
||||
An array of strings or objects to be used as dropdown choices.
|
||||
If you are using an array of objects, vue-select will look for
|
||||
a `label` key (ex. `[{label: 'Canada', value: 'CA'}]`). A
|
||||
custom label key can be set with the `label` prop.
|
||||
|
||||
```js
|
||||
options: {
|
||||
type: Array,
|
||||
default() {
|
||||
return [];
|
||||
}
|
||||
},
|
||||
```
|
||||
|
||||
## disabled
|
||||
|
||||
Disable the entire component.
|
||||
|
||||
```js
|
||||
disabled: {
|
||||
type: Boolean,
|
||||
default: false
|
||||
},
|
||||
```
|
||||
|
||||
## clearable
|
||||
|
||||
Can the user clear the selected property?
|
||||
|
||||
```js
|
||||
clearable: {
|
||||
type: Boolean,
|
||||
default: true
|
||||
},
|
||||
```
|
||||
|
||||
## maxHeight
|
||||
|
||||
::: warning Deprecated in `v2.x` & Removed in `v3.0`
|
||||
This prop was removed in `v3.0`. You can use the `$vs-dropdown-max-height`
|
||||
SCSS variable to adjust this setting in `v3.x`.
|
||||
:::
|
||||
|
||||
Sets the max-height property on the dropdown list.
|
||||
|
||||
```js
|
||||
maxHeight: {
|
||||
type: String,
|
||||
default: "400px"
|
||||
},
|
||||
```
|
||||
|
||||
## searchable
|
||||
|
||||
Enable/disable filtering the options.
|
||||
|
||||
```js
|
||||
searchable: {
|
||||
type: Boolean,
|
||||
default: true
|
||||
},
|
||||
```
|
||||
|
||||
## multiple
|
||||
|
||||
Equivalent to the `multiple` attribute on a `<select>` input.
|
||||
|
||||
```js
|
||||
multiple: {
|
||||
type: Boolean,
|
||||
default: false
|
||||
},
|
||||
```
|
||||
|
||||
## placeholder
|
||||
|
||||
Equivalent to the `placeholder` attribute on an `<input>`.
|
||||
|
||||
```js
|
||||
placeholder: {
|
||||
type: String,
|
||||
default: ""
|
||||
},
|
||||
```
|
||||
|
||||
## transition
|
||||
|
||||
Sets a Vue transition property on the `.dropdown-menu`. vue-select
|
||||
does not include CSS for transitions, you'll need to add them yourself.
|
||||
|
||||
```js
|
||||
transition: {
|
||||
type: String,
|
||||
default: "fade"
|
||||
},
|
||||
```
|
||||
|
||||
## clearSearchOnSelect
|
||||
|
||||
Enables/disables clearing the search text when an option is selected.
|
||||
|
||||
```js
|
||||
clearSearchOnSelect: {
|
||||
type: Boolean,
|
||||
default: true
|
||||
},
|
||||
```
|
||||
|
||||
## closeOnSelect
|
||||
|
||||
Close a dropdown when an option is chosen. Set to false to keep the dropdown
|
||||
open (useful when combined with multi-select, for example)
|
||||
|
||||
```js
|
||||
closeOnSelect: {
|
||||
type: Boolean,
|
||||
default: true
|
||||
},
|
||||
```
|
||||
|
||||
## label
|
||||
|
||||
Tells vue-select what key to use when generating option
|
||||
labels when each `option` is an object.
|
||||
|
||||
```js
|
||||
label: {
|
||||
type: String,
|
||||
default: "label"
|
||||
},
|
||||
```
|
||||
|
||||
## reduce
|
||||
|
||||
When working with objects, the reduce
|
||||
prop allows you to transform a given
|
||||
object to only the information you
|
||||
want passed to a v-model binding
|
||||
or @input event.
|
||||
|
||||
```js
|
||||
reduce: {
|
||||
type: Function,
|
||||
default: option => option,
|
||||
},
|
||||
```
|
||||
|
||||
## getOptionLabel
|
||||
|
||||
Callback to generate the label text. If `{option}`
|
||||
is an object, returns `option[this.label]` by default.
|
||||
|
||||
Label text is used for filtering comparison and
|
||||
displaying. If you only need to adjust the
|
||||
display, you should use the `option` and
|
||||
`selected-option` slots.
|
||||
|
||||
```js
|
||||
getOptionLabel: {
|
||||
type: Function,
|
||||
default(option) {
|
||||
if (typeof option === 'object') {
|
||||
if (!option.hasOwnProperty(this.label)) {
|
||||
return console.warn(
|
||||
`[vue-select warn]: Label key "option.${this.label}" does not` +
|
||||
` exist in options object ${JSON.stringify(option)}.\n` +
|
||||
'https://vue-select.org/api/props.html#getoptionlabel'
|
||||
)
|
||||
}
|
||||
return option[this.label]
|
||||
}
|
||||
return option;
|
||||
}
|
||||
},
|
||||
```
|
||||
|
||||
## getOptionKey
|
||||
|
||||
Callback to get an option key. If `option`
|
||||
is an object and has an `id`, returns `option.id`
|
||||
by default, otherwise tries to serialize `option`
|
||||
to JSON.
|
||||
|
||||
The key must be unique for an option.
|
||||
|
||||
```js
|
||||
getOptionKey: {
|
||||
type: Function,
|
||||
default(option) {
|
||||
if (typeof option === 'object' && option.id) {
|
||||
return option.id
|
||||
} else {
|
||||
try {
|
||||
return JSON.stringify(option)
|
||||
} catch(e) {
|
||||
return console.warn(
|
||||
`[vue-select warn]: Could not stringify option ` +
|
||||
`to generate unique key. Please provide 'getOptionKey' prop ` +
|
||||
`to return a unique key for each option.\n` +
|
||||
'https://vue-select.org/api/props.html#getoptionkey'
|
||||
)
|
||||
return null
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
```
|
||||
|
||||
## onTab
|
||||
|
||||
Select the current value if `selectOnTab` is enabled
|
||||
|
||||
```js
|
||||
onTab: {
|
||||
type: Function,
|
||||
default: function() {
|
||||
if (this.selectOnTab) {
|
||||
this.typeAheadSelect();
|
||||
}
|
||||
}
|
||||
},
|
||||
```
|
||||
|
||||
## taggable
|
||||
|
||||
Enable/disable creating options from searchInput.
|
||||
|
||||
```js
|
||||
taggable: {
|
||||
type: Boolean,
|
||||
default: false
|
||||
},
|
||||
```
|
||||
|
||||
## tabindex
|
||||
|
||||
Set the tabindex for the input field.
|
||||
|
||||
```js
|
||||
tabindex: {
|
||||
type: Number,
|
||||
default: null
|
||||
},
|
||||
```
|
||||
|
||||
## pushTags
|
||||
|
||||
When true, newly created tags will be added to
|
||||
the options list.
|
||||
|
||||
```js
|
||||
pushTags: {
|
||||
type: Boolean,
|
||||
default: false
|
||||
},
|
||||
```
|
||||
|
||||
## filterable
|
||||
|
||||
When true, existing options will be filtered
|
||||
by the search text. Should not be used in conjunction
|
||||
with taggable.
|
||||
|
||||
```js
|
||||
filterable: {
|
||||
type: Boolean,
|
||||
default: true
|
||||
},
|
||||
```
|
||||
|
||||
## filterBy
|
||||
|
||||
Callback to determine if the provided option should
|
||||
match the current search text. Used to determine
|
||||
if the option should be displayed.
|
||||
|
||||
```js
|
||||
filterBy: {
|
||||
type: Function,
|
||||
default(option, label, search) {
|
||||
return (label | "").toLowerCase().indexOf(search.toLowerCase()) > -1;
|
||||
}
|
||||
},
|
||||
```
|
||||
|
||||
## filter
|
||||
|
||||
Callback to filter results when search text
|
||||
is provided. Default implementation loops
|
||||
each option, and returns the result of
|
||||
this.filterBy.
|
||||
|
||||
```js
|
||||
filter: {
|
||||
type: Function,
|
||||
default(options, search) {
|
||||
return options.filter(option => {
|
||||
let label = this.getOptionLabel(option);
|
||||
if (typeof label === "number") {
|
||||
label = label.toString();
|
||||
}
|
||||
return this.filterBy(option, label, search);
|
||||
});
|
||||
}
|
||||
},
|
||||
```
|
||||
|
||||
## createOption
|
||||
|
||||
User defined function for adding Options
|
||||
|
||||
```js
|
||||
createOption: {
|
||||
type: Function,
|
||||
default(newOption) {
|
||||
if (typeof this.optionList[0] === 'object') {
|
||||
newOption = {[this.label]: newOption}
|
||||
}
|
||||
|
||||
this.$emit('option:created', newOption)
|
||||
return newOption
|
||||
}
|
||||
},
|
||||
```
|
||||
|
||||
## resetOnOptionsChange
|
||||
|
||||
When false, updating the options will not reset the select value
|
||||
|
||||
```js
|
||||
resetOnOptionsChange: {
|
||||
type: Boolean,
|
||||
default: false
|
||||
},
|
||||
```
|
||||
|
||||
## noDrop
|
||||
|
||||
Disable the dropdown entirely.
|
||||
|
||||
```js
|
||||
noDrop: {
|
||||
type: Boolean,
|
||||
default: false
|
||||
},
|
||||
```
|
||||
|
||||
## inputId
|
||||
|
||||
Sets the id of the input element.
|
||||
|
||||
```js
|
||||
inputId: {
|
||||
type: String
|
||||
},
|
||||
```
|
||||
|
||||
## dir
|
||||
|
||||
Sets RTL support. Accepts `ltr`, `rtl`, `auto`.
|
||||
|
||||
```js
|
||||
dir: {
|
||||
type: String,
|
||||
default: "auto"
|
||||
},
|
||||
```
|
||||
|
||||
## selectOnTab
|
||||
|
||||
When true, hitting the 'tab' key will select the current select value
|
||||
|
||||
```js
|
||||
selectOnTab: {
|
||||
type: Boolean,
|
||||
default: false
|
||||
}
|
||||
<ApiDocs type="props" />
|
||||
|
||||
@@ -17,7 +17,9 @@
|
||||
"cross-env": "^5.2.0",
|
||||
"fuse.js": "^3.4.4",
|
||||
"gh-pages": "^0.11.0",
|
||||
"markdown-it": "^10.0.0",
|
||||
"node-sass": "^4.12.0",
|
||||
"prismjs": "^1.17.1",
|
||||
"sass-loader": "^7.1.0",
|
||||
"vue": "^2.6.10",
|
||||
"vuepress": "^1.0.0-alpha.47",
|
||||
|
||||
+13
-2
@@ -2891,7 +2891,7 @@ entities@^1.1.1, entities@~1.1.1:
|
||||
resolved "https://registry.yarnpkg.com/entities/-/entities-1.1.2.tgz#bdfa735299664dfafd34529ed4f8522a275fea56"
|
||||
integrity sha512-f2LZMYl1Fzu7YSBKg+RoROelpOaNrcGmE9AZubeDfrCEia483oW4MI4VyFd5VNHIgQ/7qm1I0wUHK1eJnn2y2w==
|
||||
|
||||
entities@^2.0.0:
|
||||
entities@^2.0.0, entities@~2.0.0:
|
||||
version "2.0.0"
|
||||
resolved "https://registry.yarnpkg.com/entities/-/entities-2.0.0.tgz#68d6084cab1b079767540d80e56a39b423e4abf4"
|
||||
integrity sha512-D9f7V0JSRwIxlRI2mjMqufDrRDnx8p+eEOz7aUM9SuvF8gsBzra0/6tbjl1m8eQHrZlYj6PxqE00hZ1SAIKPLw==
|
||||
@@ -4701,6 +4701,17 @@ markdown-it-table-of-contents@^0.4.0:
|
||||
resolved "https://registry.yarnpkg.com/markdown-it-table-of-contents/-/markdown-it-table-of-contents-0.4.4.tgz#3dc7ce8b8fc17e5981c77cc398d1782319f37fbc"
|
||||
integrity sha512-TAIHTHPwa9+ltKvKPWulm/beozQU41Ab+FIefRaQV1NRnpzwcV9QOe6wXQS5WLivm5Q/nlo0rl6laGkMDZE7Gw==
|
||||
|
||||
markdown-it@^10.0.0:
|
||||
version "10.0.0"
|
||||
resolved "https://registry.yarnpkg.com/markdown-it/-/markdown-it-10.0.0.tgz#abfc64f141b1722d663402044e43927f1f50a8dc"
|
||||
integrity sha512-YWOP1j7UbDNz+TumYP1kpwnP0aEa711cJjrAQrzd0UXlbJfc5aAq0F/PZHjiioqDC1NKgvIMX+o+9Bk7yuM2dg==
|
||||
dependencies:
|
||||
argparse "^1.0.7"
|
||||
entities "~2.0.0"
|
||||
linkify-it "^2.0.0"
|
||||
mdurl "^1.0.1"
|
||||
uc.micro "^1.0.5"
|
||||
|
||||
markdown-it@^8.4.1:
|
||||
version "8.4.2"
|
||||
resolved "https://registry.yarnpkg.com/markdown-it/-/markdown-it-8.4.2.tgz#386f98998dc15a37722aa7722084f4020bdd9b54"
|
||||
@@ -6063,7 +6074,7 @@ pretty-time@^1.1.0:
|
||||
resolved "https://registry.yarnpkg.com/pretty-time/-/pretty-time-1.1.0.tgz#ffb7429afabb8535c346a34e41873adf3d74dd0e"
|
||||
integrity sha512-28iF6xPQrP8Oa6uxE6a1biz+lWeTOAPKggvjB8HAs6nVMKZwf5bG++632Dx614hIWgUPkgivRfG+a8uAXGTIbA==
|
||||
|
||||
prismjs@^1.13.0:
|
||||
prismjs@^1.13.0, prismjs@^1.17.1:
|
||||
version "1.17.1"
|
||||
resolved "https://registry.yarnpkg.com/prismjs/-/prismjs-1.17.1.tgz#e669fcbd4cdd873c35102881c33b14d0d68519be"
|
||||
integrity sha512-PrEDJAFdUGbOP6xK/UsfkC5ghJsPJviKgnQOoxaDbBjwc8op68Quupwt1DeAFoG8GImPhiKXAvvsH7wDSLsu1Q==
|
||||
|
||||
Reference in New Issue
Block a user