CustomSelect: Adapt component for legacy props #57902

brookewp · 2024-01-17T02:20:29Z

What?

Another option to replace CustomSelectControl with the new ariakit verison without breaking changes. This started in #57000, which was using a similiar approach to ColorPicker's legacy adapter. It was getting a bit complicated, so this PR ius based on another approach shared by @ciampo. This has the same goal but aims to be less convoluted.

Why?

To transition away from using CustomSelectControl to the new version for more flexibility.

How?

No changes were made to CustomSelectItem, aside from moving it to a separate file.
The same for CustomSelect, and the store has been moved outside of the component and instead is forwarded the store.

In this version, there are two components, one for the legacy and another for the new/soon-to-be-default version. There is a check to see which props have been passed through. If it's the legacy, the props are translated to the new version of the component.

This also adds the same tests from CustomSelectControl. The only changes made were to the role which is now combobox instead of button, and the tests for the custom event handlers have been removed.

To Do

unmountOnHide - add to both or just legacy? Related: Select: defaultValue doesn't behave as intended when using unmountOnHide ariakit/ariakit#3374
Edit README

Legacy

fix ~~arrow~~checkmark size
legacy compact/default sizing, related comment
return object: CustomSelect: Adapt component for legacy props #57902 (comment)

New

re-rendering on selection: e3c0be1

Testing Instructions

run npm storybook:dev
See the two separated stories
Ensure that the Default version works as it did before, in trunk.
Ensure the Legacy version behaves and looks the same as the original CustomSelectControl

brookewp · 2024-01-17T02:30:57Z

packages/components/src/custom-select-control-v2/legacy-component/index.tsx

+			const changeObject = {
+				selectedItem: {
+					// value will always be a string for the legacy component
+					name: value as string,
+					key: state.activeId as string,
+				},
+				highlightedIndex: state.renderedItems.findIndex(
+					( item ) => item.value === value
+				),
+				isOpen: state.open,
+			};
+			props.onChange( changeObject );


Just to note, I'm still looking into the onChange return object. I've implemented the suggestion by @diegohaz from an earlier PR: #55234 (comment), minus the type and inputValue. I'm looking to see if it makes sense to include these / how we could implement them.

The value of type is the interaction method used to make a selection, i.e. __item_click__, __menu_keydown_enter__

The value of inputValue is the first character entered via keydown to make a selection (with type returning __togglebutton_keydown_character__). If keydown isn't used to make a selection, then it returns an empty string.

The value of type is the interaction method used to make a selection, i.e. __item_click__, __menu_keydown_enter__
[...]
The value of inputValue is the first character entered via keydown to make a selection (with type returning __togglebutton_keydown_character__). If keydown isn't used to make a selection, then it returns an empty string.

Mhh, I'm not sure we can reliably access those pieces of information. Maybe Diego can advise.

In the meantime, we can give them a fixed '' value to at least make sure that if anyone is accessing those properties, they are defined.

I'd keep the type as __item_click__ by default for simplicity's sake. If anyone depends on these values, it's likely the type they're handling as standard.

You could get this value by listening to DOM events and storing the information in a ref for subsequent use in Ariakit's setValue prop. But honestly, I wouldn't sweat it. It's not even mentioned in the Downshift docs. It doesn't seem to be part of their public API.

Edit: I was wrong. It is part of their public API (see stateChangeTypes). Still, if these constants weren't exposed by WordPress components, I'd avoid re-implementing this logic.

ciampo

This is looking promising!

I know that it's still a draft, but I left a few initial comments that are hopefully going to help move the work forward 🤞

packages/components/src/custom-select-control-v2/stories/legacy.story.tsx

packages/components/src/custom-select-control-v2/legacy-adapter.tsx

packages/components/src/custom-select-control-v2/stories/legacy.story.tsx

ciampo · 2024-01-18T09:47:16Z

packages/components/src/custom-select-control-v2/legacy-component/index.tsx

+			const changeObject = {
+				selectedItem: {
+					// value will always be a string for the legacy component
+					name: value as string,
+					key: state.activeId as string,
+				},
+				highlightedIndex: state.renderedItems.findIndex(
+					( item ) => item.value === value
+				),
+				isOpen: state.open,
+			};
+			props.onChange( changeObject );


