# Bone Flow #045 ToggleButton

Version: 1.0.12  
Status: Development

## 1. 役割

#045 ToggleButton は **Action UI** のToggleButtonです。Button操作で `OFF ⇄ ON` を切り替え、状態を `boolean` として保持します。

Bone契約:

`{ id: string, type: "TOGGLE_BUTTON", value: boolean }`

string / number / object をbooleanへ暗黙変換しません。

## 2. 使用 / 参照コンポーネント

- #001 Bone Core v1.0.0 — Bone基盤
- #002 Bone Joint v1.1.36 — 接続判定・描画・WAIT / FIFO / BLOCKED Delivery
- #017 Bone Text v1.0.34 — #040表示スタックで使用
- #020 Bone Label v1.0.61 — #040 / 共通UI・QA基準
- #022 Bone Hover Border Effect v1.0.10 — Active / Mouse Over Effect
- #040 Bone ColorPicker v1.0.15 — 色トリガーから開く正式Caller API

#019 Image / #039 FilePicker / #042 Button は #045 の直接Runtime依存ではありません。

## 3. 表示Pattern

正式表示Patternは5種類です。

1. `standard` — Track + moving Thumb
2. `soft-rounded` — 角丸弱め
3. `text` — ON / OFF文字入り
4. `icon` — 状態アイコン入り（ON=`✓` / OFF=`○`）
5. `button` — ボタン型。Thumbを表示せず状態文字を表示

Patternを変更してもBoneの `value:boolean` 契約は変わりません。

## 4. ColorPicker

Property内に独自ColorPickerを作りません。色見本をクリックして #040 `BoneColorPicker.attachCaller()` を開きます。

- ON色: solid + gradient
- OFF色: solid + gradient
- Thumb色: solid + gradient
- Parent背景 / Parent文字: solid
- Active Effect色 / Mouse Over Effect色: solid

Gradientは #040 `GRADIENT_V1` を保持し、#040 `gradientToCss()` で表示へ変換します。

## 5. Parent / FIT / 9方向

- 単体時: `width / height / position`
- 9方向: `top-left / top-center / top-right / middle-left / center / middle-right / bottom-left / bottom-center / bottom-right`
- `inheritParent=true`: 親styleを参照
- `fit=true`: rootだけでなく実際のTrack視覚も親領域へフィット

## 6. Effect

#022へ委譲します。ActiveとMouse Overは独立です。

- Effect: `normal / neon / spin / cross / blink`
- Direction: `clockwise / counterclockwise`
- Speed: `slow / normal / fast`

Active Effectは **focus / active時だけ** 有効です。ON / `checked=true` とは連動しません。

## 7. Security

Untrusted INは通常Previewとは独立したSecurity Sandboxで検査します。

- own data property `value:boolean` のみACCEPT
- string / number / objectはBLOCK
- accessor/getterは実行せずBLOCK
- BLOCK時は直前値を保持
- `disabled` はユーザー操作/API toggleを止める表示・操作状態であり、SecurityでACCEPTされた #002 Joint IN は反映する

## 8. 接続イメージ

#002 `BoneJoint.evaluate()` / `drawLine()` を使用し、5ケースを独立表示します。

1. 正常IN / OUT
2. IN Target Field不存在
3. OUT Target Field不存在
4. IN型不一致
5. OUT型不一致

## 9. OUT WAIT / FIFO / BLOCKED

#045は独自queueを作らず #002 `createDeliveryChannel()` へ委譲します。送信は正式な `channel.deliver(output)` を使用します。

- Target Busy → WAIT
- WAIT中OUT → FIFO queue
- Target Ready → FIFO順に自動配送
- guard拒否 → BLOCKED、接続維持、Target非到達
- `connectOutput()` のoptionsは省略/nullまたはplain objectのみ。配列・DOM・Date等は拒否

## 10. Public API

