@aiquants/period-slider 0.18.0 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/CHANGELOG.md +209 -0
  2. package/README.md +26 -7
  3. package/dist/DateSelector.d.ts +9 -9
  4. package/dist/DateSelector.d.ts.map +1 -1
  5. package/dist/MonthSelector.d.ts +5 -4
  6. package/dist/MonthSelector.d.ts.map +1 -1
  7. package/dist/PeriodSlider.d.ts +23 -4
  8. package/dist/PeriodSlider.d.ts.map +1 -1
  9. package/dist/VirtualDateDropdown.d.ts +25 -10
  10. package/dist/VirtualDateDropdown.d.ts.map +1 -1
  11. package/dist/YearSelector.d.ts +7 -4
  12. package/dist/YearSelector.d.ts.map +1 -1
  13. package/dist/index.cjs +1 -1
  14. package/dist/index.js +2859 -2394
  15. package/dist/optionText.d.ts +1 -1
  16. package/dist/optionText.d.ts.map +1 -1
  17. package/dist/renderScope.d.ts +486 -0
  18. package/dist/renderScope.d.ts.map +1 -0
  19. package/dist/selectorMemo.d.ts +42 -22
  20. package/dist/selectorMemo.d.ts.map +1 -1
  21. package/dist/useCommittedRef.d.ts +64 -71
  22. package/dist/useCommittedRef.d.ts.map +1 -1
  23. package/dist/usePeriodSlider.d.ts +56 -12
  24. package/dist/usePeriodSlider.d.ts.map +1 -1
  25. package/dist/useUncontrolledSelection.d.ts +7 -7
  26. package/dist/useUncontrolledSelection.d.ts.map +1 -1
  27. package/package.json +1 -1
  28. package/src/DateSelector.tsx +45 -20
  29. package/src/MonthSelector.tsx +41 -19
  30. package/src/PeriodSlider.tsx +39 -14
  31. package/src/VirtualDateDropdown.tsx +163 -92
  32. package/src/YearSelector.tsx +26 -27
  33. package/src/optionText.ts +6 -4
  34. package/src/renderScope.ts +766 -0
  35. package/src/selectorMemo.ts +53 -25
  36. package/src/useCommittedRef.ts +51 -155
  37. package/src/usePeriodSlider.ts +316 -138
  38. package/src/useUncontrolledSelection.ts +8 -9
package/CHANGELOG.md CHANGED
@@ -4,6 +4,215 @@ All notable changes to `@aiquants/period-slider` are documented here.
4
4
  見出しは版番号です。次の公開に入る変更は、その版番号と作成日の見出し (`## 0.14.0 (2026-09-24)` の形) の下へ書きます。
5
5
  本書は 0.10.0 で起こしたため、0.7.0 以前の項はありません (0.8.0 と 0.9.0 は公開済みの差分から起こした要約です)。
6
6
 
