Merge pull request #52 from commitd/sh/51

feat(usemergedrefs): add a hook to merge refs

Author: stuarthendren

src/index.ts

@@ -9,6 +9,7 @@ export * from './useHover'
 export * from './useInterval'
 export * from './useKeyboard'
 export * from './useLocalState'
+export * from './useMergedRefs'
 export * from './useModal'
 export * from './usePoll'
 export * from './useTimeout'

src/useMergedRefs/index.ts

@@ -0,0 +1 @@
+export * from './useMergedRefs'

src/useMergedRefs/useMergedRefs.stories.tsx

@@ -0,0 +1,85 @@
+import { Column, Input, Text } from '@committed/components'
+import { Meta, Story } from '@storybook/react'
+import React, { useRef } from 'react'
+import { useBoolean, useHover, useKeyboard } from '../'
+import { useMergedRefs } from './useMergedRefs'
+
+export interface UseMergedRefsDocsProps<T> {
+  /** spread array of refs to be merged, T extends `HTMLElement` */
+  refs?: Array<
+    React.RefCallback<T> | React.MutableRefObject<T> | undefined | null
+  >
+}
+
+/**
+ * useMergedRefs merges the passed refs into a single memoized ref function.
+ *
+ * ```ts
+ * const ExampleComponent = React.forwardRef((props, forwardedRef) => {
+ *   const ref = React.useRef();
+ *   return <div {...props} ref={useMergeRefs(ref, forwardedRef)} />;
+ * });
+ * ```
+ *
+ * @param refs spread array of refs to be merged
+ */
+export const UseMergedRefsDocs = <T extends HTMLElement>(
+  props: UseMergedRefsDocsProps<T>
+) => null
+
+export default {
+  title: 'Hooks/useMergedRefs',
+  component: UseMergedRefsDocs,
+  excludeStories: ['UseMergedRefsDocs'],
+} as Meta
+
+const ExampleComponent = React.forwardRef<HTMLInputElement>(
+  (props, forwardedRef) => {
+    const internalRef = React.useRef<HTMLInputElement>(null)
+    const [isHovered] = useHover(internalRef)
+    const mergedRef = useMergedRefs<HTMLInputElement>(forwardedRef, internalRef)
+
+    return (
+      <Input
+        css={{
+          color: isHovered ? '$primary' : '$primaryContrast',
+        }}
+        ref={mergedRef}
+      />
+    )
+  }
+)
+
+const Template: Story = () => {
+  // const ExampleComponent = React.forwardRef<HTMLInputElement>(
+  //   (props, forwardedRef) => {
+  //     const internalRef = React.useRef<HTMLInputElement>(null)
+  //     const [isHovered] = useHover(internalRef)
+  //     const mergedRef = useMergedRefs<HTMLInputElement>(forwardedRef, internalRef)
+  //
+  //     return (
+  //       <Input
+  //         css={{
+  //           color: isHovered ? '$primary' : '$primaryContrast',
+  //         }}
+  //         ref={mergedRef}
+  //       />
+  //     )
+  //   }
+  // )
+
+  const externalRef = useRef<HTMLInputElement>(null)
+
+  const [typing, { setTrue, setFalse }] = useBoolean(false)
+  useKeyboard('', setFalse, { event: 'keyup', element: externalRef })
+  useKeyboard('', setTrue, { event: 'keydown', element: externalRef })
+
+  return (
+    <Column gap>
+      <ExampleComponent ref={externalRef} />
+      <Text>{typing ? 'Typing...' : ``}</Text>
+    </Column>
+  )
+}
+
+export const Default = Template.bind({})

src/useMergedRefs/useMergedRefs.test.ts

@@ -0,0 +1,40 @@
+import { renderHook } from '@testing-library/react-hooks'
+import React from 'react'
+import { useMergedRefs } from '.'
+
+test('Should provide initial null', () => {
+  const { result: first } = renderHook(() => useMergedRefs())
+  expect(first.current).toBeNull()
+})
+test('Should be null if all supplied null', () => {
+  const { result: first } = renderHook(() => useMergedRefs(null, null))
+  expect(first.current).toBeNull()
+})
+
+test('useMergedRefs should merge the refs', () => {
+  const testVal = true
+  const refAsFunc = jest.fn()
+  const refAsObj = { current: undefined }
+
+  const { result: first } = renderHook(() => useMergedRefs(refAsFunc, refAsObj))
+  expect(first.current).not.toBeNull()
+
+  first.current?.(testVal)
+
+  expect(refAsFunc).toHaveBeenCalledTimes(1)
+  expect(refAsFunc).toHaveBeenCalledWith(testVal)
+  expect(refAsObj.current).toBe(testVal)
+})
+
+test('useMergedRefs should not fail if invalid values', () => {
+  const refAsInvalid = { invalid: undefined }
+
+  const { result: first } = renderHook(() =>
+    useMergedRefs(null, (refAsInvalid as unknown) as React.Ref<string>)
+  )
+  // Would be valid if null here
+  expect(first.current).not.toBeNull()
+
+  // should not throw
+  first.current?.('testVal')
+})

src/useMergedRefs/useMergedRefs.ts

@@ -0,0 +1,39 @@
+import React, { useMemo } from 'react'
+
+type Ref<T> =
+  | React.RefCallback<T | null>
+  | React.MutableRefObject<T | null>
+  | undefined
+  | null
+
+/**
+ * useMergedRefs merges the passed refs into a single memoized ref function.
+ *
+ * ```ts
+ * const ExampleComponent = React.forwardRef((props, forwardedRef) => {
+ *   const ref = React.useRef();
+ *   return <div {...props} ref={useMergeRefs(ref, forwardedRef)} />;
+ * });
+ * ```
+ *
+ * @param refs spread array of refs to be merged
+ */
+export function useMergedRefs<T>(
+  ...refs: Ref<T>[]
+): React.RefCallback<T> | null {
+  return useMemo(() => {
+    if (refs.every((ref) => ref == null)) {
+      return null
+    }
+    return (value: T) => {
+      refs.forEach((ref) => {
+        if (typeof ref === 'function') {
+          ref(value)
+        } else if (ref != null && 'current' in ref) {
+          ref.current = value
+        }
+      })
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, refs)
+}