@aiquants/period-slider 0.2.0 → 0.3.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 +465 -85
- package/dist/DateSelector.d.ts +43 -14
- package/dist/DateSelector.d.ts.map +1 -1
- package/dist/MonthSelector.d.ts +26 -9
- package/dist/MonthSelector.d.ts.map +1 -1
- package/dist/PeriodSlider.d.ts +257 -125
- package/dist/PeriodSlider.d.ts.map +1 -1
- package/dist/YearSelector.d.ts +26 -9
- package/dist/YearSelector.d.ts.map +1 -1
- package/dist/index.cjs +1 -1
- package/dist/index.d.cts +28 -0
- package/dist/index.d.ts +10 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1642 -1382
- package/dist/styles/period-slider.css +1 -1
- package/dist/styles/period-slider.standalone.css +1 -1
- package/dist/usePeriodSlider.d.ts +83 -78
- package/dist/usePeriodSlider.d.ts.map +1 -1
- package/package.json +17 -10
- package/src/DateSelector.tsx +495 -194
- package/src/MonthSelector.tsx +258 -137
- package/src/PeriodSlider.tsx +1109 -572
- package/src/YearSelector.tsx +174 -55
- package/src/index.ts +13 -0
- package/src/styles/period-slider.css +41 -7
- package/src/usePeriodSlider.ts +466 -277
- package/dist/period-slider.css +0 -1
package/README.md
CHANGED
|
@@ -5,47 +5,53 @@
|
|
|
5
5
|
|
|
6
6
|
## 概要
|
|
7
7
|
|
|
8
|
-
`@aiquants/period-slider` は、年・月・日単位での期間範囲選択 (Range) および単一時点選択 (Point) に対応した `PeriodSlider
|
|
8
|
+
`@aiquants/period-slider` は、年・月・日単位での期間範囲選択 (Range) および単一時点選択 (Point) に対応した `PeriodSlider`、および年・年月・年月日のステッパー付き入力コンポーネント (`YearSelector`, `MonthSelector`, `DateSelector`) を提供します。
|
|
9
9
|
|
|
10
10
|
外部依存ライブラリ (nouislider 等) を排した純粋な React / SVG 実装であり、滑らかなドラッグ操作、数学的幾何計算による近接ラベルの重なり防止自動斜めエフェクト、上限/下限交差時のアクティブハイライト自動追従、および WAI-ARIA に準拠したキーボードアクセシビリティを備えています。
|
|
11
11
|
|
|
12
|
+
必須の入力 (定義域境界・初期値) が欠落または不正な場合、本パッケージは既定値や壁時計時刻で代替せず、すべて `RangeError` で即座に失敗します。詳細は [実行時バリデーション](#実行時バリデーション-fail-fast) を参照してください。
|
|
13
|
+
|
|
14
|
+
組み込みの表示文字列はロケール中立です。アクセシブル名の既定値はすべて英語 (`"Range start"` 等)、日付ラベル・選択肢テキストの既定値はロケール非依存の ISO 8601 表記 (`2025` / `2025-01` / `2025-01-15`) で、`locale` (BCP 47 言語タグ) を渡した時のみ `Intl.DateTimeFormat` 書式へ切り替わります。詳細は [ロケールと表示書式](#ロケールと表示書式-locale) を参照してください。
|
|
15
|
+
|
|
12
16
|
## 特徴
|
|
13
17
|
|
|
14
18
|
- **柔軟な時間単位**: `year`, `month`, `day` の 3 つの単位をサポート。
|
|
15
19
|
- **3 つの操作モード**:
|
|
16
20
|
- `range`: 開始時期と終了時期の 2 つのつまみと連結バーで範囲を選択。
|
|
17
21
|
- `point`: 単一のつまみで時点を選択。
|
|
18
|
-
- `vernier`:
|
|
19
|
-
-
|
|
22
|
+
- `vernier`: ノギス (Vernier Caliper) 型 2 段スケール一体型モード。全体期間からマクロ表示窓を上側で指定し、その拡大スケールを下側で精密選択。上下反転、台形プロジェクション光、2 段スケールの目盛線、精密ヘアライン針を完備。
|
|
23
|
+
- **半円直径 (±8px) 完全充填幾何配置**: 半円ノブ底面 (16px) を完全に満たす一体型選択ゲージ。
|
|
20
24
|
- **上下段つまみ交差反転スワップ (Crossover)**: マクロ・ミクロ双方で上限下限の追い越し反転をサポート。
|
|
21
25
|
- **弾性復元 (Push-and-Restore)**: マクロ縮小時の一時クランプ後、拡大時に記憶された初期ミクロ選択範囲へ自動復元。
|
|
22
|
-
- **マクロ・ミクロ完全独立設定**:
|
|
23
|
-
- **中央 1 px スリット空隙**: 上段 3.5 px、中央空隙 1.0 px、下段 3.5 px
|
|
24
|
-
- **SVG ベクター幾何学半円ドーム (`VernierKnobSvg`)**:
|
|
25
|
-
- **上下反転時のセマンティック配色直交分離**:
|
|
26
|
+
- **マクロ・ミクロ完全独立設定**: マクロ (年) × ミクロ (日) やマクロ (年) × ミクロ (月) などの異単位構成、個別離散スナップ (`macroIsDiscrete` / `microIsDiscrete` と併用)、個別カスタムフォーマッタに対応。
|
|
27
|
+
- **中央 1 px スリット空隙**: 上段 3.5 px、中央空隙 1.0 px、下段 3.5 px (`calc(50% - 0.5px)`) の独立レール設計による高い視認性と数学的均等分割。
|
|
28
|
+
- **SVG ベクター幾何学半円ドーム (`VernierKnobSvg`)**: 数学的真円弧コマンド (`shapeRendering="geometricPrecision"`) による、環境非依存で一切のガタつき・階段状ジャギーのない滑らかな真円弧。
|
|
29
|
+
- **上下反転時のセマンティック配色直交分離**: 配置位置 (`data-vernier-pos`) と配色 (`data-handle-type`) を CSS セレクタレベルで直交分離し、反転時もマクロ針・ノブグロー・目盛線・台形プロジェクション光が完璧に追従。
|
|
26
30
|
- **トラック厚み 8px 偶数設計**: サブピクセル滲みを完全に解消し、上下対称の半円つまみ配置と 3.5px+1.0px+3.5px マクロ・ミクロ塗り分けを実現。
|
|
27
|
-
- **離散日付対応 (`allowedDates`)**:
|
|
31
|
+
- **離散日付対応 (`allowedDates`)**: 実データが存在する日付のみをスナップ対象にする離散モードを内蔵。`[minDate, maxDate]` 外の要素は到達不能なため除外され、全要素が範囲外の場合は `RangeError` で失敗。
|
|
28
32
|
- **ラベル配置と重なり防止自動傾斜**:
|
|
29
33
|
- `labelPosition`: 上側 (`"top"`, 既定) または下側 (`"bottom"`) のラベル表示位置を選択可能。
|
|
30
|
-
- `
|
|
31
|
-
-
|
|
34
|
+
- `autoSlantLabels`: 2 つのラベルが近接した際に Smootherstep 補間により 0° 〜 90° に滑らかに自動傾斜し、テキストの重なりを数学的に完全防止。回転時もラベル下端がトラック中心から常に 10px (つまみ上端から 2px) の統一された高さを維持。
|
|
35
|
+
- 衝突判定はラベルの実測幅 (`ResizeObserver` が返すボーダーボックス幅) のみを用います。単位や書式から推定した定数を使わないため、`locale`・`formatLabel`・ホストのフォントを変えても判定はずれません。実測値が得られるまでラベルは傾斜せず直立します。
|
|
36
|
+
- 操作中 (ドラッグ中) のラベル・つまみを前面 (`z-index`) に強調表示。
|
|
32
37
|
- **上限/下限交差 (クロスオーバー) の動的ハイライト追従**:
|
|
33
38
|
- レンジドラッグ中につまみが相手側アンカーを超えて上限と下限が入れ替わった際、現在ポインターで操作している側のつまみへアクティブ状態 (`[data-active="true"]`、スケール縮小+ブルーグロー・波紋) がリアルタイムに自動スワップ。
|
|
34
39
|
- **充実した日付セレクタ**:
|
|
35
40
|
- `YearSelector`: ドロップダウンと ◀▶ ステッパーで年を選択。
|
|
36
|
-
- `MonthSelector`: カレンダー入力 /
|
|
37
|
-
- `DateSelector`:
|
|
41
|
+
- `MonthSelector`: カレンダー入力 (`variant="date"`, 既定) / ドロップダウン (`variant="dropdown"`) 対応の月セレクタ。
|
|
42
|
+
- `DateSelector`: 日付入力 (`variant="date"`, 既定)、単一セレクトボックス (`variant="dropdown"`)、年月日の 3 分割セレクト (`variant="split-dropdown"`) に対応。
|
|
38
43
|
- **カラーテーマ・メリハリ対比 & ダークモード**:
|
|
39
|
-
- `colorScheme`: 6
|
|
40
|
-
- ノギス 2
|
|
41
|
-
-
|
|
44
|
+
- `colorScheme`: 6 系統のカラーパレット (`"blue-rose"` [既定], `"indigo-amber"`, `"teal-emerald"`, `"violet-fuchsia"`, `"slate-sky"`, `"monochrome"`) をサポート。
|
|
45
|
+
- ノギス 2 段スケールにおける広域マクロ (青系) と確定ミクロ (赤系) の明確なメリハリ対比、および境界を結ぶ台形プロジェクション光の動的 2 色グラデーション。
|
|
46
|
+
- トラック、ノブ、目盛線、ツールチップ、セレクタ群 (`YearSelector`, `MonthSelector`, `DateSelector`) を含む Tailwind `.dark` クラスによるダークモード完全対応。
|
|
42
47
|
- **垂直レイアウト対応 (`isVertical`)**:
|
|
43
48
|
- `isVertical={true}` によりダッシュボードのサイドバーや狭小パネルに最適な垂直指向スライダーを提供。
|
|
44
49
|
- つまみ左側から厳密に 8.00px の数学的クリアランスでツールチップラベルを配置。
|
|
45
50
|
- **数学的 8.00px 均一クリアランス & ノギスツールチップ色分け**:
|
|
46
|
-
-
|
|
47
|
-
-
|
|
48
|
-
-
|
|
51
|
+
- 垂直スライダーおよびノギス (Vernier) モードにおいて、つまみ端面からラベルまでの距離を厳密に 8.00px に統一。
|
|
52
|
+
- ノギスモードではマクロツールチップ (`--aqps-macro-color`) とミクロツールチップ (`--aqps-micro-color`) がセマンティックに色分けされ、上下段の対応関係が一目で判別可能。
|
|
53
|
+
- **ロケール中立な表示文字列**: 組み込み文字列に特定の言語を持ちません。アクセシブル名の既定値は英語、日付表記の既定値は ISO 8601 で、`locale` を渡せば `Intl.DateTimeFormat` 書式、フォーマッタ Props を渡せば任意書式になります。`<input>` の `value` と `<option value>` は常に ISO 8601 (または生の数値) で、`locale` の影響を受けません。
|
|
54
|
+
- **高いアクセシビリティ**: WAI-ARIA `slider` ロール、キーボード操作 (矢印キー, PageUp/Down, Home/End) 完全準拠 (Vernier ノギスハンドル含む)。
|
|
49
55
|
|
|
50
56
|
## インストール
|
|
51
57
|
|
|
@@ -57,14 +63,79 @@ pnpm add @aiquants/period-slider
|
|
|
57
63
|
|
|
58
64
|
### スタイル読み込み
|
|
59
65
|
|
|
66
|
+
本パッケージは 2 種類の CSS 成果物を出力します。ホスト環境に応じてどちらか一方のみを読み込んでください。
|
|
67
|
+
|
|
60
68
|
```typescript
|
|
61
|
-
// Tailwind CSS v4
|
|
69
|
+
// A. Tailwind CSS v4 プロジェクトの場合: パッケージ固有のコンポーネントクラスのみを読み込む
|
|
62
70
|
import "@aiquants/period-slider/styles/period-slider.css"
|
|
63
71
|
|
|
64
|
-
//
|
|
72
|
+
// B. 非 Tailwind (スタンドアロン) 環境の場合: 自己完結 CSS を読み込む
|
|
65
73
|
import "@aiquants/period-slider/styles/period-slider.standalone.css"
|
|
66
74
|
```
|
|
67
75
|
|
|
76
|
+
| 成果物 | 含まれるもの | 用途 |
|
|
77
|
+
| :--- | :--- | :--- |
|
|
78
|
+
| `styles/period-slider.css` | 手書きコンポーネントクラス (`.period-slider-*`) のみ。テーマ変数・ユーティリティ・preflight は含まない | ホスト側に Tailwind CSS v4 ビルドがある場合 |
|
|
79
|
+
| `styles/period-slider.standalone.css` | テーマ変数・ユーティリティを同梱した自己完結スタイル | ホストに Tailwind ビルドが無い場合 |
|
|
80
|
+
|
|
81
|
+
> [!IMPORTANT]
|
|
82
|
+
> A を選ぶ場合、ホスト側の Tailwind エントリ CSS に次の 2 行が必須です。
|
|
83
|
+
>
|
|
84
|
+
> ```css
|
|
85
|
+
> @import "tailwindcss";
|
|
86
|
+
> @source "../node_modules/@aiquants/period-slider/dist";
|
|
87
|
+
> @custom-variant dark (&:where(.dark, .dark *));
|
|
88
|
+
> ```
|
|
89
|
+
>
|
|
90
|
+
> - `@source`: Tailwind CSS v4 は既定で `node_modules` を走査しないため、これが無いとパッケージが出力するユーティリティクラス (`inline-flex`, `rounded-full`, `bg-blue-500`, `dark:*` 等) が一切生成されず、コンポーネントが未装飾のテキストとして描画されます。
|
|
91
|
+
> - `@custom-variant dark`: Tailwind CSS v4 の `dark:` は既定で `@media (prefers-color-scheme: dark)` にコンパイルされます。これが無いと `.dark` クラスでは切り替わらず、手書きクラスで配色を持つスライダー本体だけが暗転し、`dark:` ユーティリティで配色を持つ 3 セレクタ (`YearSelector`, `MonthSelector`, `DateSelector`) が明色のまま取り残されます。
|
|
92
|
+
>
|
|
93
|
+
> B のスタンドアロン CSS は自己完結のため `@source` 指定は不要ですが、ホストの Tailwind ビルドと混在させないでください (ユーティリティ層が二重定義になります)。
|
|
94
|
+
|
|
95
|
+
### ロケールと表示書式 (`locale`)
|
|
96
|
+
|
|
97
|
+
`PeriodSlider`・`YearSelector`・`MonthSelector`・`DateSelector` はいずれも `locale?: string` (BCP 47 言語タグ) を受け取ります。
|
|
98
|
+
|
|
99
|
+
| `locale` | 組み込みの日付表記 |
|
|
100
|
+
| :--- | :--- |
|
|
101
|
+
| 未指定 (既定) | ロケール非依存の ISO 8601 表記。`unit="year"` は `2025`、`unit="month"` は `2025-01`、`unit="day"` は `2025-01-15` (年は 4 桁ゼロ埋め) |
|
|
102
|
+
| 指定 | `Intl.DateTimeFormat(locale, options)` の出力。`options` は単位ごとに `year: { year: "numeric" }`、`month: { year: "numeric", month: "2-digit" }`、`day: { year: "numeric", month: "2-digit", day: "2-digit" }` |
|
|
103
|
+
|
|
104
|
+
ISO 8601 はフォールバックではなく、本パッケージの仕様上の既定値です。英語などの自然言語表記を既定にすると汎用パッケージへ 1 つの言語を焼き付けることになり、`Intl` の出力は ICU / Node のバージョン間で変化するためです。
|
|
105
|
+
|
|
106
|
+
- **優先順位**: フォーマッタ Props (`formatLabel` / `formatMacroLabel` / `formatMicroLabel` / `formatAriaValueText`、`DateSelector` の `formatYearOption` / `formatMonthOption` / `formatDayOption`) が最優先、次に `locale`、最後に ISO 8601 既定です。
|
|
107
|
+
- **地域化されるのは人間が読むテキストのみ**: `<input type="date">` の `value` / `min` / `max` は常に `yyyy-MM-dd`、`<input type="month">` は常に `yyyy-MM`、`<option value>` は常に ISO 文字列 (`yyyy-MM-dd` / `yyyy-MM`) または生の数値 (年セレクト、`variant="split-dropdown"` の 3 セレクト) です。
|
|
108
|
+
- **アクセシブル名は `locale` では変わりません**: ボタン・セレクト・つまみの名称は英語既定のままです。翻訳するには `lowerAriaLabel` / `decreaseAriaLabel` / `selectAriaLabel` などのアクセシブル名 Props を渡してください。
|
|
109
|
+
- **Fail Fast**: 空文字列や `Intl.DateTimeFormat` が受理しない値 (`"en_US"`、非文字列等) を渡した場合、既定の ISO へ黙って戻さず `RangeError` を送出します (メッセージは [実行時バリデーション](#実行時バリデーション-fail-fast) 参照)。`"xx-YY"` のように構造として妥当なタグは、対応する翻訳データが無くても受理されます。
|
|
110
|
+
|
|
111
|
+
```tsx
|
|
112
|
+
// 既定 (locale 省略): ラベルは "2024-03-10"
|
|
113
|
+
<PeriodSlider mode="point" unit="day" minDate={minDate} maxDate={maxDate} value={date} onChangePoint={setDate} />
|
|
114
|
+
|
|
115
|
+
// locale 指定: ラベルは ja-JP ロケールの "2024/03/10"
|
|
116
|
+
<PeriodSlider mode="point" unit="day" locale="ja-JP" minDate={minDate} maxDate={maxDate} value={date} onChangePoint={setDate} />
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
#### 日本語 UI での表示
|
|
120
|
+
|
|
121
|
+
`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 のため、表示書式はブラウザのロケール設定が決めます)。
|
|
122
|
+
|
|
123
|
+
`2024年01月15日` のような独自表記が必要な場合は、`locale` ではなくフォーマッタ Props を渡してください。
|
|
124
|
+
|
|
125
|
+
```tsx
|
|
126
|
+
const formatJapaneseDay = (date: Date): string => `${date.getFullYear()}年${String(date.getMonth() + 1).padStart(2, "0")}月${String(date.getDate()).padStart(2, "0")}日`
|
|
127
|
+
|
|
128
|
+
<PeriodSlider mode="point" unit="day" formatLabel={formatJapaneseDay} minDate={minDate} maxDate={maxDate} value={date} onChangePoint={setDate} />
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
#### フック利用時の `locale`
|
|
132
|
+
|
|
133
|
+
フック (`usePeriodSliderRange` 等) へ渡した `locale` は `sliderProps` へ転送されますが、`SelectorProps` は `locale` を含みません。スライダーとセレクタの書式を揃えるには、セレクタ側へも明示的に渡してください。
|
|
134
|
+
|
|
135
|
+
```tsx
|
|
136
|
+
<MonthSelector {...startSelectorProps} locale="ja-JP" />
|
|
137
|
+
```
|
|
138
|
+
|
|
68
139
|
### ゼロ・ボイラープレート React フック連携 (`usePeriodSliderRange`)
|
|
69
140
|
|
|
70
141
|
ステート管理・単一要素ミューテータ・セレクタ連動を 1 行で完結できます。
|
|
@@ -110,9 +181,9 @@ export function Example() {
|
|
|
110
181
|
minDate={new Date(2020, 0, 1)}
|
|
111
182
|
maxDate={new Date(2025, 11, 1)}
|
|
112
183
|
range={range}
|
|
113
|
-
|
|
184
|
+
onChangeRange={(lower, upper) => setRange([lower, upper])}
|
|
114
185
|
labelPosition="top"
|
|
115
|
-
|
|
186
|
+
autoSlantLabels={true}
|
|
116
187
|
/>
|
|
117
188
|
)
|
|
118
189
|
}
|
|
@@ -133,7 +204,7 @@ export function PointExample() {
|
|
|
133
204
|
unit="month"
|
|
134
205
|
minDate={new Date(2020, 0, 1)}
|
|
135
206
|
maxDate={new Date(2025, 11, 1)}
|
|
136
|
-
|
|
207
|
+
value={date}
|
|
137
208
|
labelPosition="top"
|
|
138
209
|
onChangePoint={(nextDate) => setDate(nextDate)}
|
|
139
210
|
/>
|
|
@@ -143,19 +214,19 @@ export function PointExample() {
|
|
|
143
214
|
|
|
144
215
|
### PeriodSlider (Vernier ノギス 2 段スケール一体型モード)
|
|
145
216
|
|
|
146
|
-
|
|
217
|
+
広域期間 (例: 数年〜十数年) の中から極小期間 (例: 数日〜数ヶ月) を精密に選択する場合に適した、ノギス型 2 段スケール一体型スライダーです。上側 (マクロ) で全体期間の表示窓を定め、下側 (ミクロ) でその表示窓を 100% に拡大した精密な選択を行います。
|
|
147
218
|
|
|
148
219
|
```tsx
|
|
149
220
|
import { PeriodSlider } from "@aiquants/period-slider"
|
|
150
221
|
import { useState } from "react"
|
|
151
222
|
|
|
152
223
|
export function VernierExample() {
|
|
153
|
-
// マクロ側の表示窓 (2023年〜2025年)
|
|
224
|
+
// マクロ側の表示窓 (2023 年〜2025 年)
|
|
154
225
|
const [macroRange, setMacroRange] = useState<[Date, Date]>([
|
|
155
226
|
new Date(2023, 0, 1),
|
|
156
227
|
new Date(2025, 0, 1),
|
|
157
228
|
])
|
|
158
|
-
// ミクロ側の最終確定選択期間 (2023年6月〜11月)
|
|
229
|
+
// ミクロ側の最終確定選択期間 (2023 年 6 月〜11 月)
|
|
159
230
|
const [microRange, setMicroRange] = useState<[Date, Date]>([
|
|
160
231
|
new Date(2023, 5, 1),
|
|
161
232
|
new Date(2023, 10, 1),
|
|
@@ -169,9 +240,8 @@ export function VernierExample() {
|
|
|
169
240
|
maxDate={new Date(2026, 11, 31)}
|
|
170
241
|
macroRange={macroRange}
|
|
171
242
|
onChangeMacroRange={(lower, upper) => setMacroRange([lower, upper])}
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
onChangeRange={(lower, upper) => setMicroRange([lower, upper])}
|
|
243
|
+
microRange={microRange}
|
|
244
|
+
onChangeMicroRange={(lower, upper) => setMicroRange([lower, upper])}
|
|
175
245
|
vernierOrientation="macro-top"
|
|
176
246
|
showVernierProjection={true}
|
|
177
247
|
showVernierTicks={true}
|
|
@@ -183,7 +253,16 @@ export function VernierExample() {
|
|
|
183
253
|
|
|
184
254
|
### PeriodSlider (垂直レイアウト)
|
|
185
255
|
|
|
186
|
-
`isVertical={true}`
|
|
256
|
+
`isVertical={true}` を指定することで、縦向き (下部が最小日付、上部が最大日付) のスライダーとして表示できます。
|
|
257
|
+
|
|
258
|
+
> [!NOTE]
|
|
259
|
+
> トラック自身は `h-48` (12rem) の固定高さを持ちます。親要素に指定した高さはスライダー周囲の余白のみを決め、トラック長には反映されません。12rem 以外の高さにする場合は、ホスト側 CSS でユーティリティ層より後に解決される規則を与えてください。
|
|
260
|
+
>
|
|
261
|
+
> ```css
|
|
262
|
+
> .period-slider-track[data-orientation="vertical"] {
|
|
263
|
+
> height: 24rem;
|
|
264
|
+
> }
|
|
265
|
+
> ```
|
|
187
266
|
|
|
188
267
|
```tsx
|
|
189
268
|
import { PeriodSlider } from "@aiquants/period-slider"
|
|
@@ -196,15 +275,14 @@ export function VerticalExample() {
|
|
|
196
275
|
])
|
|
197
276
|
|
|
198
277
|
return (
|
|
199
|
-
<div className="
|
|
278
|
+
<div className="flex items-center justify-center p-4">
|
|
200
279
|
<PeriodSlider
|
|
201
280
|
mode="range"
|
|
202
281
|
unit="month"
|
|
203
282
|
isVertical={true}
|
|
204
283
|
minDate={new Date(2024, 0, 1)}
|
|
205
284
|
maxDate={new Date(2024, 11, 31)}
|
|
206
|
-
|
|
207
|
-
upperDate={range[1]}
|
|
285
|
+
range={range}
|
|
208
286
|
onChangeRange={(lower, upper) => setRange([lower, upper])}
|
|
209
287
|
/>
|
|
210
288
|
</div>
|
|
@@ -214,7 +292,7 @@ export function VerticalExample() {
|
|
|
214
292
|
|
|
215
293
|
### PeriodSlider (離散日付スナップ & 目盛表示)
|
|
216
294
|
|
|
217
|
-
|
|
295
|
+
実データが存在する離散日付のみを選択対象とし、トラック上に目盛線を表示します。`allowedDates` を指定する場合も `minDate` / `maxDate` は必須で、範囲外の要素は除外されます。
|
|
218
296
|
|
|
219
297
|
```tsx
|
|
220
298
|
import { PeriodSlider } from "@aiquants/period-slider"
|
|
@@ -235,10 +313,12 @@ export function DiscreteExample() {
|
|
|
235
313
|
<PeriodSlider
|
|
236
314
|
mode="point"
|
|
237
315
|
unit="day"
|
|
316
|
+
minDate={new Date(2024, 0, 1)}
|
|
317
|
+
maxDate={new Date(2024, 11, 31)}
|
|
238
318
|
allowedDates={discreteDates}
|
|
239
319
|
showTicks={true}
|
|
240
320
|
snapMode="time"
|
|
241
|
-
|
|
321
|
+
value={point}
|
|
242
322
|
onChangePoint={(d) => setPoint(d)}
|
|
243
323
|
/>
|
|
244
324
|
)
|
|
@@ -271,8 +351,7 @@ export function CustomLabelExample() {
|
|
|
271
351
|
unit="month"
|
|
272
352
|
minDate={new Date(2023, 0, 1)}
|
|
273
353
|
maxDate={new Date(2025, 11, 31)}
|
|
274
|
-
|
|
275
|
-
upperDate={range[1]}
|
|
354
|
+
range={range}
|
|
276
355
|
hideConnectBar={true}
|
|
277
356
|
formatLabel={formatQuarter}
|
|
278
357
|
tooltipStyle="balloon"
|
|
@@ -282,46 +361,142 @@ export function CustomLabelExample() {
|
|
|
282
361
|
}
|
|
283
362
|
```
|
|
284
363
|
|
|
285
|
-
### PeriodSlider
|
|
364
|
+
### PeriodSlider Props
|
|
365
|
+
|
|
366
|
+
#### 全モード共通 Props
|
|
286
367
|
|
|
287
368
|
| プロパティ | 型 | 既定値 | 説明 |
|
|
288
369
|
| :--- | :--- | :--- | :--- |
|
|
289
370
|
| `mode` | `"range" \| "point" \| "vernier"` | (必須) | 操作モード (`range`: 2 点範囲選択, `point`: 1 点選択, `vernier`: ノギス 2 段スケール一体型) |
|
|
290
371
|
| `unit` | `"year" \| "month" \| "day"` | (必須) | 時間解像度単位 |
|
|
291
|
-
| `minDate` | `Date` | (必須) |
|
|
292
|
-
| `maxDate` | `Date` | (必須) |
|
|
293
|
-
| `
|
|
294
|
-
| `
|
|
295
|
-
| `valueDate` | `Date` | (point 必須) | ポイント選択時の日付 |
|
|
296
|
-
| `macroRange` | `[Date, Date]` | (vernier 必須) | ノギスモード時のマクロ側表示窓 [開始, 終了] |
|
|
297
|
-
| `macroUnit` | `"year" \| "month" \| "day"` | `unit` | ノギスモード時のマクロ側時間解像度単位 (異単位構成用) |
|
|
298
|
-
| `microUnit` | `"year" \| "month" \| "day"` | `unit` | ノギスモード時のミクロ側時間解像度単位 (異単位構成用) |
|
|
299
|
-
| `formatMacroLabel` | `(date: Date) => string` | `undefined` | ノギスマクロ側ラベル・ツールチップのカスタム表示文字列生成関数 |
|
|
300
|
-
| `formatMicroLabel` | `(date: Date) => string` | `undefined` | ノギスミクロ側ラベル・ツールチップのカスタム表示文字列生成関数 |
|
|
301
|
-
| `macroAllowedDates` | `Date[]` | `undefined` | ノギスマクロ側の離散スナップ対象日付配列 |
|
|
302
|
-
| `microAllowedDates` | `Date[]` | `undefined` | ノギスミクロ側の離散スナップ対象日付配列 |
|
|
303
|
-
| `vernierOrientation` | `"macro-top" \| "macro-bottom"` | `"macro-top"` | ノギスの上下配置 (上マクロ/下ミクロ または 上ミクロ/下マクロ反転) |
|
|
304
|
-
| `showVernierProjection` | `boolean` | `true` | マクロ窓からミクロ全幅へ広がる半透明台形プロジェクション光の表示有無 |
|
|
305
|
-
| `showVernierTicks` | `boolean` | `true` | マクロレールおよびミクロレール上のアダプティブ目盛線の表示有無 |
|
|
306
|
-
| `showHairline` | `boolean` | `true` | 半円つまみ先端の 1px 精密ヘアライン針の表示有無 |
|
|
307
|
-
| `adaptiveExpand` | `boolean` | `false` | ノギスモード時のズーム展開アニメーション有無 |
|
|
308
|
-
| `allowedDates` | `Date[]` | `undefined` | 離散スナップ対象日付配列 (指定時はこの日付のみにスナップ) |
|
|
309
|
-
| `snapMode` | `"index" \| "time"` | `"time"` | 離散スナップ時の計算方式 (`"time"`: 時間距離, `"index"`: 配列インデックス均等) |
|
|
372
|
+
| `minDate` | `Date` | (必須) | 選択可能最小日付。欠落・Invalid Date は `RangeError` |
|
|
373
|
+
| `maxDate` | `Date` | (必須) | 選択可能最大日付。`minDate` より厳密に後であること。欠落・Invalid Date・逆転は `RangeError` |
|
|
374
|
+
| `allowedDates` | `Date[]` | `undefined` | 離散スナップ対象日付配列 (指定時はこの日付のみにスナップ)。`[minDate, maxDate]` 外の要素は除外され、全要素が範囲外なら `RangeError` |
|
|
375
|
+
| `snapMode` | `"index" \| "time"` | `"index"` | 離散スナップ時の配置方式 (`"index"`: 配列インデックス均等, `"time"`: 実時間比例)。実時間軸やチャートと位置を揃える場合は `"time"` を明示指定 |
|
|
310
376
|
| `labelPosition` | `"top" \| "bottom"` | `"top"` | 日付ラベルの表示位置 (スライダーの上側または下側) |
|
|
311
|
-
| `autoSlantLabels` | `boolean` | `true` | 近接時にラベルを斜め〜90
|
|
312
|
-
| `tooltipStyle` | `"always" \| "hover" \| "balloon"` | `"
|
|
377
|
+
| `autoSlantLabels` | `boolean` | `true` | 近接時にラベルを斜め〜90° に自動傾斜させて重なりを防止 |
|
|
378
|
+
| `tooltipStyle` | `"always" \| "hover" \| "balloon"` | `"always"` | ツールチップの表示スタイル (`"always"`: 常時, `"hover"`: ポインター操作時, `"balloon"`: 吹き出し型) |
|
|
313
379
|
| `isVertical` | `boolean` | `false` | 垂直スライダー表示の有効化 |
|
|
314
380
|
| `hideConnectBar` | `boolean` | `false` | 範囲選択バー (ハイライト) を非表示にし、独立 2 点選択 UI として利用 |
|
|
315
|
-
| `showTicks` | `boolean` | `false` |
|
|
381
|
+
| `showTicks` | `boolean` | `false` | 離散モード時のトラック上の目盛線の表示有無 |
|
|
316
382
|
| `showStepper` | `boolean` | `true` | ◀▶ ステッパーボタンの表示有無 (垂直時は ▲▼) |
|
|
317
|
-
| `formatLabel` | `(date: Date) => string` | `undefined` |
|
|
383
|
+
| `formatLabel` | `(date: Date) => string` | `undefined` | 日付ラベル・ツールチップのカスタム表示文字列生成関数。`locale` より優先される |
|
|
384
|
+
| `locale` | `string` | `undefined` | 組み込み日付表記のロケール (BCP 47 言語タグ)。未指定はロケール非依存の ISO 8601 (`2025` / `2025-01` / `2025-01-15`)、指定時は `Intl.DateTimeFormat` 書式。空文字列・不正タグ・非文字列は `RangeError` |
|
|
318
385
|
| `disabled` | `boolean` | `false` | スライダーの無効化・非活性表示 |
|
|
319
|
-
| `debounceMs` | `number` | `0` |
|
|
386
|
+
| `debounceMs` | `number` | `0` | 変更コールバック呼び出しのデバウンス時間 (ミリ秒)。`0` は即時発火 |
|
|
320
387
|
| `colorScheme` | `PeriodSliderColorScheme` | `"blue-rose"` | カラーテーマプリセット (`"blue-rose"`, `"indigo-amber"`, `"teal-emerald"`, `"violet-fuchsia"`, `"slate-sky"`, `"monochrome"`) |
|
|
321
|
-
| `className` | `string` | `
|
|
322
|
-
| `
|
|
323
|
-
|
|
324
|
-
|
|
388
|
+
| `className` | `string` | `""` | 最外層コンテナ要素の追加 CSS クラス |
|
|
389
|
+
| `style` | `React.CSSProperties` | `undefined` | 最外層コンテナ要素のインラインスタイル (CSS 変数の直接注入等) |
|
|
390
|
+
|
|
391
|
+
#### Range モード専用 Props (`mode="range"`)
|
|
392
|
+
|
|
393
|
+
| プロパティ | 型 | 既定値 | 説明 |
|
|
394
|
+
| :--- | :--- | :--- | :--- |
|
|
395
|
+
| `range` | `[Date, Date]` | `undefined` | 制御 (Controlled) 時の選択期間タプル [開始, 終了]。指定時は本 Props が単一真実源 |
|
|
396
|
+
| `defaultRange` | `[Date, Date]` | `undefined` | 非制御 (Uncontrolled) 時の初期選択期間タプル。`range` 指定時は無視 |
|
|
397
|
+
| `onChangeRange` | `(lower: Date, upper: Date) => void` | `undefined` | 選択期間変更時コールバック |
|
|
398
|
+
|
|
399
|
+
`range` / `defaultRange` を共に省略した場合、両つまみは `minDate` (離散時は候補日付の先頭) に重なり、幅ゼロの期間として描画されます。意図した期間は必ずどちらかで与えてください。
|
|
400
|
+
|
|
401
|
+
#### Point モード専用 Props (`mode="point"`)
|
|
402
|
+
|
|
403
|
+
| プロパティ | 型 | 既定値 | 説明 |
|
|
404
|
+
| :--- | :--- | :--- | :--- |
|
|
405
|
+
| `value` | `Date` | `undefined` | 制御 (Controlled) 時の選択日付。指定時は本 Props が単一真実源 |
|
|
406
|
+
| `defaultValue` | `Date` | `undefined` | 非制御 (Uncontrolled) 時の初期選択日付。`value` 指定時は無視 |
|
|
407
|
+
| `onChangePoint` | `(value: Date) => void` | `undefined` | 選択日付変更時コールバック |
|
|
408
|
+
|
|
409
|
+
`value` / `defaultValue` を共に省略した場合、選択日付は定義域下限 (`minDate`、離散時は候補日付の先頭) として描画されます。
|
|
410
|
+
|
|
411
|
+
#### Vernier モード専用 Props (`mode="vernier"`)
|
|
412
|
+
|
|
413
|
+
| プロパティ | 型 | 既定値 | 説明 |
|
|
414
|
+
| :--- | :--- | :--- | :--- |
|
|
415
|
+
| `macroRange` | `[Date, Date]` | (必須) | マクロ側の広域表示窓 [開始, 終了]。制御専用 (非制御版は存在しない)。欠落・2 要素タプル以外・Invalid Date・逆転 (`end` が `start` より前) は `RangeError`。`start` と `end` が同値の場合は 1 マクロ単位幅の窓として有効 |
|
|
416
|
+
| `onChangeMacroRange` | `(lower: Date, upper: Date) => void` | `undefined` | マクロ窓変更時コールバック |
|
|
417
|
+
| `microRange` | `[Date, Date]` | `undefined` | 制御時のミクロ選択期間タプル [開始, 終了]。指定時は本 Props が単一真実源となり、内部ステートは一切参照されない |
|
|
418
|
+
| `defaultMicroRange` | `[Date, Date]` | `undefined` | 非制御時の初期ミクロ選択期間タプル。以降のミクロ操作はコンポーネント内部のステートが保持し、つまみは操作に追従する。`microRange` 指定時は無視 |
|
|
419
|
+
| `onChangeMicroRange` | `(lower: Date, upper: Date) => void` | `undefined` | ミクロ選択期間変更時コールバック |
|
|
420
|
+
| `macroUnit` | `"year" \| "month" \| "day"` | `unit` | マクロ側時間解像度単位 (異単位構成用)。`macroUnit` で `minDate` と `maxDate` が同一値に丸められる場合は `RangeError` |
|
|
421
|
+
| `microUnit` | `"year" \| "month" \| "day"` | `unit` | ミクロ側時間解像度単位 (異単位構成用) |
|
|
422
|
+
| `macroIsDiscrete` | `boolean` | `false` | マクロ側の離散スナップ有効化フラグ。`false` の間は `macroAllowedDates` が参照されない |
|
|
423
|
+
| `microIsDiscrete` | `boolean` | `false` | ミクロ側の離散スナップ有効化フラグ。`false` の間は `microAllowedDates` が参照されない |
|
|
424
|
+
| `macroAllowedDates` | `Date[]` | `allowedDates` | マクロ側の離散スナップ対象日付配列。`macroIsDiscrete={true}` との併用が必須 |
|
|
425
|
+
| `microAllowedDates` | `Date[]` | `allowedDates` | ミクロ側の離散スナップ対象日付配列。`microIsDiscrete={true}` との併用が必須。候補はマクロ窓で切り出され、窓の外の日付へはキーボード・ポインターのいずれからも到達しない。窓内に候補が 1 件も残らない場合、ミクロレールは窓内の連続値として振る舞う |
|
|
426
|
+
| `formatMacroLabel` | `(date: Date) => string` | `formatLabel` | マクロ側ラベル・ツールチップのカスタム表示文字列生成関数 |
|
|
427
|
+
| `formatMicroLabel` | `(date: Date) => string` | `formatLabel` | ミクロ側ラベル・ツールチップのカスタム表示文字列生成関数。引数はつまみ位置と同一の `microUnit` 正規化済み `Date` (`microUnit="month"` なら常に月初) |
|
|
428
|
+
| `vernierOrientation` | `"macro-top" \| "macro-bottom" \| "macro-left" \| "macro-right"` | 水平時 `"macro-top"` / `isVertical` 時 `"macro-left"` | ノギスのレール配置。水平時は上下 (`macro-top` / `macro-bottom`)、垂直時は左右 (`macro-left` / `macro-right`) を指定 |
|
|
429
|
+
| `showVernierProjection` | `boolean` | `true` | マクロ窓からミクロ全幅へ広がる半透明台形プロジェクション光の表示有無 |
|
|
430
|
+
| `showVernierTicks` | `boolean` | `true` | 目盛線の表示有無。マクロレールに 20% 間隔で 4 本、ミクロレールに 10% 間隔で 9 本を等間隔に描画する |
|
|
431
|
+
| `showHairline` | `boolean` | `true` | 半円つまみ先端の 1px 精密ヘアライン針の表示有無 |
|
|
432
|
+
|
|
433
|
+
`microRange` (制御) / `defaultMicroRange` (非制御) はいずれか一方が必須です。共に省略した場合は描画時に `RangeError` を送出し、ミクロ選択範囲を発明しません。
|
|
434
|
+
|
|
435
|
+
#### アクセシビリティ Props (`AccessibleSliderLabels`, 全モード共通)
|
|
436
|
+
|
|
437
|
+
| プロパティ | 型 | 既定値 | 説明 |
|
|
438
|
+
| :--- | :--- | :--- | :--- |
|
|
439
|
+
| `lowerAriaLabel` | `string` | `"Range start"` (vernier 時 `"Micro range start"`) | 下限つまみのアクセシブル名 |
|
|
440
|
+
| `upperAriaLabel` | `string` | `"Range end"` (vernier 時 `"Micro range end"`) | 上限つまみのアクセシブル名 |
|
|
441
|
+
| `pointAriaLabel` | `string` | `"Selected date"` | 単一選択つまみのアクセシブル名 (`mode="point"` のみ) |
|
|
442
|
+
| `macroLowerAriaLabel` | `string` | `"Macro range start"` | マクロ下限つまみのアクセシブル名 (`mode="vernier"` のみ) |
|
|
443
|
+
| `macroUpperAriaLabel` | `string` | `"Macro range end"` | マクロ上限つまみのアクセシブル名 (`mode="vernier"` のみ) |
|
|
444
|
+
| `decreaseAriaLabel` | `string` | `"Decrease"` | 値を `minDate` 方向へ 1 単位動かすステッパーボタンのアクセシブル名 (水平時は左の `◀`、垂直時は下の `▼`) |
|
|
445
|
+
| `increaseAriaLabel` | `string` | `"Increase"` | 値を `maxDate` 方向へ 1 単位動かすステッパーボタンのアクセシブル名 (水平時は右の `▶`、垂直時は上の `▲`) |
|
|
446
|
+
| `formatAriaValueText` | `(date: Date, unit: PeriodSliderUnit) => string` | `undefined` | `aria-valuetext` の読み上げ文字列生成関数。未指定時は可視ラベルと同一の文字列 (ISO 8601、`locale` 指定時は `Intl.DateTimeFormat` 書式)。ノギスのマクロ側には `macroRange` の値がそのまま、ミクロ側には `microUnit` 正規化済みの `Date` が渡される |
|
|
447
|
+
|
|
448
|
+
ステッパーの 2 つの名称は配置ではなく値への作用で定義されています。同じボタンが水平レイアウトでは左、垂直レイアウトでは下に立つため、位置で命名すると意味が反転するからです。
|
|
449
|
+
|
|
450
|
+
#### コールバック一覧
|
|
451
|
+
|
|
452
|
+
各イベントに対するコールバックは 1 つだけ存在し、別名は提供されません。
|
|
453
|
+
|
|
454
|
+
| コールバック | 発火モード | シグネチャ |
|
|
455
|
+
| :--- | :--- | :--- |
|
|
456
|
+
| `onChangePoint` | `point` | `(value: Date) => void` |
|
|
457
|
+
| `onChangeRange` | `range` | `(lower: Date, upper: Date) => void` |
|
|
458
|
+
| `onChangeMacroRange` | `vernier` | `(lower: Date, upper: Date) => void` |
|
|
459
|
+
| `onChangeMicroRange` | `vernier` | `(lower: Date, upper: Date) => void` |
|
|
460
|
+
|
|
461
|
+
#### DOM 契約 (テストフック)
|
|
462
|
+
|
|
463
|
+
DOM 要素の特定は CSS クラス名ではなく `data-*` 属性で行います。クラス名はスタイリングの契約であり、予告なく変更されます。
|
|
464
|
+
|
|
465
|
+
| フック | 対象 |
|
|
466
|
+
| :--- | :--- |
|
|
467
|
+
| `[data-mode="range" \| "point" \| "vernier"]` | ルート要素。`data-unit` / `data-orientation` / `data-label-position` / `data-color-scheme` / `data-disabled` を併せ持つ |
|
|
468
|
+
| `[role="slider"]` | すべてのつまみ。`aria-label` (既定 `"Range start"` / `"Range end"` / `"Selected date"`) で個々のつまみを識別でき、`data-active` / `data-front` が操作状態を表す |
|
|
469
|
+
| `[data-testid="period-slider-knob"]` | `range` / `point` モードのつまみ本体 (円形ノブ)。つまみの位置・寸法の測定に用いる |
|
|
470
|
+
| `[data-handle-type="macro-low" \| "macro-high" \| "micro-low" \| "micro-high"]` | ノギスモードのつまみのみに付与 (`role="slider"` との併用)。配置位置は `data-vernier-pos` (`top` / `bottom` / `left` / `right`) が持ち、配色を決める `data-handle-type` と直交する |
|
|
471
|
+
| `[data-testid="period-slider-track"]` | トラック (`data-vernier-orientation` でノギスのレール配置を判別) |
|
|
472
|
+
| `[data-testid="period-slider-connect"]` | 接続バー。ノギスでは `period-slider-connect-macro` / `period-slider-connect-micro` の 2 本 |
|
|
473
|
+
| `[data-testid="period-slider-tick"]` | 目盛線。ノギスモードでは `data-tick-scale="macro" \| "micro"` が併記され上下段を判別できる |
|
|
474
|
+
| `[data-testid="period-slider-hover-guide"]` | ホバーガイド |
|
|
475
|
+
| `[data-testid="period-slider-hover-dot"]` | ホバーガイドの点 |
|
|
476
|
+
|
|
477
|
+
### 実行時バリデーション (Fail Fast)
|
|
478
|
+
|
|
479
|
+
本パッケージは欠落値・不正値を既定値や壁時計時刻で代替しません。次の条件では描画時に例外を送出します。
|
|
480
|
+
|
|
481
|
+
| コンポーネント / 関数 | 条件 | 例外 |
|
|
482
|
+
| :--- | :--- | :--- |
|
|
483
|
+
| `PeriodSlider` | `minDate` が未指定または Invalid Date | `RangeError: PeriodSlider: minDate is required and must be a valid Date (received: ...)` |
|
|
484
|
+
| `PeriodSlider` | `maxDate` が未指定または Invalid Date | `RangeError: PeriodSlider: maxDate is required and must be a valid Date (received: ...)` |
|
|
485
|
+
| `PeriodSlider` | `maxDate <= minDate` | `RangeError: PeriodSlider: maxDate must be strictly later than minDate (...)` |
|
|
486
|
+
| `PeriodSlider` (`vernier`) | `macroUnit` で `minDate` と `maxDate` が同一単位に丸められる | `RangeError: PeriodSlider: macroUnit "..." cannot distinguish minDate from maxDate (...)` |
|
|
487
|
+
| `PeriodSlider` (`vernier`) | `macroRange` の未指定・2 要素タプル以外・Invalid Date・逆転 | `RangeError: PeriodSlider: macroRange is required and must be a [start, end] Date tuple (...)` / `... macroRange[0] must be a valid Date (...)` / `... macroRange must not be inverted (...)` |
|
|
488
|
+
| `PeriodSlider` (`vernier`) | `microRange` / `defaultMicroRange` が共に未指定 | `RangeError: PeriodSlider: vernier mode requires a micro selection; supply microRange (controlled) or defaultMicroRange (uncontrolled)` |
|
|
489
|
+
| `PeriodSlider` (`vernier`) | 指定された `microRange` / `defaultMicroRange` が 2 要素タプル以外・Invalid Date・逆転 | `RangeError: PeriodSlider: <プロパティ名> ...` |
|
|
490
|
+
| `PeriodSlider` | `allowedDates` の全要素が `[minDate, maxDate]` 外 | `RangeError: getSortedAllowedDates: every allowedDates entry falls outside [minDate, maxDate] (...)` |
|
|
491
|
+
| `usePeriodSliderRange` / `usePeriodSliderPoint` / `useVernierSlider` | 境界・初期値の欠落、Invalid Date、逆転 | `RangeError: <フック名>: ...` |
|
|
492
|
+
| `PeriodSlider` | `locale` が空文字列・構造として不正な BCP 47 タグ・非文字列 | `RangeError: PeriodSlider: locale must be a valid BCP 47 language tag (received: ...)` |
|
|
493
|
+
| `DateSelector` | 同上 | `RangeError: DateSelector: "locale" must be a valid BCP 47 language tag (received ...)` |
|
|
494
|
+
| `MonthSelector` / `YearSelector` | 同上 | ``RangeError: <コンポーネント名>: `locale` must be a valid BCP 47 language tag, received ....`` |
|
|
495
|
+
| `YearSelector` / `MonthSelector` / `DateSelector` | `value` と `initialDate` が共に未指定 | `RangeError: <コンポーネント名>: either \`value\` (controlled) or \`initialDate\` (uncontrolled) is required; ...` |
|
|
496
|
+
| `YearSelector` / `MonthSelector` | 境界の欠落・矛盾、境界外の選択値、Date / 年 Props の不正値 | `RangeError` |
|
|
497
|
+
| `DateSelector` | Date / 年 Props の不正値、解決後の範囲が空、バリアントが要求する境界の欠落、`variant="split-dropdown"` への `allowedDates` 指定 | `RangeError` |
|
|
498
|
+
|
|
499
|
+
`DateSelector` は構成そのものの矛盾を優先して報告します。`variant="split-dropdown"` と `allowedDates` の併用は、`value` / `initialDate` の欠落よりも先に判定されます。
|
|
325
500
|
|
|
326
501
|
### カラーテーマ & ダークモード
|
|
327
502
|
|
|
@@ -331,52 +506,64 @@ export function CustomLabelExample() {
|
|
|
331
506
|
<PeriodSlider
|
|
332
507
|
mode="vernier"
|
|
333
508
|
unit="month"
|
|
509
|
+
minDate={new Date(2020, 0, 1)}
|
|
510
|
+
maxDate={new Date(2026, 11, 31)}
|
|
511
|
+
macroRange={macroRange}
|
|
334
512
|
colorScheme="indigo-amber" // 🟣 Indigo × 🟠 Amber 配色
|
|
335
|
-
// ...
|
|
336
513
|
/>
|
|
337
514
|
```
|
|
338
515
|
|
|
339
|
-
| プリセット | マクロ色 | ミクロ色 | アクセント色 | 特徴 |
|
|
516
|
+
| プリセット | マクロ色 (`--aqps-macro-color`) | ミクロ色 (`--aqps-micro-color`) | アクセント色 (`--aqps-accent-color`) | 特徴 |
|
|
340
517
|
| :--- | :--- | :--- | :--- | :--- |
|
|
341
|
-
| `"blue-rose"` (既定) | Sky
|
|
342
|
-
| `"indigo-amber"` | Indigo (`#4f46e5`) | Amber (`#d97706`) |
|
|
343
|
-
| `"teal-emerald"` | Teal (`#0d9488`) | Emerald (`#059669`) |
|
|
344
|
-
| `"violet-fuchsia"` | Violet (`#7c3aed`) | Fuchsia (`#c026d3`) |
|
|
345
|
-
| `"slate-sky"` | Slate (`#475569`) | Sky (`#0284c7`) |
|
|
346
|
-
| `"monochrome"` | Zinc (`#52525b`) |
|
|
518
|
+
| `"blue-rose"` (既定) | Sky (`#0284c7`) | Rose (`#e11d48`) | Sky (`#0284c7`) | 青と赤の鮮明なメリハリ対比 |
|
|
519
|
+
| `"indigo-amber"` | Indigo (`#4f46e5`) | Amber (`#d97706`) | Indigo (`#4f46e5`) | 藍色と琥珀色のモダンなコントラスト |
|
|
520
|
+
| `"teal-emerald"` | Teal (`#0d9488`) | Emerald (`#059669`) | Teal (`#0d9488`) | 自然で落ち着きのあるグリーン・ティール系 |
|
|
521
|
+
| `"violet-fuchsia"` | Violet (`#7c3aed`) | Fuchsia (`#c026d3`) | Violet (`#7c3aed`) | クリエイティブな紫・赤紫系 |
|
|
522
|
+
| `"slate-sky"` | Slate (`#475569`) | Sky (`#0284c7`) | Slate (`#475569`) | エンタープライズ向けクールスレート系 |
|
|
523
|
+
| `"monochrome"` | Zinc (`#52525b`) | Zinc 950 (`#18181b`) | Zinc 800 (`#27272a`) | 無彩色ニュートラル設計 |
|
|
347
524
|
|
|
348
|
-
|
|
525
|
+
アクセント色 (つまみのグロー・波紋) は `monochrome` を除きマクロ色と同一値です。各プリセットの実値は `COLOR_SCHEME_PALETTES` からも取得できます。
|
|
526
|
+
|
|
527
|
+
ダークモードは、祖先要素に `.dark` クラスを付与するだけで、スライダー (トラック、ノブ、グロー光、目盛線、ツールチップ) および全セレクタ (`YearSelector`, `MonthSelector`, `DateSelector`) が自動でダークパレットに適応します。
|
|
349
528
|
|
|
350
529
|
### 各種セレクタ
|
|
351
530
|
|
|
531
|
+
3 つのセレクタはいずれも `value` (制御) または `initialDate` (非制御) で選択値を受け取り、両脇の ◀▶ ステッパーボタンで 1 単位ずつ移動します。
|
|
532
|
+
|
|
352
533
|
```tsx
|
|
353
534
|
import { YearSelector, MonthSelector, DateSelector } from "@aiquants/period-slider"
|
|
354
535
|
import { useState } from "react"
|
|
355
536
|
|
|
537
|
+
const minDate = new Date(2020, 0, 1)
|
|
538
|
+
const maxDate = new Date(2030, 11, 31)
|
|
539
|
+
|
|
356
540
|
export function SelectorsExample() {
|
|
357
|
-
const [currentDate, setCurrentDate] = useState<Date>(new Date())
|
|
541
|
+
const [currentDate, setCurrentDate] = useState<Date>(new Date(2024, 5, 15))
|
|
358
542
|
|
|
359
543
|
return (
|
|
360
544
|
<div className="flex flex-col gap-4">
|
|
361
|
-
{/* 年セレクタ */}
|
|
545
|
+
{/* 年セレクタ (境界必須) */}
|
|
362
546
|
<YearSelector
|
|
363
|
-
|
|
547
|
+
value={currentDate}
|
|
364
548
|
minYear={2020}
|
|
365
549
|
maxYear={2030}
|
|
366
|
-
onChange={(date
|
|
550
|
+
onChange={(date) => setCurrentDate(date)}
|
|
367
551
|
/>
|
|
368
552
|
|
|
369
|
-
{/* 年月セレクタ */}
|
|
553
|
+
{/* 年月セレクタ (variant="dropdown" は境界必須) */}
|
|
370
554
|
<MonthSelector
|
|
371
|
-
|
|
555
|
+
value={currentDate}
|
|
372
556
|
variant="dropdown"
|
|
373
|
-
|
|
557
|
+
minDate={minDate}
|
|
558
|
+
maxDate={maxDate}
|
|
559
|
+
onChange={(date) => setCurrentDate(date)}
|
|
374
560
|
/>
|
|
375
561
|
|
|
376
|
-
{/* 年月日セレクタ (
|
|
562
|
+
{/* 年月日セレクタ (既定の variant="date" は境界任意) */}
|
|
377
563
|
<DateSelector
|
|
378
|
-
|
|
379
|
-
|
|
564
|
+
value={currentDate}
|
|
565
|
+
minDate={minDate}
|
|
566
|
+
maxDate={maxDate}
|
|
380
567
|
onChange={(date) => setCurrentDate(date)}
|
|
381
568
|
/>
|
|
382
569
|
</div>
|
|
@@ -384,6 +571,199 @@ export function SelectorsExample() {
|
|
|
384
571
|
}
|
|
385
572
|
```
|
|
386
573
|
|
|
574
|
+
#### `YearSelector` Props
|
|
575
|
+
|
|
576
|
+
年を 1 年刻みで選択するコンポーネント。選択肢は解決後の上限年から下限年までの降順で、境界を跨いで広がることはありません。選択肢のテキストは 4 桁ゼロ埋めの年 (`2024`) で、`locale` 指定時は `Intl.DateTimeFormat` 書式 (`ja-JP` なら `2024年`)。`<option value>` は常に生の数値です。
|
|
577
|
+
|
|
578
|
+
| プロパティ | 型 | 既定値 | 説明 |
|
|
579
|
+
| :--- | :--- | :--- | :--- |
|
|
580
|
+
| `value` | `Date` | `undefined` | 制御時の選択日付 (年のみ使用)。`initialDate` 未指定時は必須 |
|
|
581
|
+
| `initialDate` | `Date` | `undefined` | 非制御時の初期選択日付 (年のみ使用)。`value` 未指定時は必須。`value` 指定時は無視 |
|
|
582
|
+
| `minYear` | `number` | `undefined` | 選択可能な最小年。`minDate` と併用時は厳しい方 (遅い方) を採用 |
|
|
583
|
+
| `maxYear` | `number` | `undefined` | 選択可能な最大年。`maxDate` と併用時は厳しい方 (早い方) を採用 |
|
|
584
|
+
| `minDate` | `Date` | `undefined` | 選択可能な最小日付 (年のみ使用)。`minYear` と併用時は厳しい方を採用 |
|
|
585
|
+
| `maxDate` | `Date` | `undefined` | 選択可能な最大日付 (年のみ使用)。`maxYear` と併用時は厳しい方を採用 |
|
|
586
|
+
| `onChange` | `(date: Date, year: number) => void` | `undefined` | 年変更時コールバック。`date` は該当年の 1 月 1 日ローカル 0 時 |
|
|
587
|
+
| `disabled` | `boolean` | `false` | 無効化フラグ。`true` の間は `onChange` を発火しない |
|
|
588
|
+
| `className` | `string` | `""` | ルート要素の追加 CSS クラス |
|
|
589
|
+
| `style` | `React.CSSProperties` | `undefined` | ルート要素のインラインスタイル |
|
|
590
|
+
| `children` | `React.ReactNode` | `undefined` | ルート要素末尾へ追加描画する子要素 |
|
|
591
|
+
| `prevYearAriaLabel` | `string` | `"Previous year"` | 前年ボタンのアクセシブル名 |
|
|
592
|
+
| `nextYearAriaLabel` | `string` | `"Next year"` | 翌年ボタンのアクセシブル名 |
|
|
593
|
+
| `selectAriaLabel` | `string` | `"Year"` | 年セレクトのアクセシブル名 |
|
|
594
|
+
| `locale` | `string` | `undefined` | 選択肢テキストのロケール (BCP 47 言語タグ)。未指定は 4 桁ゼロ埋めの年、指定時は `Intl.DateTimeFormat` 書式。空文字列・不正タグ・非文字列は `RangeError` |
|
|
595
|
+
| `unit` | `"year" \| "month" \| "day"` | `undefined` | **不活性 Props**。フックの `SelectorProps` をスプレッドするための受け口で、描画・挙動には一切影響しない |
|
|
596
|
+
|
|
597
|
+
下限 (`minYear` または `minDate`) と上限 (`maxYear` または `maxDate`) は共に必須です。選択年が境界外の場合、境界に丸めるのではなく `RangeError` を送出します。
|
|
598
|
+
|
|
599
|
+
#### `MonthSelector` Props
|
|
600
|
+
|
|
601
|
+
年月を 1 ヶ月刻みで選択するコンポーネント。
|
|
602
|
+
|
|
603
|
+
| プロパティ | 型 | 既定値 | 説明 |
|
|
604
|
+
| :--- | :--- | :--- | :--- |
|
|
605
|
+
| `value` | `Date` | `undefined` | 制御時の選択日付 (年月のみ使用)。`initialDate` 未指定時は必須 |
|
|
606
|
+
| `initialDate` | `Date` | `undefined` | 非制御時の初期選択日付 (年月のみ使用)。`value` 未指定時は必須。`value` 指定時は無視 |
|
|
607
|
+
| `variant` | `"date" \| "dropdown"` | `"date"` | `"date"`: `<input type="month">`、`"dropdown"`: `YYYY-MM` の `<select>` |
|
|
608
|
+
| `minYear` | `number` | `undefined` | 選択可能な最小年 (その年の 1 月)。`minDate` と併用時は厳しい方を採用 |
|
|
609
|
+
| `maxYear` | `number` | `undefined` | 選択可能な最大年 (その年の 12 月)。`maxDate` と併用時は厳しい方を採用 |
|
|
610
|
+
| `minDate` | `Date` | `undefined` | 選択可能な最小日付 (月頭に切り捨て)。`minYear` と併用時は厳しい方を採用 |
|
|
611
|
+
| `maxDate` | `Date` | `undefined` | 選択可能な最大日付 (月頭に切り捨て)。`maxYear` と併用時は厳しい方を採用 |
|
|
612
|
+
| `onChange` | `(date: Date, yyyymm: number) => void` | `undefined` | 月変更時コールバック。`date` は該当月 1 日ローカル 0 時、`yyyymm` は `年 * 100 + 月` の整数 |
|
|
613
|
+
| `isWarning` | `boolean` | `false` | 警告枠スタイル (アンバー) の適用フラグ。`variant` を問わず有効 |
|
|
614
|
+
| `disabled` | `boolean` | `false` | 無効化フラグ。`true` の間は `onChange` を発火しない |
|
|
615
|
+
| `className` | `string` | `""` | ルート要素の追加 CSS クラス |
|
|
616
|
+
| `style` | `React.CSSProperties` | `undefined` | ルート要素のインラインスタイル |
|
|
617
|
+
| `children` | `React.ReactNode` | `undefined` | ルート要素末尾へ追加描画する子要素 |
|
|
618
|
+
| `prevMonthAriaLabel` | `string` | `"Previous month"` | 前月ボタンのアクセシブル名 |
|
|
619
|
+
| `nextMonthAriaLabel` | `string` | `"Next month"` | 翌月ボタンのアクセシブル名 |
|
|
620
|
+
| `selectAriaLabel` | `string` | `"Month"` | 年月セレクトのアクセシブル名 |
|
|
621
|
+
| `locale` | `string` | `undefined` | 選択肢テキストのロケール (BCP 47 言語タグ)。未指定は ISO 8601 の `YYYY-MM`、指定時は `Intl.DateTimeFormat` 書式。`<input type="month">` および `<option value>` は常に `yyyy-MM`。空文字列・不正タグ・非文字列は `RangeError` |
|
|
622
|
+
| `unit` | `"year" \| "month" \| "day"` | `undefined` | **不活性 Props**。フックの `SelectorProps` をスプレッドするための受け口で、描画・挙動には一切影響しない |
|
|
623
|
+
|
|
624
|
+
`variant="dropdown"` は選択肢生成のため下限と上限の双方が必須です (`variant="date"` では任意)。境界外の直接入力は丸められず破棄され、`onChange` は発火しません。
|
|
625
|
+
|
|
626
|
+
#### `DateSelector` Props
|
|
627
|
+
|
|
628
|
+
年月日を 1 日刻みで選択するコンポーネント。
|
|
629
|
+
|
|
630
|
+
| プロパティ | 型 | 既定値 | 説明 |
|
|
631
|
+
| :--- | :--- | :--- | :--- |
|
|
632
|
+
| `value` | `Date` | `undefined` | 制御時の選択日付 (日単位に正規化)。`initialDate` 未指定時は必須。`initialDate` 指定時も `value` が優先 |
|
|
633
|
+
| `initialDate` | `Date` | `undefined` | 非制御時の初期選択日付。`value` 未指定時は必須。`value` 指定時は無視 |
|
|
634
|
+
| `variant` | `"date" \| "dropdown" \| "split-dropdown"` | `"date"` | `"date"`: `<input type="date">`、`"dropdown"`: `YYYY-MM-DD` の単一 `<select>`、`"split-dropdown"`: 年・月・日の 3 分割 `<select>` |
|
|
635
|
+
| `allowedDates` | `Date[]` | `undefined` | 選択可能な離散日付配列。空配列は「選択可能日なし」を意味する。境界で絞り込み・日単位で重複排除される |
|
|
636
|
+
| `minYear` | `number` | `undefined` | 選択可能な最小年 (その年の 1 月 1 日)。`minDate` と併用時は厳しい方を採用 |
|
|
637
|
+
| `maxYear` | `number` | `undefined` | 選択可能な最大年 (その年の 12 月 31 日)。`maxDate` と併用時は厳しい方を採用 |
|
|
638
|
+
| `minDate` | `Date` | `undefined` | 選択可能な最小日付。`minYear` と併用時は厳しい方を採用 |
|
|
639
|
+
| `maxDate` | `Date` | `undefined` | 選択可能な最大日付。`maxYear` と併用時は厳しい方を採用 |
|
|
640
|
+
| `onChange` | `(date: Date) => void` | `undefined` | 選択日付変更時コールバック。選択可能集合内の日付でのみ発火し、ローカル 0 時に正規化された `Date` を渡す |
|
|
641
|
+
| `disabled` | `boolean` | `false` | 無効化フラグ。`true` の間は `onChange` を発火しない |
|
|
642
|
+
| `className` | `string` | `""` | ルート要素の追加 CSS クラス |
|
|
643
|
+
| `style` | `React.CSSProperties` | `undefined` | ルート要素のインラインスタイル |
|
|
644
|
+
| `children` | `React.ReactNode` | `undefined` | ルート要素末尾へ追加描画する子要素 |
|
|
645
|
+
| `prevDateAriaLabel` | `string` | `"Previous day"` | 前日ボタンのアクセシブル名 |
|
|
646
|
+
| `nextDateAriaLabel` | `string` | `"Next day"` | 翌日ボタンのアクセシブル名 |
|
|
647
|
+
| `selectAriaLabel` | `string` | `"Date"` | 単一セレクトおよび日付入力のアクセシブル名 |
|
|
648
|
+
| `yearAriaLabel` | `string` | `"Year"` | 年セレクトのアクセシブル名 (`variant="split-dropdown"` のみ) |
|
|
649
|
+
| `monthAriaLabel` | `string` | `"Month"` | 月セレクトのアクセシブル名 (`variant="split-dropdown"` のみ) |
|
|
650
|
+
| `dayAriaLabel` | `string` | `"Day"` | 日セレクトのアクセシブル名 (`variant="split-dropdown"` のみ) |
|
|
651
|
+
| `locale` | `string` | `undefined` | 選択肢テキストのロケール (BCP 47 言語タグ)。未指定は ISO 8601 (`variant="dropdown"` は `YYYY-MM-DD`、`variant="split-dropdown"` は `2024` / `01` / `15`)、指定時は `Intl.DateTimeFormat` 書式。`<input type="date">` と `<option value>` は常に `yyyy-MM-dd` または生の数値。空文字列・不正タグ・非文字列は `RangeError` |
|
|
652
|
+
| `formatYearOption` | `(year: number) => string` | `undefined` | `variant="split-dropdown"` の年選択肢テキスト生成関数 (`locale` より優先) |
|
|
653
|
+
| `formatMonthOption` | `(month: number) => string` | `undefined` | `variant="split-dropdown"` の月選択肢テキスト生成関数。引数は 1〜12 (`locale` より優先) |
|
|
654
|
+
| `formatDayOption` | `(day: number) => string` | `undefined` | `variant="split-dropdown"` の日選択肢テキスト生成関数。引数は 1〜31 (`locale` より優先) |
|
|
655
|
+
| `unit` | `"year" \| "month" \| "day"` | `undefined` | **不活性 Props**。フックの `SelectorProps` をスプレッドするための受け口で、描画・挙動には一切影響しない |
|
|
656
|
+
|
|
657
|
+
境界要件と挙動:
|
|
658
|
+
|
|
659
|
+
- `value` (制御) と `initialDate` (非制御) はいずれか一方が必須です。共に省略した場合は `RangeError` を送出し、選択日付を壁時計時刻から推定しません。
|
|
660
|
+
- `variant="dropdown"`: `allowedDates` を指定しない場合、下限と上限の双方が必須です。境界を与えると `minDate` 〜 `maxDate` の全日が選択肢として展開されるため、広い範囲では `variant="date"` の利用を推奨します (例: 3 年間で 1,095 個の `<option>`)。
|
|
661
|
+
- `variant="split-dropdown"`: 下限と上限の双方が必須で、`allowedDates` との併用は `RangeError` になります。存在しない日付になる年・月へ切り替えた場合 (1 月 31 日を選択中に 2 月へ変更等)、月末日へ丸めず選択を破棄し、`onChange` を発火しません。選択肢のテキストは既定でゼロ埋めの数値 (`2024` / `01` / `15`) で、`locale` または `formatYearOption` / `formatMonthOption` / `formatDayOption` で変更できます。
|
|
662
|
+
- `variant="date"`: 境界は任意です。指定した場合は `<input>` の `min` / `max` 属性へ反映されます。
|
|
663
|
+
- ステッパーは離散指定時に隣接する選択可能日へ移動し、集合の端では `disabled` になります。
|
|
664
|
+
- 選択可能集合外の日付は丸められず破棄され、`onChange` は発火しません。
|
|
665
|
+
|
|
666
|
+
DOM 契約: ルート要素は `data-variant="date|dropdown|split-dropdown"` を持ち、現在値が選択可能集合の外にある場合は `data-out-of-range="true"` が付与され、各 `<select>` の先頭に現在値を表示する選択不可のプレースホルダ `<option value="">` が描画されます (このとき `select.value === ""`)。
|
|
667
|
+
|
|
668
|
+
### React フック
|
|
669
|
+
|
|
670
|
+
3 つのフックはいずれもステート、更新関数、および `PeriodSlider` / セレクタへそのままスプレッドできる Props を返します。境界・初期値は必須で、欠落・Invalid Date・逆転はすべて `RangeError` です。
|
|
671
|
+
|
|
672
|
+
`setRange` / `setValue` / `setMacroRange` / `setMicroRange` はステートを置き換えるだけでコールバックを発火しません。それ以外の更新関数 (`setLowerDate`, `shiftRange`, `resetRange`, `setMicroUpperDate`, `shiftMacroRange`, `resetVernier` 等) は対応する `onChange*` を発火します。
|
|
673
|
+
|
|
674
|
+
#### 共通: `SelectorProps`
|
|
675
|
+
|
|
676
|
+
`startSelectorProps` などが返す、セレクタへスプレッドするための Props です。
|
|
677
|
+
|
|
678
|
+
| プロパティ | 型 | 説明 |
|
|
679
|
+
| :--- | :--- | :--- |
|
|
680
|
+
| `value` | `Date` | 現在の選択日付 |
|
|
681
|
+
| `onChange` | `(date: Date) => void` | フックのステートへ連動する選択ハンドラ |
|
|
682
|
+
| `minDate` | `Date` | セレクタの下限日付 |
|
|
683
|
+
| `maxDate` | `Date` | セレクタの上限日付 |
|
|
684
|
+
| `unit` | `PeriodSliderUnit` | セレクタの時間解像度単位 (セレクタ側では不活性) |
|
|
685
|
+
|
|
686
|
+
`SelectorProps` は上記 5 つのみで、`locale` やアクセシブル名 Props は含みません。フックへ渡した `locale` は `sliderProps` にのみ転送されるため、セレクタの書式を揃える場合は `<MonthSelector {...startSelectorProps} locale="ja-JP" />` のように明示的に渡してください。
|
|
687
|
+
|
|
688
|
+
#### `usePeriodSliderRange(options)`
|
|
689
|
+
|
|
690
|
+
| オプション | 型 | 既定値 | 説明 |
|
|
691
|
+
| :--- | :--- | :--- | :--- |
|
|
692
|
+
| `unit` | `PeriodSliderUnit` | (必須) | 時間解像度単位 |
|
|
693
|
+
| `minDate` | `Date` | (必須) | 選択可能最小日付 |
|
|
694
|
+
| `maxDate` | `Date` | (必須) | 選択可能最大日付 (`minDate` より厳密に後) |
|
|
695
|
+
| `initialRange` | `[Date, Date]` | (必須) | 初期選択期間 [開始, 終了] |
|
|
696
|
+
| `onChangeRange` | `(lower: Date, upper: Date) => void` | `undefined` | 期間変更時コールバック |
|
|
697
|
+
| その他 | — | — | `mode` / `unit` / `minDate` / `maxDate` / `range` / `defaultRange` / `onChangeRange` を除く `PeriodSlider` の Range モード Props をすべて受け取り、`sliderProps` へそのまま転送 |
|
|
698
|
+
|
|
699
|
+
| 返却値 | 型 | 説明 |
|
|
700
|
+
| :--- | :--- | :--- |
|
|
701
|
+
| `range` | `[Date, Date]` | 現在の選択期間タプル |
|
|
702
|
+
| `lowerDate` | `Date` | 現在の選択下限日付 (`range[0]`) |
|
|
703
|
+
| `upperDate` | `Date` | 現在の選択上限日付 (`range[1]`) |
|
|
704
|
+
| `setRange` | `React.Dispatch<React.SetStateAction<[Date, Date]>>` | 期間の直接更新関数 (コールバックは発火しない) |
|
|
705
|
+
| `setLowerDate` | `(date: Date) => void` | 下限更新関数。上限を超えた場合は上限も追従。`onChangeRange` を発火する |
|
|
706
|
+
| `setUpperDate` | `(date: Date) => void` | 上限更新関数。下限を下回った場合は下限も追従。`onChangeRange` を発火する |
|
|
707
|
+
| `shiftRange` | `(delta: number) => void` | 両端を `delta` 単位シフトし、それぞれ境界へクランプ (境界に達した側は期間幅が縮む) |
|
|
708
|
+
| `resetRange` | `() => void` | `initialRange` へ復帰 |
|
|
709
|
+
| `startSelectorProps` | `SelectorProps` | 開始側セレクタ用 Props (`maxDate` は現在の上限日付) |
|
|
710
|
+
| `endSelectorProps` | `SelectorProps` | 終了側セレクタ用 Props (`minDate` は現在の下限日付) |
|
|
711
|
+
| `sliderProps` | `PeriodSliderRangeProps` | `<PeriodSlider {...sliderProps} />` へ渡す Props |
|
|
712
|
+
|
|
713
|
+
#### `usePeriodSliderPoint(options)`
|
|
714
|
+
|
|
715
|
+
| オプション | 型 | 既定値 | 説明 |
|
|
716
|
+
| :--- | :--- | :--- | :--- |
|
|
717
|
+
| `unit` | `PeriodSliderUnit` | (必須) | 時間解像度単位 |
|
|
718
|
+
| `minDate` | `Date` | (必須) | 選択可能最小日付 |
|
|
719
|
+
| `maxDate` | `Date` | (必須) | 選択可能最大日付 (`minDate` より厳密に後) |
|
|
720
|
+
| `initialValue` | `Date` | (必須) | 初期選択日付 |
|
|
721
|
+
| `onChangePoint` | `(value: Date) => void` | `undefined` | 日付変更時コールバック |
|
|
722
|
+
| その他 | — | — | `mode` / `unit` / `minDate` / `maxDate` / `value` / `defaultValue` / `onChangePoint` を除く `PeriodSlider` の Point モード Props をすべて受け取り、`sliderProps` へそのまま転送 |
|
|
723
|
+
|
|
724
|
+
| 返却値 | 型 | 説明 |
|
|
725
|
+
| :--- | :--- | :--- |
|
|
726
|
+
| `value` | `Date` | 現在の選択日付 |
|
|
727
|
+
| `setValue` | `React.Dispatch<React.SetStateAction<Date>>` | 日付の直接更新関数 (コールバックは発火しない) |
|
|
728
|
+
| `shiftValue` | `(delta: number) => void` | 日付を `delta` 単位シフトし、境界へクランプ |
|
|
729
|
+
| `resetValue` | `() => void` | `initialValue` へ復帰 |
|
|
730
|
+
| `selectorProps` | `SelectorProps` | セレクタ用 Props |
|
|
731
|
+
| `sliderProps` | `PeriodSliderPointProps` | `<PeriodSlider {...sliderProps} />` へ渡す Props |
|
|
732
|
+
|
|
733
|
+
#### `useVernierSlider(options)`
|
|
734
|
+
|
|
735
|
+
| オプション | 型 | 既定値 | 説明 |
|
|
736
|
+
| :--- | :--- | :--- | :--- |
|
|
737
|
+
| `unit` | `PeriodSliderUnit` | (必須) | 基本時間解像度単位 |
|
|
738
|
+
| `minDate` | `Date` | (必須) | 全期間マクロの下限日付 |
|
|
739
|
+
| `maxDate` | `Date` | (必須) | 全期間マクロの上限日付 (`minDate` より厳密に後) |
|
|
740
|
+
| `initialMacroRange` | `[Date, Date]` | (必須) | 初期マクロ表示窓 [開始, 終了] |
|
|
741
|
+
| `initialMicroRange` | `[Date, Date]` | (必須) | 初期ミクロ選択期間 [開始, 終了] |
|
|
742
|
+
| `macroUnit` | `PeriodSliderUnit` | `unit` | マクロ側時間解像度単位 |
|
|
743
|
+
| `microUnit` | `PeriodSliderUnit` | `unit` | ミクロ側時間解像度単位 |
|
|
744
|
+
| `onChangeMacroRange` | `(lower: Date, upper: Date) => void` | `undefined` | マクロ窓変更時コールバック |
|
|
745
|
+
| `onChangeMicroRange` | `(lower: Date, upper: Date) => void` | `undefined` | ミクロ選択期間変更時コールバック |
|
|
746
|
+
| その他 | — | — | 上記および `mode` / `macroRange` / `microRange` / `defaultMicroRange` を除く `PeriodSlider` の Vernier モード Props をすべて受け取り、`sliderProps` へそのまま転送 |
|
|
747
|
+
|
|
748
|
+
| 返却値 | 型 | 説明 |
|
|
749
|
+
| :--- | :--- | :--- |
|
|
750
|
+
| `macroRange` | `[Date, Date]` | 現在のマクロ表示窓タプル |
|
|
751
|
+
| `setMacroRange` | `React.Dispatch<React.SetStateAction<[Date, Date]>>` | マクロ窓の直接更新関数 |
|
|
752
|
+
| `microRange` | `[Date, Date]` | 現在のミクロ選択期間タプル |
|
|
753
|
+
| `setMicroRange` | `React.Dispatch<React.SetStateAction<[Date, Date]>>` | ミクロ選択期間の直接更新関数 |
|
|
754
|
+
| `setMacroLowerDate` | `(date: Date) => void` | マクロ開始日更新関数。`minDate` より前は `minDate` へ収め、マクロ上限を超えた場合は上限も追従 |
|
|
755
|
+
| `setMacroUpperDate` | `(date: Date) => void` | マクロ終了日更新関数。`maxDate` より後は `maxDate` へ収め、マクロ下限を下回った場合は下限も追従 |
|
|
756
|
+
| `setMicroLowerDate` | `(date: Date) => void` | ミクロ開始日更新関数。マクロ窓の下限より前は窓下限へ収め、ミクロ上限を超えた場合は上限も追従 |
|
|
757
|
+
| `setMicroUpperDate` | `(date: Date) => void` | ミクロ終了日更新関数。マクロ窓の上限より後は窓上限へ収め、ミクロ下限を下回った場合は下限も追従 |
|
|
758
|
+
| `shiftMacroRange` | `(delta: number) => void` | マクロ窓を `delta` マクロ単位シフト。窓幅を保つため、片側でも `[minDate, maxDate]` を越えるシフトは全体を中止する (クランプしない) |
|
|
759
|
+
| `shiftMicroRange` | `(delta: number) => void` | ミクロ選択期間を `delta` ミクロ単位シフト。マクロ窓からはみ出すシフトは全体を中止する (クランプしない) |
|
|
760
|
+
| `resetVernier` | `() => void` | マクロ・ミクロ双方を初期値へ復帰 |
|
|
761
|
+
| `macroStartSelectorProps` | `SelectorProps` | マクロ開始日セレクタ用 Props |
|
|
762
|
+
| `macroEndSelectorProps` | `SelectorProps` | マクロ終了日セレクタ用 Props |
|
|
763
|
+
| `microStartSelectorProps` | `SelectorProps` | ミクロ開始日セレクタ用 Props |
|
|
764
|
+
| `microEndSelectorProps` | `SelectorProps` | ミクロ終了日セレクタ用 Props |
|
|
765
|
+
| `sliderProps` | `PeriodSliderVernierProps` | `<PeriodSlider {...sliderProps} />` へ渡す Props |
|
|
766
|
+
|
|
387
767
|
## ライセンス
|
|
388
768
|
|
|
389
769
|
MIT
|