[core] add AsyncControllableTextArea based on AsyncControllableInput & add async control option for TextArea component #6312

nurseiit · 2023-08-01T16:47:21Z

Related to #4678.

Checklist

Includes tests
Update documentation

Changes proposed in this pull request:

a. (~~Extends the existing AsyncControllableInput with an option to render a textarea element. (the type of Props is quite complicated now, and I am open to suggestions to further simplify it)~~) -- initial approach. Ended up with a useAsyncControllableValue hook to use in AsyncControllableTextArea component.

b. Adds asyncControl option to TextArea component that ~~reuses AsyncControllableInput~~ uses AsyncControllableTextArea when set to true.

Reviewers should focus on:

Basically the only thing I was afraid of and tried to avoid is any external incompatibilities with the API and component props types. But since AsyncControllableInput is not exported externally and only used as a part of other components I think we can get away with the introduced complex types.

Also I generalised the tests for AsyncControllableInput instead of copying them, one can argue this was unnecessary, but I am also open for any suggestions on this.

Thanks!

adidahiya · 2023-08-01T16:57:56Z

add correct types & copy tests from default input

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

adidahiya · 2023-08-01T22:19:07Z

fix lint, object order

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

nurseiit · 2023-08-02T13:00:46Z

packages/core/src/components/forms/asyncControllableInputProps.ts

+    // NOTE: these are copied from the React.HTMLAttributes interface definition.
+    onChange?: React.ChangeEventHandler<AsyncControllableElement<T>> | undefined;
+    onCompositionStart?: React.CompositionEventHandler<AsyncControllableElement<T>> | undefined;
+    onCompositionEnd?: React.CompositionEventHandler<AsyncControllableElement<T>> | undefined;


not sure if this is the best way to do it, but I would argue this is fine since this component is not exported directly.

I did not want to further complicate the types by excluding and extending the native interfaces above.

adidahiya · 2023-08-02T13:10:13Z

refactor tests

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

nurseiit · 2023-08-11T13:30:19Z

Hi @gluxon, any chance you could take a look a this? Thanks!

gluxon

Apologies for the late response — It took me a bit of time to come around to it, but I like how this takes advantage of generic types to ensure type safety of the input props.

A discussion of a long-term approach may make sense. Zooming out a bit, more recent React code tends to lean on hooks for component logic sharing. I think the need to add additional functionality to this existing AsyncControllableInput class component comes from the fact that it was written when component composition was a more common logic reuse pattern. In that prior world, this PR makes sense.

If we were to imagine an alternative hooks-based approach, I think adding support for new HTML textual input elements becomes significantly easier. This example isn't complete and likely fails to compile, but here's the rough direction I was thinking:

function AsyncControllableInput(props: P) {
    const { value, onChange, ...rest } = props;
    const { textInputProps } = useAsyncControlledValue({ value, onChange });

    return <input {...rest} {...textInputProps} />
}

function AsyncControllableTextarea(props: P) {
    const { value, onChange, ...rest } = props;
    const { textInputProps } = useAsyncControlledValue({ value, onChange });

    return <textarea {...rest} {...textInputProps} />
}

function useAsyncControllableValue(opts) {
    const [isComposing, setIsComposing] = React.useState(false);
    const [nextValue, setNextValue ] = React.useState(/* ... */);
    const [hasPendingUpdate, setHasPendingUpdate ] = React.useState(/* ... */);

    function onCompositionStart() {
        setIsComposing(true)
    }

    function onCompositionEnd() {
        setIsComposing(false)
    }

    const value = isComposing || hasPendingUpdate ? nextValue : value

    /* ... */

    return {
        value,
        onChange,
        onCompositionEnd,
        onCompositionStart
    };
}

Since this PR adds a new functionality, I do wonder if it makes sense to create a new AsyncControllableTextarea that's based upon the hook approach. We would then battle-test that purely new functionality before switching AsyncControllableInput to be implemented from the same hook in a future Blueprint release.

I'm also okay extending the existing AsyncControllableInput to be generic since it's private anyway. I do think the hook approach is the preferable long-term approach though. What do you think?

Basically the only thing I was afraid of and tried to avoid is any external incompatibilities with the API and component props types. But since AsyncControllableInput is not exported externally and only used as a part of other components I think we can get away with the introduced complex types.

I appreciate that! I scanned through the PR looking for changes to external APIs and don't see any other than the new asyncControl prop that was intended.

gluxon · 2023-08-14T17:33:26Z

packages/core/test/forms/asyncControllableInputTests.tsx

