Merge pull request #240 from CrowdStrike/make-autocomplete-@noResults…

…Text-required chore: make Autocomplete `@noResultsText` required
CrowdStrike · Jul 27, 2023 · d877163 · d877163
2 parents 99b6635 + 48cb710
commit d877163
Show file tree

Hide file tree

Showing 11 changed files with 247 additions and 90 deletions.
diff --git a/.changeset/tough-planets-raise.md b/.changeset/tough-planets-raise.md
@@ -0,0 +1,6 @@
+---
+'@crowdstrike/ember-toucan-core': minor
+'@crowdstrike/ember-toucan-form': minor
+---
+
+Make Autocomplete `@noResultsText` required.
diff --git a/docs/components/autocomplete-field/index.md b/docs/components/autocomplete-field/index.md
@@ -16,6 +16,7 @@ Provide a string to the `@label` component argument or content to the `:label` n
 <Form::Fields::Autocomplete
   @label='Label'
   @error={{this.errorMessage}}
+  @noResultsText='No results'
   @onChange={{this.onChange}}
   as |autocomplete|
 >
@@ -30,6 +31,27 @@ Provide a string to the `@label` component argument or content to the `:label` n
 ```hbs
 <Form::Fields::Autocomplete
   @error={{this.errorMessage}}
+  @noResultsText='No results'
+  @onChange={{this.onChange}}
+  placeholder='Colors'
+  as |autocomplete|
+>
+  <:label>Here is a label <IconButton><Tooltip /><IconButton></:label>
+
+  <autocomplete.Option @label="Blue" @value="blue" />
+</Form::Fields::Autocomplete>
+```
+
+## No results text
+
+Required.
+
+`@noResultsText` is shown when there are no results after filtering. 
+
+```hbs
+<Form::Fields::Autocomplete
+  @error={{this.errorMessage}}
+  @noResultsText='No results'
   @onChange={{this.onChange}}
   placeholder='Colors'
   as |autocomplete|
@@ -55,6 +77,7 @@ Provide a string to the `@hint` component argument or content to `:hint` named b
   @label='Label'
   @hint='Here is a hint'
   @error={{this.errorMessage}}
+  @noResultsText='No results'
   @onChange={{this.onChange}}
   as |autocomplete|
 >
@@ -70,6 +93,7 @@ Provide a string to the `@hint` component argument or content to `:hint` named b
 <Form::Fields::Autocomplete
   @label='Label'
   @error={{this.errorMessage}}
+  @noResultsText='No results'
   @onChange={{this.onChange}}
   as |autocomplete|
 >
@@ -96,6 +120,7 @@ Provide a string or array of strings to `@error` to render the text into the Err
 <Form::Fields::Autocomplete
   @label='Label'
   @error={{(array 'Error 1' 'Error 2')}}
+  @noResultsText='No results'
   @onChange={{this.onChange}}
   as |autocomplete|
 >
@@ -107,12 +132,15 @@ Provide a string or array of strings to `@error` to render the text into the Err
 
 ## `@onChange`
 
+Optional.
+
 Provide an `@onChange` callback to be notified when the user's selections have changed.
 `@onChange` will receive the value as its only argument.
 
 ```hbs
 <Form::Fields::Autocomplete
   @label='Label'
+  @noResultsText='No results'
   @onChange={{this.onChange}}
   as |autocomplete|
 >
