# 機能設計書 56-ブールウィジェット

## 概要

本ドキュメントは、Decap CMSにおけるブールウィジェット（Boolean Widget）の設計を記述する。トグルスイッチによるtrue/false入力ウィジェットである。

### 本機能の処理概要

**業務上の目的・背景**：CMSで管理するコンテンツには、公開/非公開フラグ・注目記事フラグ・機能有効化フラグなど、真偽値（boolean）の入力が必要なフィールドがある。本ウィジェットはトグルスイッチUIを提供し、視覚的にtrue/falseの状態を切り替えられるようにする。

**機能の利用シーン**：エントリ編集画面・エントリ新規作成画面において、`widget: boolean`が指定されたフィールドに対してトグルスイッチをレンダリングする。デフォルト値はfalseである。

**主要な処理内容**：
1. Toggleコンポーネント（decap-cms-ui-default）によるトグルスイッチのレンダリング
2. アクティブ/非アクティブ状態に応じた背景色の変更
3. 入力値の変更時にonChangeコールバックで親コンポーネントにブール値を通知

**関連システム・外部連携**：decap-cms-ui-defaultパッケージのToggle、ToggleBackground、colorsコンポーネントに依存。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | エントリ編集画面 | 主機能 | ブールフィールドのトグル操作 |
| 7 | エントリ新規作成画面 | 主機能 | ブールフィールドのトグル操作 |

## 機能種別

UI入力コンポーネント

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| field | ImmutableMap | Yes | フィールド設定 | - |
| onChange | function | Yes | 値変更時のコールバック関数 | - |
| classNameWrapper | string | Yes | ラッパーのCSSクラス名 | - |
| setActiveStyle | function | Yes | フォーカス時のスタイル設定関数 | - |
| setInactiveStyle | function | Yes | ブラー時のスタイル設定関数 | - |
| forID | string | No | トグル要素のid属性 | - |
| value | boolean | No | 現在のブール値（デフォルト: false） | - |

### 入力データソース

エディタのコントロールペインから提供されるprops。

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| value | boolean | トグルの状態（true/false） |

### 出力先

onChangeコールバック経由でReduxストアのエントリドラフトに反映される。

## 処理フロー

### 処理シーケンス

```
1. Toggleコンポーネントをレンダリング
   └─ active={value} でトグル状態を表示
   └─ BooleanBackground でアクティブ/非アクティブの背景色を設定
2. ユーザーがトグルをクリック
   └─ onChangeコールバックが直接呼び出される
3. 値が親コンポーネントに伝達
   └─ Reduxストアのドラフト更新
```

### フローチャート

```mermaid
flowchart TD
    A[Toggle レンダリング] --> B{active状態?}
    B -->|true| C[colors.active 背景]
    B -->|false| D[colors.textFieldBorder 背景]
    C --> E[ユーザークリック]
    D --> E
    E --> F[onChange呼び出し]
    F --> G[Reduxドラフト更新]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-56-01 | デフォルト値 | valueが未指定の場合はfalseをデフォルト値とする | value prop未指定時 |
| BR-56-02 | アクティブ色 | トグルがアクティブ（true）の場合はcolors.active、非アクティブ（false）の場合はcolors.textFieldBorderを背景色とする | 常時 |

### 計算ロジック

特になし。

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

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

該当なし。

## エラー処理

### エラーケース一覧

特にエラー処理は実装されていない。トグルスイッチは常にtrue/falseの二値のみを取るため、不正な値が入ることはない。

### リトライ仕様

該当なし。

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

該当なし。

## パフォーマンス要件

特になし。

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

特になし。トグルスイッチはブール値のみを扱うため、インジェクション等のリスクはない。

## 備考

- プレビューコンポーネントは提供されていない（index.jsにpreviewComponentが含まれていない）
- @emotion/reactによるCSSスタイリングを使用

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.js | `packages/decap-cms-widget-boolean/src/index.js` | Widget関数がname: 'boolean'でcontrolComponentのみを返す（previewComponent不在）。4-9行目 |

**読解のコツ**: 他のウィジェットと異なり、previewComponentが登録されていない。これはブール値のプレビュー表示が単純なため、デフォルトのプレビュー処理に委譲されている可能性がある。

#### Step 2: コントロールコンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | BooleanControl.js | `packages/decap-cms-widget-boolean/src/BooleanControl.js` | BooleanBackgroundのカスタムスタイル（7-16行目）とBooleanControlのrender（19-34行目） |

**主要処理フロー**:
1. **1-5行目**: import - Toggle, ToggleBackground, colorsをdecap-cms-ui-defaultから取得
2. **7-16行目**: BooleanBackground - isActiveに基づく背景色切替（colors.active vs colors.textFieldBorder）
3. **18-35行目**: BooleanControl - Reactクラスコンポーネント
4. **20-21行目**: render内のprops取得（value, forID, onChange等）
5. **24-31行目**: Toggleコンポーネントにactive={value}, onChange, Background={BooleanBackground}を渡す
6. **37-45行目**: PropTypes定義（value: PropTypes.bool）
7. **47-49行目**: defaultProps（value: false）

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

```
DecapCmsWidgetBoolean (index.js)
    |
    └── Widget()
            └── { name: 'boolean', controlComponent }
                    |
                    └── BooleanControl (BooleanControl.js)
                            +-- render()
                            |       └── Toggle (decap-cms-ui-default)
                            |               └── BooleanBackground
                            |                       └── isActive ? colors.active : colors.textFieldBorder
                            └── onChange - 直接Toggle経由
```

### データフロー図

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

ユーザークリック  ──> Toggle onChange ──> onChange(boolean)
                                            |
                                            v
                                     Reduxドラフト更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.js | `packages/decap-cms-widget-boolean/src/index.js` | ソース | ウィジェットエクスポート定義 |
| BooleanControl.js | `packages/decap-cms-widget-boolean/src/BooleanControl.js` | ソース | トグルスイッチコントロール |
