# 機能設計書 63-Selector

## 概要

本ドキュメントは、Avaloniaフレームワークにおける**Selector**機能の設計仕様を記述する。Selectorは、CSSに類似したセレクター構文でスタイルのターゲット要素を指定するための機能を提供する。

### 本機能の処理概要

Selectorは、スタイルが適用されるコントロールを選択するための条件を定義する抽象クラスである。型セレクター、クラスセレクター、名前セレクター、プロパティセレクター、子孫セレクター等、様々なセレクタータイプを組み合わせて複雑な条件を表現できる。

**業務上の目的・背景**：UIスタイリングにおいて、適用対象を柔軟に指定することは不可欠である。CSSのような宣言的なセレクター構文により、開発者は直感的に「どのコントロールに」「どの条件で」スタイルを適用するかを記述できる。これにより、コードの可読性とメンテナンス性が向上し、テーマやスタイルの再利用が容易になる。

**機能の利用シーン**：
- 特定の型のコントロールを選択（例: `Button`, `TextBox`）
- スタイルクラスによる選択（例: `.primary`, `.disabled`）
- コントロール名による選択（例: `#myButton`）
- 状態に基づく選択（例: `:hover`, `:pressed`, `:checked`）
- 構造的な関係による選択（例: 子要素、子孫要素）
- テンプレート内要素の選択（例: `/template/`）

**主要な処理内容**：
1. セレクター構文の解析とセレクターオブジェクトの構築
2. コントロールに対するマッチング評価
3. 動的なマッチング状態の監視（状態変更時の再評価）
4. 複合セレクターの論理演算（AND, OR, NOT）

**関連システム・外部連携**：SelectorはAvalonia.Base.Stylingモジュール内で実装され、Style、ControlTheme、およびStylingActivatorシステムと連携する。

**権限による制御**：特にアクセス権限による制御は行われない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 全コントロール | 主機能 | スタイルセレクターによる要素選択 |

## 機能種別

スタイリング / セレクター評価 / 条件マッチング

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| control | StyledElement | Yes | マッチング対象のコントロール | nullは不可 |
| parent | IStyle | No | 親スタイル（ネスティング時） | - |
| subscribe | bool | No | 変更を監視するか | デフォルトtrue |

### 入力データソース

- XAML定義またはコードで構築されたセレクター
- マッチング対象のコントロール階層

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| SelectorMatch | struct | マッチ結果（Result, IsMatch, Activator） |
| Result | SelectorMatchResult | マッチ結果の種別 |
| Activator | IStyleActivator | 動的マッチング用のアクティベーター |

### 出力先

- Style.TryAttachメソッドへの返却値

## 処理フロー

### 処理シーケンス

```
1. Match呼び出し
   └─ セレクターチェーンの逆順処理開始
2. MatchUntilCombinator（コンビネーター前まで評価）
   └─ 各セレクターのEvaluate呼び出し
3. コンビネーターの評価（存在する場合）
   └─ 親要素・祖先要素のマッチング
4. 結果の合成
   └─ SelectorMatch.And()で複合結果を生成
5. アクティベーターの構築（Sometimes時）
   └─ 状態変更監視用のActivatorを生成
```

### フローチャート

