@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.
@@ -1,25 +1,60 @@
1
+ /**
2
+ * Period slider component: range, point and vernier dual-scale date selection on a single track.
3
+ * 1 本のトラック上で期間・時点・ノギス 2 段スケールの日付選択を行うコンポーネント本体。
4
+ *
5
+ * Holds the pure date encoding and geometry utilities shared by every mode, together with the
6
+ * memoized React component and its prop-equality comparator.
7
+ * 全モード共通の純粋な日付エンコード・幾何計算ユーティリティと、メモ化済み React コンポーネント本体および Props 比較器を収録。
8
+ */
9
+ import { addDays, addMonths, addYears } from "date-fns"
1
10
  import type React from "react"
2
11
  import { type CSSProperties, memo, useCallback, useEffect, useId, useMemo, useRef, useState } from "react"
3
- import "./styles/period-slider.css"
4
12
 
5
13
  // ======================================================================
6
14
  // 1. Core Domain Types & Public Interfaces
7
15
  // ======================================================================
8
16
 
17
+ /**
18
+ * Time resolution the slider domain is quantized to.
19
+ * スライダー定義域を量子化する時間解像度単位。
20
+ */
9
21
  export type PeriodSliderUnit = "year" | "month" | "day"
22
+
23
+ /**
24
+ * Side of the track the handle labels are placed on.
25
+ * つまみラベルを配置するトラックの側。
26
+ */
10
27
  export type PeriodSliderLabelPosition = "top" | "bottom"
11
28
 
29
+ /**
30
+ * Layout strategy used to place discrete allowed dates along the track.
31
+ * 離散候補日付をトラック上へ配置する方式。
32
+ *
33
+ * - "index": every allowed date occupies an equal share of the track / 候補日付を等間隔配置
34
+ * - "time": every allowed date is placed proportionally to elapsed time / 候補日付を実時間比例配置
35
+ */
36
+ export type PeriodSliderSnapMode = "index" | "time"
37
+
12
38
  /**
13
39
  * Color theme preset for PeriodSlider.
14
40
  * スライダーの配色テーマプリセット。
15
41
  */
16
42
  export type PeriodSliderColorScheme = "blue-rose" | "indigo-amber" | "teal-emerald" | "violet-fuchsia" | "slate-sky" | "monochrome"
17
43
 
44
+ /**
45
+ * Five colors one colorScheme preset paints the rails, knobs and glows with.
46
+ * 1 つの colorScheme プリセットがレール・つまみ・グローへ与える 5 色。
47
+ */
18
48
  export interface ColorSchemePalette {
49
+ /** Macro rail base color / マクロレールの基調色 */
19
50
  macro: string
51
+ /** Macro rail highlight color / マクロレールの明色 */
20
52
  macroLight: string
53
+ /** Micro rail base color / ミクロレールの基調色 */
21
54
  micro: string
55
+ /** Micro rail highlight color / ミクロレールの明色 */
22
56
  microLight: string
57
+ /** Accent color of knobs and the connect bar / つまみと接続バーのアクセント色 */
23
58
  accent: string
24
59
  }
25
60
 
@@ -72,187 +107,195 @@ export const COLOR_SCHEME_PALETTES: Record<PeriodSliderColorScheme, ColorSchemeP
72
107
  },
73
108
  }
74
109
 
110
+ /**
111
+ * Geometry the label anti-collision solver works from.
112
+ * ラベル衝突回避計算が前提とする幾何情報。
113
+ *
114
+ * The label width is a rendering result, never a constant: it changes with the formatter, the locale
115
+ * and the consumer's font, so it has no default and an absent value means "not measured yet".
116
+ * ラベル幅はフォーマッタ・ロケール・利用側フォントで変わる描画結果であり定数ではないため既定値を持たず、未指定は「未実測」の意。
117
+ */
75
118
  export interface LabelSlantConfig {
76
- /** Estimated width of the label in pixels / ラベルの推定横幅(ピクセル) */
119
+ /** Measured border-box width of the rendered label in pixels; absent disables slanting / 実測したラベルのボーダーボックス幅 (ピクセル、未指定時は傾斜を行わない) */
77
120
  estimatedWidthPx?: number
78
- /** Estimated height (thickness) of the label in pixels / ラベルの推定高さ・厚み(ピクセル) */
121
+ /** Measured border-box height (thickness) of the rendered label in pixels (default: 16) / 実測したラベルのボーダーボックス高さ・厚み (ピクセル、既定: 16) */
79
122
  estimatedHeightPx?: number
80
- /** Extra clearance gap in pixels / 衝突検知時の余白マージン(ピクセル) */
123
+ /** Extra clearance gap in pixels (default: 12) / 衝突検知時の余白マージン (ピクセル、既定: 12) */
81
124
  paddingPx?: number
82
- /** Maximum slant angle in degrees (default: 90) / 最大傾斜角度(度、既定: 90) */
125
+ /** Maximum slant angle in degrees (default: 90) / 最大傾斜角度 (度、既定: 90) */
83
126
  maxAngleDeg?: number
84
- /** Clearance from handle center in Y axis (pixels, default: 18) / つまみ中心とのY軸クリアランス(ピクセル、既定: 18) */
127
+ /** Clearance between the knob edge and the label edge in Y axis (pixels, default: 2) / つまみ外縁とラベル外縁の Y 軸クリアランス (ピクセル、既定: 2) */
85
128
  anchorGapY?: number
86
129
  }
87
130
 
131
+ /**
132
+ * Placement the anti-collision solver resolved for the two handle labels.
133
+ * 衝突回避計算が解決した 2 つのつまみラベルの配置。
134
+ */
88
135
  export interface LabelSlantResult {
89
- /** Low handle label angle in degrees (e.g., -90 to 0 for top) */
136
+ /** Low handle label angle in degrees, negative above the track / 下限つまみラベルの回転角 (度、上側配置では負) */
90
137
  lowAngleDeg: number
91
- /** High handle label angle in degrees (e.g., -90 to 0 for top) */
138
+ /** High handle label angle in degrees, negative above the track / 上限つまみラベルの回転角 (度、上側配置では負) */
92
139
  highAngleDeg: number
93
- /** Low handle horizontal shift in pixels */
140
+ /** Low handle horizontal shift in pixels / 下限つまみラベルの水平移動量 (ピクセル) */
94
141
  lowOffsetX: number
95
- /** High handle horizontal shift in pixels */
142
+ /** High handle horizontal shift in pixels / 上限つまみラベルの水平移動量 (ピクセル) */
96
143
  highOffsetX: number
97
- /** Low handle vertical shift in pixels (maintains boundary clearance) */
144
+ /** Low handle vertical shift in pixels, keeping the knob clearance / 下限つまみラベルの垂直移動量 (ピクセル、つまみクリアランス維持) */
98
145
  lowOffsetY: number
99
- /** High handle vertical shift in pixels (maintains boundary clearance) */
146
+ /** High handle vertical shift in pixels, keeping the knob clearance / 上限つまみラベルの垂直移動量 (ピクセル、つまみクリアランス維持) */
100
147
  highOffsetY: number
101
- /** True if labels are currently slanted to avoid collision */
148
+ /** True while the labels are rotated to avoid a collision / 衝突回避のため回転中か */
102
149
  isSlanted: boolean
103
- /** Normalized collision proximity factor between 0 and 1 */
150
+ /** Normalized collision proximity between 0 (apart) and 1 (coincident) / 正規化した接近度 (0: 離間、1: 完全一致) */
104
151
  proximity: number
105
152
  }
106
153
 
154
+ /**
155
+ * Accessible names and the screen-reader formatter every slider mode accepts.
156
+ * 全モード共通で受け付けるアクセシブル名とスクリーンリーダー用フォーマッタ。
157
+ *
158
+ * Every default is English: a generic package cannot know the host application's language, so the
159
+ * consumer localises these names. The stepper names are defined by what the button does to the value,
160
+ * never by where it sits, because the same button is drawn left in a horizontal and below in a
161
+ * vertical layout.
162
+ * 既定値は全て英語。汎用パッケージは利用側アプリの言語を知り得ないため翻訳は利用側の責務。
163
+ * ステッパー名は配置ではなく値への作用で定義 (同じボタンが横向きでは左、縦向きでは下に立つため)。
164
+ */
107
165
  export interface AccessibleSliderLabels {
108
- /** Accessible name for lower handle / 下限つまみのアクセシブル名 (既定: "開始時期") */
166
+ /** Accessible name for lower handle / 下限つまみのアクセシブル名 (既定: "Range start" / vernier モードでは "Micro range start") */
109
167
  lowerAriaLabel?: string
110
- /** Accessible name for upper handle / 上限つまみのアクセシブル名 (既定: "終了時期") */
168
+ /** Accessible name for upper handle / 上限つまみのアクセシブル名 (既定: "Range end" / vernier モードでは "Micro range end") */
111
169
  upperAriaLabel?: string
112
- /** Accessible name for single point handle / 単一選択つまみのアクセシブル名 (既定: "選択時期") */
170
+ /** Accessible name for single point handle / 単一選択つまみのアクセシブル名 (既定: "Selected date") */
113
171
  pointAriaLabel?: string
114
- /** Accessible name for macro lower handle / マクロ下限つまみ (既定: "マクロ開始時期") */
172
+ /** Accessible name for macro lower handle / マクロ下限つまみのアクセシブル名 (既定: "Macro range start") */
115
173
  macroLowerAriaLabel?: string
116
- /** Accessible name for macro upper handle / マクロ上限つまみ (既定: "マクロ終了時期") */
174
+ /** Accessible name for macro upper handle / マクロ上限つまみのアクセシブル名 (既定: "Macro range end") */
117
175
  macroUpperAriaLabel?: string
176
+ /** Accessible name for the stepper button moving the value toward minDate / 値を minDate 方向へ動かすステッパーボタンのアクセシブル名 (既定: "Decrease") */
177
+ decreaseAriaLabel?: string
178
+ /** Accessible name for the stepper button moving the value toward maxDate / 値を maxDate 方向へ動かすステッパーボタンのアクセシブル名 (既定: "Increase") */
179
+ increaseAriaLabel?: string
118
180
  /** Human-readable text formatter for screen readers / スクリーンリーダー専用読み上げフォーマッタ */
119
181
  formatAriaValueText?: (date: Date, unit: PeriodSliderUnit) => string
120
182
  }
121
183
 
184
+ /**
185
+ * Props shared by every PeriodSlider mode.
186
+ * 全 PeriodSlider モードが共有する Props。
187
+ */
122
188
  export interface BasePeriodSliderProps extends AccessibleSliderLabels {
189
+ /** Time resolution unit of the slider domain / スライダー定義域の時間解像度単位 */
123
190
  unit: PeriodSliderUnit
124
- minDate?: Date
125
- maxDate?: Date
191
+ /** Minimum selectable boundary date (required, no fallback) / 選択可能下限日付 (必須・フォールバックなし) */
192
+ minDate: Date
193
+ /** Maximum selectable boundary date, strictly later than minDate (required, no fallback) / 選択可能上限日付 (必須・minDate より後・フォールバックなし) */
194
+ maxDate: Date
195
+ /** Discrete snap targets; when supplied the slider resolves to these dates only / 離散スナップ対象日付配列 (指定時はこの日付のみへスナップ) */
126
196
  allowedDates?: Date[]
127
- snapMode?: "index" | "time"
197
+ /** Placement strategy for allowedDates (default: "index") / allowedDates の配置方式 (既定: "index") */
198
+ snapMode?: PeriodSliderSnapMode
199
+ /** Debounce interval in milliseconds for change callbacks (default: 0) / 変更コールバックのデバウンス間隔ミリ秒 (既定: 0) */
128
200
  debounceMs?: number
201
+ /** Disables every pointer and keyboard interaction (default: false) / 全操作の無効化 (既定: false) */
129
202
  disabled?: boolean
203
+ /** Extra class names appended to the root element / ルート要素へ付与する追加クラス名 */
130
204
  className?: string
131
205
  /** Custom inline styles / カスタムインラインスタイル (CSS変数の直接注入等) */
132
206
  style?: React.CSSProperties
207
+ /** Shows the previous/next stepper buttons (default: true) / 前後ステッパーボタンの表示 (既定: true) */
133
208
  showStepper?: boolean
209
+ /** Tooltip display strategy (default: "always") / ツールチップ表示方式 (既定: "always") */
134
210
  tooltipStyle?: "always" | "hover" | "balloon"
135
211
  /** Label position: "top" (default) or "bottom" / ラベル表示位置("top": 上側 [既定], "bottom": 下側) */
136
212
  labelPosition?: PeriodSliderLabelPosition
137
213
  /** Whether to automatically slant labels when close in range mode (default: true) / Rangeモードで接近時に自動斜め表示するか(既定: true) */
138
214
  autoSlantLabels?: boolean
139
- /** Alias for autoSlantLabels / autoSlantLabels のエイリアス */
140
- preventCollisionSlant?: boolean
215
+ /** Renders the slider along the vertical axis (default: false) / 垂直方向レイアウト (既定: false) */
141
216
  isVertical?: boolean
217
+ /** Hides the connect bar drawn between the two handles (default: false) / つまみ間の接続バー非表示 (既定: false) */
142
218
  hideConnectBar?: boolean
219
+ /** Renders one tick per allowed date in discrete mode (default: false) / 離散モード時の目盛り点描画 (既定: false) */
143
220
  showTicks?: boolean
221
+ /** Custom label formatter for handles and tooltips / つまみ・ツールチップ用カスタム日付フォーマッタ */
144
222
  formatLabel?: (date: Date) => string
145
- /** Color scheme theme preset for slider rails and handles (default: "blue-rose") / スライダーのカラーテーマプリセット(既定: "blue-rose") */
223
+ /** BCP 47 language tag selecting Intl built-in label formatting; omitted keeps every built-in label on locale-independent ISO 8601 / 組み込みラベルを Intl 書式にする BCP 47 言語タグ (未指定時はロケール非依存の ISO 8601 表記) */
224
+ locale?: string
225
+ /** Color scheme theme preset for slider rails and handles (default: "blue-rose") / スライダーのカラーテーマプリセット (既定: "blue-rose") */
146
226
  colorScheme?: PeriodSliderColorScheme
147
227
  }
148
228
 
229
+ /**
230
+ * Props of the two-handle range mode.
231
+ * 2 つのつまみで期間を選ぶ range モードの Props。
232
+ */
149
233
  export interface PeriodSliderRangeProps extends BasePeriodSliderProps {
234
+ /** Two-handle range selection mode / 2 つのつまみによる期間選択モード */
150
235
  mode: "range"
151
- /** Selected date range tuple [lower, upper] / 選択期間タプル (優先指定) */
236
+ /** Controlled selected date range tuple [lower, upper] / 制御時の選択期間タプル */
152
237
  range?: [Date, Date]
153
- /** Lower boundary date of selected range / 選択期間の開始日付 */
154
- lowerDate?: Date
155
- /** Upper boundary date of selected range / 終了期間の終了日付 */
156
- upperDate?: Date
157
238
  /** Initial date range tuple for uncontrolled usage / 非制御時の初期選択期間タプル */
158
239
  defaultRange?: [Date, Date]
159
- /** Initial date range tuple alias / 非制御時の初期選択期間タプル (エイリアス) */
160
- initialRange?: [Date, Date]
161
- /** Initial lower date for uncontrolled usage / 非制御時の初期開始日付 */
162
- defaultLowerDate?: Date
163
- /** Initial lower date alias / 非制御時の初期開始日付 (エイリアス) */
164
- initialLowerDate?: Date
165
- /** Initial upper date for uncontrolled usage / 非制御時の初期終了日付 */
166
- defaultUpperDate?: Date
167
- /** Initial upper date alias / 非制御時の初期終了日付 (エイリアス) */
168
- initialUpperDate?: Date
169
- /** Callback triggered when range changes / 期間変更時コールバック */
240
+ /** Callback triggered when the selected range changes / 期間変更時コールバック */
170
241
  onChangeRange?: (lower: Date, upper: Date) => void
171
- /** Callback triggered with tuple [lower, upper] when range changes / 期間変更時タプルコールバック */
172
- onChangeRangeTuple?: (range: [Date, Date]) => void
173
- /** Standard tuple callback alias / 標準タプルコールバック */
174
- onChange?: (range: [Date, Date]) => void
242
+
243
+ // 他モード専用 Props の相互排他マーカー (range モードでは指定不可)
175
244
  value?: never
176
- valueDate?: never
245
+ defaultValue?: never
177
246
  onChangePoint?: never
178
- onChangeValue?: never
179
247
  macroRange?: never
180
248
  onChangeMacroRange?: never
181
249
  microRange?: never
250
+ defaultMicroRange?: never
251
+ onChangeMicroRange?: never
182
252
  }
183
253
 
254
+ /**
255
+ * Props of the single-handle point mode.
256
+ * 単一つまみで時点を選ぶ point モードの Props。
257
+ */
184
258
  export interface PeriodSliderPointProps extends BasePeriodSliderProps {
259
+ /** Single-handle point selection mode / 単一つまみによる時点選択モード */
185
260
  mode: "point"
186
- /** Selected point date / 選択日付 */
261
+ /** Controlled selected point date / 制御時の選択日付 */
187
262
  value?: Date
188
- /** Selected point date (legacy alias) / 選択日付(エイリアス) */
189
- valueDate?: Date
190
263
  /** Initial point date for uncontrolled usage / 非制御時の初期選択日付 */
191
264
  defaultValue?: Date
192
- /** Initial point date alias / 非制御時の初期選択日付 (セレクタ群と統一) */
193
- initialDate?: Date
194
- /** Callback triggered when point changes / ポイント変更時コールバック */
265
+ /** Callback triggered when the selected point changes / ポイント変更時コールバック */
195
266
  onChangePoint?: (value: Date) => void
196
- /** Callback triggered when point changes (alias) / ポイント変更時コールバック(エイリアス) */
197
- onChangeValue?: (value: Date) => void
198
- /** Standard Date callback alias / 標準日付コールバック */
199
- onChange?: (value: Date) => void
267
+
268
+ // 他モード専用 Props の相互排他マーカー (point モードでは指定不可)
200
269
  range?: never
201
- lowerDate?: never
202
- upperDate?: never
270
+ defaultRange?: never
203
271
  onChangeRange?: never
204
- onChangeRangeTuple?: never
205
272
  macroRange?: never
206
273
  onChangeMacroRange?: never
207
274
  microRange?: never
275
+ defaultMicroRange?: never
276
+ onChangeMicroRange?: never
208
277
  }
209
278
 
