From 50f9bacc5d36923efa137dd996afdd1601b50bb6 Mon Sep 17 00:00:00 2001 From: th3c0r Date: Sun, 2 Oct 2022 21:27:05 +0300 Subject: [PATCH 1/3] Add option to add aria-label attribute --- src/autoComplete.js | 1 + src/services/init.js | 1 + 2 files changed, 2 insertions(+) diff --git a/src/autoComplete.js b/src/autoComplete.js index 42760b5..7050368 100644 --- a/src/autoComplete.js +++ b/src/autoComplete.js @@ -24,6 +24,7 @@ import init from "./services/init"; * @param {Number} [config.threshold=1] - Minimum number of characters required in the input before triggering autocompletion. * @param {Number} [config.debounce=0] - Delay in milliseconds after input for autocompletion to start. * @param {Boolean} [config.wrapper=true] - Wraps the input element in a div for a11y purposes, adding some ARIA attributes. + * @param {String} [config.ariaLabel] - Adds the attribute aria-label to the wrapper if the wrapper option is true, otherwise to the input. * @param {(String|Function)} [config.searchEngine=strict] - "strict" checks if the given query is contained within the data, "loose" returns every result where every character in the query is present in the data in any order and location. Signature: (query: string, record: any), given the manipulated query input and each data.src array entry or for each entry[config.data.keys]. * @param {Boolean} [config.diacritics=false] - Enable to normalize query and data values using String.normalize and by removing u0300 through u036f. See {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize}. * @param {(Object|Boolean)} [config.resultsList] - false to disable result list rendering. diff --git a/src/services/init.js b/src/services/init.js index 92dcc4c..00d1d90 100644 --- a/src/services/init.js +++ b/src/services/init.js @@ -16,6 +16,7 @@ export default async function (ctx) { "aria-owns": resultsList.id, "aria-haspopup": true, "aria-expanded": false, + ...(ctx.ariaLabel && {"aria-label":ctx.ariaLabel}), }; // Set "input" attributes From 7a6dcf04fb0894a5eb1c2319945ca5dd8df5649d Mon Sep 17 00:00:00 2001 From: th3c0r Date: Tue, 4 Oct 2022 23:21:45 +0300 Subject: [PATCH 2/3] Modify docs --- docs/configuration.md | 182 ++++++++++++++++++++++++++++-------------- 1 file changed, 120 insertions(+), 62 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 34b8d00..d3fabd9 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -2,11 +2,11 @@ API configuration options, methods and events -*** +--- ## Options -*** +--- ### name (optional) @@ -21,11 +21,10 @@ API configuration options, methods and events name: "autoComplete", ``` -*** +--- ### selector (optional) - > Responsible for the input, textarea, or contentEditable element selection - Type: `String` of [selector](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors) | `Function` returns `Element` @@ -36,11 +35,13 @@ name: "autoComplete", #### ** String ** + ```js selector: "#autoComplete", // Any valid selector ``` #### ** Function ** + ```js selector: () => { return [Element]; // Any valid selector @@ -49,11 +50,10 @@ selector: () => { -*** +--- ### wrapper (optional) - > Responsible for rendering the `div` that wraps the `input` and the `list` element - Type: `Boolean` @@ -65,7 +65,22 @@ selector: () => { wrapper: false, ``` -*** +--- + +### ariaLabel (optional) + +> Adds the attribute aria-label to the wrapper if the wrapper option is true, otherwise to the input. + +- Type: `String` +- Default: `` + +##### Example + +```js +ariaLabel: 'Search Box', +``` + +--- ### data (required) @@ -76,19 +91,23 @@ wrapper: false, ##### Methods: #### `src` (required) + - Type: `Array`|`Function` returns `Array` of results values - Parameters: (`query`) (Only works if `data.cache` is `false`) - Default: `null` #### `keys` (required) + - Type: `Array` (Only required if `data.src` is `Array` of `Objects`) - Default: `null` #### `cache` (optional) + - Type: `Boolean` - Default: `false` #### `filter` (optional) + - Type: `Function` returns `Array` of results values - Parameters: (`list`) - Default: No action @@ -96,6 +115,7 @@ wrapper: false, ##### Example: + #### ** Array (Strings) ** ```js @@ -149,9 +169,10 @@ data: { keys: ["food"] }, ``` + -*** +--- ### trigger (optional) @@ -169,7 +190,7 @@ trigger: (query) => { }, ``` -*** +--- ### query (optional) @@ -187,7 +208,7 @@ query: (input) => { }, ``` -*** +--- ### placeHolder (optional) @@ -202,7 +223,7 @@ query: (input) => { placeHolder: "Search...", ``` -*** +--- ### threshold (optional) @@ -217,7 +238,7 @@ placeHolder: "Search...", threshold: 2, ``` -*** +--- ### debounce (optional) @@ -232,7 +253,7 @@ threshold: 2, debounce: 300, // Milliseconds value ``` -*** +--- ### searchEngine (optional) @@ -249,7 +270,7 @@ debounce: 300, // Milliseconds value searchEngine: "strict", ``` -*** +--- ### diacritics (optional) @@ -264,7 +285,7 @@ searchEngine: "strict", diacritics: true, ``` -*** +--- ### resultsList (optional) @@ -275,39 +296,48 @@ diacritics: true, ##### Methods: #### `tag` (optional) - - Type: `String` of html [tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element) - - Default: `ul` + +- Type: `String` of html [tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element) +- Default: `ul` #### `id` (optional) - - Type: `String` of id value - - Default: `autoComplete_list_[id]` + +- Type: `String` of id value +- Default: `autoComplete_list_[id]` #### `class` (optional) - - Type: `String` of class values - - Default: No classes + +- Type: `String` of class values +- Default: No classes #### `destination` (optional) - - Type: `String` of [selector](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors) | `Function` destination - - Default: `#autoComplete` + +- Type: `String` of [selector](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors) | `Function` destination +- Default: `#autoComplete` #### `position` (optional) + - Type: `String` of [position](https://developer.mozilla.org/en-US/docs/Web/API/Element/insertAdjacentElement#parameters) - Default: `afterend` #### `element` (optional) + - Type: `Function` with no return - Parameters: (`list`, `data`) - Default: `Function` #### `maxResults` (optional) + - Type: `Integer` - Default: `5` #### `tabSelect` (optional) + - Type: `Boolean` to enable/disable tab selection - Default: `false` #### `noResults` (optional) + - Type: `Boolean` to enable/disable list resistance in case of no results - Default: `false` @@ -328,7 +358,7 @@ resultsList: { }, ``` -*** +--- ### resultItem (optional) @@ -339,27 +369,33 @@ resultsList: { ##### Methods: #### `tag` (optional) + - Type: `String` of html [tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element) - Default: `li` #### `id` (optional) + - Type: `String` of id value - Default: `autoComplete_result_[index]` #### `class` (optional) + - Type: `String` of class values - Default: No classes #### `element` (optional) + - Type: `Function` with no return - Parameters: (`item`, `data`) - Default: `Function` #### `highlight` (optional) + - Type: `Boolean` | `String` of class values - Defaults: `false` #### `selected` (optional) + - Type: `String` of class values - Default: No classes @@ -377,7 +413,7 @@ resultItem: { }, ``` -*** +--- ### submit (optional) @@ -392,7 +428,7 @@ resultItem: { submit: true, ``` -*** +--- ### events (optional) @@ -422,12 +458,13 @@ events: { }, ``` -*** +--- ## APIs -*All examples assume that the "autoComplete" new instance is assigned to an "autoCompleteJS" named variable* -*** +_All examples assume that the "autoComplete" new instance is assigned to an "autoCompleteJS" named variable_ + +--- ### init() @@ -438,7 +475,7 @@ events: { 3. Creating new empty hidden `list` 4. Getting `data` if set to `cache` 5. Attaching all event listeners on the `events` list -6. Emitting `init` event +6. Emitting `init` event ##### Example: @@ -446,7 +483,7 @@ events: { autoCompleteJS.init(); ``` -*** +--- ### start(query) @@ -460,9 +497,11 @@ autoCompleteJS.init(); 6. Rendering `list` if enabled Arguments: + - query: `String` (optional) Defaults: + - query: `input` query value ##### Example: @@ -471,13 +510,14 @@ Defaults: autoCompleteJS.start("tea"); ``` -*** +--- ### search(query, record, options) > autoComplete.js powerful search engine Arguments: + - query: `String` - record: `String` - options: `Object` (optional) @@ -488,6 +528,7 @@ Arguments: - highlight: `Boolean` | `String` of class values Defaults: + - options: `Object` - mode: `"strict"` - diacritics: `false` @@ -500,10 +541,10 @@ autoCompleteJS.search(query, record, options); // Or -autoComplete.search(query, record, options) +autoComplete.search(query, record, options); ``` -*** +--- ### open() @@ -515,7 +556,7 @@ autoComplete.search(query, record, options) autoCompleteJS.open(); ``` -*** +--- ### next() @@ -527,7 +568,7 @@ autoCompleteJS.open(); autoCompleteJS.next(); ``` -*** +--- ### previous() @@ -539,16 +580,18 @@ autoCompleteJS.next(); autoCompleteJS.previous(); ``` -*** +--- ### goTo(index) > Navigates to a specific `resultItem` on the list by its `index` number Arguments: + - index: `Number` Defaults: + - index: No default value ##### Example: @@ -557,17 +600,18 @@ Defaults: autoCompleteJS.goTo(1); ``` - -*** +--- ### select(index) > Selects a `resultItem` from the list by its `index` number Arguments: + - index: `Number` (optional) Defaults: + - index: current cursor position ##### Example: @@ -576,7 +620,7 @@ Defaults: autoCompleteJS.select(1); ``` -*** +--- ### close() @@ -588,7 +632,7 @@ autoCompleteJS.select(1); autoCompleteJS.close(); ``` -*** +--- ### unInit() @@ -600,23 +644,25 @@ autoCompleteJS.close(); autoCompleteJS.unInit(); ``` -*** +--- ## Events ### init -*** +--- > Fires after `autoComplete.js` engine is initialized and ready - Example: ```js -document.querySelector("#autoComplete").addEventListener("init", function (event) { +document + .querySelector("#autoComplete") + .addEventListener("init", function (event) { // "event.detail" carries the returned data values console.log(event); -}); + }); ``` ### response @@ -626,13 +672,15 @@ document.querySelector("#autoComplete").addEventListener("init", function (event ##### Example: ```js -document.querySelector("#autoComplete").addEventListener("response", function (event) { +document + .querySelector("#autoComplete") + .addEventListener("response", function (event) { // "event.detail" carries the returned data values console.log(event.detail); -}); + }); ``` -*** +--- ### results @@ -641,13 +689,15 @@ document.querySelector("#autoComplete").addEventListener("response", function (e ##### Example: ```js -document.querySelector("#autoComplete").addEventListener("results", function (event) { +document + .querySelector("#autoComplete") + .addEventListener("results", function (event) { // "event.detail" carries the matching results values console.log(event.detail); -}); + }); ``` -*** +--- ### open @@ -656,13 +706,15 @@ document.querySelector("#autoComplete").addEventListener("results", function (ev ##### Example: ```js -document.querySelector("#autoComplete").addEventListener("open", function (event) { +document + .querySelector("#autoComplete") + .addEventListener("open", function (event) { // "event.detail" carries the autoComplete.js "feedback" object console.log(event.detail); -}); + }); ``` -*** +--- ### navigate @@ -671,13 +723,15 @@ document.querySelector("#autoComplete").addEventListener("open", function (event ##### Example: ```js -document.querySelector("#autoComplete").addEventListener("navigate", function (event) { +document + .querySelector("#autoComplete") + .addEventListener("navigate", function (event) { // "event.detail" carries the autoComplete.js "feedback" object console.log(event.detail); -}); + }); ``` -*** +--- ### selection @@ -686,13 +740,15 @@ document.querySelector("#autoComplete").addEventListener("navigate", function (e ##### Example: ```js -document.querySelector("#autoComplete").addEventListener("selection", function (event) { +document + .querySelector("#autoComplete") + .addEventListener("selection", function (event) { // "event.detail" carries the autoComplete.js "feedback" object console.log(event.detail); -}); + }); ``` -*** +--- ### close @@ -701,8 +757,10 @@ document.querySelector("#autoComplete").addEventListener("selection", function ( ##### Example: ```js -document.querySelector("#autoComplete").addEventListener("close", function (event) { +document + .querySelector("#autoComplete") + .addEventListener("close", function (event) { // "event.detail" carries the autoComplete.js "feedback" object console.log(event.detail); -}); + }); ``` From c481e15c793c45e0dd4b98751c06ece4cd3bf761 Mon Sep 17 00:00:00 2001 From: th3c0r Date: Sat, 15 Oct 2022 21:22:55 +0300 Subject: [PATCH 3/3] modify autoformatted markdown --- docs/configuration.md | 169 ++++++++++++++++-------------------------- 1 file changed, 63 insertions(+), 106 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index d3fabd9..9d49f09 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -2,11 +2,11 @@ API configuration options, methods and events ---- +*** ## Options ---- +*** ### name (optional) @@ -21,10 +21,11 @@ API configuration options, methods and events name: "autoComplete", ``` ---- +*** ### selector (optional) + > Responsible for the input, textarea, or contentEditable element selection - Type: `String` of [selector](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors) | `Function` returns `Element` @@ -35,13 +36,11 @@ name: "autoComplete", #### ** String ** - ```js selector: "#autoComplete", // Any valid selector ``` #### ** Function ** - ```js selector: () => { return [Element]; // Any valid selector @@ -50,10 +49,11 @@ selector: () => { ---- +*** ### wrapper (optional) + > Responsible for rendering the `div` that wraps the `input` and the `list` element - Type: `Boolean` @@ -65,7 +65,7 @@ selector: () => { wrapper: false, ``` ---- +*** ### ariaLabel (optional) @@ -80,7 +80,7 @@ wrapper: false, ariaLabel: 'Search Box', ``` ---- +*** ### data (required) @@ -91,23 +91,19 @@ ariaLabel: 'Search Box', ##### Methods: #### `src` (required) - - Type: `Array`|`Function` returns `Array` of results values - Parameters: (`query`) (Only works if `data.cache` is `false`) - Default: `null` #### `keys` (required) - - Type: `Array` (Only required if `data.src` is `Array` of `Objects`) - Default: `null` #### `cache` (optional) - - Type: `Boolean` - Default: `false` #### `filter` (optional) - - Type: `Function` returns `Array` of results values - Parameters: (`list`) - Default: No action @@ -115,7 +111,6 @@ ariaLabel: 'Search Box', ##### Example: - #### ** Array (Strings) ** ```js @@ -169,10 +164,9 @@ data: { keys: ["food"] }, ``` - ---- +*** ### trigger (optional) @@ -190,7 +184,7 @@ trigger: (query) => { }, ``` ---- +*** ### query (optional) @@ -208,7 +202,7 @@ query: (input) => { }, ``` ---- +*** ### placeHolder (optional) @@ -223,7 +217,7 @@ query: (input) => { placeHolder: "Search...", ``` ---- +*** ### threshold (optional) @@ -238,7 +232,7 @@ placeHolder: "Search...", threshold: 2, ``` ---- +*** ### debounce (optional) @@ -253,7 +247,7 @@ threshold: 2, debounce: 300, // Milliseconds value ``` ---- +*** ### searchEngine (optional) @@ -270,7 +264,7 @@ debounce: 300, // Milliseconds value searchEngine: "strict", ``` ---- +*** ### diacritics (optional) @@ -285,7 +279,7 @@ searchEngine: "strict", diacritics: true, ``` ---- +*** ### resultsList (optional) @@ -296,48 +290,39 @@ diacritics: true, ##### Methods: #### `tag` (optional) - -- Type: `String` of html [tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element) -- Default: `ul` + - Type: `String` of html [tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element) + - Default: `ul` #### `id` (optional) - -- Type: `String` of id value -- Default: `autoComplete_list_[id]` + - Type: `String` of id value + - Default: `autoComplete_list_[id]` #### `class` (optional) - -- Type: `String` of class values -- Default: No classes + - Type: `String` of class values + - Default: No classes #### `destination` (optional) - -- Type: `String` of [selector](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors) | `Function` destination -- Default: `#autoComplete` + - Type: `String` of [selector](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors) | `Function` destination + - Default: `#autoComplete` #### `position` (optional) - - Type: `String` of [position](https://developer.mozilla.org/en-US/docs/Web/API/Element/insertAdjacentElement#parameters) - Default: `afterend` #### `element` (optional) - - Type: `Function` with no return - Parameters: (`list`, `data`) - Default: `Function` #### `maxResults` (optional) - - Type: `Integer` - Default: `5` #### `tabSelect` (optional) - - Type: `Boolean` to enable/disable tab selection - Default: `false` #### `noResults` (optional) - - Type: `Boolean` to enable/disable list resistance in case of no results - Default: `false` @@ -358,7 +343,7 @@ resultsList: { }, ``` ---- +*** ### resultItem (optional) @@ -369,33 +354,27 @@ resultsList: { ##### Methods: #### `tag` (optional) - - Type: `String` of html [tag](https://developer.mozilla.org/en-US/docs/Web/HTML/Element) - Default: `li` #### `id` (optional) - - Type: `String` of id value - Default: `autoComplete_result_[index]` #### `class` (optional) - - Type: `String` of class values - Default: No classes #### `element` (optional) - - Type: `Function` with no return - Parameters: (`item`, `data`) - Default: `Function` #### `highlight` (optional) - - Type: `Boolean` | `String` of class values - Defaults: `false` #### `selected` (optional) - - Type: `String` of class values - Default: No classes @@ -413,7 +392,7 @@ resultItem: { }, ``` ---- +*** ### submit (optional) @@ -428,7 +407,7 @@ resultItem: { submit: true, ``` ---- +*** ### events (optional) @@ -458,13 +437,12 @@ events: { }, ``` ---- +*** ## APIs +*All examples assume that the "autoComplete" new instance is assigned to an "autoCompleteJS" named variable* -_All examples assume that the "autoComplete" new instance is assigned to an "autoCompleteJS" named variable_ - ---- +*** ### init() @@ -475,7 +453,7 @@ _All examples assume that the "autoComplete" new instance is assigned to an "aut 3. Creating new empty hidden `list` 4. Getting `data` if set to `cache` 5. Attaching all event listeners on the `events` list -6. Emitting `init` event +6. Emitting `init` event ##### Example: @@ -483,7 +461,7 @@ _All examples assume that the "autoComplete" new instance is assigned to an "aut autoCompleteJS.init(); ``` ---- +*** ### start(query) @@ -497,11 +475,9 @@ autoCompleteJS.init(); 6. Rendering `list` if enabled Arguments: - - query: `String` (optional) Defaults: - - query: `input` query value ##### Example: @@ -510,14 +486,13 @@ Defaults: autoCompleteJS.start("tea"); ``` ---- +*** ### search(query, record, options) > autoComplete.js powerful search engine Arguments: - - query: `String` - record: `String` - options: `Object` (optional) @@ -528,7 +503,6 @@ Arguments: - highlight: `Boolean` | `String` of class values Defaults: - - options: `Object` - mode: `"strict"` - diacritics: `false` @@ -541,10 +515,10 @@ autoCompleteJS.search(query, record, options); // Or -autoComplete.search(query, record, options); +autoComplete.search(query, record, options) ``` ---- +*** ### open() @@ -556,7 +530,7 @@ autoComplete.search(query, record, options); autoCompleteJS.open(); ``` ---- +*** ### next() @@ -568,7 +542,7 @@ autoCompleteJS.open(); autoCompleteJS.next(); ``` ---- +*** ### previous() @@ -580,18 +554,16 @@ autoCompleteJS.next(); autoCompleteJS.previous(); ``` ---- +*** ### goTo(index) > Navigates to a specific `resultItem` on the list by its `index` number Arguments: - - index: `Number` Defaults: - - index: No default value ##### Example: @@ -600,18 +572,17 @@ Defaults: autoCompleteJS.goTo(1); ``` ---- + +*** ### select(index) > Selects a `resultItem` from the list by its `index` number Arguments: - - index: `Number` (optional) Defaults: - - index: current cursor position ##### Example: @@ -620,7 +591,7 @@ Defaults: autoCompleteJS.select(1); ``` ---- +*** ### close() @@ -632,7 +603,7 @@ autoCompleteJS.select(1); autoCompleteJS.close(); ``` ---- +*** ### unInit() @@ -644,25 +615,23 @@ autoCompleteJS.close(); autoCompleteJS.unInit(); ``` ---- +*** ## Events ### init ---- +*** > Fires after `autoComplete.js` engine is initialized and ready - Example: ```js -document - .querySelector("#autoComplete") - .addEventListener("init", function (event) { +document.querySelector("#autoComplete").addEventListener("init", function (event) { // "event.detail" carries the returned data values console.log(event); - }); +}); ``` ### response @@ -672,15 +641,13 @@ document ##### Example: ```js -document - .querySelector("#autoComplete") - .addEventListener("response", function (event) { +document.querySelector("#autoComplete").addEventListener("response", function (event) { // "event.detail" carries the returned data values console.log(event.detail); - }); +}); ``` ---- +*** ### results @@ -689,15 +656,13 @@ document ##### Example: ```js -document - .querySelector("#autoComplete") - .addEventListener("results", function (event) { +document.querySelector("#autoComplete").addEventListener("results", function (event) { // "event.detail" carries the matching results values console.log(event.detail); - }); +}); ``` ---- +*** ### open @@ -706,15 +671,13 @@ document ##### Example: ```js -document - .querySelector("#autoComplete") - .addEventListener("open", function (event) { +document.querySelector("#autoComplete").addEventListener("open", function (event) { // "event.detail" carries the autoComplete.js "feedback" object console.log(event.detail); - }); +}); ``` ---- +*** ### navigate @@ -723,15 +686,13 @@ document ##### Example: ```js -document - .querySelector("#autoComplete") - .addEventListener("navigate", function (event) { +document.querySelector("#autoComplete").addEventListener("navigate", function (event) { // "event.detail" carries the autoComplete.js "feedback" object console.log(event.detail); - }); +}); ``` ---- +*** ### selection @@ -740,15 +701,13 @@ document ##### Example: ```js -document - .querySelector("#autoComplete") - .addEventListener("selection", function (event) { +document.querySelector("#autoComplete").addEventListener("selection", function (event) { // "event.detail" carries the autoComplete.js "feedback" object console.log(event.detail); - }); +}); ``` ---- +*** ### close @@ -757,10 +716,8 @@ document ##### Example: ```js -document - .querySelector("#autoComplete") - .addEventListener("close", function (event) { +document.querySelector("#autoComplete").addEventListener("close", function (event) { // "event.detail" carries the autoComplete.js "feedback" object console.log(event.detail); - }); +}); ```