Page MenuHomePhabricator

Add SearchInput component to Codex and TypeaheadSearch component
Closed, ResolvedPublic

Description

Component design

Background/Goal

The SearchInput component needs to be designed and specified before its implementation as one of the building blocks of the Codex TypeaheadSearch component.

Screenshot 2022-03-23 at 17.38.22.png (185×1 px, 13 KB)

This Figma frame contains the design specifications for this component.
User stories

As a designer and developer, I need to be able to reuse a system-compliant SearchInput component, in order to provide users with an input they can use to submit a search query.

Considerations

The SearchInput component has two variants:

  • A simple version that only presents a single input type search
  • A version that also includes a 'Search' button (Normal neutral, with text or IconOnly) beside the input
Development considerations

The SearchInput component is composed either by a single search input (i.e. an Input with type=search) or a search input + Normal Neutral Button.

Acceptance criteria (or Done)

  • All the interactive states and behavior of the SearchInput are documented.
  • All the visual properties of the SearchInput are fully specified
  • Keyboard navigation support is defined

Component implementation

Background

The existing version of TypeaheadSearch within Codex has a UI similar to that of SearchInput, and should use the SearchInput component once it exists.

Acceptance criteria

  • CdxSearchInput can be used within TypeaheadSearch, while providing a reusable interface for other search implementations
  • CdxSearchInput is properly documented on the Codex docs site
  • CdxSearchInput follows the design spec

Notes:

  • Responsiveness is out of the scope of this task and captured by this separate ticket: T302881

Event Timeline

Please find work in progress design specifications for this component in this Figma frame.

@Sarai-WMDE We have been discussing the possibility of adding a SearchInput component, which is just a TextInput component with certain preset props and attributes. Does BasicSearch replace that?

Thanks for the question, Anne! This is only a terminology replacement, yes. We thought that naming this small component family something like "BasicSearch" instead of "SearchInput" was more adequate, given that one of its variants is actually a combination of said SearchInput with a Button.

The component family tree would look as follows in our demo site:

  • Search
    • BasicSearch
      • Demos
      • Usage
    • TypeaheadSearch
      • Demos
      • Usage

@AnneT, after a recent conversation with the Pattern Lab team, it looks like we'll go for "SimpleSearch" instead of "BasicSearch". I'll apply the new name everywhere, starting with this ticket.

Sarai-WMDE renamed this task from Design BasicSearch component to Design SimpleSearch component.Feb 3 2022, 12:55 PM
Sarai-WMDE updated the task description. (Show Details)

Change 763809 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[design/codex@main] SimpleSearch: Add SimpleSearch component and use in TypeaheadSearch

https://gerrit.wikimedia.org/r/763809

AnneT renamed this task from Design SimpleSearch component to Design and build initial SimpleSearch component.Feb 28 2022, 8:10 PM
AnneT claimed this task.
AnneT updated the task description. (Show Details)

@Sarai-WMDE and @AnneT I'd like to propose that we re-name this component. My understanding is that this component only contains the input box, the button, and the icon – not a menu of results, or any ability to make API requests, etc.

Given that, I'd like to propose that we refer to this as a SearchInput – we already have a TextInput component, and we will likely have other kinds of inputs as we move forward (password input? date/time input? etc). A dedicated SearchInput would fit into such a scheme, and also seems clearer in terms of describing the component's responsibilities.

Thoughts? Ideally we could also remove all references to the old "BasicSearch" name as part of this.

Hey, @egardner. Thanks for the suggestion. The fact that this component can feature an optional button is what actually prevented us from keeping the original name: it seemed inaccurate to use the term SearchInput to refer to the combination of the search input and a button. Nevertheless, I agree that BasicSearch also introduces an exception in the way we'll name inputs in Codex. The name has raised questions before.

