# 機能設計書 28-AutoCompleteBox

## 概要

本ドキュメントは、AvaloniaフレームワークにおけるAutoCompleteBoxコントロールの機能設計を記載する。AutoCompleteBoxは、テキスト入力時に候補を自動補完するドロップダウン付きテキストボックスコントロールである。

### 本機能の処理概要

AutoCompleteBoxは、ユーザーがテキストを入力すると、入力内容に基づいて候補リストをフィルタリングし、ドロップダウンで表示するコントロールである。検索ボックス、タグ入力、コマンドパレットなど、入力補助が必要なシーンで活用される。複数のフィルタリングモード（前方一致、部分一致、カスタムフィルタ）をサポートし、非同期データ取得にも対応する。

**業務上の目的・背景**：
業務アプリケーションにおいて、大量の選択肢から効率的に選択する必要がある場面は多い。AutoCompleteBoxは、入力内容に応じて候補を絞り込むことで、ユーザーの入力効率を向上させ、入力ミスを防止する。

**機能の利用シーン**：
- 検索ボックスでのキーワード候補表示
- 住所入力での自動補完
- ユーザー名・メールアドレスの入力補助
- タグ・ラベルの入力
- コマンドパレット・アクション検索
- 商品コード・製品名の検索

**主要な処理内容**：
1. テキスト入力に基づく候補リストのフィルタリング
2. 複数のフィルタリングモード（StartsWith、Contains、Equals等）
3. カスタムフィルタ関数のサポート（ItemFilter、TextFilter）
4. ドロップダウンでの候補表示と選択
5. テキスト補完機能（IsTextCompletionEnabled）
6. 非同期データ取得（AsyncPopulator）
7. 最小入力文字数による候補表示制御（MinimumPrefixLength）
8. 遅延ポピュレート（MinimumPopulateDelay）
9. SelectionChanged/TextChanged/Populating/Populatedイベントの発行

**関連システム・外部連携**：
- ISelectionAdapterによるカスタム選択UI
- AsyncPopulatorによる非同期データ取得

**権限による制御**：
本コントロールには権限による制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | AutoCompleteBox | 主画面 | AutoCompleteBoxコントロールのデモ |

## 機能種別

UI操作 / 入力コントロール / 自動補完

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Text | string | No | 入力テキスト | - |
| ItemsSource | IEnumerable | No | 候補データソース | - |
| SelectedItem | object | No | 選択されたアイテム | - |
| FilterMode | AutoCompleteFilterMode | No | フィルタリングモード | デフォルト: StartsWith |
| MinimumPrefixLength | int | No | 最小入力文字数 | デフォルト: 1、-1以上 |
| MinimumPopulateDelay | TimeSpan | No | ポピュレート遅延時間 | デフォルト: 0ms |
| MaxDropDownHeight | double | No | ドロップダウン最大高さ | デフォルト: double.PositiveInfinity |
| IsTextCompletionEnabled | bool | No | テキスト補完を有効化 | デフォルト: false |
| IsDropDownOpen | bool | No | ドロップダウン開閉状態 | - |
| ItemFilter | AutoCompleteFilterPredicate<object> | No | カスタムアイテムフィルタ | - |
| TextFilter | AutoCompleteFilterPredicate<string> | No | カスタムテキストフィルタ | - |
| TextSelector | AutoCompleteSelector<object> | No | 選択時のテキスト変換 | - |
| ItemSelector | AutoCompleteSelector<object> | No | 選択時のアイテム変換 | - |
| AsyncPopulator | Func<string, CancellationToken, Task<IEnumerable<object>>> | No | 非同期データ取得関数 | - |
| ValueMemberBinding | BindingBase | No | 表示値のバインディング | - |
| ItemTemplate | IDataTemplate | No | アイテムテンプレート | - |

### 入力データソース

- ユーザーによるテキスト入力
- キーボード操作（上下矢印、Enter、Escape）
- ドロップダウンアイテムのクリック
- プログラムによるText/SelectedItem設定
- データバインディングによる制御

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Text | string | 入力/選択されたテキスト |
| SelectedItem | object | 選択されたアイテム |
| SearchText | string | 検索に使用されたテキスト（読み取り専用） |
| IsDropDownOpen | bool | ドロップダウン開閉状態 |

### 出力先

- UI表示（テキスト、ドロップダウン候補リスト）
- TextChangedイベントの発行
- SelectionChangedイベントの発行
- Populating/Populatedイベントの発行
- DropDownOpening/DropDownOpened/DropDownClosing/DropDownClosedイベントの発行

## 処理フロー

### 処理シーケンス

