@aiquants/period-slider 0.12.0 → 0.13.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 CHANGED
@@ -7,6 +7,159 @@ All notable changes to `@aiquants/period-slider` are documented here.
7
7
 
8
8
  ## Unreleased
9
9
 
10
+ パッケージが所有するテキスト面を、1 つのフォーマッタ契約 (`PeriodOptionFormatter`) へ統一。
11
+
12
+ ### 追加
13
+
14
+ - **`formatOption` を `MonthSelector` / `YearSelector` / `DateSelector` の 3 つが受け取ります**。署名は
15
+ `(date: Date, unit: PeriodSliderUnit, scope: PeriodOptionScope) => string` の 1 つだけで、`unit` と `scope` は
16
+ ウィジェットが与えます。1 つのコールバック値をレールの `formatLabel` と 3 つのセレクタの `formatOption` へ渡せば、
17
+ 同じ画面の中で表記が食い違う余地そのものが無くなります (レールが `2025年度 第1四半期` と描く横で、セレクタが
18
+ `2025-04` と読める状態がこれで終わります)。
19
+ - **渡される `Date` は、その面が表す日付です**。`scope: "part"` は自分より粗い部位だけを保持値から取り、
20
+ 細かい部位は 1 に固定します (年は 1 月 1 日、月は当月 1 日、日は保持中の年月とその日)。保持中の細かい部位を
21
+ 混ぜないのは、混ぜると非グレゴリオ暦で同じ `<select>` の別々の値が同じ文字になるためです (「既知の制約」)。
22
+ Invalid Date が渡ることはありません。
23
+ - **4 つのフックが `formatOption` を受け取り、`locale` とともに `SelectorProps` へ載せます**。フックへ 1 度
24
+ 与えれば、レールと同じフックから配線した全セレクタが同じ表記で描きます。**これは挙動の変更です** — 従来は
25
+ `locale` がレールにしか届かず、`usePeriodSliderRange({ …, locale: "ja-JP" })` はレールに `2024/03`、隣の
26
+ セレクタに `2024-03` を出していました (1 つの画面が自分と食い違う状態)。レールとドロップダウンで敢えて別の
27
+ 文字列を出したい利用側は、セレクタへ `formatOption` を直接渡せばスプレッドの後ろに来るため上書きされます。
28
+ - **優先順位は 3 段のままで、段は増えません**: フォーマッタ Props > `locale` (Intl) > ロケール非依存の ISO 8601。
29
+ `scope: "period"` の面はすべて `formatLabel(unit, date, formatOption, locale)` の 1 本であり、優先順位の記述は
30
+ パッケージ全体で 1 箇所です。
31
+ - **組み込みの表記は、1 年以上の年については変わりません**。`"period"` は `2025` / `2025-04` / `2025-04-15`
32
+ (`ja-JP` では `2025年` / `2025/04` / `2025/04/15`)、`"part"` は `2025` / `04` / `15` (`ja-JP` では
33
+ `2025年` / `04月` / `15日`) です。0 年以下だけは下の「利用側の契約が変わる点」のとおり変わります。
34
+ - **`variant="date"` は履行できないため 1 度も呼びません** (表示はブラウザが所有します)。Props を渡すこと自体は
35
+ 合法で、`locale` と同じ扱いです。
36
+ - **戻り値はどの面でも機械可読値へ届きません**。`aria-label`・`<option value>`・`data-value`・
37
+ `variant="date"` の `input.value`・`onChange` が運ぶ値は、いずれもフォーマッタを通りません。
38
+ - **空文字列は合法な戻り値です** (無効日付に対して `formatLabel` が返す仕様上の値と同じであるため)。
39
+ - **`formatOptionText(date, unit, scope, locale?)` を公開します**。組み込みの段そのものであり、一部の
40
+ `(unit, scope)` だけを担当する利用側が残りをそのまま転送するための委譲先です (「`undefined` を返したら既定」という
41
+ 代替値連鎖を書かずに済みます)。宣言外の `unit` / `scope` は自分の名前を含む `RangeError`、Invalid Date は
42
+ 空文字列 (`formatLabel` と同じ約束) です。
43
+ - **型 `PeriodOptionFormatter` と `PeriodOptionScope` (`"period" | "part"`) を公開します**。`"period"` は 1 つの操作要素の
44
+ 値そのもの (月の選択肢・年の選択肢・日の行と、それらの畳んだ表示)、`"part"` は `variant="split-dropdown"` が
45
+ 3 つ並べる部位の 1 つです。
46
+ - **戻り値は読み上げ値にも届くため、読み上げ可能な文字列にしてください**。行き先は選択肢・プレースホルダ・
47
+ 畳んだ表示 (`variant="dropdown"` のコンボボックスでは、入力欄の可視テキストである `value` そのもの) に加え、
48
+ レールのつまみラベル・ホバーツールチップ・`aria-valuetext` です。`formatAriaValueText` を渡していないとき、
49
+ 読み上げ値は `formatLabel` / `formatMacroLabel` / `formatMicroLabel` の戻り値そのものになります
50
+ (`formatScreenReaderLabel` が `formatLabel` へ委譲するため)。記号だけで組んだ装飾は、画面では読めても
51
+ 読み上げでは読めません。
52
+ - **渡される `Date` が確定値でない面は、レールのホバーツールチップだけです** (ポインタ直下の日付が渡ります)。
53
+ セレクタの選択肢・プレースホルダ・畳んだ表示と、レールのつまみラベル・読み上げ値は、いずれも確定値です。
54
+ - **スライダーのフォーマッタ Props 4 つと公開ヘルパー 2 つが、同じ型へ広がりました** (`formatLabel` /
55
+ `formatMacroLabel` / `formatMicroLabel` / `formatAriaValueText`、`formatLabel` / `formatScreenReaderLabel`)。
56
+ `tsc --strict` での実測どおり、引数を減らした `(d: Date) => string` と `(d, u) => string` は引き続き代入可能で、
57
+ 逆向き (3 引数の関数を 1 引数のスロットへ) は `TS2322` (`Target signature provides too few arguments`) です。
58
+ **ただし「余分な引数が省略可能なら通る」という 0.12.0 の感覚は、そのままでは通用しません**。省略可能な第 2 /
59
+ 第 3 引数を持つコールバックは、その型によって代入できなくなるか、型エラーなしで受け取る値が変わります。
60
+ どちらも「利用側の契約が変わる点」に書き下しました。`formatQuarterLabel` は `(Date, number) => string` であり
61
+ `formatOption` の形ではないため、`formatOption={formatQuarterLabel}` はコンパイラが拒否します
62
+ (最も起こりやすい取り違えです)。
63
+ - これで 0.12.0 の「既知の制約」が解けます。四半期は ECMA-402 に無く `Intl` が黙って捨てるため `locale` の段を
64
+ 持ちません。`formatOption` がその経路です。
65
+
66
+ ### 利用側の契約が変わる点 (0.12.0 からの移行)
67
+
68
+ - **0 年以下の年の ISO 表記が変わります (`"00-1"` → `"-000001"`)。** 公開関数 `formatLabel` /
69
+ `formatScreenReaderLabel` / `formatOptionText` の戻り値、つまみラベル、`aria-valuetext`、3 セレクタの選択肢
70
+ テキスト、`MonthSelector` の `<option value>` と `input[type="month"]` の値がこの範囲で変わります。
71
+ 1 年以上の年は 1 文字も変わりません。
72
+ 理由: 年の 0 埋め規則がパッケージ内に 3 通りあり、2 つが誤っていました。同じ 1 日について `data-value` が
73
+ `-000001-01-02` (`formatIsoDay`、以前から正しい) である一方、表示テキストは `00-1-01-02` で、1 つのウィジェットが
74
+ 同じ日付に 2 つの ISO 表記を持っていました。ISO 8601 は 0 年以下に 4 桁形式を持たず、符号を 4 桁へ押し込んだ
75
+ `00-1` はどの規格にも属しません。規則を `formatIsoYear` 1 つへ寄せ、機械可読値側の正しい形へ揃えました。
76
+ 0.12.0 で `"00-1-Q1"` を固定していたテストは `"-000001-Q1"` へ改めています。
77
+
78
+ - **`DateSelector` の `formatYearOption` / `formatMonthOption` / `formatDayOption` を削除しました**。別名も二重経路も
79
+ 残していません。1 つの概念に 4 つの形があった状態 (レールの `(date) => string`、部位別の 3 つ、そして
80
+ `MonthSelector` / `YearSelector` には何も無い) を、`formatOption` 1 つへ畳んだためです。
81
+ - 移行はそのまま 1 行で書けます: `formatMonthOption={(m) => g(m)}` →
82
+ `formatOption={(date, unit, scope) => (scope === "part" && unit === "month" ? g(date.getMonth() + 1) : formatOptionText(date, unit, scope, locale))}`。
83
+ 担当しない組は `formatOptionText` へ転送してください。
84
+ - **旧 Props は数値 1 つしか受け取らなかったため、年度も四半期も表現できませんでした**。`formatYearOption(2019)` からは
85
+ その 4 月がどの年度に属するのかを知る術が無く、`formatMonthOption(4)` は年を知りません。新しいコールバックは
86
+ その選択肢が確定する日付そのものを受け取るため、どちらも導けます。
87
+ - `MonthSelector` と `YearSelector` は元々選択肢のフォーマッタを 1 つも持たず、`locale` しか無かったため、
88
+ こちらは追加のみで移行はありません。
89
+ - **余分な省略可能引数を持つコールバックは、フォーマッタ Props へ渡せなくなる場合があります**。4 つのフォーマッタ
90
+ Props と公開ヘルパー 2 つが 3 引数の `PeriodOptionFormatter` へ広がったため、第 2 引数が省略可能でありながら
91
+ `PeriodSliderUnit` (`"year" | "month" | "day"`) を受けられない型のコールバック (第 3 引数なら `PeriodOptionScope`)
92
+ は代入できません。0.12.0 の `formatLabel?: (date: Date) => string` は、余分な引数が省略可能でありさえすれば
93
+ そのまま受理していたため、**実在する破壊的変更です** (`Array.prototype.map` が誘う
94
+ `(date, index?: number) => string` や、既定値を付けた引数を足した形がこれに当たります)。
95
+ - 実測 (`tsc --strict` / TypeScript 5.9.3)。`const padded = (d: Date, pad = 4): string => …` を `formatLabel` へ
96
+ 渡すと `TS2322: Type '(d: Date, pad?: number) => string' is not assignable to type 'PeriodOptionFormatter'.` に
97
+ 続けて `Types of parameters 'pad' and 'unit' are incompatible. Type 'PeriodSliderUnit' is not assignable to type
98
+ 'number | undefined'.` が出ます。第 3 引数でも同じで、`(d, u: PeriodSliderUnit, pad?: number) => string` は
99
+ `scope` と衝突します。
100
+ - **その場に書いた無名関数では、診断が Props の名前を 1 度も出しません**。
101
+ `formatLabel={(d, verbose = false) => …}` の診断は `TS2322: Type 'false' is not assignable to type
102
+ 'PeriodSliderUnit'` であり、Props ではなく既定値そのものを指します。
103
+ - **移行**: 第 2 / 第 3 引数の型を `unit` / `scope` を受けられる形まで広げるか、1 引数のラッパーで包んでください
104
+ (`formatLabel={(d) => padded(d)}`)。
105
+ - **型エラーにならない側にも一度目を通してください**。余分な引数が `string` / `unknown` / `any` / 可変長のときは
106
+ 0.12.0 でも本リリースでも型エラーになりませんが、0.12.0 が `customFormat(d)` と 1 引数で呼んでいたのに対し
107
+ 本リリースは `customFormat(d, unit, "period")` と呼ぶため、既定値ではなく `unit` と `scope` が入ります
108
+ (`const withMode = (d: Date, mode = "long") => …` の `mode` は `"long"` から `"year"` へ変わり、`tsc` は緑のまま
109
+ 表示テキストだけが変わります)。
110
+ - **分割セレクト (`variant="split-dropdown"`) の日の `<option>` が、発行できない組で `disabled` になります**。年と月の
111
+ 選択肢は以前から `disabled` でしたが、日だけが抜けており、押しても `onChange` が発行されない選択肢が押せる
112
+ 見た目のまま並んでいました。判定は年・月と同じ `isSplitChoiceEmittable` (保持中の年月との組が境界の外、または
113
+ `allowedDates` に無い) です。**`option:disabled` を読むホストの CSS は、以前は当たらなかった要素に当たるように
114
+ なります**。選択肢は一覧に残り、`option` の `value` と発行される日付は変わりません。
115
+ - **`YearSelector` が新しい DOM を持ちます**。保持している年が境界の外にあるとき、ルートが
116
+ `data-out-of-range="true"` を持ち、一覧へ押し込まれるその年の `<option>` が `disabled` になります
117
+ (`MonthSelector` と `DateSelector` が以前から行っていたことに揃えました)。**`[data-out-of-range]` や `:disabled` を
118
+ 読むホストの CSS は、以前は当たらなかった要素に当たるようになります**。選択肢は一覧に残り、`select.value` が
119
+ 実年を持つ挙動は変わりません。境界外の年は以前から発行できず `RangeError` だったため、`disabled` は
120
+ 「押せる」と「発行できる」を揃えるだけです。
121
+
122
+ ### 修正
123
+
124
+ - **分割セレクト (`variant="split-dropdown"`) の各 `<select>` の選択肢テキストは、その `<select>` の値だけから
125
+ 決まります** (年は 1 月 1 日、月は当月 1 日、日は保持中の年月とその日)。保持中の他部位を基準日へ混ぜません。
126
+ 一度は「その選択肢が確定する日付」を基準日にしましたが、**撤回しました**。選択肢テキストは同じ `<select>` の
127
+ 中で相互に区別できること (単射であること) が先であり、非グレゴリオ暦では保持日を混ぜた瞬間に別々の値が
128
+ 同じ文字になるためです。実測 (`fa-IR`・ICU 既定暦は `persian`・2018-01-01〜2022-12-31・保持 2020-03-20):
129
+ 1 月 1 日基準なら年の選択肢は `۱۴۰۰ ۱۳۹۹ ۱۳۹۸ ۱۳۹۷ ۱۳۹۶` と全て異なりますが、確定日基準では
130
+ `۱۴۰۰ ۱۳۹۹ ۱۳۹۹ ۱۳۹۷ ۱۳۹۶` となり 2020 年と 2021 年が同じ文字になります (月も 1 つ消えて 1 つ重複)。
131
+ **既知の制約**: グレゴリオ暦の年・月を、境界の異なる暦 (和暦・ペルシア暦など) で描く以上、
132
+ 「その選択肢が確定する日付の呼び名」と「選択肢どうしが区別できること」は同時には満たせません。本パッケージは
133
+ 後者を採ります。`ja-JP-u-ca-japanese` では 2019 年の選択肢は常に **平成31年** (1 月 1 日の元号) であり、
134
+ 5 月を保持したまま押すと確定するのは令和元年の日付です。区別が要らず確定日の呼び名が要る利用側は
135
+ `formatOption` で自分の基準日を選んでください (日の部位には保持中の年月が渡るため、そこから組めます)。
136
+ - **履行できない面と、描かない文字列のためにフォーマッタを呼びません**。`DateSelector` の畳んだ表示は
137
+ `variant="dropdown"` のとき、`MonthSelector` のプレースホルダは `variant="dropdown"` かつ保持月が候補外のときだけ
138
+ 組み立てます。以前はどちらも毎描画で組み立てては捨てており、利用側のコールバックが入ると「誰も読まない文字列の
139
+ ための呼び出し」になっていました。
140
+ - **`DateSelector` が `Date` でない日付 Props を、形の段階で拒否します**。`value` / `initialDate` / `minDate` /
141
+ `maxDate` は以前 `Number.isNaN(date.getTime())` しか見ていなかったため、型検査を受けない JavaScript の利用側が
142
+ 文字列を渡すと `date.getTime is not a function` という `TypeError` がコンポーネントの内側から飛び、どの Props が
143
+ 原因かを名乗りませんでした。`instanceof Date` を先に見るようにしたため、いまは prop 名を含む `RangeError`
144
+ (`DateSelector: "minDate" must be a valid Date (received 2025-01-01)`) になります (`YearSelector` が以前から
145
+ 行っていたことに揃えました)。TypeScript の利用側は同じ値を型検査が先に弾くため、到達しません。
146
+ - **`YearSelector` の選択肢ラベルが memo の中で組まれます**。以前は JSX の中で組んでいたため、描画のたびに年の数だけ
147
+ 書式化していました (`MonthSelector` は以前から memo の中です)。出力は変わりません。
148
+ - **分割セレクトの選択肢ラベルと `allowedKey` も memo の中で組みます (性能だけの変更で、契約は変わりません)**。年・月・
149
+ 日のラベルは JSX の中ではなく 3 つの `useMemo` の中で (`useCallback` で安定化した 1 つの組み立て関数を通して) 組み、
150
+ `allowedKey` は `allowedDates` の同一性で memo 化しました (以前は描画のたびに候補数に比例する文字列連結を
151
+ コンポーネント本体で行っていました)。描かれるテキストも DOM も変わりません (変わるのは再描画あたりの書式化回数
152
+ だけであり、挙動の変化を探す必要はありません)。
153
+ - **先頭一致入力の契約を書き下しました**。`resolveTypeAheadIndex` は表示書式を一切参照せず (`labelAt` を読みません)、
154
+ 先発グレゴリオ暦の `yyyy[MM[dd]]` の数字だけで解決します。利用側フォーマッタが何を描いても、打鍵と行の対応は
155
+ 動きません。以前の注記は「区切りを落とせば同じ数字になるから」と説明していましたが、これは現行の表示では既に
156
+ 成り立っていませんでした。
157
+ - **内部: `DateOptionDomain.valueAt` を削除しました**。`src/index.ts` はこのモジュールから何も再輸出せず、
158
+ `exports` マップが深いパスを封じているため、公開面の変更ではありません (`src/` に呼び出し元は 1 つもありませんでした)。
159
+ 「選択肢の機械可読値」の第 2 の定義が、表示テキストの新しい引数の隣に残る状態を避けたものです。
160
+
161
+ ## 0.12.0
162
+
10
163
  1 月以外の月から始まる年 (年度) と、その上の四半期。
