@aiquants/period-slider 0.15.1 → 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 (52) hide show
  1. package/CHANGELOG.md +494 -8
  2. package/README.md +309 -141
  3. package/dist/DateSelector.d.ts +41 -6
  4. package/dist/DateSelector.d.ts.map +1 -1
  5. package/dist/MonthSelector.d.ts +33 -6
  6. package/dist/MonthSelector.d.ts.map +1 -1
  7. package/dist/PeriodSlider.d.ts +282 -28
  8. package/dist/PeriodSlider.d.ts.map +1 -1
  9. package/dist/YearSelector.d.ts +35 -6
  10. package/dist/YearSelector.d.ts.map +1 -1
  11. package/dist/dateOptionDomain.d.ts +3 -3
  12. package/dist/dateOptionDomain.d.ts.map +1 -1
  13. package/dist/index.cjs +1 -1
  14. package/dist/index.d.cts +4 -0
  15. package/dist/index.d.ts +4 -0
  16. package/dist/index.d.ts.map +1 -1
  17. package/dist/index.js +2851 -2203
  18. package/dist/inputValue.d.ts +154 -0
  19. package/dist/inputValue.d.ts.map +1 -0
  20. package/dist/optionText.d.ts.map +1 -1
  21. package/dist/selectorMemo.d.ts +51 -0
  22. package/dist/selectorMemo.d.ts.map +1 -0
  23. package/dist/selectorStep.d.ts +303 -0
  24. package/dist/selectorStep.d.ts.map +1 -0
  25. package/dist/useCommittedRef.d.ts +80 -0
  26. package/dist/useCommittedRef.d.ts.map +1 -0
  27. package/dist/usePeriodSlider.d.ts +137 -44
  28. package/dist/usePeriodSlider.d.ts.map +1 -1
  29. package/dist/useUncontrolledSelection.d.ts +27 -0
  30. package/dist/useUncontrolledSelection.d.ts.map +1 -0
  31. package/dist/valueSet.d.ts +117 -6
  32. package/dist/valueSet.d.ts.map +1 -1
  33. package/dist/vernierStep.d.ts +189 -0
  34. package/dist/vernierStep.d.ts.map +1 -0
  35. package/package.json +1 -1
  36. package/src/DateSelector.tsx +318 -84
  37. package/src/MonthSelector.tsx +140 -55
  38. package/src/PeriodSlider.tsx +603 -226
  39. package/src/VirtualDateDropdown.tsx +2 -2
  40. package/src/YearSelector.tsx +190 -67
  41. package/src/dateOptionDomain.ts +10 -7
  42. package/src/index.ts +15 -0
  43. package/src/inputValue.ts +237 -0
  44. package/src/labels.ts +4 -4
  45. package/src/optionText.ts +4 -3
  46. package/src/selectorMemo.ts +66 -0
  47. package/src/selectorStep.ts +548 -0
  48. package/src/useCommittedRef.ts +206 -0
  49. package/src/usePeriodSlider.ts +922 -405
  50. package/src/useUncontrolledSelection.ts +54 -0
  51. package/src/valueSet.ts +187 -8
  52. package/src/vernierStep.ts +568 -0
