State diagram

À propos des diagrammes d'état

Un diagramme d'état (également appelé statechart ou diagramme de machine à états) décrit le cycle de vie d'un système réactif — dans quels états il peut se trouver, quels événements provoquent des transitions entre eux, et quelles actions s'exécutent à l'entrée, à la sortie ou pendant un état. Les architectes logiciels les utilisent pour spécifier des flux de travail ; les ingénieurs en automatique pour concevoir des contrôleurs réactifs ; les concepteurs d'interface utilisateur pour modéliser les cycles de vie des écrans. Ils sont formalisés dans OMG UML 2.5.1 §14 (machines à états) et dans l'extension Statechart de Harel (1987) qui a introduit les états composites, l'historique et les régions orthogonales.

Schematex implémente un sur-ensemble strict de Mermaid stateDiagram-v2 — chaque exemple Mermaid peut être collé sans modification, et vous bénéficiez en plus de fonctionnalités UML 2.5 que Mermaid n'expose pas : activités entry / exit / do, étiquettes de transition complètes trigger [guard] / action, pseudo-états terminate et history, junction, et notes en blocs de style Schematex. La mise en page utilise le même moteur DAG Sugiyama en couches que les diagrammes de flux, de sorte que les cycles, les états composites et les transitions inter-frontières sont tous correctement routés.

1. Votre premier diagramme d'état

Le diagramme d'état utile le plus simple a un état initial, un état final et une transition.

Trois règles couvrent 80 % des usages :

1. Commencez par l'en-tête stateDiagram-v2 (style Mermaid) ou state (style Schematex).
2. Utilisez [*] pour le nœud de départ implicite (à gauche de -->) ou le nœud de fin (à droite).
3. Connectez les états avec -->. Ajoutez une étiquette après : — la forme UML complète est trigger [guard] / action.

La direction par défaut est TB (de haut en bas) pour correspondre à Mermaid. Remplacez par direction LR sur sa propre ligne, ou [direction: LR] sur l'en-tête.

Les commentaires utilisent %% (Mermaid), # ou //.

2. Déclarations d'état

Les états sont créés automatiquement lors de leur première référence dans une transition, mais les déclarations explicites permettent de contrôler l'étiquette et la forme.

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

3. Pseudo-états

Les pseudo-états contrôlent le flux d'une machine à états sans représenter un état stable de repos.

[*] est l'alias Mermaid et est toujours résolu par direction : du côté source de --> c'est un initial, du côté cible c'est un final. Chaque portée composite obtient sa propre paire.

4. Transitions

L'étiquette de transition complète UML 2.5 a trois parties optionnelles :

trigger [guard] / action

Les trois sont optionnels — une transition sans étiquette est anonyme (transition de complétion).

A --> B                                      %% complétion anonyme
A --> B : tick                                %% déclencheur seul
A --> B : [count > 0]                         %% garde seul
A --> B : / clearErrors()                     %% action seule
A --> B : tick [count > 0] / log()            %% les trois
A --> B : tick, tock [enabled] / handle()     %% multi-déclencheur

Les étiquettes longues se plient automatiquement lorsqu'elles dépassent la largeur du couloir.

5. États composites

Un état composite contient un sous-statechart imbriqué. L'état externe agit comme un conteneur avec ses propres pseudo-états initial / final.

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

La syntaxe Mermaid (state X { … }) et la forme Schematex (composite X { … }) sont toutes deux acceptées. Les activités peuvent être déclarées dans le bloc composite :

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

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

Le renderer dessine les composites comme un cluster stylisé avec une barre de titre et un compartiment d'activités.

Les transitions inter-frontières (Extérieur --> Intérieur) sont routées automatiquement — la mise en page Sugiyama tire la source/cible à travers la bordure composite.

6. Régions concurrentes

Dans un composite, le séparateur -- (Mermaid) ou --- (Schematex) divise le corps en régions orthogonales qui s'exécutent de manière concurrente.

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

Utilisez fork et join pour créer / synchroniser des régions :

7. Notes

Une courte annotation peut être attachée à l'un ou l'autre côté de n'importe quel état.

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

Les notes multilignes utilisent la forme de bloc Mermaid end note, ou la forme 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. Auto-transitions

Une transition A --> A s'affiche comme un arc courbé sur le côté droit du nœud.

Idle --> Idle : poll / refresh()

L'étiquette est placée à côté de l'arc, à l'extérieur de la boîte englobante.

9. Direction de mise en page

Schematex utilise par défaut TB (de haut en bas), correspondant à Mermaid. Remplacez sur l'en-tête :

stateDiagram-v2
direction LR

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

Ou avec la forme d'attribut entre crochets de Schematex :

state "Order Lifecycle" [direction: TB]

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

BT et RL sont acceptés par le parseur mais normalisés respectivement en TB et LR (le moteur de mise en page ne retourne pas encore l'ordre visuel).

10. Erreurs courantes

11. Grammaire (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_]*

Source faisant autorité : src/diagrams/state/parser.ts. En cas de divergence avec le parseur, le parseur a la priorité — veuillez ouvrir un ticket.

12. Conformité aux normes

Schematex est un sur-ensemble strict de Mermaid stateDiagram-v2. Les exemples Mermaid peuvent être collés sans modification ; les éléments UML 2.5 supplémentaires (activités, history, junction, terminate, étiquettes de transition complètes) sont acceptés en parallèle.

Références :

• 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. Feuille de route

• Directions BT / RL — actuellement normalisées en TB / LR à l'analyse ; retournement visuel en attente
• Remplacement de direction par région — direction LR dans un bloc composite (actuellement ignoré silencieusement)
• Références de sous-machine — rendu du stéréotype state Foo : Submachine
• Compartiment de transition interne — séparateur visuel explicite pour les lignes tick [g] / a dans le corps d'un état

Exemples associés

Scénarios prêts à l'emploi depuis la galerie d'exemples :