@aiquants/period-slider 0.8.0 → 0.9.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.
@@ -505,6 +505,33 @@ export const addUnit = (unit: PeriodSliderUnit, d: Date, amount: number): Date =
505
505
  return addDays(d, amount)
506
506
  }
507
507
 
508
+ /**
509
+ * Calculates the start boundary of a macro window in micro unit resolution.
510
+ * マクロ窓の開始境界を、ミクロ単位の解像度で算出する関数。
511
+ *
512
+ * The end boundary is expanded to the end of the terminal macro period (getMacroWindowEndDate), so the
513
+ * start must be collapsed to the head of the leading one: otherwise a window whose raw start sits mid
514
+ * period opens a rail that begins somewhere the macro handles never claim.
515
+ * 終了境界は末尾マクロ期間の末日まで広げられる (getMacroWindowEndDate) ため、開始境界も先頭マクロ期間の
516
+ * 先頭へ畳む必要がある。畳まないと、生の開始日が期間の途中にある窓で、マクロつまみが一度も名乗らない
517
+ * 位置からミクロレールが始まる。
518
+ *
519
+ * Normalising by the macro unit and then by the micro unit reproduces, for every unit pair, the mirror
520
+ * image of the end-side case table - including the pairs where the macro unit is the finer of the two.
521
+ * マクロ単位で正規化してからミクロ単位で正規化する形は、マクロ側が細かい組み合わせも含め、
522
+ * 全ての単位の組で終了側の場合分けの鏡像と一致する。
523
+ *
524
+ * @param macroUnit - Macro scale unit / マクロ側の時間解像度単位
525
+ * @param microUnit - Micro scale unit / ミクロ側の時間解像度単位
526
+ * @param d - Macro range start date / マクロ範囲の開始日付
527
+ * @returns Corrected boundary Date in micro unit resolution / 補正後のミクロ解像度開始日付
528
+ * @throws RangeError when d is absent or an Invalid Date / d が未指定または Invalid Date の場合
529
+ */
530
+ export const getMacroWindowStartDate = (macroUnit: PeriodSliderUnit, microUnit: PeriodSliderUnit, d: Date): Date => {
531
+ if (!isValidDate(d)) throw new RangeError(`getMacroWindowStartDate: d must be a valid Date (received: ${describeDateValue(d)})`)
532
+ return normalizeDateByUnit(microUnit, normalizeDateByUnit(macroUnit, d))
533
+ }
534
+
508
535
  /**
509
536
  * Calculates the end boundary of a macro window in micro unit resolution.
510
537
  * When the macro unit is coarser than the micro unit, expands the date to encompass
@@ -538,6 +565,48 @@ export const getMacroWindowEndDate = (macroUnit: PeriodSliderUnit, microUnit: Pe
538
565
  return normalizeDateByUnit(microUnit, d)
539
566
  }
540
567
 
568
+ /**
569
+ * Clamps a date into an inclusive boundary pair, returning the input itself when it already fits.
570
+ * 日付を境界の対の内側へ収める関数 (既に内側なら入力をそのまま返す)。
571
+ *
572
+ * @param date - Date to contain / 収める対象の日付
573
+ * @param min - Lower boundary / 下限
574
+ * @param max - Upper boundary / 上限
575
+ * @returns Date guaranteed to lie within [min, max] / [min, max] の内側であることが保証された日付
576
+ */
577
+ const clampDateInto = (date: Date, min: Date, max: Date): Date => (date < min ? min : date > max ? max : date)
578
+
579
+ /**
580
+ * Resolves the effective micro window: the macro window intersected with [minDate, maxDate].
581
+ * Both boundaries of a macro window are rounded outward to whole macro periods, so on its own the
582
+ * window reaches past the domain whenever minDate or maxDate falls mid period. The rails, the state
583
+ * hooks' containment and the micro selectors must all read the same intersected pair: when one of them
584
+ * uses the raw window instead, it commits a micro date that the component's own domain assertions then
585
+ * reject, and the tree throws during render.
586
+ * 実効ミクロ窓 (マクロ窓と [minDate, maxDate] の交差) を解決する関数。
587
+ * マクロ窓は両端ともマクロ期間の外側へ丸められるため、minDate / maxDate が期間の途中にあると窓単体では
588
+ * 定義域を越える。レール・ステートフックの収め込み・ミクロセレクタが同一の交差結果を共有しないと、
589
+ * 生の窓を見た側が定義域外のミクロ日付を確定させ、本体の定義域表明がそれを弾いて描画中に送出する。
590
+ *
591
+ * @param macroUnit - Macro scale unit / マクロ側の時間解像度単位
592
+ * @param microUnit - Micro scale unit / ミクロ側の時間解像度単位
593
+ * @param macroRange - Current macro window tuple / 現在のマクロ窓タプル
594
+ * @param minDate - Domain lower boundary / 定義域の下限
595
+ * @param maxDate - Domain upper boundary / 定義域の上限
596
+ * @returns Window tuple in micro unit resolution, guaranteed to lie inside [minDate, maxDate] / [minDate, maxDate] の内側であることが保証されたミクロ解像度の窓タプル
597
+ * @throws RangeError naming this function when macroRange is not a usable tuple, when a boundary is absent or an Invalid Date, or when either pair is inverted / macroRange が利用可能なタプルでない場合、境界が未指定または Invalid Date の場合、いずれかの対が逆転している場合 (メッセージは本関数を名指しする)
598
+ */
599
+ export const resolveMacroWindow = (macroUnit: PeriodSliderUnit, microUnit: PeriodSliderUnit, macroRange: [Date, Date], minDate: Date, maxDate: Date): [Date, Date] => {
600
+ // 公開関数であり、内部の呼び出し元が持つ表明の外からも呼ばれる。自分の引数は自分の名前で拒否する
601
+ assertDateRangeTuple("macroRange", macroRange, "resolveMacroWindow")
602
+ if (!isValidDate(minDate)) throw new RangeError(`resolveMacroWindow: minDate must be a valid Date (received: ${describeDateValue(minDate)})`)
603
+ if (!isValidDate(maxDate)) throw new RangeError(`resolveMacroWindow: maxDate must be a valid Date (received: ${describeDateValue(maxDate)})`)
604
+ if (maxDate.getTime() < minDate.getTime()) throw new RangeError(`resolveMacroWindow: maxDate must not precede minDate (minDate: ${describeDateValue(minDate)}, maxDate: ${describeDateValue(maxDate)})`)
605
+ // クランプの結果は生の minDate / maxDate になり得るため、ミクロ単位へ畳み直す。
606
+ // 畳まないと返り値は「ミクロ解像度」を名乗れず、日付で比較する呼び出し側が符号化で比較する側と食い違う
607
+ return [normalizeDateByUnit(microUnit, clampDateInto(getMacroWindowStartDate(macroUnit, microUnit, macroRange[0]), minDate, maxDate)), normalizeDateByUnit(microUnit, clampDateInto(getMacroWindowEndDate(macroUnit, microUnit, macroRange[1]), minDate, maxDate))]
608
+ }
609
+
541
610
  /**
542
611
  * Intl option set each unit is formatted with once a locale is supplied.
543
612
  * ロケール指定時に各単位を書式化する Intl オプション集合。
@@ -1106,6 +1175,52 @@ export type VernierHandle = "macro-low" | "macro-high" | "macro-connect" | "micr
1106
1175
  */
