Merge pull request #23 from commitd/useUnuseControllableState

Adding useControllable hook

Author: stuarthendren

Diff for: package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.3.0",
+  "version": "0.4.0",
   "name": "@committed/hooks",
   "description": "Committed hooks library",
   "author": "Committed",
@@ -74,8 +74,8 @@
     "@material-ui/icons": "^4.9.1",
     "@material-ui/lab": "^4.0.0-alpha.56",
     "@size-limit/preset-small-lib": "^4.6.2",
-    "@storybook/addon-essentials": "^6.0.28",
-    "@storybook/react": "^6.0.28",
+    "@storybook/addon-essentials": "^6.1.14",
+    "@storybook/react": "^6.1.14",
     "@storybook/storybook-deployer": "^2.8.7",
     "@testing-library/jest-dom": "^5.11.5",
     "@testing-library/react": "^11.1.0",

Diff for: src/index.ts

@@ -11,3 +11,4 @@ export * from './usePoll'
 export * from './useTimeout'
 export * from './useTitle'
 export * from './useTrackedState'
+export * from './useControllableState'

Diff for: src/useControllableState/index.ts

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

Diff for: src/useControllableState/useControllableState.stories.tsx

@@ -0,0 +1,63 @@
+import React from 'react'
+import { Story, Meta } from '@storybook/react'
+import { useControllableState } from '.'
+import { CheckToken } from '@committed/components'
+import { action } from '@storybook/addon-actions'
+
+export interface UseControllableStateDocsProps<T> {
+  /** The controlled value (of type T) or undefined for an uncontrolled value */
+  value: T | undefined
+  /** The dispatch handler for state changes or undefined for when an uncontrolled value, ignored if uncontrolled*/
+  setValue: React.Dispatch<React.SetStateAction<T>> | undefined
+  /** The initial state value, or state initializer for when uncontrolled, ignored if controlled  */
+  initialState?: T | (() => T | undefined) | undefined
+}
+
+/**
+ * useControllableState hook for when the state may be controlled or uncontrolled.
+ *
+ * Returns as the standard useState hook, but has additional props of a controlled value and a controlled change handler.
+ * Set these using the components incoming props for the state, if defined they will be used, if not you get the standard useState behaviour.
+ */
+export const UseControllableStateDocs = <T extends any>(
+  props: UseControllableStateDocsProps<T>
+) => null
+
+export default {
+  title: 'Hooks/useControllableState',
+  component: UseControllableStateDocs,
+  excludeStories: ['UseControllableStateDocs'],
+} as Meta
+
+const Template: Story<UseControllableStateDocsProps<boolean>> = ({
+  value,
+  setValue,
+}) => {
+  const [state, setState] = useControllableState(value, setValue, false)
+  return (
+    <CheckToken
+      color="primary"
+      selected={state}
+      onClick={() => setState(!state)}
+    >
+      {value === undefined ? 'Uncontrolled' : 'Controlled'}
+    </CheckToken>
+  )
+}
+
+export const Default = Template.bind({})
+Default.args = {}
+
+export const Controlled = Template.bind({})
+Controlled.args = {
+  value: true,
+  setValue: action('setValue'),
+}
+Controlled.parameters = {
+  docs: {
+    description: {
+      story:
+        'This is a controlled example, clicking does not change the value but registers the click in the actions',
+    },
+  },
+}

Diff for: src/useControllableState/useControllableState.test.ts