```
1. テキスト入力検出
   └─ OnTextBoxTextChanged
2. 入力文字数チェック
   └─ MinimumPrefixLength以上か確認
3. ポピュレート遅延
   └─ MinimumPopulateDelay待機（タイマー使用）
4. 候補データ取得
   ├─ AsyncPopulator使用: 非同期取得
   └─ ItemsSource使用: 同期フィルタリング
5. フィルタリング実行
   └─ RefreshView → FilterModeに基づき候補をフィルタ
6. ドロップダウン表示
   └─ IsDropDownOpen = true
7. 選択処理
   └─ キーボードまたはクリックで選択
8. テキスト更新
   └─ FormatValue/TextSelectorでテキスト変換
9. イベント発行
   └─ SelectionChanged
```

### フローチャート

```mermaid
flowchart TD
    A[テキスト入力] --> B{文字数 >= MinimumPrefixLength?}
    B -->|No| C[ドロップダウン閉じる]
    B -->|Yes| D{MinimumPopulateDelay > 0?}
    D -->|Yes| E[タイマー開始]
    D -->|No| F[PopulateDropDown]
    E --> F
    F --> G{AsyncPopulator?}
    G -->|Yes| H[非同期データ取得]
    G -->|No| I[RefreshView]
    H --> J[ItemsSource更新]
    J --> I
    I --> K[候補フィルタリング]
    K --> L{候補あり?}
    L -->|Yes| M[ドロップダウン表示]
    L -->|No| C
    M --> N[ユーザー選択]
    N --> O[SelectedItem更新]
    O --> P[テキスト更新]
    P --> Q[SelectionChangedイベント]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 最小入力文字数 | MinimumPrefixLength未満の場合は候補表示しない | 常時適用 |
| BR-002 | 遅延ポピュレート | MinimumPopulateDelay経過後にポピュレート実行 | 遅延設定時 |
| BR-003 | 非同期キャンセル | 新しい入力があった場合、前の非同期取得をキャンセル | AsyncPopulator使用時 |
| BR-004 | テキスト補完 | IsTextCompletionEnabled=trueの場合、先頭一致の候補でテキストを補完 | 補完有効時 |
| BR-005 | フォーカスロスト | フォーカスを失った場合、ドロップダウンを閉じる | 常時適用 |
| BR-006 | Escapeキー | Escapeキーでドロップダウンを閉じ、テキストを元に戻す | ドロップダウン表示時 |

### 計算ロジック

フィルタリングモードの動作：
```
StartsWith: item.StartsWith(text, StringComparison.CurrentCultureIgnoreCase)
StartsWithCaseSensitive: item.StartsWith(text, StringComparison.CurrentCulture)
Contains: item.Contains(text, StringComparison.CurrentCultureIgnoreCase)
Equals: item.Equals(text, StringComparison.CurrentCultureIgnoreCase)
Custom: ItemFilter(text, item)
```

## データベース操作仕様

本コントロールはデータベース操作を行わない。AsyncPopulatorを通じて外部データソースからデータを取得可能。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ItemFilterがnullでCustomモード | FilterMode=CustomでItemFilterが未設定 | 例外をスロー |
| - | 非同期取得キャンセル | 新しい入力による前の非同期取得キャンセル | TaskCancelledExceptionを無視 |

### リトライ仕様

該当なし

## トランザクション仕様

該当なし

## パフォーマンス要件

- フィルタリングは入力に即座に反応する必要がある
- 大量の候補がある場合もドロップダウン表示は滑らかに行う
- 非同期取得中もUIはブロックしない

## セキュリティ考慮事項

本コントロールにはセキュリティ上の特別な考慮事項はない。

## 備考

- Microsoft Silverlight/WPFのAutoCompleteBoxをベースに実装されている
- AsyncPopulatorを使用することで、APIからのリアルタイム検索が可能

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

AutoCompleteBox関連の型定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | AutoCompleteBox.cs | `src/Avalonia.Controls/AutoCompleteBox/AutoCompleteBox.cs` | デリゲート定義（30-63行目） |
| 1-2 | AutoCompleteFilterMode.cs | `src/Avalonia.Controls/AutoCompleteBox/AutoCompleteFilterMode.cs` | フィルタリングモード列挙型 |
| 1-3 | ISelectionAdapter.cs | `src/Avalonia.Controls/AutoCompleteBox/ISelectionAdapter.cs` | 選択アダプターインターフェース |

**読解のコツ**: AutoCompleteBoxは多くのフィルタリングモードとカスタムフィルタ関数をサポートしている。AutoCompleteSearchクラス（内部クラス）にフィルタ関数の実装がある。

#### Step 2: エントリーポイントを理解する

AutoCompleteBoxクラスの主要プロパティを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | AutoCompleteBox.cs | `src/Avalonia.Controls/AutoCompleteBox/AutoCompleteBox.cs` | プロパティ定義 |
| 2-2 | AutoCompleteBox.Properties.cs | `src/Avalonia.Controls/AutoCompleteBox/AutoCompleteBox.Properties.cs` | プロパティ定義（分割ファイル） |

**主要処理フロー**:
1. **70-96行目**: TemplatePart属性（PART_Popup、PART_SelectingItemsControl、PART_TextBox等）
2. **プロパティ定義**: Text、SelectedItem、ItemsSource、FilterMode、MinimumPrefixLength等
3. **イベント定義**: SelectionChanged、TextChanged、Populating、Populated、DropDown関連

#### Step 3: テンプレート適用処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | AutoCompleteBox.cs | `src/Avalonia.Controls/AutoCompleteBox/AutoCompleteBox.cs` | OnApplyTemplate（635-664行目） |

**主要処理フロー**:
- **635-664行目**: Popup、SelectionAdapter、TextBoxの取得とイベントハンドラ設定

#### Step 4: テキスト更新とフィルタリングを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | AutoCompleteBox.cs | `src/Avalonia.Controls/AutoCompleteBox/AutoCompleteBox.cs` | TextUpdated（1297-1358行目） |
| 4-2 | AutoCompleteBox.cs | `src/Avalonia.Controls/AutoCompleteBox/AutoCompleteBox.cs` | RefreshView（1380-1457行目） |

**主要処理フロー**:
- **1297-1358行目**: TextUpdatedでテキスト変更を検出、PopulateDropDownを呼び出し
- **1380-1457行目**: RefreshViewでフィルタリング実行、_viewを更新

#### Step 5: フィルタ関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | AutoCompleteBox.cs | `src/Avalonia.Controls/AutoCompleteBox/AutoCompleteBox.cs` | AutoCompleteSearch（内部クラス、1804-2015行目） |

**主要処理フロー**:
- **1812-1857行目**: GetFilterでFilterModeに応じたフィルタ関数を取得
- **1881-2014行目**: StartsWith、Contains、Equalsなどの各種フィルタ関数

### プログラム呼び出し階層図

```
AutoCompleteBox
    │
    ├─ OnApplyTemplate
    │      ├─ Popup取得
    │      ├─ SelectionAdapter取得
    │      └─ TextBox取得・イベント登録
    │
    ├─ OnTextBoxTextChanged
    │      └─ TextUpdated
    │             ├─ MinimumPrefixLengthチェック
    │             └─ PopulateDropDown（タイマー or 直接）
    │
    ├─ PopulateDropDown
    │      ├─ AsyncPopulator使用時: PopulateAsync
    │      └─ 同期時: PopulateComplete
    │
    ├─ PopulateComplete
    │      ├─ RefreshView（フィルタリング）
    │      ├─ IsDropDownOpen設定
    │      └─ UpdateTextCompletion
    │
    └─ OnAdapterSelectionComplete
           ├─ SelectedItem更新
           └─ SelectionChangedイベント
