@aiquants/period-slider 0.4.1 → 0.4.2

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.
@@ -12,7 +12,7 @@
12
12
 
13
13
  import type React from "react"
14
14
  import { memo, useEffect, useMemo, useState } from "react"
15
- import { formatLabel, type PeriodSliderUnit } from "./PeriodSlider"
15
+ import { formatLabel } from "./PeriodSlider"
16
16
 
17
17
  /**
18
18
  * Props of the year-resolution selector.
@@ -30,8 +30,6 @@ export interface YearSelectorProps {
30
30
  value?: Date
31
31
  /** Initial selected date; required unless `value` is supplied / 選択日付(非制御用・`value` 未指定時は必須) */
32
32
  initialDate?: Date
33
- /** Time resolution unit (ignored by selector, accepted for hook interoperability) / 時間解像度単位 (フック相互運用用) */
34
- unit?: PeriodSliderUnit
35
33
  /** Callback triggered when year changes / 年変更時コールバック */
36
34
  onChange?(date: Date, year: number): void
37
35
  /** Child elements / 子要素 */
@@ -141,10 +139,13 @@ function resolveBoundYear(boundYear: number | undefined, boundDate: Date | undef
141
139
 
142
140
  /**
143
141
  * Year selector component supporting min/max boundaries and stepper buttons (◀▶).
142
+ * A held year outside the resolved bounds is rendered as it stands instead of being clamped or
143
+ * rejected, and a stepper whose target year cannot be emitted is disabled.
144
144
  * 年セレクタ共通コンポーネント。
145
145
  * 中央のドロップダウン (`<select>`) と両脇のステッパーボタン (◀▶) で ±1 年を変更可能。
146
146
  * アクセシブル名の既定値は全て英語、選択肢テキストは `locale` 未指定なら ISO 8601 表記。
147
- * `value` / `initialDate` の欠落・不正値、境界の欠落・矛盾、境界外の選択値、不正な `locale` はいずれも RangeError で即時失敗。
147
+ * `value` / `initialDate` の欠落・不正値、境界の欠落・矛盾、不正な `locale` はいずれも RangeError で即時失敗。
148
+ * 境界外の保持値は丸めも即時失敗もせず選択肢へ加えて表示し、発行できない年へ進むステッパーは無効化。
148
149
  */
149
150
  const YearSelectorComponent = (props: YearSelectorProps): React.JSX.Element => {
150
151
  const { value, initialDate, onChange, children, minYear, maxYear, minDate, maxDate, className = "", style, disabled = false, prevYearAriaLabel = "Previous year", nextYearAriaLabel = "Next year", selectAriaLabel = "Year", locale } = props
@@ -189,20 +190,36 @@ const YearSelectorComponent = (props: YearSelectorProps): React.JSX.Element => {
189
190
  setYear(effectiveDate.getFullYear())
190
191
  }, [isControlled, effectiveTime])
191
192
 
192
- const emit = (nextYear: number) => {
193
+ const isWithinBounds = (candidateYear: number): boolean => candidateYear >= minYearBound && candidateYear <= maxYearBound
194
+
195
+ const emit = (targetYear: number) => {
193
196
  if (disabled) return
194
- if (nextYear < minYearBound || nextYear > maxYearBound) {
195
- throw new RangeError(`YearSelector: refusing to emit ${nextYear}, which lies outside the declared bounds ${minYearBound}-${maxYearBound}.`)
197
+ if (!isWithinBounds(targetYear)) {
198
+ throw new RangeError(`YearSelector: refusing to emit ${targetYear}, which lies outside the declared bounds ${minYearBound}-${maxYearBound}.`)
196
199
  }
197
200
 
198
201
  if (!isControlled) {
199
- setYear(nextYear)
202
+ setYear(targetYear)
200
203
  }
201
- onChange?.(yearStart(nextYear), nextYear)
204
+ onChange?.(yearStart(targetYear), targetYear)
205
+ }
206
+
207
+ // 保持値が窓の外にある間は、窓へ戻る向きの隣年も窓の外に出る。可否を「1 歩が手前の境界を
208
+ // 越えないか」で決めると emit が拒否する年でボタンが有効になり、クリックが RangeError を
209
+ // 利用側へ投げる。押せる年と発行できる年は常に同じ判定で決める
210
+ const prevYear = isWithinBounds(currentYear - 1) ? currentYear - 1 : null
211
+ const nextYear = isWithinBounds(currentYear + 1) ? currentYear + 1 : null
212
+
213
+ const isPrevDisabled = disabled || prevYear === null
214
+ const isNextDisabled = disabled || nextYear === null
215
+
216
+ const handlePrevious = () => {
217
+ if (prevYear !== null) emit(prevYear)
202
218
  }
203
219
 
204
- const isPrevDisabled = disabled || currentYear - 1 < minYearBound
205
- const isNextDisabled = disabled || currentYear + 1 > maxYearBound
220
+ const handleNext = () => {
221
+ if (nextYear !== null) emit(nextYear)
222
+ }
206
223
 
207
224
  const years = useMemo(() => {
208
225
  const list: number[] = []
@@ -225,7 +242,7 @@ const YearSelectorComponent = (props: YearSelectorProps): React.JSX.Element => {
225
242
  aria-label={prevYearAriaLabel}
226
243
  disabled={isPrevDisabled}
227
244
  className="relative my-auto inline-flex h-5 w-4 cursor-pointer items-center justify-center rounded p-0 after:absolute after:inset-[-14px] after:content-[''] focus:outline-none focus-visible:ring-2 focus-visible:ring-blue-600 disabled:opacity-40"
228
- onClick={() => emit(currentYear - 1)}>
245
+ onClick={handlePrevious}>
229
246
  <span className="h-0 w-0 border-y-[6px] border-y-transparent border-r-[6px] border-r-slate-500 border-solid hover:border-r-slate-700 dark:border-r-slate-400 dark:hover:border-r-slate-200" />
230
247
  </button>
231
248
  <select
@@ -251,7 +268,7 @@ const YearSelectorComponent = (props: YearSelectorProps): React.JSX.Element => {
251
268
  aria-label={nextYearAriaLabel}
252
269
  disabled={isNextDisabled}
253
270
  className="relative my-auto inline-flex h-5 w-4 cursor-pointer items-center justify-center rounded p-0 after:absolute after:inset-[-14px] after:content-[''] focus:outline-none focus-visible:ring-2 focus-visible:ring-blue-600 disabled:opacity-40"
254
- onClick={() => emit(currentYear + 1)}>
271
+ onClick={handleNext}>
255
272
  <span className="h-0 w-0 border-y-[6px] border-y-transparent border-l-[6px] border-l-slate-500 border-solid hover:border-l-slate-700 dark:border-l-slate-400 dark:hover:border-l-slate-200" />
256
273
  </button>
257
274
  {children}
@@ -207,6 +207,10 @@ export interface SelectorProps {
207
207
  // 1. Range Mode Hook (usePeriodSliderRange)
208
208
  // ======================================================================
209
209
 
210
+ /**
211
+ * Options accepted by the range hook; slider props not owned by the hook pass straight through.
212
+ * レンジフックが受け取るオプション。フックが所有しないスライダー props はそのまま素通し。
213
+ */
210
214
  export interface UsePeriodSliderRangeOptions extends Partial<Omit<PeriodSliderRangeProps, "mode" | "unit" | "minDate" | "maxDate" | "range" | "defaultRange" | "onChangeRange">> {
211
215
  /** Time resolution unit / 時間解像度単位 */
212
216
  unit: PeriodSliderUnit
@@ -220,6 +224,10 @@ export interface UsePeriodSliderRangeOptions extends Partial<Omit<PeriodSliderRa
220
224
  onChangeRange?: (lower: Date, upper: Date) => void
221
225
  }
222
226
 
227
+ /**
228
+ * State, mutators and ready-to-spread props returned by the range hook.
229
+ * レンジフックが返す状態・更新関数・スプレッド可能な props 一式。
230
+ */
223
231
  export interface UsePeriodSliderRangeReturn {
224
232
  /** Current selected range tuple / 現在の選択期間タプル */
225
233
  range: [Date, Date]
@@ -415,6 +423,10 @@ export function usePeriodSliderRange(options: UsePeriodSliderRangeOptions): UseP
415
423
  // 2. Point Mode Hook (usePeriodSliderPoint)
416
424
  // ======================================================================
417
425
 
426
+ /**
427
+ * Options accepted by the point hook; slider props not owned by the hook pass straight through.
428
+ * ポイントフックが受け取るオプション。フックが所有しないスライダー props はそのまま素通し。
429
+ */
418
430
  export interface UsePeriodSliderPointOptions extends Partial<Omit<PeriodSliderPointProps, "mode" | "unit" | "minDate" | "maxDate" | "value" | "defaultValue" | "onChangePoint">> {
419
431
  /** Time resolution unit / 時間解像度単位 */
420
432
  unit: PeriodSliderUnit
@@ -428,6 +440,10 @@ export interface UsePeriodSliderPointOptions extends Partial<Omit<PeriodSliderPo
428
440
  onChangePoint?: (value: Date) => void
429
441
  }
430
442
 
443
+ /**
444
+ * State, mutators and ready-to-spread props returned by the point hook.
445
+ * ポイントフックが返す状態・更新関数・スプレッド可能な props 一式。
446
+ */
431
447
  export interface UsePeriodSliderPointReturn {
432
448
  /** Current selected point date / 現在の選択日付 */
433
449
  value: Date
@@ -568,6 +584,10 @@ export function usePeriodSliderPoint(options: UsePeriodSliderPointOptions): UseP
568
584
  // 3. Vernier Dual-Scale Hook (useVernierSlider)
569
585
  // ======================================================================
570
586
 
587
+ /**
588
+ * Options accepted by the vernier hook; slider props not owned by the hook pass straight through.
589
+ * ノギスフックが受け取るオプション。フックが所有しないスライダー props はそのまま素通し。
590
+ */
571
591
  export interface UseVernierSliderOptions extends Partial<Omit<PeriodSliderVernierProps, "mode" | "unit" | "minDate" | "maxDate" | "macroUnit" | "microUnit" | "macroRange" | "microRange" | "defaultMicroRange" | "onChangeMacroRange" | "onChangeMicroRange">> {
572
592
  /** Base time resolution unit / 基本時間解像度単位 */
573
593
  unit: PeriodSliderUnit
@@ -589,6 +609,10 @@ export interface UseVernierSliderOptions extends Partial<Omit<PeriodSliderVernie
589
609
  onChangeMicroRange?: (lower: Date, upper: Date) => void
590
610
  }
591
611
 
612
+ /**
613
+ * Macro/micro state, mutators and ready-to-spread props returned by the vernier hook.
614
+ * ノギスフックが返すマクロ・ミクロの状態・更新関数・スプレッド可能な props 一式。
615
+ */
592
616
  export interface UseVernierSliderReturn {
593
617
  /** Macro window range tuple / マクロ窓期間タプル */
594
618
  macroRange: [Date, Date]