fix(useControlledState): fix multiple function set state actions problem

[kyukyu-dev]

Overview

This PR improves useControlledState to correctly handle multiple functional setState actions executed within the same render cycle.

Previously, functional updates relied on a closure-captured value, which could lead to stale state when multiple updates were batched by React. This change introduces an internal valueRef to always compute the next state from the latest intermediate value.

Additionally, a safe insertion/layout effect is used to keep the ref synchronized with the actual state after each render, ensuring consistent behavior in both controlled and uncontrolled modes.

Problem

useControlledState previously calculated the next value using the value captured in the closure.

const nextValue = isSetStateAction(next) ? next(value) : next;

When multiple functional setState actions were executed within the same render cycle, each updater received the same stale value, because React batches updates.

Example:

setValue(prev => prev + 3);
setValue(prev => prev + 3);

Expected result: 5 → 8 → 11

Actual result: 5 → 8

Both updates used the same previous value (5).

Solution

To ensure each updater receives the latest intermediate value, this PR introduces an internal valueRef.

const valueRef = useRef(uncontrolledState);

The setter now computes updates based on valueRef.current:

const nextValue = isSetStateAction(next) ? next(valueRef.current) : next;

After computing the next value, the ref is updated immediately:

valueRef.current = nextValue;

This ensures subsequent functional updates in the same render cycle receive the correct latest value.

Ref synchronization

Since the ref may be optimistically updated before React commits the actual value, we resync it after each render using a safe insertion/layout effect:

useSafeInsertionEffect(() => {
  valueRef.current = value;
});

This keeps the ref consistent with the real state value.

Controlled mode edge case

In controlled mode, the parent may choose not to update the value.
To ensure the ref resynchronizes correctly in that case, a forced re-render is triggered:

const [, triggerRerender] = useReducer(() => ({}), {});

...

triggerRerender();

Result

useControlledState now correctly handles multiple functional updates:

setValue(prev => prev + 3);
setValue(prev => prev + 3);

// 5 → 8 → 11

without stale closure issues.

Checklist

• Did you write the test code?
• Have you run yarn run fix to format and lint the code and docs?
• Have you run yarn run test:coverage to make sure there is no uncovered line?
• Did you write the JSDoc?