Bone Flow #017 Text ガイド

このガイドについて

• DOC ID: DOC-0017
• UI ID: UI-017
• Component: #017 Text
• Runtime Version: 1.0.34
• DOC Version: 1.0.2

このDOCは、#017 Textを初めて使う人が「何を設定すると、実際に何が変わるのか」まで確認できる操作ガイド兼正式仕様です。画面Help、HTML Functional Classガイド、印刷説明書、PDF、Help検索から同じ DOC-0017 を再利用します。

このガイドでは、各Propertyを 説明 → 正式仕様 → 全許容値 → 使用サンプル → 実行結果 の順で説明します。コードブロックには「コピー」ボタンが表示され、そのまま利用できます。

実行時初期値（Runtime Default）と、#017テスト画面の設定欄（Property Editor）の初期値は同じとは限りません。異なる場合は両方を明記します。

このガイドで使う用語

専門語だけを並べず、次の意味で表記します。

• Runtime（実行本体）: ブラウザ上で実際にTextを生成・更新する BoneText 本体。
• Runtime Default（実行時初期値）: 何も指定しなかったときに実行本体が使う値。
• Property（設定項目）: Textの表示や入力方法を変える設定。
• Property Editor（画面の設定欄）: #017テスト画面の左側から変更できる設定欄。
• Public API（JavaScript高度操作）: HTMLだけでは指定できない設定をJavaScriptから直接操作する正式機能。
• HTML Functional Class: class="bf-text" を付けてHTMLからTextを使い始める入口。

英語名やError Codeは正式仕様名なので残しますが、必ず日本語で「何が変わるのか」を併記します。

最初に

#017 Textの最小利用は、HTMLに bf-text を付けるだけです。

<span class="bf-text">ABC</span>

使用結果: ABC がTextとして有効化されて表示されます。HTML内の文字列は初期値として扱われ、表示はTextの実行本体による安全な文字表示を通ります。

入力UIとして使う場合は input に同じClassを付けます。

<input class="bf-text" type="text" value="ABC" placeholder="入力してください">

使用結果: Text入力欄が生成され、初期値 ABC とPlaceholderが反映されます。

高度な設定項目を使う場合、HTML標準属性で表現できるものはHTMLから、直接表現できないものは BoneText のJavaScript高度操作（Public API）から設定します。独自の追加属性は作りません。

Textとは

#017 Textは、TYPE TEXT の値を安全に表示し、Text / Number / Passwordの入力欄を提供する基礎UI部品です。

主な責務は次のとおりです。

• 文字列、数値、真偽値、BigInt、Date、TYPE TEXT Boneの表示
• Text / Number / Password入力
• 表示用Textの9方向Position
• 入力欄内の文字揃え
• Placeholder / Required / Read Only
• 入力中Font
• #040 ColorPickerで選択し、#017へ返された（RETURN）文字色 / 背景色
• whitespace / overflow / maxLinesによる長文制御
• prefix / suffix / emptyText / formatter
• Joint接続時にTextをIN / OUTの接続口（Endpoint）として利用
• Smoke / Validation / Completion
• Public APIによる高度操作

表示値は textContent へ設定されます。値として渡したHTML文字列を実行するComponentではありません。

HTML Functional Class

正式Class

一般利用向けHTML Functional Classは bf-text 1つだけです。Public API 17件をHTML Classへ1対1変換しません。

<span class="bf-text">ABC</span>

対応HTML要素

表示用は次の8要素です。

• span
• p
• div
• small
• strong
• em
• code
• pre

入力用は input です。input の type は text / number / password の3種類です。

初期値の取得元

表示用8要素は要素の textContent を初期値として使用します。

<p class="bf-text">処理を開始します。</p>

input は value を初期値として使用します。

<input class="bf-text" type="number" value="123">

HTMLから直接指定できるもの

HTML標準属性や標準styleで意味が確定している設定だけを読み取ります。

• 要素名 → tag（表示用）
• class → className
• id → id
• role → role
• aria-label → ariaLabel
• title → title
• lang → lang
• dir → direction
• hidden → hidden
• type → valueType（inputのみ）
• placeholder → placeholder（inputのみ）
• readonly → readOnly（inputのみ）
• required → required（inputのみ）
• style="text-align:..." → inputAlign（inputのみ）
• style="white-space:..." → whitespace（表示用のみ）
• style="font-family:..." → inputFont.family（inputのみ）
• style="font-size:...px" → inputFont.size（inputのみ）
• style="font-weight:..." → inputFont.weight（inputのみ）
• style="font-style:..." → inputFont.style（inputのみ）
• style="color:#RRGGBB" → inputFont.color（inputのみ）
• style="background-color:#RRGGBB" → inputFont.backgroundColor（inputのみ）