1107
1176
  export type VernierMicroShape = "range" | "point"
1108
1177
 
1178
+ /**
1179
+ * Tells which vernier rail a cross-axis offset falls on.
1180
+ * 直交軸オフセットがノギスのどちらのレールに属するかを判定する関数。
1181
+ *
1182
+ * The track carries two rails separated by its centre line, so the sign of the offset - together with
1183
+ * which rail the macro scale was drawn on - is the whole rule. Every gesture that has to pick a scale
1184
+ * (a press, a wheel) reads it here rather than restating it.
1185
+ * トラックは中心線で分かれた 2 本のレールを載せるため、オフセットの符号とマクロレールの側だけが判定規則の全て。
1186
+ * スケールを選ぶ必要のある操作 (押下・ホイール) は、規則を再掲せず本関数を読む。
1187
+ *
1188
+ * @param pointerCrossAxisOffset - Signed pointer offset from the track center line in pixels / トラック中心線からのポインター直交軸オフセット (ピクセル、符号付き)
1189
+ * @param orientation - Which rail the macro scale is drawn on / マクロスケールを描くレール
1190
+ * @returns Rail the offset belongs to / オフセットが属するレール
1191
+ */
1192
+ export const resolveVernierRailZone = (pointerCrossAxisOffset: number, orientation: "macro-top" | "macro-bottom" | "macro-left" | "macro-right"): "macro" | "micro" => {
1193
+ // orientation に応じて第一レール (上段または左段) がマクロかミクロかを決定
1194
+ const isFirstRailMacro = orientation === "macro-top" || orientation === "macro-left"
1195
+ const isTargetingFirstRail = pointerCrossAxisOffset <= 0
1196
+ return (isFirstRailMacro && isTargetingFirstRail) || !(isFirstRailMacro || isTargetingFirstRail) ? "macro" : "micro"
1197
+ }
1198
+
1199
+ /**
1200
+ * Resolves the signed unit step a wheel gesture asks the rail for.
1201
+ * ホイール操作がレールへ要求する符号付き 1 単位ステップを解決する関数。
1202
+ *
1203
+ * Holding Shift makes some platforms report the gesture on deltaX and others on deltaY, so the dominant
1204
+ * component is read as the primary axis instead of trusting either field.
1205
+ * Shift 押下時に deltaX で報告する環境と deltaY で報告する環境があるため、いずれかを信じず支配的な成分を主軸として読む。
1206
+ *
1207
+ * Screen coordinates grow rightwards and downwards, while the rail grows rightwards when horizontal and
1208
+ * upwards when vertical - so the sign is flipped for a vertical rail. This is the axis, not a preference.
1209
+ * 画面座標は右・下方向へ増えるのに対し、レールは横向きなら右、縦向きなら上へ伸びるため、縦向きだけ符号が反転する。
1210
+ * これは好みではなく軸そのもの。
1211
+ *
1212
+ * @param deltaX - Horizontal wheel delta / ホイールの水平デルタ
1213
+ * @param deltaY - Vertical wheel delta / ホイールの垂直デルタ
1214
+ * @param isVertical - Whether the rail runs along the vertical axis / レールが垂直方向か
1215
+ * @returns +1 toward maxDate, -1 toward minDate, or 0 when the gesture carries no usable delta / maxDate 方向なら +1、minDate 方向なら -1、使えるデルタが無ければ 0
1216
+ */
1217
+ export const resolveWheelStep = (deltaX: number, deltaY: number, isVertical: boolean): number => {
1218
+ const dominant = Math.abs(deltaX) > Math.abs(deltaY) ? deltaX : deltaY
1219
+ if (!Number.isFinite(dominant) || dominant === 0) return 0
1220
+ const isTowardMax = isVertical ? dominant < 0 : dominant > 0
1221
+ return isTowardMax ? 1 : -1
1222
+ }
1223
+
1109
1224
  /**
1110
1225
  * Resolves the target Vernier handle based on pointer primary-axis ratio and cross-axis offset relative to track center.
1111
1226
  * トラック中心線に対するポインターの直交軸オフセットと主軸比率から、操作対象となるノギスハンドル(マクロまたはミクロ)を判定します。
@@ -1135,10 +1250,7 @@ export function resolveVernierTargetHandle(
1135
1250
  microShape: VernierMicroShape = "range",
1136
1251
  ): VernierHandle {
1137
1252
  // orientation に応じて第一レール(上段または左段)がマクロかミクロかを決定
1138
- const isFirstRailMacro = orientation === "macro-top" || orientation === "macro-left"
1139
- const isTargetingFirstRail = pointerCrossAxisOffset <= 0
1140
-
1141
- if ((isFirstRailMacro && isTargetingFirstRail) || !(isFirstRailMacro || isTargetingFirstRail)) {
1253
+ if (resolveVernierRailZone(pointerCrossAxisOffset, orientation) === "macro") {
1142
1254
  // マクロ操作ゾーン
1143
1255
  const distLow = Math.abs(pointerPrimaryRatio - macroLowRatio)
1144
1256
  const distHigh = Math.abs(pointerPrimaryRatio - macroHighRatio)
@@ -1319,18 +1431,19 @@ const assertDomainBounds = (minDate: Date, maxDate: Date): void => {
1319
1431
  *
1320
1432
  * @param propName - Prop name quoted in the error message / エラーメッセージへ埋め込む Props 名
1321
1433
  * @param value - Raw prop value supplied by the consumer / 利用側が指定した生の Props 値
1434
+ * @param owner - API name the message blames (default: the component) / メッセージが名指しする API 名 (既定: コンポーネント)
1322
1435
  * @returns Nothing; the function only throws or returns normally / 戻り値なし (正常時は無返却)
1323
1436
  * @throws RangeError when the value is not a two-element tuple, holds an Invalid Date, or is inverted / 2 要素タプルでない場合、Invalid Date を含む場合、または開始と終了が逆転している場合
1324
1437
  */
