## HTML Functional Class

`bf-textbox` は `bone-textbox-html-class.js` で有効化。`data-value` / `data-placeholder` / `data-width` / `data-height` / `data-theme` 等の属性を使用。Public APIは維持。

# Bone Flow #027 TextBox Specification v1.0

Component ID: #027  
Component: TextBox  
Specification Version: 1.0  
Status: Development Candidate / Implementation v1.0.35

## 1. 責務

#017 Text は表示専用Primitive。#027 TextBoxは文字列valueの入力・編集・commitを担当するInput UI。#017へ入力責務を追加せず、#027も#017を複製しない。

## 2. Bone / IN Contract

Bone最小構造 `id / type / value` は変更しない。基本value型はstring。`null / undefined` は表示上のみ空文字列へ正規化可能。

INは信頼済みとはみなさない。#027はJoint INを受ける前に契約検証を行う。

- valueは string / null / undefined のみ。
- object / array / function / symbol / bigintを `String(value)` で強制変換しない。
- accessor getter/setterを持つ契約値を実行しない。
- Proxy等で安全なproperty inspectionができない場合は拒否する。
- securityMaxLength既定262,144文字、絶対上限1,048,576文字。
- NUL等の危険な制御文字、不正なunpaired surrogateを拒否する。
- 拒否時は直前のcommittedValueを保持し、例外を外へ漏らしてUI全体を停止させない。
- `<script>` / `<img onerror>` 等の文字列はDOM HTMLとして解釈せずinput.valueとしてのみ扱う。文字列内容の業務/セキュリティ判定は別Guard責務。

Malformed INはConnection Errorへ潰さず、`IN Contract / Security Rejected`として分離する。

## 3. Editing / Commit

`committedValue` と `editingValue` を分離する。inputは編集途中、changeは編集成立、commitは正式確定。Enterとblurを基本commit triggerとし、IME composition中のEnterはcommitしない。Invalid値は破棄せず、既定ではcommitしない。

## 4. OUT / Joint Delivery

#027はOUT待機キューや再送を実装しない。#002 Bone Joint v1.1.36 `createDeliveryChannel()` を正式利用する。

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

WAITINGは再接続ではない。BLOCKEDも未接続ではない。接続状態と配送状態を分離する。

commit時点のOUT snapshotをJointへ渡し、待機中にTextBoxの現在値を取り直して内容を変更しない。

## 5. disabled / readonly / keyboard / clipboard

- disabled: focus不可、編集不可、commit不可。
- readonly: focus/selection/copy可能、編集/commit不可。
- Escape: editingValueをcommittedValueへ戻す。
- copy/paste/Undo/Redoはブラウザ標準責務。
- selection/cursor APIを公開する。

## 6. Validation / Error

required / minlength / maxlength と Security Validationを分離しつつ同一Validation結果で確認可能にする。Validation Error、IN Contract Error、Joint Delivery WAIT/BLOCKEDを1件の曖昧なConnection Errorへ統合しない。

## 7. 公開API

既存 v1.0.0 APIを維持し、v1.0.1で追加する。

- `inspectUntrustedText()`
- `connectOutput()`
- `disconnectOutput()`
- `setTargetReady()`
- `clearOutputBlock()`
- `getOutputState()`
- `getOutputQueue()`

## 8. Events

既存 `input / change / commit / invalid / focus / blur / composition* / reset` に加え、`in-accepted / in-rejected / security-rejected / delivery-state / delivery` を公開する。

## 9. Test

- 正常IN
- object / getter / Proxy / 巨大値 / 制御文字 / 不正Unicode
- HTML風文字列の非HTML実行
- committedValue保持
- IME
- readonly / disabled
- validation
- selection / cursor
- #002 WAIT FIFO
- 3秒Target Busy目視: spinner → ○ / 線維持 / 自動配送
- BLOCK目視: fa-ban + beat-fade / 線維持 / Target受信0件
- BLOCK解除後の正常配送

## 10. Completion

JavaScript / JSON / Smoke / Validation / Runtime / Console Error / MANIFEST SHA-256 / ZIP integrity / installer / localhost Version一致を確認する。ブラウザ目視が必要なWAIT/BLOCKはユーザー確認前にPASSとしない。


## v1.0.3 Test UI / Integration Clarification

- PropertyテストUIは日本語 / English を切替可能とする。
- 接続イメージは正常IN/OUT、Target不存在、型不一致を #002 Bone Joint実描画で表示する。
- OUT WAIT / BLOCKEDテストは #002 Bone JointのPathと前面Markerを必ず表示する。
- Smoke Test / Validationは画面上で個別再実行および全実行でき、件数・時刻・PASS/FAILを表示する。
- WAIT/BLOCKの委譲検証はprivate実装名の推測ではなく、#002 Delivery Channelの観測可能な状態・FIFO配送で確認する。


## v1.0.17 Appearance Extension

仕様追加採用：

- 背景色をProperty化する。`theme` / `transparent` / 安全なHEX色を受け付ける。無色は `transparent`。
- Themeは `default / dark / light`。
- 外見は `normal / flat / borderless / inherit`。`inherit` は親の背景・文字色・角丸へ合わせるための外見モード。
- Active時の枠Effectは `normal / neon / blink`。
- `normal` は従来Focus表現を維持する。
- `neon` は点線状の枠ラインを移動Animationさせる。
- `blink` はActive枠を点滅させる。
- reduced-motion環境ではAnimationを停止し、視認可能な静止状態を維持する。
- 外観Propertyは入力値・Joint Delivery・Validation責務へ混入させない。
- 背景色Propertyから任意CSSや `url()` を実行できないよう、値を `theme / transparent / HEX` に限定する。


## v1.0.17 追加仕様

