@fringeworks/react-utils 0.9.2 → 0.11.0

package/README.ja.md

@@ -31,15 +31,23 @@ import useLatestRef from '@fringeworks/react-utils/hooks/useLatestRef';
 
 ### hook
 
-| hook                                | 説明                                                                   |
-| ----------------------------------- | ---------------------------------------------------------------------- |
-| `useCombinedRefs(...refs)`          | 複数の ref にまとめて値を渡す callback ref を返す                      |
-| `useConstant(factory)`              | 初回のレンダリングで作った値を、アンマウントされるまで返し続ける       |
-| `useExecutionAt(options?)`          | Execution Request プロパティに渡す値と、実行のきっかけになる関数を返す |
-| `useIsMounted()`                    | マウントされているかどうかを判定する関数を返す                         |
-| `useLatestRef(value)`               | 最新の値を保持する参照を返す                                           |
-| `usePreviousValue(value, options?)` | 前回の値を返す                                                         |
-| `useStableLength(arr)`              | 配列の要素数がレンダリングをまたいで変わらないことを確認する           |
+| hook                                            | 説明                                                                     |
+| ----------------------------------------------- | ------------------------------------------------------------------------ |
+| `useChangeEffect(dependencies, callback)`       | `xxxOn` のプロパティで受け取った依存の値が変わったときに、処理を実行する |
+| `useChangeLayoutEffect(dependencies, callback)` | `useChangeEffect` の、画面に表示する前に実行する版                       |
+| `useCombinedRefs(...refs)`                      | 複数の ref にまとめて値を渡す callback ref を返す                        |
+| `useConstant(factory)`                          | 初回のレンダリングで作った値を、アンマウントされるまで返し続ける         |
+| `useExecutionAt(options?)`                      | Execution Request プロパティに渡す値と、実行のきっかけになる関数を返す   |
+| `useExecutionEffect(request, callback)`         | Execution Request プロパティで要求されたときに、処理を実行する           |
+| `useExecutionLayoutEffect(request, callback)`   | `useExecutionEffect` の、画面に表示する前に実行する版                    |
+| `useExecutionMark()`                            | payload の無い Execution Request と、要求する関数を返す                  |
+| `useIsHydrated()`                               | ハイドレーションが終わっているかを返す                                   |
+| `useIsMounted()`                                | マウントされているかどうかを判定する関数を返す                           |
+| `useLatestRef(value)`                           | 最新の値を保持する参照を返す                                             |
+| `usePreviousValue(value, options?)`             | 前回の値を返す                                                           |
+| `useRerender()`                                 | 再レンダリングだけを起こす関数を返す                                     |
+| `useStableCallback(callback)`                   | 参照が変わらず、最新のコールバックを呼ぶ関数を返す                       |
+| `useStableLength(arr)`                          | 配列の要素数がレンダリングをまたいで変わらないことを確認する             |
 
 ### 関数
 
@@ -56,6 +64,59 @@ import useLatestRef from '@fringeworks/react-utils/hooks/useLatestRef';
 | `transformContent(children, callback)`                | Fragment を透過し、エレメント・文字列・数値を変換した配列を返す    |
 | `transformElement(children, callback)`                | Fragment を透過し、エレメントを変換した配列を返す                  |
 
