状態図

状態図とは

状態図（ステートチャートまたは状態機械図とも呼ばれる）は、リアクティブシステムのライフサイクルを記述します——システムがとりうる状態、何のイベントが状態間の遷移を引き起こすか、状態への入場・退場・滞在中に実行されるアクション。ソフトウェアアーキテクトはワークフローの仕様記述に使用し、制御エンジニアはリアクティブコントローラの設計に使用し、UI デザイナーは画面ライフサイクルのモデリングに使用します。OMG UML 2.5.1 §14（状態機械）と、コンポジット状態・ヒストリー・直交領域を導入した Harel の1987年のステートチャート拡張で形式化されています。

Schematex は Mermaid stateDiagram-v2 の厳密なスーパーセットを実装しています——すべての Mermaid の例をそのまま貼り付けて動作し、Mermaid が公開していない UML 2.5 の機能も利用できます：entry / exit / do アクティビティ、完全な trigger [guard] / action 遷移ラベル、terminate とヒストリー擬似状態、junction、Schematex スタイルのブロックノート。レイアウトはフローチャートと同じ Sugiyama 階層化 DAG エンジンを使用するため、サイクル・コンポジット状態・クロスバウンダリ遷移もすべてクリーンにルーティングされます。

1. 最初の状態図

最小限の実用的な状態図：初期状態、最終状態、1つの遷移。

3つのルールで使用例の80%をカバーできます：

1. stateDiagram-v2（Mermaid スタイル）または state（Schematex スタイル）ヘッダーで始めます。
2. 暗黙的な開始ノード（--> の左側にある場合）または終了ノード（右側にある場合）に [*] を使用します。
3. --> で状態をつなぎます。: の後にラベルを追加します——完全な UML 形式は trigger [guard] / action です。

デフォルトの方向は Mermaid に合わせて TB（上から下）です。独立した行に direction LR を記述するか、ヘッダーに [direction: LR] を記述してオーバーライドします。

コメントは %%（Mermaid）、#、または // を使用します。

2. 状態の宣言

状態は遷移で初めて参照されたときに自動的に作成されますが、明示的な宣言でラベルと形状を制御できます。

state Authenticating
state "Awaiting Approval" as Approval
Idle: Waiting for input

3. 擬似状態

擬似状態は、安定した待機状態を表すことなく、状態機械のフローを制御します。

[*] は Mermaid のエイリアスで、常に方向によって解決されます：--> のソース側では initial、ターゲット側では final。各コンポジットスコープは独自のペアを持ちます。

4. 遷移

完全な UML 2.5 遷移ラベルは3つのオプションパーツを持ちます：

trigger [guard] / action

3つすべてオプションです——ラベルなしの遷移は匿名（完了遷移）です。

A --> B                                      %% 匿名完了
A --> B : tick                                %% トリガーのみ
A --> B : [count > 0]                         %% ガードのみ
A --> B : / clearErrors()                     %% アクションのみ
A --> B : tick [count > 0] / log()            %% 3つすべて
A --> B : tick, tock [enabled] / handle()     %% マルチトリガー

長いラベルはレーン幅を超えると自動的に折り返されます。

5. コンポジット状態

コンポジット状態は、ネストされたサブ状態チャートを含みます。外側の状態は独自の初期 / 最終擬似状態を持つコンテナとして機能します。

state Playing {
  [*] --> Buffering
  Buffering --> Streaming : buffer_full
  Streaming --> Buffering : underflow
}

Mermaid 構文（state X { … }）と Schematex 形式（composite X { … }）の両方が受け入れられます。アクティビティはコンポジットブロック内で宣言できます：

state Playing {
  entry / startBuffer()
  exit / stopBuffer()
  do / decodeFrames()

  [*] --> Buffering
  Buffering --> Streaming : buffer_full
  Streaming --> Buffering : underflow
}

レンダラーはコンポジットをタイトルバーとアクティビティコンパートメントを持つスタイル付きクラスターとして描画します。

クロスバウンダリ遷移（Outside --> Inside）は自動的にルーティングされます——Sugiyama レイアウトがソース / ターゲットをコンポジットボーダーを通して引き出します。

