# #042 Button — HTML Functional Class

Version: 1.0.12

## 1. 正式な意味

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

Marker: `bone-html-class-use`

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

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

`getState / setLabel / execute / connectOutput` など第1引数が `element` のAPIには、任意のdivではなく **`BoneButton.create()` が返した `.bone-button` root** を渡します。HTMLから既存instanceを渡す場合は `$id:...` または `$selector:...` を使います。GuideのLive Runも先に専用instanceを生成・確認してから実APIを呼びます。

## 3. Class共通引数契約

| 設定 / Token | 意味 | いつ使うか | Default | 例 |
|---|---|---|---|---|
| class | HTML class属性。`bone-html-class-use` + 対象Class | Functional Classを有効化 | — | `class="bone-html-class-use bone-button-set-label"` |
| data-bone-event | 実行イベント | 自動実行タイミング | load | `click` / `change` / `manual` |
| data-bone-args | 全引数JSON配列 | 複数引数を一括指定 | [] | `["$id:my-button","保存"]` |
| data-bone-arg-N | index別引数 | 引数を個別指定 | 未指定 | `data-bone-arg-0="$id:my-button"` |
| data-bone-once | event listenerをonce登録 | 1回だけ実行 | false | `true` |
| data-bone-append-result | HTMLElement戻り値をhostへappend | create等のDOM戻り値 | true | `false`で自動appendしない |
| data-bone-throw | 記録したエラーを非同期rethrow | caller側例外監視 | false | `true` |
| $self | Class指定DOM要素 | host自身を渡す | — | `$self` |
| $event | 発火Event | Eventを渡す | null | `$event` |
| $value | 要素.value | input/select値 | undefined | `$value` |
| $checked | 要素.checked | boolean入力 | undefined | `$checked` |
| $text | textContent | 表示文字 | undefined | `$text` |
| $dataset | dataset copy | data-*をobjectで渡す | {} | `$dataset` |
| $files | FileList | file input | null | `$files` |
| $selector:... | querySelector結果 | CSS selector参照 | null | `$selector:#panel .bone-button` |
| $id:... | getElementById結果 | 生成済みButton instance root参照 | null | `$id:my-button` |
| $global:... | globalThis値 | 共有object | undefined | `$global:ButtonOutputOptions` |
| $handler:... | globalThis function | execute/guard等callback | undefined | `$handler:onSave` |

## 4. 35 Functional Class一覧