```mermaid
flowchart TD
    A[Match開始] --> B[MatchUntilCombinator呼び出し]
    B --> C{前のセレクターあり?}
    C -->|Yes| D{コンビネーター?}
    D -->|No| E[再帰的にMatch呼び出し]
    D -->|Yes| F[combinator保存]
    C -->|No| G[現セレクターEvaluate]
    E --> G
    F --> G
    G --> H{マッチ結果}
    H -->|NeverThisType/Instance| I[即座に不一致返却]
    H -->|AlwaysThisType/Instance| J[次のセレクターへ]
    H -->|Sometimes| K[Activator追加]
    K --> J
    J --> L{combinator存在?}
    I --> M[結果返却]
    L -->|Yes| N[combinator.Match呼び出し]
    L -->|No| M
    N --> O[結果合成]
    O --> M
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-63-01 | 右から左への評価 | セレクターは右から左の順序で評価される | 常時 |
| BR-63-02 | コンビネーター結果変換 | コンビネーターがある場合、AlwaysThisType→AlwaysThisInstance、NeverThisType→NeverThisInstanceに変換 | コンビネーター存在時 |
| BR-63-03 | NeverThisType優先 | 型が一致しない場合は即座に不一致として処理を終了 | 型セレクター評価時 |
| BR-63-04 | Activator合成 | 複数のSometimes結果はAndActivatorBuilderで合成 | 複合セレクター |

### 計算ロジック

- マッチ結果の優先順位: NeverThisType < NeverThisInstance < Sometimes < AlwaysThisInstance < AlwaysThisType
- 合成ロジック: SelectorMatch.And(SelectorMatch other)

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvalidOperationException | ControlThemeスタイルに複数TemplateSelectorがある場合 | 単一のTemplateSelectorに修正 |
| - | InvalidOperationException | NestingSelectorが見つからない場合 | ^（ネスティングセレクター）を追加 |
| - | InvalidOperationException | ControlThemeスタイルで直接Child/Descendantセレクターを使用した場合 | セレクター構造を修正 |

### リトライ仕様

リトライ処理は行わない。

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

本機能はトランザクションを使用しない。

## パフォーマンス要件

- 型セレクターを最初に評価して早期終了を実現
- マッチ結果のキャッシュは行わない（動的状態のため）

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

特段のセキュリティ要件はない。

## 備考

**セレクタータイプ一覧**：
- `OfType<T>` / `Is<T>`: 型セレクター
- `Class`: クラスセレクター（.className）
- `Name`: 名前セレクター（#elementName）
- `PropertyEquals`: プロパティ値セレクター
- `Child`: 子要素セレクター（>）
- `Descendant`: 子孫セレクター（空白）
- `Template`: テンプレート内セレクター（/template/）
- `Not`: 否定セレクター
- `Or`: OR結合セレクター
- `NthChild` / `NthLastChild`: n番目要素セレクター
- `Nesting`: ネスティングセレクター（^）

---

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

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

### 推奨読解順序

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

Selectorクラスの基本構造と抽象メンバーを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Selector.cs | `src/Avalonia.Base/Styling/Selector.cs` | 基底クラス。抽象メンバーとMatchメソッドを確認 |
| 1-2 | SelectorMatch.cs | `src/Avalonia.Base/Styling/SelectorMatch.cs` | マッチ結果の構造体 |

**読解のコツ**: Selectorは抽象クラスで、各具象セレクターがEvaluate, MovePrevious, MovePreviousOrParentを実装する。

**主要処理フロー (Selector.cs)**:
1. **17行目**: InTemplate プロパティ - テンプレート内かどうか
2. **25行目**: IsCombinator プロパティ - コンビネーターかどうか
3. **30行目**: TargetType プロパティ - ターゲット型
4. **44-68行目**: Match メソッド - メインのマッチング処理
5. **99行目**: Evaluate 抽象メソッド - セレクター固有の評価
6. **104行目**: MovePrevious 抽象メソッド - 前のセレクターへ移動
7. **111-136行目**: ValidateNestingSelector - ネスティングセレクターのバリデーション
8. **138-153行目**: MatchUntilCombinator - コンビネーター前までの評価
9. **155-213行目**: Match（内部）- 再帰的なマッチング処理

#### Step 2: 拡張メソッドを理解する

セレクターの構築に使用する拡張メソッドを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Selectors.cs | `src/Avalonia.Base/Styling/Selectors.cs` | セレクター構築用の拡張メソッド |

**主要処理フロー (Selectors.cs)**:
1. **16-19行目**: Child - 子要素セレクター
2. **27-47行目**: Class - クラスセレクター
3. **54-57行目**: Descendant - 子孫セレクター
4. **65-69行目**: Is - 派生型を含む型セレクター
5. **89-109行目**: Name - 名前セレクター
6. **122-136行目**: Not - 否定セレクター
7. **141-152行目**: NthChild / NthLastChild - n番目要素セレクター
8. **160-176行目**: OfType - 厳密型セレクター
9. **183-196行目**: Or - OR結合セレクター
10. **206-225行目**: PropertyEquals - プロパティ値セレクター
11. **232-235行目**: Template - テンプレートセレクター

#### Step 3: 具体的なセレクター実装を理解する

代表的なセレクター実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | TypeNameAndClassSelector.cs | `src/Avalonia.Base/Styling/TypeNameAndClassSelector.cs` | 型・名前・クラスセレクター |
| 3-2 | ChildSelector.cs | `src/Avalonia.Base/Styling/ChildSelector.cs` | 子要素セレクター |
| 3-3 | DescendantSelector.cs | `src/Avalonia.Base/Styling/DescendantSelector.cs` | 子孫セレクター |
| 3-4 | TemplateSelector.cs | `src/Avalonia.Base/Styling/TemplateSelector.cs` | テンプレートセレクター |
| 3-5 | OrSelector.cs | `src/Avalonia.Base/Styling/OrSelector.cs` | OR結合セレクター |

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

```
Style.TryAttach()
    │
    └─ Selector.Match(control, parent, subscribe)
           │
           └─ MatchUntilCombinator(control, start, parent, subscribe)
                  │
                  ├─ Match(control, selector, parent, subscribe, activators, combinator) [再帰]
                  │      │
                  │      ├─ selector.MovePrevious()
                  │      │
                  │      └─ selector.Evaluate(control, parent, subscribe)
                  │             │
                  │             └─ [各セレクタータイプ固有の評価]
                  │
                  └─ combinator?.Match(control, parent, subscribe)
                         │
                         └─ [Child/Descendant等のコンビネーター評価]
