DOC-0027 — TextBox 操作・HTML Functional Class

0. 文書情報

DOC ID: DOC-0027
TOC ID: TOC-0027
UI: UI-027 / #027 TextBox
Runtime: BoneTextBox v1.0.35
DOC Integration: 1.0.4
通常利用HTML Functional Class: bf-textbox
Shared DOC: bone-doc-loader.js / bone-doc-guide.js / bone-doc-guide.css（#027固有都合で変更しない）

1. TextBoxの役割

#027 TextBoxは、1行の文字入力を「入力中」と「確定済み」に分けて安全に扱うUIです。単に文字を表示するだけではなく、入力・Validation・確定・Security・#002 JointへのIN/OUTまでを一つの状態として管理します。

1.1 最初に覚える用語

元input — HTMLに書く <input class="bf-textbox"> です。これは設定を読み取る元の要素です。画面では一旦非表示になり、その直後へ実TextBoxが生成されます。
実TextBox — 画面に実際に表示される .bone-textbox です。入力欄、feedback、状態Classを持ちます。
editingValue — ユーザーが今まさに編集中の文字列です。入力するたびに変わります。
committedValue — Enter、blur、または commit() で確定した文字列です。OUTへ送る値もこちらです。
commit — editingValueをcommittedValueへ確定する操作です。「入力しただけ」と「確定した」を区別するためにあります。
Validation — required / minlength / maxlengthの条件を満たすかを確認します。業務上の入力条件の検査です。
Security — 制御文字、壊れたUnicode、長さ上限超過、危険なObject読取などを拒否します。Validationより前段の安全性検査です。
Delivery Channel — #002 Jointが提供するOUT配送経路です。TargetがBusyならWAITしてQueueへ積み、Ready後にFIFO順で配送し、guard拒否ならBLOCKEDになります。

1.2 まず基本操作を理解する

TextBoxへ文字を入力すると editingValueだけ が変わります。未確定なのでcommittedValueはまだ変わりません。
enterCommit=true（Default）なら、IME変換中でないEnterでcommitします。
blurCommit=true（Default）なら、TextBoxからフォーカスが外れた時にもcommitを試みます。
required / minlength / maxlengthに違反していて commitInvalid=false ならcommitを拒否し、committedValueは直前の値を維持します。
Escapeを押すと未確定のeditingValueを破棄し、committedValueへ戻します。
Securityで拒否された入力はeditingValueへも採用せず、直前の安全な値を維持します。

1.3 disabled と readonly の違い

disabled=true — 操作自体を停止します。入力、focus、commitを受け付けません。見た目は薄くなります。
readonly=true — 値を見せたまま編集を禁止します。入力値は残り、ブラウザ上ではfocus/文字選択ができますが、Runtimeのcommitは reason=not-editable で拒否します。
両方false — 通常の編集・commitができます。

1.4 Validation と Security の違い

Validation Errorは「文字列自体は安全だが、requiredや文字数ルールを満たしていない」状態です。commitInvalid=trueなら確定を許可できます。
Security Errorは「Runtimeへ採用してはいけない入力」です。commitInvalid=trueでも通しません。
例: required=trueで空文字 → Validation。securityMaxLength=8で9文字 → Security。

2. HTML Functional Class `bf-textbox`

2.1 最小利用

<input class="bf-textbox" value="ABC">

bf-textboxを付けた元inputを見つけると、HTML Functional Class処理が BoneTextBox.create() を呼び、元inputの直後へ実TextBoxを生成します。通常利用Classはこれ1個です。元input自身は非表示になります。実TextBoxでcommitが成功すると、その確定値を元inputのvalueへ同期します。

つまりHTML利用者は「元inputへclassと属性を書く」だけでよく、.bone-textboxを自分で組み立てる必要はありません。旧bone-html-class-useや35個のAPI別Classは通常利用仕様ではありません。

[[BF-TEXTBOX-SAMPLE:basic]]

2.2 設定付き利用

<input class="bf-textbox" value="ABC"
       placeholder="文字を入力"
       data-theme="neon"
       data-width="360" data-height="48"
       data-position="center" data-input-align="left"
       data-active-border-effect="neon"
       data-mouseover-border-effect="cross">

2.3 設定 → 実表示サンプル

各サンプルは 設定HTML → その設定で変わる箇所 → 実 BoneTextBox v1.0.35 → Runtime state の順で表示します。単なる画像や疑似図ではありません。コードを変更したら、直下の実表示とstateを見比べてください。

Theme 全4値

[[BF-TEXTBOX-SAMPLE:themeDefault]]

[[BF-TEXTBOX-SAMPLE:themeDark]]

[[BF-TEXTBOX-SAMPLE:themeLight]]

[[BF-TEXTBOX-SAMPLE:themeNeon]]

Background

[[BF-TEXTBOX-SAMPLE:bgTransparent]]

[[BF-TEXTBOX-SAMPLE:bgCustom]]

Appearance

[[BF-TEXTBOX-SAMPLE:appNormal]]

[[BF-TEXTBOX-SAMPLE:appFlat]]

[[BF-TEXTBOX-SAMPLE:appBorderless]]

Validation

[[BF-TEXTBOX-SAMPLE:required]]

サイズ

[[BF-TEXTBOX-SAMPLE:size]]

入力文字位置全4値

[[BF-TEXTBOX-SAMPLE:alignAuto]]

[[BF-TEXTBOX-SAMPLE:alignLeft]]

[[BF-TEXTBOX-SAMPLE:alignCenter]]

[[BF-TEXTBOX-SAMPLE:alignRight]]

disabled / readonly / selectOnFocus / commit policy

[[BF-TEXTBOX-SAMPLE:disabled]]

[[BF-TEXTBOX-SAMPLE:readonly]]

[[BF-TEXTBOX-SAMPLE:select]]

[[BF-TEXTBOX-SAMPLE:commitPolicy]]

Active Effect

normalは通常枠です。neon / spin / cross / blinkは下のinputへfocusして実表示します。 [[BF-TEXTBOX-SAMPLE:activeNeon]]

[[BF-TEXTBOX-SAMPLE:activeSpin]]

[[BF-TEXTBOX-SAMPLE:activeCross]]

[[BF-TEXTBOX-SAMPLE:activeBlink]]

Mouse Over Effect

normalは通常枠です。neon / spin / cross / blinkは下のTextBoxへマウスを重ねて実表示します。 [[BF-TEXTBOX-SAMPLE:hoverNeon]]

[[BF-TEXTBOX-SAMPLE:hoverSpin]]

[[BF-TEXTBOX-SAMPLE:hoverCross]]

[[BF-TEXTBOX-SAMPLE:hoverBlink]]

2.4 HTML宣言Property 全33件「設定 → 表示/動作」早見

placeholder — Default "" / HTML placeholder / data-placeholder / 入力欄が空の時に補助文字を表示します。
disabled — Default false / HTML disabled / data-disabled / 入力・focus・commitを無効化します。
readonly — Default false / HTML readonly / data-readonly / 表示は維持し編集・commitを禁止します。
required — Default false / HTML required / data-required / 空文字をValidation Errorにします。
minlength — Default null / HTML minlength / data-minlength / 最小文字数を設定します。
maxlength — Default null / HTML maxlength / data-maxlength / 最大文字数を設定します。
name — Default "" / HTML name / data-name / 内部inputのname属性へ反映します。
autocomplete — Default "off" / HTML autocomplete / data-autocomplete / 内部inputのautocomplete属性へ反映します。
spellcheck — Default false / HTML spellcheck / data-spellcheck / 内部inputのspellcheckを切替えます。
inputMode — Default "text" / HTML inputmode / data-input-mode / ソフトキーボード入力ヒントを設定します。
enterCommit — Default true / HTML data-enter-commit / Enter押下でeditingValueをcommitします。
blurCommit — Default true / HTML data-blur-commit / blur時にeditingValueをcommitします。
commitInvalid — Default false / HTML data-commit-invalid / Validation Error時もcommitを許可するか制御します。
selectOnFocus — Default false / HTML data-select-on-focus / focus時に入力文字列を全選択します。
ariaLabel — Default "" / HTML aria-label / data-aria-label / 内部inputのaria-labelを設定します。
className — Default "" / HTML data-class-name / 実TextBox本体（.bone-textbox）へ追加Classを設定します。
theme — Default "default" / HTML data-theme / TextBoxのテーマ色を切替えます。
backgroundColor — Default "theme" / HTML data-background-color / TextBox背景をTheme/透明/HEXで設定します。
appearance — Default "normal" / HTML data-appearance / 外枠外観を切替えます。
inheritParent — Default false / HTML data-inherit-parent / 親要素の幅・高さ・背景・文字色・枠色・角丸・textAlignを継承します。
width — Default 320 / HTML data-width / 単体TextBoxの幅を設定します。
height — Default 44 / HTML data-height / 単体TextBoxの高さを設定します。
position — Default "center" / HTML data-position / 親Preview内での表示位置を9方向から選びます。
inputAlign — Default "auto" / HTML data-input-align / 入力文字の横位置を設定します。
activeBorderEffect — Default "normal" / HTML data-active-border-effect / focus中の枠Effectを#022へ委譲します。
activeEffectColor — Default "theme" / HTML data-active-effect-color / Active Effect色を設定します。
activeEffectDirection — Default "clockwise" / HTML data-active-effect-direction / Active Effect方向を設定します。
activeEffectSpeed — Default "normal" / HTML data-active-effect-speed / Active Effect速度を設定します。
mouseoverBorderEffect — Default "normal" / HTML data-mouseover-border-effect / Mouse Over時の枠Effectを#022へ委譲します。
mouseoverEffectColor — Default "theme" / HTML data-mouseover-effect-color / Mouse Over Effect色を設定します。
mouseoverEffectDirection — Default "clockwise" / HTML data-mouseover-effect-direction / Mouse Over Effect方向を設定します。
mouseoverEffectSpeed — Default "normal" / HTML data-mouseover-effect-speed / Mouse Over Effect速度を設定します。
securityMaxLength — Default 262144 / HTML data-security-max-length / Security Gateが受理する文字列長の上限です。

3. Default Property 全33件 — 個別Reference

3.1 `placeholder`

初めて使う人向け: 入力前だけ薄く表示する案内文です。値そのものには入りません。
型: string
Runtime Default: ""
HTML指定: placeholder / data-placeholder
表示/動作: 入力欄が空の時に補助文字を表示します。
許容値・範囲・競合: 任意文字列。HTMLとして解釈せずplaceholder属性へ設定。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_OPTION_TYPE_INVALID
具体例: placeholder="氏名"
設定後の表示/動作: 値が空の間だけ「氏名」を補助表示し、1文字でも入力すると消えます。committedValueには入りません。
許容値の詳細: 空文字も有効。HTML文字列として実行されず文字として表示されます。
関連/競合: value / editingValueとは独立した表示補助です。
不正例: BoneTextBox.setOptions(root,{placeholder:{}})
修正例: BoneTextBox.setOptions(root,{placeholder:"氏名"})

3.2 `disabled`

初めて使う人向け: 入力欄を完全に操作停止したい時に使います。
型: boolean
Runtime Default: false
HTML指定: disabled / data-disabled
表示/動作: 入力・focus・commitを無効化します。
許容値・範囲・競合: true=無効 / false=有効。commitはreason=not-editable。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_FUNCTIONAL_CLASS_BOOLEAN_INVALID (HTML宣言時)
具体例: disabled または data-disabled="true"
設定後の表示/動作: trueでは入力、focus、commitを拒否します。falseへ戻すと通常操作へ戻ります。
許容値の詳細: true / false。属性だけのdisabledもtrueとして読まれます。
関連/競合: readonlyより強い操作禁止です。既存表示値は消しません。
不正例: data-disabled="maybe"
修正例: data-disabled="true"

