# Bone Flow #029 NumberBox Specification v1.0

Component ID: #029  
Component: NumberBox  
Version: 1.0.19  
Status: Development  
Standard: Bone Flow Development Standard v1.0

## 1. 責務

#029 NumberBox は **単一行の数値入力・編集・確定・数値精度・表示書式・伝票表示**を担当する Input UI である。#027 Bone TextBox v1.0.13 を単一行 Input UI の正式基準として参照し、NumberBox 固有差分だけを追加する。#028 Bone TextArea v1.0.0 は Security / Joint 配送責務の確認基準として参照する。

完成済みの #001 / #002 / #017 / #027 / #028 は #029 都合で変更しない。

## 2. value 契約

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

NumberBox の正式 committed value は次のいずれか。

- finite JavaScript `number`
- `null`（空欄）

numeric string は Joint IN の number へ暗黙変換しない。`NaN` / `Infinity` / object / array / function / accessor / unsafe Proxy は拒否する。

## 3. editing / committed / display の分離

- `editingValue`: 編集中の数値文字列。3桁カンマを含めない。
- `committedValue`: 計算小数桁と丸め方式を適用した正式 `number | null`。
- `displayValue`: 表示小数桁と3桁カンマを適用した表示専用文字列。

`displayValue` は Bone.value / OUT value を変更しない。

例：

- committedValue: `1000`
- displayDecimalPlaces: `2`
- useGrouping: `true`
- displayValue: `1,000.00`

フォーカス中は編集可能な raw 数値文字列を表示し、非フォーカス時は displayValue を表示する。このため実装 input は `type="text" + inputmode="decimal"` とし、数値 Validation は NumberBox が担当する。

## 4. NumberBox 固有 Property

### min / max / step

- `min`: finite number / null
- `max`: finite number / null
- `step`: `"any"` または 0 より大きい finite number

### decimalPlaces

**計算上の小数桁数**。`null` または `0..15`。

commit / setValue / Bone IN / Joint IN の正式数値を、この桁数へ丸めて committedValue とする。

### displayDecimalPlaces

**表示上の小数桁数**。`null` または `0..20`。

表示専用であり committedValue / OUT value は変更しない。指定時は末尾ゼロも表示する。

例：値 `1000`、displayDecimalPlaces=`2` → `1000.00`。

### useGrouping

`true` の場合、非フォーカス時の表示に 3桁カンマを付ける。

例：`1000.00` → `1,000.00`。

カンマは表示専用であり、editingValue / committedValue / OUT へ混ぜない。

### roundingMode

`decimalPlaces` による計算丸めと、表示桁を減らす場合の表示丸めに使用する。

- `half-up`: 四捨五入。5以上を絶対値方向へ丸める。
- `up`: 切り上げ。0から遠ざかる方向へ丸める。
- `down`: 切り捨て。0へ近づく方向へ丸める。

負数でも定義を固定する。

例（小数2桁）：

| 入力 | 四捨五入 | 切り上げ | 切り捨て |
|---:|---:|---:|---:|
| 1.235 | 1.24 | 1.24 | 1.23 |
| -1.235 | -1.24 | -1.24 | -1.23 |

## 5. commit

- input: editingValue 更新
- Enter: IME composition 中でなければ commit
- blur: dirty の場合 commit
- Escape: rollback
- readonly / disabled: commit禁止

commit は `editingValue → parse → decimalPlaces/roundingMode → min/max/step Validation → committedValue → OUT snapshot` の順で行う。

## 6. Untrusted IN / Security

Joint IN は信用しない。finite number / null / undefined のみ受理し、numeric string / object / getter / Proxy / NaN / Infinity を拒否する。object の `Number()` / `String()` coercion は実行しない。

Security Test は通常 Preview から独立した NumberBox instance を使用する。

## 7. OUT / #002 Joint

#029 は commit までを担当し、WAIT / FIFO / BLOCKED / 配送は #002 Bone Joint v1.1.36 `createDeliveryChannel()` へ委譲する。

OUT は **丸め確定後の committedValue snapshot** を配送する。表示用カンマや末尾ゼロ文字列は配送しない。

## 8. 表示基準

#027 の正式 Input UI 表現を維持する。

- Property 日本語 / English
- Theme: default / dark / light / neon
- backgroundColor
- appearance
- inheritParent
- width / height
- 9方向 position
- inputAlign（NumberBoxデフォルトは `right`。`auto` も右寄せへ解決）
- Active Border Effect

#017 Bone Text は Runtime 非依存で、表示責務・Property表現・配置設定の基準としてのみ参照する。


## 8.1 伝票モード

NumberBox は通常入力とは別に、伝票・帳票向けの表示モードを持つ。通常のデフォルトは `voucherMode=false`。

### 状態遷移

```text
通常入力 / focus
      ↓ blur
伝票表示
      ↓ mouseover
入力表示
      ↓ mouseleave（未focus）
伝票表示
```

伝票モード中も committedValue / OUT は number|null のまま保持し、表示文字列を value へ混ぜない。

### 表示

- 右寄り
- 文字ごとに等幅セルで均等割り付け
- `voucherYenMark=true` で数値の直前へ `￥` を表示する。表示専用で committedValue / Bone.value / OUT value は変更しない
- `voucherYenMark=false`（デフォルト）では `￥` を表示しない
- `voucherGridLines=true` で伝票罫線を表示
- `voucherGridLines=false` で罫線を非表示
- `voucherAutoFontSize=true` をデフォルトとし、幅・高さ・表示文字数からフォントサイズを自動調整
- 自動調整OFF時は `voucherFontSize` を使用（8..96px）