6. 並行リージョン

コンポジットの内側で、-- セパレーター（Mermaid）または ---（Schematex）がボディを並行して実行される直交リージョンに分割します。

state Active {
  [*] --> r1_idle
  r1_idle --> Connected : connect
  --
  [*] --> r2_idle
  r2_idle --> Working : start
}

fork と join を使用してリージョン間でスポーン / 同期します：

7. ノート

短いアノテーションを任意の状態のどちら側にも付加できます。

note right of Checking : Calls /api/verify synchronously.
note left of Idle : Anonymous landing state

複数行のノートは Mermaid の end note ブロック形式、または Schematex の { … } 形式を使用します：

note right of Authenticating
  Stores the JWT in localStorage
  on success.
end note

note left_of Idle {
  Anonymous landing state.
  Returns here on 401.
}

8. セルフ遷移

遷移 A --> A はノードの右側に曲線弧としてレンダリングされます。

Idle --> Idle : poll / refresh()

ラベルは弧の横、バウンディングボックスの外側に配置されます。

9. レイアウトの方向

Schematex はデフォルトで Mermaid に合わせて TB（上から下）です。ヘッダーでオーバーライドします：

stateDiagram-v2
direction LR

[*] --> Loading
Loading --> Ready

または Schematex のブラケット属性形式で：

state "Order Lifecycle" [direction: TB]

[*] --> Pending
Pending --> Paid

BT と RL はパーサーが受け付けますが、それぞれ TB と LR に正規化されます（レイアウトエンジンはまだ視覚的な順序を反転しません）。

10. よくある間違い

11. 文法（EBNF）

document     = header statement*
header       = ("stateDiagram-v2" | "stateDiagram" | "state")
                ( title )? ( "[" attrs "]" )? NEWLINE
attrs        = attr ("," attr)*
attr         = "direction:" ("TB" | "LR")

statement    = comment
             | direction-stmt              %% direction LR / TB / BT / RL
             | state-decl
             | alias-decl                  %% state "Long" as ID
             | stereotype-decl             %% state ID <<choice|fork|join|end>>
             | pseudo-decl                 %% initial / final / choice / ... ID
             | composite-block             %% (state | composite) ID { ... }
             | label-stmt                  %% ID : description
             | transition
             | note-stmt
             | region-sep                  %% --  or  ---

transition   = (ID | "[*]") "-->" (ID | "[*]") ( ":" trans-label )? NEWLINE
trans-label  = trigger? ( "[" guard "]" )? ( "/" action )?

note-stmt    = "note" side ID ":" inline-text NEWLINE
             | "note" side ID NEWLINE  text-line+  ("end note" | "}") NEWLINE
side         = "left of" | "right of" | "left_of" | "right_of"

comment      = "%%" any | "#" any | "//" any

ID           = [A-Za-z_] [A-Za-z0-9_]*

権威ある情報源：src/diagrams/state/parser.ts。パーサーとの相違がある場合は、パーサーが優先されます——Issue を作成してください。

12. 標準準拠

Schematex は Mermaid stateDiagram-v2 の厳密なスーパーセットです。Mermaid の例はそのまま貼り付けて動作し、追加の UML 2.5 要素（アクティビティ、ヒストリー、junction、terminate、完全な遷移ラベル）もサイドバイサイドで受け入れられます。

参考文献：

• OMG UML 2.5.1 — Unified Modeling Language: https://www.omg.org/spec/UML/2.5.1/
• Harel (1987) — Statecharts: A visual formalism for complex systems, Science of Computer Programming 8(3)
• Mermaid stateDiagram-v2 — https://mermaid.js.org/syntax/stateDiagram.html

13. ロードマップ

• BT / RL 方向 — 現在はパース時に TB / LR に正規化；視覚的な反転は保留中
• リージョンごとの方向オーバーライド — コンポジットブロック内の direction LR（現在は暗黙的に無視）
• サブマシン参照 — state Foo : Submachine ステレオタイプレンダリング
• 内部遷移コンパートメント — 状態ボディ内の tick [g] / a 行の明示的な視覚的区切り

関連する例

サンプルギャラリーからすぐに使えるシナリオ：