| Functional Class | Public API | 用途 | 引数 / 型 | Default | Result | 使用場所 |
|---|---|---|---|---|---|---|
| `bone-button-defaults` | `BoneButton.defaults` | 既定Propertyを取得 | なし | 引数なし | Property object | Property / Preview / 利用側HTML |
| `bone-button-normalize-options` | `BoneButton.normalizeOptions` | Property入力を安全な正規形へ変換 | `options`: plain object（`label / pressedLabel / tooltip / shape / normalColor / normalImage / pressedImage / icon / iconPosition / mode / Parent / Effect...`） | options省略項目は `BoneButton.defaults()` | `BoneButton.normalizeOptions()` の戻り値 | Property / Preview / 利用側HTML |
| `bone-button-normalize-bone` | `BoneButton.normalizeBone` | BUTTON Boneを検査・正規化 | `bone`: plain object `{id,type:"BUTTON",value}` | 必須引数は省略不可。Property省略はAPI契約に従う | `BoneButton.normalizeBone()` の戻り値 | Property / Preview / 利用側HTML |
| `bone-button-normalize-command` | `BoneButton.normalizeCommand` | Command契約を検査・正規化 | `command`: plain object `{id,execute,canExecute?}` / `expectedId`: string (command.id照合) | expectedId空文字ならID一致強制なし | `BoneButton.normalizeCommand()` の戻り値 | Property / Preview / 利用側HTML |
| `bone-button-inspect-untrusted-input` | `BoneButton.inspectUntrustedInput` | Untrusted INを副作用なしで検査 | `payload`: plain object `{value:string}` | 必須引数は省略不可。Property省略はAPI契約に従う | `{accepted,blocked,code,message,value?}` | Untrusted IN / Security Sandbox |
| `bone-button-create` | `BoneButton.create` | Button instanceを生成 | `bone`: plain object `{id,type:"BUTTON",value}` / `options`: plain object（`label / pressedLabel / tooltip / shape / normalColor / normalImage / pressedImage / icon / iconPosition / mode / Parent / Effect...`） | options未指定項目は `BoneButton.defaults()` | HTMLElement `.bone-button` | Property / Preview / 利用側HTML |
| `bone-button-destroy` | `BoneButton.destroy` | instanceとEffect/OUTを破棄 | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) | 必須引数は省略不可。Property省略はAPI契約に従う | `BoneButton.destroy()` の戻り値 | Property / Preview / 利用側HTML |
| `bone-button-is-instance` | `BoneButton.isInstance` | BoneButton instanceか判定 | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) | 必須引数は省略不可。Property省略はAPI契約に従う | boolean | Property / Preview / 利用側HTML |
| `bone-button-get-button` | `BoneButton.getButton` | 内部button controlを取得 | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) | 必須引数は省略不可。Property省略はAPI契約に従う | native `<button>` control | Property / Preview / 利用側HTML |
| `bone-button-get-state` | `BoneButton.getState` | 現在Stateを取得 | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) | 必須引数は省略不可。Property省略はAPI契約に従う | Button State object | Property / Preview / 利用側HTML |
| `bone-button-get-options` | `BoneButton.getOptions` | 現在Propertyを取得 | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) | 必須引数は省略不可。Property省略はAPI契約に従う | `BoneButton.getOptions()` の戻り値 | Property / Preview / 利用側HTML |
| `bone-button-set-options` | `BoneButton.setOptions` | Propertyを部分更新 | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) / `patch`: plain object (変更Propertyのみ) | 必須引数は省略不可。Property省略はAPI契約に従う | `BoneButton.setOptions()` の戻り値 | Property / Preview / 利用側HTML |
| `bone-button-get-bone` | `BoneButton.getBone` | 現在Boneを取得 | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) | 必須引数は省略不可。Property省略はAPI契約に従う | `BoneButton.getBone()` の戻り値 | Property / Preview / 利用側HTML |
| `bone-button-set-bone` | `BoneButton.setBone` | BUTTON Boneを差し替え | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) / `bone`: plain object `{id,type:"BUTTON",value}` | 必須引数は省略不可。Property省略はAPI契約に従う | `BoneButton.setBone()` の戻り値 | Property / Preview / 利用側HTML |
| `bone-button-get-label` | `BoneButton.getLabel` | 表示文字を取得 | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) | 必須引数は省略不可。Property省略はAPI契約に従う | `BoneButton.getLabel()` の戻り値 | Property / Preview / 利用側HTML |
| `bone-button-set-label` | `BoneButton.setLabel` | 表示文字を変更 | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) / `label`: string (1..240 / ASCII制御文字不可) | 必須引数は省略不可。Property省略はAPI契約に従う | `BoneButton.setLabel()` の戻り値 | Property / Preview / 利用側HTML |
| `bone-button-get-mode` | `BoneButton.getMode` | Normal/Command modeを取得 | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) | 必須引数は省略不可。Property省略はAPI契約に従う | `BoneButton.getMode()` の戻り値 | Property / Preview / 利用側HTML |
| `bone-button-set-mode` | `BoneButton.setMode` | Normal/Command modeを切替 | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) / `mode`: `"normal" \| "command"` | 必須引数は省略不可。Property省略はAPI契約に従う | `BoneButton.setMode()` の戻り値 | Property / Preview / 利用側HTML |
| `bone-button-get-command` | `BoneButton.getCommand` | 接続Command概要を取得 | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) | 必須引数は省略不可。Property省略はAPI契約に従う | `BoneButton.getCommand()` の戻り値 | Preview / Command mode (#044責務統合) |
| `bone-button-set-command` | `BoneButton.setCommand` | Commandを接続 | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) / `command`: plain object `{id,execute,canExecute?}` | 必須引数は省略不可。Property省略はAPI契約に従う | `{id,hasCanExecute} \| null` | Preview / Command mode (#044責務統合) |
| `bone-button-refresh-command-state` | `BoneButton.refreshCommandState` | canExecuteを再評価 | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) | 必須引数は省略不可。Property省略はAPI契約に従う | `BoneButton.refreshCommandState()` の戻り値 | Preview / Command mode (#044責務統合) |
| `bone-button-execute` | `BoneButton.execute` | Button/Commandを実行 | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) / `source`: string (実行/OUT元) | source = `"user"` | `{executed,result,output,delivery}` または Promise | Preview / Command mode (#044責務統合) |
| `bone-button-click` | `BoneButton.click` | 実button clickを発火 | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) | 必須引数は省略不可。Property省略はAPI契約に従う | `BoneButton.click()` の戻り値 | Property / Preview / 利用側HTML |
| `bone-button-set-disabled` | `BoneButton.setDisabled` | disabledを変更 | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) / `disabled`: boolean | 必須引数は省略不可。Property省略はAPI契約に従う | `BoneButton.setDisabled()` の戻り値 | Property / Preview / 利用側HTML |
| `bone-button-build-output` | `BoneButton.buildOutput` | OUT payloadを生成 | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) / `source`: string (実行/OUT元) / `actionResult`: any (execute結果) | 必須引数は省略不可。Property省略はAPI契約に従う | `BoneButton.buildOutput()` の戻り値 | #002 OUT / WAIT / FIFO / BLOCKED |
| `bone-button-connect-output` | `BoneButton.connectOutput` | #002 Delivery Channelへ接続 | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) / `options`: plain object（`label / pressedLabel / tooltip / shape / normalColor / normalImage / pressedImage / icon / iconPosition / mode / Parent / Effect...`） | targetReady=true / guard=null / deliver=no-op / onStateChange=null | #002 Delivery state | #002 OUT / WAIT / FIFO / BLOCKED |
| `bone-button-disconnect-output` | `BoneButton.disconnectOutput` | OUT接続を解除 | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) | 必須引数は省略不可。Property省略はAPI契約に従う | `BoneButton.disconnectOutput()` の戻り値 | #002 OUT / WAIT / FIFO / BLOCKED |
| `bone-button-set-target-ready` | `BoneButton.setTargetReady` | Target READY/BUSYを#002へ通知 | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) / `ready`: boolean | 必須引数は省略不可。Property省略はAPI契約に従う | `BoneButton.setTargetReady()` の戻り値 | #002 OUT / WAIT / FIFO / BLOCKED |
| `bone-button-clear-output-block` | `BoneButton.clearOutputBlock` | #002 BLOCK状態を解除 | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) | 必須引数は省略不可。Property省略はAPI契約に従う | `BoneButton.clearOutputBlock()` の戻り値 | #002 OUT / WAIT / FIFO / BLOCKED |
| `bone-button-get-output-state` | `BoneButton.getOutputState` | WAIT/BLOCK/queue状態を取得 | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) | 必須引数は省略不可。Property省略はAPI契約に従う | #002 Delivery state | #002 OUT / WAIT / FIFO / BLOCKED |
| `bone-button-get-output-queue` | `BoneButton.getOutputQueue` | 待機queueを取得 | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) | 必須引数は省略不可。Property省略はAPI契約に従う | WAIT queue copy | #002 OUT / WAIT / FIFO / BLOCKED |
| `bone-button-apply-joint-input` | `BoneButton.applyJointInput` | Security検査後にJoint INを適用 | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) / `payload`: plain object `{value:string}` | 必須引数は省略不可。Property省略はAPI契約に従う | `{accepted,blocked,code,message,...}` | Untrusted IN / Security Sandbox |
| `bone-button-validate` | `BoneButton.validate` | 現在Button状態をValidation | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) | 必須引数は省略不可。Property省略はAPI契約に従う | `{valid,issues[]}` | Property / Preview / 利用側HTML |
| `bone-button-sync-parent-style` | `BoneButton.syncParentStyle` | 親要素styleを再同期 | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) | 必須引数は省略不可。Property省略はAPI契約に従う | `BoneButton.syncParentStyle()` の戻り値 | Parent Preview / 親要素依存 |
| `bone-button-set-feedback` | `BoneButton.setFeedback` | 表示feedbackを設定 | `element`: HTMLElement (`BoneButton.create()` が返した `.bone-button` root) / `feedback`: plain object \| null `{code?,message}` | nullで解除 | `BoneButton.setFeedback()` の戻り値 | Property / Preview / 利用側HTML |