@@ -0,0 +1,135 @@
+import { renderHook, act } from '@testing-library/react-hooks'
+import { useControllableState } from '.'
+
+let spy: jest.SpyInstance<void, [message?: any, ...optionalParams: any[]]>
+interface TestArgs {
+  value: boolean | undefined
+  setValue: React.Dispatch<React.SetStateAction<boolean>> | undefined
+}
+
+type TestReturn = [boolean, React.Dispatch<React.SetStateAction<boolean>>]
+
+const value = true
+const altValue = false
+let setValue: jest.Mock<any, any>
+
+beforeEach(() => {
+  setValue = jest.fn()
+  spy = jest.spyOn(console, 'warn').mockImplementation()
+})
+
+afterEach(() => {
+  spy.mockRestore()
+})
+
+test('Should provide initial output as setState when uncontrolled', () => {
+  const { result } = renderHook(() =>
+    useControllableState(undefined, undefined)
+  )
+  expect(result.current[0]).toBeUndefined()
+  expect(typeof result.current[1]).toBe('function')
+})
+
+test('Should use default value if not controlled', () => {
+  const { result } = renderHook(() =>
+    useControllableState(undefined, undefined, value)
+  )
+  expect(result.current[0]).toBe(value)
+})
+
+test('Should call default initializer not controlled', () => {
+  const initializer = jest.fn().mockImplementation(() => value)
+
+  const { result } = renderHook(() =>
+    useControllableState(undefined, undefined, initializer)
+  )
+  expect(result.current[0]).toBe(value)
+  expect(initializer).toHaveBeenCalled()
+})
+
+test('Should provide initial output as setState when controlled', () => {
+  const { result } = renderHook(() => useControllableState(true, setValue))
+  expect(result.current[0]).toBe(value)
+  expect(typeof result.current[1]).toBe('function')
+})
+
+test('Should not use initializer if controlled', () => {
+  const { result } = renderHook(() =>
+    useControllableState(value, setValue, false)
+  )
+  expect(result.current[0]).toBe(value)
+})
+
+test('Should not call default initializer controlled', () => {
+  const initializer = jest.fn().mockImplementation(() => value)
+
+  const { result } = renderHook(() =>
+    useControllableState(value, setValue, initializer)
+  )
+  expect(result.current[0]).toBe(value)
+  expect(initializer).not.toHaveBeenCalled()
+})
+
+test('setValue should change value when uncontrolled', () => {
+  const { result } = renderHook(() =>
+    useControllableState<boolean | undefined>(undefined, undefined)
+  )
+
+  const value = true
+
+  act(() => {
+    result.current[1](value)
+  })
+  expect(result.current[0]).toEqual(value)
+})
+
+test('setValue should call supplied function when controlled', () => {
+  const { result } = renderHook(() =>
+    useControllableState<boolean | undefined>(value, setValue)
+  )
+
+  act(() => {
+    result.current[1](altValue)
+  })
+  expect(result.current[0]).toEqual(value)
+  expect(setValue).toHaveBeenCalledWith(altValue)
+})
+
+test('should warn if switching from uncontrolled to controlled', () => {
+  const { rerender } = renderHook<TestArgs, TestReturn>(
+    ({ value, setValue }) =>
+      useControllableState<boolean>(value, setValue, false),
+    { initialProps: { value: undefined, setValue: undefined } }
+  )
+
+  rerender({ value: value, setValue: setValue })
+  expect(console.warn).toHaveBeenCalledTimes(1)
+})
+
+test('should warn if switching from uncontrolled to controlled', () => {
+  const { rerender } = renderHook<TestArgs, TestReturn>(
+    ({ value, setValue }) =>
+      useControllableState<boolean>(value, setValue, false),
+    { initialProps: { value: value, setValue: setValue } }
+  )
+
+  rerender({ value: undefined, setValue: undefined })
+  expect(console.warn).toHaveBeenCalledTimes(1)
+})
+
+test('Should not warn in production mode', () => {
+  const previousEnv = process.env.NODE_ENV
+  process.env.NODE_ENV = 'production'
+  try {
+    const { rerender } = renderHook<TestArgs, TestReturn>(
+      ({ value, setValue }) =>
+        useControllableState<boolean>(value, setValue, false),
+      { initialProps: { value: value, setValue: setValue } }
+    )
+
+    rerender({ value: undefined, setValue: undefined })
+    expect(console.warn).toHaveBeenCalledTimes(0)
+  } finally {
+    process.env.NODE_ENV = previousEnv
+  }
+})

