frameplot 0.5.5__tar.gz → 0.5.6__tar.gz

{frameplot-0.5.5/src/frameplot.egg-info → frameplot-0.5.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frameplot
-Version: 0.5.5
+Version: 0.5.6
 Summary: Turn Python-defined pipeline graphs into presentation-ready SVG and PNG diagrams.
 Author: Small Turtle 2
 License-Expression: MIT
@@ -147,6 +147,12 @@ Top-level imports are the supported public API:
 - `to_png_bytes(scale=4.0) -> bytes`
 - `save_png(path, scale=4.0) -> None`
 
+## Modeling Guidance
+
+- Keep the main graph at one abstraction level. Frameplot lays the pipeline out as a dependency-driven left-to-right graph, not as a freeform block diagram.
+- Use `DetailPanel` for repeated block internals or per-stage mechanics that would otherwise create long-range edges in the main graph.
+- Use `Group` to highlight nearby related nodes, not to force distant nodes to stay together. Groups are visual overlays and routing obstacles, so very wide groups can increase route detours.
+
 ## Advanced Example: Multi-cloud Data Pipeline
 
 The hero image at the top and the theme gallery above are generated from [`examples/theme_heroes.py`](https://github.com/smturtle2/frameplot/blob/main/examples/theme_heroes.py), using the shared pipeline definition in [`examples/hero_pipeline.py`](https://github.com/smturtle2/frameplot/blob/main/examples/hero_pipeline.py). Together they showcase:
@@ -161,6 +167,7 @@ The hero image at the top and the theme gallery above are generated from [`examp
 - Edge labels are not supported yet, but edge-to-edge joins can render optional `+` / `x` badges.
 - Groups stay visual overlays, and routes leaving or re-entering grouped nodes bend outside grouped areas.
 - Detail panels render as separate lower insets attached to a focus node in the main flow.
+- If a sample looks stretched or routes far outside the intended block, the graph usually mixes stage-level flow with internal logic in one plane; move the internals into a `DetailPanel`.
 
 ## Development
 

{frameplot-0.5.5 → frameplot-0.5.6}/README.md

@@ -118,6 +118,12 @@ Top-level imports are the supported public API:
 - `to_png_bytes(scale=4.0) -> bytes`
 - `save_png(path, scale=4.0) -> None`
 
+## Modeling Guidance
+
+- Keep the main graph at one abstraction level. Frameplot lays the pipeline out as a dependency-driven left-to-right graph, not as a freeform block diagram.
+- Use `DetailPanel` for repeated block internals or per-stage mechanics that would otherwise create long-range edges in the main graph.
+- Use `Group` to highlight nearby related nodes, not to force distant nodes to stay together. Groups are visual overlays and routing obstacles, so very wide groups can increase route detours.
+
 ## Advanced Example: Multi-cloud Data Pipeline
 
 The hero image at the top and the theme gallery above are generated from [`examples/theme_heroes.py`](https://github.com/smturtle2/frameplot/blob/main/examples/theme_heroes.py), using the shared pipeline definition in [`examples/hero_pipeline.py`](https://github.com/smturtle2/frameplot/blob/main/examples/hero_pipeline.py). Together they showcase:
@@ -132,6 +138,7 @@ The hero image at the top and the theme gallery above are generated from [`examp
 - Edge labels are not supported yet, but edge-to-edge joins can render optional `+` / `x` badges.
 - Groups stay visual overlays, and routes leaving or re-entering grouped nodes bend outside grouped areas.
 - Detail panels render as separate lower insets attached to a focus node in the main flow.
+- If a sample looks stretched or routes far outside the intended block, the graph usually mixes stage-level flow with internal logic in one plane; move the internals into a `DetailPanel`.
 
 ## Development
 

{frameplot-0.5.5 → frameplot-0.5.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "frameplot"
-version = "0.5.5"
+version = "0.5.6"
 description = "Turn Python-defined pipeline graphs into presentation-ready SVG and PNG diagrams."
 readme = "README.md"
 requires-python = ">=3.11"

{frameplot-0.5.5 → frameplot-0.5.6}/src/frameplot/api.py

@@ -19,8 +19,12 @@ class Pipeline:
     """Describe and render a pipeline diagram.
 
     The constructor accepts any iterable of nodes, edges, and groups, then
-    normalizes them to tuples for deterministic rendering. Passing `theme=None`
-    uses the default :class:`Theme`.
+    normalizes them to tuples for deterministic rendering. The main graph uses
+    dependency-driven left-to-right auto-layout, so it works best when kept to
+    one abstraction level. If stage flow and internal mechanics are mixed into
+    the same graph, ranks can stretch and routes can become unexpectedly long;
+    move those internals into a :class:`DetailPanel` instead. Passing
+    `theme=None` uses the default :class:`Theme`.
     """
 
     nodes: tuple[Node, ...]

{frameplot-0.5.5 → frameplot-0.5.6}/src/frameplot/layout/text.py

@@ -64,14 +64,20 @@ def measure_text(validated: ValidatedPipeline) -> dict[str, MeasuredText]:
 def _wrap(value: str | None, width: int) -> list[str]:
     if not value:
         return []
-    wrapped = textwrap.wrap(
-        value,
-        width=width,
-        break_long_words=True,
-        break_on_hyphens=False,
-        drop_whitespace=True,
-    )
-    return wrapped or [value]
+    lines: list[str] = []
+    for explicit_line in value.splitlines() or [value]:
+        if explicit_line == "":
+            lines.append("")
+            continue
+        wrapped = textwrap.wrap(
+            explicit_line,
+            width=width,
+            break_long_words=True,
+            break_on_hyphens=False,
+            drop_whitespace=True,
+        )
+        lines.extend(wrapped or [explicit_line])
+    return lines
 
 
 def _max_line_width(lines: tuple[str, ...], font_size: float, ratio: float) -> float:

{frameplot-0.5.5 → frameplot-0.5.6}/src/frameplot/model.py

@@ -76,9 +76,10 @@ class Edge:
 class Group:
     """Highlight related nodes or edges with a labeled overlay.
 
-    Groups stay visual first, but routes leaving or re-entering grouped nodes
-    bend outside the grouped area. At least one node or edge reference is
-    required.
+    Groups stay visual first: they do not pin members together or force a
+    compact cluster. Layout still follows dependency ranks, and routes leaving
+    or re-entering grouped nodes bend outside the grouped area. At least one
+    node or edge reference is required.
     """
 
     id: str
@@ -106,8 +107,10 @@ class Group:
 class DetailPanel:
     """Expand a focus node into a lower inset with its own mini-graph.
 
-    The focus node must exist in the main pipeline graph, and the panel must
-    contain at least one node.
+    Use a detail panel when a node's internal mechanics would otherwise add
+    long-range or cross-level edges to the main graph. The focus node must
+    exist in the main pipeline graph, and the panel must contain at least one
+    node.
     """
 
     id: str

{frameplot-0.5.5 → frameplot-0.5.6}/src/frameplot/render/svg.py

@@ -51,7 +51,7 @@ def render_svg(layout: LayoutResult, theme: Theme) -> str:
     )
 
     group_layer = ET.SubElement(root, ET.QName(SVG_NS, "g"), attrib={"id": "groups"})
-    _render_groups(group_layer, layout.main, theme, metrics)
+    _render_group_shapes(group_layer, layout.main, theme, metrics)
 
     if layout.detail_panel is not None:
         guide_layer = ET.SubElement(root, ET.QName(SVG_NS, "g"), attrib={"id": "detail-panel-guides"})
@@ -62,8 +62,8 @@ def render_svg(layout: LayoutResult, theme: Theme) -> str:
             ET.QName(SVG_NS, "g"),
             attrib={"id": f"detail-panel-{layout.detail_panel.panel.id}"},
         )
-        _render_detail_panel_container(panel_layer, layout.detail_panel, theme, metrics)
-        _render_groups(panel_layer, layout.detail_panel.graph, theme, metrics)
+        _render_detail_panel_container_shape(panel_layer, layout.detail_panel, theme, metrics)
+        _render_group_shapes(panel_layer, layout.detail_panel.graph, theme, metrics)
 
     edge_layer = ET.SubElement(root, ET.QName(SVG_NS, "g"), attrib={"id": "edges"})
     _render_edges(edge_layer, layout.main.edges, marker_ids, theme, metrics)
@@ -86,6 +86,12 @@ def render_svg(layout: LayoutResult, theme: Theme) -> str:
             id_prefix=f"detail-panel-{layout.detail_panel.panel.id}-",
         )
 
+    label_layer = ET.SubElement(root, ET.QName(SVG_NS, "g"), attrib={"id": "labels"})
+    _render_group_labels(label_layer, layout.main, theme, metrics)
+    if layout.detail_panel is not None:
+        _render_detail_panel_title(label_layer, layout.detail_panel, theme, metrics)
+        _render_group_labels(label_layer, layout.detail_panel.graph, theme, metrics)
+
     return ET.tostring(root, encoding="unicode")
 
 
@@ -142,7 +148,7 @@ def _build_shadow_filter(defs: ET.Element, metrics: ResolvedThemeMetrics) -> Non
     ET.SubElement(merge, ET.QName(SVG_NS, "feMergeNode"), attrib={"in": "SourceGraphic"})
 
 
-def _render_groups(
+def _render_group_shapes(
     parent: ET.Element,
     graph: GraphLayout,
     theme: Theme,
@@ -180,18 +186,28 @@ def _render_groups(
                     "stroke-linecap": "round",
                 },
             )
-        ET.SubElement(
+
+
+def _render_group_labels(
+    parent: ET.Element,
+    graph: GraphLayout,
+    theme: Theme,
+    metrics: ResolvedThemeMetrics,
+) -> None:
+    for overlay in graph.groups:
+        _render_label_text(
             parent,
-            ET.QName(SVG_NS, "text"),
-            attrib={
-                "x": _fmt(overlay.bounds.x + theme.group_padding),
-                "y": _fmt(overlay.bounds.y + metrics.group_label_baseline_offset),
-                "fill": theme.group_label_color,
-                "font-family": theme.title_font_family,
-                "font-size": _fmt(theme.subtitle_font_size),
-                "font-weight": str(theme.title_font_weight),
-            },
-        ).text = overlay.group.label
+            text=overlay.group.label,
+            x=overlay.bounds.x + theme.group_padding,
+            baseline_y=overlay.bounds.y + metrics.group_label_baseline_offset,
+            font_family=theme.title_font_family,
+            font_size=theme.subtitle_font_size,
+            font_weight=theme.title_font_weight,
+            text_color=theme.group_label_color,
+            underpaint_color=theme.background_color,
+            underpaint_opacity=1.0,
+            underpaint_width=max(theme.stroke_width * 3.0, theme.subtitle_font_size * 0.24),
+        )
 
 
 def _render_guide_lines(parent: ET.Element, guide_lines: tuple[GuideLine, ...], theme: Theme) -> None:
@@ -209,7 +225,7 @@ def _render_guide_lines(parent: ET.Element, guide_lines: tuple[GuideLine, ...],
         )
 
 
-def _render_detail_panel_container(
+def _render_detail_panel_container_shape(
     parent: ET.Element,
     detail_panel: DetailPanelLayout,
     theme: Theme,
@@ -243,18 +259,72 @@ def _render_detail_panel_container(
         },
     )
 
+
+def _render_detail_panel_title(
+    parent: ET.Element,
+    detail_panel: DetailPanelLayout,
+    theme: Theme,
+    metrics: ResolvedThemeMetrics,
+) -> None:
+    _render_label_text(
+        parent,
+        text=detail_panel.panel.label,
+        x=detail_panel.bounds.x + theme.detail_panel_padding,
+        baseline_y=detail_panel.bounds.y + metrics.detail_panel_title_baseline_offset,
+        font_family=theme.title_font_family,
+        font_size=theme.subtitle_font_size,
+        font_weight=theme.title_font_weight,
+        text_color=theme.detail_panel_title_color,
+        underpaint_color=detail_panel.fill,
+        underpaint_opacity=1.0,
+        underpaint_width=max(theme.stroke_width * 3.0, theme.subtitle_font_size * 0.26),
+    )
+
+
+def _render_label_text(
+    parent: ET.Element,
+    *,
+    text: str,
+    x: float,
+    baseline_y: float,
+    font_family: str,
+    font_size: float,
+    font_weight: int,
+    text_color: str,
+    underpaint_color: str,
+    underpaint_opacity: float,
+    underpaint_width: float,
+) -> None:
+    ET.SubElement(
+        parent,
+        ET.QName(SVG_NS, "text"),
+        attrib={
+            "x": _fmt(x),
+            "y": _fmt(baseline_y),
+            "fill": underpaint_color,
+            "fill-opacity": _fmt(underpaint_opacity),
+            "stroke": underpaint_color,
+            "stroke-opacity": _fmt(underpaint_opacity),
+            "stroke-width": _fmt(underpaint_width),
+            "stroke-linejoin": "round",
+            "font-family": font_family,
+            "font-size": _fmt(font_size),
+            "font-weight": str(font_weight),
+        },
+    ).text = text
+
     ET.SubElement(
         parent,
         ET.QName(SVG_NS, "text"),
         attrib={
-            "x": _fmt(detail_panel.bounds.x + theme.detail_panel_padding),
-            "y": _fmt(detail_panel.bounds.y + metrics.detail_panel_title_baseline_offset),
-            "fill": theme.detail_panel_title_color,
-            "font-family": theme.title_font_family,
-            "font-size": _fmt(theme.subtitle_font_size),
-            "font-weight": str(theme.title_font_weight),
+            "x": _fmt(x),
+            "y": _fmt(baseline_y),
+            "fill": text_color,
+            "font-family": font_family,
+            "font-size": _fmt(font_size),
+            "font-weight": str(font_weight),
         },
-    ).text = detail_panel.panel.label
+    ).text = text
 
 
 def _render_edges(

{frameplot-0.5.5 → frameplot-0.5.6/src/frameplot.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frameplot
-Version: 0.5.5
+Version: 0.5.6
 Summary: Turn Python-defined pipeline graphs into presentation-ready SVG and PNG diagrams.
 Author: Small Turtle 2
 License-Expression: MIT
@@ -147,6 +147,12 @@ Top-level imports are the supported public API:
 - `to_png_bytes(scale=4.0) -> bytes`
 - `save_png(path, scale=4.0) -> None`
 
+## Modeling Guidance
+
+- Keep the main graph at one abstraction level. Frameplot lays the pipeline out as a dependency-driven left-to-right graph, not as a freeform block diagram.
+- Use `DetailPanel` for repeated block internals or per-stage mechanics that would otherwise create long-range edges in the main graph.
+- Use `Group` to highlight nearby related nodes, not to force distant nodes to stay together. Groups are visual overlays and routing obstacles, so very wide groups can increase route detours.
+
 ## Advanced Example: Multi-cloud Data Pipeline
 
 The hero image at the top and the theme gallery above are generated from [`examples/theme_heroes.py`](https://github.com/smturtle2/frameplot/blob/main/examples/theme_heroes.py), using the shared pipeline definition in [`examples/hero_pipeline.py`](https://github.com/smturtle2/frameplot/blob/main/examples/hero_pipeline.py). Together they showcase:
@@ -161,6 +167,7 @@ The hero image at the top and the theme gallery above are generated from [`examp
 - Edge labels are not supported yet, but edge-to-edge joins can render optional `+` / `x` badges.
 - Groups stay visual overlays, and routes leaving or re-entering grouped nodes bend outside grouped areas.
 - Detail panels render as separate lower insets attached to a focus node in the main flow.
+- If a sample looks stretched or routes far outside the intended block, the graph usually mixes stage-level flow with internal logic in one plane; move the internals into a `DetailPanel`.
 
 ## Development
 

{frameplot-0.5.5 → frameplot-0.5.6}/tests/test_rendering.py

@@ -1384,6 +1384,30 @@ def test_text_measurement_and_render_share_resolved_baselines() -> None:
     assert float(texts[1].attrib["y"]) == pytest.approx(expected_subtitle_y)
 
 
+def test_text_measurement_preserves_explicit_newlines() -> None:
+    pipeline = Pipeline(
+        nodes=[Node("focus", "Primary Title", "First subtitle line\nSecond subtitle line")],
+        edges=[],
+    )
+
+    layout = build_layout(pipeline)
+    layout_node = layout.main.nodes["focus"]
+    node_group = ET.fromstring(pipeline.to_svg()).find(".//svg:g[@id='focus']", SVG_NS)
+
+    assert node_group is not None
+    texts = node_group.findall("svg:text", SVG_NS)
+
+    assert layout_node.subtitle_lines == ("First subtitle line", "Second subtitle line")
+    assert [text.text for text in texts] == [
+        "Primary Title",
+        "First subtitle line",
+        "Second subtitle line",
+    ]
+    assert float(texts[2].attrib["y"]) - float(texts[1].attrib["y"]) == pytest.approx(
+        layout_node.subtitle_line_height
+    )
+
+
 def test_detail_panel_renders_as_separate_block_with_guides() -> None:
     pipeline = Pipeline(
         nodes=[
@@ -1417,6 +1441,50 @@ def test_detail_panel_renders_as_separate_block_with_guides() -> None:
     assert svg.count('marker-end="url(#arrow-') == 4
 
 
+def test_group_and_detail_panel_labels_render_after_nodes() -> None:
+    theme = Theme.dark()
+    pipeline = Pipeline(
+        nodes=[
+            Node("source", "Source"),
+            Node("focus", "Focus"),
+        ],
+        edges=[Edge("e1", "source", "focus")],
+        groups=[Group("g1", "Shared Stage", ("source", "focus"))],
+        detail_panel=DetailPanel(
+            "detail",
+            "focus",
+            "Expanded Focus",
+            nodes=(Node("inner", "Inner"),),
+            edges=(),
+        ),
+        theme=theme,
+    )
+
+    root = ET.fromstring(pipeline.to_svg())
+    layer_ids = [child.attrib.get("id") for child in root if child.tag == f"{{{SVG_NS['svg']}}}g"]
+    labels = root.find(".//svg:g[@id='labels']", SVG_NS)
+
+    assert labels is not None
+    label_rects = labels.findall("svg:rect", SVG_NS)
+    label_texts = labels.findall("svg:text", SVG_NS)
+    shared_stage = [text for text in label_texts if text.text == "Shared Stage"]
+    expanded_focus = [text for text in label_texts if text.text == "Expanded Focus"]
+
+    assert not label_rects
+    assert len(shared_stage) == 2
+    assert len(expanded_focus) == 2
+    assert shared_stage[0].attrib["stroke"] == theme.background_color
+    assert shared_stage[0].attrib["fill"] == theme.background_color
+    assert shared_stage[1].attrib["fill"] == theme.group_label_color
+    assert "stroke" not in shared_stage[1].attrib
+    assert expanded_focus[0].attrib["stroke"] == theme.detail_panel_fill
+    assert expanded_focus[0].attrib["fill"] == theme.detail_panel_fill
+    assert expanded_focus[1].attrib["fill"] == theme.detail_panel_title_color
+    assert "stroke" not in expanded_focus[1].attrib
+    assert layer_ids.index("nodes") < layer_ids.index("labels")
+    assert layer_ids.index("edge-joins") < layer_ids.index("labels")
+
+
 def test_detail_panel_biases_focus_flow_to_lower_rows() -> None:
     pipeline = Pipeline(
         nodes=[