Render Options¶

@dataclass
class PlantUMLRenderOptions:
    """
    Final render options for rendering a C4-PlantUML diagram.

    This class encapsulates all layout directives, macros, tag definitions,
    and visual styles that should be applied to a diagram at render time.

    Attributes:
        includes: A list of PlantUML `!include` directives
            to be injected at the beginning of the diagram.
        layout: Layout direction (e.g., top-down, left-right, landscape).
        layout_with_legend: Whether to apply the LAYOUT_WITH_LEGEND macro.
        layout_as_sketch: Whether to apply the LAYOUT_AS_SKETCH macro.
        set_sketch_style: Optional sketch-style visual customization.
        show_legend: Configuration for SHOW_LEGEND macro.
        show_floating_legend: Configuration for SHOW_FLOATING_LEGEND macro.
        hide_stereotype: Whether to hide stereotype labels globally.
        hide_person_sprite: Whether to hide person sprites globally.
        show_person_sprite: Configuration for SHOW_PERSON_SPRITE macro.
        show_person_portrait: Whether to enable person portraits.
        show_person_outline: Whether to enable person outlines.
        without_property_header: If no header is used, then the second column
            is bold.
        legend_title: Optional title for the diagram legend.
        tags: List of tag macros (e.g., AddElementTag, AddRelTag).
        styles: List of style update macros (e.g., UpdateElementStyle).
    """

    includes: list[str] = field(default_factory=list)
    layout: DiagramLayout | None = None
    layout_with_legend: bool = False
    layout_as_sketch: bool = False
    set_sketch_style: SetSketchStyle | None = None
    show_legend: ShowLegend | None = None
    show_floating_legend: ShowFloatingLegend | None = None
    hide_stereotype: bool = False
    hide_person_sprite: bool = False
    show_person_sprite: ShowPersonSprite | None = None
    show_person_portrait: bool = False
    show_person_outline: bool = False
    without_property_header: bool = False
    legend_title: str | None = None
    tags: list[BaseTag] = field(default_factory=list)
    styles: list[BaseStyle] = field(default_factory=list)

@unique
class DiagramLayout(StrEnum):
    """
    Defines layout direction options for a PlantUML diagram.

    This enum controls how diagram elements are arranged visually using
    predefined PlantUML layout macros.
    """

    LAYOUT_TOP_DOWN = "LAYOUT_TOP_DOWN"
    LAYOUT_LEFT_RIGHT = "LAYOUT_LEFT_RIGHT"
    LAYOUT_LANDSCAPE = "LAYOUT_LANDSCAPE"

@dataclass
class BaseTag:
    """
    Base class for C4-PlantUML tag macros.

    Represents shared attributes for tags applied to diagram elements or
    relationships, including optional visual enhancements and legend metadata.

    Attributes:
        tag_stereo: Stereotype name of the tag. Must match one of the tags
            declared in the `tags` field of a diagram component.
        legend_text: The text shown in the legend for this tag.
        legend_sprite: The sprite displayed in the legend.
        sprite: The sprite icon associated with the element or relationship.
    """

    tag_stereo: str | None = None
    legend_text: str | None = None
    legend_sprite: str | None = None
    sprite: str | None = None

@dataclass
class ElementTag(BaseTag):
    """
    Represents a tag for general diagram elements
    (e.g., containers, nodes, components).

    Defines color, border, shape, and optional technology metadata.

    Attributes:
        bg_color: Background color of the element.
        font_color: Font color used for labels.
        border_color: Color of the element border.
        shadowing: Shadow style or toggle (e.g., "true", "false").
        shape: Optional shape used for rendering.
        technology: Technology label shown in the element.
        border_style: Border style (e.g., solid, dashed).
        border_thickness: Thickness of the borderline.
    """

    bg_color: str | None = None
    font_color: str | None = None
    border_color: str | None = None
    shadowing: bool | None = None
    shape: TagShape | None = None
    technology: str | None = None
    border_style: LineStyle | None = None
    border_thickness: str | None = None

@dataclass
class RelTag(BaseTag):
    """
    Represents a tag for relationship styling in the diagram.

    Includes text and line formatting, plus optional technology
    and sprite metadata.

    Attributes:
        text_color: Color of the relationship label.
        line_color: Color of the relationship line.
        line_style: Line style (e.g., solid, dashed).
        line_thickness: Thickness of the line.
        technology: Technology label associated with the relationship.
    """

    text_color: str | None = None
    line_color: str | None = None
    line_style: LineStyle | None = None
    line_thickness: str | None = None
    technology: str | None = None

