Summary
TypeaheadSearch and its subcomponents were built as part of the Vue.js search project, for which the WVUI library was initially built. A lot has changed since it was built, including further developed library architecture and components, and new guiding principles for the shared library that include aiming for some level of MediaWiki-agnosticism (see T288380 for details).
There are various factors we should consider as we plan how to handle this component in the new library.
Considerations
Inclusion of TypeaheadSearch in the shared library
Is TypeaheadSearch meant to be a reusable component, or will it likely only ever be used in the header in Vector? Due to its complexity and how MediaWiki-specific parts of it are, if we believe it is unlikely to be reused, perhaps the top-level component doesn't belong in the shared library.
Component reuse
There are a few things to consider here:
- Relationship to Lookup: Lookup is similar in functionality (text input with autocomplete suggestions in a dropdown). One cannot discern the difference between these two components based on their names alone.
- Common menu behavior: TypeaheadSearch, Lookup, and Dropdown (and more) all have dropdown menus of options that become visible based on user action
- Reusability of TypeaheadSuggestion: TypeheadSuggestion is basically a card component that has already been reused in Related Articles. We may consider generalizing this component so it's no longer specific to TypeheadSearch.
MediaWiki-specific parts
There are several aspects of the TypeaheadSearch components that are MediaWiki-specific (Note: please edit this list if you see anything missing):
- Search client: API responses are expected in MediaWiki-specific formats:
- REST search client: this is the default SearchClient (see code)
- URL generator: a function to generate a URL for a suggestion can be passed into TypeaheadSuggestion as a prop, and a MediaWiki-specific default is provided (see code)
- UrlGenerator interface uses language specific to articles
- createDefaultUrlGenerator() is MediaWiki-specific
- MediaWiki-specific props and language:
We have a few options to deal with this:
- Don't include TypeaheadSearch in the library (but maybe include TypeaheadSuggestion under a more generic name)
- Include it as-is, but sequester it to a MediaWiki specific section in the code and in the docs, separate from truly agnostic components
- Include it, but remove MediaWiki-specific language and functionality, requiring that those things be housed in the codebase where the component is used (e.g. Vector) and provided as props to TypeaheadSearch
- Include it, but sequester MediaWiki-specific language and functionality to separate files/locations to clearly delineate the component from its MediaWiki-specific implementation. Sometimes the MediaWiki-specific thing will be included as a default (e.g. how the URL generator is currently set up), but we'll try to keep the component as agnostic as possible. This is already happening to some extent, but if we remove all MW-specific language and code to separate locations, it will make the delineation much clearer.
This is a simpler example, but in MediaSearch we implemented something similar to option 4 for our AutocompleteSearchInput (which is basically a Lookup component): the AutocompleteSearchInput emits an event on change, lets the parent handle the API call and response formatting, then takes in a set of autocomplete suggestions as a prop. It has no idea what's going on to get those results. All of the API logic happens in a mixin, which is mixed into the component that contains the AutocompleteSearchInput.
Of course, we want to balance agnosticism with ease-of-use for the main use case, which is MediaWiki. So having clearly delineated MediaWiki-specific defaults that can be easily overwritten might be the best path forward.
To do
- Discuss these factors in this ticket and, if needed, synchronously
- Determine the best path forward for maintaining this work as we move to the new Vue component library
- Distill that plan into a task or set of tasks