1325
- const assertDateRangeTuple = (propName: string, value: unknown): void => {
1438
+ const assertDateRangeTuple = (propName: string, value: unknown, owner: string = "PeriodSlider"): void => {
1326
1439
  if (!Array.isArray(value) || value.length !== 2) {
1327
- throw new RangeError(`PeriodSlider: ${propName} is required and must be a [start, end] Date tuple (received: ${describeDateValue(value)})`)
1440
+ throw new RangeError(`${owner}: ${propName} is required and must be a [start, end] Date tuple (received: ${describeDateValue(value)})`)
1328
1441
  }
1329
1442
  const [start, end] = value
1330
- if (!isValidDate(start)) throw new RangeError(`PeriodSlider: ${propName}[0] must be a valid Date (received: ${describeDateValue(start)})`)
1331
- if (!isValidDate(end)) throw new RangeError(`PeriodSlider: ${propName}[1] must be a valid Date (received: ${describeDateValue(end)})`)
1443
+ if (!isValidDate(start)) throw new RangeError(`${owner}: ${propName}[0] must be a valid Date (received: ${describeDateValue(start)})`)
1444
+ if (!isValidDate(end)) throw new RangeError(`${owner}: ${propName}[1] must be a valid Date (received: ${describeDateValue(end)})`)
1332
1445
  if (end.getTime() < start.getTime()) {
1333
- throw new RangeError(`PeriodSlider: ${propName} must not be inverted (start: ${describeDateValue(start)}, end: ${describeDateValue(end)})`)
1446
+ throw new RangeError(`${owner}: ${propName} must not be inverted (start: ${describeDateValue(start)}, end: ${describeDateValue(end)})`)
1334
1447
  }
1335
1448
  }
1336
1449
 
@@ -1427,11 +1540,19 @@ interface VernierMicroSelection {
1427
1540
  * silently preferring one of them would leave the callback of the other silent forever.
1428
1541
  * ミクロ 2 系統は相互排他。両方指定するとつまみ数が決まらず、黙って片方を優先すれば他方のコールバックは永久に鳴らない。
1429
1542
  *
1543
+ * The micro selection is a value the user must be able to reach, so it is required to lie inside the
1544
+ * declared domain - unlike macroRange, which is deliberately allowed to overhang it (the rails intersect
1545
+ * the window with the domain, and the macro callback clamps what it emits).
1546
+ * ミクロ選択は利用者が到達できる値であるため宣言済み定義域の内側を要求する。定義域からはみ出すことを
1547
+ * 意図的に許している macroRange とは扱いが異なる (レールは窓と定義域の積を取り、マクロ通知はクランプ済みの値を配る)。
1548
+ *
1430
1549
  * @param props - Raw vernier props the component was rendered with / コンポーネントへ渡された生のノギス Props
1550
+ * @param minDate - Lower domain boundary / 定義域下限
1551
+ * @param maxDate - Upper domain boundary / 定義域上限
1431
1552
  * @returns Resolved micro shape and the selection tuple seeding the uncontrolled state / 解決済みのミクロ形態と、非制御ステートの初期値となる選択タプル
1432
- * @throws RangeError when macroRange is unusable, when both micro families are supplied, or when neither is / macroRange が利用不能な場合、ミクロ 2 系統を同時指定した場合、いずれも未指定の場合
1553
+ * @throws RangeError when macroRange is unusable, when both micro families are supplied, when neither is, or when a supplied micro selection lies outside the domain / macroRange が利用不能な場合、ミクロ 2 系統を同時指定した場合、いずれも未指定の場合、指定されたミクロ選択が定義域外の場合
1433
1554
  */
1434
- const resolveVernierMicroSelection = (props: PeriodSliderVernierProps): VernierMicroSelection => {
1555
+ const resolveVernierMicroSelection = (props: PeriodSliderVernierProps, minDate: Date, maxDate: Date): VernierMicroSelection => {
1435
1556
  assertDateRangeTuple("macroRange", props.macroRange)
1436
1557
 
1437
1558
  const hasRangeProps = props.microRange !== undefined || props.defaultMicroRange !== undefined || props.onChangeMicroRange !== undefined
@@ -1444,10 +1565,12 @@ const resolveVernierMicroSelection = (props: PeriodSliderVernierProps): VernierM
1444
1565
  if (hasPointProps) {
1445
1566
  if (props.microValue !== undefined) {
1446
1567
  assertSelectionDate("microValue", props.microValue)
1568
+ assertSelectionWithinDomain("microValue", props.microValue, minDate, maxDate)
1447
1569
  return { shape: "point", selection: [props.microValue, props.microValue] }
1448
1570
  }
1449
1571
  if (props.defaultMicroValue !== undefined) {
1450
1572
  assertSelectionDate("defaultMicroValue", props.defaultMicroValue)
1573
+ assertSelectionWithinDomain("defaultMicroValue", props.defaultMicroValue, minDate, maxDate)
1451
1574
  return { shape: "point", selection: [props.defaultMicroValue, props.defaultMicroValue] }
1452
1575
  }
1453
1576
  throw new RangeError("PeriodSlider: vernier point mode requires a micro selection; supply microValue (controlled) or defaultMicroValue (uncontrolled)")
@@ -1455,10 +1578,14 @@ const resolveVernierMicroSelection = (props: PeriodSliderVernierProps): VernierM
1455
1578
 
1456
1579
  if (props.microRange !== undefined) {
1457
1580
  assertDateRangeTuple("microRange", props.microRange)
1581
+ assertSelectionWithinDomain("microRange[0]", props.microRange[0], minDate, maxDate)
1582
+ assertSelectionWithinDomain("microRange[1]", props.microRange[1], minDate, maxDate)
1458
1583
  return { shape: "range", selection: props.microRange }
1459
1584
  }
1460
1585
  if (props.defaultMicroRange !== undefined) {
1461
1586
  assertDateRangeTuple("defaultMicroRange", props.defaultMicroRange)
1587
+ assertSelectionWithinDomain("defaultMicroRange[0]", props.defaultMicroRange[0], minDate, maxDate)
1588
+ assertSelectionWithinDomain("defaultMicroRange[1]", props.defaultMicroRange[1], minDate, maxDate)
1462
1589
  return { shape: "range", selection: props.defaultMicroRange }
1463
1590
  }
1464
1591
  // 形態を宣言済みの呼び出し側へ他方の形態の救済を示すと、それは型エラーであり、
@@ -1741,7 +1868,7 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1741
1868
  // マクロ窓とミクロ選択もノギスの位置計算の根拠そのもの。欠ければ同じくフック前に失敗させる。
1742
1869
  // 形態はステートへ写さず毎レンダー Props から解決する。写すと利用側が形態を差し替えた瞬間に、
1743
1870
  // 描かれるつまみ数と鳴るコールバックが食い違う
1744
- const vernierMicro: VernierMicroSelection | null = props.mode === "vernier" ? resolveVernierMicroSelection(props) : null
1871
+ const vernierMicro: VernierMicroSelection | null = props.mode === "vernier" ? resolveVernierMicroSelection(props, minDate, maxDate) : null
1745
1872
  const isMicroPointShape = vernierMicro !== null && vernierMicro.shape === "point"
1746
1873
 
1747
1874
  const palette = COLOR_SCHEME_PALETTES[colorScheme]
@@ -1936,59 +2063,102 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
1936
2063
  return getSortedAllowedDates(macroAllowedDates, macroUnit, minDate, maxDate)
1937
2064
  }, [isVernierMode, macroAllowedDates, macroUnit, minTime, maxTime])
1938
2065
 
2066
+ // macroRange は定義域をはみ出してよい窓なので、レールに載る対はここで一度だけ定義域へ畳む。
2067
+ // 生の値のまま使うと aria-valuenow が自分の aria-valuemin/max の外を指し、
2068
+ // 平行移動はみ出した分を戻そうとして操作と逆向きに動く
1939
2069
  const vernierMacroLowEnc = useMemo(() => {
1940
2070
  if (props.mode !== "vernier") return vernierMacroMinEnc
1941
- return encode(macroUnit, props.macroRange[0])
1942
- }, [props.mode, macroRangeStartMs, vernierMacroMinEnc, macroUnit])
2071
+ return Math.max(vernierMacroMinEnc, Math.min(vernierMacroMaxEnc, encode(macroUnit, props.macroRange[0])))
2072
+ }, [props.mode, macroRangeStartMs, vernierMacroMinEnc, vernierMacroMaxEnc, macroUnit])
1943
2073
 
1944
2074
  const vernierMacroHighEnc = useMemo(() => {
1945
2075
  if (props.mode !== "vernier") return vernierMacroMaxEnc
1946
- return encode(macroUnit, props.macroRange[1])
1947
- }, [props.mode, macroRangeEndMs, vernierMacroMaxEnc, macroUnit])
2076
+ return Math.max(vernierMacroMinEnc, Math.min(vernierMacroMaxEnc, encode(macroUnit, props.macroRange[1])))
2077
+ }, [props.mode, macroRangeEndMs, vernierMacroMinEnc, vernierMacroMaxEnc, macroUnit])
1948
2078
 
