@aiquants/period-slider 0.16.0 → 0.17.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 (39) hide show
  1. package/CHANGELOG.md +215 -0
  2. package/README.md +55 -30
  3. package/dist/DateSelector.d.ts +2 -2
  4. package/dist/DateSelector.d.ts.map +1 -1
  5. package/dist/MonthSelector.d.ts +2 -2
  6. package/dist/MonthSelector.d.ts.map +1 -1
  7. package/dist/PeriodSlider.d.ts +235 -40
  8. package/dist/PeriodSlider.d.ts.map +1 -1
  9. package/dist/YearSelector.d.ts +4 -2
  10. package/dist/YearSelector.d.ts.map +1 -1
  11. package/dist/index.cjs +1 -1
  12. package/dist/index.js +2459 -2340
  13. package/dist/inputValue.d.ts +90 -21
  14. package/dist/inputValue.d.ts.map +1 -1
  15. package/dist/selectorMemo.d.ts +14 -0
  16. package/dist/selectorMemo.d.ts.map +1 -1
  17. package/dist/selectorStep.d.ts +13 -10
  18. package/dist/selectorStep.d.ts.map +1 -1
  19. package/dist/useCommittedRef.d.ts +80 -0
  20. package/dist/useCommittedRef.d.ts.map +1 -0
  21. package/dist/usePeriodSlider.d.ts +42 -18
  22. package/dist/usePeriodSlider.d.ts.map +1 -1
  23. package/dist/useUncontrolledSelection.d.ts +27 -0
  24. package/dist/useUncontrolledSelection.d.ts.map +1 -0
  25. package/dist/vernierStep.d.ts +10 -1
  26. package/dist/vernierStep.d.ts.map +1 -1
  27. package/package.json +1 -1
  28. package/src/DateSelector.tsx +15 -17
  29. package/src/MonthSelector.tsx +11 -15
  30. package/src/PeriodSlider.tsx +430 -148
  31. package/src/YearSelector.tsx +20 -13
  32. package/src/inputValue.ts +151 -21
  33. package/src/selectorMemo.ts +18 -3
  34. package/src/selectorStep.ts +24 -29
  35. package/src/useCommittedRef.ts +206 -0
  36. package/src/usePeriodSlider.ts +342 -208
  37. package/src/useUncontrolledSelection.ts +54 -0
  38. package/src/valueSet.ts +1 -1
  39. package/src/vernierStep.ts +12 -10