次はHTMLから直接指定しません: position、overflow、selectable、maxLines、emptyText、prefix、suffix、formatter、Gradient形式のFont Color。これらはPublic APIを使用します。

設定付き使用サンプル

<input class="bf-text"
       type="text"
       value="ABC"
       placeholder="入力してください"
       required
       style="text-align:center; font-size:18px; font-weight:600;">

使用結果: Text入力、初期値 ABC、Placeholder、Required ON、中央揃え、18px、Weight 600になります。

使用サンプル

ここは「仕様値の一覧」ではなく、実際の利用場面をそのままコピーするためのサンプルです。

1. 通常の説明文

<p class="bf-text">処理が完了しました。</p>

使用結果: 通常のText表示として 処理が完了しました。 を表示します。

2. Number入力を右寄せで使う

<input class="bf-text" type="number" value="1200" placeholder="数量">

使用結果: type=number のため、inputAlign=auto では右寄せになります。

3. 必須入力を中央揃えで使う

<input class="bf-text"
       type="text"
       value=""
       placeholder="コードを入力"
       required
       style="text-align:center;">

使用結果: RequiredがONになり、文字は中央揃えです。#017テスト画面では空欄時に必須入力メッセージを表示します。

4. 改行と連続空白を保持する

<pre class="bf-text" style="white-space:pre-wrap;">1行目
  2行目</pre>

使用結果: 改行と先頭の連続空白を保持し、必要な場合は親領域で折り返します。

5. HTMLだけでは指定できない設定を使う

position や overflow はHTML標準属性へ無理に割り当てません。JavaScript高度操作（Public API）で指定します。

<div id="text-stage" class="bone-text-position-stage"></div>
<script>
const stage = document.getElementById("text-stage");
BoneText.render(stage, "左上に表示", {
  position: "top-left",
  overflow: "wrap"
});
</script>

使用結果: #017の正式Position Stage内ではTextが左上へ配置されます。position は親レイアウトが配置Classを解釈して初めて見た目へ反映されます。

6. 長い文字を2行で省略する

<div id="summary"></div>
<script>
BoneText.render(document.getElementById("summary"),
  "これは長い説明文です。表示領域を超えた場合は2行で省略します。", {
    overflow: "ellipsis",
    maxLines: 2
  }
);
</script>

使用結果: overflow=ellipsis と maxLines=2 の組合せで、2行まで表示して残りを省略します。親要素に実際の幅制約が必要です。

実行時初期値 / 画面の設定欄（Runtime Default / Property Editor）

実行時初期値（Runtime Default）全件

BoneText.defaults の正式Defaultです。

画面の設定欄（Property Editor）初期値

現在の bone-text.html の画面設定欄（Property Editor）で直接編集できる項目は、実行本体の設定全件ではありません。

• valueType: text
• サンプル値（Sample Value）: サンプルテキスト
• placeholder: 入力してください（Runtime Defaultは空文字）
• required: OFF
• readOnly: OFF
• inputAlign: auto
• inputFont.family: system-ui, sans-serif
• inputFont.size: 16、Editor入力範囲 8〜72
• inputFont.weight: 選択肢 400 / 600 / 700、初期 400
• inputFont.style: normal / italic / oblique、初期 normal
• inputFont.color: #111111
• inputFont.backgroundColor: #ffffff

position、direction、whitespace、overflow、maxLines、prefix、suffix、formatterなどは実行本体の設定項目ですが、現在の画面設定欄には直接入力欄がありません。JavaScript高度操作（Public API）またはHTML標準属性で設定します。

tag 全8値

tag は 表示用TextをどのHTML要素として生成するか を決めます。入力Editorは常に input を生成するため、このPropertyは表示用です。

Runtime Defaultは span。生成後の表示要素でtagを変更すると BONE_TEXT_TAG_IMMUTABLE です。