1949
2079
  // 位置と ARIA は正規化済みエンコード値、表示だけ生 prop という二重の真実を解消する。
1950
2080
  // 同じ値なら表示も一致することが構造的に保証される
1951
2081
  const vernierMacroLowDate = useMemo(() => decode(macroUnit, vernierMacroLowEnc), [macroUnit, vernierMacroLowEnc])
1952
2082
  const vernierMacroHighDate = useMemo(() => decode(macroUnit, vernierMacroHighEnc), [macroUnit, vernierMacroHighEnc])
1953
2083
 
1954
- // ミクロ境界 (マクロ窓がミクロのスケール範囲)。
1955
- // マクロ窓は macroUnit 単位へ丸められるうえ末尾期間全体まで広げられるため、そのままでは定義域の外側まで伸びる。
1956
- // レール自体を [minDate, maxDate] で切り落とさないと、aria-valuemin/max もドラッグ端も定義域外の日付を指す
1957
- const vernierMicroMinEnc = useMemo(() => {
1958
- if (props.mode !== "vernier") return encode(microUnit, minDate)
1959
- return Math.max(encode(microUnit, props.macroRange[0]), encode(microUnit, minDate))
1960
- }, [props.mode, macroRangeStartMs, microUnit, minTime])
1961
-
1962
- const vernierMicroMaxEnc = useMemo(() => {
1963
- if (props.mode !== "vernier") return encode(microUnit, maxDate)
1964
- // マクロ窓が 1 単位に収まる場合、ミクロ側の定義域も同じ 1 単位。広げるとマクロ窓外の日付を選択できてしまう
1965
- return Math.min(encode(microUnit, getMacroWindowEndDate(macroUnit, microUnit, props.macroRange[1])), encode(microUnit, maxDate))
1966
- }, [props.mode, macroRangeEndMs, macroUnit, microUnit, maxTime])
1967
-
1968
- // 候補日付はマクロ窓で切り出す。定義域全体のままではキーボードもポインターも窓の外の日付を発火する。
1969
- // 窓内に候補が 1 つも無い場合は空配列となり、各操作は離散分岐へ入らず窓内の連続値として扱われる
1970
- const sortedMicroAllowedDates = useMemo(() => {
2084
+ // ミクロレールが張る範囲。マクロ窓は macroUnit へ丸められたうえ末尾期間全体まで広げられるため、
2085
+ // 定義域と交差させないと aria-valuemin/max もドラッグ端も定義域外の日付を指す。
2086
+ // 出発点は生の macroRange ではなく、マクロつまみが実際に名乗る対 — 生の値から解決すると、
2087
+ // 窓が定義域の完全に外側にあるときレールと確定経路が別々の窓を見ることになる
2088
+ const vernierMicroWindow = useMemo<[Date, Date]>(() => {
2089
+ if (props.mode !== "vernier") return [minDate, maxDate]
2090
+ return resolveMacroWindow(macroUnit, microUnit, [vernierMacroLowDate, vernierMacroHighDate], minDate, maxDate)
2091
+ }, [props.mode, vernierMacroLowDate, vernierMacroHighDate, macroUnit, microUnit, minTime, maxTime])
2092
+
2093
+ const vernierMicroMinEnc = useMemo(() => encode(microUnit, vernierMicroWindow[0]), [microUnit, vernierMicroWindow])
2094
+
2095
+ // マクロ窓が 1 単位に収まる場合、ミクロ側の定義域も同じ 1 単位。広げるとマクロ窓外の日付を選択できてしまう
2096
+ const vernierMicroMaxEnc = useMemo(() => encode(microUnit, vernierMicroWindow[1]), [microUnit, vernierMicroWindow])
2097
+
2098
+ // 候補は定義域で解決してからマクロ窓で切り出す。窓を境界にして解決すると、候補を 1 つも含まない窓で
2099
+ // getSortedAllowedDates が送出してしまう。窓が動いた先の候補もこの一覧から絞る
2100
+ const sortedMicroDomainDates = useMemo(() => {
1971
2101
  if (!isVernierMode) return []
1972
- const domainDates = getSortedAllowedDates(microAllowedDates, microUnit, minDate, maxDate)
1973
- return domainDates.filter((d) => {
2102
+ return getSortedAllowedDates(microAllowedDates, microUnit, minDate, maxDate)
2103
+ }, [isVernierMode, microAllowedDates, microUnit, minTime, maxTime])
2104
+
2105
+ /**
2106
+ * Narrows the domain-resolved micro candidates to those a given micro window contains.
2107
+ * 定義域で解決済みのミクロ候補を、指定のミクロ窓が含むものだけへ絞り込む関数。
2108
+ *
2109
+ * @param windowMinEnc - Encoded window start / エンコード済み窓開始値
2110
+ * @param windowMaxEnc - Encoded window end / エンコード済み窓終了値
2111
+ * @returns Candidates inside the window, ascending / 窓の内側の候補 (昇順)
2112
+ */
2113
+ const narrowMicroCandidatesToWindow = (windowMinEnc: number, windowMaxEnc: number): Date[] =>
2114
+ sortedMicroDomainDates.filter((d) => {
1974
2115
  const enc = encode(microUnit, d)
1975
- return enc >= vernierMicroMinEnc && enc <= vernierMicroMaxEnc
2116
+ return enc >= windowMinEnc && enc <= windowMaxEnc
1976
2117
  })
1977
- }, [isVernierMode, microAllowedDates, microUnit, minTime, maxTime, vernierMicroMinEnc, vernierMicroMaxEnc])
2118
+
2119
+ // 窓内に候補が 1 つも無い場合は空配列となり、各操作は離散分岐へ入らず窓内の連続値として扱われる
2120
+ const sortedMicroAllowedDates = useMemo(() => narrowMicroCandidatesToWindow(vernierMicroMinEnc, vernierMicroMaxEnc), [sortedMicroDomainDates, microUnit, vernierMicroMinEnc, vernierMicroMaxEnc])
1978
2121
 
1979
2122
  // 離散指定は窓内に候補が 1 つでも残っているときだけ成立する。空配列のままでは窓内の連続値として扱う
1980
2123
  const macroIsDiscreteScale = macroIsDiscrete && sortedMacroAllowedDates.length > 0
1981
2124
  const microIsDiscreteScale = microIsDiscrete && sortedMicroAllowedDates.length > 0
1982
2125
 
2126
+ /**
2127
+ * Resolves the encoded value a micro date takes on the rail as it is currently drawn.
2128
+ * 現在描かれているレール上で、ミクロ日付が取る符号化値を解決する関数。
2129
+ *
2130
+ * A discrete rail draws nothing but its candidate set, so a date that is not a candidate has no
2131
+ * position of its own there and resolves to the nearest one; a continuous rail only clamps into the
2132
+ * window. Position, ARIA, label and every committed value read this one rule, so the rail can never
2133
+ * draw a handle somewhere the published value does not name.
2134
+ * 離散レールは候補集合しか描かないため、候補でない日付はそこに固有の位置を持たず最近傍候補へ解決される。
2135
+ * 連続レールは窓へ収めるだけ。位置・ARIA・ラベル・確定値の全てがこの 1 規則を読むため、
2136
+ * つまみを描く場所と公表する値が食い違わない。
2137
+ *
2138
+ * @param date - Micro date to place / 位置を求めるミクロ日付
2139
+ * @param candidates - Candidates the window contains, ascending (empty for a continuous rail) / 窓が含む候補 (昇順、連続レールでは空)
2140
+ * @param windowMinEnc - Encoded window start / エンコード済み窓開始値
2141
+ * @param windowMaxEnc - Encoded window end / エンコード済み窓終了値
2142
+ * @returns Encoded value on the rail / レール上の符号化値
2143
+ */
2144
+ const resolveMicroRailEnc = (date: Date, candidates: Date[], windowMinEnc: number, windowMaxEnc: number): number =>
2145
+ candidates.length > 0 ? encode(microUnit, candidates[findNearestDateIndex(candidates, date, microUnit)]) : Math.max(windowMinEnc, Math.min(windowMaxEnc, encode(microUnit, date)))
2146
+
2147
+ /** Candidates the current window contains, empty while the micro rail is continuous / 現在の窓が含む候補 (ミクロレールが連続の間は空) */
2148
+ const railMicroCandidates = microIsDiscreteScale ? sortedMicroAllowedDates : []
2149
+
2150
+ // 定義域の内側でもマクロ窓の外側であり得る (制御下の選択は窓が動いた次のレンダーまで遅れる)。
2151
+ // レールへ載せた値を配ることで、aria-valuenow が自分の aria-valuemin/max を外れる状態も、
2152
+ // 離散レールが候補でない日付を読み上げる状態も構造的に消える
1983
2153
  const vernierMicroLowEnc = useMemo(() => {
1984
2154
  if (vernierMicroSelection === null) return vernierMicroMinEnc
1985
- return encode(microUnit, vernierMicroSelection[0])
1986
- }, [microLowMs, vernierMicroMinEnc, microUnit, vernierMicroSelection])
2155
+ return resolveMicroRailEnc(vernierMicroSelection[0], railMicroCandidates, vernierMicroMinEnc, vernierMicroMaxEnc)
2156
+ }, [microLowMs, vernierMicroMinEnc, vernierMicroMaxEnc, microUnit, vernierMicroSelection, railMicroCandidates])
1987
2157
 
