facet layout

docs/Changelog.md

@@ -1,7 +1,8 @@
 # Changelog
 
-## 0.7.5
+## 0.7.5 (2025-01-29)
 * UI [configuration](Configuration.md)
+* experimental [Facet._layout](Facet.md#layout)
 
 ## 0.7.4 (2025-01-27)
 * Python 3.13 compatible

docs/Facet.md

@@ -1,2 +1,35 @@
 # Facet
-::: mininterface.facet.Facet
+::: mininterface.facet.Facet
+
+## Layout
+
+!!! Experimental
+    Share your thoughs about how the layout method should work!
+
+Should you need represent more information, Facet has a hidden method `_layout` that you may call with a list of `LayoutElements`:
+
+* `str`
+* `pathlib.Path`
+* `facet.Image`
+
+```python
+from dataclasses import dataclass
+from pathlib import Path
+from mininterface import run
+from mininterface.facet import Image
+
+@dataclass
+class Env:
+    my_str: str = "Hello"
+
+m = run(Env)
+# Image object has currently single 'src' attribute
+m.facet._layout(["My text", Image("dog1.jpg"), Path("dog1.jpg")])
+m.form()
+```
+
+As you see, the program displays "My text", then the image and than the path info.
+![Layout GUI](asset/layout-gui.avif)
+
+Even in the TUI, the images are visible. (And mouse-zoomable.)
+![Layout TUI](asset/layout-tui.avif)

mininterface/facet.py

@@ -19,11 +19,14 @@
 
 @dataclass
 class Image:
-    """ NOTE. Experimental. Undocumented. """
+    """ NOTE. Experimental. """
+
     src: str | Path
+    """ Src to the image. """
 
 
 LayoutElement = TypeVar("LayoutElement", str, Image, Path, "Self")
+""" Either a string, Path or facet.Image. """
 
 
 class BackendAdaptor(ABC):
@@ -102,7 +105,7 @@ def set_title(self, text):
         print("Title", text)
 
     def _layout(self, elements: list[LayoutElement]):
-        """ Experimental. """
+        """ Experimental. Input is a list of `LayoutElements`."""
         # NOTE remove warn when working in textual
         warn("Facet layout not implemented for this interface.")
 
@@ -120,6 +123,7 @@ def callback(tag: Tag):
             "My choice": Tag(choices=["one", "two"], on_change=callback)
         })
         # continue here immediately after clicking on a radio button
+        ```
 
         """
         self.adaptor.post_submit_action = _post_submit