3.3 `readonly`

初めて使う人向け: 値を見せたいがユーザーには編集させたくない時に使います。
型: boolean
Runtime Default: false
HTML指定: readonly / data-readonly
表示/動作: 表示は維持し編集・commitを禁止します。
許容値・範囲・競合: true=読取専用 / false=編集可。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_FUNCTIONAL_CLASS_BOOLEAN_INVALID (HTML宣言時)
具体例: readonly または data-readonly="true"
設定後の表示/動作: trueでは値を表示したままユーザー編集とcommitを禁止します。falseで編集可能です。
許容値の詳細: true / false。
関連/競合: disabledと違い表示・選択用途を維持しますがcommitはnot-editableになります。
不正例: data-readonly="maybe"
修正例: data-readonly="true"

3.4 `required`

初めて使う人向け: 空文字を入力エラーとして扱うかを決めます。
型: boolean
Runtime Default: false
HTML指定: required / data-required
表示/動作: 空文字をValidation Errorにします。
許容値・範囲・競合: trueで空文字はTEXTBOX_REQUIRED。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_FUNCTIONAL_CLASS_BOOLEAN_INVALID (HTML宣言時)
具体例: data-required="true"
設定後の表示/動作: trueで空文字をTEXTBOX_REQUIREDにし、commitInvalid=falseならcommitを拒否します。falseでは空文字を許可します。
許容値の詳細: true / false。
関連/競合: commitInvalidと組み合わせます。Security拒否とは別レイヤーです。
不正例: data-required="maybe"
修正例: data-required="true"

3.5 `minlength`

初めて使う人向け: 確定前のValidationで必要な最小文字数を決めます。
型: integer/null
Runtime Default: null
HTML指定: minlength / data-minlength
表示/動作: 最小文字数を設定します。
許容値・範囲・競合: 0以上の整数または未指定。maxlength以下。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_LENGTH_INVALID / TEXTBOX_LENGTH_RANGE_INVALID
具体例: data-minlength="3"
設定後の表示/動作: 0～2文字をTEXTBOX_MINLENGTH、3文字以上を条件通過にします。
許容値の詳細: 0以上の整数または未指定。
関連/競合: maxlength以下である必要があります。
不正例: data-minlength="-1"
修正例: data-minlength="3"

3.6 `maxlength`

初めて使う人向け: 入力可能な最大文字数を決めます。Security上限より大きくできません。
型: integer/null
Runtime Default: null
HTML指定: maxlength / data-maxlength
表示/動作: 最大文字数を設定します。
許容値・範囲・競合: 0以上かつsecurityMaxLength以下。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_LENGTH_INVALID / TEXTBOX_MAXLENGTH_SECURITY_RANGE / TEXTBOX_LENGTH_RANGE_INVALID
具体例: data-maxlength="20"
設定後の表示/動作: 21文字以上をTEXTBOX_MAXLENGTHにします。内部inputにもmaxlengthを反映します。
許容値の詳細: 0以上の整数または未指定。
関連/競合: securityMaxLength以下、かつminlength以上である必要があります。
不正例: data-maxlength="999999" data-security-max-length="100"
修正例: data-maxlength="20" data-security-max-length="100"

3.7 `name`

初めて使う人向け: 内部inputへフォーム用nameを付けます。見た目は変わりません。
型: string
Runtime Default: ""
HTML指定: name / data-name
表示/動作: 内部inputのname属性へ反映します。
許容値・範囲・競合: フォーム識別名。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_OPTION_TYPE_INVALID
具体例: name="customerName"
設定後の表示/動作: 内部inputのname属性がcustomerNameになります。見た目は変わりません。
許容値の詳細: 任意string。
関連/競合: フォーム識別用で、Bone idとは別です。
不正例: BoneTextBox.setOptions(root,{name:{}})
修正例: BoneTextBox.setOptions(root,{name:"customerName"})

3.8 `autocomplete`

初めて使う人向け: ブラウザの入力候補機能へ渡すautocomplete tokenです。
型: string
Runtime Default: "off"
HTML指定: autocomplete / data-autocomplete
表示/動作: 内部inputのautocomplete属性へ反映します。
許容値・範囲・競合: ブラウザ標準autocomplete token。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_OPTION_TYPE_INVALID
具体例: autocomplete="email"
設定後の表示/動作: 内部inputへautocomplete=emailを設定し、ブラウザの入力補助ヒントに使います。
許容値の詳細: ブラウザ標準tokenのstring。
関連/競合: BoneTextBoxは候補UI自体を実装しません。
不正例: BoneTextBox.setOptions(root,{autocomplete:{}})
修正例: data-autocomplete="off"

3.9 `spellcheck`

初めて使う人向け: ブラウザのスペルチェックをON/OFFします。
型: boolean
Runtime Default: false
HTML指定: spellcheck / data-spellcheck
表示/動作: 内部inputのspellcheckを切替えます。
許容値・範囲・競合: true / false。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_FUNCTIONAL_CLASS_BOOLEAN_INVALID (HTML宣言時)
具体例: data-spellcheck="true"
設定後の表示/動作: trueで内部inputのspellcheckを有効化し、対応ブラウザで校正候補対象になります。falseでは無効です。
許容値の詳細: true / false。
関連/競合: ブラウザ機能なので表示差は環境依存です。
不正例: data-spellcheck="maybe"
修正例: data-spellcheck="true"

3.10 `inputMode`

初めて使う人向け: スマホ等のソフトキーボードに、どんな入力を期待するかヒントを渡します。
型: string
Runtime Default: "text"
HTML指定: inputmode / data-input-mode
表示/動作: ソフトキーボード入力ヒントを設定します。
許容値・範囲・競合: text / numeric / email等、ブラウザ標準値。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_OPTION_TYPE_INVALID
具体例: inputmode="numeric"
設定後の表示/動作: 対応端末のソフトキーボードへnumeric入力ヒントを出します。値の型はstringのままです。
許容値の詳細: ブラウザ標準inputmode token。
関連/競合: ValidationやSecurityで数値型へ変換しません。
不正例: BoneTextBox.setOptions(root,{inputMode:{}})
修正例: data-input-mode="text"

3.11 `enterCommit`

初めて使う人向け: Enterキーで確定するかを決めます。falseならEnterしても編集中のままです。
型: boolean
Runtime Default: true
HTML指定: data-enter-commit
表示/動作: Enter押下でeditingValueをcommitします。
許容値・範囲・競合: falseではEnterだけでは確定しません。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_FUNCTIONAL_CLASS_BOOLEAN_INVALID (HTML宣言時)
具体例: data-enter-commit="false"
設定後の表示/動作: falseではEnterでeditingValueを確定しません。trueではIME composition中でないEnterでcommitします。
許容値の詳細: true / false。
関連/競合: blurCommitと独立。両方falseならAPI commit()など明示経路が必要です。
不正例: data-enter-commit="maybe"
修正例: data-enter-commit="false"

3.12 `blurCommit`

初めて使う人向け: TextBoxから離れた時に自動確定するかを決めます。
型: boolean
Runtime Default: true
HTML指定: data-blur-commit
表示/動作: blur時にeditingValueをcommitします。
許容値・範囲・競合: falseではfocus離脱だけでは確定しません。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_FUNCTIONAL_CLASS_BOOLEAN_INVALID (HTML宣言時)
具体例: data-blur-commit="false"
設定後の表示/動作: falseではfocusを外してもeditingValueを確定しません。trueではblur時にcommitを試みます。
許容値の詳細: true / false。
関連/競合: enterCommitと独立。Validation/Securityで拒否される場合があります。
不正例: data-blur-commit="maybe"
修正例: data-blur-commit="true"

3.13 `commitInvalid`

初めて使う人向け: Validation Errorがあっても確定を許すかを決めます。Security拒否はこの設定では通りません。
型: boolean
Runtime Default: false
HTML指定: data-commit-invalid
表示/動作: Validation Error時もcommitを許可するか制御します。
許容値・範囲・競合: falseは不正値commit拒否、trueは確定許可。Security拒否は別。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_FUNCTIONAL_CLASS_BOOLEAN_INVALID (HTML宣言時)
具体例: data-commit-invalid="true"
設定後の表示/動作: trueではrequired/minlength/maxlengthのValidation Errorがあってもcommitを許可します。falseでは拒否します。
許容値の詳細: true / false。
関連/競合: Security Gate拒否を解除する設定ではありません。
不正例: data-commit-invalid="maybe"
修正例: data-commit-invalid="true"

3.14 `selectOnFocus`

初めて使う人向け: focusした瞬間に入力文字列を全選択するかを決めます。
型: boolean
Runtime Default: false
HTML指定: data-select-on-focus
表示/動作: focus時に入力文字列を全選択します。
許容値・範囲・競合: true / false。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_FUNCTIONAL_CLASS_BOOLEAN_INVALID (HTML宣言時)
具体例: data-select-on-focus="true"
設定後の表示/動作: trueではfocusした瞬間に入力文字列全体を選択します。falseでは通常caret位置です。
許容値の詳細: true / false。
関連/競合: select()/setSelectionRange()によるAPI選択とは別にfocus時だけ自動実行します。
不正例: data-select-on-focus="maybe"
修正例: data-select-on-focus="true"

3.15 `ariaLabel`

初めて使う人向け: 画面読み上げ用の名前を内部inputへ設定します。通常画面には表示されません。
型: string
Runtime Default: ""
HTML指定: aria-label / data-aria-label
表示/動作: 内部inputのaria-labelを設定します。
許容値・範囲・競合: 空文字は属性を除去。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_OPTION_TYPE_INVALID
具体例: aria-label="検索文字"
設定後の表示/動作: 内部inputのaria-labelになります。視覚表示は変えず支援技術へ名前を提供します。
許容値の詳細: 任意string。
関連/競合: placeholderの代替ではありません。
不正例: BoneTextBox.setOptions(root,{ariaLabel:{}})
修正例: data-aria-label="検索文字"

3.16 `className`

初めて使う人向け: 実TextBox本体へ追加CSS Classを付けます。元inputではなく生成後の.bone-textboxへ付きます。
型: string
Runtime Default: ""
HTML指定: data-class-name
表示/動作: 実TextBox本体（.bone-textbox）へ追加Classを設定します。
許容値・範囲・競合: 空白区切りClass。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_OPTION_TYPE_INVALID
具体例: data-class-name="my-textbox"
設定後の表示/動作: create時に実TextBox本体（.bone-textbox）へmy-textbox Classを追加します。
許容値の詳細: 任意string。
関連/競合: setOptions後のclass差替え用途ではなくcreate時root追加Classとして扱います。
不正例: BoneTextBox.setOptions(root,{className:{}})
修正例: data-class-name="customer-field"

3.17 `theme`

初めて使う人向け: TextBoxの文字・placeholder・枠・強調色の組み合わせを切り替えます。
型: enum
Runtime Default: "default"
HTML指定: data-theme
表示/動作: TextBoxのテーマ色を切替えます。
許容値・範囲・競合: default / dark / light / neon。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_OPTION_ENUM_INVALID
具体例: data-theme="neon"
設定後の表示/動作: 背景面/background/強調色等のTheme既定色をneonへ切替えます。4値はLive Sampleで比較できます。
許容値の詳細: default / dark / light / neon。
関連/競合: backgroundColorが明示HEX/transparentなら背景はその値が優先されます。
不正例: data-theme="blue"
修正例: data-theme="neon"

