termrender 4.4.0__tar.gz → 4.6.0__tar.gz

{termrender-4.4.0 → termrender-4.6.0}/CHANGELOG.md

@@ -1,6 +1,59 @@
 # CHANGELOG
 
 
+## v4.6.0 (2026-07-06)
+
+### Features
+
+- Add flowchart node shapes, subgraph frames, and direction rendering
+  ([`e872199`](https://github.com/crouton-labs/termrender/commit/e87219956294319feb0015d2cf4573b8cc60a0cb))
+
+Applies and hardens the salvaged decoration work for the native mermaid flowchart renderer's layout
+  engine:
+
+- Nine distinct node-shape borders (rect, round, stadium, cylinder, circle, diamond, hexagon,
+  subroutine, parallelogram), each reserving its full bounding box so the router treats every shape
+  as impassable. - Subgraph enclosure frames (left-anchored title, nested, flatten when members
+  aren't placed contiguously enough for a clean rect). - TB/BT/LR/RL direction handling via a
+  post-layout coordinate transform.
+
+Fixes found while hardening: - draw_frame now reserves the title text cells (not the whole border)
+  so a cross-boundary edge crossing a frame's top border can no longer clobber a letter of the
+  subgraph title. - Subgraph frame sizing is now computed bottom-up (_build_subgraph_frames): a
+  parent subgraph's extent is built from its children's *padded frame rects* (when they get a frame)
+  rather than raw member extents, so a nested subgraph whose members share the same column/row span
+  as its parent no longer produces an identically-sized frame that overwrites the parent's border —
+  nesting now always has real margin. - Corrected the module docstring's stale "every node renders
+  as a plain rectangle, frames not yet wired" description to match the shipped shape/frame drawers.
+
+Adds tests/test_mermaid_flow_shapes.py: real-geometry assertions for shape distinctness, a 9-shape
+  gallery, subgraph frame containment, nested-frame non-overlap, non-contiguous-subgraph flatten,
+  LR/RL/BT topology + arrowhead direction, LR same-rank spacing, and router avoidance of a diamond's
+  interior. Full suite: 437 passed (422 existing + 15 new), no regressions.
+
+
+## v4.5.0 (2026-07-06)
+
+### Features
+
+- Add flowchart edge router and public render_flowchart
+  ([`a1b46cf`](https://github.com/crouton-labs/termrender/commit/a1b46cf11607ec6b31ea8fe1b4d90b11aafff10f))
+
+- Replace the placeholder edge drawing in mermaid_flow_layout.py with the full orthogonal router:
+  rank-relative endpoint anchors (forward/same-rank/ back-edge), L/Z staircase paths for forward
+  edges, growing side-lane C-paths for back-edges so they never overlay forward edges, arrowheads
+  chosen from final-segment direction, edge labels centered on the longest straight run (shifting
+  off reserved cells), and self-loops modeled on the sequence renderer's self-message loop. - Add
+  mermaid_flow.py exposing the public, pure, never-raising render_flowchart(source, width) ->
+  list[str], wiring parse -> layout_flowgraph -> lines behind the three-case degradation contract
+  (no header, zero nodes, unexpected layout exception -> raw echo). - Add
+  tests/test_mermaid_flow.py: real end-to-end geometry/topology assertions, including the labeled
+  back-edge cycle that panics the Go binary, multi-parent attachment, headless edges, and echo
+  degradation.
+
+Unwired: nothing imports mermaid_flow yet (later phase's cutover).
+
+
 ## v4.4.0 (2026-07-06)
 
 ### Features

{termrender-4.4.0 → termrender-4.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: termrender
-Version: 4.4.0
+Version: 4.6.0
 Summary: Rich terminal rendering of directive-flavored markdown
 Project-URL: Homepage, https://github.com/CaptainCrouton89/termrender
 Project-URL: Repository, https://github.com/CaptainCrouton89/termrender

termrender-4.6.0/src/termrender/renderers/mermaid_flow.py

@@ -0,0 +1,110 @@
+"""Public entry point for the native mermaid flowchart/graph renderer.
+
+Standalone module: exposes a single pure function, :func:`render_flowchart`.
+Not yet wired into ``mermaid.py``'s dispatcher (a later, orchestrator-owned
+phase) — nothing in this package imports it. This module is a thin
+orchestrator over the parser and layout engine; it owns none of the grammar
+or layout logic itself, only header sniffing and the degradation contract.
+
+Layout model
+------------
+``render_flowchart`` is ``parse -> layout_flowgraph -> lines``, wrapped in a
+degradation guard (see *Degradation contract* below). :func:`~termrender.
+renderers.mermaid_flow_parser.parse` turns mermaid source into a
+:class:`~termrender.renderers.mermaid_flow_model.FlowGraph`;
+:func:`~termrender.renderers.mermaid_flow_layout.layout_flowgraph` lays it
+out with ``grandalf`` (pure-Python Sugiyama) and rasterizes it — bordered
+rectangle nodes, an orthogonal edge router (L/Z paths for forward edges,
+growing side lanes for back-edges/cycles, arrowheads, edge labels,
+self-loops) — onto a char grid. See ``mermaid_flow_parser.py`` and
+``mermaid_flow_layout.py``'s module docstrings for the full grammar and
+routing model; this module covers only the public contract.
+
+Grammar supported
+------------------
+Header: ``graph``/``flowchart`` + direction (``TD``/``TB``/``LR``/``RL``/
+``BT``). Node shapes: ``[rect]``, ``(round)``, ``([stadium])``,
+``[(cylinder)]``, ``((circle))``, ``{diamond}``, ``{{hexagon}}``,
+``[[subroutine]]``, ``[/parallelogram/]`` — this phase renders every shape
+as a plain rectangle (distinct shape borders are a later phase; only the
+label text is load-bearing here). Edges: ``-->``, ``---``, ``-.->``, ``==>``
+(and bidirectional forms), with ``|label|`` and inline ``A -- text --> B``
+labels, and ``&`` fan-out. ``subgraph ... end`` blocks parse but are not yet
+rendered as frames (nodes inside them still place and render normally).
+``class``/``classDef``/``style``/``click``/``linkStyle`` lines are ignored.
+
+Known degradations (by design, not bugs)
+-----------------------------------------
+- Node shapes other than a plain rectangle border are not yet visually
+  distinct (Phase 4 of this renderer's build).
+- Subgraph blocks parse but are not yet drawn as enclosing frames (Phase 4).
+- See ``mermaid_flow_layout.py``'s module docstring for the edge-routing
+  degradations (dense-graph crossings, label-lane overlap, CJK wrapping,
+  minimum-box-size self-loop cosmetics).
+- ``width`` is advisory only: like the other native renderers in this
+  package, this renderer sizes to content and may overflow a narrow
+  terminal rather than truncate the diagram.
+"""
+
+from __future__ import annotations
+
+from termrender.renderers.mermaid_flow_layout import layout_flowgraph
+from termrender.renderers.mermaid_flow_parser import FlowchartError, parse
+
+__all__ = ["render_flowchart"]
+
+
+def render_flowchart(source: str, width: int) -> list[str]:
+    """Render a mermaid ``graph``/``flowchart`` source to unicode lines.
+
+    Pure and total: never raises. Degrades to a raw echo of ``source``
+    (each line ``\\n``-split and ``.rstrip()``-ed, containing no
+    box-drawing glyphs) exactly when:
+
+    1. The source isn't a flowchart at all (no ``graph``/``flowchart``
+       header on its first non-blank, post-prelude line) — :func:`parse`
+       raises :class:`FlowchartError`.
+    2. Parsing succeeds but yields zero nodes (an empty or comment-only
+       diagram body) — nothing to draw.
+    3. Any unexpected exception escapes :func:`layout_flowgraph` — a
+       defensive catch-all; this should never happen for well-typed input,
+       but the guarantee is "never crash, degrade" regardless.
+
+    Otherwise, returns the rendered diagram: guaranteed to contain unicode
+    box-drawing glyphs (every node is a bordered box), never ANSI escapes.
+    The distinction matters downstream — code that detects render success
+    by the *presence* of box-drawing glyphs relies on the echo path never
+    emitting any.
+
+    Args:
+        source: The mermaid fence body (with or without the surrounding
+            fence markers — only the text between them).
+        width: Advisory terminal width. See the module docstring's
+            "Known degradations" for why this is advisory rather than a
+            hard wrap.
+
+    Returns:
+        Rendered lines on success, or a raw-echo of ``source`` on any of
+        the three degradation conditions above.
+    """
+    try:
+        graph = parse(source)
+    except FlowchartError:
+        return _raw_echo(source)
+
+    if not graph.nodes:
+        return _raw_echo(source)
+
+    try:
+        lines = layout_flowgraph(graph, width)
+    except Exception:
+        return _raw_echo(source)
+
+    if not lines:
+        return _raw_echo(source)
+
+    return lines
+
+
+def _raw_echo(source: str) -> list[str]:
+    return [line.rstrip() for line in source.splitlines()]