+describe("<AsyncControllableInput>", () => {
+    runAsyncControllableInputTests({ tagName: "input", inputType: "text" });
+    runAsyncControllableInputTests({ tagName: "textarea" });


I like the test deduplication here. Thanks for doing that.

What are your thoughts on describe.each? That would be another way to write this in more idiomatic Jest. https://jestjs.io/docs/api#describeeachtablename-fn-timeout

gluxon · 2023-08-14T18:17:22Z

packages/core/src/components/forms/textArea.tsx

@@ -170,13 +190,22 @@ export class TextArea extends AbstractPureComponent<TextAreaProps, TextAreaState
            };
        }

-        return (
+        return asyncControl ? (


Does this seem to work when testing live? The code changes look correct. Just wondering if <TextArea asyncControl /> works as expected.

nurseiit · 2023-08-15T09:48:00Z

Apologies for the late response — It took me a bit of time to come around to it, but I like how this takes advantage of generic types to ensure type safety of the input props.

A discussion of a long-term approach may make sense. Zooming out a bit, more recent React code tends to lean on hooks for component logic sharing. I think the need to add additional functionality to this existing AsyncControllableInput class component comes from the fact that it was written when component composition was a more common logic reuse pattern. In that prior world, this PR makes sense.

If we were to imagine an alternative hooks-based approach, I think adding support for new HTML textual input elements becomes significantly easier. This example isn't complete and likely fails to compile, but here's the rough direction I was thinking:
function AsyncControllableInput(props: P) {
    const { value, onChange, ...rest } = props;
    const { textInputProps } = useAsyncControlledValue({ value, onChange });

    return <input {...rest} {...textInputProps} />
}

function AsyncControllableTextarea(props: P) {
    const { value, onChange, ...rest } = props;
    const { textInputProps } = useAsyncControlledValue({ value, onChange });

    return <textarea {...rest} {...textInputProps} />
}

function useAsyncControllableValue(opts) {
    const [isComposing, setIsComposing] = React.useState(false);
    const [nextValue, setNextValue ] = React.useState(/* ... */);
    const [hasPendingUpdate, setHasPendingUpdate ] = React.useState(/* ... */);

    function onCompositionStart() {
        setIsComposing(true)
    }

    function onCompositionEnd() {
        setIsComposing(false)
    }

    const value = isComposing || hasPendingUpdate ? nextValue : value

    /* ... */

    return {
        value,
        onChange,
        onCompositionEnd,
        onCompositionStart
    };
}
Since this PR adds a new functionality, I do wonder if it makes sense to create a new AsyncControllableTextarea that's based upon the hook approach. We would then battle-test that purely new functionality before switching AsyncControllableInput to be implemented from the same hook in a future Blueprint release.

I'm also okay extending the existing AsyncControllableInput to be generic since it's private anyway. I do think the hook approach is the preferable long-term approach though. What do you think?

Basically the only thing I was afraid of and tried to avoid is any external incompatibilities with the API and component props types. But since AsyncControllableInput is not exported externally and only used as a part of other components I think we can get away with the introduced complex types.

I appreciate that! I scanned through the PR looking for changes to external APIs and don't see any other than the new asyncControl prop that was intended.

I really do like the hooks approach! That's what I was aiming for at first, but then gave up unfortunately. In any case, I will revisit this again with hooks. Thanks for reviewing!

…extarea

gluxon · 2023-08-17T00:00:02Z

I really do like the hooks approach! That's what I was aiming for at first, but then gave up unfortunately. In any case, I will revisit this again with hooks. Thanks for reviewing!

Please reach out if you want a second pair of eyes while looking at this! 🙂

nurseiit · 2023-08-18T15:40:10Z

I really do like the hooks approach! That's what I was aiming for at first, but then gave up unfortunately. In any case, I will revisit this again with hooks. Thanks for reviewing!

Please reach out if you want a second pair of eyes while looking at this! 🙂

Thanks! I updated the PR with hooks alternative based on the AsyncControllableInput component and your comment above. Let me know what do you think 😌

adidahiya · 2023-08-18T15:49:08Z

add more comments

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

gluxon

Thanks for working on this! I personally like how this came out. Just have a few more questions and I think we'll be ready to merge soon.

Played around with the latest hook-based version live. Seeing all the expected expected state updates.

packages/core/src/components/forms/asyncControllableTextArea.tsx

packages/core/src/components/forms/textArea.tsx

packages/core/src/components/forms/asyncControllableTextArea.tsx

packages/core/src/components/forms/useAsyncControllableValue.ts

gluxon · 2023-08-19T02:20:15Z

packages/core/src/components/forms/useAsyncControllableValue.ts

+            if (propValue === nextValue) {
+                // parent has processed and accepted our update
+                if (hasPendingUpdate) {
+                    setValue(propValue);
+                    setHasPendingUpdate(false);
+                } else if (value !== nextValue) {
+                    setValue(nextValue);
+                }


There might be opportunity to simplify this block. I know it was copied from the original version, but since we're rewriting it anyway, it might be cool to revisit.

Staring at this part, I think I can convince myself that these blocks are equivalent:

if (propValue === nextValue) { // parent has processed and accepted our update if (hasPendingUpdate) { setValue(propValue); setHasPendingUpdate(false); } else if (value !== nextValue) { setValue(nextValue); } } else {

if (propValue === nextValue) { // parent has processed and accepted our update setValue(propValue); setHasPendingUpdate(false); } else {

The theory being that

propValue and nextValue are the same, so either can be used to setValue.

React should no-op the setHasPendingUpdate(false) call if it's already false.

Taking this a bit further, I think the nested logic can be much flatter.

if (!isStateDerivationPaused) { const userTriggeredUpdate = nextValue !== value; if (userTriggeredUpdate && propValue === nextValue) { // parent has processed and accepted our update setValue(propValue); setHasPendingUpdate(false); } else if (userTriggeredUpdate && propValue === value) { // we have sent the update to our parent, but it has not been processed yet. just wait. // DO NOT set nextValue here, since that will temporarily render a potentially stale controlled value, // causing the cursor to jump once the new value is accepted if (!hasPendingUpdate) { setHasPendingUpdate(true); } } else if (userTriggeredUpdate || value !== propValue || hasPendingUpdate) { // accept controlled update, could be confirming or denying user action setValue(propValue); setNextValue(propValue); setHasPendingUpdate(false); } }

But I could definitely use help making sure I refactored that correctly. The general strategy was to propagate the userTriggeredUpdate condition down and then remove layers of nesting.

If you would rather not think about further refactors and prefer to keep the existing structure as-is to match the current getDerivedStateFromProps approach, I think that's okay too!

I refactored this bit to be flatter and (arguably) more readable than the initial getDerivedStateFromProps version in the latest commit. Thanks for the ideas above!

Looks good!

packages/core/src/components/forms/useAsyncControllableValue.ts

nurseiit · 2023-08-21T12:45:12Z

Thanks for the review @gluxon! Updated based on the latest comments / suggestions 👍

packages/core/test/forms/asyncControllableInputTests.tsx

adidahiya · 2023-08-21T12:55:01Z

flatten & simplify state derival + comments

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

gluxon

Thanks for the updates! I think everything looks good. Expecting to approve and merge once the discussion about tests https://github.com/palantir/blueprint/pull/6312/files/bdc07b6e4a19ef154d84cbc233943985c6f91cbd#r1300068035 wraps up.

packages/core/test/forms/asyncControllableInputTests.tsx

nurseiit · 2023-08-22T13:00:08Z

Updated the tests & added a clarifying note at the top of the test file ☺️ Thanks for reviewing this @gluxon!

adidahiya · 2023-08-22T13:06:46Z

dedup tests & add note

Build artifact links for this commit: documentation | landing | table | demo

This is an automated comment from the deploy-preview CircleCI job.

gluxon

Thank you for the improvements and new feature @nurseiit! 🎉

adidahiya

Thanks @nurseiit & @gluxon! I like the new approach of using the hook to implement this behavior. We should be able to migrate AsyncControllableInput to use it as well soon.

I can fix my minor review comments in a follow-up PR.

packages/core/src/components/forms/asyncControllableTextArea.tsx

adidahiya · 2023-08-24T13:20:28Z

packages/core/src/components/forms/useAsyncControllableValue.ts

+
+import * as React from "react";
+
+interface IUseAsyncControllableValueProps<E extends HTMLInputElement | HTMLTextAreaElement> {


nit: same comment about avoiding the I prefix

nurseiit added 2 commits August 1, 2023 15:36

async control TextArea component

93f9f0c

add correct types & copy tests from default input

ee920ff

fix lint, object order

dd62954

nurseiit added 2 commits August 2, 2023 12:49

move types to their own file

7407ca9

refactor tests

c28308c

nurseiit commented Aug 2, 2023

View reviewed changes

nurseiit changed the title ~~WIP: async control option for TextArea~~ AsyncControllableInput to render textarea element & async control option for TextArea component Aug 2, 2023

nurseiit marked this pull request as ready for review August 2, 2023 13:09

nurseiit requested a review from adidahiya August 2, 2023 13:11

nurseiit changed the title ~~AsyncControllableInput to render textarea element & async control option for TextArea component~~ [core] AsyncControllableInput to render textarea element & async control option for TextArea component Aug 2, 2023

nurseiit added Package: core Type: enhancement labels Aug 2, 2023

gluxon self-assigned this Aug 8, 2023

gluxon reviewed Aug 14, 2023

View reviewed changes

Merge remote-tracking branch 'origin/develop' into na/async-control-t…

6548a62

…extarea

nurseiit added 3 commits August 17, 2023 15:12

tests pass, but WIP

b5c2643

remove example

c562eaa

add more comments

276814e

gluxon reviewed Aug 19, 2023

View reviewed changes

nurseiit added 3 commits August 21, 2023 13:10

forwardRef for TextArea

29c07fe

useRef empty type with undefined

cd41247

flatten & simplify state derival + comments

bdc07b6

nurseiit commented Aug 21, 2023

View reviewed changes

packages/core/test/forms/asyncControllableInputTests.tsx Show resolved Hide resolved

gluxon reviewed Aug 21, 2023

View reviewed changes

packages/core/test/forms/asyncControllableInputTests.tsx Show resolved Hide resolved

packages/core/test/forms/asyncControllableInputTests.tsx Show resolved Hide resolved

dedup tests & add note

c35297a

nurseiit changed the title ~~[core] AsyncControllableInput to render textarea element & async control option for TextArea component~~ [core] add AsyncControllableTextarea based on AsyncControllableInput & add async control option for TextArea component Aug 22, 2023

nurseiit changed the title ~~[core] add AsyncControllableTextarea based on AsyncControllableInput & add async control option for TextArea component~~ [core] add AsyncControllableTextArea based on AsyncControllableInput & add async control option for TextArea component Aug 22, 2023

gluxon approved these changes Aug 23, 2023

View reviewed changes

gluxon merged commit 55f525d into develop Aug 23, 2023

gluxon deleted the na/async-control-textarea branch August 23, 2023 16:41

adidahiya reviewed Aug 24, 2023

View reviewed changes

adidahiya added a commit that referenced this pull request Aug 28, 2023

[core] chore: minor code style fixes for #6312

3b48c46

adidahiya mentioned this pull request Aug 28, 2023

[core] chore: minor code style fixes for #6312 #6335

Merged

adidahiya added a commit that referenced this pull request Aug 28, 2023

[core] chore: minor code style fixes for #6312 (#6335)

6ade0a8

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[core] add AsyncControllableTextArea based on AsyncControllableInput & add async control option for TextArea component #6312

[core] add AsyncControllableTextArea based on AsyncControllableInput & add async control option for TextArea component #6312

nurseiit commented Aug 1, 2023 •

edited

Loading

adidahiya commented Aug 1, 2023

adidahiya commented Aug 1, 2023

nurseiit Aug 2, 2023

nurseiit Aug 2, 2023

adidahiya commented Aug 2, 2023

nurseiit commented Aug 11, 2023

gluxon left a comment

gluxon Aug 14, 2023

gluxon Aug 14, 2023

nurseiit commented Aug 15, 2023

gluxon commented Aug 17, 2023

nurseiit commented Aug 18, 2023

adidahiya commented Aug 18, 2023

gluxon left a comment •

edited

Loading

gluxon Aug 19, 2023 •

edited

Loading

gluxon Aug 19, 2023

nurseiit Aug 21, 2023

gluxon Aug 21, 2023

nurseiit commented Aug 21, 2023

adidahiya commented Aug 21, 2023

gluxon left a comment

nurseiit commented Aug 22, 2023

adidahiya commented Aug 22, 2023

gluxon left a comment

adidahiya left a comment

adidahiya Aug 24, 2023


		import * as React from "react";

		interface IUseAsyncControllableValueProps<E extends HTMLInputElement \| HTMLTextAreaElement> {

[core] add AsyncControllableTextArea based on AsyncControllableInput & add async control option for TextArea component #6312

[core] add AsyncControllableTextArea based on AsyncControllableInput & add async control option for TextArea component #6312

Conversation

nurseiit commented Aug 1, 2023 • edited Loading

Checklist

Changes proposed in this pull request:

Reviewers should focus on:

adidahiya commented Aug 1, 2023

add correct types & copy tests from default input

adidahiya commented Aug 1, 2023

fix lint, object order

Choose a reason for hiding this comment

Choose a reason for hiding this comment

adidahiya commented Aug 2, 2023

refactor tests

nurseiit commented Aug 11, 2023

gluxon left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nurseiit commented Aug 15, 2023

gluxon commented Aug 17, 2023

nurseiit commented Aug 18, 2023

adidahiya commented Aug 18, 2023

add more comments

gluxon left a comment • edited Loading

Choose a reason for hiding this comment

gluxon Aug 19, 2023 • 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

nurseiit commented Aug 21, 2023

adidahiya commented Aug 21, 2023

flatten & simplify state derival + comments

gluxon left a comment

Choose a reason for hiding this comment

nurseiit commented Aug 22, 2023

adidahiya commented Aug 22, 2023

dedup tests & add note

gluxon left a comment

Choose a reason for hiding this comment

adidahiya left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nurseiit commented Aug 1, 2023 •

edited

Loading

gluxon left a comment •

edited

Loading

gluxon Aug 19, 2023 •

edited

Loading