Create useClientSideValue hook #116 (#160)

* Create useClientSideValue hook #116

* Add initialValue option

* Fix eslint warning

README.md

@@ -115,7 +115,7 @@ const { result, rerender, unmount } = renderHook(useToggle, {
 // inspect the response of the hook
 console.log(result.current);
 
-await act(() => {
+act(() => {
   // interact with your hook
   result.current[1]();
 });

src/hooks/useClientSideValue/useClientSideValue.mdx

@@ -0,0 +1,55 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="hooks/useClientSideValue" />
+
+# useClientSideValue
+
+Hook that returns the value returned by a callback function that is only called on client-side.
+
+## Reference
+
+```ts
+function useClientSideValue<T extends () => unknown>(callback: T): ReturnType<T> | null;
+```
+
+## Usage
+
+Use this hook when an API is not available on the server or may return a different result on the
+server to avoid hydration mismatches.
+
+Common use cases:
+
+- Date APIs
+- Intl APIs
+
+```tsx
+type MyComponentProps = {
+  serverTime: Date;
+};
+
+function MyComponent({ serverTime }): ReactElement {
+  const now = useClientSideValue(Date.now, serverTime);
+
+  return <>{now ?? 'n/a'}</>;
+}
+```
+
+```tsx
+type MyComponentProps = {
+  bytes: number;
+};
+
+function MyComponent({ bytes }: MyComponentProps): ReactElement {
+  const numberFormat = useClientSideValue(
+    () =>
+      new Intl.NumberFormat(process.env.LOCALE, {
+        notation: 'compact',
+        style: 'unit',
+        unit: 'byte',
+        unitDisplay: 'narrow',
+      }),
+  );
+
+  return <>{numberFormat?.format(bytes) ?? bytes}</>;
+}
+```

src/hooks/useClientSideValue/useClientSideValue.stories.tsx

@@ -0,0 +1,50 @@
+/* eslint-disable react-hooks/rules-of-hooks */
+/* eslint-disable react/jsx-no-literals */
+import type { StoryObj } from '@storybook/react';
+import { useClientSideValue } from './useClientSideValue.js';
+
+export default {
+  title: 'hooks/useClientSideValue',
+};
+
+const note = (
+  <div className="alert alert-secondary">
+    <h4 className="alert-heading">Note!</h4>
+    <p className="mb-0">
+      The initial value before the mount is different in a server-side rendered context, this is not
+      visible in the documentation.
+    </p>
+  </div>
+);
+
+export const Demo: StoryObj = {
+  render() {
+    const value = useClientSideValue(Date.now, 0);
+
+    return (
+      <>
+        <div>
+          Value: <span className="badge rounded-pill bg-primary">{value}</span>
+        </div>
+
+        {note}
+      </>
+    );
+  },
+};
+
+export const Nullable: StoryObj = {
+  render() {
+    const value = useClientSideValue<number | null>(Date.now, null);
+
+    return (
+      <>
+        <div>
+          Value: <span className="badge rounded-pill bg-primary">{value}</span>
+        </div>
+
+        {note}
+      </>
+    );
+  },
+};

src/hooks/useClientSideValue/useClientSideValue.test.tsx

@@ -0,0 +1,20 @@
+import { renderHook } from '@testing-library/react';
+import { useClientSideValue } from './useClientSideValue.js';
+
+describe('useClientSideValue', () => {
+  it('should not crash', async () => {
+    renderHook(() => useClientSideValue(Date.now, 0));
+  });
+
+  it('should set the value once', async () => {
+    let count = 0;
+
+    const { result, rerender } = renderHook(() => useClientSideValue(() => ++count, 0));
+
+    expect(result.current).toBe(1);
+
+    rerender();
+
+    expect(result.current).toBe(1);
+  });
+});

src/hooks/useClientSideValue/useClientSideValue.ts

@@ -0,0 +1,22 @@
+import { useState } from 'react';
+import { useMount } from '../useMount/useMount.js';
+
+/**
+ * Hook that returns the value returned by a callback function that is only called on client-side.
+ *
+ * @example
+ * function MyComponent() {
+ *   const value = useClientSideValue(Date.now, null);
+ *
+ *   return <div>{value ?? 'n/a'}</div>;
+ * }
+ */
+export function useClientSideValue<T>(callback: () => T, initialValue?: T): typeof initialValue {
+  const [value, setValue] = useState(initialValue);
+
+  useMount(() => {
+    setValue(callback);
+  });
+
+  return value;
+}

src/hooks/useForceRerender/useForceRerender.test.tsx

@@ -30,7 +30,7 @@ describe('useForceRerender', () => {
 
     expect(spy).toBeCalledTimes(1);
 
-    await act(() => {
+    act(() => {
       forceRerender();
     });
 

src/hooks/useHasFocus/useHasFocus.test.tsx

@@ -5,7 +5,7 @@ import { useRef, type ReactElement } from 'react';
 import { useHasFocus } from './useHasFocus.js';
 
 describe('useHasFocus', () => {
-  it('should not crash', async () => {
+  it('should not crash', () => {
     function TestComponent(): ReactElement {
       const ref = useRef<HTMLDivElement>(null);
       const hasFocus = useHasFocus(ref);
@@ -18,7 +18,7 @@ describe('useHasFocus', () => {
     expect(result.queryByTestId('focus')).not.toBeInTheDocument();
   });
 
-  it('should update when element has focus within', async () => {
+  it('should update when element has focus within', () => {
     function TestComponent(): ReactElement {
       const ref = useRef<HTMLButtonElement>(null);
       const hasFocus = useHasFocus(ref, ':focus');
@@ -36,7 +36,7 @@ describe('useHasFocus', () => {
 
     const result = render(<TestComponent />);
 
-    await act(() => {
+    act(() => {
       result.getByTestId('button').focus();
     });
 

src/hooks/useRefs/useRefs.test.tsx

@@ -9,7 +9,7 @@ type TestRefs = MutableRefs<{
 }>;
 
 describe('useRefs', () => {
-  it('should not crash', async () => {
+  it('should not crash', () => {
     renderHook(() => {
       useRefs();
     });
@@ -23,10 +23,10 @@ describe('useRefs', () => {
     });
   });
 
-  it('should be able to register a ref', async () => {
+  it('should be able to register a ref', () => {
     const { result } = renderHook(() => useRefs<TestRefs>());
 
-    await act(() => {
+    act(() => {
       result.current.number1.current = 1;
       result.current.number2.current = 2;
     });
@@ -37,16 +37,16 @@ describe('useRefs', () => {
     });
   });
 
-  it('should be able to set a ref to null', async () => {
+  it('should be able to set a ref to null', () => {
     const { result } = renderHook(() => useRefs<TestRefs>());
 
-    await act(() => {
+    act(() => {
       result.current.number1.current = 1;
     });
 
     expect(result.current.number1.current).toEqual(1);
 
-    await act(() => {
+    act(() => {
       result.current.number1.current = null;
     });
 

src/hooks/useRegisterRef/useRegisterRef.test.tsx

@@ -2,7 +2,7 @@ import { act, renderHook } from '@testing-library/react';
 import { useRegisterRef } from './useRegisterRef.js';
 
 describe('useRegisterRef', () => {
-  it('should not crash', async () => {
+  it('should not crash', () => {
     renderHook(useRegisterRef);
   });
 
@@ -14,22 +14,22 @@ describe('useRegisterRef', () => {
     expect(typeof registerRef).toBe('function');
   });
 
-  it('should be able to register a ref', async () => {
+  it('should be able to register a ref', () => {
     const { result } = renderHook(useRegisterRef);
     const [refs, registerRef] = result.current;
 
-    await act(() => {
+    act(() => {
       registerRef('item')('A');
     });
 
     expect(refs).toEqual({ item: 'A' });
   });
 
-  it('should be able to register Array refs', async () => {
+  it('should be able to register Array refs', () => {
     const { result } = renderHook(useRegisterRef);
     const [refs, registerRef] = result.current;
 
-    await act(() => {
+    act(() => {
       // eslint-disable-next-line @typescript-eslint/ban-ts-comment
       // @ts-expect-error
       registerRef('items[]', 0)('A');

src/hooks/useToggle/useToggle.test.ts

@@ -20,40 +20,40 @@ describe('useToggle', () => {
     expect(result2.current[0]).toEqual(false);
   });
 
-  it('should switch the value when calling toggle', async () => {
+  it('should switch the value when calling toggle', () => {
     const { result } = renderHook(useToggle, {
       initialProps: false,
     });
     expect(result.current[0]).toEqual(false);
 
-    await act(() => {
+    act(() => {
       result.current[1]();
     });
     expect(result.current[0]).toEqual(true);
 
-    await act(() => {
+    act(() => {
       result.current[1]();
     });
     expect(result.current[0]).toEqual(false);
   });
 
-  it('should set the value explicitly', async () => {
+  it('should set the value explicitly', () => {
     const { result } = renderHook(useToggle, {
       initialProps: false,
     });
     expect(result.current[0]).toEqual(false);
 
-    await act(() => {
+    act(() => {
       result.current[1](false);
     });
     expect(result.current[0]).toEqual(false);
 
-    await act(() => {
+    act(() => {
       result.current[1](true);
     });
     expect(result.current[0]).toEqual(true);
 
-    await act(() => {
+    act(() => {
       result.current[1](true);
     });
     expect(result.current[0]).toEqual(true);

src/index.ts

@@ -2,6 +2,7 @@
 export * from './components/AutoFill/AutoFill.js';
 export * from './hocs/ensuredForwardRef/ensuredForwardRef.js';
 export * from './hooks/useBeforeMount/useBeforeMount.js';
+export * from './hooks/useClientSideValue/useClientSideValue.js';
 export * from './hooks/useEventListener/useEventListener.js';
 export * from './hooks/useForceRerender/useForceRerender.js';
 export * from './hooks/useHasFocus/useHasFocus.js';
@@ -11,12 +12,12 @@ export * from './hooks/useIsomorphicLayoutEffect/useIsomorphicLayoutEffect.js';
 export * from './hooks/useMediaDuration/useMediaDuration.js';
 export * from './hooks/useMediaQuery/useMediaQuery.js';
 export * from './hooks/useMount/useMount.js';
+export * from './hooks/useRefValue/useRefValue.js';
 export * from './hooks/useRefs/useRefs.js';
 export * from './hooks/useRefs/useRefs.types.js';
 export * from './hooks/useRefs/utils/assertAndUnwrapRefs/assertAndUnwrapRefs.js';
 export * from './hooks/useRefs/utils/unwrapRefs/unwrapRefs.js';
 export * from './hooks/useRefs/utils/unwrapRefs/unwrapRefs.types.js';
-export * from './hooks/useRefValue/useRefValue.js';
 export * from './hooks/useRegisterRef/useRegisterRef.js';
 export * from './hooks/useResizeObserver/useResizeObserver.js';
 export * from './hooks/useStaticValue/useStaticValue.js';