@aiquants/period-slider 0.11.0 → 0.12.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.
- package/CHANGELOG.md +56 -0
- package/README.md +225 -20
- package/dist/PeriodSlider.d.ts +144 -19
- package/dist/PeriodSlider.d.ts.map +1 -1
- package/dist/VirtualDateDropdown.d.ts.map +1 -1
- package/dist/YearSelector.d.ts +2 -0
- package/dist/YearSelector.d.ts.map +1 -1
- package/dist/index.cjs +1 -1
- package/dist/index.d.cts +13 -2
- package/dist/index.d.ts +13 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2081 -2022
- package/dist/styles/period-slider.standalone.css +1 -1
- package/dist/usePeriodSlider.d.ts +2 -0
- package/dist/usePeriodSlider.d.ts.map +1 -1
- package/package.json +5 -5
- package/src/PeriodSlider.tsx +363 -156
- package/src/VirtualDateDropdown.tsx +4 -0
- package/src/YearSelector.tsx +62 -22
- package/src/index.ts +14 -0
- package/src/usePeriodSlider.ts +125 -90
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,62 @@ All notable changes to `@aiquants/period-slider` are documented here.
|
|
|
7
7
|
|
|
8
8
|
## Unreleased
|
|
9
9
|
|
|
10
|
+
1 月以外の月から始まる年 (年度) と、その上の四半期。
|
|
11
|
+
|
|
12
|
+
### 追加
|
|
13
|
+
|
|
14
|
+
- **`yearStartMonth` (0 始まりの暦月、既定 `0`) で、`unit: "year"` の 1 年が始まる月を選べます**。`PeriodSlider`
|
|
15
|
+
(`BasePeriodSliderProps`)、`YearSelector`、フックが返す `SelectorProps`、4 つのフックのオプション、
|
|
16
|
+
`ConnectDragValueOptions` が受け取ります。4 月開始を指定すると、年つまみが名乗る位置・離散候補の正規化・
|
|
17
|
+
`YearSelector` の選択肢・ステッパーの 1 歩が、すべて 4 月から翌年 3 月までの周期の上に乗ります。年軸を持つのは
|
|
18
|
+
`YearSelector` だけで、`MonthSelector` / `DateSelector` は年の開始月を読みません。
|
|
19
|
+
- **年はその先頭月が属する暦年で名付けます** (4 月開始では 2025-04-01 〜 2026-03-31 が 2025 年)。これがパッケージ内で
|
|
20
|
+
唯一の年の定義であり、`normalizeDateByUnit` / `encode` / `decode` / `resolveQuarter` / `YearSelector` が同じ採番を使います。
|
|
21
|
+
米国式に終了年で呼ぶ慣行 (10 月開始の 2025-10 〜 2026-09 を FY2026 と呼ぶ形) は、利用側で 1 を足してください。
|
|
22
|
+
- **公開純関数 8 つが末尾の引数に `yearStartMonth = 0` を受けます**: `normalizeDateByUnit`・`encode`・`decode`・
|
|
23
|
+
`getMacroWindowStartDate`・`getMacroWindowEndDate`・`resolveMacroWindow`・`findNearestDateIndex`・`getSortedAllowedDates`。
|
|
24
|
+
既定値があるため、既存の呼び出しは 1 つも変わりません。`addUnit` は**受け取りません** (ずらした年も厳密に 12 か月であり、
|
|
25
|
+
読まない引数を足せばシグネチャが嘘になるため)。
|
|
26
|
+
- **未指定は仕様上の既定 (暦年) であり、指定された値だけを検証します**。`12`・`-1`・`1.5`・`NaN`・`Infinity`・`"3"`・
|
|
27
|
+
`null` は `RangeError` です (`null` は既定へ落ちません)。検証は各公開 API が**自分の名前で**、早期 return より前に行います。
|
|
28
|
+
- **移行の注意 — `allowedDates` / `macroAllowedDates` / `microAllowedDates` の各要素は「その日を含む年」として読まれます**。
|
|
29
|
+
年レールで暦年の 1 月 1 日を並べた候補集合 (`[2016-01-01, 2018-01-01, …]`) を 4 月開始のレールへそのまま渡すと、
|
|
30
|
+
各要素は 1 つ手前の年 (2015 年・2017 年) の先頭へ正規化され、候補が黙って 1 年ずれます。非暦年を指定するときは、
|
|
31
|
+
候補もその年の先頭日 (`2016-04-01` など) で書いてください。
|
|
32
|
+
- **四半期の座標と表記を公開します**: `resolveQuarter(d, yearStartMonth): PeriodQuarter`、
|
|
33
|
+
`formatQuarterLabel(d, yearStartMonth): string` (`"2025-Q1"` 形式)、型 `PeriodQuarter`
|
|
34
|
+
(`{ year: number; quarter: 1 | 2 | 3 | 4; startDate: Date }`)。**新しい Props はありません**。四半期はフォーマッタ Props
|
|
35
|
+
(`formatLabel` / `formatMacroLabel` / `formatMicroLabel`) を通してラベルに現れます。
|
|
36
|
+
- **`yearStartMonth` は両関数で必須です** (既定値を持ちません)。既存の公開純関数 8 つが `= 0` を持つのは、以前からある
|
|
37
|
+
呼び出し側の挙動を変えられないためです。新設の記号にその義務は無く、非暦年を扱うためのリリースで省略を許せば、
|
|
38
|
+
最も起こりやすい誤り (暦四半期) が既定になります。**周辺の面に対する意図的な逸脱であり、そう明記します。**
|
|
39
|
+
- **関数自身の引数であり、スライダーの同名 Props を読みません**。年度レール上の暦四半期も、暦年レール上の年度四半期も
|
|
40
|
+
表現できます。序数と年番号は必ず同一の引数から導かれるため、年と四半期が食い違うラベルは構成できません。
|
|
41
|
+
- **四半期の境界は `yearStartMonth` を 3 で割った剰余で決まり、番号は `yearStartMonth` そのもので決まります**。
|
|
42
|
+
0・3・6・9 では境界が暦四半期と一致して番号だけがずれ、他の 8 通りでは境界自体が動きます (1 なら 2 月〜4 月が Q1)。
|
|
43
|
+
- **`year` は `startDate.getFullYear()` と一致するとは限りません**。1 月を跨ぐ四半期 (4 月開始の 2026-01-15 は
|
|
44
|
+
`year` が 2025、`startDate` が 2026-01-01) で両者は異なるため、ラベルの年は必ず `year` から組み立ててください。
|
|
45
|
+
- **`formatQuarterLabel` が返す文字列はロケール非依存ですが、ISO 8601 ではありません** (ISO 8601 は暦日・年間通日・
|
|
46
|
+
週日付のみを定め、四半期表記を定めません)。ECMA-402 に四半期のフィールドが無く、`Intl.DateTimeFormat` は `quarter`
|
|
47
|
+
オプションを送出せずに黙って捨てます (実測: `{ quarter: "long", year: "numeric" }` の `resolvedOptions()` は
|
|
48
|
+
`year` だけを返し、`ja-JP` では 2025-04-01 が `2025年` になります。`formatToParts` に四半期の断片は現れません)。履行できない `locale` 引数は置かないため、本パッケージの 3 段の優先順位
|
|
49
|
+
(フォーマッタ Props > `locale` > ISO 8601 既定) に四半期の段はありません。地域化した表記 (`2025年度 第2四半期`) は
|
|
50
|
+
`resolveQuarter` から利用側が組み立てます (年の部分だけは `formatLabel("year", …, undefined, locale)` で `locale` に従います)。
|
|
51
|
+
- **エラー契約は既存の 2 つの族をそのまま踏襲します**。`resolveQuarter` は未指定・Invalid Date で `RangeError` を
|
|
52
|
+
送出し (計算族: `normalizeDateByUnit` と同じ)、`formatQuarterLabel` は空文字列を返します (ラベル族: `formatLabel` と
|
|
53
|
+
同じ)。`formatQuarterLabel` の無効日付の短絡は `yearStartMonth` の検証より前に置きます。不正な `yearStartMonth` は
|
|
54
|
+
どちらも `RangeError` です。
|
|
55
|
+
- **既知の制約**: `MonthSelector` / `YearSelector` は選択肢のフォーマッタ Props を持たないため、四半期の粒度で
|
|
56
|
+
ラベル付けした月ドロップダウンは依然として作れません (フォーマッタ Props の新設は本リリースの範囲外)。
|
|
57
|
+
|
|
58
|
+
## 0.11.1
|
|
59
|
+
|
|
60
|
+
### 修正
|
|
61
|
+
|
|
62
|
+
- **日付ドロップダウンに親指送りのタップサークルを描きません**。仮想スクロールの既定は有効で、直径 40px の円が
|
|
63
|
+
操作要素の幅に合わせた 1 列のリストの上へ重なっていました (行を覆うだけで、ネイティブのポップアップにも
|
|
64
|
+
無い部品です)。
|
|
65
|
+
|
|
10
66
|
## 0.11.0
|
|
11
67
|
|
|
12
68
|
### 利用側の契約が変わる点
|
package/README.md
CHANGED
|
@@ -16,6 +16,7 @@
|
|
|
16
16
|
## 特徴
|
|
17
17
|
|
|
18
18
|
- **柔軟な時間単位**: `year`, `month`, `day` の 3 つの単位をサポート。
|
|
19
|
+
- **暦年以外の年 (`yearStartMonth`)**: 1 年の始まりを任意の暦月へ置けます (`3` なら 4 月〜翌 3 月の会計年度、`9` なら 10 月〜翌 9 月のでん粉年度)。年はその年の先頭月が属する暦年で名乗り、レールの目盛・ノギスのマクロ窓・年解像度の離散候補がまとめて同じ境界に従います。四半期は `resolveQuarter` / `formatQuarterLabel` が暦四半期・年度四半期の双方を返します (スライダーの Props とは独立した引数で選びます)。
|
|
19
20
|
- **3 つの操作モード**:
|
|
20
21
|
- `range`: 開始時期と終了時期の 2 つのつまみと連結バーで範囲を選択。
|
|
21
22
|
- `point`: 単一のつまみで時点を選択。
|
|
@@ -127,7 +128,7 @@ peer dependency の `@aiquants/virtualscroll` のスタイルシートは、本
|
|
|
127
128
|
|
|
128
129
|
ISO 8601 はフォールバックではなく、本パッケージの仕様上の既定値です。英語などの自然言語表記を既定にすると汎用パッケージへ 1 つの言語を焼き付けることになり、`Intl` の出力は ICU / Node のバージョン間で変化するためです。
|
|
129
130
|
|
|
130
|
-
- **優先順位**: フォーマッタ Props (`formatLabel` / `formatMacroLabel` / `formatMicroLabel` / `formatAriaValueText`、`DateSelector` の `formatYearOption` / `formatMonthOption` / `formatDayOption`) が最優先、次に `locale`、最後に ISO 8601
|
|
131
|
+
- **優先順位**: フォーマッタ Props (`formatLabel` / `formatMacroLabel` / `formatMicroLabel` / `formatAriaValueText`、`DateSelector` の `formatYearOption` / `formatMonthOption` / `formatDayOption`) が最優先、次に `locale`、最後に ISO 8601 既定です。四半期表記だけはこの 3 段に乗りません (`locale` の段を持ちません)。理由と書き方は [四半期表示](#四半期表示-暦四半期と年度四半期) を参照してください。
|
|
131
132
|
- **地域化されるのは人間が読むテキストのみ**: `<input type="date">` の `value` / `min` / `max` は常に `yyyy-MM-dd`、`<input type="month">` は常に `yyyy-MM`、`DateSelector` の `variant="dropdown"` が操作要素に持つ `data-value` は常に `yyyy-MM-dd`、`<option value>` は常に ISO 文字列 (`yyyy-MM`) または生の数値 (年セレクト、`variant="split-dropdown"` の 3 セレクト) です。
|
|
132
133
|
- **アクセシブル名は `locale` では変わりません**: ボタン・セレクト・つまみの名称は英語既定のままです。翻訳するには `lowerAriaLabel` / `decreaseAriaLabel` / `selectAriaLabel` などのアクセシブル名 Props を渡してください。
|
|
133
134
|
- **Fail Fast**: 空文字列や `Intl.DateTimeFormat` が受理しない値 (`"en_US"`、非文字列等) を渡した場合、既定の ISO へ黙って戻さず `RangeError` を送出します (メッセージは [実行時バリデーション](#実行時バリデーション-fail-fast) 参照)。`"xx-YY"` のように構造として妥当なタグは、対応する翻訳データが無くても受理されます。
|
|
@@ -160,6 +161,64 @@ const formatJapaneseDay = (date: Date): string => `${date.getFullYear()}年${Str
|
|
|
160
161
|
<MonthSelector {...startSelectorProps} locale="ja-JP" />
|
|
161
162
|
```
|
|
162
163
|
|
|
164
|
+
#### 四半期表示 (暦四半期と年度四半期)
|
|
165
|
+
|
|
166
|
+
四半期だけは上の 3 段の優先順位に乗りません。**`locale` の段が存在しない**ためです。ECMA-402 に四半期のフィールドが無く、`Intl.DateTimeFormat` は `quarter` オプションを受け取っても送出せず黙って捨てます (Node v24.16.0 / ICU 78.3 で実測)。
|
|
167
|
+
|
|
168
|
+
```ts
|
|
169
|
+
const formatter = new Intl.DateTimeFormat("ja-JP", { quarter: "long", year: "numeric" })
|
|
170
|
+
|
|
171
|
+
formatter.resolvedOptions()
|
|
172
|
+
// { locale: "ja-JP", calendar: "gregory", numberingSystem: "latn", timeZone: "Asia/Tokyo", year: "numeric" }
|
|
173
|
+
// -> quarter は解決結果に残らない
|
|
174
|
+
formatter.format(new Date(2025, 3, 1)) // "2025年" (四半期はどこにも現れない)
|
|
175
|
+
Intl.supportedValuesOf("unit").includes("quarter") // false
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
履行できない引数は置かない方針のため、四半期の 2 関数は `locale` を受け取りません。
|
|
179
|
+
|
|
180
|
+
| 関数 | シグネチャ | 返り値 |
|
|
181
|
+
| :--- | :--- | :--- |
|
|
182
|
+
| `resolveQuarter` | `(d: Date, yearStartMonth: number) => PeriodQuarter` | `{ year, quarter, startDate }` の四半期座標 |
|
|
183
|
+
| `formatQuarterLabel` | `(d: Date, yearStartMonth: number) => string` | `"2025-Q1"` 形式のロケール非依存文字列 |
|
|
184
|
+
|
|
185
|
+
- **`yearStartMonth` は 2 関数とも必須です**。年を扱う 8 つのヘルパー (`normalizeDateByUnit` 等) が `= 0` を持つのとは意図的に違えています。非暦年の四半期を扱えることがこの API の目的であり、省略を暦四半期として黙って解釈すると、年度四半期のつもりの呼び出しが 1 四半期ずれたまま通ってしまうためです。
|
|
186
|
+
- **この `yearStartMonth` は関数自身の引数であり、スライダーの同名 Props を読むものではありません**。年度レール (`yearStartMonth={3}`) 上の暦四半期も、暦年レール上の年度四半期も、どちらも表現できます。
|
|
187
|
+
- **返る文字列はロケール非依存ですが ISO 8601 ではありません**。ISO 8601 が定めるのは暦日・年間通日・週日付の 3 形式だけで、四半期の表記はありません。
|
|
188
|
+
|
|
189
|
+
`2025年度 第2四半期` のような地域化した表記は、`resolveQuarter` から利用側が組み立てます。年は必ず `year` から取ってください。1 月境界を跨ぐ四半期では `startDate.getFullYear()` と一致しません (`yearStartMonth` が `3` のとき `2026-01-15` は `year: 2025` / `startDate: 2026-01-01`)。
|
|
190
|
+
|
|
191
|
+
```tsx
|
|
192
|
+
import { resolveQuarter } from "@aiquants/period-slider"
|
|
193
|
+
|
|
194
|
+
const FISCAL_YEAR_START_MONTH = 3
|
|
195
|
+
|
|
196
|
+
const formatFiscalQuarterJa = (date: Date): string => {
|
|
197
|
+
const { year, quarter } = resolveQuarter(date, FISCAL_YEAR_START_MONTH)
|
|
198
|
+
return `${year}年度 第${quarter}四半期`
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
formatFiscalQuarterJa(new Date(2026, 0, 15)) // "2025年度 第4四半期"
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
年の部分だけは `locale` に従わせられます。年ラベルと同じ公開経路 (`normalizeDateByUnit` を通した `formatLabel("year", ...)`) を使うと、`Q` の綴りだけがロケール非依存のまま残ります。
|
|
205
|
+
|
|
206
|
+
```tsx
|
|
207
|
+
import { formatLabel, normalizeDateByUnit, resolveQuarter } from "@aiquants/period-slider"
|
|
208
|
+
|
|
209
|
+
const formatQuarterWithLocale = (date: Date, locale?: string): string => {
|
|
210
|
+
const { quarter } = resolveQuarter(date, FISCAL_YEAR_START_MONTH)
|
|
211
|
+
// 年の切り出しを自前で書くと、年ラベルと四半期ラベルが年について食い違い得る
|
|
212
|
+
const year = formatLabel("year", normalizeDateByUnit("year", date, FISCAL_YEAR_START_MONTH), undefined, locale)
|
|
213
|
+
return `${year} Q${quarter}`
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
formatQuarterWithLocale(new Date(2025, 3, 1)) // "2025 Q1"
|
|
217
|
+
formatQuarterWithLocale(new Date(2025, 3, 1), "ja-JP") // "2025年 Q1"
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
`PeriodQuarter` の各フィールド、`yearStartMonth` ごとの出力表、例外の契約は [公開ユーティリティ関数](#公開ユーティリティ関数) にまとめてあります。
|
|
221
|
+
|
|
163
222
|
### ゼロ・ボイラープレート React フック連携 (`usePeriodSliderRange`)
|
|
164
223
|
|
|
165
224
|
ステート管理・単一要素ミューテータ・セレクタ連動を 1 行で完結できます。
|
|
@@ -394,11 +453,11 @@ export function DiscreteExample() {
|
|
|
394
453
|
|
|
395
454
|
### PeriodSlider (カスタムラベル & 独立 2 点選択)
|
|
396
455
|
|
|
397
|
-
四半期表示などのカスタムフォーマット (`formatLabel`) や、2 点間の連結バーを非表示にする `hideConnectBar={true}`
|
|
456
|
+
四半期表示などのカスタムフォーマット (`formatLabel`) や、2 点間の連結バーを非表示にする `hideConnectBar={true}` を組み合わせた設定例です。四半期の文字列はパッケージが公開する `formatQuarterLabel` で作ります (`Math.floor(month / 3)` を自前で書くと、年度運用へ移したときに年と四半期が食い違います)。
|
|
398
457
|
|
|
399
458
|
```tsx
|
|
400
|
-
import { PeriodSlider } from "@aiquants/period-slider"
|
|
401
|
-
import { useState } from "react"
|
|
459
|
+
import { formatQuarterLabel, PeriodSlider } from "@aiquants/period-slider"
|
|
460
|
+
import { useCallback, useState } from "react"
|
|
402
461
|
|
|
403
462
|
export function CustomLabelExample() {
|
|
404
463
|
const [range, setRange] = useState<[Date, Date]>([
|
|
@@ -406,11 +465,8 @@ export function CustomLabelExample() {
|
|
|
406
465
|
new Date(2024, 6, 1),
|
|
407
466
|
])
|
|
408
467
|
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
const q = Math.floor(date.getMonth() / 3) + 1
|
|
412
|
-
return `${y}-Q${q}`
|
|
413
|
-
}
|
|
468
|
+
// 暦四半期 (1-3 月が Q1): 2024-01-01 -> "2024-Q1"、2024-07-01 -> "2024-Q3"
|
|
469
|
+
const formatCalendarQuarter = useCallback((date: Date) => formatQuarterLabel(date, 0), [])
|
|
414
470
|
|
|
415
471
|
return (
|
|
416
472
|
<PeriodSlider
|
|
@@ -420,7 +476,7 @@ export function CustomLabelExample() {
|
|
|
420
476
|
maxDate={new Date(2025, 11, 31)}
|
|
421
477
|
range={range}
|
|
422
478
|
hideConnectBar={true}
|
|
423
|
-
formatLabel={
|
|
479
|
+
formatLabel={formatCalendarQuarter}
|
|
424
480
|
tooltipStyle="balloon"
|
|
425
481
|
onChangeRange={(lower, upper) => setRange([lower, upper])}
|
|
426
482
|
/>
|
|
@@ -428,6 +484,68 @@ export function CustomLabelExample() {
|
|
|
428
484
|
}
|
|
429
485
|
```
|
|
430
486
|
|
|
487
|
+
同じレールへ年度四半期 (4 月開始) を載せる場合も、変えるのは `formatQuarterLabel` の第 2 引数だけです。レールの構成 (`unit` / `minDate` / `maxDate`) は 1 文字も変わりません。
|
|
488
|
+
|
|
489
|
+
```tsx
|
|
490
|
+
import { formatQuarterLabel, PeriodSlider } from "@aiquants/period-slider"
|
|
491
|
+
import { useCallback, useState } from "react"
|
|
492
|
+
|
|
493
|
+
const FISCAL_YEAR_START_MONTH = 3
|
|
494
|
+
|
|
495
|
+
export function FiscalQuarterLabelExample() {
|
|
496
|
+
const [range, setRange] = useState<[Date, Date]>([
|
|
497
|
+
new Date(2024, 0, 1),
|
|
498
|
+
new Date(2024, 6, 1),
|
|
499
|
+
])
|
|
500
|
+
|
|
501
|
+
// 年度四半期 (4-6 月が Q1): 2024-01-01 -> "2023-Q4"、2024-07-01 -> "2024-Q2"
|
|
502
|
+
const formatFiscalQuarter = useCallback((date: Date) => formatQuarterLabel(date, FISCAL_YEAR_START_MONTH), [])
|
|
503
|
+
|
|
504
|
+
return (
|
|
505
|
+
<PeriodSlider
|
|
506
|
+
mode="range"
|
|
507
|
+
unit="month"
|
|
508
|
+
minDate={new Date(2023, 0, 1)}
|
|
509
|
+
maxDate={new Date(2025, 11, 31)}
|
|
510
|
+
range={range}
|
|
511
|
+
hideConnectBar={true}
|
|
512
|
+
formatLabel={formatFiscalQuarter}
|
|
513
|
+
tooltipStyle="balloon"
|
|
514
|
+
onChangeRange={(lower, upper) => setRange([lower, upper])}
|
|
515
|
+
/>
|
|
516
|
+
)
|
|
517
|
+
}
|
|
518
|
+
```
|
|
519
|
+
|
|
520
|
+
同じ 2 つの日付が、2 つの四半期系で次のように分かれます。
|
|
521
|
+
|
|
522
|
+
| 日付 | `formatQuarterLabel(date, 0)` | `formatQuarterLabel(date, 3)` |
|
|
523
|
+
| :--- | :--- | :--- |
|
|
524
|
+
| `2024-01-01` | `"2024-Q1"` | `"2023-Q4"` |
|
|
525
|
+
| `2024-07-01` | `"2024-Q3"` | `"2024-Q2"` |
|
|
526
|
+
|
|
527
|
+
上の 2 例はどちらも `yearStartMonth` Props を渡していません。`unit="month"` のレールには動かすべき年の境界が無いためです (渡しても値の検証が走るだけで、つまみの位置もラベルも変わりません)。Props が効くのは年の格子を持つ構成 — `unit="year"`、ノギスの `macroUnit="year"`、年解像度の `allowedDates` — で、そこでもラベルの四半期系を決めるのは関数の第 2 引数のままです。
|
|
528
|
+
|
|
529
|
+
```tsx
|
|
530
|
+
// 年度レールの上に年度四半期を載せる (抜粋): 定数は 1 つ、渡す先は 2 つ、どちらも明示的
|
|
531
|
+
<PeriodSlider
|
|
532
|
+
mode="vernier"
|
|
533
|
+
unit="month"
|
|
534
|
+
macroUnit="year"
|
|
535
|
+
microUnit="month"
|
|
536
|
+
yearStartMonth={FISCAL_YEAR_START_MONTH}
|
|
537
|
+
minDate={new Date(2020, 3, 1)}
|
|
538
|
+
maxDate={new Date(2026, 2, 31)}
|
|
539
|
+
macroRange={macroRange}
|
|
540
|
+
microRange={microRange}
|
|
541
|
+
formatMicroLabel={formatFiscalQuarter}
|
|
542
|
+
onChangeMacroRange={(lower, upper) => setMacroRange([lower, upper])}
|
|
543
|
+
onChangeMicroRange={(lower, upper) => setMicroRange([lower, upper])}
|
|
544
|
+
/>
|
|
545
|
+
```
|
|
546
|
+
|
|
547
|
+
四半期フォーマッタを `formatMacroLabel` ではなく `formatMicroLabel` へ渡している点が要点です。マクロつまみが `macroUnit="year"` のとき、フォーマッタが受け取る日付は必ずその年の先頭月なので、四半期は常に Q1 になります。
|
|
548
|
+
|
|
431
549
|
### ポインター操作の約束
|
|
432
550
|
|
|
433
551
|
- **1 つの操作が押下から解放まで値の持ち主です**: 掴んでいる間は、2 本目の指の押下も `Shift` + ホイールも矢印キーもステッパーも値を動かしません (ホイールはページのスクロールのままです)。ネイティブの `range` 入力と同じく、先に押した指のものです。
|
|
@@ -465,6 +583,7 @@ export function CustomLabelExample() {
|
|
|
465
583
|
| :--- | :--- | :--- | :--- |
|
|
466
584
|
| `mode` | `"range" \| "point" \| "vernier"` | (必須) | 操作モード (`range`: 2 点範囲選択, `point`: 1 点選択, `vernier`: ノギス 2 段スケール一体型) |
|
|
467
585
|
| `unit` | `"year" \| "month" \| "day"` | (必須) | 時間解像度単位 |
|
|
586
|
+
| `yearStartMonth` | `number` | `0` | `unit="year"` (ノギスの `macroUnit="year"` / `microUnit="year"` を含む) の 1 年が始まる暦月 (0 始まり)。`3` は 4 月〜翌 3 月の会計年度、`9` は 10 月〜翌 9 月のでん粉年度。**年はその年の先頭月が属する暦年で名乗ります** (`yearStartMonth={3}` なら 2025-04-01 〜 2026-03-31 が「2025 年」)。`allowedDates` / `macroAllowedDates` の要素は「その日を含む年」として読まれるため、年解像度の候補は `new Date(y, yearStartMonth, 1)` で渡してください (1 月 1 日を渡すと `yearStartMonth={3}` では前年の候補になります)。`unit="month"` / `"day"` のレールには年の境界が無いため位置は変わりません。`0`〜`11` の整数以外 (`12` / `-1` / `1.5` / `NaN` / `null`) は `RangeError`、未指定は仕様上の `0` (暦年) |
|
|
468
587
|
| `minDate` | `Date` | (必須) | 選択可能最小日付。欠落・Invalid Date は `RangeError` |
|
|
469
588
|
| `maxDate` | `Date` | (必須) | 選択可能最大日付。`minDate` より厳密に後であること。欠落・Invalid Date・逆転は `RangeError` |
|
|
470
589
|
| `allowedDates` | `Date[]` | `undefined` | 離散スナップ対象日付配列 (指定時はこの日付のみにスナップ)。`[minDate, maxDate]` 外の要素は除外され、全要素が範囲外なら `RangeError` |
|
|
@@ -476,7 +595,7 @@ export function CustomLabelExample() {
|
|
|
476
595
|
| `hideConnectBar` | `boolean` | `false` | 範囲選択バー (ハイライト) を非表示にし、独立 2 点選択 UI として利用 |
|
|
477
596
|
| `showTicks` | `boolean` | `false` | 離散モード時のトラック上の目盛線の表示有無 |
|
|
478
597
|
| `showStepper` | `boolean` | `true` | ステッパーボタンの表示有無 (水平時は左右、垂直時は上下を指す矢印) |
|
|
479
|
-
| `formatLabel` | `(date: Date) => string` | `undefined` | 日付ラベル・ツールチップのカスタム表示文字列生成関数。`locale`
|
|
598
|
+
| `formatLabel` | `(date: Date) => string` | `undefined` | 日付ラベル・ツールチップのカスタム表示文字列生成関数。`locale` より優先される。ノギスでは `formatMacroLabel` / `formatMicroLabel` 双方の既定値でもあるため、ここへ四半期フォーマッタを渡すと**マクロ側にも同じ関数が流れ**、マクロラベルが常に Q1 になる。ノギスで四半期を出すなら `formatMicroLabel` にだけ渡す |
|
|
480
599
|
| `locale` | `string` | `undefined` | 組み込み日付表記のロケール (BCP 47 言語タグ)。未指定はロケール非依存の ISO 8601 (`2025` / `2025-01` / `2025-01-15`)、指定時は `Intl.DateTimeFormat` 書式。空文字列・不正タグ・非文字列は `RangeError` |
|
|
481
600
|
| `disabled` | `boolean` | `false` | スライダーの無効化・非活性表示 |
|
|
482
601
|
| `debounceMs` | `number` | `0` | 変更コールバック呼び出しのデバウンス時間 (ミリ秒)。`0` は即時発火 |
|
|
@@ -518,8 +637,8 @@ export function CustomLabelExample() {
|
|
|
518
637
|
| `microIsDiscrete` | `boolean` | `false` | ミクロ側の離散スナップ有効化フラグ。`false` の間は `microAllowedDates` が参照されない。`true` かつ現在のマクロ窓が候補を 1 つ以上含む間、ミクロレールは候補集合しか描かないため、位置・`aria-valuenow` / `aria-valuetext`・ラベル・**確定値**のすべてが最近傍候補へ解決される (ドラッグ・キーボード・ホイール・ステッパー・フックの収め込みで同一規則)。窓が候補を 1 つも含まない場合は窓内の連続値として振る舞う |
|
|
519
638
|
| `macroAllowedDates` | `Date[]` | `allowedDates` | マクロ側の離散スナップ対象日付配列。`macroIsDiscrete={true}` との併用が必須 |
|
|
520
639
|
| `microAllowedDates` | `Date[]` | `allowedDates` | ミクロ側の離散スナップ対象日付配列。`microIsDiscrete={true}` との併用が必須。候補はマクロ窓で切り出され、窓の外の日付へはキーボード・ポインターのいずれからも到達しない。窓内に候補が 1 件も残らない場合、ミクロレールは窓内の連続値として振る舞う |
|
|
521
|
-
| `formatMacroLabel` | `(date: Date) => string` | `formatLabel` | マクロ側ラベル・ツールチップのカスタム表示文字列生成関数。引数はつまみ位置・`aria-valuenow` と同一の符号値から復元した `macroUnit` 正規化済み `Date` であり、`macroRange` の生の値ではない (`macroUnit="month"` なら常に月初、`"year"`
|
|
522
|
-
| `formatMicroLabel` | `(date: Date) => string` | `formatLabel` | ミクロ側ラベル・ツールチップのカスタム表示文字列生成関数。引数はつまみ位置と同一の `microUnit` 正規化済み `Date` (`microUnit="month"` なら常に月初) |
|
|
640
|
+
| `formatMacroLabel` | `(date: Date) => string` | `formatLabel` | マクロ側ラベル・ツールチップのカスタム表示文字列生成関数。引数はつまみ位置・`aria-valuenow` と同一の符号値から復元した `macroUnit` 正規化済み `Date` であり、`macroRange` の生の値ではない (`macroUnit="month"` なら常に月初、`"year"` なら常にその年の先頭月 1 日 (`yearStartMonth` が `0` なら元日)、`"day"` は暦日そのままで時刻が 0 時)。`macroUnit="year"` では引数が必ず年の先頭月であるため、ここへ四半期フォーマッタを渡すと表示は常に Q1 になる (四半期は月・日解像度のミクロ側へ載せる) |
|
|
641
|
+
| `formatMicroLabel` | `(date: Date) => string` | `formatLabel` | ミクロ側ラベル・ツールチップのカスタム表示文字列生成関数。引数はつまみ位置と同一の `microUnit` 正規化済み `Date` (`microUnit="month"` なら常に月初)。四半期ラベルはこの `microUnit="month"` / `"day"` の側に載せる。`formatQuarterLabel` へ渡す `yearStartMonth` はその関数自身の引数であり、スライダーの `yearStartMonth` Props とは独立に選べる |
|
|
523
642
|
| `vernierOrientation` | `"macro-top" \| "macro-bottom" \| "macro-left" \| "macro-right"` | 水平時 `"macro-top"` / `isVertical` 時 `"macro-left"` | ノギスのレール配置。水平時は上下 (`macro-top` / `macro-bottom`)、垂直時は左右 (`macro-left` / `macro-right`) を指定 |
|
|
524
643
|
| `showVernierProjection` | `boolean` | `true` | マクロ窓からミクロ全幅へ広がる半透明台形プロジェクション光の表示有無 |
|
|
525
644
|
| `showVernierTicks` | `boolean` | `true` | 目盛線の表示有無。マクロレールに 20% 間隔で 4 本、ミクロレールに 10% 間隔で 9 本を等間隔に描画する |
|
|
@@ -558,7 +677,7 @@ export function CustomLabelExample() {
|
|
|
558
677
|
| `macroUpperAriaLabel` | `string` | `"Macro range end"` | マクロ上限つまみのアクセシブル名 (`mode="vernier"` のみ) |
|
|
559
678
|
| `decreaseAriaLabel` | `string` | `"Decrease"` | 値を `minDate` 方向へ 1 単位動かすステッパーボタンのアクセシブル名 (水平時は左端の左向き矢印、垂直時は下端の下向き矢印) |
|
|
560
679
|
| `increaseAriaLabel` | `string` | `"Increase"` | 値を `maxDate` 方向へ 1 単位動かすステッパーボタンのアクセシブル名 (水平時は右端の右向き矢印、垂直時は上端の上向き矢印) |
|
|
561
|
-
| `formatAriaValueText` | `(date: Date, unit: PeriodSliderUnit) => string` | `undefined` | `aria-valuetext` の読み上げ文字列生成関数。未指定時は可視ラベルと同一の文字列 (ISO 8601、`locale` 指定時は `Intl.DateTimeFormat` 書式)。ノギスでは可視ラベルと同じく、マクロ側に `macroUnit` 正規化済み、ミクロ側に `microUnit` 正規化済みの `Date`
|
|
680
|
+
| `formatAriaValueText` | `(date: Date, unit: PeriodSliderUnit) => string` | `undefined` | `aria-valuetext` の読み上げ文字列生成関数。未指定時は可視ラベルと同一の文字列 (ISO 8601、`locale` 指定時は `Intl.DateTimeFormat` 書式)。ノギスでは可視ラベルと同じく、マクロ側に `macroUnit` 正規化済み、ミクロ側に `microUnit` 正規化済みの `Date` が渡される。**指定すると、`aria-valuetext` を組み立てる 6 か所すべてで可視ラベルの経路 (`formatScreenReaderLabel`) を短絡します**。四半期ラベルを表示しているなら、ここへ渡す文字列も**同じ `resolveQuarter` 呼び出し**から組み立ててください (省略すれば可視ラベルと一字一句同じ文字列が読み上げられます) |
|
|
562
681
|
|
|
563
682
|
ステッパーの 2 つの名称は配置ではなく値への作用で定義されています。同じボタンが水平レイアウトでは左、垂直レイアウトでは下に立つため、位置で命名すると意味が反転するからです。
|
|
564
683
|
|
|
@@ -598,6 +717,82 @@ DOM 要素の特定は CSS クラス名ではなく `data-*` 属性で行いま
|
|
|
598
717
|
| `[data-duplicate="true"]` | 同じ値が二重に描かれる側を隠す唯一の印。対象は 2 種類で、いずれも符号化値 (`aria-valuenow`) の厳密一致が条件。(1) 同じ値に重なった対のうち冗長な側のつまみラベル 1 枚 — 対は Range の下限 / 上限、ノギスのマクロ下限 / 上限、ノギスのミクロ期間形態のミクロ下限 / 上限の 3 つで、Point モードとノギスのミクロ時点形態には付かない。(2) 指している値がつまみの確定値と一致したときのオーバーレイの追従ラベル — こちらは Point モードでも付く (`tooltipStyle="hover"` ではつまみのラベルが描かれず二重にならないため付かない) |
|
|
599
718
|
| `[data-handle-type="macro-low"] [data-tooltip-style]` | 個々のノギスラベル。ノギスのツールチップは親つまみ経由で特定する。水平レール (`macro-top` / `macro-bottom`) かつ `autoSlantLabels` 有効時はインライン `style` に `--ps-tooltip-tx` / `--ps-tooltip-ty` / `--ps-tooltip-rot` の 3 つを持ち (`--ps-tooltip-ty` はレール基準からの生のピクセル差分)、垂直レール (`macro-left` / `macro-right`)、`autoSlantLabels={false}`、およびミクロ時点形態のミクロラベルでは `style` 属性を持たない (時点には離す相手が居ないため傾斜計算そのものを行わない) |
|
|
600
719
|
|
|
720
|
+
### 公開ユーティリティ関数
|
|
721
|
+
|
|
722
|
+
`PeriodSlider` が内部で使う純粋関数のうち、次のものはパッケージのルート (`@aiquants/period-slider`) から公開されています。React に依存しないため、レールの外 (取得期間の算出、集計キーの生成など) でもそのまま使えます。
|
|
723
|
+
|
|
724
|
+
#### 四半期 — `resolveQuarter` / `formatQuarterLabel`
|
|
725
|
+
|
|
726
|
+
```ts
|
|
727
|
+
export interface PeriodQuarter {
|
|
728
|
+
/** その年の先頭月が属する暦年 */
|
|
729
|
+
year: number
|
|
730
|
+
/** その年の中の四半期序数 (1 始まり) */
|
|
731
|
+
quarter: 1 | 2 | 3 | 4
|
|
732
|
+
/** 四半期先頭の現地 0 時 */
|
|
733
|
+
startDate: Date
|
|
734
|
+
}
|
|
735
|
+
|
|
736
|
+
export declare const resolveQuarter: (d: Date, yearStartMonth: number) => PeriodQuarter
|
|
737
|
+
export declare const formatQuarterLabel: (d: Date, yearStartMonth: number) => string
|
|
738
|
+
```
|
|
739
|
+
|
|
740
|
+
- **`yearStartMonth` は 2 関数とも必須**で、下の 8 つのヘルパーが持つ `= 0` とは意図的に違えてあります。省略を暦四半期として黙って解釈すると、年度四半期のつもりの呼び出しが 1 四半期ずれたまま通るためです。
|
|
741
|
+
- **`yearStartMonth` は関数自身の引数**であり、スライダーの同名 Props を読むものではありません。年度レール上の暦四半期も、暦年レール上の年度四半期も表現できます。
|
|
742
|
+
- 序数の型は `PeriodQuarter["quarter"]` で参照できるため、地域化テーブルの添字にキャストが要りません (`const JA: Record<PeriodQuarter["quarter"], string>`)。
|
|
743
|
+
- `yearStartMonth` を含む四半期が必ず Q1 です。`year` はその年の先頭月が属する暦年で、**`startDate.getFullYear()` と一致するとは限りません** (`yearStartMonth` が `3` のとき `2026-01-15` は `year: 2025` / `startDate: 2026-01-01`)。ラベルの年は必ず `year` から取ってください。
|
|
744
|
+
- `formatQuarterLabel` が返す `"<year>-Q<n>"` はロケール非依存ですが **ISO 8601 ではありません** (ISO 8601 が定めるのは暦日・年間通日・週日付の 3 形式のみ)。
|
|
745
|
+
|
|
746
|
+
`formatQuarterLabel(date, yearStartMonth)` の出力:
|
|
747
|
+
|
|
748
|
+
| 日付 | `yearStartMonth: 0` | `yearStartMonth: 3` (4-3 月) | `yearStartMonth: 9` (10-9 月) |
|
|
749
|
+
| :--- | :--- | :--- | :--- |
|
|
750
|
+
| `2025-01-15` | `"2025-Q1"` | `"2024-Q4"` | `"2024-Q2"` |
|
|
751
|
+
| `2025-04-01` | `"2025-Q2"` | `"2025-Q1"` | `"2024-Q3"` |
|
|
752
|
+
| `2025-12-31` | `"2025-Q4"` | `"2025-Q3"` | `"2025-Q1"` |
|
|
753
|
+
| `2026-03-31` | `"2026-Q1"` | `"2025-Q4"` | `"2025-Q2"` |
|
|
754
|
+
|
|
755
|
+
**四半期の境界は `yearStartMonth` を 3 で割った剰余だけで決まり、番号は `yearStartMonth` そのもので決まります。** 上の 4 日付の `resolveQuarter(date, ...).startDate` は `yearStartMonth` が `0` / `3` / `9` のいずれでも同一 (`2025-01-01` / `2025-04-01` / `2025-10-01` / `2026-01-01`) で、動くのは番号だけです。3 の倍数でない開始月 (`1`, `2`, `4`, `5`, `7`, `8`, `10`, `11`) では境界そのものが動きます (`yearStartMonth: 1` は 2 月〜4 月が Q1 で、`2025-04-01` は `"2025-Q1"` / `startDate: 2025-02-01`)。
|
|
756
|
+
|
|
757
|
+
月 (1 月〜12 月) から四半期序数への対応:
|
|
758
|
+
|
|
759
|
+
```text
|
|
760
|
+
yearStartMonth=0 1,1,1,2,2,2,3,3,3,4,4,4
|
|
761
|
+
yearStartMonth=1 4,1,1,1,2,2,2,3,3,3,4,4
|
|
762
|
+
yearStartMonth=3 4,4,4,1,1,1,2,2,2,3,3,3
|
|
763
|
+
yearStartMonth=9 2,2,2,3,3,3,4,4,4,1,1,1
|
|
764
|
+
```
|
|
765
|
+
|
|
766
|
+
例外の契約は、パッケージの計算系とラベル系の作法をそのまま踏襲します。
|
|
767
|
+
|
|
768
|
+
| 入力 | `resolveQuarter` (計算系) | `formatQuarterLabel` (ラベル系) |
|
|
769
|
+
| :--- | :--- | :--- |
|
|
770
|
+
| `d` が未指定・Invalid Date | `RangeError` (`normalizeDateByUnit` と同じ) | `""` (`formatLabel` と同じ) |
|
|
771
|
+
| `yearStartMonth` が `0`〜`11` の整数以外 | `RangeError` | `RangeError` |
|
|
772
|
+
| 両方とも不正 | `RangeError` | `""` (無効日付の短絡が `yearStartMonth` の検査より先) |
|
|
773
|
+
|
|
774
|
+
メッセージは必ず呼ばれた関数自身を名指しします (`formatQuarterLabel: yearStartMonth must be an integer between 0 and 11 (received: 12)`)。
|
|
775
|
+
|
|
776
|
+
`quarter` が `1` の日付では、`resolveQuarter(d, ysm).startDate` が `normalizeDateByUnit("year", d, ysm)` と厳密に一致します。四半期の格子とレールの年の格子は同じ 1 つの規則から導かれており、ずれません。
|
|
777
|
+
|
|
778
|
+
#### 年を扱う 8 つのヘルパーの `yearStartMonth` (末尾引数・既定 `0`)
|
|
779
|
+
|
|
780
|
+
| シグネチャ | 役割 |
|
|
781
|
+
| :--- | :--- |
|
|
782
|
+
| `normalizeDateByUnit(unit, d, yearStartMonth = 0)` | 単位先頭への正規化。`unit="year"` は「その日を含む年」の先頭月 1 日 |
|
|
783
|
+
| `encode(unit, d, yearStartMonth = 0)` | 比較用の整数キー。`unit="year"` では年番号そのもの |
|
|
784
|
+
| `decode(unit, val, yearStartMonth = 0)` | 整数キーから日付へ。`unit="year"` は `new Date(val, yearStartMonth, 1)` |
|
|
785
|
+
| `getMacroWindowStartDate(macroUnit, microUnit, d, yearStartMonth = 0)` | マクロ窓の開始境界 |
|
|
786
|
+
| `getMacroWindowEndDate(macroUnit, microUnit, d, yearStartMonth = 0)` | マクロ窓の終了境界。年の末尾は 12 月ではなく、開始月から数えて 12 番目の月 |
|
|
787
|
+
| `resolveMacroWindow(macroUnit, microUnit, macroRange, minDate, maxDate, yearStartMonth = 0)` | マクロ窓と `[minDate, maxDate]` の交差 |
|
|
788
|
+
| `findNearestDateIndex(dates, target, unit, yearStartMonth = 0)` | 昇順配列に対する最近傍の二分探索 |
|
|
789
|
+
| `getSortedAllowedDates(allowedDates, unit, minDate, maxDate, yearStartMonth = 0)` | 離散候補の正規化・重複排除・境界絞り込み |
|
|
790
|
+
|
|
791
|
+
- `yearStartMonth` は**必ず末尾**の引数です。既存の呼び出しは 1 文字も変えずに済み、`0` のときの結果は従来と同一です。
|
|
792
|
+
- 未指定 (`undefined`) は仕様上の値である `0` (暦年) です。`null` は既定引数が効かないため `RangeError` になります。`12` / `-1` / `1.5` / `NaN` / `Infinity` / `"3"` も同じく拒否され、近い月へ丸められることはありません。
|
|
793
|
+
- 検証は**早期 return より前**に行われます。空配列を渡した `getSortedAllowedDates` や 1 要素しかない `findNearestDateIndex` でも、不正な `yearStartMonth` が素通りすることはありません。
|
|
794
|
+
- **`addUnit(unit, d, amount)` は意図的にこの引数を受け取りません。** 開始月をずらした年もちょうど 12 か月であり、加算の結果は `yearStartMonth` に依存しないためです。無視するだけの引数を置けば、「渡せば効く」という嘘の契約を名乗ることになります。
|
|
795
|
+
|
|
601
796
|
### 実行時バリデーション (Fail Fast)
|
|
602
797
|
|
|
603
798
|
本パッケージは欠落値・不正値を既定値や壁時計時刻で代替しません。次の条件では描画時に例外を送出します。
|
|
@@ -824,7 +1019,7 @@ export function SelectorsExample() {
|
|
|
824
1019
|
| `maxYear` | `number` | `undefined` | 選択可能な最大年。`maxDate` と併用時は厳しい方 (早い方) を採用 |
|
|
825
1020
|
| `minDate` | `Date` | `undefined` | 選択可能な最小日付 (年のみ使用)。`minYear` と併用時は厳しい方を採用 |
|
|
826
1021
|
| `maxDate` | `Date` | `undefined` | 選択可能な最大日付 (年のみ使用)。`maxYear` と併用時は厳しい方を採用 |
|
|
827
|
-
| `onChange` | `(date: Date, year: number) => void` | `undefined` | 年変更時コールバック。`date`
|
|
1022
|
+
| `onChange` | `(date: Date, year: number) => void` | `undefined` | 年変更時コールバック。`date` は該当年の先頭月 1 日ローカル 0 時 (`yearStartMonth` が `0` なら 1 月 1 日)、`year` はその年の番号 |
|
|
828
1023
|
| `disabled` | `boolean` | `false` | 無効化フラグ。`true` の間は `onChange` を発火せず、◀▶ とコンボボックス・セレクト・入力をネイティブに無効化する (タブ順から外れ、ポップアップも開かない) |
|
|
829
1024
|
| `className` | `string` | `""` | ルート要素の追加 CSS クラス |
|
|
830
1025
|
| `style` | `React.CSSProperties` | `undefined` | ルート要素のインラインスタイル |
|
|
@@ -833,7 +1028,10 @@ export function SelectorsExample() {
|
|
|
833
1028
|
| `nextYearAriaLabel` | `string` | `"Next year"` | 翌年ボタンのアクセシブル名 |
|
|
834
1029
|
| `selectAriaLabel` | `string` | `"Year"` | 年セレクトのアクセシブル名 |
|
|
835
1030
|
| `locale` | `string` | `undefined` | 選択肢テキストのロケール (BCP 47 言語タグ)。未指定は 4 桁ゼロ埋めの年、指定時は `Intl.DateTimeFormat` 書式。空文字列・不正タグ・非文字列は `RangeError` |
|
|
836
|
-
| `unit` |
|
|
1031
|
+
| `unit` | — | — | **このコンポーネントが宣言していない名前です**。フックの `SelectorProps` をそのままスプレッドできるよう、受け取っても読まれず捨てられます (コンポーネントは必要な Props だけを名前で取り出すため、DOM へも届きません)。型にも宣言が無いので、JSX へ直接書くとコンパイルエラーになります (スプレッドは余剰プロパティ検査を受けないため通ります) |
|
|
1032
|
+
| `yearStartMonth` | `number` | `0` | 1 年が始まる暦月 (0 始まり)。選択肢の年の数え方と `onChange` が返す日付を決めます (`yearStartMonth={3}` なら「2025 年」は 2025-04-01 〜 2026-03-31 で、`onChange` は `2025-04-01` を渡します)。`0`〜`11` の整数以外 (`12` / `-1` / `1.5` / `NaN` / `null`) は `RangeError`、未指定は仕様上の `0` (暦年) |
|
|
1033
|
+
|
|
1034
|
+
`value` / `initialDate` / `minDate` / `maxDate` は「その日付を含む年」として読みます。`yearStartMonth` が `0` 以外のとき、開始月より前の暦月は 1 つ手前の年に属します (`yearStartMonth={3}` では `2025-01-15` は「2024 年」で、その年の選択肢テキストも `2024` です)。
|
|
837
1035
|
|
|
838
1036
|
下限 (`minYear` または `minDate`) と上限 (`maxYear` または `maxDate`) は共に必須です。境界外の年を保持している間は、境界へ丸めず・`RangeError` も送出せず、その年を選択肢へ 1 件加えてそのまま表示します。ステッパーは移動先の年が境界内にある場合だけ有効です (境界の 1 つ外側では戻る側だけが有効、それより外では両方とも使用不可 (`aria-disabled="true"`、フォーカスは保持))。境界外の年が `onChange` へ渡ることはありません。
|
|
839
1037
|
|
|
@@ -861,7 +1059,8 @@ export function SelectorsExample() {
|
|
|
861
1059
|
| `nextMonthAriaLabel` | `string` | `"Next month"` | 翌月ボタンのアクセシブル名 |
|
|
862
1060
|
| `selectAriaLabel` | `string` | `"Month"` | 年月セレクトのアクセシブル名 |
|
|
863
1061
|
| `locale` | `string` | `undefined` | 選択肢テキストのロケール (BCP 47 言語タグ)。未指定は ISO 8601 の `YYYY-MM`、指定時は `Intl.DateTimeFormat` 書式。`<input type="month">` および `<option value>` は常に `yyyy-MM`。空文字列・不正タグ・非文字列は `RangeError` |
|
|
864
|
-
| `unit` |
|
|
1062
|
+
| `unit` | — | — | **このコンポーネントが宣言していない名前です**。フックの `SelectorProps` をそのままスプレッドできるよう、受け取っても読まれず捨てられます (コンポーネントは必要な Props だけを名前で取り出すため、DOM へも届きません)。型にも宣言が無いので、JSX へ直接書くとコンパイルエラーになります (スプレッドは余剰プロパティ検査を受けないため通ります) |
|
|
1063
|
+
| `yearStartMonth` | — | — | `unit` と同じく、このコンポーネントが宣言していない名前です。年の開始月を読むのは `YearSelector` だけで、月・日の格子には動かすべき年の境界がありません |
|
|
865
1064
|
|
|
866
1065
|
境界要件と挙動:
|
|
867
1066
|
|
|
@@ -910,7 +1109,8 @@ const allowedMonths = useMemo(() => baseMonths.map((yyyymm) => new Date(Math.tru
|
|
|
910
1109
|
| `formatYearOption` | `(year: number) => string` | `undefined` | `variant="split-dropdown"` の年選択肢テキスト生成関数 (`locale` より優先) |
|
|
911
1110
|
| `formatMonthOption` | `(month: number) => string` | `undefined` | `variant="split-dropdown"` の月選択肢テキスト生成関数。引数は 1〜12 (`locale` より優先) |
|
|
912
1111
|
| `formatDayOption` | `(day: number) => string` | `undefined` | `variant="split-dropdown"` の日選択肢テキスト生成関数。引数は 1〜31 (`locale` より優先) |
|
|
913
|
-
| `unit` |
|
|
1112
|
+
| `unit` | — | — | **このコンポーネントが宣言していない名前です**。フックの `SelectorProps` をそのままスプレッドできるよう、受け取っても読まれず捨てられます (コンポーネントは必要な Props だけを名前で取り出すため、DOM へも届きません)。型にも宣言が無いので、JSX へ直接書くとコンパイルエラーになります (スプレッドは余剰プロパティ検査を受けないため通ります) |
|
|
1113
|
+
| `yearStartMonth` | — | — | `unit` と同じく、このコンポーネントが宣言していない名前です。年の開始月を読むのは `YearSelector` だけで、月・日の格子には動かすべき年の境界がありません |
|
|
914
1114
|
|
|
915
1115
|
境界要件と挙動:
|
|
916
1116
|
|
|
@@ -950,15 +1150,17 @@ DOM 契約: ルート要素は `data-variant="date|dropdown|split-dropdown"` を
|
|
|
950
1150
|
| `onChange` | `(date: Date) => void` | フックのステートへ連動する選択ハンドラ |
|
|
951
1151
|
| `minDate` | `Date` | セレクタの下限日付 |
|
|
952
1152
|
| `maxDate` | `Date` | セレクタの上限日付 |
|
|
953
|
-
| `unit` | `PeriodSliderUnit` |
|
|
1153
|
+
| `unit` | `PeriodSliderUnit` | セレクタの時間解像度単位。3 セレクタのいずれも宣言していない名前のため、スプレッドされても読まれません |
|
|
1154
|
+
| `yearStartMonth` | `number` | 1 年が始まる暦月 (0 始まり)。読むのは `YearSelector` だけです。型としては任意 (`yearStartMonth?: number`) ですが、4 つのフックは常に解決済みの値を載せます |
|
|
954
1155
|
|
|
955
|
-
`SelectorProps` は上記
|
|
1156
|
+
`SelectorProps` は上記 6 つのみで、`locale` やアクセシブル名 Props は含みません。フックへ渡した `locale` は `sliderProps` にのみ転送されるため、セレクタの書式を揃える場合は `<MonthSelector {...startSelectorProps} locale="ja-JP" />` のように明示的に渡してください。
|
|
956
1157
|
|
|
957
1158
|
#### `usePeriodSliderRange(options)`
|
|
958
1159
|
|
|
959
1160
|
| オプション | 型 | 既定値 | 説明 |
|
|
960
1161
|
| :--- | :--- | :--- | :--- |
|
|
961
1162
|
| `unit` | `PeriodSliderUnit` | (必須) | 時間解像度単位 |
|
|
1163
|
+
| `yearStartMonth` | `number` | `0` | `unit="year"` の 1 年が始まる暦月 (0 始まり)。`sliderProps` と `SelectorProps` の双方へ転送されるだけでなく、フック自身の境界判定・離散候補の解決にも使われます。`0`〜`11` の整数以外は `RangeError` |
|
|
962
1164
|
| `minDate` | `Date` | (必須) | 選択可能最小日付 |
|
|
963
1165
|
| `maxDate` | `Date` | (必須) | 選択可能最大日付 (`minDate` より厳密に後) |
|
|
964
1166
|
| `initialRange` | `[Date, Date]` | (必須) | 初期選択期間 [開始, 終了] |
|
|
@@ -984,6 +1186,7 @@ DOM 契約: ルート要素は `data-variant="date|dropdown|split-dropdown"` を
|
|
|
984
1186
|
| オプション | 型 | 既定値 | 説明 |
|
|
985
1187
|
| :--- | :--- | :--- | :--- |
|
|
986
1188
|
| `unit` | `PeriodSliderUnit` | (必須) | 時間解像度単位 |
|
|
1189
|
+
| `yearStartMonth` | `number` | `0` | `unit="year"` の 1 年が始まる暦月 (0 始まり)。`sliderProps` と `SelectorProps` の双方へ転送されるだけでなく、フック自身の境界判定・離散候補の解決にも使われます。`0`〜`11` の整数以外は `RangeError` |
|
|
987
1190
|
| `minDate` | `Date` | (必須) | 選択可能最小日付 |
|
|
988
1191
|
| `maxDate` | `Date` | (必須) | 選択可能最大日付 (`minDate` より厳密に後) |
|
|
989
1192
|
| `initialValue` | `Date` | (必須) | 初期選択日付 |
|
|
@@ -1004,6 +1207,7 @@ DOM 契約: ルート要素は `data-variant="date|dropdown|split-dropdown"` を
|
|
|
1004
1207
|
| オプション | 型 | 既定値 | 説明 |
|
|
1005
1208
|
| :--- | :--- | :--- | :--- |
|
|
1006
1209
|
| `unit` | `PeriodSliderUnit` | (必須) | 基本時間解像度単位 |
|
|
1210
|
+
| `yearStartMonth` | `number` | `0` | `macroUnit` / `microUnit` が `"year"` のときの 1 年が始まる暦月 (0 始まり)。`sliderProps` と 4 つの `SelectorProps` へ転送されるだけでなく、マクロ窓の解決 (`resolveMacroWindow`)・境界判定・離散候補の解決にも使われます。`0`〜`11` の整数以外は `RangeError` |
|
|
1007
1211
|
| `minDate` | `Date` | (必須) | 全期間マクロの下限日付 |
|
|
1008
1212
|
| `maxDate` | `Date` | (必須) | 全期間マクロの上限日付 (`minDate` より厳密に後) |
|
|
1009
1213
|
| `initialMacroRange` | `[Date, Date]` | (必須) | 初期マクロ表示窓 [開始, 終了] |
|
|
@@ -1040,6 +1244,7 @@ DOM 契約: ルート要素は `data-variant="date|dropdown|split-dropdown"` を
|
|
|
1040
1244
|
| オプション | 型 | 既定値 | 説明 |
|
|
1041
1245
|
| :--- | :--- | :--- | :--- |
|
|
1042
1246
|
| `unit` | `PeriodSliderUnit` | (必須) | 基本時間解像度単位 |
|
|
1247
|
+
| `yearStartMonth` | `number` | `0` | `macroUnit` / `microUnit` が `"year"` のときの 1 年が始まる暦月 (0 始まり)。`sliderProps` と 4 つの `SelectorProps` へ転送されるだけでなく、マクロ窓の解決 (`resolveMacroWindow`)・境界判定・離散候補の解決にも使われます。`0`〜`11` の整数以外は `RangeError` |
|
|
1043
1248
|
| `minDate` | `Date` | (必須) | 全期間マクロの下限日付 |
|
|
1044
1249
|
| `maxDate` | `Date` | (必須) | 全期間マクロの上限日付 (`minDate` より厳密に後) |
|
|
1045
1250
|
| `initialMacroRange` | `[Date, Date]` | (必須) | 初期マクロ表示窓 [開始, 終了] |
|