feat: diagram generation for compound, parallel, and history states

- Render initial pseudo-state (black dot → initial child) inside all
  compound subgraphs, not just root level
- Add history state rendering as UML circles labeled "H" / "H*"
- Annotate parallel state subgraph labels with ☷ indicator
- Support multi-target transitions (one edge per target)
- Extract _add_transitions() helper to reduce _graph_states() complexity
- Remove stale TODO comment
- Fix NestedStateFactory to propagate kwargs (e.g. parallel=True) from
  State.Parallel/State.Compound base classes to subclass-created States
- Export HistoryState from statemachine.__init__
- Register event label "None" bug as release blocker in PLAN

Author: fgmacedo

statemachine/__init__.py

@@ -1,4 +1,5 @@
 from .event import Event
+from .state import HistoryState
 from .state import State
 from .statemachine import StateChart
 from .statemachine import StateMachine
@@ -7,4 +8,4 @@
 __email__ = "fgmacedo@gmail.com"
 __version__ = "2.5.0"
 
-__all__ = ["StateChart", "StateMachine", "State", "Event"]
+__all__ = ["StateChart", "StateMachine", "State", "HistoryState", "Event"]

statemachine/contrib/diagram.py

@@ -47,8 +47,11 @@ def _get_subgraph(self, state):
         style = ", solid"
         if state.parent and state.parent.parallel:
             style = ", dashed"