package/CHANGELOG.md CHANGED
@@ -4,6 +4,457 @@ 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
+
222
+ ## 0.16.0 (2026-10-01)
223
+
224
+ セレクタの ◀▶ を所有者へ引き渡す口と、◀▶ が期間・ノギスの窓をどう動かすかを 1 か所で決める規則を加えた版です。
225
+ あわせて、フックとセレクタの既存の欠陥 (離散レールの候補がセレクタへ届かない、平レールのフックがレールの描かない値を保持する、
226
+ 通知が利用側の知らない値を取りこぼす、境界が初期値を越えて動くと送出する、`YearSelector` が Date の表現範囲の端で別の年を
227
+ 発行し得る、など) を直しました。**新しい Props・オプションを渡さないホストでも、下の「変更」の各点で挙動が変わります**
228
+ (フックを使うホスト全般。とりわけ離散レール・実行中に動く境界・`setRange` などの直接の更新関数・`YearSelector` への番兵・`DateSelector variant="split-dropdown"` への -271821 年の日付を使うホストと、拒否メッセージの文言を照合するテスト)。
229
+
230
+ ### 追加
231
+
232
+ - **3 セレクタの `stepper` Props**。`{ onStep, canStepPrevious, canStepNext }` を渡すと、◀▶ の押下は `onChange` ではなく
233
+ `onStep("previous" | "next")` だけを呼び、押せるかどうかは `canStepPrevious` / `canStepNext` そのものになります。これまで ◀▶ の押下は
234
+ 隣の値を選んだ操作と同じ `onChange` で届き、所有者は両者を区別できず、押せるかどうかもセレクタ自身の判定 (示している値に隣があるか) に
235
+ 縛られていました。セレクタは自分の値を動かさないため制御の `value` を要求し (`initialDate` だけなら `RangeError`)、
236
+ 選択肢・入力で選んだ値は `onChange` で届きます。`disabled` は引き続き両方の矢印を無効にします。メモ比較は `stepper` を
237
+ フィールドごとに比べ、付け外しの描画と、付けたまま非制御へ切り替えた描画は省かずに検証します。
238
+ - **`resolveSelectorSteps`**。向きごとの規則 (`shift` [`edge` は `"disable"` 既定 / `"clamp"`]・`start`・`end`・`single`) のもとで、
239
+ ◀▶ が選択 ([開始, 終了]) をどこへ送るか、そもそも送れるかを返す純関数です。動かす端はすべて単一の値のステッパーが送る先へ着くため、
240
+ 選択と同じ単位の 1 歩ではセレクタ自身の ◀▶ の規則 (集合の外からは戻る向きだけが押せる) と一致します。離散候補 (`allowedDates`)、
241
+ 片側だけの境界、`yearStartMonth`、月の期間を年の行で動かす 1 歩 (`stepUnit: "year"`。日の選択を月・年で動かす組み合わせは、暦の
242
+ 月末で丸まって往復しても戻らないため `RangeError`) を扱います。両側へ広げる動きは `start` と `end` の組で表します。候補配列は
243
+ 参照で同一視して 1 度だけ準備する (初回は O(n log n)) ため、以後の 1 歩の費用は候補の数に対して O(log n) です (100 年分の日の
244
+ 候補でも、数か月分と比べて二分探索の数段しか増えません)。
245
+ - **`resolveVernierSelectorSteps`**。ノギスのマクロ行・ミクロ行の ◀▶ が確定するマクロ窓とミクロ選択を、向きごとにまとめて返す純関数です。
246
+ ミクロの 1 歩は今の窓ではなく定義域全体の上を動き、窓は `window` (`"keep"` 既定 / `"follow"`) で据え置くか行き先のマクロ単位へ合わせます
247
+ (離散マクロレールでは外側の候補へ吸着し、`edge: "clamp"` は最後の候補の窓の端で効きます)。行き先の窓のレールが描かない端は押した向きへ
248
+ そのレールが描く最初の値まで進み、どの端も押した向きに逆らって動きません。マクロの 1 歩は、窓ごと動けばミクロ選択を運び、片端だけ
249
+ 動けば切り落とします。候補配列は `resolveSelectorSteps` と同じく 1 度だけ準備し、マクロの 1 歩も行き先の窓の候補を日付へ戻さずに
250
+ ミクロ選択を置くため、1 歩の費用は窓の広さに依りません。
251
+ - **`useSelectorStepper`**。行き先から `stepper` を作るフックです。`onStep` は描画を跨いで同一で、押せるかどうかが変わらない限り
252
+ 同じオブジェクトを返します (セレクタのメモ比較が描画を省けるため)。行き先はオブジェクトか `null` で、`undefined` を返し得る出所は
253
+ 型が拒みます。
254
+ - **フックのオプション `selectorStep` (`usePeriodSliderRange`)、`macroSelectorStep` / `microSelectorStep` (`useVernierSliderRange` /
255
+ `useVernierSliderPoint`)**。規則を渡した行の `SelectorProps` に `stepper` が載り (`SelectorProps.stepper`)、押下は他の変更と同じ確定経路を
256
+ 通ります (コールバックは動いたスケールだけが 1 度ずつ鳴る)。規則は中身で、境界は時刻で比べるため、インラインの規則や描画ごとに
257
+ 値の等しい新しい `Date` で渡した境界では行き先を求め直しません (求め直すのは規則の中身・選択・境界の時刻・単位・候補配列が変わったとき)。規則を渡さない行の Props に `stepper` キーは無く、規則は `sliderProps` へ転送されません。時点フックの
258
+ ミクロ行が読むのは `window` だけです。
259
+ - 型 `SelectorStepper` / `SelectorStepDirection` / `SelectorStepRule` / `SelectorStepRules` / `SelectorStepEdge` / `SelectorStepWindow` /
260
+ `VernierRangeStepRule` / `VernierPointStepRule` / `ResolveSelectorStepsOptions` / `SelectorStepTargets` /
261
+ `ResolveVernierSelectorStepsOptions` / `VernierSelectorStep` / `VernierSelectorStepTargets`。
262
+ - デモの 14 番目のセクション。ノギスのフックへ規則を渡し、年の行を窓ごと・月の行を期間ごと動かします (月の行の動き方と窓の扱いを切り替え、
263
+ 規則を外した従来の動きとも比べられます)。
264
+ - `SelectorProps.allowedYears` / `allowedMonths` / `allowedDates` (下の「変更」の 1 点目)。
265
+
266
+ ### 変更
267
+
268
+ - **フックのセレクタ Props (`SelectorProps`) が、離散レールの候補を運びます**。レールが離散の間 (`usePeriodSliderRange` /
269
+ `usePeriodSliderPoint` は `allowedDates` が空でない間、ノギスのマクロ行は `macroIsDiscrete` の間、ミクロ行は `microIsDiscrete` かつ
270
+ 現在の窓が候補を含む間)、行の `unit` のセレクタが読むキー 1 つ (`"year"` は `allowedYears`、`"month"` は `allowedMonths`、
271
+ `"day"` は `allowedDates`) に、レールが描く候補 (定義域で絞り、単位の先頭へ正規化した昇順の配列) を載せます。スプレッドした
272
+ セレクタは選択肢も ◀▶ もレールが描く値だけを差し出します。0.15.1 までは候補でない年・月・日も選択肢に並び、規則を渡さない行の
273
+ ◀▶ は候補でない値を発行していました。レールが連続の間はキーそのものを載せません。候補の一覧はフックが境界の時刻でメモ化するため、
274
+ 境界へ描画ごとに値の等しい新しい `Date` を渡してもセレクタの描画は省かれます。
275
+ **離散の日レールのフックを `DateSelector` の `variant="split-dropdown"` へ広げると `RangeError` になります** (この形は離散集合を
276
+ 扱えません)。この形を使い続けるならスプレッドの後ろに `allowedDates={undefined}` を書くか、`variant="dropdown"` /
277
+ `variant="date"` へ移してください。候補でない日の選択は、平レールのフックとノギスのミクロ行が最近傍の候補へ動かします
278
+ (ノギスのマクロ行は定義域へ収めるだけです)。
279
+ - **`usePeriodSliderRange` / `usePeriodSliderPoint` は、レールが描く値だけを保持します**。`allowedDates` がレールを離散にしている間、
280
+ 確定する値 (設定関数・セレクタの `onChange`・`sliderProps` のコールバック・`resetRange` / `resetValue`) とレンダー中の収め直しを
281
+ 最近傍の候補へ寄せてから `[minDate, maxDate]` へ収めます。0.15.1 までは候補でない値 (候補が 1 月と 6 月のレールでの `2024-03`) を
282
+ そのまま保持・通知し、レールだけが最近傍の候補 (`2024-01`) を描いていました (フックの値とレールの表示が別の期間を示す状態)。
283
+ 候補と同じ単位の中の値 (`2024-01-15`) はその候補として描かれるため、渡したまま残ります。期間の両端が同じ候補へ寄って生の時刻で
284
+ 逆転するときは、上限を下限へ揃えます。候補の上にない `initialRange` / `initialValue` は拒まず、初回の描画で同じ規則により
285
+ 置き直します。連続レールの挙動 (時刻で `[minDate, maxDate]` へ収める) は変わりません。
286
+ - **フックの通知 (`onChangeRange` / `onChangePoint`、ノギスの `onChangeMacroRange` / `onChangeMicroRange` / `onChangeMicroPoint`) は、
287
+ 確定した値が利用側の知っている値と異なるときに鳴ります**。知っている値とは、渡した初期値・`setRange` / `setValue` / `setMacroRange` /
288
+ `setMicroRange` / `setMicroValue` で自分で書いた値・最後に通知した値です。レンダー中の収め直し (境界や候補の変化、初期値の寄せ) はその場では通知せず、次にその値へ
289
+ 落ち着いた操作で通知します。反対に、収め直しの後で利用側の知っている値へ戻る操作は、ステートが変わっても鳴りません。
290
+ 0.15.1 までの平レールのフックは「ステートと異なるとき」だけ鳴ったため、収め直しの後に同じ値へ落ち着いた操作は利用側へ何も
291
+ 伝えず、ノギスのマクロ窓の通知も「ステートと異なるとき」だけ鳴り、ミクロ通知は初回の描画で寄せた初期値を通知済みとして扱い、
292
+ 直接の更新関数で書いた値を記録していませんでした (書いた値の後で以前の通知値へ戻る操作が鳴らなかった)。
293
+ - **`usePeriodSliderRange` / `usePeriodSliderPoint` は、設定関数とセレクタ・スライダーのコールバックへ渡した Invalid Date を、
294
+ フック名と入口の名前を名乗る `RangeError` で拒みます** (`setLowerDate(date)` / `setUpperDate(date)` / `sliderProps.onChangeRange(lower)` /
295
+ `selectorProps.onChange(date)` / `sliderProps.onChangePoint(value)`。`setRange` / `setValue` で入れた値は、次の描画が `range[0]` /
296
+ `value` などを名乗って拒みます)。ノギスのフックと同じ扱いです。0.15.1 までは Invalid Date をそのままステートと `onChangeRange` /
297
+ `onChangePoint` へ流していました。
298
+ - **期間を扱う 3 つのフック (`usePeriodSliderRange` / `useVernierSliderRange` / `useVernierSliderPoint`) は、利用側が渡した逆転した
299
+ 期間を黙って揃えず、名乗って拒みます**。`setRange` / `setMacroRange` / `setMicroRange` で
300
+ 入れた逆転した期間は次の描画が `range upper must not be earlier than lower` のように状態名を名乗って、`sliderProps` のコールバック
301
+ (`onChangeRange` / `onChangeMacroRange` / `onChangeMicroRange`) へ直接渡した逆転した期間は `sliderProps.onChangeRange(upper) must not
302
+ be earlier than lower` のように入口の名前を名乗って `RangeError` です (本体は逆転した期間を通知しません)。期間の両端が同じ候補へ
303
+ 寄って生の時刻で逆転する場合だけは、上限を下限へ揃えます。
304
+ - **4 つのフックは、初期値 (`initialRange` / `initialValue` / `initialMacroRange` / `initialMicroRange` / `initialMicroValue`) を定義域と
305
+ 初期の窓に照らすのを、マウント時だけにしました**。0.15.1 までは描画のたびに照らしたため、初期値を変えずに境界を初期値の先へ
306
+ 動かすと、描画中に `RangeError` になっていました (仕様は「マウント後に動いた境界へはステートの収め直しで応じる」としていました)。
307
+ マウント時に渡した初期値だけがリセットの行き先になり、リセットもいまの定義域へ収めて確定します (ノギスの `resetVernier` は窓を
308
+ 定義域へ収め、ミクロ選択をその窓のレールへ置きます)。
309
+ - **`YearSelector` は、年の始まりが Date の表現範囲の外にある Props を、prop 名を名乗る `RangeError` で拒みます**。対象は `value` /
310
+ `initialDate` / `minDate` / `maxDate` と `allowedYears` の要素 (その日付を含む年の、`yearStartMonth` の月の 1 日)、および
311
+ `minYear` / `maxYear` (どちらも発行し得る年を名指すため両方) です。0.15.1 までは、`new Date(-8.64e15)` のような番兵の境界で
312
+ 選択肢のラベルが空になり `onChange` へ Invalid Date が届き得たほか、始まりが表現範囲の外にある年 (10 月始まりの
313
+ `maxYear={275760}`) を選ぶと、年の初日の組み立て (コンストラクタで作った Invalid Date に年を書き戻す 2 段組み) が範囲内の別の
314
+ 日付へ化け、選んだのと別の年の日付を発行していました。年の初日は年・月・日を 1 回の `setFullYear` で組みます (`MonthSelector` /
315
+ `DateSelector` と同じ形)。番兵の境界のエラーは、実際に選ばせる年の範囲 (`minYear` / `maxYear`) か `allowedYears` を渡すよう示し、
316
+ 年 Props のエラーは年の始まりを決めた開始月を名乗ります。
317
+ - **`DateSelector variant="split-dropdown"` は、1 月 1 日が Date の表現範囲の外にある年 (-271821 年) の日付を `RangeError` で
318
+ 拒みます** (`YearSelector` と同じ規則)。`value` / `initialDate` / `minDate` / `maxDate` は prop 名を名乗り (境界には、`minYear` / `maxYear` で年を
319
+ 宣言するよう示す番兵の直し方を添える)、以前の描画から保持している非制御の選択がその年にあるまま描く描画 (その選択を保持したままの
320
+ `variant="split-dropdown"` への切り替えと、制御から非制御への切り替え) は `variant="split-dropdown"` を名乗ります。メモ比較器も
321
+ この年の日付のキーを使えない値として扱い、再描画で渡したその年の日付 (制御中の `initialDate` を含む) もその描画で拒みます。0.15.1 までは、
322
+ 境界・保持値・非制御の選択がその年にあると、年の選択肢 `-271821` と月の選択肢 `4` (保持年が境界の年でなければ 1〜4 月と、始まりが
323
+ 範囲外の日) の基準日を表現範囲の外に組み、組み込みのテキストは空になり、`formatOption` は Invalid Date を受け取っていました
324
+ (Invalid Date で例外を投げるフォーマッタ、たとえば date-fns の `format` では描画ごと落ちていた)。4 月の日数も数えられず、31 日を
325
+ 保持したまま 4 月を選ぶと、選んでいない 5 月 1 日を発行していました。
326
+ - **3 セレクタは、`allowedYears` / `allowedMonths` / `allowedDates` の `undefined` の要素と疎配列の穴を、添字付きの `RangeError` で
327
+ 名指します**。0.15.1 までは `YearSelector` / `MonthSelector` が内部の `TypeError` で落ち、`DateSelector` は穴を黙って飛ばし、
328
+ `Date` でない要素と `undefined` を、どの要素かを名乗らない `TypeError` で落としていました。
329
+ - `allowedYears` / `allowedMonths` / `allowedDates` と `stepper` (3 セレクタと `SelectorProps`) の型は `| undefined` を明示します
330
+ (`Date[] | undefined`・`SelectorStepper | undefined`)。`exactOptionalPropertyTypes` を有効にした利用側でも、フックの Props を広げた後ろで
331
+ `allowedDates={undefined}` や `stepper={undefined}` を書けます。
332
+ - **拒否のメッセージは、受け取った文字列を JSON の引用符付きで示します** (例:
333
+ `formatOptionText: scope must be "period" or "part" (received: "label")`、
334
+ `PeriodSlider: value must be a valid Date (received: "2024-02-12")`)。0.15.1 までは、`formatLocale`・`locale`・`labels` の検証だけが
335
+ 引用符を付け、ほかの検証 (Date 型 Props・年 Props・フックのオプション・`formatOptionText` の
336
+ 引数など) は引用符なしで示していたため、日付に見える文字列が有効な Date の ISO 表記と見分けられず、空文字列は何も示されません
337
+ でした。メッセージに載る受け取った値と保持している値 (`received` / `holding`) はパッケージ全体で 1 つの関数が組みます (文字列は JSON、
338
+ 有効な Date は ISO 8601、それ以外は `String()` の形)。`formatLocale` に文字列でない値を渡したときも JSON ではなくこの形で示します
339
+ (`NaN` は `null` ではなく `NaN`、素のオブジェクトは `{}` ではなく `[object Object]`、`BigInt` は名前を名乗らない `TypeError` ではなく数字)。
340
+ 例外は `labels` と `locale` の検証で、それらを検証するエンジン (`@aiquants/virtualscroll`) と同じ形 (`got number` など) のままです
341
+ (`locale` のメッセージはエンジンのメッセージを包み直したもの)。解決した境界など、パッケージが組んだ日付は、これまでどおり
342
+ `yyyy-MM-dd` (`DateSelector`) / `yyyy-MM` (`MonthSelector`) で示します。
343
+ - **`PeriodSlider` のタプル Props の形のエラーは、描画に必須の `macroRange` だけが `is required` を名乗ります** (公開関数
344
+ `resolveMacroWindow` の引数 `macroRange` も同じ)。省ける選択 Props (`range` / `defaultRange` / `microRange` / `defaultMicroRange`) は
345
+ 形だけを求めます (`PeriodSlider: defaultMicroRange must be a [start, end] Date tuple (received: null)`)。0.15.1 までは省ける Props も
346
+ `range is required and must be a [start, end] Date tuple` のように必須と名乗っていました。
347
+ - **ノギスの離散ミクロレールで、窓を動かす費用が候補の一覧の大きさに比例しなくなりました**。0.15.1 までのフック
348
+ (`useVernierSliderRange` / `useVernierSliderPoint`) は、窓が動くたび (レンダーと確定経路の両方) に候補の一覧全体を検証・整列し直し、
349
+ スライダー本体も窓の候補を一覧全体の符号化で絞っていました。どちらも候補を定義域で 1 度だけ解決し (候補の一覧・境界・単位・
350
+ `yearStartMonth` が変わったときだけ)、窓の候補はそのキーの二分探索で求めます。配置の結果 (値、値が変わらない端の `Date` そのもの、
351
+ 連続レールが返す窓の端の `Date`、送出) は、下の (3) を除いて変わりません。利用側から見える違いは 4 つです。
352
+ (1) 両端が同じ候補へ吸着したミクロ選択の 2 つの端は、同じ時刻の別々の `Date` になることがあります (0.15.1 までは 1 つの `Date` を
353
+ 共有していました)。(2) `shiftMicroRange` / `shiftMicroValue` が確定する `Date` は解決した一覧の `Date` そのもので、窓を跨いで同じ
354
+ インスタンスです (ミクロ行のセレクタへ渡す候補も同じ)。受け取った `Date` を書き換えないでください。(3) 単位の先頭が `Date` の
355
+ 表現範囲の始まり (`-8.64e15` ms) より前になるミクロの値 (表現範囲の最初の単位の中の値。日の単位では UTC 以外の時間帯だけ) を候補の
356
+ ある窓へ置くと、`drawnValuesNearest: value must be a finite integer (received: NaN)` で送出します。0.15.1 までは、窓の候補が 1 つなら
357
+ その候補へ寄せ、2 つ以上なら `normalizeDateByUnit: d must be a valid Date (received: undefined)` で送出していました。
358
+ (4) フックの確定経路 (`sliderProps` のミクロのコールバック・`shiftMicroRange` / `shiftMicroValue`) は、画面に描かれている描画が
359
+ 解決したミクロの候補を読みます。0.15.1 までは、確定していない描画 (保留中の移行) が渡した候補の一覧と離散スイッチを読むことが
360
+ あり、その間は画面のレールに無い値へ寄せ得ました。
361
+ ミクロ行のセレクタへ渡す窓の候補は窓が動くたびに新しい配列 (長さは窓の候補の数) で、セレクタはそれを受け取るたびに読み直すため、
362
+ セレクタを描く費用は窓の広さに比例します。
363
+
364
+ ### 修正
365
+
366
+ - **3 セレクタは、値の単位 (年・月・日) を変えずに制御と非制御を切り替えた描画を省かなくなりました**。0.15.1 までは比較器が
367
+ その切り替えを「変化なし」とみなして描画を省き、制御へ移った後も本体が内部ステートで描き続けていました (▶ を押すと、利用側が
368
+ 動かしていない値を表示していた)。
369
+ - **3 セレクタと `PeriodSlider` のメモ比較器は、再描画で渡した使えない Date 型 Props で例外を投げず、「変化なし」ともみなさなく
370
+ なりました**。Date でない値 (文字列・数値・`null`・素のオブジェクト) と Invalid Date は、初回のマウントと同じく、その描画で
371
+ Props 名を名指す `RangeError` になります (例: ``YearSelector: `minDate` must be a valid Date, received null.``)。比較器自身は、
372
+ どの値を渡しても例外を投げません。0.15.1 までは `YearSelector` / `MonthSelector` / `PeriodSlider` の比較器が、名前を名乗らない
373
+ `TypeError` (`date.getFullYear is not a function` など) を検証より先に投げていました。`DateSelector` の比較器は同じ日へ変換できる
374
+ 文字列・数値・`null` を等しいとみなして描画ごと省き、検証は無関係な Props が次に変わった描画まで走りませんでした。制御中の
375
+ `initialDate`、`initialDate` と並べた `value={null}`、未指定から `null` / `0` / `""` へ変えた `MonthSelector` の境界、未指定から
376
+ `null` へ変えた `YearSelector` の `yearStartMonth` と `PeriodSlider` の `value` / `range` / `microValue` も同じく省かれていました。
377
+ 有効な Date の扱いは変わりません (3 セレクタは同じ年・月・日の中の移動の描画を引き続き省き、`PeriodSlider` は引き続き時刻で比べます)。
378
+ - **ノギスは、制御のミクロ選択 (`microValue` / `microRange`) と並べて渡した既定値 (`defaultMicroValue` / `defaultMicroRange`) も
379
+ 描画のたびに検証します** (point / range モードの `value` / `defaultValue`・`range` / `defaultRange` と同じ規則)。0.15.1 までは
380
+ 制御の値があると既定値を検証せず、`null`・Invalid Date・定義域外の既定値を黙って受け取り、Date でない既定値 (文字列など) では
381
+ 初回のマウントが通った後、最初の再描画でメモ比較器が名前を名乗らない `TypeError` (`prev.defaultMicroValue?.getTime is not a function`)
382
+ を投げていました。
383
+ - **拒否のメッセージを組む段で例外を投げなくなり、使えない Date 型 Props はすべて、初回のマウントでも再描画でも拒否した部品・関数の名前付きの
384
+ `RangeError` になります**。文字列へ変換すると例外になる値 (`Object.create(null)`・時刻値を持たずに `Date.prototype` を継ぐ
385
+ オブジェクト・Date を包んだ Proxy) を渡すと、0.15.1 までは有効な Date かの判定 (`getTime` の呼び出し) か、メッセージに載せる値の
386
+ 文字列化が、名前を名乗らない `TypeError` (`this is not a Date object.`・`Cannot convert object to primitive value`) を投げて
387
+ いました。こうした値はメッセージでは `an object that cannot be converted to a string` と示します。有効な Date かどうかは Date
388
+ 自身の時刻値で判定するため、自前の `getTime` を持つだけで `Date.prototype` を継ぐオブジェクトも有効な Date とはみなしません。
389
+ フックのオプションとステップ規則の検証も、同じ判定とメッセージの規則を読みます。
390
+ - **ノギスのフックは、本体がマクロ窓を動かしたとき、利用側がまだ知らないミクロ選択を窓の外のまま通知しなくなりました**。
391
+ レンダー中に収め直した選択が新しい窓のレールに載らないときは窓だけを確定し、本体が置き直した値を 1 度だけ通知します
392
+ (0.15.1 までは、収め直した値を先に鳴らしてから本体の値で 2 度目を鳴らしていました)。レールに載ったままの選択は、窓と一緒に
393
+ 1 度だけ通知します。
394
+ - **`useVernierSliderPoint` のミクロセレクタの `onChange` は `setMicroDate` そのものになり**、Invalid Date を
395
+ `useVernierSliderPoint: setMicroDate(date)` を名乗って拒みます (0.15.1 までは内部関数 `normalizeDateByUnit` の名前で失敗していました)。
396
+ - **`getSortedAllowedDates` (本体・フックが離散候補を解決する関数) は、Date でない要素と疎配列の穴を
397
+ `getSortedAllowedDates: allowedDates[1] must be a valid Date (received: undefined)` のように添字付きで名指します** (0.15.1 までは
398
+ 正規化の奥の `normalizeDateByUnit` の名前で、どの要素かを名乗らずに失敗していました)。
399
+ - **`MonthSelector` / `DateSelector` の表現範囲のエラーは、番兵の境界 (`minDate` / `maxDate`) にだけ直し方を添えます**
400
+ (`YearSelector` と同じ規則)。値や許可月・許可日の要素のエラーに「prop を省く」直し方を添えていたのをやめ、境界の直し方も
401
+ 「変種が許せば境界を省く、または `minYear` / `maxYear` か許可集合で宣言する」に改めました (境界が必須の変種もあるため)。
402
+ 境界の双方を要し `allowedDates` も拒む `DateSelector variant="split-dropdown"` の境界のエラーは、`minYear` / `maxYear` で年を
403
+ 宣言するようにだけ示します。
404
+ - **`DateSelector variant="split-dropdown"` が上限より後の保持年・保持月を暦の終わりまで埋める月と日の一覧は、Date の表現範囲の端で
405
+ 終わります**。0.15.1 までは、275760 年の保持値で 10〜12 月を基準日の無い選択肢 (空のテキスト、`formatOption` へ Invalid Date) として
406
+ 描き、同年 9 月の保持値では日数を数えられずに日の一覧が空でした (日のセレクトはプレースホルダだけで `select.value === ""`)。日の一覧は
407
+ 実在する日だけを並べ (次項)、保持日だけが変わっても組み直しません (同じ月の中で保持日が動くだけなら、日の選択肢のために
408
+ `formatOption` は呼ばれ直しません)。
409
+ - **`DateSelector variant="split-dropdown"` の日の一覧はローカルの暦に実在する日だけを並べ、どの選択肢も自分が名指す日だけを
410
+ 発行します**。実在するのは、年・月・日から組んだ日付が同じ年・月・日を名乗る日だけです (月の日数は数えません)。0.15.1 までは
411
+ 月の日数で一覧を組んでいたため、タイムゾーンが月の途中の日を飛ばした月 (Pacific/Apia の 2011 年 12 月は 30 日が無い) では
412
+ 30 日の選択肢が `31` と描かれ、それを選ぶと (保持日と組んでその日になる年・月を選んでも) 選んでいない 12 月 31 日を発行し、
413
+ 月末の日を飛ばした月 (Pacific/Kiritimati と Pacific/Kanton の 1994 年 12 月、Asia/Manila の 1844 年 12 月) では日の一覧が
414
+ 1 日の 1 件だけになり、ほかの日を選べませんでした。飛ばされた日は一覧に現れず、その日になる年・月の選択肢は `disabled` です。
415
+
416
+ ### 移行
417
+
418
+ - `onChange` に届いた値が今の値の隣かどうかで ◀▶ の押下を推し量っていた利用側は、`stepper` で押下を直接受け取れます
419
+ (README「セレクタの矢印を所有者が引き受ける」)。推し量りは、選択肢から隣の値を選んだ操作と区別できません。
420
+ - フックへ規則を渡した行の `SelectorProps` には `stepper` が載ります。`SelectorProps` をセレクタへそのままスプレッドしていれば、
421
+ ほかに書き換えるものはありません。
422
+ - 離散レールをフックで使い、候補でない選択肢や ◀▶ の行き先を前提にしていたテストは、候補の上の値へ改めてください。セレクタへ
423
+ 自分で `allowedYears` / `allowedMonths` / `allowedDates` を渡していた場合、スプレッドの後ろに書いていればその値がそのまま勝ち、
424
+ 前に書いていればフックの候補が勝ちます (フックが載せるのはレールの候補そのものなので、同じ集合なら書かなくて構いません)。
425
+ - 通知の回数を数えるテストは、収め直しや初期値の寄せの後にその値へ落ち着く操作で 1 回増え、収め直しの後に利用側の知っている値へ
426
+ 戻る操作で 1 回減ることがあります。ノギスのミクロ通知は、`setMicroRange` / `setMicroValue` で書いた値の後に以前の通知値へ戻る
427
+ 操作で 1 回増え、書いた値と同じ値の確定で 1 回減ります。現在の値は、コールバックではなくフックの `range` / `value` /
428
+ `microRange` / `microValue` で読めます。
429
+ - 平レールのフックの設定関数・コールバックへ Invalid Date を渡し得るコードは、値を検証してから渡してください (`RangeError` になります)。
430
+ - 境界を動かすたびに `initialRange` などを境界の内側へ作り直して渡していた回避は、要らなくなりました。
431
+ - ノギスで `microValue` / `microRange` と一緒に `defaultMicroValue` / `defaultMicroRange` を渡している場合、既定値も有効な Date
432
+ (タプル) で定義域の中にある必要があります。表示に使わない既定値は渡さないでください。
433
+ - 再描画でセレクタや `PeriodSlider` の Date 型 Props へ文字列・数値・`null` を渡していた場合 (`DateSelector` へ同じ日の ISO 文字列を
434
+ 渡すなど、0.15.1 では描画が省かれて気付かなかったものを含む) は、その描画で `RangeError` になります。Date を渡してください。
435
+ - 拒否のメッセージの文言を照合しているテストは、受け取った文字列を引用符付きで照合してください (`(received: x)` は
436
+ `(received: "x")`、`DateSelector` の `(received 2024-05-02)` は `(received "2024-05-02")`)。`PeriodSlider` の省ける選択 Props の
437
+ タプルのエラーは `is required and` を含みません (`range is required and must be a [start, end] Date tuple` は
438
+ `range must be a [start, end] Date tuple`)。
439
+ - `DateSelector` の `variant="split-dropdown"` に -271821 年の日付 (UTC で渡す番兵 `new Date(-8.64e15)` を含む) を渡していた場合は
440
+ `RangeError` になります。選ばせる年を `minYear={-271820}` のように宣言するか、日だけを描く `variant="dropdown"` / `variant="date"` を
441
+ 使ってください。非制御のまま `variant` を切り替える画面や、制御と非制御を切り替える画面でその年の日を選ばせていた場合は、`value` で制御してください。
442
+
443
+ ### 0.13.0 の記述の訂正
444
+
445
+ - 「新しいコールバックはその選択肢が確定する日付そのものを受け取る」は不正確でした。分割セレクトの部位 (`scope === "part"`) の
446
+ 選択肢が受け取るのは、その `<select>` の値と、それより粗い保持中の部位から決まる日付 (年は 1 月 1 日、月は保持中の年の当月 1 日、
447
+ 日は保持中の年月とその日) であり、確定日を基準日にする形は同じ 0.13.0 の「修正」のとおり撤回されています。和暦の元号のように
448
+ 確定日の呼び名が要る場合は、同じ節の既知の制約のとおり、利用側が自分の基準日を選んでください。
449
+
450
+ ### 文書
451
+
452
+ - README から版ごとの移行節 (0.12・0.13・0.14・0.15.0 からの移行、インストール節の 0.9.0 / 0.10.x からの注意、`DateSelector` の
453
+ `<select>` を前提にしたテストの読み替え) を除き、本書の該当する版へ移しました。README は現在の仕様だけを書き、版ごとの変更と
454
+ 移行手順は本書が持ちます。README にしか無かった手順と例は 0.11.0・0.13.0・0.14.0・0.15.1 の各節へ書き足しています。
455
+ - README の `useVernierSliderPoint` の `yearStartMonth` は「4 つの `SelectorProps` へ転送」としていましたが、このフックが返すセレクタ
456
+ Props は 3 つ (マクロ開始・マクロ終了・ミクロ時点) のため直しました。
457
+
7
458
  ## 0.15.1 (2026-09-25)
