# Bone Flow #033 Checkbox Specification v1.0

Component ID: #033  
Component: Checkbox  
Specification Version: 1.0  
Implementation: v1.0.11  
Status: Specification Frozen / Development

## 1. 責務

#033 Checkbox は boolean `value` の入力・編集・commitを担当するInput UI。
Development OrderのInput UI順序に従い、#027 TextBox v1.0.22で確立済みの Property / Joint / Security / WAIT / BLOCKED / Smoke / Validation / Runtime QA / Completion の共通構造を維持し、Checkbox固有差分だけを持つ。

## 2. Bone / value Contract

Bone最小構造 `id / type / value` は変更しない。

- `type`: `CHECKBOX`
- `value`: booleanのみ (`true` / `false`)
- `checked`: `value` と同じbooleanをUI状態として扱う
- string `"true"` / `"false"`、number `1` / `0`、object等をbooleanへ暗黙変換しない

#033自身で値の意味を別表現へ変換しない。OUTでも `value` / `checked` / `bone.value` はbooleanを保持する。

## 3. Editing / Commit

`committedValue` と `editingValue` を分離する。

- Native checkboxの編集値は `editingValue`
- 正式確定値は `committedValue`
- `changeCommit=true` を既定とし、通常ユーザー操作のchangeでcommitする
- APIやテストでは `changeCommit=false` により editing → commit の分離確認が可能
- invalid値はcommittedValueへ反映しない
- `required=true` の場合、`true` のみValidation PASS。`false` はcommitしない
- `disabled=true`: 操作/commit不可
- `readonly=true`: 表示/focus可能だがユーザーによる値変更/commit不可

## 4. Untrusted IN / Security

Joint INは信頼済みとみなさない。

- plain object契約として安全に検査する
- `value` はbooleanのみ受理
- objectを `Boolean(value)` 等で強制変換しない
- getter/setterを実行しない
- Proxy等で安全なproperty inspectionができない場合は拒否
- 拒否時は直前のcommittedValueを保持
- Security ErrorとConnection Errorを混同しない

## 5. OUT / #002 Delivery Channel

#033は独自Queue/Retryを実装しない。#002 Bone Joint v1.1.36 `createDeliveryChannel()` を正式利用する。

```text
Checkbox commit
  ↓
#002 Joint Delivery Channel
  ├─ READY    → 即Delivery
  ├─ WAITING  → Joint FIFOに保持 → Target READYで自動Delivery
  └─ BLOCKED  → 接続維持 / Targetへ配送しない
```

WAITING / BLOCKEDは接続状態と分離する。commit済みboolean snapshotをJointへ渡す。

## 6. Property / Appearance

#027 Input UI基準の共通Propertyを維持する。

- 日本語 / English Property表示
- `theme`: `default / dark / light / neon`
- `backgroundColor`: `theme / transparent / HEX`
- `appearance`: `standard / outline / filled / rounded / circle / neon / minimal / inherit`  （legacy alias: `normal / flat / borderless`）
- `elementClickToggle`: boolean, default `false`. `true` の場合はCheckbox control要素内のクリックでもcheckedを反転する。input本体クリックは二重反転させない。readonly / disabledでは反転しない。
- `label`: string。Checkbox本体の横へ表示。空文字は非表示。
- `labelGap`: number。Checkbox本体とラベル間の余白(px)、0～64、既定8。
- `labelFontSize`: number。#020 Labelへ渡す文字サイズ(px)、8～56、既定14。Checkbox本体サイズもこの値から連動算出する。
- `inheritParent`: 親Previewの背景・文字・枠・角丸・位置へ追従
- `width / height`
- `position`: 9方向
- `inputAlign`: `auto / left / center / right`（Checkbox本体の位置）
- `activeBorderEffect`: `normal / neon / spin / cross / blink`
- Effect color / clockwise-counterclockwise / slow-normal-fast

外観Propertyをboolean値、Validation、Joint Deliveryへ混入させない。

## 7. 接続イメージ

テスト画面は #002 `BoneJoint.evaluate()` / `BoneJoint.drawLine()` を使い、以下の5ケースを実描画する。

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

Raw State / 診断 / 4色凡例を表示する。

## 8. Security Test

通常Previewから独立した専用Checkbox instanceを使用し、以下を確認する。