+### `useChangeEffect`
+
+```ts
+useChangeEffect(
+  dependencies: ChangeDependencies | undefined,
+  callback: () => void,
+): void
+```
+
+`xxxOn` のプロパティ（例: `refreshOn`）を受け取る側の hook です。受け取った依存の値（Change Dependencies）が変わったときに、`callback` を実行します。処理は画面に表示した後（`useEffect`）に実行します。
+
+測り直しや再計算など、結果が入力だけで決まる操作を、利用者が渡した値の変化に合わせて実行するために使います。回数や payload に意味がある命令は、Execution Request（`useExecutionAt`・`useExecutionEffect`）を使います。
+
+- 1段目のプロパティを `Object.is` で比べ、どれかが変わったときに実行します。プロパティが増えた・減った場合も変化とみなします。
+- 比べるのは1段目だけです。プロパティの値がオブジェクトの場合は参照で比べるため、その場で作ったオブジェクト（`{ style }` など）を入れると、毎回変化とみなします。
+- 依存の値そのものは、その場で書いたオブジェクトを渡してかまいません。
+- 初回（マウントしたとき）は実行しません。
+- `dependencies` が `undefined` の場合は、プロパティの無いオブジェクトとして扱います。省略できるプロパティをそのまま渡せます。
+- `callback` は最新のものを呼びます。`callback` の参照が変わっても実行しません。
+- Execution Request（`useExecutionAt` の値）をプロパティに入れると、要求のたびに実行します。
+
+```tsx
+// 渡す側
+<WrappedComponent refreshOn={{ className, theme }} />;
+
+// 受け取る側
+type Props = { refreshOn?: ChangeDependencies };
+
+function WrappedComponent({ refreshOn }: Props) {
+  const instance = useConstant(() => createInstance());
+  useChangeEffect(refreshOn, () => {
+    instance.refresh();
+  });
+  // ...
+}
+```
+
+| 引数           | 型                                | 説明                                 |
+| -------------- | --------------------------------- | ------------------------------------ |
+| `dependencies` | `ChangeDependencies \| undefined` | 受け取った依存の値                   |
+| `callback`     | `() => void`                      | 依存の値が変わったときに実行する処理 |
+
+### `useChangeLayoutEffect`
+
+```ts
+useChangeLayoutEffect(
+  dependencies: ChangeDependencies | undefined,
+  callback: () => void,
+): void
+```
+
+`useChangeEffect` の、処理を画面に表示する前（`useLayoutEffect`）に実行する版です。測り直しなど、結果を画面に表示する前に反映したい処理に使います。依存の値の扱いと引数は `useChangeEffect` と同じです。
+
 ### `useCombinedRefs`
 
 ```ts
@@ -96,7 +157,7 @@ useExecutionAt<P = void>(
 
 命令的な API を持つ部品をラップしたコンポーネントで、プロパティを通じてそのメソッドを実行するための hook です。Execution Request プロパティ（`undoAt` のように `At` で終わるプロパティ）に渡す値と、実行のきっかけになる関数を返します。
 
-- `request.at` は初期状態では `0` で、`execute` を呼ぶたびに増加します。受け取る側は `at` が変わったら処理を実行します。
+- `request.at` は初期状態では `0` で、`execute` を呼ぶたびに増加します。受け取る側は `useExecutionEffect` / `useExecutionLayoutEffect` で処理を実行します。payload が要らない場合は `useExecutionMark` を使います。
 - `execute` の参照は常に同じです。
 
 ```tsx
@@ -110,6 +171,90 @@ const [undoAt, undo] = useExecutionAt<string>();
 | ----------------- | --- | --------------------------------- |
 | `initialPayload?` | `P` | 初期状態の `request.payload` の値 |
 