Diff for: src/useControllableState/useControllableState.ts

@@ -0,0 +1,57 @@
+import { useEffect, useRef, useState } from 'react'
+
+/** type guard to check if value or function */
+function isValue<T>(arg: T | (() => T | undefined)): arg is T {
+  return typeof arg !== 'function'
+}
+
+/** no operation  */
+// eslint-disable-next-line @typescript-eslint/no-empty-function
+function noop() {}
+
+/**
+ * useControllableState hook for when the state may be controlled or uncontrolled.
+ *
+ * Returns as the standard useState hook, but has additional props of a controlled value and a controlled change handler.
+ * Set these using the components incoming props for the state, if defined they will be used, if not you get the standard useState behaviour.
+ *
+ * @param {T | undefined} value The controlled value (of type T) or undefined for an uncontrolled value
+ * @param {React.Dispatch<React.SetStateAction<T>> | undefined} setValue  The dispatch handler for state changes or undefined for when an uncontrolled value, ignored if uncontrolled
+ * @param {T | (() => T | undefined) | undefined} initialState  The initial state value, or state initializer for when uncontrolled, ignored if controlled
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function useControllableState<T = any>(
+  value: T | undefined,
+  setValue: React.Dispatch<React.SetStateAction<T>> | undefined,
+  initialState?: T | (() => T | undefined) | undefined
+): [T, React.Dispatch<React.SetStateAction<T>>] {
+  const { current: wasControlled } = useRef(value !== undefined)
+  const isControlled = value !== undefined
+
+  const [uncontrolled, setUncontrolled] = useState<T | undefined>(() => {
+    if (value === undefined) {
+      if (initialState !== undefined) {
+        return isValue(initialState) ? initialState : initialState()
+      }
+    }
+    return undefined
+  })
+  let effect = noop
+  if (process.env.NODE_ENV !== 'production') {
+    effect = function () {
+      if (wasControlled !== isControlled) {
+        console.warn(
+          'Components should not switch from uncontrolled to controlled (or vice versa)'
+        )
+      }
+    }
+  }
+  useEffect(effect, [isControlled])
+
+  return [
+    (wasControlled ? value : uncontrolled) as T,
+    (wasControlled ? setValue : setUncontrolled) as React.Dispatch<
+      React.SetStateAction<T>
+    >,
+  ]
+}

Diff for: src/useDebounce/useDebounce.stories.tsx

@@ -30,7 +30,9 @@ export interface UseDebounceDocsProps<T> {
  * Adapted from <https://usehooks.com/>, if more functionality or control is required use [use-debounce](https://github.com/xnimorz/use-debounce).
  *
  */
