Adds declarative props to clear/submit TextInput

[rozele]

This change adds two new props and a new behavior for multiline TextInput.

New props:

1. clearTextOnSubmit: similar to clearTextOnFocus, except that it clears out the TextInput whenever the onSubmitEditing event would be dispatched.
2. submitKeyEvents: registers a set of key down events that will trigger onSubmitEditing for multiline TextInput.

New behavior:
Previously, onSubmitEditing would never fire when multiline={true} for a TextInput. Now, onSubmitEditing may fire for a multiline TextInput if a key down event matching the configuration in submitKeyEvents is observed.

Fixes #7330

Microsoft Reviewers: Open in CodeFlow

[rozele]

I haven't added anything to TextInput.windows.js (though it works w/o declaring the prop types) and this should probably include an e2e test / update to RNTester. Will work on those once we decide if this is worth landing.

[asklar]

@rozele thanks for sending this out! I'd love for these types of changes to be discussed at one of the design reviews. For example, is it necessary to have a property for "clear on submit" instead of just having the app do the clear on an onSubmit event handler?

[rozele]

@asklar The referenced issue (#7330) discusses the motivation for the prop. Happy to discuss this in the coming weeks (though I believe our next opportunity isn't until ~3/24).

[rectified95]

Is this necessary? I thought Subclass::UpdateProperties gets called after the ShadowNodeBase keyboard handler gets bound in the PreviewKeyboardEventHandlerOnRoot constructor?

[rozele]

Yes - this is necessary. Although the root-level keyboard event handler for emitting key events gets subscribed before any of these props get set, the view-level keyboard event handler that sets Handled(true) on the routed events gets subscribed in Super::updateProperties.

If we subscribe to PreviewKeyDown for onSubmitEditing before we subscribe to PreviewKeyDown for keyDownEvents, then we'll always call onSubmitEditing, even if the key was intended to be marked Handled by the keyDownEvents prop.

Note, this wasn't a problem before because you could just use keyDownEvents={[{code: 'Enter', handledEventPhase: Capturing}]} to mark the event as Handled in the preview phase, and the KeyDown event that was previously used for onSubmitEditing would not be called.

[rectified95]

Got it. Then, I have a few questions:

1. Since UpdateProperties will be called at least once (and potentially many times during the lifespan of the component), do we need still need the initial registration up in registerEvents()? Not sure how expensive these are, though..
2. This seems to result in the re-registration of the Preview handler every time that UpdateProperties is called for a TextInput with keyDownEvents specified - can we avoid that?
3. Just to confirm - do you need to switch from listening to KeyDown to PreviewKeyDown, so that you can stop the submission on 'Enter'?

[rozele]

1. We still need the initial registration in case keyDownEvents is never set.
2. I don't believe it's that expensive, but it will only be re-registered any time someone changes keyDownEvents, which is likely to be infrequent. It's probably not worth the added complexity to add a state field that signals when we've already re-registered.
3. Not exactly. We now need to handle onSubmitEditing in PreviewKeyDown as opposed to KeyDown because we want submitKeyEvents to apply even to TextBox with AcceptsReturn == true. If we used KeyDown, there would be no way to intercept 'Enter' before it created a newline character.

[rectified95]

If we subscribe to PreviewKeyDown for onSubmitEditing before we subscribe to PreviewKeyDown for keyDownEvents, then we'll always call onSubmitEditing, even if the key was intended to be marked Handled by the keyDownEvents prop.

Just for my information - this relies on the event handlers being called in the order of their registration for a given event type - is that guaranteed not to change (and documented somewhere)?

[rectified95]

I haven't added anything to TextInput.windows.js (though it works w/o declaring the prop types) and this should probably include an e2e test / update to RNTester. Will work on those once we decide if this is worth landing.

Can you add some examples to RNTester? Otheriwse, I think it looks great.

[rozele]

@rectified95 Added an RNTester example:

playground.2021-04-09.12-30-18.mp4