From 4d2caa129c215fd70d97d523dbfdec16d6c916e1 Mon Sep 17 00:00:00 2001 From: Zack Schuster Date: Fri, 4 Aug 2017 14:49:29 -0700 Subject: [PATCH] Update types for 3.0.0 --- index.d.ts | 393 +++++++++++++++++++++++++++++------------------------ 1 file changed, 216 insertions(+), 177 deletions(-) diff --git a/index.d.ts b/index.d.ts index 4420680..4f79579 100644 --- a/index.d.ts +++ b/index.d.ts @@ -3,208 +3,208 @@ declare module "choices.js" { passedElement: Element; constructor(element?: string | HTMLElement | HTMLCollectionOf | NodeList, userConfig?: Choices.Options); - new(element?: string | HTMLElement | HTMLCollectionOf | NodeList, userConfig?: Choices.Options): this;; + new(element?: string | HTMLElement | HTMLCollectionOf | NodeList, userConfig?: Choices.Options): this; - /** - * Initialise Choices - * @return - * @public - */ - init(): void; + /** + * Initialise Choices + * @return + * @public + */ + init(): void; - /** - * Destroy Choices and nullify values - * @return - * @public - */ - destroy(): void; + /** + * Destroy Choices and nullify values + * @return + * @public + */ + destroy(): void; - /** - * Render group choices into a DOM fragment and append to choice list - * @param {Array} groups Groups to add to list - * @param {Array} choices Choices to add to groups - * @param {DocumentFragment} fragment Fragment to add groups and options to (optional) - * @return {DocumentFragment} Populated options fragment - * @private - */ - renderGroups(groups: any[], choices: any[], fragment?: DocumentFragment): DocumentFragment; + /** + * Render group choices into a DOM fragment and append to choice list + * @param {Array} groups Groups to add to list + * @param {Array} choices Choices to add to groups + * @param {DocumentFragment} fragment Fragment to add groups and options to (optional) + * @return {DocumentFragment} Populated options fragment + * @private + */ + renderGroups(groups: any[], choices: any[], fragment?: DocumentFragment): DocumentFragment; - /** - * Render choices into a DOM fragment and append to choice list - * @param {Array} choices Choices to add to list - * @param {DocumentFragment} fragment Fragment to add choices to (optional) - * @return {DocumentFragment} Populated choices fragment - * @private - */ + /** + * Render choices into a DOM fragment and append to choice list + * @param {Array} choices Choices to add to list + * @param {DocumentFragment} fragment Fragment to add choices to (optional) + * @return {DocumentFragment} Populated choices fragment + * @private + */ renderChoices(choices: any[], fragment?: DocumentFragment): DocumentFragment; - /** - * Render items into a DOM fragment and append to items list - * @param {Array} items Items to add to list - * @param {DocumentFragment} fragment Fragrment to add items to (optional) - * @return - * @private - */ - renderItems(items: any[], fragment?: DocumentFragment): void; + /** + * Render items into a DOM fragment and append to items list + * @param {Array} items Items to add to list + * @param {DocumentFragment} fragment Fragrment to add items to (optional) + * @return + * @private + */ + renderItems(items: any[], fragment?: DocumentFragment): void; - /** - * Render DOM with values - * @return - * @private - */ - render(): void; + /** + * Render DOM with values + * @return + * @private + */ + render(): void; - /** - * Select item (a selected item can be deleted) - * @param {Element} item Element to select - * @param {boolean} runEvent Whether to highlight immediately or not. Defaults to true. - * @return {Object} Class instance - * @public - */ - highlightItem(item: Element, runEvent?: boolean): this; + /** + * Select item (a selected item can be deleted) + * @param {Element} item Element to select + * @param {boolean} runEvent Whether to highlight immediately or not. Defaults to true. + * @return {Object} Class instance + * @public + */ + highlightItem(item: Element, runEvent?: boolean): this; - /** - * Deselect item - * @param {Element} item Element to de-select - * @return {Object} Class instance - * @public - */ + /** + * Deselect item + * @param {Element} item Element to de-select + * @return {Object} Class instance + * @public + */ unhighlightItem(item: Element): this; - /** - * Highlight items within store - * @return {Object} Class instance - * @public - */ - highlightAll(): this; + /** + * Highlight items within store + * @return {Object} Class instance + * @public + */ + highlightAll(): this; - /** - * Deselect items within store - * @return {Object} Class instance - * @public - */ - unhighlightAll(): this; + /** + * Deselect items within store + * @return {Object} Class instance + * @public + */ + unhighlightAll(): this; - /** - * Remove an item from the store by its value - * @param {String} value Value to search for - * @return {Object} Class instance - * @public - */ - removeItemsByValue(value: string): this; + /** + * Remove an item from the store by its value + * @param {String} value Value to search for + * @return {Object} Class instance + * @public + */ + removeItemsByValue(value: string): this; - /** - * Remove all items from store array - * @note Removed items are soft deleted - * @param {Number} excludedId Optionally exclude item by ID - * @return {Object} Class instance - * @public - */ - removeActiveItems(excludedId?: number): this; + /** + * Remove all items from store array + * @note Removed items are soft deleted + * @param {Number} excludedId Optionally exclude item by ID + * @return {Object} Class instance + * @public + */ + removeActiveItems(excludedId?: number): this; - /** - * Remove all selected items from store - * @note Removed items are soft deleted - * @param {boolean} runEvent Whether to remove highlighted items immediately or not. Defaults to false. - * @return {Object} Class instance - * @public - */ - removeHighlightedItems(runEvent?: boolean): this; + /** + * Remove all selected items from store + * @note Removed items are soft deleted + * @param {boolean} runEvent Whether to remove highlighted items immediately or not. Defaults to false. + * @return {Object} Class instance + * @public + */ + removeHighlightedItems(runEvent?: boolean): this; - /** - * Show dropdown to user by adding active state class - * @param {boolean} focusInput Whether to focus the input or not. Defaults to false. - * @return {Object} Class instance - * @public - */ - showDropdown(focusInput?: boolean): this; + /** + * Show dropdown to user by adding active state class + * @param {boolean} focusInput Whether to focus the input or not. Defaults to false. + * @return {Object} Class instance + * @public + */ + showDropdown(focusInput?: boolean): this; - /** - * Hide dropdown from user - * @param {boolean} focusInput Whether to blur input focus or not. Defaults to false. - * @return {Object} Class instance - * @public - */ - hideDropdown(blurInput?: boolean): this; + /** + * Hide dropdown from user + * @param {boolean} focusInput Whether to blur input focus or not. Defaults to false. + * @return {Object} Class instance + * @public + */ + hideDropdown(blurInput?: boolean): this; - /** - * Determine whether to hide or show dropdown based on its current state - * @return {Object} Class instance - * @public - */ - toggleDropdown(): this; + /** + * Determine whether to hide or show dropdown based on its current state + * @return {Object} Class instance + * @public + */ + toggleDropdown(): this; - /** - * Get value(s) of input (i.e. inputted items (text) or selected choices (select)) - * @param {Boolean} valueOnly Get only values of selected items, otherwise return selected items - * @return {Array/String} selected value (select-one) or array of selected items (inputs & select-multiple) - * @public - */ - getValue(valueOnly?: boolean): string | string[]; + /** + * Get value(s) of input (i.e. inputted items (text) or selected choices (select)) + * @param {Boolean} valueOnly Get only values of selected items, otherwise return selected items + * @return {Array/String} selected value (select-one) or array of selected items (inputs & select-multiple) + * @public + */ + getValue(valueOnly?: boolean): string | string[]; - /** - * Set value of input. If the input is a select box, a choice will be created and selected otherwise - * an item will created directly. - * @param {Array} args Array of value objects or value strings - * @return {Object} Class instance - * @public - */ - setValue(args: any[]): this; + /** + * Set value of input. If the input is a select box, a choice will be created and selected otherwise + * an item will created directly. + * @param {Array} args Array of value objects or value strings + * @return {Object} Class instance + * @public + */ + setValue(args: any[]): this; - /** - * Select value of select box via the value of an existing choice - * @param {Array/String} value An array of strings of a single string - * @return {Object} Class instance - * @public - */ - setValueByChoice(value: string | string[]): this; + /** + * Select value of select box via the value of an existing choice + * @param {Array/String} value An array of strings of a single string + * @return {Object} Class instance + * @public + */ + setValueByChoice(value: string | string[]): this; - /** - * Direct populate choices - * @param {Array} choices - Choices to insert - * @param {String} value - Name of 'value' property - * @param {String} label - Name of 'label' property - * @param {Boolean} replaceChoices Whether existing choices should be removed - * @return {Object} Class instance - * @public - */ - setChoices(choices: any[], value: string, label: string, replaceChoices?: boolean): this; + /** + * Direct populate choices + * @param {Array} choices - Choices to insert + * @param {String} value - Name of 'value' property + * @param {String} label - Name of 'label' property + * @param {Boolean} replaceChoices Whether existing choices should be removed + * @return {Object} Class instance + * @public + */ + setChoices(choices: any[], value: string, label: string, replaceChoices?: boolean): this; - /** - * Clear items,choices and groups - * @note Hard delete - * @return {Object} Class instance - * @public - */ - clearStore(): this; + /** + * Clear items,choices and groups + * @note Hard delete + * @return {Object} Class instance + * @public + */ + clearStore(): this; - /** - * Set value of input to blank - * @return {Object} Class instance - * @public - */ - clearInput(): this; + /** + * Set value of input to blank + * @return {Object} Class instance + * @public + */ + clearInput(): this; - /** - * Enable interaction with Choices - * @return {Object} Class instance - */ - enable(): this; + /** + * Enable interaction with Choices + * @return {Object} Class instance + */ + enable(): this; - /** - * Disable interaction with Choices - * @return {Object} Class instance - * @public - */ - disable(): this; + /** + * Disable interaction with Choices + * @return {Object} Class instance + * @public + */ + disable(): this; - /** - * Populate options via ajax callback - * @param {Function} fn Passed - * @return {Object} Class instance - * @public - */ - ajax(fn: (values: any) => any): this; + /** + * Populate options via ajax callback + * @param {Function} fn Passed + * @return {Object} Class instance + * @public + */ + ajax(fn: (values: any) => any): this; } namespace Choices { @@ -272,6 +272,14 @@ declare module "choices.js" { */ choices?: any[]; + /** + * 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 + */ + renderChoiceLimit?: number; + /** * The amount of items a user can input/select ("-1" indicates no limit). * @@ -436,7 +444,15 @@ declare module "choices.js" { /** * 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-one, select-multiple + * Note: For single select boxes, the recommended way of adding a placeholder is as follows: + * + * + * Input types affected: text, select-multiple * @default true */ placeholder?: boolean; @@ -444,11 +460,19 @@ declare module "choices.js" { /** * The value of the inputs placeholder. * - * Input types affected: text, select-one, select-multiple + * Input types affected: text, select-multiple * @default null */ placeholderValue?: string; + /** + * The value of the search inputs placeholder. + * + * Input types affected: select-one + * @default null + */ + searchPlaceholderValue?: string; + /** * Prepend a value to each item added/selected. * @@ -603,6 +627,11 @@ declare module "choices.js" { */ groupHeading?: string; + /** + * @default 'choices__placeholder' + */ + placeholder?: string; + /** * @default 'choices__button' */ @@ -647,6 +676,16 @@ declare module "choices.js" { * @default 'is-loading' */ loadingState?: string; + + /** + * @default 'has-no-results' + */ + noResults?: string; + + /** + * @default 'has-no-choices' + */ + noChoices?: string; }; /**