Page MenuHomePhabricator

docs: Clarify TypeaheadSearch's use case and differences from Lookup
Closed, ResolvedPublic

Description

We've already seen and felt some confusion between TypeaheadSearch and Lookup while building Codex and observing others starting to use Codex. Let's consider how we can better differentiate between the two and clearly show their distinct use cases in the code and in the docs.

Some ideas:

  • Give the components more precise names. The names of the components currently do not differentiate them at all; they essentially mean the same thing. We may want to consider giving TypeaheadSearch a name that indicates its narrower use case, like PageSearch
  • Clarify the different use cases in the docs. Lookup is a much more generic component that will be the right choice in most cases, while TypeaheadSearch is specifically meant to search pages and provide links to other pages for the user to visit. We should clarify this in the docblock of each component, which will also display on the components' doc pages.
  • Consider moving TypeaheadSearch. We have discussed the idea of separating out components that cover specific use cases and are more app-like than component-like. Perhaps TypeaheadSearch should live in its own package, or we should have a separate folder within the codex package for [name of something bigger than components, like how molecules are composed of atoms?]

Event Timeline

Hey @AnneT! I keep forgetting to add my take here. I think that both renaming and moving TahS to its own ("Patterns"?) section would make sense (specially if we determine that we're definitely not handling a core component).

Nevertheless, I do find that a first (easier) step to alleviate confusion – while we figure everything out – could be adding some clarifying lines in the docs. I think that the main difference between Lookup and TahS is that the former is an input component*: users search the Lookup only to obtain a list of options from which they can select a value to input (e.g. in a form). While, as you mention, TahS offers options that allow users to navigate away from their current page, into a new one that contains content related to their search.

(*In terms of naming, maybe it would help if we renamed cdx-Lookup to cdx-LookupInput?)

STH triaged this task as High priority.May 17 2022, 5:20 PM

@Sarai-WMDE How does this plan sound:

  1. Update the Lookup and TypeaheadSearch docs to state that Lookup is a "predictive input" while TahS is for searching and navigating to new content
  2. Implement the component groupings as part of T309109 since that will separate Lookup and TypeaheadSearch into different groups
  3. Re-evaluate if we need to change "Lookup" to "LookupInput". I'm hoping the changes in the first two steps will be sufficient, because I do think semantically "Lookup" is the better name, but if we feel we need additional clarity, this will be a useful path for that.

Taking this out as child from typeaheadsearch on codex. as not part of the MVP for Typeaheadsearch. Will link to beta release epic

ldelench_wmf subscribed.

Moving from sprint to backlog per:

Taking this out as child from typeaheadsearch on codex. as not part of the MVP for Typeaheadsearch. Will link to beta release epic

Without much context on how you all think about component taxonomy, I could see the difference here as a matter of configuration. I wonder if it's worth considering merging the two components...high level they seem more similar than different: an input box with an accompanying menu based on what you've input.

Hey @alexhollender_WMF 👋🏻 We decided that these components shouldn't be merged. As explained in the comment above, Lookup and TypeaheadSearch share visual and functional similarities related to autocomplete/prediction, but we believe that they are essentially different.
The first is an input: users type in the Lookup to retrieve an option that they ultimately want to select as part of a process (e.g. select a template), or to see reflected in a form/UI (e.g. property selector in Wikidata). In the context of Lookup, navigating to menu options is secondary (it's allowed mostly to let users confirm their selection). On the other hand, Typeahead is a search element that belongs to the search/navigation system of a project. TahS doesn't allow inputting information in a form (the input/selection doesn't need to be preserved), instead, the result of selecting any of the retrieved results is navigation.

@AnneT I just created a task (T315993) to update the component descriptions in their demo pages.

egardner lowered the priority of this task from High to Medium.Jan 23 2023, 5:20 PM

I believe we have sufficiently resolved this by including component guidelines on the Codex docs site. The guidelines for Lookup and TypeaheadSearch describe when to use each one. In the future, we may consider moving TypeaheadSearch to a different library, but for now I think we have achieved this task's goal.

AnneT edited subscribers, added: CCiufo-WMF; removed: alexhollender_WMF, STH.

I'm reopening this based on feedback we got from some Codex users:

  • It's not clear when to use TypeaheadSearch and when to use Lookup
  • It's not clear that TahS is for page navigation and Lookup is for selecting an item
  • The name of the components, especially TahS, do not help clarify their purpose. In particular, both components have "typeahead search" aka autocomplete.
  • We could rename one or both components but keep an alias of the old name. Changing CSS class names would be trickier since they are sometimes used outside of Codex (though we discourage this). For example, there are 2 instances of .cdx-typeahead-search selectors in Vector - perhaps these could be updated to a vector-specific classname instead. Unfortunately, there is also a TahS class used in a Vector message (for the search footer text)

Additionally, I'd like to note that not all features of TahS are available in Lookup:

  • Search query highlighting - this would be easy to implement in Lookup and I think we should do it
  • Expanding input behavior - this is feature-specific and should not be used in Lookup
  • Search button - this is actually part of SearchInput, which TahS uses under the hood. This would be a bit more complex to implement in Lookup but we could do it.

...and things that already work in Lookup, but we're not demonstrating:

  • Examples on the demo page of menu item features like thumbnails
  • search input type
AnneT removed AnneT as the assignee of this task.Oct 11 2024, 1:49 PM
bmartinezcalvo renamed this task from Clarify TypeaheadSearch's use case and differences from Lookup to docs: Clarify TypeaheadSearch's use case and differences from Lookup.EditedMar 13 2025, 1:24 PM
bmartinezcalvo subscribed.

We included a section for "When to use" each component in Codex, clarifying when to use TypeaheadSearch or Lookup so I guess we can solve this task @AnneT

AnneT claimed this task.

In addition to @bmartinezcalvo's comment above, I'm resolving this since we intend to remove TypeaheadSearch from Codex as part of Codex 2.0 and move it into core