Add missing type definitions + rename sortFn (#734)

* Add wrapped element getters + fix some types

* Remove comment

* Add missing config options to types

* Add types to constants

* Rename sortFn to sorter

* Update PR template

* Add refactor to PR template

* Add passed element types to constants

* Add js doc comments to actions

* Add "returns" to js doc comments

* Add missing choice prop to type

* Add types to store.js

* Add jsdoc comments to components

* Ignore strict null checks

* Move loading action into misc.js

* Further type def additions

* Rename itemCompare to valueCompare

* Update badges

* Rename scrollToChoice to scrollToChildElement

.github/PULL_REQUEST_TEMPLATE.md

@@ -4,19 +4,14 @@
 <!--- Why is this change required? What problem does it solve? -->
 <!--- If it fixes an open issue, please link to the issue here. -->
 
-## How Has This Been Tested?
-
-<!--- Please describe in detail how you tested your changes. -->
-<!--- Include details of your testing environment, tests ran to see how -->
-<!--- your change affects other areas of the code, etc. -->
-
 ## Screenshots (if appropriate)
 
 ## Types of changes
 
 <!--- What types of changes does your code introduce? Put an `x` in all the boxes that apply: -->
 
 - [ ] Chore (tooling change or documentation change)
+- [ ] Refactor (non-breaking change which maintains existing functionality)
 - [ ] Bug fix (non-breaking change which fixes an issue)
 - [ ] New feature (non-breaking change which adds functionality)
 - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)

README.md

@@ -1,4 +1,4 @@
-# Choices.js [![Actions Status](https://github.com/jshjohnson/Choices/workflows/Unit%20Tests/badge.svg)](https://github.com/jshjohnson/Choices/actions) [![npm](https://img.shields.io/npm/v/choices.js.svg)](https://www.npmjs.com/package/choices.js) [![codebeat badge](https://codebeat.co/badges/55120150-5866-42d8-8010-6aaaff5d3fa1)](https://codebeat.co/projects/github-com-jshjohnson-choices-master)
+# Choices.js [![Actions Status](https://github.com/jshjohnson/Choices/workflows/Build%20and%20test/badge.svg)](https://github.com/jshjohnson/Choices/actions) [![Actions Status](https://github.com/jshjohnson/Choices/workflows/Bundle%20size%20checks/badge.svg)](https://github.com/jshjohnson/Choices/actions) [![npm](https://img.shields.io/npm/v/choices.js.svg)](https://www.npmjs.com/package/choices.js)
 
 A vanilla, lightweight (~19kb gzipped 🎉), configurable select box/text input plugin. Similar to Select2 and Selectize but without the jQuery dependency.
 
@@ -105,7 +105,7 @@ Or include Choices directly:
     resetScrollPosition: true,
     shouldSort: true,
     shouldSortItems: false,
-    sortFn: () => {...},
+    sorter: () => {...},
     placeholder: true,
     placeholderValue: null,
     searchPlaceholderValue: null,
@@ -122,8 +122,8 @@ Or include Choices directly:
     maxItemText: (maxItemCount) => {
       return `Only ${maxItemCount} values can be added`;
     },
