Page MenuHomePhabricator

Spike: Nearby Pages use-case for MenuItem ("Card") Component
Closed, DeclinedPublicSpike

Description

MenuItem is a component that is part of Codex: https://doc.wikimedia.org/codex/main/components/menu-item.html

MenuItem is also what is used in the Codex version of TypeaheadSearch: https://doc.wikimedia.org/codex/main/components/typeahead-search.html#demos

On Nearby Pages, a similar WVUI "Card" component is used in this scenario: https://en.wikipedia.beta.wmflabs.org/wiki/Special:Nearby#/coord/37.78348208159495,-122.4685506720315

Could the MenuItem component be a good candidate for the NearbyPages use-case? To determine this, let's consider...

  • If we should to use MenuItem outside of a menu context, such as in a list (would need to think about implications for different ways to use it, e.g. MenuItem becomes ListItem, perhaps with a wrapper around it? Or further decoupling? This could be a good opportunity for a design/engineering sync.)
  • What design changes would be made to the existing implementation? (Readers Web, would you please review design specs from MenuItem and note inconsistencies, questions, concerns in comments?)

The outcomes of this spike should be a decision on whether to use the existing MenuItem component in NearbyPages or a new component (e.g. ListItem), and the creation of follow-up tasks for design and engineering requirements.

Event Timeline

STH added a subscriber: DAbad.

MenuItem in its current state shouldn't be used outside of a Menu—it has states related to Menu (selected, active, highlighted, disabled) and its semantics don't mesh with the NearbyPages use case (see the docs page for this component).

The limited use of MenuItem was deliberately done based on design feedback in T299682. My initial plan when implementing TypeaheadSearch in Codex was to have a generic ListItem component that would contain the content common between the Nearby (and RelatedArticles) use cases and the TypeaheaSearch/Menu use cases, then have a MenuItem component that contained the logic related to menus and used the ListItem component for its content. But after receiving the feedback that those use cases were too different, I merged ListItem into MenuItem.

If we now think that the use cases are close enough, we could go back to this paradigm of one generic component with the content that gets used by the MenuItem component. But I'd like to better understand if/why that decision is being undone, because this represents a pretty significant refactor.

After speaking with @Sarai-WMDE and reviewing the specifics of the Card use case, I'd like to amend my previous comment a bit. Now that I've more closely reviewed the examples of Cards provided T278311, it's clearer to me that MenuItem and Card are indeed completely separate components, and Nearby should (eventually) use the new Card component. My original idea of a generic ListItem component that could be used by both MenuItem and Nearby is not sufficient, because there are more differences between MenuItem and Card than I previously realized. To summarize:

  • Selectability: MenuItems can be selected, Cards cannot (though they may be clickable links)
  • Interactive states: MenuItems have strongly depicted interactive states related to the Menu they're a part of: active, selected, and highlighted. Cards have much more subtle interactive states on events like hover and focus.
  • Content: MenuItems have strictly limited content, including a title with optional search query highlighting, a search "match", and a description. Cards can have titles, descriptions, and other text following the description.
  • Orientation options: MenuItems always appear in the same orientation, while Cards can appear in both a landscape/horizontal and portrait/vertical orientation.

So, a generic ListItem that can be used by both MenuItem and "card" use cases does not seem like the correct architectural decision, even though there is some overlap. Rather, I think we should move forward with refining the use cases and requirements for Card, then design and build that component.

(Side note that there *might* be a use case for a generic ListItem component for literal lists that aren't menus, but that use case is not yet clear so we can ignore it for the purposes of this discussion.)

Hey, Readers Web team 👋🏻 Supported by the arguments provided by Anne in the comment above, the Codex team identified the need to introduce a Card component into Codex (See Epic: T278311). We've taken the first steps in that direction and defined the scope of the Card's MVP (T310628), which will start to be implemented by our team as soon as the corresponding MVP design specs are finalized.

It looks like the first iteration of Card could already fit the Nearby pages' use case, but we'd like to validate this and make sure we provide a fully useful and reusable component. With this purpose, I created this overview in Figma (sorry, docs and presentations were too limiting). The purpose of this document is to present the new Card component and, specially, outline its potential differences with the suggestion elements currently used in Nearby pages. Any feedback or comments (either async or in a call!) on this very first iteration will be much appreciated.

As noted above, we're developing the initial iteration of the new Card component to fit the Nearby Pages use case, so I'm declining this task.