@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.
- package/CHANGELOG.md +359 -0
- package/README.md +97 -66
- package/dist/DateSelector.d.ts +2 -2
- package/dist/DateSelector.d.ts.map +1 -1
- package/dist/MonthSelector.d.ts +2 -2
- package/dist/MonthSelector.d.ts.map +1 -1
- package/dist/PeriodSlider.d.ts +324 -47
- package/dist/PeriodSlider.d.ts.map +1 -1
- package/dist/VirtualDateDropdown.d.ts +19 -1
- package/dist/VirtualDateDropdown.d.ts.map +1 -1
- package/dist/YearSelector.d.ts +4 -2
- package/dist/YearSelector.d.ts.map +1 -1
- package/dist/index.cjs +1 -1
- package/dist/index.js +2723 -2593
- package/dist/inputValue.d.ts +98 -21
- package/dist/inputValue.d.ts.map +1 -1
- package/dist/optionText.d.ts +1 -1
- package/dist/optionText.d.ts.map +1 -1
- package/dist/selectorMemo.d.ts +14 -0
- package/dist/selectorMemo.d.ts.map +1 -1
- package/dist/selectorStep.d.ts +25 -30
- package/dist/selectorStep.d.ts.map +1 -1
- package/dist/useCommittedRef.d.ts +99 -0
- package/dist/useCommittedRef.d.ts.map +1 -0
- package/dist/usePeriodSlider.d.ts +74 -40
- package/dist/usePeriodSlider.d.ts.map +1 -1
- package/dist/useUncontrolledSelection.d.ts +40 -0
- package/dist/useUncontrolledSelection.d.ts.map +1 -0
- package/dist/vernierStep.d.ts +10 -1
- package/dist/vernierStep.d.ts.map +1 -1
- package/package.json +1 -1
- package/src/DateSelector.tsx +34 -67
- package/src/MonthSelector.tsx +24 -57
- package/src/PeriodSlider.tsx +614 -198
- package/src/VirtualDateDropdown.tsx +90 -46
- package/src/YearSelector.tsx +34 -56
- package/src/inputValue.ts +159 -21
- package/src/optionText.ts +3 -5
- package/src/selectorMemo.ts +18 -3
- package/src/selectorStep.ts +46 -58
- package/src/useCommittedRef.ts +236 -0
- package/src/usePeriodSlider.ts +536 -289
- package/src/useUncontrolledSelection.ts +83 -0
- package/src/valueSet.ts +1 -1
- package/src/vernierStep.ts +19 -17
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]`
|
|
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
|
|
|
@@ -819,11 +819,11 @@ export function FiscalQuarterLabelExample() {
|
|
|
819
819
|
| プロパティ | 型 | 既定値 | 説明 |
|
|
820
820
|
| :--- | :--- | :--- | :--- |
|
|
821
821
|
| `mode` | `"range" \| "point" \| "vernier"` | (必須) | 操作モード (`range`: 2 点範囲選択, `point`: 1 点選択, `vernier`: ノギス 2 段スケール一体型) |
|
|
822
|
-
| `unit` | `"year" \| "month" \| "day"` | (必須) |
|
|
822
|
+
| `unit` | `"year" \| "month" \| "day"` | (必須) | 時間解像度単位。`"year"` / `"month"` / `"day"` 以外 (`null` を含む) は `RangeError` |
|
|
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)`、ノギスの行が継いだときは `PeriodSlider: allowedDates (inherited by the micro row) must be an array of Dates (received: null)`)。どちらの `RangeError` も一覧を読む所で送出する。range / point は `unit` で読み、ノギスは自分の一覧を省略した離散の行 (`macroIsDiscrete` / `microIsDiscrete`) だけがその行の単位で読む (継ぐ行が無ければ読まず、検証もしない) |
|
|
827
827
|
| `snapMode` | `"index" \| "time"` | `"index"` | 離散スナップ時の配置方式 (`"index"`: 配列インデックス均等, `"time"`: 実時間比例)。実時間軸やチャートと位置を揃える場合は `"time"` を明示指定 |
|
|
828
828
|
| `labelPosition` | `"top" \| "bottom"` | `"top"` | 日付ラベルの表示位置 (スライダーの上側または下側) |
|
|
829
829
|
| `autoSlantLabels` | `boolean` | `true` | 近接時にラベルを斜め〜90° に自動傾斜させて重なりを防止 (Range の 1 対とノギスの 2 対へ対ごとに適用。垂直レイアウトでは適用されない) |
|
|
@@ -847,7 +847,7 @@ export function FiscalQuarterLabelExample() {
|
|
|
847
847
|
| プロパティ | 型 | 既定値 | 説明 |
|
|
848
848
|
| :--- | :--- | :--- | :--- |
|
|
849
849
|
| `range` | `[Date, Date]` | `undefined` | 制御 (Controlled) 時の選択期間タプル [開始, 終了]。指定時は本 Props が単一真実源 |
|
|
850
|
-
| `defaultRange` | `[Date, Date]` | `undefined` | 非制御 (Uncontrolled) 時の初期選択期間タプル。`range`
|
|
850
|
+
| `defaultRange` | `[Date, Date]` | `undefined` | 非制御 (Uncontrolled) 時の初期選択期間タプル。`range` 指定時は無視。ノギスでマウントした木を `range` へ切り替えたときは (ミクロ選択の制御・非制御に依らず)、新しくマウントした場合と同じ位置から始め、平レールを最初に操作するまでこの値の変更に従う |
|
|
851
851
|
| `onChangeRange` | `(lower: Date, upper: Date) => void` | `undefined` | 選択期間変更時コールバック |
|
|
852
852
|
|
|
853
853
|
`range` / `defaultRange` を共に省略した場合、両つまみは `minDate` (離散時は候補日付の先頭) に重なり、幅ゼロの期間として描画されます (この状態のラベルは 1 枚へ畳まれます)。意図した期間は必ずどちらかで与えてください。
|
|
@@ -857,7 +857,7 @@ export function FiscalQuarterLabelExample() {
|
|
|
857
857
|
| プロパティ | 型 | 既定値 | 説明 |
|
|
858
858
|
| :--- | :--- | :--- | :--- |
|
|
859
859
|
| `value` | `Date` | `undefined` | 制御 (Controlled) 時の選択日付。指定時は本 Props が単一真実源 |
|
|
860
|
-
| `defaultValue` | `Date` | `undefined` | 非制御 (Uncontrolled) 時の初期選択日付。`value`
|
|
860
|
+
| `defaultValue` | `Date` | `undefined` | 非制御 (Uncontrolled) 時の初期選択日付。`value` 指定時は無視。ノギスでマウントした木を `point` へ切り替えたときは (ミクロ選択の制御・非制御に依らず)、新しくマウントした場合と同じ位置から始め、平レールを最初に操作するまでこの値の変更に従う |
|
|
861
861
|
| `onChangePoint` | `(value: Date) => void` | `undefined` | 選択日付変更時コールバック |
|
|
862
862
|
|
|
863
863
|
`value` / `defaultValue` を共に省略した場合、選択日付は定義域下限 (`minDate`、離散時は候補日付の先頭) として描画されます。
|
|
@@ -870,12 +870,12 @@ export function FiscalQuarterLabelExample() {
|
|
|
870
870
|
| :--- | :--- | :--- | :--- |
|
|
871
871
|
| `macroRange` | `[Date, Date]` | (必須) | マクロ側の広域表示窓 [開始, 終了]。制御専用 (非制御版は存在しない)。欠落・2 要素タプル以外・Invalid Date・逆転 (`end` が `start` より前) は `RangeError`。`start` と `end` が同値の場合は 1 マクロ単位幅の窓として有効 |
|
|
872
872
|
| `onChangeMacroRange` | `(lower: Date, upper: Date) => void` | `undefined` | マクロ窓変更時コールバック |
|
|
873
|
-
| `macroUnit` | `"year" \| "month" \| "day"` | `unit` | マクロ側時間解像度単位 (異単位構成用)。`macroUnit` で `minDate` と `maxDate`
|
|
874
|
-
| `microUnit` | `"year" \| "month" \| "day"` | `unit` | ミクロ側時間解像度単位 (異単位構成用) |
|
|
875
|
-
| `macroIsDiscrete` | `boolean` | `false` |
|
|
876
|
-
| `microIsDiscrete` | `boolean` | `false` |
|
|
877
|
-
| `macroAllowedDates` | `Date[]` | `allowedDates` | マクロ側の離散スナップ対象日付配列。`macroIsDiscrete={true}`
|
|
878
|
-
| `microAllowedDates` | `Date[]` | `allowedDates` | ミクロ側の離散スナップ対象日付配列。`microIsDiscrete={true}`
|
|
873
|
+
| `macroUnit` | `"year" \| "month" \| "day"` | `unit` | マクロ側時間解像度単位 (異単位構成用)。`macroUnit` で `minDate` と `maxDate` が同じ単位へ丸められる定義域も、1 マクロ単位の定義域として描く。既定の `unit` は省略 (`undefined`) のときだけ。`null` を含む宣言外の値は `RangeError` |
|
|
874
|
+
| `microUnit` | `"year" \| "month" \| "day"` | `unit` | ミクロ側時間解像度単位 (異単位構成用)。既定の `unit` は省略 (`undefined`) のときだけ。`null` を含む宣言外の値は `RangeError` |
|
|
875
|
+
| `macroIsDiscrete` | `boolean` | `false` | マクロ側の離散スナップ有効化フラグ。離散にするのは `true` だけで、それ以外 (省略・`false`・`1` などの真偽値以外の値) の間は `macroAllowedDates` (省略時に継ぐ `allowedDates`) が参照されない。ノギスのフックも同じ規則で読む |
|
|
876
|
+
| `microIsDiscrete` | `boolean` | `false` | ミクロ側の離散スナップ有効化フラグ。離散にするのは `true` だけで、それ以外 (省略・`false`・`1` などの真偽値以外の値) の間は `microAllowedDates` (省略時に継ぐ `allowedDates`) が参照されない。ノギスのフックも同じ規則で読む。`true` かつ現在のマクロ窓が候補を 1 つ以上含む間、ミクロレールは候補集合しか描かないため、位置・`aria-valuenow` / `aria-valuetext`・ラベル・**確定値**のすべてが最近傍候補へ解決される (ドラッグ・キーボード・ホイール・ステッパー・フックの収め込みで同一規則)。窓が候補を 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`) を指定 |
|
|
@@ -969,6 +969,8 @@ DOM 要素の特定は CSS クラス名ではなく `data-*` 属性で行いま
|
|
|
969
969
|
|
|
970
970
|
セレクタの ◀▶ が期間・窓をどう動かすかの規則 (`resolveSelectorSteps` / `resolveVernierSelectorSteps`) も React に依存しない純粋関数です。契約は [セレクタの矢印を所有者が引き受ける](#セレクタの矢印を所有者が引き受ける-stepper-と-1-歩の規則) にまとめてあります。
|
|
971
971
|
|
|
972
|
+
単位を受け取る公開関数 (`normalizeDateByUnit` / `encode` / `decode` / `addUnit` / `getMacroWindowStartDate` / `getMacroWindowEndDate` / `resolveMacroWindow` / `findNearestDateIndex` / `getSortedAllowedDates` / `formatLabel` / `formatScreenReaderLabel` / `formatOptionText` / `calculateConnectDragValues` / `resolveSelectorSteps` / `resolveVernierSelectorSteps`) は、`"year"` / `"month"` / `"day"` 以外の単位 (`null`・大文字違い・空文字列を含む。省略できない単位の引数では `undefined` も) を日として読まず、`RangeError: <関数名>: <引数名> must be one of "year", "month", "day" (received: ...)` で拒否します (`encode: unit must be one of "year", "month", "day" (received: "decade")`)。単位は `yearStartMonth`・日付・`amount`・候補の一覧より先、無効日付の短絡 (`formatLabel` / `formatScreenReaderLabel` / `formatOptionText` の `""`) と早期 return (`findNearestDateIndex` / `getSortedAllowedDates` の空の一覧、`calculateConnectDragValues` の連続モード) より先に判定します。`resolveSelectorSteps` / `resolveVernierSelectorSteps` だけは、オプションがオブジェクトであること (`resolveVernierSelectorSteps` は `row` / `shows` も) を単位より先に判定します。`resolveSelectorSteps` の `stepUnit` が `unit` になるのは省略 (`undefined`) したときだけで、`null` は同じ `RangeError` です。
|
|
973
|
+
|
|
972
974
|
#### 表示テキスト — `formatOptionText` / `PeriodOptionFormatter` / `PeriodOptionScope`
|
|
973
975
|
|
|
974
976
|
```ts
|
|
@@ -984,7 +986,7 @@ export declare const formatOptionText: (date: Date, unit: PeriodSliderUnit, scop
|
|
|
984
986
|
- `formatOptionText` は**組み込みの 2 段そのもの**です (`formatLocale` 指定時は `Intl.DateTimeFormat`、未指定時はロケール非依存の ISO 8601)。第 1 段を担当しない (`unit`, `scope`) の組は、この関数へそのまま転送してください。引数順がコールバックと同一なので逐語転送できます。
|
|
985
987
|
- **「`undefined` を返したら既定」という形は採っていません**。それは代替値連鎖であり、本パッケージが排している形です。返り値は常に文字列で、**空文字列も合法**です (無効な日付に対する `formatLabel` の仕様値と同じ)。
|
|
986
988
|
- `date` が未指定・Invalid Date のときは `""` を返します (`formatLabel` と同じ約束)。
|
|
987
|
-
- `unit` が `"year"` / `"month"` / `"day"` 以外、`scope` が `"period"` / `"part"` 以外の場合は `RangeError` を送出し、メッセージは関数自身を名指しします (`formatOptionText: scope must be "period" or "part" (received: "label")`)。フォーマッタ Props は型検査を受けますが、この関数は公開の入口であり JavaScript からも引数が届くためです。
|
|
989
|
+
- `unit` が `"year"` / `"month"` / `"day"` 以外、`scope` が `"period"` / `"part"` 以外の場合は `RangeError` を送出し、メッセージは関数自身を名指しします (`formatOptionText: unit must be one of "year", "month", "day" (received: "quarter")` は単位を受け取る他の公開関数と同じ文言、`formatOptionText: scope must be "period" or "part" (received: "label")`)。フォーマッタ Props は型検査を受けますが、この関数は公開の入口であり JavaScript からも引数が届くためです。
|
|
988
990
|
|
|
989
991
|
`formatOptionText(date, unit, scope, formatLocale)` の出力 (`date` は `2025-04-15`):
|
|
990
992
|
|
|
@@ -1055,16 +1057,17 @@ yearStartMonth=9 2,2,2,3,3,3,4,4,4,1,1,1
|
|
|
1055
1057
|
| `normalizeDateByUnit(unit, d, yearStartMonth = 0)` | 単位先頭への正規化。`unit="year"` は「その日を含む年」の先頭月 1 日 |
|
|
1056
1058
|
| `encode(unit, d, yearStartMonth = 0)` | 比較用の整数キー。`unit="year"` では年番号そのもの |
|
|
1057
1059
|
| `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)` |
|
|
1060
|
+
| `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: ...)` など |
|
|
1061
|
+
| `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
1062
|
| `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)` |
|
|
1063
|
+
| `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` を返す) |
|
|
1064
|
+
| `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
1065
|
|
|
1064
1066
|
- `yearStartMonth` は**必ず末尾**の引数です。省けば既定の `0` (暦年) で計算されます。
|
|
1065
1067
|
- 未指定 (`undefined`) は仕様上の値である `0` (暦年) です。`null` は既定引数が効かないため `RangeError` になります。`12` / `-1` / `1.5` / `NaN` / `Infinity` / `"3"` も同じく拒否され、近い月へ丸められることはありません。
|
|
1066
|
-
- 検証は**早期 return より前**に行われます。空配列を渡した `getSortedAllowedDates` や 1 要素しかない `findNearestDateIndex`
|
|
1068
|
+
- 検証は**早期 return より前**に行われます。空配列を渡した `getSortedAllowedDates` や 1 要素しかない `findNearestDateIndex` でも、宣言外の単位や不正な `yearStartMonth` が素通りすることはありません (単位は `yearStartMonth` より先に判定します)。
|
|
1067
1069
|
- **`addUnit(unit, d, amount)` は意図的にこの引数を受け取りません。** 開始月をずらした年もちょうど 12 か月であり、加算の結果は `yearStartMonth` に依存しないためです。無視するだけの引数を置けば、「渡せば効く」という嘘の契約を名乗ることになります。
|
|
1070
|
+
- `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
1071
|
|
|
1069
1072
|
### 実行時バリデーション (Fail Fast)
|
|
1070
1073
|
|
|
@@ -1072,9 +1075,14 @@ yearStartMonth=9 2,2,2,3,3,3,4,4,4,1,1,1
|
|
|
1072
1075
|
|
|
1073
1076
|
| コンポーネント / 関数 | 条件 | 例外 |
|
|
1074
1077
|
| :--- | :--- | :--- |
|
|
1078
|
+
| `PeriodSlider` | `unit` が `"year"` / `"month"` / `"day"` 以外 (`null` を含む。全モードで、年の開始月・定義域より先に判定) | `RangeError: PeriodSlider: unit must be one of "year", "month", "day" (received: ...)` |
|
|
1079
|
+
| `PeriodSlider` (`vernier`) | 指定した `macroUnit` / `microUnit` が `"year"` / `"month"` / `"day"` 以外 (`null` を含む。`unit` になるのは省略 (`undefined`) したときだけ。`unit` の次にこの順で判定) | `RangeError: PeriodSlider: macroUnit must be one of "year", "month", "day" (received: null)` |
|
|
1080
|
+
| `usePeriodSliderRange` / `usePeriodSliderPoint` / `useVernierSliderRange` / `useVernierSliderPoint` | 毎描画: `unit` (ノギスのフックは続いて指定した `macroUnit` / `microUnit`) が `"year"` / `"month"` / `"day"` 以外 (`null` を含む。ノギスの行の単位が `unit` になるのは省略したときだけ。年の開始月を含む他のどのオプションより先に判定) | `RangeError: useVernierSliderRange: microUnit must be one of "year", "month", "day" (received: "decade")` |
|
|
1081
|
+
| 単位を受け取る公開関数 (「公開ユーティリティ関数」の一覧) | 単位の引数が `"year"` / `"month"` / `"day"` 以外 (`null` を含む。省略できない単位の引数では `undefined` も。他の引数・無効日付の短絡・早期 return より先に判定。1 歩の関数 2 つ (`resolveSelectorSteps` / `resolveVernierSelectorSteps`) だけは、オプションがオブジェクトであること (`resolveVernierSelectorSteps` は `row` / `shows` も) を先に判定) | `RangeError: <関数名>: <引数名> must be one of "year", "month", "day" (received: ...)` |
|
|
1075
1082
|
| `PeriodSlider` | `minDate` が未指定または Invalid Date | `RangeError: PeriodSlider: minDate is required and must be a valid Date (received: ...)` |
|
|
1076
1083
|
| `PeriodSlider` | `maxDate` が未指定または Invalid Date | `RangeError: PeriodSlider: maxDate is required and must be a valid Date (received: ...)` |
|
|
1077
1084
|
| `PeriodSlider` | `maxDate <= minDate` | `RangeError: PeriodSlider: maxDate must be strictly later than minDate (...)` |
|
|
1085
|
+
| `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
1086
|
| `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
1087
|
| `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
1088
|
| `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,35 +1092,47 @@ yearStartMonth=9 2,2,2,3,3,3,4,4,4,1,1,1
|
|
|
1084
1092
|
| `PeriodSlider` (`vernier`) | 指定された `microValue` / `defaultMicroValue` が Invalid Date | `RangeError: PeriodSlider: <プロパティ名> must be a valid Date (received: ...)` |
|
|
1085
1093
|
| `PeriodSlider` (`vernier`) | 制御のミクロ選択と並べた既定値が不正・定義域外 | `RangeError: PeriodSlider: defaultMicroValue must be a valid Date (received: null)` など |
|
|
1086
1094
|
| `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` | `
|
|
1089
|
-
| `PeriodSlider` | `allowedDates`
|
|
1095
|
+
| `PeriodSlider` (`vernier`) | 指定されたミクロ選択が `microUnit` の解像度で `[minDate, maxDate]` の外 | `RangeError: PeriodSlider: <プロパティ名> must lie within [minDate, maxDate] (...)` (`macroRange` は定義域をはみ出してよい。レールが定義域と積を取り、通知はクランプ済みの値を配るため。ただし `macroRange[0]` の `macroUnit` の始まりは Date の表現範囲に入ること) |
|
|
1096
|
+
| `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: ...)` (救済は添えない) |
|
|
1097
|
+
| `PeriodSlider` / `usePeriodSliderRange` / `usePeriodSliderPoint` / `useVernierSliderRange` / `useVernierSliderPoint` | 指定された候補の一覧が配列でない (`null`・単独の Date・文字列・配列風のオブジェクト・取り消した Proxy)。所有者は読んだ一覧だけを検証する。`PeriodSlider` は range / point では `allowedDates` を `unit` で、ノギスでは離散の行 (`macroIsDiscrete` / `microIsDiscrete` が `true` の行) の一覧 (`macroAllowedDates` / `microAllowedDates`、自分の一覧を省略した行なら継いだ `allowedDates`) をその行の単位で検証する。継ぐ行の無いノギスの `allowedDates` は読まない。平レールのフックは `allowedDates` を、ノギスのフックは本体と同じ行の一覧を同じ単位で検証し、行を離散と読むのも本体と同じくフラグが `true` のときだけのため、フックが受け付けた一覧を、それを描く `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)` |
|
|
1098
|
+
| 同上 | 同じ一覧の要素が有効な 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")` |
|
|
1099
|
+
| 同上 | 同じ一覧の要素の、その行の単位の始まりが Date の表現範囲の外 (定義域の外の要素のように黙って除かない) | `RangeError: PeriodSlider: allowedDates[1] must fall in a month that starts inside the Date range (received: ...)` |
|
|
1100
|
+
| 同上 | 同じ一覧の全要素が、その行の単位で `[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
1101
|
| `usePeriodSliderRange` / `usePeriodSliderPoint` / `useVernierSliderRange` / `useVernierSliderPoint` | 境界・初期値の欠落、Invalid Date、逆転。マウント時の初期値が定義域 (ノギスのミクロの初期値は初期の窓) の外 (マウント後に境界が初期値を越えて動いても送出しない) | `RangeError: <フック名>: ...` |
|
|
1102
|
+
| 同上 | 毎描画: `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: ...)` |
|
|
1103
|
+
| 同上 | 設定関数・セレクタのコールバック・`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
1104
|
| `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
1105
|
| `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
1106
|
| `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
1107
|
| `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")` 等 |
|
|
1095
|
-
| `
|
|
1096
|
-
| `
|
|
1097
|
-
| `
|
|
1098
|
-
| `
|
|
1099
|
-
| `MonthSelector` / `YearSelector` | 同上 | ``RangeError: <コンポーネント名>: `formatLocale` must be a valid BCP 47 language tag, received ....`` |
|
|
1108
|
+
| `resolveMacroWindow` | 宣言外の `macroUnit` / `microUnit` (この順に最初に判定)、`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: ...)` 等 (すべて自身の名を名乗る) |
|
|
1109
|
+
| `resolveSelectorSteps` | オプションがオブジェクトでない、未知の `unit` / `stepUnit` (`null` を含む) / `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, ...` 等 |
|
|
1110
|
+
| `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] (...)` 等 |
|
|
1111
|
+
| 4 部品すべて | `formatLocale` が空文字列・構造として不正な BCP 47 タグ・非文字列 | `RangeError: <コンポーネント名>: formatLocale must be a valid BCP 47 language tag (received: ...)` |
|
|
1100
1112
|
| 4 部品すべて | `locale` が `"en"` / `"ja"` 以外 (`"ja-JP"`・`"EN"`・`""`・`null` 等) | `RangeError: [period-slider] locale is the UI language, not a BCP 47 tag (date formatting reads formatLocale): [virtualscroll] locale must be one of "en", "ja"; got ...` (`cause` はエンジンの `RangeError`) |
|
|
1101
1113
|
| 4 部品すべて | `labels` が `null`・非オブジェクト・素のオブジェクトでない・未知キー (`*AriaLabel` の名前を含む)・空白や非文字列の値 | `RangeError: [period-slider] labels ...` (エンジン 7 キーの値は `RangeError: [virtualscroll] labels.<キー> must be a non-blank string; ...`) |
|
|
1102
|
-
| `YearSelector` / `MonthSelector` / `DateSelector` | `value` と `initialDate` が共に未指定 | `RangeError: <コンポーネント名>: either
|
|
1103
|
-
| `YearSelector` / `MonthSelector` | `stepper` がオブジェクトでない、`onStep` が関数でない、`canStepPrevious` / `canStepNext` が真偽値でない、または `value` を渡さずに `stepper` を渡した |
|
|
1104
|
-
| `DateSelector` | 同上 | `RangeError: DateSelector: "stepper.canStepNext" must be a boolean (received undefined)` / `... "stepper" requires the controlled "value"; ...` |
|
|
1114
|
+
| `YearSelector` / `MonthSelector` / `DateSelector` | `value` と `initialDate` が共に未指定 | `RangeError: <コンポーネント名>: either value (controlled) or initialDate (uncontrolled) is required; ...` |
|
|
1115
|
+
| `YearSelector` / `MonthSelector` / `DateSelector` | `stepper` がオブジェクトでない、`onStep` が関数でない、`canStepPrevious` / `canStepNext` が真偽値でない、または `value` を渡さずに `stepper` を渡した | `RangeError: MonthSelector: stepper.onStep must be a function (received: "next")` / `RangeError: DateSelector: stepper.canStepNext must be a boolean (received: undefined)` / `... stepper requires the controlled value; ...` |
|
|
1105
1116
|
| `YearSelector` | 境界の欠落・矛盾、Date / 年 Props の不正値、`allowedYears` の要素が Invalid Date または `Date` でない (`undefined`・疎配列の穴を含む。添字付きで報告) | `RangeError` |
|
|
1106
|
-
| `YearSelector` | Date Props (`value` / `initialDate` / `minDate` / `maxDate` / `allowedYears` の要素) を含む年、または年 Props (`minYear` / `maxYear`) の年の始まり (`yearStartMonth` の月の 1 日) が Date の表現範囲の外 (`new Date(-8.64e15)` はどのタイムゾーンでも該当) |
|
|
1107
|
-
| `MonthSelector` | 境界の矛盾、`allowedMonths` を伴わない `variant="dropdown"` での境界の欠落、`allowedMonths` の要素が Invalid Date または `Date` でない (`undefined`・疎配列の穴を含む。添字付きで報告)、Date / 年 Props の不正値 |
|
|
1108
|
-
| `MonthSelector` | Date Props (`value` / `initialDate` / `minDate` / `maxDate` / `allowedMonths` の要素) の月の始まり、または年 Props が名指す端の月 (`minYear` の 1 月・`maxYear` の 12 月) の始まりが Date の表現範囲 (±8.64e15 ms) の外 |
|
|
1117
|
+
| `YearSelector` | Date Props (`value` / `initialDate` / `minDate` / `maxDate` / `allowedYears` の要素) を含む年、または年 Props (`minYear` / `maxYear`) の年の始まり (`yearStartMonth` の月の 1 日) が Date の表現範囲の外 (`new Date(-8.64e15)` はどのタイムゾーンでも該当) | `RangeError: YearSelector: minDate must fall in a year that starts inside the Date range (received: ...); ...` / `... maxYear must name a year that starts inside the Date range (received: 275760); under yearStartMonth 9 that year starts on month 10, day 1` |
|
|
1118
|
+
| `MonthSelector` | 境界の矛盾、`allowedMonths` を伴わない `variant="dropdown"` での境界の欠落、`allowedMonths` の要素が Invalid Date または `Date` でない (`undefined`・疎配列の穴を含む。添字付きで報告)、Date / 年 Props の不正値 | `RangeError: MonthSelector: allowedMonths[1] must be a valid Date (received: ...)` 等 |
|
|
1119
|
+
| `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 (received: ...); ...` / `... maxYear must name a year whose December starts inside the Date range (received: ...)` |
|
|
1109
1120
|
| `DateSelector` | Date / 年 Props の不正値、`allowedDates` の要素が Invalid Date または `Date` でない (`undefined`・疎配列の穴を含む。添字付きで報告)、解決後の範囲が空、バリアントが要求する境界の欠落、`variant="split-dropdown"` への `allowedDates` 指定 | `RangeError` |
|
|
1110
|
-
| `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:
|
|
1121
|
+
| `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 in a day that starts inside the Date range (received: ...); ...` / `... maxYear must name a year whose last day starts inside the Date range (received: ...)` (`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 (received: ...); ...` / `... variant="split-dropdown" cannot draw the uncontrolled selection held from an earlier render (holding ...), because that selection's year starts outside the Date range; ...` |
|
|
1122
|
+
| `YearSelector` / `MonthSelector` / `DateSelector` | 指定された `allowedYears` / `allowedMonths` / `allowedDates` が配列でない (`null`・単独の Date・文字列・配列風のオブジェクト・取り消した Proxy。文字列を 1 文字ずつ要素として読まず、一覧そのものを名指す。`variant="split-dropdown"` の `DateSelector` は形を問う前に `allowedDates` の指定そのものを拒否する) | `RangeError: YearSelector: allowedYears must be an array of Dates (received: null)` / `RangeError: MonthSelector: allowedMonths must be an array of Dates (received: "2024")` / `RangeError: DateSelector: allowedDates must be an array of Dates (received: null)` |
|
|
1123
|
+
|
|
1124
|
+
拒否メッセージは、`labels` と `locale` の検証を除き、どの部品・フック・純関数でも `<所有者>: <パス> <条件> (received: <値>)<直し方>` の形です。パス (`minDate`・`allowedYears[1]`・`stepper.onStep`) は引用符で囲みません。比べた 2 つの値は 1 つの括弧の中に名前付きで並べ (`(lower: ..., upper: ...)`・`(minDate: ..., maxDate: ...)`)、保持している値は `(holding ...)` で示し、値が 1 つに定まらない条件は文で示します。条件はその理由を括弧の前に述べることがあり、直し方は閉じ括弧の後に `; ...` で続けます。末尾に句点は付けません。同じ条件 (候補の一覧の形・単位の始まりが表現範囲の外にある日付・`formatLocale`・セレクタの `stepper`) は、どの部品でも同じ文言で拒否します (`variant="split-dropdown"` の `DateSelector` が年を描くために Date Props の年の始まりを問う検査は、理由を添える `DateSelector` 自身の文言です)。
|
|
1111
1125
|
|
|
1112
|
-
メッセージに載る受け取った値と保持している値 (`received` / `holding`) は、パッケージ全体で 1 つの規則で示します。文字列は JSON の引用符付き (`"2024-02-12"`・`""`) で、日付に見える文字列や空文字列も Date や未指定と見分けられます。有効な Date は ISO 8601
|
|
1126
|
+
メッセージに載る受け取った値と保持している値 (`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`) / 年 (`YearSelector`) で示します (`YearSelector: the resolved upper bound must not precede the resolved lower bound (lower: 2031, upper: 2030)`)。
|
|
1127
|
+
|
|
1128
|
+
**候補の一覧の拒否は、読んだ所有者と一覧を名乗ります。** 所有者は `PeriodSlider`・4 つのフック・3 セレクタで、一覧は利用側が書いた名前 (`allowedDates` / `macroAllowedDates` / `microAllowedDates` / `allowedYears` / `allowedMonths`) です。ノギスの行が自分の一覧を省略 (`undefined`) して共有の `allowedDates` を継いだときは、半角スペースに続けて `(inherited by the macro row)` / `(inherited by the micro row)` を添えます (要素が定義域に入るかは行の単位で決まるため)。ノギスは平レールを描かないため、本体もノギスのフックも共有の `allowedDates` を、それを継ぐ離散の行の読み出しでだけ、その行の単位で読みます。継いだ一覧のどの誤り (形の誤り・有効な Date でない要素・行の単位の始まりが表現範囲の外にある要素・行の単位での全滅) にも行の名が付きます (`PeriodSlider: allowedDates[3] (inherited by the micro row) must be a valid Date (...)`)。両方の行が読むときはミクロ行を先に読んで名乗ります (両方の行が共有の一覧を継ぐときも、両方の行の自分の一覧が不正なときも)。継ぐ行の無いノギス (離散のフラグを降ろした行と、自分の一覧を持つ行だけの構成) は `allowedDates` を読まず、検証もしません。本体とフックは同じ一覧を同じ行の単位で読むため、フックが受け付けた一覧を、それを描く `PeriodSlider` が拒否することはありません。`getSortedAllowedDates` を直接呼んだときは自身の名を名乗ります。
|
|
1113
1129
|
|
|
1114
1130
|
**定義域の内包は、値が載るレールの解像度で判定します。** レールが描くのは単位まるごと (年・月・日) であるため、`minDate` が期間の途中を指す場合 (`unit="month"` に `2026-09-15`、`unit="day"` に時刻を持つ `new Date()` など) は、その期間まるごと (`2026-09-01`) がレールの先頭として描かれ、`Home` キー・ステッパー・ドラッグ・フックはいずれもその日付を確定値として配ります。したがってその日付をそのまま制御 Props (`range` / `value` / `microRange` など) へ戻しても受理されます。1 単位でも外れた日付は `RangeError` です。
|
|
1115
1131
|
|
|
1132
|
+
**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` のはみ出しの扱いを受けます。
|
|
1133
|
+
|
|
1134
|
+
**計算で 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 年の窓も同じ暦の算術で数えるため、月 × 日の窓はその年の月末日で閉じます。
|
|
1135
|
+
|
|
1116
1136
|
`DateSelector` は構成そのものの矛盾を優先して報告します。`variant="split-dropdown"` と `allowedDates` の併用は、`value` / `initialDate` の欠落よりも先に判定されます。
|
|
1117
1137
|
|
|
1118
1138
|
### カラーテーマ & ダークモード
|
|
@@ -1252,6 +1272,8 @@ yearStartMonth=9 2,2,2,3,3,3,4,4,4,1,1,1
|
|
|
1252
1272
|
|
|
1253
1273
|
Date 型 Props (`value` / `initialDate` / `minDate` / `maxDate`) は描画のたびに検証します。再描画で Date でない値 (文字列・数値・`null`・素のオブジェクト) や Invalid Date を渡すと、初回のマウントと同じく、その描画で Props 名を名指す `RangeError` になります。制御中で表示に効かない `initialDate` も同じです。同じ年・月・日の中で動いただけの有効な Date は、ほかの Props が変わらなければ再描画を起こしません (メモ比較器が単位で比べるため)。
|
|
1254
1274
|
|
|
1275
|
+
非制御の `initialDate` は、非制御になった描画 (マウントと、制御から非制御への切り替え) と、最後に取り込んだものと別の単位 (日・月・年。`YearSelector` の年は `yearStartMonth` で区切る) へ動いた描画で、**その描画のうちに**取り込みます。取り込んだ値はその描画の最初の確定から描かれ、`onChange` は発火しません。取り込みは描画が導き、保持する選択への記録はその描画の確定 (レイアウト副作用) で行います (取り込む更新は、同じ値を描く 2 回目の確定を伴います)。そのため、Suspense が保留した移行のように確定しない描画は保持する選択を変えず、その間に利用者が ◀▶・選択肢・入力で選んだ値はそのまま描かれます。隠れた `<Activity>` の中の確定は記録せず、表示したときにその描画の Props で記録します。隠れている間に `value` を渡して外した、または `initialDate` を別の単位へ動かして戻したセレクタは、表示したとき隠す前の選択を描きます。同じ単位の中の移動は、ほかの Props が変わって再描画された場合も取り込まず、利用者が ◀▶・選択肢・入力で選んだ値を置き換えません (別の単位への移動は置き換えます)。`YearSelector` は `yearStartMonth` を変えた描画でも、年の区切りが変わるため `initialDate` を取り込み直します。
|
|
1276
|
+
|
|
1255
1277
|
◀▶ は押せる間だけ、ポインターを載せると矢印の色が背景から際立ち (ライトでは濃く、ダークでは明るく) 淡い面が現れ、キーボードフォーカスで青いリングが付きます。押せる範囲は矢印を中心とする 44px 四方で、隣のセレクトボックスや日付入力の縁で止まります。境界に着いて動けない ◀▶ はフォーカスを保ち、タブ順にも残ったまま使用不可 (`aria-disabled="true"`) になり、押しても何も発行しません (キーボードで押し続けて境界に着いても、フォーカスが文書へ落ちません)。ネイティブの `disabled` が付くのは `disabled` Props でセレクタ全体を無効にしたときだけで、そのときは全てのバリアントで ◀▶ の両方がセレクトや日付入力と共にタブ順から外れます。
|
|
1256
1278
|
|
|
1257
1279
|
> [!NOTE]
|
|
@@ -1305,7 +1327,7 @@ export function SelectorsExample() {
|
|
|
1305
1327
|
| プロパティ | 型 | 既定値 | 説明 |
|
|
1306
1328
|
| :--- | :--- | :--- | :--- |
|
|
1307
1329
|
| `value` | `Date` | `undefined` | 制御時の選択日付 (年のみ使用)。`initialDate` 未指定時は必須 |
|
|
1308
|
-
| `initialDate` | `Date` | `undefined` | 非制御時の初期選択日付 (年のみ使用)。`value` 未指定時は必須。`value`
|
|
1330
|
+
| `initialDate` | `Date` | `undefined` | 非制御時の初期選択日付 (年のみ使用)。`value` 未指定時は必須。`value` 指定時は無視。別の年へ動かした描画と `yearStartMonth` を変えた描画のうちに取り込み、同じ年の中の移動では利用者の選択を置き換えない |
|
|
1309
1331
|
| `minYear` | `number` | `undefined` | 選択可能な最小年。`minDate` と併用時は厳しい方 (遅い方) を採用 |
|
|
1310
1332
|
| `maxYear` | `number` | `undefined` | 選択可能な最大年。`maxDate` と併用時は厳しい方 (早い方) を採用 |
|
|
1311
1333
|
| `minDate` | `Date` | `undefined` | 選択可能な最小日付 (年のみ使用)。`minYear` と併用時は厳しい方を採用 |
|
|
@@ -1320,7 +1342,7 @@ export function SelectorsExample() {
|
|
|
1320
1342
|
| `labels` | `PeriodSliderLabelOverrides` | `undefined` | カタログへのキー単位の上書き。読むのは `previousYear` / `nextYear` / `yearSelect` |
|
|
1321
1343
|
| `formatLocale` | `string` | `undefined` | 選択肢テキストのロケール (BCP 47 言語タグ)。未指定は 4 桁ゼロ埋めの年、指定時は `Intl.DateTimeFormat` 書式。空文字列・不正タグ・非文字列は `RangeError` |
|
|
1322
1344
|
| `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`。参照比較で再描画を判定するため、利用側でメモ化する |
|
|
1345
|
+
| `allowedYears` | `Date[]` | `undefined` | 離散の選択可能年。各要素は「その日付を含む年」(`yearStartMonth` 準拠) として読み、重複は畳み、境界の外の要素は落とします。指定すると連続範囲を置き換えるため、候補の無い年は選択肢からもステッパーの行き先からも外れます。指定時は境界必須の条件も満たします (`MonthSelector` の `allowedMonths` / `DateSelector` の `allowedDates` と同じ扱い)。`[]` は「選択可能年なし」を意味し、要素の Invalid Date は添字付きの `RangeError`、配列でない指定値 (`null`・文字列を含む) は一覧そのものを名指す `RangeError`。参照比較で再描画を判定するため、利用側でメモ化する |
|
|
1324
1346
|
| `unit` | — | — | **このコンポーネントが宣言していない名前です**。フックの `SelectorProps` をそのままスプレッドできるよう、受け取っても読まれず捨てられます (コンポーネントは必要な Props だけを名前で取り出すため、DOM へも届きません)。型にも宣言が無いので、JSX へ直接書くとコンパイルエラーになります (スプレッドは余剰プロパティ検査を受けないため通ります) |
|
|
1325
1347
|
| `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
1348
|
|
|
@@ -1339,9 +1361,9 @@ DOM 契約: 保持年が集合外の間、ルート要素に `data-out-of-range=
|
|
|
1339
1361
|
| プロパティ | 型 | 既定値 | 説明 |
|
|
1340
1362
|
| :--- | :--- | :--- | :--- |
|
|
1341
1363
|
| `value` | `Date` | `undefined` | 制御時の選択日付 (年月のみ使用)。`initialDate` 未指定時は必須 |
|
|
1342
|
-
| `initialDate` | `Date` | `undefined` | 非制御時の初期選択日付 (年月のみ使用)。`value` 未指定時は必須。`value`
|
|
1364
|
+
| `initialDate` | `Date` | `undefined` | 非制御時の初期選択日付 (年月のみ使用)。`value` 未指定時は必須。`value` 指定時は無視。別の月へ動かした描画のうちに取り込み、同じ月の中の移動では利用者の選択を置き換えない |
|
|
1343
1365
|
| `variant` | `"date" \| "dropdown"` | `"date"` | `"date"`: `<input type="month">`、`"dropdown"`: `YYYY-MM` の `<select>` |
|
|
1344
|
-
| `allowedMonths` | `Date[]` | `undefined` | 選択可能な離散月配列。各要素は月頭に切り捨てられ (日の部分は無視)
|
|
1366
|
+
| `allowedMonths` | `Date[]` | `undefined` | 選択可能な離散月配列。各要素は月頭に切り捨てられ (日の部分は無視)、月単位で重複排除・境界で絞り込まれる。空配列は「選択可能月なし」を意味し、配列でない指定値 (`null`・文字列を含む) は一覧そのものを名指す `RangeError`。参照比較で再描画を判定するため、利用側でメモ化する |
|
|
1345
1367
|
| `minYear` | `number` | `undefined` | 選択可能な最小年 (その年の 1 月)。`minDate` と併用時は厳しい方を採用 |
|
|
1346
1368
|
| `maxYear` | `number` | `undefined` | 選択可能な最大年 (その年の 12 月)。`maxDate` と併用時は厳しい方を採用 |
|
|
1347
1369
|
| `minDate` | `Date` | `undefined` | 選択可能な最小日付 (月頭に切り捨て)。`minYear` と併用時は厳しい方を採用 |
|
|
@@ -1386,9 +1408,9 @@ const allowedMonths = useMemo(() => baseMonths.map((yyyymm) => new Date(Math.tru
|
|
|
1386
1408
|
| プロパティ | 型 | 既定値 | 説明 |
|
|
1387
1409
|
| :--- | :--- | :--- | :--- |
|
|
1388
1410
|
| `value` | `Date` | `undefined` | 制御時の選択日付 (日単位に正規化)。`initialDate` 未指定時は必須。`initialDate` 指定時も `value` が優先 |
|
|
1389
|
-
| `initialDate` | `Date` | `undefined` | 非制御時の初期選択日付。`value` 未指定時は必須。`value`
|
|
1411
|
+
| `initialDate` | `Date` | `undefined` | 非制御時の初期選択日付。`value` 未指定時は必須。`value` 指定時は無視。別の日へ動かした描画のうちに取り込み、同じ日の中の移動では利用者の選択を置き換えない |
|
|
1390
1412
|
| `variant` | `"date" \| "dropdown" \| "split-dropdown"` | `"date"` | `"date"`: `<input type="date">`、`"dropdown"`: 日単位の全選択肢を仮想化した `role="combobox"` (行は `YYYY-MM-DD`、定義域の広さに費用が比例しない)、`"split-dropdown"`: 年・月・日の 3 分割 `<select>` |
|
|
1391
|
-
| `allowedDates` | `Date[]` | `undefined` |
|
|
1413
|
+
| `allowedDates` | `Date[]` | `undefined` | 選択可能な離散日付配列。空配列は「選択可能日なし」を意味し、配列でない指定値 (`null` を含む) は Props 名を名乗る `RangeError`。境界で絞り込み・日単位で重複排除される |
|
|
1392
1414
|
| `minYear` | `number` | `undefined` | 選択可能な最小年 (その年の 1 月 1 日)。`minDate` と併用時は厳しい方を採用 |
|
|
1393
1415
|
| `maxYear` | `number` | `undefined` | 選択可能な最大年 (その年の 12 月 31 日)。`maxDate` と併用時は厳しい方を採用 |
|
|
1394
1416
|
| `minDate` | `Date` | `undefined` | 選択可能な最小日付。`minYear` と併用時は厳しい方を採用 |
|
|
@@ -1410,7 +1432,7 @@ const allowedMonths = useMemo(() => baseMonths.map((yyyymm) => new Date(Math.tru
|
|
|
1410
1432
|
|
|
1411
1433
|
- `value` (制御) と `initialDate` (非制御) はいずれか一方が必須です。共に省略した場合は `RangeError` を送出し、選択日付を壁時計時刻から推定しません。
|
|
1412
1434
|
- `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`
|
|
1435
|
+
- `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` を取り込むため、どちらも送出しません。隠れた `<Activity>` の中で `value` を渡して外した場合は取り込みが記録されず、表示したときに隠す前の選択を描くため、その選択の年の始まりが表現範囲の外なら送出します。分割セレクトに保持させる日は `value` で制御してください。上限より後の保持年・保持月を暦の終わりまで埋める月と日の一覧は、Date の表現範囲の端 (275760 年 9 月と、その月の表現できる最後のローカル暦日) で終わります。
|
|
1414
1436
|
|
|
1415
1437
|
> **既知の制約 (非グレゴリオ暦)**: グレゴリオ暦の年・月を、年や月の境界が異なる暦 (和暦・ペルシア暦など) で描く以上、「その選択肢が確定する日付の呼び名」と「同じ `<select>` の選択肢どうしが区別できること」は同時には満たせません。本パッケージは**区別できること**を採ります。そのため `ja-JP-u-ca-japanese` では 2019 年の選択肢は常に 平成31年 (1 月 1 日の元号) で、5 月を保持したまま押すと確定するのは令和元年の日付です。逆に保持日を基準日へ混ぜると、`fa-IR` では 2020 年と 2021 年の選択肢が同じペルシア年 (`۱۳۹۹`) になります (実測)。確定日の呼び名が要る利用側は `formatOption` で自分の基準日を組んでください。
|
|
1416
1438
|
|
|
@@ -1428,6 +1450,7 @@ DOM 契約: ルート要素は `data-variant="date|dropdown|split-dropdown"` を
|
|
|
1428
1450
|
- ポップアップには `role="listbox"` のほかに `@aiquants/virtualscroll` のスクロールバーが同居します (`role="scrollbar"`、つまみの `role="slider"`、そして `aria-label` を持つ矢印ボタン 2 つ)。矢印ボタンは常に `disabled` でタブ順にもキーボード操作にも現れませんが、アクセシビリティツリーには残ります。その名前は `locale` のカタログの `scrollUp` / `scrollDown` (`Scroll up` / `Scroll down`、`ja` では `上へスクロール` / `下へスクロール`) で、`labels` の同じキーで上書きできます (本パッケージが内蔵 VirtualScroll へ `locale` とエンジン 7 キーを転送します)。ポップアップに絞った `getByRole("button")` はこの 2 つに当たるため、行は `role="option"` か `data-testid` で引いてください。
|
|
1429
1451
|
- キーボード: `ArrowDown` / `ArrowUp` (閉じていれば開く、開いていれば 1 行移動)、`Home` / `End` (先頭 = 最新日 / 末尾 = 最古日)、`PageDown` / `PageUp` (1 窓 = 7 行)、`Enter` (閉じていれば開く、開いていればアクティブ行を確定)、`Escape` (閉じる・発火しない)、`Tab` (閉じる)、数字と `-` / `/` / `.` (先頭一致入力。**表示書式に関わらず**先発グレゴリオ暦の `yyyy` / `yyyyMM` / `yyyyMMdd` として解釈し、走査せずに当該日へ飛ぶ。`formatOption` が非数字のテキストを返していても変わらない)。行の押下でも DOM フォーカスは操作要素から離れません。
|
|
1430
1452
|
- 閉じる契機: 行の確定、`Escape`、`Tab`、操作要素からのフォーカス喪失、ポップアップ外の `pointerdown`。
|
|
1453
|
+
- `startTransition` で渡した境界・`allowedDates`・`formatLocale`・`formatOption` は、その描画が確定するまでポップアップに使われません。一覧の行 (スクロールで描き足す行も)・先頭一致入力・行の押下は、画面に描かれている一覧を読みます。開いたまま件数が縮み、アクティブ行が一覧の外に出るときは、件数を縮めた描画のうちに末尾の行へ移り、件数が戻っても移った行に留まります。開いている間に配置だけが変わる描画 (ページのスクロール・リサイズへの追従) は、描かれている行を描き直しません (`formatOption` を呼ぶのは新しく描く行だけです)。
|
|
1431
1454
|
- ポップアップは `.period-slider` の外に立つため、`colorScheme` の変数 (`--aqps-*`) は届きません。選択中の行のアクセント色はパッケージ既定の色です。重なり順だけは `--aqps-z-date-popup` (既定 60) で差し替えられます。
|
|
1432
1455
|
- ダークモードは `.dark` の位置に依存しません。ポップアップの祖先 (`document.body` の側) に `.dark` が無くても、**操作要素自身の位置**で解決したモードを `data-color-mode` として運ぶため、`.dark` を部分木へ限定したホストでも暗色で開きます。
|
|
1433
1456
|
|
|
@@ -1469,7 +1492,7 @@ export interface ResolveSelectorStepsOptions {
|
|
|
1469
1492
|
readonly selection: readonly [Date, Date] // [開始, 終了]。時点は [値, 値]
|
|
1470
1493
|
readonly shows: "start" | "end" // 押されたセレクタが示している端 (single はここから動く)
|
|
1471
1494
|
readonly unit: PeriodSliderUnit // 選択と集合を読む解像度
|
|
1472
|
-
readonly stepUnit?: PeriodSliderUnit // 1 歩の大きさ (既定: unit)。unit そのもの、または unit が "month" のときの "year"
|
|
1495
|
+
readonly stepUnit?: PeriodSliderUnit // 1 歩の大きさ (既定: unit。省略したときだけで、null は RangeError)。unit そのもの、または unit が "month" のときの "year"
|
|
1473
1496
|
readonly yearStartMonth?: number // unit が "year" のときの 1 年の開始月 (既定: 0)
|
|
1474
1497
|
readonly minDate?: Date // 省略した側は無制限
|
|
1475
1498
|
readonly maxDate?: Date
|
|
@@ -1573,8 +1596,8 @@ export declare const useSelectorStepper: <T extends object>(
|
|
|
1573
1596
|
```
|
|
1574
1597
|
|
|
1575
1598
|
- 行き先から `stepper` を作るフックです。押せるかどうかはこの描画の行き先で決まります (行き先が `null` でない向きだけ押せる)。行き先はオブジェクトか `null` で、`undefined` を返し得る出所 (`Map.get` など) は型が拒みます (欠落を押せる・押せないのどちらへも黙って読み替えないため)。
|
|
1576
|
-
- `onStep`
|
|
1577
|
-
-
|
|
1599
|
+
- `onStep` は最後に確定した描画の行き先と `onStepTo` を参照で読むため、所有者が行き先とコールバックを描画ごとに作り直しても同じ関数です。押せるかどうかが変わらない限り同じオブジェクトを返すので、セレクタのメモ比較は描画を省きます。確定しない描画 (Suspense で中断した移行など) が作った行き先とコールバックは使いません。
|
|
1600
|
+
- 最後の確定の後に行き先が消えた向きの押下は何もしません。
|
|
1578
1601
|
|
|
1579
1602
|
#### フックへ規則を渡す
|
|
1580
1603
|
|
|
@@ -1643,8 +1666,8 @@ const { sliderProps, macroStartSelectorProps, macroEndSelectorProps, microStartS
|
|
|
1643
1666
|
| フック・行 | 候補を載せる間 | 載せる候補 |
|
|
1644
1667
|
| :--- | :--- | :--- |
|
|
1645
1668
|
| `usePeriodSliderRange` / `usePeriodSliderPoint` | `allowedDates` が空でない間 | `allowedDates` (範囲フックでは 2 つのセレクタが同じ配列を読む) |
|
|
1646
|
-
| ノギスのマクロ行 | `macroIsDiscrete` の間 | `macroAllowedDates` (
|
|
1647
|
-
| ノギスのミクロ行 | `microIsDiscrete` かつ現在の窓が候補を含む間 | 現在の窓が含む `microAllowedDates` (
|
|
1669
|
+
| ノギスのマクロ行 | `macroIsDiscrete` が `true` の間 | `macroAllowedDates` (省略 (`undefined`) なら `allowedDates`) |
|
|
1670
|
+
| ノギスのミクロ行 | `microIsDiscrete` が `true` かつ現在の窓が候補を含む間 | 現在の窓が含む `microAllowedDates` (省略 (`undefined`) なら `allowedDates`) |
|
|
1648
1671
|
|
|
1649
1672
|
- レールが連続の間 (候補を含まない窓のミクロ行を含む) はキーそのものを載せないため、スプレッドより前に書いた `allowedMonths` などを上書きしません。スプレッドの後ろに書いた値はフックの候補より優先されます。
|
|
1650
1673
|
- 候補の一覧は、フックが境界の時刻と宣言された配列の参照でメモ化します。境界へ描画ごとに値の等しい新しい `Date` を渡しても一覧は同じ参照のままで、セレクタの描画は省かれます。宣言する配列 (`allowedDates` など) は利用側でメモ化してください。
|
|
@@ -1657,18 +1680,26 @@ const { sliderProps, startSelectorProps } = usePeriodSliderRange({ unit: "day",
|
|
|
1657
1680
|
<DateSelector variant="split-dropdown" {...startSelectorProps} allowedDates={undefined} /> // 分割セレクトは候補を外して使う
|
|
1658
1681
|
```
|
|
1659
1682
|
|
|
1660
|
-
**`usePeriodSliderRange` / `usePeriodSliderPoint` はレールが描く値だけを保持・通知します**。確定する値 (設定関数・セレクタの `onChange`・`sliderProps` のコールバック・`resetRange` / `resetValue`)
|
|
1683
|
+
**`usePeriodSliderRange` / `usePeriodSliderPoint` はレールが描く値だけを保持・通知します**。確定する値 (設定関数・セレクタの `onChange`・`sliderProps` のコールバック・`resetRange` / `resetValue`) と、境界や候補が動いたときの収め直しは、レールが離散の間は最近傍の候補へ寄せたうえで `[minDate, maxDate]` へ収めます (連続の間は `[minDate, maxDate]` へ収めるだけです)。
|
|
1661
1684
|
|
|
1662
1685
|
- 候補と同じ単位の中の値 (月の候補 `2024-01-01` に対する `2024-01-15`) は、その候補として描かれるため渡されたまま残ります。
|
|
1663
1686
|
- 単位で定義域に入る候補は生の時刻では境界の外に居られるため (月の途中を指す `minDate` と月初の候補)、寄せた後も時刻で境界へ収めます。期間の両端が同じ候補へ寄って生の時刻で逆転するときは、上限を下限へ揃えます。利用側が `setRange` や `sliderProps.onChangeRange` へ逆転した期間を渡したときは揃えず、`RangeError` です。
|
|
1664
|
-
- 候補の上にない `initialRange` / `initialValue`
|
|
1665
|
-
-
|
|
1687
|
+
- 候補の上にない `initialRange` / `initialValue` は拒まず、同じ規則でレールへ置いた値でステートを始め、最初の確定から置いた値を描きます (マウントの確定は 1 回です)。初期値を境界と照らすのはマウント時だけです。マウント時に渡した初期値だけが `resetRange` / `resetValue` の行き先になり (後から変えた `initialRange` / `initialValue` は有効性と逆転だけを検証し、採用しません)、リセットもいまの定義域へ収めて確定します。境界が初期値を越えて動いても送出せず、ステートを収め直します。
|
|
1688
|
+
- 収め直しは描画が描き、ステートへの記録はその描画の確定 (レイアウト副作用) で行います。描画中にステートを書くと、確定しない描画 (Suspense が保留した移行) が求めた値を React がキューに残し、その値と同じオブジェクトの受け渡しが描画を起こさずに捨てられるためです。収め直す更新は、同じ値を描く 2 回目の確定を伴います。ノギスのフック (`useVernierSliderRange` / `useVernierSliderPoint`) のマクロ窓とミクロ選択の収め直しも同じで、ノギスのフックは離散のミクロレールに載らない初期値を最初の確定で記録するため、そのマウントは確定が 2 回になります。隠れた `<Activity>` の中の確定は記録せず、表示したときにその描画の Props で記録します (隠れている間に境界を狭めて戻したフックは、畳む前の値を描きます)。
|
|
1689
|
+
- `onChangeRange` / `onChangePoint` は、確定した値が**利用側の知っている値** (渡した初期値・`setRange` / `setValue` で自分で書いた値・最後に通知した値) と異なるときに鳴ります。ノギスの通知 (`onChangeMacroRange` / `onChangeMicroRange` / `onChangeMicroPoint`。知っている値は `setMacroRange` / `setMicroRange` / `setMicroValue` で書いた値も含む) も同じ規則です。収め直しはその場では通知しませんが、次にその値へ落ち着いた操作で通知されます (マウントで寄せた初期値も同じ)。反対に、収め直しの後で利用側の知っている値へ戻る操作は鳴りません。現在の値はコールバックではなく、フックの `range` / `value` で読めます。
|
|
1690
|
+
|
|
1691
|
+
**フックの返す関数は、画面に描かれている描画 (最後に確定した描画) の値を読みます**。4 つのフックの設定関数・シフト・リセット・`sliderProps` のコールバック・セレクタの ◀▶ は、最後に確定した描画の境界・候補・コールバック・ステートを読みます。
|
|
1692
|
+
|
|
1693
|
+
- `startTransition` で渡した新しいオプションは、その描画が確定するまで使われません。確定していない描画が渡したコールバックは呼ばれません。関数の同一性は変わりません。
|
|
1694
|
+
- 子孫のレイアウト副作用から呼んでも、隠れた `Activity` の中でも、その確定の値を読みます。
|
|
1695
|
+
- 確定経路は、返す関数が最後にステートへ渡した値と同じ値を、それがステートの最後の更新だと分かっている間は渡さず、それ以外は同じ値でもステートへ渡します。そのため `startTransition` の中で呼んだ設定関数が中断している間に別の操作をしても、保存される値は最後に通知した値 (または `setRange` などで書いた値) と一致します。その間に境界・候補・窓が動いて確定済みの値を収め直しても、収め直しの記録は中断している値を上書きしません。中断している値と同じ値を緊急に呼び直しても、その間にホストが描き直されていなければその値を緊急の優先度へ引き上げず (代替表示を出さず)、更新の後に同じ値で呼び直してもホストは描き直されません。
|
|
1696
|
+
- 描画中に呼ぶと、描画中の値ではなく最後に確定した描画の値を読みます (同じ描画で広げた `maxDate` ではなく、前の確定の `maxDate` で収めます)。フック自身の値と比べて描画のたびに呼ぶ追従は、値が境界・候補・窓へ置き直される場合も、置き直した値で落ち着きます。同じ描画の値で収めるには、副作用 (`useEffect` / `useLayoutEffect`) かイベントハンドラの中で呼んでください。
|
|
1666
1697
|
|
|
1667
1698
|
#### `usePeriodSliderRange(options)`
|
|
1668
1699
|
|
|
1669
1700
|
| オプション | 型 | 既定値 | 説明 |
|
|
1670
1701
|
| :--- | :--- | :--- | :--- |
|
|
1671
|
-
| `unit` | `PeriodSliderUnit` | (必須) |
|
|
1702
|
+
| `unit` | `PeriodSliderUnit` | (必須) | 時間解像度単位。`"year"` / `"month"` / `"day"` 以外 (`null` を含む) は `RangeError` |
|
|
1672
1703
|
| `yearStartMonth` | `number` | `0` | `unit="year"` の 1 年が始まる暦月 (0 始まり)。`sliderProps` と `SelectorProps` の双方へ転送されるだけでなく、フック自身の境界判定・離散候補の解決にも使われます。`0`〜`11` の整数以外は `RangeError` |
|
|
1673
1704
|
| `minDate` | `Date` | (必須) | 選択可能最小日付 |
|
|
1674
1705
|
| `maxDate` | `Date` | (必須) | 選択可能最大日付 (`minDate` より厳密に後) |
|
|
@@ -1682,10 +1713,10 @@ const { sliderProps, startSelectorProps } = usePeriodSliderRange({ unit: "day",
|
|
|
1682
1713
|
| `range` | `[Date, Date]` | 現在の選択期間タプル |
|
|
1683
1714
|
| `lowerDate` | `Date` | 現在の選択下限日付 (`range[0]`) |
|
|
1684
1715
|
| `upperDate` | `Date` | 現在の選択上限日付 (`range[1]`) |
|
|
1685
|
-
| `setRange` | `React.Dispatch<React.SetStateAction<[Date, Date]>>` | 期間の直接更新関数 (
|
|
1716
|
+
| `setRange` | `React.Dispatch<React.SetStateAction<[Date, Date]>>` | 期間の直接更新関数 (コールバックは発火しない。レールに載らない期間は描画で置き直し、記録はその確定で行う) |
|
|
1686
1717
|
| `setLowerDate` | `(date: Date) => void` | 下限更新関数。上限を超えた場合は上限も追従し、離散レールでは最近傍の候補へ寄せる。`onChangeRange` を発火する |
|
|
1687
1718
|
| `setUpperDate` | `(date: Date) => void` | 上限更新関数。下限を下回った場合は下限も追従し、離散レールでは最近傍の候補へ寄せる。`onChangeRange` を発火する |
|
|
1688
|
-
| `shiftRange` | `(delta: number) => void` | 両端を `delta` 単位シフトし、それぞれ境界へクランプ (境界に達した側は期間幅が縮む) |
|
|
1719
|
+
| `shiftRange` | `(delta: number) => void` | 両端を `delta` 単位シフトし、それぞれ境界へクランプ (境界に達した側は期間幅が縮む)。和が Date の表現範囲を越える端も、境界を越えたほかの端と同じく進む向きの境界で止まる |
|
|
1689
1720
|
| `resetRange` | `() => void` | `initialRange` へ復帰 (いまの定義域へ収め、離散レールでは最近傍の候補へ寄せた期間) |
|
|
1690
1721
|
| `startSelectorProps` | `SelectorProps` | 開始側セレクタ用 Props (`maxDate` は現在の上限日付) |
|
|
1691
1722
|
| `endSelectorProps` | `SelectorProps` | 終了側セレクタ用 Props (`minDate` は現在の下限日付) |
|
|
@@ -1695,7 +1726,7 @@ const { sliderProps, startSelectorProps } = usePeriodSliderRange({ unit: "day",
|
|
|
1695
1726
|
|
|
1696
1727
|
| オプション | 型 | 既定値 | 説明 |
|
|
1697
1728
|
| :--- | :--- | :--- | :--- |
|
|
1698
|
-
| `unit` | `PeriodSliderUnit` | (必須) |
|
|
1729
|
+
| `unit` | `PeriodSliderUnit` | (必須) | 時間解像度単位。`"year"` / `"month"` / `"day"` 以外 (`null` を含む) は `RangeError` |
|
|
1699
1730
|
| `yearStartMonth` | `number` | `0` | `unit="year"` の 1 年が始まる暦月 (0 始まり)。`sliderProps` と `SelectorProps` の双方へ転送されるだけでなく、フック自身の境界判定・離散候補の解決にも使われます。`0`〜`11` の整数以外は `RangeError` |
|
|
1700
1731
|
| `minDate` | `Date` | (必須) | 選択可能最小日付 |
|
|
1701
1732
|
| `maxDate` | `Date` | (必須) | 選択可能最大日付 (`minDate` より厳密に後) |
|
|
@@ -1706,8 +1737,8 @@ const { sliderProps, startSelectorProps } = usePeriodSliderRange({ unit: "day",
|
|
|
1706
1737
|
| 返却値 | 型 | 説明 |
|
|
1707
1738
|
| :--- | :--- | :--- |
|
|
1708
1739
|
| `value` | `Date` | 現在の選択日付 |
|
|
1709
|
-
| `setValue` | `React.Dispatch<React.SetStateAction<Date>>` | 日付の直接更新関数 (
|
|
1710
|
-
| `shiftValue` | `(delta: number) => void` | 日付を `delta`
|
|
1740
|
+
| `setValue` | `React.Dispatch<React.SetStateAction<Date>>` | 日付の直接更新関数 (コールバックは発火しない。レールに載らない日付は描画で置き直し、記録はその確定で行う) |
|
|
1741
|
+
| `shiftValue` | `(delta: number) => void` | 日付を `delta` 単位シフトし、境界へクランプ。和が Date の表現範囲を越える場合も、境界を越えたほかの和と同じく進む向きの境界で止まる |
|
|
1711
1742
|
| `resetValue` | `() => void` | `initialValue` へ復帰 (いまの定義域へ収め、離散レールでは最近傍の候補へ寄せた日付) |
|
|
1712
1743
|
| `selectorProps` | `SelectorProps` | セレクタ用 Props |
|
|
1713
1744
|
| `sliderProps` | `PeriodSliderPointProps` | `<PeriodSlider {...sliderProps} />` へ渡す Props |
|
|
@@ -1716,16 +1747,16 @@ const { sliderProps, startSelectorProps } = usePeriodSliderRange({ unit: "day",
|
|
|
1716
1747
|
|
|
1717
1748
|
| オプション | 型 | 既定値 | 説明 |
|
|
1718
1749
|
| :--- | :--- | :--- | :--- |
|
|
1719
|
-
| `unit` | `PeriodSliderUnit` | (必須) |
|
|
1750
|
+
| `unit` | `PeriodSliderUnit` | (必須) | 基本時間解像度単位。`"year"` / `"month"` / `"day"` 以外 (`null` を含む) は `RangeError` |
|
|
1720
1751
|
| `yearStartMonth` | `number` | `0` | `macroUnit` / `microUnit` が `"year"` のときの 1 年が始まる暦月 (0 始まり)。`sliderProps` と 4 つの `SelectorProps` へ転送されるだけでなく、マクロ窓の解決 (`resolveMacroWindow`)・境界判定・離散候補の解決にも使われます。`0`〜`11` の整数以外は `RangeError` |
|
|
1721
1752
|
| `minDate` | `Date` | (必須) | 全期間マクロの下限日付 |
|
|
1722
1753
|
| `maxDate` | `Date` | (必須) | 全期間マクロの上限日付 (`minDate` より厳密に後) |
|
|
1723
1754
|
| `initialMacroRange` | `[Date, Date]` | (必須) | 初期マクロ表示窓 [開始, 終了] |
|
|
1724
1755
|
| `initialMicroRange` | `[Date, Date]` | (必須) | 初期ミクロ選択期間 [開始, 終了] (初期マクロ窓と `[minDate, maxDate]` の交差の内側) |
|
|
1725
|
-
| `macroUnit` | `PeriodSliderUnit` | `unit` |
|
|
1726
|
-
| `microUnit` | `PeriodSliderUnit` | `unit` |
|
|
1756
|
+
| `macroUnit` | `PeriodSliderUnit` | `unit` | マクロ側時間解像度単位。既定の `unit` は省略 (`undefined`) のときだけ。`null` を含む宣言外の値は `RangeError` |
|
|
1757
|
+
| `microUnit` | `PeriodSliderUnit` | `unit` | ミクロ側時間解像度単位。既定の `unit` は省略 (`undefined`) のときだけ。`null` を含む宣言外の値は `RangeError` |
|
|
1727
1758
|
| `onChangeMacroRange` | `(lower: Date, upper: Date) => void` | `undefined` | マクロ窓変更時コールバック。確定した窓が利用側の知っている窓 (初期値・`setMacroRange` で書いた値・最後に通知した値) と異なるときに鳴る |
|
|
1728
|
-
| `onChangeMicroRange` | `(lower: Date, upper: Date) => void` | `undefined` | ミクロ選択期間変更時コールバック。利用側の知っている値 (初期値・`setMicroRange` で書いた値・最後に通知した値)
|
|
1759
|
+
| `onChangeMicroRange` | `(lower: Date, upper: Date) => void` | `undefined` | ミクロ選択期間変更時コールバック。利用側の知っている値 (初期値・`setMicroRange` で書いた値・最後に通知した値) と異なるときに鳴るため、収め直された値も、次に確定した操作の値がステートと同じであれ必ず届く |
|
|
1729
1760
|
| `macroSelectorStep` | `SelectorStepRules` | `undefined` | 2 つのマクロセレクタの ◀▶ がマクロ窓をどう動かすか (向きごと)。窓は `resolveVernierSelectorSteps` (`row: "macro"`) で動き、ミクロ選択を運ぶか切り落とす。省略時は各セレクタが自分の端を動かす |
|
|
1730
1761
|
| `microSelectorStep` | `SelectorStepRules<VernierRangeStepRule>` | `undefined` | 2 つのミクロセレクタの ◀▶ がミクロ選択とマクロ窓をどう動かすか (向きごと)。選択は定義域全体の上を `resolveVernierSelectorSteps` (`row: "micro"`) で動き、窓を据え置くか追従させるかは `window` (既定 `"keep"`) が決める。省略時は各セレクタが自分の端を動かす |
|
|
1731
1762
|
| その他 | — | — | 上記および `mode` / `macroRange` / `microRange` / `defaultMicroRange` を除く `PeriodSlider` の Vernier モード Props をすべて受け取り、`sliderProps` へそのまま転送 |
|
|
@@ -1740,8 +1771,8 @@ const { sliderProps, startSelectorProps } = usePeriodSliderRange({ unit: "day",
|
|
|
1740
1771
|
| `setMacroUpperDate` | `(date: Date) => void` | マクロ終了日更新関数。`maxDate` より後は `maxDate` へ収め、マクロ下限を下回った場合は下限も追従 |
|
|
1741
1772
|
| `setMicroLowerDate` | `(date: Date) => void` | ミクロ開始日更新関数。マクロ窓の下限より前は窓下限へ収め、ミクロ上限を超えた場合は上限も追従 |
|
|
1742
1773
|
| `setMicroUpperDate` | `(date: Date) => void` | ミクロ終了日更新関数。マクロ窓の上限より後は窓上限へ収め、ミクロ下限を下回った場合は下限も追従 |
|
|
1743
|
-
| `shiftMacroRange` | `(delta: number) => void` | マクロ窓を `delta` マクロ単位シフト。窓幅を保つため、片側でも `[minDate, maxDate]`
|
|
1744
|
-
| `shiftMicroRange` | `(delta: number) => void` | ミクロ選択期間を `delta` ミクロ単位シフト。実効マクロ窓 (マクロ窓と `[minDate, maxDate]` の交差)
|
|
1774
|
+
| `shiftMacroRange` | `(delta: number) => void` | マクロ窓を `delta` マクロ単位シフト。窓幅を保つため、片側でも `[minDate, maxDate]` を越えるシフト (和が Date の表現範囲を越える端を含む) は全体を中止する (クランプしない)。`macroIsDiscrete={true}` のときはスライダー本体と同じ候補集合 (`macroAllowedDates`、未指定なら `allowedDates`) の上を `delta` 個分歩き、候補集合を外れるシフトも同じく全体中止 |
|
|
1775
|
+
| `shiftMicroRange` | `(delta: number) => void` | ミクロ選択期間を `delta` ミクロ単位シフト。実効マクロ窓 (マクロ窓と `[minDate, maxDate]` の交差) からはみ出すシフト (和が Date の表現範囲を越える端を含む) は全体を中止する (クランプしない)。`microIsDiscrete={true}` のときはスライダー本体と同じ候補集合 (`microAllowedDates`、未指定なら `allowedDates`) の上を `delta` 個分歩き、候補集合を外れるシフトも同じく全体中止。現在のマクロ窓に候補が 1 つも無い場合は連続として扱う |
|
|
1745
1776
|
| `resetVernier` | `() => void` | マクロ・ミクロ双方を初期値へ復帰 (窓はいまの定義域へ収め、ミクロ選択はその窓のレールへ置く) |
|
|
1746
1777
|
| `macroStartSelectorProps` | `SelectorProps` | マクロ開始日セレクタ用 Props |
|
|
1747
1778
|
| `macroEndSelectorProps` | `SelectorProps` | マクロ終了日セレクタ用 Props |
|
|
@@ -1755,16 +1786,16 @@ const { sliderProps, startSelectorProps } = usePeriodSliderRange({ unit: "day",
|
|
|
1755
1786
|
|
|
1756
1787
|
| オプション | 型 | 既定値 | 説明 |
|
|
1757
1788
|
| :--- | :--- | :--- | :--- |
|
|
1758
|
-
| `unit` | `PeriodSliderUnit` | (必須) |
|
|
1789
|
+
| `unit` | `PeriodSliderUnit` | (必須) | 基本時間解像度単位。`"year"` / `"month"` / `"day"` 以外 (`null` を含む) は `RangeError` |
|
|
1759
1790
|
| `yearStartMonth` | `number` | `0` | `macroUnit` / `microUnit` が `"year"` のときの 1 年が始まる暦月 (0 始まり)。`sliderProps` と 3 つの `SelectorProps` へ転送されるだけでなく、マクロ窓の解決 (`resolveMacroWindow`)・境界判定・離散候補の解決にも使われます。`0`〜`11` の整数以外は `RangeError` |
|
|
1760
1791
|
| `minDate` | `Date` | (必須) | 全期間マクロの下限日付 |
|
|
1761
1792
|
| `maxDate` | `Date` | (必須) | 全期間マクロの上限日付 (`minDate` より厳密に後) |
|
|
1762
1793
|
| `initialMacroRange` | `[Date, Date]` | (必須) | 初期マクロ表示窓 [開始, 終了] |
|
|
1763
1794
|
| `initialMicroValue` | `Date` | (必須) | 初期ミクロ選択時点 (初期マクロ窓と `[minDate, maxDate]` の交差の内側) |
|
|
1764
|
-
| `macroUnit` | `PeriodSliderUnit` | `unit` |
|
|
1765
|
-
| `microUnit` | `PeriodSliderUnit` | `unit` |
|
|
1795
|
+
| `macroUnit` | `PeriodSliderUnit` | `unit` | マクロ側時間解像度単位。既定の `unit` は省略 (`undefined`) のときだけ。`null` を含む宣言外の値は `RangeError` |
|
|
1796
|
+
| `microUnit` | `PeriodSliderUnit` | `unit` | ミクロ側時間解像度単位。既定の `unit` は省略 (`undefined`) のときだけ。`null` を含む宣言外の値は `RangeError` |
|
|
1766
1797
|
| `onChangeMacroRange` | `(lower: Date, upper: Date) => void` | `undefined` | マクロ窓変更時コールバック。確定した窓が利用側の知っている窓 (初期値・`setMacroRange` で書いた値・最後に通知した値) と異なるときに鳴る |
|
|
1767
|
-
| `onChangeMicroPoint` | `(value: Date) => void` | `undefined` | ミクロ時点変更時コールバック。利用側の知っている値 (初期値・`setMicroValue` で書いた値・最後に通知した値)
|
|
1798
|
+
| `onChangeMicroPoint` | `(value: Date) => void` | `undefined` | ミクロ時点変更時コールバック。利用側の知っている値 (初期値・`setMicroValue` で書いた値・最後に通知した値) と異なるときに鳴るため、収め直された値も、次に確定した操作の値がステートと同じであれ必ず届く |
|
|
1768
1799
|
| `macroSelectorStep` | `SelectorStepRules` | `undefined` | 2 つのマクロセレクタの ◀▶ がマクロ窓をどう動かすか (向きごと)。窓は `resolveVernierSelectorSteps` (`row: "macro"`) で動き、時点は新しい窓が描くレールへ置かれる。省略時は各セレクタが自分の端を動かす |
|
|
1769
1800
|
| `microSelectorStep` | `SelectorStepRules<VernierPointStepRule>` | `undefined` | 時点セレクタの ◀▶ がマクロ窓をどう扱うか (向きごと)。時点は定義域全体の上で隣へ進み、窓を据え置くか追従させるかは `window` (既定 `"keep"`) が決める。書けるのは `window` だけ (`motion` は `RangeError`)。省略時はセレクタが窓の中で時点を動かす |
|
|
1770
1801
|
| その他 | — | — | 上記および `mode` / `macroRange` を除く `PeriodSlider` の Vernier 共通 Props をすべて受け取り、`sliderProps` へそのまま転送 |
|
|
@@ -1778,8 +1809,8 @@ const { sliderProps, startSelectorProps } = usePeriodSliderRange({ unit: "day",
|
|
|
1778
1809
|
| `setMacroLowerDate` | `(date: Date) => void` | マクロ開始日更新関数。`minDate` より前は `minDate` へ収め、マクロ上限を超えた場合は上限も追従 |
|
|
1779
1810
|
| `setMacroUpperDate` | `(date: Date) => void` | マクロ終了日更新関数。`maxDate` より後は `maxDate` へ収め、マクロ下限を下回った場合は下限も追従 |
|
|
1780
1811
|
| `setMicroDate` | `(date: Date) => void` | ミクロ時点更新関数。マクロ窓の外はマクロ窓の境界へ収める |
|
|
1781
|
-
| `shiftMacroRange` | `(delta: number) => void` | マクロ窓を `delta` マクロ単位シフト。窓幅を保つため、片側でも `[minDate, maxDate]`
|
|
1782
|
-
| `shiftMicroValue` | `(delta: number) => void` | ミクロ時点を `delta` ミクロ単位シフトし、実効マクロ窓 (マクロ窓と `[minDate, maxDate]` の交差) へクランプする。時点には保つべき幅が無いため、`shiftMicroRange`
|
|
1812
|
+
| `shiftMacroRange` | `(delta: number) => void` | マクロ窓を `delta` マクロ単位シフト。窓幅を保つため、片側でも `[minDate, maxDate]` を越えるシフト (和が Date の表現範囲を越える端を含む) は全体を中止する (クランプしない)。`macroIsDiscrete={true}` のときはスライダー本体と同じ候補集合 (`macroAllowedDates`、未指定なら `allowedDates`) の上を `delta` 個分歩き、候補集合を外れるシフトも同じく全体中止 |
|
|
1813
|
+
| `shiftMicroValue` | `(delta: number) => void` | ミクロ時点を `delta` ミクロ単位シフトし、実効マクロ窓 (マクロ窓と `[minDate, maxDate]` の交差) へクランプする。時点には保つべき幅が無いため、`shiftMicroRange` と違い端で中止せず端へ着ける (和が Date の表現範囲を越える場合も、進む向きの窓の端へ着く)。`microIsDiscrete={true}` のときはスライダー本体と同じ候補集合 (`microAllowedDates`、未指定なら `allowedDates`) の上を `delta` 個分歩き、現在のマクロ窓に候補が 1 つも無い場合は連続スライダーと同じ 1 単位シフトへ退化する (送出しない) |
|
|
1783
1814
|
| `resetVernier` | `() => void` | マクロ窓・ミクロ時点の双方を初期値へ復帰 (窓はいまの定義域へ収め、時点はその窓のレールへ置く) |
|
|
1784
1815
|
| `macroStartSelectorProps` | `SelectorProps` | マクロ開始日セレクタ用 Props |
|
|
1785
1816
|
| `macroEndSelectorProps` | `SelectorProps` | マクロ終了日セレクタ用 Props |
|