Skip to content

Commit 8a39b0e

Browse files
cliffhallclaude
andcommitted
docs: state useValueChange's referential-stability requirement (#1838)
Copilot review on #1900: the hook compares with `Object.is`, so an object or array literal rebuilt in the component body compares unequal every render. Because the callback is what updates state, that is not merely a wasted render — it is an infinite loop. Every current caller passes a primitive (`boolean`, `string`) or an already- memoized value, so nothing changes behaviorally. But the hazard was implicit, and the next caller is the one it would bite. Documented on the hook itself, and one clause added to the AGENTS.md rule with its mirror in `.github/copilot-instructions.md`. No runtime guard: the requirement is the same one a `useEffect` dependency array carries, and here the failure is loud and immediate rather than silent. `npm run ci` passes. Claude-Session: https://claude.ai/code/session_01YAt8rqxysNbhYWLhoRm3fU Co-authored-by: Claude Opus 5 (1M context) <[email protected]>
1 parent a0ce518 commit 8a39b0e

3 files changed

Lines changed: 12 additions & 2 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ const CardContent = Group.withProps({
5151
### State and effects
5252

5353
- **Never reset or re-sync local state from a prop inside a `useEffect`.** `useEffect(() => setX(prop), [prop])` paints the stale value first and renders twice; it is an error under `react-hooks/set-state-in-effect`.
54-
- Use **`useValueChange(value, onChange)`** (`src/hooks/useValueChange.ts`) — React's documented "adjusting state during render" pattern. It does not fire on the first render; seed the state with `useState`.
54+
- Use **`useValueChange(value, onChange)`** (`src/hooks/useValueChange.ts`) — React's documented "adjusting state during render" pattern. It does not fire on the first render; seed the state with `useState`. The comparison is `Object.is`, so pass a **referentially stable** value — a primitive key (id/name/URI) or a memoized one, never a fresh object literal.
5555
- Effects remain correct for real external-system synchronization (DOM measurement, rAF, subscriptions, timers).
5656

5757
### Theme files vs. element components

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -379,7 +379,7 @@ Nothing **enforces** the boundary: no path alias keys off it, and the coverage `
379379
```
380380
- State and effects
381381
- **NEVER reset or re-sync local state from a prop inside a `useEffect`.** `useEffect(() => setX(prop), [prop])` renders once with the stale value, paints it, and only then corrects itself — the user sees the wrong frame and React renders twice. It is an error under `react-hooks/set-state-in-effect`, which the web client's `eslint-plugin-react-hooks` recommended set enforces.
382-
- Use **`useValueChange(value, onChange)`** (`clients/web/src/hooks/useValueChange.ts`) instead. It is React's documented ["adjusting state during render"](https://react.dev/reference/react/useState#storing-information-from-previous-renders) pattern: it compares `value` against the previous render's with `Object.is` and calls `onChange(next)` during render, so React discards the in-progress output and re-runs the component before anything reaches the DOM. It does **not** fire on the first render — seed the dependent state with `useState` instead.
382+
- Use **`useValueChange(value, onChange)`** (`clients/web/src/hooks/useValueChange.ts`) instead. It is React's documented ["adjusting state during render"](https://react.dev/reference/react/useState#storing-information-from-previous-renders) pattern: it compares `value` against the previous render's with `Object.is` and calls `onChange(next)` during render, so React discards the in-progress output and re-runs the component before anything reaches the DOM. It does **not** fire on the first render — seed the dependent state with `useState` instead. Because the comparison is `Object.is`, the value you pass **must be referentially stable** across renders that mean "no change": prefer a primitive key derived from the data (an id, a name, a URI), and otherwise a memoized value. A fresh object/array literal would compare unequal every render and loop.
383383
- An effect is still the right tool for genuine synchronization with an external system (DOM measurement, `requestAnimationFrame`, subscriptions, timers). The rule is about deriving React state from React props, not about effects in general.
384384
- Theme files vs. Storybook element components
385385
- **Theme files** (`src/theme/<Component>.ts`) and **element components** (`src/components/elements/`) serve different purposes and both are needed.

‎clients/web/src/hooks/useValueChange.ts‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,16 @@ import { useState } from "react";
1515
* user sees one frame of the old state and React has to render twice. Adjusting
1616
* during render lets React discard the in-progress output and re-run the
1717
* component body before anything reaches the DOM.
18+
*
19+
* ⚠️ **`value` must be referentially stable across renders that mean "no
20+
* change".** The comparison is `Object.is`, so an object or array literal built
21+
* fresh in the component body looks different on every render — `onChange`
22+
* would fire every render, and because it is what updates state, that is an
23+
* infinite render loop rather than a merely wasteful one. Pass a **primitive
24+
* key** derived from the data (an id, a name, a URI) wherever one exists, and
25+
* otherwise a value that is already memoized or owned by the parent. This is
26+
* the same stability requirement a `useEffect` dependency array carries; the
27+
* difference is only that here the failure is loud and immediate.
1828
*/
1929
export function useValueChange<T>(value: T, onChange: (next: T) => void): void {
2030
const [previous, setPrevious] = useState(value);

0 commit comments

Comments
 (0)