• span: 行内Text。短いラベルや文章内の一部に使用。
• p: 段落として使用。
• div: ブロック領域として使用。
• small: 補足・小さな注記の意味を持つ要素。
• strong: 強い重要性を持つText。
• em: 強調を表すText。
• code: コード断片を表すText。
• pre: 改行・空白を意識した整形済みText。

HTMLでは要素名そのものが tag になります。

<strong class="bf-text">重要</strong>

Public API使用例:

BoneText.render(document.getElementById("host"), "注意事項", { tag: "p" });

不正値: BONE_TEXT_TAG_INVALID。

valueType 全3値

valueType は EditorをText / Number / Passwordのどの入力として生成するか を決めます。表示用Textでは data-value-type の状態として保持されますが、入力形式を変えるのはEditorです。

Runtime Defaultは text。Property Editor初期値も text です。

• text: 通常の文字入力。inputAlign=auto の解決結果は左寄せ。
• number: 数値入力。inputAlign=auto の解決結果は右寄せ。
• password: パスワード入力。入力値はpassword表示。inputAlign=auto は左寄せ。

<input class="bf-text" type="password" value="secret" placeholder="Password">

不正値: BONE_TEXT_VALUE_TYPE_INVALID。HTML Functional Classで input type="email" などを使用した場合は BONE_TEXT_HTML_CLASS_INPUT_TYPE_INVALID。

表示位置（position）全9値

position は 表示用Textを親レイアウトのどこへ配置するかを表す9方向の配置状態 です。単なる文字揃えではありません。文字揃えは inputAlign の責務です。

Runtime Defaultは center。現在のProperty EditorにはPosition入力欄はありません。HTML標準属性からも直接指定しません。

#017正式CSSでは、親が .bone-text-position-stage の場合に bone-text--position-* ClassをGridの align-self / justify-self へ反映します。親がこの配置契約を持たない場合、position 値を設定しても親レイアウト側が見た目を決めます。

• top-left: 親領域の左上。
• top-center: 親領域の上中央。
• top-right: 親領域の右上。
• middle-left: 親領域の左中央。
• center: 親領域の中央。Runtime Default。
• middle-right: 親領域の右中央。
• bottom-left: 親領域の左下。
• bottom-center: 親領域の下中央。
• bottom-right: 親領域の右下。

使用サンプル:

<div id="position-demo" class="bone-text-position-stage"></div>
<script>
BoneText.render(document.getElementById("position-demo"), "右下", {
  position: "bottom-right"
});
</script>

使用結果: 正式Position Stage内の右下へTextを配置します。

不正値: BONE_TEXT_POSITION_INVALID。

入力文字の揃え（inputAlign）全4値

inputAlign は 入力欄の中で文字を左右どこへ揃えるか を決めます。position と違い、Editor内部の文字揃えです。

Runtime DefaultとProperty Editor初期値は auto です。

• auto: number は右寄せ、text / password は左寄せ。
• left: 種類に関係なく左寄せ。
• center: 種類に関係なく中央揃え。
• right: 種類に関係なく右寄せ。

HTMLでは style="text-align:..." の left / center / right を直接利用できます。style指定がなければ auto です。

<input class="bf-text" type="number" value="123" style="text-align:center;">

使用結果: Number入力ですが明示指定のため中央揃えになります。

不正値: BONE_TEXT_INPUT_ALIGN_INVALID。

文字方向（direction）全3値

direction は、文章をどちら側から書き始める言語として扱うかを決めます。文字を左寄せ・右寄せする設定ではありません。文字の揃えは inputAlign、要素そのものの配置は position が担当します。

• 実行時初期値（Runtime Default）: auto
• 画面の設定欄: 現在は直接変更する項目なし
• HTMLからの指定: 標準 dir 属性を使用
• 不正値: BONE_TEXT_DIRECTION_INVALID

3つの値の意味

• ltr: 左から右へ読む言語用。文章の開始側を左として扱います。英語などで使用します。ltr は “Left To Right” の略です。
• rtl: 右から左へ読む言語用。文章の開始側を右として扱います。アラビア語やヘブライ語などで使用します。rtl は “Right To Left” の略です。
• auto: 内容を見てブラウザに判断させる設定です。言語が固定できないTextで使います。これが実行時初期値です。

使用サンプル

右から始まる文章領域として表示する確認例です。読めない外国語をサンプル本文には使いません。

<p class="bf-text" dir="rtl">ABC 123</p>