7
+ ## 0.20.0 (2026-10-02)
8
+
9
+ 4 つのフック (`usePeriodSliderRange` / `usePeriodSliderPoint` / `useVernierSliderRange` / `useVernierSliderPoint`) は `duringRender(action)` を返すようにしました。
10
+ ホストが自分の描画の中で `action` の中に呼んだ返す関数はその描画の中だけで働き、ステートへの受け渡しは React の描画中の更新になり、写し・受け渡しの記録・利用側が知っている値への書き込みと通知はその描画の確定で行い、React が捨てた描画は何も残しません (下の「追加」)。
11
+ `duringRender` の外の呼び出しは、描画中でも 0.19.0 と同じく、その場で働く事象の時点の呼び出しです (描画中の直接の呼び出しは対応外です。下の「変更」)。
12
+ ノギスのフックの操作は、動かさないスケールの値が返す関数の読む値とも利用側が知っている値とも等しい間、そのスケールをステートへ渡さず通知もしないようにしました (下の「変更」)。
13
+ 4 つのフックは、ステートへ最後に渡した値の記録を、その受け渡しを持たない描画 (移行の中の受け渡しを飛ばして確定した緊急の描画など) を挟んでも保つようにしました (下の「変更」)。
14
+ 3 セレクタのメモ比較器の費用を計測し (下の「文書」)、比較器 1 回がキーを求める回数と、比較器が候補の一覧の要素を読まないこと、キーを呼び出しをまたいで保持しないことをテストで押さえました。
15
+ あわせて、`DateSelector variant="dropdown"` は所有側 (隠れた `<Activity>`、フォールバックを出した `Suspense`) が隠すとポップアップを閉じ、
16
+ 隠れている間はポップアップを画面に出さず、隠れた操作要素へ届いた入力を無視するようにしました (Props と公開 API は変わりません)。
17
+ **描画中に返す関数を呼ぶホスト (その呼び出しを `duringRender` で包みます)、ノギスのフックの操作の前後でホストの描画や `Profiler` の確定を数えるテスト、
18
+ 移行の中の受け渡しを飛ばした描画の後の同じ値の確定経路の前後で `Profiler` の確定を数えるテスト、開いた `DateSelector variant="dropdown"` を `Activity` や `Suspense` で隠して表示し直すホストとテストでは、下の「変更」の点で挙動が変わります。**
19
+
20
+ ### 追加
21
+
22
+ - **4 つのフックは `duringRender: (action: () => void) => void` を返します**。ホストが自分の描画の中で、フックを呼んだ後に `duringRender(action)` を呼ぶと、
23
+ `action` の中で同期に呼んだこのフックの返す関数 (設定関数・シフト・リセット・セレクタと `sliderProps` のコールバック・◀▶) は、その描画の中だけで働きます。
24
+ 読む値は最後に確定した描画の値 (その後に事象の時点で書いた値と、同じ描画で先に呼んだ返す関数が渡した値があればその値) で、境界とコールバックも確定した描画のものです。
25
+ ステートへの受け渡しは React の描画中の更新になり、写し・受け渡しの記録・利用側が知っている値への書き込みと通知はその描画の範囲へ入り、その描画の確定が当てます。
26
+ 範囲を続けるのは、`duringRender` を呼んだ描画の続き (描画中の更新の後の走らせ直し、`StrictMode` の 2 度目の呼び出し、中断した描画のデータが解決した後の再実行) だけです。
27
+ React が捨てた描画の範囲は、同じステートを持つ後の別の描画が確定しても当たらず、後の描画の `action` の書き込みと通知を消しもしません。これを見分けるため、
28
+ 描画の中で最初に呼んだ `duringRender` はその描画に印を描画中の更新として付けます (`action` が何も渡さない描画でも、ホストの本体が同じ描画の中でもう 1 度走ります。子の描画と確定は増えません)。
29
+ `action` の中でステートを変える値を渡した描画の確定は、その受け渡しを、ホストのレイアウト副作用からステートの更新の列へ同一性で守った更新関数として記録します。
30
+ その描画が飛ばした優先度の低い受け渡し (移行の中で渡した値) を React が後で当て直しても、保存される値は通知した値に行き着きます。記録の分、子の描画を省くホストの描画が 1 度走ります。
31
+ 通知はその描画のコールバックを呼び、ホストのレイアウト副作用で届きます (その確定で先に走る子孫のレイアウト副作用がフックへ書くか通知するときはその前、
32
+ 隠れた `<Activity>` の中の確定ではマイクロタスク)。入れ子のホストでは子から親の順に、1 つのホストの複数のフックではフックを呼んだ順に届きます。
33
+ サーバー描画では確定が無いため、`action` の中の呼び出しはコールバックを呼びません。ほかのコンポーネントのステートを書くコールバックでも、
34
+ React の「Cannot update a component while rendering a different component」警告は出ません。
35
+ その描画がフックを呼んだ後に事象の時点の呼び出しが書いたステートと、描画が持たない事象の時点の受け渡し (移行が譲っている間にホストの描画より前に渡した値、
36
+ その描画が飛ばす優先度の移行の中で渡した値) を待つステートには、その描画の分を当てません (ノギスのフックではスケールごと。React は事象の更新を後で当て、そちらが勝ちます)。
37
+ `action` の中の受け渡しがまだ確定し得る間は、表示中の値へ落ち着く事象の時点の呼び出しも同じ値をステートへ渡し直し、後の操作として勝ちます。
38
+ 渡し直しは子の描画を省くホストの描画を 1 度走らせます (React が捨てた描画の `action` が値を渡した後も、ホストが次に描かれるまでは、最初のそうした呼び出しで同じく 1 度走ることがあります)。
39
+ フックの描画の範囲が閉じた後 (フックの最後の描画が確定した後と、本体を走らせた同期の処理が終わった後。副作用・イベントハンドラ・フックを呼んだ後に積んだマイクロタスクの中) に `duringRender` を呼ぶと
40
+ `Error` (`<フック名>: duringRender(action) must be called during the host's render, after the hook call (call the returned functions directly from event handlers and effects)`)、
41
+ `action` が関数でなければ `TypeError` (`<フック名>: duringRender(action) must be a function (received: ...)`) です。`action` の中でほかのフックのインスタンスの返す関数を呼ぶと、
42
+ そのインスタンスは何もせずに `Error` (`<フック名>: a returned function was called during another hook's duringRender(action); call it inside this hook's own duringRender(action)`) を送出します
43
+ (そのインスタンス自身の `duringRender` を入れ子に呼べば働きます)。`action` が送出した例外はそのまま伝わります。`duringRender` の同一性はコンポーネントの存続中ずっと変わりません。
44
+ ほかのコンポーネントの描画の中、フックを呼ぶ前、確定しなかった描画と同じ同期の処理の中の事象のコード、描画のコードがフックを呼ぶ前に積んだマイクロタスク
45
+ (先に描いたコンポーネントが積んだものを含む) での `duringRender` は検出せず (送出されないことがあります)、対応外です。
46
+ React が捨てた描画 (Suspense が保留した移行、取り消した移行、追い越された移行、割り込まれた描画) の中の呼び出しは何も残しません。日単位の `usePeriodSliderPoint`
47
+ (2024-01-01〜2024-01-31、初期値 2024-01-10) が、`duringRender` の中の `setValue` で 2024-01-20 へ追従する移行を Suspense が保留している間の例です。
48
+ - `shiftValue(1)` は確定した 2024-01-10 から進み、2024-01-11 を描いて通知します。3 回続けると 2024-01-11・2024-01-12・2024-01-13 をそれぞれ 1 度通知します。
49
+ - `setValue(2024-01-25)` の後の `shiftValue(1)` は 2024-01-26 を描きます。
50
+ - 2024-01-20 を渡す `selectorProps.onChange` は、親を描き直した後でも 2024-01-20 を描いて 1 度通知します。
51
+ - 月単位の `usePeriodSliderRange` (初期 2024-02〜2024-10) が `setRange` で 2024-04〜2024-10 へ追従する移行では、`shiftRange(1)` が 2024-03〜2024-11 を描きます。
52
+ ノギスのフックの `shiftMicroValue` / `shiftMicroRange` / `shiftMacroRange` も確定した値から進みます。
53
+ - `duringRender` の中の `selectorProps.onChange` で 2024-01-20 へ追従する移行は、Suspense が保留している間は通知せず、データの解決で確定したときに 2024-01-20 を 1 度だけ通知します。
54
+ 確定する前に取り消した移行は通知しません。
55
+ - 取り消した移行の後に 2024-01-20 を渡す `selectorProps.onChange` は `onChangePoint` を 1 度呼びます (捨てた描画の中でホストが渡しただけの値は、利用側が知っている値になりません)。
56
+ `setValue` は通知しません。
57
+
58
+ ### 変更
59
+
60
+ - **`DateSelector variant="dropdown"` は所有側が隠すとポップアップを閉じ、表示し直した操作要素は閉じています**。
61
+ 0.19.0 は開いたまま隠して表示し直すと、同じ行を名指して開いたまま戻していました (0.19.0 の「修正」)。隠れた操作要素はフォーカスを保てず (ブラウザは次の描画更新で外す。HTML のフォーカスの修正の規則)、
62
+ React は表示し直してもフォーカスを戻さないため、開いたまま戻した一覧は、キーボードの届かないまま `aria-expanded="true"` を名乗っていました
63
+ (APG のコンボボックスは開いている間フォーカスを操作要素に保ちます。ネイティブの `<select>` も描かれなくなると一覧を閉じ、自分からは開き直しません)。
64
+ 表示し直した後は `aria-controls` も `aria-activedescendant` も無く、アクティブ行と先頭一致入力のバッファは捨てられ、次に開くと保持値の行 (集合の外なら最も近い行) から始まります。
65
+ 閉じる描画は、`Activity` では隠れた木の描画 (それより先に表示し直したときは表示し直す確定)、`Suspense` では表示し直す確定です。それまで隠れた操作要素は
66
+ `aria-expanded="true"` と `aria-controls` を持ち続けますが、指す listbox は DOM に在ります (画面には出ません。下の「修正」)。
67
+ jsdom の `Profiler` (境界の外に置いたもの) では、開いたポップアップを隠す確定が 2 回から 3 回に増え、表示し直す確定が 3 回から 2 回に減ります (`Activity` と `Suspense` で同じ)。
68
+ 押下と同じ事象の中でホストが隠す場合は、押下の確定が 2 回から 3 回に、表示し直す確定が 2 回から 1 回になり、表示後は開かずに閉じています。
69
+ 閉じたまま隠す場合と、開く・閉じる操作の確定の回数は変わりません。
70
+ 上の回数は `StrictMode` なしのものです。`StrictMode` の中では、開いたポップアップを隠す確定が 2 回から 3 回に増え、表示し直す確定は 2 回のまま変わりません。
71
+ 押下と同じ事象の中でホストが隠す場合は、押下の確定が `Activity` では 4 回から 5 回に、`Suspense` では 2 回から 3 回に増え、表示し直す確定が 2 回から 1 回になります。
72
+
73
+ - **描画中に `duringRender` の外で返す関数を呼ぶのは対応外です**。そうした呼び出しは 0.19.0 と同じく事象の時点の呼び出しとして、その場で写し・受け渡しの記録・利用側が知っている値を書いて通知し、
74
+ React が捨てた描画の中の呼び出しでも書き込みと通知を残します。描画中の呼び出しは `duringRender(action)` で包んでください (上の「追加」と下の「移行」)。
75
+ `duringRender` の外の呼び出しは、事象の処理・副作用・マイクロタスク・確定の途中 (子孫のレイアウト副作用の後始末など)・子の描画を省いたホストの描画の直後のどこで呼んでも、
76
+ 事象の時点の呼び出しです。`duringRender` の動作の中でほかのフックのインスタンスの返す関数を呼ぶと、そのインスタンスは何もせずに `Error` を送出します (上の「追加」)。
77
+ - **ノギスのフックの操作は、動かさないスケールをステートへ渡しません**。片方のスケールだけを動かす確定経路 (マクロ窓は `setMacroLowerDate` / `setMacroUpperDate`・`shiftMacroRange`・
78
+ マクロのセレクタの `onChange` と ◀▶・`sliderProps.onChangeMacroRange`、ミクロ選択は `setMicroLowerDate` / `setMicroUpperDate` / `setMicroDate`・`shiftMicroRange` / `shiftMicroValue`・
79
+ ミクロのセレクタの `onChange` と ◀▶・`sliderProps` のミクロのコールバック) は、もう片方のスケールの落ち着いた値が返す関数の読む値とも利用側が知っている値とも等しい間、
80
+ そのスケールを渡さず、知っている値も書かず、通知もしません。渡し直すと、事象の時点の書き込みとして、そのスケールへの `duringRender` の受け渡し (移行の描画が譲っている間の追従) を置き換え、
81
+ 追従した値を元へ戻してその通知も捨てるためです。利用側が別の値を知っているとき (収め直した値、緊急の確定が元の窓を描いた間も保留している窓の移行) は、これまでどおり描いた値を渡し直して通知し、
82
+ 保存する値を最後に通知した値と揃えます。操作の結果もう片方のスケールも動くとき (窓の移動で置き直したミクロ選択、窓を追従させるミクロの ◀▶) と `resetVernier` は、両方のスケールを確定します。
83
+ 動かすスケールは、返す関数の読む値 (確定したもう片方のスケール) に照らして置きます。追従した値と動かした値の両方を持つ描画でミクロ選択が窓に収まらないときは、
84
+ その描画が収め直しと同じくミクロ選択を置き直し (その場では通知しません)、その値は次にそれへ落ち着いた操作で通知されます。
85
+ そのため、マウントの後にまだ何も渡していないスケールへの同じ値の確定経路は、もう片方のスケールの操作の後でも、子の描画を省くホストの描画を 1 度走らせます。
86
+ 例えば `useVernierSliderRange` で、ミクロだけを動かす `setMicroUpperDate` の後に窓と同じ値の `setMacroUpperDate` を呼ぶと、0.19.0 では `setMicroUpperDate` が窓も渡して記録していたため描画が走りませんでしたが、
87
+ この版では 1 度走り、以後のホストの描画の回数が 1 つずつ増えます (`Profiler` の確定も 1 回増えます)。
88
+ - **4 つのフックは、ステートへ最後に渡した値の記録を、その受け渡しを持たない描画を挟んでも保ちます**。移行の中で渡した値を飛ばして確定した緊急の描画や、
89
+ 移行の描画が譲っている間に渡した値を持たないその移行の描画の後も、渡した値が確定すれば、その値へ落ち着く確定経路は何も渡さず、ホストは描き直されません。
90
+ 0.19.0 はそうした描画で記録を捨てていたため、その確定経路が同じ値を渡し直し、子の描画を省くホストの描画を 1 度走らせていました。
91
+ 値と通知は変わらず、`Profiler` の確定は 0.19.0 より 1 回少なくなります。
92
+
93
+ ### 修正
94
+
95
+ - **`DateSelector variant="dropdown"` のポップアップが、所有側が隠れている間も画面に残らなくなりました**。
96
+ React が隠すのは境界の中の最上位のホスト要素 (インラインの `display: none !important`) だけで、`document.body` へポータルしたポップアップには届きません。
97
+ これまでは開いたまま隠すと、ポップアップが隠れた操作要素から切り離されて最後の位置に (スクロールとリサイズへの追従も止まったまま) 画面に残り、
98
+ 行を押すと隠れたセレクタの `onChange` が呼ばれていました。ポップアップの根は隠す確定から同じインラインの `display: none !important` を持ち、閉じる描画で外れます。
99
+ 押下と同じ事象の中でホストが隠した場合 (開く更新と隠す更新が同じ一括に積まれる場合) も閉じます。
100
+ 隠れた操作要素へ届いた `ArrowDown`・`Enter`・押下は何もしません。所有側が隠すと React は操作要素の ref を外しますが、ブラウザが隠れた要素からフォーカスを外すのは次の描画更新のときで、
101
+ それまでの入力は隠れた操作要素へ届きます。受けると隠れた木で一覧を開き (`Activity` では配置を片付ける副作用が走らず、隠す前の配置でポップアップが画面に出る)、
102
+ `Enter` で `onChange` を呼び、表示し直すと開いたまま現れるため、ref の外れた操作要素への入力は捨てます。ref は確定のレイアウトの段階で付くため、画面に在る操作要素への入力は捨てません。
103
+
104
+ ### 移行
105
+
106
+ - 開いた `DateSelector variant="dropdown"` を `Activity` や `Suspense` で隠して表示し直すホストとテストは、表示後に閉じた操作要素 (`aria-expanded="false"`) を期待してください。
107
+ 一覧は利用者がもう一度開きます (パッケージは開き直す API を持ちません)。
108
+ - その前後で境界の外に置いた `Profiler` の確定を数えていた jsdom のテストは、開いたポップアップを隠す確定を 3 回 (これまで 2 回)、表示し直す確定を 2 回 (これまで 3 回)、
109
+ 押下と同じ事象の中で隠す場合は押下を 3 回 (これまで 2 回)・表示し直しを 1 回 (これまで 2 回) と期待してください。閉じたまま隠す場合の回数は変わりません。
110
+ `StrictMode` の中で数えるテストは、開いたポップアップを隠す確定を 3 回 (これまで 2 回)、表示し直す確定を 2 回 (変わらず)、押下と同じ事象の中で隠す場合は押下を `Activity` で 5 回 (これまで 4 回)・
111
+ `Suspense` で 3 回 (これまで 2 回)、表示し直しを 1 回 (これまで 2 回) と期待してください。
112
+
113
+ - 描画中に返す関数を呼ぶホストは、その呼び出しを `duringRender(action)` で包んでください (`if (target !== held) { setHeld(target); point.duringRender(() => point.setValue(target)) }`)。
114
+ 包んだ呼び出しの書き込みと通知はその描画の確定で当たり、React が捨てた描画は何も残しません。包まない描画中の呼び出しは 0.19.0 と同じくその場で働きますが、対応外です。
115
+ 描画のたびにフック自身の値と比べて追従するときは確定経路で呼ぶか、この例のように保持した目標と比べてください (直接の設定関数は呼ぶたびに値を渡すため、
116
+ フックが置き直す値への追従は落ち着かず、React の「Too many re-renders」に至ります。下の「文書」)。
117
+ ほかのフックの返す関数は、そのフックの `duringRender` の中で呼んでください (別のフックの `action` の中では `Error` です)。
118
+ - 包んだ呼び出しの通知は、その描画の確定でその描画のコールバックへ届きます。描画の途中で通知を読んでいたホストとテストは、その描画の確定で届く通知を読んでください
119
+ (描画中に通知へ応えていた処理は確定の後に走ります)。入れ子のホストの通知を親から子の順や前の確定のコールバックで期待していたテストは、子から親の順と、その描画のコールバックを期待してください。
120
+ 1 つのホストの複数のフックの通知は、フックを呼んだ順に届きます。
121
+ - 包んだ呼び出しの通知に応えてホスト自身のステートを書くホストで `Profiler` の確定を数えるテストは、確定が 1 回増えることを期待してください
122
+ (コールバックは確定の後に走るため、その更新は描画中の更新として同じ描画に畳まれず、同期の描画と確定をもう 1 回走らせます)。
123
+ - 描画中に返す関数を呼んで追従し、取り消した移行の後の同じ値の確定経路が通知しないことを期待していたテストは、呼び出しを `duringRender` で包んだうえで 1 度の通知を期待してください。
124
+ - ノギスのフックの操作の前後でホストの描画や `Profiler` の確定を数えるテストは、マウントの後にまだ何も渡していないスケールへ同じ値の確定経路を呼ぶと、
125
+ もう片方のスケールの操作の後でも 1 回増えることを期待してください (上の「変更」)。
126
+ - 移行の中で渡した値を飛ばした描画 (その後の緊急の描画や、移行の描画が譲っている間に渡した値を持たないその移行の描画) を挟み、その値の確定の後に同じ値の確定経路を呼ぶ前後で
127
+ `Profiler` の確定やホストの描画を数えるテストは、0.19.0 より 1 回少なく期待してください (4 つのフックに共通。上の「変更」)。
128
+ - `duringRender` で包んだ呼び出しがステートを変える値を渡した描画の確定の後には、その受け渡しの記録のため、子の描画を省くホストの描画と `Profiler` の確定が 1 回ずつ続きます。
129
+ 0.19.0 で描画中に直接呼んでいた追従を包んだホストでその前後を数えるテストは、1 回多く期待してください。`action` が何も渡さない描画では、ホストの本体が同じ描画の中で
130
+ もう 1 度走ります (確定は増えません)。
131
+
132
+ ### 文書
133
+
134
+ - **3 セレクタのメモ比較器の費用を計測しました。** キーを検証と同じ関数 (`keyInsideDateRange`) で求める 0.19.0 の比較器は、1 回あたり 0.18.0 の約 1.0〜1.7 倍で
135
+ (Node 24・jsdom・`TZ=Asia/Tokyo` の計測。比較器 1 回は 1〜数 µs)、増分は 1 キーあたり約 0.1 µs です。比較器 1 回がキーを求める回数は 0.18.0 と同じで
136
+ (読む Date 型 Props の値 1 つにつき 1 回、高々 7 回。`DateSelector variant="split-dropdown"` は高々 14 回)、範囲の広さと
137
+ `allowedDates` / `allowedMonths` / `allowedYears` の要素の数には依りません。日単位の `PeriodSlider` に 3 セレクタを結んだドラッグでは、増分は親の描画 1 回の 0.1% 未満です。
138
+ - **0.17.0 の「変更」の「フック自身の値と比べて描画のたびに呼ぶ追従は、値が境界・候補・窓へ置き直される場合も、これまでどおり置き直した値で落ち着きます」は、確定経路に限ります。**
139
+ 確定経路 (シフト・リセット、`setLowerDate` / `setMicroDate` などの端ごとの設定関数、セレクタと `sliderProps` のコールバック、◀▶) は、走らせ直した描画で同じ値を何も渡さずに落ち着きます。
140
+ 直接の設定関数 (`setValue` / `setRange` / `setMacroRange` / `setMicroRange` / `setMicroValue`) は呼ぶたびに値を渡すため、フックが置き直す値へ描画のたびに比べて追従すると
141
+ 落ち着かず、React の「Too many re-renders」に至ります (0.19.0 の描画中の直接の呼び出しでも、この版の `duringRender` の中でも同じです)。
142
+ そうした追従は確定経路で呼ぶか、保持した目標と比べてください (上の「移行」の例)。
143
+
144
+ ## 0.19.0 (2026-10-02)
145
+
146
+ パッケージ全体が Date を時刻値のシステムのタイムゾーンで読むようにし、3 セレクタのメモ比較器と非制御の選択が、Date 型 Props の単位を検証と同じ関数 (`keyInsideDateRange`) で読むようにした版です。
147
+ 比較器が描画を省くかどうかと検証が拒否するかどうかは、2 つの実装が同じ時刻を求めることを前提にせず、構成上一致します。Props は増えず、通常の `Date` では Date の読み方による挙動の変化はありません。
148
+ あわせて、`DateSelector variant="dropdown"` の操作要素の `aria-activedescendant` と `aria-controls` が DOM に無い要素を指さないようにしました (Props と公開 API は変わりません)。
149
+ 4 つのフックは返す関数が値を渡すステートを `useReducer` で持ち、React が捨てた描画の中でホストが返す関数へ渡したオブジェクトを、後で同じオブジェクトのまま渡しても描くようにしました (Props と公開 API は変わりません)。
150
+ **自身のゲッターがシステムのタイムゾーンと別の年・月・日を名乗る Date (別のタイムゾーンで作った `@date-fns/tz` の `TZDate`、`@date-fns/utc` の `UTCDate` など) を
151
+ 3 セレクタ・本体・4 つのフック・公開の純関数へ渡すホストでは、下の「変更」と「修正」の点で挙動が変わります。**
152
+ **4 つのフックの設定関数へステートが既に持つオブジェクトを渡すホスト、受け渡しの記録が無い間 (マウントの後など) に保持する値と同じ値で確定経路
153
+ (`resetValue`・セレクタの `onChange`・`setLowerDate` など) を呼ぶホスト、そうした呼び出しの前後でホストの描画や `Profiler` の確定を数えるテストでは、下の「変更」の点で挙動が変わります。**
154
+ **`DateSelector variant="dropdown"` を開く前後で `Profiler` の確定を数えるテストと、操作要素の React の Props から `aria-activedescendant` を読むツールでも、下の「変更」の点で挙動が変わります。**
155
+
156
+ ### 変更
157
+
158
+ - **4 つのフックの設定関数へステートが既に持つオブジェクトを渡すと、子の描画を省くホストの描画が呼び出しごとに 1 度走ります**。
159
+ 対象は `setRange` / `setValue` / `setMacroRange` / `setMicroRange` / `setMicroValue` へステートのオブジェクトそのもの (引数をそのまま返す更新関数を含む) を渡す呼び出しで、
160
+ 更新の後の 2 度目以降の同じ呼び出しも含みます。これまでは、ホストに保留中の更新が無い間は React が描画を起こさずに捨てていました (更新の直後の 1 度目だけは同じ描画が走っていました)。
161
+ 設定関数以外の返す関数 (セレクタの `onChange`・`sliderProps` のコールバックなど) では、受け渡しの記録が無い間 (マウントの後、収め直しの記録の確定から別の確定を挟んだ後など。
162
+ 記録の確定の直後の呼び出しは、これまでも 1 度走っていました) に保持する値へ落ち着いたとき 1 度だけ走り、
163
+ その後の同じ値はこれまでどおり記録で省きます (更新の後の同じ値の呼び直しも、これまでどおり描画を起こしません)。パッケージの本体とセレクタは、設定関数以外の返す関数だけを呼びます。
164
+ 走る描画は子を描き直さず、副作用も DOM の変更もありません (`Profiler` の確定は 1 回増えます)。値・コールバック・返す関数とオブジェクトの同一性・マウントと収め直しの確定の回数は変わりません。
165
+ - **年の単位も、Date を時刻値のシステムのタイムゾーンで読みます**。`normalizeDateByUnit` は月と日の単位では時刻値の複製を読む一方、年の単位では Date 自身のゲッター
166
+ (`getFullYear` / `getMonth`) を読んでおり、`addUnit` の月・年の加算、`getMacroWindowEndDate` の年 × 月・年 × 日・月 × 日の期間、`resolveQuarter` / `formatQuarterLabel` の四半期、
167
+ `formatLabel` / `formatOptionText` の ISO と数字の表記 (`formatLocale` を渡さない段)、`YearSelector` の描く年・境界・`allowedYears` の要素も同じゲッターを読んでいました。
168
+ どれも時刻値のシステムのタイムゾーンでの年・月・日を読むため、ゲッターが別のタイムゾーンを名乗る Date の派生クラスは、同じ時刻の素の `Date` と同じ単位・同じ表記になります
169
+ (`encode` / `keyInsideDateRange` の年のキーと、それを読む本体・4 つのフックの年の単位の値と境界を含みます)。東京で `2024-03-31T20:00Z` (現地 4 月 1 日 5 時) の `UTCDate` は、
170
+ `yearStartMonth={3}` の `YearSelector` では 2023 年を描いていましたが 2024 年を描き、`formatLabel("day", ...)` は `2024-03-31` でしたが `2024-04-01` を返します。
171
+ `formatLocale` を渡した表記は以前から時刻値を読んでおり、変わりません。
172
+ - **`DateSelector variant="dropdown"` は、開くたびの確定が 1 回減り (jsdom の `Profiler` で 3 回 → 2 回)、描画範囲の通知による再描画が無くなります**
173
+ (jsdom のテストでこの再描画が出していた `act(...)` の警告も出ません)。`formatOption` の呼び出し回数は変わりません。
174
+ 操作要素の `aria-activedescendant` はアクティブ行の ref が書くため (下の「修正」)、操作要素の React の Props ではなくなり、開発ツールの Props には現れません
175
+ (DOM と支援技術から見える値は同じです)。
176
+
177
+ ### 修正
178
+
179
+ - **`MonthSelector` は `value` / `initialDate` / `minDate` / `maxDate` と `allowedMonths` の要素を、検証が判定する月 (時刻値のシステムのタイムゾーンでの月) で読みます**。
180
+ これまでは検証が時刻値の月を判定する一方、描く月・`min` / `max` の属性・選択肢・メモ比較器は各 Date 自身のゲッター (`getFullYear` / `getMonth`) の月を読んでおり、
181
+ ゲッターが別の月を名乗る Date では 2 つの月が食い違っていました (東京で `2024-03-31T20:00Z` (現地 4 月 1 日 5 時) の `UTCDate` を渡すと `2024-03` を描いていましたが、
182
+ `2024-04` を描きます)。比較器も同じ月で比べるため、そうした値を検証が拒む月へ動かした再描画は省かれずにその描画で `RangeError` になり (これまでは省かれ、
183
+ 拒否が次の無関係な変更まで遅れていました)、省いた描画は新規のマウントと同じ月を描きます。表現範囲の最初の月の近くで、ゲッターが表現範囲の外で始まる月を名乗る Date を
184
+ 検証が受け付けた描画は、内部関数の `RangeError` (`drawnValuesNeighbour: values.min must be a finite integer (received: NaN)`) で落ちていましたが、時刻値の月を描きます。
185
+ `YearSelector` の年と `DateSelector variant="split-dropdown"` の年の検査も、時刻値の読み方へ揃えました (上の「変更」と下の項)。
186
+ - **`DateSelector variant="split-dropdown"` は、ゲッターが別の年を名乗る Date の `value` / `initialDate` / `minDate` / `maxDate` を、描く年で検査します**。
187
+ これまでは年の検査 (`assertSplitYearProp`) が Props 自身のゲッターの年を、保持中の選択の検査と描画が時刻値の年を読んでおり、表現範囲の最初の年の近くで食い違っていました
188
+ (ニューヨークで `-271820-01-01T02:00Z` (現地 -271821 年 12 月 31 日 21 時) の `UTCDate` を `value` に渡すと、名指す日付の無い年の選択肢を描いて `formatOption` に Invalid Date を渡し、
189
+ `initialDate` に渡すと、初回のマウントが以前の描画から保持している選択を名指す `RangeError` になっていました)。どちらも同じ時刻の素の `Date` と同じく、
190
+ Props を名指す `RangeError` (`DateSelector: value must fall in a year that starts inside the Date range, because variant="split-dropdown" draws its year (received: ...)`) になります。
191
+ - **`DateSelector variant="dropdown"` の `aria-activedescendant` と `aria-controls` が、DOM に無い要素を指さなくなりました**。
192
+ 開く操作の最初の確定 (ポップアップの実測前) は listbox も行も無いのに両属性を持ち、ホイール・スクロールバーでアクティブ行を描画窓の外へ送ると、
193
+ スクローラの描画範囲の通知 (後のアニメーションフレーム) が届くまで消えた行を指したまま描かれ、スクロールやキー操作で窓へ戻すと、通知が届くまで名指しを欠いていました。
194
+ 開いたまま選択肢が 0 件になった確定も、閉じる前に存在しない listbox を `aria-controls` で指していました。
195
+ `aria-activedescendant` は Props ではなくアクティブ行の ref が書き、行を付けた確定で名指し、外した確定で消します。`aria-controls` はポップアップを描くのと同じ条件で名乗ります。
196
+ Activity・Suspense で隠れている間は `aria-activedescendant` を持たず、開いたまま表示し直すと同じ行を名指します (隠れている間に閉じても、表示後に消えた行を指しません)。
197
+ 開くたびの確定の回数と、操作要素の React の Props から属性が無くなる点は、上の「変更」にまとめました。
198
+ - **4 つのフックは、React が捨てた描画の中でホストが返す関数へ渡したオブジェクトを、後で同じオブジェクトのまま渡しても描きます**。
199
+ ホストが自分の描画の中で返す関数を呼んで Props へ追従し、React がその描画を捨てた後 (Suspense が保留した移行、取り消した移行) に、同じオブジェクトを
200
+ `setValue` / `setRange` / `setMacroRange` / `setMicroRange` / `setMicroValue` へ渡すと、これまでは描かれず、フックが別の理由で描き直されるまで
201
+ (取り消した移行の後では、いつまでも) 前の値に留まっていましたが、その確定が描きます (取り消した移行の後も、その場で描きます)。
202
+ 確定経路 (セレクタの `onChange` など) がそのオブジェクトを渡すとき (時点フックはレールに載っている Date をそのまま渡します) も、捨てた描画の後 (取り消した移行) にフックが一度描かれていれば、その確定が描きます。
203
+ これまでどおり、ホスト自身が渡した値は利用側が知っている値のため、通知しません。取り消した移行では、捨てた描画からフックが次に描かれるまでの間、返す関数はその描画が渡した値を読み、
204
+ 確定経路はそれと同じ値を渡しません (その呼び出しは描かれず、通知もされません。この版でも変わりません)。
205
+ Suspense が保留したままの移行では、React は確定のたびにその移行を描き直して捨て、ホストの描画中の呼び出しが同じ値を渡し直すため、写し・受け渡しの記録・利用側が知っている値は、
206
+ その移行が確定するか取り消されるまでその値に戻り続けます (シフトはそこから進み、その値と同じ確定経路の呼び出しは描かれず、通知もされません。この版でも変わりません)。
207
+
208
+ ### 移行
209
+
210
+ - 3 セレクタ・本体・4 つのフック・公開の純関数にゲッターが別のタイムゾーンを名乗る Date を渡し、そのゲッターの年・月・日を描かせていた、または読ませていたホストは、
211
+ 描かせたい年・月・日に属するシステムのタイムゾーンでの日付を渡してください。
212
+ - 4 つのフックの設定関数へステートが持つオブジェクトを渡す前後で `Profiler` の確定やホストの描画を数えていたテストは、呼び出しごとに 1 回多い回数を期待してください (上の「変更」)。
213
+ - `DateSelector variant="dropdown"` を開く前後の `Profiler` の確定を数えていたテストは、開くたびに 1 回少ない回数を期待してください。操作要素の React の Props から
214
+ `aria-activedescendant` を読んでいたツールは、DOM の属性を読んでください (上の「変更」)。
215
+
7
216
  ## 0.18.0 (2026-10-02)
