@aiquants/period-slider 0.5.0 → 0.7.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.
@@ -3,15 +3,18 @@
3
3
  * @package @aiquants/period-slider
4
4
  *
5
5
  * Provides a month selector rendered either as a native `input[type="month"]` or as a dropdown of
6
- * yyyy-MM options, always flanked by stepper buttons that move the selection by one month. Bounds
7
- * are the stricter of the year and date declarations; missing and invalid inputs fail fast rather
8
- * than being substituted, while an out-of-bounds month is neither clamped nor emitted. Option text
9
- * is locale-independent ISO 8601 until a `locale` tag opts into Intl formatting, while every
10
- * machine-read value stays yyyy-MM.
6
+ * yyyy-MM options, always flanked by stepper buttons that move the selection to the adjacent
7
+ * selectable month. The selectable set is either every month between the stricter of the year and
8
+ * date bounds, or the discrete `allowedMonths` intersected with those bounds; missing and invalid
9
+ * inputs fail fast rather than being substituted, while a month outside the set is neither clamped
10
+ * nor emitted. Option text is locale-independent ISO 8601 until a `locale` tag opts into Intl
11
+ * formatting, while every machine-read value stays yyyy-MM.
11
12
  *
12
- * ネイティブ `input[type="month"]` または yyyy-MM ドロップダウンと ±1 ヶ月ステッパーによる年月セレクタ。
13
- * 境界は年指定と日付指定の厳しい方を採用し、欠落値・不正値は代替せず即時エラー、境界外値はクランプも発行もせず破棄。
14
- * 選択肢テキストは既定でロケール非依存の ISO 8601 表記 (`locale` 指定時のみ Intl 書式)、機械可読値は常に yyyy-MM。
13
+ * ネイティブ `input[type="month"]` または yyyy-MM ドロップダウンと、隣接する選択可能月へ移動する
14
+ * ステッパーによる年月セレクタ。選択可能集合は年指定と日付指定の厳しい方で挟んだ全月、または
15
+ * その境界と積を取った離散集合 `allowedMonths` のいずれか。欠落値・不正値は代替せず即時エラー、
16
+ * 集合外の月はクランプも発行もせず破棄。選択肢テキストは既定でロケール非依存の ISO 8601 表記
17
+ * (`locale` 指定時のみ Intl 書式)、機械可読値は常に yyyy-MM。
15
18
  */
16
19
 
17
20
  import type React from "react"