- `inheritParent` を正式Propertyとして追加。`true` の場合は親要素の背景色・文字色・枠色・角丸へ追従する。
- `appearance: inherit` は後方互換aliasとして `inheritParent: true` と同義に扱う。
- Runtime ReportをJSON / Markdownで保存できる。
- テストページは `fetch(..., { cache: "no-store" })` で #027 JS/CSS を再取得し、HTMLだけ更新されてJS/CSSがブラウザキャッシュに残る不整合を防ぐ。


## v1.0.17 Addendum: Theme / Layout / Parent / Active Effect
Theme: default / dark / light / neon. Standalone: width, height, position(9-way), inputAlign. Parent Dependency: parent size 100%, parent visual/text-align inheritance, no independent normal border; standalone layout values are retained but ignored for rendering while enabled. Active Effect: normal/neon/blink + color + clockwise/counterclockwise + slow/normal/fast.


## v1.0.17 Neon枠Effect修正

- 時計回りを上辺→右、右辺→下、下辺→左、左辺→上として統一。
- 反時計回りは上記を完全反転。
- 各辺のbackground-positionを辺ローカル座標へ統一し、4辺の移動距離と速度差を解消。
- 下辺が消える表示不具合を修正。


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

- #022 Bone Hover Border Effect v1.0.8を正式Runtime依存として追加する。
- TextBoxのActive時枠Effect描画は#027内で再実装しない。
- #027はTextBox control要素へ#022を `trigger: active` でattachする。
- focus時 `setActive(true)`、blur時 `setActive(false)`。
- Effectは `normal / neon / spin / cross / blink`。
- `activeEffectColor / activeEffectDirection / activeEffectSpeed` は#022へ委譲する。
- #027 destroy時はattach済み#022をdetachする。
- 入力値、commit、Untrusted IN、Security、#002 Delivery WAIT/BLOCK、接続イメージ、Smoke/Validation、Completionの既存契約は変更しない。


## v1.0.30 Addendum: Mouse Over Effect / Dependency compatibility

- `borderEffectTrigger`: `active / mouseover / both`。Default=`active`。
- `activeBorderEffect / activeEffectColor / activeEffectDirection / activeEffectSpeed` の既存Property値を、選択したTriggerとともに #022へ渡す。
- Mouse Overは#022正式契約の `mouseenter / mouseleave` で表示/解除する。
- 依存Version判定は同一major + minimum version以上を条件とし、必要Public API/capability欠落時はVersionが上でもERRORとする。


## v1.0.31 Addendum: Independent Active / Mouse Over Effects

- `borderEffectTrigger` は現行契約から削除する。
- Active EffectとMouse Over Effectは選択式ではなく、別々の設定セットとして常時保持する。
- Active設定: `activeBorderEffect / activeEffectColor / activeEffectDirection / activeEffectSpeed`。
- Mouse Over設定: `mouseoverBorderEffect / mouseoverEffectColor / mouseoverEffectDirection / mouseoverEffectSpeed`。
- ActiveはTextBox inputへ#022 `trigger: active` でattachする。
- Mouse OverはTextBox controlへ#022 `trigger: mouseover` でattachする。
- 2つの#022 stateは独立しており、focus + mouseenter時は両方が表示可能。
- #027 destroy時は両方の#022 attachmentをdetachする。
- 色選択UIは#040 Caller APIを使用し、Mouse Over Effect Colorを含む5色すべて `allowedKinds:["solid"]`。


## v1.0.32 Addendum: Guide live runtime sample and API inventory
- The guide SHALL display a real runtime-created TextBox using `BoneTextBox.create()`.
- The guide SHALL include the runtime Public API inventory and detailed per-API documentation.
- Guide QA SHALL verify the live sample is a current `BoneTextBox` instance and that the inventory matches runtime public functions.


## v1.0.33 TEST Class sample correction

- TEST本体のPublic API検証方式は変更しない。
- 通常画面の「Class リスト」は、`BoneTextBox` Public APIを利用側Class `TextBoxClassSample` から使用し、実際にTextBoxを表示できるサンプルへ変更。
- `TextBoxClassSample` はTEST HTML内の利用例であり、`bone-textbox.js` のRuntime実装方式をClassへ変更しない。
- Public API一覧・API詳細はガイド内へ集約。ガイド内の実表示サンプルは削除。
- Classサンプルは内部DOMへ依存せず、`BoneCore.create` / `BoneTextBox.create` / `setValue` / `commit` / `getState` / `destroy` のPublic APIだけを使用する。


## v1.0.34 Class sample result pairing
- The TEST-side Class sample must show its live result immediately after the sample code.
- The result must be generated through BoneTextBox Public API and show an actual instance, not a static mock.
- Guide Public API content remains separate.


## v1.0.35 Addendum: Guide Operation class documentation
- Guide Operation SHALL start with a linked class list and SHALL provide one target section per listed class.
- Each class section SHALL document when/where to use it, referenced data including the class-name portion, code-writing steps, sample code, and the result.
- `TextBoxClassSample` remains a TEST-side consumer Class example built on BoneTextBox Public API; `bone-textbox.js` runtime architecture is not converted to a JavaScript class.
- Public API TEST and API guide inventory/detail remain unchanged.


## Runtime correction candidate (package 1.0.71, runtime 1.0.38)
- #022 Border Effect is connected for Active and Mouse Over with focus/blur updates and all nine official effect kinds.
- #040 gradient RETURN is preserved; the official #022 overlay gets a caller-scoped gradient border layer.
- #118 four Property options remain available below Effect settings and are passed to #040 Caller.
- Actual Windows Installer execution and localhost UI tests are unverified. Use the on-page effect audit and existing Smoke/Validation.