- boolean true / false: PASS
- string `"true"`: BLOCKED
- number `1`: BLOCKED
- getter: BLOCKED / getter非実行
- Proxy: BLOCKED
- object: BLOCKED / 暗黙変換なし

Before / After / Preview / Result JSON / Security Gate code + messageを表示する。

## 9. WAIT / BLOCKED Test

通常Previewから独立した `deliveryBox` を使う。

- WAIT: Target READY=falseで許可値 `false` をcommitし、3秒後READY=trueで自動配送を確認
- BLOCK: Guardが拒否する `true` をcommitし、接続線は維持したままTarget受信件数が増えないことを確認
- WAIT/BLOCKの目視確認はCompletion条件から削除しない

## 10. Smoke / Validation / Completion

Browser RuntimeではSmoke / Validationを個別または一括実行できる。

Completion条件:

1. Runtime Smoke ALL PASS
2. Runtime Validation ALL PASS
3. WAIT実動作成功 + ユーザー目視確認
4. BLOCK実動作成功 + ユーザー目視確認

Packaging環境でBrowser Runtimeを実行していない場合、ALL PASS / Completedとは記載しない。
ユーザーlocalhost Runtime QA ALL PASS前はStatusをDevelopmentのままとする。

### Parent Dependency visibility rule (v1.0.1)

`inheritParent=true` は親コンテナへ追従するが、Checkbox入力本体を非表示・全幅塗り潰しにしてはならない。チェック入力は可視状態を維持し、親の配置へ追従する。


### Connection image CSS binding rule (v1.0.3)

`#connection-images` 配下の接続イメージ用classは `bone-checkbox-*` と一致させ、旧 `bone-text-*` selectorを残さない。


## v1.0.3 Appearance variants

- Added 7 visible appearance presets: `standard / outline / filled / rounded / circle / neon / minimal`.
- Kept legacy compatibility aliases: `normal -> standard`, `flat -> outline`, `borderless -> minimal`.
- No changes to Checkbox boolean contract, Security, WAIT/BLOCKED, connection image, or Completion flow.


## v1.0.4 Element click toggle

`elementClickToggle` only changes the click target surface. Boolean value, commit, OUT, Security, WAIT/BLOCKED and Completion contracts are unchanged.


## v1.0.5 Label / spacing

- `label: string` — visible label text inside the Checkbox control; empty string hides it.
- `labelGap: number` — spacing in px between checkbox glyph and label, range 0..64, default 8.
- Visible label is associated by `aria-labelledby`. If label is empty, existing `ariaLabel` fallback is used.
- Whole-element toggle remains controlled only by `elementClickToggle`; adding a label does not implicitly enable it.


### #020 Label delegation and checkbox size linkage (v1.0.6)

When `label` is non-empty, #033 MUST create the visible label through `BoneLabel.create()` (#020). Private label text rendering is not permitted. `labelFontSize` is passed to #020 `textStyle.fontSize`. Checkbox glyph size is derived from that font size and scales with it. `elementClickToggle=false` continues to prevent label/empty-area clicks from changing the Checkbox.


### Runtime QA geometry / #020 public API rule (v1.0.10)

Geometry Validation MUST run in a rendered off-screen sandbox; `hidden` / `display:none` containers are prohibited because they force DOM geometry to zero. #020 delegation MUST be verified through public `BoneLabel.getOutput()` / `getChildOutput()` rather than private DOM class names. Checkbox glyph size MUST use the normalized font size returned by #020 Label OUT.


## v1.0.10 Runtime QA correction

- S14 now performs deterministic #002 Joint WAIT and BLOCKED rendering and verifies both the Joint path and the corresponding waiting/blocked marker before restoring connected display.
- V27 verifies the #033 -> #020 Label public boundary, visible label text, labelGap, and aria-labelledby association without depending on a particular internal #020 -> #017 output object shape.
- Checkbox behavior, appearance, parent dependency, Security, Delivery, Completion, label sizing, and click behavior are unchanged.


## #022 Active Border Effect delegation
- Active Border Effect描画は #022 Bone Hover Border Effect v1.0.1へ委譲する。
- Checkbox側のActive判定は既存どおりfocus/blur。
- #033固有のboolean/commit/Security/WAIT/BLOCK/Label契約は変更しない。