`Form.Autosuggest` error states and freeform text

[brian-smith-tcril]

originally posted on slack

when handling the error state, it's not quite clear what the intended behavior is if you click into a control and immediately click/tab out, you will get the "Error, no selected value" text however, if text is entered and then deleted there is no error message there is also no error message if text is entered that doesn't match anything in the dropdown (for example, typing "foo" in any of the sample boxes) i didn't see any issue reported on github, so i wasn't sure if this was working as intended or not

while investigating this, i noticed an oddity with handleClickOutside

https://github.com/openedx/paragon/blob/81f746f104b873802ae7655747ac6f4b3c1a7c5f/src/Form/FormAutosuggest.jsx#L111-L121

being called even when clicking inside the control, which makes sense because it's added as a listener here

https://github.com/openedx/paragon/blob/81f746f104b873802ae7655747ac6f4b3c1a7c5f/src/Form/FormAutosuggest.jsx#L137-L145

i also looked into how other autosuggest components handle error states

with https://mui.com/material-ui/react-autocomplete/ there are ways to configure the component to allow/prevent arbitrary text (see https://mui.com/material-ui/react-autocomplete/#controlled-states and https://mui.com/material-ui/react-autocomplete/#controlled-states)

it's not clear how much of this functionality is desired, and what the scope of this component should be

blocked by https://github.com/openedx/paragon/issues/2510

### Tasks
- [ ] Error state appropriately updates based on if the component input matches 
- [ ] Interactive docs example for allowing/not allowing a unmatched value with correct error message

[brian-smith-tcril]

after discussion in the paragon working group meeting, moving forward we should:

• allow configuring the component to allow freeform text or not
• display error state based on if freeform text is allowed or not

edit: more notes from meeting notes

Questions:

• What is the intended behavior for the error state?
  • The Figma specs (here and here) define what the error state should look like, but doesn’t really define when the error should appear.
• Free text or should it only support selection from limited list of items in the dropdown (configurable).
• “Feels like the component isn't fully defined”

Notes:

• When is it in error state. Needs figma spec.
• Refer to Mature Autocomplete library for understanding edge cases of behavior (e.g., material).
• [A11y] A form field with nothing in it is not an error, but yes on blur.
• Ideally configure to allow or not allow freeform text as an option

[adamstankiewicz]

Thanks for bringing the next steps back into this issue, @brian-smith-tcril :)

[brian-smith-tcril]

It seems this is mostly well enough defined for work, but it'd be good to get a little extra clarification on how to handle error states. We have noted

display error state based on if freeform text is allowed or not

and

[A11y] A form field with nothing in it is not an error, but yes on blur.

so if I'm understanding this correctly, once the user has left the control

required field	allows freeform	entered value	error state?
no	yes	nothing	no error
yes	yes	nothing	error
no	yes	freeform	no error
yes	yes	freeform	no error
no	yes	selected	no error
yes	yes	selected	no error
no	no	nothing	no error
yes	no	nothing	error
no	no	freeform	error (with helper text noting the user must select a value, not just type one in)
yes	no	freeform	error (with helper text noting the user must select a value, not just type one in)
no	no	selected	no error
yes	no	selected	no error

[brian-smith-tcril]

Discussed in the Paragon WG https://openedx.atlassian.net/wiki/spaces/BPL/pages/3819765775/2023-07-19+Meeting+notes

Implement different error states when no options match the entered text vs when there are options that match the entered text but none were selected.

In the context of the field not being required, the suggestion was to recommend clearing the input when no options match, and choosing a selection when there are valid options.

[brian-smith-tcril]

re:

there is also no error message if text is entered that doesn't match anything in the dropdown (for example, typing "foo" in any of the sample boxes)

it seems this is happening because of state.dropDownItems.length > 0 in https://github.com/openedx/paragon/blob/13b7488f495dfe260811fe3a8d0565929713b10b/src/Form/FormAutosuggest.jsx#L115

if state.dropDownItems.length > 0 is removed and the line is changed to

if (parentRef.current && !parentRef.current.contains(e.target)) {

error states appear on multiple autosuggest components on the docs page. This implies that state.dropDownItems.length > 0 is being used to mean "this is the autosuggest compoent the user is interacting with right now." In the case where we have entered text that filters the dropdownitems down to zero, the component behaves as if it is not the one the user is interacting with, and doesn't show an error.

edit: made this into its own issue https://github.com/openedx/paragon/issues/2510