### マイナス表示

`voucherNegativeMark`:

- `minus`: `－1000.00`
- `triangle`: `△1000.00`
- `none`: `1000.00`

`voucherNegativeRed=true` の場合、負数の伝票表示を赤文字にする。記号指定と赤文字指定は独立して組み合わせられる。

### マウス操作

`voucherHoverEdit=true` の場合、非focusの伝票表示へマウスオーバーすると入力表示へ切替える。マウスが外れ、inputがfocusされていなければ伝票表示へ戻る。

### テスト再現

テストUIには `showVoucherDisplay()` / `showInputMode()` を利用する再現ボタンを用意する。これにより、テスト環境で実際のfocus lostを発生させにくい場合でも伝票表示を確認できる。

## 9. Joint 描画

接続イメージ、WAIT spinner、BLOCK fa-ban + beat-fade は #002 Bone Joint 正式描画 API を使用する。NumberBox 独自 Joint 線は作らない。

## 10. Test

Node Test は number/null、min/max/step、IME、Security、WAIT/FIFO/BLOCKEDに加え、以下を検査する。

- calculation decimal places
- display decimal places
- `1,000.00` grouping
- half-up / up / down
- 正数 / 負数の丸め
- display と OUT value の分離
- Joint IN / setValue の計算丸め
- 入力時文字位置デフォルト右寄せ
- 伝票モード focus / blur / mouseover 切替
- 伝票罫線表示/非表示
- フォントサイズ自動調整
- マイナス記号 / △ / 記号なし / 赤文字
- `￥` 表示ON/OFFと numeric value 非改変
- フォーカスロスト再現API

Browser Runtime QA は localhost で実行する。未実施 Browser Runtime を ALL PASS と記録しない。


## 11. Test Instance Isolation

正式テストページでは、以下の3インスタンスを完全分離する。

- Preview: Property / 伝票表示確認専用。WAIT/BLOCK/Securityの配送テストへ接続しない。
- Security Sandbox: Untrusted IN / Security Test専用。Previewを変更しない。
- Delivery Sandbox: WAIT / FIFO / BLOCKED専用。Previewの value / deliveryState / displayMode / voucherMode を変更しない。

Security Test および WAIT/BLOCK Test の実行前後で Preview の committedValue / editingValue / displayMode / voucherMode が不変であることを確認する。
## v1.0.11 伝票罫線と区切り記号

- `voucherGridLines=true`：3桁区切りと小数区切りは罫線で表現し、`,` と `.` は表示しない。
- `voucherGridLines=false`：罫線を非表示にし、同じ論理位置へ3桁区切り`,` と小数区切り`.`を表示する。
- 固定桁の先頭空白領域には不要な`,`を表示しない。


## v1.0.15 伝票￥表示

- `voucherYenMark` を追加。デフォルト `false`。
- `true` の場合のみ伝票表示の数値直前へ `￥` を表示する。
- `￥` は表示専用であり、`committedValue` / `Bone.value` / `OUT value` は従来どおり `number | null` を維持する。
- 通常入力モードの編集文字列へ `￥` を混入させない。


## v1.0.16 伝票￥独立マス表示

- `voucherYenMark=true` の `￥` は数値先頭文字と同じマスへ連結せず、独立した1マスとして表示する。
- 罫線ON時は `｜￥｜1｜0｜0｜0｜` のように、`￥` と先頭数字の間にも通常罫線を表示する。
- `￥` は引き続き表示専用であり、`committedValue` / `Bone.value` / `OUT value` は変更しない。


## v1.0.19 Addendum: #022 Active Border Effect Delegation

- #022 Bone Hover Border Effect formal Runtime APIを正式Runtime依存として追加する。
- NumberBoxのActive時枠Effect描画は#029内で再実装しない。
- #029はNumberBox control要素へ#022を `trigger: active` でattachする。
- focus時 `setActive(true)`、blur時 `setActive(false)`。
- Effectは `normal / neon / spin / cross / blink`。
- `activeEffectColor / activeEffectDirection / activeEffectSpeed` は#022へ委譲する。
- #029 destroy時はattach済み#022をdetachする。
- 数値value契約、丸め、表示小数桁、伝票モード、￥独立マス、Security、#002 WAIT/BLOCKED、接続イメージ、Completionは変更しない。


## v1.0.19 NumberBox Property / Dependency update

- #022 is checked against the actual formal API and its published effects, not a hard-coded file path or fixed minor version. Older cross maps to corner if only the newer formal effect catalog is available. Unsupported effects fail explicitly.
- #040 ColorPicker is used for Property color selection. Background and parent background support solid and normalized linear gradient; effect, text and voucher line colors remain solid-only because their rendering contract requires a stroke/text color.
- #118 Transition is passed into the actual #040 Caller OPEN/CLOSE path using transition/direction/speed/respectReducedMotion. The test-page audit reports real results and is not pre-marked PASS.
- The normal HTML Functional Class remains `bf-numberbox`; it preserves numerical, voucher and Joint contracts. The runtime/Property bridge is test-page-only, not a new unsupported HTML attribute.
- New package status remains Development / Candidate until user localhost verification.