使用結果: ABC 123 という文字自体は同じですが、文章の開始側を右側として扱う領域になります。これは「右揃え」と同じ意味ではありません。

実際に右から左へ読む言語を表示する場合も、同じ dir="rtl" を使用します。

関連設定

• inputAlign: 入力欄の中で左・中央・右のどこへ揃えるか。
• position: Text要素そのものを親領域のどこへ置くか。
• direction: 言語としての文字の進む基本方向。

Public APIの createEditor() は現行v1.0.34で direction をEditorへ直接適用しません。bf-text を付けたHTMLの input では、元の標準 dir 属性を生成後のinputへコピーします。

空白・改行の扱い（whitespace）全6値

whitespace は、連続した空白・改行・自動折返しをどう扱うかを決めます。同じ文字列でも設定によって見え方が大きく変わります。

• 実行時初期値: normal
• HTMLからの指定: 表示用要素で標準 style="white-space:..." を使用
• 入力用 input: このPropertyを読み取りません
• 不正値: BONE_TEXT_WHITESPACE_INVALID

比較する元Textは「ABC と DEF の間に空白3個」「その後に改行して GHI」です。

6つの値の意味

• normal: 普通の文章向け。連続空白は1個相当にまとめ、改行も通常の空白として扱い、親幅に合わせて自動折返しします。
• nowrap: 1行のまま表示したい場合。連続空白はまとめますが、自動折返しをしません。幅が足りない場合は親領域からはみ出す可能性があります。
• pre: 入力された空白と改行をそのまま保ちたい場合。連続空白と改行を保持し、自動折返しは基本的に行いません。
• pre-wrap: 空白と改行を保ちつつ、幅が足りなければ折り返したい場合。ログや整形済み文章を狭い領域へ表示するときに使えます。
• pre-line: 改行だけ残し、余分な連続空白はまとめたい場合。人が入力した段落区切りは残したいが、スペース数までは保持しない用途です。
• break-spaces: 空白も改行もできるだけそのまま保持し、空白部分でも折返し可能にしたい場合。スペース位置そのものに意味がある表示向けです。

使用サンプル

<pre class="bf-text" style="white-space:pre-wrap;">ABC   DEF
GHI</pre>

使用結果: ABC と DEF の間の空白3個と改行を保持します。親幅が狭い場合は必要な位置で折り返します。

使い分けの目安

• 普通の文章: normal
• 1行固定: nowrap
• 整形済みTextを完全保持: pre
• 整形を保持しつつ折返し: pre-wrap
• 改行だけ保持: pre-line
• 空白位置まで強く保持しつつ折返し: break-spaces

overflow=ellipsis と組み合わせる場合、#017正式CSSが省略表示を成立させるため white-space を上書きすることがあります。1行省略では nowrap、maxLines>1 の複数行省略では通常の折返し側が優先されます。

はみ出し時の表示（overflow）全3値 / 最大行数（maxLines）

overflow は、Textが親領域に収まらないとき、全文を折り返す・省略記号を出す・途中で切るのどれにするかを決めます。見た目の効果には親要素の幅などの制限が必要です。

• 実行時初期値: wrap
• 画面の設定欄: 現在は直接変更する項目なし
• HTML標準属性からの直接指定: なし
• 不正値: BONE_TEXT_OVERFLOW_INVALID

3つの値の意味

• wrap: 全文を読ませたい場合。#017固有の切捨て処理をせず、通常の折返しに任せます。
• ellipsis: 領域を超えたTextを … で省略したい場合。maxLines=0 または 1 なら1行省略、maxLines=2 以上なら指定行数まで表示して残りを省略します。
• clip: 領域外を単純に切りたい場合。… は付けません。

maxLines は「何行まで表示するか」を指定する0以上の整数です。実行時初期値は 0。主に overflow="ellipsis" と組み合わせて使います。

使用サンプル: 2行まで表示して省略

BoneText.render(document.getElementById("host"),
  "長いタイトルを2行まで表示し、それ以降を省略します。", {
    overflow: "ellipsis",
    maxLines: 2
  }
);

使用結果: 親要素に幅制約がある場合、最大2行まで表示し、その先を省略表示します。

使用サンプル: 省略記号を付けずに切る

BoneText.render(document.getElementById("host"),
  "領域からはみ出す長いText", {
    overflow: "clip"
  }
);

使用結果: 親領域を超えた部分を隠し、… は表示しません。

