@aiquants/period-slider 0.2.0 → 0.3.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.
@@ -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
- // 1. Range Mode Hook (usePeriodSliderRange)
23
+ // 0. Shared Validation & Helpers
18
24
  // ======================================================================
19
25
 
20
- export interface UsePeriodSliderRangeOptions extends Partial<Omit<PeriodSliderRangeProps, "mode" | "unit" | "range" | "lowerDate" | "upperDate" | "onChangeRange" | "onChangeRangeTuple" | "onChange">> {
21
- /** Time resolution unit / 時間解像度単位 */
22
- unit: PeriodSliderUnit
23
- /** Initial selected range [lower, upper] / 初期選択期間 */
24
- initialRange?: [Date, Date]
25
- /** Initial selected range alias / 初期選択期間 (エイリアス) */
26
- defaultRange?: [Date, Date]
27
- /** Minimum selectable boundary date / 選択可能下限日付 */
28
- minDate?: Date
29
- /** Maximum selectable boundary date / 選択可能上限日付 */
30
- maxDate?: Date
31
- /** Callback triggered when range changes / 期間変更時コールバック */
32
- onChangeRange?: (lower: Date, upper: Date) => void
33
- /** Callback triggered with tuple when range changes / 期間変更時タプルコールバック */
34
- onChangeRangeTuple?: (range: [Date, Date]) => void
35
- /** Callback alias when range changes / 期間変更時コールバック (エイリアス) */
36
- onChange?: (range: [Date, Date]) => void
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
- minDate?: Date
43
- maxDate?: Date
44
- unit?: PeriodSliderUnit
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
- /** State updater for lower date with automatic boundary adjustment / 下限日付更新関数 */
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
- /** State updater for upper date with automatic boundary adjustment / 上限日付更新関数 */
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
- /** Shift entire range forward/backward by delta units / 期間幅を維持したまま delta 単位シフト */
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, initialRange: rawInitialRange, defaultRange, minDate, maxDate, onChangeRange, onChangeRangeTuple, onChange, ...restUiProps } = options
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 setLowerDate = useCallback((newLower: Date) => {
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
- let nextUpper = current[1]
116
- if (newLower.getTime() > nextUpper.getTime()) {
117
- nextUpper = newLower
118
- }
119
- const nextRange: [Date, Date] = [newLower, nextUpper]
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 setUpperDate = useCallback((newUpper: Date) => {
127
- const current = rangeRef.current
128
- let nextLower = current[0]
129
- if (newUpper.getTime() < nextLower.getTime()) {
130
- nextLower = newUpper
131
- }
132
- const nextRange: [Date, Date] = [nextLower, newUpper]
133
- setRange(nextRange)
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 handleSliderChange = useCallback((lower: Date, upper: Date) => {
140
- const nextRange: [Date, Date] = [lower, upper]
141
- setRange(nextRange)
142
- onChangeRangeRef.current?.(lower, upper)
143
- onChangeRangeTupleRef.current?.(nextRange)
144
- onChangeRef.current?.(nextRange)
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 handleSliderChangeTuple = useCallback((nextRange: [Date, Date]) => {
148
- setRange(nextRange)
149
- onChangeRangeRef.current?.(nextRange[0], nextRange[1])
150
- onChangeRangeTupleRef.current?.(nextRange)
151
- onChangeRef.current?.(nextRange)
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
- const newLower = addUnit(unit, current[0], delta)
158
- const newUpper = addUnit(unit, current[1], delta)
159
- const clampedLower = clampDate(newLower, minDate, maxDate)
160
- const clampedUpper = clampDate(newUpper, minDate, maxDate)
161
- const nextRange: [Date, Date] = [clampedLower, clampedUpper]
162
- setRange(nextRange)
163
- onChangeRangeRef.current?.(nextRange[0], nextRange[1])
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, minDate, maxDate],
357
+ [unit, emitRange],
168
358
  )
169
359
 
170
360
  const resetRange = useCallback(() => {
171
- const resetVal = initialRangeRef.current
172
- setRange(resetVal)
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
- ...restUiProps,
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
- [restUiProps, unit, range, minDate, maxDate, handleSliderChange, handleSliderChangeTuple],
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" | "value" | "valueDate" | "onChangePoint" | "onChangeValue" | "onChange">> {
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
- /** Initial selected date / 初期選択日 */
238
- initialValue?: Date
239
- /** Initial selected date alias (consistent with selectors) / 初期選択日 (セレクタ連携エイリアス) */
240
- initialDate?: Date
241
- /** Initial selected date alias (consistent with slider) / 初期選択日 (スライダー連携エイリアス) */
242
- defaultValue?: Date
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
- /** Shift point by delta units / 日付を delta 単位シフト */
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, initialValue: rawInitialValue, initialDate, defaultValue, minDate, maxDate, onChangePoint, onChangeValue, onChange, ...restUiProps } = options
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
- const onChangeValueRef = useRef(onChangeValue)
300
- onChangeValueRef.current = onChangeValue
301
- const onChangeRef = useRef(onChange)
302
- onChangeRef.current = onChange
303
-
304
- const handlePointChange = useCallback((nextDate: Date) => {
305
- setValue(nextDate)
306
- onChangePointRef.current?.(nextDate)
307
- onChangeValueRef.current?.(nextDate)
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 current = valueRef.current
314
- const newDate = addUnit(unit, current, delta)
315
- const clamped = clampDate(newDate, minDate, maxDate)
316
- setValue(clamped)
317
- onChangePointRef.current?.(clamped)
318
- onChangeValueRef.current?.(clamped)
319
- onChangeRef.current?.(clamped)
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, minDate, maxDate],
526
+ [unit, emitValue],
322
527
  )
323
528
 
324
529
  const resetValue = useCallback(() => {
325
- const resetVal = initialValueRef.current
326
- setValue(resetVal)
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: handlePointChange,
536
+ onChange: emitValue,
336
537
  minDate,
337
538
  maxDate,
338
539
  unit,
339
540
  }),
340
- [value, handlePointChange, minDate, maxDate, unit],
541
+ [value, emitValue, minDate, maxDate, unit],
341
542
  )
342
543
 
343
544
  const sliderProps = useMemo<PeriodSliderPointProps>(
344
545
  () => ({
345
- ...restUiProps,
546
+ ...uiProps,
346
547
  mode: "point",
347
548
  unit,
348
549
  value,
349
550
  minDate,
350
551
  maxDate,
351
- onChangePoint: handlePointChange,
352
- onChangeValue: handlePointChange,
353
- onChange: handlePointChange,
552
+ onChangePoint: emitValue,
354
553
  }),
355
- [restUiProps, unit, value, minDate, maxDate, handlePointChange],
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
- extends Partial<
374
- Omit<PeriodSliderVernierProps, "mode" | "minDate" | "maxDate" | "macroRange" | "microRange" | "onChangeMacroRange" | "onChangeMacroRangeTuple" | "onChangeMacro" | "onChangeRange" | "onChangeRangeTuple" | "onChangeMicroRange" | "onChangeMicroRangeTuple" | "onChangeMicro">
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?: [Date, Date]
382
- /** Initial macro window range alias / 初期マクロ窓期間 (エイリアス) */
383
- defaultMacroRange?: [Date, Date]
384
- /** Initial micro selected range [lower, upper] / 初期ミクロ選択期間 */
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
- /** Set macro lower date / マクロ開始日更新 */
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
- /** Set macro upper date / マクロ終了日更新 */
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
- /** Set micro lower date / ミクロ開始日更新 */
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
- /** Set micro upper date / ミクロ終了日更新 */
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
- /** Shift macro range by delta units / マクロ窓をシフト */
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
- /** Shift micro range by delta units / ミクロ選択範囲をシフト */
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
- minDate,
467
- maxDate,
468
- initialMacroRange,
469
- defaultMacroRange,
470
- initialMicroRange,
471
- defaultMicroRange,
472
- unit = "month",
473
- macroUnit = unit,
474
- microUnit = unit,
475
- onChangeMacroRange,
476
- onChangeMacroRangeTuple,
477
- onChangeMacro,
478
- onChangeRange,
479
- onChangeRangeTuple,
480
- onChangeMicroRange,
481
- onChangeMicroRangeTuple,
482
- onChangeMicro,
483
- ...restUiProps
484
- } = options
485
-
486
- const resolvedInitialMacroRange: [Date, Date] = initialMacroRange ?? defaultMacroRange ?? [minDate, maxDate]
487
- const resolvedInitialMicroRange: [Date, Date] = initialMicroRange ?? defaultMicroRange ?? resolvedInitialMacroRange
488
-
489
- const initialMacroRef = useRef<[Date, Date]>(resolvedInitialMacroRange)
490
- const initialMicroRef = useRef<[Date, Date]>(resolvedInitialMicroRange)
491
-
492
- const [macroRange, setMacroRange] = useState<[Date, Date]>(resolvedInitialMacroRange)
493
- const [microRange, setMicroRange] = useState<[Date, Date]>(resolvedInitialMicroRange)
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
- setMacroRange([lower, upper])
502
- onChangeMacroRange?.(lower, upper)
503
- onChangeMacroRangeTuple?.([lower, upper])
504
- onChangeMacro?.([lower, upper])
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
- [onChangeMacroRange, onChangeMacroRangeTuple, onChangeMacro],
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
- setMicroRange([lower, upper])
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
- [onChangeRange, onChangeRangeTuple, onChangeMicroRange, onChangeMicroRangeTuple, onChangeMicro],
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(nextLower, nextUpper)
737
+ handleChangeMacroRange(date, nextUpper)
541
738
  },
542
- [minDate, handleChangeMacroRange],
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, nextUpper)
746
+ handleChangeMacroRange(nextLower, date)
551
747
  },
552
- [maxDate, handleChangeMacroRange],
748
+ [handleChangeMacroRange],
553
749
  )
554
750
 
555
751
  const setMicroLowerDate = useCallback(
556
752
  (date: Date) => {
557
- const currentMacro = macroRangeRef.current
558
- const currentMicro = microRangeRef.current
559
- const nextLower = date < currentMacro[0] ? currentMacro[0] : date
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 currentMacro = macroRangeRef.current
569
- const currentMicro = microRangeRef.current
570
- const nextUpper = date > currentMacro[1] ? currentMacro[1] : date
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
- if (shiftedLow < minDate || shiftedHigh > maxDate) return
775
+ // 窓幅を保つため、片側でも境界を越えるシフトは全体を中止する
776
+ if (shiftedLow < domainLower || shiftedHigh > domainUpper) return
583
777
  handleChangeMacroRange(shiftedLow, shiftedHigh)
584
778
  },
585
- [macroUnit, minDate, maxDate, handleChangeMacroRange],
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
- if (shiftedLow < currentMacro[0] || shiftedHigh > currentMacro[1]) return
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 [initMacroLow, initMacroHigh] = initialMacroRef.current
602
- const [initMicroLow, initMicroHigh] = initialMicroRef.current
603
- handleChangeMacroRange(initMacroLow, initMacroHigh)
604
- handleChangeMicroRange(initMicroLow, initMicroHigh)
605
- }, [handleChangeMacroRange, handleChangeMicroRange])
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: macroRange[1],
840
+ maxDate: macroWindowEnd,
646
841
  unit: microUnit,
647
842
  }),
648
- [microRange, setMicroUpperDate, macroRange, microUnit],
843
+ [microRange, setMicroUpperDate, macroWindowEnd, microUnit],
649
844
  )
650
845
 
651
846
  const sliderProps: PeriodSliderVernierProps = useMemo(
652
847
  () => ({
653
- ...restUiProps,
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
- [restUiProps, unit, macroUnit, microUnit, minDate, maxDate, macroRange, microRange, handleChangeMacroRange, handleChangeMacroRangeTuple, handleChangeMicroRange, handleChangeMicroRangeTuple],
860
+ [uiProps, unit, macroUnit, microUnit, minDate, maxDate, macroRange, microRange, handleChangeMacroRange, handleChangeMicroRange],
672
861
  )
673
862
 
674
863
  return {