Initial implementation of new-style refs

[sophiebits]

Depends on/includes #1758.

cf. #1373

This particular implementation doesn't attempt to do anything smart about async resolution -- .then always runs one of its arguments immediately. It can be used in any situation that refs can currently be used (and can also be used without an owner, which is a plus).

We can enhance this later to do something more intelligent when using refs during updates.

cc @jordwalke @sebmarkbage

[facebook-github-bot]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Facebook open source project. Thanks!

[jordwalke]

One cool feature of the async refs, is that it makes it impossible (or at least difficult/fragile) for anyone to access a ref inside of a render method.

[syranide]

Updated https:/facebook/react/wiki/Projects#fix-refs

[jordwalke]

So it sounds like the only thing left to do on this one is to make the refs .then actually asynchronous (on a different event loop) so that program behavior is predictable. Was that @sebmarkbage's only concern?

[sophiebits]

I think so. You also wanted some test cases around cloneWithProps and transferPropsTo. Do you want to support having more than one ref? Right now cloneWithProps just warns you if you clone a component with a (string) ref.

[jordwalke]

With this diff, cloning a component with (this type of) ref should be okay because refs won't be tied to any particular owner. So that means multiple components can retain a reference to the ref.
Yeah, some test cases. But also - it would be great to not put the refs callbacks on another event loop cycle - that can be pretty far in the future (many ms). So can we figure out a way to get them to work like setImmediate?

I'd say it's bad for any program to be effected by whether or not your refs are resolved in a blocking manner, (at the moment you invoke .then()). But it's probably not as bad for program behavior to be effected by whether or not your ref is resolved at a later time towards the end of the current event loop, or on a different event loop.

So that being said, @sebmarkbage: Can we just make sure the then() is resolved later, but no ton a different event loop? Then this should be fairly compatible with whatever promise library we pull in. If it doesn't have completely identical behavior, at least it will be very close.

[jordwalke]

Under those terms, we can hide this feature behind React.__usePromiseRefs = true/false that I can flip to try it out.

[sophiebits]

This doesn't work on initial render because of how the batching currently works and also doesn't work if you access it outside of a lifecycle method, like in an event handler. Not sure how serious a problem that is for you @jordwalke.

[sebmarkbage]

Let's call setImmediate something else (such as asap). setImmediate doesn't do exactly what we want here and probably won't be standardized. Something else will be standardized with a different name, so the upgrade path to a real polyfill is confusing.

Also, I think that we should make _owner + string an API of createElement that creates a first-class ref behind the scene that updates this.refs. That way we can deprecate the old style in the core.

I still hate this API (even though I originally came up with it) but I don't have a better idea for now.