8
217
 
9
218
  単位を受け取るすべての公開の入口 (本体・4 つのフック・公開の純関数) が、`"year"` / `"month"` / `"day"` 以外の単位を日として読まず、
package/README.md CHANGED
@@ -971,6 +971,8 @@ DOM 要素の特定は CSS クラス名ではなく `data-*` 属性で行いま
971
971
 
972
972
  単位を受け取る公開関数 (`normalizeDateByUnit` / `encode` / `decode` / `addUnit` / `getMacroWindowStartDate` / `getMacroWindowEndDate` / `resolveMacroWindow` / `findNearestDateIndex` / `getSortedAllowedDates` / `formatLabel` / `formatScreenReaderLabel` / `formatOptionText` / `calculateConnectDragValues` / `resolveSelectorSteps` / `resolveVernierSelectorSteps`) は、`"year"` / `"month"` / `"day"` 以外の単位 (`null`・大文字違い・空文字列を含む。省略できない単位の引数では `undefined` も) を日として読まず、`RangeError: <関数名>: <引数名> must be one of "year", "month", "day" (received: ...)` で拒否します (`encode: unit must be one of "year", "month", "day" (received: "decade")`)。単位は `yearStartMonth`・日付・`amount`・候補の一覧より先、無効日付の短絡 (`formatLabel` / `formatScreenReaderLabel` / `formatOptionText` の `""`) と早期 return (`findNearestDateIndex` / `getSortedAllowedDates` の空の一覧、`calculateConnectDragValues` の連続モード) より先に判定します。`resolveSelectorSteps` / `resolveVernierSelectorSteps` だけは、オプションがオブジェクトであること (`resolveVernierSelectorSteps` は `row` / `shows` も) を単位より先に判定します。`resolveSelectorSteps` の `stepUnit` が `unit` になるのは省略 (`undefined`) したときだけで、`null` は同じ `RangeError` です。