## 5. HTML設定例 — create

```html
<div id="button-create-host"
  class="bone-html-class-use bone-button-create"
  data-bone-event="manual"
  data-bone-args='[{"id":"save","type":"BUTTON","value":"保存"},{"label":"保存","pressedLabel":"処理中","tooltip":"保存します","shape":"raised","normalColor":"#2563eb","mode":"normal"}]'>
</div>
```

`BoneButtonHTMLClass.invoke(host, "bone-button-create", args)` を実行すると、返された `.bone-button` instanceがhostへappendされ、Result/Stateが記録されます。

## 6. HTML設定例 — 生成済みinstanceへ setLabel

```html
<div class="bone-html-class-use bone-button-set-label"
  data-bone-event="click"
  data-bone-arg-0="$id:my-button"
  data-bone-arg-1="新しい表示">
  label変更
</div>
```

`my-button` は `BoneButton.create()` が返したroot自身に付けたIDです。

## 7. Command mode (#044責務統合)

#044を別Runtimeとして作らず、#042 `mode="command"` で扱います。`setCommand()` へ `{id, execute, canExecute?}` を接続し、`refreshCommandState()` で `canExecute` を再評価、`execute()` でCommand結果をOUTへ渡します。

## 8. Untrusted IN / Security

`inspectUntrustedInput()` は副作用なしの検査、`applyJointInput()` はACCEPTED時だけSecurity専用Buttonのlabelへ反映します。null / number / object / accessor / ASCII制御文字はBLOCKED。通常Preview / Security Sandbox / WAIT-BLOCK / Class Live Runを混線させません。HTML風文字列は `textContent` として文字列扱いし、HTML実行しません。