11
164
 
12
165
  ### 追加
package/README.md CHANGED
@@ -60,7 +60,7 @@
60
60
  - **ノギスの均一 8px クリアランス & ツールチップ色分け**:
61
61
  - ノギス (Vernier) モードでは、上下左右いずれのレールでも半円つまみの平面からラベルまでの距離を 8px に統一 (`--aqps-label-rail-gap` で変更可)。
62
62
  - ノギスモードではマクロツールチップ (`--aqps-macro-color`) とミクロツールチップ (`--aqps-micro-color`) がセマンティックに色分けされ、上下段の対応関係が一目で判別可能。
63
- - **ロケール中立な表示文字列**: 組み込み文字列に特定の言語を持ちません。アクセシブル名の既定値は英語、日付表記の既定値は ISO 8601 で、`locale` を渡せば `Intl.DateTimeFormat` 書式、フォーマッタ Props を渡せば任意書式になります。`<input>` の `value` と `<option value>` は常に ISO 8601 (または生の数値) で、`locale` の影響を受けません。
63
+ - **ロケール中立な表示文字列**: 組み込み文字列に特定の言語を持ちません。アクセシブル名の既定値は英語、日付表記の既定値は ISO 8601 で、`locale` を渡せば `Intl.DateTimeFormat` 書式、フォーマッタ Props を渡せば任意書式になります。フォーマッタ Props はレールの 4 つもセレクタの `formatOption` も同一の `PeriodOptionFormatter` で、1 つのコールバックがパッケージの全テキスト面を賄います。`<input>` の `value` と `<option value>` は常に ISO 8601 (または生の数値) で、`locale` の影響を受けません。
64
64
  - **高いアクセシビリティ**: WAI-ARIA `slider` ロール、キーボード操作 (矢印キー, PageUp/Down, Home/End) 完全準拠 (Vernier ノギスハンドル含む)。