8
459
 
9
460
  0.15.0 の回帰を直す修正版です。0.15.0 は「`allowedYears` を渡していないホストの DOM は、上の 5 点以外は 1 バイトも変わりません」と
@@ -33,9 +484,10 @@ All notable changes to `@aiquants/period-slider` are documented here.
33
484
  窓ごと運ぶ、`macro-connect` は暦の差分だけ平行移動してから運ぶ) で置き直した値を 1 度だけ通知し、フックのステートはその値になります。
34
485
  - **ノギスのフックは、窓の最初と最後の単位の途中にあるミクロ日付を単位の先頭へ書き換えていました** (0.14.0 から)。
35
486
  12 月で終わる窓の中の `2024-12-15` は、本体にとっては 12 月の上にある正当な値ですが、フックは時刻で比べて `2024-12-01` へ
36
- 切り落としていました。本体が「動いていない」とみなして通知しない場面 (マクロつまみで窓を縮めた直後、`initialMicroRange` の
37
- 初回描画など) では、ステートだけが黙って変わっていました。フックの包含判定は本体と同じくミクロ単位で行い、窓の内側の値は
38
- 渡されたまま残します。`shiftMicroRange` が窓の最後の単位の途中へ着くシフトを「はみ出す」として中止していたのも同じ原因です。
487
+ 切り落としていました。本体が「動いていない」とみなして通知しない場面 (マクロつまみで窓を縮めた直後、`initialMicroRange` /
488
+ `initialMicroValue` の初回描画など) では、ステートだけが黙って変わっていました。フックの包含判定は本体と同じくミクロ単位で行い、窓の内側の値は
489
+ 渡されたまま残します。`initialMicroRange` / `initialMicroValue` に単位の途中の日付を渡していたホストでは、初回描画から
490
+ 渡した値のままになります。`shiftMicroRange` が窓の最後の単位の途中へ着くシフトを「はみ出す」として中止していたのも同じ原因です。
39
491
  - **離散マクロレールへ候補の外の `macroRange` を渡すと、マクロつまみの `aria-valuenow` が自分の `aria-valuemin` /