The value of type is the interaction method used to make a selection, i.e. __item_click__, __menu_keydown_enter__
[...]
The value of inputValue is the first character entered via keydown to make a selection (with type returning __togglebutton_keydown_character__). If keydown isn't used to make a selection, then it returns an empty string.

Mhh, I'm not sure we can reliably access those pieces of information. Maybe Diego can advise.

In the meantime, we can give them a fixed '' value to at least make sure that if anyone is accessing those properties, they are defined.

packages/components/src/custom-select-control-v2/legacy-component/index.tsx

packages/components/src/custom-select-control-v2/types.ts

packages/components/src/custom-select-control-v2/stories/default.story.tsx

packages/components/src/custom-select-control-v2/legacy-component/index.tsx

github-actions · 2024-01-18T20:37:43Z

Flaky tests detected in 3a2be41.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/7850850332
📝 Reported issues:

[Flaky Test] name is correctly hydrated for different values #57881 in /test/e2e/specs/interactivity/directive-bind.spec.ts

packages/components/src/custom-select-control-v2/legacy-component/index.tsx

packages/components/src/custom-select-control-v2/types.ts

packages/components/src/custom-select-control-v2/legacy-component/index.tsx

brookewp · 2024-01-24T02:36:52Z

packages/components/src/custom-select-control-v2/types.ts

