mirrors/vue-select
2
0
Fork 0
mirror of https://github.com/tenrok/vue-select.git synced 2026-05-17 02:29:37 +03:00
Code Activity

WIP: V3 - Remove index prop, add reduce prop (#800)

Browse Source 
* remove `index` in favour of `reduce`, tests passing

* refactor findOptionFromReducedValue

* - always use getOptionLabel in comparisons

* - refactor deselect method
- add missing jsdoc blocks
- organize methods

* bump documentation
This commit is contained in:
Jeff Sagal
2019-03-24 19:23:30 -07:00
committed by GitHub
parent e4d4b27540
commit 699d595f9a
7 changed files with 272 additions and 245 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/.vuepress/config.js
-1
View File
@@ -87,7 +87,6 @@ module.exports = {
['digging-deeper/templating', 'Templating & Slots'],
['digging-deeper/vuex', 'Vuex'],
['digging-deeper/ajax', 'AJAX'],
['digging-deeper/examples', 'Examples'],
],
},
{
docs/digging-deeper/ajax.md
+1 -1
View File
@@ -1,4 +1,4 @@
## AJAX Remote Option Loading
# AJAX Remote Option Loading
<CodePen url="POMeOX" height="400"/>
docs/getting-started/install.md
+18 -4
View File
@@ -1,6 +1,5 @@
### Vue Compatibility
- `vue ~2.0` use `vue-select ~2.0`
- `vue ~1.0` use `vue-select ~1.0`
- `vue 1.x` use `vue-select 1.x`
## Yarn / NPM
Install with yarn:
@@ -18,10 +17,23 @@ Then, import and register the component:
import Vue from 'vue'
import vSelect from 'vue-select'
// register component
Vue.component('v-select', vSelect)
```
## CDN
The component itself does not include any CSS. You'll need to include it separately:
```js
import 'vue-select/dist/vue-select.css';
```
You can also import the scss yourself for complete control of the component styles:
```scss
@import "vue-select/src/scss/vue-select.scss";
```
## In the Browser / CDN
Include `vue` & `vue-select.js` - I recommend using [unpkg.com](https://unpkg.com/#/).
@@ -31,8 +43,10 @@ Include `vue` & `vue-select.js` - I recommend using [unpkg.com](https://unpkg.co
<!-- use the latest release -->
<script src="https://unpkg.com/vue-select@latest"></script>
<link rel="stylesheet" href="https://unpkg.com/vue-select@latest/dist/vue-select.css">
<!-- or point to a specific release -->
<script src="https://unpkg.com/vue-select@1.30"></script>
<script src="https://unpkg.com/vue-select@2.6.0"></script>
<link rel="stylesheet" href="https://unpkg.com/vue-select@2.6.0/dist/vue-select.css">
```
Then register the component in your javascript:
docs/getting-started/options.md
+22 -26
View File
@@ -1,20 +1,29 @@
# Dropdown Options
`vue-select` accepts arrays of strings or objects to use as options through the `options` prop:
## Options Prop
`vue-select` accepts arrays of primitive values or objects to use as options through the `options` prop:
```html
<!-- array of strings or numbers -->
<v-select :options="['foo','bar']"></v-select>
```
When provided an array of objects, `vue-select` will display a single value of the object. By default, `vue-select` will look for a key named `label` on the object to use as display text.
```html
<!-- or, an array of objects -->
<v-select :options="[{label: 'foo', value: 'Foo'}]"></v-select>
```
## Option Labels
When the `options` array contains objects, `vue-select` looks for the `label` key to display by default. You can set your own label to match your source data using the `label` prop.
#### Option Primitives (strings, numbers)
When `options` contains strings or numbers, they'll be used as the label for the option within the
component. No further configuration is necessary.
#### Option Objects
When `options` is an array of objects, the component must generate a label to be shown as the options text. By default,
`vue-select` will attempt to render `option.label` as the option label. You can set your own label to match your
source data using the `label` prop.
For example, consider an object with `countryCode` and `countryName` properties:
@@ -33,26 +42,13 @@ If you wanted to display `Canada` in the dropdown, you'd use the `countryName` k
<CodePen url="aEjLPB" height="450"/>
## Option Object Key
When the `options` array contains objects, `vue-select` returns the whole object as dropdown value upon selection. You can specify your own `index` prop to return only the value contained in the specific property.
For example, consider an object with `value` and `label` properties:
```json
{
value: "CA",
label: "Canada"
}
```
If you wanted to return `CA` in the dropdown when `Canada` is selected, you'd use the `index` key:
```html
<v-select index="value" :options="countries"></v-select>
```
## Null / Empty Options
`vue-select` requires the `option` property to be an `array`. If you are using Vue in development mode, you will get warnings attempting to pass anything other than an `array` to the `options` prop. If you need a `null`/`empty` value, use an empty array `[]`.
## Tagging
To allow input that's not present within the options, set the `taggable` prop to true.
If you want new tags to be pushed to the options list, set `push-tags` to true.
<CodePen url="XVoWxm" height="350"/>
docs/getting-started/values.md
+63 -37
View File
@@ -1,53 +1,79 @@
# Selecting Values
## Getting / Setting
The most common use case for `vue-select` is to have the chosen value synced with a parent component. `vue-select` takes advantage of the `v-model` syntax to sync values with a parent.
### `v-model`
The most common use case for `vue-select` is to have the chosen value synced with a parent component. `vue-select`
takes advantage of the `v-model` syntax to sync values with a parent.
```html
<v-select v-model="selected"></v-select>
<v-select v-model="selected" />
```
<CodePen url="Kqxbjw" height="250"/>
### `value` prop & `input` event
If you don't require the `value` to be synced, you can also pass the prop directly:
If you don't require the `value` to be synced, but you need to preselect a value, you can use the `value` prop. It will
accept strings, numbers or objects. If you're using a `multiple` v-select, you'll want to pass an array.
```html
<v-select :value="selected"></v-select>
<v-select :value="selected" />
```
This method allows you to pre-select a value(s), without syncing any changes to the parent component. This is also very useful when using a state management tool, like Vuex.
The `value` prop is very useful when using a state management tool, like Vuex. `vue-select` will emit an `input` event
any time a value changes.
```html
<v-select :value="selected" @input="setSelected" />
```
```js
methods: {
setSelected(value) {
// do something with selected value
}
}
```
## Transforming Selections
When the `options` array contains objects, `vue-select` returns the whole object as dropdown value upon selection.
If you need to return a single key, or transform the data before it is synced, `vue-select` provides a `reduce` callback
that allows you to transform a selected option before it is passed to the `@input` event. Consider this data structure:
```js
let options = [{code: 'CA', country: 'Canada'}, ...];
```
If we want to display the `country`, but return the `code` to `v-model`, we can use the `reduce` prop to receive
only the data that's required.
```html
<v-select :options="options" :reduce="country => country.code" label="country" />
```
The `reduce` property also works well when you have a deeply nested value:
```
{
country: 'canada',
meta: {
id: '1',
code: 'ca'
}
}
```
```html
<v-select :options="options" :reduce="country => country.value.id" label="country" />
```
## Single/Multiple Selection
By default, `vue-select` supports choosing a single value. If you need multiple values, use the `multiple` prop:
By default, `vue-select` supports choosing a single value. If you need multiple values, use the `multiple` boolean prop,
much the same way you would on a native `<select>` element. When `multiple` is true, `v-model` or `value` should be
arrays.
```html
<v-select multiple v-model="selected"></v-select>
```
<CodePen url="opMGro" height="250"/>
## Tagging
To allow input that's not present within the options, set the `taggable` prop to true.
If you want new tags to be pushed to the options list, set `push-tags` to true.
<CodePen url="XVoWxm" height="350"/>
## Return a Single Key from an Object
When the `options` array contains objects, `vue-select` returns the whole object as dropdown value upon selection. You can specify your own `index` prop to return only the value contained in the specific property.
For example, consider an object with `value` and `label` properties:
```json
{
value: "CA",
label: "Canada"
}
```
If you wanted to return `CA` in the dropdown when `Canada` is selected, you'd use the `index` key:
```html
<v-select index="value" :options="countries"></v-select>
<v-select multiple v-model="selected" :options="['foo','bar']" />
```
<v-select multiple :options="['foo','bar']" />
src/components/Select.vue
+131 -110
View File
@@ -200,13 +200,15 @@
},
/**
* Tells vue-select what key to use when generating option
* values when each `option` is an object.
* @type {String}
* 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.
*/
index: {
type: String,
default: null
reduce: {
type: Function,
default: option => option,
},
/**
@@ -225,10 +227,6 @@
getOptionLabel: {
type: Function,
default(option) {
if( this.index ) {
option = this.findOptionByIndexValue(option)
}
if (typeof option === 'object') {
if (!option.hasOwnProperty(this.label)) {
return console.warn(
@@ -450,7 +448,15 @@
* attach any event listeners.
*/
created() {
this.mutableLoading = this.loading
this.mutableLoading = this.loading;
if (this.$options.propsData.hasOwnProperty('reduce') && this.value) {
if (Array.isArray(this.value)) {
this.$data._value = this.value.map(value => this.findOptionFromReducedValue(value));
} else {
this.$data._value = this.findOptionFromReducedValue(this.value);
}
}
this.$on('option:created', this.maybePushTag)
},
@@ -467,17 +473,6 @@
if (this.taggable && !this.optionExists(option)) {
option = this.createOption(option)
}
if (this.index) {
if (!option.hasOwnProperty(this.index)) {
return console.warn(
`[vue-select warn]: Index key "option.${this.index}" does not` +
` exist in options object ${JSON.stringify(option)}.`
)
}
option = option[this.index]
}
if (this.multiple) {
option = this.selectedValue.concat(option)
}
@@ -492,15 +487,10 @@
* @param {Object|String} option
* @return {void}
*/
deselect(option) {
let value = null
if (this.multiple) {
value = this.selectedValue.filter(val => {
return ! this.optionComparator(val, option)
});
}
this.updateValue(value);
deselect (option) {
this.updateValue(this.selectedValue.filter(val => {
return !this.optionComparator(val, option);
}));
},
/**
@@ -527,11 +517,28 @@
}
},
updateValue(value) {
if (typeof this.value === 'undefined') {
/**
* Accepts a selected value, updates local
* state when required, and triggers the
* input event.
*
* @emits input
* @param value
*/
updateValue (value) {
if (this.isTrackingValues) {
// Vue select has to manage value
this.$data._value = value;
}
if (value !== null) {
if (Array.isArray(value)) {
value = value.map(val => this.reduce(val));
} else {
value = this.reduce(value);
}
}
this.$emit('input', value);
},
@@ -573,7 +580,6 @@
* @returns {boolean}
*/
optionComparator(value, option) {
// This method will need to be cleaned/replaced when the `reducer` API is added
if (typeof value !== 'object' && typeof option !== 'object') {
// Comparing primitives
if (value === option) {
@@ -581,13 +587,13 @@
}
} else {
// Comparing objects
if (this.index && value === option[this.index]) {
if (value === this.reduce(option)) {
return true
}
if ((value[this.label] === option[this.label]) || (value[this.label] === option)) {
if ((this.getOptionLabel(value) === this.getOptionLabel(option)) || (this.getOptionLabel(value) === option)) {
return true
}
if (this.index && value[this.index] === option[this.index]) {
if (this.reduce(value) === this.reduce(option)) {
return true
}
}
@@ -597,19 +603,80 @@
/**
* Finds an option from this.options
* where option[this.index] matches
* where a reduced value matches
* the passed in value.
*
* @param value {Object}
* @returns {*}
*/
findOptionByIndexValue(value) {
this.options.forEach(_option => {
if (JSON.stringify(_option[this.index]) === JSON.stringify(value)) {
value = _option
findOptionFromReducedValue (value) {
return this.options.find(option => JSON.stringify(this.reduce(option)) === JSON.stringify(value)) || value;
},
/**
* 'Private' function to close the search options
* @emits {search:blur}
* @returns {void}
*/
closeSearchOptions(){
this.open = false
this.$emit('search:blur')
},
/**
* Delete the value on Delete keypress when there is no
* text in the search input, & there's tags to delete
* @return {this.value}
*/
maybeDeleteValue() {
if (!this.searchEl.value.length && this.selectedValue && this.clearable) {
let value = null;
if (this.multiple) {
value = [...this.selectedValue.slice(0, this.selectedValue.length - 1)]
}
this.updateValue(value)
}
},
/**
* Determine if an option exists
* within this.optionList array.
*
* @param {Object || String} option
* @return {boolean}
*/
optionExists(option) {
return this.optionList.some(opt => {
if (typeof opt === 'object' && this.getOptionLabel(opt) === option) {
return true
} else if (opt === option) {
return true
}
return false
})
return value
},
/**
* Ensures that options are always
* passed as objects to scoped slots.
* @param option
* @return {*}
*/
normalizeOptionForSlot (option) {
return (typeof option === 'object') ? option : {[this.label]: option};
},
/**
* If push-tags is true, push the
* given option to `this.pushedTags`.
*
* @param {Object || String} option
* @return {void}
*/
maybePushTag(option) {
if (this.pushTags) {
this.pushedTags.push(option)
}
},
/**
@@ -647,16 +714,6 @@
}
},
/**
* 'Private' function to close the search options
* @emits {search:blur}
* @returns {void}
*/
closeSearchOptions(){
this.open = false
this.$emit('search:blur')
},
/**
* Open the dropdown on focus.
* @emits {search:focus}
@@ -667,62 +724,6 @@
this.$emit('search:focus')
},
/**
* Delete the value on Delete keypress when there is no
* text in the search input, & there's tags to delete
* @return {this.value}
*/
maybeDeleteValue() {
if (!this.searchEl.value.length && this.selectedValue && this.clearable) {
let value = null;
if (this.multiple) {
value = [...this.selectedValue.slice(0, this.selectedValue.length - 1)]
}
this.updateValue(value)
}
},
/**
* Determine if an option exists
* within this.optionList array.
*
* @param {Object || String} option
* @return {boolean}
*/
optionExists(option) {
return this.optionList.some(opt => {
if (typeof opt === 'object' && opt[this.label] === option) {
return true
} else if (opt === option) {
return true
}
return false
})
},
/**
* Ensures that options are always
* passed as objects to scoped slots.
* @param option
* @return {*}
*/
normalizeOptionForSlot (option) {
return (typeof option === 'object') ? option : {[this.label]: option};
},
/**
* If push-tags is true, push the
* given option to `this.pushedTags`.
*
* @param {Object || String} option
* @return {void}
*/
maybePushTag(option) {
if (this.pushTags) {
this.pushedTags.push(option)
}
},
/**
* Event-Handler to help workaround IE11 (probably fixes 10 as well)
* firing a `blur` event when clicking
@@ -788,10 +789,23 @@
computed: {
/**
* Determine if the component needs to
* track the state of values internally.
* @return {boolean}
*/
isTrackingValues () {
return typeof this.value === 'undefined' || this.$options.propsData.hasOwnProperty('reduce');
},
/**
* The options that are currently selected.
* @return {Array}
*/
selectedValue () {
let value = this.value;
if (typeof this.value === 'undefined') {
if (this.isTrackingValues) {
// Vue select has to manage value internally
value = this.$data._value;
}
@@ -803,6 +817,13 @@
return [];
},
/**
* The options available to be chosen
* from the dropdown, including any
* tags that have been pushed.
*
* @return {Array}
*/
optionList () {
return this.options.concat(this.pushedTags);
},
tests/unit/ObjectIndex.spec.js → tests/unit/Reduce.spec.js
+37 -66
View File
@@ -1,22 +1,22 @@
import { mount, shallowMount } from "@vue/test-utils";
import VueSelect from "../../src/components/Select";
describe("When index prop is defined", () => {
describe("When reduce prop is defined", () => {
it("can accept an array of objects and pre-selected value (single)", () => {
const Select = shallowMount(VueSelect, {
propsData: {
index: "value",
reduce: option => option.value,
value: "foo",
options: [{ label: "This is Foo", value: "foo" }]
}
});
expect(Select.vm.selectedValue).toEqual(["foo"]);
expect(Select.vm.selectedValue).toEqual([{ label: "This is Foo", value: "foo" }]);
});
it("can determine if an object is pre-selected", () => {
const Select = shallowMount(VueSelect, {
propsData: {
index: "id",
reduce: option => option.id,
value: "foo",
options: [
{
@@ -35,30 +35,28 @@ describe("When index prop is defined", () => {
).toEqual(true);
});
it("can determine if an object is selected after it has been chosen", () => {
const Select = shallowMount(VueSelect, {
propsData: {
index: "id",
options: [{ id: "foo", label: "FooBar" }]
}
it('can determine if an object is selected after its been chosen', () => {
const Select = shallowMount(VueSelect, {
propsData: {
reduce: option => option.id,
options: [{id: 'foo', label: 'FooBar'}],
},
});
Select.vm.select({id: 'foo', label: 'FooBar'});
expect(Select.vm.isOptionSelected({
id: 'foo',
label: 'This is FooBar',
})).toEqual(true);
});
Select.vm.select({ id: "foo", label: "FooBar" });
expect(
Select.vm.isOptionSelected({
id: "foo",
label: "This is Foo"
})
).toEqual(true);
});
it("can accept an array of objects and pre-selected values (multiple)", () => {
const Select = shallowMount(VueSelect, {
propsData: {
multiple: true,
index: "value",
value: ["foo", "bar"],
reduce: option => option.value,
value: ["foo"],
options: [
{ label: "This is Foo", value: "foo" },
{ label: "This is Bar", value: "bar" }
@@ -66,14 +64,14 @@ describe("When index prop is defined", () => {
}
});
expect(Select.vm.selectedValue).toEqual(["foo", "bar"]);
expect(Select.vm.selectedValue).toEqual([{ label: "This is Foo", value: "foo" }]);
});
it("can deselect a pre-selected object", () => {
const Select = shallowMount(VueSelect, {
propsData: {
multiple: true,
index: "value",
reduce: option => option.value,
options: [
{ label: "This is Foo", value: "foo" },
{ label: "This is Bar", value: "bar" }
@@ -90,7 +88,7 @@ describe("When index prop is defined", () => {
it("can deselect an option when multiple is false", () => {
const Select = shallowMount(VueSelect, {
propsData: {
index: "value",
reduce: option => option.value,
options: [
{ label: "This is Foo", value: "foo" },
{ label: "This is Bar", value: "bar" }
@@ -105,7 +103,7 @@ describe("When index prop is defined", () => {
it("can use v-model syntax for a two way binding to a parent component", () => {
const Parent = mount({
data: () => ({
index: "value",
reduce: option => option.value,
value: "foo",
options: [
{ label: "This is Foo", value: "foo" },
@@ -113,13 +111,13 @@ describe("When index prop is defined", () => {
{ label: "This is Baz", value: "baz" }
]
}),
template: `<div><v-select :index="index" :options="options" v-model="value"></v-select></div>`,
template: `<div><v-select :reduce="option => option.value" :options="options" v-model="value"></v-select></div>`,
components: { "v-select": VueSelect }
});
const Select = Parent.vm.$children[0];
expect(Select.value).toEqual("foo");
expect(Select.selectedValue).toEqual(["foo"]);
expect(Select.selectedValue).toEqual([{ label: "This is Foo", value: "foo" }]);
Select.select({ label: "This is Bar", value: "bar" });
expect(Parent.vm.value).toEqual("bar");
@@ -129,52 +127,37 @@ describe("When index prop is defined", () => {
const Select = shallowMount(VueSelect, {
propsData: {
multiple: true,
index: "value",
value: ["baz"],
reduce: option => option.value,
value: ["CA"],
label: "name",
options: [{ value: "foo", name: "Foo" }, { value: "baz", name: "Baz" }]
options: [{ value: "CA", name: "Canada" }, { value: "US", name: "United States" }]
}
});
expect(Select.find(".vs__selected").text()).toContain("Baz");
});
it("will console.warn when attempting to select an option with an undefined index", () => {
const spy = jest.spyOn(console, "warn").mockImplementation(() => {});
const Select = shallowMount(VueSelect, {
propsData: {
index: "value",
options: [{ label: "Foo" }]
}
});
Select.vm.select({ label: "Foo" });
expect(spy).toHaveBeenCalledWith(
`[vue-select warn]: Index key "option.value" does not exist in options object {"label":"Foo"}.`
);
expect(Select.find(".vs__selected").text()).toContain("Canada");
});
it("can find the original option within this.options", () => {
const optionToFind = { id: 1, label: "Foo" };
const Select = shallowMount(VueSelect, {
propsData: {
index: "id",
reduce: option => option.id,
options: [optionToFind, { id: 2, label: "Bar" }]
}
});
expect(Select.vm.findOptionByIndexValue(1)).toEqual(optionToFind);
expect(Select.vm.findOptionByIndexValue(optionToFind)).toEqual(
expect(Select.vm.findOptionFromReducedValue(1)).toEqual(optionToFind);
expect(Select.vm.findOptionFromReducedValue(optionToFind)).toEqual(
optionToFind
);
});
describe("And when option[index] is a nested object", () => {
describe("And when a reduced option is a nested object", () => {
it("can determine if an object is pre-selected", () => {
const nestedOption = { value: { nested: true }, label: "foo" };
const Select = shallowMount(VueSelect, {
propsData: {
index: "value",
reduce: option => option.value,
value: {
nested: true
},
@@ -182,14 +165,14 @@ describe("When index prop is defined", () => {
}
});
expect(Select.vm.isOptionSelected({ nested: true })).toEqual(true);
expect(Select.vm.selectedValue).toEqual([nestedOption]);
});
it("can determine if an object is selected after it is chosen", () => {
const nestedOption = { value: { nested: true }, label: "foo" };
const Select = shallowMount(VueSelect, {
propsData: {
index: "value",
reduce: option => option.value,
options: [nestedOption]
}
});
@@ -198,17 +181,5 @@ describe("When index prop is defined", () => {
expect(Select.vm.isOptionSelected(nestedOption)).toEqual(true);
});
it("can determine a selected values label", () => {
const nestedOption = { value: { nested: true }, label: "foo" };
const Select = shallowMount(VueSelect, {
propsData: {
index: "value",
value: { nested: true },
options: [nestedOption]
}
});
expect(Select.vm.getOptionLabel({ nested: true })).toEqual("foo");
});
});
});