@aiquants/period-slider 0.16.0 → 0.18.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 (45) hide show
  1. package/CHANGELOG.md +359 -0
  2. package/README.md +97 -66
  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 +324 -47
  8. package/dist/PeriodSlider.d.ts.map +1 -1
  9. package/dist/VirtualDateDropdown.d.ts +19 -1
  10. package/dist/VirtualDateDropdown.d.ts.map +1 -1
  11. package/dist/YearSelector.d.ts +4 -2
  12. package/dist/YearSelector.d.ts.map +1 -1
  13. package/dist/index.cjs +1 -1
  14. package/dist/index.js +2723 -2593
  15. package/dist/inputValue.d.ts +98 -21
  16. package/dist/inputValue.d.ts.map +1 -1
  17. package/dist/optionText.d.ts +1 -1
  18. package/dist/optionText.d.ts.map +1 -1
  19. package/dist/selectorMemo.d.ts +14 -0
  20. package/dist/selectorMemo.d.ts.map +1 -1
  21. package/dist/selectorStep.d.ts +25 -30
  22. package/dist/selectorStep.d.ts.map +1 -1
  23. package/dist/useCommittedRef.d.ts +99 -0
  24. package/dist/useCommittedRef.d.ts.map +1 -0
  25. package/dist/usePeriodSlider.d.ts +74 -40
  26. package/dist/usePeriodSlider.d.ts.map +1 -1
  27. package/dist/useUncontrolledSelection.d.ts +40 -0
  28. package/dist/useUncontrolledSelection.d.ts.map +1 -0
  29. package/dist/vernierStep.d.ts +10 -1
  30. package/dist/vernierStep.d.ts.map +1 -1
  31. package/package.json +1 -1
  32. package/src/DateSelector.tsx +34 -67
  33. package/src/MonthSelector.tsx +24 -57
  34. package/src/PeriodSlider.tsx +614 -198
  35. package/src/VirtualDateDropdown.tsx +90 -46
  36. package/src/YearSelector.tsx +34 -56
  37. package/src/inputValue.ts +159 -21
  38. package/src/optionText.ts +3 -5
  39. package/src/selectorMemo.ts +18 -3
  40. package/src/selectorStep.ts +46 -58
  41. package/src/useCommittedRef.ts +236 -0
  42. package/src/usePeriodSlider.ts +536 -289
  43. package/src/useUncontrolledSelection.ts +83 -0
  44. package/src/valueSet.ts +1 -1
  45. package/src/vernierStep.ts +19 -17
