CONNECT · ROUTE · STATE · DELIVER · DIAGNOSE

Bone Flow #002 - Bone Joint Guide

Runtime 1.1.40 / Package 1.0.28。Bone Flowで「意味」を次へ安全につなぐ接続層を、初見の人でも実画面と対応づけて理解するためのGuideです。

1. Bone FlowとJoint

#001 Bone Coreは id / type / value を持つ「意味の最小単位」を作ります。#002 Bone Jointは、その意味をSourceからTargetへ接続・評価・配送し、UIが見た目へ変換できる状態へ渡します。

最初に覚える1行： Coreが意味を作る → Jointがつなぐ → UIが表現する → Validationが正しさを確かめる。

Source / #001 BoneOUT Port
Source Field

→

#002 Bone JointEndpoint解決 / Compatibility / State / Delivery / Route

→

Target UI / BoneIN Port
Target Field

JointはSVG線そのものではありません。線はJointが持つ接続状態を可視化した結果です。

2. Jointの構造

要素	役割	異常時
Source	意味を送り出すBone/UI	Bone不存在 / Endpoint不存在 / Field不存在を別々に診断
Target	意味を受け取るBone/UI	同上
Endpoint	`boneId + field` の接続定義	Endpoint invalid / unavailable
Field	実際の値を出し入れする対象	Field missing
Compatibility	Source値→Target値が接続可能か	EXACT / WARNING / ERROR
State	connected / waiting / blocked等	診断表示・Deliveryに反映

const result = BoneJoint.evaluate({
  id: "title-joint",
  source: { boneId: "source", field: "title" },
  target: { boneId: "target", field: "text" }
}, bones);

result.sourceField.exists
result.targetField.exists
result.compatibility.connectionAllowed
result.state.status

3. Port / RETURN

方向TB/BT/LR/RLによってTOP/RIGHT/BOTTOM/LEFTの役割をIN/OUT/RETURNへ割り当てます。通常配送は OUT → IN、差戻し経路はRETURNを使います。

接続	結果	Code
OUT → IN	正常	OK
OUT → RETURN	差戻し	OK_RETURN
RETURN → RETURN	差戻し	OK_RETURN
OUT → OUT	禁止	JOINT_PORT_ROLE_INCOMPATIBLE
不明Role	禁止	JOINT_PORT_ROLE_INVALID

4. Compatibility

Fieldが実在してから型互換性を評価します。INT/NUMBER → STRING はWARNINGだが接続可能、それ以外の暗黙型不一致はERRORとして接続不可です。NULLは規則で許容できます。

EXACT

同一型。connectionAllowed=true

WARNING

数値→文字列等。接続維持、警告Marker。

ERROR

STRING→INT等。JOINT_TYPE_INCOMPATIBLE

5. 接続状態

connected

接続成立、配送可能。

waiting

Target Busy。接続維持、Queue待機。

blocked

接続維持、配送停止。

disconnected

切断済み。

reconnecting

再接続試行中。

error

Bone/Endpoint/Field/Compatibility等の異常。

6. WAIT / FIFO / BLOCKED

createDeliveryChannel() が実配送を担当します。単なる表示状態ではありません。

WAIT

targetReady=false の間はPayloadをQueueへ保持。Readyになったら自動flush。

FIFO

Queueへ入った順に配送。getQueue() / getHistory() で確認可能。

BLOCKED

guardが拒否したPayloadはQueueへ入れずTargetにも渡さない。clearBlock() で状態解除。

違い： WAIT=後で届ける。BLOCKED=届けない。

const channel = BoneJoint.createDeliveryChannel({
  targetReady: false,
  deliver(payload) { target.receive(payload); },
  guard(payload) { return { allowed: isTrusted(payload), reason: "security" }; }
});
channel.deliver({ id: 1 }); // waiting / queued
channel.setTargetReady(true); // FIFOで自動配送

7. 直線 / 曲線 / 直角

Jointの接続形態はHTML Functional Classでも直接指定できます。下の表示は画像ではなく、すべて実際の bf-joint です。

直線 / straight

Source

Target

曲線 / curve

Source

Target

直角 / orthogonal

Source

Target

直角はPort Clearance / Corner Radius / Lane Separation / Shape Avoidanceの対象です。

8. Joint表示設定

Test画面上部の設定はRenderer確認用です。起点形状/サイズ、未接続終端、線色・太さ・透明度・線種、方向アニメーション、Orthogonal設定、交差表現、Joint Labelを切り替えます。

MarkerLine StyleAnimationPort ClearanceCorner RadiusLane GapShape AvoidanceIntersection BridgeLabel

これらは接続判定そのものとは分離されています。見た目を変えてもSource/Target/Compatibility/Stateの判定結果を改変してはいけません。

9. 異常接続と正式Marker

異常表示は bf-joint 独自のアイコンを持ちません。WAIT / BLOCKED / Error / Compatibility は BoneJoint 1.1.40 の正式Markerをそのまま描画します。

WAIT / 正式spinner

OUT

Target

BLOCKED / 正式ban

OUT

Target

