# 画面設計書 6-プレビュー

## 概要

本ドキュメントは、Nushell Exploreにおけるプレビュー画面の設計仕様を定義する。プレビューは、テキストデータや文字列値をシンプルに表示するTUI画面である。

### 本画面の処理概要

プレビュー画面は、`explore`コマンドで文字列や単純な値を渡した際、またはレコードビューで展開（e キー）を行った際に表示される画面である。テキストデータを行単位で表示し、スクロールによる閲覧を提供する。

**業務上の目的・背景**：
構造化データ以外のテキストデータ（ログ、設定ファイル、出力テキスト等）を閲覧する際に、シンプルなテキストビューアが必要である。プレビュー画面は、テキストを行単位で表示し、上下左右のスクロールと検索機能を提供する。レコードビューからの展開表示にも対応し、ネストされたデータの詳細を確認できる。

**画面へのアクセス方法**：
- メインREPLで `explore` コマンドに文字列/単純値を渡す
- レコードビューで `e` キーを押下（展開）
- 例: `"hello world" | explore`
- 例: `cat file.txt | explore`

**主要な操作・処理内容**：
1. テキストデータの行単位表示
2. 上下スクロールによるナビゲーション
3. 左右スクロールによる長い行の閲覧
4. 検索機能によるテキスト検索

**画面遷移**：
- メインREPL（画面No.1） → explore コマンド（文字列） → プレビュー
- レコードビュー（画面No.4） → e キー → プレビュー
- プレビュー → Esc → レコードビュー / メインREPL
- プレビュー → :q → メインREPL

**権限による表示制御**：
- 特になし。全ユーザーが同一の機能を利用可能

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 69 | テーブル表示 | 主機能 | テキストデータ・文字列値のプレビュー表示 |
| 71 | 探索モード | 補助機能 | テキストデータのスクロール・ナビゲーション |

## 画面種別

TUI（Terminal User Interface）テキストビューア

## URL/ルーティング

N/A（CLI/TUIアプリケーションのためURL概念なし）

## 入出力項目

| 項目名 | 型 | 入力/出力 | 説明 |
|--------|-----|----------|------|
| テキストデータ | String | 入力 | 表示対象の文字列データ |
| underlying_value | Option<Value> | 入力 | 元の値（終了時に返却） |
| 行リスト | Vec<String> | 処理 | 改行で分割された行リスト |
| カーソル位置 | WindowCursor2D | 処理 | 表示位置管理 |

## 表示項目

| 項目名 | 説明 | 表示形式 |
|--------|------|----------|
| テキスト行 | 各行のテキスト | 文字列 |
| ステータスバー | TOP/END表示 | 下部バー |

## イベント仕様

### 1-上下矢印キー（行スクロール）

1. cursor.prev_row_i() / cursor.next_row_i() を呼び出し
2. 表示開始行を更新
3. TOP/END状態をチェックしてステータス更新

### 2-左右矢印キー（列スクロール）

1. ウィンドウ幅の半分だけ移動
2. prev_column_by() / next_column_by() を呼び出し
3. 長い行を左右にスクロール

### 3-Page Up/Page Down（ページ移動）

1. ページサイズ分だけ上下に移動
2. cursor.prev_row_page() / cursor.next_row_page()

### 4-Esc（戻る）

1. プレビューを終了
2. 呼び出し元（レコードビュー/メインREPL）に戻る

## データベース更新仕様

N/A（データベース操作なし）

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|----------|
| TOP | 情報 | TOP | スクロール位置が先頭 |
| END | 情報 | END | スクロール位置が末尾 |

## 例外処理

| 例外状態 | 対応処理 |
|---------|---------|
| 空のテキスト | 空のビューを表示 |

## 備考

- タブ文字はスペース4つに変換（TUI描画の制約）
- underlying_valueがある場合は終了時にその値を返却
- underlying_valueがない場合はテキストをjoinして返却
- ColoredTextWidgetでANSIエスケープシーケンス対応
- 検索結果は行番号を指定してshow_dataで表示位置を設定

---

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

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

### 推奨読解順序

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

プレビューで扱う主要なデータ構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | preview.rs | `crates/nu-explore/src/explore/views/preview.rs` | Preview構造体（20-24行） |

**読解のコツ**: Previewはlinesとしてテキストを行リストで持ち、cursorで表示位置を管理

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

Viewトレイト実装を通じて画面描画と入力処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | preview.rs | `crates/nu-explore/src/explore/views/preview.rs` | View for Preview実装（43-108行） |

**主要処理フロー**:
1. **44-59行**: `draw`関数 - ColoredTextWidgetの描画
2. **62-81行**: `handle_input`関数 - キー入力処理
3. **99-107行**: `exit`関数 - 終了時の値返却

#### Step 3: カーソル操作を理解する

CursorMoveHandlerトレイト実装を追う。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | preview.rs | `crates/nu-explore/src/explore/views/preview.rs` | CursorMoveHandler実装（110-122行） |

**主要処理フロー**:
- **114-117行**: `handle_left` - 左スクロール（ウィンドウ幅の半分）
- **118-121行**: `handle_right` - 右スクロール（ウィンドウ幅の半分）

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

```
explore コマンド（文字列）/ e キー
    |
    +-- Preview::new()                   [preview.rs:27]
            |
            +-- lines() でテキストを行分割
            +-- タブをスペース4つに変換
            +-- WindowCursor2D::new()

Preview::draw()                          [preview.rs:44]
    |
    +-- set_window_size()                カーソルにウィンドウサイズ設定
    |
    +-- lines[cursor.window_origin().row..]  表示開始行を取得
    |
    +-- ColoredTextWidget::new()
    |       +-- get_plain_text()         検索用のプレーンテキスト取得
    |
    +-- f.render_widget()
    +-- layout.push()                    検索用にテキストを登録

Preview::handle_input()                  [preview.rs:62]
    |
    +-- handle_input_key()               [CursorMoveHandler]
            |
            +-- set_status_top() / set_status_end()
```

### データフロー図

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

String（テキスト） ───────▶ Preview::new()
                            │
                            ▼
                      lines() で行分割
                      タブ→スペース変換
                            │
                            ▼
                      draw()
                            │
                            ▼
                      ColoredTextWidget ─────────────▶ TUI画面描画
                            │                          - テキスト行
                            │
                      handle_input()
                            │
                            ▼
                      cursor更新 ───────────────────▶ 表示位置変更
                            │
                      exit()
                            │
                            ▼
                      underlying_value or ──────────▶ Value返却
                      lines.join("\n")
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| preview.rs | `crates/nu-explore/src/explore/views/preview.rs` | ソース | プレビューのコア実装 |
| colored_text_widget.rs | `crates/nu-explore/src/explore/views/colored_text_widget.rs` | ソース | ANSIカラー対応テキストウィジェット |
| cursor/mod.rs | `crates/nu-explore/src/explore/views/cursor/mod.rs` | ソース | カーソル管理 |
| window_cursor_2d.rs | `crates/nu-explore/src/explore/views/cursor/window_cursor_2d.rs` | ソース | 2Dカーソル実装 |
| report.rs | `crates/nu-explore/src/explore/pager/report.rs` | ソース | ステータスレポート |