+### `useExecutionEffect`
+
+```ts
+useExecutionEffect<P = void>(
+  request: ExecutionRequest<P> | ExecutionMark | undefined,
+  callback: (payload: P | undefined) => void,
+): void
+```
+
+`useExecutionAt`・`useExecutionMark` と対になる、受け取る側の hook です。Execution Request プロパティで要求されたときに、要求の `payload` を渡して `callback` を実行します。処理は画面に表示した後（`useEffect`）に実行します。
+
+- 印（`request.at`、または `ExecutionMark` の値）が変わったときだけ実行します。`payload` は比べません。
+- マウントしたときに渡されていた要求は実行しません（マウントしたときの印を基準にします）。
+- 印が `0`（まだ要求していない）の場合は実行しません。
+- `ExecutionMark` を受け取った場合、`callback` の `payload` は `undefined` です。印は `markAt()` で作ったものでなくてもかまいません（要求のたびに異なる値であればよい）。
+- 次のレンダリングまでに複数回要求した場合は、最後の要求だけを実行します。
+- `callback` は最新のものを呼びます。`callback` の参照が変わっても実行しません。
+- `request` が `undefined` の場合は、要求なしとして扱います。省略できるプロパティをそのまま渡せます。
+
+```tsx
+type Props = { undoAt?: ExecutionRequest<string> };
+
+function WrappedImperativeComponent({ undoAt }: Props) {
+  const instance = useConstant(() => createImperativeComponent());
+  useExecutionEffect(undoAt, (payload) => {
+    instance.undo(payload);
+  });
+  // ...
+}
+```
+
+| 引数       | 型                                  | 説明                                        |
+| ---------- | ----------------------------------- | ------------------------------------------- |
+| `request`  | `ExecutionRequest<P> \| undefined`  | 受け取った Execution Request プロパティの値 |
+| `callback` | `(payload: P \| undefined) => void` | 要求されたときに実行する処理                |
+
+### `useExecutionLayoutEffect`
+
+```ts
+useExecutionLayoutEffect<P = void>(
+  request: ExecutionRequest<P> | ExecutionMark | undefined,
+  callback: (payload: P | undefined) => void,
+): void
+```
+
+`useExecutionEffect` の、処理を画面に表示する前（`useLayoutEffect`）に実行する版です。スクロールの位置を合わせる、計測し直すなど、結果を画面に表示する前に反映したい処理に使います。要求の扱いと引数は `useExecutionEffect` と同じです。
+
+### `useExecutionMark`
+
+```ts
+useExecutionMark(): UseExecutionMarkResult
+```
+
+`useExecutionAt` の payload を持たない版です。payload の無い Execution Request（`ExecutionMark`。実体は数値）と、要求する関数を返します。命令的な部品の `focus()`・`reset()` のような、引数の要らないメソッドをプロパティから実行する場合に使います。
+
+- 値は初期状態では `0`（まだ要求していない）で、`execute` を呼ぶたびに `markAt()` で作った新しい値になります。
+- `execute` の参照は常に同じです。
+- この hook を使わずに、`ExecutionMark` を自分で作ってもかまいません（ストアや設定に置いた値など）。その場合は、**要求のたびに前回と異なる値にしてください**。同じ値を続けて渡すと、2回目は要求とみなしません。`markAt()` を使うと、呼ぶたびに異なる値になります。
+
+```tsx
+const [focusAt, focus] = useExecutionMark();
+
+<button onClick={focus}>Focus</button>
+<WrappedImperativeComponent focusAt={focusAt} />
+```
+
+### `useIsHydrated`
+
+```ts
+useIsHydrated(): boolean
+```
+
+ハイドレーションが終わっているかを返します。クライアントにしか無い値（`window`・`localStorage`・画面の幅など）を、ハイドレーションの不一致を起こさずに描画するために使います。
+
+- サーバーの描画とハイドレーション中は `false`、その後は `true` を返します。
+- ハイドレーションの後にマウントしたコンポーネントや、クライアントだけで描画した場合は、最初から `true` を返します。
+- `typeof window` による判定と違い、クライアントでもハイドレーション中は `false` になります。そのため、サーバーの HTML と食い違いません。
+
+```tsx
+const isHydrated = useIsHydrated();
+
+<p>{isHydrated ? navigator.userAgent : ''}</p>;
+```
+
 ### `useIsMounted`
 
 ```ts
@@ -151,6 +296,38 @@ usePreviousValue<T = unknown>(
 | `initialValue?` | `T`                                     | 値が一度も変わっていない間に返す値                                     |
 | `isEqual?`      | `(oldValue: T, newValue: T) => boolean` | 同じ値とみなす場合に `true` を返す比較関数。未指定の場合は `Object.is` |
 
+### `useRerender`
+
+```ts
+useRerender(): () => void
+```
+
+再レンダリングだけを起こす関数を返します。値を持たずに描画し直したい場合（外部の状態を読み直して表示するときなど）に使います。
+
+- 返す関数の参照は常に同じです。
+
+### `useStableCallback`
+
+```ts
+useStableCallback<A extends unknown[], R>(
+  callback: (...args: A) => R,
+): (...args: A) => R
+```
+
+参照が変わらず、呼ぶと最新の `callback` を実行する関数を返します。子のコンポーネントに渡すイベントハンドラーの参照を変えずに、中身は常に最新にする場合に使います。
+
+- 返す関数の参照は常に同じです。
+- 最新の `callback` はコミット時に反映されます。レンダリング中には呼ばないでください（古い `callback` が呼ばれます）。イベントハンドラーやエフェクトの中から呼びます。
+- React 19.2 の `useEffectEvent` はエフェクトの中から呼ぶ専用ですが、この hook が返す関数は子のコンポーネントにも渡せます。
+
+```tsx
+const handleSelect = useStableCallback((id: string) => {
+  onSelect(id, filter);
+});
+
+<MemoizedList onSelect={handleSelect} />;
+```
+
 ### `useStableLength`
 
 ```ts
