@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/README.md CHANGED
@@ -66,7 +66,7 @@
66
66
  - **高いアクセシビリティ**: WAI-ARIA `slider` ロール、キーボード操作 (矢印キー, PageUp/Down, Home/End) 完全準拠 (Vernier ノギスハンドル含む)。
67
67
  - **`Shift` + ホイールによる平行移動**: スライダーの範囲領域 (レールの行・つまみとラベルが描かれる帯 — レール方向にもラベルの外縁まで — ・ステッパー) のどこでも `Shift` を押しながらホイールを回すと、選択がステッパーと同じ ±1 単位だけ平行移動します。インジケーターの真上である必要はありません。`Shift` 無しの素のホイールはページのスクロールのままで、ページのスクロールを奪うのは `Shift` 付きのホイールが使えるデルタを運んでいるときだけです (選択が端に着いていて結果的に何も動かない場合も、操作は範囲領域へ向けられているため奪います)。縦向きレールではレールの正方向が上のため符号が反転します。ノギスではポインターがトラック中心線のどちら側にあるかで段 (マクロレールならマクロ窓、ミクロレールならミクロ選択) が決まり、ステッパーの上ではクリックと同じミクロ選択が動きます。
68
68
  - **レールが描く位置だけを名乗り、そこだけを確定させる**: 離散ミクロレール (`microIsDiscrete`) は候補集合しか描かないため、つまみの位置・読み上げ値・ラベル・そして確定値がすべて同じ 1 規則 (候補があれば最近傍候補、無ければ窓へのクランプ) を読みます。つまみが描かれている場所と利用側が受け取る値が食い違いません。
69
- - **マクロ窓の両境界は対**: ノギスのミクロレールは、マクロつまみが名乗る期間をちょうど覆います。`macroRange` に期間の途中を指す日付を渡しても、開始側は先頭マクロ期間の先頭へ (`getMacroWindowStartDate`)、終了側は末尾マクロ期間の末日へ (`getMacroWindowEndDate`) 揃います (例: `2026-09-15`〜`2026-10-15` は `2026-09-01`〜`2026-10-31`)。丸めた窓が `[minDate, maxDate]` をはみ出す場合は定義域で切り落とされ、この交差は `resolveMacroWindow` が一手に引き受けます — レール・フックの収め込み・ミクロセレクタが同じ窓を読むため、どの経路も定義域外のミクロ日付を確定させません。
69
+ - **マクロ窓の両境界は対**: ノギスのミクロレールは、マクロつまみが名乗る期間をちょうど覆います。`macroRange` に期間の途中を指す日付を渡しても、開始側は先頭マクロ期間の先頭へ (`getMacroWindowStartDate`)、終了側は末尾マクロ期間の末日へ (`getMacroWindowEndDate`) 揃います (例: `2026-09-15`〜`2026-10-15` は `2026-09-01`〜`2026-10-31`)。丸めた窓が `[minDate, maxDate]` をはみ出す場合は定義域で切り落とされ (末尾の期間が `maxDate` の期間かそれより後なら、期間の末日を組まずに `maxDate` のミクロ単位の始まりで閉じるため、Date の表現範囲の最後のマクロ期間へ届く窓も描けます)、この交差は `resolveMacroWindow` が一手に引き受けます — レール・フックの収め込み・ミクロセレクタが同じ窓を読むため、どの経路も定義域外のミクロ日付を確定させません。
70
70
 
71
71
  ## インストール
72
72
 
