# #045 ToggleButton — HTML Functional Class

Version: 1.0.12  
Status: Development

## 1. 正式な意味

これはJavaScript `class` の一覧ではありません。HTMLの `class="..."` を入口にして、既存の `BoneToggleButton` Public APIを呼び出す **HTML Functional Class** です。

Marker: `bone-html-class-use`

実行結果はhostの `data-bone-class-status` / `data-bone-class-result` / `__boneClassResult` と、instance系APIでは `BoneToggleButton.getState()` で確認します。

## 2. 最重要 — instanceの渡し方

`getState / setChecked / toggle / connectOutput` など第1引数が `element` のAPIには、任意のdivではなく **`BoneToggleButton.create()` が返した `.bone-togglebutton` root** を渡します。

HTMLから既存instanceを渡す場合は `$id:...` または `$selector:...` を使います。Guide Live Runは通常Preview / Security / Deliveryとは別の専用instanceを生成して実行します。

Direct `invoke()` で `HTMLElement / Event / FileList` を渡す場合はBridgeがその実体を保持し、plain objectへ変換しません。

## 3. Class共通引数契約

| 設定 / Token | 意味 | Default |
|---|---|---|
| `class` | `bone-html-class-use` + 対象Class | — |
| `data-bone-event` | `load / click / input / change / manual` 等 | `load` |
| `data-bone-args` | 全引数JSON配列 | `[]` |
| `data-bone-arg-N` | index別引数 | 未指定 |
| `data-bone-once` | event listenerをonce登録 | `false` |
| `data-bone-append-result` | HTMLElement戻り値をhostへappend | `true` |
| `data-bone-throw` | 記録した同期errorを非同期rethrow | `false` |
| `$self` | Class指定DOM要素 | — |
| `$event` | 発火Event | `null` |
| `$value` | 要素.value | `undefined` |
| `$checked` | 要素.checked | `undefined` |
| `$text` | textContent | `undefined` |
| `$dataset` | dataset copy | `{}` |
| `$files` | FileList。共通Bridge tokenであり#045依存ではない | `null` |
| `$selector:...` | `document.querySelector()` 結果 | `null` |
| `$id:...` | `document.getElementById()` 結果 | `null` |
| `$global:...` | globalThis値 | `undefined` |
| `$handler:...` | globalThis function | `undefined` |

## 4. 29 Functional Class一覧

| Functional Class | Public API | 用途 | 引数 |
|---|---|---|---|
| `bone-togglebutton-defaults` | `BoneToggleButton.defaults` | 既定Propertyを取得 | `なし` |
| `bone-togglebutton-normalize-options` | `BoneToggleButton.normalizeOptions` | Propertyを正規化 | `options` |
| `bone-togglebutton-normalize-bone` | `BoneToggleButton.normalizeBone` | TOGGLE_BUTTON Boneを検証・正規化 | `bone` |
| `bone-togglebutton-inspect-untrusted-input` | `BoneToggleButton.inspectUntrustedInput` | Untrusted INを副作用なしで検査 | `payload` |
| `bone-togglebutton-create` | `BoneToggleButton.create` | ToggleButton instanceを生成 | `bone, options` |
| `bone-togglebutton-destroy` | `BoneToggleButton.destroy` | instance / Effect / OUTを破棄 | `element` |
| `bone-togglebutton-is-instance` | `BoneToggleButton.isInstance` | ToggleButton instanceか判定 | `element` |
| `bone-togglebutton-get-button` | `BoneToggleButton.getButton` | 内部button controlを取得 | `element` |
| `bone-togglebutton-get-state` | `BoneToggleButton.getState` | 現在Stateを取得 | `element` |
| `bone-togglebutton-get-options` | `BoneToggleButton.getOptions` | 現在Propertyを取得 | `element` |
| `bone-togglebutton-set-options` | `BoneToggleButton.setOptions` | Propertyを部分更新 | `element, patch` |
| `bone-togglebutton-get-bone` | `BoneToggleButton.getBone` | 現在Boneを取得 | `element` |
| `bone-togglebutton-set-bone` | `BoneToggleButton.setBone` | Boneを差し替え | `element, bone` |
| `bone-togglebutton-get-checked` | `BoneToggleButton.getChecked` | boolean状態を取得 | `element` |
| `bone-togglebutton-set-checked` | `BoneToggleButton.setChecked` | boolean状態を設定 | `element, value, options` |
| `bone-togglebutton-toggle` | `BoneToggleButton.toggle` | OFF / ONを反転 | `element, options` |
| `bone-togglebutton-click` | `BoneToggleButton.click` | native button clickを発火 | `element` |
| `bone-togglebutton-set-disabled` | `BoneToggleButton.setDisabled` | disabledを変更 | `element, disabled` |
| `bone-togglebutton-build-output` | `BoneToggleButton.buildOutput` | OUT payloadを生成 | `element, source` |
| `bone-togglebutton-connect-output` | `BoneToggleButton.connectOutput` | #002 Delivery Channelへ接続 | `element, options` |
| `bone-togglebutton-disconnect-output` | `BoneToggleButton.disconnectOutput` | OUT接続を解除 | `element` |
| `bone-togglebutton-set-target-ready` | `BoneToggleButton.setTargetReady` | Target READY / BUSYを通知 | `element, ready` |
| `bone-togglebutton-clear-output-block` | `BoneToggleButton.clearOutputBlock` | #002 BLOCK状態を解除 | `element` |
| `bone-togglebutton-get-output-state` | `BoneToggleButton.getOutputState` | Delivery Stateを取得 | `element` |
| `bone-togglebutton-get-output-queue` | `BoneToggleButton.getOutputQueue` | FIFO queueを取得 | `element` |
| `bone-togglebutton-apply-joint-input` | `BoneToggleButton.applyJointInput` | Security後にboolean INを適用 | `element, payload` |
| `bone-togglebutton-validate` | `BoneToggleButton.validate` | 現在状態をValidation | `element` |
| `bone-togglebutton-sync-parent-style` | `BoneToggleButton.syncParentStyle` | 親styleを再同期 | `element` |
| `bone-togglebutton-set-feedback` | `BoneToggleButton.setFeedback` | feedbackを設定 | `element, feedback` |

## 5. Guide表示要件

Test pageのGuideはOverviewだけでなく全29 Classについて、次を表示します。

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

Class名だけを並べたGuideは正式要件を満たしません。

## 6. Result / Error

成功時:

- `data-bone-class-status="ok"`
- `data-bone-class-result` にシリアライズ結果
- `__boneClassResult` に実戻り値

失敗時:

- `data-bone-class-status="error"`
- `data-bone-class-result` に `name / code / message`

Guideは `undefined` を成功扱いしてerrorを隠さず、host statusを見てerror内容を表示します。

## 追加契約確認

- `create` の `options` は省略/null または plain object。配列・DOM・Date等を options として渡した場合は拒否する。
- `setChecked` の `options` は `{emit?: boolean, source?: string}`。既定は `emit=false`。
- `toggle` の `options` は `{emit?: boolean, source?: string}`。既定は `emit=true`。
- `connectOutput` は `{targetReady?, guard?, deliver?, onStateChange?}` のplain objectのみを受理し、#002 `createDeliveryChannel` へ委譲する。配列・DOM・Date等は拒否する。
- `setFeedback(element, null)` は feedback を解除する。
- `applyJointInput` はSecurityでACCEPTされたbooleanを反映する。`disabled=true` でもJoint INは反映し、ユーザー操作停止とIN受理を混同しない。
- `icon` Patternの状態記号はON=`✓` / OFF=`○`。