@aiquants/period-slider 0.2.0 → 0.4.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/README.md +465 -85
- package/dist/DateSelector.d.ts +43 -14
- package/dist/DateSelector.d.ts.map +1 -1
- package/dist/MonthSelector.d.ts +26 -9
- package/dist/MonthSelector.d.ts.map +1 -1
- package/dist/PeriodSlider.d.ts +257 -125
- package/dist/PeriodSlider.d.ts.map +1 -1
- package/dist/YearSelector.d.ts +26 -9
- package/dist/YearSelector.d.ts.map +1 -1
- package/dist/index.cjs +1 -1
- package/dist/index.d.cts +28 -0
- package/dist/index.d.ts +10 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1642 -1382
- package/dist/styles/period-slider.css +1 -1
- package/dist/styles/period-slider.standalone.css +1 -1
- package/dist/usePeriodSlider.d.ts +83 -78
- package/dist/usePeriodSlider.d.ts.map +1 -1
- package/package.json +17 -10
- package/src/DateSelector.tsx +495 -194
- package/src/MonthSelector.tsx +258 -137
- package/src/PeriodSlider.tsx +1109 -572
- package/src/YearSelector.tsx +174 -55
- package/src/index.ts +13 -0
- package/src/styles/period-slider.css +41 -7
- package/src/usePeriodSlider.ts +466 -277
- package/dist/period-slider.css +0 -1
package/src/usePeriodSlider.ts
CHANGED
|
@@ -4,44 +4,220 @@
|
|
|
4
4
|
*
|
|
5
5
|
* Provides ready-to-use custom hooks that eliminate boilerplate state management
|
|
6
6
|
* for Range, Point, and Vernier dual-scale PeriodSlider components.
|
|
7
|
+
* Every hook takes exactly one canonical option per concept and fails fast with a
|
|
8
|
+
* RangeError when a required boundary or initial date is missing, invalid, inverted or
|
|
9
|
+
* outside the domain it declares. Committed state is always kept inside
|
|
10
|
+
* [minDate, maxDate] - and, for the Vernier micro range, inside the current macro window.
|
|
7
11
|
*
|
|
8
12
|
* レンジ・ポイント・ノギス型 2 段スケール PeriodSlider のステート管理ボイラープレートを
|
|
9
|
-
* 最小化する標準 React
|
|
13
|
+
* 最小化する標準 React カスタムフック群を提供します。各概念につき正準オプションは 1 つのみで、
|
|
14
|
+
* 必須の境界日付・初期日付が欠落・不正・逆転・定義域外の場合は RangeError で即時失敗します。
|
|
15
|
+
* 確定済みステートは常に [minDate, maxDate] の内側 (ノギスのミクロ選択は現在のマクロ窓の内側) に保たれます。
|
|
10
16
|
*/
|
|
11
17
|
|
|
12
18
|
import type React from "react"
|
|
13
19
|
import { useCallback, useMemo, useRef, useState } from "react"
|
|
14
|
-
import { addUnit, type PeriodSliderPointProps, type PeriodSliderRangeProps, type PeriodSliderUnit, type PeriodSliderVernierProps } from "./PeriodSlider"
|
|
20
|
+
import { addUnit, findNearestDateIndex, getMacroWindowEndDate, getSortedAllowedDates, type PeriodSliderPointProps, type PeriodSliderRangeProps, type PeriodSliderUnit, type PeriodSliderVernierProps } from "./PeriodSlider"
|
|
15
21
|
|
|
16
22
|
// ======================================================================
|
|
17
|
-
//
|
|
23
|
+
// 0. Shared Validation & Helpers
|
|
18
24
|
// ======================================================================
|
|
19
25
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
26
|
+
/**
|
|
27
|
+
* Asserts that a required date option is a usable Date instance.
|
|
28
|
+
* 必須日付オプションが有効な Date インスタンスであることの表明。
|
|
29
|
+
*
|
|
30
|
+
* @param hookName - Calling hook name used as the error prefix / エラー接頭辞となる呼び出し元フック名
|
|
31
|
+
* @param label - Option name under validation / 検証対象オプション名
|
|
32
|
+
* @param date - Value under validation / 検証対象値
|
|
33
|
+
* @returns Nothing; returns normally only for a valid Date / 返り値なし (有効な Date の場合のみ正常復帰)
|
|
34
|
+
* @throws {RangeError} When the value is not a Date instance or is an Invalid Date / Date インスタンスでない、または Invalid Date の場合
|
|
35
|
+
*/
|
|
36
|
+
function assertValidDate(hookName: string, label: string, date: Date): void {
|
|
37
|
+
if (!(date instanceof Date) || Number.isNaN(date.getTime())) {
|
|
38
|
+
throw new RangeError(`${hookName}: ${label} is required and must be a valid Date (received: ${String(date)})`)
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* Asserts that the selectable boundary pair is valid and strictly ordered.
|
|
44
|
+
* 選択可能境界ペアが有効かつ厳密に順序付けされていることの表明。
|
|
45
|
+
*
|
|
46
|
+
* @param hookName - Calling hook name used as the error prefix / エラー接頭辞となる呼び出し元フック名
|
|
47
|
+
* @param minDate - Lower boundary date / 下限日付
|
|
48
|
+
* @param maxDate - Upper boundary date / 上限日付
|
|
49
|
+
* @returns Nothing; returns normally only for a valid boundary pair / 返り値なし (有効な境界ペアの場合のみ正常復帰)
|
|
50
|
+
* @throws {RangeError} When either boundary is invalid or maxDate is not strictly later than minDate / 境界が不正、または maxDate が minDate より後でない場合
|
|
51
|
+
*/
|
|
52
|
+
function assertValidBounds(hookName: string, minDate: Date, maxDate: Date): void {
|
|
53
|
+
assertValidDate(hookName, "minDate", minDate)
|
|
54
|
+
assertValidDate(hookName, "maxDate", maxDate)
|
|
55
|
+
if (maxDate.getTime() <= minDate.getTime()) {
|
|
56
|
+
throw new RangeError(`${hookName}: maxDate must be strictly later than minDate (minDate: ${minDate.toISOString()}, maxDate: ${maxDate.toISOString()})`)
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* Asserts that a required [lower, upper] tuple holds two valid, non-inverted dates.
|
|
62
|
+
* 必須の [lower, upper] タプルが有効かつ逆転していない 2 日付を保持することの表明。
|
|
63
|
+
*
|
|
64
|
+
* @param hookName - Calling hook name used as the error prefix / エラー接頭辞となる呼び出し元フック名
|
|
65
|
+
* @param label - Option name under validation / 検証対象オプション名
|
|
66
|
+
* @param range - Tuple under validation / 検証対象タプル
|
|
67
|
+
* @returns Nothing; returns normally only for a valid tuple / 返り値なし (有効なタプルの場合のみ正常復帰)
|
|
68
|
+
* @throws {RangeError} When the value is not a two-element tuple, holds an Invalid Date, or is inverted / 2 要素タプルでない、Invalid Date を含む、または逆転している場合
|
|
69
|
+
*/
|
|
70
|
+
function assertValidRangeTuple(hookName: string, label: string, range: [Date, Date]): void {
|
|
71
|
+
if (!Array.isArray(range) || range.length !== 2) {
|
|
72
|
+
throw new RangeError(`${hookName}: ${label} is required and must be a [lower, upper] Date tuple (received: ${String(range)})`)
|
|
73
|
+
}
|
|
74
|
+
assertValidDate(hookName, `${label}[0]`, range[0])
|
|
75
|
+
assertValidDate(hookName, `${label}[1]`, range[1])
|
|
76
|
+
if (range[0].getTime() > range[1].getTime()) {
|
|
77
|
+
throw new RangeError(`${hookName}: ${label} upper must not be earlier than lower (lower: ${range[0].toISOString()}, upper: ${range[1].toISOString()})`)
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* Asserts that a required initial date lies inside the window it will be rendered in.
|
|
83
|
+
* An out-of-window initial date would make the slider report aria-valuenow outside
|
|
84
|
+
* aria-valuemin/aria-valuemax, so it is rejected instead of being silently clamped.
|
|
85
|
+
* 必須の初期日付が描画対象の窓の内側にあることの表明 (窓外は黙ってクランプせず拒否)。
|
|
86
|
+
*
|
|
87
|
+
* @param hookName - Calling hook name used as the error prefix / エラー接頭辞となる呼び出し元フック名
|
|
88
|
+
* @param label - Option name under validation / 検証対象オプション名
|
|
89
|
+
* @param date - Value under validation / 検証対象値
|
|
90
|
+
* @param lowerBound - Inclusive lower boundary of the window / 窓の下限日付 (境界含む)
|
|
91
|
+
* @param upperBound - Inclusive upper boundary of the window / 窓の上限日付 (境界含む)
|
|
92
|
+
* @param windowLabel - Human readable name of the window used in the error message / エラーメッセージ中の窓の名称
|
|
93
|
+
* @returns Nothing; returns normally only for a contained date / 返り値なし (窓内の日付の場合のみ正常復帰)
|
|
94
|
+
* @throws {RangeError} When the date lies outside [lowerBound, upperBound] / 日付が [lowerBound, upperBound] の外にある場合
|
|
95
|
+
*/
|
|
96
|
+
function assertWithinBounds(hookName: string, label: string, date: Date, lowerBound: Date, upperBound: Date, windowLabel: string): void {
|
|
97
|
+
if (date.getTime() < lowerBound.getTime() || date.getTime() > upperBound.getTime()) {
|
|
98
|
+
throw new RangeError(`${hookName}: ${label} must lie within ${windowLabel} (value: ${date.toISOString()}, lower: ${lowerBound.toISOString()}, upper: ${upperBound.toISOString()})`)
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/**
|
|
103
|
+
* Asserts that both ends of a required initial tuple lie inside the window it will be rendered in.
|
|
104
|
+
* 必須の初期タプルの両端が描画対象の窓の内側にあることの表明。
|
|
105
|
+
*
|
|
106
|
+
* @param hookName - Calling hook name used as the error prefix / エラー接頭辞となる呼び出し元フック名
|
|
107
|
+
* @param label - Option name under validation / 検証対象オプション名
|
|
108
|
+
* @param range - Tuple under validation / 検証対象タプル
|
|
109
|
+
* @param lowerBound - Inclusive lower boundary of the window / 窓の下限日付 (境界含む)
|
|
110
|
+
* @param upperBound - Inclusive upper boundary of the window / 窓の上限日付 (境界含む)
|
|
111
|
+
* @param windowLabel - Human readable name of the window used in the error message / エラーメッセージ中の窓の名称
|
|
112
|
+
* @returns Nothing; returns normally only for a fully contained tuple / 返り値なし (両端が窓内の場合のみ正常復帰)
|
|
113
|
+
* @throws {RangeError} When either end lies outside [lowerBound, upperBound] / いずれかの端が [lowerBound, upperBound] の外にある場合
|
|
114
|
+
*/
|
|
115
|
+
function assertRangeWithinBounds(hookName: string, label: string, range: [Date, Date], lowerBound: Date, upperBound: Date, windowLabel: string): void {
|
|
116
|
+
assertWithinBounds(hookName, `${label}[0]`, range[0], lowerBound, upperBound, windowLabel)
|
|
117
|
+
assertWithinBounds(hookName, `${label}[1]`, range[1], lowerBound, upperBound, windowLabel)
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/**
|
|
121
|
+
* Clamps a date into the inclusive [min, max] boundary window.
|
|
122
|
+
* 日付を [min, max] の閉区間へ収める。
|
|
123
|
+
*
|
|
124
|
+
* @param date - Date to clamp / 収める対象日付
|
|
125
|
+
* @param min - Lower boundary date / 下限日付
|
|
126
|
+
* @param max - Upper boundary date / 上限日付
|
|
127
|
+
* @returns The date itself, or the boundary it exceeded / 日付そのもの、または超過した側の境界日付
|
|
128
|
+
*/
|
|
129
|
+
function clampDate(date: Date, min: Date, max: Date): Date {
|
|
130
|
+
if (date < min) return min
|
|
131
|
+
if (date > max) return max
|
|
132
|
+
return date
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
/**
|
|
136
|
+
* Clamps both ends of a micro range into the effective macro window.
|
|
137
|
+
* The window ends at getMacroWindowEndDate so that a micro date the slider can legally
|
|
138
|
+
* reach (e.g. December 31 for a yearly macro scale) is not truncated to the raw macro end.
|
|
139
|
+
* ミクロ期間の両端を実効マクロ窓 (終端は getMacroWindowEndDate) の内側へ収める。
|
|
140
|
+
*
|
|
141
|
+
* @param range - Micro range tuple to contain / 収める対象のミクロ期間タプル
|
|
142
|
+
* @param macroUnit - Macro scale unit / マクロ側の時間解像度単位
|
|
143
|
+
* @param microUnit - Micro scale unit / ミクロ側の時間解像度単位
|
|
144
|
+
* @param macroRange - Current macro window tuple / 現在のマクロ窓タプル
|
|
145
|
+
* @returns Micro range tuple guaranteed to lie inside the macro window / マクロ窓の内側であることが保証されたミクロ期間タプル
|
|
146
|
+
*/
|
|
147
|
+
function clampRangeIntoMacroWindow(range: [Date, Date], macroUnit: PeriodSliderUnit, microUnit: PeriodSliderUnit, macroRange: [Date, Date]): [Date, Date] {
|
|
148
|
+
const windowEnd = getMacroWindowEndDate(macroUnit, microUnit, macroRange[1])
|
|
149
|
+
return [clampDate(range[0], macroRange[0], windowEnd), clampDate(range[1], macroRange[0], windowEnd)]
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
/**
|
|
153
|
+
* Steps a date through the discrete allowed set by index, clamping at both ends of the set.
|
|
154
|
+
* 離散候補集合をインデックスで歩き、集合の両端でクランプした日付を返す関数。
|
|
155
|
+
*
|
|
156
|
+
* @param sortedAllowedDates - Ascending, domain-restricted allowed dates (non-empty) / 昇順かつ定義域内に制限済みの候補日付 (空でないこと)
|
|
157
|
+
* @param unit - Time resolution unit used for the nearest-entry lookup / 最近傍探索に用いる時間解像度単位
|
|
158
|
+
* @param current - Currently selected date / 現在の選択日付
|
|
159
|
+
* @param delta - Number of positions to move through the set / 集合内で移動する位置数
|
|
160
|
+
* @returns Allowed date delta positions away, clamped to the set boundaries / delta 個先の候補日付 (集合の端でクランプ)
|
|
161
|
+
*/
|
|
162
|
+
function stepThroughAllowedDates(sortedAllowedDates: Date[], unit: PeriodSliderUnit, current: Date, delta: number): Date {
|
|
163
|
+
const nextIndex = findNearestDateIndex(sortedAllowedDates, current, unit) + delta
|
|
164
|
+
return sortedAllowedDates[Math.max(0, Math.min(sortedAllowedDates.length - 1, nextIndex))]
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
/**
|
|
168
|
+
* Keeps the previous object reference while every own key stays shallowly equal.
|
|
169
|
+
* Rest-destructured UI props are rebuilt on every render, which would make every
|
|
170
|
+
* downstream useMemo miss unconditionally; this restores their memoization contract.
|
|
171
|
+
* 浅い等価性が保たれる限り前回のオブジェクト参照を維持するフック (レスト構文で再生成される Props のメモ化回復)。
|
|
172
|
+
*
|
|
173
|
+
* @param value - Freshly allocated object to stabilise / 毎レンダー再生成されるオブジェクト
|
|
174
|
+
* @returns The previous reference when shallowly equal, otherwise the new one / 浅い等価なら前回参照、異なれば新しい参照
|
|
175
|
+
*/
|
|
176
|
+
function useShallowStable<T extends object>(value: T): T {
|
|
177
|
+
const stableRef = useRef<T>(value)
|
|
178
|
+
const previous = stableRef.current as unknown as Record<string, unknown>
|
|
179
|
+
const current = value as unknown as Record<string, unknown>
|
|
180
|
+
const previousKeys = Object.keys(previous)
|
|
181
|
+
const currentKeys = Object.keys(current)
|
|
182
|
+
const isShallowEqual = previousKeys.length === currentKeys.length && currentKeys.every((key) => Object.is(previous[key], current[key]))
|
|
183
|
+
if (!isShallowEqual) {
|
|
184
|
+
stableRef.current = value
|
|
185
|
+
}
|
|
186
|
+
return stableRef.current
|
|
37
187
|
}
|
|
38
188
|
|
|
189
|
+
/**
|
|
190
|
+
* Pre-configured props for the bundled YearSelector / MonthSelector / DateSelector components.
|
|
191
|
+
* 同梱の YearSelector・MonthSelector・DateSelector へそのまま渡せる Props。
|
|
192
|
+
*/
|
|
39
193
|
export interface SelectorProps {
|
|
194
|
+
/** Currently selected date / 現在の選択日付 */
|
|
40
195
|
value: Date
|
|
196
|
+
/** Selection handler wired to the owning hook state / フックのステートへ連動する選択ハンドラ */
|
|
41
197
|
onChange: (date: Date) => void
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
198
|
+
/** Lower boundary date for the selector / セレクタの下限日付 */
|
|
199
|
+
minDate: Date
|
|
200
|
+
/** Upper boundary date for the selector / セレクタの上限日付 */
|
|
201
|
+
maxDate: Date
|
|
202
|
+
/** Time resolution unit of the selector / セレクタの時間解像度単位 */
|
|
203
|
+
unit: PeriodSliderUnit
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
// ======================================================================
|
|
207
|
+
// 1. Range Mode Hook (usePeriodSliderRange)
|
|
208
|
+
// ======================================================================
|
|
209
|
+
|
|
210
|
+
export interface UsePeriodSliderRangeOptions extends Partial<Omit<PeriodSliderRangeProps, "mode" | "unit" | "minDate" | "maxDate" | "range" | "defaultRange" | "onChangeRange">> {
|
|
211
|
+
/** Time resolution unit / 時間解像度単位 */
|
|
212
|
+
unit: PeriodSliderUnit
|
|
213
|
+
/** Minimum selectable boundary date (required, no fallback) / 選択可能下限日付 (必須・フォールバックなし) */
|
|
214
|
+
minDate: Date
|
|
215
|
+
/** Maximum selectable boundary date, strictly later than minDate (required, no fallback) / 選択可能上限日付 (必須・minDate より後・フォールバックなし) */
|
|
216
|
+
maxDate: Date
|
|
217
|
+
/** Initial selected range [lower, upper], both inside [minDate, maxDate] (required, no fallback) / 初期選択期間 (必須・両端が [minDate, maxDate] 内・フォールバックなし) */
|
|
218
|
+
initialRange: [Date, Date]
|
|
219
|
+
/** Callback triggered when the selected range changes / 期間変更時コールバック */
|
|
220
|
+
onChangeRange?: (lower: Date, upper: Date) => void
|
|
45
221
|
}
|
|
46
222
|
|
|
47
223
|
export interface UsePeriodSliderRangeReturn {
|
|
@@ -51,13 +227,13 @@ export interface UsePeriodSliderRangeReturn {
|
|
|
51
227
|
lowerDate: Date
|
|
52
228
|
/** Current upper date / 現在の選択上限日付 */
|
|
53
229
|
upperDate: Date
|
|
54
|
-
/** State updater for full range / 期間更新関数 */
|
|
230
|
+
/** State updater for full range; replaces state without firing onChangeRange / 期間更新関数 (onChangeRange は発火しない) */
|
|
55
231
|
setRange: React.Dispatch<React.SetStateAction<[Date, Date]>>
|
|
56
|
-
/**
|
|
232
|
+
/** Sets the lower date, pushing the upper date when overtaken and clamping into [minDate, maxDate] / 下限日付更新関数 (上限を超えたら上限も追従・[minDate, maxDate] へクランプ) */
|
|
57
233
|
setLowerDate: (date: Date) => void
|
|
58
|
-
/**
|
|
234
|
+
/** Sets the upper date, pushing the lower date when undercut and clamping into [minDate, maxDate] / 上限日付更新関数 (下限を下回ったら下限も追従・[minDate, maxDate] へクランプ) */
|
|
59
235
|
setUpperDate: (date: Date) => void
|
|
60
|
-
/**
|
|
236
|
+
/** Shifts both edges by delta units - or delta positions through allowedDates - clamping each edge into [minDate, maxDate] (the clamped edge narrows the period) / 両端を delta 単位 (allowedDates 指定時は delta 個分) シフトし各端を [minDate, maxDate] へクランプ (境界に達した側は期間幅が縮む) */
|
|
61
237
|
shiftRange: (delta: number) => void
|
|
62
238
|
/** Reset range to initial values / 初期期間へリセット */
|
|
63
239
|
resetRange: () => void
|
|
@@ -69,20 +245,23 @@ export interface UsePeriodSliderRangeReturn {
|
|
|
69
245
|
sliderProps: PeriodSliderRangeProps
|
|
70
246
|
}
|
|
71
247
|
|
|
72
|
-
function clampDate(date: Date, min?: Date, max?: Date): Date {
|
|
73
|
-
if (min && date < min) return min
|
|
74
|
-
if (max && date > max) return max
|
|
75
|
-
return date
|
|
76
|
-
}
|
|
77
|
-
|
|
78
248
|
/**
|
|
79
249
|
* Custom hook to manage state and props for a range PeriodSlider.
|
|
250
|
+
* The selected range never leaves [minDate, maxDate]: it is clamped on every mutation and
|
|
251
|
+
* re-clamped during render when the boundary options move, and a mutation that resolves to
|
|
252
|
+
* the current selection fires no callback.
|
|
80
253
|
* Range モード PeriodSlider のステート管理と Props 生成を行うカスタムフック。
|
|
81
254
|
*
|
|
255
|
+
* @param options - Required unit, boundaries and initial range plus optional UI props / 必須の単位・境界・初期期間と任意の UI Props
|
|
256
|
+
* @returns Range state, mutators and pre-configured slider/selector props / 期間ステート・更新関数・生成済み Props 群
|
|
257
|
+
* @throws {RangeError} When minDate/maxDate/initialRange is missing, invalid, inverted or outside [minDate, maxDate] / minDate・maxDate・initialRange が欠落、不正、逆転、または [minDate, maxDate] の外にある場合
|
|
258
|
+
*
|
|
82
259
|
* @example
|
|
83
260
|
* ```tsx
|
|
84
261
|
* const { sliderProps, startSelectorProps, endSelectorProps } = usePeriodSliderRange({
|
|
85
262
|
* unit: "month",
|
|
263
|
+
* minDate: new Date(2020, 0, 1),
|
|
264
|
+
* maxDate: new Date(2025, 11, 1),
|
|
86
265
|
* initialRange: [new Date(2023, 0, 1), new Date(2024, 0, 1)],
|
|
87
266
|
* })
|
|
88
267
|
* return (
|
|
@@ -95,85 +274,92 @@ function clampDate(date: Date, min?: Date, max?: Date): Date {
|
|
|
95
274
|
* ```
|
|
96
275
|
*/
|
|
97
276
|
export function usePeriodSliderRange(options: UsePeriodSliderRangeOptions): UsePeriodSliderRangeReturn {
|
|
98
|
-
const { unit,
|
|
277
|
+
const { unit, minDate, maxDate, initialRange, onChangeRange, ...restUiProps } = options
|
|
278
|
+
|
|
279
|
+
assertValidBounds("usePeriodSliderRange", minDate, maxDate)
|
|
280
|
+
assertValidRangeTuple("usePeriodSliderRange", "initialRange", initialRange)
|
|
281
|
+
assertRangeWithinBounds("usePeriodSliderRange", "initialRange", initialRange, minDate, maxDate, "[minDate, maxDate]")
|
|
282
|
+
|
|
283
|
+
// レスト構文の転送 Props は毎レンダー別オブジェクトになり、依存に置くと sliderProps のメモ化が常に外れる
|
|
284
|
+
const uiProps = useShallowStable(restUiProps)
|
|
285
|
+
|
|
286
|
+
const initialRangeRef = useRef<[Date, Date]>(initialRange)
|
|
287
|
+
const [rangeState, setRange] = useState<[Date, Date]>(initialRange)
|
|
288
|
+
|
|
289
|
+
// 境界オプションは実行中に動き得るため、定義域外になったステートはレンダー中に畳み込む (aria-valuenow が valuemin/valuemax を外れないため)
|
|
290
|
+
let range = rangeState
|
|
291
|
+
const containedRange: [Date, Date] = [clampDate(rangeState[0], minDate, maxDate), clampDate(rangeState[1], minDate, maxDate)]
|
|
292
|
+
if (containedRange[0] !== rangeState[0] || containedRange[1] !== rangeState[1]) {
|
|
293
|
+
range = containedRange
|
|
294
|
+
setRange(containedRange)
|
|
295
|
+
}
|
|
99
296
|
|
|
100
|
-
const resolvedInitialRange: [Date, Date] = rawInitialRange ?? defaultRange ?? [minDate ?? new Date(), maxDate ?? new Date()]
|
|
101
|
-
const initialRangeRef = useRef<[Date, Date]>(resolvedInitialRange)
|
|
102
|
-
const [range, setRange] = useState<[Date, Date]>(resolvedInitialRange)
|
|
103
297
|
const rangeRef = useRef<[Date, Date]>(range)
|
|
104
298
|
rangeRef.current = range
|
|
105
299
|
|
|
300
|
+
// 境界と離散候補も ref 経由で読むことで、消費側が毎レンダー新しい Date や配列を渡しても更新関数の同一性を保つ
|
|
301
|
+
const domainRef = useRef({ minDate, maxDate, allowedDates: uiProps.allowedDates })
|
|
302
|
+
domainRef.current = { minDate, maxDate, allowedDates: uiProps.allowedDates }
|
|
303
|
+
|
|
304
|
+
// コールバックを ref 経由で読むことで、消費側が毎レンダー新しい関数を渡しても更新関数の同一性を保つ
|
|
106
305
|
const onChangeRangeRef = useRef(onChangeRange)
|
|
107
306
|
onChangeRangeRef.current = onChangeRange
|
|
108
|
-
const onChangeRangeTupleRef = useRef(onChangeRangeTuple)
|
|
109
|
-
onChangeRangeTupleRef.current = onChangeRangeTuple
|
|
110
|
-
const onChangeRef = useRef(onChange)
|
|
111
|
-
onChangeRef.current = onChange
|
|
112
307
|
|
|
113
|
-
const
|
|
308
|
+
const emitRange = useCallback((nextRange: [Date, Date]) => {
|
|
309
|
+
const { minDate: domainLower, maxDate: domainUpper } = domainRef.current
|
|
310
|
+
const lower = clampDate(nextRange[0], domainLower, domainUpper)
|
|
311
|
+
const upper = clampDate(nextRange[1], domainLower, domainUpper)
|
|
114
312
|
const current = rangeRef.current
|
|
115
|
-
|
|
116
|
-
if (
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
setRange(nextRange)
|
|
121
|
-
onChangeRangeRef.current?.(nextRange[0], nextRange[1])
|
|
122
|
-
onChangeRangeTupleRef.current?.(nextRange)
|
|
123
|
-
onChangeRef.current?.(nextRange)
|
|
313
|
+
// 選択が動いていない確定値でコールバックを撃つと、変更駆動の消費側が無意味な再取得を行う
|
|
314
|
+
if (lower.getTime() === current[0].getTime() && upper.getTime() === current[1].getTime()) return
|
|
315
|
+
rangeRef.current = [lower, upper]
|
|
316
|
+
setRange([lower, upper])
|
|
317
|
+
onChangeRangeRef.current?.(lower, upper)
|
|
124
318
|
}, [])
|
|
125
319
|
|
|
126
|
-
const
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
}
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
onChangeRangeRef.current?.(nextRange[0], nextRange[1])
|
|
135
|
-
onChangeRangeTupleRef.current?.(nextRange)
|
|
136
|
-
onChangeRef.current?.(nextRange)
|
|
137
|
-
}, [])
|
|
320
|
+
const setLowerDate = useCallback(
|
|
321
|
+
(newLower: Date) => {
|
|
322
|
+
const current = rangeRef.current
|
|
323
|
+
const nextUpper = newLower.getTime() > current[1].getTime() ? newLower : current[1]
|
|
324
|
+
emitRange([newLower, nextUpper])
|
|
325
|
+
},
|
|
326
|
+
[emitRange],
|
|
327
|
+
)
|
|
138
328
|
|
|
139
|
-
const
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
329
|
+
const setUpperDate = useCallback(
|
|
330
|
+
(newUpper: Date) => {
|
|
331
|
+
const current = rangeRef.current
|
|
332
|
+
const nextLower = newUpper.getTime() < current[0].getTime() ? newUpper : current[0]
|
|
333
|
+
emitRange([nextLower, newUpper])
|
|
334
|
+
},
|
|
335
|
+
[emitRange],
|
|
336
|
+
)
|
|
146
337
|
|
|
147
|
-
const
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
338
|
+
const handleSliderChange = useCallback(
|
|
339
|
+
(lower: Date, upper: Date) => {
|
|
340
|
+
emitRange([lower, upper])
|
|
341
|
+
},
|
|
342
|
+
[emitRange],
|
|
343
|
+
)
|
|
153
344
|
|
|
154
345
|
const shiftRange = useCallback(
|
|
155
346
|
(delta: number) => {
|
|
347
|
+
const { minDate: domainLower, maxDate: domainUpper, allowedDates } = domainRef.current
|
|
156
348
|
const current = rangeRef.current
|
|
157
|
-
|
|
158
|
-
const
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
onChangeRangeTupleRef.current?.(nextRange)
|
|
165
|
-
onChangeRef.current?.(nextRange)
|
|
349
|
+
// 離散指定時に暦単位で進めると、スライダーが表示しない日付をステートとコールバックへ流してしまう
|
|
350
|
+
const sortedAllowedDates = getSortedAllowedDates(allowedDates, unit, domainLower, domainUpper)
|
|
351
|
+
if (sortedAllowedDates.length > 0) {
|
|
352
|
+
emitRange([stepThroughAllowedDates(sortedAllowedDates, unit, current[0], delta), stepThroughAllowedDates(sortedAllowedDates, unit, current[1], delta)])
|
|
353
|
+
return
|
|
354
|
+
}
|
|
355
|
+
emitRange([addUnit(unit, current[0], delta), addUnit(unit, current[1], delta)])
|
|
166
356
|
},
|
|
167
|
-
[unit,
|
|
357
|
+
[unit, emitRange],
|
|
168
358
|
)
|
|
169
359
|
|
|
170
360
|
const resetRange = useCallback(() => {
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
onChangeRangeRef.current?.(resetVal[0], resetVal[1])
|
|
174
|
-
onChangeRangeTupleRef.current?.(resetVal)
|
|
175
|
-
onChangeRef.current?.(resetVal)
|
|
176
|
-
}, [])
|
|
361
|
+
emitRange(initialRangeRef.current)
|
|
362
|
+
}, [emitRange])
|
|
177
363
|
|
|
178
364
|
const startSelectorProps = useMemo<SelectorProps>(
|
|
179
365
|
() => ({
|
|
@@ -199,17 +385,15 @@ export function usePeriodSliderRange(options: UsePeriodSliderRangeOptions): UseP
|
|
|
199
385
|
|
|
200
386
|
const sliderProps = useMemo<PeriodSliderRangeProps>(
|
|
201
387
|
() => ({
|
|
202
|
-
...
|
|
388
|
+
...uiProps,
|
|
203
389
|
mode: "range",
|
|
204
390
|
unit,
|
|
205
391
|
range,
|
|
206
392
|
minDate,
|
|
207
393
|
maxDate,
|
|
208
394
|
onChangeRange: handleSliderChange,
|
|
209
|
-
onChangeRangeTuple: handleSliderChangeTuple,
|
|
210
|
-
onChange: handleSliderChangeTuple,
|
|
211
395
|
}),
|
|
212
|
-
[
|
|
396
|
+
[uiProps, unit, range, minDate, maxDate, handleSliderChange],
|
|
213
397
|
)
|
|
214
398
|
|
|
215
399
|
return {
|
|
@@ -231,33 +415,25 @@ export function usePeriodSliderRange(options: UsePeriodSliderRangeOptions): UseP
|
|
|
231
415
|
// 2. Point Mode Hook (usePeriodSliderPoint)
|
|
232
416
|
// ======================================================================
|
|
233
417
|
|
|
234
|
-
export interface UsePeriodSliderPointOptions extends Partial<Omit<PeriodSliderPointProps, "mode" | "unit" | "
|
|
418
|
+
export interface UsePeriodSliderPointOptions extends Partial<Omit<PeriodSliderPointProps, "mode" | "unit" | "minDate" | "maxDate" | "value" | "defaultValue" | "onChangePoint">> {
|
|
235
419
|
/** Time resolution unit / 時間解像度単位 */
|
|
236
420
|
unit: PeriodSliderUnit
|
|
237
|
-
/**
|
|
238
|
-
|
|
239
|
-
/**
|
|
240
|
-
|
|
241
|
-
/** Initial selected date
|
|
242
|
-
|
|
243
|
-
/** Minimum selectable boundary date / 選択可能下限日付 */
|
|
244
|
-
minDate?: Date
|
|
245
|
-
/** Maximum selectable boundary date / 選択可能上限日付 */
|
|
246
|
-
maxDate?: Date
|
|
421
|
+
/** Minimum selectable boundary date (required, no fallback) / 選択可能下限日付 (必須・フォールバックなし) */
|
|
422
|
+
minDate: Date
|
|
423
|
+
/** Maximum selectable boundary date, strictly later than minDate (required, no fallback) / 選択可能上限日付 (必須・minDate より後・フォールバックなし) */
|
|
424
|
+
maxDate: Date
|
|
425
|
+
/** Initial selected date inside [minDate, maxDate] (required, no fallback) / 初期選択日 (必須・[minDate, maxDate] 内・フォールバックなし) */
|
|
426
|
+
initialValue: Date
|
|
247
427
|
/** Callback triggered when point changes / 日付変更時コールバック */
|
|
248
428
|
onChangePoint?: (value: Date) => void
|
|
249
|
-
/** Callback triggered when point changes (alias) / 日付変更時コールバック (エイリアス) */
|
|
250
|
-
onChangeValue?: (value: Date) => void
|
|
251
|
-
/** Callback alias when point changes / 日付変更時コールバック (エイリアス) */
|
|
252
|
-
onChange?: (value: Date) => void
|
|
253
429
|
}
|
|
254
430
|
|
|
255
431
|
export interface UsePeriodSliderPointReturn {
|
|
256
432
|
/** Current selected point date / 現在の選択日付 */
|
|
257
433
|
value: Date
|
|
258
|
-
/** State updater for point / 日付更新関数 */
|
|
434
|
+
/** State updater for point; replaces state without firing onChangePoint / 日付更新関数 (onChangePoint は発火しない) */
|
|
259
435
|
setValue: React.Dispatch<React.SetStateAction<Date>>
|
|
260
|
-
/**
|
|
436
|
+
/** Shifts the point by delta units - or delta positions through allowedDates - clamping into [minDate, maxDate] / 日付を delta 単位 (allowedDates 指定時は delta 個分) シフトし [minDate, maxDate] へクランプ */
|
|
261
437
|
shiftValue: (delta: number) => void
|
|
262
438
|
/** Reset to initial value / 初期日付へリセット */
|
|
263
439
|
resetValue: () => void
|
|
@@ -269,12 +445,21 @@ export interface UsePeriodSliderPointReturn {
|
|
|
269
445
|
|
|
270
446
|
/**
|
|
271
447
|
* Custom hook to manage state and props for a point PeriodSlider.
|
|
448
|
+
* The selected date never leaves [minDate, maxDate]: it is clamped on every mutation and
|
|
449
|
+
* re-clamped during render when the boundary options move, and a mutation that resolves to
|
|
450
|
+
* the current selection fires no callback.
|
|
272
451
|
* Point モード PeriodSlider のステート管理と Props 生成を行うカスタムフック。
|
|
273
452
|
*
|
|
453
|
+
* @param options - Required unit, boundaries and initial value plus optional UI props / 必須の単位・境界・初期日付と任意の UI Props
|
|
454
|
+
* @returns Point state, mutators and pre-configured slider/selector props / 日付ステート・更新関数・生成済み Props 群
|
|
455
|
+
* @throws {RangeError} When minDate/maxDate/initialValue is missing, invalid or outside [minDate, maxDate] / minDate・maxDate・initialValue が欠落、不正、または [minDate, maxDate] の外にある場合
|
|
456
|
+
*
|
|
274
457
|
* @example
|
|
275
458
|
* ```tsx
|
|
276
459
|
* const { value, sliderProps, selectorProps } = usePeriodSliderPoint({
|
|
277
460
|
* unit: "month",
|
|
461
|
+
* minDate: new Date(2020, 0, 1),
|
|
462
|
+
* maxDate: new Date(2025, 11, 1),
|
|
278
463
|
* initialValue: new Date(2024, 5, 1),
|
|
279
464
|
* })
|
|
280
465
|
* return (
|
|
@@ -286,73 +471,87 @@ export interface UsePeriodSliderPointReturn {
|
|
|
286
471
|
* ```
|
|
287
472
|
*/
|
|
288
473
|
export function usePeriodSliderPoint(options: UsePeriodSliderPointOptions): UsePeriodSliderPointReturn {
|
|
289
|
-
const { unit,
|
|
474
|
+
const { unit, minDate, maxDate, initialValue, onChangePoint, ...restUiProps } = options
|
|
475
|
+
|
|
476
|
+
assertValidBounds("usePeriodSliderPoint", minDate, maxDate)
|
|
477
|
+
assertValidDate("usePeriodSliderPoint", "initialValue", initialValue)
|
|
478
|
+
assertWithinBounds("usePeriodSliderPoint", "initialValue", initialValue, minDate, maxDate, "[minDate, maxDate]")
|
|
479
|
+
|
|
480
|
+
// レスト構文の転送 Props は毎レンダー別オブジェクトになり、依存に置くと sliderProps のメモ化が常に外れる
|
|
481
|
+
const uiProps = useShallowStable(restUiProps)
|
|
482
|
+
|
|
483
|
+
const initialValueRef = useRef<Date>(initialValue)
|
|
484
|
+
const [valueState, setValue] = useState<Date>(initialValue)
|
|
485
|
+
|
|
486
|
+
// 境界オプションは実行中に動き得るため、定義域外になったステートはレンダー中に畳み込む (aria-valuenow が valuemin/valuemax を外れないため)
|
|
487
|
+
let value = valueState
|
|
488
|
+
const containedValue = clampDate(valueState, minDate, maxDate)
|
|
489
|
+
if (containedValue !== valueState) {
|
|
490
|
+
value = containedValue
|
|
491
|
+
setValue(containedValue)
|
|
492
|
+
}
|
|
290
493
|
|
|
291
|
-
const resolvedInitialValue: Date = rawInitialValue ?? initialDate ?? defaultValue ?? minDate ?? new Date()
|
|
292
|
-
const initialValueRef = useRef<Date>(resolvedInitialValue)
|
|
293
|
-
const [value, setValue] = useState<Date>(resolvedInitialValue)
|
|
294
494
|
const valueRef = useRef<Date>(value)
|
|
295
495
|
valueRef.current = value
|
|
296
496
|
|
|
497
|
+
// 境界と離散候補も ref 経由で読むことで、消費側が毎レンダー新しい Date や配列を渡しても更新関数の同一性を保つ
|
|
498
|
+
const domainRef = useRef({ minDate, maxDate, allowedDates: uiProps.allowedDates })
|
|
499
|
+
domainRef.current = { minDate, maxDate, allowedDates: uiProps.allowedDates }
|
|
500
|
+
|
|
501
|
+
// コールバックを ref 経由で読むことで、消費側が毎レンダー新しい関数を渡しても更新関数の同一性を保つ
|
|
297
502
|
const onChangePointRef = useRef(onChangePoint)
|
|
298
503
|
onChangePointRef.current = onChangePoint
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
onChangeRef.current?.(nextDate)
|
|
504
|
+
|
|
505
|
+
const emitValue = useCallback((nextDate: Date) => {
|
|
506
|
+
const { minDate: domainLower, maxDate: domainUpper } = domainRef.current
|
|
507
|
+
const nextValue = clampDate(nextDate, domainLower, domainUpper)
|
|
508
|
+
// 選択が動いていない確定値でコールバックを撃つと、変更駆動の消費側が無意味な再取得を行う
|
|
509
|
+
if (nextValue.getTime() === valueRef.current.getTime()) return
|
|
510
|
+
valueRef.current = nextValue
|
|
511
|
+
setValue(nextValue)
|
|
512
|
+
onChangePointRef.current?.(nextValue)
|
|
309
513
|
}, [])
|
|
310
514
|
|
|
311
515
|
const shiftValue = useCallback(
|
|
312
516
|
(delta: number) => {
|
|
313
|
-
const
|
|
314
|
-
|
|
315
|
-
const
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
517
|
+
const { minDate: domainLower, maxDate: domainUpper, allowedDates } = domainRef.current
|
|
518
|
+
// 離散指定時に暦単位で進めると、スライダーが表示しない日付をステートとコールバックへ流してしまう
|
|
519
|
+
const sortedAllowedDates = getSortedAllowedDates(allowedDates, unit, domainLower, domainUpper)
|
|
520
|
+
if (sortedAllowedDates.length > 0) {
|
|
521
|
+
emitValue(stepThroughAllowedDates(sortedAllowedDates, unit, valueRef.current, delta))
|
|
522
|
+
return
|
|
523
|
+
}
|
|
524
|
+
emitValue(addUnit(unit, valueRef.current, delta))
|
|
320
525
|
},
|
|
321
|
-
[unit,
|
|
526
|
+
[unit, emitValue],
|
|
322
527
|
)
|
|
323
528
|
|
|
324
529
|
const resetValue = useCallback(() => {
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
onChangePointRef.current?.(resetVal)
|
|
328
|
-
onChangeValueRef.current?.(resetVal)
|
|
329
|
-
onChangeRef.current?.(resetVal)
|
|
330
|
-
}, [])
|
|
530
|
+
emitValue(initialValueRef.current)
|
|
531
|
+
}, [emitValue])
|
|
331
532
|
|
|
332
533
|
const selectorProps = useMemo<SelectorProps>(
|
|
333
534
|
() => ({
|
|
334
535
|
value,
|
|
335
|
-
onChange:
|
|
536
|
+
onChange: emitValue,
|
|
336
537
|
minDate,
|
|
337
538
|
maxDate,
|
|
338
539
|
unit,
|
|
339
540
|
}),
|
|
340
|
-
[value,
|
|
541
|
+
[value, emitValue, minDate, maxDate, unit],
|
|
341
542
|
)
|
|
342
543
|
|
|
343
544
|
const sliderProps = useMemo<PeriodSliderPointProps>(
|
|
344
545
|
() => ({
|
|
345
|
-
...
|
|
546
|
+
...uiProps,
|
|
346
547
|
mode: "point",
|
|
347
548
|
unit,
|
|
348
549
|
value,
|
|
349
550
|
minDate,
|
|
350
551
|
maxDate,
|
|
351
|
-
onChangePoint:
|
|
352
|
-
onChangeValue: handlePointChange,
|
|
353
|
-
onChange: handlePointChange,
|
|
552
|
+
onChangePoint: emitValue,
|
|
354
553
|
}),
|
|
355
|
-
[
|
|
554
|
+
[uiProps, unit, value, minDate, maxDate, emitValue],
|
|
356
555
|
)
|
|
357
556
|
|
|
358
557
|
return {
|
|
@@ -369,66 +568,47 @@ export function usePeriodSliderPoint(options: UsePeriodSliderPointOptions): UseP
|
|
|
369
568
|
// 3. Vernier Dual-Scale Hook (useVernierSlider)
|
|
370
569
|
// ======================================================================
|
|
371
570
|
|
|
372
|
-
export interface UseVernierSliderOptions
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
/** Minimum selectable boundary date for entire macro range / 全期間マクロの下限日付 (必須) */
|
|
571
|
+
export interface UseVernierSliderOptions extends Partial<Omit<PeriodSliderVernierProps, "mode" | "unit" | "minDate" | "maxDate" | "macroUnit" | "microUnit" | "macroRange" | "microRange" | "defaultMicroRange" | "onChangeMacroRange" | "onChangeMicroRange">> {
|
|
572
|
+
/** Base time resolution unit / 基本時間解像度単位 */
|
|
573
|
+
unit: PeriodSliderUnit
|
|
574
|
+
/** Minimum selectable boundary date for entire macro range (required, no fallback) / 全期間マクロの下限日付 (必須・フォールバックなし) */
|
|
377
575
|
minDate: Date
|
|
378
|
-
/** Maximum selectable boundary date for entire macro range / 全期間マクロの上限日付 (
|
|
576
|
+
/** Maximum selectable boundary date for entire macro range, strictly later than minDate (required, no fallback) / 全期間マクロの上限日付 (必須・minDate より後・フォールバックなし) */
|
|
379
577
|
maxDate: Date
|
|
380
|
-
/** Initial macro window range [start, end] / 初期マクロ窓期間 */
|
|
381
|
-
initialMacroRange
|
|
382
|
-
/** Initial macro window
|
|
383
|
-
|
|
384
|
-
/**
|
|
385
|
-
initialMicroRange?: [Date, Date]
|
|
386
|
-
/** Initial micro selected range alias / 初期ミクロ選択期間 (エイリアス) */
|
|
387
|
-
defaultMicroRange?: [Date, Date]
|
|
388
|
-
/** Base time resolution unit / 基本単位 (既定: "month") */
|
|
389
|
-
unit?: PeriodSliderUnit
|
|
390
|
-
/** Macro scale unit / マクロ単位 */
|
|
578
|
+
/** Initial macro window range [start, end] inside [minDate, maxDate] (required, no fallback) / 初期マクロ窓期間 (必須・[minDate, maxDate] 内・フォールバックなし) */
|
|
579
|
+
initialMacroRange: [Date, Date]
|
|
580
|
+
/** Initial micro selected range [lower, upper] inside the initial macro window (required, no fallback) / 初期ミクロ選択期間 (必須・初期マクロ窓の内側・フォールバックなし) */
|
|
581
|
+
initialMicroRange: [Date, Date]
|
|
582
|
+
/** Macro scale unit (defaults to unit) / マクロ単位 (既定: unit) */
|
|
391
583
|
macroUnit?: PeriodSliderUnit
|
|
392
|
-
/** Micro scale unit / ミクロ単位 */
|
|
584
|
+
/** Micro scale unit (defaults to unit) / ミクロ単位 (既定: unit) */
|
|
393
585
|
microUnit?: PeriodSliderUnit
|
|
394
586
|
/** Callback triggered when macro window changes / マクロ窓変更時コールバック */
|
|
395
587
|
onChangeMacroRange?: (lower: Date, upper: Date) => void
|
|
396
|
-
/** Callback triggered with tuple when macro window changes / マクロ窓変更時タプルコールバック */
|
|
397
|
-
onChangeMacroRangeTuple?: (range: [Date, Date]) => void
|
|
398
|
-
/** Symmetrical callback alias for macro window / マクロ窓変更時コールバック (エイリアス) */
|
|
399
|
-
onChangeMacro?: (range: [Date, Date]) => void
|
|
400
588
|
/** Callback triggered when micro range changes / ミクロ選択範囲変更時コールバック */
|
|
401
|
-
onChangeRange?: (lower: Date, upper: Date) => void
|
|
402
|
-
/** Callback triggered with tuple when micro range changes / ミクロ選択範囲変更時タプルコールバック */
|
|
403
|
-
onChangeRangeTuple?: (range: [Date, Date]) => void
|
|
404
|
-
/** Symmetrical callback for micro range / ミクロ選択範囲変更時コールバック */
|
|
405
589
|
onChangeMicroRange?: (lower: Date, upper: Date) => void
|
|
406
|
-
/** Symmetrical tuple callback for micro range / ミクロ選択範囲変更時タプルコールバック */
|
|
407
|
-
onChangeMicroRangeTuple?: (range: [Date, Date]) => void
|
|
408
|
-
/** Symmetrical alias for micro range / ミクロ選択範囲変更時コールバック (エイリアス) */
|
|
409
|
-
onChangeMicro?: (range: [Date, Date]) => void
|
|
410
590
|
}
|
|
411
591
|
|
|
412
592
|
export interface UseVernierSliderReturn {
|
|
413
593
|
/** Macro window range tuple / マクロ窓期間タプル */
|
|
414
594
|
macroRange: [Date, Date]
|
|
415
|
-
/** State updater for macro range / マクロ窓更新関数 */
|
|
595
|
+
/** State updater for macro range; replaces state without firing onChangeMacroRange / マクロ窓更新関数 (onChangeMacroRange は発火しない) */
|
|
416
596
|
setMacroRange: React.Dispatch<React.SetStateAction<[Date, Date]>>
|
|
417
597
|
/** Micro selected range tuple / ミクロ選択期間タプル */
|
|
418
598
|
microRange: [Date, Date]
|
|
419
|
-
/** State updater for micro range / ミクロ選択範囲更新関数 */
|
|
599
|
+
/** State updater for micro range; replaces state without firing onChangeMicroRange / ミクロ選択範囲更新関数 (onChangeMicroRange は発火しない) */
|
|
420
600
|
setMicroRange: React.Dispatch<React.SetStateAction<[Date, Date]>>
|
|
421
|
-
/**
|
|
601
|
+
/** Sets the macro lower date, pushing the macro upper date when overtaken and clamping the window into [minDate, maxDate] / マクロ開始日更新 (上限を超えたら上限も追従・窓を [minDate, maxDate] へクランプ) */
|
|
422
602
|
setMacroLowerDate: (date: Date) => void
|
|
423
|
-
/**
|
|
603
|
+
/** Sets the macro upper date, pushing the macro lower date when undercut and clamping the window into [minDate, maxDate] / マクロ終了日更新 (下限を下回ったら下限も追従・窓を [minDate, maxDate] へクランプ) */
|
|
424
604
|
setMacroUpperDate: (date: Date) => void
|
|
425
|
-
/**
|
|
605
|
+
/** Sets the micro lower date, pushing the micro upper date when overtaken and clamping into the macro window / ミクロ開始日更新 (上限を超えたら上限も追従・マクロ窓へクランプ) */
|
|
426
606
|
setMicroLowerDate: (date: Date) => void
|
|
427
|
-
/**
|
|
607
|
+
/** Sets the micro upper date, pushing the micro lower date when undercut and clamping into the macro window / ミクロ終了日更新 (下限を下回ったら下限も追従・マクロ窓へクランプ) */
|
|
428
608
|
setMicroUpperDate: (date: Date) => void
|
|
429
|
-
/**
|
|
609
|
+
/** Shifts the macro window by delta macro units, aborting entirely when either edge would leave [minDate, maxDate] / マクロ窓を delta マクロ単位シフト (片側でも定義域を越える場合は全体中止) */
|
|
430
610
|
shiftMacroRange: (delta: number) => void
|
|
431
|
-
/**
|
|
611
|
+
/** Shifts the micro range by delta micro units, aborting entirely when either edge would leave the macro window / ミクロ選択範囲を delta ミクロ単位シフト (片側でもマクロ窓を越える場合は全体中止) */
|
|
432
612
|
shiftMicroRange: (delta: number) => void
|
|
433
613
|
/** Reset to initial macro and micro ranges / 初期状態へリセット */
|
|
434
614
|
resetVernier: () => void
|
|
@@ -438,7 +618,7 @@ export interface UseVernierSliderReturn {
|
|
|
438
618
|
macroEndSelectorProps: SelectorProps
|
|
439
619
|
/** Pre-configured props for micro start selector / ミクロ開始日セレクタ用 Props */
|
|
440
620
|
microStartSelectorProps: SelectorProps
|
|
441
|
-
/** Pre-configured props for micro end selector / ミクロ終了日セレクタ用 Props */
|
|
621
|
+
/** Pre-configured props for micro end selector (maxDate is the effective macro window end) / ミクロ終了日セレクタ用 Props (maxDate は実効マクロ窓終端) */
|
|
442
622
|
microEndSelectorProps: SelectorProps
|
|
443
623
|
/** Pre-configured props to spread directly onto PeriodSlider / PeriodSlider に直接スプレッド可能な Props */
|
|
444
624
|
sliderProps: PeriodSliderVernierProps
|
|
@@ -446,11 +626,19 @@ export interface UseVernierSliderReturn {
|
|
|
446
626
|
|
|
447
627
|
/**
|
|
448
628
|
* Custom hook to manage state and props for a Vernier dual-scale PeriodSlider.
|
|
629
|
+
* Two containment invariants hold after every mutation and every render: the macro window
|
|
630
|
+
* stays inside [minDate, maxDate], and the micro range stays inside the macro window whose
|
|
631
|
+
* end is getMacroWindowEndDate(macroUnit, microUnit, macroRange[1]).
|
|
449
632
|
* Vernier 2 段スケール PeriodSlider のステート管理と Props 生成を行うカスタムフック。
|
|
450
633
|
*
|
|
634
|
+
* @param options - Required unit, boundaries, initial macro/micro ranges plus optional UI props / 必須の単位・境界・初期マクロ/ミクロ期間と任意の UI Props
|
|
635
|
+
* @returns Dual-scale state, mutators and pre-configured slider/selector props / 2 段スケールのステート・更新関数・生成済み Props 群
|
|
636
|
+
* @throws {RangeError} When a boundary or initial range is missing, invalid, inverted, outside [minDate, maxDate], or (for initialMicroRange) outside the initial macro window / 境界または初期期間が欠落、不正、逆転、[minDate, maxDate] 外、または (initialMicroRange が) 初期マクロ窓の外にある場合
|
|
637
|
+
*
|
|
451
638
|
* @example
|
|
452
639
|
* ```tsx
|
|
453
640
|
* const { macroRange, microRange, sliderProps, macroStartSelectorProps, macroEndSelectorProps } = useVernierSlider({
|
|
641
|
+
* unit: "month",
|
|
454
642
|
* minDate: new Date(2015, 0, 1),
|
|
455
643
|
* maxDate: new Date(2030, 11, 31),
|
|
456
644
|
* initialMacroRange: [new Date(2020, 0, 1), new Date(2026, 0, 1)],
|
|
@@ -462,127 +650,133 @@ export interface UseVernierSliderReturn {
|
|
|
462
650
|
* ```
|
|
463
651
|
*/
|
|
464
652
|
export function useVernierSlider(options: UseVernierSliderOptions): UseVernierSliderReturn {
|
|
465
|
-
const {
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
653
|
+
const { unit, minDate, maxDate, initialMacroRange, initialMicroRange, macroUnit = unit, microUnit = unit, onChangeMacroRange, onChangeMicroRange, ...restUiProps } = options
|
|
654
|
+
|
|
655
|
+
assertValidBounds("useVernierSlider", minDate, maxDate)
|
|
656
|
+
assertValidRangeTuple("useVernierSlider", "initialMacroRange", initialMacroRange)
|
|
657
|
+
assertValidRangeTuple("useVernierSlider", "initialMicroRange", initialMicroRange)
|
|
658
|
+
assertRangeWithinBounds("useVernierSlider", "initialMacroRange", initialMacroRange, minDate, maxDate, "[minDate, maxDate]")
|
|
659
|
+
assertRangeWithinBounds("useVernierSlider", "initialMicroRange", initialMicroRange, initialMacroRange[0], getMacroWindowEndDate(macroUnit, microUnit, initialMacroRange[1]), "the initial macro window")
|
|
660
|
+
|
|
661
|
+
// レスト構文の転送 Props は毎レンダー別オブジェクトになり、依存に置くと sliderProps のメモ化が常に外れる
|
|
662
|
+
const uiProps = useShallowStable(restUiProps)
|
|
663
|
+
|
|
664
|
+
const initialMacroRef = useRef<[Date, Date]>(initialMacroRange)
|
|
665
|
+
const initialMicroRef = useRef<[Date, Date]>(initialMicroRange)
|
|
666
|
+
|
|
667
|
+
const [macroRangeState, setMacroRange] = useState<[Date, Date]>(initialMacroRange)
|
|
668
|
+
const [microRangeState, setMicroRange] = useState<[Date, Date]>(initialMicroRange)
|
|
669
|
+
|
|
670
|
+
// 境界オプションもマクロ窓も実行中に動き得るため、包含関係が崩れたステートはレンダー中に畳み込む (aria-valuenow が valuemin/valuemax を外れないため)
|
|
671
|
+
let macroRange = macroRangeState
|
|
672
|
+
const containedMacro: [Date, Date] = [clampDate(macroRangeState[0], minDate, maxDate), clampDate(macroRangeState[1], minDate, maxDate)]
|
|
673
|
+
if (containedMacro[0] !== macroRangeState[0] || containedMacro[1] !== macroRangeState[1]) {
|
|
674
|
+
macroRange = containedMacro
|
|
675
|
+
setMacroRange(containedMacro)
|
|
676
|
+
}
|
|
677
|
+
|
|
678
|
+
let microRange = microRangeState
|
|
679
|
+
const containedMicro = clampRangeIntoMacroWindow(microRangeState, macroUnit, microUnit, macroRange)
|
|
680
|
+
if (containedMicro[0] !== microRangeState[0] || containedMicro[1] !== microRangeState[1]) {
|
|
681
|
+
microRange = containedMicro
|
|
682
|
+
setMicroRange(containedMicro)
|
|
683
|
+
}
|
|
684
|
+
|
|
494
685
|
const macroRangeRef = useRef<[Date, Date]>(macroRange)
|
|
495
686
|
macroRangeRef.current = macroRange
|
|
496
687
|
const microRangeRef = useRef<[Date, Date]>(microRange)
|
|
497
688
|
microRangeRef.current = microRange
|
|
498
689
|
|
|
690
|
+
// 境界を ref 経由で読むことで、消費側が毎レンダー新しい Date を渡しても更新関数の同一性を保つ
|
|
691
|
+
const domainRef = useRef({ minDate, maxDate })
|
|
692
|
+
domainRef.current = { minDate, maxDate }
|
|
693
|
+
|
|
694
|
+
// コールバックを ref 経由で読むことで、消費側が毎レンダー新しい関数を渡しても更新関数の同一性を保つ
|
|
695
|
+
const onChangeMacroRangeRef = useRef(onChangeMacroRange)
|
|
696
|
+
onChangeMacroRangeRef.current = onChangeMacroRange
|
|
697
|
+
const onChangeMicroRangeRef = useRef(onChangeMicroRange)
|
|
698
|
+
onChangeMicroRangeRef.current = onChangeMicroRange
|
|
699
|
+
|
|
700
|
+
const commitVernier = useCallback((nextMacro: [Date, Date], nextMicro: [Date, Date]) => {
|
|
701
|
+
const currentMacro = macroRangeRef.current
|
|
702
|
+
const currentMicro = microRangeRef.current
|
|
703
|
+
// 動いていないスケールのコールバックを撃つと、消費側が無関係な再取得を行う
|
|
704
|
+
if (nextMacro[0].getTime() !== currentMacro[0].getTime() || nextMacro[1].getTime() !== currentMacro[1].getTime()) {
|
|
705
|
+
macroRangeRef.current = nextMacro
|
|
706
|
+
setMacroRange(nextMacro)
|
|
707
|
+
onChangeMacroRangeRef.current?.(nextMacro[0], nextMacro[1])
|
|
708
|
+
}
|
|
709
|
+
if (nextMicro[0].getTime() !== currentMicro[0].getTime() || nextMicro[1].getTime() !== currentMicro[1].getTime()) {
|
|
710
|
+
microRangeRef.current = nextMicro
|
|
711
|
+
setMicroRange(nextMicro)
|
|
712
|
+
onChangeMicroRangeRef.current?.(nextMicro[0], nextMicro[1])
|
|
713
|
+
}
|
|
714
|
+
}, [])
|
|
715
|
+
|
|
499
716
|
const handleChangeMacroRange = useCallback(
|
|
500
717
|
(lower: Date, upper: Date) => {
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
718
|
+
const { minDate: domainLower, maxDate: domainUpper } = domainRef.current
|
|
719
|
+
const nextMacro: [Date, Date] = [clampDate(lower, domainLower, domainUpper), clampDate(upper, domainLower, domainUpper)]
|
|
720
|
+
// マクロ窓が動くとミクロ選択がはみ出し得るため、同じ確定経路で窓の内側へ押し込む
|
|
721
|
+
commitVernier(nextMacro, clampRangeIntoMacroWindow(microRangeRef.current, macroUnit, microUnit, nextMacro))
|
|
505
722
|
},
|
|
506
|
-
[
|
|
507
|
-
)
|
|
508
|
-
|
|
509
|
-
const handleChangeMacroRangeTuple = useCallback(
|
|
510
|
-
(r: [Date, Date]) => {
|
|
511
|
-
handleChangeMacroRange(r[0], r[1])
|
|
512
|
-
},
|
|
513
|
-
[handleChangeMacroRange],
|
|
723
|
+
[macroUnit, microUnit, commitVernier],
|
|
514
724
|
)
|
|
515
725
|
|
|
516
726
|
const handleChangeMicroRange = useCallback(
|
|
517
727
|
(lower: Date, upper: Date) => {
|
|
518
|
-
|
|
519
|
-
onChangeRange?.(lower, upper)
|
|
520
|
-
onChangeRangeTuple?.([lower, upper])
|
|
521
|
-
onChangeMicroRange?.(lower, upper)
|
|
522
|
-
onChangeMicroRangeTuple?.([lower, upper])
|
|
523
|
-
onChangeMicro?.([lower, upper])
|
|
728
|
+
commitVernier(macroRangeRef.current, clampRangeIntoMacroWindow([lower, upper], macroUnit, microUnit, macroRangeRef.current))
|
|
524
729
|
},
|
|
525
|
-
[
|
|
526
|
-
)
|
|
527
|
-
|
|
528
|
-
const handleChangeMicroRangeTuple = useCallback(
|
|
529
|
-
(r: [Date, Date]) => {
|
|
530
|
-
handleChangeMicroRange(r[0], r[1])
|
|
531
|
-
},
|
|
532
|
-
[handleChangeMicroRange],
|
|
730
|
+
[macroUnit, microUnit, commitVernier],
|
|
533
731
|
)
|
|
534
732
|
|
|
535
733
|
const setMacroLowerDate = useCallback(
|
|
536
734
|
(date: Date) => {
|
|
537
735
|
const currentUpper = macroRangeRef.current[1]
|
|
538
|
-
const nextLower = date < minDate ? minDate : date
|
|
539
736
|
const nextUpper = date > currentUpper ? date : currentUpper
|
|
540
|
-
handleChangeMacroRange(
|
|
737
|
+
handleChangeMacroRange(date, nextUpper)
|
|
541
738
|
},
|
|
542
|
-
[
|
|
739
|
+
[handleChangeMacroRange],
|
|
543
740
|
)
|
|
544
741
|
|
|
545
742
|
const setMacroUpperDate = useCallback(
|
|
546
743
|
(date: Date) => {
|
|
547
744
|
const currentLower = macroRangeRef.current[0]
|
|
548
|
-
const nextUpper = date > maxDate ? maxDate : date
|
|
549
745
|
const nextLower = date < currentLower ? date : currentLower
|
|
550
|
-
handleChangeMacroRange(nextLower,
|
|
746
|
+
handleChangeMacroRange(nextLower, date)
|
|
551
747
|
},
|
|
552
|
-
[
|
|
748
|
+
[handleChangeMacroRange],
|
|
553
749
|
)
|
|
554
750
|
|
|
555
751
|
const setMicroLowerDate = useCallback(
|
|
556
752
|
(date: Date) => {
|
|
557
|
-
const
|
|
558
|
-
const
|
|
559
|
-
|
|
560
|
-
const nextUpper = date > currentMicro[1] ? date : currentMicro[1]
|
|
561
|
-
handleChangeMicroRange(nextLower, nextUpper)
|
|
753
|
+
const currentUpper = microRangeRef.current[1]
|
|
754
|
+
const nextUpper = date > currentUpper ? date : currentUpper
|
|
755
|
+
handleChangeMicroRange(date, nextUpper)
|
|
562
756
|
},
|
|
563
757
|
[handleChangeMicroRange],
|
|
564
758
|
)
|
|
565
759
|
|
|
566
760
|
const setMicroUpperDate = useCallback(
|
|
567
761
|
(date: Date) => {
|
|
568
|
-
const
|
|
569
|
-
const
|
|
570
|
-
|
|
571
|
-
const nextLower = date < currentMicro[0] ? date : currentMicro[0]
|
|
572
|
-
handleChangeMicroRange(nextLower, nextUpper)
|
|
762
|
+
const currentLower = microRangeRef.current[0]
|
|
763
|
+
const nextLower = date < currentLower ? date : currentLower
|
|
764
|
+
handleChangeMicroRange(nextLower, date)
|
|
573
765
|
},
|
|
574
766
|
[handleChangeMicroRange],
|
|
575
767
|
)
|
|
576
768
|
|
|
577
769
|
const shiftMacroRange = useCallback(
|
|
578
770
|
(delta: number) => {
|
|
771
|
+
const { minDate: domainLower, maxDate: domainUpper } = domainRef.current
|
|
579
772
|
const current = macroRangeRef.current
|
|
580
773
|
const shiftedLow = addUnit(macroUnit, current[0], delta)
|
|
581
774
|
const shiftedHigh = addUnit(macroUnit, current[1], delta)
|
|
582
|
-
|
|
775
|
+
// 窓幅を保つため、片側でも境界を越えるシフトは全体を中止する
|
|
776
|
+
if (shiftedLow < domainLower || shiftedHigh > domainUpper) return
|
|
583
777
|
handleChangeMacroRange(shiftedLow, shiftedHigh)
|
|
584
778
|
},
|
|
585
|
-
[macroUnit,
|
|
779
|
+
[macroUnit, handleChangeMacroRange],
|
|
586
780
|
)
|
|
587
781
|
|
|
588
782
|
const shiftMicroRange = useCallback(
|
|
@@ -591,18 +785,19 @@ export function useVernierSlider(options: UseVernierSliderOptions): UseVernierSl
|
|
|
591
785
|
const currentMicro = microRangeRef.current
|
|
592
786
|
const shiftedLow = addUnit(microUnit, currentMicro[0], delta)
|
|
593
787
|
const shiftedHigh = addUnit(microUnit, currentMicro[1], delta)
|
|
594
|
-
|
|
788
|
+
// ミクロ選択範囲はマクロ窓の内側に限られるため、はみ出すシフトは中止する
|
|
789
|
+
if (shiftedLow < currentMacro[0] || shiftedHigh > getMacroWindowEndDate(macroUnit, microUnit, currentMacro[1])) return
|
|
595
790
|
handleChangeMicroRange(shiftedLow, shiftedHigh)
|
|
596
791
|
},
|
|
597
|
-
[microUnit, handleChangeMicroRange],
|
|
792
|
+
[macroUnit, microUnit, handleChangeMicroRange],
|
|
598
793
|
)
|
|
599
794
|
|
|
600
795
|
const resetVernier = useCallback(() => {
|
|
601
|
-
const
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
796
|
+
const initialMacro = initialMacroRef.current
|
|
797
|
+
commitVernier(initialMacro, clampRangeIntoMacroWindow(initialMicroRef.current, macroUnit, microUnit, initialMacro))
|
|
798
|
+
}, [macroUnit, microUnit, commitVernier])
|
|
799
|
+
|
|
800
|
+
const macroWindowEnd = useMemo(() => getMacroWindowEndDate(macroUnit, microUnit, macroRange[1]), [macroUnit, microUnit, macroRange[1]])
|
|
606
801
|
|
|
607
802
|
const macroStartSelectorProps: SelectorProps = useMemo(
|
|
608
803
|
() => ({
|
|
@@ -642,15 +837,15 @@ export function useVernierSlider(options: UseVernierSliderOptions): UseVernierSl
|
|
|
642
837
|
value: microRange[1],
|
|
643
838
|
onChange: setMicroUpperDate,
|
|
644
839
|
minDate: microRange[0],
|
|
645
|
-
maxDate:
|
|
840
|
+
maxDate: macroWindowEnd,
|
|
646
841
|
unit: microUnit,
|
|
647
842
|
}),
|
|
648
|
-
[microRange, setMicroUpperDate,
|
|
843
|
+
[microRange, setMicroUpperDate, macroWindowEnd, microUnit],
|
|
649
844
|
)
|
|
650
845
|
|
|
651
846
|
const sliderProps: PeriodSliderVernierProps = useMemo(
|
|
652
847
|
() => ({
|
|
653
|
-
...
|
|
848
|
+
...uiProps,
|
|
654
849
|
mode: "vernier",
|
|
655
850
|
unit,
|
|
656
851
|
macroUnit,
|
|
@@ -660,15 +855,9 @@ export function useVernierSlider(options: UseVernierSliderOptions): UseVernierSl
|
|
|
660
855
|
macroRange,
|
|
661
856
|
microRange,
|
|
662
857
|
onChangeMacroRange: handleChangeMacroRange,
|
|
663
|
-
onChangeMacroRangeTuple: handleChangeMacroRangeTuple,
|
|
664
|
-
onChangeMacro: handleChangeMacroRangeTuple,
|
|
665
|
-
onChangeRange: handleChangeMicroRange,
|
|
666
|
-
onChangeRangeTuple: handleChangeMicroRangeTuple,
|
|
667
858
|
onChangeMicroRange: handleChangeMicroRange,
|
|
668
|
-
onChangeMicroRangeTuple: handleChangeMicroRangeTuple,
|
|
669
|
-
onChangeMicro: handleChangeMicroRangeTuple,
|
|
670
859
|
}),
|
|
671
|
-
[
|
|
860
|
+
[uiProps, unit, macroUnit, microUnit, minDate, maxDate, macroRange, microRange, handleChangeMacroRange, handleChangeMicroRange],
|
|
672
861
|
)
|
|
673
862
|
|
|
674
863
|
return {
|