Merge pull request #20 from mynamesleon/8-create-option

8 create option

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 All notable changes to this project will be documented in this file.
 
-## [1.2.0] - 2020-10-30
+## [1.2.0] - 2020-10-31
 
 ### Added
 
@@ -13,8 +13,9 @@ All notable changes to this project will be documented in this file.
 -   the function usage of the `source` option can now take a Promise which resolves with the items to render, instead of having to use the provided second argument callback
 -   `onAsyncBeforeSend` callback option, to allow adjustments to the xhr object before it is sent (e.g. adding auth headers)
 -   `onAsyncComplete` callback option, that fires after async call successfully completes and all items have rendered
--   `srAutoClear` option that takes a boolean, or number, to allow a delay before automatically clearing the screen reader announcement element
+-   `srAutoClear` option that takes a boolean, or number, to allow a delay before automatically clearing the screen reader announcement element - defaults to 5 seconds
 -   `deleteAllControl` and `deleteAllText` options to render a button enabling quick deletion of all selected items (when there are at least 2 selected items)
+-   `create` option to allow adding a results entry for the current search text (if no exact results match is found)
 -   for all async related callbacks, and when the `source` is a function, there is now an additional final param that indicates if it is the first/starting call.
 -   the selected items in multiple mode, and the show all button, will now have their `aria-describedby` set to link them to the control label
 
@@ -24,6 +25,7 @@ All notable changes to this project will be documented in this file.
 -   in multiple mode, when deleting a selected item by clicking it or using enter, move focus to the next available selected item
 -   set the `aria-describedby` attribute on the list container to reference the control's
 -   do not hide the list when focus moves from the input to the show all control
+-   moved the screen reader announcement element to be before the generated input, so that if users navigate past the input, they will not encounter the announcement element out of context
 
 ### Fixed
 
@@ -32,6 +34,7 @@ All notable changes to this project will be documented in this file.
 -   Added a workaround for an IE11 bug where the options were shown on load if the `minLength` was set to 0 on a multi-select autocomplete with starting values. This was due to the input's placeholder being removed, which erroneously triggers the `input` event in IE11.
 -   Edge case errors when destroying the component immediately after certain actions (such as selecting an item, or blurring off of the component).
 -   In multiple mode, moved the selected items to be after the list to fix issue on mobile when navigating by swipe, as it was possible to reach the selected items first, causing the list to disappear.
+-   Issue with `confirmOnBlur` option not working correctly when a results option did not currently have focus.
 
 ## [1.1.4] - 2020-07-05
 

README.md

@@ -89,7 +89,10 @@ The full list of options, and their defaults:
     /**
      * Specify source. See examples file for more specific usage.
      * @example ['Afghanistan', 'Albania', 'Algeria', ...more]
+     * @example [{ label: 'Afghanistan', value: 'AFG' }, ...more]
+     * @example 'https://some-endpoint.somewhere/available'
      * @example (query, render, isFirstCall) => render(arrayToUse)
+     * @example (query) => async () => arrayToUse
      */
     source: string[] | any[] | string | Function;
 
@@ -104,6 +107,12 @@ The full list of options, and their defaults:
      */
     alsoSearchIn: string[] = [];
 
+    /**
+     * If no exact match is found,
+     * create an entry in the options list for the current search text
+     */
+    create: boolean | ((value: string) => string | object) = false;
+
     /**
      * Input delay after typing before running a search
      */
@@ -215,9 +224,9 @@ The full list of options, and their defaults:
 
     /**
      * Automatically clear the screen reader announcement element after the specified delay
-     * Defaults to 2 seconds if true
+     * Number is in milliseconds. If true, defaults to 5000.
      */
