Calling Mandatory Getter props
Hilly Landscape in the Village
of Şimon.
...there's a lot going on with the attributes and the handlers and the ref and the other properties...
Let's assume that we have the following scenario. We have a custom hook that returns getter props, and we want to make sure that those getter props are called correctly. But, first things first:
What is a getter prop?
It's a function that gets returned from the custom hook, which is supposed to be
called and its result used for some reason. Let's take the getInputProps
getter prop from downshift:
import * as React from 'react'
import {useCombobox} from 'downshift'
const items = ['red', 'green', 'blue']
const {getInputProps} = useCombobox({
items,
})
return (
<div>
<input {...getInputProps()} />
</div>
)
The getInputProps result is an object with properties such as:
aria-labelledby, aria-expanded, role, onChange, onClick etc. These
properties are going to make our input more or less acting like a combobox. The
combobox logic is kept inside the custom hook, the inputs are retrieved through
the event handler functions (onClick, onChange) and the combobox related
information is passed through the other attributes (aria-labelledby,
aria-expanded). Of course, there are many more handlers and properties, but we
are keeping it simple for now.
There's also the ref property that is going to be returned from
getInputProps, and this is needed in order to allow useCombobox to access
the input element and perform some custom .focus() actions when needed.
The Problem
Given that there's a lot going on with the attributes and the handlers and the
ref and the other properties, we want to make sure that the getInputProps
getter function is called correctly.
- First of all, we want to make sure that it is called.
- Secondly, that is called on an
<input>element, or in such a way that it has access to an<input>element. - Thirdly, in case it is not called correctly, we want to inform the user through a console error and give them enough information to fix the getter function call.
- Moreover, we also want to show the console error in the development environment, not production. -In addition, we would like to show this error only on the first render, as we believe it's enough in terms of checks and informations.
- Last, but not least, we will also provide an escape hatch to avoid getting
this error if the consumer just cannot call
getInputPropsproperly on the first render.- We are going to document this escape hatch and make sure the consumer knows
why we are adding it. Ideally, if a consumer will use the escape hatch, they
are aware how
getInputPropsworks, how it should be called, and if they, for some reason, cannot call it on first render (using a Portal for example), they will use the escape hatch to avoid the error, but they will test their implementation to make sure that it works as it would by callinggetInputPropsnormally.
- We are going to document this escape hatch and make sure the consumer knows
why we are adding it. Ideally, if a consumer will use the escape hatch, they
are aware how
The Solution
Inside the getInputProps function we return, we would like to have a mechanism
that checks whether the function is called withing the right conditions. We can
do so with a function to which we supply the call parameters. This function will
be called at render time, since getInputProps is called on render time. The
actual check happens after the first render, so we will involve a
React.useEffect hook. After a bit of thinking, the solution is actually
simple: a custom React hook that will keep call information inside a React ref.
This call information will be supplied by a function which we will return from
the hook. The returned function will store the call information inside that ref.
And inside the effect function, we will perform the check and show the errors if
needed.
The Tests
We actually have a good and simple solution in mind, so let's see what do we actually expect from this solution.
- we want an error displayed when
getInputPropsis not called. - we want an error displayed if
getInputPropsis not called with a ref pointing to an element. - we don't want an error displayed if
getInputPropsis not called on subsequent renders. - we don't want an error displayed if
getInputPropsis called correctly. - we don't want an error displayed if we use the escape hatch provided and
getInputPropsis not called with a ref pointing to an element.
We will use
React Testing Library
renderHook and together with Jest, we will set up our
tests suite.
describe('non production errors', () => {
beforeAll(() => {
jest.spyOn(console, 'error').mockImplementation(() => {})
})
afterAll(() => {
jest.restoreAllMocks()
})
test('will be displayed if getInputProps is not called', () => {
renderHook(() => {
// we just render the hook, we don't call getInputProps.
useCombobox({items})
})
expect(console.error.mock.calls[0][0]).toMatchInlineSnapshot(
`downshift: You forgot to call the getInputProps getter function on your component / element.`,
)
})
test('will be displayed if element ref is not set and suppressRefError is false', () => {
renderHook(() => {
const {getInputProps} = useCombobox({
items,
})
getInputProps()
})
expect(console.error.mock.calls[0][0]).toMatchInlineSnapshot(
`downshift: The ref prop "ref" from getInputProps was not applied correctly on your element.`,
)
})
test('will not be displayed if getInputProps is not called on subsequent renders', () => {
let firstRender = true
const {rerender} = renderHook(() => {
const {getInputProps} = useCombobox({
items,
})
if (firstRender) {
firstRender = false
getInputProps({}, {suppressRefError: true})
}
})
rerender()
expect(console.error).not.toHaveBeenCalled()
})
test('will not be displayed if called with a correct ref', () => {
// we supply a mock ref function to getInputProps.
const refFn = jest.fn()
const inputNode = {}
renderHook(() => {
const {getInputProps} = useCombobox({
items,
})
// getInputProps returns a ref function which will make the element
// usable both outside and inside useCombobox.
const {ref} = getInputProps({
ref: refFn,
})
// we call the final ref function received with a dummy node.
ref(inputNode)
})
expect(console.error).not.toHaveBeenCalled()
})
test('will not be displayed if element ref is not set and suppressRefError is true', () => {
renderHook(() => {
const {getInputProps} = useCombobox({
items,
})
getInputProps({}, {suppressRefError: true})
})
expect(console.error).not.toHaveBeenCalled()
})
})
The tests are quite self explanatory given our 5 expected use cases. For now, they will obviously fail, and we will consider our job done once we write the implementation and the tests are green.
The Implementation
To recap, the getter prop is called on render, so we would like our check to be performed after the render. We will store the call information inside a React ref, and we will check it using a React useEffect. Since we need our check to be performed in development mode, not production, we will define the custom hook like this:
let useGetterPropsCalledChecker = () => {}
if (process.env.NODE_ENV !== 'production') {
useGetterPropsCalledChecker = () => {
// the actual implementation.
}
}
First and foremost, we would like to set up our ref object that we will use for the check.
if (process.env.NODE_ENV !== 'production') {
useGetterPropsCalledChecker = (...propKeys) => {
const getterPropsCalledRef = useRef(
propKeys.reduce((acc, propKey) => {
acc[propKey] = {}
return acc
}, {}),
)
}
}
And we will call this hook inside useCombobox like this:
useGetterPropsCalledChecker(
'getInputProps',
'getToggleButtonProps',
'getMenuProps',
)
Notice that we will most definitely want the hook to check that other getter props are called correctly as well. We are going to stick to getInputProps here purely for explanatory purposes. Anyway, for each prop key we pass to the hook, we will create an empty object container inside the ref. We add this empty object as we want, during our checking phase, to be able to tell if the getter prop with that prop name was not called. We cannot perform this check if we do not store any initial information about the getter props. What prop keys should we actually check, right?
Next, we want to give the consumer, which is the getter prop function, to be able to store the call information. For that, we will return a function from the hook, which stores this information within the ref.
if (process.env.NODE_ENV !== 'production') {
useGetterPropsCalledChecker = (...propKeys) => {
const getterPropsCalledRef = useRef(
propKeys.reduce((acc, propKey) => {
acc[propKey] = {}
return acc
}, {}),
)
}
const setGetterPropCallInfo = useCallback(
(propKey, suppressRefError, refKey, elementRef) => {
getterPropsCalledRef.current[propKey] = {
suppressRefError,
refKey,
elementRef,
}
},
[],
)
return setGetterPropCallInfo
}
And the usage within getInputProps is going to be something like this:
// this is going to end up on the input element via getInputProps
const inputRef = React.useRef(null)
const getInputProps = useCallback(
({refKey = 'ref', ref, ...rest} = {}, {suppressRefError = false} = {}) => {
setGetterPropCallInfo('getInputProps', suppressRefError, refKey, inputRef)
// rest of the logic
return {
[refKey]: mergeRefsUtil(ref, inputNode => {
inputRef.current = inputNode
}),
// the rest of the attributes and handlers that will end on the input
}
},
)
In case the above ref logic is not clear, it ensures that all ref objects have
access to the same input element. We need the input ref in useCombobox. The
consumer might also need the input ref for some additional logic, hence the
merge of these ref objects and passing the merged object to the <input>
element. Also, suppressRefError is the escape hatch we talked about
previously.
Now the checking part. We have the initial object created for each getter prop
on render phase, when useGetterPropsCalledChecker is called. We have the call
information stored when getInputProps is called, also on render phase. Now we
have to check if the function is called correctly, on first render only, so we
add a React useEffect hook inside our custom hook:
useEffect(() => {
Object.keys(getterPropsCalledRef.current).forEach(propKey => {
const propCallInfo = getterPropsCalledRef.current[propKey]
if (!Object.keys(propCallInfo).length) {
// eslint-disable-next-line no-console
console.error(
`downshift: You forgot to call the ${propKey} getter function on your component / element.`,
)
return
}
})
})
Our first test should pass. If the object is empty, then it means that we did not call the getter prop at all, so we show an error. If the getter prop is actually called, then we need to check if the element exists, which means that the getter prop is called correctly on an element.
useEffect(() => {
Object.keys(getterPropsCalledRef.current).forEach(propKey => {
const propCallInfo = getterPropsCalledRef.current[propKey]
if (!Object.keys(propCallInfo).length) {
// eslint-disable-next-line no-console
console.error(
`downshift: You forgot to call the ${propKey} getter function on your component / element.`,
)
return
}
const {refKey, elementRef} = propCallInfo
if (!elementRef?.current) {
// eslint-disable-next-line no-console
console.error(
`downshift: The ref prop "${refKey}" from ${propKey} was not applied correctly on your element.`,
)
}
})
})
Our second test should now pass. The element check is, sure, not ideal, since we're not checking for an actual HTML input element, but let's say it suffices for now. The fourth test which checks that there is no error logged was passing already, but now with the actual element check, we make sure that, when it's passing, it does so for the right reason.
To fix the second test, we need our hook to be called only once, on first
render, so we add [] as the second parameter to useEffect.
And to fix the fifth test, which checks the escape hatch, we will also involve
the suppressRefError parameter from the call information. Our final
implementation will look like this.
if (process.env.NODE_ENV !== 'production') {
useGetterPropsCalledChecker = (...propKeys) => {
const getterPropsCalledRef = useRef(
propKeys.reduce((acc, propKey) => {
acc[propKey] = {}
return acc
}, {}),
)
useEffect(() => {
Object.keys(getterPropsCalledRef.current).forEach(propKey => {
const propCallInfo = getterPropsCalledRef.current[propKey]
if (!Object.keys(propCallInfo).length) {
// eslint-disable-next-line no-console
console.error(
`downshift: You forgot to call the ${propKey} getter function on your component / element.`,
)
return
}
const {suppressRefError, refKey, elementRef} = propCallInfo
if (suppressRefError) {
return
}
if (!elementRef?.current) {
// eslint-disable-next-line no-console
console.error(
`downshift: The ref prop "${refKey}" from ${propKey} was not applied correctly on your element.`,
)
}
})
}, [])
const setGetterPropCallInfo = useCallback(
(propKey, suppressRefError, refKey, elementRef) => {
getterPropsCalledRef.current[propKey] = {
suppressRefError,
refKey,
elementRef,
}
},
[],
)
return setGetterPropCallInfo
}
}
Recap
Basically, we initialize an empty object for each getter prop we want to check,
using the getterPropsCalledRef React ref object. Then we return the
setGetterPropCallInfo function that will store information for each getter
function when called. Finally, inside the useEffect function, for each getter
prop, we get the call info from the ref, we check for an empty object and show
the getter function not getting called error. In case we our object in not
empty, we get the call information, and do nothing if suppressRefError is
true. Otherwise, we check the actual element ref and show an error if it's
falsy.
We may go even further with the tests and check if the hook is actually an empty object on production environments, but at this point I'm not sure if it's possible to implement such a test, or if it's even worth it. Bottom line is that, using this custom hook, we are able to perform the function getting called check, or other checks as well, in order to make sure our consumers are doing the right thing and the solution we ship works for them.
Praia da Arrifana,
Portugal.