@@ -34,7 +37,7 @@ export interface MonthSelectorProps {
34
37
  value?: Date
35
38
  /** Initial selected date; required unless `value` is supplied / 選択日付(非制御用・`value` 未指定時は必須) */
36
39
  initialDate?: Date
37
- /** Callback triggered when month changes / 月変更時コールバック */
40
+ /** Callback triggered when a selectable month is chosen / 選択可能な月が選ばれた時のコールバック */
38
41
  onChange?(date: Date, yyyymm: number): void
39
42
  /** Child elements / 子要素 */
40
43
  children?: React.ReactNode
@@ -43,14 +46,16 @@ export interface MonthSelectorProps {
43
46
  * 表示バリエーション: "date" (input[type="month"]) または "dropdown" (select[yyyy-mm])。既定値 "date"
44
47
  */
45
48
  variant?: "date" | "dropdown"
46
- /** Lower bound year (January); combined with `minDate` as the stricter of the two. Required for variant="dropdown" together with `minDate` / 可能範囲の最小年 (1 月起点)。`minDate` とは厳しい方を採用。variant="dropdown" では `minDate` との少なくとも一方が必須 */
49
+ /** Lower bound year (January); combined with `minDate` as the stricter of the two. variant="dropdown" without `allowedMonths` requires this or `minDate` / 可能範囲の最小年 (1 月起点)。`minDate` とは厳しい方を採用。`allowedMonths` 無しの variant="dropdown" では `minDate` との少なくとも一方が必須 */
47
50
  minYear?: number
48
- /** Upper bound year (December); combined with `maxDate` as the stricter of the two. Required for variant="dropdown" together with `maxDate` / 可能範囲の最大年 (12 月起点)。`maxDate` とは厳しい方を採用。variant="dropdown" では `maxDate` との少なくとも一方が必須 */
51
+ /** Upper bound year (December); combined with `maxDate` as the stricter of the two. variant="dropdown" without `allowedMonths` requires this or `maxDate` / 可能範囲の最大年 (12 月起点)。`maxDate` とは厳しい方を採用。`allowedMonths` 無しの variant="dropdown" では `maxDate` との少なくとも一方が必須 */
49
52
  maxYear?: number
50
53
  /** Lower bound date (truncated to its month); combined with `minYear` as the stricter of the two / 可能範囲の最小日付 (月単位に切り捨て)。`minYear` とは厳しい方を採用 */
51
54
  minDate?: Date
52
55
  /** Upper bound date (truncated to its month); combined with `maxYear` as the stricter of the two / 可能範囲の最大日付 (月単位に切り捨て)。`maxYear` とは厳しい方を採用 */
53
56
  maxDate?: Date
57
+ /** Discrete allowed months (day part ignored), intersected with the bounds; an empty array means nothing is selectable / 選択可能な離散月配列 (日は無視・境界と積を取る・空配列は「選択可能月なし」) */
58
+ allowedMonths?: Date[]
54
59
  /** Warning style flag / 警告枠スタイル適用フラグ */
55
60
  isWarning?: boolean
56
61
  /** Additional CSS class name / 追加の CSS クラス名 */
@@ -178,47 +183,74 @@ function resolveUpperBound(maxYear: number | undefined, maxDate: Date | undefine
178
183
  }
179
184
 
180
185
  /**
181
- * Build the option pairing a human-facing label with the yyyy-MM value the change handler parses.
182
- * 表示用ラベルと、変更ハンドラが解釈する yyyy-MM 値を対にした選択肢の生成。
186
+ * Normalize the discrete allowed months to their first day, deduplicate them, drop the ones outside
187
+ * the resolved bounds and sort the rest ascending.
188
+ * 離散月配列を月初へ正規化・重複排除し、解決済み境界の外の要素を除外して昇順に並べる関数。
183
189
  *
184
- * @param date - Month the option represents / 選択肢が表す月
185
- * @param locale - BCP 47 language tag enabling Intl label formatting / Intl ラベル書式を有効化する BCP 47 言語タグ
186
- * @returns Option whose value is always yyyy-MM / value が常に yyyy-MM である選択肢
190
+ * @param allowedMonths - Caller supplied months, already validated, whose day part is ignored / 検証済みの呼び出し側指定月 (日は無視)
191
+ * @param minBound - Resolved lower bound month, or null when unbounded / 解決済み下限月 (無制限時は null)
192
+ * @param maxBound - Resolved upper bound month, or null when unbounded / 解決済み上限月 (無制限時は null)
193
+ * @returns Ascending, deduplicated first-of-month dates inside the bounds (possibly empty) / 境界内の昇順・重複排除済み月初日付 (空の場合あり)
187
194
  */
188
- function toMonthOption(date: Date, locale: string | undefined): { label: string; value: string } {
189
- return { label: formatLabel("month", date, undefined, locale), value: formatMonth(date) }
195
+ function resolveSelectableMonths(allowedMonths: Date[], minBound: Date | null, maxBound: Date | null): Date[] {
196
+ const byTime = new Map<number, Date>()
197
+ for (const entry of allowedMonths) {
198
+ const normalized = monthStart(entry.getFullYear(), entry.getMonth())
199
+ if (minBound !== null && normalized < minBound) continue
200
+ if (maxBound !== null && normalized > maxBound) continue
201
+ if (!byTime.has(normalized.getTime())) byTime.set(normalized.getTime(), normalized)
202
+ }
203
+ return Array.from(byTime.values()).sort((a, b) => a.getTime() - b.getTime())
190
204
  }
191
205
 
192
206
  /**
193
- * Generate the complete month option list spanning the declared bounds, newest first.
194
- * 宣言された下限〜上限を過不足なく網羅する月選択肢リスト (降順) の生成。
207
+ * Expand a bounded range into every month it contains, ascending.
208
+ * 境界で挟まれた範囲を、含まれる全月 (昇順) へ展開する関数。
195
209
  *
196
210
  * @param minBound - First selectable month / 選択可能な最初の月
197
211
  * @param maxBound - Last selectable month / 選択可能な最後の月
198
- * @param locale - BCP 47 language tag enabling Intl label formatting / Intl ラベル書式を有効化する BCP 47 言語タグ
199
- * @returns Every month between the bounds in descending order / 境界間の全月 (降順)
212
+ * @returns Every month between the bounds in ascending order / 境界間の全月 (昇順)
200
213
  */
201
- function generateDropdownOptions(minBound: Date, maxBound: Date, locale: string | undefined): { label: string; value: string }[] {
214
+ function expandBoundedMonths(minBound: Date, maxBound: Date): Date[] {
202
215
  const startIndex = minBound.getFullYear() * 12 + minBound.getMonth()
203
216
  const endIndex = maxBound.getFullYear() * 12 + maxBound.getMonth()
204
-
205
- const list: { label: string; value: string }[] = []
206
- for (let i = endIndex; i >= startIndex; i--) {
207
- list.push(toMonthOption(monthStart(Math.floor(i / 12), i % 12), locale))
217
+ const list: Date[] = []
218
+ for (let i = startIndex; i <= endIndex; i++) {
219
+ list.push(monthStart(Math.floor(i / 12), i % 12))
208
220
  }
209
-
210
221
  return list
211
222
  }
212
223
 
213
224
  /**
214
- * Month selector component supporting both input[type="month"] and dropdown (yyyy-mm) modes.
215
- * A held month outside the resolved bounds is rendered as it stands instead of being clamped or
216
- * rejected, and a stepper whose target month cannot be emitted is disabled.
225
+ * Render an ascending month list as the descending option list of the dropdown, pairing a
226
+ * human-facing label with the yyyy-MM value the change handler parses.
227
+ * 昇順月配列を、表示用ラベルと変更ハンドラが解釈する yyyy-MM 値を対にした降順選択肢へ変換する関数。
228
+ *
229
+ * @param monthsAscending - Ascending selectable months / 昇順の選択可能月
230
+ * @param locale - BCP 47 language tag enabling Intl label formatting / Intl ラベル書式を有効化する BCP 47 言語タグ
231
+ * @returns Descending options whose value is always yyyy-MM / value が常に yyyy-MM である降順選択肢
232
+ */
233
+ function toDescendingOptions(monthsAscending: Date[], locale: string | undefined): { label: string; value: string }[] {
234
+ const options: { label: string; value: string }[] = []
235
+ for (let i = monthsAscending.length - 1; i >= 0; i--) {
236
+ options.push({ label: formatLabel("month", monthsAscending[i], undefined, locale), value: formatMonth(monthsAscending[i]) })
237
+ }
238
+ return options
239
+ }
240
+
241
+ /**
242
+ * Month selector component supporting both input[type="month"] and dropdown (yyyy-mm) modes, a
243
+ * bounded continuous range and a discrete allowed set. Every control presented as enabled is
244
+ * emittable: a stepper whose target month is outside the selectable set is disabled, and a held
245
+ * month outside the set is rendered as it stands instead of being clamped or rejected.
217
246
  * 月セレクタ共通コンポーネント。
218
- * `<input type="month">` または `<select>` ドロップダウンと両脇のステッパーボタン (◀▶) で ±1 ヶ月を変更可能。
247
+ * `<input type="month">` または `<select>` ドロップダウンと両脇のステッパーボタン (◀▶) で隣接する選択可能月へ移動。
248
+ * 選択可能集合は `allowedMonths` (離散・境界と積) または [minDate/minYear, maxDate/maxYear] (連続) が決定し、集合外の月は emit されない。
219
249
  * アクセシブル名の既定値は全て英語、選択肢テキストは `locale` 未指定なら ISO 8601 表記。
220
- * `value` / `initialDate` の欠落・不正値、境界の欠落・矛盾、不正な `locale` はいずれも RangeError で即時失敗。
221
- * 境界外の保持値は丸めも即時失敗もせず選択肢へ加えて表示し、発行できない月へ進むステッパーは無効化。
250
+ * `value` / `initialDate` の欠落・不正値、境界の矛盾、`allowedMonths` 無しの `variant="dropdown"` での境界欠落、
251
+ * `allowedMonths` の不正要素、不正な `locale` はいずれも RangeError で即時失敗。
252
+ * 集合外の保持値は丸めも即時失敗もせずそのまま表示し (ルートに `data-out-of-range="true"`、`<select>` には選択不可の
253
+ * プレースホルダ)、発行できない月へ進むステッパーは無効化。
222
254
  */
223
255
  const MonthSelectorComponent = (props: MonthSelectorProps): React.JSX.Element => {
224
256
  const {
@@ -231,6 +263,7 @@ const MonthSelectorComponent = (props: MonthSelectorProps): React.JSX.Element =>
231
263
  maxYear,
232
264
  minDate,
233
265
  maxDate,
266
+ allowedMonths,
234
267
  isWarning = false,
235
268
  className = "",
236
269
  style,
@@ -248,6 +281,9 @@ const MonthSelectorComponent = (props: MonthSelectorProps): React.JSX.Element =>
248
281
  assertValidDateProp(maxDate, "maxDate")
249
282
  assertValidYearProp(minYear, "minYear")
250
283
  assertValidYearProp(maxYear, "maxYear")
284
+ allowedMonths?.forEach((entry, index) => {
285
+ assertValidDateProp(entry, `allowedMonths[${index}]`)
286
+ })
251
287
 
252
288
  const effectiveDate = value ?? initialDate
253
289
  if (effectiveDate === undefined) {
@@ -264,14 +300,30 @@ const MonthSelectorComponent = (props: MonthSelectorProps): React.JSX.Element =>
264
300
 
265
301
  const minDateBound = useMemo(() => resolveLowerBound(minYear, minDate), [minYear, minTime])
266
302
  const maxDateBound = useMemo(() => resolveUpperBound(maxYear, maxDate), [maxYear, maxTime])
303
+ const minBoundTime = minDateBound?.getTime() ?? null
304
+ const maxBoundTime = maxDateBound?.getTime() ?? null
267
305
 
268
306
  if (minDateBound !== null && maxDateBound !== null && minDateBound > maxDateBound) {
269
307
  throw new RangeError(`MonthSelector: the resolved lower bound ${formatMonth(minDateBound)} is after the resolved upper bound ${formatMonth(maxDateBound)}.`)
270
308
  }
271
- if (variant === "dropdown" && (minDateBound === null || maxDateBound === null)) {
272
- throw new RangeError('MonthSelector: variant="dropdown" requires a lower bound (`minYear` or `minDate`) and an upper bound (`maxYear` or `maxDate`); the option window is never invented.')
309
+ if (variant === "dropdown" && allowedMonths === undefined && (minDateBound === null || maxDateBound === null)) {
310
+ throw new RangeError('MonthSelector: variant="dropdown" requires a lower bound (`minYear` or `minDate`) and an upper bound (`maxYear` or `maxDate`), or `allowedMonths`; the option window is never invented.')
311
+ }
312
+
313
+ const allowedKey = allowedMonths === undefined ? null : allowedMonths.map((d) => d.getTime()).join(",")
314
+
315
+ const selectableMonths = useMemo<Date[] | null>(() => {
316
+ if (allowedMonths === undefined) return null
317
+ return resolveSelectableMonths(allowedMonths, minDateBound, maxDateBound)
318
+ }, [allowedKey, minBoundTime, maxBoundTime])
319
+
320
+ const isSelectable = (candidate: Date): boolean => {
321
+ const time = candidate.getTime()
322
+ if (selectableMonths !== null) return selectableMonths.some((month) => month.getTime() === time)
323
+ if (minBoundTime !== null && time < minBoundTime) return false
324
+ if (maxBoundTime !== null && time > maxBoundTime) return false
325
+ return true
273
326
  }
274
- const isSelectionOutsideBounds = (minDateBound !== null && activeDate < minDateBound) || (maxDateBound !== null && activeDate > maxDateBound)
275
327
 
276
328
  // 外部からの initialDate 変更に追従 (制御時は value がそのまま真実の源)
277
329
  const effectiveTime = effectiveDate.getTime()
@@ -282,12 +334,10 @@ const MonthSelectorComponent = (props: MonthSelectorProps): React.JSX.Element =>
282
334
  setCurrentDate((prev) => (prev.getTime() === next.getTime() ? prev : next))
283
335
  }, [isControlled, effectiveTime])
284
336
 
285
- const isWithinBounds = (candidate: Date): boolean => (minDateBound === null || candidate >= minDateBound) && (maxDateBound === null || candidate <= maxDateBound)
286
-
287
337
  const emit = (nextDate: Date) => {
288
338
  if (disabled) return
289
- if (!isWithinBounds(nextDate)) {
290
- throw new RangeError(`MonthSelector: refusing to emit ${formatMonth(nextDate)}, which lies outside the declared bounds.`)
339
+ if (!isSelectable(nextDate)) {
340
+ throw new RangeError(`MonthSelector: refusing to emit ${formatMonth(nextDate)}, which lies outside the selectable months.`)
291
341
  }
292
342
 
293
343
  if (!isControlled) {
@@ -297,18 +347,33 @@ const MonthSelectorComponent = (props: MonthSelectorProps): React.JSX.Element =>
297
347
  onChange?.(nextDate, yyyymm)
298
348
  }
299
349
 
300
- // 保持値が窓の外にある間は、窓へ戻る向きの隣月も窓の外に出る。可否を「1 歩が手前の境界を
350
+ const activeTime = activeDate.getTime()
351
+ const isActiveSelectable = isSelectable(activeDate)
352
+
353
+ // 保持値が集合の外にある間は、集合へ戻る向きの隣月も集合の外に出うる。可否を「1 歩が手前の境界を
301
354
  // 越えないか」で決めると emit が拒否する月でボタンが有効になり、クリックが RangeError を
302
- // 利用側へ投げる。押せる月と発行できる月は常に同じ判定で決める
355
+ // 利用側へ投げる。押せる月と発行できる月は常に同じ判定で決め、離散集合では候補配列上の隣へ進む
303
356
  const prevMonthDate = useMemo<Date | null>(() => {
357
+ if (selectableMonths !== null) {
358
+ for (let i = selectableMonths.length - 1; i >= 0; i--) {
359
+ if (selectableMonths[i].getTime() < activeTime) return selectableMonths[i]
360
+ }
361
+ return null
362
+ }
304
363
  const candidate = monthStart(activeDate.getFullYear(), activeDate.getMonth() - 1)
305
- return isWithinBounds(candidate) ? candidate : null
306
- }, [activeDate, minDateBound?.getTime(), maxDateBound?.getTime()])
364
+ return isSelectable(candidate) ? candidate : null
365
+ }, [selectableMonths, activeTime, minBoundTime, maxBoundTime])
307
366
 
308
367
  const nextMonthDate = useMemo<Date | null>(() => {
368
+ if (selectableMonths !== null) {
369
+ for (const candidate of selectableMonths) {
370
+ if (candidate.getTime() > activeTime) return candidate
371
+ }
372
+ return null
373
+ }
309
374
  const candidate = monthStart(activeDate.getFullYear(), activeDate.getMonth() + 1)
310
- return isWithinBounds(candidate) ? candidate : null
311
- }, [activeDate, minDateBound?.getTime(), maxDateBound?.getTime()])
375
+ return isSelectable(candidate) ? candidate : null
376
+ }, [selectableMonths, activeTime, minBoundTime, maxBoundTime])
312
377
 
313
378
  const isPrevDisabled = disabled || prevMonthDate === null
314
379
  const isNextDisabled = disabled || nextMonthDate === null
@@ -329,8 +394,8 @@ const MonthSelectorComponent = (props: MonthSelectorProps): React.JSX.Element =>
329
394
  if (!(Number.isInteger(year) && Number.isInteger(month))) return
330
395
 
331
396
  const next = monthStart(year, month)
332
- // 境界外の直接入力は丸めずに破棄する (丸めると利用者が選んでいない月が親へ伝播するため)
333
- if (!isWithinBounds(next)) return
397
+ // 集合外の直接入力は丸めずに破棄する (丸めると利用者が選んでいない月が親へ伝播するため)
398
+ if (!isSelectable(next)) return
334
399
  emit(next)
335
400
  }
336
401
 
@@ -343,21 +408,21 @@ const MonthSelectorComponent = (props: MonthSelectorProps): React.JSX.Element =>
343
408
  }
344
409
 
345
410
  const formattedValue = formatMonth(activeDate)
411
+ const activeLabel = formatLabel("month", activeDate, undefined, locale)
346
412
 
347
413
  const minFormatted = minDateBound ? formatMonth(minDateBound) : undefined
348
414
 
349
415
  const maxFormatted = maxDateBound ? formatMonth(maxDateBound) : undefined
350
416
 
351
417
  const dropdownOptions = useMemo(() => {
352
- if (variant !== "dropdown" || minDateBound === null || maxDateBound === null) return []
353
- const options = generateDropdownOptions(minDateBound, maxDateBound, locale)
354
- if (!isSelectionOutsideBounds) return options
355
- // 境界が動的に狭まると、値が追従するまでの 1 描画だけ選択値が窓の外に出る。
356
- // その月を選択肢に加えないと select は別の月を表示し、保持値と画面が食い違う
357
- const selected = toMonthOption(activeDate, locale)
358
- // 並べ替えは表示ラベルではなく yyyy-MM 値で行う (ラベルはロケールで語順が変わり暦順にならないため)
359
- return [...options, selected].sort((a, b) => b.value.localeCompare(a.value))
360
- }, [variant, minDateBound?.getTime(), maxDateBound?.getTime(), isSelectionOutsideBounds, activeDate, locale])
418
+ if (variant !== "dropdown") return []
419
+ if (selectableMonths !== null) return toDescendingOptions(selectableMonths, locale)
420
+ if (minDateBound === null || maxDateBound === null) return []
421
+ return toDescendingOptions(expandBoundedMonths(minDateBound, maxDateBound), locale)
422
+ }, [variant, selectableMonths, minBoundTime, maxBoundTime, locale])
423
+
424
+ // <select> は一致する選択肢が無いと先頭項目を表示してしまうため、集合外の現在値は選択不可の実値プレースホルダとして明示する
425
+ const selectValue = isActiveSelectable ? formattedValue : ""
361
426
 
362
427
  const warningClassName = isWarning
363
428
  ? "border-amber-300 bg-amber-50 text-amber-900 focus:border-amber-500 focus:ring-amber-500 dark:border-amber-900/50 dark:bg-amber-950/20 dark:text-amber-200"
@@ -368,7 +433,7 @@ const MonthSelectorComponent = (props: MonthSelectorProps): React.JSX.Element =>
368
433
  const selectClassName = `mx-1 my-auto w-28 appearance-none rounded-md border px-1 py-0.5 text-center font-mono text-xs tabular-nums [text-align-last:center] [text-align:center] disabled:opacity-50 ${warningClassName}`
369
434
 
370
435
  return (
371
- <div className={`inline-flex w-38 items-center ${className}`} style={style}>
436
+ <div className={`inline-flex w-38 items-center ${className}`} style={style} data-out-of-range={isActiveSelectable ? undefined : "true"}>
372
437
  <button
373
438
  type="button"
374
439
  aria-label={prevMonthAriaLabel}
@@ -378,7 +443,12 @@ const MonthSelectorComponent = (props: MonthSelectorProps): React.JSX.Element =>
378
443
  <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" />
379
444
  </button>
380
445
  {variant === "dropdown" ? (
381
- <select aria-label={selectAriaLabel} disabled={disabled} className={selectClassName} value={formattedValue} onChange={handleSelectChange}>
446
+ <select aria-label={selectAriaLabel} disabled={disabled} className={selectClassName} value={selectValue} onChange={handleSelectChange}>
447
+ {isActiveSelectable ? null : (
448
+ <option value="" disabled className="text-center font-mono text-gray-500 tabular-nums [text-align-last:center] [text-align:center] dark:bg-slate-700 dark:text-slate-400">
449
+ {activeLabel}
450
+ </option>
451
+ )}
382
452
  {dropdownOptions.map((opt) => (
383
453
  <option key={opt.value} value={opt.value} className="text-center font-mono text-gray-900 tabular-nums [text-align-last:center] [text-align:center] dark:bg-slate-700 dark:text-slate-100">
384
454
  {opt.label}
@@ -403,7 +473,8 @@ const MonthSelectorComponent = (props: MonthSelectorProps): React.JSX.Element =>
403
473
 
404
474
  /**
405
475
  * Month-resolution selector re-rendering only when a prop its output depends on changes.
406
- * 描画結果が依存する Props の変化時のみ再描画する月単位セレクタ。
476
+ * `allowedMonths` is compared by reference, so consumers memoize the array.
477
+ * 描画結果が依存する Props の変化時のみ再描画する月単位セレクタ。`allowedMonths` は参照比較のため利用側でメモ化。
407
478
  */
408
479
  export const MonthSelector = memo(MonthSelectorComponent, (prev, next) => {
409
480
  const prevD = prev.value ?? prev.initialDate
@@ -424,6 +495,7 @@ export const MonthSelector = memo(MonthSelectorComponent, (prev, next) => {
424
495
  const prevMaxYm = prev.maxDate ? prev.maxDate.getFullYear() * 12 + prev.maxDate.getMonth() : null
425
496
  const nextMaxYm = next.maxDate ? next.maxDate.getFullYear() * 12 + next.maxDate.getMonth() : null
426
497
  if (prevMaxYm !== nextMaxYm) return false
498
+ if (prev.allowedMonths !== next.allowedMonths) return false
427
499
  if (prev.onChange !== next.onChange) return false
428
500
  if (prev.children !== next.children) return false
429
501
  if (prev.prevMonthAriaLabel !== next.prevMonthAriaLabel) return false
@@ -2951,6 +2951,12 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
2951
2951
 
2952
2952
  const hoverDate = hoverValue !== null ? valueToDate(hoverValue) : null
2953
2953
 
2954
+ // 追従ツールチップはつまみのラベルと同じ書式化関数を通るため、指している値が一致すれば文字列まで一致する。
2955
+ // 判定は畳み込みと同じく符号化値で行う (ピクセル距離では隣の値と区別できない)。
2956
+ // tooltipStyle="hover" ではつまみ側のラベルが 1 枚も描かれず、これが唯一の表示になるため重複には成り得ない。
2957
+ // point モードのつまみは 1 つで、その値は下限側が持つ (上限側のつまみは描かれない)
2958
+ const isHoverLabelDuplicate = tooltipStyle !== "hover" && hoverValue !== null && (hoverValue === currentLowVal || (!isPointMode && hoverValue === currentHighVal))
2959
+
2954
2960
  // 離散ミクロでは先頭・末尾の候補が可動端。生の窓境界で判定すると、末尾候補を越えて候補外の日付を歩き続ける
2955
2961
  const microStepFloorEnc = microIsDiscreteScale ? encode(microUnit, sortedMicroAllowedDates[0]) : vernierMicroMinEnc
2956
2962
  const microStepCeilEnc = microIsDiscreteScale ? encode(microUnit, sortedMicroAllowedDates[sortedMicroAllowedDates.length - 1]) : vernierMicroMaxEnc
@@ -3134,7 +3140,7 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
3134
3140
  {showHairline && <div className="period-slider-hairline" />}
3135
3141
  {tooltipStyle !== "hover" && (
3136
3142
  <div
3137
- 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" : ""}`}
3143
+ className={`period-slider-tooltip absolute whitespace-nowrap font-medium shadow-md ${tooltipStyle === "balloon" ? "period-slider-tooltip-balloon" : ""}`}
3138
3144
  data-tooltip-style={tooltipStyle}
3139
3145
  data-duplicate={isVernierMacroLowLabelDuplicate ? "true" : undefined}
3140
3146
  data-slanted={macroPairPlacement.slant.isSlanted ? "true" : undefined}
@@ -3193,7 +3199,7 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
3193
3199
  {showHairline && <div className="period-slider-hairline" />}
3194
3200
  {tooltipStyle !== "hover" && (
3195
3201
  <div
3196
- 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" : ""}`}
3202
+ className={`period-slider-tooltip absolute whitespace-nowrap font-medium shadow-md ${tooltipStyle === "balloon" ? "period-slider-tooltip-balloon" : ""}`}
3197
3203
  data-tooltip-style={tooltipStyle}
3198
3204
  data-duplicate={isVernierMacroHighLabelDuplicate ? "true" : undefined}
3199
3205
  data-slanted={macroPairPlacement.slant.isSlanted ? "true" : undefined}
@@ -3252,7 +3258,7 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
3252
3258
  {showHairline && <div className="period-slider-hairline" />}
3253
3259
  {tooltipStyle !== "hover" && (
3254
3260
  <div
3255
- 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" : ""}`}
3261
+ className={`period-slider-tooltip absolute whitespace-nowrap font-medium shadow-md ${tooltipStyle === "balloon" ? "period-slider-tooltip-balloon" : ""}`}
3256
3262
  data-tooltip-style={tooltipStyle}
3257
3263
  data-duplicate={isVernierMicroLowLabelDuplicate ? "true" : undefined}
3258
3264
  data-slanted={microPairPlacement.slant.isSlanted ? "true" : undefined}
@@ -3311,7 +3317,7 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
3311
3317
  {showHairline && <div className="period-slider-hairline" />}
3312
3318
  {tooltipStyle !== "hover" && (
3313
3319
  <div
3314
- 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" : ""}`}
3320
+ className={`period-slider-tooltip absolute whitespace-nowrap font-medium shadow-md ${tooltipStyle === "balloon" ? "period-slider-tooltip-balloon" : ""}`}
3315
3321
  data-tooltip-style={tooltipStyle}
3316
3322
  data-duplicate={isVernierMicroHighLabelDuplicate ? "true" : undefined}
3317
3323
  data-slanted={microPairPlacement.slant.isSlanted ? "true" : undefined}
@@ -3341,9 +3347,11 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
3341
3347
 
3342
3348
  {/* トラック上のマウスホバーガイド & ツールチップ */}
3343
3349
  {!disabled && hoverValue !== null && hoverPct !== null && activeHandle === null && hoverDate && (
3344
- <div data-testid="period-slider-hover-guide" className="period-slider-hover-guide pointer-events-none absolute z-20 h-2 w-2" style={hoverGuideStyle}>
3350
+ <div data-testid="period-slider-hover-guide" className="period-slider-hover-guide pointer-events-none absolute h-2 w-2" style={hoverGuideStyle}>
3345
3351
  <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" />
3346
3352
  <div
3353
+ data-testid="period-slider-hover-tooltip"
3354
+ data-duplicate={isHoverLabelDuplicate ? "true" : undefined}
3347
3355
  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`}>
3348
3356
  {formatLabel(unit, hoverDate, props.formatLabel, locale)}
3349
3357
  </div>
@@ -3374,7 +3382,7 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
3374
3382
  />
3375
3383
  {tooltipStyle !== "hover" && (
3376
3384
  <div
3377
- 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" : ""}`}
3385
+ className={`period-slider-tooltip absolute whitespace-nowrap font-medium shadow-md ${tooltipStyle === "balloon" ? "period-slider-tooltip-balloon" : ""}`}
3378
3386
  data-tooltip-style={tooltipStyle}
3379
3387
  data-label-position={labelPosition}
3380
3388
  data-slanted={slantResult.isSlanted ? "true" : undefined}
@@ -3412,7 +3420,7 @@ const PeriodSliderComponent: React.FC<PeriodSliderProps> = (props) => {
3412
3420
  />
3413
3421
  {tooltipStyle !== "hover" && (
3414
3422
  <div
3415
- 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" : ""}`}
3423
+ className={`period-slider-tooltip absolute whitespace-nowrap font-medium shadow-md ${tooltipStyle === "balloon" ? "period-slider-tooltip-balloon" : ""}`}
3416
3424
  data-tooltip-style={tooltipStyle}
3417
3425
  data-label-position={labelPosition}
3418
3426
  data-slanted={slantResult.isSlanted ? "true" : undefined}
@@ -175,7 +175,7 @@
175
175
  display: flex;
176
176
  flex-direction: column;
177
177
  align-items: center;
178
- z-index: 2;
178
+ z-index: var(--aqps-z-handle-wrapper, 2);
179
179
  touch-action: none;
180
180
  }
181
181
 
@@ -188,7 +188,7 @@
188
188
  }
189
189
 
190
190
  .period-slider-handle-wrapper.is-active {
191
- z-index: 10;
191
+ z-index: var(--aqps-z-handle-wrapper-active, 10);
192
192
  }
193
193
 
194
194
  /* つまみ丸グラフィック (.period-slider-knob) */
@@ -303,13 +303,18 @@
303
303
  }
304
304
 
305
305
  /* つまみハンドル (.period-slider-handle) の階層 */
306
- .period-slider-handle {
307
- z-index: 30;
306
+ /* !important が無いと変数は一切効かない。コンポーネントが同じ層をインライン style でも書いており、
307
+ 通常宣言はインラインに常に負けるため。丸つまみだけを対象にするのは、ノギスの 4 つのつまみが
308
+ マクロ 15 / ミクロ 20 と互いに別の層を持ち、その差はインライン値にしか無いからで、
309
+ ここで一律に上書きすると上下段の前後関係が潰れる。
310
+ 前面側の規則は同詳細度 (0,2,0) で後ろに置くことで勝たせている (詳細度が同点なら後勝ち) */
311
+ .period-slider-handle:not(.period-slider-handle-vernier) {
312
+ z-index: var(--aqps-z-handle, 30) !important;
308
313
  }
309
314
 
310
315
  .period-slider-handle[data-front="true"],
311
316
  .period-slider-handle[data-active="true"] {
312
- z-index: 40 !important;
317
+ z-index: var(--aqps-z-handle-front, 40) !important;
313
318
  }
314
319
 
315
320
  /* インジケーターラベル (.period-slider-tooltip): ● (つまみ) の中心点 (top:50%, left:50%) を基準に配置 */
@@ -329,7 +334,7 @@
329
334
  transform: translate(var(--ps-tooltip-tx), var(--ps-tooltip-ty)) rotate(var(--ps-tooltip-rot)) scale(var(--ps-tooltip-scale)) !important;
330
335
  white-space: nowrap !important;
331
336
  pointer-events: none !important;
332
- z-index: 31 !important;
337
+ z-index: var(--aqps-z-label, 31) !important;
333
338
  transition:
334
339
  transform 0.2s cubic-bezier(0.16, 1, 0.3, 1),
335
340
  box-shadow 0.2s ease,
@@ -339,7 +344,7 @@
339
344
  /* 前面(クリック/操作中)ハンドルのツールチップ z-index */
340
345
  .period-slider-handle[data-front="true"] .period-slider-tooltip,
341
346
  .period-slider-handle[data-active="true"] .period-slider-tooltip {
342
- z-index: 41 !important;
347
+ z-index: var(--aqps-z-label-front, 41) !important;
343
348
  box-shadow: 0 3px 10px rgba(0, 0, 0, 0.35);
344
349
  }
345
350
 
@@ -351,12 +356,16 @@
351
356
  0 0 22px rgba(56, 189, 248, 0.75);
352
357
  }
353
358
 
354
- /* 2 つのつまみが同じ値を持つとき、背面側のラベルは前面側と一字一句同じ文字列になるため隠す。
359
+ /* 同じ値が二重に描かれる 2 つの場合を 1 つの機構で隠す。
360
+ (1) 2 つのつまみが同じ値を持つとき、背面側のラベルは前面側と一字一句同じ文字列になる。
361
+ (2) ポインターがつまみと同じ値を指しているとき、追従ツールチップはそのつまみのラベルと同じ文字列になる。
355
362
  display:none やアンマウントでは ResizeObserver が実寸を報告しなくなり (0px または通知停止)、
356
- つまみが離れた瞬間に未実測の値で傾斜計算が走って配置が跳ねる。
357
- visibility:hidden ならボーダーボックスは残り実測が続く一方、描画とアクセシビリティツリーの
358
- 双方からは外れる。!important は隣接宣言と同じく Tailwind ユーティリティ層へ勝つため */
359
- .period-slider-tooltip[data-duplicate="true"] {
363
+ つまみが離れた瞬間に未実測の値で傾斜計算が走って配置が跳ねる。加えて追従ツールチップは
364
+ 出現アニメーションを持つため、値が一致するたびに消して作り直すと横切るだけで再生が繰り返される。
365
+ visibility:hidden ならボーダーボックスは残り実測も要素の同一性も続く一方、描画とアクセシビリティ
366
+ ツリーの双方からは外れる。!important は隣接宣言と同じく Tailwind ユーティリティ層へ勝つため */
367
+ .period-slider-tooltip[data-duplicate="true"],
368
+ .period-slider-hover-tooltip[data-duplicate="true"] {
360
369
  visibility: hidden !important;
361
370
  }
362
371
 
@@ -381,6 +390,13 @@
381
390
  animation: period-slider-kirat 0.3s ease-out 0s forwards;
382
391
  }
383
392
 
393
+ /* トラック(バー)上ホバーガイド: 点と追従ツールチップを束ねる器。
394
+ z-index を持つ位置指定要素なので自身が積層文脈を作り、内部の --aqps-z-hover-tooltip は
395
+ 点との前後だけを決める。つまみ (--aqps-z-handle) との前後を決めるのは常にこちら */
396
+ .period-slider-hover-guide {
397
+ z-index: var(--aqps-z-hover-guide, 20);
398
+ }
399
+
384
400
  /* トラック(バー)上ホバーツールチップ */
385
401
  .period-slider-hover-tooltip {
386
402
  position: absolute !important;
@@ -392,7 +408,7 @@
392
408
  transform-origin: 50% 100% !important;
393
409
  white-space: nowrap !important;
394
410
  pointer-events: none !important;
395
- z-index: 25 !important;
411
+ z-index: var(--aqps-z-hover-tooltip, 25) !important;
396
412
  animation: period-slider-tooltip-pop 0.12s ease-out forwards;
397
413
  }
398
414
 
@@ -452,14 +468,16 @@
452
468
  justify-content: center;
453
469
  height: 16px;
454
470
  min-width: max-content;
455
- padding: 0 5px 1.5px 5px;
471
+ padding: var(--aqps-label-padding, 0.125rem 0.5rem) !important;
456
472
  border: 1px solid rgba(255, 255, 255, 0.3);
457
- background-color: #0284c7;
458
- color: #ffffff;
459
- font-size: 10px;
473
+ background-color: var(--aqps-label-bg, oklch(0.208 0.042 265.755)) !important;
474
+ color: var(--aqps-label-fg, #ffffff) !important;
475
+ font-size: var(--aqps-label-font-size, 0.75rem) !important;
460
476
  font-weight: 600;
461
- line-height: 1;
462
- border-radius: 3px;
477
+ /* 行送りは比率のまま持つ。文字寸法を --aqps-label-font-size で変えても行箱が追従し、
478
+ 固定の 16px 相当を書いた時のような半端な中央寄せ (サブピクセル位置の食い違い) が起きない */
479
+ line-height: calc(1 / 0.75);
480
+ border-radius: var(--aqps-label-radius, 0.25rem) !important;
463
481
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.2);
464
482
  transition:
465
483
  background-color 0.15s ease,
@@ -489,8 +507,8 @@
489
507
  }
490
508
 
491
509
  .dark .period-slider-tooltip {
492
- background-color: #0284c7;
493
- color: #f8fafc;
510
+ background-color: var(--aqps-label-bg-dark, oklch(0.279 0.041 260.031)) !important;
511
+ color: var(--aqps-label-fg-dark, #ffffff) !important;
494
512
  }
495
513
 
496
514
  .dark .period-slider-tooltip.is-active {
@@ -879,10 +897,10 @@
879
897
  right: auto;
880
898
  }
881
899
 
882
- /* Vernier モードにおけるツールチップのクリアランス(上側 / 下側に 8px の数学的クリアランスを確保) */
900
+ /* Vernier モードにおけるツールチップのクリアランス(上側 / 下側に既定 8px の数学的クリアランスを確保) */
883
901
  .period-slider-handle-vernier[data-vernier-pos="top"] .period-slider-tooltip {
884
902
  top: auto !important;
885
- bottom: calc(100% + 8px) !important;
903
+ bottom: calc(100% + var(--aqps-label-rail-gap, 8px)) !important;
886
904
  left: 50% !important;
887
905
  right: auto !important;
888
906
  margin: 0 !important;
@@ -893,7 +911,7 @@
893
911
  }
894
912
 
895
913
  .period-slider-handle-vernier[data-vernier-pos="bottom"] .period-slider-tooltip {
896
- top: calc(100% + 8px) !important;
914
+ top: calc(100% + var(--aqps-label-rail-gap, 8px)) !important;
897
915
  bottom: auto !important;
898
916
  left: 50% !important;
899
917
  right: auto !important;
@@ -904,11 +922,11 @@
904
922
  transform: translate(var(--ps-tooltip-tx), var(--ps-tooltip-ty)) rotate(var(--ps-tooltip-rot)) scale(var(--ps-tooltip-scale)) !important;
905
923
  }
906
924
 
907
- /* 垂直ノギスにおけるツールチップ(左側 / 右側に 8px の数学的クリアランス、垂直中央揃えで相互衝突完全ゼロ) */
925
+ /* 垂直ノギスにおけるツールチップ(左側 / 右側に既定 8px の数学的クリアランス、垂直中央揃えで相互衝突完全ゼロ) */
908
926
  .period-slider-handle-vernier.is-vertical[data-vernier-pos="left"] .period-slider-tooltip {
909
927
  top: 50% !important;
910
928
  bottom: auto !important;
911
- right: calc(100% + 8px) !important;
929
+ right: calc(100% + var(--aqps-label-rail-gap, 8px)) !important;
912
930
  left: auto !important;
913
931
  margin: 0 !important;
914
932
  --ps-tooltip-tx: 0px;
@@ -920,7 +938,7 @@
920
938
  .period-slider-handle-vernier.is-vertical[data-vernier-pos="right"] .period-slider-tooltip {
921
939
  top: 50% !important;
922
940
  bottom: auto !important;
923
- left: calc(100% + 8px) !important;
941
+ left: calc(100% + var(--aqps-label-rail-gap, 8px)) !important;
924
942
  right: auto !important;
925
943
  margin: 0 !important;
926
944
  --ps-tooltip-tx: 0px;