-    srAutoClear: boolean | number = false;
+    srAutoClear: boolean | number = 5000;
 
     /**
      * Screen reader text used in multiple mode for element deletion.

dist/index.d.ts

@@ -1,9 +1,10 @@
 export interface IAriaAutocompleteOptions {
     id?: string;
     name?: string;
-    source?: string | string[] | any[] | Function;
+    source?: string | string[] | any[] | Function | Promise<any[]>;
     sourceMapping?: any;
     alsoSearchIn?: string[];
+    create?: boolean | ((value: string) => string | any);
     delay?: number;
     minLength?: number;
     maxResults?: number;

index.html

@@ -254,7 +254,7 @@ <h3>1. Array as Source, using default options</h3>
                     </div>
                     <div class="tile" id="example-2">
                         <h3>2. Progressive Enhancement, using Element(s) as Source</h3>
-                        <p><b>(With multi-select, autogrow, results limit, and show all control)</b></p>
+                        <p><b>(With result creation, multi-select, autogrow, results limit, and show all control)</b></p>
                         <label for="countrylist-select">Select up to 5 countries</label>
                         <select id="countrylist-select" multiple="">
                             <option value=''>Please select</option><option value='AFG'>Afghanistan</option><option value='ALB'>Albania</option><option value='DZA'>Algeria</option><option value='ASM'>American Samoa</option><option value='AND'>Andorra</option><option value='AGO'>Angola</option><option value='AIA'>Anguilla</option><option value='ATA'>Antarctica</option><option value='ATG'>Antigua and Barbuda</option><option value='ARG'>Argentina</option><option value='ARM'>Armenia</option><option value='ABW'selected>Aruba</option><option value='AUS'>Australia</option><option value='AUT'>Austria</option><option value='AZE'>Azerbaijan</option><option value='BHS'>Bahamas (the)</option><option value='BHR'>Bahrain</option><option value='BGD'>Bangladesh</option><option value='BRB'>Barbados</option><option value='BLR'>Belarus</option><option value='BEL'>Belgium</option><option value='BLZ'>Belize</option><option value='BEN'>Benin</option><option value='BMU'>Bermuda</option><option value='BTN'>Bhutan</option><option value='BOL'>Bolivia (Plurinational State of)</option><option value='BES'>Bonaire, Sint Eustatius and Saba</option><option value='BIH'>Bosnia and Herzegovina</option><option value='BWA'>Botswana</option><option value='BVT'>Bouvet Island</option><option value='BRA'>Brazil</option><option value='IOT'>British Indian Ocean Territory (the)</option><option value='BRN'>Brunei Darussalam</option><option value='BGR'>Bulgaria</option><option value='BFA'>Burkina Faso</option><option value='BDI'>Burundi</option><option value='CPV'>Cabo Verde</option><option value='KHM'>Cambodia</option><option value='CMR'>Cameroon</option><option value='CAN'>Canada</option><option value='CYM'>Cayman Islands (the)</option><option value='CAF'>Central African Republic (the)</option><option value='TCD'>Chad</option><option value='CHL'>Chile</option><option value='CHN'>China</option><option value='CXR'>Christmas Island</option><option value='CCK'>Cocos (Keeling) Islands (the)</option><option value='COL'>Colombia</option><option value='COM'>Comoros (the)</option><option value='COD'>Congo (the Democratic Republic of the)</option><option value='COG'>Congo (the)</option><option value='COK'>Cook Islands (the)</option><option value='CRI'>Costa Rica</option><option value='HRV'>Croatia</option><option value='CUB'>Cuba</option><option value='CUW'>Curaçao</option><option value='CYP'>Cyprus</option><option value='CZE'>Czechia</option><option value='CIV'>Côte d'Ivoire</option><option value='DNK'>Denmark</option><option value='DJI'>Djibouti</option><option value='DMA'>Dominica</option><option value='DOM'>Dominican Republic (the)</option><option value='ECU'>Ecuador</option><option value='EGY'>Egypt</option><option value='SLV'>El Salvador</option><option value='GNQ'>Equatorial Guinea</option><option value='ERI'>Eritrea</option><option value='EST'>Estonia</option><option value='SWZ'>Eswatini</option><option value='ETH'>Ethiopia</option><option value='FLK'>Falkland Islands (the) [Malvinas]</option><option value='FRO'>Faroe Islands (the)</option><option value='FJI'>Fiji</option><option value='FIN'>Finland</option><option value='FRA'>France</option><option value='GUF'>French Guiana</option><option value='PYF'>French Polynesia</option><option value='ATF'>French Southern Territories (the)</option><option value='GAB'>Gabon</option><option value='GMB'>Gambia (the)</option><option value='GEO'>Georgia</option><option value='DEU'>Germany</option><option value='GHA'>Ghana</option><option value='GIB'>Gibraltar</option><option value='GRC'>Greece</option><option value='GRL'>Greenland</option><option value='GRD'>Grenada</option><option value='GLP'>Guadeloupe</option><option value='GUM'>Guam</option><option value='GTM'>Guatemala</option><option value='GGY'>Guernsey</option><option value='GIN'>Guinea</option><option value='GNB'>Guinea-Bissau</option><option value='GUY'>Guyana</option><option value='HTI'>Haiti</option><option value='HMD'>Heard Island and McDonald Islands</option><option value='VAT'>Holy See (the)</option><option value='HND'>Honduras</option><option value='HKG'>Hong Kong</option><option value='HUN'>Hungary</option><option value='ISL'>Iceland</option><option value='IND'>India</option><option value='IDN'>Indonesia</option><option value='IRN'>Iran (Islamic Republic of)</option><option value='IRQ'>Iraq</option><option value='IRL'>Ireland</option><option value='IMN'>Isle of Man</option><option value='ISR'>Israel</option><option value='ITA'>Italy</option><option value='JAM'>Jamaica</option><option value='JPN'>Japan</option><option value='JEY'>Jersey</option><option value='JOR'>Jordan</option><option value='KAZ'>Kazakhstan</option><option value='KEN'>Kenya</option><option value='KIR'>Kiribati</option><option value='PRK'>Korea (the Democratic People's Republic of)</option><option value='KOR'>Korea (the Republic of)</option><option value='KWT'>Kuwait</option><option value='KGZ'>Kyrgyzstan</option><option value='LAO'>Lao People's Democratic Republic (the)</option><option value='LVA'>Latvia</option><option value='LBN'>Lebanon</option><option value='LSO'>Lesotho</option><option value='LBR'>Liberia</option><option value='LBY'>Libya</option><option value='LIE'>Liechtenstein</option><option value='LTU'>Lithuania</option><option value='LUX'>Luxembourg</option><option value='MAC'>Macao</option><option value='MDG'>Madagascar</option><option value='MWI'>Malawi</option><option value='MYS'>Malaysia</option><option value='MDV'>Maldives</option><option value='MLI'>Mali</option><option value='MLT'>Malta</option><option value='MHL'>Marshall Islands (the)</option><option value='MTQ'>Martinique</option><option value='MRT'>Mauritania</option><option value='MUS'>Mauritius</option><option value='MYT'>Mayotte</option><option value='MEX'>Mexico</option><option value='FSM'>Micronesia (Federated States of)</option><option value='MDA'>Moldova (the Republic of)</option><option value='MCO'>Monaco</option><option value='MNG'>Mongolia</option><option value='MNE'>Montenegro</option><option value='MSR'>Montserrat</option><option value='MAR'>Morocco</option><option value='MOZ'>Mozambique</option><option value='MMR'>Myanmar</option><option value='NAM'>Namibia</option><option value='NRU'>Nauru</option><option value='NPL'>Nepal</option><option value='NLD'>Netherlands (the)</option><option value='NCL'>New Caledonia</option><option value='NZL'>New Zealand</option><option value='NIC'>Nicaragua</option><option value='NER'>Niger (the)</option><option value='NGA'>Nigeria</option><option value='NIU'>Niue</option><option value='NFK'>Norfolk Island</option><option value='MNP'>Northern Mariana Islands (the)</option><option value='NOR'>Norway</option><option value='OMN'>Oman</option><option value='PAK'>Pakistan</option><option value='PLW'>Palau</option><option value='PSE'>Palestine, State of</option><option value='PAN'>Panama</option><option value='PNG'>Papua New Guinea</option><option value='PRY'>Paraguay</option><option value='PER'>Peru</option><option value='PHL'>Philippines (the)</option><option value='PCN'>Pitcairn</option><option value='POL'>Poland</option><option value='PRT'>Portugal</option><option value='PRI'>Puerto Rico</option><option value='QAT'>Qatar</option><option value='MKD'>Republic of North Macedonia</option><option value='ROU'>Romania</option><option value='RUS'>Russian Federation (the)</option><option value='RWA'>Rwanda</option><option value='REU'>Réunion</option><option value='BLM'>Saint Barthélemy</option><option value='SHN'>Saint Helena, Ascension and Tristan da Cunha</option><option value='KNA'>Saint Kitts and Nevis</option><option value='LCA'>Saint Lucia</option><option value='MAF'>Saint Martin (French part)</option><option value='SPM'>Saint Pierre and Miquelon</option><option value='VCT'>Saint Vincent and the Grenadines</option><option value='WSM'>Samoa</option><option value='SMR'>San Marino</option><option value='STP'>Sao Tome and Principe</option><option value='SAU'>Saudi Arabia</option><option value='SEN'>Senegal</option><option value='SRB'>Serbia</option><option value='SYC'>Seychelles</option><option value='SLE'>Sierra Leone</option><option value='SGP'>Singapore</option><option value='SXM'>Sint Maarten (Dutch part)</option><option value='SVK'>Slovakia</option><option value='SVN'>Slovenia</option><option value='SLB'>Solomon Islands</option><option value='SOM'>Somalia</option><option value='ZAF'>South Africa</option><option value='SGS'>South Georgia and the South Sandwich Islands</option><option value='SSD'>South Sudan</option><option value='ESP'>Spain</option><option value='LKA'selected>Sri Lanka</option><option value='SDN'>Sudan (the)</option><option value='SUR'>Suriname</option><option value='SJM'>Svalbard and Jan Mayen</option><option value='SWE'>Sweden</option><option value='CHE'>Switzerland</option><option value='SYR'>Syrian Arab Republic</option><option value='TWN'>Taiwan (Province of China)</option><option value='TJK'>Tajikistan</option><option value='TZA'>Tanzania, United Republic of</option><option value='THA'>Thailand</option><option value='TLS'>Timor-Leste</option><option value='TGO'>Togo</option><option value='TKL'>Tokelau</option><option value='TON'>Tonga</option><option value='TTO'>Trinidad and Tobago</option><option value='TUN'>Tunisia</option><option value='TUR'>Turkey</option><option value='TKM'>Turkmenistan</option><option value='TCA'>Turks and Caicos Islands (the)</option><option value='TUV'>Tuvalu</option><option value='UGA'>Uganda</option><option value='UKR'>Ukraine</option><option value='ARE'>United Arab Emirates (the)</option><option value='GBR'>United Kingdom of Great Britain and Northern Ireland (the)</option><option value='UMI'>United States Minor Outlying Islands (the)</option><option value='USA'>United States of America (the)</option><option value='URY'>Uruguay</option><option value='UZB'>Uzbekistan</option><option value='VUT'>Vanuatu</option><option value='VEN'>Venezuela (Bolivarian Republic of)</option><option value='VNM'>Viet Nam</option><option value='VGB'>Virgin Islands (British)</option><option value='VIR'>Virgin Islands (U.S.)</option><option value='WLF'>Wallis and Futuna</option><option value='ESH'>Western Sahara</option><option value='YEM'>Yemen</option><option value='ZMB'>Zambia</option><option value='ZWE'>Zimbabwe</option><option value='ALA'>Åland Islands</option>
@@ -266,6 +266,7 @@ <h3>2. Progressive Enhancement, using Element(s) as Source</h3>
                                 showAllControl: true,
                                 autoGrow: true,
                                 maxResults: 50,
+                                create: true,
                                 minLength: 0,
                                 maxItems: 5
                             });
@@ -276,16 +277,18 @@ <h3>2. Progressive Enhancement, using Element(s) as Source</h3>
     showAllControl: true,
     autoGrow: true,
     maxResults: 50,
+    create: true,
     minLength: 0,
     maxItems: 5
 });</code></pre>
                         <p>If the <code>source</code> option is falsy, or is an empty Array, the autocomplete will check to see if the element used is a <code>&lt;select&gt;</code>, or if there are any checkboxes inside the element, and will build up a <code>source</code> Array from what's available.</p>
                         <p>This example uses a <code>&lt;select&gt;</code> element; so when an option in the autocomplete is selected (or removed), the corresponding <code>&lt;option&gt;</code> element will also be selected (or deselected) as well.</p>
-                        <p>Any pre-selected <code>&lt;option&gt;</code> or checkbox elements are respected, and the <code>multiple</code> option will also be set to <code>true</code> automatically if the <code>&lt;select&gt;</code> has that attribute set; if checkboxes are used, the <code>multiple</code> option will always be set to <code>true</code>.</p>
+                        <p>Any pre-selected <code>&lt;option&gt;</code> or checkbox elements are respected, and the <code>multiple</code> option will also be set to <code>true</code> automatically if the <code>&lt;select&gt;</code> has that attribute set. If checkboxes are used, the <code>multiple</code> option will always be set to <code>true</code>.</p>
+                        <p>When using the <code>create</code> option along with progressive enhancement, the created selections will be added to the original <code>&lt;select&gt;</code> element or checkbox list. So they will always remain as available options (both internally, and in the DOM) even after being de-selected.</p>
                     </div>
                     <div class="tile" id="example-3">
                         <h3>3. Function as Source</h3>
-                        <p><b>(With multi-select and delete all control, but without autogrow)</b></p>
+                        <p><b>(With delete all control and multi-select, but without autogrow)</b></p>
                         <p>If you use a Function for the <code>source</code> with your own filtering logic, it will be passed the search query, and a render Function, which expects an Array (using either of the formats mentioned above).</p>
                         <label for="countrylist-function">
                             Select up to 4 countries by country code
@@ -407,6 +410,8 @@ <h3>Core options</h3>
                                 <dd>Additional properties to use when searching for a match</dd>
                             </div>
                             <div>
+                                <dt>create: <code>boolean | Function</code></dt>
+                                <dd>If no exact match is found, create an entry in the results list for the current search text<br>Default: <code>false</code></dd>
                                 <dt>delay: <code>number</code></dt>
                                 <dd>input delay before running a search<br>Default: <code>100</code></dd>
                                 <dt>minLength: <code>number</code></dt>
@@ -467,7 +472,7 @@ <h3>Screen reader enhancements</h3>
                         <dl>
                             <div>
                                 <dt>srAutoClear: <code>boolean | number</code></dt>
-                                <dd>Automatically clear the screen reader announcement element after the specified delay. Defaults to 2 seconds if true<br>Default: <code>`false`</code></dd>
+                                <dd>Automatically clear the screen reader announcement element after the specified delay. Number is in milliseconds.<br>Default: <code>5000</code></dd>
                                 <dt>srDeleteText: <code>string</code></dt>
                                 <dd>In multi mode, screen reader text used for element deletion - prepended to label<br>Default: <code>`delete`</code></dd>
                                 <dt>srDeletedText: <code>string</code></dt>