40
492
  `aria-valuemax` の外を指していました** (0.15.0 の回帰。可動端を候補集合の端にした変更で生じた)。外側の端は
41
493
  「可動端と現在値のうち外側の方」を名乗ります。候補の上に居る間は 0.15.0 と同じく候補集合の端です。
@@ -60,7 +512,7 @@ All notable changes to `@aiquants/period-slider` are documented here.
60
512
  `useVernierSliderPoint` の `setMicroDate` は Invalid Date を黙ってステートと通知へ流していました。
61
513
  `sliderProps` のコールバック (`onChangeMacroRange` / `onChangeMicroRange` / `onChangeMicroPoint`) を利用側が直接呼んだ場合も、
62
514
  `useVernierSliderRange: sliderProps.onChangeMicroRange(upper) is required ...` のように引数名まで名乗って拒みます。
63
- - **4 つのフックのシフト関数は、整数でない `delta` をフック名と関数名を名乗る `RangeError` で拒みます**
515
+ - **4 つのフックのシフト関数は、整数でない `delta` (`NaN`・`Infinity`・小数) をフック名と関数名を名乗る `RangeError` で拒みます**
64
516
  (`usePeriodSliderRange` の `shiftRange`、`usePeriodSliderPoint` の `shiftValue`、ノギスの 2 フックの `shiftMacroRange` と
65
517
  `shiftMicroRange` / `shiftMicroValue`。メッセージは `useVernierSliderRange: shiftMicroRange(delta) must be an integer number of units (received: NaN)`)。