## 9. OUT / WAIT / FIFO / BLOCKED

`connectOutput()` 以降のqueue・READY/BUSY・BLOCKED配送は #002 Bone Joint v1.1.36へ委譲します。#042は#002のDelivery Channelを再実装しません。

## 10. Parent / Effect / ColorPicker責務

- Parent: `inheritParent / fit / position` と `syncParentStyle()`。親DOMそのものは変更しません。
- Active / Mouse Over Effect: #022 v1.0.10へ委譲。
- 色選択UI: #040 ColorPicker v1.0.15 `attachCaller()` を利用。Normal色 / Pressed text色は `solid + gradient`、Parent / Effect色は `solid`。#042は色Propertyの意味・値・Validationを保持します。

## 11. Browser Class Guide

Test pageの「Class Guideを開く」は、左に35 Class一覧、右に選択Classの **API / 用途 / いつ使うか / 使用場所 / 引数と型 / Default / HTML設定 / 実行方法 / 実際の結果 / Result-State / 責務境界 / 使用状況 / JavaScript例 / HTML例 / Live Run** を表示します。


## 12. Button表示Property

`normalizeOptions / create / setOptions` の `options` で次を扱います。

- `shape`: `normal | square | raised | image`
- `normalColor`: `#RRGGBB` または #040 `GRADIENT_V1` object
- `normalImage`: Normal画像Source。Property UIでは#039 FilePickerで選択。`default` は標準画像。
- `pressedImage`: Pressed画像Source。Property UIでは#039 FilePickerで選択。`default-pressed` は標準押下画像。
- `icon`: #019 Bone Imageのicon用途value。
- `iconPosition`: `top | bottom | left | right`。
- `pressedLabel`: 押下中の文字列。空なら通常label。
- `tooltip`: Tooltip text。

ボタン画像の**選択は#039 FilePicker**、画像描画とボタンアイコン設定/描画は#019 Bone Image、Normal色選択UIは#040 ColorPickerへ委譲します。Functional Class側で別のFilePicker/Image/Color処理を作りません。


## v1.0.6 correction
- Class List / HTML Functional Class is restored immediately after Button Preview / API and before Security.
- Normal color delegates to #040 ColorPicker with solid + GRADIENT_V1.
- Button runtime accepts #040 GRADIENT_V1 and converts it with BoneColorPicker.gradientToCss().
- #019 Image icon flow uses only the Image Editor native Font Awesome list. #042 enhances that same list with visible Glyph / 60-item paging / release / current selection status; no second catalog is rendered.
- #039 Normal / Pressed image picker, Parent, #022 effects, Security, Connection Image, WAIT/FIFO/BLOCKED, Smoke/Validation and Completion are retained.

## v1.0.9 correction

- Fixed Preview overflow where the #019/#018 standalone icon container could push the Button label outside the control.
- Icon + Text stay inside the Button for top / bottom / left / right positions.
- Added Browser Runtime bounds checks for this exact regression.