@@ -823,7 +823,7 @@ export function FiscalQuarterLabelExample() {
823
823
  | `yearStartMonth` | `number` | `0` | `unit="year"` (ノギスの `macroUnit="year"` / `microUnit="year"` を含む) の 1 年が始まる暦月 (0 始まり)。`3` は 4 月〜翌 3 月の会計年度、`9` は 10 月〜翌 9 月のでん粉年度。**年はその年の先頭月が属する暦年で名乗ります** (`yearStartMonth={3}` なら 2025-04-01 〜 2026-03-31 が「2025 年」)。`allowedDates` / `macroAllowedDates` の要素は「その日を含む年」として読まれるため、年解像度の候補は `new Date(y, yearStartMonth, 1)` で渡してください (1 月 1 日を渡すと `yearStartMonth={3}` では前年の候補になります)。`unit="month"` / `"day"` のレールには年の境界が無いため位置は変わりません。`0`〜`11` の整数以外 (`12` / `-1` / `1.5` / `NaN` / `null`) は `RangeError`、未指定は仕様上の `0` (暦年) |
824
824
  | `minDate` | `Date` | (必須) | 選択可能最小日付。欠落・Invalid Date は `RangeError` |
825
825
  | `maxDate` | `Date` | (必須) | 選択可能最大日付。`minDate` より厳密に後であること。欠落・Invalid Date・逆転は `RangeError` |
826
- | `allowedDates` | `Date[]` | `undefined` | 離散スナップ対象日付配列 (指定時はこの日付のみにスナップ)。`[minDate, maxDate]` 外の要素は除外され、全要素が範囲外なら `RangeError` |
826
+ | `allowedDates` | `Date[]` | `undefined` | 離散スナップ対象日付配列 (指定時はこの日付のみにスナップ)。`[minDate, maxDate]` 外の要素は除外され、全要素が範囲外なら `RangeError`。省略は `undefined` だけで、`[]` はレールを連続のまま保つ。配列でない指定値 (`null`・単独の Date など) は `RangeError: PeriodSlider: allowedDates must be an array of Dates (received: null)` |
827
827
  | `snapMode` | `"index" \| "time"` | `"index"` | 離散スナップ時の配置方式 (`"index"`: 配列インデックス均等, `"time"`: 実時間比例)。実時間軸やチャートと位置を揃える場合は `"time"` を明示指定 |
828
828
  | `labelPosition` | `"top" \| "bottom"` | `"top"` | 日付ラベルの表示位置 (スライダーの上側または下側) |
829
829
  | `autoSlantLabels` | `boolean` | `true` | 近接時にラベルを斜め〜90° に自動傾斜させて重なりを防止 (Range の 1 対とノギスの 2 対へ対ごとに適用。垂直レイアウトでは適用されない) |
@@ -874,8 +874,8 @@ export function FiscalQuarterLabelExample() {
874
874
  | `microUnit` | `"year" \| "month" \| "day"` | `unit` | ミクロ側時間解像度単位 (異単位構成用) |
875
875
  | `macroIsDiscrete` | `boolean` | `false` | マクロ側の離散スナップ有効化フラグ。`false` の間は `macroAllowedDates` が参照されない |
876
876
  | `microIsDiscrete` | `boolean` | `false` | ミクロ側の離散スナップ有効化フラグ。`false` の間は `microAllowedDates` が参照されない。`true` かつ現在のマクロ窓が候補を 1 つ以上含む間、ミクロレールは候補集合しか描かないため、位置・`aria-valuenow` / `aria-valuetext`・ラベル・**確定値**のすべてが最近傍候補へ解決される (ドラッグ・キーボード・ホイール・ステッパー・フックの収め込みで同一規則)。窓が候補を 1 つも含まない場合は窓内の連続値として振る舞う |
877
- | `macroAllowedDates` | `Date[]` | `allowedDates` | マクロ側の離散スナップ対象日付配列。`macroIsDiscrete={true}` との併用が必須 |
878
- | `microAllowedDates` | `Date[]` | `allowedDates` | ミクロ側の離散スナップ対象日付配列。`microIsDiscrete={true}` との併用が必須。候補はマクロ窓で切り出され、窓の外の日付へはキーボード・ポインターのいずれからも到達しない。窓内に候補が 1 件も残らない場合、ミクロレールは窓内の連続値として振る舞う |
877
+ | `macroAllowedDates` | `Date[]` | `allowedDates` | マクロ側の離散スナップ対象日付配列。`macroIsDiscrete={true}` との併用が必須。`allowedDates` を継ぐのは省略 (`undefined`) したときだけで、`null` は継がずに `RangeError: PeriodSlider: macroAllowedDates must be an array of Dates (received: null)` |
878
+ | `microAllowedDates` | `Date[]` | `allowedDates` | ミクロ側の離散スナップ対象日付配列。`microIsDiscrete={true}` との併用が必須。`allowedDates` を継ぐのは省略 (`undefined`) したときだけで、`null` は継がずに `RangeError: PeriodSlider: microAllowedDates must be an array of Dates (received: null)`。候補はマクロ窓で切り出され、窓の外の日付へはキーボード・ポインターのいずれからも到達しない。窓内に候補が 1 件も残らない場合、ミクロレールは窓内の連続値として振る舞う |
879
879
  | `formatMacroLabel` | `PeriodOptionFormatter` | `formatLabel` | マクロ側ラベル・ツールチップのカスタム表示文字列生成関数。引数はつまみ位置・`aria-valuenow` と同一の符号値から復元した `macroUnit` 正規化済み `Date` であり、`macroRange` の生の値ではない (`macroUnit="month"` なら常に月初、`"year"` なら常にその年の先頭月 1 日 (`yearStartMonth` が `0` なら元日)、`"day"` は暦日そのままで時刻が 0 時)。`macroUnit="year"` では引数が必ず年の先頭月であるため、ここへ四半期フォーマッタを渡すと表示は常に Q1 になる (四半期は月・日解像度のミクロ側へ載せる) |
880
880
  | `formatMicroLabel` | `PeriodOptionFormatter` | `formatLabel` | ミクロ側ラベル・ツールチップのカスタム表示文字列生成関数。引数はつまみ位置と同一の `microUnit` 正規化済み `Date` (`microUnit="month"` なら常に月初)。四半期ラベルはこの `microUnit="month"` / `"day"` の側に載せる。`formatQuarterLabel` へ渡す `yearStartMonth` はその関数自身の引数であり、スライダーの `yearStartMonth` Props とは独立に選べる |
881
881
  | `vernierOrientation` | `"macro-top" \| "macro-bottom" \| "macro-left" \| "macro-right"` | 水平時 `"macro-top"` / `isVertical` 時 `"macro-left"` | ノギスのレール配置。水平時は上下 (`macro-top` / `macro-bottom`)、垂直時は左右 (`macro-left` / `macro-right`) を指定 |
@@ -1055,16 +1055,17 @@ yearStartMonth=9 2,2,2,3,3,3,4,4,4,1,1,1
1055
1055
  | `normalizeDateByUnit(unit, d, yearStartMonth = 0)` | 単位先頭への正規化。`unit="year"` は「その日を含む年」の先頭月 1 日 |
1056
1056
  | `encode(unit, d, yearStartMonth = 0)` | 比較用の整数キー。`unit="year"` では年番号そのもの |
1057
1057
  | `decode(unit, val, yearStartMonth = 0)` | 整数キーから日付へ。`unit="year"` は `new Date(val, yearStartMonth, 1)` |
1058
- | `getMacroWindowStartDate(macroUnit, microUnit, d, yearStartMonth = 0)` | マクロ窓の開始境界 |
1059
- | `getMacroWindowEndDate(macroUnit, microUnit, d, yearStartMonth = 0)` | マクロ窓の終了境界。年の末尾は 12 月ではなく、開始月から数えて 12 番目の月 |
1058
+ | `getMacroWindowStartDate(macroUnit, microUnit, d, yearStartMonth = 0)` | マクロ窓の開始境界。`d` の `macroUnit`・`microUnit` の始まりが Date の表現範囲の外なら、この順に判定して `RangeError: getMacroWindowStartDate: d must fall in a month that starts inside the Date range (received: ...)` など |
1059
+ | `getMacroWindowEndDate(macroUnit, microUnit, d, yearStartMonth = 0)` | マクロ窓の終了境界。`macroUnit` が粗い組では `d` を含むマクロ期間の最後のミクロ単位の始まり (現地 0 時。0 時の無い日はその日の最初の瞬間) で、年の末尾は 12 月ではなく、開始月から数えて 12 番目の月。最後の単位はキーで数えるため、0-99 年も自分の年のまま (1900 年代へ写らない) で、始まりが表現範囲の外にある最初の期間も最後の単位を返す。その始まりが Date の表現範囲の外 (275760 年 9 月を含む期間。ただし年 × 月で 275760 年 9 月に終わる年 (`yearStartMonth = 9`) は 275760-09-01 を返す) なら `RangeError: getMacroWindowEndDate: d must fall in a month whose last day starts inside the Date range (received: ...)` など。それ以外の組 (同じ単位、`macroUnit` のほうが細かい組) では `d` 自身のミクロ単位の始まりで、その始まりが Date の表現範囲の外なら `RangeError: getMacroWindowEndDate: d must fall in a month that starts inside the Date range (received: ...)` など |
1060
1060
  | `resolveMacroWindow(macroUnit, microUnit, macroRange, minDate, maxDate, yearStartMonth = 0)` | マクロ窓と `[minDate, maxDate]` の交差 |
1061
- | `findNearestDateIndex(dates, target, unit, yearStartMonth = 0)` | 昇順配列に対する最近傍の二分探索 |
1062
- | `getSortedAllowedDates(allowedDates, unit, minDate, maxDate, yearStartMonth = 0)` | 離散候補の正規化・重複排除・境界絞り込み |
1061
+ | `findNearestDateIndex(dates, target, unit, yearStartMonth = 0)` | 昇順かつ単位正規化済みの配列に対する最近傍の二分探索。2 要素以上の一覧では、有効な Date でない `target` は `RangeError: findNearestDateIndex: target must be a valid Date (received: Invalid Date)`、`unit` の始まりが Date の表現範囲の外にある `target` は `RangeError: findNearestDateIndex: target must fall in a month that starts inside the Date range (received: ...)` など (0 要素・1 要素の一覧は `target` を読まずに `0` を返す) |
1062
+ | `getSortedAllowedDates(allowedDates, unit, minDate, maxDate, yearStartMonth = 0)` | 離散候補の正規化・重複排除・境界絞り込み。`undefined` と `[]` は `[]` を返し、配列でない指定値 (`null` を含む) は `RangeError: getSortedAllowedDates: allowedDates must be an array of Dates (received: null)`。メッセージはすべて自身の名を名乗る (`getSortedAllowedDates: allowedDates[1] must be a valid Date (...)`)。空でない一覧では、有効な Date でない `minDate` / `maxDate` は `RangeError: getSortedAllowedDates: minDate must be a valid Date (received: Invalid Date)`、`minDate` / `maxDate` / 要素の `unit` の始まりが Date の表現範囲の外なら `RangeError: getSortedAllowedDates: maxDate must fall in a month that starts inside the Date range (...)` など (境界の順序は検証しないため、片側の絞り込みが黙って外れないよう両端を判定する。空の一覧は境界を読まない) |
1063
1063
 
1064
1064
  - `yearStartMonth` は**必ず末尾**の引数です。省けば既定の `0` (暦年) で計算されます。
1065
1065
  - 未指定 (`undefined`) は仕様上の値である `0` (暦年) です。`null` は既定引数が効かないため `RangeError` になります。`12` / `-1` / `1.5` / `NaN` / `Infinity` / `"3"` も同じく拒否され、近い月へ丸められることはありません。
1066
1066
  - 検証は**早期 return より前**に行われます。空配列を渡した `getSortedAllowedDates` や 1 要素しかない `findNearestDateIndex` でも、不正な `yearStartMonth` が素通りすることはありません。
1067
1067
  - **`addUnit(unit, d, amount)` は意図的にこの引数を受け取りません。** 開始月をずらした年もちょうど 12 か月であり、加算の結果は `yearStartMonth` に依存しないためです。無視するだけの引数を置けば、「渡せば効く」という嘘の契約を名乗ることになります。
1068
+ - `addUnit` の `amount` は整数の単位数です。小数・`NaN`・`Infinity` は `RangeError: addUnit: amount must be an integer number of units (received: 1.5)` になります。月・年の加算は加算先の月の末日へ丸め (1 月 31 日の 1 か月後は 2 月末日)、現地の時刻を保ちます。Invalid Date を返すのは和が Date の表現範囲を越えるときだけです (275760-08-01 の 1 か月後は 275760-09-01、275760-08-31 の 1 か月後は範囲の外)。
1068
1069
 
1069
1070
  ### 実行時バリデーション (Fail Fast)
1070
1071
 
@@ -1075,6 +1076,7 @@ yearStartMonth=9 2,2,2,3,3,3,4,4,4,1,1,1
1075
1076
  | `PeriodSlider` | `minDate` が未指定または Invalid Date | `RangeError: PeriodSlider: minDate is required and must be a valid Date (received: ...)` |
1076
1077
  | `PeriodSlider` | `maxDate` が未指定または Invalid Date | `RangeError: PeriodSlider: maxDate is required and must be a valid Date (received: ...)` |
1077
1078
  | `PeriodSlider` | `maxDate <= minDate` | `RangeError: PeriodSlider: maxDate must be strictly later than minDate (...)` |
1079
+ | `PeriodSlider` | `minDate` の単位の始まりが Date の表現範囲の外 (平レールは `unit`、`vernier` は `macroUnit`・`microUnit`・`unit` の順に判定し、最初に外れた単位を名乗る。ノギスも共有の平坦な値を `unit` で作るため)。`new Date(-8.64e15)` は月と年ではどの時間帯でも、日では UTC 以外で該当し、年の始まりは `yearStartMonth` と共に動く | `RangeError: 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"` |
1078
1080
  | `PeriodSlider` (`vernier`) | `macroRange` の未指定・2 要素タプル以外・Invalid Date・逆転 | `RangeError: PeriodSlider: macroRange is required and must be a [start, end] Date tuple (...)` / `... macroRange[0] must be a valid Date (...)` / `... macroRange must not be inverted (...)` |
1079
1081
  | `PeriodSlider` (`vernier`) | ミクロ選択 Props を 1 つも指定していない | `RangeError: PeriodSlider: vernier mode requires a micro selection; supply microRange / defaultMicroRange for a period, or microValue / defaultMicroValue for a point` |
1080
1082
  | `PeriodSlider` (`vernier`) | ミクロ期間系とミクロ時点系の Props を同時に指定 | `RangeError: PeriodSlider: vernier mode takes either a micro range (microRange / defaultMicroRange / onChangeMicroRange) or a micro point (microValue / defaultMicroValue / onChangeMicroPoint), never both` |
@@ -1084,16 +1086,22 @@ yearStartMonth=9 2,2,2,3,3,3,4,4,4,1,1,1
1084
1086
  | `PeriodSlider` (`vernier`) | 指定された `microValue` / `defaultMicroValue` が Invalid Date | `RangeError: PeriodSlider: <プロパティ名> must be a valid Date (received: ...)` |
1085
1087
  | `PeriodSlider` (`vernier`) | 制御のミクロ選択と並べた既定値が不正・定義域外 | `RangeError: PeriodSlider: defaultMicroValue must be a valid Date (received: null)` など |
1086
1088
  | `PeriodSlider` | 指定された `range` / `defaultRange` / `value` / `defaultValue` が `unit` の解像度で `[minDate, maxDate]` の外 | `RangeError: PeriodSlider: <プロパティ名> must lie within [minDate, maxDate] (...)` |
1087
- | `PeriodSlider` (`vernier`) | 指定されたミクロ選択が `microUnit` の解像度で `[minDate, maxDate]` の外 | `RangeError: PeriodSlider: <プロパティ名> must lie within [minDate, maxDate] (...)` (`macroRange` は定義域をはみ出してよい。レールが定義域と積を取り、通知はクランプ済みの値を配るため) |
1088
- | `PeriodSlider` | `allowedDates` (ノギスは離散の行の `macroAllowedDates` / `microAllowedDates` も) の要素が有効な Date でない (疎配列の穴を含む) | `RangeError: getSortedAllowedDates: allowedDates[1] must be a valid Date (received: undefined)` |
1089
- | `PeriodSlider` | `allowedDates` の全要素が `[minDate, maxDate]` 外 | `RangeError: getSortedAllowedDates: every allowedDates entry falls outside [minDate, maxDate] (...)` |
1089
+ | `PeriodSlider` (`vernier`) | 指定されたミクロ選択が `microUnit` の解像度で `[minDate, maxDate]` の外 | `RangeError: PeriodSlider: <プロパティ名> must lie within [minDate, maxDate] (...)` (`macroRange` は定義域をはみ出してよい。レールが定義域と積を取り、通知はクランプ済みの値を配るため。ただし `macroRange[0]` の `macroUnit` の始まりは Date の表現範囲に入ること) |
1090
+ | `PeriodSlider` | 指定された選択 Props の単位の始まりが Date の表現範囲の外 (`range` / `defaultRange` / `value` / `defaultValue` は `unit`、`vernier` の `macroRange[0]` は `macroUnit`、ミクロ選択 Props は `microUnit`)。定義域の内包の判定より先に行う | `RangeError: PeriodSlider: <プロパティ名> must fall in a <単位> that starts inside the Date range (received: ...)` (救済は添えない) |
1091
+ | `PeriodSlider` / `usePeriodSliderRange` / `usePeriodSliderPoint` / `useVernierSliderRange` / `useVernierSliderPoint` | 指定された候補の一覧が配列でない (`null`・単独の Date・文字列・配列風のオブジェクト・取り消した Proxy)。`PeriodSlider` は `allowedDates` をどのモードでも (離散のフラグを両方とも降ろしたノギスでも) `unit` で検証し、ノギスでは離散の行の `macroAllowedDates` / `microAllowedDates` も検証する。フックは自分が読む一覧だけを検証する (平レールのフックは `allowedDates`、ノギスのフックは離散の行の一覧と、それを省略した行が継ぐ `allowedDates`)。フックは `allowedDates` をそのまま `sliderProps` へ渡すため、ノギスのフックが受け付けた一覧も、それを描く `PeriodSlider` が拒否することがある | `RangeError: PeriodSlider: allowedDates must be an array of Dates (received: null)` / `useVernierSliderPoint: allowedDates (inherited by the macro row) must be an array of Dates (received: null)` |
1092
+ | 同上 | 同じ一覧の要素が有効な Date でない (疎配列の穴を含む) | `RangeError: PeriodSlider: microAllowedDates[3] must be a valid Date (received: "x")` / `useVernierSliderRange: allowedDates[3] (inherited by the micro row) must be a valid Date (received: "x")` |
1093
+ | 同上 | 同じ一覧の要素の、その行の単位の始まりが Date の表現範囲の外 (定義域の外の要素のように黙って除かない) | `RangeError: PeriodSlider: allowedDates[1] must fall in a month that starts inside the Date range (received: ...)` |
1094
+ | 同上 | 同じ一覧の全要素が、その行の単位で `[minDate, maxDate]` 外 | `RangeError: PeriodSlider: every macroAllowedDates entry falls outside [minDate, maxDate] (...)` / `PeriodSlider: every allowedDates entry (inherited by the micro row) falls outside [minDate, maxDate] (...)` |
1090
1095
  | `usePeriodSliderRange` / `usePeriodSliderPoint` / `useVernierSliderRange` / `useVernierSliderPoint` | 境界・初期値の欠落、Invalid Date、逆転。マウント時の初期値が定義域 (ノギスのミクロの初期値は初期の窓) の外 (マウント後に境界が初期値を越えて動いても送出しない) | `RangeError: <フック名>: ...` |
1096
+ | 同上 | 毎描画: `minDate` の単位の始まりが Date の表現範囲の外 (平レールは `unit`、ノギスは `macroUnit`・`microUnit`・`unit` (スライダーへ渡す単位) の順に判定し、最初に外れた単位を名乗る)。初期値 (`initialRange` / `initialValue` は `unit`、`initialMacroRange` は `macroUnit`、`initialMicroRange` / `initialMicroValue` は `microUnit`) がそうした日付を含む (マウント時の定義域の照合より先) | `RangeError: useVernierSliderRange: minDate must fall in a month that starts inside the Date range (received: ...); minDate is required, so pass the earliest date to offer instead of a sentinel for "no bound"` / `usePeriodSliderPoint: initialValue must fall in a month that starts inside the Date range (received: ...)` |
1097
+ | 同上 | 設定関数・セレクタのコールバック・`sliderProps` のコールバックへ渡した日付、または直接の更新関数 (`setRange` / `setValue` / `setMacroRange` / `setMicroRange` / `setMicroValue`) で入れた直後の描画の日付の、描く単位 (平レールは `unit`、マクロの入口と窓は `macroUnit`、ミクロの入口と選択は `microUnit`) の始まりが Date の表現範囲の外。時刻でクランプせず、入口・状態の名前で拒否する | `RangeError: usePeriodSliderRange: setLowerDate(date) must fall in a day that starts inside the Date range (received: ...)` / `useVernierSliderPoint: sliderProps.onChangeMicroPoint(value) must fall in a day ...` / `... range[0] must fall in a day ...` |
1091
1098
  | `usePeriodSliderRange` / `usePeriodSliderPoint` | 設定関数 (`setLowerDate` / `setUpperDate`)、セレクタのコールバック (`selectorProps.onChange`。範囲フックのセレクタは設定関数を名乗る)、`sliderProps` のコールバック (`onChangeRange` / `onChangePoint`) へ Invalid Date、または `setRange` / `setValue` で Invalid Date を入れた直後の描画 | `RangeError: usePeriodSliderRange: setLowerDate(date) is required and must be a valid Date (...)` / `... sliderProps.onChangeRange(upper) ...` / `usePeriodSliderPoint: selectorProps.onChange(date) ...` / `... range[0] ...` / `... value ...` |
1092
1099
  | `useVernierSliderRange` / `useVernierSliderPoint` | 設定関数 (`setMacroLowerDate` / `setMacroUpperDate` / `setMicroLowerDate` / `setMicroUpperDate` / `setMicroDate`。各セレクタ Props の `onChange` はこれらの設定関数そのもの) や `sliderProps` のコールバック (`onChangeMacroRange` / `onChangeMicroRange` / `onChangeMicroPoint`) へ Invalid Date、または `setMacroRange` / `setMicroRange` / `setMicroValue` で Invalid Date を入れた直後の描画 | `RangeError: useVernierSliderRange: setMicroLowerDate(date) is required and must be a valid Date (...)` / `... sliderProps.onChangeMicroRange(upper) is required ...` / `... macroRange[0] is required and must be a valid Date (...)` |
1093
1100
  | `usePeriodSliderRange` / `usePeriodSliderPoint` / `useVernierSliderRange` / `useVernierSliderPoint` | シフト関数 (`shiftRange` / `shiftValue` / `shiftMacroRange` / `shiftMicroRange` / `shiftMicroValue`) へ整数でない `delta` (`NaN`・`Infinity`・小数) | `RangeError: useVernierSliderRange: shiftMicroRange(delta) must be an integer number of units (received: NaN)` |
1094
1101
  | `usePeriodSliderRange` / `useVernierSliderRange` / `useVernierSliderPoint` | `selectorStep` / `macroSelectorStep` / `microSelectorStep` がオブジェクトでない・向きの規則が欠けている・未知の `motion` / `edge` / `window`・`shift` 以外への `edge`・その行が読まないキー (マクロ行と期間フックの `window`、時点フックのミクロ行の `motion` など) | `RangeError: usePeriodSliderRange: selectorStep.previous.window is not read here; the accepted keys are "motion", "edge" (received: "keep")` 等 |
1102
+ | `resolveMacroWindow` | `macroRange` が 2 要素タプルでない・Invalid Date を含む・逆転、`minDate` / `maxDate` が Invalid Date・逆転、不正な `yearStartMonth`、`maxDate` の `microUnit` の始まりが Date の表現範囲の外 (`maxDate` へクランプした窓の端は `microUnit` で畳むため)、`macroRange[0]` の `macroUnit` または `microUnit` の始まりが Date の表現範囲の外 (窓の開始はこの 2 つの単位で畳むため)。`minDate` は判定しない (`minDate` へクランプするのは、範囲に入るミクロ単位の始まりである窓の端より後にあるときだけのため) | `RangeError: resolveMacroWindow: maxDate must fall in a month that starts inside the Date range (received: ...)` / `... macroRange[0] must fall in a month that starts inside the Date range (received: ...)` 等 (すべて自身の名を名乗る) |
1095
1103
  | `resolveSelectorSteps` | オプションがオブジェクトでない、未知の `unit` / `stepUnit` / `shows`、`unit` そのものでも月の選択に対する `"year"` でもない `stepUnit`、不正な `yearStartMonth`、`unit` の解像度で逆転した・有効な Date 2 つでない `selection`、不正または逆転した境界、`allowedDates` が配列でない・不正な要素 (疎配列の穴を含む)、整っていない `rules`、単位の始まりが Date の表現範囲の外にある日付 | `RangeError: resolveSelectorSteps: selection must not be inverted at month resolution (...)` / `... stepUnit must be "day" for a day selection, ...` 等 |
1096
- | `resolveVernierSelectorSteps` | 未知の `row` / `shows` / 単位、不正な `yearStartMonth`、不正または厳密に順序づいていない境界、有効な Date 2 つで順序どおりでない `macroRange` / `microSelection` (`macroRange` は同じマクロ単位の中の時刻の逆転も)、候補が配列でない・不正な要素 (疎配列の穴を含む)・全要素が定義域の外、整っていない `rules` | `RangeError: resolveVernierSelectorSteps: every microAllowedDates entry falls outside [minDate, maxDate] (...)` 等 |
1104
+ | `resolveVernierSelectorSteps` | 未知の `row` / `shows` / 単位、不正な `yearStartMonth`、不正または厳密に順序づいていない境界、`macroUnit` または `microUnit` の始まりが Date の表現範囲の外にある `minDate` (`macroUnit` を先に判定。`maxDate` は厳密に後にあるため判定しない)、有効な Date 2 つで順序どおりでない `macroRange` / `microSelection` (`macroRange` は同じマクロ単位の中の時刻の逆転も)、候補が配列でない・不正な要素 (疎配列の穴を含む)・全要素が定義域の外、整っていない `rules`、単位の始まりが Date の表現範囲の外にある `macroRange` (`macroUnit`)・`microSelection` (`microUnit`)・候補 (その行の単位) | `RangeError: resolveVernierSelectorSteps: minDate must fall in a month that starts inside the Date range (received: ...)` / `... every microAllowedDates entry falls outside [minDate, maxDate] (...)` 等 |
1097
1105
  | `PeriodSlider` | `formatLocale` が空文字列・構造として不正な BCP 47 タグ・非文字列 | `RangeError: PeriodSlider: formatLocale must be a valid BCP 47 language tag (received: ...)` |
1098
1106
  | `DateSelector` | 同上 | `RangeError: DateSelector: "formatLocale" must be a valid BCP 47 language tag (received ...)` |
1099
1107
  | `MonthSelector` / `YearSelector` | 同上 | ``RangeError: <コンポーネント名>: `formatLocale` must be a valid BCP 47 language tag, received ....`` |
@@ -1108,11 +1116,19 @@ yearStartMonth=9 2,2,2,3,3,3,4,4,4,1,1,1
1108
1116
  | `MonthSelector` | Date Props (`value` / `initialDate` / `minDate` / `maxDate` / `allowedMonths` の要素) の月の始まり、または年 Props が名指す端の月 (`minYear` の 1 月・`maxYear` の 12 月) の始まりが Date の表現範囲 (±8.64e15 ms) の外 | ``RangeError: MonthSelector: `minDate` must fall in a month that starts inside the Date range, ...`` / ``... `maxYear` must name a year whose December starts inside the Date range, ...`` |
1109
1117
  | `DateSelector` | Date / 年 Props の不正値、`allowedDates` の要素が Invalid Date または `Date` でない (`undefined`・疎配列の穴を含む。添字付きで報告)、解決後の範囲が空、バリアントが要求する境界の欠落、`variant="split-dropdown"` への `allowedDates` 指定 | `RangeError` |
1110
1118
  | `DateSelector` | Date Props (`value` / `initialDate` / `minDate` / `maxDate` / `allowedDates` の要素) のローカルのその日の始まり、または年 Props が名指す端の日 (`minYear` の 1 月 1 日・`maxYear` の 12 月 31 日) が Date の表現範囲の外 (`new Date(-8.64e15)` は UTC 以外のタイムゾーンでこれに当たる)。`variant="split-dropdown"` では、Date Props (`value` / `initialDate` / `minDate` / `maxDate`) が属する年の 1 月 1 日が表現範囲の外 (-271821 年の日付はどのタイムゾーンでも該当)、および以前の描画から保持している非制御の選択がその年にあるまま `variant="split-dropdown"` で描く描画 | `RangeError: DateSelector: "minDate" must fall on a day that starts inside the Date range (...)` / `... "maxYear" must name a year whose last day is inside the Date range (...)` (`minYear` は 1 月 1 日、`maxYear` は 12 月 31 日だけを検査) / `... "minDate" must fall in a year that starts inside the Date range, because variant="split-dropdown" draws its year (...)` / `... variant="split-dropdown" cannot draw the uncontrolled selection held from an earlier render (holding ...), because that selection's year starts outside the Date range; ...` |
1119
+ | `YearSelector` / `MonthSelector` | 指定された `allowedYears` / `allowedMonths` が配列でない (`null`・単独の Date・文字列・配列風のオブジェクト・取り消した Proxy。文字列を 1 文字ずつ要素として読まず、一覧そのものを名指す) | ``RangeError: YearSelector: `allowedYears` must be an array of Dates, received null.`` / ``RangeError: MonthSelector: `allowedMonths` must be an array of Dates, received "2024".`` |
1120
+ | `DateSelector` | 指定された `allowedDates` が配列でない (同上。`variant="split-dropdown"` は形を問う前に `allowedDates` の指定そのものを拒否する) | `RangeError: DateSelector: "allowedDates" must be an array of Dates (received null)` |
1111
1121
 
1112
- メッセージに載る受け取った値と保持している値 (`received` / `holding`) は、パッケージ全体で 1 つの規則で示します。文字列は JSON の引用符付き (`"2024-02-12"`・`""`) で、日付に見える文字列や空文字列も Date や未指定と見分けられます。有効な Date は ISO 8601 の時刻、それ以外は `String()` の形 (`null`・`undefined`・`Invalid Date`・数値) です。文字列へ変換すると例外になる値 (`Object.create(null)`・時刻値を持たずに `Date.prototype` を継ぐオブジェクト・Date を包んだ Proxy) は `an object that cannot be converted to a string` と示し、メッセージを組む段で例外を投げません。`labels` と `locale` の検証だけは、それらを検証するエンジン (`@aiquants/virtualscroll`) と同じ形 (文字列は引用符付き、それ以外は型名。`got number` など) で示します (`labels` はエンジンが半分のキーを検証し、`locale` のメッセージはエンジンのメッセージを包み直したものです)。解決した境界など、パッケージが組んだ日付は受け取った値ではないため、`yyyy-MM-dd` (`DateSelector`) / `yyyy-MM` (`MonthSelector`) で示します。
1122
+ メッセージに載る受け取った値と保持している値 (`received` / `holding`) は、パッケージ全体で 1 つの規則で示します。文字列は JSON の引用符付き (`"2024-02-12"`・`""`) で、日付に見える文字列や空文字列も Date や未指定と見分けられます。有効な Date は ISO 8601 の時刻 (どのタイムゾーンでも同じ表記) です。配列は要素ごとに同じ規則で `[e0, e1, e2, ... n more]` と示し、示すのは先頭の 3 要素までです (穴は `empty`、配列である要素は中へ降りずに `Array(長さ)`、読み出しが投げる要素はその要素だけを `an object that cannot be converted to a string`)。したがって 3 要素の `defaultRange` は `(received: [2024-01-01T00:00:00.000Z, 2024-02-01T00:00:00.000Z, 2024-03-01T00:00:00.000Z])` と読め、`[3]` は `3` と区別されます。それ以外は `String()` の形 (`null`・`undefined`・`Invalid Date`・数値) です。文字列へ変換すると例外になる値 (`Object.create(null)`・時刻値を持たずに `Date.prototype` を継ぐオブジェクト・Date を包んだ Proxy・取り消した Proxy) と `length` を読めない配列は `an object that cannot be converted to a string` と示し、メッセージを組む段で例外を投げません。配列かどうかの判定も例外を投げないため、取り消した Proxy を一覧やタプルとして渡しても、ほかの配列でない値と同じく、マウントでも再描画 (メモ比較) でも Props・オプション名を名乗る `RangeError` になります。`labels` と `locale` の検証だけは、それらを検証するエンジン (`@aiquants/virtualscroll`) と同じ形 (文字列は引用符付き、それ以外は型名。`got number` など) で示します (`labels` はエンジンが半分のキーを検証し、`locale` のメッセージはエンジンのメッセージを包み直したものです)。解決した境界など、パッケージが組んだ日付は受け取った値ではないため、`yyyy-MM-dd` (`DateSelector`) / `yyyy-MM` (`MonthSelector`) で示します。
1123
+
1124
+ **候補の一覧の拒否は、読んだ所有者と一覧を名乗ります。** 所有者は `PeriodSlider` と 4 つのフックで、一覧は利用側が書いた名前 (`allowedDates` / `macroAllowedDates` / `microAllowedDates`) です。ノギスの行が自分の一覧を省略 (`undefined`) して共有の `allowedDates` を継いだときは、半角スペースに続けて `(inherited by the macro row)` / `(inherited by the micro row)` を添えます (要素が定義域に入るかは行の単位で決まるため)。本体はモードや離散のフラグに依らず共有の `allowedDates` を `unit` でも、行の読み出しより先に読みます。そのため形の誤りと有効な Date でない要素は本体自身の読み出しが行の名なしで報告し (`PeriodSlider: allowedDates[3] must be a valid Date (...)`)、`unit` で拒否される一覧 (`unit` の始まりが表現範囲の外にある要素、`unit` での全滅) も行の名なしです。行の名が付くのは、`unit` では通るのに行の単位で拒否される場合です。行の単位が `unit` より細かく、そこでだけ全要素が定義域の外に落ちる全滅と、`unit` より粗い行の単位の始まりが表現範囲の外にある要素 (`unit` では定義域の外として除かれる要素も行の単位で判定されます。`PeriodSlider: allowedDates[0] (inherited by the macro row) must fall in a month that starts inside the Date range (...)`) がこれに当たります。フックは共有の一覧を離散の行の読み出しでだけ読むため、継いだ一覧のどの誤りにも行の名が付きます。ただしフックは `allowedDates` をそのまま `sliderProps` へ渡すため、それを描く `PeriodSlider` は同じ一覧を `unit` でも読み、フックが受け付けた一覧を行の名なしで拒否することがあります。`getSortedAllowedDates` を直接呼んだときは自身の名を名乗ります。
1113
1125
 
1114
1126
  **定義域の内包は、値が載るレールの解像度で判定します。** レールが描くのは単位まるごと (年・月・日) であるため、`minDate` が期間の途中を指す場合 (`unit="month"` に `2026-09-15`、`unit="day"` に時刻を持つ `new Date()` など) は、その期間まるごと (`2026-09-01`) がレールの先頭として描かれ、`Home` キー・ステッパー・ドラッグ・フックはいずれもその日付を確定値として配ります。したがってその日付をそのまま制御 Props (`range` / `value` / `microRange` など) へ戻しても受理されます。1 単位でも外れた日付は `RangeError` です。
1115
1127
 
1128
+ **Date の表現範囲の最初の単位にある日付は、Invalid Date と同じく拒否します。** 本体とフックが単位で描く日付は、その単位の始まりが Date の表現範囲 (±8.64e15 ms) に入らなければなりません。`new Date(-8.64e15)` は月と年ではどの時間帯でも、日では UTC 以外で始まりが範囲の外にあり (年の始まりは `yearStartMonth` と共に動く)、そのままでは符号化キーが `NaN` になって定義域の判定をすべて素通りします。そこで Invalid Date を拒否するのと同じ所有者・名前・時点で、定義域の内包の判定より先に `<所有者>: <名前> must fall in a <単位> that starts inside the Date range (received: ...)` の `RangeError` にします (判定と文言は `resolveSelectorSteps` と共有)。救済の文 (`; minDate is required, ...`) を添えるのは `minDate` だけです。本体とフックが境界と `macroRange` で判定するのは下側 (`minDate`・`macroRange[0]`) だけです (順序は先に検証済みで、上側はそれより後にあるため。境界の順序を検証しない `getSortedAllowedDates` は両端を判定し、`resolveMacroWindow` は窓の端を `maxDate` へクランプしてから `microUnit` で畳むため `maxDate` を `microUnit` で判定します)。この規則は表現範囲の上端の日付を拒否しません (単位の始まりは日付より後にならないため、`new Date(8.64e15)` も `maxDate` として通ります)。UTC の日の単位のように始まりが範囲に入る場合は、`new Date(-8.64e15)` もこれまでどおり定義域の判定 (`must lie within`) や `macroRange` のはみ出しの扱いを受けます。
1129
+
1130
+ **計算で Date の表現範囲を越える日付は、進む向きの定義域の端の外にあるものとして扱います。** フックのシフトの和、`macro-connect` のパンで運ぶミクロ選択、マクロ窓の末尾がこれに当たります (定義域の両端は、始まりが範囲に入る単位にあるため)。`shiftRange` / `shiftValue` は定義域の端 (`minDate` / `maxDate`) へ、`shiftMicroValue` は窓の端へ着いて止まり、`shiftMacroRange` / `shiftMicroRange` は中止します。どれも通常の境界を越えたシフトと同じ扱いで、Invalid Date を通知することはありません。`macro-connect` のパンは、マクロの差分だけ暦の算術で動かしたミクロ選択を Date へ戻さずにキーのまま運び、長さを保って窓へ収めます (275760-08-20〜08-31 を 1 か月運ぶと 9 月 20 日〜30 日になり、その長さのまま窓の末尾へ寄って、最後の日の 10 日前〜最後の日になります)。窓が Date の表現範囲の最後のマクロ期間 (275760 年 9 月、またはそれを含む年) へ届くと、窓の末尾は期間の末尾を組まずに `maxDate` のミクロ単位の始まりになります。0-99 年の窓も同じ暦の算術で数えるため、月 × 日の窓はその年の月末日で閉じます。
1131
+
1116
1132
  `DateSelector` は構成そのものの矛盾を優先して報告します。`variant="split-dropdown"` と `allowedDates` の併用は、`value` / `initialDate` の欠落よりも先に判定されます。
1117
1133
 
1118
1134
  ### カラーテーマ & ダークモード
@@ -1252,6 +1268,8 @@ yearStartMonth=9 2,2,2,3,3,3,4,4,4,1,1,1
1252
1268
 
1253
1269
  Date 型 Props (`value` / `initialDate` / `minDate` / `maxDate`) は描画のたびに検証します。再描画で Date でない値 (文字列・数値・`null`・素のオブジェクト) や Invalid Date を渡すと、初回のマウントと同じく、その描画で Props 名を名指す `RangeError` になります。制御中で表示に効かない `initialDate` も同じです。同じ年・月・日の中で動いただけの有効な Date は、ほかの Props が変わらなければ再描画を起こしません (メモ比較器が単位で比べるため)。
1254
1270
 
1271
+ 非制御の `initialDate` は、非制御になった描画 (マウントと、制御から非制御への切り替え) と、最後に取り込んだものと別の単位 (日・月・年。`YearSelector` の年は `yearStartMonth` で区切る) へ動いた描画で、**その描画のうちに**取り込みます。取り込んだ値はその描画の最初の確定から描かれ、`onChange` は発火しません。同じ単位の中の移動は、ほかの Props が変わって再描画された場合も取り込まず、利用者が ◀▶・選択肢・入力で選んだ値を置き換えません (別の単位への移動は置き換えます)。`YearSelector` は `yearStartMonth` を変えた描画でも、年の区切りが変わるため `initialDate` を取り込み直します。
1272
+
1255
1273
  ◀▶ は押せる間だけ、ポインターを載せると矢印の色が背景から際立ち (ライトでは濃く、ダークでは明るく) 淡い面が現れ、キーボードフォーカスで青いリングが付きます。押せる範囲は矢印を中心とする 44px 四方で、隣のセレクトボックスや日付入力の縁で止まります。境界に着いて動けない ◀▶ はフォーカスを保ち、タブ順にも残ったまま使用不可 (`aria-disabled="true"`) になり、押しても何も発行しません (キーボードで押し続けて境界に着いても、フォーカスが文書へ落ちません)。ネイティブの `disabled` が付くのは `disabled` Props でセレクタ全体を無効にしたときだけで、そのときは全てのバリアントで ◀▶ の両方がセレクトや日付入力と共にタブ順から外れます。
1256
1274
 
1257
1275
  > [!NOTE]
@@ -1305,7 +1323,7 @@ export function SelectorsExample() {
1305
1323
  | プロパティ | 型 | 既定値 | 説明 |
1306
1324
  | :--- | :--- | :--- | :--- |
1307
1325
  | `value` | `Date` | `undefined` | 制御時の選択日付 (年のみ使用)。`initialDate` 未指定時は必須 |
1308
- | `initialDate` | `Date` | `undefined` | 非制御時の初期選択日付 (年のみ使用)。`value` 未指定時は必須。`value` 指定時は無視 |
1326
+ | `initialDate` | `Date` | `undefined` | 非制御時の初期選択日付 (年のみ使用)。`value` 未指定時は必須。`value` 指定時は無視。別の年へ動かした描画と `yearStartMonth` を変えた描画のうちに取り込み、同じ年の中の移動では利用者の選択を置き換えない |
1309
1327
  | `minYear` | `number` | `undefined` | 選択可能な最小年。`minDate` と併用時は厳しい方 (遅い方) を採用 |
1310
1328
  | `maxYear` | `number` | `undefined` | 選択可能な最大年。`maxDate` と併用時は厳しい方 (早い方) を採用 |
1311
1329
  | `minDate` | `Date` | `undefined` | 選択可能な最小日付 (年のみ使用)。`minYear` と併用時は厳しい方を採用 |
@@ -1320,7 +1338,7 @@ export function SelectorsExample() {
1320
1338
  | `labels` | `PeriodSliderLabelOverrides` | `undefined` | カタログへのキー単位の上書き。読むのは `previousYear` / `nextYear` / `yearSelect` |
1321
1339
  | `formatLocale` | `string` | `undefined` | 選択肢テキストのロケール (BCP 47 言語タグ)。未指定は 4 桁ゼロ埋めの年、指定時は `Intl.DateTimeFormat` 書式。空文字列・不正タグ・非文字列は `RangeError` |
1322
1340
  | `formatOption` | `PeriodOptionFormatter` | `undefined` | 選択肢 (境界外の保持年を含む) と畳んだ表示のテキスト生成関数 (`formatLocale` より優先)。`(date, unit, scope) => string` で、`unit` は常に `"year"`、`scope` は常に `"period"`、`date` はその年の先頭月 1 日 (`yearStartMonth` 準拠)。このコンポーネントは単一形態でプレースホルダを持たず、境界外の保持年も書式化された実選択肢 (`disabled`) として並ぶ。返り値は機械可読値 (`<option value>` は常に生の数値)・`aria-label`・`onChange` の引数には届かない。参照比較で再描画を判定するため、利用側でメモ化する |
1323
- | `allowedYears` | `Date[]` | `undefined` | 離散の選択可能年。各要素は「その日付を含む年」(`yearStartMonth` 準拠) として読み、重複は畳み、境界の外の要素は落とします。指定すると連続範囲を置き換えるため、候補の無い年は選択肢からもステッパーの行き先からも外れます。指定時は境界必須の条件も満たします (`MonthSelector` の `allowedMonths` / `DateSelector` の `allowedDates` と同じ扱い)。`[]` は「選択可能年なし」を意味し、要素の Invalid Date は添字付きの `RangeError`。参照比較で再描画を判定するため、利用側でメモ化する |
1341
+ | `allowedYears` | `Date[]` | `undefined` | 離散の選択可能年。各要素は「その日付を含む年」(`yearStartMonth` 準拠) として読み、重複は畳み、境界の外の要素は落とします。指定すると連続範囲を置き換えるため、候補の無い年は選択肢からもステッパーの行き先からも外れます。指定時は境界必須の条件も満たします (`MonthSelector` の `allowedMonths` / `DateSelector` の `allowedDates` と同じ扱い)。`[]` は「選択可能年なし」を意味し、要素の Invalid Date は添字付きの `RangeError`、配列でない指定値 (`null`・文字列を含む) は一覧そのものを名指す `RangeError`。参照比較で再描画を判定するため、利用側でメモ化する |
1324
1342
  | `unit` | — | — | **このコンポーネントが宣言していない名前です**。フックの `SelectorProps` をそのままスプレッドできるよう、受け取っても読まれず捨てられます (コンポーネントは必要な Props だけを名前で取り出すため、DOM へも届きません)。型にも宣言が無いので、JSX へ直接書くとコンパイルエラーになります (スプレッドは余剰プロパティ検査を受けないため通ります) |
1325
1343
  | `yearStartMonth` | `number` | `0` | 1 年が始まる暦月 (0 始まり)。選択肢の年の数え方と `onChange` が返す日付を決めます (`yearStartMonth={3}` なら「2025 年」は 2025-04-01 〜 2026-03-31 で、`onChange` は `2025-04-01` を渡します)。`0`〜`11` の整数以外 (`12` / `-1` / `1.5` / `NaN` / `null`) は `RangeError`、未指定は仕様上の `0` (暦年) |
1326
1344
 
@@ -1339,9 +1357,9 @@ DOM 契約: 保持年が集合外の間、ルート要素に `data-out-of-range=
1339
1357
  | プロパティ | 型 | 既定値 | 説明 |
1340
1358
  | :--- | :--- | :--- | :--- |
1341
1359
  | `value` | `Date` | `undefined` | 制御時の選択日付 (年月のみ使用)。`initialDate` 未指定時は必須 |
1342
- | `initialDate` | `Date` | `undefined` | 非制御時の初期選択日付 (年月のみ使用)。`value` 未指定時は必須。`value` 指定時は無視 |
1360
+ | `initialDate` | `Date` | `undefined` | 非制御時の初期選択日付 (年月のみ使用)。`value` 未指定時は必須。`value` 指定時は無視。別の月へ動かした描画のうちに取り込み、同じ月の中の移動では利用者の選択を置き換えない |
1343
1361
  | `variant` | `"date" \| "dropdown"` | `"date"` | `"date"`: `<input type="month">`、`"dropdown"`: `YYYY-MM` の `<select>` |
1344
- | `allowedMonths` | `Date[]` | `undefined` | 選択可能な離散月配列。各要素は月頭に切り捨てられ (日の部分は無視)、月単位で重複排除・境界で絞り込まれる。空配列は「選択可能月なし」を意味する。参照比較で再描画を判定するため、利用側でメモ化する |
1362
+ | `allowedMonths` | `Date[]` | `undefined` | 選択可能な離散月配列。各要素は月頭に切り捨てられ (日の部分は無視)、月単位で重複排除・境界で絞り込まれる。空配列は「選択可能月なし」を意味し、配列でない指定値 (`null`・文字列を含む) は一覧そのものを名指す `RangeError`。参照比較で再描画を判定するため、利用側でメモ化する |
1345
1363
  | `minYear` | `number` | `undefined` | 選択可能な最小年 (その年の 1 月)。`minDate` と併用時は厳しい方を採用 |
1346
1364
  | `maxYear` | `number` | `undefined` | 選択可能な最大年 (その年の 12 月)。`maxDate` と併用時は厳しい方を採用 |
1347
1365
  | `minDate` | `Date` | `undefined` | 選択可能な最小日付 (月頭に切り捨て)。`minYear` と併用時は厳しい方を採用 |
@@ -1386,9 +1404,9 @@ const allowedMonths = useMemo(() => baseMonths.map((yyyymm) => new Date(Math.tru
1386
1404
  | プロパティ | 型 | 既定値 | 説明 |
1387
1405
  | :--- | :--- | :--- | :--- |
1388
1406
  | `value` | `Date` | `undefined` | 制御時の選択日付 (日単位に正規化)。`initialDate` 未指定時は必須。`initialDate` 指定時も `value` が優先 |
1389
- | `initialDate` | `Date` | `undefined` | 非制御時の初期選択日付。`value` 未指定時は必須。`value` 指定時は無視 |
1407
+ | `initialDate` | `Date` | `undefined` | 非制御時の初期選択日付。`value` 未指定時は必須。`value` 指定時は無視。別の日へ動かした描画のうちに取り込み、同じ日の中の移動では利用者の選択を置き換えない |
1390
1408
  | `variant` | `"date" \| "dropdown" \| "split-dropdown"` | `"date"` | `"date"`: `<input type="date">`、`"dropdown"`: 日単位の全選択肢を仮想化した `role="combobox"` (行は `YYYY-MM-DD`、定義域の広さに費用が比例しない)、`"split-dropdown"`: 年・月・日の 3 分割 `<select>` |
1391
- | `allowedDates` | `Date[]` | `undefined` | 選択可能な離散日付配列。空配列は「選択可能日なし」を意味する。境界で絞り込み・日単位で重複排除される |
1409
+ | `allowedDates` | `Date[]` | `undefined` | 選択可能な離散日付配列。空配列は「選択可能日なし」を意味し、配列でない指定値 (`null` を含む) は Props 名を名乗る `RangeError`。境界で絞り込み・日単位で重複排除される |
1392
1410
  | `minYear` | `number` | `undefined` | 選択可能な最小年 (その年の 1 月 1 日)。`minDate` と併用時は厳しい方を採用 |
1393
1411
  | `maxYear` | `number` | `undefined` | 選択可能な最大年 (その年の 12 月 31 日)。`maxDate` と併用時は厳しい方を採用 |
1394
1412
  | `minDate` | `Date` | `undefined` | 選択可能な最小日付。`minYear` と併用時は厳しい方を採用 |
@@ -1410,7 +1428,7 @@ const allowedMonths = useMemo(() => baseMonths.map((yyyymm) => new Date(Math.tru
1410
1428
 
1411
1429
  - `value` (制御) と `initialDate` (非制御) はいずれか一方が必須です。共に省略した場合は `RangeError` を送出し、選択日付を壁時計時刻から推定しません。
1412
1430
  - `variant="dropdown"`: `allowedDates` を指定しない場合、下限と上限の双方が必須です。選択肢は `minDate` 〜 `maxDate` の全日 (降順) ですが、配列としては実体化しません。件数は境界から算出し、行の日付・テキストは描画時に導出し、DOM に存在するのはポップアップの可視行だけです。境界を動かす費用は連続範囲で O(1)、`allowedDates` 指定時は二分探索の O(log n) で、100 年分 (36,525 日) の定義域でも 1 か月分と同じ費用で動きます。ポインタ移動ごとに境界を動かすホスト (ノギスの連動セレクタなど) でも、この変種を日単位のまま使えます。
1413
- - `variant="split-dropdown"`: 下限と上限の双方が必須で、`allowedDates` との併用は `RangeError` になります。存在しない日付になる年・月へ切り替えた場合 (1 月 31 日を選択中に 2 月へ変更等)、月末日へ丸めず選択を破棄し、`onChange` を発火しません。実在する日は、年・月・日から組んだ日付が同じ年・月・日を名乗る日だけで、タイムゾーンが飛ばした日 (Pacific/Kiritimati の 1994 年 12 月 31 日、Pacific/Apia の 2011 年 12 月 30 日など) も存在しない日付です。その日は日の一覧に現れず、その日になる年・月も選べず、翌日へ寄せて発行することもありません。そうした選択肢 — 保持中の他 2 部位と組んで実在しない日付になるもの、および境界の外へ出るもの — は、年・月・日の 3 つの `<select>` すべてで `disabled` として描かれ、押せる範囲と発行できる範囲が一致します (1 月 31 日を保持していれば月の `2` / `4` / `6` / `9` / `11` が `disabled` になり、保持値そのものが境界の外にある間は、その保持値と組んで境界内へ収まる選択肢を 1 つも持たないセレクトの全選択肢が `disabled` になります)。選択肢のテキストは既定でゼロ埋めの数値 (`2024` / `01` / `15`) で、`formatLocale` または `formatOption` (`scope: "part"`) で変更できます。基準日は**その `<select>` の値だけ**から決まります (年は 1 月 1 日、月は当月 1 日、日は保持中の年月とその日)。Date Props (`value` / `initialDate` / `minDate` / `maxDate`) が属する年の 1 月 1 日が Date の表現範囲の外にある場合 (-271821 年の日付。表現範囲は同年 4 月 20 日 UTC から始まるため、どのタイムゾーンでも該当) は、年と月の部位を名指す基準日を組めないため prop 名を名乗る `RangeError` です (日だけを描く `variant="date"` / `"dropdown"` は受け付けます)。境界 (`minDate` / `maxDate`) のエラーは、境界を省けず `allowedDates` も使えないこの変種に合わせ、番兵の代わりに `minYear` / `maxYear` で年を宣言するよう示します。以前の描画から保持している非制御の選択がその年にあるまま `variant="split-dropdown"` で描く場合も、`variant="split-dropdown"` を名乗る `RangeError` です。起こるのは、日だけを描く変種のあいだにその年へ動かした選択を保持したまま `variant="split-dropdown"` へ切り替えた場合と、制御から非制御へ切り替えた場合 (制御中は非制御の選択を更新しないため、その前の非制御の描画がその年に残した選択が古いまま現れる。`variant` を変えていなくても該当) の 2 つです。どちらも、`initialDate` の変更は描画の確定後に取り込むため、同じ描画で渡し直しても避けられません。分割セレクトに保持させる日は `value` で制御してください。上限より後の保持年・保持月を暦の終わりまで埋める月と日の一覧は、Date の表現範囲の端 (275760 年 9 月と、その月の表現できる最後のローカル暦日) で終わります。
1431
+ - `variant="split-dropdown"`: 下限と上限の双方が必須で、`allowedDates` との併用は `RangeError` になります。存在しない日付になる年・月へ切り替えた場合 (1 月 31 日を選択中に 2 月へ変更等)、月末日へ丸めず選択を破棄し、`onChange` を発火しません。実在する日は、年・月・日から組んだ日付が同じ年・月・日を名乗る日だけで、タイムゾーンが飛ばした日 (Pacific/Kiritimati の 1994 年 12 月 31 日、Pacific/Apia の 2011 年 12 月 30 日など) も存在しない日付です。その日は日の一覧に現れず、その日になる年・月も選べず、翌日へ寄せて発行することもありません。そうした選択肢 — 保持中の他 2 部位と組んで実在しない日付になるもの、および境界の外へ出るもの — は、年・月・日の 3 つの `<select>` すべてで `disabled` として描かれ、押せる範囲と発行できる範囲が一致します (1 月 31 日を保持していれば月の `2` / `4` / `6` / `9` / `11` が `disabled` になり、保持値そのものが境界の外にある間は、その保持値と組んで境界内へ収まる選択肢を 1 つも持たないセレクトの全選択肢が `disabled` になります)。選択肢のテキストは既定でゼロ埋めの数値 (`2024` / `01` / `15`) で、`formatLocale` または `formatOption` (`scope: "part"`) で変更できます。基準日は**その `<select>` の値だけ**から決まります (年は 1 月 1 日、月は当月 1 日、日は保持中の年月とその日)。Date Props (`value` / `initialDate` / `minDate` / `maxDate`) が属する年の 1 月 1 日が Date の表現範囲の外にある場合 (-271821 年の日付。表現範囲は同年 4 月 20 日 UTC から始まるため、どのタイムゾーンでも該当) は、年と月の部位を名指す基準日を組めないため prop 名を名乗る `RangeError` です (日だけを描く `variant="date"` / `"dropdown"` は受け付けます)。境界 (`minDate` / `maxDate`) のエラーは、境界を省けず `allowedDates` も使えないこの変種に合わせ、番兵の代わりに `minYear` / `maxYear` で年を宣言するよう示します。以前の描画から保持している非制御の選択がその年にあるまま `variant="split-dropdown"` で描く場合も、`variant="split-dropdown"` を名乗る `RangeError` です。起こるのは、日だけを描く変種のあいだに利用者がその年へ動かした選択を保持したまま、`initialDate` を最後に取り込んだ日と同じ日に置いて `variant="split-dropdown"` へ切り替えた場合だけです。同じ描画で別の日の `initialDate` を渡せばその描画で取り込まれ、制御から非制御へ切り替えた描画は必ず `initialDate` を取り込むため、どちらも送出しません。分割セレクトに保持させる日は `value` で制御してください。上限より後の保持年・保持月を暦の終わりまで埋める月と日の一覧は、Date の表現範囲の端 (275760 年 9 月と、その月の表現できる最後のローカル暦日) で終わります。
1414
1432
 
1415
1433
  > **既知の制約 (非グレゴリオ暦)**: グレゴリオ暦の年・月を、年や月の境界が異なる暦 (和暦・ペルシア暦など) で描く以上、「その選択肢が確定する日付の呼び名」と「同じ `<select>` の選択肢どうしが区別できること」は同時には満たせません。本パッケージは**区別できること**を採ります。そのため `ja-JP-u-ca-japanese` では 2019 年の選択肢は常に 平成31年 (1 月 1 日の元号) で、5 月を保持したまま押すと確定するのは令和元年の日付です。逆に保持日を基準日へ混ぜると、`fa-IR` では 2020 年と 2021 年の選択肢が同じペルシア年 (`۱۳۹۹`) になります (実測)。確定日の呼び名が要る利用側は `formatOption` で自分の基準日を組んでください。
1416
1434
 
@@ -1573,8 +1591,8 @@ export declare const useSelectorStepper: <T extends object>(
1573
1591
  ```
1574
1592
 
1575
1593
  - 行き先から `stepper` を作るフックです。押せるかどうかはこの描画の行き先で決まります (行き先が `null` でない向きだけ押せる)。行き先はオブジェクトか `null` で、`undefined` を返し得る出所 (`Map.get` など) は型が拒みます (欠落を押せる・押せないのどちらへも黙って読み替えないため)。
1576
- - `onStep` は最新の行き先と最新の `onStepTo` を参照で読むため、所有者が行き先とコールバックを描画ごとに作り直しても同じ関数です。押せるかどうかが変わらない限り同じオブジェクトを返すので、セレクタのメモ比較は描画を省きます。
1577
- - 最後の描画の後に行き先が消えた向きの押下は何もしません。
1594
+ - `onStep` は最後に確定した描画の行き先と `onStepTo` を参照で読むため、所有者が行き先とコールバックを描画ごとに作り直しても同じ関数です。押せるかどうかが変わらない限り同じオブジェクトを返すので、セレクタのメモ比較は描画を省きます。確定しない描画 (Suspense で中断した移行など) が作った行き先とコールバックは使いません。
1595
+ - 最後の確定の後に行き先が消えた向きの押下は何もしません。
1578
1596
 
1579
1597
  #### フックへ規則を渡す
1580
1598
 
@@ -1643,8 +1661,8 @@ const { sliderProps, macroStartSelectorProps, macroEndSelectorProps, microStartS
1643
1661
  | フック・行 | 候補を載せる間 | 載せる候補 |
1644
1662
  | :--- | :--- | :--- |
1645
1663
  | `usePeriodSliderRange` / `usePeriodSliderPoint` | `allowedDates` が空でない間 | `allowedDates` (範囲フックでは 2 つのセレクタが同じ配列を読む) |
1646
- | ノギスのマクロ行 | `macroIsDiscrete` の間 | `macroAllowedDates` (未指定なら `allowedDates`) |
1647
- | ノギスのミクロ行 | `microIsDiscrete` かつ現在の窓が候補を含む間 | 現在の窓が含む `microAllowedDates` (未指定なら `allowedDates`) |
1664
+ | ノギスのマクロ行 | `macroIsDiscrete` の間 | `macroAllowedDates` (省略 (`undefined`) なら `allowedDates`) |
1665
+ | ノギスのミクロ行 | `microIsDiscrete` かつ現在の窓が候補を含む間 | 現在の窓が含む `microAllowedDates` (省略 (`undefined`) なら `allowedDates`) |
1648
1666
 
1649
1667
  - レールが連続の間 (候補を含まない窓のミクロ行を含む) はキーそのものを載せないため、スプレッドより前に書いた `allowedMonths` などを上書きしません。スプレッドの後ろに書いた値はフックの候補より優先されます。
1650
1668
  - 候補の一覧は、フックが境界の時刻と宣言された配列の参照でメモ化します。境界へ描画ごとに値の等しい新しい `Date` を渡しても一覧は同じ参照のままで、セレクタの描画は省かれます。宣言する配列 (`allowedDates` など) は利用側でメモ化してください。
@@ -1664,6 +1682,13 @@ const { sliderProps, startSelectorProps } = usePeriodSliderRange({ unit: "day",
1664
1682
  - 候補の上にない `initialRange` / `initialValue` は拒まず、初回の描画で同じ規則により置き直します。初期値を境界と照らすのはマウント時だけです。マウント時に渡した初期値だけが `resetRange` / `resetValue` の行き先になり (後から変えた `initialRange` / `initialValue` は有効性と逆転だけを検証し、採用しません)、リセットもいまの定義域へ収めて確定します。境界が初期値を越えて動いても送出せず、ステートを収め直します。
1665
1683
  - `onChangeRange` / `onChangePoint` は、確定した値が**利用側の知っている値** (渡した初期値・`setRange` / `setValue` で自分で書いた値・最後に通知した値) と異なるときに鳴ります。ノギスの通知 (`onChangeMacroRange` / `onChangeMicroRange` / `onChangeMicroPoint`。知っている値は `setMacroRange` / `setMicroRange` / `setMicroValue` で書いた値も含む) も同じ規則です。レンダー中の収め直しはその場では通知しませんが、次にその値へ落ち着いた操作で通知されます (初回の描画で寄せた初期値も同じ)。反対に、収め直しの後で利用側の知っている値へ戻る操作は鳴りません。現在の値はコールバックではなく、フックの `range` / `value` で読めます。
1666
1684
 
1685
+ **フックの返す関数は、画面に描かれている描画 (最後に確定した描画) の値を読みます**。4 つのフックの設定関数・シフト・リセット・`sliderProps` のコールバック・セレクタの ◀▶ は、最後に確定した描画の境界・候補・コールバック・ステートを読みます。
1686
+
1687
+ - `startTransition` で渡した新しいオプションは、その描画が確定するまで使われません。確定していない描画が渡したコールバックは呼ばれません。関数の同一性は変わりません。
1688
+ - 子孫のレイアウト副作用から呼んでも、隠れた `Activity` の中でも、その確定の値を読みます。
1689
+ - 確定経路は、返す関数が最後にステートへ渡した値と同じ値を、それがステートの最後の更新だと分かっている間は渡さず、それ以外は同じ値でもステートへ渡します。そのため `startTransition` の中で呼んだ設定関数が中断している間に別の操作をしても、保存される値は最後に通知した値 (または `setRange` などで書いた値) と一致します。中断している値と同じ値を緊急に呼び直しても、その間にホストが描き直されていなければその値を緊急の優先度へ引き上げず (代替表示を出さず)、更新の後に同じ値で呼び直してもホストは描き直されません。
1690
+ - 描画中に呼ぶと、描画中の値ではなく最後に確定した描画の値を読みます (同じ描画で広げた `maxDate` ではなく、前の確定の `maxDate` で収めます)。フック自身の値と比べて描画のたびに呼ぶ追従は、値が境界・候補・窓へ置き直される場合も、置き直した値で落ち着きます。同じ描画の値で収めるには、副作用 (`useEffect` / `useLayoutEffect`) かイベントハンドラの中で呼んでください。
1691
+
1667
1692
  #### `usePeriodSliderRange(options)`
1668
1693
 
1669
1694
  | オプション | 型 | 既定値 | 説明 |
@@ -1685,7 +1710,7 @@ const { sliderProps, startSelectorProps } = usePeriodSliderRange({ unit: "day",
1685
1710
  | `setRange` | `React.Dispatch<React.SetStateAction<[Date, Date]>>` | 期間の直接更新関数 (コールバックは発火しない。レールに載らない期間はレンダー中に置き直す) |
1686
1711
  | `setLowerDate` | `(date: Date) => void` | 下限更新関数。上限を超えた場合は上限も追従し、離散レールでは最近傍の候補へ寄せる。`onChangeRange` を発火する |
1687
1712
  | `setUpperDate` | `(date: Date) => void` | 上限更新関数。下限を下回った場合は下限も追従し、離散レールでは最近傍の候補へ寄せる。`onChangeRange` を発火する |
1688
- | `shiftRange` | `(delta: number) => void` | 両端を `delta` 単位シフトし、それぞれ境界へクランプ (境界に達した側は期間幅が縮む) |
1713
+ | `shiftRange` | `(delta: number) => void` | 両端を `delta` 単位シフトし、それぞれ境界へクランプ (境界に達した側は期間幅が縮む)。和が Date の表現範囲を越える端も、境界を越えたほかの端と同じく進む向きの境界で止まる |
1689
1714
  | `resetRange` | `() => void` | `initialRange` へ復帰 (いまの定義域へ収め、離散レールでは最近傍の候補へ寄せた期間) |
1690
1715
  | `startSelectorProps` | `SelectorProps` | 開始側セレクタ用 Props (`maxDate` は現在の上限日付) |
1691
1716
  | `endSelectorProps` | `SelectorProps` | 終了側セレクタ用 Props (`minDate` は現在の下限日付) |
@@ -1707,7 +1732,7 @@ const { sliderProps, startSelectorProps } = usePeriodSliderRange({ unit: "day",
1707
1732
  | :--- | :--- | :--- |
1708
1733
  | `value` | `Date` | 現在の選択日付 |
1709
1734
  | `setValue` | `React.Dispatch<React.SetStateAction<Date>>` | 日付の直接更新関数 (コールバックは発火しない。レールに載らない日付はレンダー中に置き直す) |
1710
- | `shiftValue` | `(delta: number) => void` | 日付を `delta` 単位シフトし、境界へクランプ |
1735
+ | `shiftValue` | `(delta: number) => void` | 日付を `delta` 単位シフトし、境界へクランプ。和が Date の表現範囲を越える場合も、境界を越えたほかの和と同じく進む向きの境界で止まる |
1711
1736
  | `resetValue` | `() => void` | `initialValue` へ復帰 (いまの定義域へ収め、離散レールでは最近傍の候補へ寄せた日付) |
1712
1737
  | `selectorProps` | `SelectorProps` | セレクタ用 Props |
1713
1738
  | `sliderProps` | `PeriodSliderPointProps` | `<PeriodSlider {...sliderProps} />` へ渡す Props |
@@ -1740,8 +1765,8 @@ const { sliderProps, startSelectorProps } = usePeriodSliderRange({ unit: "day",
1740
1765
  | `setMacroUpperDate` | `(date: Date) => void` | マクロ終了日更新関数。`maxDate` より後は `maxDate` へ収め、マクロ下限を下回った場合は下限も追従 |
1741
1766
  | `setMicroLowerDate` | `(date: Date) => void` | ミクロ開始日更新関数。マクロ窓の下限より前は窓下限へ収め、ミクロ上限を超えた場合は上限も追従 |
1742
1767
  | `setMicroUpperDate` | `(date: Date) => void` | ミクロ終了日更新関数。マクロ窓の上限より後は窓上限へ収め、ミクロ下限を下回った場合は下限も追従 |
1743
- | `shiftMacroRange` | `(delta: number) => void` | マクロ窓を `delta` マクロ単位シフト。窓幅を保つため、片側でも `[minDate, maxDate]` を越えるシフトは全体を中止する (クランプしない)。`macroIsDiscrete={true}` のときはスライダー本体と同じ候補集合 (`macroAllowedDates`、未指定なら `allowedDates`) の上を `delta` 個分歩き、候補集合を外れるシフトも同じく全体中止 |
1744
- | `shiftMicroRange` | `(delta: number) => void` | ミクロ選択期間を `delta` ミクロ単位シフト。実効マクロ窓 (マクロ窓と `[minDate, maxDate]` の交差) からはみ出すシフトは全体を中止する (クランプしない)。`microIsDiscrete={true}` のときはスライダー本体と同じ候補集合 (`microAllowedDates`、未指定なら `allowedDates`) の上を `delta` 個分歩き、候補集合を外れるシフトも同じく全体中止。現在のマクロ窓に候補が 1 つも無い場合は連続として扱う |
1768
+ | `shiftMacroRange` | `(delta: number) => void` | マクロ窓を `delta` マクロ単位シフト。窓幅を保つため、片側でも `[minDate, maxDate]` を越えるシフト (和が Date の表現範囲を越える端を含む) は全体を中止する (クランプしない)。`macroIsDiscrete={true}` のときはスライダー本体と同じ候補集合 (`macroAllowedDates`、未指定なら `allowedDates`) の上を `delta` 個分歩き、候補集合を外れるシフトも同じく全体中止 |
1769
+ | `shiftMicroRange` | `(delta: number) => void` | ミクロ選択期間を `delta` ミクロ単位シフト。実効マクロ窓 (マクロ窓と `[minDate, maxDate]` の交差) からはみ出すシフト (和が Date の表現範囲を越える端を含む) は全体を中止する (クランプしない)。`microIsDiscrete={true}` のときはスライダー本体と同じ候補集合 (`microAllowedDates`、未指定なら `allowedDates`) の上を `delta` 個分歩き、候補集合を外れるシフトも同じく全体中止。現在のマクロ窓に候補が 1 つも無い場合は連続として扱う |
1745
1770
  | `resetVernier` | `() => void` | マクロ・ミクロ双方を初期値へ復帰 (窓はいまの定義域へ収め、ミクロ選択はその窓のレールへ置く) |
1746
1771
  | `macroStartSelectorProps` | `SelectorProps` | マクロ開始日セレクタ用 Props |
1747
1772
  | `macroEndSelectorProps` | `SelectorProps` | マクロ終了日セレクタ用 Props |
@@ -1778,8 +1803,8 @@ const { sliderProps, startSelectorProps } = usePeriodSliderRange({ unit: "day",
1778
1803
  | `setMacroLowerDate` | `(date: Date) => void` | マクロ開始日更新関数。`minDate` より前は `minDate` へ収め、マクロ上限を超えた場合は上限も追従 |
1779
1804
  | `setMacroUpperDate` | `(date: Date) => void` | マクロ終了日更新関数。`maxDate` より後は `maxDate` へ収め、マクロ下限を下回った場合は下限も追従 |
1780
1805
  | `setMicroDate` | `(date: Date) => void` | ミクロ時点更新関数。マクロ窓の外はマクロ窓の境界へ収める |
1781
- | `shiftMacroRange` | `(delta: number) => void` | マクロ窓を `delta` マクロ単位シフト。窓幅を保つため、片側でも `[minDate, maxDate]` を越えるシフトは全体を中止する (クランプしない)。`macroIsDiscrete={true}` のときはスライダー本体と同じ候補集合 (`macroAllowedDates`、未指定なら `allowedDates`) の上を `delta` 個分歩き、候補集合を外れるシフトも同じく全体中止 |
1782
- | `shiftMicroValue` | `(delta: number) => void` | ミクロ時点を `delta` ミクロ単位シフトし、実効マクロ窓 (マクロ窓と `[minDate, maxDate]` の交差) へクランプする。時点には保つべき幅が無いため、`shiftMicroRange` と違い端で中止せず端へ着ける。`microIsDiscrete={true}` のときはスライダー本体と同じ候補集合 (`microAllowedDates`、未指定なら `allowedDates`) の上を `delta` 個分歩き、現在のマクロ窓に候補が 1 つも無い場合は連続スライダーと同じ 1 単位シフトへ退化する (送出しない) |
1806
+ | `shiftMacroRange` | `(delta: number) => void` | マクロ窓を `delta` マクロ単位シフト。窓幅を保つため、片側でも `[minDate, maxDate]` を越えるシフト (和が Date の表現範囲を越える端を含む) は全体を中止する (クランプしない)。`macroIsDiscrete={true}` のときはスライダー本体と同じ候補集合 (`macroAllowedDates`、未指定なら `allowedDates`) の上を `delta` 個分歩き、候補集合を外れるシフトも同じく全体中止 |
1807
+ | `shiftMicroValue` | `(delta: number) => void` | ミクロ時点を `delta` ミクロ単位シフトし、実効マクロ窓 (マクロ窓と `[minDate, maxDate]` の交差) へクランプする。時点には保つべき幅が無いため、`shiftMicroRange` と違い端で中止せず端へ着ける (和が Date の表現範囲を越える場合も、進む向きの窓の端へ着く)。`microIsDiscrete={true}` のときはスライダー本体と同じ候補集合 (`microAllowedDates`、未指定なら `allowedDates`) の上を `delta` 個分歩き、現在のマクロ窓に候補が 1 つも無い場合は連続スライダーと同じ 1 単位シフトへ退化する (送出しない) |
1783
1808
  | `resetVernier` | `() => void` | マクロ窓・ミクロ時点の双方を初期値へ復帰 (窓はいまの定義域へ収め、時点はその窓のレールへ置く) |
1784
1809
  | `macroStartSelectorProps` | `SelectorProps` | マクロ開始日セレクタ用 Props |
1785
1810
  | `macroEndSelectorProps` | `SelectorProps` | マクロ終了日セレクタ用 Props |
@@ -16,7 +16,7 @@ import { SelectorStepper } from './selectorStep.js';
16
16
  export interface DateSelectorProps {
17
17
  /** Controlled selected date; required unless `initialDate` is supplied; must be a valid Date / 選択日付 (外部制御用・`initialDate` 未指定時は必須・Invalid Date 不可) */
18
18
  value?: Date;
19
- /** Initial selected date; required unless `value` is supplied; must be a valid Date / 初期選択日付 (非制御用・`value` 未指定時は必須・Invalid Date 不可) */
19
+ /** Initial selected date; required unless `value` is supplied; must be a valid Date; adopted during the render that turns the selector uncontrolled or moves it to another day, while a move within the day keeps the user's choice / 初期選択日付 (非制御用・`value` 未指定時は必須・Invalid Date 不可。非制御になった描画と別の日へ動かした描画のうちに取り込み、同じ日の中の移動では利用者の選択を置き換えない) */
20
20
  initialDate?: Date;
21
21
  /** Callback triggered when a selectable date is chosen; the ◀▶ call it too unless `stepper` takes them over / 選択可能な日付が選ばれた時のコールバック (`stepper` が引き受けない限り ◀▶ もこれを呼ぶ) */
22
22
  onChange?(date: Date): void;
@@ -37,7 +37,7 @@ export interface DateSelectorProps {
37
37
  minDate?: Date;
38
38
  /** Maximum selectable date; intersected with maxYear when both are given / 選択可能範囲の最大日付 (maxYear 併用時は厳しい方を採用) */
39
39
  maxDate?: Date;
40
- /** Discrete allowed dates list; an empty array means nothing is selectable. `undefined` is accepted explicitly, so `allowedDates={undefined}` after spreading a hook's selector props opts out of its candidates / 選択可能な離散日付配列 (空配列は「選択可能日なし」)。`undefined` を明示でき、フックのセレクタ Props を広げた後ろの `allowedDates={undefined}` で候補を外せる */
40
+ /** Discrete allowed dates list; an empty array means nothing is selectable, and a supplied value that is not an array (`null` included) throws RangeError. `undefined` is accepted explicitly, so `allowedDates={undefined}` after spreading a hook's selector props opts out of its candidates / 選択可能な離散日付配列 (空配列は「選択可能日なし」、配列でない指定値 (`null` を含む) は RangeError)。`undefined` を明示でき、フックのセレクタ Props を広げた後ろの `allowedDates={undefined}` で候補を外せる */
41
41
  allowedDates?: Date[] | undefined;
42
42
  /**
43
43
  * UI Variant:
@@ -1 +1 @@
1
- {"version":3,"file":"DateSelector.d.ts","sourceRoot":"","sources":["../src/DateSelector.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAgB9B,OAAO,EAA0B,KAAK,0BAA0B,EAAE,KAAK,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAE3G,OAAO,EAAe,KAAK,qBAAqB,EAAyB,MAAM,gBAAgB,CAAA;AAG/F,OAAO,EAA4B,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAK/E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB;IAC9B,qJAAqJ;IACrJ,KAAK,CAAC,EAAE,IAAI,CAAA;IACZ,uIAAuI;IACvI,WAAW,CAAC,EAAE,IAAI,CAAA;IAClB,sKAAsK;IACtK,QAAQ,CAAC,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAA;IAC3B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAA;IACrC,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC1B,+GAA+G;IAC/G,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,+GAA+G;IAC/G,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,gHAAgH;IAChH,OAAO,CAAC,EAAE,IAAI,CAAA;IACd,gHAAgH;IAChH,OAAO,CAAC,EAAE,IAAI,CAAA;IACd,8TAA8T;IAC9T,YAAY,CAAC,EAAE,IAAI,EAAE,GAAG,SAAS,CAAA;IACjC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,gBAAgB,CAAA;IAChD,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAA;IAC3B,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,gOAAgO;IAChO,MAAM,CAAC,EAAE,kBAAkB,CAAA;IAC3B,uVAAuV;IACvV,MAAM,CAAC,EAAE,0BAA0B,CAAA;IACnC,0PAA0P;IAC1P,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mUAAmU;IACnU,YAAY,CAAC,EAAE,qBAAqB,CAAA;CACvC;AA6nBD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,yBAAyB,GAAI,MAAM,iBAAiB,EAAE,MAAM,iBAAiB,KAAG,OA2B5F,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,oCA7aa,iBAAiB,KAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CA6aO,CAAA"}
1
+ {"version":3,"file":"DateSelector.d.ts","sourceRoot":"","sources":["../src/DateSelector.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAgB9B,OAAO,EAA0B,KAAK,0BAA0B,EAAE,KAAK,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAE3G,OAAO,EAAe,KAAK,qBAAqB,EAAyB,MAAM,gBAAgB,CAAA;AAG/F,OAAO,EAA4B,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAM/E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB;IAC9B,qJAAqJ;IACrJ,KAAK,CAAC,EAAE,IAAI,CAAA;IACZ,4UAA4U;IAC5U,WAAW,CAAC,EAAE,IAAI,CAAA;IAClB,sKAAsK;IACtK,QAAQ,CAAC,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAA;IAC3B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAA;IACrC,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC1B,+GAA+G;IAC/G,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,+GAA+G;IAC/G,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,gHAAgH;IAChH,OAAO,CAAC,EAAE,IAAI,CAAA;IACd,gHAAgH;IAChH,OAAO,CAAC,EAAE,IAAI,CAAA;IACd,gbAAgb;IAChb,YAAY,CAAC,EAAE,IAAI,EAAE,GAAG,SAAS,CAAA;IACjC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,gBAAgB,CAAA;IAChD,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAA;IAC3B,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,gOAAgO;IAChO,MAAM,CAAC,EAAE,kBAAkB,CAAA;IAC3B,uVAAuV;IACvV,MAAM,CAAC,EAAE,0BAA0B,CAAA;IACnC,0PAA0P;IAC1P,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mUAAmU;IACnU,YAAY,CAAC,EAAE,qBAAqB,CAAA;CACvC;AA0nBD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,yBAAyB,GAAI,MAAM,iBAAiB,EAAE,MAAM,iBAAiB,KAAG,OA2B5F,CAAA;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,oCA1aa,iBAAiB,KAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CA0aO,CAAA"}
@@ -16,7 +16,7 @@ import { SelectorStepper } from './selectorStep.js';
16
16
  export interface MonthSelectorProps {
17
17
  /** Controlled selected date; required unless `initialDate` is supplied / 選択日付 (外部制御用・`initialDate` 未指定時は必須) */
18
18
  value?: Date;
19
- /** Initial selected date; required unless `value` is supplied / 選択日付 (非制御用・`value` 未指定時は必須) */
19
+ /** Initial selected date; required unless `value` is supplied; adopted during the render that turns the selector uncontrolled or moves it to another month, while a move within the month keeps the user's choice / 選択日付 (非制御用・`value` 未指定時は必須。非制御になった描画と別の月へ動かした描画のうちに取り込み、同じ月の中の移動では利用者の選択を置き換えない) */
20
20
  initialDate?: Date;
21
21
  /** Callback triggered when a selectable month is chosen; the ◀▶ call it too unless `stepper` takes them over / 選択可能な月が選ばれた時のコールバック (`stepper` が引き受けない限り ◀▶ もこれを呼ぶ) */
22
22
  onChange?(date: Date, yyyymm: number): void;
@@ -42,7 +42,7 @@ export interface MonthSelectorProps {
42
42
  minDate?: Date;
43
43
  /** Upper bound date (truncated to its month); combined with `maxYear` as the stricter of the two / 可能範囲の最大日付 (月単位に切り捨て)。`maxYear` とは厳しい方を採用 */
44
44
  maxDate?: Date;
45
- /** Discrete allowed months (day part ignored), intersected with the bounds; an empty array means nothing is selectable / 選択可能な離散月配列 (日は無視・境界と積を取る・空配列は「選択可能月なし」) */
45
+ /** Discrete allowed months (day part ignored), intersected with the bounds; an empty array means nothing is selectable, and a supplied value that is not an array (`null` or a string included) throws RangeError naming the list / 選択可能な離散月配列 (日は無視・境界と積を取る・空配列は「選択可能月なし」・配列でない指定値 (`null`・文字列を含む) は一覧を名指す RangeError) */
46
46
  allowedMonths?: Date[] | undefined;
47
47
  /** Warning style flag / 警告枠スタイル適用フラグ */
48
48
  isWarning?: boolean;
@@ -1 +1 @@
1
- {"version":3,"file":"MonthSelector.d.ts","sourceRoot":"","sources":["../src/MonthSelector.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAG9B,OAAO,EAA0B,KAAK,0BAA0B,EAAE,KAAK,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAC3G,OAAO,EAA8B,KAAK,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AAGvF,OAAO,EAA4B,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAI/E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IAC/B,+GAA+G;IAC/G,KAAK,CAAC,EAAE,IAAI,CAAA;IACZ,+FAA+F;IAC/F,WAAW,CAAC,EAAE,IAAI,CAAA;IAClB,sKAAsK;IACtK,QAAQ,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3C;;;;;OAKG;IACH,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAA;IACrC,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;IAC7B,oQAAoQ;IACpQ,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,sQAAsQ;IACtQ,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,+IAA+I;IAC/I,OAAO,CAAC,EAAE,IAAI,CAAA;IACd,+IAA+I;IAC/I,OAAO,CAAC,EAAE,IAAI,CAAA;IACd,oKAAoK;IACpK,aAAa,CAAC,EAAE,IAAI,EAAE,GAAG,SAAS,CAAA;IAClC,wCAAwC;IACxC,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAA;IAC3B,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,0KAA0K;IAC1K,MAAM,CAAC,EAAE,kBAAkB,CAAA;IAC3B,2MAA2M;IAC3M,MAAM,CAAC,EAAE,0BAA0B,CAAA;IACnC,oPAAoP;IACpP,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mUAAmU;IACnU,YAAY,CAAC,EAAE,qBAAqB,CAAA;CACvC;AA0eD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,0BAA0B,GAAI,MAAM,kBAAkB,EAAE,MAAM,kBAAkB,KAAG,OA0B/F,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,oCApQa,kBAAkB,KAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAoQQ,CAAA"}
1
+ {"version":3,"file":"MonthSelector.d.ts","sourceRoot":"","sources":["../src/MonthSelector.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAG9B,OAAO,EAA0B,KAAK,0BAA0B,EAAE,KAAK,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAC3G,OAAO,EAA8B,KAAK,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AAGvF,OAAO,EAA4B,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAK/E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IAC/B,+GAA+G;IAC/G,KAAK,CAAC,EAAE,IAAI,CAAA;IACZ,wSAAwS;IACxS,WAAW,CAAC,EAAE,IAAI,CAAA;IAClB,sKAAsK;IACtK,QAAQ,CAAC,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3C;;;;;OAKG;IACH,OAAO,CAAC,EAAE,eAAe,GAAG,SAAS,CAAA;IACrC,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,UAAU,CAAA;IAC7B,oQAAoQ;IACpQ,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,sQAAsQ;IACtQ,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,+IAA+I;IAC/I,OAAO,CAAC,EAAE,IAAI,CAAA;IACd,+IAA+I;IAC/I,OAAO,CAAC,EAAE,IAAI,CAAA;IACd,2TAA2T;IAC3T,aAAa,CAAC,EAAE,IAAI,EAAE,GAAG,SAAS,CAAA;IAClC,wCAAwC;IACxC,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,+CAA+C;IAC/C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,2BAA2B;IAC3B,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAA;IAC3B,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,0KAA0K;IAC1K,MAAM,CAAC,EAAE,kBAAkB,CAAA;IAC3B,2MAA2M;IAC3M,MAAM,CAAC,EAAE,0BAA0B,CAAA;IACnC,oPAAoP;IACpP,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,mUAAmU;IACnU,YAAY,CAAC,EAAE,qBAAqB,CAAA;CACvC;AAqeD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,0BAA0B,GAAI,MAAM,kBAAkB,EAAE,MAAM,kBAAkB,KAAG,OA0B/F,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,oCA/Pa,kBAAkB,KAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CA+PQ,CAAA"}