66
518
  0.15.0 は `NaN` を渡すと、平坦な 2 フックが Invalid Date を `onChangeRange` / `onChangePoint` へ通知し、ノギスの 2 フックが
@@ -183,8 +635,10 @@ All notable changes to `@aiquants/period-slider` are documented here.
183
635
  > **0.13 で `locale="ja"` / `locale="en"` を渡していたホストは、型エラーも実行時エラーも出ないまま意味が変わります**。
184
636
  > `"ja"` / `"en"` は 0.13 では日付書式の正当な BCP 47 タグでしたが、0.14 では UI 言語の `locale` の受理値そのものです。
185
637
  > `formatLocale` へ改名しない限り、日付テキストは黙って ISO 8601 へ戻り (`2024/01` → `2024-01`、`04/15/2025` → `2025-04-15`)、
186
- > `"ja"` では部品の名前も日本語カタログへ切り替わります (`Previous month` → `前月`)。
638
+ > `"ja"` では部品の名前も日本語カタログへ切り替わります (`Previous month` → `前月`)。アクセシブル名や Intl 書式の日付を照合するテストは、
639
+ > 原因を示さずに失敗します。
187
640
  > **0.13 の `locale` は値が何であれ、すべて `formatLocale` へ改名してください**。日本語の名前が欲しい場合に限り、そのあとで `locale="ja"` を加えます。