@@ -261,7 +438,7 @@ HOC の `displayName` などに使う、コンポーネントの名前を返し
 markAt(): MarkAtResult
 ```
 
-呼び出すたびに増加する値を返します。値は `1` から始まり、重複しません。`useExecutionAt` で `request.at` に使っています。
+呼び出すたびに増加する値を返します。値は `1` から始まり、重複しません。`useExecutionAt` の `request.at` と、`useExecutionMark` の値に使っています。
 
 ### `setRefCurrent`
 
@@ -304,15 +481,18 @@ const items = transformElement(children, (element, index) => (
 | 型                           | 説明                                                                             |
 | ---------------------------- | -------------------------------------------------------------------------------- |
 | `AppliedProps<P, Ds>`        | `applyDefaultProps` の戻り値の型                                                 |
+| `ChangeDependencies`         | `xxxOn` のプロパティに渡す依存の値（1段目のプロパティを `Object.is` で比べる）   |
 | `CSSPropertiesWithVars`      | CSS 変数（`--name`）を書ける `CSSProperties`                                     |
 | `ExecutionFunction<P>`       | `useExecutionAt` が返す、実行のきっかけになる関数                                |
 | `ExecutionRequest<P>`        | `useExecutionAt` が返す、Execution Request プロパティに渡す値（`at`・`payload`） |
 | `ExtendableProps`            | `extendElement` に渡せるエレメントの props（`className`・`style`）               |
 | `LatestRef<T>`               | `useLatestRef` が返す参照                                                        |
+| `ExecutionMark`              | payload の無い Execution Request（実体は数値。要求のたびに異なる値にする）       |
 | `MarkAtResult`               | `markAt` の戻り値の型                                                            |
 | `SkippedDefaults`            | `applyDefaultProps` でスキップされる値（`null`・`undefined`・`false`）           |
 | `UseExecutionAtOptions<P>`   | `useExecutionAt` のオプション                                                    |
 | `UseExecutionAtResult<P>`    | `useExecutionAt` の戻り値の型                                                    |
+| `UseExecutionMarkResult`     | `useExecutionMark` の戻り値の型                                                  |
 | `UsePreviousValueOptions<T>` | `usePreviousValue` のオプション                                                  |
 
 ## ライセンス

package/README.md

@@ -31,15 +31,23 @@ import useLatestRef from '@fringeworks/react-utils/hooks/useLatestRef';
 
 ### Hooks
 
-| Hook                                | Description                                                                   |
-| ----------------------------------- | ----------------------------------------------------------------------------- |
-| `useCombinedRefs(...refs)`          | Returns a callback ref that passes the value to all the given refs            |
-| `useConstant(factory)`              | Keeps returning the value created on the first render until unmount           |
-| `useExecutionAt(options?)`          | Returns a value for an Execution Request prop and a function that triggers it |
-| `useIsMounted()`                    | Returns a function that tells whether the component is mounted                |
-| `useLatestRef(value)`               | Returns a ref that holds the latest value                                     |
-| `usePreviousValue(value, options?)` | Returns the previous value                                                    |
-| `useStableLength(arr)`              | Ensures that the length of an array does not change across renders            |
+| Hook                                            | Description                                                                          |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `useChangeEffect(dependencies, callback)`       | Runs an operation when the dependency values received through an `xxxOn` prop change |
+| `useChangeLayoutEffect(dependencies, callback)` | A version of `useChangeEffect` that runs before the browser paints                   |
+| `useCombinedRefs(...refs)`                      | Returns a callback ref that passes the value to all the given refs                   |
+| `useConstant(factory)`                          | Keeps returning the value created on the first render until unmount                  |
+| `useExecutionAt(options?)`                      | Returns a value for an Execution Request prop and a function that triggers it        |
+| `useExecutionEffect(request, callback)`         | Runs an operation when it is requested through an Execution Request prop             |
+| `useExecutionLayoutEffect(request, callback)`   | A version of `useExecutionEffect` that runs before the browser paints                |
+| `useExecutionMark()`                            | Returns an Execution Request without a payload and a function that makes a request   |
+| `useIsHydrated()`                               | Returns whether hydration has finished                                               |
+| `useIsMounted()`                                | Returns a function that tells whether the component is mounted                       |
+| `useLatestRef(value)`                           | Returns a ref that holds the latest value                                            |
+| `usePreviousValue(value, options?)`             | Returns the previous value                                                           |
+| `useRerender()`                                 | Returns a function that only triggers a re-render                                    |
+| `useStableCallback(callback)`                   | Returns a function with a stable reference that calls the latest callback            |
+| `useStableLength(arr)`                          | Ensures that the length of an array does not change across renders                   |
 
 ### Functions
 
@@ -56,6 +64,59 @@ import useLatestRef from '@fringeworks/react-utils/hooks/useLatestRef';
 | `transformContent(children, callback)`                | Maps elements, strings, and numbers to an array, looking through Fragments |
 | `transformElement(children, callback)`                | Maps elements to an array, looking through Fragments                       |
 
+### `useChangeEffect`
+
+```ts
+useChangeEffect(
+  dependencies: ChangeDependencies | undefined,
+  callback: () => void,
+): void
+```
+
+The receiving hook for `xxxOn` props (such as `refreshOn`). It runs `callback` when the received dependency values (Change Dependencies) change. The operation runs after the browser paints (`useEffect`).
+
+Use it to run operations whose result depends only on their inputs, such as measuring or recalculating again, when the values passed by the user change. For commands where the count or the payload matters, use Execution Requests (`useExecutionAt`, `useExecutionEffect`).
+
+- It compares the first-level properties with `Object.is` and runs when any of them changes. Added or removed properties also count as a change.
+- Only the first level is compared. Object values are compared by reference, so putting an object created during rendering (such as `{ style }`) counts as a change every time.
+- The dependency object itself may be written inline.
+- It does not run on the first commit (mount).
+- An `undefined` `dependencies` is treated as an object with no properties, so an optional prop can be passed as is.
+- The latest `callback` is called. Changing the reference of `callback` does not run it.
+- Putting an Execution Request (the value of `useExecutionAt`) in a property runs the operation on every request.
+
+```tsx
+// Passing side
+<WrappedComponent refreshOn={{ className, theme }} />;
+
+// Receiving side
+type Props = { refreshOn?: ChangeDependencies };
+
+function WrappedComponent({ refreshOn }: Props) {
+  const instance = useConstant(() => createInstance());
+  useChangeEffect(refreshOn, () => {
+    instance.refresh();
+  });
+  // ...
+}
+```
+
+| Parameter      | Type                              | Description                                            |
+| -------------- | --------------------------------- | ------------------------------------------------------ |
+| `dependencies` | `ChangeDependencies \| undefined` | The received dependency values                         |
+| `callback`     | `() => void`                      | The operation to run when the dependency values change |
+
+### `useChangeLayoutEffect`
+
+```ts
+useChangeLayoutEffect(
+  dependencies: ChangeDependencies | undefined,
+  callback: () => void,
+): void
+```
+
+A version of `useChangeEffect` that runs the operation before the browser paints (`useLayoutEffect`). Use it for operations whose result should be reflected before painting, such as measuring again. Dependency values and parameters are handled the same way as `useChangeEffect`.
+
 ### `useCombinedRefs`
 
 ```ts