不正な maxLines は BONE_TEXT_MAX_LINES_INVALID です。

文字列・Boolean Property

ここでは列挙値ではないPropertyの意味をまとめます。どのPropertyも「名前だけ」でなく、表示にどう影響するかを確認してください。

className / id / role / ariaLabel / title / lang

• className: 表示要素へ追加するClass文字列。Default空文字。Displayでは bone-text ... に追加される。Public API createEditor() では適用されないが、HTML bf-text inputは元HTMLのClassを生成後inputへコピーする。
• id: 表示要素のid。Default空文字。Public API createEditor() では直接適用されない。HTML bf-text inputは元idをコピーする。
• role: 表示要素のARIA role。Default空文字。Public API createEditor() では直接適用されない。
• ariaLabel: aria-label。Default空文字。Display / Editorの両方へ適用。
• title: 表示要素の標準title。Default空文字。Public API createEditor() では直接適用されない。
• lang: 表示要素の言語。Default空文字。Public API createEditor() では直接適用されない。

文字列型Propertyへ文字列以外を渡すと BONE_TEXT_OPTION_TYPE_INVALID です。

selectable

Default true。表示用Textで false にすると bone-text--not-selectable が付き、正式CSSの user-select:none が適用されます。EditorではこのPropertyによる選択禁止は適用しません。

BoneText.render(document.getElementById("host"), "選択不可", { selectable: false });

hidden

Default false。表示用Textでは element.hidden へ反映します。Public API createEditor() は現行v1.0.34で hidden を直接適用しません。HTML bf-text inputでは元要素の hidden を生成後inputへコピーします。

emptyText / prefix / suffix / formatter

これらは表示Textの最終文字列を作るPropertyです。Editorの入力値生成では使用しません。

• emptyText: 元値が null / undefined の場合に使用する代替Text。Default空文字。
• prefix: 最終Textの先頭へ付ける文字列。Default空文字。
• suffix: 最終Textの末尾へ付ける文字列。Default空文字。
• formatter: 正規化後Textを変換するFunction。Default null。

処理順は 値正規化 → formatter → prefix / suffix です。

BoneText.render(document.getElementById("price"), 1200, {
  prefix: "¥",
  suffix: " 税込",
  formatter: text => Number(text).toLocaleString("ja-JP")
});

使用結果: ¥1,200 税込。

formatter がFunction / null以外の場合は BONE_TEXT_FORMATTER_INVALID。

inputFont / #040 ColorPicker

inputFont は 入力・編集時のinput表示だけ を担当します。通常表示Textの業務装飾は親UI / Perspectiveの責務です。

Runtime Default:

family          = system-ui, sans-serif
size            = 16
weight          = 400
style           = normal
color           = #111111
backgroundColor = #ffffff

フォント種類（family）

family は、入力欄で使う文字の書体を指定します。実行本体は空でないフォント指定文字列を受け付けます。

画面の設定欄で選べる4件:

• system-ui, sans-serif: OS標準の読みやすい画面用フォントを優先します。
• Meiryo, sans-serif: Windowsの日本語表示で一般的なメイリオを優先します。
• 'Noto Sans JP', sans-serif: Noto Sans JPが利用可能ならそれを使う日本語向け指定です。環境にフォントが無い場合はsans-serifへ代替されます。
• Consolas, monospace: 英数字の幅が揃う等幅フォントです。コードや固定幅表示に向きます。

実行本体はこの4件だけに限定されません。空文字などは BONE_TEXT_FONT_FAMILY_INVALID です。

使用サンプル:

<input class="bf-text" type="text" value="ABC123"
       style="font-family:Consolas, monospace;">

使用結果: 利用環境にConsolasがあれば等幅フォントで表示し、無ければ monospace 系へ代替されます。

文字サイズ（size）

size は、入力欄の文字サイズです。実行本体では0より大きい有限数を受け付け、px単位で適用します。

• 実行時初期値: 16
• 画面の設定欄: 8〜72
• 画面の初期値: 16
• 単位: px
• 不正値: BONE_TEXT_FONT_SIZE_INVALID

実行本体の許容範囲と、画面の設定欄で入力できる範囲は同じではありません。

<input class="bf-text" type="text" value="18pxの文字"
       style="font-size:18px;">

使用結果: 入力文字を18pxで表示します。

文字の太さ（weight）全13値