3.18 `backgroundColor`

初めて使う人向け: 入力欄の背景だけをTheme既定・透明・HEXから指定します。Themeの文字色や枠色はそのままです。
型: string
Runtime Default: "theme"
HTML指定: data-background-color
表示/動作: TextBox背景をTheme/透明/HEXで設定します。
許容値・範囲・競合: theme / transparent / #RGB / #RRGGBB / #RRGGBBAA。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_BACKGROUND_COLOR_INVALID
具体例: data-background-color="#26354acc"
設定後の表示/動作: root背景を半透明HEXへ変更します。themeならTheme既定、transparentなら親背景が透けます。
許容値の詳細: theme / transparent / #RGB / #RGBA / #RRGGBB / #RRGGBBAA。
関連/競合: url(), rgb(), named colorはRuntime契約外。#040は色を選ぶUIだけを担当します。
不正例: data-background-color="url(x)"
修正例: data-background-color="#26354a"

3.19 `appearance`

初めて使う人向け: 枠の形をnormal / flat / borderlessで切り替えます。inheritは親要素追従を有効にする互換値です。
型: enum
Runtime Default: "normal"
HTML指定: data-appearance
表示/動作: 外枠外観を切替えます。
許容値・範囲・競合: normal / flat / borderless / inherit。inheritは親依存を有効化。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_OPTION_ENUM_INVALID
具体例: data-appearance="borderless"
設定後の表示/動作: normal/flat/borderlessで外枠外観を切替えます。inheritは互換入力としてinheritParent=trueへ正規化されます。
許容値の詳細: normal / flat / borderless / inherit。
関連/競合: inherit指定後の正規化appearanceはnormalで、親追従はinheritParent側で保持します。
不正例: data-appearance="rounded"
修正例: data-appearance="flat"

3.20 `inheritParent`

初めて使う人向け: TextBox自身のサイズや背景ではなく、親要素の見た目へ100%追従させます。
型: boolean
Runtime Default: false
HTML指定: data-inherit-parent
表示/動作: 親要素の幅・高さ・背景・文字色・枠色・角丸・textAlignを継承します。
許容値・範囲・競合: trueではwidth/height/position/inputAlignの単体指定より親スタイルが優先。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_FUNCTIONAL_CLASS_BOOLEAN_INVALID (HTML宣言時)
具体例: data-inherit-parent="true"
設定後の表示/動作: trueでrootは親の幅/高さ100%と背景・文字色・枠色・角丸・text-alignへ追従します。
許容値の詳細: true / false。
関連/競合: true時は単体width/height/position/inputAlignより親styleが表示上優先されます。親変更後はsyncParentStyle()。
不正例: data-inherit-parent="maybe"
修正例: data-inherit-parent="true"

3.21 `width`

初めて使う人向け: 単体表示時のTextBox幅です。親追従ONでは画面上は親幅100%が優先されます。
型: number px
Runtime Default: 320
HTML指定: data-width
表示/動作: 単体TextBoxの幅を設定します。
許容値・範囲・競合: 40～4000px。inheritParent=trueでは100%。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_SIZE_INVALID
具体例: data-width="420"
設定後の表示/動作: 単体rootの幅を420pxにします。
許容値の詳細: 40～4000の数値（px）。
関連/競合: inheritParent=trueでは親100%追従が表示上優先。
不正例: data-width="20"
修正例: data-width="320"

3.22 `height`

初めて使う人向け: 単体表示時の入力欄高さです。親追従ONでは親高さが優先されます。
型: number px
Runtime Default: 44
HTML指定: data-height
表示/動作: 単体TextBoxの高さを設定します。
許容値・範囲・競合: 24～2000px。inheritParentでは親高さへ追従。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_SIZE_INVALID
具体例: data-height="56"
設定後の表示/動作: 単体rootの高さを56pxにします。
許容値の詳細: 24～2000の数値（px）。
関連/競合: inheritParent=trueでは親100%追従が表示上優先。
不正例: data-height="10"
修正例: data-height="44"

3.23 `position`

初めて使う人向け: 親がgrid/flex等で配置を受けられる時、TextBox自身を9方向のどこへ置くか決めます。
型: enum
Runtime Default: "center"
HTML指定: data-position
表示/動作: 親Preview内での表示位置を9方向から選びます。
許容値・範囲・競合: top-left / top-center / top-right / middle-left / center / middle-right / bottom-left / bottom-center / bottom-right。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_OPTION_ENUM_INVALID
具体例: data-position="bottom-right"
設定後の表示/動作: 親配置領域の右下へrootを配置します。9値それぞれをLive Sampleで比較できます。
許容値の詳細: top-left / top-center / top-right / middle-left / center / middle-right / bottom-left / bottom-center / bottom-right。
関連/競合: Default=center。inheritParent=trueでは親吸着が優先されます。
不正例: data-position="left-top"
修正例: data-position="top-left"

3.24 `inputAlign`

初めて使う人向け: 入力文字の横寄せです。autoは通常left、親追従時は親text-alignを使います。
型: enum
Runtime Default: "auto"
HTML指定: data-input-align
表示/動作: 入力文字の横位置を設定します。
許容値・範囲・競合: auto / left / center / right。autoは通常left、親依存時は親textAlign。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_OPTION_ENUM_INVALID
具体例: data-input-align="right"
設定後の表示/動作: 入力文字を右寄せします。autoは単体時left、親追従時は親text-alignを利用します。
許容値の詳細: auto / left / center / right。
関連/競合: inheritParent=true + autoで親text-alignを反映します。
不正例: data-input-align="justify"
修正例: data-input-align="right"

3.25 `activeBorderEffect`

初めて使う人向け: TextBoxへfocusしている間の枠Effectです。描画は#022へ委譲します。
型: enum
Runtime Default: "normal"
HTML指定: data-active-border-effect
表示/動作: focus中の枠Effectを#022へ委譲します。
許容値・範囲・競合: normal / neon / spin / cross / blink。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_OPTION_ENUM_INVALID / TEXTBOX_022_DEPENDENCY_REQUIRED
具体例: data-active-border-effect="spin"
設定後の表示/動作: inputがfocus中だけ#022 spin枠Effectを表示し、blurで消します。
許容値の詳細: normal / neon / spin / cross / blink。
関連/競合: Mouse Over Effectとは独立attach。normalは追加Effectなし。
不正例: data-active-border-effect="pulse"
修正例: data-active-border-effect="spin"

3.26 `activeEffectColor`

初めて使う人向け: focus中Effectの色です。themeまたはHEXだけを受理します。
型: string
Runtime Default: "theme"
HTML指定: data-active-effect-color
表示/動作: Active Effect色を設定します。
許容値・範囲・競合: theme または安全なHEX。#040は選択UI、Runtimeは値のみ受領。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_ACTIVE_EFFECT_COLOR_INVALID
具体例: data-active-effect-color="#35f4ff"
設定後の表示/動作: Active Effectの色をcyanへ変更します。
許容値の詳細: theme / #RGB / #RGBA / #RRGGBB / #RRGGBBAA。
関連/競合: #040 ColorPickerのsolid RETURNをこのPropertyへ設定できます。
不正例: data-active-effect-color="red"
修正例: data-active-effect-color="#35f4ff"

3.27 `activeEffectDirection`

初めて使う人向け: focus中Effectの進行方向を#022へ渡します。neon/spinで見た目の方向が変わります。
型: enum
Runtime Default: "clockwise"
HTML指定: data-active-effect-direction
表示/動作: Active Effect方向を設定します。
許容値・範囲・競合: clockwise / counterclockwise。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_OPTION_ENUM_INVALID
具体例: data-active-effect-direction="counterclockwise"
設定後の表示/動作: spin/cross等の方向契約を反時計回りへ渡します。
許容値の詳細: clockwise / counterclockwise。
関連/競合: Effect=normalでは視覚差がありません。
不正例: data-active-effect-direction="left"
修正例: data-active-effect-direction="counterclockwise"

3.28 `activeEffectSpeed`

初めて使う人向け: focus中Effectのアニメーション速度を#022へ渡します。normal/crossのように動かないEffectでは見た目の差が出ません。
型: enum
Runtime Default: "normal"
HTML指定: data-active-effect-speed
表示/動作: Active Effect速度を設定します。
許容値・範囲・競合: slow / normal / fast。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_OPTION_ENUM_INVALID
具体例: data-active-effect-speed="fast"
設定後の表示/動作: Active Effectのアニメーション速度をfastへ渡します。
許容値の詳細: slow / normal / fast。
関連/競合: Effect=normalでは視覚差がありません。
不正例: data-active-effect-speed="turbo"
修正例: data-active-effect-speed="fast"

3.29 `mouseoverBorderEffect`

初めて使う人向け: マウスをTextBoxへ重ねている間の枠Effectです。focus用Effectとは別設定です。
型: enum
Runtime Default: "normal"
HTML指定: data-mouseover-border-effect
表示/動作: Mouse Over時の枠Effectを#022へ委譲します。
許容値・範囲・競合: normal / neon / spin / cross / blink。Activeとは独立。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_OPTION_ENUM_INVALID / TEXTBOX_022_DEPENDENCY_REQUIRED
具体例: data-mouseover-border-effect="neon"
設定後の表示/動作: controlへmouseenterした間だけ#022 neon枠Effectを表示し、mouseleaveで消します。
許容値の詳細: normal / neon / spin / cross / blink。
関連/競合: Active Effectとは独立して同時保持できます。
不正例: data-mouseover-border-effect="pulse"
修正例: data-mouseover-border-effect="neon"

3.30 `mouseoverEffectColor`

初めて使う人向け: Mouse Over Effectの色です。themeまたはHEXだけを受理します。
型: string
Runtime Default: "theme"
HTML指定: data-mouseover-effect-color
表示/動作: Mouse Over Effect色を設定します。
許容値・範囲・競合: theme または安全なHEX。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_ACTIVE_EFFECT_COLOR_INVALID
具体例: data-mouseover-effect-color="#ff33cc"
設定後の表示/動作: Mouse Over Effect色をmagentaへ変更します。
許容値の詳細: theme / #RGB / #RGBA / #RRGGBB / #RRGGBBAA。
関連/競合: #040 ColorPicker solid RETURNを利用できます。
不正例: data-mouseover-effect-color="red"
修正例: data-mouseover-effect-color="#ff33cc"

3.31 `mouseoverEffectDirection`

初めて使う人向け: Mouse Over Effectの進行方向を#022へ渡します。
型: enum
Runtime Default: "clockwise"
HTML指定: data-mouseover-effect-direction
表示/動作: Mouse Over Effect方向を設定します。
許容値・範囲・競合: clockwise / counterclockwise。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_OPTION_ENUM_INVALID
具体例: data-mouseover-effect-direction="counterclockwise"
設定後の表示/動作: Mouse Over spin/cross等の方向を反時計回りへ渡します。
許容値の詳細: clockwise / counterclockwise。
関連/競合: Effect=normalでは視覚差がありません。
不正例: data-mouseover-effect-direction="left"
修正例: data-mouseover-effect-direction="clockwise"

3.32 `mouseoverEffectSpeed`

