Backport useRefInit and htmlMain added in major version WIP

Author: greglittlefield-wf

lib/hooks.dart

@@ -392,7 +392,46 @@ T useContext<T>(Context<T> context) => ContextHelpers.unjsifyNewContext(React.us
 /// ```
 ///
 /// Learn more: <https://reactjs.org/docs/hooks-reference.html#useref>.
-Ref<T> useRef<T>([T initialValue]) => Ref.useRefInit(initialValue);
+Ref<T> useRef<T>([
+  // This will eventually be deprecated, but not just yet.
+  // @Deprecated('Use `useRefInit` instead to create refs with initial values.'
+  //     ' Since the argument to useRefInit is required, it can be used to create a Ref that holds a non-nullable type,'
+  //     ' whereas this function can only create Refs with nullable type arguments.')
+  T initialValue,
+]) =>
+    useRefInit(initialValue);
+
+/// Returns a mutable [Ref] object with [Ref.current] property initialized to [initialValue].
+///
+/// Changes to the [Ref.current] property do not cause the containing [DartFunctionComponent] to re-render.
+///
+/// The returned [Ref] object will persist for the full lifetime of the [DartFunctionComponent].
+/// Compare to [createRef] which returns a new [Ref] object on each render.
+///
+/// > __Note:__ there are two [rules for using Hooks](https://reactjs.org/docs/hooks-rules.html):
+/// >
+/// > * Only call Hooks at the top level.
+/// > * Only call Hooks from inside a [DartFunctionComponent].
+///
+/// __Example__:
+///
+/// ```dart
+/// UseRefTestComponent(Map props) {
+///   final countRef = useRefInit(0);
+///
+///   handleClick([_]) {
+///     ref.current = ref.current + 1;
+///     window.alert('You clicked ${ref.current} times!');
+///   }
+///
+///   return react.Fragment({}, [
+///     react.button({'onClick': handleClick}, ['Click me!']),
+///   ]);
+/// }
+/// ```
+///
+/// Learn more: <https://reactjs.org/docs/hooks-reference.html#useref>.
+Ref<T> useRefInit<T>(T initialValue) => Ref.useRefInit(initialValue);
 
 /// Returns a memoized version of the return value of [createFunction].
 ///

lib/react.dart

@@ -1699,8 +1699,11 @@ dynamic li = validateJsApiThenReturn(() => ReactDomComponentFactoryProxy('li'));
 /// The HTML `<link>` `LinkElement`.
 dynamic link = validateJsApiThenReturn(() => ReactDomComponentFactoryProxy('link'));
 
+@Deprecated('Use htmlMain instead. To be removed in react 7.0.0.')
+dynamic main = htmlMain;
+
 /// The HTML `<main>` `Element`.
-dynamic main = validateJsApiThenReturn(() => ReactDomComponentFactoryProxy('main'));
+dynamic htmlMain = validateJsApiThenReturn(() => ReactDomComponentFactoryProxy('main'));
 
 /// The HTML `<map>` `MapElement`.
 dynamic map = validateJsApiThenReturn(() => ReactDomComponentFactoryProxy('map'));

test/hooks_test.dart

@@ -510,6 +510,55 @@ main() {
       });
     });
 
+    group('useRefInit -', () {
+      DivElement mountNode;
+      ButtonElement reRenderButton;
+      Ref initRef;
+      StateHook<int> renderIndex;
+
+      setUpAll(() {
+        mountNode = DivElement();
+
+        final UseRefTest = react.registerFunctionComponent((props) {
+          initRef = useRefInit(mountNode);
+
+          renderIndex = useState(1);
+
+          return react.Fragment({}, [
+            react.p({}, [renderIndex.value]),
+            react.button({
+              'ref': (ref) => reRenderButton = ref as ButtonElement,
+              'onClick': (_) => renderIndex.setWithUpdater((prev) => prev + 1)
+            }, [
+              're-render'
+            ]),
+          ]);
+        });
+
+        react_dom.render(UseRefTest({}), mountNode);
+      });
+
+      group('correctly initializes a Ref object', () {
+        test('with current property set to the initial value given', () {
+          expect(initRef, isA<Ref>());
+          expect(initRef.current, mountNode);
+        });
+      });
+
+      group('the returned Ref', () {
+        test('will persist even after the component re-renders', () {
+          expect(renderIndex.value, 1);
+          expect(initRef.current, mountNode, reason: 'Ref object initially created on first render');
+
+          react_test_utils.Simulate.click(reRenderButton);
+
+          expect(renderIndex.value, 2);
+          expect(initRef.current, mountNode,
+              reason: 'useRef returns the same Ref object on every render for the full lifetime of the component');
+        });
+      });
+    });
+
     group('useMemo -', () {
       ReactDartFunctionComponentFactoryProxy UseMemoTest;
       StateHook<int> count;