# 機能設計書 38-選択範囲を単語に拡張

## 概要

本ドキュメントは、Windows Terminal における「選択範囲を単語に拡張」機能（ExpandSelectionToWord アクション）の設計を記述する。現在の選択範囲を、開始位置は単語の先頭まで、終了位置は単語の末尾まで拡張する機能である。

### 本機能の処理概要

**業務上の目的・背景**：テキスト選択時に、現在選択されている範囲が単語の途中にある場合、ワンアクションで選択範囲を完全な単語の境界まで拡張する機能を提供する。これにより、部分的に選択された単語を完全に選択し直す手間が省ける。

**機能の利用シーン**：マークモードやキーボード選択で文字単位の選択を行った後、選択範囲を単語の境界に合わせたい場合に使用する。例えば、ファイルパスやコマンド名の一部を選択した後に、その単語全体を選択するために使用する。

**主要な処理内容**：
1. _HandleExpandSelectionToWord でアクションを受信
2. TermControl.ExpandSelectionToWord を呼び出し
3. ControlCore 経由で Terminal::ExpandSelectionToWord を実行
4. テキストバッファの GetWordStart2/GetWordEnd2 で単語境界を取得
5. 選択範囲を単語境界に拡張
6. 選択UIを更新

**関連システム・外部連携**：なし

**権限による制御**：なし

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | TermControl（ターミナル表示） | 主画面 | ExpandSelectionToWord により選択範囲を単語境界まで拡張 |
| 1 | TerminalPage（メイン画面） | 主画面 | _HandleExpandSelectionToWord でアクションを処理 |

## 機能種別

テキスト操作 / 選択制御

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| (なし) | - | - | ExpandSelectionToWord アクションはパラメータを持たない | - |

### 入力データソース

- 現在の選択状態（IsSelectionActive）
- 選択の開始位置と終了位置
- テキストバッファの内容
- 単語区切り文字設定（_wordDelimiters）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (なし) | - | 選択範囲が単語の境界まで拡張され、選択UIが更新される |

### 出力先

- Terminal の選択範囲（start / end / pivot）

## 処理フロー

### 処理シーケンス

```
1. _HandleExpandSelectionToWord が ActionEventArgs を受信
   └─ _GetActiveControl で TermControl を取得
2. TermControl.ExpandSelectionToWord → ControlCore.ExpandSelectionToWord
   └─ LockForWriting でロック取得
3. Terminal::ExpandSelectionToWord
   └─ 選択がアクティブか確認（非アクティブなら何もしない）
   └─ buffer.GetWordStart2(selection.start) で開始位置を単語先頭に移動
   └─ selection.pivot = selection.start に設定
   └─ buffer.GetWordEnd2(selection.end) で終了位置を単語末尾に移動
   └─ 両端点を操作中の場合は End のみに変更
4. _updateSelectionUI で選択UIを更新
```

### フローチャート

