feat: added EsAutocomplete

[ericdouglaspratt]

🔗 Linked issue

• https://energysage.atlassian.net/browse/CEO-683

❓ Type of change

• 📖 Documentation (updates to the documentation or readme)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality like performance)
• ✨ New feature (a non-breaking change that adds functionality)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

• There's a lot here, because this PR accomplishes several things:
  • Added EsAutocomplete, broken into subcomponents and utilities for easier separation of concerns
  • Satisfies the full screen takeover requirement for mobile (using Reka UI's Dialog) with a separate subcomponent
  • Splits some of the concerns (e.g. animation, mobile choreography, showing only enough rows there's space for, etc.) into separate composables or utils
  • Added Vitest for unit tests
• On focus outline behavior:
  • Our inputs do not currently comply with the "sufficient contrast" accessibility requirements for a focus outline
  • There is also a browser limitation on inputs where they cannot show a focus outline only on :focus-visible when tabbed to via keyboard - either they show one when it has focus of any kind, or they don't show one
  • Because of this, I chose to have a focus outline on the autocomplete whenever the input has focus
  • We will likely need to move to a similar approach for all of our other inputs for consistency and to meet the contrast requirement, but that's outside the scope of this PR
• On animation and motion design:
  • The motion design for the autocomplete was created to solve for the as-of-yet undocumented principle that "everything should clearly come from somewhere; nothing should just pop into existence or disappear" - this is especially important for users who are less familiar with technology or cognitively impaired so when things appear or go away, it is clear where they came from, where they went, and to what part of the UI they are associated
  • On desktop, the suggestions pane slides out of and back into the input, and animates its height change whenever the number of suggestions changes
  • On mobile, the fullscreen takeover is made less jarring by animating the input from its position on the page up to its position in the takeover, and back into place on the page when closed
  • All animation respects the reduce motion setting
• Started off making use of Reka UI's alpha Autocomplete primitives but eventually moved away from it because (a) it's marked as being in "alpha" mode so its API may be unreliable, and (b) I kept having to add workaround after workaround for various things, including to:
  • Override undesired focus and submit behavior
  • Ensure the suggestion list is DOM-adjacent to the input for accessibility rather than being portaled
  • Allow up/down arrows to cycle through the list of suggestions and go back to the input
  • Fix over-repetition in VoiceOver readouts
• Expected limitations:
  • In VoiceOver mode, when the suggestions pane is brought up and then you navigate to the next elements on the page outside of the autocomplete without making a selection, the suggestions pane does not close until the next focusable page element (e.g. a link or input) receives focus. This is a VoiceOver limitation that Google, Amazon, and other sites with autocompletes also face, as the last-focused element technically retains focus until the next focusable element gets it, even if the VoiceOver reading cursor has moved on.

Desktop simple example

Desktop address example (inverted behavior)

Mobile address example (fullscreen takeover open)

🥼 Testing

• Tested locally at:
  • http://localhost:8500/molecules/autocomplete
  • http://localhost:8500/examples/form-field-validation (this one shows integration with Vuelidate)
• Also tested mobile behavior and VoiceOver on iPhone at:
  • https://design.energysage.dev/molecules/autocomplete

🧐 Feedback Requested / Focus Areas

• Overall

📝 Checklist

• I have verified accessibility of any new components by:
  • automated check with the WAVE browser extension
  • navigating by keyboard
  • using with a screen reader (e.g. VoiceOver on Safari)
• I have updated any applicable documentation.