973
973
 
974
+ 日付は、どの部品・フック・公開関数も **Date 自身のゲッターではなく、時刻値をシステムのタイムゾーンで読みます** (年・月・日・四半期の判定、`addUnit` の加算、`formatLocale` を渡さない ISO と数字の表記。`formatLocale` を渡した Intl の表記と同じ読み方です)。自身のゲッターが別のタイムゾーンを名乗る Date の派生クラス (別のタイムゾーンで作った `@date-fns/tz` の `TZDate`、`@date-fns/utc` の `UTCDate` など) も、同じ時刻の素の `Date` と同じ年・月・日として扱います。別のタイムゾーンの暦の年・月・日を選ばせたいときは、その年・月・日に当たるシステムのタイムゾーンでの日付を渡してください。
975
+
974
976
  #### 表示テキスト — `formatOptionText` / `PeriodOptionFormatter` / `PeriodOptionScope`
975
977
 
976
978
  ```ts
@@ -1444,12 +1446,12 @@ DOM 契約: ルート要素は `data-variant="date|dropdown|split-dropdown"` を
1444
1446
 
1445
1447
  `variant="dropdown"` の DOM 契約:
1446
1448
 
1447
- - 操作要素は `<input type="text" readonly role="combobox">` で、`value` には人間が読むテキスト (`formatOption` 指定時はその返り値、未指定なら `formatLocale` 書式)、`data-value` には常に `yyyy-MM-dd` の機械可読値を持ちます。この `value` は選択中の行のテキストと必ず一致します (同じ関数値へ同じ形の引数を渡すため)。`aria-expanded` / `aria-haspopup="listbox"` / `aria-controls` (開いている間) / `aria-activedescendant` (アクティブ行が描画されている間) を持ち、`data-testid="period-slider-date-combobox"` で引けます。集合外の保持値は行にならず、操作要素の表示テキストとしてだけ現れます。
1449
+ - 操作要素は `<input type="text" readonly role="combobox">` で、`value` には人間が読むテキスト (`formatOption` 指定時はその返り値、未指定なら `formatLocale` 書式)、`data-value` には常に `yyyy-MM-dd` の機械可読値を持ちます。この `value` は選択中の行のテキストと必ず一致します (同じ関数値へ同じ形の引数を渡すため)。`aria-expanded` / `aria-haspopup="listbox"` / `aria-controls` (ポップアップが描かれている間) / `aria-activedescendant` (アクティブ行が DOM に在る間。スクロールで窓の外へ出ると外れ、戻ると同じ確定で付き、Activity などで隠れている間は持たない) を持ち、`data-testid="period-slider-date-combobox"` で引けます。集合外の保持値は行にならず、操作要素の表示テキストとしてだけ現れます。
1448
1450
  - 開く位置は保持値の行、保持値が集合の外にあるときは**その値に最も近い行** (同距離では早い側の日付) です。先頭行から開かないため、100 年の定義域でも戻る操作が数行で済みます。開いた行は `data-active="true"` と `aria-activedescendant` が指しますが、集合外の保持値では `aria-selected="true"` の行は 1 つもありません (アクティブ行は「これから選ぶ候補」であり、選択済みではないため)。操作要素の表示テキストと `data-out-of-range="true"` はどちらも動きません。
1449
- - ポップアップは `document.body` へポータルされ (`data-testid="period-slider-date-popup"`)、開いた時点の操作要素の位置から解決した配色モードを `data-color-mode="light|dark"` として持ち、操作要素の下に開き、余地が無ければ上へ反転して視野内へ収まります。中の `role="listbox"` (アクセシブル名は `labels.dateSelect`、操作要素と同じ名前) が `role="option"` の行を持ち、各行は `aria-selected` / `aria-posinset` / `aria-setsize` (集合全体の件数) / `data-active` (キーボードの現在位置) を持ち、`data-testid="period-slider-date-option"` で引けます。DOM に存在する行は可視窓の分だけで、集合全体の件数は `aria-setsize` から読みます。
1451
+ - ポップアップは `document.body` へポータルされ (`data-testid="period-slider-date-popup"`)、開いた時点の操作要素の位置から解決した配色モードを `data-color-mode="light|dark"` として持ち、操作要素の下に開き、余地が無ければ上へ反転して視野内へ収まります。中の `role="listbox"` (アクセシブル名は `labels.dateSelect`、操作要素と同じ名前) が `role="option"` の行を持ち、各行は `aria-selected` / `aria-posinset` / `aria-setsize` (集合全体の件数) / `data-active` (キーボードの現在位置) を持ち、`data-testid="period-slider-date-option"` で引けます。DOM に存在する行は可視窓の分だけで、集合全体の件数は `aria-setsize` から読みます。所有側 (`Activity`・`Suspense`) が隠れている間、ポップアップは画面に出ません (隠す確定でインラインの `display: none !important` を持ち、閉じて外れます)。隠れている間に操作要素へ届いた打鍵と押下は何もしません (一覧を開かず、`onChange` も呼びません)。
1450
1452
  - ポップアップには `role="listbox"` のほかに `@aiquants/virtualscroll` のスクロールバーが同居します (`role="scrollbar"`、つまみの `role="slider"`、そして `aria-label` を持つ矢印ボタン 2 つ)。矢印ボタンは常に `disabled` でタブ順にもキーボード操作にも現れませんが、アクセシビリティツリーには残ります。その名前は `locale` のカタログの `scrollUp` / `scrollDown` (`Scroll up` / `Scroll down`、`ja` では `上へスクロール` / `下へスクロール`) で、`labels` の同じキーで上書きできます (本パッケージが内蔵 VirtualScroll へ `locale` とエンジン 7 キーを転送します)。ポップアップに絞った `getByRole("button")` はこの 2 つに当たるため、行は `role="option"` か `data-testid` で引いてください。
1451
1453
  - キーボード: `ArrowDown` / `ArrowUp` (閉じていれば開く、開いていれば 1 行移動)、`Home` / `End` (先頭 = 最新日 / 末尾 = 最古日)、`PageDown` / `PageUp` (1 窓 = 7 行)、`Enter` (閉じていれば開く、開いていればアクティブ行を確定)、`Escape` (閉じる・発火しない)、`Tab` (閉じる)、数字と `-` / `/` / `.` (先頭一致入力。**表示書式に関わらず**先発グレゴリオ暦の `yyyy` / `yyyyMM` / `yyyyMMdd` として解釈し、走査せずに当該日へ飛ぶ。`formatOption` が非数字のテキストを返していても変わらない)。行の押下でも DOM フォーカスは操作要素から離れません。
1452
- - 閉じる契機: 行の確定、`Escape`、`Tab`、操作要素からのフォーカス喪失、ポップアップ外の `pointerdown`。
1454
+ - 閉じる契機: 行の確定、`Escape`、`Tab`、操作要素からのフォーカス喪失、ポップアップ外の `pointerdown`、所有側が `<Activity mode="hidden">` で隠れたとき・`Suspense` がフォールバックを出したとき (表示し直しても閉じたまま)。
1453
1455
  - `startTransition` で渡した境界・`allowedDates`・`formatLocale`・`formatOption` は、その描画が確定するまでポップアップに使われません。一覧の行 (スクロールで描き足す行も)・先頭一致入力・行の押下は、画面に描かれている一覧を読みます。開いたまま件数が縮み、アクティブ行が一覧の外に出るときは、件数を縮めた描画のうちに末尾の行へ移り、件数が戻っても移った行に留まります。開いている間に配置だけが変わる描画 (ページのスクロール・リサイズへの追従) は、描かれている行を描き直しません (`formatOption` を呼ぶのは新しく描く行だけです)。
1454
1456
  - ポップアップは `.period-slider` の外に立つため、`colorScheme` の変数 (`--aqps-*`) は届きません。選択中の行のアクセント色はパッケージ既定の色です。重なり順だけは `--aqps-z-date-popup` (既定 60) で差し替えられます。
1455
1457
  - ダークモードは `.dark` の位置に依存しません。ポップアップの祖先 (`document.body` の側) に `.dark` が無くても、**操作要素自身の位置**で解決したモードを `data-color-mode` として運ぶため、`.dark` を部分木へ限定したホストでも暗色で開きます。
@@ -1685,15 +1687,26 @@ const { sliderProps, startSelectorProps } = usePeriodSliderRange({ unit: "day",
1685
1687
  - 候補と同じ単位の中の値 (月の候補 `2024-01-01` に対する `2024-01-15`) は、その候補として描かれるため渡されたまま残ります。
1686
1688
  - 単位で定義域に入る候補は生の時刻では境界の外に居られるため (月の途中を指す `minDate` と月初の候補)、寄せた後も時刻で境界へ収めます。期間の両端が同じ候補へ寄って生の時刻で逆転するときは、上限を下限へ揃えます。利用側が `setRange` や `sliderProps.onChangeRange` へ逆転した期間を渡したときは揃えず、`RangeError` です。
1687
1689
  - 候補の上にない `initialRange` / `initialValue` は拒まず、同じ規則でレールへ置いた値でステートを始め、最初の確定から置いた値を描きます (マウントの確定は 1 回です)。初期値を境界と照らすのはマウント時だけです。マウント時に渡した初期値だけが `resetRange` / `resetValue` の行き先になり (後から変えた `initialRange` / `initialValue` は有効性と逆転だけを検証し、採用しません)、リセットもいまの定義域へ収めて確定します。境界が初期値を越えて動いても送出せず、ステートを収め直します。
1688
- - 収め直しは描画が描き、ステートへの記録はその描画の確定 (レイアウト副作用) で行います。描画中にステートを書くと、確定しない描画 (Suspense が保留した移行) が求めた値を React がキューに残し、その値と同じオブジェクトの受け渡しが描画を起こさずに捨てられるためです。収め直す更新は、同じ値を描く 2 回目の確定を伴います。ノギスのフック (`useVernierSliderRange` / `useVernierSliderPoint`) のマクロ窓とミクロ選択の収め直しも同じで、ノギスのフックは離散のミクロレールに載らない初期値を最初の確定で記録するため、そのマウントは確定が 2 回になります。隠れた `<Activity>` の中の確定は記録せず、表示したときにその描画の Props で記録します (隠れている間に境界を狭めて戻したフックは、畳む前の値を描きます)。
1689
- - `onChangeRange` / `onChangePoint` は、確定した値が**利用側の知っている値** (渡した初期値・`setRange` / `setValue` で自分で書いた値・最後に通知した値) と異なるときに鳴ります。ノギスの通知 (`onChangeMacroRange` / `onChangeMicroRange` / `onChangeMicroPoint`。知っている値は `setMacroRange` / `setMicroRange` / `setMicroValue` で書いた値も含む) も同じ規則です。収め直しはその場では通知しませんが、次にその値へ落ち着いた操作で通知されます (マウントで寄せた初期値も同じ)。反対に、収め直しの後で利用側の知っている値へ戻る操作は鳴りません。現在の値はコールバックではなく、フックの `range` / `value` で読めます。
1690
+ - 収め直しは描画が描き、ステートへの記録はその描画の確定 (レイアウト副作用) で行います。記録するのは画面に出た確定が描いた値だけです。収め直す更新は、同じ値を描く 2 回目の確定を伴います。ノギスのフック (`useVernierSliderRange` / `useVernierSliderPoint`) のマクロ窓とミクロ選択の収め直し (片方のスケールへの追従ともう片方の操作の両方を持つ描画で、ミクロ選択が窓に収まらないときを含む。下の「ノギスの操作は、動かすスケールだけをステートへ渡します」) も同じで、ノギスのフックは離散のミクロレールに載らない初期値を最初の確定で記録するため、そのマウントは確定が 2 回になります。隠れた `<Activity>` の中の確定は記録せず、表示したときにその描画の Props で記録します (隠れている間に境界を狭めて戻したフックは、畳む前の値を描きます)。
1691
+ - `onChangeRange` / `onChangePoint` は、確定した値が**利用側の知っている値** (渡した初期値・`setRange` / `setValue` で自分で書いた値・最後に通知した値) と異なるときに鳴ります。`duringRender` の中で呼んだ返す関数が書いた値と通知した値は、その描画が確定したときに知っている値になります (React が捨てた描画の中で渡しただけの値は、知っている値になりません)。ノギスの通知 (`onChangeMacroRange` / `onChangeMicroRange` / `onChangeMicroPoint`。知っている値は `setMacroRange` / `setMicroRange` / `setMicroValue` で書いた値も含む) も同じ規則です。収め直しはその場では通知しませんが、次にその値へ落ち着いた操作で通知されます (マウントで寄せた初期値も同じ)。反対に、収め直しの後で利用側の知っている値へ戻る操作は鳴りません。現在の値はコールバックではなく、フックの `range` / `value` で読めます。
1690
1692
 
1691
1693
  **フックの返す関数は、画面に描かれている描画 (最後に確定した描画) の値を読みます**。4 つのフックの設定関数・シフト・リセット・`sliderProps` のコールバック・セレクタの ◀▶ は、最後に確定した描画の境界・候補・コールバック・ステートを読みます。
1692
1694
 
1693
1695
  - `startTransition` で渡した新しいオプションは、その描画が確定するまで使われません。確定していない描画が渡したコールバックは呼ばれません。関数の同一性は変わりません。
1694
1696
  - 子孫のレイアウト副作用から呼んでも、隠れた `Activity` の中でも、その確定の値を読みます。
1695
- - 確定経路は、返す関数が最後にステートへ渡した値と同じ値を、それがステートの最後の更新だと分かっている間は渡さず、それ以外は同じ値でもステートへ渡します。そのため `startTransition` の中で呼んだ設定関数が中断している間に別の操作をしても、保存される値は最後に通知した値 (または `setRange` などで書いた値) と一致します。その間に境界・候補・窓が動いて確定済みの値を収め直しても、収め直しの記録は中断している値を上書きしません。中断している値と同じ値を緊急に呼び直しても、その間にホストが描き直されていなければその値を緊急の優先度へ引き上げず (代替表示を出さず)、更新の後に同じ値で呼び直してもホストは描き直されません。
1696
- - 描画中に呼ぶと、描画中の値ではなく最後に確定した描画の値を読みます (同じ描画で広げた `maxDate` ではなく、前の確定の `maxDate` で収めます)。フック自身の値と比べて描画のたびに呼ぶ追従は、値が境界・候補・窓へ置き直される場合も、置き直した値で落ち着きます。同じ描画の値で収めるには、副作用 (`useEffect` / `useLayoutEffect`) かイベントハンドラの中で呼んでください。
1697
+ - 確定経路は、返す関数が最後にステートへ渡した値と同じ値を、それがステートの最後の更新だと分かっている間は渡さず、それ以外は同じ値でもステートへ渡します。そのため `startTransition` の中で呼んだ設定関数が中断している間に別の操作をしても、保存される値は最後に通知した値 (または `setRange` などで書いた値) と一致します。その間に境界・候補・窓が動いて確定済みの値を収め直しても、収め直しの記録は中断している値を上書きしません。中断している値と同じ値を緊急に呼び直しても、その間にホストが描き直されていなければその値を緊急の優先度へ引き上げず (代替表示を出さず)、更新の後に同じ値で呼び直してもホストは描き直されません。確定経路がステートと同じオブジェクトを渡すときと、設定関数へステートが持つオブジェクトそのものを渡したとき (呼び出しごと) は、子を描き直さないホストの描画が 1 度走ります。
1698
+ - ホストの描画の中で返す関数を呼ぶときは、`duringRender(action)` の `action` の中で呼びます。`action` の中で同期に呼んだこのフックの返す関数は、その描画の中だけで働きます。読む値は最後に確定した描画の値 (その後に事象の時点で書いた値と、同じ描画で先に呼んだ返す関数が渡した値があればその値) で、境界も前の確定のもので収めます (同じ描画で広げた `maxDate` ではなく、前の確定の `maxDate`)。ステートへの受け渡しは React の描画中の更新になり、写し・受け渡しの記録・利用側が知っている値への書き込みと通知は、その描画が確定したときに行います。React が捨てた描画 (Suspense が保留した移行、取り消した移行) は何も残しません。フックがその描画の分を続けるのは、`duringRender` を呼んだ描画の続き (描画中の更新の後の走らせ直し、`StrictMode` の 2 度目の呼び出し、中断した描画のデータが解決した後の再実行) だけで、React が捨てた描画の分は、同じ値を持つ後の別の描画が確定しても当たらず (通知も届かず)、後の描画の `action` の書き込みと通知を消しもしません。これを見分けるため、描画の中で最初に呼んだ `duringRender` はその描画に印を描画中の更新として付け、`action` が何も渡さなくても、ホストの本体は同じ描画の中でもう 1 度走ります (子の描画と確定は増えません)。その描画に入らない事象の書き込み (描画がフックを呼んだ後の書き込みと、描画が持たない保留中の受け渡し: 移行が譲っている間にホストの描画より前に渡した値や、その描画が飛ばす優先度の移行の中で渡した値) があるステートには描画の分を当てず、事象の書き込みが後から当たります (ノギスのフックではスケールごと)。`action` の中の受け渡しがまだ確定し得る間は、表示中の値へ落ち着く事象の時点の呼び出しも同じ値をステートへ渡し直し、後の操作として勝ちます (渡し直しは子の描画を省くホストの描画を 1 度走らせます。React が捨てた描画の `action` が値を渡した後も、ホストが次に描かれるまでは、最初のそうした呼び出しで同じく 1 度走ることがあります)。`action` の中でステートを変える値を渡した描画の確定の後は、その受け渡しをステートの更新の列へ記録するため、子の描画を省くホストの描画が 1 度走ります (その描画が飛ばした優先度の低い受け渡しを React が後で当て直しても、保存される値が通知した値に行き着くようにするため)。フック自身の値と比べて描画のたびに呼ぶ追従は、確定経路 (シフト・リセット、`setLowerDate` / `setMicroDate` などの端ごとの設定関数、セレクタと `sliderProps` のコールバック、◀▶) で呼べば、値が境界・候補・窓へ置き直される場合も置き直した値で落ち着きます (走らせ直した描画の同じ値の確定経路は何も渡しません)。直接の設定関数 (`setValue` / `setRange` / `setMacroRange` / `setMicroRange` / `setMicroValue`) は呼ぶたびに値を渡すため、フックが置き直す値へ描画のたびに比べて追従すると落ち着かず、React の「Too many re-renders」に至ります。設定関数で追従するときは、下の例のように保持した目標と比べます (`if (target !== held)`)。同じ描画の値で収めるには、副作用 (`useEffect` / `useLayoutEffect`) かイベントハンドラの中で呼んでください。設定関数 (`setValue` など) へ渡した値は、同じオブジェクトでもその確定が描きます。
1699
+ - `duringRender` は、フックを呼んだホスト自身の描画の中で、フックを呼んだ後に呼びます。フックの描画の範囲が閉じた後、つまりフックの最後の描画が確定した後 (確定した描画から控えた戻り値をフックの呼び出しより前に使う場合を含む) と、本体を走らせた同期の処理が終わった後 (副作用・イベントハンドラ・フックを呼んだ後に積んだマイクロタスク) に呼ぶと、フック名を名乗る `Error` (`usePeriodSliderPoint: duringRender(action) must be called during the host's render, after the hook call (...)`) です。`action` が関数でなければ `TypeError` (`usePeriodSliderPoint: duringRender(action) must be a function (received: ...)`) です。`action` の中でほかのフックのインスタンスの返す関数を呼ぶと、そのインスタンスが何もせずに自分の名前を名乗る `Error` (`... a returned function was called during another hook's duringRender(action); ...`) を送出します (そのインスタンスの `duringRender` を入れ子に呼び、その中で呼びます)。`action` が送出した例外はそのまま伝わり、`duringRender` の同一性はコンポーネントの存続中ずっと変わりません。ほかのコンポーネントの描画の中、フックを呼ぶ前、確定しなかった描画と同じ同期の処理の中の事象のコード、描画のコードがフックを呼ぶ前に積んだマイクロタスク (先に描いたコンポーネントが積んだものを含む) で `duringRender` を呼ぶのも対応外です (送出されないことがあります)。
1700
+ - `duringRender` の外の呼び出しは、どこで呼んでも (事象の処理・副作用・マイクロタスク・確定の途中 (子孫のレイアウト副作用の後始末など)・描画中) 事象の時点の呼び出しで、その場で書き、待っている通知を届けてから通知します。描画中に `duringRender` の外で呼ぶのは対応外です (React が捨てた描画の中でも書き込みと通知が残ります)。`action` の中の呼び出しの通知は、その描画のコールバックへホストのレイアウト副作用で届き (その確定で先に走る子孫のレイアウト副作用がフックへ書くか通知するときはその前、隠れた `Activity` の中の確定ではマイクロタスク)、入れ子のホストでは子から親、1 つのホストの複数のフックではフックを呼んだ順に届きます。通知に応えてホスト自身のステートを書くコールバックは確定の後に走るため、その更新は同期の描画と確定をもう 1 回走らせます。サーバー描画では確定が無いため、`action` の中の呼び出しはコールバックを呼びません。
1701
+
1702
+ ```tsx
1703
+ const point = usePeriodSliderPoint({ unit: "day", minDate, maxDate, initialValue })
1704
+ const [held, setHeld] = useState(target)
1705
+ if (target !== held) {
1706
+ setHeld(target)
1707
+ point.duringRender(() => point.setValue(target)) // 描画中の呼び出しは duringRender で包む
1708
+ }
1709
+ ```
1697
1710
 
1698
1711
  #### `usePeriodSliderRange(options)`
1699
1712
 
@@ -1721,6 +1734,7 @@ const { sliderProps, startSelectorProps } = usePeriodSliderRange({ unit: "day",
1721
1734
  | `startSelectorProps` | `SelectorProps` | 開始側セレクタ用 Props (`maxDate` は現在の上限日付) |
1722
1735
  | `endSelectorProps` | `SelectorProps` | 終了側セレクタ用 Props (`minDate` は現在の下限日付) |
1723
1736
  | `sliderProps` | `PeriodSliderRangeProps` | `<PeriodSlider {...sliderProps} />` へ渡す Props |
1737
+ | `duringRender` | `(action: () => void) => void` | ホストの描画の中で返す関数を呼ぶための関数。`action` の中で同期に呼んだ返す関数はその描画の中だけで働き、書き込みと通知はその確定で当たる (上の「共通: `SelectorProps`」)。ホスト自身の描画の中、フックを呼んだ後で呼ぶ (フックの最後の描画が確定した後と、本体を走らせた同期の処理が終わった後は `Error`、関数でない `action` は `TypeError`。検出しない誤用は上の「共通: `SelectorProps`」)。同一性はコンポーネントの存続中ずっと変わらない |
1724
1738
 
1725
1739
  #### `usePeriodSliderPoint(options)`
1726
1740
 
@@ -1742,9 +1756,12 @@ const { sliderProps, startSelectorProps } = usePeriodSliderRange({ unit: "day",
1742
1756
  | `resetValue` | `() => void` | `initialValue` へ復帰 (いまの定義域へ収め、離散レールでは最近傍の候補へ寄せた日付) |
1743
1757
  | `selectorProps` | `SelectorProps` | セレクタ用 Props |
1744
1758
  | `sliderProps` | `PeriodSliderPointProps` | `<PeriodSlider {...sliderProps} />` へ渡す Props |
1759
+ | `duringRender` | `(action: () => void) => void` | ホストの描画の中で返す関数を呼ぶための関数。`action` の中で同期に呼んだ返す関数はその描画の中だけで働き、書き込みと通知はその確定で当たる (上の「共通: `SelectorProps`」)。ホスト自身の描画の中、フックを呼んだ後で呼ぶ (フックの最後の描画が確定した後と、本体を走らせた同期の処理が終わった後は `Error`、関数でない `action` は `TypeError`。検出しない誤用は上の「共通: `SelectorProps`」)。同一性はコンポーネントの存続中ずっと変わらない |
1745
1760
 
1746
1761
  #### `useVernierSliderRange(options)`
1747
1762
 
1763
+ **ノギスの操作は、動かすスケールだけをステートへ渡します** (`useVernierSliderRange` / `useVernierSliderPoint` に共通)。片方のスケールだけを動かす確定経路 (マクロ窓は `setMacroLowerDate` / `setMacroUpperDate`・`shiftMacroRange`・マクロのセレクタの `onChange` と ◀▶・`sliderProps.onChangeMacroRange`、ミクロ選択は `setMicroLowerDate` / `setMicroUpperDate` / `setMicroDate`・`shiftMicroRange` / `shiftMicroValue`・ミクロのセレクタの `onChange` と ◀▶・`sliderProps` のミクロのコールバック) は、もう片方のスケールの落ち着いた値が返す関数の読む値とも利用側が知っている値とも等しい間、そのスケールを渡さず通知もしません。そのため、`duringRender` で一方のスケールへ追従する移行の描画が譲っている間にもう一方だけを動かしても、追従した値はその確定で描かれて通知されます。利用側が別の値を知っているとき (収め直した値、緊急の確定が元の窓を描いた間も保留している窓の移行) は、操作が描いている値を渡し直して通知し、保存する値を最後に通知した値と揃えます。操作の結果もう片方のスケールも動くとき (窓の移動で置き直したミクロ選択、窓を追従させるミクロの ◀▶) と `resetVernier` は、両方のスケールを確定します。動かすスケールは、返す関数の読む値 (確定したもう片方のスケール) に照らして置きます。追従した値と動かした値の両方を持つ描画でミクロ選択が窓に収まらないときは、その描画が収め直しと同じくミクロ選択を置き直し (その場では通知しません)、その値は次にそれへ落ち着いた操作で通知されます。直接の更新関数 (`setMacroRange` / `setMicroRange` / `setMicroValue`) は自分のスケールだけを渡します。もう片方の操作はそのスケールを渡さないため、マウントの後にまだ何も渡していないスケールへ同じ値の確定経路を初めて呼ぶと、子の描画を省くホストの描画が 1 度走ります (上の「共通: `SelectorProps`」の同じ値の受け渡しと同じ)。
1764
+
1748
1765
  | オプション | 型 | 既定値 | 説明 |
1749
1766
  | :--- | :--- | :--- | :--- |
1750
1767
  | `unit` | `PeriodSliderUnit` | (必須) | 基本時間解像度単位。`"year"` / `"month"` / `"day"` 以外 (`null` を含む) は `RangeError` |
@@ -1779,6 +1796,7 @@ const { sliderProps, startSelectorProps } = usePeriodSliderRange({ unit: "day",
1779
1796
  | `microStartSelectorProps` | `SelectorProps` | ミクロ開始日セレクタ用 Props |
1780
1797
  | `microEndSelectorProps` | `SelectorProps` | ミクロ終了日セレクタ用 Props |
1781
1798
  | `sliderProps` | `PeriodSliderVernierRangeProps` | `<PeriodSlider {...sliderProps} />` へ渡す Props。本体がマクロ窓を動かしたとき (つまみ・`macro-connect`・ホイール・キーボード)、フックは窓だけを記録し、ミクロ選択は本体が操作ごとの規則で置き直して 1 度だけ通知した値になります (つまみ 1 本は縁で切り落とし、ホイールとキーボードは窓ごと運び、`macro-connect` は暦の差分だけ平行移動してから運ぶ)。包含は本体と同じくミクロ単位で判定するため、窓の端の単位の途中にある値 (12 月で終わる窓の 12 月 15 日) は書き換えません。利用側がまだ知らないミクロ選択 (初期値の寄せ・収め直しの結果) は、新しい窓のレールに載ったままのときだけ窓と一緒に通知します (窓の外の古い値を先に鳴らさない)。コールバックを直接呼んで Invalid Date を渡すと、`sliderProps.onChangeMicroRange(upper)` のように引数名を名乗る `RangeError` |
1799
+ | `duringRender` | `(action: () => void) => void` | ホストの描画の中で返す関数を呼ぶための関数。`action` の中で同期に呼んだ返す関数はその描画の中だけで働き、書き込みと通知はその確定で当たる (上の「共通: `SelectorProps`」)。ホスト自身の描画の中、フックを呼んだ後で呼ぶ (フックの最後の描画が確定した後と、本体を走らせた同期の処理が終わった後は `Error`、関数でない `action` は `TypeError`。検出しない誤用は上の「共通: `SelectorProps`」)。同一性はコンポーネントの存続中ずっと変わらない |
1782
1800
 
1783
1801
  #### `useVernierSliderPoint(options)`
1784
1802
 
@@ -1816,6 +1834,7 @@ const { sliderProps, startSelectorProps } = usePeriodSliderRange({ unit: "day",
1816
1834
  | `macroEndSelectorProps` | `SelectorProps` | マクロ終了日セレクタ用 Props |
1817
1835
  | `microSelectorProps` | `SelectorProps` | ミクロ時点セレクタ用 Props (`maxDate` は実効マクロ窓終端。`onChange` は `setMicroDate` そのもので、Invalid Date を関数名で拒む) |
1818
1836
  | `sliderProps` | `PeriodSliderVernierPointProps` | `<PeriodSlider {...sliderProps} />` へ渡す Props。本体がマクロ窓を動かしたとき、フックは窓だけを記録し、時点は本体が操作ごとの規則 (`macro-connect` では暦の差分だけ平行移動) で置き直して 1 度だけ通知した値になります。窓の端の単位の途中にある時点は書き換えません。利用側がまだ知らない時点は、新しい窓のレールに載ったままのときだけ窓と一緒に通知します。コールバックを直接呼んで Invalid Date を渡すと、引数名を名乗る `RangeError` |
1837
+ | `duringRender` | `(action: () => void) => void` | ホストの描画の中で返す関数を呼ぶための関数。`action` の中で同期に呼んだ返す関数はその描画の中だけで働き、書き込みと通知はその確定で当たる (上の「共通: `SelectorProps`」)。ホスト自身の描画の中、フックを呼んだ後で呼ぶ (フックの最後の描画が確定した後と、本体を走らせた同期の処理が終わった後は `Error`、関数でない `action` は `TypeError`。検出しない誤用は上の「共通: `SelectorProps`」)。同一性はコンポーネントの存続中ずっと変わらない |
1819
1838
 
1820
1839
  ## ライセンス
1821
1840
 
@@ -66,13 +66,13 @@ export interface DateSelectorProps {
66
66
  * Memo comparator of `DateSelector`: true only when every prop its output depends on is unchanged, never for a prop the render rejects.
67
67
  * `DateSelector` のメモ比較器 (描画結果が依存する Props がすべて不変のときだけ true。描画が拒否する Props では常に false)。
68
68
  *
69
- * Date props are compared by the day they fall in through `areSelectorDatePropsEqual`, so an invalid one on a re-render reaches the
70
- * render-time validation and throws the same named RangeError as on the first mount; the comparator itself never throws. When the
71
- * next render is `variant="split-dropdown"`, a date whose year starts outside the Date range keys to `NaN` (`splitDropdownDayStart`),
72
- * so the render that rejects it is not skipped either, including a controlled `initialDate` moved into such a year.
73
- * Date 型 Props は `areSelectorDatePropsEqual` で属する日として比べるため、再描画で渡した不正な値も描画時の検証へ届き、
69
+ * Date props are compared through `areSelectorDatePropsEqual` by `dayKey`, the day the validation reads, so an invalid one on a
70
+ * re-render reaches the render-time validation and throws the same named RangeError as on the first mount; the comparator itself never
71
+ * throws. When the next render is `variant="split-dropdown"`, a date whose year starts outside the Date range keys to `NaN`
72
+ * (`splitDropdownDayKey`), so the render that rejects it is not skipped either, including a controlled `initialDate` moved into such a year.
73
+ * Date 型 Props は `areSelectorDatePropsEqual` で `dayKey` (検証が読む日) により比べるため、再描画で渡した不正な値も描画時の検証へ届き、
74
74
  * 初回のマウントと同じく Props 名を名指す RangeError になる (比較器自身は例外を投げない)。今回の描画が `variant="split-dropdown"` なら、
75
- * 年の始まりが表現範囲の外にある日付のキーは `NaN` になり (`splitDropdownDayStart`)、制御中の `initialDate` をその年へ動かした描画も含め、
75
+ * 年の始まりが表現範囲の外にある日付のキーは `NaN` になり (`splitDropdownDayKey`)、制御中の `initialDate` をその年へ動かした描画も含め、
76
76
  * それを拒む描画も省かない。
77
77
  *
78
78
  * @param prev - Props of the previous render / 前回の描画の Props
@@ -85,11 +85,11 @@ export declare const areDateSelectorPropsEqual: (prev: DateSelectorProps, next:
85
85
  * `allowedDates` is compared by reference, so consumers memoize the array; `stepper` is compared field by field, and a render that adds or
86
86
  * removes it, or that switches between controlled and uncontrolled, is never skipped (the stepper has to be validated, and the
87
87
  * component has to change which owner it renders).
88
- * Date props go through `areSelectorDatePropsEqual`, so an invalid one on a re-render throws the same named RangeError as on the first mount,
89
- * and so does a date `variant="split-dropdown"` rejects for its year.
88
+ * Date props go through `areSelectorDatePropsEqual` by the key the validation's own function computes, so an invalid one on a re-render
89
+ * throws the same named RangeError as on the first mount, and so does a date `variant="split-dropdown"` rejects for its year.
90
90
  * 描画結果が依存する Props の変化時のみ再描画する日単位セレクタ。`allowedDates` は参照比較のため利用側でメモ化、`stepper` はフィールドごとに比較し、
91
91
  * 付け外しと、制御・非制御の切り替えは描画を省かない (引き受けを検証し、描く持ち主を切り替えるため)。
92
- * Date 型 Props は `areSelectorDatePropsEqual` で比べるため、再描画で渡した不正な値も、`variant="split-dropdown"` が年で拒む日付も、
92
+ * Date 型 Props は `areSelectorDatePropsEqual` で検証と同じ関数が求めるキーにより比べるため、再描画で渡した不正な値も、`variant="split-dropdown"` が年で拒む日付も、
93
93
  * 初回のマウントと同じ名指しの RangeError になる。
94
94
  */
95
95
  export declare const DateSelector: React.MemoExoticComponent<(props: DateSelectorProps) => React.JSX.Element>;
@@ -1 +1 @@
1
- {"version":3,"file":"DateSelector.d.ts","sourceRoot":"","sources":["../src/DateSelector.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAgB9B,OAAO,EAA0B,KAAK,0BAA0B,EAAE,KAAK,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAE3G,OAAO,EAAuD,KAAK,qBAAqB,EAA8C,MAAM,gBAAgB,CAAA;AAG5J,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAM5E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB;IAC9B,qJAAqJ;IACrJ,KAAK,CAAC,EAAE,IAAI,CAAA;IACZ,4UAA4U;IAC5U,WAAW,CAAC,EAAE,IAAI,CAAA;IAClB,sKAAsK;IACtK,QAAQ,CAAC,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAA;IAC3B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAA;IACrC,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC1B,+GAA+G;IAC/G,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,+GAA+G;IAC/G,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,gHAAgH;IAChH,OAAO,CAAC,EAAE,IAAI,CAAA;IACd,gHAAgH;IAChH,OAAO,CAAC,EAAE,IAAI,CAAA;IACd,gbAAgb;IAChb,YAAY,CAAC,EAAE,IAAI,EAAE,GAAG,SAAS,CAAA;IACjC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,gBAAgB,CAAA;IAChD,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAA;IAC3B,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,gOAAgO;IAChO,MAAM,CAAC,EAAE,kBAAkB,CAAA;IAC3B,uVAAuV;IACvV,MAAM,CAAC,EAAE,0BAA0B,CAAA;IACnC,0PAA0P;IAC1P,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mUAAmU;IACnU,YAAY,CAAC,EAAE,qBAAqB,CAAA;CACvC;AA2lBD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,yBAAyB,GAAI,MAAM,iBAAiB,EAAE,MAAM,iBAAiB,KAAG,OA2B5F,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,oCA/Za,iBAAiB,KAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CA+ZO,CAAA"}
1
+ {"version":3,"file":"DateSelector.d.ts","sourceRoot":"","sources":["../src/DateSelector.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAgB9B,OAAO,EAA0B,KAAK,0BAA0B,EAAE,KAAK,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAE3G,OAAO,EAA2E,KAAK,qBAAqB,EAA8C,MAAM,gBAAgB,CAAA;AAGhL,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAM5E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB;IAC9B,qJAAqJ;IACrJ,KAAK,CAAC,EAAE,IAAI,CAAA;IACZ,4UAA4U;IAC5U,WAAW,CAAC,EAAE,IAAI,CAAA;IAClB,sKAAsK;IACtK,QAAQ,CAAC,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAA;IAC3B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAA;IACrC,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC1B,+GAA+G;IAC/G,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,+GAA+G;IAC/G,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,gHAAgH;IAChH,OAAO,CAAC,EAAE,IAAI,CAAA;IACd,gHAAgH;IAChH,OAAO,CAAC,EAAE,IAAI,CAAA;IACd,gbAAgb;IAChb,YAAY,CAAC,EAAE,IAAI,EAAE,GAAG,SAAS,CAAA;IACjC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,gBAAgB,CAAA;IAChD,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAA;IAC3B,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,gOAAgO;IAChO,MAAM,CAAC,EAAE,kBAAkB,CAAA;IAC3B,uVAAuV;IACvV,MAAM,CAAC,EAAE,0BAA0B,CAAA;IACnC,0PAA0P;IAC1P,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mUAAmU;IACnU,YAAY,CAAC,EAAE,qBAAqB,CAAA;CACvC;AAonBD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,yBAAyB,GAAI,MAAM,iBAAiB,EAAE,MAAM,iBAAiB,KAAG,OA2B5F,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,oCA/Za,iBAAiB,KAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CA+ZO,CAAA"}
@@ -65,10 +65,11 @@ export interface MonthSelectorProps {
65
65
  * Memo comparator of `MonthSelector`: true only when every prop its output depends on is unchanged, never for a prop the render rejects.
66
66
  * `MonthSelector` のメモ比較器 (描画結果が依存する Props がすべて不変のときだけ true。描画が拒否する Props では常に false)。
67
67
  *
68
- * Date props are compared by the month they fall in through `areSelectorDatePropsEqual`, so an invalid one on a re-render reaches the
69
- * render-time validation and throws the same named RangeError as on the first mount; the comparator itself never throws.
70
- * Date 型 Props は `areSelectorDatePropsEqual` で属する月として比べるため、再描画で渡した不正な値も描画時の検証へ届き、
71
- * 初回のマウントと同じく Props 名を名指す RangeError になる (比較器自身は例外を投げない)。
68
+ * Date props are compared through `areSelectorDatePropsEqual` by `monthKey`, the month the validation and the render read, so an
69
+ * invalid one on a re-render reaches the render-time validation and throws the same named RangeError as on the first mount, and a
70
+ * skipped render draws the month a fresh mount would; the comparator itself never throws.
71
+ * Date 型 Props は `areSelectorDatePropsEqual` で `monthKey` (検証と描画が読む月) により比べるため、再描画で渡した不正な値も描画時の検証へ届き、
72
+ * 初回のマウントと同じく Props 名を名指す RangeError になり、省いた描画は新規のマウントと同じ月を描く (比較器自身は例外を投げない)。
72
73
  *
73
74
  * @param prev - Props of the previous render / 前回の描画の Props
74
75
  * @param next - Props of the next render / 今回の描画の Props
@@ -1 +1 @@
1
- {"version":3,"file":"MonthSelector.d.ts","sourceRoot":"","sources":["../src/MonthSelector.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAG9B,OAAO,EAA0B,KAAK,0BAA0B,EAAE,KAAK,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAC3G,OAAO,EAAsE,KAAK,qBAAqB,EAAuB,MAAM,gBAAgB,CAAA;AAGpJ,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAK5E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IAC/B,+GAA+G;IAC/G,KAAK,CAAC,EAAE,IAAI,CAAA;IACZ,wSAAwS;IACxS,WAAW,CAAC,EAAE,IAAI,CAAA;IAClB,sKAAsK;IACtK,QAAQ,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3C;;;;;OAKG;IACH,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAA;IACrC,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;IAC7B,oQAAoQ;IACpQ,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,sQAAsQ;IACtQ,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,+IAA+I;IAC/I,OAAO,CAAC,EAAE,IAAI,CAAA;IACd,+IAA+I;IAC/I,OAAO,CAAC,EAAE,IAAI,CAAA;IACd,2TAA2T;IAC3T,aAAa,CAAC,EAAE,IAAI,EAAE,GAAG,SAAS,CAAA;IAClC,wCAAwC;IACxC,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAA;IAC3B,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,0KAA0K;IAC1K,MAAM,CAAC,EAAE,kBAAkB,CAAA;IAC3B,2MAA2M;IAC3M,MAAM,CAAC,EAAE,0BAA0B,CAAA;IACnC,oPAAoP;IACpP,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mUAAmU;IACnU,YAAY,CAAC,EAAE,qBAAqB,CAAA;CACvC;AAwcD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,0BAA0B,GAAI,MAAM,kBAAkB,EAAE,MAAM,kBAAkB,KAAG,OA0B/F,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,oCApPa,kBAAkB,KAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAoPQ,CAAA"}
1
+ {"version":3,"file":"MonthSelector.d.ts","sourceRoot":"","sources":["../src/MonthSelector.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAG9B,OAAO,EAA0B,KAAK,0BAA0B,EAAE,KAAK,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAC3G,OAAO,EAAkG,KAAK,qBAAqB,EAAuB,MAAM,gBAAgB,CAAA;AAGhL,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAK5E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IAC/B,+GAA+G;IAC/G,KAAK,CAAC,EAAE,IAAI,CAAA;IACZ,wSAAwS;IACxS,WAAW,CAAC,EAAE,IAAI,CAAA;IAClB,sKAAsK;IACtK,QAAQ,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3C;;;;;OAKG;IACH,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAA;IACrC,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;IAC7B,oQAAoQ;IACpQ,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,sQAAsQ;IACtQ,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,+IAA+I;IAC/I,OAAO,CAAC,EAAE,IAAI,CAAA;IACd,+IAA+I;IAC/I,OAAO,CAAC,EAAE,IAAI,CAAA;IACd,2TAA2T;IAC3T,aAAa,CAAC,EAAE,IAAI,EAAE,GAAG,SAAS,CAAA;IAClC,wCAAwC;IACxC,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAA;IAC3B,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,0KAA0K;IAC1K,MAAM,CAAC,EAAE,kBAAkB,CAAA;IAC3B,2MAA2M;IAC3M,MAAM,CAAC,EAAE,0BAA0B,CAAA;IACnC,oPAAoP;IACpP,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mUAAmU;IACnU,YAAY,CAAC,EAAE,qBAAqB,CAAA;CACvC;AA6dD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,0BAA0B,GAAI,MAAM,kBAAkB,EAAE,MAAM,kBAAkB,KAAG,OA0B/F,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,oCArPa,kBAAkB,KAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAqPQ,CAAA"}
@@ -479,8 +479,16 @@ export declare const yearKeyOfCivil: (year: number, monthIndex: number, yearStar
479
479
  * Normalizes a date to the start of the specified unit.
480
480
  * 指定した単位 (year, month, day) の先頭に日付を正規化します。
481
481
  *
482
+ * Every unit reads d by its time value in the system time zone, through a plain copy, never through d's own getters: a Date
483
+ * subclass whose getters report another zone (a `TZDate` of `@date-fns/tz`, a `UTCDate` of `@date-fns/utc`) falls in the same
484
+ * unit as a plain Date of the same instant. This is the package's one reading of a Date; encode, keyInsideDateRange and every
485
+ * unit decision built on them (the body, the hooks, the three selectors) inherit it.
486
+ * どの単位も d を、自身のゲッターではなく時刻値のシステムのタイムゾーンでの読み (素の Date の複製) で読む。ゲッターが別のタイムゾーンを名乗る
487
+ * Date の派生クラス (`@date-fns/tz` の `TZDate`、`@date-fns/utc` の `UTCDate`) も、同じ時刻の素の Date と同じ単位に属する。これがパッケージの
488
+ * 唯一の Date の読み方で、encode・keyInsideDateRange とその上の単位の判定 (本体・フック・3 セレクタ) はすべてこれを継ぐ。
489
+ *
482
490
  * @param unit - Time resolution unit / 時間解像度単位
483
- * @param d - Date to normalize / 正規化対象の日付
491
+ * @param d - Date to normalize, read by its time value / 正規化対象の日付 (時刻値で読む)
484
492
  * @param yearStartMonth - Calendar month a `unit: "year"` period starts in, 0-based; 0 keeps the calendar year (default: 0) / `unit: "year"` の 1 年が始まる暦月 (0 始まり)。0 は暦年 (既定: 0)
485
493
  * @returns New Date pinned to the start of the unit / 単位先頭に揃えた新しい Date
486
494
  * @throws RangeError when unit is not "year", "month" or "day", judged first (`normalizeDateByUnit: unit must be one of "year", "month", "day" (received: ...)`), when d is absent or an Invalid Date, or when yearStartMonth is not an integer in [0, 11] / unit が "year"・"month"・"day" でない場合 (最初に判定)、d が未指定または Invalid Date の場合、yearStartMonth が 0 以上 11 以下の整数でない場合
@@ -491,7 +499,7 @@ export declare const normalizeDateByUnit: (unit: PeriodSliderUnit, d: Date, year
491
499
  * 日付を比較用数値キーにエンコードします。
492
500
  *
493
501
  * @param unit - Time resolution unit / 時間解像度単位
494
- * @param d - Date to encode / エンコード対象の日付
502
+ * @param d - Date to encode, read by its time value in the system time zone (normalizeDateByUnit) / エンコード対象の日付 (時刻値をシステムのタイムゾーンで読む。normalizeDateByUnit)
495
503
  * @param yearStartMonth - Calendar month a `unit: "year"` period starts in, 0-based; 0 keeps the calendar year (default: 0) / `unit: "year"` の 1 年が始まる暦月 (0 始まり)。0 は暦年 (既定: 0)
496
504
  * @returns Integer key that is strictly monotonic in time for the given unit / 単位ごとに時間について厳密単調な整数キー
497
505
  * @throws RangeError when unit is not "year", "month" or "day", judged first (`encode: unit must be one of "year", "month", "day" (received: ...)`), when d is absent or an Invalid Date, or when yearStartMonth is not an integer in [0, 11] / unit が "year"・"month"・"day" でない場合 (最初に判定)、d が未指定または Invalid Date の場合、yearStartMonth が 0 以上 11 以下の整数でない場合
@@ -584,8 +592,13 @@ export declare const keyInsideDateRange: (date: Date, unit: PeriodSliderUnit, ye
584
592
  * 月・年の加算は shiftCivilMonths に従い年月日を 1 度で書くため、表現範囲の最後の月への加算も月末日からその日付を返す。
585
593
  * Invalid Date になるのは和そのものが Date の表現範囲を越えるときだけ。
586
594
  *
595
+ * The calendar fields are read from a plain copy of d's time value in the system time zone, as normalizeDateByUnit reads them,
596
+ * so a Date subclass whose getters report another zone steps from the same date as a plain Date of the same instant.
597
+ * 暦の欄は normalizeDateByUnit と同じく d の時刻値の複製からシステムのタイムゾーンで読むため、ゲッターが別のタイムゾーンを名乗る Date の派生クラスも、
598
+ * 同じ時刻の素の Date と同じ日付から進む。
599
+ *
587
600
  * @param unit - Time resolution unit to step by / 加減算する時間解像度単位
588
- * @param d - Base date / 起点日付
601
+ * @param d - Base date, read by its time value / 起点日付 (時刻値で読む)
589
602
  * @param amount - Signed whole number of units to add / 加減算する整数の単位数 (符号付き)
590
603
  * @returns New Date advanced by amount units, or an Invalid Date when the sum lies past the Date range / amount 単位進めた新しい Date (和が Date の表現範囲を越える場合は Invalid Date)
591
604
  * @throws RangeError when unit is not "year", "month" or "day", judged first (`addUnit: unit must be one of "year", "month", "day" (received: ...)`), when d is absent or an Invalid Date (`addUnit: d must be a valid Date (received: ...)`), or when amount is not an integer (`addUnit: amount must be an integer number of units (received: ...)`) / unit が "year"・"month"・"day" でない場合 (最初に判定)、d が未指定または Invalid Date の場合、amount が整数でない場合
@@ -646,6 +659,8 @@ export declare const getMacroWindowStartDate: (macroUnit: PeriodSliderUnit, micr
646
659
  * (年の末尾は 12 月ではなく `yearStartMonth` から数えて 12 番目の月。現地 0 時、0 時の無い日はその日の最初の瞬間)。
647
660
  * 最後の単位はキーで数えるため、0-99 年は自分の年のまま、始まりが表現範囲の外にある期間も最後の単位を返す。
648
661
  * それ以外の組では d 自身のミクロ単位の始まり。
662
+ * d is read by its time value in the system time zone (a plain copy), as normalizeDateByUnit reads it.
663
+ * d は normalizeDateByUnit と同じく時刻値の複製からシステムのタイムゾーンで読む。
649
664
  *
650
665
  * @param macroUnit - Macro scale unit / マクロ側の時間解像度単位
651
666
  * @param microUnit - Micro scale unit / ミクロ側の時間解像度単位
@@ -719,7 +734,7 @@ export interface PeriodQuarter {
719
734
  * 四半期の境界は `yearStartMonth` を 3 で割った剰余だけで決まり、番号は `yearStartMonth` そのもので決まる。
720
735
  * 0・3・6・9 では境界が暦四半期と一致して番号だけがずれ、他の 8 通りでは境界自体が動く。
721
736
  *
722
- * @param d - Date to classify / 判定対象の日付
737
+ * @param d - Date to classify, read by its time value in the system time zone (a plain copy), as normalizeDateByUnit reads it / 判定対象の日付 (normalizeDateByUnit と同じく時刻値の複製をシステムのタイムゾーンで読む)
723
738
  * @param yearStartMonth - Calendar month a year starts in, 0-based; required, so the calendar year is never assumed / 1 年が始まる暦月 (0 始まり)。必須であり暦年を暗黙に仮定しない
724
739
  * @returns Quarter coordinates of the date / 日付の四半期座標
725
740
  * @throws RangeError when d is absent or an Invalid Date, or when yearStartMonth is not an integer in [0, 11] / d が未指定または Invalid Date の場合、yearStartMonth が 0 以上 11 以下の整数でない場合
@@ -753,6 +768,10 @@ export declare const formatIsoYear: (year: number) => string;
753
768
  * into a generic package, and Intl output drifts between ICU versions.
754
769
  * 解決順序は customFormat が最優先、次に formatLocale 指定時の Intl.DateTimeFormat、未指定時はロケール非依存の ISO 8601。
755
770
  * ISO 表記は本パッケージの仕様上の既定値であり代替値ではない (自然言語既定は汎用パッケージに 1 言語を焼き付け、Intl 出力は ICU 版で揺れるため)。
771
+ * Both built-in tiers read d by its time value in the system time zone, so a Date subclass whose getters report another zone is
772
+ * labelled as a plain Date of the same instant; customFormat receives d as passed.
773
+ * 組み込みの 2 段はどちらも d を時刻値のシステムのタイムゾーンで読むため、ゲッターが別のタイムゾーンを名乗る Date の派生クラスも、同じ時刻の
774
+ * 素の Date と同じ表記になる (customFormat には渡された d をそのまま渡す)。
756
775
  *
757
776
  * @param unit - Time resolution unit deciding the precision / 精度を決める時間解像度単位
758
777
  * @param d - Date to format / 書式化対象の日付