Target Field不存在

Source.value

Target.caption

Compatibility Warning

INT

STRING

Compatibility Error

STRING

INT

禁止: bf-joint専用のalert icon / spinner / ban / animation / diagnosticを追加しません。

10. Public API（Runtime 1.1.40）

以下は実Runtimeに存在する公開APIです。Guide上の架空APIは追加しません。

evaluate()Source/Target/Endpoint/Field/Compatibility/Stateを一括評価。

disconnect()切断状態を生成。

reconnect()再接続状態を生成。

wait()waiting状態を生成。

block()blocked状態を生成。

createDeliveryChannel()WAIT/FIFO/BLOCKEDを実配送するChannel。

resolvePortRoles()TB/BT/LR/RLのIN/OUT/RETURNを解決。

resolvePortRole()指定位置のPort roleを取得。

validatePortConnection()OUT→IN/RETURN等の接続可否を判定。

drawLine()正式Joint線を描画。

drawError()不存在終端等のエラー線/Markerを描画。

drawCompatibilityMarker()型互換性Markerを描画。

setMarkerOptions()Marker表示設定を変更。

getMarkerOptions()Marker表示設定を取得。

resolveRoute()Straight/Curve/Orthogonal経路を解決。

setDisplayOptions()表示オプションを設定。

getDisplayOptions()表示オプションを取得。

setDefaultStyle()Renderer既定Styleを設定。

getDefaultStyle()Renderer既定Styleを取得。

resolveStyle()既定＋個別Styleを解決。

renderIntersections()交差/Bridge表現を描画。

renderLabel()Joint Label/Calloutを描画。

getLabelState()Label位置状態を取得。

resetLabelPositions()Label位置を自動配置へ戻す。

11. HTML Functional Class：bf-joint

bf-joint は別Jointではなく、HTMLから正式 BoneJoint APIを呼ぶ薄いAdapterです。

<div class="bf-joint" data-route="orthogonal" data-state="blocked">
  <div class="bf-joint-source">OUT</div>
  <div class="bf-joint-target">Target</div>
</div>

bf-joint-in / bf-joint-out は既存 bf-joint Hostへ付ける意味役割modifierです。正式Joint描画はそのままBoneJoint Runtimeを使用し、Hostの data-bf-joint-role と実Pathの data-joint-role に in / out を反映します。到達方向の三角形は先端を実Target endpointへ合わせ、黒枠は表示しません。

<div class="bf-joint bf-joint-in" ...>...</div>
<div class="bf-joint bf-joint-out" ...>...</div>

属性	値	正式対応
data-route	straight / curve / orthogonal	BoneJoint.drawLine routeStyle
data-state	connected / waiting / blocked / disconnected / reconnecting / error	BoneJoint正式State
data-source / data-target	JSON Endpoint	BoneJoint.evaluate definition.source / target
data-bones	JSON Bone辞書	BoneJoint.evaluate bones
data-source-port / data-target-port	TOP / RIGHT / BOTTOM / LEFT	正式Port position
data-source-id / data-target-id	Host内element id	描画座標のDOM参照

異常の種類・Marker・AnimationをHTML側で再定義しません。評価Codeと表示は正式Runtimeの結果を使用します。

12. Smoke Test / Validation / 000累積回帰

確認	対象	役割
Smoke Test	#002単体	主要API・主要Route・主要Stateの基本動作。
Validation	#002単体	異常系、診断Code、Port、WAIT/FIFO/BLOCKED、描画規則を詳細検証。
000 Development Order	統合bundle	#001+#002を含む `boneflow.js / boneflow.css` の累積回帰。

13. コンポーネント完了管理

Smoke Test ALL PASS
Validation ALL PASS
WAIT: Busy→Queue→Ready後FIFO配送をlocalhostで目視
BLOCKED: 接続維持かつTarget配送0をlocalhostで目視
完了ボタン二重実行不可
再読込後Completion状態維持
ユーザーが「完了」と明示した後だけ正式Completed / Frozen

14. 実装例

正常接続を評価

const result = BoneJoint.evaluate(definition, bones);
if (result.connectionEstablished) {
  // Joint線を描画し配送可能状態へ
}

表示経路を解決

const route = BoneJoint.resolveRoute({
  x1: 100, y1: 120, x2: 420, y2: 260,
  routeStyle: "orthogonal",
  sourcePortPosition: "RIGHT",
  targetPortPosition: "LEFT",
  orthogonalClearance: 40,
  orthogonalCornerRadius: 10
});

15. 確認チェックリスト

Source/Target/Bone/Endpoint/Fieldを別々に診断できる
OUT→INとRETURN規則が実Runtimeと一致
EXACT/WARNING/ERRORがSource→Target方向で正しい
WAITはQueue保持、FIFOで自動配送
BLOCKEDはTarget配送0
disconnected/reconnecting/errorをWAIT/BLOCKEDと混同しない
Straight/Curve/Orthogonalを実座標から描画
不存在側から線を発生させない
Smoke/Validation/000を別役割として確認
Guide JP/EN/検索/印刷/TOCが動作