+        label = state.name
+        if state.parallel:
+            label = f"<<b>{state.name}</b> &#9783;>"
         subgraph = pydot.Subgraph(
-            label=f"{state.name}",
+            label=label,
             graph_name=f"cluster_{state.id}",
             style=f"rounded{style}",
             cluster="true",
@@ -128,6 +131,21 @@ def _state_id(state):
         else:
             return state.id
 
+    def _history_node(self, state):
+        label = "H*" if state.deep else "H"
+        return pydot.Node(
+            self._state_id(state),
+            label=label,
+            shape="circle",
+            style="filled",
+            fillcolor="white",
+            fontname=self.font_name,
+            fontsize="8pt",
+            fixedsize="true",
+            width=0.3,
+            height=0.3,
+        )
+
     def _state_as_node(self, state):
         actions = self._state_actions(state)
 
@@ -150,41 +168,51 @@ def _state_as_node(self, state):
             node.set_fillcolor("white")
         return node
 
-    def _transition_as_edge(self, transition):
-        cond = ", ".join([str(cond) for cond in transition.cond])
+    def _transition_as_edges(self, transition):
+        targets = transition.targets if transition.targets else [None]
+        cond = ", ".join([str(c) for c in transition.cond])
         if cond:
             cond = f"\n[{cond}]"
 
-        extra_params = {}
-        has_substates = transition.source.states or (
-            transition.target and transition.target.states
-        )
-        if transition.source.states:
-            extra_params["ltail"] = f"cluster_{transition.source.id}"
-        if transition.target and transition.target.states:
-            extra_params["lhead"] = f"cluster_{transition.target.id}"
-
-        targetless = transition.target is None
-        return pydot.Edge(
-            self._state_id(transition.source),
-            self._state_id(transition.target)
-            if not targetless
-            else self._state_id(transition.source),
-            label=f"{transition.event}{cond}",
-            color="blue",
-            fontname=self.font_name,
-            fontsize=self.transition_font_size,
-            minlen=2 if has_substates else 1,
-            **extra_params,
-        )
+        edges = []
+        for i, target in enumerate(targets):
+            extra_params = {}
+            has_substates = transition.source.states or (target and target.states)
+            if transition.source.states:
+                extra_params["ltail"] = f"cluster_{transition.source.id}"
+            if target and target.states:
+                extra_params["lhead"] = f"cluster_{target.id}"
+
+            targetless = target is None
+            label = f"{transition.event}{cond}" if i == 0 else ""
+            dst = self._state_id(target) if not targetless else self._state_id(transition.source)
+            edges.append(
+                pydot.Edge(
+                    self._state_id(transition.source),
+                    dst,
+                    label=label,
+                    color="blue",
+                    fontname=self.font_name,
+                    fontsize=self.transition_font_size,
+                    minlen=2 if has_substates else 1,
+                    **extra_params,
+                )
+            )
+        return edges
 
     def get_graph(self):
         graph = self._get_graph(self.machine)
         self._graph_states(self.machine, graph, is_root=True)
         return graph
 
+    def _add_transitions(self, graph, state):
+        for transition in state.transitions:
+            if transition.internal:
+                continue
+            for edge in self._transition_as_edges(transition):
+                graph.add_edge(edge)
+
     def _graph_states(self, state, graph, is_root=False):
-        # TODO: handle parallel states in diagram
         initial_node = self._initial_node(state)
         initial_subgraph = pydot.Subgraph(
             graph_name=f"{initial_node.get_name()}_initial",
@@ -202,9 +230,10 @@ def _graph_states(self, state, graph, is_root=False):
         graph.add_subgraph(initial_subgraph)
         graph.add_subgraph(atomic_states_subgraph)
 
-        if is_root:
-            initial = next(s for s in state.states if s.initial)
-            graph.add_edge(self._initial_edge(initial_node, initial))
+        if state.states and not getattr(state, "parallel", False):
+            initial = next((s for s in state.states if s.initial), None)
+            if initial:
+                graph.add_edge(self._initial_edge(initial_node, initial))
 
         for substate in state.states:
             if substate.states:
@@ -213,11 +242,11 @@ def _graph_states(self, state, graph, is_root=False):
                 graph.add_subgraph(subgraph)
             else:
                 atomic_states_subgraph.add_node(self._state_as_node(substate))
+            self._add_transitions(graph, substate)
 
-            for transition in substate.transitions:
-                if transition.internal:
-                    continue
-                graph.add_edge(self._transition_as_edge(transition))
+        for history_state in getattr(state, "history", []):
+            atomic_states_subgraph.add_node(self._history_node(history_state))
+            self._add_transitions(graph, history_state)
 
     def __call__(self):
         return self.get_graph()

statemachine/state.py

@@ -55,7 +55,15 @@ def __new__(  # type: ignore [misc]
         cls, classname, bases, attrs, name="", **kwargs
     ) -> "State":
         if not bases:
-            return super().__new__(cls, classname, bases, attrs)  # type: ignore [return-value]
+            new_cls = super().__new__(cls, classname, bases, attrs)  # type: ignore [return-value]
+            new_cls._factory_kwargs = kwargs  # type: ignore [attr-defined]
+            return new_cls  # type: ignore [return-value]
+
+        # Inherit factory kwargs from base classes (e.g., parallel=True from State.Parallel)
+        inherited_kwargs: dict = {}
+        for base in bases:
+            inherited_kwargs.update(getattr(base, "_factory_kwargs", {}))
+        inherited_kwargs.update(kwargs)
 
         states = []
         callbacks = {}
@@ -68,7 +76,7 @@ def __new__(  # type: ignore [misc]
             elif callable(value):
                 callbacks[key] = value
 
-        return State(name=name, states=states, _callbacks=callbacks, **kwargs)
+        return State(name=name, states=states, _callbacks=callbacks, **inherited_kwargs)
 
     @classmethod
     def to(cls, *args: "State", **kwargs) -> "_ToState":  # pragma: no cover

tests/test_contrib_diagram.py

@@ -5,7 +5,9 @@
 from statemachine.contrib.diagram import DotGraphMachine
 from statemachine.contrib.diagram import main
 from statemachine.contrib.diagram import quickchart_write_svg
+from statemachine.transition import Transition
 
+from statemachine import HistoryState
 from statemachine import State
 from statemachine import StateChart
 
@@ -193,3 +195,164 @@ def test_initial_edge_with_compound_state_has_lhead():
     edge = graph_maker._initial_edge(initial_node, compound)
     attrs = edge.obj_dict["attributes"]
     assert attrs.get("lhead") == f"cluster_{compound.id}"
+
+
+def test_initial_edge_inside_compound_subgraph():
+    """Compound substate has an initial edge from dot to initial child."""
+
+    class SM(StateChart):
+        class parent(State.Compound, name="Parent"):
+            child1 = State(initial=True)
+            child2 = State(final=True)
+
+            go = child1.to(child2)
+
+        start = State(initial=True)
+        end = State(final=True)
+
+        enter = start.to(parent)
+        finish = parent.to(end)
+
+    graph = DotGraphMachine(SM)
+    dot = graph().to_string()
+    # The compound subgraph should contain an initial point node and an edge to child1
+    assert "parent_anchor" in dot
+    assert "child1" in dot
+    # Verify the initial edge exists (from parent's initial node to child1)
+    assert "parent_anchor -> child1" in dot
+
+
+def test_history_state_shallow_diagram():
+    """DOT output contains an 'H' circle node for shallow history state."""
+    h = HistoryState(name="H", deep=False)
+    h._set_id("h_shallow")
+
+    graph_maker = DotGraphMachine.__new__(DotGraphMachine)
+    graph_maker.font_name = "Arial"
+    node = graph_maker._history_node(h)
+    attrs = node.obj_dict["attributes"]
+    assert attrs["label"] in ("H", '"H"')
+    assert attrs["shape"] == "circle"
+
+
+def test_history_state_deep_diagram():
+    """DOT output contains an 'H*' circle node for deep history state."""
+    h = HistoryState(name="H*", deep=True)
+    h._set_id("h_deep")
+
+    graph_maker = DotGraphMachine.__new__(DotGraphMachine)
+    graph_maker.font_name = "Arial"
+    node = graph_maker._history_node(h)
+    # Verify the node renders correctly in DOT output
+    dot_str = node.to_string()
+    assert "H*" in dot_str
+    assert "circle" in dot_str
+
+
+def test_history_state_default_transition():
+    """History state's default transition appears as an edge in the diagram."""
+    child1 = State("child1", initial=True)
+    child1._set_id("child1")
+    child2 = State("child2")
+    child2._set_id("child2")
+
+    h = HistoryState(name="H", deep=False)
+    h._set_id("hist")
+    # Add a default transition from history to child1
+    t = Transition(source=h, target=child1, initial=True)
+    h.transitions.add_transitions(t)
+
+    parent = State("parent", states=[child1, child2], history=[h])
+    parent._set_id("parent")
+
+    graph_maker = DotGraphMachine.__new__(DotGraphMachine)
+    graph_maker.font_name = "Arial"
+    graph_maker.transition_font_size = "9pt"
+
+    edges = graph_maker._transition_as_edges(t)
+    assert len(edges) == 1
+    edge = edges[0]
+    assert edge.obj_dict["points"] == ("hist", "child1")
+
+
+def test_parallel_state_label_indicator():
+    """Parallel subgraph label includes a visual indicator."""
+
+    class SM(StateChart):
+        validate_disconnected_states: bool = False
+
+        class p(State.Parallel, name="p"):
+            class r1(State.Compound, name="r1"):
+                a = State(initial=True)
+
+            class r2(State.Compound, name="r2"):
+                b = State(initial=True)
+
+        start = State(initial=True)
+        begin = start.to(p)
+
+    graph = DotGraphMachine(SM)
+    dot = graph().to_string()
+    # The parallel state label should contain an HTML-like label with the indicator
+    assert "☷" in dot
+
+
+def test_multi_target_transition_diagram():
+    """Edges are created for all targets of a multi-target transition."""
+    source = State("source", initial=True)
+    source._set_id("source")
+    target1 = State("target1")
+    target1._set_id("target1")
+    target2 = State("target2")
+    target2._set_id("target2")
+
+    t = Transition(source=source, target=[target1, target2])
+    t._events.add("go")
+
+    graph_maker = DotGraphMachine.__new__(DotGraphMachine)
+    graph_maker.font_name = "Arial"
+    graph_maker.transition_font_size = "9pt"
+
+    edges = graph_maker._transition_as_edges(t)
+    assert len(edges) == 2
+    assert edges[0].obj_dict["points"] == ("source", "target1")
+    assert edges[1].obj_dict["points"] == ("source", "target2")
+    # Only the first edge gets a label
+    assert edges[0].obj_dict["attributes"]["label"] == "go"
+    assert edges[1].obj_dict["attributes"]["label"] == ""
+
+
+def test_compound_and_parallel_mixed():
+    """Full diagram with compound and parallel states renders without error."""
+
+    class SM(StateChart):
+        validate_disconnected_states: bool = False
+
+        class top(State.Compound, name="Top"):
+            class par(State.Parallel, name="Par"):
+                class region1(State.Compound, name="Region1"):
+                    r1_a = State(initial=True)
+                    r1_b = State(final=True)
+                    r1_go = r1_a.to(r1_b)
+
+                class region2(State.Compound, name="Region2"):
+                    r2_a = State(initial=True)
+                    r2_b = State(final=True)
+                    r2_go = r2_a.to(r2_b)
+
+            entry = State(initial=True)
+            start_par = entry.to(par)
+
+        begin = State(initial=True)
+        enter_top = begin.to(top)
+
+    graph = DotGraphMachine(SM)
+    dot = graph().to_string()
+    assert "cluster_top" in dot
+    assert "cluster_par" in dot
+    assert "cluster_region1" in dot
+    assert "cluster_region2" in dot
+    # Parallel indicator
+    assert "☷" in dot
+    # Verify initial edges exist for compound states (top and regions)
+    assert "top_anchor -> entry" in dot