# Bone Flow #045 ToggleButton Specification v1.0

Component: #045 ToggleButton  
Implementation Version: 1.0.12  
Status: Development

## 1. Component責務

#045はAction UIとして、押下操作によるboolean状態の保持・反転、ToggleButton表示、OUT生成までを担当します。

`OFF ⇄ ON`

#035 SwitchのInput UI責務を複製せず、#042 ButtonのImage / FilePicker責務も持ち込みません。

## 2. Bone契約

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

- `id`: string
- `type`: `TOGGLE_BUTTON`
- `value`: boolean
- 非boolean値の暗黙変換は禁止

## 3. Property

### ToggleButton固有

- `checked: boolean`
- `checkedLabel: string`
- `uncheckedLabel: string`
- `displayPattern: standard | soft-rounded | text | icon | button`
- `checkedColor: #RRGGBB | #040 GRADIENT_V1`
- `uncheckedColor: #RRGGBB | #040 GRADIENT_V1`
- `thumbColor: #RRGGBB | #040 GRADIENT_V1`
- `disabled: boolean`
- `tooltip: string`
- `theme: default | dark | light | neon`

### Layout

- `inheritParent: boolean`
- `fit: boolean`
- `width: number`
- `height: number`
- `position`: 正式9方向

### Active Effect

- `activeBorderEffect: normal | neon | spin | cross | blink`
- `activeEffectColor: theme | #RRGGBB`
- `activeEffectDirection: clockwise | counterclockwise`
- `activeEffectSpeed: slow | normal | fast`

### Mouse Over Effect

- `mouseoverBorderEffect: normal | neon | spin | cross | blink`
- `mouseoverEffectColor: theme | #RRGGBB`
- `mouseoverEffectDirection: clockwise | counterclockwise`
- `mouseoverEffectSpeed: slow | normal | fast`

## 4. 表示Pattern

#035完成版の表示責務を参照し、5Patternを保持します。

- `standard`
- `soft-rounded`
- `text`
- `icon` — ON=`✓` / OFF=`○`
- `button`

Patternは表示だけを変更し、boolean状態・Security・OUT契約を変更しません。

## 5. #040 ColorPicker契約

色Propertyは **色トリガークリック → #040 Picker表示** の正式Caller方式です。

ON / OFF / Thumb:

`allowedKinds: ["solid", "gradient"]`

Parent / Effect:

`allowedKinds: ["solid"]`

Gradient対応はコード存在だけでは確認済みにしません。Browser QAではPickerを実際に開き、Gradient見出し・8 preset表示・Gradient選択・Caller RETURN・Toggle表示反映まで確認対象とします。

## 6. Parent / FIT

- Parent依存OFF / FIT OFF: standalone `width / height / 9方向`
- `fit=true`: 実Trackまで親領域へ追従
- `inheritParent=true`: 親computed styleを `syncParentStyle()` で同期
- 親DOM自体を#045が改変しない

## 7. #022 Effect

ActiveとMouse Overを別attachとして扱います。

- root: `trigger:"active"`
- internal button: `trigger:"mouseover"`

Activeはfocus/active条件のみです。ON / `value=true` をActive条件にしません。

## 8. Untrusted IN / Security

`inspectUntrustedInput()` / `applyJointInput()` はplain objectのown data property `value:boolean` のみACCEPTします。

getter / setterは実行しません。型不一致はBLOCKし、直前値を保持します。Security Sandboxは通常Preview・Deliveryと分離します。

`disabled=true` はユーザー操作/API toggleを停止しますが、SecurityでACCEPT済みの #002 Joint IN は状態へ反映します。

## 9. #002 Connection / Delivery

接続イメージは #002で5ケースを評価・描画します。

OUTは #002 `createDeliveryChannel()` の戻り値へ `deliver(output)` します。

- WAIT: Target Busy
- FIFO: queue順配送
- BLOCKED: guard reject、接続維持、Target非到達

#045内部に並列queueや `.send()` APIを作りません。

`connectOutput(element, options)` の `options` は省略/nullまたはplain objectのみを許可します。配列・DOM・Date等の非plain objectは `TOGGLEBUTTON_OUTPUT_OPTIONS_INVALID` で拒否します。

## 10. HTML Functional Class

Marker: `bone-html-class-use`

29 Public APIすべてに `bone-togglebutton-*` Classを1:1で公開します。

Bridgeは以下を保持します。

- `data-bone-event`
- `data-bone-args`
- `data-bone-arg-N`
- `data-bone-once`
- `data-bone-append-result`
- `data-bone-throw`
- `$self / $event / $value / $checked / $text / $dataset / $files / $selector: / $id: / $global: / $handler:`
- `data-bone-class-status`
- `data-bone-class-result`
- `scan / bind / MutationObserver`

Direct `HTMLElement / Event / FileList` を `invoke()` 引数として渡した場合はplain objectへ潰さず、その実体を保持します。

## 11. Guide

Class GuideはClass名一覧だけにしません。Overviewと全29 Classについて次を表示します。

- 対応Public API
- 用途
- いつ使うか
- 使用場所
- 引数 / 型
- 許可値
- Default
- HTML設定
- 実行方法
- 実際のResult
- Result / State
- 責務境界
- 現在の使用状況
- JavaScript例
- HTML例
- Guide専用instanceによるLive Run

Guide専用instanceは通常Preview / Security / Deliveryと分離します。

## 12. Property言語

日本語 / EnglishをProperty全体へ適用します。Group説明、全label、select option、Effect方向・速度も言語切替対象です。API valueは変更しません。

## 13. Smoke / Validation / Report / Runtime Console

- 初期状態: NOT RUN
- Smoke / Validation個別実行
- 全テスト実行
- 件数 / PASS / FAIL / duration表示
- JSON / Markdown Report保存
- Runtime Console保持
- browser error / unhandled rejection監視

## 14. Completion

Completion条件:

1. Runtime Test ALL PASS
2. WAIT目視確認
3. BLOCK目視確認
4. ユーザー操作でCompletion

ユーザーlocalhost Browser Runtime確認前は正式Completedにしません。

## 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は変更しない。