初めて使う人向け: Mouse Over Effectのアニメーション速度を#022へ渡します。
型: enum
Runtime Default: "normal"
HTML指定: data-mouseover-effect-speed
表示/動作: Mouse Over Effect速度を設定します。
許容値・範囲・競合: slow / normal / fast。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_OPTION_ENUM_INVALID
具体例: data-mouseover-effect-speed="fast"
設定後の表示/動作: Mouse Over Effectの速度をfastへ渡します。
許容値の詳細: slow / normal / fast。
関連/競合: Effect=normalでは視覚差がありません。
不正例: data-mouseover-effect-speed="turbo"
修正例: data-mouseover-effect-speed="slow"

3.33 `securityMaxLength`

初めて使う人向け: Runtimeが安全性検査で受け入れる文字列長の上限です。業務上のmaxlengthとは別です。
型: integer
Runtime Default: 262144
HTML指定: data-security-max-length
表示/動作: Security Gateが受理する文字列長の上限です。
許容値・範囲・競合: 1～1048576。maxlengthはこの値以下。既存committedValueより小さく変更不可。
不正な設定: 型違い・範囲外・未対応値は下記の関連Errorで拒否し、その設定変更を採用しません。
関連Error: TEXTBOX_SECURITY_LIMIT_INVALID / TEXTBOX_EXISTING_VALUE_SECURITY_LIMIT / TEXTBOX_MAXLENGTH_SECURITY_RANGE
具体例: data-security-max-length="1024"
設定後の表示/動作: Security Gateが受理する最大文字数を1024へ変更します。1025文字以上はcommit前に拒否します。
許容値の詳細: 1～1048576の整数。Default 262144。
関連/競合: maxlengthはこの値以下。現在committedValueより小さくsetOptionsすることも拒否されます。
不正例: data-security-max-length="0"
修正例: data-security-max-length="262144"

4. JavaScript専用Callback 全15件

4.0 Callback共通payloadと受け取り方

15 CallbackはHTML data-* では指定せず、create() / setOptions() のJavaScript optionへFunctionとして渡します。各Callbackのevent固有項目に加え、Runtime event detailには識別用の共通情報として componentId / componentName / version / boneId / boneType が付与されます。CallbackでDOMを書き換える前に、必要なら boneId とevent固有 source を確認してください。

BoneTextBox.setOptions(root, {
  onCommit(detail) {
    console.log(detail.componentId, detail.boneId, detail.value, detail.source);
  }
});

CallbackはHTML data属性へFunction文字列として埋め込みません。BoneTextBox.create() / setOptions()のJavaScript経路でFunctionを渡します。Runtime Eventと同じdetailがCallbackへ渡されます。

4.1 `onInput`

発火Event: bone-textbox:input
payload: value / previousValue / source="user" / composing
動作: inputイベントごとの編集値通知。IME composing中はcomposing=true。
設定例: BoneTextBox.setOptions(root, { onInput: detail => console.log(detail) });

4.2 `onChange`

発火Event: bone-textbox:change
payload: value / previousValue / source="user"
動作: blur時にedit開始値から変化していた場合のchange通知。
設定例: BoneTextBox.setOptions(root, { onChange: detail => console.log(detail) });

4.3 `onCommit`

発火Event: bone-textbox:commit
payload: value / previousValue / source / validation / bone
動作: Enter・blur・API setValue emit=true等で確定した値を受け取る。
設定例: BoneTextBox.setOptions(root, { onCommit: detail => console.log(detail) });

4.4 `onInvalid`

発火Event: bone-textbox:invalid
payload: value / previousValue / source / validation
動作: commitInvalid=falseでValidation不正のcommitが拒否された時に受け取る。
設定例: BoneTextBox.setOptions(root, { onInvalid: detail => console.log(detail) });

4.5 `onFocus`

発火Event: bone-textbox:focus
payload: value / source="user"
動作: 実input focusとActive Effect開始のタイミングを受け取る。
設定例: BoneTextBox.setOptions(root, { onFocus: detail => console.log(detail) });

4.6 `onBlur`

発火Event: bone-textbox:blur
payload: value / source="user"
動作: 実input blurを受け取る。blurCommit=trueではこの後commit経路へ進む。
設定例: BoneTextBox.setOptions(root, { onBlur: detail => console.log(detail) });

4.7 `onCompositionstart`

発火Event: bone-textbox:compositionstart
payload: value / source="user"
動作: IME composition開始。Enter commit抑止の開始点。
設定例: BoneTextBox.setOptions(root, { onCompositionstart: detail => console.log(detail) });

4.8 `onCompositionupdate`

発火Event: bone-textbox:compositionupdate
payload: value / source="user"
動作: IME composition更新。
設定例: BoneTextBox.setOptions(root, { onCompositionupdate: detail => console.log(detail) });

4.9 `onCompositionend`

発火Event: bone-textbox:compositionend
payload: value / source="user"
動作: IME composition終了。以後Enter commit可能。
設定例: BoneTextBox.setOptions(root, { onCompositionend: detail => console.log(detail) });

4.10 `onReset`

発火Event: bone-textbox:reset
payload: value / source="escape" または "api"
動作: Escapeまたはreset()でeditingValueがcommittedValueへ戻った時。
設定例: BoneTextBox.setOptions(root, { onReset: detail => console.log(detail) });

4.11 `onInAccepted`

発火Event: bone-textbox:in-accepted
payload: accepted / blocked / source / value / state
動作: Joint INがSecurity/契約検査を通過し値が更新された時。
設定例: BoneTextBox.setOptions(root, { onInAccepted: detail => console.log(detail) });

4.12 `onInRejected`

発火Event: bone-textbox:in-rejected
payload: accepted=false / blocked=true / code / message / preservedValue / suggestedJointState="blocked"
動作: Joint IN拒否時。直前committedValueは保持される。
設定例: BoneTextBox.setOptions(root, { onInRejected: detail => console.log(detail) });

4.13 `onSecurityRejected`

発火Event: bone-textbox:security-rejected
payload: code / message / source
動作: ユーザーinputのSecurity検査が制御文字・壊れたUnicode文字列（片側だけのサロゲート）・上限等で拒否された時。
設定例: BoneTextBox.setOptions(root, { onSecurityRejected: detail => console.log(detail) });

4.14 `onDeliveryState`

発火Event: bone-textbox:delivery-state
payload: deliveryState / detail / targetReady / queueLength
動作: 実#002 ChannelのREADY/WAIT/BLOCKED等の状態変化。
設定例: BoneTextBox.setOptions(root, { onDeliveryState: detail => console.log(detail) });

4.15 `onDelivery`

発火Event: bone-textbox:delivery
payload: source / output / result
動作: commitされたOUT payloadを#002 Channelへdeliverした結果。
設定例: BoneTextBox.setOptions(root, { onDelivery: detail => console.log(detail) });

5. editingValue / committedValue / commit

TextBoxでは「画面で編集中の値」と「確定して外へ使える値」を分けます。これを理解するとEnter、blur、Escape、OUTの動きが分かります。

入力開始前: editingValue === committedValue。dirty=false。
文字を入力: editingValueだけ更新。枠がdirty表示になり、committedValueは前の値のまま。
Enter (enterCommit=true): Validationを確認し、成功するとcommittedValueへコピー。OUT接続済みなら確定値を配送。
blur (blurCommit=true): Enterと同じくcommitを試みます。
Escape: 入力途中を捨て、editingValueをcommittedValueへ戻します。
reset(): APIからEscapeと同じ「未確定分を破棄」を行います。
setValue(): APIからeditingValue / committedValueの両方を同時に新しい値へ更新します。emit:trueを付けた時だけcommit EventとOUT配送を行います。

例: committedValueがABCの時にABCDまで入力しただけなら、画面はABCDでもOUT値はまだABCです。Enterで初めてABCDが確定します。

6. Validation / Security / 文字数

6.1 どの検査が何を止めるか

Validation: required / minlength / maxlength。安全な文字列に対する入力ルールです。失敗してもeditingValueは画面に残ります。commitInvalid=falseなら確定だけを止めます。
Security: securityMaxLength、制御文字、壊れたUnicode、危険なObject入力。安全でない値をeditingValueへ採用する前に止めます。
commitInvalid=trueで無視できるのはValidationだけです。Security拒否は必ず拒否します。

6.2 具体例

required=true / minlength=3 / maxlength=8 で AB を入力すると、文字列自体は安全なので画面には表示されますがValidationはinvalidです。EnterしてもDefaultのcommitInvalid=falseではcommittedValueは更新されません。ABCへ直すとcommitできます。

securityMaxLength=8 で9文字目を入力しようとした場合はSecurity拒否です。9文字目はeditingValueへ採用されず、直前の8文字を維持します。

[[BF-TEXTBOX-SAMPLE:required]]

[[BF-TEXTBOX-SAMPLE:security]]

6.3 文字数設定の関係

minlength: 0以上。未指定はnull。
maxlength: 0以上。未指定はnull。
minlength <= maxlength が必要です。
maxlength <= securityMaxLength が必要です。
securityMaxLength: Default 262144、許容1～1048576。

7. Theme / Background / Appearance

7.1 Theme 全4値 — 何が変わるか

Themeは文字色・placeholder色・通常枠色・強調色の組み合わせを変えます。backgroundColorを明示した場合、背景だけはそちらが優先されます。

default — 濃紺背景向け。白系文字、灰青枠、青の強調色。
dark — defaultより暗い配色。白系文字、暗めの枠、水色の強調色。
light — 明るい背景向け。濃い文字、明るい灰枠、青の強調色。
neon — 暗い背景にcyan系の文字/枠/強調色と軽いglow。

[[BF-TEXTBOX-SAMPLE:themeDefault]]

[[BF-TEXTBOX-SAMPLE:themeDark]]

[[BF-TEXTBOX-SAMPLE:themeLight]]

[[BF-TEXTBOX-SAMPLE:themeNeon]]

7.2 Background

theme — 選択中Themeの既定背景。
transparent — 入力欄背景を透明にして親背景を見せる。
HEX — #RGB / #RGBA / #RRGGBB / #RRGGBBAA。alpha付きHEXも可。
red、url(...)、gradient等は受理しません。

[[BF-TEXTBOX-SAMPLE:bgTransparent]]

[[BF-TEXTBOX-SAMPLE:bgCustom]]

[[BF-TEXTBOX-SAMPLE:colorRgba]]

7.3 Appearance 全4値

normal — 角丸8pxの標準1px枠。Default。
flat — 角丸を0にして四角い1px枠。box-shadowを使わない。
borderless — 通常枠を透明にして枠なし表示。
inherit — 互換用の値。内部ではinheritParent=trueとして扱い、Appearance自体はnormalへ戻します。

[[BF-TEXTBOX-SAMPLE:appNormal]]

[[BF-TEXTBOX-SAMPLE:appFlat]]

[[BF-TEXTBOX-SAMPLE:appBorderless]]

8. Layout / Position / inputAlign

8.1 Position 全9値

positionはTextBoxの親レイアウト内での自己配置を指定します。CSSのjustify-self / align-selfで動くため、親側がgrid等で配置を受けられる領域で意味を持ちます。TextBoxの幅/高さそのものは変えません。Defaultはcenterです。

top-left — 左上。横=start / 縦=start。
top-center — 上中央。横=center / 縦=start。
top-right — 右上。横=end / 縦=start。
middle-left — 左中央。横=start / 縦=center。
center — 中央。横=center / 縦=center。Default。
middle-right — 右中央。横=end / 縦=center。
bottom-left — 左下。横=start / 縦=end。
bottom-center — 下中央。横=center / 縦=end。
bottom-right — 右下。横=end / 縦=end。

inheritParent=trueでは親へstretchするため、画面上のposition指定は無視されます。

[[BF-TEXTBOX-SAMPLE:posTopLeft]]