@@ -96,7 +157,7 @@ useExecutionAt<P = void>(
 
 A hook for components that wrap a part with an imperative API, letting you call its methods through props. It returns a value to pass to an Execution Request prop (a prop ending with `At`, such as `undoAt`) and a function that triggers it.
 
-- `request.at` is `0` initially and increases every time `execute` is called. The receiving side runs the operation when `at` changes.
+- `request.at` is `0` initially and increases every time `execute` is called. The receiving side runs the operation with `useExecutionEffect` / `useExecutionLayoutEffect`. Use `useExecutionMark` when no payload is needed.
 - `execute` always keeps the same reference.
 
 ```tsx
@@ -110,6 +171,90 @@ const [undoAt, undo] = useExecutionAt<string>();
 | ----------------- | ---- | -------------------------------------- |
 | `initialPayload?` | `P`  | The initial value of `request.payload` |
 
+### `useExecutionEffect`
+
+```ts
+useExecutionEffect<P = void>(
+  request: ExecutionRequest<P> | ExecutionMark | undefined,
+  callback: (payload: P | undefined) => void,
+): void
+```
+
+The receiving counterpart of `useExecutionAt` and `useExecutionMark`. When an operation is requested through an Execution Request prop, it runs `callback` with the request's `payload`. The operation runs after the browser paints (`useEffect`).
+
+- It runs only when the mark (`request.at`, or the value of an `ExecutionMark`) changes. `payload` is not compared.
+- A request that was already passed at mount is not run (the mark at mount is the baseline).
+- It does not run when the mark is `0` (not requested yet).
+- When it receives an `ExecutionMark`, the `payload` passed to `callback` is `undefined`. The mark does not have to be created by `markAt()` (any value that differs on every request works).
+- If multiple requests are made before the next render, only the last one is run.
+- The latest `callback` is called. Changing the reference of `callback` does not run it.
+- An `undefined` `request` is treated as no request, so an optional prop can be passed as is.
+
+```tsx
+type Props = { undoAt?: ExecutionRequest<string> };
+
+function WrappedImperativeComponent({ undoAt }: Props) {
+  const instance = useConstant(() => createImperativeComponent());
+  useExecutionEffect(undoAt, (payload) => {
+    instance.undo(payload);
+  });
+  // ...
+}
+```
+
+| Parameter  | Type                                | Description                                      |
+| ---------- | ----------------------------------- | ------------------------------------------------ |
+| `request`  | `ExecutionRequest<P> \| undefined`  | The value of the received Execution Request prop |
+| `callback` | `(payload: P \| undefined) => void` | The operation to run when requested              |
+
+### `useExecutionLayoutEffect`
+
+```ts
+useExecutionLayoutEffect<P = void>(
+  request: ExecutionRequest<P> | ExecutionMark | undefined,
+  callback: (payload: P | undefined) => void,
+): void
+```
+
+A version of `useExecutionEffect` that runs the operation before the browser paints (`useLayoutEffect`). Use it for operations whose result should be reflected before painting, such as adjusting the scroll position or measuring again. Requests and parameters are handled the same way as `useExecutionEffect`.
+
+### `useExecutionMark`
+
+```ts
+useExecutionMark(): UseExecutionMarkResult
+```
+
+A version of `useExecutionAt` without a payload. It returns an Execution Request without a payload (`ExecutionMark`, which is a number) and a function that makes a request. Use it to run methods that take no arguments, such as `focus()` or `reset()` of an imperative part, through props.
+
+- The value is `0` (not requested yet) initially, and becomes a new value created by `markAt()` every time `execute` is called.
+- `execute` always keeps the same reference.
+- You may create an `ExecutionMark` yourself without this hook (for example, a value in a store or configuration). In that case, **make it different from the previous value on every request**. Passing the same value again is not treated as a new request. `markAt()` returns a different value on every call.
+
+```tsx
+const [focusAt, focus] = useExecutionMark();
+
+<button onClick={focus}>Focus</button>
+<WrappedImperativeComponent focusAt={focusAt} />
+```
+
+### `useIsHydrated`
+
+```ts
+useIsHydrated(): boolean
+```
+
+Returns whether hydration has finished. Use it to render client-only values (`window`, `localStorage`, the viewport width, and so on) without causing a hydration mismatch.
+
+- Returns `false` during server rendering and hydration, and `true` afterwards.
+- Returns `true` from the start in components mounted after hydration and in client-only rendering.
+- Unlike checking `typeof window`, it returns `false` during hydration even on the client, so the output matches the server HTML.
+
+```tsx
+const isHydrated = useIsHydrated();
+
+<p>{isHydrated ? navigator.userAgent : ''}</p>;
+```
+
 ### `useIsMounted`
 
 ```ts
@@ -151,6 +296,38 @@ When the value changes, the previous value is updated by a state update during r
 | `initialValue?` | `T`                                     | The value returned until the value changes for the first time                         |
 | `isEqual?`      | `(oldValue: T, newValue: T) => boolean` | A comparison that returns `true` for values considered equal. Defaults to `Object.is` |
 
+### `useRerender`
+
+```ts
+useRerender(): () => void
+```
+
+Returns a function that only triggers a re-render. Use it when you want to render again without holding a value (for example, to show external state after reading it again).
+
+- The returned function always keeps the same reference.
+
+### `useStableCallback`
+
+```ts
+useStableCallback<A extends unknown[], R>(
+  callback: (...args: A) => R,
+): (...args: A) => R
+```
+
+Returns a function whose reference never changes and that calls the latest `callback`. Use it to keep the reference of an event handler passed to child components while always running the latest logic.
+
+- The returned function always keeps the same reference.
+- The latest `callback` is applied on commit. Do not call the function during rendering (the previous `callback` would be called). Call it from event handlers or effects.
+- React 19.2's `useEffectEvent` can only be called from effects, while the function returned by this hook can also be passed to child components.
+
+```tsx
+const handleSelect = useStableCallback((id: string) => {
+  onSelect(id, filter);
+});
+
+<MemoizedList onSelect={handleSelect} />;
+```
+
 ### `useStableLength`
 
 ```ts
@@ -261,7 +438,7 @@ Returns the name of a component, for use in an HOC's `displayName` and the like.
 markAt(): MarkAtResult
 ```
 
-Returns a value that increases on every call. Values start from `1` and are never duplicated. `useExecutionAt` uses it for `request.at`.
+Returns a value that increases on every call. Values start from `1` and are never duplicated. `useExecutionAt` uses it for `request.at`, and `useExecutionMark` uses it for its value.
 
 ### `setRefCurrent`
 
@@ -301,19 +478,22 @@ const items = transformElement(children, (element, index) => (
 
 ### Types
 
-| Type                         | Description                                                                            |
-| ---------------------------- | -------------------------------------------------------------------------------------- |
-| `AppliedProps<P, Ds>`        | The return type of `applyDefaultProps`                                                 |
-| `CSSPropertiesWithVars`      | `CSSProperties` that also accepts CSS variables (`--name`)                             |
-| `ExecutionFunction<P>`       | The trigger function returned by `useExecutionAt`                                      |
-| `ExecutionRequest<P>`        | The value for an Execution Request prop returned by `useExecutionAt` (`at`, `payload`) |
-| `ExtendableProps`            | The props of an element that `extendElement` accepts (`className`, `style`)            |
-| `LatestRef<T>`               | The ref returned by `useLatestRef`                                                     |
-| `MarkAtResult`               | The return type of `markAt`                                                            |
-| `SkippedDefaults`            | Values skipped by `applyDefaultProps` (`null`, `undefined`, `false`)                   |
-| `UseExecutionAtOptions<P>`   | The options of `useExecutionAt`                                                        |
-| `UseExecutionAtResult<P>`    | The return type of `useExecutionAt`                                                    |
-| `UsePreviousValueOptions<T>` | The options of `usePreviousValue`                                                      |
+| Type                         | Description                                                                                            |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `AppliedProps<P, Ds>`        | The return type of `applyDefaultProps`                                                                 |
+| `ChangeDependencies`         | The dependency values passed to an `xxxOn` prop (first-level properties are compared with `Object.is`) |
+| `CSSPropertiesWithVars`      | `CSSProperties` that also accepts CSS variables (`--name`)                                             |
+| `ExecutionFunction<P>`       | The trigger function returned by `useExecutionAt`                                                      |
+| `ExecutionRequest<P>`        | The value for an Execution Request prop returned by `useExecutionAt` (`at`, `payload`)                 |
+| `ExtendableProps`            | The props of an element that `extendElement` accepts (`className`, `style`)                            |
+| `LatestRef<T>`               | The ref returned by `useLatestRef`                                                                     |
+| `ExecutionMark`              | An Execution Request without a payload (a number; make it different on every request)                  |
+| `MarkAtResult`               | The return type of `markAt`                                                                            |
+| `SkippedDefaults`            | Values skipped by `applyDefaultProps` (`null`, `undefined`, `false`)                                   |
+| `UseExecutionAtOptions<P>`   | The options of `useExecutionAt`                                                                        |
+| `UseExecutionAtResult<P>`    | The return type of `useExecutionAt`                                                                    |
+| `UseExecutionMarkResult`     | The return type of `useExecutionMark`                                                                  |
+| `UsePreviousValueOptions<T>` | The options of `usePreviousValue`                                                                      |
 
 ## License
 

package/{_helpers → _internal}/_traverseChildren.cjs

@@ -1,7 +1,7 @@
 Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: 'Module' } });
 let react = require("react");
 