```

### データフロー図

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

StyledElement ──────────────▶ Selector.Match() ──────────────▶ SelectorMatch
    │                              │                                  │
    │ control                      │ MatchUntilCombinator()           │ Result
    │ parent style                 │ Evaluate()                       │ IsMatch
    │ subscribe flag               │ combinator.Match()               │ Activator
    └──────────────────────────────┘                                  │
                                                                      ▼
                                                              Sometimes時:
                                                              IStyleActivator生成
                                                                      │
                                                                      ▼
                                                              状態変更監視開始
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Selector.cs | `src/Avalonia.Base/Styling/Selector.cs` | ソース | セレクター基底クラス |
| Selectors.cs | `src/Avalonia.Base/Styling/Selectors.cs` | ソース | セレクター拡張メソッド |
| SelectorMatch.cs | `src/Avalonia.Base/Styling/SelectorMatch.cs` | ソース | マッチ結果構造体 |
| TypeNameAndClassSelector.cs | `src/Avalonia.Base/Styling/TypeNameAndClassSelector.cs` | ソース | 型・名前・クラスセレクター |
| ChildSelector.cs | `src/Avalonia.Base/Styling/ChildSelector.cs` | ソース | 子要素セレクター |
| DescendantSelector.cs | `src/Avalonia.Base/Styling/DescendantSelector.cs` | ソース | 子孫セレクター |
| TemplateSelector.cs | `src/Avalonia.Base/Styling/TemplateSelector.cs` | ソース | テンプレートセレクター |
| PropertyEqualsSelector.cs | `src/Avalonia.Base/Styling/PropertyEqualsSelector.cs` | ソース | プロパティ値セレクター |
| NotSelector.cs | `src/Avalonia.Base/Styling/NotSelector.cs` | ソース | 否定セレクター |
| OrSelector.cs | `src/Avalonia.Base/Styling/OrSelector.cs` | ソース | OR結合セレクター |
| NestingSelector.cs | `src/Avalonia.Base/Styling/NestingSelector.cs` | ソース | ネスティングセレクター |
| NthChildSelector.cs | `src/Avalonia.Base/Styling/NthChildSelector.cs` | ソース | n番目子要素セレクター |
| AndActivatorBuilder.cs | `src/Avalonia.Base/Styling/Activators/AndActivatorBuilder.cs` | ソース | Activator合成 |
