# Bone Flow #042 Button Specification v1.0

Component: #042 Button
Runtime: `bone-button.js`
Initial implementation version: 1.0.6
Status: Development

## 1. Responsibility

#042 owns Button rendering, click/execute, state, safe Joint IN label updates, and handing executed OUT to #002 Delivery Channel.

#044 CommandButton is integrated rather than implemented as a separate duplicate component. `mode="command"` adds `commandId`, `command.execute`, and optional `command.canExecute` semantics to #042.

## 2. Responsibility boundaries

- #001 Core: Bone creation/normalization foundation.
- #002 Joint: delivery queue, WAIT/FIFO, BLOCK state and line rendering.
- #017 Text v1.0.34: text/display responsibility reference.
- #019 Image v1.0.72: `shape="image"` のNormal / Pressed画像描画、およびButton iconの設定・描画。
- #039 FilePicker v1.0.2: Normal / Pressed button imageファイルの選択。
- #020 Label v1.0.61: common Label/display/QA/Completion responsibility reference used by the formal UI contract.
- #022 Hover Border Effect v1.0.10: Active/focus and mouse-over border effects.
- #040 ColorPicker v1.0.15: Normal色 / Parent色 / Effect色の選択UI via formal Caller API; #042 keeps the Property meaning/value/validation.
- Button does not reimplement #002 WAIT/BLOCK, #022 animation, or #040 picker internals.

## 3. Bone contract

`{ id: string, type: "BUTTON", value: string }`

`value` is the Button label. ASCII control characters are rejected.

## 4. Modes

### normal

`execute()` emits a normal Button action. Caller decides what the click means.

### command

A command object is bound:

- `id: string`
- `execute(context): any | Promise<any>`
- `canExecute(context): boolean` (optional)

`canExecute !== true` disables execution. `execute()` result is included in Button OUT.


## 5. Visual / state properties

Button固有の表示契約:

- `shape`: `normal`（通常） / `square`（□） / `raised`（浮き出し） / `image`（画像）
- `normalColor`: 通常表示時の色。`#RRGGBB` または #040 `GRADIENT_V1` object。Property UIでは#040 ColorPickerを `solid + gradient` で使用。
- `normalImage`: 画像形状のNormal画像。Property UIでは#039 FilePickerから選択し、`default` は標準画像。実描画は#019 Bone Imageへ委譲。
- `pressedImage`: 画像形状の押下時画像。Property UIでは#039 FilePickerから選択し、`default-pressed` は標準押下画像。
- `icon`: #019 Bone Imageのicon用途value。Button iconの選択・設定・描画を#019へ委譲。
- `iconPosition`: `top | bottom | left | right`。Button textに対するicon表示位置。
- `pressedLabel`: 押下中に表示するテキスト。空なら通常`label`を維持。
- `tooltip`: Buttonのtooltip text。native `title` / `aria-label`へ反映。

画像ファイル選択は#039、画像/アイコン描画は#019へ委譲する。#042はFilePickerやImageの内部処理を再実装しない。

## 6. Parent

`inheritParent=true` makes the Button fill its parent. `fit=true` fills the available parent Preview area without changing the parent itself. Parent Preview keeps the 9-direction standalone placement contract when inheritance/FIT are off.

`inheritParent=true` and follow parent background, text color, border color, radius, and text alignment. `syncParentStyle()` explicitly resynchronizes computed parent style.

## 7. Effects

Active/focus effect is attached to the Button root through #022 and driven with `setActive()` on focus/blur. Mouse-over effect is independently attached to the internal Button control through #022 `attach/update`; repeated mouseenter/leave remains #022 responsibility. Effect color selection in the test Property uses #040 v1.0.15 `attachCaller()` with `allowedKinds:["solid"]`.

## 8. Untrusted IN / Security

`inspectUntrustedInput()` and `applyJointInput()` accept only a safe string in `payload.value`.

Blocked examples: non-plain payload, accessor/getter `value`, null, number, object, ASCII control characters, excessive length. BLOCKED preserves the previous Button label. The Security test uses a dedicated Button instance and does not modify the normal Preview or OUT state. The test UI displays Before / After / Preview Before / Preview After, result code, message, and Result JSON.

## 9. Connection image

The test page uses #002 `BoneJoint.evaluate()` and formal line rendering for five isolated cases: normal IN/OUT, IN Target Field missing, OUT Target Field missing, IN type mismatch, and OUT type mismatch.

## 10. OUT WAIT / BLOCKED

`connectOutput()` delegates to #002 `createDeliveryChannel()`.

- Target Busy -> WAIT queue.
- Target Ready -> queued OUT is delivered FIFO.
- guard reject -> BLOCKED; connection is maintained and data is not delivered.

## 11. QA / Completion

Smoke and Validation start as NOT RUN. ALL PASS is shown only after the user executes the tests and every case passes. Completion requires Runtime ALL PASS plus visual WAIT and BLOCK confirmations.

## 12. HTML Functional Class

Marker class: `bone-html-class-use`.

Each public API has a `bone-button-*` functional class. The Guide documents class name, matching Public API, purpose, usage location, arguments, type/value, default, HTML setup, execution method, result/state, and current usage. Instance methods must receive an element returned from `BoneButton.create()`; the Guide live runner creates a dedicated instance before invoking them.


## 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.


## v1.0.9 Pressed text color
- `pressedTextColor`: 押下中のButton文字色。`#RRGGBB` または #040 `GRADIENT_V1` object。Property UIでは#040 ColorPickerを `solid + gradient` で使用し、#042のPressed stateで文字へ適用する。
- Font Awesome一覧は#019 Image Editor内の1一覧だけを使用し、#019ローカルFont Awesomeフォントのロード完了後に実Glyph + 名前を表示する。


## v1.0.10 Property language correction
- Property表示言語が日本語の時、Button Propertyのラベルだけでなくselect option（Mode / Variant / Size / Theme / Appearance / Shape / Icon position / 9-way / Effect）も日本語表示する。
- English選択時は同じoptionを英語へ戻す。value/API値は変更しない。


## v1.0.12 Pressed text gradient correction
- `pressedTextColor` accepts `#RRGGBB` and #040 `GRADIENT_V1`.
- The #040 Caller for pressed text exposes both solid and gradient sections.
- Browser Runtime QA explicitly opens both Normal and Pressed text callers and checks that the gradient section is rendered.


## v1.0.12 Runtime QA correction
- V17は#042が独自native color inputを持たないことを検証する。
- #040 ColorPicker自身が生成する`.bone-colorpicker input[type=color]`と、#019 Image Editor責務の`.bone-image-editor input[type=color]`は正式依存Component内部として許可する。
- #042 Propertyの6つのcolor sourceはhiddenのまま、各triggerが#040 Callerへattach済みであることを同時検証する。