-//#region src/_helpers/_traverseChildren.ts
+//#region src/_internal/_traverseChildren.ts
 /**
 * ReactElement、string、numberのいずれかであるかを判定する
 * @param child 子要素

package/{_helpers → _internal}/_traverseChildren.d.cts

@@ -1,5 +1,5 @@
 import { ReactElement, ReactNode } from "react";
-//#region src/_helpers/_traverseChildren.d.ts
+//#region src/_internal/_traverseChildren.d.ts
 type IndexCursor = {
   current: number;
 };

package/{_helpers → _internal}/_traverseChildren.d.mts

@@ -1,5 +1,5 @@
 import { ReactElement, ReactNode } from "react";
-//#region src/_helpers/_traverseChildren.d.ts
+//#region src/_internal/_traverseChildren.d.ts
 type IndexCursor = {
   current: number;
 };

package/{_helpers → _internal}/_traverseChildren.mjs

@@ -1,6 +1,6 @@
 import { Children, Fragment, isValidElement } from "react";
 
-//#region src/_helpers/_traverseChildren.ts
+//#region src/_internal/_traverseChildren.ts
 /**
 * ReactElement、string、numberのいずれかであるかを判定する
 * @param child 子要素

package/_internal/_useChangeHandler.cjs

@@ -0,0 +1,48 @@
+Object.defineProperties(exports, { __esModule: { value: true }, [Symbol.toStringTag]: { value: 'Module' } });
+const require_hooks_useLatestRef_useLatestRef = require("../hooks/useLatestRef/useLatestRef.cjs");
+require("../hooks/useLatestRef/index.cjs");
+let react = require("react");
+
+//#region src/_internal/_useChangeHandler.ts
+/**
+* 依存の値が変わったか（1段目のプロパティを `Object.is` で比べる）
+*
+* undefined はプロパティの無いオブジェクトとして扱う
+*/
+const isChanged = (prev, next) => {
+	if (prev === next) return false;
+	const a = prev ?? {};
+	const b = next ?? {};
+	const keys = Object.keys(a);
+	if (keys.length !== Object.keys(b).length) return true;
+	return keys.some((key) => !Object.prototype.hasOwnProperty.call(b, key) || !Object.is(a[key], b[key]));
+};
+/**
+* 依存の値（Change Dependencies）を受け取り、変わっていれば処理を実行する関数を返すフック
+*
+* `useChangeEffect`・`useChangeLayoutEffect` に共通の処理。返す関数を、毎回のコミットでエフェクトから呼ぶ。
+*
+* - 前回の処理の後にコミットした依存の値と比べる。初回のコミットの値が最初の基準になるため、初回は実行しない
+* - 比べるのはエフェクトの中（コミットした値どうし）。破棄されたレンダリングの値とは比べない
+* - 同じ値のままエフェクトが再実行されても（StrictMode など）実行しない
+* - コールバックは最新のものを呼ぶ
+*
+* @param dependencies 依存の値。undefined の場合は依存なし
+* @param callback 依存の値が変わったときに実行する処理
+* @returns エフェクトで呼ぶ関数。参照は常に同じ
+*/
+function useChangeHandler(dependencies, callback) {
+	const dependenciesRef = require_hooks_useLatestRef_useLatestRef.default(dependencies);
+	const callbackRef = require_hooks_useLatestRef_useLatestRef.default(callback);
+	const committedRef = (0, react.useRef)(dependencies);
+	return (0, react.useCallback)(() => {
+		const next = dependenciesRef.current;
+		if (isChanged(committedRef.current, next)) {
+			committedRef.current = next;
+			callbackRef.current();
+		}
+	}, [dependenciesRef, callbackRef]);
+}
+
+//#endregion
+exports.default = useChangeHandler;

package/_internal/_useChangeHandler.d.cts

@@ -0,0 +1,18 @@
+import { ChangeDependencies } from "../hooks/useChangeEffect/types.cjs";
+//#region src/_internal/_useChangeHandler.d.ts
+/**
+ * 依存の値（Change Dependencies）を受け取り、変わっていれば処理を実行する関数を返すフック
+ *
+ * `useChangeEffect`・`useChangeLayoutEffect` に共通の処理。返す関数を、毎回のコミットでエフェクトから呼ぶ。
+ *
+ * - 前回の処理の後にコミットした依存の値と比べる。初回のコミットの値が最初の基準になるため、初回は実行しない
+ * - 比べるのはエフェクトの中（コミットした値どうし）。破棄されたレンダリングの値とは比べない
+ * - 同じ値のままエフェクトが再実行されても（StrictMode など）実行しない
+ * - コールバックは最新のものを呼ぶ
+ *
+ * @param dependencies 依存の値。undefined の場合は依存なし
+ * @param callback 依存の値が変わったときに実行する処理
+ * @returns エフェクトで呼ぶ関数。参照は常に同じ
+ */
+declare function useChangeHandler(dependencies: ChangeDependencies | undefined, callback: () => void): () => void;
+export = useChangeHandler;