# Bone Flow #023 - コード入力ガイド

Version: 1.0.80  
Status: Release Ready Candidate

## 目的

Flow Editor の `.bflow` Source を初めて入力する利用者向けの正式入力ガイドです。
画面の **入力ガイド** ボタンを押すと、#021 Bone Shape Registry の実Shape画像一覧、Node / Joint / Port / TABLE_DETAIL / Directive の説明をエディタ内で確認できます。Shape画像は #023 が独自に描き直さず、インストール済み #021 Bone Shape を実行時生成します。

## 1. 最小コード

```text
@id sample-flow
@title "Sample Flow"
@version 1.0.0
@flow direction=TB
@theme light
@joint line=orthogonal
@joint animate=false
@layout mode=auto

(start:開始)
=>
[process:処理]
=>
((end:終了))
```

## 2. Node / Shape

主要Shapeは短縮Syntaxを使用できます。

| TYPE | Syntax | 用途 |
| --- | --- | --- |
| START | `(start:開始)` | 開始 |
| END | `((end:終了))` | 終了 |
| PROCESS | `[work:処理]` | 通常処理 |
| DECISION | `<check:承認？>` | 条件分岐 |
| INPUT_OUTPUT | `{io:入出力}` | 入出力 |
| SUB_PROCESS | `[[sub:サブ処理]]` | サブプロセス |
| その他 | `[id:TYPE:表示文字]` | #021 Registry TYPE |

その他TYPEの例：

```text
[db:DATABASE:顧客DB]
[api:API:注文API]
[doc:DOCUMENT:納品書]
[file:FILE:orders.csv]
```

画面のShape TYPE一覧は `BoneShape.list()` / `BoneShape.registry.shapes` の実体を使用するため、#021 Registryの内容と同期します。Shapeカードをクリックすると対応するNodeコードをSourceのカーソル位置へ挿入します。

## 3. Node option

```text
[node:PROCESS:処理] {manual,x:120,y:240,theme:dark,scale:1.2,comment:"説明",tooltip:"詳細"}
```

- `manual`: 手動配置
- `x`, `y`: 手動座標
- `theme`: Node個別テーマ
- `scale`: Node個別倍率
- `comment`: Shape Comment
- `tooltip`: Tooltip

## 4. Joint

| 記号 | 線種 | 例 |
| --- | --- | --- |
| `--` | Global Default | `[a] -- [b]` |
| `->` | Straight | `[a] -> [b]` |
| `~>` | Curve | `[a] ~> [b]` |
| `=>` | Orthogonal | `[a] => [b]` |

Joint Label：

```text
[a] -"送信"-> [b]
[a] ~"送信"~> [b]
[a] ="送信"=> [b]
```

Decision Branch：

```text
<check:承認？>
[check] ="承認"=>{key:承認} [ok:実行]
[check] ="否認"=>{key:差戻し} [ng:差戻し]
```

`key:` は表示する分岐キーです。YES / NO 固定ではありません。Joint LabelとBranch Keyは別情報です。

主なJoint option：

- `animate:true|false`
- `speed:slow|normal|fast`
- `solid`, `dashed`, `dotted`, `dash-dot`
- `width:1..12`
- `jump`, `nojump`
- `curve-side:auto|left|right`
- `color:"#RRGGBB"`
- `clearance:0..120`
- `key:VALUE`

## 5. Port / RETURN

通常接続は OUT → IN です。TB方向の通常Shapeは以下の実効Roleです。

- TOP = IN
- BOTTOM = OUT
- LEFT = RETURN
- RIGHT = RETURN

物理Portを直接指定する場合：

```text
[source].BOTTOM => [target].TOP
```

差戻し：

```text
[ng].LEFT => [request].LEFT
```

RETURNは `.RETURN` というRole suffixでは指定しません。LEFT / RIGHT等の**物理位置selector**で指定します。Previewでは有効なRETURN送信位置をOUTとして表示し、RETURN文字は表示しません。

## 6. TABLE_DETAIL

```text
[customers:TABLE_DETAIL:顧客]
{
    customer_id : 顧客ID : INT {pk,required}
    name        : 顧客名 : VARCHAR
}

[orders:TABLE_DETAIL:注文]
{
    order_id    : 注文ID : INT {pk,required}
    customer_id : 顧客ID : INT {fk,required}
}

[customers].customer_id.OUT ="customer_id"=> [orders].customer_id.IN
```

TABLE_DETAIL Field Portは常に LEFT=IN / RIGHT=OUT です。`@flow direction` ではField PortのIN / OUTは回転しません。

## 7. Directive

```text
@id flow-id
@title "タイトル"
@version 1.0.0
@flow direction=TB
@theme light
@shape scale=1
@joint line=orthogonal
@joint animate=true
@joint speed=normal
@joint intersection=jump
@layout mode=auto
@layout gap=80
@layout branch-gap=120
```

- `direction`: `TB / BT / LR / RL`
- `theme`: `light / dark / neon`
- `joint line`: `straight / curve / orthogonal`
- `layout mode`: `auto / manual`

## 8. 入力支援

- Source Editor の **入力ガイド**: 実Shape画像とコード説明を表示
- Shapeカード: 対応するNodeコードをカーソル位置へ挿入
- 各コード例の **Sourceへ挿入**: 例をカーソル位置へ挿入
- `Ctrl+Space`: 簡易補完
- **フロー設定**: DirectiveをGUIから変更
- **サンプル**: Basic / Decision / Data / Table / Error Flowを実例として確認

## 9. Export

- Source保存: `.bflow`
- SVG保存: 背景透明、Jointアニメーション保持
- PNG保存: 背景透明、静止画

## 10. 責務

- Shape Geometry / Shape画像: #021 Bone Shape
- Joint描画 / Label / Animation / Error表示: #002 Bone Joint
- Syntax / Parser / Validation / Layout / Editor / Input Guide: #023 Bone Flow Editor

#023側でShape Geometryを再実装しません。