65
65
  - **`Shift` + ホイールによる平行移動**: スライダーの範囲領域 (レールの行・つまみとラベルが描かれる帯 — レール方向にもラベルの外縁まで — ・ステッパー) のどこでも `Shift` を押しながらホイールを回すと、選択がステッパーと同じ ±1 単位だけ平行移動します。インジケーターの真上である必要はありません。`Shift` 無しの素のホイールはページのスクロールのままで、ページのスクロールを奪うのは `Shift` 付きのホイールが使えるデルタを運んでいるときだけです (選択が端に着いていて結果的に何も動かない場合も、操作は範囲領域へ向けられているため奪います)。縦向きレールではレールの正方向が上のため符号が反転します。ノギスではポインターがトラック中心線のどちら側にあるかで段 (マクロレールならマクロ窓、ミクロレールならミクロ選択) が決まり、ステッパーの上ではクリックと同じミクロ選択が動きます。
66
66
  - **レールが描く位置だけを名乗り、そこだけを確定させる**: 離散ミクロレール (`microIsDiscrete`) は候補集合しか描かないため、つまみの位置・読み上げ値・ラベル・そして確定値がすべて同じ 1 規則 (候補があれば最近傍候補、無ければ窓へのクランプ) を読みます。つまみが描かれている場所と利用側が受け取る値が食い違いません。
@@ -128,9 +128,9 @@ peer dependency の `@aiquants/virtualscroll` のスタイルシートは、本
128
128
 
129
129
  ISO 8601 はフォールバックではなく、本パッケージの仕様上の既定値です。英語などの自然言語表記を既定にすると汎用パッケージへ 1 つの言語を焼き付けることになり、`Intl` の出力は ICU / Node のバージョン間で変化するためです。
130
130
 