weight は、入力文字をどのくらい細く・太く表示するかを指定します。

• 実行時初期値: 400
• 画面の設定欄で選べる値: 400 / 600 / 700
• 実行本体から設定できる値: 下記13件すべて
• 不正値: BONE_TEXT_FONT_WEIGHT_INVALID

13個の値の意味

• normal: 標準の太さ。CSS上は通常 400 相当として扱われます。
• bold: 太字。CSS上は通常 700 相当として扱われます。
• bolder: 親要素より1段階太くする相対指定。固定の数値ではありません。
• lighter: 親要素より1段階細くする相対指定。固定の数値ではありません。
• 100: 最も細い側。Thin相当。
• 200: かなり細い。Extra Light相当。
• 300: 細め。Light相当。
• 400: 標準。Normal相当。#017の実行時初期値です。
• 500: 標準より少し太い。Medium相当。
• 600: やや太い。Semi Bold相当。画面の設定欄で選択できます。
• 700: 太字。Bold相当。画面の設定欄で選択できます。
• 800: かなり太い。Extra Bold相当。
• 900: 最も太い側。Black / Heavy相当。

実際に見える太さは使用フォントが持つWeightに依存します。指定した太さがフォントに無い場合、ブラウザが利用可能な近い太さを使うため、例えば 500 と 600 の見た目が同じになる場合があります。

使用サンプル: 600で少し強調

<input class="bf-text" type="text" value="確認してください"
       style="font-weight:600;">

使用結果: 標準の 400 より太い文字として表示します。

使用サンプル: 親より太くする

<div style="font-weight:400;">
  <input class="bf-text" type="text" value="親より太く表示"
         style="font-weight:bolder;">
</div>

使用結果: bolder は固定値ではなく、親の太さを基準に1段階太い側へ解決されます。

文字の傾き（style）全3値

style は、入力文字を通常表示・イタリック・斜体のどれにするかを指定します。

• 実行時初期値: normal

• 画面の設定欄初期値: normal

• 不正値: BONE_TEXT_FONT_STYLE_INVALID

• normal: 通常の立った文字。傾けません。

• italic: フォントが持つイタリック書体を優先して表示します。

• oblique: 通常文字を斜めに傾ける指定です。利用フォントやブラウザによって italic と近い見た目になる場合があります。

<input class="bf-text" type="text" value="斜体サンプル"
       style="font-style:italic;">

使用結果: イタリック書体が利用できれば、その書体で表示します。

文字色 / 背景色（color / backgroundColor）

color は入力文字そのものの色、backgroundColor は入力欄の背景色です。#017専用のColorPickerは作らず、正式な #040 ColorPickerを使用します。

画面操作では、#017の色設定ボタンから #040 ColorPickerを開き、選んだ値を #017へ戻して反映します。

設定できる形式:

• #RRGGBB: 例 #0066CC。通常の単色。
• transparent: 透明。
• GRADIENT_V1: #040正式仕様のグラデーション値。

単色の使用サンプル

<input class="bf-text" type="text" value="青い文字"
       style="color:#0066CC; background-color:#FFFFFF;">

使用結果: 文字が青、背景が白になります。

グラデーションの仕様

• kind: gradient 固定。
• type: linear 固定。直線方向のグラデーション。
• angle: 0以上360未満。グラデーションの角度。
• stops: 色の停止点を2件指定。
• 各 position: 0〜100。開始から何%の位置か。
• 各 color: #RRGGBB。
• 1件目の position は2件目より小さくする。

BoneText.renderEditor(document.getElementById("host"), "Gradient", {
  inputFont: {
    color: {
      kind: "gradient",
      type: "linear",
      angle: 90,
      stops: [
        { position: 0, color: "#00AEEF" },
        { position: 100, color: "#8A2BE2" }
      ]
    },
    backgroundColor: "#FFFFFF"
  }
});

使用結果: 入力文字を左から右へ色が変化するグラデーションとして表示します。文字グラデーションでは、文字形の内側だけに背景グラデーションを見せる方式をRuntimeが使用します。

不正値: BONE_TEXT_FONT_COLOR_INVALID / BONE_TEXT_FONT_GRADIENT_INVALID。

操作方法 / キーボード

画面の設定欄（Property Editor）では、左側の設定を変更すると右側の実表示確認（Preview）へすぐ反映します。