1988
2158
  const vernierMicroHighEnc = useMemo(() => {
1989
2159
  if (vernierMicroSelection === null) return vernierMicroMaxEnc
1990
- return encode(microUnit, vernierMicroSelection[1])
1991
- }, [microHighMs, vernierMicroMaxEnc, microUnit, vernierMicroSelection])
2160
+ return resolveMicroRailEnc(vernierMicroSelection[1], railMicroCandidates, vernierMicroMinEnc, vernierMicroMaxEnc)
2161
+ }, [microHighMs, vernierMicroMinEnc, vernierMicroMaxEnc, microUnit, vernierMicroSelection, railMicroCandidates])
1992
2162
 
1993
2163
  // つまみ位置と同じ enc から復元することで、ラベルと描画位置が食い違う余地をなくす
1994
2164
  const vernierMicroLowDate = useMemo(() => decode(microUnit, vernierMicroLowEnc), [microUnit, vernierMicroLowEnc])
@@ -2321,12 +2491,7 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
2321
2491
  startMacroHighRatio: number
2322
2492
  startMicroLowRatio: number
2323
2493
  startMicroHighRatio: number
2324
- startMacroLowEnc: number
2325
- startMacroHighEnc: number
2326
- startMicroLowEnc: number
2327
- startMicroHighEnc: number
2328
2494
  startMacroLowDate: Date
2329
- startMacroHighDate: Date
2330
2495
  initialMicroLowDate: Date
2331
2496
  initialMicroHighDate: Date
2332
2497
  } | null>(null)
@@ -2374,13 +2539,19 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
2374
2539
  notifyMacroRange(nextMacroLowDate, nextMacroHighDate)
2375
2540
  }
2376
2541
 
