[LG-5553] feat(hooks): add useControlled hook for generic controlled/uncontrolled state management (#3153)

* feat(hooks): add useControlledInputValue hook with tests

* refactor(hooks): rename useControlledValue to useControlledInputValue and update tests accordingly

* refactor: replace useControlledValue with useControlledInputValue across multiple components

* refactor(hooks): restore useControlledValue export and clean up imports in useControlledInputValue

* refactor(hooks): update type definitions and imports in useControlledInputValue and useControlledValue

* refactor(hooks): update type definitions

* doc(hook): add changesets

* docs(hooks): minor to major

* refactor(hooks): remove useControlledInputValue and update components to use useControlledValue

* test(hooks): file useControlled spec file name

* refactor(hooks): remove console warning from useControlled and add to useControlledValue

* refactor(hooks): add console warning for useControlled and remove from useControlledValue

* refactor(hooks): reorder imports in useControlled for consistency

* refactor(hooks): update console log to be more generic

Author: shaneeza

.changeset/new-dryers-invite.md

@@ -0,0 +1,6 @@
+---
+'@leafygreen-ui/hooks': minor
+---
+
+- Creates `useControlled` hook. This hook is a more generic version of `useControlledValue` that can be used for any component.
+- Refactors `useControlledValue` to use `useControlled` under the hood.

packages/hooks/src/index.ts

@@ -1,6 +1,7 @@
 export { useAutoScroll } from './useAutoScroll';
 export { default as useAvailableSpace } from './useAvailableSpace';
 export { useBackdropClick } from './useBackdropClick';
+export { useControlled } from './useControlled';
 export { useControlledValue } from './useControlledValue';
 export { type DynamicRefGetter, useDynamicRefs } from './useDynamicRefs';
 export { default as useEscapeKey } from './useEscapeKey';

packages/hooks/src/useControlled/index.ts

@@ -0,0 +1 @@
+export { useControlled } from './useControlled';

packages/hooks/src/useControlled/useControlled.spec.tsx

@@ -0,0 +1,275 @@
+import React, { ChangeEventHandler } from 'react';
+import { render } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+import { act, renderHook } from '@leafygreen-ui/testing-lib';
+
+import { useControlled } from './useControlled';
+
+const errorSpy = jest.spyOn(console, 'error');
+
+const renderUseControlledHook = <T extends any>(
+  ...[valueProp, callback, initial]: Parameters<typeof useControlled<T>>
+) => {
+  const result = renderHook(v => useControlled(v, callback, initial), {
+    initialProps: valueProp,
+  });
+
+  return result;
+};
+
+describe('packages/hooks/useControlled', () => {
+  beforeEach(() => {
+    errorSpy.mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    errorSpy.mockReset();
+  });
+
+  test('rendering without any arguments sets hook to uncontrolled', () => {
+    const { result } = renderUseControlledHook();
+    expect(result.current.isControlled).toEqual(false);
+  });
+
+  describe('accepts various value types', () => {
+    test('accepts number values', () => {
+      const { result } = renderUseControlledHook(5);
+      expect(result.current.value).toBe(5);
+    });
+
+    test('accepts boolean values', () => {
+      const { result } = renderUseControlledHook(false);
+      expect(result.current.value).toBe(false);
+    });
+
+    test('accepts array values', () => {
+      const arr = ['foo', 'bar'];
+      const { result } = renderUseControlledHook(arr);
+      expect(result.current.value).toBe(arr);
+    });
+
+    test('accepts object values', () => {
+      const obj = { foo: 'foo', bar: 'bar' };
+      const { result } = renderUseControlledHook(obj);
+      expect(result.current.value).toBe(obj);
+    });
+
+    test('accepts date values', () => {
+      const date = new Date('2023-08-23');
+      const { result } = renderUseControlledHook(date);
+      expect(result.current.value).toBe(date);
+    });
+
+    test('accepts multiple/union types', () => {
+      const { result, rerender } = renderUseControlledHook<string | number>(5);
+      expect(result.current.value).toBe(5);
+      rerender('foo');
+      expect(result.current.value).toBe('foo');
+    });
+  });
+
+  describe('Controlled', () => {
+    test('rendering with a value sets value and isControlled', () => {
+      const { result } = renderUseControlledHook('apple');
+      expect(result.current.isControlled).toBe(true);
+      expect(result.current.value).toBe('apple');
+    });
+
+    test('rerendering with a new value changes the value', () => {
+      const { rerender, result } = renderUseControlledHook('apple');
+      expect(result.current.value).toBe('apple');
+      rerender('banana');
+      expect(result.current.value).toBe('banana');
+    });
+
+    test('provided handler is called within `updateValue`', () => {
+      const handler = jest.fn();
+      const { result } = renderUseControlledHook<string>('apple', handler);
+      result.current.updateValue('banana');
+      expect(handler).toHaveBeenCalledWith('banana');
+    });
+
+    test('hook value does not change when `updateValue` is called', () => {
+      const { result } = renderUseControlledHook<string>('apple');
+      result.current.updateValue('banana');
+      // value doesn't change unless we explicitly change it
+      expect(result.current.value).toBe('apple');
+    });
+
+    test('setting value to undefined should keep the component controlled', () => {
+      const { rerender, result } = renderUseControlledHook('apple');
+      expect(result.current.isControlled).toBe(true);
+      act(() => rerender(undefined));
+      expect(result.current.isControlled).toBe(true);
+    });
+
+    test('initial value is ignored when controlled', () => {
+      const { result } = renderUseControlledHook<string>(
+        'apple',
+        () => {},
+        'banana',
+      );
+      expect(result.current.value).toBe('apple');
+    });
+
+    test('setUncontrolledValue does nothing for controlled components', () => {
+      const { result } = renderUseControlledHook('apple');
+      act(() => {
+        result.current.setUncontrolledValue('banana');
+      });
+      expect(result.current.value).toBe('apple');
+    });
+  });
+
+  describe('Uncontrolled', () => {
+    test('calling without a value sets value to `initialValue`', () => {
+      const {
+        result: { current },
+      } = renderUseControlledHook(undefined, () => {}, 'apple');
+
+      expect(current.isControlled).toBe(false);
+      expect(current.value).toBe('apple');
+    });
+
+    test('provided handler is called within `updateValue`', () => {
+      const handler = jest.fn();
+      const {
+        result: { current },
+      } = renderUseControlledHook(undefined, handler);
+
+      current.updateValue('apple');
+      expect(handler).toHaveBeenCalledWith('apple');
+    });
+
+    test('updateValue updates the value', () => {
+      const { result, rerender } = renderUseControlledHook<string>(undefined);
+      result.current.updateValue('banana');
+      rerender();
+      expect(result.current.value).toBe('banana');
+    });
+
+    test('rerendering from initial undefined does not set value and isControlled', async () => {
+      const { rerender, result } = renderUseControlledHook();
+      rerender('apple');
+      expect(result.current.isControlled).toBe(false);
+      expect(result.current.value).toBeUndefined();
+    });
+
+    test('setUncontrolledValue updates value', () => {
+      const handler = jest.fn();
+      const { result } = renderUseControlledHook<string>(
+        undefined,
+        handler,
+        '',
+      );
+
+      act(() => {
+        result.current.setUncontrolledValue('apple');
+      });
+      expect(result.current.value).toBe('apple');
+      expect(handler).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('Within test component', () => {
+    const TestComponent = ({
+      valueProp,
+      handlerProp,
+    }: {
+      valueProp?: string;
+      handlerProp?: (val?: string) => void;
+    }) => {
+      const initialVal = '';
+
+      const { value, updateValue } = useControlled(
+        valueProp,
+        handlerProp,
+        initialVal,
+      );
+
+      const handleChange: ChangeEventHandler<HTMLInputElement> = e => {
+        updateValue(e.target.value);
+      };
+
+      return (
+        <>
+          <input
+            data-testid="test-input"
+            value={value}
+            onChange={handleChange}
+          />
+          <button
+            data-testid="test-button"
+            onClick={() => updateValue('carrot')}
+          />
+        </>
+      );
+    };
+
+    describe('Controlled', () => {
+      test('initially renders with a value', () => {
+        const result = render(<TestComponent valueProp="apple" />);
+        const input = result.getByTestId('test-input');
+        expect(input).toHaveValue('apple');
+      });
+
+      test('responds to value changes', () => {
+        const result = render(<TestComponent valueProp="apple" />);
+        const input = result.getByTestId('test-input');
+        result.rerender(<TestComponent valueProp="banana" />);
+        expect(input).toHaveValue('banana');
+      });
+
+      test('user interaction triggers handler', () => {
+        const handler = jest.fn();
+        const result = render(
+          <TestComponent valueProp="apple" handlerProp={handler} />,
+        );
+        const input = result.getByTestId('test-input');
+        userEvent.type(input, 'b');
+        expect(handler).toHaveBeenCalledWith(expect.stringContaining('b'));
+      });
+
+      test('user interaction does not change the element value', () => {
+        const result = render(<TestComponent valueProp="apple" />);
+        const input = result.getByTestId('test-input');
+        userEvent.type(input, 'b');
+        expect(input).toHaveValue('apple');
+      });
+    });
+
+    describe('Uncontrolled', () => {
+      test('initially renders without a value', () => {
+        const result = render(<TestComponent />);
+        const input = result.getByTestId('test-input');
+        expect(input).toHaveValue('');
+        expect(errorSpy).not.toHaveBeenCalled();
+      });
+
+      test('user interaction triggers handler', () => {
+        const handler = jest.fn();
+        const result = render(<TestComponent handlerProp={handler} />);
+        const input = result.getByTestId('test-input');
+        userEvent.type(input, 'b');
+        expect(handler).toHaveBeenCalled();
+      });
+
+      test('user interaction changes the element value', () => {
+        const handler = jest.fn();
+        const result = render(<TestComponent handlerProp={handler} />);
+        const input = result.getByTestId('test-input');
+        userEvent.type(input, 'banana');
+        expect(input).toHaveValue('banana');
+      });
+
+      test('clicking the button updates the value', () => {
+        const result = render(<TestComponent />);
+        const input = result.getByTestId('test-input');
+        const button = result.getByTestId('test-button');
+        userEvent.click(button);
+        expect(input).toHaveValue('carrot');
+      });
+    });
+  });
+});

packages/hooks/src/useControlled/useControlled.ts

@@ -0,0 +1,72 @@
+import { useEffect, useMemo, useState } from 'react';
+import isUndefined from 'lodash/isUndefined';
+
+import { consoleOnce } from '@leafygreen-ui/lib';
+
+import { ControlledReturnObject } from './useControlled.types';
+
+/**
+ * A hook that enables a component to be both controlled or uncontrolled.
+ *
+ * Returns a {@link ControlledReturnObject}
+ */
+export const useControlled = <T extends any>(
+  controlledValue?: T,
+  onChange?: (val?: T) => void,
+  initialValue?: T,
+): ControlledReturnObject<T | undefined> => {
+  /**
+   * isControlled should only be computed once
+   */
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const isControlled = useMemo(() => !isUndefined(controlledValue), []);
+
+  /**
+   * Keep track of the uncontrolled value state internally
+   */
+  const [uncontrolledValue, setUncontrolledValue] = useState<T | undefined>(
+    initialValue,
+  );
+
+  /**
+   * The returned value.
+   * If the component is uncontrolled, it will return the internal value.
+   * If the component is controlled, it will return the controlled value.
+   */
+  const value = useMemo(
+    () => (isControlled ? controlledValue : uncontrolledValue),
+    [isControlled, uncontrolledValue, controlledValue],
+  );
+
+  /**
+   * Updates the value of the component.
+   * If the component is uncontrolled, it will update the internal value.
+   * If the component is controlled, it will not update the controlled value.
+   *
+   * onChange callback is called if provided.
+   */
+  const updateValue = (newVal: T | undefined) => {
+    if (!isControlled) {
+      setUncontrolledValue(newVal);
+    }
+    onChange?.(newVal);
+  };
+
+  /**
+   * Log a warning if neither controlled value or initialValue is provided
+   */
+  useEffect(() => {
+    if (isUndefined(controlledValue) && isUndefined(initialValue)) {
+      consoleOnce.error(
+        `Warning: \`useControlled\` hook is being used without a value or initialValue. If using an input, this will cause a React warning when an input changes. Please decide between using a controlled or uncontrolled element, and provide either a controlledValue or initialValue to \`useControlled\``,
+      );
+    }
+  }, [controlledValue, initialValue]);
+
+  return {
+    isControlled,
+    value,
+    updateValue,
+    setUncontrolledValue,
+  };
+};

packages/hooks/src/useControlled/useControlled.types.ts

@@ -0,0 +1,21 @@
+export interface ControlledReturnObject<T extends any> {
+  /** Whether the value is controlled */
+  isControlled: boolean;
+
+  /** The controlled or uncontrolled value */
+  value: T;
+
+  /**
+   * Either updates the uncontrolled value,
+   * or calls the provided `onChange` callback
+   */
+  updateValue: (newVal?: T) => void;
+
+  /**
+   * A setter for the internal value.
+   * Does not change the controlled value if the provided value has not changed.
+   * Prefer using `updateValue` to programmatically set the value.
+   * @internal
+   */
+  setUncontrolledValue: React.Dispatch<React.SetStateAction<T>>;
+}