279
+ /**
280
+ * Props of the vernier mode, where a macro window rail scopes the micro selection rail.
281
+ * マクロ窓レールがミクロ選択レールの定義域となるノギスモードの Props。
282
+ */
210
283
  export interface PeriodSliderVernierProps extends BasePeriodSliderProps {
211
284
  /** Vernier dual-scale integrated mode / ノギス型 2 段スケール一体型モード */
212
285
  mode: "vernier"
213
- /** Minimum selectable boundary date for entire macro range (required, no default) / 全期間マクロの下限日付 (必須) */
214
- minDate: Date
215
- /** Maximum selectable boundary date for entire macro range (required, no default) / 全期間マクロの上限日付 (必須) */
216
- maxDate: Date
217
- /** Macro window range [start, end] / マクロ側の広域表示窓 (必須) */
286
+ /** Controlled macro window range [start, end] / マクロ側の広域表示窓 (必須・制御) */
218
287
  macroRange: [Date, Date]
219
- /** Callback triggered when macro window changes / マクロ窓変更時コールバック */
288
+ /** Callback triggered when the macro window changes / マクロ窓変更時コールバック */
220
289
  onChangeMacroRange?: (lower: Date, upper: Date) => void
221
- /** Callback triggered with tuple [lower, upper] when macro window changes / マクロ窓変更時タプルコールバック */
222
- onChangeMacroRangeTuple?: (range: [Date, Date]) => void
223
- /** Symmetrical alias for macro window changes / マクロ窓変更時コールバック (エイリアス) */
224
- onChangeMacro?: (range: [Date, Date]) => void
225
290
 
226
- /** Micro selected range tuple [lower, upper] / ミクロ側の最終確定期間タプル (優先指定) */
291
+ /** Controlled micro selected range tuple [lower, upper] / 制御時のミクロ選択期間タプル */
227
292
  microRange?: [Date, Date]
228
- /** Micro selected lower date / ミクロ側の最終確定開始日付 */
229
- lowerDate?: Date
230
- /** Micro selected upper date / ミクロ側の最終確定終了日付 */
231
- upperDate?: Date
232
293
  /** Initial micro range tuple for uncontrolled usage / 非制御時の初期ミクロ選択期間タプル */
233
294
  defaultMicroRange?: [Date, Date]
234
- /** Initial micro range tuple alias / 非制御時の初期ミクロ選択期間タプル (エイリアス) */
235
- initialMicroRange?: [Date, Date]
236
- /** Initial lower date for uncontrolled usage / 非制御時の初期ミクロ開始日付 */
237
- defaultLowerDate?: Date
238
- /** Initial lower date alias / 非制御時の初期ミクロ開始日付 (エイリアス) */
239
- initialLowerDate?: Date
240
- /** Initial upper date for uncontrolled usage / 非制御時の初期ミクロ終了日付 */
241
- defaultUpperDate?: Date
242
- /** Initial upper date alias / 非制御時の初期ミクロ終了日付 (エイリアス) */
243
- initialUpperDate?: Date
244
- /** Callback triggered when micro range changes / ミクロ選択範囲変更時コールバック */
245
- onChangeRange?: (lower: Date, upper: Date) => void
246
- /** Callback triggered with tuple [lower, upper] when micro range changes / ミクロ選択範囲変更時タプルコールバック */
247
- onChangeRangeTuple?: (range: [Date, Date]) => void
248
- /** Symmetrical callback for micro range / ミクロ選択範囲変更時コールバック (対称命名) */
295
+ /** Callback triggered when the micro selected range changes / ミクロ選択範囲変更時コールバック */
249
296
  onChangeMicroRange?: (lower: Date, upper: Date) => void
250
- /** Symmetrical tuple callback for micro range / ミクロ選択範囲変更時タプルコールバック (対称命名) */
251
- onChangeMicroRangeTuple?: (range: [Date, Date]) => void
252
- /** Symmetrical alias for micro callback / ミクロ選択範囲変更時コールバック (エイリアス) */
253
- onChangeMicro?: (range: [Date, Date]) => void
254
297
 
255
- /** Vernier scale orientation: "macro-top" (default), "macro-bottom", "macro-left", or "macro-right" / ノギス配置方向 (既定: "macro-top") */
298
+ /** Vernier scale orientation; default is "macro-top" horizontally and "macro-left" when isVertical / ノギス配置方向 (既定: 横向き "macro-top"、isVertical 時 "macro-left") */
256
299
  vernierOrientation?: "macro-top" | "macro-bottom" | "macro-left" | "macro-right"
257
300
  /** Show semi-transparent trapezoid projection cone between macro and micro / 台形プロジェクション光の表示 (既定: true) */
258
301
  showVernierProjection?: boolean
@@ -260,8 +303,6 @@ export interface PeriodSliderVernierProps extends BasePeriodSliderProps {
260
303
  showVernierTicks?: boolean
261
304
  /** Show 1px precision hairline pointer cursor on semicircles / 精密ヘアライン針の表示 (既定: true) */
262
305
  showHairline?: boolean
263
- /** Adaptive zoom expansion animation toggle / 自動適応ズーム展開アニメーション (既定: false) */
264
- adaptiveExpand?: boolean
265
306
 
266
307
  /** Macro scale unit (defaults to props.unit) / マクロ側の単位 (既定: props.unit) */
267
308
  macroUnit?: PeriodSliderUnit
@@ -280,25 +321,57 @@ export interface PeriodSliderVernierProps extends BasePeriodSliderProps {
280
321
  /** Custom label formatter for micro handles and tooltip / ミクロ用カスタム日付フォーマッタ */
281
322
  formatMicroLabel?: (date: Date) => string
282
323
 
324
+ // 他モード専用 Props の相互排他マーカー (vernier モードでは指定不可)
283
325
  range?: never
326
+ defaultRange?: never
327
+ onChangeRange?: never
284
328
  value?: never
285
- valueDate?: never
329
+ defaultValue?: never
286
330
  onChangePoint?: never
287
- onChangeValue?: never
288
331
  }
289
332
 
333
+ /**
334
+ * Discriminated union of every PeriodSlider mode, keyed by the mode prop.
335
+ * mode Props を判別子とする全 PeriodSlider モードの判別可能合併型。
336
+ */
290
337
  export type PeriodSliderProps = PeriodSliderRangeProps | PeriodSliderPointProps | PeriodSliderVernierProps
291
338
 
292
339
  // ======================================================================
293
340
  // 2. Pure Date & Math Utilities
294
341
  // ======================================================================
295
342
 
343
+ /**
344
+ * Type guard telling whether a value is a Date carrying a representable instant.
345
+ * 値が表現可能な時刻を保持する Date かどうかを判定する型ガード。
346
+ *
347
+ * @param value - Candidate value / 判定対象の値
348
+ * @returns True when value is a Date and not an Invalid Date / Date かつ Invalid Date でない場合に true
349
+ */
350
+ const isValidDate = (value: unknown): value is Date => value instanceof Date && !Number.isNaN(value.getTime())
351
+
352
+ /**
353
+ * Renders an arbitrary value as a short diagnostic string for error messages.
354
+ * 例外メッセージ用に任意の値を短い診断文字列へ整形する関数。
355
+ *
356
+ * @param value - Value to describe / 整形対象の値
357
+ * @returns ISO string for a valid Date, "Invalid Date", or the stringified value / 有効な Date は ISO 文字列、無効な Date は "Invalid Date"、それ以外は文字列化した値
358
+ */
359
+ const describeDateValue = (value: unknown): string => {
360
+ if (value instanceof Date) return Number.isNaN(value.getTime()) ? "Invalid Date" : value.toISOString()
361
+ return String(value)
362
+ }
363
+
296
364
  /**
297
365
  * Normalizes a date to the start of the specified unit.
298
366
  * 指定した単位 (year, month, day) の先頭に日付を正規化します。
367
+ *
368
+ * @param unit - Time resolution unit / 時間解像度単位
369
+ * @param d - Date to normalize / 正規化対象の日付
370
+ * @returns New Date pinned to the start of the unit / 単位先頭に揃えた新しい Date
371
+ * @throws RangeError when d is absent or an Invalid Date / d が未指定または Invalid Date の場合
299
372
  */
300
373
  export const normalizeDateByUnit = (unit: PeriodSliderUnit, d: Date): Date => {
301
- if (!d || Number.isNaN(d.getTime())) return new Date()
374
+ if (!isValidDate(d)) throw new RangeError(`normalizeDateByUnit: d must be a valid Date (received: ${describeDateValue(d)})`)
302
375
  const normalized = new Date(d.getTime())
303
376
  if (unit === "year") {
304
377
  normalized.setMonth(0, 1)
@@ -315,9 +388,13 @@ export const normalizeDateByUnit = (unit: PeriodSliderUnit, d: Date): Date => {
315
388
  /**
316
389
  * Encodes a normalized date into a numeric integer key for efficient comparison.
317
390
  * 日付を比較用数値キーにエンコードします。
391
+ *
392
+ * @param unit - Time resolution unit / 時間解像度単位
393
+ * @param d - Date to encode / エンコード対象の日付
394
+ * @returns Integer key that is strictly monotonic in time for the given unit / 単位ごとに時間について厳密単調な整数キー
395
+ * @throws RangeError when d is absent or an Invalid Date / d が未指定または Invalid Date の場合
318
396
  */
319
397
  export const encode = (unit: PeriodSliderUnit, d: Date): number => {
320
- if (!d || Number.isNaN(d.getTime())) return 0
321
398
  const norm = normalizeDateByUnit(unit, d)
322
399
  const y = norm.getFullYear()
323
400
  const m = norm.getMonth() + 1
@@ -331,6 +408,10 @@ export const encode = (unit: PeriodSliderUnit, d: Date): number => {
331
408
  /**
332
409
  * Decodes a numeric integer key back to a normalized Date object.
333
410
  * エンコードされた数値キーから Date オブジェクトを復元します。
411
+ *
412
+ * @param unit - Time resolution unit the key was produced with / キー生成時の時間解像度単位
413
+ * @param val - Encoded integer key / エンコード済み整数キー
414
+ * @returns Date pinned to the start of the encoded unit / エンコード単位の先頭に揃えた Date
334
415
  */
335
416
  export const decode = (unit: PeriodSliderUnit, val: number): Date => {
336
417
  if (unit === "year") return new Date(val, 0, 1)
@@ -344,15 +425,21 @@ export const decode = (unit: PeriodSliderUnit, val: number): Date => {
344
425
  }
345
426
 
346
427
  /**
347
- * Adds or subtracts units from a given date.
348
- * 日付に対して単位数を加減算します。
428
+ * Adds or subtracts units from a given date, clamping the day of month to the target month length.
429
+ * 日付に対して単位数を加減算します (月末日は加算先の月の末日に丸め)。
430
+ *
431
+ * @param unit - Time resolution unit to step by / 加減算する時間解像度単位
432
+ * @param d - Base date / 起点日付
433
+ * @param amount - Signed number of units to add / 加減算する単位数 (符号付き)
434
+ * @returns New Date advanced by amount units / amount 単位進めた新しい Date
435
+ * @throws RangeError when d is absent or an Invalid Date / d が未指定または Invalid Date の場合
349
436
  */
350
437
  export const addUnit = (unit: PeriodSliderUnit, d: Date, amount: number): Date => {
351
- const res = new Date(d.getTime())
352
- if (unit === "year") res.setFullYear(res.getFullYear() + amount)
353
- else if (unit === "month") res.setMonth(res.getMonth() + amount)
354
- else res.setDate(res.getDate() + amount)
355
- return res
438
+ if (!isValidDate(d)) throw new RangeError(`addUnit: d must be a valid Date (received: ${describeDateValue(d)})`)
439
+ // setMonth / setFullYear は 31 日起点で桁溢れし 2 か月先へ飛ぶため、月末丸めを行う date-fns を使う
440
+ if (unit === "year") return addYears(d, amount)
441
+ if (unit === "month") return addMonths(d, amount)
442
+ return addDays(d, amount)
356
443
  }
357
444
 
358
445
  /**
@@ -365,9 +452,10 @@ export const addUnit = (unit: PeriodSliderUnit, d: Date, amount: number): Date =
365
452
  * @param microUnit - Micro scale unit / ミクロ側の時間解像度単位
366
453
  * @param d - Macro range end date / マクロ範囲の終了日付
367
454
  * @returns Corrected boundary Date in micro unit resolution / 補正後のミクロ解像度終了日付
455
+ * @throws RangeError when d is absent or an Invalid Date / d が未指定または Invalid Date の場合
368
456
  */
369
457
  export const getMacroWindowEndDate = (macroUnit: PeriodSliderUnit, microUnit: PeriodSliderUnit, d: Date): Date => {
370
- if (!d || Number.isNaN(d.getTime())) return new Date()
458
+ if (!isValidDate(d)) throw new RangeError(`getMacroWindowEndDate: d must be a valid Date (received: ${describeDateValue(d)})`)
371
459
  if (macroUnit === microUnit) {
372
460
  return normalizeDateByUnit(microUnit, d)
373
461
  }
@@ -388,43 +476,105 @@ export const getMacroWindowEndDate = (macroUnit: PeriodSliderUnit, microUnit: Pe
388
476
  }
389
477
 
390
478
  /**
391
- * Formats a Date object into a readable localized string.
392
- * 日付を表示用文字列にフォーマットします。
479
+ * Intl option set each unit is formatted with once a locale is supplied.
480
+ * ロケール指定時に各単位を書式化する Intl オプション集合。
393
481
  */
394
- export const formatLabel = (unit: PeriodSliderUnit, d: Date, customFormat?: (date: Date) => string): string => {
395
- if (!d || Number.isNaN(d.getTime())) return ""
396
- if (customFormat) return customFormat(d)
397
- const y = d.getFullYear()
398
- const m = String(d.getMonth() + 1).padStart(2, "0")
482
+ const INTL_OPTIONS_BY_UNIT: Record<PeriodSliderUnit, Intl.DateTimeFormatOptions> = {
483
+ year: { year: "numeric" },
484
+ month: { year: "numeric", month: "2-digit" },
485
+ day: { year: "numeric", month: "2-digit", day: "2-digit" },
486
+ }
487
+
488
+ /** Formatters already built, keyed by unit and locale / 構築済みフォーマッタのキャッシュ (単位とロケールが鍵) */
489
+ const dateTimeFormatCache = new Map<string, Intl.DateTimeFormat>()
490
+
491
+ /**
492
+ * Returns the Intl formatter for a unit and locale, building each combination once.
493
+ * 単位とロケールの組ごとに 1 度だけ構築した Intl フォーマッタの取得。
494
+ *
495
+ * @param unit - Time resolution unit selecting the option set / オプション集合を選ぶ時間解像度単位
496
+ * @param locale - BCP 47 language tag / BCP 47 言語タグ
497
+ * @returns Formatter bound to the unit and locale / 単位とロケールに束縛されたフォーマッタ
498
+ * @throws RangeError when locale is not a structurally valid BCP 47 tag / locale が構造的に妥当な BCP 47 タグでない場合
499
+ */
500
+ const getDateTimeFormat = (unit: PeriodSliderUnit, locale: string): Intl.DateTimeFormat => {
501
+ // 言語タグに現れ得ない NUL を区切りに使い、単位とタグの境界が曖昧になる鍵衝突を避ける
502
+ const cacheKey = `${unit}\u0000${locale}`
503
+ const cached = dateTimeFormatCache.get(cacheKey)
504
+ if (cached !== undefined) return cached
505
+ const formatter = new Intl.DateTimeFormat(locale, INTL_OPTIONS_BY_UNIT[unit])
506
+ dateTimeFormatCache.set(cacheKey, formatter)
507
+ return formatter
508
+ }
509
+
510
+ /**
511
+ * Renders a date as a locale-independent ISO 8601 calendar string at the given unit.
512
+ * 指定単位における日付の ISO 8601 暦表記 (ロケール非依存) を生成する関数。
513
+ *
514
+ * @param unit - Time resolution unit deciding the precision / 精度を決める時間解像度単位
515
+ * @param d - Valid date to render / 表記対象の有効な日付
516
+ * @returns "2025" for year, "2025-01" for month, "2025-01-15" for day / year は "2025"、month は "2025-01"、day は "2025-01-15"
517
+ */
518
+ const formatIsoByUnit = (unit: PeriodSliderUnit, d: Date): string => {
519
+ const year = String(d.getFullYear()).padStart(4, "0")
520
+ if (unit === "year") return year
521
+ const month = String(d.getMonth() + 1).padStart(2, "0")
522
+ if (unit === "month") return `${year}-${month}`
399
523
  const day = String(d.getDate()).padStart(2, "0")
400
- if (unit === "year") return `${y}年`
401
- if (unit === "month") return `${y}年${m}月`
402
- return `${y}年${m}月${day}日`
524
+ return `${year}-${month}-${day}`
403
525
  }
404
526
 
405
527
  /**
406
- * Generates an accessible, human-friendly label for screen readers.
407
- * スクリーンリーダー向けの自然言語アクセシブルラベルを生成します。
528
+ * Formats a date for handle labels and tooltips.
529
+ * つまみラベル・ツールチップ用の日付文字列を生成する関数。
408
530
  *
409
- * @param unit - The time unit of the slider
410
- * @param d - The target date
411
- * @param customFormat - Optional custom formatter
412
- * @returns Human-friendly string (e.g. "2026年 9月 11日")
531
+ * Resolution order: customFormat wins; otherwise a supplied locale selects Intl.DateTimeFormat, and an
532
+ * omitted locale yields locale-independent ISO 8601. ISO is the specification-defined output of this
533
+ * package, not a convenience fallback: a built-in natural-language default would bake one language
534
+ * into a generic package, and Intl output drifts between ICU versions.
535
+ * 解決順序は customFormat が最優先、次に locale 指定時の Intl.DateTimeFormat、未指定時はロケール非依存の ISO 8601。
536
+ * ISO 表記は本パッケージの仕様上の既定値であり代替値ではない (自然言語既定は汎用パッケージに 1 言語を焼き付け、Intl 出力は ICU 版で揺れるため)。
537
+ *
538
+ * @param unit - Time resolution unit deciding the precision / 精度を決める時間解像度単位
539
+ * @param d - Date to format / 書式化対象の日付
540
+ * @param customFormat - Consumer formatter taking priority over both built-in paths / 組み込み 2 経路より優先される利用側フォーマッタ
541
+ * @param locale - BCP 47 language tag enabling Intl formatting / Intl 書式を有効化する BCP 47 言語タグ
542
+ * @returns Formatted label, or an empty string when d is absent or an Invalid Date / 書式化済みラベル (d が未指定・Invalid Date の場合は空文字列)
543
+ * @throws RangeError when locale is not a structurally valid BCP 47 tag / locale が構造的に妥当な BCP 47 タグでない場合
413
544
  */
414
- export const formatScreenReaderLabel = (unit: PeriodSliderUnit, d: Date, customFormat?: (date: Date) => string): string => {
415
- if (!d || Number.isNaN(d.getTime())) return ""
545
+ export const formatLabel = (unit: PeriodSliderUnit, d: Date, customFormat?: (date: Date) => string, locale?: string): string => {
546
+ if (!isValidDate(d)) return ""
416
547
  if (customFormat) return customFormat(d)
417
- const y = d.getFullYear()
418
- const m = d.getMonth() + 1
419
- const day = d.getDate()
420
- if (unit === "year") return `${y}年`
421
- if (unit === "month") return `${y}年 ${m}月`
422
- return `${y}年 ${m}月 ${day}日`
548
+ if (locale === undefined) return formatIsoByUnit(unit, d)
549
+ return getDateTimeFormat(unit, locale).format(d)
423
550
  }
424
551
 
552
+ /**
553
+ * Formats the date a screen reader announces through aria-valuetext.
554
+ * スクリーンリーダーが aria-valuetext として読み上げる日付文字列を生成する関数。
555
+ *
556
+ * Announcing a different string than the visible label would leave sighted and non-sighted users with
557
+ * two different values, so this delegates to formatLabel and stays its single source of truth.
558
+ * 可視ラベルと別の文字列を読み上げると晴眼者と非晴眼者で値が食い違うため formatLabel へ委譲し単一の真実源を保つ。
559
+ *
560
+ * @param unit - Time resolution unit deciding the precision / 精度を決める時間解像度単位
561
+ * @param d - Date to format / 書式化対象の日付
562
+ * @param customFormat - Consumer formatter taking priority over both built-in paths / 組み込み 2 経路より優先される利用側フォーマッタ
563
+ * @param locale - BCP 47 language tag enabling Intl formatting / Intl 書式を有効化する BCP 47 言語タグ
564
+ * @returns Announced text, or an empty string when d is absent or an Invalid Date / 読み上げ文字列 (d が未指定・Invalid Date の場合は空文字列)
565
+ * @throws RangeError when locale is not a structurally valid BCP 47 tag / locale が構造的に妥当な BCP 47 タグでない場合
566
+ */
567
+ export const formatScreenReaderLabel = (unit: PeriodSliderUnit, d: Date, customFormat?: (date: Date) => string, locale?: string): string => formatLabel(unit, d, customFormat, locale)
568
+
425
569
  /**
426
570
  * Finds the index of the date in a sorted array closest to the target date via binary search.
427
571
  * 昇順ソート済み日付配列の中から、対象日付に最も近い要素のインデックスを二分探索 ($O(\log N)$) で算出します。
572
+ *
573
+ * @param dates - Ascending, unit-normalized date list / 昇順かつ単位正規化済みの日付一覧
574
+ * @param target - Date to locate / 探索対象の日付
575
+ * @param unit - Time resolution unit used for the distance metric / 距離尺度に用いる時間解像度単位
576
+ * @returns Index of the closest entry, or 0 for an empty list / 最近傍要素のインデックス (空配列時は 0)
577
+ * @throws RangeError when target or any inspected entry is an Invalid Date / target または参照した要素が Invalid Date の場合
428
578
  */
429
579
  export const findNearestDateIndex = (dates: Date[], target: Date, unit: PeriodSliderUnit): number => {
430
580
  if (!dates || dates.length === 0) return 0
@@ -455,37 +605,41 @@ export const findNearestDateIndex = (dates: Date[], target: Date, unit: PeriodSl
455
605
  }
456
606
 
457
607
  /**
458
- * Pre-processes, normalizes, deduplicates, and sorts discrete dates.
459
- * 離散日付配列を事前処理・正規化・重複排除・昇順ソートします。
608
+ * Normalizes, deduplicates, sorts and range-restricts the discrete snap targets.
609
+ * Entries outside [minDate, maxDate] are dropped because they are unreachable on the track.
610
+ * 離散日付配列を正規化・重複排除・昇順ソートし、[minDate, maxDate] 外の要素を除外する関数。
611
+ *
612
+ * @param allowedDates - Raw discrete snap targets, or undefined for a continuous slider / 離散候補日付の生配列 (連続スライダー時は undefined)
613
+ * @param unit - Time resolution unit used for normalization and deduplication / 正規化・重複排除に用いる時間解像度単位
614
+ * @param minDate - Lower domain boundary; entries before it are excluded / 定義域下限 (これより前の要素は除外)
615
+ * @param maxDate - Upper domain boundary; entries after it are excluded / 定義域上限 (これより後の要素は除外)
616
+ * @returns Ascending, deduplicated dates inside the domain, or an empty array when allowedDates is absent or empty / 定義域内の昇順・重複排除済み日付 (allowedDates 未指定・空配列時は空配列)
617
+ * @throws RangeError when an entry is an Invalid Date, or when every supplied entry falls outside the domain / 要素が Invalid Date の場合、または全要素が定義域外の場合
460
618
  */
461
- export const getSortedAllowedDates = (allowedDates: Date[] | undefined, unit: PeriodSliderUnit, minDate?: Date, maxDate?: Date): Date[] => {
619
+ export const getSortedAllowedDates = (allowedDates: Date[] | undefined, unit: PeriodSliderUnit, minDate: Date, maxDate: Date): Date[] => {
462
620
  if (!Array.isArray(allowedDates) || allowedDates.length === 0) return []
463
621
 
464
- const validDates = allowedDates.filter((d) => d && !Number.isNaN(d.getTime())).map((d) => normalizeDateByUnit(unit, d))
465
-
466
- if (validDates.length === 0) return []
622
+ const minEnc = encode(unit, minDate)
623
+ const maxEnc = encode(unit, maxDate)
467
624
 
468
625
  const encMap = new Map<number, Date>()
469
- for (const d of validDates) {
470
- const enc = encode(unit, d)
626
+ for (const d of allowedDates) {
627
+ const norm = normalizeDateByUnit(unit, d)
628
+ const enc = encode(unit, norm)
629
+ if (enc < minEnc || enc > maxEnc) continue
471
630
  if (!encMap.has(enc)) {
472
- encMap.set(enc, d)
631
+ encMap.set(enc, norm)
473
632
  }
474
633
  }
475
634
 
476
- const sortedEncs = Array.from(encMap.keys()).sort((a, b) => a - b)
477
- let filteredDates = sortedEncs.map((enc) => encMap.get(enc)).filter((d): d is Date => d !== undefined)
478
-
479
- if (minDate && !Number.isNaN(minDate.getTime())) {
480
- const minEnc = encode(unit, minDate)
481
- filteredDates = filteredDates.filter((d) => encode(unit, d) >= minEnc)
482
- }
483
- if (maxDate && !Number.isNaN(maxDate.getTime())) {
484
- const maxEnc = encode(unit, maxDate)
485
- filteredDates = filteredDates.filter((d) => encode(unit, d) <= maxEnc)
635
+ // 全滅を空配列で返すと呼び出し側が「離散指定なし」と区別できず、連続スライダーへ黙って退化する
636
+ if (encMap.size === 0) {
637
+ throw new RangeError(`getSortedAllowedDates: every allowedDates entry falls outside [minDate, maxDate] (minDate: ${describeDateValue(minDate)}, maxDate: ${describeDateValue(maxDate)}, entries: ${allowedDates.length})`)
486
638
  }
487
639
 
488
- return filteredDates
640
+ return Array.from(encMap.keys())
641
+ .sort((a, b) => a - b)
642
+ .map((enc) => encMap.get(enc) as Date)
489
643
  }
490
644
 
491
645
  /**
@@ -538,38 +692,92 @@ export const getActiveDragHandle = (originalHandle: "low" | "high", pointerVal:
538
692
  }
539
693
 
540
694
  /**
541
- * Computes dragging values when translating/dragging the connection bar.
542
- * 接続バー並進ドラッグ時の数値を算出します。
695
+ * Input bundle for translating a connect-bar drag into a new [lower, upper] value pair.
696
+ * 接続バードラッグを新しい上下限値の組へ変換するための入力一式。
543
697
  */
544
- export const calculateConnectDragValues = (posDiffPct: number, startLowVal: number, startHighVal: number, rangeMin: number, rangeMax: number, isDiscrete: boolean, sortedAllowedDates: Date[]): [number, number] | null => {
545
- const rangeSpan = rangeMax - rangeMin
546
- if (rangeSpan <= 0) return null
698
+ export interface ConnectDragValueOptions {
699
+ /** Pointer translation along the track as a fraction of the full track length / トラック全長に対するポインター移動量の比率 */
700
+ posDiffPct: number
701
+ /** Lower value captured at drag start (encoded date or discrete index) / ドラッグ開始時の下限値 (エンコード値または離散インデックス) */
702
+ startLowVal: number
703
+ /** Upper value captured at drag start (encoded date or discrete index) / ドラッグ開始時の上限値 (エンコード値または離散インデックス) */
704
+ startHighVal: number
705
+ /** Domain lower bound in the same value space / 同一値空間における定義域下限 */
706
+ rangeMin: number
707
+ /** Domain upper bound in the same value space / 同一値空間における定義域上限 */
708
+ rangeMax: number
709
+ /** Whether the slider snaps to discrete allowed dates / 離散候補日付へスナップするか */
710
+ isDiscrete: boolean
711
+ /** Ascending discrete snap targets (empty when not discrete) / 昇順の離散候補日付 (非離散時は空配列) */
712
+ sortedAllowedDates: Date[]
713
+ /** Placement strategy of the discrete snap targets / 離散候補日付の配置方式 */
714
+ snapMode: PeriodSliderSnapMode
715
+ /** Time resolution unit used to resolve the nearest discrete date / 離散最近傍解決に用いる時間解像度単位 */
716
+ unit: PeriodSliderUnit
717
+ }
547
718
 
719
+ /**
720
+ * Computes the [low, high] pair reached by translating the connection bar.
721
+ * The pair is always derived from the values captured at drag start, so returning the pointer to its
722
+ * grab point restores the original range, and "time" snapping preserves the selected duration.
723
+ * 接続バー並進ドラッグ後の [下限, 上限] を算出する関数。開始時の値を基準に毎回再計算するため、
724
+ * ポインターを掴んだ位置へ戻せば元の期間へ復帰し、"time" スナップでは選択期間長を保持。
725
+ *
726
+ * @param options - Drag geometry, domain bounds and snapping configuration / ドラッグ形状・定義域・スナップ設定
727
+ * @returns Clamped [low, high] pair in the slider value space / スライダー値空間へクランプ済みの [下限, 上限]
728
+ */
729
+ export const calculateConnectDragValues = ({ posDiffPct, startLowVal, startHighVal, rangeMin, rangeMax, isDiscrete, sortedAllowedDates, snapMode, unit }: ConnectDragValueOptions): [number, number] => {
548
730
  if (isDiscrete) {
549
- const indexShift = Math.round(posDiffPct * (sortedAllowedDates.length - 1))
550
- if (indexShift === 0) return null
731
+ const maxIdx = sortedAllowedDates.length - 1
732
+ if (maxIdx <= 0) return [0, 0]
733
+
734
+ const startLowIdx = Math.max(0, Math.min(maxIdx, Math.round(startLowVal)))
735
+ const startHighIdx = Math.max(startLowIdx, Math.min(maxIdx, Math.round(startHighVal)))
736
+
737
+ if (snapMode === "time") {
738
+ // 描画・当たり判定が時間比例のため、インデックス平行移動では期間長が伸縮しバーがポインターから離れる
739
+ const firstMs = sortedAllowedDates[0].getTime()
740
+ const lastMs = sortedAllowedDates[maxIdx].getTime()
741
+ const startLowMs = sortedAllowedDates[startLowIdx].getTime()
742
+ const durationMs = sortedAllowedDates[startHighIdx].getTime() - startLowMs
743
+
744
+ let nextLowMs = startLowMs + posDiffPct * (lastMs - firstMs)
745
+ let nextHighMs = nextLowMs + durationMs
746
+ if (nextLowMs < firstMs) {
747
+ nextLowMs = firstMs
748
+ nextHighMs = firstMs + durationMs
749
+ }
750
+ if (nextHighMs > lastMs) {
751
+ nextHighMs = lastMs
752
+ nextLowMs = lastMs - durationMs
753
+ }
551
754
 
552
- let nextLowIdx = startLowVal + indexShift
553
- let nextHighIdx = startHighVal + indexShift
755
+ const lowIdx = findNearestDateIndex(sortedAllowedDates, new Date(nextLowMs), unit)
756
+ const highIdx = findNearestDateIndex(sortedAllowedDates, new Date(nextHighMs), unit)
757
+ return [lowIdx, Math.max(lowIdx, highIdx)]
758
+ }
759
+
760
+ const indexShift = Math.round(posDiffPct * maxIdx)
761
+ let nextLowIdx = startLowIdx + indexShift
762
+ let nextHighIdx = startHighIdx + indexShift
554
763
 
555
764
  if (nextLowIdx < 0) {
556
765
  nextHighIdx += -nextLowIdx
557
766
  nextLowIdx = 0
558
767
  }
559
- if (nextHighIdx > sortedAllowedDates.length - 1) {
560
- nextLowIdx -= nextHighIdx - (sortedAllowedDates.length - 1)
561
- nextHighIdx = sortedAllowedDates.length - 1
768
+ if (nextHighIdx > maxIdx) {
769
+ nextLowIdx -= nextHighIdx - maxIdx
770
+ nextHighIdx = maxIdx
562
771
  }
563
772
 
564
- nextLowIdx = Math.max(0, Math.min(sortedAllowedDates.length - 1, nextLowIdx))
565
- nextHighIdx = Math.max(0, Math.min(sortedAllowedDates.length - 1, nextHighIdx))
566
-
567
- return [nextLowIdx, nextHighIdx]
773
+ return [Math.max(0, Math.min(maxIdx, nextLowIdx)), Math.max(0, Math.min(maxIdx, nextHighIdx))]
568
774
  }
569
775
 
570
- const encDiff = Math.round(posDiffPct * rangeSpan)
571
- if (encDiff === 0) return null
776
+ const clampToDomain = (val: number): number => Math.max(rangeMin, Math.min(rangeMax, val))
777
+ const rangeSpan = rangeMax - rangeMin
778
+ if (rangeSpan <= 0) return [clampToDomain(startLowVal), clampToDomain(startHighVal)]
572
779
 
780
+ const encDiff = Math.round(posDiffPct * rangeSpan)
573
781
  let nextLowEnc = startLowVal + encDiff
574
782
  let nextHighEnc = startHighVal + encDiff
575
783
 
@@ -582,10 +790,7 @@ export const calculateConnectDragValues = (posDiffPct: number, startLowVal: numb
582
790
  nextHighEnc = rangeMax
583
791
  }
584
792
 
585
- nextLowEnc = Math.max(rangeMin, Math.min(rangeMax, nextLowEnc))
586
- nextHighEnc = Math.max(rangeMin, Math.min(rangeMax, nextHighEnc))
587
-
588
- return [nextLowEnc, nextHighEnc]
793
+ return [clampToDomain(nextLowEnc), clampToDomain(nextHighEnc)]
589
794
  }
590
795
 
591
796
  /**
@@ -646,85 +851,108 @@ export const calculateKeyboardActionValues = (key: string, handle: "low" | "high
646
851
  return [targetLow, targetHigh]
647
852
  }
648
853
 
854
+ /** Outer radius of the handle knob in pixels, the surface a label must clear / つまみ外径の半径 (ピクセル、ラベルが避けるべき面) */
855
+ const KNOB_RADIUS_PX = 8
856
+
857
+ /** Visual gap between the knob edge and the label edge in pixels / つまみ外縁とラベル外縁の視覚ギャップ (ピクセル) */
858
+ const DEFAULT_LABEL_ANCHOR_GAP_Y_PX = 2
859
+
860
+ /** Label thickness assumed until the rendered label reports its own height / 描画済みラベルが自身の高さを報告するまで仮定する厚み */
861
+ const DEFAULT_LABEL_HEIGHT_PX = 16
862
+
863
+ /** Clearance kept between the two labels once they are pushed apart in pixels / 押し広げた 2 ラベル間に保つ余白 (ピクセル) */
864
+ const DEFAULT_LABEL_PADDING_PX = 12
865
+
866
+ /** Angle the labels reach when the two handles coincide, in degrees / 2 つのつまみが完全一致した時に到達する角度 (度) */
867
+ const DEFAULT_MAX_SLANT_ANGLE_DEG = 90
868
+
869
+ /**
870
+ * Builds the upright placement both labels take whenever no rotation applies.
871
+ * 回転を行わない場合に両ラベルが取る直立配置を構築する関数。
872
+ *
873
+ * @param labelPosition - Side of the track the labels sit on / ラベルを配置するトラックの側
874
+ * @param config - Optional geometry overrides / 任意の幾何設定
875
+ * @returns Horizontal placement holding the knob clearance / つまみクリアランスを保った水平配置
876
+ */
877
+ const buildHorizontalSlantResult = (labelPosition: PeriodSliderLabelPosition, config?: LabelSlantConfig): LabelSlantResult => {
878
+ const labelHeight = config?.estimatedHeightPx ?? DEFAULT_LABEL_HEIGHT_PX
879
+ const clearance = KNOB_RADIUS_PX + (config?.anchorGapY ?? DEFAULT_LABEL_ANCHOR_GAP_Y_PX)
880
+ const baseCenterDist = clearance + labelHeight / 2
881
+ const baseOffsetY = labelPosition === "top" ? -baseCenterDist : baseCenterDist
882
+
883
+ return {
884
+ lowAngleDeg: 0,
885
+ highAngleDeg: 0,
886
+ lowOffsetX: 0,
887
+ highOffsetX: 0,
888
+ lowOffsetY: baseOffsetY,
889
+ highOffsetY: baseOffsetY,
890
+ isSlanted: false,
891
+ proximity: 0,
892
+ }
893
+ }
894
+
649
895
  /**
650
896
  * Mathematically calculates smooth rotation angle and offsets to prevent label collision in range mode.
651
- * Range モードにおいて、2つのつまみラベルの重複を回避するための滑らかな回転角とオフセットを数学的に計算します。
897
+ * Range モードにおいて、2 つのつまみラベルの重複を回避するための滑らかな回転角とオフセットを数学的に計算する関数。
652
898
  *
653
899
  * Ken Perlin's Smootherstep function S(u) = 6u^5 - 15u^4 + 10u^3 ensures C^2 continuity (smooth acceleration and zero jerk).
654
900
  *
655
- * @param lowPct - Percent position of lower handle (0-100)
656
- * @param highPct - Percent position of upper handle (0-100)
657
- * @param trackWidthPx - Measured pixel width of the track (falls back to 400 if 0 or unavailable)
658
- * @param labelPosition - "top" or "bottom"
659
- * @param unit - "year" | "month" | "day"
660
- * @param config - Optional configuration for fine-tuning
901
+ * Both dimensions the geometry consumes are rendering results, so an unmeasured track or an unmeasured
902
+ * label yields the upright baseline instead of an invented number.
903
+ * 幾何計算が使う 2 つの寸法はいずれも描画結果であるため、トラックまたはラベルが未実測なら数値を捏造せず直立基準値を返す。
904
+ *
905
+ * @param lowPct - Percent position of lower handle (0-100) / 下限つまみの位置 (0-100%)
906
+ * @param highPct - Percent position of upper handle (0-100) / 上限つまみの位置 (0-100%)
907
+ * @param trackWidthPx - Measured pixel width of the track; a non-positive value means "not measured yet" and yields the horizontal baseline / 実測トラック幅 (0 以下は未実測とみなし水平基準値を返す)
908
+ * @param labelPosition - "top" or "bottom" / ラベル表示位置
909
+ * @param config - Geometry of the rendered label; without config.estimatedWidthPx the labels stay upright / 描画済みラベルの幾何情報 (config.estimatedWidthPx が無い場合は直立を維持)
910
+ * @returns Rotation angles and offsets guaranteeing a non-overlapping label pair / ラベルが重ならないことを保証する回転角とオフセット
661
911
  */
662
- export const calculateLabelSlant = (lowPct: number, highPct: number, trackWidthPx: number, labelPosition: PeriodSliderLabelPosition = "top", unit: PeriodSliderUnit = "day", config?: LabelSlantConfig): LabelSlantResult => {
663
- const width = trackWidthPx > 0 ? trackWidthPx : 400
664
- const pixelDistance = (Math.max(0, highPct - lowPct) / 100) * width
665
-
666
- // Unit-based default label widths based on actual rendered dimensions
667
- const defaultWidth = unit === "year" ? 48 : unit === "month" ? 68 : 90
668
- const labelWidth = config?.estimatedWidthPx ?? defaultWidth
669
- const labelHeight = config?.estimatedHeightPx ?? 16
670
- const padding = config?.paddingPx ?? 12
671
- const maxAngle = config?.maxAngleDeg ?? 90
672
-
673
- // Knob radius is 8px (16px knob diameter). Target gap between knob edge and label is 2px.
674
- // Unified baseline clearance from track center: knobRadius (8px) + visualGap (2px) = 10px.
675
- const knobRadius = 8
676
- const visualGap = config?.anchorGapY !== undefined ? config.anchorGapY : 2
677
- const clearance = knobRadius + visualGap
678
-
679
- // Base vertical center offset when horizontal (clearance 10px + labelHeight / 2 = 18px)
680
- const baseCenterDist = clearance + labelHeight / 2
681
- const baseOffsetY = labelPosition === "top" ? -baseCenterDist : baseCenterDist
912
+ export const calculateLabelSlant = (lowPct: number, highPct: number, trackWidthPx: number, labelPosition: PeriodSliderLabelPosition = "top", config?: LabelSlantConfig): LabelSlantResult => {
913
+ const labelWidth = config?.estimatedWidthPx
914
+ const labelHeight = config?.estimatedHeightPx ?? DEFAULT_LABEL_HEIGHT_PX
915
+ const padding = config?.paddingPx ?? DEFAULT_LABEL_PADDING_PX
916
+ const maxAngle = config?.maxAngleDeg ?? DEFAULT_MAX_SLANT_ANGLE_DEG
917
+
918
+ // つまみ外径 16px の半径 8px を起点に、ラベルがつまみへ被らない最小離隔を作る
919
+ const clearance = KNOB_RADIUS_PX + (config?.anchorGapY ?? DEFAULT_LABEL_ANCHOR_GAP_Y_PX)
920
+
921
+ const horizontalResult = buildHorizontalSlantResult(labelPosition, config)
922
+
923
+ // 初回描画・SSR ではトラック未実測 (0)。既定幅を捏造すると実測直後に傾斜が跳ねるため、未知は「傾斜なし」として扱う
924
+ if (!(Number.isFinite(trackWidthPx) && trackWidthPx > 0)) return horizontalResult
925
+
926
+ // ラベル幅は書式・ロケール・フォントで変わる描画結果。単位から推定した定数で代用すると、
927
+ // 実寸との差がそのまま押し出し量の誤差になり、傾けたラベルがトラックへ食い込む
928
+ if (labelWidth === undefined || !Number.isFinite(labelWidth) || labelWidth <= 0) return horizontalResult
929
+
930
+ const pixelDistance = (Math.max(0, highPct - lowPct) / 100) * trackWidthPx
682
931
 
683
- // Threshold distance below which collision avoidance activates
684
932
  const threshold = labelWidth + padding
685
933
 
686
- if (pixelDistance >= threshold) {
687
- return {
688
- lowAngleDeg: 0,
689
- highAngleDeg: 0,
690
- lowOffsetX: 0,
691
- highOffsetX: 0,
692
- lowOffsetY: baseOffsetY,
693
- highOffsetY: baseOffsetY,
694
- isSlanted: false,
695
- proximity: 0,
696
- }
697
- }
934
+ if (pixelDistance >= threshold) return horizontalResult
698
935
 
699
- // Normalized proximity factor u in [0, 1]
700
936
  const u = Math.max(0, Math.min(1, (threshold - pixelDistance) / threshold))
701
937
 
702
- // Ken Perlin's Smootherstep function for continuous C^2 smooth transitions: S(u) = 6u^5 - 15u^4 + 10u^3
938
+ // Smootherstep S(u) = 6u^5 - 15u^4 + 10u^3 は端点で 1 次・2 次微分が 0 となり、傾き始めと傾き切りで角速度が跳ねない
703
939
  const smoothFactor = u * u * u * (u * (u * 6 - 15) + 10)
704
940
 
705
941
  const angle = smoothFactor * maxAngle
706
942
 
707
- // Same direction rotation for both labels:
708
- // Top position: tilts counter-clockwise (upwards) up to -90deg
709
- // Bottom position: tilts clockwise (downwards) up to +90deg
710
943
  const signedAngle = labelPosition === "top" ? -angle : angle
711
944
 
712
- // Mathematically calculate rotated bounding-box half-height: y'max(θ) = (W/2)*|sin θ| + (H/2)*|cos θ|
713
- // The center offset needed when rotated to keep the lowest edge stationary at clearance (10px from track center)
714
- // is (clearance + halfHeightRotated)
945
+ // 回転後の外接矩形の半高は (W/2)|sin θ| + (H/2)|cos θ|。
946
+ // 中心をこの分だけ離隔に足して押し出さないと、傾けた瞬間にラベル下端がつまみへ食い込む
715
947
  const rad = (angle * Math.PI) / 180
716
948
  const halfHeightRotated = (labelWidth / 2) * Math.abs(Math.sin(rad)) + (labelHeight / 2) * Math.abs(Math.cos(rad))
717
949
  const calculatedCenterDist = clearance + halfHeightRotated
718
950
  const calculatedOffsetY = labelPosition === "top" ? -calculatedCenterDist : +calculatedCenterDist
719
951
 
720
- // Parallel slit clearance when approaching 90 degrees:
721
- // When vertical (90 deg), the label's horizontal occupation is labelHeight (16px).
722
- // The required center-to-center clearance between parallel slits is minCenterDist = labelHeight + slitGap (20px).
723
- // If the actual handle distance is smaller than this clearance, distribute the deficit horizontally.
724
- const slitGap = 4
725
- const minCenterDist = labelHeight + slitGap
726
- const deficit = Math.max(0, minCenterDist - pixelDistance)
727
- const shiftX = smoothFactor * (deficit / 2)
952
+ // 同角度で回転した合同な 2 矩形は、中心間距離が回転後の水平占有幅 W*|cos θ| + H*|sin θ| 以上になった時点で
953
+ // 分離軸定理より必ず分離する。角度ランプだけでは中間距離帯で重なるため、不足分を左右へ等分して押し広げる
954
+ const rotatedFootprint = labelWidth * Math.abs(Math.cos(rad)) + labelHeight * Math.abs(Math.sin(rad))
955
+ const shiftX = Math.max(0, (rotatedFootprint + padding - pixelDistance) / 2)
728
956
 
729
957
  return {
730
958
  lowAngleDeg: signedAngle,
@@ -738,6 +966,10 @@ export const calculateLabelSlant = (lowPct: number, highPct: number, trackWidthP
738
966
  }
739
967
  }
740
968
 
969
+ /**
970
+ * Grabbable part of a vernier slider, naming both the rail and the element on it.
971
+ * ノギススライダーで掴める部位 (レールと要素の組)。
972
+ */
741
973
  export type VernierHandle = "macro-low" | "macro-high" | "macro-connect" | "micro-low" | "micro-high" | "micro-connect"
742
974
 
743
975
  /**
@@ -817,7 +1049,6 @@ export function calculateVernierMacroDrag(handle: "macro-low" | "macro-high" | "
817
1049
  }
818
1050
  return [clamped, startMacroHighRatio, "macro-low"]
819
1051
  }
820
- // macro-high
821
1052
  const clamped = Math.max(0, Math.min(1, pointerRatio))
822
1053
  if (clamped < startMacroLowRatio) {
823
1054
  return [clamped, startMacroLowRatio, "macro-low"]
@@ -851,7 +1082,6 @@ export function calculateVernierMicroDrag(handle: "micro-low" | "micro-high" | "
851
1082
  }
852
1083
  return [clamped, startMicroHighRatio, "micro-low"]
853
1084
  }
854
- // micro-high
855
1085
  const clamped = Math.max(0, Math.min(1, pointerRatio))
856
1086
  if (clamped < startMicroLowRatio) {
857
1087
  return [clamped, startMicroLowRatio, "micro-low"]
@@ -899,6 +1129,209 @@ VernierKnobSvg.displayName = "VernierKnobSvg"
899
1129
  // 3. React Component Implementation
900
1130
  // ======================================================================
901
1131
 
1132
+ /**
1133
+ * Validates the mandatory slider domain boundaries and fails fast on an unusable domain.
1134
+ * スライダー定義域の必須境界を検証し、利用不能な入力で即座に失敗させる関数。
1135
+ *
1136
+ * @param minDate - Lower domain boundary supplied by the consumer / 利用側が指定した定義域下限
1137
+ * @param maxDate - Upper domain boundary supplied by the consumer / 利用側が指定した定義域上限
1138
+ * @returns Nothing; the function only throws or returns normally / 戻り値なし (正常時は無返却)
1139
+ * @throws RangeError when a boundary is absent or an Invalid Date, or maxDate is not strictly later than minDate / 境界の欠落・Invalid Date・maxDate が minDate 以下の場合
1140
+ */
1141
+ const assertDomainBounds = (minDate: Date, maxDate: Date): void => {
1142
+ if (!isValidDate(minDate)) throw new RangeError(`PeriodSlider: minDate is required and must be a valid Date (received: ${describeDateValue(minDate)})`)
1143
+ if (!isValidDate(maxDate)) throw new RangeError(`PeriodSlider: maxDate is required and must be a valid Date (received: ${describeDateValue(maxDate)})`)
1144
+ if (maxDate.getTime() <= minDate.getTime()) {
1145
+ throw new RangeError(`PeriodSlider: maxDate must be strictly later than minDate (minDate: ${describeDateValue(minDate)}, maxDate: ${describeDateValue(maxDate)})`)
1146
+ }
1147
+ }
1148
+
1149
+ /**
1150
+ * Validates a required [start, end] Date tuple prop and fails fast on an unusable value.
1151
+ * 必須の [開始, 終了] 日付タプル Props を検証し、利用不能な値で即座に失敗させる関数。
1152
+ *
1153
+ * @param propName - Prop name quoted in the error message / エラーメッセージへ埋め込む Props 名
1154
+ * @param value - Raw prop value supplied by the consumer / 利用側が指定した生の Props 値
1155
+ * @returns Nothing; the function only throws or returns normally / 戻り値なし (正常時は無返却)
1156
+ * @throws RangeError when the value is not a two-element tuple, holds an Invalid Date, or is inverted / 2 要素タプルでない場合、Invalid Date を含む場合、または開始と終了が逆転している場合
1157
+ */
1158
+ const assertDateRangeTuple = (propName: string, value: unknown): void => {
1159
+ if (!Array.isArray(value) || value.length !== 2) {
1160
+ throw new RangeError(`PeriodSlider: ${propName} is required and must be a [start, end] Date tuple (received: ${describeDateValue(value)})`)
1161
+ }
1162
+ const [start, end] = value
1163
+ if (!isValidDate(start)) throw new RangeError(`PeriodSlider: ${propName}[0] must be a valid Date (received: ${describeDateValue(start)})`)
1164
+ if (!isValidDate(end)) throw new RangeError(`PeriodSlider: ${propName}[1] must be a valid Date (received: ${describeDateValue(end)})`)
1165
+ if (end.getTime() < start.getTime()) {
1166
+ throw new RangeError(`PeriodSlider: ${propName} must not be inverted (start: ${describeDateValue(start)}, end: ${describeDateValue(end)})`)
1167
+ }
1168
+ }
1169
+
1170
+ /**
1171
+ * Validates the mandatory vernier props and resolves the micro selection that seeds the uncontrolled state.
1172
+ * ノギスモードの必須 Props を検証し、非制御ステートの初期値となるミクロ選択期間を解決する関数。
1173
+ *
1174
+ * @param macroRange - Macro window tuple; the micro rail spans exactly this window / マクロ窓タプル (ミクロレールの定義域そのもの)
1175
+ * @param microRange - Controlled micro selection tuple, or undefined when uncontrolled / 制御時のミクロ選択タプル (非制御時は undefined)
1176
+ * @param defaultMicroRange - Initial micro selection tuple for uncontrolled usage / 非制御時の初期ミクロ選択タプル
1177
+ * @returns Validated micro selection tuple / 検証済みのミクロ選択タプル
1178
+ * @throws RangeError when macroRange is unusable, or when neither micro selection prop is supplied / macroRange が利用不能な場合、またはミクロ選択 Props がいずれも未指定の場合
1179
+ */
1180
+ const assertVernierRanges = (macroRange: [Date, Date], microRange: [Date, Date] | undefined, defaultMicroRange: [Date, Date] | undefined): [Date, Date] => {
1181
+ assertDateRangeTuple("macroRange", macroRange)
1182
+ if (microRange !== undefined) {
1183
+ assertDateRangeTuple("microRange", microRange)
1184
+ return microRange
1185
+ }
1186
+ if (defaultMicroRange !== undefined) {
1187
+ assertDateRangeTuple("defaultMicroRange", defaultMicroRange)
1188
+ return defaultMicroRange
1189
+ }
1190
+ throw new RangeError("PeriodSlider: vernier mode requires a micro selection; supply microRange (controlled) or defaultMicroRange (uncontrolled)")
1191
+ }
1192
+
1193
+ /**
1194
+ * Resolves the discrete date reached by one keyboard step inside a sorted allowed-date list.
1195
+ * 昇順の離散候補日付一覧の中で、キーボード 1 操作分の移動先日付を解決する関数。
1196
+ *
1197
+ * @param dates - Ascending, deduplicated allowed dates / 昇順・重複排除済みの候補日付一覧
1198
+ * @param unit - Time resolution unit used to locate the current entry / 現在値の特定に用いる時間解像度単位
1199
+ * @param current - Currently selected date of the manipulated handle / 操作対象つまみの現在選択日付
1200
+ * @param lowerBound - Lowest date the handle may reach / つまみが到達可能な下限日付
1201
+ * @param upperBound - Highest date the handle may reach / つまみが到達可能な上限日付
1202
+ * @param delta - Signed number of indices to move / 移動するインデックス数 (符号付き)
1203
+ * @param isHome - Whether the Home key was pressed / Home キー押下か
1204
+ * @param isEnd - Whether the End key was pressed / End キー押下か
1205
+ * @returns Allowed date the handle moves to / つまみの移動先となる候補日付
1206
+ */
1207
+ const stepDiscreteDate = (dates: Date[], unit: PeriodSliderUnit, current: Date, lowerBound: Date, upperBound: Date, delta: number, isHome: boolean, isEnd: boolean): Date => {
1208
+ const lowIdx = findNearestDateIndex(dates, lowerBound, unit)
1209
+ const highIdx = findNearestDateIndex(dates, upperBound, unit)
1210
+ if (isHome) return dates[lowIdx]
1211
+ if (isEnd) return dates[highIdx]
1212
+ const nextIdx = Math.max(lowIdx, Math.min(highIdx, findNearestDateIndex(dates, current, unit) + delta))
1213
+ return dates[nextIdx]
1214
+ }
1215
+
1216
+ /**
1217
+ * Mutable slot holding the timer and payload of a single pending debounced emission.
1218
+ * デバウンス中の発火 1 件分のタイマーと処理を保持する可変枠。
1219
+ */
1220
+ interface PendingEmitSlot {
1221
+ /** Identifier of the armed timer, or null when nothing is pending / 予約済みタイマーの識別子 (保留なしなら null) */
1222
+ timerId: ReturnType<typeof setTimeout> | null
1223
+ /** Emission the armed timer will run, or null when nothing is pending / 予約済みタイマーが実行する発火処理 (保留なしなら null) */
1224
+ emit: (() => void) | null
1225
+ }
1226
+
1227
+ /**
1228
+ * Disarms the pending emission of a slot without running it.
1229
+ * 枠に保留中の発火を、実行せずに取り消す関数。
1230
+ *
1231
+ * @param slot - Slot to disarm / 取り消し対象の枠
1232
+ * @returns Nothing / 戻り値なし
1233
+ */
1234
+ const cancelPendingEmit = (slot: PendingEmitSlot): void => {
1235
+ if (slot.timerId !== null) {
1236
+ clearTimeout(slot.timerId)
1237
+ }
1238
+ slot.timerId = null
1239
+ slot.emit = null
1240
+ }
1241
+
1242
+ /**
1243
+ * Validates a BCP 47 language tag prop and fails fast on a tag Intl cannot use.
1244
+ * BCP 47 言語タグ Props を検証し、Intl が解釈できないタグで即座に失敗させる関数。
1245
+ *
1246
+ * @param propName - Prop name quoted in the error message / エラーメッセージへ埋め込む Props 名
1247
+ * @param locale - Raw prop value supplied by the consumer / 利用側が指定した生の Props 値
1248
+ * @returns Nothing; the function only throws or returns normally / 戻り値なし (正常時は無返却)
1249
+ * @throws RangeError when the value is not a structurally valid language tag / 値が構造的に妥当な言語タグでない場合
1250
+ */
1251
+ const assertLocaleTag = (propName: string, locale: unknown): void => {
1252
+ try {
1253
+ // 構造的に不正なタグと空文字列は Intl が送出する RangeError でのみ判定できる。
1254
+ // 独自の正規表現で真似ると ICU が受理するタグを取りこぼす
1255
+ Intl.DateTimeFormat.supportedLocalesOf([locale as string])
1256
+ } catch {
1257
+ throw new RangeError(`PeriodSlider: ${propName} must be a valid BCP 47 language tag (received: ${JSON.stringify(locale)})`)
1258
+ }
1259
+ }
1260
+
1261
+ /**
1262
+ * Layout size of a rendered element in CSS pixels, unaffected by any CSS transform.
1263
+ * CSS トランスフォームの影響を受けない描画済み要素のレイアウトサイズ (CSS ピクセル)。
1264
+ */
1265
+ interface MeasuredBoxPx {
1266
+ /** Border-box width / ボーダーボックス幅 */
1267
+ widthPx: number
1268
+ /** Border-box height / ボーダーボックス高さ */
1269
+ heightPx: number
1270
+ }
1271
+
1272
+ /**
1273
+ * Tracks the border-box size of whichever element is handed to the returned ref callback.
1274
+ * 返却した ref コールバックへ渡された要素のボーダーボックスサイズを追跡するフック。
1275
+ *
1276
+ * @returns Ref callback to attach, and the latest measured box or null while unmeasured / 要素へ渡す ref コールバックと最新の実測サイズ (未実測時は null)
1277
+ */
1278
+ const useMeasuredBorderBox = (): [(element: HTMLElement | null) => void, MeasuredBoxPx | null] => {
1279
+ const [box, setBox] = useState<MeasuredBoxPx | null>(null)
1280
+ const observerRef = useRef<ResizeObserver | null>(null)
1281
+
1282
+ const measureRef = useCallback((element: HTMLElement | null): void => {
1283
+ observerRef.current?.disconnect()
1284
+ observerRef.current = null
1285
+
1286
+ if (element === null) {
1287
+ setBox(null)
1288
+ return
1289
+ }
1290
+
1291
+ // getBoundingClientRect は回転後の外接矩形を返すため、傾けるほど幅が増えて更に傾く自己増幅ループになる。
1292
+ // borderBoxSize は transform 非依存のレイアウト寸法であり、この経路だけが安定する
1293
+ if (typeof ResizeObserver === "undefined") return
1294
+
1295
+ const observer = new ResizeObserver((entries) => {
1296
+ for (const entry of entries) {
1297
+ const borderBox = entry.borderBoxSize?.[0]
1298
+ if (borderBox === undefined) continue
1299
+ setBox((prev) => (prev !== null && Math.abs(prev.widthPx - borderBox.inlineSize) < 0.5 && Math.abs(prev.heightPx - borderBox.blockSize) < 0.5 ? prev : { widthPx: borderBox.inlineSize, heightPx: borderBox.blockSize }))
1300
+ }
1301
+ })
1302
+ observer.observe(element)
1303
+ observerRef.current = observer
1304
+ }, [])
1305
+
1306
+ useEffect(
1307
+ () => () => {
1308
+ observerRef.current?.disconnect()
1309
+ observerRef.current = null
1310
+ },
1311
+ [],
1312
+ )
1313
+
1314
+ return [measureRef, box]
1315
+ }
1316
+
1317
+ /**
1318
+ * What a stepper button does to the selected value.
1319
+ * ステッパーボタンが選択値へ与える作用。
1320
+ */
1321
+ type StepDirection = "decrease" | "increase"
1322
+
1323
+ /** Arrow each stepper direction is drawn with per axis / 軸ごとの各ステッパー方向の矢印 */
1324
+ const STEPPER_GLYPHS: Record<"horizontal" | "vertical", Record<StepDirection, string>> = {
1325
+ horizontal: { decrease: "◀", increase: "▶" },
1326
+ vertical: { decrease: "▼", increase: "▲" },
1327
+ }
1328
+
1329
+ /** Position class each stepper direction carries per axis / 軸ごとの各ステッパー方向が持つ配置クラス */
1330
+ const STEPPER_POSITION_CLASSES: Record<"horizontal" | "vertical", Record<StepDirection, string>> = {
1331
+ horizontal: { decrease: "period-slider-stepper-prev", increase: "period-slider-stepper-next" },
1332
+ vertical: { decrease: "period-slider-stepper-prev period-slider-stepper-down", increase: "period-slider-stepper-next period-slider-stepper-up" },
1333
+ }
1334
+
902
1335
  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: Vernier integrated multi-mode scale requires comprehensive coordinate handling
903
1336
  const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
904
1337
  const {
@@ -917,19 +1350,31 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
917
1350
  hideConnectBar = false,
918
1351
  showTicks = false,
919
1352
  colorScheme = "blue-rose",
1353
+ locale,
1354
+ decreaseAriaLabel = "Decrease",
1355
+ increaseAriaLabel = "Increase",
920
1356
  } = props
921
1357
 
922
- const palette = COLOR_SCHEME_PALETTES[colorScheme] ?? COLOR_SCHEME_PALETTES["blue-rose"]
1358
+ // 定義域が欠けたまま描画すると全ての位置計算が無根拠になるため、フック呼び出し前に失敗させる
1359
+ assertDomainBounds(minDate, maxDate)
1360
+
1361
+ // 不正なロケールを黙って ISO 表記へ落とすと、利用側は翻訳が効かない理由に気付けない
1362
+ if (locale !== undefined) assertLocaleTag("locale", locale)
1363
+
1364
+ // マクロ窓とミクロ選択もノギスの位置計算の根拠そのもの。欠ければ同じくフック前に失敗させる
1365
+ const initialVernierMicroRange: [Date, Date] | null = props.mode === "vernier" ? assertVernierRanges(props.macroRange, props.microRange, props.defaultMicroRange) : null
1366
+
1367
+ const palette = COLOR_SCHEME_PALETTES[colorScheme]
923
1368
  const vernierGradId = useId()
924
1369
 
925
1370
  const propsRef = useRef(props)
926
1371
  propsRef.current = props
927
1372
 
928
- const minTime = minDate?.getTime()
929
- const maxTime = maxDate?.getTime()
1373
+ const minTime = minDate.getTime()
1374
+ const maxTime = maxDate.getTime()
930
1375
 
931
1376
  // ------------------------------------------------------------------
932
- // A. Pre-processed Discrete Dates & Range Bounds
1377
+ // A. 離散候補日付と値域の前処理
933
1378
  // ------------------------------------------------------------------
934
1379
  const sortedAllowedDates = useMemo(() => {
935
1380
  return getSortedAllowedDates(allowedDates, unit, minDate, maxDate)
@@ -941,30 +1386,20 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
941
1386
  if (isDiscrete) {
942
1387
  return { rangeMin: 0, rangeMax: sortedAllowedDates.length - 1 }
943
1388
  }
944
- const defaultMin = normalizeDateByUnit(unit, minDate ?? new Date(2020, 0, 1))
945
- let defaultMax = normalizeDateByUnit(unit, maxDate ?? new Date(2030, 0, 1))
946
-
947
- const minEnc = encode(unit, defaultMin)
948
- let maxEnc = encode(unit, defaultMax)
949
-
950
- if (maxEnc <= minEnc) {
951
- defaultMax = addUnit(unit, defaultMin, 1)
952
- maxEnc = encode(unit, defaultMax)
953
- }
954
-
955
- return { rangeMin: minEnc, rangeMax: maxEnc }
1389
+ // 単位丸めで minEnc === maxEnc になる定義域は 1 単位分の正当な定義域。広げると maxDate 超過の日付を返してしまう
1390
+ return { rangeMin: encode(unit, minDate), rangeMax: encode(unit, maxDate) }
956
1391
  }, [isDiscrete, sortedAllowedDates, unit, minTime, maxTime])
957
1392
 
958
1393
  const isPointMode = props.mode === "point"
959
1394
 
960
1395
  // ------------------------------------------------------------------
961
- // B. Value Transformation Converters
1396
+ // B. 値空間の相互変換
962
1397
  // ------------------------------------------------------------------
963
1398
  const valueToDate = useCallback(
964
1399
  (val: number): Date => {
965
1400
  if (isDiscrete) {
966
1401
  const idx = Math.max(0, Math.min(sortedAllowedDates.length - 1, Math.round(val)))
967
- return sortedAllowedDates[idx] ?? new Date()
1402
+ return sortedAllowedDates[idx]
968
1403
  }
969
1404
  return decode(unit, Math.round(val))
970
1405
  },
@@ -973,7 +1408,8 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
973
1408
 
974
1409
  const dateToValue = useCallback(
975
1410
  (d?: Date): number => {
976
- if (!d || Number.isNaN(d.getTime())) return rangeMin
1411
+ // 未指定は「定義域の先頭を選択」を意味する仕様上の既定値。Invalid Date は normalizeDateByUnit が送出
1412
+ if (d === undefined) return rangeMin
977
1413
  const norm = normalizeDateByUnit(unit, d)
978
1414
  if (isDiscrete) {
979
1415
  return findNearestDateIndex(sortedAllowedDates, norm, unit)
@@ -984,34 +1420,19 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
984
1420
  )
985
1421
 
986
1422
  // ------------------------------------------------------------------
987
- // C. Internal State Initialization & Sync
1423
+ // C. 内部ステートの初期化と同期
988
1424
  // ------------------------------------------------------------------
989
- const effectiveLowerDate: Date | undefined =
990
- props.mode === "range"
991
- ? props.range
992
- ? props.range[0]
993
- : (props.lowerDate ?? props.defaultRange?.[0] ?? props.initialRange?.[0] ?? props.defaultLowerDate ?? props.initialLowerDate)
994
- : props.mode === "vernier"
995
- ? props.microRange
996
- ? props.microRange[0]
997
- : (props.lowerDate ?? props.defaultMicroRange?.[0] ?? props.initialMicroRange?.[0] ?? props.defaultLowerDate ?? props.initialLowerDate)
998
- : undefined
999
-
1000
- const effectiveUpperDate: Date | undefined =
1001
- props.mode === "range"
1002
- ? props.range
1003
- ? props.range[1]
1004
- : (props.upperDate ?? props.defaultRange?.[1] ?? props.initialRange?.[1] ?? props.defaultUpperDate ?? props.initialUpperDate)
1005
- : props.mode === "vernier"
1006
- ? props.microRange
1007
- ? props.microRange[1]
1008
- : (props.upperDate ?? props.defaultMicroRange?.[1] ?? props.initialMicroRange?.[1] ?? props.defaultUpperDate ?? props.initialUpperDate)
1009
- : undefined
1010
-
1011
- const effectivePointDate: Date | undefined = props.mode === "point" ? (props.value ?? props.valueDate ?? props.defaultValue ?? props.initialDate) : undefined
1012
-
1013
- const safeLowerDate = effectiveLowerDate ?? (isDiscrete ? sortedAllowedDates[0] : decode(unit, rangeMin))
1014
- const safeUpperDate = effectiveUpperDate ?? (isDiscrete ? sortedAllowedDates[sortedAllowedDates.length - 1] : decode(unit, rangeMax))
1425
+ // ノギス非制御時のミクロ選択。初期値は defaultMicroRange、以降は notifyMicroRange が唯一の書き込み経路
1426
+ const [uncontrolledMicroRange, setUncontrolledMicroRange] = useState<[Date, Date] | null>(() => initialVernierMicroRange)
1427
+
1428
+ // null はノギス以外を意味する。ノギスでは assertVernierRanges が値の存在を保証済み
1429
+ const vernierMicroSelection: [Date, Date] | null = props.mode !== "vernier" ? null : props.microRange !== undefined ? props.microRange : uncontrolledMicroRange
1430
+
1431
+ const effectiveLowerDate: Date | undefined = props.mode === "range" ? (props.range?.[0] ?? props.defaultRange?.[0]) : props.mode === "vernier" ? vernierMicroSelection?.[0] : undefined
1432
+
1433
+ const effectiveUpperDate: Date | undefined = props.mode === "range" ? (props.range?.[1] ?? props.defaultRange?.[1]) : props.mode === "vernier" ? vernierMicroSelection?.[1] : undefined
1434
+
1435
+ const effectivePointDate: Date | undefined = props.mode === "point" ? (props.value ?? props.defaultValue) : undefined
1015
1436
 
1016
1437
  const propLowerMs = props.mode === "point" ? effectivePointDate?.getTime() : effectiveLowerDate?.getTime()
1017
1438
  const propUpperMs = props.mode === "range" ? effectiveUpperDate?.getTime() : propLowerMs
@@ -1027,21 +1448,10 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1027
1448
  }, [props.mode, propLowerMs, propUpperMs, dateToValue, effectivePointDate, effectiveLowerDate, effectiveUpperDate])
1028
1449
 
1029
1450
  // 非制御 (Uncontrolled) 運用時の自律ステート管理
1030
- const isControlled =
1031
- props.mode === "point"
1032
- ? props.value !== undefined || props.valueDate !== undefined
1033
- : props.mode === "range"
1034
- ? props.range !== undefined || props.lowerDate !== undefined || props.upperDate !== undefined
1035
- : props.microRange !== undefined || props.lowerDate !== undefined || props.upperDate !== undefined
1451
+ const isControlled = props.mode === "point" ? props.value !== undefined : props.mode === "range" ? props.range !== undefined : props.microRange !== undefined
1036
1452
 
1037
1453
  const [uncontrolledValues, setUncontrolledValues] = useState<[number, number]>(() => [initLow, initHigh])
1038
1454
 
1039
- useEffect(() => {
1040
- if (isControlled) {
1041
- setUncontrolledValues([initLow, initHigh])
1042
- }
1043
- }, [isControlled, initLow, initHigh])
1044
-
1045
1455
  const [draggingValues, setDraggingValues] = useState<[number, number] | null>(null)
1046
1456
  const [activeHandle, setActiveHandle] = useState<"low" | "high" | "connect" | null>(null)
1047
1457
  const activeHandleRef = useRef<"low" | "high" | "connect" | null>(null)
@@ -1055,7 +1465,7 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1055
1465
  const currentHighVal = draggingValues ? draggingValues[1] : isControlled ? initHigh : uncontrolledValues[1]
1056
1466
 
1057
1467
  // ------------------------------------------------------------------
1058
- // C-2. Vernier Scale Bounds & Drag State
1468
+ // C-2. ノギススケールの境界とドラッグ状態
1059
1469
  // ------------------------------------------------------------------
1060
1470
  const isVernierMode = props.mode === "vernier"
1061
1471
  const vernierOrientation = props.mode === "vernier" ? (props.vernierOrientation ?? (isVertical ? "macro-left" : "macro-top")) : "macro-top"
@@ -1076,71 +1486,81 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1076
1486
  const formatMacroLabel = isVernierMode ? ((props as PeriodSliderVernierProps).formatMacroLabel ?? props.formatLabel) : props.formatLabel
1077
1487
  const formatMicroLabel = isVernierMode ? ((props as PeriodSliderVernierProps).formatMicroLabel ?? props.formatLabel) : props.formatLabel
1078
1488
 
1079
- const macroRangeStartMs = isVernierMode && (props as PeriodSliderVernierProps).macroRange ? (props as PeriodSliderVernierProps).macroRange[0]?.getTime() : undefined
1080
- const macroRangeEndMs = isVernierMode && (props as PeriodSliderVernierProps).macroRange ? (props as PeriodSliderVernierProps).macroRange[1]?.getTime() : undefined
1081
- const lowerDateMs = props.mode !== "point" ? props.lowerDate?.getTime() : undefined
1082
- const upperDateMs = props.mode !== "point" ? props.upperDate?.getTime() : undefined
1489
+ const macroRangeStartMs = props.mode === "vernier" ? props.macroRange[0].getTime() : undefined
1490
+ const macroRangeEndMs = props.mode === "vernier" ? props.macroRange[1].getTime() : undefined
1491
+ const microLowMs = effectiveLowerDate?.getTime()
1492
+ const microHighMs = effectiveUpperDate?.getTime()
1083
1493
 
1084
1494
  const [activeVernierHandle, setActiveVernierHandle] = useState<VernierHandle | null>(null)
1085
1495
  const activeVernierHandleRef = useRef<VernierHandle | null>(null)
1086
1496
  activeVernierHandleRef.current = activeVernierHandle
1087
1497
  const [frontVernierHandle, setFrontVernierHandle] = useState<VernierHandle>("micro-high")
1088
1498
 
1089
- // マクロ境界
1090
- const vernierMacroMinEnc = useMemo(() => {
1091
- if (!isVernierMode) return 0
1092
- return encode(macroUnit, normalizeDateByUnit(macroUnit, minDate ?? new Date(2020, 0, 1)))
1093
- }, [isVernierMode, minTime, macroUnit, minDate])
1499
+ // マクロ境界 (ノギス以外では読まれないが、定義域そのものなので分岐せず素直に求める)
1500
+ const vernierMacroMinEnc = useMemo(() => encode(macroUnit, minDate), [minTime, macroUnit])
1094
1501
 
1095
1502
  const vernierMacroMaxEnc = useMemo(() => {
1096
- if (!isVernierMode) return 1
1097
- const maxNorm = normalizeDateByUnit(macroUnit, maxDate ?? new Date(2030, 0, 1))
1098
- const maxEnc = encode(macroUnit, maxNorm)
1099
- return maxEnc <= vernierMacroMinEnc ? vernierMacroMinEnc + 1 : maxEnc
1100
- }, [isVernierMode, maxTime, vernierMacroMinEnc, macroUnit, maxDate])
1503
+ const maxEnc = encode(macroUnit, maxDate)
1504
+ // 1 マクロ単位に収まる定義域はマクロレールが操作不能。旧実装のように 1 単位広げると maxDate 超過の日付を返す
1505
+ if (isVernierMode && maxEnc <= vernierMacroMinEnc) {
1506
+ throw new RangeError(`PeriodSlider: macroUnit "${macroUnit}" cannot distinguish minDate from maxDate (minDate: ${describeDateValue(minDate)}, maxDate: ${describeDateValue(maxDate)})`)
1507
+ }
1508
+ return maxEnc
1509
+ }, [isVernierMode, minTime, maxTime, vernierMacroMinEnc, macroUnit])
1101
1510
 
1102
1511
  const sortedMacroAllowedDates = useMemo(() => {
1103
1512
  if (!isVernierMode) return []
1104
1513
  return getSortedAllowedDates(macroAllowedDates, macroUnit, minDate, maxDate)
1105
- }, [isVernierMode, macroAllowedDates, macroUnit, minDate, maxDate])
1106
-
1107
- const sortedMicroAllowedDates = useMemo(() => {
1108
- if (!isVernierMode) return []
1109
- return getSortedAllowedDates(microAllowedDates, microUnit, minDate, maxDate)
1110
- }, [isVernierMode, microAllowedDates, microUnit, minDate, maxDate])
1514
+ }, [isVernierMode, macroAllowedDates, macroUnit, minTime, maxTime])
1111
1515
 
1112
1516
  const vernierMacroLowEnc = useMemo(() => {
1113
- if (!(isVernierMode && props.macroRange)) return vernierMacroMinEnc
1114
- return encode(macroUnit, normalizeDateByUnit(macroUnit, props.macroRange[0]))
1115
- }, [isVernierMode, macroRangeStartMs, vernierMacroMinEnc, macroUnit])
1517
+ if (props.mode !== "vernier") return vernierMacroMinEnc
1518
+ return encode(macroUnit, props.macroRange[0])
1519
+ }, [props.mode, macroRangeStartMs, vernierMacroMinEnc, macroUnit])
1116
1520
 
1117
1521
  const vernierMacroHighEnc = useMemo(() => {
1118
- if (!(isVernierMode && props.macroRange)) return vernierMacroMaxEnc
1119
- return encode(macroUnit, normalizeDateByUnit(macroUnit, props.macroRange[1]))
1120
- }, [isVernierMode, macroRangeEndMs, vernierMacroMaxEnc, macroUnit])
1522
+ if (props.mode !== "vernier") return vernierMacroMaxEnc
1523
+ return encode(macroUnit, props.macroRange[1])
1524
+ }, [props.mode, macroRangeEndMs, vernierMacroMaxEnc, macroUnit])
1121
1525
 
1122
- // ミクロ境界 (マクロ窓がミクロのスケール範囲)
1526
+ // ミクロ境界 (マクロ窓がミクロのスケール範囲)。
1527
+ // マクロ窓は macroUnit 単位へ丸められるうえ末尾期間全体まで広げられるため、そのままでは定義域の外側まで伸びる。
1528
+ // レール自体を [minDate, maxDate] で切り落とさないと、aria-valuemin/max もドラッグ端も定義域外の日付を指す
1123
1529
  const vernierMicroMinEnc = useMemo(() => {
1124
- if (!(isVernierMode && props.macroRange)) return 0
1125
- return encode(microUnit, normalizeDateByUnit(microUnit, props.macroRange[0]))
1126
- }, [isVernierMode, macroRangeStartMs, microUnit])
1530
+ if (props.mode !== "vernier") return encode(microUnit, minDate)
1531
+ return Math.max(encode(microUnit, props.macroRange[0]), encode(microUnit, minDate))
1532
+ }, [props.mode, macroRangeStartMs, microUnit, minTime])
1127
1533
 
1128
1534
  const vernierMicroMaxEnc = useMemo(() => {
1129
- if (!(isVernierMode && props.macroRange)) return 1
1130
- const macroEnd = getMacroWindowEndDate(macroUnit, microUnit, props.macroRange[1])
1131
- const maxEnc = encode(microUnit, normalizeDateByUnit(microUnit, macroEnd))
1132
- return maxEnc <= vernierMicroMinEnc ? vernierMicroMinEnc + 1 : maxEnc
1133
- }, [isVernierMode, macroRangeEndMs, vernierMicroMinEnc, macroUnit, microUnit])
1535
+ if (props.mode !== "vernier") return encode(microUnit, maxDate)
1536
+ // マクロ窓が 1 単位に収まる場合、ミクロ側の定義域も同じ 1 単位。広げるとマクロ窓外の日付を選択できてしまう
1537
+ return Math.min(encode(microUnit, getMacroWindowEndDate(macroUnit, microUnit, props.macroRange[1])), encode(microUnit, maxDate))
1538
+ }, [props.mode, macroRangeEndMs, macroUnit, microUnit, maxTime])
1539
+
1540
+ // 候補日付はマクロ窓で切り出す。定義域全体のままではキーボードもポインターも窓の外の日付を発火する。
1541
+ // 窓内に候補が 1 つも無い場合は空配列となり、各操作は離散分岐へ入らず窓内の連続値として扱われる
1542
+ const sortedMicroAllowedDates = useMemo(() => {
1543
+ if (!isVernierMode) return []
1544
+ const domainDates = getSortedAllowedDates(microAllowedDates, microUnit, minDate, maxDate)
1545
+ return domainDates.filter((d) => {
1546
+ const enc = encode(microUnit, d)
1547
+ return enc >= vernierMicroMinEnc && enc <= vernierMicroMaxEnc
1548
+ })
1549
+ }, [isVernierMode, microAllowedDates, microUnit, minTime, maxTime, vernierMicroMinEnc, vernierMicroMaxEnc])
1134
1550
 
1135
1551
  const vernierMicroLowEnc = useMemo(() => {
1136
- if (!(isVernierMode && effectiveLowerDate)) return vernierMicroMinEnc
1137
- return encode(microUnit, normalizeDateByUnit(microUnit, effectiveLowerDate))
1138
- }, [isVernierMode, lowerDateMs, vernierMicroMinEnc, microUnit, effectiveLowerDate])
1552
+ if (vernierMicroSelection === null) return vernierMicroMinEnc
1553
+ return encode(microUnit, vernierMicroSelection[0])
1554
+ }, [microLowMs, vernierMicroMinEnc, microUnit, vernierMicroSelection])
1139
1555
 
1140
1556
  const vernierMicroHighEnc = useMemo(() => {
1141
- if (!(isVernierMode && effectiveUpperDate)) return vernierMicroMaxEnc
1142
- return encode(microUnit, normalizeDateByUnit(microUnit, effectiveUpperDate))
1143
- }, [isVernierMode, upperDateMs, vernierMicroMaxEnc, microUnit, effectiveUpperDate])
1557
+ if (vernierMicroSelection === null) return vernierMicroMaxEnc
1558
+ return encode(microUnit, vernierMicroSelection[1])
1559
+ }, [microHighMs, vernierMicroMaxEnc, microUnit, vernierMicroSelection])
1560
+
1561
+ // つまみ位置と同じ enc から復元することで、ラベルと描画位置が食い違う余地をなくす
1562
+ const vernierMicroLowDate = useMemo(() => decode(microUnit, vernierMicroLowEnc), [microUnit, vernierMicroLowEnc])
1563
+ const vernierMicroHighDate = useMemo(() => decode(microUnit, vernierMicroHighEnc), [microUnit, vernierMicroHighEnc])
1144
1564
 
1145
1565
  // 比率 (0.0 〜 1.0)
1146
1566
  const macroSpan = Math.max(1, vernierMacroMaxEnc - vernierMacroMinEnc)
@@ -1152,73 +1572,163 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1152
1572
  const microHighRatio = Math.max(microLowRatio, Math.min(1, (vernierMicroHighEnc - vernierMicroMinEnc) / microSpan))
1153
1573
 
1154
1574
  // ------------------------------------------------------------------
1155
- // D. Debounce & Callback Notification
1575
+ // D. デバウンスとコールバック通知
1156
1576
  // ------------------------------------------------------------------
1157
- const debounceTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null)
1577
+ // range/point・マクロ・ミクロで枠を分ける。1 枠を共有すると macro-connect ドラッグのように
1578
+ // 1 回の move で 2 系統が発火する場面で、後から予約した側が先の予約を取り消してしまう
1579
+ const rangeEmitRef = useRef<PendingEmitSlot>({ timerId: null, emit: null })
1580
+ const macroEmitRef = useRef<PendingEmitSlot>({ timerId: null, emit: null })
1581
+ const microEmitRef = useRef<PendingEmitSlot>({ timerId: null, emit: null })
1158
1582
 
1159
- // Clean up timer on unmount to prevent memory leaks
1160
1583
  useEffect(() => {
1584
+ const slots = [rangeEmitRef, macroEmitRef, microEmitRef]
1161
1585
  return () => {
1162
- if (debounceTimerRef.current) {
1163
- clearTimeout(debounceTimerRef.current)
1586
+ for (const slot of slots) {
1587
+ cancelPendingEmit(slot.current)
1164
1588
  }
1165
1589
  }
1166
1590
  }, [])
1167
1591
 
1592
+ /**
1593
+ * Emits now, or replaces the pending emission of the given slot with one deferred by debounceMs.
1594
+ * 指定枠の保留発火を置き換えつつ、即時または debounceMs 経過後に発火処理を実行する関数。
1595
+ *
1596
+ * @param slot - Slot owning the pending emission / 保留中の発火を保持する枠
1597
+ * @param emit - Emission to run / 実行する発火処理
1598
+ * @param immediate - Bypasses the debounce and emits at once / デバウンスを迂回して即時発火するか
1599
+ * @returns Nothing / 戻り値なし
1600
+ */
1601
+ const scheduleEmit = useCallback((slot: PendingEmitSlot, emit: () => void, immediate: boolean): void => {
1602
+ cancelPendingEmit(slot)
1603
+ const { debounceMs } = propsRef.current
1604
+ if (immediate || !debounceMs || debounceMs <= 0) {
1605
+ emit()
1606
+ return
1607
+ }
1608
+ slot.emit = emit
1609
+ slot.timerId = setTimeout(() => {
1610
+ slot.timerId = null
1611
+ slot.emit = null
1612
+ emit()
1613
+ }, debounceMs)
1614
+ }, [])
1615
+
1616
+ /**
1617
+ * Runs the pending emission of the given slot immediately, if one is armed.
1618
+ * 指定枠に保留中の発火が存在する場合、それを即座に実行する関数。
1619
+ *
1620
+ * @param slot - Slot owning the pending emission / 保留中の発火を保持する枠
1621
+ * @returns Nothing / 戻り値なし
1622
+ */
1623
+ const flushPendingEmit = useCallback((slot: PendingEmitSlot): void => {
1624
+ const pending = slot.emit
1625
+ cancelPendingEmit(slot)
1626
+ pending?.()
1627
+ }, [])
1628
+
1629
+ /**
1630
+ * Clamps a date produced by rail arithmetic into the declared [minDate, maxDate] domain.
1631
+ * レール計算が生成した日付を、宣言済み定義域 [minDate, maxDate] へ収める関数。
1632
+ *
1633
+ * @param d - Date produced by a rail computation / レール計算が生成した日付
1634
+ * @returns Date guaranteed to lie inside the declared domain / 宣言済み定義域内であることが保証された日付
1635
+ */
1636
+ const clampToDomain = useCallback((d: Date): Date => new Date(Math.min(Math.max(d.getTime(), minTime), maxTime)), [minTime, maxTime])
1637
+
1168
1638
  const lastEmittedKeyRef = useRef<string | null>(null)
1169
1639
 
1170
1640
  const notifyChange = useCallback(
1171
1641
  (nextLow: number, nextHigh: number, immediate = false) => {
1172
- const p = propsRef.current
1173
1642
  const lowDate = valueToDate(nextLow)
1174
1643
  const highDate = valueToDate(nextHigh)
1175
1644
 
1176
- const key = p.mode === "point" ? `${lowDate.getTime()}` : `${lowDate.getTime()}-${highDate.getTime()}`
1645
+ const key = propsRef.current.mode === "point" ? `${lowDate.getTime()}` : `${lowDate.getTime()}-${highDate.getTime()}`
1177
1646
 
1178
- if (key === lastEmittedKeyRef.current && !debounceTimerRef.current) {
1647
+ if (key === lastEmittedKeyRef.current && rangeEmitRef.current.timerId === null) {
1179
1648
  return
1180
1649
  }
1181
1650
 
1651
+ // ノギスモードは値空間 (rangeMin/rangeMax) が別系統のため、この経路ではなく notifyMicroRange / notifyMacroRange を使う
1182
1652
  const doEmit = () => {
1183
1653
  lastEmittedKeyRef.current = key
1654
+ // 予約から発火までの間に利用側が別のハンドラへ差し替えることがある。
1655
+ // 予約時点のスナップショットを閉じ込めると、既に捨てられたクロージャだけが呼ばれる
1656
+ const p = propsRef.current
1184
1657
  if (p.mode === "point") {
1185
1658
  p.onChangePoint?.(lowDate)
1186
- p.onChangeValue?.(lowDate)
1187
- p.onChange?.(lowDate)
1188
1659
  } else if (p.mode === "range") {
1189
1660
  p.onChangeRange?.(lowDate, highDate)
1190
- p.onChangeRangeTuple?.([lowDate, highDate])
1191
- p.onChange?.([lowDate, highDate])
1192
- } else if (p.mode === "vernier") {
1193
- p.onChangeRange?.(lowDate, highDate)
1194
- p.onChangeRangeTuple?.([lowDate, highDate])
1195
- p.onChangeMicroRange?.(lowDate, highDate)
1196
- p.onChangeMicroRangeTuple?.([lowDate, highDate])
1197
- p.onChangeMicro?.([lowDate, highDate])
1198
1661
  }
1199
1662
  }
1200
1663
 
1201
- if (immediate || !p.debounceMs || p.debounceMs === 0) {
1202
- if (debounceTimerRef.current) {
1203
- clearTimeout(debounceTimerRef.current)
1204
- debounceTimerRef.current = null
1205
- }
1206
- doEmit()
1207
- } else {
1208
- if (debounceTimerRef.current) {
1209
- clearTimeout(debounceTimerRef.current)
1210
- }
1211
- debounceTimerRef.current = setTimeout(() => {
1212
- doEmit()
1213
- debounceTimerRef.current = null
1214
- }, p.debounceMs)
1664
+ scheduleEmit(rangeEmitRef.current, doEmit, immediate)
1665
+ },
1666
+ [valueToDate, scheduleEmit],
1667
+ )
1668
+
1669
+ /**
1670
+ * Emits the canonical macro window change callback, clamped to the declared domain.
1671
+ * マクロ窓変更の正準コールバックを、宣言済み定義域へクランプしたうえで発火する関数。
1672
+ *
1673
+ * @param lower - New macro window start date / 新しいマクロ窓の開始日付
1674
+ * @param upper - New macro window end date / 新しいマクロ窓の終了日付
1675
+ * @param immediate - Bypasses debounceMs and emits at once / debounceMs を迂回して即時発火するか
1676
+ * @returns Nothing / 戻り値なし
1677
+ */
1678
+ const notifyMacroRange = useCallback(
1679
+ (lower: Date, upper: Date, immediate = false) => {
1680
+ if (propsRef.current.mode !== "vernier") return
1681
+ // 境界は macroUnit の先頭へ丸められるため、そのままでは minDate より前の日付を利用側へ渡してしまう
1682
+ const clampedLower = clampToDomain(lower)
1683
+ const clampedUpper = clampToDomain(upper)
1684
+ scheduleEmit(
1685
+ macroEmitRef.current,
1686
+ () => {
1687
+ const p = propsRef.current
1688
+ if (p.mode !== "vernier") return
1689
+ p.onChangeMacroRange?.(clampedLower, clampedUpper)
1690
+ },
1691
+ immediate,
1692
+ )
1693
+ },
1694
+ [clampToDomain, scheduleEmit],
1695
+ )
1696
+
1697
+ /**
1698
+ * Commits the micro range to the uncontrolled state when needed and emits the canonical callback.
1699
+ * 非制御時はミクロ選択ステートを更新したうえで、正準コールバックを発火する関数。
1700
+ *
1701
+ * @param lower - New micro range start date / 新しいミクロ範囲の開始日付
1702
+ * @param upper - New micro range end date / 新しいミクロ範囲の終了日付
1703
+ * @param immediate - Bypasses debounceMs and emits at once / debounceMs を迂回して即時発火するか
1704
+ * @returns Nothing / 戻り値なし
1705
+ */
1706
+ const notifyMicroRange = useCallback(
1707
+ (lower: Date, upper: Date, immediate = false) => {
1708
+ const p = propsRef.current
1709
+ if (p.mode !== "vernier") return
1710
+ const clampedLower = clampToDomain(lower)
1711
+ const clampedUpper = clampToDomain(upper)
1712
+ // 非制御時はここが唯一の自律更新点。書かなければコールバックだけが鳴り、つまみは初期位置で固まる。
1713
+ // デバウンス対象は利用側への通知のみで、つまみ追従までは遅らせない
1714
+ if (p.microRange === undefined) {
1715
+ setUncontrolledMicroRange([clampedLower, clampedUpper])
1215
1716
  }
1717
+ scheduleEmit(
1718
+ microEmitRef.current,
1719
+ () => {
1720
+ const current = propsRef.current
1721
+ if (current.mode !== "vernier") return
1722
+ current.onChangeMicroRange?.(clampedLower, clampedUpper)
1723
+ },
1724
+ immediate,
1725
+ )
1216
1726
  },
1217
- [valueToDate],
1727
+ [clampToDomain, scheduleEmit],
1218
1728
  )
1219
1729
 
1220
1730
  // ------------------------------------------------------------------
1221
- // E. Percentage Math & Position Calculations
1731
+ // E. 百分率換算と位置計算
1222
1732
  // ------------------------------------------------------------------
1223
1733
  const valueToPct = useCallback(
1224
1734
  (val: number): number => {
@@ -1263,11 +1773,13 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1263
1773
  )
1264
1774
 
1265
1775
  // ------------------------------------------------------------------
1266
- // F. Pointer Coordinate Tracking & Track Dimension Observer
1776
+ // F. ポインター座標追跡とトラック実測
1267
1777
  // ------------------------------------------------------------------
1268
1778
  const trackRef = useRef<HTMLDivElement | null>(null)
1269
1779
  const [trackLength, setTrackLength] = useState<number>(0)
1270
- const trackWidth = trackLength // 後方互換性エイリアス
1780
+
1781
+ const [lowLabelRef, lowLabelBox] = useMeasuredBorderBox()
1782
+ const [highLabelRef, highLabelBox] = useMeasuredBorderBox()
1271
1783
 
1272
1784
  useEffect(() => {
1273
1785
  const el = trackRef.current
@@ -1298,30 +1810,31 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1298
1810
  return () => window.removeEventListener("resize", updateDimensions)
1299
1811
  }, [isVertical])
1300
1812
 
1301
- const calcPercentFromPos = useCallback(
1302
- (clientX: number, clientY: number, rect: DOMRect) => {
1303
- if (isVertical) {
1304
- const height = rect.height > 0 ? rect.height : 100
1305
- const diff = rect.bottom - clientY
1306
- return Math.max(0, Math.min(100, (diff / height) * 100))
1307
- }
1308
- const width = rect.width > 0 ? rect.width : 100
1309
- const diff = clientX - rect.left
1310
- return Math.max(0, Math.min(100, (diff / width) * 100))
1813
+ const calcRatioFromPos = useCallback(
1814
+ (clientX: number, clientY: number, rect: DOMRect): number | null => {
1815
+ const length = isVertical ? rect.height : rect.width
1816
+ // 初回描画・SSR・折り畳みレイアウトではトラックが未実測。既定長を捏造するとつまみが定義域の中央へ飛ぶ
1817
+ if (!(Number.isFinite(length) && length > 0)) return null
1818
+ const diff = isVertical ? rect.bottom - clientY : clientX - rect.left
1819
+ // 座標を持たない合成イベントでは比率が NaN になり、離散候補の添字に使うと undefined を掴む
1820
+ if (!Number.isFinite(diff)) return null
1821
+ return Math.max(0, Math.min(1, diff / length))
1311
1822
  },
1312
1823
  [isVertical],
1313
1824
  )
1314
1825
 
1315
1826
  const getTrackPctFromPointer = useCallback(
1316
- (clientX: number, clientY: number): number => {
1317
- if (!trackRef.current) return 0
1318
- return calcPercentFromPos(clientX, clientY, trackRef.current.getBoundingClientRect())
1827
+ (clientX: number, clientY: number): number | null => {
1828
+ const el = trackRef.current
1829
+ if (!el) return null
1830
+ const ratio = calcRatioFromPos(clientX, clientY, el.getBoundingClientRect())
1831
+ return ratio === null ? null : ratio * 100
1319
1832
  },
1320
- [calcPercentFromPos],
1833
+ [calcRatioFromPos],
1321
1834
  )
1322
1835
 
1323
1836
  // ------------------------------------------------------------------
1324
- // G. Drag Operation Handling & Event Subscriptions
1837
+ // G. ドラッグ操作とイベント購読
1325
1838
  // ------------------------------------------------------------------
1326
1839
  const dragContextRef = useRef<{
1327
1840
  pointerId: number
@@ -1361,15 +1874,8 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1361
1874
  const vCtx = vernierDragContextRef.current
1362
1875
  if (!vCtx || (e.pointerId !== 0 && e.pointerId !== vCtx.pointerId)) return
1363
1876
  if (!trackRef.current) return
1364
- const rect = trackRef.current.getBoundingClientRect()
1365
- const trackLength = isVertical ? rect.height : rect.width
1366
- if (trackLength <= 0) return
1367
-
1368
- const currentPos = isVertical ? e.clientY : e.clientX
1369
- const pointerRatio = Math.max(0, Math.min(1, isVertical ? (rect.bottom - currentPos) / trackLength : (currentPos - rect.left) / trackLength))
1370
-
1371
- const p = propsRef.current as PeriodSliderVernierProps
1372
- if (!p) return
1877
+ const pointerRatio = calcRatioFromPos(e.clientX, e.clientY, trackRef.current.getBoundingClientRect())
1878
+ if (pointerRatio === null) return
1373
1879
 
1374
1880
  if (vCtx.handle === "macro-low" || vCtx.handle === "macro-high" || vCtx.handle === "macro-connect") {
1375
1881
  const [nextMacroLowRatio, nextMacroHighRatio, activeMacroHandle] = calculateVernierMacroDrag(vCtx.handle, pointerRatio, vCtx.startPointerRatio, vCtx.startMacroLowRatio, vCtx.startMacroHighRatio)
@@ -1385,8 +1891,8 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1385
1891
  const maxIdx = sortedMacroAllowedDates.length - 1
1386
1892
  const lowIdx = Math.max(0, Math.min(maxIdx, Math.round(nextMacroLowRatio * maxIdx)))
1387
1893
  const highIdx = Math.max(lowIdx, Math.min(maxIdx, Math.round(nextMacroHighRatio * maxIdx)))
1388
- nextMacroLowDate = sortedMacroAllowedDates[lowIdx] ?? new Date()
1389
- nextMacroHighDate = sortedMacroAllowedDates[highIdx] ?? new Date()
1894
+ nextMacroLowDate = sortedMacroAllowedDates[lowIdx]
1895
+ nextMacroHighDate = sortedMacroAllowedDates[highIdx]
1390
1896
  } else {
1391
1897
  const nextLowEnc = Math.round(vernierMacroMinEnc + nextMacroLowRatio * macroSpan)
1392
1898
  const nextHighEnc = Math.round(vernierMacroMinEnc + nextMacroHighRatio * macroSpan)
@@ -1397,9 +1903,7 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1397
1903
  const macroKey = `${nextMacroLowDate.getTime()}_${nextMacroHighDate.getTime()}`
1398
1904
  if (macroKey !== lastEmittedMacroRangeRef.current) {
1399
1905
  lastEmittedMacroRangeRef.current = macroKey
1400
- p.onChangeMacroRange?.(nextMacroLowDate, nextMacroHighDate)
1401
- p.onChangeMacroRangeTuple?.([nextMacroLowDate, nextMacroHighDate])
1402
- p.onChangeMacro?.([nextMacroLowDate, nextMacroHighDate])
1906
+ notifyMacroRange(nextMacroLowDate, nextMacroHighDate)
1403
1907
  }
1404
1908
 
1405
1909
  // 異単位スケール間(例: 月×日)でのパン操作時の日数ズレを防ぐため、マクロ単位の暦月・暦年差分に基づいて平行移動
@@ -1445,7 +1949,7 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1445
1949
  nextMicroHighDate = normalizeDateByUnit(microUnit, new Date(targetHighMs))
1446
1950
  } else {
1447
1951
  // マクロ窓境界変更時の弾性復元 (Elastic Range Restoration & Push Clamp)
1448
- // 操作開始時の選択幅を維持しつつ、マクロ窓拡張時に記憶した初期境界まで自然復元
1952
+ // 記憶した初期境界を毎 move 生きた窓へ当て直すことで、窓を再拡張した際に選択が元位置へ戻る (クランプ後の値を確定させると戻らない)
1449
1953
  const minMs = nextMacroLowDate.getTime()
1450
1954
  const maxMs = getMacroWindowEndDate(macroUnit, microUnit, nextMacroHighDate).getTime()
1451
1955
  const targetLowMs = vCtx.initialMicroLowDate.getTime()
@@ -1461,8 +1965,7 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1461
1965
  const microKey = `${nextMicroLowDate.getTime()}_${nextMicroHighDate.getTime()}`
1462
1966
  if (microKey !== lastEmittedMicroRangeRef.current) {
1463
1967
  lastEmittedMicroRangeRef.current = microKey
1464
- p.onChangeRange?.(nextMicroLowDate, nextMicroHighDate)
1465
- p.onChangeRangeTuple?.([nextMicroLowDate, nextMicroHighDate])
1968
+ notifyMicroRange(nextMicroLowDate, nextMicroHighDate)
1466
1969
  }
1467
1970
  } else if (vCtx.handle === "micro-low" || vCtx.handle === "micro-high" || vCtx.handle === "micro-connect") {
1468
1971
  const [nextMicroLowRatio, nextMicroHighRatio, activeMicroHandle] = calculateVernierMicroDrag(vCtx.handle, pointerRatio, vCtx.startPointerRatio, vCtx.startMicroLowRatio, vCtx.startMicroHighRatio)
@@ -1478,8 +1981,8 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1478
1981
  const maxIdx = sortedMicroAllowedDates.length - 1
1479
1982
  const lowIdx = Math.max(0, Math.min(maxIdx, Math.round(nextMicroLowRatio * maxIdx)))
1480
1983
  const highIdx = Math.max(lowIdx, Math.min(maxIdx, Math.round(nextMicroHighRatio * maxIdx)))
1481
- nextMicroLowDate = sortedMicroAllowedDates[lowIdx] ?? new Date()
1482
- nextMicroHighDate = sortedMicroAllowedDates[highIdx] ?? new Date()
1984
+ nextMicroLowDate = sortedMicroAllowedDates[lowIdx]
1985
+ nextMicroHighDate = sortedMicroAllowedDates[highIdx]
1483
1986
  } else {
1484
1987
  const nextMicroLowEnc = Math.round(vernierMicroMinEnc + nextMicroLowRatio * microSpan)
1485
1988
  const nextMicroHighEnc = Math.round(vernierMicroMinEnc + nextMicroHighRatio * microSpan)
@@ -1490,8 +1993,7 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1490
1993
  const microKey = `${nextMicroLowDate.getTime()}_${nextMicroHighDate.getTime()}`
1491
1994
  if (microKey !== lastEmittedMicroRangeRef.current) {
1492
1995
  lastEmittedMicroRangeRef.current = microKey
1493
- p.onChangeRange?.(nextMicroLowDate, nextMicroHighDate)
1494
- p.onChangeRangeTuple?.([nextMicroLowDate, nextMicroHighDate])
1996
+ notifyMicroRange(nextMicroLowDate, nextMicroHighDate)
1495
1997
  }
1496
1998
  }
1497
1999
  return
@@ -1504,25 +2006,35 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1504
2006
  const rect = trackRef.current.getBoundingClientRect()
1505
2007
  const currentPos = isVertical ? e.clientY : e.clientX
1506
2008
  const trackLength = isVertical ? rect.height : rect.width
1507
- if (trackLength <= 0) return
2009
+ if (!(Number.isFinite(trackLength) && trackLength > 0)) return
1508
2010
 
1509
2011
  if (ctx.handle === "connect") {
1510
2012
  const rawDiffPct = isVertical ? (ctx.startPointerPos - currentPos) / trackLength : (currentPos - ctx.startPointerPos) / trackLength
1511
2013
 
1512
- const res = calculateConnectDragValues(rawDiffPct, ctx.startLowVal, ctx.startHighVal, rangeMin, rangeMax, isDiscrete, sortedAllowedDates)
1513
- if (res) {
1514
- if (latestDraggingValuesRef.current && latestDraggingValuesRef.current[0] === res[0] && latestDraggingValuesRef.current[1] === res[1]) {
1515
- return
1516
- }
1517
- latestDraggingValuesRef.current = res
1518
- setDraggingValues(res)
1519
- notifyChange(res[0], res[1], false)
2014
+ const res = calculateConnectDragValues({
2015
+ posDiffPct: rawDiffPct,
2016
+ startLowVal: ctx.startLowVal,
2017
+ startHighVal: ctx.startHighVal,
2018
+ rangeMin,
2019
+ rangeMax,
2020
+ isDiscrete,
2021
+ sortedAllowedDates,
2022
+ snapMode,
2023
+ unit,
2024
+ })
2025
+ if (latestDraggingValuesRef.current && latestDraggingValuesRef.current[0] === res[0] && latestDraggingValuesRef.current[1] === res[1]) {
2026
+ return
1520
2027
  }
2028
+ latestDraggingValuesRef.current = res
2029
+ setDraggingValues(res)
2030
+ notifyChange(res[0], res[1], false)
1521
2031
  return
1522
2032
  }
1523
2033
 
1524
- const pct = getTrackPctFromPointer(e.clientX, e.clientY)
1525
- const clickedVal = pctToValue(pct)
2034
+ // 長さガードで読んだ矩形を再利用する。読み直すと 1 move につき同期レイアウトが 2 回走る
2035
+ const ratio = calcRatioFromPos(e.clientX, e.clientY, rect)
2036
+ if (ratio === null) return
2037
+ const clickedVal = pctToValue(ratio * 100)
1526
2038
 
1527
2039
  const [nextLow, nextHigh] = calculateHandleDragValues(ctx.handle, clickedVal, ctx.startLowVal, ctx.startHighVal, rangeMin, rangeMax, isPointMode)
1528
2040
  if (!latestDraggingValuesRef.current || latestDraggingValuesRef.current[0] !== nextLow || latestDraggingValuesRef.current[1] !== nextHigh) {
@@ -1558,9 +2070,13 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1558
2070
  rangeMax,
1559
2071
  isDiscrete,
1560
2072
  sortedAllowedDates,
1561
- getTrackPctFromPointer,
2073
+ snapMode,
2074
+ unit,
2075
+ calcRatioFromPos,
1562
2076
  pctToValue,
1563
2077
  notifyChange,
2078
+ notifyMacroRange,
2079
+ notifyMicroRange,
1564
2080
  isPointMode,
1565
2081
  ],
1566
2082
  )
@@ -1573,6 +2089,9 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1573
2089
  vernierDragContextRef.current = null
1574
2090
  activeVernierHandleRef.current = null
1575
2091
  setActiveVernierHandle(null)
2092
+ // 予約したままドラッグを終えると、指を離した位置の値が発火されずに消える
2093
+ flushPendingEmit(macroEmitRef.current)
2094
+ flushPendingEmit(microEmitRef.current)
1576
2095
  return
1577
2096
  }
1578
2097
 
@@ -1591,7 +2110,7 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1591
2110
  activeHandleRef.current = null
1592
2111
  setActiveHandle(null)
1593
2112
  },
1594
- [isVernierMode, draggingValues, notifyChange],
2113
+ [isVernierMode, draggingValues, notifyChange, flushPendingEmit],
1595
2114
  )
1596
2115
 
1597
2116
  const handlePointerMoveRef = useRef(handleGlobalPointerMove)
@@ -1639,7 +2158,8 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1639
2158
 
1640
2159
  const startVernierDrag = useCallback(
1641
2160
  (pointerId: number, handle: VernierHandle, startPointerRatio: number) => {
1642
- const p = propsRef.current as PeriodSliderVernierProps
2161
+ const p = propsRef.current
2162
+ if (p.mode !== "vernier") return
1643
2163
  vernierDragContextRef.current = {
1644
2164
  pointerId,
1645
2165
  handle,
@@ -1654,14 +2174,14 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1654
2174
  startMicroHighEnc: vernierMicroHighEnc,
1655
2175
  startMacroLowDate: p.macroRange[0],
1656
2176
  startMacroHighDate: p.macroRange[1],
1657
- initialMicroLowDate: safeLowerDate,
1658
- initialMicroHighDate: safeUpperDate,
2177
+ initialMicroLowDate: vernierMicroLowDate,
2178
+ initialMicroHighDate: vernierMicroHighDate,
1659
2179
  }
1660
2180
  activeVernierHandleRef.current = handle
1661
2181
  setActiveVernierHandle(handle)
1662
2182
  setFrontVernierHandle(handle)
1663
2183
  },
1664
- [macroLowRatio, macroHighRatio, microLowRatio, microHighRatio, vernierMacroLowEnc, vernierMacroHighEnc, vernierMicroLowEnc, vernierMicroHighEnc],
2184
+ [macroLowRatio, macroHighRatio, microLowRatio, microHighRatio, vernierMacroLowEnc, vernierMacroHighEnc, vernierMicroLowEnc, vernierMicroHighEnc, vernierMicroLowDate, vernierMicroHighDate],
1665
2185
  )
1666
2186
 
1667
2187
  const handleKnobPointerDown = (handle: "low" | "high") => (e: React.PointerEvent<HTMLDivElement>) => {
@@ -1677,9 +2197,10 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1677
2197
  if (disabled) return
1678
2198
  e.stopPropagation()
1679
2199
  e.preventDefault()
1680
- if (!trackRef.current) return
1681
- const rect = trackRef.current.getBoundingClientRect()
1682
- const pointerRatio = isVertical ? Math.max(0, Math.min(1, (rect.bottom - e.clientY) / (rect.height > 0 ? rect.height : 100))) : Math.max(0, Math.min(1, (e.clientX - rect.left) / (rect.width > 0 ? rect.width : 100)))
2200
+ const el = trackRef.current
2201
+ if (!el) return
2202
+ const pointerRatio = calcRatioFromPos(e.clientX, e.clientY, el.getBoundingClientRect())
2203
+ if (pointerRatio === null) return
1683
2204
  startVernierDrag(e.pointerId, handle, pointerRatio)
1684
2205
  }
1685
2206
 
@@ -1695,9 +2216,11 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1695
2216
  if (disabled) return
1696
2217
 
1697
2218
  if (isVernierMode) {
1698
- if (!trackRef.current) return
1699
- const rect = trackRef.current.getBoundingClientRect()
1700
- const pointerRatio = isVertical ? Math.max(0, Math.min(1, (rect.bottom - e.clientY) / (rect.height > 0 ? rect.height : 100))) : Math.max(0, Math.min(1, (e.clientX - rect.left) / (rect.width > 0 ? rect.width : 100)))
2219
+ const el = trackRef.current
2220
+ if (!el) return
2221
+ const rect = el.getBoundingClientRect()
2222
+ const pointerRatio = calcRatioFromPos(e.clientX, e.clientY, rect)
2223
+ if (pointerRatio === null) return
1701
2224
  const pointerCrossAxisOffset = isVertical ? e.clientX - (rect.left + rect.width / 2) : e.clientY - (rect.top + rect.height / 2)
1702
2225
  const targetHandle = resolveVernierTargetHandle(pointerRatio, pointerCrossAxisOffset, macroLowRatio, macroHighRatio, microLowRatio, microHighRatio, vernierOrientation)
1703
2226
  startVernierDrag(e.pointerId, targetHandle, pointerRatio)
@@ -1705,6 +2228,7 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1705
2228
  }
1706
2229
 
1707
2230
  const pct = getTrackPctFromPointer(e.clientX, e.clientY)
2231
+ if (pct === null) return
1708
2232
  const clickedVal = pctToValue(pct)
1709
2233
 
1710
2234
  let chosenHandle: "low" | "high" = "low"
@@ -1732,6 +2256,7 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1732
2256
  const handleTrackPointerMove = (e: React.PointerEvent<HTMLDivElement>) => {
1733
2257
  if (disabled || activeHandle !== null) return
1734
2258
  const pct = getTrackPctFromPointer(e.clientX, e.clientY)
2259
+ if (pct === null) return
1735
2260
  const val = pctToValue(pct)
1736
2261
  setHoverValue(val)
1737
2262
  setHoverPct(valueToPct(val))
@@ -1743,7 +2268,7 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1743
2268
  }
1744
2269
 
1745
2270
  // ------------------------------------------------------------------
1746
- // H. Keyboard & Stepper Operations
2271
+ // H. キーボードとステッパー操作
1747
2272
  // ------------------------------------------------------------------
1748
2273
  const handleKeyDown = (handle: "low" | "high") => (e: React.KeyboardEvent<HTMLDivElement>) => {
1749
2274
  if (disabled) return
@@ -1797,44 +2322,58 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1797
2322
  }
1798
2323
  e.preventDefault()
1799
2324
 
1800
- const notifyMacro = (low: Date, high: Date) => {
1801
- props.onChangeMacroRange?.(low, high)
1802
- props.onChangeMacroRangeTuple?.([low, high])
1803
- props.onChangeMacro?.([low, high])
1804
- }
1805
-
1806
- const notifyMicro = (low: Date, high: Date) => {
1807
- props.onChangeRange?.(low, high)
1808
- props.onChangeRangeTuple?.([low, high])
1809
- props.onChangeMicroRange?.(low, high)
1810
- props.onChangeMicroRangeTuple?.([low, high])
1811
- props.onChangeMicro?.([low, high])
1812
- }
2325
+ // 離散指定時はポインター操作と同じ候補集合の上を移動しないと、キーボードだけが候補外の日付を発火する
2326
+ const macroIsDiscreteScale = macroIsDiscrete && sortedMacroAllowedDates.length > 0
2327
+ const microIsDiscreteScale = microIsDiscrete && sortedMicroAllowedDates.length > 0
1813
2328
 
1814
2329
  if (handle === "macro-low") {
2330
+ const currentLow = decode(macroUnit, vernierMacroLowEnc)
2331
+ const currentHigh = decode(macroUnit, vernierMacroHighEnc)
2332
+ if (macroIsDiscreteScale) {
2333
+ notifyMacroRange(stepDiscreteDate(sortedMacroAllowedDates, macroUnit, currentLow, sortedMacroAllowedDates[0], currentHigh, delta, isHome, isEnd), currentHigh, true)
2334
+ return
2335
+ }
1815
2336
  let next: number
1816
2337
  if (isHome) next = vernierMacroMinEnc
1817
2338
  else if (isEnd) next = vernierMacroHighEnc
1818
2339
  else next = Math.max(vernierMacroMinEnc, Math.min(vernierMacroHighEnc, vernierMacroLowEnc + delta))
1819
- notifyMacro(decode(macroUnit, next), decode(macroUnit, vernierMacroHighEnc))
2340
+ notifyMacroRange(decode(macroUnit, next), currentHigh, true)
1820
2341
  } else if (handle === "macro-high") {
2342
+ const currentLow = decode(macroUnit, vernierMacroLowEnc)
2343
+ const currentHigh = decode(macroUnit, vernierMacroHighEnc)
2344
+ if (macroIsDiscreteScale) {
2345
+ notifyMacroRange(currentLow, stepDiscreteDate(sortedMacroAllowedDates, macroUnit, currentHigh, currentLow, sortedMacroAllowedDates[sortedMacroAllowedDates.length - 1], delta, isHome, isEnd), true)
2346
+ return
2347
+ }
1821
2348
  let next: number
1822
2349
  if (isHome) next = vernierMacroLowEnc
1823
2350
  else if (isEnd) next = vernierMacroMaxEnc
1824
2351
  else next = Math.max(vernierMacroLowEnc, Math.min(vernierMacroMaxEnc, vernierMacroHighEnc + delta))
1825
- notifyMacro(decode(macroUnit, vernierMacroLowEnc), decode(macroUnit, next))
2352
+ notifyMacroRange(currentLow, decode(macroUnit, next), true)
1826
2353
  } else if (handle === "micro-low") {
2354
+ const currentLow = decode(microUnit, vernierMicroLowEnc)
2355
+ const currentHigh = decode(microUnit, vernierMicroHighEnc)
2356
+ if (microIsDiscreteScale) {
2357
+ notifyMicroRange(stepDiscreteDate(sortedMicroAllowedDates, microUnit, currentLow, sortedMicroAllowedDates[0], currentHigh, delta, isHome, isEnd), currentHigh, true)
2358
+ return
2359
+ }
1827
2360
  let next: number
1828
2361
  if (isHome) next = vernierMicroMinEnc
1829
2362
  else if (isEnd) next = vernierMicroHighEnc
1830
2363
  else next = Math.max(vernierMicroMinEnc, Math.min(vernierMicroHighEnc, vernierMicroLowEnc + delta))
1831
- notifyMicro(decode(microUnit, next), decode(microUnit, vernierMicroHighEnc))
2364
+ notifyMicroRange(decode(microUnit, next), currentHigh, true)
1832
2365
  } else if (handle === "micro-high") {
2366
+ const currentLow = decode(microUnit, vernierMicroLowEnc)
2367
+ const currentHigh = decode(microUnit, vernierMicroHighEnc)
2368
+ if (microIsDiscreteScale) {
2369
+ notifyMicroRange(currentLow, stepDiscreteDate(sortedMicroAllowedDates, microUnit, currentHigh, currentLow, sortedMicroAllowedDates[sortedMicroAllowedDates.length - 1], delta, isHome, isEnd), true)
2370
+ return
2371
+ }
1833
2372
  let next: number
1834
2373
  if (isHome) next = vernierMicroLowEnc
1835
2374
  else if (isEnd) next = vernierMicroMaxEnc
1836
2375
  else next = Math.max(vernierMicroLowEnc, Math.min(vernierMicroMaxEnc, vernierMicroHighEnc + delta))
1837
- notifyMicro(decode(microUnit, vernierMicroLowEnc), decode(microUnit, next))
2376
+ notifyMicroRange(currentLow, decode(microUnit, next), true)
1838
2377
  }
1839
2378
  }
1840
2379
 
@@ -1865,10 +2404,7 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1865
2404
  nextLow = Math.max(minEnc, nextHigh - span)
1866
2405
  }
1867
2406
  if (nextLow !== curLowEnc || nextHigh !== curHighEnc) {
1868
- const lowD = decode(microUnit, nextLow)
1869
- const highD = decode(microUnit, nextHigh)
1870
- p.onChangeRange?.(lowD, highD)
1871
- p.onChangeRangeTuple?.([lowD, highD])
2407
+ notifyMicroRange(decode(microUnit, nextLow), decode(microUnit, nextHigh), true)
1872
2408
  }
1873
2409
  } else {
1874
2410
  const span = currentHighVal - currentLowVal
@@ -1889,11 +2425,11 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1889
2425
  }
1890
2426
  }
1891
2427
  },
1892
- [currentLowVal, currentHighVal, rangeMin, rangeMax, isControlled, notifyChange, vernierMicroLowEnc, vernierMicroHighEnc, vernierMicroMinEnc, vernierMicroMaxEnc, microUnit],
2428
+ [currentLowVal, currentHighVal, rangeMin, rangeMax, isControlled, notifyChange, notifyMicroRange, vernierMicroLowEnc, vernierMicroHighEnc, vernierMicroMinEnc, vernierMicroMaxEnc, microUnit],
1893
2429
  )
1894
2430
 
1895
2431
  // ------------------------------------------------------------------
1896
- // I. Visual Position & Style Calculations
2432
+ // I. 表示位置とスタイル計算
1897
2433
  // ------------------------------------------------------------------
1898
2434
  const lowPct = valueToPct(currentLowVal)
1899
2435
  const highPct = valueToPct(currentHighVal)
@@ -1901,24 +2437,21 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1901
2437
  const lowDate = valueToDate(currentLowVal)
1902
2438
  const highDate = valueToDate(currentHighVal)
1903
2439
 
1904
- // Mathematical collision avoidance for range mode handles
1905
- const slantResult: LabelSlantResult = useMemo(() => {
1906
- // Unified baseline: clearance 10px from track center + labelHeight / 2 (8px) = 18px
1907
- const baseOffsetY = labelPosition === "top" ? -18 : 18
1908
- if (isPointMode || !autoSlantLabels || isVertical) {
1909
- return {
1910
- lowAngleDeg: 0,
1911
- highAngleDeg: 0,
1912
- lowOffsetX: 0,
1913
- highOffsetX: 0,
1914
- lowOffsetY: baseOffsetY,
1915
- highOffsetY: baseOffsetY,
1916
- isSlanted: false,
1917
- proximity: 0,
1918
- }
2440
+ // 衝突回避は 2 枚のラベルの実寸で決まる。片方でも未実測なら広い方が分からず、押し出し量を誤って
2441
+ // トラックへ食い込ませるため、point モード (ラベル 1 枚) 以外は両方揃うまで実寸なしとして扱う
2442
+ const labelSlantConfig: LabelSlantConfig | undefined = useMemo(() => {
2443
+ if (isPointMode) return lowLabelBox === null ? undefined : { estimatedWidthPx: lowLabelBox.widthPx, estimatedHeightPx: lowLabelBox.heightPx }
2444
+ if (lowLabelBox === null || highLabelBox === null) return undefined
2445
+ return {
2446
+ estimatedWidthPx: Math.max(lowLabelBox.widthPx, highLabelBox.widthPx),
2447
+ estimatedHeightPx: Math.max(lowLabelBox.heightPx, highLabelBox.heightPx),
1919
2448
  }
1920
- return calculateLabelSlant(lowPct, highPct, trackWidth, labelPosition, unit)
1921
- }, [isPointMode, autoSlantLabels, isVertical, lowPct, highPct, trackWidth, labelPosition, unit])
2449
+ }, [isPointMode, lowLabelBox, highLabelBox])
2450
+
2451
+ const slantResult: LabelSlantResult = useMemo(() => {
2452
+ if (isPointMode || !autoSlantLabels || isVertical) return buildHorizontalSlantResult(labelPosition, labelSlantConfig)
2453
+ return calculateLabelSlant(lowPct, highPct, trackLength, labelPosition, labelSlantConfig)
2454
+ }, [isPointMode, autoSlantLabels, isVertical, lowPct, highPct, trackLength, labelPosition, labelSlantConfig])
1922
2455
 
1923
2456
  const isLowFront = activeHandle === "low" || (activeHandle !== "high" && frontHandle === "low")
1924
2457
  const isHighFront = !isPointMode && (activeHandle === "high" || (activeHandle !== "low" && frontHandle === "high"))
@@ -1988,14 +2521,38 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1988
2521
 
1989
2522
  const hoverDate = hoverValue !== null ? valueToDate(hoverValue) : null
1990
2523
 
1991
- const stepperPrevDisabled = disabled || (isVernierMode ? vernierMicroLowEnc <= vernierMicroMinEnc : isPointMode ? currentLowVal <= rangeMin : currentLowVal <= rangeMin && currentHighVal <= rangeMin)
1992
- const stepperNextDisabled = disabled || (isVernierMode ? vernierMicroHighEnc >= vernierMicroMaxEnc : isPointMode ? currentHighVal >= rangeMax : currentLowVal >= rangeMax && currentHighVal >= rangeMax)
2524
+ const stepperDecreaseDisabled = disabled || (isVernierMode ? vernierMicroLowEnc <= vernierMicroMinEnc : isPointMode ? currentLowVal <= rangeMin : currentLowVal <= rangeMin && currentHighVal <= rangeMin)
2525
+ const stepperIncreaseDisabled = disabled || (isVernierMode ? vernierMicroHighEnc >= vernierMicroMaxEnc : isPointMode ? currentHighVal >= rangeMax : currentLowVal >= rangeMax && currentHighVal >= rangeMax)
1993
2526
 
1994
2527
  const cursorClass = disabled ? "cursor-not-allowed opacity-50" : "cursor-pointer"
1995
2528
 
1996
2529
  // ------------------------------------------------------------------
1997
- // J. JSX Render Assembly
2530
+ // J. JSX 組み立て
1998
2531
  // ------------------------------------------------------------------
2532
+ /**
2533
+ * Renders one stepper button identified by what it does to the value, never by where it sits.
2534
+ * 配置ではなく値への作用で識別したステッパーボタン 1 つを描画する関数。
2535
+ *
2536
+ * @param direction - "decrease" steps toward minDate, "increase" steps toward maxDate / "decrease" は minDate 方向、"increase" は maxDate 方向へ 1 単位
2537
+ * @returns Stepper button element / ステッパーボタン要素
2538
+ */
2539
+ const renderStepperButton = (direction: StepDirection): React.JSX.Element => {
2540
+ const axis = isVertical ? "vertical" : "horizontal"
2541
+ const isDecrease = direction === "decrease"
2542
+ const positionClass = STEPPER_POSITION_CLASSES[axis][direction]
2543
+
2544
+ return (
2545
+ <button
2546
+ type="button"
2547
+ className={`period-slider-stepper-btn relative after:absolute after:inset-[-11px] after:content-[''] ${positionClass} flex h-6 w-6 shrink-0 items-center justify-center rounded-md border border-slate-300 bg-white font-bold text-[10px] text-slate-700 leading-none shadow-2xs transition-all hover:bg-slate-100 hover:text-indigo-600 focus:outline-none focus-visible:ring-2 focus-visible:ring-blue-600 active:scale-95 disabled:cursor-not-allowed disabled:opacity-30 dark:border-slate-700 dark:bg-slate-800 dark:text-slate-200 dark:hover:bg-slate-700 ${cursorClass}`}
2548
+ onClick={() => shift(isDecrease ? -1 : 1)}
2549
+ disabled={isDecrease ? stepperDecreaseDisabled : stepperIncreaseDisabled}
2550
+ aria-label={isDecrease ? decreaseAriaLabel : increaseAriaLabel}>
2551
+ {STEPPER_GLYPHS[axis][direction]}
2552
+ </button>
2553
+ )
2554
+ }
2555
+
1999
2556
  return (
2000
2557
  <div
2001
2558
  style={props.style}
@@ -2006,17 +2563,8 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
2006
2563
  data-orientation={isVertical ? "vertical" : "horizontal"}
2007
2564
  data-label-position={labelPosition}
2008
2565
  data-color-scheme={colorScheme}>
2009
- {/* ◀ 1ステップ戻るボタン / 垂直時は ▲ 1ステップ進むボタン */}
2010
- {showStepper && (
2011
- <button
2012
- type="button"
2013
- className={`period-slider-stepper-btn relative after:absolute after:inset-[-10px] after:content-[''] ${isVertical ? "period-slider-stepper-next period-slider-stepper-up" : "period-slider-stepper-prev"} flex h-6 w-6 shrink-0 items-center justify-center rounded-md border border-slate-300 bg-white font-bold text-[10px] text-slate-700 leading-none shadow-2xs transition-all hover:bg-slate-100 hover:text-indigo-600 focus:outline-none focus-visible:ring-2 focus-visible:ring-blue-600 active:scale-95 disabled:cursor-not-allowed disabled:opacity-30 dark:border-slate-700 dark:bg-slate-800 dark:text-slate-200 dark:hover:bg-slate-700 ${cursorClass}`}
2014
- onClick={() => shift(isVertical ? 1 : -1)}
2015
- disabled={isVertical ? stepperNextDisabled : stepperPrevDisabled}
2016
- aria-label={isVertical ? "1つ後へ" : "1つ前へ"}>
2017
- {isVertical ? "▲" : "◀"}
2018
- </button>
2019
- )}
2566
+ {/* 先頭のステッパー: 横向きは左端が定義域の下限なので減少、縦向きは上端が上限なので増加 */}
2567
+ {showStepper && renderStepperButton(isVertical ? "increase" : "decrease")}
2020
2568
 
2021
2569
  {/* スライダートラック */}
2022
2570
  <div
@@ -2092,10 +2640,10 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
2092
2640
  {showVernierTicks && (
2093
2641
  <div className="period-slider-vernier-ticks pointer-events-none absolute inset-0">
2094
2642
  {[0.2, 0.4, 0.6, 0.8].map((t) => (
2095
- <div key={`macro-tick-${t}`} className="period-slider-tick period-slider-tick-macro" style={isVertical ? { bottom: `${t * 100}%` } : { left: `${t * 100}%` }} />
2643
+ <div key={`macro-tick-${t}`} data-testid="period-slider-tick" data-tick-scale="macro" className="period-slider-tick period-slider-tick-macro" style={isVertical ? { bottom: `${t * 100}%` } : { left: `${t * 100}%` }} />
2096
2644
  ))}
2097
2645
  {[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9].map((t) => (
2098
- <div key={`micro-tick-${t}`} className="period-slider-tick period-slider-tick-micro" style={isVertical ? { bottom: `${t * 100}%` } : { left: `${t * 100}%` }} />
2646
+ <div key={`micro-tick-${t}`} data-testid="period-slider-tick" data-tick-scale="micro" className="period-slider-tick period-slider-tick-micro" style={isVertical ? { bottom: `${t * 100}%` } : { left: `${t * 100}%` }} />
2099
2647
  ))}
2100
2648
  </div>
2101
2649
  )}
@@ -2104,21 +2652,21 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
2104
2652
  <div
2105
2653
  tabIndex={disabled ? -1 : 0}
2106
2654
  role="slider"
2107
- aria-label={props.macroLowerAriaLabel ?? "マクロ開始時期"}
2655
+ aria-label={props.macroLowerAriaLabel ?? "Macro range start"}
2108
2656
  aria-disabled={disabled ? "true" : undefined}
2109
2657
  aria-valuemin={vernierMacroMinEnc}
2110
2658
  aria-valuemax={vernierMacroHighEnc}
2111
2659
  aria-valuenow={vernierMacroLowEnc}
2112
- aria-valuetext={props.formatAriaValueText ? props.formatAriaValueText(props.macroRange[0], macroUnit) : formatScreenReaderLabel(macroUnit, props.macroRange[0], formatMacroLabel)}
2660
+ aria-valuetext={props.formatAriaValueText ? props.formatAriaValueText(props.macroRange[0], macroUnit) : formatScreenReaderLabel(macroUnit, props.macroRange[0], formatMacroLabel, locale)}
2113
2661
  aria-orientation={isVertical ? "vertical" : "horizontal"}
2114
2662
  className={`period-slider-handle period-slider-handle-vernier ${isVertical ? "is-vertical" : ""} group absolute touch-none ${
2115
2663
  isVertical
2116
2664
  ? isMacroFirstRail
2117
- ? "after:absolute after:-inset-y-3 after:right-0 after:-left-3"
2118
- : "after:absolute after:-inset-y-3 after:-right-3 after:left-0"
2665
+ ? "after:absolute after:-inset-y-3 after:right-0 after:-left-4"
2666
+ : "after:absolute after:-inset-y-3 after:-right-4 after:left-0"
2119
2667
  : isMacroFirstRail
2120
- ? "after:absolute after:-inset-x-3 after:-top-3 after:bottom-0"
2121
- : "after:absolute after:-inset-x-3 after:top-0 after:-bottom-3"
2668
+ ? "after:absolute after:-inset-x-3 after:-top-4 after:bottom-0"
2669
+ : "after:absolute after:-inset-x-3 after:top-0 after:-bottom-4"
2122
2670
  } after:content-[''] focus:outline-none focus-visible:ring-2 focus-visible:ring-blue-600 focus-visible:ring-offset-2 ${cursorClass}`}
2123
2671
  style={
2124
2672
  isVertical
@@ -2145,28 +2693,28 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
2145
2693
  data-handle-type="macro-low">
2146
2694
  <VernierKnobSvg type="macro" isTop={isMacroFirstRail} isVertical={isVertical} isLeft={isMacroFirstRail} />
2147
2695
  {showHairline && <div className="period-slider-hairline" />}
2148
- <div className="period-slider-tooltip absolute whitespace-nowrap rounded bg-slate-900 px-2 py-0.5 font-medium text-white text-xs shadow-md dark:bg-slate-800">{formatLabel(macroUnit, props.macroRange[0], formatMacroLabel)}</div>
2696
+ <div className="period-slider-tooltip absolute whitespace-nowrap rounded bg-slate-900 px-2 py-0.5 font-medium text-white text-xs shadow-md dark:bg-slate-800">{formatLabel(macroUnit, props.macroRange[0], formatMacroLabel, locale)}</div>
2149
2697
  </div>
2150
2698
 
2151
2699
  {/* マクロ上限ハンドル (上半円爪 / 左半円爪) */}
2152
2700
  <div
2153
2701
  tabIndex={disabled ? -1 : 0}
2154
2702
  role="slider"
2155
- aria-label={props.macroUpperAriaLabel ?? "マクロ終了時期"}
2703
+ aria-label={props.macroUpperAriaLabel ?? "Macro range end"}
2156
2704
  aria-disabled={disabled ? "true" : undefined}
2157
2705
  aria-valuemin={vernierMacroLowEnc}
2158
2706
  aria-valuemax={vernierMacroMaxEnc}
2159
2707
  aria-valuenow={vernierMacroHighEnc}
2160
- aria-valuetext={props.formatAriaValueText ? props.formatAriaValueText(props.macroRange[1], macroUnit) : formatScreenReaderLabel(macroUnit, props.macroRange[1], formatMacroLabel)}
2708
+ aria-valuetext={props.formatAriaValueText ? props.formatAriaValueText(props.macroRange[1], macroUnit) : formatScreenReaderLabel(macroUnit, props.macroRange[1], formatMacroLabel, locale)}
2161
2709
  aria-orientation={isVertical ? "vertical" : "horizontal"}
2162
2710
  className={`period-slider-handle period-slider-handle-vernier ${isVertical ? "is-vertical" : ""} group absolute touch-none ${
2163
2711
  isVertical
2164
2712
  ? isMacroFirstRail
2165
- ? "after:absolute after:-inset-y-3 after:right-0 after:-left-3"
2166
- : "after:absolute after:-inset-y-3 after:-right-3 after:left-0"
2713
+ ? "after:absolute after:-inset-y-3 after:right-0 after:-left-4"
2714
+ : "after:absolute after:-inset-y-3 after:-right-4 after:left-0"
2167
2715
  : isMacroFirstRail
2168
- ? "after:absolute after:-inset-x-3 after:-top-3 after:bottom-0"
2169
- : "after:absolute after:-inset-x-3 after:top-0 after:-bottom-3"
2716
+ ? "after:absolute after:-inset-x-3 after:-top-4 after:bottom-0"
2717
+ : "after:absolute after:-inset-x-3 after:top-0 after:-bottom-4"
2170
2718
  } after:content-[''] focus:outline-none focus-visible:ring-2 focus-visible:ring-blue-600 focus-visible:ring-offset-2 ${cursorClass}`}
2171
2719
  style={
2172
2720
  isVertical
@@ -2193,28 +2741,28 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
2193
2741
  data-handle-type="macro-high">
2194
2742
  <VernierKnobSvg type="macro" isTop={isMacroFirstRail} isVertical={isVertical} isLeft={isMacroFirstRail} />
2195
2743
  {showHairline && <div className="period-slider-hairline" />}
2196
- <div className="period-slider-tooltip absolute whitespace-nowrap rounded bg-slate-900 px-2 py-0.5 font-medium text-white text-xs shadow-md dark:bg-slate-800">{formatLabel(macroUnit, props.macroRange[1], formatMacroLabel)}</div>
2744
+ <div className="period-slider-tooltip absolute whitespace-nowrap rounded bg-slate-900 px-2 py-0.5 font-medium text-white text-xs shadow-md dark:bg-slate-800">{formatLabel(macroUnit, props.macroRange[1], formatMacroLabel, locale)}</div>
2197
2745
  </div>
2198
2746
 
2199
2747
  {/* ミクロ下限ハンドル (下半円爪 / 右半円爪) */}
2200
2748
  <div
2201
2749
  tabIndex={disabled ? -1 : 0}
2202
2750
  role="slider"
2203
- aria-label={props.lowerAriaLabel ?? "ミクロ開始時期"}
2751
+ aria-label={props.lowerAriaLabel ?? "Micro range start"}
2204
2752
  aria-disabled={disabled ? "true" : undefined}
2205
2753
  aria-valuemin={vernierMicroMinEnc}
2206
2754
  aria-valuemax={vernierMicroHighEnc}
2207
2755
  aria-valuenow={vernierMicroLowEnc}
2208
- aria-valuetext={props.formatAriaValueText ? props.formatAriaValueText(safeLowerDate, microUnit) : formatScreenReaderLabel(microUnit, safeLowerDate, formatMicroLabel)}
2756
+ aria-valuetext={props.formatAriaValueText ? props.formatAriaValueText(vernierMicroLowDate, microUnit) : formatScreenReaderLabel(microUnit, vernierMicroLowDate, formatMicroLabel, locale)}
2209
2757
  aria-orientation={isVertical ? "vertical" : "horizontal"}
2210
2758
  className={`period-slider-handle period-slider-handle-vernier ${isVertical ? "is-vertical" : ""} group absolute touch-none ${
2211
2759
  isVertical
2212
2760
  ? isMacroFirstRail
2213
- ? "after:absolute after:-inset-y-3 after:-right-3 after:left-0"
2214
- : "after:absolute after:-inset-y-3 after:right-0 after:-left-3"
2761
+ ? "after:absolute after:-inset-y-3 after:-right-4 after:left-0"
2762
+ : "after:absolute after:-inset-y-3 after:right-0 after:-left-4"
2215
2763
  : isMacroFirstRail
2216
- ? "after:absolute after:-inset-x-3 after:top-0 after:-bottom-3"
2217
- : "after:absolute after:-inset-x-3 after:-top-3 after:bottom-0"
2764
+ ? "after:absolute after:-inset-x-3 after:top-0 after:-bottom-4"
2765
+ : "after:absolute after:-inset-x-3 after:-top-4 after:bottom-0"
2218
2766
  } after:content-[''] focus:outline-none focus-visible:ring-2 focus-visible:ring-blue-600 focus-visible:ring-offset-2 ${cursorClass}`}
2219
2767
  style={
2220
2768
  isVertical
@@ -2241,28 +2789,28 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
2241
2789
  data-handle-type="micro-low">
2242
2790
  <VernierKnobSvg type="micro" isTop={!isMacroFirstRail} isVertical={isVertical} isLeft={!isMacroFirstRail} />
2243
2791
  {showHairline && <div className="period-slider-hairline" />}
2244
- <div className="period-slider-tooltip absolute whitespace-nowrap rounded bg-slate-900 px-2 py-0.5 font-medium text-white text-xs shadow-md dark:bg-slate-800">{formatLabel(microUnit, safeLowerDate, formatMicroLabel)}</div>
2792
+ <div className="period-slider-tooltip absolute whitespace-nowrap rounded bg-slate-900 px-2 py-0.5 font-medium text-white text-xs shadow-md dark:bg-slate-800">{formatLabel(microUnit, vernierMicroLowDate, formatMicroLabel, locale)}</div>
2245
2793
  </div>
2246
2794
 
2247
2795
  {/* ミクロ上限ハンドル (下半円爪 / 右半円爪) */}
2248
2796
  <div
2249
2797
  tabIndex={disabled ? -1 : 0}
2250
2798
  role="slider"
2251
- aria-label={props.upperAriaLabel ?? "ミクロ終了時期"}
2799
+ aria-label={props.upperAriaLabel ?? "Micro range end"}
2252
2800
  aria-disabled={disabled ? "true" : undefined}
2253
2801
  aria-valuemin={vernierMicroLowEnc}
2254
2802
  aria-valuemax={vernierMicroMaxEnc}
2255
2803
  aria-valuenow={vernierMicroHighEnc}
2256
- aria-valuetext={props.formatAriaValueText ? props.formatAriaValueText(safeUpperDate, microUnit) : formatScreenReaderLabel(microUnit, safeUpperDate, formatMicroLabel)}
2804
+ aria-valuetext={props.formatAriaValueText ? props.formatAriaValueText(vernierMicroHighDate, microUnit) : formatScreenReaderLabel(microUnit, vernierMicroHighDate, formatMicroLabel, locale)}
2257
2805
  aria-orientation={isVertical ? "vertical" : "horizontal"}
2258
2806
  className={`period-slider-handle period-slider-handle-vernier ${isVertical ? "is-vertical" : ""} group absolute touch-none ${
2259
2807
  isVertical
2260
2808
  ? isMacroFirstRail
2261
- ? "after:absolute after:-inset-y-3 after:-right-3 after:left-0"
2262
- : "after:absolute after:-inset-y-3 after:right-0 after:-left-3"
2809
+ ? "after:absolute after:-inset-y-3 after:-right-4 after:left-0"
2810
+ : "after:absolute after:-inset-y-3 after:right-0 after:-left-4"
2263
2811
  : isMacroFirstRail
2264
- ? "after:absolute after:-inset-x-3 after:top-0 after:-bottom-3"
2265
- : "after:absolute after:-inset-x-3 after:-top-3 after:bottom-0"
2812
+ ? "after:absolute after:-inset-x-3 after:top-0 after:-bottom-4"
2813
+ : "after:absolute after:-inset-x-3 after:-top-4 after:bottom-0"
2266
2814
  } after:content-[''] focus:outline-none focus-visible:ring-2 focus-visible:ring-blue-600 focus-visible:ring-offset-2 ${cursorClass}`}
2267
2815
  style={
2268
2816
  isVertical
@@ -2289,23 +2837,22 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
2289
2837
  data-handle-type="micro-high">
2290
2838
  <VernierKnobSvg type="micro" isTop={!isMacroFirstRail} isVertical={isVertical} isLeft={!isMacroFirstRail} />
2291
2839
  {showHairline && <div className="period-slider-hairline" />}
2292
- <div className="period-slider-tooltip absolute whitespace-nowrap rounded bg-slate-900 px-2 py-0.5 font-medium text-white text-xs shadow-md dark:bg-slate-800">{formatLabel(microUnit, safeUpperDate, formatMicroLabel)}</div>
2840
+ <div className="period-slider-tooltip absolute whitespace-nowrap rounded bg-slate-900 px-2 py-0.5 font-medium text-white text-xs shadow-md dark:bg-slate-800">{formatLabel(microUnit, vernierMicroHighDate, formatMicroLabel, locale)}</div>
2293
2841
  </div>
2294
2842
  </>
2295
2843
  ) : (
2296
2844
  <>
2297
2845
  {/* 選択範囲バー (Connect) */}
2298
- {!hideConnectBar && <div data-testid="period-slider-connect" className="period-slider-connect absolute rounded-full bg-blue-500 hover:bg-blue-600 dark:bg-blue-400" style={connectStyle} onPointerDown={handleConnectPointerDown} />}
2846
+ {!hideConnectBar && <div data-testid="period-slider-connect" className="period-slider-connect absolute rounded-full" style={connectStyle} onPointerDown={handleConnectPointerDown} />}
2299
2847
 
2300
2848
  {/* 離散モード用 Tick (目盛り点) 描画 */}
2301
2849
  {showTicks && isDiscrete && sortedAllowedDates.length > 1 && (
2302
2850
  <div className="period-slider-ticks pointer-events-none absolute inset-0">
2303
- {sortedAllowedDates.map((d) => {
2851
+ {sortedAllowedDates.map((d, idx) => {
2304
2852
  const enc = encode(unit, d)
2305
- const idx = sortedAllowedDates.findIndex((item) => encode(unit, item) === enc)
2306
2853
  const pct = valueToPct(idx)
2307
2854
  const tickStyle: CSSProperties = isVertical ? { bottom: `${pct}%`, left: "50%", transform: "translate(-50%, 50%)" } : { left: `${pct}%`, top: "50%", transform: "translate(-50%, -50%)" }
2308
- return <div key={`tick-${enc}`} className="period-slider-tick absolute h-1.5 w-1.5 rounded-full bg-slate-400/60 dark:bg-slate-500/60" style={tickStyle} />
2855
+ return <div key={`tick-${enc}`} data-testid="period-slider-tick" className="period-slider-tick absolute h-1.5 w-1.5 rounded-full bg-slate-400/60 dark:bg-slate-500/60" style={tickStyle} />
2309
2856
  })}
2310
2857
  </div>
2311
2858
  )}
@@ -2313,10 +2860,10 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
2313
2860
  {/* トラック上のマウスホバーガイド & ツールチップ */}
2314
2861
  {!disabled && hoverValue !== null && hoverPct !== null && activeHandle === null && hoverDate && (
2315
2862
  <div data-testid="period-slider-hover-guide" className="period-slider-hover-guide pointer-events-none absolute z-20 h-2 w-2" style={hoverGuideStyle}>
2316
- <div className="period-slider-hover-dot h-full w-full rounded-full border border-white/80 bg-sky-400/80 shadow-[0_0_6px_#38bdf8] dark:border-slate-800 dark:bg-sky-300/80" />
2863
+ <div data-testid="period-slider-hover-dot" className="period-slider-hover-dot h-full w-full rounded-full border border-white/80 bg-[var(--aqps-accent-light)] shadow-[0_0_6px_var(--aqps-accent-glow)] dark:border-slate-800" />
2317
2864
  <div
2318
2865
  className={`period-slider-hover-tooltip ${labelPosition === "bottom" && !isVertical ? "period-slider-hover-tooltip-bottom" : ""} rounded bg-slate-800/90 px-2 py-0.5 font-medium text-white text-xs shadow-lg backdrop-blur-xs dark:bg-slate-900/90`}>
2319
- {formatLabel(unit, hoverDate, props.formatLabel)}
2866
+ {formatLabel(unit, hoverDate, props.formatLabel, locale)}
2320
2867
  </div>
2321
2868
  </div>
2322
2869
  )}
@@ -2325,12 +2872,12 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
2325
2872
  <div
2326
2873
  tabIndex={disabled ? -1 : 0}
2327
2874
  role="slider"
2328
- aria-label={isPointMode ? (props.pointAriaLabel ?? "選択時期") : (props.lowerAriaLabel ?? "開始時期")}
2875
+ aria-label={isPointMode ? (props.pointAriaLabel ?? "Selected date") : (props.lowerAriaLabel ?? "Range start")}
2329
2876
  aria-disabled={disabled ? "true" : undefined}
2330
2877
  aria-valuemin={rangeMin}
2331
2878
  aria-valuemax={isPointMode ? rangeMax : currentHighVal}
2332
2879
  aria-valuenow={currentLowVal}
2333
- aria-valuetext={props.formatAriaValueText ? props.formatAriaValueText(lowDate, unit) : formatScreenReaderLabel(unit, lowDate, props.formatLabel)}
2880
+ aria-valuetext={props.formatAriaValueText ? props.formatAriaValueText(lowDate, unit) : formatScreenReaderLabel(unit, lowDate, props.formatLabel, locale)}
2334
2881
  aria-orientation={isVertical ? "vertical" : "horizontal"}
2335
2882
  className={`period-slider-handle group absolute h-4 w-4 touch-none after:absolute after:inset-[-14px] after:content-[''] focus:outline-none focus-visible:outline-none ${cursorClass}`}
2336
2883
  style={lowHandleStyle}
@@ -2338,7 +2885,10 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
2338
2885
  onKeyDown={handleKeyDown("low")}
2339
2886
  data-active={activeHandle === "low" ? "true" : undefined}
2340
2887
  data-front={isLowFront ? "true" : undefined}>
2341
- <div className="period-slider-knob h-full w-full rounded-full border-2 border-white bg-blue-600 shadow-md group-focus-visible:ring-2 group-focus-visible:ring-blue-600 group-focus-visible:ring-offset-2 dark:border-slate-800 dark:bg-blue-400" />
2888
+ <div
2889
+ data-testid="period-slider-knob"
2890
+ className={`period-slider-knob h-full w-full rounded-full border-2 border-white bg-[var(--aqps-accent-color)] group-focus-visible:ring-2 group-focus-visible:ring-blue-600 group-focus-visible:ring-offset-2 dark:border-slate-800 dark:bg-[var(--aqps-accent-light)] ${activeHandle === "low" ? "" : "shadow-md"}`}
2891
+ />
2342
2892
  {tooltipStyle !== "hover" && (
2343
2893
  <div
2344
2894
  className={`period-slider-tooltip absolute whitespace-nowrap rounded bg-slate-900 px-2 py-0.5 font-medium text-white text-xs shadow-md dark:bg-slate-800 ${tooltipStyle === "balloon" ? "period-slider-tooltip-balloon" : ""}`}
@@ -2346,8 +2896,9 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
2346
2896
  data-label-position={labelPosition}
2347
2897
  data-slanted={slantResult.isSlanted ? "true" : undefined}
2348
2898
  data-front={isLowFront ? "true" : undefined}
2899
+ ref={lowLabelRef}
2349
2900
  style={lowTooltipStyle}>
2350
- {formatLabel(unit, lowDate, props.formatLabel)}
2901
+ {formatLabel(unit, lowDate, props.formatLabel, locale)}
2351
2902
  </div>
2352
2903
  )}
2353
2904
  </div>
@@ -2357,12 +2908,12 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
2357
2908
  <div
2358
2909
  tabIndex={disabled ? -1 : 0}
2359
2910
  role="slider"
2360
- aria-label={props.upperAriaLabel ?? "終了時期"}
2911
+ aria-label={props.upperAriaLabel ?? "Range end"}
2361
2912
  aria-disabled={disabled ? "true" : undefined}
2362
2913
  aria-valuemin={currentLowVal}
2363
2914
  aria-valuemax={rangeMax}
2364
2915
  aria-valuenow={currentHighVal}
2365
- aria-valuetext={props.formatAriaValueText ? props.formatAriaValueText(highDate, unit) : formatScreenReaderLabel(unit, highDate, props.formatLabel)}
2916
+ aria-valuetext={props.formatAriaValueText ? props.formatAriaValueText(highDate, unit) : formatScreenReaderLabel(unit, highDate, props.formatLabel, locale)}
2366
2917
  aria-orientation={isVertical ? "vertical" : "horizontal"}
2367
2918
  className={`period-slider-handle group absolute h-4 w-4 touch-none after:absolute after:inset-[-14px] after:content-[''] focus:outline-none focus-visible:outline-none ${cursorClass}`}
2368
2919
  style={highHandleStyle}
@@ -2370,7 +2921,10 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
2370
2921
  onKeyDown={handleKeyDown("high")}
2371
2922
  data-active={activeHandle === "high" ? "true" : undefined}
2372
2923
  data-front={isHighFront ? "true" : undefined}>
2373
- <div className="period-slider-knob h-full w-full rounded-full border-2 border-white bg-blue-600 shadow-md group-focus-visible:ring-2 group-focus-visible:ring-blue-600 group-focus-visible:ring-offset-2 dark:border-slate-800 dark:bg-blue-400" />
2924
+ <div
2925
+ data-testid="period-slider-knob"
2926
+ className={`period-slider-knob h-full w-full rounded-full border-2 border-white bg-[var(--aqps-accent-color)] group-focus-visible:ring-2 group-focus-visible:ring-blue-600 group-focus-visible:ring-offset-2 dark:border-slate-800 dark:bg-[var(--aqps-accent-light)] ${activeHandle === "high" ? "" : "shadow-md"}`}
2927
+ />
2374
2928
  {tooltipStyle !== "hover" && (
2375
2929
  <div
2376
2930
  className={`period-slider-tooltip absolute whitespace-nowrap rounded bg-slate-900 px-2 py-0.5 font-medium text-white text-xs shadow-md dark:bg-slate-800 ${tooltipStyle === "balloon" ? "period-slider-tooltip-balloon" : ""}`}
@@ -2378,8 +2932,9 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
2378
2932
  data-label-position={labelPosition}
2379
2933
  data-slanted={slantResult.isSlanted ? "true" : undefined}
2380
2934
  data-front={isHighFront ? "true" : undefined}
2935
+ ref={highLabelRef}
2381
2936
  style={highTooltipStyle}>
2382
- {formatLabel(unit, highDate, props.formatLabel)}
2937
+ {formatLabel(unit, highDate, props.formatLabel, locale)}
2383
2938
  </div>
2384
2939
  )}
2385
2940
  </div>
@@ -2388,17 +2943,8 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
2388
2943
  )}
2389
2944
  </div>
2390
2945
 
2391
- {/* ▶ 1ステップ進むボタン / 垂直時は ▼ 1ステップ戻るボタン */}
2392
- {showStepper && (
2393
- <button
2394
- type="button"
2395
- className={`period-slider-stepper-btn relative after:absolute after:inset-[-10px] after:content-[''] ${isVertical ? "period-slider-stepper-prev period-slider-stepper-down" : "period-slider-stepper-next"} flex h-6 w-6 shrink-0 items-center justify-center rounded-md border border-slate-300 bg-white font-bold text-[10px] text-slate-700 leading-none shadow-2xs transition-all hover:bg-slate-100 hover:text-indigo-600 focus:outline-none focus-visible:ring-2 focus-visible:ring-blue-600 active:scale-95 disabled:cursor-not-allowed disabled:opacity-30 dark:border-slate-700 dark:bg-slate-800 dark:text-slate-200 dark:hover:bg-slate-700 ${cursorClass}`}
2396
- onClick={() => shift(isVertical ? -1 : 1)}
2397
- disabled={isVertical ? stepperPrevDisabled : stepperNextDisabled}
2398
- aria-label={isVertical ? "1つ前へ" : "1つ後へ"}>
2399
- {isVertical ? "▼" : "▶"}
2400
- </button>
2401
- )}
2946
+ {/* 末尾のステッパー: 先頭と逆向き (横向きは増加、縦向きは減少) */}
2947
+ {showStepper && renderStepperButton(isVertical ? "decrease" : "increase")}
2402
2948
  </div>
2403
2949
  )
2404
2950
  }
@@ -2454,13 +3000,12 @@ export const arePeriodSliderPropsEqual = (prev: PeriodSliderProps, next: PeriodS
2454
3000
  if (prev.mode !== next.mode) return false
2455
3001
  if (prev.unit !== next.unit) return false
2456
3002
 
2457
- if ((prev.minDate?.getTime() ?? null) !== (next.minDate?.getTime() ?? null)) return false
2458
- if ((prev.maxDate?.getTime() ?? null) !== (next.maxDate?.getTime() ?? null)) return false
3003
+ if (prev.minDate.getTime() !== next.minDate.getTime()) return false
3004
+ if (prev.maxDate.getTime() !== next.maxDate.getTime()) return false
2459
3005
 
2460
3006
  if (
2461
3007
  prev.labelPosition !== next.labelPosition ||
2462
3008
  prev.autoSlantLabels !== next.autoSlantLabels ||
2463
- prev.preventCollisionSlant !== next.preventCollisionSlant ||
2464
3009
  prev.isVertical !== next.isVertical ||
2465
3010
  prev.hideConnectBar !== next.hideConnectBar ||
2466
3011
  prev.showTicks !== next.showTicks ||
@@ -2473,11 +3018,14 @@ export const arePeriodSliderPropsEqual = (prev: PeriodSliderProps, next: PeriodS
2473
3018
  !areStylesEqual(prev.style, next.style) ||
2474
3019
  prev.snapMode !== next.snapMode ||
2475
3020
  prev.formatLabel !== next.formatLabel ||
3021
+ prev.locale !== next.locale ||
2476
3022
  prev.lowerAriaLabel !== next.lowerAriaLabel ||
2477
3023
  prev.upperAriaLabel !== next.upperAriaLabel ||
2478
3024
  prev.pointAriaLabel !== next.pointAriaLabel ||
2479
3025
  prev.macroLowerAriaLabel !== next.macroLowerAriaLabel ||
2480
3026
  prev.macroUpperAriaLabel !== next.macroUpperAriaLabel ||
3027
+ prev.decreaseAriaLabel !== next.decreaseAriaLabel ||
3028
+ prev.increaseAriaLabel !== next.increaseAriaLabel ||
2481
3029
  prev.formatAriaValueText !== next.formatAriaValueText
2482
3030
  ) {
2483
3031
  return false
@@ -2486,60 +3034,42 @@ export const arePeriodSliderPropsEqual = (prev: PeriodSliderProps, next: PeriodS
2486
3034
  if (!areDateArraysEqual(prev.allowedDates, next.allowedDates)) return false
2487
3035
 
2488
3036
  if (prev.mode === "point" && next.mode === "point") {
2489
- const prevVal = prev.value?.getTime() ?? prev.valueDate?.getTime() ?? null
2490
- const nextVal = next.value?.getTime() ?? next.valueDate?.getTime() ?? null
2491
- if (prevVal !== nextVal) return false
3037
+ if ((prev.value?.getTime() ?? null) !== (next.value?.getTime() ?? null)) return false
3038
+ if ((prev.defaultValue?.getTime() ?? null) !== (next.defaultValue?.getTime() ?? null)) return false
2492
3039
  if (prev.onChangePoint !== next.onChangePoint) return false
2493
- if (prev.onChangeValue !== next.onChangeValue) return false
2494
- if (prev.onChange !== next.onChange) return false
2495
3040
  return true
2496
3041
  }
2497
3042
 
2498
3043
  if (prev.mode === "range" && next.mode === "range") {
2499
- const prevLow = prev.range?.[0]?.getTime() ?? prev.lowerDate?.getTime() ?? null
2500
- const prevHigh = prev.range?.[1]?.getTime() ?? prev.upperDate?.getTime() ?? null
2501
- const nextLow = next.range?.[0]?.getTime() ?? next.lowerDate?.getTime() ?? null
2502
- const nextHigh = next.range?.[1]?.getTime() ?? next.upperDate?.getTime() ?? null
2503
- if (prevLow !== nextLow || prevHigh !== nextHigh) return false
3044
+ if ((prev.range?.[0]?.getTime() ?? null) !== (next.range?.[0]?.getTime() ?? null)) return false
3045
+ if ((prev.range?.[1]?.getTime() ?? null) !== (next.range?.[1]?.getTime() ?? null)) return false
3046
+ if ((prev.defaultRange?.[0]?.getTime() ?? null) !== (next.defaultRange?.[0]?.getTime() ?? null)) return false
3047
+ if ((prev.defaultRange?.[1]?.getTime() ?? null) !== (next.defaultRange?.[1]?.getTime() ?? null)) return false
2504
3048
  if (prev.onChangeRange !== next.onChangeRange) return false
2505
- if (prev.onChangeRangeTuple !== next.onChangeRangeTuple) return false
2506
- if (prev.onChange !== next.onChange) return false
2507
3049
  return true
2508
3050
  }
2509
3051
 
2510
3052
  if (prev.mode === "vernier" && next.mode === "vernier") {
2511
- const prevMicroLow = prev.microRange?.[0]?.getTime() ?? prev.lowerDate?.getTime() ?? null
2512
- const prevMicroHigh = prev.microRange?.[1]?.getTime() ?? prev.upperDate?.getTime() ?? null
2513
- const nextMicroLow = next.microRange?.[0]?.getTime() ?? next.lowerDate?.getTime() ?? null
2514
- const nextMicroHigh = next.microRange?.[1]?.getTime() ?? next.upperDate?.getTime() ?? null
2515
- if (prevMicroLow !== nextMicroLow || prevMicroHigh !== nextMicroHigh) return false
2516
-
2517
- const prevMacro0 = prev.macroRange?.[0]?.getTime() ?? null
2518
- const prevMacro1 = prev.macroRange?.[1]?.getTime() ?? null
2519
- const nextMacro0 = next.macroRange?.[0]?.getTime() ?? null
2520
- const nextMacro1 = next.macroRange?.[1]?.getTime() ?? null
2521
- if (prevMacro0 !== nextMacro0 || prevMacro1 !== nextMacro1) return false
3053
+ if ((prev.microRange?.[0]?.getTime() ?? null) !== (next.microRange?.[0]?.getTime() ?? null)) return false
3054
+ if ((prev.microRange?.[1]?.getTime() ?? null) !== (next.microRange?.[1]?.getTime() ?? null)) return false
3055
+ if ((prev.defaultMicroRange?.[0]?.getTime() ?? null) !== (next.defaultMicroRange?.[0]?.getTime() ?? null)) return false
3056
+ if ((prev.defaultMicroRange?.[1]?.getTime() ?? null) !== (next.defaultMicroRange?.[1]?.getTime() ?? null)) return false
3057
+ if (prev.macroRange[0].getTime() !== next.macroRange[0].getTime()) return false
3058
+ if (prev.macroRange[1].getTime() !== next.macroRange[1].getTime()) return false
2522
3059
 
2523
3060
  if (
2524
3061
  prev.vernierOrientation !== next.vernierOrientation ||
2525
3062
  prev.showVernierProjection !== next.showVernierProjection ||
2526
3063
  prev.showVernierTicks !== next.showVernierTicks ||
2527
3064
  prev.showHairline !== next.showHairline ||
2528
- prev.adaptiveExpand !== next.adaptiveExpand ||
2529
3065
  prev.macroUnit !== next.macroUnit ||
2530
3066
  prev.microUnit !== next.microUnit ||
2531
3067
  prev.macroIsDiscrete !== next.macroIsDiscrete ||
2532
3068
  prev.microIsDiscrete !== next.microIsDiscrete ||
2533
3069
  prev.formatMacroLabel !== next.formatMacroLabel ||
2534
3070
  prev.formatMicroLabel !== next.formatMicroLabel ||
2535
- prev.onChangeRange !== next.onChangeRange ||
2536
- prev.onChangeRangeTuple !== next.onChangeRangeTuple ||
2537
3071
  prev.onChangeMicroRange !== next.onChangeMicroRange ||
2538
- prev.onChangeMicroRangeTuple !== next.onChangeMicroRangeTuple ||
2539
- prev.onChangeMicro !== next.onChangeMicro ||
2540
- prev.onChangeMacroRange !== next.onChangeMacroRange ||
2541
- prev.onChangeMacroRangeTuple !== next.onChangeMacroRangeTuple ||
2542
- prev.onChangeMacro !== next.onChangeMacro
3072
+ prev.onChangeMacroRange !== next.onChangeMacroRange
2543
3073
  ) {
2544
3074
  return false
2545
3075
  }
@@ -2553,5 +3083,12 @@ export const arePeriodSliderPropsEqual = (prev: PeriodSliderProps, next: PeriodS
2553
3083
  return false
2554
3084
  }
2555
3085
 
3086
+ /**
3087
+ * Range, point and vernier date slider rendered on a single track.
3088
+ * 1 本のトラック上に期間・時点・ノギスの各モードを描画する日付スライダー。
3089
+ *
3090
+ * Re-renders only when arePeriodSliderPropsEqual reports a functional difference.
3091
+ * arePeriodSliderPropsEqual が機能的差分を報告した場合にのみ再描画。
3092
+ */
2556
3093
  export const PeriodSlider = memo(PeriodSliderComponent, arePeriodSliderPropsEqual)
2557
3094
  PeriodSlider.displayName = "PeriodSlider"