```

### データフロー図

```
[入力]                    [処理]                         [出力]

テキスト入力 ───────▶ TextUpdated
                           │
                           ├─ MinimumPrefixLengthチェック
                           │
                           ▼
               ┌─────PopulateDropDown─────┐
               │                          │
               ▼                          ▼
        AsyncPopulator              RefreshView
        （非同期取得）             （同期フィルタ）
               │                          │
               └──────────┬───────────────┘
                          │
                          ▼
                   _view更新（候補リスト）
                          │
                          ▼
                   IsDropDownOpen = true
                          │
                          ▼
ユーザー選択 ─────▶ OnAdapterSelectionComplete
                          │
                          ▼
                   SelectedItem更新 ──▶ SelectionChangedイベント
                          │
                          ▼
                   Text更新 ──▶ TextChangedイベント
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AutoCompleteBox.cs | `src/Avalonia.Controls/AutoCompleteBox/AutoCompleteBox.cs` | ソース | メインコントロールクラス |
| AutoCompleteBox.Properties.cs | `src/Avalonia.Controls/AutoCompleteBox/AutoCompleteBox.Properties.cs` | ソース | プロパティ定義（分割） |
| AutoCompleteFilterMode.cs | `src/Avalonia.Controls/AutoCompleteBox/AutoCompleteFilterMode.cs` | ソース | フィルタリングモード列挙型 |
| ISelectionAdapter.cs | `src/Avalonia.Controls/AutoCompleteBox/ISelectionAdapter.cs` | ソース | 選択アダプターインターフェース |
| SelectingItemsControlSelectionAdapter.cs | `src/Avalonia.Controls/AutoCompleteBox/SelectingItemsControlSelectionAdapter.cs` | ソース | 標準選択アダプター |
| PopulatingEventArgs.cs | `src/Avalonia.Controls/AutoCompleteBox/PopulatingEventArgs.cs` | ソース | ポピュレートイベント引数 |
| PopulatedEventArgs.cs | `src/Avalonia.Controls/AutoCompleteBox/PopulatedEventArgs.cs` | ソース | ポピュレート完了イベント引数 |
| AutoCompleteBox.xaml | `src/Avalonia.Themes.Fluent/Controls/AutoCompleteBox.xaml` | テンプレート | Fluentテーマのテンプレート |