package/CHANGELOG.md CHANGED
@@ -4,6 +4,221 @@ 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.17.0 (2026-10-01)
8
+
9
+ 候補の一覧 (`allowedDates` / `allowedYears` / `allowedMonths` / `macroAllowedDates` / `microAllowedDates`) が一覧かどうかを 1 つの規則で判定し、
10
+ 拒否メッセージが所有者と読んだ一覧を名乗るようにした版です。あわせて、単位の始まりが Date の表現範囲の外にある日付 (`new Date(-8.64e15)` など、
11
+ 表現範囲の最初の単位の日付) を、本体・4 つのフック・公開の純関数 (`getSortedAllowedDates` / `resolveMacroWindow` / `resolveSelectorSteps` /
12
+ `resolveVernierSelectorSteps`) が Invalid Date と同じく名指しで拒否します。
13
+ 4 つのフックと `useSelectorStepper` の返す関数は、最後に確定した描画の値だけを読みます (`startTransition` で渡したオプションが保留している間の誤りを直します)。
14
+ 3 セレクタは非制御の `initialDate` を、確定後のエフェクトではなく描画のうちに取り込みます。
15
+ 計算で Date の表現範囲を越える日付 (フックのシフトの和・`macro-connect` のパンで運ぶミクロ選択・マクロ窓の末尾) は、進む向きの定義域の端の外にあるものとして扱い、
16
+ 表現範囲の最後のマクロ期間へ届く窓も描けるようにし、0-99 年の窓が期間の末日で閉じるようにしました。
17
+ **新しい Props・オプションを渡さないホストでも、下の「変更」の各点で挙動が変わります**
18
+ (配列でない一覧 (`null`・単独の Date など) を渡しているホスト、ノギスの行の一覧に `null` を渡して共有の `allowedDates` を継がせていたホスト、
19
+ `minDate` に `new Date(-8.64e15)` のような番兵を渡しているホスト、表現範囲の最初の単位の日付をフックへ渡して定義域の端へクランプさせていたホスト、
20
+ 描画中にフックの返す関数を呼んで Props に追従しているホスト、
21
+ 非制御のセレクタの `initialDate` を同じ日・月・年の中で動かして利用者の選択を戻させていたホスト、`addUnit` へ整数でない `amount` を渡しているホスト、
22
+ 0-99 年の窓を描くノギス、セレクタの確定や `formatOption` の呼び出しを数えるテスト、
23
+ 候補の拒否メッセージや配列を含む拒否メッセージの文言を照合するテスト、`getMacroWindowStartDate` / `getMacroWindowEndDate` / `findNearestDateIndex` の `normalizeDateByUnit` の文言や Invalid Date の戻り値を照合するテスト、
24
+ 表現範囲の端でのフックのシフトの送出を照合するテスト)。
25
+
26
+ ### 変更
27
+
28
+ - **配列でない候補の一覧は、本体・フック・`getSortedAllowedDates` でも名指しの `RangeError` になります**。省略は `undefined` だけで、
29
+ `null`・単独の Date・文字列・配列風のオブジェクト・取り消した Proxy は指定値として拒否します (`PeriodSlider: allowedDates must be an array of Dates (received: null)`、
30
+ `usePeriodSliderRange: ...`、`getSortedAllowedDates: ...`)。これまで本体 (全モード) と `usePeriodSliderRange` / `usePeriodSliderPoint`、ノギスのフックの離散の行は
31
+ 黙って連続のレール (と連続の ◀▶) になり、`getSortedAllowedDates` は `[]` を返していました。ノギスのフックに行の 1 歩の規則を渡していた場合は、内部の関数名
32
+ (`resolveVernierSelectorSteps: microAllowedDates must be an array of Dates (...)`) で落ちていました。空配列の意味は変わらず (レールと 1 歩の関数は連続、
33
+ `resolveSelectorSteps` は押せる向きなし)、離散のフラグが降りている行はこれまでどおり一覧を読みません。
34
+ - **ノギスの行が共有の `allowedDates` を継ぐのは、行の一覧 (`macroAllowedDates` / `microAllowedDates`) を省略 (`undefined`) したときだけです**。`null` は行自身の
35
+ 一覧として拒否します (`PeriodSlider: microAllowedDates must be an array of Dates (received: null)`)。これまでは `undefined` と同じく共有の一覧を継いでいました。
36
+ - **本体とフックの候補の拒否メッセージは、所有者と読んだ一覧を名乗ります**。`getSortedAllowedDates: allowedDates[3] must be a valid Date (...)` は
37
+ `PeriodSlider: microAllowedDates[3] must be a valid Date (...)` のように、`getSortedAllowedDates: every allowedDates entry falls outside ...` は
38
+ `useVernierSliderRange: every macroAllowedDates entry falls outside ...` のようになります。共有の一覧を継いだ行は、その行も名乗ります
39
+ (`useVernierSliderRange: allowedDates[3] (inherited by the micro row) must be a valid Date (...)`)。本体は共有の `allowedDates` をモードやフラグに依らず
40
+ `unit` でも行より先に読むため、形の誤り・有効な Date でない要素・`unit` での拒否は行の名なしで報告し (`PeriodSlider: allowedDates[3] ...`)、本体で行の名が
41
+ 付くのは `unit` では通るのに行の単位で拒否される場合 (より細かい行の単位でだけの全滅と、より粗い行の単位の始まりが Date の表現範囲の外にある要素。
42
+ `PeriodSlider: allowedDates[0] (inherited by the macro row) must fall in a month that starts inside the Date range (...)`) です。
43
+ `getSortedAllowedDates` を直接呼んだときのメッセージは、配列でない指定値の拒否と、単位の始まりが Date の表現範囲の外にある境界・要素の拒否 (下記) が
44
+ 加わり、有効な Date でない境界の拒否が自身の名を名乗り (下記)、受け取った値が配列である要素の示し方が次項の規則に変わるほかは変わりません。
45
+ - **拒否メッセージが受け取った配列は、要素ごとに示します**。`[e0, e1, e2, ... n more]` の形で先頭の 3 要素までを示し、Date は ISO 8601、文字列は引用符付き、
46
+ 穴は `empty`、配列である要素は `Array(長さ)`、読み出しが投げる要素はその要素だけを `an object that cannot be converted to a string` とします。これまでは `String()` の形
47
+ (Date はタイムゾーン依存の `Mon Jan 01 2024 09:00:00 GMT+0900 ...`、`null`・`undefined`・穴は空、`[3]` は `3` と同じ表記、自身を含む配列は空文字) でした。
48
+ タプルの形のエラー (`PeriodSlider: defaultRange must be a [start, end] Date tuple (received: [...])` など) を含め、配列を受け取るすべての拒否メッセージが変わります
49
+ (`labels` / `locale` の検証はエンジンの形のまま)。
50
+
51
+ - **単位の始まりが Date の表現範囲の外にある `minDate` は、本体と 4 つのフックで名指しの `RangeError` になります**
52
+ (`PeriodSlider: minDate must fall in a day that starts inside the Date range (received: -271821-04-20T00:00:00.000Z); minDate is required, so pass the earliest date to offer instead of a sentinel for "no bound"`)。
53
+ 判定する単位は平レールが `unit`、ノギス (本体とフック) が `macroUnit`・`microUnit`・`unit` で、最初に外れた単位を名乗ります。`new Date(-8.64e15)` は
54
+ 月と年ではどの時間帯でも、日では UTC 以外で該当し、年の始まりは `yearStartMonth` と共に動きます。これまで本体の平レールは `aria-valuemin="NaN"` のまま描画し、
55
+ ノギスは `resolveMacroWindow: macroRange[0] must be a valid Date (received: Invalid Date)` で、`unit` が両レールより粗いノギスは
56
+ `normalizeDateByUnit: d must be a valid Date (received: Invalid Date)` で落ち、フックは黙って受け取って `sliderProps` とセレクタ Props へ渡していました。
57
+ `unit` が両レールより粗いノギスでは、`minDate` が表現範囲の最初の `unit` の期間にあれば、選択が後の期間にあって描画できていた構成も拒否されます。
58
+ UTC の日の単位のように始まりが範囲に入る場合は、これまでどおり定義域の判定を受けます。救済の文を添えるのは `minDate` のメッセージだけです。
59
+ - **本体の選択 Props と候補の要素も、描く単位で同じ規則により名指しします**。`value` / `defaultValue` / `range[i]` / `defaultRange[i]` (`unit`)、
60
+ `microRange[i]` / `defaultMicroRange[i]` / `microValue` / `defaultMicroValue` (`microUnit`) は、定義域の内包の判定より先に
61
+ `PeriodSlider: <Props 名> must fall in a <単位> that starts inside the Date range (received: ...)` になります (これまで `normalizeDateByUnit: d must be a valid Date (received: Invalid Date)`)。
62
+ `macroRange[0]` (`macroUnit`) も同じ形です (これまで `resolveMacroWindow: macroRange[0] must be a valid Date (received: Invalid Date)`)。`macroRange` のはみ出しは、
63
+ `macroRange[0]` のマクロ単位の始まりが範囲に入る限りこれまでどおり許されます。候補の一覧の要素は、所有者と一覧を名乗って
64
+ `PeriodSlider: allowedDates[1] must fall in a month that starts inside the Date range (...)` のようになります (これまで `normalizeDateByUnit: ...`)。
65
+ - **`getSortedAllowedDates` は、空でない一覧に対して単位の始まりが範囲の外にある `minDate` / `maxDate` を拒否します**
66
+ (`getSortedAllowedDates: minDate must fall in a month that starts inside the Date range (received: ...)` / `... maxDate ...`)。これまではその側のキーが `NaN` になって
67
+ 絞り込みが黙って外れ、正常に返っていました (`maxDate` が表現範囲の最初の単位にあると、`maxDate` より後の候補まで返していました)。要素は
68
+ `getSortedAllowedDates: allowedDates[i] must fall in a <単位> that starts inside the Date range (...)` です (これまで `normalizeDateByUnit: ...`)。
69
+ 有効な Date でない `minDate` / `maxDate` も、空でない一覧に対して `getSortedAllowedDates: minDate must be a valid Date (received: Invalid Date)` と自身の名で
70
+ 拒否します (これまで `normalizeDateByUnit: d must be a valid Date (received: Invalid Date)`。空の一覧はこれまでどおり境界を読まずに `[]` を返します)。
71
+ - **`resolveMacroWindow` は `macroRange[0]` を `macroUnit` と `microUnit` の両方で、`maxDate` を `microUnit` で判定します** (窓の開始をこの 2 つの単位で畳むため。
72
+ `resolveMacroWindow: macroRange[0] must fall in a month that starts inside the Date range (...)`、これまで `normalizeDateByUnit: ...`)。`maxDate` を判定するのは、
73
+ 窓の端を `maxDate` へクランプしてから `microUnit` で畳むためです (`resolveMacroWindow: maxDate must fall in a month that starts inside the Date range (...)`。
74
+ これまでは `maxDate` が表現範囲の最初のミクロ単位にあると、送出せずに Invalid Date の窓を返していました)。`minDate` は判定しません (`minDate` へクランプするのは、
75
+ 範囲に入るミクロ単位の始まりである窓の端より後にあるときだけのため)。
76
+ - **`resolveVernierSelectorSteps` は、`macroUnit` または `microUnit` の始まりが Date の表現範囲の外にある `minDate` を名指しで拒否します**
77
+ (`resolveVernierSelectorSteps: minDate must fall in a month that starts inside the Date range (received: ...)`。`macroUnit` を先に判定)。これまでは
78
+ `minDate` の符号化キーが `NaN` のまま 1 歩を解いていました。`maxDate` は厳密に後にあるため判定しません。
79
+ - **フックの初期値・入口・状態も、時刻でクランプせず名指しで拒否します**。`initialRange` / `initialValue` (`unit`)・`initialMacroRange` (`macroUnit`)・
80
+ `initialMicroRange` / `initialMicroValue` (`microUnit`) は毎描画で (マウント時の定義域の照合より先に)、平レールの `setLowerDate` / `setUpperDate` /
81
+ `selectorProps.onChange` / `sliderProps.onChangeRange` / `sliderProps.onChangePoint` (`unit`)、ノギスの `setMacroLowerDate` / `setMacroUpperDate` /
82
+ `sliderProps.onChangeMacroRange` (`macroUnit`)、`setMicroLowerDate` / `setMicroUpperDate` / `setMicroDate` / `sliderProps.onChangeMicroRange` /
83
+ `sliderProps.onChangeMicroPoint` (`microUnit`) は呼び出し時に、`setRange` / `setValue` / `setMacroRange` / `setMicroRange` / `setMicroValue` で書いた値は次の描画で、
84
+ `<フック名>: <名前> must fall in a <単位> that starts inside the Date range (received: ...)` になります。これまでは、黙って `minDate` や窓の端へクランプされるか、
85
+ 内部の関数の名 (`normalizeDateByUnit` / `clampPairIntoDrawnValues: low must be a finite integer (received: NaN)` /
86
+ `drawnValuesNearest: value must be a finite integer (received: NaN)`) で落ちるか、連続レールの時点では値を窓と定義域の外のまま保持していました。
87
+ 0.16.0 の「変更」(3) の `drawnValuesNearest` の送出は、こうして入口や Props の名指しの拒否に置き換わります。
88
+ - **フックの返す関数を描画中に呼ぶと、描画中の値ではなく最後に確定した描画の値を読みます**。4 つのフックと `useSelectorStepper` の返す関数
89
+ (設定関数・シフト・リセット・`sliderProps` / `SelectorProps` のコールバック・◀▶ の `onStep`) が読む境界・候補・コールバック・ステートは、確定の段階で写した値です
90
+ (下の「修正」)。Props に追従するため自分の描画中に設定関数を呼ぶホストでは、同じ描画で広げた `maxDate` ではなく前の確定の `maxDate` で収めます。
91
+ これまでは描画中の値を読んでいました。同じ描画の値で収めるには、副作用 (`useEffect` / `useLayoutEffect`) かイベントハンドラの中で呼んでください。
92
+ フック自身の値と比べて描画のたびに呼ぶ追従は、値が境界・候補・窓へ置き直される場合も、これまでどおり置き直した値で落ち着きます。
93
+
94
+ - **3 セレクタは非制御の `initialDate` を描画のうちに取り込みます**。取り込むのは、非制御になった描画 (マウントと、制御から非制御への切り替え) と、
95
+ `initialDate` が最後に取り込んだものと別の単位 (`DateSelector` は日、`MonthSelector` は月、`YearSelector` は `yearStartMonth` で区切った年。
96
+ `yearStartMonth` を変えた描画も含む) へ動いた描画で、その描画の最初の確定から取り込んだ値を描きます。取り込みは `onChange` を呼びません。
97
+ これまでは確定後のエフェクトで取り込んでいたため、その描画の確定は古い選択 (制御でマウントしていればマウント時の `value`、制御の前に非制御だったなら
98
+ そのときの選択) を描き (`DateSelector variant="dropdown"` の畳んだ表示と `MonthSelector variant="dropdown"` の集合外プレースホルダは古い日付で `formatOption` を呼び、
99
+ `YearSelector` は `yearStartMonth` の変更で `initialDate` を含まない年を選択中として描き)、取り込みのための確定がもう 1 回続いていました。
100
+ - **同じ単位の中で `initialDate` を動かしても、利用者の選択は置き換わりません**。これまでは時刻が動くと、メモ比較器が描画を省かなかったとき
101
+ (ほかの Props も変わった描画) だけ、◀▶・選択肢・入力で選んだ値が `initialDate` の単位へ戻りました (`initialDate={new Date()}` と描画ごとに作る `onChange` を
102
+ 渡すホストでは、親の再描画のたびに戻っていました)。別の単位への移動は、これまでどおり利用者の選択を置き換えます。
103
+ - 取り込む描画と、非制御から制御へ切り替える描画では、セレクタの本体が 2 回走ります (描画中の状態更新による再実行。確定は 1 回)。本体で呼ぶ `formatOption`
104
+ (`DateSelector variant="dropdown"` の畳んだ表示と `MonthSelector variant="dropdown"` の集合外プレースホルダ) は、その描画で同じ引数のまま 2 回呼ばれ得ます
105
+ (`DateSelector variant="dropdown"` を制御へ切り替える描画は 1 回から 2 回。集合の外の値を描く `MonthSelector variant="dropdown"` のプレースホルダは、
106
+ 制御へ切り替える描画と、保持中と同じ月の `initialDate` のまま非制御へ戻す描画で 1 回から 2 回)。非制御の `DateSelector` のマウントは 1 回の確定で済み (これまでは 2 回、
107
+ `variant="dropdown"` では 3 回)、`variant="dropdown"` の畳んだ表示の `formatOption` もマウントで 1 回になります (これまでは同じ日で 2 回)。`variant="dropdown"` の
108
+ コンボボックス内部の確定 (`formatOption` も `onChange` も呼ばない) 1 回は、マウントからマウント後の最初の更新 (どの更新でも) へ移ります (確定の総数は減ります)。
109
+
110
+ - **`addUnit` は表現範囲の最後の月 (275760 年 9 月) へ届く月・年の加算で正しい日付を返し、整数でない `amount` を拒否します**。
111
+ `addUnit("month", 275760-08-01, 1)` は 275760-09-01、`addUnit("year", 275759-09-12, 1)` は 275760-09-12 です (これまで Invalid Date)。Invalid Date を返すのは、
112
+ 和そのものが表現範囲を越えるとき (275760-08-31 の 1 か月後など) だけです。小数・`NaN`・`Infinity` は
113
+ `addUnit: amount must be an integer number of units (received: 1.5)` の `RangeError` になります。これまでは単位と日付によって別の向きへ切り捨てるか
114
+ (6 月の -1.5 か月は -2 か月、1 月の -1.5 か月は -1 か月、+1.5 日は +1 日)、Invalid Date を返していました。通常の入力の結果 (月末丸め・現地の時刻の保持) は変わりません。
115
+ ただし、加算先の月の末日の、元の日付と同じ現地時刻が夏時間の開始で飛ばされる場合 (Europe/Moscow の 1918-05-31・1919-05-31) は、これまで翌月の日付
116
+ (1919-08-15 22:00 の 15 か月前は 1918-06-01 00:00) を返していたのに対し、加算先の月の日付 (1918-05-15 22:00) を返します。
117
+ - **`getMacroWindowEndDate` は最後のミクロ単位をキーで数えます**。月 × 日は 0-99 年でもその年の月末日を返します (`0050-06-15` は `0050-06-30`。これまで `1950-06-30`)。
118
+ 開始月 8 の 275759 年の年 × 日は `275760-08-31` (これまで `normalizeDateByUnit: d must be a valid Date (received: Invalid Date)`)、開始月 9 の 275759 年の年 × 月は
119
+ `275760-09-01` (これまで Invalid Date) です。最後のミクロ単位の始まりが表現範囲の外にある期間 (275760 年 9 月の月 × 日、275760 年 9 月を含む年の年 × 日、275760 年 9 月より後の月で終わる年の年 × 月 (`yearStartMonth = 9` 以外の、275760 年 9 月を含む年)) は
120
+ `getMacroWindowEndDate: d must fall in a month whose last day starts inside the Date range (received: ...)` (年は `a year whose last day` / `a year whose last month`) の
121
+ `RangeError` です (これまでは黙って Invalid Date を返すか、`normalizeDateByUnit: ...` で落ちていました)。年 × 月は、年の初日に現地 0 時の無い時間帯でも末尾の月の
122
+ 現地 0 時を返します (Europe/Moscow の 1981-1984 年の開始月 3、America/Havana の 2012 年の開始月 3、America/Santiago の 1928 年・1932 年の開始月 8 など。
123
+ これまでは 1 時。America/Santiago の 1927 年の開始月 8 では 0 時 42 分)。始まりが表現範囲の外にある最初の年も、範囲に入る末尾の月・日を返します
124
+ (`new Date(-8.64e15)` の年 × 月は -271821-12-01、年 × 日は -271821-12-31。これまで Invalid Date / `normalizeDateByUnit: ...`)。月 × 日の下端 (-271821-04-30) は変わりません。
125
+ 同じ単位の組とマクロ単位のほうが細かい組は、これまでどおり `d` 自身のミクロ単位の始まりを返し、その始まりが表現範囲の外にある `d` を
126
+ `getMacroWindowEndDate: d must fall in a month that starts inside the Date range (received: ...)` で拒否します (これまでは黙って Invalid Date を返していました。
127
+ `new Date(-8.64e15)` は年 × 年・月 × 月・月 × 年・日 × 月・日 × 年ではどの時間帯でも、日 × 日では UTC 以外で該当します)。
128
+ - **マクロ窓が Date の表現範囲の最後のマクロ期間 (275760 年 9 月、またはそれを含む年) へ届いても解決します**。`resolveMacroWindow` は、末尾の期間が `maxDate` の期間か
129
+ それより後のとき、期間の末尾を組まずに `maxDate` のミクロ単位の始まりで窓を閉じます (末尾を組める窓では結果は変わりません)。これまでは `maxDate` が 275760-09-12 のような
130
+ 通常の日付でも `normalizeDateByUnit: d must be a valid Date (received: Invalid Date)` で落ちていたため、マクロ単位がミクロ単位より粗い `mode="vernier"` の本体は描画で、
131
+ `useVernierSliderRange` / `useVernierSliderPoint` はマウントで (`macroSelectorStep` / `microSelectorStep` を渡すと、1 歩の行き先の窓を解くため最後の期間の 1 つ手前の窓でも)、
132
+ `shiftMacroRange` は最後の期間へのシフトで (`resolveMacroWindow: macroRange[0] must be a valid Date (received: Invalid Date)`)、`resolveVernierSelectorSteps` は
133
+ 行き先の窓で落ちていました。月 × 日の 0-99 年の窓は期間の末日で閉じます (下の「修正」)。
134
+ - **4 つのフックのシフトは、和が Date の表現範囲を越えても Invalid Date を通知せず、通常の境界を越えた和と同じく止まるか中止します**
135
+ (表現範囲の両端で、どの時間帯でも、日・月・年のどの単位でも)。`shiftRange` / `shiftValue` は `minDate` / `maxDate` に着いて止まります (これまでは
136
+ `onChangeRange` / `onChangePoint` を Invalid Date で呼び、次の描画が `<フック名>: range[i] is required and must be a valid Date (received: Invalid Date)` /
137
+ `... value ...` で落ちていました)。`shiftMacroRange` (2 つのノギスのフック) と `shiftMicroRange` は、ステートを変えずコールバックも呼ばずに中止します
138
+ (これまで `normalizeDateByUnit: ...`・`resolveMacroWindow: macroRange[i] must be a valid Date (received: Invalid Date)`・
139
+ `clampPairIntoDrawnValues: low must be a finite integer (received: NaN)` で落ちていました)。`shiftMicroValue` は進む向きの窓の端へ着きます (これまでは落ちるか、
140
+ 次の描画が `useVernierSliderPoint: microValue must fall in a <単位> that starts inside the Date range` で拒む値を保持していました)。
141
+ - **`macro-connect` のパンは、暦の差分で表現範囲の外へ出たミクロ選択もキーのまま運び、長さを保って窓へ収めます**。`[275760-08-20, 08-31]` を 1 か月運ぶと
142
+ 9 月 20 日〜30 日になり、その長さのまま窓の末尾へ寄って `[最後の日の 10 日前, 最後の日]` になります。この経路はこれまで描画が先に落ちるため到達できず、
143
+ 到達すればポインターのハンドラから送出していました。通常のパンの結果 (月末丸め。1 月 31 日の 1 か月後は 2 月末日) は変わりません。
144
+ - **`findNearestDateIndex` と `getMacroWindowStartDate` は自分の引数を自分の名前で拒否します**。2 要素以上の一覧に対し、`findNearestDateIndex` は有効な Date でない `target` を
145
+ `findNearestDateIndex: target must be a valid Date (received: Invalid Date)`、単位の始まりが表現範囲の外にある `target` を
146
+ `findNearestDateIndex: target must fall in a month that starts inside the Date range (received: ...)` で拒否します (これまで
147
+ `normalizeDateByUnit: d must be a valid Date (received: Invalid Date)` / `(received: undefined)`)。0 要素・1 要素の一覧はこれまでどおり `target` を読まずに `0` を返します。
148
+ `getMacroWindowStartDate` は `d` の `macroUnit`・`microUnit` の始まりが表現範囲の外なら、この順に判定して
149
+ `getMacroWindowStartDate: d must fall in a month that starts inside the Date range (received: ...)` で拒否します (これまで
150
+ `normalizeDateByUnit: d must be a valid Date (received: Invalid Date)` で落ちるか、マクロ単位がミクロ単位より細かい組では Invalid Date を返していました)。
151
+
152
+ ### 修正
153
+
154
+ - **3 セレクタは配列でない `allowedDates` / `allowedYears` / `allowedMonths` を、Props 名を名乗る `RangeError` で拒否します**
155
+ (`DateSelector: "allowedDates" must be an array of Dates (received null)`、`` YearSelector: `allowedYears` must be an array of Dates, received null. ``、
156
+ `` MonthSelector: `allowedMonths` must be an array of Dates, received null. ``)。これまでは名前を名乗らない `TypeError` になり、文字列は 1 文字ずつ要素として読まれて
157
+ `` `allowedYears[0]` must be a valid Date, received "2". `` のように別のものを名指していました。`DateSelector variant="split-dropdown"` は従来どおり、形を問う前に
158
+ この変種では `allowedDates` を使えないと名乗ります。
159
+ - **取り消した Proxy を一覧やタプルとして渡しても、マウントでも再描画でも Props・オプション名を名乗る `RangeError` になります**
160
+ (`(received: an object that cannot be converted to a string)`)。これまでは配列の判定 (`Array.isArray`) 自身が名前の無い `TypeError` を投げ、`PeriodSlider` では
161
+ 再描画のメモ比較器からも投げていました (`range` / `defaultRange` などのタプル、`allowedDates` / `macroAllowedDates` / `microAllowedDates`、フックの初期値のタプル、
162
+ `resolveSelectorSteps` / `resolveVernierSelectorSteps` の選択・窓・候補)。
163
+
164
+ - **表現範囲の最初の単位の日付が、定義域の判定をすべて素通りしていた欠陥を直しました**。その日付の符号化キーは `NaN` で、`NaN` はどの大小比較にも
165
+ 掛からないため、平レールは `aria-valuemin="NaN"` で描かれ、`getSortedAllowedDates` は片側の絞り込みを外して定義域の外の候補を返し、
166
+ ノギスのフックの連続レールは時点を窓と定義域の外のまま保持していました。判定を 1 つの関数に集め、セレクタの 1 歩の関数 (`resolveSelectorSteps` /
167
+ `resolveVernierSelectorSteps`) と同じ判定と文言で拒否します。利用側から見える違いは上の「変更」のとおりです。
168
+
169
+ - **4 つのフックと `useSelectorStepper` の返す関数は、最後に確定した描画の境界・候補・コールバック・ステート・◀▶ の行き先だけを読みます**。
170
+ 0.16.0 までは、確定経路が事象の時点で読むこれらの値をレンダー中に ref へ写していました。React は確定しない描画 (`startTransition` で渡したオプションが
171
+ Suspense で中断して保留している間の描画、割り込まれた並行描画) でも本体を走らせるため、移行が保留している間に確定した描画の設定関数・
172
+ `sliderProps` のコールバック・シフト・リセット・◀▶ を呼ぶと、次のように振る舞いました。
173
+ - (1) 保留中の `minDate` / `maxDate` で収めた。ノギスのマクロのシフトは、保留中の境界を越えると中止した。
174
+ - (2) 保留中の `allowedDates` / `macroAllowedDates`・`unit`・`yearStartMonth` で解決した候補へ寄せ、その上を歩いた。
175
+ - (3) 確定していない描画が渡したコールバックを呼んだ。
176
+ - (4) 保留中の描画が畳んだステートを起点にした。ノギスでは、動かしていないマクロ窓を畳んだ値で通知しながらステートは変えず、利用側とフックが別の窓を
177
+ 持つことがあった。平レールでは、保留中の描画が畳んだ値と同じ値へ動かす操作を、通知だけして保存しないことがあった。
178
+ - (5) ◀▶ が保留中の描画の行き先へ送るか、何もしなかった。
179
+
180
+ 写しは挿入副作用 (`useInsertionEffect`) で行うため、子孫のレイアウト副作用から呼んでも、隠れた `Activity` の中でも、その確定の値を読みます。
181
+ 返す関数が事象の処理中に書いたステートの写しは、その後に確定した描画がそれより前に走っていれば上書きしないため、時間分割した描画がフックのホストを
182
+ 描いた後で譲っている間の呼び出しも、これまでどおり効きます。確定経路は、返す関数が最後にステートへ渡したオブジェクトを写しが持つ間だけ
183
+ 同じ値を渡すのを省き、それ以外は写しと同じ値でも渡すため、`startTransition` の中で呼んだ設定関数が中断している間に別の描画が確定し、そのあとで
184
+ 設定関数・リセットを呼んでも、保存される値は最後に通知した値と一致します。中断している値と同じ値の緊急の呼び直しは、
185
+ その間にホストが描き直されていなければ、これまでどおりその値を緊急の優先度へ引き上げず (代替表示を出さず)、更新の後の同じ値の呼び直しも
186
+ ホストを描き直しません。
187
+ 関数・Props の同一性と拒否メッセージの文言は変わりません。
188
+
189
+ - **`DateSelector variant="split-dropdown"` を制御から非制御へ切り替えた描画は `RangeError` を投げなくなりました**。以前の非制御の描画が -271821 年に残した選択は、
190
+ 切り替えた描画が `initialDate` を取り込んで置き換えるため描かれません。制御を挟んで同じ `initialDate` のまま非制御へ戻した描画も、`initialDate` を
191
+ 取り込み直すため送出しません。日だけを描く変種で利用者が -271821 年へ動かした選択を保持したまま `variant="split-dropdown"` へ切り替える描画も、
192
+ 同じ描画で別の日の `initialDate` を渡せば通ります (最後に取り込んだ日と同じ日に置いたままなら、これまでどおり `variant="split-dropdown"` を名乗る `RangeError`)。
193
+ メッセージの文言は変わりません。
194
+
195
+ - **0-99 年のノギスの窓の末尾が 1900 年代へ写っていた欠陥を直しました**。月 × 日の窓の末尾を `new Date(y, m + 1, 0)` で組んでいたため、0-99 年では 1900 年代の日付になり、
196
+ 窓は `maxDate` へのクランプで閉じていました。ミクロレール (50 年 6 月の窓のミクロ終了つまみの `aria-valuemax` は、`0060-01-01` の `-697613` ではなく `0050-06-30` の `-701085`)、
197
+ フックの収め込み (`shiftMicroRange` は期間の末日で中止し、`shiftMicroValue` は末日で止まります。これまでは翌月 (`0050-07-01`) へ動いていました)、
198
+ ミクロセレクタの境界 (`microEndSelectorProps.maxDate` など) が、実際の期間を張ります。
199
+ - **表現範囲の最後の月へ届く月・年の加算が、表現できる結果を Invalid Date にしていた欠陥を直しました**。加算先の月末を先に組む実装 (date-fns の `addMonths` / `addYears`) が、
200
+ 途中の月末で表現範囲を越えていました。月・年の加算は暦の算術 (`shiftCivilMonths`) で年月日を 1 度に書きます。
201
+
202
+ ### 移行
203
+
204
+ - 配列でない値で「候補なし (連続のレール)」を表していたホストは、一覧を省略 (`undefined`) するか `[]` を渡してください。
205
+ - ノギスの行の一覧に `null` を渡して共有の `allowedDates` を継がせていたホストは、その行の一覧を省略 (`undefined`) してください。
206
+ - 本体やフックの候補の拒否メッセージを `getSortedAllowedDates:` で照合していたテストは、所有者 (`PeriodSlider` / `usePeriodSliderRange` / `usePeriodSliderPoint` /
207
+ `useVernierSliderRange` / `useVernierSliderPoint`) と読んだ一覧 (継いだ行を含む) で照合してください。`getSortedAllowedDates` を直接呼ぶ場合、既存の拒否の文言は、
208
+ 配列を示す部分と、有効な Date でない境界の拒否 (`normalizeDateByUnit:` から `getSortedAllowedDates:` へ) を除いて変わりません。
209
+ - 受け取った配列を `String()` の形で照合していたテストは、要素ごとの形 (README「実行時バリデーション (Fail Fast)」の受け取った値の規則) へ改めてください。
210
+ - `minDate` に `new Date(-8.64e15)` のような番兵を「下限なし」として渡していたホストは、提示したい最も早い日付を渡してください (`minDate` は必須です)。
211
+ - 表現範囲の最初の単位の日付をフックの設定関数・コールバックへ渡して定義域の端へクランプさせていたホストは、`minDate` そのものか定義域の中の日付を渡してください。
212
+ - これらの日付の拒否を `normalizeDateByUnit:` / `resolveMacroWindow: macroRange[0] must be a valid Date` / `clampPairIntoDrawnValues:` / `drawnValuesNearest:` で照合していた
213
+ テストは、所有者と Props・入口の名前を名乗る `must fall in a <単位> that starts inside the Date range` で照合してください。
214
+ - 描画中にフックの返す関数 (設定関数など) を呼んで Props に追従していたホストは、副作用 (`useEffect` / `useLayoutEffect`) かイベントハンドラの中で呼んでください
215
+ (描画中の呼び出しは最後に確定した描画の値を読みます)。
216
+ - 非制御のセレクタへ同じ日・月・年の中で動く `initialDate` を渡して利用者の選択を戻させていたホストは、`value` で制御するか、`key` を変えて作り直してください
217
+ (別の単位への移動は、これまでどおり取り込みます)。
218
+ - `addUnit` へ整数でない `amount` を渡していたホストは、整数へ丸めてから渡してください (切り捨ての向きは単位と日付で揃っていませんでした)。
219
+ - `getMacroWindowStartDate` / `getMacroWindowEndDate` / `findNearestDateIndex` の拒否を `normalizeDateByUnit:` で照合していたテストと Invalid Date の戻り値を照合していたテスト、
220
+ 表現範囲の端でのフックのシフトの送出を照合していたテストは、新しい文言 (README「年を扱う 8 つのヘルパー」) と、止まる・中止する挙動で照合してください。
221
+
7
222
  ## 0.16.0 (2026-10-01)
8
223
 
9
224
  セレクタの ◀▶ を所有者へ引き渡す口と、◀▶ が期間・ノギスの窓をどう動かすかを 1 か所で決める規則を加えた版です。