tesserax 0.5.1__tar.gz → 0.5.2__tar.gz

{tesserax-0.5.1 → tesserax-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tesserax
-Version: 0.5.1
+Version: 0.5.2
 Summary: A pure-Python library for rendering professional CS graphics.
 Author-email: Alejandro Piad <apiad@apiad.net>
 License-File: LICENSE

{tesserax-0.5.1 → tesserax-0.5.2}/docs/core.qmd

@@ -53,9 +53,28 @@ canvas.fit(padding=10).display()
 
 ```
 
+## Grouping and Aligning Shapes
+
+The `Group` class acts a container that has control over its children positions, so you can align and layout shapes easily with a procedural API.
+
+```{python}
+from tesserax import Canvas, Rect, Circle, Square, Group
+
+with Canvas() as canvas:
+    with Group() as g:
+        Rect(100, 50, fill="lightblue")
+        Circle(30, fill="salmon")
+        Square(40, fill="pink")
+
+    g.align("vertical", "center").distribute("horizontal", gap=10)
+
+canvas.fit(padding=10).display()
+
+```
+
 ## Simplifying with Layouts
 
-Manually calculating offsets (like the `150, 25` above) becomes tedious in complex diagrams. **Layouts** automate this positioning. The `Row` layout arranges its children horizontally with an optional `gap`.
+Manually calculating offsets or calling procedural alignment becomes tedious in complex diagrams. **Layouts** automate this positioning. The `Row` layout arranges its children horizontally with an optional `gap`. The `Column` does so vertically.
 
 ```{python}
 from tesserax import Canvas, Rect, Circle
@@ -63,9 +82,10 @@ from tesserax.layout import Row
 
 with Canvas() as canvas:
     # Row is also a context manager
-    with Row(gap=20):
+    with Row(gap=10):
         Rect(100, 50, fill="lightblue")
         Circle(30, fill="salmon")
+        Square(40, fill="pink")
 
 canvas.fit(padding=10).display()
 
@@ -128,7 +148,7 @@ with Canvas() as canvas:
     # Even though c1 is inside a rotated row, c1.anchor("right")
     # returns the correct global coordinate for the arrow.
     Arrow(
-        c1.anchor("top").dy(5),
+        c1.anchor("top").dy(-5),
         target.anchor("left").dx(-5),
         stroke="grey",
         width=2,

{tesserax-0.5.1 → tesserax-0.5.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tesserax"
-version = "0.5.1"
+version = "0.5.2"
 description = "A pure-Python library for rendering professional CS graphics."
 readme = "README.md"
 authors = [

{tesserax-0.5.1 → tesserax-0.5.2}/src/tesserax/__init__.py

@@ -13,4 +13,4 @@ from .base import (
     Text,
 )
 
-__version__ = "0.5.1"
+__version__ = "0.5.2"

{tesserax-0.5.1 → tesserax-0.5.2}/src/tesserax/base.py

@@ -194,6 +194,69 @@ class Group(Shape):
 
         return self
 
+    def distribute(
+        self,
+        axis: Literal["horizontal", "vertical"],
+        size: float | None = None,
+        mode: Literal["tight", "space-between", "space-around"] = "tight",
+        gap: float = 0.0,
+    ) -> Self:
+        """
+        Distributes children along an axis using rigid or flexible spacing.
+        """
+        if not self.shapes:
+            return self
+
+        # 1. Reset and Measure
+        for s in self.shapes:
+            if isinstance(s, Spring):
+                s._size = 0.0
+
+        springs = [s for s in self.shapes if isinstance(s, Spring)]
+        total_flex = sum(s.flex for s in springs)
+        n = len(self.shapes)
+
+        # 2. Calculate Spacing Logic
+        is_horiz = axis == "horizontal"
+        rigid_total = sum(
+            s.local().width if is_horiz else s.local().height
+            for s in self.shapes
+            if not isinstance(s, Spring)
+        )
+
+        effective_gap = gap
+        start_offset = 0.0
+        spring_unit = 0.0
+
+        if size is not None:
+            if springs:
+                # Springs take all space not occupied by rigid shapes and fixed gaps
+                remaining = size - rigid_total - (gap * (n - 1))
+                spring_unit = max(0, remaining / total_flex) if total_flex > 0 else 0
+            elif mode == "space-between" and n > 1:
+                effective_gap = (size - rigid_total) / (n - 1)
+            elif mode == "space-around":
+                effective_gap = (size - rigid_total) / n
+                start_offset = effective_gap / 2
+
+        # 3. Apply Translations
+        cursor = start_offset
+        for s in self.shapes:
+            b = s.local()
+
+            if isinstance(s, Spring):
+                s._size = s.flex * spring_unit
+                cursor += s._size
+            else:
+                if is_horiz:
+                    s.transform.tx = cursor - b.x
+                    cursor += b.width + effective_gap
+                else:
+                    s.transform.ty = cursor - b.y
+                    cursor += b.height + effective_gap
+
+        return self
+
 
 class Path(Shape):
     """
@@ -457,3 +520,54 @@ class Text(Shape):
             f'fill="{self.fill}" text-anchor="{self._anchor}" dominant-baseline="middle">'
             f"{self.content}</text>"
         )
+
+
+class Spacer(Shape):
+    """
+    An invisible rectangular shape used to reserve fixed space in layouts.
+    """
+
+    def __init__(self, w: float, h: float) -> None:
+        super().__init__()
+        self.w, self.h = w, h
+
+    def local(self) -> Bounds:
+        return Bounds(0, 0, self.w, self.h)
+
+    def _render(self) -> str:
+        return ""
+
+
+class Ghost(Shape):
+    """
+    A shape that proxies the bounds of a target shape without rendering.
+    """
+
+    def __init__(self, target: Shape) -> None:
+        super().__init__()
+        self.target = target
+
+    def local(self) -> Bounds:
+        """Returns the current local bounds of the target shape."""
+        return self.target.local()
+
+    def _render(self) -> str:
+        return ""
+
+
+class Spring(Shape):
+    """
+    A flexible spacer that expands to fill available space in layouts.
+    """
+
+    def __init__(self, flex: float = 1.0) -> None:
+        super().__init__()
+        self.flex = flex
+        self._size: float = 0.0
+
+    def local(self) -> Bounds:
+        # Returns a 0-width/height bound unless size is set by distribute()
+        return Bounds(0, 0, self._size, self._size)
+
+    def _render(self) -> str:
+        return ""

{tesserax-0.5.1 → tesserax-0.5.2}/src/tesserax/layout.py

@@ -2,7 +2,7 @@ from abc import abstractmethod
 from collections import defaultdict
 import math
 from typing import Literal, Self
-from .core import Shape, Bounds
+from .core import Anchor, Shape, Bounds
 from .base import Group
 
 
@@ -32,81 +32,60 @@ class Row(Layout):
         self,
         shapes: list[Shape] | None = None,
         align: Align = "middle",
-        gap: float = 0,
+        gap: float = 0.0,
+        width: float | None = None,
+        mode: Literal["tight", "space-between", "space-around"] = "tight",
     ) -> None:
-        self.align = align
+        self.align_mode = align
         self.gap = gap
+        self.width = width
+        self.mode = mode
         super().__init__(shapes)
 
     def do_layout(self) -> None:
-        if not self.shapes:
-            return
-
-        # 1. First pass: Reset transforms so we get pure local bounds
-        for s in self.shapes:
-            s.transform.reset()
+        # Map Row's 'align' terminology to the Group's 'anchor' terminology
+        anchor_map: dict[Align, Anchor] = {
+            "start": "top",
+            "middle": "center",
+            "end": "bottom",
+        }
 
-        # 2. Calculate offsets based on the 'clean' shapes
-        max_h = max(s.local().height for s in self.shapes)
-        current_x = 0.0
+        # 1. Distribute along the flow axis (X)
+        self.distribute(
+            axis="horizontal", size=self.width, mode=self.mode, gap=self.gap
+        )
 
-        for shape in self.shapes:
-            b = shape.local()
+        # 2. Align along the cross axis (Y)
+        self.align(axis="vertical", anchor=anchor_map[self.align_mode])
 
-            # Calculate Y based on baseline
-            match self.align:
-                case "start":
-                    dy = -b.y
-                case "middle":
-                    dy = (max_h / 2) - (b.y + b.height / 2)
-                case "end":
-                    dy = max_h - (b.y + b.height)
-                case _:
-                    dy = 0
 
-            # 3. Apply the strict layout position
-            shape.transform.tx = current_x - b.x
-            shape.transform.ty = dy
-
-            current_x += b.width + self.gap
-
-
-class Column(Row):
+class Column(Layout):
     def __init__(
         self,
         shapes: list[Shape] | None = None,
         align: Align = "middle",
-        gap: float = 0,
+        gap: float = 0.0,
+        height: float | None = None,
+        mode: Literal["tight", "space-between", "space-around"] = "tight",
     ) -> None:
-        super().__init__(shapes, align, gap)
+        self.align_mode = align
+        self.gap = gap
+        self.height = height
+        self.mode = mode
+        super().__init__(shapes)
 
     def do_layout(self) -> None:
-        if not self.shapes:
-            return
-
-        for s in self.shapes:
-            s.transform.reset()
-
-        max_w = max(s.local().width for s in self.shapes)
-        current_y = 0.0
-
-        for shape in self.shapes:
-            b = shape.local()
-
-            match self.align:
-                case "start":
-                    dx = -b.x
-                case "end":
-                    dx = max_w - (b.x + b.width)
-                case "middle":
-                    dx = (max_w / 2) - (b.x + b.width / 2)
-                case _:
-                    dx = 0
+        anchor_map: dict[Align, Anchor] = {
+            "start": "left",
+            "middle": "center",
+            "end": "right",
+        }
 
-            shape.transform.tx = dx
-            shape.transform.ty = current_y - b.y
+        # 1. Distribute along the flow axis (Y)
+        self.distribute(axis="vertical", size=self.height, mode=self.mode, gap=self.gap)
 
-            current_y += b.height + self.gap
+        # 2. Align along the cross axis (X)
+        self.align(axis="horizontal", anchor=anchor_map[self.align_mode])
 
 
 class ForceLayout(Layout):

{tesserax-0.5.1 → tesserax-0.5.2}/uv.lock

@@ -1790,7 +1790,7 @@ wheels = [
 
 [[package]]
 name = "tesserax"
-version = "0.5.1"
+version = "0.5.2"
 source = { editable = "." }
 
 [package.dev-dependencies]

tesserax-0.5.1/examples/basic.py

@@ -1,14 +0,0 @@
-from tesserax import Canvas, Rect, Arrow, Circle
-from tesserax.layout import Row
-
-# Initialize a canvas for an array visualization
-with Canvas() as canvas:
-    # Create two objects in a row layout
-    with Row(gap=50):
-        circle = Circle(20)
-        rect = Rect(40, 40)
-
-    # Create a pointer using the bounds-to-bounds logic
-    ptr = Arrow(circle.anchor("right").dx(5), rect.anchor("left").dx(-5))
-
-canvas.fit(10).save("quicksort_partition.svg")