D2 Render Options¶

@dataclass(frozen=True)
class D2RenderOptions:
    """
    Render options for the D2 renderer.

    Attributes:
        direction: Overall diagram layout direction. Set to `None` to omit the
            D2 direction directive.
        layout: D2 layout engine used by image export backends.
        theme: Optional D2 theme ID.
        title_near: Optional D2 `near` placement for generated title nodes.
            Set to `None` to preserve the title without forcing placement.
        sequence_diagram: Whether DynamicDiagram output should be emitted as a
            D2 sequence diagram.
        auto_number_relationships: Whether relationship labels should be
            prefixed with their render order.
        include_type_label: Whether element type labels appear in Markdown
            labels.
        include_technology: Whether element technology appears in labels.
        include_properties: Whether element properties are emitted.
        bidirectional_relationships: How bidirectional relationships are
            rendered. ``"two_edges"`` preserves the existing behavior;
            ``"single_edge"`` emits one D2 ``<->`` edge.
        fully_qualified_relationships: Whether relationship endpoints always
            use fully qualified D2 paths.
        legend: Optional structured D2 legend.
    """

    direction: D2Direction | None = "right"
    layout: D2Layout = "dagre"
    theme: int | None = None
    title_near: D2NearPosition | None = "top-center"
    sequence_diagram: bool = False
    auto_number_relationships: bool = False
    include_type_label: bool = True
    include_technology: bool = True
    include_properties: bool = False
    bidirectional_relationships: D2BidirectionalRelationshipStrategy = (
        "two_edges"
    )
    fully_qualified_relationships: bool = True
    legend: D2Legend | None = None

    def __post_init__(self) -> None:
        """Validate render option values."""
        if self.direction is not None and self.direction not in _D2_DIRECTIONS:
            directions = ", ".join(
                repr(direction) for direction in _D2_DIRECTIONS
            )
            raise ValueError(
                f"D2 direction must be one of {directions}, or None. "
                f"Got {self.direction!r}."
            )

        if self.layout not in _D2_LAYOUTS:
            layouts = ", ".join(repr(layout) for layout in _D2_LAYOUTS)
            raise ValueError(
                f"D2 layout must be one of {layouts}. Got {self.layout!r}."
            )

        if self.theme is not None:
            if isinstance(self.theme, bool) or not isinstance(self.theme, int):
                raise TypeError(
                    "D2 theme must be None or a non-negative integer theme ID. "
                    f"Got {self.theme!r}."
                )

            if self.theme < 0:
                raise ValueError(
                    "D2 theme must be None or a non-negative integer theme ID. "
                    f"Got {self.theme!r}."
                )

        if (
            self.title_near is not None
            and self.title_near not in _D2_NEAR_POSITIONS
        ):
            positions = ", ".join(
                repr(position) for position in _D2_NEAR_POSITIONS
            )
            raise ValueError(
                f"D2 title near position must be one of {positions}, or None. "
                f"Got {self.title_near!r}."
            )

        if (
            self.bidirectional_relationships
            not in _D2_BIDIRECTIONAL_RELATIONSHIP_STRATEGIES
        ):
            strategies = ", ".join(
                repr(strategy)
                for strategy in _D2_BIDIRECTIONAL_RELATIONSHIP_STRATEGIES
            )
            raise ValueError(
                "D2 bidirectional relationship strategy must be one of "
                f"{strategies}. Got {self.bidirectional_relationships!r}."
            )

        _validate_legend(self.legend)

@dataclass(frozen=True)
class D2Legend:
    """Structured D2 legend render options."""

    label: str = "Legend"
    items: list[D2LegendElement | D2LegendRel] = field(default_factory=list)

@dataclass(frozen=True)
class D2LegendElement:
    """A D2 legend node sample."""

    label: str
    alias: str | None = None
    shape: str | None = None
    style: StyleExtensions | dict[str, D2StyleValue] | None = None
    icon: str | None = None
    classes: list[str] | None = None

@dataclass(frozen=True)
class D2LegendRel:
    """A D2 legend relationship sample."""

    label: str
    alias: str | None = None
    source: str | None = None
    target: str | None = None
    bidirectional: bool = False
    style: StyleExtensions | dict[str, D2StyleValue] | None = None
    classes: list[str] | None = None
    hide_endpoints: bool | None = None