`defaults`, `normalizeOptions`, `normalizeBone`, `inspectUntrustedInput`, `create`, `destroy`, `isInstance`, `getButton`, `getState`, `getOptions`, `setOptions`, `getBone`, `setBone`, `getChecked`, `setChecked`, `toggle`, `click`, `setDisabled`, `buildOutput`, `connectOutput`, `disconnectOutput`, `setTargetReady`, `clearOutputBlock`, `getOutputState`, `getOutputQueue`, `applyJointInput`, `validate`, `syncParentStyle`, `setFeedback`。

合計29 API。HTML Functional Classも29件で1:1対応します。

## 11. Runtime QA / Report / Completion

Smoke / Validationは初期状態をNOT RUNとします。Runtime Console、JSON/MD Report保存、WAIT/BLOCK目視確認、Completion管理を保持します。

Package / Node / Static確認はBrowser Runtime ALL PASSの代替にはなりません。ユーザーlocalhost確認前はBrowser ALL PASS / Completed / Specification Frozenにしません。

## v1.0.10 defect correction

- ToggleButton固有の `checkedLabel` / `uncheckedLabel` を default `standard` / `soft-rounded` でも実表示し、ON/OFF表示文字が消える退行を修正。
- Smoke / Validationが通常Previewのchecked/Effect/FIT/Feedback/disabled状態を変更しないようQA用instanceへ分離。
- Smokeのみ/Validationのみ実行時は `0 FAIL` ではなく `INCOMPLETE` と表示し、個別実行時間も更新。
- HTML Functional Class Guide Live Runは戻り値HTMLElementをGuide hostへ自動appendしない。各実行前にGuide専用instanceを初期化し、実UIは最大1 instanceに固定。


### BLOCKED test oracle correction

- BLOCK demo guard is the completed-component formal rejection shape `{allowed:false, reason, code}`.
- Manual BLOCK operation passes only when the real #002 output state is `blocked` and Target receive count does not increase.
- Smoke S23 executes the same live BLOCK route.
- Validation V44 verifies the formal guard contract and V45 executes the same live BLOCK UI route.
- Overall `ALL PASS` requires both explicit BLOCK checks in addition to zero failures. A suite that never proves BLOCKED cannot report ALL PASS.
- Completion still requires separate user WAIT / BLOCK visual confirmation.


## v1.0.10 OUT WAIT correction

- Manual OUT WAIT確認は `getOutputQueue()` 内部item形状へ依存しない。
- 正式#002状態契約 `getOutputState().state` / `queueLength` でWAIT成立を判定する。
- READY復帰後はTarget受信件数とFIFO `true → false → true`、最終 `ready / queueLength=0` を確認してから目視チェックを有効化する。
- Smoke / ValidationのALL PASSにはWAIT/FIFO実動作ゲートとBLOCKED実動作ゲートの両方を必須とする。


## v1.0.12 Completion correction

- Smoke / ValidationのBLOCK回帰テストは手動Delivery UIを使用せず、QA専用ToggleButton / #002 Delivery Channelで隔離実行する。
- Smoke / Validation実行によってユーザーのWAIT/BLOCK目視確認チェックを解除・初期化しない。
- Completion管理にはRuntime QA / WAIT目視 / BLOCK目視を常時表示する。
- `コンポーネント完了` は Runtime ALL PASS + WAIT確認済み + BLOCK確認済み + 未完了 の時だけ有効化する。
- Completion可否判定は `isCompletionReady()` に一本化し、表示とクリック処理で同じ条件を使用する。

## v1.0.12 Completion button state display correction

- Completion前のボタン表示 `コンポーネント完了` を維持する。
- Completion成立後、同じ完了ボタン表示を `完了済み` へ切り替える。
- 完了解除後は `コンポーネント完了` へ戻す。
- Runtime ALL PASS / WAIT / BLOCK / Completion gate、Smoke / Validation、他UIは変更しない。