641
+ > フックのオプション (`{ locale: "ja" }` → `{ formatLocale: "ja" }`) と `SelectorProps` も同じです。
188
642
 
189
643
  - `locale="ja-JP"` (日付書式) → `formatLocale="ja-JP"`。フックの `{ locale: "ja-JP" }` も `{ formatLocale: "ja-JP" }` へ。
190
644
  `"ja"` / `"en"` 以外のタグを旧名のまま渡すと、UI 言語の `locale` として
@@ -289,7 +743,34 @@ All notable changes to `@aiquants/period-slider` are documented here.
289
743
  `MonthSelector` / `YearSelector` には何も無い) を、`formatOption` 1 つへ畳んだためです。
290
744
  - 移行はそのまま 1 行で書けます: `formatMonthOption={(m) => g(m)}` →
291
745
  `formatOption={(date, unit, scope) => (scope === "part" && unit === "month" ? g(date.getMonth() + 1) : formatOptionText(date, unit, scope, locale))}`。
292
- 担当しない組は `formatOptionText` へ転送してください。
746
+ 担当しない組は `formatOptionText` へ転送してください。3 つの旧 Props は同じ 1 つの関数の枝になります (旧 Props が受け取っていた
747
+ 数値は、受け取った日付から取り出せます):
748
+
749
+ | 0.12 まで | 0.13 から |
750
+ | :--- | :--- |
751
+ | `formatYearOption={(year) => …}` | `formatOption` の `unit === "year" && scope === "part"` の枝 (`year` は `date.getFullYear()`) |
752
+ | `formatMonthOption={(month) => …}` | 同じ関数の `unit === "month" && scope === "part"` の枝 (`month` は `date.getMonth() + 1`) |
753
+ | `formatDayOption={(day) => …}` | 同じ関数の `unit === "day" && scope === "part"` の枝 (`day` は `date.getDate()`) |
754
+
755
+ ```tsx
756
+ // 0.12
757
+ <DateSelector variant="split-dropdown" locale="ja-JP" formatMonthOption={(month) => `${month}月`} {...rest} />
758
+
759
+ // 0.13 — 担当しない組は formatOptionText へ転送し、書式ロケールは Props ではなく第 4 引数で渡す
760
+ const formatOption: PeriodOptionFormatter = (date, unit, scope) =>
761
+ unit === "month" && scope === "part" ? `${date.getMonth() + 1}月` : formatOptionText(date, unit, scope, "ja-JP")
762
+
763
+ // formatOption(new Date(2025, 3, 15), "month", "part") === "4月"
764
+ // formatOption(new Date(2025, 3, 15), "day", "part") === "15日" (組み込みの段へ委譲。第 4 引数を省くと "15")
765
+ <DateSelector variant="split-dropdown" formatOption={formatOption} {...rest} />
766
+ ```
767
+
768
+ - **書式ロケール (`locale`。0.14.0 で `formatLocale` へ改名) を指定していたホストは、同じタグを `formatOptionText` の第 4 引数へ
769
+ 渡してください**。`formatOption` は書式ロケールより上の段なので、フォーマッタを渡した時点で Props の書式ロケールはどの表示
770
+ テキストにも届かなくなります (残しても害はありませんが、表示は決めません)。転送時に第 4 引数を省くと、自分で描かない組だけが
771
+ Intl の段からロケール非依存の ISO 8601 の段へ落ちます — 上の例では年が `2025年` → `2025`、日が `15日` → `15` となり、自分で
772
+ 描いた月だけが変わらないため、3 列のうち 2 列が黙って言語を変えます。書式ロケールを指定していなかったホストは、第 4 引数も
773
+ 省いたままで挙動が変わりません。
293
774
  - **旧 Props は数値 1 つしか受け取らなかったため、年度も四半期も表現できませんでした**。`formatYearOption(2019)` からは