-    itemComparer: (choice, item) => {
-      return choice === item;
+    valueComparer: (value1, value2) => {
+      return value1 === value2;
     },
     classNames: {
       containerOuter: 'choices',
@@ -408,7 +408,7 @@ new Choices(element, {
 
 **Usage:** Whether items should be sorted. If false, items will appear in the order they were selected.
 
-### sortFn
+### sorter
 
 **Type:** `Function` **Default:** sortByAlpha
 
@@ -421,7 +421,7 @@ new Choices(element, {
 ```js
 // Sorting via length of label from largest to smallest
 const example = new Choices(element, {
-  sortFn: function(a, b) {
+  sorter: function(a, b) {
     return b.label.length - a.label.length;
   },
 };
@@ -536,13 +536,21 @@ For backward compatibility, `<option placeholder>This is a placeholder</option>`
 
 **Usage:** 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.
 
-### itemComparer
+### valueComparer
 
 **Type:** `Function` **Default:** `strict equality`
 
 **Input types affected:** `select-one`, `select-multiple`
 
-**Usage:** 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).
+**Usage:** A custom compare function used when finding choices by value (using `setChoiceByValue`).
+
+**Example:**
+
+```js
+const example = new Choices(element, {
+  valueComparer: (a, b) => value.trim() === b.trim(),
+};
+```
 
 ### classNames
 

jsconfig.json

@@ -11,6 +11,7 @@
     "noUnusedLocals": true,
     "noUnusedParameters": true,
     "noImplicitReturns": true,
-    "noFallthroughCasesInSwitch": true
+    "noFallthroughCasesInSwitch": true,
+    "strictNullChecks": false
   }
 }

src/scripts/actions/choices.js

@@ -1,5 +1,13 @@
+/**
+ * @typedef {import('../../../types/index').Choices.Choice} Choice
+ */
+
 import { ACTION_TYPES } from '../constants';
 
+/**
+ * @argument {Choice} choice
+ * @returns {{ type: string } & Choice}
+ */
 export const addChoice = ({
   value,
   label,
@@ -23,16 +31,27 @@ export const addChoice = ({
   keyCode,
 });
 
+/**
+ * @argument {Choice[]} results
+ * @returns {{ type: string, results: Choice[] }}
+ */
 export const filterChoices = results => ({
   type: ACTION_TYPES.FILTER_CHOICES,
   results,
 });
 
+/**
+ * @argument {boolean} active
+ * @returns {{ type: string, active: boolean }}
+ */
 export const activateChoices = (active = true) => ({
   type: ACTION_TYPES.ACTIVATE_CHOICES,
   active,
 });
 
+/**
+ * @returns {{ type: string }}
+ */
 export const clearChoices = () => ({
   type: ACTION_TYPES.CLEAR_CHOICES,
 });

src/scripts/actions/groups.js

@@ -1,6 +1,14 @@
 import { ACTION_TYPES } from '../constants';
 
-export const addGroup = (value, id, active, disabled) => ({
+/**
+ * @typedef {import('../../../types/index').Choices.Group} Group
+ */
+
+/**
+ * @param {Group} group
+ * @returns {{ type: string } & Group}
+ */
+export const addGroup = ({ value, id, active, disabled }) => ({
   type: ACTION_TYPES.ADD_GROUP,
   value,
   id,

src/scripts/actions/groups.test.js

@@ -16,7 +16,7 @@ describe('actions/groups', () => {
         disabled,
       };
 
-      expect(actions.addGroup(value, id, active, disabled)).to.eql(
+      expect(actions.addGroup({ value, id, active, disabled })).to.eql(
         expectedAction,
       );
     });

src/scripts/actions/items.js

@@ -1,5 +1,13 @@
 import { ACTION_TYPES } from '../constants';
 
+/**
+ * @typedef {import('../../../types/index').Choices.Item} Item
+ */
+
+/**
+ * @param {Item} item
+ * @returns {{ type: string } & Item}
+ */
 export const addItem = ({
   value,
   label,
@@ -21,12 +29,22 @@ export const addItem = ({
   keyCode,
 });
 
+/**
+ * @param {string} id
+ * @param {string} choiceId
+ * @returns {{ type: string, id: string, choiceId: string }}
+ */
 export const removeItem = (id, choiceId) => ({
   type: ACTION_TYPES.REMOVE_ITEM,
   id,
   choiceId,
 });
 
+/**
+ * @param {string} id
+ * @param {boolean} highlighted
+ * @returns {{ type: string, id: string, highlighted: boolean }}
+ */
 export const highlightItem = (id, highlighted) => ({
   type: ACTION_TYPES.HIGHLIGHT_ITEM,
   id,

src/scripts/actions/items.test.js

@@ -9,8 +9,8 @@ describe('actions/items', () => {
       const id = '1234';
       const choiceId = '1234';
       const groupId = 'test';
-      const customProperties = 'test';
-      const placeholder = 'test';
+      const customProperties = { test: true };
+      const placeholder = true;
       const keyCode = 10;
 
       const expectedAction = {

src/scripts/actions/misc.js

@@ -1,8 +1,24 @@
+/**
+ * @returns {{ type: string }}
+ */
 export const clearAll = () => ({
   type: 'CLEAR_ALL',
 });
 
+/**
+ * @param {any} state
+ * @returns {{ type: string, state: object }}
+ */
 export const resetTo = state => ({
   type: 'RESET_TO',
   state,
 });
+
+/**
+ * @param {boolean} isLoading
+ * @returns {{ type: string, isLoading: boolean }}
+ */
+export const setIsLoading = isLoading => ({
+  type: 'SET_IS_LOADING',
+  isLoading,
+});

src/scripts/actions/misc.test.js

@@ -11,4 +11,40 @@ describe('actions/misc', () => {
       expect(actions.clearAll()).to.eql(expectedAction);
     });
   });
+
+  describe('resetTo action', () => {
+    it('returns RESET_TO action', () => {
+      const state = { test: true };
+      const expectedAction = {
+        type: 'RESET_TO',
+        state,
+      };
+
+      expect(actions.resetTo(state)).to.eql(expectedAction);
+    });
+  });
+
+  describe('setIsLoading action', () => {
+    describe('setting loading state to true', () => {
+      it('returns expected action', () => {
+        const expectedAction = {
+          type: 'SET_IS_LOADING',
+          isLoading: true,
+        };
+
+        expect(actions.setIsLoading(true)).to.eql(expectedAction);
+      });
+    });
+
+    describe('setting loading state to false', () => {
+      it('returns expected action', () => {
+        const expectedAction = {
+          type: 'SET_IS_LOADING',
+          isLoading: false,
+        };
+
+        expect(actions.setIsLoading(false)).to.eql(expectedAction);
+      });
+    });
+  });
 });