Merge pull request #262 from cleandart/chainRefs

Add chainRef/chainRefList utilities

Author: greglittlefield-wf

.travis.yml

@@ -16,6 +16,6 @@ before_script:
   - pub run dependency_validator -i build_runner,build_test,build_web_compilers
 
 script:
-  - pub run build_runner test --release -- -p chrome
-  - pub run build_runner test -- -p chrome
+  - pub run build_runner test --release -- --preset dart2js
+  - pub run build_runner test -- --preset dartdevc
   - dart ./tool/run_consumer_tests.dart --orgName Workiva --repoName over_react --testCmd "pub run dart_dev test -P dartdevc"

dart_test.yaml

@@ -0,0 +1,12 @@
+# Specify chrome and VM as default platforms for running all tests,
+# then let the `@TestOn()` annotations determine which suites actually run
+platforms:
+  - chrome
+  - vm
+
+presets:
+  dart2js:
+    exclude_tags: no-dart2js
+
+  dartdevc:
+    exclude_tags: no-dartdevc

lib/react_client.dart

@@ -30,6 +30,7 @@ import 'package:react/src/ddc_emulated_function_name_bug.dart' as ddc_emulated_f
 
 export 'package:react/react_client/react_interop.dart' show ReactElement, ReactJsComponentFactory, inReactDevMode, Ref;
 export 'package:react/react.dart' show ReactComponentFactoryProxy, ComponentFactory;
+export 'package:react/src/react_client/chain_refs.dart' show chainRefs, chainRefList;
 
 /// The type of `Component.ref` specified as a callback.
 ///

lib/react_client/react_interop.dart

