From 753ba1647ef67fcefd63d79b11ce3ee52ee2a5d3 Mon Sep 17 00:00:00 2001
From: Adam Thompson <adam.thompson@mongodb.com>
Date: Thu, 24 Aug 2023 12:49:00 -0400
Subject: [PATCH 01/16] Extends `useControlledValue` to accept any type

---
 .changeset/soft-berries-obey.md                       |  5 +++++
 .../src/useControlledValue/useControlledValue.ts      | 11 +++++++----
 2 files changed, 12 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/soft-berries-obey.md

diff --git a/.changeset/soft-berries-obey.md b/.changeset/soft-berries-obey.md
new file mode 100644
index 0000000000..f169b748be
--- /dev/null
+++ b/.changeset/soft-berries-obey.md
@@ -0,0 +1,5 @@
+---
+'@leafygreen-ui/hooks': minor
+---
+
+Extends `useControlledValue` to accept any type
diff --git a/packages/hooks/src/useControlledValue/useControlledValue.ts b/packages/hooks/src/useControlledValue/useControlledValue.ts
index 008235ee54..c1eacd848d 100644
--- a/packages/hooks/src/useControlledValue/useControlledValue.ts
+++ b/packages/hooks/src/useControlledValue/useControlledValue.ts
@@ -1,7 +1,7 @@
 import { ChangeEventHandler, useEffect, useState } from 'react';
 import isUndefined from 'lodash/isUndefined';
 
