Usage
=====

Sequence Diagram Elements
-------------------------

Block
+++++

A *Block* is anything (except ``Box``) that has an `end` statement in Mermaid JS.
Some Block types have clauses; clauses can only be added to a given Block type.
The table below summarises the Block types and their clauses, and how these translate to Mermaid JS.

+-----------+--------+------------+--------+
| Block     | Clause | Mermaid JS |        |
+===========+========+============+========+
| Breakk    |        | break      |        |
+-----------+--------+------------+--------+
| Critical  | Option | critical   | option |
+-----------+--------+------------+--------+
| Iff       | Elsee  | alt & opt  | else   |
+-----------+--------+------------+--------+
| Loop      |        | loop       |        |
+-----------+--------+------------+--------+
| Parallel  | Andd   | par        | and    |
+-----------+--------+------------+--------+
| Rectangle |        | rect       |        |
+-----------+--------+------------+--------+

Blocks accept Items (See `Item`_). Block Items are rendered in the order that they are added to the Block.

.. note::
    Blocks are Items and so can be added to Blocks.
    For example, an `Iff` conditional block clause can contain a `Parallel` block.

Breakk
******

A `Breakk` block indicates a stopping of the sequence within the flow.

Critical
********

A `Critical` block indicates that a group of actions must happen.
It *may* contain `Option` clauses to indicate groups of actions dependant on conditions and/or events.

Iff
***

An `Iff` block is a conditional block.
It *may* contain `Elsee` clauses, either with a condition (elseif) or without (else).
If the `Iff` block has `Elsee` clauses it is rendered as an `alt` in Mermaid JS;
if not it is rendered as an `opt`.

Loop
****

A `Loop` block indicates that the actions in the block repeat.
The description *should* indicate such things as repetition frequency,
the condition on which repetition continues or ends, etc.

Parallel
********

A `Parallel` block indicates groups of actions that happen simultaneously and *should* have one or more `Andd` clauses.

.. note::
    It is the action groups that run in parallel; actions within the groups run in sequence.

Rectangle
*********

A `Rectangle` provides a means of grouping actions together.

Item
++++

As mentioned above, Blocks are Items. The other Items are `Message` and `Note`.

Message
*******

.. note::

    `Actor` is used to indicate an `Actor` or `Participant`.

    They are functionally identical and differ only in how they are rendered by Mermaid JS.

A `Message` indicates an action between two `Actors` - a sender and a recipient.
`Actors` are typically defined ahead of time, usually defined at the start of the diagram.
This is always true for the sender, but the the recipient can be defined just before the message.
Similarly, if either the sender or recipient will not take part in any further messages they can be destroyed.

.. note::
    Only one create or destroy can be associated with a `Message`.

    It is not possible to create and destroy an `Actor`, or destroy the sender and recipient on the same message.

Note
****

A `Note` provides additional information about an `Actor`, `Message` or action in the diagram.

Actor/Participant
+++++++++++++++++

An `Actor` is an entity that sends and/or receives messages; it may represent a person, service, job function, ...

The only difference between an `Actor` and a `Participant` is their shape in the diagram;
functionally they are the same;

Box
***

Multiple `Actor`s can be grouped together in a `Box`.

Example
-------

PHP
+++

.. code-block:: php

    echo Mermaid::create(SequenceDiagram::class)
        ->withParticipant($alice, $bob)
        ->withItem(
            new Message($alice, 'Hello Bob', Arrow::solidLineArrowhead, $bob),
            new Message($bob, 'Hello Alice', Arrow::solidLineArrowhead, $alice),
            (new Parallel('Alice to Bob'))
                ->withItem(
                    new Message($alice, 'Message AB', Arrow::solidLineArrowhead, $bob)
                )
                ->withAnd(
                    (new Andd('Alice to Carol'))
                        ->withItem(
                            (new Message($alice, 'Message AC', Arrow::solidLineArrowhead))
                                ->withRecipient($carol)
                            ,
                            (new Message($carol, 'Message CA', Arrow::solidLineArrowhead, $alice))
                                ->destroy(Destroy::sender)
                        )
                    ,
                    (new Andd('Check on Bob'))
                        ->withItem(
                            (new Loop("Check Bob's status every hour until OK"))
                                ->withitem(
                                    new Message($alice, "How's it going Bob", Arrow::solidLineArrowhead, $bob),
                                )
                            ,
                            new Note('Bob is OK so end the loop', Position::over, $alice, $bob),
                            new Message($bob, "I'm OK Alice", Arrow::solidLineArrowhead, $alice),
                            (new Iff('If it concerns Dave'))
                                ->withItem(
                                    (new Message($alice, 'Message AD', Arrow::solidLineArrowhead))
                                        ->withRecipient($dave)
                                )

                        )
                    ,
                    (new Andd('One of the boys'))
                        ->withItem(
                            (new Iff('Dave'))
                                ->withItem(
                                    (new Message($alice, 'Message AD', Arrow::solidLineArrowhead, $dave))
                                        ->destroy(Destroy::recipient)
                                )
                                ->withElse(
                                    (new Elsee('Bob'))
                                        ->withItem(
                                            new Message($alice, 'Message AB', Arrow::solidLineArrowhead, $bob)
                                        )
                                )
                        )
                ),
                new Message($alice, 'Time to wrap up Bob', Arrow::solidLineArrowhead, $bob),
                new Message($bob, 'OK Alice', Arrow::solidLineArrowhead, $alice)
        )
        ->render()
    ;

Generated Mermaid
+++++++++++++++++

.. code-block:: html

    <pre class="mermaid">
    sequenceDiagram
      participant _A as Alice
      participant _B as Bob
      _A->>_B: Hello Bob
      _B->>_A: Hello Alice
      par Alice to Bob
        _A->>_B: Message AB
      and Alice to Carol
        create participant _C as Carol
        _A->>_C: Message AC
        destroy _C
        _C->>_A: Message CA
      and Check on Bob
        loop Check Bob's status every hour until OK
          _A->>_B: How's it going Bob
        end
        note over _A,_B: Bob is OK so end the loop
        _B->>_A: I'm OK Alice
        opt If it concerns Dave
          create participant _D as Dave
          _A->>_D: Message AD
        end
      and One of the boys
        alt Dave
          destroy _D
          _A->>_D: Message AD
        else Bob
          _A->>_B: Message AB
        end
      end
      _A->>_B: Time to wrap up Bob
      _B->>_A: OK Alice
    </pre>

Mermaid Diagram
+++++++++++++++

.. mermaid::

    sequenceDiagram
      participant _A as Alice
      participant _B as Bob
      _A->>_B: Hello Bob
      _B->>_A: Hello Alice
      par Alice to Bob
        _A->>_B: Message AB
      and Alice to Carol
        create participant _C as Carol
        _A->>_C: Message AC
        destroy _C
        _C->>_A: Message CA
      and Check on Bob
        loop Check Bob's status every hour until OK
          _A->>_B: How's it going Bob
        end
        note over _A,_B: Bob is OK so end the loop
        _B->>_A: I'm OK Alice
        opt If it concerns Dave
          create participant _D as Dave
          _A->>_D: Message AD
        end
      and One of the boys
        alt Dave
          destroy _D
          _A->>_D: Message AD
        else Bob
          _A->>_B: Message AB
        end
      end
      _A->>_B: Time to wrap up Bob
      _B->>_A: OK Alice