Page MenuHomePhabricator

Address inconsistencies across components with menu items
Closed, ResolvedPublic

Description

Several Codex components take in menuItems as a prop and use a v-model binding (usually with the default name, modelValue) to indicate which menu item, if any, is selected. We should make sure that the use of these props is as consistent as possible across all components, to make their use more predictable and intuitive.

Some things to address:

  • Some components require the selected value prop (usually modelValue), some do not. We should make this consistent.
  • Similarly, some components require the menuItems prop, even if it's an empty array, while some do not and default to an empty array. This should also be consistent.
  • The default value for the model value may vary across components to some extent, but we should carefully example each default value to create some level of consistency, especially for null/falsy values

QA:
All the components that make use of Menu items have been modified. The QA required for this task is to make sure that the following components are tested and work as expected:

  • Select component
  • Typeahead component
  • Lookout component
  • Menu component
  • Combobox component

Event Timeline

STH raised the priority of this task from Low to Needs Triage.
SimoneThisDot changed the task status from Open to In Progress.May 17 2022, 11:40 AM
SimoneThisDot claimed this task.
SimoneThisDot moved this task from Up Next to Backlog on the Design-System-Team board.
SimoneThisDot moved this task from Backlog to Design-System-Sprint on the Design-System-Team board.
STH triaged this task as High priority.May 17 2022, 5:18 PM

I have done some research on the different components and found the following differences:

image.png (152×1 px, 21 KB)

I would propose the following changes:

  1. Change the property for the selected value of the different menus to be "ModuleValue"
  2. Change the ModelValue to always be Required (otherwise it defeats the purpose of having a component that selects a value)
  3. Change the type of ModelValue to also accept "null" so that it is possible to initialize it with a null value
  4. Leave the MenuItems and SearchItems inconsistency as the latter is actually of type "searchItem" and not MenuItem".
  5. Change the emit triggered when a user Type in the menu box to change this would align with the expected event of a normal HTML input
  6. Change the event triggered when an item is clicked and selected to update:ModelValue

One more question unrelated to the above. The typeahead seems to be emitting and setting lots of events, but it currently is set to always open up in a new tab no matter what you do, so not sure why we should trigger any event from it as the user will be redirected to a new URL on click. I just wanted to ask about the use case so that we can specify it more in the Documentation

cc: @Catrope @AnneT

Thanks for reviewing this, @SimoneThisDot!

  1. Change the property for the selected value of the different menus to be "ModuleValue"

Is this referring to the selected prop of the Menu component? IIRC, we decided to name that model value a) to clarify what it means and b) because there's another named v-model (expanded) and we preferred to name both rather than having one default and one named.

  1. Change the emit triggered when a user Type in the menu box to change this would align with the expected event of a normal HTML input

I had proposed some standards for custom event names in T299242, but I'm definitely open to feedback here. We're using change in the way I had proposed in the MenuItem component, so I just want to avoid any confusion over what the "change" event means. Since the event eventually emitted by something like Lookup on user input involves some processing before it's actually emitted, I like the idea of differentiating it from the actual HTML events that happen on input.

Regarding the events emitted by TypeaheadSearch, the only events that the parent app cares about are used for analytics—it doesn't actually do anything for the user, for the reasons you described.

Hi Anne,

so if I understand the above comment correctly, after your comment is seem like the best way to go forward would be:

  1. Change the property for the selected value of the different menus to be "Selected"

For the reply to number 5, I am not sure if I agree (or prob do not understand it entirely). For a user, typing into a text box is a change event and may not want to know about the component's internals. providing consistency will help massively users (that may expect an change event), while adding extra standards may provide a more "logical" solution, but result in more complex usage.. Happy to go ahead with anything we choose, but I wanted to share my thought! :)

@SimoneThisDot regarding the first item: I think it's okay for Menu to have a different property name for the selected value, because:

  • It's ideal to use the default v-model prop name (modelValue) for components that use Menu
  • For the Menu component itself, we have two props controlled by v-model, so we have to use at least one named v-model, and we decided to name both for clarity.

So, I think the current state is fine.

Also noting that we discussed the 5th item and agree that we should try to follow paradigms established elsewhere, and use change as Simone has suggested in his proposal.

So I have done some work, and this is what I have so far, do you guys agree? I rolled back with a couple of things I suggested above, as while developing they were making the code very unclear!

I wanted to get agreement on this before I continue the task (i just have tests and documentation to update but want to make sure it is ok before I do that as it is time-consuming to complete.

image.png (248×959 px, 34 KB)

cc: @Catrope @AnneT

This comment was removed by Catrope.

This looks good to me, thanks for listing these out @SimoneThisDot!

+1, with just one small change: I think we should keep TypeaheadSearch's search-result-click event as-is. It's not quite the same as selected as it happens literally on search result click, not on @update:selected, and it also can be applied to the search footer item (the "Search Wikipedia for ___" item), which isn't ever truly selected.

Hey @AnneT @SimoneThisDot ; I'm working on removing the bulk of our sprint tasks unrelated to our sprint goals (TypeaheadSearch, Testing, or Component Epic Template), but I also want to respect work completed so far.
Do we want to keep this prioritized and/or add as a subtask of T297025?

@ldelench_wmf This doesn't absolutely have to block the initial release of TypeaheadSearch, but it would save us a corresponding patch in Vector paired with a future Codex release if we complete it now. One of the event names in TypeaheadSearch needs to change, and any implementation of TypehaeadSearch will need to be updated to use the new event name. So, if we do it now (at least the TypeaheadSearch part), we'll save ourselves some time down the road.

Change 803335 had a related patch set uploaded (by Simone Cuomo; author: Simone Cuomo):

[design/codex@main] [WIP] refactor: Fix inconsistencies across components with menu items

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

After discussion on the ticket the following is what has been agreed and implemented:

image.png (154×957 px, 26 KB)

Change 803335 merged by jenkins-bot:

[design/codex@main] refactor: Fix inconsistencies across components with menu items

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

This is done, but:

  • It could use functional testing of components that use the Menu component (currently Combobox, Lookup, Select, and TypeaheadSearch) to ensure there are no regressions
  • It might be worth talking to early developer users of Codex to ask about their experience with these components and the patterns we've created related to providing props for menu items and the current selection (or lack thereof). The goal of this task was to make this both consistent across components and clear overall, so we should try to validate that latter goal.

Many thanks to @SimoneThisDot for all the work on this task!

EUdoh-WMF subscribed.

Testing

There are no functional regressions on the components:

  • Lookup
  • Menu
  • Select
  • Combobox
  • Typeahead

Nice work, all! Resolving as acceptance criteria/QA checklist is complete and the patch included in Codex 0.1.0-alpha.8 - feel free to reopen if I've missed anything.