@aiquants/period-slider 0.12.0 → 0.14.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/README.md CHANGED
@@ -11,7 +11,7 @@
11
11
 
12
12
  必須の入力 (定義域境界・初期値) が欠落または不正な場合、本パッケージは既定値や壁時計時刻で代替せず、すべて `RangeError` で即座に失敗します。詳細は [実行時バリデーション](#実行時バリデーション-fail-fast) を参照してください。
13
13
 
14
- 組み込みの表示文字列はロケール中立です。アクセシブル名の既定値はすべて英語 (`"Range start"` 等)、日付ラベル・選択肢テキストの既定値はロケール非依存の ISO 8601 表記 (`2025` / `2025-01` / `2025-01-15`) で、`locale` (BCP 47 言語タグ) を渡した時のみ `Intl.DateTimeFormat` 書式へ切り替わります。詳細は [ロケールと表示書式](#ロケールと表示書式-locale) を参照してください。
14
+ 地域化は独立した 2 つの軸を持ちます。**UI クローム言語** (`locale`: `"en"` [既定] / `"ja"`) はつまみ・ステッパー・セレクト・ポップアップのアクセシブル名を凍結カタログから選び、`labels` でキー単位に上書きできます ([Localization](#localization-ui-クローム言語-locale-と-labels))。**日付テキスト** の既定値はロケール非依存の ISO 8601 表記 (`2025` / `2025-01` / `2025-01-15`) で、`formatLocale` (BCP 47 言語タグ) を渡した時のみ `Intl.DateTimeFormat` 書式へ切り替わります ([日付の表示書式](#日付の表示書式-formatlocale))。一方の軸から他方を導出することはありません。
15
15
 
16
16
  ## 特徴
17
17
 
@@ -36,7 +36,7 @@
36
36
  - `autoSlantLabels`: 2 つのラベルが近接した際に Smootherstep 補間により 0° 〜 90° に滑らかに自動傾斜し、テキストの重なりを数学的に完全防止。回転時もラベル下端がトラック中心から常に 10px (つまみ上端から 2px) の統一された高さを維持。角度は 2 つの値が一致する位置まで連続で、その位置で 90° に達します。
37
37
  - 傾斜は Range の 1 対と、ノギスのマクロ対・ミクロ対の計 3 組へ**対ごとに独立して**適用されます (対ごとに比率も単位もラベル幅も違うため、計算を共有しません)。マクロ対とミクロ対で角度が異なるのは正常です。
38
38
  - 垂直レイアウト (`isVertical={true}`、垂直ノギスを含む) では傾斜しません。傾斜幾何が X 軸方向にしか分離しないためで、垂直向けの衝突回避は未整備の保留領域です。
39
- - 衝突判定はラベルの実測幅 (`ResizeObserver` が返すボーダーボックス幅) のみを用います。単位や書式から推定した定数を使わないため、`locale`・`formatLabel`・ホストのフォントを変えても判定はずれません。実測値が得られるまでラベルは傾斜せず直立します。
39
+ - 衝突判定はラベルの実測幅 (`ResizeObserver` が返すボーダーボックス幅) のみを用います。単位や書式から推定した定数を使わないため、`formatLocale`・`formatLabel`・ホストのフォントを変えても判定はずれません。実測値が得られるまでラベルは傾斜せず直立します。
40
40
  - 2 つのつまみが同じ値に重なったときは、同一文字列のラベルを 2 枚並べず 1 枚へ畳みます。冗長な側のラベルには `data-duplicate="true"` が付いて `visibility: hidden` になり (要素は残るため実測は継続)、残った 1 枚は 90° に傾いたままつまみの中心に立ちます (畳んでも角度は変えず、離す相手が居なくなった水平方向の押し退けだけを 0 にします)。畳まれたかどうかは傾斜の可否を動かしません。値が一致していても、上記のとおり実測が揃うまで・`autoSlantLabels={false}`・垂直レイアウトでは直立のままです。同じ機構がノギスのマクロ対・ミクロ対にも適用され (判定は各対の符号化値の厳密一致)、可視ラベルは掴んだ・打鍵した・`Tab` で到達したつまみへ追従します。
41
41
  - トラック上をホバーしたときに出る追従ラベル (ポインターオーバーレイ) も、指している値がつまみの確定値と一致する間は同じ機構で隠します。つまみのラベルと一字一句同じ文字列が 4px ずれて二重に描かれるのを防ぐためで、判定はラベル併合と同じ符号化値の厳密一致です。ポインター位置そのものを示す点とガイドは表示したままです。
42
42
  - 操作中 (ドラッグ中)、直近にクリック・キー操作・フォーカスしたラベル・つまみを前面 (`z-index`) に強調表示。併合時に見えるのはこの前面側のラベルです。
@@ -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
+ - **独立した 2 軸の地域化**: アクセシブル名は `locale` (`"en"` [既定] / `"ja"`) が選ぶ凍結カタログ (`PERIOD_SLIDER_LABEL_CATALOGS`) と `labels` の上書きから決まり、`DateSelector variant="dropdown"` のポップアップにある `@aiquants/virtualscroll` のスクロールクロームも同じ言語で描かれます。日付表記の既定値は ISO 8601 で、`formatLocale` を渡せば `Intl.DateTimeFormat` 書式、フォーマッタ Props を渡せば任意書式になります。フォーマッタ Props はレールの 4 つもセレクタの `formatOption` も同一の `PeriodOptionFormatter` で、1 つのコールバックがパッケージの全テキスト面を賄います。`<input>` の `value` と `<option value>` は常に ISO 8601 (または生の数値) で、どちらの軸の影響も受けません。
64
64
  - **高いアクセシビリティ**: WAI-ARIA `slider` ロール、キーボード操作 (矢印キー, PageUp/Down, Home/End) 完全準拠 (Vernier ノギスハンドル含む)。
65
65
  - **`Shift` + ホイールによる平行移動**: スライダーの範囲領域 (レールの行・つまみとラベルが描かれる帯 — レール方向にもラベルの外縁まで — ・ステッパー) のどこでも `Shift` を押しながらホイールを回すと、選択がステッパーと同じ ±1 単位だけ平行移動します。インジケーターの真上である必要はありません。`Shift` 無しの素のホイールはページのスクロールのままで、ページのスクロールを奪うのは `Shift` 付きのホイールが使えるデルタを運んでいるときだけです (選択が端に着いていて結果的に何も動かない場合も、操作は範囲領域へ向けられているため奪います)。縦向きレールではレールの正方向が上のため符号が反転します。ノギスではポインターがトラック中心線のどちら側にあるかで段 (マクロレールならマクロ窓、ミクロレールならミクロ選択) が決まり、ステッパーの上ではクリックと同じミクロ選択が動きます。
66
66
  - **レールが描く位置だけを名乗り、そこだけを確定させる**: 離散ミクロレール (`microIsDiscrete`) は候補集合しか描かないため、つまみの位置・読み上げ値・ラベル・そして確定値がすべて同じ 1 規則 (候補があれば最近傍候補、無ければ窓へのクランプ) を読みます。つまみが描かれている場所と利用側が受け取る値が食い違いません。
@@ -117,35 +117,139 @@ peer dependency の `@aiquants/virtualscroll` のスタイルシートは、本
117
117
  >
118
118
  > B のスタンドアロン CSS は自己完結のため `@source` 指定は不要ですが、ホストの Tailwind ビルドと混在させないでください (ユーティリティ層が二重定義になります)。
119
119
 
120
- ### ロケールと表示書式 (`locale`)
120
+ ### Localization (UI クローム言語 `locale` と `labels`)
121
121
 
122
- `PeriodSlider`・`YearSelector`・`MonthSelector`・`DateSelector` はいずれも `locale?: string` (BCP 47 言語タグ) を受け取ります。
122
+ `PeriodSlider`・`YearSelector`・`MonthSelector`・`DateSelector` はいずれも次の 2 つの Props を受け取ります。
123
123
 
124
- | `locale` | 組み込みの日付表記 |
124
+ | Prop | 型 | 既定 | 説明 |
125
+ | :--- | :--- | :--- | :--- |
126
+ | `locale` | `PeriodSliderLocale` (`"en"` \| `"ja"`) | `undefined` (= `"en"`) | UI クローム言語。アクセシブル名と、`DateSelector variant="dropdown"` のポップアップに埋め込まれた `@aiquants/virtualscroll` のスクロールクロームの言語を選ぶ。それ以外の値 (`"ja-JP"`・`"EN"`・`""`・`null` 等) は `RangeError` |
127
+ | `labels` | `PeriodSliderLabelOverrides` | `undefined` | `locale` のカタログへキー単位で重ねる上書き。各コンポーネントは自分のキーだけを読むため、1 つのオブジェクトをスライダーと全セレクタへ渡せる |
128
+
129
+ - **`locale` と `formatLocale` は別の軸です**。`locale` は部品の名前の言語 (閉じた `"en"` / `"ja"`)、`formatLocale` は日付テキストの書式 (任意の BCP 47 タグ) です。`formatLocale="ja-JP"` を渡しても名前は英語のまま、`locale="ja"` を渡しても日付は ISO 8601 のままです。**言語ネゴシエーションは行いません**: `navigator.language` などからの対応付けはホストの責務です。
130
+ - 既定の `"en"` カタログは 0.13 以前の英語既定と 1 バイトも違わないため、`locale` を渡さないホストの DOM は変わりません。
131
+ - `PeriodSliderLocale` は `@aiquants/virtualscroll` の `VirtualScrollLocale` そのものです。エンジンの 7 キーは `VIRTUAL_SCROLL_LABEL_CATALOGS` の値をそのまま再利用し、本パッケージでは書き直しません。
132
+
133
+ ```tsx
134
+ // 名前は日本語、日付は ja-JP の Intl 書式 (2 つの軸を両方指定)
135
+ <PeriodSlider mode="range" unit="month" locale="ja" formatLocale="ja-JP" minDate={minDate} maxDate={maxDate} range={range} onChangeRange={setRange} />
136
+
137
+ // 1 つの labels を全部品へ渡す (各部品は自分のキーだけを読む)。インラインで書いても値が同じなら再描画しない
138
+ const labels = { rangeStart: "調査開始月", rangeEnd: "調査完了月", previousMonth: "1 か月前" } as const
139
+ <PeriodSlider mode="range" unit="month" locale="ja" labels={labels} {...rest} />
140
+ <MonthSelector locale="ja" labels={labels} {...selectorRest} />
141
+ ```
142
+
143
+ #### カタログ (`PERIOD_SLIDER_LABEL_CATALOGS`)
144
+
145
+ 全 29 キー (エンジン 7 + 固有 22)。`PERIOD_SLIDER_LABEL_KEYS` はこの順の閉じたキー集合です。
146
+
147
+ | キー | 読む部品 / 面 | `en` | `ja` |
148
+ | :--- | :--- | :--- | :--- |
149
+ | `scrollUp` | `DateSelector variant="dropdown"` ポップアップの上矢印 | `Scroll up` | `上へスクロール` |
150
+ | `scrollDown` | 同 下矢印 | `Scroll down` | `下へスクロール` |
151
+ | `scrollLeft` | (横スクロールを持たないため描かれない) | `Scroll left` | `左へスクロール` |
152
+ | `scrollRight` | (同上) | `Scroll right` | `右へスクロール` |
153
+ | `scrollToTop` | (端移動ピルを有効にしないため描かれない) | `Top` | `先頭へ` |
154
+ | `scrollToBottom` | (同上) | `Bottom` | `末尾へ` |
155
+ | `noItems` | (選択肢 0 件ではポップアップを開かないため描かれない) | `No items` | `項目がありません` |
156
+ | `rangeStart` | `PeriodSlider` range の下限つまみ | `Range start` | `期間の開始` |
157
+ | `rangeEnd` | `PeriodSlider` range の上限つまみ | `Range end` | `期間の終了` |
158
+ | `selectedDate` | `PeriodSlider` point のつまみ | `Selected date` | `選択日` |
159
+ | `macroRangeStart` | ノギスのマクロ下限つまみ | `Macro range start` | `広域期間の開始` |
160
+ | `macroRangeEnd` | ノギスのマクロ上限つまみ | `Macro range end` | `広域期間の終了` |
161
+ | `microRangeStart` | ノギス (ミクロ期間形態) のミクロ下限つまみ | `Micro range start` | `詳細期間の開始` |
162
+ | `microRangeEnd` | ノギス (ミクロ期間形態) のミクロ上限つまみ | `Micro range end` | `詳細期間の終了` |
163
+ | `microSelectedDate` | ノギス (ミクロ時点形態) のミクロつまみ | `Micro selected date` | `詳細の選択日` |
164
+ | `decrease` | `PeriodSlider` の `minDate` 方向ステッパー | `Decrease` | `前へ` |
165
+ | `increase` | `PeriodSlider` の `maxDate` 方向ステッパー | `Increase` | `次へ` |
166
+ | `previousYear` | `YearSelector` の ◀ | `Previous year` | `前年` |
167
+ | `nextYear` | `YearSelector` の ▶ | `Next year` | `翌年` |
168
+ | `yearSelect` | `YearSelector` の年セレクト | `Year` | `年` |
169
+ | `previousMonth` | `MonthSelector` の ◀ | `Previous month` | `前月` |
170
+ | `nextMonth` | `MonthSelector` の ▶ | `Next month` | `翌月` |
171
+ | `monthSelect` | `MonthSelector` の年月セレクト / `input[type="month"]` | `Month` | `年月` |
172
+ | `previousDay` | `DateSelector` の ◀ | `Previous day` | `前日` |
173
+ | `nextDay` | `DateSelector` の ▶ | `Next day` | `翌日` |
174
+ | `dateSelect` | `DateSelector` の日付入力、`variant="dropdown"` ではコンボボックスとポップアップの `listbox` の双方 | `Date` | `日付` |
175
+ | `splitYear` | `DateSelector variant="split-dropdown"` の年セレクト | `Year` | `年` |
176
+ | `splitMonth` | 同 月セレクト | `Month` | `月` |
177
+ | `splitDay` | 同 日セレクト | `Day` | `日` |
178
+
179
+ `monthSelect` と `splitMonth` は `en` では同じ `Month` ですが、指す対象 (年月全体と月の部位) が違うため別キーです。
180
+
181
+ #### 解決規則 (`resolvePeriodSliderLabels`)
182
+
183
+ `resolvePeriodSliderLabels(locale, overrides)` は各部品が描画中に呼ぶ唯一の畳込み点で、公開もされています。
184
+
185
+ - ロケールは `resolveVirtualScrollLocale` で解決します (`undefined` → `"en"`)。それ以外の非対応値は、エンジンの `RangeError` を `cause` に持つ `RangeError: [period-slider] locale is the UI language, not a BCP 47 tag (date formatting reads formatLocale): [virtualscroll] locale must be one of "en", "ja"; got ...` になり、移行漏れの日付書式タグの移し先 (`formatLocale`) を示します。
186
+ - `overrides` が `undefined` ならカタログそのもの (同一参照) を返します。
187
+ - それ以外は素のオブジェクト (プロトタイプが `Object.prototype` か `null`) だけを受け付け、**自身のプロパティだけ**を読みます。配列・クラスインスタンス・他オブジェクト継承・`null`・非オブジェクトは `RangeError` です。
188
+ - 未知キーは `RangeError` です (撤去した `*AriaLabel` 名も未知キーとして拒否されます)。値が `undefined` のキーはカタログ値のままです。
189
+ - 与えた値は空白以外の文字を含む文字列でなければ `RangeError` です。エンジン 7 キーの検証は `resolveVirtualScrollLabels` 自身が行います。メッセージ中の拒否値は例外を投げない記述 (文字列は JSON、`null` は `null`、それ以外は `typeof`) で示されます。
190
+ - 結果は凍結された新しいオブジェクトです。入力は変更しません。
191
+
192
+ 部品は解決結果を値で安定化します。`labels={{ ... }}` をインラインで書いても、文字列が同じ間はメモ比較器が再描画を起こさず、内蔵 VirtualScroll へ渡すエンジンラベルの同一性も保たれます。
193
+
194
+ #### 0.13 からの移行
195
+
196
+ 0.14.0 は 0.x の破壊的変更を含むマイナー版です。変更の全体は `CHANGELOG.md` の 0.14.0 と同じです。
197
+
198
+ > [!WARNING]
199
+ > **0.13 で `locale="ja"` / `locale="en"` を渡していたホストは、0.14 でも型エラーも実行時エラーも出ないまま、意味だけが変わります**。`"ja"` / `"en"` は 0.13 では日付書式の正当な BCP 47 タグでしたが、0.14 では新しい UI 言語の `locale` の受理値そのものです。`formatLocale` へ改名しない限り、日付テキストは黙って ISO 8601 へ戻り (`2024/01` → `2024-01`、`04/15/2025` → `2025-04-15`)、`"ja"` ではボタン・つまみ・セレクトの名前も日本語カタログへ切り替わります (`Previous month` → `前月`)。アクセシブル名や Intl 書式の日付を照合するテストは、原因を示さずに失敗します。**0.13 の `locale` はその値が何であれ、すべて `formatLocale` へ改名してください**。部品の名前を日本語にしたい場合に限り、そのあとで `locale="ja"` を別途加えます。フックのオプション (`{ locale: "ja" }` → `{ formatLocale: "ja" }`) と `SelectorProps` も同じです。
200
+
201
+ - **日付書式の `locale` は `formatLocale` へ改名しました** (別名は残していません)。4 部品の Props・4 フックのオプション・`SelectorProps` のすべてが対象で、検証メッセージも新しい名前を名乗ります。`formatLabel` / `formatScreenReaderLabel` / `formatOptionText` の第 4 引数は位置引数のため呼び出しは変わりません。
202
+ - `"ja"` / `"en"` 以外のタグ (`locale="ja-JP"` 等) を旧名のまま渡すと、新しい UI 言語の `locale` として `RangeError: [period-slider] locale is the UI language, not a BCP 47 tag (date formatting reads formatLocale): ...` になります。`formatLocale="ja-JP"` へ書き換えてください。
203
+ - `"ja"` / `"en"` は拒否されません (上の警告)。値が何であっても改名が必要です。
204
+ - **4 部品 (延べ 19 個、名前としては 17 種: `selectAriaLabel` は 3 つのセレクタに共通) の `*AriaLabel` Props と `AccessibleSliderLabels` 型を撤去し、`labels` へ統合しました**。`formatAriaValueText` は `BasePeriodSliderProps` へ移り、そのまま使えます。
205
+
206
+ | 撤去した Prop | 部品 | `labels` のキー |
207
+ | :--- | :--- | :--- |
208
+ | `lowerAriaLabel` | `PeriodSlider` | `rangeStart` (ノギスのミクロ期間形態では `microRangeStart`) |
209
+ | `upperAriaLabel` | `PeriodSlider` | `rangeEnd` (ノギスのミクロ期間形態では `microRangeEnd`) |
210
+ | `pointAriaLabel` | `PeriodSlider` | `selectedDate` (ノギスのミクロ時点形態では `microSelectedDate`) |
211
+ | `macroLowerAriaLabel` / `macroUpperAriaLabel` | `PeriodSlider` | `macroRangeStart` / `macroRangeEnd` |
212
+ | `decreaseAriaLabel` / `increaseAriaLabel` | `PeriodSlider` | `decrease` / `increase` |
213
+ | `prevYearAriaLabel` / `nextYearAriaLabel` / `selectAriaLabel` | `YearSelector` | `previousYear` / `nextYear` / `yearSelect` |
214
+ | `prevMonthAriaLabel` / `nextMonthAriaLabel` / `selectAriaLabel` | `MonthSelector` | `previousMonth` / `nextMonth` / `monthSelect` |
215
+ | `prevDateAriaLabel` / `nextDateAriaLabel` / `selectAriaLabel` | `DateSelector` | `previousDay` / `nextDay` / `dateSelect` |
216
+ | `yearAriaLabel` / `monthAriaLabel` / `dayAriaLabel` | `DateSelector` | `splitYear` / `splitMonth` / `splitDay` |
217
+
218
+ - 日本語名を個別の Props で与えていたホストは、まず `locale="ja"` でカタログに任せ、カタログと違う名前だけを `labels` に残すのが最小の書き換えです。部品の名前を日本語で出したいホストは `locale="ja"` を明示してください (既定は `"en"` で、0.13 の英語既定と同じ名前です)。
219
+ - 撤去した `*AriaLabel` 名を `labels` のキーとして渡すと、未知キーとして `RangeError` になります (黙って無視されません)。
220
+ - 何も渡していなかったホスト (英語名・ISO 表記に依存するテストを含む) は変更不要です。
221
+ - **新しい公開 API**: Props `locale` / `labels` (4 部品と 4 フックのオプション、`SelectorProps`)、`PERIOD_SLIDER_LABEL_KEYS`・`PERIOD_SLIDER_LABEL_CATALOGS`・`resolvePeriodSliderLabels(locale, overrides)`、型 `PeriodSliderLocale` (`VirtualScrollLocale` と同一)・`PeriodSliderLabels`・`PeriodSliderLabelOverrides`。`DateSelector variant="dropdown"` のポップアップの内蔵 VirtualScroll へ `locale` とエンジン 7 キーを転送するため、スクロールバー矢印の名前 (`scrollUp` / `scrollDown`) も翻訳・上書きできます。
222
+ - 必要な `@aiquants/virtualscroll` は 3.7.0 以上です (`locale` / `labels` の受け口)。
223
+
224
+ ### 日付の表示書式 (`formatLocale`)
225
+
226
+ `PeriodSlider`・`YearSelector`・`MonthSelector`・`DateSelector` はいずれも `formatLocale?: string` (BCP 47 言語タグ) を受け取ります。UI クローム言語の `locale` とは独立しています。
227
+
228
+ | `formatLocale` | 組み込みの日付表記 |
125
229
  | :--- | :--- |
126
230
  | 未指定 (既定) | ロケール非依存の ISO 8601 表記。`unit="year"` は `2025`、`unit="month"` は `2025-01`、`unit="day"` は `2025-01-15` (年は 4 桁ゼロ埋め) |
127
- | 指定 | `Intl.DateTimeFormat(locale, options)` の出力。`options` は単位ごとに `year: { year: "numeric" }`、`month: { year: "numeric", month: "2-digit" }`、`day: { year: "numeric", month: "2-digit", day: "2-digit" }` |
231
+ | 指定 | `Intl.DateTimeFormat(formatLocale, options)` の出力。`options` は単位ごとに `year: { year: "numeric" }`、`month: { year: "numeric", month: "2-digit" }`、`day: { year: "numeric", month: "2-digit", day: "2-digit" }` |
128
232
 
129
233
  ISO 8601 はフォールバックではなく、本パッケージの仕様上の既定値です。英語などの自然言語表記を既定にすると汎用パッケージへ 1 つの言語を焼き付けることになり、`Intl` の出力は ICU / Node のバージョン間で変化するためです。
130
234
 
131
- - **優先順位**: フォーマッタ Props (`formatLabel` / `formatMacroLabel` / `formatMicroLabel` / `formatAriaValueText`、`DateSelector` の `formatYearOption` / `formatMonthOption` / `formatDayOption`) が最優先、次に `locale`、最後に ISO 8601 既定です。四半期表記だけはこの 3 段に乗りません (`locale` の段を持ちません)。理由と書き方は [四半期表示](#四半期表示-暦四半期と年度四半期) を参照してください。
235
+ - **優先順位**: フォーマッタ Props (`PeriodSlider` の `formatLabel` / `formatMacroLabel` / `formatMicroLabel` / `formatAriaValueText`、`YearSelector` / `MonthSelector` / `DateSelector` の `formatOption`) が最優先、次に `formatLocale`、最後に ISO 8601 既定です。この 5 つは**すべて同じ型 `PeriodOptionFormatter`** で、同一の関数値をどのスロットへも渡せます ([1 つのフォーマッタで全テキスト面を決める](#1-つのフォーマッタで全テキスト面を決める-formatoption))。四半期表記だけはこの 3 段に乗りません (`formatLocale` の段を持ちません)。理由と書き方は [四半期表示](#四半期表示-暦四半期と年度四半期) を参照してください。
132
236
  - **地域化されるのは人間が読むテキストのみ**: `<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 を渡してください。
237
+ - **アクセシブル名は `formatLocale` では変わりません**: ボタン・セレクト・つまみの名称は UI クローム言語 (`locale` / `labels`) だけが決めます ([Localization](#localization-ui-クローム言語-locale-と-labels))。
134
238
  - **Fail Fast**: 空文字列や `Intl.DateTimeFormat` が受理しない値 (`"en_US"`、非文字列等) を渡した場合、既定の ISO へ黙って戻さず `RangeError` を送出します (メッセージは [実行時バリデーション](#実行時バリデーション-fail-fast) 参照)。`"xx-YY"` のように構造として妥当なタグは、対応する翻訳データが無くても受理されます。
135
239
 
136
240
  ```tsx
137
- // 既定 (locale 省略): ラベルは "2024-03-10"
241
+ // 既定 (formatLocale 省略): ラベルは "2024-03-10"
138
242
  <PeriodSlider mode="point" unit="day" minDate={minDate} maxDate={maxDate} value={date} onChangePoint={setDate} />
139
243
 
140
- // locale 指定: ラベルは ja-JP ロケールの "2024/03/10"
141
- <PeriodSlider mode="point" unit="day" locale="ja-JP" minDate={minDate} maxDate={maxDate} value={date} onChangePoint={setDate} />
244
+ // formatLocale 指定: ラベルは ja-JP ロケールの "2024/03/10"
245
+ <PeriodSlider mode="point" unit="day" formatLocale="ja-JP" minDate={minDate} maxDate={maxDate} value={date} onChangePoint={setDate} />
142
246
  ```
143
247
 
144
248
  #### 日本語 UI での表示
145
249
 
146
- `locale="ja-JP"` を渡すと、日本語ロケールの書式へ切り替わります。`PeriodSlider` のラベルは `unit` に応じて `2024年` / `2024/01` / `2024/01/15`、`YearSelector` の選択肢は `2024年`、`MonthSelector` の選択肢は `2024/01`、`DateSelector` の選択肢は `2024/01/15`、`DateSelector` の `variant="split-dropdown"` は `2024年` / `01月` / `15日` になります (`variant="date"` はブラウザ標準の日付入力 UI のため、表示書式はブラウザのロケール設定が決めます)。
250
+ `formatLocale="ja-JP"` を渡すと、日本語ロケールの書式へ切り替わります (部品の名前も日本語にするには、別軸の `locale="ja"` を併せて渡します)。`PeriodSlider` のラベルは `unit` に応じて `2024年` / `2024/01` / `2024/01/15`、`YearSelector` の選択肢は `2024年`、`MonthSelector` の選択肢は `2024/01`、`DateSelector` の選択肢は `2024/01/15`、`DateSelector` の `variant="split-dropdown"` は `2024年` / `01月` / `15日` になります (`variant="date"` はブラウザ標準の日付入力 UI のため、表示書式はブラウザのロケール設定が決めます)。
147
251
 
148
- `2024年01月15日` のような独自表記が必要な場合は、`locale` ではなくフォーマッタ Props を渡してください。
252
+ `2024年01月15日` のような独自表記が必要な場合は、`formatLocale` ではなくフォーマッタ Props を渡してください。
149
253
 
150
254
  ```tsx
151
255
  const formatJapaneseDay = (date: Date): string => `${date.getFullYear()}年${String(date.getMonth() + 1).padStart(2, "0")}月${String(date.getDate()).padStart(2, "0")}日`
@@ -153,17 +257,86 @@ const formatJapaneseDay = (date: Date): string => `${date.getFullYear()}年${Str
153
257
  <PeriodSlider mode="point" unit="day" formatLabel={formatJapaneseDay} minDate={minDate} maxDate={maxDate} value={date} onChangePoint={setDate} />
154
258
  ```
155
259
 
156
- #### フック利用時の `locale`
260
+ #### 1 つのフォーマッタで全テキスト面を決める (`formatOption`)
261
+
262
+ レールと 3 セレクタは**同じ 1 つのコールバック型**でテキストを作ります。`PeriodSlider` の `formatLabel` / `formatMacroLabel` / `formatMicroLabel` / `formatAriaValueText` も、`YearSelector` / `MonthSelector` / `DateSelector` の `formatOption` も、いずれも `PeriodOptionFormatter` です。1 つの関数値をすべてへ渡せば、レールが `2025年度 第1四半期` と描いている隣でセレクタが `2025-04` と名乗る、という食い違いが起こりません。
263
+
264
+ ```ts
265
+ type PeriodOptionScope = "period" | "part"
266
+ type PeriodOptionFormatter = (date: Date, unit: PeriodSliderUnit, scope: PeriodOptionScope) => string
267
+ ```
268
+
269
+ - `date` は**その面が表す日付**です。面が所有する単位の先頭へ正規化され、所有しない細かい部位は 1 に固定されます。`scope: "part"` は自分の部位より粗い部位だけを保持値から取り、細かい部位は 1 に固定します (年は 1 月 1 日、月は当月 1 日、日は保持中の年月とその日)。**保持中の細かい部位を混ぜません** — 混ぜると、境界の異なる暦で同じ `<select>` の別々の値が同じ文字になります (下の「既知の制約」)。Invalid Date が渡ることはありません。確定値でない唯一の面はレールのホバーツールチップで、そこではポインタ下の日付が渡ります。
270
+ - `unit` と `scope` は**ウィジェットが与えます**。利用側が単位を言い当てるラッパーを書く必要はなく、年・月・日のどの面かは引数から判ります。
271
+ - `scope: "period"` はその操作要素の値そのもの (年・月・日それぞれの選択肢 1 件と、畳んだ表示)、`scope: "part"` は `variant="split-dropdown"` が横に 3 つ並べる部位の 1 つです。同じ `"month"` でも、前者は「年月全体」、後者は「月の部位」を指します。組み込みの段はこの 2 つを別の書式で描きます。
272
+
273
+ | `scope` | `unit="year"` | `unit="month"` | `unit="day"` |
274
+ | :--- | :--- | :--- | :--- |
275
+ | `"period"` (`formatLocale` 未指定) | `2025` | `2025-04` | `2025-04-15` |
276
+ | `"period"` (`formatLocale="ja-JP"`) | `2025年` | `2025/04` | `2025/04/15` |
277
+ | `"part"` (`formatLocale` 未指定) | `2025` | `04` | `15` |
278
+ | `"part"` (`formatLocale="ja-JP"`) | `2025年` | `04月` | `15日` |
279
+
280
+ 面ごとの呼び出しは次の通りです。
281
+
282
+ | コンポーネント / バリアント | 面 | `unit` | `scope` | `date` |
283
+ | :--- | :--- | :--- | :--- | :--- |
284
+ | `YearSelector` | 選択肢・畳んだ表示・境界外の保持年 | `"year"` | `"period"` | その年の先頭月 1 日 (`yearStartMonth` 準拠) |
285
+ | `MonthSelector variant="dropdown"` | 選択肢・畳んだ表示 | `"month"` | `"period"` | その月の 1 日 |
286
+ | `MonthSelector variant="dropdown"` | 集合外プレースホルダ | `"month"` | `"period"` | 保持中の日付 |
287
+ | `MonthSelector variant="date"` | ネイティブ入力 | — | — | **呼び出さない** |
288
+ | `DateSelector variant="dropdown"` | 仮想化された `role="option"` 行 | `"day"` | `"period"` | その行の日付 |
289
+ | `DateSelector variant="dropdown"` | 操作要素の表示テキスト (畳んだ表示) | `"day"` | `"period"` | 保持中の日付 |
290
+ | `DateSelector variant="split-dropdown"` | 年の選択肢とプレースホルダ | `"year"` | `"part"` | その年の 1 月 1 日 |
291
+ | `DateSelector variant="split-dropdown"` | 月の選択肢とプレースホルダ | `"month"` | `"part"` | 保持中の年の、その月の 1 日 |
292
+ | `DateSelector variant="split-dropdown"` | 日の選択肢とプレースホルダ | `"day"` | `"part"` | 保持中の年月の、その日 |
293
+ | `DateSelector variant="date"` | ネイティブ入力 | — | — | **呼び出さない** |
294
+ | ステッパー ◀▶ (3 セレクタ共通) | SVG の矢印 | — | — | **テキストノードを持たない** |
295
+ | `PeriodSlider` | つまみラベル・ツールチップ・マクロ / ミクロレール・`aria-valuetext` | 各単位 | `"period"` | 各つまみの日付 (ホバーツールチップだけはポインタ下の日付) |
296
+
297
+ `<select>` の畳んだ表示は選択中の `<option>` のテキストそのもの (HTML の規定) なので、一覧と畳んだ表示が食い違うことはありません。`DateSelector variant="dropdown"` だけは一覧行と操作要素が別経路ですが、**同じ関数値へ同じ形の引数**を渡すため同じ文字列になります。
298
+
299
+ 返り値は画面に出るだけのテキストではありません。レールのつまみは同じ文字列を `aria-valuetext` として読み上げ、`variant="dropdown"` のコンボボックスはそれを可視テキストである `value` として持ちます。**読み上げられる前提のテキストを返してください** — 記号や罫線だけのラベルは、晴眼者に見えている値がそのまま読み上げ不能になります。
300
+
301
+ **フォーマッタが届かない先** (いずれも別の関数が別の経路で作ります):
302
+
303
+ - すべての `aria-label` (◀▶・セレクト・コンボボックス・ポップアップの `listbox`、ポップアップのスクロールバーの矢印ボタン 2 つ)。これらは UI クローム言語の `locale` と `labels` が決めます ([Localization](#localization-ui-クローム言語-locale-と-labels))。矢印ボタンの名前 (`scrollUp` / `scrollDown`) は内蔵の `@aiquants/virtualscroll` へ転送され、常に `disabled` のためタブ順には入らず、支援技術がポップアップ内を辿ったときに現れます。
304
+ - すべての機械可読値: `<option value>`、`variant="dropdown"` の `data-value`、`<input type="date">` / `<input type="month">` の `value` / `min` / `max`。
305
+ - `onChange` が渡す引数。表示を変えても発行される `Date` は 1 ミリ秒も動きません。
157
306
 
158
- フック (`usePeriodSliderRange` 等) へ渡した `locale` は `sliderProps` へ転送されますが、`SelectorProps` は `locale` を含みません。スライダーとセレクタの書式を揃えるには、セレクタ側へも明示的に渡してください。
307
+ **呼び出しすら行わない面**: `MonthSelector variant="date"` と `DateSelector variant="date"` です。ネイティブ入力の表示テキストはブラウザが所有し、DOM 上に差し込む場所がありません (`formatLocale` も同じ理由で届きません)。受け取って無視するだけで、例外にはなりません — `variant` を切り替えただけで落ちると、Props を 1 度設定して使い分ける形が壊れるためです。
308
+
309
+ **先頭一致入力は表示書式に追従しません**。`DateSelector variant="dropdown"` の打鍵は、`formatOption` が何を描いていても**先発グレゴリオ暦の `yyyy[MM[dd]]` の数字列**として解釈されます。`20250309` と打てば 2025-03-09 の行へ飛び、その行の表示が `2024年度 第4四半期 (2025/03/09)` であっても変わりません。表示テキストの前方一致照合は選択肢総数に比例する費用になり、1 打鍵あたり定数時間という保証を壊すため採用していません。
310
+
311
+ **参照比較で再描画を判定するため、利用側でメモ化してください** (`allowedMonths` / `allowedDates` と同じ約束です)。JSX へインラインで書いた矢印関数は毎描画で同一性が変わり、選択肢ラベルの再計算を毎回起こします。モジュール直下の `const` か `useCallback` で固定してください。
312
+
313
+ **一部の (`unit`, `scope`) だけを担当する場合は、残りを `formatOptionText` へ転送します**。引数順がコールバックと同一なので逐語転送でき、担当外の書式を手で書き直す必要はありません。「`undefined` を返したら既定」という形は採っていません (代替値連鎖になるためです)。
314
+
315
+ ```ts
316
+ import { formatOptionText, type PeriodOptionFormatter } from "@aiquants/period-slider"
317
+
318
+ // 年の period 区分だけを自分で描き、残りは組み込みの段へそのまま渡す
319
+ const formatOption: PeriodOptionFormatter = (date, unit, scope) =>
320
+ unit === "year" && scope === "period" ? `${date.getFullYear()}年度` : formatOptionText(date, unit, scope, "ja-JP")
321
+
322
+ formatOption(new Date(2025, 3, 1), "year", "period") // "2025年度"
323
+ formatOption(new Date(2025, 3, 1), "month", "period") // "2025/04"
324
+ formatOption(new Date(2025, 3, 1), "month", "part") // "04月"
325
+ ```
326
+
327
+ #### フック利用時の `formatLocale` / `locale` / `labels`
328
+
329
+ フック (`usePeriodSliderRange` 等) へ渡した `formatLocale`・`formatOption`・`locale`・`labels` は `sliderProps` と全 `SelectorProps` の両方へ配られます。フックへ 1 度渡せば、レールと隣のセレクタは同じ書式・同じ言語で描かれます。セレクタだけ別の値にしたい場合は、スプレッドの後ろで直接渡してください (後ろの指定が勝ちます)。
159
330
 
160
331
  ```tsx
161
- <MonthSelector {...startSelectorProps} locale="ja-JP" />
332
+ const { sliderProps, startSelectorProps } = usePeriodSliderRange({ unit: "month", minDate, maxDate, initialRange, formatLocale: "ja-JP", locale: "ja" })
333
+ <PeriodSlider {...sliderProps} />
334
+ <MonthSelector {...startSelectorProps} />
162
335
  ```
163
336
 
164
337
  #### 四半期表示 (暦四半期と年度四半期)
165
338
 
166
- 四半期だけは上の 3 段の優先順位に乗りません。**`locale` の段が存在しない**ためです。ECMA-402 に四半期のフィールドが無く、`Intl.DateTimeFormat` は `quarter` オプションを受け取っても送出せず黙って捨てます (Node v24.16.0 / ICU 78.3 で実測)。
339
+ 四半期だけは上の 3 段の優先順位に乗りません。**`formatLocale` の段が存在しない**ためです。ECMA-402 に四半期のフィールドが無く、`Intl.DateTimeFormat` は `quarter` オプションを受け取っても送出せず黙って捨てます (Node v24.16.0 / ICU 78.3 で実測)。
167
340
 
168
341
  ```ts
169
342
  const formatter = new Intl.DateTimeFormat("ja-JP", { quarter: "long", year: "numeric" })
@@ -175,7 +348,7 @@ formatter.format(new Date(2025, 3, 1)) // "2025年" (四半期はどこにも現
175
348
  Intl.supportedValuesOf("unit").includes("quarter") // false
176
349
  ```
177
350
 
178
- 履行できない引数は置かない方針のため、四半期の 2 関数は `locale` を受け取りません。
351
+ 履行できない引数は置かない方針のため、四半期の 2 関数は `formatLocale` を受け取りません。
179
352
 
180
353
  | 関数 | シグネチャ | 返り値 |
181
354
  | :--- | :--- | :--- |
@@ -201,15 +374,15 @@ const formatFiscalQuarterJa = (date: Date): string => {
201
374
  formatFiscalQuarterJa(new Date(2026, 0, 15)) // "2025年度 第4四半期"
202
375
  ```
203
376
 
204
- 年の部分だけは `locale` に従わせられます。年ラベルと同じ公開経路 (`normalizeDateByUnit` を通した `formatLabel("year", ...)`) を使うと、`Q` の綴りだけがロケール非依存のまま残ります。
377
+ 年の部分だけは `formatLocale` に従わせられます。年ラベルと同じ公開経路 (`normalizeDateByUnit` を通した `formatLabel("year", ...)`) を使うと、`Q` の綴りだけがロケール非依存のまま残ります。
205
378
 
206
379
  ```tsx
207
380
  import { formatLabel, normalizeDateByUnit, resolveQuarter } from "@aiquants/period-slider"
208
381
 
209
- const formatQuarterWithLocale = (date: Date, locale?: string): string => {
382
+ const formatQuarterWithLocale = (date: Date, formatLocale?: string): string => {
210
383
  const { quarter } = resolveQuarter(date, FISCAL_YEAR_START_MONTH)
211
384
  // 年の切り出しを自前で書くと、年ラベルと四半期ラベルが年について食い違い得る
212
- const year = formatLabel("year", normalizeDateByUnit("year", date, FISCAL_YEAR_START_MONTH), undefined, locale)
385
+ const year = formatLabel("year", normalizeDateByUnit("year", date, FISCAL_YEAR_START_MONTH), undefined, formatLocale)
213
386
  return `${year} Q${quarter}`
214
387
  }
215
388
 
@@ -217,6 +390,98 @@ formatQuarterWithLocale(new Date(2025, 3, 1)) // "2025 Q1"
217
390
  formatQuarterWithLocale(new Date(2025, 3, 1), "ja-JP") // "2025年 Q1"
218
391
  ```
219
392
 
393
+ ##### 1 つのコールバックをレールと 3 セレクタへ渡す
394
+
395
+ `formatLabel` と `formatOption` は同じ `PeriodOptionFormatter` なので、**ページ全体で 1 つの関数値**を作り、レールにもセレクタにも同じものを渡せます。自分で描かない `scope: "part"` は `formatOptionText` へ逐語転送します。
396
+
397
+ ```tsx
398
+ import {
399
+ DateSelector,
400
+ MonthSelector,
401
+ PeriodSlider,
402
+ YearSelector,
403
+ formatOptionText,
404
+ resolveQuarter,
405
+ type PeriodOptionFormatter,
406
+ } from "@aiquants/period-slider"
407
+
408
+ const FISCAL_YEAR_START_MONTH = 3
409
+
410
+ // モジュール直下に置いて同一性を固定する (インラインの矢印関数は毎描画で別物になる)
411
+ const formatFiscalPeriod: PeriodOptionFormatter = (date, unit, scope) => {
412
+ // 分割セレクトの 3 部位は自分で描かず、組み込みの段へそのまま渡す
413
+ if (scope === "part") return formatOptionText(date, unit, scope, "ja-JP")
414
+ const { year, quarter } = resolveQuarter(date, FISCAL_YEAR_START_MONTH)
415
+ if (unit === "year") return `${year}年度`
416
+ if (unit === "month") return `${year}年度 第${quarter}四半期`
417
+ return `${year}年度 第${quarter}四半期 (${formatOptionText(date, "day", "period", "ja-JP")})`
418
+ }
419
+
420
+ formatFiscalPeriod(new Date(2026, 0, 1), "year", "period") // "2025年度"
421
+ formatFiscalPeriod(new Date(2026, 0, 1), "month", "period") // "2025年度 第4四半期"
422
+ formatFiscalPeriod(new Date(2025, 4, 15), "day", "period") // "2025年度 第1四半期 (2025/05/15)"
423
+ formatFiscalPeriod(new Date(2025, 4, 15), "month", "part") // "05月"
424
+ ```
425
+
426
+ ```tsx
427
+ <PeriodSlider
428
+ mode="point"
429
+ unit="month"
430
+ yearStartMonth={FISCAL_YEAR_START_MONTH}
431
+ minDate={new Date(2025, 3, 1)}
432
+ maxDate={new Date(2026, 2, 31)}
433
+ value={month}
434
+ formatLabel={formatFiscalPeriod}
435
+ onChangePoint={setMonth}
436
+ />
437
+
438
+ {/* 選択肢は "2026年度" / "2025年度" / "2024年度" */}
439
+ <YearSelector
440
+ value={month}
441
+ minYear={2024}
442
+ maxYear={2026}
443
+ yearStartMonth={FISCAL_YEAR_START_MONTH}
444
+ formatOption={formatFiscalPeriod}
445
+ onChange={setMonth}
446
+ />
447
+
448
+ {/* 選択肢は "2025年度 第2四半期" (2025-09 〜 2025-07) と "2025年度 第1四半期" (2025-06 〜 2025-04) */}
449
+ <MonthSelector
450
+ variant="dropdown"
451
+ value={month}
452
+ minDate={new Date(2025, 3, 1)}
453
+ maxDate={new Date(2025, 8, 30)}
454
+ formatOption={formatFiscalPeriod}
455
+ onChange={setMonth}
456
+ />
457
+
458
+ {/* 3 部位は "2025年" / "05月" / "15日" */}
459
+ <DateSelector
460
+ variant="split-dropdown"
461
+ value={day}
462
+ minDate={new Date(2025, 3, 1)}
463
+ maxDate={new Date(2025, 5, 30)}
464
+ formatOption={formatFiscalPeriod}
465
+ onChange={setDay}
466
+ />
467
+ ```
468
+
469
+ `formatAriaValueText` を省略すれば、読み上げにも同じ文字列が流れます (上の `PeriodSlider` は 2025-05 を選択中に `aria-valuetext="2025年度 第1四半期"` を持ちます)。`DateSelector variant="dropdown"` へ同じ関数を渡すと、行も操作要素も `2025年度 第1四半期 (2025/05/15)` になり、`data-value` は `2025-05-15` のままです。
470
+
471
+ > [!WARNING]
472
+ > **`unit="month"` の四半期ラベルは、3 つ並ぶ月が同じ文字列になります。** 上の `MonthSelector` は 2025-04 / 2025-05 / 2025-06 の 3 選択肢がすべて `2025年度 第1四半期` です (`<option value>` は `2025-04` / `2025-05` / `2025-06` のまま区別されるので、選択そのものは壊れません)。四半期を 1 行 1 件で選ばせたい場合は、四半期の開始月だけを `allowedMonths` へ渡してください。
473
+
474
+ ```tsx
475
+ // 各四半期の開始月だけを候補にすると、選択肢と表示が 1 対 1 になる
476
+ const quarterStarts = useMemo(
477
+ () => [0, 3, 6, 9].map((offset) => new Date(2025, FISCAL_YEAR_START_MONTH + offset, 1)),
478
+ [],
479
+ )
480
+
481
+ // 選択肢は "2025年度 第4四半期" (2026-01) / 第3 (2025-10) / 第2 (2025-07) / 第1 (2025-04) の 4 件
482
+ <MonthSelector variant="dropdown" value={month} allowedMonths={quarterStarts} formatOption={formatFiscalPeriod} onChange={setMonth} />
483
+ ```
484
+
220
485
  `PeriodQuarter` の各フィールド、`yearStartMonth` ごとの出力表、例外の契約は [公開ユーティリティ関数](#公開ユーティリティ関数) にまとめてあります。
221
486
 
222
487
  ### ゼロ・ボイラープレート React フック連携 (`usePeriodSliderRange`)
@@ -374,7 +639,7 @@ export function VernierPointExample() {
374
639
 
375
640
  時点形態の契約は次のとおりです。
376
641
 
377
- - ミクロレールのつまみは 1 つ (`data-handle-type="micro-point"`) で、`role="slider"` はマクロ 2 つと合わせて 3 つになります。既定のアクセシブル名は `"Micro selected date"` で、`pointAriaLabel` で上書きできます。
642
+ - ミクロレールのつまみは 1 つ (`data-handle-type="micro-point"`) で、`role="slider"` はマクロ 2 つと合わせて 3 つになります。既定のアクセシブル名は `"Micro selected date"` (`locale="ja"` では `詳細の選択日`) で、`labels.microSelectedDate` で上書きできます (point モード用の `selectedDate` は読みません)。
378
643
  - ミクロ側の接続バー (`period-slider-connect-micro`) は描きません。幅を持たない選択を帯で表すと「満タンの期間」に見え、掴める帯まで生えてしまうためです。マクロ窓の帯は従来どおり残ります。
379
644
  - `aria-valuemin` / `aria-valuemax` はミクロレールの両端 (マクロ窓で切り出した範囲) で、`aria-valuenow` は選択時点そのものです。期間形態のように相手のつまみで塞がれることはありません。
380
645
  - キーボードは `mode="point"` と同じく左右対称です。`←` `→` で ±1 ミクロ単位、`PageUp` / `PageDown` で ±5、`Home` / `End` でレールの両端へ届きます。動けない押下はコールバックを発火しません。
@@ -595,8 +860,10 @@ export function FiscalQuarterLabelExample() {
595
860
  | `hideConnectBar` | `boolean` | `false` | 範囲選択バー (ハイライト) を非表示にし、独立 2 点選択 UI として利用 |
596
861
  | `showTicks` | `boolean` | `false` | 離散モード時のトラック上の目盛線の表示有無 |
597
862
  | `showStepper` | `boolean` | `true` | ステッパーボタンの表示有無 (水平時は左右、垂直時は上下を指す矢印) |
598
- | `formatLabel` | `(date: Date) => string` | `undefined` | 日付ラベル・ツールチップのカスタム表示文字列生成関数。`locale` より優先される。ノギスでは `formatMacroLabel` / `formatMicroLabel` 双方の既定値でもあるため、ここへ四半期フォーマッタを渡すと**マクロ側にも同じ関数が流れ**、マクロラベルが常に Q1 になる。ノギスで四半期を出すなら `formatMicroLabel` にだけ渡す |
599
- | `locale` | `string` | `undefined` | 組み込み日付表記のロケール (BCP 47 言語タグ)。未指定はロケール非依存の ISO 8601 (`2025` / `2025-01` / `2025-01-15`)、指定時は `Intl.DateTimeFormat` 書式。空文字列・不正タグ・非文字列は `RangeError` |
863
+ | `formatLabel` | `PeriodOptionFormatter` | `undefined` | 日付ラベル・ツールチップのカスタム表示文字列生成関数。`formatLocale` より優先される。3 セレクタの `formatOption` と同じ型のため、同一の関数値を両方へ渡せる (引数は `(date, unit, scope)` で `scope` は常に `"period"`。`(date) => string` も従来どおり代入可能)。ノギスでは `formatMacroLabel` / `formatMicroLabel` 双方の既定値でもあるため、ここへ四半期フォーマッタを渡すと**マクロ側にも同じ関数が流れ**、マクロラベルが常に Q1 になる。ノギスで四半期を出すなら `formatMicroLabel` にだけ渡す |
864
+ | `formatLocale` | `string` | `undefined` | 組み込み日付表記のロケール (BCP 47 言語タグ)。未指定はロケール非依存の ISO 8601 (`2025` / `2025-01` / `2025-01-15`)、指定時は `Intl.DateTimeFormat` 書式。空文字列・不正タグ・非文字列は `RangeError`。アクセシブル名の言語は変えない |
865
+ | `locale` | `PeriodSliderLocale` | `undefined` (= `"en"`) | UI クローム言語 (`"en"` / `"ja"`)。つまみとステッパーのアクセシブル名を選ぶ。日付表記は変えない。非対応値は `RangeError` ([Localization](#localization-ui-クローム言語-locale-と-labels)) |
866
+ | `labels` | `PeriodSliderLabelOverrides` | `undefined` | `locale` のカタログへのキー単位の上書き。スライダーが読むのは下の [アクセシブル名](#アクセシブル名-labels-のキー全モード共通) の 10 キー |
600
867
  | `disabled` | `boolean` | `false` | スライダーの無効化・非活性表示 |
601
868
  | `debounceMs` | `number` | `0` | 変更コールバック呼び出しのデバウンス時間 (ミリ秒)。`0` は即時発火 |
602
869
  | `colorScheme` | `PeriodSliderColorScheme` | `"blue-rose"` | カラーテーマプリセット (`"blue-rose"`, `"indigo-amber"`, `"teal-emerald"`, `"violet-fuchsia"`, `"slate-sky"`, `"monochrome"`) |
@@ -637,8 +904,8 @@ export function FiscalQuarterLabelExample() {
637
904
  | `microIsDiscrete` | `boolean` | `false` | ミクロ側の離散スナップ有効化フラグ。`false` の間は `microAllowedDates` が参照されない。`true` かつ現在のマクロ窓が候補を 1 つ以上含む間、ミクロレールは候補集合しか描かないため、位置・`aria-valuenow` / `aria-valuetext`・ラベル・**確定値**のすべてが最近傍候補へ解決される (ドラッグ・キーボード・ホイール・ステッパー・フックの収め込みで同一規則)。窓が候補を 1 つも含まない場合は窓内の連続値として振る舞う |
638
905
  | `macroAllowedDates` | `Date[]` | `allowedDates` | マクロ側の離散スナップ対象日付配列。`macroIsDiscrete={true}` との併用が必須 |
639
906
  | `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 とは独立に選べる |
907
+ | `formatMacroLabel` | `PeriodOptionFormatter` | `formatLabel` | マクロ側ラベル・ツールチップのカスタム表示文字列生成関数。引数はつまみ位置・`aria-valuenow` と同一の符号値から復元した `macroUnit` 正規化済み `Date` であり、`macroRange` の生の値ではない (`macroUnit="month"` なら常に月初、`"year"` なら常にその年の先頭月 1 日 (`yearStartMonth` が `0` なら元日)、`"day"` は暦日そのままで時刻が 0 時)。`macroUnit="year"` では引数が必ず年の先頭月であるため、ここへ四半期フォーマッタを渡すと表示は常に Q1 になる (四半期は月・日解像度のミクロ側へ載せる) |
908
+ | `formatMicroLabel` | `PeriodOptionFormatter` | `formatLabel` | ミクロ側ラベル・ツールチップのカスタム表示文字列生成関数。引数はつまみ位置と同一の `microUnit` 正規化済み `Date` (`microUnit="month"` なら常に月初)。四半期ラベルはこの `microUnit="month"` / `"day"` の側に載せる。`formatQuarterLabel` へ渡す `yearStartMonth` はその関数自身の引数であり、スライダーの `yearStartMonth` Props とは独立に選べる |
642
909
  | `vernierOrientation` | `"macro-top" \| "macro-bottom" \| "macro-left" \| "macro-right"` | 水平時 `"macro-top"` / `isVertical` 時 `"macro-left"` | ノギスのレール配置。水平時は上下 (`macro-top` / `macro-bottom`)、垂直時は左右 (`macro-left` / `macro-right`) を指定 |
643
910
  | `showVernierProjection` | `boolean` | `true` | マクロ窓からミクロ全幅へ広がる半透明台形プロジェクション光の表示有無 |
644
911
  | `showVernierTicks` | `boolean` | `true` | 目盛線の表示有無。マクロレールに 20% 間隔で 4 本、ミクロレールに 10% 間隔で 9 本を等間隔に描画する |
@@ -666,18 +933,25 @@ export function FiscalQuarterLabelExample() {
666
933
 
667
934
  期間側の 3 Props と時点側の 3 Props は**相互排他**です。型では互いを `never` として宣言しているため同時指定はコンパイルエラーになり、JavaScript からの同時指定は描画時に `RangeError` で拒否します (黙ってどちらかを優先すると、渡したはずのコールバックが永久に鳴らない状態になるため)。
668
935
 
669
- #### アクセシビリティ Props (`AccessibleSliderLabels`, 全モード共通)
936
+ #### アクセシブル名 (`labels` のキー、全モード共通)
937
+
938
+ `PeriodSlider` のつまみとステッパーの名前は `locale` のカタログと `labels` から決まります ([Localization](#localization-ui-クローム言語-locale-と-labels))。
939
+
940
+ | `labels` のキー | 既定 (`en` / `ja`) | 名指す部品 |
941
+ | :--- | :--- | :--- |
942
+ | `rangeStart` / `rangeEnd` | `Range start` / `期間の開始`、`Range end` / `期間の終了` | `mode="range"` の下限・上限つまみ |
943
+ | `selectedDate` | `Selected date` / `選択日` | `mode="point"` のつまみ |
944
+ | `macroRangeStart` / `macroRangeEnd` | `Macro range start` / `広域期間の開始`、`Macro range end` / `広域期間の終了` | ノギスのマクロ下限・上限つまみ |
945
+ | `microRangeStart` / `microRangeEnd` | `Micro range start` / `詳細期間の開始`、`Micro range end` / `詳細期間の終了` | ノギス (ミクロ期間形態) のミクロ下限・上限つまみ |
946
+ | `microSelectedDate` | `Micro selected date` / `詳細の選択日` | ノギス (ミクロ時点形態) のミクロつまみ |
947
+ | `decrease` | `Decrease` / `前へ` | 値を `minDate` 方向へ 1 単位動かすステッパーボタン (水平時は左端の左向き矢印、垂直時は下端の下向き矢印) |
948
+ | `increase` | `Increase` / `次へ` | 値を `maxDate` 方向へ 1 単位動かすステッパーボタン (水平時は右端の右向き矢印、垂直時は上端の上向き矢印) |
949
+
950
+ 読み上げ値 (`aria-valuetext`) は名前ではなく日付テキストで、次の Prop が決めます。
670
951
 
671
952
  | プロパティ | 型 | 既定値 | 説明 |
672
953
  | :--- | :--- | :--- | :--- |
673
- | `lowerAriaLabel` | `string` | `"Range start"` (vernier 時 `"Micro range start"`) | 下限つまみのアクセシブル名 |
674
- | `upperAriaLabel` | `string` | `"Range end"` (vernier 時 `"Micro range end"`) | 上限つまみのアクセシブル名 |
675
- | `pointAriaLabel` | `string` | `"Selected date"` (vernier 時点形態では `"Micro selected date"`) | 単一選択つまみのアクセシブル名 (`mode="point"`、およびノギスのミクロ時点形態) |
676
- | `macroLowerAriaLabel` | `string` | `"Macro range start"` | マクロ下限つまみのアクセシブル名 (`mode="vernier"` のみ) |
677
- | `macroUpperAriaLabel` | `string` | `"Macro range end"` | マクロ上限つまみのアクセシブル名 (`mode="vernier"` のみ) |
678
- | `decreaseAriaLabel` | `string` | `"Decrease"` | 値を `minDate` 方向へ 1 単位動かすステッパーボタンのアクセシブル名 (水平時は左端の左向き矢印、垂直時は下端の下向き矢印) |
679
- | `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` 呼び出し**から組み立ててください (省略すれば可視ラベルと一字一句同じ文字列が読み上げられます) |
954
+ | `formatAriaValueText` | `PeriodOptionFormatter` | `undefined` | `aria-valuetext` の読み上げ文字列生成関数。未指定時は可視ラベルと同一の文字列 (ISO 8601、`formatLocale` 指定時は `Intl.DateTimeFormat` 書式)。ノギスでは可視ラベルと同じく、マクロ側に `macroUnit` 正規化済み、ミクロ側に `microUnit` 正規化済みの `Date` が渡される。**指定すると、`aria-valuetext` を組み立てる 6 か所すべてで可視ラベルの経路 (`formatScreenReaderLabel`) を短絡します**。四半期ラベルを表示しているなら、ここへ渡す文字列も**同じ `resolveQuarter` 呼び出し**から組み立ててください (省略すれば可視ラベルと一字一句同じ文字列が読み上げられます) |
681
955
 
682
956
  ステッパーの 2 つの名称は配置ではなく値への作用で定義されています。同じボタンが水平レイアウトでは左、垂直レイアウトでは下に立つため、位置で命名すると意味が反転するからです。
683
957
 
@@ -705,7 +979,7 @@ DOM 要素の特定は CSS クラス名ではなく `data-*` 属性で行いま
705
979
  | `[data-handle-type="macro-low" \| "macro-high" \| "micro-low" \| "micro-high" \| "micro-point"]` | ノギスモードのつまみのみに付与 (`role="slider"` との併用)。`micro-low` / `micro-high` はミクロが期間の形態、`micro-point` はミクロが時点の形態でのみ現れ、両者が同時に存在することはない。配置位置は `data-vernier-pos` (`top` / `bottom` / `left` / `right`) が持ち、配色を決める `data-handle-type` と直交する |
706
980
  | `[data-testid="period-slider-track"]` | トラック (`data-vernier-orientation` でノギスのレール配置を判別) |
707
981
  | `[data-range-area]` | 範囲領域 (ルート要素の最初の子)。`Shift` + ホイールを受ける矩形そのもので、何も描かず `pointer-events: none` のためヒットテストにも答えない |
708
- | `button[aria-label]` 内の `svg[data-arrow="left" \| "right" \| "up" \| "down"]` | ステッパー (アクセシブル名は `decreaseAriaLabel` / `increaseAriaLabel`、`type="button"`) とその矢印の向き。矢印は色を持たず、ボタンの文字色 (`currentColor`) で塗られる (パッケージのスタイルシートも、ボタンや祖先のクラスも矢印を選ばない)。ホバーの文字色は不透明で、押せる矢印をホバーで使用不可の淡色へ落とさない。境界で動けない間はボタンが `aria-disabled="true"` を持ち、フォーカスを保ちタブ順にも残ったまま押下を受け付けない。ネイティブの `disabled` は `disabled` Props でスライダー全体を無効にしたときだけ付く |
982
+ | `button[aria-label]` 内の `svg[data-arrow="left" \| "right" \| "up" \| "down"]` | ステッパー (アクセシブル名は `labels` の `decrease` / `increase`、`type="button"`) とその矢印の向き。矢印は色を持たず、ボタンの文字色 (`currentColor`) で塗られる (パッケージのスタイルシートも、ボタンや祖先のクラスも矢印を選ばない)。ホバーの文字色は不透明で、押せる矢印をホバーで使用不可の淡色へ落とさない。境界で動けない間はボタンが `aria-disabled="true"` を持ち、フォーカスを保ちタブ順にも残ったまま押下を受け付けない。ネイティブの `disabled` は `disabled` Props でスライダー全体を無効にしたときだけ付く |
709
983
  | `[data-testid="period-slider-connect"]` | 接続バー。ノギスでは `period-slider-connect-macro` / `period-slider-connect-micro` の 2 本 (ミクロが時点の形態では `period-slider-connect-micro` を描かない) |
710
984
  | `[data-testid="period-slider-tick"]` | 目盛線と離散レールの候補点。ノギスモードでは `data-tick-scale="macro" \| "micro"` が併記され上下段を判別できる。塗りはパッケージのスタイルシートが 1 か所で持つ (レールの境界線と同じインク) |
711
985
  | `[data-testid="period-slider-hairline"]` | ノギスの読み取りの針 (`showHairline` が真のときだけ描かれる)。線の中心がつまみの中心 = 値そのものに揃う |
@@ -721,6 +995,31 @@ DOM 要素の特定は CSS クラス名ではなく `data-*` 属性で行いま
721
995
 
722
996
  `PeriodSlider` が内部で使う純粋関数のうち、次のものはパッケージのルート (`@aiquants/period-slider`) から公開されています。React に依存しないため、レールの外 (取得期間の算出、集計キーの生成など) でもそのまま使えます。
723
997
 
998
+ #### 表示テキスト — `formatOptionText` / `PeriodOptionFormatter` / `PeriodOptionScope`
999
+
1000
+ ```ts
1001
+ export type PeriodOptionScope = "period" | "part"
1002
+ export type PeriodOptionFormatter = (date: Date, unit: PeriodSliderUnit, scope: PeriodOptionScope) => string
1003
+
1004
+ export declare const formatOptionText: (date: Date, unit: PeriodSliderUnit, scope: PeriodOptionScope, formatLocale?: string) => string
1005
+ ```
1006
+
1007
+ - `PeriodOptionFormatter` は、4 つのスライダー Props (`formatLabel` / `formatMacroLabel` / `formatMicroLabel` / `formatAriaValueText`) と 3 セレクタの `formatOption` に**共通の 1 つの型**です。面ごとの契約は [1 つのフォーマッタで全テキスト面を決める](#1-つのフォーマッタで全テキスト面を決める-formatoption) にまとめてあります。
1008
+ - **引数を減らした関数は今まで通り渡せます**。`(date: Date) => string` も `(date: Date, unit: PeriodSliderUnit) => string` も代入可能で、逆向き (3 引数の関数を 1 引数のスロットへ) だけがコンパイルエラーになります。`formatQuarterLabel` は `(Date, number) => string` で第 2 引数が単位ではなく `yearStartMonth` のため、`formatOption` へ**直接は渡せません** (型が拒否します)。四半期は上のレシピのように `resolveQuarter` から組み立ててください。
1009
+ - `PeriodOptionScope` は `"period"` (その操作要素の値そのもの) と `"part"` (`variant="split-dropdown"` が 3 つ並べる部位の 1 つ) の 2 値です。組み込みの段がこの 2 つを別の Intl オプション集合で描き分けているため、`unit` だけでは同じ `"month"` が「年月全体」と「月の部位」のどちらを指すのか決まりません。
1010
+ - `formatOptionText` は**組み込みの 2 段そのもの**です (`formatLocale` 指定時は `Intl.DateTimeFormat`、未指定時はロケール非依存の ISO 8601)。第 1 段を担当しない (`unit`, `scope`) の組は、この関数へそのまま転送してください。引数順がコールバックと同一なので逐語転送できます。
1011
+ - **「`undefined` を返したら既定」という形は採っていません**。それは代替値連鎖であり、本パッケージが排している形です。返り値は常に文字列で、**空文字列も合法**です (無効な日付に対する `formatLabel` の仕様値と同じ)。
1012
+ - `date` が未指定・Invalid Date のときは `""` を返します (`formatLabel` と同じ約束)。
1013
+ - `unit` が `"year"` / `"month"` / `"day"` 以外、`scope` が `"period"` / `"part"` 以外の場合は `RangeError` を送出し、メッセージは関数自身を名指しします (`formatOptionText: scope must be "period" or "part" (received: label)`)。フォーマッタ Props は型検査を受けますが、この関数は公開の入口であり JavaScript からも引数が届くためです。
1014
+
1015
+ `formatOptionText(date, unit, scope, formatLocale)` の出力 (`date` は `2025-04-15`):
1016
+
1017
+ | `unit` | `scope: "period"` (`formatLocale` 未指定) | `scope: "period"` (`"ja-JP"`) | `scope: "part"` (`formatLocale` 未指定) | `scope: "part"` (`"ja-JP"`) |
1018
+ | :--- | :--- | :--- | :--- | :--- |
1019
+ | `"year"` | `2025` | `2025年` | `2025` | `2025年` |
1020
+ | `"month"` | `2025-04` | `2025/04` | `04` | `04月` |
1021
+ | `"day"` | `2025-04-15` | `2025/04/15` | `15` | `15日` |
1022
+
724
1023
  #### 四半期 — `resolveQuarter` / `formatQuarterLabel`
725
1024
 
726
1025
  ```ts
@@ -814,9 +1113,11 @@ yearStartMonth=9 2,2,2,3,3,3,4,4,4,1,1,1
814
1113
  | `PeriodSlider` (`vernier`) | 指定されたミクロ選択が `microUnit` の解像度で `[minDate, maxDate]` の外 | `RangeError: PeriodSlider: <プロパティ名> must lie within [minDate, maxDate] (...)` (`macroRange` は定義域をはみ出してよい。レールが定義域と積を取り、通知はクランプ済みの値を配るため) |
815
1114
  | `PeriodSlider` | `allowedDates` の全要素が `[minDate, maxDate]` 外 | `RangeError: getSortedAllowedDates: every allowedDates entry falls outside [minDate, maxDate] (...)` |
816
1115
  | `usePeriodSliderRange` / `usePeriodSliderPoint` / `useVernierSliderRange` / `useVernierSliderPoint` | 境界・初期値の欠落、Invalid Date、逆転 | `RangeError: <フック名>: ...` |
817
- | `PeriodSlider` | `locale` が空文字列・構造として不正な BCP 47 タグ・非文字列 | `RangeError: PeriodSlider: locale must be a valid BCP 47 language tag (received: ...)` |
818
- | `DateSelector` | 同上 | `RangeError: DateSelector: "locale" must be a valid BCP 47 language tag (received ...)` |
819
- | `MonthSelector` / `YearSelector` | 同上 | ``RangeError: <コンポーネント名>: `locale` must be a valid BCP 47 language tag, received ....`` |
1116
+ | `PeriodSlider` | `formatLocale` が空文字列・構造として不正な BCP 47 タグ・非文字列 | `RangeError: PeriodSlider: formatLocale must be a valid BCP 47 language tag (received: ...)` |
1117
+ | `DateSelector` | 同上 | `RangeError: DateSelector: "formatLocale" must be a valid BCP 47 language tag (received ...)` |
1118
+ | `MonthSelector` / `YearSelector` | 同上 | ``RangeError: <コンポーネント名>: `formatLocale` must be a valid BCP 47 language tag, received ....`` |
1119
+ | 4 部品すべて | `locale` が `"en"` / `"ja"` 以外 (`"ja-JP"`・`"EN"`・`""`・`null` 等) | `RangeError: [period-slider] locale is the UI language, not a BCP 47 tag (date formatting reads formatLocale): [virtualscroll] locale must be one of "en", "ja"; got ...` (`cause` はエンジンの `RangeError`) |
1120
+ | 4 部品すべて | `labels` が `null`・非オブジェクト・素のオブジェクトでない・未知キー (撤去した `*AriaLabel` 名を含む)・空白や非文字列の値 | `RangeError: [period-slider] labels ...` (エンジン 7 キーの値は `RangeError: [virtualscroll] labels.<キー> must be a non-blank string; ...`) |
820
1121
  | `YearSelector` / `MonthSelector` / `DateSelector` | `value` と `initialDate` が共に未指定 | `RangeError: <コンポーネント名>: either \`value\` (controlled) or \`initialDate\` (uncontrolled) is required; ...` |
821
1122
  | `YearSelector` | 境界の欠落・矛盾、Date / 年 Props の不正値 | `RangeError` |
822
1123
  | `MonthSelector` | 境界の矛盾、`allowedMonths` を伴わない `variant="dropdown"` での境界の欠落、`allowedMonths` の要素が Invalid Date または `Date` でない (添字付きで報告)、Date / 年 Props の不正値 | ``RangeError: MonthSelector: `allowedMonths[1]` must be a valid Date, received ....`` 等 |
@@ -1009,7 +1310,7 @@ export function SelectorsExample() {
1009
1310
 
1010
1311
  #### `YearSelector` Props
1011
1312
 
1012
- 年を 1 年刻みで選択するコンポーネント。選択肢は解決後の上限年から下限年までの降順で、境界を跨いで広がることはありません。選択肢のテキストは 4 桁ゼロ埋めの年 (`2024`) で、`locale` 指定時は `Intl.DateTimeFormat` 書式 (`ja-JP` なら `2024年`)。`<option value>` は常に生の数値です。
1313
+ 年を 1 年刻みで選択するコンポーネント。`MonthSelector` / `DateSelector` と違って形態は 1 つだけで、`variant` を持ちません (常にドロップダウン + ステッパー)。選択肢は解決後の上限年から下限年までの降順で、境界を跨いで広がることはありません。選択肢のテキストは 4 桁ゼロ埋めの年 (`2024`) で、`formatLocale` 指定時は `Intl.DateTimeFormat` 書式 (`ja-JP` なら `2024年`)。`<option value>` は常に生の数値です。
1013
1314
 
1014
1315
  | プロパティ | 型 | 既定値 | 説明 |
1015
1316
  | :--- | :--- | :--- | :--- |
@@ -1024,10 +1325,10 @@ export function SelectorsExample() {
1024
1325
  | `className` | `string` | `""` | ルート要素の追加 CSS クラス |
1025
1326
  | `style` | `React.CSSProperties` | `undefined` | ルート要素のインラインスタイル |
1026
1327
  | `children` | `React.ReactNode` | `undefined` | ルート要素末尾へ追加描画する子要素 |
1027
- | `prevYearAriaLabel` | `string` | `"Previous year"` | 前年ボタンのアクセシブル名 |
1028
- | `nextYearAriaLabel` | `string` | `"Next year"` | 翌年ボタンのアクセシブル名 |
1029
- | `selectAriaLabel` | `string` | `"Year"` | 年セレクトのアクセシブル名 |
1030
- | `locale` | `string` | `undefined` | 選択肢テキストのロケール (BCP 47 言語タグ)。未指定は 4 桁ゼロ埋めの年、指定時は `Intl.DateTimeFormat` 書式。空文字列・不正タグ・非文字列は `RangeError` |
1328
+ | `locale` | `PeriodSliderLocale` | `undefined` (= `"en"`) | UI クローム言語。アクセシブル名 (`previousYear` / `nextYear` / `yearSelect`: `Previous year` / `Next year` / `Year`、`ja` では `前年` / `翌年` / `年`) を選ぶ |
1329
+ | `labels` | `PeriodSliderLabelOverrides` | `undefined` | カタログへのキー単位の上書き。読むのは `previousYear` / `nextYear` / `yearSelect` |
1330
+ | `formatLocale` | `string` | `undefined` | 選択肢テキストのロケール (BCP 47 言語タグ)。未指定は 4 桁ゼロ埋めの年、指定時は `Intl.DateTimeFormat` 書式。空文字列・不正タグ・非文字列は `RangeError` |
1331
+ | `formatOption` | `PeriodOptionFormatter` | `undefined` | 選択肢 (境界外の保持年を含む) と畳んだ表示のテキスト生成関数 (`formatLocale` より優先)。`(date, unit, scope) => string` で、`unit` は常に `"year"`、`scope` は常に `"period"`、`date` はその年の先頭月 1 日 (`yearStartMonth` 準拠)。このコンポーネントは単一形態でプレースホルダを持たず、境界外の保持年も書式化された実選択肢 (`disabled`) として並ぶ。返り値は機械可読値 (`<option value>` は常に生の数値)・`aria-label`・`onChange` の引数には届かない。参照比較で再描画を判定するため、利用側でメモ化する |
1031
1332
  | `unit` | — | — | **このコンポーネントが宣言していない名前です**。フックの `SelectorProps` をそのままスプレッドできるよう、受け取っても読まれず捨てられます (コンポーネントは必要な Props だけを名前で取り出すため、DOM へも届きません)。型にも宣言が無いので、JSX へ直接書くとコンパイルエラーになります (スプレッドは余剰プロパティ検査を受けないため通ります) |
1032
1333
  | `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
1334
 
@@ -1035,6 +1336,8 @@ export function SelectorsExample() {
1035
1336
 
1036
1337
  下限 (`minYear` または `minDate`) と上限 (`maxYear` または `maxDate`) は共に必須です。境界外の年を保持している間は、境界へ丸めず・`RangeError` も送出せず、その年を選択肢へ 1 件加えてそのまま表示します。ステッパーは移動先の年が境界内にある場合だけ有効です (境界の 1 つ外側では戻る側だけが有効、それより外では両方とも使用不可 (`aria-disabled="true"`、フォーカスは保持))。境界外の年が `onChange` へ渡ることはありません。
1037
1338
 
1339
+ DOM 契約: 保持年が境界外の間、ルート要素に `data-out-of-range="true"` が付与され、押し込まれた境界外の `<option>` は `disabled` になります (押せる範囲と発行できる範囲を一致させるためで、`emit` は境界外の年に対して `RangeError` を送出します)。`select.value` は**保持年のまま**で、`MonthSelector` / `DateSelector` のように `""` にはなりません — 選択中の年を畳んだ表示に出し続けるためです。
1340
+
1038
1341
  #### `MonthSelector` Props
1039
1342
 
1040
1343
  年月を 1 ヶ月刻みで選択するコンポーネント。
@@ -1055,10 +1358,10 @@ export function SelectorsExample() {
1055
1358
  | `className` | `string` | `""` | ルート要素の追加 CSS クラス |
1056
1359
  | `style` | `React.CSSProperties` | `undefined` | ルート要素のインラインスタイル |
1057
1360
  | `children` | `React.ReactNode` | `undefined` | ルート要素末尾へ追加描画する子要素 |
1058
- | `prevMonthAriaLabel` | `string` | `"Previous month"` | 前月ボタンのアクセシブル名 |
1059
- | `nextMonthAriaLabel` | `string` | `"Next month"` | 翌月ボタンのアクセシブル名 |
1060
- | `selectAriaLabel` | `string` | `"Month"` | 年月セレクトのアクセシブル名 |
1061
- | `locale` | `string` | `undefined` | 選択肢テキストのロケール (BCP 47 言語タグ)。未指定は ISO 8601 の `YYYY-MM`、指定時は `Intl.DateTimeFormat` 書式。`<input type="month">` および `<option value>` は常に `yyyy-MM`。空文字列・不正タグ・非文字列は `RangeError` |
1361
+ | `locale` | `PeriodSliderLocale` | `undefined` (= `"en"`) | UI クローム言語。アクセシブル名 (`previousMonth` / `nextMonth` / `monthSelect`: `Previous month` / `Next month` / `Month`、`ja` では `前月` / `翌月` / `年月`) を選ぶ |
1362
+ | `labels` | `PeriodSliderLabelOverrides` | `undefined` | カタログへのキー単位の上書き。読むのは `previousMonth` / `nextMonth` / `monthSelect` |
1363
+ | `formatLocale` | `string` | `undefined` | 選択肢テキストのロケール (BCP 47 言語タグ)。未指定は ISO 8601 の `YYYY-MM`、指定時は `Intl.DateTimeFormat` 書式。`<input type="month">` および `<option value>` は常に `yyyy-MM`。空文字列・不正タグ・非文字列は `RangeError` |
1364
+ | `formatOption` | `PeriodOptionFormatter` | `undefined` | 選択肢・プレースホルダ・畳んだ表示のテキスト生成関数 (`formatLocale` より優先)。`(date, unit, scope) => string` で、`unit` と `scope` はコンポーネントが与える。ネイティブ入力を使う `variant="date"` では履行できないため**呼び出しも行わない**。返り値は機械可読値・`aria-label`・`onChange` の引数には届かない。参照比較で再描画を判定するため、利用側でメモ化する |
1062
1365
  | `unit` | — | — | **このコンポーネントが宣言していない名前です**。フックの `SelectorProps` をそのままスプレッドできるよう、受け取っても読まれず捨てられます (コンポーネントは必要な Props だけを名前で取り出すため、DOM へも届きません)。型にも宣言が無いので、JSX へ直接書くとコンパイルエラーになります (スプレッドは余剰プロパティ検査を受けないため通ります) |
1063
1366
  | `yearStartMonth` | — | — | `unit` と同じく、このコンポーネントが宣言していない名前です。年の開始月を読むのは `YearSelector` だけで、月・日の格子には動かすべき年の境界がありません |
1064
1367
 
@@ -1074,10 +1377,11 @@ export function SelectorsExample() {
1074
1377
  DOM 契約: 現在値が選択可能集合の外にある場合、ルート要素に `data-out-of-range="true"` が付与されます。`variant="dropdown"` ではさらに `<select>` の先頭に現在値を表示する選択不可のプレースホルダ `<option value="">` が描画され (このとき `select.value === ""`)、`variant="date"` では `<input type="month">` が保持値をそのまま表示します。
1075
1378
 
1076
1379
  ```tsx
1077
- // データに存在する基準年月 (四半期の開始月) だけを選ばせる
1380
+ // データに存在する基準年月 (四半期の開始月) だけを選ばせる。上書きはモジュール直下で固定する
1381
+ const BASE_MONTH_LABELS = { monthSelect: "基準年月" } as const
1078
1382
  const allowedMonths = useMemo(() => baseMonths.map((yyyymm) => new Date(Math.trunc(yyyymm / 100), (yyyymm % 100) - 1, 1)), [baseMonths])
1079
1383
 
1080
- <MonthSelector variant="dropdown" value={currentMonth} allowedMonths={allowedMonths} selectAriaLabel="基準年月" onChange={(_date, yyyymm) => jumpTo(yyyymm)} />
1384
+ <MonthSelector variant="dropdown" value={currentMonth} allowedMonths={allowedMonths} labels={BASE_MONTH_LABELS} onChange={(_date, yyyymm) => jumpTo(yyyymm)} />
1081
1385
  ```
1082
1386
 
1083
1387
  #### `DateSelector` Props
@@ -1099,16 +1403,10 @@ const allowedMonths = useMemo(() => baseMonths.map((yyyymm) => new Date(Math.tru
1099
1403
  | `className` | `string` | `""` | ルート要素の追加 CSS クラス |
1100
1404
  | `style` | `React.CSSProperties` | `undefined` | ルート要素のインラインスタイル |
1101
1405
  | `children` | `React.ReactNode` | `undefined` | ルート要素末尾へ追加描画する子要素 |
1102
- | `prevDateAriaLabel` | `string` | `"Previous day"` | 前日ボタンのアクセシブル名 |
1103
- | `nextDateAriaLabel` | `string` | `"Next day"` | 翌日ボタンのアクセシブル名 |
1104
- | `selectAriaLabel` | `string` | `"Date"` | コンボボックス (とそのポップアップの listbox) および日付入力のアクセシブル名 |
1105
- | `yearAriaLabel` | `string` | `"Year"` | 年セレクトのアクセシブル名 (`variant="split-dropdown"` のみ) |
1106
- | `monthAriaLabel` | `string` | `"Month"` | 月セレクトのアクセシブル名 (`variant="split-dropdown"` のみ) |
1107
- | `dayAriaLabel` | `string` | `"Day"` | 日セレクトのアクセシブル名 (`variant="split-dropdown"` のみ) |
1108
- | `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` より優先) |
1406
+ | `locale` | `PeriodSliderLocale` | `undefined` (= `"en"`) | UI クローム言語。アクセシブル名 (`previousDay` / `nextDay` / `dateSelect`、`variant="split-dropdown"` では `splitYear` / `splitMonth` / `splitDay`) と、`variant="dropdown"` のポップアップに埋め込まれた `@aiquants/virtualscroll` のスクロールクロームの言語を選ぶ |
1407
+ | `labels` | `PeriodSliderLabelOverrides` | `undefined` | カタログへのキー単位の上書き。読むのは `previousDay` / `nextDay` / `dateSelect` / `splitYear` / `splitMonth` / `splitDay` と、`variant="dropdown"` ではエンジン 7 キー (内蔵 VirtualScroll へ転送) |
1408
+ | `formatLocale` | `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` |
1409
+ | `formatOption` | `PeriodOptionFormatter` | `undefined` | 選択肢・プレースホルダ・畳んだ表示のテキスト生成関数 (`formatLocale` より優先)。`(date, unit, scope) => string` で、`unit` と `scope` はコンポーネントが与える。ネイティブ入力を使う `variant="date"` では履行できないため**呼び出しも行わない**。返り値は機械可読値・`aria-label`・`onChange` の引数には届かない。参照比較で再描画を判定するため、利用側でメモ化する |
1112
1410
  | `unit` | — | — | **このコンポーネントが宣言していない名前です**。フックの `SelectorProps` をそのままスプレッドできるよう、受け取っても読まれず捨てられます (コンポーネントは必要な Props だけを名前で取り出すため、DOM へも届きません)。型にも宣言が無いので、JSX へ直接書くとコンパイルエラーになります (スプレッドは余剰プロパティ検査を受けないため通ります) |
1113
1411
  | `yearStartMonth` | — | — | `unit` と同じく、このコンポーネントが宣言していない名前です。年の開始月を読むのは `YearSelector` だけで、月・日の格子には動かすべき年の境界がありません |
1114
1412
 
@@ -1116,23 +1414,58 @@ const allowedMonths = useMemo(() => baseMonths.map((yyyymm) => new Date(Math.tru
1116
1414
 
1117
1415
  - `value` (制御) と `initialDate` (非制御) はいずれか一方が必須です。共に省略した場合は `RangeError` を送出し、選択日付を壁時計時刻から推定しません。
1118
1416
  - `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` で変更できます。
1417
+ - `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`) で、`formatLocale` または `formatOption` (`scope: "part"`) で変更できます。基準日は**その `<select>` の値だけ**から決まります (年は 1 月 1 日、月は当月 1 日、日は保持中の年月とその日)。
1418
+
1419
+ > **既知の制約 (非グレゴリオ暦)**: グレゴリオ暦の年・月を、年や月の境界が異なる暦 (和暦・ペルシア暦など) で描く以上、「その選択肢が確定する日付の呼び名」と「同じ `<select>` の選択肢どうしが区別できること」は同時には満たせません。本パッケージは**区別できること**を採ります。そのため `ja-JP-u-ca-japanese` では 2019 年の選択肢は常に 平成31年 (1 月 1 日の元号) で、5 月を保持したまま押すと確定するのは令和元年の日付です。逆に保持日を基準日へ混ぜると、`fa-IR` では 2020 年と 2021 年の選択肢が同じペルシア年 (`۱۳۹۹`) になります (実測)。確定日の呼び名が要る利用側は `formatOption` で自分の基準日を組んでください。
1420
+
1120
1421
  - `variant="date"`: 境界は任意です。指定した場合は `<input>` の `min` / `max` 属性へ反映されます。
1121
1422
  - ステッパーは離散指定時に隣接する選択可能日へ移動し、集合の端では使用不可 (`aria-disabled="true"`) になります。
1122
1423
  - 選択可能集合外の日付は丸められず破棄され、`onChange` は発火しません。
1123
1424
 
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">` が保持値をそのまま表示します。
1425
+ 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
1426
 
1126
1427
  `variant="dropdown"` の DOM 契約:
1127
1428
 
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"` で引けます。集合外の保持値は行にならず、操作要素の表示テキストとしてだけ現れます。
1129
- - ポップアップは `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 フォーカスは操作要素から離れません。
1429
+ - 操作要素は `<input type="text" readonly role="combobox">` で、`value` には人間が読むテキスト (`formatOption` 指定時はその返り値、未指定なら `formatLocale` 書式)、`data-value` には常に `yyyy-MM-dd` の機械可読値を持ちます。この `value` は選択中の行のテキストと必ず一致します (同じ関数値へ同じ形の引数を渡すため)。`aria-expanded` / `aria-haspopup="listbox"` / `aria-controls` (開いている間) / `aria-activedescendant` (アクティブ行が描画されている間) を持ち、`data-testid="period-slider-date-combobox"` で引けます。集合外の保持値は行にならず、操作要素の表示テキストとしてだけ現れます。
1430
+ - ポップアップは `document.body` へポータルされ (`data-testid="period-slider-date-popup"`)、開いた時点の操作要素の位置から解決した配色モードを `data-color-mode="light|dark"` として持ち、操作要素の下に開き、余地が無ければ上へ反転して視野内へ収まります。中の `role="listbox"` (アクセシブル名は `labels.dateSelect`、操作要素と同じ名前) が `role="option"` の行を持ち、各行は `aria-selected` / `aria-posinset` / `aria-setsize` (集合全体の件数) / `data-active` (キーボードの現在位置) を持ち、`data-testid="period-slider-date-option"` で引けます。DOM に存在する行は可視窓の分だけで、集合全体の件数は `aria-setsize` から読みます。
1431
+ - ポップアップには `role="listbox"` のほかに `@aiquants/virtualscroll` のスクロールバーが同居します (`role="scrollbar"`、つまみの `role="slider"`、そして `aria-label` を持つ矢印ボタン 2 つ)。矢印ボタンは常に `disabled` でタブ順にもキーボード操作にも現れませんが、アクセシビリティツリーには残ります。その名前は `locale` のカタログの `scrollUp` / `scrollDown` (`Scroll up` / `Scroll down`、`ja` では `上へスクロール` / `下へスクロール`) で、`labels` の同じキーで上書きできます (本パッケージが内蔵 VirtualScroll へ `locale` とエンジン 7 キーを転送します)。ポップアップに絞った `getByRole("button")` はこの 2 つに当たるため、行は `role="option"` か `data-testid` で引いてください。
1432
+ - キーボード: `ArrowDown` / `ArrowUp` (閉じていれば開く、開いていれば 1 行移動)、`Home` / `End` (先頭 = 最新日 / 末尾 = 最古日)、`PageDown` / `PageUp` (1 窓 = 7 行)、`Enter` (閉じていれば開く、開いていればアクティブ行を確定)、`Escape` (閉じる・発火しない)、`Tab` (閉じる)、数字と `-` / `/` / `.` (先頭一致入力。**表示書式に関わらず**先発グレゴリオ暦の `yyyy` / `yyyyMM` / `yyyyMMdd` として解釈し、走査せずに当該日へ飛ぶ。`formatOption` が非数字のテキストを返していても変わらない)。行の押下でも DOM フォーカスは操作要素から離れません。
1131
1433
  - 閉じる契機: 行の確定、`Escape`、`Tab`、操作要素からのフォーカス喪失、ポップアップ外の `pointerdown`。
1132
1434
  - ポップアップは `.period-slider` の外に立つため、`colorScheme` の変数 (`--aqps-*`) は届きません。選択中の行のアクセント色はパッケージ既定の色です。重なり順だけは `--aqps-z-date-popup` (既定 60) で差し替えられます。
1133
1435
  - ダークモードは `.dark` の位置に依存しません。ポップアップの祖先 (`document.body` の側) に `.dark` が無くても、**操作要素自身の位置**で解決したモードを `data-color-mode` として運ぶため、`.dark` を部分木へ限定したホストでも暗色で開きます。
1134
1436
 
1135
- `<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", …)` で読みます)。
1437
+ `<select>` を前提にしていたテストの移行: `select.value` → `combobox.getAttribute("data-value")`、`select.options` を数える → 開いてから `aria-setsize` を読む (`renderedRows.length` は可視窓の分だけ)、`selectOption(value)` → 開いて行を押すか、ISO の数字を打って `Enter`。Playwright なら `getByRole("combobox", { name: "Date" })` はそのまま解決します (`toHaveValue` は `formatLocale` 書式のテキストと比較されるので、ISO は `toHaveAttribute("data-value", …)` で読みます)。
1438
+
1439
+ ### 0.12 から 0.13 への移行 (`formatOption` への集約)
1440
+
1441
+ `DateSelector` の `formatYearOption` / `formatMonthOption` / `formatDayOption` は**削除されました**。別名も互換経路も残していません。3 セレクタ共通の `formatOption` 1 つへ移してください。
1442
+
1443
+ | 0.12 まで | 0.13 から |
1444
+ | :--- | :--- |
1445
+ | `formatYearOption={(year) => …}` | `formatOption` の `unit === "year" && scope === "part"` の枝 |
1446
+ | `formatMonthOption={(month) => …}` | 同じ関数の `unit === "month" && scope === "part"` の枝 |
1447
+ | `formatDayOption={(day) => …}` | 同じ関数の `unit === "day" && scope === "part"` の枝 |
1448
+
1449
+ 旧 Props が受け取っていたのは数値 1 つだけで、**その 4 月がどの年の 4 月なのかを知る術がありませんでした**。`formatOption` はその選択肢が確定する日付そのものを受け取るため、年度・四半期・和暦を引数だけから導けます。担当しない組は `formatOptionText` へ転送します。
1450
+
1451
+ ```tsx
1452
+ // 0.12
1453
+ <DateSelector variant="split-dropdown" locale="ja-JP" formatMonthOption={(month) => `${month}月`} {...rest} />
1454
+
1455
+ // 0.13 — 担当しない組は formatOptionText へ転送し、書式ロケールは Props ではなく第 4 引数で渡す (0.14 で Props 名は formatLocale)
1456
+ const formatOption: PeriodOptionFormatter = (date, unit, scope) =>
1457
+ unit === "month" && scope === "part" ? `${date.getMonth() + 1}月` : formatOptionText(date, unit, scope, "ja-JP")
1458
+
1459
+ // formatOption(new Date(2025, 3, 15), "month", "part") === "4月"
1460
+ // formatOption(new Date(2025, 3, 15), "day", "part") === "15日" (組み込みの段へ委譲。第 4 引数を省くと "15")
1461
+ <DateSelector variant="split-dropdown" formatOption={formatOption} {...rest} />
1462
+ ```
1463
+
1464
+ **書式ロケール (0.13 の `locale`、0.14 からの `formatLocale`) を指定していたホストは、同じタグを第 4 引数へ渡してください**。`formatOption` は書式ロケールより上の段なので、フォーマッタを渡した時点で Props の書式ロケールはどの表示テキストにも届かなくなります (残しても害はありませんが、表示は決めません)。転送時に第 4 引数を省くと、自分で描かない組だけが Intl の段からロケール非依存の ISO 8601 の段へ落ちます — 上の例では年が `2025年` → `2025`、日が `15日` → `15` となり、自分で描いた月だけが変わらないため、3 列のうち 2 列が黙って言語を変えます。書式ロケールを指定していなかったホストは、第 4 引数も省いたままで挙動が変わりません。
1465
+
1466
+ スライダー側の `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)` を渡してください。
1467
+
1468
+ `YearSelector` には DOM 契約が 2 つ加わりました。保持年が境界外のときルート要素が `data-out-of-range="true"` を持ち、押し込まれた境界外の選択肢が `disabled` になります (`select.value` は保持年のままで、従来どおりです)。`MonthSelector` / `DateSelector` が既に持っていた契約へ揃えたものなので、`data-out-of-range` を読む既存のテストは 3 セレクタで同じ形になります。
1136
1469
 
1137
1470
  ### React フック
1138
1471
 
@@ -1152,8 +1485,16 @@ DOM 契約: ルート要素は `data-variant="date|dropdown|split-dropdown"` を
1152
1485
  | `maxDate` | `Date` | セレクタの上限日付 |
1153
1486
  | `unit` | `PeriodSliderUnit` | セレクタの時間解像度単位。3 セレクタのいずれも宣言していない名前のため、スプレッドされても読まれません |
1154
1487
  | `yearStartMonth` | `number` | 1 年が始まる暦月 (0 始まり)。読むのは `YearSelector` だけです。型としては任意 (`yearStartMonth?: number`) ですが、4 つのフックは常に解決済みの値を載せます |
1488
+ | `formatLocale` | `string \| undefined` | フックへ与えた書式ロケール (BCP 47)。セレクタがレールと同じ表記で値を描くため |
1489
+ | `formatOption` | `PeriodOptionFormatter \| undefined` | フックへ与えた選択肢フォーマッタ |
1490
+ | `locale` | `PeriodSliderLocale \| undefined` | フックへ与えた UI クローム言語。セレクタがレールと同じ言語で操作要素を名乗るため |
1491
+ | `labels` | `PeriodSliderLabelOverrides \| undefined` | フックへ与えたラベル上書き (各セレクタは自分のキーだけを読む) |
1155
1492
 
1156
- `SelectorProps` は上記 6 つのみで、`locale` やアクセシブル名 Props は含みません。フックへ渡した `locale` は `sliderProps` にのみ転送されるため、セレクタの書式を揃える場合は `<MonthSelector {...startSelectorProps} locale="ja-JP" />` のように明示的に渡してください。
1493
+ フックへ 1 度与えた書式と言語はレール (`sliderProps`) と全セレクタの両方へ届きます。セレクタだけ別の値にしたい場合は、スプレッドの後ろで直接渡してください (後ろの指定が勝ちます)。
1494
+
1495
+ ```tsx
1496
+ <MonthSelector {...startSelectorProps} formatOption={formatFiscalPeriod} />
1497
+ ```
1157
1498
 
1158
1499
  #### `usePeriodSliderRange(options)`
1159
1500