@aiquants/period-slider 0.13.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 を渡せば任意書式になります。フォーマッタ Props はレールの 4 つもセレクタの `formatOption` も同一の `PeriodOptionFormatter` で、1 つのコールバックがパッケージの全テキスト面を賄います。`<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 (`PeriodSlider` の `formatLabel` / `formatMacroLabel` / `formatMicroLabel` / `formatAriaValueText`、`YearSelector` / `MonthSelector` / `DateSelector` の `formatOption`) が最優先、次に `locale`、最後に ISO 8601 既定です。この 5 つは**すべて同じ型 `PeriodOptionFormatter`** で、同一の関数値をどのスロットへも渡せます ([1 つのフォーマッタで全テキスト面を決める](#1-つのフォーマッタで全テキスト面を決める-formatoption))。四半期表記だけはこの 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 を渡してください。ただし `DateSelector variant="dropdown"` のポップアップにあるスクロールバーの矢印ボタン 2 つだけは例外で、`@aiquants/virtualscroll` が所有する固定の英語名 (`"Scroll up"` / `"Scroll down"`) のままです (翻訳する口がありません)。
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")}日`
@@ -168,10 +272,10 @@ type PeriodOptionFormatter = (date: Date, unit: PeriodSliderUnit, scope: PeriodO
168
272
 
169
273
  | `scope` | `unit="year"` | `unit="month"` | `unit="day"` |
170
274
  | :--- | :--- | :--- | :--- |
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日` |
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日` |
175
279
 
176
280
  面ごとの呼び出しは次の通りです。
177
281
 
@@ -196,11 +300,11 @@ type PeriodOptionFormatter = (date: Date, unit: PeriodSliderUnit, scope: PeriodO
196
300
 
197
301
  **フォーマッタが届かない先** (いずれも別の関数が別の経路で作ります):
198
302
 
199
- - すべての `aria-label` (◀▶・セレクト・コンボボックス・ポップアップの `listbox`)。これらを翻訳するには `selectAriaLabel` などのアクセシブル名 Props を渡してください。ただし `DateSelector variant="dropdown"` のポップアップは、この 4 種に加えてスクロールバーの矢印ボタン 2 つが `aria-label="Scroll up"` / `"Scroll down"` を持ちます。この 2 つは `@aiquants/virtualscroll` が所有する固定文字列で、**本パッケージのどの Props からも翻訳できません** (常に `disabled` のためタブ順には入らず、支援技術がポップアップ内を辿ったときに現れます)。
303
+ - すべての `aria-label` (◀▶・セレクト・コンボボックス・ポップアップの `listbox`、ポップアップのスクロールバーの矢印ボタン 2 つ)。これらは UI クローム言語の `locale` と `labels` が決めます ([Localization](#localization-ui-クローム言語-locale-と-labels))。矢印ボタンの名前 (`scrollUp` / `scrollDown`) は内蔵の `@aiquants/virtualscroll` へ転送され、常に `disabled` のためタブ順には入らず、支援技術がポップアップ内を辿ったときに現れます。
200
304
  - すべての機械可読値: `<option value>`、`variant="dropdown"` の `data-value`、`<input type="date">` / `<input type="month">` の `value` / `min` / `max`。
201
305
  - `onChange` が渡す引数。表示を変えても発行される `Date` は 1 ミリ秒も動きません。
202
306
 
203
- **呼び出しすら行わない面**: `MonthSelector variant="date"` と `DateSelector variant="date"` です。ネイティブ入力の表示テキストはブラウザが所有し、DOM 上に差し込む場所がありません (`locale` も同じ理由で届きません)。受け取って無視するだけで、例外にはなりません — `variant` を切り替えただけで落ちると、Props を 1 度設定して使い分ける形が壊れるためです。
307
+ **呼び出しすら行わない面**: `MonthSelector variant="date"` と `DateSelector variant="date"` です。ネイティブ入力の表示テキストはブラウザが所有し、DOM 上に差し込む場所がありません (`formatLocale` も同じ理由で届きません)。受け取って無視するだけで、例外にはなりません — `variant` を切り替えただけで落ちると、Props を 1 度設定して使い分ける形が壊れるためです。
204
308
 
205
309
  **先頭一致入力は表示書式に追従しません**。`DateSelector variant="dropdown"` の打鍵は、`formatOption` が何を描いていても**先発グレゴリオ暦の `yyyy[MM[dd]]` の数字列**として解釈されます。`20250309` と打てば 2025-03-09 の行へ飛び、その行の表示が `2024年度 第4四半期 (2025/03/09)` であっても変わりません。表示テキストの前方一致照合は選択肢総数に比例する費用になり、1 打鍵あたり定数時間という保証を壊すため採用していません。
206
310
 
@@ -220,17 +324,19 @@ formatOption(new Date(2025, 3, 1), "month", "period") // "2025/04"
220
324
  formatOption(new Date(2025, 3, 1), "month", "part") // "04月"
221
325
  ```
222
326
 
223
- #### フック利用時の `locale`
327
+ #### フック利用時の `formatLocale` / `locale` / `labels`
224
328
 
225
- フック (`usePeriodSliderRange` 等) へ渡した `locale` は `sliderProps` へ転送されますが、`SelectorProps` は `locale` を含みません。スライダーとセレクタの書式を揃えるには、セレクタ側へも明示的に渡してください。
329
+ フック (`usePeriodSliderRange` 等) へ渡した `formatLocale`・`formatOption`・`locale`・`labels` は `sliderProps` と全 `SelectorProps` の両方へ配られます。フックへ 1 度渡せば、レールと隣のセレクタは同じ書式・同じ言語で描かれます。セレクタだけ別の値にしたい場合は、スプレッドの後ろで直接渡してください (後ろの指定が勝ちます)。
226
330
 
227
331
  ```tsx
228
- <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} />
229
335
  ```
230
336
 
231
337
  #### 四半期表示 (暦四半期と年度四半期)
232
338
 
233
- 四半期だけは上の 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 で実測)。
234
340
 
235
341
  ```ts
236
342
  const formatter = new Intl.DateTimeFormat("ja-JP", { quarter: "long", year: "numeric" })
@@ -242,7 +348,7 @@ formatter.format(new Date(2025, 3, 1)) // "2025年" (四半期はどこにも現
242
348
  Intl.supportedValuesOf("unit").includes("quarter") // false
243
349
  ```
244
350
 
245
- 履行できない引数は置かない方針のため、四半期の 2 関数は `locale` を受け取りません。
351
+ 履行できない引数は置かない方針のため、四半期の 2 関数は `formatLocale` を受け取りません。
246
352
 
247
353
  | 関数 | シグネチャ | 返り値 |
248
354
  | :--- | :--- | :--- |
@@ -268,15 +374,15 @@ const formatFiscalQuarterJa = (date: Date): string => {
268
374
  formatFiscalQuarterJa(new Date(2026, 0, 15)) // "2025年度 第4四半期"
269
375
  ```
270
376
 
271
- 年の部分だけは `locale` に従わせられます。年ラベルと同じ公開経路 (`normalizeDateByUnit` を通した `formatLabel("year", ...)`) を使うと、`Q` の綴りだけがロケール非依存のまま残ります。
377
+ 年の部分だけは `formatLocale` に従わせられます。年ラベルと同じ公開経路 (`normalizeDateByUnit` を通した `formatLabel("year", ...)`) を使うと、`Q` の綴りだけがロケール非依存のまま残ります。
272
378
 
273
379
  ```tsx
274
380
  import { formatLabel, normalizeDateByUnit, resolveQuarter } from "@aiquants/period-slider"
275
381
 
276
- const formatQuarterWithLocale = (date: Date, locale?: string): string => {
382
+ const formatQuarterWithLocale = (date: Date, formatLocale?: string): string => {
277
383
  const { quarter } = resolveQuarter(date, FISCAL_YEAR_START_MONTH)
278
384
  // 年の切り出しを自前で書くと、年ラベルと四半期ラベルが年について食い違い得る
279
- 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)
280
386
  return `${year} Q${quarter}`
281
387
  }
282
388
 
@@ -533,7 +639,7 @@ export function VernierPointExample() {
533
639
 
534
640
  時点形態の契約は次のとおりです。
535
641
 
536
- - ミクロレールのつまみは 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` は読みません)。
537
643
  - ミクロ側の接続バー (`period-slider-connect-micro`) は描きません。幅を持たない選択を帯で表すと「満タンの期間」に見え、掴める帯まで生えてしまうためです。マクロ窓の帯は従来どおり残ります。
538
644
  - `aria-valuemin` / `aria-valuemax` はミクロレールの両端 (マクロ窓で切り出した範囲) で、`aria-valuenow` は選択時点そのものです。期間形態のように相手のつまみで塞がれることはありません。
539
645
  - キーボードは `mode="point"` と同じく左右対称です。`←` `→` で ±1 ミクロ単位、`PageUp` / `PageDown` で ±5、`Home` / `End` でレールの両端へ届きます。動けない押下はコールバックを発火しません。
@@ -754,8 +860,10 @@ export function FiscalQuarterLabelExample() {
754
860
  | `hideConnectBar` | `boolean` | `false` | 範囲選択バー (ハイライト) を非表示にし、独立 2 点選択 UI として利用 |
755
861
  | `showTicks` | `boolean` | `false` | 離散モード時のトラック上の目盛線の表示有無 |
756
862
  | `showStepper` | `boolean` | `true` | ステッパーボタンの表示有無 (水平時は左右、垂直時は上下を指す矢印) |
757
- | `formatLabel` | `PeriodOptionFormatter` | `undefined` | 日付ラベル・ツールチップのカスタム表示文字列生成関数。`locale` より優先される。3 セレクタの `formatOption` と同じ型のため、同一の関数値を両方へ渡せる (引数は `(date, unit, scope)` で `scope` は常に `"period"`。`(date) => string` も従来どおり代入可能)。ノギスでは `formatMacroLabel` / `formatMicroLabel` 双方の既定値でもあるため、ここへ四半期フォーマッタを渡すと**マクロ側にも同じ関数が流れ**、マクロラベルが常に Q1 になる。ノギスで四半期を出すなら `formatMicroLabel` にだけ渡す |
758
- | `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 キー |
759
867
  | `disabled` | `boolean` | `false` | スライダーの無効化・非活性表示 |
760
868
  | `debounceMs` | `number` | `0` | 変更コールバック呼び出しのデバウンス時間 (ミリ秒)。`0` は即時発火 |
761
869
  | `colorScheme` | `PeriodSliderColorScheme` | `"blue-rose"` | カラーテーマプリセット (`"blue-rose"`, `"indigo-amber"`, `"teal-emerald"`, `"violet-fuchsia"`, `"slate-sky"`, `"monochrome"`) |
@@ -825,18 +933,25 @@ export function FiscalQuarterLabelExample() {
825
933
 
826
934
  期間側の 3 Props と時点側の 3 Props は**相互排他**です。型では互いを `never` として宣言しているため同時指定はコンパイルエラーになり、JavaScript からの同時指定は描画時に `RangeError` で拒否します (黙ってどちらかを優先すると、渡したはずのコールバックが永久に鳴らない状態になるため)。
827
935
 
828
- #### アクセシビリティ 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 が決めます。
829
951
 
830
952
  | プロパティ | 型 | 既定値 | 説明 |
831
953
  | :--- | :--- | :--- | :--- |
832
- | `lowerAriaLabel` | `string` | `"Range start"` (vernier 時 `"Micro range start"`) | 下限つまみのアクセシブル名 |
833
- | `upperAriaLabel` | `string` | `"Range end"` (vernier 時 `"Micro range end"`) | 上限つまみのアクセシブル名 |
834
- | `pointAriaLabel` | `string` | `"Selected date"` (vernier 時点形態では `"Micro selected date"`) | 単一選択つまみのアクセシブル名 (`mode="point"`、およびノギスのミクロ時点形態) |
835
- | `macroLowerAriaLabel` | `string` | `"Macro range start"` | マクロ下限つまみのアクセシブル名 (`mode="vernier"` のみ) |
836
- | `macroUpperAriaLabel` | `string` | `"Macro range end"` | マクロ上限つまみのアクセシブル名 (`mode="vernier"` のみ) |
837
- | `decreaseAriaLabel` | `string` | `"Decrease"` | 値を `minDate` 方向へ 1 単位動かすステッパーボタンのアクセシブル名 (水平時は左端の左向き矢印、垂直時は下端の下向き矢印) |
838
- | `increaseAriaLabel` | `string` | `"Increase"` | 値を `maxDate` 方向へ 1 単位動かすステッパーボタンのアクセシブル名 (水平時は右端の右向き矢印、垂直時は上端の上向き矢印) |
839
- | `formatAriaValueText` | `PeriodOptionFormatter` | `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` 呼び出し**から組み立ててください (省略すれば可視ラベルと一字一句同じ文字列が読み上げられます) |
840
955
 
841
956
  ステッパーの 2 つの名称は配置ではなく値への作用で定義されています。同じボタンが水平レイアウトでは左、垂直レイアウトでは下に立つため、位置で命名すると意味が反転するからです。
842
957
 
@@ -864,7 +979,7 @@ DOM 要素の特定は CSS クラス名ではなく `data-*` 属性で行いま
864
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` と直交する |
865
980
  | `[data-testid="period-slider-track"]` | トラック (`data-vernier-orientation` でノギスのレール配置を判別) |
866
981
  | `[data-range-area]` | 範囲領域 (ルート要素の最初の子)。`Shift` + ホイールを受ける矩形そのもので、何も描かず `pointer-events: none` のためヒットテストにも答えない |
867
- | `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 でスライダー全体を無効にしたときだけ付く |
868
983
  | `[data-testid="period-slider-connect"]` | 接続バー。ノギスでは `period-slider-connect-macro` / `period-slider-connect-micro` の 2 本 (ミクロが時点の形態では `period-slider-connect-micro` を描かない) |
869
984
  | `[data-testid="period-slider-tick"]` | 目盛線と離散レールの候補点。ノギスモードでは `data-tick-scale="macro" \| "micro"` が併記され上下段を判別できる。塗りはパッケージのスタイルシートが 1 か所で持つ (レールの境界線と同じインク) |
870
985
  | `[data-testid="period-slider-hairline"]` | ノギスの読み取りの針 (`showHairline` が真のときだけ描かれる)。線の中心がつまみの中心 = 値そのものに揃う |
@@ -886,20 +1001,20 @@ DOM 要素の特定は CSS クラス名ではなく `data-*` 属性で行いま
886
1001
  export type PeriodOptionScope = "period" | "part"
887
1002
  export type PeriodOptionFormatter = (date: Date, unit: PeriodSliderUnit, scope: PeriodOptionScope) => string
888
1003
 
889
- export declare const formatOptionText: (date: Date, unit: PeriodSliderUnit, scope: PeriodOptionScope, locale?: string) => string
1004
+ export declare const formatOptionText: (date: Date, unit: PeriodSliderUnit, scope: PeriodOptionScope, formatLocale?: string) => string
890
1005
  ```
891
1006
 
892
1007
  - `PeriodOptionFormatter` は、4 つのスライダー Props (`formatLabel` / `formatMacroLabel` / `formatMicroLabel` / `formatAriaValueText`) と 3 セレクタの `formatOption` に**共通の 1 つの型**です。面ごとの契約は [1 つのフォーマッタで全テキスト面を決める](#1-つのフォーマッタで全テキスト面を決める-formatoption) にまとめてあります。
893
1008
  - **引数を減らした関数は今まで通り渡せます**。`(date: Date) => string` も `(date: Date, unit: PeriodSliderUnit) => string` も代入可能で、逆向き (3 引数の関数を 1 引数のスロットへ) だけがコンパイルエラーになります。`formatQuarterLabel` は `(Date, number) => string` で第 2 引数が単位ではなく `yearStartMonth` のため、`formatOption` へ**直接は渡せません** (型が拒否します)。四半期は上のレシピのように `resolveQuarter` から組み立ててください。
894
1009
  - `PeriodOptionScope` は `"period"` (その操作要素の値そのもの) と `"part"` (`variant="split-dropdown"` が 3 つ並べる部位の 1 つ) の 2 値です。組み込みの段がこの 2 つを別の Intl オプション集合で描き分けているため、`unit` だけでは同じ `"month"` が「年月全体」と「月の部位」のどちらを指すのか決まりません。
895
- - `formatOptionText` は**組み込みの 2 段そのもの**です (`locale` 指定時は `Intl.DateTimeFormat`、未指定時はロケール非依存の ISO 8601)。第 1 段を担当しない (`unit`, `scope`) の組は、この関数へそのまま転送してください。引数順がコールバックと同一なので逐語転送できます。
1010
+ - `formatOptionText` は**組み込みの 2 段そのもの**です (`formatLocale` 指定時は `Intl.DateTimeFormat`、未指定時はロケール非依存の ISO 8601)。第 1 段を担当しない (`unit`, `scope`) の組は、この関数へそのまま転送してください。引数順がコールバックと同一なので逐語転送できます。
896
1011
  - **「`undefined` を返したら既定」という形は採っていません**。それは代替値連鎖であり、本パッケージが排している形です。返り値は常に文字列で、**空文字列も合法**です (無効な日付に対する `formatLabel` の仕様値と同じ)。
897
1012
  - `date` が未指定・Invalid Date のときは `""` を返します (`formatLabel` と同じ約束)。
898
1013
  - `unit` が `"year"` / `"month"` / `"day"` 以外、`scope` が `"period"` / `"part"` 以外の場合は `RangeError` を送出し、メッセージは関数自身を名指しします (`formatOptionText: scope must be "period" or "part" (received: label)`)。フォーマッタ Props は型検査を受けますが、この関数は公開の入口であり JavaScript からも引数が届くためです。
899
1014
 
900
- `formatOptionText(date, unit, scope, locale)` の出力 (`date` は `2025-04-15`):
1015
+ `formatOptionText(date, unit, scope, formatLocale)` の出力 (`date` は `2025-04-15`):
901
1016
 
902
- | `unit` | `scope: "period"` (`locale` 未指定) | `scope: "period"` (`"ja-JP"`) | `scope: "part"` (`locale` 未指定) | `scope: "part"` (`"ja-JP"`) |
1017
+ | `unit` | `scope: "period"` (`formatLocale` 未指定) | `scope: "period"` (`"ja-JP"`) | `scope: "part"` (`formatLocale` 未指定) | `scope: "part"` (`"ja-JP"`) |
903
1018
  | :--- | :--- | :--- | :--- | :--- |
904
1019
  | `"year"` | `2025` | `2025年` | `2025` | `2025年` |
905
1020
  | `"month"` | `2025-04` | `2025/04` | `04` | `04月` |
@@ -998,9 +1113,11 @@ yearStartMonth=9 2,2,2,3,3,3,4,4,4,1,1,1
998
1113
  | `PeriodSlider` (`vernier`) | 指定されたミクロ選択が `microUnit` の解像度で `[minDate, maxDate]` の外 | `RangeError: PeriodSlider: <プロパティ名> must lie within [minDate, maxDate] (...)` (`macroRange` は定義域をはみ出してよい。レールが定義域と積を取り、通知はクランプ済みの値を配るため) |
999
1114
  | `PeriodSlider` | `allowedDates` の全要素が `[minDate, maxDate]` 外 | `RangeError: getSortedAllowedDates: every allowedDates entry falls outside [minDate, maxDate] (...)` |
1000
1115
  | `usePeriodSliderRange` / `usePeriodSliderPoint` / `useVernierSliderRange` / `useVernierSliderPoint` | 境界・初期値の欠落、Invalid Date、逆転 | `RangeError: <フック名>: ...` |
1001
- | `PeriodSlider` | `locale` が空文字列・構造として不正な BCP 47 タグ・非文字列 | `RangeError: PeriodSlider: locale must be a valid BCP 47 language tag (received: ...)` |
1002
- | `DateSelector` | 同上 | `RangeError: DateSelector: "locale" must be a valid BCP 47 language tag (received ...)` |
1003
- | `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; ...`) |
1004
1121
  | `YearSelector` / `MonthSelector` / `DateSelector` | `value` と `initialDate` が共に未指定 | `RangeError: <コンポーネント名>: either \`value\` (controlled) or \`initialDate\` (uncontrolled) is required; ...` |
1005
1122
  | `YearSelector` | 境界の欠落・矛盾、Date / 年 Props の不正値 | `RangeError` |
1006
1123
  | `MonthSelector` | 境界の矛盾、`allowedMonths` を伴わない `variant="dropdown"` での境界の欠落、`allowedMonths` の要素が Invalid Date または `Date` でない (添字付きで報告)、Date / 年 Props の不正値 | ``RangeError: MonthSelector: `allowedMonths[1]` must be a valid Date, received ....`` 等 |
@@ -1193,7 +1310,7 @@ export function SelectorsExample() {
1193
1310
 
1194
1311
  #### `YearSelector` Props
1195
1312
 
1196
- 年を 1 年刻みで選択するコンポーネント。`MonthSelector` / `DateSelector` と違って形態は 1 つだけで、`variant` を持ちません (常にドロップダウン + ステッパー)。選択肢は解決後の上限年から下限年までの降順で、境界を跨いで広がることはありません。選択肢のテキストは 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>` は常に生の数値です。
1197
1314
 
1198
1315
  | プロパティ | 型 | 既定値 | 説明 |
1199
1316
  | :--- | :--- | :--- | :--- |
@@ -1208,11 +1325,10 @@ export function SelectorsExample() {
1208
1325
  | `className` | `string` | `""` | ルート要素の追加 CSS クラス |
1209
1326
  | `style` | `React.CSSProperties` | `undefined` | ルート要素のインラインスタイル |
1210
1327
  | `children` | `React.ReactNode` | `undefined` | ルート要素末尾へ追加描画する子要素 |
1211
- | `prevYearAriaLabel` | `string` | `"Previous year"` | 前年ボタンのアクセシブル名 |
1212
- | `nextYearAriaLabel` | `string` | `"Next year"` | 翌年ボタンのアクセシブル名 |
1213
- | `selectAriaLabel` | `string` | `"Year"` | 年セレクトのアクセシブル名 |
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` の引数には届かない。参照比較で再描画を判定するため、利用側でメモ化する |
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` の引数には届かない。参照比較で再描画を判定するため、利用側でメモ化する |
1216
1332
  | `unit` | — | — | **このコンポーネントが宣言していない名前です**。フックの `SelectorProps` をそのままスプレッドできるよう、受け取っても読まれず捨てられます (コンポーネントは必要な Props だけを名前で取り出すため、DOM へも届きません)。型にも宣言が無いので、JSX へ直接書くとコンパイルエラーになります (スプレッドは余剰プロパティ検査を受けないため通ります) |
1217
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` (暦年) |
1218
1334
 
@@ -1242,11 +1358,10 @@ DOM 契約: 保持年が境界外の間、ルート要素に `data-out-of-range=
1242
1358
  | `className` | `string` | `""` | ルート要素の追加 CSS クラス |
1243
1359
  | `style` | `React.CSSProperties` | `undefined` | ルート要素のインラインスタイル |
1244
1360
  | `children` | `React.ReactNode` | `undefined` | ルート要素末尾へ追加描画する子要素 |
1245
- | `prevMonthAriaLabel` | `string` | `"Previous month"` | 前月ボタンのアクセシブル名 |
1246
- | `nextMonthAriaLabel` | `string` | `"Next month"` | 翌月ボタンのアクセシブル名 |
1247
- | `selectAriaLabel` | `string` | `"Month"` | 年月セレクトのアクセシブル名 |
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` の引数には届かない。参照比較で再描画を判定するため、利用側でメモ化する |
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` の引数には届かない。参照比較で再描画を判定するため、利用側でメモ化する |
1250
1365
  | `unit` | — | — | **このコンポーネントが宣言していない名前です**。フックの `SelectorProps` をそのままスプレッドできるよう、受け取っても読まれず捨てられます (コンポーネントは必要な Props だけを名前で取り出すため、DOM へも届きません)。型にも宣言が無いので、JSX へ直接書くとコンパイルエラーになります (スプレッドは余剰プロパティ検査を受けないため通ります) |
1251
1366
  | `yearStartMonth` | — | — | `unit` と同じく、このコンポーネントが宣言していない名前です。年の開始月を読むのは `YearSelector` だけで、月・日の格子には動かすべき年の境界がありません |
1252
1367
 
@@ -1262,10 +1377,11 @@ DOM 契約: 保持年が境界外の間、ルート要素に `data-out-of-range=
1262
1377
  DOM 契約: 現在値が選択可能集合の外にある場合、ルート要素に `data-out-of-range="true"` が付与されます。`variant="dropdown"` ではさらに `<select>` の先頭に現在値を表示する選択不可のプレースホルダ `<option value="">` が描画され (このとき `select.value === ""`)、`variant="date"` では `<input type="month">` が保持値をそのまま表示します。
1263
1378
 
1264
1379
  ```tsx
1265
- // データに存在する基準年月 (四半期の開始月) だけを選ばせる
1380
+ // データに存在する基準年月 (四半期の開始月) だけを選ばせる。上書きはモジュール直下で固定する
1381
+ const BASE_MONTH_LABELS = { monthSelect: "基準年月" } as const
1266
1382
  const allowedMonths = useMemo(() => baseMonths.map((yyyymm) => new Date(Math.trunc(yyyymm / 100), (yyyymm % 100) - 1, 1)), [baseMonths])
1267
1383
 
1268
- <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)} />
1269
1385
  ```
1270
1386
 
1271
1387
  #### `DateSelector` Props
@@ -1287,14 +1403,10 @@ const allowedMonths = useMemo(() => baseMonths.map((yyyymm) => new Date(Math.tru
1287
1403
  | `className` | `string` | `""` | ルート要素の追加 CSS クラス |
1288
1404
  | `style` | `React.CSSProperties` | `undefined` | ルート要素のインラインスタイル |
1289
1405
  | `children` | `React.ReactNode` | `undefined` | ルート要素末尾へ追加描画する子要素 |
1290
- | `prevDateAriaLabel` | `string` | `"Previous day"` | 前日ボタンのアクセシブル名 |
1291
- | `nextDateAriaLabel` | `string` | `"Next day"` | 翌日ボタンのアクセシブル名 |
1292
- | `selectAriaLabel` | `string` | `"Date"` | コンボボックス (とそのポップアップの listbox) および日付入力のアクセシブル名 |
1293
- | `yearAriaLabel` | `string` | `"Year"` | 年セレクトのアクセシブル名 (`variant="split-dropdown"` のみ) |
1294
- | `monthAriaLabel` | `string` | `"Month"` | 月セレクトのアクセシブル名 (`variant="split-dropdown"` のみ) |
1295
- | `dayAriaLabel` | `string` | `"Day"` | 日セレクトのアクセシブル名 (`variant="split-dropdown"` のみ) |
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` |
1297
- | `formatOption` | `PeriodOptionFormatter` | `undefined` | 選択肢・プレースホルダ・畳んだ表示のテキスト生成関数 (`locale` より優先)。`(date, unit, scope) => string` で、`unit` と `scope` はコンポーネントが与える。ネイティブ入力を使う `variant="date"` では履行できないため**呼び出しも行わない**。返り値は機械可読値・`aria-label`・`onChange` の引数には届かない。参照比較で再描画を判定するため、利用側でメモ化する |
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` の引数には届かない。参照比較で再描画を判定するため、利用側でメモ化する |
1298
1410
  | `unit` | — | — | **このコンポーネントが宣言していない名前です**。フックの `SelectorProps` をそのままスプレッドできるよう、受け取っても読まれず捨てられます (コンポーネントは必要な Props だけを名前で取り出すため、DOM へも届きません)。型にも宣言が無いので、JSX へ直接書くとコンパイルエラーになります (スプレッドは余剰プロパティ検査を受けないため通ります) |
1299
1411
  | `yearStartMonth` | — | — | `unit` と同じく、このコンポーネントが宣言していない名前です。年の開始月を読むのは `YearSelector` だけで、月・日の格子には動かすべき年の境界がありません |
1300
1412
 
@@ -1302,7 +1414,7 @@ const allowedMonths = useMemo(() => baseMonths.map((yyyymm) => new Date(Math.tru
1302
1414
 
1303
1415
  - `value` (制御) と `initialDate` (非制御) はいずれか一方が必須です。共に省略した場合は `RangeError` を送出し、選択日付を壁時計時刻から推定しません。
1304
1416
  - `variant="dropdown"`: `allowedDates` を指定しない場合、下限と上限の双方が必須です。選択肢は `minDate` 〜 `maxDate` の全日 (降順) ですが、配列としては実体化しません。件数は境界から算出し、行の日付・テキストは描画時に導出し、DOM に存在するのはポップアップの可視行だけです。境界を動かす費用は連続範囲で O(1)、`allowedDates` 指定時は二分探索の O(log n) で、100 年分 (36,525 日) の定義域でも 1 か月分と同じ費用で動きます。ポインタ移動ごとに境界を動かすホスト (ノギスの連動セレクタなど) でも、この変種を日単位のまま使えます。
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 日、日は保持中の年月とその日)。
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 日、日は保持中の年月とその日)。
1306
1418
 
1307
1419
  > **既知の制約 (非グレゴリオ暦)**: グレゴリオ暦の年・月を、年や月の境界が異なる暦 (和暦・ペルシア暦など) で描く以上、「その選択肢が確定する日付の呼び名」と「同じ `<select>` の選択肢どうしが区別できること」は同時には満たせません。本パッケージは**区別できること**を採ります。そのため `ja-JP-u-ca-japanese` では 2019 年の選択肢は常に 平成31年 (1 月 1 日の元号) で、5 月を保持したまま押すと確定するのは令和元年の日付です。逆に保持日を基準日へ混ぜると、`fa-IR` では 2020 年と 2021 年の選択肢が同じペルシア年 (`۱۳۹۹`) になります (実測)。確定日の呼び名が要る利用側は `formatOption` で自分の基準日を組んでください。
1308
1420
 
@@ -1314,15 +1426,15 @@ DOM 契約: ルート要素は `data-variant="date|dropdown|split-dropdown"` を
1314
1426
 
1315
1427
  `variant="dropdown"` の DOM 契約:
1316
1428
 
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"` で引けます。集合外の保持値は行にならず、操作要素の表示テキストとしてだけ現れます。
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` から読みます。
1319
- - ポップアップには `role="listbox"` のほかに `@aiquants/virtualscroll` のスクロールバーが同居します (`role="scrollbar"`、つまみの `role="slider"`、そして `aria-label="Scroll up"` / `"Scroll down"` を持つ矢印ボタン 2 つ)。矢印ボタンは常に `disabled` でタブ順にもキーボード操作にも現れませんが、アクセシビリティツリーには残り、**そのアクセシブル名は固定の英語で本パッケージからは翻訳できません**。ポップアップに絞った `getByRole("button")` はこの 2 つに当たるため、行は `role="option"` か `data-testid` で引いてください。
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` で引いてください。
1320
1432
  - キーボード: `ArrowDown` / `ArrowUp` (閉じていれば開く、開いていれば 1 行移動)、`Home` / `End` (先頭 = 最新日 / 末尾 = 最古日)、`PageDown` / `PageUp` (1 窓 = 7 行)、`Enter` (閉じていれば開く、開いていればアクティブ行を確定)、`Escape` (閉じる・発火しない)、`Tab` (閉じる)、数字と `-` / `/` / `.` (先頭一致入力。**表示書式に関わらず**先発グレゴリオ暦の `yyyy` / `yyyyMM` / `yyyyMMdd` として解釈し、走査せずに当該日へ飛ぶ。`formatOption` が非数字のテキストを返していても変わらない)。行の押下でも DOM フォーカスは操作要素から離れません。
1321
1433
  - 閉じる契機: 行の確定、`Escape`、`Tab`、操作要素からのフォーカス喪失、ポップアップ外の `pointerdown`。
1322
1434
  - ポップアップは `.period-slider` の外に立つため、`colorScheme` の変数 (`--aqps-*`) は届きません。選択中の行のアクセント色はパッケージ既定の色です。重なり順だけは `--aqps-z-date-popup` (既定 60) で差し替えられます。
1323
1435
  - ダークモードは `.dark` の位置に依存しません。ポップアップの祖先 (`document.body` の側) に `.dark` が無くても、**操作要素自身の位置**で解決したモードを `data-color-mode` として運ぶため、`.dark` を部分木へ限定したホストでも暗色で開きます。
1324
1436
 
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", …)` で読みます)。
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", …)` で読みます)。
1326
1438
 
1327
1439
  ### 0.12 から 0.13 への移行 (`formatOption` への集約)
1328
1440
 
@@ -1340,7 +1452,7 @@ DOM 契約: ルート要素は `data-variant="date|dropdown|split-dropdown"` を
1340
1452
  // 0.12
1341
1453
  <DateSelector variant="split-dropdown" locale="ja-JP" formatMonthOption={(month) => `${month}月`} {...rest} />
1342
1454
 
1343
- // 0.13 — 担当しない組は formatOptionText へ転送し、locale は Props ではなく第 4 引数で渡す
1455
+ // 0.13 — 担当しない組は formatOptionText へ転送し、書式ロケールは Props ではなく第 4 引数で渡す (0.14 で Props 名は formatLocale)
1344
1456
  const formatOption: PeriodOptionFormatter = (date, unit, scope) =>
1345
1457
  unit === "month" && scope === "part" ? `${date.getMonth() + 1}月` : formatOptionText(date, unit, scope, "ja-JP")
1346
1458
 
@@ -1349,7 +1461,7 @@ const formatOption: PeriodOptionFormatter = (date, unit, scope) =>
1349
1461
  <DateSelector variant="split-dropdown" formatOption={formatOption} {...rest} />
1350
1462
  ```
1351
1463
 
1352
- **`locale` を指定していたホストは、同じタグを第 4 引数へ渡してください**。`formatOption` は `locale` より上の段なので、フォーマッタを渡した時点で Props の `locale` はどの表示テキストにも届かなくなります (残しても害はありませんが、表示は決めません)。転送時に第 4 引数を省くと、自分で描かない組だけが Intl の段からロケール非依存の ISO 8601 の段へ落ちます — 上の例では年が `2025年` → `2025`、日が `15日` → `15` となり、自分で描いた月だけが変わらないため、3 列のうち 2 列が黙って言語を変えます。`locale` を指定していなかったホストは、第 4 引数も省いたままで挙動が変わりません。
1464
+ **書式ロケール (0.13 の `locale`、0.14 からの `formatLocale`) を指定していたホストは、同じタグを第 4 引数へ渡してください**。`formatOption` は書式ロケールより上の段なので、フォーマッタを渡した時点で Props の書式ロケールはどの表示テキストにも届かなくなります (残しても害はありませんが、表示は決めません)。転送時に第 4 引数を省くと、自分で描かない組だけが Intl の段からロケール非依存の ISO 8601 の段へ落ちます — 上の例では年が `2025年` → `2025`、日が `15日` → `15` となり、自分で描いた月だけが変わらないため、3 列のうち 2 列が黙って言語を変えます。書式ロケールを指定していなかったホストは、第 4 引数も省いたままで挙動が変わりません。
1353
1465
 
1354
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)` を渡してください。
1355
1467
 
@@ -1373,11 +1485,15 @@ const formatOption: PeriodOptionFormatter = (date, unit, scope) =>
1373
1485
  | `maxDate` | `Date` | セレクタの上限日付 |
1374
1486
  | `unit` | `PeriodSliderUnit` | セレクタの時間解像度単位。3 セレクタのいずれも宣言していない名前のため、スプレッドされても読まれません |
1375
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` | フックへ与えたラベル上書き (各セレクタは自分のキーだけを読む) |
1376
1492
 
1377
- `SelectorProps` は上記 6 つのみで、`locale`・`formatOption`・アクセシブル名 Props は含みません。表示に関する Props を 1 つも運ばない設計で、状態管理フックへ表示言語や書式を持ち込まないためです。フックへ渡した `locale` は `sliderProps` にのみ転送されるため、レールとセレクタの書式を揃える場合は、スプレッドの隣へ明示的に渡してください。
1493
+ フックへ 1 度与えた書式と言語はレール (`sliderProps`) と全セレクタの両方へ届きます。セレクタだけ別の値にしたい場合は、スプレッドの後ろで直接渡してください (後ろの指定が勝ちます)。
1378
1494
 
1379
1495
  ```tsx
1380
- <MonthSelector {...startSelectorProps} locale="ja-JP" formatOption={formatFiscalPeriod} />
1496
+ <MonthSelector {...startSelectorProps} formatOption={formatFiscalPeriod} />
1381
1497
  ```
1382
1498
 
1383
1499
  #### `usePeriodSliderRange(options)`