[[BF-TEXTBOX-SAMPLE:posTopCenter]]

[[BF-TEXTBOX-SAMPLE:posTopRight]]

[[BF-TEXTBOX-SAMPLE:posMiddleLeft]]

[[BF-TEXTBOX-SAMPLE:posCenter]]

[[BF-TEXTBOX-SAMPLE:posMiddleRight]]

[[BF-TEXTBOX-SAMPLE:posBottomLeft]]

[[BF-TEXTBOX-SAMPLE:posBottomCenter]]

[[BF-TEXTBOX-SAMPLE:posBottomRight]]

8.2 inputAlign 全4値

auto — 単体表示ではleft。inheritParent=trueでは親のtext-alignを使う。
left — 入力文字を左寄せ。
center — 入力文字を中央寄せ。
right — 入力文字を右寄せ。

8.3 inheritParent — 何が優先されるか

data-inherit-parent="true"を指定すると、TextBoxは親の幅/高さ・背景・文字色・角丸・text-alignへ追従します。画面上は width / height / position / inputAlign / backgroundColor / 通常枠 より親styleが優先されます。Property値自体が消えるわけではありません。OFFへ戻せば単体設定が再び表示へ反映されます。

親styleをJavaScriptで後から変更した時は BoneTextBox.syncParentStyle(root) で再取得できます。

[[BF-TEXTBOX-SAMPLE:inheritParent]]

9. Active Border Effect — #022

Active Effectは入力欄にfocusがある間だけ表示する枠Effectです。TextBoxは設定を#022 Hover Border Effectへ渡し、Effect描画そのものは#022が担当します。blurすると非表示になります。

9.1 Effect 全5値

normal — 通常枠。追加アニメーションなし。direction/speedを設定しても動きません。
neon — 光る線が枠沿いに移動。directionで進行方向、speedで移動速度が変わります。
spin — conic-gradientの光が枠を回転。directionとspeedがそのまま見た目へ反映されます。
cross — 交差形状の枠表現。現在の#022では静止表示なのでdirection/speedによる動きはありません。
blink — 枠を点滅。speedで点滅周期が変わります。directionによる見た目差はありません。

9.2 Direction 全2値

clockwise — neon/spinを標準方向へ進める。Default。
counterclockwise — neon/spinのアニメーションを逆方向へする。

9.3 Speed 全3値

slow — #022 duration 2s。
normal — 1.2s。Default。
fast — 0.65s。

色はthemeまたはHEXです。focusしていない時はEffectは見えません。

[[BF-TEXTBOX-SAMPLE:activeNeon]]

[[BF-TEXTBOX-SAMPLE:activeSpin]]

[[BF-TEXTBOX-SAMPLE:activeCross]]

[[BF-TEXTBOX-SAMPLE:activeBlink]]

10. Mouse Over Border Effect — #022

Mouse Over EffectはTextBoxへマウスを重ねている間だけ表示します。Active Effectとは別の#022 attachなので、focus中とhover中が重なっても設定を上書きしません。

Effect値はActiveと同じ normal / neon / spin / cross / blink。
Directionの意味もActiveと同じです。
Speedはslow=2s / normal=1.2s / fast=0.65s。
normalは追加アニメーションなし、crossは静止、blinkではdirectionの見た目差はありません。

[[BF-TEXTBOX-SAMPLE:hoverNeon]]

[[BF-TEXTBOX-SAMPLE:hoverSpin]]

[[BF-TEXTBOX-SAMPLE:hoverCross]]

[[BF-TEXTBOX-SAMPLE:hoverBlink]]

11. 基本操作 / Focus / IME / 選択

focus: クリック/Tab、またはfocus()で入力開始。selectOnFocus=trueなら全選択。
入力: editingValueが更新され、committedValueとの差があればdirty状態になります。
Enter: enterCommit=trueかつIME変換中でなければcommit。
blur: blurCommit=trueならcommitを試みます。
Escape: 未確定編集を破棄して最後のcommittedValueへ戻します。
IME: compositionstart～compositionend中はEnter commitを抑止し、日本語変換確定をcommitと誤認しません。
文字選択: select() / setSelectionRange() / getSelection()。

12. Untrusted IN / Security

applyJointInput()は#002から来た値をそのまま信用せず、安全に読めるObjectか、valueがstringか、制御文字/壊れたUnicode/長さ超過がないかを確認します。Objectを勝手にString()へ変換しません。getterやProxy等の特殊Objectで安全にPropertyを読めない場合も拒否します。

12.1 許可例 — HTML風文字列も「文字」として扱う

const result = BoneTextBox.applyJointInput(root, {
  source: "joint",
  value: "<script>alert(1)</script>",
  state: { status: "connected" }
});

この値はscriptとして実行せず、文字列<script>alert(1)</script>そのものとしてcommittedValueへ入ります。

12.2 拒否例と値保持 — 制御文字を含む

const before = BoneTextBox.getCommittedValue(root);
const result = BoneTextBox.applyJointInput(root, {
  source: "joint",
  value: "A\u0000B",
  state: { status: "connected" }
});
const after = BoneTextBox.getCommittedValue(root);

TEXTBOX_CONTROL_CHARACTER_REJECTEDでaccepted=false / blocked=trueとなり、after === beforeを維持します。拒否値で既存の確定値を壊しません。

13. #002 Joint IN

#002 Joint INは、別ComponentからTextBoxへ値を渡す正式経路です。payloadの主な項目は source / value / state です。

source — どこから来た値かを示す文字列。
value — TextBoxへ入れる文字列。Security検査対象。
state — 接続状態。string、または{status, reason}のObject。
受理: editingValue / committedValue / Bone.valueを同時更新し、bone-textbox:in-acceptedを発火。
拒否: 値を維持し、bone-textbox:in-rejectedを発火。

BoneTextBox.applyJointInput(root, {
  source: "upstream-001",
  value: "受信文字列",
  state: { status: "connected", reason: "normal" }
});

14. OUT WAIT / FIFO / BLOCKED

OUTはcommit済みのcommittedValueだけを#002 Delivery Channelへ渡します。入力中のeditingValueは送信しません。

14.1 WAIT → FIFO配送

connectOutput(... targetReady:false)でTarget Busy状態にする。
Aをcommit → 接続は維持したままWAIT、QueueへA。
Bをcommit → Queueは[A,B]。
setTargetReady(root,true) → ReadyになりA→Bの順で自動配送。

const delivered = [];
BoneTextBox.connectOutput(root, {
  targetReady: false,
  deliver: output => delivered.push(output.value)
});
BoneTextBox.setValue(root, "A"); BoneTextBox.commit(root, "demo");
BoneTextBox.setValue(root, "B"); BoneTextBox.commit(root, "demo");
BoneTextBox.setTargetReady(root, true);
// WAIT中は queue=[A,B]。Ready後 delivered === ["A", "B"]

14.2 BLOCKED → 解除

guardが拒否した場合は接続を切らずBLOCKEDになります。拒否した値はTargetへ配送しません。clearOutputBlock()で解除後、安全な値をcommitして再開します。

BoneTextBox.connectOutput(root, {
  targetReady: true,
  guard: output => output.value === "BAD"
    ? { allowed:false, reason:"security", code:"APP_BLOCK" }
    : true,
  deliver: output => console.log(output.value)
});

getOutputState()でwaiting / blocked / readyを、getOutputQueue()でQueue内容を確認できます。

15. #040 ColorPicker責務分離

#040は色を選んでsolid HEXを返すUI、#027はそのHEXをTextBoxのPropertyへ適用する側です。#027内に別ColorPickerを作りません。

function applyPickedColor(hex) {
  BoneTextBox.setOptions(root, { backgroundColor: hex });
}
function applyActiveEffectColor(hex) {
  BoneTextBox.setOptions(root, { activeEffectColor: hex });
}
function applyMouseOverEffectColor(hex) {
  BoneTextBox.setOptions(root, { mouseoverEffectColor: hex });
}

使用先は backgroundColor / activeEffectColor / mouseoverEffectColor。gradientはこれらPropertyでは受理しません。

16. Event / Callback

Runtimeは状態変化を bone-textbox:<event> というDOM Eventで実TextBox本体から通知します。Eventは親DOMへも伝播するため、個別TextBoxだけでなく上位Containerでも監視できます。

Callback (onInput等) は同じ状態変化をJavaScript Functionとして直接受け取る方法です。

主なEvent: input / change / commit / invalid / focus / blur / compositionstart / compositionupdate / compositionend / reset / in-accepted / in-rejected / security-rejected / delivery-state / delivery。

17. Public API 全35件

API個別項目は左TOCを過密化しないためH4で記載します。各APIは「用途・引数・戻り値・状態変化・Error・使用例」まで説明します。

17.1 `defaults()`

用途: 33件のRuntime既定Propertyをcloneで取得する。
引数: なし
戻り値: Object
状態/DOM: Runtime instanceやDOMを変更しない。設定UIの初期値確認に使用する。
Error: なし（依存Runtimeが読込済みであること）。
使用例:

const defaults = BoneTextBox.defaults();

確認ポイント: Runtime instanceやDOMを変更しない。設定UIの初期値確認に使用する。

17.2 `normalizeOptions(options)`

用途: HTML/JavaScriptで指定した設定Objectを、TextBoxが使える型・範囲・列挙値か確認し、正式な設定Objectへ変換します。
引数: options: 通常のJavaScriptオブジェクト（{}で作るObject）
戻り値: Object
状態/DOM: 33 Propertyの型・範囲・列挙値・相互条件を検証し、正規化済みcloneを返す。DOMは作らない。
Error: TEXTBOX_OPTIONS_INVALID / TEXTBOX_OPTION_TYPE_INVALID / TEXTBOX_OPTION_ENUM_INVALID / 各範囲Error。
使用例:

const opts = BoneTextBox.normalizeOptions({ theme: "neon", width: 420 });

確認ポイント: 33 Propertyの型・範囲・列挙値・相互条件を検証し、正規化済みcloneを返す。DOMは作らない。

17.3 `validateValue(value, options)`

用途: 文字列をrequired/minlength/maxlength/security条件で検証する。
引数: value: string, options: Property object
戻り値: Validation Object
状態/DOM: DOMやinstanceを変更せず、valid/errors/warnings/value/lengthを返す。options自体が不正でも例外化せずvalid=falseを返す。
Error: 値型・長さ・required/minlength/maxlength/securityに対応するTEXTBOX_*。
使用例:

const result = BoneTextBox.validateValue("ABC", { required: true, minlength: 2 });

確認ポイント: DOMやinstanceを変更せず、valid/errors/warnings/value/lengthを返す。options自体が不正でも例外化せずvalid=falseを返す。

17.4 `inspectUntrustedText(value, limit)`

用途: Untrusted文字列を強制String変換せずSecurity検査する。
引数: value, limit
戻り値: Inspection Object
状態/DOM: stringだけを受理し、制御文字・壊れたUnicode文字列（片側だけのサロゲート）・上限超過を検査する。DOM/committedValueは変更しない。
Error: TEXTBOX_VALUE_TYPE_REJECTED / TEXTBOX_SECURITY_LENGTH_EXCEEDED / TEXTBOX_CONTROL_CHARACTER_REJECTED / TEXTBOX_UNPAIRED_SURROGATE_REJECTED。
使用例:

const check = BoneTextBox.inspectUntrustedText(payload, 4096);

確認ポイント: stringだけを受理し、制御文字・壊れたUnicode文字列（片側だけのサロゲート）・上限超過を検査する。DOM/committedValueは変更しない。