294
775
  その 4 月がどの年度に属するのかを知る術が無く、`formatMonthOption(4)` は年を知りません。新しいコールバックは
295
776
  その選択肢が確定する日付そのものを受け取るため、どちらも導けます。
@@ -309,8 +790,10 @@ All notable changes to `@aiquants/period-slider` are documented here.
309
790
  - **その場に書いた無名関数では、診断が Props の名前を 1 度も出しません**。
310
791
  `formatLabel={(d, verbose = false) => …}` の診断は `TS2322: Type 'false' is not assignable to type
311
792
  'PeriodSliderUnit'` であり、Props ではなく既定値そのものを指します。
793
+ - `dates.map(formatDate)` と共用するために書かれがちな `(date: Date, index?: number) => string` は
794
+ `Type '(date: Date, index?: number) => string' is not assignable to type 'PeriodOptionFormatter'` になります。
312
795
  - **移行**: 第 2 / 第 3 引数の型を `unit` / `scope` を受けられる形まで広げるか、1 引数のラッパーで包んでください
313
- (`formatLabel={(d) => padded(d)}`)。
796
+ (`formatLabel={(d) => padded(d)}`。`map` と共用している関数なら、`map` へ `(date) => formatDate(date)` を渡す形でも構いません)。
314
797
  - **型エラーにならない側にも一度目を通してください**。余分な引数が `string` / `unknown` / `any` / 可変長のときは