package/CHANGELOG.md CHANGED
@@ -4,6 +4,365 @@ 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.18.0 (2026-10-02)
8
+
9
+ 単位を受け取るすべての公開の入口 (本体・4 つのフック・公開の純関数) が、`"year"` / `"month"` / `"day"` 以外の単位を日として読まず、
10
+ 名指しの `RangeError` で拒否するようにした版です。あわせて、ノギスの本体が描かない平レールの候補を読まないようにしました。
11
+ 3 セレクタ・4 つのフック・本体は描画中にステートを書かず、描画が導いた値をその確定で記録します (Suspense が保留した移行の間に選んだ値が描かれ、
12
+ 取り込み・収め直し・畳み込みの更新は、同じ値を描く 2 回目の確定を伴います)。`DateSelector variant="dropdown"` のポップアップは、移行が保留している間も
13
+ 画面に描かれている一覧だけを読み、配置だけが変わる描画では描かれている行を描き直しません。
14
+ 3 セレクタ (`YearSelector` / `MonthSelector` / `DateSelector`) の拒否メッセージを、本体・4 つのフック・公開の純関数と同じ 1 つの形へ揃えました
15
+ (この変更では、拒否する入力・判定の順序・例外型 (`RangeError`) は変わらず、変わるのはメッセージの文言だけです)。
16
+ **新しい Props・オプションを渡さないホストでも、下の「変更」の各点で挙動が変わります**
17
+ (型検査を経ずに単位を渡しているホスト (JavaScript・キャスト・型の無いデータから組んだ単位)、ノギスの `macroUnit` / `microUnit` に `null` を渡しているホスト、
18
+ ノギスに `allowedDates` を渡しているホスト、ノギスの `macroIsDiscrete` / `microIsDiscrete` に真偽値以外を渡しているホスト、ノギスでマウントしたスライダーを `range` / `value` を渡さずに range / point へ切り替えるホスト、
19
+ `formatOptionText` の単位の拒否メッセージや、宣言外の単位と他の不正な引数を同時に渡したときの拒否メッセージ、候補の一覧の拒否メッセージを照合するテスト、
20
+ セレクタ・フックのホスト・本体の確定を `Profiler` で数えるテスト、隠れた `<Activity>` の中でセレクタの `value` / `initialDate` やフックの境界を動かして戻すホスト、
21
+ `DateSelector variant="dropdown"` のポップアップを開いたまま `formatOption` の呼び出しや `Profiler` の確定を数えるテスト、
22
+ 3 セレクタの拒否メッセージを照合するテスト)。
23
+ 単位の判定は、`PeriodSliderUnit` を型どおりに渡す TypeScript のホストには影響しません。
24
+
25
+ ### 変更
26
+
27
+ - **宣言外の単位は名指しの `RangeError` になります**。`PeriodSlider` の `unit` (全モード) と `macroUnit` / `microUnit` (`vernier`)、4 つのフックの同名のオプション、
28
+ `normalizeDateByUnit` / `encode` / `decode` / `addUnit` / `getMacroWindowStartDate` / `getMacroWindowEndDate` / `resolveMacroWindow` / `findNearestDateIndex` /
29
+ `getSortedAllowedDates` / `formatLabel` / `formatScreenReaderLabel` / `calculateConnectDragValues` が、`resolveSelectorSteps` / `resolveVernierSelectorSteps` /
30
+ `formatOptionText` と同じ 1 つの判定と文言で拒否します (`encode: unit must be one of "year", "month", "day" (received: "decade")`)。これまでは日として読まれ
31
+ (`"decade"` のレールは日で描かれ・数えられ・歩かれました)、`formatLocale` を渡した `formatLabel` は Intl の既定の書式 (`1/15/2024`) で描き、
32
+ `customFormat` は宣言外の単位をそのまま受け取っていました。`findNearestDateIndex` / `getSortedAllowedDates` は空の一覧でも、`calculateConnectDragValues` は単位を読まない
33
+ 連続モードでも拒否し、`formatLabel` / `formatScreenReaderLabel` は Invalid Date でも `""` を返さずに拒否します。
34
+ - **単位は `yearStartMonth`・日付・`amount`・候補の一覧より先、無効日付の短絡・早期 return (`findNearestDateIndex` / `getSortedAllowedDates` の空の一覧、
35
+ `calculateConnectDragValues` の連続モードを含む) より先に判定します** (`formatOptionText` と同じ順序。`resolveSelectorSteps` / `resolveVernierSelectorSteps` は
36
+ これまでどおり、オプションがオブジェクトであること (`resolveVernierSelectorSteps` は `row` / `shows` も) を先に判定します)。宣言外の単位と他の不正な引数を同時に渡すと、単位の文言で拒否します
37
+ (`normalizeDateByUnit("decade", new Date(NaN))` はこれまで `normalizeDateByUnit: d must be a valid Date (received: Invalid Date)` でした)。
38
+ - **ノギスの `macroUnit` / `microUnit` を `unit` へ畳むのは省略 (`undefined`) のときだけです**。`null` は `RangeError` です
39
+ (`PeriodSlider: macroUnit must be one of "year", "month", "day" (received: null)`)。これまで本体は `null` を `unit` と読んでいました。
40
+ - **`formatOptionText` の宣言外の `unit` のメッセージを他の入口と同じ文言にしました**: `formatOptionText: unit must be "year", "month" or "day" (received: ...)` →
41
+ `formatOptionText: unit must be one of "year", "month", "day" (received: ...)`。
42
+ - **ノギスの `PeriodSlider` は、共有の `allowedDates` を、自分の一覧を省略した離散の行の読み出しでだけ読みます**。これまではノギスでも平レールの読み出しが
43
+ `allowedDates` を `unit` で読み (ノギスは平レールを描かないため、描画にも操作にも使われない読み出しでした)、配列でない値・有効な Date でない要素・
44
+ `unit` の始まりが表現範囲の外にある要素・`unit` での全滅を拒否していました。継ぐ行の無いノギス (離散のフラグを降ろした行と、自分の一覧を持つ行だけの構成) は
45
+ `allowedDates` を読まず、検証もしません。継ぐ行は一覧をその行の単位でだけ判定します (`unit="day"` / `macroUnit="month"` / `minDate` 2024-03-15 のノギスで
46
+ マクロ行が継ぐ `[2024-03-01]` は、日の単位では全滅でも月の単位では定義域に入るため受け付けます。`unit` がより粗いときにだけ始まりが表現範囲の外に出る要素は、
47
+ 行の単位で定義域の外として除かれます)。描画と操作は変わりません。
48
+ - **継いだ `allowedDates` の拒否は、どの誤りでも継いだ行を名乗ります**: `PeriodSlider: allowedDates must be an array of Dates (received: null)` →
49
+ `PeriodSlider: allowedDates (inherited by the micro row) must be an array of Dates (received: null)`、
50
+ `PeriodSlider: allowedDates[3] must be a valid Date (received: "x")` → `PeriodSlider: allowedDates[3] (inherited by the micro row) must be a valid Date (received: "x")`
51
+ (マクロ行が継いだときは `(inherited by the macro row)`)。両方の行が継ぐとき、また両方の行の自分の一覧が不正なときは、ミクロ行を先に読んで名乗ります
52
+ (ノギスのフックと同じ行。これまではマクロ行の `macroAllowedDates` を先に報告していました)。
53
+ - **本体の `macroIsDiscrete` / `microIsDiscrete` は、ノギスのフックと同じく `true` だけを離散と読みます**。これまで本体は `1` や `"yes"` などの真と評価される値も
54
+ 離散と読み、その行の候補の一覧を読んで検証していました (フックはその行を連続と読み、一覧を検証せずに `sliderProps` へ渡していました)。型検査を経ずに真偽値以外の
55
+ フラグを渡すホストでは、その行は連続のレールになります。
56
+ - **ノギスでマウントしたスライダーを、`range` / `value` を渡さない `mode="range"` / `"point"` へ切り替えると、そのモードの `defaultRange` / `defaultValue` から始まります**
57
+ (ミクロ選択の制御・非制御を問わず、新しくマウントした場合と同じ位置)。これまでは、マウント時のミクロ選択 (その後の操作を反映しない) を `unit` へ写した値
58
+ (`allowedDates` があればその候補へ寄せた値) から始まっていました。平レールを最初に操作するまでは `defaultRange` / `defaultValue` の変更に従います
59
+ (後から `vernier` へ切り替えたときのミクロ選択と同じ規則)。平レールでマウントしたスライダーの選択は、ノギスを往復しても保たれます。
60
+ - **取り込み・収め直し・畳み込みを描画中にステートへ書かず、描画が描いた値をその確定のレイアウト副作用で記録します** (セレクタの `initialDate` の取り込みと
61
+ 制御の描画、4 つのフックの境界・候補・窓への収め直し、本体のミクロ形態の切り替えで畳む非制御のミクロ選択と前面つまみ)。描く値と最初の確定は変わりませんが、
62
+ これらの更新は同じ値を描く 2 回目の確定を伴い、多くの場合で確定が 1 回増えます (jsdom の `Profiler` で数えた例: `DateSelector` / `MonthSelector` / `YearSelector` の取り込み 1 → 2、制御と非制御の切り替え 1 → 2
63
+ (`DateSelector variant="dropdown"` で `value` を渡す切り替えは 2 のまま)、`usePeriodSliderPoint` / `usePeriodSliderRange` の境界の移動による収め直し 1 → 2、
64
+ ノギスのフックの境界の移動によるマクロ窓の収め直し 1 → 2、本体のミクロ形態の期間から時点への切り替え 1 → 2。`DateSelector variant="dropdown"` の取り込みと、
65
+ 時点から期間への切り替えは 2 のまま)。2 回目の確定は描画前に同期で行われます。`DateSelector variant="dropdown"` の `formatOption` の呼び出し回数は
66
+ 変わりません (取り込みと切り替えで 2 回のまま)。`usePeriodSliderPoint` / `usePeriodSliderRange` のマウントはレールへ置いた初期値でステートを始めるため、
67
+ マウントの確定は 1 回のままです。`useVernierSliderPoint` / `useVernierSliderRange` に離散のミクロレールへ載らない初期値を渡したマウントは、確定が 1 → 2 回になります。
68
+ 隠れた `<Activity>` の中の確定は記録せず、表示したときにその描画の Props で記録します。そのため、隠れている間に `value` を渡して外す、または `initialDate` を
69
+ 別の単位へ動かして戻すと、表示したセレクタは隠す前の選択を描きます (これまでは `initialDate` を取り込み直していました)。隠れている間に境界を狭めて戻したフックは、
70
+ 畳む前の値を描きます (これまでは畳んだ値のままでした)。
71
+ - **`DateSelector variant="dropdown"` のポップアップは、開いている間に配置だけが変わる描画 (ページのスクロール・リサイズへの追従) で、描かれている選択肢の行を描き直しません**。
72
+ 行を描き直すのは、選択肢の一覧・保持値の行・アクティブ行のいずれかが変わる描画だけです (高さが変わって新しく描く行は描きます)。`formatOption` の呼び出しを数えるテストでは、
73
+ 開いている間のページのスクロール・リサイズ 1 回あたりの呼び出しが描画行数ぶんから 0 回になり (jsdom の実測で 37 回 → 0 回)、開いたまま件数を縮めた描画の呼び出しも
74
+ 行の描き直し 1 回分減ります (45 回 → 23 回)。`Profiler` で数える確定の回数は、スクロール・リサイズへの追従と件数の縮小で、スクローラが間引いて通知する範囲の時機により
75
+ jsdom でも実行ごとに 1 回ずれます (この版でも 0.17.0 でも、スクロール・リサイズで 1〜2 回、件数の縮小で 2〜3 回が出ます) ので、固定の回数で照合しないでください。
76
+ 開く・矢印キー・先頭一致入力・`End`・`Escape` の確定の回数は変わりません。
77
+ - **3 セレクタの拒否メッセージを、本体・フック・公開の純関数と同じ形 `<部品名>: <パス> <要件> (received: <値>)<直し方>` へ揃えました**。
78
+ パスを引用符で囲まず (これまでは `YearSelector` / `MonthSelector` と、`DateSelector` の `value` / `initialDate` の欠落のメッセージがバッククォート、それ以外の `DateSelector` が二重引用符)、受け取った値を `(received: ...)` に入れ
79
+ (これまでは `, received ...` / `(received ...)`)、理由は括弧の前に、直し方は閉じ括弧の後に `; ...` で続け、末尾に句点を付けません (これまでは `YearSelector` /
80
+ `MonthSelector` の文と、`DateSelector` の `value` / `initialDate` の欠落の文が句点で終わっていました)。例: `YearSelector: minDate must fall in a year that starts inside the Date range (received: -271821-04-20T00:00:00.000Z); declare the years to offer with minYear / maxYear or allowedYears instead of a sentinel for "no bound"`
81
+ (これまでは ``YearSelector: `minDate` must fall in a year that starts inside the Date range, received -271821-04-20T00:00:00.000Z; declare the years to offer with `minYear` / `maxYear` or `allowedYears` instead of a sentinel for "no bound".``)。
82
+ - **同じ条件は、本体・フックと同じ検証が同じ文言で拒否します**: 候補の一覧の形 (`<部品名>: allowedYears must be an array of Dates (received: ...)` など)、
83
+ 単位の始まりが Date の表現範囲の外にある日付 (`<部品名>: <パス> must fall in a <year|month|day> that starts inside the Date range (received: ...)`。
84
+ `DateSelector` の `fall on a day` は `fall in a day` になります)、`formatLocale` (`<部品名>: formatLocale must be a valid BCP 47 language tag (received: ...)`)、
85
+ `stepper` のフィールド (`<部品名>: stepper.onStep must be a function (received: ...)` など) と非制御での `stepper` (`<部品名>: stepper requires the controlled value; ...`)。
86
+ `DateSelector` の `variant="split-dropdown"` が年を描くための検査は、理由を添える `DateSelector` 自身の文言のままです (`..., because variant="split-dropdown" draws its year (received: ...)`)。
87
+ - **セレクタごとに違っていた文言を揃えました**。解決した境界の逆転は `<部品名>: the resolved upper bound must not precede the resolved lower bound (lower: ..., upper: ...)`
88
+ (これまでは `YearSelector` が `the resolved lower bound 2031 is after the resolved upper bound 2030.`、`MonthSelector` が同じ文を月で (`the resolved lower bound 2031-01 is after the resolved upper bound 2030-12.`)、`DateSelector` が
89
+ `the resolved range is empty (min ... is after max ...)`)。境界の欠落は `requires a lower bound (minYear or minDate) and an upper bound (maxYear or maxDate), or <一覧>; the option list is never invented`
90
+ (`variant="split-dropdown"` は `, or <一覧>` なし。バリアントを持たない `YearSelector` は `a lower bound (minYear or minDate) and an upper bound (maxYear or maxDate), or allowedYears, are required; the option list is never invented`。
91
+ これまでは `DateSelector` が `needs a bounded range; supply minDate/minYear and maxDate/maxYear ...`、`MonthSelector` が `the option window is never invented`、
92
+ `YearSelector` が `the year option list is never invented`)。`DateSelector` の年 Props は `whose first day starts inside` / `whose last day starts inside` (これまでは `is inside`) です。
93
+ - **番兵の境界に添える直し方は、本体と同じ `; <直し方> instead of a sentinel for "no bound"` の形です** (Props 名の引用符と、`instead` の前のカンマを外しました)。
94
+
95
+ ### 修正
96
+
97
+ - **ノギスのフックが `macroUnit` / `microUnit` の `null` を日と読み、本体は `unit` と読んでいた食い違いを直しました**。フックは `null` をそのまま
98
+ `sliderProps` へ渡すため、`unit: "month"` のフックの `shiftMacroRange(1)` が窓を 1 日動かす一方で、本体は月のレールを描いていました。どちらも同じ `RangeError` で拒否します。
99
+ - **ノギスのフックが受け付けた `allowedDates` で、その `sliderProps` を描く `PeriodSlider` が落ちていた食い違いを直しました**。離散のフラグを降ろした
100
+ `useVernierSliderRange` / `useVernierSliderPoint` は `null` などの一覧を受け付けてそのまま `sliderProps` へ渡す一方、本体は描かない平レールの読み出しで
101
+ それを拒否していました。本体とフックは同じ一覧を同じ行の単位で読み、行を離散と読むのも同じくフラグが `true` のときだけです。
102
+ - **非制御のセレクタで、Suspense が保留した移行の間に利用者が選んだ値が描かれなかった退行を直しました** (0.17.0 で `initialDate` の取り込みを描画のうちへ移したときに
103
+ 入りました)。非制御の `YearSelector` / `MonthSelector` / `DateSelector` で、`startTransition` で `initialDate` を別の単位へ動かした、または `value` を渡した移行が
104
+ Suspense で保留されている間に、利用者が ◀▶・選択肢・入力で選ぶと、`onChange` は選んだ値で鳴るのに、セレクタは選ぶ前の値を描き続けていました
105
+ (保留した描画が描画中に記録した取り込みを React が設定関数の即時の計算の基準に残し、選んだ値が取り込み直しで消えていました)。同期の事象でも `await` した事象でも起きていました。
106
+ - **`usePeriodSliderPoint` で、保留した移行が境界を動かして日付を収め直している間に、収め直し先と同じ Date オブジェクト (`minDate` / `maxDate` として渡したもの) を
107
+ `setValue` へ渡すと、別の理由で描き直されるまで描かれなかった問題を直しました**。
108
+ - **4 つのフックで、`startTransition` の中で呼んだ返す関数 (`setRange` / `setValue` / `setMicroRange` / `setMicroValue` など) の値が Suspense で保留している間に、
109
+ 境界・候補・窓の緊急の変化が確定済みの値を収め直すと、移行が確定したときに渡した値ではなく収め直した値が残っていた問題を直しました** (0.17.0 にもありました)。
110
+ 利用側へは渡した値を通知したまま (`setRange` などは自分で書いたまま)、収め直した値は通知されませんでした。収め直しの記録は、その描画が読んだステートにだけ当たり、
111
+ 保留中の受け渡しを上書きしません。
112
+ - **`DateSelector variant="dropdown"` のポップアップは、`startTransition` で渡した境界・`allowedDates`・`formatLocale`・`formatOption` が Suspense で保留している間も、
113
+ 画面に描かれている選択肢の一覧だけを読みます**。これまでは確定しなかった描画の一覧が内部に残り、先頭一致入力はその一覧で添字を引いて画面の一覧では別の日の行へ移り
114
+ (続く `Enter` はその別の日を発行し、`maxDate` を広げる移行の保留中に `2024` を打って `Enter` を押すと、2024-12-31 ではなく 2024-01-01 を発行していました)、ポップアップをホイールや
115
+ スクロールバーで送るとスクローラが描き足す行は保留中の一覧の日付を名乗っていました (その行の押下は、名乗った日ではなく画面の一覧の同じ位置の日を発行していました)。
116
+ キーボードの移動 (`ArrowDown` / `ArrowUp` / `Home` / `End` / `PageDown` / `PageUp`) は以前から画面の一覧を読んでいます。
117
+ - **開いたまま選択肢の件数が縮み、アクティブ行が一覧の外に出るとき、その行を指したままの確定を描かなくなりました**。これまでは件数を縮めた確定で `aria-activedescendant` が
118
+ 存在しない行の `id` を指し、`data-active="true"` の行が 1 つも無く (その間の `Enter` は何も発行せず)、次の確定でアクティブ行が末尾の行へ移っていました。件数を縮めた描画が
119
+ 末尾の行をアクティブ行として描きます。末尾の行へ移す規則と、件数が戻っても移した行に留まることは変わりません。
120
+
121
+ ### 移行
122
+
123
+ - 型検査を経ずに単位を渡していたホスト (JavaScript・キャスト・URL や JSON から組んだ単位) は、`"year"` / `"month"` / `"day"` のいずれかへ揃えてから渡してください
124
+ (大文字違い・空文字列・`null` も拒否します)。
125
+ - ノギスの `macroUnit` / `microUnit` に `null` を渡して `unit` と同じ単位を表していたホストは、その Props・オプションを省略 (`undefined`) してください。
126
+ - `formatOptionText` の単位の拒否メッセージを照合していたテストは、`formatOptionText: unit must be one of "year", "month", "day" (received: ...)` で照合してください。
127
+ - 宣言外の単位と他の不正な引数を同時に渡して、他の引数の文言を照合していたテストは、単位の文言 (`<入口名>: <引数名> must be one of "year", "month", "day" (received: ...)`)
128
+ で照合してください。
129
+ - ノギスで継いだ `allowedDates` の拒否メッセージを照合していたテストは、`(inherited by the micro row)` / `(inherited by the macro row)` 付きの文言で照合し、
130
+ 両方の行が継ぐ構成と両方の行の一覧が不正な構成ではミクロ行の文言で照合してください。
131
+ - 継ぐ行の無いノギスへ渡した `allowedDates` の拒否で不正な一覧を検出していたホストは、`getSortedAllowedDates` で一覧を検証してください。
132
+ - ノギスの `macroIsDiscrete` / `microIsDiscrete` に真偽値以外 (`1`・`"yes"`・一覧の長さなど) を渡して行を離散にしていたホストは、`true` を渡してください。
133
+ - ノギスから range / point へ切り替えたときにノギスで選んでいた期間を平レールの初期選択に使っていたホストは、その選択を `defaultRange` / `defaultValue`
134
+ (または制御の `range` / `value`) で渡してください。
135
+ - セレクタ・フックのホスト・本体の確定を `Profiler` で数えていたテストは、取り込み・収め直し・畳み込みの更新と、離散のミクロレールに載らない初期値で
136
+ マウントしたノギスのフックの確定を 1 回多く数えてください (上の「変更」の一覧)。
137
+ - 隠れた `<Activity>` の中で `value` を渡して外す、または `initialDate` を別の単位へ動かして戻すことでセレクタに `initialDate` を取り込ませていたホストは、
138
+ 表示した後に `initialDate` を別の単位へ動かすか、`key` を変えてセレクタをマウントし直してください。
139
+ - `DateSelector variant="dropdown"` のポップアップを開いたまま `formatOption` の呼び出しや `Profiler` の確定を数えていたテストは、配置だけが変わる描画
140
+ (ページのスクロール・リサイズへの追従) と件数を縮めた描画で、描かれている行の描き直しによる `formatOption` の呼び出しを数えず、スクロール・リサイズへの
141
+ 追従と件数の縮小の確定の回数が実行ごとに 1 回ずれることを許してください (上の「変更」)。
142
+ - 3 セレクタの拒否メッセージを照合していたテストは、新しい文言で照合してください。主な置き換えは次のとおりです (型と、拒否する入力は変わりません)。
143
+ ``YearSelector: `value` must be a valid Date, received Invalid Date.`` → `YearSelector: value must be a valid Date (received: Invalid Date)`、
144
+ ``MonthSelector: `allowedMonths` must be an array of Dates, received null.`` → `MonthSelector: allowedMonths must be an array of Dates (received: null)`、
145
+ `DateSelector: "minDate" must fall on a day that starts inside the Date range (received ...)` → `DateSelector: minDate must fall in a day that starts inside the Date range (received: ...)`、
146
+ `DateSelector: "stepper.onStep" must be a function (received "next")` → `DateSelector: stepper.onStep must be a function (received: "next")`、
147
+ ``YearSelector: `stepper` requires the controlled `value`; ...`` → `YearSelector: stepper requires the controlled value; ...`、
148
+ ``YearSelector: either `value` (controlled) or `initialDate` (uncontrolled) is required; ...`` → `YearSelector: either value (controlled) or initialDate (uncontrolled) is required; ...`。
149
+ 解決した境界の逆転・境界の欠落・番兵の直し方は上の「変更」の文言で照合してください。
150
+
151
+ ## 0.17.0 (2026-10-01)
152
+
153
+ 候補の一覧 (`allowedDates` / `allowedYears` / `allowedMonths` / `macroAllowedDates` / `microAllowedDates`) が一覧かどうかを 1 つの規則で判定し、
154
+ 拒否メッセージが所有者と読んだ一覧を名乗るようにした版です。あわせて、単位の始まりが Date の表現範囲の外にある日付 (`new Date(-8.64e15)` など、
155
+ 表現範囲の最初の単位の日付) を、本体・4 つのフック・公開の純関数 (`getSortedAllowedDates` / `resolveMacroWindow` / `resolveSelectorSteps` /
156
+ `resolveVernierSelectorSteps`) が Invalid Date と同じく名指しで拒否します。
157
+ 4 つのフックと `useSelectorStepper` の返す関数は、最後に確定した描画の値だけを読みます (`startTransition` で渡したオプションが保留している間の誤りを直します)。
158
+ 3 セレクタは非制御の `initialDate` を、確定後のエフェクトではなく描画のうちに取り込みます。
159
+ 計算で Date の表現範囲を越える日付 (フックのシフトの和・`macro-connect` のパンで運ぶミクロ選択・マクロ窓の末尾) は、進む向きの定義域の端の外にあるものとして扱い、
160
+ 表現範囲の最後のマクロ期間へ届く窓も描けるようにし、0-99 年の窓が期間の末日で閉じるようにしました。
161
+ **新しい Props・オプションを渡さないホストでも、下の「変更」の各点で挙動が変わります**
162
+ (配列でない一覧 (`null`・単独の Date など) を渡しているホスト、ノギスの行の一覧に `null` を渡して共有の `allowedDates` を継がせていたホスト、
163
+ `minDate` に `new Date(-8.64e15)` のような番兵を渡しているホスト、表現範囲の最初の単位の日付をフックへ渡して定義域の端へクランプさせていたホスト、
164
+ 描画中にフックの返す関数を呼んで Props に追従しているホスト、
165
+ 非制御のセレクタの `initialDate` を同じ日・月・年の中で動かして利用者の選択を戻させていたホスト、`addUnit` へ整数でない `amount` を渡しているホスト、
166
+ 0-99 年の窓を描くノギス、セレクタの確定や `formatOption` の呼び出しを数えるテスト、
167
+ 候補の拒否メッセージや配列を含む拒否メッセージの文言を照合するテスト、`getMacroWindowStartDate` / `getMacroWindowEndDate` / `findNearestDateIndex` の `normalizeDateByUnit` の文言や Invalid Date の戻り値を照合するテスト、
168
+ 表現範囲の端でのフックのシフトの送出を照合するテスト)。
169
+
170
+ ### 変更
171
+
172
+ - **配列でない候補の一覧は、本体・フック・`getSortedAllowedDates` でも名指しの `RangeError` になります**。省略は `undefined` だけで、
173
+ `null`・単独の Date・文字列・配列風のオブジェクト・取り消した Proxy は指定値として拒否します (`PeriodSlider: allowedDates must be an array of Dates (received: null)`、
174
+ `usePeriodSliderRange: ...`、`getSortedAllowedDates: ...`)。これまで本体 (全モード) と `usePeriodSliderRange` / `usePeriodSliderPoint`、ノギスのフックの離散の行は
175
+ 黙って連続のレール (と連続の ◀▶) になり、`getSortedAllowedDates` は `[]` を返していました。ノギスのフックに行の 1 歩の規則を渡していた場合は、内部の関数名
176
+ (`resolveVernierSelectorSteps: microAllowedDates must be an array of Dates (...)`) で落ちていました。空配列の意味は変わらず (レールと 1 歩の関数は連続、
177
+ `resolveSelectorSteps` は押せる向きなし)、離散のフラグが降りている行はこれまでどおり一覧を読みません。
178
+ - **ノギスの行が共有の `allowedDates` を継ぐのは、行の一覧 (`macroAllowedDates` / `microAllowedDates`) を省略 (`undefined`) したときだけです**。`null` は行自身の
179
+ 一覧として拒否します (`PeriodSlider: microAllowedDates must be an array of Dates (received: null)`)。これまでは `undefined` と同じく共有の一覧を継いでいました。
180
+ - **本体とフックの候補の拒否メッセージは、所有者と読んだ一覧を名乗ります**。`getSortedAllowedDates: allowedDates[3] must be a valid Date (...)` は
181
+ `PeriodSlider: microAllowedDates[3] must be a valid Date (...)` のように、`getSortedAllowedDates: every allowedDates entry falls outside ...` は
182
+ `useVernierSliderRange: every macroAllowedDates entry falls outside ...` のようになります。共有の一覧を継いだ行は、その行も名乗ります
183
+ (`useVernierSliderRange: allowedDates[3] (inherited by the micro row) must be a valid Date (...)`)。本体は共有の `allowedDates` をモードやフラグに依らず
184
+ `unit` でも行より先に読むため、形の誤り・有効な Date でない要素・`unit` での拒否は行の名なしで報告し (`PeriodSlider: allowedDates[3] ...`)、本体で行の名が
185
+ 付くのは `unit` では通るのに行の単位で拒否される場合 (より細かい行の単位でだけの全滅と、より粗い行の単位の始まりが Date の表現範囲の外にある要素。
186
+ `PeriodSlider: allowedDates[0] (inherited by the macro row) must fall in a month that starts inside the Date range (...)`) です。
187
+ `getSortedAllowedDates` を直接呼んだときのメッセージは、配列でない指定値の拒否と、単位の始まりが Date の表現範囲の外にある境界・要素の拒否 (下記) が
188
+ 加わり、有効な Date でない境界の拒否が自身の名を名乗り (下記)、受け取った値が配列である要素の示し方が次項の規則に変わるほかは変わりません。
189
+ - **拒否メッセージが受け取った配列は、要素ごとに示します**。`[e0, e1, e2, ... n more]` の形で先頭の 3 要素までを示し、Date は ISO 8601、文字列は引用符付き、
190
+ 穴は `empty`、配列である要素は `Array(長さ)`、読み出しが投げる要素はその要素だけを `an object that cannot be converted to a string` とします。これまでは `String()` の形
191
+ (Date はタイムゾーン依存の `Mon Jan 01 2024 09:00:00 GMT+0900 ...`、`null`・`undefined`・穴は空、`[3]` は `3` と同じ表記、自身を含む配列は空文字) でした。
192
+ タプルの形のエラー (`PeriodSlider: defaultRange must be a [start, end] Date tuple (received: [...])` など) を含め、配列を受け取るすべての拒否メッセージが変わります
193
+ (`labels` / `locale` の検証はエンジンの形のまま)。
194
+
195
+ - **単位の始まりが Date の表現範囲の外にある `minDate` は、本体と 4 つのフックで名指しの `RangeError` になります**
196
+ (`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"`)。
197
+ 判定する単位は平レールが `unit`、ノギス (本体とフック) が `macroUnit`・`microUnit`・`unit` で、最初に外れた単位を名乗ります。`new Date(-8.64e15)` は
198
+ 月と年ではどの時間帯でも、日では UTC 以外で該当し、年の始まりは `yearStartMonth` と共に動きます。これまで本体の平レールは `aria-valuemin="NaN"` のまま描画し、
199
+ ノギスは `resolveMacroWindow: macroRange[0] must be a valid Date (received: Invalid Date)` で、`unit` が両レールより粗いノギスは
200
+ `normalizeDateByUnit: d must be a valid Date (received: Invalid Date)` で落ち、フックは黙って受け取って `sliderProps` とセレクタ Props へ渡していました。
201
+ `unit` が両レールより粗いノギスでは、`minDate` が表現範囲の最初の `unit` の期間にあれば、選択が後の期間にあって描画できていた構成も拒否されます。
202
+ UTC の日の単位のように始まりが範囲に入る場合は、これまでどおり定義域の判定を受けます。救済の文を添えるのは `minDate` のメッセージだけです。
203
+ - **本体の選択 Props と候補の要素も、描く単位で同じ規則により名指しします**。`value` / `defaultValue` / `range[i]` / `defaultRange[i]` (`unit`)、
204
+ `microRange[i]` / `defaultMicroRange[i]` / `microValue` / `defaultMicroValue` (`microUnit`) は、定義域の内包の判定より先に
205
+ `PeriodSlider: <Props 名> must fall in a <単位> that starts inside the Date range (received: ...)` になります (これまで `normalizeDateByUnit: d must be a valid Date (received: Invalid Date)`)。
206
+ `macroRange[0]` (`macroUnit`) も同じ形です (これまで `resolveMacroWindow: macroRange[0] must be a valid Date (received: Invalid Date)`)。`macroRange` のはみ出しは、
207
+ `macroRange[0]` のマクロ単位の始まりが範囲に入る限りこれまでどおり許されます。候補の一覧の要素は、所有者と一覧を名乗って
208
+ `PeriodSlider: allowedDates[1] must fall in a month that starts inside the Date range (...)` のようになります (これまで `normalizeDateByUnit: ...`)。
209
+ - **`getSortedAllowedDates` は、空でない一覧に対して単位の始まりが範囲の外にある `minDate` / `maxDate` を拒否します**
210
+ (`getSortedAllowedDates: minDate must fall in a month that starts inside the Date range (received: ...)` / `... maxDate ...`)。これまではその側のキーが `NaN` になって
211
+ 絞り込みが黙って外れ、正常に返っていました (`maxDate` が表現範囲の最初の単位にあると、`maxDate` より後の候補まで返していました)。要素は
212
+ `getSortedAllowedDates: allowedDates[i] must fall in a <単位> that starts inside the Date range (...)` です (これまで `normalizeDateByUnit: ...`)。
213
+ 有効な Date でない `minDate` / `maxDate` も、空でない一覧に対して `getSortedAllowedDates: minDate must be a valid Date (received: Invalid Date)` と自身の名で
214
+ 拒否します (これまで `normalizeDateByUnit: d must be a valid Date (received: Invalid Date)`。空の一覧はこれまでどおり境界を読まずに `[]` を返します)。
215
+ - **`resolveMacroWindow` は `macroRange[0]` を `macroUnit` と `microUnit` の両方で、`maxDate` を `microUnit` で判定します** (窓の開始をこの 2 つの単位で畳むため。
216
+ `resolveMacroWindow: macroRange[0] must fall in a month that starts inside the Date range (...)`、これまで `normalizeDateByUnit: ...`)。`maxDate` を判定するのは、
217
+ 窓の端を `maxDate` へクランプしてから `microUnit` で畳むためです (`resolveMacroWindow: maxDate must fall in a month that starts inside the Date range (...)`。
218
+ これまでは `maxDate` が表現範囲の最初のミクロ単位にあると、送出せずに Invalid Date の窓を返していました)。`minDate` は判定しません (`minDate` へクランプするのは、
219
+ 範囲に入るミクロ単位の始まりである窓の端より後にあるときだけのため)。
220
+ - **`resolveVernierSelectorSteps` は、`macroUnit` または `microUnit` の始まりが Date の表現範囲の外にある `minDate` を名指しで拒否します**
221
+ (`resolveVernierSelectorSteps: minDate must fall in a month that starts inside the Date range (received: ...)`。`macroUnit` を先に判定)。これまでは
222
+ `minDate` の符号化キーが `NaN` のまま 1 歩を解いていました。`maxDate` は厳密に後にあるため判定しません。
223
+ - **フックの初期値・入口・状態も、時刻でクランプせず名指しで拒否します**。`initialRange` / `initialValue` (`unit`)・`initialMacroRange` (`macroUnit`)・
224
+ `initialMicroRange` / `initialMicroValue` (`microUnit`) は毎描画で (マウント時の定義域の照合より先に)、平レールの `setLowerDate` / `setUpperDate` /
225
+ `selectorProps.onChange` / `sliderProps.onChangeRange` / `sliderProps.onChangePoint` (`unit`)、ノギスの `setMacroLowerDate` / `setMacroUpperDate` /
226
+ `sliderProps.onChangeMacroRange` (`macroUnit`)、`setMicroLowerDate` / `setMicroUpperDate` / `setMicroDate` / `sliderProps.onChangeMicroRange` /
227
+ `sliderProps.onChangeMicroPoint` (`microUnit`) は呼び出し時に、`setRange` / `setValue` / `setMacroRange` / `setMicroRange` / `setMicroValue` で書いた値は次の描画で、
228
+ `<フック名>: <名前> must fall in a <単位> that starts inside the Date range (received: ...)` になります。これまでは、黙って `minDate` や窓の端へクランプされるか、
229
+ 内部の関数の名 (`normalizeDateByUnit` / `clampPairIntoDrawnValues: low must be a finite integer (received: NaN)` /
230
+ `drawnValuesNearest: value must be a finite integer (received: NaN)`) で落ちるか、連続レールの時点では値を窓と定義域の外のまま保持していました。
231
+ 0.16.0 の「変更」(3) の `drawnValuesNearest` の送出は、こうして入口や Props の名指しの拒否に置き換わります。
232
+ - **フックの返す関数を描画中に呼ぶと、描画中の値ではなく最後に確定した描画の値を読みます**。4 つのフックと `useSelectorStepper` の返す関数
233
+ (設定関数・シフト・リセット・`sliderProps` / `SelectorProps` のコールバック・◀▶ の `onStep`) が読む境界・候補・コールバック・ステートは、確定の段階で写した値です
234
+ (下の「修正」)。Props に追従するため自分の描画中に設定関数を呼ぶホストでは、同じ描画で広げた `maxDate` ではなく前の確定の `maxDate` で収めます。
235
+ これまでは描画中の値を読んでいました。同じ描画の値で収めるには、副作用 (`useEffect` / `useLayoutEffect`) かイベントハンドラの中で呼んでください。
236
+ フック自身の値と比べて描画のたびに呼ぶ追従は、値が境界・候補・窓へ置き直される場合も、これまでどおり置き直した値で落ち着きます。
237
+
238
+ - **3 セレクタは非制御の `initialDate` を描画のうちに取り込みます**。取り込むのは、非制御になった描画 (マウントと、制御から非制御への切り替え) と、
239
+ `initialDate` が最後に取り込んだものと別の単位 (`DateSelector` は日、`MonthSelector` は月、`YearSelector` は `yearStartMonth` で区切った年。
240
+ `yearStartMonth` を変えた描画も含む) へ動いた描画で、その描画の最初の確定から取り込んだ値を描きます。取り込みは `onChange` を呼びません。
241
+ これまでは確定後のエフェクトで取り込んでいたため、その描画の確定は古い選択 (制御でマウントしていればマウント時の `value`、制御の前に非制御だったなら
242
+ そのときの選択) を描き (`DateSelector variant="dropdown"` の畳んだ表示と `MonthSelector variant="dropdown"` の集合外プレースホルダは古い日付で `formatOption` を呼び、
243
+ `YearSelector` は `yearStartMonth` の変更で `initialDate` を含まない年を選択中として描き)、取り込みのための確定がもう 1 回続いていました。
244
+ - **同じ単位の中で `initialDate` を動かしても、利用者の選択は置き換わりません**。これまでは時刻が動くと、メモ比較器が描画を省かなかったとき
245
+ (ほかの Props も変わった描画) だけ、◀▶・選択肢・入力で選んだ値が `initialDate` の単位へ戻りました (`initialDate={new Date()}` と描画ごとに作る `onChange` を
246
+ 渡すホストでは、親の再描画のたびに戻っていました)。別の単位への移動は、これまでどおり利用者の選択を置き換えます。
247
+ - 取り込む描画と、非制御から制御へ切り替える描画では、セレクタの本体が 2 回走ります (描画中の状態更新による再実行。確定は 1 回)。本体で呼ぶ `formatOption`
248
+ (`DateSelector variant="dropdown"` の畳んだ表示と `MonthSelector variant="dropdown"` の集合外プレースホルダ) は、その描画で同じ引数のまま 2 回呼ばれ得ます
249
+ (`DateSelector variant="dropdown"` を制御へ切り替える描画は 1 回から 2 回。集合の外の値を描く `MonthSelector variant="dropdown"` のプレースホルダは、
250
+ 制御へ切り替える描画と、保持中と同じ月の `initialDate` のまま非制御へ戻す描画で 1 回から 2 回)。非制御の `DateSelector` のマウントは 1 回の確定で済み (これまでは 2 回、
251
+ `variant="dropdown"` では 3 回)、`variant="dropdown"` の畳んだ表示の `formatOption` もマウントで 1 回になります (これまでは同じ日で 2 回)。`variant="dropdown"` の
252
+ コンボボックス内部の確定 (`formatOption` も `onChange` も呼ばない) 1 回は、マウントからマウント後の最初の更新 (どの更新でも) へ移ります (確定の総数は減ります)。
253
+
254
+ - **`addUnit` は表現範囲の最後の月 (275760 年 9 月) へ届く月・年の加算で正しい日付を返し、整数でない `amount` を拒否します**。
255
+ `addUnit("month", 275760-08-01, 1)` は 275760-09-01、`addUnit("year", 275759-09-12, 1)` は 275760-09-12 です (これまで Invalid Date)。Invalid Date を返すのは、
256
+ 和そのものが表現範囲を越えるとき (275760-08-31 の 1 か月後など) だけです。小数・`NaN`・`Infinity` は
257
+ `addUnit: amount must be an integer number of units (received: 1.5)` の `RangeError` になります。これまでは単位と日付によって別の向きへ切り捨てるか
258
+ (6 月の -1.5 か月は -2 か月、1 月の -1.5 か月は -1 か月、+1.5 日は +1 日)、Invalid Date を返していました。通常の入力の結果 (月末丸め・現地の時刻の保持) は変わりません。
259
+ ただし、加算先の月の末日の、元の日付と同じ現地時刻が夏時間の開始で飛ばされる場合 (Europe/Moscow の 1918-05-31・1919-05-31) は、これまで翌月の日付
260
+ (1919-08-15 22:00 の 15 か月前は 1918-06-01 00:00) を返していたのに対し、加算先の月の日付 (1918-05-15 22:00) を返します。
261
+ - **`getMacroWindowEndDate` は最後のミクロ単位をキーで数えます**。月 × 日は 0-99 年でもその年の月末日を返します (`0050-06-15` は `0050-06-30`。これまで `1950-06-30`)。
262
+ 開始月 8 の 275759 年の年 × 日は `275760-08-31` (これまで `normalizeDateByUnit: d must be a valid Date (received: Invalid Date)`)、開始月 9 の 275759 年の年 × 月は
263
+ `275760-09-01` (これまで Invalid Date) です。最後のミクロ単位の始まりが表現範囲の外にある期間 (275760 年 9 月の月 × 日、275760 年 9 月を含む年の年 × 日、275760 年 9 月より後の月で終わる年の年 × 月 (`yearStartMonth = 9` 以外の、275760 年 9 月を含む年)) は
264
+ `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`) の
265
+ `RangeError` です (これまでは黙って Invalid Date を返すか、`normalizeDateByUnit: ...` で落ちていました)。年 × 月は、年の初日に現地 0 時の無い時間帯でも末尾の月の
266
+ 現地 0 時を返します (Europe/Moscow の 1981-1984 年の開始月 3、America/Havana の 2012 年の開始月 3、America/Santiago の 1928 年・1932 年の開始月 8 など。
267
+ これまでは 1 時。America/Santiago の 1927 年の開始月 8 では 0 時 42 分)。始まりが表現範囲の外にある最初の年も、範囲に入る末尾の月・日を返します
268
+ (`new Date(-8.64e15)` の年 × 月は -271821-12-01、年 × 日は -271821-12-31。これまで Invalid Date / `normalizeDateByUnit: ...`)。月 × 日の下端 (-271821-04-30) は変わりません。
269
+ 同じ単位の組とマクロ単位のほうが細かい組は、これまでどおり `d` 自身のミクロ単位の始まりを返し、その始まりが表現範囲の外にある `d` を
270
+ `getMacroWindowEndDate: d must fall in a month that starts inside the Date range (received: ...)` で拒否します (これまでは黙って Invalid Date を返していました。
271
+ `new Date(-8.64e15)` は年 × 年・月 × 月・月 × 年・日 × 月・日 × 年ではどの時間帯でも、日 × 日では UTC 以外で該当します)。
272
+ - **マクロ窓が Date の表現範囲の最後のマクロ期間 (275760 年 9 月、またはそれを含む年) へ届いても解決します**。`resolveMacroWindow` は、末尾の期間が `maxDate` の期間か
273
+ それより後のとき、期間の末尾を組まずに `maxDate` のミクロ単位の始まりで窓を閉じます (末尾を組める窓では結果は変わりません)。これまでは `maxDate` が 275760-09-12 のような
274
+ 通常の日付でも `normalizeDateByUnit: d must be a valid Date (received: Invalid Date)` で落ちていたため、マクロ単位がミクロ単位より粗い `mode="vernier"` の本体は描画で、
275
+ `useVernierSliderRange` / `useVernierSliderPoint` はマウントで (`macroSelectorStep` / `microSelectorStep` を渡すと、1 歩の行き先の窓を解くため最後の期間の 1 つ手前の窓でも)、
276
+ `shiftMacroRange` は最後の期間へのシフトで (`resolveMacroWindow: macroRange[0] must be a valid Date (received: Invalid Date)`)、`resolveVernierSelectorSteps` は
277
+ 行き先の窓で落ちていました。月 × 日の 0-99 年の窓は期間の末日で閉じます (下の「修正」)。
278
+ - **4 つのフックのシフトは、和が Date の表現範囲を越えても Invalid Date を通知せず、通常の境界を越えた和と同じく止まるか中止します**
279
+ (表現範囲の両端で、どの時間帯でも、日・月・年のどの単位でも)。`shiftRange` / `shiftValue` は `minDate` / `maxDate` に着いて止まります (これまでは
280
+ `onChangeRange` / `onChangePoint` を Invalid Date で呼び、次の描画が `<フック名>: range[i] is required and must be a valid Date (received: Invalid Date)` /
281
+ `... value ...` で落ちていました)。`shiftMacroRange` (2 つのノギスのフック) と `shiftMicroRange` は、ステートを変えずコールバックも呼ばずに中止します
282
+ (これまで `normalizeDateByUnit: ...`・`resolveMacroWindow: macroRange[i] must be a valid Date (received: Invalid Date)`・
283
+ `clampPairIntoDrawnValues: low must be a finite integer (received: NaN)` で落ちていました)。`shiftMicroValue` は進む向きの窓の端へ着きます (これまでは落ちるか、
284
+ 次の描画が `useVernierSliderPoint: microValue must fall in a <単位> that starts inside the Date range` で拒む値を保持していました)。
285
+ - **`macro-connect` のパンは、暦の差分で表現範囲の外へ出たミクロ選択もキーのまま運び、長さを保って窓へ収めます**。`[275760-08-20, 08-31]` を 1 か月運ぶと
286
+ 9 月 20 日〜30 日になり、その長さのまま窓の末尾へ寄って `[最後の日の 10 日前, 最後の日]` になります。この経路はこれまで描画が先に落ちるため到達できず、
287
+ 到達すればポインターのハンドラから送出していました。通常のパンの結果 (月末丸め。1 月 31 日の 1 か月後は 2 月末日) は変わりません。
288
+ - **`findNearestDateIndex` と `getMacroWindowStartDate` は自分の引数を自分の名前で拒否します**。2 要素以上の一覧に対し、`findNearestDateIndex` は有効な Date でない `target` を
289
+ `findNearestDateIndex: target must be a valid Date (received: Invalid Date)`、単位の始まりが表現範囲の外にある `target` を
290
+ `findNearestDateIndex: target must fall in a month that starts inside the Date range (received: ...)` で拒否します (これまで
291
+ `normalizeDateByUnit: d must be a valid Date (received: Invalid Date)` / `(received: undefined)`)。0 要素・1 要素の一覧はこれまでどおり `target` を読まずに `0` を返します。
292
+ `getMacroWindowStartDate` は `d` の `macroUnit`・`microUnit` の始まりが表現範囲の外なら、この順に判定して
293
+ `getMacroWindowStartDate: d must fall in a month that starts inside the Date range (received: ...)` で拒否します (これまで
294
+ `normalizeDateByUnit: d must be a valid Date (received: Invalid Date)` で落ちるか、マクロ単位がミクロ単位より細かい組では Invalid Date を返していました)。
295
+
296
+ ### 修正
297
+
298
+ - **3 セレクタは配列でない `allowedDates` / `allowedYears` / `allowedMonths` を、Props 名を名乗る `RangeError` で拒否します**
299
+ (`DateSelector: "allowedDates" must be an array of Dates (received null)`、`` YearSelector: `allowedYears` must be an array of Dates, received null. ``、
300
+ `` MonthSelector: `allowedMonths` must be an array of Dates, received null. ``)。これまでは名前を名乗らない `TypeError` になり、文字列は 1 文字ずつ要素として読まれて
301
+ `` `allowedYears[0]` must be a valid Date, received "2". `` のように別のものを名指していました。`DateSelector variant="split-dropdown"` は従来どおり、形を問う前に
302
+ この変種では `allowedDates` を使えないと名乗ります。
303
+ - **取り消した Proxy を一覧やタプルとして渡しても、マウントでも再描画でも Props・オプション名を名乗る `RangeError` になります**
304
+ (`(received: an object that cannot be converted to a string)`)。これまでは配列の判定 (`Array.isArray`) 自身が名前の無い `TypeError` を投げ、`PeriodSlider` では
305
+ 再描画のメモ比較器からも投げていました (`range` / `defaultRange` などのタプル、`allowedDates` / `macroAllowedDates` / `microAllowedDates`、フックの初期値のタプル、
306
+ `resolveSelectorSteps` / `resolveVernierSelectorSteps` の選択・窓・候補)。
307
+
308
+ - **表現範囲の最初の単位の日付が、定義域の判定をすべて素通りしていた欠陥を直しました**。その日付の符号化キーは `NaN` で、`NaN` はどの大小比較にも
309
+ 掛からないため、平レールは `aria-valuemin="NaN"` で描かれ、`getSortedAllowedDates` は片側の絞り込みを外して定義域の外の候補を返し、
310
+ ノギスのフックの連続レールは時点を窓と定義域の外のまま保持していました。判定を 1 つの関数に集め、セレクタの 1 歩の関数 (`resolveSelectorSteps` /
311
+ `resolveVernierSelectorSteps`) と同じ判定と文言で拒否します。利用側から見える違いは上の「変更」のとおりです。
312
+
313
+ - **4 つのフックと `useSelectorStepper` の返す関数は、最後に確定した描画の境界・候補・コールバック・ステート・◀▶ の行き先だけを読みます**。
314
+ 0.16.0 までは、確定経路が事象の時点で読むこれらの値をレンダー中に ref へ写していました。React は確定しない描画 (`startTransition` で渡したオプションが
315
+ Suspense で中断して保留している間の描画、割り込まれた並行描画) でも本体を走らせるため、移行が保留している間に確定した描画の設定関数・
316
+ `sliderProps` のコールバック・シフト・リセット・◀▶ を呼ぶと、次のように振る舞いました。
317
+ - (1) 保留中の `minDate` / `maxDate` で収めた。ノギスのマクロのシフトは、保留中の境界を越えると中止した。
318
+ - (2) 保留中の `allowedDates` / `macroAllowedDates`・`unit`・`yearStartMonth` で解決した候補へ寄せ、その上を歩いた。
319
+ - (3) 確定していない描画が渡したコールバックを呼んだ。
320
+ - (4) 保留中の描画が畳んだステートを起点にした。ノギスでは、動かしていないマクロ窓を畳んだ値で通知しながらステートは変えず、利用側とフックが別の窓を
321
+ 持つことがあった。平レールでは、保留中の描画が畳んだ値と同じ値へ動かす操作を、通知だけして保存しないことがあった。
322
+ - (5) ◀▶ が保留中の描画の行き先へ送るか、何もしなかった。
323
+
324
+ 写しは挿入副作用 (`useInsertionEffect`) で行うため、子孫のレイアウト副作用から呼んでも、隠れた `Activity` の中でも、その確定の値を読みます。
325
+ 返す関数が事象の処理中に書いたステートの写しは、その後に確定した描画がそれより前に走っていれば上書きしないため、時間分割した描画がフックのホストを
326
+ 描いた後で譲っている間の呼び出しも、これまでどおり効きます。確定経路は、返す関数が最後にステートへ渡したオブジェクトを写しが持つ間だけ
327
+ 同じ値を渡すのを省き、それ以外は写しと同じ値でも渡すため、`startTransition` の中で呼んだ設定関数が中断している間に別の描画が確定し、そのあとで
328
+ 設定関数・リセットを呼んでも、保存される値は最後に通知した値と一致します。中断している値と同じ値の緊急の呼び直しは、
329
+ その間にホストが描き直されていなければ、これまでどおりその値を緊急の優先度へ引き上げず (代替表示を出さず)、更新の後の同じ値の呼び直しも
330
+ ホストを描き直しません。
331
+ 関数・Props の同一性と拒否メッセージの文言は変わりません。
332
+
333
+ - **`DateSelector variant="split-dropdown"` を制御から非制御へ切り替えた描画は `RangeError` を投げなくなりました**。以前の非制御の描画が -271821 年に残した選択は、
334
+ 切り替えた描画が `initialDate` を取り込んで置き換えるため描かれません。制御を挟んで同じ `initialDate` のまま非制御へ戻した描画も、`initialDate` を
335
+ 取り込み直すため送出しません。日だけを描く変種で利用者が -271821 年へ動かした選択を保持したまま `variant="split-dropdown"` へ切り替える描画も、
336
+ 同じ描画で別の日の `initialDate` を渡せば通ります (最後に取り込んだ日と同じ日に置いたままなら、これまでどおり `variant="split-dropdown"` を名乗る `RangeError`)。
337
+ メッセージの文言は変わりません。
338
+
339
+ - **0-99 年のノギスの窓の末尾が 1900 年代へ写っていた欠陥を直しました**。月 × 日の窓の末尾を `new Date(y, m + 1, 0)` で組んでいたため、0-99 年では 1900 年代の日付になり、
340
+ 窓は `maxDate` へのクランプで閉じていました。ミクロレール (50 年 6 月の窓のミクロ終了つまみの `aria-valuemax` は、`0060-01-01` の `-697613` ではなく `0050-06-30` の `-701085`)、
341
+ フックの収め込み (`shiftMicroRange` は期間の末日で中止し、`shiftMicroValue` は末日で止まります。これまでは翌月 (`0050-07-01`) へ動いていました)、
342
+ ミクロセレクタの境界 (`microEndSelectorProps.maxDate` など) が、実際の期間を張ります。
343
+ - **表現範囲の最後の月へ届く月・年の加算が、表現できる結果を Invalid Date にしていた欠陥を直しました**。加算先の月末を先に組む実装 (date-fns の `addMonths` / `addYears`) が、
344
+ 途中の月末で表現範囲を越えていました。月・年の加算は暦の算術 (`shiftCivilMonths`) で年月日を 1 度に書きます。
345
+
346
+ ### 移行
347
+
348
+ - 配列でない値で「候補なし (連続のレール)」を表していたホストは、一覧を省略 (`undefined`) するか `[]` を渡してください。
349
+ - ノギスの行の一覧に `null` を渡して共有の `allowedDates` を継がせていたホストは、その行の一覧を省略 (`undefined`) してください。
350
+ - 本体やフックの候補の拒否メッセージを `getSortedAllowedDates:` で照合していたテストは、所有者 (`PeriodSlider` / `usePeriodSliderRange` / `usePeriodSliderPoint` /
351
+ `useVernierSliderRange` / `useVernierSliderPoint`) と読んだ一覧 (継いだ行を含む) で照合してください。`getSortedAllowedDates` を直接呼ぶ場合、既存の拒否の文言は、
352
+ 配列を示す部分と、有効な Date でない境界の拒否 (`normalizeDateByUnit:` から `getSortedAllowedDates:` へ) を除いて変わりません。
353
+ - 受け取った配列を `String()` の形で照合していたテストは、要素ごとの形 (README「実行時バリデーション (Fail Fast)」の受け取った値の規則) へ改めてください。
354
+ - `minDate` に `new Date(-8.64e15)` のような番兵を「下限なし」として渡していたホストは、提示したい最も早い日付を渡してください (`minDate` は必須です)。
355
+ - 表現範囲の最初の単位の日付をフックの設定関数・コールバックへ渡して定義域の端へクランプさせていたホストは、`minDate` そのものか定義域の中の日付を渡してください。
356
+ - これらの日付の拒否を `normalizeDateByUnit:` / `resolveMacroWindow: macroRange[0] must be a valid Date` / `clampPairIntoDrawnValues:` / `drawnValuesNearest:` で照合していた
357
+ テストは、所有者と Props・入口の名前を名乗る `must fall in a <単位> that starts inside the Date range` で照合してください。
358
+ - 描画中にフックの返す関数 (設定関数など) を呼んで Props に追従していたホストは、副作用 (`useEffect` / `useLayoutEffect`) かイベントハンドラの中で呼んでください
359
+ (描画中の呼び出しは最後に確定した描画の値を読みます)。
360
+ - 非制御のセレクタへ同じ日・月・年の中で動く `initialDate` を渡して利用者の選択を戻させていたホストは、`value` で制御するか、`key` を変えて作り直してください
361
+ (別の単位への移動は、これまでどおり取り込みます)。
362
+ - `addUnit` へ整数でない `amount` を渡していたホストは、整数へ丸めてから渡してください (切り捨ての向きは単位と日付で揃っていませんでした)。
363
+ - `getMacroWindowStartDate` / `getMacroWindowEndDate` / `findNearestDateIndex` の拒否を `normalizeDateByUnit:` で照合していたテストと Invalid Date の戻り値を照合していたテスト、
364
+ 表現範囲の端でのフックのシフトの送出を照合していたテストは、新しい文言 (README「年を扱う 8 つのヘルパー」) と、止まる・中止する挙動で照合してください。
365
+
7
366
  ## 0.16.0 (2026-10-01)
8
367
 
9
368
  セレクタの ◀▶ を所有者へ引き渡す口と、◀▶ が期間・ノギスの窓をどう動かすかを 1 か所で決める規則を加えた版です。