2542
+ // 両分岐とも同じ窓を見るため、解決は 1 度だけ
2543
+ const [nextWindowStart, nextWindowEnd] = resolveMacroWindow(macroUnit, microUnit, [nextMacroLowDate, nextMacroHighDate], minDate, maxDate)
2544
+ const nextMicroMinEnc = encode(microUnit, nextWindowStart)
2545
+ const nextMicroMaxEnc = encode(microUnit, nextWindowEnd)
2546
+ const nextMicroCandidates = microIsDiscrete ? narrowMicroCandidatesToWindow(nextMicroMinEnc, nextMicroMaxEnc) : []
2547
+
2377
2548
  // 異単位スケール間(例: 月×日)でのパン操作時の日数ズレを防ぐため、マクロ単位の暦月・暦年差分に基づいて平行移動
2378
2549
  let nextMicroLowDate: Date
2379
2550
  let nextMicroHighDate: Date
2380
2551
 
2381
2552
  if (vCtx.handle === "macro-connect") {
2382
- const curMacroLowDate = normalizeDateByUnit(microUnit, nextMacroLowDate)
2383
- const curMacroHighDate = getMacroWindowEndDate(macroUnit, microUnit, nextMacroHighDate)
2553
+ const curMacroLowDate = nextWindowStart
2554
+ const curMacroHighDate = nextWindowEnd
2384
2555
 
2385
2556
  let shiftedLowDate: Date
2386
2557
  let shiftedHighDate: Date
@@ -2418,8 +2589,8 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
2418
2589
  } else {
2419
2590
  // マクロ窓境界変更時の弾性復元 (Elastic Range Restoration & Push Clamp)
2420
2591
  // 記憶した初期境界を毎 move 生きた窓へ当て直すことで、窓を再拡張した際に選択が元位置へ戻る (クランプ後の値を確定させると戻らない)
2421
- const minMs = nextMacroLowDate.getTime()
2422
- const maxMs = getMacroWindowEndDate(macroUnit, microUnit, nextMacroHighDate).getTime()
2592
+ const minMs = nextWindowStart.getTime()
2593
+ const maxMs = nextWindowEnd.getTime()
2423
2594
  const targetLowMs = vCtx.initialMicroLowDate.getTime()
2424
2595
  const targetHighMs = vCtx.initialMicroHighDate.getTime()
2425
2596
 
@@ -2430,6 +2601,13 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
2430
2601
  nextMicroHighDate = normalizeDateByUnit(microUnit, new Date(clampedHighMs))
2431
2602
  }
2432
2603
 
2604
+ // 離散レールはつまみを最近傍候補の位置に描くため、確定値も同じ規則で解決しないと
2605
+ // 描かれている位置と利用側のステートが食い違う (ミクロつまみのドラッグは既にこの規則で動く)
2606
+ const emitLowEnc = resolveMicroRailEnc(nextMicroLowDate, nextMicroCandidates, nextMicroMinEnc, nextMicroMaxEnc)
2607
+ const emitHighEnc = Math.max(emitLowEnc, resolveMicroRailEnc(nextMicroHighDate, nextMicroCandidates, nextMicroMinEnc, nextMicroMaxEnc))
2608
+ nextMicroLowDate = decode(microUnit, emitLowEnc)
2609
+ nextMicroHighDate = decode(microUnit, emitHighEnc)
2610
+
2433
2611
  const microKey = `${nextMicroLowDate.getTime()}_${nextMicroHighDate.getTime()}`
2434
2612
  if (microKey !== lastEmittedMicroRangeRef.current) {
2435
2613
  lastEmittedMicroRangeRef.current = microKey
@@ -2451,10 +2629,12 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
2451
2629
  nextMicroLowDate = sortedMicroAllowedDates[lowIdx]
2452
2630
  nextMicroHighDate = sortedMicroAllowedDates[highIdx]
2453
2631
  } else {
2454
- const nextMicroLowEnc = Math.round(vernierMicroMinEnc + nextMicroLowRatio * microSpan)
2455
- const nextMicroHighEnc = Math.round(vernierMicroMinEnc + nextMicroHighRatio * microSpan)
2456
- nextMicroLowDate = decode(microUnit, nextMicroLowEnc)
2457
- nextMicroHighDate = decode(microUnit, nextMicroHighEnc)
2632
+ // microSpan は比率計算の 0 除算を避けるため 1 で床止めされている。乗数として使うと
2633
+ // 幅 1 単位の窓で窓端の 1 つ先を指すため、他の発火経路と同じレール規則へ通す
2634
+ const lowEnc = resolveMicroRailEnc(decode(microUnit, Math.round(vernierMicroMinEnc + nextMicroLowRatio * microSpan)), railMicroCandidates, vernierMicroMinEnc, vernierMicroMaxEnc)
2635
+ const highEnc = Math.max(lowEnc, resolveMicroRailEnc(decode(microUnit, Math.round(vernierMicroMinEnc + nextMicroHighRatio * microSpan)), railMicroCandidates, vernierMicroMinEnc, vernierMicroMaxEnc))
2636
+ nextMicroLowDate = decode(microUnit, lowEnc)
2637
+ nextMicroHighDate = decode(microUnit, highEnc)
2458
2638
  }
2459
2639
 
2460
2640
  const microKey = `${nextMicroLowDate.getTime()}_${nextMicroHighDate.getTime()}`
@@ -2527,8 +2707,12 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
2527
2707
  microUnit,
2528
2708
  macroIsDiscreteScale,
2529
2709
  microIsDiscreteScale,
2710
+ microIsDiscrete,
2711
+ minTime,
2712
+ maxTime,
2530
2713
  sortedMacroAllowedDates,
2531
2714
  sortedMicroAllowedDates,
2715
+ sortedMicroDomainDates,
2532
2716
  vernierMacroMinEnc,
2533
2717
  macroSpan,
2534
2718
  vernierMicroMinEnc,
@@ -2635,12 +2819,10 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
2635
2819
  startMacroHighRatio: macroHighRatio,
2636
2820
  startMicroLowRatio: microLowRatio,
2637
2821
  startMicroHighRatio: microHighRatio,
2638
- startMacroLowEnc: vernierMacroLowEnc,
2639
- startMacroHighEnc: vernierMacroHighEnc,
2640
- startMicroLowEnc: vernierMicroLowEnc,
2641
- startMicroHighEnc: vernierMicroHighEnc,
2642
- startMacroLowDate: p.macroRange[0],
2643
- startMacroHighDate: p.macroRange[1],
2822
+ // 平行移動量は暦差分で求めるため、基準は表示しているマクロ値 (期間先頭・定義域内) でなければならない。
2823
+ // 生の Props を基準にすると、期間の途中や定義域の外を指す開始日で日差分が半端になり、
2824
+ // 動いていない押下でも丸めで 1 単位ずれる
2825
+ startMacroLowDate: vernierMacroLowDate,
2644
2826
  initialMicroLowDate: vernierMicroLowDate,