315
798
  0.12.0 でも本リリースでも型エラーになりませんが、0.12.0 が `customFormat(d)` と 1 引数で呼んでいたのに対し
316
799
  本リリースは `customFormat(d, unit, "period")` と呼ぶため、既定値ではなく `unit` と `scope` が入ります
@@ -440,7 +923,10 @@ All notable changes to `@aiquants/period-slider` are documented here.
440
923
  変わりません。
441
924
  - 操作要素は `<input type="text" readonly role="combobox">` になり、`value` は人間が読むテキスト、機械可読値は
442
925
  `data-value` (`yyyy-MM-dd`) です。`<select>` の `value` / `options` / `selectOption` を前提にしたテストと DOM 参照は
443
- README「各種セレクタ」の `DateSelector` の項の移行表に従ってください。
926
+ 次のように読み替えてください: `select.value` → `combobox.getAttribute("data-value")`、`select.options` を数える → 開いてから
927
+ 行の `aria-setsize` を読む (描画される行は可視窓の分だけ)、`selectOption(value)` → 開いて行を押すか、ISO の数字を打って `Enter`。
928
+ Playwright の `getByRole("combobox", { name: "Date" })` はそのまま解決します (名前は既定の `Date`)。`toHaveValue` は書式ロケール
929
+ (0.11 の `locale`、0.14.0 からの `formatLocale`) のテキストと比較されるため、ISO は `toHaveAttribute("data-value", …)` で読みます。
444
930
  - ポップアップは `document.body` へポータルされ、下に余地が無ければ上へ反転して視野内へ収まります。各行は
445
931
  `aria-posinset` / `aria-setsize` を集合全体の件数で持ち、キーボード (矢印・`Home` / `End` / `PageUp` / `PageDown` /
446
932
  `Enter` / `Escape` / 先頭一致入力) は操作要素が `aria-activedescendant` 方式で担います。タッチでは OS のホイール式