-interface ControlledValueReturnObject<T extends string> {
+interface ControlledValueReturnObject<T extends any> {
   /** Whether the value is controlled */
   isControlled: boolean;
 
@@ -24,14 +24,17 @@ interface ControlledValueReturnObject<T extends string> {
  * Returns a {@link ControlledValueReturnObject} with the controlled or uncontrolled `value`,
  * `onChange` & `onClear` handlers, a `setInternalValue` setter, and a boolean `isControlled`
  */
-export const useControlledValue = <T extends string>(
+export const useControlledValue = <T extends any>(
   controlledValue?: T,
   changeHandler?: ChangeEventHandler<any>,
-): ControlledValueReturnObject<T> => {
+  defaultValue?: T,
+): ControlledValueReturnObject<T | undefined> => {
   const isControlled = !isUndefined(controlledValue);
 
   // Keep track of state internally, initializing it to the controlled value
-  const [value, setInternalValue] = useState<T>(controlledValue ?? ('' as T));
+  const [value, setInternalValue] = useState<T | undefined>(
+    controlledValue ?? defaultValue,
+  );
 
   // If the controlled value changes, update the internal state variable
   useEffect(() => {

From c565f2638902fabe592895c0dcb9a5c1bb61eed6 Mon Sep 17 00:00:00 2001
From: Adam Thompson <adam.thompson@mongodb.com>
Date: Thu, 24 Aug 2023 15:16:06 -0400
Subject: [PATCH 02/16] Adds more explicit tests

---
 .../useControlledValue.spec.ts                | 112 +++++++++++++-----
 1 file changed, 83 insertions(+), 29 deletions(-)

diff --git a/packages/hooks/src/useControlledValue/useControlledValue.spec.ts b/packages/hooks/src/useControlledValue/useControlledValue.spec.ts
index 8ebc6f789a..035cee5cb5 100644
--- a/packages/hooks/src/useControlledValue/useControlledValue.spec.ts
+++ b/packages/hooks/src/useControlledValue/useControlledValue.spec.ts
@@ -1,42 +1,96 @@
-import { ChangeEvent } from 'react';
+import { ChangeEvent, ChangeEventHandler } from 'react';
 import { act } from 'react-test-renderer';
 import { renderHook } from '@testing-library/react-hooks';
 
 import { useControlledValue } from './useControlledValue';
 
+const changeEventMock = {
+  target: { value: 'banana' },
+} as ChangeEvent<any>;
+
 describe('packages/lib/useControlledValue', () => {
-  test('with controlled component', async () => {
-    const value = 'apple';
-    const handler = jest.fn();
-    const {
-      result: { current },
-    } = renderHook(() => useControlledValue(value as string, handler));
-    expect(current.isControlled).toBe(true);
-    expect(current.value).toBe(value);
-
-    act(() => {
-      current.handleChange({ target: { value: 'banana' } } as ChangeEvent<any>);
-      current.setUncontrolledValue('banana');
+  describe('with controlled component', () => {
+    test('calling with a value sets value and isControlled', () => {
+      const handler = jest.fn();
+      const { result } = renderHook(v => useControlledValue(v, handler), {
+        initialProps: 'apple',
+      });
+      expect(result.current.isControlled).toBe(true);
+      expect(result.current.value).toBe('apple');
+    });
+
+    test('calling with a new value changes the value', () => {
+      const handler = jest.fn();
+      const { result, rerender } = renderHook(
+        v => useControlledValue(v, handler),
+        {
+          initialProps: 'apple',
+        },
+      );
+
+      expect(result.current.value).toBe('apple');
+
+      act(() => {
+        rerender('banana');
+      });
+
+      expect(result.current.value).toBe('banana');
+    });
+
+    test('provided handler should be called', () => {
+      const handler = jest.fn();
+      const { result } = renderHook(v => useControlledValue(v, handler), {
+        initialProps: 'apple',
+      });
+
+      // simulate responding to an event
+      act(() => {
+        result.current.handleChange(changeEventMock);
+      });
+      expect(handler).toHaveBeenCalledWith(
+        expect.objectContaining(changeEventMock),
+      );
+      // value doesn't change unless we explicitly change it
+      expect(result.current.value).toBe('apple');
     });
-    expect(handler).toHaveBeenCalledWith(
-      expect.objectContaining({ target: { value: 'banana' } }),
-    );
-    expect(current.value).toBe('apple');
   });
 
-  test('with uncontrolled component', async () => {
-    const value = undefined;
-    const handler = jest.fn();
-    const {
-      result: { current },
-    } = renderHook(() => useControlledValue(value, handler));
-    expect(current.isControlled).toBe(false);
-    expect(current.value).toBe('');
-
-    act(() => {
-      current.handleChange({ target: { value: 'apple' } } as ChangeEvent<any>);
+  describe('with uncontrolled component', () => {
+    test('calling without a value sets value and isControlled', () => {
+      const handler = jest.fn();
+      const { result } = renderHook(v => useControlledValue(v, handler), {
+        initialProps: undefined,
+      });
+      expect(result.current.isControlled).toBe(false);
+      expect(result.current.value).toBe(undefined);
+    });
+
+    test('calling setter updates value', () => {
+      const handler = jest.fn();
+      const { result } = renderHook(
+        v => useControlledValue<string>(v, handler),
+        {
+          initialProps: undefined,
+        },
+      );
+
+      act(() => {
+        result.current.setUncontrolledValue('apple');
+      });
+      expect(result.current.value).toBe('apple');
+    });
+
+    test('provided handler should be called', () => {
+      const handler = jest.fn();
+      const { result } = renderHook(v => useControlledValue(v, handler), {
+        initialProps: undefined,
+      });
+
+      act(() => {
+        result.current.handleChange(changeEventMock);
+      });
       expect(handler).toHaveBeenCalledWith(
-        expect.objectContaining({ target: { value: 'apple' } }),
+        expect.objectContaining(changeEventMock),
       );
     });
   });

From b61283585a257987408ccfa6b54b6ce23dd27d45 Mon Sep 17 00:00:00 2001
From: Adam Thompson <adam.thompson@mongodb.com>
Date: Thu, 24 Aug 2023 15:28:30 -0400
Subject: [PATCH 03/16] adds test component tests

---
 ...ue.spec.ts => useControlledValue.spec.tsx} | 80 +++++++++++++++++++
 1 file changed, 80 insertions(+)
 rename packages/hooks/src/useControlledValue/{useControlledValue.spec.ts => useControlledValue.spec.tsx} (51%)

diff --git a/packages/hooks/src/useControlledValue/useControlledValue.spec.ts b/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
similarity index 51%
rename from packages/hooks/src/useControlledValue/useControlledValue.spec.ts
rename to packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
index 035cee5cb5..bfff17fbb2 100644
--- a/packages/hooks/src/useControlledValue/useControlledValue.spec.ts
+++ b/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
@@ -1,6 +1,9 @@
+import React from 'react';
 import { ChangeEvent, ChangeEventHandler } from 'react';
 import { act } from 'react-test-renderer';
+import { render } from '@testing-library/react';
 import { renderHook } from '@testing-library/react-hooks';
+import userEvent from '@testing-library/user-event';
 
 import { useControlledValue } from './useControlledValue';
 
@@ -94,4 +97,81 @@ describe('packages/lib/useControlledValue', () => {
       );
     });
   });
+
+  describe('with test component', () => {
+    const TestComponent = ({
+      valueProp,
+      handlerProp,
+    }: {
+      valueProp?: string;
+      handlerProp?: ChangeEventHandler;
+    }) => {
+      // eslint-disable-next-line react-hooks/rules-of-hooks
+      const { value, handleChange } = useControlledValue(
+        valueProp,
+        handlerProp,
+      );
+
+      return <input data-testid="test" value={value} onChange={handleChange} />;
+    };
+
+    describe('Controlled test component', () => {
+      test('initially renders with a value', () => {
+        const result = render(<TestComponent valueProp="apple" />);
+        const input = result.getByTestId('test');
+        expect(input).toHaveValue('apple');
+      });
+
+      test('responds to value changes', () => {
+        const result = render(<TestComponent valueProp="apple" />);
+        const input = result.getByTestId('test');
+        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');
+        userEvent.type(input, 'b');
+        expect(handler).toHaveBeenCalled();
+      });
+
+      test('user interaction does not change the element value', () => {
+        const handler = jest.fn();
+        const result = render(
+          <TestComponent valueProp="apple" handlerProp={handler} />,
+        );
+        const input = result.getByTestId('test');
+        userEvent.type(input, 'b');
+        expect(input).toHaveValue('apple');
+      });
+    });
+
+    describe('Uncontrolled test component', () => {
+      test('initially renders without a value', () => {
+        const result = render(<TestComponent />);
+        const input = result.getByTestId('test');
+        expect(input).toHaveValue('');
+      });
+
+      test('user interaction triggers handler', () => {
+        const handler = jest.fn();
+        const result = render(<TestComponent handlerProp={handler} />);
+        const input = result.getByTestId('test');
+        userEvent.type(input, 'b');
+        expect(handler).toHaveBeenCalled();
+      });
+
+      test('user interaction does not change the element value', () => {
+        const handler = jest.fn();
+        const result = render(<TestComponent handlerProp={handler} />);
+        const input = result.getByTestId('test');
+        userEvent.type(input, 'banana');
+        expect(input).toHaveValue('banana');
+      });
+    });
+  });
 });

From f4e1c613075c85b707533d8831840073fbb7cf87 Mon Sep 17 00:00:00 2001
From: Adam Thompson <adam.thompson@mongodb.com>
Date: Thu, 24 Aug 2023 15:32:55 -0400
Subject: [PATCH 04/16] adds value tests

---
 .../useControlledValue.spec.tsx               | 40 +++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx b/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
index bfff17fbb2..8b2e85a018 100644
--- a/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
+++ b/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
@@ -56,6 +56,46 @@ describe('packages/lib/useControlledValue', () => {
       // value doesn't change unless we explicitly change it
       expect(result.current.value).toBe('apple');
     });
+
+    describe('value types', () => {
+      test('accepts number values', () => {
+        const { result } = renderHook(v => useControlledValue(v), {
+          initialProps: 5,
+        });
+        expect(result.current.value).toBe(5);
+      });
+
+      test('accepts boolean values', () => {
+        const { result } = renderHook(v => useControlledValue(v), {
+          initialProps: false,
+        });
+        expect(result.current.value).toBe(false);
+      });
+
+      test('accepts array values', () => {
+        const arr = ['foo', 'bar'];
+        const { result } = renderHook(v => useControlledValue(v), {
+          initialProps: arr,
+        });
+        expect(result.current.value).toBe(arr);
+      });
+
+      test('accepts object values', () => {
+        const obj = { foo: 'foo', bar: 'bar' };
+        const { result } = renderHook(v => useControlledValue(v), {
+          initialProps: obj,
+        });
+        expect(result.current.value).toBe(obj);
+      });
+
+      test('accepts date values', () => {
+        const date = new Date('2023-08-23');
+        const { result } = renderHook(v => useControlledValue(v), {
+          initialProps: date,
+        });
+        expect(result.current.value).toBe(date);
+      });
+    });
   });
 
   describe('with uncontrolled component', () => {

From bbb1832e65f3661f6f2dbc98706cf26844e2e53a Mon Sep 17 00:00:00 2001
From: Adam Thompson <adam.thompson@mongodb.com>
Date: Thu, 24 Aug 2023 15:51:20 -0400
Subject: [PATCH 05/16] isControlled never changes from initial render

---
 .changeset/soft-berries-obey.md               |  3 +-
 .../useControlledValue.spec.tsx               | 63 +++++++++++++------
 .../useControlledValue/useControlledValue.ts  |  6 +-
 3 files changed, 50 insertions(+), 22 deletions(-)

diff --git a/.changeset/soft-berries-obey.md b/.changeset/soft-berries-obey.md
index f169b748be..8d0236cdfe 100644
--- a/.changeset/soft-berries-obey.md
+++ b/.changeset/soft-berries-obey.md
@@ -2,4 +2,5 @@
 '@leafygreen-ui/hooks': minor
 ---
 
-Extends `useControlledValue` to accept any type
+- Extends `useControlledValue` to accept any type.
+- The value of `isControlled` is now immutable after the first render
diff --git a/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx b/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
index 8b2e85a018..faf8fc1b6f 100644
--- a/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
+++ b/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
@@ -14,8 +14,7 @@ const changeEventMock = {
 describe('packages/lib/useControlledValue', () => {
   describe('with controlled component', () => {
     test('calling with a value sets value and isControlled', () => {
-      const handler = jest.fn();
-      const { result } = renderHook(v => useControlledValue(v, handler), {
+      const { result } = renderHook(v => useControlledValue(v), {
         initialProps: 'apple',
       });
       expect(result.current.isControlled).toBe(true);
@@ -23,13 +22,9 @@ describe('packages/lib/useControlledValue', () => {
     });
 
     test('calling with a new value changes the value', () => {
-      const handler = jest.fn();
-      const { result, rerender } = renderHook(
-        v => useControlledValue(v, handler),
-        {
-          initialProps: 'apple',
-        },
-      );
+      const { result, rerender } = renderHook(v => useControlledValue(v), {
+        initialProps: 'apple',
+      });
 
       expect(result.current.value).toBe('apple');
 
@@ -40,7 +35,7 @@ describe('packages/lib/useControlledValue', () => {
       expect(result.current.value).toBe('banana');
     });
 
-    test('provided handler should be called', () => {
+    test('provided handler is called within returned hook handler', () => {
       const handler = jest.fn();
       const { result } = renderHook(v => useControlledValue(v, handler), {
         initialProps: 'apple',
@@ -57,6 +52,15 @@ describe('packages/lib/useControlledValue', () => {
       expect(result.current.value).toBe('apple');
     });
 
+    test('setting value to undefined should keep the component controlled', () => {
+      const { result, rerender } = renderHook(v => useControlledValue(v), {
+        initialProps: 'apple',
+      });
+      expect(result.current.isControlled).toBe(true);
+      act(() => rerender(undefined));
+      expect(result.current.isControlled).toBe(true);
+    });
+
     describe('value types', () => {
       test('accepts number values', () => {
         const { result } = renderHook(v => useControlledValue(v), {
@@ -100,8 +104,7 @@ describe('packages/lib/useControlledValue', () => {
 
   describe('with uncontrolled component', () => {
     test('calling without a value sets value and isControlled', () => {
-      const handler = jest.fn();
-      const { result } = renderHook(v => useControlledValue(v, handler), {
+      const { result } = renderHook(v => useControlledValue(v), {
         initialProps: undefined,
       });
       expect(result.current.isControlled).toBe(false);
@@ -109,13 +112,9 @@ describe('packages/lib/useControlledValue', () => {
     });
 
     test('calling setter updates value', () => {
-      const handler = jest.fn();
-      const { result } = renderHook(
-        v => useControlledValue<string>(v, handler),
-        {
-          initialProps: undefined,
-        },
-      );
+      const { result } = renderHook(v => useControlledValue<string>(v), {
+        initialProps: undefined,
+      });
 
       act(() => {
         result.current.setUncontrolledValue('apple');
@@ -136,6 +135,32 @@ describe('packages/lib/useControlledValue', () => {
         expect.objectContaining(changeEventMock),
       );
     });
+
+    test('calling the returned handler sets the value', () => {
+      const handler = jest.fn();
+      const { result } = renderHook(v => useControlledValue(v, handler), {
+        initialProps: undefined,
+      });
+
+      act(() => {
+        result.current.handleChange(changeEventMock);
+      });
+      expect(result.current.value).toBe('banana');
+    });
+
+    test('changing value prop from initial undefined is ignored', () => {
+      const { result, rerender } = renderHook(
+        v => useControlledValue<string>(v),
+        {
+          initialProps: undefined,
+        },
+      );
+      expect(result.current.isControlled).toBe(false);
+      // @ts-ignore - picking up renderHook.options types, not actual hook types
+      act(() => rerender('apple'));
+      expect(result.current.isControlled).toBe(false);
+      expect(result.current.value).toBe(undefined);
+    });
   });
 
   describe('with test component', () => {
diff --git a/packages/hooks/src/useControlledValue/useControlledValue.ts b/packages/hooks/src/useControlledValue/useControlledValue.ts
index 536879319f..e843f2f551 100644
--- a/packages/hooks/src/useControlledValue/useControlledValue.ts
+++ b/packages/hooks/src/useControlledValue/useControlledValue.ts
@@ -1,4 +1,4 @@
-import { ChangeEventHandler, useState } from 'react';
+import { ChangeEventHandler, useEffect, useMemo, useState } from 'react';
 import isUndefined from 'lodash/isUndefined';
 
 interface ControlledValueReturnObject<T extends any> {
@@ -28,7 +28,9 @@ export const useControlledValue = <T extends any>(
   controlledValue?: T,
   changeHandler?: ChangeEventHandler<any>,
 ): ControlledValueReturnObject<T | undefined> => {
-  const isControlled = !isUndefined(controlledValue);
+  // 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>();

From af6cc4867690aeac0cf8f57618e4fb0819a4441c Mon Sep 17 00:00:00 2001
From: Adam Thompson <adam.thompson@mongodb.com>
Date: Thu, 24 Aug 2023 16:31:17 -0400
Subject: [PATCH 06/16] adds synthetic events

---
 .changeset/soft-berries-obey.md               |   1 +
 packages/hooks/package.json                   |   1 +
 .../useControlledValue.spec.tsx               | 108 +++++++++++++++---
 .../useControlledValue/useControlledValue.ts  |  30 ++++-
 packages/hooks/tsconfig.json                  |   6 +-
 5 files changed, 130 insertions(+), 16 deletions(-)

diff --git a/.changeset/soft-berries-obey.md b/.changeset/soft-berries-obey.md
index 8d0236cdfe..b428fe5f29 100644
--- a/.changeset/soft-berries-obey.md
+++ b/.changeset/soft-berries-obey.md
@@ -3,4 +3,5 @@
 ---
 
 - Extends `useControlledValue` to accept any type.
+- Adds `updateValue` function in return value. This method triggers a synthetic event to update the value of a controlled or uncontrolled component.
 - The value of `isControlled` is now immutable after the first render
diff --git a/packages/hooks/package.json b/packages/hooks/package.json
index 27ca1b683d..e3f73c5d70 100644
--- a/packages/hooks/package.json
+++ b/packages/hooks/package.json
@@ -22,6 +22,7 @@
     "access": "public"
   },
   "dependencies": {
+    "@leafygreen-ui/lib": "^11.0.0",
     "lodash": "^4.17.21"
   },
   "gitHead": "dd71a2d404218ccec2e657df9c0263dc1c15b9e0",
diff --git a/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx b/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
index faf8fc1b6f..837c94aaa3 100644
--- a/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
+++ b/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
@@ -1,4 +1,4 @@
-import React from 'react';
+import React, { useRef } from 'react';
 import { ChangeEvent, ChangeEventHandler } from 'react';
 import { act } from 'react-test-renderer';
 import { render } from '@testing-library/react';
@@ -11,6 +11,10 @@ const changeEventMock = {
   target: { value: 'banana' },
 } as ChangeEvent<any>;
 
+const mutableRefMock = {
+  current: document.createElement('div'),
+};
+
 describe('packages/lib/useControlledValue', () => {
   describe('with controlled component', () => {
     test('calling with a value sets value and isControlled', () => {
@@ -61,6 +65,30 @@ describe('packages/lib/useControlledValue', () => {
       expect(result.current.isControlled).toBe(true);
     });
 
+    test('setUncontrolledValue does nothing for controlled components', () => {
+      const { result } = renderHook(v => useControlledValue(v), {
+        initialProps: 'apple',
+      });
+      act(() => {
+        result.current.setUncontrolledValue('banana');
+      });
+      expect(result.current.value).toBe('apple');
+    });
+
+    test('updateValue triggers the provided handler', async () => {
+      const handler = jest.fn();
+
+      const { result } = renderHook(v => useControlledValue(v, handler), {
+        initialProps: 'apple',
+      });
+
+      await act(() => {
+        result.current.updateValue('banana', mutableRefMock);
+      });
+
+      expect(handler).toHaveBeenCalled();
+    });
+
     describe('value types', () => {
       test('accepts number values', () => {
         const { result } = renderHook(v => useControlledValue(v), {
@@ -111,15 +139,20 @@ describe('packages/lib/useControlledValue', () => {
       expect(result.current.value).toBe(undefined);
     });
 
-    test('calling setter updates value', () => {
-      const { result } = renderHook(v => useControlledValue<string>(v), {
-        initialProps: undefined,
-      });
+    test('setUncontrolledValue updates value', () => {
+      const handler = jest.fn();
+      const { result } = renderHook(
+        v => useControlledValue<string>(v, handler),
+        {
+          initialProps: undefined,
+        },
+      );
 
       act(() => {
         result.current.setUncontrolledValue('apple');
       });
       expect(result.current.value).toBe('apple');
+      expect(handler).not.toHaveBeenCalled();
     });
 
     test('provided handler should be called', () => {
@@ -136,6 +169,23 @@ describe('packages/lib/useControlledValue', () => {
       );
     });
 
+    test('updateValue updates value & calls handler', () => {
+      const handler = jest.fn();
+      const { result } = renderHook(
+        v => useControlledValue<string>(v, handler),
+        {
+          initialProps: undefined,
+        },
+      );
+
+      act(() => {
+        result.current.updateValue('banana', mutableRefMock);
+      });
+
+      expect(handler).toHaveBeenCalled();
+      expect(result.current.value).toBe('banana');
+    });
+
     test('calling the returned handler sets the value', () => {
       const handler = jest.fn();
       const { result } = renderHook(v => useControlledValue(v, handler), {
@@ -171,25 +221,39 @@ describe('packages/lib/useControlledValue', () => {
       valueProp?: string;
       handlerProp?: ChangeEventHandler;
     }) => {
+      const inputRef = useRef<HTMLInputElement>(null);
       // eslint-disable-next-line react-hooks/rules-of-hooks
-      const { value, handleChange } = useControlledValue(
+      const { value, handleChange, updateValue } = useControlledValue(
         valueProp,
         handlerProp,
       );
 
-      return <input data-testid="test" value={value} onChange={handleChange} />;
+      return (
+        <>
+          <input
+            ref={inputRef}
+            data-testid="test-input"
+            value={value}
+            onChange={handleChange}
+          />
+          <button
+            data-testid="test-button"
+            onClick={() => updateValue('carrot', inputRef)}
+          />
+        </>
+      );
     };
 
     describe('Controlled test component', () => {
       test('initially renders with a value', () => {
         const result = render(<TestComponent valueProp="apple" />);
-        const input = result.getByTestId('test');
+        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');
+        const input = result.getByTestId('test-input');
         result.rerender(<TestComponent valueProp="banana" />);
         expect(input).toHaveValue('banana');
       });
@@ -199,7 +263,7 @@ describe('packages/lib/useControlledValue', () => {
         const result = render(
           <TestComponent valueProp="apple" handlerProp={handler} />,
         );
-        const input = result.getByTestId('test');
+        const input = result.getByTestId('test-input');
         userEvent.type(input, 'b');
         expect(handler).toHaveBeenCalled();
       });
@@ -209,23 +273,31 @@ describe('packages/lib/useControlledValue', () => {
         const result = render(
           <TestComponent valueProp="apple" handlerProp={handler} />,
         );
-        const input = result.getByTestId('test');
+        const input = result.getByTestId('test-input');
         userEvent.type(input, 'b');
         expect(input).toHaveValue('apple');
       });
+
+      test('clicking the button updates the value', () => {
+        const result = render(<TestComponent valueProp="apple" />);
+        const input = result.getByTestId('test-input');
+        const button = result.getByTestId('test-button');
+        userEvent.click(button);
+        expect(input).toHaveValue('carrot');
+      });
     });
 
     describe('Uncontrolled test component', () => {
       test('initially renders without a value', () => {
         const result = render(<TestComponent />);
-        const input = result.getByTestId('test');
+        const input = result.getByTestId('test-input');
         expect(input).toHaveValue('');
       });
 
       test('user interaction triggers handler', () => {
         const handler = jest.fn();
         const result = render(<TestComponent handlerProp={handler} />);
-        const input = result.getByTestId('test');
+        const input = result.getByTestId('test-input');
         userEvent.type(input, 'b');
         expect(handler).toHaveBeenCalled();
       });
@@ -233,10 +305,18 @@ describe('packages/lib/useControlledValue', () => {
       test('user interaction does not change the element value', () => {
         const handler = jest.fn();
         const result = render(<TestComponent handlerProp={handler} />);
-        const input = result.getByTestId('test');
+        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');
+      });
     });
   });
 });
diff --git a/packages/hooks/src/useControlledValue/useControlledValue.ts b/packages/hooks/src/useControlledValue/useControlledValue.ts
index e843f2f551..3720c08cc0 100644
--- a/packages/hooks/src/useControlledValue/useControlledValue.ts
+++ b/packages/hooks/src/useControlledValue/useControlledValue.ts
@@ -1,6 +1,8 @@
-import { ChangeEventHandler, useEffect, useMemo, useState } from 'react';
+import { ChangeEventHandler, MutableRefObject, useMemo, useState } from 'react';
 import isUndefined from 'lodash/isUndefined';
 
+import { createSyntheticEvent } from '@leafygreen-ui/lib';
+
 interface ControlledValueReturnObject<T extends any> {
   /** Whether the value is controlled */
   isControlled: boolean;
@@ -14,8 +16,17 @@ interface ControlledValueReturnObject<T extends any> {
   /**
    * 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>>;
+
+  /**
+   * Synthetically triggers a change event within the `handleChange` callback.
+   * Signals that the value should change for controlled components,
+   * and updates the internal value for uncontrolled components
+   */
+  updateValue: (newVal: T, ref: MutableRefObject<any>) => void;
 }
 
 /**
@@ -44,10 +55,27 @@ export const useControlledValue = <T extends any>(
     }
   };
 
+  // A wrapper around `handleChange` that fires a simulated event
+  const updateValue = (newVal: T | undefined, ref: MutableRefObject<any>) => {
+    if (ref.current) {
+      ref.current.value = newVal;
+      const synthEvt = createSyntheticEvent(
+        new Event('change', {
+          cancelable: true,
+          bubbles: true,
+        }),
+        ref.current,
+      );
+
+      handleChange(synthEvt);
+    }
+  };
+
   return {
     isControlled,
     value: isControlled ? controlledValue : uncontrolledValue,
     handleChange,
     setUncontrolledValue,
+    updateValue,
   };
 };
diff --git a/packages/hooks/tsconfig.json b/packages/hooks/tsconfig.json
index 9f2d965a63..a2786ad64a 100644
--- a/packages/hooks/tsconfig.json
+++ b/packages/hooks/tsconfig.json
@@ -14,5 +14,9 @@
     "src/**/*"
   ],
   "exclude": ["**/*.spec.*", "**/*.story.*"],
-  "references": []
+  "references": [
+    {
+      "path": "../lib"
+    }
+  ]
 }

From f6751e822baa7198a47ff3e526399aab9b0097d9 Mon Sep 17 00:00:00 2001
From: Adam Thompson <adam.thompson@mongodb.com>
Date: Thu, 24 Aug 2023 17:10:12 -0400
Subject: [PATCH 07/16] adds initialValue & warning

---
 .../useControlledValue.spec.tsx               | 43 +++++++++++++++----
 .../useControlledValue/useControlledValue.ts  | 28 +++++++++---
 2 files changed, 57 insertions(+), 14 deletions(-)

diff --git a/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx b/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
index 837c94aaa3..36805f620f 100644
--- a/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
+++ b/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
@@ -15,7 +15,7 @@ const mutableRefMock = {
   current: document.createElement('div'),
 };
 
-describe('packages/lib/useControlledValue', () => {
+describe('packages/hooks/useControlledValue', () => {
   describe('with controlled component', () => {
     test('calling with a value sets value and isControlled', () => {
       const { result } = renderHook(v => useControlledValue(v), {
@@ -89,6 +89,16 @@ describe('packages/lib/useControlledValue', () => {
       expect(handler).toHaveBeenCalled();
     });
 
+    test('initial value is ignored when controlled', () => {
+      const { result } = renderHook(
+        v => useControlledValue(v, null, 'foobar'),
+        {
+          initialProps: 'apple',
+        },
+      );
+      expect(result.current.value).toBe('apple');
+    });
+
     describe('value types', () => {
       test('accepts number values', () => {
         const { result } = renderHook(v => useControlledValue(v), {
@@ -127,22 +137,36 @@ describe('packages/lib/useControlledValue', () => {
         });
         expect(result.current.value).toBe(date);
       });
+
+      test('accepts multiple types', () => {
+        const { result, rerender } = renderHook(
+          v => useControlledValue<string | number>(v),
+          {
+            initialProps: 5 as string | number,
+          },
+        );
+        expect(result.current.value).toBe(5);
+        act(() => {
+          rerender('foo');
+        });
+        expect(result.current.value).toBe('foo');
+      });
     });
   });
 
   describe('with uncontrolled component', () => {
-    test('calling without a value sets value and isControlled', () => {
-      const { result } = renderHook(v => useControlledValue(v), {
+    test('calling without a value sets value to initialValue and isControlled: false', () => {
+      const { result } = renderHook(v => useControlledValue(v, null, ''), {
         initialProps: undefined,
       });
       expect(result.current.isControlled).toBe(false);
-      expect(result.current.value).toBe(undefined);
+      expect(result.current.value).toBe('');
     });
 
     test('setUncontrolledValue updates value', () => {
       const handler = jest.fn();
       const { result } = renderHook(
-        v => useControlledValue<string>(v, handler),
+        v => useControlledValue<string>(v, handler, ''),
         {
           initialProps: undefined,
         },
@@ -157,7 +181,7 @@ describe('packages/lib/useControlledValue', () => {
 
     test('provided handler should be called', () => {
       const handler = jest.fn();
-      const { result } = renderHook(v => useControlledValue(v, handler), {
+      const { result } = renderHook(v => useControlledValue(v, handler, ''), {
         initialProps: undefined,
       });
 
@@ -172,7 +196,7 @@ describe('packages/lib/useControlledValue', () => {
     test('updateValue updates value & calls handler', () => {
       const handler = jest.fn();
       const { result } = renderHook(
-        v => useControlledValue<string>(v, handler),
+        v => useControlledValue<string>(v, handler, ''),
         {
           initialProps: undefined,
         },
@@ -188,7 +212,7 @@ describe('packages/lib/useControlledValue', () => {
 
     test('calling the returned handler sets the value', () => {
       const handler = jest.fn();
-      const { result } = renderHook(v => useControlledValue(v, handler), {
+      const { result } = renderHook(v => useControlledValue(v, handler, ''), {
         initialProps: undefined,
       });
 
@@ -200,7 +224,7 @@ describe('packages/lib/useControlledValue', () => {
 
     test('changing value prop from initial undefined is ignored', () => {
       const { result, rerender } = renderHook(
-        v => useControlledValue<string>(v),
+        v => useControlledValue<string>(v, null, ''),
         {
           initialProps: undefined,
         },
@@ -226,6 +250,7 @@ describe('packages/lib/useControlledValue', () => {
       const { value, handleChange, updateValue } = useControlledValue(
         valueProp,
         handlerProp,
+        '',
       );
 
       return (
diff --git a/packages/hooks/src/useControlledValue/useControlledValue.ts b/packages/hooks/src/useControlledValue/useControlledValue.ts
index 3720c08cc0..e2d5c45842 100644
--- a/packages/hooks/src/useControlledValue/useControlledValue.ts
+++ b/packages/hooks/src/useControlledValue/useControlledValue.ts
@@ -1,7 +1,13 @@
-import { ChangeEventHandler, MutableRefObject, useMemo, useState } from 'react';
+import {
+  ChangeEventHandler,
+  MutableRefObject,
+  useEffect,
+  useMemo,
+  useState,
+} from 'react';
 import isUndefined from 'lodash/isUndefined';
 
-import { createSyntheticEvent } from '@leafygreen-ui/lib';
+import { consoleOnce, createSyntheticEvent } from '@leafygreen-ui/lib';
 
 interface ControlledValueReturnObject<T extends any> {
   /** Whether the value is controlled */
@@ -35,16 +41,19 @@ interface ControlledValueReturnObject<T extends any> {
  * Returns a {@link ControlledValueReturnObject} with the controlled or uncontrolled `value`,
  * `onChange` & `onClear` handlers, a `setInternalValue` setter, and a boolean `isControlled`
  */
-export const useControlledValue = <T extends any>(
+export const useControlledValue = <T>(
   controlledValue?: T,
-  changeHandler?: ChangeEventHandler<any>,
+  changeHandler?: ChangeEventHandler<any> | null,
+  initialValue?: T,
 ): ControlledValueReturnObject<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>();
+  const [uncontrolledValue, setUncontrolledValue] = useState<T | undefined>(
+    initialValue,
+  );
 
   // Create a change event handler that either updates the internal state
   // or fires an external change handler
@@ -71,6 +80,15 @@ export const useControlledValue = <T extends any>(
     }
   };
 
+  useEffect(() => {
+    // Log a warning if neither controlled value or initialValue is provided
+    if (isUndefined(controlledValue) && isUndefined(initialValue)) {
+      consoleOnce.error(
+        `Warning: \`useControlledValue\` hook is being used without a value or initialValue. This will cause a React warning when the input changes. Please decide between using a controlled or uncontrolled input element, and provide either a controlledValue or initialValue to \`useControlledValue\``,
+      );
+    }
+  }, [controlledValue, initialValue]);
+
   return {
     isControlled,
     value: isControlled ? controlledValue : uncontrolledValue,

From 0fd6d6bda2225a07888a00125ce6d31733a49829 Mon Sep 17 00:00:00 2001
From: Adam Thompson <adam.thompson@mongodb.com>
Date: Fri, 25 Aug 2023 10:20:25 -0400
Subject: [PATCH 08/16] Update useControlledValue.spec.tsx

---
 .../hooks/src/useControlledValue/useControlledValue.spec.tsx   | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx b/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
index 36805f620f..17a3fec8ec 100644
--- a/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
+++ b/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
@@ -230,10 +230,11 @@ describe('packages/hooks/useControlledValue', () => {
         },
       );
       expect(result.current.isControlled).toBe(false);
+      expect(result.current.value).toBe('');
       // @ts-ignore - picking up renderHook.options types, not actual hook types
       act(() => rerender('apple'));
       expect(result.current.isControlled).toBe(false);
-      expect(result.current.value).toBe(undefined);
+      expect(result.current.value).toBe('');
     });
   });
 

From 405229a473173ec3b49b2d6fb348dd65ea9f46ed Mon Sep 17 00:00:00 2001
From: Adam Thompson <adam.thompson@mongodb.com>
Date: Fri, 25 Aug 2023 10:28:40 -0400
Subject: [PATCH 09/16] resolves circular dependency in lib

---
 packages/lib/src/consoleOnce.ts       |  7 +++++++
 packages/lib/src/index.ts             | 26 +-------------------------
 packages/lib/src/validateChildren.tsx | 20 +++++++++++++++++++-
 3 files changed, 27 insertions(+), 26 deletions(-)
 create mode 100644 packages/lib/src/consoleOnce.ts

diff --git a/packages/lib/src/consoleOnce.ts b/packages/lib/src/consoleOnce.ts
new file mode 100644
index 0000000000..0157a30216
--- /dev/null
+++ b/packages/lib/src/consoleOnce.ts
@@ -0,0 +1,7 @@
+import once from 'lodash/once';
+
+export const consoleOnce = {
+  error: once(console.error),
+  warn: once(console.warn),
+  log: once(console.log),
+};
diff --git a/packages/lib/src/index.ts b/packages/lib/src/index.ts
index 5efc1a09b8..143983c11e 100644
--- a/packages/lib/src/index.ts
+++ b/packages/lib/src/index.ts
@@ -1,5 +1,3 @@
-import isObject from 'lodash/isObject';
-import once from 'lodash/once';
 import * as typeIs from './typeIs';
 import createUniqueClassName from './createUniqueClassName';
 import getNodeTextContent from './getNodeTextContent';
@@ -8,6 +6,7 @@ import getTheme from './getTheme';
 import { allEqual } from './allEqual';
 export { validateChildren } from './validateChildren';
 export { createSyntheticEvent } from './createSyntheticEvent';
+export { consoleOnce } from './consoleOnce';
 
 export {
   type ExtendedComponentProps,
@@ -87,23 +86,6 @@ export type OneOf<T1, T2> =
   | (T1 & Partial<Record<Exclude<keyof T2, keyof T1>, never>>)
   | (T2 & Partial<Record<Exclude<keyof T1, keyof T2>, never>>);
 
-/** Helper type to check if element is a specific React Component  */
-export function isComponentType<
-  T extends React.ReactElement = React.ReactElement,
->(element: React.ReactNode, displayName: string): element is T {
-  return (
-    element != null &&
-    typeof element === 'object' &&
-    'type' in element &&
-    ((element.type as any).displayName === displayName ||
-      // TODO: temp solution; Components using InferredPolymorphic have a displayName inside render.
-      // https://jira.mongodb.org/browse/LG-3232
-      (isObject(element.type as any) &&
-        'render' in (element.type as any) &&
-        (element.type as any).render?.displayName === displayName))
-  );
-}
-
 /**
  * Utility for making it easier to couple a React Component to a css selector.
  * Useful when writing css selectors that rely on interactivity, i.e. :hover.
@@ -220,9 +202,3 @@ export type RecursivePartial<T> = {
 export function enforceExhaustive(value: never): never {
   throw Error(`Received unhandled value: ${value}`);
 }
-
-export const consoleOnce = {
-  error: once(console.error),
-  warn: once(console.warn),
-  log: once(console.log),
-};
diff --git a/packages/lib/src/validateChildren.tsx b/packages/lib/src/validateChildren.tsx
index 2ec4a592ff..aac74b0cc8 100644
--- a/packages/lib/src/validateChildren.tsx
+++ b/packages/lib/src/validateChildren.tsx
@@ -1,6 +1,24 @@
+import isObject from 'lodash/isObject';
 import isUndefined from 'lodash/isUndefined';
 import React, { ReactElement } from 'react';
-import { consoleOnce, isComponentType } from '.';
+import { consoleOnce } from '.';
+
+/** Helper type to check if element is a specific React Component  */
+export function isComponentType<
+  T extends React.ReactElement = React.ReactElement,
+>(element: React.ReactNode, displayName: string): element is T {
+  return (
+    element != null &&
+    typeof element === 'object' &&
+    'type' in element &&
+    ((element.type as any).displayName === displayName ||
+      // TODO: temp solution; Components using InferredPolymorphic have a displayName inside render.
+      // https://jira.mongodb.org/browse/LG-3232
+      (isObject(element.type as any) &&
+        'render' in (element.type as any) &&
+        (element.type as any).render?.displayName === displayName))
+  );
+}
 
 /**
  * Filters children down to a restricted set of component types.

From 152db57f57532314a864a6d02462c6f9eb288334 Mon Sep 17 00:00:00 2001
From: Adam Thompson <adam.thompson@mongodb.com>
Date: Fri, 25 Aug 2023 10:56:05 -0400
Subject: [PATCH 10/16] expect no console

---
 .changeset/soft-berries-obey.md                   |  1 +
 .../useControlledValue.spec.tsx                   | 15 ++++++++++++++-
 2 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/.changeset/soft-berries-obey.md b/.changeset/soft-berries-obey.md
index b428fe5f29..b3ab179499 100644
--- a/.changeset/soft-berries-obey.md
+++ b/.changeset/soft-berries-obey.md
@@ -4,4 +4,5 @@
 
 - Extends `useControlledValue` to accept any type.
 - Adds `updateValue` function in return value. This method triggers a synthetic event to update the value of a controlled or uncontrolled component.
+- Adds `initialValue` argument. Used for setting the initial value for uncontrolled components. Without this we may encounter a React error for switching between controlled/uncontrolled inputs
 - The value of `isControlled` is now immutable after the first render
diff --git a/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx b/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
index 17a3fec8ec..cbc5d43611 100644
--- a/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
+++ b/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
@@ -15,7 +15,17 @@ const mutableRefMock = {
   current: document.createElement('div'),
 };
 
+const errorSpy = jest.spyOn(console, 'error');
+
 describe('packages/hooks/useControlledValue', () => {
+  beforeEach(() => {
+    errorSpy.mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    errorSpy.mockReset();
+  });
+
   describe('with controlled component', () => {
     test('calling with a value sets value and isControlled', () => {
       const { result } = renderHook(v => useControlledValue(v), {
@@ -235,6 +245,7 @@ describe('packages/hooks/useControlledValue', () => {
       act(() => rerender('apple'));
       expect(result.current.isControlled).toBe(false);
       expect(result.current.value).toBe('');
+      expect(errorSpy).not.toHaveBeenCalled();
     });
   });
 
@@ -246,12 +257,13 @@ describe('packages/hooks/useControlledValue', () => {
       valueProp?: string;
       handlerProp?: ChangeEventHandler;
     }) => {
+      const initialVal = '';
       const inputRef = useRef<HTMLInputElement>(null);
       // eslint-disable-next-line react-hooks/rules-of-hooks
       const { value, handleChange, updateValue } = useControlledValue(
         valueProp,
         handlerProp,
-        '',
+        initialVal,
       );
 
       return (
@@ -318,6 +330,7 @@ describe('packages/hooks/useControlledValue', () => {
         const result = render(<TestComponent />);
         const input = result.getByTestId('test-input');
         expect(input).toHaveValue('');
+        expect(errorSpy).not.toHaveBeenCalled();
       });
 
       test('user interaction triggers handler', () => {

From 50a45ae491ea209d999d8a133c6aaec375bc0feb Mon Sep 17 00:00:00 2001
From: Adam Thompson <adam.thompson@mongodb.com>
Date: Fri, 25 Aug 2023 12:33:53 -0400
Subject: [PATCH 11/16] Adds NextLink legacyBehavior test

---
 packages/button/src/Button/Button.spec.tsx | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/packages/button/src/Button/Button.spec.tsx b/packages/button/src/Button/Button.spec.tsx
index 2cb453d69e..f488039fda 100644
--- a/packages/button/src/Button/Button.spec.tsx
+++ b/packages/button/src/Button/Button.spec.tsx
@@ -146,7 +146,24 @@ describe('packages/button', () => {
     test(`renders a when passing in a NextJS Link wrapper`, () => {
       // eslint-disable-next-line react/prop-types
       const Linker = ({ href, children, ...props }: any) => (
-        <NextLink href={href}>
+        <NextLink href={href} {...props}>
+          {children}
+        </NextLink>
+      );
+
+      const { container, button } = renderButton({
+        href: 'https://mongodb.design',
+        as: Linker,
+      });
+
+      expect(container.querySelector('button')).not.toBeInTheDocument();
+      expect(button.tagName.toLowerCase()).toBe('a');
+    });
+
+    test(`renders a when passing in a legacy NextJS Link wrapper`, () => {
+      // eslint-disable-next-line react/prop-types
+      const Linker = ({ href, children, ...props }: any) => (
+        <NextLink legacyBehavior href={href}>
           <a {...props}>{children}</a>
         </NextLink>
       );

From 80dc30c464c496daf97aa8633bd17f71cfca123c Mon Sep 17 00:00:00 2001
From: Adam Thompson <adam.thompson@mongodb.com>
Date: Fri, 25 Aug 2023 12:46:50 -0400
Subject: [PATCH 12/16] rm lib from dev dep

---
 packages/hooks/package.json | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/packages/hooks/package.json b/packages/hooks/package.json
index dd703afe60..28ec0140ee 100644
--- a/packages/hooks/package.json
+++ b/packages/hooks/package.json
@@ -35,7 +35,6 @@
     "url": "https://jira.mongodb.org/projects/PD/summary"
   },
   "devDependencies": {
-    "@leafygreen-ui/emotion": "^4.0.7",
-    "@leafygreen-ui/lib": "^11.0.0"
+    "@leafygreen-ui/emotion": "^4.0.7"
   }
 }

From a697215dbd6159af381ee695a33590c31f1498e4 Mon Sep 17 00:00:00 2001
From: Adam Thompson <adam.thompson@mongodb.com>
Date: Fri, 15 Sep 2023 18:32:29 -0400
Subject: [PATCH 13/16] Update useControlledValue.spec.tsx

---
 .../useControlledValue.spec.tsx                  | 16 ++++++++++++----
 1 file changed, 12 insertions(+), 4 deletions(-)

diff --git a/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx b/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
index cbc5d43611..1e6dfa7fcd 100644
--- a/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
+++ b/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
@@ -27,7 +27,7 @@ describe('packages/hooks/useControlledValue', () => {
   });
 
   describe('with controlled component', () => {
-    test('calling with a value sets value and isControlled', () => {
+    test('rendering with no value', () => {
       const { result } = renderHook(v => useControlledValue(v), {
         initialProps: 'apple',
       });
@@ -35,7 +35,15 @@ describe('packages/hooks/useControlledValue', () => {
       expect(result.current.value).toBe('apple');
     });
 
-    test('calling with a new value changes the value', () => {
+    test('rendering with a value sets value and isControlled', () => {
+      const { result } = renderHook(v => useControlledValue(v), {
+        initialProps: 'apple',
+      });
+      expect(result.current.isControlled).toBe(true);
+      expect(result.current.value).toBe('apple');
+    });
+
+    test('rerendering with a new value changes the value', () => {
       const { result, rerender } = renderHook(v => useControlledValue(v), {
         initialProps: 'apple',
       });
@@ -109,7 +117,7 @@ describe('packages/hooks/useControlledValue', () => {
       expect(result.current.value).toBe('apple');
     });
 
-    describe('value types', () => {
+    describe('accepts various value types', () => {
       test('accepts number values', () => {
         const { result } = renderHook(v => useControlledValue(v), {
           initialProps: 5,
@@ -148,7 +156,7 @@ describe('packages/hooks/useControlledValue', () => {
         expect(result.current.value).toBe(date);
       });
 
-      test('accepts multiple types', () => {
+      test('accepts multiple/union types', () => {
         const { result, rerender } = renderHook(
           v => useControlledValue<string | number>(v),
           {

From 7a833ae6a0562263573084729c21ad79cdfab620 Mon Sep 17 00:00:00 2001
From: Adam Thompson <adam.thompson@mongodb.com>
Date: Mon, 18 Sep 2023 16:57:17 -0400
Subject: [PATCH 14/16] updates useControlled value to be more flexible

---
 .../useControlledValue.spec.tsx               | 345 +++++++-----------
 .../useControlledValue/useControlledValue.ts  | 102 ++----
 2 files changed, 168 insertions(+), 279 deletions(-)

diff --git a/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx b/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
index 1e6dfa7fcd..88ffd43277 100644
--- a/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
+++ b/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
@@ -1,21 +1,23 @@
-import React, { useRef } from 'react';
-import { ChangeEvent, ChangeEventHandler } from 'react';
+import React from 'react';
+import { ChangeEventHandler } from 'react';
 import { act } from 'react-test-renderer';
 import { render } from '@testing-library/react';
-import { renderHook } from '@testing-library/react-hooks';
+import { renderHook, RenderHookResult } from '@testing-library/react-hooks';
 import userEvent from '@testing-library/user-event';
 
 import { useControlledValue } from './useControlledValue';
 
-const changeEventMock = {
-  target: { value: 'banana' },
-} as ChangeEvent<any>;
+const errorSpy = jest.spyOn(console, 'error');
 
-const mutableRefMock = {
-  current: document.createElement('div'),
-};
+const renderUseControlledValueHook = <T extends any>(
+  ...[valueProp, callback, initial]: Parameters<typeof useControlledValue<T>>
+): RenderHookResult<T, ReturnType<typeof useControlledValue<T>>> => {
+  const result = renderHook(v => useControlledValue(v, callback, initial), {
+    initialProps: valueProp,
+  });
 
-const errorSpy = jest.spyOn(console, 'error');
+  return { ...result };
+};
 
 describe('packages/hooks/useControlledValue', () => {
   beforeEach(() => {
@@ -26,265 +28,190 @@ describe('packages/hooks/useControlledValue', () => {
     errorSpy.mockReset();
   });
 
-  describe('with controlled component', () => {
-    test('rendering with no value', () => {
-      const { result } = renderHook(v => useControlledValue(v), {
-        initialProps: 'apple',
-      });
-      expect(result.current.isControlled).toBe(true);
-      expect(result.current.value).toBe('apple');
-    });
+  test('rendering without any arguments sets hook to uncontrolled', () => {
+    const {
+      result: { current },
+    } = renderUseControlledValueHook();
+    expect(current.isControlled).toEqual(false);
+  });
 
-    test('rendering with a value sets value and isControlled', () => {
-      const { result } = renderHook(v => useControlledValue(v), {
-        initialProps: 'apple',
-      });
-      expect(result.current.isControlled).toBe(true);
-      expect(result.current.value).toBe('apple');
+  describe('accepts various value types', () => {
+    test('accepts number values', () => {
+      const {
+        result: { current },
+      } = renderUseControlledValueHook(5);
+      expect(current.value).toBe(5);
     });
 
-    test('rerendering with a new value changes the value', () => {
-      const { result, rerender } = renderHook(v => useControlledValue(v), {
-        initialProps: 'apple',
-      });
-
-      expect(result.current.value).toBe('apple');
-
-      act(() => {
-        rerender('banana');
-      });
-
-      expect(result.current.value).toBe('banana');
+    test('accepts boolean values', () => {
+      const {
+        result: { current },
+      } = renderUseControlledValueHook(false);
+      expect(current.value).toBe(false);
     });
 
-    test('provided handler is called within returned hook handler', () => {
-      const handler = jest.fn();
-      const { result } = renderHook(v => useControlledValue(v, handler), {
-        initialProps: 'apple',
-      });
+    test('accepts array values', () => {
+      const arr = ['foo', 'bar'];
+      const {
+        result: { current },
+      } = renderUseControlledValueHook(arr);
+      expect(current.value).toBe(arr);
+    });
 
-      // simulate responding to an event
-      act(() => {
-        result.current.handleChange(changeEventMock);
-      });
-      expect(handler).toHaveBeenCalledWith(
-        expect.objectContaining(changeEventMock),
-      );
-      // value doesn't change unless we explicitly change it
-      expect(result.current.value).toBe('apple');
+    test('accepts object values', () => {
+      const obj = { foo: 'foo', bar: 'bar' };
+      const {
+        result: { current },
+      } = renderUseControlledValueHook(obj);
+      expect(current.value).toBe(obj);
     });
 
-    test('setting value to undefined should keep the component controlled', () => {
-      const { result, rerender } = renderHook(v => useControlledValue(v), {
-        initialProps: 'apple',
-      });
-      expect(result.current.isControlled).toBe(true);
-      act(() => rerender(undefined));
-      expect(result.current.isControlled).toBe(true);
+    test('accepts date values', () => {
+      const date = new Date('2023-08-23');
+      const {
+        result: { current },
+      } = renderUseControlledValueHook(date);
+      expect(current.value).toBe(date);
     });
 
-    test('setUncontrolledValue does nothing for controlled components', () => {
-      const { result } = renderHook(v => useControlledValue(v), {
-        initialProps: 'apple',
-      });
+    test('accepts multiple/union types', () => {
+      const { result, rerender } = renderHook(
+        v => useControlledValue<string | number>(v),
+        {
+          initialProps: 5 as string | number,
+        },
+      );
+      expect(result.current.value).toBe(5);
       act(() => {
-        result.current.setUncontrolledValue('banana');
+        rerender('foo');
       });
-      expect(result.current.value).toBe('apple');
+      expect(result.current.value).toBe('foo');
     });
+  });
 
-    test('updateValue triggers the provided handler', async () => {
-      const handler = jest.fn();
-
-      const { result } = renderHook(v => useControlledValue(v, handler), {
-        initialProps: 'apple',
-      });
+  describe('Controlled', () => {
+    test('rendering with a value sets value and isControlled', () => {
+      const {
+        result: { current },
+      } = renderUseControlledValueHook('apple');
+      expect(current.isControlled).toBe(true);
+      expect(current.value).toBe('apple');
+    });
 
-      await act(() => {
-        result.current.updateValue('banana', mutableRefMock);
-      });
+    test('rerendering from initial undefined sets value and isControlled', async () => {
+      const { rerender, result } = renderUseControlledValueHook();
+      rerender('apple');
 
-      expect(handler).toHaveBeenCalled();
+      expect(result.current.isControlled).toBe(true);
+      expect(result.current.value).toEqual('apple');
     });
 
-    test('initial value is ignored when controlled', () => {
-      const { result } = renderHook(
-        v => useControlledValue(v, null, 'foobar'),
-        {
-          initialProps: 'apple',
-        },
-      );
+    test('rerendering with a new value changes the value', () => {
+      const { rerender, result } = renderUseControlledValueHook('apple');
+
       expect(result.current.value).toBe('apple');
+
+      rerender('banana');
+      expect(result.current.value).toBe('banana');
     });
 
-    describe('accepts various value types', () => {
-      test('accepts number values', () => {
-        const { result } = renderHook(v => useControlledValue(v), {
-          initialProps: 5,
-        });
-        expect(result.current.value).toBe(5);
-      });
+    test('provided handler is called within `updateValue`', () => {
+      const handler = jest.fn();
+      const {
+        result: { current },
+      } = renderUseControlledValueHook<string>('apple', handler);
 
-      test('accepts boolean values', () => {
-        const { result } = renderHook(v => useControlledValue(v), {
-          initialProps: false,
-        });
-        expect(result.current.value).toBe(false);
-      });
+      current.updateValue('banana');
 
-      test('accepts array values', () => {
-        const arr = ['foo', 'bar'];
-        const { result } = renderHook(v => useControlledValue(v), {
-          initialProps: arr,
-        });
-        expect(result.current.value).toBe(arr);
-      });
+      expect(handler).toHaveBeenCalledWith('banana');
+    });
 
-      test('accepts object values', () => {
-        const obj = { foo: 'foo', bar: 'bar' };
-        const { result } = renderHook(v => useControlledValue(v), {
-          initialProps: obj,
-        });
-        expect(result.current.value).toBe(obj);
-      });
+    test('hook value does not change when `updateValue` is called', () => {
+      const {
+        result: { current },
+      } = renderUseControlledValueHook<string>('apple');
 
-      test('accepts date values', () => {
-        const date = new Date('2023-08-23');
-        const { result } = renderHook(v => useControlledValue(v), {
-          initialProps: date,
-        });
-        expect(result.current.value).toBe(date);
-      });
+      current.updateValue('banana');
 
-      test('accepts multiple/union types', () => {
-        const { result, rerender } = renderHook(
-          v => useControlledValue<string | number>(v),
-          {
-            initialProps: 5 as string | number,
-          },
-        );
-        expect(result.current.value).toBe(5);
-        act(() => {
-          rerender('foo');
-        });
-        expect(result.current.value).toBe('foo');
-      });
+      // value doesn't change unless we explicitly change it
+      expect(current.value).toBe('apple');
     });
-  });
 
-  describe('with uncontrolled component', () => {
-    test('calling without a value sets value to initialValue and isControlled: false', () => {
-      const { result } = renderHook(v => useControlledValue(v, null, ''), {
-        initialProps: undefined,
-      });
-      expect(result.current.isControlled).toBe(false);
-      expect(result.current.value).toBe('');
+    test('setting value to undefined should keep the component controlled', () => {
+      const {
+        rerender,
+        result: { current },
+      } = renderUseControlledValueHook<string>('apple');
+      expect(current.isControlled).toBe(true);
+      act(() => rerender(undefined));
+      expect(current.isControlled).toBe(true);
     });
 
-    test('setUncontrolledValue updates value', () => {
-      const handler = jest.fn();
-      const { result } = renderHook(
-        v => useControlledValue<string>(v, handler, ''),
-        {
-          initialProps: undefined,
-        },
-      );
-
-      act(() => {
-        result.current.setUncontrolledValue('apple');
-      });
-      expect(result.current.value).toBe('apple');
-      expect(handler).not.toHaveBeenCalled();
+    test('initial value is ignored when controlled', () => {
+      const {
+        result: { current },
+      } = renderUseControlledValueHook<string>('apple', () => {}, 'banana');
+      expect(current.value).toBe('apple');
     });
+  });
 
-    test('provided handler should be called', () => {
-      const handler = jest.fn();
-      const { result } = renderHook(v => useControlledValue(v, handler, ''), {
-        initialProps: undefined,
-      });
+  describe('Uncontrolled', () => {
+    test('calling without a value sets value to `initialValue`', () => {
+      const {
+        result: { current },
+      } = renderUseControlledValueHook(undefined, () => {}, 'apple');
 
-      act(() => {
-        result.current.handleChange(changeEventMock);
-      });
-      expect(handler).toHaveBeenCalledWith(
-        expect.objectContaining(changeEventMock),
-      );
+      expect(current.isControlled).toBe(false);
+      expect(current.value).toBe('apple');
     });
 
-    test('updateValue updates value & calls handler', () => {
+    test('provided handler is called within `updateValue`', () => {
       const handler = jest.fn();
-      const { result } = renderHook(
-        v => useControlledValue<string>(v, handler, ''),
-        {
-          initialProps: undefined,
-        },
-      );
+      const {
+        result: { current },
+      } = renderUseControlledValueHook(undefined, handler);
 
-      act(() => {
-        result.current.updateValue('banana', mutableRefMock);
-      });
-
-      expect(handler).toHaveBeenCalled();
-      expect(result.current.value).toBe('banana');
+      current.updateValue('apple');
+      expect(handler).toHaveBeenCalledWith('apple');
     });
 
-    test('calling the returned handler sets the value', () => {
-      const handler = jest.fn();
-      const { result } = renderHook(v => useControlledValue(v, handler, ''), {
-        initialProps: undefined,
-      });
-
-      act(() => {
-        result.current.handleChange(changeEventMock);
-      });
+    test('updateValue updates the value', () => {
+      const { result } = renderUseControlledValueHook<string>(undefined);
+      result.current.updateValue('banana');
       expect(result.current.value).toBe('banana');
     });
-
-    test('changing value prop from initial undefined is ignored', () => {
-      const { result, rerender } = renderHook(
-        v => useControlledValue<string>(v, null, ''),
-        {
-          initialProps: undefined,
-        },
-      );
-      expect(result.current.isControlled).toBe(false);
-      expect(result.current.value).toBe('');
-      // @ts-ignore - picking up renderHook.options types, not actual hook types
-      act(() => rerender('apple'));
-      expect(result.current.isControlled).toBe(false);
-      expect(result.current.value).toBe('');
-      expect(errorSpy).not.toHaveBeenCalled();
-    });
   });
 
-  describe('with test component', () => {
+  describe('Within test component', () => {
     const TestComponent = ({
       valueProp,
       handlerProp,
     }: {
       valueProp?: string;
-      handlerProp?: ChangeEventHandler;
+      handlerProp?: (val?: string) => void;
     }) => {
       const initialVal = '';
-      const inputRef = useRef<HTMLInputElement>(null);
       // eslint-disable-next-line react-hooks/rules-of-hooks
-      const { value, handleChange, updateValue } = useControlledValue(
+      const { value, updateValue } = useControlledValue(
         valueProp,
         handlerProp,
         initialVal,
       );
 
+      const handleChange: ChangeEventHandler<HTMLInputElement> = e => {
+        updateValue(e.target.value);
+      };
+
       return (
         <>
           <input
-            ref={inputRef}
             data-testid="test-input"
             value={value}
             onChange={handleChange}
           />
           <button
             data-testid="test-button"
-            onClick={() => updateValue('carrot', inputRef)}
+            onClick={() => updateValue('carrot')}
           />
         </>
       );
@@ -311,7 +238,7 @@ describe('packages/hooks/useControlledValue', () => {
         );
         const input = result.getByTestId('test-input');
         userEvent.type(input, 'b');
-        expect(handler).toHaveBeenCalled();
+        expect(handler).toHaveBeenCalledWith(expect.stringContaining('b'));
       });
 
       test('user interaction does not change the element value', () => {
@@ -323,14 +250,6 @@ describe('packages/hooks/useControlledValue', () => {
         userEvent.type(input, 'b');
         expect(input).toHaveValue('apple');
       });
-
-      test('clicking the button updates the value', () => {
-        const result = render(<TestComponent valueProp="apple" />);
-        const input = result.getByTestId('test-input');
-        const button = result.getByTestId('test-button');
-        userEvent.click(button);
-        expect(input).toHaveValue('carrot');
-      });
     });
 
     describe('Uncontrolled test component', () => {
diff --git a/packages/hooks/src/useControlledValue/useControlledValue.ts b/packages/hooks/src/useControlledValue/useControlledValue.ts
index e2d5c45842..07eed7592e 100644
--- a/packages/hooks/src/useControlledValue/useControlledValue.ts
+++ b/packages/hooks/src/useControlledValue/useControlledValue.ts
@@ -1,14 +1,6 @@
-import {
-  ChangeEventHandler,
-  MutableRefObject,
-  useEffect,
-  useMemo,
-  useState,
-} from 'react';
+import { useMemo, useState } from 'react';
 import isUndefined from 'lodash/isUndefined';
 
-import { consoleOnce, createSyntheticEvent } from '@leafygreen-ui/lib';
-
 interface ControlledValueReturnObject<T extends any> {
   /** Whether the value is controlled */
   isControlled: boolean;
@@ -16,84 +8,62 @@ interface ControlledValueReturnObject<T extends any> {
   /** The controlled or uncontrolled value */
   value: T;
 
-  /** A ChangeEventHandler to assign to any onChange event */
-  handleChange: ChangeEventHandler<any>;
-
-  /**
-   * 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>>;
-
   /**
-   * Synthetically triggers a change event within the `handleChange` callback.
-   * Signals that the value should change for controlled components,
-   * and updates the internal value for uncontrolled components
+   * Either updates the uncontrolled value,
+   * or calls the provided `onChange` callback
    */
-  updateValue: (newVal: T, ref: MutableRefObject<any>) => void;
+  updateValue: (newVal?: T, ...args: Array<any>) => void;
 }
 
 /**
  * A hook that enables a component to be both controlled or uncontrolled.
  *
- * Returns a {@link ControlledValueReturnObject} with the controlled or uncontrolled `value`,
- * `onChange` & `onClear` handlers, a `setInternalValue` setter, and a boolean `isControlled`
+ * Returns a {@link ControlledValueReturnObject}
  */
-export const useControlledValue = <T>(
-  controlledValue?: T,
-  changeHandler?: ChangeEventHandler<any> | null,
-  initialValue?: T,
+export const useControlledValue = <T extends any>(
+  valueProp?: T,
+  onChange?: (val?: T, ...args: Array<any>) => void,
+  initialProp?: T,
 ): ControlledValueReturnObject<T | undefined> => {
-  // isControlled should only be computed once
-  // eslint-disable-next-line react-hooks/exhaustive-deps
-  const isControlled = useMemo(() => !isUndefined(controlledValue), []);
+  // Initially set isControlled to the existence of `valueProp`.
+  // If the value prop changes from undefined to something defined,
+  // then isControlled is set to true,
+  // and will remain true for the life of the component
+  const isControlled: boolean = useMemo(() => {
+    return isControlled || !isUndefined(valueProp);
+  }, [valueProp]);
+
+  // We set the initial value to either the `value`
+  // or the temporary `initialValue` prop
+  const initialValue = useMemo(
+    () => (isControlled ? valueProp : initialProp),
+    [initialProp, isControlled, valueProp],
+  );
 
-  // Keep track of the uncontrolled value state internally
+  // Keep track of the internal value state
   const [uncontrolledValue, setUncontrolledValue] = useState<T | undefined>(
     initialValue,
   );
 
-  // Create a change event handler that either updates the internal state
-  // or fires an external change handler
-  const handleChange: ChangeEventHandler<any> = e => {
-    changeHandler?.(e);
-    if (!isControlled) {
-      setUncontrolledValue(e.target.value as T);
-    }
-  };
+  // The returned value is wither the provided value prop
+  // or the uncontrolled value
+  const value = useMemo(
+    () => (isControlled ? valueProp : uncontrolledValue),
+    [isControlled, uncontrolledValue, valueProp],
+  );
 
   // A wrapper around `handleChange` that fires a simulated event
-  const updateValue = (newVal: T | undefined, ref: MutableRefObject<any>) => {
-    if (ref.current) {
-      ref.current.value = newVal;
-      const synthEvt = createSyntheticEvent(
-        new Event('change', {
-          cancelable: true,
-          bubbles: true,
-        }),
-        ref.current,
-      );
-
-      handleChange(synthEvt);
+  const updateValue = (newVal: T | undefined) => {
+    if (!isControlled) {
+      setUncontrolledValue(newVal);
     }
-  };
 
-  useEffect(() => {
-    // Log a warning if neither controlled value or initialValue is provided
-    if (isUndefined(controlledValue) && isUndefined(initialValue)) {
-      consoleOnce.error(
-        `Warning: \`useControlledValue\` hook is being used without a value or initialValue. This will cause a React warning when the input changes. Please decide between using a controlled or uncontrolled input element, and provide either a controlledValue or initialValue to \`useControlledValue\``,
-      );
-    }
-  }, [controlledValue, initialValue]);
+    onChange?.(newVal);
+  };
 
   return {
     isControlled,
-    value: isControlled ? controlledValue : uncontrolledValue,
-    handleChange,
-    setUncontrolledValue,
+    value,
     updateValue,
   };
 };

From cf61a279712fbee761eb65c159f4820cfcfd0bda Mon Sep 17 00:00:00 2001
From: Adam Thompson <adam.thompson@mongodb.com>
Date: Mon, 18 Sep 2023 17:17:16 -0400
Subject: [PATCH 15/16] add warnings

---
 .../useControlledValue.spec.tsx               | 114 +++++++-----------
 .../useControlledValue/useControlledValue.ts  |  25 +++-
 2 files changed, 69 insertions(+), 70 deletions(-)

diff --git a/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx b/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
index 88ffd43277..7f3ad040d2 100644
--- a/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
+++ b/packages/hooks/src/useControlledValue/useControlledValue.spec.tsx
@@ -1,6 +1,5 @@
 import React from 'react';
 import { ChangeEventHandler } from 'react';
-import { act } from 'react-test-renderer';
 import { render } from '@testing-library/react';
 import { renderHook, RenderHookResult } from '@testing-library/react-hooks';
 import userEvent from '@testing-library/user-event';
@@ -29,129 +28,98 @@ describe('packages/hooks/useControlledValue', () => {
   });
 
   test('rendering without any arguments sets hook to uncontrolled', () => {
-    const {
-      result: { current },
-    } = renderUseControlledValueHook();
-    expect(current.isControlled).toEqual(false);
+    const { result } = renderUseControlledValueHook();
+    expect(result.current.isControlled).toEqual(false);
   });
 
   describe('accepts various value types', () => {
     test('accepts number values', () => {
-      const {
-        result: { current },
-      } = renderUseControlledValueHook(5);
-      expect(current.value).toBe(5);
+      const { result } = renderUseControlledValueHook(5);
+      expect(result.current.value).toBe(5);
     });
 
     test('accepts boolean values', () => {
-      const {
-        result: { current },
-      } = renderUseControlledValueHook(false);
-      expect(current.value).toBe(false);
+      const { result } = renderUseControlledValueHook(false);
+      expect(result.current.value).toBe(false);
     });
 
     test('accepts array values', () => {
       const arr = ['foo', 'bar'];
-      const {
-        result: { current },
-      } = renderUseControlledValueHook(arr);
-      expect(current.value).toBe(arr);
+      const { result } = renderUseControlledValueHook(arr);
+      expect(result.current.value).toBe(arr);
     });
 
     test('accepts object values', () => {
       const obj = { foo: 'foo', bar: 'bar' };
-      const {
-        result: { current },
-      } = renderUseControlledValueHook(obj);
-      expect(current.value).toBe(obj);
+      const { result } = renderUseControlledValueHook(obj);
+      expect(result.current.value).toBe(obj);
     });
 
     test('accepts date values', () => {
       const date = new Date('2023-08-23');
-      const {
-        result: { current },
-      } = renderUseControlledValueHook(date);
-      expect(current.value).toBe(date);
+      const { result } = renderUseControlledValueHook(date);
+      expect(result.current.value).toBe(date);
     });
 
     test('accepts multiple/union types', () => {
-      const { result, rerender } = renderHook(
-        v => useControlledValue<string | number>(v),
-        {
-          initialProps: 5 as string | number,
-        },
-      );
+      const { result, rerender } = renderUseControlledValueHook<
+        string | number
+      >(5);
       expect(result.current.value).toBe(5);
-      act(() => {
-        rerender('foo');
-      });
+      rerender('foo');
       expect(result.current.value).toBe('foo');
     });
   });
 
   describe('Controlled', () => {
     test('rendering with a value sets value and isControlled', () => {
-      const {
-        result: { current },
-      } = renderUseControlledValueHook('apple');
-      expect(current.isControlled).toBe(true);
-      expect(current.value).toBe('apple');
+      const { result } = renderUseControlledValueHook('apple');
+      expect(result.current.isControlled).toBe(true);
+      expect(result.current.value).toBe('apple');
     });
 
     test('rerendering from initial undefined sets value and isControlled', async () => {
       const { rerender, result } = renderUseControlledValueHook();
       rerender('apple');
-
       expect(result.current.isControlled).toBe(true);
       expect(result.current.value).toEqual('apple');
     });
 
     test('rerendering with a new value changes the value', () => {
       const { rerender, result } = renderUseControlledValueHook('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: { current },
-      } = renderUseControlledValueHook<string>('apple', handler);
-
-      current.updateValue('banana');
-
+      const { result } = renderUseControlledValueHook<string>('apple', handler);
+      result.current.updateValue('banana');
       expect(handler).toHaveBeenCalledWith('banana');
     });
 
     test('hook value does not change when `updateValue` is called', () => {
-      const {
-        result: { current },
-      } = renderUseControlledValueHook<string>('apple');
-
-      current.updateValue('banana');
-
+      const { result } = renderUseControlledValueHook<string>('apple');
+      result.current.updateValue('banana');
       // value doesn't change unless we explicitly change it
-      expect(current.value).toBe('apple');
+      expect(result.current.value).toBe('apple');
     });
 
     test('setting value to undefined should keep the component controlled', () => {
-      const {
-        rerender,
-        result: { current },
-      } = renderUseControlledValueHook<string>('apple');
-      expect(current.isControlled).toBe(true);
-      act(() => rerender(undefined));
-      expect(current.isControlled).toBe(true);
+      const { rerender, result } = renderUseControlledValueHook('apple');
+      expect(result.current.isControlled).toBe(true);
+      rerender(undefined);
+      expect(result.current.isControlled).toBe(true);
     });
 
     test('initial value is ignored when controlled', () => {
-      const {
-        result: { current },
-      } = renderUseControlledValueHook<string>('apple', () => {}, 'banana');
-      expect(current.value).toBe('apple');
+      const { result } = renderUseControlledValueHook<string>(
+        'apple',
+        () => {},
+        'banana',
+      );
+      expect(result.current.value).toBe('apple');
     });
   });
 
@@ -217,7 +185,7 @@ describe('packages/hooks/useControlledValue', () => {
       );
     };
 
-    describe('Controlled test component', () => {
+    describe('Controlled', () => {
       test('initially renders with a value', () => {
         const result = render(<TestComponent valueProp="apple" />);
         const input = result.getByTestId('test-input');
@@ -242,9 +210,17 @@ describe('packages/hooks/useControlledValue', () => {
       });
 
       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');
+      });
+
+      // eslint-disable-next-line jest/no-disabled-tests
+      test.skip('user interaction does not change the element value when initially undefined', () => {
         const handler = jest.fn();
         const result = render(
-          <TestComponent valueProp="apple" handlerProp={handler} />,
+          <TestComponent valueProp={undefined} handlerProp={handler} />,
         );
         const input = result.getByTestId('test-input');
         userEvent.type(input, 'b');
@@ -252,7 +228,7 @@ describe('packages/hooks/useControlledValue', () => {
       });
     });
 
-    describe('Uncontrolled test component', () => {
+    describe('Uncontrolled', () => {
       test('initially renders without a value', () => {
         const result = render(<TestComponent />);
         const input = result.getByTestId('test-input');
diff --git a/packages/hooks/src/useControlledValue/useControlledValue.ts b/packages/hooks/src/useControlledValue/useControlledValue.ts
index 07eed7592e..e55d570c17 100644
--- a/packages/hooks/src/useControlledValue/useControlledValue.ts
+++ b/packages/hooks/src/useControlledValue/useControlledValue.ts
@@ -1,6 +1,10 @@
-import { useMemo, useState } from 'react';
+import { useEffect, useMemo, useState } from 'react';
 import isUndefined from 'lodash/isUndefined';
 
+import { consoleOnce } from '@leafygreen-ui/lib';
+
+import usePrevious from '../usePrevious';
+
 interface ControlledValueReturnObject<T extends any> {
   /** Whether the value is controlled */
   isControlled: boolean;
@@ -32,6 +36,25 @@ export const useControlledValue = <T extends any>(
   const isControlled: boolean = useMemo(() => {
     return isControlled || !isUndefined(valueProp);
   }, [valueProp]);
+  const wasControlled = usePrevious(isControlled);
+
+  useEffect(() => {
+    if (isUndefined(isControlled) || isUndefined(wasControlled)) return;
+
+    if (isControlled !== wasControlled) {
+      const err = `WARN: A component changed from ${
+        wasControlled ? 'controlled' : 'uncontrolled'
+      } to ${
+        isControlled ? 'controlled' : 'uncontrolled'
+      }. This can cause issues with React states. ${
+        isControlled
+          ? 'To control a component but have an initially empty input, consider setting the `value` prop to `null`.'
+          : ''
+      }`;
+
+      consoleOnce.warn(err);
+    }
+  }, [isControlled, wasControlled]);
 
   // We set the initial value to either the `value`
   // or the temporary `initialValue` prop

From d4af1bd47b15678bdaf6140a58eddf73c11cbc29 Mon Sep 17 00:00:00 2001
From: Adam Thompson <adam.thompson@mongodb.com>
Date: Mon, 18 Sep 2023 17:19:38 -0400
Subject: [PATCH 16/16] Update soft-berries-obey.md

---
 .changeset/soft-berries-obey.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/.changeset/soft-berries-obey.md b/.changeset/soft-berries-obey.md
index b3ab179499..bf46541737 100644
--- a/.changeset/soft-berries-obey.md
+++ b/.changeset/soft-berries-obey.md
@@ -1,8 +1,8 @@
 ---
-'@leafygreen-ui/hooks': minor
+'@leafygreen-ui/hooks': major
 ---
 
 - Extends `useControlledValue` to accept any type.
-- Adds `updateValue` function in return value. This method triggers a synthetic event to update the value of a controlled or uncontrolled component.
-- Adds `initialValue` argument. Used for setting the initial value for uncontrolled components. Without this we may encounter a React error for switching between controlled/uncontrolled inputs
-- The value of `isControlled` is now immutable after the first render
+  - Adds `initialValue` argument. Used for setting the initial value for uncontrolled components. Without this we may encounter a React error for switching between controlled/uncontrolled inputs
+  - Changes signature of `onChange` argument to be a simple setter function (`(value: T) => void`)
+  - Changes return object to include only `isControlled`, `value` and an `updateValue` setter function