2645
2827
  initialMicroHighDate: vernierMicroHighDate,
2646
2828
  }
@@ -2648,7 +2830,7 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
2648
2830
  setActiveVernierHandle(handle)
2649
2831
  setFrontVernierHandle(handle)
2650
2832
  },
2651
- [macroLowRatio, macroHighRatio, microLowRatio, microHighRatio, vernierMacroLowEnc, vernierMacroHighEnc, vernierMicroLowEnc, vernierMicroHighEnc, vernierMicroLowDate, vernierMicroHighDate],
2833
+ [macroLowRatio, macroHighRatio, microLowRatio, microHighRatio, vernierMacroLowDate, vernierMicroLowDate, vernierMicroHighDate],
2652
2834
  )
2653
2835
 
2654
2836
  const handleKnobPointerDown = (handle: "low" | "high") => (e: React.PointerEvent<HTMLDivElement>) => {
@@ -2785,22 +2967,35 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
2785
2967
  * Re-contains the micro selection into a newly resolved macro window and emits it only when it moved.
2786
2968
  * 新しく確定したマクロ窓へミクロ選択を収め直し、実際に動いた場合のみ発火する関数。
2787
2969
  *
2788
- * The clamp is applied to the two tuple slots with the upper one floored at the lower, so a zero-width
2970
+ * Containment is applied to the two tuple slots with the upper one floored at the lower, so a zero-width
2789
2971
  * point selection stays a point: the shape needs no branch of its own here.
2790
- * クランプは上限を下限で床止めしてタプル 2 枠へ適用するため、幅ゼロの時点選択は時点のまま保たれ、形態別の分岐を持たない。
2972
+ * 収め直しは上限を下限で床止めしてタプル 2 枠へ適用するため、幅ゼロの時点選択は時点のまま保たれ、形態別の分岐を持たない。
2973
+ *
2974
+ * A discrete micro rail only draws its candidate set, so the selection is carried to the nearest
2975
+ * candidate of the next window rather than to the window edge; a window holding no candidate at all
2976
+ * is continuous by specification and keeps the plain encoded clamp.
2977
+ * 離散ミクロレールは候補集合しか描かないため、選択は窓端ではなく次の窓の最近傍候補へ運ぶ。
2978
+ * 候補を 1 つも含まない窓は仕様上連続レールとなるため、素のエンコード値クランプのまま。
2791
2979
  *
2792
2980
  * @param nextMacroLow - Start date of the macro window just resolved / 確定直後のマクロ窓開始日付
2793
2981
  * @param nextMacroHigh - End date of the macro window just resolved / 確定直後のマクロ窓終了日付
2794
2982
  * @returns Nothing / 戻り値なし
2795
2983
  */
2796
2984
  const containMicroSelectionIntoMacroWindow = (nextMacroLow: Date, nextMacroHigh: Date): void => {
2797
- // 次のレンダーでミクロレール端はこの式へ置き換わる。同じ式で収め直さないと aria-valuenow が aria-valuemax の外を指し続ける
2798
- const nextMicroMinEnc = Math.max(encode(microUnit, nextMacroLow), encode(microUnit, minDate))
2799
- const nextMicroMaxEnc = Math.min(encode(microUnit, getMacroWindowEndDate(macroUnit, microUnit, nextMacroHigh)), encode(microUnit, maxDate))
2800
- const clampedLowEnc = Math.max(nextMicroMinEnc, Math.min(nextMicroMaxEnc, vernierMicroLowEnc))
2801
- const clampedHighEnc = Math.max(clampedLowEnc, Math.min(nextMicroMaxEnc, vernierMicroHighEnc))
2802
- if (clampedLowEnc === vernierMicroLowEnc && clampedHighEnc === vernierMicroHighEnc) return
2803
- notifyMicroSelection(decode(microUnit, clampedLowEnc), decode(microUnit, clampedHighEnc), true)
2985
+ if (vernierMicroSelection === null) return
2986
+ // 次のレンダーでミクロレール端はこの窓へ置き換わる。同じ解決器で収め直さないと aria-valuenow が aria-valuemax の外を指し続ける
2987
+ const [nextWindowStart, nextWindowEnd] = resolveMacroWindow(macroUnit, microUnit, [nextMacroLow, nextMacroHigh], minDate, maxDate)
2988
+ const nextMicroMinEnc = encode(microUnit, nextWindowStart)
2989
+ const nextMicroMaxEnc = encode(microUnit, nextWindowEnd)
2990
+ const nextCandidates = microIsDiscrete ? narrowMicroCandidatesToWindow(nextMicroMinEnc, nextMicroMaxEnc) : []
2991
+ // 出発点は利用側が保持している選択そのもの。レールへ載せた表示値から出発すると、新しい窓が選択を
2992
+ // 完全に含む場合でも古い窓の端へ引き戻し、比較の両辺が同じ端になって訂正自体が発火しなくなる
2993
+ const currentLowEnc = encode(microUnit, vernierMicroSelection[0])
2994
+ const currentHighEnc = encode(microUnit, vernierMicroSelection[1])
2995
+ const nextLowEnc = resolveMicroRailEnc(vernierMicroSelection[0], nextCandidates, nextMicroMinEnc, nextMicroMaxEnc)
2996
+ const nextHighEnc = Math.max(nextLowEnc, resolveMicroRailEnc(vernierMicroSelection[1], nextCandidates, nextMicroMinEnc, nextMicroMaxEnc))
2997
+ if (nextLowEnc === currentLowEnc && nextHighEnc === currentHighEnc) return
2998
+ notifyMicroSelection(decode(microUnit, nextLowEnc), decode(microUnit, nextHighEnc), true)
2804
2999
  }
2805
3000
 
2806
3001
  /**
@@ -2934,6 +3129,60 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
2934
3129
  }
2935
3130
  }
2936
3131
 
3132
+ /**
3133
+ * Shifts the macro window by delta macro units, preserving its width and clamping it to the domain.
3134
+ * マクロ窓を delta マクロ単位だけ幅を保ったまま平行移動し、定義域へクランプする関数。
3135
+ *
3136
+ * The rule is the one the stepper already applies to the micro selection: keep the span, re-anchor at
3137
+ * whichever end the shift would have crossed, and re-contain the micro selection into the new window.
3138
+ * 規則はステッパーがミクロ選択へ既に適用しているものと同一 (幅を保ち、越えた側の端へ寄せ直し、
3139
+ * ミクロ選択を新しい窓へ収め直す)。
3140
+ *
3141
+ * @param delta - Signed number of macro units to move by / 移動するマクロ単位数 (符号付き)
3142
+ * @returns Nothing / 戻り値なし
3143
+ */
3144
+ const shiftMacroWindow = (delta: number): void => {
3145
+ if (props.mode !== "vernier") return
3146
+
3147
+ if (macroIsDiscreteScale) {
3148
+ const maxIdx = sortedMacroAllowedDates.length - 1
3149
+ const curLowIdx = findNearestDateIndex(sortedMacroAllowedDates, vernierMacroLowDate, macroUnit)
3150
+ const curHighIdx = findNearestDateIndex(sortedMacroAllowedDates, vernierMacroHighDate, macroUnit)
3151
+ const idxSpan = curHighIdx - curLowIdx
3152
+ let nextLowIdx = curLowIdx + delta
3153
+ let nextHighIdx = curHighIdx + delta
3154
+ if (delta < 0 && nextLowIdx < 0) {
3155
+ nextLowIdx = 0
3156
+ nextHighIdx = Math.min(maxIdx, idxSpan)
3157
+ } else if (delta > 0 && nextHighIdx > maxIdx) {
3158
+ nextHighIdx = maxIdx
3159
+ nextLowIdx = Math.max(0, maxIdx - idxSpan)
3160
+ }
3161
+ if (nextLowIdx === curLowIdx && nextHighIdx === curHighIdx) return
3162
+ const nextLowDate = sortedMacroAllowedDates[nextLowIdx]
3163
+ const nextHighDate = sortedMacroAllowedDates[nextHighIdx]
3164
+ notifyMacroRange(nextLowDate, nextHighDate, true)
3165
+ containMicroSelectionIntoMacroWindow(nextLowDate, nextHighDate)
3166
+ return
3167
+ }
3168
+
3169
+ const span = vernierMacroHighEnc - vernierMacroLowEnc
3170
+ let nextLow = vernierMacroLowEnc + delta
3171
+ let nextHigh = vernierMacroHighEnc + delta
3172
+ if (delta < 0 && nextLow < vernierMacroMinEnc) {
3173
+ nextLow = vernierMacroMinEnc
3174
+ nextHigh = Math.min(vernierMacroMaxEnc, nextLow + span)
3175
+ } else if (delta > 0 && nextHigh > vernierMacroMaxEnc) {
3176
+ nextHigh = vernierMacroMaxEnc
3177
+ nextLow = Math.max(vernierMacroMinEnc, nextHigh - span)
3178
+ }
3179
+ if (nextLow === vernierMacroLowEnc && nextHigh === vernierMacroHighEnc) return
3180
+ const nextLowDate = decode(macroUnit, nextLow)
3181
+ const nextHighDate = decode(macroUnit, nextHigh)
3182
+ notifyMacroRange(nextLowDate, nextHighDate, true)
3183
+ containMicroSelectionIntoMacroWindow(nextLowDate, nextHighDate)
3184
+ }
3185
+
2937
3186
  const shift = useCallback(
2938
3187
  (delta: number) => {
2939
3188
  const p = propsRef.current
@@ -3022,6 +3271,63 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
3022
3271
  ],
3023
3272
  )
3024
3273
 
3274
+ /**
3275
+ * Shifts the scale the pointer is over by one unit when the wheel is turned with Shift held.
3276
+ * Shift 押下中のホイール操作で、ポインターが載っているスケールを 1 単位だけ平行移動するハンドラ。
3277
+ *
3278
+ * Shift is required so that an ordinary wheel over the slider keeps scrolling the page, and the page
3279
+ * scroll is only taken for a gesture that is actually aimed at the rail.
3280
+ * Shift を要求するのは、スライダー上の素のホイールがページスクロールであり続けるため。
3281
+ * ページのスクロールを奪うのはレールへ向けられた操作のときだけ。
3282
+ *
3283
+ * In vernier mode the track carries two rails, so the wheel moves the scale under the pointer: the
3284
+ * macro window on the macro rail, the micro selection on the micro rail. Moving the micro selection
3285
+ * while the pointer sits on the macro rail would misreport what the pointer is on.
3286
+ * ノギスではトラックが 2 本のレールを載せるため、ポインターの下のスケールを動かす
3287
+ * (マクロレールならマクロ窓、ミクロレールならミクロ選択)。マクロレール上でミクロ選択が動くのは、
3288
+ * ポインターが何の上に居るかについての嘘になる。
3289
+ *
3290
+ * @param event - Wheel event delivered by the non-passive track listener / 非パッシブなトラックリスナーが受け取るホイールイベント
3291
+ * @returns Nothing / 戻り値なし
3292
+ */
3293
+ const handleTrackWheel = (event: WheelEvent): void => {
3294
+ if (disabled || !event.shiftKey) return
3295
+ const step = resolveWheelStep(event.deltaX, event.deltaY, isVertical)
3296
+ if (step === 0) return
3297
+ event.preventDefault()
3298
+
3299
+ if (!isVernierMode) {
3300
+ shift(step)
3301
+ return
3302
+ }
3303
+
3304
+ const el = trackRef.current
3305
+ if (!el) return
3306
+ const rect = el.getBoundingClientRect()
3307
+ const pointerCrossAxisOffset = isVertical ? event.clientX - (rect.left + rect.width / 2) : event.clientY - (rect.top + rect.height / 2)
3308
+ if (resolveVernierRailZone(pointerCrossAxisOffset, vernierOrientation) === "macro") {
3309
+ shiftMacroWindow(step)
3310
+ return
3311
+ }
3312
+ shift(step)
3313
+ }
3314
+
3315
+ // ハンドラは毎レンダー作り直されるが、リスナーは 1 度だけ張る。ref 経由で最新を呼ぶことで、
3316
+ // 登録し直しによる取りこぼしも、閉じ込めた古い値も起こらない (ポインター移動と同じ手)
3317
+ const handleTrackWheelRef = useRef(handleTrackWheel)
3318
+ handleTrackWheelRef.current = handleTrackWheel
3319
+
3320
+ useEffect(() => {
3321
+ const el = trackRef.current
3322
+ if (!el) return
3323
+
3324
+ // React は wheel をルートへパッシブ登録するため、onWheel からは preventDefault できない。
3325
+ // ページのスクロールを止めるには、非パッシブなリスナーを自前で張るしかない
3326
+ const onWheel = (event: WheelEvent) => handleTrackWheelRef.current(event)
3327
+ el.addEventListener("wheel", onWheel, { passive: false })
3328
+ return () => el.removeEventListener("wheel", onWheel)
3329
+ }, [])
3330
+
3025
3331
  // ------------------------------------------------------------------
3026
3332
  // I. 表示位置とスタイル計算
3027
3333
  // ------------------------------------------------------------------