131
- - **優先順位**: フォーマッタ Props (`formatLabel` / `formatMacroLabel` / `formatMicroLabel` / `formatAriaValueText`、`DateSelector` の `formatYearOption` / `formatMonthOption` / `formatDayOption`) が最優先、次に `locale`、最後に ISO 8601 既定です。四半期表記だけはこの 3 段に乗りません (`locale` の段を持ちません)。理由と書き方は [四半期表示](#四半期表示-暦四半期と年度四半期) を参照してください。
131
+ - **優先順位**: フォーマッタ Props (`PeriodSlider` の `formatLabel` / `formatMacroLabel` / `formatMicroLabel` / `formatAriaValueText`、`YearSelector` / `MonthSelector` / `DateSelector` の `formatOption`) が最優先、次に `locale`、最後に ISO 8601 既定です。この 5 つは**すべて同じ型 `PeriodOptionFormatter`** で、同一の関数値をどのスロットへも渡せます ([1 つのフォーマッタで全テキスト面を決める](#1-つのフォーマッタで全テキスト面を決める-formatoption))。四半期表記だけはこの 3 段に乗りません (`locale` の段を持ちません)。理由と書き方は [四半期表示](#四半期表示-暦四半期と年度四半期) を参照してください。
132
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 セレクト) です。
133
- - **アクセシブル名は `locale` では変わりません**: ボタン・セレクト・つまみの名称は英語既定のままです。翻訳するには `lowerAriaLabel` / `decreaseAriaLabel` / `selectAriaLabel` などのアクセシブル名 Props を渡してください。
133
+ - **アクセシブル名は `locale` では変わりません**: ボタン・セレクト・つまみの名称は英語既定のままです。翻訳するには `lowerAriaLabel` / `decreaseAriaLabel` / `selectAriaLabel` などのアクセシブル名 Props を渡してください。ただし `DateSelector variant="dropdown"` のポップアップにあるスクロールバーの矢印ボタン 2 つだけは例外で、`@aiquants/virtualscroll` が所有する固定の英語名 (`"Scroll up"` / `"Scroll down"`) のままです (翻訳する口がありません)。
134
134
  - **Fail Fast**: 空文字列や `Intl.DateTimeFormat` が受理しない値 (`"en_US"`、非文字列等) を渡した場合、既定の ISO へ黙って戻さず `RangeError` を送出します (メッセージは [実行時バリデーション](#実行時バリデーション-fail-fast) 参照)。`"xx-YY"` のように構造として妥当なタグは、対応する翻訳データが無くても受理されます。
135
135
 
136
136
  ```tsx
@@ -153,6 +153,73 @@ const formatJapaneseDay = (date: Date): string => `${date.getFullYear()}年${Str
153
153
  <PeriodSlider mode="point" unit="day" formatLabel={formatJapaneseDay} minDate={minDate} maxDate={maxDate} value={date} onChangePoint={setDate} />
154
154
  ```
155
155
 
156
+ #### 1 つのフォーマッタで全テキスト面を決める (`formatOption`)
157
+
158
+ レールと 3 セレクタは**同じ 1 つのコールバック型**でテキストを作ります。`PeriodSlider` の `formatLabel` / `formatMacroLabel` / `formatMicroLabel` / `formatAriaValueText` も、`YearSelector` / `MonthSelector` / `DateSelector` の `formatOption` も、いずれも `PeriodOptionFormatter` です。1 つの関数値をすべてへ渡せば、レールが `2025年度 第1四半期` と描いている隣でセレクタが `2025-04` と名乗る、という食い違いが起こりません。
159
+
160
+ ```ts
161
+ type PeriodOptionScope = "period" | "part"
162
+ type PeriodOptionFormatter = (date: Date, unit: PeriodSliderUnit, scope: PeriodOptionScope) => string
163
+ ```
164
+
165
+ - `date` は**その面が表す日付**です。面が所有する単位の先頭へ正規化され、所有しない細かい部位は 1 に固定されます。`scope: "part"` は自分の部位より粗い部位だけを保持値から取り、細かい部位は 1 に固定します (年は 1 月 1 日、月は当月 1 日、日は保持中の年月とその日)。**保持中の細かい部位を混ぜません** — 混ぜると、境界の異なる暦で同じ `<select>` の別々の値が同じ文字になります (下の「既知の制約」)。Invalid Date が渡ることはありません。確定値でない唯一の面はレールのホバーツールチップで、そこではポインタ下の日付が渡ります。
166
+ - `unit` と `scope` は**ウィジェットが与えます**。利用側が単位を言い当てるラッパーを書く必要はなく、年・月・日のどの面かは引数から判ります。
167
+ - `scope: "period"` はその操作要素の値そのもの (年・月・日それぞれの選択肢 1 件と、畳んだ表示)、`scope: "part"` は `variant="split-dropdown"` が横に 3 つ並べる部位の 1 つです。同じ `"month"` でも、前者は「年月全体」、後者は「月の部位」を指します。組み込みの段はこの 2 つを別の書式で描きます。
168
+
169
+ | `scope` | `unit="year"` | `unit="month"` | `unit="day"` |
170
+ | :--- | :--- | :--- | :--- |
171
+ | `"period"` (`locale` 未指定) | `2025` | `2025-04` | `2025-04-15` |
172
+ | `"period"` (`locale="ja-JP"`) | `2025年` | `2025/04` | `2025/04/15` |
173
+ | `"part"` (`locale` 未指定) | `2025` | `04` | `15` |
174
+ | `"part"` (`locale="ja-JP"`) | `2025年` | `04月` | `15日` |
175
+
176
+ 面ごとの呼び出しは次の通りです。
177
+
178
+ | コンポーネント / バリアント | 面 | `unit` | `scope` | `date` |
179
+ | :--- | :--- | :--- | :--- | :--- |
180
+ | `YearSelector` | 選択肢・畳んだ表示・境界外の保持年 | `"year"` | `"period"` | その年の先頭月 1 日 (`yearStartMonth` 準拠) |
181
+ | `MonthSelector variant="dropdown"` | 選択肢・畳んだ表示 | `"month"` | `"period"` | その月の 1 日 |
182
+ | `MonthSelector variant="dropdown"` | 集合外プレースホルダ | `"month"` | `"period"` | 保持中の日付 |
183
+ | `MonthSelector variant="date"` | ネイティブ入力 | — | — | **呼び出さない** |
184
+ | `DateSelector variant="dropdown"` | 仮想化された `role="option"` 行 | `"day"` | `"period"` | その行の日付 |
185
+ | `DateSelector variant="dropdown"` | 操作要素の表示テキスト (畳んだ表示) | `"day"` | `"period"` | 保持中の日付 |
186
+ | `DateSelector variant="split-dropdown"` | 年の選択肢とプレースホルダ | `"year"` | `"part"` | その年の 1 月 1 日 |
187
+ | `DateSelector variant="split-dropdown"` | 月の選択肢とプレースホルダ | `"month"` | `"part"` | 保持中の年の、その月の 1 日 |
188
+ | `DateSelector variant="split-dropdown"` | 日の選択肢とプレースホルダ | `"day"` | `"part"` | 保持中の年月の、その日 |
189
+ | `DateSelector variant="date"` | ネイティブ入力 | — | — | **呼び出さない** |
190
+ | ステッパー ◀▶ (3 セレクタ共通) | SVG の矢印 | — | — | **テキストノードを持たない** |
191
+ | `PeriodSlider` | つまみラベル・ツールチップ・マクロ / ミクロレール・`aria-valuetext` | 各単位 | `"period"` | 各つまみの日付 (ホバーツールチップだけはポインタ下の日付) |
192
+
193
+ `<select>` の畳んだ表示は選択中の `<option>` のテキストそのもの (HTML の規定) なので、一覧と畳んだ表示が食い違うことはありません。`DateSelector variant="dropdown"` だけは一覧行と操作要素が別経路ですが、**同じ関数値へ同じ形の引数**を渡すため同じ文字列になります。
194
+
195
+ 返り値は画面に出るだけのテキストではありません。レールのつまみは同じ文字列を `aria-valuetext` として読み上げ、`variant="dropdown"` のコンボボックスはそれを可視テキストである `value` として持ちます。**読み上げられる前提のテキストを返してください** — 記号や罫線だけのラベルは、晴眼者に見えている値がそのまま読み上げ不能になります。
196
+
197
+ **フォーマッタが届かない先** (いずれも別の関数が別の経路で作ります):
198
+
199
+ - すべての `aria-label` (◀▶・セレクト・コンボボックス・ポップアップの `listbox`)。これらを翻訳するには `selectAriaLabel` などのアクセシブル名 Props を渡してください。ただし `DateSelector variant="dropdown"` のポップアップは、この 4 種に加えてスクロールバーの矢印ボタン 2 つが `aria-label="Scroll up"` / `"Scroll down"` を持ちます。この 2 つは `@aiquants/virtualscroll` が所有する固定文字列で、**本パッケージのどの Props からも翻訳できません** (常に `disabled` のためタブ順には入らず、支援技術がポップアップ内を辿ったときに現れます)。
200
+ - すべての機械可読値: `<option value>`、`variant="dropdown"` の `data-value`、`<input type="date">` / `<input type="month">` の `value` / `min` / `max`。
201
+ - `onChange` が渡す引数。表示を変えても発行される `Date` は 1 ミリ秒も動きません。
202
+
203
+ **呼び出しすら行わない面**: `MonthSelector variant="date"` と `DateSelector variant="date"` です。ネイティブ入力の表示テキストはブラウザが所有し、DOM 上に差し込む場所がありません (`locale` も同じ理由で届きません)。受け取って無視するだけで、例外にはなりません — `variant` を切り替えただけで落ちると、Props を 1 度設定して使い分ける形が壊れるためです。
204
+
205
+ **先頭一致入力は表示書式に追従しません**。`DateSelector variant="dropdown"` の打鍵は、`formatOption` が何を描いていても**先発グレゴリオ暦の `yyyy[MM[dd]]` の数字列**として解釈されます。`20250309` と打てば 2025-03-09 の行へ飛び、その行の表示が `2024年度 第4四半期 (2025/03/09)` であっても変わりません。表示テキストの前方一致照合は選択肢総数に比例する費用になり、1 打鍵あたり定数時間という保証を壊すため採用していません。
206
+
207
+ **参照比較で再描画を判定するため、利用側でメモ化してください** (`allowedMonths` / `allowedDates` と同じ約束です)。JSX へインラインで書いた矢印関数は毎描画で同一性が変わり、選択肢ラベルの再計算を毎回起こします。モジュール直下の `const` か `useCallback` で固定してください。
208
+
209
+ **一部の (`unit`, `scope`) だけを担当する場合は、残りを `formatOptionText` へ転送します**。引数順がコールバックと同一なので逐語転送でき、担当外の書式を手で書き直す必要はありません。「`undefined` を返したら既定」という形は採っていません (代替値連鎖になるためです)。
210
+
211
+ ```ts
212
+ import { formatOptionText, type PeriodOptionFormatter } from "@aiquants/period-slider"
213
+
214
+ // 年の period 区分だけを自分で描き、残りは組み込みの段へそのまま渡す
215
+ const formatOption: PeriodOptionFormatter = (date, unit, scope) =>
216
+ unit === "year" && scope === "period" ? `${date.getFullYear()}年度` : formatOptionText(date, unit, scope, "ja-JP")
217
+
218
+ formatOption(new Date(2025, 3, 1), "year", "period") // "2025年度"
219
+ formatOption(new Date(2025, 3, 1), "month", "period") // "2025/04"
220
+ formatOption(new Date(2025, 3, 1), "month", "part") // "04月"
221
+ ```
222
+
156
223
  #### フック利用時の `locale`
157
224
 
158
225
  フック (`usePeriodSliderRange` 等) へ渡した `locale` は `sliderProps` へ転送されますが、`SelectorProps` は `locale` を含みません。スライダーとセレクタの書式を揃えるには、セレクタ側へも明示的に渡してください。
@@ -217,6 +284,98 @@ formatQuarterWithLocale(new Date(2025, 3, 1)) // "2025 Q1"
217
284
  formatQuarterWithLocale(new Date(2025, 3, 1), "ja-JP") // "2025年 Q1"
218
285
  ```
219
286
 
287
+ ##### 1 つのコールバックをレールと 3 セレクタへ渡す
288
+
289
+ `formatLabel` と `formatOption` は同じ `PeriodOptionFormatter` なので、**ページ全体で 1 つの関数値**を作り、レールにもセレクタにも同じものを渡せます。自分で描かない `scope: "part"` は `formatOptionText` へ逐語転送します。
290
+
291
+ ```tsx
292
+ import {
293
+ DateSelector,
294
+ MonthSelector,
295
+ PeriodSlider,
296
+ YearSelector,
297
+ formatOptionText,
298
+ resolveQuarter,
299
+ type PeriodOptionFormatter,
300
+ } from "@aiquants/period-slider"
301
+
302
+ const FISCAL_YEAR_START_MONTH = 3
303
+
304
+ // モジュール直下に置いて同一性を固定する (インラインの矢印関数は毎描画で別物になる)
305
+ const formatFiscalPeriod: PeriodOptionFormatter = (date, unit, scope) => {
306
+ // 分割セレクトの 3 部位は自分で描かず、組み込みの段へそのまま渡す
307
+ if (scope === "part") return formatOptionText(date, unit, scope, "ja-JP")
308
+ const { year, quarter } = resolveQuarter(date, FISCAL_YEAR_START_MONTH)
309
+ if (unit === "year") return `${year}年度`
310
+ if (unit === "month") return `${year}年度 第${quarter}四半期`
311
+ return `${year}年度 第${quarter}四半期 (${formatOptionText(date, "day", "period", "ja-JP")})`
312
+ }
313
+
314
+ formatFiscalPeriod(new Date(2026, 0, 1), "year", "period") // "2025年度"
315
+ formatFiscalPeriod(new Date(2026, 0, 1), "month", "period") // "2025年度 第4四半期"
316
+ formatFiscalPeriod(new Date(2025, 4, 15), "day", "period") // "2025年度 第1四半期 (2025/05/15)"
317
+ formatFiscalPeriod(new Date(2025, 4, 15), "month", "part") // "05月"
318
+ ```
319
+
320
+ ```tsx
321
+ <PeriodSlider
322
+ mode="point"
323
+ unit="month"
324
+ yearStartMonth={FISCAL_YEAR_START_MONTH}
325
+ minDate={new Date(2025, 3, 1)}
326
+ maxDate={new Date(2026, 2, 31)}
327
+ value={month}
328
+ formatLabel={formatFiscalPeriod}
329
+ onChangePoint={setMonth}
330
+ />
331
+
332
+ {/* 選択肢は "2026年度" / "2025年度" / "2024年度" */}
333
+ <YearSelector
334
+ value={month}
335
+ minYear={2024}
336
+ maxYear={2026}
337
+ yearStartMonth={FISCAL_YEAR_START_MONTH}
338
+ formatOption={formatFiscalPeriod}
339
+ onChange={setMonth}
340
+ />
341
+
342
+ {/* 選択肢は "2025年度 第2四半期" (2025-09 〜 2025-07) と "2025年度 第1四半期" (2025-06 〜 2025-04) */}
343
+ <MonthSelector
344
+ variant="dropdown"
345
+ value={month}
346
+ minDate={new Date(2025, 3, 1)}
347
+ maxDate={new Date(2025, 8, 30)}
348
+ formatOption={formatFiscalPeriod}
349
+ onChange={setMonth}
350
+ />
351
+
352
+ {/* 3 部位は "2025年" / "05月" / "15日" */}
353
+ <DateSelector
354
+ variant="split-dropdown"
355
+ value={day}
356
+ minDate={new Date(2025, 3, 1)}
357
+ maxDate={new Date(2025, 5, 30)}
358
+ formatOption={formatFiscalPeriod}
359
+ onChange={setDay}
360
+ />
361
+ ```
362
+
363
+ `formatAriaValueText` を省略すれば、読み上げにも同じ文字列が流れます (上の `PeriodSlider` は 2025-05 を選択中に `aria-valuetext="2025年度 第1四半期"` を持ちます)。`DateSelector variant="dropdown"` へ同じ関数を渡すと、行も操作要素も `2025年度 第1四半期 (2025/05/15)` になり、`data-value` は `2025-05-15` のままです。
364
+
365
+ > [!WARNING]
366
+ > **`unit="month"` の四半期ラベルは、3 つ並ぶ月が同じ文字列になります。** 上の `MonthSelector` は 2025-04 / 2025-05 / 2025-06 の 3 選択肢がすべて `2025年度 第1四半期` です (`<option value>` は `2025-04` / `2025-05` / `2025-06` のまま区別されるので、選択そのものは壊れません)。四半期を 1 行 1 件で選ばせたい場合は、四半期の開始月だけを `allowedMonths` へ渡してください。
367
+
368
+ ```tsx
369
+ // 各四半期の開始月だけを候補にすると、選択肢と表示が 1 対 1 になる
370
+ const quarterStarts = useMemo(
371
+ () => [0, 3, 6, 9].map((offset) => new Date(2025, FISCAL_YEAR_START_MONTH + offset, 1)),
372
+ [],
373
+ )
374
+
375
+ // 選択肢は "2025年度 第4四半期" (2026-01) / 第3 (2025-10) / 第2 (2025-07) / 第1 (2025-04) の 4 件
376
+ <MonthSelector variant="dropdown" value={month} allowedMonths={quarterStarts} formatOption={formatFiscalPeriod} onChange={setMonth} />
377
+ ```
378
+
220
379
  `PeriodQuarter` の各フィールド、`yearStartMonth` ごとの出力表、例外の契約は [公開ユーティリティ関数](#公開ユーティリティ関数) にまとめてあります。
221
380
 
222
381
  ### ゼロ・ボイラープレート React フック連携 (`usePeriodSliderRange`)
@@ -595,7 +754,7 @@ export function FiscalQuarterLabelExample() {
595
754
  | `hideConnectBar` | `boolean` | `false` | 範囲選択バー (ハイライト) を非表示にし、独立 2 点選択 UI として利用 |
596
755
  | `showTicks` | `boolean` | `false` | 離散モード時のトラック上の目盛線の表示有無 |
597
756
  | `showStepper` | `boolean` | `true` | ステッパーボタンの表示有無 (水平時は左右、垂直時は上下を指す矢印) |
598
- | `formatLabel` | `(date: Date) => string` | `undefined` | 日付ラベル・ツールチップのカスタム表示文字列生成関数。`locale` より優先される。ノギスでは `formatMacroLabel` / `formatMicroLabel` 双方の既定値でもあるため、ここへ四半期フォーマッタを渡すと**マクロ側にも同じ関数が流れ**、マクロラベルが常に Q1 になる。ノギスで四半期を出すなら `formatMicroLabel` にだけ渡す |
757
+ | `formatLabel` | `PeriodOptionFormatter` | `undefined` | 日付ラベル・ツールチップのカスタム表示文字列生成関数。`locale` より優先される。3 セレクタの `formatOption` と同じ型のため、同一の関数値を両方へ渡せる (引数は `(date, unit, scope)` で `scope` は常に `"period"`。`(date) => string` も従来どおり代入可能)。ノギスでは `formatMacroLabel` / `formatMicroLabel` 双方の既定値でもあるため、ここへ四半期フォーマッタを渡すと**マクロ側にも同じ関数が流れ**、マクロラベルが常に Q1 になる。ノギスで四半期を出すなら `formatMicroLabel` にだけ渡す |
599
758
  | `locale` | `string` | `undefined` | 組み込み日付表記のロケール (BCP 47 言語タグ)。未指定はロケール非依存の ISO 8601 (`2025` / `2025-01` / `2025-01-15`)、指定時は `Intl.DateTimeFormat` 書式。空文字列・不正タグ・非文字列は `RangeError` |
600
759
  | `disabled` | `boolean` | `false` | スライダーの無効化・非活性表示 |
601
760
  | `debounceMs` | `number` | `0` | 変更コールバック呼び出しのデバウンス時間 (ミリ秒)。`0` は即時発火 |
@@ -637,8 +796,8 @@ export function FiscalQuarterLabelExample() {
637
796
  | `microIsDiscrete` | `boolean` | `false` | ミクロ側の離散スナップ有効化フラグ。`false` の間は `microAllowedDates` が参照されない。`true` かつ現在のマクロ窓が候補を 1 つ以上含む間、ミクロレールは候補集合しか描かないため、位置・`aria-valuenow` / `aria-valuetext`・ラベル・**確定値**のすべてが最近傍候補へ解決される (ドラッグ・キーボード・ホイール・ステッパー・フックの収め込みで同一規則)。窓が候補を 1 つも含まない場合は窓内の連続値として振る舞う |
638
797
  | `macroAllowedDates` | `Date[]` | `allowedDates` | マクロ側の離散スナップ対象日付配列。`macroIsDiscrete={true}` との併用が必須 |
639
798
  | `microAllowedDates` | `Date[]` | `allowedDates` | ミクロ側の離散スナップ対象日付配列。`microIsDiscrete={true}` との併用が必須。候補はマクロ窓で切り出され、窓の外の日付へはキーボード・ポインターのいずれからも到達しない。窓内に候補が 1 件も残らない場合、ミクロレールは窓内の連続値として振る舞う |
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 とは独立に選べる |
799
+ | `formatMacroLabel` | `PeriodOptionFormatter` | `formatLabel` | マクロ側ラベル・ツールチップのカスタム表示文字列生成関数。引数はつまみ位置・`aria-valuenow` と同一の符号値から復元した `macroUnit` 正規化済み `Date` であり、`macroRange` の生の値ではない (`macroUnit="month"` なら常に月初、`"year"` なら常にその年の先頭月 1 日 (`yearStartMonth` が `0` なら元日)、`"day"` は暦日そのままで時刻が 0 時)。`macroUnit="year"` では引数が必ず年の先頭月であるため、ここへ四半期フォーマッタを渡すと表示は常に Q1 になる (四半期は月・日解像度のミクロ側へ載せる) |
800
+ | `formatMicroLabel` | `PeriodOptionFormatter` | `formatLabel` | ミクロ側ラベル・ツールチップのカスタム表示文字列生成関数。引数はつまみ位置と同一の `microUnit` 正規化済み `Date` (`microUnit="month"` なら常に月初)。四半期ラベルはこの `microUnit="month"` / `"day"` の側に載せる。`formatQuarterLabel` へ渡す `yearStartMonth` はその関数自身の引数であり、スライダーの `yearStartMonth` Props とは独立に選べる |
642
801
  | `vernierOrientation` | `"macro-top" \| "macro-bottom" \| "macro-left" \| "macro-right"` | 水平時 `"macro-top"` / `isVertical` 時 `"macro-left"` | ノギスのレール配置。水平時は上下 (`macro-top` / `macro-bottom`)、垂直時は左右 (`macro-left` / `macro-right`) を指定 |
643
802
  | `showVernierProjection` | `boolean` | `true` | マクロ窓からミクロ全幅へ広がる半透明台形プロジェクション光の表示有無 |
644
803
  | `showVernierTicks` | `boolean` | `true` | 目盛線の表示有無。マクロレールに 20% 間隔で 4 本、ミクロレールに 10% 間隔で 9 本を等間隔に描画する |
@@ -677,7 +836,7 @@ export function FiscalQuarterLabelExample() {
677
836
  | `macroUpperAriaLabel` | `string` | `"Macro range end"` | マクロ上限つまみのアクセシブル名 (`mode="vernier"` のみ) |
678
837
  | `decreaseAriaLabel` | `string` | `"Decrease"` | 値を `minDate` 方向へ 1 単位動かすステッパーボタンのアクセシブル名 (水平時は左端の左向き矢印、垂直時は下端の下向き矢印) |
679
838
  | `increaseAriaLabel` | `string` | `"Increase"` | 値を `maxDate` 方向へ 1 単位動かすステッパーボタンのアクセシブル名 (水平時は右端の右向き矢印、垂直時は上端の上向き矢印) |
680
- | `formatAriaValueText` | `(date: Date, unit: PeriodSliderUnit) => string` | `undefined` | `aria-valuetext` の読み上げ文字列生成関数。未指定時は可視ラベルと同一の文字列 (ISO 8601、`locale` 指定時は `Intl.DateTimeFormat` 書式)。ノギスでは可視ラベルと同じく、マクロ側に `macroUnit` 正規化済み、ミクロ側に `microUnit` 正規化済みの `Date` が渡される。**指定すると、`aria-valuetext` を組み立てる 6 か所すべてで可視ラベルの経路 (`formatScreenReaderLabel`) を短絡します**。四半期ラベルを表示しているなら、ここへ渡す文字列も**同じ `resolveQuarter` 呼び出し**から組み立ててください (省略すれば可視ラベルと一字一句同じ文字列が読み上げられます) |
839
+ | `formatAriaValueText` | `PeriodOptionFormatter` | `undefined` | `aria-valuetext` の読み上げ文字列生成関数。未指定時は可視ラベルと同一の文字列 (ISO 8601、`locale` 指定時は `Intl.DateTimeFormat` 書式)。ノギスでは可視ラベルと同じく、マクロ側に `macroUnit` 正規化済み、ミクロ側に `microUnit` 正規化済みの `Date` が渡される。**指定すると、`aria-valuetext` を組み立てる 6 か所すべてで可視ラベルの経路 (`formatScreenReaderLabel`) を短絡します**。四半期ラベルを表示しているなら、ここへ渡す文字列も**同じ `resolveQuarter` 呼び出し**から組み立ててください (省略すれば可視ラベルと一字一句同じ文字列が読み上げられます) |
681
840
 
682
841
  ステッパーの 2 つの名称は配置ではなく値への作用で定義されています。同じボタンが水平レイアウトでは左、垂直レイアウトでは下に立つため、位置で命名すると意味が反転するからです。
683
842
 
@@ -721,6 +880,31 @@ DOM 要素の特定は CSS クラス名ではなく `data-*` 属性で行いま
721
880
 
722
881
  `PeriodSlider` が内部で使う純粋関数のうち、次のものはパッケージのルート (`@aiquants/period-slider`) から公開されています。React に依存しないため、レールの外 (取得期間の算出、集計キーの生成など) でもそのまま使えます。
723
882
 
883
+ #### 表示テキスト — `formatOptionText` / `PeriodOptionFormatter` / `PeriodOptionScope`
884
+
885
+ ```ts
886
+ export type PeriodOptionScope = "period" | "part"
887
+ export type PeriodOptionFormatter = (date: Date, unit: PeriodSliderUnit, scope: PeriodOptionScope) => string
888
+
889
+ export declare const formatOptionText: (date: Date, unit: PeriodSliderUnit, scope: PeriodOptionScope, locale?: string) => string
890
+ ```
891
+
892
+ - `PeriodOptionFormatter` は、4 つのスライダー Props (`formatLabel` / `formatMacroLabel` / `formatMicroLabel` / `formatAriaValueText`) と 3 セレクタの `formatOption` に**共通の 1 つの型**です。面ごとの契約は [1 つのフォーマッタで全テキスト面を決める](#1-つのフォーマッタで全テキスト面を決める-formatoption) にまとめてあります。
893
+ - **引数を減らした関数は今まで通り渡せます**。`(date: Date) => string` も `(date: Date, unit: PeriodSliderUnit) => string` も代入可能で、逆向き (3 引数の関数を 1 引数のスロットへ) だけがコンパイルエラーになります。`formatQuarterLabel` は `(Date, number) => string` で第 2 引数が単位ではなく `yearStartMonth` のため、`formatOption` へ**直接は渡せません** (型が拒否します)。四半期は上のレシピのように `resolveQuarter` から組み立ててください。
894
+ - `PeriodOptionScope` は `"period"` (その操作要素の値そのもの) と `"part"` (`variant="split-dropdown"` が 3 つ並べる部位の 1 つ) の 2 値です。組み込みの段がこの 2 つを別の Intl オプション集合で描き分けているため、`unit` だけでは同じ `"month"` が「年月全体」と「月の部位」のどちらを指すのか決まりません。
895
+ - `formatOptionText` は**組み込みの 2 段そのもの**です (`locale` 指定時は `Intl.DateTimeFormat`、未指定時はロケール非依存の ISO 8601)。第 1 段を担当しない (`unit`, `scope`) の組は、この関数へそのまま転送してください。引数順がコールバックと同一なので逐語転送できます。
896
+ - **「`undefined` を返したら既定」という形は採っていません**。それは代替値連鎖であり、本パッケージが排している形です。返り値は常に文字列で、**空文字列も合法**です (無効な日付に対する `formatLabel` の仕様値と同じ)。
897
+ - `date` が未指定・Invalid Date のときは `""` を返します (`formatLabel` と同じ約束)。
898
+ - `unit` が `"year"` / `"month"` / `"day"` 以外、`scope` が `"period"` / `"part"` 以外の場合は `RangeError` を送出し、メッセージは関数自身を名指しします (`formatOptionText: scope must be "period" or "part" (received: label)`)。フォーマッタ Props は型検査を受けますが、この関数は公開の入口であり JavaScript からも引数が届くためです。
899
+
900
+ `formatOptionText(date, unit, scope, locale)` の出力 (`date` は `2025-04-15`):
901
+
902
+ | `unit` | `scope: "period"` (`locale` 未指定) | `scope: "period"` (`"ja-JP"`) | `scope: "part"` (`locale` 未指定) | `scope: "part"` (`"ja-JP"`) |
903
+ | :--- | :--- | :--- | :--- | :--- |
904
+ | `"year"` | `2025` | `2025年` | `2025` | `2025年` |
905
+ | `"month"` | `2025-04` | `2025/04` | `04` | `04月` |
906
+ | `"day"` | `2025-04-15` | `2025/04/15` | `15` | `15日` |
907
+
724
908
  #### 四半期 — `resolveQuarter` / `formatQuarterLabel`
725
909
 
726
910
  ```ts
@@ -1009,7 +1193,7 @@ export function SelectorsExample() {
1009
1193
 
1010
1194
  #### `YearSelector` Props
1011
1195
 
1012
- 年を 1 年刻みで選択するコンポーネント。選択肢は解決後の上限年から下限年までの降順で、境界を跨いで広がることはありません。選択肢のテキストは 4 桁ゼロ埋めの年 (`2024`) で、`locale` 指定時は `Intl.DateTimeFormat` 書式 (`ja-JP` なら `2024年`)。`<option value>` は常に生の数値です。
1196
+ 年を 1 年刻みで選択するコンポーネント。`MonthSelector` / `DateSelector` と違って形態は 1 つだけで、`variant` を持ちません (常にドロップダウン + ステッパー)。選択肢は解決後の上限年から下限年までの降順で、境界を跨いで広がることはありません。選択肢のテキストは 4 桁ゼロ埋めの年 (`2024`) で、`locale` 指定時は `Intl.DateTimeFormat` 書式 (`ja-JP` なら `2024年`)。`<option value>` は常に生の数値です。
1013
1197
 
1014
1198
  | プロパティ | 型 | 既定値 | 説明 |
1015
1199
  | :--- | :--- | :--- | :--- |
@@ -1028,6 +1212,7 @@ export function SelectorsExample() {
1028
1212
  | `nextYearAriaLabel` | `string` | `"Next year"` | 翌年ボタンのアクセシブル名 |
1029
1213
  | `selectAriaLabel` | `string` | `"Year"` | 年セレクトのアクセシブル名 |
1030
1214
  | `locale` | `string` | `undefined` | 選択肢テキストのロケール (BCP 47 言語タグ)。未指定は 4 桁ゼロ埋めの年、指定時は `Intl.DateTimeFormat` 書式。空文字列・不正タグ・非文字列は `RangeError` |
1215
+ | `formatOption` | `PeriodOptionFormatter` | `undefined` | 選択肢 (境界外の保持年を含む) と畳んだ表示のテキスト生成関数 (`locale` より優先)。`(date, unit, scope) => string` で、`unit` は常に `"year"`、`scope` は常に `"period"`、`date` はその年の先頭月 1 日 (`yearStartMonth` 準拠)。このコンポーネントは単一形態でプレースホルダを持たず、境界外の保持年も書式化された実選択肢 (`disabled`) として並ぶ。返り値は機械可読値 (`<option value>` は常に生の数値)・`aria-label`・`onChange` の引数には届かない。参照比較で再描画を判定するため、利用側でメモ化する |
1031
1216
  | `unit` | — | — | **このコンポーネントが宣言していない名前です**。フックの `SelectorProps` をそのままスプレッドできるよう、受け取っても読まれず捨てられます (コンポーネントは必要な Props だけを名前で取り出すため、DOM へも届きません)。型にも宣言が無いので、JSX へ直接書くとコンパイルエラーになります (スプレッドは余剰プロパティ検査を受けないため通ります) |
1032
1217
  | `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
1218
 
@@ -1035,6 +1220,8 @@ export function SelectorsExample() {
1035
1220
 
1036
1221
  下限 (`minYear` または `minDate`) と上限 (`maxYear` または `maxDate`) は共に必須です。境界外の年を保持している間は、境界へ丸めず・`RangeError` も送出せず、その年を選択肢へ 1 件加えてそのまま表示します。ステッパーは移動先の年が境界内にある場合だけ有効です (境界の 1 つ外側では戻る側だけが有効、それより外では両方とも使用不可 (`aria-disabled="true"`、フォーカスは保持))。境界外の年が `onChange` へ渡ることはありません。
1037
1222
 
1223
+ DOM 契約: 保持年が境界外の間、ルート要素に `data-out-of-range="true"` が付与され、押し込まれた境界外の `<option>` は `disabled` になります (押せる範囲と発行できる範囲を一致させるためで、`emit` は境界外の年に対して `RangeError` を送出します)。`select.value` は**保持年のまま**で、`MonthSelector` / `DateSelector` のように `""` にはなりません — 選択中の年を畳んだ表示に出し続けるためです。
1224
+
1038
1225
  #### `MonthSelector` Props
1039
1226
 
1040
1227
  年月を 1 ヶ月刻みで選択するコンポーネント。
@@ -1059,6 +1246,7 @@ export function SelectorsExample() {
1059
1246
  | `nextMonthAriaLabel` | `string` | `"Next month"` | 翌月ボタンのアクセシブル名 |
1060
1247
  | `selectAriaLabel` | `string` | `"Month"` | 年月セレクトのアクセシブル名 |
1061
1248
  | `locale` | `string` | `undefined` | 選択肢テキストのロケール (BCP 47 言語タグ)。未指定は ISO 8601 の `YYYY-MM`、指定時は `Intl.DateTimeFormat` 書式。`<input type="month">` および `<option value>` は常に `yyyy-MM`。空文字列・不正タグ・非文字列は `RangeError` |
1249
+ | `formatOption` | `PeriodOptionFormatter` | `undefined` | 選択肢・プレースホルダ・畳んだ表示のテキスト生成関数 (`locale` より優先)。`(date, unit, scope) => string` で、`unit` と `scope` はコンポーネントが与える。ネイティブ入力を使う `variant="date"` では履行できないため**呼び出しも行わない**。返り値は機械可読値・`aria-label`・`onChange` の引数には届かない。参照比較で再描画を判定するため、利用側でメモ化する |
1062
1250
  | `unit` | — | — | **このコンポーネントが宣言していない名前です**。フックの `SelectorProps` をそのままスプレッドできるよう、受け取っても読まれず捨てられます (コンポーネントは必要な Props だけを名前で取り出すため、DOM へも届きません)。型にも宣言が無いので、JSX へ直接書くとコンパイルエラーになります (スプレッドは余剰プロパティ検査を受けないため通ります) |
1063
1251
  | `yearStartMonth` | — | — | `unit` と同じく、このコンポーネントが宣言していない名前です。年の開始月を読むのは `YearSelector` だけで、月・日の格子には動かすべき年の境界がありません |
1064
1252
 
@@ -1106,9 +1294,7 @@ const allowedMonths = useMemo(() => baseMonths.map((yyyymm) => new Date(Math.tru
1106
1294
  | `monthAriaLabel` | `string` | `"Month"` | 月セレクトのアクセシブル名 (`variant="split-dropdown"` のみ) |
1107
1295
  | `dayAriaLabel` | `string` | `"Day"` | 日セレクトのアクセシブル名 (`variant="split-dropdown"` のみ) |
1108
1296
  | `locale` | `string` | `undefined` | 選択肢テキストのロケール (BCP 47 言語タグ)。未指定は ISO 8601 (`variant="dropdown"` は `YYYY-MM-DD`、`variant="split-dropdown"` は `2024` / `01` / `15`)、指定時は `Intl.DateTimeFormat` 書式。`<input type="date">` の値・コンボボックスの `data-value`・`<option value>` は常に `yyyy-MM-dd` または生の数値。空文字列・不正タグ・非文字列は `RangeError` |
1109
- | `formatYearOption` | `(year: number) => string` | `undefined` | `variant="split-dropdown"` の年選択肢テキスト生成関数 (`locale` より優先) |
1110
- | `formatMonthOption` | `(month: number) => string` | `undefined` | `variant="split-dropdown"` の月選択肢テキスト生成関数。引数は 1〜12 (`locale` より優先) |
1111
- | `formatDayOption` | `(day: number) => string` | `undefined` | `variant="split-dropdown"` の日選択肢テキスト生成関数。引数は 1〜31 (`locale` より優先) |
1297
+ | `formatOption` | `PeriodOptionFormatter` | `undefined` | 選択肢・プレースホルダ・畳んだ表示のテキスト生成関数 (`locale` より優先)。`(date, unit, scope) => string` で、`unit` と `scope` はコンポーネントが与える。ネイティブ入力を使う `variant="date"` では履行できないため**呼び出しも行わない**。返り値は機械可読値・`aria-label`・`onChange` の引数には届かない。参照比較で再描画を判定するため、利用側でメモ化する |
1112
1298
  | `unit` | — | — | **このコンポーネントが宣言していない名前です**。フックの `SelectorProps` をそのままスプレッドできるよう、受け取っても読まれず捨てられます (コンポーネントは必要な Props だけを名前で取り出すため、DOM へも届きません)。型にも宣言が無いので、JSX へ直接書くとコンパイルエラーになります (スプレッドは余剰プロパティ検査を受けないため通ります) |
1113
1299
  | `yearStartMonth` | — | — | `unit` と同じく、このコンポーネントが宣言していない名前です。年の開始月を読むのは `YearSelector` だけで、月・日の格子には動かすべき年の境界がありません |
1114
1300
 
@@ -1116,24 +1302,59 @@ const allowedMonths = useMemo(() => baseMonths.map((yyyymm) => new Date(Math.tru
1116
1302
 
1117
1303
  - `value` (制御) と `initialDate` (非制御) はいずれか一方が必須です。共に省略した場合は `RangeError` を送出し、選択日付を壁時計時刻から推定しません。
1118
1304
  - `variant="dropdown"`: `allowedDates` を指定しない場合、下限と上限の双方が必須です。選択肢は `minDate` 〜 `maxDate` の全日 (降順) ですが、配列としては実体化しません。件数は境界から算出し、行の日付・テキストは描画時に導出し、DOM に存在するのはポップアップの可視行だけです。境界を動かす費用は連続範囲で O(1)、`allowedDates` 指定時は二分探索の O(log n) で、100 年分 (36,525 日) の定義域でも 1 か月分と同じ費用で動きます。ポインタ移動ごとに境界を動かすホスト (ノギスの連動セレクタなど) でも、この変種を日単位のまま使えます。
1119
- - `variant="split-dropdown"`: 下限と上限の双方が必須で、`allowedDates` との併用は `RangeError` になります。存在しない日付になる年・月へ切り替えた場合 (1 月 31 日を選択中に 2 月へ変更等)、月末日へ丸めず選択を破棄し、`onChange` を発火しません。選択肢のテキストは既定でゼロ埋めの数値 (`2024` / `01` / `15`) で、`locale` または `formatYearOption` / `formatMonthOption` / `formatDayOption` で変更できます。
1305
+ - `variant="split-dropdown"`: 下限と上限の双方が必須で、`allowedDates` との併用は `RangeError` になります。存在しない日付になる年・月へ切り替えた場合 (1 月 31 日を選択中に 2 月へ変更等)、月末日へ丸めず選択を破棄し、`onChange` を発火しません。そうした選択肢 — 保持中の他 2 部位と組んで実在しない日付になるもの、および境界の外へ出るもの — は、年・月・日の 3 つの `<select>` すべてで `disabled` として描かれ、押せる範囲と発行できる範囲が一致します (1 月 31 日を保持していれば月の `2` / `4` / `6` / `9` / `11` が `disabled` になり、保持値そのものが境界の外にある間は、その保持値と組んで境界内へ収まる選択肢を 1 つも持たないセレクトの全選択肢が `disabled` になります)。選択肢のテキストは既定でゼロ埋めの数値 (`2024` / `01` / `15`) で、`locale` または `formatOption` (`scope: "part"`) で変更できます。基準日は**その `<select>` の値だけ**から決まります (年は 1 月 1 日、月は当月 1 日、日は保持中の年月とその日)。
1306
+
1307
+ > **既知の制約 (非グレゴリオ暦)**: グレゴリオ暦の年・月を、年や月の境界が異なる暦 (和暦・ペルシア暦など) で描く以上、「その選択肢が確定する日付の呼び名」と「同じ `<select>` の選択肢どうしが区別できること」は同時には満たせません。本パッケージは**区別できること**を採ります。そのため `ja-JP-u-ca-japanese` では 2019 年の選択肢は常に 平成31年 (1 月 1 日の元号) で、5 月を保持したまま押すと確定するのは令和元年の日付です。逆に保持日を基準日へ混ぜると、`fa-IR` では 2020 年と 2021 年の選択肢が同じペルシア年 (`۱۳۹۹`) になります (実測)。確定日の呼び名が要る利用側は `formatOption` で自分の基準日を組んでください。
1308
+
1120
1309
  - `variant="date"`: 境界は任意です。指定した場合は `<input>` の `min` / `max` 属性へ反映されます。
1121
1310
  - ステッパーは離散指定時に隣接する選択可能日へ移動し、集合の端では使用不可 (`aria-disabled="true"`) になります。
1122
1311
  - 選択可能集合外の日付は丸められず破棄され、`onChange` は発火しません。
1123
1312
 
1124
- DOM 契約: ルート要素は `data-variant="date|dropdown|split-dropdown"` を持ち、現在値が選択可能集合の外にある場合は `data-out-of-range="true"` が付与されます。`variant="split-dropdown"` ではさらに、各 `<select>` の先頭に現在値を表示する選択不可のプレースホルダ `<option value="">` が描画され (このとき `select.value === ""`)、`variant="date"` では `<input type="date">` が保持値をそのまま表示します。
1313
+ DOM 契約: ルート要素は `data-variant="date|dropdown|split-dropdown"` を持ち、現在値が選択可能集合の外にある場合は `data-out-of-range="true"` が付与されます。`variant="split-dropdown"` では、**保持値がその部位自身の選択肢一覧に無い `<select>` だけ**が、先頭に現在値を表示する選択不可のプレースホルダ `<option value="">` を描きます (そのセレクトの `select.value === ""`)。一覧に既に居る部位はプレースホルダを持たず `select.value` が実値を指します — 同じ文字・同じ無効状態の行が 1 つのセレクトに 2 つ並ぶと、利用者にも `formatOption` にも見分けがつかないためです。`variant="date"` では `<input type="date">` が保持値をそのまま表示します。
1125
1314
 
1126
1315
  `variant="dropdown"` の DOM 契約:
1127
1316
 
1128
- - 操作要素は `<input type="text" readonly role="combobox">` で、`value` には人間が読むテキスト (`locale` 書式)、`data-value` には常に `yyyy-MM-dd` の機械可読値を持ちます。`aria-expanded` / `aria-haspopup="listbox"` / `aria-controls` (開いている間) / `aria-activedescendant` (アクティブ行が描画されている間) を持ち、`data-testid="period-slider-date-combobox"` で引けます。集合外の保持値は行にならず、操作要素の表示テキストとしてだけ現れます。
1317
+ - 操作要素は `<input type="text" readonly role="combobox">` で、`value` には人間が読むテキスト (`formatOption` 指定時はその返り値、未指定なら `locale` 書式)、`data-value` には常に `yyyy-MM-dd` の機械可読値を持ちます。この `value` は選択中の行のテキストと必ず一致します (同じ関数値へ同じ形の引数を渡すため)。`aria-expanded` / `aria-haspopup="listbox"` / `aria-controls` (開いている間) / `aria-activedescendant` (アクティブ行が描画されている間) を持ち、`data-testid="period-slider-date-combobox"` で引けます。集合外の保持値は行にならず、操作要素の表示テキストとしてだけ現れます。
1129
1318
  - ポップアップは `document.body` へポータルされ (`data-testid="period-slider-date-popup"`)、開いた時点の操作要素の位置から解決した配色モードを `data-color-mode="light|dark"` として持ち、操作要素の下に開き、余地が無ければ上へ反転して視野内へ収まります。中の `role="listbox"` (アクセシブル名は `selectAriaLabel`) が `role="option"` の行を持ち、各行は `aria-selected` / `aria-posinset` / `aria-setsize` (集合全体の件数) / `data-active` (キーボードの現在位置) を持ち、`data-testid="period-slider-date-option"` で引けます。DOM に存在する行は可視窓の分だけで、集合全体の件数は `aria-setsize` から読みます。
1130
- - キーボード: `ArrowDown` / `ArrowUp` (閉じていれば開く、開いていれば 1 行移動)、`Home` / `End` (先頭 = 最新日 / 末尾 = 最古日)、`PageDown` / `PageUp` (1 窓 = 7 行)、`Enter` (閉じていれば開く、開いていればアクティブ行を確定)、`Escape` (閉じる・発火しない)、`Tab` (閉じる)、数字と `-` / `/` / `.` (先頭一致入力。`yyyy` / `yyyyMM` / `yyyyMMdd` として解釈し、走査せずに当該日へ飛ぶ)。行の押下でも DOM フォーカスは操作要素から離れません。
1319
+ - ポップアップには `role="listbox"` のほかに `@aiquants/virtualscroll` のスクロールバーが同居します (`role="scrollbar"`、つまみの `role="slider"`、そして `aria-label="Scroll up"` / `"Scroll down"` を持つ矢印ボタン 2 つ)。矢印ボタンは常に `disabled` でタブ順にもキーボード操作にも現れませんが、アクセシビリティツリーには残り、**そのアクセシブル名は固定の英語で本パッケージからは翻訳できません**。ポップアップに絞った `getByRole("button")` はこの 2 つに当たるため、行は `role="option"` か `data-testid` で引いてください。
1320
+ - キーボード: `ArrowDown` / `ArrowUp` (閉じていれば開く、開いていれば 1 行移動)、`Home` / `End` (先頭 = 最新日 / 末尾 = 最古日)、`PageDown` / `PageUp` (1 窓 = 7 行)、`Enter` (閉じていれば開く、開いていればアクティブ行を確定)、`Escape` (閉じる・発火しない)、`Tab` (閉じる)、数字と `-` / `/` / `.` (先頭一致入力。**表示書式に関わらず**先発グレゴリオ暦の `yyyy` / `yyyyMM` / `yyyyMMdd` として解釈し、走査せずに当該日へ飛ぶ。`formatOption` が非数字のテキストを返していても変わらない)。行の押下でも DOM フォーカスは操作要素から離れません。
1131
1321
  - 閉じる契機: 行の確定、`Escape`、`Tab`、操作要素からのフォーカス喪失、ポップアップ外の `pointerdown`。
1132
1322
  - ポップアップは `.period-slider` の外に立つため、`colorScheme` の変数 (`--aqps-*`) は届きません。選択中の行のアクセント色はパッケージ既定の色です。重なり順だけは `--aqps-z-date-popup` (既定 60) で差し替えられます。
1133
1323
  - ダークモードは `.dark` の位置に依存しません。ポップアップの祖先 (`document.body` の側) に `.dark` が無くても、**操作要素自身の位置**で解決したモードを `data-color-mode` として運ぶため、`.dark` を部分木へ限定したホストでも暗色で開きます。
1134
1324
 
1135
1325
  `<select>` を前提にしていたテストの移行: `select.value` → `combobox.getAttribute("data-value")`、`select.options` を数える → 開いてから `aria-setsize` を読む (`renderedRows.length` は可視窓の分だけ)、`selectOption(value)` → 開いて行を押すか、ISO の数字を打って `Enter`。Playwright なら `getByRole("combobox", { name: "Date" })` はそのまま解決します (`toHaveValue` は `locale` 書式のテキストと比較されるので、ISO は `toHaveAttribute("data-value", …)` で読みます)。
1136
1326
 
1327
+ ### 0.12 から 0.13 への移行 (`formatOption` への集約)
1328
+
1329
+ `DateSelector` の `formatYearOption` / `formatMonthOption` / `formatDayOption` は**削除されました**。別名も互換経路も残していません。3 セレクタ共通の `formatOption` 1 つへ移してください。
1330
+
1331
+ | 0.12 まで | 0.13 から |
1332
+ | :--- | :--- |
1333
+ | `formatYearOption={(year) => …}` | `formatOption` の `unit === "year" && scope === "part"` の枝 |
1334
+ | `formatMonthOption={(month) => …}` | 同じ関数の `unit === "month" && scope === "part"` の枝 |
1335
+ | `formatDayOption={(day) => …}` | 同じ関数の `unit === "day" && scope === "part"` の枝 |
1336
+
1337
+ 旧 Props が受け取っていたのは数値 1 つだけで、**その 4 月がどの年の 4 月なのかを知る術がありませんでした**。`formatOption` はその選択肢が確定する日付そのものを受け取るため、年度・四半期・和暦を引数だけから導けます。担当しない組は `formatOptionText` へ転送します。
1338
+
1339
+ ```tsx
1340
+ // 0.12
1341
+ <DateSelector variant="split-dropdown" locale="ja-JP" formatMonthOption={(month) => `${month}月`} {...rest} />
1342
+
1343
+ // 0.13 — 担当しない組は formatOptionText へ転送し、locale は Props ではなく第 4 引数で渡す
1344
+ const formatOption: PeriodOptionFormatter = (date, unit, scope) =>
1345
+ unit === "month" && scope === "part" ? `${date.getMonth() + 1}月` : formatOptionText(date, unit, scope, "ja-JP")
1346
+
1347
+ // formatOption(new Date(2025, 3, 15), "month", "part") === "4月"
1348
+ // formatOption(new Date(2025, 3, 15), "day", "part") === "15日" (組み込みの段へ委譲。第 4 引数を省くと "15")
1349
+ <DateSelector variant="split-dropdown" formatOption={formatOption} {...rest} />
1350
+ ```
1351
+
1352
+ **`locale` を指定していたホストは、同じタグを第 4 引数へ渡してください**。`formatOption` は `locale` より上の段なので、フォーマッタを渡した時点で Props の `locale` はどの表示テキストにも届かなくなります (残しても害はありませんが、表示は決めません)。転送時に第 4 引数を省くと、自分で描かない組だけが Intl の段からロケール非依存の ISO 8601 の段へ落ちます — 上の例では年が `2025年` → `2025`、日が `15日` → `15` となり、自分で描いた月だけが変わらないため、3 列のうち 2 列が黙って言語を変えます。`locale` を指定していなかったホストは、第 4 引数も省いたままで挙動が変わりません。
1353
+
1354
+ スライダー側の `formatLabel` / `formatMacroLabel` / `formatMicroLabel` / `formatAriaValueText` は型が `PeriodOptionFormatter` へ広がっただけで、ほとんどの呼び出し側は**変更不要**です (`(date) => string` も `(date, unit) => string` もそのまま代入できます)。例外は**第 2 引数が任意でありながら `PeriodSliderUnit` を受けられない形**で、`(date: Date, index?: number) => string` — `dates.map(formatDate)` と共用するために書かれがちな形 — は 1 引数型だった 0.12 では通っていたものが型エラーになります (`Type '(date: Date, index?: number) => string' is not assignable to type 'PeriodOptionFormatter'`)。第 2 引数を `PeriodSliderUnit` を受けられる形にするか、`map` へは `(date) => formatDate(date)` を渡してください。
1355
+
1356
+ `YearSelector` には DOM 契約が 2 つ加わりました。保持年が境界外のときルート要素が `data-out-of-range="true"` を持ち、押し込まれた境界外の選択肢が `disabled` になります (`select.value` は保持年のままで、従来どおりです)。`MonthSelector` / `DateSelector` が既に持っていた契約へ揃えたものなので、`data-out-of-range` を読む既存のテストは 3 セレクタで同じ形になります。
1357
+
1137
1358
  ### React フック
1138
1359
 
1139
1360
  4 つのフックはいずれもステート、更新関数、および `PeriodSlider` / セレクタへそのままスプレッドできる Props を返します。境界・初期値は必須で、欠落・Invalid Date・逆転はすべて `RangeError` です。ノギスは選択形態ごとに 1 つずつ用意されており、`useVernierSliderRange` がミクロ期間、`useVernierSliderPoint` がミクロ時点を受け持ちます。
@@ -1153,7 +1374,11 @@ DOM 契約: ルート要素は `data-variant="date|dropdown|split-dropdown"` を
1153
1374
  | `unit` | `PeriodSliderUnit` | セレクタの時間解像度単位。3 セレクタのいずれも宣言していない名前のため、スプレッドされても読まれません |
1154
1375
  | `yearStartMonth` | `number` | 1 年が始まる暦月 (0 始まり)。読むのは `YearSelector` だけです。型としては任意 (`yearStartMonth?: number`) ですが、4 つのフックは常に解決済みの値を載せます |
1155
1376
 
1156
- `SelectorProps` は上記 6 つのみで、`locale` やアクセシブル名 Props は含みません。フックへ渡した `locale` は `sliderProps` にのみ転送されるため、セレクタの書式を揃える場合は `<MonthSelector {...startSelectorProps} locale="ja-JP" />` のように明示的に渡してください。
1377
+ `SelectorProps` は上記 6 つのみで、`locale`・`formatOption`・アクセシブル名 Props は含みません。表示に関する Props を 1 つも運ばない設計で、状態管理フックへ表示言語や書式を持ち込まないためです。フックへ渡した `locale` は `sliderProps` にのみ転送されるため、レールとセレクタの書式を揃える場合は、スプレッドの隣へ明示的に渡してください。
1378
+
1379
+ ```tsx
1380
+ <MonthSelector {...startSelectorProps} locale="ja-JP" formatOption={formatFiscalPeriod} />
1381
+ ```
1157
1382
 
1158
1383
  #### `usePeriodSliderRange(options)`
1159
1384