17.5 `create(boneInput, options)`

用途: Bone入力から実TextBox rootを生成する。
引数: boneInput: plain Bone object, options: Property/callback object
戻り値: HTMLElement
状態/DOM: editingValueとcommittedValueをBone valueで初期化し、input/feedback DOMと#022 Effectを構成する。
Error: TEXTBOX_DOM_REQUIRED / TEXTBOX_OPTIONS_INVALID / Bone契約Error / #001/#002/#022依存Error。
使用例:

const root = BoneTextBox.create(BoneCore.create({ id: "name", type: "TEXTBOX", value: "ABC" }), { theme: "dark" });

確認ポイント: editingValueとcommittedValueをBone valueで初期化し、input/feedback DOMと#022 Effectを構成する。

17.6 `isInstance(element)`

用途: 要素がBoneTextBox管理rootか判定する。
引数: element
戻り値: boolean
状態/DOM: 状態を変更しない。destroy後はfalse。
Error: なし。
使用例:

if (BoneTextBox.isInstance(root)) { /* safe to call instance APIs */ }

確認ポイント: 状態を変更しない。destroy後はfalse。

17.7 `getInput(element)`

用途: 実TextBox本体（.bone-textbox）内部の実input要素を取得する。
引数: element: instance root
戻り値: HTMLInputElement
状態/DOM: 状態を変更しない。選択位置確認など、必要な実input参照用。値変更はTextBox APIを使用する。
Error: TEXTBOX_INSTANCE_INVALID。
使用例:

const input = BoneTextBox.getInput(root);

確認ポイント: 状態を変更しない。選択位置確認など、必要な実input参照用。値変更はTextBox APIを使用する。

17.8 `getValue(element)`

用途: 現在の確定値committedValueを取得する。
引数: element
戻り値: string
状態/DOM: editingValueが未commitでも確定値だけを返す。
Error: TEXTBOX_INSTANCE_INVALID。
使用例:

const committed = BoneTextBox.getValue(root);

確認ポイント: editingValueが未commitでも確定値だけを返す。

17.9 `getEditingValue(element)`

用途: 現在の編集中値editingValueを取得する。
引数: element
戻り値: string
状態/DOM: 未commitの入力内容を確認できる。committedValueは変更しない。
Error: TEXTBOX_INSTANCE_INVALID。
使用例:

const editing = BoneTextBox.getEditingValue(root);

確認ポイント: 未commitの入力内容を確認できる。committedValueは変更しない。

17.10 `getCommittedValue(element)`

用途: 現在の確定値を明示的に取得する。
引数: element
戻り値: string
状態/DOM: getValue()と同じcommittedValueを返す。
Error: TEXTBOX_INSTANCE_INVALID。
使用例:

const committed = BoneTextBox.getCommittedValue(root);

確認ポイント: getValue()と同じcommittedValueを返す。

17.11 `getBone(element)`

用途: 現在のBone契約をcloneで取得する。
引数: element
戻り値: Object
状態/DOM: id/type/valueを含むBoneのcloneを返し、内部Boneを直接変更させない。
Error: TEXTBOX_INSTANCE_INVALID。
使用例:

const bone = BoneTextBox.getBone(root);

確認ポイント: id/type/valueを含むBoneのcloneを返し、内部Boneを直接変更させない。

17.12 `getOptions(element)`

用途: 現在の正規化済み33 Propertyをcloneで取得する。
引数: element
戻り値: Object
状態/DOM: 状態を変更しない。
Error: TEXTBOX_INSTANCE_INVALID。
使用例:

const options = BoneTextBox.getOptions(root);

確認ポイント: 状態を変更しない。

17.13 `getState(element)`

用途: 編集・Validation・Delivery・Effect・配置状態をまとめて取得する。
引数: element
戻り値: Object
状態/DOM: committedValue/editingValue/dirty/composing/focused/jointState/deliveryState等をcloneで返す。
Error: TEXTBOX_INSTANCE_INVALID。
使用例:

const state = BoneTextBox.getState(root);

確認ポイント: committedValue/editingValue/dirty/composing/focused/jointState/deliveryState等をcloneで返す。

17.14 `setValue(element, value, options)`

用途: APIから安全に値を設定しeditingValue/committedValue/Bone valueを同期する。
引数: element, value, options? {emit, source}
戻り値: string
状態/DOM: 既定emit=falseではcommit Event/OUT配送を発火しない。emit=trueかつ値が変化した場合はcommit EventとDeliveryを行う。
Error: TEXTBOX_INSTANCE_INVALID / Security value Error。
使用例:

BoneTextBox.setValue(root, "ABC", { emit: true, source: "api" });

確認ポイント: 既定emit=falseではcommit Event/OUT配送を発火しない。emit=trueかつ値が変化した場合はcommit EventとDeliveryを行う。

17.15 `setOptions(element, patch)`

用途: 現在Propertyへpatchを適用し再正規化・再描画する。
引数: element, patch: 通常のJavaScriptオブジェクト（{}で作るObject）
戻り値: Object
状態/DOM: 33 Propertyとcallbackを更新する。現在値より小さいsecurityMaxLengthへの変更は拒否する。
Error: TEXTBOX_OPTIONS_INVALID / Property Error / TEXTBOX_EXISTING_VALUE_SECURITY_LIMIT。
使用例:

BoneTextBox.setOptions(root, { theme: "light", width: 500 });

確認ポイント: 33 Propertyとcallbackを更新する。現在値より小さいsecurityMaxLengthへの変更は拒否する。

17.16 `applyBone(element, boneInput)`

用途: 新しいBone入力をinstanceへ適用する。
引数: element, boneInput
戻り値: Object
状態/DOM: rootのboneId/boneTypeとediting/committed/input valueを新Boneへ同期し、commit Eventは発火しない。
Error: TEXTBOX_INSTANCE_INVALID / Bone契約Error / Security Error。
使用例:

BoneTextBox.applyBone(root, { id: "name2", type: "TEXTBOX", value: "XYZ" });

確認ポイント: rootのboneId/boneTypeとediting/committed/input valueを新Boneへ同期し、commit Eventは発火しない。

17.17 `applyJointInput(element, payload)`

用途: Untrusted Joint INを安全検査して受理/拒否する。
引数: element, payload
戻り値: Result Object
状態/DOM: 受理時はediting/committed/Bone/inputを更新してin-accepted。拒否時は直前committedValueを保持してin-rejectedし、suggestedJointState=blockedを返す。
Error: Joint契約Error / Security Errorはthrowではなくaccepted=falseのResultへ変換される。
使用例:

const result = BoneTextBox.applyJointInput(root, { value: "IN", source: "joint", state: "ready" });

確認ポイント: 受理時はediting/committed/Bone/inputを更新してin-accepted。拒否時は直前committedValueを保持してin-rejectedし、suggestedJointState=blockedを返す。

17.18 `buildOutput(element, source)`

用途: 現在の確定値からOUT payloadを構築する。
引数: element, source?
戻り値: Object
状態/DOM: Deliveryは実行せず、現在Bone/committedValueとsourceを含むpayloadを生成する。
Error: TEXTBOX_INSTANCE_INVALID。
使用例:

const payload = BoneTextBox.buildOutput(root, "manual");

確認ポイント: Deliveryは実行せず、現在Bone/committedValueとsourceを含むpayloadを生成する。

17.19 `connectOutput(element, options)`

用途: 実#002 Delivery Channelを接続する。
引数: element, {targetReady, guard, deliver, onStateChange}
戻り値: Object
状態/DOM: 既存Channelがあればdisposeして接続し直す。WAIT/FIFO/BLOCKEDは#002の実Channel状態を使用する。
Error: TEXTBOX_OUTPUT_OPTIONS_INVALID / GUARD_INVALID / DELIVER_INVALID / STATE_CALLBACK_INVALID / TEXTBOX_DEPENDENCY_JOINT_MISSING。
使用例:

BoneTextBox.connectOutput(root, { targetReady: false, deliver: payload => console.log(payload) });

確認ポイント: 既存Channelがあればdisposeして接続し直す。WAIT/FIFO/BLOCKEDは#002の実Channel状態を使用する。

17.20 `disconnectOutput(element)`

用途: OUT Delivery Channelをdisposeしてunboundへ戻す。
引数: element
戻り値: boolean
状態/DOM: queue/channelを切断しdeliveryStateをunboundへ戻す。
Error: TEXTBOX_INSTANCE_INVALID。
使用例:

BoneTextBox.disconnectOutput(root);

確認ポイント: queue/channelを切断しdeliveryStateをunboundへ戻す。

17.21 `setTargetReady(element, ready)`

用途: 接続済み#002 ChannelのTarget Readyを変更する。
引数: element, ready: boolean
戻り値: Object
状態/DOM: falseでWAIT/queue、trueへ戻すとFIFO順で配送する。
Error: TEXTBOX_OUTPUT_CHANNEL_UNBOUND。
使用例:

BoneTextBox.setTargetReady(root, true);

確認ポイント: falseでWAIT/queue、trueへ戻すとFIFO順で配送する。

17.22 `clearOutputBlock(element)`

用途: 接続済み#002 ChannelのBLOCK状態を解除する。
引数: element
戻り値: Object
状態/DOM: BLOCKEDを解除してChannelを再配送可能状態へ戻す。
Error: TEXTBOX_OUTPUT_CHANNEL_UNBOUND。
使用例:

BoneTextBox.clearOutputBlock(root);

確認ポイント: BLOCKEDを解除してChannelを再配送可能状態へ戻す。

17.23 `getOutputState(element)`

用途: 現在のDelivery状態を取得する。
引数: element
戻り値: Object
状態/DOM: 未接続時はstate=unbound,targetReady=null,queueLength=0,historyLength=0を返す。
Error: TEXTBOX_INSTANCE_INVALID。
使用例:

const delivery = BoneTextBox.getOutputState(root);

確認ポイント: 未接続時はstate=unbound,targetReady=null,queueLength=0,historyLength=0を返す。

17.24 `getOutputQueue(element)`

用途: 現在の#002待機Queueをcloneで取得する。
引数: element
戻り値: Array
状態/DOM: 未接続なら空配列。Queue自体を利用側が変更してもRuntime内部へ影響しない。
Error: TEXTBOX_INSTANCE_INVALID。
使用例:

const queued = BoneTextBox.getOutputQueue(root);

確認ポイント: 未接続なら空配列。Queue自体を利用側が変更してもRuntime内部へ影響しない。

17.25 `commit(element, source)`

用途: editingValueをValidation後に確定し、必要ならOUT配送する。
引数: element, source?
戻り値: Commit Result
状態/DOM: disabled/readonlyはnot-editable。Validation不正かつcommitInvalid=falseなら確定しない。成功時はcommittedValue/Boneを更新してcommit EventとDeliveryを実行する。
Error: TEXTBOX_INSTANCE_INVALID / Validation/SecurityはResultへ反映。
使用例:

const result = BoneTextBox.commit(root, "api");

確認ポイント: disabled/readonlyはnot-editable。Validation不正かつcommitInvalid=falseなら確定しない。成功時はcommittedValue/Boneを更新してcommit EventとDeliveryを実行する。

17.26 `reset(element)`

用途: 未確定editingValueをcommittedValueへ戻す。
引数: element
戻り値: string
状態/DOM: input表示も確定値へ戻し、securityErrorをclearしてreset Eventを発火する。
Error: TEXTBOX_INSTANCE_INVALID。
使用例:

BoneTextBox.reset(root);

確認ポイント: input表示も確定値へ戻し、securityErrorをclearしてreset Eventを発火する。