@dataclass
class BoundaryTag(BaseTag):
    """
    Represents a tag for diagram boundaries (e.g., containers or systems).

    Defines color, border, shape, and optional type metadata.
    """

    bg_color: str | None = None
    font_color: str | None = None
    border_color: str | None = None
    shadowing: bool | None = None
    shape: TagShape | None = None
    type_: str | None = None
    border_style: LineStyle | None = None
    border_thickness: str | None = None

@dataclass
class ComponentTag(ElementTag):
    """
    Represents a tag for internal software components.

    Inherits common styling options from ElementTag.
    """

@dataclass
class ExternalComponentTag(ComponentTag):
    """
    Represents a tag for external software components.

    Inherits common styling options from ComponentTag.
    """

@dataclass
class ContainerTag(ElementTag):
    """
    Represents a tag for internal containers (e.g., microservices, databases).

    Inherits common styling options from ElementTag.
    """

@dataclass
class ExternalContainerTag(ContainerTag):
    """
    Represents a tag for external containers.

    Inherits common styling options from ContainerTag.
    """

@dataclass
class NodeTag(BaseTag):
    """
    Represents a tag for nodes, typically infrastructure elements.

    Defines color, border, shape, and optional type metadata.
    """

    bg_color: str | None = None
    font_color: str | None = None
    border_color: str | None = None
    shadowing: bool | None = None
    shape: TagShape | None = None
    type_: str | None = None
    border_style: LineStyle | None = None
    border_thickness: str | None = None

@dataclass
class PersonTag(BaseTag):
    """
    Represents a tag for internal Person elements (actors, users, roles).

    Attributes:
        bg_color: Background color of the person symbol.
        font_color: Font color used in the label.
        border_color: Border color of the symbol.
        shadowing: Whether shadowing is applied.
        shape: Optional shape used for rendering.
        type_: Person type (e.g., "person", "group").
        border_style: Border style (e.g., solid, dashed).
        border_thickness: Border thickness.
    """

    bg_color: str | None = None
    font_color: str | None = None
    border_color: str | None = None
    shadowing: bool | None = None
    shape: TagShape | None = None
    type_: str | None = None
    border_style: LineStyle | None = None
    border_thickness: str | None = None

@dataclass
class ExternalPersonTag(PersonTag):
    """
    Represents a tag for external people (actors outside the system boundary).

    Inherits common styling options from PersonTag.
    """

@dataclass
class SystemTag(BaseTag):
    """
    Represents a tag for internal software systems.

    Attributes:
        bg_color: Background color.
        font_color: Font color used in text.
        border_color: Color of the system border.
        shadowing: Shadow effect toggle.
        shape: Optional rendering shape.
        type_: Type of system (e.g., "software system").
        border_style: Style of the system border line.
        border_thickness: Thickness of the border.
    """

    bg_color: str | None = None
    font_color: str | None = None
    border_color: str | None = None
    shadowing: bool | None = None
    shape: TagShape | None = None
    type_: str | None = None
    border_style: LineStyle | None = None
    border_thickness: str | None = None

@dataclass
class ExternalSystemTag(SystemTag):
    """
    Represents a tag for external software systems.

    Inherits common styling options from SystemTag.
    """

@dataclass
class ElementStyle(BaseStyle):
    """
    Defines style overrides for an individual diagram element.

    Attributes:
        element_name: Alias of the element to style.
        bg_color: Background color.
        font_color: Font/text color.
        border_color: Borderline color.
        shadowing: Shadow effect toggle.
        shape: Shape type used for rendering.
        sprite: Optional sprite icon.
        technology: Optional technology label.
        legend_text: Label used in the legend.
        legend_sprite: Sprite shown in the legend.
        border_style: Borderline style (e.g. dashed, solid).
        border_thickness: Thickness of the borderline.
    """

    element_name: str | None = None
    bg_color: str | None = None
    font_color: str | None = None
    border_color: str | None = None
    shadowing: bool | None = None
    shape: TagShape | None = None
    sprite: str | None = None
    technology: str | None = None
    legend_text: str | None = None
    legend_sprite: str | None = None
    border_style: LineStyle | None = None
    border_thickness: str | None = None

@dataclass
class RelStyle(BaseStyle):
    """
    Defines style overrides for relationship lines.

    Attributes:
        text_color: Color of the relationship label.
        line_color: Color of the connecting line.
    """

    text_color: str | None = None
    line_color: str | None = None