```mermaid
flowchart TD
    A[ExpandSelectionToWord アクション受信] --> B[_GetActiveControl で TermControl 取得]
    B --> C{TermControl 取得成功?}
    C -->|No| Z[何もしない]
    C -->|Yes| D[ControlCore.ExpandSelectionToWord]
    D --> E[LockForWriting でロック取得]
    E --> F{選択がアクティブ?}
    F -->|No| G[false を返す]
    F -->|Yes| H[GetWordStart2 で開始位置を単語先頭に]
    H --> I[pivot = start に設定]
    I --> J[GetWordEnd2 で終了位置を単語末尾に]
    J --> K{Start+End 両方を操作中?}
    K -->|Yes| L[End のみに変更]
    K -->|No| M[そのまま]
    L --> N[_updateSelectionUI]
    M --> N
    N --> O[true を返す]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-38-01 | 選択必須 | 選択がアクティブでない場合は拡張ができない（false を返す） | IsSelectionActive が false |
| BR-38-02 | 単語区切り文字 | _wordDelimiters 設定に基づいて単語の境界を判定する | 常に適用 |
| BR-38-03 | pivot 更新 | 拡張後の pivot は新しい start 位置に設定される | 常に適用 |
| BR-38-04 | 端点の単一化 | 両端点を操作中だった場合、拡張後は End のみの操作に変更される | Start && End フラグの場合 |

### 計算ロジック

- 単語の開始位置: `buffer.GetWordStart2(selection.start, _wordDelimiters, false)`
- 単語の終了位置: `buffer.GetWordEnd2(selection.end, _wordDelimiters, false)`

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

### 操作別データベース影響一覧

本機能はデータベースを使用しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 選択なし | テキストが選択されていない状態で実行 | false を返し、アクションを未処理とする |
| - | コントロール未取得 | アクティブな TermControl がない | 何もしない |

### リトライ仕様

リトライは行わない。

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

Terminal::ExpandSelectionToWord の実行中は LockForWriting でロックを保持する。

## パフォーマンス要件

即座に選択範囲の拡張が完了すること。

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

特になし。

## 備考

- GetWordStart2 / GetWordEnd2 は、テキストバッファ内で単語区切り文字に基づいて単語の境界を見つけるメソッド
- _wordDelimiters はプロファイル設定で指定可能
- マウスダブルクリックでの単語選択とは異なるロジック（こちらは既存選択の拡張）
- _HandleExpandSelectionToWord は _GetActiveControl を使用する（_senderOrActiveControl ではない）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | _HandleExpandSelectionToWord がエントリーポイント |

**主要処理フロー**:
1. **1559-1567行目**: _GetActiveControl で TermControl を取得し、control.ExpandSelectionToWord() の戻り値を handled に設定

#### Step 2: ControlCore 層

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ControlCore.cpp | `src/cascadia/TerminalControl/ControlCore.cpp` | ExpandSelectionToWord の実装 |

**主要処理フロー**:
- **1427-1437行目**: LockForWriting、選択アクティブ確認、_terminal->ExpandSelectionToWord() 呼び出し、_updateSelectionUI

#### Step 3: Terminal コア層

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | TerminalSelection.cpp | `src/cascadia/TerminalCore/TerminalSelection.cpp` | Terminal::ExpandSelectionToWord の実装 |

**主要処理フロー**:
- **433-450行目**: GetWordStart2 で start を単語先頭に、GetWordEnd2 で end を単語末尾に拡張。pivot を start に設定。両端点操作時は End のみに変更。

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

```
TerminalPage::_HandleExpandSelectionToWord (AppActionHandlers.cpp:1559)
    |
    +-- TermControl::ExpandSelectionToWord (TermControl.cpp:2588)
           |
           +-- ControlCore::ExpandSelectionToWord (ControlCore.cpp:1427)
                  |
                  +-- Terminal::ExpandSelectionToWord (TerminalSelection.cpp:433)
                  |      |
                  |      +-- TextBuffer::GetWordStart2 (開始位置の単語先頭)
                  |      +-- TextBuffer::GetWordEnd2 (終了位置の単語末尾)
                  |
                  +-- _updateSelectionUI
```

### データフロー図

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

選択範囲               --> ExpandSelectionToWord           --> 拡張された選択範囲
  (start, end)             |                                    (start=単語先頭,
テキストバッファ           v                                     end=単語末尾)
_wordDelimiters       GetWordStart2 / GetWordEnd2              |
                                                                v
                                                            選択UIの更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| AppActionHandlers.cpp | `src/cascadia/TerminalApp/AppActionHandlers.cpp` | ソース | _HandleExpandSelectionToWord アクションハンドラ |
| TermControl.cpp | `src/cascadia/TerminalControl/TermControl.cpp` | ソース | ExpandSelectionToWord の委譲 |
| TermControl.h | `src/cascadia/TerminalControl/TermControl.h` | ヘッダ | ExpandSelectionToWord 宣言 |
| ControlCore.cpp | `src/cascadia/TerminalControl/ControlCore.cpp` | ソース | ExpandSelectionToWord の実装 |
| TerminalSelection.cpp | `src/cascadia/TerminalCore/TerminalSelection.cpp` | ソース | Terminal::ExpandSelectionToWord の実装 |
| Terminal.hpp | `src/cascadia/TerminalCore/Terminal.hpp` | ヘッダ | ExpandSelectionToWord 宣言 |