@@ -22,7 +27,13 @@ export type CustomSelectProps = {
 	 * An optional default value for the control. If left `undefined`, the first
 	 * non-disabled item will be used.
 	 */
-	defaultValue?: string | string[];
+	defaultValue: string | string[];


When adding unmountOnHide, the initial selected value was an empty string because it no longer had access to the items through the store (see details here: ariakit/ariakit#3374 (comment))

I'm thinking it might be cleanest to require a defaultValue (for the new version, the legacy would use the hardcoded default to behave the same), as it's just a string for the consumer to implement.

Otherwise, we'd have to map over the children to find a default value. The problem here is that the children could be a fragment or a div or anything that the consumer implements. So it seems like it could get a bit messy to extract a value.

It's also likely I'm overcomplicating it and there is an easy way to get the value. I'm happy to hear if there is a better solution. 🙂

Is defaultValue still required if the value prop is provided?

As Diego suggests, defaultValue shouldn't be required when value is provided — it would actually cause more confusion, since defaultValue is used to provide an initial value to the component when used as uncontrolled, while value is used to set the component's value in a controlled mode.

Otherwise, we'd have to map over the children to find a default value. The problem here is that the children could be a fragment or a div or anything that the consumer implements

If we expect children to be instances of CustomSelectControlItem, then we could read the value prop, which is required on those components, and assume as a default value the first defined value that we find when mapping over the children.

Would that work?

Is there a way we can access the value prop without mapping through the children?

That is the only way I am aware of. Other than doing something that might be considered strange and passing it from the child to parent through context.

If we map though the children to find the value, then we're back to the same problem I shared earlier where we might not know how many layers deep the value is. For example, if they are wrapped in a div:

Unless we have a recursive function but that's where I thought it was getting messy or that I was overcomplicating it.

Yeah, it's tricky. If the CustomSelectControlItem component gets abstracted into another custom component, you won't have access to it, even with recursion. It seems odd to impose such artificial restrictions on JSX, where users expect certain features to work seamlessly. It's like trying to use JSX as a DSL for an array of objects, when simply using the array of objects might be the answer.

I'd suggest that either defaultValue or value should be required. There are ways to express this in TypeScript, but a runtime warning might be necessary because the TypeScript error may not be very clear.

This might be a strange idea, but after seeing Lena's work I thought maybe we could add another hack for unmountOnHide 😄

If we mount and then unmount it on the initial render, then we get the first item as the defaultValue without explicitly setting it, like before:

gutenberg/packages/components/src/custom-select-control-v2/custom-select.tsx

Lines 112 to 116 in e3c328f

const [ unmountOnHide, setUnmountOnHide ] = useState( false );

useEffect( () => {

setUnmountOnHide( true );

}, [] );

Could this be a potential solution?

but the test for this behavior is still failing:

From personal experience, user-event may cause some incompatibilities with ariakit-based components, especially when we make some async changes like in the suggestion above. Maybe switching to @ariakit/test fixes it?

Could this be a potential solution?

It could work, as an additional hack. I've updated the example and it seems to work as expected. It may have some performance ripercussion, though — so we could go with this implementation at first (which allows us to keep defaultValue as optional), and only switch to requiring defaultValue as a fallback? What do folks think?

Maybe switching to @ariakit/test fixes it?

It does! I just thought we might want to keep the tests as close to the original CustomSelectControl as possible, so I planned to move to ariakit/test after. But since the tests are the same aside from the interaction method, maybe it will be okay to do that now.

If we mount and then unmount it on the initial render

I feel like the initial render is exactly the most important time to reap the performance benefits of unmountOnHide, so I'm not sure it makes sense to mount on initial render but hide it after.

So going back to basics, if we don't already have proof that just keeping unmountOnHide={ false } all the time has a perceivable performance hit to the overall Gutenberg app, I'd even be fine with not messing with that prop at all for the first iteration. I have to imagine that there are much fewer CustomSelectControls in any given view than a generic Tooltip, for example.

So, we remove unmountOnHide and all of the related workarounds? 🙈 If I understood correctly, then that is done through: 6baa642

Just to note: the tests will pass using @testing-library/user-event or with @ariakit/test. I believe the former is faster, but I think we will likely need to move to @ariakit/test when integrating the new tests (#58583) — based on seeing flaky test results when merging the new and legacy tests in another version of the legacy adapter: #57000

We could revert to RTL, merge this PR, and then merge the tests/change to @ariakit/test if needed in a follow-up. Or we could keep it with @ariakit/test, and I can merge the new tests into this.

Any preferences?

packages/components/src/custom-select-control-v2/legacy-component/index.tsx

packages/components/src/custom-select-control-v2/types.ts

packages/components/src/custom-select-control-v2/custom-select-item.tsx

packages/components/src/custom-select-control-v2/custom-select.tsx

packages/components/src/custom-select-control-v2/types.ts

packages/components/src/custom-select-control-v2/legacy-adapter.tsx

packages/components/src/custom-select-control-v2/types.ts

packages/components/src/custom-select-control-v2/legacy-adapter.tsx

packages/components/src/custom-select-control-v2/types.ts

packages/components/src/custom-select-control-v2/legacy-component/index.tsx

github-actions · 2024-02-01T20:28:01Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: brookewp <brookemk@git.wordpress.org>
Co-authored-by: mirka <0mirka00@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>
Co-authored-by: diegohaz <hazdiego@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

packages/components/src/custom-select-control-v2/custom-select.tsx

brookewp · 2024-02-01T02:22:38Z

packages/components/src/custom-select-control-v2/types.ts

@@ -22,7 +27,13 @@ export type CustomSelectProps = {
 	 * An optional default value for the control. If left `undefined`, the first
 	 * non-disabled item will be used.
 	 */
-	defaultValue?: string | string[];
+	defaultValue: string | string[];


With respect to the initial value, it should be determined by the consumer by passing either the value prop (controlled mode) or the defaultValue prop (uncontrolled mode)

Would that involve typing so only one is required when the other isn't present? Something like:

type CustomSelectModeProps = | { /** * A default value to show as the currently selected item. Not required when adding a * value to use component in controlled mode. */ defaultValue: string | string[]; value?: string | string[]; } | { defaultValue?: string | string[]; /** * Can be used to externally control the value of the control. */ value: string | string[]; };

There are still some issues with the defaultValue for the legacy component. When a default value is provided, tests are failing, but if we don't pass one, we have the empty initial state due to the unmountOnHide prop. So I'm still looking into that

brookewp · 2024-02-01T04:37:47Z

packages/components/src/custom-select-control-v2/types.ts

@@ -22,7 +27,13 @@ export type CustomSelectProps = {
 	 * An optional default value for the control. If left `undefined`, the first
 	 * non-disabled item will be used.
 	 */
-	defaultValue?: string | string[];
+	defaultValue: string | string[];


however, Lena suggested a little hack which seems to work: set unmountOnHide to false when focusing the button that is triggering the dropdown (see example)

This suggestion worked well in combination with these additional props . When testing in SB, it works as expected, but the test for this behavior is still failing:

gutenberg/packages/components/src/custom-select-control-v2/test/index.tsx

Line 376 in 5babba6

it( 'Can change selection with a focused input and closed dropdown if typed characters match an option', async () => {

🤔

brookewp · 2024-02-01T20:34:02Z

packages/components/src/custom-select-control-v2/types.ts

@@ -22,7 +27,13 @@ export type CustomSelectProps = {
 	 * An optional default value for the control. If left `undefined`, the first
 	 * non-disabled item will be used.
 	 */
-	defaultValue?: string | string[];
+	defaultValue: string | string[];


This might be a strange idea, but after seeing Lena's work I thought maybe we could add another hack for unmountOnHide 😄

If we mount and then unmount it on the initial render, then we get the first item as the defaultValue without explicitly setting it, like before:

gutenberg/packages/components/src/custom-select-control-v2/custom-select.tsx

Lines 112 to 116 in e3c328f

const [ unmountOnHide, setUnmountOnHide ] = useState( false );

useEffect( () => {

setUnmountOnHide( true );

}, [] );

Could this be a potential solution?

packages/components/src/custom-select-control-v2/legacy-adapter.tsx

brookewp · 2024-02-02T20:57:30Z

If this solution is something we can do to handle defaultValue then I believe these are the remaining items:

Decide if we want to use BaseControl instead of Ariakit.SelectLabel: CustomSelect: Adapt component for legacy props #57902 (comment)
Children vs render for Ariakit.SelectArrow - related: CustomSelect: Adapt component for legacy props #57902 (comment)
Refine README

And then, of course, smoke-testing it in the editor once the above is resolved.

cc @mirka @ciampo

brookewp · 2024-02-06T22:27:33Z

I've combined the tests from #58583 in this commit: c73ce18

It's super verbose, with some tests being in both the suites for the legacy and default sections. But with the uncontrolled/controlled sections, I wasn't sure how to do it without overcomplicating it / making it very confusing.

I've let @mirka know about this, as she'll be taking this over this PR at this stage. 🙇‍♀️

mirka

I did a bit of overall clean up in terms of naming, documentation, and styles.

Since this PR has been running long and over-reviewed at this point, I'd like to merge now and iterate in more smaller scopes.

I identified these remaining tasks, and added them to the tracking issue (#55023):

Remove legacy adapter layer (make two separate exports)
Rename to CustomSelectControl and CustomSelectControl.Item
Try to make the TS types for the single/multiple selection modes be more ergonomic
Styling issues
- Focus styles are incorrect
- Needs a utility padding wrapper like InputControlPrefixWrapper
- Line-height is wrong

brookewp added [Type] Enhancement A suggestion for improvement. [Package] Components /packages/components labels Jan 17, 2024

brookewp requested a review from a team January 17, 2024 02:20

brookewp self-assigned this Jan 17, 2024

brookewp commented Jan 17, 2024

View reviewed changes

brookewp mentioned this pull request Jan 17, 2024

CustomSelectControl: explore ariakit refactor #55234

Closed

9 tasks

ciampo reviewed Jan 18, 2024

View reviewed changes

brookewp force-pushed the add/legacy-adapter-customselectcontrol branch from d042c2f to 007aba0 Compare January 18, 2024 20:18

brookewp commented Jan 20, 2024

View reviewed changes

packages/components/src/custom-select-control-v2/legacy-component/index.tsx Outdated Show resolved Hide resolved

brookewp requested a review from ciampo January 22, 2024 16:49

mirka reviewed Jan 23, 2024

View reviewed changes

brookewp force-pushed the add/legacy-adapter-customselectcontrol branch from 0d1e182 to 63f5d28 Compare January 24, 2024 02:27

brookewp commented Jan 24, 2024

View reviewed changes

mirka reviewed Jan 25, 2024

View reviewed changes

packages/components/src/custom-select-control-v2/legacy-component/index.tsx Outdated Show resolved Hide resolved

packages/components/src/custom-select-control-v2/legacy-component/index.tsx Outdated Show resolved Hide resolved

brookewp commented Jan 26, 2024

View reviewed changes

packages/components/src/custom-select-control-v2/types.ts Outdated Show resolved Hide resolved

brookewp force-pushed the add/legacy-adapter-customselectcontrol branch from 6a07814 to 4d6819b Compare January 26, 2024 23:54

brookewp marked this pull request as ready for review January 26, 2024 23:55

brookewp requested a review from ajitbohra as a code owner January 26, 2024 23:55

brookewp requested review from mirka and a team January 29, 2024 20:31

mirka reviewed Jan 30, 2024

View reviewed changes

brookewp force-pushed the add/legacy-adapter-customselectcontrol branch 2 times, most recently from 5babba6 to e3c328f Compare February 1, 2024 20:27

brookewp mentioned this pull request Feb 2, 2024

CustomSelect: add tests for new features #58583

Merged

brookewp commented Feb 2, 2024

View reviewed changes

brookewp mentioned this pull request Feb 2, 2024

CustomSelect: disable virtualFocus to fix issue for screenreaders #58585

Merged

brookewp mentioned this pull request Feb 5, 2024

CustomSelectControl: Add adapter for legacy to new version #57000

Closed

6 tasks

brookewp added 12 commits February 6, 2024 10:35

Remove export that is no longer needed

e0caf2d

Update legacy onChange type

cafbdf8

Update tests

7b86a97

Update naming

bc7027e

Try mounting on first render to avoid required defaultValue

4f9f6f9

Add WordPressComponentProps to default export

71b2c1a

Update types

be17780

Replace RTL/userEvent with ariakit/test

287c354

Remove unmountOnHide and related logic for first iteration

7eb2134

Update docs

c794d06

Update naming

5c58f78

Merge new tests and update to ariakit/test

c73ce18

brookewp force-pushed the add/legacy-adapter-customselectcontrol branch from 794fcd0 to c73ce18 Compare February 6, 2024 22:23

mirka self-assigned this Feb 7, 2024

mirka added 10 commits February 8, 2024 03:09

Fix typo in readme

795df54

Legacy: Clean up stories

4171c67

Default: Clean up stories

8d70b4f

Add todo comment about BaseControl

cb88b8b

Fix styles

d2dfe8b

Rename styled components for consistency

ddc8e6b

Fix typo in readme

faa6d7b

Merge branch 'trunk' into add/legacy-adapter-customselectcontrol

797e139

Rename for clarity

f8446f8

Update changelog

3a2be41

mirka mentioned this pull request Feb 9, 2024

CustomSelectControl: refactor with ariakit #55023

Open

85 tasks

mirka approved these changes Feb 9, 2024

View reviewed changes

mirka merged commit 5939c41 into trunk Feb 10, 2024
58 checks passed

mirka deleted the add/legacy-adapter-customselectcontrol branch February 10, 2024 01:03

github-actions bot added this to the Gutenberg 17.8 milestone Feb 10, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

CustomSelect: Adapt component for legacy props #57902

CustomSelect: Adapt component for legacy props #57902

brookewp commented Jan 17, 2024 •

edited

Loading

brookewp Jan 17, 2024

ciampo Jan 18, 2024

diegohaz Jan 26, 2024 •

edited

Loading

ciampo left a comment

ciampo Jan 18, 2024

github-actions bot commented Jan 18, 2024 •

edited

Loading

brookewp Jan 24, 2024

diegohaz Jan 24, 2024

ciampo Jan 25, 2024

brookewp Jan 25, 2024

diegohaz Jan 26, 2024

brookewp Feb 1, 2024

ciampo Feb 2, 2024

brookewp Feb 2, 2024

mirka Feb 5, 2024

brookewp Feb 5, 2024

github-actions bot commented Feb 1, 2024 •

edited

Loading

brookewp Feb 1, 2024

brookewp Feb 1, 2024

brookewp Feb 1, 2024

brookewp commented Feb 2, 2024 •

edited

Loading

brookewp commented Feb 6, 2024

mirka left a comment

	const [ unmountOnHide, setUnmountOnHide ] = useState( false );

	useEffect( () => {
	setUnmountOnHide( true );
	}, [] );

CustomSelect: Adapt component for legacy props #57902

CustomSelect: Adapt component for legacy props #57902

Conversation

brookewp commented Jan 17, 2024 • edited Loading

What?

Why?

How?

To Do

Legacy

New

Testing Instructions

Choose a reason for hiding this comment

Choose a reason for hiding this comment

diegohaz Jan 26, 2024 • edited Loading

Choose a reason for hiding this comment

ciampo left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Jan 18, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Feb 1, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

brookewp commented Feb 2, 2024 • edited Loading

brookewp commented Feb 6, 2024

mirka left a comment

Choose a reason for hiding this comment

brookewp commented Jan 17, 2024 •

edited

Loading

diegohaz Jan 26, 2024 •

edited

Loading

github-actions bot commented Jan 18, 2024 •

edited

Loading

github-actions bot commented Feb 1, 2024 •

edited

Loading

brookewp commented Feb 2, 2024 •

edited

Loading