@@ -82,15 +82,27 @@ class Ref<T> {
   T get current {
     final jsCurrent = jsRef.current;
 
-    if (jsCurrent is! Element) {
-      final dartCurrent = (jsCurrent as ReactComponent)?.dartComponent;
+    // Note: this ReactComponent check will pass for many types of JS objects,
+    // so don't assume for sure that it's a ReactComponent
+    if (jsCurrent is! Element && jsCurrent is ReactComponent) {
+      final dartCurrent = jsCurrent.dartComponent;
 
       if (dartCurrent != null) {
         return dartCurrent as T;
       }
     }
     return jsCurrent;
   }
+
+  /// Used internally to combine refs https://github.com/facebook/react/issues/13029
+  @protected
+  set current(T value) {
+    if (value is Component) {
+      jsRef.current = value.jsThis;
+    } else {
+      jsRef.current = value;
+    }
+  }
 }
 
 /// A JS ref object returned by [React.createRef].
@@ -101,6 +113,10 @@ class Ref<T> {
 @anonymous
 class JsRef {
   external dynamic get current;
+
+  /// Used internally to combine refs https://github.com/facebook/react/issues/13029
+  @protected
+  external set current(dynamic value);
 }
 
 /// Automatically passes a [Ref] through a component to one of its children.

lib/src/react_client/chain_refs.dart

@@ -0,0 +1,97 @@
+import 'package:js/js_util.dart';
+import 'package:react/react_client/react_interop.dart';
+
+/// Returns a ref that updates both [ref1] and [ref2], effectively
+/// allowing you to set multiple refs.
+///
+/// Useful when you're using ref forwarding and want to also set your own ref.
+///
+/// For more information on this problem, see https://github.com/facebook/react/issues/13029.
+///
+/// Inputs can be callback refs, [createRef]-based refs ([Ref]),
+/// or raw JS `createRef` refs ([JsRef]).
+///
+/// If either [ref1] or [ref2] is null, the other ref will be passed through.
+///
+/// If both are null, null is returned.
+///
+/// ```dart
+/// final Example = forwardRef((props, ref) {
+///   final localRef = useRef<FooComponent>();
+///   return Foo({
+///     ...props,
+///     'ref': chainRefs(localRef, ref),
+///   });
+/// });
+/// ```
+dynamic chainRefs(dynamic ref1, dynamic ref2) {
+  return chainRefList([ref1, ref2]);
+}
+
+/// Like [chainRefs], but takes in a list of [refs].
+dynamic chainRefList(List<dynamic> refs) {
+  final nonNullRefs = refs.where((ref) => ref != null).toList(growable: false);
+
+  // Wrap in an assert so iteration doesn't take place unnecessarily
+  assert(() {
+    nonNullRefs.forEach(_validateChainRefsArg);
+    return true;
+  }());
+
+  // Return null if there are no refs to chain
+  if (nonNullRefs.isEmpty) return null;
+
+  // Pass through the ref if there's nothing to chain it with
+  if (nonNullRefs.length == 1) return nonNullRefs[0];
+
+  // Adapted from https://github.com/smooth-code/react-merge-refs/tree/v1.0.0
+  //
+  // Copyright 2019 Smooth Code
+  //
+  // Permission is hereby granted, free of charge, to any person obtaining a
+  // copy of this software and associated documentation files (the 'Software'),
+  // to deal in the Software without restriction, including without limitation
+  // the rights to use, copy, modify, merge, publish, distribute, sublicense,
+  // and/or sell copies of the Software, and to permit persons to whom the
+  // Software is furnished to do so, subject to the following conditions:
+  //
+  // The above copyright notice and this permission notice shall be included in
+  // all copies or substantial portions of the Software.
+  //
+  // THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+  // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+  // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+  // THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+  // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+  // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+  // DEALINGS IN THE SOFTWARE.
+  void _chainedRef(value) {
+    for (final ref in nonNullRefs) {
+      if (ref is Function) {
+        ref(value);
+      } else if (ref is Ref) {
+        // ignore: invalid_use_of_protected_member
+        ref.current = value;
+      } else {
+        // ignore: invalid_use_of_protected_member
+        (ref as JsRef).current = value;
+      }
+    }
+  }
+
+  return _chainedRef;
+}
+
+void _validateChainRefsArg(dynamic ref) {
+  if (ref is Function(Null) ||
+      ref is Ref ||
+      // Need to duck-type since `is JsRef` will return true for most JS objects.
+      (ref is JsRef && hasProperty(ref, 'current'))) {
+    return;
+  }
+
+  if (ref is String) throw AssertionError('String refs cannot be chained');
+  if (ref is Function) throw AssertionError('callback refs must take a single argument');
+
+  throw AssertionError('Invalid ref type: $ref');
+}

test/factory/common_factory_tests.dart

@@ -6,6 +6,7 @@ import 'dart:js_util';
 
 import 'package:meta/meta.dart';
 import 'package:react/react_client/js_backed_map.dart';
+import 'package:react/src/react_client/chain_refs.dart';
 import 'package:test/test.dart';
 
 import 'package:react/react_client.dart';
@@ -303,15 +304,11 @@ void refTests<T>(ReactComponentFactoryProxy factory, {void verifyRefValue(dynami
     verifyRefValue(refObject.current);
   });
 
-  _typedCallbackRefTests<T>(factory);
-}
-
-void _typedCallbackRefTests<T>(react.ReactComponentFactoryProxy factory) {
-  if (T == dynamic) {
-    throw ArgumentError('Generic parameter T must be specified');
-  }
-
   group('has functional callback refs when they are typed as', () {
+    if (T == dynamic) {
+      throw ArgumentError('Generic parameter T must be specified');
+    }
+
     test('`dynamic Function(dynamic)`', () {
       T fooRef;
       callbackRef(dynamic ref) {
@@ -334,6 +331,31 @@ void _typedCallbackRefTests<T>(react.ReactComponentFactoryProxy factory) {
       expect(fooRef, isA<T>(), reason: 'should be the correct type, not be a NativeJavaScriptObject/etc.');
     });
   });
+
+  group('chainRefList works', () {
+    test('with all different types of values, ignoring null', () {
+      final testCases = RefTestCase.allChainable<T>();
+
+      T refValue;
+      rtu.renderIntoDocument(factory({
+        'ref': chainRefList([
+          (ref) => refValue = ref,
+          null,
+          null,
+          ...testCases.map((t) => t.ref),
+        ]),
+      }));
+      // Test setup check: verify refValue is correct,
+      // which we'll use below to verify refs were updated.
+      verifyRefValue(refValue);
+
+      for (final testCase in testCases) {
+        testCase.verifyRefWasUpdated(refValue);
+      }
+    });
+
+    // Other cases tested in chainRefList's own tests
+  });
 }
 
 void _childKeyWarningTests(Function factory, {Function(ReactElement Function()) renderWithUniqueOwnerName}) {

test/react_client/chain_refs_test.dart

@@ -0,0 +1,95 @@
+@TestOn('browser')
+@JS()
+library react.chain_refs_test;
+
+import 'package:js/js.dart';
+import 'package:react/react_client.dart';
+import 'package:react/src/react_client/chain_refs.dart';
+import 'package:test/test.dart';
+
+import '../util.dart';
+
+main() {
+  group('Ref chaining utils:', () {
+    testRef(_) {}
+
+    group('chainRefs', () {
+      // Chaining and arg validation is tested via chainRefList.
+
+      group('skips chaining and passes through arguments when', () {
+        test('both arguments are null', () {
+          expect(chainRefs(null, null), isNull);
+        });
+
+        test('the first argument is null', () {
+          expect(chainRefs(null, testRef), same(testRef));
+        });
+
+        test('the second argument is null', () {
+          expect(chainRefs(testRef, null), same(testRef));
+        });
+      });
+    });
+
+    group('chainRefList', () {
+      // Chaining is tested functionally in refTests with each component type.
+
+      group('skips chaining and passes through arguments when', () {
+        test('the list is empty', () {
+          expect(chainRefList([]), isNull);
+        });
+
+        test('there is a single element in the list', () {
+          expect(chainRefList([testRef]), same(testRef));
+        });
+
+        test('the list has only null values', () {
+          expect(chainRefList([null, null]), isNull);
+        });
+
+        test('there is a single non-null element in the list', () {
+          expect(chainRefList([null, testRef]), same(testRef));
+        });
+      });
+
+      group('raises an assertion when inputs are invalid:', () {
+        test('strings', () {
+          expect(() => chainRefList([testRef, 'bad ref']), throwsA(isA<AssertionError>()));
+        });
+
+        test('unsupported function types', () {
+          expect(() => chainRefList([testRef, () {}]), throwsA(isA<AssertionError>()));
+        });
+
+        test('other objects', () {
+          expect(() => chainRefList([testRef, Object()]), throwsA(isA<AssertionError>()));
+        });
+
+        // test JS interop objects since type-checking anonymous interop objects
+        test('non-createRef anonymous JS interop objects', () {
+          expect(() => chainRefList([testRef, JsTypeAnonymous()]), throwsA(isA<AssertionError>()));
+        });
+
+        // test JS interop objects since type-checking anonymous interop objects
+        test('non-createRef JS interop objects', () {
+          expect(() => chainRefList([testRef, JsType()]), throwsA(isA<AssertionError>()));
+        });
+      }, tags: 'no-dart2js');
+
+      test('does not raise an assertion for valid input refs', () {
+        expect(() => chainRefList(RefTestCase.allChainable().map((r) => r.ref).toList()), returnsNormally);
+      });
+    });
+  });
+}
+
+@JS()
+@anonymous
+class JsTypeAnonymous {
+  external factory JsTypeAnonymous();
+}
+
+@JS()
+class JsType {
+  external JsType();
+}

test/react_client/chain_refs_test.html

@@ -0,0 +1,18 @@
+<!DOCTYPE html>
+<html>
+<head lang="en">
+    <meta charset="UTF-8">
+    <title></title>
+    <script src="packages/react/react_with_addons.js"></script>
+    <script src="packages/react/react_dom.js"></script>
+
+    <script>
+        function JsType() {}
+    </script>
+
+    <link rel="x-dart-test" href="chain_refs_test.dart">
+    <script src="packages/test/dart.js"></script>
+</head>
+<body>
+</body>
+</html>

test/react_client/react_interop_test.dart

@@ -1,3 +1,6 @@
+@TestOn('browser')
+library react.react_interop_test;
+
 import 'dart:html';
 
 import 'package:react/react_client.dart';