17.27 `validate(element)`

用途: 現在editingValueをRuntime条件で再検証する。
引数: element
戻り値: Validation Object
状態/DOM: Validation表示を再計算するがcommittedValueは変更しない。
Error: TEXTBOX_INSTANCE_INVALID。
使用例:

const validation = BoneTextBox.validate(root);

確認ポイント: Validation表示を再計算するがcommittedValueは変更しない。

17.28 `focus(element)`

用途: 内部inputへfocusする。
引数: element
戻り値: undefined
状態/DOM: focused状態とActive Effectが実ブラウザfocus Event経由で反映される。
Error: TEXTBOX_INSTANCE_INVALID。
使用例:

BoneTextBox.focus(root);

確認ポイント: focused状態とActive Effectが実ブラウザfocus Event経由で反映される。

17.29 `blur(element)`

用途: 内部inputをblurする。
引数: element
戻り値: undefined
状態/DOM: blurCommit=trueなら実blur Event経由でcommitされる。
Error: TEXTBOX_INSTANCE_INVALID。
使用例:

BoneTextBox.blur(root);

確認ポイント: blurCommit=trueなら実blur Event経由でcommitされる。

17.30 `select(element)`

用途: 内部inputの全文字を選択する。
引数: element
戻り値: undefined
状態/DOM: selectionStart=0, selectionEnd=文字数となる。
Error: TEXTBOX_INSTANCE_INVALID。
使用例:

BoneTextBox.select(root);

確認ポイント: selectionStart=0, selectionEnd=文字数となる。

17.31 `setSelectionRange(element, start, end, direction)`

用途: 内部inputの選択範囲を設定する。
引数: element, start, end, direction?
戻り値: undefined
状態/DOM: ブラウザHTMLInputElement.setSelectionRangeへ委譲する。
Error: TEXTBOX_INSTANCE_INVALID。範囲値はブラウザinput契約にも従う。
使用例:

BoneTextBox.setSelectionRange(root, 1, 3, "forward");

確認ポイント: ブラウザHTMLInputElement.setSelectionRangeへ委譲する。

17.32 `getSelection(element)`

用途: 現在の選択開始・終了・方向を取得する。
引数: element
戻り値: Object {start,end,direction}
状態/DOM: 状態を変更しない。
Error: TEXTBOX_INSTANCE_INVALID。
使用例:

const selection = BoneTextBox.getSelection(root);

確認ポイント: 状態を変更しない。

17.33 `setFeedback(element, feedback)`

用途: 利用側からfeedback表示を上書きする。
引数: element, {level,message}
戻り値: Object
状態/DOM: levelはnone/warning/error/success。その他はnoneへ正規化。messageは最大8192文字の安全文字列として処理する。
Error: TEXTBOX_FEEDBACK_INVALID / Security text Error。
使用例:

BoneTextBox.setFeedback(root, { level: "success", message: "保存しました" });

確認ポイント: levelはnone/warning/error/success。その他はnoneへ正規化。messageは最大8192文字の安全文字列として処理する。

17.34 `syncParentStyle(element)`

用途: inheritParent時の親Computed Styleを再取得して反映する。
引数: element
戻り値: Object
状態/DOM: 親幅/高さ/背景/文字色/枠色/角丸/textAlign変更後に再同期し再描画する。
Error: TEXTBOX_INSTANCE_INVALID。
使用例:

BoneTextBox.syncParentStyle(root);

確認ポイント: 親幅/高さ/背景/文字色/枠色/角丸/textAlign変更後に再同期し再描画する。

17.35 `destroy(element)`

用途: instanceを完全破棄する。
引数: element
戻り値: boolean
状態/DOM: Delivery Channelをdisposeし、#022 Effectをdetachし、instance登録とroot DOMを削除する。EXIT残骸を残さない。
Error: TEXTBOX_INSTANCE_INVALID。
使用例:

BoneTextBox.destroy(root);

確認ポイント: Delivery Channelをdisposeし、#022 Effectをdetachし、instance登録とroot DOMを削除する。EXIT残骸を残さない。

18. Error Code

個別ErrorはTOCを過密化しないため見出し化せず、コード・意味・発生経路・修正方法を本文で説明します。

18.1 Runtime Error 全41件

TEXTBOX_UNTRUSTED_RECORD_INVALID

意味: 通常のJavaScriptオブジェクト（{}で作るObject）契約ではないUntrusted recordを拒否。
発生経路: readOwnDataを使うUntrusted入力読取。
修正方法: 配列/null/Date等ではなく通常のJavaScriptオブジェクト（{}で作るObject）を渡す。
不正例: applyJointInput(root, [])
正しい例/対処: 通常のJavaScriptオブジェクト（{}で作るObject） payloadへ直す。
影響: 入力を拒否しcommittedValueを保持。

TEXTBOX_UNTRUSTED_PROPERTY_TRAP

意味: Proxy等の特殊ObjectによりOwn Property Descriptorの安全な読取が失敗。
発生経路: Untrusted recordのproperty読取。
修正方法: Proxy等の特殊Object trapを含まない{source, value, state}のような通常のデータObjectへ変換する。
不正例: Proxy等の特殊ObjectのgetOwnPropertyDescriptorがthrowするobject
正しい例/対処: Proxy等の特殊Objectを外した{source, value, state}のような通常のデータObjectへコピーする。
影響: 安全読取を中止し値を変更しない。

TEXTBOX_UNTRUSTED_PROPERTY_MISSING

意味: 必須Untrusted propertyが存在しない。
発生経路: required=trueでreadOwnDataした契約項目。
修正方法: 必要なdata propertyを明示する。
不正例: Bone INに必須valueがない
正しい例/対処: id/type/value等の必須data propertyを入れる。
影響: 正規化を中止。

TEXTBOX_UNTRUSTED_ACCESSOR_REJECTED

意味: getter/setterを実行せずAccessor propertyを拒否。
発生経路: Untrusted record property読取。
修正方法: getter/setterではなくvalueを持つdata propertyを使う。
不正例: valueをgetterで定義
正しい例/対処: 通常のdata property value:"ABC"へ直す。
影響: getterを実行せず拒否。

TEXTBOX_VALUE_TYPE_REJECTED

意味: TextBox valueがstringではない。objectをString()へ強制変換しない。
発生経路: inspectUntrustedText / setValue / Joint IN等。
修正方法: 文字列を渡す。
不正例: setValue(root,{x:1})
正しい例/対処: setValue(root,"ABC")
影響: objectを文字列化せず拒否し既存値保持。

TEXTBOX_SECURITY_LENGTH_EXCEEDED

意味: 入力長がsecurityMaxLengthを超過。
発生経路: Security Gate。
修正方法: securityMaxLength以下へ短縮する。
不正例: limit=8へ9文字
正しい例/対処: 8文字以下へ短縮または安全な範囲でlimitを見直す。
影響: Security拒否、commitしない。

TEXTBOX_CONTROL_CHARACTER_REJECTED

意味: 許可しないASCII制御文字を含む。
発生経路: Security Gate。
修正方法: U+0000–0008, U+000B, U+000C, U+000E–001F, U+007Fを除去する。
不正例: "A\u0000B"
正しい例/対処: 禁止制御文字を除いた"AB"
影響: Security拒否、既存値保持。

TEXTBOX_UNPAIRED_SURROGATE_REJECTED

意味: 不正なUnicode Unicodeサロゲート pairを検出。
発生経路: Security Gate。
修正方法: 正しいUnicode文字列へ修正する。
不正例: 単独high Unicodeサロゲートを含むstring
正しい例/対処: 正しいUnicode pairの文字列
影響: Security拒否。

TEXTBOX_LENGTH_INVALID

意味: minlength/maxlengthが0以上の整数または未指定ではない。
発生経路: normalizeOptions。
修正方法: 0以上の整数またはnull/未指定へ修正する。
不正例: minlength:1.5
正しい例/対処: minlength:1または未指定
影響: option正規化を拒否。

TEXTBOX_SECURITY_LIMIT_INVALID

意味: securityMaxLengthが1～1048576の整数外。
発生経路: normalizeOptions / inspectUntrustedText limit。
修正方法: 1～1048576の整数にする。
不正例: securityMaxLength:0
正しい例/対処: 1～1048576の整数
影響: option正規化/inspectを拒否。

TEXTBOX_OPTION_TYPE_INVALID

意味: string指定Propertyへ非stringを渡した。
発生経路: normalizeOptions。
修正方法: 対象Propertyをstringで指定する。
不正例: theme:123
正しい例/対処: theme:"neon"
影響: option正規化を拒否。

TEXTBOX_OPTION_ENUM_INVALID

意味: 列挙Propertyが許容値外。
発生経路: normalizeOptions。
修正方法: DOC-0027記載の全許容値から選ぶ。
不正例: position:"upper"
正しい例/対処: 9つの正式positionから選ぶ。
影響: option正規化を拒否。

TEXTBOX_BACKGROUND_COLOR_INVALID

意味: backgroundColorがtheme/transparent/安全なHEXではない。
発生経路: normalizeOptions。
修正方法: theme, transparent, #RGB/#RGBA/#RRGGBB/#RRGGBBAAを使用する。
不正例: backgroundColor:"red"
正しい例/対処: #ff0000 / theme / transparent
影響: option正規化を拒否。

TEXTBOX_ACTIVE_EFFECT_COLOR_INVALID

意味: Active/MouseOver Effect colorがtheme/安全なHEXではない。
発生経路: normalizeOptions。
修正方法: themeまたは対応HEXを使用する。#040は色選択UI責務。
不正例: activeEffectColor:"rgb(1,2,3)"
正しい例/対処: #010203またはtheme
影響: Effect option正規化を拒否。

TEXTBOX_SIZE_INVALID

意味: width/heightがRuntime許容範囲外または数値化不可。
発生経路: normalizeOptions。
修正方法: width 40～4000px、height 24～2000pxにする。
不正例: width:20 / height:10
正しい例/対処: width 40～4000、height 24～2000
影響: create/setOptionsを拒否し既存instanceは保持。

TEXTBOX_OPTIONS_INVALID

意味: options/setOptions patchが通常のJavaScriptオブジェクト（{}で作るObject）ではない。
発生経路: normalizeOptions / setOptions。
修正方法: 通常のJavaScriptオブジェクト（{}で作るObject）で指定する。
不正例: setOptions(root,[])
正しい例/対処: 通常のJavaScriptオブジェクト（{}で作るObject） patchを渡す。
影響: 更新を行わない。

TEXTBOX_MAXLENGTH_SECURITY_RANGE

意味: maxlengthがsecurityMaxLengthを超過。
発生経路: normalizeOptions。
修正方法: maxlength <= securityMaxLengthにする。
不正例: maxlength:200, securityMaxLength:100
正しい例/対処: maxlength<=securityMaxLength
影響: option正規化を拒否。

TEXTBOX_LENGTH_RANGE_INVALID

意味: minlengthがmaxlengthを超過。
発生経路: normalizeOptions。
修正方法: minlength <= maxlengthにする。
不正例: minlength:10,maxlength:5
正しい例/対処: minlength<=maxlength
影響: option正規化を拒否。

TEXTBOX_DEPENDENCY_CORE_MISSING

意味: #001 Bone Core v1.0.0以上（同一major）またはnormalize APIが不足。
発生経路: create / Bone normalize。
修正方法: 互換#001を先に読み込む。
不正例: #001未読込でcreate
正しい例/対処: #001 v1.0.0+互換を先に読込む。
影響: create/Bone normalizeを開始しない。