• 種類: Text / Number / Password
• 値: 実表示確認へ入れるサンプル値（Sample Value）
• Placeholder
• Required ON / OFF
• Read Only ON / OFF
• inputAlign
• inputFont
• 文字色 / 背景色: #040 ColorPickerを開き、選択値を#017へ戻して反映（RETURN）

ガイド操作:

• 操作ガイド DOC-0017 でこのModalを開く。
• 左Navigationで章へ移動。
• JP / ENでDOC言語を切替。
• コードブロックの「コピー」で使用サンプルをClipboardへコピー。
• 上部の×、下部の「閉じる」、暗くなった背景部分（Overlay）のクリック、Escape で閉じる。

このガイドはTabキーによるブラウザ標準フォーカス移動を利用します。独自のArrow Key操作は定義していません。

Joint

Jointの判定・接続線・状態描画は #002 Bone Jointの責務です。#017は独自の代替線を持ちません。

テスト画面では次を確認します。

• IN正常接続
• OUT正常接続
• IN Target Field不存在
• OUT Target Field不存在
• IN型不一致
• OUT型不一致

表示色:

• 青: IN
• 緑: OUT
• オレンジ: 型不一致
• 赤: 接続エラー / 不存在終端

使用サンプルの考え方: Textを接続口（Endpoint）として接続定義へ渡し、接続できるかの判定と線の描画は BoneJoint の正式APIへ任せます。#017側で見た目だけの線を描いて正常に見せる実装は行いません。

Smoke / Validation

テスト画面の操作:

• Smoke Test 実行
• Validation 実行
• 全テスト実行
• 結果クリア
• JSON Report保存
• Markdown Report保存

ページを開いただけでは実行済みになりません。SmokeとValidationの結果は実行ボタンを押した回の結果です。

最低限、実行本体/API、設定項目、#040 ColorPickerの呼出元（Caller）と戻り値（RETURN）、Joint、異常値、Completion条件を確認します。

Completion

保存キー:

boneflow.017.text.completion

完了条件:

• Smoke Test実行済み
• Validation実行済み
• allPass === true
• smokePassed === true
• validationPassed === true

条件未達で complete() を呼ぶと BONE_TEXT_COMPLETION_VALIDATION_REQUIRED。

完了すると completionFlag=true / status=Release Ready / validationStatus=ALL PASS を保存します。reopen() でDevelopmentへ戻します。

ユーザーlocalhost確認前のパッケージ作成時点では、正式Completed / Specification Frozenと断定しません。

JavaScript高度操作（Public API）

Public APIは、HTMLだけでは足りない細かな制御をJavaScriptから行う正式な高度操作です。一般利用入口の bf-text とは別物で、17件をHTML Classへ変換しません。

1. BoneText.normalizeValue(value, emptyText) — 値をTextへ正規化。
2. BoneText.normalizeOptions(options) — optionsをDefaultとValidationへ通す。
3. BoneText.create(value, options) — 表示要素を生成。
4. BoneText.createEditor(value, options) — input Editorを生成。
5. BoneText.render(target, value, options) — targetへ表示要素をappend。
6. BoneText.renderEditor(target, value, options) — targetへEditorをappend。
7. BoneText.update(element, value, options) — 既存Instanceを更新。Editorはreplacementを返す。
8. BoneText.setText(element, value) — 現在Text / input valueを設定。
9. BoneText.getText(element) — 表示Textまたはinput valueを取得。
10. BoneText.getValue(element) — Instanceが保持する元valueを取得。
11. BoneText.getOptions(element) — 正規化済optionsを取得。
12. BoneText.setOptions(element, options) — 現在valueを維持してoptions更新。
13. BoneText.destroy(element) — Instanceを解除しDOMから削除。
14. BoneText.isInstance(element) — BoneText管理Instanceか確認。
15. BoneText.getCompletionState() — Completion状態取得。
16. BoneText.complete(validation) — ALL PASS Validationを受けて完了化。
17. BoneText.reopen() — Completionを解除。

基本使用サンプル:

const host = document.getElementById("host");
const text = BoneText.render(host, "Hello", {
  tag: "strong",
  prefix: "[",
  suffix: "]"
});
console.log(BoneText.getText(text));

使用結果: [Hello] を strong 要素として描画し、getText() でも [Hello] を取得します。

発生イベント（Events）

bone-text-change

