@financial-times/o-autocomplete 1.9.2 → 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +51 -39
- package/MIGRATION.md +18 -0
- package/README.md +157 -78
- package/demos/src/dynamic-custom-highlighted-suggestion/data.js +2098 -0
- package/demos/src/dynamic-custom-highlighted-suggestion/dynamic-custom-highlighted-suggestion.js +127 -0
- package/demos/src/dynamic-custom-highlighted-suggestion/dynamic-custom-highlighted-suggestion.mustache +14 -0
- package/demos/src/dynamic-custom-suggestion/dynamic-custom-suggestion.js +2 -1
- package/main.scss +51 -41
- package/origami.json +8 -0
- package/package.json +45 -51
- package/src/js/autocomplete.js +4 -7
- package/src/scss/_brand.scss +2 -2
- package/src/scss/_variables.scss +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,130 +1,142 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
-
## [
|
|
3
|
+
## [2.0.0](https://github.com/Financial-Times/origami/compare/o-autocomplete-v1.10.0...o-autocomplete-v2.0.0) (2025-02-20)
|
|
4
|
+
|
|
5
|
+
### ⚠ BREAKING CHANGES
|
|
6
|
+
|
|
7
|
+
This introduces a new design language and visually breaking changes. Including mobile optimised typography, icons, and buttons (see [MIGRATION.md](./MIGRATION.md)).
|
|
8
|
+
|
|
9
|
+
#### Origami 3: Principles, Purpose, and Impact
|
|
10
|
+
|
|
11
|
+
For anyone in P&T. We covered what’s new in Origami 3 (o3), why it matters, and what’s next.
|
|
12
|
+
|
|
13
|
+
[Slides](https://docs.google.com/presentation/d/1Qs8RHpMrDxxP5LyrVlnsUHnS3AriRK5-IboUeneRyMs/edit#slide=id.g764506c38c_0_357) | [Recording](https://drive.google.com/file/d/1OMW9zdTOEUvWyW1trsFqL3XhpTejYelO/view)
|
|
14
|
+
|
|
15
|
+
#### Origami 3: Bridging design & code
|
|
16
|
+
|
|
17
|
+
For designers and engineers alike. How to work with design guidelines, design foundations, and techniques for designer–engineer collaboration.
|
|
18
|
+
|
|
19
|
+
[Slides](https://docs.google.com/presentation/d/1pGBKFNv-g8RbY2g3SJ7v823XBI-MQqpjHrdgg9B6bzI/edit#slide=id.g764506c38c_0_357) | [Recording](https://drive.google.com/file/d/14hWVKM690arNEWROPHx9gmebnOUa6wlM/view)
|
|
4
20
|
|
|
21
|
+
#### Origami 3: Engineers’ Deep Dive
|
|
22
|
+
|
|
23
|
+
We got into the technical detail. Working with Origami CSS (no more Sass), custom elements, JSX templates, etc.
|
|
24
|
+
|
|
25
|
+
[Slides](https://docs.google.com/presentation/d/1s1S959CwZYnd0Q89EhsDFLFUuy2HZ9UnpBVaDHDFX7A/edit#slide=id.g3347c4befb5_0_402) | [Recording](https://drive.google.com/file/d/1hDtSN8Ce_P0Vr_dv0KXuXhs5Q9aHfvAp/view)
|
|
26
|
+
|
|
27
|
+
## [1.10.0](https://github.com/Financial-Times/origami/compare/o-autocomplete-v1.9.2...o-autocomplete-v1.10.0) (2024-04-19)
|
|
28
|
+
|
|
29
|
+
### Features
|
|
30
|
+
|
|
31
|
+
- Enable highlighting of custom suggestions ([#1516](https://github.com/Financial-Times/origami/issues/1516)) ([c326099](https://github.com/Financial-Times/origami/commit/c3260998c4a8926f875e7ba95134b230ca517669))
|
|
32
|
+
|
|
33
|
+
## [1.9.2](https://github.com/Financial-Times/origami/compare/o-autocomplete-v1.9.1...o-autocomplete-v1.9.2) (2024-04-12)
|
|
5
34
|
|
|
6
35
|
### Bug Fixes
|
|
7
36
|
|
|
8
|
-
|
|
37
|
+
- Update financial-times/accessible-autocomplete ([#1524](https://github.com/Financial-Times/origami/issues/1524)) ([8bcd024](https://github.com/Financial-Times/origami/commit/8bcd02402f3fa50e35756d3eb2a22b10435d634b))
|
|
9
38
|
|
|
10
39
|
## [1.9.1](https://github.com/Financial-Times/origami/compare/o-autocomplete-v1.9.0...o-autocomplete-v1.9.1) (2023-10-27)
|
|
11
40
|
|
|
12
|
-
|
|
13
41
|
### Bug Fixes
|
|
14
42
|
|
|
15
|
-
|
|
43
|
+
- Update node and npm ([c371fc3](https://github.com/Financial-Times/origami/commit/c371fc3f7f2d66266dbca95862ecef3ddeb1f339))
|
|
16
44
|
|
|
17
45
|
## [1.9.0](https://github.com/Financial-Times/origami/compare/o-autocomplete-v1.8.1...o-autocomplete-v1.9.0) (2023-09-08)
|
|
18
46
|
|
|
19
|
-
|
|
20
47
|
### Features
|
|
21
48
|
|
|
22
|
-
|
|
49
|
+
- Add an `autoselect` option ([c414db4](https://github.com/Financial-Times/origami/commit/c414db4780e8f74bffb25e9a04004c4d450077f4))
|
|
23
50
|
|
|
24
51
|
## [1.8.1](https://github.com/Financial-Times/origami/compare/o-autocomplete-v1.8.0...o-autocomplete-v1.8.1) (2023-08-25)
|
|
25
52
|
|
|
26
|
-
|
|
27
53
|
### Bug Fixes
|
|
28
54
|
|
|
29
|
-
|
|
55
|
+
- update o-typography dependency ([fb45b47](https://github.com/Financial-Times/origami/commit/fb45b47274241ea828f7dd50233441a76a215a51))
|
|
30
56
|
|
|
31
57
|
## [1.8.0](https://www.github.com/Financial-Times/origami/compare/o-autocomplete-v1.7.4...o-autocomplete-v1.8.0) (2023-05-30)
|
|
32
58
|
|
|
33
|
-
|
|
34
59
|
### Features
|
|
35
60
|
|
|
36
|
-
|
|
61
|
+
- autocomplete, add a suggestionTemplate override option ([23e1397](https://www.github.com/Financial-Times/origami/commit/23e1397deb29034faaf009c16e41ab169dcc3a42))
|
|
37
62
|
|
|
38
63
|
### [1.7.4](https://www.github.com/Financial-Times/origami/compare/o-autocomplete-v1.7.3...o-autocomplete-v1.7.4) (2023-04-28)
|
|
39
64
|
|
|
40
|
-
|
|
41
65
|
### Bug Fixes
|
|
42
66
|
|
|
43
|
-
|
|
67
|
+
- Require latest minor version of o-colors, o-buttons, and o-forms ([#1098](https://www.github.com/Financial-Times/origami/issues/1098)) ([b856ca6](https://www.github.com/Financial-Times/origami/commit/b856ca66c9ec555f3c70833ffa35cb05cd19841f))
|
|
44
68
|
|
|
45
69
|
### [1.7.3](https://www.github.com/Financial-Times/origami/compare/o-autocomplete-v1.7.2...o-autocomplete-v1.7.3) (2023-01-20)
|
|
46
70
|
|
|
47
|
-
|
|
48
71
|
### Bug Fixes
|
|
49
72
|
|
|
50
|
-
|
|
73
|
+
- ensure components depend on the latest o-normalise version ([e910236](https://www.github.com/Financial-Times/origami/commit/e910236454318ce1bf198a06da7e76c0893c9142))
|
|
51
74
|
|
|
52
75
|
### [1.7.2](https://www.github.com/Financial-Times/origami/compare/o-autocomplete-v1.7.1...o-autocomplete-v1.7.2) (2022-12-21)
|
|
53
76
|
|
|
54
|
-
|
|
55
77
|
### Bug Fixes
|
|
56
78
|
|
|
57
|
-
|
|
79
|
+
- require 3.3.0 or higher ([fc180c6](https://www.github.com/Financial-Times/origami/commit/fc180c619755daa1b7bfe65509f354cf0de113bf))
|
|
58
80
|
|
|
59
81
|
### [1.7.1](https://www.github.com/Financial-Times/origami/compare/o-autocomplete-v1.7.0...o-autocomplete-v1.7.1) (2022-12-08)
|
|
60
82
|
|
|
61
|
-
|
|
62
83
|
### Bug Fixes
|
|
63
84
|
|
|
64
|
-
|
|
85
|
+
- handle dynamic input changes when validating forms ([69ac478](https://www.github.com/Financial-Times/origami/commit/69ac4780922aded1dd4ce9b62b8437c454f0adba))
|
|
65
86
|
|
|
66
87
|
## [1.7.0](https://www.github.com/Financial-Times/origami/compare/o-autocomplete-v1.6.2...o-autocomplete-v1.7.0) (2022-09-14)
|
|
67
88
|
|
|
68
|
-
|
|
69
89
|
### Features
|
|
70
90
|
|
|
71
|
-
|
|
91
|
+
- autocomplete, add a `defaultValue` for a default input value ([#812](https://www.github.com/Financial-Times/origami/issues/812)) ([70a77ae](https://www.github.com/Financial-Times/origami/commit/70a77ae218c9c19967fe3bb32c18206d7cd9c2c3))
|
|
72
92
|
|
|
73
93
|
### [1.6.2](https://www.github.com/Financial-Times/origami/compare/o-autocomplete-v1.6.1...o-autocomplete-v1.6.2) (2022-04-21)
|
|
74
94
|
|
|
75
|
-
|
|
76
95
|
### Bug Fixes
|
|
77
96
|
|
|
78
|
-
|
|
97
|
+
- Adds basic existence checking to most module entry points ([#714](https://www.github.com/Financial-Times/origami/issues/714)) ([7ba3a61](https://www.github.com/Financial-Times/origami/commit/7ba3a61d0de2a32d3a27a225fd4258b3820c7bda))
|
|
79
98
|
|
|
80
99
|
### [1.6.1](https://www.github.com/Financial-Times/origami/compare/o-autocomplete-v1.6.0...o-autocomplete-v1.6.1) (2022-01-13)
|
|
81
100
|
|
|
82
|
-
|
|
83
101
|
### Bug Fixes
|
|
84
102
|
|
|
85
|
-
|
|
103
|
+
- expand all uses of docs to documentation ([26f8d9d](https://www.github.com/Financial-Times/origami/commit/26f8d9d8cbbe3e78902d8c3951b37e08150a77bd))
|
|
86
104
|
|
|
87
105
|
## [1.6.0](https://www.github.com/Financial-Times/origami/compare/o-autocomplete-v1.5.0...o-autocomplete-v1.6.0) (2021-12-09)
|
|
88
106
|
|
|
89
|
-
|
|
90
107
|
### Features
|
|
91
108
|
|
|
92
|
-
|
|
109
|
+
- support internal brand on o-autocomplete ([f519cf8](https://www.github.com/Financial-Times/origami/commit/f519cf8b668304ece9e0cc5e64940ad4295343ce))
|
|
93
110
|
|
|
94
111
|
## [1.5.0](https://www.github.com/Financial-Times/origami/compare/o-autocomplete-v1.4.1...o-autocomplete-v1.5.0) (2021-11-24)
|
|
95
112
|
|
|
96
|
-
|
|
97
113
|
### Features
|
|
98
114
|
|
|
99
|
-
|
|
115
|
+
- allow npm 8 in engines config ([eeb1cae](https://www.github.com/Financial-Times/origami/commit/eeb1cae6e7f0379e647f2b41240b1f294997d528))
|
|
100
116
|
|
|
101
117
|
### [1.4.1](https://www.github.com/Financial-Times/origami/compare/o-autocomplete-v1.4.0...o-autocomplete-v1.4.1) (2021-11-08)
|
|
102
118
|
|
|
103
|
-
|
|
104
119
|
### Bug Fixes
|
|
105
120
|
|
|
106
|
-
|
|
121
|
+
- pin components to latest o-brand, or greater ([3a6ccea](https://www.github.com/Financial-Times/origami/commit/3a6ccea1e838e4a2003322ca1f855d0b87b26b60))
|
|
107
122
|
|
|
108
123
|
## [1.4.0](https://www.github.com/Financial-Times/origami/compare/o-autocomplete-v1.3.2...o-autocomplete-v1.4.0) (2021-11-08)
|
|
109
124
|
|
|
110
|
-
|
|
111
125
|
### Features
|
|
112
126
|
|
|
113
|
-
|
|
127
|
+
- Rename master brand in component origami.json ([f642faf](https://www.github.com/Financial-Times/origami/commit/f642faf0574d84ea8185b56e6090c8015def27e6))
|
|
114
128
|
|
|
115
129
|
### [1.3.2](https://www.github.com/Financial-Times/origami/compare/o-autocomplete-v1.3.1...o-autocomplete-v1.3.2) (2021-11-02)
|
|
116
130
|
|
|
117
|
-
|
|
118
131
|
### Bug Fixes
|
|
119
132
|
|
|
120
|
-
|
|
121
|
-
|
|
133
|
+
- correct o-autocomplete markup ([f3d73b6](https://www.github.com/Financial-Times/origami/commit/f3d73b623d19bdfb7fac507cd40712d0032648fb))
|
|
134
|
+
- Update `o-brand` in components, replace "master" with "core" ([322617e](https://www.github.com/Financial-Times/origami/commit/322617ea80f30a6825d9c36872e05574b871ea82))
|
|
122
135
|
|
|
123
136
|
### [1.3.1](https://www.github.com/Financial-Times/origami/compare/o-autocomplete-v1.3.0...o-autocomplete-v1.3.1) (2021-09-21)
|
|
124
137
|
|
|
125
|
-
|
|
126
138
|
### Bug Fixes
|
|
127
139
|
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
140
|
+
- Add homepage, bugs and support email to the package.json ([6c0de60](https://www.github.com/Financial-Times/origami/commit/6c0de60ebd6e64c4dd16d000fcc6b79412ce30f4))
|
|
141
|
+
- update bugs urls ([3ea0ca0](https://www.github.com/Financial-Times/origami/commit/3ea0ca03bcb6e55142a77387ad0fff5ddf056d44))
|
|
142
|
+
- update origami json urls ([c757653](https://www.github.com/Financial-Times/origami/commit/c7576532b5a14f0462d5346dfb63238be025602e))
|
package/MIGRATION.md
ADDED
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
## Migration Guide
|
|
2
|
+
|
|
3
|
+
### Migrating from v1 to v2
|
|
4
|
+
|
|
5
|
+
This major release introduces a new design language and visually breaking changes. This includes mobile optimised typography, icons, and buttons. It also removes peer dependencies from deprecated "o2" components.
|
|
6
|
+
|
|
7
|
+
To upgrade, replace the following "o2" components with their "o3" equivalent:
|
|
8
|
+
|
|
9
|
+
- [o-normalise](../o-normalise/MIGRATION.md)
|
|
10
|
+
- [o-spacing](../o-spacing/MIGRATION.md)
|
|
11
|
+
- [o-colors](../o-colors/MIGRATION.md)
|
|
12
|
+
- [o-icons](../o-icons/MIGRATION.md)
|
|
13
|
+
- [o-buttons](../o-buttons/MIGRATION.md)
|
|
14
|
+
- [o-typography](../o-typography/MIGRATION.md)
|
|
15
|
+
- [o-editorial-typography](../o-editorial-typography/MIGRATION.md)
|
|
16
|
+
- [o-big-number](../o-big-number/MIGRATION.md)
|
|
17
|
+
- [o-quote](../o-quote/MIGRATION.md)
|
|
18
|
+
- [o-fonts](../o-fonts/MIGRATION.md)
|
package/README.md
CHANGED
|
@@ -4,18 +4,18 @@ An Origami component for autocomplete inputs. This is built on top of the excell
|
|
|
4
4
|
|
|
5
5
|
- [Usage](#usage)
|
|
6
6
|
- [Markup](#markup)
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
7
|
+
- [For a static set of suggestions](#for-a-static-set-of-suggestions)
|
|
8
|
+
- [For a dynamic set of suggestions](#for-a-dynamic-set-of-suggestions)
|
|
9
|
+
- [Use with o-forms](#use-with-o-forms)
|
|
10
10
|
- [Sass](#sass)
|
|
11
11
|
- [JavaScript](#javascript)
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
12
|
+
- [dynamic suggestions function](#dynamic-suggestions-function)
|
|
13
|
+
- [mapOptionToSuggestedValue](#mapoptiontosuggestedvalue)
|
|
14
|
+
- [onConfirm](#onconfirm)
|
|
15
15
|
- [Keyboard Support](#keyboard-support)
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
16
|
+
- [When focus is within the text input](#when-focus-is-within-the-text-input)
|
|
17
|
+
- [When focus is within the suggestions menu](#when-focus-is-within-the-suggestions-menu)
|
|
18
|
+
- [When focus is within the clear button](#when-focus-is-within-the-clear-button)
|
|
19
19
|
- [Migration](#migration)
|
|
20
20
|
- [Contact](#contact)
|
|
21
21
|
- [Licence](#licence)
|
|
@@ -33,11 +33,11 @@ To provide a static set of suggestions, we recommend using a `select` element. o
|
|
|
33
33
|
```html
|
|
34
34
|
<label for="my-autocomplete">Select your country</label>
|
|
35
35
|
<span data-o-component="o-autocomplete" class="o-autocomplete">
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
36
|
+
<select id="my-autocomplete">
|
|
37
|
+
<option value="fr">France</option>
|
|
38
|
+
<option value="de">Germany</option>
|
|
39
|
+
<option value="gb">United Kingdom</option>
|
|
40
|
+
</select>
|
|
41
41
|
</span>
|
|
42
42
|
```
|
|
43
43
|
|
|
@@ -46,9 +46,10 @@ To provide a static set of suggestions, we recommend using a `select` element. o
|
|
|
46
46
|
To provide a dynamic set of suggestions, provide a javascript function or name of a javascript function on the window object which follows the [dynamic-suggestions-function](#dynamic-suggestions-function) <abbr title="application programming interface">API</abbr>.
|
|
47
47
|
|
|
48
48
|
The input element requires an `id` attribute, this is used within the component to implement the accessibility features.
|
|
49
|
+
|
|
49
50
|
```html
|
|
50
51
|
<span data-o-component="o-autocomplete" class="o-autocomplete">
|
|
51
|
-
|
|
52
|
+
<input id="my-autocomplete" type="text" />
|
|
52
53
|
</span>
|
|
53
54
|
```
|
|
54
55
|
|
|
@@ -57,27 +58,29 @@ The input element requires an `id` attribute, this is used within the component
|
|
|
57
58
|
To have styling for labels, you will need to use [o-forms](https://registry.origami.ft.com/components/o-forms) as part of the autocomplete implementation.
|
|
58
59
|
|
|
59
60
|
Below is an example of how to combine o-forms and o-autocomplete components together. Note the `label` and `select` element are connected using `for` and `id` attributes.
|
|
61
|
+
|
|
60
62
|
```html
|
|
61
|
-
<span class="o-forms-field"
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
63
|
+
<span class="o-forms-field">
|
|
64
|
+
<label for="my-autocomplete" class="o-forms-title">
|
|
65
|
+
<span class="o-forms-title__main">Select your country</span>
|
|
66
|
+
</label>
|
|
67
|
+
<span class="o-forms-input o-forms-input--select">
|
|
68
|
+
<span data-o-component="o-autocomplete" class="o-autocomplete">
|
|
69
|
+
<select id="my-autocomplete">
|
|
70
|
+
<option value=""></option>
|
|
71
|
+
<option>Afghanistan</option>
|
|
72
|
+
</select>
|
|
73
|
+
</span>
|
|
74
|
+
</span>
|
|
73
75
|
</span>
|
|
74
76
|
```
|
|
77
|
+
|
|
75
78
|
## Sass
|
|
76
79
|
|
|
77
80
|
Use `@include oAutocomplete()` to include styles for all `o-autocomplete` features.
|
|
78
81
|
|
|
79
82
|
```scss
|
|
80
|
-
@import
|
|
83
|
+
@import '@financial-times/o-autocomplete/main';
|
|
81
84
|
|
|
82
85
|
@include oAutocomplete();
|
|
83
86
|
```
|
|
@@ -86,7 +89,7 @@ Use `@include oAutocomplete()` to include styles for all `o-autocomplete` featur
|
|
|
86
89
|
|
|
87
90
|
JavaScript is initialised automatically for [Origami Build Service](https://www.ft.com/__origami/service/build/v3/) users.
|
|
88
91
|
|
|
89
|
-
If your project is using a manual build process, initialise
|
|
92
|
+
If your project is using a manual build process, initialise `o-autocomplete` manually.
|
|
90
93
|
For example call the `init` method to initialise all `o-autocomplete` instances in the document:
|
|
91
94
|
|
|
92
95
|
```js
|
|
@@ -98,9 +101,12 @@ Or pass an element to initialise a specific `o-autocomplete` instance:
|
|
|
98
101
|
|
|
99
102
|
```js
|
|
100
103
|
import oAutocomplete from 'o-autocomplete';
|
|
101
|
-
const oAutocompleteElement = document.getElementById(
|
|
104
|
+
const oAutocompleteElement = document.getElementById(
|
|
105
|
+
'my-o-autocomplete-element'
|
|
106
|
+
);
|
|
102
107
|
new oAutocomplete(oAutocompleteElement);
|
|
103
108
|
```
|
|
109
|
+
|
|
104
110
|
### dynamic suggestions function
|
|
105
111
|
|
|
106
112
|
#### Example
|
|
@@ -117,15 +123,17 @@ import oAutocomplete from 'o-autocomplete';
|
|
|
117
123
|
* @param {string} query - Text which was typed into the autocomplete by the user
|
|
118
124
|
* @param {PopulateOptions} populateOptions - Function to call when ready to update the suggestions dropdown
|
|
119
125
|
* @returns {void}
|
|
120
|
-
*/
|
|
126
|
+
*/
|
|
121
127
|
async function customSuggestions(query, populateOptions) {
|
|
122
128
|
const suggestions = await getSuggestions(query);
|
|
123
129
|
populateOptions(suggestions);
|
|
124
130
|
}
|
|
125
131
|
|
|
126
|
-
const oAutocompleteElement = document.getElementById(
|
|
132
|
+
const oAutocompleteElement = document.getElementById(
|
|
133
|
+
'my-o-autocomplete-element'
|
|
134
|
+
);
|
|
127
135
|
new oAutocomplete(oAutocompleteElement, {
|
|
128
|
-
|
|
136
|
+
source: customSuggestions,
|
|
129
137
|
});
|
|
130
138
|
```
|
|
131
139
|
|
|
@@ -135,20 +143,20 @@ If wanting to supply dynamic suggestions, you will need to provide a function wh
|
|
|
135
143
|
|
|
136
144
|
#### (query, suggestionsCallback) ⇒ <code>void</code>
|
|
137
145
|
|
|
138
|
-
| Param
|
|
139
|
-
|
|
|
140
|
-
| query
|
|
146
|
+
| Param | Type | Description |
|
|
147
|
+
| ------------------- | -------------------------------------------------------- | ---------------------------------------------------------- |
|
|
148
|
+
| query | <code>string</code> | Text which was typed into the text input |
|
|
141
149
|
| suggestionsCallback | [<code>suggestionsCallback</code>](#suggestionsCallback) | Function to call when ready to update the suggestions menu |
|
|
142
150
|
|
|
143
151
|
<a name="suggestionsCallback"></a>
|
|
144
152
|
|
|
145
153
|
#### suggestionsCallback : <code>function</code>
|
|
146
|
-
**Properties**
|
|
147
154
|
|
|
148
|
-
|
|
149
|
-
| --- | --- | --- |
|
|
150
|
-
| options | <code>Array.<*></code> | The options which match the entered query |
|
|
155
|
+
**Properties**
|
|
151
156
|
|
|
157
|
+
| Name | Type | Description |
|
|
158
|
+
| ------- | ----------------------------- | ----------------------------------------- |
|
|
159
|
+
| options | <code>Array.<\*></code> | The options which match the entered query |
|
|
152
160
|
|
|
153
161
|
### mapOptionToSuggestedValue
|
|
154
162
|
|
|
@@ -157,7 +165,6 @@ If the `source` function is returning an array of strings which are already suit
|
|
|
157
165
|
|
|
158
166
|
The most common scenario which requires having to define a `mapOptionToSuggestedValue` function is when the `source` function is returning an array of objects, where one of the properties in the object should be used as the suggestion.
|
|
159
167
|
|
|
160
|
-
|
|
161
168
|
#### Example
|
|
162
169
|
|
|
163
170
|
```js
|
|
@@ -171,25 +178,28 @@ async function customSuggestions(query, populateOptions) {
|
|
|
171
178
|
/**
|
|
172
179
|
* @param {{"suggestionText": string}} option - The option to transform into a suggestion string
|
|
173
180
|
* @returns {string} The string to display as the suggestions for this option
|
|
174
|
-
*/
|
|
181
|
+
*/
|
|
175
182
|
function mapOptionToSuggestedValue(option) {
|
|
176
183
|
return option.suggestionText;
|
|
177
184
|
}
|
|
178
185
|
|
|
179
|
-
const oAutocompleteElement = document.getElementById(
|
|
186
|
+
const oAutocompleteElement = document.getElementById(
|
|
187
|
+
'my-o-autocomplete-element'
|
|
188
|
+
);
|
|
180
189
|
new oAutocomplete(oAutocompleteElement, {
|
|
181
|
-
|
|
182
|
-
|
|
190
|
+
mapOptionToSuggestedValue,
|
|
191
|
+
source: customSuggestions,
|
|
183
192
|
});
|
|
184
193
|
```
|
|
185
194
|
|
|
186
195
|
<a name="MapOptionToSuggestedValue"></a>
|
|
187
196
|
|
|
188
197
|
#### MapOptionToSuggestedValue ⇒ <code>string</code>
|
|
198
|
+
|
|
189
199
|
**Returns**: <code>string</code> - The string to display as the suggestions for this option
|
|
190
200
|
|
|
191
|
-
| Param
|
|
192
|
-
|
|
|
201
|
+
| Param | Type | Description |
|
|
202
|
+
| ------ | --------------- | ------------------------------------------------ |
|
|
193
203
|
| option | <code>\*</code> | The option to transform into a suggestion string |
|
|
194
204
|
|
|
195
205
|
### onConfirm
|
|
@@ -229,17 +239,20 @@ new oAutocomplete(oAutocompleteElement, {
|
|
|
229
239
|
});
|
|
230
240
|
```
|
|
231
241
|
|
|
232
|
-
|
|
233
242
|
### suggestionTemplate
|
|
234
243
|
|
|
235
244
|
This function is used to override the default rendering of suggestion items, with a function that returns a custom HTML string for the given option.
|
|
236
245
|
|
|
237
246
|
It is typically used when wanting to provide additional context or styling for each suggestion item.
|
|
238
247
|
|
|
248
|
+
The `query` value (text which was typed into the autocomplete text input field by the user) is provided so that it can be used as a basis for highlighting the `option` value (or one of its values if it is an object).
|
|
249
|
+
|
|
239
250
|
:warning: **Caution:** because this function allows you to output arbitrary HTML, you should [make sure it's trusted](https://en.wikipedia.org/wiki/Cross-site_scripting), and accessible. The HTML will be output within listbox options, so [ensure all descendants are presentational](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/option_role#all_descendants_are_presentational).
|
|
240
251
|
|
|
241
252
|
#### Example
|
|
242
253
|
|
|
254
|
+
Providing additional context by displaying multiple `option` properties:
|
|
255
|
+
|
|
243
256
|
```js
|
|
244
257
|
import oAutocomplete from 'o-autocomplete';
|
|
245
258
|
|
|
@@ -250,6 +263,7 @@ async function customSuggestions(query, populateOptions) {
|
|
|
250
263
|
|
|
251
264
|
/**
|
|
252
265
|
* @param {{"name": string, "role": string}} option - The option to transform into a suggestion
|
|
266
|
+
* @param {string} [query] - Text which was typed into the autocomplete text input field by the user
|
|
253
267
|
* @returns {string} The HTML to render in the suggestion list*/
|
|
254
268
|
function suggestionTemplate(option) {
|
|
255
269
|
return `
|
|
@@ -260,21 +274,84 @@ function suggestionTemplate(option) {
|
|
|
260
274
|
`;
|
|
261
275
|
}
|
|
262
276
|
|
|
263
|
-
const oAutocompleteElement = document.getElementById(
|
|
277
|
+
const oAutocompleteElement = document.getElementById(
|
|
278
|
+
'my-o-autocomplete-element'
|
|
279
|
+
);
|
|
264
280
|
new oAutocomplete(oAutocompleteElement, {
|
|
265
|
-
|
|
266
|
-
|
|
281
|
+
suggestionTemplate,
|
|
282
|
+
source: customSuggestions,
|
|
283
|
+
});
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
Using the `query` value to apply highlighting to one of the `option` properties:
|
|
287
|
+
|
|
288
|
+
```js
|
|
289
|
+
import oAutocomplete from 'o-autocomplete';
|
|
290
|
+
|
|
291
|
+
async function customSuggestions(query, populateOptions) {
|
|
292
|
+
const suggestions = await getSuggestions(query);
|
|
293
|
+
populateOptions(suggestions);
|
|
294
|
+
}
|
|
295
|
+
|
|
296
|
+
function highlightSuggestion(suggestion, query) {
|
|
297
|
+
const result = suggestion.split('');
|
|
298
|
+
|
|
299
|
+
const matchIndex = suggestion
|
|
300
|
+
.toLocaleLowerCase()
|
|
301
|
+
.indexOf(query.toLocaleLowerCase());
|
|
302
|
+
return result.map(function (character, index) {
|
|
303
|
+
let shouldHighlight = true;
|
|
304
|
+
const hasMatched = matchIndex > -1;
|
|
305
|
+
const characterIsWithinMatch =
|
|
306
|
+
index >= matchIndex && index <= matchIndex + query.length - 1;
|
|
307
|
+
if (hasMatched && characterIsWithinMatch) {
|
|
308
|
+
shouldHighlight = false;
|
|
309
|
+
}
|
|
310
|
+
return [character, shouldHighlight];
|
|
311
|
+
});
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
/**
|
|
315
|
+
* @param {{"name": string, "role": string}} option - The option to transform into a suggestion
|
|
316
|
+
* @param {string} [query] - Text which was typed into the autocomplete text input field by the user
|
|
317
|
+
* @returns {string} The HTML to render in the suggestion list*/
|
|
318
|
+
function suggestionTemplate(option, query) {
|
|
319
|
+
const characters = highlightSuggestion(option.name, query || option.name);
|
|
320
|
+
|
|
321
|
+
let output = '';
|
|
322
|
+
for (const [character, shoudHighlight] of characters) {
|
|
323
|
+
if (shoudHighlight) {
|
|
324
|
+
output += `<span class="o-autocomplete__option--highlight">${character}</span>`;
|
|
325
|
+
} else {
|
|
326
|
+
output += `${character}`;
|
|
327
|
+
}
|
|
328
|
+
}
|
|
329
|
+
output += ` (${option.role})`;
|
|
330
|
+
const span = document.createElement('span');
|
|
331
|
+
span.setAttribute('aria-label', option.name);
|
|
332
|
+
span.innerHTML = output;
|
|
333
|
+
return span.outerHTML;
|
|
334
|
+
}
|
|
335
|
+
|
|
336
|
+
const oAutocompleteElement = document.getElementById(
|
|
337
|
+
'my-o-autocomplete-element'
|
|
338
|
+
);
|
|
339
|
+
new oAutocomplete(oAutocompleteElement, {
|
|
340
|
+
suggestionTemplate,
|
|
341
|
+
source: customSuggestions,
|
|
267
342
|
});
|
|
268
343
|
```
|
|
269
344
|
|
|
270
345
|
<a name="SuggestionTemplate"></a>
|
|
271
346
|
|
|
272
347
|
#### SuggestionTemplate ⇒ <code>string</code>
|
|
348
|
+
|
|
273
349
|
**Returns**: <code>string</code> - The HTML string to render as the suggestion for this option
|
|
274
350
|
|
|
275
|
-
| Param
|
|
276
|
-
|
|
|
277
|
-
| option | <code>\*</code>
|
|
351
|
+
| Param | Type | Description |
|
|
352
|
+
| ------ | ------------------- | ----------------------------------------------------------------------- |
|
|
353
|
+
| option | <code>\*</code> | The option to transform into a suggestion |
|
|
354
|
+
| query | <code>string</code> | Text which was typed into the autocomplete text input field by the user |
|
|
278
355
|
|
|
279
356
|
### onConfirm
|
|
280
357
|
|
|
@@ -317,8 +394,8 @@ new oAutocomplete(oAutocompleteElement, {
|
|
|
317
394
|
|
|
318
395
|
#### onConfirm ⇒ <code>void</code>
|
|
319
396
|
|
|
320
|
-
| Param
|
|
321
|
-
|
|
|
397
|
+
| Param | Type | Description |
|
|
398
|
+
| ------ | --------------- | ---------------------------- |
|
|
322
399
|
| option | <code>\*</code> | The option the user selected |
|
|
323
400
|
|
|
324
401
|
#### `defaultValue` (default: `''`)
|
|
@@ -333,40 +410,42 @@ _When progressively enhancing a [static set of suggestions](#for-a-static-set-of
|
|
|
333
410
|
|
|
334
411
|
### When focus is within the text input
|
|
335
412
|
|
|
336
|
-
Key|Function
|
|
337
|
-
|
|
338
|
-
Down Arrow | If the suggestions menu is displayed, moves focus to the first suggested value in the suggestions menu.
|
|
339
|
-
Enter
|
|
340
|
-
Escape
|
|
413
|
+
| Key | Function |
|
|
414
|
+
| ---------- | ------------------------------------------------------------------------------------------------------- |
|
|
415
|
+
| Down Arrow | If the suggestions menu is displayed, moves focus to the first suggested value in the suggestions menu. |
|
|
416
|
+
| Enter | If the suggestions menu is displayed, does nothing. |
|
|
417
|
+
| Escape | If the suggestions menu is displayed, closes it. |
|
|
341
418
|
|
|
342
419
|
### When focus is within the suggestions menu
|
|
343
420
|
|
|
344
|
-
Key|Function
|
|
345
|
-
|
|
346
|
-
Enter
|
|
347
|
-
Tab
|
|
348
|
-
Space
|
|
349
|
-
Up Arrow
|
|
350
|
-
Down Arrow
|
|
351
|
-
Backspace
|
|
352
|
-
Printable Characters | <ul><li>Moves focus to the text input.</li><li>Types the characters into the text input.</li></ul>
|
|
421
|
+
| Key | Function |
|
|
422
|
+
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
423
|
+
| Enter | <ul><li>Sets the text input value to the content of the focused option in the suggestions menu.</li><li>Closes the suggestions menu.</li><li>Sets focus on the text input.</li></ul> |
|
|
424
|
+
| Tab | <ul><li>Sets the text input value to the content of the focused option in the suggestions menu.</li><li>Closes the suggestions menu.</li><li>Sets focus on the clear button.</li></ul> |
|
|
425
|
+
| Space | <ul><li>Sets the text input value to the content of the focused option in the suggestions menu.</li><li>Closes the suggestions menu.</li><li>Sets focus on the text input.</li></ul> |
|
|
426
|
+
| Up Arrow | If focus is on the first option, returns focus to the text input. Otherwise, moves focus to and selects the previous option in the suggestions menu. |
|
|
427
|
+
| Down Arrow | If focus is on the last option, does nothing. Otherwise, moves focus to and selects the next option in the suggestions menu. |
|
|
428
|
+
| Backspace | Returns focus to the text input and deletes the character prior to the cursor |
|
|
429
|
+
| Printable Characters | <ul><li>Moves focus to the text input.</li><li>Types the characters into the text input.</li></ul> |
|
|
353
430
|
|
|
354
431
|
### When focus is within the clear button
|
|
355
432
|
|
|
356
|
-
Key|Function
|
|
357
|
-
|
|
358
|
-
Enter | <ul><li>Moves focus to the text input.</li><li>Removes all the characters within the text input.</li></ul>
|
|
359
|
-
Space | <ul><li>Moves focus to the text input.</li><li>Removes all the characters within the text input.</li></ul>
|
|
360
|
-
|
|
433
|
+
| Key | Function |
|
|
434
|
+
| ----- | ---------------------------------------------------------------------------------------------------------- |
|
|
435
|
+
| Enter | <ul><li>Moves focus to the text input.</li><li>Removes all the characters within the text input.</li></ul> |
|
|
436
|
+
| Space | <ul><li>Moves focus to the text input.</li><li>Removes all the characters within the text input.</li></ul> |
|
|
361
437
|
|
|
362
438
|
## Migration
|
|
363
439
|
|
|
364
|
-
State
|
|
365
|
-
|
|
366
|
-
|
|
440
|
+
| State | Major Version | Last Minor Release | Migration guide |
|
|
441
|
+
| :----------: | :-----------: | :----------------: | :---------------------------------------------------: |
|
|
442
|
+
| ⚠ maintained | 3 | n/a | [migrate to v2](MIGRATION.md#migrating-from-v1-to-v2) |
|
|
443
|
+
| ⚠ maintained | 1 | 1.10 | N/A |
|
|
367
444
|
|
|
368
445
|
## Contact
|
|
446
|
+
|
|
369
447
|
If you have any questions or comments about this component, or need help using it, please either [raise an issue](https://github.com/Financial-Times/o-autocomplete/issues), visit [##origami-support](https://financialtimes.slack.com/messages/#origami-support/) or email [origami.support@ft.com](mailto:origami.support@ft.com).
|
|
370
448
|
|
|
371
449
|
## Licence
|
|
450
|
+
|
|
372
451
|
This software is published by the Financial Times under the [MIT licence](http://opensource.org/licenses/MIT).
|