TEXTBOX_DEPENDENCY_JOINT_MISSING

意味: #002 Bone Joint v1.1.36以上（同一major）のDelivery APIが不足。
発生経路: connectOutput。
修正方法: 互換#002を先に読み込む。
不正例: #002未読込でconnectOutput
正しい例/対処: #002 v1.1.36+互換を先に読込む。
影響: Delivery Channelを作らない。

TEXTBOX_BONE_INPUT_INVALID

意味: Bone INが通常のJavaScriptオブジェクト（{}で作るObject）ではない。
発生経路: create / applyBone。
修正方法: 通常のJavaScriptオブジェクト（{}で作るObject） Boneを渡す。
不正例: create([],options)
正しい例/対処: 通常のJavaScriptオブジェクト（{}で作るObject） Boneを渡す。
影響: create/applyBoneを拒否。

TEXTBOX_BONE_ID_TYPE_INVALID

意味: Bone id/typeがstringではない。
発生経路: create / applyBone。
修正方法: id/typeをstringで指定する。
不正例: {id:1,type:"TEXTBOX",value:"A"}
正しい例/対処: id/typeをstringにする。
影響: Bone正規化を拒否。

TEXTBOX_JOINT_STATE_INVALID

意味: Joint stateがstringまたは通常のJavaScriptオブジェクト（{}で作るObject）ではない。
発生経路: applyJointInput。
修正方法: string statusまたは通常のJavaScriptオブジェクト（{}で作るObject） stateを使う。
不正例: state:[]
正しい例/対処: stringまたは通常のJavaScriptオブジェクト（{}で作るObject）
影響: Joint IN拒否。

TEXTBOX_JOINT_STATE_STATUS_INVALID

意味: Joint state.statusがstringではない。
発生経路: applyJointInput。
修正方法: statusをstringにする。
不正例: state:{status:1}
正しい例/対処: status:"connected"
影響: Joint IN拒否。

TEXTBOX_JOINT_STATE_REASON_INVALID

意味: Joint state.reasonがstringではない。
発生経路: applyJointInput。
修正方法: reasonをstringにする。
不正例: state:{status:"blocked",reason:1}
正しい例/対処: reasonをstring
影響: Joint IN拒否。

TEXTBOX_JOINT_INPUT_INVALID

意味: Joint IN payloadが通常のJavaScriptオブジェクト（{}で作るObject）ではない。
発生経路: applyJointInput。
修正方法: 通常のJavaScriptオブジェクト（{}で作るObject） payloadを渡す。
不正例: applyJointInput(root,"ABC")
正しい例/対処: 通常のJavaScriptオブジェクト（{}で作るObject） payload
影響: IN拒否、既存値保持。

TEXTBOX_JOINT_SOURCE_INVALID

意味: Joint IN sourceがstring/null以外。
発生経路: applyJointInput。
修正方法: sourceをstringまたはnullにする。
不正例: source:{}
正しい例/対処: stringまたはnull
影響: IN拒否。

TEXTBOX_REQUIRED

意味: required=trueで値が空。
発生経路: validate / commit。
修正方法: 値を入力するかrequired=falseにする。
不正例: required=trueで空文字
正しい例/対処: 1文字以上入力またはrequired=false
影響: commitInvalid=falseならcommit拒否。

TEXTBOX_MINLENGTH

意味: 文字数がminlength未満。
発生経路: validate / commit。
修正方法: minlength以上の文字数にする。
不正例: minlength=3で"AB"
正しい例/対処: 3文字以上
影響: Validation invalid。

TEXTBOX_MAXLENGTH

意味: 文字数がmaxlength超過。
発生経路: validate / commit。
修正方法: maxlength以下へ短縮する。
不正例: maxlength=3で"ABCD"
正しい例/対処: 3文字以下
影響: Validation invalid。

TEXTBOX_022_DEPENDENCY_REQUIRED

意味: #022 Hover Border Effect v1.0.8以上（同一major）の正式Effect APIが不足。
発生経路: Active/MouseOver Effect初期化。
修正方法: 互換#022（現行v1.0.10上位互換）を先に読み込む。
不正例: #022なしでEffect!=normal
正しい例/対処: #022 v1.0.8+互換（現行v1.0.10）を読込む。
影響: Effect初期化を拒否。

TEXTBOX_INSTANCE_INVALID

意味: 渡したelementがBoneTextBox管理instanceではない。
発生経路: instanceを要求するPublic API。
修正方法: create()の戻りrootを渡し、destroy後rootを再利用しない。
不正例: 未管理divをgetValue()へ渡す
正しい例/対処: create()戻りrootを渡す。
影響: API処理を拒否。

TEXTBOX_DOM_REQUIRED

意味: document/createElementを持つDOM環境がない。
発生経路: create。
修正方法: ブラウザDOM環境で生成する。
不正例: documentのない環境でcreate
正しい例/対処: ブラウザDOMでcreate
影響: DOM生成を行わない。

TEXTBOX_IN_REJECTED

意味: Joint IN拒否時のfallback code。
発生経路: applyJointInput catch path。
修正方法: returned result.code/messageを確認し元のSecurity/Joint契約違反を修正する。
不正例: Joint IN内部契約違反
正しい例/対処: 返却code/messageの元原因を修正
影響: INを拒否し値保持。

TEXTBOX_OUTPUT_OPTIONS_INVALID

意味: connectOutput optionsが通常のJavaScriptオブジェクト（{}で作るObject）ではない。
発生経路: connectOutput。
修正方法: 通常のJavaScriptオブジェクト（{}で作るObject）を渡す。
不正例: connectOutput(root,[])
正しい例/対処: 通常のJavaScriptオブジェクト（{}で作るObject） options
影響: Channel接続しない。

TEXTBOX_OUTPUT_GUARD_INVALID

意味: guardがfunction/null/未指定ではない。
発生経路: connectOutput。
修正方法: functionまたはnullにする。
不正例: guard:"yes"
正しい例/対処: function/null/未指定
影響: Channel接続設定を拒否。

TEXTBOX_OUTPUT_DELIVER_INVALID

意味: deliverがfunction/null/未指定ではない。
発生経路: connectOutput。
修正方法: functionまたはnullにする。
不正例: deliver:true
正しい例/対処: function/null/未指定
影響: Channel接続設定を拒否。

TEXTBOX_OUTPUT_STATE_CALLBACK_INVALID

意味: onStateChangeがfunction/null/未指定ではない。
発生経路: connectOutput。
修正方法: functionまたはnullにする。
不正例: onStateChange:{}
正しい例/対処: function/null/未指定
影響: Channel接続設定を拒否。

TEXTBOX_OUTPUT_CHANNEL_UNBOUND

意味: OUT Channel未接続のままReady/BLOCK操作を行った。
発生経路: setTargetReady / clearOutputBlock。
修正方法: 先にconnectOutput()する。
不正例: connectOutput前にsetTargetReady
正しい例/対処: 先にconnectOutput()
影響: 状態変更を拒否。

TEXTBOX_EXISTING_VALUE_SECURITY_LIMIT

意味: 新securityMaxLengthが現在committedValue長より小さい。
発生経路: setOptions。
修正方法: 現在値以上のsecurityMaxLengthにするか、先に値を安全に短縮する。
不正例: 現在100文字でsecurityMaxLength=50へ変更
正しい例/対処: 先に値を50文字以下にするかlimit>=現在長
影響: 既存値を切断せずsetOptionsを拒否。

TEXTBOX_FEEDBACK_INVALID

意味: feedbackが通常のJavaScriptオブジェクト（{}で作るObject）ではない。
発生経路: setFeedback。
修正方法: {level,message} 通常のJavaScriptオブジェクト（{}で作るObject）を渡す。

18.2 HTML Functional Class Integration Error

不正例: setFeedback(root,"error")
正しい例/対処: {level:"error",message:"..."} 通常のJavaScriptオブジェクト（{}で作るObject）
影響: feedback更新を拒否。

TEXTBOX_FUNCTIONAL_CLASS_RUNTIME_MISSING

意味: bf-textbox mount前にBoneTextBox Runtimeがない/不適合。
修正方法: bone-textbox.jsをFunctional Classより先に読込む。

TEXTBOX_FUNCTIONAL_CLASS_ANCHOR_INVALID

意味: mount対象が.bf-textboxを持つElementではない。
修正方法: <input class="bf-textbox">等のElementを渡す。

TEXTBOX_FUNCTIONAL_CLASS_BOOLEAN_INVALID

意味: data-* Boolean値がtrue/false系tokenではない。
修正方法: true/false/1/0/yes/no/on/offを使用する。

19. Lifecycle / destroy

create → input/edit → validate → commit → OUT Delivery → destroyが基本Lifecycleです。destroy()はDelivery Channelをdisposeし、#022 Active/Mouse Over attachをdetachしてRuntime DOMを削除します。Functional Classのunmount()は元inputのhidden状態を復元します。

20. Troubleshooting

入力してもgetValue()が変わらない: editingValueのままです。Enter/blurまたはcommit()で確定します。
commitできない: disabled/readonly/composition中/Validation Errorを確認します。
OUTが届かない: getOutputState()でunbound/waiting/blockedを確認します。
色が反映されない: theme/transparent/HEX契約と#040 RETURN値を確認します。
Activeだけ見えない: inputへfocusし、#022依存とactiveBorderEffectを確認します。
Mouse Overだけ見えない: controlへmouseenterし、mouseoverBorderEffectを確認します。
親依存が更新されない: inheritParent=trueとsyncParentStyle()を確認します。

21. 責務境界

#001 Core: Bone normalize。
#002 Joint: 接続、Delivery Channel、WAIT/FIFO/BLOCKED。
#017 Text: 表示責務境界のみ。#027 Runtime依存ではありません。
#022 Hover Border Effect: Active/Mouse Over枠Effect。
#040 ColorPicker: 色選択UI。
#027 TextBox: 1行文字入力、editing/commit、Validation、Security IN、確定文字列OUT接続。

#027 TextBox

bf-textbox + BoneFlow.data

正式ガイド DOC-0027

DOC-0027 — TextBox 操作・HTML Functional Class

0. 文書情報

1. TextBoxの役割

1.1 最初に覚える用語

1.2 まず基本操作を理解する

1.3 disabled と readonly の違い

1.4 Validation と Security の違い

2. HTML Functional Class bf-textbox

2.1 最小利用

2.2 設定付き利用

2.3 設定 → 実表示サンプル

Theme 全4値

Background

Appearance

Validation

サイズ

入力文字位置 全4値

disabled / readonly / selectOnFocus / commit policy

Active Effect

Mouse Over Effect

2.4 HTML宣言Property 全33件「設定 → 表示/動作」早見

3. Default Property 全33件 — 個別Reference

3.1 placeholder

3.2 disabled

3.3 readonly

3.4 required

3.5 minlength

3.6 maxlength

3.7 name

3.8 autocomplete

3.9 spellcheck

3.10 inputMode

3.11 enterCommit

3.12 blurCommit

3.13 commitInvalid

3.14 selectOnFocus

3.15 ariaLabel

3.16 className

3.17 theme

3.18 backgroundColor

3.19 appearance

3.20 inheritParent

3.21 width

3.22 height

3.23 position

3.24 inputAlign

3.25 activeBorderEffect

3.26 activeEffectColor

3.27 activeEffectDirection

3.28 activeEffectSpeed

3.29 mouseoverBorderEffect

3.30 mouseoverEffectColor

3.31 mouseoverEffectDirection

3.32 mouseoverEffectSpeed

3.33 securityMaxLength