RN: Create useMergeRefs Utility

Summary:
Creates `useMergeRefs` which will be used by components in React Native.

Changelog:
[Internal]

Reviewed By: lunaleaps

Differential Revision: D28862439

fbshipit-source-id: 60eac7bcd6cceb06ee82181386b4712d642f5404

Author: yungsters

Libraries/Utilities/__tests__/useMergeRefs-test.js

@@ -0,0 +1,228 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @emails oncall+react_native
+ * @flow strict-local
+ * @format
+ */
+
+import useMergeRefs from '../useMergeRefs';
+import * as React from 'react';
+import {View} from 'react-native';
+import {act, create} from 'react-test-renderer';
+
+/**
+ * TestView provide a component execution environment to test hooks.
+ */
+function TestView({name, refs}) {
+  const mergeRef = useMergeRefs(...refs);
+  return <View ref={mergeRef} testID={name} />;
+}
+
+/**
+ * TestViewInstance provides a pretty-printable replacement for React instances.
+ */
+class TestViewInstance {
+  name: string;
+
+  constructor(name: string) {
+    this.name = name;
+  }
+
+  // $FlowIgnore[unclear-type] - Intentional.
+  static fromValue(value: any): ?TestViewInstance {
+    const testID = value?.props?.testID;
+    return testID == null ? null : new TestViewInstance(testID);
+  }
+
+  static named(name: string) {
+    // $FlowIssue[prop-missing] - Flow does not support type augmentation.
+    return expect.testViewInstance(name);
+  }
+}
+
+/**
+ * extend.testViewInstance makes it easier to assert expected values. But use
+ * TestViewInstance.named instead of extend.testViewInstance because of Flow.
+ */
+expect.extend({
+  testViewInstance(received, name) {
+    const pass = received instanceof TestViewInstance && received.name === name;
+    return {pass};
+  },
+});
+
+/**
+ * Creates a registry that records the values assigned to the mock refs created
+ * by either of the two returned callbacks.
+ */
+function mockRefRegistry<T>(): {
+  mockCallbackRef: (name: string) => T => mixed,
+  mockObjectRef: (name: string) => {current: T, ...},
+  registry: $ReadOnlyArray<{[string]: T}>,
+} {
+  const registry = [];
+  return {
+    mockCallbackRef: (name: string): (T => mixed) => current => {
+      registry.push({[name]: TestViewInstance.fromValue(current)});
+    },
+    mockObjectRef: (name: string): {current: T, ...} => ({
+      // $FlowIgnore[unsafe-getters-setters] - Intentional.
+      set current(current) {
+        registry.push({[name]: TestViewInstance.fromValue(current)});
+      },
+    }),
+    registry,
+  };
+}
+
+test('accepts a callback ref', () => {
+  let root;
+
+  const {mockCallbackRef, registry} = mockRefRegistry();
+  const refA = mockCallbackRef('refA');
+
+  act(() => {
+    root = create(<TestView name="foo" refs={[refA]} />);
+  });
+
+  expect(registry).toEqual([{refA: TestViewInstance.named('foo')}]);
+
+  act(() => {
+    root = create(<TestView name="bar" refs={[refA]} />);
+  });
+
+  expect(registry).toEqual([
+    {refA: TestViewInstance.named('foo')},
+    {refA: TestViewInstance.named('bar')},
+  ]);
+
+  act(() => {
+    root.unmount();
+  });
+
+  expect(registry).toEqual([
+    {refA: TestViewInstance.named('foo')},
+    {refA: TestViewInstance.named('bar')},
+    {refA: null},
+  ]);
+});
+
+test('accepts an object ref', () => {
+  let root;
+
+  const {mockObjectRef, registry} = mockRefRegistry();
+  const refA = mockObjectRef('refA');
+
+  act(() => {
+    root = create(<TestView name="foo" refs={[refA]} />);
+  });
+
+  expect(registry).toEqual([{refA: TestViewInstance.named('foo')}]);
+
+  act(() => {
+    root = create(<TestView name="bar" refs={[refA]} />);
+  });
+
+  expect(registry).toEqual([
+    {refA: TestViewInstance.named('foo')},
+    {refA: TestViewInstance.named('bar')},
+  ]);
+
+  act(() => {
+    root.unmount();
+  });
+
+  expect(registry).toEqual([
+    {refA: TestViewInstance.named('foo')},
+    {refA: TestViewInstance.named('bar')},
+    {refA: null},
+  ]);
+});
+
+test('invokes refs in order', () => {
+  let root;
+
+  const {mockCallbackRef, mockObjectRef, registry} = mockRefRegistry();
+  const refA = mockCallbackRef('refA');
+  const refB = mockObjectRef('refB');
+  const refC = mockCallbackRef('refC');
+  const refD = mockObjectRef('refD');
+
+  act(() => {
+    root = create(<TestView name="foo" refs={[refA, refB, refC, refD]} />);
+  });
+
+  expect(registry).toEqual([
+    {refA: TestViewInstance.named('foo')},
+    {refB: TestViewInstance.named('foo')},
+    {refC: TestViewInstance.named('foo')},
+    {refD: TestViewInstance.named('foo')},
+  ]);
+
+  act(() => {
+    root.unmount();
+  });
+
+  expect(registry).toEqual([
+    {refA: TestViewInstance.named('foo')},
+    {refB: TestViewInstance.named('foo')},
+    {refC: TestViewInstance.named('foo')},
+    {refD: TestViewInstance.named('foo')},
+    {refA: null},
+    {refB: null},
+    {refC: null},
+    {refD: null},
+  ]);
+});
+
+// This is actually undesirable behavior, but it's what we have so let's make
+// sure it does not change unexpectedly.
+test('invokes all refs if any ref changes', () => {
+  let root;
+
+  const {mockCallbackRef, registry} = mockRefRegistry();
+  const refA = mockCallbackRef('refA');
+  const refB = mockCallbackRef('refB');
+
+  act(() => {
+    root = create(<TestView name="foo" refs={[refA, refB]} />);
+  });
+
+  expect(registry).toEqual([
+    {refA: TestViewInstance.named('foo')},
+    {refB: TestViewInstance.named('foo')},
+  ]);
+
+  const refAPrime = mockCallbackRef('refAPrime');
+  act(() => {
+    root.update(<TestView name="foo" refs={[refAPrime, refB]} />);
+  });
+
+  expect(registry).toEqual([
+    {refA: TestViewInstance.named('foo')},
+    {refB: TestViewInstance.named('foo')},
+    {refA: null},
+    {refB: null},
+    {refAPrime: TestViewInstance.named('foo')},
+    {refB: TestViewInstance.named('foo')},
+  ]);
+
+  act(() => {
+    root.unmount();
+  });
+
+  expect(registry).toEqual([
+    {refA: TestViewInstance.named('foo')},
+    {refB: TestViewInstance.named('foo')},
+    {refA: null},
+    {refB: null},
+    {refAPrime: TestViewInstance.named('foo')},
+    {refB: TestViewInstance.named('foo')},
+    {refAPrime: null},
+    {refB: null},
+  ]);
+});

Libraries/Utilities/useMergeRefs.js

@@ -0,0 +1,44 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @flow strict
+ * @format
+ */
+
+import {useCallback} from 'react';
+
+type CallbackRef<T> = T => mixed;
+type ObjectRef<T> = {current: T, ...};
+
+type Ref<T> = CallbackRef<T> | ObjectRef<T>;
+
+/**
+ * Constructs a new ref that forwards new values to each of the given refs. The
+ * given refs will always be invoked in the order that they are supplied.
+ *
+ * WARNING: A known problem of merging refs using this approach is that if any
+ * of the given refs change, the returned callback ref will also be changed. If
+ * the returned callback ref is supplied as a `ref` to a React element, this may
+ * lead to problems with the given refs being invoked more times than desired.
+ */
+export default function useMergeRefs<T>(
+  ...refs: $ReadOnlyArray<?Ref<T>>
+): CallbackRef<T> {
+  return useCallback(
+    (current: T) => {
+      for (const ref of refs) {
+        if (ref != null) {
+          if (typeof ref === 'function') {
+            ref(current);
+          } else {
+            ref.current = current;
+          }
+        }
+      }
+    },
+    [...refs], // eslint-disable-line react-hooks/exhaustive-deps
+  );
+}