表示Instanceを update() した後に発行します。detailは value と最終 text。

bone-text-input

Editorでinputイベントが発生したときに発行します。detailは現在の value。

bone-text-html-class-mounted

bf-text の有効化（mount）成功後に、生成された要素から発行します。

bone-text-html-class-error

HTML Functional Classの有効化（mount）でエラーになったときに発行されます。detailにComponent ID、Class名、Error Code、messageを含みます。

エラー / 困ったとき（Troubleshooting）

主なError Code:

• BONE_TEXT_VALUE_UNSUPPORTED: 表示可能な値型ではない。
• BONE_TEXT_FONT_COLOR_INVALID: Font Color形式が不正。
• BONE_TEXT_FONT_GRADIENT_INVALID: GRADIENT_V1のangle / stops等が不正。
• BONE_TEXT_INPUT_FONT_INVALID: inputFontがobjectではない。
• BONE_TEXT_FONT_FAMILY_INVALID: familyが空など不正。
• BONE_TEXT_FONT_SIZE_INVALID: sizeが0以下、非数など。
• BONE_TEXT_FONT_WEIGHT_INVALID: weightが許容13値外。
• BONE_TEXT_FONT_STYLE_INVALID: styleが3値外。
• BONE_TEXT_OPTIONS_INVALID: optionsがplain objectではない。
• BONE_TEXT_TAG_INVALID: tagが8値外。
• BONE_TEXT_VALUE_TYPE_INVALID: valueTypeが3値外。
• BONE_TEXT_POSITION_INVALID: positionが9値外。
• BONE_TEXT_INPUT_ALIGN_INVALID: inputAlignが4値外。
• BONE_TEXT_DIRECTION_INVALID: directionが3値外。
• BONE_TEXT_WHITESPACE_INVALID: whitespaceが6値外。
• BONE_TEXT_OVERFLOW_INVALID: overflowが3値外。
• BONE_TEXT_MAX_LINES_INVALID: maxLinesが0以上の整数ではない。
• BONE_TEXT_FORMATTER_INVALID: formatterがFunction / nullではない。
• BONE_TEXT_OPTION_TYPE_INVALID: string Propertyへ文字列以外を指定。
• BONE_TEXT_TYPE_MISMATCH: BoneのtypeがTEXTではない。
• BONE_TEXT_DOCUMENT_UNAVAILABLE: documentが利用できない環境でDOM生成。
• BONE_TEXT_TARGET_INVALID: render先がElementではない。
• BONE_TEXT_TAG_IMMUTABLE: 生成済Displayのtag変更。
• BONE_TEXT_INSTANCE_INVALID: BoneText管理外ElementへInstance APIを使用。
• BONE_TEXT_COMPLETION_VALIDATION_REQUIRED: ALL PASS条件なしでcomplete。
• BONE_TEXT_HTML_CLASS_INPUT_TYPE_INVALID: bf-text inputでtypeがtext / number / password以外。
• BONE_TEXT_HTML_CLASS_ELEMENT_UNSUPPORTED: bf-text を対応外要素へ設定。
• BONE_TEXT_HTML_CLASS_RUNTIME_UNAVAILABLE: BoneText Runtime未読込。

Troubleshooting例:

• Positionが動かない: 親レイアウトが bone-text--position-* を解釈しているか確認。#017正式サンプルは .bone-text-position-stage。
• ellipsisが見えない: 親幅が制約されているか、overflow=ellipsis と maxLines を確認。
• Numberなのに左寄せ: inputAlign が auto 以外に固定されていないか確認。
• Gradientが拒否される: angle範囲、stops 2件、position順序、#RRGGBB を確認。
• ColorPickerが出ない: #040 ColorPicker依存と、呼出元（Caller）から戻り値（RETURN）までの状態を確認し、#017独自Pickerで代替しない。

Dependencies / DOC再利用

#017テスト画面で明示される最低Version:

• #001 Bone Core 1.0.0
• #002 Bone Joint 1.1.36
• #020 Bone Label 1.0.50
• #022 Hover Border Effect 1.0.5
• #040 ColorPicker 1.0.15

依存Version判定は同一major.minorで最低patch以上を互換として扱い、必須Public API不足はFAILです。

DOC-0017 は UI-017 Help、HTML Functional Class Guide、印刷説明書、PDF、Help検索から共通利用します。DOC本文を bone-text.html へ重複コピーしません。