Now, in order to try to make consistency a factor here, I checked other "composed" inputs in our style guide: File input and Number input. In the first case, the input cannot be separated from its button; while, in Number input, the buttons might be optional (we may need to create an individual NumberInput that can be combined to produce other components – e.g., the quantitiyInput needed in Wikidata/Wikibase and Common's structured data).

These two examples seem to support the idea that our inputs, in general, can have buttons by default (FileInput), or feature variants that include buttons (SearchInput, NumberInput). With that in mind, the phylogeny of these three components might look as follows:

  • FileInput (includes a button by default)
  • NumberInput (with optional decrease/increase buttons – probably configurable via a prop)
  • Search
    • SearchInput (SearchInput and SearchIput with button – probably configurable via a prop)
    • TypeaheadSearch

I agree to this being a more consistent naming approach overall and thus support your suggestion 😄 Unless there's any opposition from @Volker_E and/or @bmartinezcalvo, I'll be happy to update the name everywhere (this time for real 😅).

I agree to this being a more consistent naming approach overall and thus support your suggestion 😄 Unless there's any opposition from @Volker_E and/or @bmartinezcalvo, I'll be happy to update the name everywhere (this time for real 😅).

@Sarai-WMDE SearchInput and SearchInput with button are totally logical and consistent with we currently have in other components such as FileInput and NumberInput. Free way on my part to update with those names.

Agreed too. The UI strictness of an input called widget has already been watered down with HTML input=search carrying clear buttons in browsers like IE or Webkit.
SearchInput makes sense from my side. Thanks for the proposal and Sarai, for the rundown of components.

Awesome, thanks, everyone! I'll update the patch to reflect the name change and will work on making the input + button styles reusable.

Thanks for the green lights! I'll update the name in the designs and Phab tickets 👍🏻

Great, glad that idea makes sense to everyone!

I think this will pay off down the road when we have to keep track of a family of related components featuring input + buttons.

Sarai-WMDE renamed this task from Design and build initial SimpleSearch component to Design and build initial SearchInput component.Mar 10 2022, 4:55 PM
Sarai-WMDE updated the task description. (Show Details)

You can check out the demos for the patch here (SearchInput and TypeaheadSearch are relevant): https://763809--wikimedia-codex.netlify.app/

Some thoughts:

TextInput styles

I noticed that some of the styles for the input are a bit different from what we have for TextInput. Should we update the TextInput component's styles to match the design spec? This includes:

  • The input padding, including around the icons and the general horizontal padding
  • Text color (it's #000 for TextInput but @color-base in the SearchInput design spec
  • Line height (it's @line-height-component: unit( ( 20 / @font-size-browser / @font-size-base ), em );, which works out to 1.42857143em, for TextInput, and @line-height-100, or 1.6, in the design spec)

If we do update the TextInput styles, I'd recommend doing so in a separate patch, since it will mean some cascading changes in components that use it (like TypeaheadSearch).

Clearable

The design spec states that the SearchInput should be clearable by default. Could we consider defaulting to not clearable, then allowing users to add the clearable prop if they want to? See the third demo here for an example; it's just a single line of code. The TypeaheadSearch component is currently not clearable (see below), and since all of our boolean props default to false, I would prefer to stick to that paradigm as much as possible and allow library users to opt-in to boolean props.

If we want to make TypeaheadSearch clearable, we'll need to think through how to avoid this scenario (which occurs when there is input but you move focus away from the input):

image.png (144×1 px, 14 KB)

This could be as simple as showing the submit button anytime there is input.

Finally, the clear button is currently not accessible via keyboard. Do we want it to be? I wonder if it might be confusing for someone to type something, hit tab expecting to go to the "submit" button, then accidentally clear the input.

Submit with empty input

The design spec says that a submit event should only occur (at least via the enter key) when there is input. I'd recommend we emit the submit event whether there's input or not, and let the parent component decide how to deal with it. Otherwise, it feels like we're hiding an event from the library user that they may want to use. Is that acceptable?

On “Clearable icon is reachable via keyboard” – from keyboard user experience, I think we are risking to over-engineer here. A keyboard user focussing the field is marking all input value. Pressing backspace/delete is sufficient, we don't have to make the clear icon keyboard focusable and expand user's workflow by one extra tab press here.

Answering inline here too:

TextInput styles

I noticed that some of the styles for the input are a bit different from what we have for TextInput. Should we update the TextInput component's styles to match the design spec?
If we do update the TextInput styles, I'd recommend doing so in a separate patch, since it will mean some cascading changes in components that use it (like TypeaheadSearch).

We should update the TextInput styles (in a separate patch, of course). This way, it'll be easier to apply changes consistently to these related components in case tokens are updated.

*Update*: After further discussion between designers, we decided to not upstream changes from the SearchInput to the TextInput. Instead, the SearchInput should consume/reuse the TextInput as is. We'll later (if agreed) apply the suggested styles to the TextInput, in a separate task

Clearable

The design spec states that the SearchInput should be clearable by default. Could we consider defaulting to not clearable, then allowing users to add the clearable prop if they want to?

Yes, it makes sense to set the clearable prop to false by default to avoid breaking that paradigm.

If we want to make TypeaheadSearch clearable, we'll need to think through how to avoid this scenario (which occurs when there is input but you move focus away from the input):

image.png (144×1 px, 14 KB)

This could be as simple as showing the submit button anytime there is input.

Ouch. The idea behind creating two separate variants of this core component was to make their anatomy permanent, and remove custom logic like displaying the button on hover or while active (leaving that possibility to the application). Is there a way to avoid that scenario while keeping this approach?

Finally, the clear button is currently not accessible via keyboard. Do we want it to be? I wonder if it might be confusing for someone to type something, hit tab expecting to go to the "submit" button, then accidentally clear the input.

I assumed that the clear button should be accessible via keyboard, but both your points make sense. SR users might not need, or even discover this option on time after all (as they might rely on pressing enter to submit their value). It's true that we'd be introducing an extra step in their navigation path. Based on that, I'd say it's ok to remove the option from their flow.

Submit with empty input

The design spec says that a submit event should only occur (at least via the enter key) when there is input. I'd recommend we emit the submit event whether there's input or not, and let the parent component decide how to deal with it. Otherwise, it feels like we're hiding an event from the library user that they may want to use. Is that acceptable?

It's perfectly acceptable and correct, yes. I think my wording was vague and that, in fact, we need to emit that event to make possible what the specs say: "The behavior of the Search button can be customized in the context of the application consuming the SearchInput component. If the button is pressed/activated when the input is empty, it might result in: [Insert wanted behavior]".

Change 763809 merged by jenkins-bot:

[design/codex@main] SearchInput: Add the SearchInput component

https://gerrit.wikimedia.org/r/763809

If we want to make TypeaheadSearch clearable, we'll need to think through how to avoid this scenario (which occurs when there is input but you move focus away from the input):

image.png (144×1 px, 14 KB)

This could be as simple as showing the submit button anytime there is input.

Ouch. The idea behind creating two separate variants of this core component was to make their anatomy permanent, and remove custom logic like displaying the button on hover or while active (leaving that possibility to the application). Is there a way to avoid that scenario while keeping this approach?

I can definitely see the case for moving some of the UX behavior of TypeaheadSearch (auto-expanding, hiding the button except on focus) to Vector, if it is truly specific to that use case. I suppose it's up to us to decide what the style and behavior of the core component should be, then move anything else to the application (Vector). I don't have all the context/information on exactly why all of the design decisions for WVUI's TypeaheadSearch were made, but if we can identify anything as specific to the case of a search bar on a MediaWiki site's header, we should consider moving it out of Codex.

@Sarai-WMDE is this task still blocked by anything, or can it be moved to design review?

Hey, @AnneT. Sorry for the late reply. The pending responsive design/implementation task is captured in a separate ticket (T302881), so I don't think that this task is blocked by anything. It can be moved to Design review (will do with your permission).

STH renamed this task from Design and build initial SearchInput component to Add SearchInput component to Codex and TypeaheadSearch component.Apr 15 2022, 8:25 PM
STH changed the task status from Open to In Progress.
STH triaged this task as High priority.

I'd swear I had added my review to this ticket. Oh my. Here are the notes:

In SearchInput With Button:

  • The top and bottom right border-radius of the SearchInput should be 0px (token currently missing) when combined with the submit button.
  • The button's left border should be visible (i.e. be "on top of" the input) when the button is interacted with (on hover, active and focus). This behavior is correctly displayed by TypeaheadSearch (both in Codex and WVUI).

In TypeaheadSearch:

  • Bringing back the conversation started above: when discussing the design specifications of this component, we decided that both SearchInput and its consumer component TypeaheadSearch would share the same two default variants: one that features an input and another that features an input and a button. In order to simplify things and ensure reusability, we originally agreed that the logic of displaying the button on hover should not be part of the core Codex component, although that approach might not be totally convenient and we might need to discuss this solution (See T307203: Decide how to handle TypeaheadSearch's button display logic)

Change 789254 had a related patch set uploaded (by Anne Tomasevich; author: Anne Tomasevich):

[design/codex@main] SearchInput: Fix border radius and button border behavior

https://gerrit.wikimedia.org/r/789254

Change 789254 merged by jenkins-bot:

[design/codex@main] SearchInput: Fix border radius and button border behavior

https://gerrit.wikimedia.org/r/789254

@Sarai-WMDE I've implemented the two suggestions in your last comment regarding the button, which is now visible on the live docs site, and moved this back into design review!

Perfect! The SearchInput fixes are on point and the component is looking great. Signing this off since the last point in my review comment will hopefully be handled once we decide on an approach. See T307203: Decide how to handle TypeaheadSearch's button display logic.

AnneT removed AnneT as the assignee of this task.May 13 2022, 9:01 PM
DAbad added a subscriber: DAbad.

closed