2019-10-24 13:02:34 +02:00
// Type definitions for Choices.js 7.1.x
2017-11-29 10:14:37 +01:00
// Project: https://github.com/jshjohnson/Choices
2019-10-25 16:43:28 +02:00
// Definitions by:
// Arthur vasconcelos <https://github.com/arthurvasconcelos>,
// Josh Johnson <https://github.com/jshjohnson>,
// Zack Schuster <https://github.com/zackschuster>
// Konstantin Vyatkin <https://github.com/tinovyatkin>
2017-11-29 10:14:37 +01:00
// Definitions: https://github.com/jshjohnson/Choices
2019-10-23 20:11:22 +02:00
import { FuseOptions } from 'fuse.js' ;
2017-11-29 10:14:37 +01:00
// Choices Namespace
declare namespace Choices {
namespace Types {
2019-10-23 20:11:22 +02:00
type strToEl = (
2019-10-28 20:33:27 +01:00
str : string ,
2019-10-23 20:11:22 +02:00
) = > HTMLElement | HTMLInputElement | HTMLOptionElement ;
2017-11-29 10:14:37 +01:00
type stringFunction = ( ) = > string ;
type noticeStringFunction = ( value : string ) = > string ;
type noticeLimitFunction = ( maxItemCount : number ) = > string ;
2019-10-29 18:29:31 +01:00
type filterFunction = ( value : string ) = > boolean ;
2019-11-02 15:59:17 +01:00
type itemCompareFunction = ( choice : Choice , item : Item ) = > boolean ;
2017-11-29 10:14:37 +01:00
}
2019-07-03 11:43:57 +02:00
interface Choice {
2019-11-02 21:43:15 +01:00
id? : string ;
2019-10-24 13:02:34 +02:00
customProperties? : Record < string , any > ;
2019-07-03 11:43:57 +02:00
disabled? : boolean ;
2019-11-02 17:19:02 +01:00
active? : boolean ;
2019-07-03 11:43:57 +02:00
elementId? : string ;
groupId? : string ;
keyCode? : number ;
label : string ;
2019-10-23 20:11:22 +02:00
placeholder? : boolean ;
2019-07-03 11:43:57 +02:00
selected? : boolean ;
2019-10-23 20:11:22 +02:00
value : string ;
2019-07-03 11:43:57 +02:00
}
2019-11-02 21:43:15 +01:00
interface Group {
id? : string ;
active? : boolean ;
disabled? : boolean ;
value : any ;
}
interface Item extends Choice {
choiceId? : string ;
keyCode? : number ;
}
2017-11-29 10:14:37 +01:00
/ * *
* Events fired by Choices behave the same as standard events . Each event is triggered on the element passed to Choices ( accessible via ` this.passedElement ` . Arguments are accessible within the ` event.detail ` object .
* /
interface EventMap {
/ * *
* Triggered each time an item is added ( programmatically or by the user ) .
*
* * * Input types affected : * * text , select - one , select - multiple
*
* Arguments : id , value , label , groupValue , keyCode
* /
2019-10-25 16:43:28 +02:00
addItem : CustomEvent < {
id : string ;
value : string ;
label : string ;
groupValue : string ;
keyCode : string ;
} > ;
2019-02-12 19:35:46 +01:00
2017-11-29 10:14:37 +01:00
/ * *
* Triggered each time an item is removed ( programmatically or by the user ) .
*
* * * Input types affected : * * text , select - one , select - multiple
*
* Arguments : id , value , label , groupValue
* /
2019-10-25 16:43:28 +02:00
removeItem : CustomEvent < {
id : string ;
value : string ;
label : string ;
groupValue : string ;
} > ;
2017-11-29 10:14:37 +01:00
/ * *
* Triggered each time an item is highlighted .
*
* * * Input types affected : * * text , select - multiple
*
* Arguments : id , value , label , groupValue
* /
2019-10-25 16:43:28 +02:00
highlightItem : CustomEvent < {
id : string ;
value : string ;
label : string ;
groupValue : string ;
} > ;
2017-11-29 10:14:37 +01:00
/ * *
* Triggered each time an item is unhighlighted .
*
* * * Input types affected : * * text , select - multiple
*
* Arguments : id , value , label , groupValue
* /
2019-10-25 16:43:28 +02:00
unhighlightItem : CustomEvent < {
id : string ;
value : string ;
label : string ;
groupValue : string ;
} > ;
2017-11-29 10:14:37 +01:00
/ * *
* Triggered each time a choice is selected * * by a user * * , regardless if it changes the value of the input .
*
* * * Input types affected : * * select - one , select - multiple
*
2019-10-28 20:33:27 +01:00
* Arguments : choice : Choice
2017-11-29 10:14:37 +01:00
* /
2019-10-28 20:33:27 +01:00
choice : CustomEvent < { choice : Choices.Choice } > ;
2017-11-29 10:14:37 +01:00
/ * *
* Triggered each time an item is added / removed * * by a user * * .
*
* * * Input types affected : * * text , select - one , select - multiple
*
* Arguments : value
* /
2019-10-25 16:43:28 +02:00
change : CustomEvent < { value : string } > ;
2017-11-29 10:14:37 +01:00
/ * *
* Triggered when a user types into an input to search choices .
*
* * * Input types affected : * * select - one , select - multiple
*
* Arguments : value , resultCount
* /
2019-10-25 16:43:28 +02:00
search : CustomEvent < { value : string ; resultCount : number } > ;
2017-11-29 10:14:37 +01:00
/ * *
* Triggered when the dropdown is shown .
*
* * * Input types affected : * * select - one , select - multiple
*
* Arguments : -
* /
2019-10-25 16:43:28 +02:00
showDropdown : CustomEvent < undefined > ;
2017-11-29 10:14:37 +01:00
/ * *
* Triggered when the dropdown is hidden .
*
* * * Input types affected : * * select - one , select - multiple
*
* Arguments : -
* /
2019-10-25 16:43:28 +02:00
hideDropdown : CustomEvent < undefined > ;
/ * *
* Triggered when a choice from the dropdown is highlighted .
*
* Input types affected : select - one , select - multiple
2019-10-28 20:33:27 +01:00
* Arguments : el is the choice . passedElement that was affected .
2019-10-25 16:43:28 +02:00
* /
2019-10-28 20:33:27 +01:00
highlightChoice : CustomEvent < { el : Choices.passedElement } > ;
2017-11-29 10:14:37 +01:00
}
interface Templates {
2019-10-25 16:43:28 +02:00
containerOuter : (
this : Choices ,
classNames : ClassNames ,
direction : HTMLElement [ 'dir' ] ,
isSelectElement : boolean ,
isSelectOneElement : boolean ,
searchEnabled : boolean ,
2019-10-28 20:33:27 +01:00
passedElementType : passedElement [ 'type' ] ,
2019-10-25 16:43:28 +02:00
) = > HTMLElement ;
containerInner : ( this : Choices , classNames : ClassNames ) = > HTMLElement ;
itemList : (
this : Choices ,
2019-10-23 20:11:22 +02:00
classNames : ClassNames ,
2019-10-28 20:33:27 +01:00
isSelectOneElement : boolean ,
2019-10-23 20:11:22 +02:00
) = > HTMLElement ;
2019-10-25 16:43:28 +02:00
placeholder : (
this : Choices ,
classNames : ClassNames ,
2019-10-28 20:33:27 +01:00
value : string ,
2019-10-25 16:43:28 +02:00
) = > HTMLElement ;
item : (
this : Choices ,
2019-10-23 20:11:22 +02:00
classNames : ClassNames ,
data : Choice ,
2019-10-28 20:33:27 +01:00
removeItemButton : boolean ,
2019-10-23 20:11:22 +02:00
) = > HTMLElement ;
2019-10-25 16:43:28 +02:00
choiceList : (
this : Choices ,
2019-10-23 20:11:22 +02:00
classNames : ClassNames ,
2019-10-28 20:33:27 +01:00
isSelectOneElement : boolean ,
2019-10-23 20:11:22 +02:00
) = > HTMLElement ;
2019-10-25 16:43:28 +02:00
choiceGroup : (
this : Choices ,
classNames : ClassNames ,
2019-10-28 20:33:27 +01:00
data : Choice ,
2019-10-25 16:43:28 +02:00
) = > HTMLElement ;
choice : (
this : Choices ,
classNames : ClassNames ,
data : Choice ,
2019-10-28 20:33:27 +01:00
selectText : string ,
2019-10-25 16:43:28 +02:00
) = > HTMLElement ;
input : (
this : Choices ,
classNames : ClassNames ,
2019-10-28 20:33:27 +01:00
placeholderValue : string ,
2019-10-25 16:43:28 +02:00
) = > HTMLInputElement ;
dropdown : ( this : Choices , classNames : ClassNames ) = > HTMLElement ;
notice : (
this : Choices ,
classNames : ClassNames ,
label : string ,
2019-10-28 20:33:27 +01:00
type : '' | 'no-results' | 'no-choices' ,
2019-10-25 16:43:28 +02:00
) = > HTMLElement ;
option : ( data : Choice ) = > HTMLOptionElement ;
2017-11-29 10:14:37 +01:00
}
/** Classes added to HTML generated by Choices. By default classnames follow the BEM notation. */
interface ClassNames {
/** @default 'choices' */
2019-10-25 16:43:28 +02:00
containerOuter : string ;
2017-11-29 10:14:37 +01:00
/** @default 'choices__inner' */
2019-10-25 16:43:28 +02:00
containerInner : string ;
2017-11-29 10:14:37 +01:00
/** @default 'choices__input' */
2019-10-25 16:43:28 +02:00
input : string ;
2017-11-29 10:14:37 +01:00
/** @default 'choices__input--cloned' */
2019-10-25 16:43:28 +02:00
inputCloned : string ;
2017-11-29 10:14:37 +01:00
/** @default 'choices__list' */
2019-10-25 16:43:28 +02:00
list : string ;
2017-11-29 10:14:37 +01:00
/** @default 'choices__list--multiple' */
2019-10-25 16:43:28 +02:00
listItems : string ;
2017-11-29 10:14:37 +01:00
/** @default 'choices__list--single' */
2019-10-25 16:43:28 +02:00
listSingle : string ;
2017-11-29 10:14:37 +01:00
/** @default 'choices__list--dropdown' */
2019-10-25 16:43:28 +02:00
listDropdown : string ;
2017-11-29 10:14:37 +01:00
/** @default 'choices__item' */
2019-10-25 16:43:28 +02:00
item : string ;
2017-11-29 10:14:37 +01:00
/** @default 'choices__item--selectable' */
2019-10-25 16:43:28 +02:00
itemSelectable : string ;
2017-11-29 10:14:37 +01:00
/** @default 'choices__item--disabled' */
2019-10-25 16:43:28 +02:00
itemDisabled : string ;
2017-11-29 10:14:37 +01:00
/** @default 'choices__item--choice' */
2019-10-25 16:43:28 +02:00
itemChoice : string ;
2017-11-29 10:14:37 +01:00
/** @default 'choices__placeholder' */
2019-10-25 16:43:28 +02:00
placeholder : string ;
2017-11-29 10:14:37 +01:00
/** @default 'choices__group' */
2019-10-25 16:43:28 +02:00
group : string ;
2017-11-29 10:14:37 +01:00
/** @default 'choices__heading' */
2019-10-25 16:43:28 +02:00
groupHeading : string ;
2017-11-29 10:14:37 +01:00
/** @default 'choices__button' */
2019-10-25 16:43:28 +02:00
button : string ;
2017-11-29 10:14:37 +01:00
/** @default 'is-active' */
2019-10-25 16:43:28 +02:00
activeState : string ;
2017-11-29 10:14:37 +01:00
/** @default 'is-focused' */
2019-10-25 16:43:28 +02:00
focusState : string ;
2017-11-29 10:14:37 +01:00
/** @default 'is-open' */
2019-10-25 16:43:28 +02:00
openState : string ;
2017-11-29 10:14:37 +01:00
/** @default 'is-disabled' */
2019-10-25 16:43:28 +02:00
disabledState : string ;
2017-11-29 10:14:37 +01:00
/** @default 'is-highlighted' */
2019-10-25 16:43:28 +02:00
highlightedState : string ;
2017-11-29 10:14:37 +01:00
/** @default 'is-flipped' */
2019-10-25 16:43:28 +02:00
flippedState : string ;
2017-11-29 10:14:37 +01:00
/** @default 'is-loading' */
2019-10-25 16:43:28 +02:00
loadingState : string ;
2017-11-29 10:14:37 +01:00
/** @default 'has-no-results' */
2019-10-25 16:43:28 +02:00
noResults : string ;
2017-11-29 10:14:37 +01:00
/** @default 'has-no-choices' */
2019-10-25 16:43:28 +02:00
noChoices : string ;
2017-11-29 10:14:37 +01:00
}
2017-11-29 10:39:19 +01:00
interface passedElement {
2019-10-23 20:11:22 +02:00
classNames : Choices.ClassNames ;
element : ( HTMLInputElement | HTMLSelectElement ) & {
// Extends HTMLElement addEventListener with Choices events
addEventListener < K extends keyof Choices.EventMap > (
type : K ,
listener : (
this : HTMLInputElement | HTMLSelectElement ,
2019-10-28 20:33:27 +01:00
ev : Choices.EventMap [ K ] ,
2019-10-23 20:11:22 +02:00
) = > void ,
2019-10-28 20:33:27 +01:00
options? : boolean | AddEventListenerOptions ,
2019-10-23 20:11:22 +02:00
) : void ;
} ;
2019-10-25 16:43:28 +02:00
type : 'text' | 'select-one' | 'select-multiple' ;
2019-10-23 20:11:22 +02:00
isDisabled : boolean ;
2017-11-29 10:39:19 +01:00
parentInstance : Choices ;
}
2017-11-29 10:14:37 +01:00
/ * *
* Choices options interface
*
* * * Terminology * *
*
2019-10-23 20:11:22 +02:00
* - * * Choice : * * A choice is a value a user can select . A choice would be equivalent to the ` <option></option> ` element within a select input .
2017-11-29 10:14:37 +01:00
* - * * Group : * * A group is a collection of choices . A group should be seen as equivalent to a ` <optgroup></optgroup> ` element within a select input .
* - * * Item : * * An item is an inputted value * * _ ( text input ) _ * * or a selected choice * * _ ( select element ) _ * * . In the context of a select element , an item is equivelent to a selected option element : ` <option value="Hello" selected></option> ` whereas in the context of a text input an item is equivelant to ` <input type="text" value="Hello"> `
* /
interface Options {
/ * *
* Optionally suppress console errors and warnings .
*
* * * Input types affected : * * text , select - single , select - multiple
*
* @default false
* /
2019-10-25 16:43:28 +02:00
silent : boolean ;
2017-11-29 10:14:37 +01:00
/ * *
* Add pre - selected items ( see terminology ) to text input .
*
* * * Input types affected : * * text
*
* @example
* ` ` `
* [ 'value 1' , 'value 2' , 'value 3' ]
* ` ` `
*
* @example
* ` ` `
* [ {
* value : 'Value 1' ,
* label : 'Label 1' ,
* id : 1
* } ,
* {
* value : 'Value 2' ,
* label : 'Label 2' ,
* id : 2 ,
* customProperties : {
* random : 'I am a custom property'
* }
* } ]
* ` ` `
*
* @default [ ]
* /
2019-10-25 16:43:28 +02:00
items : string [ ] | Choice [ ] ;
2017-11-29 10:14:37 +01:00
/ * *
* Add choices ( see terminology ) to select input .
*
* * * Input types affected : * * select - one , select - multiple
*
* @example
* ` ` `
* [ {
* value : 'Option 1' ,
* label : 'Option 1' ,
* selected : true ,
* disabled : false ,
* } ,
* {
* value : 'Option 2' ,
* label : 'Option 2' ,
* selected : false ,
* disabled : true ,
* customProperties : {
* description : 'Custom description about Option 2' ,
* random : 'Another random custom property'
* } ,
* } ]
* ` ` `
*
* @default [ ]
* /
2019-10-25 16:43:28 +02:00
choices : Choice [ ] ;
2017-11-29 10:14:37 +01:00
/ * *
* The amount of choices to be rendered within the dropdown list ` ("-1" indicates no limit) ` . This is useful if you have a lot of choices where it is easier for a user to use the search area to find a choice .
*
* * * Input types affected : * * select - one , select - multiple
*
* @default - 1
* /
2019-10-25 16:43:28 +02:00
renderChoiceLimit : number ;
2017-11-29 10:14:37 +01:00
/ * *
* The amount of items a user can input / select ` ("-1" indicates no limit) ` .
*
* * * Input types affected : * * text , select - multiple
*
* @default - 1
* /
2019-10-25 16:43:28 +02:00
maxItemCount : number ;
2017-11-29 10:14:37 +01:00
/ * *
* Whether a user can add items .
*
* * * Input types affected : * * text
*
* @default true
* /
2019-10-25 16:43:28 +02:00
addItems : boolean ;
2017-11-29 10:14:37 +01:00
2019-10-23 20:11:22 +02:00
/ * *
* A filter that will need to pass for a user to successfully add an item .
*
* * * Input types affected : * * text
*
* @default null
* /
2019-11-02 15:59:17 +01:00
addItemFilter : string | RegExp | Choices . Types . filterFunction | null ;
2019-10-23 20:11:22 +02:00
/ * *
* The text that is shown when a user has inputted a new item but has not pressed the enter key . To access the current input value , pass a function with a ` value ` argument ( see the * * default config * * [ https : //github.com/jshjohnson/Choices#setup] for an example), otherwise pass a string.
*
* * * Input types affected : * * text
*
* @default
* ` ` `
* ( value ) = > ` Press Enter to add <b>" ${ value } "</b> ` ;
* ` ` `
* /
2019-10-25 16:43:28 +02:00
addItemText : string | Choices . Types . noticeStringFunction ;
2019-10-23 20:11:22 +02:00
2017-11-29 10:14:37 +01:00
/ * *
* Whether a user can remove items .
*
* * * Input types affected : * * text , select - multiple
*
* @default true
* /
2019-10-25 16:43:28 +02:00
removeItems : boolean ;
2017-11-29 10:14:37 +01:00
/ * *
* Whether each item should have a remove button .
*
* * * Input types affected : * * text , select - one , select - multiple
*
* @default false
* /
2019-10-25 16:43:28 +02:00
removeItemButton : boolean ;
2017-11-29 10:14:37 +01:00
/ * *
* Whether a user can edit items . An item ' s value can be edited by pressing the backspace .
*
* * * Input types affected : * * text
*
* @default false
* /
2019-10-25 16:43:28 +02:00
editItems : boolean ;
2017-11-29 10:14:37 +01:00
/ * *
* Whether each inputted / chosen item should be unique .
*
* * * Input types affected : * * text , select - multiple
*
* @default true
* /
2019-10-25 16:43:28 +02:00
duplicateItemsAllowed : boolean ;
2017-11-29 10:14:37 +01:00
/ * *
2019-10-23 20:11:22 +02:00
* What divides each value . The default delimiter separates each value with a comma : ` "Value 1, Value 2, Value 3" ` .
2017-11-29 10:14:37 +01:00
*
* * * Input types affected : * * text
*
* @default ','
* /
2019-10-25 16:43:28 +02:00
delimiter : string ;
2017-11-29 10:14:37 +01:00
/ * *
* Whether a user can paste into the input .
*
* * * Input types affected : * * text , select - multiple
*
* @default true
* /
2019-10-25 16:43:28 +02:00
paste : boolean ;
2017-11-29 10:14:37 +01:00
/ * *
* Whether a search area should be shown .
*
* @note Multiple select boxes will always show search areas .
*
* * * Input types affected : * * select - one
*
* @default true
* /
2019-10-25 16:43:28 +02:00
searchEnabled : boolean ;
2017-11-29 10:14:37 +01:00
/ * *
* Whether choices should be filtered by input or not . If ` false ` , the search event will still emit , but choices will not be filtered .
*
* * * Input types affected : * * select - one
*
* @default true
* /
2019-10-25 16:43:28 +02:00
searchChoices : boolean ;
2017-11-29 10:14:37 +01:00
/ * *
* The minimum length a search value should be before choices are searched .
*
* * * Input types affected : * * select - one , select - multiple
*
* @default 1
* /
2019-10-25 16:43:28 +02:00
searchFloor : number ;
2017-11-29 10:14:37 +01:00
/ * *
* The maximum amount of search results to show .
*
* * * Input types affected : * * select - one , select - multiple
*
* @default 4
* /
2019-10-25 16:43:28 +02:00
searchResultLimit : number ;
2017-11-29 10:14:37 +01:00
/ * *
* Specify which fields should be used when a user is searching . If you have added custom properties to your choices , you can add these values thus : ` ['label', 'value', 'customProperties.example'] ` .
*
* Input types affected :select - one , select - multiple
*
* @default [ 'label' , 'value' ]
* /
2019-10-25 16:43:28 +02:00
searchFields : string [ ] ;
2017-11-29 10:14:37 +01:00
/ * *
* Whether the dropdown should appear above ` (top) ` or below ` (bottom) ` the input . By default , if there is not enough space within the window the dropdown will appear above the input , otherwise below it .
*
* * * Input types affected : * * select - one , select - multiple
*
* @default 'auto'
* /
2019-10-25 16:43:28 +02:00
position : 'auto' | 'top' ;
2017-11-29 10:14:37 +01:00
/ * *
* Whether the scroll position should reset after adding an item .
*
* * * Input types affected : * * select - multiple
*
* @default true
* /
2019-10-25 16:43:28 +02:00
resetScrollPosition : boolean ;
2017-11-29 10:14:37 +01:00
/ * *
* Whether choices and groups should be sorted . If false , choices / groups will appear in the order they were given .
*
* * * Input types affected : * * select - one , select - multiple
*
* @default true
* /
2019-10-25 16:43:28 +02:00
shouldSort : boolean ;
2017-11-29 10:14:37 +01:00
/ * *
* Whether items should be sorted . If false , items will appear in the order they were selected .
*
* * * Input types affected : * * text , select - multiple
*
* @default false
* /
2019-10-25 16:43:28 +02:00
shouldSortItems : boolean ;
2017-11-29 10:14:37 +01:00
/ * *
* The function that will sort choices and items before they are displayed ( unless a user is searching ) . By default choices and items are sorted by alphabetical order .
*
* * * Input types affected : * * select - one , select - multiple
*
* @example
* ` ` `
* // Sorting via length of label from largest to smallest
* const example = new Choices ( element , {
2019-11-02 16:04:24 +01:00
* sorter : function ( a , b ) {
2017-11-29 10:14:37 +01:00
* return b . label . length - a . label . length ;
* } ,
* } ;
* ` ` `
*
* @default sortByAlpha
* /
2019-11-02 16:04:24 +01:00
sorter : ( current : Choice , next : Choice ) = > number ;
2017-11-29 10:14:37 +01:00
/ * *
* Whether the input should show a placeholder . Used in conjunction with ` placeholderValue ` . If ` placeholder ` is set to true and no value is passed to ` placeholderValue ` , the passed input ' s placeholder attribute will be used as the placeholder value .
*
* * * Input types affected : * * text , select - multiple
*
* @note For single select boxes , the recommended way of adding a placeholder is as follows :
* ` ` `
* < select >
* < option placeholder > This is a placeholder < / option >
* < option > . . . < / option >
* < option > . . . < / option >
* < option > . . . < / option >
* < / select >
* ` ` `
*
* @default true
* /
2019-10-25 16:43:28 +02:00
placeholder : boolean ;
2017-11-29 10:14:37 +01:00
/ * *
* The value of the inputs placeholder .
*
* * * Input types affected : * * text , select - multiple
*
* @default null
* /
2019-11-02 15:59:17 +01:00
placeholderValue : string | null ;
2017-11-29 10:14:37 +01:00
/ * *
* The value of the search inputs placeholder .
*
* * * Input types affected : * * select - one
*
* @default null
* /
2019-11-02 15:59:17 +01:00
searchPlaceholderValue : string | null ;
2017-11-29 10:14:37 +01:00
/ * *
* Prepend a value to each item added / selected .
*
* * * Input types affected : * * text , select - one , select - multiple
*
* @default null
* /
2019-11-02 15:59:17 +01:00
prependValue : string | null ;
2017-11-29 10:14:37 +01:00
/ * *
* Append a value to each item added / selected .
*
* * * Input types affected : * * text , select - one , select - multiple
*
* @default null
* /
2019-11-02 15:59:17 +01:00
appendValue : string | null ;
2017-11-29 10:14:37 +01:00
/ * *
* Whether selected choices should be removed from the list . By default choices are removed when they are selected in multiple select box . To always render choices pass ` always ` .
*
* * * Input types affected : * * select - one , select - multiple
*
* @default 'auto' ;
* /
2019-10-25 16:43:28 +02:00
renderSelectedChoices : 'auto' | 'always' ;
2017-11-29 10:14:37 +01:00
/ * *
* The text that is shown whilst choices are being populated via AJAX .
*
* * * Input types affected : * * select - one , select - multiple
*
* @default 'Loading...'
* /
2019-10-25 16:43:28 +02:00
loadingText : string ;
2017-11-29 10:14:37 +01:00
/ * *
* The text that is shown when a user ' s search has returned no results . Optionally pass a function returning a string .
*
* * * Input types affected : * * select - one , select - multiple
*
* @default 'No results found'
* /
2019-10-25 16:43:28 +02:00
noResultsText : string | Choices . Types . stringFunction ;
2017-11-29 10:14:37 +01:00
/ * *
* The text that is shown when a user has selected all possible choices . Optionally pass a function returning a string .
*
* * * Input types affected : * * select - multiple
*
* @default 'No choices to choose from'
* /
2019-10-25 16:43:28 +02:00
noChoicesText : string | Choices . Types . stringFunction ;
2017-11-29 10:14:37 +01:00
/ * *
* The text that is shown when a user hovers over a selectable choice .
*
* * * Input types affected : * * select - multiple , select - one
*
* @default 'Press to select'
* /
2019-10-25 16:43:28 +02:00
itemSelectText : string ;
2017-11-29 10:14:37 +01:00
/ * *
* The text that is shown when a user has focus on the input but has already reached the * * max item count * * [ https : //github.com/jshjohnson/Choices#maxitemcount]. To access the max item count, pass a function with a `maxItemCount` argument (see the **default config** [https://github.com/jshjohnson/Choices#setup] for an example), otherwise pass a string.
*
* * * Input types affected : * * text
*
* @default
* ` ` `
* ( maxItemCount ) = > ` Only ${ maxItemCount } values can be added. ` ;
* ` ` `
* /
2019-10-25 16:43:28 +02:00
maxItemText : string | Choices . Types . noticeLimitFunction ;
2017-11-29 10:14:37 +01:00
/ * *
* If no duplicates are allowed , and the value already exists in the array .
*
2019-11-02 15:59:17 +01:00
* @default 'Only unique values can be added'
2017-11-29 10:14:37 +01:00
* /
2019-10-25 16:43:28 +02:00
uniqueItemText : string | Choices . Types . noticeStringFunction ;
2017-11-29 10:14:37 +01:00
2019-11-02 15:59:17 +01:00
/ * *
* The text that is shown when addItemFilter is passed and it returns false
*
* * * Input types affected : * * text
*
* @default 'Only values matching specific conditions can be added'
* /
customAddItemText : string | Choices . Types . noticeStringFunction ;
/ * *
* Compare choice and value in appropriate way ( e . g . deep equality for objects ) . To compare choice and value , pass a function with a ` itemComparer ` argument ( see the [ default config ] ( https : //github.com/jshjohnson/Choices#setup) for an example).
*
* * * Input types affected : * * select - one , select - multiple
*
* @default
* ` ` `
* ( choice , item ) = > choice === item ;
* ` ` `
* /
itemComparer : Choices.Types.itemCompareFunction ;
2017-11-29 10:14:37 +01:00
/ * *
* Classes added to HTML generated by Choices . By default classnames follow the BEM notation .
*
* * * Input types affected : * * text , select - one , select - multiple
* /
2019-10-25 16:43:28 +02:00
classNames : Partial < Choices.ClassNames > ;
2017-11-29 10:14:37 +01:00
/ * *
* Choices uses the great Fuse library for searching . You can find more options here : https : //github.com/krisk/Fuse#options
* /
2019-10-25 16:43:28 +02:00
fuseOptions : FuseOptions < Choice > ;
2017-11-29 10:14:37 +01:00
/ * *
* Function to run once Choices initialises .
*
* * * Input types affected : * * text , select - one , select - multiple
*
* @note For each callback , this refers to the current instance of Choices . This can be useful if you need access to methods ` (this.disable()) ` or the config object ` (this.config) ` .
*
* @default null
* /
2019-11-02 15:59:17 +01:00
callbackOnInit : ( ( this : Choices ) = > void ) | null ;
2017-11-29 10:14:37 +01:00
/ * *
* Function to run on template creation . Through this callback it is possible to provide custom templates for the various components of Choices ( see terminology ) . For Choices to work with custom templates , it is important you maintain the various data attributes defined here [ https : //github.com/jshjohnson/Choices/blob/67f29c286aa21d88847adfcd6304dc7d068dc01f/assets/scripts/src/choices.js#L1993-L2067].
*
* * * Input types affected : * * text , select - one , select - multiple
*
* @note For each callback , this refers to the current instance of Choices . This can be useful if you need access to methods ` (this.disable()) ` or the config object ` (this.config) ` .
*
* @example
* ` ` `
* const example = new Choices ( element , {
* callbackOnCreateTemplates : function ( template ) {
* var classNames = this . config . classNames ;
* return {
* item : ( data ) = > {
* return template ( `
* < div class = "${classNames.item} ${data.highlighted ? classNames.highlightedState : classNames.itemSelectable}" data - item data - id = "${data.id}" data - value = "${data.value}" $ { data.active ? ' aria - selected = "true" ' : ' ' } $ { data.disabled ? ' aria - disabled = "true" ' : ' ' } >
* < span > & bigstar ; < / span > $ { data . label }
* < / div >
* ` );
* } ,
* choice : ( data ) = > {
* return template ( `
* < div class = "${classNames.item} ${classNames.itemChoice} ${data.disabled ? classNames.itemDisabled : classNames.itemSelectable}" data - select - text = "${this.config.itemSelectText}" data - choice $ { data.disabled ? ' data - choice - disabled aria - disabled = "true" ' : ' data - choice - selectable ' } data - id = "${data.id}" data - value = "${data.value}" $ { data.groupId > 0 ? 'role="treeitem"' : 'role="option"' } >
* < span > & bigstar ; < / span > $ { data . label }
* < / div >
* ` );
* } ,
* } ;
* }
* } ) ;
* ` ` `
*
* @default null
* /
2019-11-02 15:59:17 +01:00
callbackOnCreateTemplates :
| ( ( template : Choices.Types.strToEl ) = > Partial < Choices.Templates > )
| null ;
2017-11-29 10:14:37 +01:00
}
}
// Exporting default class
export default class Choices {
2019-10-29 16:13:00 +01:00
static readonly defaults : {
readonly options : Partial < Choices.Options > ;
readonly templates : Choices.Templates ;
} ;
2019-10-25 16:43:28 +02:00
readonly config : Choices.Options ;
2017-11-29 10:14:37 +01:00
// State Tracking
initialised : boolean ;
// Element
2019-10-25 16:43:28 +02:00
readonly passedElement : Choices.passedElement ;
2017-11-29 10:14:37 +01:00
2019-10-25 16:43:28 +02:00
placeholder : boolean ;
2017-11-29 10:14:37 +01:00
2019-10-23 20:11:22 +02:00
constructor (
2019-10-24 13:02:34 +02:00
selectorOrElement : string | HTMLInputElement | HTMLSelectElement ,
2019-10-28 20:33:27 +01:00
userConfig? : Partial < Choices.Options > ,
2019-10-23 20:11:22 +02:00
) ;
2017-11-29 10:14:37 +01:00
/ * *
* Creates a new instance of Choices , adds event listeners , creates templates and renders a Choices element to the DOM .
*
* @note This is called implicitly when a new instance of Choices is created . This would be used after a Choices instance had already been destroyed ` (using destroy()) ` .
*
* * * Input types affected : * * text , select - multiple , select - one
* /
init ( ) : void ;
/ * *
* Kills the instance of Choices , removes all event listeners and returns passed input to its initial state .
*
* * * Input types affected : * * text , select - multiple , select - one
* /
destroy ( ) : void ;
/** Select item (a selected item can be deleted) */
highlightItem ( item : Element , runEvent? : boolean ) : this ;
/** Deselect item */
unhighlightItem ( item : Element ) : this ;
/ * *
* Highlight each chosen item ( selected items can be removed ) .
*
* * * Input types affected : * * text , select - multiple
* /
highlightAll ( ) : this ;
/ * *
* Un - highlight each chosen item .
*
* * * Input types affected : * * text , select - multiple
* /
unhighlightAll ( ) : this ;
/ * *
* Remove each item by a given value .
*
* * * Input types affected : * * text , select - multiple
* /
2017-11-29 10:17:42 +01:00
removeActiveItemsByValue ( value : string ) : this ;
2017-11-29 10:14:37 +01:00
/ * *
* Remove each selectable item .
*
* * * Input types affected : * * text , select - multiple
* /
removeActiveItems ( excludedId : number ) : this ;
/ * *
* Remove each item the user has selected .
*
* * * Input types affected : * * text , select - multiple
* /
removeHighlightedItems ( runEvent? : boolean ) : this ;
/ * *
* Show option list dropdown ( only affects select inputs ) .
*
* * * Input types affected : * * select - one , select - multiple
* /
showDropdown ( focusInput? : boolean ) : this ;
/ * *
* Hide option list dropdown ( only affects select inputs ) .
*
* * * Input types affected : * * text , select - multiple
* /
hideDropdown ( blurInput? : boolean ) : this ;
/ * *
* Get value ( s ) of input ( i . e . inputted items ( text ) or selected choices ( select ) ) . Optionally pass an argument of ` true ` to only return values rather than value objects .
*
* * * Input types affected : * * text , select - one , select - multiple
*
* @example
* ` ` `
* const example = new Choices ( element ) ;
* const values = example . getValue ( true ) ; // returns ['value 1', 'value 2'];
* const valueArray = example . getValue ( ) ; // returns [{ active: true, choiceId: 1, highlighted: false, id: 1, label: 'Label 1', value: 'Value 1'}, { active: true, choiceId: 2, highlighted: false, id: 2, label: 'Label 2', value: 'Value 2'}];
* ` ` `
* /
getValue ( valueOnly? : boolean ) : string | string [ ] ;
2019-10-29 19:12:32 +01:00
/ * * D i r e c t p o p u l a t e c h o i c e s
*
* @param { string [ ] | Choices . Item [ ] } items
* /
setValue ( items : string [ ] | Choices . Item [ ] ) : this ;
/ * *
* Set value of input based on existing Choice . ` value ` can be either a single string or an array of strings
*
* * * Input types affected : * * select - one , select - multiple
*
* @example
* ` ` `
* const example = new Choices ( element , {
* choices : [
* { value : 'One' , label : 'Label One' } ,
* { value : 'Two' , label : 'Label Two' , disabled : true } ,
* { value : 'Three' , label : 'Label Three' } ,
* ] ,
* } ) ;
*
* example . setChoiceByValue ( 'Two' ) ; // Choice with value of 'Two' has now been selected.
* ` ` `
* /
setChoiceByValue ( value : string | string [ ] ) : this ;
2017-11-29 10:14:37 +01:00
/ * *
2019-10-29 19:12:32 +01:00
* Set choices of select input via an array of objects ( or function that returns array of object or promise of it ) ,
* a value field name and a label field name .
2017-11-29 10:14:37 +01:00
* This behaves the same as passing items via the choices option but can be called after initialising Choices .
* This can also be used to add groups of choices ( see example 2 ) ; Optionally pass a true ` replaceChoices ` value to remove any existing choices .
* Optionally pass a ` customProperties ` object to add additional data to your choices ( useful when searching / filtering etc ) .
*
* * * Input types affected : * * select - one , select - multiple
*
2019-10-29 19:12:32 +01:00
* @param { string } [ value = 'value' ] - name of ` value ` field
* @param { string } [ label = 'label' ] - name of 'label' field
* @param { boolean } [ replaceChoices = false ] - whether to replace of add choices
*
* @example
* ` ` ` js
2017-11-29 10:14:37 +01:00
* const example = new Choices ( element ) ;
*
* example . setChoices ( [
* { value : 'One' , label : 'Label One' , disabled : true } ,
* { value : 'Two' , label : 'Label Two' , selected : true } ,
* { value : 'Three' , label : 'Label Three' } ,
* ] , 'value' , 'label' , false ) ;
* ` ` `
*
2019-10-29 19:12:32 +01:00
* @example
* ` ` ` js
* const example = new Choices ( element ) ;
*
* example . setChoices ( async ( ) = > {
* try {
* const items = await fetch ( '/items' ) ;
* return items . json ( )
* } catch ( err ) {
* console . error ( err )
* }
* } ) ;
2017-11-29 10:14:37 +01:00
* ` ` `
2019-10-29 19:12:32 +01:00
*
* @example
* ` ` ` js
2017-11-29 10:14:37 +01:00
* const example = new Choices ( element ) ;
*
* example . setChoices ( [ {
* label : 'Group one' ,
* id : 1 ,
* disabled : false ,
* choices : [
* { value : 'Child One' , label : 'Child One' , selected : true } ,
* { value : 'Child Two' , label : 'Child Two' , disabled : true } ,
* { value : 'Child Three' , label : 'Child Three' } ,
* ]
* } ,
* {
* label : 'Group two' ,
* id : 2 ,
* disabled : false ,
* choices : [
* { value : 'Child Four' , label : 'Child Four' , disabled : true } ,
* { value : 'Child Five' , label : 'Child Five' } ,
* { value : 'Child Six' , label : 'Child Six' , customProperties : {
* description : 'Custom description about child six' ,
* random : 'Another random custom property'
* } } ,
* ]
* } ] , 'value' , 'label' , false ) ;
* ` ` `
* /
2019-10-29 19:12:32 +01:00
setChoices <
T extends object [ ] | ( ( instance : Choices ) = > object [ ] | Promise < object [ ] > )
> (
choices : T ,
value? : string ,
label? : string ,
2019-10-28 20:33:27 +01:00
replaceChoices? : boolean ,
2019-10-29 19:12:32 +01:00
) : T extends object [ ] ? this : Promise < this > ;
2017-11-29 10:14:37 +01:00
2019-10-29 18:07:22 +01:00
/ * *
* Clear all choices from select .
*
* * * Input types affected : * * select - one , select - multiple
* /
clearChoices ( ) : this ;
2017-11-29 10:14:37 +01:00
/ * *
* Removes all items , choices and groups . Use with caution .
*
* * * Input types affected : * * text , select - one , select - multiple
* /
clearStore ( ) : this ;
/ * *
* Clear input of any user inputted text .
*
* * * Input types affected : * * text
* /
clearInput ( ) : this ;
/ * *
* Enables input to accept new values / select further choices .
*
* * * Input types affected : * * text , select - one , select - multiple
* /
enable ( ) : this ;
/ * *
* Disables input from accepting new value / selecting further choices .
*
* * * Input types affected : * * text , select - one , select - multiple
* /
disable ( ) : this ;
2018-10-30 09:36:52 +01:00
}