@@ -136,10 +164,14 @@ export default class extends Component {
 
 ## Disabled State
 
+Optional.
+
 Set the `@isDisabled` argument to disable the input.
 
 ## Read Only State
 
+Optional.
+
 Set the `@isReadOnly` argument to put the input in the read only state.
 
 ## Attributes and Modifiers
@@ -156,7 +188,7 @@ This test selector will be used as the value for the `data-root-field` attribute
 The Field can be targeted via:
 
 ```hbs
-<Form::Fields::Autocomplete @label='Label' @rootTestSelector='example' />
+<Form::Fields::Autocomplete @label='Label' @noResultsText='No results' @rootTestSelector='example' />
 ```
 
 ```js
@@ -182,7 +214,7 @@ Target the error block via `data-error`.
 ### autocompleteField with `@label`
 
 <div class='mb-4 w-64'>
-  <Form::Fields::Autocomplete @label='Label' placeholder='Colors' />
+  <Form::Fields::Autocomplete @noResultsText='No results' @label='Label' placeholder='Colors' />
 </div>
 
 ### autocompleteField with `@label` and `@hint`
@@ -191,14 +223,15 @@ Target the error block via `data-error`.
   <Form::Fields::Autocomplete
     @label='Label'
     @hint='With hint text'
+    @noResultsText='No results'
     placeholder='Colors'
   />
 </div>
 
 ### autocompleteField with `:label` and `:hint` blocks
 
 <div class='mb-4 w-64'>
-  <Form::Fields::Autocomplete placeholder='Colors'>
+  <Form::Fields::Autocomplete @noResultsText='No results' placeholder='Colors'>
     <:label>Label <svg class="inline w-4 h-4" xmlns="http://www.w3.org/2000/svg" width="24" height="24" stroke="currentColor" viewBox="0 0 24 24"><path d="M12 3a9 9 0 11-6.364 2.636A8.972 8.972 0 0112 3zm0 4.7v5.2m0 3.39v.01" fill="none" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"></path></svg></:label>
     <:hint>Hint text <a href="https://www.crowdstrike.com/">link</a></:hint>
     <:default as |autocomplete|>
@@ -215,6 +248,7 @@ Target the error block via `data-error`.
   <Form::Fields::Autocomplete
     @label='Label'
     @error='With error text'
+    @noResultsText='No results'
     placeholder='Colors'
   />
 </div>
@@ -226,6 +260,7 @@ Target the error block via `data-error`.
     @label='Label'
     @hint='With hint text'
     @error='With error text'
+    @noResultsText='No results'
     placeholder='Colors'
   />
 </div>
@@ -236,6 +271,7 @@ Target the error block via `data-error`.
   <Form::Fields::Autocomplete
     @label='Label'
     @isDisabled={{true}}
+    @noResultsText='No results'
     placeholder='Colors'
   />
 </div>
@@ -248,6 +284,7 @@ Target the error block via `data-error`.
     @isDisabled={{true}}
     @selected="blue"
     @options={{(array 'blue' 'red')}}
+    @noResultsText='No results'
     placeholder='Colors'
   as |autocomplete|>
     <autocomplete.Option>
@@ -263,6 +300,7 @@ Target the error block via `data-error`.
     @label='Label'
     @options={{(array 'blue' 'red')}}
     @error={{(array 'With error 1' 'With error 2' 'With error 3')}}
+    @noResultsText='No results'
     placeholder='Colors'
   as |autocomplete|>
     <autocomplete.Option>
@@ -278,6 +316,7 @@ Target the error block via `data-error`.
     @label='Label'
     @hint='With hint text'
     @isReadOnly={{true}}
+    @noResultsText='No results'
   />
 </div>
 
@@ -289,6 +328,7 @@ Target the error block via `data-error`.
     @isReadOnly={{true}}
     @selected="blue"
     @options={{(array 'blue' 'red')}}
+    @noResultsText='No results'
     placeholder='Colors'
   as |autocomplete|>
     <autocomplete.Option>

diff --git a/docs/components/autocomplete/index.md b/docs/components/autocomplete/index.md
@@ -3,8 +3,30 @@
 Provides a Toucan-styled autocomplete with filtering.
 If you are building forms, you may be interested in the [AutocompleteField](./autocomplete-field) component instead.
 
+## No results text
+
+Required.
+
+`@noResultsText` is shown when there are no results after filtering. 
+
+```hbs
+<Form::Controls::Autocomplete
+  @noResultsText='No results'
+  @options={{this.options}}
+  @selected={{this.selected}}
+  as |autocomplete|
+>
+  <autocomplete.Option>
+    <!-- The content of each popover list item will be rendered here -->
+    {{autocomplete.option}}
+  </autocomplete.Option>
+</Form::Controls::Autocomplete>
+```
+
 ## Popover z-index
 
+Optional.
+
 A CSS class to add to this component's content container. Commonly used to specify a `z-index`.
 
 ```hbs
@@ -13,10 +35,13 @@ A CSS class to add to this component's content container. Commonly used to speci
 
 ## Options
 
+Optional.
+
 `@options` forms the content of this component. 
 
 ```hbs
 <Form::Controls::Autocomplete
+  @noResultsText='No results'
   @options={{this.options}}
   @selected={{this.selected}}
   as |autocomplete|
@@ -30,10 +55,13 @@ A CSS class to add to this component's content container. Commonly used to speci
 
 ## Selected
 
+Optional.
+
 The currently selected option.
 
 ```hbs
 <Form::Controls::Autocomplete
+  @noResultsText='No results'
   @options={{this.options}}
   @selected={{this.selected}}
   as |autocomplete|
@@ -56,11 +84,14 @@ export default class extends Component {
 
 ## onChange
 
+Optional.
+
 Called when the user makes a selection. It is called with the selected option (derived from `@options`) as its only argument. You'll want to update `@selected` with the new value in your on change handler.
 
 ```hbs
 <Form::Controls::Autocomplete
-  @onChange={{this.handleChange}}
+  @noResultsText='No results'
+  @onChange={{this.onChange}}
   @options={{this.options}}
   @selected={{this.selected}}
   as |autocomplete|
@@ -82,7 +113,7 @@ export default class extends Component {
   options = ['Blue', 'Red', 'Yellow'];
 
   @action
-  handleChange(option) {
+  onChange(option) {
     this.selected = option;
   }
 }
@@ -92,12 +123,15 @@ export default class extends Component {
 
 Optional.
 
-By default, when `@options` are an array of strings, the built-in filtering does simple `startsWith` filtering. When `@options` are an array of objects, the same filtering logic applies, but the key of each object is determined by the provided `@optionKey`. There may be cases where you need to write your own filtering logic completely that is more complex than the built-in `startsWith` filtering described. To do so, leverage `@onFilter` instead. This function should return an array of items that will then be used to populate the dropdown results.
+By default, when `@options` are an array of strings, the built-in filtering does simple `String.prototype.startsWith` filtering. 
+There may be cases where you need to write your own filtering logic completely that is more complex than the built-in `String.prototype.startsWith` filtering described. 
+To do so, leverage `@onFilter` instead. This function should return an array of items that will then be used to populate the dropdown results.
 
 ```hbs
 <Form::Controls::Autocomplete
-  @onFilter={{this.handleFilter}}
-  @onChange={{this.handleChange}}
+  @noResultsText='No results'
+  @onFilter={{this.onFilter}}
+  @onChange={{this.onChange}}
   @options={{this.options}}
   @selected={{this.selected}}
   as |autocomplete|
@@ -148,19 +182,21 @@ export default class extends Component {
   ];
 
   @action
-  handleChange(option) {
+  onChange(option) {
     this.selected = option;
   }
 
   @action
-  handleFilter(value) {
+  onFilter(value) {
     return this.options.filter((option) => option === value);
   }
 }
 ```
 
 ## Disabled State
 
+Optional.
+
 Set the `@isDisabled` argument to disable the input.
 
 ```hbs
@@ -169,6 +205,8 @@ Set the `@isDisabled` argument to disable the input.
 
 ## Read Only State
 
+Optional.
+
 Set the `@isReadOnly` argument to put the input in the read only state.
 
 ```hbs
@@ -177,6 +215,8 @@ Set the `@isReadOnly` argument to put the input in the read only state.
 
 ## Error State
 
+Optional.
+
 Set the `@hasError` argument to apply an error box shadow to the `<input>`.
 
 ```hbs