-export const UseDebounceDocs: React.FC<UseDebounceDocsProps<any>> = () => null
+export const UseDebounceDocs = <T extends any>(
+  props: UseDebounceDocsProps<T>
+) => null
 
 export default {
   title: 'Hooks/useDebounce',

Diff for: src/useDebounce/useDebounce.ts

@@ -9,8 +9,8 @@ import { useEffect, useState } from 'react'
  *
  * Adapted from <https://usehooks.com/>.
  *
- * @param value The value to debounce updates for
- * @param delay The time to delay updates by (ms)
+ * @param {T} value The value to debounce updates for
+ * @param { number | null} delay The time to delay updates by (ms)
  */
 export function useDebounce<T>(
   value: T,

Diff for: src/useEventListener/useEventListener.stories.tsx

@@ -10,7 +10,7 @@ export interface UseEventListenerDocsProps<
   eventName: string
   /** the callback function to call on the event firing  */
   handler: ((event: Event) => void) | null
-  /** (optional) reference for the element to add the listener too */
+  /** (optional) reference for the element to add the listener to T extends `HTMLElement` and defaults to `HTMLDivElement` */
   element?: RefObject<T>
 }
 
@@ -27,8 +27,9 @@ export interface UseEventListenerDocsProps<
  * @param handler the callback function
  * @param element (optional) reference for the element
  */
-export const UseEventListenerDocs: React.FC<UseEventListenerDocsProps> = () =>
-  null
+export const UseEventListenerDocs = <T extends HTMLElement>(
+  props: UseEventListenerDocsProps<T>
+) => null
 
 export default {
   title: 'Hooks/useEventListener',

Diff for: src/useHover/useHover.stories.tsx

@@ -4,7 +4,7 @@ import { Box } from '@committed/components'
 import { useHover } from '.'
 
 export interface UseHoverDocsProps<T extends HTMLElement> {
-  /** element reference to track hover on */
+  /** element reference to track hover on, T extends `HTMLElement` */
   element?: RefObject<T>
 }
 
@@ -13,7 +13,9 @@ export interface UseHoverDocsProps<T extends HTMLElement> {
  *
  * @param element reference for the element to add the listener too
  */
-export const UseHoverDocs: React.FC<UseHoverDocsProps<HTMLElement>> = () => null
+export const UseHoverDocs = <T extends HTMLElement>(
+  props: UseHoverDocsProps<T>
+) => null
 
 export default {
   title: 'Hooks/useHover',

Diff for: src/useKeyboard/useKeyboard.stories.tsx

@@ -14,7 +14,7 @@ import React, { useRef } from 'react'
 import { KEYBOARD_MODIFIERS, Keys, useKeyboard } from '.'
 import { useBoolean } from '../useBoolean/useBoolean'
 
-export interface UseKeyboardDocsProps<T> {
+export interface UseKeyboardDocsProps<T extends HTMLElement = HTMLDivElement> {
   /** The definition of the key filter.
    *
    * The basic definition is a string filter separated with the `+` e.g. `'a'` or `'ctrl+a'`
@@ -29,7 +29,7 @@ export interface UseKeyboardDocsProps<T> {
   handler: ((event: KeyboardEvent) => void) | null
   /** Options
    *
-   * - __element__ provide a ref for the element to bind to (defaults to `window`)
+   * - __element__ provide a ref for the element to bind to (defaults to `window`) (T extends `HTMLElement`)
    * - __event__ the key event to listen to (defaults to `keydown`)
    * - __ignoreKey__ set `true` to turn off the `KeyCode` test no other match (defaults to `false`)
    * - __ignoreRepeat__ set `true` to ignore repeat events (defaults to `false`)
@@ -45,7 +45,9 @@ export interface UseKeyboardDocsProps<T> {
 /**
  * useKeyboard hook to add a callback to be called on the use of the keyboard under specified circumstances.
  */
-export const UseKeyboardDocs: React.FC<UseKeyboardDocsProps<any>> = () => null
+export const UseKeyboardDocs = <T extends HTMLElement = HTMLDivElement>(
+  props: UseKeyboardDocsProps<T>
+) => null
 
 export default {
   title: 'Hooks/useKeyboard',

Diff for: src/useLocalState/useLocalState.stories.tsx

@@ -19,8 +19,8 @@ export interface UseLocalStateDocsProps<T> {
  * useLocalState hook behaves like `React.useState`, returning the state and a function to set the value.
  * In addition, the value is put in local storage against the given key and is persisted through page refresh.
  */
-export const UseLocalStateDocs: React.FC<UseLocalStateDocsProps<any>> = (
-  _props: UseLocalStateDocsProps<any>
+export const UseLocalStateDocs = <T extends any>(
+  props: UseLocalStateDocsProps<T>
 ) => null
 
 export default {

Diff for: src/useTrackedState/useTrackedState.stories.tsx

@@ -14,9 +14,9 @@ export interface UseTrackedStateDocsProps<T> {
  *
  * @param initialState (optional) starting state or function to provide starting state
  */
-export const UseTrackedStateDocs: React.FC<UseTrackedStateDocsProps<
-  any
->> = () => null
+export const UseTrackedStateDocs = <T extends any>(
+  props: UseTrackedStateDocsProps<T>
+) => null
 
 export default {
   title: 'Hooks/useTrackedState',